@runtypelabs/persona 3.21.2 → 3.22.0

package/src/smart-dom-reader.test.ts

@@ -0,0 +1,135 @@
+// @vitest-environment jsdom
+//
+// End-to-end smoke test for the optional smart-dom-reader entry, exercising the
+// vendored library under jsdom. The pure-mapper correctness guarantee lives in
+// utils/smart-dom-adapter.test.ts (no DOM, no library); this test confirms the
+// vendored runtime loads and the provider wires up against a real document.
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import {
+  collectSmartDomContext,
+  createSmartDomReaderContextProvider
+} from "./smart-dom-reader";
+
+// jsdom implements no layout, so getBoundingClientRect()/offsetParent report the
+// element as zero-size and the library's visibility filter would drop everything.
+// includeHidden bypasses that filter so we can exercise real extraction under jsdom.
+const JSDOM_OPTS = { extractionOptions: { includeHidden: true } } as const;
+
+// This vitest jsdom environment doesn't expose CSS.escape (real browsers do). The
+// vendored library calls it unguarded during selector generation, so shim it with the
+// same fallback dom-context.ts uses.
+function ensureCssEscape(): void {
+  const g = globalThis as unknown as { CSS?: { escape?: (s: string) => string } };
+  if (!g.CSS) g.CSS = {};
+  if (typeof g.CSS.escape !== "function") {
+    g.CSS.escape = (str: string) => str.replace(/([^\w-])/g, "\\$1");
+  }
+}
+
+describe("smart-dom-reader entry (jsdom)", () => {
+  beforeEach(() => {
+    ensureCssEscape();
+    document.body.innerHTML = "";
+  });
+  afterEach(() => {
+    document.body.innerHTML = "";
+  });
+
+  it("collects interactive elements from the light DOM", () => {
+    document.body.innerHTML = `
+      <main>
+        <button id="checkout">Checkout</button>
+        <a href="/cart">View cart</a>
+        <input type="text" name="q" />
+      </main>
+    `;
+
+    const elements = collectSmartDomContext(JSDOM_OPTS);
+    const selectors = elements.map((e) => e.selector).join(" ");
+    // At minimum the button and link should be discovered and actionable.
+    expect(elements.length).toBeGreaterThan(0);
+    expect(selectors).toMatch(/checkout|Checkout/i);
+  });
+
+  it("pierces shadow DOM (full mode), surfacing elements the default TreeWalker reader misses", () => {
+    // The library pierces shadow roots in full mode, attaching shadow descendants as
+    // children of a semantic-container host; the adapter flattens those children. The
+    // default dom-context.ts TreeWalker cannot reach into shadow trees at all.
+    const host = document.createElement("article");
+    host.id = "wc-host";
+    document.body.appendChild(host);
+    const shadow = host.attachShadow({ mode: "open" });
+    shadow.innerHTML = `<button id="shadow-btn">Shadow action</button>`;
+
+    const elements = collectSmartDomContext({
+      mode: "full",
+      extractionOptions: { includeHidden: true }
+    });
+    const texts = elements.map((e) => e.text).join(" | ");
+    expect(texts).toContain("Shadow action");
+  });
+
+  it("excludes the widget host (.persona-host) from results", () => {
+    document.body.innerHTML = `
+      <div class="persona-host"><button id="widget-internal">Send</button></div>
+      <main><button id="page-cta">Buy now</button></main>
+    `;
+
+    const elements = collectSmartDomContext(JSDOM_OPTS);
+    const selectors = elements.map((e) => e.selector);
+    expect(selectors.some((s) => s.includes("persona-host"))).toBe(false);
+    expect(elements.some((e) => e.text === "Buy now")).toBe(true);
+    expect(elements.some((e) => e.text === "Send")).toBe(false);
+  });
+
+  it("scopes extraction to `root`, ignoring elements outside the subtree", () => {
+    document.body.innerHTML = `
+      <nav><button id="chrome-cta">Sign up</button></nav>
+      <main id="content"><button id="page-cta">Buy now</button></main>
+    `;
+    const root = document.getElementById("content")!;
+
+    const elements = collectSmartDomContext({
+      root,
+      extractionOptions: { includeHidden: true }
+    });
+    expect(elements.some((e) => e.text === "Buy now")).toBe(true);
+    expect(elements.some((e) => e.text === "Sign up")).toBe(false);
+  });
+
+  it("pierces shadow DOM within a scoped `root`", () => {
+    const host = document.createElement("article");
+    host.id = "scoped-host";
+    const main = document.createElement("main");
+    main.id = "scoped-content";
+    main.appendChild(host);
+    document.body.appendChild(main);
+    host.attachShadow({ mode: "open" }).innerHTML =
+      `<button id="scoped-shadow-btn">Scoped shadow action</button>`;
+
+    const elements = collectSmartDomContext({
+      root: main,
+      mode: "full",
+      extractionOptions: { includeHidden: true }
+    });
+    const texts = elements.map((e) => e.text).join(" | ");
+    expect(texts).toContain("Scoped shadow action");
+  });
+
+  it("provider returns formatted context under the configured key", async () => {
+    document.body.innerHTML = `<main><button id="go">Continue</button></main>`;
+    const provider = createSmartDomReaderContextProvider({
+      contextKey: "pageContext",
+      ...JSDOM_OPTS
+    });
+    const result = await provider({ messages: [], config: {} as never });
+    expect(result).toBeTruthy();
+    expect(typeof (result as Record<string, unknown>).pageContext).toBe("string");
+    expect((result as Record<string, string>).pageContext).toContain("Continue");
+  });
+
+  it("returns [] for an empty document", () => {
+    document.body.innerHTML = "";
+    expect(collectSmartDomContext(JSDOM_OPTS)).toEqual([]);
+  });
+});

