hyperframes 0.1.7 → 0.1.8

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.8" : "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

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.8",
   "description": "HyperFrames CLI — create, preview, and render HTML video compositions",
   "repository": {
     "type": "git",