Harden CineScreen: crash/data-loss fixes, correctness, perf, tests, CI

One squashed commit covering a full-repo hardening pass.

Recording safety
- Stop hotkey is ⌥⎋, not bare ESC (a global unmodified-ESC monitor
  silently ended recordings whenever ESC was pressed in the recorded app).
- Stream death mid-recording (display disconnect, permission revoked) is
  surfaced: the session salvages captured frames via the normal stop path
  and the HUD swaps to a failure notice instead of counting over a dead
  stream.
- Quit guard stops-and-saves before terminating; automatic termination is
  disabled (the OS could reclaim the app mid-recording while its windows
  were hidden). ⌘N is disabled while a session is active.
- Cancelled/failed recordings no longer leave permanent "Incomplete"
  tiles; a metadata-write failure no longer deletes the captured video.

Data safety
- Project delete moves to the Trash behind a confirmation, and only
  folders with CineScreen artifacts are listed (pointing the library at a
  general directory used to make arbitrary folders one misclick from
  permanent deletion).
- Editor edits autosave (debounced) and flush on window close — the Save
  button was the only write path and closing the window lost everything.

Export
- Failure-safe export session: resume-once teardown (double-resumed
  continuations crashed the app on e.g. disk-full), shared stop flags (a
  dead video loop hung the audio loop forever), temp file + atomic
  promote (failures destroyed existing files and left broken partials),
  Cancel button, and decoder failures fail loudly instead of
  freeze-framing a "successful" export. Ordered progress stream.
- Webcam overlay is time-aligned: the camera warm-up offset
  (webcamFirstPTS − screenFirstPTS, both host-clock) is persisted as
  metadata.webcamOffsetMs and applied in editor playback and export.

Capture correctness
- Cursor coordinates are correct for window/region/secondary-display
  capture: mapping is (global − contentRect.origin) × px/pt against the
  captured content's rect, not full-display bounds; the seed sample
  converts Cocoa→CG via the primary screen.
- The Low/Medium/High quality picker actually applies its bitrate;
  duration derives from the last video frame's PTS instead of a wall
  clock that included startup latency; frame counter race fixed.

Editor correctness + perf
- Adaptive cursor smoothing: speed + lag urgency, mouse-down-only click
  window (binary-searched), validated by offline replay (click lag
  21-149px → 0.3-1.9px; hover settle 467ms → 150ms).
- RenderSnapshot cached on the VM (it was rebuilt 3× per frame including
  240Hz pan-track integration — preview stutter scaled with zoom
  coverage); invalidation centralised in metadata.didSet.
- Zoom sections can no longer overlap, cross, or collapse; persisted
  order is repaired on load; pan table sorted defensively.
- Preview canvas locks to the export aspect (webcam placement, padding,
  and shadow used to silently diverge from the exported file).
- Cancel-safe gestures via @GestureState; pinch zoom no longer compounds
  exponentially; webcam drag/resize inverts the exact forward mapping.

Foundations
- New CineScreenTests target (19 tests over smoothing, snapshot policy,
  metadata codec, zoom generation, projects library) + make test.
- CI builds and tests every push to main (previously PR-only, so main
  was never verified). Releases gate on tag == MARKETING_VERSION,
  Sparkle is pinned to exactly 2.6.4, release concurrency serialised,
  broken workflow_dispatch removed, artifacts named -universal.
- Dead code removed (legacy window-picker plumbing and its UI,
  SimplePlayerView, fossil scripts, write-only fields); control-bar
  frame-rate/quality settings persist; README inaccuracies and committed
  tool-call residue fixed; Info.plist pseudo-keys dropped.
- .claude/skills/ added: dev-loop, debug-recording, pitfalls, release.

Author: jasonzh0

