@kheleshikhi/studio-agent 0.8.0 → 0.9.0

package/dist/render-jobs.js

@@ -0,0 +1,241 @@
+/**
+ * Long presentation renders as bounded daemon jobs.
+ *
+ * A 120 s / 30 fps render captures 3,600 frames at roughly 150 ms each: about
+ * nine minutes inside the daemon. A single loopback request that answers only
+ * after the last frame cannot carry that, because Node's fetch gives up on a
+ * response whose headers have not arrived after 300 s
+ * (`UND_ERR_HEADERS_TIMEOUT`), while the daemon kept rendering for nobody.
+ *
+ * So the CLI starts a job, polls its status and progress with short
+ * requests, and receives the result when the job completes. A job is
+ * bounded on both sides:
+ *
+ * - one job per render browser at a time (one by default; the daemon owns
+ *   `NERDBRO_RENDER_WORKERS` browsers, each with its own page and profile);
+ * - a job nobody has polled for `abandonAfterMs` is cancelled (the CLI
+ *   died, was killed, or lost the daemon), and so is a job that runs past
+ *   `maxRuntimeMs`;
+ * - `DELETE` cancels it; the renderer stops at its next frame;
+ * - a cancelled or failed job runs its cleanup (the frames and audio it
+ *   wrote) once the renderer has really stopped;
+ * - a finished job is forgotten `retainMs` after it ended.
+ *
+ * A failure keeps the stage the renderer last reported, so the caller can
+ * say where it failed.
+ */
+import { randomBytes } from "node:crypto";
+import { CliError } from "./types.js";
+export const RENDER_JOB_LIMITS = {
+    /** No status poll for this long: the client is gone, so the job is cancelled. */
+    abandonAfterMs: 60_000,
+    /** The documented ceiling is ~9 minutes of capture; this is generous headroom. */
+    maxRuntimeMs: 45 * 60_000,
+    /** A finished job's result is kept this long for its client to collect. */
+    retainMs: 10 * 60_000,
+};
+/** The error a renderer throws when its job's signal is aborted. */
+export function cancelledError(signal) {
+    const reason = typeof signal.reason === "string" ? signal.reason : "cancelled";
+    return new CliError(`The render was cancelled (${reason}).`, "VIDEO_RENDER_CANCELLED", 1, { reason });
+}
+/** Throw [cancelledError] when the job was cancelled; called between frames. */
+export function throwIfCancelled(signal) {
+    if (signal?.aborted)
+        throw cancelledError(signal);
+}
+export class RenderJobs {
+    options;
+    jobs = new Map();
+    limits;
+    /** Jobs that may run at once: one per render browser the daemon owns. */
+    maxConcurrent;
+    constructor(options = {}) {
+        this.options = options;
+        this.maxConcurrent = Math.max(1, Math.floor(options.maxConcurrent ?? 1));
+        this.limits = { ...RENDER_JOB_LIMITS, ...options.limits };
+    }
+    now() { return (this.options.clock ?? Date.now)(); }
+    /** Start one job; refused while another is still running or stopping. */
+    start(kind, runner, cleanup) {
+        const active = [...this.jobs.values()].filter((job) => job.state === "running" || job.state === "cancelling");
+        if (active.length >= this.maxConcurrent) {
+            throw new CliError("The daemon is already rendering; wait for that render or cancel it.", "VIDEO_RENDER_BUSY", 3, { job: active[0].id, active: active.length, max_concurrent: this.maxConcurrent });
+        }
+        const now = this.now();
+        const controller = new AbortController();
+        const job = {
+            id: `render_${randomBytes(9).toString("base64url")}`,
+            kind, state: "running", progress: { stage: "starting" },
+            startedAt: now, lastSeenAt: now, controller,
+        };
+        const progress = (value) => { if (job.state === "running" || job.state === "cancelling")
+            job.progress = { ...value }; };
+        job.done = (async () => {
+            try {
+                const result = await runner({ signal: controller.signal, progress });
+                throwIfCancelled(controller.signal);
+                job.result = result;
+                job.state = "completed";
+                job.progress = { ...job.progress, stage: "completed" };
+            }
+            catch (error) {
+                const failure = error instanceof CliError ? error : new CliError(String(error), "VIDEO_RENDER_FAILED");
+                const details = failure.details && typeof failure.details === "object" ? failure.details : undefined;
+                const stage = typeof details?.stage === "string" ? details.stage : job.progress.stage;
+                if (controller.signal.aborted) {
+                    const reason = typeof controller.signal.reason === "string" ? controller.signal.reason : "cancelled";
+                    job.state = "cancelled";
+                    job.error = { code: "VIDEO_RENDER_CANCELLED", message: `The render was cancelled (${reason}).`, stage, exitCode: 1, details: { reason } };
+                }
+                else {
+                    job.state = "failed";
+                    job.error = { code: failure.code, message: failure.message, stage, exitCode: failure.exitCode, details: failure.details };
+                }
+                if (cleanup)
+                    await cleanup().catch(() => undefined);
+            }
+            finally {
+                job.finishedAt = this.now();
+            }
+        })();
+        this.jobs.set(job.id, job);
+        return this.view(job);
+    }
+    find(id) {
+        const job = this.jobs.get(id);
+        if (!job)
+            throw new CliError("No such render job (it finished long ago, or the daemon restarted).", "VIDEO_RENDER_JOB_UNKNOWN", 1, { job: id });
+        return job;
+    }
+    /** A client's poll: the job's state, and its result once it completed. Keeps the job alive. */
+    status(id) {
+        const job = this.find(id);
+        job.lastSeenAt = this.now();
+        return { job: this.view(job), ...(job.state === "completed" ? { result: job.result } : {}) };
+    }
+    /** Ask a running job to stop; it becomes `cancelled` once the renderer has. */
+    cancel(id, reason = "cancelled by client") {
+        const job = this.find(id);
+        this.abort(job, reason);
+        return this.view(job);
+    }
+    abort(job, reason) {
+        if (job.state !== "running")
+            return;
+        job.state = "cancelling";
+        job.cancelReason = reason;
+        job.controller.abort(reason);
+    }
+    /** Cancel abandoned or overlong jobs and forget old finished ones. Run periodically. */
+    sweep() {
+        const now = this.now();
+        for (const job of [...this.jobs.values()]) {
+            if (job.state === "running" && now - job.lastSeenAt > this.limits.abandonAfterMs)
+                this.abort(job, "abandoned: no client polled it");
+            else if (job.state === "running" && now - job.startedAt > this.limits.maxRuntimeMs)
+                this.abort(job, "timed out");
+            else if (job.finishedAt !== undefined && now - job.finishedAt > this.limits.retainMs)
+                this.jobs.delete(job.id);
+        }
+    }
+    /** Resolves once the job's renderer and cleanup have finished (tests and shutdown). */
+    async settled(id) {
+        const job = this.find(id);
+        await job.done;
+        return this.view(job);
+    }
+    /** Cancel everything and wait (daemon shutdown). */
+    async stopAll(reason = "daemon stopping") {
+        const pending = [...this.jobs.values()];
+        for (const job of pending)
+            this.abort(job, reason);
+        await Promise.all(pending.map((job) => job.done));
+    }
+    view(job) {
+        return {
+            id: job.id, kind: job.kind, state: job.state, progress: { ...job.progress },
+            elapsed_ms: (job.finishedAt ?? this.now()) - job.startedAt,
+            ...(job.cancelReason ? { cancel_reason: job.cancelReason } : {}),
+            ...(job.error ? { error: job.error } : {}),
+        };
+    }
+}
+/**
+ * The daemon's job routes: `POST /render-jobs` {kind, request} starts one,
+ * `GET /render-jobs/<id>` polls it, `DELETE /render-jobs/<id>` cancels it.
+ * Returns null for any other route.
+ */
+export async function renderJobRoute(jobs, runners, cleanups, method, pathname, body) {
+    if (pathname === "/render-jobs" && method === "POST") {
+        const input = await body();
+        const kind = String(input.kind);
+        const runner = Object.hasOwn(runners, kind) ? runners[kind] : undefined;
+        if (!runner)
+            throw new CliError(`Unknown render job kind ${kind}.`, "VIDEO_RENDER_JOB_INVALID", 2);
+        const request = (input.request && typeof input.request === "object" ? input.request : {});
+        const cleanup = cleanups[kind];
+        const job = jobs.start(kind, (context) => runner(request, context), cleanup ? () => cleanup(request) : undefined);
+        return { status: 202, value: { ok: true, job } };
+    }
+    const match = /^\/render-jobs\/([A-Za-z0-9_-]{1,64})$/.exec(pathname);
+    if (!match)
+        return null;
+    if (method === "GET")
+        return { status: 200, value: { ok: true, ...jobs.status(match[1]) } };
+    if (method === "DELETE")
+        return { status: 200, value: { ok: true, job: jobs.cancel(match[1]) } };
+    return null;
+}
+function abortableSleep(milliseconds, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted) {
+            resolve();
+            return;
+        }
+        const timer = setTimeout(done, milliseconds);
+        function done() { clearTimeout(timer); signal?.removeEventListener("abort", done); resolve(); }
+        signal?.addEventListener("abort", done, { once: true });
+    });
+}
+/**
+ * Run one render as a daemon job: start, poll until it ends, return its
+ * result. Each request is short, so no request comes near any client or
+ * server timeout however long the render is. A daemon that predates jobs
+ * (`AGENT_LOCAL_RPC_NOT_FOUND`) is served by its single long request.
+ */
+export async function runRenderJob(rpc, kind, legacyRoute, request, options = {}) {
+    const sleep = options.sleep ?? abortableSleep;
+    let started;
+    try {
+        started = await rpc("/render-jobs", { method: "POST", body: JSON.stringify({ kind, request }) });
+    }
+    catch (error) {
+        if (error instanceof CliError && error.code === "AGENT_LOCAL_RPC_NOT_FOUND") {
+            return (await rpc(legacyRoute, { method: "POST", body: JSON.stringify(request) })).result;
+        }
+        throw error;
+    }
+    const id = started.job.id;
+    for (;;) {
+        if (options.signal?.aborted) {
+            await rpc(`/render-jobs/${id}`, { method: "DELETE" }).catch(() => undefined);
+            const reason = typeof options.signal.reason === "string" ? options.signal.reason : "interrupted";
+            throw new CliError(`The render was cancelled (${reason}).`, "VIDEO_RENDER_CANCELLED", 130, { reason, job: id, stage: started.job.progress.stage });
+        }
+        await sleep(options.pollMs ?? 1000, options.signal);
+        if (options.signal?.aborted)
+            continue;
+        const status = await rpc(`/render-jobs/${id}`, { method: "GET" });
+        started = status;
+        options.onProgress?.(status.job);
+        if (status.job.state === "completed")
+            return status.result;
+        if (status.job.state === "failed" || status.job.state === "cancelled") {
+            const error = status.job.error ?? { code: "VIDEO_RENDER_FAILED", message: "The render failed.", stage: status.job.progress.stage, exitCode: 1 };
+            const details = error.details && typeof error.details === "object" ? error.details : {};
+            throw new CliError(error.message, error.code, error.exitCode, { ...details, stage: error.stage, job: id });
+        }
+    }
+}
+//# sourceMappingURL=render-jobs.js.map

