@parity/product-lab 0.0.1-placeholder → 0.1.0

package/entrypoints/panel/src/visible/tile-placement.d.ts

@@ -0,0 +1,61 @@
+import type { Page } from "playwright";
+import type { FramesNetwork } from "@parity/product-lab/ports/browser";
+import type { SessionPlacements } from "@parity/product-lab/ports/host";
+/** Sent to the shell when a tile starts or stops showing a host page (`detail`: `HostedTile` or `{ actor, url: null }`). */
+export declare const TILE_HOSTED_EVENT = "product-lab:tile-hosted";
+/** The shell asks for every hosted tile when it loads (returns `HostedTile[]`). */
+export declare const HOSTED_TILES_BINDING = "__productLabHostedTiles";
+/** C4: why a tile routes one person's requests but not their sockets. */
+export declare const TILE_SOCKETS_OPEN = "In the lab window this person's host page runs in their tile, which shares the window's page with every other person. The lab blocks and lists every request the tile's pages and their worker make outside what the lock allows, but a socket does not say which tile opened it, so sockets are open here. In a headless run the whole lock applies";
+/**
+ * C7: the same where the window observes its traffic by frame: the tile's sockets are observed and listed (in the host
+ * check), not blocked. No browser control can block one tile's sockets: Chromium's blocked URLs stop neither a page's
+ * nor a worker's sockets (`docs/verification/2026-10-06-wasm-window-network.md`).
+ */
+export declare const TILE_SOCKETS_OBSERVED = "In the lab window this person's host page runs in their tile, which shares the window's page with every other person. The lab blocks and lists every request the tile's pages and their worker make outside what the lock allows. Its sockets are observed and listed in the host check, not blocked: the browser cannot block one tile's sockets";
+/** A tile showing a person's host page. */
+export interface HostedTile {
+    readonly actor: string;
+    /** The host page's address as first opened (no secret). */
+    readonly url: string;
+}
+/**
+ * C4: the name the shell gives a hosted tile's iframe when it creates it, so a route can tell which tile a request
+ * comes from by walking its frames, synchronously, never through the window's document (a route that asked the
+ * document deadlocked the window's own reload: its navigation waited for the route, the route for the document).
+ */
+export declare const tileFrameName: (actorId: string) => string;
+/** The tile's iframe in the window. */
+export declare const tileSelector: (actorId: string) => string;
+/** The app's frame inside a host page: the iframe whose address is the app's origin. */
+export declare const appFrameSelector: (appUrl: string) => string;
+/** The window's tiles as placements, and which of them show a host page now. */
+export declare class TilePlacements {
+    private readonly page;
+    private readonly frames?;
+    private readonly hosted;
+    /** `frames`: the window's traffic by frame (C7), from which each tile's tab reads its own; absent: no passive observation. */
+    constructor(page: Page, frames?: FramesNetwork | undefined);
+    /** For `LabRuntime.placeSessions`: every person's tile (the environment gives it only to hosts that embed their app). */
+    readonly placements: SessionPlacements;
+    /** The tile of `actorId` when it shows a host page. */
+    hostedTile(actorId: string): HostedTile | undefined;
+    /** Every hosted tile, for a shell that loads (or loads again). */
+    list(): HostedTile[];
+    private placement;
+    /** Tell the shell (if it is there) what a tile shows; a shell that loads later asks for the list. */
+    private publish;
+    private show;
+    private unhost;
+    /** The tile's document now, or null when the window shows no tile for the person. */
+    private frame;
+    private requireFrame;
+    /**
+     * Whether a request comes from the person's tile (its document, a frame inside it, or a worker of theirs: Playwright
+     * gives a worker's request its page's frame). Decided from the frames alone: the tile is the main frame's child the
+     * shell named for the person (`tileFrameName`). The window's own requests are never the tile's.
+     */
+    private fromTile;
+    private browser;
+    private tab;
+}

