rebrowser-playwright-core 1.49.1 → 1.64.1

package/lib/tools/skills/playwright-cli/references/tracing.md

@@ -0,0 +1,139 @@
+# Tracing
+
+Capture detailed execution traces for debugging and analysis. Traces include DOM snapshots, screenshots, network activity, and console logs.
+
+## Basic Usage
+
+```bash
+# Start trace recording
+playwright-cli tracing-start
+
+# Perform actions
+playwright-cli open https://example.com
+playwright-cli click e1
+playwright-cli fill e2 "test"
+
+# Stop trace recording
+playwright-cli tracing-stop
+```
+
+## Trace Output Files
+
+When you start tracing, Playwright creates a `.playwright-cli/traces/` directory with several files:
+
+### `trace-{timestamp}.trace`
+
+**Action log** - The main trace file containing:
+- Every action performed (clicks, fills, navigations)
+- DOM snapshots before and after each action
+- Screenshots at each step
+- Timing information
+- Console messages
+- Source locations
+
+### `trace-{timestamp}.network`
+
+**Network log** - Complete network activity:
+- All HTTP requests and responses
+- Request headers and bodies
+- Response headers and bodies
+- Timing (DNS, connect, TLS, TTFB, download)
+- Resource sizes
+- Failed requests and errors
+
+### `resources/`
+
+**Resources directory** - Cached resources:
+- Images, fonts, stylesheets, scripts
+- Response bodies for replay
+- Assets needed to reconstruct page state
+
+## What Traces Capture
+
+| Category | Details |
+|----------|---------|
+| **Actions** | Clicks, fills, hovers, keyboard input, navigations |
+| **DOM** | Full DOM snapshot before/after each action |
+| **Screenshots** | Visual state at each step |
+| **Network** | All requests, responses, headers, bodies, timing |
+| **Console** | All console.log, warn, error messages |
+| **Timing** | Precise timing for each operation |
+
+## Use Cases
+
+### Debugging Failed Actions
+
+```bash
+playwright-cli tracing-start
+playwright-cli open https://app.example.com
+
+# This click fails - why?
+playwright-cli click e5
+
+playwright-cli tracing-stop
+# Open trace to see DOM state when click was attempted
+```
+
+### Analyzing Performance
+
+```bash
+playwright-cli tracing-start
+playwright-cli open https://slow-site.com
+playwright-cli tracing-stop
+
+# View network waterfall to identify slow resources
+```
+
+### Capturing Evidence
+
+```bash
+# Record a complete user flow for documentation
+playwright-cli tracing-start
+
+playwright-cli open https://app.example.com/checkout
+playwright-cli fill e1 "4111111111111111"
+playwright-cli fill e2 "12/25"
+playwright-cli fill e3 "123"
+playwright-cli click e4
+
+playwright-cli tracing-stop
+# Trace shows exact sequence of events
+```
+
+## Trace vs Video vs Screenshot
+
+| Feature | Trace | Video | Screenshot |
+|---------|-------|-------|------------|
+| **Format** | .trace file | .webm video | .png/.jpeg image |
+| **DOM inspection** | Yes | No | No |
+| **Network details** | Yes | No | No |
+| **Step-by-step replay** | Yes | Continuous | Single frame |
+| **File size** | Medium | Large | Small |
+| **Best for** | Debugging | Demos | Quick capture |
+
+## Best Practices
+
+### 1. Start Tracing Before the Problem
+
+```bash
+# Trace the entire flow, not just the failing step
+playwright-cli tracing-start
+playwright-cli open https://example.com
+# ... all steps leading to the issue ...
+playwright-cli tracing-stop
+```
+
+### 2. Clean Up Old Traces
+
+Traces can consume significant disk space:
+
+```bash
+# Remove traces older than 7 days
+find .playwright-cli/traces -mtime +7 -delete
+```
+
+## Limitations
+
+- Traces add overhead to automation
+- Large traces can consume significant disk space
+- Some dynamic content may not replay perfectly

package/lib/tools/skills/playwright-cli/references/video-recording.md

