@parity/product-lab 0.0.1-placeholder → 0.1.0

package/entrypoints/panel/src/visible/visible-ui.js

@@ -0,0 +1,429 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { typeVerified } from "./verified-typing.js";
+export const CURSOR_SPEEDS = { slow: 700, normal: 350, fast: 150 };
+export function cursorGlideMs(speed, visibleDelayMs) {
+    const wanted = typeof speed === "number" ? speed : CURSOR_SPEEDS[speed];
+    return Math.max(0, Math.min(wanted, visibleDelayMs));
+}
+const untimed = (_step, work) => work();
+export const LANE_TARGET_TIMEOUT_MS = 5_000;
+function moveCursor(page, key, spec, point, glideMs, click) {
+    page.evaluate(({ key, name, point, glideMs, click }) => {
+        window.__productLabCursor?.(key, point, { name, glideMs, click });
+    }, { key, name: spec.name, point, glideMs, click }).catch(() => {
+    });
+}
+export async function showRing(page, box, key) {
+    await page.evaluate(({ value, key }) => {
+        const host = window;
+        if (!host.__productLabRing) {
+            const rings = new Map();
+            host.__productLabRing = (next, name) => {
+                let element = rings.get(name ?? "");
+                if (!element) {
+                    element = document.createElement("div");
+                    element.setAttribute("data-product-lab-ring", name ?? "");
+                    Object.assign(element.style, {
+                        position: "fixed",
+                        pointerEvents: "none",
+                        border: "3px solid #ff3b7f",
+                        borderRadius: "10px",
+                        boxShadow: "0 0 0 4px rgba(255,59,127,.25)",
+                        zIndex: "2147483647",
+                        display: "none",
+                    });
+                    document.body.append(element);
+                    rings.set(name ?? "", element);
+                }
+                const b = next;
+                if (!b) {
+                    element.style.display = "none";
+                    return;
+                }
+                Object.assign(element.style, {
+                    display: "block",
+                    left: `${b.x - 4}px`,
+                    top: `${b.y - 4}px`,
+                    width: `${b.width + 8}px`,
+                    height: `${b.height + 8}px`,
+                });
+            };
+        }
+        host.__productLabRing(value, key ?? undefined);
+    }, { value: box, key: key ?? null });
+}
+function spotInFrame(element, keyboard) {
+    element.scrollIntoView({ block: "nearest", inline: "nearest" });
+    const rect = element.getBoundingClientRect();
+    const documentTarget = keyboard === true && (element === document.body || element === document.documentElement);
+    let left = documentTarget ? Math.max(0, rect.left) : rect.left;
+    let top = documentTarget ? Math.max(0, rect.top) : rect.top;
+    let width = documentTarget ? Math.max(0, Math.min(document.documentElement.clientWidth, rect.right) - left) : rect.width;
+    let height = documentTarget ? Math.max(0, Math.min(document.documentElement.clientHeight, rect.bottom) - top) : rect.height;
+    let documentFocus;
+    if (documentTarget) {
+        const interactive = 'a[href],area[href],button,input,select,textarea,summary,iframe,object,embed,[tabindex],[contenteditable]:not([contenteditable="false"]),[onclick],[onmousedown],[onpointerdown],[role="button"],[role="link"],[role="textbox"],[role="checkbox"],[role="radio"],[role="switch"],[role="combobox"],[role="menuitem"],[role="option"],[role="slider"],[role="spinbutton"],[role="tab"]';
+        for (const [rx, ry] of [[.5, .5], [.1, .1], [.9, .1], [.1, .9], [.9, .9], [.5, .1], [.5, .9], [.1, .5], [.9, .5]]) {
+            const x = left + width * rx, y = top + height * ry;
+            const hit = document.elementFromPoint(x, y);
+            if (!hit || !element.contains(hit) || hit.closest(interactive))
+                continue;
+            let safe = true;
+            for (let node = hit; node; node = node.parentElement) {
+                if (getComputedStyle(node).cursor === "pointer") {
+                    safe = false;
+                    break;
+                }
+            }
+            if (safe) {
+                documentFocus = { x, y };
+                break;
+            }
+        }
+        if (documentFocus) {
+            left = documentFocus.x - .5;
+            top = documentFocus.y - .5;
+            width = height = 1;
+        }
+    }
+    const animating = document.getAnimations().some((animation) => {
+        const target = animation.effect instanceof KeyframeEffect ? animation.effect.target : null;
+        return animation.playState === "running" && target instanceof Element && target.contains(element) && animation.effect.getComputedTiming().endTime !== Infinity;
+    });
+    const host = window;
+    host.__productLabDocument ??= `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+    return {
+        x: left, y: top, width, height, boxless: element.getClientRects().length === 0 || width <= 0 || height <= 0,
+        nested: window.parent !== window.top, animating, viewWidth: document.documentElement.clientWidth, viewHeight: document.documentElement.clientHeight,
+        document: host.__productLabDocument,
+        documentFocus, noNeutralPoint: documentTarget && !documentFocus,
+    };
+}
+function neutralDocumentPoint(element, arg) {
+    const point = arg;
+    const host = window;
+    if ((element !== document.body && element !== document.documentElement) || host.__productLabDocument !== point.document)
+        return null;
+    const hit = document.elementFromPoint(point.x, point.y);
+    const interactive = 'a[href],area[href],button,input,select,textarea,summary,iframe,object,embed,[tabindex],[contenteditable]:not([contenteditable="false"]),[onclick],[onmousedown],[onpointerdown],[role="button"],[role="link"],[role="textbox"],[role="checkbox"],[role="radio"],[role="switch"],[role="combobox"],[role="menuitem"],[role="option"],[role="slider"],[role="spinbutton"],[role="tab"]';
+    if (!hit || !element.contains(hit) || hit.closest(interactive))
+        return null;
+    for (let node = hit; node; node = node.parentElement)
+        if (getComputedStyle(node).cursor === "pointer")
+            return null;
+    const rect = element.getBoundingClientRect();
+    return { x: point.x - rect.left - element.clientLeft, y: point.y - rect.top - element.clientTop };
+}
+const documentMarks = new WeakMap();
+async function documentMark(frame, fresh = false) {
+    const known = documentMarks.get(frame);
+    if (!fresh && known && known.url === frame.url())
+        return known.mark;
+    const url = frame.url();
+    const mark = await frame.evaluate(() => {
+        const host = window;
+        return (host.__productLabDocument ??= `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`);
+    });
+    documentMarks.set(frame, { url, mark });
+    return mark;
+}
+async function probeInPage(request) {
+    const host = window;
+    if (request.reveal !== null)
+        host.__productLabReveal?.(request.reveal);
+    const frames = document.querySelectorAll(request.selector);
+    const frame = frames[0];
+    if (request.frameCheck) {
+        if (frames.length !== 1) {
+            const actor = /\[data-actor=("(?:[^"\\]|\\.)*")\]/.exec(request.selector)?.[1];
+            const refused = actor && !frames.length ? document.querySelector(`#application [data-frame-refused][data-actor=${actor}]`) : null;
+            const why = refused?.getAttribute("data-frame-refused");
+            return { refusal: why ? `${why} Watch drives the app in its frame, so it cannot run this step; run it in the background.` : `No displayed app frame matches ${request.selector}` };
+        }
+        const rect = frame.getBoundingClientRect();
+        if (rect.width < 1 || rect.height < 1)
+            return { refusal: `The app frame ${request.selector} has no visible box` };
+        if (document.elementFromPoint(rect.x + rect.width / 2, rect.y + rect.height / 2) !== frame)
+            return { refusal: `The app frame ${request.selector} is hidden or covered` };
+        if (!request.spot && !request.box)
+            return { box: { x: rect.x, y: rect.y, width: rect.width, height: rect.height } };
+    }
+    let box = request.box;
+    if (!box && request.spot) {
+        const spot = request.spot;
+        if (!frame || !(frame instanceof HTMLElement))
+            return { box: { x: -1, y: -1, width: spot.width, height: spot.height }, shown: false };
+        const deadline = Date.now() + request.settleMs;
+        let placed = frame.getBoundingClientRect();
+        let rect = placed;
+        for (;;) {
+            await new Promise((resolve) => { requestAnimationFrame(resolve); setTimeout(resolve, 250); });
+            rect = frame.getBoundingClientRect();
+            const animating = document.getAnimations().some((animation) => {
+                const target = animation.effect instanceof KeyframeEffect ? animation.effect.target : null;
+                return animation.playState === "running" && target instanceof Element && target.contains(frame);
+            });
+            if (Date.now() >= deadline) {
+                if (animating)
+                    return { moved: true };
+                break;
+            }
+            if (!animating && rect.x === placed.x && rect.y === placed.y && rect.width === placed.width && rect.height === placed.height)
+                break;
+            placed = rect;
+        }
+        const scaleX = frame.offsetWidth > 0 ? rect.width / frame.offsetWidth : 1;
+        const scaleY = frame.offsetHeight > 0 ? rect.height / frame.offsetHeight : 1;
+        if (Math.abs(scaleX - scaleY) > 0.002 * Math.max(1, scaleX))
+            return { transformed: true };
+        const scale = Math.abs(scaleX - 1) > 0.001 ? (scaleX + scaleY) / 2 : 1;
+        const style = getComputedStyle(frame);
+        const [padX, padY] = [parseFloat(style.paddingLeft) + parseFloat(style.paddingRight), parseFloat(style.paddingTop) + parseFloat(style.paddingBottom)];
+        if (Math.abs(frame.clientWidth - padX - spot.viewWidth) > 1 || Math.abs(frame.clientHeight - padY - spot.viewHeight) > 1)
+            return { moved: true };
+        const left = rect.left + (frame.clientLeft + parseFloat(style.paddingLeft)) * scale;
+        const top = rect.top + (frame.clientTop + parseFloat(style.paddingTop)) * scale;
+        box = { x: left + spot.x * scale, y: top + spot.y * scale, width: spot.width * scale, height: spot.height * scale };
+    }
+    if (!box)
+        return {};
+    const x = box.x + box.width / 2;
+    const y = box.y + box.height / 2;
+    const hit = document.elementFromPoint(x, y);
+    const shown = hit !== null && hit === document.querySelector(request.selector);
+    if (!shown)
+        return { box, shown };
+    let ringDrawn = false;
+    if (request.ring && host.__productLabRing) {
+        host.__productLabRing(box, request.ring.key ?? undefined);
+        ringDrawn = true;
+    }
+    if (request.cursor)
+        host.__productLabCursor?.(request.cursor.key, { x, y }, { name: request.cursor.name, glideMs: request.cursor.glideMs, click: false });
+    return { box, shown, ringDrawn };
+}
+async function probe(page, request) {
+    const result = await page.evaluate(probeInPage, request);
+    if (result.refusal)
+        throw new Error(result.refusal);
+    return result;
+}
+export async function assertFrameDisplayed(page, iframeSelector, tile) {
+    const { box } = await probe(page, { selector: iframeSelector, reveal: tile ?? null, frameCheck: true, spot: null, box: null, ring: null, cursor: null, settleMs: 0 });
+    return box;
+}
+export const FRAME_DISPLAY_WAIT_MS = 5_000;
+export async function waitForFrameDisplayed(page, iframeSelector, tile, timeoutMs = FRAME_DISPLAY_WAIT_MS) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        try {
+            return await assertFrameDisplayed(page, iframeSelector, tile);
+        }
+        catch (error) {
+            if (Date.now() >= deadline)
+                throw error;
+            await page.waitForTimeout(100);
+        }
+    }
+}
+let frameMarks = 0;
+export function displayedFrame(page, selector, inner) {
+    let known;
+    const app = async (frame) => {
+        if (!frame || inner === undefined)
+            return frame;
+        const handle = await frame.$(inner).catch(() => null);
+        try {
+            return (await handle?.contentFrame()) ?? null;
+        }
+        finally {
+            await handle?.dispose().catch(() => undefined);
+        }
+    };
+    const tile = async () => {
+        if (known && !known.frame.isDetached()) {
+            const same = await page.evaluate(({ selector, mark }) => {
+                const nodes = document.querySelectorAll(selector);
+                return nodes.length === 1 && (nodes[0].__productLabFrameMarks?.has(mark) ?? false);
+            }, { selector, mark: known.mark });
+            if (same && !known.frame.isDetached())
+                return known.frame;
+        }
+        known = undefined;
+        const elements = await page.locator(selector).elementHandles();
+        try {
+            const element = elements[0];
+            const frame = await element?.contentFrame();
+            if (!element || !frame)
+                return null;
+            const mark = String(++frameMarks);
+            await element.evaluate((node, value) => {
+                const marked = node;
+                (marked.__productLabFrameMarks ??= new Set()).add(value);
+            }, mark);
+            known = { mark, frame };
+            return frame;
+        }
+        finally {
+            await Promise.all(elements.map((element) => element.dispose().catch(() => {
+            })));
+        }
+    };
+    return async () => app(await tile());
+}
+export function visibleUi(page, iframeSelector, options = {}) {
+    const delay = options.visibleDelayMs ?? 0;
+    const bound = options.laneTimeoutMs ?? LANE_TARGET_TIMEOUT_MS;
+    if (!Number.isFinite(bound) || bound <= 0)
+        throw new RangeError("laneTimeoutMs must be a finite positive number");
+    const lane = (work) => (options.input ? options.input(work) : work());
+    const time = options.timeStep ?? untimed;
+    const keyboardDisplayed = options.displayed ?? displayedFrame(page, iframeSelector);
+    const ring = (box) => showRing(page, box, options.ring);
+    const hold = () => (options.timeHold ? options.timeHold(() => page.waitForTimeout(delay)) : page.waitForTimeout(delay));
+    const locate = async (target, frame, cursor, keyboard = false) => {
+        const request = {
+            selector: iframeSelector,
+            reveal: options.tile ?? null,
+            frameCheck: options.tile !== undefined || keyboard,
+            spot: null,
+            box: null,
+            ring: { key: options.ring ?? null },
+            cursor: cursor ? { key: options.ring ?? "", name: cursor.name, glideMs: cursorGlideMs(cursor.speed, delay) } : null,
+            settleMs: bound,
+        };
+        const settled = async () => {
+            await time("scroll", () => target.scrollIntoViewIfNeeded({ timeout: bound }));
+            const box = await time("box", () => target.boundingBox({ timeout: bound }));
+            if (!box)
+                throw new Error("Target has no box (hidden or detached)");
+            return time("hit", () => probe(page, { ...request, box }));
+        };
+        let result;
+        let documentFocus;
+        for (let attempt = 0; frame && attempt < 3 && (!result || result.moved); attempt++) {
+            const spot = await time("scroll", () => target.evaluate(spotInFrame, keyboard, { timeout: bound }));
+            if (spot.boxless)
+                throw new Error("Target has no box (hidden or detached)");
+            if (spot.noNeutralPoint)
+                throw new Error("No neutral visible point is available to focus the app document");
+            documentFocus = spot.documentFocus ? { ...spot.documentFocus, document: spot.document } : undefined;
+            if (keyboard && spot.document !== (await documentMark(frame)) && spot.document !== (await time("identify", () => documentMark(frame, true))))
+                throw new Error(`Target is not inside ${iframeSelector}'s document`);
+            if (documentFocus && (spot.nested || spot.animating))
+                throw new Error("Keyboard document focus requires a stable, directly displayed frame");
+            if (spot.nested || spot.animating) {
+                result = await settled();
+                break;
+            }
+            if (!keyboard && spot.document !== (await documentMark(frame)) && spot.document !== (await time("identify", () => documentMark(frame, true))))
+                throw new Error(`Target is not inside ${iframeSelector}'s document`);
+            result = await time("hit", () => probe(page, { ...request, spot }));
+        }
+        if (documentFocus && result?.transformed)
+            throw new Error("Keyboard document focus requires a displayed frame scaled evenly or not at all");
+        if (!result || result.moved || result.transformed)
+            result = await settled();
+        const box = result.box;
+        if (result.shown && !result.ringDrawn)
+            await time("ring", () => ring(box));
+        return { box: { ...box, documentFocus }, shown: result.shown === true };
+    };
+    const settle = async (target, cursor, keyboard = false) => {
+        const displayed = keyboard ? keyboardDisplayed : options.displayed;
+        const frame = displayed ? await time("identify", displayed) : undefined;
+        if (keyboard && !frame)
+            throw new Error(`No displayed app frame matches ${iframeSelector}`);
+        await options.verify?.(time, frame);
+        let located = await locate(target, frame, cursor, keyboard);
+        if (!located.shown && (options.reveal || options.tile !== undefined)) {
+            if (options.reveal)
+                await time("reveal", options.reveal);
+            located = await locate(target, frame, cursor, keyboard);
+        }
+        const { box } = located;
+        if (!located.shown)
+            throw new Error(`Target is not visible inside ${iframeSelector} at (${Math.round(box.x + box.width / 2)}, ${Math.round(box.y + box.height / 2)})`);
+        return box;
+    };
+    const center = (box) => ({ x: box.x + box.width / 2, y: box.y + box.height / 2 });
+    const prove = async (target) => {
+        await lane(() => settle(target));
+        if (delay)
+            await hold();
+    };
+    const gesture = (target, input, keyboard = false) => lane(async () => {
+        const cursor = options.cursor?.();
+        const box = await settle(target, cursor, keyboard);
+        if (delay)
+            await time("delay", hold);
+        if (cursor)
+            await time("cursor", async () => moveCursor(page, options.ring ?? "", cursor, center(box), 0, true));
+        await time("input", () => (options.timeInput ? options.timeInput(() => input(box)) : input(box)));
+    });
+    const done = async () => {
+        if (delay)
+            await hold();
+        await ring(null);
+    };
+    return {
+        async click(target) {
+            await gesture(target, () => target.click({ timeout: bound }));
+            await done();
+        },
+        async fill(target, text) {
+            let note;
+            await gesture(target, async () => {
+                await target.click({ timeout: bound });
+                await target.clear({ timeout: bound });
+                note = await typeVerified(target, text, { delay: options.typingDelayMs ?? 0, timeout: bound, refocus: () => target.click({ timeout: bound }) });
+            });
+            await done();
+            return note;
+        },
+        async press(target, key, pressOptions = {}) {
+            const press = target.press;
+            if (!press)
+                throw new Error("Keyboard input is unsupported: the target locator does not provide press()");
+            const documentTarget = await target.evaluate(element => element === document.body || element === document.documentElement, undefined, { timeout: bound });
+            if (documentTarget && !pressOptions.allowDocumentFocusClick)
+                throw new Error("Keyboard document target requires explicit allowDocumentFocusClick");
+            await gesture(target, async (box) => {
+                if (box.documentFocus) {
+                    const position = await target.evaluate(neutralDocumentPoint, box.documentFocus, { timeout: bound });
+                    if (!position)
+                        throw new Error("The app document's neutral focus point changed before keyboard input");
+                    await target.click({ timeout: bound, position });
+                    await options.verify?.(time, await keyboardDisplayed());
+                    const focused = await target.evaluate(() => document.hasFocus() && (document.activeElement === document.body || document.activeElement === document.documentElement), undefined, { timeout: bound });
+                    if (!focused)
+                        throw new Error("Keyboard focus did not reach the displayed app document");
+                }
+                else {
+                    const focusable = await target.evaluate(element => {
+                        if (!(element instanceof HTMLElement) || element.matches(":disabled") || element.closest("[inert]"))
+                            return false;
+                        const explicitTab = element.getAttribute("tabindex");
+                        return element.tabIndex >= 0 || element.isContentEditable || (explicitTab !== null && /^\s*-?\d+\s*$/.test(explicitTab));
+                    }, undefined, { timeout: bound });
+                    if (!focusable)
+                        throw new Error("Keyboard target is not an enabled focusable element");
+                }
+                await press.call(target, key, { timeout: bound });
+            }, true);
+            await done();
+        },
+        async read(target) {
+            await prove(target);
+            const text = (await target.textContent()) ?? "";
+            await done();
+            return text.trim();
+        },
+        async waitFor(target, waitOptions = {}) {
+            await target.waitFor({ state: "visible", ...waitOptions });
+            await prove(target);
+            await done();
+        },
+    };
+}