package/entrypoints/panel/src/visible/tile-placement.js

@@ -0,0 +1,155 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export const TILE_HOSTED_EVENT = "product-lab:tile-hosted";
+export const HOSTED_TILES_BINDING = "__productLabHostedTiles";
+export const TILE_SOCKETS_OPEN = "In the lab window this person's host page runs in their tile, which shares the window's page with every other person. The lab blocks and lists every request the tile's pages and their worker make outside what the lock allows, but a socket does not say which tile opened it, so sockets are open here. In a headless run the whole lock applies";
+export const TILE_SOCKETS_OBSERVED = "In the lab window this person's host page runs in their tile, which shares the window's page with every other person. The lab blocks and lists every request the tile's pages and their worker make outside what the lock allows. Its sockets are observed and listed in the host check, not blocked: the browser cannot block one tile's sockets";
+export const tileFrameName = (actorId) => `product-lab-tile:${actorId}`;
+export const tileSelector = (actorId) => `#application iframe[data-actor=${JSON.stringify(actorId)}]`;
+export const appFrameSelector = (appUrl) => `iframe[src^=${JSON.stringify(`${new URL(appUrl).origin}/`)}]`;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export class TilePlacements {
+    page;
+    frames;
+    hosted = new Map();
+    constructor(page, frames) {
+        this.page = page;
+        this.frames = frames;
+    }
+    placements = (actorId) => this.placement(actorId);
+    hostedTile(actorId) {
+        return this.hosted.get(actorId);
+    }
+    list() {
+        return [...this.hosted.values()];
+    }
+    placement(actorId) {
+        const tag = `tile-${actorId}`;
+        return { browser: this.browser(actorId), label: `${actorId}'s lab-window tile`, tag, network: { sockets: this.frames ? TILE_SOCKETS_OBSERVED : TILE_SOCKETS_OPEN } };
+    }
+    async publish(detail) {
+        if (this.page.isClosed())
+            return;
+        await this.page
+            .evaluate(([name, value]) => { dispatchEvent(new CustomEvent(name, { detail: value })); }, [TILE_HOSTED_EVENT, detail])
+            .catch(() => undefined);
+    }
+    async show(actorId, url) {
+        const tile = { actor: actorId, url };
+        this.hosted.set(actorId, tile);
+        await this.publish(tile);
+    }
+    async unhost(actorId) {
+        if (!this.hosted.delete(actorId))
+            return;
+        await this.publish({ actor: actorId, url: null });
+    }
+    async frame(actorId) {
+        if (this.page.isClosed())
+            return null;
+        const handles = await this.page.locator(tileSelector(actorId)).elementHandles();
+        try {
+            return (await handles[0]?.contentFrame()) ?? null;
+        }
+        finally {
+            await Promise.all(handles.map((handle) => handle.dispose().catch(() => undefined)));
+        }
+    }
+    async requireFrame(actorId) {
+        const frame = await this.frame(actorId);
+        if (!frame)
+            throw new Error(`The lab window shows no tile for ${actorId}`);
+        return frame;
+    }
+    fromTile(actorId, request) {
+        let frame;
+        try {
+            frame = request.frame();
+        }
+        catch {
+            return false;
+        }
+        const main = this.page.mainFrame();
+        for (; frame; frame = frame.parentFrame())
+            if (frame.parentFrame() === main)
+                return frame.name() === tileFrameName(actorId);
+        return false;
+    }
+    browser(actorId) {
+        const routes = [];
+        const route = async (url, handler) => {
+            const scoped = async (playwrightRoute, request) => {
+                if (this.fromTile(actorId, request))
+                    await handler(playwrightRoute);
+                else
+                    await playwrightRoute.fallback();
+            };
+            routes.push({ url, handler: scoped });
+            await this.page.route(url, scoped);
+        };
+        const tab = this.tab(actorId, route);
+        const context = {
+            newPage: async () => tab,
+            route,
+            routeWebSocket: async () => {
+                throw new Error(TILE_SOCKETS_OPEN);
+            },
+            addInitScript: (script) => this.page.addInitScript(script),
+            close: async () => {
+                for (const { url, handler } of routes.splice(0))
+                    await this.page.unroute(url, handler).catch(() => undefined);
+                await this.unhost(actorId);
+            },
+        };
+        return {
+            newContext: async () => context,
+            newPage: async () => tab,
+            close: async () => context.close(),
+        };
+    }
+    tab(actorId, route) {
+        const frames = this.page.frameLocator(tileSelector(actorId));
+        let current;
+        const frameOf = async () => (current = await this.requireFrame(actorId));
+        return {
+            url: () => (current && !current.isDetached() ? current.url() : (this.hosted.get(actorId)?.url ?? "about:blank")),
+            goto: async (url, options) => {
+                const timeout = options?.timeout ?? 30_000;
+                const target = new URL(url).origin;
+                await this.show(actorId, url);
+                const deadline = Date.now() + timeout;
+                for (;;) {
+                    const frame = await this.frame(actorId);
+                    const shown = frame?.url();
+                    if (frame && shown && shown !== "about:blank" && new URL(shown).origin === target) {
+                        current = frame;
+                        await frame.waitForLoadState("load", { timeout: Math.max(1, deadline - Date.now()) });
+                        return null;
+                    }
+                    if (Date.now() >= deadline)
+                        throw Object.assign(new Error(`${actorId}'s tile did not show ${target} within ${timeout} ms`), { name: "TimeoutError" });
+                    await sleep(100);
+                }
+            },
+            reload: async (options) => {
+                const frame = await frameOf();
+                await frame.goto(frame.url(), { waitUntil: "load", ...(options?.timeout !== undefined ? { timeout: options.timeout } : {}) });
+                return null;
+            },
+            route,
+            ...(this.frames ? { networkEvidence: () => this.frames.frame(tileFrameName(actorId)).evidence() } : {}),
+            evaluate: async (fn, arg) => { const frame = await frameOf(); return frame.evaluate(fn, arg); },
+            waitForFunction: async (fn, arg, options) => { const frame = await frameOf(); return frame.waitForFunction(fn, arg, { polling: 100, ...options }); },
+            waitForSelector: async (selector, options) => {
+                const handle = await (await frameOf()).waitForSelector(selector, { ...options, state: "attached" });
+                return handle ? { contentFrame: () => handle.contentFrame() } : null;
+            },
+            locator: (selector) => frames.locator(selector),
+            getByLabel: (text, options) => frames.getByLabel(text, options),
+            getByRole: (role, options) => frames.getByRole(role, options),
+            getByTestId: (testId) => frames.getByTestId(testId),
+            getByText: (text, options) => frames.getByText(text, options),
+            close: async () => undefined,
+        };
+    }
+}