@@ -0,0 +1,216 @@
+# Video Recording
+
+Capture browser automation sessions as video for debugging, documentation, or verification. Produces WebM (VP8/VP9 codec).
+
+## Basic Recording
+
+```bash
+# Open browser first
+playwright-cli open
+
+# Start recording, --cursor renders an animated mouse cursor that travels to each action point
+# and paces actions by 800ms so that it has time to travel
+playwright-cli video-start demo.webm --cursor --fps=60
+
+# Add a chapter marker for section transitions
+playwright-cli video-chapter "Getting Started" --description="Opening the homepage" --duration=2000
+
+# Navigate and perform actions
+playwright-cli goto https://example.com
+playwright-cli snapshot
+playwright-cli click e1
+
+# Add another chapter
+playwright-cli video-chapter "Filling Form" --description="Entering test data" --duration=2000
+playwright-cli fill e2 "test input"
+
+# Stop and save
+playwright-cli video-stop
+```
+
+## Cursor, Target Highlight and Click Point
+
+Three decorations can be drawn for each action: the mouse **cursor**, a **highlight** box around the
+target element and a **point** marker at the click point. A **title** callout naming the action comes
+with `video-show-actions`. The cursor is the only one `video-start --cursor` turns on; the rest are
+opt-in and styled with plain CSS declarations, so they look exactly the way you want.
+
+```bash
+# Cursor only, nothing else on screen
+playwright-cli video-start demo.webm --cursor
+
+# Action callout, plus a red click point and a dark frame around the target
+playwright-cli video-show-actions --duration=800 --position=top-right \
+  --point-style="width: 20px; height: 20px; border-radius: 50%; background: rgba(255,0,0,.7)" \
+  --highlight-style="outline: 2px solid #333; background: rgba(0,128,255,.15)" \
+  --title-style="font-size: 16px"
+
+# Stop annotating actions
+playwright-cli video-hide-actions
+```
+
+The same options are available programmatically, which is the better choice for hero scripts:
+
+```js
+await page.screencast.showActions({
+  // 'pointer' (default) animates the cursor from the previous action point, 'none' hides it.
+  cursor: 'pointer',
+  // How long decorations stay on screen. Actions are paced by this delay, 500ms by default.
+  duration: 800,
+  // Where the action title goes: top-left, top, top-right, bottom-left, bottom, bottom-right.
+  position: 'top-right',
+  style: {
+    // Marker at the click point. The element is zero-sized and centered on the point,
+    // so give it a size, or draw around the point with box-shadow. Hidden when omitted.
+    point: 'width: 20px; height: 20px; border-radius: 50%; background: rgba(255, 0, 0, .7)',
+    // Box that covers the target element. Hidden when omitted.
+    // Prefer `outline` over `border`, it does not shrink the box.
+    highlight: 'outline: 2px solid #333; background: rgba(0, 128, 255, .15)',
+    // The action title. Use 'display: none' to keep the cursor but drop the callout.
+    title: 'font-size: 16px',
+  },
+});
+```
+
+Notes:
+- All decorations fade out over `duration`. Override `animation` in a style to do something else.
+- The cursor stays on screen at the last action point between actions and across navigations,
+  and travels along a slightly curved path, so it reads as a hand moving a mouse.
+- Call `page.screencast.hideActions()` to stop annotating and hide the cursor.
+
+## Best Practices
+
+### 1. Use Descriptive Filenames
+
+```bash
+# Include context in filename
+playwright-cli video-start recordings/login-flow-2024-01-15.webm
+playwright-cli video-start recordings/checkout-test-run-42.webm
+```
+
+### 2. Record entire hero scripts.
+
+When recording a video for the user or as a proof of work, it is best to create a code snippet and execute it with run-code.
+It allows inserting appropriate pauses between the actions and annotating the video. There are new Playwright APIs for that.
+
+1) Perform scenario using CLI and take note of all locators and actions. You'll need those locators to request their bounding boxes for highlight.
+2) Create a file with the intended script for video (below). Use pressSequentially w/ delay for nice typing, make reasonable pauses.
+3) Use playwright-cli run-code --filename your-script.js
+
+**Important**: Overlays are `pointer-events: none` — they do not interfere with page interactions. You can safely keep sticky overlays visible while clicking, filling, or performing any actions on the page.
+
+```js
+async page => {
+  await page.screencast.start({ path: 'video.webm', size: { width: 1280, height: 800 }, fps: 60 });
+  // Show the cursor and mark the click point, and pace actions by 800ms.
+  await page.screencast.showActions({
+    duration: 800,
+    style: {
+      point: 'width: 20px; height: 20px; border-radius: 50%; background: rgba(255, 0, 0, .7)',
+      title: 'display: none',
+    },
+  });
+  await page.goto('https://demo.playwright.dev/todomvc');
+
+  // Show a chapter card — blurs the page and shows a dialog.
+  // Blocks until duration expires, then auto-removes.
+  // Use this for simple use cases, but always feel free to hand-craft your own beautiful
+  // overlay via await page.screencast.showOverlay().
+  await page.screencast.showChapter('Adding Todo Items', {
+    description: 'We will add several items to the todo list.',
+    duration: 2000,
+  });
+
+  // Perform action
+  await page.getByRole('textbox', { name: 'What needs to be done?' }).pressSequentially('Walk the dog', { delay: 60 });
+  await page.getByRole('textbox', { name: 'What needs to be done?' }).press('Enter');
+  await page.waitForTimeout(1000);
+
+  // Show next chapter
+  await page.screencast.showChapter('Verifying Results', {
+    description: 'Checking the item appeared in the list.',
+    duration: 2000,
+  });
+
+  // Add a sticky annotation that stays while you perform actions.
+  // Overlays are pointer-events: none, so they won't block clicks.
+  const annotation = await page.screencast.showOverlay(`
+    <div style="position: absolute; top: 8px; right: 8px;
+      padding: 6px 12px; background: rgba(0,0,0,0.7);
+      border-radius: 8px; font-size: 13px; color: white;">
+      ✓ Item added successfully
+    </div>
+  `);
+
+  // Perform more actions while the annotation is visible
+  await page.getByRole('textbox', { name: 'What needs to be done?' }).pressSequentially('Buy groceries', { delay: 60 });
+  await page.getByRole('textbox', { name: 'What needs to be done?' }).press('Enter');
+  await page.waitForTimeout(1500);
+
+  // Remove the annotation when done
+  await annotation.dispose();
+
+  // You can also highlight relevant locators and provide contextual annotations.
+  const bounds = await page.getByText('Walk the dog').boundingBox();
+  await page.screencast.showOverlay(`
+    <div style="position: absolute;
+      top: ${bounds.y}px;
+      left: ${bounds.x}px;
+      width: ${bounds.width}px;
+      height: ${bounds.height}px;
+      border: 1px solid red;">
+    </div>
+    <div style="position: absolute;
+      top: ${bounds.y + bounds.height + 5}px;
+      left: ${bounds.x + bounds.width / 2}px;
+      transform: translateX(-50%);
+      padding: 6px;
+      background: #808080;
+      border-radius: 10px;
+      font-size: 14px;
+      color: white;">Check it out, it is right above this text
+    </div>
+  `, { duration: 2000 });
+
+  await page.screencast.stop();
+}
+```
+
+Embrace creativity, overlays are powerful.
+
+### Overlay API Summary
+
+| Method | Use Case |
+|--------|----------|
+| `page.screencast.showChapter(title, { description?, duration?, styleSheet? })` | Full-screen chapter card with blurred backdrop — ideal for section transitions |
+| `page.screencast.showOverlay(html, { duration? })` | Custom HTML overlay — use for callouts, labels, highlights |
+| `disposable.dispose()` | Remove a sticky overlay added without duration |
+| `page.screencast.hideOverlays()` / `page.screencast.showOverlays()` | Temporarily hide/show all overlays |
+| `page.screencast.showActions({ cursor, duration, position, style })` | Cursor, click point, target highlight and action title |
+| `page.screencast.hideActions()` | Stop annotating actions and hide the cursor |
+
+### 3. Attach the recording to the pull request
+
+A hero script recording is the best proof of work for a user-facing change. GitHub accepts WebM as is, so once the recording looks right, attach it with `gh` 2.99+ instead of describing the flow in words:
+
+```bash
+gh pr create --title "feat(todo): add items inline" --body-file body.md --attach ./demo.webm
+gh pr comment 123 --body "Walkthrough of the new flow." --attach ./demo.webm
+gh issue comment 456 --body "Recording of the repro steps." --attach ./repro.webm
+```
+
+`gh` appends unreferenced attachments to the end of the body, which is the right place for a walkthrough. Videos are limited to 10 MB on free plans and 100 MB on paid plans, so keep the script focused, record at a modest size such as 1280x800 and drop chapters that do not add to the story. See [pr-attachments.md](pr-attachments.md) for the full set of commands, including attaching test artifacts from CI.
+
+## Tracing vs Video
+
+| Feature | Video | Tracing |
+|---------|-------|---------|
+| Output | WebM file | Trace file (viewable in Trace Viewer) |
+| Shows | Visual recording | DOM snapshots, network, console, actions |
+| Use case | Demos, documentation | Debugging, analysis |
+| Size | Larger | Smaller |
+
+## Limitations
+
+- Recording adds slight overhead to automation
+- Large recordings can consume significant disk space

