@parity/product-lab 0.0.1-placeholder → 0.1.0

package/entrypoints/cli/ai-kit/skills/product-lab-setup/references/minimal-lab.md

@@ -0,0 +1,480 @@
+# The minimal lab, complete (product-lab's `examples/minimal`: the shape to start from)
+
+<!-- Generated from examples/minimal by entrypoints/cli/src/ai/kit-reference.ts when the package is packed. Do not edit. -->
+
+One page, one button, one signed remark on People, checked on the finalized chain and in the UI. The lab is one `lab.config.ts` with only what is about the product (the app's steps, the chains it needs: `chains: ["people"]`, one person on live Paseo next-v2 and one character) and a `lab/` folder: `lab/steps/minimal.ts` (`defineSteps`: one UI action, one UI assertion and the framework's generic chain-event assertion) and `lab/features/` (the scenario and its negative control side by side). Everything else the lab works out: the environments that have People (`fast`, the local dev chain (Omni Node); `paseo-copy`, a local copy of Paseo, Full or Light by this machine; `live-next-v2`, greyed until its person's phrase is set), the truAPI CLI and WASM hosts, free ports, Vite in `app/`, readiness (the host says the app connected), funding on local chains and one chain connection per chain. `npx --no-install product-lab config` shows each value and where it came from. Most product labs start here; the complete notes lab (product-lab-integration skill, `references/notes-lab.md`) adds Statement Store and Bulletin reading, fixtures and modes.
+
+## How to adapt it
+
+1. Install the dev dependencies the files import (pin these versions):
+
+   ```sh
+   npm install --save-dev @parity/product-lab playwright@1.63.0 @noble/hashes@1.8.0 polkadot-api@3.2.1 @parity/product-sdk-host@0.29.0 vite@7.3.6
+   ```
+
+2. Copy `lab.config.ts`, `lab/` and `lab.lock.json` into your repository. Run `npx --no-install product-lab fetch` (it caches the runtime and node binary the lock pins) and `npx --no-install product-lab doctor` (what this machine still lacks, and what fits it). `lab.config.ts` below already runs your people on the released truAPI WASM test host, which `@parity/product-lab` installs (`defaultHost: "truapi-wasm"`, and its modes' hosts): changed from the truAPI CLI host the minimal lab was written for. That host's locked official release takes the lab's local endpoints (https://github.com/paritytech/host-rust-core/pull/1166), so it runs a product's local environment too; `npx --no-install product-lab doctor` says which release is locked and what it provides. No environment variable is required.
+3. Point the app at yours. The lab detects the dev server from your app's `package.json` and gives it the setting names `VITE_PRODUCT_ID` and `VITE_<CHAIN>_GENESIS`. When detection is wrong, or the app reads other names, write `app.devServer` (the command, its arguments with `{port}`, its directory, `updates`) and `app.settings`: the product-lab-app skill. The `MINIMAL_APP_ROOT` branch below shows the declaration.
+4. Replace the product parts in `lab/steps/`: the action's form and button (your app's test ids), the UI assertion, and the chain assertion's pallet, event and expected fields (`chainEventAssertion`; write your own reader only when one event is not enough). Set `app.chains` to the chains your app needs. Rename `minimal` and every `MINIMAL_*` variable to your product's words. Drop `live` and `characters` until you need them.
+5. Check and run: `npx --no-install product-lab config` and `npx --no-install product-lab check --config lab.config.ts` (both start nothing), `npx --no-install product-lab test --config lab.config.ts` (the scenarios, headless; no `cucumber.ts` and no step files: every step is generated from the sentences), and the negative controls (each a scenario tagged `@negative-control`, with `@fails-with:<reason>` when one reason counts):
+
+   ```sh
+   npx --no-install product-lab test --config lab.config.ts --negative-control
+   ```
+
+   or `npx --no-install product-lab --config lab.config.ts` for the lab window, or the MCP tools (`lab_describe`, `env_start`, `run_scenario`, `run_negative_controls`).
+
+The app files show what a product app needs for the lab: test ids, and `data-state` and the result's attributes only because the app already holds those values. It has no readiness element and no account line: the account comes from the host.
+
+## Files
+
+Each file below is a `### <path>` heading followed by its full source, in this order:
+
+- `lab.config.ts`
+- `lab/steps/minimal.ts`
+- `lab.lock.json`
+- `lab/features/minimal.feature`
+- `lab/features/wrong-text.feature`
+- `app/index.html`
+- `app/src/main.ts`
+- `app/vite.config.ts`
+
+### lab.config.ts
+
+```ts
+// The minimal lab: only what is about the product (config redesign, 6 October 2026). One app that needs People, its
+// steps (lab/steps/minimal.ts) and scenarios (lab/features, the default), one person who exists on live Paseo next-v2,
+// and one kind of person. Everything else the lab works out and `product-lab config` shows where each value came from:
+// the environments offered (fast, a local copy of Paseo, live next-v2), the host (the truAPI WASM test host, `defaultHost`:
+// a product runs released hosts only), ports, the dev server (Vite), readiness (the host says the
+// app connected), the runtimes and polkadot-omni-node (lab.lock.json, through the shared cache). Copy this file and
+// lab/ to start a new example ("Copy this to start", README.md). Optional machine inputs are in .env.example.
+import { isAbsolute, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import { defineLab, type ProductLabConfig } from "@parity/product-lab";
+import { minimal } from "./lab/steps/minimal.ts";
+
+export const exampleRoot = fileURLToPath(new URL(".", import.meta.url));
+
+/** `env.MINIMAL_APP_ROOT`: an independently installed copy of the app (the isolated install proof) and its Vite. */
+export function minimalConfig(env: NodeJS.ProcessEnv = process.env): ProductLabConfig {
+  const appRoot = env.MINIMAL_APP_ROOT;
+  if (appRoot && !isAbsolute(appRoot)) throw new Error("MINIMAL_APP_ROOT must be an absolute path");
+  return {
+    name: "Minimal",
+    // The released truAPI WASM test host, which @parity/product-lab installs and which runs everywhere (the truAPI CLI host's locked release takes the lab's local endpoints, #1166, so it runs local environments too).
+    defaultHost: "truapi-wasm",
+    app: {
+      steps: minimal,
+      chains: ["people"],
+      ...(appRoot ? { devServer: {
+        command: relative(exampleRoot, join(appRoot, "node_modules", ".bin", "vite")),
+        args: ["--host", "127.0.0.1", "--port", "{port}", "--strictPort"],
+        cwd: relative(exampleRoot, appRoot),
+        settings: { productId: "VITE_PRODUCT_ID", genesis: "VITE_{CHAIN}_GENESIS" },
+        updates: "vite",
+      } } : {}),
+    },
+    // Live Paseo next-v2, writing (backlog A7): Ada already exists there and holds PAS on People (her phrase in
+    // MINIMAL_LIVE_ADA_MNEMONIC; greyed until it is set; opt-in, never in the gates). One new person per run is
+    // onboarded under `plabtest` and funded by Ada (lab/features/new-identity.feature). What a run writes stays there.
+    live: { "next-v2": { people: { Ada: "MINIMAL_LIVE_ADA_MNEMONIC" }, newPeople: { fundedBy: "Ada", prefix: "plabtest", fund: "5 PAS", maxPerRun: 1 } } },
+    // Backlog 35c: someone with nothing to pay a fee with. The sentence is the framework's; the name is this lab's.
+    characters: { "a person with no funds": { steps: ["{actor} is a new actor with no funds"], description: "A new identity the lab never funds: nothing to pay a fee with" } },
+    // Ways to run (`product-lab test --mode <name>`): merge on the fast chain with the WASM test host at the locked
+    // versions; nightly on every local environment this example offers, at the locked versions and at the latest
+    // releases of everything lab.lock.json pins and of the WASM test host.
+    modes: {
+      merge: { environment: "fast", host: "truapi-wasm", versions: ["locked"] },
+      nightly: { environments: ["fast", "paseo-copy"], hosts: ["truapi-wasm"], versions: ["locked", "latest"] },
+    },
+  };
+}
+
+export default defineLab(minimalConfig());
+```
+
+### lab/steps/minimal.ts
+
+```ts
+// The minimal example's steps (defineSteps; lab/steps since the config redesign, 6 October 2026): one action
+// through the app's UI, a UI assertion and the framework's generic chain-event assertion (no reader of its own). The
+// app has no readiness element and no account line: the account comes from the host, and ready is the default, "the
+// host reports the app connected".
+import { blake2b } from "@noble/hashes/blake2b";
+import { AccountAddress, chainEventAssertion, defineAction, defineAssertion, defineSteps, ExpectedAccount, fail, sameAccount, type ActorSession, type IntegrationChain } from "@parity/product-lab";
+import { matchFields, waitForEvent } from "@parity/product-lab/chain";
+import { defaultSessionPage } from "@parity/product-lab/composition";
+import { HeadlessAppSurface } from "@parity/product-lab/browser-playwright";
+
+const MESSAGES = ["Hello from product-lab", "This is the minimal example"] as const;
+export const remarkHash = (text: string) => `0x${Array.from(blake2b(new TextEncoder().encode(text), { dkLen: 32 }), (b) => b.toString(16).padStart(2, "0")).join("")}`;
+const pageOf = (actorId: string) => defaultSessionPage(actorId) ?? (() => { throw new Error(`No page for actor ${actorId}`); })();
+
+/**
+ * Backlog 111: a send reads its remark back in the step. The app's `finalized` is the app's word; the step then waits
+ * until People's finalized chain shows `System.Remarked` from the actor with the text's hash, scanning from the first
+ * block after the one finalized before the click, and fails at the send step naming the chain side.
+ */
+export async function remarkReadBack(chain: IntegrationChain | undefined, actor: Pick<ActorSession, "name" | "account">, text: string, fromBlock: number, timeoutMs = 60_000) {
+  if (!chain) throw new Error('No "people" chain connection to read the remark back (load the lab through the composition root)');
+  // An identity whose account is not an address (a lab's own placeholder) keeps the exact comparison.
+  const want = { sender: AccountAddress.tryParse(actor.account) ? new ExpectedAccount(actor.account) : actor.account, hash: remarkHash(text) };
+  try {
+    const found = await waitForEvent(chain, `${actor.name}'s remark "${text}" on the finalized chain`, "System", "Remarked", (value) => matchFields(value, want), fromBlock, timeoutMs, "finalized");
+    return { block: found.block, blockHash: found.blockHash };
+  } catch (error) {
+    throw new Error(`${actor.name}'s app reported "${text}" sent and finalized, but People's finalized chain shows no System.Remarked from ${actor.name} with its hash from block #${fromBlock}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+  }
+}
+
+export const minimal = defineSteps({
+  id: "minimal",
+  product: { label: "minimal" },
+  requires: { chains: ["people"] },
+  actions: {
+    send: defineAction({
+      title: "Send a remark",
+      via: "ui",
+      inputs: { message: { type: "choice", label: "Message", options: MESSAGES.map((value) => ({ value, label: value })), default: MESSAGES[0] } },
+      sentences: ["{actor} sends the remark {string}"],
+      async run({ actor, progress, ui: shown, chains }, inputs) {
+        const text = String(inputs.message);
+        progress(`Sending "${text}" in ${actor.name}'s app`);
+        // The surface the run shows this actor's app on (its tile in the lab window), else its session's page.
+        const ui = shown ?? new HeadlessAppSurface(pageOf(actor.id));
+        const people = chains?.people;
+        const fromBlock = people ? (await people.access.finalizedHead()).number + 1 : 0;
+        await ui.fill(ui.app.getByLabel("Message", { exact: true }), text);
+        await ui.click(ui.app.getByTestId("remark-send"));
+        await ui.waitFor(ui.app.locator('[data-testid="remark-send-status"]:is([data-state="finalized"], [data-state="failed"])'), { timeout: 90_000 });
+        const state = await ui.app.getByTestId("remark-send-status").getAttribute("data-state");
+        if (state !== "finalized") throw new Error(`Sending failed in the app: ${state}`);
+        const remark = await remarkReadBack(people, actor, text, fromBlock);
+        progress(`${actor.name}'s remark is in finalized block #${remark.block}`);
+        return { text };
+      },
+    }),
+    // Backlog 35c: the same send by someone who may not be able to pay; whatever the app shows is the next step's to check.
+    attempt: defineAction({
+      title: "Try to send a remark",
+      via: "ui",
+      inputs: { message: { type: "choice", label: "Message", options: MESSAGES.map((value) => ({ value, label: value })), default: MESSAGES[0] } },
+      sentences: ["{actor} tries to send the remark {string}"],
+      async run({ actor, progress, ui: shown }, inputs) {
+        const text = String(inputs.message);
+        progress(`Trying to send "${text}" in ${actor.name}'s app`);
+        const ui = shown ?? new HeadlessAppSurface(pageOf(actor.id));
+        await ui.fill(ui.app.getByLabel("Message", { exact: true }), text);
+        await ui.click(ui.app.getByTestId("remark-send"));
+        await ui.waitFor(ui.app.locator('[data-testid="remark-send-status"]:is([data-state="finalized"], [data-state="failed"])'), { timeout: 90_000 });
+        return { text };
+      },
+    }),
+  },
+  assertions: {
+    shown: defineAssertion({
+      title: "Remark shown in the app",
+      sentence: "{actor}'s remark {string} is shown in the app",
+      async observe({ actor, ui: shown }, args) {
+        const text = String(Object.values(args).at(-1) ?? "");
+        const ui = shown ?? new HeadlessAppSurface(pageOf(actor.id));
+        const result = ui.app.getByTestId("remark-result");
+        await ui.waitFor(result);
+        const [shownAccount, shownText] = await Promise.all([result.getAttribute("data-account"), result.textContent()]);
+        if (!shownAccount || !sameAccount(shownAccount, actor.account)) fail("screen-mismatch", `The app shows ${shownAccount ?? "no"} account, not ${actor.name}'s`);
+        if (shownText !== text) fail("screen-mismatch", `The app shows "${shownText}"; expected "${text}"`);
+      },
+      compare() {},
+    }),
+    // Backlog 35c: what the app shows someone whose send did not go through (the status the app already has).
+    notSent: defineAssertion({
+      title: "The app says the remark was not sent",
+      sentence: "{actor}'s app shows that the remark was not sent",
+      async observe({ actor, ui: shown }) {
+        const status = (shown ?? new HeadlessAppSurface(pageOf(actor.id))).app.getByTestId("remark-send-status");
+        const [state, text] = await Promise.all([status.getAttribute("data-state"), status.textContent()]);
+        if (state !== "failed") fail("screen-mismatch", `${actor.name}'s app shows the send as ${state ?? "nothing"} ("${text ?? ""}"), not failed`);
+        return { shown: text ?? "" };
+      },
+      compare() {},
+    }),
+    onChain: chainEventAssertion({
+      title: "Remark stored on the finalized chain",
+      sentence: "{actor}'s remark {string} is on the finalized chain",
+      pallet: "System",
+      event: "Remarked",
+      expected: (account, text) => ({ sender: account, hash: remarkHash(text) }),
+    }),
+  },
+});
+```
+
+### lab.lock.json
+
+```json
+{
+  "schema": 1,
+  "components": {
+    "binary:polkadot-omni-node": {
+      "version": "polkadot-stable2606-2",
+      "source": {
+        "type": "github-release",
+        "repository": "paritytech/polkadot-sdk",
+        "tag": "polkadot-stable2606-2"
+      },
+      "digests": {
+        "file:aarch64-apple-darwin": "sha256:1fa97ad532da1f74eb51031f260fa48402a4bbbdaedd1198b2f65d936e9d37b1",
+        "file:x86_64-unknown-linux-gnu": "sha256:b85f59bdea6fd005fcb948bdb48ab90e6814e5511c5406c0556bb3efa77e45a9"
+      },
+      "selector": {
+        "release": "paritytech/polkadot-sdk@polkadot-stable2606-2"
+      },
+      "resolvedAt": "2026-09-25T11:23:27.873Z",
+      "attributes": {
+        "asset:aarch64-apple-darwin": "polkadot-omni-node-aarch64-apple-darwin",
+        "asset:x86_64-unknown-linux-gnu": "polkadot-omni-node",
+        "nodeVersion": "1.24.2-72284b37a23"
+      }
+    },
+    "runtime:asset-hub": {
+      "version": "v0.3.3",
+      "source": {
+        "type": "github-release",
+        "repository": "paritytech/individuality-community",
+        "tag": "v0.3.3"
+      },
+      "digests": {
+        "code": "blake2-256:34f4b47f4b93129fcdc4936e593346a849622111fbf6ea4ea8325bdaa3f4fa3a",
+        "file": "sha256:a570d57eaaa853341ff4728a84818b4b94ea78f3d80cc62290c27c8dfd16e35e"
+      },
+      "selector": {
+        "release": "paritytech/individuality-community@v0.3.3"
+      },
+      "resolvedAt": "2026-09-25T11:23:27.873Z",
+      "attributes": {
+        "asset": "next_asset_hub_paseo_runtime.compact.compressed.wasm",
+        "specName": "next-asset-hub-paseo",
+        "specVersion": 3003000,
+        "transactionVersion": 21
+      }
+    },
+    "runtime:people": {
+      "version": "v0.3.3",
+      "source": {
+        "type": "github-release",
+        "repository": "paritytech/individuality-community",
+        "tag": "v0.3.3"
+      },
+      "digests": {
+        "code": "blake2-256:90d0e268041cf5e4a6d97dbba4d42e63747196b28becf245fd0de946ff843744",
+        "file": "sha256:0c03c3bb1182eb214a309304d8d46cd8608d50cde011a40be9c2ee9a2c3832b1"
+      },
+      "selector": {
+        "release": "paritytech/individuality-community@v0.3.3"
+      },
+      "resolvedAt": "2026-09-25T11:23:27.873Z",
+      "attributes": {
+        "asset": "next_people_paseo_runtime.compact.compressed.wasm",
+        "specName": "next-people-paseo",
+        "specVersion": 3003000,
+        "transactionVersion": 5
+      }
+    }
+  }
+}
+```
+
+### lab/features/minimal.feature
+
+```gherkin
+Feature: Minimal
+  A person sends a short remark from their product account. The chain and
+  the app are checked independently.
+
+  @minimal @smoke @journey
+  Scenario: A new actor sends a remark
+    Given Ada is a new actor
+    When Ada sends the remark "Hello from product-lab"
+    Then Ada's remark "Hello from product-lab" is shown in the app
+    And Ada's remark "Hello from product-lab" is on the finalized chain
+```
+
+### lab/features/wrong-text.feature
+
+```gherkin
+@negative-control @fails-with:screen-mismatch
+Feature: Negative control: the shown remark is checked against the wrong text
+
+  Scenario: The check expects a remark that was never sent
+    Given Ada is a new actor
+    When Ada sends the remark "Hello from product-lab"
+    Then Ada's remark "Never sent" is shown in the app
+```
+
+### app/index.html
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Minimal</title>
+    <style>
+      body { font: 16px/1.5 system-ui, sans-serif; margin: 0; background: #f6f6f4; color: #1d1d1b; }
+      main { max-width: 28rem; margin: 0 auto; padding: 2rem 1rem; }
+      h1 { margin: 0 0 .25rem; }
+      .muted { color: #6b6b66; font-size: .875rem; word-break: break-all; }
+      form { display: flex; gap: .5rem; margin: 1.5rem 0 .5rem; }
+      label { position: absolute; left: -9999px; }
+      input { flex: 1; padding: .5rem .75rem; border: 1px solid #c9c9c3; border-radius: .5rem; font: inherit; }
+      button { padding: .5rem 1rem; border: 0; border-radius: .5rem; background: #1d1d1b; color: #fff; font: inherit; }
+      button:disabled { opacity: .5; }
+      #remark-result:not(:empty) { background: #fff; border: 1px solid #e3e3de; border-radius: .5rem; padding: .75rem 1rem; }
+    </style>
+  </head>
+  <body>
+    <main>
+      <h1>Minimal</h1>
+      <form data-testid="remark-form">
+        <label for="remark-text">Message</label>
+        <input id="remark-text" data-testid="remark-input" maxlength="128" autocomplete="off" placeholder="Say something on chain" disabled />
+        <button type="submit" data-testid="remark-send" disabled>Send</button>
+      </form>
+      <p class="muted" data-testid="remark-send-status" aria-live="polite"></p>
+      <p data-testid="remark-result"></p>
+    </main>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>
+```
+
+### app/src/main.ts
+
+```ts
+// The minimal product: one button. It reads the actor's product account from
+// the truAPI host, sends one signed remark (`System.remark_with_event`) on
+// People, and shows the result once it finalizes. It knows nothing about the
+// lab and shows nothing for it: no readiness element, no account line, no
+// transaction hash. The lab learns the account from the host, that the app is
+// ready from the host, and a transaction from the chain (docs/design.md, "The
+// lab adapts to the app"). What is left are test ids on what a journey uses
+// and attributes of values the result already has.
+import { AccountId, createClient, type PolkadotClient, type TxCreator } from "polkadot-api";
+import { getAccountsProvider, getHostProvider, isInsideContainerSync } from "@parity/product-sdk-host";
+
+const env = import.meta.env;
+const productId = env.VITE_PRODUCT_ID || "minimal.paseo";
+const genesis = env.VITE_PEOPLE_GENESIS as `0x${string}` | undefined;
+
+const $ = <T extends HTMLElement>(id: string) => document.querySelector<T>(`[data-testid="${id}"]`)!;
+const form = $<HTMLFormElement>("remark-form");
+const input = $<HTMLInputElement>("remark-input");
+const send = $<HTMLButtonElement>("remark-send");
+const sendStatus = $("remark-send-status");
+const result = $("remark-result");
+
+const ss58 = AccountId(42);
+
+type RemarkWithEvent = NonNullable<NonNullable<ReturnType<PolkadotClient["getUnsafeApi"]>["tx"]["System"]>["remark_with_event"]>;
+
+interface Session {
+  address: string;
+  signer: TxCreator;
+  remark: RemarkWithEvent;
+}
+
+async function connect(): Promise<Session> {
+  if (!isInsideContainerSync()) throw new Error("Open this app inside a truAPI host to use your account.");
+  const provider = await getAccountsProvider();
+  if (!provider) throw new Error("The host offers no accounts.");
+  const account = await provider.getProductAccount(productId, 0).match(
+    (value) => value,
+    (error) => {
+      throw new Error(`The host declined the product account: ${String(error)}`);
+    },
+  );
+  if (!genesis) throw new Error("No People chain configured (VITE_PEOPLE_GENESIS).");
+  // The host's refusal (for example an unsupported chain) stays in the message the page shows.
+  const chain = await getHostProvider(genesis).catch((error: unknown) => {
+    throw new Error(`The host does not serve the People chain: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+  });
+  if (!chain) throw new Error("The host does not serve the People chain.");
+  const remark = createClient(chain).getUnsafeApi().tx.System?.remark_with_event;
+  if (!remark) throw new Error("This chain has no System.remark_with_event.");
+  return { address: ss58.dec(account.publicKey), signer: provider.getProductAccountSigner(account), remark };
+}
+
+function setSendState(state: string, message: string) {
+  sendStatus.dataset.state = state;
+  sendStatus.textContent = message;
+}
+
+/** Send one remark and show the result once it finalizes: where it landed
+ * (`data-block`, `data-block-hash`, `data-index`) and whose it is
+ * (`data-account`), plus the text itself, visibly. */
+async function sendRemark(session: Session, text: string): Promise<void> {
+  const tx = session.remark({ remark: new TextEncoder().encode(text) });
+  result.textContent = "";
+  for (const key of ["block", "blockHash", "index", "account"]) delete result.dataset[key];
+  setSendState("signing", "Waiting for the host to sign…");
+  await new Promise<void>((resolve, reject) => {
+    tx.createSubmitAndWatch(session.signer).subscribe({
+      next(event) {
+        if (event.type === "broadcasted") setSendState("submitted", "Submitted");
+        if (event.type === "inBestBlock") setSendState("included", `Included in block #${event.block.number}`);
+        if (event.type === "finalized") {
+          if (!event.ok) {
+            reject(new Error(`The remark failed on chain in block #${event.block.number}`));
+            return;
+          }
+          result.dataset.account = session.address;
+          result.dataset.block = String(event.block.number);
+          result.dataset.blockHash = event.block.hash;
+          result.dataset.index = String(event.block.index);
+          result.textContent = text;
+          setSendState("finalized", `Sent in block #${event.block.number}`);
+          resolve();
+        }
+      },
+      error: reject,
+    });
+  });
+}
+
+async function main() {
+  const session = await connect();
+  input.disabled = false;
+  send.disabled = false;
+  form.addEventListener("submit", (event) => {
+    event.preventDefault();
+    const text = input.value;
+    send.disabled = true;
+    sendRemark(session, text)
+      .then(() => {
+        input.value = "";
+      })
+      .catch((error: unknown) => setSendState("failed", error instanceof Error ? error.message : String(error)))
+      .finally(() => {
+        send.disabled = false;
+      });
+  });
+}
+
+// A person sees why the form stays disabled, in the same line that reports a send.
+main().catch((error: unknown) => setSendState("failed", error instanceof Error ? error.message : String(error)));
+```
+
+### app/vite.config.ts
+
+```ts
+import { defineConfig } from "vite";
+
+// Nothing here is for the lab: the lab's proxy stands in front of this dev server and adds the host's bridge script
+// to the page (docs/design.md, "Any dev server").
+export default defineConfig({
+  base: "./",
+  appType: "mpa",
+  build: { target: "es2022" },
+});
+```

package/entrypoints/cli/ai-kit/skills/product-lab-test-ids/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: product-lab-test-ids
+description: "Add the test ids product-lab uses to observe a product SPA: data-testid on the controls a journey uses and on the elements a check reads. Everything beyond test ids is optional: data-state, data-account, data-finalized-block and data-block only describe values the app already has. Use when a UI check cannot find or scope what it reads, when adding a screen that tests observe, or when reviewing app markup for testability."
+---
+
+# Test ids, and optional attributes
+
+**An app adds test ids at most.** The lab adapts to the app. It never asks an app for a behaviour change, a flag or variable named for the lab, a chosen way of reading the chain (finalized only, one pinned block, no optimistic state) or an attribute as a condition of using the lab. What the lab needs beyond test ids is declared in `lab.config.ts` or found out by the lab.
+
+## Test ids
+
+Put `data-testid="<stable-name>"` on every control a test clicks or fills, every status line, every list or card a check reads, and every item in such a list. It is a stable handle, independent of copy, layout and styling. Use kebab-case product words (`note-list`, `order-submit`), never lab words.
+
+Accessible names still matter: the lab also uses `getByLabel` and roles for form fields, which keeps tests aligned with what users see.
+
+## Optional attributes
+
+These describe values the component already has when it renders. Add one only when that is true. Do not compute, fetch or store a value to fill an attribute, and do not change how the app reads the chain to make one true.
+
+| Attribute (optional) | Put it on | Meaning | Add it when |
+| --- | --- | --- | --- |
+| `data-state="…"` (optional) | Anything asynchronous: connection status, a transaction's progress | A small closed vocabulary, for example `ready`/`failed`; `signing`/`submitted`/`included`/`finalized`/`failed` | The app already tracks the state (it usually shows it as text). Tests then wait for a terminal state instead of sleeping |
+| `data-account="<address>"` (optional) | Each element whose content belongs to one account (account line, account-scoped list, card) | Whose data this render shows | The component already has the address |
+| `data-finalized-block="<n>"` (optional) | An account-scoped container | The finalized block the rendered data was read at | Your app already knows the block it rendered from. An app that renders best-block or optimistic state leaves it out: it cannot set it truthfully |
+| `data-block="<n>"` (optional) | Each item derived from a chain event or extrinsic, and a transaction's status once it lands | Where the item came from | The app already has that block number |
+| `data-source="chain|index|…"` (optional) | Items that can come from different sources | Which path produced the item | The app already knows the path |
+
+The lab asks the page for no readiness element, no account and no transaction hash: it takes the person's account from the host, treats the app as ready when the host reports it connected, and settles a failed step from what the chain and the host saw. An app that connects only after a click, or shows readiness its own way, is declared in `lab.config.ts` (`app.ready`); an app whose host cannot tell the account gets a page reader (under `advanced` for now): both in the product-lab-app skill, never a change to the app.
+
+## How a check uses what the app shows
+
+A check compares what the screen claims with the chain through one function, `checkUiAgainstChain` from `@parity/product-lab`, in the mode that fits how the app renders. Choose the mode from the app; never change the app to fit a mode.
+
+| How the app renders | Mode | What passes |
+| --- | --- | --- |
+| It shows the block it rendered from (`data-finalized-block`, optional: only when the app already knows that block) | `pinned` | The claim equals an independent chain read at exactly that block, and the block is final. The evidence says which block the screen showed |
+| It renders finalized state and shows no block | `eventual` | The claim equals finalized state within a time bound and stays equal for a stability period. The evidence says the rendered block is unknown: a limit of the check, never a fault of the app |
+| It may be ahead of finality (it renders from best blocks, or says "done" from the click) | `optimistic` | While the claim is not final, best-block state or a pending transaction of the actor backs it; it then equals finalized state within the bound. A claim nothing backs, or one the chain finalized without, fails |
+
+- With `data-account`, pass the actor's account as the check's `subject`: a render for another account never agrees.
+- When a step expects a change (a registration, a new item), pass `until`: the check then ends only when screen and chain agree on that change, not on the state before it.
+- Time comes from the chain, never from a countdown on screen.
+- **Every check has a negative control that makes the screen lie**: change what the rendered element claims (a value the chain never held, another account) and see the check fail for that reason (`@negative-control @fails-with:screen-not-backed`, or `screen-mismatch`), with its message recorded.
+
+## Rules
+
+- **The app never knows the lab exists.** No lab imports, no lab terms, no test-only code paths, no "if testing" flags, no lab setup advice in the UI. Test ids and descriptive attributes are generic: any tool could use them.
+- **An attribute says what was rendered.** When you add one, set it from the data you rendered, in the same update as the content: the block a list was read at, not "now". An attribute updated separately from the content makes the check lie.
+- **Scope, never scan.** Checks read inside one `data-testid` container; the page may contain other accounts or stale copies.
+- **Keep IDs stable** across refactors and copy changes; renaming one is a breaking change for the tests.
+- **Do not expose secrets** (keys, session tokens, signed payloads) in attributes.
+
+## Example (a notes list)
+
+The notes app reads its list at a finalized block, so it already has the block number and can show it:
+
+```ts
+list.dataset.account = session.address;
+if (finalized !== undefined) list.dataset.finalizedBlock = String(finalized);
+list.dataset.count = String(notes.size);
+for (const note of notes) {
+  const item = document.createElement("li");
+  item.dataset.testid = "note";
+  item.dataset.block = String(note.block);
+  item.dataset.source = note.source;
+  item.textContent = note.text;
+  list.append(item);
+}
+```
+
+Its check waits for `note-list` with `data-account === actor` and a rendered block at or after the chain's, reads exactly one matching `note`, compares its `data-block` with the block the chain read found, reloads, and repeats. That is the `pinned` mode. An app that shows no block keeps its test ids; its check runs in `eventual` or `optimistic` mode, as described above.
+
+## When a check wants more than the app shows
+
+Propose test ids to the app owners as a normal product change. Until they land, a lab-side patch may add test ids and attributes of values the component already has, and nothing else; never patch an app's behaviour from the lab. Do not ask the app to change how it loads or shows data so that a check becomes easier. If a check cannot prove something from what the app shows, say so in the check and in its result: a check in `eventual` or `optimistic` mode cannot say which block the app rendered from, and the evidence names the mode that ran.
+
+## Verify
+
+`read_ui` (MCP) returns what a scoped reader sees for an actor; compare it with `read_chain`. A missing test id or a stale value shows up there before it shows up as a flaky scenario.

package/entrypoints/cli/bin/esbuild-own-session.sh

@@ -0,0 +1,8 @@
+#!/bin/sh
+# tsx's esbuild, in a session of its own (lane E2, 6 October 2026): tsx starts esbuild's service for the lab's lifetime
+# whenever its transform cache is cold, and in the terminal's foreground process group a terminal that names its
+# foreground process in the title (macOS Terminal) showed "esbuild" instead of the lab. setsid (Linux) or perl
+# (macOS) leaves the session and execs the binary in place: the same process, so esbuild's API still owns it.
+# product-lab.mjs points ESBUILD_BINARY_PATH here, for tsx's esbuild only (esbuild-session.mjs).
+if command -v setsid >/dev/null 2>&1; then exec setsid "$PRODUCT_LAB_ESBUILD_BINARY" "$@"; fi
+exec perl -MPOSIX -e 'POSIX::setsid(); exec { $ARGV[0] } @ARGV or die "esbuild: $!\n"' "$PRODUCT_LAB_ESBUILD_BINARY" "$@"

package/entrypoints/cli/bin/esbuild-session.mjs

@@ -0,0 +1,70 @@
+// tsx's esbuild out of the terminal's foreground process group (lane E2, 6 October 2026), for product-lab.mjs. Plain
+// JavaScript: it runs before tsx is registered.
+import { randomUUID } from "node:crypto";
+import { accessSync, constants, existsSync, rmSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { delimiter, join } from "node:path";
+import process from "node:process";
+import { fileURLToPath, pathToFileURL, URL } from "node:url";
+
+const WRAPPER = fileURLToPath(new URL("./esbuild-own-session.sh", import.meta.url));
+
+/** Whether the wrapper can run: a copy that lost its mode (or the file) would leave tsx unable to start esbuild at all. */
+function runnable(file) {
+  try {
+    accessSync(file, constants.X_OK);
+    return true;
+  } catch (error) {
+    if (error?.code === "EACCES" || error?.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+/** tsx's own esbuild binary (the version its esbuild API expects), or undefined where it cannot be found. */
+export function tsxEsbuildBinary(from = import.meta.url) {
+  try {
+    const tsx = createRequire(createRequire(from).resolve("tsx/package.json"));
+    const esbuild = createRequire(tsx.resolve("esbuild/package.json"));
+    return esbuild.resolve(`@esbuild/${process.platform}-${process.arch}/bin/esbuild`);
+  } catch (error) {
+    // Not installed this way (another layout, a platform without a native package): esbuild finds its own, as before.
+    if (error?.code === "MODULE_NOT_FOUND" || error?.code === "ERR_PACKAGE_PATH_NOT_EXPORTED") return undefined;
+    throw error;
+  }
+}
+
+/**
+ * Start tsx's esbuild in a session of its own (esbuild-own-session.sh), for a lab in a terminal. A terminal that names
+ * its foreground process in the title (macOS Terminal) showed "esbuild" for the lab's whole life whenever tsx's
+ * transform cache was cold: tsx's esbuild starts its service (in a worker it makes at the first transform) in the
+ * terminal's foreground process group.
+ *
+ * Call it before tsx's `register()`; it points ESBUILD_BINARY_PATH at the wrapper. Then await `started()`: it has tsx
+ * transform one new file, so esbuild's worker (which copies the variables when it is made) and its service start now,
+ * through the wrapper, and then the variables leave this process: nothing the lab starts (an app's dev server with an
+ * esbuild of another version) inherits them. Nothing changes without a terminal, on Windows, when ESBUILD_BINARY_PATH
+ * is already set, when the wrapper cannot run, or without setsid or perl on the PATH.
+ */
+export function esbuildInOwnSession({ env = process.env, terminal = Boolean(process.stdin.isTTY && process.stdout.isTTY), binary = tsxEsbuildBinary(), directory = tmpdir(), wrapper = WRAPPER } = {}) {
+  const onPath = (name) => (env.PATH ?? "").split(delimiter).some((entry) => entry && existsSync(join(entry, name)));
+  if (!terminal || process.platform === "win32" || env.ESBUILD_BINARY_PATH || !binary || !runnable(wrapper) || !(onPath("setsid") || onPath("perl")))
+    return { applied: false, started: async () => undefined };
+  env.ESBUILD_BINARY_PATH = wrapper;
+  env.PRODUCT_LAB_ESBUILD_BINARY = binary;
+  return {
+    applied: true,
+    started: async () => {
+      // New content each time, so tsx's cache cannot answer it without esbuild.
+      const file = join(directory, `product-lab-esbuild-${process.pid}-${randomUUID()}.ts`);
+      try {
+        writeFileSync(file, `export const started: string = ${JSON.stringify(randomUUID())};\n`);
+        await import(pathToFileURL(file).href);
+      } finally {
+        rmSync(file, { force: true });
+        delete env.ESBUILD_BINARY_PATH;
+        delete env.PRODUCT_LAB_ESBUILD_BINARY;
+      }
+    },
+  };
+}