package/entrypoints/panel/src/visible/tile-ready.d.ts

@@ -0,0 +1,25 @@
+import { type AppReadiness } from "@parity/product-lab/domain/apps";
+import type { AppSurface } from "@parity/product-lab/ports/browser";
+/** What `tileReady` reads and does: the tile's surface, how to bring it on screen, and its document. */
+export interface TileReadyTarget {
+    /** The actor's name, for messages. */
+    readonly actor: string;
+    readonly surface: Pick<AppSurface, "app" | "click" | "fill">;
+    /**
+     * Bring the tile on screen showing the actor's active app (the lab runner's readiness before a gesture); false when
+     * the window's view shows no tile for the actor.
+     */
+    show(): Promise<boolean>;
+    /** The tile's document once it has loaded, by its address; null when the tile shows none. */
+    loaded(timeoutMs: number): Promise<string | null>;
+    /** The app the tile shows, as the lab declares its readiness. */
+    readonly readiness: AppReadiness;
+}
+/**
+ * Wait until the tile shows its app ready: on screen with the actor's app, its document loaded, the declared steps
+ * performed in it, and the declared signal there. Refuses naming what was waited for and what was seen.
+ */
+export declare function tileReady(target: TileReadyTarget, options?: {
+    signal?: AbortSignal;
+    pollMs?: number;
+}): Promise<void>;