.claude/skills/debug-recording/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: debug-recording
+description: Debug CineScreen capture, cursor, playback, and export issues — logs, recording artifacts on disk, the ffmpeg frame-extraction validation method, and the offline smoother-replay harness. Use when investigating "cursor is off", A/V desync, export problems, or any recording misbehaviour.
+---
+
+# Debugging recordings
+
+## Logs
+
+Everything logs through `os.Logger` via `Log.*` (CineScreen/Util/Logger.swift):
+subsystems `capture`, `session`, `mouse`, `editor`, `app`. Stream live:
+
+```bash
+log stream --predicate 'subsystem == "com.cinescreen.app"' --level debug
+```
+
+(Adjust the subsystem string to what Logger.swift declares — check it first.)
+
+## Recording artifacts on disk
+
+Projects live at `~/Documents/CineScreen/Recording YYYY-MM-DD HH-mm-ss/`:
+
+- `recording.mp4` — the capture (H.264, PTS rebased to start at 0)
+- `recording.json` — sidecar metadata: cursor keyframes + clicks in
+  **video-pixel space, top-left origin**; zoom sections; trim; canvas;
+  `webcamOffsetMs` (screenT = webcamT + offset)
+- `webcam.mp4` — optional webcam track (its t=0 lags the screen's by
+  `webcamOffsetMs` — camera warm-up)
+- `project.json` — descriptor (this file is what makes a folder count as a
+  project in the library)
+
+Inspect metadata quickly:
+
+```bash
+python3 -c "import json;m=json.load(open('recording.json'));print(m['video'],len(m['cursor']['keyframes']),'kf',len(m['clicks']),'clicks')"
+```
+
+## "Cursor position is off" — validation method (proven)
+
+The rendered cursor is a **synthetic sprite** (the capture hides the real
+one, `showsCursor=false`), positioned from `recording.json` + spring
+smoothing. Two distinct root causes exist; identify which before fixing:
+
+1. **Smoothing lag** (display recordings): raw coordinates are correct; the
+   sprite trails because of `SmoothPosition2D` glide. Validate: extract the
+   frame at a click timestamp and check the raw (x,y) lands on the clicked
+   UI element —
+
+   ```bash
+   ffmpeg -ss <t_seconds> -i recording.mp4 -frames:v 1 click.png
+   ```
+
+   then overlay a crosshair at the click's (x,y) from recording.json.
+2. **Capture geometry** (window/region/secondary-display recordings): the
+   mapping is `(globalPoint − contentRectPoints.origin) × pixelsPerPoint`
+   (MouseTrackingService). If raw coordinates themselves miss the target,
+   the geometry (CaptureInfo.contentRectPoints) is wrong for that mode.
+
+## Offline smoother replay (no GUI needed)
+
+To evaluate smoothing changes numerically, write a standalone Swift script
+that mirrors `Spring.swift` + the relevant `RenderSnapshot` math, replays
+`recording.json` at a 60fps grid, and reports sprite↔raw lag at mouse-downs
+plus settle time after moves. This pattern validated the adaptive-smoothing
+work (click lag 21–149px → 0.3–1.9px). Keep the script out of the repo
+(/tmp) — the real math lives in unit tests (Tests/CineScreenTests).
+
+## Preview vs export divergence
+
+Preview (`MetalRenderer`) and export (`ExportCompositor`) share Shaders.metal
+and `RenderSnapshot`, but have **duplicated pipeline setup and uniform struct
+definitions** ("must match" comments). If a visual effect differs between
+preview and exported file, diff those two files first — and remember the
+preview canvas is aspect-locked to the video (EditorView) precisely so
+canvas-relative placement matches the export.

.claude/skills/dev-loop/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: dev-loop
+description: Build, test, and iterate on CineScreen — XcodeGen workflow, make targets, stale-module fixes, and verification discipline. Use when building, running, or testing this repo, or when the build fails mysteriously.
+---
+
+# CineScreen development loop
+
+## Project generation — edit project.yml, never the pbxproj
+
+`CineScreen.xcodeproj` is **gitignored and generated**. Adding files, targets,
+settings, or SPM packages happens in `project.yml`, then:
+
+```bash
+make project     # xcodegen generate
+```
+
+New Swift files under `CineScreen/` or `Tests/CineScreenTests/` are picked up
+by the source globs automatically — but the xcodeproj must be regenerated to
+see them.
+
+## Build / test / run
+
+```bash
+make build       # Debug build (the type-check gate — run before claiming any change works)
+make test        # unit tests (CineScreenTests, app-hosted, ~20s incremental)
+make open        # open in Xcode
+```
+
+Verification discipline: a change is not done until `make build` (or
+`make test` when logic changed) passes. There is no standalone type-checker —
+the build IS the check.
+
+## Known failure modes
+
+- **SourceKit/IDE diagnostics say "Cannot find type X in scope" everywhere**
+  for types that clearly exist (CTheme, RecordingMetadata, Log, …): false
+  positives when the xcodeproj hasn't been generated or is stale. Ignore
+  them; trust `make build`. Run `make project` to quiet the IDE.
+- **"file has been modified since the module file was built"** (usually a
+  Sparkle header): stale precompiled modules after a dependency version
+  change. Fix: `rm -rf build/derived` and rebuild.
+- **Sparkle is pinned to exactly 2.6.4** in project.yml. Don't float it —
+  Package.resolved lives inside the gitignored xcodeproj and can't pin
+  anything, and CI pins the 2.6.4 appcast CLI tools to match.
+
+## CI
+
+`.github/workflows/build.yml` builds + tests every PR **and every push to
+main** (unsigned Debug). Releases run `release.yml` on `v*.*.*` tags only —
+see the `release` skill.

