hyperframes 0.1.7 → 0.1.9

package/dist/cli.js

@@ -422,7 +422,7 @@ var VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    VERSION = true ? "0.1.7" : "0.0.0-dev";
+    VERSION = true ? "0.1.9" : "0.0.0-dev";
   }
 });
 
@@ -3499,6 +3499,37 @@ function lintHyperframeHtml(html, options = {}) {
       fixHint: "Register each composition timeline on `window.__timelines[compositionId]`."
     });
   }
+  if (TIMELINE_REGISTRY_ASSIGN_PATTERN.test(source) && !TIMELINE_REGISTRY_INIT_PATTERN.test(source)) {
+    pushFinding({
+      code: "timeline_registry_missing_init",
+      severity: "error",
+      message: "`window.__timelines[\u2026] = \u2026` is used without initializing `window.__timelines` first.",
+      fixHint: "Add `window.__timelines = window.__timelines || {};` before any timeline assignment."
+    });
+  }
+  {
+    const htmlCompIds = /* @__PURE__ */ new Set();
+    const timelineRegKeys = /* @__PURE__ */ new Set();
+    const compIdRe = /data-composition-id\s*=\s*["']([^"']+)["']/gi;
+    const tlKeyRe = /window\.__timelines\[\s*["']([^"']+)["']\s*\]/g;
+    let m;
+    while ((m = compIdRe.exec(source)) !== null) {
+      if (m[1]) htmlCompIds.add(m[1]);
+    }
+    while ((m = tlKeyRe.exec(source)) !== null) {
+      if (m[1]) timelineRegKeys.add(m[1]);
+    }
+    for (const key2 of timelineRegKeys) {
+      if (!htmlCompIds.has(key2)) {
+        pushFinding({
+          code: "timeline_id_mismatch",
+          severity: "error",
+          message: `Timeline registered as "${key2}" but no element has data-composition-id="${key2}". The runtime cannot auto-nest this timeline.`,
+          fixHint: `Change window.__timelines["${key2}"] to match the data-composition-id attribute, or vice versa.`
+        });
+      }
+    }
+  }
   if (INVALID_SCRIPT_CLOSE_PATTERN.test(source)) {
     pushFinding({
       code: "invalid_inline_script_syntax",
@@ -23796,7 +23827,11 @@ __export(render_exports, {
   default: () => render_default
 });
 import { existsSync as existsSync24, mkdirSync as mkdirSync16, statSync as statSync9 } from "fs";
+import { cpus as cpus2 } from "os";
 import { resolve as resolve13, dirname as dirname12, join as join22 } from "path";
+function defaultWorkerCount() {
+  return Math.max(1, Math.min(Math.floor(CPU_CORE_COUNT / 2), 4));
+}
 async function renderDocker(projectDir, outputPath, options) {
   const producer = await loadProducer();
   const startTime = Date.now();
@@ -23810,7 +23845,11 @@ async function renderDocker(projectDir, outputPath, options) {
     });
     await producer.executeRenderJob(job, projectDir, outputPath);
   } catch (error) {
-    trackRenderError({ fps: options.fps, quality: options.quality, docker: true });
+    trackRenderError({
+      fps: options.fps,
+      quality: options.quality,
+      docker: true
+    });
     const message = error instanceof Error ? error.message : String(error);
     errorBox("Render failed", message, "Check Docker is running: docker info");
     process.exit(1);
@@ -23820,7 +23859,7 @@ async function renderDocker(projectDir, outputPath, options) {
     durationMs: elapsed,
     fps: options.fps,
     quality: options.quality,
-    workers: options.workers ?? 4,
+    workers: options.workers,
     docker: true,
     gpu: options.gpu
   });
@@ -23845,7 +23884,11 @@ async function renderLocal(projectDir, outputPath, options) {
   try {
     await producer.executeRenderJob(job, projectDir, outputPath, onProgress);
   } catch (error) {
-    trackRenderError({ fps: options.fps, quality: options.quality, docker: false });
+    trackRenderError({
+      fps: options.fps,
+      quality: options.quality,
+      docker: false
+    });
     const message = error instanceof Error ? error.message : String(error);
     errorBox("Render failed", message, "Try --docker for containerized rendering");
     process.exit(1);
@@ -23855,7 +23898,7 @@ async function renderLocal(projectDir, outputPath, options) {
     durationMs: elapsed,
     fps: options.fps,
     quality: options.quality,
-    workers: options.workers ?? 4,
+    workers: options.workers,
     docker: false,
     gpu: options.gpu
   });
@@ -23873,7 +23916,7 @@ function printRenderComplete(outputPath, elapsedMs, quiet) {
   console.log(c.success("\u25C7") + "  " + c.accent(outputPath));
   console.log("   " + c.bold(fileSize) + c.dim(" \xB7 " + duration + " \xB7 completed"));
 }
-var VALID_FPS, VALID_QUALITY, VALID_FORMAT, render_default;
+var VALID_FPS, VALID_QUALITY, VALID_FORMAT, CPU_CORE_COUNT, render_default;
 var init_render = __esm({
   "src/commands/render.ts"() {
     "use strict";
@@ -23887,6 +23930,7 @@ var init_render = __esm({
     VALID_FPS = /* @__PURE__ */ new Set([24, 30, 60]);
     VALID_QUALITY = /* @__PURE__ */ new Set(["draft", "standard", "high"]);
     VALID_FORMAT = /* @__PURE__ */ new Set(["mp4", "webm"]);
+    CPU_CORE_COUNT = cpus2().length;
     render_default = defineCommand({
       meta: {
         name: "render",
@@ -23899,19 +23943,45 @@ Examples:
   hyperframes render --docker --output deterministic.mp4`
       },
       args: {
-        dir: { type: "positional", description: "Project directory", required: false },
-        output: { type: "string", description: "Output path (default: renders/<name>.mp4)" },
-        fps: { type: "string", description: "Frame rate: 24, 30, 60", default: "30" },
-        quality: { type: "string", description: "Quality: draft, standard, high", default: "standard" },
+        dir: {
+          type: "positional",
+          description: "Project directory",
+          required: false
+        },
+        output: {
+          type: "string",
+          description: "Output path (default: renders/<name>.mp4)"
+        },
+        fps: {
+          type: "string",
+          description: "Frame rate: 24, 30, 60",
+          default: "30"
+        },
+        quality: {
+          type: "string",
+          description: "Quality: draft, standard, high",
+          default: "standard"
+        },
         format: {
           type: "string",
           description: "Output format: mp4, webm (WebM renders with transparency)",
           default: "mp4"
         },
-        workers: { type: "string", description: "Parallel workers 1-8" },
-        docker: { type: "boolean", description: "Use Docker for deterministic render", default: false },
+        workers: {
+          type: "string",
+          description: "Parallel render workers (1-8 or 'auto'). Default: half your CPU cores, max 4. Each worker launches a separate Chrome process."
+        },
+        docker: {
+          type: "boolean",
+          description: "Use Docker for deterministic render",
+          default: false
+        },
         gpu: { type: "boolean", description: "Use GPU encoding", default: false },
-        quiet: { type: "boolean", description: "Suppress verbose output", default: false }
+        quiet: {
+          type: "boolean",
+          description: "Suppress verbose output",
+          default: false
+        }
       },
       async run({ args }) {
         const project = resolveProject(args.dir);
@@ -23934,10 +24004,10 @@ Examples:
         }
         const format = formatRaw;
         let workers;
-        if (args.workers != null) {
+        if (args.workers != null && args.workers !== "auto") {
           const parsed = parseInt(args.workers, 10);
           if (isNaN(parsed) || parsed < 1 || parsed > 8) {
-            errorBox("Invalid workers", `Got "${args.workers}". Must be between 1 and 8.`);
+            errorBox("Invalid workers", `Got "${args.workers}". Must be 1-8 or "auto".`);
             process.exit(1);
           }
           workers = parsed;
@@ -23945,22 +24015,18 @@ Examples:
         const rendersDir = resolve13("renders");
         const ext = format === "webm" ? ".webm" : ".mp4";
         const outputPath = args.output ? resolve13(args.output) : join22(rendersDir, `${project.name}${ext}`);
-        const outputDir = dirname12(outputPath);
-        if (!existsSync24(outputDir)) {
-          mkdirSync16(outputDir, { recursive: true });
-        }
+        mkdirSync16(dirname12(outputPath), { recursive: true });
         const useDocker = args.docker ?? false;
         const useGpu = args.gpu ?? false;
         const quiet = args.quiet ?? false;
-        const workerCount = workers ?? 4;
+        const workerCount = workers ?? defaultWorkerCount();
         if (!quiet) {
+          const workerLabel = args.workers != null ? `${workerCount} workers` : `${workerCount} workers (auto \u2014 half of ${CPU_CORE_COUNT} cores)`;
           console.log("");
           console.log(
             c.accent("\u25C6") + "  Rendering " + c.accent(project.name) + c.dim(" \u2192 " + outputPath)
           );
-          console.log(
-            c.dim("   " + fps + "fps \xB7 " + quality + " \xB7 " + workerCount + " workers")
-          );
+          console.log(c.dim("   " + fps + "fps \xB7 " + quality + " \xB7 " + workerLabel));
           console.log("");
         }
         if (!useDocker) {
@@ -24007,7 +24073,7 @@ Examples:
             fps,
             quality,
             format,
-            workers,
+            workers: workerCount,
             gpu: useGpu,
             quiet
           });
@@ -24016,7 +24082,7 @@ Examples:
             fps,
             quality,
             format,
-            workers,
+            workers: workerCount,
             gpu: useGpu,
             quiet,
             browserPath
@@ -24397,8 +24463,16 @@ async function handleVideoFile(videoPath, destDir, interactive) {
         const transcode = await Jt({
           message: "Transcode to H.264 MP4 for browser playback?",
           options: [
-            { value: "yes", label: "Yes, transcode", hint: "converts to H.264 MP4" },
-            { value: "no", label: "No, keep original", hint: "video won't play in browser" }
+            {
+              value: "yes",
+              label: "Yes, transcode",
+              hint: "converts to H.264 MP4"
+            },
+            {
+              value: "no",
+              label: "No, keep original",
+              hint: "video won't play in browser"
+            }
           ]
         });
         if (Ct(transcode)) {
@@ -24484,7 +24558,11 @@ async function nextStepLoop(destDir) {
     const next = await Jt({
       message: "What do you want to do?",
       options: [
-        { value: "dev", label: "Open in studio", hint: "full editor with timeline" },
+        {
+          value: "dev",
+          label: "Open in studio",
+          hint: "full editor with timeline"
+        },
         { value: "render", label: "Render to MP4", hint: "export video now" },
         { value: "done", label: "Done for now" }
       ]
@@ -24533,10 +24611,10 @@ var init_init = __esm({
         description: `Scaffold a new composition project
 
 Examples:
-  hyperframes init my-video --template blank --video video.mp4
-  hyperframes init podcast --template warm-grain --audio episode.mp3
-  hyperframes init my-video --template blank --skip-skills --skip-transcribe
-  hyperframes init --human-friendly                    # interactive mode`
+  hyperframes init my-video                            # interactive wizard
+  hyperframes init my-video --template warm-grain      # pick a template
+  hyperframes init my-video --video video.mp4          # with video file
+  hyperframes init my-video --non-interactive           # skip prompts (CI/agents)`
       },
       args: {
         name: { type: "positional", description: "Project name", required: false },
@@ -24545,11 +24623,28 @@ Examples:
           description: `Template (${ALL_TEMPLATE_IDS.join(", ")})`,
           alias: "t"
         },
-        video: { type: "string", description: "Path to a video file (MP4, WebM, MOV)", alias: "V" },
-        audio: { type: "string", description: "Path to an audio file (MP3, WAV, M4A)", alias: "a" },
-        "skip-skills": { type: "boolean", description: "Skip AI coding skills installation" },
-        "skip-transcribe": { type: "boolean", description: "Skip whisper transcription" },
-        "human-friendly": { type: "boolean", description: "Enable interactive terminal UI" }
+        video: {
+          type: "string",
+          description: "Path to a video file (MP4, WebM, MOV)",
+          alias: "V"
+        },
+        audio: {
+          type: "string",
+          description: "Path to an audio file (MP3, WAV, M4A)",
+          alias: "a"
+        },
+        "skip-skills": {
+          type: "boolean",
+          description: "Skip AI coding skills installation"
+        },
+        "skip-transcribe": {
+          type: "boolean",
+          description: "Skip whisper transcription"
+        },
+        "non-interactive": {
+          type: "boolean",
+          description: "Disable interactive prompts (for CI/agents)"
+        }
       },
       async run({ args }) {
         const templateFlag = args.template;
@@ -24557,21 +24652,16 @@ Examples:
         const audioFlag = args.audio;
         const skipSkills = args["skip-skills"] === true;
         const skipTranscribe = args["skip-transcribe"] === true;
-        const humanFriendly = args["human-friendly"] === true;
-        if (!humanFriendly) {
-          if (!templateFlag) {
-            console.error(c.error("Missing required flag: --template"));
-            console.error(`Available: ${ALL_TEMPLATE_IDS.join(", ")}`);
-            console.error(`
-Example: hyperframes init my-video --template blank --video video.mp4`);
-            process.exit(1);
-          }
-          if (!ALL_TEMPLATE_IDS.includes(templateFlag)) {
-            console.error(c.error(`Unknown template: ${templateFlag}`));
+        const nonInteractive = args["non-interactive"] === true;
+        const interactive = !nonInteractive && process.stdout.isTTY === true;
+        if (!interactive) {
+          const resolvedTemplate = templateFlag ?? "blank";
+          if (!ALL_TEMPLATE_IDS.includes(resolvedTemplate)) {
+            console.error(c.error(`Unknown template: ${resolvedTemplate}`));
             console.error(`Available: ${ALL_TEMPLATE_IDS.join(", ")}`);
             process.exit(1);
           }
-          const templateId2 = templateFlag;
+          const templateId2 = resolvedTemplate;
           const name2 = args.name ?? "my-video";
           const destDir2 = resolve14(name2);
           if (existsSync26(destDir2) && readdirSync7(destDir2).length > 0) {
@@ -24706,7 +24796,11 @@ Example: hyperframes init my-video --template blank --video video.mp4`);
             options: [
               { value: "video", label: "Video", hint: "MP4, WebM, MOV" },
               { value: "audio", label: "Audio only", hint: "MP3, WAV, M4A" },
-              { value: "no", label: "No", hint: "Start with motion graphics or text" }
+              {
+                value: "no",
+                label: "No",
+                hint: "Start with motion graphics or text"
+              }
             ],
             initialValue: "no"
           });
@@ -24763,7 +24857,9 @@ Example: hyperframes init my-video --template blank --video video.mp4`);
               await ensureWhisper2({
                 onProgress: (msg) => spin.message(msg)
               });
-              await ensureModel2(void 0, { onProgress: (msg) => spin.message(msg) });
+              await ensureModel2(void 0, {
+                onProgress: (msg) => spin.message(msg)
+              });
               spin.message("Transcribing audio...");
               const { transcribe: runTranscribe } = await Promise.resolve().then(() => (init_transcribe(), transcribe_exports));
               const transcribeResult = await runTranscribe(sourceFilePath, destDir, {
@@ -24779,21 +24875,29 @@ Example: hyperframes init my-video --template blank --video video.mp4`);
             }
           }
         }
-        const defaultTemplate = isAudioOnly ? "warm-grain" : "blank";
-        const templateResult = await Jt({
-          message: "Pick a template",
-          options: TEMPLATES.map((t2) => ({
-            value: t2.id,
-            label: t2.label,
-            hint: t2.hint
-          })),
-          initialValue: defaultTemplate
-        });
-        if (Ct(templateResult)) {
-          Nt("Setup cancelled.");
-          process.exit(0);
+        let templateId;
+        if (templateFlag && ALL_TEMPLATE_IDS.includes(templateFlag)) {
+          templateId = templateFlag;
+        } else {
+          if (templateFlag) {
+            R2.warn(`Unknown template "${templateFlag}" \u2014 pick from the list below`);
+          }
+          const defaultTemplate = isAudioOnly ? "warm-grain" : "blank";
+          const templateResult = await Jt({
+            message: "Pick a template",
+            options: TEMPLATES.map((t2) => ({
+              value: t2.id,
+              label: t2.label,
+              hint: t2.hint
+            })),
+            initialValue: defaultTemplate
+          });
+          if (Ct(templateResult)) {
+            Nt("Setup cancelled.");
+            process.exit(0);
+          }
+          templateId = templateResult;
         }
-        const templateId = templateResult;
         scaffoldProject(destDir, name, templateId, localVideoName, videoDuration);
         trackInitTemplate(templateId);
         const transcriptFile = resolve14(destDir, "transcript.json");

package/dist/skills/compose-video/SKILL.md

@@ -137,6 +137,7 @@ Video must be `muted playsinline`. Audio is always a separate `<audio>` element:
 - From sub-compositions, use `../` to reference root files
 
 For PiP, title cards, and slide show patterns, see [patterns.md](./patterns.md).
+For data, stats, and infographics, see [data-in-motion.md](./data-in-motion.md).
 
 ## Output Checklist
 

package/dist/skills/compose-video/data-in-motion.md

@@ -0,0 +1,19 @@
+# Data in Motion
+
+Light guidance for data and stats in video compositions. The [house style](./house-style.md) handles aesthetics — this just addresses data-specific pitfalls.
+
+## Visual Continuity
+
+When successive stats belong to the same concept (Q1 → Q2 → Q3 → Q4, or three metrics for the same product), keep them in the same visual space with the same aesthetic. Only the VALUE changes. An aesthetic change should signal a new concept, not just a new number.
+
+## Numbers Need Visual Weight
+
+A number on its own floats in empty space. Pair every metric with a visual element that gives it presence — a proportional fill bar, a background color shift, a shape that represents the value, a progress ring. The visual doesn't need to be a chart — it just needs to fill the frame and make the data feel tangible rather than just text on a background.
+
+## Avoid Web Patterns
+
+- **No pie charts** — hard to compare, looks like PowerPoint
+- **No multi-axis charts** — viewer can't study intersections in a 3-second window
+- **No 6-panel dashboards** — 2-3 related metrics side-by-side is fine, 6+ is a web pattern
+- **No gridlines, tick marks, or legends** — visual noise that adds nothing in motion
+- **No chart library output** — build with GSAP + SVG/CSS, not D3 or Chart.js

package/dist/skills/compose-video/house-style.md

@@ -7,7 +7,8 @@ Defaults when no `visual-style.md` or animation direction is provided. These rai
 1. **Interpret the prompt.** Generate real content for the topic — don't use the prompt text as body copy. A recipe lists real ingredients. A stats dashboard shows the actual numbers given. A product showcase names real features and specs. A sci-fi HUD has actual crosshairs and readouts, not a heading that says "sci-fi HUD."
 2. **Pick a palette.** First decide: does this content call for a light or dark canvas? Food, weddings, children, wellness, education, lifestyle, nature, and celebrations → light palette (Warm/Editorial, Clean/Corporate, Nature/Earth, Pastel/Soft). Tech, finance, cinema, nightlife, horror, gaming, and premium → dark palette. Then load the file and pick one palette. Declare your bg, fg, and accent colors before writing any code.
 3. **Pick a typeface.** Don't reach for Sora, Space Grotesk, Outfit, Playfair Display, Cormorant Garamond, or Bodoni Moda — they're overused. Explore the full range of Google Fonts. Serif for editorial, mono for technical, display for impact, handwritten for personal.
-4. **Pick your entrance patterns.** Plan how elements enter — never use the same entrance pattern twice in a composition.
+4. **Pick a layout approach.** Don't default to the same structure every time. Options: full-bleed centered hero, left-aligned editorial column, split-frame (content left / visual right or vice versa), scattered/asymmetric positioning, grid-based with uneven cells, stacked vertical sections. Vary this across compositions.
+5. **Pick your entrance patterns.** Plan how elements enter — never use the same entrance pattern twice in a composition.
 
 ## Motion
 
@@ -85,7 +86,7 @@ Flat single-color backgrounds look digital. Avoid pure solid backgrounds — add
 
 Beyond choosing a typeface:
 
-- **Weight contrast** — pair a heavy weight (700-900) headline with a light weight (300-400) body. Don't use the same weight on everything.
+- **Weight contrast** — pair a heavy weight (700-900) headline with a light weight (300-400) body. Always use at least two explicit font-weight values — even with display fonts that look bold by default, set labels or secondary text to a lighter weight.
 - **Case deliberately** — ALL CAPS for labels and short text (under 5 words). Sentence case for longer text. Don't uppercase paragraphs.
 - **Tracking** — tight tracking (-0.02em) on large headlines. Normal or wide tracking on small labels.
 - **One typeface, two weights** — don't mix typefaces unless you have a reason. One family at two weights creates more hierarchy than two families at one weight each.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hyperframes",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "HyperFrames CLI — create, preview, and render HTML video compositions",
   "repository": {
     "type": "git",