hyperframes 0.7.3 → 0.7.5

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.5" : "0.0.0-dev";
   }
 });
 
@@ -25071,8 +25071,16 @@ function findHtmlTag(source) {
   };
 }
 function findRootTag(source) {
-  const bodyOpenMatch = /<body\b[^>]*>/i.exec(source);
+  const bodyOpenMatch = /<body\b([^>]*)>/i.exec(source);
   const bodyCloseMatch = /<\/body>/i.exec(source);
+  if (bodyOpenMatch && (readAttr(bodyOpenMatch[0], "data-composition-id") || readAttr(bodyOpenMatch[0], "data-width") || readAttr(bodyOpenMatch[0], "data-height"))) {
+    return {
+      raw: bodyOpenMatch[0],
+      name: "body",
+      attrs: bodyOpenMatch[1] ?? "",
+      index: bodyOpenMatch.index
+    };
+  }
   const bodyStart = bodyOpenMatch ? bodyOpenMatch.index + bodyOpenMatch[0].length : 0;
   const bodyEnd = bodyOpenMatch && bodyCloseMatch && bodyCloseMatch.index > bodyStart ? bodyCloseMatch.index : source.length;
   const bodyContent = bodyOpenMatch ? source.slice(bodyStart, bodyEnd) : source;
@@ -26137,6 +26145,30 @@ function isHiddenGsapState(values) {
   const display = stringValue(values.display)?.toLowerCase();
   return zeroValue(values.opacity) || zeroValue(values.autoAlpha) || visibility === "hidden" || display === "none";
 }
+function oneValue(values, keys2) {
+  for (const key2 of keys2) {
+    const value = values[key2];
+    if (value !== void 0) return value;
+  }
+  return void 0;
+}
+function isVisibleGsapState(values) {
+  const opacity = oneValue(values, ["opacity", "autoAlpha"]);
+  if (typeof opacity === "number") return opacity > 0;
+  if (typeof opacity === "string" && opacity.trim()) {
+    const numeric = Number(opacity);
+    if (Number.isFinite(numeric)) return numeric > 0;
+  }
+  const visibility = stringValue(values.visibility)?.toLowerCase();
+  if (visibility === "visible" || visibility === "inherit") return true;
+  const display = stringValue(values.display)?.toLowerCase();
+  if (display && display !== "none") return true;
+  return false;
+}
+function makesOverlayVisible(win) {
+  if (win.method === "from" && isHiddenGsapState(win.propertyValues)) return true;
+  return isVisibleGsapState(win.propertyValues);
+}
 function isSceneBoundaryExit(win) {
   if (win.end <= win.position) return false;
   if (win.method !== "to" && win.method !== "fromTo") return false;
@@ -26225,6 +26257,67 @@ function getSingleClassSelector(selector) {
   const match = selector.trim().match(/^\.(?<name>[A-Za-z0-9_-]+)$/);
   return match?.groups?.name || null;
 }
+function readStyleProperty(style, property) {
+  const escapedProperty = property.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const match = style.match(new RegExp(`(?:^|;)\\s*${escapedProperty}\\s*:\\s*([^;]+)`, "i"));
+  return match?.[1]?.trim() || null;
+}
+function cssZero(value) {
+  if (!value) return false;
+  return /^0(?:\.0+)?(?:px|%|vw|vh|rem|em)?$/i.test(value.trim());
+}
+function styleHasHiddenInitialState(style) {
+  const opacity = readStyleProperty(style, "opacity");
+  if (opacity && Number(opacity) === 0) return true;
+  if (readStyleProperty(style, "visibility")?.toLowerCase() === "hidden") return true;
+  if (readStyleProperty(style, "display")?.toLowerCase() === "none") return true;
+  return false;
+}
+function styleHasOpaqueBackground(style) {
+  const background = readStyleProperty(style, "background") || readStyleProperty(style, "background-color");
+  if (!background) return false;
+  const normalized = background.toLowerCase().replace(/\s+/g, "");
+  if (normalized === "transparent" || normalized === "none") return false;
+  if (/rgba?\([^)]*,0(?:\.0+)?\)$/.test(normalized)) return false;
+  if (/hsla?\([^)]*,0(?:\.0+)?\)$/.test(normalized)) return false;
+  return true;
+}
+function styleLooksFullFrameOverlay(style) {
+  const position = readStyleProperty(style, "position")?.toLowerCase();
+  if (position !== "fixed" && position !== "absolute") return false;
+  const coversFrame = cssZero(readStyleProperty(style, "inset")) || cssZero(readStyleProperty(style, "top")) && cssZero(readStyleProperty(style, "right")) && cssZero(readStyleProperty(style, "bottom")) && cssZero(readStyleProperty(style, "left"));
+  return coversFrame && styleHasOpaqueBackground(style);
+}
+function collectSimpleStyleRules(styles) {
+  const rules = /* @__PURE__ */ new Map();
+  for (const style of styles) {
+    for (const [, selectorList, body] of style.content.matchAll(/([^{}]+)\{([^}]+)\}/g)) {
+      if (!selectorList || !body) continue;
+      for (const selector of selectorList.split(",")) {
+        const token = selector.trim();
+        if (!/^[#.][A-Za-z0-9_-]+$/.test(token)) continue;
+        rules.set(token, `${rules.get(token) || ""};${body}`);
+      }
+    }
+  }
+  return rules;
+}
+function tagSimpleSelectors(tag) {
+  const selectors = [];
+  const id = readAttr(tag.raw, "id");
+  if (id) selectors.push(`#${id}`);
+  const classes = readAttr(tag.raw, "class")?.split(/\s+/).filter(Boolean) ?? [];
+  for (const className of classes) selectors.push(`.${className}`);
+  return selectors;
+}
+function combinedTagStyle(tag, styleRules) {
+  const styles = [readAttr(tag.raw, "style") || ""];
+  for (const selector of tagSimpleSelectors(tag)) {
+    const ruleStyle = styleRules.get(selector);
+    if (ruleStyle) styles.push(ruleStyle);
+  }
+  return styles.filter(Boolean).join(";");
+}
 function cssTransformToGsapProps(cssTransform) {
   const parts = [];
   const translateMatch = cssTransform.match(
@@ -26253,17 +26346,53 @@ 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
-      async ({ source, tags, scripts, rootCompositionId }) => {
+      async ({ source, tags, scripts, styles, rootCompositionId }) => {
         const findings = [];
         const clipIds = /* @__PURE__ */ new Map();
         const clipClasses = /* @__PURE__ */ new Map();
@@ -26284,6 +26413,8 @@ var init_gsap = __esm({
         }
         const classUsage = countClassUsage(tags);
         const clipStartBoundariesByComposition = collectClipStartBoundariesByComposition(source, tags);
+        const styleRules = collectSimpleStyleRules(styles);
+        const reportedVisibleOverlayKeys = /* @__PURE__ */ new Set();
         for (const script of scripts) {
           const localTimelineCompId = readRegisteredTimelineCompositionId(script.content);
           const gsapWindows = await cachedExtractGsapWindows(script.content);
@@ -26335,6 +26466,45 @@ ${right.raw}`)
               });
             }
           }
+          for (const tag of tags) {
+            const selectors = tagSimpleSelectors(tag);
+            if (selectors.length === 0) continue;
+            const overlayKey = readAttr(tag.raw, "id") || String(tag.index);
+            if (reportedVisibleOverlayKeys.has(overlayKey)) continue;
+            const authoredStyle = combinedTagStyle(tag, styleRules);
+            if (!authoredStyle || !styleLooksFullFrameOverlay(authoredStyle)) continue;
+            if (styleHasHiddenInitialState(authoredStyle)) continue;
+            const visibilityWindows = gsapWindows.filter((win) => {
+              const tokens = targetedSelectorTokens(win.targetSelector);
+              if (!selectors.some((selector2) => tokens.has(selector2))) return false;
+              return win.properties.some(
+                (prop2) => ["opacity", "autoAlpha", "visibility", "display"].includes(prop2)
+              );
+            }).sort((a, b2) => a.position - b2.position);
+            const startsHiddenAtZero = visibilityWindows.some(
+              (win) => win.position <= SCENE_BOUNDARY_EPSILON_SECONDS && isHiddenGsapState(win.propertyValues)
+            );
+            if (startsHiddenAtZero) continue;
+            const firstVisible = visibilityWindows.find((win) => makesOverlayVisible(win));
+            if (!firstVisible) continue;
+            const selector = selectors.find(
+              (candidate) => targetedSelectorTokens(firstVisible.targetSelector).has(candidate)
+            ) || selectors[0] || tag.name;
+            const laterHidden = visibilityWindows.some(
+              (win) => win.position >= firstVisible.position && isHiddenGsapState(win.propertyValues)
+            );
+            if (firstVisible.method !== "from" && !laterHidden) continue;
+            reportedVisibleOverlayKeys.add(overlayKey);
+            findings.push({
+              code: "gsap_fullscreen_overlay_starts_visible",
+              severity: "error",
+              message: `Full-frame overlay "${selector}" starts visible before its first GSAP opacity tween at ${firstVisible.position.toFixed(2)}s. It will cover earlier render frames, often as a blank/white video.`,
+              selector,
+              elementId: readAttr(tag.raw, "id") || void 0,
+              fixHint: `Add \`opacity: 0\` to "${selector}" in CSS/inline styles, or add \`tl.set("${selector}", { opacity: 0 }, 0)\` before the reveal tween.`,
+              snippet: truncateSnippet(firstVisible.raw)
+            });
+          }
           for (const win of gsapWindows) {
             const sel = win.targetSelector;
             const clipInfo = clipIds.get(sel) || clipClasses.get(sel);
@@ -26413,22 +26583,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 +27103,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 +27584,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 +33415,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 +33433,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 +33463,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 }
@@ -34491,7 +34730,11 @@ function getCapturePerfSummary(session) {
     staticDedupSkipReason: session.staticDedupSkipReason
   };
 }
-var BROWSER_CONSOLE_BUFFER_SIZE, CAPTURE_SESSION_CLOSE_TIMEOUT_MS, LOCKED_WARMUP_TICKS, realSleep, HF_READY_DIAGNOSTIC_EXPR;
+function isTransientBrowserError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return TRANSIENT_BROWSER_ERROR_PATTERNS.some((pattern) => pattern.test(message));
+}
+var BROWSER_CONSOLE_BUFFER_SIZE, CAPTURE_SESSION_CLOSE_TIMEOUT_MS, LOCKED_WARMUP_TICKS, realSleep, HF_READY_DIAGNOSTIC_EXPR, TRANSIENT_BROWSER_ERROR_PATTERNS;
 var init_frameCapture = __esm({
   "../engine/src/services/frameCapture.ts"() {
     "use strict";
@@ -34522,6 +34765,17 @@ var init_frameCapture = __esm({
     declaredDuration: declaredDuration,
   };
 })()`;
+    TRANSIENT_BROWSER_ERROR_PATTERNS = [
+      /Navigating frame was detached/i,
+      /Target closed/i,
+      /Session closed/i,
+      /browser has disconnected/i,
+      /Page crashed/i,
+      /Execution context was destroyed/i,
+      /Cannot find context with specified id/i,
+      /Failed to launch the browser process/i,
+      /ECONNREFUSED/i
+    ];
   }
 });
 
@@ -37049,21 +37303,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 +37328,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 +37349,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;
@@ -41789,6 +42034,7 @@ __export(src_exports2, {
   isHdrColorSpace: () => isHdrColorSpace,
   isHttpUrl: () => isHttpUrl,
   isLowMemorySystem: () => isLowMemorySystem,
+  isTransientBrowserError: () => isTransientBrowserError,
   isVideoFrameFormat: () => isVideoFrameFormat,
   killTrackedProcesses: () => killTrackedProcesses,
   launchHdrBrowser: () => launchHdrBrowser,
@@ -45203,6 +45449,7 @@ __export(manager_exports, {
   ensureModel: () => ensureModel,
   ensureWhisper: () => ensureWhisper,
   findWhisper: () => findWhisper,
+  getInstallInstructions: () => getInstallInstructions,
   hasFFmpeg: () => hasFFmpeg,
   isWhisperUnavailable: () => isWhisperUnavailable
 });
@@ -45309,6 +45556,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 +46163,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 +46176,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 +46200,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 +46232,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 +46429,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 +93995,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 +95548,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) {
@@ -96258,33 +96537,71 @@ async function runProbeStage(input2) {
       quality: needsAlpha ? void 0 : 80,
       deviceScaleFactor
     };
-    log2.info("Browser launched, creating capture session...");
-    probeSession = await createCaptureSession(
-      fileServer.url,
-      join44(workDir, "probe"),
-      captureOpts,
-      null,
-      probeCfg
-    );
-    log2.info("Waiting for composition to initialize...");
-    const initStart = Date.now();
-    const heartbeat = setInterval(() => {
-      const elapsed = ((Date.now() - initStart) / 1e3).toFixed(1);
-      log2.info(`Still waiting for browser initialization... (${elapsed}s elapsed)`);
-    }, 3e4);
-    try {
-      await initializeSession(probeSession);
-    } finally {
-      clearInterval(heartbeat);
+    const PROBE_MAX_ATTEMPTS = 2;
+    for (let attempt = 1; attempt <= PROBE_MAX_ATTEMPTS; attempt++) {
+      const attemptStart = Date.now();
+      try {
+        log2.info("Creating capture session...", { attempt, maxAttempts: PROBE_MAX_ATTEMPTS });
+        probeSession = await createCaptureSession(
+          fileServer.url,
+          join44(workDir, "probe"),
+          captureOpts,
+          null,
+          probeCfg
+        );
+        log2.info("Waiting for composition to initialize...", { attempt });
+        const heartbeat = setInterval(() => {
+          const elapsed = ((Date.now() - attemptStart) / 1e3).toFixed(1);
+          log2.info(`Still waiting for browser initialization... (${elapsed}s elapsed)`);
+        }, 3e4);
+        try {
+          await initializeSession(probeSession);
+        } finally {
+          clearInterval(heartbeat);
+        }
+      } catch (err) {
+        const isTransient = isTransientBrowserError(err);
+        const errMsg = err instanceof Error ? err.message : String(err);
+        log2.warn("Browser probe attempt failed", {
+          attempt,
+          maxAttempts: PROBE_MAX_ATTEMPTS,
+          isTransient,
+          error: errMsg,
+          elapsedMs: Date.now() - attemptStart
+        });
+        if (probeSession) {
+          try {
+            await closeCaptureSession(probeSession);
+          } catch (closeErr) {
+            log2.warn("Failed to close crashed probe session", {
+              error: closeErr instanceof Error ? closeErr.message : String(closeErr)
+            });
+          }
+          probeSession = null;
+        }
+        if (isTransient && attempt < PROBE_MAX_ATTEMPTS) {
+          log2.info("Retrying with a fresh browser session...", {
+            attempt: attempt + 1,
+            maxAttempts: PROBE_MAX_ATTEMPTS
+          });
+          assertNotAborted();
+          continue;
+        }
+        throw err;
+      }
+      log2.info("Composition ready", {
+        attempt,
+        initMs: Date.now() - attemptStart
+      });
+      break;
     }
-    log2.info("Composition ready", {
-      initMs: Date.now() - initStart
-    });
     assertNotAborted();
-    lastBrowserConsole = probeSession.browserConsoleBuffer;
+    const session = probeSession;
+    probeSession = session;
+    lastBrowserConsole = session.browserConsoleBuffer;
     if (composition.duration <= 0) {
       log2.info("Discovering composition duration...");
-      const discoveredDuration = await getCompositionDuration(probeSession);
+      const discoveredDuration = await getCompositionDuration(session);
       assertNotAborted();
       log2.info("Probed composition duration from browser", {
         discoveredDuration,
@@ -96298,7 +96615,7 @@ async function runProbeStage(input2) {
     }
     if (compiled.unresolvedCompositions.length > 0) {
       const resolutions = await resolveCompositionDurations(
-        probeSession.page,
+        session.page,
         compiled.unresolvedCompositions
       );
       assertNotAborted();
@@ -96317,7 +96634,7 @@ async function runProbeStage(input2) {
       }
     }
     log2.info("Discovering media assets from browser DOM...");
-    const browserMedia = await discoverMediaFromBrowser(probeSession.page);
+    const browserMedia = await discoverMediaFromBrowser(session.page);
     assertNotAborted();
     if (browserMedia.length > 0) {
       const existingVideoIds = new Set(composition.videos.map((v2) => v2.id));
@@ -96408,7 +96725,7 @@ async function runProbeStage(input2) {
         audioCount: composition.audios.length
       });
       const automation = await discoverAudioVolumeAutomationFromTimeline(
-        probeSession.page,
+        session.page,
         composition.audios.map((audio) => audio.id),
         composition.duration,
         fpsToNumber(job.config.fps)
@@ -96431,7 +96748,7 @@ async function runProbeStage(input2) {
         videoCount: composition.videos.length
       });
       const visibilityWindows = await discoverVideoVisibilityFromTimeline(
-        probeSession.page,
+        session.page,
         composition.duration
       );
       assertNotAborted();
@@ -99550,6 +99867,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 +99897,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 +100114,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 +100248,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 +102359,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 +104851,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 +105053,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 +106984,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 +107005,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 +107753,7 @@ async function renderDocker(projectDir, outputPath, options) {
       entryFile: options.entryFile,
       outputResolution: options.outputResolution,
       pageSideCompositing: options.pageSideCompositing,
+      debug: options.debug,
       pageNavigationTimeoutMs: options.pageNavigationTimeoutMs
     }
   });
@@ -107480,7 +107821,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 +107844,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 +108224,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 +108456,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 +108628,7 @@ var init_render2 = __esm({
             pageNavigationTimeoutMs,
             protocolTimeout,
             playerReadyTimeout,
+            debug,
             exitAfterComplete: false,
             throwOnError: true,
             skipFeedback: true
@@ -108323,6 +108672,7 @@ var init_render2 = __esm({
             videoBitrate,
             videoFrameFormat,
             quiet,
+            debug,
             variables,
             entryFile,
             outputResolution,
@@ -108348,6 +108698,7 @@ var init_render2 = __esm({
             videoFrameFormat,
             quiet,
             browserPath,
+            debug,
             variables,
             entryFile,
             outputResolution,
@@ -112167,6 +112518,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 +112584,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 +112905,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 +163277,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 +163308,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 +163319,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) => {