feat(cli): --windows — clean multi-window capture with slide transitions

Window mode captures one window cleanly, but a real demo moves between a
terminal, an editor, a browser. `record --windows "a,b,c"` captures every
matched window continuously in parallel — ScreenCaptureKit window capture,
so each feed stays clean even while occluded — plus the focus timeline.
`export --follow-windows` then composites one video that switches to
whichever window had focus, the incoming window sliding in from the side
it sat on (450 ms eased slide; direction follows screen geometry).

- Swift helper: new optional `multiWindows` request mode running N
  SCStreams + writers in one process. This is load-bearing: a second
  helper *process* interrupts the first stream (SCStreamErrorDomain
  -3805, empirically verified), while in-process streams coexist.
- Focus helper now reports the CGWindowID so focus samples bind exactly
  to captured windows.
- electron/cli/multiWindowRecorder.ts: match windows by title, drive the
  multi-capture helper + focus sampler, write a
  `<primary>.multiwindow.json` manifest (windows + focus timeline).
- src/lib/windowSwitch/: manifest contracts and a pure, unit-tested
  switch-timeline builder (1.2 s dwell, flicker collapse, unrecorded
  windows keep the current screen, geometry-based slide direction).
- src/cli/multiWindowCompositor.ts: offline lockstep decode of all
  window videos (frame channels with backpressure) → slide compositing →
  VideoEncoder/VideoMuxer intermediate, which then flows through the
  normal export pipeline (wallpaper, padding, annotations, --audio).

macOS only; audio via export --audio for now.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019ceTJjoPJYa5BdmXZdDc5J

Author: PeterTakahashi

docs/cli.md

@@ -74,7 +74,32 @@ Platform notes:
   which may show a system picker dialog and requires a desktop session
   (headless/SSH sessions without a portal cannot record).
 
-### Multi-window demos: `--follow-windows`
+### Multi-window demos: `--windows` (clean capture + slide transitions)
+
+The flagship mode for product demos. Every listed window is captured
+**continuously and cleanly in parallel** (ScreenCaptureKit window capture — no
+desktop background, no overlap, works even while occluded), together with a
+focus timeline. The export step then composites one video that *switches to
+whichever window you focused*, with the incoming window sliding in from the
+side it sat on:
+
+```bash
+openscreen record --windows "Terminal,Code,Chrome" --project demo.openscreen
+# ...work normally across the three windows...
+openscreen export demo.openscreen -o demo.mp4 --follow-windows
+```
+
+- Focus held ≥1.2 s switches the screen; brief flickers are ignored; focusing
+  an unlisted window keeps the current one on screen.
+- Transitions are 450 ms eased slides; the direction follows screen geometry
+  (a window to the right slides in from the right).
+- All windows must live in one capture process: concurrent helper *processes*
+  interrupt each other's streams (SCStreamErrorDomain -3805), so the Swift
+  helper gained a `multiWindows` mode running N streams in-process.
+- macOS only; no audio yet (add narration with `export --audio`). Composes
+  with wallpaper/padding/annotations and `--audio` like any export.
+
+### Display recording: `--follow-windows` zoom mode
 
 One window is rarely enough for a product demo — a real workflow moves between
 a terminal, an editor, a browser. `--follow-windows` records the whole display

electron/cli/args.ts

