@runtypelabs/persona 3.21.2 → 3.22.0

package/src/utils/smart-dom-adapter.test.ts

@@ -0,0 +1,257 @@
+// Pure mapper test — no DOM, no installed/vendored library at runtime (types only).
+import { describe, it, expect } from "vitest";
+import { smartDomResultToEnriched } from "./smart-dom-adapter";
+import { formatEnrichedContext } from "./dom-context";
+import type {
+  SmartDOMResult,
+  ExtractedElement,
+  ElementSelector
+} from "../vendor/smart-dom-reader";
+
+function makeSelector(partial: Partial<ElementSelector> = {}): ElementSelector {
+  return { css: "div", xpath: "/html/body/div", ...partial };
+}
+
+function makeEl(partial: Partial<ExtractedElement> = {}): ExtractedElement {
+  return {
+    tag: partial.tag ?? "div",
+    text: partial.text ?? "",
+    selector: partial.selector ?? makeSelector(),
+    attributes: partial.attributes ?? {},
+    context: {
+      parentChain: [],
+      ...(partial.context ?? {})
+    },
+    interaction: partial.interaction ?? {},
+    children: partial.children
+  };
+}
+
+function makeResult(
+  interactive: Partial<SmartDOMResult["interactive"]> = {},
+  semantic?: SmartDOMResult["semantic"]
+): SmartDOMResult {
+  return {
+    mode: semantic ? "full" : "interactive",
+    timestamp: 0,
+    page: {
+      url: "https://example.com",
+      title: "Example",
+      hasErrors: false,
+      isLoading: false,
+      hasModals: false
+    },
+    landmarks: {
+      navigation: [],
+      main: [],
+      forms: [],
+      headers: [],
+      footers: [],
+      articles: [],
+      sections: []
+    },
+    interactive: {
+      buttons: [],
+      links: [],
+      inputs: [],
+      forms: [],
+      clickable: [],
+      ...interactive
+    },
+    semantic
+  };
+}
+
+describe("smartDomResultToEnriched", () => {
+  it("prefers the highest-scoring plain-CSS candidate and skips XPath/text", () => {
+    const result = makeResult({
+      buttons: [
+        makeEl({
+          tag: "button",
+          text: "Add to cart",
+          interaction: { click: true },
+          selector: makeSelector({
+            css: "button.add",
+            xpath: "/html/body/button[1]",
+            candidates: [
+              { type: "xpath", value: "/html/body/button[1]", score: 100 },
+              { type: "text", value: "text=Add to cart", score: 90 },
+              { type: "data-testid", value: '[data-testid="add"]', score: 80 },
+              { type: "class-path", value: "button.add", score: 50 }
+            ]
+          })
+        })
+      ]
+    });
+
+    const enriched = smartDomResultToEnriched(result);
+    expect(enriched).toHaveLength(1);
+    // best plain-CSS candidate by score (data-testid:80 > class-path:50; xpath/text skipped)
+    expect(enriched[0].selector).toBe('[data-testid="add"]');
+    expect(enriched[0].interactivity).toBe("clickable");
+  });
+
+  it("falls back to selector.css when no candidates qualify", () => {
+    const result = makeResult({
+      buttons: [
+        makeEl({
+          tag: "button",
+          text: "Go",
+          interaction: { click: true },
+          selector: makeSelector({ css: "button.go", candidates: [] })
+        })
+      ]
+    });
+    const enriched = smartDomResultToEnriched(result);
+    expect(enriched[0].selector).toBe("button.go");
+  });
+
+  it("classifies interactivity from tag/role/interaction", () => {
+    const result = makeResult({
+      buttons: [
+        makeEl({
+          tag: "button",
+          text: "Buy",
+          interaction: { click: true },
+          selector: makeSelector({ css: "button.buy" })
+        })
+      ],
+      links: [
+        makeEl({
+          tag: "a",
+          text: "Home",
+          attributes: { href: "/home" },
+          interaction: { nav: true },
+          selector: makeSelector({ css: "a.home" })
+        })
+      ],
+      inputs: [
+        makeEl({
+          tag: "input",
+          attributes: { type: "text", name: "q" },
+          interaction: { change: true },
+          selector: makeSelector({ css: "input.q" })
+        })
+      ]
+    });
+
+    const enriched = smartDomResultToEnriched(result);
+    const bySel = Object.fromEntries(enriched.map((e) => [e.selector, e]));
+    expect(bySel["button.buy"].interactivity).toBe("clickable");
+    expect(bySel["a.home"].interactivity).toBe("navigable");
+    expect(bySel["input.q"].interactivity).toBe("input");
+  });
+
+  it("excludes elements under the host (.persona-host) via parentChain", () => {
+    const result = makeResult({
+      buttons: [
+        makeEl({
+          tag: "button",
+          text: "Widget send",
+          interaction: { click: true },
+          selector: makeSelector({ css: "button.send" }),
+          context: { parentChain: ["div.persona-host", "div.panel"] }
+        }),
+        makeEl({
+          tag: "button",
+          text: "Page button",
+          interaction: { click: true },
+          selector: makeSelector({ css: "button.page" }),
+          context: { parentChain: ["main", "section"] }
+        })
+      ]
+    });
+
+    const enriched = smartDomResultToEnriched(result);
+    expect(enriched.map((e) => e.selector)).toEqual(["button.page"]);
+  });
+
+  it("includes semantic elements only when present and not disabled", () => {
+    const semantic: SmartDOMResult["semantic"] = {
+      headings: [
+        makeEl({
+          tag: "h1",
+          text: "Title",
+          selector: makeSelector({ css: "h1.title" })
+        })
+      ],
+      images: [],
+      tables: [],
+      lists: [],
+      articles: []
+    };
+    const result = makeResult(
+      {
+        buttons: [
+          makeEl({
+            tag: "button",
+            text: "Go",
+            interaction: { click: true },
+            selector: makeSelector({ css: "button.go" })
+          })
+        ]
+      },
+      semantic
+    );
+
+    const withSemantic = smartDomResultToEnriched(result);
+    expect(withSemantic.map((e) => e.selector)).toContain("h1.title");
+    const heading = withSemantic.find((e) => e.selector === "h1.title");
+    expect(heading?.interactivity).toBe("static");
+
+    const withoutSemantic = smartDomResultToEnriched(result, {
+      includeSemantic: false
+    });
+    expect(withoutSemantic.map((e) => e.selector)).not.toContain("h1.title");
+  });
+
+  it("deduplicates by selector and honors maxElements", () => {
+    const dup = makeEl({
+      tag: "button",
+      text: "Dup",
+      interaction: { click: true },
+      selector: makeSelector({ css: "button.dup" })
+    });
+    const result = makeResult({
+      buttons: [dup, dup],
+      clickable: [dup]
+    });
+    expect(smartDomResultToEnriched(result)).toHaveLength(1);
+
+    const many = makeResult({
+      buttons: [
+        makeEl({ tag: "button", text: "1", interaction: { click: true }, selector: makeSelector({ css: "button.a" }) }),
+        makeEl({ tag: "button", text: "2", interaction: { click: true }, selector: makeSelector({ css: "button.b" }) }),
+        makeEl({ tag: "button", text: "3", interaction: { click: true }, selector: makeSelector({ css: "button.c" }) })
+      ]
+    });
+    expect(smartDomResultToEnriched(many, { maxElements: 2 })).toHaveLength(2);
+  });
+
+  it("produces output that feeds formatEnrichedContext", () => {
+    const result = makeResult({
+      buttons: [
+        makeEl({
+          tag: "button",
+          text: "Checkout",
+          interaction: { click: true },
+          selector: makeSelector({ css: "button.checkout" })
+        })
+      ],
+      links: [
+        makeEl({
+          tag: "a",
+          text: "Cart",
+          attributes: { href: "/cart" },
+          interaction: { nav: true },
+          selector: makeSelector({ css: "a.cart" })
+        })
+      ]
+    });
+
+    const formatted = formatEnrichedContext(smartDomResultToEnriched(result));
+    expect(formatted).toContain("button.checkout");
+    expect(formatted).toContain("a.cart");
+    expect(formatted).toContain("Checkout");
+  });
+});

