@hypit/hypit 0.2.6 → 0.2.7

package/packages/provider-hyperframes-local/README.md

@@ -1,12 +1,22 @@
 # @hypit/provider-hyperframes-local
 
-Trusted local Provider for the `@hypit/render-hyperframes#render-visual` capability. It stages the
+Trusted local Provider for `@hypit/render-hyperframes@1#render-visual` and `#render-frames`. It stages the
 Resource dependencies declared by a `HyperframesDocument`, renders a silent MP4 with the
 HyperFrames engine, probes the bytes, and returns a verified `RenderedVisual`. Before capturing a typed
 Surface it decodes the exact bytes and checks declared dimensions, still/frame timing, SDR/sRGB and
 opaque/straight-alpha facts. These checks validate the typed rendering input; they do not create
 content identity or hidden output metadata.
 
+`render-frames` uses the same staging, source-frame mapping, readiness and opaque PNG capture as
+video export, returning the PNGs before encoding. It accepts a compiled document or a materialized
+HTML project. For selected frames it merges only their required source-frame windows; continuous
+windows decode sequentially. A complete batch shares one staged project and browser lifetime.
+The existing browser selection, explicit preparation, worker settings and cancellation apply.
+`maxRenderedBytes` bounds the total returned PNG bytes, or the encoded MP4 for a video request.
+`render-frames` has its own capability binding; it does not inherit a `render-visual` binding.
+For immediate CLI invocation, the host calls the handler directly: Build admission reservations do
+not coordinate separate CLI processes. Worker limits still bound browsers inside each invocation.
+
 Normalized transparent videos displayed by Media or project components use the ordinary video path.
 The engine decodes them to PNG frames with alpha, then Chrome blends them with lower layers and
 the authored Canvas background. Final frames use fast PNG encoding after Chrome has composited
@@ -73,8 +83,7 @@ an opaque session and chooses PNG separately at capture. It does not patch engin
 The Runtime Adapter declares one managed browser program. Prepare it explicitly:
 
 ```sh
-hypit programs up --runtime ./hypit.runtime.json --endpoint hyperframes.local
-hypit doctor --runtime ./hypit.runtime.json
+hypit programs prepare --runtime ./hypit.runtime.json --endpoint hyperframes.local
 ```
 
 Use the instance name from the Profile. `runtime up` also prepares it and starts the Runtime Worker.