package/lib/tools/skills/playwright-component-testing/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: playwright-component-testing
+description: Set up component testing with Playwright using a story gallery — scaffold stories and a gallery dev page driven by the built-in mount fixture, no dedicated component-testing runtime. Use when asked to test React or Vue components in isolation with Playwright, or to migrate off @playwright/experimental-ct-react / -vue.
+---
+
+# Component Testing with Playwright
+
+Test components with regular Playwright e2e tests against a small **story gallery** page hosted by the app's own dev server. No extra test runner, bundler integration or npm packages are required.
+
+## Concept
+
+- A **story** is a tiny wrapper component that embeds the component under test in one specific scenario: hard-coded props, mock data, providers, recorded callbacks. Stories live next to the component in `*.story.tsx` (or `.ts`/`.jsx`/`.js`/`.vue`) files; each named export is one story.
+- The **gallery** is a single page you implement to `references/gallery-spec.md`: it exposes `window.mount(params)` / `window.unmount()` that render a story — resolved from your story files (e.g. with `import.meta.glob`) — into `#root`. It is framework-specific and yours to own — there is no template to copy for it.
+- Tests are plain Playwright tests. The built-in **`mount(storyId, props?)` fixture** (from `@playwright/test`) drives the gallery's `window.mount` and returns a `Locator` for the gallery root (`#root`). Scope the queries from there — `component.getByRole('button').click()`, not `component.click()`. Nothing to scaffold for it.
+
+Everything the component needs must be set up *inside the story* (it runs in the browser); everything the test asserts must be observable *through the page* (DOM, URL, network). Where the component takes callbacks, the story creates the state, provides the callbacks and records the state into a hidden form for the test to assert on. `mount(id, props)` passes plain serializable `props` to the story.
+
+## Setup workflow
+
+1. **Detect the framework and bundler.** React vs Vue decides the framework notes and example story to follow. Then:
+   - **App runs on Vite** (has `vite.config.*`): the gallery is served by the existing dev server at `/playwright/gallery/index.html` — Vite serves any `.html` file under the project root, the app's plugins/aliases/CSS apply automatically, and `vite build` ignores it. No extra server needed.
+   - **Anything else** (Next.js, webpack, no dev server): run a small standalone dev server (e.g. Vite) that serves the gallery page, and point `baseURL` at it. Requires `vite` and the framework plugin as devDependencies.
+2. **Implement the gallery** to `references/gallery-spec.md`: a page at `<project>/playwright/gallery/` that renders the requested story into `#root`. Start from the worked example in the spec and the framework notes in `references/react.md` / `references/vue.md`. Keep story discovery (`import.meta.glob`) and the framework mount here — this is the only framework-specific glue, so keep it small. Import the app's global CSS the same way the app's own entry does.
+3. **Configure Playwright** — add to `playwright.config.ts`:
+
+   ```ts
+   projects: [
+     {
+       name: 'components',
+       testDir: './tests/components',
+       use: { ...devices['Desktop Chrome'], baseURL: 'http://localhost:5173/playwright/gallery/index.html', serviceWorkers: 'block', reuseContext: true },
+     },
+   ],
+   webServer: {
+     command: 'npm run dev',                                       // or: npx vite --config playwright/vite.config.ts
+     url: 'http://localhost:5173/playwright/gallery/index.html',   // standalone server: http://localhost:3100/playwright/gallery/index.html
+     reuseExistingServer: !process.env.CI,
+   },
+   ```
+
+   Match the port to the dev server. `mount` navigates to `baseURL`, so set `baseURL` to the gallery's URL. `serviceWorkers: 'block'` keeps the app's own service worker from serving cached responses that would shadow your `page.route()` mocks. `reuseContext: true` reuses the browser context across tests in a worker (as the old component-testing runtime did) — a large speedup for component suites. If the config already has projects/webServer, merge instead of replacing.
+4. **Write a first story** next to an existing component, modeled on `templates/<react|vue>/Button.story.*`.
+5. **Write a first spec**, modeled on `templates/react/button.spec.ts`, importing `test`/`expect` from `@playwright/test`.
+6. **Run**: `npx playwright test --project=components`. Open `http://localhost:5173/playwright/gallery/index.html` in a browser to eyeball all stories.
+
+## Conventions
+
+- Story id: path under `src/` without the `.story.*` extension, plus the export name — `src/components/Button.story.tsx` export `Primary` → `components/Button/Primary`. Any unique suffix works too: `mount('Button/Primary')`. A `.story.vue` single-file component is one story, addressable by its path alone (its `default` export). With gallery types (`references/typing.md`) ids are prefixed with the package name: `acme-ui/components/Button/Primary`.
+- One export per scenario. Prefer a new story export over parameterizing an existing one — stories are greppable, reviewable documentation of component states.
+
+## Testing patterns
+
+Examples are React; the Vue equivalents differ only in story syntax.
+
+### Callbacks and events
+
+**The story owns the state and provides the callbacks.** Where the component takes callbacks, create the state inside the story, wire the callbacks to it, and record the state into a hidden form next to the component. Tests perform operations and assert on the recorded values:
+
+```tsx
+export const Stateful = () => {
+  const [expanded, setExpanded] = useState(false);
+  return <>
+    <Expandable expanded={expanded} setExpanded={setExpanded} title="Title">Details</Expandable>
+    <form hidden><input data-testid="expanded" readOnly value={String(expanded)} /></form>
+  </>;
+};
+```
+
+```ts
+test('click should expand', async ({ mount }) => {
+  const component = await mount('components/Expandable/Stateful');
+  await component.locator('.codicon-chevron-right').click();
+  await expect(component.getByTestId('expanded')).toHaveValue('true');
+});
+```
+
+This keeps the whole scenario in the browser: no callback marshalling, the story doubles as documentation, and the recorded state is visible when eyeballing the gallery. Record each observed value in its own `data-testid` input (`String(...)` or `JSON.stringify(...)` for payloads) and assert with `toHaveValue()` — a web-first assertion that retries until the state lands. The negative direction works the same way: perform the operation, then assert the value did **not** change.
+
+### Per-test props
+
+When a scenario is genuinely parametric (e.g. a boundary-value sweep), pass props as the second argument to `mount`; the gallery hands them to the story as its props. Keep props to plain serializable data — callbacks belong inside the story.
+
+```tsx
+export const WithTitle = ({ title = 'Default' }: { title?: string }) =>
+  <Button title={title} />;
+```
+
+```ts
+const component = await mount('components/Button/WithTitle', { title: 'Hello' });
+```
+
+Props are type-checked in two optional ways, see `references/typing.md`: pass the story type as a template argument (`mount<typeof WithTitle>('components/Button/WithTitle', { title: 'Hello' })`, no setup), or generate gallery types with a small Vite plugin so the id itself is typed (`mount('acme-ui/components/Button/WithTitle', { title: 'Hello' })`, with autocomplete and rename safety). Vue stories must additionally declare the props at runtime — see the `Typed props` sections in `references/react.md` / `references/vue.md`.
+
+### Prop transitions with `update()`
+
+To test how a component reacts to a prop change **without remounting** (state preserved), call `component.update(newProps)` — it re-renders the same story with new props on the existing root:
+
+```ts
+const component = await mount('components/Counter/Default', { value: 1 });
+await expect(component.getByTestId('value')).toHaveText('1');
+await component.update({ value: 2 });
+await expect(component.getByTestId('value')).toHaveText('2');
+```
+
+This requires the gallery to reuse its root/instance (`references/gallery-spec.md`); state survives as long as the story stays the same.
+
+### Multiple states in one test
+
+Each `mount()` navigates fresh, so tests are fully isolated and mounting several stories in one test is cheap:
+
+```ts
+await expect(await mount('Button/Primary')).toHaveScreenshot('primary.png');
+await expect(await mount('Button/Disabled')).toHaveScreenshot('disabled.png');
+```
+
+For visual comparison, screenshot the returned root locator (as above), not the page, to avoid asserting on browser chrome.
+
+### Network mocking
+
+Use `page.route()` as usual — register routes before `mount()`, since mounting navigates. `serviceWorkers: 'block'` (set in the config above) keeps the app's own service worker from serving cached responses that shadow the routes. Teams with MSW handler libraries can start the worker inside a story or decorator instead.
+
+### Debugging stories
+
+Open your gallery URL (`baseURL`) in a browser and call `await window.mount({ story: 'components/Button/Primary' })` from the devtools console — that is exactly what the `mount` fixture does. An unknown story rejects `window.mount`, which surfaces as the test's `mount()` throwing with a real stack. To browse without the console, give your gallery an optional index page.
+
+## Decision points
+
+- **Monorepos / non-`src` layouts**: change the glob and the id derivation in your gallery (`references/gallery-spec.md`) to match, and prefix ids with the package name (`references/typing.md`).
+- **Global providers** (theme, i18n, store, router): create a shared `decorator` helper next to the gallery and wrap components in stories; see `references/react.md` / `references/vue.md`.
+## References
+
+- `references/gallery-spec.md` — the gallery endpoint contract to implement (**start here**).
+- `references/typing.md` — optional typing for `mount`: explicit story types vs generated gallery types, with the Vite plugin.
+- `references/react.md` — React walkthrough: providers, StrictMode, CSS.
+- `references/vue.md` — Vue walkthrough: `.story.ts` and `.story.vue` stories, plugins.
+- `references/migration.md` — migrating off `@playwright/experimental-ct-react` / `-vue`.