package/entrypoints/panel/src/visible/tile-ready.js

@@ -0,0 +1,78 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { describeElement } from "@parity/product-lab/domain/apps";
+const CSS_STRING = /["\\]/g;
+const quote = (text) => `"${text.replace(CSS_STRING, "\\$&")}"`;
+function locate(root, target) {
+    switch (target.kind) {
+        case "selector":
+            return root.locator(target.selector);
+        case "testId":
+            return target.attribute === undefined
+                ? root.getByTestId(target.testId)
+                : root.locator(`[data-testid=${quote(target.testId)}][${target.attribute}${target.value !== undefined ? `=${quote(target.value)}` : ""}]`);
+        case "role":
+            return root.getByRole(target.role, target.name !== undefined ? { name: target.name, exact: true } : {});
+        case "label":
+            return root.getByLabel(target.label, { exact: true });
+        case "text":
+            return root.getByText(target.text, { exact: true });
+    }
+}
+async function present(locator, timeoutMs) {
+    try {
+        await locator.waitFor({ state: "attached", timeout: timeoutMs });
+        return true;
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === "TimeoutError")
+            return false;
+        throw error;
+    }
+}
+function ownAddress(url) {
+    try {
+        const parsed = new URL(url);
+        parsed.searchParams.delete("bridge");
+        return `${parsed.pathname}${parsed.search}${parsed.hash}`;
+    }
+    catch {
+        return url;
+    }
+}
+export async function tileReady(target, options = {}) {
+    const { readiness, surface } = target;
+    const deadline = Date.now() + readiness.timeoutMs;
+    const remaining = () => Math.max(1, deadline - Date.now());
+    if (!(await target.show()))
+        return;
+    const address = await target.loaded(remaining());
+    if (address === null)
+        throw new Error(`${target.actor}'s tile shows no document of ${readiness.app}`);
+    for (const step of readiness.steps) {
+        options.signal?.throwIfAborted();
+        const element = locate(surface.app, step.target);
+        if (step.action === "click")
+            await surface.click(element);
+        else
+            await surface.fill(element, step.value);
+    }
+    const signal = readiness.signal;
+    if (signal.kind === "host")
+        return;
+    const ready = signal.kind === "url" ? undefined : locate(surface.app, signal);
+    const failed = readiness.failed ? locate(surface.app, readiness.failed) : undefined;
+    const pollMs = options.pollMs ?? 250;
+    for (;;) {
+        options.signal?.throwIfAborted();
+        if (failed && (await present(failed, pollMs))) {
+            const text = ((await failed.textContent({ timeout: 1_000 }).catch(() => null)) ?? "").trim();
+            throw new Error(`${target.actor}'s tile shows ${readiness.app} failed to start (${describeElement(readiness.failed)})${text ? `: ${text}` : ""}`);
+        }
+        if (ready ? await present(ready, pollMs) : ownAddress((await target.loaded(remaining())) ?? "").startsWith(signal.url))
+            return;
+        if (Date.now() > deadline)
+            throw new Error(`${target.actor}'s tile did not show ${readiness.app} ready within ${readiness.timeoutMs} ms: it waited for ${readiness.describe()}`);
+        await new Promise((resolve) => setTimeout(resolve, pollMs));
+    }
+}

package/entrypoints/panel/src/visible/ui-activity.d.ts

