v2

.claude/skills/screenize-explorer/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: screenize-explorer
+description: Explore and debug .screenize project packages. Lists projects, reads project.json, summarizes event streams, displays timeline segments, and shows recording statistics.
+user-invocable: true
+allowed-tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+
+<role>
+You are a Screenize project data inspector. You help developers explore and debug .screenize package contents by reading JSON files and presenting structured summaries. You understand the Screenize data model including project metadata, event streams, timeline tracks, and render settings.
+</role>
+
+<context>
+Screenize is a macOS screen recording app. Projects are stored as `.screenize` packages (macOS directory bundles that appear as single files in Finder).
+
+### Package Structure
+
+```
+MyProject.screenize/
+├── project.json               # ScreenizeProject v5
+└── recording/
+    ├── recording.mp4          # Video file
+    ├── metadata.json          # PolyRecordingMetadata
+    ├── mousemoves-0.json      # [PolyMouseMoveEvent]
+    ├── mouseclicks-0.json     # [PolyMouseClickEvent]
+    ├── keystrokes-0.json      # [PolyKeystrokeEvent]
+    └── uistates-0.json        # [PolyUIStateEvent]
+```
+
+### project.json Schema (v5)
+
+Top-level fields:
+- `id` (UUID), `version` (int), `name`, `createdAt`, `modifiedAt` (ISO 8601)
+- `media`: `{ videoPath, mouseDataPath, pixelSize: {width, height}, frameRate, duration }`
+- `captureMeta`: `{ displayID?, boundsPt: {x,y,width,height}, scaleFactor }`
+- `timeline`: `{ tracks: [{type, data}], duration, trimStart, trimEnd? }`
+- `renderSettings`: codec, quality, resolution, background, corners, shadow, padding, motionBlur
+- `interop`: `{ sourceKind, eventBundleVersion, recordingMetadataPath, streams: {mouseMoves, mouseClicks, keystrokes, uiStates}, primaryVideoPath }`
+- `frameAnalysisCache` (optional array), `frameAnalysisVersion`
+
+### Timeline Track Types
+
+Each track is wrapped as `{ type: "transform"|"cursor"|"keystroke", data: {...} }`:
+
+**Camera track** (type: "transform"): segments with `startTime`, `endTime`, `startTransform: {zoom, center: {x, y}}`, `endTransform`, `interpolation`, `mode` ("manual"/"followCursor"), `cursorFollow`, `transitionToNext`
+
+**Cursor track** (type: "cursor"): `useSmoothCursor`, segments with `startTime`, `endTime`, `style`, `visible`, `scale`, `clickFeedback`, `transitionToNext`
+
+**Keystroke track** (type: "keystroke"): segments with `startTime`, `endTime`, `displayText`, `position`, `fadeInDuration`, `fadeOutDuration`
+
+### Event Stream Formats
+
+**metadata.json**: `{ formatVersion, recorderName, recorderVersion, createdAt, processTimeStartMs, processTimeEndMs, unixTimeStartMs, display: { widthPx, heightPx, scaleFactor } }`
+
+**mousemoves-0.json**: Array of `{ type, processTimeMs, unixTimeMs, x, y, cursorId?, activeModifiers, button? }`. Coordinates: display-local pixels, top-left origin.
+
+**mouseclicks-0.json**: Array of `{ type: "mouseDown"|"mouseUp", processTimeMs, unixTimeMs, x, y, button: "left"|"right", cursorId?, activeModifiers }`.
+
+**keystrokes-0.json**: Array of `{ type: "keyDown"|"keyUp", processTimeMs, unixTimeMs, character?, isARepeat, activeModifiers }`.
+
+**uistates-0.json**: Array of `{ processTimeMs, unixTimeMs, cursorX, cursorY, elementRole?, elementSubrole?, elementTitle?, elementAppName?, elementFrameX/Y/W/H?, elementIsClickable?, caretX/Y/W/H? }`.
+
+### Computing Timeline Seconds
+
+`timelineSec = (event.processTimeMs - metadata.processTimeStartMs) / 1000.0`
+</context>
+
+<workflow>
+When invoked, follow these steps. All output must be in English.
+
+## Step 1: Find Project
+
+If the user provides a specific `.screenize` path as an argument, use it directly.
+
+Otherwise, search for projects in these locations (in order):
+1. `./projects/` relative to the current working directory
+2. `~/Movies/Screenize/`
+
+Use Glob to find `.screenize` packages:
+```
+pattern: projects/**/*.screenize
+```
+
+If multiple projects are found, list them with names and ask the user which one to inspect. If only one is found, use it automatically. If none are found, inform the user.
+
+## Step 2: Package Overview
+
+Read `project.json` from the package root. Present:
+
+```
+### Project: [name]
+- **Version**: [version] | **ID**: [id]
+- **Created**: [date] | **Modified**: [date]
+- **Video**: [width]x[height] @ [fps] fps, [MM:SS duration]
+- **Capture**: Display [id], [w]x[h] pt, scale [factor]x
+- **Export**: [codec] / [quality] / [resolution]
+- **Background**: [enabled/disabled]
+- **Trim**: [start] - [end] (or "None")
+```
+
+## Step 3: Timeline Summary
+
+For each track in the timeline:
+
+### Camera Track ([N] segments)
+Table with columns: `#`, `Time Range`, `Start Zoom`, `End Zoom`, `Center`, `Mode`, `Easing`
+
+### Cursor Track ([N] segments, smooth: [yes/no])
+Table with columns: `#`, `Time Range`, `Style`, `Visible`, `Scale`
+
+### Keystroke Track ([N] segments)
+Table with columns: `#`, `Time Range`, `Text`
+
+## Step 4: Event Stream Statistics
+
+Read `recording/metadata.json` first for processTimeStartMs.
+
+For each event stream file that exists, read it (use Bash `wc -l` for very large files, or Read for moderate ones) and report:
+
+### Recording Metadata
+- Recorder: [name] v[version]
+- Display: [w]x[h] px @ [scale]x
+- Duration: [computed] sec
+- Created: [date]
+
+### Mouse Moves
+- Total: [count] events
+- Time range: [first] - [last] sec
+- Avg frequency: [count/duration] Hz
+
+### Mouse Clicks
+- Total: [count] ([downs] mouseDown, [ups] mouseUp)
+- Left: [count] | Right: [count]
+
+### Keystrokes
+- Total: [count] ([downs] keyDown, [ups] keyUp)
+- Characters: [first 20 unique non-nil characters]
+
+### UI States
+- Total: [count] samples
+- Unique apps: [list]
+- Unique roles: [list]
+
+## Step 5: Deep Dive (Optional)
+
+After showing the summary, ask the user if they want to:
+1. View raw JSON of a specific file
+2. Inspect events in a specific time range (e.g., "show clicks between 5.0-10.0 sec")
+3. See detailed camera segment transitions with easing curves
+4. List all UI element interactions in chronological order
+
+Only proceed if the user requests one of these.
+</workflow>
+
+<constraints>
+- All output in English.
+- Format durations as MM:SS.mmm for precise values, MM:SS for summaries.
+- Format coordinates to 3 decimal places.
+- For large event files (>10000 events), show count only. For detail, show first 5 and last 5 with "..." between.
+- Mark missing files as "[missing]" rather than erroring.
+- Never modify any package files. This skill is read-only.
+- Use the Read tool for JSON files, not cat via Bash.
+- When reading JSON, use Bash `python3 -m json.tool` only if needed for formatting, otherwise Read directly.
+</constraints>

