@hypit/hypit 0.1.13 → 0.1.14

package/packages/hyperframes/src/project.ts

@@ -12,9 +12,10 @@ export type HyperframesArtifactReader = (
   artifact: BlobRef,
   signal?: AbortSignal,
 ) => Promise<Uint8Array | AsyncIterable<Uint8Array>>;
+/** Inspect the completed staged file; its lifetime belongs to the staging caller. */
 export type HyperframesSurfaceValidator = (
   surface: CompositableSurfaceRef,
-  bytes: Uint8Array,
+  path: string,
   signal?: AbortSignal,
 ) => Promise<void>;
 
@@ -39,9 +40,7 @@ function extension(mediaType: string): string {
 /**
  * Lay one document out as a directory HyperFrames can render.
  *
- * The same layout serves a local render and a distributed one: the local
- * Provider serves it to the capture engine, and the AWS Provider tars it into a site. If
- * the two laid it out differently, one Need would name two different projects.
+ * A local or hosted Provider can serve the same staged document to its capture engine.
  * Resource names are local to this staged project and carry no content claim.
  */
 export async function stageHyperframesProject(options: {
@@ -63,25 +62,25 @@ export async function stageHyperframesProject(options: {
   await mkdir(artifactDirectory, { recursive: true });
   const paths = new Map<string, string>();
   const surfaces = new Map(document.surfaces.map((surface) => [surface.artifact.resource, surface]));
-  await Promise.allSettled(document.artifacts.map(async (artifact) => {
+  await Promise.allSettled(document.artifacts.map(async (artifact, index) => {
     try {
       signal.throwIfAborted();
-      const name = `${artifact.resource}${extension(artifact.mediaType)}`;
+      // Resource identities are portable protocol values, not filesystem names.
+      const name = `asset-${index}${extension(artifact.mediaType)}`;
       const opened = await read(artifact, signal);
       signal.throwIfAborted();
       const chunks = opened instanceof Uint8Array
         ? (async function* () { yield opened; })()
         : opened;
       const surface = surfaces.get(artifact.resource);
-      const retained: Uint8Array[] = [];
       let size = 0;
-      const target = await open(join(artifactDirectory, name), "w");
+      const path = join(artifactDirectory, name);
+      const target = await open(path, "w");
       try {
         for await (const chunk of chunks) {
           signal.throwIfAborted();
-          await target.write(chunk);
+          await target.writeFile(chunk);
           size += chunk.byteLength;
-          if (surface !== undefined) retained.push(Uint8Array.from(chunk));
         }
       } finally {
         await target.close();
@@ -89,17 +88,9 @@ export async function stageHyperframesProject(options: {
       if (size !== artifact.size) {
         throw new Error(`HyperFrames Artifact ${artifact.resource} size differs`);
       }
-      const bytes = surface === undefined ? undefined : (() => {
-        const value = new Uint8Array(size);
-        let offset = 0;
-        for (const chunk of retained) {
-          value.set(chunk, offset);
-          offset += chunk.byteLength;
-        }
-        return value;
-      })();
       if (surface !== undefined) {
-        await options.validateSurface!(structuredClone(surface), bytes!.slice(), signal);
+        // The validator borrows the completed staged file for this call only.
+        await options.validateSurface!(structuredClone(surface), path, signal);
       }
       paths.set(artifact.resource, `./artifacts/${name}`);
     } catch (error) {

package/packages/media-execution/README.md

@@ -26,6 +26,13 @@ deployments can reuse the same functions to preserve stream selection, timing, c
 This is not an author package, Provider, queue or Core extension. It performs no endpoint selection,
 credential lookup or SVML parsing.
 
+`verifyCompositableSurfaceFile({ surface, path, ... })` inspects a file already staged by an execution
+owner. That owner must keep it unchanged until the call settles, including cancellation; inspection
+neither copies nor removes it. `verifyCompositableSurfaceBytes({ surface, bytes, ... })` remains a
+convenience wrapper for callers that have bytes, creates its own temporary file, and removes that
+file only after probing has settled. Both use the same decoded Surface checks and return no extra
+result facts. Filesystem paths belong to this Node execution boundary, not to Surface or Blob refs.
+
 Audio gain envelopes and audible subranges are evaluated per sample after tempo/looping and Clip
 fades, before the requested range is cropped. Original source and envelope progress therefore survive
 local silence and range rendering. This is generic AudioProgramPlan execution, independent of author

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

@@ -33,6 +33,7 @@ import {
   } from "@hypit/protocol";
 import type { BlobRef, CanonicalValue, StoredValue } from "@hypit/protocol";
 
+import { mediaProcessEnv } from "./process-env.js";
 import { parseMediaInspection } from "./probe.js";
 import {
   compositeAnimatedWebpFrame,
@@ -98,10 +99,7 @@ async function runProcess(args: {
       shell: false,
       windowsHide: true,
       stdio: ["ignore", "pipe", "pipe"],
-      env: {
-        PATH: process.env.PATH ?? "",
-        ...(args.sharedLibraryPath === undefined ? {} : { LD_LIBRARY_PATH: args.sharedLibraryPath }),
-      },
+      env: mediaProcessEnv(args.sharedLibraryPath === undefined ? undefined : { LD_LIBRARY_PATH: args.sharedLibraryPath }),
     });
     const stdout: Buffer[] = [];
     let stdoutBytes = 0;
@@ -678,8 +676,10 @@ export async function executeNormalizeMedia(
         "scale=trunc(iw*max(sar\\,1)/2)*2:trunc(ih*max(1/sar\\,1)/2)*2",
         "setsar=1",
       ].join(",");
+      // FFmpeg enables autorotation by default. Its positive boolean option changed
+      // syntax across releases; no override is needed to materialize source rotation.
       const visualInput = animation === undefined
-        ? [...encoding.inputArgs, "-autorotate", "-i", input, "-map", `0:${plan.video.index}`]
+        ? [...encoding.inputArgs, "-i", input, "-map", `0:${plan.video.index}`]
         : ["-f", "concat", "-safe", "0", "-i", await animatedWebpConcat(env, animation, work), "-map", "0:v:0"];
       // The execution format must retain the source's alpha while materializing
       // the program clock. Both encodings publish the same SynchronizedMedia type.

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

@@ -10,7 +10,7 @@ export {
   executeTransformMedia,
 } from "./execute.js";
 export { parseMediaInspection } from "./probe.js";
-export { verifyCompositableSurfaceBytes } from "./surface.js";
+export { verifyCompositableSurfaceBytes, verifyCompositableSurfaceFile } from "./surface.js";
 export { probeMediaToolchain } from "./toolchain.js";
 export type { MediaToolchainState } from "./toolchain.js";
 export type * from "./execute.js";

package/packages/media-execution/src/process-env.ts

@@ -0,0 +1,20 @@
+const windowsProcessCreation = ["PATHEXT", "SYSTEMROOT", "WINDIR", "ComSpec"] as const;
+
+/**
+ * ffmpeg and ffprobe are started as PATH executables. The Host environment is
+ * not forwarded, so credential values stay out of those processes. Windows still
+ * needs the process-creation variables CreateProcess uses to resolve `.exe`.
+ */
+export function mediaProcessEnv(
+  extra?: Readonly<Record<string, string>>,
+): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = { PATH: process.env.PATH ?? "" };
+  if (process.platform === "win32") {
+    for (const name of windowsProcessCreation) {
+      const value = process.env[name];
+      if (value !== undefined && value.length > 0) env[name] = value;
+    }
+  }
+  if (extra !== undefined) Object.assign(env, extra);
+  return env;
+}

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/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": {