package/dist/render-jobs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-jobs.js","sourceRoot":"","sources":["../src/render-jobs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAsBtC,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,iFAAiF;IACjF,cAAc,EAAE,MAAM;IACtB,kFAAkF;IAClF,YAAY,EAAE,EAAE,GAAG,MAAM;IACzB,2EAA2E;IAC3E,QAAQ,EAAE,EAAE,GAAG,MAAM;CACtB,CAAC;AAiBF,oEAAoE;AACpE,MAAM,UAAU,cAAc,CAAC,MAAmB;IAChD,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC;IAC/E,OAAO,IAAI,QAAQ,CAAC,6BAA6B,MAAM,IAAI,EAAE,wBAAwB,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;AACxG,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,gBAAgB,CAAC,MAA+B;IAC9D,IAAI,MAAM,EAAE,OAAO;QAAE,MAAM,cAAc,CAAC,MAAM,CAAC,CAAC;AACpD,CAAC;AAED,MAAM,OAAO,UAAU;IAOQ;IANZ,IAAI,GAAG,IAAI,GAAG,EAAe,CAAC;IACtC,MAAM,CAA2B;IAE1C,yEAAyE;IAChE,aAAa,CAAS;IAE/B,YAA6B,UAAwG,EAAE;QAA1G,YAAO,GAAP,OAAO,CAAmG;QACrI,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,aAAa,IAAI,CAAC,CAAC,CAAC,CAAC;QACzE,IAAI,CAAC,MAAM,GAAG,EAAE,GAAG,iBAAiB,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAC5D,CAAC;IAEO,GAAG,KAAa,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IAEpE,yEAAyE;IACzE,KAAK,CAAC,IAAY,EAAE,MAAoB,EAAE,OAA6B;QACrE,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,KAAK,SAAS,IAAI,GAAG,CAAC,KAAK,KAAK,YAAY,CAAC,CAAC;QAC9G,IAAI,MAAM,CAAC,MAAM,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YACxC,MAAM,IAAI,QAAQ,CAAC,qEAAqE,EAAE,mBAAmB,EAAE,CAAC,EAC9G,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,CAAC,aAAa,EAAE,CAAC,CAAC;QACtF,CAAC;QACD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,GAAG,GAAG;YACV,EAAE,EAAE,UAAU,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE;YACpD,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE;YACvD,SAAS,EAAE,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,UAAU;SACrC,CAAC;QACT,MAAM,QAAQ,GAAG,CAAC,KAAqB,EAAE,EAAE,GAAG,IAAI,GAAG,CAAC,KAAK,KAAK,SAAS,IAAI,GAAG,CAAC,KAAK,KAAK,YAAY;YAAE,GAAG,CAAC,QAAQ,GAAG,EAAE,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;QACxI,GAAG,CAAC,IAAI,GAAG,CAAC,KAAK,IAAI,EAAE;YACrB,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;gBACrE,gBAAgB,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;gBACpC,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC;gBACpB,GAAG,CAAC,KAAK,GAAG,WAAW,CAAC;gBACxB,GAAG,CAAC,QAAQ,GAAG,EAAE,GAAG,GAAG,CAAC,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC;YACzD,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,OAAO,GAAG,KAAK,YAAY,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,qBAAqB,CAAC,CAAC;gBACvG,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,OAAkC,CAAC,CAAC,CAAC,SAAS,CAAC;gBAChI,MAAM,KAAK,GAAG,OAAO,OAAO,EAAE,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC;gBACtF,IAAI,UAAU,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;oBAC9B,MAAM,MAAM,GAAG,OAAO,UAAU,CAAC,MAAM,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC;oBACrG,GAAG,CAAC,KAAK,GAAG,WAAW,CAAC;oBACxB,GAAG,CAAC,KAAK,GAAG,EAAE,IAAI,EAAE,wBAAwB,EAAE,OAAO,EAAE,6BAA6B,MAAM,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,EAAE,CAAC;gBAC5I,CAAC;qBAAM,CAAC;oBACN,GAAG,CAAC,KAAK,GAAG,QAAQ,CAAC;oBACrB,GAAG,CAAC,KAAK,GAAG,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;gBAC5H,CAAC;gBACD,IAAI,OAAO;oBAAE,MAAM,OAAO,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;YACtD,CAAC;oBAAS,CAAC;gBACT,GAAG,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YAC9B,CAAC;QACH,CAAC,CAAC,EAAE,CAAC;QACL,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;QAC3B,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACxB,CAAC;IAEO,IAAI,CAAC,EAAU;QACrB,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC9B,IAAI,CAAC,GAAG;YAAE,MAAM,IAAI,QAAQ,CAAC,qEAAqE,EAAE,0BAA0B,EAAE,CAAC,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC,CAAC;QAChJ,OAAO,GAAG,CAAC;IACb,CAAC;IAED,+FAA+F;IAC/F,MAAM,CAAC,EAAU;QACf,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC1B,GAAG,CAAC,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC5B,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,KAAK,KAAK,WAAW,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;IAC/F,CAAC;IAED,+EAA+E;IAC/E,MAAM,CAAC,EAAU,EAAE,MAAM,GAAG,qBAAqB;QAC/C,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC1B,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QACxB,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACxB,CAAC;IAEO,KAAK,CAAC,GAAQ,EAAE,MAAc;QACpC,IAAI,GAAG,CAAC,KAAK,KAAK,SAAS;YAAE,OAAO;QACpC,GAAG,CAAC,KAAK,GAAG,YAAY,CAAC;QACzB,GAAG,CAAC,YAAY,GAAG,MAAM,CAAC;QAC1B,GAAG,CAAC,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IAC/B,CAAC;IAED,wFAAwF;IACxF,KAAK;QACH,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,KAAK,MAAM,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC;YAC1C,IAAI,GAAG,CAAC,KAAK,KAAK,SAAS,IAAI,GAAG,GAAG,GAAG,CAAC,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,cAAc;gBAAE,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,gCAAgC,CAAC,CAAC;iBAC/H,IAAI,GAAG,CAAC,KAAK,KAAK,SAAS,IAAI,GAAG,GAAG,GAAG,CAAC,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,YAAY;gBAAE,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;iBAC5G,IAAI,GAAG,CAAC,UAAU,KAAK,SAAS,IAAI,GAAG,GAAG,GAAG,CAAC,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ;gBAAE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACjH,CAAC;IACH,CAAC;IAED,uFAAuF;IACvF,KAAK,CAAC,OAAO,CAAC,EAAU;QACtB,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC1B,MAAM,GAAG,CAAC,IAAI,CAAC;QACf,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACxB,CAAC;IAED,oDAAoD;IACpD,KAAK,CAAC,OAAO,CAAC,MAAM,GAAG,iBAAiB;QACtC,MAAM,OAAO,GAAG,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;QACxC,KAAK,MAAM,GAAG,IAAI,OAAO;YAAE,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QACnD,MAAM,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;IACpD,CAAC;IAEO,IAAI,CAAC,GAAQ;QACnB,OAAO;YACL,EAAE,EAAE,GAAG,CAAC,EAAE,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,GAAG,GAAG,CAAC,QAAQ,EAAE;YAC3E,UAAU,EAAE,CAAC,GAAG,CAAC,UAAU,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,GAAG,CAAC,SAAS;YAC1D,GAAG,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,GAAG,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAChE,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC3C,CAAC;IACJ,CAAC;CACF;AAKD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,IAAgB,EAAE,OAAyB,EAAE,QAA2B,EACxE,MAAc,EAAE,QAAgB,EAAE,IAA4C;IAE9E,IAAI,QAAQ,KAAK,cAAc,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;QACrD,MAAM,KAAK,GAAG,MAAM,IAAI,EAAE,CAAC;QAC3B,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAChC,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QACxE,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,QAAQ,CAAC,2BAA2B,IAAI,GAAG,EAAE,0BAA0B,EAAE,CAAC,CAAC,CAAC;QACnG,MAAM,OAAO,GAAG,CAAC,KAAK,CAAC,OAAO,IAAI,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAA4B,CAAC;QACrH,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC/B,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QAClH,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC;IACnD,CAAC;IACD,MAAM,KAAK,GAAG,wCAAwC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACtE,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,IAAI,MAAM,KAAK,KAAK;QAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;IAC5F,IAAI,MAAM,KAAK,QAAQ;QAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;IACjG,OAAO,IAAI,CAAC;AACd,CAAC;AAYD,SAAS,cAAc,CAAC,YAAoB,EAAE,MAAoB;IAChE,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;YAAC,OAAO,EAAE,CAAC;YAAC,OAAO;QAAC,CAAC;QAC3C,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;QAC7C,SAAS,IAAI,KAAK,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QAC/F,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1D,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAI,GAAQ,EAAE,IAAY,EAAE,WAAmB,EAAE,OAAgC,EACjH,UAAkC,EAAE;IACpC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,cAAc,CAAC;IAC9C,IAAI,OAA+B,CAAC;IACpC,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,GAAG,CAAyB,cAAc,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC;IAC3H,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,QAAQ,IAAI,KAAK,CAAC,IAAI,KAAK,2BAA2B,EAAE,CAAC;YAC5E,OAAO,CAAC,MAAM,GAAG,CAAgB,WAAW,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;QAC3G,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;IACD,MAAM,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;IAC1B,SAAS,CAAC;QACR,IAAI,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;YAC5B,MAAM,GAAG,CAAC,gBAAgB,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;YAC7E,MAAM,MAAM,GAAG,OAAO,OAAO,CAAC,MAAM,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,aAAa,CAAC;YACjG,MAAM,IAAI,QAAQ,CAAC,6BAA6B,MAAM,IAAI,EAAE,wBAAwB,EAAE,GAAG,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;QACrJ,CAAC;QACD,MAAM,KAAK,CAAC,OAAO,CAAC,MAAM,IAAI,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;QACpD,IAAI,OAAO,CAAC,MAAM,EAAE,OAAO;YAAE,SAAS;QACtC,MAAM,MAAM,GAAG,MAAM,GAAG,CAAqC,gBAAgB,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;QACtG,OAAO,GAAG,MAAM,CAAC;QACjB,OAAO,CAAC,UAAU,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,MAAM,CAAC,GAAG,CAAC,KAAK,KAAK,WAAW;YAAE,OAAO,MAAM,CAAC,MAAW,CAAC;QAChE,IAAI,MAAM,CAAC,GAAG,CAAC,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,GAAG,CAAC,KAAK,KAAK,WAAW,EAAE,CAAC;YACtE,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,IAAI,EAAE,qBAAqB,EAAE,OAAO,EAAE,oBAAoB,EAAE,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;YAChJ,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,IAAI,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,OAAkC,CAAC,CAAC,CAAC,EAAE,CAAC;YACnH,MAAM,IAAI,QAAQ,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,QAAQ,EAAE,EAAE,GAAG,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC,CAAC;QAC7G,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/shot-provenance.d.ts

