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:

# 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:

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 shots 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 and 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.