@sightmap/playwright 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fullstory, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,159 @@
+# @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
+
+```sh
+pnpm add -D @sightmap/playwright @playwright/cli
+```
+
+`@playwright/cli` is a peer dependency. `sightmap-playwright` shells out
+to it for the browser primitives.
+
+## Usage
+
+```sh
+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 it with
+the matched sightmap view, view memory, and the sightmap components
+present on the page (with live `matchCount`).
+
+```text
+$ 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:
+  - heading "Results for 'sightmap'" [level=1]
+  ...
+```
+
+Pass `--json` to get the structured `EnrichedSnapshot` plus 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.
+
+```text
+$ 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.
+
+```text
+$ 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.
+
+```text
+$ 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:
+
+```sh
+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:
+
+```sh
+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:
+
+```sh
+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`](../sightmap) — the underlying matcher, lint, and
+  validate library. Same semantics, no browser.
+- [`@sightmap/mcp`](../mcp) — the MCP-server alternative if your host
+  agent speaks MCP.
+- [sightmap.org](https://sightmap.org) — spec and full docs.
+
+## License
+
+MIT.

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.js

@@ -0,0 +1,437 @@
+#!/usr/bin/env node
+
+// src/commands/act.ts
+import {
+  loadDirectory,
+  resolveSightmapAct
+} from "@sightmap/sightmap";
+async function runActCommand(opts) {
+  const sightmap = await loadDirectory(opts.sightmapDir);
+  const r = resolveSightmapAct(sightmap, { componentName: opts.componentName });
+  if (r.kind === "error") {
+    process.stderr.write(r.message + "\n");
+    process.exit(1);
+    return;
+  }
+  if (opts.json) {
+    process.stdout.write(JSON.stringify(r, null, 2) + "\n");
+    return;
+  }
+  process.stdout.write(`${r.selector}
+`);
+  if (r.allSelectors.length > 1) {
+    process.stdout.write(`# fallbacks: ${r.allSelectors.slice(1).join(", ")}
+`);
+  }
+}
+
+// src/commands/match.ts
+import { loadDirectory as loadDirectory2, match } from "@sightmap/sightmap";
+async function runMatchCommand(opts) {
+  const sightmap = await loadDirectory2(opts.sightmapDir);
+  const result = match(sightmap, { url: opts.url });
+  if (opts.json) {
+    process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+    return;
+  }
+  const lines = [];
+  if (result.view) {
+    lines.push(`View: ${result.view.name} (${result.view.route})`);
+    for (const m of result.view.memory ?? []) lines.push(`  memory: ${m}`);
+  } else {
+    lines.push(`View: (no match)`);
+  }
+  if (result.components.length > 0) {
+    lines.push(`Components:`);
+    for (const c of result.components) {
+      lines.push(`  - ${c.name} (${c.scope})`);
+    }
+  }
+  if (result.requests.length > 0) {
+    lines.push(`Requests:`);
+    for (const r of result.requests) {
+      lines.push(`  - ${r.method ?? "ANY"} ${r.route} \u2192 ${r.name}`);
+    }
+  }
+  process.stdout.write(lines.join("\n") + "\n");
+}
+
+// src/commands/network.ts
+import {
+  loadDirectory as loadDirectory3,
+  annotateNetworkRequests
+} from "@sightmap/sightmap";
+
+// src/exec.ts
+import { spawn } from "child_process";
+async function execPlaywrightCli(args, options = {}) {
+  const binary = options.binary ?? "playwright-cli";
+  const timeoutMs = options.timeoutMs ?? 6e4;
+  return await new Promise((resolve, reject) => {
+    const child = spawn(binary, args, {
+      cwd: options.cwd ?? process.cwd(),
+      env: options.env ?? process.env,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    const stdoutChunks = [];
+    const stderrChunks = [];
+    child.stdout.on("data", (c) => stdoutChunks.push(c));
+    child.stderr.on("data", (c) => stderrChunks.push(c));
+    const killTimer = setTimeout(() => {
+      child.kill("SIGTERM");
+    }, timeoutMs);
+    child.on("error", (err) => {
+      clearTimeout(killTimer);
+      reject(err);
+    });
+    child.on("close", (code) => {
+      clearTimeout(killTimer);
+      resolve({
+        exitCode: code ?? -1,
+        stdout: Buffer.concat(stdoutChunks).toString("utf8"),
+        stderr: Buffer.concat(stderrChunks).toString("utf8")
+      });
+    });
+  });
+}
+async function streamPlaywrightCli(args, options = {}) {
+  const binary = options.binary ?? "playwright-cli";
+  return await new Promise((resolve, reject) => {
+    const child = spawn(binary, args, {
+      cwd: options.cwd ?? process.cwd(),
+      env: options.env ?? process.env,
+      stdio: "inherit"
+    });
+    child.on("error", reject);
+    child.on("close", (code) => {
+      resolve({ exitCode: code ?? -1 });
+    });
+  });
+}
+
+// src/parse-network.ts
+function parsePlaywrightCliNetwork(text) {
+  const requests = [];
+  if (!/^###\s+Result/m.test(text)) return [];
+  const lines = text.split(/\r?\n/);
+  const re = /^\s*\d+\.\s*\[([A-Z]+)\]\s+(\S+)\s+=>\s+\[(\d+)\]\s*(.*?)\s*$/;
+  for (const line of lines) {
+    const m = re.exec(line);
+    if (m === null) continue;
+    requests.push({
+      method: m[1] ?? "",
+      url: m[2] ?? "",
+      status: Number.parseInt(m[3] ?? "0", 10),
+      statusText: m[4] ?? ""
+    });
+  }
+  return requests;
+}
+
+// src/commands/network.ts
+async function runNetworkCommand(opts) {
+  const sightmap = await loadDirectory3(opts.sightmapDir);
+  const result = await execPlaywrightCli([
+    "-s",
+    opts.sessionName,
+    "network",
+    "requests"
+  ]);
+  if (result.exitCode !== 0) {
+    process.stderr.write(result.stderr);
+    process.exit(result.exitCode);
+  }
+  const parsed = parsePlaywrightCliNetwork(result.stdout);
+  const annotated = annotateNetworkRequests(sightmap, parsed);
+  if (opts.json) {
+    process.stdout.write(JSON.stringify(annotated, null, 2) + "\n");
+    return;
+  }
+  for (const r of annotated) {
+    const tag = r.sightmapName ? `  [${r.sightmapName}]` : "";
+    process.stdout.write(`[${r.method}] ${r.url} \u2192 ${r.status}${tag}
+`);
+    if (r.sightmapMemory) {
+      for (const m of r.sightmapMemory) process.stdout.write(`    memory: ${m}
+`);
+    }
+  }
+}
+
+// src/commands/passthrough.ts
+async function runPassthroughCommand(opts) {
+  const { exitCode } = await streamPlaywrightCli([
+    "-s",
+    opts.sessionName,
+    ...opts.rest
+  ]);
+  if (exitCode !== 0) process.exit(exitCode);
+}
+
+// src/commands/snapshot.ts
+import {
+  enrichSnapshot,
+  loadDirectory as loadDirectory4,
+  match as sightmapMatch
+} from "@sightmap/sightmap";
+
+// src/parse-snapshot.ts
+function parsePlaywrightCliSnapshot(text) {
+  const lines = text.split(/\r?\n/);
+  let url = "";
+  let title;
+  const nodes = [];
+  let inSnapshotSection = false;
+  let snapshotBaseIndent = null;
+  const pageUrlRe = /^- Page URL:\s*(\S+)/;
+  const pageTitleRe = /^- Page Title:\s*(.+?)\s*$/;
+  const nodeRe = /^(\s*)-\s+([a-zA-Z][\w-]*)\s*(?:"([^"]*)")?\s*((?:\[[^\]]+\]\s*)*)\s*:?/;
+  const refAttrRe = /\[ref=(e\d+)\]/;
+  for (const line of lines) {
+    if (/^###\s+Snapshot/.test(line)) {
+      inSnapshotSection = true;
+      continue;
+    }
+    if (/^###\s+Events/.test(line)) {
+      inSnapshotSection = false;
+      continue;
+    }
+    if (/^###\s+/.test(line)) {
+      inSnapshotSection = false;
+      continue;
+    }
+    if (/^```/.test(line)) continue;
+    if (!inSnapshotSection) {
+      const u = pageUrlRe.exec(line);
+      if (u) {
+        url = u[1] ?? "";
+        continue;
+      }
+      const t = pageTitleRe.exec(line);
+      if (t) {
+        title = t[1];
+        continue;
+      }
+      continue;
+    }
+    const m = nodeRe.exec(line);
+    if (m === null) continue;
+    const indent = m[1] ?? "";
+    const role = m[2];
+    const name = m[3];
+    const attrs = m[4] ?? "";
+    const refMatch = refAttrRe.exec(attrs);
+    const ref = refMatch?.[1];
+    if (snapshotBaseIndent === null) snapshotBaseIndent = indent.length;
+    const depth = Math.max(
+      0,
+      Math.floor((indent.length - snapshotBaseIndent) / 2)
+    );
+    nodes.push({
+      depth,
+      ...ref !== void 0 ? { ref } : {},
+      ...role !== void 0 ? { role } : {},
+      ...name !== void 0 ? { name } : {}
+    });
+  }
+  return {
+    url,
+    ...title !== void 0 ? { title } : {},
+    ariaText: text,
+    nodes
+  };
+}
+
+// src/in-page-runner.ts
+import {
+  buildInPageEvalFunction
+} from "@sightmap/sightmap";
+async function runInPageMatcher(components, sessionName, options = {}) {
+  if (components.length === 0) return [];
+  const js = buildInPageEvalFunction(components);
+  const result = await execPlaywrightCli(
+    ["-s", sessionName, "eval", js],
+    options
+  );
+  if (result.exitCode !== 0) {
+    throw new Error(`playwright-cli eval failed: ${result.stderr}`);
+  }
+  return parseInPageEvalStdout(result.stdout);
+}
+function parseInPageEvalStdout(stdout) {
+  const text = stdout.trim();
+  if (text.length === 0) return [];
+  const afterResult = text.split(/^###\s*Result/im)[1] ?? text;
+  const start = afterResult.indexOf("{");
+  if (start < 0) return [];
+  for (let end = afterResult.length; end > start; end--) {
+    try {
+      const parsed = JSON.parse(afterResult.slice(start, end));
+      if (Array.isArray(parsed.matches)) return parsed.matches;
+    } catch {
+    }
+  }
+  return [];
+}
+
+// src/commands/snapshot.ts
+async function runSnapshotCommand(opts) {
+  const sightmap = await loadDirectory4(opts.sightmapDir);
+  const snapResult = await execPlaywrightCli([
+    "-s",
+    opts.sessionName,
+    "snapshot"
+  ]);
+  if (snapResult.exitCode !== 0) {
+    process.stderr.write(snapResult.stderr);
+    process.exit(snapResult.exitCode);
+  }
+  const parsed = parsePlaywrightCliSnapshot(snapResult.stdout);
+  const matchResult = sightmapMatch(sightmap, { url: parsed.url });
+  const allComponents = matchResult.components.map((c) => ({
+    name: c.name,
+    selector: c.selector
+  }));
+  const inPage = await runInPageMatcher(allComponents, opts.sessionName);
+  const enriched = enrichSnapshot({
+    sightmap,
+    currentUrl: parsed.url,
+    inPageMatches: inPage
+  });
+  if (opts.json) {
+    process.stdout.write(
+      JSON.stringify({ ...enriched, ariaSnapshot: parsed.ariaText }, null, 2) + "\n"
+    );
+  } else {
+    process.stdout.write(formatHuman(enriched, parsed.ariaText));
+  }
+}
+function formatHuman(enriched, ariaText) {
+  const lines = [];
+  if (enriched.view) {
+    lines.push(`View: ${enriched.view.name} (${enriched.view.route})`);
+    if (enriched.view.memory.length > 0) {
+      lines.push(`  memory:`);
+      for (const m of enriched.view.memory) lines.push(`    - ${m}`);
+    }
+  } else {
+    lines.push(`View: (no match)`);
+  }
+  if (enriched.components.length > 0) {
+    lines.push(`Components:`);
+    for (const c of enriched.components) {
+      lines.push(
+        `  - ${c.name} (${c.scope}) \u2014 ${c.matchCount} match${c.matchCount === 1 ? "" : "es"}`
+      );
+      for (const m of c.memory) lines.push(`      memory: ${m}`);
+    }
+  }
+  lines.push("");
+  lines.push("--- ARIA snapshot ---");
+  lines.push(ariaText);
+  return lines.join("\n");
+}
+
+// src/cli.ts
+function requireValue(flag, next) {
+  if (next === void 0 || next.startsWith("-")) {
+    console.error(
+      `${flag}: expected a value, got "${next ?? "(end of args)"}"`
+    );
+    process.exit(2);
+  }
+  return next;
+}
+function parseArgs(argv) {
+  let session = "default";
+  let sightmapDir = ".sightmap";
+  let json = false;
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "-s" || a === "--session") {
+      session = requireValue(a, argv[++i]);
+    } else if (a === "--sightmap-dir") {
+      sightmapDir = requireValue(a, argv[++i]);
+    } else if (a === "--json") {
+      json = true;
+    } else {
+      positional.push(a);
+    }
+  }
+  return {
+    command: positional[0] ?? "",
+    session,
+    sightmapDir,
+    json,
+    rest: positional.slice(1)
+  };
+}
+function printHelp() {
+  console.log(
+    `sightmap-playwright \u2014 sightmap-aware wrapper around @playwright/cli
+
+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 with sightmap component names
+  match URL               Show the matching sightmap view for URL
+  act NAME                Resolve a sightmap component name to a selector
+  network                 Network requests annotated with sightmap memory
+
+All other commands are forwarded to @playwright/cli verbatim.
+`
+  );
+}
+async function main() {
+  const argv = process.argv.slice(2);
+  if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
+    printHelp();
+    return;
+  }
+  const { command, session, sightmapDir, json, rest } = parseArgs(argv);
+  switch (command) {
+    case "snapshot":
+      await runSnapshotCommand({ sessionName: session, sightmapDir, json });
+      return;
+    case "match": {
+      const url = rest[0];
+      if (url === void 0) {
+        console.error("sightmap-playwright match: URL required");
+        process.exit(2);
+      }
+      await runMatchCommand({ url, sightmapDir, json });
+      return;
+    }
+    case "act": {
+      const name = rest[0];
+      if (name === void 0) {
+        console.error("sightmap-playwright act: component name required");
+        process.exit(2);
+      }
+      await runActCommand({ componentName: name, sightmapDir, json });
+      return;
+    }
+    case "network":
+      await runNetworkCommand({ sessionName: session, sightmapDir, json });
+      return;
+    default: {
+      const passArgs = json ? ["--json", command, ...rest] : [command, ...rest];
+      await runPassthroughCommand({
+        sessionName: session,
+        rest: passArgs.filter((s) => s.length > 0)
+      });
+      return;
+    }
+  }
+}
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@sightmap/playwright",
+  "version": "0.9.0",
+  "description": "Sightmap-aware wrapper around @playwright/cli. Adds sightmap_* commands and enriches snapshot output with component names from .sightmap/.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sightmap/sightmap-js.git",
+    "directory": "packages/playwright"
+  },
+  "homepage": "https://sightmap.org",
+  "keywords": [
+    "sightmap",
+    "playwright",
+    "cli",
+    "agent",
+    "browser"
+  ],
+  "type": "module",
+  "bin": {
+    "sightmap-playwright": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@playwright/cli": "^0.1.13",
+    "@types/node": "^20.19.39",
+    "tsup": "^8.5.1",
+    "typescript": "~5.7.3",
+    "vitest": "^3.0.0"
+  },
+  "dependencies": {
+    "@sightmap/sightmap": "^0.9.0"
+  },
+  "peerDependencies": {
+    "@playwright/cli": "^0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@playwright/cli": {
+      "optional": false
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  }
+}