@openvidstudio/mcp-server 0.1.0

package/dist/util.js

@@ -0,0 +1,163 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveProjectRoot = resolveProjectRoot;
+exports.sanitizeSegment = sanitizeSegment;
+exports.pascalCase = pascalCase;
+exports.sanitizeRelativeOutPath = sanitizeRelativeOutPath;
+exports.copyTemplateTree = copyTemplateTree;
+exports.spawnCapture = spawnCapture;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+function resolveProjectRoot(projectRoot) {
+    return projectRoot ? path.resolve(projectRoot) : process.cwd();
+}
+const SAFE_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+/**
+ * Validates a value used as a single path segment (project/video name, beat id)
+ * before it's joined into any filesystem path or process argv. Rejects `..`,
+ * `/`, `\`, and anything else outside a conservative safe set.
+ */
+function sanitizeSegment(value, label) {
+    if (!SAFE_SEGMENT.test(value)) {
+        throw new Error(`${label} "${value}" is not a safe path segment. Use letters, numbers, "-", or "_", starting with a letter or number.`);
+    }
+    return value;
+}
+/**
+ * PascalCases an id for use as a component/file name: split on any run of
+ * non-alphanumeric characters, capitalize the first letter of each remaining
+ * segment, join. A result starting with a digit gets an "S" prefix (invalid
+ * JS identifier otherwise); an empty result (all-symbol id) falls back to "Scene".
+ * scaffold_scene and stitch_composition both call this, so a beat's scene file name
+ * and its import in the generated composition always agree.
+ */
+function pascalCase(id) {
+    const parts = id.split(/[^A-Za-z0-9]+/).filter(Boolean);
+    const pascal = parts.map((p) => p.charAt(0).toUpperCase() + p.slice(1)).join("");
+    const safe = pascal.length > 0 ? pascal : "Scene";
+    return /^[0-9]/.test(safe) ? `S${safe}` : safe;
+}
+// Blocks shell metacharacters relevant on POSIX (;&|`$<>) and on Windows cmd.exe
+// specifically (%^"), which matters here because render_video spawns npx.cmd --
+// Windows can only execute a .cmd/.bat file via cmd.exe, and spawnCapture (below)
+// explicitly routes that one case through shell:true, so cmd.exe's own
+// metacharacters are in scope for any argument reaching that spawn call.
+const DANGEROUS_CHARS = /[;&|`$<>\n\r%^"]/;
+/**
+ * Validates a path argument that will be handed to a spawned child process
+ * (npx/ffmpeg): no shell metacharacters, and must resolve inside `root` so a
+ * crafted `../../` can't point the command at an arbitrary filesystem location.
+ */
+function sanitizeRelativeOutPath(root, relPath, label) {
+    if (DANGEROUS_CHARS.test(relPath)) {
+        throw new Error(`${label} "${relPath}" contains disallowed characters.`);
+    }
+    const rootResolved = path.resolve(root);
+    const resolved = path.resolve(rootResolved, relPath);
+    if (resolved !== rootResolved && !resolved.startsWith(rootResolved + path.sep)) {
+        throw new Error(`${label} "${relPath}" must resolve inside the project root.`);
+    }
+    return relPath;
+}
+/**
+ * Copies a directory tree, skipping any `node_modules` subtree and never
+ * overwriting a file that already exists at the destination -- used by
+ * init_project to lay the bundled template shell into a user's project without
+ * clobbering anything the dev (or a prior init_project call, for a second video
+ * in the same project) has already touched.
+ */
+function copyTemplateTree(src, dest) {
+    if (!fs.existsSync(src)) {
+        throw new Error(`Template directory not found at ${src}. This package's build step (scripts/copy-template.mjs) may not have run.`);
+    }
+    fs.mkdirSync(dest, { recursive: true });
+    for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+        if (entry.name === "node_modules")
+            continue;
+        const s = path.join(src, entry.name);
+        const d = path.join(dest, entry.name);
+        if (entry.isDirectory()) {
+            copyTemplateTree(s, d);
+        }
+        else if (!fs.existsSync(d)) {
+            fs.copyFileSync(s, d);
+        }
+    }
+}
+// On Windows, spawning a `.cmd`/`.bat` shim (npx.cmd, the only such command any caller of
+// spawnCapture ever passes -- ffmpeg/ffprobe are real .exe) with shell:false throws a
+// synchronous EINVAL: CreateProcess cannot launch a batch file directly, and (verified
+// against this repo's actual Node runtime, Task 4's real end-to-end pipeline run) Node's
+// spawn() does not transparently shell out for it the way an older assumption in this file
+// believed. shell:true routes exactly that one case through cmd.exe, which is also why
+// sanitizeRelativeOutPath/sanitizeSegment already block shell metacharacters including `%^"`
+// (cmd.exe's own specials) everywhere a value can reach this function -- that defense was
+// already written for a cmd.exe hop, this just makes the hop actually happen for the case
+// that needs it, without changing behavior for the real-.exe (ffmpeg/ffprobe) callers.
+const WINDOWS_SHIM_RE = /\.(cmd|bat)$/i;
+/**
+ * Runs a child process to completion and captures its stdout/stderr in memory.
+ * `spawn` with an argv array, never `exec`/`execSync` with an interpolated shell string --
+ * render_video and qc_extract_frames both go through this. Capturing the child's output
+ * here has nothing to do with *this* process's own stdout (the MCP transport); it's
+ * returned as normal tool-result content by the caller.
+ */
+function spawnCapture(command, args, cwd) {
+    return new Promise((resolve, reject) => {
+        const shell = process.platform === "win32" && WINDOWS_SHIM_RE.test(command);
+        // Node's own shell:true + args-array combination does NOT escape/quote args for the
+        // caller (it just concatenates them into one command line before handing it to
+        // cmd.exe -- Node emits DEP0190 warning about exactly this), so an argument containing
+        // a space (a legal, unsanitized character in e.g. outPathRel) would silently word-split
+        // into two argv entries once shell:true is in effect. Every arg that reaches this
+        // function is already filtered through DANGEROUS_CHARS/SAFE_SEGMENT, which blocks `"`
+        // itself, so wrapping each in double quotes here is always safe and closes that gap
+        // without touching the non-shell (ffmpeg/ffprobe) call path at all.
+        const finalArgs = shell ? args.map((a) => `"${a}"`) : args;
+        const child = (0, node_child_process_1.spawn)(command, finalArgs, { cwd, shell });
+        let stdout = "";
+        let stderr = "";
+        child.stdout?.on("data", (chunk) => {
+            stdout += chunk.toString();
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr += chunk.toString();
+        });
+        child.on("error", reject);
+        child.on("close", (code) => resolve({ code, stdout, stderr }));
+    });
+}