@@ -0,0 +1,60 @@
+import type { Page } from "playwright";
+import type { RecordedUiCall } from "@parity/product-lab/domain/recordings";
+import type { UiCallTiming, UiPhase } from "./ui-timing.js";
+/** The shell window event (src/client/ui-calls.ts `UI_CALL_EVENT`). */
+export declare const UI_CALL_EVENT = "product-lab:ui-call";
+/** The binding the shell calls for the history (guarded like the run bindings: the lab shell's main frame only). */
+export declare const UI_CALLS_BINDING = "__productLabUiCalls";
+/** Calls kept for a reloaded shell. */
+export declare const UI_CALL_HISTORY = 2000;
+/** One stretch of a call, wall clock (ms since the Unix epoch). */
+export interface UiActivitySegment {
+    phase: UiPhase;
+    start: number;
+    end: number;
+}
+/** One visible UI call as the shell receives it: live while it runs (`phase`), final once `ended`. */
+export interface UiActivityCall {
+    /** Unique in this window. */
+    id: number;
+    /** The actor session id of the surface. */
+    actor: string;
+    call: UiCallTiming["call"];
+    target?: string;
+    /** What a person calls the target, its kind, a fill's shortened text (UiCallTiming). */
+    targetName?: string;
+    targetRole?: string;
+    typed?: string;
+    typedHidden?: boolean;
+    /** UiCallTiming.note. */
+    note?: string;
+    startedAt: number;
+    /** The phase it is in now; absent once it ended. */
+    phase?: UiPhase;
+    phaseAt?: number;
+    endedAt?: number;
+    ok?: boolean;
+    error?: string;
+    segments: UiActivitySegment[];
+}
+export interface UiActivityFeed {
+    /** A call entered a phase (`atMs` on the runner's clock). */
+    phase(timing: UiCallTiming, phase: UiPhase, atMs: number): void;
+    /** A call settled. */
+    settled(timing: UiCallTiming): void;
+    /** The calls so far, oldest first (bounded). */
+    history(): UiActivityCall[];
+    /**
+     * Backlog 110: the calls that settled after cursor `after` (absent: every settled call still kept), in the order they
+     * settled, as run recordings keep them, with the cursor to read from next (`FrameCapture.uiCalls`).
+     */
+    settledSince(after?: number): {
+        calls: RecordedUiCall[];
+        next: number;
+    };
+}
+/**
+ * The feed of one lab window. `origin` is the runner's clock origin (`Date.now()` when it attached): runner times plus
+ * `origin` are wall-clock times. Events reach the page only while its main frame is on `shellOrigin`.
+ */
+export declare function uiActivityFeed(page: Page, shellOrigin: string, origin: number): UiActivityFeed;

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

