@parity/product-lab 0.0.1-placeholder → 0.1.0

package/entrypoints/panel/src/visible/detached-window.js

@@ -0,0 +1,161 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { deviceContextOptions, deviceKind } from "./device-catalogue.js";
+import { cutInWorker, viewportShot } from "./viewport-shot.js";
+import { videoOpened } from "./window-video.js";
+export function detachedWindowClosed(actorName) {
+    return new Error(`${actorName}'s detached window was closed`);
+}
+export const FRAMING_REFUSED = "shown without the device frame: the app refuses framing";
+const BEZEL = 14;
+const MARGIN = 24;
+export async function openDetachedWindow(options) {
+    if (deviceKind(options.device) === "desktop")
+        return (await openWindow(options, "desktop"));
+    return (await openWindow(options, "framed")) ?? (await openWindow(options, "exact", FRAMING_REFUSED));
+}
+async function openWindow(options, mode, notice) {
+    const framed = mode === "framed";
+    const { viewport } = options.device;
+    const outer = framed ? { width: viewport.width + 2 * (BEZEL + MARGIN), height: viewport.height + 2 * (BEZEL + MARGIN) } : viewport;
+    const emulation = mode === "exact" ? deviceContextOptions(options.device) : {
+        viewport: null,
+        ...(options.device.userAgent ? { userAgent: options.device.userAgent } : {}),
+        ...(framed && options.device.touch ? { hasTouch: true } : {}),
+    };
+    const context = await options.browser.newContext({
+        ...emulation,
+        ...(options.recordVideo ? { recordVideo: { dir: options.recordVideo.dir, size: { ...outer } } } : {}),
+        ...(options.permissions?.length ? { permissions: [...options.permissions] } : {}),
+        ...(options.reducedMotion ? { reducedMotion: options.reducedMotion } : {}),
+    });
+    let gone = false;
+    const closed = new Promise((resolve) => context.once("close", () => { gone = true; resolve(); }));
+    try {
+        const page = await context.newPage();
+        if (options.recordVideo)
+            videoOpened(page);
+        page.once("close", () => { void context.close().catch(() => { }); });
+        if (mode !== "exact")
+            await sizeWindow(context, page, outer);
+        const timeout = options.loadTimeoutMs ?? 30_000;
+        let app = page.mainFrame();
+        let screen;
+        let shots;
+        if (framed) {
+            await pixelRatio(context, page, options.device.deviceScaleFactor);
+            shots = await context.newCDPSession(page);
+            await page.setContent(frameDocument(options.url, options.actor.name, options.device), { timeout, waitUntil: "load" });
+            screen = (await page.$("iframe#app")) ?? undefined;
+            const frame = await screen?.contentFrame();
+            if (!screen || !frame)
+                throw new Error(`${options.actor.name}'s detached window has no app frame`);
+            if (frame.url().startsWith("chrome-error:")) {
+                await context.close();
+                return undefined;
+            }
+            app = frame;
+            await pixelRatio(context, app, options.device.deviceScaleFactor);
+        }
+        else {
+            await page.goto(options.url, { timeout });
+        }
+        const appBox = async () => {
+            if (!screen) {
+                const size = await page.evaluate(() => ({ width: globalThis.innerWidth, height: globalThis.innerHeight }));
+                return { x: 0, y: 0, ...size, scale: 1 };
+            }
+            return screen.evaluate((element, device) => {
+                const box = element.getBoundingClientRect();
+                return { x: box.x, y: box.y, width: box.width, height: box.height, scale: box.width / device.width };
+            }, viewport);
+        };
+        const capture = async (captureOptions = {}) => {
+            const timeout = captureOptions.timeoutMs !== undefined ? { timeout: captureOptions.timeoutMs } : undefined;
+            if (!screen || !shots)
+                return viewportShot(page, undefined, timeout);
+            const [bytes, box, width] = await Promise.all([sessionShot(shots, captureOptions.timeoutMs ?? 30_000), appBox(), page.evaluate(() => globalThis.innerWidth)]);
+            return cutInWorker(bytes, width, { rect: { x: box.x, y: box.y, width: box.width, height: box.height }, fit: viewport });
+        };
+        return {
+            actor: { ...options.actor },
+            device: options.device,
+            context,
+            page,
+            app,
+            framed,
+            ...(notice ? { notice } : {}),
+            ...(options.recordVideo ? { videoSize: { ...outer } } : {}),
+            appBox,
+            capture,
+            closed,
+            isClosed: () => gone || page.isClosed(),
+            close: async () => {
+                if (!gone)
+                    await context.close();
+            },
+        };
+    }
+    catch (error) {
+        await context.close().catch(() => { });
+        throw error;
+    }
+}
+async function sizeWindow(context, page, size) {
+    const cdp = await context.newCDPSession(page);
+    try {
+        const { windowId } = (await cdp.send("Browser.getWindowForTarget"));
+        const bars = await page.evaluate(() => ({ width: window.outerWidth - window.innerWidth, height: window.outerHeight - window.innerHeight }));
+        await cdp.send("Browser.setWindowBounds", { windowId, bounds: { windowState: "normal" } });
+        await cdp.send("Browser.setWindowBounds", { windowId, bounds: { width: size.width + Math.max(0, bars.width), height: size.height + Math.max(0, bars.height) } });
+    }
+    finally {
+        await cdp.detach();
+    }
+}
+async function pixelRatio(context, target, deviceScaleFactor) {
+    let session;
+    try {
+        session = await context.newCDPSession(target);
+    }
+    catch (error) {
+        if ("page" in target && typeof target.page === "function")
+            return undefined;
+        throw error;
+    }
+    await session.send("Emulation.setDeviceMetricsOverride", { width: 0, height: 0, deviceScaleFactor, mobile: false });
+    return session;
+}
+async function sessionShot(session, timeoutMs) {
+    let timer;
+    const late = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`the detached window's capture took over ${timeoutMs} ms`)), timeoutMs);
+    });
+    try {
+        const { data } = await Promise.race([session.send("Page.captureScreenshot", { format: "png" }), late]);
+        return Buffer.from(data, "base64");
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function frameDocument(url, name, device) {
+    const escape = (text) => text.replace(/[&<>"]/g, (char) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[char]);
+    const { width, height } = device.viewport;
+    return `<!doctype html><html><head><meta charset="utf-8"><title>${escape(name)} · ${escape(device.name)}</title><style>
+html, body { margin: 0; height: 100%; background: #15161a; overflow: hidden; }
+.device { position: absolute; left: 50%; top: 50%; padding: ${BEZEL}px; border-radius: ${Math.round(BEZEL * 3)}px; background: #050506; box-shadow: 0 0 0 1px #3a3b42, 0 24px 64px rgb(0 0 0 / 0.55); transform: translate(-50%, -50%); transform-origin: center; }
+.device iframe { display: block; width: ${width}px; height: ${height}px; border: 0; border-radius: ${Math.round(BEZEL * 2)}px; background: #fff; }
+@media (prefers-color-scheme: light) { html, body { background: #e8e9ee; } .device { box-shadow: 0 0 0 1px #b9bac3, 0 24px 64px rgb(0 0 0 / 0.22); } }
+</style></head><body><div class="device" id="device" data-device="${escape(device.name)}"><iframe id="app" title="${escape(name)}" src="${escape(url)}" allow="camera; microphone; clipboard-read; clipboard-write; geolocation"></iframe></div>
+<script>
+const device = document.getElementById("device");
+const fit = () => {
+  const scale = Math.min(1, (innerWidth - ${2 * MARGIN}) / device.offsetWidth, (innerHeight - ${2 * MARGIN}) / device.offsetHeight);
+  device.style.transform = "translate(-50%, -50%) scale(" + Math.max(0.1, scale) + ")";
+  device.dataset.scale = String(Math.max(0.1, scale));
+};
+addEventListener("resize", fit);
+fit();
+</script></body></html>`;
+}

package/entrypoints/panel/src/visible/device-catalogue.d.ts

@@ -0,0 +1,12 @@
+import { type BrowserContextOptions } from "playwright";
+import { type DeviceChoice, type DeviceProfile } from "@parity/product-lab/domain/devices";
+/** Every named device: the desktop window, then Playwright's registry (landscape variants included). */
+export declare function deviceCatalogue(): Readonly<Record<string, DeviceProfile>>;
+/** Phones, tablets or desktops: a mobile device whose shorter side is 600 CSS pixels or more is a tablet. */
+export declare function deviceKind(profile: DeviceProfile): "phone" | "tablet" | "desktop";
+/** Every device name: phones, then tablets, then the desktop window and other desktops; landscape after portrait. */
+export declare function deviceNames(): string[];
+/** A name or written-out profile as the device a window opens with; an unknown name throws with the nearest names. */
+export declare function deviceFor(choice: DeviceChoice | undefined, at?: string): DeviceProfile;
+/** The browser context options that emulate `profile` (fixed for the context's life). */
+export declare function deviceContextOptions(profile: DeviceProfile): BrowserContextOptions;

package/entrypoints/panel/src/visible/device-catalogue.js

@@ -0,0 +1,40 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { devices } from "playwright";
+import { DESKTOP_DEVICE, resolveDevice } from "@parity/product-lab/domain/devices";
+let catalogue;
+export function deviceCatalogue() {
+    catalogue ??= Object.freeze({
+        [DESKTOP_DEVICE.name]: DESKTOP_DEVICE,
+        ...Object.fromEntries(Object.entries(devices).map(([name, device]) => [
+            name,
+            { name, viewport: { ...device.viewport }, deviceScaleFactor: device.deviceScaleFactor, mobile: device.isMobile, touch: device.hasTouch, userAgent: device.userAgent },
+        ])),
+    });
+    return catalogue;
+}
+export function deviceKind(profile) {
+    if (!profile.mobile)
+        return "desktop";
+    return Math.min(profile.viewport.width, profile.viewport.height) >= 600 ? "tablet" : "phone";
+}
+export function deviceNames() {
+    const order = { phone: 0, tablet: 1, desktop: 2 };
+    const entries = Object.entries(deviceCatalogue()).map(([name, profile], index) => ({ name, index, kind: order[deviceKind(profile)], landscape: / landscape$/.test(name) ? 1 : 0, desktop: name === DESKTOP_DEVICE.name ? 0 : 1 }));
+    return entries.sort((a, b) => a.kind - b.kind || a.desktop - b.desktop || a.landscape - b.landscape || a.index - b.index).map((entry) => entry.name);
+}
+export function deviceFor(choice, at = "device") {
+    const resolved = resolveDevice(choice ?? DESKTOP_DEVICE.name, deviceCatalogue(), at);
+    if ("problem" in resolved)
+        throw new Error(resolved.problem);
+    return resolved.profile;
+}
+export function deviceContextOptions(profile) {
+    return {
+        viewport: { ...profile.viewport },
+        deviceScaleFactor: profile.deviceScaleFactor,
+        isMobile: profile.mobile,
+        hasTouch: profile.touch,
+        ...(profile.userAgent ? { userAgent: profile.userAgent } : {}),
+    };
+}

package/entrypoints/panel/src/visible/embedded-host.d.ts

@@ -0,0 +1,6 @@
+import type { ActorHost } from "@parity/product-lab/domain";
+/** Why `actor` cannot be driven in this window, or undefined when nothing stands in the way. */
+export declare function unhostedEmbeddedApp(actor: {
+    readonly name: string;
+    readonly host?: ActorHost;
+}, tileShowsHostPage: boolean): string | undefined;

package/entrypoints/panel/src/visible/embedded-host.js

@@ -0,0 +1,8 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export function unhostedEmbeddedApp(actor, tileShowsHostPage) {
+    if (!actor.host?.embedsApp || tileShowsHostPage)
+        return undefined;
+    return (`${actor.name} is on the ${actor.host.label} host, which shows the app inside its own page, but ${actor.name}'s tile shows the app without that page, ` +
+        `so the app has no host to answer it. Run it in Background, where ${actor.name}'s host shows the app in its own page.`);
+}

package/entrypoints/panel/src/visible/frame-locations.d.ts

@@ -0,0 +1,15 @@
+import type { Page } from "playwright";
+/** The shell window event (address-bar.ts `FRAME_LOCATION_EVENT`). */
+export declare const FRAME_LOCATION_EVENT = "product-lab:frame-location";
+export interface FrameLocation {
+    actor: string;
+    frame: string;
+    url: string;
+}
+/**
+ * Report every navigation of the shell's actor iframes to the shell, in order, while the shell is on `origin`.
+ * Frames without `data-actor`/`data-frame` (for example an app's own nested frames) are ignored. Backlog 108: a tile
+ * showing a person's host page (`hosted`) reports the app's frame inside it, never the host page's own address.
+ * Returns a function that stops reporting.
+ */
+export declare function reportFrameLocations(page: Page, origin: string, hosted?: (actor: string) => boolean): () => void;

package/entrypoints/panel/src/visible/frame-locations.js

@@ -0,0 +1,29 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export const FRAME_LOCATION_EVENT = "product-lab:frame-location";
+export function reportFrameLocations(page, origin, hosted = () => false) {
+    let queue = Promise.resolve();
+    const listener = (frame) => {
+        const parent = frame.parentFrame();
+        const tile = parent === page.mainFrame() ? frame : parent?.parentFrame() === page.mainFrame() ? parent : null;
+        if (!tile)
+            return;
+        const url = frame.url();
+        if (!/^https?:\/\//.test(url))
+            return;
+        queue = queue.then(async () => {
+            const element = await tile.frameElement();
+            const ids = await element.evaluate((node) => ({ actor: node.getAttribute("data-actor"), frame: node.getAttribute("data-frame") }));
+            await element.dispose();
+            if (!ids.actor || !ids.frame || new URL(page.mainFrame().url()).origin !== origin)
+                return;
+            if ((frame === tile) === hosted(ids.actor))
+                return;
+            const location = { actor: ids.actor, frame: ids.frame, url };
+            await page.mainFrame().evaluate(([name, detail]) => { window.dispatchEvent(new CustomEvent(name, { detail })); }, [FRAME_LOCATION_EVENT, location]);
+        }).catch(() => {
+        });
+    };
+    page.on("framenavigated", listener);
+    return () => { page.off("framenavigated", listener); };
+}

package/entrypoints/panel/src/visible/index.d.ts

@@ -0,0 +1,13 @@
+export { LAB_WINDOW_MEDIA_ARGS, labWindowArgs, labWindowCursor, openLabWindow, type LabWindow, type LabWindowOptions } from "./window.js";
+export { withSyntheticMedia } from "@parity/product-lab/domain/devices";
+export { actorFrameSelector, attachLabRunner, attachRunner, RUNNER_BINDING, FEATURE_BINDING, TOOL_BINDING, BUILDER_BINDING, CURSOR_BINDING, parseCursorMode, type CursorMode, type LabBuilderRunRequest, type JournalEntry, type LabFeatureRunRequest, type LabFeatureRunResult, type LabToolRunRequest, type LabRunner, type LabRunnerOptions, type LabRunRequest, type LabRunResult, type Refusal, type RegisteredAction, type Runner, type RunnerOptions, type RunnerRequest, } from "./runner.js";
+export { visibleAppSurface, type VisibleSurfaceOptions } from "./app-ui.js";
+export { windowFrameCapture } from "./window-frames.js";
+export { deviceCatalogue } from "./device-catalogue.js";
+export { activeRunIds, RUN_VIEW_TIMEOUT_MS, runViewSync, type RunViewOptions, type RunViewResult } from "./run-view.js";
+export { FRAME_RELOAD_TIMEOUT_MS, labWindowFrameReloader } from "./app-reload.js";
+export { summarizeUiCalls, type UiActorTiming, type UiCall, type UiCallSegment, type UiCallSummary, type UiCallTiming, type UiPhase } from "./ui-timing.js";
+export { UI_CALL_EVENT, UI_CALLS_BINDING, uiActivityFeed, type UiActivityCall, type UiActivityFeed, type UiActivitySegment } from "./ui-activity.js";
+export { describeTarget } from "./app-ui.js";
+export { FRAME_LOCATION_EVENT, reportFrameLocations, type FrameLocation } from "./frame-locations.js";
+export { assertFrameDisplayed, CURSOR_SPEEDS, cursorGlideMs, FRAME_DISPLAY_WAIT_MS, LANE_TARGET_TIMEOUT_MS, showRing, visibleUi, waitForFrameDisplayed, type Box, type CursorSpec, type CursorSpeed, type VisibleOptions, type VisibleUi } from "./visible-ui.js";

package/entrypoints/panel/src/visible/index.js

@@ -0,0 +1,15 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export { LAB_WINDOW_MEDIA_ARGS, labWindowArgs, labWindowCursor, openLabWindow } from "./window.js";
+export { withSyntheticMedia } from "@parity/product-lab/domain/devices";
+export { actorFrameSelector, attachLabRunner, attachRunner, RUNNER_BINDING, FEATURE_BINDING, TOOL_BINDING, BUILDER_BINDING, CURSOR_BINDING, parseCursorMode, } from "./runner.js";
+export { visibleAppSurface } from "./app-ui.js";
+export { windowFrameCapture } from "./window-frames.js";
+export { deviceCatalogue } from "./device-catalogue.js";
+export { activeRunIds, RUN_VIEW_TIMEOUT_MS, runViewSync } from "./run-view.js";
+export { FRAME_RELOAD_TIMEOUT_MS, labWindowFrameReloader } from "./app-reload.js";
+export { summarizeUiCalls } from "./ui-timing.js";
+export { UI_CALL_EVENT, UI_CALLS_BINDING, uiActivityFeed } from "./ui-activity.js";
+export { describeTarget } from "./app-ui.js";
+export { FRAME_LOCATION_EVENT, reportFrameLocations } from "./frame-locations.js";
+export { assertFrameDisplayed, CURSOR_SPEEDS, cursorGlideMs, FRAME_DISPLAY_WAIT_MS, LANE_TARGET_TIMEOUT_MS, showRing, visibleUi, waitForFrameDisplayed } from "./visible-ui.js";

package/entrypoints/panel/src/visible/mirror.d.ts

@@ -0,0 +1,41 @@
+import type { Page } from "playwright";
+/** One frame of a detached window, as the tile shows it. */
+export interface MirrorFrame {
+    readonly actor: string;
+    /** A JPEG, base64. */
+    readonly data: string;
+    /** The window's viewport in CSS pixels when the frame was painted. */
+    readonly width: number;
+    readonly height: number;
+    /** When it was painted (ms since the epoch). */
+    readonly at: number;
+}
+export interface MirrorOptions {
+    actor: string;
+    /** Delivers a frame; the next one waits for it (newer frames replace a waiting one). */
+    onFrame(frame: MirrorFrame): void | Promise<void>;
+    /** The mirror stopped on its own (the window closed, the screencast ended); `reason` says why. */
+    onStopped?(reason: string): void;
+    /** Largest frame size in device pixels (default 800x1000: a tile, not a full screen). */
+    maxWidth?: number;
+    maxHeight?: number;
+    /** At most one frame per this many ms (default 100: 10 a second). */
+    minIntervalMs?: number;
+    /** JPEG quality, 0 to 100 (default 60). */
+    quality?: number;
+}
+export interface Mirror {
+    /** Frames delivered so far. */
+    readonly frames: number;
+    /** When the last delivered frame was painted. */
+    readonly lastFrameAt: number | undefined;
+    /** Why the mirror stopped, once it has. */
+    readonly stopped: string | undefined;
+    /** The last delivery that failed, if one did. */
+    readonly deliveryError: string | undefined;
+    stop(): Promise<void>;
+}
+/** Why `page` cannot be mirrored, or undefined when it can (a Chromium page). */
+export declare function mirrorUnavailable(page: Page): string | undefined;
+/** Start mirroring `page`. Throws when the browser has no screencast. */
+export declare function startMirror(page: Page, options: MirrorOptions): Promise<Mirror>;

package/entrypoints/panel/src/visible/mirror.js

@@ -0,0 +1,100 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export function mirrorUnavailable(page) {
+    const name = page.context().browser()?.browserType().name();
+    return name === "chromium" ? undefined : `The live mirror needs Chromium's DevTools screencast; this browser (${name ?? "unknown"}) has none`;
+}
+export async function startMirror(page, options) {
+    const unavailable = mirrorUnavailable(page);
+    if (unavailable)
+        throw new Error(unavailable);
+    const session = await page.context().newCDPSession(page);
+    const minInterval = options.minIntervalMs ?? 100;
+    let frames = 0;
+    let lastFrameAt;
+    let lastDeliveredMs = 0;
+    let stopped;
+    let deliveryError;
+    let delivering = false;
+    let waiting;
+    const pump = async () => {
+        if (delivering)
+            return;
+        delivering = true;
+        try {
+            while (waiting && !stopped) {
+                const wait = lastDeliveredMs + minInterval - Date.now();
+                if (wait > 0)
+                    await new Promise((resolve) => setTimeout(resolve, wait));
+                const frame = waiting;
+                waiting = undefined;
+                if (!frame || stopped)
+                    break;
+                lastDeliveredMs = Date.now();
+                try {
+                    await options.onFrame(frame);
+                    frames++;
+                    lastFrameAt = frame.at;
+                }
+                catch (error) {
+                    deliveryError = error instanceof Error ? error.message : String(error);
+                }
+            }
+        }
+        finally {
+            delivering = false;
+        }
+    };
+    const end = (reason) => {
+        if (stopped)
+            return;
+        stopped = reason;
+        waiting = undefined;
+        options.onStopped?.(reason);
+    };
+    session.on("Page.screencastFrame", (event) => {
+        session.send("Page.screencastFrameAck", { sessionId: event.sessionId }).catch(() => undefined);
+        if (stopped)
+            return;
+        const frame = {
+            actor: options.actor,
+            data: event.data,
+            width: event.metadata.deviceWidth,
+            height: event.metadata.deviceHeight,
+            at: event.metadata.timestamp !== undefined ? Math.round(event.metadata.timestamp * 1000) : Date.now(),
+        };
+        waiting = frame;
+        void pump();
+    });
+    page.once("close", () => end("the detached window was closed"));
+    session.on("Inspector.detached", () => end("the screencast ended"));
+    await session.send("Page.startScreencast", {
+        format: "jpeg",
+        quality: options.quality ?? 60,
+        maxWidth: options.maxWidth ?? 800,
+        maxHeight: options.maxHeight ?? 1000,
+    });
+    return {
+        get frames() {
+            return frames;
+        },
+        get lastFrameAt() {
+            return lastFrameAt;
+        },
+        get stopped() {
+            return stopped;
+        },
+        get deliveryError() {
+            return deliveryError;
+        },
+        async stop() {
+            if (stopped)
+                return;
+            end("stopped by the lab");
+            if (page.isClosed())
+                return;
+            await session.send("Page.stopScreencast");
+            await session.detach();
+        },
+    };
+}

package/entrypoints/panel/src/visible/png-parts.d.ts

@@ -0,0 +1,33 @@
+import { PNG } from "pngjs";
+export interface ShotRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** One part to cut: `rect` in CSS pixels; with `fit`, brought to that viewport (CSS pixels) at the capture's ratio. */
+export interface PartRequest {
+    rect: ShotRect;
+    fit?: {
+        width: number;
+        height: number;
+    };
+}
+/** `rect` (CSS pixels) of an image taken at `ratio` device pixels per CSS pixel, at those device pixels. */
+export declare function cut(image: PNG, ratio: number, rect: ShotRect): PNG;
+/**
+ * A cut part as PNG bytes. One row filter (Paeth) rather than pngjs's default of trying all five on every row: a lab
+ * tile at 2x encodes in about a third of the time (3 tiles: 31 ms, not 80) for 2% more bytes (5 October 2026).
+ */
+export declare function encodePng(image: PNG): Buffer;
+/** `image` at `size` (bilinear): a scaled frame's app brought back to the device's own pixel size. */
+export declare function resample(image: PNG, size: {
+    width: number;
+    height: number;
+}): PNG;
+/**
+ * One part of a decoded capture of a viewport `viewportWidth` CSS pixels wide, as PNG bytes. With `fit`, the part is
+ * brought to that viewport at the capture's ratio when it was drawn scaled (a detached phone's frame shown smaller);
+ * never scaled up beyond what the window drew.
+ */
+export declare function cutPart(whole: PNG, viewportWidth: number, part: PartRequest): Buffer;

package/entrypoints/panel/src/visible/png-parts.js

@@ -0,0 +1,38 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { PNG } from "pngjs";
+export function cut(image, ratio, rect) {
+    const left = Math.min(image.width - 1, Math.max(0, Math.round(rect.x * ratio)));
+    const top = Math.min(image.height - 1, Math.max(0, Math.round(rect.y * ratio)));
+    const width = Math.max(1, Math.min(Math.round(rect.width * ratio), image.width - left));
+    const height = Math.max(1, Math.min(Math.round(rect.height * ratio), image.height - top));
+    const out = new PNG({ width, height });
+    PNG.bitblt(image, out, left, top, width, height, 0, 0);
+    return out;
+}
+export function encodePng(image) {
+    return PNG.sync.write(image, { filterType: 4 });
+}
+export function resample(image, size) {
+    const out = new PNG(size);
+    const sx = image.width / size.width, sy = image.height / size.height;
+    for (let y = 0; y < size.height; y++) {
+        const fy = Math.min(image.height - 1, Math.max(0, (y + 0.5) * sy - 0.5)), y0 = Math.floor(fy), y1 = Math.min(image.height - 1, y0 + 1), wy = fy - y0;
+        for (let x = 0; x < size.width; x++) {
+            const fx = Math.min(image.width - 1, Math.max(0, (x + 0.5) * sx - 0.5)), x0 = Math.floor(fx), x1 = Math.min(image.width - 1, x0 + 1), wx = fx - x0;
+            for (let c = 0; c < 4; c++) {
+                const at = (px, py) => image.data[(py * image.width + px) * 4 + c];
+                out.data[(y * size.width + x) * 4 + c] = Math.round((at(x0, y0) * (1 - wx) + at(x1, y0) * wx) * (1 - wy) + (at(x0, y1) * (1 - wx) + at(x1, y1) * wx) * wy);
+            }
+        }
+    }
+    return out;
+}
+export function cutPart(whole, viewportWidth, part) {
+    const ratio = whole.width / viewportWidth;
+    const piece = cut(whole, ratio, part.rect);
+    if (!part.fit)
+        return encodePng(piece);
+    const size = { width: Math.round(part.fit.width * ratio), height: Math.round(part.fit.height * ratio) };
+    return encodePng(Math.abs(piece.width - size.width) <= 1 && Math.abs(piece.height - size.height) <= 1 ? piece : resample(piece, size));
+}

package/entrypoints/panel/src/visible/png-work.d.ts

@@ -0,0 +1,14 @@
+import { type PartRequest } from "./png-parts.js";
+export interface PngTask {
+    id: number;
+    bytes: Uint8Array;
+    viewportWidth: number;
+    parts: PartRequest[];
+}
+export type PngReply = {
+    id: number;
+    parts: Uint8Array[];
+} | {
+    id: number;
+    error: string;
+};

package/entrypoints/panel/src/visible/png-work.js

@@ -0,0 +1,15 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { parentPort } from "node:worker_threads";
+import { PNG } from "pngjs";
+import { cutPart } from "./png-parts.js";
+parentPort.on("message", (task) => {
+    try {
+        const whole = PNG.sync.read(Buffer.from(task.bytes.buffer, task.bytes.byteOffset, task.bytes.byteLength));
+        const parts = task.parts.map((part) => new Uint8Array(cutPart(whole, task.viewportWidth, part)));
+        parentPort.postMessage({ id: task.id, parts }, parts.map((part) => part.buffer));
+    }
+    catch (error) {
+        parentPort.postMessage({ id: task.id, error: error instanceof Error ? error.message : String(error) });
+    }
+});

package/entrypoints/panel/src/visible/png-worker.mjs

@@ -0,0 +1,13 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+// The PNG worker's entry (viewport-shot.ts, `cutInWorker`). Plain JavaScript: a worker thread does not inherit the tsx
+// registration the CLI makes through tsx's API (bin/product-lab.mjs), so it registers tsx itself when the TypeScript
+// body cannot load (under `node --import tsx` the worker inherits the flag and loads it directly).
+try {
+  await import("./png-work.js");
+} catch (error) {
+  if (error?.code !== "ERR_UNKNOWN_FILE_EXTENSION") throw error;
+  const { register } = await import("tsx/esm/api");
+  register();
+  await import("./png-work.js");
+}

package/entrypoints/panel/src/visible/run-view.d.ts

@@ -0,0 +1,37 @@
+import type { Page } from "playwright";
+import type { LabSnapshot } from "@parity/product-lab/ports/driving";
+/** How long the runner waits for the shell to draw the run view before it goes on without it. */
+export declare const RUN_VIEW_TIMEOUT_MS = 5000;
+/** The ids of the runs acting now in the runtime's snapshot (the shell's `activeRuns`, views.ts). */
+export declare function activeRunIds(snapshot: {
+    job?: LabSnapshot["job"];
+    jobs: LabSnapshot["jobs"];
+}): string[];
+/** What one sync did, for the call's timing and for tests. */
+export interface RunViewResult {
+    /** The active runs asked for (empty: nothing acts, nothing was asked). */
+    runs: string[];
+    /** `drawn`: the shell drew a snapshot with them; `current`: already drawn for them; `unavailable`: no shell function; `timeout`; `failed`. */
+    outcome: "drawn" | "current" | "none" | "unavailable" | "timeout" | "failed";
+    /** Time spent in this call, lane wait included. */
+    ms: number;
+    error?: string;
+}
+export interface RunViewOptions {
+    page: Pick<Page, "evaluate">;
+    /** The active run ids now (the runtime's snapshot). */
+    runs: () => string[];
+    /** The window's input lane. */
+    lane: <T>(work: () => Promise<T>) => Promise<T>;
+    timeoutMs?: number;
+    now?: () => number;
+    /** Every sync that asked the shell, as it settles. */
+    onSync?: (result: RunViewResult) => void;
+}
+/**
+ * Returns `sync()`: before a gesture, make sure the shell has drawn the view of the runs acting now. The first gesture of
+ * a new set of active runs asks the shell once (concurrent gestures share the request); later gestures of the same runs
+ * cost nothing. A shell without the function, a timeout or a failure is not retried for that set: the gesture's own
+ * frame and hit checks still guard the input, only the ring or cursor may be drawn before the switch.
+ */
+export declare function runViewSync(options: RunViewOptions): () => Promise<RunViewResult>;