browser-workspace 0.4.0

package/src/browser_harness/video.py

@@ -0,0 +1,749 @@
+#!/usr/bin/env python3
+"""Initialize, compile, review, and export browser-harness recordings."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import math
+import re
+import shutil
+from pathlib import Path
+from typing import Any
+
+TEMPLATE = Path(__file__).with_name("video-template.html")
+SOURCE_MANIFEST = "video-source.json"
+COMPOSITION_PREFIX = "window.COMPOSITION ="
+SENSITIVE = re.compile(
+    r"@|onmicrosoft\.com|(?:tenant|user|object)[_-]?id|"
+    r"\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b",
+    re.IGNORECASE,
+)
+ROUTE_UNSAFE = re.compile(
+    r"@|[?#]|://|onmicrosoft|(?:tenant|user|object)[_-]?id|"
+    r"\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b",
+    re.IGNORECASE,
+)
+OPAQUE_HEX = re.compile(r"^#[0-9a-f]{6}$", re.IGNORECASE)
+HOUSE_STYLE = {
+    "version": 1,
+    "frameStyle": "native",
+    "readingWpm": 380,
+    "background": ["#efece4", "#dce7e7"],
+    "cursorStart": {"x": 700, "y": 280},
+    "pacing": {
+        "captionBaseSeconds": 0.35,
+        "captionSecondsPerWord": 0.2,
+        "rawToCardHoldSeconds": 0.55,
+        "baseDurationBudget": 22,
+        "extraActionSeconds": 1.25,
+        "extraExplanationSeconds": 3,
+        "maximumDurationBudget": 32,
+    },
+    "motion": {
+        "autoFollow": True,
+        "autoZoom": 1.7,
+        "cursorDuration": 0.48,
+        "zoomDuration": 0.42,
+        "panDuration": 0.55,
+        "wideScale": 0.78,
+        "reactionLag": 0.025,
+        "reactionFade": 0.04,
+    },
+    "privacy": {"pad": 10, "mask": {"fill": "#ffffff", "stroke": False, "radius": 0}},
+}
+ACTION_KEYS = {
+    "event",
+    "frameEvent",
+    "afterEvent",
+    "chapter",
+    "route",
+    "afterRoute",
+    "narration",
+    "label",
+    "detour",
+    "error",
+    "context",
+    "showTyping",
+}
+BRIEF_KEYS = {
+    "task",
+    "summary",
+    "plan",
+    "actions",
+    "explanations",
+    "outcomeTitle",
+    "outcomeSummary",
+    "outcomes",
+    "privacy",
+}
+PRIVACY_KEYS = {"reviewedFrames", "redact"}
+EXPLANATION_KEYS = {
+    "afterAction",
+    "title",
+    "summary",
+    "observed",
+    "mistake",
+    "correction",
+}
+TYPE_HELPERS = {"type_text", "fill", "fill_input"}
+CLICK_HELPERS = {"click_at_xy"}
+REDACTION_KEYS = {"x", "y", "w", "h", "fill", "stroke", "radius", "pad"}
+VIEWPORT_TOLERANCE = 2
+
+
+class BriefError(ValueError):
+    """An edit brief violates the deliberately small authoring contract."""
+
+
+def load_json(path: Path) -> dict[str, Any]:
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise BriefError(f"cannot read {path}: {exc}") from exc
+    if not isinstance(value, dict):
+        raise BriefError(f"{path} must contain a JSON object")
+    return value
+
+
+def file_hash(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def load_composition(path: Path) -> dict[str, Any]:
+    try:
+        text = path.read_text(encoding="utf-8").strip()
+    except OSError as exc:
+        raise BriefError(f"cannot read {path}: {exc}") from exc
+    if not text.startswith(COMPOSITION_PREFIX) or not text.endswith(";"):
+        raise BriefError(f"{path} is not a generated composition")
+    try:
+        value = json.loads(text[len(COMPOSITION_PREFIX) : -1].strip())
+    except json.JSONDecodeError as exc:
+        raise BriefError(f"cannot read {path}: {exc}") from exc
+    if not isinstance(value, dict):
+        raise BriefError(f"{path} must set a JSON object")
+    return value
+
+
+def used_frames(composition: dict[str, Any]) -> list[str]:
+    frames: list[str] = []
+    for beat in composition.get("beats") or []:
+        for key in ("frame", "after"):
+            frame = beat.get(key)
+            if frame and frame not in frames:
+                frames.append(str(frame))
+    return frames
+
+
+def source_files(recording: Path) -> list[Path]:
+    required = [recording / name for name in ("events.jsonl", "meta.json", "recording-summary.json")]
+    frames = sorted(path for path in recording.glob("*.jpg") if path.stem.isdigit())
+    return [path for path in required if path.is_file()] + frames
+
+
+def write_source_manifest(recording: Path) -> dict[str, Any]:
+    meta_path = recording / "meta.json"
+    meta = load_json(meta_path) if meta_path.is_file() else {}
+    files = source_files(recording)
+    manifest = {
+        "recording": recording.name,
+        "started": meta.get("started"),
+        "explicit": meta_path.is_file() and meta.get("auto") is not True,
+        "files": {path.name: file_hash(path) for path in files},
+    }
+    (recording / SOURCE_MANIFEST).write_text(json.dumps(manifest, indent=2) + "\n", encoding="utf-8")
+    return manifest
+
+
+def verify_source_manifest(recording: Path) -> dict[str, Any]:
+    manifest = load_json(recording / SOURCE_MANIFEST)
+    if manifest.get("recording") != recording.name:
+        raise BriefError("recording directory does not match video-source.json")
+    expected = manifest.get("files")
+    if not isinstance(expected, dict):
+        raise BriefError("video-source.json has no source hashes")
+    paths = source_files(recording)
+    if {path.name for path in paths} != set(expected):
+        raise BriefError("recording source files changed after initialization")
+    for path in paths:
+        if expected.get(path.name) != file_hash(path):
+            raise BriefError(f"recording source changed after initialization: {path.name}")
+    return manifest
+
+
+def reject_unknown(value: dict[str, Any], allowed: set[str], where: str) -> None:
+    unknown = sorted(set(value) - allowed)
+    if unknown:
+        raise BriefError(f"{where} has unsupported field(s): {', '.join(unknown)}")
+
+
+def require_text(value: Any, where: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise BriefError(f"{where} must be non-empty text")
+    return value.strip()
+
+
+def require_text_list(value: Any, where: str, low: int, high: int) -> list[str]:
+    if not isinstance(value, list) or not low <= len(value) <= high:
+        raise BriefError(f"{where} must contain {low}–{high} items")
+    return [require_text(item, f"{where}[{index}]") for index, item in enumerate(value)]
+
+
+def words(value: Any) -> int:
+    return len(re.findall(r"\S+", str(value or "")))
+
+
+def card_duration(
+    title: str,
+    summary: str | None,
+    details: list[str],
+    kind: str,
+    reading_wpm: float,
+) -> float:
+    text = " ".join(part for part in (title, summary, *details) if part)
+    base = 4.5 if kind in {"intro", "outcome"} else 4.0
+    return round(max(base, 0.4 + words(text) * 60 / reading_wpm), 3)
+
+
+def validate_narration(value: Any, where: str) -> str | None:
+    if value is None:
+        return None
+    if not isinstance(value, str):
+        raise BriefError(f"{where} must be text")
+    if words(value) > 7:
+        raise BriefError(f"{where} exceeds seven words")
+    return value.strip()
+
+
+def optional_text(value: Any, where: str) -> str | None:
+    if value is None:
+        return None
+    return require_text(value, where)
+
+
+def event_at(events: list[dict[str, Any]], number: Any, where: str) -> dict[str, Any]:
+    if not isinstance(number, int) or isinstance(number, bool):
+        raise BriefError(f"{where} must be a one-based integer")
+    if number < 1 or number > len(events):
+        raise BriefError(f"{where} is outside recording-summary.json")
+    event = events[number - 1]
+    if not event.get("frame"):
+        raise BriefError(f"{where} has no captured frame")
+    return event
+
+
+def event_target(event: dict[str, Any]) -> dict[str, float] | None:
+    cursor = event.get("cursor")
+    if isinstance(cursor, dict) and cursor.get("x") is not None and cursor.get("y") is not None:
+        return {"x": float(cursor["x"]), "y": float(cursor["y"])}
+    box = event.get("box")
+    if isinstance(box, dict) and all(box.get(key) is not None for key in ("x", "y", "w", "h")):
+        return {
+            "x": float(box["x"]) + float(box["w"]) * 0.3,
+            "y": float(box["y"]) + float(box["h"]) / 2,
+        }
+    return None
+
+
+def require_matching_viewport(event: dict[str, Any], viewport: dict[str, Any], where: str) -> None:
+    candidate = event.get("viewport") or {}
+    try:
+        dw = abs(float(candidate["w"]) - float(viewport["w"]))
+        dh = abs(float(candidate["h"]) - float(viewport["h"]))
+    except (KeyError, TypeError, ValueError):
+        raise BriefError(f"{where} has no valid viewport") from None
+    if dw > VIEWPORT_TOLERANCE or dh > VIEWPORT_TOLERANCE:
+        raise BriefError(f"{where} uses a different viewport; split or normalize the recording first")
+
+
+def default_action_duration(beat: dict[str, Any], pacing: dict[str, Any]) -> float:
+    base = 0.7
+    if beat.get("click"):
+        base = 1.15
+    if beat.get("after"):
+        base = max(base, 1.4)
+    typing = beat.get("type")
+    if typing:
+        base = max(base, 0.6 + len(str(typing.get("text") or "")) * 0.035)
+    narration = beat.get("narration")
+    if narration:
+        base = max(
+            base,
+            float(pacing["captionBaseSeconds"])
+            + float(pacing["captionSecondsPerWord"]) * words(narration),
+        )
+    return round(base, 3)
+
+
+def duration_budget(
+    action_count: int,
+    explanation_count: int,
+    raw_to_card_count: int,
+    pacing: dict[str, Any],
+) -> float:
+    budget = float(pacing["baseDurationBudget"])
+    budget += max(0, action_count - 5) * float(pacing["extraActionSeconds"])
+    budget += max(0, explanation_count - 1) * float(
+        pacing["extraExplanationSeconds"]
+    )
+    budget += raw_to_card_count * float(pacing["rawToCardHoldSeconds"])
+    return round(min(budget, float(pacing["maximumDurationBudget"])), 3)
+
+
+def add_raw_to_card_holds(beats: list[dict[str, Any]], pacing: dict[str, Any]) -> int:
+    hold = float(pacing["rawToCardHoldSeconds"])
+    count = 0
+    for beat, next_beat in zip(beats, beats[1:]):
+        if beat.get("card") or not next_beat.get("card"):
+            continue
+        beat["endStateHold"] = hold
+        beat["dur"] = round(float(beat["dur"]) + hold, 3)
+        count += 1
+    return count
+
+
+def validate_narration_cadence(beats: list[dict[str, Any]]) -> None:
+    """Keep narration semantic and sticky instead of mirroring every frame."""
+
+    segments: list[list[dict[str, Any]]] = []
+    current: list[dict[str, Any]] = []
+    for beat in beats:
+        if beat.get("card"):
+            if current:
+                segments.append(current)
+                current = []
+        else:
+            current.append(beat)
+    if current:
+        segments.append(current)
+
+    for segment in segments:
+        cues = [beat for beat in segment if beat.get("narration")]
+        if len(segment) >= 3 and len(cues) > math.ceil(len(segment) / 2):
+            raise BriefError(
+                "narration is sticky: set it only when the thought changes, then "
+                "omit it while 2–3 screenshots advance underneath"
+            )
+        consecutive = 0
+        for beat in segment:
+            consecutive = consecutive + 1 if beat.get("narration") else 0
+            if consecutive >= 3:
+                raise BriefError(
+                    "three consecutive actions change narration; omit narration on "
+                    "intervening actions so text and screenshots use different pacing"
+                )
+
+
+def compile_action(
+    action: dict[str, Any],
+    index: int,
+    events: list[dict[str, Any]],
+    plan: list[str],
+    first_ts: float,
+    previous_target: dict[str, float] | None,
+    viewport: dict[str, float],
+    pacing: dict[str, Any],
+    revealed_text: dict[int, str],
+) -> tuple[dict[str, Any], dict[str, float] | None]:
+    if not isinstance(action, dict):
+        raise BriefError(f"actions[{index}] must be an object")
+    reject_unknown(action, ACTION_KEYS, f"actions[{index}]")
+    if "showTyping" in action and not isinstance(action["showTyping"], bool):
+        raise BriefError(f"actions[{index}].showTyping must be true or false")
+    event = event_at(events, action.get("event"), f"actions[{index}].event")
+    require_matching_viewport(event, viewport, f"actions[{index}].event")
+    frame_event = event
+    if action.get("frameEvent") is not None:
+        frame_event = event_at(
+            events, action["frameEvent"], f"actions[{index}].frameEvent"
+        )
+        require_matching_viewport(frame_event, viewport, f"actions[{index}].frameEvent")
+    chapter = action.get("chapter")
+    if not isinstance(chapter, int) or isinstance(chapter, bool) or not 0 <= chapter < len(plan):
+        raise BriefError(f"actions[{index}].chapter must index plan")
+    route = require_text(action.get("route"), f"actions[{index}].route")
+    if ROUTE_UNSAFE.search(route):
+        raise BriefError(f"actions[{index}].route must be semantic, not a raw URL or identity")
+
+    beat: dict[str, Any] = {
+        "frame": frame_event["frame"],
+        "route": route,
+        "chapter": chapter,
+    }
+    after_number = action.get("afterEvent")
+    if after_number is not None:
+        after = event_at(events, after_number, f"actions[{index}].afterEvent")
+        require_matching_viewport(after, viewport, f"actions[{index}].afterEvent")
+        beat["after"] = after["frame"]
+        after_route = action.get("afterRoute")
+        if after_route is not None:
+            after_route = require_text(after_route, f"actions[{index}].afterRoute")
+            if ROUTE_UNSAFE.search(after_route):
+                raise BriefError(f"actions[{index}].afterRoute must be semantic")
+            beat["afterRoute"] = after_route
+
+    narration = validate_narration(action.get("narration"), f"actions[{index}].narration")
+    if narration is not None:
+        beat["narration"] = narration
+    if action.get("label") is not None:
+        beat["label"] = require_text(action["label"], f"actions[{index}].label")
+    if action.get("detour") is True:
+        beat["detour"] = True
+    if action.get("error") is True:
+        beat["error"] = True
+
+    helper = str(event.get("helper") or "")
+    cursor = event.get("cursor")
+    if helper in CLICK_HELPERS:
+        if not isinstance(cursor, dict) or cursor.get("x") is None or cursor.get("y") is None:
+            raise BriefError(f"actions[{index}] identifies a click without captured coordinates")
+        beat["cursor"] = {"x": cursor["x"], "y": cursor["y"]}
+        beat["click"] = True
+    elif helper in TYPE_HELPERS:
+        box = event.get("box")
+        if not isinstance(box, dict) or not all(box.get(key) is not None for key in ("x", "y", "w", "h")):
+            raise BriefError(f"actions[{index}] identifies typing without a captured box")
+        show_typing = action.get("showTyping") is True
+        if show_typing and event.get("password"):
+            raise BriefError(f"actions[{index}].showTyping cannot reveal a password field")
+        source_line = event.get("sourceLine")
+        if show_typing and source_line not in revealed_text:
+            raise BriefError(f"actions[{index}].showTyping requires the original typed event")
+        beat["type"] = {
+            "box": {key: box[key] for key in ("x", "y", "w", "h")},
+            "text": revealed_text[source_line] if show_typing else "••••••",
+            **({} if show_typing else {"redact": True}),
+        }
+    elif action.get("showTyping") is not None:
+        raise BriefError(f"actions[{index}].showTyping requires a typing event")
+
+    target = event_target(event)
+    if action.get("context") is True and not (beat.get("click") or beat.get("type")):
+        beat["wide"] = True
+    elif target and previous_target:
+        distance = math.hypot(target["x"] - previous_target["x"], target["y"] - previous_target["y"])
+        diagonal = math.hypot(float(viewport["w"]), float(viewport["h"]))
+        if distance > diagonal * 0.58:
+            beat["cameraCut"] = True
+
+    ts = event.get("ts")
+    if isinstance(ts, (int, float)):
+        beat["t"] = round(max(0.0, float(ts) - first_ts), 3)
+    beat["dur"] = default_action_duration(beat, pacing)
+    return beat, target or previous_target
+
+
+def validate_privacy(reviewed: list[str], redact: dict[str, Any], composition: dict[str, Any]) -> None:
+    frames = used_frames(composition)
+    for frame in (*frames, *reviewed, *redact):
+        if Path(frame).name != frame or not frame.lower().endswith(".jpg"):
+            raise BriefError(f"invalid frame name: {frame}")
+    if len(reviewed) != len(set(reviewed)):
+        raise BriefError("privacy.reviewedFrames contains duplicates")
+    missing = [frame for frame in frames if frame not in reviewed]
+    if missing:
+        raise BriefError("privacy review missing: " + ", ".join(missing))
+    unknown = sorted(set(redact) - set(frames))
+    if unknown:
+        raise BriefError("privacy.redact lists unused frames: " + ", ".join(unknown))
+    for frame, rectangles in redact.items():
+        if not isinstance(rectangles, list):
+            raise BriefError(f"privacy.redact.{frame} must be a list")
+        for index, rectangle in enumerate(rectangles):
+            where = f"privacy.redact.{frame}[{index}]"
+            if not isinstance(rectangle, dict):
+                raise BriefError(f"{where} must be an object")
+            reject_unknown(rectangle, REDACTION_KEYS, where)
+            for key in ("x", "y", "w", "h"):
+                value = rectangle.get(key)
+                if not isinstance(value, (int, float)) or isinstance(value, bool) or not math.isfinite(value):
+                    raise BriefError(f"{where}.{key} must be a finite number")
+            if rectangle["w"] <= 0 or rectangle["h"] <= 0:
+                raise BriefError(f"{where} must have positive width and height")
+            for key in ("fill", "stroke"):
+                value = rectangle.get(key)
+                if value is not None and value is not False and (
+                    not isinstance(value, str) or not OPAQUE_HEX.fullmatch(value)
+                ):
+                    raise BriefError(f"{where}.{key} must be false or opaque six-digit hex")
+
+
+def compile_brief(summary: dict[str, Any], brief: dict[str, Any], style: dict[str, Any], revealed_text: dict[int, str] | None = None) -> dict[str, Any]:
+    reject_unknown(brief, BRIEF_KEYS, "edit brief")
+    task = require_text(brief.get("task"), "task")
+    summary_text = optional_text(brief.get("summary"), "summary")
+    plan = require_text_list(brief.get("plan"), "plan", 2, 5)
+    outcomes = require_text_list(brief.get("outcomes"), "outcomes", 1, 5)
+    actions = brief.get("actions")
+    if not isinstance(actions, list) or not actions:
+        raise BriefError("actions must contain at least one action")
+    events = summary.get("events")
+    if not isinstance(events, list) or not events:
+        raise BriefError("recording-summary.json has no events")
+    first_action = actions[0]
+    if not isinstance(first_action, dict):
+        raise BriefError("actions[0] must be an object")
+    viewport_event = event_at(
+        events,
+        first_action.get("frameEvent", first_action.get("event")),
+        "actions[0].frameEvent" if "frameEvent" in first_action else "actions[0].event",
+    )
+    if not (viewport_event.get("viewport") or {}).get("w") or not (viewport_event.get("viewport") or {}).get("h"):
+        raise BriefError("recording-summary.json has no viewport")
+    viewport = viewport_event["viewport"]
+    first_ts = next(
+        (float(event["ts"]) for event in events if isinstance(event.get("ts"), (int, float))),
+        0.0,
+    )
+
+    privacy = brief.get("privacy")
+    if not isinstance(privacy, dict):
+        raise BriefError("privacy must be an object")
+    reject_unknown(privacy, PRIVACY_KEYS, "privacy")
+    reviewed = privacy.get("reviewedFrames")
+    if not isinstance(reviewed, list) or not all(isinstance(frame, str) for frame in reviewed):
+        raise BriefError("privacy.reviewedFrames must be a list of frame names")
+    redact = privacy.get("redact") or {}
+    if not isinstance(redact, dict):
+        raise BriefError("privacy.redact must be an object")
+
+    explanations = brief.get("explanations") or []
+    if not isinstance(explanations, list):
+        raise BriefError("explanations must be a list")
+    pacing = style["pacing"]
+    reading_wpm = float(style["readingWpm"])
+    explanation_by_action: dict[int, list[dict[str, Any]]] = {}
+    revealed_text = revealed_text or {}
+    for index, explanation in enumerate(explanations):
+        if not isinstance(explanation, dict):
+            raise BriefError(f"explanations[{index}] must be an object")
+        reject_unknown(explanation, EXPLANATION_KEYS, f"explanations[{index}]")
+        after_action = explanation.get("afterAction")
+        if not isinstance(after_action, int) or isinstance(after_action, bool) or not 1 <= after_action <= len(actions):
+            raise BriefError(f"explanations[{index}].afterAction must index actions")
+        title = require_text(explanation.get("title"), f"explanations[{index}].title")
+        sub = optional_text(explanation.get("summary"), f"explanations[{index}].summary")
+        points = [
+            {"label": "Observed", "text": require_text(explanation.get("observed"), f"explanations[{index}].observed")},
+            {"label": "Mistake", "text": require_text(explanation.get("mistake"), f"explanations[{index}].mistake")},
+            {"label": "Correction", "text": require_text(explanation.get("correction"), f"explanations[{index}].correction")},
+        ]
+        card = {
+            "card": True,
+            "kind": "explanation",
+            "title": title,
+            **({"sub": sub} if sub is not None else {}),
+            "points": points,
+            "dur": card_duration(
+                title,
+                sub,
+                [part for point in points for part in (point["label"], point["text"])],
+                "explanation",
+                reading_wpm,
+            ),
+        }
+        explanation_by_action.setdefault(after_action, []).append(card)
+
+    intro = {
+        "card": True,
+        "kind": "intro",
+        "title": task,
+        **({"sub": summary_text} if summary_text is not None else {}),
+        "dur": card_duration(task, summary_text, plan, "intro", reading_wpm),
+    }
+    beats: list[dict[str, Any]] = [intro]
+    previous_target = None
+    for index, action in enumerate(actions):
+        beat, previous_target = compile_action(
+            action, index, events, plan, first_ts, previous_target, viewport, pacing, revealed_text
+        )
+        beats.append(beat)
+        beats.extend(explanation_by_action.get(index + 1, []))
+
+    outcome_title = require_text(brief.get("outcomeTitle") or "Task complete", "outcomeTitle")
+    outcome_summary = optional_text(brief.get("outcomeSummary"), "outcomeSummary")
+    beats.append(
+        {
+            "card": True,
+            "kind": "outcome",
+            "title": outcome_title,
+            **({"sub": outcome_summary} if outcome_summary is not None else {}),
+            "outcomes": outcomes,
+            "dur": card_duration(
+                outcome_title, outcome_summary, outcomes, "outcome", reading_wpm
+            ),
+        }
+    )
+
+    validate_narration_cadence(beats)
+    raw_to_card_count = add_raw_to_card_holds(beats, pacing)
+    budget = duration_budget(
+        len(actions), len(explanations), raw_to_card_count, pacing
+    )
+    duration = round(sum(float(beat["dur"]) for beat in beats), 3)
+    if duration > budget + 0.001:
+        raise BriefError(
+            f"compiled video is {duration:.1f}s; house-style budget is "
+            f"{budget:.1f}s. Shorten card copy, remove redundant actions, or set "
+            "narration only when the thought changes; viewers can pause for detail"
+        )
+
+    house_privacy = style["privacy"]
+    composition = {
+        "schemaVersion": style["version"],
+        "viewport": {"w": viewport["w"], "h": viewport["h"]},
+        "cursorStart": style["cursorStart"],
+        "frameStyle": style["frameStyle"],
+        "readingWpm": style["readingWpm"],
+        "pacing": pacing,
+        "durationBudget": budget,
+        "bg": style["background"],
+        "plan": plan,
+        "motion": style["motion"],
+        "privacy": {
+            "reviewedFrames": reviewed,
+            "pad": house_privacy["pad"],
+            "mask": house_privacy["mask"],
+        },
+        "redact": redact,
+        "beats": beats,
+    }
+    validate_privacy(reviewed, redact, composition)
+    return composition
+
+
+def write_composition(path: Path, composition: dict[str, Any]) -> None:
+    body = json.dumps(composition, indent=2, ensure_ascii=False)
+    path.write_text(f"window.COMPOSITION = {body};\n", encoding="utf-8")
+
+
+def load_revealed_text(events_path: Path) -> dict[int, str]:
+    revealed: dict[int, str] = {}
+    try:
+        lines = events_path.read_text(encoding="utf-8").splitlines()
+    except OSError as exc:
+        raise BriefError(f"cannot read {events_path}: {exc}") from exc
+    for source_line, line in enumerate(lines, 1):
+        if not line.strip():
+            continue
+        try:
+            event = json.loads(line)
+        except json.JSONDecodeError as exc:
+            raise BriefError(f"cannot read {events_path}: {exc}") from exc
+        if event.get("helper") in TYPE_HELPERS and event.get("input") != "password":
+            text = event.get("text")
+            if text is not None:
+                revealed[source_line] = str(text)
+    return revealed
+
+
+def safe_text(event: dict[str, Any]) -> str | None:
+    value = event.get("text")
+    if value is None:
+        return None
+    if event.get("helper") in TYPE_HELPERS:
+        return "<typed text hidden>"
+    value = str(value)
+    if event.get("input") == "password" or SENSITIVE.search(value):
+        return "<sensitive>"
+    return value[:120]
+
+
+def safe_label(value: object) -> str | None:
+    if value is None:
+        return None
+    value = str(value)
+    return "<sensitive>" if SENSITIVE.search(value) else value[:120]
+
+
+def init_recording(recording: Path, require_explicit: bool = False) -> int:
+    events_path = recording / "events.jsonl"
+    if not events_path.is_file():
+        raise BriefError(f"missing {events_path}")
+    meta_path = recording / "meta.json"
+    meta = load_json(meta_path) if meta_path.is_file() else {}
+    if require_explicit and (not meta_path.is_file() or meta.get("auto") is True):
+        raise BriefError("not an explicit recording; use the exact path returned by start_recording()")
+
+    shutil.copy2(TEMPLATE, recording / "video.html")
+    events = []
+    for source_line, line in enumerate(events_path.read_text(encoding="utf-8").splitlines(), 1):
+        if not line.strip():
+            continue
+        try:
+            raw = json.loads(line)
+        except json.JSONDecodeError as exc:
+            raise BriefError(f"cannot read {events_path}: {exc}") from exc
+        if not raw.get("frame"):
+            continue
+        events.append(
+            {
+                "frame": raw["frame"],
+                "sourceLine": source_line,
+                "helper": raw.get("helper"),
+                "ts": raw.get("ts"),
+                "route": "Browser",
+                "tab": safe_label(raw.get("title")),
+                "viewport": {"w": raw.get("w"), "h": raw.get("h")},
+                "cursor": (
+                    {"x": raw.get("x"), "y": raw.get("y")}
+                    if raw.get("x") is not None and raw.get("y") is not None
+                    else None
+                ),
+                "box": raw.get("box"),
+                "text": safe_text(raw),
+                "textLength": len(str(raw.get("text") or "")),
+                "password": raw.get("input") == "password",
+            }
+        )
+
+    summary = {
+        "recording": recording.name,
+        "title": safe_label(meta.get("title")),
+        "eventCount": len(events),
+        "events": events,
+    }
+    output = recording / "recording-summary.json"
+    output.write_text(json.dumps(summary, indent=2) + "\n", encoding="utf-8")
+    write_source_manifest(recording)
+    print(f"summary: {output}")
+    print(f"next: write {recording / 'edit-brief.json'}, then run browser-harness video review")
+    return 0
+
+
+def run_cli(args: list[str]) -> int:
+    parser = argparse.ArgumentParser(prog="browser-harness video")
+    sub = parser.add_subparsers(dest="command", required=True)
+    init = sub.add_parser("init", help="prepare a recording for editing")
+    init.add_argument("recording", type=Path)
+    init.add_argument("--require-explicit", action="store_true")
+    review = sub.add_parser("review", help="compile and generate a review sheet")
+    review.add_argument("recording", type=Path)
+    export = sub.add_parser("export", help="export a reviewed MP4")
+    export.add_argument("recording", type=Path)
+    export.add_argument("--output", default="video.mp4")
+    export.add_argument("--reviewed", action="store_true")
+    parsed = parser.parse_args(args)
+    recording = parsed.recording.expanduser().resolve()
+    try:
+        if parsed.command == "init":
+            return init_recording(recording, parsed.require_explicit)
+        from . import video_render
+
+        if parsed.command == "review":
+            return video_render.review(recording)
+        return video_render.export(recording, parsed.output, parsed.reviewed)
+    except (OSError, ValueError, RuntimeError) as exc:
+        parser.error(str(exc))
+
+
+def main() -> int:
+    import sys
+
+    return run_cli(sys.argv[1:])
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())