.gitignore

@@ -63,5 +63,7 @@ xcuserdata/
 tools
 release
 private-docs
+projects/
 
 __pycache__
+.worktrees/

AGENTS.md

@@ -0,0 +1,145 @@
+# AGENTS.md
+Guidance for autonomous coding agents working in this repository.
+
+## Repository Snapshot
+- Project: **Screenize** (macOS screen recording and editing app)
+- Language: **Swift**
+- UI framework: **SwiftUI**
+- Target platform: **macOS 13+**
+- Build system: **Xcode project** (`Screenize.xcodeproj`)
+- External dependency: **Sparkle** (via Swift Package Manager)
+
+## Mandatory Agent Workflow
+Follow this sequence for each meaningful work unit:
+1. **START**: run the `work-context-finder` agent to check prior related work.
+2. **WORK**: implement the task.
+3. **FINISH**: execute `/log-work` using the `work-logger` skill.
+
+Notes:
+- This workflow is defined in `CLAUDE.md` and should be treated as repository policy.
+- All generated logs/summaries/tags for vector DB workflows must be in English.
+
+## Build, Lint, and Test Commands
+Run all commands from repository root (`/Users/sung-yein/Workspace/screenize`).
+
+### Build
+```bash
+xcodebuild -project Screenize.xcodeproj -scheme Screenize -configuration Debug build
+```
+
+### Lint
+```bash
+./scripts/lint.sh
+```
+Auto-fix lint violations where possible:
+```bash
+./scripts/lint.sh --fix
+```
+
+### Tests (Current Status + How To Run)
+Current repository status:
+- There is currently **no test target** configured in `Screenize.xcodeproj`.
+- There are currently **no `*Tests*` files/directories** in the repo.
+- Primary verification today is **successful build + lint**.
+
+When tests are added, use these command patterns:
+
+Run all tests for a scheme:
+```bash
+xcodebuild -project Screenize.xcodeproj -scheme Screenize -destination 'platform=macOS' test
+```
+
+Run a single test class:
+```bash
+xcodebuild -project Screenize.xcodeproj -scheme Screenize -destination 'platform=macOS' -only-testing:ScreenizeTests/MyFeatureTests test
+```
+
+Run a single test method:
+```bash
+xcodebuild -project Screenize.xcodeproj -scheme Screenize -destination 'platform=macOS' -only-testing:ScreenizeTests/MyFeatureTests/testExample test
+```
+
+Tip: if scheme/target names differ, inspect with:
+```bash
+xcodebuild -list -project Screenize.xcodeproj
+```
+
+### Permission Reset Helpers (Local Dev)
+If screen/microphone permission state is broken:
+```bash
+tccutil reset ScreenCapture com.screenize.Screenize
+tccutil reset Microphone com.screenize.Screenize
+```
+
+## Code Style and Conventions
+
+### Language and Documentation
+- Write **all code, comments, commit messages, and docs in English**.
+- Keep comments focused on non-obvious intent or constraints.
+
+### Imports
+- Use explicit imports required by each file (avoid unnecessary imports).
+- Keep import blocks clean and grouped at the file top.
+- Prefer Apple frameworks first; avoid wildcard or indirect import patterns.
+
+### Formatting and Lint Rules
+This repo uses SwiftLint (`.swiftlint.yml`) with key limits:
+- `line_length`: warning 140, error 200
+- `file_length`: warning 600, error 1000
+- `function_body_length`: warning 80, error 150
+- `type_body_length`: warning 400, error 600
+- `function_parameter_count`: warning 8, error 12
+- `nesting`: type level 2, function level 5
+- `force_cast`: warning only (required in some AXValue APIs)
+- `force_try`: error
+
+General formatting expectations:
+- Use clear `// MARK:` sectioning in larger files.
+- Keep methods small and focused.
+- Respect existing spacing and brace style already used in nearby code.
+
+### Types, Concurrency, and State
+- Prefer strong, domain-specific types over untyped dictionaries.
+- Use `@MainActor` for major app/state classes and UI-facing state.
+- Use `Sendable` and safe queue/concurrency boundaries where relevant.
+- Use async/await patterns consistently with existing code.
+- Keep singleton usage aligned with existing architecture (`AppState.shared`, `ProjectManager.shared`).
+
+### Naming Conventions
+- Use descriptive Swift names in standard Apple style.
+- Use `Manager` / `Coordinator` suffixes for orchestration components.
+- Keep keyframe/timeline terms consistent with domain model naming.
+- Use imperative, behavior-first function names for actions.
+
+### Error Handling and Logging
+- Prefer typed error propagation (`throw`) when callers can act on failures.
+- In UI/state layers, convert errors to user-visible messages when appropriate.
+- Avoid silent failure unless intentionally best-effort.
+- Keep logs concise and contextual; avoid noisy debug output in stable paths.
+
+### Architecture-Specific Rules
+- Internal coordinate standard is **NormalizedPoint** (`0...1`, bottom-left origin).
+- Convert coordinate spaces only at API boundaries using `CoordinateConverter`.
+- Keep timeline keyframes sorted by time within tracks.
+- Preserve three-phase flow: recording -> editor -> export.
+
+### File and Project System Expectations
+- Project package format is `.screenize` with `project.json` and `recording/` media.
+- Persist relative media paths in project JSON; resolve absolute URLs at load boundaries.
+
+## Git and Change Hygiene for Agents
+- Do not revert unrelated local changes in a dirty worktree.
+- Keep edits scoped to the requested task.
+- Prefer small, reviewable diffs.
+- Use imperative commit messages when committing (if requested).
+
+## Cursor / Copilot Rule Files
+Checked paths:
+- `.cursor/rules/`
+- `.cursorrules`
+- `.github/copilot-instructions.md`
+
+Current status:
+- No Cursor rules or Copilot instruction files were found in this repository.
+
+If these files are added later, update this document to mirror any required agent constraints.

