# Phase 8: Screenshot Profiles - Context

**Gathered:** 2026-04-13
**Status:** Ready for planning

<domain>
## Phase Boundary

Per-project named screenshot profiles that store capture target parameters. Agents define a capture area once and reference it by name in future `start_capture` calls. New MCP tools: `save_screenshot_profile`, `list_screenshot_profiles`, `delete_screenshot_profile`. Profiles persisted to a project-local JSON file.

</domain>

<decisions>
## Implementation Decisions

### Profile Storage
- **D-01:** Profiles are stored in a single JSON file at a project-local path. The file path is configurable via an environment variable `SCREEN_TIMELAPSE_PROFILES_PATH`, defaulting to `.screen-timelapse/profiles.json` relative to CWD. This lets agents working in different project directories maintain separate profile sets.
- **D-02:** The JSON file stores both screenshot profiles and timing profiles (Phase 9) in separate top-level keys: `{ "screenshot": { ... }, "timing": { ... } }`. Single file keeps things simple and avoids coordinating multiple config files.
- **D-03:** Saving a profile with an existing name overwrites silently. Agents don't need confirmation dialogs — they know what they're doing. The previous version is not preserved.

### Profile Contents
- **D-04:** A screenshot profile stores: `name` (string, the key), `target` (desktop/window/region/window_region), `window_title` (optional, for window re-discovery), `window_handle` (optional, for direct targeting — may go stale), `x`, `y`, `width`, `height` (optional, for region coordinates), `description` (optional, human-readable note about what this captures), `created_at` (ISO timestamp), `updated_at` (ISO timestamp).
- **D-05:** Window profiles store `window_title` as the primary identifier. `window_handle` is stored as a hint but profiles resolve by title at capture time since handles are ephemeral. If the window title matches multiple windows, the first match is used (consistent with existing `findWindow` behavior).
- **D-06:** Profile names are case-insensitive, trimmed, and must be non-empty. Slugified internally for storage key (lowercase, hyphens). Display name preserved in a `display_name` field.

### Tool Interface Design
- **D-07:** Three new MCP tools:
  - `save_screenshot_profile` — upsert a named profile. Required: `name`, `target`. Optional: all target-specific fields, `description`. Returns the saved profile object.
  - `list_screenshot_profiles` — list all saved profiles. No required params. Returns array of profile objects with name, target type, description, and timestamps.
  - `delete_screenshot_profile` — delete by name. Required: `name`. Returns success/not-found status.
- **D-08:** `save_screenshot_profile` accepts the same target parameters as `start_capture` (target, window_title, window_handle, x, y, width, height, region_x, region_y, region_width, region_height). This means an agent can copy-paste parameters between tools without translation.
- **D-09:** Validation: `save_screenshot_profile` validates that required fields for the target type are present (e.g., window target needs window_title or window_handle, region needs x/y/width/height). Returns a structured error if validation fails.

### Profile Resolution (start_capture integration)
- **D-10:** `start_capture` gains an optional `screenshot_profile` parameter (string). When provided, the tool loads the named profile and uses its target parameters. Any inline parameters override the profile (merge semantics — profile is the base, inline params are patches).
- **D-11:** If both `screenshot_profile` and explicit target params are provided, the explicit params win. This lets agents say "use my sidebar profile but override the region width."
- **D-12:** If the named profile doesn't exist, `start_capture` returns a structured error immediately (no capture attempted). The error includes the list of available profile names to help the agent self-correct.

### Additional Agent-Power Features
- **D-13:** `save_screenshot_profile` supports a `capture_from_current` mode: if `source_session` is provided (a session ID from a completed capture), the profile is auto-populated from that session's config. This lets agents say "save what I just captured as a profile" without re-specifying parameters.
- **D-14:** `list_screenshot_profiles` includes a `test` field per profile indicating whether the target is currently available (window exists, region is on-screen). This is a quick liveness check — not a capture, just a target validation pass.

### Claude's Discretion
- Internal file format details (JSON structure, indentation)
- Error message wording
- Whether to create the profiles directory automatically on first save
- Profile field ordering in list output

</decisions>

<canonical_refs>
## Canonical References

**Downstream agents MUST read these before planning or implementing.**

No external specs — requirements fully captured in decisions above.

### Codebase References
- `src/types.ts` — `CaptureConfig` interface defines all target parameters to mirror in profiles
- `src/server.ts` — Existing `registerTool` pattern for adding new MCP tools; `start_capture` tool definition to extend with `screenshot_profile` param
- `src/capture/targets/window-utils.ts` — `findWindow` function used for window title resolution
- `src/capture/targets/capture-target.ts` — `CaptureTarget` interface for target validation patterns

</canonical_refs>

<code_context>
## Existing Code Insights

### Reusable Assets
- `CaptureConfig` in `types.ts`: Already defines all target parameters (target type, windowHandle, windowTitle, region coordinates). Profile storage mirrors this structure.
- `findWindow()` in `window-utils.ts`: Window title matching logic reusable for profile liveness checks.
- `server.ts` tool registration pattern: Consistent pattern for adding new tools with zod schemas.

### Established Patterns
- **Zod schemas for tool input**: All existing tools use zod for input validation. New profile tools follow the same pattern.
- **SessionManager singleton**: Module-level singleton pattern. Profile storage can follow the same pattern (ProfileManager singleton).
- **Snake_case tool params**: MCP tool interface uses snake_case (e.g., `interval_ms`, `window_handle`). Profile tools must match.

### Integration Points
- `start_capture` tool in `server.ts` (~line 38): Needs `screenshot_profile` optional param added to schema
- `CaptureConfig` type: Profile resolution happens before config is passed to SessionManager
- Profile file I/O: New module, no existing file persistence pattern in codebase (sessions are in-memory only)

</code_context>

<specifics>
## Specific Ideas

- **User directive for Phase 11:** Frame subset selection must support three query modes: start+end time (relative to capture start), start time+length, and frame index+count. This is noted here for cross-phase awareness but belongs in Phase 11 scope.
- **User directive for all v1.2 phases:** Full creative discretion granted — Claude should ideate, decide, and introduce features that maximize tool power and flexibility for agent consumers.

</specifics>

<deferred>
## Deferred Ideas

- **Profile import/export**: Sharing profiles between projects via JSON import/export. Useful but not needed for core functionality.
- **Profile groups/tags**: Organizing profiles into categories. Over-engineering for the current scope — flat list with good names suffices.

</deferred>

---

*Phase: 08-screenshot-profiles*
*Context gathered: 2026-04-13*