videoclaw 3.0.0-alpha.1

package/src/video/motion-overlay/motion-style.ts

@@ -0,0 +1,162 @@
+/**
+ * Pure motion-style registry + concept→animation metaphor map.
+ *
+ * Three styles, each a {accent, visualBlock, motionBlock} record:
+ *  - `apple-clean`     — ported verbatim from the source skill (Apple-keynote
+ *    minimalism with tactile materiality).
+ *  - `editorial-dark`  — genericized from the source skill's "CODA Dark"
+ *    (manifesto / punchline editorial poster aesthetic). CRITICAL: the prose
+ *    carries NO numeric specs, hex codes, or font-family names (CRITICAL
+ *    RULE 2 — those leak as on-screen text). The accent is a configurable
+ *    field, never baked into the prose.
+ *  - `knowledge-tool`  — genericized from the source skill's "Brain Clone"
+ *    (dark-academia / knowledge-graph look). Same no-specs prose discipline.
+ *
+ * The accent default lives in `MOTION_STYLES[id].accent`; `resolveStyle` lets a
+ * caller override it (`--accent`) or supply a brand profile (`--brand`, which
+ * takes precedence over `--accent`).
+ *
+ * Pure: no I/O. Deterministic.
+ */
+
+import type { MotionStyleId, ResolvedStyle } from './types.js';
+
+export interface MotionStyleDef {
+  accent: string; // default accent hex for this style
+  visualBlock: string; // prose — NO px/ms/hex/font-name/easing tokens
+  motionBlock: string; // prose — NO px/ms/hex/font-name/easing tokens
+}
+
+/**
+ * Style registry. The visual/motion prose is what gets sent to Omni, so it must
+ * stay free of any technical metadata (CRITICAL RULE 2). The accent is held
+ * separately as a hex value and is resolved into a HUMAN-NAMED colour at compose
+ * time — it never appears as a hex string in the prompt.
+ */
+export const MOTION_STYLES: Record<MotionStyleId, MotionStyleDef> = {
+  // ── apple-clean — ported verbatim from the source skill ──────────────────
+  'apple-clean': {
+    accent: '#FF5000',
+    visualBlock:
+      'Style: Apple-keynote minimalism with tactile materiality. Cards are dark frosted glass — they should feel like physical sheets of darkened glass with subtle refraction of the footage visible through them, not flat digital rectangles. Very soft rounded corners, a barely-visible hairline white edge that catches light like a real material seam, and a soft weighted drop shadow suggesting the card is floating slightly above the background. Text is clean modern white sans-serif, mostly sentence case, with category labels in uppercase. Typography itself behaves like an actor: each headline word feels deliberate, with tracking that breathes (slightly tighter on entry, settling into final spacing). The only accent colour is the configured accent — used SOLELY for the asterisk character (*) following key words, or as a thin underline below a single emphasized phrase. Never use the accent to fill or colour entire words; the accent is a beat marker, not decoration. Icons are pure white hairline outlines, never filled, never glowing. Backgrounded elements (cards no longer in focus) carry a subtle depth-of-field blur — the foreground is sharp, the background softens, like a cinematic lens.',
+    motionBlock:
+      'Motion: Slow, confident, premium — like an Apple product reveal directed with a real camera. Cards and headlines enter with a soft glide that decelerates into rest, NEVER linear motion — always settling under their own weight. Active camera movement is essential: elements use push-in and pull-out as if a slow cinematic lens is approaching and retreating. While an element holds on screen, it carries a slow gentle push-in — scaling up subtly over a beat, as if the camera is moving closer. When an element exits, it pulls back and slips into soft depth-of-field blur, shrinking slightly as it recedes. On key beats (asterisks, numbers, anchor words), a brief emphasis pulse hits the element — a quick scale up and settle that punctuates the rhythm. Idle elements carry a barely-perceptible parallax drift, suggesting the camera is never fully locked, always breathing slightly. Text reveals word by word with a small upward offset; on headline-anchor words (large dominant text), the letter tracking is slightly tight on entry and breathes outward into final spacing as the word settles — letters exhaling into place. Crossfades are smooth, outgoing elements fading while pulling back and slipping out of focus. Icons appear via stroke-on draw animation — lines drawing themselves like a pen on paper, never popping in. Kinetic typography mixes with cards: the speaker\'s anchor words appear as giant headline text dominating the frame, sometimes alone, sometimes alongside an icon — never let a take be only cards with icon labels; intersperse with at least one giant headline-anchor moment that syncs with the speaker\'s emphasis. Critical pacing principle: when the speaker pauses or breathes between sentences, the visual STOPS too — hold the current state silent and still during that beat. Silence before a reveal is more powerful than continuous animation. No bouncy springs, no whip pans, no pop-in, no constant motion filling every second. Subtle motion blur on all transforms.',
+  },
+
+  // ── editorial-dark — genericized from "CODA Dark" (no specs / no fonts) ───
+  'editorial-dark': {
+    accent: '#FF5000',
+    visualBlock:
+      'Style: Editorial dark manifesto — high-contrast poster typography in motion. Cards are solid deep-black surfaces with sharp, squared corners, no rounding — an editorial, decisive feel rather than a soft product look. Typography is a bold, condensed grotesque sans-serif set in uppercase with tight tracking and a low, punchy line height, treated like a magazine cover headline. The only accent colour is the configured accent, used SOLELY for a small asterisk (*) after each headline and for a thin underline on key shapes — never to fill whole words. Icons are minimal hairline strokes in the accent on key shapes only. A weighted drop shadow gives each black card real heft so it reads as a stacked poster panel floating above the frame. The overall feeling is a printed manifesto poster brought to life: stark, confident, punchline-driven, generous negative space around a single dominant statement.',
+    motionBlock:
+      'Motion: Snappy, decisive, high-contrast — an editorial poster animated. Cards and headlines enter fast and crisp, then settle without bounce, NEVER linear motion. Headlines snap in word by word in quick succession, each word landing with a confident stop. Exits are a quick fade with a small upward drift, the panel slipping away cleanly. There is still a real camera: a subtle push-in while a statement holds, a slight pull-back on exit, and a brief emphasis pulse on the asterisk or a key number to mark the beat. Idle panels carry a barely-perceptible parallax drift. Keep the rhythm decisive and poster-like rather than soft and floaty. Kinetic typography dominates: anchor words from the speech appear as giant uppercase headlines filling the frame, sometimes alone, sometimes with one hairline icon — never a take that is only icon-labelled cards. Critical pacing principle: when the speaker pauses, the visual STOPS too — hold the current panel silent and still during that beat. Silence before a reveal lands harder than constant motion. No springs, no whip pans, no pop-in clutter.',
+  },
+
+  // ── knowledge-tool — genericized from "Brain Clone" (no specs / no fonts) ─
+  'knowledge-tool': {
+    accent: '#A78BFA',
+    visualBlock:
+      'Style: Dark-academia digital meeting a knowledge-graph aesthetic — a knowledge-tool look, not generic motion graphics. Cards are deep near-black surfaces with the slightest cool blue undertone (never pure black), with very subtle hairline edges and a soft weighted shadow suggesting weight. Two typographic worlds intermix: headline anchors use a classical editorial serif — italic-capable, manuscript-like, the kind of letterforms on the cover of an old hardcover book; card labels and sublines use a clean modern sans-serif; small technical brackets and timestamps use a monospace typewriter-style face like an editor label. The only accent colour is the configured accent — a soft, calm lavender, never neon, never magenta — used SOLELY for the asterisk character (*) after key words and occasionally a thin underline. The asterisks have a slightly hand-drawn, brushy quality, like an ink stroke rather than a perfectly geometric character. The accent is a beat marker, never decoration. Icons are clean hairline outlines in soft, slightly cool off-white. Backgrounded elements carry depth-of-field blur. The composition feels like a knowledge tool: editorial magazine layout, generous negative space, considered hierarchy — not a slick product ad.',
+    motionBlock:
+      'Motion: Slow, contemplative, scholarly — directed like a documentary about a thinker\'s notebook rather than a product reveal. Cards and headlines enter with a soft glide that decelerates into rest, NEVER linear motion. Active cinematic camera: a slow push-in during a hold, as if a lens is approaching a page; a pull-out on exit where the element shrinks slightly and slips into soft depth-of-field blur; an emphasis pulse on key beats (asterisks, anchor words) — a quick scale up and settle. Idle elements carry a barely-perceptible parallax drift. The serif headline letters enter with tracking slightly tight, then breathe outward into final spacing as the word settles — letters exhaling like the word is being read aloud and considered. The brushy accent asterisk lands distinct from the word, a beat marker punctuating thought. Icons appear via stroke-on draw animation, lines forming like ink on paper. Kinetic typography mixes with cards: anchor words appear as giant serif headlines dominating the frame, sometimes alone, sometimes alongside an icon — never a take that is only cards with icon labels. Critical pacing principle: when the speaker pauses, the visual STOPS too — hold silent and still. Silence before a reveal is more powerful than continuous motion. The overall feeling: a quiet, deliberate study session, premium and considered.',
+  },
+};
+
+export interface ResolveStyleOptions {
+  /** Override the style's default accent (e.g. `--accent #00AAFF`). */
+  accent?: string;
+  /** Brand profile: its accent wins over both the style default AND `accent`. */
+  brand?: { accent?: string };
+}
+
+/**
+ * Resolve a style id + optional accent/brand overrides into a `ResolvedStyle`.
+ *
+ * Accent precedence (highest first): `brand.accent` → `accent` → style default.
+ * Pure: returns a fresh object; never mutates the registry.
+ */
+export function resolveStyle(id: MotionStyleId, opts: ResolveStyleOptions = {}): ResolvedStyle {
+  const def = MOTION_STYLES[id];
+  if (!def) {
+    throw new Error(`resolveStyle: unknown style "${id}"`);
+  }
+  const accent = opts.brand?.accent ?? opts.accent ?? def.accent;
+  return {
+    id,
+    accent,
+    visualBlock: def.visualBlock,
+    motionBlock: def.motionBlock,
+  };
+}
+
+/**
+ * Concept → animation prose.
+ *
+ * Concrete concepts (real-world objects) map to minimalist hairline-icon prose;
+ * abstract concepts (states/processes — AI, clones, intelligence, insight) map
+ * to a MATERIAL METAPHOR (particles / grids / light), never a generic hairline
+ * icon (which reads weak for an abstract idea). Pure — returns prose with no
+ * numeric specs.
+ */
+const CONCRETE_ICONS: Record<string, string> = {
+  carousel: 'three staggered diagonal portrait rectangles, like a deck of slides fanned out',
+  slides: 'three staggered diagonal portrait rectangles, like a deck of slides fanned out',
+  website: 'a browser window outline with three dots in the top-left and a few horizontal content lines',
+  'web page': 'a browser window outline with three dots in the top-left and a few horizontal content lines',
+  app: 'the hairline outline of a vertical phone with a small notch',
+  application: 'the hairline outline of a vertical phone with a small notch',
+  code: 'a window outline holding a few lines of code suggested as hairlines with varied indentation',
+  programming: 'a window outline holding a few lines of code suggested as hairlines with varied indentation',
+  chat: 'two stacked speech bubbles, one showing typing dots',
+  conversation: 'two stacked speech bubbles, one showing typing dots',
+  money: 'a currency mark inside a hairline circle',
+  revenue: 'a currency mark inside a hairline circle',
+  time: 'a clock outline with slim hands',
+  fast: 'a clock outline with slim hands',
+  data: 'a hairline bar chart with a few rising bars',
+  analytics: 'a hairline bar chart with a few rising bars',
+  vault: 'a hexagonal outline with a central dot and radial lines',
+  obsidian: 'a hexagonal outline with a central dot and radial lines',
+};
+
+const ABSTRACT_METAPHORS: Record<string, string> = {
+  ai: 'soft white particles drifting upward, slowly coalescing into a brain-like silhouette outlined in hairlines, with a subtle inner glow',
+  intelligence:
+    'soft white particles drifting upward, slowly coalescing into a brain-like silhouette outlined in hairlines, with a subtle inner glow',
+  thinking:
+    'soft white particles drifting upward, slowly coalescing into a brain-like silhouette outlined in hairlines, with a subtle inner glow',
+  clone: 'thin hairline lines drawing themselves one by one between scattered white dots, forming a network constellation that settles into a stable graph',
+  clones:
+    'thin hairline lines drawing themselves one by one between scattered white dots, forming a network constellation that settles into a stable graph',
+  sources:
+    'thin hairline lines drawing themselves one by one between scattered white dots, forming a network constellation that settles into a stable graph',
+  knowledge:
+    'thin hairline lines drawing themselves one by one between scattered white dots, forming a network constellation that settles into a stable graph',
+  insight: 'a soft warm-white bloom of light expanding outward from a central point, then settling into a clean centred headline as the light fades',
+  reveal: 'a soft warm-white bloom of light expanding outward from a central point, then settling into a clean centred headline as the light fades',
+  answer: 'a soft warm-white bloom of light expanding outward from a central point, then settling into a clean centred headline as the light fades',
+  agent: 'interconnected nodes with one node pulsing softly, suggesting a continuous process — gentle, not mechanical',
+  automation: 'interconnected nodes with one node pulsing softly, suggesting a continuous process — gentle, not mechanical',
+  processing: 'particles flowing into a structured grid that locks into place line by line, then settles',
+  analysis: 'particles flowing into a structured grid that locks into place line by line, then settles',
+};
+
+/**
+ * Resolve a single concept word to animation prose. Concrete → hairline icon;
+ * abstract → material metaphor; unknown abstract-ish words fall back to a
+ * generic light metaphor and unknown concrete-ish words to a generic hairline
+ * icon. Lookup is case-insensitive on the trimmed concept.
+ */
+export function conceptAnimation(concept: string): string {
+  const key = concept.trim().toLowerCase();
+  if (key in ABSTRACT_METAPHORS) {
+    return ABSTRACT_METAPHORS[key];
+  }
+  if (key in CONCRETE_ICONS) {
+    return CONCRETE_ICONS[key];
+  }
+  // Unknown: keep the concrete default (a hairline icon). Abstract concepts the
+  // map doesn't know about should be added rather than guessed at — a hairline
+  // icon is the safer generic than an over-specific metaphor.
+  return `a minimalist hairline icon representing "${concept.trim()}"`;
+}