@@ -110,17 +119,20 @@ receipt is stored. To install into an empty location, explicitly choose `browser
 
 `config.chromePath` selects a user-managed Chrome/Chromium executable. It cannot be combined with
 `browserVersion` or `browserDownloadBaseUrl`; invalid combinations fail instead of assigning precedence. Relative paths resolve
-from the Runtime Profile root. This mode never downloads or repairs a browser. Its version remains
+from the Runtime data root, as does `browserCacheDirectory`. The Profile's `dataRoot` itself resolves
+relative to the Profile file. This mode never downloads or repairs a browser. Its version remains
 under the user's control, including system-browser auto-updates. `HYPERFRAMES_BROWSER_PATH` and
 `PRODUCER_HEADLESS_SHELL_PATH` do not select browsers in this Provider; configure `chromePath`.
 On platforms without a supported managed download, explicitly select an installed browser.
 
 `doctor` displays the selected path and its source, and only inspects it. Build preflight, rendering
-and previews never install a browser. `programs up` / `runtime up` display the selected managed
+and previews never install a browser. `programs prepare`, `programs up` and `runtime up` display the selected managed
 version, installation location and download URL before running preparation. The probe runs `--version` and checks
 FFmpeg/FFprobe; it does not promise GPU or page compatibility. Capture receives that same selected
-path as the engine's `chromePath`, including its GPU probe. Active Workers keep their loaded package
-recommendation; restart them explicitly after changing Profile or package dependencies.
+path as the engine's `chromePath`, including its GPU probe. New Builds read current Endpoint
+configuration and project implementation; active Builds keep their selected configuration. A
+Distribution update or change to the Worker's inherited environment requires an explicit Worker
+restart when active work permits. Ordinary Profile edits do not require restarting every process.
 
 The Provider's `hypit.dependencyInstallEnv` disables Puppeteer's browser download while preparing its
 engine/producer npm dependencies. The repository `.puppeteerrc.cjs` does the same for checkout installs.

package/packages/provider-hyperframes-local/src/capture.ts

@@ -11,7 +11,8 @@ import { CaptureConcurrency } from "./concurrency.js";
 import { createOpaqueFrameCapture } from "./opaque-capture.js";
 
 export type CaptureInput = {
-  readonly document: HyperframesDocument;
+  readonly document: Pick<HyperframesDocument, "frameRate" | "frameCount" | "canvas">;
+  readonly frames?: readonly number[];
   readonly range: MediaFrameRange;
   readonly config: ReturnType<typeof resolveExecutionOptions> & { readonly chromePath: string };
   readonly directory: string;
@@ -24,14 +25,16 @@ export async function captureStagedVisual(input: CaptureInput, controller: Abort
   onProgress: (event: HyperframesRenderProgress) => void): Promise<string> {
   const { document, range, config, directory: work } = input;
   const signal = controller.signal;
-  const frameCount = range.endFrameExclusive - range.startFrame;
+  const frameCount = input.frames?.length ?? range.endFrameExclusive - range.startFrame;
+  const selected = input.frames === undefined ? undefined : new Set(input.frames);
+  const at = (index: number) => input.frames?.[index] ?? range.startFrame + index;
   const fps = { num: document.frameRate.numerator, den: document.frameRate.denominator };
   const limit = renderWorkerLimit(config, frameCount, fps.num / fps.den);
   const concurrency = new CaptureConcurrency(limit, config.workers === "auto");
   // Short contiguous batches retain sequential capture while allowing free browsers
   // to help with expensive passages. This queue exists only inside this render.
   const batchCount = Math.max(limit, Math.ceil(frameCount / Math.max(1, Math.round(fps.num / fps.den))));
-  const batches = distributeFrameRange(range, batchCount);
+  const batches = distributeFrameRange({ startFrame: 0, endFrameExclusive: frameCount }, batchCount);
   let nextBatch = 0;
   const started = performance.now();
   const elapsedMs = () => Math.round(performance.now() - started);
@@ -81,7 +84,8 @@ export async function captureStagedVisual(input: CaptureInput, controller: Abort
     const sources = new Map<string, { frames: Map<number, string>; width: number; height: number }>();
     let sourceFrames = 0;
     // One source at a time bounds decoder pressure independently of browser concurrency.
-    const windows = sourceWindows(slots, range);
+    const windows = sourceWindows(slots, input.frames === undefined ? [range]
+      : input.frames.map(frame => ({ startFrame: frame, endFrameExclusive: frame + 1 })));
     const sourceTotal = windows.reduce((sum, source) => sum + source.windows.reduce((count, window) =>
       count + window.endFrameExclusive - window.startFrame, 0), 0);
     if (sourceTotal > 0) onProgress({ phase: "decoding", completed: 0, total: sourceTotal, elapsedMs: elapsedMs() });
@@ -119,7 +123,7 @@ export async function captureStagedVisual(input: CaptureInput, controller: Abort
           const frameIndex = sourceFrameAt(slot, frame);
           const framePath = sources.get(slot.src)?.frames.get(frameIndex);
           // Browser initialization may seek outside the requested interval.
-          if (frame < range.startFrame || frame >= range.endFrameExclusive) continue;
+          if (selected === undefined ? frame < range.startFrame || frame >= range.endFrameExclusive : !selected.has(frame)) continue;
           assert(framePath !== undefined, `HyperFrames has no decoded frame ${frameIndex} for ${slot.id}`);
           payloads.set(slot.id, { framePath, frameIndex });
         }
@@ -132,7 +136,7 @@ export async function captureStagedVisual(input: CaptureInput, controller: Abort
     await mkdir(outputFrames);
     onProgress?.({ phase: "prepared", workers: concurrency.target, sourceFrames, elapsedMs: elapsedMs() });
     const jobs: Promise<void>[] = [];
-    let active = 0, open = 0, initializing = 0, capturedFrames = 0;
+    let active = 0, open = 0, initializing = 0, capturedFrames = 0, capturedBytes = 0;
     let startupMs = 0;
     const launch = (): void => {
       const worker = jobs.length;
@@ -187,13 +191,18 @@ export async function captureStagedVisual(input: CaptureInput, controller: Abort
           if (active > concurrency.target) break;
           const batch = batches[nextBatch++];
           if (batch === undefined) break;
-          for (let frame = batch.startFrame; frame < batch.endFrameExclusive; frame++) {
+          for (let index = batch.startFrame; index < batch.endFrameExclusive; index++) {
+            const frame = at(index);
             signal.throwIfAborted();
             const captured = await stage(`worker ${worker} frame ${frame}`, config.frameTimeoutMs, () => captureFrame(frame));
+            if (input.frames !== undefined) {
+              capturedBytes += captured.buffer.byteLength;
+              assert(capturedBytes <= config.maxRenderedBytes, "HyperFrames PNG output exceeds its byte limit");
+            }
             timing.seekMs += captured.seekMs;
             timing.prepareMs += captured.prepareMs;
             timing.screenshotMs += captured.screenshotMs;
-            await writeFile(join(outputFrames, `${String(frame - range.startFrame).padStart(9, "0")}.png`), captured.buffer);
+            await writeFile(join(outputFrames, `${String(index).padStart(9, "0")}.png`), captured.buffer);
             completed++;
             capturedFrames++;
             if (performance.now() - lastProgressAt >= 1_000) {
@@ -239,6 +248,7 @@ export async function captureStagedVisual(input: CaptureInput, controller: Abort
     if (failure !== undefined) throw failure;
     signal.throwIfAborted();
     await Promise.all(closing.values());
+    if (input.frames !== undefined) return outputFrames;
     const output = join(work, "visual.mp4");
     onProgress({ phase: "encoding", elapsedMs: elapsedMs() });
     const crf = { draft: 28, standard: 23, high: 18 }[config.quality];

package/packages/provider-hyperframes-local/src/index.ts

@@ -6,5 +6,5 @@ export type {
   HyperframesWorkers,
 } from "./provider.js";
 
-export { renderHyperframesVisual } from "./render.js";
+export { renderHyperframesVisual, renderHyperframesFrames } from "./render.js";
 export type { RenderHyperframesVisualOptions, HyperframesRenderProgress } from "./render.js";

package/packages/provider-hyperframes-local/src/output.ts

@@ -38,7 +38,7 @@ function outputFrameCount(stream: ProbeStream): number {
 
 export async function verifyOutput(args: {
   readonly path: string;
-  readonly document: HyperframesDocument;
+  readonly document: Pick<HyperframesDocument, "frameRate" | "frameCount" | "canvas">;
   readonly ffprobePath: string;
   readonly timeoutMs: number;
   readonly maxOutputBytes: number;

package/packages/provider-hyperframes-local/src/process-tree.ts

@@ -33,7 +33,10 @@ export async function killRenderTree(pid: number): Promise<void> {
   for (const child of descendants.reverse()) {
     for (const target of [-child, child]) {
       try { process.kill(target, "SIGKILL"); }
-      catch (error) { if ((error as NodeJS.ErrnoException).code !== "ESRCH") throw error; }
+      catch (error) {
+        const code = (error as NodeJS.ErrnoException).code;
+        if (code !== "ESRCH" && !(target < 0 && code === "EPERM")) throw error;
+      }
     }
   }
   const deadline = Date.now() + cleanupMs;
@@ -76,7 +79,10 @@ export function killRenderDescendantsSync(pid: number): void {
   for (const child of descendants.slice(1).reverse()) {
     for (const target of [-child, child]) {
       try { process.kill(target, "SIGKILL"); }
-      catch (error) { if ((error as NodeJS.ErrnoException).code !== "ESRCH") throw error; }
+      catch (error) {
+        const code = (error as NodeJS.ErrnoException).code;
+        if (code !== "ESRCH" && !(target < 0 && code === "EPERM")) throw error;
+      }
     }
   }
 }

package/packages/provider-hyperframes-local/src/provider.ts

@@ -1,8 +1,8 @@
 import { defineEndpointPackage } from "@hypit/endpoint-kit";
 import { mediaTypes } from "@hypit/media";
-import { renderHyperframesCapabilities, verifyHyperframesVisualRequest } from "@hypit/render-hyperframes";
+import { renderHyperframesCapabilities, renderHyperframesTypes, verifyHyperframesFramesRequest, hyperframesFramesDomain, verifyHyperframesVisualRequest } from "@hypit/render-hyperframes";
 import { canonicalize } from "@hypit/protocol";
-import { renderHyperframesVisual, resolveExecutionOptions, renderWorkerLimit } from "./render.js";
+import { renderHyperframesVisual, renderHyperframesFrames, resolveExecutionOptions, renderWorkerLimit } from "./render.js";
 import type { HyperframesExecutionOptions } from "./options.js";
 import { renderProgressReporter } from "./progress.js";
 
@@ -67,6 +67,33 @@ export function createLocalHyperframesProvider(config: CreateLocalHyperframesPro
           await progress.flush();
         }
       },
+    }, {
+      lifecycle: "immediate" as const,
+      capability: renderHyperframesCapabilities.renderFrames,
+      returns: renderHyperframesTypes.frames,
+      ...(config.browserCapacity === undefined ? {} : {
+        resources: [{ id: browsers, limit: config.browserCapacity }],
+        unitsForRequest: (request: import("@hypit/endpoint-kit").EndpointRequest) => {
+          verifyHyperframesFramesRequest(request.constraints);
+          const document = hyperframesFramesDomain(request.constraints);
+          return { [browsers]: renderWorkerLimit(reserved, request.constraints.frames.length,
+            document.frameRate.numerator / document.frameRate.denominator) };
+        },
+      }),
+      handler: async context => {
+        const request = context.need.constraints;
+        verifyHyperframesFramesRequest(request);
+        const progress = renderProgressReporter(context.reportProgress, request.frames.length);
+        try {
+          const frames = await renderHyperframesFrames(request, { ...config,
+            ...(execution.chromePath === undefined ? { browserVersion: execution.browserVersion! } : { chromePath: execution.chromePath }),
+            browserCacheDirectory: execution.browserCacheDirectory,
+            workers: execution.workers, maxWorkers,
+            resources: context.resources, onProgress: progress.onProgress,
+            ...(context.reportDiagnostic === undefined ? {} : { onDiagnostic: context.reportDiagnostic }) });
+          return { value: { kind: "inline", value: canonicalize(frames) } };
+        } finally { await progress.flush(); }
+      },
     }],
   });
 }

package/packages/provider-hyperframes-local/src/render.ts

@@ -3,12 +3,12 @@ import { mkdtemp, readFile, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { EndpointInvocationContext } from "@hypit/endpoint-kit";
-import { stageHyperframesProject } from "@hypit/hyperframes/project";
+import { stageHyperframesProject, stageHyperframesHtmlProject } from "@hypit/hyperframes/project";
 import { sealRenderedVisual } from "@hypit/media";
 import type { MediaFrameRange, RenderedVisual } from "@hypit/media";
 import { verifyCompositableSurfaceFile } from "@hypit/media-execution";
-import { verifyHyperframesVisualRequest } from "@hypit/render-hyperframes";
-import type { HyperframesVisualRequest } from "@hypit/render-hyperframes";
+import { verifyHyperframesVisualRequest, verifyHyperframesFramesRequest, hyperframesFramesDomain } from "@hypit/render-hyperframes";
+import type { HyperframesVisualRequest, HyperframesFramesRequest, HyperframesFrames } from "@hypit/render-hyperframes";
 import { isStreamingResourceStore } from "@hypit/runtime";
 import type { HyperframesExecutionOptions } from "./options.js";
 import { assert, positiveInteger } from "./process.js";
@@ -75,10 +75,22 @@ export async function renderHyperframesVisual(
   options: RenderHyperframesVisualOptions,
 ): Promise<RenderedVisual> {
   verifyHyperframesVisualRequest(request);
+  return capture(request, options) as Promise<RenderedVisual>;
+}
+
+export async function renderHyperframesFrames(request: HyperframesFramesRequest, options: RenderHyperframesVisualOptions): Promise<HyperframesFrames> {
+  verifyHyperframesFramesRequest(request);
+  return capture(request, options) as Promise<HyperframesFrames>;
+}
+
+async function capture(request: HyperframesVisualRequest | HyperframesFramesRequest, options: RenderHyperframesVisualOptions): Promise<RenderedVisual | HyperframesFrames> {
   const config = { ...resolveExecutionOptions(options), chromePath: browserExecutablePath(options) };
-  const { document } = request;
-  const range = request.range ?? { startFrame: 0, endFrameExclusive: document.frameCount };
-  const frameCount = range.endFrameExclusive - range.startFrame;
+  const frames = "frames" in request ? request.frames : undefined;
+  const document = "frames" in request ? hyperframesFramesDomain(request) : request.document;
+  const range = frames === undefined
+    ? (request as HyperframesVisualRequest).range ?? { startFrame: 0, endFrameExclusive: document.frameCount }
+    : { startFrame: frames[0]!, endFrameExclusive: frames.at(-1)! + 1 };
+  const frameCount = frames?.length ?? range.endFrameExclusive - range.startFrame;
   const controller = new AbortController();
   const signal = options.signal === undefined ? controller.signal : AbortSignal.any([controller.signal, options.signal]);
   const started = performance.now();
@@ -103,23 +115,25 @@ export async function renderHyperframesVisual(
     signal.throwIfAborted();
     await requireBrowserExecutable(config.chromePath, config.browserVersion);
     await options.onDiagnostic?.({ level: "info", message:
-      `Render ${frameCount} frames; workers ${config.workers} (limit ${renderWorkerLimit(config, frameCount, document.frameRate.numerator / document.frameRate.denominator)}); opaque fast PNG; quality ${config.quality}; GPU ${config.browserGpu}; browser ${config.chromePath}; encoder ${config.ffmpegPath}` });
+      `Capture ${frameCount} frames; workers ${config.workers} (limit ${renderWorkerLimit(config, frameCount, document.frameRate.numerator / document.frameRate.denominator)}); opaque fast PNG; GPU ${config.browserGpu}; browser ${config.chromePath}`
+      + (frames === undefined ? `; quality ${config.quality}; encoder ${config.ffmpegPath}` : "; PNG output") });
     options.onProgress?.({ phase: "staging", elapsedMs: 0 });
     work = await mkdtemp(join(tmpdir(), "hypit-hyperframes-local-"));
-    await stageHyperframesProject({ document, directory: work, signal,
-      read: async (artifact, readSignal) => {
+    const read: import("@hypit/hyperframes/project").HyperframesArtifactReader = async (artifact, readSignal) => {
         const io = { signal: readSignal! };
         const bytes = isStreamingResourceStore(options.resources)
           ? await options.resources.open(artifact.resource, io) : await options.resources.get(artifact.resource, io);
         assert(bytes !== undefined, `HyperFrames Artifact ${artifact.resource} is unavailable`);
         return bytes;
-      },
+      };
+    if ("project" in request) await stageHyperframesHtmlProject({ project: request.project, directory: work, signal, read });
+    else await stageHyperframesProject({ document: request.document, directory: work, signal, read,
       validateSurface: (surface, path, probeSignal) => verifyCompositableSurfaceFile({ surface, path,
         ffprobePath: config.ffprobePath, processTimeoutMs: config.processTimeoutMs,
         maxProbeOutputBytes: config.maxProcessOutputBytes, signal: probeSignal! }),
     });
     changePhase("decoding source frames");
-    await runCaptureProcess({ document, range, config, directory: work,
+    await runCaptureProcess({ document, range, ...(frames === undefined ? {} : { frames }), config, directory: work,
       engineModule: import.meta.resolve("@hyperframes/engine"),
       producerModule: import.meta.resolve("@hyperframes/producer"),
     }, signal, (event) => {
@@ -132,22 +146,33 @@ export async function renderHyperframesVisual(
     signal.throwIfAborted();
     changePhase("storing output");
     options.onProgress?.({ phase: "storing", elapsedMs: Math.round(performance.now() - started) });
-    const output = join(work, "visual.mp4");
-    let artifact;
-    if (isStreamingResourceStore(options.resources)) {
-      const stream = createReadStream(output, { signal });
-      const closed = finished(stream).catch(() => {});
-      try { artifact = await options.resources.putStream(stream, "video/mp4", { signal }); }
-      finally { stream.destroy(); await closed; }
+    const store = async (output: string, mediaType: string) => {
+      if (isStreamingResourceStore(options.resources)) {
+        const stream = createReadStream(output, { signal });
+        const closed = finished(stream).catch(() => {});
+        try { return await options.resources.putStream(stream, mediaType, { signal }); }
+        finally { stream.destroy(); await closed; }
+      }
+      return options.resources.put(await readFile(output, { signal }), mediaType, { signal });
+    };
+    let result: RenderedVisual | HyperframesFrames;
+    if (frames === undefined) {
+      result = sealRenderedVisual({ frameRate: document.frameRate, frameCount, canvas: document.canvas,
+        artifact: await store(join(work, "visual.mp4"), "video/mp4") });
     } else {
-      artifact = await options.resources.put(await readFile(output, { signal }), "video/mp4", { signal });
+      const artifacts = [];
+      for (let index = 0; index < frames.length; index++) {
+        signal.throwIfAborted();
+        artifacts.push(await store(join(work, "frames", `${String(index).padStart(9, "0")}.png`), "image/png"));
+      }
+      result = artifacts;
     }
     signal.throwIfAborted();
 
     changePhase("complete");
     await Promise.all(diagnostics);
     options.onProgress?.({ phase: "complete", frames: frameCount, elapsedMs: Math.round(performance.now() - started) });
-    return sealRenderedVisual({ frameRate: document.frameRate, frameCount, canvas: document.canvas, artifact });
+    return result;
   } catch (error) {
     if (signal.aborted) throw signal.reason;
     controller.abort(error);

package/packages/provider-hyperframes-local/src/sampling.ts

@@ -51,9 +51,10 @@ export function sourceFrameAt(slot: VideoSlot, frame: number): number {
   return value;
 }
 
-export function sourceWindows(slots: readonly VideoSlot[], range: MediaFrameRange) {
+export function sourceWindows(slots: readonly VideoSlot[], selection: MediaFrameRange | readonly MediaFrameRange[]) {
+  const ranges: readonly MediaFrameRange[] = Array.isArray(selection) ? selection : [selection as MediaFrameRange];
   const sources = new Map<string, { fps: VideoSlot["sourceFps"]; windows: MediaFrameRange[] }>();
-  for (const slot of slots) {
+  for (const range of ranges) for (const slot of slots) {
     const first = Math.max(range.startFrame, slot.startFrame);
     const last = Math.min(range.endFrameExclusive, slot.endFrameExclusive) - 1;
     if (last < first) continue;

package/packages/provider-whisperx-local/README.md

@@ -91,16 +91,19 @@ torch caches and their environment settings. Changing a running service's cache
 an explicit restart when idle, just like changing its model or hardware. The managed installation
 does not require a global `whisperx` shell command.
 
-Preparation and service processes inherit the environment of the command starting them. Set
-network and cache variables there before `programs up` or `runtime up`. A service already running
-retains its earlier environment. Inspect its reported log before deciding whether a selected
-Program needs restarting, and account for active work using it.
+Preparation and service processes inherit the environment of the command starting them. Set download
+route variables on `programs prepare` (or the preparation performed by `programs up` / `runtime up`).
+Changing only a download source does not require restarting a running service using the same cache.
+Cache settings must select the same resource location for preparation and the service. A running
+service retains its earlier environment; arrange an idle restart when changing that location or its
+inference settings. Inspect its reported configuration and logs, and account for active work.
 
 If NLTK refuses a proxied fetch during preparation, follow the service’s
 [explicit proxy preparation](../../services/whisperx/README.md#preparing-sentence-data-through-a-proxy).
 
 Preparation commands write `install.log`; the running service writes `program.log`, with stderr in
-`program.err.log` on Windows. Inspect the stderr file for Python model-loading and download messages.
+`program.err.log` on Windows. Inspect service logs for Python model-loading and inference messages;
+download messages belong to preparation's `install.log`.
 `programs status` reports these files as `installationLogPath`, `logPath` and `errorLogPath` when they
 exist, even before installation finishes. Preparation notices name the Python environment and selected model/language resources separately. The service logs the start and completion of ASR loading, transcription,
 language-alignment model loading and alignment, with elapsed times. Downloads happen only in

package/packages/render-hyperframes/README.md

@@ -6,6 +6,15 @@ semantic coverage through the same frame and audio pipeline.
 
 Explicit author and capability boundary for final HyperFrames video rendering.
 
+`@hypit/render-hyperframes@1#render-frames` captures an existing programme's selected frames.
+`hyperframesFramesRequest({ document, frames })` accepts a `HyperframesDocument` and strictly
+increasing original-frame indices. `{ project: { html, assets }, frames }` accepts already
+materialized HTML with its URL-addressed assets. The `Frames` result is a PNG `BlobRef[]` in request
+order; the request already owns the frame identities. Canvas and clock stay in the input.
+This capability requests picture capture only. File names, contact sheets and pagination belong to
+the caller. `hypit snapshot` invokes it immediately through a selected Profile; there is no Build
+or video encoding in that observation path.
+
 The package owns `<render:Video composition={...}/>` and lowers it to ordinary Operations that:
 
 1. obtain the `ProgramSpace` from the Timeline input and compile the referenced `Composition` into a `HyperframesDocument`;