package/src/utils/smart-dom-adapter.ts

@@ -0,0 +1,217 @@
+/**
+ * Pure mapper: `@mcp-b/smart-dom-reader` output → Persona's {@link EnrichedPageElement}[].
+ *
+ * This module imports the smart-dom-reader types with `import type` ONLY, so the
+ * library's runtime value is never pulled in here. That keeps the mapper — and its
+ * unit test — free of any DOM and free of the (vendored) library at runtime; the
+ * types are erased during compilation.
+ *
+ * The smart-dom-reader returns a structured {@link SmartDOMResult} JSON object with
+ * rich selectors (CSS + XPath + ranked candidates). Persona's collect → reason → act
+ * loop drives clicks through `document.querySelector` (see `utils/actions.ts`), which
+ * cannot pierce shadow roots or evaluate XPath. So this mapper deliberately prefers
+ * the **best plain-CSS candidate selector** for each element and skips XPath / text
+ * pseudo-selectors, keeping results actionable.
+ */
+
+import type {
+  SmartDOMResult,
+  ExtractedElement,
+  ElementSelectorCandidate
+} from "../vendor/smart-dom-reader";
+import type { EnrichedPageElement } from "./dom-context";
+
+/** Options for {@link smartDomResultToEnriched}. */
+export interface SmartDomAdapterOptions {
+  /**
+   * Include non-interactive `semantic` groups (headings, images, tables, lists,
+   * articles) when the result has them (i.e. full-mode extraction). Default: true.
+   */
+  includeSemantic?: boolean;
+  /**
+   * Skip elements whose own selector / ancestor chain contains this selector string,
+   * so the widget never reports its own shadow-DOM UI. Matched as a substring against
+   * the element's candidate selectors and `context.parentChain`. Default: ".persona-host".
+   * Pass "" to disable.
+   */
+  excludeSelector?: string;
+  /** Truncate each element's text to this many characters. Default: 200. */
+  maxTextLength?: number;
+  /** Optional cap on the number of mapped elements returned. */
+  maxElements?: number;
+}
+
+/**
+ * Candidate selector types that resolve through `document.querySelector` (plain CSS).
+ * Everything else smart-dom-reader can emit — `xpath` and text pseudo-selectors —
+ * is not actionable via the current click loop, so it is skipped here.
+ */
+const PLAIN_CSS_CANDIDATE_TYPES: ReadonlySet<ElementSelectorCandidate["type"]> =
+  new Set(["id", "data-testid", "role-aria", "name", "class-path", "css-path"]);
+
+/** Looks like an XPath expression rather than a CSS selector. */
+function looksLikeXPath(value: string): boolean {
+  const v = value.trim();
+  return v.startsWith("/") || v.startsWith("(") || v.startsWith("./");
+}
+
+/**
+ * Pick the best `document.querySelector`-able selector for an extracted element:
+ * the highest-scoring plain-CSS candidate, falling back to the primary `css` field
+ * when no candidate qualifies. Returns null when only XPath-like selectors exist.
+ */
+function bestPlainCssSelector(el: ExtractedElement): string | null {
+  const candidates = el.selector.candidates;
+  if (candidates && candidates.length > 0) {
+    let best: ElementSelectorCandidate | null = null;
+    for (const c of candidates) {
+      if (!PLAIN_CSS_CANDIDATE_TYPES.has(c.type)) continue;
+      if (!c.value || looksLikeXPath(c.value)) continue;
+      if (!best || c.score > best.score) best = c;
+    }
+    if (best) return best.value;
+  }
+  const css = el.selector.css;
+  if (css && !looksLikeXPath(css)) return css;
+  return null;
+}
+
+/** Classify an extracted element into Persona's interactivity buckets. */
+function classifyInteractivity(
+  el: ExtractedElement
+): EnrichedPageElement["interactivity"] {
+  const tag = el.tag.toLowerCase();
+  const role = el.interaction.role ?? el.attributes.role;
+
+  if (tag === "a" && (el.interaction.nav || el.attributes.href != null)) {
+    return "navigable";
+  }
+  if (tag === "input" || tag === "select" || tag === "textarea") return "input";
+  if (
+    role === "textbox" ||
+    role === "combobox" ||
+    role === "listbox" ||
+    role === "spinbutton"
+  ) {
+    return "input";
+  }
+  if (el.interaction.change && !el.interaction.click) return "input";
+  if (
+    tag === "button" ||
+    role === "button" ||
+    el.interaction.click ||
+    el.interaction.submit
+  ) {
+    return "clickable";
+  }
+  return "static";
+}
+
+/** Build the relevant-attribute bag, mirroring `dom-context.collectAttributes`. */
+function collectAttributes(el: ExtractedElement): Record<string, string> {
+  const attrs: Record<string, string> = { ...el.attributes };
+  const role = el.interaction.role;
+  if (role && !attrs.role) attrs.role = role;
+  return attrs;
+}
+
+/**
+ * Returns true when the element sits under `excludeSelector` (e.g. the widget host).
+ * smart-dom-reader has no exclude option and pierces shadow DOM by default, so this
+ * guards against the widget reading its own UI. The check is a substring match across
+ * the element's candidate selectors and ancestor chain — robust for the default
+ * `.persona-host` class guard.
+ */
+function isExcluded(el: ExtractedElement, excludeSelector: string): boolean {
+  if (!excludeSelector) return false;
+  const haystacks: Array<string | undefined> = [
+    el.selector.css,
+    el.selector.xpath,
+    el.context.nearestForm,
+    el.context.nearestSection,
+    el.context.nearestMain,
+    el.context.nearestNav,
+    ...(el.selector.candidates?.map((c) => c.value) ?? []),
+    ...el.context.parentChain
+  ];
+  return haystacks.some((h) => !!h && h.includes(excludeSelector));
+}
+
+/**
+ * Map a {@link SmartDOMResult} into Persona's {@link EnrichedPageElement}[] shape so it
+ * can be formatted by `formatEnrichedContext` and consumed wherever the default
+ * `collectEnrichedPageContext` output is.
+ *
+ * - Maps `interactive.{buttons, links, inputs, clickable}` and, when present and
+ *   `includeSemantic` is not false, `semantic.{headings, images, tables, lists, articles}`.
+ * - Chooses the best plain-CSS selector per element (skipping XPath / shadow-piercing
+ *   selectors) so results stay actionable via `document.querySelector`.
+ * - Drops elements under `excludeSelector` (default `.persona-host`).
+ * - Deduplicates by selector and preserves discovery order (interactive before semantic).
+ */
+export function smartDomResultToEnriched(
+  result: SmartDOMResult,
+  opts: SmartDomAdapterOptions = {}
+): EnrichedPageElement[] {
+  const includeSemantic = opts.includeSemantic ?? true;
+  const excludeSelector = opts.excludeSelector ?? ".persona-host";
+  const maxTextLength = opts.maxTextLength ?? 200;
+
+  const groups: ExtractedElement[][] = [
+    result.interactive.buttons,
+    result.interactive.links,
+    result.interactive.inputs,
+    result.interactive.clickable
+  ];
+
+  if (includeSemantic && result.semantic) {
+    groups.push(
+      result.semantic.headings,
+      result.semantic.images,
+      result.semantic.tables,
+      result.semantic.lists,
+      result.semantic.articles
+    );
+  }
+
+  const out: EnrichedPageElement[] = [];
+  const seen = new Set<string>();
+
+  // Walk an element and any nested children. In full mode the library attaches
+  // shadow-DOM descendants as `children` of semantic containers, so recursing here
+  // is how those pierced elements surface. Returns false once the optional
+  // maxElements cap is reached.
+  const visit = (el: ExtractedElement): boolean => {
+    if (isExcluded(el, excludeSelector)) return true;
+
+    const selector = bestPlainCssSelector(el);
+    if (selector && !seen.has(selector)) {
+      seen.add(selector);
+      out.push({
+        selector,
+        tagName: el.tag.toLowerCase(),
+        text: (el.text ?? "").trim().substring(0, maxTextLength),
+        role: el.interaction.role ?? el.attributes.role ?? null,
+        interactivity: classifyInteractivity(el),
+        attributes: collectAttributes(el)
+      });
+      if (opts.maxElements && out.length >= opts.maxElements) return false;
+    }
+
+    if (el.children) {
+      for (const child of el.children) {
+        if (!visit(child)) return false;
+      }
+    }
+    return true;
+  };
+
+  for (const group of groups) {
+    if (!group) continue;
+    for (const el of group) {
+      if (!visit(el)) return out;
+    }
+  }
+
+  return out;
+}