.claude/skills/pitfalls/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: pitfalls
+description: CineScreen's sharp edges and invariants — metadata invalidation, zoom-section rules, coordinate spaces, PTS rebasing, AVFoundation callback traps, SwiftUI gesture state, autosave suppression. Read before modifying capture, editor, or export code.
+---
+
+# Common pitfalls & invariants
+
+## Editor state
+
+- **`EditorViewModel.metadata.didSet` is the single invalidation choke
+  point**: it clears `cachedSnapshot` + `cachedZoomSections` and schedules
+  the debounced autosave. Mutate metadata *through the property* (value-type
+  write-back does this automatically, e.g. `metadata?.zoom.sections = …`).
+  Never cache derived render state anywhere else.
+- **`suppressAutosave` must wrap any code that loads state INTO the VM**
+  (loadMetadata, derived defaults) — otherwise merely opening a recording
+  rewrites its sidecar.
+- **Trim lives twice** (vm.trimStartMs/EndMs ↔ metadata.trim) and is synced
+  by the trim didSets. Don't add a third copy.
+- **Zoom sections invariant: sorted by startTime, non-overlapping, ≥100ms.**
+  `updateZoomSection` enforces it by clamping to neighbours (which is also
+  why no mid-drag re-sort is needed — a drag can't cross a neighbour).
+  `RenderSnapshot.init` sorts defensively; the pan table is binary-searched
+  by time and breaks on non-monotonic input.
+- **Drag gesture baselines must be `@GestureState`, not `@State`** — SwiftUI
+  never calls `onEnded` for a *cancelled* gesture, and stale `@State` wedged
+  scrubbing/drags before. Same for pinch: `MagnifyGesture.magnification` is
+  cumulative from gesture start; scale a gesture-start baseline or it
+  compounds exponentially.
+
+## Coordinate spaces (four of them — never mix)
+
+1. **CGEvent global points**: top-left origin of the primary display. This is
+   what the mouse tap yields. (NSEvent.mouseLocation is bottom-left Cocoa —
+   convert once using the *primary* screen, not NSScreen.main.)
+2. **Recorded-file pixels**: top-left; metadata keyframes/clicks live here.
+   Mapping: `(global − CaptureInfo.contentRectPoints.origin) × px/pt`.
+3. **UV [0,1]²** in shaders (video space), then **NDC** with y-up; canvas
+   passes multiply `aspectScale` then `canvas.contentScale` — every overlay
+   pass (video, cursor, clicks) must apply both or it drifts under padding.
+4. **Webcam layout norms** are relative to the *padded content rect*:
+   on-screen px = norm × contentScale × viewSize. Invert exactly.
+
+## Timing
+
+- All capture PTS are **rebased so the file starts at 0** (first screen
+  frame is the base; mic + system audio rebase against it and drop
+  negative-PTS samples).
+- **Webcam**: screenT = webcamT + `metadata.webcamOffsetMs` (camera warm-up).
+  Editor seeks and export reads must apply the mapping; playback defers the
+  webcam start inside the warm-up gap.
+- Recorded duration comes from the **last video frame's rebased PTS**, not
+  wall clock (wall clock includes ~0.3–1s of startup latency).
+
+## AVFoundation traps
+
+- `requestMediaDataWhenReady` blocks are **re-invoked after failures** (a
+  failed writer forces `isReadyForMoreMediaData=true` so you can poll the
+  error). Any continuation resumed from such a block needs a resume-once
+  guard + `markAsFinished()` — see ExportPipeline's `finish(_:)` pattern.
+  Double-resume = runtime trap.
+- With multiple writer inputs, the writer **interleaves**: a stalled/failed
+  input blocks the others forever. Mark the failed input finished so
+  siblings' callbacks fire and can exit (shared `ExportSessionState`).
+- `alwaysCopiesSampleData = true` on reader outputs feeding
+  CVMetalTextureCache is load-bearing: cached textures pin decoder pool
+  buffers; without copies the decoder stalls (~2s in, export "freezes").
+- Export writes to a hidden temp file and promotes atomically on success —
+  never write directly to the user's chosen path.
+
+## Capture
+
+- `ScreenCaptureService.stop()` tolerates an already-dead stream — stream
+  death mid-recording routes through `onRuntimeFailure` → RecordingSession
+  salvages via the normal stop path.
+- The stop hotkey is **⌥⎋ exactly** (caps-lock tolerated). Never rebind to
+  unmodified ESC (it silently ended recordings from the recorded app) and
+  never match ⌘⌥⎋ (Force Quit).
+- After granting Screen Recording, macOS requires an **app relaunch** before
+  `CGPreflightScreenCaptureAccess()` returns true — a permission that "won't
+  turn green" in-process is expected, not a bug.
+- `_CGSCurrentCursorSeed` is private SPI (cursor-shape detection). It can
+  vanish in an OS update; if cursor-shape code crashes at launch, look here.
+
+## Process & release
+
+- Each improvement = its own commit, pushed (user preference).
+- `NSSupportsAutomaticTermination` must stay **false** — a recorder with all
+  regular windows hidden must not be reclaimable mid-capture.
+- CFBundleVersion = `git rev-list --count HEAD` (Sparkle monotonicity).
+  History rewrites that reduce the commit count below the last release's
+  would break auto-update — check before squashing/rebasing main.
+- The release tag must equal project.yml's MARKETING_VERSION (CI preflight
+  enforces it).

