@hypit/hypit 0.1.12 → 0.1.14

package/packages/model-kit/src/index.ts

@@ -13,13 +13,13 @@ import type { HostFacet } from "@hypit/host";
 import {
   bindGenerationMedia,
   bindGenerationText,
-  finalizeGenerationRequestDraft,
   generationModuleRef,
   generationProducers,
   generationTypes,
   mediaBindingSchemaFromPort,
   requestDraftSchemaFromPorts,
   requestSchemaFromPorts,
+  sealGenerationPortRequest,
   verifyGenerationMediaBinding,
   verifyRequestDraftAgainstPorts,
   verifyRequestAgainstPorts,
@@ -28,6 +28,7 @@ import type {
   GenerationMediaBinding,
   GenerationMediaPort,
   GenerationPortTable,
+  GenerationRequest,
   GenerationRequestDraft,
 } from "@hypit/generation";
 import { textDependency, textTypes } from "@hypit/text";
@@ -76,6 +77,10 @@ export type ExactModelEndpointSpec = {
   readonly requestTypeName: string;
   readonly producerName: string;
   readonly ports: GenerationPortTable;
+  /** Additional complete-request rules, after port and supplied-input validation. */
+  readonly validateRequest?: (request: GenerationRequest) => void;
+  /** Pure, synchronous checks of supplied values, in drafts and complete requests; throw to reject. */
+  readonly validateInputs?: (inputs: GenerationRequestDraft) => void;
 };
 
 export type ExactModelEndpoint = {
@@ -89,6 +94,9 @@ export type ExactModelEndpoint = {
   readonly mediaBindings: Readonly<Record<string, ExactModelMediaBindingEndpoint>>;
   readonly textBindings: Readonly<Record<string, ExactModelTextBindingEndpoint>>;
   readonly ports: GenerationPortTable;
+  readonly validateRequest: (request: unknown) => void;
+  readonly validateDraft: (draft: unknown) => void;
+  readonly sealRequest: (ports: GenerationRequest["ports"]) => GenerationRequest;
   readonly fragment: ReturnType<typeof sealGraphFragment>;
 };
 
@@ -267,7 +275,7 @@ export function plannedExactModelRequest(
 
   const knownNeed = state.needs.find((need) => need.id === binding.id);
   if (knownNeed !== undefined) {
-    verifyRequestAgainstPorts(endpoint.ports, knownNeed.constraints);
+    endpoint.validateRequest(knownNeed.constraints);
     return {
       model: endpoint.ports.model,
       ports: structuredClone((knownNeed.constraints as unknown as GenerationRequestDraft).ports),
@@ -281,6 +289,12 @@ export function plannedExactModelRequest(
     Object.values(step.outputs).map((record) => [record, step] as const)));
   const requestRecord = generationStep.inputs.request;
   if (requestRecord === undefined) return undefined;
+  const knownRequest = records.get(requestRecord);
+  if (knownRequest !== undefined) {
+    const request = inlineValue<GenerationRequest>(knownRequest.value, `${endpoint.ports.model} request`);
+    endpoint.validateRequest(request);
+    return { model: endpoint.ports.model, ports: structuredClone(request.ports), pendingMedia: [], complete: false };
+  }
   const finalize = producedBy.get(requestRecord);
   if (finalize === undefined || !sameReference(finalize.producer, endpoint.finalizeProducer)) return undefined;
   const finalDraft = finalize.inputs.draft;
@@ -295,7 +309,7 @@ export function plannedExactModelRequest(
       const record = records.get(recordId);
       if (record !== undefined) {
         const draft = inlineValue<GenerationRequestDraft>(record.value, `${endpoint.ports.model} request draft`);
-        verifyRequestDraftAgainstPorts(endpoint.ports, draft);
+        endpoint.validateDraft(draft);
         return draft;
       }
       const step = producedBy.get(recordId);
@@ -354,6 +368,8 @@ export function plannedExactModelRequest(
   };
 
   const draft = rebuildDraft(finalDraft);
+  endpoint.validateDraft(draft);
+  if (pendingMedia.length === 0) endpoint.validateRequest(draft);
   return {
     model: endpoint.ports.model,
     ports: structuredClone(draft.ports),
@@ -502,6 +518,15 @@ export function defineExactModelModule<const Key extends string>(
   };
 
   const endpoints = Object.fromEntries(endpointData.map((item): [Key, ExactModelEndpoint] => {
+    const validateRequest = (request: unknown): void => {
+      verifyRequestAgainstPorts(item.spec.ports, request);
+      item.spec.validateInputs?.(request);
+      item.spec.validateRequest?.(request);
+    };
+    const validateDraft = (draft: unknown): void => {
+      verifyRequestDraftAgainstPorts(item.spec.ports, draft);
+      item.spec.validateInputs?.(draft);
+    };
     const fragment = sealGraphFragment({
       inputs: [{ name: "request", type: item.requestType }],
       operations: [{
@@ -527,6 +552,14 @@ export function defineExactModelModule<const Key extends string>(
       mediaBindings: item.mediaBindings,
       textBindings: item.textBindings,
       ports: item.spec.ports,
+      validateRequest,
+      validateDraft,
+      sealRequest(ports) {
+        const request = sealGenerationPortRequest(item.spec.ports, ports);
+        item.spec.validateInputs?.(request);
+        item.spec.validateRequest?.(request);
+        return request;
+      },
       fragment,
     } satisfies ExactModelEndpoint];
   }));
@@ -540,12 +573,12 @@ export function defineExactModelModule<const Key extends string>(
       validators: endpointData.flatMap((item) => [{
         type: item.requestType,
         handler({ value }) {
-          verifyRequestAgainstPorts(item.spec.ports, inlineRequest(value, item.spec.key));
+          endpoints[item.spec.key]!.validateRequest(inlineRequest(value, item.spec.key));
         },
       }, {
         type: item.draftType,
         handler({ value }) {
-          verifyRequestDraftAgainstPorts(item.spec.ports, inlineRequest(value, `${item.spec.key} draft`));
+          endpoints[item.spec.key]!.validateDraft(inlineRequest(value, `${item.spec.key} draft`));
         },
       }]),
       producers: endpointData.flatMap((item) => [
@@ -555,7 +588,7 @@ export function defineExactModelModule<const Key extends string>(
             const requestRecord = inputs.request;
             assert(requestRecord !== undefined, `${item.spec.key} request input is missing`);
             const request = inlineRequest(requestRecord.value, item.spec.key);
-            verifyRequestAgainstPorts(item.spec.ports, request);
+            endpoints[item.spec.key]!.validateRequest(request);
             return { outputs: {}, needs: { generation: request } };
           },
         },
@@ -570,11 +603,13 @@ export function defineExactModelModule<const Key extends string>(
             verifyGenerationMediaBinding(port, value);
             const artifact = inputs.artifact!.value;
             assert(artifact.kind === "blob", `${binding.port} artifact must be a Blob`);
+            const bound = bindGenerationMedia(item.spec.ports, draft, binding.port, value, artifact);
+            endpoints[item.spec.key]!.validateDraft(bound);
             return {
               outputs: {
                 draft: {
                   kind: "inline" as const,
-                  value: canonicalize(bindGenerationMedia(item.spec.ports, draft, binding.port, value, artifact)),
+                  value: canonicalize(bound),
                 },
               },
               needs: {},
@@ -586,11 +621,13 @@ export function defineExactModelModule<const Key extends string>(
           handler: ({ inputs }: ProducerHandlerContext) => {
             const draft = inlineValue<GenerationRequestDraft>(inputs.draft!.value, `${item.spec.key} draft`);
             const text = inlineValue<Text>(inputs.text!.value, `${binding.port} Text`);
+            const bound = bindGenerationText(item.spec.ports, draft, binding.port, text);
+            endpoints[item.spec.key]!.validateDraft(bound);
             return {
               outputs: {
                 draft: {
                   kind: "inline" as const,
-                  value: canonicalize(bindGenerationText(item.spec.ports, draft, binding.port, text)),
+                  value: canonicalize(bound),
                 },
               },
               needs: {},
@@ -599,18 +636,20 @@ export function defineExactModelModule<const Key extends string>(
         })),
         {
           producer: item.finalizeProducer,
-          handler: ({ inputs }) => ({
-            outputs: {
-              request: {
-                kind: "inline" as const,
-                value: canonicalize(finalizeGenerationRequestDraft(
-                  item.spec.ports,
-                  inlineValue<GenerationRequestDraft>(inputs.draft!.value, `${item.spec.key} draft`),
-                )),
+          handler: ({ inputs }) => {
+            const endpoint = endpoints[item.spec.key]!;
+            const draft = inlineValue<GenerationRequestDraft>(inputs.draft!.value, `${item.spec.key} draft`);
+            endpoint.validateDraft(draft);
+            return {
+              outputs: {
+                request: {
+                  kind: "inline" as const,
+                  value: canonicalize(endpoint.sealRequest(draft.ports)),
+                },
               },
-            },
-            needs: {},
-          }),
+              needs: {},
+            };
+          },
         },
       ]),
       plannedNeeds: Object.values(endpoints).map((endpoint) => exactModelPlannedNeedFacet(endpoint)),

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/project-context-node/README.md

@@ -6,6 +6,8 @@ It does not load Providers, install programs, inspect credentials or select serv
 
 1. `resolveProjectRoot({ workspaceRoot?, cwd? })` uses the explicit Workspace, otherwise the nearest
    `package.json` above cwd, otherwise cwd itself. Source and Run filenames do not choose the project.
+   After selecting the existing directory, it returns its real filesystem path so project and Source
+   paths use the same representation. Symlinks do not redirect the preceding parent-project search.
 2. `findRuntimeProfile(projectRoot)` reads only that project's `.hypit/runtime` file and resolves its
    path relative to the project. An entrypoint's explicit `--runtime` overrides this read for that invocation.
 3. The selected Runtime implementation interprets the Profile, including `dataRoot`, Credentials,

package/packages/project-context-node/src/project-context.ts

@@ -1,4 +1,4 @@
-import { stat } from "node:fs/promises";
+import { realpath, stat } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 
 async function nearestProjectPackageRoot(start: string): Promise<string | undefined> {
@@ -28,8 +28,10 @@ export async function resolveProjectRoot(options: {
   readonly cwd?: string;
 } = {}): Promise<string> {
   const start = resolve(options.workspaceRoot ?? options.cwd ?? process.cwd());
-  if (options.workspaceRoot !== undefined) return start;
-  return await nearestProjectPackageRoot(start) ?? start;
+  const selected = options.workspaceRoot !== undefined ? start : await nearestProjectPackageRoot(start) ?? start;
+  // Select through the caller's directory first; following a link before discovery
+  // could choose a different parent project. Source readers also return real paths.
+  return await realpath(selected);
 }
 
 /** Project package discovery cannot escape an already resolved project. */

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:
 
@@ -96,11 +151,31 @@ execution earlier. ResourceStore I/O and Surface probes receive the cancellation
 ResourceStore must implement the port's cancellation behavior, including streaming reads and writes.
 
 Browser launch, source extraction, capture and encoding run in one disposable child process per
-render. At cancellation it receives a stop request and has up to five seconds to clean up. The owner
-then terminates any remaining process tree, including Chrome's separate process groups, and awaits
-the child exit before removing temporary files and returning failure. This also covers engine calls
-that do not accept a signal. The deadline initiates shutdown; the call may spend additional time
-closing resources. Completed Outputs in the Build remain available for a new Run and Build.
+render. After successful capture closes its resources, the child sends its completion message,
+flushes that message and disconnects IPC so it can exit normally. The owner awaits exit and drains
+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
+process tree, including Chrome's separate process groups. Cleanup problems are reported through the
+existing diagnostic callback; they do not discard a render already reported as completed. If process
+enumeration fails, the owner still terminates the direct child but cannot confirm descendant cleanup.
+This also covers engine calls that do not accept a signal. The deadline initiates shutdown; the call
+may spend additional time closing resources. Completed Outputs in the Build remain available for a
+new Run and Build.
 
 Deployments may additionally set `initializationTimeoutMs` or `frameTimeoutMs` when they have a
 measured stage deadline. Initialization here means initializing an already created browser session;
@@ -109,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
@@ -125,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);