@@ -84,6 +84,9 @@ Record options (recording is saved into the app's recordings directory):
                             Write a ready-to-export project file when done
   --follow-windows          Also record which window has focus (macOS); pair with
                             "export --follow-windows" for automatic window switching
+  --windows <t1,t2,...>     Multi-window capture (macOS): record every matched window
+                            in parallel; "export --follow-windows" switches between
+                            them with slide transitions as focus changes
   --json                    NDJSON events on stdout
 
 Stopping a recording: send SIGINT/SIGTERM, type "stop" + Enter on stdin,
@@ -297,6 +300,7 @@ function parseRecord(args: string[], cwd: string): CliCommand {
 		durationMs: null,
 		projectOut: null,
 		followWindows: false,
+		windows: null,
 	};
 
 	for (let i = 0; i < args.length; i++) {
@@ -362,6 +366,21 @@ function parseRecord(args: string[], cwd: string): CliCommand {
 			case "--follow-windows":
 				request.followWindows = true;
 				break;
+			case "--windows": {
+				const [value, next] = takeValue(args, i, arg);
+				const titles = value
+					.split(",")
+					.map((title) => title.trim())
+					.filter(Boolean);
+				if (titles.length < 2) {
+					throw new Error(
+						'--windows needs at least two comma-separated titles, e.g. "Terminal,Chrome"',
+					);
+				}
+				request.windows = titles;
+				i = next;
+				break;
+			}
 			case "--json":
 				request.json = true;
 				break;

electron/cli/cliMain.ts

@@ -17,6 +17,7 @@ import { getSelectedDesktopSource, registerIpcHandlers } from "../ipc/handlers";
 import { ASSET_BASE_URL_ARG } from "../windows";
 import { CLI_USAGE, type CliCommand } from "./args";
 import { FocusSampler, isFocusSamplingAvailable, resolveRecordedDisplayId } from "./focusSampler";
+import { startMultiWindowRecording } from "./multiWindowRecorder";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const VITE_DEV_SERVER_URL = process.env["VITE_DEV_SERVER_URL"];
@@ -314,6 +315,69 @@ async function runPackCommand(projectPath: string, outDir: string, json: boolean
 	return 0;
 }
 
+async function runMultiWindowRecord(
+	command: import("../../src/lib/cliContracts").CliRecordRequest & { json?: boolean },
+	output: CliOutput,
+): Promise<void> {
+	const titles = command.windows ?? [];
+	output.info(`Starting multi-window capture (${titles.length} windows)…`);
+
+	let handle: Awaited<ReturnType<typeof startMultiWindowRecording>>;
+	try {
+		handle = await startMultiWindowRecording(titles, command.displayIndex);
+		await handle.allStarted;
+	} catch (error) {
+		output.error(error instanceof Error ? error.message : String(error));
+		app.exit(1);
+		return;
+	}
+	for (const summary of handle.windowSummaries) {
+		output.info(`Recording window: ${summary.title}`);
+	}
+	output.info("Recording started (all windows)");
+	output.event("recording-started", { windows: handle.windowSummaries.map((w) => w.title) });
+
+	let stopping = false;
+	const finish = async (reason: string) => {
+		if (stopping) return;
+		stopping = true;
+		output.info(`Stopping recording (${reason})…`);
+		output.event("stopping", { reason });
+		try {
+			const result = await handle.stop();
+			if (command.projectOut) {
+				await writeProjectFile(command.projectOut, {
+					version: 2,
+					media: { screenVideoPath: result.primaryVideoPath, cursorCaptureMode: "system" },
+					editor: {},
+				});
+			}
+			output.info(`Recorded ${result.videoPaths.length} windows → ${result.primaryVideoPath}`);
+			output.info(`Manifest → ${result.manifestPath}`);
+			if (command.projectOut) output.info(`Project → ${command.projectOut}`);
+			output.event("done", {
+				success: true,
+				screenVideoPath: result.primaryVideoPath,
+				videoPaths: result.videoPaths,
+				multiWindowManifestPath: result.manifestPath,
+				durationMs: result.durationMs,
+				focusSamples: result.focusSampleCount,
+				...(command.projectOut ? { projectPath: command.projectOut } : {}),
+			});
+			app.exit(0);
+		} catch (error) {
+			output.error(error instanceof Error ? error.message : String(error));
+			output.event("done", { success: false });
+			app.exit(1);
+		}
+	};
+
+	setupRecordStopSignals((reason) => void finish(reason));
+	if (command.durationMs) {
+		setTimeout(() => void finish(`duration ${command.durationMs}ms`), command.durationMs);
+	}
+}
+
 async function runInfoCommand(projectPath: string, json: boolean): Promise<number> {
 	const raw = await fs.readFile(projectPath, "utf8");
 	const data = JSON.parse(raw) as {
@@ -448,6 +512,11 @@ export function runCli(command: CliCommand): void {
 				return;
 			}
 
+			if (command.kind === "record" && command.windows) {
+				await runMultiWindowRecord(command, output);
+				return;
+			}
+
 			if (command.kind === "pack") {
 				const code = await runPackCommand(
 					command.projectPath,

electron/cli/focusSampler.ts

@@ -22,6 +22,7 @@ const SAMPLE_INTERVAL_MS = 200;
 interface RawHelperSample {
 	type?: string;
 	timestampMs?: number;
+	windowNumber?: number;
 	appName?: string;
 	windowTitle?: string;
 	x?: number;
@@ -155,6 +156,7 @@ export class FocusSampler {
 			}
 			samples.push({
 				timeMs: Math.max(0, raw.timestampMs - startedAt),
+				windowNumber: raw.windowNumber ?? 0,
 				appName: raw.appName ?? "",
 				windowTitle: raw.windowTitle ?? "",
 				x: raw.x ?? 0,