package/src/video/motion-overlay/plan.ts

@@ -0,0 +1,111 @@
+/**
+ * Pure motion-overlay plan assembler.
+ *
+ * `buildMotionOverlayPlan` composes a `MotionOverlayPlan` (`schemaVersion: 1`)
+ * from already-computed inputs: the input probe, the resolved style, the take
+ * splits, each take's analysis, and each take's composed prompt. It performs NO
+ * I/O and NO provider/ffmpeg/STT calls — those happen upstream (transcribe,
+ * slice, analyze-reel, compose-prompt) and are passed in. This keeps the
+ * manifest shape deterministic and unit-testable.
+ *
+ * The per-take `file` / `promptFile` paths are the work-folder-relative names
+ * (`takes/…mp4`, `prompts/…md`) the `write.ts` emitter will produce; this module
+ * only names them, it does not write them.
+ */
+
+import type {
+  MotionLayout,
+  MotionOverlayPlan,
+  MotionStyleId,
+  MotionTake,
+  TakeAnalysis,
+  TakeSplit,
+} from './types.js';
+
+export interface BuildMotionOverlayPlanArgs {
+  input: { path: string; durationSeconds: number; width: number; height: number; aspect: string };
+  layout: MotionLayout;
+  style: MotionStyleId;
+  /** Resolved accent (hex or already-resolved name) recorded on the manifest. */
+  accent: string;
+  language: string;
+  /** Work-folder path (absolute or relative; recorded verbatim). */
+  workdir: string;
+  /** The take splits (one per output clip), in order. */
+  splits: TakeSplit[];
+  /** Per-take analysis, parallel to `splits` (keyed by index). */
+  analyses: TakeAnalysis[];
+  /** Per-take composed prompts, parallel to `splits` (keyed by index). */
+  prompts: string[];
+}
+
+/** Build the work-folder-relative take clip filename for a take. */
+export function takeFileName(split: TakeSplit): string {
+  return `takes/${takeStem(split)}.mp4`;
+}
+
+/** Build the work-folder-relative prompt markdown filename for a take. */
+export function takePromptFileName(split: TakeSplit): string {
+  return `prompts/${takeStem(split)}.md`;
+}
+
+/** Shared stem, e.g. `take-01_0s-10s` (1-based index, whole-second bounds). */
+export function takeStem(split: TakeSplit): string {
+  const n = String(split.index + 1).padStart(2, '0');
+  const start = Math.round(split.start);
+  const end = Math.round(split.end);
+  return `take-${n}_${start}s-${end}s`;
+}
+
+/**
+ * Assemble the `MotionOverlayPlan`. Pure. Throws if the analyses/prompts arrays
+ * don't line up with the splits (a programmer error, surfaced loudly).
+ */
+export function buildMotionOverlayPlan(args: BuildMotionOverlayPlanArgs): MotionOverlayPlan {
+  const { splits, analyses, prompts } = args;
+  if (analyses.length !== splits.length) {
+    throw new Error(`buildMotionOverlayPlan: ${splits.length} splits but ${analyses.length} analyses.`);
+  }
+  if (prompts.length !== splits.length) {
+    throw new Error(`buildMotionOverlayPlan: ${splits.length} splits but ${prompts.length} prompts.`);
+  }
+
+  const takes: MotionTake[] = splits.map((split, i) => {
+    const analysis = analyses[i];
+    if (!analysis || analysis.index !== split.index) {
+      throw new Error(`buildMotionOverlayPlan: analysis ${i} does not match split index ${split.index}.`);
+    }
+    const prompt = prompts[i];
+    return {
+      index: split.index,
+      start: split.start,
+      end: split.end,
+      durationSeconds: round(split.end - split.start),
+      file: takeFileName(split),
+      promptFile: takePromptFileName(split),
+      anatomy: analysis.anatomy,
+      prompt,
+    };
+  });
+
+  return {
+    schemaVersion: 1,
+    input: {
+      path: args.input.path,
+      durationSeconds: args.input.durationSeconds,
+      width: args.input.width,
+      height: args.input.height,
+      aspect: args.input.aspect,
+    },
+    layout: args.layout,
+    style: args.style,
+    accent: args.accent,
+    language: args.language,
+    workdir: args.workdir,
+    takes,
+  };
+}
+
+function round(n: number): number {
+  return Math.round(n * 1000) / 1000;
+}