package/src/smart-dom-reader.ts

@@ -0,0 +1,135 @@
+/**
+ * Optional entry point: `@runtypelabs/persona/smart-dom-reader`.
+ *
+ * Adapts `@mcp-b/smart-dom-reader` into Persona's enriched page-context pipeline and
+ * exposes a ready-made {@link AgentWidgetContextProvider} you can drop into
+ * `config.contextProviders`. This is the ONLY module that imports the smart-dom-reader
+ * runtime value, so the library never reaches the main bundle or the IIFE/CDN build —
+ * importing this subpath is opt-in.
+ *
+ * The library is **vendored** under `src/vendor/smart-dom-reader/` (it is mis-published
+ * on npm and cannot be imported by name — see that directory's README). Vendoring it
+ * here means consumers need no extra install: the code is bundled into this entry, and
+ * consumers who never import this subpath pay nothing.
+ *
+ * What it adds over the default `collectEnrichedPageContext`: Shadow-DOM piercing
+ * (on by default), form grouping, and page landmarks/state.
+ *
+ * ## Actionability caveat
+ *
+ * Persona's click loop (`utils/actions.ts`) drives `document.querySelector`, which
+ * cannot pierce shadow roots or evaluate XPath. The adapter therefore prefers plain-CSS
+ * selectors; elements reachable only via shadow-piercing / XPath selectors are surfaced
+ * to the model as context but are not clickable through the current action handlers.
+ *
+ * @example
+ * ```ts
+ * import initAgentWidget from "@runtypelabs/persona";
+ * import { createSmartDomReaderContextProvider } from "@runtypelabs/persona/smart-dom-reader";
+ *
+ * initAgentWidget({
+ *   // ...config
+ *   contextProviders: [createSmartDomReaderContextProvider()]
+ * });
+ * ```
+ */
+
+import { SmartDOMReader } from "./vendor/smart-dom-reader";
+import type { ExtractionOptions } from "./vendor/smart-dom-reader";
+import {
+  smartDomResultToEnriched,
+  type SmartDomAdapterOptions
+} from "./utils/smart-dom-adapter";
+import { formatEnrichedContext, type EnrichedPageElement } from "./utils/dom-context";
+import type { AgentWidgetContextProvider } from "./types";
+
+export { smartDomResultToEnriched };
+export type { SmartDomAdapterOptions } from "./utils/smart-dom-adapter";
+
+/** Options for {@link collectSmartDomContext} and {@link createSmartDomReaderContextProvider}. */
+export interface SmartDomContextOptions extends SmartDomAdapterOptions {
+  /**
+   * `interactive` (default) extracts UI elements only; `full` additionally extracts
+   * semantic content (headings, images, tables, lists, articles).
+   */
+  mode?: "interactive" | "full";
+  /**
+   * Extraction options passed through to smart-dom-reader (e.g. `includeShadowDOM`,
+   * `maxDepth`, `viewportOnly`). `includeShadowDOM` defaults to true in the library;
+   * the `.persona-host` exclusion guards against the widget reading its own shadow UI.
+   *
+   * Note: the vendored library exposes an `includeIframes` flag but does not actually
+   * traverse iframe content, so iframe piercing is not supported.
+   */
+  extractionOptions?: Partial<ExtractionOptions>;
+  /** Document to extract from. Default: the global `document`. Ignored when `root` is set. */
+  document?: Document;
+  /**
+   * Scope extraction to this element's subtree instead of the whole document — parity
+   * with `collectEnrichedPageContext`'s `root`. Useful to read only a main-content region
+   * and skip site chrome (nav, sidebars). Shadow DOM inside the subtree is still pierced.
+   * When set, `document` is ignored.
+   */
+  root?: Element;
+}
+
+/**
+ * Collect enriched page context using smart-dom-reader, mapped into Persona's
+ * {@link EnrichedPageElement}[] shape (parity with `collectEnrichedPageContext`).
+ *
+ * Pass `root` to scope extraction to an element subtree (skipping site chrome);
+ * otherwise the whole `document` (or `opts.document`) is read. Returns an empty array
+ * when neither `root` nor a document is available (e.g. SSR).
+ */
+export function collectSmartDomContext(
+  opts: SmartDomContextOptions = {}
+): EnrichedPageElement[] {
+  const mode = opts.mode ?? "interactive";
+
+  let result;
+  if (opts.root) {
+    result = SmartDOMReader.extractFromElement(
+      opts.root,
+      mode,
+      opts.extractionOptions
+    );
+  } else {
+    const doc =
+      opts.document ?? (typeof document !== "undefined" ? document : undefined);
+    if (!doc) return [];
+    result =
+      mode === "full"
+        ? SmartDOMReader.extractFull(doc, opts.extractionOptions)
+        : SmartDOMReader.extractInteractive(doc, opts.extractionOptions);
+  }
+
+  return smartDomResultToEnriched(result, {
+    includeSemantic: opts.includeSemantic ?? mode === "full",
+    excludeSelector: opts.excludeSelector,
+    maxTextLength: opts.maxTextLength,
+    maxElements: opts.maxElements
+  });
+}
+
+/** Options for {@link createSmartDomReaderContextProvider}. */
+export interface SmartDomReaderProviderOptions extends SmartDomContextOptions {
+  /** Key under which the formatted context is placed in `payload.context`. Default: "pageContext". */
+  contextKey?: string;
+}
+
+/**
+ * Build an {@link AgentWidgetContextProvider} that collects page context with
+ * smart-dom-reader and returns it under `contextKey` (default `"pageContext"`).
+ * Drop into `config.contextProviders`; `buildAgentPayload` merges the result into
+ * `payload.context` on every agent request.
+ */
+export function createSmartDomReaderContextProvider(
+  opts: SmartDomReaderProviderOptions = {}
+): AgentWidgetContextProvider {
+  const contextKey = opts.contextKey ?? "pageContext";
+  return () => {
+    const elements = collectSmartDomContext(opts);
+    if (elements.length === 0) return {};
+    return { [contextKey]: formatEnrichedContext(elements) };
+  };
+}

