# Playwemo documentation (Markdown)

Concatenated source for agents. Prefer individual `.md` URLs when you need one page.

---

# api/configure.md

# configureDemoWalk

```ts
function configureDemoWalk(partial: DemoWalkConfig): void
function getDemoWalkConfig(): ResolvedDemoWalkConfig
function resetDemoWalkConfig(): void
function resolveDemoPacing(
  pacing?: DemoPacingConfig,
  options?: { video?: boolean },
): ResolvedDemoPacing
function personaStyle(persona: string): DemoPersonaStyle
function personaLabel(persona: string): string
```

```ts
type DemoWalkConfig = {
  personas?: Record<string, DemoPersonaStyle>;
  layout?: DemoWalkLayout;
  artifactsDir?: string;
  startPath?: string;
  pacing?: DemoPacingConfig;
};

type DemoPacingConfig = {
  pace?: 'tight' | 'normal' | 'slow';
  chapterMs?: number;
  pulseMs?: number;
  afterClickMs?: number;
};
```

Defaults: empty personas, empty layout, empty pacing (`pace: 'normal'`
when resolved), `artifactsDir` = `/opt/cursor/artifacts`
(`DEFAULT_ARTIFACTS_DIR`), `startPath` = `/`.

Pacing is three teaching beats. `pace` scales them (`tight` 0.75,
`normal` 1, `slow` 1.4). Explicit `chapterMs` / `pulseMs` /
`afterClickMs` win. After-click default is 500ms on video and 700ms on
headed stills. Per-call overrides: `demoFocus(..., { chapterMs })`,
`demoClick` / `fillField` / `fillShown` / `demoClickAndWaitUrl`
`{ pulseMs, afterClickMs }`.

`personaStyle` returns `FALLBACK_PERSONA_STYLE` when the id is unknown.

---

# api/device.md

# Device

```ts
type DemoDevice = 'desktop' | 'tablet' | 'mobile';

function resolveDemoDevice(raw: string | undefined): DemoDevice
function demoDeviceFromEnv(env: Record<string, string | undefined>): DemoDevice
function demoContextOptions(device: DemoDevice): DemoDevicePreset
function applyDemoViewport(page: Page, device: DemoDevice): Promise<void>
function isDemoFullscreen(env: Record<string, string | undefined>): boolean
function isOsWindowFullscreen(env: Record<string, string | undefined>): boolean
function presentDemoWindow(
  page: Page,
  env?: Record<string, string | undefined>,
): Promise<void>
```

`DEMO_DEVICE_PRESETS` is the viewport table in the
[devices guide](/guide/devices).

---

# api/index.md

# API overview

Import from the package root:

```ts
import {
  configureDemoWalk,
  runDemoWalk,
  demoFocus,
  demoClick,
} from '@dragonmastery/playwemo';
```

| Area | Entry points |
|---|---|
| Config | `configureDemoWalk`, `getDemoWalkConfig`, `resetDemoWalkConfig`, `resolveDemoPacing` |
| Walk | `runDemoWalk`, `withDemoPages`, `resumeOnSharedPage`, `demoTimeout` |
| Pacing | `demoFocus`, `demoPoint`, `demoClick`, `demoClickAndWaitUrl`, `demoScreenshot`, `fillField`, … |
| Overlay | `installDemoOverlay`, `setDemoCaption`, `setDemoPersona`, `DEMO_OVERLAY` |
| Cursor | `installDemoCursor`, `moveDemoCursor`, `holdDemoCursorRing`, `releaseDemoCursorRing`, `DEMO_CURSOR_ID` |
| Device | `demoContextOptions`, `presentDemoWindow`, `resolveDemoDevice` |
| Record | `isDemoVideo`, `isDemoClean`, `prepareDemoWalkRoot`, `stitchDemoWalk`, `copyWalkForChat` |
| Transcript | `formatWalkTranscriptText`, `isSecretControl` |
| Desktop | `closeStrayBrowserWindows` (optional) |

Types: `DemoPersonaId` is `string`. `DemoWalk<P>` keys pages by those
ids.

Teaching stills: pass `shot` on pacing helpers. See [Stills](/guide/stills).

---

# api/overlay.md

# Overlay

```ts
const DEMO_OVERLAY: {
  rootId: 'e2e-demo-overlay';
  personaId: 'e2e-demo-persona';
  deviceId: 'e2e-demo-device';
  bannerId: 'e2e-demo-banner';
  titleId: 'e2e-demo-banner-title';
  routeId: 'e2e-demo-banner-route';
  noteId: 'e2e-demo-banner-note';
  storageKey: 'e2e.demo.caption';
  personaKey: 'e2e.demo.persona';
  // …
};

function installDemoOverlay(
  context: BrowserContext,
  persona: string,
  device?: DemoDevice,
): Promise<void>

function setDemoCaption(page: Page, next: Partial<DemoCaption>): Promise<void>
function setDemoPersona(page: Page, persona: string): Promise<void>

function paintDemoOverlayInit(args: OverlayInitArgs): void
function installDemoCursor(context: BrowserContext): Promise<void>
function paintDemoCursorInit(args: { storageKey: string; cursorId: string }): void
function moveDemoCursor(page: Page, locator: Locator): Promise<void>
function holdDemoCursorRing(page: Page): Promise<void>
function releaseDemoCursorRing(page: Page): Promise<void>
function hideDemoCursor(page: Page): Promise<void>

const DEMO_CURSOR_ID = 'e2e-demo-cursor'
const DEMO_CURSOR_RING_ID = 'e2e-demo-cursor-ring'
```

`setDemoCaption` no-ops on `about:blank`. It merges fields and calls
`window.__e2ePaintDemoOverlay` when present. `setDemoPersona` writes
`e2e.demo.persona` and repaints the chip from the style map in
`overlayInitArgs` (every configured actor, not only the lead).
`demoFocus` calls both when you pass a bound `walk.page[id]`.

`installDemoCursor` runs on both speeds. The pointer stays hidden until
`moveDemoCursor`. `holdDemoCursorRing` paints one gold ring for the
still; `releaseDemoCursorRing` fades that same ring on headed stills
(CI removes it immediately). Video does not hold the ring — it pulses,
then clicks when that pulse is done, then pauses. Do not call
`pulseDemoCursor` after a hold — that was the double-ring in video.

---

# api/pacing.md

# Pacing helpers

All of these no-op the waits when `E2E_DEMO` is unset, except that
clicks and fills still happen immediately and still record transcript
events.

| Function | Role |
|---|---|
| `demoFocus(page, step, title, note?, opts?)` | Chapter: transcript + caption + bring-to-front + dwell |
| `demoChapter(page, step, title)` | `demoFocus` without a note |
| `demoAnnounce(page, note)` | Current-action line only |
| `demoDwell(page, ms?)` | Pause (default 2400ms) |
| `demoSee(page, ms?)` | Short dwell (default 1200ms) |
| `demoScreenshot(page, name)` | Rest-frame viewport PNG (pointer hidden) |
| `demoPoint(page, locator, opts?)` | Scroll into view, aim, optional `shot` |
| `demoClick(page, locator, opts?)` | Aim, optional `shot`, click |
| `demoClickAndWaitUrl(page, locator, url, opts?)` | Same, then `waitForURL` |
| `fillField(page, locator, value, opts?)` | Aim, optional `shot`, then type |
| `fillIdentityEmail(page, locator, email)` | Sequential keys (80ms) |
| `fillTypedValue(locator, value, delay?)` | Click, record, type or `fill` |
| `fillShown(page, locator, value, opts?)` | Aim, optional `shot`, then `locator.fill` |

