@hypit/hypit 0.0.1 → 0.1.0

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

@@ -0,0 +1,107 @@
+import {
+  createRuntimeEndpointAdapterFacet,
+  runtimeConfigExact,
+  runtimeConfigObject,
+  runtimeConfigPositiveInteger,
+  runtimeConfigString,
+} from "@hypit/runtime-kit";
+import {
+  diagnoseRuntimeExecutable,
+  resolveRuntimeExecutable,
+} from "@hypit/runtime-host-node";
+
+import { createLocalHyperframesProvider } from "./provider.js";
+import { defaultHyperframesCliPath } from "./provider.js";
+import type { HyperframesBrowserGpu, HyperframesQuality, HyperframesWorkers } from "./provider.js";
+import { localHyperframesBrowserProgram } from "./program.js";
+
+const localHyperframesRuntimeAdapter = createRuntimeEndpointAdapterFacet({
+  use: "@hypit/provider-hyperframes-local",
+  activate(context) {
+    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", "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") {
+      runtimeConfigPositiveInteger(workers, "HyperFrames workers");
+    }
+    const quality = runtimeConfigString(config.quality, "HyperFrames quality");
+    if (quality !== undefined && quality !== "draft" && quality !== "standard" && quality !== "high") {
+      throw new Error("HyperFrames quality is invalid");
+    }
+    const browserGpu = runtimeConfigString(config.browserGpu, "HyperFrames browserGpu");
+    if (browserGpu !== undefined && browserGpu !== "auto" && browserGpu !== "software" && browserGpu !== "hardware") {
+      throw new Error("HyperFrames browserGpu is invalid");
+    }
+    const configuredNode = runtimeConfigString(config.nodePath, "HyperFrames nodePath");
+    const configuredCli = runtimeConfigString(config.hyperframesCliPath, "HyperFrames hyperframesCliPath");
+    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");
+    const defaultConcurrency = runtimeConfigPositiveInteger(config.defaultConcurrency, "HyperFrames defaultConcurrency");
+    const browserCapacity = runtimeConfigPositiveInteger(config.browserCapacity, "HyperFrames browserCapacity");
+    const initializationTimeoutMs = runtimeConfigPositiveInteger(config.initializationTimeoutMs, "HyperFrames initializationTimeoutMs");
+    const frameTimeoutMs = runtimeConfigPositiveInteger(config.frameTimeoutMs, "HyperFrames frameTimeoutMs");
+    const processTimeoutMs = runtimeConfigPositiveInteger(config.processTimeoutMs, "HyperFrames processTimeoutMs");
+    const maxProcessOutputBytes = runtimeConfigPositiveInteger(config.maxProcessOutputBytes, "HyperFrames maxProcessOutputBytes");
+    const maxRenderedBytes = runtimeConfigPositiveInteger(config.maxRenderedBytes, "HyperFrames maxRenderedBytes");
+    return {
+      endpoint: createLocalHyperframesProvider({
+        instance: context.instance,
+        pool: context.pool,
+        nodePath,
+        hyperframesCliPath,
+        ffprobePath,
+        ffmpegPath,
+        ...(workers === undefined ? {} : { workers: workers as HyperframesWorkers }),
+        ...(quality === undefined ? {} : { quality: quality as HyperframesQuality }),
+        ...(browserGpu === undefined ? {} : { browserGpu: browserGpu as HyperframesBrowserGpu }),
+        ...(defaultConcurrency === undefined ? {} : { defaultConcurrency }),
+        ...(browserCapacity === undefined ? {} : { browserCapacity }),
+        ...(initializationTimeoutMs === undefined ? {} : { initializationTimeoutMs }),
+        ...(frameTimeoutMs === undefined ? {} : { frameTimeoutMs }),
+        ...(processTimeoutMs === undefined ? {} : { processTimeoutMs }),
+        ...(maxProcessOutputBytes === undefined ? {} : { maxProcessOutputBytes }),
+        ...(maxRenderedBytes === undefined ? {} : { maxRenderedBytes }),
+      }),
+      program: localHyperframesBrowserProgram({
+        id: context.instance,
+        nodePath,
+        hyperframesCliPath,
+        ffprobePath,
+        ffmpegPath,
+      }),
+      diagnose: async () => [
+        ...await diagnoseRuntimeExecutable({ root: context.dataRoot, configured: configuredFfmpeg, fallback: "ffmpeg", subject: "FFmpeg" }),
+        ...await diagnoseRuntimeExecutable({
+          root: context.dataRoot,
+          configured: configuredNode,
+          fallback: process.execPath,
+          subject: "Node.js",
+        }),
+        ...await diagnoseRuntimeExecutable({
+          root: context.dataRoot,
+          configured: configuredFfprobe,
+          fallback: "ffprobe",
+          subject: "FFprobe",
+        }),
+      ],
+    };
+  },
+});
+
+export const hypitPackage = {
+  format: "hypit.node-package@1" as const,
+  hostFacets: [localHyperframesRuntimeAdapter],
+};
+
+export default hypitPackage;

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