@@ -0,0 +1,66 @@
+export type Api = <T>(method: string, route: string, body?: unknown) => Promise<T>;
+export declare const DEPENDENCY_SCHEMA = "kheleshikhi.scene-dependencies.v1";
+export type DependencyRecord = {
+    schema: string;
+    compilerVersion?: string;
+    componentHeader?: string;
+    components?: Array<{
+        id: string;
+        definitionHash: string | null;
+    }>;
+    behaviors?: Array<{
+        id: string;
+        definitionHash: string | null;
+    }>;
+    audio?: Array<{
+        id: string;
+        sha256: string | null;
+    }>;
+    digest: string;
+};
+export type SceneIdentity = {
+    /** Experience Scene id (manifest id) or "main" for a Studio Scene shot. */
+    scene: string;
+    kind: "studio_source" | "approved_revision" | "gallery_package";
+    asset?: string | null;
+    revision?: string | null;
+    source_hash?: string | null;
+    manifest_path?: string | null;
+    package?: string | null;
+    package_sha256?: string | null;
+    dependencies_digest: string | null;
+    dependencies?: DependencyRecord | null;
+    note?: string;
+};
+export type ExperienceProvenance = {
+    schema: "kheleshikhi.experience-scene-provenance.v1";
+    preview_source_hash: string | null;
+    scenes: Record<string, SceneIdentity>;
+    /** Audio stable id -> sha256 of its exact bytes. */
+    audio: Record<string, string>;
+    digest: string;
+};
+export declare function canonicalJson(value: unknown): string;
+export declare function digestOf(value: unknown): string;
+/** A dependency record from a compile response, or null when it has none. */
+export declare function dependencyRecord(compileResult: unknown): DependencyRecord | null;
+/** Compile a Studio source and return its dependency record. */
+export declare function compileDependencies(api: Api, asset: string, source: unknown): Promise<{
+    compiled: boolean;
+    source_hash: string | null;
+    dependencies: DependencyRecord | null;
+}>;
+/**
+ * One approved Scene revision's identity: the asset's approved source (when
+ * it is the asset's current source, i.e. no newer draft hides it) compiled
+ * for its dependency record. A draft over the revision leaves the record
+ * unknown, which is said, never guessed.
+ */
+export declare function approvedSceneIdentity(api: Api, scene: string, asset: string, revision: string, manifestPath: string | null): Promise<SceneIdentity>;
+/**
+ * Every Scene and sound an Experience document resolves to right now, from
+ * the server's draft preview (the same resolution the player uses).
+ */
+export declare function experienceProvenance(api: Api, document: unknown, options?: {
+    dependencies?: boolean;
+}): Promise<ExperienceProvenance>;

