@hypit/hypit 0.1.13 → 0.2.0

package/packages/media-execution/src/surface.ts

@@ -1,9 +1,10 @@
 import { spawn } from "node:child_process";
-import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { mkdtemp, rm, stat, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
 import { assertCompositableSurfaceRef } from "@hypit/media";
+import { mediaProcessEnv } from "./process-env.js";
 import type { CompositableSurfaceRef } from "@hypit/media";
 
 type JsonObject = Record<string, unknown>;
@@ -57,7 +58,7 @@ async function runProcess(args: {
       shell: false,
       windowsHide: true,
       stdio: ["ignore", "pipe", "pipe"],
-      env: { PATH: process.env.PATH ?? "" },
+      env: mediaProcessEnv(),
     });
     const stdout: Buffer[] = [];
     let bytes = 0;
@@ -192,95 +193,101 @@ async function pixelFormatAlpha(
   return result;
 }
 
-function suffix(mediaType: string): string {
-  if (mediaType === "image/png") return ".png";
-  if (mediaType === "image/webp") return ".webp";
-  if (mediaType === "video/webm") return ".webm";
-  if (mediaType === "video/mp4") return ".mp4";
-  throw new Error(`Surface media type ${mediaType} is unsupported`);
-}
-
-/**
- * Decode and verify one typed Surface before its bytes enter a renderer.
- *
- * This is an admission gate, not a second media Product. Success returns no
- * side-channel facts; anything a later graph step needs must be an explicit output.
- */
-export async function verifyCompositableSurfaceBytes(options: {
+type SurfaceInspectionOptions = {
   readonly surface: CompositableSurfaceRef;
-  readonly bytes: Uint8Array;
   readonly ffprobePath?: string;
   readonly processTimeoutMs?: number;
   readonly maxProbeOutputBytes?: number;
   readonly signal?: AbortSignal;
+};
+
+/** Inspect bytes supplied by callers that do not already own a staged file. */
+export async function verifyCompositableSurfaceBytes(options: SurfaceInspectionOptions & {
+  readonly bytes: Uint8Array;
+}): Promise<void> {
+  options.signal?.throwIfAborted();
+  assertCompositableSurfaceRef(options.surface);
+  assert(options.bytes.byteLength === options.surface.artifact.size,
+    `Surface ${options.surface.artifact.resource} byte size differs`);
+  const directory = await mkdtemp(join(tmpdir(), "hypit-surface-verify-"));
+  try {
+    // FFprobe detects the encoded media itself; both entry points inspect the same formats.
+    const path = join(directory, "surface");
+    await writeFile(path, options.bytes, { signal: options.signal });
+    await verifyCompositableSurfaceFile({ ...options, path });
+  } finally {
+    await rm(directory, { recursive: true, force: true }).catch(() => {});
+  }
+}
+
+/**
+ * Inspect an existing execution file without copying it. The caller owns the file
+ * and keeps it unchanged until this call settles. Success returns no side-channel facts.
+ */
+export async function verifyCompositableSurfaceFile(options: SurfaceInspectionOptions & {
+  readonly path: string;
 }): Promise<void> {
   const controller = new AbortController();
   const signal = options.signal === undefined ? controller.signal : AbortSignal.any([controller.signal, options.signal]);
   signal.throwIfAborted();
   assertCompositableSurfaceRef(options.surface);
-  assert(options.bytes.byteLength === options.surface.artifact.size,
+  assert((await stat(options.path)).size === options.surface.artifact.size,
     `Surface ${options.surface.artifact.resource} byte size differs`);
+  signal.throwIfAborted();
   const ffprobePath = options.ffprobePath ?? "ffprobe";
   const timeoutMs = options.processTimeoutMs ?? 120_000;
   const maxOutputBytes = options.maxProbeOutputBytes ?? 8 * 1024 * 1024;
-  const directory = await mkdtemp(join(tmpdir(), "hypit-surface-verify-"));
-  try {
-    const path = join(directory, `surface${suffix(options.surface.artifact.mediaType)}`);
-    await writeFile(path, options.bytes, { signal });
-    const pending = [
-      runProcess({
-        executable: ffprobePath,
-        argv: ["-v", "error", "-print_format", "json", "-show_streams", "-count_frames", path],
-        timeoutMs,
-        maxOutputBytes, signal,
-      }),
-      pixelFormatAlpha(ffprobePath, timeoutMs, maxOutputBytes, signal),
-    ] as const;
-    await Promise.allSettled(pending.map(async (job) => {
-      try { return await job; } catch (error) { controller.abort(error); throw error; }
-    }));
-    signal.throwIfAborted();
-    const [probe, formats] = await Promise.all(pending);
-    const root = json(probe, "ffprobe Surface query");
-    assert(Array.isArray(root.streams) && root.streams.length === 1,
-      "Surface must contain exactly one visual stream and no audio or auxiliary streams");
-    const stream = root.streams[0] as ProbeStream;
-    assert(stream.codec_type === "video", "Surface stream is not visual");
-    assert(stream.disposition?.attached_pic !== 1, "Surface cannot be an attached-picture stream");
-    const width = positiveInteger(stream.width, "Surface width");
-    const height = positiveInteger(stream.height, "Surface height");
-    assert(width === options.surface.width && height === options.surface.height,
-      "Surface decoded dimensions differ from its declaration");
-    assert(stream.sample_aspect_ratio === undefined || stream.sample_aspect_ratio === "1:1",
-      "Surface must use square pixels");
-    assert(rotation(stream) === 0, "Surface must not depend on display rotation metadata");
-    assert(stream.field_order === undefined || stream.field_order === "progressive" || stream.field_order === "unknown",
-      "Surface must be progressive");
-    assertSrgb(stream);
+  const pending = [
+    runProcess({
+      executable: ffprobePath,
+      argv: ["-v", "error", "-print_format", "json", "-show_streams", "-count_frames", options.path],
+      timeoutMs,
+      maxOutputBytes, signal,
+    }),
+    pixelFormatAlpha(ffprobePath, timeoutMs, maxOutputBytes, signal),
+  ] as const;
+  await Promise.allSettled(pending.map(async (job) => {
+    try { return await job; } catch (error) { controller.abort(error); throw error; }
+  }));
+  signal.throwIfAborted();
+  const [probe, formats] = await Promise.all(pending);
+  const root = json(probe, "ffprobe Surface query");
+  assert(Array.isArray(root.streams) && root.streams.length === 1,
+    "Surface must contain exactly one visual stream and no audio or auxiliary streams");
+  const stream = root.streams[0] as ProbeStream;
+  assert(stream.codec_type === "video", "Surface stream is not visual");
+  assert(stream.disposition?.attached_pic !== 1, "Surface cannot be an attached-picture stream");
+  const width = positiveInteger(stream.width, "Surface width");
+  const height = positiveInteger(stream.height, "Surface height");
+  assert(width === options.surface.width && height === options.surface.height,
+    "Surface decoded dimensions differ from its declaration");
+  assert(stream.sample_aspect_ratio === undefined || stream.sample_aspect_ratio === "1:1",
+    "Surface must use square pixels");
+  assert(rotation(stream) === 0, "Surface must not depend on display rotation metadata");
+  assert(stream.field_order === undefined || stream.field_order === "progressive" || stream.field_order === "unknown",
+    "Surface must be progressive");
+  assertSrgb(stream);
 
-    assert(typeof stream.pix_fmt === "string" && stream.pix_fmt.length > 0,
-      "Surface pixel format is absent");
-    const pixelAlpha = formats.get(stream.pix_fmt);
-    assert(pixelAlpha !== undefined, `Surface pixel format ${stream.pix_fmt} is unknown to ffprobe`);
-    const taggedAlpha = stream.tags?.alpha_mode === "1" || stream.tags?.alpha_mode === "straight";
-    const hasAlpha = pixelAlpha || taggedAlpha;
-    if (options.surface.alphaMode === "straight") {
-      assert(hasAlpha, "Surface declares straight alpha but its bytes carry no alpha channel");
-    } else {
-      assert(!hasAlpha, "Surface declares opaque pixels but its encoded format carries alpha");
-    }
+  assert(typeof stream.pix_fmt === "string" && stream.pix_fmt.length > 0,
+    "Surface pixel format is absent");
+  const pixelAlpha = formats.get(stream.pix_fmt);
+  assert(pixelAlpha !== undefined, `Surface pixel format ${stream.pix_fmt} is unknown to ffprobe`);
+  const taggedAlpha = stream.tags?.alpha_mode === "1" || stream.tags?.alpha_mode === "straight";
+  const hasAlpha = pixelAlpha || taggedAlpha;
+  if (options.surface.alphaMode === "straight") {
+    assert(hasAlpha, "Surface declares straight alpha but its bytes carry no alpha channel");
+  } else {
+    assert(!hasAlpha, "Surface declares opaque pixels but its encoded format carries alpha");
+  }
 
-    const frameCount = positiveInteger(stream.nb_read_frames ?? stream.nb_frames, "Surface frame count");
-    if (options.surface.timing.kind === "still") {
-      assert(frameCount === 1, "Still Surface must decode to exactly one frame");
-    } else {
-      assert(frameCount === options.surface.timing.frameCount,
-        "Surface decoded frame count differs from its declaration");
-      const rate = rational(stream.avg_frame_rate ?? stream.r_frame_rate, "Surface frame rate");
-      assert(sameRational(rate, options.surface.timing.frameRate),
-        "Surface decoded frame rate differs from its declaration");
-    }
-  } finally {
-    await rm(directory, { recursive: true, force: true }).catch(() => {});
+  const frameCount = positiveInteger(stream.nb_read_frames ?? stream.nb_frames, "Surface frame count");
+  if (options.surface.timing.kind === "still") {
+    assert(frameCount === 1, "Still Surface must decode to exactly one frame");
+  } else {
+    assert(frameCount === options.surface.timing.frameCount,
+      "Surface decoded frame count differs from its declaration");
+    const rate = rational(stream.avg_frame_rate ?? stream.r_frame_rate, "Surface frame rate");
+    assert(sameRational(rate, options.surface.timing.frameRate),
+      "Surface decoded frame rate differs from its declaration");
   }
 }

package/packages/narrative/README.md

@@ -26,4 +26,6 @@ no Tokens. Authored order is independent of gaps, overlap or placement order in
 Caption uses this content query and the Narrative's display correspondence to select complete
 subtitle units. Timeline projection uses the same semantic references to locate events in physical
 time. Neither operation substitutes for the other. Token lookup returns Tokens, not reconstructed
-source prose: whitespace, comments and source-preserving edits remain the author language's concern.
+source prose: comments and source-preserving edits remain the author language's concern. Caption
+Display Words separately carry `separatorBefore` (`""` or `" "`) so consumers can reconstruct the
+authored display spelling without guessing from Token boundaries or importing an author parser.

package/packages/narrative/src/schema.ts

@@ -29,6 +29,7 @@ export const narrativeExcerptSchema: ValueSchema = object({
   tokenStart: { schema: integer }, tokenEndExclusive: { schema: integer },
 });
 const captionDisplayWord = object({
+  separatorBefore: { schema: { kind: "string", enum: ["", " "] } },
   id: { schema: string }, unitId: { schema: string }, segmentId: { schema: string },
   turnId: { schema: string }, role: { schema: string, optional: true }, text: { schema: string },
   attributes: { schema: { kind: "array", items: object({

package/packages/narrative/src/types.ts

@@ -50,6 +50,8 @@ export type NarrativeMomentRef = NarrativeMoment & {
 
 /** One author-visible word surface. Punctuation owned by the surface is preserved. */
 export type CaptionDisplayWord = {
+  /** Authored display separator from the preceding word; ignored at a displayed line start. */
+  readonly separatorBefore: "" | " ";
   readonly id: string;
   readonly unitId: string;
   readonly segmentId: string;

package/packages/package-loader-node/README.md

@@ -51,3 +51,13 @@ This is trusted execution, not a sandbox. Builtins, native libraries and process
 (including `process.cwd()` and `process.env`) remain shared. Existing module bindings do not change
 under an active Build; a file or dependency first
 read later uses ordinary filesystem semantics. Scoped loading does not make a project tree immutable.
+
+## Dependency installation options
+
+A Distribution package may declare `hypit.dependencyInstallEnv` in its package.json, keyed by its
+ordinary direct external dependency names. Each value is an environment-variable map passed to that
+dependency's explicit npm installation. For example, an owner can disable an SDK's automatic asset
+download and prepare that asset through its ManagedProgram instead. Options do not propagate to
+unrelated installations or the caller's process. Conflicting values from selected packages fail;
+no package wins by discovery order. They are command inputs, not a second dependency inventory,
+readiness record, or new version system. Project packages remain owned by their package manager.

package/packages/package-loader-node/src/index.ts

@@ -15,6 +15,7 @@ export {
 } from "./distribution-resolution.js";
 export {
   locateNodePackage,
+  NodePackageNotFoundError,
   externalPackageInstallRoot,
   resolveNodePackageExecutable,
   resolveNodePackageResource,

package/packages/package-loader-node/src/loader.ts

@@ -16,7 +16,7 @@ import { externalPackageRoots, locateNodePackage } from "./location.js";
 type PackageJson = {
   readonly name: string;
   readonly version?: string;
-  readonly hypit?: { readonly activation?: string };
+  readonly hypit?: { readonly activation?: string; readonly dependencyInstallEnv?: Readonly<Record<string, Readonly<Record<string, string>>>> };
   readonly dependencies: Readonly<Record<string, string>>;
 };
 
@@ -43,7 +43,19 @@ function parsePackageJson(value: unknown, subject: string): PackageJson {
   return {
     name: text(item.name, `${subject}.name`),
     ...(item.version === undefined ? {} : { version: text(item.version, `${subject}.version`) }),
-    ...(hypit?.activation === undefined ? {} : { hypit: { activation: text(hypit.activation, `${subject}.hypit.activation`) } }),
+    ...(hypit === undefined ? {} : { hypit: {
+      ...(hypit.activation === undefined ? {} : { activation: text(hypit.activation, `${subject}.hypit.activation`) }),
+      ...(hypit.dependencyInstallEnv === undefined ? {} : { dependencyInstallEnv: Object.fromEntries(
+        Object.entries(object(hypit.dependencyInstallEnv, `${subject}.hypit.dependencyInstallEnv`)).map(([name, raw]) => {
+          assert(Object.hasOwn(dependencies, name) && !name.startsWith("@hypit/"), `${subject}: installation environment must name a direct external dependency: ${name}`);
+          const env = object(raw, `${subject}.hypit.dependencyInstallEnv.${name}`);
+          for (const [key, value] of Object.entries(env)) {
+            assert(/^[A-Za-z_][A-Za-z0-9_]*$/u.test(key) && typeof value === "string", `${subject}: invalid installation environment for ${name}`);
+          }
+          return [name, env as Record<string, string>];
+        }),
+      ) }),
+    } }),
     dependencies: Object.fromEntries(Object.entries(dependencies).map(([name, version]) => [
       name,
       text(version, `${subject}.dependencies.${name}`),
@@ -183,11 +195,11 @@ export class NodePackageSelectionMissingError extends Error {
 export async function distributionExternalPackageRequirements(
   specifiers: readonly string[],
   distributionRoot: string,
-): Promise<readonly { readonly name: string; readonly version: string; readonly specifier: string }[]> {
+): Promise<readonly { readonly name: string; readonly version: string; readonly specifier: string; readonly env?: Readonly<Record<string, string>> }[]> {
   const root = resolve(distributionRoot);
   const queue = [...new Set(specifiers.filter((name) => name.startsWith("@hypit/")))].sort();
   const visited = new Set<string>();
-  const external = new Map<string, { readonly name: string; readonly version: string; readonly specifier: string }>();
+  const external = new Map<string, { readonly name: string; readonly version: string; readonly specifier: string; readonly env?: Readonly<Record<string, string>> }>();
   while (queue.length > 0) {
     const name = queue.shift()!;
     if (visited.has(name)) continue;
@@ -199,7 +211,15 @@ export async function distributionExternalPackageRequirements(
         continue;
       }
       const specifier = `${dependency}@${version}`;
-      external.set(specifier, { name: dependency, version, specifier });
+      const requested = physical.json.hypit?.dependencyInstallEnv?.[dependency];
+      const previous = external.get(specifier);
+      const env = { ...previous?.env };
+      for (const [key, value] of Object.entries(requested ?? {})) {
+        assert(env[key] === undefined || env[key] === value, `Conflicting installation environment ${key} for ${specifier}`);
+        env[key] = value;
+      }
+      external.set(specifier, { name: dependency, version, specifier,
+        ...(Object.keys(env).length === 0 ? {} : { env }) });
     }
   }
   return [...external.values()].sort((left, right) => left.specifier.localeCompare(right.specifier));

package/packages/package-loader-node/src/location.ts

@@ -2,6 +2,14 @@ import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from "n
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 
+/** Only absence is repairable by installing a package; malformed manifests and I/O errors are not. */
+export class NodePackageNotFoundError extends Error {
+  constructor(name: string) {
+    super(`cannot locate installed package ${name}`);
+    this.name = "NodePackageNotFoundError";
+  }
+}
+
 export type LocatedNodePackage = {
   readonly root: string;
   readonly manifest: {
@@ -88,7 +96,8 @@ export function declaredExternalPackageRoot(root: string, from: string | URL, na
       // An upstream asset a package ships as optional is still selected by one exact version here.
       // `hypit packages install` places it under the machine npm root named by this selection, so
       // reading only the required map makes the documented repair unusable for every optional asset.
-      const version = value.dependencies?.[name] ?? value.optionalDependencies?.[name];
+      // npm lets optionalDependencies override dependencies with the same name.
+      const version = value.optionalDependencies?.[name] ?? value.dependencies?.[name];
       return version === undefined ? undefined : externalPackageInstallRoot(root, name, version);
     }
     const parent = dirname(cursor);
@@ -223,7 +232,7 @@ export function locateNodePackage(nameValue: string, options: LocateNodePackageO
       if (found !== undefined) return found;
     }
   }
-  throw new Error(`cannot locate installed package ${name}`);
+  throw new NodePackageNotFoundError(name);
 }
 
 function packageFile(

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

@@ -2,7 +2,7 @@
 
 Trusted local Provider for the `@hypit/render-hyperframes#render-visual` capability. 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 staging a typed
+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.
@@ -64,12 +64,67 @@ GPU, or `auto` to let the engine decide. Capture uses screenshots and independen
 the CLI's automatic worker and drawElement policies do not override the count. The opaque screenshot
 adapter uses the engine's public session, video injector and page seek protocol plus Chrome CDP.
 It waits for seek completion, dynamic images/fonts and the page compositor before capturing PNGs.
+Image readiness includes CSS class and pseudo-element images, CSS masks and SVG images. A failed
+image decode reports its URL instead of producing a successful frame with missing media. Failed
+declared fonts also fail capture instead of silently leaving fallback glyphs in the output.
 The pinned engine couples its PNG session setup to transparent export, so this adapter initializes
 an opaque session and chooses PNG separately at capture. It does not patch engine methods or files.
 
-The Runtime Adapter also declares one managed browser program. `programs up` invokes the pinned
-HyperFrames CLI's `browser ensure`; its probe resolves and starts that browser and checks
-the FFmpeg/FFprobe toolchain before a Build.
+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
+```
+
+Use the instance name from the Profile. `runtime up` also prepares it and starts the Runtime Worker.
+The Provider's `package.json` declares its recommended Chrome Headless Shell version in
+`hypit.renderBrowser.version`, alongside the engine dependency used to test that release. The
+installer consumes that declaration; it does not have a browser version constant or fetch a
+"latest" channel. `config.browserVersion` explicitly selects another exact four-part version.
+Changing the recommendation belongs to a Provider release and requires real rendering tests; a
+Puppeteer recommendation alone is not a HyperFrames compatibility guarantee.
+
+The default cache is `~/.cache/hyperframes/chrome`; `config.browserCacheDirectory` selects another
+location. Only the selected version is used, regardless of other cached or system browsers.
+Projects sharing this cache use the existing ManagedProgram preparation lock/logs under
+`.hypit-render-program`. Readiness comes from the executable and its reported version, not a receipt.
+Explicit preparation reuses a healthy installation or repairs only the selected managed version.
+A failed download reports failure without selecting another version or browser.
+
+`config.browserDownloadBaseUrl` selects a Chrome for Testing archive mirror for explicit preparation.
+It is an absolute HTTP(S) base URL, without credentials, a query or a fragment. The browser library
+appends the selected version, platform and archive name; the mirror must serve that same layout.
+For example, a base of `https://mirror.example/chrome-for-testing` serves archives beneath
+`<base>/<version>/<platform>/chrome-headless-shell-<platform>.zip`. Choose a source maintained by
+the user or organization; this Provider does not keep a mirror list or choose one by region.
+Omitting the setting uses the browser library's official Chrome for Testing source. A configured
+source replaces it: failed transfers or invalid archives fail preparation without trying the official
+source or another mirror. Normal HTTP redirects supplied by the selected server are handled by the
+download library. Preparation displays the complete archive URL, version and destination before
+download. An npm registry setting does not redirect this binary download.
+
+The download source only determines where missing installation bytes come from. It does not change
+the executable selection, and changing it does not invalidate a healthy cached version. No source
+receipt is stored. To install into an empty location, explicitly choose `browserCacheDirectory`.
+
+`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
+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
+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.
+
+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.
+No browser postinstall allowlist is required. The former `hyperframesCliPath` option is removed.
 
 The same executor is exported for callers with an already compiled document:
 
@@ -101,6 +156,17 @@ flushes that message and disconnects IPC so it can exit normally. The owner awai
 diagnostics before returning. Normal completion does not enumerate or forcibly terminate processes.
 On failure, cleanup may be incomplete: the child reports the error and keeps IPC open while the owner
 discovers and terminates the remaining process tree, before it can become orphaned.
+The capture child also installs synchronous exit cleanup before loading the engine. Early
+`process.exit()`, uncaught exceptions, and catchable `SIGINT`/`SIGTERM` exits stop descendants
+while their owner still exists, even if browser initialization never returned a session.
+Successful resource closure removes this exit handler. No historical browser PID list is retained.
+
+Uncatchable termination (`SIGKILL`, native crashes, or OS termination on Windows) cannot run that
+cleanup. The owner reports the termination and cannot confirm descendant cleanup; it never searches
+by an already-exited root PID. If an orphan keeps the output pipes open, the owner closes its pipe
+ends after five seconds so the failed invocation can settle. Guaranteed cleanup after an OS hard
+kill requires containment supplied by that deployment (for example a process job or container);
+this local Node implementation does not provide that guarantee.
 
 At cancellation the child receives a stop request and has up to five seconds to clean up. A child
 that remains after cancellation or its completion message is forcibly terminated along with its discovered
@@ -118,7 +184,10 @@ more of the shared render budget on a slow initialization or frame.
 An explicit stage-timeout error names the worker and stage/frame, aborts sibling workers and awaits
 cleanup. A completed worker closes its Chrome immediately.
 
-One call stages the HTML and every declared asset once. Typed Surface validation includes a complete
+One call stages the HTML and every declared asset once. Typed Surface inspection reads the completed
+staged file directly, without retaining its chunks, assembling another whole-file buffer, or writing
+a second temporary copy. The caller keeps that file until inspection and capture have settled.
+Typed Surface validation includes a complete
 decoded-frame count, even for a short render interval. The renderer then finds source-frame windows
 needed by that interval, merges overlapping windows, and extracts them one source/window at a time.
 Decoded PNGs are shared by all workers in this call. Each worker initializes its own page, then takes
@@ -134,9 +203,13 @@ do not share staged files or decoded PNGs. Exact compiler sampling markers retai
 fractional playback rates. There is no SVML rewrite, intermediate cut MP4 or repeat normalization.
 Already compiled video documents need the current compiler's frame markers.
 
-Source extraction uses the pinned engine's FFmpeg/FFprobe resolver. `ffmpegPath` selects the final
-H.264 encoder; `ffprobePath` verifies output and typed surfaces. `nodePath` and `hyperframesCliPath`
-serve managed browser installation. The requested frame range travels in the Model's Need.
+`ffmpegPath` selects both source decoding and final H.264 encoding; `ffprobePath` selects source,
+output and typed Surface inspection. Bare commands resolve through PATH. The capture child passes
+these selected executables to the engine's public binary overrides; inherited
+`HYPERFRAMES_FFMPEG_PATH` / `HYPERFRAMES_FFPROBE_PATH` cannot select a different decoding toolchain.
+`nodePath` selects the managed
+browser installer's Node executable. Capture uses the current Node process's executable.
+The requested frame range travels in the Model's Need; browser paths stay in the Provider.
 
 ```ts
 import { createLocalHyperframesProvider } from "@hypit/provider-hyperframes-local";

package/packages/provider-hyperframes-local/package.json

@@ -8,7 +8,18 @@
     ".": "./src/index.ts"
   },
   "hypit": {
-    "activation": "./src/activation.ts"
+    "activation": "./src/activation.ts",
+    "renderBrowser": {
+      "version": "152.0.7928.2"
+    },
+    "dependencyInstallEnv": {
+      "@hyperframes/engine": {
+        "PUPPETEER_SKIP_DOWNLOAD": "true"
+      },
+      "@hyperframes/producer": {
+        "PUPPETEER_SKIP_DOWNLOAD": "true"
+      }
+    }
   },
   "dependencies": {
     "@hyperframes/engine": "0.7.101",
@@ -17,13 +28,12 @@
     "@hypit/hyperframes": "workspace:*",
     "@hypit/media": "workspace:*",
     "@hypit/media-execution": "workspace:*",
-    "@hypit/package-loader-node": "workspace:*",
     "@hypit/protocol": "workspace:*",
     "@hypit/render-hyperframes": "workspace:*",
     "@hypit/runtime": "workspace:*",
     "@hypit/runtime-host-node": "workspace:*",
     "@hypit/runtime-kit": "workspace:*",
-    "hyperframes": "0.7.101",
+    "@puppeteer/browsers": "3.2.2",
     "tsx": "4.21.0"
   },
   "devDependencies": {

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

@@ -1,3 +1,4 @@
+import { resolve } from "node:path";
 import {
   createRuntimeEndpointAdapterFacet,
   runtimeConfigExact,
@@ -11,7 +12,7 @@ import {
 } from "@hypit/runtime-host-node";
 
 import { createLocalHyperframesProvider } from "./provider.js";
-import { defaultHyperframesCliPath } from "./provider.js";
+import { configuredBrowserPath, browserExecutablePath, selectedBrowserVersion } from "./browser.js";
 import type { HyperframesBrowserGpu, HyperframesQuality, HyperframesWorkers } from "./provider.js";
 import { localHyperframesBrowserProgram } from "./program.js";
 
@@ -21,11 +22,10 @@ const localHyperframesRuntimeAdapter = createRuntimeEndpointAdapterFacet({
     if (context.pool === undefined) throw new Error("local HyperFrames Provider Pool is required");
     const config = runtimeConfigObject(context.config, "local HyperFrames");
     runtimeConfigExact(config, [
-      "nodePath", "hyperframesCliPath", "ffprobePath", "ffmpegPath", "workers", "maxWorkers", "quality", "browserGpu",
+      "nodePath", "chromePath", "browserVersion", "browserCacheDirectory", "browserDownloadBaseUrl", "ffprobePath", "ffmpegPath", "workers", "maxWorkers", "quality", "browserGpu",
       "defaultConcurrency", "browserCapacity", "initializationTimeoutMs", "frameTimeoutMs", "processTimeoutMs", "maxProcessOutputBytes", "maxRenderedBytes",
     ], "local HyperFrames");
     runtimeConfigString(config.nodePath, "HyperFrames nodePath");
-    runtimeConfigString(config.hyperframesCliPath, "HyperFrames hyperframesCliPath");
     runtimeConfigString(config.ffprobePath, "HyperFrames ffprobePath");
     const workers = config.workers;
     if (workers !== undefined && workers !== "auto") {
@@ -40,10 +40,21 @@ const localHyperframesRuntimeAdapter = createRuntimeEndpointAdapterFacet({
       throw new Error("HyperFrames browserGpu is invalid");
     }
     const configuredNode = runtimeConfigString(config.nodePath, "HyperFrames nodePath");
-    const configuredCli = runtimeConfigString(config.hyperframesCliPath, "HyperFrames hyperframesCliPath");
+    const configuredChrome = runtimeConfigString(config.chromePath, "HyperFrames chromePath");
+    const browserVersion = runtimeConfigString(config.browserVersion, "HyperFrames browserVersion");
+    const browserDownloadBaseUrl = runtimeConfigString(config.browserDownloadBaseUrl, "HyperFrames browserDownloadBaseUrl");
+    const configuredCache = runtimeConfigString(config.browserCacheDirectory, "HyperFrames browserCacheDirectory");
+    const chromePath = configuredBrowserPath({ ...(configuredChrome === undefined ? {} : {
+      chromePath: resolve(context.dataRoot, configuredChrome),
+    }) });
+    const browser = {
+      ...(browserVersion === undefined ? {} : { browserVersion }),
+      ...(browserDownloadBaseUrl === undefined ? {} : { browserDownloadBaseUrl }),
+      ...(chromePath === undefined ? {} : { chromePath }),
+      ...(configuredCache === undefined ? {} : { browserCacheDirectory: resolve(context.dataRoot, configuredCache) }),
+    };
     const configuredFfprobe = runtimeConfigString(config.ffprobePath, "HyperFrames ffprobePath");
     const nodePath = resolveRuntimeExecutable(context.dataRoot, configuredNode ?? process.execPath);
-    const hyperframesCliPath = () => resolveRuntimeExecutable(context.dataRoot, configuredCli ?? defaultHyperframesCliPath());
     const configuredFfmpeg = runtimeConfigString(config.ffmpegPath, "HyperFrames ffmpegPath");
     const ffmpegPath = resolveRuntimeExecutable(context.dataRoot, configuredFfmpeg ?? "ffmpeg");
     const ffprobePath = resolveRuntimeExecutable(context.dataRoot, configuredFfprobe ?? "ffprobe");
@@ -60,6 +71,7 @@ const localHyperframesRuntimeAdapter = createRuntimeEndpointAdapterFacet({
         instance: context.instance,
         pool: context.pool,
         nodePath,
+        ...browser,
         ffprobePath,
         ffmpegPath,
         ...(workers === undefined ? {} : { workers: workers as HyperframesWorkers }),
@@ -77,11 +89,13 @@ const localHyperframesRuntimeAdapter = createRuntimeEndpointAdapterFacet({
       program: localHyperframesBrowserProgram({
         id: context.instance,
         nodePath,
-        hyperframesCliPath,
+        ...browser,
         ffprobePath,
         ffmpegPath,
       }),
       diagnose: async () => [
+        { severity: "info", code: "HYPERFRAMES_BROWSER_SELECTION", subject: context.instance,
+          message: `${chromePath === undefined ? `Managed Chrome Headless Shell ${selectedBrowserVersion(browser)} (${browserVersion === undefined ? "Provider recommendation" : "Profile version"})` : "Profile browser"}: ${browserExecutablePath(browser)}` },
         ...await diagnoseRuntimeExecutable({ root: context.dataRoot, configured: configuredFfmpeg, fallback: "ffmpeg", subject: "FFmpeg" }),
         ...await diagnoseRuntimeExecutable({
           root: context.dataRoot,

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

@@ -0,0 +1,5 @@
+import { installRenderBrowser } from "./browser.js";
+
+const [cacheDir, version, baseUrl] = process.argv.slice(2);
+if (process.argv.length < 4 || process.argv.length > 5 || !cacheDir || !version) throw new Error("Expected the render browser cache directory, exact version and optional archive base URL");
+await installRenderBrowser(cacheDir, version, baseUrl);