hyperframes 0.8.150 → 0.8.152

package/dist/{render-SDHFXL3Y.js → render-5EREH6YD.js}

@@ -6,15 +6,19 @@ var __filename = __hf_fileURLToPath(import.meta.url);
 var __dirname = __hf_dirname(__filename);
 import {
   maybePromptRenderFeedback
-} from "./chunk-UJB7356Y.js";
+} from "./chunk-3LO7BBJX.js";
+import {
+  captureArtifactRevision
+} from "./chunk-KCFF4ENE.js";
+import "./chunk-7TASSBN2.js";
 import {
   reportVariableIssues,
   resolveVariablesArg,
   validateVariablesAgainstProject
-} from "./chunk-UQYQ7TBA.js";
+} from "./chunk-7NPSXBIN.js";
 import {
   loadProducer
-} from "./chunk-6QB7F2II.js";
+} from "./chunk-3E4OCOC5.js";
 import {
   renderJobObservabilityTelemetryPayload
 } from "./chunk-VXVRPIJA.js";
@@ -26,11 +30,16 @@ import {
   resolveCompositionEntryArg,
   resolveDefaultFpsArg,
   windowsChromeCrashRemediation
-} from "./chunk-423DJVX2.js";
+} from "./chunk-PKO2EWO7.js";
 import "./chunk-WPNE5NEP.js";
+import {
+  recordRenderSuccess,
+  registerRenderOutput
+} from "./chunk-7FYFEXD2.js";
+import "./chunk-FFDC5OWV.js";
 import {
   resolveProject
-} from "./chunk-NFQY7EIC.js";
+} from "./chunk-IBYC3VUA.js";
 import {
   formatLintStartupMessage
 } from "./chunk-6CSYCFQV.js";
@@ -46,23 +55,24 @@ import {
   resolvePrintedCaptureMode
 } from "./chunk-K2FLNJVB.js";
 import "./chunk-DCAI5DBR.js";
+import "./chunk-DQBY7FRR.js";
 import {
   runEnvironmentChecks
-} from "./chunk-M5B42RL5.js";
+} from "./chunk-WUUOFMHU.js";
 import "./chunk-442JNXRM.js";
 import {
   loadProjectConfig,
   readProjectConfigWithStatus,
   seedProjectAuthoringSkill
-} from "./chunk-XQMEGSHG.js";
+} from "./chunk-D6RJXQLD.js";
 import "./chunk-XT7X6QCP.js";
 import "./chunk-4YYJOFKS.js";
 import {
   normalizeSkillSlug
 } from "./chunk-HVW7ABXD.js";
-import "./chunk-BLRJKBKP.js";
-import "./chunk-M6UDJ2E7.js";
-import "./chunk-OQ7XMM3S.js";
+import "./chunk-QESSGUKX.js";
+import "./chunk-6Z4YJ5Q3.js";
+import "./chunk-3HPJM5IQ.js";
 import "./chunk-AWDFDFI3.js";
 import "./chunk-P6LJ4Y32.js";
 import "./chunk-GMECXFAN.js";
