@sightmap/playwright

Sightmap-aware wrapper around @playwright/cli. Adds sightmap-aware commands (snapshot, match, act, network) that consume your .sightmap/ corpus and enrich the agent-facing output with component names, view memory, and request annotations. Other commands pass through to @playwright/cli unchanged.

This is the no-MCP path: a coding agent invokes sightmap-playwright the same way it would invoke playwright, with no MCP protocol overhead.

Install

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

@playwright/cli is a peer dependency. sightmap-playwright shells out to it for the browser primitives.

Usage

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

Global flags:

-s, --session NAME      Named playwright-cli session (default: "default")
--sightmap-dir DIR      Path to .sightmap/ directory (default: ".sightmap")
--json                  Emit JSON instead of human-readable text

Sightmap-specific commands

snapshot — enriched a11y snapshot

Captures an ARIA snapshot from the current page and annotates the a11y tree itself: every node that matches a sightmap component gets an inline [sightmap=Name] token, placed right after the engine's [ref=eN] token. A header still lists the matched view, view memory, and components (with live matchCount) as an index.

The annotation is purely additive:

• The engine's native [ref=eN] tokens are preserved verbatim — the agent's click/navigation and sightmap-bootstrap paths are untouched.
• Unmatched nodes are byte-identical to the un-enriched tool, so a page with zero sightmap coverage looks exactly as before.
• Multiple component matches on one node are comma-joined ([sightmap=PrimaryCTA,Checkout.SubmitButton]); view-scoped components are slash-qualified ([sightmap=Checkout/PaymentForm]).

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

--- ARIA snapshot ---
- main [ref=e1]:
  - heading "Results for 'sightmap'" [level=1] [ref=e2]
  - searchbox "Search" [ref=e3] [sightmap=SearchBar]
  - listitem [ref=e7] [sightmap=ResultCard]:
    - link "First result" [ref=e8]

Annotation requires a Chromium-backed session; non-Chromium engines (no CDP) degrade gracefully to the un-annotated tree. Pass --json to get the structured EnrichedSnapshot (now including enrichedAriaText) plus the raw ARIA text under ariaSnapshot for back-compat.

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.

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

No browser is launched; this is the same matcher used by @sightmap/sightmap exposed 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 a sightmap-specific command is forwarded to @playwright/cli verbatim, preserving the session flag:

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

This means you can use sightmap-playwright as a drop-in for playwright and only opt into the sightmap-aware behavior on the four commands above.

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.

.sightmap/ resolution

Sightmap files are loaded per invocation from --sightmap-dir (default .sightmap), resolved against the current working directory. Override it if you're invoking from outside the project root:

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

There is no daemon and no cache — each command re-reads the corpus, so edits to .sightmap/ are picked up immediately.

See also

• @sightmap/sightmap — the underlying matcher, lint, and validate library. Same semantics, no browser.
• @sightmap/mcp — the MCP-server alternative if your host agent speaks MCP.
• sightmap.org — spec and full docs.

License

MIT.