@@ -0,0 +1,110 @@
+import { execFile, spawn } from "node:child_process";
+import { promisify } from "node:util";
+import { fileURLToPath } from "node:url";
+import { setTimeout as delay } from "node:timers/promises";
+import type { CaptureInput } from "./capture.js";
+import type { HyperframesRenderProgress } from "./render.js";
+
+const exec = promisify(execFile);
+const cleanupMs = 5_000;
+
+/** Chrome starts its own process group, so stopping only the Node child is insufficient. */
+async function killRenderTree(pid: number): Promise<void> {
+  if (process.platform === "win32") {
+    await exec("taskkill", ["/PID", String(pid), "/T", "/F"], { windowsHide: true, timeout: cleanupMs });
+    return;
+  }
+  const { stdout } = await exec("ps", ["-A", "-o", "pid=,ppid="], { timeout: cleanupMs });
+  const rows = stdout.trim().split("\n").map((line) => line.trim().split(/\s+/u).map(Number));
+  const descendants = [pid];
+  for (let i = 0; i < descendants.length; i++) {
+    for (const [child, parent] of rows) if (parent === descendants[i] && child !== undefined) descendants.push(child);
+  }
+  for (const child of descendants.reverse()) {
+    for (const target of [-child, child]) {
+      try { process.kill(target, "SIGKILL"); }
+      catch (error) { if ((error as NodeJS.ErrnoException).code !== "ESRCH") throw error; }
+    }
+    // Signal delivery is asynchronous. Wait for execution to stop while the
+    // parent is still alive to reap its child; zombies no longer hold resources.
+    const deadline = Date.now() + cleanupMs;
+    while (true) {
+      const state = await exec("ps", ["-p", String(child), "-o", "stat="], { timeout: cleanupMs })
+        .then(({ stdout }) => stdout.trim(), (error) => {
+          if (error.code === 1 && !error.stdout?.trim()) return "";
+          throw error;
+        });
+      if (state === "" || state.startsWith("Z")) break;
+      if (Date.now() >= deadline) throw new Error(`Render process ${child} did not stop after SIGKILL`);
+      await delay(20);
+    }
+  }
+}
+
+/** One disposable execution, with no persisted state or resubmission behavior. */
+export async function runCaptureProcess(
+  input: CaptureInput,
+  signal: AbortSignal,
+  onProgress: (event: HyperframesRenderProgress) => void,
+  entry = new URL("./capture-worker.ts", import.meta.url),
+): Promise<void> {
+  signal.throwIfAborted();
+  await new Promise<void>((resolve, reject) => {
+    const child = spawn(process.execPath, ["--import", import.meta.resolve("tsx"), fileURLToPath(entry)], {
+      detached: process.platform !== "win32", windowsHide: true,
+      stdio: ["ignore", "pipe", "pipe", "ipc"],
+    });
+    let failure: Error | undefined;
+    let completed = false;
+    let outputBytes = 0;
+    let stderr = "";
+    let grace: ReturnType<typeof setTimeout> | undefined;
+    let killing: Promise<void> | undefined;
+    const kill = () => {
+      if (grace !== undefined) clearTimeout(grace);
+      killing ??= (child.pid === undefined ? Promise.resolve() : killRenderTree(child.pid)).catch((error) => {
+        failure = new Error(`${failure?.message ?? "Render cleanup failed"}; ${String(error)}`);
+        child.kill("SIGKILL");
+      });
+      return killing;
+    };
+    const stop = (error: Error) => {
+      failure ??= error;
+      if (child.connected) child.send({ type: "abort", error: failure.message }, () => {});
+      grace ??= setTimeout(() => { void kill(); }, cleanupMs);
+    };
+    const abort = () => stop(signal.reason instanceof Error ? signal.reason : new Error(String(signal.reason)));
+    signal.addEventListener("abort", abort, { once: true });
+    const log = (chunk: Buffer, error: boolean) => {
+      outputBytes += chunk.byteLength;
+      if (error) stderr = `${stderr}${chunk.toString()}`.slice(-32_000);
+      if (outputBytes > input.config.maxProcessOutputBytes) stop(new Error("HyperFrames process output exceeded the configured limit"));
+    };
+    child.stdout?.on("data", (chunk: Buffer) => log(chunk, false));
+    child.stderr?.on("data", (chunk: Buffer) => log(chunk, true));
+    child.on("message", (value: { type: string; event?: HyperframesRenderProgress; error?: string }) => {
+      if (value.type === "progress" && value.event !== undefined) {
+        try { onProgress(value.event); } catch (error) { stop(error instanceof Error ? error : new Error(String(error))); }
+      } else if (value.type === "stopping") {
+        stop(new Error(value.error));
+      } else if (value.type === "completed" || value.type === "failed") {
+        completed = value.type === "completed";
+        if (!completed) failure ??= new Error(value.error);
+        // The worker has finished cleanup. Terminate any leftover descendants before releasing capacity.
+        void kill();
+      }
+    });
+    child.on("error", (error) => { failure ??= error; void kill(); });
+    child.on("close", () => {
+      if (grace !== undefined) clearTimeout(grace);
+      signal.removeEventListener("abort", abort);
+      void (killing ?? Promise.resolve()).then(() => {
+        if (failure !== undefined) reject(failure);
+        else if (!completed) reject(new Error(`HyperFrames process exited before completion: ${stderr}`));
+        else resolve();
+      });
+    });
+    child.send({ type: "start", input }, (error) => { if (error) { failure ??= error; void kill(); } });
+    if (signal.aborted) abort();
+  });
+}

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