@@ -71,8 +81,8 @@ import {
   trackRenderError,
   trackRenderObservation,
   trackRenderPreflightRejected
-} from "./chunk-3UAIVF4L.js";
-import "./chunk-6KWA3XPS.js";
+} from "./chunk-H2SGM2V2.js";
+import "./chunk-KZ3L3W4Q.js";
 import "./chunk-VWG7OQKU.js";
 import {
   bytesToMb
@@ -95,10 +105,11 @@ import {
 import {
   c
 } from "./chunk-ZTZA4UWZ.js";
+import "./chunk-EOOEC32M.js";
 import {
   hasDefinitiveEntryMismatch
 } from "./chunk-Q5X2B5WT.js";
-import "./chunk-7IEGPJ4P.js";
+import "./chunk-LBT4AMSF.js";
 import "./chunk-K4WIOZFP.js";
 import {
   readConfigFresh,
@@ -112,11 +123,11 @@ import {
 } from "./chunk-ISN5GRYI.js";
 import {
   VERSION
-} from "./chunk-I6DATIHC.js";
+} from "./chunk-IZIRIDJH.js";
 import "./chunk-EOVYQ3IG.js";
 import {
   createRenderCancellationScope
-} from "./chunk-4WFNTWKZ.js";
+} from "./chunk-FNN5QINS.js";
 import {
   H264EncoderUnavailableError,
   chromeLaunchRemediation,
@@ -124,15 +135,15 @@ import {
   findFFmpeg,
   findFFprobe,
   getFFmpegInstallHint
-} from "./chunk-DUUFDLC4.js";
+} from "./chunk-4MLYMDQ4.js";
 import "./chunk-AMKC3AXA.js";
 import {
   EXTRACT_CACHE_DIR_DISABLED_ALIASES,
   MAX_VP9_CPU_USED,
   MIN_VP9_CPU_USED,
   isVideoFrameFormat
-} from "./chunk-5NAYNDBT.js";
-import "./chunk-WLIUULZQ.js";
+} from "./chunk-EXH6L2XZ.js";
+import "./chunk-RN5I2DP5.js";
 import "./chunk-NE55C6S5.js";
 import "./chunk-JYVGYKXG.js";
 import {
@@ -140,8 +151,8 @@ import {
   fpsToFfmpegArg,
   fpsToNumber,
   parseFps
-} from "./chunk-PCWOSS7G.js";
-import "./chunk-CEND6BLF.js";
+} from "./chunk-5ERVRJMV.js";
+import "./chunk-S3RCK56N.js";
 import "./chunk-VC76R6W2.js";
 import "./chunk-UJKQWGFF.js";
 import {
@@ -149,7 +160,7 @@ import {
   isAspectAgnosticResolutionAlias,
   normalizeResolutionFlag,
   suggestMatchingPreset
-} from "./chunk-LFNQDTSH.js";
+} from "./chunk-VYKPBRCB.js";
 import "./chunk-OFQWTKPW.js";
 import "./chunk-DPVXBVLL.js";
 import "./chunk-T76PLPD6.js";
@@ -157,24 +168,24 @@ import "./chunk-FXMKHHPO.js";
 import "./chunk-RQVDTPGD.js";
 import {
   killOrphanedProcessesForRender
-} from "./chunk-B3XLIBFL.js";
+} from "./chunk-YIJMVFEJ.js";
 import {
   runRenderSetupWorker
-} from "./chunk-XPQSL5VS.js";
+} from "./chunk-54DMWFQZ.js";
 import "./chunk-TWWSYAKJ.js";
 import {
   lintProject,
   shouldBlockRender
-} from "./chunk-JDB65PPT.js";
+} from "./chunk-YOEGUBBY.js";
 import {
   collectSubCompositionSrcs
 } from "./chunk-IWFLMU2N.js";
-import "./chunk-APDLWWFG.js";
+import "./chunk-3VGU2SH7.js";
 import "./chunk-VAS6HQX3.js";
 import "./chunk-3RM2ETQT.js";
 import "./chunk-BSQ7XANM.js";
 import "./chunk-SDYDNHEE.js";
