talktrack 0.0.0 → 0.1.1

package/dist/index.cjs

@@ -0,0 +1,678 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let node_child_process = require("node:child_process");
+let node_fs_promises = require("node:fs/promises");
+let node_os = require("node:os");
+let node_path = require("node:path");
+let _playwright_test = require("@playwright/test");
+/**
+* Uniform noise in -spread..spread, used for micro-jitter along the path.
+*/
+function jitter(spread) {
+	return (Math.random() - .5) * 2 * spread;
+}
+/**
+* Builds the human-feeling path between two points as a list of intermediate points; the caller paces them out over real wall-clock time so a screen recording actually shows the glide. The last point is always exactly `to`, regardless of jitter or overshoot.
+*/
+function buildHumanPath(from, to) {
+	const dx = to.x - from.x;
+	const dy = to.y - from.y;
+	const distance = Math.hypot(dx, dy);
+	if (distance < 2) return [to];
+	const steps = Math.max(8, Math.min(34, Math.round(distance / 14)));
+	const perpX = -dy / distance;
+	const perpY = dx / distance;
+	const bowMagnitude = Math.min(40, distance * .12) * (Math.random() < .5 ? 1 : -1);
+	const overshoot = distance > 180 && Math.random() < .6;
+	const overshootPx = overshoot ? 6 + Math.random() * 10 : 0;
+	const OVERSHOOT_WINDOW_START_T = .8;
+	const OVERSHOOT_WINDOW_END_T = .97;
+	const OVERSHOOT_WINDOW_WIDTH_T = .17;
+	const PATH_POINT_JITTER_PX = .6;
+	const path = [];
+	for (let i = 1; i <= steps; i++) {
+		const t = i / steps;
+		const eased = easeInOutCubic(t);
+		const bow = Math.sin(t * Math.PI) * bowMagnitude;
+		let px = from.x + dx * eased + perpX * bow;
+		let py = from.y + dy * eased + perpY * bow;
+		if (overshoot && t > OVERSHOOT_WINDOW_START_T && t < OVERSHOOT_WINDOW_END_T) {
+			const overshootT = (t - OVERSHOOT_WINDOW_START_T) / OVERSHOOT_WINDOW_WIDTH_T;
+			const settle = Math.sin(overshootT * Math.PI);
+			px += dx / distance * overshootPx * settle;
+			py += dy / distance * overshootPx * settle;
+		}
+		path.push({
+			x: px + jitter(PATH_POINT_JITTER_PX),
+			y: py + jitter(PATH_POINT_JITTER_PX)
+		});
+	}
+	path[path.length - 1] = to;
+	return path;
+}
+/**
+* Ease-in-out cubic, shared with naturalScrollIntoView's own identical curve: a real scroll (wheel or trackpad) accelerates away from rest and decelerates into rest, it doesn't move at constant speed.
+*/
+function easeInOutCubic(t) {
+	return t < .5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2;
+}
+//#endregion
+//#region src/timeline.ts
+const recordingStartedAt = /* @__PURE__ */ new WeakMap();
+const captionTimeline = /* @__PURE__ */ new WeakMap();
+/**
+* Called once, as early as possible (installCursor's own first line). First call wins, so a demo that navigates before installing the overlay doesn't shift t0 later than the recording's own real start.
+*/
+function markRecordingStart(page) {
+	if (!recordingStartedAt.has(page)) recordingStartedAt.set(page, Date.now());
+}
+/**
+* Appends one narration event for the page: a string shows that caption from now, null hides whatever is showing. Called by showCaption/hideCaption; direct use is only for advanced driving.
+*/
+function recordCaptionEvent(page, text) {
+	const startedAt = recordingStartedAt.get(page) ?? Date.now();
+	const events = captionTimeline.get(page) ?? [];
+	events.push({
+		atMs: Date.now() - startedAt,
+		text
+	});
+	captionTimeline.set(page, events);
+}
+/**
+* Snapshot for the framing pass. Read after the context has closed is fine: the map is keyed by the Page object itself, which outlives its browser context.
+*/
+function getRecordingTimeline(page) {
+	return {
+		startedAt: recordingStartedAt.get(page) ?? Date.now(),
+		events: captionTimeline.get(page) ?? []
+	};
+}
+//#endregion
+//#region src/cursor.ts
+const TALKTRACK_OVERLAY_INIT = () => {
+	if (document.getElementById("__talktrack_cursor__")) return;
+	const style = document.createElement("style");
+	style.textContent = `
+    #__talktrack_cursor__ {
+      position: fixed; top: 0; left: 0; width: 22px; height: 22px;
+      border-radius: 50%; background: rgba(220,38,38,0.88);
+      border: 2px solid white; box-shadow: 0 1px 5px rgba(0,0,0,0.6);
+      pointer-events: none; z-index: 2147483647; transform: translate(-50%, -50%) scale(1);
+      transition: transform 0.12s ease-out, background-color 0.12s ease-out;
+    }
+    #__talktrack_cursor__.__talktrack_pressed__ {
+      transform: translate(-50%, -50%) scale(0.55);
+      background: rgba(153,27,27,0.95);
+    }
+    .__talktrack_ripple__ {
+      position: fixed; width: 14px; height: 14px; border-radius: 50%;
+      border: 3px solid rgba(220,38,38,0.9); pointer-events: none; z-index: 2147483647;
+      transform: translate(-50%, -50%); animation: __talktrack_ripple_anim__ 0.55s ease-out forwards;
+    }
+    @keyframes __talktrack_ripple_anim__ {
+      from { width: 14px; height: 14px; opacity: 1; }
+      to { width: 58px; height: 58px; opacity: 0; }
+    }
+  `;
+	document.head.appendChild(style);
+	const cursor = document.createElement("div");
+	cursor.id = "__talktrack_cursor__";
+	document.body.appendChild(cursor);
+	window.addEventListener("mousemove", (e) => {
+		cursor.style.left = `${String(e.clientX)}px`;
+		cursor.style.top = `${String(e.clientY)}px`;
+	}, true);
+	window.__talktrackPress = (x, y) => {
+		cursor.classList.add("__talktrack_pressed__");
+		const ripple = document.createElement("div");
+		ripple.className = "__talktrack_ripple__";
+		ripple.style.left = `${String(x)}px`;
+		ripple.style.top = `${String(y)}px`;
+		document.body.appendChild(ripple);
+		setTimeout(() => {
+			ripple.remove();
+		}, 600);
+	};
+	window.__talktrackRelease = () => {
+		cursor.classList.remove("__talktrack_pressed__");
+	};
+};
+const currentPosition = /* @__PURE__ */ new WeakMap();
+async function glideTo(page, to) {
+	const path = buildHumanPath(currentPosition.get(page) ?? {
+		x: to.x,
+		y: to.y
+	}, to);
+	const MOVE_STEP_MIN_DELAY_MS = 12;
+	const MOVE_STEP_DELAY_RANGE_MS = 10;
+	for (const point of path) {
+		await page.mouse.move(point.x, point.y);
+		await page.waitForTimeout(MOVE_STEP_MIN_DELAY_MS + Math.random() * MOVE_STEP_DELAY_RANGE_MS);
+	}
+	currentPosition.set(page, to);
+}
+async function tolerateNavigationRace(promise) {
+	return promise.catch(() => void 0);
+}
+/**
+* Playwright's own locator.scrollIntoViewIfNeeded() is a synchronous DOM scrollIntoView: an instant jump-cut in a recording, not something a person watching would recognise as scrolling at all. This drives a real sequence of wheel events instead, eased and paced like glideTo's own mouse path, so a recording shows the page actually gliding to the target rather than teleporting to it. Exported (not just used internally by moveAndClick below) so a demo can bring a target into view on its own, with no click attached (for example before narrating over a tall diagram whose own heading satisfies a "content rendered" assertion long before the diagram's body, the actual thing being narrated, has scrolled into the visible viewport).
+*/
+async function naturalScrollIntoView(page, locator) {
+	const viewport = page.viewportSize();
+	if (!viewport) return;
+	const hoverPoint = {
+		x: viewport.width / 2,
+		y: viewport.height / 2
+	};
+	await tolerateNavigationRace(page.mouse.move(hoverPoint.x, hoverPoint.y));
+	const box = await tolerateNavigationRace(locator.boundingBox());
+	if (!box) return;
+	const margin = 96;
+	if (box.y >= margin && box.y + box.height <= viewport.height - margin) return;
+	const totalDelta = box.y + box.height / 2 - viewport.height / 2;
+	if (Math.abs(totalDelta) < 12) return;
+	const steps = Math.max(7, Math.min(26, Math.round(Math.abs(totalDelta) / 55)));
+	let deliveredSoFar = 0;
+	const SCROLL_STEP_MIN_DELAY_MS = 14;
+	const SCROLL_STEP_DELAY_RANGE_MS = 12;
+	for (let i = 1; i <= steps; i++) {
+		const target = totalDelta * easeInOutCubic(i / steps);
+		const stepDelta = target - deliveredSoFar;
+		deliveredSoFar = target;
+		await page.mouse.wheel(0, stepDelta);
+		await page.waitForTimeout(SCROLL_STEP_MIN_DELAY_MS + Math.random() * SCROLL_STEP_DELAY_RANGE_MS);
+	}
+	await page.waitForTimeout(140 + Math.random() * 120);
+}
+async function applyCursor(page) {
+	await tolerateNavigationRace(page.evaluate(TALKTRACK_OVERLAY_INIT));
+	const pos = currentPosition.get(page);
+	if (!pos) return;
+	await tolerateNavigationRace(page.evaluate(([x, y]) => {
+		const cursor = document.getElementById("__talktrack_cursor__");
+		if (cursor) {
+			cursor.style.left = `${String(x)}px`;
+			cursor.style.top = `${String(y)}px`;
+		}
+	}, [pos.x, pos.y]));
+	await tolerateNavigationRace(page.mouse.move(pos.x, pos.y, { steps: 1 }));
+}
+/**
+* Re-injects on every navigation (addInitScript) and once immediately for the current document, since addInitScript only applies to documents created after it's registered. Also marks the recording's own t0 (see ./timeline): every demo calls this as its very first action, which is the closest available proxy for "when the video recording actually began" without needing frame-exact precision a demo narration track doesn't need anyway.
+*/
+async function installCursor(page) {
+	markRecordingStart(page);
+	await page.addInitScript(TALKTRACK_OVERLAY_INIT);
+	await applyCursor(page);
+}
+/**
+* Use in place of page.goto() for any navigation after installCursor(): restores the cursor to its last known state on the new document instead of letting it reset, so navigating doesn't read as a visual glitch in the recording.
+*/
+async function gotoWithCursor(page, url) {
+	await page.goto(url);
+	await applyCursor(page);
+}
+/**
+* Use in place of page.reload() for any navigation after installCursor(): restores the cursor to its last known state on the new document the same way gotoWithCursor does for page.goto(). A bare page.reload() in a demo that has already called installCursor() is the one navigation path the overlay can't cover on its own: addInitScript recreates the cursor DOM element on the fresh document (so it doesn't vanish outright), but nothing repositions it, so a reload leaves the cursor visibly pinned to the corner until the next moveAndClick's glide happens to move it (confirmed live as the cause of a cursor going missing mid-recording during a demo's own periodic safety-net reloads).
+*/
+async function reloadWithCursor(page) {
+	await page.reload();
+	await applyCursor(page);
+}
+/**
+* Sets (or updates) the narration shown in the footer band below the recorded app window; see ./timeline for how this timestamped event actually becomes an on-screen banner during post-processing. Pass null (or call hideCaption) to clear it between unrelated steps rather than leaving a stale caption shown throughout the gap.
+*/
+function showCaption(page, text) {
+	recordCaptionEvent(page, text);
+}
+/**
+* Clears the narration band (closes the window the last showCaption opened). Hide between unrelated steps rather than leaving a stale caption shown throughout the gap.
+*/
+function hideCaption(page) {
+	recordCaptionEvent(page, null);
+}
+function humanPause(baseMs) {
+	return Math.round(baseMs * (.75 + Math.random() * .5));
+}
+/**
+* Moves the cursor humanly to the locator (scrolling it into view first), clicks it, and holds a jittered pause afterwards. Use in place of locator.click() in any recording.
+*/
+async function moveAndClick(page, locator, pauseMs = 250) {
+	await naturalScrollIntoView(page, locator);
+	const box = await locator.boundingBox();
+	if (!box) throw new Error("Could not resolve a bounding box for the click target");
+	const CLICK_TARGET_MIN_OFFSET_RATIO = .4;
+	const CLICK_TARGET_OFFSET_RANGE_RATIO = .2;
+	const target = {
+		x: box.x + box.width * (CLICK_TARGET_MIN_OFFSET_RATIO + Math.random() * CLICK_TARGET_OFFSET_RANGE_RATIO),
+		y: box.y + box.height * (CLICK_TARGET_MIN_OFFSET_RATIO + Math.random() * CLICK_TARGET_OFFSET_RANGE_RATIO)
+	};
+	await glideTo(page, target);
+	await page.waitForTimeout(humanPause(180));
+	await tolerateNavigationRace(page.evaluate(([px, py]) => window.__talktrackPress?.(px, py), [target.x, target.y]));
+	await locator.click();
+	await page.waitForTimeout(humanPause(100));
+	await tolerateNavigationRace(page.evaluate(() => window.__talktrackRelease?.()));
+	const CURSOR_REAPPLY_ATTEMPTS = 4;
+	const CURSOR_REAPPLY_INTERVAL_MS = 90;
+	for (let i = 0; i < CURSOR_REAPPLY_ATTEMPTS; i++) {
+		await applyCursor(page);
+		await page.waitForTimeout(CURSOR_REAPPLY_INTERVAL_MS);
+	}
+	await page.waitForTimeout(humanPause(pauseMs));
+}
+async function typeCharByChar(page, text) {
+	const CHAR_TYPE_MIN_DELAY_MS = 28;
+	const CHAR_TYPE_DELAY_RANGE_MS = 55;
+	const SPACE_PAUSE_MIN_DELAY_MS = 40;
+	const SPACE_PAUSE_DELAY_RANGE_MS = 60;
+	const THINKING_PAUSE_PROBABILITY = .04;
+	const THINKING_PAUSE_MIN_DELAY_MS = 200;
+	const THINKING_PAUSE_DELAY_RANGE_MS = 400;
+	for (const ch of text) {
+		await page.keyboard.type(ch);
+		let delay = CHAR_TYPE_MIN_DELAY_MS + Math.random() * CHAR_TYPE_DELAY_RANGE_MS;
+		if (ch === " ") delay += SPACE_PAUSE_MIN_DELAY_MS + Math.random() * SPACE_PAUSE_DELAY_RANGE_MS;
+		if (Math.random() < THINKING_PAUSE_PROBABILITY) delay += THINKING_PAUSE_MIN_DELAY_MS + Math.random() * THINKING_PAUSE_DELAY_RANGE_MS;
+		await page.waitForTimeout(delay);
+	}
+}
+/**
+* Clicks into the locator and types the text character by character at human speed, so a recording shows the value appearing as it's typed rather than arriving at once.
+*/
+async function fillVisibly(page, locator, text, pauseMs = 300) {
+	await moveAndClick(page, locator, humanPause(150));
+	await locator.fill("");
+	await typeCharByChar(page, text);
+	await page.waitForTimeout(humanPause(pauseMs));
+}
+/**
+* Exported so demos can pace their own non-interaction "reading" pauses (for example holding on a state that just changed) with the same jittered, human-feeling timing.
+*/
+function humanBeatMs(baseMs) {
+	return humanPause(baseMs);
+}
+/**
+* Waits a jittered pause of roughly `ms` milliseconds on the page, for "reading" beats between interactions.
+*/
+async function beat(page, ms = 600) {
+	await page.waitForTimeout(humanBeatMs(ms));
+}
+const NARRATE_SCENE_DEFAULT_LEAD_IN_MS = 800;
+const NARRATE_SCENE_DEFAULT_DWELL_MS = 1200;
+/**
+* Shows a caption, waits for a real page-state condition to settle while the caption stays up, holds a digest dwell, then hides it. The caption's on-screen duration is tied to genuine readiness (the `settle` promise) rather than a fixed sleep: `leadInMs` is a minimum floor running concurrently with `settle`, and `dwellMs` is the "look at this" hold after it resolves.
+*/
+async function narrateScene(page, text, settle, opts) {
+	const leadInMs = opts?.leadInMs ?? NARRATE_SCENE_DEFAULT_LEAD_IN_MS;
+	const dwellMs = opts?.dwellMs ?? NARRATE_SCENE_DEFAULT_DWELL_MS;
+	showCaption(page, text);
+	const [result] = await Promise.all([settle(), beat(page, leadInMs)]);
+	await beat(page, dwellMs);
+	hideCaption(page);
+	return result;
+}
+//#endregion
+//#region src/bands.ts
+/** The band look talktrack frames recordings with when no `bands` override is given. */
+const defaultBandStyle = {
+	headerHeightPx: 48,
+	footerHeightPx: 96,
+	background: "#111827",
+	textColor: "#f8fafc",
+	fontStack: "-apple-system, BlinkMacSystemFont, \"Segoe UI\", Roboto, sans-serif",
+	headerFontSizePx: 18,
+	footerFontSizePx: 20
+};
+/**
+* Merges a caller's partial band overrides over {@link defaultBandStyle}; an absent overrides object yields the defaults unchanged.
+*/
+function resolveBandStyle(overrides) {
+	return {
+		...defaultBandStyle,
+		...overrides
+	};
+}
+/**
+* Escapes the five characters HTML treats as markup, so arbitrary narration text can be embedded in the band page's template safely.
+*/
+function escapeHtml(text) {
+	return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+/**
+* Renders one band as a PNG. Takes a dedicated throwaway BrowserContext, not the demo's own page/context: a context recording video (recordVideo or Playwright Test's video option) records every page opened within it, so rendering the bands through the demo's own context would leave junk video files alongside the real recording. A fresh context with no video option set (off by default) avoids that entirely.
+*
+* Text is rendered as an ordinary PNG screenshot of that throwaway page rather than via ffmpeg's drawtext filter, since drawtext needs libfreetype/libfontconfig support that common ffmpeg builds (a plain Homebrew install, for instance) don't ship. Rendering text via the same browser already driving the recording sidesteps that dependency and gives exact font parity with the recorded application for free.
+*/
+async function renderTextBand(bandContext, style, band) {
+	const bandPage = await bandContext.newPage();
+	try {
+		await bandPage.setViewportSize({
+			width: band.width,
+			height: band.height
+		});
+		await bandPage.setContent(`<!doctype html>
+<html><head><style>
+  html, body { margin: 0; width: ${String(band.width)}px; height: ${String(band.height)}px; background: ${style.background}; display: flex; align-items: center; justify-content: center; }
+  p { margin: 0; padding: 0 28px; max-width: 100%; box-sizing: border-box; color: ${style.textColor}; font: 500 ${String(band.fontSizePx)}px/1.35 ${style.fontStack}; text-align: center; overflow-wrap: break-word; }
+</style></head>
+<body><p>${escapeHtml(band.text)}</p></body></html>`);
+		return await bandPage.screenshot({ type: "png" });
+	} finally {
+		await bandPage.close();
+	}
+}
+//#endregion
+//#region src/filter-graph.ts
+/**
+* A window opens at each show event and closes at whatever event follows it (an explicit hide, or a subsequent show replacing the line), or at the video's own end if nothing follows. A hide event only ever closes the preceding show's window: it opens no window of its own.
+*/
+function captionWindows(events, videoDurationMs) {
+	const windows = [];
+	for (const [i, event] of events.entries()) {
+		if (event.text === null) continue;
+		const nextEvent = events[i + 1];
+		windows.push({
+			text: event.text,
+			startMs: event.atMs,
+			endMs: nextEvent === void 0 ? videoDurationMs : nextEvent.atMs
+		});
+	}
+	return windows;
+}
+const MS_PER_SECOND = 1e3;
+const FFMPEG_TIME_DECIMAL_PLACES = 3;
+/**
+* Input 0 is the raw recording, input 1 the header band PNG, inputs 2.. the caption band PNGs in window order. The graph pads input 0 onto a taller canvas of band colour (header band above, footer band below), overlays the header at the top, then chains one time-gated overlay per caption window onto the footer region.
+*/
+function buildFramePlan(viewport, style, windows) {
+	const padHeight = viewport.height + style.headerHeightPx + style.footerHeightPx;
+	let filterGraph = `[0:v]pad=${String(viewport.width)}:${String(padHeight)}:0:${String(style.headerHeightPx)}:color=${style.background}[bg];[bg][1:v]overlay=0:0[v0]`;
+	let lastLabel = "v0";
+	let inputIndex = 2;
+	for (const [i, window] of windows.entries()) {
+		const startS = (window.startMs / MS_PER_SECOND).toFixed(FFMPEG_TIME_DECIMAL_PLACES);
+		const endS = (window.endMs / MS_PER_SECOND).toFixed(FFMPEG_TIME_DECIMAL_PLACES);
+		const nextLabel = `v${String(i + 1)}`;
+		filterGraph += `;[${lastLabel}][${String(inputIndex)}:v]overlay=0:${String(style.headerHeightPx + viewport.height)}:enable='between(t,${startS},${endS})'[${nextLabel}]`;
+		lastLabel = nextLabel;
+		inputIndex++;
+	}
+	return {
+		inputCount: inputIndex,
+		filterGraph,
+		finalLabel: lastLabel
+	};
+}
+//#endregion
+//#region src/ffmpeg.ts
+async function runCommand(command, args, label) {
+	return await new Promise((resolve, reject) => {
+		(0, node_child_process.execFile)(command, args, (error, stdout) => {
+			if (error) {
+				const reason = error.code === "ENOENT" ? `${label} not found on PATH. talktrack drives the external ${label} binary for video post-processing; install it (for example "brew install ffmpeg" or "apt-get install ffmpeg") and retry.` : `${label} failed: ${error.message}`;
+				reject(new Error(reason, { cause: error }));
+			} else resolve(stdout);
+		});
+	});
+}
+/**
+* Runs the external ffmpeg binary with the given arguments. Rejects with an install hint rather than a bare spawn error when ffmpeg is not on PATH.
+*/
+async function runFfmpeg(args) {
+	return await runCommand("ffmpeg", args, "ffmpeg");
+}
+/**
+* Throws unless the recorded video's pixel size equals the viewport the bands are laid out against. Playwright records a smaller video than the viewport unless `video.size` is set to match (its default scales the recording to fit inside 800x800), and the framing pass would then pad that smaller picture onto a canvas sized for the full viewport: a silently mis-laid-out result that still looks like a successful run.
+*/
+function assertVideoMatchesViewport(facts, viewport, videoPath) {
+	if (facts.width === viewport.width && facts.height === viewport.height) return;
+	throw new Error(`talktrack cannot frame ${videoPath}: the recording is ${String(facts.width)}x${String(facts.height)} but the viewport is ${String(viewport.width)}x${String(viewport.height)}. Set the recording size to the viewport size (Playwright Test: video: { mode: "on", size }; recordDemo does this itself) so the bands line up with the picture.`);
+}
+/**
+* Narrows a parsed JSON value to a plain object, per the house unknown-handling rule: never an assertion, always a guard.
+*/
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Probes a video file with ffprobe for its pixel dimensions and duration in milliseconds. Any output shape other than the documented stream+format JSON object rejects with the path and what was wrong.
+*/
+async function probeVideo(videoPath) {
+	const stdout = await runCommand("ffprobe", [
+		"-v",
+		"error",
+		"-select_streams",
+		"v:0",
+		"-show_entries",
+		"stream=width,height:format=duration",
+		"-of",
+		"json",
+		videoPath
+	], "ffprobe");
+	const parsed = JSON.parse(stdout);
+	if (!isRecord(parsed)) throw new Error(`Unexpected ffprobe output for ${videoPath}: not a JSON object`);
+	const streams = parsed.streams;
+	const format = parsed.format;
+	if (!Array.isArray(streams) || !isRecord(format)) throw new Error(`Unexpected ffprobe output for ${videoPath}: streams is not an array or format is not an object`);
+	const firstStream = streams[0];
+	if (!isRecord(firstStream)) throw new Error(`Unexpected ffprobe output for ${videoPath}: first stream is not an object`);
+	const width = firstStream.width;
+	const height = firstStream.height;
+	const durationRaw = format.duration;
+	if (typeof width !== "number" || typeof height !== "number" || typeof durationRaw !== "string") throw new Error(`Unexpected ffprobe output for ${videoPath}: stream width/height or format.duration has the wrong type`);
+	return {
+		durationMs: Math.round(Number.parseFloat(durationRaw) * 1e3),
+		width,
+		height
+	};
+}
+//#endregion
+//#region src/frame.ts
+/**
+* The default header band: the word "commit", the short sha, a middot, and the ISO recording-start timestamp, or just the timestamp when not inside a git working tree (demos run from anywhere, not only repos).
+*/
+async function defaultHeaderText(startedAtMs) {
+	const createdAtIso = new Date(startedAtMs).toISOString();
+	try {
+		return `commit ${await new Promise((resolve, reject) => {
+			(0, node_child_process.execFile)("git", [
+				"rev-parse",
+				"--short",
+				"HEAD"
+			], (error, stdout) => {
+				if (error) reject(new Error(error.message, { cause: error }));
+				else resolve(stdout.trim());
+			});
+		})} · ${createdAtIso}`;
+	} catch {
+		return createdAtIso;
+	}
+}
+/**
+* Frames one raw recording: renders the header and caption band PNGs, probes the raw video's duration, and composites everything into {@link FrameRecordingInput.framedPath} with ffmpeg. Returns that path.
+*/
+async function frameRecording(input) {
+	const style = resolveBandStyle(input.bands);
+	const timeline = getRecordingTimeline(input.page);
+	const facts = await probeVideo(input.videoPath);
+	assertVideoMatchesViewport(facts, input.viewport, input.videoPath);
+	const windows = captionWindows(timeline.events, facts.durationMs);
+	const plan = buildFramePlan(input.viewport, style, windows);
+	const bandContext = await input.browser.newContext();
+	const workDir = await (0, node_fs_promises.mkdtemp)((0, node_path.join)((0, node_os.tmpdir)(), "talktrack-frame-"));
+	try {
+		const inputArgs = ["-i", input.videoPath];
+		const headerPngPath = (0, node_path.join)(workDir, "header.png");
+		await (0, node_fs_promises.writeFile)(headerPngPath, await renderTextBand(bandContext, style, {
+			width: input.viewport.width,
+			height: style.headerHeightPx,
+			fontSizePx: style.headerFontSizePx,
+			text: await input.headerText
+		}));
+		inputArgs.push("-i", headerPngPath);
+		for (const [i, window] of windows.entries()) {
+			const captionPngPath = (0, node_path.join)(workDir, `caption-${String(i)}.png`);
+			await (0, node_fs_promises.writeFile)(captionPngPath, await renderTextBand(bandContext, style, {
+				width: input.viewport.width,
+				height: style.footerHeightPx,
+				fontSizePx: style.footerFontSizePx,
+				text: window.text
+			}));
+			inputArgs.push("-i", captionPngPath);
+		}
+		await runFfmpeg([
+			"-y",
+			...inputArgs,
+			"-filter_complex",
+			plan.filterGraph,
+			"-map",
+			`[${plan.finalLabel}]`,
+			"-c:v",
+			"libvpx-vp9",
+			"-crf",
+			"32",
+			"-b:v",
+			"0",
+			"-deadline",
+			"good",
+			"-cpu-used",
+			"3",
+			input.framedPath
+		]);
+		return input.framedPath;
+	} finally {
+		await bandContext.close();
+		await (0, node_fs_promises.rm)(workDir, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+//#endregion
+//#region src/test-adapter.ts
+/**
+* Produces a taller, framed copy of the just-recorded spec video: the app window exactly as recorded, a static header above it, and a footer below it showing each narration line only while it was actually shown during the run. A no-op returning undefined (not a failure) when there's no video to frame at all (a spec run without video enabled) or no viewport to size bands against.
+*
+* Closes the page. Playwright only finalises a page's video once the page is closed, and an afterEach hook runs while the test's page is still open, so the recording on disk is incomplete until then: the adapter closes the page itself and waits for the finalised video (video.saveAs waits for exactly that) before reading it. The page is unusable afterwards, which is why this belongs in afterEach and not mid-test.
+*/
+async function finalizeFramedRecording(page, testInfo, opts) {
+	const video = page.video();
+	if (!video) return void 0;
+	const viewport = page.viewportSize();
+	if (!viewport) return void 0;
+	const browser = page.context().browser();
+	if (!browser) throw new Error("talktrack cannot frame this recording: a persistent browser context has no separate Browser handle to render caption bands through");
+	const rawPath = await video.path();
+	const framedPath = opts?.framedPath ?? rawPath.replace(/\.webm$/, "-framed.webm");
+	const headerText = opts?.headerText ?? defaultHeaderText(getRecordingTimeline(page).startedAt);
+	const scratchDir = await (0, node_fs_promises.mkdtemp)((0, node_path.join)((0, node_os.tmpdir)(), "talktrack-raw-"));
+	try {
+		await page.close();
+		const finalisedRawPath = (0, node_path.join)(scratchDir, "raw.webm");
+		await video.saveAs(finalisedRawPath);
+		await frameRecording({
+			page,
+			videoPath: finalisedRawPath,
+			viewport,
+			browser,
+			headerText,
+			framedPath,
+			...opts?.bands ? { bands: opts.bands } : {}
+		});
+	} finally {
+		await (0, node_fs_promises.rm)(scratchDir, {
+			recursive: true,
+			force: true
+		});
+	}
+	await testInfo.attach("framed-recording", {
+		path: framedPath,
+		contentType: "video/webm"
+	});
+	return framedPath;
+}
+//#endregion
+//#region src/standalone.ts
+/**
+* Starts one standalone demo recording: launches (or borrows) a browser, opens a video-recording context at the given viewport, installs the cursor, optionally navigates to `url`, and returns the session. Drive the page through the session's helpers, then `await session.finish()` once; it returns the framed recording's path.
+*/
+async function recordDemo(name, opts) {
+	const outputDir = opts.outputDir ?? (0, node_path.join)(process.cwd(), "talktrack-output");
+	await (0, node_fs_promises.mkdir)(outputDir, { recursive: true });
+	const ownsBrowser = opts.browser === void 0;
+	const browser = opts.browser ?? await (opts.browserType ?? _playwright_test.chromium).launch(opts.launchOptions ?? {});
+	const context = await browser.newContext({
+		...opts.contextOptions,
+		viewport: opts.viewport,
+		recordVideo: {
+			dir: outputDir,
+			size: opts.viewport
+		}
+	});
+	const page = await context.newPage();
+	await installCursor(page);
+	if (opts.url !== void 0) await gotoWithCursor(page, opts.url);
+	const finish = async () => {
+		const viewport = page.viewportSize();
+		if (!viewport) throw new Error("talktrack could not read the viewport before closing the demo's context");
+		const video = page.video();
+		if (!video) throw new Error("talktrack's recording context produced no video handle");
+		const videoPathPromise = video.path();
+		await context.close();
+		const videoPath = await videoPathPromise;
+		const framedPath = (0, node_path.join)(outputDir, `${name}-framed.webm`);
+		const headerText = opts.headerText ?? defaultHeaderText(getRecordingTimeline(page).startedAt);
+		const framed = await frameRecording({
+			page,
+			videoPath,
+			viewport,
+			browser,
+			headerText,
+			framedPath,
+			...opts.bands ? { bands: opts.bands } : {}
+		});
+		if (ownsBrowser) await browser.close();
+		return framed;
+	};
+	return {
+		page,
+		context,
+		moveAndClick: async (locator, pauseMs) => moveAndClick(page, locator, pauseMs),
+		fillVisibly: async (locator, text, pauseMs) => fillVisibly(page, locator, text, pauseMs),
+		naturalScrollIntoView: async (locator) => naturalScrollIntoView(page, locator),
+		goto: async (url) => gotoWithCursor(page, url),
+		reload: async () => reloadWithCursor(page),
+		caption: (text) => {
+			showCaption(page, text);
+		},
+		hideCaption: () => {
+			hideCaption(page);
+		},
+		narrateScene: async (text, settle, narrateOpts) => narrateScene(page, text, settle, narrateOpts),
+		beat: async (ms) => beat(page, ms),
+		finish
+	};
+}
+//#endregion
+exports.beat = beat;
+exports.buildFramePlan = buildFramePlan;
+exports.captionWindows = captionWindows;
+exports.defaultBandStyle = defaultBandStyle;
+exports.defaultHeaderText = defaultHeaderText;
+exports.fillVisibly = fillVisibly;
+exports.finalizeFramedRecording = finalizeFramedRecording;
+exports.frameRecording = frameRecording;
+exports.gotoWithCursor = gotoWithCursor;
+exports.hideCaption = hideCaption;
+exports.humanBeatMs = humanBeatMs;
+exports.installCursor = installCursor;
+exports.markRecordingStart = markRecordingStart;
+exports.moveAndClick = moveAndClick;
+exports.narrateScene = narrateScene;
+exports.naturalScrollIntoView = naturalScrollIntoView;
+exports.recordCaptionEvent = recordCaptionEvent;
+exports.recordDemo = recordDemo;
+exports.reloadWithCursor = reloadWithCursor;
+exports.showCaption = showCaption;
+
+//# sourceMappingURL=index.cjs.map