.claude/skills/release/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: release
+description: Cut a CineScreen release — version bump, tag, CI pipeline, Sparkle appcast, and the invariants that keep auto-update working. Use when releasing a new version or debugging the release/update pipeline.
+---
+
+# Cutting a release
+
+## The happy path
+
+1. Bump `MARKETING_VERSION` in **project.yml** (nowhere else).
+2. Commit and push to main; wait for CI green.
+3. Tag and push — the tag must match the version exactly:
+
+   ```bash
+   git tag v2.6.0 && git push origin v2.6.0
+   ```
+
+4. `release.yml` takes over: preflight asserts tag == MARKETING_VERSION,
+   then the reusable build workflow signs with Developer ID (secrets),
+   notarizes the app ZIP + DMG, staples, EdDSA-signs the ZIP, generates
+   `appcast.xml`, publishes a GitHub Release, and deploys the appcast to
+   `gh-pages`. Existing users auto-update via Sparkle.
+
+## Invariants — break these and auto-update breaks
+
+- **Tag == MARKETING_VERSION.** CI preflight fails the release otherwise.
+  Without it, Sparkle would still push mismatched assets to every user,
+  because…
+- **CFBundleVersion = `git rev-list --count HEAD`** (set by
+  scripts/make_release.sh). It must increase every release. Never rewrite
+  main's history in a way that drops the commit count below the previous
+  release's count.
+- **Sparkle framework is pinned to exactly 2.6.4** in project.yml, matching
+  the `SPARKLE_VERSION` CLI tools pinned in build-workflow.yml. Bump both
+  together.
+- **`SUPublicEDKey` in Info.plist is the real production key.** Updates are
+  signature-verified against it; the matching private key is the
+  `SPARKLE_PRIVATE_KEY` repo secret.
+- In-place updates preserve TCC grants (Screen Recording/Accessibility)
+  because the app is replaced at its existing path with the same signing
+  identity — don't change the bundle id or signing identity casually.
+
+## Artifacts
+
+`CineScreen-<version>-universal.{dmg,zip}` — the archive is universal
+(ARCHS_STANDARD, ONLY_ACTIVE_ARCH=NO). The ZIP is what the appcast
+enclosures point at; the DMG is the human download.
+
+## Local / debugging
+
+- `bash scripts/make_release.sh` is the real pipeline (the Makefile's
+  archive/export/dmg targets are a simplified local approximation).
+- `--archive-only` stops after archiving.
+- Notarization credentials: `xcrun notarytool store-credentials
+  cinescreen-notary …` (see README).
+- There is deliberately **no workflow_dispatch** on release.yml — running it
+  from a branch baked broken enclosure URLs into the appcast. Tag pushes
+  only.