package/entrypoints/panel/src/visible/window-frames.d.ts

@@ -0,0 +1,35 @@
+import type { FrameLocator, Page } from "playwright";
+import type { FrameMedia } from "@parity/product-lab/domain/recordings";
+import type { CaptureOptions, FrameCapture } from "@parity/product-lab/ports/recording";
+/**
+ * The lab window's capture of each identity's displayed frame (`frameSelector(actorId)`). `videos`: where the runtime
+ * records video for recordings (`RecordingListing.videos`); the window's one video then shows every identity (backlog 18b).
+ * `uiCalls`: the window's record of its UI calls (backlog 110).
+ */
+export declare function windowFrameCapture(page: Page, frameSelector: (actorId: string) => string, media: FrameMedia, videos?: string, uiCalls?: FrameCapture["uiCalls"]): FrameCapture;
+/** How long a capture waits for the tile's box to hold still (backlog 110), at most half the capture's own limit. */
+export declare const STEADY_MS = 2000;
+type Box = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/**
+ * Runs in the shell page (self-contained, no named inner functions: the page cannot see the bundler's name helper): the frame's box once it holds still, read across
+ * rendered frames with no running animation on the frame or around it (a tile sliding in, a grid reflowing), within
+ * `settleMs`; `moving` when it did not. With `settleMs` 0, the box as it is now.
+ */
+export declare function steadyFrameBox(request: {
+    selector: string;
+    settleMs: number;
+}): Promise<Box | {
+    moving: true;
+}>;
+/**
+ * Waits until each selector matches a visible element of an app document (`CaptureOptions.settled`): the lab
+ * window's frame of it or a detached window's page. Undefined once all do, else why not (the first that matched none,
+ * and the time waited). Reads only.
+ */
+export declare function settle(document: Pick<FrameLocator | Page, "locator">, settled: NonNullable<CaptureOptions["settled"]>): Promise<string | undefined>;
+export {};

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