package/lib/tools/skills/playwright-component-testing/references/gallery-spec.md

@@ -0,0 +1,144 @@
+# Gallery contract
+
+The **gallery** is a single page, served by your dev server at the URL you set as `baseURL` in your
+Playwright config, that exposes two methods on `window` for Playwright to drive:
+
+- `window.mount(params)` — render a story.
+- `window.unmount()` — unmount the current story.
+
+The built-in `mount` fixture navigates to the gallery, then calls `window.mount` via
+`page.evaluate()`. Keep props to plain serializable data — where the component takes callbacks,
+the story creates the state, provides the callbacks and records the state into a hidden form for
+the test to assert on.
+
+## `window.mount(params)`
+
+`params` is `{ story, props }`, straight from the test's `mount(story, props)` call:
+
+- `story` — the story id (string). Resolve it (see id grammar) to a component.
+- `props` — the plain serializable props object passed to the component.
+
+Render the resolved component with `props` into `#root`. Return a `Promise` that resolves once the
+component is mounted and **rejects on failure** (unknown story, render throw). The rejection
+surfaces as the test's `await mount(...)` throwing, with a real stack — there is no HTTP-status or
+DOM-attribute signalling.
+
+**Reuse the root across calls.** The test's `component.update(props)` calls `window.mount` again
+with the same story and new props, **without navigating**. If you render into the same root /
+instance rather than recreating it, the framework reconciles and component-internal state is
+preserved — that is CT's `update()`. Recreating the root each call (or navigating) resets state, so
+reuse it: create it on first mount and render into it on every call. The framework reconciles,
+remounting on its own only when the story (component type) changes.
+
+**`window.mount` is your setup/teardown hook.** It is the browser-side equivalent of CT's
+`beforeMount` / `afterMount`: install providers or plugins, seed a store, start an in-browser mock
+server *before* you render, and run post-render work *after* — all inside this one function,
+branched on the `story` / `props` the test passed. There is no separate hook registry; the function
+you own is the hook.
+
+## `window.unmount()`
+
+Unmount the current story from `#root` and return a `Promise`. The test calls it via
+`component.unmount()`. Needed only to assert teardown/cleanup effects — each `mount` navigates
+fresh, so tests are already isolated.
+
+## `#root`
+
+Render the component into an element with `id="root"`. `mount` returns a `Locator` for `#root`
+itself, so tests scope their queries from there — `component.getByRole('button').click()`, not
+`component.click()`. Stories are free to render fragments, e.g. the component plus a hidden form
+recording its state.
+
+## Story id grammar (recommended)
+
+The gallery owns resolution; `mount` passes the id through untouched. Recommended scheme:
+
+- `<path under src, without the .story.* extension>/<ExportName>` — e.g.
+  `src/components/Button.story.tsx` export `Primary` → `components/Button/Primary`.
+- Any unique trailing suffix resolves too: `Button/Primary`.
+- A single-file-component story (`Button.story.vue`) is one story, addressed by its path alone
+  (its default export): `components/Button`.
+
+## Worked example (React + Vite SPA)
+
+An illustration of the contract, **not** a file to copy — implement the equivalent for your stack.
+`import.meta.glob` stays inline here: Vite analyzes it statically, relative to this file, so it
+cannot be moved into shared/shipped code. That is exactly why the gallery is yours to own.
+
+```tsx
+// playwright/gallery/main.tsx
+import { flushSync } from 'react-dom';
+import { createRoot, type Root } from 'react-dom/client';
+
+const stories = import.meta.glob('../../src/**/*.story.{tsx,jsx}');
+const id = (f: string) => f.replace(/^(\.\.\/)+src\//, '').replace(/\.story\.\w+$/, '');
+
+async function resolve(storyId: string) {
+  const sep = storyId.lastIndexOf('/');
+  const [path, name] = [storyId.slice(0, sep), storyId.slice(sep + 1)];
+  const file = Object.keys(stories).find(f => id(f) === path || id(f).endsWith('/' + path));
+  const mod = (file && await stories[file]()) as Record<string, any> | undefined;
+  return mod?.[name] ?? mod?.default;
+}
+
+const rootEl = document.getElementById('root')!;
+let root: Root | undefined;
+
+(window as any).mount = async ({ story, props }: { story: string, props?: Record<string, any> }) => {
+  const Story = await resolve(story);
+  if (!Story)
+    throw new Error(`Unknown story: ${story}`);
+  root ??= createRoot(rootEl);   // reuse the root so update() reconciles and preserves state
+  // flushSync so a render error rejects the promise instead of being swallowed.
+  flushSync(() => root!.render(<Story {...props} />));
+};
+
+(window as any).unmount = async () => {
+  root?.unmount();
+  root = undefined;
+};
+```
+
+```html
+<!-- playwright/gallery/index.html -->
+<!DOCTYPE html>
+<div id="root"></div>
+<script type="module" src="./main.tsx"></script>
+```
+
+## Vue variant (state-preserving)
+
+Vue's `createApp(...).mount()` builds a fresh instance each call, so mount a small **reactive host**
+once and update its refs — updating them re-renders in place, which is what preserves state across
+`update()`:
+
+```ts
+// playwright/gallery/main.ts
+import { createApp, h, shallowRef, type App, type Component } from 'vue';
+
+// resolve() and the import.meta.glob are the same as the React example.
+const story = shallowRef<Component | null>(null);
+const props = shallowRef<Record<string, any>>({});
+const host = { render: () => (story.value ? h(story.value, props.value) : null) };
+let app: App | undefined;
+
+(window as any).mount = async ({ story: id, props: next }: { story: string, props?: Record<string, any> }) => {
+  const resolved = await resolve(id);
+  if (!resolved)
+    throw new Error(`Unknown story: ${id}`);
+  story.value = resolved;
+  props.value = next ?? {};
+  if (!app) {                    // mount once; the ref updates above re-render in place
+    app = createApp(host);
+    app.mount('#root');
+  }
+};
+
+(window as any).unmount = async () => {
+  app?.unmount();
+  app = undefined;
+};
+```
+
+Keep the story-resolution glob and the framework mount in this file; everything
+else lives in your stories and tests.