@@ -0,0 +1,91 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export const UI_CALL_EVENT = "product-lab:ui-call";
+export const UI_CALLS_BINDING = "__productLabUiCalls";
+export const UI_CALL_HISTORY = 2000;
+function recorded(call) {
+    return {
+        actor: call.actor,
+        call: call.call,
+        ...(call.target ? { target: call.target } : {}),
+        ...(call.targetName ? { targetName: call.targetName } : {}),
+        ...(call.targetRole ? { targetRole: call.targetRole } : {}),
+        ...(call.typed !== undefined ? { typed: call.typed } : {}),
+        ...(call.typedHidden ? { typedHidden: true } : {}),
+        ...(call.note ? { note: call.note } : {}),
+        startedAt: call.startedAt,
+        durationMs: Math.max(0, (call.endedAt ?? call.startedAt) - call.startedAt),
+        ok: call.ok ?? false,
+        ...(call.error ? { error: call.error } : {}),
+    };
+}
+export function uiActivityFeed(page, shellOrigin, origin) {
+    const calls = new Map();
+    const history = [];
+    const settled = [];
+    let seq = 0;
+    let next = 0;
+    let queue = Promise.resolve();
+    const at = (ms) => origin + ms;
+    const view = (timing) => {
+        let call = calls.get(timing);
+        if (!call) {
+            call = { id: ++next, actor: timing.actor, call: timing.call, startedAt: at(timing.startedMs), segments: [] };
+            calls.set(timing, call);
+            history.push(call);
+            if (history.length > UI_CALL_HISTORY) {
+                const dropped = history.shift();
+                for (const [key, item] of calls)
+                    if (item === dropped)
+                        calls.delete(key);
+            }
+        }
+        if (timing.target)
+            call.target = timing.target;
+        if (timing.targetName)
+            call.targetName = timing.targetName;
+        if (timing.targetRole)
+            call.targetRole = timing.targetRole;
+        if (timing.typed !== undefined)
+            call.typed = timing.typed;
+        if (timing.typedHidden)
+            call.typedHidden = true;
+        if (timing.note)
+            call.note = timing.note;
+        call.segments = (timing.segments ?? []).map((segment) => ({ phase: segment.phase, start: at(segment.startMs), end: at(segment.endMs) }));
+        return call;
+    };
+    const push = (call) => {
+        const detail = structuredClone(call);
+        queue = queue.then(async () => {
+            if (page.isClosed() || new URL(page.mainFrame().url()).origin !== shellOrigin)
+                return;
+            await page.mainFrame().evaluate(([name, value]) => { window.dispatchEvent(new CustomEvent(name, { detail: value })); }, [UI_CALL_EVENT, detail]);
+        }).catch(() => {
+        });
+    };
+    return {
+        phase(timing, phase, atMs) {
+            const call = view(timing);
+            call.phase = phase;
+            call.phaseAt = at(atMs);
+            push(call);
+        },
+        settled(timing) {
+            const call = view(timing);
+            delete call.phase;
+            delete call.phaseAt;
+            call.endedAt = at(timing.startedMs + timing.durationMs);
+            call.ok = timing.ok;
+            if (timing.error)
+                call.error = timing.error;
+            calls.delete(timing);
+            settled.push({ seq: ++seq, call: recorded(call) });
+            if (settled.length > UI_CALL_HISTORY)
+                settled.shift();
+            push(call);
+        },
+        history: () => history.map((call) => structuredClone(call)),
+        settledSince: (after) => ({ calls: settled.filter((entry) => after === undefined || entry.seq > after).map((entry) => structuredClone(entry.call)), next: seq }),
+    };
+}

package/entrypoints/panel/src/visible/ui-timing.d.ts