@@ -0,0 +1,128 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { unsettledReason } from "@parity/product-lab/domain/checks";
+import { assertFrameDisplayed } from "./visible-ui.js";
+import { cutInWorker, windowBytes } from "./viewport-shot.js";
+import { windowVideo } from "./window-video.js";
+export function windowFrameCapture(page, frameSelector, media, videos, uiCalls) {
+    const shots = sharedShots(page);
+    return {
+        source: "lab-window",
+        media,
+        ...(uiCalls ? { uiCalls } : {}),
+        video: () => windowVideo(page, videos, { source: "lab-window", scope: "window" }),
+        async capture(actorId, options) {
+            const selector = frameSelector(actorId);
+            const started = Date.now();
+            const unsettled = options?.settled?.selectors.length ? await settle(page.frameLocator(selector), options.settled) : undefined;
+            if (unsettled)
+                return { status: "unavailable", reason: unsettled };
+            const settled = options?.settled?.selectors.length ? { settledMs: Date.now() - started } : {};
+            const settleMs = Math.min(STEADY_MS, Math.max(1, (options?.timeoutMs ?? STEADY_MS * 2) / 2));
+            for (let attempt = 0; attempt < 2; attempt++) {
+                shots.measuring++;
+                let shot;
+                try {
+                    let box;
+                    try {
+                        await assertFrameDisplayed(page, selector);
+                        const steady = await page.evaluate(steadyFrameBox, { selector, settleMs });
+                        if ("moving" in steady)
+                            return { status: "unavailable", reason: `The lab window's tiles were still moving after ${settleMs} ms: no frame of this identity's app was taken` };
+                        box = steady;
+                    }
+                    catch (error) {
+                        return { status: "unavailable", reason: `The lab window does not show this identity's app: ${error instanceof Error ? error.message : String(error)}` };
+                    }
+                    const view = page.viewportSize() ?? (await page.evaluate(() => ({ width: window.innerWidth, height: window.innerHeight })));
+                    const x = Math.max(0, box.x);
+                    const y = Math.max(0, box.y);
+                    const width = Math.min(view.width, box.x + box.width) - x;
+                    const height = Math.min(view.height, box.y + box.height) - y;
+                    if (width < 1 || height < 1)
+                        return { status: "unavailable", reason: "The lab window shows none of this identity's app frame" };
+                    shot = shots.join();
+                    const bytes = await cutInWorker(await shot, view.width, { rect: { x, y, width, height } });
+                    const after = await page.evaluate(steadyFrameBox, { selector, settleMs: 0 });
+                    if (!("moving" in after) && sameBox(after, box))
+                        return { status: "captured", mediaType: "image/png", bytes: new Uint8Array(bytes), ...settled };
+                }
+                finally {
+                    if (!shot)
+                        shots.leave();
+                }
+            }
+            return { status: "unavailable", reason: "The lab window's tiles moved while this identity's app was being captured, twice: no frame was taken" };
+        },
+    };
+}
+export const STEADY_MS = 2_000;
+const sameBox = (a, b) => a.x === b.x && a.y === b.y && a.width === b.width && a.height === b.height;
+export async function steadyFrameBox(request) {
+    const frame = document.querySelector(request.selector);
+    if (!frame)
+        return { moving: true };
+    const first = frame.getBoundingClientRect();
+    let placed = { x: first.x, y: first.y, width: first.width, height: first.height };
+    if (request.settleMs <= 0)
+        return placed;
+    const deadline = Date.now() + request.settleMs;
+    for (;;) {
+        await new Promise((resolve) => { requestAnimationFrame(() => requestAnimationFrame(resolve)); setTimeout(resolve, 250); });
+        const rect = frame.getBoundingClientRect();
+        const now = { x: rect.x, y: rect.y, width: rect.width, height: rect.height };
+        const animating = document.getAnimations().some((animation) => {
+            const target = animation.effect instanceof KeyframeEffect ? animation.effect.target : null;
+            return animation.playState === "running" && target instanceof Element && target.contains(frame);
+        });
+        if (!animating && now.x === placed.x && now.y === placed.y && now.width === placed.width && now.height === placed.height)
+            return now;
+        if (Date.now() >= deadline)
+            return { moving: true };
+        placed = now;
+    }
+}
+function sharedShots(page) {
+    let next;
+    const flush = () => {
+        if (!next || shared.measuring > 0)
+            return;
+        const batch = next;
+        next = undefined;
+        batch.start();
+    };
+    const shared = {
+        measuring: 0,
+        join() {
+            shared.measuring--;
+            if (!next) {
+                let start;
+                const begun = new Promise((resolve) => { start = resolve; });
+                next = { start, shot: begun.then(() => windowBytes(page)) };
+            }
+            const { shot } = next;
+            flush();
+            return shot;
+        },
+        leave() {
+            shared.measuring--;
+            flush();
+        },
+    };
+    return shared;
+}
+export async function settle(document, settled) {
+    const started = Date.now();
+    for (const selector of settled.selectors) {
+        const left = Math.max(1, settled.timeoutMs - (Date.now() - started));
+        try {
+            await document.locator(selector).first().waitFor({ state: "visible", timeout: left });
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === "TimeoutError")
+                return unsettledReason(selector, settled.timeoutMs);
+            throw error;
+        }
+    }
+    return undefined;
+}