`demoClick` options: `{ force?: boolean; waitAfter?: boolean; shot?: string; pulseMs?: number; afterClickMs?: number }`.
`fillField` / `fillShown` / `demoClickAndWaitUrl` also take `pulseMs` /
`afterClickMs`. `demoFocus` takes `{ chapterMs?: number }` as a fifth
argument. App-wide defaults: `configureDemoWalk({ pacing })` — see
[configureDemoWalk](/api/configure).

`shot` writes a teaching still **after** the pointer and held click ring
are on the control, **before** the action — on the stills path. Video
skips the hold and the file so the camera does not freeze on a
still-pose; keep `shot` on the spec anyway. Each click uses one ring
(held, then released — fade on demo, snap-off on CI). On video there is
no hold: the ring pulses, then the click lands when that pulse is
done.

`demoScreenshot` slugs the name (`Vitepress Home` → `vitepress_home.png`)
and hides the pointer (rest frame) when it writes a file. Video skips
the write. When a stills record dir exists, files land in
`<stamp>/screenshots/`. On headed stills they also copy into
`E2E_DEMO_SCREENSHOT_DIR` or `artifactsDir`.

---

# api/record.md

# Record and stitch

Planning (no I/O):

```ts
const DEMO_WALK_ROOT = 'test-results/e2e-demo'
type DemoWalkKind = 'stills' | 'video'

function isDemoVideo(env: Record<string, string | undefined>): boolean
function isDemoScreenshotCapture(
  env?: Record<string, string | undefined>,
): boolean
function demoScreenshotAnimations(
  env: Record<string, string | undefined>,
): 'disabled' | 'allow'
function isDemoClean(env?: Record<string, string | undefined>): boolean
function demoWalkKind(env: Record<string, string | undefined>): DemoWalkKind
function demoWalkKindRoot(env: Record<string, string | undefined>): string
function demoVideoStamp(nowMs: number): string
function demoVideoDir(env: Record<string, string | undefined>, stamp: string): string
function demoChatArtifactPath(
  env: Record<string, string | undefined>,
  artifactsDirAvailable: boolean,
  stamp: string,
): string | null
function evenVideoSize(size: DemoVideoSize): DemoVideoSize
function demoRecordVideoOption(viewport: DemoVideoSize, dir: string): { dir: string; size: DemoVideoSize }
function personaVideoName(persona: string): string
function chapterSegments(chapters: readonly DemoChapter[], endMs: number): DemoChapterSegment[]
function chapterFileRange(
  segment: { startMs: number; endMs: number },
  startedAt: number,
  videoOriginMs: number,
): { startMs: number; endMs: number }
```

I/O (needs `ffmpeg` for stitch):

```ts
function prepareDemoWalkRoot(env?: NodeJS.ProcessEnv): Promise<void>
function ensureDemoVideoDir(dir: string): Promise<void>
function savePersonaVideo(video: Video | null, persona: string, dir: string): Promise<string | null>
function stitchDemoWalk(meta: DemoRecordMeta): Promise<string | null>
function writeDemoRecordManifest(meta: DemoRecordMeta, files: Record<string, string>): Promise<string>
function writeDemoLatestPointer(
  dir: string,
  env?: Record<string, string | undefined>,
): Promise<void>
function copyWalkForChat(walk: string, env?: NodeJS.ProcessEnv, stamp?: string): Promise<string | null>
function writeWalkTranscript(meta: DemoRecordMeta): Promise<string | null>
function copyTranscriptForChat(transcript: string, env?: NodeJS.ProcessEnv, stamp?: string): Promise<string | null>
```

`CURSOR_ARTIFACTS_DIR` is the default artifacts path. Runtime copies use
`getDemoWalkConfig().artifactsDir`.

`isDemoScreenshotCapture` is false while `recordVideo` is on — video
does not hold the ring, write a still, or call `page.screenshot`. The
the click pulse plays, then the click (`pulseDemoCursor`, wait the
full pulse, then act). `demoScreenshotAnimations` is `"disabled"` for
the stills PNG.

`prepareDemoWalkRoot` keeps prior stamps unless `E2E_DEMO_CLEAN=1`.
Stamps land under `e2e-demo/stills/<stamp>/` or `e2e-demo/video/<stamp>/`
from `isDemoVideo`. Each kind has its own `latest.txt`. Playwright
`outputDir` must be `test-results/playwright` (not `test-results`) so a
test run does not delete those stamps.

---

# api/transcript.md

# Transcript

```ts
function isDemoTranscript(env: Record<string, string | undefined>): boolean
function isDemoTranscriptMarkdown(env: Record<string, string | undefined>): boolean
function demoPathFromUrl(url: string): string
function isSecretControl(control: string): boolean
function redactTranscriptValue(control: string, value: string): string
function formatWalkClock(atMs: number): string
function formatWalkTranscriptText(doc: DemoTranscriptDoc): string
function formatWalkTranscriptMarkdown(doc: DemoTranscriptDoc): string
function groupTranscriptChapters(events: readonly DemoTranscriptEvent[]): Array<{
  chapter: DemoTranscriptEvent;
  actions: DemoTranscriptEvent[];
}>
function demoChatTranscriptPath(
  env: Record<string, string | undefined>,
  artifactsDirAvailable: boolean,
  stamp: string,
): string | null
```

`formatWalkClock` exists for tooling. The default text handout does
**not** print clocks.

---

# api/walk.md

# runDemoWalk

```ts
function isE2eDemo(env?: Record<string, string | undefined>): boolean

function demoTimeout(fastMs: number, demoMs?: number): number
// demoMs default 900_000

function withDemoPages<P extends string>(
  fixtures: { browser: Browser; page: Page },
  personas: readonly P[],
  options?: { device?: DemoDevice },
): Promise<DemoWalk<P>>

function runDemoWalk<P extends string>(
  fixtures: { browser: Browser; page: Page },
  personas: readonly P[],
  body: (walk: DemoWalk<P>) => Promise<void>,
  options?: { device?: DemoDevice },
): Promise<void>

function resumeOnSharedPage(
  walk: { multi: boolean },
  fn: () => Promise<void>,
): Promise<void>
```

```ts
type DemoWalk<P extends string> = {
  page: Record<P, Page>;
  multi: boolean;
  close: () => Promise<void>;
};
```

`runDemoWalk` always `close()`s in a `finally` (transcript, optional
video).

`withDemoPages` throws if `personas` is empty. On the fast path it
installs the teaching cursor on the shared fixture page (hidden until
aimed), sizes the viewport to `options.device` (or `E2E_DEMO_DEVICE`),
and brands each `walk.page[id]` so `demoFocus` can update the HUD chip.
On the demo path it closes the fixture page and opens one context per
persona (overlay + cursor), then `goto(startPath)`.

`resumeOnSharedPage` runs `fn` only when `walk.multi` is false.

---

# guide/best-practices.md

# Best practices

A short checklist. The loop itself is [Stills](/guide/stills).

## One spec, two speeds

Do not keep a “CI walk” and a “demo walk.” `E2E_DEMO` changes chrome and
timing, not the story.

| Flag | Use when |
|---|---|
| unset | Writing the walk, CI, reviewing stills |
| `E2E_DEMO=1` | The stills already look good and you need `walk.mp4` |

## `shot` owns the teaching still

