@parity/product-lab 0.1.0 → 0.1.2

package/entrypoints/cli/src/demo-command.d.ts

@@ -1,4 +1,4 @@
 import type { DemoReport, LabRuntime } from "@parity/product-lab/ports/driving";
-export declare const DEMO_USAGE = "Usage: product-lab demo [<recording-id>] [--actor <role> | --window] [--out <dir>] [--max-seconds 60]\n                        [--format mp4|webm] [--plan | --slide-only] [--failed] [--json] [--config lab.config.ts]\n\nA demo of a recorded feature scenario: its video cut to about a minute, every action at real speed with its result\nheld, waits sped up and labelled (\u00D78 waiting for finality), a caption per Gherkin step, plus demo.vtt (the captions),\ndemo.json (the edit, segment by segment) and a slide (slide.png, slide.html: the scenario, its steps, who and where,\nthe last screen). Record a run with video first (product-lab test --video, or the lab window's recording).\n  <recording-id>    default: the newest passed feature recording\n  --actor <role>    cut that actor's app video (default: the lab window's, else the actor in most steps)\n  --window          cut the lab window's video\n  --out <dir>       default: <lab>/.product-lab/demos/<recording-id>\n  --max-seconds <n> the longest the cut should be (default 60); over it the waits speed up first\n  --format mp4|webm default mp4 (H.264); webm is VP9\n  --plan            only demo.json and demo.vtt (needs no ffmpeg)\n  --slide-only      the plan and the slide, no video (needs no ffmpeg)\n  --failed          allow a failed run: every frame and the slide say it failed\n  --json            print the report as JSON\n  The video needs ffmpeg and ffprobe on PATH (or PRODUCT_LAB_FFMPEG naming their folder); product-lab never bundles them.\n  Exit code: 0 made, 2 refused (no such recording, no video, a failed run without --failed, no ffmpeg) or bad arguments,\n  1 when the lab does not load or the cut fails.";
+export declare const DEMO_USAGE = "Usage: product-lab demo [<recording-id>] [--actor <role> | --window] [--out <dir>] [--max-seconds 60] [--hold-seconds 2]\n                        [--format mp4|webm] [--plan | --slide-only] [--failed] [--json] [--config lab.config.ts]\n\nA demo of a recorded feature scenario: its real after-step images held for at least 2 seconds each,\nwith captions in a band under the app and step-001.png (one encoded midpoint PNG per step), plus demo.vtt (the captions),\ndemo.json (the edit, segment by segment) and a slide (slide.png, slide.html: the scenario, its steps, who and where,\nthe last screen). Record a run with video first (product-lab test --video, or the lab window's recording).\n  <recording-id>    default: the newest passed feature recording\n  --actor <role>    cut that actor's app video (default: the lab window's, else the actor in most steps)\n  --window          cut the lab window's video\n  --out <dir>       default: <lab>/.product-lab/demos/<recording-id>\n  --max-seconds <n> the target length (default 60); never shortens the step holds\n  --hold-seconds <n> hold each after-step image (default 2, minimum 2 seconds)\n  --format mp4|webm default mp4 (H.264); webm is VP9\n  --plan            only demo.json and demo.vtt (needs no ffmpeg)\n  --slide-only      the plan and the slide, no video (needs no ffmpeg)\n  --failed          allow a failed run: every frame and the slide say it failed\n  --json            print the report as JSON\n  The video needs ffmpeg and ffprobe on PATH (or PRODUCT_LAB_FFMPEG naming their folder); product-lab never bundles them.\n  Exit code: 0 made, 2 refused (no such recording, no video, a failed run without --failed, no ffmpeg) or bad arguments,\n  1 when the lab does not load or the cut fails.";
 export declare function renderDemo(report: DemoReport): string;
 export declare function runDemoCommand(runtime: LabRuntime, argv: string[], signal?: AbortSignal, out?: (text: string) => void, err?: (text: string) => void): Promise<number>;

package/entrypoints/cli/src/demo-command.js

@@ -2,18 +2,19 @@
 // SPDX-License-Identifier: Apache-2.0
 import { parseArgs } from "node:util";
 import { DemoRefusedError } from "@parity/product-lab/domain/recordings";
-export const DEMO_USAGE = `Usage: product-lab demo [<recording-id>] [--actor <role> | --window] [--out <dir>] [--max-seconds 60]
+export const DEMO_USAGE = `Usage: product-lab demo [<recording-id>] [--actor <role> | --window] [--out <dir>] [--max-seconds 60] [--hold-seconds 2]
                         [--format mp4|webm] [--plan | --slide-only] [--failed] [--json] [--config lab.config.ts]
 