package/dist/shot-provenance.js

@@ -0,0 +1,114 @@
+/**
+ * What a render was made from, exactly enough to key a cache on.
+ *
+ * A Scene render is made from one Scene Source (its source hash) compiled
+ * against exact Component, Behavior and Audio definitions: the server's
+ * compile response carries that record (`artifacts.dependencies`, schema
+ * `kheleshikhi.scene-dependencies.v1`, with its own digest). An Experience
+ * render is made from the Experience Source and, for each of its Scenes, the
+ * approved revision the draft preview resolved (asset, revision, stored
+ * manifest) plus that revision's dependency record when it can be read, and
+ * from the exact bytes of every sound it names.
+ *
+ * Nothing here decides validity on its own; the episode runner hashes these
+ * facts into a shot key. Library or project membership is never an input.
+ */
+import { createHash } from "node:crypto";
+export const DEPENDENCY_SCHEMA = "kheleshikhi.scene-dependencies.v1";
+export function canonicalJson(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    const record = value;
+    return `{${Object.keys(record).filter((key) => record[key] !== undefined).sort()
+        .map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(",")}}`;
+}
+export function digestOf(value) {
+    return createHash("sha256").update(canonicalJson(value)).digest("hex");
+}
+/** A dependency record from a compile response, or null when it has none. */
+export function dependencyRecord(compileResult) {
+    const artifacts = compileResult?.artifacts;
+    const record = artifacts?.dependencies;
+    if (!record || record.schema !== DEPENDENCY_SCHEMA || typeof record.digest !== "string")
+        return null;
+    return record;
+}
+/** Compile a Studio source and return its dependency record. */
+export async function compileDependencies(api, asset, source) {
+    const result = await api("POST", `/v1/agent/studio/${encodeURIComponent(asset)}/compile`, { source });
+    return {
+        compiled: result.compiled === true,
+        source_hash: typeof result.source_hash === "string" ? result.source_hash : null,
+        dependencies: dependencyRecord(result),
+    };
+}
+/**
+ * One approved Scene revision's identity: the asset's approved source (when
+ * it is the asset's current source, i.e. no newer draft hides it) compiled
+ * for its dependency record. A draft over the revision leaves the record
+ * unknown, which is said, never guessed.
+ */
+export async function approvedSceneIdentity(api, scene, asset, revision, manifestPath) {
+    const identity = { scene, kind: "approved_revision", asset, revision, manifest_path: manifestPath, dependencies_digest: null };
+    try {
+        const loaded = await api("GET", `/v1/agent/studio/${encodeURIComponent(asset)}`);
+        if (loaded.source_origin === "approved" && loaded.base_revision_public_id === revision && loaded.source) {
+            const compiled = await compileDependencies(api, asset, loaded.source);
+            identity.source_hash = typeof loaded.source_hash === "string" ? loaded.source_hash : compiled.source_hash;
+            identity.dependencies = compiled.dependencies;
+            identity.dependencies_digest = compiled.dependencies?.digest ?? null;
+        }
+        else {
+            identity.note = "A newer draft or revision hides this revision's source; keyed by revision and stored manifest only.";
+        }
+    }
+    catch (error) {
+        identity.note = `Source not readable: ${error instanceof Error ? error.message : String(error)}`.slice(0, 300);
+    }
+    return identity;
+}
+/**
+ * Every Scene and sound an Experience document resolves to right now, from
+ * the server's draft preview (the same resolution the player uses).
+ */
+export async function experienceProvenance(api, document, options = {}) {
+    const preview = await api("POST", "/v1/agent/authoring/experience/preview", { document });
+    const scenes = {};
+    for (const [scene, raw] of Object.entries((preview.scenes ?? {}))) {
+        if (raw.kind === "media") {
+            const origin = (raw.provenance ?? {});
+            const asset = typeof origin.asset === "string" ? origin.asset : null;
+            const revision = typeof origin.revision === "string" ? origin.revision : null;
+            const manifestPath = typeof raw.manifestPath === "string" ? raw.manifestPath : null;
+            if (asset && revision && options.dependencies !== false) {
+                scenes[scene] = await approvedSceneIdentity(api, scene, asset, revision, manifestPath);
+            }
+            else {
+                scenes[scene] = { scene, kind: "approved_revision", asset, revision, manifest_path: manifestPath,
+                    source_hash: typeof origin.sourceHash === "string" ? origin.sourceHash : null, dependencies_digest: null };
+            }
+        }
+        else {
+            scenes[scene] = { scene, kind: "gallery_package", package: raw.package ?? null, package_sha256: raw.packageSha256 ?? null,
+                dependencies_digest: null, note: "An approved Gallery package: its sha256 is its identity." };
+        }
+    }
+    const audio = {};
+    for (const entry of Object.values((preview.audio ?? {}))) {
+        if (typeof entry.audio === "string" && typeof entry.sha256 === "string")
+            audio[entry.audio] = entry.sha256;
+    }
+    const body = { preview_source_hash: typeof preview.sourceHash === "string" ? preview.sourceHash : null, scenes, audio };
+    return {
+        schema: "kheleshikhi.experience-scene-provenance.v1",
+        ...body,
+        digest: digestOf({
+            preview_source_hash: body.preview_source_hash,
+            scenes: Object.fromEntries(Object.entries(scenes).map(([key, value]) => [key, { ...value, dependencies: undefined, note: undefined }])),
+            audio,
+        }),
+    };
+}
+//# sourceMappingURL=shot-provenance.js.map