CLAUDE.md

@@ -2,6 +2,65 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
+## Core Principles
+
+- **Simplicity First**: Make every change as simple as possible. Impact minimal code.
+- **No Laziness**: Find root causes. No temporary fixes. Senior developer standards.
+- **Minimal Impact**: Changes should only touch what's necessary. Avoid introducing bugs.
+
+## Workflow Orchestration
+
+### Plan Node Default
+
+- Enter plan mode for ANY non-trivial task (3+ steps or architectural decisions).
+- If something goes sideways, STOP and re-plan immediately — don't keep pushing.
+- Use plan mode for verification steps, not just building.
+- Write detailed specs upfront to reduce ambiguity.
+
+### Subagent Strategy
+
+- Use subagents liberally to keep main context window clean.
+- Offload research, exploration, and parallel analysis to subagents.
+- For complex problems, throw more compute at it via subagents.
+- One task per subagent for focused execution.
+
+### Self-Improvement Loop
+
+- After ANY correction from the user: update `tasks/lessons.md` with the pattern.
+- Write rules for yourself that prevent the same mistake.
+- Ruthlessly iterate on these lessons until mistake rate drops.
+- Review lessons at session start for relevant project.
+
+### Verification Before Done
+
+- Never mark a task complete without proving it works.
+- Diff behavior between main and your changes when relevant.
+- Ask yourself: "Would a staff engineer approve this?"
+- Run build, check logs, demonstrate correctness.
+
+### Demand Elegance (Balanced)
+
+- For non-trivial changes: pause and ask "is there a more elegant way?"
+- If a fix feels hacky: "Knowing everything I know now, implement the elegant solution."
+- Skip this for simple, obvious fixes — don't over-engineer.
+- Challenge your own work before presenting it.
+
+### Autonomous Bug Fixing
+
+- When given a bug report: just fix it. Don't ask for hand-holding.
+- Point at logs, errors, failing tests — then resolve them.
+- Zero context switching required from the user.
+- Go fix failing CI tests without being told how.
+
+## Task Management
+
+1. **Plan First**: Write plan to `tasks/todo.md` with checkable items.
+2. **Verify Plan**: Check in before starting implementation.
+3. **Track Progress**: Mark items complete as you go.
+4. **Explain Changes**: High-level summary at each step.
+5. **Document Results**: Add review section to `tasks/todo.md`.
+6. **Capture Lessons**: Update `tasks/lessons.md` after corrections.
+
 ## Language
 
 All comments, code, commit messages, and documentation must be written in English. Do not use any other language.
@@ -111,7 +170,6 @@ Screenize is a macOS screen recording application that captures screen/window co
 - `PackageManager` - Singleton managing `.screenize` package CRUD (create, save, load, path resolution)
 - `ProjectManager` - Orchestrates project lifecycle, recent projects, delegates to PackageManager
 - `ProjectCreator` - Factory creating projects from recordings or imported videos (accepts `PackageInfo`)
-- `LegacyProjectMigrator` - Auto-migrates old `.fsproj` projects to `.screenize` format (remove in next minor version)
 - `RenderSettings` - Export codec, quality, resolution settings
 
 **`.screenize` package structure:**