-A demo of a recorded feature scenario: its video cut to about a minute, every action at real speed with its result
-held, waits sped up and labelled (×8 waiting for finality), a caption per Gherkin step, plus demo.vtt (the captions),
+A demo of a recorded feature scenario: its real after-step images held for at least 2 seconds each,
+with captions in a band under the app and step-001.png (one encoded midpoint PNG per step), plus demo.vtt (the captions),
 demo.json (the edit, segment by segment) and a slide (slide.png, slide.html: the scenario, its steps, who and where,
 the last screen). Record a run with video first (product-lab test --video, or the lab window's recording).
   <recording-id>    default: the newest passed feature recording
   --actor <role>    cut that actor's app video (default: the lab window's, else the actor in most steps)
   --window          cut the lab window's video
   --out <dir>       default: <lab>/.product-lab/demos/<recording-id>
-  --max-seconds <n> the longest the cut should be (default 60); over it the waits speed up first
+  --max-seconds <n> the target length (default 60); never shortens the step holds
+  --hold-seconds <n> hold each after-step image (default 2, minimum 2 seconds)
   --format mp4|webm default mp4 (H.264); webm is VP9
   --plan            only demo.json and demo.vtt (needs no ffmpeg)
   --slide-only      the plan and the slide, no video (needs no ffmpeg)