-import "./chunk-2PSPARWP.js";
+import "./chunk-TYXH3EKP.js";
 import "./chunk-IXLUTE6N.js";
 import {
   normalizeErrorMessage
@@ -672,7 +683,7 @@ async function executeRenderPlan(plan, dependencies, cancellation) {
   let batchModule;
   let preparedBatch;
   if (plan.batchPath) {
-    batchModule = await import("./batchRender-ZBKAYLWU.js");
+    batchModule = await import("./batchRender-7PLJISCN.js");
     try {
       preparedBatch = batchModule.prepareBatchRender({
         batchPath: plan.batchPath,
@@ -761,7 +772,7 @@ function assertRenderActive(cancellation) {
   cancellation?.signal.throwIfAborted();
 }
 async function ensureRenderBrowser(plan, signal) {
-  const { ensureBrowser } = await import("./manager-GWU5J6RJ.js");
+  const { ensureBrowser } = await import("./manager-ZLJD3EAY.js");
   let browserSpinner;
   try {
     if (plan.effectiveQuiet) {
@@ -1147,6 +1158,34 @@ var DockerRenderExitError = class extends Error {
   }
 };
 
+// src/utils/dockerBuildFailure.ts
+var DOCKER_BUILD_TIMEOUT_MINUTES = 10;
+function isSpawnTimeout(error) {
+  return error instanceof Error && "code" in error && error.code === "ETIMEDOUT";
+}
+function describeDockerBuildFailure(error) {
+  if (error instanceof Error && isSpawnTimeout(error.cause)) {
+    return {
+      title: "Docker image build timed out",
+      message: `Building the render image took longer than ${DOCKER_BUILD_TIMEOUT_MINUTES} minutes, so it was stopped.`,
+      hint: "Run the same command again. Docker keeps the layers it already built, so the build picks up where it stopped."
+    };
+  }
+  const message = normalizeErrorMessage(error);
+  if (/connect|not found|ENOENT/i.test(message)) {
+    return {
+      title: "Docker not available",
+      message,
+      hint: "Install Docker: https://docs.docker.com/get-docker/"
+    };
+  }
+  return {
+    title: "Docker image build failed",
+    message,
+    hint: "Check Docker is running: docker info"
+  };
+}
+
 // src/browser/macosOldChromeCrash.ts
 var DYLD_SYMBOL_NOT_FOUND = /Symbol not found:/i;
 var MACOS_13_ONLY_SYMBOL = /_kVTCompressionPropertyKey_ReferenceBufferCount/;
@@ -1543,11 +1582,11 @@ function ensureDockerImage(version, platform, quiet) {
         tag,
         tmpDir
       ],
-      { stdio: quiet ? "pipe" : "inherit", timeout: 6e5 }
+      { stdio: quiet ? "pipe" : "inherit", timeout: DOCKER_BUILD_TIMEOUT_MINUTES * 6e4 }
     );
   } catch (error) {
     const message = normalizeErrorMessage(error);
-    throw new Error(`Failed to build Docker image: ${message}`);
+    throw new Error(`Failed to build Docker image: ${message}`, { cause: error });
   } finally {
     rmSync(tmpDir, { recursive: true, force: true });
   }
@@ -1573,7 +1612,14 @@ function resolveDockerHostPlatform(options) {
   }
   return platform;
 }
+async function registerRenderOutputOrWarn(projectDir, outputPath) {
+  await registerRenderOutput(projectDir, outputPath).catch(
+    (error) => console.warn(`Render output was not registered: ${normalizeErrorMessage(error)}`)
+  );
+}
 async function renderDocker(projectDir, outputPath, options) {
+  await registerRenderOutputOrWarn(projectDir, outputPath);
+  const capture = await captureArtifactRevision(projectDir).catch(() => void 0);
   const startTime = Date.now();
   const dockerVersion = isDevMode() ? "latest" : VERSION;
   if (!options.quiet && isDevMode()) {
@@ -1584,13 +1630,8 @@ async function renderDocker(projectDir, outputPath, options) {
   try {
     imageTag = ensureDockerImage(dockerVersion, platform, options.quiet);
   } catch (error) {
-    const message = normalizeErrorMessage(error);
-    const isDockerMissing = /connect|not found|ENOENT/i.test(message);
-    errorBox(
-      isDockerMissing ? "Docker not available" : "Docker image build failed",
-      message,
-      isDockerMissing ? "Install Docker: https://docs.docker.com/get-docker/" : "Check Docker is running: docker info"
-    );
+    const failure = describeDockerBuildFailure(error);
+    errorBox(failure.title, failure.message, failure.hint);
     failCommand();
   }
   const outputDir = dirname2(outputPath);
@@ -1654,6 +1695,11 @@ async function renderDocker(projectDir, outputPath, options) {
   }
   const elapsed = Date.now() - startTime;
   markRenderSucceeded();
+  await runPostRenderStepAsync(
+    "recordRenderSuccess",
+    () => recordRenderSuccess(projectDir, outputPath, "completed", capture).then(() => {
+    })
+  );
   runPostRenderStep(
     "trackRenderComplete",
     () => trackRenderComplete({
@@ -1700,6 +1746,8 @@ async function renderLocal(projectDir, outputPath, options, commandCancellation)
   }
 }
 async function executeLocalRender(projectDir, outputPath, options, cancellation) {
+  await registerRenderOutputOrWarn(projectDir, outputPath);
+  const capture = await captureArtifactRevision(projectDir).catch(() => void 0);
   cancellation.checkAncestors();
   cancellation.signal.throwIfAborted();
   let recoveredOrphanTrees = 0;
@@ -1870,6 +1918,16 @@ async function executeLocalRender(projectDir, outputPath, options, cancellation)
     );
   }
   markRenderSucceeded();
+  await runPostRenderStepAsync(
+    "recordRenderSuccess",
+    () => recordRenderSuccess(
+      projectDir,
+      outputPath,
+      job.outcome === "completed_with_warnings" ? "completed_with_warnings" : "completed",
+      capture
+    ).then(() => {
+    })
+  );
   maybeConsumeDeParallelRouterTrial(deParallelRouterActive, job, options.quiet);
   const elapsed = Date.now() - startTime;
   if (job.outcome === "completed_with_warnings") {

package/dist/{render-HS3YOLSD.js → render-6GH5FSXU.js}

@@ -15,7 +15,7 @@ import {
   reportVariableIssues,
   resolveVariablesArg,
   validateVariablesAgainstProject
-} from "./chunk-UQYQ7TBA.js";
+} from "./chunk-7NPSXBIN.js";
 import "./chunk-FH7WODJH.js";
 import "./chunk-K2FLNJVB.js";
 import "./chunk-442JNXRM.js";
@@ -25,11 +25,11 @@ import {
 import {
   c
 } from "./chunk-ZTZA4UWZ.js";
-import "./chunk-PCWOSS7G.js";
-import "./chunk-CEND6BLF.js";
+import "./chunk-5ERVRJMV.js";
+import "./chunk-S3RCK56N.js";
 import "./chunk-VC76R6W2.js";
 import "./chunk-UJKQWGFF.js";
-import "./chunk-LFNQDTSH.js";
+import "./chunk-VYKPBRCB.js";
 import "./chunk-OFQWTKPW.js";
 import "./chunk-DPVXBVLL.js";
 import "./chunk-T76PLPD6.js";
@@ -38,7 +38,7 @@ import "./chunk-RQVDTPGD.js";
 import "./chunk-3RM2ETQT.js";
 import "./chunk-BSQ7XANM.js";
 import "./chunk-SDYDNHEE.js";
-import "./chunk-2PSPARWP.js";
+import "./chunk-TYXH3EKP.js";
 import "./chunk-IXLUTE6N.js";
 import "./chunk-M2WBOQ2Q.js";
 

package/dist/{render-batch-J64AJHQY.js → render-batch-UMBUQWWS.js}

@@ -14,7 +14,7 @@ import {
   loadProjectVariableSchema,
   reportVariableIssues,
   validateVariablesAgainstSchema
-} from "./chunk-UQYQ7TBA.js";
+} from "./chunk-7NPSXBIN.js";
 import "./chunk-FH7WODJH.js";
 import {
   errorBox
@@ -27,11 +27,11 @@ import {
 import {
   c
 } from "./chunk-ZTZA4UWZ.js";
-import "./chunk-PCWOSS7G.js";
-import "./chunk-CEND6BLF.js";
+import "./chunk-5ERVRJMV.js";
+import "./chunk-S3RCK56N.js";
 import "./chunk-VC76R6W2.js";
 import "./chunk-UJKQWGFF.js";
-import "./chunk-LFNQDTSH.js";
+import "./chunk-VYKPBRCB.js";
 import "./chunk-OFQWTKPW.js";
 import "./chunk-DPVXBVLL.js";
 import "./chunk-T76PLPD6.js";
@@ -40,7 +40,7 @@ import "./chunk-RQVDTPGD.js";
 import "./chunk-3RM2ETQT.js";
 import "./chunk-BSQ7XANM.js";
 import "./chunk-SDYDNHEE.js";
-import "./chunk-2PSPARWP.js";
+import "./chunk-TYXH3EKP.js";
 import "./chunk-IXLUTE6N.js";
 import {
   normalizeErrorMessage

package/dist/renderSetupWorker.js

@@ -8,26 +8,26 @@ import "./chunk-Q5X2B5WT.js";
 import {
   ensureBrowser,
   releaseOwnedBrowserInstallLock
-} from "./chunk-7IEGPJ4P.js";
+} from "./chunk-LBT4AMSF.js";
 import {
   killOrphanedProcesses
-} from "./chunk-B3XLIBFL.js";
+} from "./chunk-YIJMVFEJ.js";
 import {
   installRenderSetupSignalHandlers,
   renderSetupErrorLine,
   renderSetupResultLine
-} from "./chunk-XPQSL5VS.js";
+} from "./chunk-54DMWFQZ.js";
 import "./chunk-TWWSYAKJ.js";
 import {
   lintProject
-} from "./chunk-JDB65PPT.js";
+} from "./chunk-YOEGUBBY.js";
 import "./chunk-IWFLMU2N.js";
-import "./chunk-APDLWWFG.js";
+import "./chunk-3VGU2SH7.js";
 import "./chunk-VAS6HQX3.js";
 import "./chunk-3RM2ETQT.js";
 import "./chunk-BSQ7XANM.js";
 import "./chunk-SDYDNHEE.js";
-import "./chunk-2PSPARWP.js";
+import "./chunk-TYXH3EKP.js";
 import "./chunk-IXLUTE6N.js";
 import "./chunk-KNU5COPB.js";
 import "./chunk-KGPLIH7B.js";

package/dist/{resolver-IHNWMDJA.js → resolver-KO6WWO5P.js}

@@ -11,16 +11,16 @@ import {
   resolveItemWithDependencies,
   resolveItemsByTag,
   unreachableRegistryMessage
-} from "./chunk-BLRJKBKP.js";
-import "./chunk-OQ7XMM3S.js";
+} from "./chunk-QESSGUKX.js";
+import "./chunk-3HPJM5IQ.js";
 import "./chunk-AWDFDFI3.js";
 import "./chunk-P6LJ4Y32.js";
 import "./chunk-GMECXFAN.js";
-import "./chunk-PCWOSS7G.js";
-import "./chunk-CEND6BLF.js";
+import "./chunk-5ERVRJMV.js";
+import "./chunk-S3RCK56N.js";
 import "./chunk-VC76R6W2.js";
 import "./chunk-UJKQWGFF.js";
-import "./chunk-LFNQDTSH.js";
+import "./chunk-VYKPBRCB.js";
 import "./chunk-OFQWTKPW.js";
 import "./chunk-DPVXBVLL.js";
 import "./chunk-T76PLPD6.js";
@@ -29,7 +29,7 @@ import "./chunk-RQVDTPGD.js";
 import "./chunk-3RM2ETQT.js";
 import "./chunk-BSQ7XANM.js";
 import "./chunk-SDYDNHEE.js";
-import "./chunk-2PSPARWP.js";
+import "./chunk-TYXH3EKP.js";
 import "./chunk-IXLUTE6N.js";
 import "./chunk-M2WBOQ2Q.js";
 export {

package/dist/{sherpa-FXBBYMDR.js → sherpa-DADGYWNR.js}

@@ -16,42 +16,42 @@ import {
   sherpaRuntimeLoadError,
   sherpaUnsupportedReason,
   transcribeWithSherpa
-} from "./chunk-6SFPQ2RZ.js";
+} from "./chunk-E6EYZ33P.js";
 import "./chunk-BXCMXMJQ.js";
 import "./chunk-3DKN5WKL.js";
 import "./chunk-EOVYQ3IG.js";
-import "./chunk-XANZ4R4P.js";
-import "./chunk-4WFNTWKZ.js";
+import "./chunk-QECEOV6W.js";
+import "./chunk-FNN5QINS.js";
 import "./chunk-6BEFEWFB.js";
-import "./chunk-CZQLCBWY.js";
+import "./chunk-YG2Y55KF.js";
 import "./chunk-PO2SDVQA.js";
-import "./chunk-DUUFDLC4.js";
+import "./chunk-4MLYMDQ4.js";
 import "./chunk-AMKC3AXA.js";
-import "./chunk-5NAYNDBT.js";
-import "./chunk-WLIUULZQ.js";
+import "./chunk-EXH6L2XZ.js";
+import "./chunk-RN5I2DP5.js";
 import "./chunk-NE55C6S5.js";
 import "./chunk-JYVGYKXG.js";
-import "./chunk-PCWOSS7G.js";
-import "./chunk-CEND6BLF.js";
+import "./chunk-5ERVRJMV.js";
+import "./chunk-S3RCK56N.js";
 import "./chunk-VC76R6W2.js";
 import "./chunk-UJKQWGFF.js";
-import "./chunk-LFNQDTSH.js";
+import "./chunk-VYKPBRCB.js";
 import "./chunk-OFQWTKPW.js";
 import "./chunk-DPVXBVLL.js";
 import "./chunk-T76PLPD6.js";
 import "./chunk-FXMKHHPO.js";
 import "./chunk-RQVDTPGD.js";
-import "./chunk-B3XLIBFL.js";
-import "./chunk-XPQSL5VS.js";
+import "./chunk-YIJMVFEJ.js";
+import "./chunk-54DMWFQZ.js";
 import "./chunk-TWWSYAKJ.js";
-import "./chunk-JDB65PPT.js";
+import "./chunk-YOEGUBBY.js";
 import "./chunk-IWFLMU2N.js";
-import "./chunk-APDLWWFG.js";
+import "./chunk-3VGU2SH7.js";
 import "./chunk-VAS6HQX3.js";
 import "./chunk-3RM2ETQT.js";
 import "./chunk-BSQ7XANM.js";
 import "./chunk-SDYDNHEE.js";
-import "./chunk-2PSPARWP.js";
+import "./chunk-TYXH3EKP.js";
 import "./chunk-IXLUTE6N.js";
 import "./chunk-KNU5COPB.js";
 import "./chunk-JZIEZCQM.js";

package/dist/skills/hyperframes/references/frame-worker-core.md

@@ -7,8 +7,9 @@ You build the frame composition file(s) assigned in your dispatch and nothing el
 **INPUT** — your dispatch provides this role, your frame packet(s), and:
 
 - `PROJECT_DIR` — the project root; all paths are relative to it.
-- `frame_id` — e.g. `03-feature`. Use it **verbatim** as the composition id, the `window.__timelines` key, and the file name (`compositions/frames/03-feature.html`) — that path **is** the frame's `src` in `STORYBOARD.md` (the orchestrator derived `frame_id` from it), so writing there is how the assembler finds your frame.
+- `frame_id` — e.g. `03-feature`. Use it **verbatim** as the composition id, the `window.__timelines` key, and the file name. Write to the exact `src` in your packet's storyboard block (e.g. `compositions/frames/<frame_id>.html` or `compositions/<frame_id>.html`); the orchestrator derived `frame_id` from that path, and the assembler reads it verbatim.
 - Your **packet** (`.hyperframes/frame-packets/<frame_id>.md`) — everything selected upstream for this frame. You never open the shared `STORYBOARD.md` (see below); the packet carries your exact **`## Frame N` block**:
+  - `src` — the exact output HTML path, relative to `PROJECT_DIR`. Preserve it; do not add or remove a `frames/` directory.
   - `scene` — a one-line contact-sheet caption. **Design intent, never visible DOM text.**
   - `voiceover` — the narration line. **Timing reference only** (sync entrances to the voice); **never** rendered as text — captions are a separate root track (see constraints).
   - `duration` — your render length in seconds. **Fixed upstream; never change it or tween to fill a different length.**
@@ -24,7 +25,7 @@ You build the frame composition file(s) assigned in your dispatch and nothing el
 
 **Retry** — if your context carries `lint` / `check` feedback from a prior pass, read it first and re-author so none of those findings recur; treat each as a hard constraint.
 
-**OUTPUT** — `compositions/frames/<frame_id>.html` for each assigned packet: exactly one bare `<template>…</template>` fragment. The first non-whitespace bytes are `<template`; the last are `</template>`. Never emit `<!doctype>`, `<html>`, `<head>`, `<body>`, or any markup outside that single template. Writing your assigned file(s) (past the self-check below) is your **terminal action** — you do not edit `STORYBOARD.md`, mint audio, assemble the index, run the CLI, or report back. The orchestrator picks up the file and marks the frame's `status`.
+**OUTPUT** — the HTML file at each assigned packet's `src`: exactly one bare `<template>…</template>` fragment. The first non-whitespace bytes are `<template`; the last are `</template>`. Never emit `<!doctype>`, `<html>`, `<head>`, `<body>`, or any markup outside that single template. The workflow delta specifies any required sidecars and the dispatch specifies which packets you own. Writing all assigned HTML files and required sidecars (past the self-check below) is your **terminal action** — you do not edit `STORYBOARD.md`, mint audio, assemble the index, run the CLI, or report back. The orchestrator picks up the file and marks the frame's `status`.
 
 ## When a confirmed sketch exists
 
@@ -56,24 +57,25 @@ Shared law for every narrative frame, each load-bearing; your workflow's delta a
 
 1. **Read** — your packet top to bottom (your frame block, the inlined blueprint, the inlined rule recipes), then `frame.md` (the look). Internalize the self-check codes below before you write — most lethal is **template transport**: every `<style>` + `<script>` (including the gsap load) must live INSIDE `<template>`, because the runtime only clones template contents and the assembled-project `lint` / `check` gate can miss an unwired blank sub-composition.
 2. **Design** — turn the time-coded shot sequence into a timeline using `frame.md`'s components and type ramp: each Scene window becomes a phase revealed on its `voiceover` cue, each named motion built from the recipe in your packet, the blueprint's signature move kept recognizable. Find a visual idea that reinforces the beat, not a literal restyle of the words.
-3. **Author** — write the full sub-composition to `compositions/frames/<frame_id>.html` (rewrite to iterate; last write wins). `<template>`-wrapped root carrying `data-composition-id="<frame_id>"` and styled via `#root` (not a class on that element — see the self-check below), exactly one `gsap.timeline({ paused: true })` registered at `window.__timelines["<frame_id>"]`, built synchronously.
+3. **Author** — write the full sub-composition to the exact `src` in your packet (rewrite to iterate; last write wins). `<template>`-wrapped root carrying `data-composition-id="<frame_id>"` and styled via `#root` (not a class on that element — see the self-check below), exactly one `gsap.timeline({ paused: true })` registered at `window.__timelines["<frame_id>"]`, built synchronously.
    Prefix authored ids and globally reusable class names with `<frame_id>-` so sibling frames assembled from parallel workers cannot collide. Contract selectors such as `#root` and `.clip` are the only exceptions.
-4. **Self-check, then finish** — re-read your file against the checklist below and fix in place; then continue to your next assigned packet, if any. You do **not** run the CLI.
+4. **Self-check, then finish** — re-read your file against the checklist below and fix in place; write any sidecar required by the workflow delta, then continue to your next assigned packet, if any. You do **not** run the CLI.
 
 ## Self-check before finishing (you do NOT run the CLI)
 
-You **can't** meaningfully run `hyperframes lint` / `check` here: they operate on the **assembled project** (the `index.html` graph / bundle), and your frame isn't wired in yet — so they report on _other_ files, not yours (a false green). The **orchestrator** runs them after assembly (the correct unit), and **re-dispatches you with the finding** if your frame fails (see **Retry** above). So get it right on write: re-read your file against this checklist before finishing — the codes in parens are `hyperframes lint`'s and what the orchestrator may cite back:
+You **can't** meaningfully run `hyperframes lint` / `check` here: they operate on the **assembled project** (the `index.html` graph / bundle), and your frame isn't wired in yet — so they report on _other_ files, not yours (a false green). The **orchestrator** runs them after assembly (the correct unit), and **re-dispatches you with the finding** if your frame fails (see **Retry** above). So get it right on write: re-read your file against this checklist before finishing — backticked diagnostic codes below are emitted by `hyperframes lint`; bold labels are manual workflow checks, not lint codes:
 
-- `missing_template_wrapper` / `missing_composition_id` — the entire file is exactly one bare `<template>…</template>` fragment (no DOCTYPE / full document); root carries `data-composition-id="<frame_id>"`.
+- **Template wrapper (manual)** — the entire file is exactly one bare `<template>…</template>` fragment (no DOCTYPE / full document).
+- `root_missing_composition_id` — root carries `data-composition-id="<frame_id>"`; check that the value matches your assigned frame id.
 - **Template transport** — every `<style>` and `<script>` block, including the GSAP load, lives inside `<template>`.
 - `subcomposition_root_styled_by_class` — **style the frame root via `#root`, never a class on the `data-composition-id` element**: at render a class on the root gets scoped to a descendant selector that can't match it, so the **whole scene renders unstyled** (Studio preview still looks right — trust this rule, not the preview). Descendants use plain selectors.
 - **Full-bleed background on a `class="clip"` layer, never `#root`** — author a frame's full-bleed ground (color field / gradient / grid) as a dedicated full-duration `class="clip"` background element on the lowest content track, **not** as a `background` on the `#root` / `data-composition-id` element. At assembly the frame root is clip-gated to its scene window, so a background painted on the root is not a dependable full-frame ground — dark content can end up over the host `body` (black) and render invisible. The video's base ground is painted separately by the assembler from `frame.md`'s `canvas` color onto the index `#root`; your full-bleed clip rides on top of it.
-- `clip_missing_data_attrs` — every `class="clip"` element has `data-start` / `data-duration` / `data-track-index`.
-- `timeline_not_paused` / `timeline_not_registered` — one paused timeline, registered at `window.__timelines["<frame_id>"]`.
+- **Clip attributes (manual)** — every `class="clip"` element has `data-start` / `data-duration` / `data-track-index`.
+- **Paused timeline + registration (manual for template frames)** — one paused timeline, registered at `window.__timelines["<frame_id>"]`. `gsap_timeline_not_registered` is a real lint code for standalone compositions, but the rule skips template/sub-compositions; it does not verify your frame registration.
 - `css_transition_used` + repeat / yoyo / non-deterministic logic — none present (the renderer seeks frame-by-frame).
 - `gsap_css_transform_conflict` — never put a CSS `transform` (e.g. `translateY(-50%)` centering) on an element you then GSAP-animate a transform prop on (`x` / `y` / `scale` / `rotation`): GSAP overwrites the whole `transform` and silently drops the CSS centering (the element jumps). Center with `margin` / `inset` (or `top`/`left` + offset), fold the offset into the tween via `xPercent` / `yPercent`, or use `fromTo` (the rule exempts it).
 - **Hero visibility** — the main subject is visible by `t <= 0.5s`; entrance tweens use `fromTo` instead of CSS-hidden starting states.
-- `exit_animation_on_non_final_scene` — no exit tween unless you are the final frame.
+- **Non-final exit (manual)** — no exit tween unless you are the final frame.
 - **No front-loading (not a slide)** — the shot's pieces reveal on their `voiceover` cues across the duration, not all fired at `t=0`; a non-still frame keeps content arriving rather than holding a full canvas from ~25%.
 - **Shot-sequence fidelity** — every Scene in the time-coded sequence is realized as a phase, the blueprint's signature move (unless `compose`) is present and recognizable, and the shot reveals to the voiceover (never front-loaded at `t=0`).
 - `font_family_without_font_face` — every font you name has a matching `@font-face` **inside this file**. **Only use fonts that ship as files** with the project: the families declared in `frame.md` (their `.woff2` live in `assets/fonts/` or `capture/assets/fonts/` — point the `@font-face` `src` at the real file you find there). **Never name a font that has no file**, including system CJK / Japanese / Devanagari families (`Hiragino Sans`, `Yu Gothic`, `Noto Sans CJK`, `Noto Sans Devanagari`, …): the render machine is a clean headless Chrome with none of them installed, so the text silently falls back to a generic font and the typography is wrong in the MP4. For non-Latin or multilingual visible text, either use a shipped font that covers the script, or romanize / transliterate it (e.g. `日本語` → `Japanese`); if neither is possible it is out of scope for this frame — do not invent a font name.

package/dist/skills/hyperframes/references/subagent-dispatch.md

@@ -10,7 +10,7 @@ The video workflows (`product-launch-video` / `faceless-explainer` / `pr-to-vide
 
 ## Concurrency cap → batching rule (cap never changes scope)
 
-A harness concurrency limit **reduces parallelism, not work**: every scene still gets built, one scene per dispatch, with the available slots chewing through the full list.
+A harness concurrency limit **reduces parallelism, not work**: every scene still gets built, with the available slots chewing through the full list. The workflow sets how many scenes each worker gets (`general-video` assigns 2–3).
 
 - When the harness queues excess children internally, submit **all N at once** and let the queue drain.
 - Harness hard-caps active children (e.g. OpenClaw `maxChildrenPerAgent`) → dispatch in **waves of the cap size**: start `cap` workers, wait for their artifacts, start the next wave, until all N scenes exist. Example: 9 scenes on a cap-3 harness = 3 waves of 3 — never drop scenes, never merge scenes into one worker to fit the cap.

package/dist/skills/hyperframes-cli/SKILL.md

@@ -79,6 +79,9 @@ Static audits cannot catch every mount failure. When the project uses sub-compos
 
 ```bash
 npx hyperframes snapshot --at <t1>,<t2>,<t3>
+# For multiple samples within one scene or interval:
+npx hyperframes snapshot --composition <data-composition-id> --frames 8
+npx hyperframes snapshot --range 3:5 --frames 8
 ```
 
 Treat tiny unstyled content, canvas-sized icons, missing hero elements, or timeline-registration timeouts as render-blocking mount defects. See `hyperframes-core/references/sub-compositions.md` for the corresponding fixes.

package/dist/skills/hyperframes-cli/references/lint-validate-inspect.md

@@ -104,9 +104,13 @@ Drop a `*.motion.json` sidecar next to the composition (matching the html basena
 npx hyperframes snapshot                       # 5 key frames as PNG
 npx hyperframes snapshot ./my-project          # specific project
 npx hyperframes snapshot --frames 10           # evenly-spaced N frames
+npx hyperframes snapshot --range 3:5 --frames 8 # 8 frames within root-timeline seconds 3–5
+npx hyperframes snapshot --composition intro --frames 8 # 8 frames within this data-composition-id
 ```
 
-Captures still PNGs from the composition for visual diffing, thumbnails, or attaching to a PR. Faster than rendering a video when you only need a few hero frames. Output lands in the project's snapshots directory. Not deprecated: it remains the standalone capture utility, while `check --snapshots` covers the gate's needs (overview frames annotated with labeled finding boxes, plus `finding-NN-<code>.png` crops for every error finding with a bbox).
+Still PNGs. Each run writes `.hyperframes/artifacts/snapshots/<id>/` unless `--output` is set. `snapshot` is the standalone capture; `check --snapshots` is the gate.
+
+One of `--at`, `--range START:END` (seconds), or `--composition <data-composition-id>` (not a CSS selector). `--frames` defaults to 5. Range and composition sample just before the end and add no extra end frame; `--at` adds one unless `--no-end`.
 
 ### Zooming into a reported finding