@@ -0,0 +1,17 @@
+import { captureStagedVisual } from "./capture.js";
+import type { CaptureInput } from "./capture.js";
+
+const controller = new AbortController();
+const message = (error: unknown) => error instanceof Error ? error.message : String(error);
+controller.signal.addEventListener("abort", () => {
+  process.send?.({ type: "stopping", error: message(controller.signal.reason) });
+}, { once: true });
+process.on("message", (value: { type: "start"; input: CaptureInput } | { type: "abort"; error: string }) => {
+  if (value.type === "abort") { controller.abort(new Error(value.error)); return; }
+  void captureStagedVisual(value.input, controller,
+    (event) => process.send?.({ type: "progress", event })).then(
+    () => process.send?.({ type: "completed" }),
+    (error) => process.send?.({ type: "failed", error: message(error) }),
+  );
+});
+process.on("disconnect", () => controller.abort(new Error("Render owner disconnected")));

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

@@ -0,0 +1,184 @@
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { join, relative, resolve, sep } from "node:path";
+import type { HyperframesDocument } from "@hypit/hyperframes";
+import type { MediaFrameRange } from "@hypit/media";
+import type { HyperframesRenderProgress, resolveExecutionOptions } from "./render.js";
+import { assert, runProcess } from "./process.js";
+import { verifyOutput } from "./output.js";
+import { distributeFrameRange, sourceFrameAt, sourceWindows, videoSlots } from "./sampling.js";
+
+export type CaptureInput = {
+  readonly document: HyperframesDocument;
+  readonly range: MediaFrameRange;
+  readonly config: ReturnType<typeof resolveExecutionOptions>;
+  readonly directory: string;
+  readonly engineModule: string;
+  readonly producerModule: string;
+};
+
+/** All browser and codec work belongs to this render's disposable process. */
+export async function captureStagedVisual(input: CaptureInput, controller: AbortController,
+  onProgress: (event: HyperframesRenderProgress) => void): Promise<string> {
+  const { document, range, config, directory: work } = input;
+  const signal = controller.signal;
+  const frameCount = range.endFrameExclusive - range.startFrame;
+  const tasks = distributeFrameRange(range, config.workers);
+  const fps = { num: document.frameRate.numerator, den: document.frameRate.denominator };
+  const started = performance.now();
+  const elapsedMs = () => Math.round(performance.now() - started);
+  const engine = await import(input.engineModule) as typeof import("@hyperframes/engine");
+  const { createFileServer } = await import(input.producerModule) as typeof import("@hyperframes/producer");
+  type Session = Awaited<ReturnType<typeof engine.createCaptureSession>>;
+  const sessions = new Set<Session>();
+  const closing = new Map<Session, Promise<void>>();
+  const close = (session: Session): Promise<void> => {
+    let promise = closing.get(session);
+    if (promise === undefined) {
+      promise = engine.closeCaptureSession(session).finally(() => { sessions.delete(session); });
+      closing.set(session, promise);
+    }
+    return promise;
+  };
+  const stage = async <T>(subject: string, timeoutMs: number | undefined, run: () => Promise<T>): Promise<T> => {
+    signal.throwIfAborted();
+    const timeout = timeoutMs === undefined
+      ? undefined
+      : setTimeout(() => controller.abort(new Error(`HyperFrames ${subject} timed out after ${timeoutMs} ms`)), timeoutMs);
+    let onAbort: () => void = () => {};
+    const stopped = new Promise<never>((_, reject) => {
+      onAbort = () => reject(signal.reason);
+      signal.addEventListener("abort", onAbort, { once: true });
+    });
+    try { return await Promise.race([run(), stopped]); }
+    finally {
+      if (timeout !== undefined) clearTimeout(timeout);
+      signal.removeEventListener("abort", onAbort);
+    }
+  };
+  let server: Awaited<ReturnType<typeof createFileServer>> | undefined;
+  // Closing pages interrupts an in-flight capture as well as the next loop iteration.
+  const abort = () => { for (const session of sessions) void close(session).catch(() => {}); };
+  signal.addEventListener("abort", abort, { once: true });
+  try {
+    signal.throwIfAborted();
+    const slots = videoSlots(await readFile(join(work, "index.html"), "utf8"));
+    const sources = new Map<string, { frames: Map<number, string>; width: number; height: number }>();
+    let sourceFrames = 0;
+    // One source at a time bounds decoder pressure independently of browser concurrency.
+    for (const source of sourceWindows(slots, range)) {
+      const path = resolve(work, source.src);
+      assert(path.startsWith(`${work}${sep}`), "HyperFrames source is outside the staged project");
+      const frames = new Map<number, string>();
+      let width = 0, height = 0;
+      for (const window of source.windows) {
+        signal.throwIfAborted();
+        const count = window.endFrameExclusive - window.startFrame;
+        const extracted = await engine.extractVideoFramesRange(path, `source-${sources.size}-${window.startFrame}`,
+          window.startFrame * source.fps.den / source.fps.num, count * source.fps.den / source.fps.num,
+          { fps: source.fps, outputDir: join(work, "decoded"), format: "png", ...(count === 1 ? { finalFrameOnly: true } : {}) },
+          signal, { ffmpegProcessTimeout: config.processTimeoutMs });
+        assert(extracted.totalFrames === count, `HyperFrames expected ${count} source frames, decoded ${extracted.totalFrames}`);
+        for (let index = 0; index < count; index++) {
+          const framePath = extracted.framePaths.get(index);
+          assert(framePath !== undefined, "HyperFrames extraction omitted a requested source frame");
+          frames.set(window.startFrame + index, framePath);
+        }
+        width = extracted.metadata.width;
+        height = extracted.metadata.height;
+        sourceFrames += count;
+      }
+      sources.set(source.src, { frames, width, height });
+    }
+    class SelectedFrameLookup extends engine.FrameLookupTable {
+      override getActiveFramePayloads(time: number) {
+        const frame = Math.round(time * fps.num / fps.den);
+        const payloads = new Map<string, { framePath: string; frameIndex: number }>();
+        for (const slot of slots) {
+          if (frame < slot.startFrame || frame >= slot.endFrameExclusive) continue;
+          const frameIndex = sourceFrameAt(slot, frame);
+          const framePath = sources.get(slot.src)?.frames.get(frameIndex);
+          // Browser initialization may seek outside the requested interval.
+          if (frame < range.startFrame || frame >= range.endFrameExclusive) continue;
+          assert(framePath !== undefined, `HyperFrames has no decoded frame ${frameIndex} for ${slot.id}`);
+          payloads.set(slot.id, { framePath, frameIndex });
+        }
+        return payloads;
+      }
+    }
+    server = await createFileServer({ projectDir: work, port: 0, fps });
+    const serverUrl = server.url;
+    const outputFrames = join(work, "frames");
+    await mkdir(outputFrames);
+    onProgress?.({ phase: "prepared", workers: tasks.length, sourceFrames, elapsedMs: elapsedMs() });
+    const results = await Promise.allSettled(tasks.map(async (task, worker) => {
+      let session: Session | undefined;
+      try {
+        signal.throwIfAborted();
+        const directory = join(work, `worker-${worker}`);
+        await mkdir(directory);
+        const injector = engine.createVideoFrameInjector(slots.length === 0 ? null : new SelectedFrameLookup(), {
+          frameSrcResolver: (path) => new URL(relative(work, path).split(sep).map(encodeURIComponent).join("/"), `${serverUrl}/`).href,
+        });
+        session = await engine.createCaptureSession(serverUrl, directory, {
+          ...document.canvas, fps, format: "png",
+          compositionDurationSeconds: document.frameCount * fps.den / fps.num,
+          skipReadinessVideoIds: slots.map((slot) => slot.id),
+          videoMetadataHints: slots.flatMap((slot) => {
+            const source = sources.get(slot.src);
+            return source === undefined ? [] : [{ id: slot.id, width: source.width, height: source.height }];
+          }),
+        }, injector, { browserGpuMode: config.browserGpu, enableBrowserPool: false, forceScreenshot: true, useDrawElement: false });
+        sessions.add(session);
+        signal.throwIfAborted();
+        const activeSession = session;
+        const browserPid = session.browser.process()?.pid;
+        onProgress?.({ phase: "worker-initializing", worker, range: task, browserPid, elapsedMs: elapsedMs() });
+        await stage(`worker ${worker} initialization`, config.initializationTimeoutMs, () => engine.initializeSession(activeSession));
+        // HyperFrames' PNG capture clears the page/composition backgrounds for
+        // standalone transparent exports. Here PNGs are intermediate frames of
+        // a Film, whose authored Canvas background still belongs in the image.
+        await activeSession.page.evaluate(() => {
+          globalThis.document.getElementById("__hf_transparent_bg__")?.remove();
+        });
+        onProgress?.({ phase: "worker-start", worker, range: task, browserPid, elapsedMs: elapsedMs() });
+        for (let frame = task.startFrame; frame < task.endFrameExclusive; frame++) {
+          signal.throwIfAborted();
+          const captured = await stage(`worker ${worker} frame ${frame}`, config.frameTimeoutMs, async () => {
+            const capture = await engine.captureFrameToBuffer(activeSession, frame, frame * fps.den / fps.num);
+            const programError = await activeSession.page.evaluate(() =>
+              (window as unknown as { __hypitBrowserProgramError?: string }).__hypitBrowserProgramError);
+            if (programError !== undefined) throw new Error(`Browser program failed at frame ${frame}: ${programError}`);
+            return capture;
+          });
+          await writeFile(join(outputFrames, `${String(frame - range.startFrame).padStart(9, "0")}.png`), captured.buffer);
+        }
+        onProgress?.({ phase: "worker-complete", worker, range: task, browserPid, elapsedMs: elapsedMs() });
+      } catch (error) {
+        controller.abort(error);
+        throw error;
+      } finally {
+        if (session !== undefined) await close(session);
+      }
+    }));
+    signal.throwIfAborted();
+    for (const result of results) if (result.status === "rejected") throw result.reason;
+    await Promise.all(closing.values());
+    const output = join(work, "visual.mp4");
+    const crf = { draft: 28, standard: 23, high: 18 }[config.quality];
+    await runProcess({ executable: config.ffmpegPath,
+      argv: ["-v", "error", "-y", "-framerate", `${fps.num}/${fps.den}`, "-i", join(outputFrames, "%09d.png"),
+        "-frames:v", String(frameCount), "-an", "-c:v", "libx264", "-crf", String(crf),
+        "-preset", config.quality === "draft" ? "veryfast" : "medium", "-pix_fmt", "yuv420p", "-movflags", "+faststart", output],
+      timeoutMs: config.processTimeoutMs, maxOutputBytes: config.maxProcessOutputBytes, signal });
+    const outputStat = await stat(output);
+    assert(outputStat.size > 0 && outputStat.size <= config.maxRenderedBytes, "HyperFrames output is empty or exceeds its byte limit");
+    await verifyOutput({ path: output, document: { ...document, frameCount }, ffprobePath: config.ffprobePath,
+      timeoutMs: config.processTimeoutMs, maxOutputBytes: config.maxProcessOutputBytes, signal });
+    signal.throwIfAborted();
+    return output;
+  } finally {
+    signal.removeEventListener("abort", abort);
+    await Promise.allSettled([...sessions].map(close));
+    if (server !== undefined) await server.close();
+  }
+}

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

