@sightmap/playwright 0.9.0 → 0.10.0

package/README.md

@@ -36,9 +36,21 @@ Global flags:
 
 ### `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`).
+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]`).
 
 ```text
 $ sightmap-playwright snapshot
@@ -51,12 +63,17 @@ Components:
       memory: clicking opens detail in a new tab
 
 --- ARIA snapshot ---
-- main:
-  - heading "Results for 'sightmap'" [level=1]
-  ...
+- 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]
 ```
 
-Pass `--json` to get the structured `EnrichedSnapshot` plus raw ARIA text.
+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
 

package/dist/cli.js

@@ -274,6 +274,71 @@ function parseInPageEvalStdout(stdout) {
   return [];
 }
 
+// src/ref-join.ts
+function buildRefJoinSnippet(components, refs) {
+  const componentsJson = JSON.stringify(components);
+  const refsJson = JSON.stringify(refs);
+  return `async (page) => {
+    const components = ${componentsJson};
+    const refs = ${refsJson};
+    await page.evaluate((components) => {
+      for (const c of components) {
+        for (const sel of (c.selector || [])) {
+          let els;
+          try { els = document.querySelectorAll(sel); } catch { continue; }
+          for (const el of Array.from(els)) {
+            let names = [];
+            try { names = JSON.parse(el.getAttribute("data-sm-mark") || "[]"); } catch { names = []; }
+            if (!names.includes(c.name)) names.push(c.name);
+            el.setAttribute("data-sm-mark", JSON.stringify(names));
+          }
+        }
+      }
+    }, components);
+    const refAnnotations = {};
+    await Promise.all(refs.map(async (ref) => {
+      try {
+        const mark = await page.locator("aria-ref=" + ref).evaluate((el) => el.getAttribute("data-sm-mark"));
+        if (mark) {
+          const names = JSON.parse(mark);
+          if (Array.isArray(names) && names.length > 0) refAnnotations[ref] = names;
+        }
+      } catch { /* ref no longer resolvable \u2014 skip */ }
+    }));
+    try {
+      await page.evaluate(() => {
+        for (const el of Array.from(document.querySelectorAll("[data-sm-mark]"))) {
+          el.removeAttribute("data-sm-mark");
+        }
+      });
+    } catch { /* best-effort cleanup */ }
+    return { refAnnotations };
+  }`;
+}
+function parseRefJoinOutput(stdout) {
+  const empty = /* @__PURE__ */ new Map();
+  const text = stdout.trim();
+  if (text.length === 0) return empty;
+  const afterResult = text.split(/^###\s*Result/im)[1] ?? text;
+  const start = afterResult.indexOf("{");
+  if (start < 0) return empty;
+  for (let end = afterResult.length; end > start; end--) {
+    try {
+      const parsed = JSON.parse(afterResult.slice(start, end));
+      const ann = parsed.refAnnotations;
+      if (ann && typeof ann === "object") {
+        const m = /* @__PURE__ */ new Map();
+        for (const [ref, names] of Object.entries(ann)) {
+          if (Array.isArray(names) && names.length > 0) m.set(ref, names);
+        }
+        return m;
+      }
+    } catch {
+    }
+  }
+  return empty;
+}
+
 // src/commands/snapshot.ts
 async function runSnapshotCommand(opts) {
   const sightmap = await loadDirectory4(opts.sightmapDir);
@@ -293,18 +358,43 @@ async function runSnapshotCommand(opts) {
     selector: c.selector
   }));
   const inPage = await runInPageMatcher(allComponents, opts.sessionName);
+  const refs = parsed.nodes.map((n) => n.ref).filter((r) => r !== void 0);
+  const refAnnotations = await resolveRefAnnotations(
+    allComponents,
+    refs,
+    opts.sessionName
+  );
   const enriched = enrichSnapshot({
     sightmap,
     currentUrl: parsed.url,
-    inPageMatches: inPage
+    inPageMatches: inPage,
+    ariaText: parsed.ariaText,
+    refAnnotations
   });
+  const ariaForHuman = enriched.enrichedAriaText ?? parsed.ariaText;
   if (opts.json) {
     process.stdout.write(
       JSON.stringify({ ...enriched, ariaSnapshot: parsed.ariaText }, null, 2) + "\n"
     );
   } else {
-    process.stdout.write(formatHuman(enriched, parsed.ariaText));
+    process.stdout.write(formatHuman(enriched, ariaForHuman));
+  }
+}
+async function resolveRefAnnotations(components, refs, sessionName) {
+  if (components.length === 0 || refs.length === 0) {
+    return /* @__PURE__ */ new Map();
+  }
+  const snippet = buildRefJoinSnippet(components, refs);
+  const result = await execPlaywrightCli([
+    "-s",
+    sessionName,
+    "run-code",
+    snippet
+  ]);
+  if (result.exitCode !== 0) {
+    return /* @__PURE__ */ new Map();
   }
+  return parseRefJoinOutput(result.stdout);
 }
 function formatHuman(enriched, ariaText) {
   const lines = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sightmap/playwright",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Sightmap-aware wrapper around @playwright/cli. Adds sightmap_* commands and enriches snapshot output with component names from .sightmap/.",
   "license": "MIT",
   "repository": {
@@ -36,7 +36,7 @@
     "vitest": "^3.0.0"
   },
   "dependencies": {
-    "@sightmap/sightmap": "^0.9.0"
+    "@sightmap/sightmap": "^0.10.0"
   },
   "peerDependencies": {
     "@playwright/cli": "^0.1.0"