@sightmap/playwright

@sightmap/playwright is a sightmap-aware wrapper around @playwright/cli. It adds four sightmap-aware commands (snapshot, match, act, network) that read your .sightmap/ corpus and enrich the agent-facing output with component names, view memory, and request annotations. Every other command passes through to @playwright/cli unchanged.

This is the shell-invocation path: a coding agent invokes sightmap-playwright the same way it would invoke playwright, with no MCP protocol overhead. Same enriched snapshots as @sightmap/mcp, different protocol surface. The wrapper covers browser-driving and snapshot enrichment only — for the curation tool family (proposal workflow, view CRUD), use @sightmap/mcp alongside it or fall back to hand-edits and the sightmap CLI.

Install

pnpm add -D @sightmap/playwright @playwright/cli

@playwright/cli is a peer dependency. sightmap-playwright shells out to it for browser primitives, so it has to be on PATH (or installed in the same node_modules).

Usage

sightmap-playwright [global flags] <command> [args...]

Global flags

Flag	Purpose
-s, --session NAME	Named playwright-cli session. Default "default".
--sightmap-dir DIR	Directory of sightmap YAML files. Default .sightmap.
--json	Emit JSON instead of human-readable text.

The .sightmap/ directory is loaded per invocation from --sightmap-dir, resolved against the current working directory. There is no daemon and no cache — every command re-reads the corpus, so edits to .sightmap/ are picked up immediately. Override --sightmap-dir when invoking from outside the project root:

sightmap-playwright --sightmap-dir /path/to/repo/.sightmap snapshot

Sightmap-specific commands

Four commands consume .sightmap/ and produce enriched output. Everything else falls through to @playwright/cli.

snapshot — enriched a11y snapshot

Captures an ARIA snapshot from the current page and annotates it with the matched sightmap view, view memory, and the sightmap components present on the page (with live matchCount).

$ sightmap-playwright snapshot
View: SearchResults (route /search)
  memory:
    - paginated; load-more button at bottom
Components:
  - SearchBar (global) — 1 match
  - ResultCard (view) — 12 matches
      memory: clicking opens detail in a new tab

--- ARIA snapshot ---
- main:
  - heading "Results for 'sightmap'" [level=1]
  ...

Pass --json for the structured EnrichedSnapshot plus the raw ARIA text.

match URL — show the matching sightmap view

Pure query: resolves a URL (or pathname) against the loaded sightmap and prints the matched view, applicable components, and known requests. No browser is launched.

$ sightmap-playwright match /list/abc123
View: ListDetailScreen (route /list/*)
  memory: id is opaque; do not parse
Components:
  - BottomTabBar (global)
  - ListCard (view)
Requests:
  - GET /api/list/:id → fetchList

This is the same matcher @sightmap/sightmap exposes, surfaced through the playwright-cli wrapper for convenience.

act NAME — resolve a component name to a selector

Resolves a sightmap component name to its primary selector (plus any fallbacks). Prints the selector to stdout so it can be piped into another playwright-cli command.

$ sightmap-playwright act SubmitButton
[data-testid="submit"]
# fallbacks: button[type="submit"]

Exits non-zero if the component name is unknown. Pass --json for the full resolution result.

network — annotated network requests

Pulls recent network requests from the current session and tags any that match a requests: entry in the sightmap, attaching request memory.

$ sightmap-playwright network
[GET] https://example.test/api/list/abc → 200  [fetchList]
    memory: returns 404 for archived lists; treat as "not found"
[POST] https://example.test/api/track → 204

Passthrough

Anything that isn’t one of the four sightmap-specific commands is forwarded to @playwright/cli verbatim, preserving the session flag:

sightmap-playwright open https://example.test
sightmap-playwright close

The upshot: sightmap-playwright is a drop-in for playwright. You only opt into the sightmap-aware behavior on the four commands above; everything else still works exactly as @playwright/cli documents it.

Sessions

@playwright/cli uses named sessions to keep a browser context alive across invocations. sightmap-playwright honors the same flag:

sightmap-playwright -s checkout open https://shop.test
sightmap-playwright -s checkout snapshot
sightmap-playwright -s checkout network
sightmap-playwright -s checkout close

If you don’t pass -s/--session, the session is "default". Run parallel flows by giving them distinct session names.

vs. @sightmap/mcp

Both packages produce the same enriched snapshots and component-name acts on top of a Playwright-driven browser. The difference is protocol surface and tool scope:

	@sightmap/playwright	@sightmap/mcp
Protocol	shell invocation	MCP (stdio)
Best for	CLI-driven agents, scripts, CI	MCP-capable hosts (Claude Code, Cursor, Codex, OpenCode)
Browser backend	@playwright/cli	@playwright/mcp
Curation tools	no — enrichment only	yes — proposal workflow + view CRUD (sightmap_propose_*, sightmap_add_view, sightmap_update_view, sightmap_delete_view, …)
Runtime snapshots	n/a (drives the browser directly)	sightmap_runtime_snapshot — endpoint, browser, or literal mode
Passthrough	full @playwright/cli surface	full @playwright/mcp surface

The choice is really about agent harness:

• MCP-capable agent — prefer @sightmap/mcp. It bundles the curation tool family on top of the same enriched browser primitives, and v0.9’s browser-mode sightmap_runtime_snapshot means MCP is no longer Vite-bound.
• Shell-invocation agent (CLI scripts, CI, custom harness) — @sightmap/playwright gives you the enriched commands without the MCP protocol overhead. You curate .sightmap/ separately (hand-edits, the sightmap CLI, or a side-car MCP server).

See also

• @sightmap/mcp — the MCP-server alternative with the curation tool family.
• @sightmap/core — the underlying matcher, lint, and validate library. Same semantics, no browser.