@@ -0,0 +1,10 @@
+export { createLocalHyperframesProvider, localHyperframesProviderModuleRef } from "./provider.js";
+export type {
+  CreateLocalHyperframesProviderOptions,
+  HyperframesBrowserGpu,
+  HyperframesQuality,
+  HyperframesWorkers,
+} from "./provider.js";
+
+export { renderHyperframesVisual } from "./render.js";
+export type { RenderHyperframesVisualOptions, HyperframesRenderProgress } from "./render.js";

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

@@ -0,0 +1,19 @@
+export type HyperframesWorkers = number | "auto";
+export type HyperframesQuality = "draft" | "standard" | "high";
+export type HyperframesBrowserGpu = "auto" | "software" | "hardware";
+
+export type HyperframesExecutionOptions = {
+  readonly ffprobePath?: string;
+  /** Final H.264 encoder. Source extraction uses the pinned engine's binary resolver. */
+  readonly ffmpegPath?: string;
+  /** Parallel Chrome workers inside one render. This is separate from Provider request concurrency. */
+  readonly workers?: HyperframesWorkers;
+  readonly quality?: HyperframesQuality;
+  /** Chrome's rasterizer, default hardware. Use software without a usable GPU. */
+  readonly browserGpu?: HyperframesBrowserGpu;
+  readonly processTimeoutMs?: number;
+  readonly initializationTimeoutMs?: number;
+  readonly frameTimeoutMs?: number;
+  readonly maxProcessOutputBytes?: number;
+  readonly maxRenderedBytes?: number;
+};

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