Pass `shot` on the click, fill, or `demoPoint` the video would click.
Capture is after the pointer and ring are on the control, before
the action. Rest-frame `demoScreenshot` hides the pointer. Leave `shot`
on the video run. Playwemo does not hold the ring or write a still
while `recordVideo` is on. On video the ring pulses, then the click,
then a short pause. Setup: [Stills](/guide/stills#stills-vs-video) and
[Video](/guide/recording#setup-so-the-recording-does-not-freeze).

## Keep assertions on

Never skip `expect` to make a recording prettier.

## Configure once

Import `configureDemoWalk` from `playwright.config.ts`. Init scripts
take arguments; they cannot close over Node state.

Set Playwright `outputDir` to `test-results/playwright` so stamps under
`test-results/e2e-demo/stills/` and `video/` survive each run.

## Accumulate stamps

Leave prior runs on disk. Compare stills across stamps.
`E2E_DEMO_CLEAN=1` only when you mean to wipe them.

## Do not minify overlay or cursor inits

`addInitScript(fn)` serializes function source. Minify breaks paint.

## Personas stay in the app

Ids are strings. Colors, selectors, and `/login` labels belong in the
consumer’s `configureDemoWalk`.

## Show the beat, do not describe it

In a Cursor Cloud thread, copy stills / `walk.mp4` into
`/opt/cursor/artifacts` and inline them. See [Cursor](/guide/cursor).

Agents: [For agents](/guide/for-agents).

---

# guide/configuration.md

# Configuration

`configureDemoWalk` merges into a process-wide object. Call it once at
startup. `resetDemoWalkConfig` is for unit tests.

## `personas`

Map of actor id → chip style.

```ts
type DemoPersonaStyle = {
  bg: string;
  fg: string;
  label?: string; // chip text; defaults to the persona id
};
```

Unknown personas use a slate fallback (`FALLBACK_PERSONA_STYLE`). Ids are
plain strings — this package does not know `ADMIN` or `PLAYER`. The
whole map is passed into the overlay init script so a shared-page
`demoFocus` can restyle the chip without closing over Node config.

## `layout`

Unused leftover fields. Older configs that still set them continue to merge.

| Field | Purpose |
|---|---|
| `main` | Unused. Kept so older configs still merge. |
| `stickyNavs` | Unused. Kept so older configs still merge. |

## `startPath`

First URL for each persona window when `E2E_DEMO=1`. Default `/`.

## `artifactsDir`

Folder used when copying `walk.mp4` / `transcript.txt` for chat or a PR.
Default `/opt/cursor/artifacts` (Cursor Cloud). On a laptop without that
directory, copies are skipped unless you set `E2E_DEMO_COPY_WALK`.

## `pacing`

Three teaching beats. Optional `pace` (`tight` · `normal` · `slow`)
scales all three. Explicit milliseconds win.

```ts
configureDemoWalk({
  pacing: { pace: 'slow', afterClickMs: 400 },
});
```

| Beat | Default | Per-call |
|---|---|---|
| Chapter sit (`demoFocus`) | 2200ms | `{ chapterMs }` |
| Click pulse | 450ms | `{ pulseMs }` on click / fill |
| After-click linger | 500ms video, 700ms headed stills | `{ afterClickMs }` |

`demoDwell(ms)` / `demoSee(ms)` / `{ waitAfter: false }` stay per-call
only. Pointer travel and stills pre-hold stay internal.

## Merge rules

Later calls **shallow-merge** `personas`, `layout`, and `pacing`.
`artifactsDir` and `startPath` replace only when provided.

---

# guide/cursor.md

# Cursor

Cursor Cloud Agents can put Playwemo stills and `walk.mp4` **in the
chat**, not only as file paths. The human reviews the beat the same way
they would open the storyboard folder.

This is the Cloud Agent path. Default `artifactsDir` is
`/opt/cursor/artifacts`. A laptop without that folder still writes
stamps under `test-results/e2e-demo/` — see [Stills](/guide/stills) and
[Video](/guide/recording).

## What Playwemo already copies

When `artifactsDir` exists:

| Artifact | When it lands there |
|---|---|
| `walk.mp4` | `E2E_DEMO=1` (unless `E2E_DEMO_VIDEO=0`) |
| `transcript.txt` | every `runDemoWalk` (unless `E2E_DEMO_TRANSCRIPT=0`) |
| teaching `shot` PNGs | stills run (`E2E_DEMO` unset) |

Fast-path stills stay in
`test-results/e2e-demo/stills/<stamp>/screenshots/`. Copy the ones you
mean to show. Video does not recapture them.

Override with `E2E_DEMO_COPY_WALK`, `E2E_DEMO_COPY_TRANSCRIPT`, or
`E2E_DEMO_SCREENSHOT_DIR`. See [Environment variables](/guide/environment).

## Show stills in the thread

1. Run the walk (`E2E_DEMO` unset).
2. Read `test-results/e2e-demo/stills/latest.txt`.
3. Copy the teaching PNGs into `/opt/cursor/artifacts/…`.
4. Put **HTML** in the reply. Absolute path. One beat per image.

```bash
stamp=$(cat test-results/e2e-demo/stills/latest.txt)
mkdir -p /opt/cursor/artifacts/walk-stills
cp "$stamp/screenshots/"*.png /opt/cursor/artifacts/walk-stills/
```

```html
<img alt="1 / 4 AUTHOR on writing-a-walk" src="/opt/cursor/artifacts/walk-stills/personas_desktop_01_author_stills.png" />
```

Caption with the step, persona, and route — the same facts as the
[transcript](/guide/transcripts). Do not describe the frame instead of
showing it. Reading a PNG with a file tool is for the model; the human
sees what you put in the reply.

Markdown `![](...)` is for this docs site. Cursor chat wants the
`<img>` tag.

## Show walk.mp4 in the thread

After a headed run, Playwemo copies the stitch when the artifacts
dir exists. Override the name with `E2E_DEMO_COPY_WALK`.

```html
<video src="/opt/cursor/artifacts/e2e_demo_walk_2026-08-22T08-08-43-623Z.mp4"></video>
```

The file is faststart (`moov` first) so the player can start. A copy
that is still writing will not play.

## Rules that bite

- Copy first, then tag. `test-results/` is for you; the chat embed uses
  `/opt/cursor/artifacts`.
- Pick the teaching shots. Do not dump every PNG.
- Keep `expect`s on. A pretty still that skipped an assertion is not a
  review.

Agents reading this site: start at [For agents](/guide/for-agents).

---

# guide/devices.md

# Devices and windows

Pass `{ device: 'desktop' | 'tablet' | 'mobile' }` to `runDemoWalk` /
`withDemoPages`. That sets the viewport and the overlay chip.
`E2E_DEMO_DEVICE` is the default when you omit it. Aliases: `phone` →
mobile, `ipad` → tablet.

```ts
await runDemoWalk({ browser, page }, ['ADMIN'], story, { device: 'mobile' });
```

`applyDemoViewport(page, device)` resizes an already-open page (the
docs walk does this so one spec covers all three).

| Mode | Viewport | `isMobile` / `hasTouch` |
|---|---|---|
| `desktop` (default) | 1920×1080 | no / no |
| `tablet` | 768×1024 | yes / yes |
| `mobile` | 390×844 | yes / yes |

This site’s walk at each preset:

![Desktop overlay](/examples/docs-walk/desktop_01_home_get_started.png)

![Tablet overlay](/examples/docs-walk/tablet_01_home_get_started.png)

![Mobile overlay](/examples/docs-walk/mobile_01_home_get_started.png)

Use `demoContextOptions(device)` when you open a context yourself. Do
not hardcode a viewport in a new demo context.

## Fullscreen

`demoFocus` → `presentDemoWindow` brings the persona forward. OS
fullscreen (CDP `Browser.setWindowBounds`) runs only when a real window
exists (`--headed` / `HEADED=1` / `E2E_DEMO_HEADED=1`).

Headless CDP fullscreen paints the page into a corner of the 1080p
video. Leave it off for recordings.

`E2E_DEMO_FULLSCREEN=0` keeps the OS window windowed even when headed.

## Leftover Chrome

`closeStrayBrowserWindows` closes leftover **Google Chrome** via
xdotool/wmctrl. It does **not** close Playwright Chromium.

---

# guide/environment.md

# Environment variables

| Variable | Default | Meaning |
|---|---|---|
| `E2E_DEMO` | unset | `1` / `true` — multi-window, pacing, video |
| `E2E_DEMO_OVERLAY` | on | `0` hides the bottom demo bar on stills and video |
| `E2E_DEMO_DEVICE` | `desktop` | One preset. Omit on stills to run desktop + tablet + mobile |
| `E2E_DEMO_FULLSCREEN` | on when `E2E_DEMO=1` | `0` windowed; `1` forces on |
| `E2E_DEMO_HEADED` | inferred from `--headed` / `HEADED` | OS fullscreen only when a window exists |
| `E2E_DEMO_VIDEO` | on when `E2E_DEMO=1` | `0` skips `recordVideo` |
| `E2E_DEMO_VIDEO_DIR` | `test-results/e2e-demo/<kind>/<stamp>` | Override output folder (`kind` is `stills` or `video`) |
| `E2E_DEMO_CLEAN` | unset | `1` / `true` — delete prior `test-results/e2e-demo` stamps before this run |
| `E2E_DEMO_COPY_WALK` | `<artifactsDir>/e2e_demo_walk_<stamp>.mp4` when that dir exists | Explicit walk copy path |
| `E2E_DEMO_COPY_TRANSCRIPT` | sibling `.txt` of the walk copy | Explicit transcript copy path |
| `E2E_DEMO_SCREENSHOT_DIR` | `artifactsDir` on `E2E_DEMO=1` | Folder for `demoScreenshot` copies |
| `DOCS_E2E_PORT` | `4177` | This repo only — VitePress preview port for `docs:e2e` |
| `E2E_DEMO_TRANSCRIPT` | on | `0` skips the handout |
| `E2E_DEMO_TRANSCRIPT_MD` | unset | `1` also writes `transcript.md` |

`isE2eDemo()`, `isDemoVideo(env)`, `isDemoTranscript(env)`, and
`isDemoClean(env)` read these flags. Pass `process.env` from Playwright
helpers. Teaching stills (`shot`) write when `E2E_DEMO` is unset (or
`E2E_DEMO_VIDEO=0`). Video (`E2E_DEMO=1`) does not hold the ring or
write a still. Pulse, then click, then a short pause. See
[Stills](/guide/stills) and [Video](/guide/recording).

---

# guide/examples.md

<script setup>
import { withBase } from 'vitepress';
const desktopWalk = withBase('/examples/docs-walk/desktop_walk.mp4');
const tabletWalk = withBase('/examples/docs-walk/tablet_walk.mp4');
const mobileWalk = withBase('/examples/docs-walk/mobile_walk.mp4');
const desktopPoster = withBase('/examples/docs-walk/desktop_01_home_get_started.png');
const tabletPoster = withBase('/examples/docs-walk/tablet_01_home_get_started.png');
const mobilePoster = withBase('/examples/docs-walk/mobile_01_home_get_started.png');
</script>

# Examples

This is the **real dogfood walk** of this site (`e2e/docs-walk.spec.ts`):
the same steps on **desktop, tablet, and mobile** — stills and one
video per viewport. See [Stills](/guide/stills) and [Devices](/guide/devices).

Pass `{ device: 'tablet' }` (or `mobile` / `desktop`) into
`runDemoWalk`. `E2E_DEMO_DEVICE` is the default when you omit it.
Stills and video run all three presets unless that env is set.

## Video

`E2E_DEMO=1`. Same walk, one file per viewport.

### Desktop · 1920×1080

<video controls playsinline preload="none" :poster="desktopPoster" :src="desktopWalk"></video>

### Tablet · 768×1024

<video controls playsinline preload="none" :poster="tabletPoster" :src="tabletWalk"></video>

### Mobile · 390×844

<video controls playsinline preload="none" :poster="mobilePoster" :src="mobileWalk"></video>

## Desktop · 1920×1080

Each PNG is a `shot`: pointer on the control, gold ring held, before
the click, with the demo bar. `E2E_DEMO_OVERLAY=0` hides the bar.

### Home → Get started

![Pointer on Get started](/examples/docs-walk/desktop_01_home_get_started.png)

### Search

![Pointer on Search](/examples/docs-walk/desktop_02_open_search.png)

![Typing overlay in search](/examples/docs-walk/desktop_03_type_search.png)

![Search results for overlay](/examples/docs-walk/desktop_04_search_results.png)

![Pointer on Overlay and cursor](/examples/docs-walk/desktop_05_search_result_overlay.png)

### Overlay page

![Pointer on the init-script heading](/examples/docs-walk/desktop_06_scroll_init_scripts.png)

### Guide sidebar

![Pointer on Stills](/examples/docs-walk/desktop_07_sidebar_stills.png)

![Pointer on Devices and windows](/examples/docs-walk/desktop_08_sidebar_devices.png)

### Top nav

![Pointer on Recipes](/examples/docs-walk/desktop_09_nav_recipes.png)

![Pointer on Maintainers](/examples/docs-walk/desktop_10_nav_maintainers.png)

![Pointer on Dogfood the docs site](/examples/docs-walk/desktop_10_sidebar_dogfood.png)

![Pointer on API](/examples/docs-walk/desktop_11_nav_api.png)

![Pointer on Pacing helpers](/examples/docs-walk/desktop_12_sidebar_pacing.png)

![Pointer on Guide](/examples/docs-walk/desktop_13_nav_guide.png)

![Pointer on Environment variables](/examples/docs-walk/desktop_14_sidebar_environment.png)

![Pointer on License](/examples/docs-walk/desktop_15_nav_license.png)

## Tablet · 768×1024

Same steps as desktop. Compact chrome opens Menu / hamburger first.

![Tablet — Get started](/examples/docs-walk/tablet_01_home_get_started.png)

![Tablet — Search](/examples/docs-walk/tablet_02_open_search.png)

![Tablet — Type search](/examples/docs-walk/tablet_03_type_search.png)

![Tablet — Search results](/examples/docs-walk/tablet_04_search_results.png)

![Tablet — Overlay result](/examples/docs-walk/tablet_05_search_result_overlay.png)

![Tablet — Init scripts](/examples/docs-walk/tablet_06_scroll_init_scripts.png)

![Tablet — Stills](/examples/docs-walk/tablet_07_sidebar_stills.png)

![Tablet — Devices](/examples/docs-walk/tablet_08_sidebar_devices.png)

![Tablet — Recipes](/examples/docs-walk/tablet_09_nav_recipes.png)

![Tablet — Maintainers](/examples/docs-walk/tablet_10_nav_maintainers.png)

![Tablet — Dogfood](/examples/docs-walk/tablet_10_sidebar_dogfood.png)

![Tablet — API](/examples/docs-walk/tablet_11_nav_api.png)

![Tablet — Pacing](/examples/docs-walk/tablet_12_sidebar_pacing.png)

![Tablet — Guide](/examples/docs-walk/tablet_13_nav_guide.png)

![Tablet — Environment](/examples/docs-walk/tablet_14_sidebar_environment.png)

![Tablet — License](/examples/docs-walk/tablet_15_nav_license.png)

## Mobile · 390×844

Same steps. Narrow HUD (8px inset, no note line).

![Mobile — Get started](/examples/docs-walk/mobile_01_home_get_started.png)

![Mobile — Search](/examples/docs-walk/mobile_02_open_search.png)

![Mobile — Type search](/examples/docs-walk/mobile_03_type_search.png)

![Mobile — Search results](/examples/docs-walk/mobile_04_search_results.png)

![Mobile — Overlay result](/examples/docs-walk/mobile_05_search_result_overlay.png)

![Mobile — Init scripts](/examples/docs-walk/mobile_06_scroll_init_scripts.png)

![Mobile — Stills](/examples/docs-walk/mobile_07_sidebar_stills.png)

![Mobile — Devices](/examples/docs-walk/mobile_08_sidebar_devices.png)

![Mobile — Recipes](/examples/docs-walk/mobile_09_nav_recipes.png)

![Mobile — Maintainers](/examples/docs-walk/mobile_10_nav_maintainers.png)

![Mobile — Dogfood](/examples/docs-walk/mobile_10_sidebar_dogfood.png)

![Mobile — API](/examples/docs-walk/mobile_11_nav_api.png)

![Mobile — Pacing](/examples/docs-walk/mobile_12_sidebar_pacing.png)

![Mobile — Guide](/examples/docs-walk/mobile_13_nav_guide.png)

![Mobile — Environment](/examples/docs-walk/mobile_14_sidebar_environment.png)

![Mobile — License](/examples/docs-walk/mobile_15_nav_license.png)

Plain-text handout from the stills run (desktop, tablet, and mobile):
[transcript.txt](/examples/docs-walk/transcript.txt).

---

# guide/for-agents.md

# For agents

The HTML site is for humans. The same pages ship as Markdown. Prefer
those URLs over scraping.

| URL | What it is |
|---|---|
| [`/llms.txt`](/llms.txt) | Index (title + `.md` link for every page) |
| [`/llms-full.txt`](/llms-full.txt) | All pages concatenated |
| `/guide/stills.md` | Example: any page path plus `.md` |

`Content-Type` is `text/markdown` or `text/plain`. `docs:dev`,
`docs:preview`, and the built site all serve them.

## Read in this order

1. [What this is](/guide/) — two speeds, what stays in the app
2. [Getting started](/guide/getting-started) — install + first `shot`
3. [Stills](/guide/stills) — storyboard loop (do this before video)
4. [Examples](/guide/examples) — this site’s own walk as PNGs
5. [Writing a walk](/guide/writing-a-walk) — lift recipe
6. [Cursor](/guide/cursor) — show stills and `walk.mp4` in the thread
7. [API overview](/api/) — exported names
8. [Environment variables](/guide/environment) — flags

Then open a single `.md` for the topic you are changing.

## Rules that bite

- One spec. `E2E_DEMO` does not fork the story. Keep `expect`s on.
- `shot` on the teaching click/fill/point — not a raw Playwright
  screenshot, not `demoScreenshot` after `demoFocus`. Keep `shot` on
  the video run; Playwemo does not hold the ring or write a still while
  `recordVideo` is on ([Video](/guide/recording)).
- Do not minify overlay or cursor inits (`addInitScript` serializes
  function source).
- Persona ids are strings. Product selectors live in the consumer’s
  `configureDemoWalk`.
- To show a still or `walk.mp4` in Cursor chat, copy it to
  `/opt/cursor/artifacts` and emit an `<img>` / `<video>` tag. See
  [Cursor](/guide/cursor).

GitHub raw also works if you have the repo, for example
`https://raw.githubusercontent.com/DragonMastery/playwemo/apex/docs/guide/stills.md`.

---

# guide/getting-started.md

# Getting started

## Install

```bash
npm install @dragonmastery/playwemo
npm install -D @playwright/test
```

Peer: `@playwright/test` `>=1.50.0`. This package does not bundle
Playwright. `ffmpeg` is optional and only needed to stitch `walk.mp4`.

## Configure once

Call `configureDemoWalk` before any overlay install. Import that module
from `playwright.config.ts` so every spec sees the same personas and
layout. Init scripts receive these values as **arguments** — they cannot
close over Node module state. See
[Playwright config](/recipes/playwright-config).

```ts
import { configureDemoWalk } from '@dragonmastery/playwemo';

configureDemoWalk({
  personas: {
    ADMIN: { bg: '#f59e0b', fg: '#111827' },
    ADVISOR: { bg: '#34d399', fg: '#022c22' },
  },
  layout: {
    main: '#main-content',
    stickyNavs: ['#nav-sidebar'],
  },
  startPath: '/login',
  pacing: { pace: 'normal' },
});
```

## First walk

```ts
import { demoClick, demoFocus, demoTimeout, runDemoWalk } from '@dragonmastery/playwemo';
import { test } from '@playwright/test';

test('owner signs in', async ({ browser, page }) => {
  test.setTimeout(demoTimeout(60_000));
  await runDemoWalk({ browser, page }, ['ADMIN'], async (walk) => {
    const admin = walk.page.ADMIN;
    await demoFocus(admin, '1 / 1', 'Sign in', 'On the login form');
    await demoClick(admin, admin.getByRole('button', { name: 'Sign in' }), {
      shot: 'sign_in',
    });
  }, { device: 'desktop' });
});
```

Leave `E2E_DEMO` unset. Open
`test-results/e2e-demo/stills/<stamp>/screenshots/sign_in.png`. That PNG
is the teaching beat (pointer + held ring). The run also writes
`transcript.txt`.

When that still looks right, run the **same spec** with `E2E_DEMO=1` for
overlay, pacing, and `walk.mp4`. Keep every `shot`. Playwemo does not
hold the ring or write those PNGs during video. See
[Video](/guide/recording).

Next: [Stills](/guide/stills), then [Writing a walk](/guide/writing-a-walk).
Agents: [For agents](/guide/for-agents) or [getting-started.md](/guide/getting-started.md).

---

# guide/index.md

# What this is

Playwemo is a **Node library** you drop into Playwright. The same spec
can stay a fast test and also become a followable walk: chapter banners,
a teaching cursor, paced typing, a click storyboard, an email-safe
transcript, and (when you ask for it) a stitched `walk.mp4`.

It is not a test runner and not a product fixture kit. Login buttons,
inbox locators, and persona *names* stay in your app.

## Two speeds

| You run | You get | When |
|---|---|---|
| Spec with `E2E_DEMO` unset | Teaching **stills** (pointer + held ring + demo bar) + `transcript.txt` | Writing the walk, CI |
| Same spec with `E2E_DEMO=1` | Paced cursor, optional `walk.mp4` (no mid-walk still) | After the stills look right |

Do not keep a “CI walk” and a “demo walk.” The flag changes chrome and
timing, not the story. Assertions stay on both paths.

## Where to go

1. [Getting started](/guide/getting-started) — install, configure, first `shot`
2. [Stills](/guide/stills) — the daily loop (storyboard PNGs)
3. [Examples](/guide/examples) — this site’s own walk, as stills
4. [Writing a walk](/guide/writing-a-walk) — `runDemoWalk`, chapters, fills
5. [Video](/guide/recording) — headed path, stitch, `walk.mp4`
6. [Cursor](/guide/cursor) — show stills and `walk.mp4` in a Cloud Agent thread

Agents: start at [llms.txt](/llms.txt) or [For agents](/guide/for-agents).
Do not scrape the HTML.

---

# guide/overlay-and-cursor.md

# Overlay and cursor

## Overlay

`installDemoOverlay(context, persona, device)` **before** `newPage()`.
The package already does this inside `runDemoWalk` / `withDemoPages`.

The banner is a **fixed HUD** — a rounded card inset from the bottom
and sides so the app shows around it. It does not wrap the consumer
app or rewrite `html` / `body` layout. Their `100vh`, `position:
fixed`, and modals keep the window as the containing block.

`padding-bottom` on `<html>` (and `scroll-padding-bottom` on `<body>`)
is the bar height so page copy can scroll out from under it.
`--e2e-demo-bar-height` and `data-e2e-demo-reserve` are that same
value.

The bar sits above page chrome (`z-index` just under the teaching
cursor). If it covers a control you need, set `E2E_DEMO_OVERLAY=0`.

Pass `{ device: 'desktop' | 'tablet' | 'mobile' }` to `runDemoWalk` so
the chip and viewport match. This site’s walk runs all three on stills.

The card shows:

- Persona chip (colors from config)
- Device chip (`DESKTOP` / `TABLET` / `MOBILE`)
- Chapter title and SPA route
- Current-action note (`demoAnnounce`)

Caption state lives in `sessionStorage` (`e2e.demo.caption`) so a
full-page navigation restores the last chapter. The persona chip is
`e2e.demo.persona` — `demoFocus` writes it from the bound
`walk.page[id]` so stills on the shared-page fast path keep the chip
in sync with the chapter. Isolated `E2E_DEMO=1` windows already have
one overlay per actor.

Test ids: `e2e-demo-overlay`, `e2e-demo-persona`, `e2e-demo-device`,
`e2e-demo-banner`, `e2e-demo-banner-title`, `e2e-demo-banner-route`,
`e2e-demo-banner-note`.

## Cursor

A SVG pointer (`e2e-demo-cursor`) is installed on every `runDemoWalk`,
including the fast CI path. It stays **hidden until aimed** at a
control (`demoClick`, `fillField`, `demoPoint`).

On stills, each teaching beat uses **one** gold ring
(`e2e-demo-cursor-ring`):

1. Aim the pointer
2. Hold the ring (storyboard `shot` captures here)
3. Release — fade that same ring when `E2E_DEMO=1` and video is off,
   snap-remove on CI
4. Click, type, or leave (`demoPoint` has no click)

On video the pulse plays **then** the click: pointer arrives, ring
scales out and fades, click lands when that pulse is done, then a
short pause. Video does not hold a static ring or take a still. Stills
freeze CSS so the storyboard is the held ring.

The overlay is **on by default** for stills and video. Set
`E2E_DEMO_OVERLAY=0` to hide the bar. `demoFocus` still writes the
chapter and the persona chip into the bar when it is shown; pacing
dwells stay on `E2E_DEMO=1` only.

## Why init scripts are not minified

Playwright calls `Function#toString()` and evals that source in the
page. The paint functions take a serializable args object only. Closing
over `getDemoWalkConfig()` would break after the lift into the browser.

---

# guide/recording.md

# Video

Record video **after** the [stills](/guide/stills) look right.
`E2E_DEMO=1` turns on Playwright `recordVideo` unless
`E2E_DEMO_VIDEO=0`. The docs walk records **desktop, tablet, and
mobile** unless `E2E_DEMO_DEVICE` picks one.

Output (relative to the Playwright cwd):

```
test-results/e2e-demo/stills/<stamp>/   # E2E_DEMO unset (or E2E_DEMO_VIDEO=0)
  screenshots/        # teaching stills from shot
test-results/e2e-demo/video/<stamp>/    # E2E_DEMO=1 with video on
  docs.webm           # headed path — one file per persona id (lowercased)
  walk.mp4            # headed path only — stitched focused chapters
  manifest.json
  transcript.txt
  transcript.json
test-results/e2e-demo/stills/latest.txt
test-results/e2e-demo/video/latest.txt
test-results/playwright/           # Playwright failure dumps only
```

The fast path writes a stamp (transcript + stills) and skips
`recordVideo`. Stamps accumulate. Playwright only cleans
`test-results/playwright`. Pass `E2E_DEMO_CLEAN=1` to wipe prior walks.

`--headed` is for live watching. The file is the page (overlay, cursor,
viewport), headed or headless.

## Setup so the recording does not freeze

Same walk as stills. `shot` stays on the teaching clicks. Playwemo does
**not** hold the ring, write a still, or call `page.screenshot()` while
the camera is rolling. Holding for a storyboard pose freezes the
picture. Teaching PNGs come from the stills run.

1. Iterate with `E2E_DEMO` **unset** until the PNGs look right.
2. Record with `E2E_DEMO=1` (and `E2E_DEMO_VIDEO=0` only if you want
   pacing without a camera).
3. Do not drop `shot` for the video run. Do not take a raw Playwright
   screenshot while the camera is rolling.

The gold ring pulses, then the click lands when that pulse is done,
then a short pause. There is no held-ring beat on film. Stills CI
still freezes CSS so the storyboard PNG is the held ring.

Stills and video are **two runs**. The storyboard pose (held ring,
before the click) is not in `walk.mp4`.

## Stitch

`ffmpeg` cuts each chapter from that persona’s webm (`-ss` after `-i`
so WebM keyframe-seek does not land on standby), pads to an even
viewport, and concats to `walk.mp4`. Without ffmpeg, persona webms still
land; stitch logs a warning and skips `walk.mp4`.

## Chat / PR copy

When `artifactsDir` exists (default `/opt/cursor/artifacts`),
`runDemoWalk` copies `walk.mp4` there. Override with
`E2E_DEMO_COPY_WALK=/absolute/path.mp4`.

A Cursor Cloud Agent can put that file (and the stills) **in the
thread**. See [Cursor](/guide/cursor).

---

# guide/stills.md

# Stills

Stills are the **click storyboard**. Every teaching beat is a PNG of the
pointer on the control, with the gold ring held, **before** the click
or keystroke. The bottom demo bar (step, title, route) is on by default
so the still matches what the video teaches. `E2E_DEMO_OVERLAY=0` hides
the bar.

Video is the same spec with a camera. It is minutes. Stills are seconds.
Iterate here first. See [Best practices](/guide/best-practices).

This site’s own walk is published as a gallery:
[Examples](/guide/examples). That is what the PNGs look like.

![Pointer on Get started — from the docs walk](/examples/docs-walk/desktop_01_home_get_started.png)

## How a still is taken

Pass `shot` on the helper that *is* the teaching beat:
`demoClick`, `demoClickAndWaitUrl`, `fillField` / `fillShown`, or
`demoPoint`.

1. Aim the pointer (hidden until then)
2. Hold one gold ring
3. Write `<slug>.png` on the stills path (CSS frozen). Video skips
   this capture so the camera does not freeze on a still-pose
4. Release the ring, then click / type / leave — on video there is no
   hold: the ring pulses fully, then the click lands, then a short
   pause so the beat can register

Do not `demoScreenshot` after `demoFocus` and hope the cursor is already
on the next button. That is a rest frame (page, no pointer). Use
`demoScreenshot` without `shot` only for “the page after typing.”

```ts
await demoClick(admin, admin.getByRole('button', { name: 'Sign in' }), {
  shot: 'sign_in',
});
```

The slug becomes `sign_in.png`. Keep names stable (`01_…` if you want
sort order).

## Where they land

```
test-results/e2e-demo/stills/<stamp>/screenshots/
test-results/e2e-demo/stills/latest.txt
```

A headed video run does **not** rewrite those PNGs. The film path does
not hold the ring or write a still — that pose is what froze the
picture. Stills stay under `stills/<stamp>/`. Video writes `walk.mp4`.

Playwright’s `outputDir` must be `test-results/playwright` so a test run
does not delete these folders. See [Playwright config](/recipes/playwright-config).

## How to review

Open `stills/latest.txt`, then that stamp’s `screenshots/`. Check:

- Pointer is on the control you meant
- One ring, not two
- Banner/chapter (headed path) matches the beat
- Persona chip matches the actor for that beat, not an earlier chapter
- You did not capture a blank pre-hydration frame

In this repo: `bun run docs:e2e` writes stills;
`bun run docs:e2e:demo` adds video. In your app, leave `E2E_DEMO` unset
for stills and set it only when the storyboard is right.

## Stills vs video

One spec. Keep `shot` on both speeds. Do not fork a “film walk” or
strip `shot` to make the cut smoother.

| You want | Flag | Capture |
|---|---|---|
| Storyboard PNGs | `E2E_DEMO` unset | Freeze CSS (`animations: "disabled"`) so the PNG is the held ring |
| `walk.mp4` | `E2E_DEMO=1` | No hold, no still. Pulse, then click, then a short pause. PNGs come from the stills run |

Do not call Playwright `page.screenshot` yourself while `recordVideo`
is on. Keep `shot` on the spec; Playwemo ignores the file write on
video. [Video](/guide/recording) is the film path.

To show the storyboard in a Cursor Cloud thread, see
[Cursor](/guide/cursor).

Next: [Writing a walk](/guide/writing-a-walk), then
[Video](/guide/recording).

---

# guide/transcripts.md

# Transcripts

Every `runDemoWalk` writes `transcript.txt` unless
`E2E_DEMO_TRANSCRIPT=0`. That includes the **fast** path — regenerate
the handout without replaying the paced demo. The file lives in the
same timestamped folder as the storyboard stills
(`test-results/e2e-demo/stills/<stamp>/` or `video/<stamp>/`).

The handout is email-safe: no markdown, **no wall-clock**. Stitch drops
setup and concatenates focused cuts, so Playwright elapsed time is not a
`walk.mp4` seek. Cite the step number, the route, and the control.

```
1 / 10 - Owner signs in
ADMIN
/login
    Typed Email: owner@example.com
    Clicked Sign in
```

`E2E_DEMO_TRANSCRIPT_MD=1` also writes `transcript.md`.

Password and card-like fields are redacted (`(hidden)`).

JSON sits beside the text file as `transcript.json` for tooling.

---

# guide/writing-a-walk.md

# Writing a walk

Prefer one lift call. Do not copy multi-window boilerplate into a spec.

```ts
test('advisor sees the new player', async ({ browser, page }) => {
  test.setTimeout(demoTimeout(180_000));
  await runDemoWalk({ browser, page }, ['ADMIN', 'ADVISOR'], async (walk) => {
    const admin = walk.page.ADMIN;
    const advisor = walk.page.ADVISOR;

    await demoFocus(admin, '1 / 3', 'Admin signs in', 'On the sign-in form');
    await demoClick(admin, admin.getByRole('button', { name: 'Sign in' }), {
      shot: 'admin_sign_in',
    });
    // login + product helpers

    await demoFocus(advisor, '3 / 3', 'Advisor first login', 'On the sign-in form');
  });
});
```

## Recipe

1. **`runDemoWalk({ browser, page }, personas, story, { device })`** —
   one shared page when `E2E_DEMO` is unset; N isolated contexts when
   on. `device` is `desktop` · `tablet` · `mobile` (or
   `E2E_DEMO_DEVICE`). Pass only the personas the story needs.
2. **Chapter = window comes forward.** `demoFocus(walk.page.ADVISOR, '2 / 5', title, note)`
   at every persona switch. That updates the HUD chip on the shared-page
   stills path too. Number chapters consecutively.
3. **Current action.** `demoAnnounce(page, 'Submitting')` before a goto
   or click that should show in the banner.
4. **Pace visible fields.** `fillField` / `fillTypedValue` / `fillShown`
   / `demoClick`. Product form helpers should call these.
5. **Storyboard stills.** Pass `shot` on the teaching click, fill, or
   `demoPoint` so CI captures the same beat the video clicks on
   (pointer + one held ring). Video does not recapture that PNG and
   does not hold the ring. The ring pulses, then the click, then a
   short pause.
   Rest-frame `demoScreenshot` hides the pointer on stills only. Do not
   screenshot after `demoFocus` and hope the cursor is already on the
   next control. Iterate on [stills](/guide/stills) before you pay for
   video (`E2E_DEMO=1`). See [Best practices](/guide/best-practices).
6. **Shared-page re-auth.** After a logout on the fast path,
   `resumeOnSharedPage(walk, () => loginAs(...))`.

`demoTimeout(fastMs)` is 15 minutes on the demo path (override the
second argument if needed).

## What stays in your app

Login labels, inbox readers, and domain form helpers. This package does
not know your `/login` button names unless you write that helper.

---

# index.md

---
layout: home
hero:
  name: Playwemo
  text: Watchable Playwright walks
  tagline: Same spec, two speeds. Review stills in seconds. Record walk.mp4 only when the storyboard is right.
  actions:
    - theme: brand
      text: Get started
      link: /guide/getting-started
    - theme: alt
      text: See the stills
      link: /guide/examples
features:
  - title: Same spec, two speeds
    details: Leave E2E_DEMO unset for a click storyboard (pointer + held ring). Set E2E_DEMO=1 for overlay, pacing, and walk.mp4. Assertions stay on.
  - title: Product-agnostic chrome
    details: Personas are strings. Colors, layout selectors, and the first URL come from configureDemoWalk.
  - title: Overlay that survives navigation
    details: Init scripts paint the banner and cursor on every document. Playwright serializes the functions — we never minify them.
  - title: Transcript + video
    details: transcript.txt on every runDemoWalk. Optional per-persona webms stitched to walk.mp4 with ffmpeg. Iterate on stills first; record the video last.
  - title: Markdown for agents
    details: Fetch /llms.txt or any page plus .md (for example /guide/stills.md). Do not scrape the HTML. Cloud Agents can inline stills and walk.mp4 in the thread. See For agents and Cursor.
---

---

# license.md

# License

Playwemo is released under the [MIT License](https://opensource.org/licenses/MIT).

Copyright © 2026 Dragon Mastery.

---

# maintainers/contributing.md

# Contributing

See `CONTRIBUTING.md` at the repo root for the full command table.

| Command | What it does |
|---|---|
| `bun run check` | Library typecheck + tests |
| `bun run docs:dev` | VitePress on port 5173 |
| `bun run docs:e2e` | Fast dogfood storyboard |
| `bun run docs:e2e:demo` | Overlay + stills + `walk.mp4` |

The library uses **tsdown** with `minify: false`. Playwright
`addInitScript(fn)` serializes function source. Overlay and cursor inits
must stay self-contained. `@playwright/test` is a peer.

After an API change, update the matching page under [API](/api/) in the
same PR. Site stills come from `shot` in `e2e/docs-walk.spec.ts` — see
[Dogfood](/maintainers/dogfood).

License: [MIT](/license) — Copyright © 2026 Dragon Mastery.

---

# maintainers/dogfood.md

# Dogfood the docs site

This repo’s VitePress site is a **consumer** of the package. There is
**one spec** (`e2e/docs-walk.spec.ts`) with a test per device. Stills
run the same walk on desktop, tablet, and mobile unless
`E2E_DEMO_DEVICE` is set. Video does the same three walks.
Compact layouts open Menu / hamburger first.
The flag picks the artifact:

| Command | Flag | Output |
|---|---|---|
| `bun run docs:e2e` | unset | Storyboard PNGs + transcript |
| `bun run docs:e2e:demo` | `E2E_DEMO=1` | Overlay + pacing + `walk.mp4` (no mid-walk stills) |
| `bun run docs:e2e:clean` | `E2E_DEMO_CLEAN=1` | Wipe prior stamps, then stills |
| `bun run docs:e2e:demo:clean` | both | Wipe prior stamps, then video |

Do not use a raw `playwright screenshot` against a static file server.
A static capture of the built HTML often lands before Vue hydrates
(blank white PNG) and never paints the overlay or cursor.

## Run the walk

From this repo root, after `bun install`:

```bash
# Fast: click storyboard (pointer + ring), no overlay / video
bun run docs:e2e

# Headed chrome: overlay, cursor, stitched walk.mp4
E2E_DEMO_COPY_WALK=/opt/cursor/artifacts/e2e_demo_vitepress_docs.mp4 \
  bun run docs:e2e:demo
```

`docs:e2e` builds the library and the site, then Playwright previews
`workers/docs/dist` on `127.0.0.1:4177`. Prior timestamped walks
stay under `test-results/e2e-demo/stills/<stamp>/` or
`video/<stamp>/`. Playwright only cleans
`test-results/playwright`.

Publish the latest stills (and `walk.mp4` when a video stamp exists)
into the docs site:

```bash
bun run docs:e2e
bun run docs:e2e:demo   # headed walk.mp4
bun run docs:examples
```

That writes `docs/public/examples/docs-walk/` (PNGs + per-device
`*_walk.mp4` + transcript). Deploy Docs refreshes stills from the CI
walk. It does not record video, so it keeps the last committed
`desktop_walk.mp4` / `tablet_walk.mp4` / `mobile_walk.mp4` unless a
video stamp is present to replace them.
Commit the folder when shots or the video change.

On `E2E_DEMO=1`, teaching `shot`s do not copy stills into `artifactsDir`
(the film path skips the file). Override stills copies with
`E2E_DEMO_SCREENSHOT_DIR` on the stills run.

## Spec

One `DOCS` persona. Teaching beats
(search, type, scroll, sidebar, top nav) pass `shot` so CI captures the
same click the video would. Use stills while developing; run
the video only after they look right. Video does not recapture those
PNGs. See
[Stills](/guide/stills) and [Best practices](/guide/best-practices). Typical stills:

- Open search, type `overlay`, pick Overlay and cursor
- Scroll to “Why init scripts are not minified”
- Sidebar and nav through Stills, Devices, Recipes, Maintainers, API, License

## Do not

- Point `playwright screenshot` at `docs:dev` without waiting for the
  app to hydrate.
- Serve the dist with a raw file server and treat that as a walk.
- Treat `bun run test` as the docs walk — that script is library Vitest.

---

# maintainers/index.md

# Maintainers

This section is for people who work **in the Playwemo repo**. It is not
part of the consumer guide.

Consumers of `@dragonmastery/playwemo` should stay in
[Guide](/guide/getting-started), [API](/api/), and
[Recipes](/recipes/playwright-config).

| Page | When you need it |
|---|---|
| [Contributing](/maintainers/contributing) | Commands, library rules, docs edits |
| [Dogfood](/maintainers/dogfood) | The VitePress walk that exercises this site |
| [Publish](/maintainers/publish) | npm, Cloudflare, GitHub Actions |

Operator checklists that should not live in VitePress stay in
`.maintainers/` at the repo root (Cloudflare token, first Tamer apply).

---

# maintainers/publish.md

# Publish

How this repo ships the library and the docs site.

## npm

`.github/workflows/publish-npm.yaml` runs on `apex`. It publishes
`@dragonmastery/playwemo` from `packages/playwemo` when that
`package.json` version is newer than npm. Auth is npm trusted publishing
(OIDC) — workflow filename must be `publish-npm.yaml`.

The docs nav version badge is read from the same `package.json` at
docs build time. Bumping the version also triggers a docs deploy.

## Docs site

`.github/workflows/deploy-docs.yml` runs the same checks as PR CI, then
`tamer apply` / `tamer deploy` to Cloudflare.

| Env | URL |
|---|---|
| `prod` | https://playwemo.dragonmastery.com |
| `dev` | https://dev.playwemo.dragonmastery.com |

First-time Cloudflare / token checklist:
`.maintainers/docs-site.md` in the repo (not duplicated here).

```bash
bun run tamer -- apply --env prod
bun run tamer -- deploy --env prod
```

## PR CI

`.github/workflows/ci.yml` is pull requests only: `bun run check` and
`bun run docs:e2e`. Headed video (`docs:e2e:demo`) is local — see
[Dogfood](/maintainers/dogfood).

---

# recipes/ci.md

# CI and artifacts

Leave `E2E_DEMO` unset in GitHub Actions. Specs stay fast. The same walk
writes a **click storyboard** (`shot` on teaching clicks: pointer + held
ring) instead of `walk.mp4`. Transcripts still write unless
`E2E_DEMO_TRANSCRIPT=0`. Record video locally (`E2E_DEMO=1`); do not
strip `shot` or call `page.screenshot` in that run. See
[Video](/guide/recording).

Do not skip assertions to make a recording prettier.

## Where files land

| Path | Who writes it | Cleared when |
|---|---|---|
| `test-results/e2e-demo/stills/<stamp>/` | Playwemo storyboard (stills + transcript) | Only if `E2E_DEMO_CLEAN=1` |
| `test-results/e2e-demo/video/<stamp>/` | Playwemo headed walk (transcript + `walk.mp4`) | Only if `E2E_DEMO_CLEAN=1` |
| `test-results/e2e-demo/stills/latest.txt` | Playwemo | Rewritten each stills run |
| `test-results/e2e-demo/video/latest.txt` | Playwemo | Rewritten each video run |
| `test-results/playwright/` | Playwright failure dumps | Every Playwright run |

`test-results/` is usually gitignored. Keep stamps so you can compare
runs. Wipe them with `E2E_DEMO_CLEAN=1` or `bun run docs:e2e:clean`.

## Sharing a walk

To show a recording in Cursor chat or a PR, copy `walk.mp4` into a
published artifacts directory. Cloud Agents then inline the file — see
[Cursor](/guide/cursor).

Default: `/opt/cursor/artifacts` when that folder exists. Override:

```bash
E2E_DEMO=1 E2E_DEMO_COPY_WALK=/opt/cursor/artifacts/my_walk.mp4 \
  bunx playwright test e2e/my-walk.spec.ts
```

The transcript copy is the same basename with `.txt`.

Headed overlay video is a local command (`E2E_DEMO=1`), not the default
CI job.

---

# recipes/multi-persona.md

# Multi-persona walks

Pass only the actors you need:

```ts
await runDemoWalk({ browser, page }, ['ADMIN', 'PLAYER'], async (walk) => {
  await demoFocus(walk.page.ADMIN, '1 / 2', 'Create the player');
  await demoFocus(walk.page.PLAYER, '2 / 2', 'First login');
});
```

On `E2E_DEMO=1` each key is an isolated browser context (own cookies).
The admin can stay signed in to read mail while the player uses another
window.

On the fast path every key is the **same** browser page, branded with
that persona. `demoFocus(walk.page.PLAYER, …)` updates the HUD chip and
the transcript actor. Pass `walk.page[id]`, not the fixture `page`, so
the chip does not stay on the lead persona after the chapter title and
route have already moved.

Logout still requires `resumeOnSharedPage` before the next privileged
action.

Persona video files are `<id>.webm` in lowercase (`admin.webm`), only
when `E2E_DEMO=1` (unless `E2E_DEMO_VIDEO=0`). Teaching `shot`s still
write on the shared-page fast path.

This repo dogfoods the shared-page chip in
`e2e/multi-persona-walk.spec.ts` (`AUTHOR` → `REVIEWER` → `READER`).

---

# recipes/playwright-config.md

# Playwright config

Import your `configureDemoWalk` module from `playwright.config.ts` so
every spec — including ones that import overlay helpers directly — sees
personas and layout.

```ts
// playwright.config.ts
import { defineConfig } from '@playwright/test';
import './e2e/demo-walk-config';

export default defineConfig({
  testDir: './e2e',
  // Keep Playwemo stamps; only this folder is wiped each run.
  outputDir: 'test-results/playwright',
  use: { baseURL: 'http://localhost:5173' },
});
```

```ts
// e2e/demo-walk-config.ts
import { configureDemoWalk } from '@dragonmastery/playwemo';

configureDemoWalk({
  personas: { ADMIN: { bg: '#f59e0b', fg: '#111827' } },
  startPath: '/login',
});
```

The library must be **built** (`dist/index.mjs`) before Playwright
resolves the package. In a bun/turbo monorepo, `dependsOn: ["^build"]`
covers that. Locally: `bun run build` in this repo, or the package’s
`tsdown` script.