package/src/theme-editor/color-utils.test.ts

@@ -0,0 +1,59 @@
+import { describe, it, expect } from 'vitest';
+import {
+  rgbToHex,
+  hexToHsl,
+  generateColorScale,
+  wcagContrastRatio,
+  SHADE_KEYS,
+} from './color-utils';
+
+describe('rgbToHex', () => {
+  it('parses integer rgb()', () => {
+    expect(rgbToHex('rgb(255, 0, 0)')).toBe('#ff0000');
+    expect(rgbToHex('rgb(37, 99, 235)')).toBe('#2563eb');
+  });
+
+  it('drops the alpha channel from rgba()', () => {
+    expect(rgbToHex('rgba(0, 128, 0, 0.5)')).toBe('#008000');
+  });
+
+  it('parses percentage channels and clamps out-of-range values', () => {
+    expect(rgbToHex('rgb(100%, 0%, 0%)')).toBe('#ff0000');
+    expect(rgbToHex('rgb(300, -20, 0)')).toBe('#ff0000');
+  });
+
+  it('returns null for non-rgb input', () => {
+    expect(rgbToHex('#2563eb')).toBeNull();
+    expect(rgbToHex('blue')).toBeNull();
+    expect(rgbToHex('rgb(1, 2)')).toBeNull();
+  });
+});
+
+describe('hexToHsl with rgb() input', () => {
+  it('produces the same HSL as the equivalent hex', () => {
+    const fromRgb = hexToHsl('rgb(37, 99, 235)');
+    const fromHex = hexToHsl('#2563eb');
+    expect(fromRgb.h).toBeCloseTo(fromHex.h, 5);
+    expect(fromRgb.s).toBeCloseTo(fromHex.s, 5);
+    expect(fromRgb.l).toBeCloseTo(fromHex.l, 5);
+  });
+});
+
+describe('generateColorScale with rgb() input', () => {
+  it('does not emit NaN shades for rgb() base colors', () => {
+    const scale = generateColorScale('rgb(255, 0, 0)');
+    for (const shade of SHADE_KEYS) {
+      expect(scale[shade]).toMatch(/^#[0-9a-f]{6}$/);
+      expect(scale[shade]).not.toContain('NaN');
+    }
+  });
+});
+
+describe('wcagContrastRatio with rgb() input', () => {
+  it('matches the hex equivalent', () => {
+    expect(wcagContrastRatio('rgb(255, 255, 255)', 'rgb(0, 0, 0)')).toBeCloseTo(
+      wcagContrastRatio('#ffffff', '#000000'),
+      5
+    );
+  });
+});

package/src/theme-editor/color-utils.ts

@@ -64,6 +64,36 @@ export function isValidHex(value: string): boolean {
   return /^#[0-9A-Fa-f]{6}$/.test(value);
 }
 
+/**
+ * Parse an `rgb()` / `rgba()` string into `#rrggbb`. Accepts integer (0-255) or
+ * percentage channels; any alpha component is dropped. Returns `null` when the
+ * string is not a parseable rgb/rgba value, so callers can fall back. This lets
+ * the HSL/luminance paths — which otherwise `parseInt` hex digits — accept the
+ * `rgb()` inputs that `coerceColor` admits without producing `#NaNNaNNaN`.
+ */
+export function rgbToHex(value: string): string | null {
+  const match = value.trim().toLowerCase().match(/^rgba?\(([^)]+)\)$/);
+  if (!match) return null;
+
+  const parts = match[1].split(',').map((p) => p.trim());
+  if (parts.length < 3) return null;
+
+  const channel = (raw: string): number => {
+    const isPct = raw.endsWith('%');
+    const n = parseFloat(isPct ? raw.slice(0, -1) : raw);
+    if (!Number.isFinite(n)) return NaN;
+    return Math.max(0, Math.min(255, Math.round(isPct ? (n / 100) * 255 : n)));
+  };
+
+  const r = channel(parts[0]);
+  const g = channel(parts[1]);
+  const b = channel(parts[2]);
+  if (!Number.isFinite(r) || !Number.isFinite(g) || !Number.isFinite(b)) return null;
+
+  const toHex = (n: number) => n.toString(16).padStart(2, '0');
+  return `#${toHex(r)}${toHex(g)}${toHex(b)}`;
+}
+
 // ─── WCAG Contrast ──────────────────────────────────────────────
 
 /**
@@ -72,7 +102,8 @@ export function isValidHex(value: string): boolean {
  */
 export function wcagContrastRatio(hex1: string, hex2: string): number {
   const luminance = (hex: string): number => {
-    const norm = normalizeColorValue(hex);
+    const normalized = normalizeColorValue(hex);
+    const norm = normalized.startsWith('rgb') ? rgbToHex(normalized) ?? '#000000' : normalized;
     const channels = [1, 3, 5].map((i) => {
       const v = parseInt(norm.slice(i, i + 2), 16) / 255;
       return v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4);
@@ -87,7 +118,12 @@ export function wcagContrastRatio(hex1: string, hex2: string): number {
 // ─── HSL Conversion ─────────────────────────────────────────────
 
 export function hexToHsl(hex: string): { h: number; s: number; l: number } {
-  const normalized = normalizeColorValue(hex);
+  const normalizedValue = normalizeColorValue(hex);
+  // `rgb()`/`rgba()` is valid color input (see coerceColor) but can't be sliced
+  // as hex digits; convert it first so the scale isn't built from NaN channels.
+  const normalized = normalizedValue.startsWith('rgb')
+    ? rgbToHex(normalizedValue) ?? '#000000'
+    : normalizedValue;
   const r = parseInt(normalized.slice(1, 3), 16) / 255;
   const g = parseInt(normalized.slice(3, 5), 16) / 255;
   const b = parseInt(normalized.slice(5, 7), 16) / 255;

package/src/theme-editor/index.ts

@@ -128,6 +128,7 @@ export {
   convertFromPx,
   normalizeColorValue,
   isValidHex,
+  rgbToHex,
   wcagContrastRatio,
   hexToHsl,
   hslToHex,
@@ -138,3 +139,37 @@ export {
   resolveThemeColorPath,
   tokenRefDisplayName,
 } from './color-utils';
+
+// WebMCP tools (transport-agnostic factory for agent-driven theming)
+export {
+  createThemeEditorTools,
+  toolResult,
+  buildSummary,
+  runContrastChecks,
+  quickContrastWarnings,
+  CONTRAST_PAIRS,
+  RADIUS_PRESETS,
+  coerceColor,
+  coerceFamily,
+  coerceIntensity,
+  coerceScheme,
+  coerceRoundnessStyle,
+  coerceRadius,
+  CSS_NAMED_COLORS,
+} from './webmcp';
+export type {
+  WebMcpTool,
+  ToolResult,
+  ToolAnnotations,
+  ToolTextContent,
+  ToolExecute,
+  ThemeEditorLike,
+  EditTarget,
+  CreateThemeEditorToolsOptions,
+  ThemeSummary,
+  RoleState,
+  ContrastReport,
+  ContrastCheck,
+  ContrastWarning,
+  ContrastLevel,
+} from './webmcp';

package/src/theme-editor/webmcp/coerce.test.ts

@@ -0,0 +1,86 @@
+import { describe, it, expect } from 'vitest';
+import {
+  coerceColor,
+  coerceFamily,
+  coerceIntensity,
+  coerceScheme,
+  coerceRoundnessStyle,
+  coerceRadius,
+  coerceTypographyRef,
+  FONT_WEIGHT_REFS,
+} from './coerce';
+
+describe('coerceColor', () => {
+  it('normalizes bare and short hex', () => {
+    expect(coerceColor('2563eb')).toBe('#2563eb');
+    expect(coerceColor('#18f')).toBe('#1188ff');
+    expect(coerceColor('#2563EB')).toBe('#2563eb');
+  });
+
+  it('maps CSS color names', () => {
+    expect(coerceColor('blue')).toBe('#0000ff');
+    expect(coerceColor('SlateBlue')).toBe('#6a5acd');
+  });
+
+  it('passes through valid rgb/rgba and transparent', () => {
+    expect(coerceColor('transparent')).toBe('transparent');
+    expect(coerceColor('rgb(1, 2, 3)')).toBe('rgb(1, 2, 3)');
+    expect(coerceColor('rgba(1,2,3,0.5)')).toBe('rgba(1,2,3,0.5)');
+  });
+
+  it('rejects malformed rgb-prefixed garbage', () => {
+    expect(() => coerceColor('rgbfoo')).toThrow(/not a recognized color/);
+    expect(() => coerceColor('rgba(')).toThrow(/not a recognized color/);
+  });
+
+  it('throws with guidance on garbage', () => {
+    expect(() => coerceColor('notacolor')).toThrow(/not a recognized color/);
+    expect(() => coerceColor('')).toThrow();
+  });
+});
+
+describe('enum coercion', () => {
+  it('coerces families with neutral synonyms', () => {
+    expect(coerceFamily('gray')).toBe('neutral');
+    expect(coerceFamily('Primary')).toBe('primary');
+    expect(() => coerceFamily('neutral', false)).toThrow(/Valid families/);
+  });
+
+  it('coerces intensity defaulting to solid', () => {
+    expect(coerceIntensity(undefined)).toBe('solid');
+    expect(coerceIntensity('SOFT')).toBe('soft');
+    expect(() => coerceIntensity('bright')).toThrow();
+  });
+
+  it('coerces scheme with system → auto', () => {
+    expect(coerceScheme('system')).toBe('auto');
+    expect(coerceScheme('Dark')).toBe('dark');
+  });
+
+  it('coerces roundness synonyms', () => {
+    expect(coerceRoundnessStyle('square')).toBe('sharp');
+    expect(coerceRoundnessStyle('circle')).toBe('pill');
+    expect(coerceRoundnessStyle('round')).toBe('rounded');
+  });
+});
+
+describe('coerceRadius', () => {
+  it('turns numbers into px', () => {
+    expect(coerceRadius(8)).toBe('8px');
+  });
+  it('normalizes css strings', () => {
+    expect(coerceRadius('0.5rem')).toBe('0.5rem');
+    expect(coerceRadius('9999px')).toBe('9999px');
+  });
+});
+
+describe('coerceTypographyRef', () => {
+  it('maps numeric weights to token refs', () => {
+    expect(coerceTypographyRef(600, FONT_WEIGHT_REFS, 'fontWeight')).toBe(
+      'palette.typography.fontWeight.semibold'
+    );
+  });
+  it('throws on unknown', () => {
+    expect(() => coerceTypographyRef('chunky', FONT_WEIGHT_REFS, 'fontWeight')).toThrow();
+  });
+});