package/docs/API.md

@@ -0,0 +1,344 @@
+# API.md: everything `@openvidstudio/core` exports
+
+Written because the alternative is reading the library source. If you are an agent
+about to write a scene, this file has every prop you need and you should not have to
+open `packages/core/src`.
+
+Import everything from the package root:
+
+```tsx
+import { CinematicScene, Layer, TerminalReplay, E, color } from "@openvidstudio/core";
+```
+
+---
+
+## Scene wrapper
+
+### `CinematicScene`
+
+Wraps every scene. Grain, vignette and colour grade are always on, and the camera rig
+lives inside it. Nothing renders outside one.
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `camera` | `CamKeyframe[]` | required | At least two, or nothing moves |
+| `stageWidth` | `number` | `1920` | |
+| `stageHeight` | `number` | `1080` | |
+| `variant` | `"dark" \| "light"` | `"dark"` | |
+| `grain` | `number` | `0.05` | |
+| `vignette` | `number` | `0.32` | |
+| `overlay` | `ReactNode` | | Screen space, not camera transformed. Captions and title cards go here |
+| `children` | `ReactNode` | required | |
+
+**The overlay is not optional knowledge.** Anything inside `children` moves with the
+camera, so a caption placed there drifts off screen as the shot pushes in. Captions,
+title cards and dips belong in `overlay`.
+
+---
+
+## Camera
+
+### `CamKeyframe`
+
+```ts
+type CamKeyframe = {
+  frame: number;
+  x: number;        // focal point on the stage, lands at frame centre
+  y: number;
+  scale: number;    // 1 = stage px equals output px, 1.6 = 160% close up
+  rotX?: number;
+  rotY?: number;
+  rotZ?: number;
+  easing?: (t: number) => number;  // easing INTO this keyframe
+};
+```
+
+**The one thing that catches everyone.** The visible area is the stage divided by
+`scale`. At `scale: 1.4` only 1371x771 of a 1920x1080 stage is on screen, so content
+laid out at full stage width is cropped at the frame edge, and the render does not
+warn. The binding number is the scene's **highest** scale, not its first.
+
+Rules of thumb:
+
+- Real captures: 1.2 to 2.5. STYLE.md requires the camera to sit inside the UI
+  rather than showing a flat full-screen grab.
+- Constructed panels: 1.04 to 1.15. They are already built at stage size, so they
+  need a gentle push, not a zoom.
+- Run `validate_scenes` and it will tell you which scenes are cropping.
+
+### `Layer`
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `depth` | `number` | `0` | Parallax and blur. `0` is the focal plane |
+| `maxBlur` | `number` | `10` | Blur in px at `depth` 1 |
+| `style` | `CSSProperties` | | |
+
+One focal plane per shot. Put background elements on a non-zero depth so they blur.
+
+### `CameraRig`, `useCamera`
+
+`CinematicScene` sets these up for you. Reach for them only when building a scene
+that needs the camera state directly.
+
+---
+
+## Motion
+
+### `E` and `SPRING`
+
+```ts
+E.cinematic  // default move: slow out, soft landing
+E.whip       // aggressive, for cuts and fast pans
+E.drift      // gentle ambient motion inside a shot
+E.snap       // snappy UI reaction, button press, blip reveal
+
+SPRING.soft  SPRING.pop  SPRING.heavy
+```
+
+**Linear easing fails QC.** There is no linear preset on purpose.
+
+### `tween`, `pop`, `jitter`, `staggerDelay`
+
+```ts
+tween(frame, [fromFrame, toFrame], [fromValue, toValue], E.cinematic): number
+pop(frame, fps, atFrame): number          // spring entrance scalar
+jitter(seed, n): number                   // deterministic 0..1, same every render
+staggerDelay(index, step = 3): number     // 3 frames at 30fps is 100ms
+```
+
+`jitter` is deterministic. Never use `Math.random()` in a scene: every frame renders
+in a separate process and random values differ per frame, which shows up as flicker.
+
+---
+
+## Text
+
+### `TitleSlam`
+
+| Prop | Type | Default |
+|---|---|---|
+| `text` | `string` | required |
+| `at` | `number` | required |
+| `fontSize` | `number` | `120` |
+| `color` | `string` | `color.textPrimary` |
+| `glowColor` | `string` | |
+| `align` | `"center" \| "left"` | `"center"` |
+| `sfx` | `boolean` | `true` |
+
+Per word entrance. Renders nothing before `at`.
+
+### `Caption`
+
+| Prop | Type | Default |
+|---|---|---|
+| `text` | `string` | required |
+| `at` | `number` | required |
+| `out` | `number` | |
+| `fontSize` | `number` | `34` |
+
+Sits 84px from the bottom. Put it in `overlay`, not `children`.
+
+---
+
+## Panels
+
+### `BrowserFrame`
+
+| Prop | Type | Default |
+|---|---|---|
+| `url` | `string` | required |
+| `width` | `number` | `1360` |
+| `height` | `number` | `850` |
+| `dark` | `boolean` | `true` |
+| `children` | `ReactNode` | required |
+
+Chrome bar is 56px, so `height` must be the capture height plus 56 or the page is
+letterboxed. `scaffold_scene` computes this from the real PNG for you.
+
+Screenshots may only appear inside a `BrowserFrame`. Recordings and AI clips must
+not: wrapping generated footage in browser chrome makes it look like a captured
+page, which STYLE.md's provenance rule forbids.
+
+### `CodePanel`
+
+| Prop | Type | Default |
+|---|---|---|
+| `title` | `string` | required |
+| `lines` | `CodeLine[]` | required |
+| `width` | `number` | `860` |
+| `height` | `number` | `640` |
+| `fontSize` | `number` | `22` |
+| `scroll` | `number` | `0` | px translateY, drive with a tween |
+| `highlight` | `number[]` | `[]` | 0-based line indexes |
+
+```ts
+type Token = { t: string; c?: "kw" | "str" | "fn" | "cm" | "num" | "plain" };
+type CodeLine = Token[];
+```
+
+```tsx
+lines={[
+  [{ t: "{", c: "plain" }],
+  [{ t: '  "name"', c: "str" }, { t: ": ", c: "plain" }, { t: '"value"', c: "str" }],
+]}
+```
+
+### `ChecklistPanel`
+
+| Prop | Type | Default |
+|---|---|---|
+| `title` | `string` | `"Community Standards"` |
+| `items` | `ChecklistItem[]` | required |
+| `width` | `number` | `760` |
+| `fontSize` | `number` | `27` |
+| `sfx` | `boolean` | `true` |
+
+```ts
+type ChecklistItem = { label: string; flipAt?: number };  // omit flipAt to stay unchecked
+```
+
+`flipAt` is an absolute scene frame.
+
+### `TerminalReplay`
+
+| Prop | Type | Default |
+|---|---|---|
+| `steps` | `TermStep[]` | required |
+| `title` | `string` | `"Project"` |
+| `width` | `number` | `1280` |
+| `fontSize` | `number` | `26` |
+| `cps` | `number` | `16` | characters per second |
+| `sfx` | `boolean` | `true` |
+| `trailingPrompt` | `boolean` | `true` |
+
+```ts
+type TermLine = { text: string; color?: string; glow?: boolean; bold?: boolean };
+type TermStep =
+  | { type: "cmd"; text: string }
+  | { type: "out"; lines: TermLine[]; stagger?: number; preDelay?: number }
+  | { type: "pause"; frames: number };
+```
+
+Terminals are always this component, never a screen recording of a terminal.
+
+`computeTerminalTimeline(steps, fps, cps)` returns `{ items, totalFrames }`, so camera
+keyframes can land frame-exact on content events rather than being guessed.
+
+### `CursorActor`
+
+| Prop | Type | Default |
+|---|---|---|
+| `path` | `CursorKeyframe[]` | required |
+| `clicks` | `number[]` | `[]` | frames where a click ring fires |
+| `scale` | `number` | `1.6` |
+| `sfx` | `boolean` | `true` |
+
+```ts
+type CursorKeyframe = { frame: number; x: number; y: number };
+```
+
+Coordinates are stage space. Movement is eased automatically; never linear.
+
+### `RepoCta`
+
+| Prop | Type | Default |
+|---|---|---|
+| `owner` | `string` | required |
+| `name` | `string` | required |
+| `description` | `string` | required |
+| `chips` | `string[]` | required |
+| `titleText` | `string` | required |
+| `durationInFrames` | `number` | `270` |
+
+A whole scene, not a panel. Do not wrap it in a `CinematicScene`; it brings its own.
+No star action by default.
+
+---
+
+## Sound
+
+All synthesized by `scripts/gen-sfx.sh` with ffmpeg, so a rendered video carries no
+third-party audio rights. Regenerate with `bash scripts/gen-sfx.sh`.
+
+| Component | Props | Use |
+|---|---|---|
+| `KeySound` | `at`, `seed?`, `volume?` (0.16) | One keystroke |
+| `TypingSfx` | `charFrames`, `volume?` | One key per typed character |
+| `EnterKey` | `at`, `volume?` (0.2) | End of a typed command |
+| `Click` | `at`, `volume?` | Cursor click |
+| `Whoosh` | `at`, `volume?` | Camera move or cut |
+| `Blip` | `at`, `volume?` (0.3) | UI reveal |
+| `SuccessChime` | `at`, `volume?` (0.35) | Completion |
+| `Bell` | `at`, `volume?` (0.3) | Heavier completion |
+| `MusicBed` | `durationInFrames`, `volume?` (0.16) | Ambient bed, loops |
+
+`TerminalReplay` emits its own typing sounds. Pass `sfx={false}` to silence it.
+
+Narration is separate: `generate_narration` writes
+`public/audio/vo/<beatId>.mp3` and `stitch_composition` picks it up.
+
+---
+
+## Look pass
+
+`FilmGrain`, `Vignette`, `ColorGrade`, `LookPass`. `CinematicScene` applies these, so
+reach for them only when compositing outside a scene.
+
+---
+
+## Tokens
+
+```ts
+color.bg0 color.bg1 color.panel color.panelBorder
+color.textPrimary color.textSecondary
+color.accent color.accentAlt color.success color.warn color.danger
+color.lightBg color.lightCard color.lightShadow
+
+font.ui    // "Inter"
+font.mono  // "JetBrains Mono"
+
+radius.window  // 12
+radius.card    // 10
+radius.pill    // 999
+
+glow(color, strength = 1)       // returns { textShadow }
+panelShadow(dark = true)        // returns a box-shadow string
+```
+
+Use tokens rather than literal hex, so a per-video theme can override them.
+
+---
+
+## A scene, end to end
+
+```tsx
+import React from "react";
+import { CinematicScene, Layer, TerminalReplay, Caption, color, E } from "@openvidstudio/core";
+
+export const Install: React.FC = () => (
+  <CinematicScene
+    camera={[
+      { frame: 0, x: 960, y: 540, scale: 1.05, rotZ: -0.4 },
+      { frame: 300, x: 960, y: 548, scale: 1.15, rotZ: 0.35, easing: E.drift },
+    ]}
+    overlay={<Caption text="one command" at={40} out={240} />}
+  >
+    <Layer depth={0}>
+      <div style={{ position: "absolute", inset: 0, display: "flex",
+                    alignItems: "center", justifyContent: "center" }}>
+        <TerminalReplay
+          width={1400}
+          steps={[
+            { type: "cmd", text: "npx -y @openvidstudio/mcp-server" },
+            { type: "out", lines: [{ text: "connected over stdio", color: color.success, glow: true }] },
+          ]}
+        />
+      </div>
+    </Layer>
+  </CinematicScene>
+);
+```
+
+Two keyframes so it moves, content centred inside the safe area, caption in the
+overlay, tokens instead of hex.