package/entrypoints/panel/src/visible/window-hold.d.ts

@@ -0,0 +1,21 @@
+import type { WorkerHold } from "@parity/product-lab/domain";
+import type { LabRuntime } from "@parity/product-lab/ports/driving";
+/** Asked by the switch confirm (src/client/environment.ts): would switching to an environment reopen the window? */
+export declare const WINDOW_SWITCH_BINDING = "__productLabWindowSwitch";
+/** The switch confirm's "Reopen and switch": the window reopens without its debugging port, then switches. */
+export declare const WINDOW_REOPEN_BINDING = "__productLabReopenAndSwitch";
+/** Asked by Settings' "Hold worker starts" row (src/client/settings.ts): does the window hold now, or why not? */
+export declare const WINDOW_HOLDING_BINDING = "__productLabWindowHolding";
+/** What the switch confirm learns from the window: whether this switch reopens it without its debugging port. */
+export interface WindowSwitch {
+    reopen: boolean;
+}
+/** Whether the lab window may hold worker starts while `environment` runs (default the selected one), or why not. */
+export declare function windowHold(runtime: Pick<LabRuntime, "observeWindowNetwork" | "workerHold">, environment?: string): WorkerHold;
+/**
+ * A free TCP port on 127.0.0.1, chosen by the system, for the window browser's `--remote-debugging-port`. It is never
+ * printed or logged: the port is only for the window's own observer, and closes with the window's browser.
+ */
+export declare function freeLoopbackPort(): Promise<number>;
+/** The launch arguments that open the debugging port on 127.0.0.1 only. */
+export declare function debuggingPortArgs(port: number): string[];

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

