Code-first video & image, rendered natively on WebGPU.
feat(renderer): abort, progress and per-job cache reset (phase 4)
okanasl588f0b143910
diff --git a/apps/renderer-service/PLAN.md b/apps/renderer-service/PLAN.mdindex 549a334a..2852ccae 100644--- a/apps/renderer-service/PLAN.md+++ b/apps/renderer-service/PLAN.md@@ -497,21 +497,23 @@ The service no longer uses `S3StorageService` from `@framefields/server-utils`,Each phase is its own PR-sized step with tests.-0. **Unbreak and remove the inline path.**+0. **Unbreak and remove the inline path.** ✅ Done.- Drop the DI container (`di-setup.ts`, inversify, `ServerMediaService`, `R2StorageService`). Storage returns in phase 6 as the service's own output sink.- Delete the `virtualMedia` path: `job-processor.ts`, `render-upload.ts`, `cli.ts --job <json>`, the `/run` and `/status` routes, `configureAssetUrls`/`BASE_URL`, and the old `render.test.ts` cases. Keep `/health`, `/ping`, readiness and graceful shutdown.- Fix the `gatewai-renderer` paths in the entrypoint and the Python shim.- Get `pnpm --filter @framefields/renderer-service typecheck test` green.-1. **Config + job schema v2 + error model.**+1. **Config + job schema v2 + error model.** ✅ Done.- `src/config/` (frozen config, secrets scrubbed from `process.env`), `src/jobs/schema.ts`, `src/errors.ts` (`RenderError` with `code`/`phase`/`retryable`), and the redactor.- API-key auth on HTTP, the job store with TTL eviction, and the single-slot queue.-2. **GitWorkspace.**+2. **GitWorkspace.** ✅ Done, except that the LFS download is untested locally because git-lfs isn't installed.- Mirror cache, ref resolution, workspace leasing, auth helpers and host profiles (6.5), LFS pull with pre- and postflight, eviction.- Integration tests use local bare repos and a file-based LFS remote (`lfs.standalonetransferagent`), so no network is needed.-3. **Installer.** Package manager detection, frozen install with framefields filtered out, skipping the install when nothing else is needed, the stamp check, shared stores, and the engine range check.-4. **Engine hooks (in `@framefields/renderer` and `framefields`).**- - `signal: AbortSignal` and `onProgress` on `renderVideo`/`renderFrame`/`renderFrameGrid`, checked between frames.- - A per-job cache reset (fonts, textures, compiled timelines) that keeps the device and pipelines.+3. **Installer.** ✅ Done: package manager detection (via `packageManager` or the lockfile, run through corepack), frozen install, skipping the install when nothing else is needed, the stamp check, shared stores, the engine range check, and install error classification. `install.prepare` steps are deferred until the repo defaults file (`framefields.render.json`) is implemented.+4. **Engine hooks (in `@framefields/renderer` and `framefields`).** ✅ Done:+ - `signal: AbortSignal` and `onProgress` on `renderVideo`, checked between frames and before the audio mix. Single-frame renders don't need either.+ - `resetRenderCaches()` (`@framefields/renderer`) clears media inputs and decoders, textures, LUTs and fonts. The worker calls it plus `FontManager.clear()` before each job. The GPU device and pipelines stay warm.+ - A GPU test (`src/engine.gpu.test.ts`, run with `FF_GPU_TESTS=1`) confirmed that without the reset, a changed file at the same workspace path is served stale.+ - Not yet verified: re-opening a *video* file at the same path after the reset. A comment in `renderImage` says a mediabunny `Input` can only be created once per URL. Phase 5 needs a GPU test that renders a video layer in two jobs back to back.5. **InProcessRenderer.**- The engine alias resolve hook, `tsImport` loading, export-shape normalisation, the job sandbox (8.2), the watchdog, the crash journal, and recycling.6. **Outputs.** The s3, presigned, local and inline sinks, verification (ffprobe), multi-output keys, and idempotency.diff --git a/apps/renderer-service/src/engine.gpu.test.ts b/apps/renderer-service/src/engine.gpu.test.tsnew file mode 100644index 00000000..cdd7c6ba--- /dev/null+++ b/apps/renderer-service/src/engine.gpu.test.ts@@ -0,0 +1,127 @@+/**+ * Engine hooks the in-process worker relies on (PLAN.md §8): progress and+ * abort in renderVideo, and the per-job cache reset. Needs a GPU, so it only+ * runs with FF_GPU_TESTS=1.+ */+import fs from "node:fs/promises";+import os from "node:os";+import path from "node:path";+import { deflateSync } from "node:zlib";+import { resetRenderCaches } from "@framefields/renderer";+import { ApplyLUT, Composition, FontManager, Media } from "framefields";+import { afterAll, beforeAll, describe, expect, it } from "vitest";++const gpu = describe.skipIf(process.env.FF_GPU_TESTS !== "1");++let dir = "";++/** A solid-colour RGB PNG, without pulling in an image library. */+function solidPng(size: number, rgb: [number, number, number]): Buffer {+ const crcTable = Array.from({ length: 256 }, (_, n) => {+ let c = n;+ for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;+ return c >>> 0;+ });+ const crc = (buf: Buffer) => {+ let c = 0xffffffff;+ for (const b of buf) c = crcTable[(c ^ b) & 0xff] ^ (c >>> 8);+ return (c ^ 0xffffffff) >>> 0;+ };+ const chunk = (type: string, data: Buffer) => {+ const len = Buffer.alloc(4);+ len.writeUInt32BE(data.length);+ const body = Buffer.concat([Buffer.from(type, "ascii"), data]);+ const sum = Buffer.alloc(4);+ sum.writeUInt32BE(crc(body));+ return Buffer.concat([len, body, sum]);+ };+ const ihdr = Buffer.alloc(13);+ ihdr.writeUInt32BE(size, 0);+ ihdr.writeUInt32BE(size, 4);+ ihdr.set([8, 2, 0, 0, 0], 8);+ const row = Buffer.concat([+ Buffer.from([0]),+ Buffer.from(Array(size).fill(rgb).flat()),+ ]);+ return Buffer.concat([+ Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),+ chunk("IHDR", ihdr),+ chunk("IDAT", deflateSync(Buffer.concat(Array(size).fill(row)))),+ chunk("IEND", Buffer.alloc(0)),+ ]);+}++const cube = (rgb: string) =>+ ["LUT_3D_SIZE 2", ...Array(8).fill(rgb)].join("\n");++beforeAll(async () => {+ dir = await fs.mkdtemp(path.join(os.tmpdir(), "ff-engine-"));+ await fs.writeFile(path.join(dir, "grey.png"), solidPng(64, [128, 128, 128]));+});+afterAll(async () => {+ await fs.rm(dir, { recursive: true, force: true });+});++gpu("engine hooks", () => {+ const film = () =>+ new Composition({+ width: 64,+ height: 64,+ fps: 24,+ durationFrames: 48,+ backgroundColor: "#204060",+ });++ it("reports progress for every frame, then the audio mix", async () => {+ const seen: string[] = [];+ const result = await film().renderVideo({+ onProgress: (p) => seen.push(`${p.phase}:${p.frame}/${p.totalFrames}`),+ });+ await result.cleanup();+ expect(seen.filter((s) => s.startsWith("render:"))).toHaveLength(48);+ expect(seen.at(-2)).toBe("render:48/48");+ expect(seen.at(-1)).toBe("audio:48/48");+ }, 120_000);++ it("aborts between frames with the signal's reason", async () => {+ const controller = new AbortController();+ const reason = new Error("job cancelled");+ let frames = 0;+ const render = film().renderVideo({+ signal: controller.signal,+ onProgress: (p) => {+ frames = p.frame;+ if (p.frame === 5) controller.abort(reason);+ },+ });+ await expect(render).rejects.toBe(reason);+ expect(frames).toBe(5);++ // The worker keeps going after an abort.+ const next = await film().renderVideo({});+ await next.cleanup();+ }, 120_000);++ it("serves a changed file at the same path only after resetRenderCaches()", async () => {+ const lut = path.join(dir, "look.cube");+ const grey = path.join(dir, "grey.png");+ const frame = () =>+ Media.image(grey, { width: 64, height: 64 })+ .apply(new ApplyLUT({ lutUrl: lut, intensity: 1 }))+ .renderFrame({ frame: 0 });++ await fs.writeFile(lut, cube("0 1 0"));+ const green = await frame();++ // Same path, new bytes: what the next job's checkout looks like.+ await fs.writeFile(lut, cube("1 0 0"));+ const stale = await frame();++ resetRenderCaches();+ FontManager.clear();+ const red = await frame();++ expect(Buffer.compare(stale, green)).toBe(0);+ expect(Buffer.compare(red, green)).not.toBe(0);+ }, 120_000);+});diff --git a/packages/framefields/src/index.ts b/packages/framefields/src/index.tsindex afe053d9..ea117cc4 100644--- a/packages/framefields/src/index.ts+++ b/packages/framefields/src/index.ts@@ -243,6 +243,7 @@ import {import {type FrameGridOptions,HeadlessMediaRenderer,+ type RenderProgress,renderFrameGrid,type VideoQaOptions,type VideoQaReport,@@ -1000,6 +1001,13 @@ export interface RenderVideoOptions {* pass thresholds (e.g. `{ targetLufs: -14 }`) to tighten them.*/qa?: boolean | VideoQaOptions;+ /**+ * Stops the render between frames. The promise rejects with+ * `signal.reason` and no file is left behind.+ */+ signal?: AbortSignal;+ /** Called as frames finish (`phase: "render"`), then once for the audio mix. */+ onProgress?: (progress: RenderProgress) => void;}export interface RenderVideoResult {@@ -2914,6 +2922,7 @@ export {HeadlessWebGPURenderer,type QaIssue,type QaSegment,+ type RenderProgress,renderFrameGrid,renderSemaphore,resolveSamplePoints,diff --git a/packages/framefields/src/renderer/index.ts b/packages/framefields/src/renderer/index.tsindex 0d5312b3..d811bbad 100644--- a/packages/framefields/src/renderer/index.ts+++ b/packages/framefields/src/renderer/index.ts@@ -5,6 +5,7 @@ export {HeadlessWebGPURenderer,type QaIssue,type QaSegment,+ type RenderProgress,renderSemaphore,type VideoQaOptions,type VideoQaReport,diff --git a/packages/renderer/src/headless-webgpu-renderer.ts b/packages/renderer/src/headless-webgpu-renderer.tsindex 245a4161..d8ea1785 100644--- a/packages/renderer/src/headless-webgpu-renderer.ts+++ b/packages/renderer/src/headless-webgpu-renderer.ts@@ -1035,6 +1035,13 @@ export class HeadlessWebGPURenderer {* and return the findings as `qa`. `true` uses default thresholds.*/qa?: boolean | VideoQaOptions;+ /**+ * Aborts the render between frames; the promise rejects with+ * `signal.reason` and the partial output is deleted.+ */+ signal?: AbortSignal;+ /** Called after each frame is queued for encoding, then once for audio. */+ onProgress?: (progress: RenderProgress) => void;},): Promise<{filePath: string;@@ -1265,6 +1272,7 @@ export class HeadlessWebGPURenderer {// Render and encode frames using pipelined double-buffered DMA staging ringfor (let i = 0; i < totalFrames; i++) {+ options?.signal?.throwIfAborted();if (i % 10 === 0) {rendererLogger.info({ renderId, frame: i, totalFrames },@@ -1321,6 +1329,11 @@ export class HeadlessWebGPURenderer {);await pipeline.enqueueFrame(i, targetTexture, encoder);+ options?.onProgress?.({+ phase: "render",+ frame: i + 1,+ totalFrames,+ });} else {throw new Error("Invalid render context state");}@@ -1347,6 +1360,12 @@ export class HeadlessWebGPURenderer {}// ── Audio ──────────────────────────────────────────────────────────────+ options?.signal?.throwIfAborted();+ options?.onProgress?.({+ phase: "audio",+ frame: totalFrames,+ totalFrames,+ });const { channels, sampleRate } = await mixAudioTracks(virtualMedia,fps,@@ -1391,6 +1410,7 @@ export class HeadlessWebGPURenderer {}}+ options?.signal?.throwIfAborted();await output.finalize();outputFinalized = true;@@ -1474,5 +1494,14 @@ export class HeadlessWebGPURenderer {}}+/** Progress reported by `renderVideo({ onProgress })`. */+export interface RenderProgress {+ /** "render" while frames are drawn and encoded, "audio" while mixing. */+ phase: "render" | "audio";+ /** Frames finished so far (1-based). */+ frame: number;+ totalFrames: number;+}+export const HeadlessMediaRenderer = HeadlessWebGPURenderer;export type HeadlessMediaRenderer = HeadlessWebGPURenderer;diff --git a/packages/renderer/src/index.ts b/packages/renderer/src/index.tsindex a8defd36..a8418280 100644--- a/packages/renderer/src/index.ts+++ b/packages/renderer/src/index.ts@@ -2,6 +2,7 @@ export * from "./asset-preloader.js";export * from "./dma-staging-ring.js";export * from "./dynamic-node-discovery.js";export * from "./headless-webgpu-renderer.js";+export * from "./job-reset.js";export * from "./logger.js";export * from "./node-manifest.js";export * from "./video-qa.js";diff --git a/packages/renderer/src/job-reset.ts b/packages/renderer/src/job-reset.tsnew file mode 100644index 00000000..4e9706d1--- /dev/null+++ b/packages/renderer/src/job-reset.ts@@ -0,0 +1,23 @@+import {+ clearAllVideoCache,+ inputStore,+ lutStore,+ mediaDecoderCache,+ SlugFontCache,+ textureCache,+} from "@framefields/webgpu-renderers";++/**+ * Drops every cache keyed by a file path or URL: media inputs and decoders,+ * textures, LUTs and fonts. A long-lived worker calls this between jobs,+ * because the next checkout may hold different bytes at the same path. The+ * GPU device and compiled pipelines stay warm.+ */+export function resetRenderCaches(): void {+ clearAllVideoCache();+ mediaDecoderCache.destroy();+ textureCache.destroy();+ inputStore.clear();+ lutStore.destroy();+ SlugFontCache.destroy();+}diff --git a/packages/webgpu-renderers/src/input-store.ts b/packages/webgpu-renderers/src/input-store.tsindex 25b0fc02..aa8a23d3 100644--- a/packages/webgpu-renderers/src/input-store.ts+++ b/packages/webgpu-renderers/src/input-store.ts@@ -95,6 +95,25 @@ class InputStore {return shared.promise;}+ /**+ * Drops every cached input, including ones a failed render never released.+ * Used between jobs, when the same path may now hold a different file.+ */+ clear(): void {+ const entries = [...this.store.values()];+ this.store.clear();+ for (const shared of entries) {+ shared.promise.then(+ (input) => {+ try {+ input.dispose();+ } catch (_) {}+ },+ () => {},+ );+ }+ }+release(url: string): void {if (!url) return;const resolvedUrl = resolveInputUrl(url, isNodeRuntime());