stereoframe 0.1.0

package/dist/cli.js

@@ -0,0 +1,761 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { readFileSync, existsSync as existsSync4 } from "node:fs";
+import { join as join4, resolve as resolve6 } from "node:path";
+
+// src/blocks.ts
+import { copyFileSync, existsSync, mkdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+var BLOCKS = {
+  ocean: {
+    description: "animated water plane (three.js Water) — reflections, sun glint",
+    assets: ["waternormals.jpg"],
+    snippet: `  <sf-ocean size="2000" color="#001e0f" speed="1"></sf-ocean>
+  <!-- pair with <sf-sky> (its sun drives the water highlights) and
+       <sf-camera far="5000"> so the horizon isn't clipped -->`
+  },
+  sky: {
+    description: "physical atmosphere dome (three.js Sky) — sun by elevation/azimuth",
+    assets: [],
+    snippet: `  <sf-sky elevation="12" azimuth="200" turbidity="8"></sf-sky>
+  <!-- low elevation (2-15) = golden hour; set <sf-scene exposure="0.6"> for balance -->`
+  }
+};
+function packagedAssetPath(file) {
+  return fileURLToPath(new URL(`../assets/${file}`, import.meta.url));
+}
+function listBlocks() {
+  return Object.entries(BLOCKS).map(([name, def]) => `  ${name.padEnd(8)} ${def.description}`).join(`
+`);
+}
+function addBlock(name, projectDir) {
+  const block = BLOCKS[name];
+  if (!block) {
+    throw new Error(`unknown block: ${name}
+
+available blocks:
+${listBlocks()}`);
+  }
+  const assetsDir = join(resolve(projectDir), "assets");
+  mkdirSync(assetsDir, { recursive: true });
+  const copied = [];
+  for (const asset of block.assets) {
+    const src = packagedAssetPath(asset);
+    if (!existsSync(src))
+      throw new Error(`packaged asset missing: ${src}`);
+    copyFileSync(src, join(assetsDir, asset));
+    copied.push(`assets/${asset}`);
+  }
+  const lines = [
+    copied.length > 0 ? `installed: ${copied.join(", ")}` : "no assets needed",
+    "",
+    "add inside <sf-scene>:",
+    block.snippet
+  ];
+  return lines.join(`
+`);
+}
+
+// src/lint.ts
+import { ASSET_ATTRS, EASE_NAMES, ELEMENT_NAMES, VERB_NAMES } from "stereoframe-runtime/vocab";
+function readAttr(attrs, name) {
+  const m = attrs.match(new RegExp(`(?:^|\\s)${name}\\s*=\\s*"([^"]*)"`));
+  return m ? m[1] : null;
+}
+function sfTags(html) {
+  const tags = [];
+  const re = /<(sf-[a-z-]+)((?:\s[^>]*)?)>/gi;
+  for (const m of html.matchAll(re)) {
+    tags.push({ name: m[1].toLowerCase(), attrs: m[2] ?? "" });
+  }
+  return tags;
+}
+function inlineScripts(html) {
+  const scripts = [];
+  const re = /<script\b([^>]*)>([\s\S]*?)<\/script>/gi;
+  for (const m of html.matchAll(re)) {
+    scripts.push({ attrs: m[1] ?? "", content: m[2] ?? "" });
+  }
+  return scripts;
+}
+var IMPURE_PATTERNS = [
+  { pattern: /\bDate\.now\s*\(/, what: "Date.now()" },
+  { pattern: /\bperformance\.now\s*\(/, what: "performance.now()" },
+  { pattern: /\bMath\.random\s*\(/, what: "Math.random()" },
+  { pattern: /\brequestAnimationFrame\s*\(/, what: "requestAnimationFrame()" }
+];
+function lintHtml(html, opts) {
+  const findings = [];
+  const tags = sfTags(html);
+  const scenes = tags.filter((t) => t.name === "sf-scene");
+  const embed = /data-composition-id\s*=/.test(html);
+  if (scenes.length === 0) {
+    findings.push({
+      rule: "missing_scene",
+      severity: "error",
+      message: "no <sf-scene> found — nothing to render.",
+      fixHint: 'Add an <sf-scene duration="<seconds>"> root with content elements inside.'
+    });
+  }
+  for (const scene of scenes) {
+    if (!readAttr(scene.attrs, "duration") && !embed) {
+      findings.push({
+        rule: "missing_duration",
+        severity: "error",
+        message: "<sf-scene> has no duration attribute — the runtime will fall back to 5s.",
+        fixHint: 'Add duration="<seconds>" to every <sf-scene>.'
+      });
+    }
+  }
+  const knownElements = new Set(ELEMENT_NAMES);
+  for (const tag of tags) {
+    if (!knownElements.has(tag.name)) {
+      findings.push({
+        rule: "unknown_element",
+        severity: "warning",
+        message: `<${tag.name}> is not a stereoframe element (typo?).`,
+        fixHint: `Known elements: ${ELEMENT_NAMES.join(", ")}.`
+      });
+    }
+  }
+  for (const tag of tags) {
+    for (const attr of ASSET_ATTRS) {
+      const value = readAttr(tag.attrs, attr);
+      if (!value)
+        continue;
+      if (/^https?:\/\//i.test(value)) {
+        findings.push({
+          rule: "remote_asset",
+          severity: "error",
+          message: `<${tag.name} ${attr}="${value}"> fetches a remote asset — renders must be network-free.`,
+          fixHint: "Download the asset into assets/ and reference it relatively."
+        });
+      } else if (!value.startsWith("data:") && !opts.fileExists(value)) {
+        findings.push({
+          rule: "asset_not_found",
+          severity: "error",
+          message: `<${tag.name} ${attr}="${value}">: file not found in the project.`,
+          fixHint: "Check the path, or install block assets with `stereoframe add <block>`."
+        });
+      }
+    }
+  }
+  if (!embed) {
+    const hasImport = /import\s+["'][^"']*stereoframe(?:\.js)?["']/.test(html) || /<script[^>]*src="[^"]*stereoframe\.js"/.test(html);
+    if (!hasImport) {
+      findings.push({
+        rule: "missing_runtime_import",
+        severity: "error",
+        message: "the stereoframe runtime is never loaded — the scene will not render.",
+        fixHint: 'Add <script type="module">import "./assets/stereoframe.js";</script> before </body>.'
+      });
+    }
+  }
+  for (const script of inlineScripts(html)) {
+    if (/\bsrc\s*=/.test(script.attrs))
+      continue;
+    for (const { pattern, what } of IMPURE_PATTERNS) {
+      if (pattern.test(script.content)) {
+        findings.push({
+          rule: "time_impurity",
+          severity: "error",
+          message: `inline script uses ${what} — output would differ between runs/frames.`,
+          fixHint: "Derive everything from seek time: use sf.onSeek((t) => …) and seeded data (sf-particles seed=…)."
+        });
+      }
+    }
+  }
+  const knownVerbs = new Set(VERB_NAMES);
+  const knownEases = new Set(EASE_NAMES);
+  const animates = tags.filter((t) => t.name === "sf-animate");
+  for (const el of animates) {
+    const verb = (readAttr(el.attrs, "verb") ?? "").toLowerCase();
+    if (verb && !knownVerbs.has(verb)) {
+      findings.push({
+        rule: "unknown_verb",
+        severity: "error",
+        message: `sf-animate verb="${verb}" is not a known verb.`,
+        fixHint: `Known verbs: ${VERB_NAMES.join(", ")}.`
+      });
+    }
+    const ease = readAttr(el.attrs, "ease");
+    if (ease && !knownEases.has(ease.trim())) {
+      findings.push({
+        rule: "unknown_ease",
+        severity: "warning",
+        message: `ease="${ease}" is not a known easing name — it will fall back to the default.`,
+        fixHint: "Use GSAP-style names like power2.inOut, back.out, sine.inOut, linear."
+      });
+    }
+    const target = readAttr(el.attrs, "target");
+    if (target?.startsWith("#")) {
+      const id = target.slice(1);
+      if (!new RegExp(`\\bid\\s*=\\s*"${id}"`).test(html)) {
+        findings.push({
+          rule: "verb_target_missing",
+          severity: "error",
+          message: `sf-animate target="${target}" matches no element id in the document.`
+        });
+      }
+    }
+  }
+  const sceneBlocks = html.match(/<sf-scene\b[^>]*>[\s\S]*?<\/sf-scene>/gi) ?? [];
+  for (const block of sceneBlocks) {
+    const blockTags = sfTags(block);
+    const ahead = blockTags.some((t) => t.name === "sf-animate" && (readAttr(t.attrs, "verb") ?? "").toLowerCase() === "camera-path" && (readAttr(t.attrs, "look") ?? "ahead") !== "none");
+    const lookAt = blockTags.some((t) => t.name === "sf-camera" && readAttr(t.attrs, "look-at") !== null);
+    if (ahead && lookAt) {
+      findings.push({
+        rule: "camera_path_lookat_conflict",
+        severity: "warning",
+        message: 'camera-path look="ahead" is overridden by sf-camera look-at in the same scene (look-at is applied after path aiming).',
+        fixHint: 'Remove look-at from that sf-camera, or set look="none" on the camera-path.'
+      });
+    }
+  }
+  const clipRe = /<(?!sf-)([a-z][a-z0-9]*)\b([^>]*\bdata-start\s*=[^>]*)>/gi;
+  for (const m of html.matchAll(clipRe)) {
+    const attrs = m[2] ?? "";
+    const cls = readAttr(attrs, "class") ?? "";
+    if (!cls.split(/\s+/).includes("clip")) {
+      findings.push({
+        rule: "dom_clip_missing_class",
+        severity: "warning",
+        message: `<${m[1]}> has data-start but no class="clip" — its visibility window will be ignored.`,
+        fixHint: 'Add class="clip" so the runtime drives its visibility from seek time.'
+      });
+    }
+  }
+  const shots = scenes.map((s) => ({
+    start: Number(readAttr(s.attrs, "start") ?? 0) || 0,
+    duration: Number(readAttr(s.attrs, "duration") ?? 5) || 5,
+    transition: (readAttr(s.attrs, "transition") ?? "cut").toLowerCase(),
+    transitionDuration: Number(readAttr(s.attrs, "transition-duration") ?? 0.6) || 0.6
+  }));
+  for (let i = 1;i < shots.length; i++) {
+    const shot = shots[i];
+    if (shot.transition !== "crossfade")
+      continue;
+    const priorEnd = Math.max(...shots.slice(0, i).map((p) => p.start + p.duration));
+    if (priorEnd < shot.start + shot.transitionDuration - 0.000001) {
+      findings.push({
+        rule: "transition_gap",
+        severity: "warning",
+        message: `shot ${i + 1} crossfades until t=${(shot.start + shot.transitionDuration).toFixed(2)} but the previous shot ends at t=${priorEnd.toFixed(2)} — the fade will show the page background.`,
+        fixHint: "Extend the previous shot's duration to cover start + transition-duration."
+      });
+    }
+  }
+  return findings;
+}
+
+// src/render.ts
+import { spawn } from "node:child_process";
+import { mkdirSync as mkdirSync2 } from "node:fs";
+import { dirname, resolve as resolve3 } from "node:path";
+
+// src/session.ts
+import puppeteer from "puppeteer";
+
+// src/serve.ts
+import { createServer } from "node:http";
+import { createReadStream, existsSync as existsSync2, statSync } from "node:fs";
+import { extname, join as join2, normalize, resolve as resolve2 } from "node:path";
+var MIME = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".webp": "image/webp",
+  ".gif": "image/gif",
+  ".svg": "image/svg+xml",
+  ".glb": "model/gltf-binary",
+  ".gltf": "model/gltf+json",
+  ".hdr": "application/octet-stream",
+  ".exr": "application/octet-stream",
+  ".bin": "application/octet-stream",
+  ".ktx2": "application/octet-stream",
+  ".mp4": "video/mp4",
+  ".mp3": "audio/mpeg",
+  ".wav": "audio/wav",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".ttf": "font/ttf",
+  ".otf": "font/otf"
+};
+function serveProject(projectDir, fixedPort = 0) {
+  const root = resolve2(projectDir);
+  const server = createServer((req, res) => {
+    const urlPath = decodeURIComponent((req.url ?? "/").split("?")[0] ?? "/");
+    if (urlPath === "/favicon.ico") {
+      res.writeHead(204).end();
+      return;
+    }
+    const rel = normalize(urlPath).replace(/^(\.\.[/\\])+/, "");
+    let filePath = join2(root, rel);
+    if (!filePath.startsWith(root)) {
+      res.writeHead(403).end("forbidden");
+      return;
+    }
+    if (existsSync2(filePath) && statSync(filePath).isDirectory()) {
+      filePath = join2(filePath, "index.html");
+    }
+    if (!existsSync2(filePath)) {
+      res.writeHead(404).end(`not found: ${urlPath}`);
+      return;
+    }
+    res.writeHead(200, {
+      "content-type": MIME[extname(filePath).toLowerCase()] ?? "application/octet-stream",
+      "cache-control": "no-store"
+    });
+    createReadStream(filePath).pipe(res);
+  });
+  return new Promise((resolvePromise, reject) => {
+    server.once("error", reject);
+    server.listen(fixedPort, "127.0.0.1", () => {
+      const address = server.address();
+      const port = typeof address === "object" && address ? address.port : fixedPort;
+      resolvePromise({
+        server,
+        port,
+        url: `http://127.0.0.1:${port}/`,
+        close: () => new Promise((r) => {
+          server.close(() => r());
+        })
+      });
+    });
+  });
+}
+
+// src/session.ts
+async function openSession(projectDir, opts = {}) {
+  const handle = await serveProject(projectDir);
+  const browser = await puppeteer.launch({
+    headless: true,
+    args: [
+      "--force-device-scale-factor=1",
+      "--hide-scrollbars",
+      "--enable-unsafe-swiftshader"
+    ]
+  });
+  try {
+    const page = await browser.newPage();
+    const errors = [];
+    const record = (msg) => {
+      errors.push(msg);
+      if (opts.echoErrors)
+        console.error("[page]", msg);
+    };
+    page.on("pageerror", (err) => record(err instanceof Error ? err.message : String(err)));
+    page.on("console", (msg) => {
+      if (msg.type() === "error")
+        record(msg.text());
+    });
+    await page.goto(handle.url, { waitUntil: "load", timeout: 60000 });
+    try {
+      await page.waitForFunction("window.__stereoframe && window.__stereoframe.ready === true", { timeout: 120000, polling: 100 });
+    } catch (err) {
+      const state = await page.evaluate(`({ hasProtocol: !!window.__stereoframe, ready: window.__stereoframe?.ready ?? null })`).catch(() => null);
+      throw new Error(`runtime never became ready (${JSON.stringify(state)}). ` + `Check that index.html imports assets/stereoframe.js and that all assets load.` + (errors.length ? `
+page errors:
+  ${errors.join(`
+  `)}` : ""));
+    }
+    const info = await page.evaluate(`({
+      duration: window.__stereoframe.duration,
+      width: window.__stereoframe.width,
+      height: window.__stereoframe.height,
+    })`);
+    await page.setViewport({ width: info.width, height: info.height, deviceScaleFactor: 1 });
+    return {
+      page,
+      info,
+      errors,
+      close: async () => {
+        await browser.close();
+        await handle.close();
+      }
+    };
+  } catch (err) {
+    await browser.close();
+    await handle.close();
+    throw err;
+  }
+}
+
+// src/render.ts
+async function renderProject(opts) {
+  const fps = opts.fps ?? 30;
+  const crf = opts.draft ? 28 : opts.crf ?? 18;
+  const preset = opts.draft ? "veryfast" : "medium";
+  const projectDir = resolve3(opts.projectDir);
+  const stamp = new Date().toISOString().replace(/[:T]/g, "-").slice(0, 19);
+  const out = resolve3(projectDir, opts.out ?? `renders/render_${stamp}.mp4`);
+  mkdirSync2(dirname(out), { recursive: true });
+  const session = await openSession(projectDir, { echoErrors: true });
+  try {
+    const { page, info } = session;
+    if (!(info.duration > 0)) {
+      throw new Error('composition reported zero duration — set duration="<seconds>" on <sf-scene>');
+    }
+    const totalFrames = Math.max(1, Math.round(info.duration * fps));
+    console.log(`rendering ${totalFrames} frames @ ${fps}fps (${info.width}x${info.height}, ${info.duration}s) → ${out}`);
+    const ffmpeg = spawn("ffmpeg", [
+      "-y",
+      "-loglevel",
+      "error",
+      "-f",
+      "image2pipe",
+      "-framerate",
+      String(fps),
+      "-c:v",
+      "png",
+      "-i",
+      "-",
+      "-c:v",
+      "libx264",
+      "-preset",
+      preset,
+      "-crf",
+      String(crf),
+      "-pix_fmt",
+      "yuv420p",
+      "-movflags",
+      "+faststart",
+      out
+    ], { stdio: ["pipe", "inherit", "inherit"] });
+    const ffmpegDone = new Promise((resolveDone, rejectDone) => {
+      ffmpeg.on("error", (err) => rejectDone(err.message.includes("ENOENT") ? new Error("ffmpeg not found on PATH — install it (e.g. `brew install ffmpeg`)") : err));
+      ffmpeg.on("close", (code) => code === 0 ? resolveDone() : rejectDone(new Error(`ffmpeg exited with code ${code}`)));
+    });
+    const cdp = await page.createCDPSession();
+    const started = Date.now();
+    for (let frame = 0;frame < totalFrames; frame++) {
+      await page.evaluate(`window.__stereoframe.seek(${frame / fps})`);
+      const shot = await cdp.send("Page.captureScreenshot", {
+        format: "png",
+        optimizeForSpeed: true
+      });
+      const ok = ffmpeg.stdin.write(Buffer.from(shot.data, "base64"));
+      if (!ok)
+        await new Promise((r) => ffmpeg.stdin.once("drain", r));
+      if (frame % Math.max(1, Math.floor(totalFrames / 10)) === 0) {
+        const pct = Math.round(frame / totalFrames * 100);
+        process.stdout.write(`\r  ${pct}% (frame ${frame}/${totalFrames})`);
+      }
+    }
+    ffmpeg.stdin.end();
+    await ffmpegDone;
+    const secs = ((Date.now() - started) / 1000).toFixed(1);
+    process.stdout.write(`\r  100% (${totalFrames} frames in ${secs}s)
+`);
+    return out;
+  } finally {
+    await session.close();
+  }
+}
+
+// src/scaffold.ts
+import { copyFileSync as copyFileSync2, existsSync as existsSync3, mkdirSync as mkdirSync3, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname as dirname2, join as join3, resolve as resolve4 } from "node:path";
+var TEMPLATE = `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <style>
+      * { margin: 0; padding: 0; box-sizing: border-box; }
+      html, body { width: 1920px; height: 1080px; overflow: hidden; background: #000; }
+      body { font-family: ui-sans-serif, system-ui, sans-serif; }
+      sf-scene { position: absolute; inset: 0; }
+      #title {
+        position: absolute; bottom: 100px; width: 100%; text-align: center;
+        font-size: 64px; font-weight: 700; color: #f4f4f5; letter-spacing: 0.04em;
+      }
+    </style>
+  </head>
+  <body>
+    <sf-scene duration="5" width="1920" height="1080" background="#101225">
+      <sf-camera fov="38" position="0 0.8 6" look-at="0 0 0"></sf-camera>
+      <sf-light preset="soft"></sf-light>
+
+      <sf-mesh id="hero" geometry="icosahedron" args="1.4 2" color="#7dd3fc"
+               metalness="0.4" roughness="0.25"></sf-mesh>
+
+      <sf-animate target="#hero" verb="bounce-in" start="0.3" duration="0.8"></sf-animate>
+      <sf-animate target="#hero" verb="turntable" rpm="10"></sf-animate>
+      <sf-animate target="#hero" verb="float" amplitude="0.12" period="3"></sf-animate>
+      <sf-animate target="#title" verb="fade-in" start="1.2" duration="0.8" rise="30"></sf-animate>
+    </sf-scene>
+
+    <div id="title" class="clip" data-start="1.2">hello stereoframe</div>
+
+    <script type="module">
+      import "./assets/stereoframe.js";
+    </script>
+  </body>
+</html>
+`;
+function resolveRuntimeBundle() {
+  const require2 = createRequire(import.meta.url);
+  return require2.resolve("stereoframe-runtime");
+}
+function scaffoldProject(name, cwd = process.cwd()) {
+  const dir = resolve4(cwd, name);
+  if (existsSync3(join3(dir, "index.html"))) {
+    throw new Error(`refusing to overwrite existing project at ${dir}`);
+  }
+  mkdirSync3(join3(dir, "assets"), { recursive: true });
+  writeFileSync(join3(dir, "index.html"), TEMPLATE);
+  writeFileSync(join3(dir, ".gitignore"), `renders/
+`);
+  copyFileSync2(resolveRuntimeBundle(), join3(dir, "assets", "stereoframe.js"));
+  return dir;
+}
+function updateRuntime(projectDir) {
+  const target = join3(resolve4(projectDir), "assets", "stereoframe.js");
+  if (!existsSync3(dirname2(target))) {
+    throw new Error(`no assets/ directory found in ${projectDir}`);
+  }
+  copyFileSync2(resolveRuntimeBundle(), target);
+  return target;
+}
+
+// src/validate.ts
+import { resolve as resolve5 } from "node:path";
+async function validateProject(projectDir) {
+  const findings = [];
+  let session;
+  try {
+    session = await openSession(resolve5(projectDir));
+  } catch (err) {
+    return [
+      {
+        rule: "runtime_not_ready",
+        severity: "error",
+        message: err instanceof Error ? err.message : String(err)
+      }
+    ];
+  }
+  try {
+    const { page, info, errors } = session;
+    for (const message of errors) {
+      findings.push({ rule: "page_error", severity: "error", message });
+    }
+    if (!(info.duration > 0)) {
+      findings.push({
+        rule: "zero_duration",
+        severity: "error",
+        message: "composition reported zero duration.",
+        fixHint: 'Set duration="<seconds>" on <sf-scene>.'
+      });
+      return findings;
+    }
+    const shots = await page.evaluate("window.__stereoframe.scenes.map(s => ({ start: s.shot.start, duration: s.shot.duration }))");
+    const sampleTimes = new Set;
+    for (const shot of shots) {
+      const end = Math.min(shot.start + shot.duration, info.duration);
+      sampleTimes.add(Math.min(shot.start + 0.05, end));
+      sampleTimes.add(shot.start + (end - shot.start) / 2);
+      sampleTimes.add(Math.max(shot.start, end - 0.05));
+    }
+    for (const t of [...sampleTimes].sort((a, b) => a - b)) {
+      const all = await page.evaluate(`window.__stereoframe.diagnostics(${t})`);
+      for (let i = 0;i < all.length; i++) {
+        const d = all[i];
+        if (!d.visible)
+          continue;
+        const where = `scene ${i + 1} at t=${t.toFixed(2)}s`;
+        if (d.hasNaN) {
+          findings.push({
+            rule: "nan_transform",
+            severity: "error",
+            message: `${where}: NaN in object/camera transforms — a verb parameter is probably malformed.`
+          });
+        }
+        if (d.litMeshCount > 0 && d.lightCount === 0 && !d.hasEnvironment) {
+          findings.push({
+            rule: "unlit_scene",
+            severity: "warning",
+            message: `${where}: ${d.litMeshCount} standard-material mesh(es) but no lights and no environment — they will render black.`,
+            fixHint: 'Add <sf-light preset="studio"> or an environment HDRI.'
+          });
+        }
+        if (d.frustumCoverage === 0) {
+          findings.push({
+            rule: "all_offscreen",
+            severity: "warning",
+            message: `${where}: no object intersects the camera frustum — the frame is empty.`,
+            fixHint: "Check camera position/look-at and object positions."
+          });
+        }
+        if (d.meanLuminance !== null && d.meanLuminance < 0.008 && d.meshCount > 0) {
+          findings.push({
+            rule: "black_frame",
+            severity: "warning",
+            message: `${where}: rendered frame is nearly black (mean luminance ${(d.meanLuminance * 255).toFixed(1)}/255).`,
+            fixHint: "Likely unlit content, an offscreen subject, or an asset that failed to apply."
+          });
+        }
+      }
+    }
+    const mid = info.duration / 2;
+    const first = await page.evaluate(`window.__stereoframe.fingerprint(${mid})`);
+    await page.evaluate(`window.__stereoframe.seek(0)`);
+    const second = await page.evaluate(`window.__stereoframe.fingerprint(${mid})`);
+    if (first !== second) {
+      findings.push({
+        rule: "non_idempotent_seek",
+        severity: "error",
+        message: `seeking t=${mid.toFixed(2)} twice produced different pixels — some state is not a pure function of seek time.`,
+        fixHint: "Look for accumulated state, wall-clock reads, or unseeded randomness in escape-hatch code."
+      });
+    }
+    return findings;
+  } finally {
+    await session.close();
+  }
+}
+
+// src/cli.ts
+function parseArgs(argv) {
+  const positional = [];
+  const options = new Map;
+  for (let i = 0;i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg.startsWith("--")) {
+      const key = arg.slice(2);
+      const next = argv[i + 1];
+      if (next !== undefined && !next.startsWith("--")) {
+        options.set(key, next);
+        i++;
+      } else {
+        options.set(key, true);
+      }
+    } else {
+      positional.push(arg);
+    }
+  }
+  return { positional, options };
+}
+var HELP = `stereoframe — declarative, deterministic 3D video on three.js
+
+USAGE
+  stereoframe init <name>              scaffold a new composition project
+  stereoframe lint [dir]               static checks (markup, assets, time purity)
+  stereoframe validate [dir]           headless run: errors, lighting, framing, idempotency
+      --json           machine-readable findings (both lint and validate)
+  stereoframe render [dir]             render index.html to mp4
+      --fps <n>        frames per second (default 30)
+      --out <path>     output file (default renders/render_<timestamp>.mp4)
+      --crf <n>        x264 quality, lower = better (default 18)
+      --draft          fast low-quality render for iteration
+  stereoframe preview [dir]            serve with looping wall-clock playback
+      --port <n>       fixed port (default: random)
+  stereoframe add <block> [dir]        install a visual block's assets + print usage
+  stereoframe blocks                   list available blocks
+  stereoframe update [dir]             refresh assets/stereoframe.js from the CLI's bundled runtime
+`;
+async function main() {
+  const [command, ...rest] = process.argv.slice(2);
+  const { positional, options } = parseArgs(rest);
+  const dir = positional[0] ?? ".";
+  switch (command) {
+    case "init": {
+      const name = positional[0];
+      if (!name)
+        throw new Error("usage: stereoframe init <name>");
+      const created = scaffoldProject(name);
+      console.log(`created ${created}`);
+      console.log(`next: cd ${name} && stereoframe render`);
+      return;
+    }
+    case "lint": {
+      const htmlPath = join4(resolve6(dir), "index.html");
+      if (!existsSync4(htmlPath))
+        throw new Error(`no index.html in ${resolve6(dir)}`);
+      const findings = lintHtml(readFileSync(htmlPath, "utf8"), {
+        fileExists: (rel) => existsSync4(join4(resolve6(dir), rel))
+      });
+      reportFindings("lint", findings, options.get("json") === true);
+      return;
+    }
+    case "validate": {
+      const findings = await validateProject(dir);
+      reportFindings("validate", findings, options.get("json") === true);
+      return;
+    }
+    case "render": {
+      const out = await renderProject({
+        projectDir: dir,
+        fps: options.has("fps") ? Number(options.get("fps")) : undefined,
+        crf: options.has("crf") ? Number(options.get("crf")) : undefined,
+        out: typeof options.get("out") === "string" ? options.get("out") : undefined,
+        draft: options.get("draft") === true
+      });
+      console.log(out);
+      return;
+    }
+    case "preview": {
+      const port = options.has("port") ? Number(options.get("port")) : 0;
+      const handle = await serveProject(dir, port);
+      console.log(`preview: ${handle.url}?sf-preview`);
+      console.log("press ctrl-c to stop");
+      return;
+    }
+    case "add": {
+      const name = positional[0];
+      if (!name)
+        throw new Error(`usage: stereoframe add <block>
+
+available blocks:
+${listBlocks()}`);
+      console.log(addBlock(name, positional[1] ?? "."));
+      return;
+    }
+    case "blocks": {
+      console.log(listBlocks());
+      return;
+    }
+    case "update": {
+      console.log(`updated ${updateRuntime(dir)}`);
+      return;
+    }
+    case "help":
+    case "--help":
+    case undefined:
+      console.log(HELP);
+      return;
+    default:
+      throw new Error(`unknown command: ${command}
+
+${HELP}`);
+  }
+}
+function reportFindings(command, findings, asJson) {
+  const errors = findings.filter((f) => f.severity === "error").length;
+  const warnings = findings.length - errors;
+  if (asJson) {
+    console.log(JSON.stringify({ command, errors, warnings, findings }, null, 2));
+  } else {
+    for (const f of findings) {
+      const mark = f.severity === "error" ? "✗" : "⚠";
+      console.log(`  ${mark} ${f.rule}: ${f.message}`);
+      if (f.fixHint)
+        console.log(`    Fix: ${f.fixHint}`);
+    }
+    console.log(`${command}: ${errors} error(s), ${warnings} warning(s)`);
+  }
+  if (errors > 0)
+    process.exit(1);
+}
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "stereoframe",
+  "version": "0.1.0",
+  "description": "Declarative, deterministic 3D video on three.js — scaffold, lint, validate, and render compositions built for AI agents.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kiyeonjeon21/stereoframe",
+    "directory": "packages/cli"
+  },
+  "type": "module",
+  "bin": {
+    "stereoframe": "./dist/cli.js"
+  },
+  "files": ["dist", "assets"],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "prepublishOnly": "bun run build",
+    "build": "bun build src/cli.ts --outfile dist/cli.js --format esm --target node --external puppeteer --external stereoframe-runtime/vocab --banner '#!/usr/bin/env node' && chmod +x dist/cli.js",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "stereoframe-runtime": "0.1.0",
+    "puppeteer": "^24.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}