package/packages/render-hyperframes/src/index.ts

@@ -4,3 +4,6 @@ export { renderHyperframesCapabilities, renderHyperframesManifest, renderHyperfr
 export { hyperframesVisualRequest, verifyHyperframesVisualRequest } from "./product.js";
 export type { HyperframesVisualRequest } from "./product.js";
 export { decodeHyperframesRenderSurface } from "./surface.js";
+export { renderHyperframesTypes } from "./manifest.js";
+export { hyperframesFramesRequest, hyperframesFramesDomain, verifyHyperframesFramesRequest, verifyHyperframesFrames } from "./product.js";
+export type { HyperframesFramesRequest, HyperframesFrames } from "./product.js";

package/packages/render-hyperframes/src/manifest.ts

@@ -12,6 +12,7 @@ import type {
   CapabilityRef,
   ModuleManifest,
   ProducerRef,
+  TypeRef,
 } from "@hypit/protocol";
 import {
   mediaPipelineModuleRef,
@@ -20,7 +21,11 @@ import {
 export const renderHyperframesModuleRef = { name: "@hypit/render-hyperframes", version: "1" } as const;
 export const renderHyperframesCapabilities = {
   renderVisual: { module: renderHyperframesModuleRef, name: "render-visual" },
+  renderFrames: { module: renderHyperframesModuleRef, name: "render-frames" },
 } satisfies Record<string, CapabilityRef>;
+export const renderHyperframesTypes = {
+  frames: { module: renderHyperframesModuleRef, name: "Frames" },
+} satisfies Record<string, TypeRef>;
 export const renderHyperframesProducers = {
   requestVisualRange: { module: renderHyperframesModuleRef, name: "request-visual-range" },
   requestVisual: { module: renderHyperframesModuleRef, name: "request-visual-render" },
@@ -70,11 +75,11 @@ export const renderHyperframesManifest: ModuleManifest = {
     { module: hyperframesModuleRef },
     { module: mediaPipelineModuleRef },
   ],
-  types: [],
+  types: [{ name: renderHyperframesTypes.frames.name }],
   capabilities: [{
     name: renderHyperframesCapabilities.renderVisual.name,
     returns: mediaTypes.renderedVisual,
-  }],
+  }, { name: renderHyperframesCapabilities.renderFrames.name, returns: renderHyperframesTypes.frames }],
   producers: [
     {
       name: renderHyperframesProducers.requestVisual.name,

package/packages/render-hyperframes/src/product.ts

@@ -1,6 +1,8 @@
 import type { CanonicalValue } from "@hypit/protocol";
-import { assertHyperframesDocument } from "@hypit/hyperframes";
-import type { HyperframesDocument } from "@hypit/hyperframes";
+import { assertHyperframesDocument, assertHyperframesHtmlProject, hyperframesHtmlDomain } from "@hypit/hyperframes";
+import type { HyperframesDocument, HyperframesHtmlProject } from "@hypit/hyperframes";
+import type { BlobRef } from "@hypit/protocol";
+import { isResourceId } from "@hypit/protocol";
 import { verifyMediaFrameRange } from "@hypit/media";
 import type { MediaFrameRange } from "@hypit/media";
 
@@ -9,6 +11,43 @@ export type HyperframesVisualRequest = {
   readonly range?: MediaFrameRange;
 };
 
+/** Select original programme frames, in strictly increasing order. */
+export type HyperframesFramesRequest = ({ readonly document: HyperframesDocument } | { readonly project: HyperframesHtmlProject }) & {
+  readonly frames: readonly number[];
+};
+/** PNG images in request order. The request already supplies each frame's identity. */
+export type HyperframesFrames = readonly BlobRef[];
+
+export function hyperframesFramesDomain(request: HyperframesFramesRequest) {
+  return "document" in request ? request.document : hyperframesHtmlDomain(request.project.html);
+}
+
+export function verifyHyperframesFramesRequest(value: unknown): asserts value is HyperframesFramesRequest {
+  if (!value || typeof value !== "object" || Array.isArray(value)
+    || Object.keys(value).some(key => !["document", "project", "frames"].includes(key))
+    || ("document" in value) === ("project" in value)) throw new Error("Frame request needs exactly one document or HTML project, and frames");
+  const request = value as HyperframesFramesRequest;
+  if ("document" in request) assertHyperframesDocument(request.document);
+  else assertHyperframesHtmlProject(request.project);
+  const { frameCount } = hyperframesFramesDomain(request);
+  if (!Array.isArray(request.frames) || request.frames.length === 0 || request.frames.some((frame, index) =>
+    !Number.isSafeInteger(frame) || frame < 0 || frame >= frameCount || (index > 0 && frame <= request.frames[index - 1]!))) {
+    throw new Error(`Frames must be strictly increasing integers in [0, ${frameCount})`);
+  }
+}
+
+export function hyperframesFramesRequest(request: HyperframesFramesRequest): CanonicalValue {
+  verifyHyperframesFramesRequest(request);
+  return request as unknown as CanonicalValue;
+}
+
+export function verifyHyperframesFrames(value: unknown): asserts value is HyperframesFrames {
+  if (!Array.isArray(value) || value.length === 0 || value.some(blob => !blob || blob.kind !== "blob"
+    || !isResourceId(blob.resource) || blob.mediaType !== "image/png" || !Number.isSafeInteger(blob.size) || blob.size <= 0)) {
+    throw new Error("HyperFrames frames must be PNG BlobRefs in request order");
+  }
+}
+
 export function verifyHyperframesVisualRequest(value: unknown): asserts value is HyperframesVisualRequest {
   if (value === null || typeof value !== "object" || Array.isArray(value)
     || Object.keys(value).some((key) => key !== "document" && key !== "range")) {

package/packages/runtime-local/src/process-control.ts

@@ -23,7 +23,10 @@ function signal(pid: number, force: boolean): ProcessStopResult {
       process.kill(target, name);
       return "sent";
     } catch (error) {
-      if (errorCode(error) === "EPERM") return "denied";
+      if (errorCode(error) === "EPERM") {
+        if (target < 0) continue;
+        return "denied";
+      }
       if (errorCode(error) !== "ESRCH") throw error;
     }
   }

package/packages/runtime-local/src/programs.ts

@@ -196,13 +196,25 @@ function powershellLiteral(value: string): string {
  * as `-e` followed by the first word of the script, and node exits on the syntax error. Given one
  * string it passes that string through as the command line, which is what this builds.
  */
-function windowsCommandLine(args: readonly string[]): string {
+export function windowsCommandLine(args: readonly string[]): string {
   return args.map((value) => {
     if (value !== "" && !/[\s"]/u.test(value)) return value;
     // A quote is escaped by the backslashes before it, so those double; a trailing run doubles too,
     // because the closing quote would otherwise escape itself against them.
-    const escaped = value.replace(/(\\*)"/gu, '$1$1\\"').replace(/(\\*)$/u, "$1$1");
-    return `"${escaped}"`;
+    let escaped = '"';
+    let backslashes = 0;
+    for (const character of value) {
+      if (character === "\\") {
+        backslashes++;
+      } else if (character === '"') {
+        escaped += "\\".repeat(backslashes * 2 + 1) + '"';
+        backslashes = 0;
+      } else {
+        escaped += "\\".repeat(backslashes) + character;
+        backslashes = 0;
+      }
+    }
+    return escaped + "\\".repeat(backslashes * 2) + '"';
   }).join(" ");
 }
 

package/packages/runtime-local/src/supervisor.ts

@@ -119,7 +119,14 @@ export async function superviseBuilds(options: {
         if (options.signal.aborted) break;
         accepting ??= launch();
         const carrier = accepting;
-        await carrier.ready;
+        try {
+          await carrier.ready;
+        } catch (error) {
+          if (accepting === carrier) accepting = undefined;
+          if (options.signal.aborted) break;
+          await finishInterrupted(build, `Build executor startup failed: ${error instanceof Error ? error.message : String(error)}; create a new Build to continue`);
+          continue;
+        }
         if (carrier.exited) break;
         if (accepting !== carrier) continue;
         await state.execution.start(build);

package/packages/script/README.md

@@ -27,8 +27,10 @@ parser is inside a Segment, a valid bare tag such as `<ALICE>` is a Role Cue. Th
 not indentation: the compact spelling
 `<opening><ALICE>I speak first.<BOB>I answer.</opening>` has the same semantic value.
 
-A Role Cue is optional. Text before the first Role Cue is a roleless Turn, and Role state is reset
-when every Segment closes; a Role can never leak into the following Segment.
+A Role Cue is optional. A Segment without Role Cues contains a roleless Turn. If Roles are used,
+the first Cue must precede that Segment's spoken text. Role state resets when the Segment closes;
+a Role can never leak into the following Segment. Role labels may use Unicode letters, marks and
+numbers; capitalization does not distinguish Roles from Segments.
 
 An empty Segment such as `<empty></empty>` (or `<empty/>`) is valid. `empty` is an ordinary
 author-chosen name, not a reserved keyword. It retains the Segment identity and both boundary anchors
@@ -101,7 +103,7 @@ Units; it does not split the Segment, cut the picture or end a Selection.
 <script id="story">
   <exchange>
     <HOST> I use it || every day, || since <2012 | twenty twelve>.
-    <GUEST> Even @{proof} on holiday @{/proof}?
+    <GUEST> Even @{proof}on holiday?@{/proof}
     <HOST> @{answer!} Especially then.
   </exchange>
 </script>
@@ -118,13 +120,18 @@ These units support precise timing and highlighting. A Caption Cue can hold a wh
 `||` chooses its handoff independently of character counts or visual line wrapping.
 
 Annotations do not create speech boundaries. Comments are transparent (`hel<!--note-->lo`
-remains `hello`); a postfix attribute or `||` inside a word is invalid. Script analyzes a complete
+remains `hello`), including when an attribute follows a comment or zero-width marker:
+`hello<!--note-->{emphasis}` and `hello@{beat!}{emphasis}` still annotate `hello`.
+An authored space before the attribute remains invalid. A postfix attribute or `||` inside a word
+is invalid. Script analyzes a complete
 prose run before binding these constructs. An explicit Dual correspondence and a speaker/Segment
 boundary remain authored structure. Shared Dual groups still expose their internal speech anchors.
 
 A Dual display side is literal authored text, including symbols and emoji: `<😀|smile>` and
 `<.|dot>` have explicit speech correspondence and require no invented speech token for the symbol.
 A literal-only display is one display surface within that correspondence.
+Every Dual needs at least one spoken word on its explicit or shared speech side. `<API|...>` cannot
+provide timed correspondence for `API` and is rejected; punctuation and markers are not spoken words.
 
 ## Display spelling and separators