.github/workflows/build-workflow.yml

@@ -70,7 +70,7 @@ jobs:
           sed -i '' 's/objectVersion = 77;/objectVersion = 70;/' CineScreen.xcodeproj/project.pbxproj
           grep -m1 "objectVersion" CineScreen.xcodeproj/project.pbxproj
 
-      - name: Build (Debug, no signing)
+      - name: Build & test (Debug, no signing)
         if: '!inputs.release'
         run: |
           set -o pipefail
@@ -83,7 +83,7 @@ jobs:
             -destination 'platform=macOS' \
             CODE_SIGN_IDENTITY="-" \
             CODE_SIGNING_REQUIRED=NO \
-            build | tee build/build.log
+            build test | tee build/build.log
 
       # ----- Code signing setup (release only) ------------------------------
       - name: Import signing certificate

.github/workflows/build.yml

@@ -1,7 +1,11 @@
 name: CI
 
+# PRs and pushes to main both build + test. Commits land directly on main in
+# this repo, so a PR-only trigger left main permanently unverified.
 on:
   pull_request:
+  push:
+    branches: [main]
 
 jobs:
   build:

.github/workflows/release.yml

@@ -1,16 +1,41 @@
 name: Release
 
+# Tag-push only. workflow_dispatch was removed deliberately: run from a
+# branch, github.ref_name is the branch name, which baked broken enclosure
+# URLs into the appcast and broke the release step's tag lookup.
 on:
   push:
     tags:
       - 'v*.*.*'
-  workflow_dispatch:
 
 permissions:
   contents: write
 
+# One release at a time — concurrent tag pushes raced each other publishing
+# to gh-pages.
+concurrency:
+  group: release
+  cancel-in-progress: false
+
 jobs:
+  preflight:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Assert tag matches MARKETING_VERSION
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          VERSION="$(grep -E '^\s*MARKETING_VERSION:' project.yml | head -1 | sed 's/.*"\(.*\)".*/\1/')"
+          if [ "$TAG" != "$VERSION" ]; then
+            echo "Tag v$TAG does not match project.yml MARKETING_VERSION=$VERSION." >&2
+            echo "Bump MARKETING_VERSION and commit before tagging — Sparkle's" >&2
+            echo "CFBundleVersion is the commit count, so a mismatched tag would" >&2
+            echo "still auto-update every user to wrongly-versioned assets." >&2
+            exit 1
+          fi
+
   build:
+    needs: preflight
     uses: ./.github/workflows/build-workflow.yml
     with:
       upload-artifacts: true

CineScreen/App/AppState.swift

@@ -24,9 +24,6 @@ final class AppState {
     var captureCamera: Bool = false
     /// AVCaptureDevice uniqueID for the selected webcam. nil = system default.
     var selectedCameraID: String? = nil
-    /// `nil` = capture the entire display. Otherwise the chosen on-screen window.
-    var selectedWindowID: CGWindowID? = nil
-    var availableWindows: [CaptureWindow] = []
 
     // Permissions snapshot (refreshed on a timer and after each request)
     var permissions: PermissionStatus
@@ -124,16 +121,6 @@ final class AppState {
         permissions = Permissions.currentStatus()
     }
 
-    // MARK: - Windows
-
-    func refreshAvailableWindows() async {
-        do {
-            availableWindows = try await ScreenCaptureService.availableWindows()
-        } catch {
-            Log.app.error("Failed to enumerate windows: \(error.localizedDescription)")
-        }
-    }
-
     // MARK: - Projects
 
     func refreshProjects() {
@@ -142,7 +129,7 @@ final class AppState {
 
     /// Creates a new project in the configured library and selects it as the
     /// recording target. The video will be written to
-    /// `<projectFolder>/recording.mov`.
+    /// `<projectFolder>/recording.mp4`.
     func beginNewProject() -> Project? {
         do {
             let project = try ProjectsLibrary.createNew(in: projectsDirectory)