package/src/video/motion-overlay/preview.ts

@@ -0,0 +1,191 @@
+/**
+ * Motion-overlay review surface (Phase 3).
+ *
+ * Renders a finished `MotionOverlayPlan` into a standalone, self-contained
+ * `review/review.html` approval surface — the **contract** the operator signs
+ * off before any provider spend. Each take card shows:
+ *   - the take clip filename + reel beat (anatomy),
+ *   - the take's anatomy / span / duration,
+ *   - the FULL composed prompt that will be sent to Omni Flash V2V verbatim.
+ *
+ * It reuses the preview-portal's `PORTAL_CSS` (including its aspect-aware media
+ * classes via `body[data-aspect]`) for visual consistency, but it does NOT go
+ * through the portal's project-discovery `render.ts` — that surface is driven by
+ * on-disk project assets, whereas motion-overlay renders straight from the
+ * deterministic plan manifest. Pure string assembly except for the single
+ * file write in `writeMotionOverlayReview`.
+ */
+
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { PORTAL_CSS } from '../preview-portal/shared-assets.js';
+import type { MotionOverlayPlan, MotionTake } from './types.js';
+
+export interface RenderMotionOverlayReviewResult {
+  /** Absolute path to the emitted review.html. */
+  reviewPath: string;
+  /** The full rendered HTML (returned for tests / callers that want it inline). */
+  html: string;
+}
+
+/** Human-friendly label for the reel-anatomy beat. */
+const ANATOMY_LABELS: Record<string, string> = {
+  hook: 'Hook',
+  contextualize: 'Contextualize',
+  burst: 'Burst',
+  breath: 'Breath',
+  cta: 'CTA',
+};
+
+/**
+ * Render the plan into the review HTML string. Pure — no I/O. The aspect
+ * (`plan.input.aspect`) drives `body[data-aspect]` so portrait/square clips get
+ * tall cards via PORTAL_CSS's aspect-aware rules.
+ */
+export function renderMotionOverlayReview(plan: MotionOverlayPlan): string {
+  const aspect = plan.input.aspect;
+  const takeCards = plan.takes.map((take) => renderTakeCard(take)).join('\n');
+  const totalDuration = plan.takes.reduce((sum, t) => sum + t.durationSeconds, 0);
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Motion-overlay review — ${esc(layoutTitle(plan))}</title>
+<style>${PORTAL_CSS}${EXTRA_CSS}</style>
+</head>
+<body data-aspect="${escAttr(aspect)}">
+<header class="hero">
+  <div class="eyebrow">motion-overlay review · approve before spend</div>
+  <h1>Motion-overlay plan</h1>
+  <p class="sub">Review each take's clip and the exact prompt that will be sent to Omni Flash V2V. This is the contract — nothing renders until you approve.</p>
+</header>
+
+<div class="stats">
+  <div class="stat"><div class="v">${plan.takes.length}</div><div class="l">Takes</div></div>
+  <div class="stat"><div class="v">${esc(plan.layout)}</div><div class="l">Layout</div></div>
+  <div class="stat"><div class="v">${esc(plan.style)}</div><div class="l">Style</div></div>
+  <div class="stat"><div class="v">${fmt(totalDuration)}s</div><div class="l">Total</div></div>
+</div>
+
+<div class="mo-meta">
+  <span><b>Input</b> ${esc(plan.input.path)}</span>
+  <span><b>Frame</b> ${plan.input.width}×${plan.input.height} (${esc(aspect)})</span>
+  <span><b>Accent</b> <i class="mo-swatch" style="background:${escAttr(plan.accent)}"></i>${esc(plan.accent)}</span>
+  <span><b>Language</b> ${esc(plan.language)}</span>
+</div>
+
+<section data-toc="Takes">
+  <div class="section-head">
+    <h2>Per-take contract</h2>
+    <div class="section-title">${plan.takes.length} take${plan.takes.length === 1 ? '' : 's'}</div>
+    <div class="section-sub">Each card is one Omni Flash V2V generation: the base clip, its reel beat, and the full composed prompt verbatim.</div>
+  </div>
+  <div class="mo-grid">
+${takeCards}
+  </div>
+</section>
+
+<footer>Generated by <code>vclaw video motion-overlay --preview</code>${plan.generatedAt ? ` · ${esc(plan.generatedAt)}` : ''}</footer>
+</body>
+</html>
+`;
+}
+
+/**
+ * Render the plan into `<workdir>/review/review.html` and return its path + html.
+ * Creates the `review/` dir if needed. The only side effect.
+ */
+export async function writeMotionOverlayReview(
+  workdir: string,
+  plan: MotionOverlayPlan,
+): Promise<RenderMotionOverlayReviewResult> {
+  const html = renderMotionOverlayReview(plan);
+  const reviewDir = join(workdir, 'review');
+  await mkdir(reviewDir, { recursive: true });
+  const reviewPath = join(reviewDir, 'review.html');
+  await writeFile(reviewPath, html, 'utf-8');
+  return { reviewPath, html };
+}
+
+/** Render one take card: clip filename, beat, anatomy/span, and full prompt. */
+function renderTakeCard(take: MotionTake): string {
+  const beat = ANATOMY_LABELS[take.anatomy] ?? take.anatomy;
+  const clipName = baseName(take.file);
+  return `    <article class="mo-card" data-card-kind="take" data-card-id="${take.index + 1}">
+      <div class="mo-card-head">
+        <span class="num">TAKE ${String(take.index + 1).padStart(2, '0')}</span>
+        <span class="mo-beat" data-anatomy="${escAttr(take.anatomy)}">${esc(beat)}</span>
+      </div>
+      <div class="mo-clip">
+        <video src="../${escAttr(take.file)}" controls preload="none"></video>
+        <div class="mo-clip-name">${esc(clipName)}</div>
+      </div>
+      <dl class="mo-anatomy">
+        <div><dt>Beat</dt><dd>${esc(beat)}</dd></div>
+        <div><dt>Span</dt><dd>${fmt(take.start)}s → ${fmt(take.end)}s</dd></div>
+        <div><dt>Duration</dt><dd>${fmt(take.durationSeconds)}s</dd></div>
+        <div><dt>Clip</dt><dd><code>${esc(take.file)}</code></dd></div>
+      </dl>
+      <div class="mo-prompt">
+        <div class="mo-prompt-label">Composed prompt (the contract)</div>
+        <pre>${esc(take.prompt)}</pre>
+      </div>
+    </article>`;
+}
+
+/** A short title line summarizing the plan's layout + style. */
+function layoutTitle(plan: MotionOverlayPlan): string {
+  return `${plan.layout} / ${plan.style}`;
+}
+
+function baseName(p: string): string {
+  const i = p.lastIndexOf('/');
+  return i >= 0 ? p.slice(i + 1) : p;
+}
+
+function fmt(seconds: number): string {
+  return (Math.round(seconds * 10) / 10).toFixed(1);
+}
+
+function esc(value: string): string {
+  return value
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;');
+}
+
+function escAttr(value: string): string {
+  return esc(value).replaceAll("'", '&#39;');
+}
+
+/**
+ * Motion-overlay-specific styling layered on top of PORTAL_CSS. Cards are
+ * aspect-aware: the clip <video> inherits PORTAL_CSS's `.card video` aspect
+ * rules via the same `aspect-ratio` defaults, re-stated here for the `.mo-clip`
+ * scope so portrait/square plans render tall clips.
+ */
+const EXTRA_CSS = `
+.mo-meta{display:flex;gap:10px 22px;flex-wrap:wrap;align-items:center;margin:0 0 30px;color:var(--ink2);font-size:12px;font-family:ui-monospace,"SF Mono",monospace}
+.mo-meta b{color:var(--ink3);font-weight:600;letter-spacing:.06em;text-transform:uppercase;font-size:10px;margin-right:6px}
+.mo-swatch{display:inline-block;width:11px;height:11px;border-radius:50%;border:1px solid rgba(255,255,255,.25);margin-right:6px;vertical-align:middle}
+.mo-grid{display:grid;grid-template-columns:repeat(2,1fr);gap:18px}
+.mo-card{background:var(--panel);border:1px solid var(--line);border-radius:14px;overflow:hidden;display:flex;flex-direction:column}
+.mo-card-head{display:flex;align-items:center;justify-content:space-between;padding:13px 16px;border-bottom:1px solid var(--line)}
+.mo-beat{font-size:10px;font-weight:700;letter-spacing:.1em;text-transform:uppercase;color:var(--accent);background:rgba(255,180,84,.12);border:1px solid rgba(255,180,84,.35);border-radius:999px;padding:3px 10px}
+.mo-clip video{width:100%;aspect-ratio:16/9;object-fit:cover;display:block;background:#000}
+.mo-clip-name{padding:8px 16px 0;color:var(--ink3);font-family:ui-monospace,"SF Mono",monospace;font-size:11px;overflow-wrap:anywhere}
+.mo-anatomy{display:grid;grid-template-columns:repeat(2,1fr);gap:8px 16px;padding:14px 16px;margin:0}
+.mo-anatomy>div{display:flex;flex-direction:column;gap:2px}
+.mo-anatomy dt{font-size:9px;font-weight:700;letter-spacing:.12em;text-transform:uppercase;color:var(--ink3)}
+.mo-anatomy dd{font-size:12px;color:var(--ink);margin:0;overflow-wrap:anywhere}
+.mo-anatomy code{font-family:ui-monospace,"SF Mono",monospace;font-size:11px;color:var(--ink2)}
+.mo-prompt{border-top:1px solid var(--line);padding:14px 16px}
+.mo-prompt-label{font-size:9px;font-weight:700;letter-spacing:.14em;text-transform:uppercase;color:var(--accent);margin-bottom:8px}
+.mo-prompt pre{white-space:pre-wrap;overflow-wrap:anywhere;font-family:ui-monospace,"SF Mono",monospace;font-size:11px;line-height:1.6;color:var(--ink2);background:#0c0c11;border:1px solid var(--line);border-radius:8px;padding:12px 14px;max-height:none}
+body[data-aspect="9:16"] .mo-clip video{aspect-ratio:9/16;width:auto;max-width:100%;max-height:70vh;margin:0 auto}
+body[data-aspect="1:1"] .mo-clip video{aspect-ratio:1/1}
+@media(max-width:900px){.mo-grid{grid-template-columns:1fr}}
+`;