@kitsra/kavio-render 0.1.0

package/dist/harness-server.js

@@ -0,0 +1,171 @@
+import { readFile } from "node:fs/promises";
+import { createServer } from "node:http";
+import { getCanvasDimensions } from "@kitsra/kavio-core";
+import { createRenderHarnessHtml } from "@kitsra/kavio-browser-renderer";
+/**
+ * Tiny localhost static server that feeds the headless render harness page to
+ * Chromium: the shared harness HTML, `/composition.json`, and the vendored
+ * `@kitsra/kavio-core` and `@kitsra/kavio-browser-renderer` ESM bundles.
+ */
+export async function createRenderHarnessServer(options) {
+    const { composition, assets } = prepareHarnessComposition(options.composition);
+    const dimensions = getCanvasDimensions(composition.composition);
+    const html = createRenderHarnessHtml({
+        width: dimensions.width,
+        height: dimensions.height,
+        fps: composition.composition.fps,
+        durationFrames: composition.composition.durationFrames
+    });
+    const compositionJson = `${JSON.stringify(composition)}\n`;
+    const [coreSource, browserRendererSource] = await Promise.all([
+        readFile(new URL("../../core/dist/index.js", import.meta.url), "utf8"),
+        readFile(new URL("../../browser-renderer/dist/index.js", import.meta.url), "utf8")
+    ]);
+    const server = createServer((request, response) => {
+        handleRequest(request, response, { html, compositionJson, coreSource, browserRendererSource, assets });
+    });
+    const port = await listenOnLocalhost(server);
+    return {
+        url: `http://127.0.0.1:${port}/`,
+        close: () => closeServer(server)
+    };
+}
+function handleRequest(request, response, assets) {
+    const path = (request.url ?? "/").split("?", 1)[0] ?? "/";
+    if (path === "/" || path === "/index.html") {
+        send(response, 200, "text/html; charset=utf-8", assets.html);
+        return;
+    }
+    if (path === "/composition.json") {
+        send(response, 200, "application/json; charset=utf-8", assets.compositionJson);
+        return;
+    }
+    if (path === "/vendor/core/index.js") {
+        send(response, 200, "text/javascript; charset=utf-8", assets.coreSource);
+        return;
+    }
+    if (path === "/vendor/browser-renderer/index.js") {
+        send(response, 200, "text/javascript; charset=utf-8", assets.browserRendererSource);
+        return;
+    }
+    const assetId = assetIdFromPath(path);
+    if (assetId !== null) {
+        const asset = assets.assets.get(assetId);
+        if (asset === undefined) {
+            send(response, 404, "text/plain; charset=utf-8", "Not found.\n");
+            return;
+        }
+        void sendFile(response, asset);
+        return;
+    }
+    send(response, 404, "text/plain; charset=utf-8", "Not found.\n");
+}
+function send(response, statusCode, contentType, value) {
+    response.statusCode = statusCode;
+    response.setHeader("content-type", contentType);
+    response.setHeader("cache-control", "no-store");
+    response.end(value);
+}
+async function sendFile(response, asset) {
+    try {
+        const bytes = await readFile(asset.path);
+        response.statusCode = 200;
+        response.setHeader("content-type", asset.contentType);
+        response.setHeader("cache-control", "no-store");
+        response.end(bytes);
+    }
+    catch {
+        send(response, 404, "text/plain; charset=utf-8", "Not found.\n");
+    }
+}
+function prepareHarnessComposition(composition) {
+    const assets = new Map();
+    const clone = JSON.parse(JSON.stringify(composition));
+    for (const [assetId, asset] of Object.entries(clone.assets)) {
+        const localPath = localAssetPath(asset.src);
+        if (localPath === null) {
+            continue;
+        }
+        const servedId = encodeURIComponent(assetId);
+        assets.set(servedId, { path: localPath, contentType: contentTypeForPath(localPath, asset) });
+        asset.src = `/assets/${servedId}`;
+    }
+    return { composition: clone, assets };
+}
+function localAssetPath(src) {
+    if (src.startsWith("/")) {
+        return src;
+    }
+    if (src.startsWith("file://")) {
+        try {
+            return decodeURIComponent(new URL(src).pathname);
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+function assetIdFromPath(path) {
+    if (!path.startsWith("/assets/")) {
+        return null;
+    }
+    return path.slice("/assets/".length);
+}
+function contentTypeForPath(path, asset) {
+    const lower = path.toLowerCase();
+    if (lower.endsWith(".png")) {
+        return "image/png";
+    }
+    if (lower.endsWith(".jpg") || lower.endsWith(".jpeg")) {
+        return "image/jpeg";
+    }
+    if (lower.endsWith(".webp")) {
+        return "image/webp";
+    }
+    if (lower.endsWith(".svg")) {
+        return "image/svg+xml";
+    }
+    if (lower.endsWith(".mp4")) {
+        return "video/mp4";
+    }
+    if (lower.endsWith(".webm")) {
+        return "video/webm";
+    }
+    if (lower.endsWith(".wav")) {
+        return "audio/wav";
+    }
+    if (lower.endsWith(".mp3")) {
+        return "audio/mpeg";
+    }
+    if (lower.endsWith(".woff2")) {
+        return "font/woff2";
+    }
+    if (lower.endsWith(".woff")) {
+        return "font/woff";
+    }
+    return asset.type === "font" ? "font/woff2" : "application/octet-stream";
+}
+function listenOnLocalhost(server) {
+    return new Promise((resolve, reject) => {
+        server.listen(0, "127.0.0.1", () => {
+            const address = server.address();
+            if (address !== null && typeof address === "object" && typeof address.port === "number") {
+                resolve(address.port);
+                return;
+            }
+            reject(new Error("Harness server did not return a TCP address."));
+        });
+    });
+}
+function closeServer(server) {
+    return new Promise((resolve, reject) => {
+        server.close((error) => {
+            if (error) {
+                reject(error);
+                return;
+            }
+            resolve();
+        });
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export declare const KAVIO_RENDER_PACKAGE = "@kitsra/kavio-render";
+export { renderError, isRenderError, RENDER_ERROR_CODES, type RenderErrorCode, type RenderErrorOptions } from "./errors.js";
+export { assembleRenderCommand, type AssembleRenderCommandOptions } from "./assemble-command.js";
+export { resolveFfmpegPath } from "./binaries.js";
+export { createFfmpegRunner, type FfmpegRunner, type FfmpegRunOptions, type FfmpegRunResult, type FfmpegSpawn, type FfmpegChildProcess, type CreateFfmpegRunnerOptions } from "./ffmpeg-runner.js";
+export { createRenderHarnessServer, type RenderHarnessServer, type CreateRenderHarnessServerOptions } from "./harness-server.js";
+export { PlaywrightDriver, type PlaywrightDriverOptions } from "./playwright-driver.js";
+export { renderComposition, type RenderCompositionOptions, type RenderCompositionResult } from "./render-composition.js";
+export { renderBatch, type RenderBatchOptions, type RenderBatchItemResult } from "./render-batch.js";
+export type { RenderBatchInput, RenderBatchRow } from "@kitsra/kavio-render-worker";
+export { FakeBrowserDriver, createFakeFfmpegRunner, type FakeFfmpegRunner, type CreateFakeFfmpegRunnerOptions } from "./testing.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAE3D,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,kBAAkB,EAAE,KAAK,eAAe,EAAE,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAC5H,OAAO,EAAE,qBAAqB,EAAE,KAAK,4BAA4B,EAAE,MAAM,uBAAuB,CAAC;AACjG,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,EACL,kBAAkB,EAClB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,EAC/B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,yBAAyB,EACzB,KAAK,mBAAmB,EACxB,KAAK,gCAAgC,EACtC,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACxF,OAAO,EACL,iBAAiB,EACjB,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,EAC7B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,KAAK,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AACrG,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AACpF,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,KAAK,gBAAgB,EACrB,KAAK,6BAA6B,EACnC,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,10 @@
+export const KAVIO_RENDER_PACKAGE = "@kitsra/kavio-render";
+export { renderError, isRenderError, RENDER_ERROR_CODES } from "./errors.js";
+export { assembleRenderCommand } from "./assemble-command.js";
+export { resolveFfmpegPath } from "./binaries.js";
+export { createFfmpegRunner } from "./ffmpeg-runner.js";
+export { createRenderHarnessServer } from "./harness-server.js";
+export { PlaywrightDriver } from "./playwright-driver.js";
+export { renderComposition } from "./render-composition.js";
+export { renderBatch } from "./render-batch.js";
+export { FakeBrowserDriver, createFakeFfmpegRunner } from "./testing.js";

package/dist/playwright-driver.d.ts

@@ -0,0 +1,27 @@
+import { type BrowserDriver, type BrowserFrameCapture, type BrowserFrameCaptureOptions, type BrowserOpenOptions } from "@kitsra/kavio-render-worker";
+import type { KavioDocument } from "@kitsra/kavio-schema";
+export interface PlaywrightDriverOptions {
+    deviceScaleFactor?: number;
+    readyTimeoutMs?: number;
+}
+/**
+ * Concrete BrowserDriver backed by Playwright + bundled Chromium. Launches with
+ * the deterministic flags, serves the headless harness page, and captures one
+ * transparent PNG per frame. Real binaries are exercised only in the gated e2e.
+ */
+export declare class PlaywrightDriver implements BrowserDriver {
+    private browser;
+    private context;
+    private page;
+    private server;
+    private viewport;
+    private readonly deviceScaleFactor;
+    private readonly readyTimeoutMs;
+    /** Chromium version string, available after open() for render metadata. */
+    chromiumVersion: string | null;
+    constructor(options?: PlaywrightDriverOptions);
+    open(composition: KavioDocument, options?: BrowserOpenOptions): Promise<void>;
+    renderFrame(frame: number, options?: BrowserFrameCaptureOptions): Promise<BrowserFrameCapture>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=playwright-driver.d.ts.map

package/dist/playwright-driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playwright-driver.d.ts","sourceRoot":"","sources":["../src/playwright-driver.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,0BAA0B,EAC/B,KAAK,kBAAkB,EAExB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AA+C1D,MAAM,WAAW,uBAAuB;IACtC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,qBAAa,gBAAiB,YAAW,aAAa;IACpD,OAAO,CAAC,OAAO,CAAkC;IACjD,OAAO,CAAC,OAAO,CAAkC;IACjD,OAAO,CAAC,IAAI,CAA+B;IAC3C,OAAO,CAAC,MAAM,CAAoC;IAClD,OAAO,CAAC,QAAQ,CAAgC;IAChD,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IAExC,2EAA2E;IAC3E,eAAe,EAAE,MAAM,GAAG,IAAI,CAAQ;gBAE1B,OAAO,GAAE,uBAA4B;IAK3C,IAAI,CAAC,WAAW,EAAE,aAAa,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC;IAsCjF,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,0BAA+B,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAgBlG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAY7B"}

package/dist/playwright-driver.js

@@ -0,0 +1,103 @@
+import { createBrowserViewport, createPngFrameCapture, DEFAULT_CHROMIUM_LAUNCH_OPTIONS } from "@kitsra/kavio-render-worker";
+import { renderError } from "./errors.js";
+import { createRenderHarnessServer } from "./harness-server.js";
+async function loadChromium() {
+    const specifier = "playwright";
+    try {
+        const mod = (await import(specifier));
+        return mod.chromium;
+    }
+    catch {
+        throw renderError({
+            code: "BINARY_MISSING",
+            stage: "render",
+            message: "Playwright (bundled Chromium) is not available.",
+            hint: "Install render browser binaries with 'corepack pnpm run install:render-browsers'."
+        });
+    }
+}
+/**
+ * Concrete BrowserDriver backed by Playwright + bundled Chromium. Launches with
+ * the deterministic flags, serves the headless harness page, and captures one
+ * transparent PNG per frame. Real binaries are exercised only in the gated e2e.
+ */
+export class PlaywrightDriver {
+    browser = null;
+    context = null;
+    page = null;
+    server = null;
+    viewport = null;
+    deviceScaleFactor;
+    readyTimeoutMs;
+    /** Chromium version string, available after open() for render metadata. */
+    chromiumVersion = null;
+    constructor(options = {}) {
+        this.deviceScaleFactor = options.deviceScaleFactor ?? 1;
+        this.readyTimeoutMs = options.readyTimeoutMs ?? 30_000;
+    }
+    async open(composition, options = {}) {
+        const viewport = options.viewport ?? createBrowserViewport(composition, this.deviceScaleFactor);
+        this.viewport = viewport;
+        const chromium = await loadChromium();
+        try {
+            this.browser = await chromium.launch({
+                headless: DEFAULT_CHROMIUM_LAUNCH_OPTIONS.headless,
+                args: DEFAULT_CHROMIUM_LAUNCH_OPTIONS.args
+            });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (missingBrowserExecutable(message)) {
+                throw renderError({
+                    code: "BINARY_MISSING",
+                    stage: "render",
+                    message: "Playwright Chromium is not installed for Kavio rendering.",
+                    hint: "Install render browser binaries with 'corepack pnpm run install:render-browsers'."
+                });
+            }
+            throw renderError({
+                code: "RENDER_FAILED",
+                stage: "render",
+                message: `Failed to launch Playwright Chromium: ${message}`
+            });
+        }
+        this.chromiumVersion = this.browser.version();
+        this.context = await this.browser.newContext({
+            viewport: { width: viewport.width, height: viewport.height },
+            deviceScaleFactor: viewport.deviceScaleFactor
+        });
+        this.page = await this.context.newPage();
+        this.server = await createRenderHarnessServer({ composition });
+        await this.page.goto(this.server.url);
+        await this.page.waitForFunction("window.__kavioReady === true", undefined, { timeout: this.readyTimeoutMs });
+    }
+    async renderFrame(frame, options = {}) {
+        if (this.page === null || this.viewport === null) {
+            throw renderError({
+                code: "RENDER_FRAME_FAILED",
+                stage: "render",
+                message: "PlaywrightDriver.renderFrame called before open()."
+            });
+        }
+        const omitBackground = options.omitBackground ?? true;
+        await this.page.evaluate(`window.__kavio.renderFrame(${frame})`);
+        const bytes = await this.page.screenshot({ type: "png", omitBackground });
+        return createPngFrameCapture({ frame, bytes, viewport: this.viewport, omitBackground });
+    }
+    async close() {
+        try {
+            await this.browser?.close();
+        }
+        finally {
+            await this.server?.close();
+        }
+        this.browser = null;
+        this.context = null;
+        this.page = null;
+        this.server = null;
+        this.viewport = null;
+    }
+}
+function missingBrowserExecutable(message) {
+    return message.includes("Executable doesn't exist") || message.includes("playwright install");
+}

package/dist/render-batch.d.ts

@@ -0,0 +1,20 @@
+import { type BrowserDriver, type RenderBatchInput } from "@kitsra/kavio-render-worker";
+import { type RenderCompositionResult } from "./render-composition.js";
+import type { FfmpegRunner } from "./ffmpeg-runner.js";
+export interface RenderBatchOptions {
+    outDir?: string;
+    driver?: BrowserDriver;
+    ffmpegRunner?: FfmpegRunner;
+    concurrency?: number;
+    failFast?: boolean;
+    signal?: AbortSignal;
+    continueOnFrameError?: boolean;
+}
+export interface RenderBatchItemResult {
+    id: string;
+    outputName: string;
+    result: RenderCompositionResult;
+}
+/** Expand a template × prop rows × export presets into jobs and render each one. */
+export declare function renderBatch(input: RenderBatchInput, options?: RenderBatchOptions): Promise<RenderBatchItemResult[]>;
+//# sourceMappingURL=render-batch.d.ts.map

package/dist/render-batch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-batch.d.ts","sourceRoot":"","sources":["../src/render-batch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,aAAa,EAAE,KAAK,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC3G,OAAO,EAAoD,KAAK,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AACzH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,uBAAuB,CAAC;CACjC;AAED,oFAAoF;AACpF,wBAAsB,WAAW,CAC/B,KAAK,EAAE,gBAAgB,EACvB,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,qBAAqB,EAAE,CAAC,CAgClC"}

package/dist/render-batch.js

@@ -0,0 +1,42 @@
+import { expandRenderBatch } from "@kitsra/kavio-render-worker";
+import { renderComposition } from "./render-composition.js";
+/** Expand a template × prop rows × export presets into jobs and render each one. */
+export async function renderBatch(input, options = {}) {
+    const jobs = expandRenderBatch(input);
+    const results = new Map();
+    // A shared injected driver cannot be driven concurrently; force sequential then.
+    const concurrency = options.driver !== undefined ? 1 : Math.max(1, Math.trunc(options.concurrency ?? 1));
+    let nextIndex = 0;
+    let aborted = false;
+    const worker = async () => {
+        while (!aborted) {
+            const index = nextIndex;
+            nextIndex += 1;
+            const job = jobs[index];
+            if (job === undefined) {
+                return;
+            }
+            const result = await renderComposition(job.document, buildRenderOptions(job, options));
+            results.set(index, { id: job.id, outputName: job.outputName, result });
+            if (!result.ok && options.failFast === true) {
+                aborted = true;
+                return;
+            }
+        }
+    };
+    const workerCount = Math.min(concurrency, jobs.length);
+    await Promise.all(Array.from({ length: workerCount }, () => worker()));
+    return [...results.entries()].sort(([left], [right]) => left - right).map(([, result]) => result);
+}
+function buildRenderOptions(job, options) {
+    return {
+        preset: job.preset,
+        propValues: job.props,
+        outputName: job.outputName,
+        ...(options.outDir !== undefined && { outDir: options.outDir }),
+        ...(options.driver !== undefined && { driver: options.driver }),
+        ...(options.ffmpegRunner !== undefined && { ffmpegRunner: options.ffmpegRunner }),
+        ...(options.signal !== undefined && { signal: options.signal }),
+        ...(options.continueOnFrameError !== undefined && { continueOnFrameError: options.continueOnFrameError })
+    };
+}

package/dist/render-composition.d.ts

@@ -0,0 +1,26 @@
+import { type KavioDocument, type KavioError } from "@kitsra/kavio-schema";
+import { type BrowserDriver, type RenderOutputMetadata } from "@kitsra/kavio-render-worker";
+import { type FfmpegRunner } from "./ffmpeg-runner.js";
+export interface RenderCompositionOptions {
+    preset: string | import("@kitsra/kavio-schema").KavioExportPreset;
+    propValues?: Record<string, unknown>;
+    outDir?: string;
+    outputName?: string;
+    driver?: BrowserDriver;
+    ffmpegRunner?: FfmpegRunner;
+    signal?: AbortSignal;
+    continueOnFrameError?: boolean;
+    ffmpegVersion?: string;
+    chromiumRevision?: string;
+}
+export type RenderCompositionResult = {
+    ok: true;
+    outputPath: string;
+    metadata: RenderOutputMetadata;
+} | {
+    ok: false;
+    errors: KavioError[];
+};
+/** End-to-end render for one (composition × export): props → view → validate → capture → encode. */
+export declare function renderComposition(doc: KavioDocument, options: RenderCompositionOptions): Promise<RenderCompositionResult>;
+//# sourceMappingURL=render-composition.d.ts.map

package/dist/render-composition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-composition.d.ts","sourceRoot":"","sources":["../src/render-composition.ts"],"names":[],"mappings":"AAKA,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,UAAU,EAEhB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAKL,KAAK,aAAa,EAElB,KAAK,oBAAoB,EAC1B,MAAM,6BAA6B,CAAC;AAErC,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAK3E,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,MAAM,GAAG,OAAO,sBAAsB,EAAE,iBAAiB,CAAC;IAClE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,MAAM,uBAAuB,GAC/B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,oBAAoB,CAAA;CAAE,GAChE;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,UAAU,EAAE,CAAA;CAAE,CAAC;AAExC,oGAAoG;AACpG,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,aAAa,EAClB,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,uBAAuB,CAAC,CAqFlC"}

package/dist/render-composition.js

@@ -0,0 +1,125 @@
+import { createHash } from "node:crypto";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { applyExportPreset, collectCompositionResourceLimitInputs, collectResourceLimitViolations, resolveTemplateProps } from "@kitsra/kavio-core";
+import { extensionForFormat, validateComposition } from "@kitsra/kavio-schema";
+import { captureFrames, createRenderMetadata, createTemporaryFramesCleanupTask, withRenderCleanup } from "@kitsra/kavio-render-worker";
+import { assembleRenderCommand } from "./assemble-command.js";
+import { createFfmpegRunner } from "./ffmpeg-runner.js";
+import { isRenderError, renderError } from "./errors.js";
+import { PlaywrightDriver } from "./playwright-driver.js";
+import { withEffectiveCodecs } from "./encoding.js";
+/** End-to-end render for one (composition × export): props → view → validate → capture → encode. */
+export async function renderComposition(doc, options) {
+    const resolution = resolveTemplateProps(doc, options.propValues ?? {});
+    if (!resolution.ok) {
+        return { ok: false, errors: resolution.errors };
+    }
+    let view;
+    try {
+        view = applyExportPreset(resolution.value, options.preset);
+    }
+    catch (error) {
+        return { ok: false, errors: [toKavioError(error)] };
+    }
+    const preset = view.exports[0];
+    if (preset === undefined) {
+        return {
+            ok: false,
+            errors: [renderError({ code: "RENDER_FAILED", stage: "render", message: "No export preset resolved for render." })]
+        };
+    }
+    const validation = validateComposition(view);
+    if (!validation.ok) {
+        return { ok: false, errors: validation.errors };
+    }
+    const violations = collectResourceLimitViolations(collectCompositionResourceLimitInputs(view));
+    if (violations.length > 0) {
+        return { ok: false, errors: violations };
+    }
+    const renderabilityError = validateRenderablePreset(preset);
+    if (renderabilityError !== null) {
+        return { ok: false, errors: [renderabilityError] };
+    }
+    const outputName = options.outputName ?? `${preset.name}.${extensionForFormat(preset.format)}`;
+    const outputPath = options.outDir === undefined ? outputName : join(options.outDir, outputName);
+    const metadataPreset = withEffectiveCodecs(preset);
+    try {
+        const metadata = await withRenderCleanup(async (cleanup) => {
+            const workDir = await mkdtemp(join(tmpdir(), "kavio-render-"));
+            cleanup.defer(createTemporaryFramesCleanupTask(async () => {
+                await rm(workDir, { recursive: true, force: true });
+            }, "workdir"));
+            const driver = options.driver ?? new PlaywrightDriver();
+            const framePattern = join(workDir, "overlay-%05d.png");
+            // captureFrames manages browser-context cleanup (open → capture → close).
+            await captureFrames({
+                driver,
+                composition: view,
+                continueOnFrameError: options.continueOnFrameError === true,
+                onFrame: async (capture) => {
+                    const name = `overlay-${String(capture.frame).padStart(5, "0")}.png`;
+                    await writeFile(join(workDir, name), capture.bytes);
+                }
+            });
+            await mkdir(dirname(outputPath), { recursive: true });
+            const args = assembleRenderCommand({ view, preset, framePattern, outputPath });
+            const ffmpegRunner = options.ffmpegRunner ?? createFfmpegRunner();
+            await ffmpegRunner.run(args, options.signal === undefined ? {} : { signal: options.signal });
+            const checksum = await sha256File(outputPath);
+            return createRenderMetadata({
+                composition: view.composition,
+                preset: metadataPreset,
+                outputName,
+                outputPath,
+                checksums: checksum,
+                ffmpegVersion: options.ffmpegVersion ?? "ffmpeg-static",
+                chromiumRevision: options.chromiumRevision ?? chromiumRevisionOf(driver)
+            });
+        });
+        return { ok: true, outputPath, metadata };
+    }
+    catch (error) {
+        return { ok: false, errors: [toKavioError(error)] };
+    }
+}
+function chromiumRevisionOf(driver) {
+    if (driver instanceof PlaywrightDriver && driver.chromiumVersion !== null) {
+        return driver.chromiumVersion;
+    }
+    return "unknown";
+}
+async function sha256File(path) {
+    const bytes = await readFile(path);
+    const value = createHash("sha256").update(bytes).digest("hex");
+    return { algorithm: "sha256", value, bytes: bytes.length };
+}
+function validateRenderablePreset(preset) {
+    if (preset.format === "gif" || preset.format === "png-sequence") {
+        return renderError({
+            code: "RENDER_FAILED",
+            stage: "render",
+            path: "exports.0.format",
+            message: `kavio render does not yet support ${preset.format} exports.`,
+            hint: "Use mp4, webm, or mov for the current render pipeline."
+        });
+    }
+    if (preset.background === "transparent") {
+        return renderError({
+            code: "RENDER_FAILED",
+            stage: "render",
+            path: "exports.0.background",
+            message: "kavio render does not yet support transparent final outputs.",
+            hint: "Use an opaque export background until alpha-capable encoding lands."
+        });
+    }
+    return null;
+}
+function toKavioError(error) {
+    if (isRenderError(error)) {
+        return error;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return renderError({ code: "RENDER_FAILED", stage: "render", message });
+}

package/dist/testing.d.ts

@@ -0,0 +1,24 @@
+import { type BrowserDriver, type BrowserFrameCapture, type BrowserFrameCaptureOptions, type BrowserOpenOptions } from "@kitsra/kavio-render-worker";
+import type { KavioDocument } from "@kitsra/kavio-schema";
+import type { FfmpegRunner } from "./ffmpeg-runner.js";
+/** In-memory BrowserDriver that returns deterministic PNG bytes without Chromium. */
+export declare class FakeBrowserDriver implements BrowserDriver {
+    opens: number;
+    closes: number;
+    renderedFrames: number[];
+    private viewport;
+    open(composition: KavioDocument, options?: BrowserOpenOptions): Promise<void>;
+    renderFrame(frame: number, options?: BrowserFrameCaptureOptions): Promise<BrowserFrameCapture>;
+    close(): Promise<void>;
+}
+export interface FakeFfmpegRunner extends FfmpegRunner {
+    /** Argument lists captured from each run() call. */
+    readonly calls: string[][];
+}
+export interface CreateFakeFfmpegRunnerOptions {
+    /** When true, run() rejects with FFMPEG_FAILED (for cleanup-on-failure tests). */
+    fail?: boolean;
+}
+/** FfmpegRunner that records args and writes a placeholder output file. */
+export declare function createFakeFfmpegRunner(options?: CreateFakeFfmpegRunnerOptions): FakeFfmpegRunner;
+//# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,0BAA0B,EAC/B,KAAK,kBAAkB,EAExB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1D,OAAO,KAAK,EAAE,YAAY,EAAqC,MAAM,oBAAoB,CAAC;AAI1F,qFAAqF;AACrF,qBAAa,iBAAkB,YAAW,aAAa;IACrD,KAAK,SAAK;IACV,MAAM,SAAK;IACX,cAAc,EAAE,MAAM,EAAE,CAAM;IAC9B,OAAO,CAAC,QAAQ,CAAgC;IAE1C,IAAI,CAAC,WAAW,EAAE,aAAa,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC;IAKjF,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,0BAA+B,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAiBlG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAI7B;AAED,MAAM,WAAW,gBAAiB,SAAQ,YAAY;IACpD,oDAAoD;IACpD,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,6BAA6B;IAC5C,kFAAkF;IAClF,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,2EAA2E;AAC3E,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,6BAAkC,GAAG,gBAAgB,CAoBpG"}

package/dist/testing.js

@@ -0,0 +1,55 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { createBrowserViewport, createPngFrameCapture } from "@kitsra/kavio-render-worker";
+import { renderError } from "./errors.js";
+const FAKE_PNG = new Uint8Array([137, 80, 78, 71, 13, 10, 26, 10]);
+/** In-memory BrowserDriver that returns deterministic PNG bytes without Chromium. */
+export class FakeBrowserDriver {
+    opens = 0;
+    closes = 0;
+    renderedFrames = [];
+    viewport = null;
+    async open(composition, options = {}) {
+        this.opens += 1;
+        this.viewport = options.viewport ?? createBrowserViewport(composition);
+    }
+    async renderFrame(frame, options = {}) {
+        if (this.viewport === null) {
+            throw renderError({
+                code: "RENDER_FRAME_FAILED",
+                stage: "render",
+                message: "FakeBrowserDriver.renderFrame called before open()."
+            });
+        }
+        this.renderedFrames.push(frame);
+        return createPngFrameCapture({
+            frame,
+            bytes: FAKE_PNG,
+            viewport: this.viewport,
+            omitBackground: options.omitBackground ?? true
+        });
+    }
+    async close() {
+        this.closes += 1;
+        this.viewport = null;
+    }
+}
+/** FfmpegRunner that records args and writes a placeholder output file. */
+export function createFakeFfmpegRunner(options = {}) {
+    const calls = [];
+    return {
+        calls,
+        async run(args, _runOptions) {
+            calls.push([...args]);
+            if (options.fail === true) {
+                throw renderError({ code: "FFMPEG_FAILED", stage: "ffmpeg", message: "Fake ffmpeg failure." });
+            }
+            const outputPath = args[args.length - 1];
+            if (outputPath !== undefined && outputPath.length > 0) {
+                await mkdir(dirname(outputPath), { recursive: true });
+                await writeFile(outputPath, FAKE_PNG);
+            }
+            return { code: 0, stderr: "" };
+        }
+    };
+}