@vosjs/cli 0.54.2 → 0.55.1

package/dist/{chunk-MTOCJ2LC.js → chunk-FQA7LFXG.js}

@@ -99,8 +99,8 @@ function landedLines(l) {
 
 // src/plugin/run.ts
 import { mkdir as mkdir11, readFile as readFile17, rm as rm5 } from "fs/promises";
-import { existsSync as existsSync23 } from "fs";
-import { join as join27, resolve as resolve15 } from "path";
+import { existsSync as existsSync24 } from "fs";
+import { join as join28, resolve as resolve15 } from "path";
 import {
   END_CARD_FROM as END_CARD_FROM2,
   docOutputDuration as docOutputDuration3,
@@ -9235,28 +9235,350 @@ async function cmdCompare(argv) {
 }
 
 // src/plugin/port.ts
-import { existsSync as existsSync19, mkdirSync as mkdirSync5, readFileSync as readFileSync6, writeFileSync as writeFileSync5 } from "fs";
-import { dirname as dirname8, join as join23, resolve as resolve11 } from "path";
+import { existsSync as existsSync20, mkdirSync as mkdirSync5, readFileSync as readFileSync7, writeFileSync as writeFileSync5 } from "fs";
+import { dirname as dirname8, join as join24, resolve as resolve11 } from "path";
 import { pathToFileURL as pathToFileURL3 } from "url";
 
 // src/plugin/portInventory.ts
 import { spawnSync as spawnSync2 } from "child_process";
 import {
-  existsSync as existsSync17,
+  existsSync as existsSync18,
   mkdirSync as mkdirSync3,
-  readFileSync as readFileSync5,
-  readdirSync as readdirSync4,
-  statSync as statSync5
+  readFileSync as readFileSync6,
+  readdirSync as readdirSync5,
+  statSync as statSync6
 } from "fs";
-import { dirname as dirname6, join as join21, relative as relative2, resolve as resolve9 } from "path";
+import { dirname as dirname6, join as join22, relative as relative2, resolve as resolve9 } from "path";
 import { pathToFileURL as pathToFileURL2 } from "url";
 import { findFontFamily as findFontFamily3 } from "@vosjs/shared";
+
+// src/plugin/portRemotion.ts
+import { existsSync as existsSync17, readFileSync as readFileSync5, readdirSync as readdirSync4, statSync as statSync5 } from "fs";
+import { createServer as createServer2 } from "http";
+import { createRequire } from "module";
+import { basename as basename7, extname as extname3, join as join21 } from "path";
+function themeColors(sources) {
+  const out = {};
+  const re = /\bconst\s+([A-Za-z_$][\w$]*)\s*(?::\s*string\s*)?=\s*['"](#[0-9a-fA-F]{3,8})['"]/g;
+  for (const src of sources)
+    for (const m of src.matchAll(re)) {
+      const key = m[1].toLowerCase().replace(/_([a-z0-9])/g, (_, c) => c.toUpperCase());
+      if (!(key in out)) out[key] = m[2].toLowerCase();
+    }
+  return out;
+}
+function remotionScenes(seqs, fps) {
+  const seen = /* @__PURE__ */ new Map();
+  const live = seqs.filter((s) => s.durationInFrames > 0);
+  const overlaps2 = (a, b) => a.from < b.from + b.durationInFrames && b.from < a.from + a.durationInFrames;
+  return live.filter(
+    (s) => !live.some(
+      (o) => o !== s && o.durationInFrames > s.durationInFrames && overlaps2(o, s)
+    )
+  ).sort((a, b) => a.from - b.from).map((s, i) => {
+    const base = s.name ?? `scene${i + 1}`;
+    const n = (seen.get(base) ?? 0) + 1;
+    seen.set(base, n);
+    return {
+      name: n > 1 ? `${base}${n}` : base,
+      start: Math.round(s.from / fps * 1e3) / 1e3,
+      duration: Math.round(s.durationInFrames / fps * 1e3) / 1e3
+    };
+  });
+}
+function mergeSceneTexts(perScene) {
+  const sig = (t) => `${t.text}|${t.font.family}|${t.font.size}|${t.box ? `${Math.round(t.box.x / 8)},${Math.round(t.box.y / 8)}` : "-"}`;
+  const counts = /* @__PURE__ */ new Map();
+  for (const s of perScene)
+    for (const k of new Set(s.texts.map(sig)))
+      counts.set(k, (counts.get(k) ?? 0) + 1);
+  const global = perScene.length >= 3 ? Math.ceil(perScene.length / 2) : Infinity;
+  const out = [];
+  const placed = /* @__PURE__ */ new Set();
+  const textPlaced = /* @__PURE__ */ new Set();
+  for (const s of perScene)
+    for (const t of s.texts) {
+      const k = sig(t);
+      const shared = (counts.get(k) ?? 0) >= global;
+      const id = shared ? k : `${s.scene}|${k}`;
+      if (placed.has(id)) continue;
+      const shape = `${t.text.replace(/\d/g, "0")}|${t.font.family}|${t.box ? Math.round(t.box.y / 8) : "-"}`;
+      if (/\d/.test(t.text) && textPlaced.has(shape)) continue;
+      placed.add(id);
+      textPlaced.add(shape);
+      out.push({
+        ...t,
+        id: `${t.id}-${out.length}`,
+        scene: shared ? null : s.scene
+      });
+    }
+  return out;
+}
+function sourceTexts(dir) {
+  const out = [];
+  const walk = (d, depth) => {
+    if (depth > 4 || out.length > 200) return;
+    for (const name of readdirSync4(d)) {
+      if (name === "node_modules" || name.startsWith(".")) continue;
+      const p = join21(d, name);
+      if (statSync5(p).isDirectory()) walk(p, depth + 1);
+      else if (/\.(tsx?|jsx?|mjs)$/.test(name))
+        out.push(readFileSync5(p, "utf8"));
+    }
+  };
+  const src = join21(dir, "src");
+  walk(existsSync17(src) ? src : dir, 0);
+  return out;
+}
+function entryPoint(dir) {
+  for (const p of [
+    "src/index.ts",
+    "src/index.tsx",
+    "src/index.js",
+    "src/index.jsx",
+    "remotion/index.ts",
+    "remotion/index.tsx"
+  ])
+    if (existsSync17(join21(dir, p))) return join21(dir, p);
+  return null;
+}
+var TYPES = {
+  ".html": "text/html",
+  ".js": "text/javascript",
+  ".css": "text/css",
+  ".json": "application/json",
+  ".woff2": "font/woff2",
+  ".woff": "font/woff",
+  ".ttf": "font/ttf",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".svg": "image/svg+xml",
+  ".wav": "audio/wav",
+  ".mp3": "audio/mpeg",
+  ".ogg": "audio/ogg",
+  ".mp4": "video/mp4",
+  ".webm": "video/webm"
+};
+var INIT = `(() => {
+  window.remotion_puppeteerTimeout = 30000
+  window.remotion_isMainTab = true
+  window.remotion_mediaCacheSizeInBytes = 100000000
+  window.remotion_initialMemoryAvailable = 1000000000
+  window.remotion_sampleRate = 48000
+  window.process = window.process || {}
+  window.process.env = window.process.env || {}
+  window.process.env.NODE_ENV = 'production'
+  window.remotion_envVariables = '{}'
+  window.remotion_inputProps = '{}'
+  window.remotion_initialFrame = 0
+  window.remotion_attempt = 1
+  window.remotion_audioEnabled = false
+  window.remotion_videoEnabled = false
+  window.remotion_logLevel = 'error'
+})()`;
+var READ_TREE = `(() => {
+  let fiber = null
+  for (const el of document.querySelectorAll('body, body *')) {
+    const k = Object.keys(el).find((k) => k.startsWith('__reactFiber$') || k.startsWith('__reactContainer$'))
+    if (k) { fiber = el[k]; break }
+  }
+  while (fiber && fiber.return) fiber = fiber.return
+  const nameOf = (t) => t && (t.displayName || t.name || (t.render && (t.render.displayName || t.render.name))) || null
+  const internal = /^(Sequence|AbsoluteFill|Freeze|Loop|Series|Fragment)$|Provider|Context|Forwarding|^Inner/
+  const seqs = []
+  const audio = []
+  const walk = (f, offset) => {
+    for (let x = f; x; x = x.sibling) {
+      const name = nameOf(x.elementType)
+      const p = x.memoizedProps || {}
+      let next = offset
+      if (name === 'Sequence' && typeof p.from === 'number') {
+        next = offset + p.from
+        if (typeof p.durationInFrames === 'number' && isFinite(p.durationInFrames)) {
+          const kids = Array.isArray(p.children) ? p.children : [p.children]
+          const held = kids.map((k) => k && nameOf(k.type)).find((n) => n && !internal.test(n))
+          seqs.push({ from: next, durationInFrames: p.durationInFrames, name: p.name || held || null })
+        }
+      }
+      if (name && /Audio$/.test(name) && typeof p.src === 'string')
+        audio.push({ src: p.src, from: next, volume: typeof p.volume === 'number' ? p.volume : null, startFrom: typeof p.startFrom === 'number' ? p.startFrom : (typeof p.trimBefore === 'number' ? p.trimBefore : null) })
+      if (x.child) walk(x.child, next)
+    }
+  }
+  walk(fiber, 0)
+  // Nested sequences repeat their parent's window at the same offset: keep the outermost.
+  const seen = new Set()
+  return { seqs: seqs.filter((s) => { const k = s.from + ':' + s.durationInFrames; if (seen.has(k)) return false; seen.add(k); return true }), audio }
+})()`;
+async function readRemotion(dir, log) {
+  const entry = entryPoint(dir);
+  let bundler;
+  try {
+    bundler = createRequire(join21(dir, "package.json"))("@remotion/bundler");
+  } catch {
+    log?.(
+      "a Remotion project whose dependencies are not installed: run `npm install` in it so vos can read its compositions (words, scenes, faces); reading only the render"
+    );
+    return null;
+  }
+  if (!entry) {
+    log?.(
+      "a Remotion project with no src/index entry (registerRoot): reading only the render"
+    );
+    return null;
+  }
+  const out = await bundler.bundle({ entryPoint: entry, onProgress: () => {
+  } });
+  const server = createServer2((rq, rs) => {
+    const path = decodeURIComponent(new URL(rq.url ?? "/", "http://x").pathname);
+    let f = join21(out, path);
+    if (!f.startsWith(out) || !existsSync17(f) || statSync5(f).isDirectory())
+      f = join21(out, "index.html");
+    rs.writeHead(200, {
+      "content-type": TYPES[extname3(f)] ?? "application/octet-stream"
+    });
+    rs.end(readFileSync5(f));
+  }).listen(0, "127.0.0.1");
+  await new Promise((r) => server.once("listening", r));
+  const port = server.address().port;
+  const browser = await launchBrowser();
+  try {
+    const ctx = await browser.newContext({
+      viewport: { width: 1920, height: 1080 }
+    });
+    const p = await ctx.newPage();
+    await p.addInitScript(INIT);
+    await p.goto(`http://127.0.0.1:${port}/index.html`);
+    await p.waitForFunction(
+      'typeof window.getStaticCompositions === "function"',
+      null,
+      { timeout: 3e4 }
+    );
+    await p.evaluate("window.remotion_setBundleMode({ type: 'evaluation' })");
+    await p.waitForFunction("window.remotion_renderReady === true", null, {
+      timeout: 3e4
+    });
+    const comps = await p.evaluate("window.getStaticCompositions()");
+    if (!comps.length) {
+      log?.(
+        "the Remotion project registers no composition: reading only the render"
+      );
+      return null;
+    }
+    const c = comps[0];
+    if (comps.length > 1)
+      log?.(`${comps.length} compositions; reading the first, ${c.id}`);
+    await p.setViewportSize({ width: c.width, height: c.height });
+    await p.evaluate(
+      `window.remotion_setBundleMode(${JSON.stringify({
+        type: "composition",
+        compositionName: c.id,
+        serializedResolvedPropsWithSchema: JSON.stringify(c.defaultProps ?? {}),
+        compositionDurationInFrames: c.durationInFrames,
+        compositionFps: c.fps,
+        compositionHeight: c.height,
+        compositionWidth: c.width,
+        compositionDefaultCodec: null,
+        compositionDefaultOutName: null,
+        compositionDefaultVideoImageFormat: null,
+        compositionDefaultPixelFormat: null,
+        compositionDefaultProResProfile: null,
+        compositionDefaultSampleRate: null
+      })})`
+    );
+    await p.waitForFunction("window.remotion_renderReady === true", null, {
+      timeout: 3e4
+    });
+    const seek = async (frame) => {
+      await p.evaluate(
+        `window.remotion_setFrame(${frame}, ${JSON.stringify(c.id)}, 1)`
+      );
+      await p.waitForFunction("window.remotion_renderReady === true", null, {
+        timeout: 3e4
+      });
+      await p.evaluate("document.fonts && document.fonts.ready");
+    };
+    await seek(0);
+    const tree = await p.evaluate(READ_TREE);
+    let scenes = remotionScenes(tree.seqs, c.fps);
+    const total = c.durationInFrames / c.fps;
+    if (!scenes.length) scenes = [{ name: c.id, start: 0, duration: total }];
+    const perScene = [];
+    let first = null;
+    const colors = /* @__PURE__ */ new Set();
+    const gaps = /* @__PURE__ */ new Set();
+    for (const s of scenes) {
+      const frame = Math.min(
+        c.durationInFrames - 1,
+        Math.round((s.start + s.duration * 0.9) * c.fps)
+      );
+      await seek(frame);
+      const read = await p.evaluate(READ_PAGE);
+      const unboxed = read.texts.filter((t) => !t.box);
+      if (unboxed.length) {
+        await seek(Math.round((s.start + s.duration * 0.5) * c.fps));
+        const mid = await p.evaluate(READ_PAGE);
+        for (const t of unboxed) {
+          const m = mid.texts.find(
+            (x) => x.box && x.text === t.text && x.font.family === t.font.family
+          );
+          if (m) t.box = m.box;
+        }
+      }
+      s.ground = await p.evaluate(READ_GROUND);
+      first ??= read;
+      for (const x of read.colors ?? []) colors.add(x);
+      for (const g of read.gaps ?? []) gaps.add(g);
+      perScene.push({ scene: s.name, texts: read.texts ?? [] });
+    }
+    const publicDir = join21(dir, "public");
+    const media = tree.audio.map((a) => {
+      const name = basename7(a.src.split("?")[0]);
+      const local = existsSync17(join21(publicDir, name)) ? `public/${name}` : a.src;
+      return {
+        kind: "audio",
+        src: local,
+        start: Math.round(a.from / c.fps * 1e3) / 1e3,
+        duration: null,
+        volume: a.volume,
+        mediaStart: a.startFrom != null ? Math.round(a.startFrom / c.fps * 1e3) / 1e3 : null
+      };
+    });
+    return {
+      width: c.width,
+      height: c.height,
+      fps: c.fps,
+      duration: Math.round(total * 1e3) / 1e3,
+      texts: mergeSceneTexts(perScene),
+      palette: themeColors(sourceTexts(dir)),
+      colors: [...colors],
+      gaps: [...gaps],
+      media,
+      canvases: first?.canvases ?? [],
+      scenes,
+      sceneEls: [],
+      variables: c.defaultProps ?? {},
+      scriptText: "",
+      composition: c.id
+    };
+  } catch (e) {
+    log?.(
+      `the Remotion bundle did not mount (${e instanceof Error ? e.message.split("\n")[0] : String(e)}): reading only the render`
+    );
+    return null;
+  } finally {
+    await browser.close();
+    server.close();
+  }
+}
+
+// src/plugin/portInventory.ts
 function detectEngine(dir) {
-  if (existsSync17(join21(dir, "hyperframes.json"))) return "hyperframes";
-  const pkg = join21(dir, "package.json");
-  if (existsSync17(pkg)) {
+  if (existsSync18(join22(dir, "hyperframes.json"))) return "hyperframes";
+  const pkg = join22(dir, "package.json");
+  if (existsSync18(pkg)) {
     try {
-      const p = JSON.parse(readFileSync5(pkg, "utf8"));
+      const p = JSON.parse(readFileSync6(pkg, "utf8"));
       const deps = { ...p.dependencies ?? {}, ...p.devDependencies ?? {} };
       if ("remotion" in deps) return "remotion";
       if ("hyperframes" in deps) return "hyperframes";
@@ -9268,14 +9590,14 @@ function detectEngine(dir) {
   return "page";
 }
 function sourcePage(source) {
-  if (!existsSync17(source)) return null;
-  if (statSync5(source).isFile()) return /\.html?$/i.test(source) ? source : null;
-  const index = join21(source, "index.html");
-  return existsSync17(index) ? index : null;
+  if (!existsSync18(source)) return null;
+  if (statSync6(source).isFile()) return /\.html?$/i.test(source) ? source : null;
+  const index = join22(source, "index.html");
+  return existsSync18(index) ? index : null;
 }
 function findRender(dir) {
-  const videos = (d) => existsSync17(d) ? readdirSync4(d).filter((f) => /\.(mp4|webm|mov)$/i.test(f)).map((f) => join21(d, f)) : [];
-  for (const d of [join21(dir, "renders"), join21(dir, "out"), dir]) {
+  const videos = (d) => existsSync18(d) ? readdirSync5(d).filter((f) => /\.(mp4|webm|mov)$/i.test(f)).map((f) => join22(d, f)) : [];
+  for (const d of [join22(dir, "renders"), join22(dir, "out"), dir]) {
     const found = videos(d);
     if (found.length) return found[0];
   }
@@ -9385,31 +9707,68 @@ var READ_PAGE = `(() => {
   const sx = rootRect.width ? width / rootRect.width : 1
   const sy = rootRect.height ? height / rootRect.height : 1
 
+  // The faces that actually render: a family loaded only italic, or only at
+  // one weight, draws that face whatever the CSS asked for.
+  const loaded = {}
+  if (document.fonts) for (const f of document.fonts) {
+    if (f.status !== 'loaded') continue
+    const fam = f.family.replace(/^["']|["']$/g, '')
+    const e = loaded[fam] || (loaded[fam] = { styles: new Set(), weights: new Set() })
+    e.styles.add(f.style)
+    const w = Number(f.weight)
+    if (Number.isFinite(w)) e.weights.add(w)
+  }
+  const renderedFace = (fam, style, weight) => {
+    const e = loaded[fam]
+    if (!e) return { style, weight }
+    const st = e.styles.has(style) ? style : style === 'normal' && e.styles.has('italic') ? 'italic' : style
+    const ws = [...e.weights]
+    const wt = !ws.length || ws.includes(weight) ? weight : ws.reduce((a, b) => (Math.abs(b - weight) < Math.abs(a - weight) ? b : a))
+    return { style: st, weight: wt }
+  }
   const texts = []
   const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT)
   const seen = new Set()
   let n = 0
   while (walker.nextNode()) {
     const node = walker.currentNode
-    const text = (node.textContent || '').replace(/\\s+/g, ' ').trim()
-    const el = node.parentElement
-    if (!text || !el || ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TITLE'].includes(el.tagName)) continue
-    if (seen.has(el)) continue
-    seen.add(el)
-    const cs = getComputedStyle(el)
-    const r = el.getBoundingClientRect()
+    let el = node.parentElement
+    if (!el || !(node.textContent || '').trim() || el.closest('script, style, noscript, title')) continue
+    // A word animated letter by letter is one span per glyph: read the word,
+    // once, as a split word, never as its letters.
+    let split = null
+    const glyphs = (a) => a && a.children.length >= 3 && [...a.childNodes].every((c) => c.nodeType === 1 ? (c.textContent || '').trim().length <= 2 : !(c.textContent || '').trim())
+    for (let a = el.parentElement, up = 0; a && up < 3; a = a.parentElement, up++) {
+      if (glyphs(a)) { el = a; split = 'chars'; break }
+    }
+    // A line with a styled word inside it ("TYPE <span>that</span> MOVES")
+    // is read run by run, each with its own box, or the runs after the
+    // first are lost.
+    const mixed = !split && [...el.children].some((c) => (c.textContent || '').trim())
+    const unit = mixed ? node : el
+    if (seen.has(unit)) continue
+    seen.add(unit)
+    const text = ((mixed ? node.textContent : el.textContent) || '').replace(/\\s+/g, ' ').trim()
+    if (!text) continue
+    // A split word wears its letters' face, never its container's.
+    const cs = getComputedStyle(split ? node.parentElement : el)
+    let r
+    if (mixed) { const range = document.createRange(); range.selectNodeContents(node); r = range.getBoundingClientRect() }
+    else r = el.getBoundingClientRect()
     const box = r.width && r.height ? {
       x: Math.round((r.left - rootRect.left) * sx), y: Math.round((r.top - rootRect.top) * sy),
       width: Math.round(r.width * sx), height: Math.round(r.height * sy) } : null
     const ls = parseFloat(cs.letterSpacing)
-    el.setAttribute('data-vos-inv', String(texts.length))
+    if (!mixed) el.setAttribute('data-vos-inv', String(texts.length))
     const sceneEl = el.closest('.scene, [data-scene], section[id]')
+    const fam = cs.fontFamily.split(',')[0].trim().replace(/^["']|["']$/g, '')
+    const face = renderedFace(fam, cs.fontStyle, Number(cs.fontWeight) || 400)
     texts.push({
-      id: el.id || (el.className && typeof el.className === 'string' ? el.className.split(' ')[0] : '') || el.tagName.toLowerCase() + '-' + (n++),
-      text, tag: el.tagName.toLowerCase(), box, scene: sceneEl && sceneEl.id ? sceneEl.id : null,
-      font: { family: cs.fontFamily.split(',')[0].trim().replace(/^["']|["']$/g, ''),
-        size: Math.round(parseFloat(cs.fontSize) * sy), weight: Number(cs.fontWeight) || 400,
-        style: cs.fontStyle, color: cs.color, letterSpacing: Number.isFinite(ls) ? Math.round(ls * sy * 100) / 100 : 0,
+      id: (mixed ? '' : el.id || (el.className && typeof el.className === 'string' ? el.className.split(' ')[0] : '')) || el.tagName.toLowerCase() + '-' + (n++),
+      text, tag: el.tagName.toLowerCase(), box, scene: sceneEl && sceneEl.id ? sceneEl.id : null, split,
+      font: { family: fam,
+        size: Math.round(parseFloat(cs.fontSize) * sy), weight: face.weight,
+        style: face.style, color: cs.color, letterSpacing: Number.isFinite(ls) ? Math.round(ls * sy * 100) / 100 : 0,
         transform: cs.textTransform },
     })
   }
@@ -9463,6 +9822,24 @@ var READ_PAGE = `(() => {
     texts, palette, colors: [...colors], gaps: [...gaps], media, canvases, scenes, sceneEls, variables, scriptText,
   }
 })()`;
+var READ_GROUND = `(() => {
+  const W = innerWidth, H = innerHeight
+  const counts = {}
+  for (const [px, py] of [[0.5, 0.5], [0.06, 0.06], [0.94, 0.94], [0.06, 0.94], [0.94, 0.06]]) {
+    for (const el of document.elementsFromPoint(px * W, py * H)) {
+      const cs = getComputedStyle(el)
+      const bg = cs.backgroundColor
+      if (!bg || bg === 'transparent' || /rgba\\([^)]*,\\s*0\\)$/.test(bg)) continue
+      const r = el.getBoundingClientRect()
+      if (r.width < W * 0.9 || r.height < H * 0.9 || Number(cs.opacity) < 0.99) continue
+      counts[bg] = (counts[bg] || 0) + 1
+      break
+    }
+  }
+  let best = null
+  for (const k in counts) if (!best || counts[k] > counts[best]) best = k
+  return best
+})()`;
 var SEEK_AND_READ = `((args) => {
   const tls = window.__timelines ? Object.values(window.__timelines) : []
   if (!tls.length) return null
@@ -9482,7 +9859,7 @@ var SEEK_AND_READ = `((args) => {
 })`;
 async function readInventory(source, opts) {
   const abs = resolve9(source);
-  const dir = existsSync17(abs) && statSync5(abs).isDirectory() ? abs : dirname6(abs);
+  const dir = existsSync18(abs) && statSync6(abs).isDirectory() ? abs : dirname6(abs);
   const engine = detectEngine(dir);
   const page = sourcePage(abs);
   const render = opts.render === void 0 ? findRender(dir) : opts.render;
@@ -9527,12 +9904,15 @@ async function readInventory(source, opts) {
       if (scripted.length > (read.scenes?.length ?? 0)) read.scenes = scripted;
       for (const s of read.scenes) {
         const indices = read.texts.map((t2, i) => t2.scene === s.name ? i : -1).filter((i) => i >= 0);
-        if (!indices.length) continue;
         const t = s.start + (s.duration ?? 1) * 0.75;
         const boxes = await p.evaluate(
           `${SEEK_AND_READ}(${JSON.stringify({ t, indices, width: read.width, height: read.height })})`
         );
-        if (!boxes) break;
+        if (!boxes)
+          break;
+        s.ground = await p.evaluate(
+          READ_GROUND
+        );
         for (const [i, box] of Object.entries(boxes)) {
           read.texts[Number(i)].box = box;
           settled++;
@@ -9543,9 +9923,15 @@ async function readInventory(source, opts) {
       await browser.close();
     }
   } else if (engine === "remotion") {
-    opts.log?.(
-      "a Remotion project: its words and colours live in its source (src/), which the agent reads; the inventory records the render and its stills"
-    );
+    const r = await readRemotion(dir, opts.log);
+    if (r) {
+      read = r;
+      fps = r.fps ?? fps;
+      duration = r.duration ?? duration;
+      opts.log?.(
+        `read the Remotion composition ${String(r.composition)} in its own bundle: ${r.scenes.length} sequences as scenes, the words where they settle in each`
+      );
+    }
   }
   if (settled)
     opts.log?.(
@@ -9576,7 +9962,7 @@ async function readInventory(source, opts) {
   if (render && duration) {
     const has = spawnSync2("ffmpeg", ["-version"]).status === 0;
     if (has) {
-      const refDir = join21(opts.outDir, "ref");
+      const refDir = join22(opts.outDir, "ref");
       mkdirSync3(refDir, { recursive: true });
       const times = read.scenes.length >= 3 ? read.scenes.map(
         (s) => s.start + (s.duration ?? 1) / 2
@@ -9585,7 +9971,7 @@ async function readInventory(source, opts) {
         (_, i) => i + 0.5
       );
       for (const t of times.filter((t2) => t2 < duration)) {
-        const file = join21(refDir, `src-${t.toFixed(2)}.png`);
+        const file = join22(refDir, `src-${t.toFixed(2)}.png`);
         const ok = spawnSync2("ffmpeg", [
           "-v",
           "error",
@@ -9638,8 +10024,8 @@ async function readInventory(source, opts) {
 
 // src/plugin/portScaffold.ts
 import { spawnSync as spawnSync3 } from "child_process";
-import { copyFileSync, existsSync as existsSync18, mkdirSync as mkdirSync4, writeFileSync as writeFileSync4 } from "fs";
-import { basename as basename7, dirname as dirname7, join as join22, resolve as resolve10 } from "path";
+import { copyFileSync, existsSync as existsSync19, mkdirSync as mkdirSync4, writeFileSync as writeFileSync4 } from "fs";
+import { basename as basename8, dirname as dirname7, join as join23, resolve as resolve10 } from "path";
 import { findFontFamily as findFontFamily4, fontFaceUrl, nearestFontWeight } from "@vosjs/shared";
 var DESIGN_HEIGHT = 1080;
 function toHex(css) {
@@ -9728,6 +10114,7 @@ function planScaffold(inv, opts) {
       id: key,
       type: "text",
       content: { $data: key },
+      ...t.split ? { split: { type: t.split } } : {},
       position: t.box ? { x: fmtPct(t.box.x / inv.width), y: fmtPct(t.box.y / inv.height) } : "center",
       font: {
         family,
@@ -9802,6 +10189,7 @@ function planScaffold(inv, opts) {
   data.scenes = inv.scenes.map((s) => ({
     name: s.name,
     at: s.start,
+    ...s.ground ? { ground: colorOf(s.ground) } : {},
     until: s.duration == null ? null : Math.round((s.start + s.duration) * 1e3) / 1e3
   }));
   data.sceneElements = sceneElements;
@@ -9848,8 +10236,8 @@ function planScaffold(inv, opts) {
   const copies = [];
   inv.media.filter((m) => m.kind === "audio" && m.src).forEach((m, i) => {
     const from = resolve10(opts.sourceDir, m.src);
-    const name = basename7(from);
-    if (!existsSync18(from)) {
+    const name = basename8(from);
+    if (!existsSync19(from)) {
       report.push(
         `- the audio ${m.src} is not in the source folder; add it to doc.json by hand`
       );
@@ -9977,7 +10365,9 @@ export default {
       tl.addLabel(s.name, s.at)
       // Each scene's words show in its window; the motion replaces this.
       for (const id of ctx.data.sceneElements[s.name] || []) {
-        const p = ctx.elements.get(id).props
+        // A split word's units carry their own opacity: hide the units.
+        const el = ctx.elements.get(id)
+        const p = el.segments && el.segments.length ? el.segments : el.props
         if (s.at > 0) {
           tl.set(p, { opacity: 0 }, 0)
           tl.set(p, { opacity: 1 }, s.at)
@@ -9991,20 +10381,25 @@ ${sceneTodos}
   },
 
   onFrame(ctx, content) {
-    ctx.scene.background.set(ctx.data.bg)${painterFrame}
+    // Each scene's ground, by its palette key; the frame's own colour between them.
+    let ground = ctx.data.bg
+    for (const s of ctx.data.scenes)
+      if (s.ground && ctx.time >= s.at && (s.until == null || ctx.time < s.until))
+        ground = ctx.data[s.ground] ?? ground
+    ctx.scene.background.set(ground)${painterFrame}
   },
 }
 `;
 }
 function reportText(inv, r) {
   const lines = [
-    `# Port report: ${inv.source}`,
+    `# Port report: ${inv.source === "." && inv.root ? basename8(inv.root) : inv.source}`,
     "",
     `${inv.engine} piece, ${inv.width}\xD7${inv.height}${inv.fps ? ` at ${inv.fps} fps` : ""}, ${inv.duration ?? "?"} s. A program has no size of its own: render it with \`--width ${inv.width} --height ${inv.height}\`.`,
     "",
     "## Placed",
     "",
-    `- ${r.elements} words as bound text elements, ${Object.keys(inv.palette).length} palette colours from the source's custom properties, ${r.params} knobs.`,
+    `- ${r.elements} words as bound text elements, ${Object.keys(inv.palette).length} palette colours the source names (its custom properties or colour constants), ${r.params} knobs.`,
     `- ${inv.scenes.length} scenes as labels${inv.scenes.length ? "" : " (none declared: name them as you translate)"}.`,
     ...r.scores.length ? [
       `- the score as a doc.json track (${r.scores.join(", ")}, copied beside the program; vos push uploads it).`
@@ -10043,20 +10438,20 @@ function reportText(inv, r) {
     "",
     "## Reference",
     "",
-    inv.render ? `The source's render: ${inv.render}. Stills in port/ref/. Check every scene: \`npx vos compare . --against ${inv.render}\`.` : "No render of the source was found: render it with its own tool and pass it to `vos compare --against`.",
+    inv.render ? `The source's render: ${inv.render}. Stills in port/ref/. Check every scene, from where the inventory ran: \`npx vos compare port/program --against ${inv.render}\`.` : "No render of the source was found: render it with its own tool and pass it to `vos compare --against`.",
     ""
   ];
   return lines.join("\n");
 }
 function writeScaffold(plan, outDir) {
   mkdirSync4(outDir, { recursive: true });
-  writeFileSync4(join22(outDir, "program.mjs"), plan.program);
+  writeFileSync4(join23(outDir, "program.mjs"), plan.program);
   writeFileSync4(
-    join22(outDir, "doc.json"),
+    join23(outDir, "doc.json"),
     JSON.stringify(plan.doc, null, 2) + "\n"
   );
-  writeFileSync4(join22(dirname7(outDir), "REPORT.md"), plan.report);
-  for (const [from, name] of plan.copies) copyFileSync(from, join22(outDir, name));
+  writeFileSync4(join23(dirname7(outDir), "REPORT.md"), plan.report);
+  for (const [from, name] of plan.copies) copyFileSync(from, join23(outDir, name));
 }
 function probeAudioDuration(file) {
   const res = spawnSync3(
@@ -10090,7 +10485,7 @@ async function inventory(argv) {
     outDir,
     log: (l) => r.log(`note: ${l}`)
   });
-  const file = join23(outDir, "inventory.json");
+  const file = join24(outDir, "inventory.json");
   writeFileSync5(file, JSON.stringify(inv, null, 2) + "\n");
   const missing = inv.fonts.filter((f) => !f.catalog).map((f) => f.family);
   r.log(
@@ -10122,32 +10517,32 @@ function summary(inv) {
 async function scaffold(argv) {
   const { flags } = parseArgs(argv, BOOLEAN_FLAGS7);
   const r = createReporter(flags.json === true);
-  const from = resolve11(strFlag(flags, "from") ?? join23("port", "inventory.json"));
-  if (!existsSync19(from))
+  const from = resolve11(strFlag(flags, "from") ?? join24("port", "inventory.json"));
+  if (!existsSync20(from))
     throw new UsageError(
       `no inventory at ${from}: run npx vos port inventory <source> first`
     );
-  const inv = JSON.parse(readFileSync6(from, "utf8"));
+  const inv = JSON.parse(readFileSync7(from, "utf8"));
   const outDir = resolve11(
-    strFlag(flags, "out") ?? join23(dirname8(from), "program")
+    strFlag(flags, "out") ?? join24(dirname8(from), "program")
   );
   const plan = planScaffold(inv, {
     sourceDir: scaffoldSourceDir(inv),
     probeDuration: probeAudioDuration
   });
   writeScaffold(plan, outDir);
-  const programFile = join23(outDir, "program.mjs");
+  const programFile = join24(outDir, "program.mjs");
   const mod = await import(`${pathToFileURL3(programFile).href}?t=${Date.now()}`);
   const built = buildProgram(mod.default, "program.mjs", plan.program);
   for (const p of built.problems) r.log(`error ${p.fn}: ${p.message}`);
   if (built.problems.length) return EXIT_ERROR;
   writeFileSync5(
-    join23(outDir, "config.json"),
+    join24(outDir, "config.json"),
     JSON.stringify(built.config, null, 2) + "\n"
   );
   r.done(
-    { program: outDir, report: join23(dirname8(outDir), "REPORT.md") },
-    `Wrote ${outDir}/program.mjs, config.json and doc.json, and ${join23(dirname8(outDir), "REPORT.md")}. Translate the motion where it says TODO, then: npx vos build program.mjs && npx vos compare . --against <their render>`
+    { program: outDir, report: join24(dirname8(outDir), "REPORT.md") },
+    `Wrote ${outDir}/program.mjs, config.json and doc.json, and ${join24(dirname8(outDir), "REPORT.md")}. Translate the motion where it says TODO, then: npx vos build program.mjs && npx vos compare . --against <their render>`
   );
   return EXIT_OK;
 }
@@ -10157,12 +10552,12 @@ function scaffoldSourceDir(inv) {
 }
 
 // src/plugin/recipe.ts
-import { readFileSync as readFileSync7 } from "fs";
-import { basename as basename8 } from "path";
+import { readFileSync as readFileSync8 } from "fs";
+import { basename as basename9 } from "path";
 var BOOLEAN_FLAGS8 = /* @__PURE__ */ new Set(["json", "help"]);
 var USAGE = "vos recipe push <file.md> (--folder <folderId|slug> | --asset <assetId>)";
 function recipeFilename(file) {
-  const name = basename8(file);
+  const name = basename9(file);
   if (!/\.md$/i.test(name)) {
     throw new UsageError(`a recipe is a markdown file \u2014 ${name} is not .md`);
   }
@@ -10177,7 +10572,7 @@ async function cmdPush2(argv) {
     throw new UsageError(USAGE);
   }
   const filename = recipeFilename(file);
-  const body = readFileSync7(file);
+  const body = readFileSync8(file);
   const r = createReporter(flags.json === true);
   const origin = platformOrigin({
     origin: strFlag(flags, "origin"),
@@ -11248,9 +11643,9 @@ async function cmdActionsScript(input, flags) {
 }
 
 // src/plugin/ingest.ts
-import { existsSync as existsSync20 } from "fs";
+import { existsSync as existsSync21 } from "fs";
 import { copyFile, mkdir as mkdir10, readFile as readFile16, stat as stat4 } from "fs/promises";
-import { basename as basename9, join as join24, resolve as resolve14 } from "path";
+import { basename as basename10, join as join25, resolve as resolve14 } from "path";
 import { inflateRawSync } from "zlib";
 import {
   cursorFromPlaywrightTrace,
@@ -11331,7 +11726,7 @@ async function copyRecording(src, dest, ext) {
   }
 }
 async function readTraceFile(path, offsetMs) {
-  const kind = traceKindOf(basename9(path));
+  const kind = traceKindOf(basename10(path));
   if (!kind) {
     throw new UsageError(
       `${path}: not a trace the recorder reads (trace.zip, .trace, .jsonl, .json or .csv)`
@@ -11352,7 +11747,7 @@ async function readTraceFile(path, offsetMs) {
     return cursorFromPlaywrightTrace(text2, { offsetMs });
   }
   const text = await readFile16(path, "utf8");
-  return cursorFromTrace(basename9(path), text, { offsetMs });
+  return cursorFromTrace(basename10(path), text, { offsetMs });
 }
 function parseViewport(v) {
   if (!v) return null;
@@ -11368,7 +11763,7 @@ async function cmdIngest(argv) {
       "vos ingest <video.webm|mp4> [--cursor <trace.zip|steps.jsonl|cursor.csv>] [--as footage|take] [--out take] [--offset <ms>] [--viewport WxH] [--background <slug|url|none>] [--json]"
     );
   const videoPath = resolve14(source);
-  if (!existsSync20(videoPath)) throw new UsageError(`${source}: no such file`);
+  if (!existsSync21(videoPath)) throw new UsageError(`${source}: no such file`);
   const r = createReporter(flags.json === true);
   const outDir = resolve14(strFlag(flags, "out") ?? "take");
   const offsetMs = numFlag(flags, "offset", 0);
@@ -11383,7 +11778,7 @@ async function cmdIngest(argv) {
       "note: finished footage opens bare, so --background is not used (pass --as take for the screen-recording card and its ground)"
     );
   const backdrop = footage ? null : await takeBackdrop(flags, r);
-  r.log(`probing ${basename9(videoPath)}\u2026`);
+  r.log(`probing ${basename10(videoPath)}\u2026`);
   const probed = await probeVideoFile(videoPath);
   if (!(probed.durationMs > 0)) {
     throw new UsageError(
@@ -11395,7 +11790,7 @@ async function cmdIngest(argv) {
     trace = await readTraceFile(resolve14(cursorPath), offsetMs);
     for (const n of trace.notes) r.log(`note: ${n}`);
   }
-  if (existsSync20(join24(outDir, "meta.json"))) {
+  if (existsSync21(join25(outDir, "meta.json"))) {
     const { prevDoc, kept } = await prepareReRecord(outDir);
     r.log(
       `note: re-ingesting into ${outDir}; kept ${kept.length ? kept.join(", ") : "nothing"}` + (prevDoc ? `; apply the previous cut with: vos plan ${outDir} --reuse` : "")
@@ -11403,7 +11798,7 @@ async function cmdIngest(argv) {
   }
   await mkdir10(outDir, { recursive: true });
   const paths = await ensureTakeDir(outDir);
-  const recording = join24(outDir, `recording.${probed.ext}`);
+  const recording = join25(outDir, `recording.${probed.ext}`);
   r.log("copying the recording\u2026");
   const remuxed = await copyRecording(videoPath, recording, probed.ext);
   const viewport = viewportFlag ?? trace?.viewport ?? {
@@ -11432,13 +11827,13 @@ async function cmdIngest(argv) {
   const clicks = events.filter((e) => e.type === "down").length;
   const seconds = (probed.durationMs / 1e3).toFixed(1);
   const facts = `${seconds}s, ${probed.width}\xD7${probed.height} @ ${meta.fps} fps${probed.hasAudio ? ", audio" : ", no audio"}${remuxed ? "" : ", copied as is"}`;
-  const cursorLine = trace ? `${events.length} cursor events (${clicks} clicks) from ${basename9(cursorPath)}${trace.dropped ? `, ${trace.dropped} not placed` : ""}; ${plan.zoomAuto} zoom${plan.zoomAuto === 1 ? "" : "s"} planned` : "no cursor track, so nothing was planned";
+  const cursorLine = trace ? `${events.length} cursor events (${clicks} clicks) from ${basename10(cursorPath)}${trace.dropped ? `, ${trace.dropped} not placed` : ""}; ${plan.zoomAuto} zoom${plan.zoomAuto === 1 ? "" : "s"} planned` : "no cursor track, so nothing was planned";
   const opened = footage ? `opened as finished footage: no card, no browser bar, no drawn cursor, ${meta.fps > 30 ? 60 : 30} fps export (--as take for a screen recording's card)` : `opened as a screen recording: the card, its ground and the drawn cursor (--as footage to open it bare)`;
   const next = footage && !trace ? `Next: vos push ${outDir} --wait \u2014 it lands as it is; trim or add to it in the studio` : trace ? `Next: vos digest ${outDir} \u2014 look before you cut; edit doc.json; vos push ${outDir}` : `Add --cursor <trace> recorded beside the video (a Playwright trace.zip, stamped JSON records, or a t,x,y,type CSV) to plan zooms from its clicks; else place them by eye: vos frames ${outDir} --times 0,25%,50%,75%,100%, then edit doc.json`;
   r.done(
     {
       out: outDir,
-      recording: basename9(recording),
+      recording: basename10(recording),
       durationMs: probed.durationMs,
       width: probed.width,
       height: probed.height,
@@ -11447,7 +11842,7 @@ async function cmdIngest(argv) {
       hasAudio: probed.hasAudio,
       remuxed,
       cursor: trace ? {
-        file: basename9(cursorPath),
+        file: basename10(cursorPath),
         kind: trace.kind,
         events: events.length,
         clicks,
@@ -11459,7 +11854,7 @@ async function cmdIngest(argv) {
       backdrop: plan.backdrop ?? null,
       as: footage ? "footage" : "take"
     },
-    `Ingested ${basename9(videoPath)} \u2192 ${outDir}/${basename9(recording)} (${facts})
+    `Ingested ${basename10(videoPath)} \u2192 ${outDir}/${basename10(recording)} (${facts})
   ${opened}
   ${cursorLine}
   ${next}`
@@ -11471,19 +11866,19 @@ async function cmdIngest(argv) {
 import { spawnSync as spawnSync4 } from "child_process";
 import {
   cpSync,
-  existsSync as existsSync22,
+  existsSync as existsSync23,
   mkdirSync as mkdirSync6,
-  readFileSync as readFileSync9,
+  readFileSync as readFileSync10,
   rmSync as rmSync3,
   writeFileSync as writeFileSync6
 } from "fs";
 import { homedir as homedir2 } from "os";
-import { join as join26 } from "path";
+import { join as join27 } from "path";
 import { chromium as chromium2 } from "playwright";
 
 // src/plugin/machine.ts
-import { existsSync as existsSync21, readFileSync as readFileSync8, readdirSync as readdirSync5, statSync as statSync6 } from "fs";
-import { dirname as dirname9, join as join25 } from "path";
+import { existsSync as existsSync22, readFileSync as readFileSync9, readdirSync as readdirSync6, statSync as statSync7 } from "fs";
+import { dirname as dirname9, join as join26 } from "path";
 var AGENT_NAMES = [
   "claude",
   "cursor",
@@ -11503,17 +11898,17 @@ var HOME_DIRS = {
   copilot: [".copilot"]
 };
 function detectAgents(root, opts = {}) {
-  const exists = opts.exists ?? existsSync21;
+  const exists = opts.exists ?? existsSync22;
   const out = [];
   for (const agent of AGENT_NAMES) {
     for (const rel of PROJECT_DIRS[agent]) {
-      const dir = join25(root, rel);
+      const dir = join26(root, rel);
       if (exists(dir)) out.push({ agent, dir, scope: "project" });
     }
-    if (agent === "copilot" && !out.some((h) => h.agent === "copilot") && exists(join25(root, ".github", "copilot-instructions.md"))) {
+    if (agent === "copilot" && !out.some((h) => h.agent === "copilot") && exists(join26(root, ".github", "copilot-instructions.md"))) {
       out.push({
         agent,
-        dir: join25(root, ".github", "copilot"),
+        dir: join26(root, ".github", "copilot"),
         scope: "project"
       });
     }
@@ -11521,7 +11916,7 @@ function detectAgents(root, opts = {}) {
   if (opts.global && opts.home) {
     for (const agent of AGENT_NAMES) {
       for (const rel of HOME_DIRS[agent]) {
-        const dir = join25(opts.home, rel);
+        const dir = join26(opts.home, rel);
         if (exists(dir)) out.push({ agent, dir, scope: "global" });
       }
     }
@@ -11539,26 +11934,26 @@ function agentsFromFlag(value, root) {
   return {
     homes: wanted.map((agent) => ({
       agent,
-      dir: join25(root, PROJECT_DIRS[agent][0]),
+      dir: join26(root, PROJECT_DIRS[agent][0]),
       scope: "project"
     }))
   };
 }
 function skillsDirFor(home) {
-  return join25(home.dir, "skills");
+  return join26(home.dir, "skills");
 }
 function fallbackSkillsHome(root) {
-  return { agent: "codex", dir: join25(root, ".agents"), scope: "project" };
+  return { agent: "codex", dir: join26(root, ".agents"), scope: "project" };
 }
-function installedSkills(dir, exists = existsSync21, list = (p) => {
+function installedSkills(dir, exists = existsSync22, list = (p) => {
   try {
-    return readdirSync5(p);
+    return readdirSync6(p);
   } catch {
     return [];
   }
 }) {
   if (!exists(dir)) return [];
-  return list(dir).filter((name) => exists(join25(dir, name, "SKILL.md"))).sort();
+  return list(dir).filter((name) => exists(join26(dir, name, "SKILL.md"))).sort();
 }
 var RULES_BEGIN = "<!-- vos:begin (written by vos setup; the block is replaced on the next run) -->";
 var RULES_END = "<!-- vos:end -->";
@@ -11590,10 +11985,10 @@ ${RULES_BLOCK}
   }
   return { text, changed: text !== current };
 }
-function rulesFileFor(root, exists = existsSync21) {
-  const agents = join25(root, "AGENTS.md");
+function rulesFileFor(root, exists = existsSync22) {
+  const agents = join26(root, "AGENTS.md");
   if (exists(agents)) return agents;
-  const claude = join25(root, "CLAUDE.md");
+  const claude = join26(root, "CLAUDE.md");
   if (exists(claude)) return claude;
   return agents;
 }
@@ -11602,14 +11997,14 @@ function chromeCandidates(platform, env) {
     return ["/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"];
   if (platform === "win32")
     return [
-      join25(
+      join26(
         env["PROGRAMFILES"] ?? "C:\\Program Files",
         "Google",
         "Chrome",
         "Application",
         "chrome.exe"
       ),
-      join25(
+      join26(
         env["LOCALAPPDATA"] ?? "",
         "Google",
         "Chrome",
@@ -11696,13 +12091,13 @@ function doctorReport(facts) {
 function bundledSkillsDir(from) {
   let dir = dirname9(from);
   for (let i = 0; i < 6; i++) {
-    const pkg = join25(dir, "package.json");
-    if (existsSync21(pkg)) {
+    const pkg = join26(dir, "package.json");
+    if (existsSync22(pkg)) {
       try {
-        const name = JSON.parse(readFileSync8(pkg, "utf8")).name;
+        const name = JSON.parse(readFileSync9(pkg, "utf8")).name;
         if (name === "@vosjs/cli") {
-          const skills = join25(dir, "skills");
-          return existsSync21(skills) && statSync6(skills).isDirectory() ? skills : null;
+          const skills = join26(dir, "skills");
+          return existsSync22(skills) && statSync7(skills).isDirectory() ? skills : null;
         }
       } catch {
       }
@@ -11733,7 +12128,7 @@ function npx() {
 function bundledChromium() {
   try {
     const p = chromium2.executablePath();
-    return p && existsSync22(p) ? p : null;
+    return p && existsSync23(p) ? p : null;
   } catch {
     return null;
   }
@@ -11742,7 +12137,7 @@ function probe2() {
   return probeBrowser({
     platform: process.platform,
     env: process.env,
-    exists: existsSync22,
+    exists: existsSync23,
     bundled: bundledChromium
   });
 }
@@ -11846,7 +12241,7 @@ async function cmdSetup(argv) {
         const dest = skillsDirFor(home);
         mkdirSync6(dest, { recursive: true });
         for (const name of installedSkills(bundled)) {
-          cpSync(join26(bundled, name), join26(dest, name), { recursive: true });
+          cpSync(join27(bundled, name), join27(dest, name), { recursive: true });
         }
       }
       skillsVia = "bundled";
@@ -11881,7 +12276,7 @@ async function cmdSetup(argv) {
   let rules = null;
   if (!noRules) {
     const file = rulesFileFor(root);
-    const existing = existsSync22(file) ? readFileSync9(file, "utf8") : null;
+    const existing = existsSync23(file) ? readFileSync10(file, "utf8") : null;
     const { text, changed } = applyRulesBlock(existing);
     if (changed) writeFileSync6(file, text);
     rules = { file, changed };
@@ -11995,7 +12390,7 @@ async function cmdWhoami(argv) {
 function cmdLogout(argv) {
   const { flags } = parseArgs(argv, BOOLEAN_FLAGS10);
   const r = reporterFor(flags);
-  const had = existsSync22(CREDENTIALS_PATH);
+  const had = existsSync23(CREDENTIALS_PATH);
   rmSync3(CREDENTIALS_PATH, { force: true });
   const envKey = Boolean(process.env.VOS_API_KEY?.trim());
   r.done(
@@ -12058,7 +12453,7 @@ Take pipeline
   vos ingest <video.webm|mp4> [--cursor <trace.zip|steps.jsonl|cursor.csv>] [--as footage|take] [--out take] [--offset <ms>] [--viewport WxH] [--background <slug|url|none>] [--json]
             a take from a recording someone else made (a cloud agent's PR video, a Playwright run's video, a Loom export): the file becomes recording.<container>, meta.json from its own dimensions and duration, and a trace beside it becomes cursor.json so the planner has clicks to zoom on; without one, nothing is planned and the done event says so. Without a trace the file opens as FINISHED footage (a render from HyperFrames or Remotion, a film): no card, no browser bar, no drawn cursor, its own frame rate; --as take gives a screen demo the card
   vos port inventory <page.html|project dir> [--render <their render.mp4>] [--out port] [--json]
-            a finished piece (HyperFrames, Remotion's render, a hand-rolled page) read as a browser renders it: words, palette, faces (catalog or missing), media, scenes, gaps \u2192 port/inventory.json, with stills from its render
+            a finished piece (a HyperFrames composition, a Remotion project bundled with its own bundler, a hand-rolled page) read as a browser renders it: words, palette, faces (catalog or missing), media, scenes, gaps \u2192 port/inventory.json, with stills from its render
   vos port scaffold [--from port/inventory.json] [--out port/program] [--json]
             a data-first program from it: every word a bound element, every colour a key, knobs, a label and a TODO per scene, the score as a doc.json track, port/REPORT.md
   vos build <program.mjs> [--out config.json] [--json]
@@ -12399,7 +12794,7 @@ function takeStorageState(flags) {
   const raw = strFlag(flags, "storage-state");
   if (!raw) return void 0;
   const path = resolve15(raw);
-  if (!existsSync23(path))
+  if (!existsSync24(path))
     throw new UsageError(`--storage-state: no such file: ${path}`);
   return path;
 }
@@ -12412,7 +12807,7 @@ function takeSessionName(flags, storageState) {
     throw new UsageError(
       "--session and --storage-state are two doors to one take: a persistent profile cannot take a storage state. Pass one"
     );
-  if (!existsSync23(sessionDir(name)))
+  if (!existsSync24(sessionDir(name)))
     throw new UsageError(
       `no session "${name}". Make one: vos session open <url> --name ${name} (a Chrome window opens; sign in and close it)`
     );
@@ -12635,7 +13030,7 @@ ${lines.join("\n")}
   }
   const paths = takePaths(outDir);
   const prepare = async () => {
-    if (existsSync23(join27(outDir, "meta.json"))) {
+    if (existsSync24(join28(outDir, "meta.json"))) {
       const { prevDoc, kept } = await prepareReRecord(outDir);
       r.log(
         `note: re-recording ${outDir} \u2014 kept ${kept.length ? kept.join(", ") : "nothing"}` + (prevDoc ? "; apply the previous cut to the new footage with: vos plan " + outDir + " --reuse" : "")
@@ -12700,7 +13095,7 @@ ${lines.join("\n")}
       },
       strictFail ? `STRICT: take recorded but incomplete \u2014 ${strictReason(rec)}; fix the flow and re-record.${skippedNote}${exposureNote(rec)}` : `Take ready: ${outDir}
   ${(rec.meta.durationMs / 1e3).toFixed(1)}s \xB7 ${rec.frames.length} frames \xB7 ${rec.events.length} cursor events \xB7 ${clicks} clicks \xB7 ${plan.doc.zoom.length} zoom spans planned \xB7 ${rec.freezePct}% frozen \xB7 ${rec.dead.pct}% dead${deadWarns(rec.dead) ? " \u26A0 " + deadLine(rec.dead) : ""}${skippedNote}
-  Next: edit ${join27(outDir, "doc.json")} (optional), then: vos render ${outDir}${exposureNote(rec)}`
+  Next: edit ${join28(outDir, "doc.json")} (optional), then: vos render ${outDir}${exposureNote(rec)}`
     );
     return strictFail ? EXIT_USAGE : EXIT_OK;
   } finally {
@@ -12726,7 +13121,7 @@ async function cmdCreate2(argv) {
     throw new UsageError('no URL \u2014 set "url" in the actions file or pass --url');
   const outDir = resolve15(strFlag(flags, "out") ?? "take");
   const format = videoFormat(strFlag(flags, "format"), positionals[0]);
-  const out = positionals[0] ?? join27(outDir, `out.${format}`);
+  const out = positionals[0] ?? join28(outDir, `out.${format}`);
   const parallel = numFlag(flags, "parallel", 1);
   if (!Number.isInteger(parallel) || parallel < 1 || parallel > 16) {
     throw new UsageError("--parallel expects an integer between 1 and 16");
@@ -12739,7 +13134,7 @@ async function cmdCreate2(argv) {
   const headers = takeHeaders(multi);
   const paths = takePaths(outDir);
   const prepare = async () => {
-    if (existsSync23(join27(outDir, "meta.json"))) {
+    if (existsSync24(join28(outDir, "meta.json"))) {
       const { prevDoc, kept } = await prepareReRecord(outDir);
       r.log(
         `note: re-recording ${outDir} \u2014 kept ${kept.length ? kept.join(", ") : "nothing"}` + (prevDoc ? "; apply the previous cut to the new footage with: vos plan " + outDir + " --reuse" : "")
@@ -12846,13 +13241,13 @@ async function cmdPlan(argv) {
     );
   const r = createReporter(flags.json === true);
   if (flags.fresh === true) {
-    await rm5(join27(dir, "doc.json"), { force: true });
+    await rm5(join28(dir, "doc.json"), { force: true });
     r.log("note: --fresh discarded the existing doc.json");
   }
   let reuse;
   if (flags.reuse === true) {
-    const from = resolve15(strFlag(flags, "from") ?? join27(dir, PREV_DOC_NAME));
-    if (!existsSync23(from)) {
+    const from = resolve15(strFlag(flags, "from") ?? join28(dir, PREV_DOC_NAME));
+    if (!existsSync24(from)) {
       throw new UsageError(
         `--reuse: ${from} does not exist \u2014 a re-record into this take writes doc.prev.json, or pass --from <doc.json>`
       );
@@ -12863,7 +13258,7 @@ async function cmdPlan(argv) {
     };
   }
   const style = await resolveStyleRef(flags);
-  const hasDoc = existsSync23(join27(dir, "doc.json"));
+  const hasDoc = existsSync24(join28(dir, "doc.json"));
   const backdrop = hasDoc ? null : await takeBackdrop(flags, r);
   const release = await releaseInputs(dir, flags, r, multi.with ?? []);
   const motionWanted = !hasDoc || flags.motion === true || flags.fresh === true;
@@ -12921,7 +13316,7 @@ async function cmdPlan(argv) {
       ...s.motion ? { motion: s.motion } : {},
       ...s.reuse ? { reuse: s.reuse } : {}
     },
-    `${s.reuse ? "Reused" : s.fresh ? "Planned" : "Refreshed"} ${join27(dir, "doc.json")}: ${s.zoomAuto} auto + ${s.zoomManual} manual zoom spans${s.cursorKept ? "" : " (cursor track dropped)"}${layoutLines}${motionLines}${reuseLines}`
+    `${s.reuse ? "Reused" : s.fresh ? "Planned" : "Refreshed"} ${join28(dir, "doc.json")}: ${s.zoomAuto} auto + ${s.zoomManual} manual zoom spans${s.cursorKept ? "" : " (cursor track dropped)"}${layoutLines}${motionLines}${reuseLines}`
   );
   return EXIT_OK;
 }
@@ -13044,7 +13439,7 @@ async function cmdRender(argv) {
     );
   const r = createReporter(flags.json === true);
   const format = videoFormat(strFlag(flags, "format"), positionals[1]);
-  const out = positionals[1] ?? join27(dir, `out.${format}`);
+  const out = positionals[1] ?? join28(dir, `out.${format}`);
   const parallel = numFlag(flags, "parallel", 1);
   if (!Number.isInteger(parallel) || parallel < 1 || parallel > 16) {
     throw new UsageError("--parallel expects an integer between 1 and 16");
@@ -13291,11 +13686,11 @@ async function resolveStyleRef(flags) {
 }
 async function resolveDocRef(ref, flags, what) {
   const styleRef = ref;
-  const file = existsSync23(styleRef) ? resolve15(
+  const file = existsSync24(styleRef) ? resolve15(
     styleRef,
-    existsSync23(join27(styleRef, "doc.json")) ? "doc.json" : ""
+    existsSync24(join28(styleRef, "doc.json")) ? "doc.json" : ""
   ) : null;
-  if (file && existsSync23(file)) {
+  if (file && existsSync24(file)) {
     return {
       from: file,
       doc: migrateHostedDoc5(
@@ -13382,7 +13777,7 @@ async function cmdDigest(argv) {
         kinds,
         frames: d.images.full,
         crops: d.images.crop,
-        sheet: d.images.sheet ? join27(result.outDir, d.images.sheet) : null,
+        sheet: d.images.sheet ? join28(result.outDir, d.images.sheet) : null,
         scenes: kinds.scene ?? 0,
         sourceDuration: d.take.sourceDuration,
         outputDuration: d.take.outputDuration,
@@ -13410,7 +13805,7 @@ async function cmdOpen(argv) {
   if (!dir) throw new UsageError("vos open <take> [--studio <url>]");
   const r = createReporter(flags.json === true);
   const take = await loadTake(dir);
-  if (!existsSync23(take.paths.recording)) {
+  if (!existsSync24(take.paths.recording)) {
     throw new UsageError(`${dir} has no recording \u2014 re-run record`);
   }
   const studio = (strFlag(flags, "studio") ?? platformOrigin()).replace(
@@ -13451,9 +13846,9 @@ async function cmdJudge(argv) {
       "vos judge <kit.json> --against <MANIFEST.json> [--out dir] [--json]\n(the manifest names the reference set: id, file, role, layout, facts, rule per asset)"
     );
   const r = createReporter(flags.json === true);
-  const kitFile = target.endsWith("kit.json") ? target : join27(target, "kit.json");
-  if (!existsSync23(kitFile)) throw new UsageError(`${kitFile}: no kit manifest`);
-  if (!existsSync23(against))
+  const kitFile = target.endsWith("kit.json") ? target : join28(target, "kit.json");
+  if (!existsSync24(kitFile)) throw new UsageError(`${kitFile}: no kit manifest`);
+  if (!existsSync24(against))
     throw new UsageError(`${against}: no reference manifest`);
   const result = await judgeKit(kitFile, against, strFlag(flags, "out"));
   const verdicts = JSON.parse(await readFile17(result.verdictFile, "utf8")).verdicts;
@@ -13575,7 +13970,7 @@ async function cmdValidate(argv) {
   const target = positionals[0];
   if (!target) throw new UsageError("vos validate <actions.json|take>");
   const r = createReporter(flags.json === true);
-  const kitTarget = target.endsWith("kit.json") ? target : existsSync23(join27(target, "kit.json")) && !isTakeDir(target) ? join27(target, "kit.json") : null;
+  const kitTarget = target.endsWith("kit.json") ? target : existsSync24(join28(target, "kit.json")) && !isTakeDir(target) ? join28(target, "kit.json") : null;
   if (kitTarget) {
     const picture = flags.picture === true;
     const verdict = await validateKit(kitTarget, { picture });
@@ -13607,9 +14002,9 @@ async function cmdValidate(argv) {
     r.done({ valid: true, target }, `${target}: valid actions file`);
     return EXIT_OK;
   }
-  if (!isTakeDir(target) && existsSync23(join27(target, "config.json"))) {
+  if (!isTakeDir(target) && existsSync24(join28(target, "config.json"))) {
     const parsed = JSON.parse(
-      await readFile17(join27(target, "config.json"), "utf8")
+      await readFile17(join28(target, "config.json"), "utf8")
     );
     const pre = preflightConfig(parsed);
     const problems2 = pre.ok ? [] : pre.issues.map((i) => `config.json: ${i}`);
@@ -13650,7 +14045,7 @@ async function cmdValidate(argv) {
   const take = await loadTake(target);
   const problems = [];
   const warnings = [];
-  if (!existsSync23(take.paths.recording)) {
+  if (!existsSync24(take.paths.recording)) {
     problems.push("missing recording (re-run record)");
   } else {
     const mismatch = containerMismatch(
@@ -13998,7 +14393,7 @@ async function cmdSession(argv) {
       if (!arg) throw new UsageError(usage);
       const bad = sessionNameVerdict(arg);
       if (bad) throw new UsageError(bad);
-      if (!existsSync23(sessionDir(arg)))
+      if (!existsSync24(sessionDir(arg)))
         throw new UsageError(`no session "${arg}" (vos session list)`);
       const summary3 = await summarizeSession(arg);
       const url = strFlag(flags, "url");
@@ -14102,4 +14497,4 @@ export {
   verbHelp,
   run
 };
-//# sourceMappingURL=chunk-MTOCJ2LC.js.map
+//# sourceMappingURL=chunk-FQA7LFXG.js.map