@@ -0,0 +1,73 @@
+import type { HyperframesDocument } from "@hypit/hyperframes";
+import { assert, runProcess } from "./process.js";
+
+type ProbeStream = {
+  readonly codec_type?: unknown;
+  readonly codec_name?: unknown;
+  readonly width?: unknown;
+  readonly height?: unknown;
+  readonly avg_frame_rate?: unknown;
+  readonly r_frame_rate?: unknown;
+  readonly nb_read_frames?: unknown;
+  readonly nb_frames?: unknown;
+};
+
+function parseRational(value: unknown, subject: string): { readonly numerator: bigint; readonly denominator: bigint } {
+  assert(typeof value === "string" && /^\d+\/\d+$/u.test(value), `${subject} is not a rational`);
+  const [numerator, denominator] = value.split("/");
+  assert(numerator !== undefined && denominator !== undefined && BigInt(denominator) > 0n,
+    `${subject} is invalid`);
+  return { numerator: BigInt(numerator), denominator: BigInt(denominator) };
+}
+
+function equalsRational(
+  actual: { readonly numerator: bigint; readonly denominator: bigint },
+  expected: { readonly numerator: number; readonly denominator: number },
+): boolean {
+  return actual.numerator * BigInt(expected.denominator)
+    === BigInt(expected.numerator) * actual.denominator;
+}
+
+function outputFrameCount(stream: ProbeStream): number {
+  const value = stream.nb_read_frames ?? stream.nb_frames;
+  assert(typeof value === "string" && /^\d+$/u.test(value), "Rendered visual has no decoded frame count");
+  const count = Number(value);
+  assert(Number.isSafeInteger(count), "Rendered visual frame count exceeds safe arithmetic");
+  return count;
+}
+
+export async function verifyOutput(args: {
+  readonly path: string;
+  readonly document: HyperframesDocument;
+  readonly ffprobePath: string;
+  readonly timeoutMs: number;
+  readonly maxOutputBytes: number;
+  readonly signal?: AbortSignal;
+}): Promise<void> {
+  const probe = await runProcess({
+    executable: args.ffprobePath,
+    argv: ["-v", "error", "-print_format", "json", "-show_streams", "-count_frames", args.path],
+    timeoutMs: args.timeoutMs,
+    maxOutputBytes: args.maxOutputBytes,
+    ...(args.signal === undefined ? {} : { signal: args.signal }),
+  });
+  let value: unknown;
+  try {
+    value = JSON.parse(Buffer.from(probe.stdout).toString("utf8"));
+  } catch {
+    throw new Error("ffprobe returned invalid JSON for the HyperFrames output");
+  }
+  assert(value !== null && typeof value === "object" && !Array.isArray(value),
+    "ffprobe returned an invalid HyperFrames inspection");
+  const streams = (value as { readonly streams?: unknown }).streams;
+  assert(Array.isArray(streams) && streams.length === 1, "Rendered visual must contain exactly one stream");
+  const stream = streams[0] as ProbeStream;
+  assert(stream.codec_type === "video" && stream.codec_name === "h264",
+    "Rendered visual must contain one H.264 video stream and no audio");
+  assert(stream.width === args.document.canvas.width && stream.height === args.document.canvas.height,
+    "Rendered visual canvas differs from its document");
+  const rate = parseRational(stream.avg_frame_rate ?? stream.r_frame_rate, "Rendered visual frame rate");
+  assert(equalsRational(rate, args.document.frameRate), "Rendered visual frame rate differs from its document");
+  assert(outputFrameCount(stream) === args.document.frameCount,
+    "Rendered visual frame count differs from its document");
+}

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

