hyperframes 0.7.3 → 0.7.4

package/dist/cli.js

@@ -50,7 +50,7 @@ var VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    VERSION = true ? "0.7.3" : "0.0.0-dev";
+    VERSION = true ? "0.7.4" : "0.0.0-dev";
   }
 });
 
@@ -26253,13 +26253,49 @@ function cssTransformToGsapProps(cssTransform) {
   }
   return parts.length > 0 ? parts.join(", ") : null;
 }
-var SCENE_BOUNDARY_EPSILON_SECONDS, gsapWindowsCache, gsapRules;
+function targetedSelectorTokens(selector) {
+  const tokens = /* @__PURE__ */ new Set();
+  for (const group of selector.split(",")) {
+    const compounds = group.trim().split(/[\s>+~]+/).filter(Boolean);
+    const last = compounds[compounds.length - 1];
+    if (!last) continue;
+    const simple2 = last.match(/[#.][A-Za-z0-9_-]+/g);
+    if (simple2) for (const token of simple2) tokens.add(token);
+  }
+  return tokens;
+}
+function matchCssTransform(gsapSelector, cssMap) {
+  if (cssMap.size === 0) return void 0;
+  const direct = cssMap.get(gsapSelector);
+  if (direct) return direct;
+  const tokens = targetedSelectorTokens(gsapSelector);
+  for (const [cssSelector, value] of cssMap) {
+    if (tokens.has(cssSelector)) return value;
+  }
+  return void 0;
+}
+function extractStandaloneGsapTransformCalls(script) {
+  const calls = [];
+  const pattern = /gsap\.(set|to|from|fromTo)\s*\(\s*(["'])([^"']+)\2\s*,\s*\{([^{}]*)\}/g;
+  let match;
+  while ((match = pattern.exec(script)) !== null) {
+    const method = match[1] ?? "set";
+    const selector = match[3] ?? "";
+    const propsBody = match[4] ?? "";
+    const properties = [...propsBody.matchAll(/([A-Za-z_$][\w$]*)\s*:/g)].map((m2) => m2[1] ?? "");
+    calls.push({ method, selector, properties, raw: truncateSnippet(match[0]) ?? match[0] });
+  }
+  return calls;
+}
+var SCENE_BOUNDARY_EPSILON_SECONDS, gsapWindowsCache, CONFLICTING_TRANSLATE_PROPS, CONFLICTING_SCALE_PROPS, gsapRules;
 var init_gsap = __esm({
   "../core/src/lint/rules/gsap.ts"() {
     "use strict";
     init_utils2();
     SCENE_BOUNDARY_EPSILON_SECONDS = 0.05;
     gsapWindowsCache = /* @__PURE__ */ new Map();
+    CONFLICTING_TRANSLATE_PROPS = ["x", "y", "xPercent", "yPercent"];
+    CONFLICTING_SCALE_PROPS = ["scale", "scaleX", "scaleY"];
     gsapRules = [
       // overlapping_gsap_tweens + gsap_animates_clip_element + unscoped_gsap_selector
       // fallow-ignore-next-line complexity
@@ -26413,22 +26449,30 @@ ${right.raw}`)
         for (const script of scripts) {
           if (!/gsap\.timeline/.test(script.content)) continue;
           const windows = await cachedExtractGsapWindows(script.content);
+          const calls = [
+            ...windows.map((win) => ({
+              method: win.method,
+              selector: win.targetSelector,
+              properties: win.properties,
+              raw: win.raw
+            })),
+            ...extractStandaloneGsapTransformCalls(stripJsComments(script.content))
+          ];
           const conflicts = /* @__PURE__ */ new Map();
-          for (const win of windows) {
-            if (win.method === "fromTo" || win.method === "from") continue;
-            const sel = win.targetSelector;
-            const cssKey = sel.startsWith("#") || sel.startsWith(".") ? sel : `#${sel}`;
-            const translateProps = win.properties.filter(
-              (p2) => ["x", "y", "xPercent", "yPercent"].includes(p2)
+          for (const call of calls) {
+            if (call.method === "fromTo" || call.method === "from") continue;
+            const sel = call.selector;
+            const translateProps = call.properties.filter(
+              (p2) => CONFLICTING_TRANSLATE_PROPS.includes(p2)
             );
-            const scaleProps = win.properties.filter((p2) => p2 === "scale");
-            const cssFromTranslate = translateProps.length > 0 ? cssTranslateSelectors.get(cssKey) : void 0;
-            const cssFromScale = scaleProps.length > 0 ? cssScaleSelectors.get(cssKey) : void 0;
+            const scaleProps = call.properties.filter((p2) => CONFLICTING_SCALE_PROPS.includes(p2));
+            const cssFromTranslate = translateProps.length > 0 ? matchCssTransform(sel, cssTranslateSelectors) : void 0;
+            const cssFromScale = scaleProps.length > 0 ? matchCssTransform(sel, cssScaleSelectors) : void 0;
             if (!cssFromTranslate && !cssFromScale) continue;
             const existing = conflicts.get(sel) ?? {
               cssTransform: [cssFromTranslate, cssFromScale].filter(Boolean).join(" "),
               props: /* @__PURE__ */ new Set(),
-              raw: win.raw
+              raw: call.raw
             };
             for (const p2 of [...translateProps, ...scaleProps]) existing.props.add(p2);
             conflicts.set(sel, existing);
@@ -26925,6 +26969,35 @@ function isCompositionRootOrMount(rawTag) {
     readAttr(rawTag, "data-composition-id") || readAttr(rawTag, "data-composition-src")
   );
 }
+function extractCssSelectors(css) {
+  const out = [];
+  const noComments = css.replace(/\/\*[\s\S]*?\*\//g, "");
+  const ruleHeader = /([^{}]+)\{/g;
+  let m2;
+  while ((m2 = ruleHeader.exec(noComments)) !== null) {
+    const header = (m2[1] ?? "").trim();
+    if (!header || header.startsWith("@")) continue;
+    for (const sel of header.split(",")) {
+      const s2 = sel.trim();
+      if (s2) out.push(s2);
+    }
+  }
+  return out;
+}
+function leftmostCompoundClasses(selector) {
+  const leftmost = selector.trim().split(/[\s>+~]+/)[0] ?? "";
+  return (leftmost.match(/\.([\w-]+)/g) ?? []).map((c3) => c3.slice(1));
+}
+function rootClassStyledSelectors(styles, rootClasses) {
+  const offenders = [];
+  for (const style of styles) {
+    for (const selector of extractCssSelectors(style.content)) {
+      const hitsRoot = leftmostCompoundClasses(selector).some((c3) => rootClasses.includes(c3));
+      if (hitsRoot && !offenders.includes(selector)) offenders.push(selector);
+    }
+  }
+  return offenders;
+}
 var MAX_COMPOSITION_LINES, MAX_TIMED_ELEMENTS_PER_TRACK, TRACK_DENSITY_EXEMPT_TAGS, compositionRules;
 var init_composition = __esm({
   "../core/src/lint/rules/composition.ts"() {
@@ -27377,6 +27450,39 @@ var init_composition = __esm({
           });
         }
         return findings;
+      },
+      // subcomposition_root_styled_by_class
+      // A sub-composition's <style> is scoped at render time to
+      // `[data-composition-id="<id>"] <selector>` so scenes inlined into one document
+      // can't leak styles into each other. A rule whose LEFTMOST selector is the ROOT
+      // element's own class (e.g. `.frame { ... }` on the same element that carries
+      // data-composition-id) therefore becomes a DESCENDANT selector that can never
+      // match the root — the whole scene renders unstyled (tiny text top-left, images
+      // at natural size). lint/validate/inspect evaluate the file in isolation (no
+      // scoping) and Studio previews each scene in its own iframe (no scoping), so the
+      // break is invisible until the composited MP4 render. Style the root via `#root`
+      // (the scoper special-cases the root id) and descendants via plain selectors,
+      // like the registry blocks — the runtime already scopes each scene by id, so a
+      // class namespace on the root is redundant.
+      ({ rootTag, rootCompositionId, styles, options }) => {
+        if (!options.isSubComposition) return [];
+        if (isRegistrySourceFile(options.filePath)) return [];
+        if (!rootTag || !rootCompositionId) return [];
+        const rootClasses = (readAttr(rootTag.raw, "class") || "").split(/\s+/).filter(Boolean);
+        if (rootClasses.length === 0) return [];
+        const offenders = rootClassStyledSelectors(styles, rootClasses);
+        if (offenders.length === 0) return [];
+        const example = offenders.slice(0, 3).join(", ");
+        return [
+          {
+            code: "subcomposition_root_styled_by_class",
+            severity: "error",
+            message: `Root element has class="${rootClasses.join(" ")}" and is styled by ${offenders.length} rule(s) keyed off that class (e.g. ${example}). At render, every sub-composition rule is scoped to [data-composition-id="${rootCompositionId}"] <selector>, so a selector whose leftmost part is the ROOT's own class becomes a descendant selector that cannot match the root \u2014 the scene renders unstyled (tiny text top-left, full-size images). lint/validate/inspect and Studio's per-frame iframe preview do not scope, so this passes every static check and looks correct in preview.`,
+            selector: example,
+            fixHint: `Give the root id="root" and style it with \`#root { ... }\` plus plain descendant selectors (\`.kicker\`, \`#hero\`) \u2014 the runtime already scopes each sub-composition by data-composition-id, so a class namespace on the root is redundant and breaks under scoping.`,
+            snippet: truncateSnippet(rootTag.raw)
+          }
+        ];
       }
     ];
   }
@@ -33175,11 +33281,10 @@ async function pageScreenshotCapture(page, options) {
     format: isPng ? "png" : "jpeg",
     quality: isPng ? void 0 : options.quality ?? 80,
     fromSurface: true,
-    // The explicit clip rect constrains output to exact composition
-    // dimensions. The viewport-boundary pre-clip from captureBeyondViewport:
-    // false is redundant, and Chrome's compositor rounds it inward under
-    // multi-tab load — clipping the bottom/right edge of tall viewports.
-    captureBeyondViewport: true,
+    // Use Chrome's faster viewport-bound screenshot path by default. Callers
+    // opt into the beyond-viewport path only for known compositor edge cases,
+    // such as native video surfaces in tall portrait renders.
+    captureBeyondViewport: options.captureBeyondViewport ?? false,
     optimizeForSpeed: !isPng,
     clip
   });
@@ -33194,8 +33299,8 @@ async function captureScreenshotWithAlpha(page, width, height) {
     const result = await client.send("Page.captureScreenshot", {
       format: "png",
       fromSurface: true,
+      // Preserve the #1094 tall-portrait edge-clipping guard on HDR alpha captures.
       captureBeyondViewport: true,
-      // see pageScreenshotCapture for rationale
       optimizeForSpeed: false,
       // `true` uses a zero-alpha-aware fast path that crushes real alpha values — observed empirically, CDP docs don't spell it out
       clip: { x: 0, y: 0, width, height, scale: 1 }
@@ -33224,8 +33329,8 @@ async function captureAlphaPng(page, width, height) {
   const result = await client.send("Page.captureScreenshot", {
     format: "png",
     fromSurface: true,
+    // Preserve the #1094 tall-portrait edge-clipping guard on HDR alpha captures.
     captureBeyondViewport: true,
-    // see pageScreenshotCapture for rationale
     optimizeForSpeed: false,
     // must be false to preserve alpha
     clip: { x: 0, y: 0, width, height, scale: 1 }
@@ -37049,21 +37154,6 @@ function defaultBuildScopeSelector(compId) {
   const escaped = compId.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
   return `[data-composition-id="${escaped}"]`;
 }
-function emptyCompositionHtmlError(src) {
-  return new Error(
-    `Composition HTML is empty or could not be parsed: ${src}. Check that the file referenced by data-composition-src contains valid HTML.`
-  );
-}
-function assertNonEmptyCompositionHtml(html, src) {
-  if (!html.trim()) {
-    throw emptyCompositionHtmlError(src);
-  }
-}
-function assertParsedCompositionDocument(doc, src) {
-  if (!doc.documentElement) {
-    throw emptyCompositionHtmlError(src);
-  }
-}
 function inlineSubCompositions(document2, hosts, options) {
   const {
     resolveHtml,
@@ -37089,15 +37179,15 @@ function inlineSubCompositions(document2, hosts, options) {
     const src = hostEl.getAttribute("data-composition-src");
     if (!src) continue;
     const compHtml = resolveHtml(src);
-    if (compHtml == null) {
-      if (onMissingComposition) {
-        onMissingComposition(src);
-      }
+    if (compHtml == null || !compHtml.trim()) {
+      onMissingComposition?.(src);
       continue;
     }
-    assertNonEmptyCompositionHtml(compHtml, src);
     const compDoc = parseHtml2(compHtml);
-    assertParsedCompositionDocument(compDoc, src);
+    if (!compDoc.documentElement) {
+      onMissingComposition?.(src);
+      continue;
+    }
     let compId;
     let runtimeCompId;
     if (hostIdentityMap) {
@@ -37110,9 +37200,15 @@ function inlineSubCompositions(document2, hosts, options) {
     }
     const contentRoot = compDoc.querySelector("template");
     const contentHtml = contentRoot ? contentRoot.innerHTML || "" : compDoc.body?.innerHTML || "";
-    assertNonEmptyCompositionHtml(contentHtml, src);
+    if (!contentHtml.trim()) {
+      onMissingComposition?.(src);
+      continue;
+    }
     const contentDoc = parseHtml2(contentHtml);
-    assertParsedCompositionDocument(contentDoc, src);
+    if (!contentDoc.documentElement) {
+      onMissingComposition?.(src);
+      continue;
+    }
     const innerRoot = compId ? queryByAttr(contentDoc, "data-composition-id", compId) : contentDoc.querySelector("[data-composition-id]");
     const inferredCompId = innerRoot?.getAttribute("data-composition-id")?.trim() || "";
     const authoredRootId = innerRoot?.getAttribute("id")?.trim() || null;
@@ -45203,6 +45299,7 @@ __export(manager_exports, {
   ensureModel: () => ensureModel,
   ensureWhisper: () => ensureWhisper,
   findWhisper: () => findWhisper,
+  getInstallInstructions: () => getInstallInstructions,
   hasFFmpeg: () => hasFFmpeg,
   isWhisperUnavailable: () => isWhisperUnavailable
 });
@@ -45309,6 +45406,12 @@ function getInstallInstructions() {
   if (platform4() === "darwin") {
     return "brew install whisper-cpp";
   }
+  if (platform4() === "linux") {
+    return "Build from source: https://github.com/ggml-org/whisper.cpp#building (requires cmake and a C compiler)";
+  }
+  if (platform4() === "win32") {
+    return "Build with cmake: https://github.com/ggml-org/whisper.cpp#building";
+  }
   return "See https://github.com/ggml-org/whisper.cpp#building";
 }
 function hasBrew() {
@@ -45910,7 +46013,8 @@ var init_npxCommand = __esm({
 // src/commands/skills.ts
 var skills_exports = {};
 __export(skills_exports, {
-  default: () => skills_default
+  default: () => skills_default,
+  installAllSkills: () => installAllSkills
 });
 import { execFileSync as execFileSync4, spawn as spawn7 } from "child_process";
 function hasNpx() {
@@ -45922,12 +46026,13 @@ function hasNpx() {
     return false;
   }
 }
-function runSkillsAdd(repo) {
-  const npx = buildNpxCommand(["skills", "add", repo, "--all"]);
+function runSkillsAdd(repo, opts = {}) {
+  const npx = buildNpxCommand(["skills", "add", repo, ...opts.extraArgs ?? ["--all"]]);
   return new Promise((resolve58, reject) => {
     const child = spawn7(npx.command, npx.args, {
       stdio: "inherit",
       timeout: 12e4,
+      cwd: opts.cwd,
       // GH #316 — the upstream `skills` CLI shells out to `git clone`.
       // When Git's clone-hook protection is active (shipped on by
       // default in 2.45.1, reverted in 2.45.2, still present on many
@@ -45945,6 +46050,22 @@ function runSkillsAdd(repo) {
     child.on("error", reject);
   });
 }
+async function installAllSkills(opts = {}) {
+  if (!hasNpx()) {
+    R2.error(c.error("npx not found. Install Node.js and retry."));
+    return;
+  }
+  for (const source of SOURCES) {
+    console.log();
+    console.log(c.bold(`Installing ${source.name} skills...`));
+    console.log();
+    try {
+      await runSkillsAdd(source.repo, opts);
+    } catch {
+      console.log(c.dim(`${source.name} skills skipped`));
+    }
+  }
+}
 var SOURCES, skills_default;
 var init_skills = __esm({
   "src/commands/skills.ts"() {
@@ -45961,20 +46082,7 @@ var init_skills = __esm({
       },
       args: {},
       async run() {
-        if (!hasNpx()) {
-          R2.error(c.error("npx not found. Install Node.js and retry."));
-          return;
-        }
-        for (const source of SOURCES) {
-          console.log();
-          console.log(c.bold(`Installing ${source.name} skills...`));
-          console.log();
-          try {
-            await runSkillsAdd(source.repo);
-          } catch {
-            console.log(c.dim(`${source.name} skills skipped`));
-          }
-        }
+        await installAllSkills();
       }
     });
   }
@@ -46171,7 +46279,16 @@ async function lintProject(project) {
   const allHtmlSources = [{ html: rootHtml }];
   const compositionsDir = resolve12(project.dir, "compositions");
   if (existsSync22(compositionsDir)) {
-    const files = readdirSync8(compositionsDir).filter((f3) => f3.endsWith(".html"));
+    const collectHtmlFiles = (dir, rel) => {
+      const out = [];
+      for (const entry of readdirSync8(dir, { withFileTypes: true })) {
+        const relPath = rel ? `${rel}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) out.push(...collectHtmlFiles(join21(dir, entry.name), relPath));
+        else if (entry.isFile() && entry.name.endsWith(".html")) out.push(relPath);
+      }
+      return out;
+    };
+    const files = collectHtmlFiles(compositionsDir, "").sort();
     for (const file of files) {
       const filePath = join21(compositionsDir, file);
       const html = readFileSync15(filePath, "utf-8");
@@ -93728,7 +93845,16 @@ var init_fileServer2 = __esm({
     var root = document.querySelector('[data-composition-id]');
     if (!root) return 0;
     var d = Number(root.getAttribute('data-duration'));
-    return Number.isFinite(d) && d > 0 ? d : 0;
+    if (Number.isFinite(d) && d > 0) return d;
+    var comps = document.querySelectorAll('[data-composition-src]');
+    var maxEnd = 0;
+    for (var i = 0; i < comps.length; i++) {
+      var start = Number(comps[i].getAttribute('data-start')) || 0;
+      var dur = Number(comps[i].getAttribute('data-duration')) || 0;
+      if (dur > 0) maxEnd = Math.max(maxEnd, start + dur);
+    }
+    if (maxEnd > 0) console.warn('[HF Bridge] No root data-duration; derived ' + maxEnd + 's from sub-compositions');
+    return maxEnd;
   }
   function seekSameOriginChildFrames(frameWindow, nextTimeMs) {
     var frames;
@@ -95272,7 +95398,10 @@ function inlineSubCompositions2(html, subCompositions, projectDir) {
       },
       parseHtml: (htmlStr) => parseHTML(htmlStr).document,
       scriptErrorLabel: "[Compiler] Composition script failed",
-      compoundAuthoredRoot: true
+      compoundAuthoredRoot: true,
+      onMissingComposition: (srcPath) => {
+        console.warn(`[Compiler] Composition file missing or empty: ${srcPath}`);
+      }
     }
   );
   for (const hostEl of hosts) {
@@ -99550,6 +99679,12 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
     job.startedAt = /* @__PURE__ */ new Date();
     assertNotAborted();
     assertConfiguredFfmpegBinariesExist();
+    if (!existsSync45(workDir)) mkdirSync26(workDir, { recursive: true });
+    if (job.config.debug) {
+      const logPath = join55(workDir, "render.log");
+      restoreLogger = installDebugLogger(logPath, log2);
+      log2.info("[Render] Debug artifacts enabled", { workDir, logPath });
+    }
     log2.info("[Render] Pipeline started", {
       platform: process.platform,
       arch: process.arch,
@@ -99574,11 +99709,6 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
       playerReadyTimeoutMs: cfg.playerReadyTimeout,
       requestedWorkers: job.config.workers ?? "auto"
     });
-    if (!existsSync45(workDir)) mkdirSync26(workDir, { recursive: true });
-    if (job.config.debug) {
-      const logPath = join55(workDir, "render.log");
-      restoreLogger = installDebugLogger(logPath, log2);
-    }
     const entryFile = job.config.entryFile || "index.html";
     let htmlPath = join55(projectDir, entryFile);
     if (!existsSync45(htmlPath)) {
@@ -99796,8 +99926,12 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
       format: needsAlpha ? "png" : "jpeg",
       quality: needsAlpha ? void 0 : job.config.quality === "draft" ? 80 : 95,
       variables: job.config.variables,
-      deviceScaleFactor
+      deviceScaleFactor,
+      captureBeyondViewport: composition.videos.length > 0
     };
+    updateCaptureObservability({
+      captureBeyondViewport: captureOptions.captureBeyondViewport ?? false
+    });
     const buildCaptureOptions = () => ({
       ...captureOptions,
       videoMetadataHints,
@@ -99926,6 +100060,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
     observability.checkpoint("capture_strategy", "resolved", {
       workerCount,
       forceScreenshot: captureForceScreenshot,
+      captureBeyondViewport: captureOptions.captureBeyondViewport ?? false,
       useStreamingEncode,
       useLayeredComposite,
       usePageSideCompositing: usePageSideCompositingForTransitions,
@@ -102036,6 +102171,7 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath) {
       // declare `data-composition-variables` leave this undefined and the
       // engine skips the `evaluateOnNewDocument` injection.
       variables: encoder.variables,
+      captureBeyondViewport: (planVideos?.videos.length ?? 0) > 0,
       // lock the BeginFrame warmup loop to a fixed iteration count so
       // `beginFrameTimeTicks` is host-independent. Only chunks ever set this.
       lockWarmupTicks: true
@@ -104527,11 +104663,22 @@ var init_init = __esm({
           for (const f3 of readdirSync23(destDir2).filter((f4) => !f4.startsWith("."))) {
             console.log(`  ${c.accent(f3)}`);
           }
+          if (!skipSkills) {
+            const { installAllSkills: installAllSkills2 } = await Promise.resolve().then(() => (init_skills(), skills_exports));
+            const args2 = process.env["CLAUDECODE"] ? ["--agent", "claude-code", "--yes"] : ["--yes"];
+            await installAllSkills2({ cwd: destDir2, extraArgs: args2 });
+          }
           console.log();
           console.log("Get started:");
           console.log();
-          console.log(`  ${c.accent("1.")} Install AI coding skills (one-time):`);
-          console.log(`     ${c.accent("npx skills add heygen-com/hyperframes")}`);
+          if (skipSkills) {
+            console.log(`  ${c.accent("1.")} Install AI coding skills (one-time):`);
+            console.log(`     ${c.accent("npx skills add heygen-com/hyperframes --yes")}`);
+          } else {
+            console.log(
+              `  ${c.accent("1.")} Restart your AI agent (new session) so it loads the skills.`
+            );
+          }
           console.log();
           console.log(`  ${c.accent("2.")} Open this project with your AI coding agent:`);
           console.log(
@@ -104718,8 +104865,8 @@ ${c.dim("Use --example blank for offline use.")}`
             process.exit(0);
           }
           if (installSkills) {
-            const skillsCmd = await Promise.resolve().then(() => (init_skills(), skills_exports)).then((m2) => m2.default);
-            await runCommand(skillsCmd, { rawArgs: [] });
+            const { installAllSkills: installAllSkills2 } = await Promise.resolve().then(() => (init_skills(), skills_exports));
+            await installAllSkills2({ cwd: destDir });
           }
         }
         R2.info("Opening studio preview...");
@@ -106649,6 +106796,10 @@ function buildDockerRunArgs(input2) {
     `${projectDir}:/project:ro`,
     "-v",
     `${outputDir}:/output`,
+    // Keep debug artifacts on the mounted host output path. The producer roots
+    // `.debug` at dirname(PRODUCER_RENDERS_DIR), so `/output/renders` maps to
+    // `/output/.debug/<job id>` instead of a disposable container path.
+    ...options.debug ? ["-e", "PRODUCER_RENDERS_DIR=/output/renders"] : [],
     imageTag,
     "/project",
     "--output",
@@ -106666,6 +106817,7 @@ function buildDockerRunArgs(input2) {
     ...options.videoBitrate ? ["--video-bitrate", options.videoBitrate] : [],
     ...options.videoFrameFormat && options.videoFrameFormat !== "auto" ? ["--video-frame-format", options.videoFrameFormat] : [],
     ...options.quiet ? ["--quiet"] : [],
+    ...options.debug ? ["--debug"] : [],
     ...options.gpu ? ["--gpu"] : [],
     ...options.browserGpu ? [] : ["--no-browser-gpu"],
     ...options.hdrMode === "force-hdr" ? ["--hdr"] : [],
@@ -107413,6 +107565,7 @@ async function renderDocker(projectDir, outputPath, options) {
       entryFile: options.entryFile,
       outputResolution: options.outputResolution,
       pageSideCompositing: options.pageSideCompositing,
+      debug: options.debug,
       pageNavigationTimeoutMs: options.pageNavigationTimeoutMs
     }
   });
@@ -107480,7 +107633,7 @@ async function renderLocal(projectDir, outputPath, options) {
   const producer = await loadProducer();
   const startTime = Date.now();
   const logger = createRenderTelemetryLogger(
-    producer.createConsoleLogger?.("info") ?? createNoopProducerLogger()
+    producer.createConsoleLogger?.(options.debug ? "debug" : "info") ?? createNoopProducerLogger()
   );
   const job = producer.createRenderJob({
     fps: options.fps,
@@ -107503,7 +107656,8 @@ async function renderLocal(projectDir, outputPath, options) {
     videoFrameFormat: options.videoFrameFormat,
     variables: options.variables,
     entryFile: options.entryFile,
-    outputResolution: options.outputResolution
+    outputResolution: options.outputResolution,
+    debug: options.debug
   });
   const onProgress = options.quiet ? void 0 : (progressJob, message) => {
     renderProgress(progressJob.progress, message);
@@ -107882,6 +108036,11 @@ var init_render2 = __esm({
           description: "Suppress verbose output",
           default: false
         },
+        debug: {
+          type: "boolean",
+          description: "Write full render diagnostics and keep intermediate artifacts under the producer .debug directory.",
+          default: false
+        },
         strict: {
           type: "boolean",
           description: "Fail render on lint errors",
@@ -108109,6 +108268,7 @@ var init_render2 = __esm({
         const browserGpuArg = args["browser-gpu"];
         const browserGpuMode = resolveBrowserGpuForCli(useDocker, browserGpuArg);
         const quiet = args.quiet ?? false;
+        const debug = args.debug ?? false;
         const batchJson = args.json ?? false;
         const effectiveQuiet = quiet || batchPath != null && batchJson;
         const strictAll = args["strict-all"] ?? false;
@@ -108280,6 +108440,7 @@ var init_render2 = __esm({
             pageNavigationTimeoutMs,
             protocolTimeout,
             playerReadyTimeout,
+            debug,
             exitAfterComplete: false,
             throwOnError: true,
             skipFeedback: true
@@ -108323,6 +108484,7 @@ var init_render2 = __esm({
             videoBitrate,
             videoFrameFormat,
             quiet,
+            debug,
             variables,
             entryFile,
             outputResolution,
@@ -108348,6 +108510,7 @@ var init_render2 = __esm({
             videoFrameFormat,
             quiet,
             browserPath,
+            debug,
             variables,
             entryFile,
             outputResolution,
@@ -112167,6 +112330,18 @@ function checkEnvironment() {
   }
   return { ok: true, detail: parts.join(" \xB7 ") };
 }
+async function checkWhisper() {
+  const { findWhisper: findWhisper2, getInstallInstructions: getInstallInstructions2 } = await Promise.resolve().then(() => (init_manager(), manager_exports));
+  const result = findWhisper2();
+  if (result) {
+    return { ok: true, detail: result.executablePath };
+  }
+  return {
+    ok: false,
+    detail: "Not found (optional \u2014 needed for transcription)",
+    hint: getInstallInstructions2()
+  };
+}
 function redactHome(s2) {
   const home = process.env["HOME"] || process.env["USERPROFILE"];
   if (!home) return s2;
@@ -112221,6 +112396,7 @@ var init_doctor = __esm({
           checks.push({ name: "/dev/shm", run: checkShm });
         }
         checks.push({ name: "Environment", run: checkEnvironment });
+        checks.push({ name: "whisper-cpp", run: checkWhisper });
         const outcomes = [];
         for (const check of checks) {
           const result = await check.run();
@@ -112541,6 +112717,58 @@ Run ${c.accent("hyperframes telemetry --help")} for usage.`
   }
 });
 
+// src/commands/events.ts
+var events_exports2 = {};
+__export(events_exports2, {
+  default: () => events_default
+});
+var ALLOWED_EVENTS, ALLOWED_OUTCOMES, SKILL_SLUG, events_default;
+var init_events2 = __esm({
+  "src/commands/events.ts"() {
+    "use strict";
+    init_dist();
+    init_client();
+    ALLOWED_EVENTS = ["skill_invoked", "skill_completed"];
+    ALLOWED_OUTCOMES = ["success", "error", "abort"];
+    SKILL_SLUG = /^[a-z0-9][a-z0-9-]{0,63}$/;
+    events_default = defineCommand({
+      meta: {
+        name: "events",
+        description: "Emit an anonymous skill-usage telemetry event (skills report their own invocation/outcome). Honors DO_NOT_TRACK / telemetry opt-out."
+      },
+      args: {
+        skill: {
+          type: "string",
+          description: "Authoring skill slug, e.g. product-launch-video"
+        },
+        event: {
+          type: "string",
+          description: "Event name: skill_invoked | skill_completed (default: skill_invoked)",
+          default: "skill_invoked"
+        },
+        outcome: {
+          type: "string",
+          description: "Optional outcome for completion events: success | error | abort"
+        }
+      },
+      async run({ args }) {
+        try {
+          const skill = typeof args.skill === "string" ? args.skill.trim() : "";
+          if (!SKILL_SLUG.test(skill)) return;
+          const event = ALLOWED_EVENTS.includes(args.event) ? args.event : "skill_invoked";
+          const props = { authoring_skill: skill };
+          if (args.outcome && ALLOWED_OUTCOMES.includes(args.outcome)) {
+            props["outcome"] = args.outcome;
+          }
+          trackEvent(event, props);
+          await flush();
+        } catch {
+        }
+      }
+    });
+  }
+});
+
 // src/utils/compositionViewport.ts
 function parseViewportDimension(value) {
   if (!value) return null;
@@ -162861,6 +163089,7 @@ var commandLoaders = {
   skills: () => Promise.resolve().then(() => (init_skills(), skills_exports)).then((m2) => m2.default),
   feedback: () => Promise.resolve().then(() => (init_feedback2(), feedback_exports)).then((m2) => m2.default),
   telemetry: () => Promise.resolve().then(() => (init_telemetry(), telemetry_exports)).then((m2) => m2.default),
+  events: () => Promise.resolve().then(() => (init_events2(), events_exports2)).then((m2) => m2.default),
   validate: () => Promise.resolve().then(() => (init_validate(), validate_exports)).then((m2) => m2.default),
   snapshot: () => Promise.resolve().then(() => (init_snapshot(), snapshot_exports)).then((m2) => m2.default),
   capture: () => Promise.resolve().then(() => (init_capture2(), capture_exports2)).then((m2) => m2.default),
@@ -162891,7 +163120,7 @@ var _flushSync;
 var _trackCliError;
 var _trackCommandResult;
 var _printUpdateNotice;
-if (!isHelp && command !== "telemetry" && command !== "unknown") {
+if (!isHelp && command !== "telemetry" && command !== "events" && command !== "unknown") {
   Promise.resolve().then(() => (init_telemetry2(), telemetry_exports2)).then((mod) => {
     _flush = mod.flush;
     _flushSync = mod.flushSync;
@@ -162902,7 +163131,7 @@ if (!isHelp && command !== "telemetry" && command !== "unknown") {
     if (mod.shouldTrack()) mod.incrementCommandCount();
   });
 }
-if (!isHelp && !hasJsonFlag && command !== "upgrade") {
+if (!isHelp && !hasJsonFlag && command !== "upgrade" && command !== "events") {
   Promise.resolve().then(() => (init_autoUpdate(), autoUpdate_exports)).then((mod) => mod.reportCompletedUpdate()).catch(() => {
   });
   Promise.resolve().then(() => (init_updateCheck(), updateCheck_exports)).then(async (mod) => {