package/docs/CAPTURE.md

@@ -0,0 +1,106 @@
+# CAPTURE.md: real screenshots and recordings for scenes
+
+Binding for every scene with `captureMethod: "screenshot"` or
+`"recording"` (see `PLANNING.md`). This protocol exists because
+uncorrected captures reliably come out small, soft, or bleed in content
+from a neighboring page section; here's why, and the fix. This is also
+what the `capture_screenshot` MCP tool does internally and why: if a
+capture from that tool ever comes out wrong, this is the mechanism to
+debug against.
+
+## The zoom-desync bug
+
+Playwright MCP's `browser_resize` sets a *requested* viewport, but a
+browser profile can carry a per-origin zoom level (set once, persisted,
+invisible in the tool output) that desyncs the requested size from the
+effective CSS layout Chrome actually renders. Confirmed on a real machine:
+requesting 1600x1000 rendered at `window.innerWidth/innerHeight` of
+2000x1250 (zoom = 0.8). This is a *consistent ratio*, not noise, so it's
+fully correctable, not something to route around by guessing crop
+coordinates.
+
+**Never trust a resize at face value. Always verify.**
+
+## Protocol
+
+1. `browser_resize` to your target size, `browser_navigate`, then
+   `page.evaluate(() => [window.innerWidth, window.innerHeight])`. If it
+   doesn't match what you requested, you have a desync.
+   `zoom = requestedWidth / actualInnerWidth`.
+2. Re-request a *compensated* viewport: `browser_resize(targetW * zoom,
+   targetH * zoom)`. Verify again: `innerWidth/innerHeight` should now
+   equal `targetW/targetH` exactly. This is the size you actually wanted,
+   once compensated.
+3. Interact with the page (click, select, scroll) to reach the exact state
+   the beat needs, in this same compensated viewport.
+4. Take a full-viewport screenshot (`scale: "css"`, no `fullPage`, no
+   element target, see below for why not element-scoped). This screenshot
+   is physically `targetW*zoom x targetH*zoom` px and contains `targetW x
+   targetH` worth of real layout, shrunk by `zoom`.
+5. Measure the DOM rect of exactly the content the beat wants, with
+   `el.getBoundingClientRect()`, in the same effective CSS space as step
+   2. Don't eyeball pixel coordinates off the screenshot; measure the real
+   element.
+6. Run `python scripts/crop-shot.py <raw.png> <out.png> <x> <y> <w> <h>
+   <zoom>` (the rect from step 5, the zoom from step 1/2). It crops the
+   physical screenshot at `rect * zoom`, then upscales the crop back to
+   `rect`'s own size with Lanczos resampling, landing on a pixel-accurate,
+   unshrunk capture with no bleed, because the crop rect came from the
+   DOM, not a guess.
+7. `Read` the output PNG before using it in a scene. Confirm by eye: no
+   cut-off text, no chrome from an unrelated section, correct state
+   selected.
+
+**Caveat when skipping `cropSelector`:** `capture_screenshot`'s output, with
+no `cropSelector` given, is exactly the compensated viewport's own pixel
+size (steps 1-2 above), not necessarily the size you originally requested.
+On a machine with a real zoom desync (zoom != 1), that means the saved
+image comes out smaller, and reads softer once a scene scales it back up,
+than the size you asked for. Passing `cropSelector` sidesteps this because
+the crop-and-upscale step (6 below) always lands back on the DOM rect's
+own true size regardless of the measured zoom; without it, check the
+tool's reported `zoom` before trusting the raw image at face value.
+
+**Why not `page.locator(selector).screenshot()`** (element-scoped): it
+re-measures and can auto-scroll the element into view at shot time,
+independent of what you measured a moment earlier. That mismatch produces
+a real bleed bug: an element-scoped shot picking up part of the next
+section down. The full-viewport-then-crop approach in steps 4-6 is
+deterministic: one screenshot, one measurement, one crop, no hidden
+re-layout between them.
+
+## Screen recordings
+
+For `captureMethod: "recording"` beats, the same zoom-desync check in step
+1 still applies before you start recording: verify the effective viewport
+matches what you requested before you hit record, since the desync is set
+once per origin and persists for the whole session. v1 scope is fixed
+full-viewport recordings only: capture at the compensated viewport size
+and composite the whole frame (no post-hoc DOM-rect cropping of a moving
+recording, that's future work, see `PIPELINE.md`).
+
+## Sizing the frame from the capture
+
+Once you have a clean capture, size `BrowserFrame` to the screenshot's
+*native* aspect so the `<Img>` (or `OffthreadVideo`, for a recording)
+needs no distortion:
+
+```
+FRAME_W = <capture width>
+FRAME_H = <capture height> + 56   // BrowserFrame's chrome bar is 56px, added on top of content
+LEFT = (1920 - FRAME_W) / 2
+TOP = (1080 - FRAME_H) / 2
+```
+
+This centers the frame on the 1920x1080 stage exactly: `LEFT + FRAME_W/2`
+is always `960` by construction. Push the camera to 115-160% (STYLE.md's
+120-250% range) with `x=960` as the base; adjust `y` only if the beat's
+important content isn't at the frame's own vertical center.
+
+**Check the bottom edge before locking a static crop.** A static camera
+crop that looks fine at scale 1.0 can push important content off the
+bottom of frame once you zoom in on it. If a screenshot is taller than
+what one crop can show at a good zoom level, animate the camera `y` across
+the beat instead of picking one static point: pan from the top
+(headline/context) to the bottom (the payoff) rather than compressing
+everything into a single frame that's forced to zoom out to fit it all.