@@ -0,0 +1,83 @@
+import { spawn } from "node:child_process";
+
+type ProcessResult = {
+  readonly stdout: Uint8Array;
+  readonly stderr: string;
+};
+
+export function assert(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(message);
+}
+export function positiveInteger(value: number, subject: string): number {
+  assert(Number.isSafeInteger(value) && value > 0, `${subject} must be a positive integer`);
+  return value;
+}
+
+function processEnvironment(): NodeJS.ProcessEnv {
+  const names = ["PATH", "HOME", "TMPDIR", "LANG", "LC_ALL"] as const;
+  return Object.fromEntries(names.flatMap((name) => process.env[name] === undefined
+    ? []
+    : [[name, process.env[name]]])) as NodeJS.ProcessEnv;
+}
+
+export async function runProcess(args: {
+  readonly executable: string;
+  readonly argv: readonly string[];
+  readonly timeoutMs: number;
+  readonly maxOutputBytes: number;
+  readonly signal?: AbortSignal;
+}): Promise<ProcessResult> {
+  args.signal?.throwIfAborted();
+  return await new Promise((resolve, reject) => {
+    const child = spawn(args.executable, [...args.argv], {
+      shell: false,
+      windowsHide: true,
+      stdio: ["ignore", "pipe", "pipe"],
+      env: processEnvironment(),
+    });
+    const stdout: Buffer[] = [];
+    let outputBytes = 0;
+    let stderr = "";
+    let settled = false;
+    let failure: Error | undefined;
+    const stop = (error: Error) => {
+      failure ??= error;
+      child.kill("SIGKILL");
+    };
+    const finish = (error?: Error): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      args.signal?.removeEventListener("abort", abort);
+      if (error === undefined) resolve({ stdout: Buffer.concat(stdout), stderr });
+      else reject(error);
+    };
+    const abort = () => stop(args.signal?.reason ?? new Error("Process aborted"));
+    args.signal?.addEventListener("abort", abort, { once: true });
+    const timer = setTimeout(() => {
+      stop(new Error(`${args.executable} timed out`));
+    }, args.timeoutMs);
+    child.stdout.on("data", (chunk: Buffer) => {
+      outputBytes += chunk.byteLength;
+      if (outputBytes > args.maxOutputBytes) {
+        stop(new Error(`${args.executable} output exceeded the configured limit`));
+        return;
+      }
+      stdout.push(chunk);
+    });
+    child.stderr.on("data", (chunk: Buffer) => {
+      outputBytes += chunk.byteLength;
+      stderr = `${stderr}${chunk.toString()}`.slice(-32_000);
+      if (outputBytes > args.maxOutputBytes) {
+        stop(new Error(`${args.executable} output exceeded the configured limit`));
+      }
+    });
+    child.on("error", (error) => finish(error));
+    if (args.signal?.aborted) abort();
+    child.on("close", (code) => {
+      if (failure !== undefined) finish(failure);
+      else if (code === 0) finish();
+      else finish(new Error(`${args.executable} exited ${String(code)}: ${stderr}`));
+    });
+  });
+}