@kheleshikhi/studio-agent 0.6.1 → 0.9.0

package/dist/browser.js

@@ -1,10 +1,12 @@
 import { mkdir, rm, writeFile } from "node:fs/promises";
+import { actionsBetween, audioKey, frameCount, frameTime, PhaseTimes, pngSize, sha256 } from "./video.js";
 import path from "node:path";
 import { chromium } from "playwright";
 import { cacheDirectory } from "./state.js";
+import { throwIfCancelled } from "./render-jobs.js";
 import { CliError } from "./types.js";
 import { assertCurrentObservation, ObservationSampler, observationSettings } from "./observation.js";
-import { isDriveCommand, matchesObservation } from "./scenario.js";
+import { evidenceMode, isDriveCommand, matchesObservation, isExperienceCommand, matchesExperienceObservation, observedValue, stepSummary } from "./scenario.js";
 export function studioBrowserLaunchOptions(headless) {
     return {
         headless,
@@ -48,6 +50,25 @@ export async function waitForCapturePaint(page) {
         throw new CliError("Studio did not paint after runtime readiness.", "STUDIO_CAPTURE_PAINT_TIMEOUT");
     }
 }
+/**
+ * One PNG of the viewport `clip` at device scale 1, through the page's
+ * existing CDP session with Chrome's fast PNG encoder (`optimizeForSpeed`:
+ * the same pixels, lighter compression). Playwright's screenshot is the
+ * fallback.
+ */
+async function captureViewportPng(page, clip) {
+    const session = viewportSessions.get(page);
+    if (session) {
+        try {
+            const { data } = await session.send("Page.captureScreenshot", {
+                format: "png", optimizeForSpeed: true, captureBeyondViewport: false, clip: { ...clip, scale: 1 },
+            });
+            return Buffer.from(data, "base64");
+        }
+        catch { /* fall back to Playwright */ }
+    }
+    return page.screenshot({ type: "png", scale: "css", clip });
+}
 async function waitForVisualReady(page, timeoutMs, stage) {
     try {
         await page.waitForFunction(() => {
@@ -76,7 +97,7 @@ async function waitForVisualReady(page, timeoutMs, stage) {
     }
 }
 const viewportSessions = new WeakMap();
-export async function applyCssViewport(page, dimensions) {
+export async function applyCssViewport(page, dimensions, deviceScaleFactor = 0) {
     const nativeScreen = await page.evaluate(() => ({
         width: window.screen.width,
         height: window.screen.height,
@@ -92,11 +113,12 @@ export async function applyCssViewport(page, dimensions) {
     }
     // The override belongs to its CDP session. Detaching here silently restores
     // the original viewport on Chromium, so keep the session until page close.
-    // deviceScaleFactor 0 leaves the host display's native scale intact.
+    // deviceScaleFactor 0 leaves the host display's native scale intact; a
+    // presentation render asks for 1, so one CSS pixel is one output pixel.
     await session.send("Emulation.setDeviceMetricsOverride", {
         width: dimensions.width,
         height: dimensions.height,
-        deviceScaleFactor: 0,
+        deviceScaleFactor,
         mobile: false,
         screenWidth: nativeScreen.width,
         screenHeight: nativeScreen.height,
@@ -249,17 +271,35 @@ export class BrowserCredentialManager {
         return this.credential;
     }
 }
+async function notify(listener, report) {
+    if (!listener)
+        return;
+    try {
+        await listener(report);
+    }
+    catch { /* Presence is supplementary. */ }
+}
+function driveOutcome(kind, steps, results, summaries, final) {
+    const observations = [...results.map((item) => (item.observation ?? item.actual)), final];
+    return {
+        evidence_mode: evidenceMode(kind, steps, observations),
+        step_summaries: summaries,
+    };
+}
 const LIBRARY_WORKSPACES = new Set(["experiences", "audio", "components", "behaviors"]);
 export class StudioBrowser {
     api;
+    profileName;
     context;
     page;
     headless = false;
     browserEngine = "not-started";
     apiOrigin;
     credentials;
-    constructor(api) {
+    /** `profileName` keeps a render worker's persistent profile apart from the main browser's. */
+    constructor(api, profileName = "browser-profile") {
         this.api = api;
+        this.profileName = profileName;
         this.apiOrigin = new URL(api.origin).origin;
         this.credentials = new BrowserCredentialManager(api);
     }
@@ -267,7 +307,7 @@ export class StudioBrowser {
         if (this.context)
             return;
         this.headless = headless;
-        const profile = path.join(cacheDirectory(), "browser-profile");
+        const profile = path.join(cacheDirectory(), this.profileName);
         await mkdir(profile, { recursive: true, mode: 0o700 });
         const attempts = [
             { channel: "chrome", name: "Google Chrome" },
@@ -364,7 +404,7 @@ export class StudioBrowser {
             throw new CliError(`Unknown Studio view: ${view}`, "STUDIO_VIEW_INVALID", 2);
         const { page, webOrigin } = await this.authenticatedPage();
         const dimensions = cssViewport(request.viewport || "desktop");
-        await applyCssViewport(page, dimensions);
+        await applyCssViewport(page, dimensions, request.deviceScaleFactor ?? 0);
         const consoleErrors = [];
         const pageErrors = [];
         const requestFailures = [];
@@ -397,9 +437,10 @@ export class StudioBrowser {
                     method: response.request().method(),
                 });
         });
+        const present = request.present ? { studio_present: "1" } : {};
         const target = request.library
-            ? new URL(`/maker/interactive/studio?${new URLSearchParams({ workspace: request.library.workspace, selection: request.library.selection, studio_observation: "1" })}`, webOrigin)
-            : new URL(`/maker/interactive/studio/${encodeURIComponent(request.asset)}?${new URLSearchParams({ ...VIEW_QUERY[view], studio_observation: "1", ...(request.drive ? { studio_drive: "1" } : {}) })}`, webOrigin);
+            ? new URL(`/maker/interactive/studio?${new URLSearchParams({ workspace: request.library.workspace, selection: request.library.selection, studio_observation: "1", ...(request.drive ? { studio_drive: "1" } : {}), ...present })}`, webOrigin)
+            : new URL(`/maker/interactive/studio/${encodeURIComponent(request.asset)}?${new URLSearchParams({ ...VIEW_QUERY[view], studio_observation: "1", ...(request.drive ? { studio_drive: "1" } : {}), ...present })}`, webOrigin);
         await page.goto(target.toString(), { waitUntil: "domcontentloaded", timeout: request.timeoutMs || 30_000 });
         const apiUnauthorized = httpErrors.some((item) => {
             if (item.status !== 401)
@@ -517,6 +558,34 @@ export class StudioBrowser {
                 });
             }
         }
+        // An unsaved candidate is mounted next and waited for by its own hash;
+        // the saved revision need not (and, mid-iteration, often cannot) mount.
+        if (request.drive && request.library?.workspace === "experiences" && !request.awaitsCandidate) {
+            const deadline = Date.now() + (request.timeoutMs || 30_000);
+            while (Date.now() < deadline) {
+                observation = await page.evaluate(() => {
+                    const raw = document.getElementById("kheleshikhi-studio-runtime-observation")?.textContent;
+                    if (!raw)
+                        return null;
+                    try {
+                        return JSON.parse(raw);
+                    }
+                    catch {
+                        return null;
+                    }
+                });
+                if (observation?.observation_scope === "live_experience_preview" &&
+                    observation.mounted === true && typeof observation.active_state === "string")
+                    break;
+                await page.waitForTimeout(125);
+            }
+            if (observation?.mounted !== true || typeof observation.active_state !== "string") {
+                throw new CliError("Experience Preview did not become ready for capture.", "EXPERIENCE_PREVIEW_TIMEOUT", 1, {
+                    elapsed_ms: request.timeoutMs || 30_000,
+                    observed: observation,
+                });
+            }
+        }
         // Runtime observation is emitted before Chromium necessarily composites
         // the first visible frame. Wait for fonts and two post-ready paint frames
         // rather than a time-based guess that varies by machine.
@@ -612,6 +681,7 @@ export class StudioBrowser {
             throw new CliError("Candidate preview reported a runtime error.", "STUDIO_RUNTIME_ERROR", 1, ready);
         }
         const results = [];
+        const summaries = [];
         const observation = async () => page.evaluate(() => {
             const raw = document.getElementById("kheleshikhi-studio-runtime-observation")?.textContent;
             return raw ? JSON.parse(raw) : {};
@@ -630,7 +700,7 @@ export class StudioBrowser {
                         node.hidden = true;
                         document.body.append(node);
                     }
-                    node.textContent = JSON.stringify({ id, op: step.op, target: step.target, value: step.value });
+                    node.textContent = JSON.stringify({ id, op: step.op, target: step.target, value: step.value, setup: step.setup });
                 }, { id, step });
                 const result = await page.waitForFunction((expected) => {
                     const raw = document.getElementById("kheleshikhi-studio-drive-result")?.textContent;
@@ -642,9 +712,24 @@ export class StudioBrowser {
                     const lastObserved = await page.evaluate(() => document.getElementById("kheleshikhi-studio-drive-result")?.textContent?.slice(0, 500) || null);
                     throw new CliError("Studio drive timed out waiting for command acknowledgement.", "STUDIO_DRIVE_TIMEOUT", 1, { stage: "command_ack", step: index, operation: step.op, elapsed_ms: step.timeoutMs || 10_000, last_observed: lastObserved });
                 });
+                summaries.push(stepSummary(step, result.ok === true));
+                await notify(request.onStep, { index, summary: summaries.at(-1), observation: result.observation });
                 if (result.ok !== true)
-                    throw new CliError(String(result.error || "Semantic command failed."), "STUDIO_DRIVE_COMMAND_FAILED", 1, { index, step, result });
+                    throw new CliError(String(result.error || "Semantic command failed."), "STUDIO_DRIVE_COMMAND_FAILED", 1, { index, step, result, step_summaries: summaries });
                 results.push({ index, op: step.op, observation: result.observation });
+                if (step.op === "restart") {
+                    // A restart remounts the production renderer; later steps act on the
+                    // fresh runtime, not on the one being torn down.
+                    await page.waitForFunction(() => {
+                        const raw = document.getElementById("kheleshikhi-studio-runtime-observation")?.textContent;
+                        if (!raw)
+                            return false;
+                        const value = JSON.parse(raw);
+                        return value.runtime_ready === true && value.visual_ready === true;
+                    }, undefined, { timeout: step.timeoutMs || 15_000 }).catch(() => {
+                        throw new CliError("The runtime did not become ready after restart.", "STUDIO_DRIVE_TIMEOUT", 1, { stage: "restart", step: index });
+                    });
+                }
                 continue;
             }
             if (step.op === "capture") {
@@ -653,7 +738,10 @@ export class StudioBrowser {
                 await waitForVisualReady(page, step.timeoutMs || 10_000, `scenario_capture_${index}`);
                 await waitForCapturePaint(page);
                 await page.screenshot({ path: output, scale: "device" });
-                results.push({ index, op: step.op, path: output, observation: await observation() });
+                const captured = await observation();
+                results.push({ index, op: step.op, path: output, observation: captured });
+                summaries.push(stepSummary(step, true));
+                await notify(request.onStep, { index, summary: summaries.at(-1), observation: captured });
                 continue;
             }
             let current = await observation();
@@ -664,12 +752,446 @@ export class StudioBrowser {
                     current = await observation();
                 }
             }
+            summaries.push(stepSummary(step, matchesObservation(current, step), observedValue(current, step.path || "")));
+            await notify(request.onStep, { index, summary: summaries.at(-1), observation: current });
             if (!matchesObservation(current, step)) {
-                throw new CliError(`Scenario ${step.op} failed at step ${index}: ${step.path}.`, step.op === "wait" ? "STUDIO_DRIVE_TIMEOUT" : "STUDIO_DRIVE_ASSERTION_FAILED", 1, { stage: step.op === "wait" ? "scenario_wait" : "assertion", step: index, operation: step.op, path: step.path, expected: "equals" in step ? step.equals : undefined, last_observed: current, elapsed_ms: step.timeoutMs || 10_000 });
+                throw new CliError(`Scenario ${step.op} failed at step ${index}: ${step.path}.`, step.op === "wait" ? "STUDIO_DRIVE_TIMEOUT" : "STUDIO_DRIVE_ASSERTION_FAILED", 1, { stage: step.op === "wait" ? "scenario_wait" : "assertion", step: index, operation: step.op, path: step.path, expected: "equals" in step ? step.equals : undefined, last_observed: current, elapsed_ms: step.timeoutMs || 10_000, step_summaries: summaries });
             }
             results.push({ index, op: step.op, path: step.path, actual: current });
         }
-        return { source_hash: request.candidateHash, initial: first, steps: results, final: await observation() };
+        const final = await observation();
+        return { source_hash: request.candidateHash, initial: first, steps: results, final,
+            ...driveOutcome("scene", request.scenario.steps, results, summaries, final) };
+    }
+    async driveExperience(request) {
+        if (request.library?.workspace !== "experiences")
+            throw new CliError("Experience drive requires the experiences workspace.", "STUDIO_VIEW_INVALID", 2);
+        const initial = await this.capture({ ...request, drive: true, observation: false,
+            awaitsCandidate: Boolean(request.candidateHash) });
+        const page = this.page;
+        if (!page)
+            throw new CliError("Studio browser is unavailable.", "AGENT_BROWSER_NOT_READY");
+        const observation = async () => page.evaluate(() => {
+            const raw = document.getElementById("kheleshikhi-studio-runtime-observation")?.textContent;
+            return raw ? JSON.parse(raw) : {};
+        });
+        if (request.candidateHash) {
+            // Mount the exact unsaved local Source in this page's Draft Preview.
+            // The page answers with the server's canonical hash of what mounted.
+            await page.evaluate((payload) => {
+                let node = document.getElementById("kheleshikhi-studio-drive-command");
+                if (!node) {
+                    node = document.createElement("div");
+                    node.id = "kheleshikhi-studio-drive-command";
+                    node.hidden = true;
+                    document.body.append(node);
+                }
+                node.textContent = JSON.stringify(payload);
+            }, { id: "candidate", op: "loadCandidate", source: request.candidate, candidateHash: request.candidateHash });
+            const reply = await page.waitForFunction(() => {
+                const raw = document.getElementById("kheleshikhi-studio-drive-result")?.textContent;
+                if (!raw)
+                    return false;
+                const value = JSON.parse(raw);
+                return value.id === "candidate" ? value : false;
+            }, undefined, { timeout: Math.max(request.timeoutMs || 30_000, 50_000) })
+                .then((handle) => handle.jsonValue())
+                .catch(() => { throw new CliError("The unsaved Experience did not mount.", "EXPERIENCE_PREVIEW_TIMEOUT", 1); });
+            if (reply.ok !== true)
+                throw new CliError(String(reply.error || "The unsaved Experience was refused."), "EXPERIENCE_SOURCE_INVALID", 1, { reply });
+            if (reply.source_hash !== request.candidateHash)
+                throw new CliError("Studio mounted a different Experience source.", "STUDIO_SOURCE_MISMATCH", 3, {
+                    expected: request.candidateHash, actual: reply.source_hash
+                });
+        }
+        await page.waitForFunction((expected) => {
+            const raw = document.getElementById("kheleshikhi-studio-runtime-observation")?.textContent;
+            if (!raw)
+                return false;
+            const state = JSON.parse(raw);
+            return state.observation_scope === "live_experience_preview" && state.mounted === true &&
+                typeof state.active_state === "string" && (!expected || state.source_hash === expected);
+        }, request.candidateHash ?? null, { timeout: request.timeoutMs || 30_000 }).catch(() => {
+            throw new CliError("Experience Preview did not mount.", "EXPERIENCE_PREVIEW_TIMEOUT", 1);
+        });
+        if (request.candidateHash) {
+            // The initial capture showed the saved revision; retake it from the
+            // candidate that is actually being driven.
+            await waitForCapturePaint(page);
+            await page.screenshot({ path: path.resolve(request.out) });
+            initial.source_origin = "local";
+            initial.observation = await observation();
+        }
+        const results = [];
+        const summaries = [];
+        const started = Date.now();
+        for (const [index, step] of request.scenario.steps.entries()) {
+            if (Date.now() - started > 120_000)
+                throw new CliError("Experience scenario exceeded two minutes.", "STUDIO_SCENARIO_TIMEOUT");
+            if (isExperienceCommand(step)) {
+                const id = `experience-${index}`;
+                await page.evaluate(({ id, step }) => {
+                    let node = document.getElementById("kheleshikhi-studio-drive-command");
+                    if (!node) {
+                        node = document.createElement("div");
+                        node.id = "kheleshikhi-studio-drive-command";
+                        node.hidden = true;
+                        document.body.append(node);
+                    }
+                    node.textContent = JSON.stringify({ id, op: step.op, target: step.target, value: step.value, setup: step.setup });
+                }, { id, step });
+                const result = await page.waitForFunction((expected) => {
+                    const raw = document.getElementById("kheleshikhi-studio-drive-result")?.textContent;
+                    if (!raw)
+                        return false;
+                    const reply = JSON.parse(raw);
+                    return reply.id === expected ? reply : false;
+                }, id, { timeout: step.timeoutMs || 10_000 }).then((handle) => handle.jsonValue()).catch(() => {
+                    throw new CliError("Experience command acknowledgement timed out.", "STUDIO_DRIVE_TIMEOUT", 1, { step: index, operation: step.op });
+                });
+                summaries.push(stepSummary(step, result.ok === true));
+                await notify(request.onStep, { index, summary: summaries.at(-1), observation: result.observation });
+                if (result.ok !== true)
+                    throw new CliError(String(result.error || "Experience command failed."), "STUDIO_DRIVE_COMMAND_FAILED", 1, { index, result, step_summaries: summaries });
+                results.push({ index, op: step.op, observation: result.observation });
+            }
+            else if (step.op === "capture") {
+                const output = path.join(path.dirname(request.out), `step-${String(index).padStart(2, "0")}${step.name ? `-${step.name}` : ""}.png`);
+                await waitForCapturePaint(page);
+                await page.screenshot({ path: output, scale: "device" });
+                const captured = await observation();
+                results.push({ index, op: step.op, path: output, observation: captured });
+                summaries.push(stepSummary(step, true));
+                await notify(request.onStep, { index, summary: summaries.at(-1), observation: captured });
+            }
+            else {
+                let current = await observation();
+                if (step.op === "wait") {
+                    const deadline = Date.now() + (step.timeoutMs || 10_000);
+                    while (!matchesExperienceObservation(current, step) && Date.now() < deadline) {
+                        await page.waitForTimeout(100);
+                        current = await observation();
+                    }
+                }
+                const matched = matchesExperienceObservation(current, step);
+                summaries.push(stepSummary(step, matched, (step.path || "").split(".").reduce((value, key) => value && typeof value === "object" && Object.hasOwn(value, key) ? value[key] : undefined, current)));
+                await notify(request.onStep, { index, summary: summaries.at(-1), observation: current });
+                if (!matched)
+                    throw new CliError(`Experience ${step.op} failed at step ${index}: ${step.path}.`, "STUDIO_DRIVE_ASSERTION_FAILED", 1, { step: index, expected: step.equals, observed: current, step_summaries: summaries });
+                results.push({ index, op: step.op, path: step.path, actual: current });
+            }
+        }
+        const final = await observation();
+        return { initial, steps: results, final,
+            ...driveOutcome("experience", request.scenario.steps, results, summaries, final) };
+    }
+    /**
+     * Presentation frames (STU-001) of a Scene, from the presentation host.
+     *
+     * Mounts and verifies the candidate exactly as `drive` does, but in the
+     * presentation host (`studio_present=1`) at a viewport of exactly the
+     * output size and device scale 1. `renderBegin` silences the Scene's
+     * sounds into a log and restarts it at 0 s; then for every frame video
+     * time is stepped to `start + k / fps`, the runtime confirms that instant
+     * and a paint, and the whole viewport is captured: one PNG of exactly the
+     * output size, proved before it is kept. Scheduled learner actions happen
+     * at their own seconds. Afterwards the audio log and each logged sound's
+     * canonical bytes are collected for the mixer.
+     */
+    async renderFrames(request) {
+        const { recipe } = request;
+        request.onProgress?.({ stage: "mount" });
+        const mounted = await this.drive({ ...request, viewport: `${recipe.width}x${recipe.height}`, present: true,
+            deviceScaleFactor: 1, scenario: { version: 1, steps: [{ op: "pause" }] } });
+        const page = this.requirePage();
+        const phases = new PhaseTimes();
+        const { observation, command } = this.renderChannel(page, phases);
+        const first = await observation();
+        if (first.scene_clock_seconds === undefined || first.scene_clock_seconds === null) {
+            throw new CliError("This Scene has no SceneClock; a video needs logical time.", "VIDEO_NO_CLOCK", 2);
+        }
+        await command({ op: "renderBegin" });
+        await this.waitForRender(page, (value) => value.visual_ready === true, "the Scene to repaint after restarting");
+        await command({ op: "step", value: recipe.start });
+        // Video time is the master; the SceneClock follows it only while it
+        // plays, so an authored pause holds the picture. Record each stretch.
+        const clock = [];
+        let lastPlaying;
+        const frames = await this.captureFrames(page, { ...request, phases }, async (time, index) => {
+            const reached = await this.waitForRender(page, (value) => typeof value.render_video_seconds === "number" &&
+                Math.abs(value.render_video_seconds - time) <= 1e-6 && value.visual_ready === true, "the Scene to stand at the frame and paint");
+            if (typeof reached.scene_clock_seconds !== "number") {
+                throw new CliError("The Scene reported no SceneClock time.", "VIDEO_CLOCK_DRIFT", 1, { frame: index });
+            }
+            if (index === 0 || reached.scene_clock_playing !== lastPlaying) {
+                clock.push({ frame: index, video_seconds: time, scene_seconds: reached.scene_clock_seconds, playing: reached.scene_clock_playing === true });
+            }
+            lastPlaying = reached.scene_clock_playing;
+            return reached;
+        }, command);
+        request.onProgress?.({ stage: "audio_collect" });
+        const log = await command({ op: "renderLog" });
+        const audio = await this.collectAudio(log.audio ?? [], request.audioDirectory, recipe, request.signal, async (event) => (await command({ op: "audioBytes", target: event.id }, 30_000)).bytes);
+        const final = await observation();
+        // Real-time playback timing on the same mounted learner preview: the
+        // clock plays from the recipe's start and every animation frame interval
+        // is sampled. Diagnostic only; it never touches the rendered frames.
+        let playback;
+        const seconds = Math.min(30, Math.max(0, request.measurePlaybackSeconds ?? 0));
+        if (seconds > 0) {
+            throwIfCancelled(request.signal);
+            request.onProgress?.({ stage: "playback_measure" });
+            // Video time only moves forward; real-time playback seeks instead.
+            await command({ op: "reset" });
+            await command({ op: "seek", value: recipe.start });
+            await command({ op: "play" });
+            const timing = await page.evaluate(async (milliseconds) => {
+                const deltas = [];
+                let last = performance.now();
+                const end = last + milliseconds;
+                await new Promise((resolve) => {
+                    const tick = (now) => { deltas.push(now - last); last = now; if (now < end)
+                        requestAnimationFrame(tick);
+                    else
+                        resolve(); };
+                    requestAnimationFrame(tick);
+                });
+                const memory = performance.memory;
+                return { deltas, heap: memory ? memory.usedJSHeapSize : null };
+            }, seconds * 1000);
+            await command({ op: "pause" });
+            const sorted = [...timing.deltas].sort((a, b) => a - b);
+            const at = (q) => sorted[Math.min(sorted.length - 1, Math.floor(q * sorted.length))];
+            const reached = await observation();
+            playback = {
+                seconds, frames: sorted.length,
+                p50_ms: Number(at(0.5).toFixed(2)), p95_ms: Number(at(0.95).toFixed(2)), p99_ms: Number(at(0.99).toFixed(2)),
+                max_ms: Number((sorted.at(-1) ?? 0).toFixed(2)), over_33ms: sorted.filter((value) => value > 33.4).length,
+                js_heap_mb: timing.heap ? Math.round(timing.heap / 1048576) : null,
+                scene_clock_after: reached.scene_clock_seconds,
+            };
+        }
+        return {
+            ...(playback ? { playback_timing: playback } : {}),
+            ...frames,
+            audio,
+            scene_clock: clock,
+            runtime_fingerprint: first.runtime_fingerprint,
+            source_hash: first.source_hash,
+            source_revision: first.source_revision,
+            mounted_evidence: mounted.evidence_mode,
+            final_states: final.active_states,
+        };
+    }
+    /**
+     * Presentation frames of an Experience: the canonical Experience player
+     * in the presentation host, driven by video time (`renderBegin`, then
+     * `step` per frame). The master timeline advances with video time only
+     * while it runs, so a learner pause or a wait for a choice stays paused,
+     * as it would in playback; Scenes change, cues fire and sounds start at
+     * the exact video second they would.
+     */
+    async renderExperienceFrames(request) {
+        const { recipe } = request;
+        request.onProgress?.({ stage: "mount" });
+        await this.driveExperience({ ...request, viewport: `${recipe.width}x${recipe.height}`, present: true,
+            deviceScaleFactor: 1, scenario: { version: 1, steps: [] }, out: path.join(request.audioDirectory, "..", "mounted.png") });
+        const page = this.requirePage();
+        const phases = new PhaseTimes();
+        const { observation, command } = this.renderChannel(page, phases);
+        const first = await observation();
+        await command({ op: "renderBegin" });
+        await this.waitForRender(page, (value) => value.mounted === true && value.stage_ready === true, "the Experience stage to paint");
+        await command({ op: "step", value: recipe.start });
+        const scenes = [];
+        let lastScene;
+        const frames = await this.captureFrames(page, { ...request, phases }, async (time, index) => {
+            const reached = await this.waitForRender(page, (value) => value.stage_ready === true, "the Experience stage to paint");
+            if (typeof reached.render_video_ms !== "number" || Math.abs(reached.render_video_ms - time * 1000) > 1) {
+                throw new CliError("The Experience did not stand at the requested video time.", "VIDEO_CLOCK_DRIFT", 1, { expected_ms: time * 1000, observed_ms: reached.render_video_ms });
+            }
+            if (index === 0 || reached.active_scene !== lastScene)
+                scenes.push({ frame: index, at: time, scene: reached.active_scene, state: reached.active_state });
+            lastScene = reached.active_scene;
+            return reached;
+        }, command);
+        request.onProgress?.({ stage: "audio_collect" });
+        const log = await command({ op: "renderLog" });
+        const audio = await this.collectAudio(log.audio ?? [], request.audioDirectory, recipe, request.signal, async (event) => (await command({ op: "audioBytes", target: event.id, ...(event.scene ? { scene: event.scene } : {}) }, 30_000)).bytes);
+        const final = await observation();
+        return {
+            ...frames,
+            audio,
+            scenes,
+            source_hash: first.source_hash,
+            source_origin: first.source_origin,
+            final_state: final.active_state,
+            final_scene: final.active_scene,
+            timeline_ms: final.timeline_ms,
+            completed: final.completed,
+        };
+    }
+    requirePage() {
+        if (!this.page)
+            throw new CliError("Studio browser is unavailable.", "AGENT_BROWSER_NOT_READY");
+        return this.page;
+    }
+    /** The page's runtime observation and its one-at-a-time drive channel. */
+    renderChannel(page, phases) {
+        const observation = async () => page.evaluate(() => {
+            const raw = document.getElementById("kheleshikhi-studio-runtime-observation")?.textContent;
+            return raw ? JSON.parse(raw) : {};
+        });
+        let sequence = 0;
+        const command = async (payload, timeoutMs = 10_000) => {
+            const id = `render-${sequence += 1}`;
+            const sent = performance.now();
+            await page.evaluate(({ id, payload }) => {
+                let node = document.getElementById("kheleshikhi-studio-drive-command");
+                if (!node) {
+                    node = document.createElement("div");
+                    node.id = "kheleshikhi-studio-drive-command";
+                    node.hidden = true;
+                    document.body.append(node);
+                }
+                node.textContent = JSON.stringify({ id, ...payload });
+                // Wake the host now; a host without the listener still finds the
+                // command on its next 150 ms poll.
+                document.dispatchEvent(new Event("kheleshikhi-studio-drive-command"));
+            }, { id, payload });
+            const delivered = performance.now();
+            phases?.add("command_send", delivered - sent);
+            const reply = await page.waitForFunction((expected) => {
+                const raw = document.getElementById("kheleshikhi-studio-drive-result")?.textContent;
+                if (!raw)
+                    return false;
+                const value = JSON.parse(raw);
+                return value.id === expected ? value : false;
+            }, id, { timeout: timeoutMs }).then((handle) => handle.jsonValue()).catch(() => {
+                throw new CliError("The presentation host did not acknowledge a render step.", "VIDEO_STEP_TIMEOUT", 1, { payload: { ...payload, bytes: undefined } });
+            });
+            phases?.add("command_ack_wait", performance.now() - delivered);
+            if (reply.ok !== true)
+                throw new CliError(String(reply.error || "Render step failed."), "VIDEO_STEP_FAILED", 1, { payload, reply });
+            return reply;
+        };
+        return { observation, command };
+    }
+    /**
+     * The newest observation once [ready] holds. The page publishes one every
+     * 150 ms and after every command; while not ready, each read also asks the
+     * host for a fresh one (the drive-command wake event, with no command
+     * waiting, only republishes), so a paint that lands between polls is seen
+     * within milliseconds.
+     */
+    async waitForRender(page, ready, what, timeoutMs = 20_000) {
+        const deadline = Date.now() + timeoutMs;
+        for (let attempt = 0;; attempt += 1) {
+            const value = await page.evaluate((wake) => {
+                const raw = document.getElementById("kheleshikhi-studio-runtime-observation")?.textContent;
+                if (wake)
+                    document.dispatchEvent(new Event("kheleshikhi-studio-drive-command"));
+                return raw ? JSON.parse(raw) : {};
+            }, attempt > 0);
+            if (ready(value))
+                return value;
+            if (Date.now() > deadline)
+                throw new CliError(`Timed out waiting for ${what}.`, "VIDEO_STAGE_NOT_READY", 1, { observed: value });
+            await page.waitForTimeout(attempt === 0 ? 0 : 10);
+        }
+    }
+    /**
+     * The frame loop both subjects share: actions at their seconds, a step to
+     * each frame's exact second, the subject's own arrival check, a paint,
+     * and a whole-viewport PNG proved to be exactly the output size.
+     */
+    async captureFrames(page, request, arrived, command) {
+        const { recipe } = request;
+        const phases = request.phases ?? new PhaseTimes();
+        throwIfCancelled(request.signal);
+        await mkdir(request.framesDirectory, { recursive: true });
+        const viewport = await page.evaluate(() => ({ width: window.innerWidth, height: window.innerHeight, dpr: window.devicePixelRatio }));
+        if (viewport.width !== recipe.width || viewport.height !== recipe.height || viewport.dpr !== 1) {
+            throw new CliError("The presentation viewport is not the output size at device scale 1.", "VIDEO_VIEWPORT_MISMATCH", 1, { viewport, expected: { width: recipe.width, height: recipe.height } });
+        }
+        const clip = { x: 0, y: 0, width: recipe.width, height: recipe.height };
+        const total = frameCount(recipe);
+        const hashes = [];
+        const shots = [];
+        const performed = [];
+        let previous = recipe.start - 1;
+        let lastShot;
+        const started = Date.now();
+        phases.active = true;
+        for (let index = 0; index < total; index += 1) {
+            const frameStarted = performance.now();
+            // A cancelled job (client gone, Ctrl-C, deadline) stops here, between frames.
+            throwIfCancelled(request.signal);
+            request.onProgress?.({ stage: "capture", frame: index, frames: total });
+            const time = frameTime(recipe, index);
+            for (const action of actionsBetween(recipe, previous, time)) {
+                await phases.time("actions", async () => {
+                    await command({ op: "step", value: action.at });
+                    await command({ op: action.op, ...(action.target !== undefined ? { target: action.target } : {}), ...(action.value !== undefined ? { value: action.value } : {}) });
+                });
+                performed.push({ at: action.at, op: action.op, ...(action.target !== undefined ? { target: action.target } : {}), frame: index });
+            }
+            await phases.time("step", () => command({ op: "step", value: time }));
+            const reached = await phases.time("arrival", () => arrived(time, index));
+            await phases.time("paint", () => waitForCapturePaint(page));
+            const png = await phases.time("screenshot", () => captureViewportPng(page, clip));
+            const writeStarted = performance.now();
+            const size = pngSize(png);
+            if (size.width !== recipe.width || size.height !== recipe.height) {
+                throw new CliError(`Frame ${index} is ${size.width}x${size.height}, not ${recipe.width}x${recipe.height}.`, "VIDEO_FRAME_SIZE_MISMATCH", 1, { frame: index, size });
+            }
+            hashes.push(sha256(png));
+            await writeFile(path.join(request.framesDirectory, `${String(index).padStart(6, "0")}.png`), png);
+            phases.add("hash_and_write", performance.now() - writeStarted);
+            phases.add("frame_total", performance.now() - frameStarted);
+            const shot = reached.learner_camera?.shot ?? null;
+            if (index === 0 || shot !== lastShot)
+                shots.push({ frame: index, at: time, shot });
+            lastShot = shot;
+            previous = time;
+        }
+        phases.active = false;
+        request.onProgress?.({ stage: "capture", frame: total, frames: total });
+        return {
+            frames: total,
+            frame_size: { width: recipe.width, height: recipe.height, device_scale_factor: 1, verified_frames: total },
+            frame_sha256: hashes,
+            frames_sha256: sha256(hashes.join("\n")),
+            learner_surface: { ...clip, kind: "presentation_host" },
+            camera_shots: shots,
+            actions: performed,
+            capture_seconds: (Date.now() - started) / 1000,
+            capture_phases: phases.summary(total),
+        };
+    }
+    /** Every logged sound's canonical bytes, written once by key; checked against the logged SHA-256. */
+    async collectAudio(events, directory, recipe, signal, bytesOf) {
+        const sources = {};
+        if (recipe.audio === "scene") {
+            await mkdir(directory, { recursive: true });
+            for (const event of events) {
+                const key = audioKey(event);
+                if (event.action !== "play" || sources[key])
+                    continue;
+                throwIfCancelled(signal);
+                if (Object.keys(sources).length >= 32)
+                    throw new CliError("A render mixes at most 32 distinct sounds.", "VIDEO_AUDIO_TOO_MANY", 2);
+                const data = Buffer.from(await bytesOf(event), "base64");
+                const digest = sha256(data);
+                if (event.sha256 && event.sha256 !== digest) {
+                    throw new CliError(`Sound ${key} bytes do not match their declared SHA-256.`, "VIDEO_AUDIO_SOURCE_MISMATCH", 1, { expected: event.sha256, actual: digest });
+                }
+                const file = path.join(directory, `${digest}.m4a`);
+                await writeFile(file, data);
+                sources[key] = { file, sha256: digest, bytes: data.length };
+            }
+        }
+        return { events, sources };
     }
     /** Local-agent capture from the same browser page and renderer the Maker sees. */
     async capturePreview(request) {