@@ -0,0 +1,29 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { createServer } from "node:net";
+export const WINDOW_SWITCH_BINDING = "__productLabWindowSwitch";
+export const WINDOW_REOPEN_BINDING = "__productLabReopenAndSwitch";
+export const WINDOW_HOLDING_BINDING = "__productLabWindowHolding";
+export function windowHold(runtime, environment) {
+    if (!runtime.observeWindowNetwork)
+        return { off: "the runtime does not observe the lab window's traffic" };
+    try {
+        return runtime.workerHold?.(environment) ?? { off: "the runtime does not say whether the lab window may hold worker starts" };
+    }
+    catch (error) {
+        return { off: `the lab could not decide for ${environment ?? "this environment"} (${error instanceof Error ? error.message : String(error)})` };
+    }
+}
+export function freeLoopbackPort() {
+    return new Promise((resolve, reject) => {
+        const server = createServer();
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", () => {
+            const address = server.address();
+            server.close(() => (typeof address === "object" && address ? resolve(address.port) : reject(new Error("No free port on 127.0.0.1"))));
+        });
+    });
+}
+export function debuggingPortArgs(port) {
+    return [`--remote-debugging-port=${port}`, "--remote-debugging-address=127.0.0.1"];
+}

package/entrypoints/panel/src/visible/window-video.d.ts

@@ -0,0 +1,17 @@
+import type { Page } from "playwright";
+import type { CapturedVideo } from "@parity/product-lab/ports/recording";
+/** Note when `page` opened: its video's first frame (call right after the page is made). */
+export declare function videoOpened(page: Page, at?: number): void;
+/**
+ * The video `page` is recorded into, for a recording to name: undefined when it records none, or when the runtime records
+ * no video for recordings (`videos` absent). A page recorded elsewhere (`dev --video <dir>`, which wins for the lab window)
+ * is refused with why: a recording names only files in its own `videos/` folder.
+ */
+export declare function windowVideo(page: Pick<Page, "video" | "viewportSize">, videos: string | undefined, what: {
+    source: string;
+    scope?: "identity" | "window";
+    size?: {
+        width: number;
+        height: number;
+    };
+}): Promise<CapturedVideo | undefined>;