@@ -0,0 +1,95 @@
+/** The `AppSurface` call a timing belongs to. */
+export type UiCall = "click" | "fill" | "press" | "read" | "waitFor" | "screenshot" | "reload";
+/**
+ * A phase of one UI call, in the order a call goes through them: `follow` (the displayed frame following the actor's
+ * active app), `ready` (the frame shown, the target visible), `lane-wait` (queued for the shared input lane),
+ * `lane-hold` (the checks, a gesture's highlight delay and its input), `input` (the physical input, inside a hold) and
+ * `hold` (the highlight delay a watching person follows: before a gesture's input inside its hold, and after a call
+ * outside the lane).
+ */
+export type UiPhase = "follow" | "ready" | "lane-wait" | "lane-hold" | "input" | "hold";
+/**
+ * One step inside the shared input lane, for `UiCallTiming.laneSteps` (where a lane hold went): `identify` (the same
+ * identity and environment, the displayed document on the actor's active app origin; also re-reading a reloaded
+ * document's mark), `scroll` (the target brought into view and measured inside its frame), `hit` (the one shell call:
+ * the tile revealed, the frame checked and held still, the target placed and hit-tested, its ring and the cursor's
+ * glide), `delay` (the highlight delay held inside a gesture), `cursor` (the click ripple sent), `input` (the physical
+ * input, as `inputMs`). The old way (a nested, scaled or animated target; a surface without `displayed`), a retry, a
+ * screenshot or a reload add `reveal`, `frame` (a frame check of its own), `box` (the browser's box of the target),
+ * `ring` (a page without the lab shell's ring) and `capture` (a screenshot's capture). README.md, "Visible input lane".
+ */
+export type LaneStep = "identify" | "reveal" | "frame" | "scroll" | "box" | "hit" | "ring" | "cursor" | "delay" | "input" | "capture";
+/** One stretch of a call's time, on the runner's clock (ms since it attached). `input` lies inside a `lane-hold`. */
+export interface UiCallSegment {
+    phase: UiPhase;
+    startMs: number;
+    endMs: number;
+}
+/** One visible UI call of one actor. */
+export interface UiCallTiming {
+    /** The actor session id of the surface ("" for a surface without one). */
+    actor: string;
+    call: UiCall;
+    /** When the call started. */
+    startedMs: number;
+    /** Readiness outside the lane: the frame shown, the target visible (without `followMs`). */
+    readyMs: number;
+    /** Waiting for the displayed frame to show the actor's active app after a navigation. */
+    followMs: number;
+    /** Waiting to acquire the shared input lane (summed, if a call takes it more than once). */
+    laneWaitMs: number;
+    /** Holding the lane: the checks, a gesture's highlight delay and the input (`laneSteps` splits it). */
+    laneHoldMs: number;
+    /** The physical input alone (a click; a fill's click, clear and typing; a key press). 0 for calls without input. */
+    inputMs: number;
+    /** When the physical input started (clicks, fills and key presses only). */
+    inputAtMs?: number;
+    durationMs: number;
+    ok: boolean;
+    error?: string;
+    /** What the call acted on, as the locator describes itself (`getByTestId('note-publish')`), when it says. */
+    target?: string;
+    /**
+     * What a person calls that element, read in the app when the call found it (`nameTarget`): its accessible name or
+     * label, else its humanized test id ("Publish", "Note", "notes"). Absent when nothing names it.
+     */
+    targetName?: string;
+    /** The element's kind in words, when it has an obvious one: `button`, `link`, `field`, `checkbox`, `radio`, `list`. */
+    targetRole?: string;
+    /** A fill's text, shortened to 24 characters; never for a password or one-time-code field (`typedHidden` instead). */
+    typed?: string;
+    /** A fill into a password or one-time-code field: its text is not kept. */
+    typedHidden?: boolean;
+    /** What the call had to do to succeed, in words (a fill whose focus was taken: "focus moved to …; refocused and completed"). */
+    note?: string;
+    /** Where the call's time went, in order (the timeline's sub-bars). Readiness splits into `follow` and `ready`. */
+    segments?: UiCallSegment[];
+    /** Where the lane holds went: ms per step inside the lane, summed over the call's holds (steps it did not take are absent). */
+    laneSteps?: Partial<Record<LaneStep, number>>;
+}
+/** One actor's calls in a run, summed. */
+export interface UiActorTiming {
+    actor: string;
+    calls: number;
+    failed: number;
+    firstCallMs: number;
+    /** When the actor's first physical input started. */
+    firstInputMs?: number;
+    readyMs: number;
+    followMs: number;
+    laneWaitMs: number;
+    maxLaneWaitMs: number;
+    laneHoldMs: number;
+    maxLaneHoldMs: number;
+    inputMs: number;
+}
+export interface UiCallSummary {
+    actors: UiActorTiming[];
+    /** Between the first and the last actor's first physical input (two or more actors with input). */
+    entrySpreadMs?: number;
+    /** All actors' lane waits. */
+    laneWaitMs: number;
+    maxLaneWaitMs: number;
+}
+/** Per-actor sums of a run's calls, in order of each actor's first call. */
+export declare function summarizeUiCalls(calls: readonly UiCallTiming[]): UiCallSummary;

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

