venetian 0.2.0-aarch64-linux → 0.2.3-aarch64-linux

data/exe/aarch64-linux/package/lib/tools/cli-client/session.js

@@ -130,6 +130,10 @@ to start the browser session.`);
     ];
     if (cliArgs.headed)
       args.push("--headed");
+    if (cliArgs.mobile)
+      args.push("--mobile");
+    if (cliArgs.device)
+      args.push(`--device=${cliArgs.device}`);
     if (cliArgs.browser)
       args.push(`--browser=${cliArgs.browser}`);
     if (cliArgs.persistent)
@@ -147,8 +151,9 @@ to start the browser session.`);
     const child = (0, import_child_process.spawn)(process.execPath, args, {
       detached: true,
       stdio: ["ignore", "pipe", err],
-      cwd: process.cwd()
+      cwd: process.cwd(),
       // Will be used as root.
+      windowsHide: true
     });
     let signalled = false;
     const sigintHandler = () => {

data/exe/aarch64-linux/package/lib/tools/{cli-client/skill → skills/playwright-cli}/SKILL.md

@@ -47,6 +47,11 @@ playwright-cli upload ./document.pdf
 playwright-cli check e12
 playwright-cli uncheck e12
 playwright-cli snapshot
+# search the snapshot for text or a regexp, returns matching nodes with surrounding context
+playwright-cli find "Sign in"
+playwright-cli find --regex "Sign (in|up)"
+# wrap the regexp in slashes to add flags, e.g. /i for case-insensitive
+playwright-cli find --regex "/sign (in|up)/i"
 playwright-cli eval "document.title"
 playwright-cli eval "el => el.textContent" e5
 # get element id, class, or any attribute not visible in the snapshot
@@ -93,6 +98,7 @@ playwright-cli mousewheel 0 100
 playwright-cli screenshot
 playwright-cli screenshot e5
 playwright-cli screenshot --filename=page.png
+playwright-cli screenshot --hires
 playwright-cli pdf --filename=page.pdf
 ```
 
@@ -159,6 +165,11 @@ playwright-cli run-code "async page => await page.context().grantPermissions(['g
 playwright-cli run-code --filename=script.js
 playwright-cli tracing-start
 playwright-cli tracing-stop
+
+# record user actions in the browser, print them as Playwright code on stop
+playwright-cli recording-start
+playwright-cli recording-stop
+
 playwright-cli video-start video.webm
 playwright-cli video-chapter "Chapter Title" --description="Details" --duration=2000
 playwright-cli video-stop
@@ -209,6 +220,12 @@ playwright-cli open --browser=firefox
 playwright-cli open --browser=webkit
 playwright-cli open --browser=msedge
 
+# Emulate a generic mobile device (Pixel 10 for Chromium, iPhone 17 for WebKit).
+# Prefer this when a mobile layout is acceptable: mobile pages are usually
+# lighter, so snapshots are smaller and cheaper.
+playwright-cli open --mobile
+playwright-cli open --device="iPhone 15"
+
 # Use persistent profile (by default profile is in-memory)
 playwright-cli open --persistent
 # Use persistent profile with custom directory
@@ -278,6 +295,11 @@ playwright-cli snapshot e34
 
 # include each element's bounding box as [box=x,y,width,height]
 playwright-cli snapshot --boxes
+
+# search a large snapshot instead of capturing it all — returns matching nodes
+# with 3 lines of context around each match (like grep -C)
+playwright-cli find "Add to cart"
+playwright-cli find --regex "\\$[0-9]+\\.[0-9]{2}"
 ```
 
 ## Targeting elements
@@ -325,13 +347,13 @@ playwright-cli kill-all
 
 ## Installation
 
-If global `playwright-cli` command is not available, try a local version via `npx playwright-cli`:
+If global `playwright-cli` command is not available, try a local version via `npx playwright cli`:
 
 ```bash
-npx --no-install playwright-cli --version
+npx --no-install playwright --version
 ```
 
-When local version is available, use `npx playwright-cli` in all commands. Otherwise, install `playwright-cli` as a global command:
+When local version is available, use `npx playwright cli` in all commands. Otherwise, install `playwright-cli` as a global command:
 
 ```bash
 npm install -g @playwright/cli@latest
@@ -396,9 +418,8 @@ playwright-cli show --annotate
 * **Request mocking** [references/request-mocking.md](references/request-mocking.md)
 * **Running Playwright code** [references/running-code.md](references/running-code.md)
 * **Browser session management** [references/session-management.md](references/session-management.md)
-* **Spec-driven testing (plan / generate / heal)** [references/spec-driven-testing.md](references/spec-driven-testing.md)
 * **Storage state (cookies, localStorage)** [references/storage-state.md](references/storage-state.md)
-* **Test generation** [references/test-generation.md](references/test-generation.md)
+* **Test generation (plan / generate / heal)** [references/test-generation.md](references/test-generation.md)
 * **Tracing** [references/tracing.md](references/tracing.md)
 * **Video recording** [references/video-recording.md](references/video-recording.md)
 * **Inspecting element attributes** [references/element-attributes.md](references/element-attributes.md)

data/exe/aarch64-linux/package/lib/tools/{cli-client/skill/references/spec-driven-testing.md → skills/playwright-cli/references/test-generation.md}

@@ -1,12 +1,141 @@
-# Spec-driven testing (plan → generate → heal)
+# Test generation (plan → generate → heal)
 
-End-to-end workflow for authoring and maintaining Playwright tests using `playwright-cli`. The three sections below can be used independently:
+End-to-end workflow for authoring and maintaining Playwright tests with `playwright-cli`. Every `playwright-cli` action emits the equivalent Playwright TypeScript, and that generated code is the raw material for every test. The sections below can be used independently:
 
-- **Planning** — explore the app, produce a spec file describing what to test.
+- **How generation works** — the core mechanic everything else relies on: actions become TypeScript, plus how to add assertions.
+- **Plan** — explore the app, produce a spec file describing what to test.
 - **Generate** — turn a spec into Playwright test files. Update the spec if it's vague or stale.
 - **Heal** — diagnose failing tests, fix the code, reconcile the spec with reality.
 
-All three lean on the same mechanic: run `npx playwright test --debug=cli` in the background, then `playwright-cli attach tw-XXXX` to drive the paused page interactively. See [playwright-tests.md](playwright-tests.md) for the debug/attach mechanics and [test-generation.md](test-generation.md) for how every `playwright-cli` action emits Playwright TypeScript.
+Plan / generate / heal lean on the same mechanic: run `npx playwright test --debug=cli` in the background, then `playwright-cli attach tw-XXXX` to drive the paused page interactively. See [playwright-tests.md](playwright-tests.md) for the debug/attach mechanics.
+
+---
+
+## 0. How generation works
+
+Every action you perform with `playwright-cli` generates corresponding Playwright TypeScript code. This code appears in the output and can be copied directly into your test files.
+
+```bash
+# Start a session
+playwright-cli open https://example.com/login
+
+# Take a snapshot to see elements
+playwright-cli snapshot
+# Output shows: e1 [textbox "Email"], e2 [textbox "Password"], e3 [button "Sign In"]
+
+# Fill form fields - generates code automatically
+playwright-cli fill e1 "user@example.com"
+# Ran Playwright code:
+# await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');
+
+playwright-cli fill e2 "password123"
+# Ran Playwright code:
+# await page.getByRole('textbox', { name: 'Password' }).fill('password123');
+
+playwright-cli click e3
+# Ran Playwright code:
+# await page.getByRole('button', { name: 'Sign In' }).click();
+```
+
+### Building a test file
+
+Collect the generated code into a Playwright test:
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('login flow', async ({ page }) => {
+  // Generated code from playwright-cli session:
+  await page.goto('https://example.com/login');
+  await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');
+  await page.getByRole('textbox', { name: 'Password' }).fill('password123');
+  await page.getByRole('button', { name: 'Sign In' }).click();
+
+  // Add assertions
+  await expect(page).toHaveURL(/.*dashboard/);
+});
+```
+
+### Use semantic locators
+
+The generated code uses role-based locators when possible, which are more resilient:
+
+```typescript
+// Generated (good - semantic)
+await page.getByRole('button', { name: 'Submit' }).click();
+
+// Avoid (fragile - CSS selectors)
+await page.locator('#submit-btn').click();
+```
+
+### Explore before recording
+
+Take snapshots to understand the page structure before recording actions:
+
+```bash
+playwright-cli open https://example.com
+playwright-cli snapshot
+# Review the element structure
+playwright-cli click e5
+```
+
+### Add assertions manually
+
+Generated code captures actions but not assertions. Add expectations in your test using one of the recommended matchers:
+
+- `toBeVisible()` — element is rendered and visible
+- `toHaveText(text)` — element text content matches
+- `toHaveValue(value) / toBeEmpty()` — input/select value matches
+- `toBeChecked() / toBeUnchecked()` — checkbox state matches
+- `toMatchAriaSnapshot(snapshot)` — page (or locator) matches a partial accessibility snapshot
+
+Use `playwright-cli generate-locator <target>` to produce the locator expression for the assertion, and the snapshot/eval commands to capture the expected value.
+
+When asserting text content, make sure that generated locator does not contain text from the element itself. `getByTestId()` or `getByLabel()` usually work well with asserting text. When locator is text-based, prefer `toBeVisible()` instead.
+
+Snapshot to be matched does not have to contain all the information - only capture what's necessary for the assertion. You can use regular expressions for unstable values.
+
+```bash
+# Get a stable locator for an element ref to use in the assertion
+playwright-cli --raw generate-locator e5
+# getByRole('button', { name: 'Submit' })
+
+# Capture expected text content for toHaveText
+playwright-cli --raw eval "el => el.textContent" e5
+
+# Capture expected input value for toHaveValue/toBeEmpty
+playwright-cli --raw eval "el => el.value" e5
+
+# Capture expected aria snapshot for toMatchAriaSnapshot/toBeChecked
+# (whole page, or use a ref to scope to a region)
+playwright-cli --raw snapshot
+playwright-cli --raw snapshot e5
+```
+
+```typescript
+// Generated action
+await page.getByRole('button', { name: 'Submit' }).click();
+
+// Manual assertions using the outputs above:
+await expect(page.getByRole('alert', { name: 'Success' })).toBeVisible();
+await expect(page.getByTestId('main-header')).toHaveText('Welcome, user');
+await expect(page.getByRole('textbox', { name: 'Email' })).toHaveValue('user@example.com');
+await expect(page.getByRole('checkbox', { name: 'Enable notifications' })).toBeChecked();
+
+// toMatchAriaSnapshot on the whole page, finds a matching region
+await expect(page).toMatchAriaSnapshot(`
+  - heading "Welcome, user"
+  - link /\\d+ new messages?/
+  - button "Sign out"
+`);
+
+// toMatchAriaSnapshot scoped to a region
+await expect(page.getByRole('navigation')).toMatchAriaSnapshot(`
+  - link "Home"
+  - link /\\d+ new messages?/
+  - link "Profile"
+`);
+```
 
 ---
 
@@ -173,7 +302,7 @@ playwright-cli attach tw-XXXX
 
 Walk the scenario's `Steps:` one by one with `playwright-cli`, treating the spec as the plan and the live app as the source of truth. If a step is vague ("click the button" — which button?), references an element that no longer exists, or contradicts the app's actual behaviour, use your judgement: update the spec to match what the app really does, then keep going. Editing the spec mid-generation is expected.
 
-Every action prints the equivalent Playwright TypeScript (see [test-generation.md](test-generation.md)):
+Every action prints the equivalent Playwright TypeScript (see [How generation works](#0-how-generation-works)):
 
 ```bash
 playwright-cli snapshot                         # find refs
@@ -182,7 +311,7 @@ playwright-cli press Enter
 playwright-cli click e7
 ```
 
-For each `- expect:` bullet, add an explicit assertion. See [test-generation.md](test-generation.md) for details.
+For each `- expect:` bullet, add an explicit assertion. See [How generation works](#0-how-generation-works) for details.
 
 Collect the generated code and write the test file at the path given in the spec:
 
@@ -300,6 +429,5 @@ Only after the user answers, either update the spec (intentional change) or file
 | For... | See |
 |---|---|
 | `--debug=cli` / attach mechanics | [playwright-tests.md](playwright-tests.md) |
-| How `playwright-cli` actions become TS | [test-generation.md](test-generation.md) |
 | Mocking requests during exploration/generation | [request-mocking.md](request-mocking.md) |
 | Managing the CLI browser session | [session-management.md](session-management.md) |

data/exe/aarch64-linux/package/lib/tools/{cli-client/skill → skills/playwright-cli}/references/tracing.md

@@ -19,7 +19,7 @@ playwright-cli tracing-stop
 
 ## Trace Output Files
 
-When you start tracing, Playwright creates a `traces/` directory with several files:
+When you start tracing, Playwright creates a `.playwright-cli/traces/` directory with several files:
 
 ### `trace-{timestamp}.trace`
 

data/exe/aarch64-linux/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`.

data/exe/aarch64-linux/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.

data/exe/aarch64-linux/package/lib/tools/skills/playwright-component-testing/references/migration.md

@@ -0,0 +1,89 @@
+# Migrating from @playwright/experimental-ct-react / -vue
+
+The CT packages compiled JSX in the test file and marshalled it into the browser. The gallery
+pattern moves the scenario into a story export that runs natively in the browser: structure (which
+component, its children, providers) plus behavior (state and callbacks, recorded into a hidden
+form for the test to assert on). Plain data props travel through `mount(storyId, props)`;
+`update()` and `unmount()` work as before.
+
+## Concept mapping
+
+| `@playwright/experimental-ct-*` | Gallery pattern |
+|---|---|
+| `mount(<Button title="…" onClick={spy} />)` | Stateful story: the story provides `onClick`, records the effect into a hidden form input; the test asserts `toHaveValue()` |
+| Plain data props from the test | Unchanged in spirit: `mount(id, props)` |
+| JSX children / slots from the test | Cannot cross — bake each composition into its own story export (Vue: `.story.vue` for slot-heavy scenarios) |
+| `component.update(<Button count={2} />)` | `component.update({ count: 2 })` — state-preserving, needs the gallery to reuse its root (`gallery-spec.md`) |
+| `component.unmount()` | `component.unmount()` — backed by the gallery's `window.unmount()` |
+| `beforeMount`/`afterMount` in `playwright/index.ts` | The body of the gallery's `window.mount` (global), or story decorators (per-story) |
+| `hooksConfig` per-test variation | Props: `mount('App/Routing', { route: '/dashboard' })` — the story/decorator interprets them |
+| `router` fixture / MSW handlers in Node | `page.route()` in the test, or MSW `setupWorker` inside a story/decorator |
+| `playwright/index.html` (styles, fonts, theme) | The gallery's `index.html` / entry module imports |
+| `ctViteConfig`, `ctPort`, `ctTemplateDir`, `ctCacheDir` | Gone — the gallery runs through the app's own dev server; port lives in `webServer` + `baseURL`; location is `playwright/gallery/` |
+| `defineConfig` from `@playwright/experimental-ct-react` | Plain `defineConfig` from `@playwright/test`, with `baseURL` = gallery URL, `serviceWorkers: 'block'`, `reuseContext: true` (see `SKILL.md`) |
+
+The CT packages were removed in Playwright 1.63 and are no longer published, so migrate while
+pinned to Playwright 1.62 and upgrade once the last spec is ported.
+
+## Steps
+
+1. Set up the gallery and config per `SKILL.md`. Keep the old CT project running until the last
+   spec is migrated.
+2. For each CT spec, split every `mount(<…/>)` call: JSX structure becomes a story export next to
+   the component; plain data props stay in the test as `mount`'s second argument. Callback spies
+   become story state recorded into a hidden form. A call site that only varies data props usually
+   needs just one generic story that spreads them:
+   `export const Default = (props: ButtonProps) => <Button title="Submit" {...props} />`.
+3. Rewrite the spec: import `test`/`expect` from `@playwright/test`; `mount(<X a={1}/>)`
+   → `mount('X/Default', { a: 1 })`; `update(<X a={2}/>)` → `update({ a: 2 })`;
+   `unmount()` unchanged. `mount` returns a locator for the gallery root — scope the queries:
+   `component.getByRole('button').click()`. Spy assertions become `toHaveValue()` on the story's
+   recorded state.
+4. Port `beforeMount` hooks: app-wide setup into the gallery's `window.mount`; per-test
+   `hooksConfig` branches into props interpreted by a story or decorator.
+5. When all specs are green, delete the CT project from the config, drop the
+   `@playwright/experimental-ct-*` dependency, remove `playwright/index.html`,
+   `playwright/index.ts*` and `playwright/.cache`, and lift the Playwright version pin.
+
+## Gotchas
+
+- **Story ids are strings.** Renaming or moving a story breaks specs at runtime, not compile time
+  — and the suffix-matching resolution can silently match a different story after a rename.
+  Gallery types (`typing.md`) turn registered ids into a compile-time check.
+- **Per-test JSX is gone.** Any test that built a different JSX tree per test (children matrices,
+  inline wrappers) becomes one story export per composition.
+
+## Before / after
+
+```tsx
+// Before (CT)
+import { test, expect } from '@playwright/experimental-ct-react';
+import Button from '../src/components/Button';
+
+test('click', async ({ mount }) => {
+  const messages: string[] = [];
+  const component = await mount(<Button title="Submit" onClick={data => messages.push(data)} />);
+  await component.click();
+  expect(messages).toEqual(['hello']);
+});
+```
+
+```tsx
+// After: src/components/Button.story.tsx
+import Button from './Button';
+
+export const Default = (props: { onClick?: (data: string) => void }) =>
+  <Button title="Submit" {...props} />;
+```
+
+```ts
+// After: src/components/Button.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('click', async ({ mount }) => {
+  const messages: string[] = [];
+  const component = await mount('components/Button/Default', { onClick: (data: string) => messages.push(data) });
+  await component.click();
+  expect(messages).toEqual(['hello']);
+});
+```