package/dist/shot-provenance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shot-provenance.js","sourceRoot":"","sources":["../src/shot-provenance.ts"],"names":[],"mappings":"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"}

package/dist/state.js

@@ -5,25 +5,29 @@ import path from "node:path";
 import { CliError } from "./types.js";
 export const DEFAULT_API_ORIGIN = "https://api.nerdbro.org";
 export function stateDirectory(env = process.env, platform = process.platform) {
+    // Paths follow the target platform's convention, wherever this runs.
+    const join = platform === "win32" ? path.win32.join : path.posix.join;
     if (env.NERDBRO_AGENT_STATE_DIR)
         return path.resolve(env.NERDBRO_AGENT_STATE_DIR);
     if (platform === "win32") {
-        return path.join(env.LOCALAPPDATA || path.join(os.homedir(), "AppData", "Local"), "NerdBro", "Studio Agent");
+        return join(env.LOCALAPPDATA || join(os.homedir(), "AppData", "Local"), "NerdBro", "Studio Agent");
     }
     if (platform === "darwin") {
-        return path.join(os.homedir(), "Library", "Application Support", "NerdBro", "Studio Agent");
+        return join(os.homedir(), "Library", "Application Support", "NerdBro", "Studio Agent");
     }
-    return path.join(env.XDG_STATE_HOME || path.join(os.homedir(), ".local", "state"), "nerdbro-studio-agent");
+    return join(env.XDG_STATE_HOME || join(os.homedir(), ".local", "state"), "nerdbro-studio-agent");
 }
 export function cacheDirectory(env = process.env, platform = process.platform) {
+    // Paths follow the target platform's convention, wherever this runs.
+    const join = platform === "win32" ? path.win32.join : path.posix.join;
     if (env.NERDBRO_AGENT_CACHE_DIR)
         return path.resolve(env.NERDBRO_AGENT_CACHE_DIR);
     if (platform === "win32") {
-        return path.join(env.LOCALAPPDATA || path.join(os.homedir(), "AppData", "Local"), "NerdBro", "Studio Agent", "Cache");
+        return join(env.LOCALAPPDATA || join(os.homedir(), "AppData", "Local"), "NerdBro", "Studio Agent", "Cache");
     }
     if (platform === "darwin")
-        return path.join(os.homedir(), "Library", "Caches", "NerdBro Studio Agent");
-    return path.join(env.XDG_CACHE_HOME || path.join(os.homedir(), ".cache"), "nerdbro-studio-agent");
+        return join(os.homedir(), "Library", "Caches", "NerdBro Studio Agent");
+    return join(env.XDG_CACHE_HOME || join(os.homedir(), ".cache"), "nerdbro-studio-agent");
 }
 function daemonPath() {
     return path.join(stateDirectory(), "daemon.json");

package/dist/state.js.map

@@ -1 +1 @@
-{"version":3,"file":"state.js","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"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"}

package/dist/video.d.ts

@@ -87,6 +87,10 @@ export type Encoder = {
  * `NERDBRO_FFPROBE`) or `ffmpeg`/`ffprobe` on PATH. It is never downloaded.
  */
 export declare function findEncoder(environment?: NodeJS.ProcessEnv): Promise<Encoder>;
+/** Audio is mixed and encoded at 48 kHz stereo. */
+export declare const MIX_SAMPLE_RATE = 48000;
+/** The exact audio length of `frames` video frames, in 48 kHz samples. */
+export declare function sampleCount(frames: number, fps: number): number;
 /**
  * The FFmpeg arguments for one recipe: H.264 High, yuv420p, CFR, AAC audio,
  * faststart. Frames are already the output size (proved per PNG), so the
@@ -149,11 +153,18 @@ export declare function audioKey(event: {
 export declare function audioSegments(events: RenderAudioEvent[], endMs: number, startMs?: number): AudioSegment[];
 /**
  * FFmpeg arguments that mix [segments] from their canonical files into one
- * 48 kHz stereo PCM track exactly `durationMs` long. Each segment is its own
- * input (a looping sound is an endlessly looped input), trimmed from its
- * offset to its length, scaled by its volume and delayed to its start;
- * the segments are summed without normalisation, so a sound is as loud as
- * the runtime would play it. Returns null when nothing sounded.
+ * 48 kHz stereo PCM track of exactly `round(durationMs * 48)` samples. Each
+ * segment is its own input (a looping sound is an endlessly looped input),
+ * trimmed from its offset to its length, scaled by its volume and delayed
+ * to its start; the segments are summed without normalisation, so a sound
+ * is as loud as the runtime would play it. Returns null when nothing sounded.
+ *
+ * Everything is counted in samples, not timestamps: a looped AAC input
+ * leaves a 1,024-sample timestamp gap at every wrap (its priming is skipped
+ * again), so a timestamp trim came out one AAC frame short per loop. Each
+ * input is renumbered by decoded sample (`asetpts=N/SR/TB`), which makes a
+ * loop gapless at the asset's own decoded length, and the mix is padded and
+ * trimmed to the exact sample count.
  */
 export declare function mixArguments(segments: AudioSegment[], files: Map<string, string>, durationMs: number, output: string): string[] | null;
 export declare function mix(encoder: Encoder, segments: AudioSegment[], files: Map<string, string>, durationMs: number, output: string): Promise<string[] | null>;
@@ -162,3 +173,25 @@ export declare function audioLevel(encoder: Encoder, file: string): Promise<{
     mean_db: number | null;
     max_db: number | null;
 }>;
+export type PhaseSummary = {
+    count: number;
+    total_ms: number;
+    per_frame_ms: number;
+    p50_ms: number;
+    p95_ms: number;
+    max_ms: number;
+};
+/**
+ * Where capture time goes, per phase, across a render's frames: the frame
+ * loop records each phase's wall time and render.json reports totals,
+ * per-frame means and percentiles. Diagnostic only; it never affects a frame.
+ */
+export declare class PhaseTimes {
+    private readonly samples;
+    /** Only the frame loop records; setup and audio collection do not. */
+    active: boolean;
+    add(phase: string, milliseconds: number): void;
+    /** Time `body` as `phase`. */
+    time<T>(phase: string, body: () => Promise<T>): Promise<T>;
+    summary(frames: number): Record<string, PhaseSummary>;
+}