@@ -0,0 +1,32 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+export function summarizeUiCalls(calls) {
+    const actors = new Map();
+    for (const call of [...calls].sort((a, b) => a.startedMs - b.startedMs)) {
+        const actor = actors.get(call.actor) ?? {
+            actor: call.actor, calls: 0, failed: 0, firstCallMs: call.startedMs, readyMs: 0, followMs: 0,
+            laneWaitMs: 0, maxLaneWaitMs: 0, laneHoldMs: 0, maxLaneHoldMs: 0, inputMs: 0,
+        };
+        actor.calls++;
+        if (!call.ok)
+            actor.failed++;
+        if (call.inputAtMs !== undefined && (actor.firstInputMs === undefined || call.inputAtMs < actor.firstInputMs))
+            actor.firstInputMs = call.inputAtMs;
+        actor.readyMs += call.readyMs;
+        actor.followMs += call.followMs;
+        actor.laneWaitMs += call.laneWaitMs;
+        actor.maxLaneWaitMs = Math.max(actor.maxLaneWaitMs, call.laneWaitMs);
+        actor.laneHoldMs += call.laneHoldMs;
+        actor.maxLaneHoldMs = Math.max(actor.maxLaneHoldMs, call.laneHoldMs);
+        actor.inputMs += call.inputMs;
+        actors.set(call.actor, actor);
+    }
+    const list = [...actors.values()];
+    const entries = list.flatMap((actor) => (actor.firstInputMs === undefined ? [] : [actor.firstInputMs]));
+    return {
+        actors: list,
+        ...(entries.length > 1 ? { entrySpreadMs: Math.max(...entries) - Math.min(...entries) } : {}),
+        laneWaitMs: list.reduce((sum, actor) => sum + actor.laneWaitMs, 0),
+        maxLaneWaitMs: list.reduce((max, actor) => Math.max(max, actor.maxLaneWaitMs), 0),
+    };
+}

package/entrypoints/panel/src/visible/verified-typing.d.ts

@@ -0,0 +1,39 @@
+import type { Locator } from "@parity/product-lab/ports/browser";
+/** What the field holds, whether it is a secret one, and what holds keyboard focus in its document (in words). */
+export interface FieldState {
+    readonly value: string;
+    readonly secret: boolean;
+    /** `null` when the field itself has focus. */
+    readonly focus: string | null;
+}
+/** Read in the field's own document. */
+export declare function fieldState(target: Locator, timeout: number): Promise<FieldState>;
+/**
+ * What one typed key may take beyond the delay. A key is two round trips to the field's renderer (Playwright sends
+ * keyDown and keyUp, each answered once the page has handled it): about 1 ms idle, but at a load of 60 on 18 CPUs a
+ * key took 50 to 300 ms (each run's median) and up to 703 ms, and 16 keys up to 5 s in a mirrored detached window.
+ * The 50 ms this was failed one fill in 30 there (job/panel-flakes, 23 October 2026).
+ */
+export declare const TYPED_KEY_MS = 300;
+/**
+ * Keys typed per call, each call bounded on its own: a renderer that stops answering fails the fill within one
+ * chunk's bound (the field's wait and 16 keys), however long the text, while typing that keeps going gets the whole
+ * allowance. A text input may hold 10,000 characters, and a tile's fill holds every actor's input lane while it types.
+ */
+export declare const TYPED_CHUNK = 16;
+/** The bound on typing `count` keys in one call: the wait for the field, then each key's delay and round trips. */
+export declare function typingTimeout(count: number, options: Pick<VerifiedTypingOptions, "delay" | "timeout">): number;
+export interface VerifiedTypingOptions {
+    /** Between keys. */
+    readonly delay: number;
+    /** For reading the field and for typing a key. */
+    readonly timeout: number;
+    /** Give the field keyboard focus again (the surface's own gesture: a click on it). */
+    readonly refocus: () => Promise<void>;
+}
+/**
+ * Type `text` into the focused field key by key, then read it back. Returns undefined when the field holds exactly the
+ * text, or the note for the call's evidence when focus moved away and one refocus completed it. Throws, before anything
+ * else happens, when the field still does not hold exactly the text.
+ */
+export declare function typeVerified(target: Locator, text: string, options: VerifiedTypingOptions): Promise<string | undefined>;