@kheleshikhi/studio-agent 0.6.1

package/dist/browser.js

@@ -0,0 +1,837 @@
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { chromium } from "playwright";
+import { cacheDirectory } from "./state.js";
+import { CliError } from "./types.js";
+import { assertCurrentObservation, ObservationSampler, observationSettings } from "./observation.js";
+import { isDriveCommand, matchesObservation } from "./scenario.js";
+export function studioBrowserLaunchOptions(headless) {
+    return {
+        headless,
+        viewport: null,
+        // Playwright otherwise adds --no-sandbox to Chromium. The Studio Agent is
+        // a normal user-machine browser and must keep the browser sandbox enabled.
+        chromiumSandbox: true,
+    };
+}
+export function browserProbeLaunchOptions(channel) {
+    return {
+        channel,
+        headless: true,
+        chromiumSandbox: true,
+    };
+}
+export function cssViewport(value) {
+    if (value === "desktop")
+        return { width: 1440, height: 1000 };
+    if (value === "mobile")
+        return { width: 390, height: 844 };
+    const match = /^(\d{3,5})x(\d{3,5})$/.exec(value);
+    if (!match)
+        throw new CliError("Viewport must be desktop, mobile, or WIDTHxHEIGHT.", "STUDIO_VIEWPORT_INVALID", 2);
+    return { width: Number(match[1]), height: Number(match[2]) };
+}
+export async function waitForCapturePaint(page) {
+    try {
+        await page.evaluate(async () => {
+            await Promise.race([
+                document.fonts.ready.then(() => new Promise((resolve) => {
+                    requestAnimationFrame(() => requestAnimationFrame(() => resolve()));
+                })),
+                new Promise((_, reject) => {
+                    setTimeout(() => reject(new Error("capture paint timeout")), 8000);
+                }),
+            ]);
+        });
+    }
+    catch {
+        throw new CliError("Studio did not paint after runtime readiness.", "STUDIO_CAPTURE_PAINT_TIMEOUT");
+    }
+}
+async function waitForVisualReady(page, timeoutMs, stage) {
+    try {
+        await page.waitForFunction(() => {
+            const raw = document.getElementById("kheleshikhi-studio-runtime-observation")?.textContent;
+            if (!raw)
+                return false;
+            const state = JSON.parse(raw);
+            return state.status === "complete" && state.visual_ready === true;
+        }, undefined, { timeout: timeoutMs });
+    }
+    catch {
+        const lastObserved = await page.evaluate(() => {
+            const raw = document.getElementById("kheleshikhi-studio-runtime-observation")?.textContent;
+            if (!raw)
+                return null;
+            try {
+                return JSON.parse(raw);
+            }
+            catch {
+                return null;
+            }
+        });
+        throw new CliError("Studio visual surface did not become ready.", "STUDIO_VISUAL_NOT_READY", 1, {
+            stage, elapsed_ms: timeoutMs, ...readinessSummary(lastObserved),
+        });
+    }
+}
+const viewportSessions = new WeakMap();
+export async function applyCssViewport(page, dimensions) {
+    const nativeScreen = await page.evaluate(() => ({
+        width: window.screen.width,
+        height: window.screen.height,
+    }));
+    let session = viewportSessions.get(page);
+    if (!session) {
+        session = await page.context().newCDPSession(page);
+        viewportSessions.set(page, session);
+        page.once("close", () => {
+            viewportSessions.delete(page);
+            void session?.detach().catch(() => undefined);
+        });
+    }
+    // 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.
+    await session.send("Emulation.setDeviceMetricsOverride", {
+        width: dimensions.width,
+        height: dimensions.height,
+        deviceScaleFactor: 0,
+        mobile: false,
+        screenWidth: nativeScreen.width,
+        screenHeight: nativeScreen.height,
+    });
+    const actual = await page.evaluate(() => ({ width: window.innerWidth, height: window.innerHeight }));
+    if (actual.width !== dimensions.width || actual.height !== dimensions.height) {
+        throw new CliError("Browser did not apply the requested CSS viewport.", "STUDIO_VIEWPORT_NOT_APPLIED", 1, {
+            requested: dimensions,
+            actual,
+        });
+    }
+}
+export async function renderingDiagnostics(page, screenshot) {
+    if (screenshot.length < 24 || screenshot.subarray(0, 8).toString("hex") !== "89504e470d0a1a0a") {
+        throw new CliError("Browser screenshot was not a valid PNG.", "STUDIO_SCREENSHOT_INVALID");
+    }
+    const display = await page.evaluate(() => ({
+        devicePixelRatio: window.devicePixelRatio,
+        innerWidth: window.innerWidth,
+        innerHeight: window.innerHeight,
+        screenWidth: window.screen.width,
+        screenHeight: window.screen.height,
+        screenAvailWidth: window.screen.availWidth,
+        screenAvailHeight: window.screen.availHeight,
+    }));
+    return {
+        viewport: { width: display.innerWidth, height: display.innerHeight },
+        device_pixel_ratio: display.devicePixelRatio,
+        window: { inner_width: display.innerWidth, inner_height: display.innerHeight },
+        screen: {
+            width: display.screenWidth,
+            height: display.screenHeight,
+            available_width: display.screenAvailWidth,
+            available_height: display.screenAvailHeight,
+        },
+        screenshot_pixels: {
+            width: screenshot.readUInt32BE(16),
+            height: screenshot.readUInt32BE(20),
+        },
+    };
+}
+export const VIEW_QUERY = {
+    canvas: { workspace: "scene", view: "canvas" },
+    final: { workspace: "scene", view: "preview" },
+    learner: { workspace: "scene", view: "preview", studio_learner: "1" },
+    source: { workspace: "scene", panel: "source" },
+    problems: { workspace: "scene", panel: "problems" },
+    states: { workspace: "scene", view: "states", panel: "events-state" },
+    variables: { workspace: "scene", panel: "variables" },
+    bindings: { workspace: "scene", panel: "wiring" },
+    internals: { workspace: "scene", panel: "internals" },
+    certification: { workspace: "scene", panel: "certification" },
+    activity: { workspace: "scene", panel: "agent-activity" },
+    math: { workspace: "scene", view: "math" },
+    components: { workspace: "components" },
+    behaviors: { workspace: "behaviors" },
+};
+// Catalogue workspaces intentionally contain no mounted Scene runtime. They
+// still support real-browser screenshots and diagnostics; runtime observation
+// remains mandatory for every Scene workspace view.
+const NON_RUNTIME_VIEWS = new Set(["components", "behaviors"]);
+const BROWSER_TOKEN_REFRESH_MARGIN_MS = 60_000;
+export function viewRequiresRuntimeObservation(view) {
+    return !NON_RUNTIME_VIEWS.has(view);
+}
+function safeUrl(raw) {
+    const url = new URL(raw);
+    // Query values and URL user-info can contain credentials even when their
+    // names look harmless. Route and host are enough to diagnose a failed load.
+    return `${url.origin}${url.pathname}`.slice(0, 300);
+}
+function boundedText(value) {
+    return value
+        .replace(/\b(?:Bearer\s+\S+|nbs_[A-Za-z0-9_-]+|nbp_[A-Za-z0-9_-]+)\b/gi, "[REDACTED]")
+        .replace(/\beyJ[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)?\b/g, "[REDACTED]")
+        .replace(/\b(?:\d{1,3}\.){3}\d{1,3}\b/g, "[REDACTED]")
+        .slice(0, 400);
+}
+function readinessSummary(value) {
+    if (!value)
+        return { readiness_stage: "observation_missing" };
+    return {
+        readiness_stage: value.readiness_stage ?? null,
+        status: value.status ?? null,
+        source_hash: value.source_hash ?? null,
+        preview_is_current: value.preview_is_current ?? null,
+        runtime_ready: value.runtime_ready ?? null,
+        visual_ready: value.visual_ready ?? null,
+        visual_surface_available: value.visual_surface_available ?? null,
+        visual_bands: value.visual_bands ?? null,
+        renderers: Array.isArray(value.renderers) ? value.renderers.slice(0, 12).map((item) => {
+            const renderer = item;
+            return {
+                id: boundedText(String(renderer.id ?? "")),
+                type: boundedText(String(renderer.type ?? "")),
+                mounted: renderer.mounted === true,
+                phase: boundedText(String(renderer.phase ?? "")),
+                instance_id: boundedText(String(renderer.instance_id ?? "")),
+                error: renderer.error ? boundedText(String(renderer.error)) : null,
+            };
+        }) : [],
+        error_summary: value.error_summary ? boundedText(String(value.error_summary)) : null,
+    };
+}
+/** Memory-only reuse of the short-lived browser JWT; bootstrap tickets stay one-use. */
+export class BrowserCredentialManager {
+    api;
+    now;
+    credential;
+    bootstrapCount = 0;
+    apiOrigin;
+    constructor(api, now = Date.now) {
+        this.api = api;
+        this.now = now;
+        this.apiOrigin = new URL(api.origin).origin;
+    }
+    clear() {
+        this.credential = undefined;
+    }
+    diagnostics() {
+        return {
+            browser_credential_cached: this.credential !== undefined,
+            browser_bootstrap_count: this.bootstrapCount,
+        };
+    }
+    tokenForRequest(requestUrl) {
+        if (!this.credential || new URL(requestUrl).origin !== this.apiOrigin)
+            return undefined;
+        return this.credential.token;
+    }
+    async get(forceRefresh = false) {
+        if (!forceRefresh
+            && this.credential
+            && this.credential.expiresAt - this.now() > BROWSER_TOKEN_REFRESH_MARGIN_MS) {
+            return this.credential;
+        }
+        this.clear();
+        const ticket = await this.api.request("POST", "/v1/agent/browser-session", {});
+        const session = await this.api.request("POST", "/v1/agent/browser-session/redeem", { ticket: ticket.ticket }, false);
+        const expiresAt = Date.parse(session.expires_at);
+        if (!Number.isFinite(expiresAt) || expiresAt <= this.now()) {
+            throw new CliError("Server returned an expired browser credential.", "AGENT_BROWSER_SESSION_INVALID", 4);
+        }
+        this.credential = {
+            token: session.browser_token,
+            expiresAt,
+            webOrigin: new URL(session.allowed_origin).origin,
+        };
+        this.bootstrapCount += 1;
+        return this.credential;
+    }
+}
+const LIBRARY_WORKSPACES = new Set(["experiences", "audio", "components", "behaviors"]);
+export class StudioBrowser {
+    api;
+    context;
+    page;
+    headless = false;
+    browserEngine = "not-started";
+    apiOrigin;
+    credentials;
+    constructor(api) {
+        this.api = api;
+        this.apiOrigin = new URL(api.origin).origin;
+        this.credentials = new BrowserCredentialManager(api);
+    }
+    async start(headless) {
+        if (this.context)
+            return;
+        this.headless = headless;
+        const profile = path.join(cacheDirectory(), "browser-profile");
+        await mkdir(profile, { recursive: true, mode: 0o700 });
+        const attempts = [
+            { channel: "chrome", name: "Google Chrome" },
+            { channel: "msedge", name: "Microsoft Edge" },
+            { name: "Playwright Chromium" },
+        ];
+        const errors = [];
+        for (const attempt of attempts) {
+            try {
+                this.context = await chromium.launchPersistentContext(profile, {
+                    ...studioBrowserLaunchOptions(headless),
+                    channel: attempt.channel,
+                });
+                await this.context.route("**/*", async (route) => {
+                    const request = route.request();
+                    const destination = new URL(request.url());
+                    const browserToken = this.credentials.tokenForRequest(request.url());
+                    if (browserToken && destination.origin === this.apiOrigin) {
+                        await route.continue({
+                            headers: {
+                                ...request.headers(),
+                                Authorization: `Bearer ${browserToken}`,
+                            },
+                        });
+                        return;
+                    }
+                    await route.continue();
+                });
+                this.page = this.context.pages()[0] || (await this.context.newPage());
+                this.browserEngine = attempt.name;
+                return;
+            }
+            catch (error) {
+                errors.push(`${attempt.name}: ${String(error).split("\n")[0]}`);
+            }
+        }
+        throw new CliError(`No supported browser could launch. Run \`nerdbro setup\`. ${errors.join("; ")}`, "STUDIO_BROWSER_UNAVAILABLE", 5);
+    }
+    async stop() {
+        this.clearAuthentication();
+        await this.context?.close();
+        this.context = undefined;
+        this.page = undefined;
+    }
+    clearAuthentication() {
+        this.credentials.clear();
+    }
+    authenticationDiagnostics() {
+        return { ...this.credentials.diagnostics(), browser_engine: this.browserEngine };
+    }
+    async authenticatedPage(forceRefresh = false) {
+        if (!this.context)
+            await this.start(this.headless);
+        const browserSession = await this.credentials.get(forceRefresh);
+        const webOrigin = browserSession.webOrigin;
+        const page = this.page && !this.page.isClosed() ? this.page : await this.context.newPage();
+        await applyCssViewport(page, { width: 1440, height: 1000 });
+        await page.goto(webOrigin, { waitUntil: "domcontentloaded", timeout: 30_000 });
+        await page.evaluate(() => {
+            localStorage.setItem("GetStorage", JSON.stringify({
+                // This is intentionally not a credential. It lets the Flutter route
+                // guard mount while Playwright injects the real short-lived browser
+                // token from daemon memory only for the configured NerdBro API.
+                jwtToken: "studio-agent-browser-session",
+                onboardingCompleted: true,
+                cachedRoles: ["maker"],
+                studioAgentBrowserSession: true,
+            }));
+        });
+        return { page, webOrigin };
+    }
+    async open(asset, view = "canvas", allowRefresh = true) {
+        if (!VIEW_QUERY[view])
+            throw new CliError(`Unknown Studio view: ${view}`, "STUDIO_VIEW_INVALID", 2);
+        const { page, webOrigin } = await this.authenticatedPage();
+        const query = new URLSearchParams({ ...(VIEW_QUERY[view] || VIEW_QUERY.canvas), studio_observation: "1" });
+        const url = new URL(`/maker/interactive/studio/${encodeURIComponent(asset)}?${query}`, webOrigin);
+        await page.goto(url.toString(), { waitUntil: "domcontentloaded", timeout: 30_000 });
+        if (/\/(sign-in|login|complete-profile)(\/|\?|$)/.test(page.url())) {
+            if (allowRefresh) {
+                this.clearAuthentication();
+                return this.open(asset, view, false);
+            }
+            throw new CliError("Studio redirected to authentication.", "AGENT_BROWSER_AUTH_REQUIRED");
+        }
+        return { ok: true, url: safeUrl(page.url()), view };
+    }
+    async capture(request, allowRefresh = true) {
+        const view = request.library ? "library" : request.view || "canvas";
+        if (request.library && !LIBRARY_WORKSPACES.has(request.library.workspace)) {
+            throw new CliError(`Unknown Library workspace: ${request.library.workspace}`, "STUDIO_VIEW_INVALID", 2);
+        }
+        if (!request.library && !VIEW_QUERY[view])
+            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);
+        const consoleErrors = [];
+        const pageErrors = [];
+        const requestFailures = [];
+        const httpErrors = [];
+        page.removeAllListeners("console");
+        page.removeAllListeners("pageerror");
+        page.removeAllListeners("requestfailed");
+        page.removeAllListeners("response");
+        page.on("console", (message) => {
+            if (message.type() === "error" && consoleErrors.length < 12)
+                consoleErrors.push(boundedText(message.text()));
+        });
+        page.on("pageerror", (error) => {
+            if (pageErrors.length < 12)
+                pageErrors.push(boundedText(error.message));
+        });
+        page.on("requestfailed", (failed) => {
+            if (requestFailures.length < 12)
+                requestFailures.push({
+                    url: safeUrl(failed.url()),
+                    method: failed.method(),
+                    error: boundedText(failed.failure()?.errorText || "request failed"),
+                });
+        });
+        page.on("response", (response) => {
+            if (response.status() >= 400 && httpErrors.length < 12)
+                httpErrors.push({
+                    url: safeUrl(response.url()),
+                    status: response.status(),
+                    method: response.request().method(),
+                });
+        });
+        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);
+        await page.goto(target.toString(), { waitUntil: "domcontentloaded", timeout: request.timeoutMs || 30_000 });
+        const apiUnauthorized = httpErrors.some((item) => {
+            if (item.status !== 401)
+                return false;
+            try {
+                return new URL(String(item.url)).origin === this.apiOrigin;
+            }
+            catch {
+                return false;
+            }
+        });
+        if (apiUnauthorized && allowRefresh) {
+            this.clearAuthentication();
+            return this.capture(request, false);
+        }
+        if (/\/(sign-in|login|complete-profile)(\/|\?|$)/.test(page.url())) {
+            if (allowRefresh) {
+                this.clearAuthentication();
+                return this.capture(request, false);
+            }
+            throw new CliError("Studio redirected away from the Maker route.", "STUDIO_ROUTE_REDIRECTED");
+        }
+        let observation = null;
+        // Library workspaces mount no Scene runtime, like the catalogue views.
+        const requireObservation = request.observation ?? (request.library ? false : viewRequiresRuntimeObservation(view));
+        if (requireObservation) {
+            const deadline = Date.now() + (request.timeoutMs || 30_000);
+            while (Date.now() < deadline) {
+                observation = await page.evaluate(() => {
+                    const value = document.getElementById("kheleshikhi-studio-runtime-observation")?.textContent;
+                    if (!value)
+                        return null;
+                    try {
+                        return JSON.parse(value);
+                    }
+                    catch {
+                        return null;
+                    }
+                });
+                if (observation?.status === "error" ||
+                    (observation?.status === "complete" && observation.visual_ready === true))
+                    break;
+                await page.waitForTimeout(125);
+            }
+            if (!observation || observation.visual_ready !== true && observation.status !== "error") {
+                throw new CliError("Studio visual surface did not become ready for capture.", "STUDIO_VISUAL_NOT_READY", 1, {
+                    stage: "capture_preflight", elapsed_ms: request.timeoutMs || 30_000,
+                    ...readinessSummary(observation),
+                    console_errors: consoleErrors, page_errors: pageErrors,
+                    request_failures: requestFailures, http_errors: httpErrors,
+                });
+            }
+            if (observation.status === "error")
+                throw new CliError(String(observation.error_summary || "Runtime observation failed."), "STUDIO_RUNTIME_ERROR", 1, {
+                    ...readinessSummary(observation), console_errors: consoleErrors,
+                    page_errors: pageErrors, request_failures: requestFailures,
+                    http_errors: httpErrors,
+                });
+            if (observation.source_hash !== request.sourceHash) {
+                throw new CliError("Studio runtime source does not match the local checkout.", "STUDIO_SOURCE_MISMATCH", 3, {
+                    expected: request.sourceHash,
+                    actual: observation.source_hash,
+                });
+            }
+            const context = await this.api.request("GET", "/v1/agent/context");
+            if (observation.runtime_fingerprint !== context.runtime_fingerprint) {
+                throw new CliError("Studio runtime fingerprint is out of step with production.", "STUDIO_RUNTIME_FINGERPRINT_MISMATCH", 3, {
+                    expected: context.runtime_fingerprint,
+                    actual: observation.runtime_fingerprint,
+                });
+            }
+            if (observation.mounted !== true)
+                throw new CliError("Studio runtime is not mounted.", "STUDIO_RUNTIME_NOT_MOUNTED");
+            if (observation.runtime_ready !== true)
+                throw new CliError("Studio runtime is not ready.", "STUDIO_RUNTIME_NOT_READY");
+            if (observation.state_machine_error)
+                throw new CliError(String(observation.state_machine_error), "STUDIO_STATE_MACHINE_ERROR");
+            const graph = observation.math_graph;
+            if (graph?.error)
+                throw new CliError(String(graph.error), "STUDIO_MATHGRAPH_ERROR");
+        }
+        let libraryObservation = null;
+        if (request.library) {
+            const deadline = Date.now() + (request.timeoutMs || 30_000);
+            while (Date.now() < deadline) {
+                libraryObservation = await page.evaluate(() => {
+                    const value = document.getElementById("kheleshikhi-studio-library-observation")?.textContent;
+                    if (!value)
+                        return null;
+                    try {
+                        return JSON.parse(value);
+                    }
+                    catch {
+                        return null;
+                    }
+                });
+                if (libraryObservation?.status === "complete")
+                    break;
+                await page.waitForTimeout(125);
+            }
+            if (!libraryObservation || libraryObservation.status !== "complete") {
+                throw new CliError("Studio Library did not load the selected definition.", "STUDIO_LIBRARY_CAPTURE_TIMEOUT", 1, {
+                    url: safeUrl(page.url()),
+                    console_errors: consoleErrors,
+                    page_errors: pageErrors,
+                    request_failures: requestFailures,
+                    http_errors: httpErrors,
+                });
+            }
+            if (libraryObservation.workspace !== request.library.workspace || libraryObservation.stable_id !== request.library.selection ||
+                (request.library.revision && libraryObservation.revision_id !== request.library.revision) ||
+                (request.library.definitionHash && libraryObservation.definition_hash !== request.library.definitionHash)) {
+                throw new CliError("Studio Library showed a different definition or revision.", "STUDIO_LIBRARY_SOURCE_MISMATCH", 3, {
+                    expected: request.library, actual: libraryObservation,
+                });
+            }
+        }
+        // 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.
+        await waitForCapturePaint(page);
+        await mkdir(path.dirname(path.resolve(request.out)), { recursive: true });
+        const screenshot = await page.screenshot({
+            path: path.resolve(request.out),
+            fullPage: request.fullPage || false,
+            scale: "device",
+        });
+        const rendering = await renderingDiagnostics(page, screenshot);
+        const browser = {
+            url: safeUrl(page.url()),
+            requested_view: view,
+            ...(libraryObservation ? { library_observation: libraryObservation } : {}),
+            ...rendering,
+            browser: this.context?.browser()?.version() || "persistent chromium",
+            headless: this.headless,
+            console_errors: consoleErrors,
+            page_errors: pageErrors,
+            request_failures: requestFailures,
+            http_errors: httpErrors,
+        };
+        return { screenshot: path.resolve(request.out), runtime: observation, browser };
+    }
+    async drive(request) {
+        const first = await this.capture({ ...request, view: "learner", drive: true,
+            observation: Boolean(request.sourceHash) });
+        const page = this.page;
+        if (!page)
+            throw new CliError("Studio browser is unavailable.", "AGENT_BROWSER_NOT_READY");
+        const current = first.runtime;
+        const alreadyCurrent = request.sourceHash === request.candidateHash &&
+            current?.source_hash === request.candidateHash && current?.runtime_ready === true &&
+            current?.preview_is_current === true;
+        if (!alreadyCurrent)
+            await page.evaluate((candidate) => {
+                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: "candidate", op: "loadCandidate", source: candidate });
+            }, request.candidate);
+        const candidateReply = alreadyCurrent ? { ok: true, source_hash: request.candidateHash } : await page.waitForFunction(() => {
+            const raw = document.getElementById("kheleshikhi-studio-drive-result")?.textContent;
+            if (!raw)
+                return false;
+            const reply = JSON.parse(raw);
+            return reply.id === "candidate" ? reply : false;
+        }, undefined, { timeout: request.timeoutMs || 30_000 }).then((handle) => handle.jsonValue()).catch(async () => {
+            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 candidate acknowledgement.", "STUDIO_DRIVE_TIMEOUT", 1, { stage: "candidate_ack", elapsed_ms: request.timeoutMs || 30_000, last_observed: lastObserved });
+        });
+        if (candidateReply.ok !== true || candidateReply.source_hash !== request.candidateHash) {
+            throw new CliError(String(candidateReply.error || "Candidate preview source hash mismatch."), "STUDIO_SOURCE_MISMATCH", 3, candidateReply);
+        }
+        await page.waitForFunction((expected) => {
+            const raw = document.getElementById("kheleshikhi-studio-runtime-observation")?.textContent;
+            if (!raw)
+                return false;
+            const value = JSON.parse(raw);
+            return value.source_hash === expected && value.runtime_ready === true && value.visual_ready === true && value.preview_is_current === true;
+        }, request.candidateHash, { timeout: request.timeoutMs || 30_000 }).catch(async () => {
+            const lastObserved = await page.evaluate(() => {
+                const raw = document.getElementById("kheleshikhi-studio-runtime-observation")?.textContent;
+                if (!raw)
+                    return null;
+                try {
+                    return JSON.parse(raw);
+                }
+                catch {
+                    return null;
+                }
+            });
+            throw new CliError("Studio drive timed out waiting for candidate runtime readiness.", "STUDIO_DRIVE_TIMEOUT", 1, {
+                stage: "candidate_runtime", elapsed_ms: request.timeoutMs || 30_000,
+                expected_hash: request.candidateHash, ...readinessSummary(lastObserved),
+                browser_errors: first.browser,
+            });
+        });
+        const ready = await page.evaluate(() => {
+            const raw = document.getElementById("kheleshikhi-studio-runtime-observation")?.textContent;
+            return raw ? JSON.parse(raw) : {};
+        });
+        const contract = await this.api.request("GET", "/v1/agent/context");
+        if (ready.runtime_fingerprint !== contract.runtime_fingerprint) {
+            throw new CliError("Candidate runtime fingerprint is out of step with the server.", "STUDIO_RUNTIME_FINGERPRINT_MISMATCH", 3);
+        }
+        if (ready.state_machine_error || ready.math_graph?.error) {
+            throw new CliError("Candidate preview reported a runtime error.", "STUDIO_RUNTIME_ERROR", 1, ready);
+        }
+        const results = [];
+        const observation = async () => page.evaluate(() => {
+            const raw = document.getElementById("kheleshikhi-studio-runtime-observation")?.textContent;
+            return raw ? JSON.parse(raw) : {};
+        });
+        const started = Date.now();
+        for (const [index, step] of request.scenario.steps.entries()) {
+            if (Date.now() - started > 120_000)
+                throw new CliError("Semantic scenario exceeded two minutes.", "STUDIO_SCENARIO_TIMEOUT");
+            if (isDriveCommand(step)) {
+                const id = `step-${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 });
+                }, { 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(async () => {
+                    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 });
+                });
+                if (result.ok !== true)
+                    throw new CliError(String(result.error || "Semantic command failed."), "STUDIO_DRIVE_COMMAND_FAILED", 1, { index, step, result });
+                results.push({ index, op: step.op, observation: result.observation });
+                continue;
+            }
+            if (step.op === "capture") {
+                const filename = `step-${String(index).padStart(2, "0")}${step.name ? `-${step.name}` : ""}.png`;
+                const output = path.join(path.dirname(request.out), filename);
+                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() });
+                continue;
+            }
+            let current = await observation();
+            if (step.op === "wait") {
+                const deadline = Date.now() + (step.timeoutMs || 10_000);
+                while (!matchesObservation(current, step) && Date.now() < deadline) {
+                    await page.waitForTimeout(100);
+                    current = await observation();
+                }
+            }
+            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 });
+            }
+            results.push({ index, op: step.op, path: step.path, actual: current });
+        }
+        return { source_hash: request.candidateHash, initial: first, steps: results, final: await observation() };
+    }
+    /** Local-agent capture from the same browser page and renderer the Maker sees. */
+    async capturePreview(request) {
+        const dimensions = cssViewport(request.viewport || "480x320");
+        const settings = observationSettings({
+            mode: request.mode, duration: request.duration, fps: request.fps,
+            ...dimensions,
+        });
+        // The requested viewport is the observation frame. The full Studio shell
+        // needs additional CSS room for its chrome/panes before we crop and scale
+        // the real preview, particularly for 480×320 LLM captures.
+        const browserViewport = {
+            width: Math.min(1280, Math.max(dimensions.width + 600, 1024)),
+            height: Math.min(960, Math.max(dimensions.height + 500, 800)),
+        };
+        const root = path.resolve(request.out);
+        await mkdir(root);
+        try {
+            const preflight = await this.capture({ ...request, view: "canvas", viewport: `${browserViewport.width}x${browserViewport.height}`, out: path.join(root, "preflight.png") });
+            const page = this.page;
+            if (!page)
+                throw new CliError("Browser preview is unavailable.", "STUDIO_CAPTURE_UNSUPPORTED");
+            let baseline = preflight.runtime;
+            // The preflight can observe the one-shot certification snapshot before
+            // the passive live bridge's next tick. Wait for the latter explicitly.
+            for (let attempt = 0; attempt < 30; attempt += 1) {
+                const value = await page.evaluate(() => document.getElementById("kheleshikhi-studio-runtime-observation")?.textContent || "");
+                if (value)
+                    baseline = JSON.parse(value);
+                if (baseline.status === "complete" && baseline.preview_is_current === true &&
+                    baseline.source_revision !== undefined && baseline.preview_bounds)
+                    break;
+                await page.waitForTimeout(100);
+            }
+            const revision = baseline.source_revision;
+            assertCurrentObservation(baseline, request.sourceHash, revision);
+            const bounds = baseline.preview_bounds;
+            if (!bounds || !Number.isFinite(bounds.x) || !Number.isFinite(bounds.y) ||
+                !Number.isFinite(bounds.width) || !Number.isFinite(bounds.height) ||
+                bounds.width < 40 || bounds.height < 40) {
+                throw new CliError("Studio did not report a visible preview rectangle.", "STUDIO_CAPTURE_PREVIEW_NOT_VISIBLE");
+            }
+            const clip = {
+                x: Math.max(0, bounds.x), y: Math.max(0, bounds.y),
+                width: Math.min(bounds.width, browserViewport.width - Math.max(0, bounds.x)),
+                height: Math.min(bounds.height, browserViewport.height - Math.max(0, bounds.y)),
+            };
+            if (clip.width < 40 || clip.height < 40)
+                throw new CliError("The preview is outside the browser viewport.", "STUDIO_CAPTURE_PREVIEW_NOT_VISIBLE");
+            const sampler = new ObservationSampler(settings);
+            const frameImages = [];
+            let encodedBytes = 0;
+            await mkdir(path.join(root, "frames"));
+            const started = Date.now();
+            const read = async () => {
+                const value = await page.evaluate(() => document.getElementById("kheleshikhi-studio-runtime-observation")?.textContent || "");
+                if (!value)
+                    throw new CliError("Live preview observation disappeared.", "STUDIO_CAPTURE_UNSUPPORTED");
+                const observed = JSON.parse(value);
+                assertCurrentObservation(observed, request.sourceHash, revision);
+                return observed;
+            };
+            const sample = async (final = false) => {
+                const atMs = Math.min(Date.now() - started, settings.durationMs);
+                const selected = sampler.consider(atMs, await read(), final);
+                if (!selected)
+                    return;
+                const cropped = await page.screenshot({ type: "jpeg", quality: 70, scale: "css", clip });
+                const resized = await page.evaluate(async ({ data, width, height }) => {
+                    const image = new Image();
+                    image.src = `data:image/jpeg;base64,${data}`;
+                    await image.decode();
+                    const canvas = document.createElement("canvas");
+                    canvas.width = width;
+                    canvas.height = height;
+                    const context = canvas.getContext("2d");
+                    if (!context)
+                        throw new Error("Browser cannot encode preview frames.");
+                    context.drawImage(image, 0, 0, width, height);
+                    return canvas.toDataURL("image/jpeg", 0.70).split(",")[1];
+                }, { data: cropped.toString("base64"), width: settings.width, height: settings.height });
+                const bytes = Buffer.from(resized, "base64");
+                encodedBytes += bytes.length;
+                if (encodedBytes > 12 * 1024 * 1024)
+                    throw new CliError("Capture exceeded the 12 MiB frame budget.", "STUDIO_CAPTURE_TOO_LARGE");
+                const filename = `${String(selected.id - 1).padStart(3, "0")}.jpg`;
+                await writeFile(path.join(root, "frames", filename), bytes);
+                frameImages.push({ data: bytes.toString("base64"), label: `${selected.id}  ${(atMs / 1000).toFixed(2)}s  ${selected.label}`, at_ms: atMs });
+            };
+            await sample();
+            while (Date.now() - started < settings.durationMs) {
+                await page.waitForTimeout(Math.min(125, settings.durationMs - (Date.now() - started)));
+                await sample();
+            }
+            await sample(true);
+            if (frameImages.length && sampler.checkpoints.length) {
+                const last = sampler.checkpoints.at(-1);
+                frameImages[frameImages.length - 1].label = `${last.id}  ${(last.at_ms / 1000).toFixed(2)}s  ${last.label}`;
+            }
+            const sheet = await page.evaluate(async (frames) => {
+                const columns = Math.min(3, frames.length);
+                const cellWidth = 320;
+                const cellHeight = 238;
+                const canvas = document.createElement("canvas");
+                canvas.width = columns * cellWidth;
+                canvas.height = Math.ceil(frames.length / columns) * cellHeight;
+                const context = canvas.getContext("2d");
+                if (!context)
+                    throw new Error("Canvas contact sheet is unsupported.");
+                context.fillStyle = "#ffffff";
+                context.fillRect(0, 0, canvas.width, canvas.height);
+                for (let index = 0; index < frames.length; index += 1) {
+                    const frame = frames[index];
+                    const image = new Image();
+                    image.src = `data:image/jpeg;base64,${frame.data}`;
+                    await image.decode();
+                    const x = (index % columns) * cellWidth;
+                    const y = Math.floor(index / columns) * cellHeight;
+                    context.drawImage(image, x, y, cellWidth, 210);
+                    context.fillStyle = "#111827";
+                    context.font = "14px sans-serif";
+                    context.fillText(frame.label.slice(0, 42), x + 8, y + 229);
+                }
+                return canvas.toDataURL("image/jpeg", 0.78).split(",")[1];
+            }, frameImages);
+            const sheetBytes = Buffer.from(sheet, "base64");
+            encodedBytes += sheetBytes.length;
+            if (encodedBytes > 16 * 1024 * 1024)
+                throw new CliError("Capture exceeded the 16 MiB package budget.", "STUDIO_CAPTURE_TOO_LARGE");
+            await read();
+            await writeFile(path.join(root, "contact-sheet.jpg"), sheetBytes);
+            const timeline = sampler.checkpoints.map(({ id, at_ms, label, observation }) => ({
+                frame: id, at_ms, label,
+                active_states: observation.active_states,
+                host_variables: observation.host_variables,
+                interactions: observation.interactions,
+                machine_dispatches: observation.machine_dispatches,
+                geometry_revision: observation.geometry_revision,
+                scene_clock_seconds: observation.scene_clock_seconds,
+            }));
+            const manifest = {
+                schema: "kheleshikhi.studio-preview-capture.v1", asset_id: request.asset,
+                source_hash: request.sourceHash, source_revision: revision,
+                base_revision_public_id: baseline.base_revision_public_id,
+                runtime_fingerprint: baseline.runtime_fingerprint,
+                preview_is_current_at_capture: true,
+                viewport: browserViewport, frame_size: dimensions,
+                settings, duration_ms: Math.min(Date.now() - started, settings.durationMs),
+                preview_bounds: clip,
+                checkpoints: sampler.checkpoints.length,
+                visual_source: "real Studio browser preview screenshot",
+                captured_at: new Date().toISOString(),
+            };
+            await writeFile(path.join(root, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+            await writeFile(path.join(root, "timeline.json"), `${JSON.stringify(timeline, null, 2)}\n`);
+            await writeFile(path.join(root, "observations.json"), `${JSON.stringify(sampler.checkpoints, null, 2)}\n`);
+            return { manifest, timeline, output: root, contact_sheet: path.join(root, "contact-sheet.jpg"), frames: path.join(root, "frames"), browser: preflight.browser };
+        }
+        catch (error) {
+            await rm(root, { recursive: true, force: true });
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=browser.js.map