@@ -48,6 +49,7 @@ export async function runDemoCommand(runtime, argv, signal, out = (text) => proc
                 window: { type: "boolean" },
                 out: { type: "string" },
                 "max-seconds": { type: "string" },
+                "hold-seconds": { type: "string" },
                 format: { type: "string" },
                 plan: { type: "boolean" },
                 "slide-only": { type: "boolean" },
@@ -66,12 +68,14 @@ export async function runDemoCommand(runtime, argv, signal, out = (text) => proc
         return 0;
     }
     const maxSeconds = values["max-seconds"] === undefined ? undefined : Number(values["max-seconds"]);
+    const holdSeconds = values["hold-seconds"] === undefined ? undefined : Number(values["hold-seconds"]);
     const problem = positionals.length > 1 ? `Unexpected arguments: ${positionals.slice(1).join(" ")}`
         : values.actor !== undefined && values.window ? "--actor and --window cannot be used together"
             : values.plan && values["slide-only"] ? "--plan and --slide-only cannot be used together"
                 : values.format !== undefined && values.format !== "mp4" && values.format !== "webm" ? `--format must be mp4 or webm, not ${values.format}`
                     : maxSeconds !== undefined && !(Number.isFinite(maxSeconds) && maxSeconds >= 5) ? `--max-seconds must be a number of seconds, at least 5, not ${values["max-seconds"]}`
-                        : undefined;
+                        : holdSeconds !== undefined && !(Number.isFinite(holdSeconds) && holdSeconds >= 2) ? `--hold-seconds must be a number of seconds, at least 2, not ${values["hold-seconds"]}`
+                            : undefined;
     if (problem) {
         err(`${problem}\n${DEMO_USAGE}\n`);
         return 2;
@@ -84,6 +88,7 @@ export async function runDemoCommand(runtime, argv, signal, out = (text) => proc
             ...(values.window ? { window: true } : {}),
             ...(values.out !== undefined ? { out: values.out } : {}),
             ...(maxSeconds !== undefined ? { maxSeconds } : {}),
+            ...(holdSeconds !== undefined ? { holdSeconds } : {}),
             ...(values.format ? { format: values.format } : {}),
             ...(values.plan ? { planOnly: true } : {}),
             ...(values["slide-only"] ? { slideOnly: true } : {}),

package/entrypoints/mcp/README.md

@@ -202,3 +202,6 @@ the file. Neither live script is part of the unit suite.
 
 The reload test creates its ES-module lab in an OS temporary directory, linking this package's `node_modules`.
 Concurrent lint can no longer discover a generated lab under the repository's `tests/` without a TypeScript project.
+
+Design-resource hashes track the current topic text, including the distinction between passive frames-only
+capture and awaited video capture at feature boundaries.

package/entrypoints/panel/README.md

@@ -417,9 +417,10 @@ Every running actor's app tile has a compact, browser-like address bar in the co
   (`data-frame`), so a re-created frame never receives an old frame's address. The bar never shows a guessed location.
 
 Tests: `node --import tsx --test entrypoints/panel/tests/address-bar.test.ts` (served shell, headless Chromium,
-loopback fixture apps on ephemeral ports; a normal tab and the lab window via `openLabWindow`, including real
-`framenavigated` reports and the acting guard). Optional `ADDRESS_BAR_SCREENS=<directory>` writes review screenshots
-(unset: none).
+loopback fixture apps on ephemeral ports that count browser requests by `Sec-Fetch-Dest`, which Chromium sends
+to these loopback origins, ignoring a local port probe without that header;
+a normal tab and the lab window via `openLabWindow`, including real `framenavigated` reports and the acting guard).
+Optional `ADDRESS_BAR_SCREENS=<directory>` writes review screenshots (unset: none).
 
 ## Visible execution: `@product-lab/shell/visible`
 
@@ -1771,3 +1772,5 @@ Framing reuse (item82): the framing section above retains the original item66 be
 The drawer puts its existing tabs in a full-width row below the title and Close control. Tabs wrap at narrow widths, keeping Recordings reachable without replacing the live app frame. Watch controls the displayed app in a window opened through `openLabWindow`; the server can keep running in the background while that window remains visible.
 
 Opening a recording displays its captured screenshots over the mounted app, with Play/Pause and previous/next screenshot controls. The viewer labels its fixed1.5s image cadence and absence of video; it cannot recover typing or clicks between captures. Back to live restores the app and run controls. Active runs are checked before and after loading the recording, using the latest panel snapshot. The run audit remains available even with zero recorded steps, and incomplete audits explicitly explain that proof is missing.
+
+Recording captures of tiles and detached windows honor `CaptureOptions.loadComplete` before taking their image and report `loadComplete: true` when checked. Only video feature after-frame checks request this wait; normal captures retain their existing policy. Tests: `tests/window-frames.test.ts` and `tests/detached-identities.test.ts`.

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

@@ -195,6 +195,10 @@ export function detachedFrameCapture(tiles, detached, options = {}) {
             const timeoutMs = captureOptions?.timeoutMs ?? options.timeoutMs ?? DETACHED_CAPTURE_TIMEOUT_MS;
             if (signal?.aborted)
                 throw new Error(`${window.actor.name}'s detached window was not captured: the recorder stopped waiting`);
+            if (captureOptions?.loadComplete) {
+                await window.app.waitForFunction(() => document.readyState === "complete", undefined, { timeout: timeoutMs });
+                signal?.throwIfAborted();
+            }
             const started = Date.now();
             const unsettled = captureOptions?.settled?.selectors.length ? await settle(window.app, captureOptions.settled) : undefined;
             if (unsettled)
@@ -211,7 +215,7 @@ export function detachedFrameCapture(tiles, detached, options = {}) {
                     throw new Error(`${window.actor.name}'s detached window gave no frame within ${timeoutMs} ms`, { cause: error });
                 throw new Error(`${window.actor.name}'s detached window could not be captured: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
             }
-            return { status: "captured", mediaType: "image/png", bytes: new Uint8Array(bytes), ...settled };
+            return { status: "captured", mediaType: "image/png", bytes: new Uint8Array(bytes), ...settled, ...(captureOptions?.loadComplete ? { loadComplete: true } : {}) };
         },
     };
 }

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

@@ -13,6 +13,19 @@ export function windowFrameCapture(page, frameSelector, media, videos, uiCalls)
         video: () => windowVideo(page, videos, { source: "lab-window", scope: "window" }),
         async capture(actorId, options) {
             const selector = frameSelector(actorId);
+            if (options?.loadComplete) {
+                const element = await page.locator(selector).elementHandle({ timeout: options.timeoutMs });
+                try {
+                    const app = await element?.contentFrame();
+                    if (!app)
+                        return { status: "unavailable", reason: "The displayed app has no current document" };
+                    await app.waitForLoadState("load", { timeout: options.timeoutMs });
+                }
+                finally {
+                    await element?.dispose();
+                }
+                options.signal?.throwIfAborted();
+            }
             const started = Date.now();
             const unsettled = options?.settled?.selectors.length ? await settle(page.frameLocator(selector), options.settled) : undefined;
             if (unsettled)
@@ -45,7 +58,7 @@ export function windowFrameCapture(page, frameSelector, media, videos, uiCalls)
                     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 };
+                        return { status: "captured", mediaType: "image/png", bytes: new Uint8Array(bytes), ...settled, ...(options?.loadComplete ? { loadComplete: true } : {}) };
                 }
                 finally {
                     if (!shot)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parity/product-lab",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "description": "Run and test Polkadot products against real local chains, hosts and browsers: the framework and the product-lab CLI.",
   "license": "Apache-2.0",