package/{LICENSE → src/vendor/smart-dom-reader/LICENSE}

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Runtype
+Copyright (c) 2025 mcp-b contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ 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.
+SOFTWARE.

package/src/vendor/smart-dom-reader/README.md

@@ -0,0 +1,61 @@
+# Vendored: `@mcp-b/smart-dom-reader`
+
+This directory contains a **vendored copy** of [`@mcp-b/smart-dom-reader`](https://github.com/WebMCP-org/npm-packages/tree/main/packages/smart-dom-reader)
+(v2.3.1, MIT, © 2025 mcp-b contributors), consumed only by the optional
+`@runtypelabs/persona/smart-dom-reader` entry point (`src/smart-dom-reader.ts`)
+and the pure mapper (`src/utils/smart-dom-adapter.ts`, type-only).
+
+## Why vendored instead of a dependency
+
+Every published version of the package (2.3.1, 2.3.2, 3.0.0) is **mis-published**:
+its `package.json` declares
+
+```json
+"main":    "./dist/index.js",
+"types":   "./dist/index.d.ts",
+"exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" } }
+```
+
+but the build tool (`vp pack`, vite-plus/rolldown) only emits `dist/index.mjs` +
+`dist/index.d.mts`. The files referenced by `package.json` are **absent from the
+tarball**, so the package cannot be imported by name in Node or any bundler
+(`ERR_MODULE_NOT_FOUND`), and TypeScript cannot resolve its types. This affects
+the package itself and every downstream consumer, so making it an optional peer
+dependency would ship a feature that no integrator could actually load.
+
+Vendoring the built artifact into this opt-in entry sidesteps the broken module
+resolution entirely: the code is bundled into `dist/smart-dom-reader.{js,cjs}`
+and never touches a package resolver. Consumers who never import the
+`/smart-dom-reader` entry pay nothing.
+
+> **Follow-up:** raise the packaging bug with the upstream maintainer. Once a
+> corrected release exists, this vendor dir can be replaced with a normal
+> optional peer dependency (see the original plan).
+
+## Files
+
+- `index.js` — upstream `dist/index.mjs`, with two local edits (see header comment).
+- `index.d.ts` — upstream `dist/index.d.mts` verbatim (sourceMappingURL stripped).
+- `LICENSE` — upstream MIT license.
+
+## Local modifications to `index.js`
+
+The **only** changes from upstream `dist/index.mjs` are:
+
+1. Removed the top-level `import { createRequire } from "node:module";` — a
+   Node-only builtin that breaks browser bundling.
+2. Replaced `var __require = createRequire(import.meta.url);` with
+   `var __require = void 0;`. `__require` is referenced only inside a guarded
+   `typeof __require === "function"` Node fallback in `resolveSmartDomReader()`;
+   the browser path (`typeof window !== "undefined"`) returns before reaching it,
+   so this is a runtime no-op in the browser.
+
+## How to update
+
+1. `npm pack @mcp-b/smart-dom-reader@<version>` and extract the tarball.
+2. Copy `dist/index.mjs` → `index.js` and `dist/index.d.mts` → `index.d.ts`.
+3. Re-apply the two edits above (strip the `node:module` import; neutralize
+   `__require`) and the provenance headers. Strip trailing `sourceMappingURL`
+   comments.
+4. Copy the upstream `LICENSE`.
+5. Re-run `pnpm --filter @runtypelabs/persona build typecheck test:run`.