@treelocator/runtime 0.5.2 → 0.6.0

package/dist/browserApi.d.ts

@@ -1,7 +1,11 @@
 import { AdapterId } from "./consts";
 import { AncestryItem } from "./functions/formatAncestryChain";
+import { CSSInspectionResult } from "./functions/cssRuleInspector";
+import { ComputedStylesResult, ExtractOptions } from "./functions/extractComputedStyles";
+import { TakeSnapshotResult, SnapshotDiffResult } from "./functions/namedSnapshots";
 import type { DejitterFinding, DejitterSummary } from "./dejitter/recorder";
 import type { InteractionEvent } from "./components/RecordingResults";
+import type { DeltaReport, ElementSnapshot } from "./visualDiff/types";
 export interface LocatorJSAPI {
     /**
      * Get formatted ancestry path for an element.
@@ -84,6 +88,36 @@ export interface LocatorJSAPI {
         path: string;
         ancestry: AncestryItem[];
     } | null>;
+    /**
+     * Get computed styles for an element, formatted for AI consumption.
+     * Extracts layout, visual, typography, and interaction styles filtered against browser defaults.
+     * Clicking the same element twice within 30s returns a diff of changed properties.
+     *
+     * @param elementOrSelector - HTMLElement or CSS selector string
+     * @param options - Optional flags like { includeDefaults: true } for a fuller dump
+     * @returns Object with formatted string and raw snapshot, or null if element not found
+     *
+     * @example
+     * // Get formatted computed styles
+     * const result = window.__treelocator__.getStyles('button.submit');
+     * console.log(result.formatted);
+     * // [ComputedStyles] Button at src/Button.tsx:23
+     * // ─────────────────────────────────────────
+     * // Layout
+     * //   display: flex
+     * //   padding: 8px 16px
+     * // ...
+     *
+     * @example
+     * // In Playwright
+     * const styles = await page.evaluate(() => {
+     *   return window.__treelocator__.getStyles('.my-element', {
+     *     includeDefaults: true,
+     *   });
+     * });
+     * console.log(styles?.formatted);
+     */
+    getStyles(elementOrSelector: HTMLElement | string, options?: ExtractOptions): ComputedStylesResult | null;
     /**
      * Display help information about the LocatorJS API.
      * Shows usage examples and method descriptions for browser automation tools.
@@ -100,6 +134,89 @@ export interface LocatorJSAPI {
      * console.log(help);
      */
     help(): string;
+    /**
+     * Inspect all CSS rules matching an element, grouped by property.
+     * Shows which rule wins for each property with specificity, source, and !important info.
+     * Returns structured data for programmatic use.
+     *
+     * @param elementOrSelector - HTMLElement or CSS selector string
+     * @returns Structured CSS inspection result, or null if element not found
+     *
+     * @example
+     * // Get structured CSS data
+     * const result = window.__treelocator__.getCSSRules('button.primary');
+     * result.properties.forEach(p => {
+     *   console.log(`${p.property}: ${p.value}`);
+     *   p.rules.forEach(r => console.log(`  ${r.winning ? '✓' : '✗'} ${r.selector}`));
+     * });
+     *
+     * @example
+     * // In Playwright - debug why a style isn't applying
+     * const css = await page.evaluate(() =>
+     *   window.__treelocator__.getCSSRules('.my-button')
+     * );
+     * const colorRules = css?.properties.find(p => p.property === 'color');
+     * console.log(colorRules);
+     */
+    getCSSRules(elementOrSelector: HTMLElement | string): CSSInspectionResult | null;
+    /**
+     * Get a formatted human-readable report of all CSS rules matching an element.
+     * Shows winning/losing rules per property with specificity and source info.
+     * Ideal for pasting into AI chat or logging.
+     *
+     * @param elementOrSelector - HTMLElement or CSS selector string
+     * @param options - Optional filter: { properties?: string[] } to limit output to specific properties
+     * @returns Formatted string report, or null if element not found
+     *
+     * @example
+     * // Get full CSS report
+     * console.log(window.__treelocator__.getCSSReport('button.primary'));
+     * // Output:
+     * // CSS Rules for button.primary
+     * // ════════════════════════════
+     * //
+     * // color: #333
+     * //   ✓ .button.primary  (0,2,0) — components.css
+     * //   ✗ .button          (0,1,0) — base.css
+     * //   ✗ button           (0,0,1) — reset.css
+     *
+     * @example
+     * // Filter to specific properties
+     * console.log(window.__treelocator__.getCSSReport('.card', { properties: ['color', 'background'] }));
+     *
+     * @example
+     * // In Playwright
+     * const report = await page.evaluate(() =>
+     *   window.__treelocator__.getCSSReport('.error-message')
+     * );
+     * console.log(report);
+     */
+    getCSSReport(elementOrSelector: HTMLElement | string, options?: {
+        properties?: string[];
+    }): string | null;
+    /**
+     * Capture a baseline snapshot of an element's computed styles and persist
+     * it in localStorage under `snapshotId`. The baseline survives page reloads
+     * and is never mutated until you call `takeSnapshot` again with the same id.
+     *
+     * @param selector - CSS selector for the element to snapshot
+     * @param snapshotId - caller-chosen id used to retrieve the diff later
+     * @param options - optional `{ index, label }` (index picks among matches)
+     */
+    takeSnapshot(selector: string, snapshotId: string, options?: {
+        index?: number;
+        label?: string;
+    }): TakeSnapshotResult;
+    /**
+     * Diff the current computed styles of the element against the baseline
+     * stored under `snapshotId`. Does not overwrite the baseline — safe to call
+     * repeatedly while iterating on a change.
+     */
+    getSnapshotDiff(snapshotId: string): SnapshotDiffResult;
+    /**
+     * Remove a stored baseline snapshot.
+     */
+    clearSnapshot(snapshotId: string): void;
     /**
      * Replay the last recorded interaction sequence.
      * Dispatches the recorded clicks at the original positions and timing.
@@ -142,7 +259,38 @@ export interface LocatorJSAPI {
         summary: DejitterSummary | null;
         data: any;
         interactions: InteractionEvent[];
+        visualDiff: DeltaReport | null;
     } | null>;
+    /**
+     * Visual diff engine — snapshot page state before/after an action and return
+     * a compact delta report.
+     *
+     * @example
+     * // In browser console or Playwright
+     * const report = await window.__treelocator__.diff.captureDiff(() => {
+     *   document.querySelector('button.submit')?.click();
+     * });
+     * console.log(report.text);
+     */
+    diff: {
+        /**
+         * Capture a snapshot of all visible viewport elements right now.
+         * Pure — no side effects on the page.
+         */
+        snapshot(): ElementSnapshot[];
+        /**
+         * Compute the delta between two snapshots.
+         */
+        computeDiff(before: ElementSnapshot[], after: ElementSnapshot[]): DeltaReport;
+        /**
+         * Take a before-snapshot, run the action, wait for the page to settle
+         * (animations idle + mutations silent for 150ms), take an after-snapshot,
+         * and return the computed delta.
+         */
+        captureDiff(action: () => void | Promise<void>, opts?: {
+            settleTimeoutMs?: number;
+        }): Promise<DeltaReport>;
+    };
 }
 export declare function createBrowserAPI(adapterId?: AdapterId): LocatorJSAPI;
 export declare function installBrowserAPI(adapterIdParam?: AdapterId): void;

package/dist/browserApi.js

@@ -1,9 +1,22 @@
 import { createTreeNode } from "./adapters/createTreeNode";
-import { collectAncestry, formatAncestryChain } from "./functions/formatAncestryChain";
+import { collectAncestry, formatAncestryChain, getElementLabel } from "./functions/formatAncestryChain";
 import { enrichAncestryWithSourceMaps } from "./functions/enrichAncestrySourceMaps";
+import { inspectCSSRules, formatCSSInspection } from "./functions/cssRuleInspector";
+import { extractComputedStyles } from "./functions/extractComputedStyles";
+import { takeNamedSnapshot, getNamedSnapshotDiff, clearNamedSnapshot } from "./functions/namedSnapshots";
+import { takeSnapshot } from "./visualDiff/snapshot";
+import { computeDiff, formatReport } from "./visualDiff/diff";
+import { waitForSettle } from "./visualDiff/settle";
 function resolveElement(elementOrSelector) {
   if (typeof elementOrSelector === "string") {
-    const element = document.querySelector(elementOrSelector);
+    // querySelector throws DOMException for invalid selector strings
+    // (e.g. "!!!") — return null instead of crashing the API call.
+    let element = null;
+    try {
+      element = document.querySelector(elementOrSelector);
+    } catch {
+      return null;
+    }
     return element instanceof HTMLElement ? element : null;
   }
   return elementOrSelector;
@@ -62,13 +75,52 @@ METHODS:
      console.log(data.path)      // formatted string
      console.log(data.ancestry)  // structured array
 
-4. replay()
+4. getStyles(elementOrSelector, options?)
+   Returns computed styles for an element, optimized for AI consumption.
+   Filters out browser defaults and groups by category (Layout, Visual, Typography).
+   Pass { includeDefaults: true } for a fuller dump closer to DevTools.
+   Calling twice on the same element within 30s returns a diff of changes.
+
+   Usage:
+     const result = window.__treelocator__.getStyles('button.submit')
+     console.log(result.formatted)  // formatted styles string
+     console.log(result.snapshot)   // raw property values + bounding rect
+     const full = window.__treelocator__.getStyles('h1', { includeDefaults: true })
+
+5. getCSSRules(elementOrSelector)
+   Returns structured CSS rule data for the element.
+   Shows all matching rules grouped by property with specificity and source.
+
+   Usage:
+     const result = window.__treelocator__.getCSSRules('button.primary')
+     result.properties.forEach(p => {
+       console.log(p.property + ': ' + p.value)
+       p.rules.forEach(r => console.log('  ' + (r.winning ? 'WIN' : '   ') + ' ' + r.selector))
+     })
+
+6. getCSSReport(elementOrSelector, options?)
+   Returns a formatted string showing all CSS rules and which wins per property.
+   Pass { properties: ['color', 'font-size'] } to filter to specific properties.
+
+   Usage:
+     console.log(window.__treelocator__.getCSSReport('button.primary'))
+     console.log(window.__treelocator__.getCSSReport('.card', { properties: ['color'] }))
+
+   Returns:
+     "CSS Rules for button.primary
+      ════════════════════════════
+      color: #333
+        ✓ .button.primary  (0,2,0) — components.css
+        ✗ .button          (0,1,0) — base.css
+        ✗ button           (0,0,1) — reset.css"
+
+7. replay()
    Replays the last recorded interaction sequence as a macro.
 
    Usage:
      window.__treelocator__.replay()
 
-5. replayWithRecord(elementOrSelector)
+8. replayWithRecord(elementOrSelector)
    Replays stored interactions while recording element changes.
    Returns dejitter analysis when replay completes.
 
@@ -77,7 +129,17 @@ METHODS:
      console.log(results.findings)  // anomaly analysis
      console.log(results.path)      // component ancestry
 
-6. help()
+9. diff.snapshot() / diff.computeDiff(before, after) / diff.captureDiff(action)
+   Visual diff engine. Captures viewport element state and returns a compact
+   delta showing what appeared, disappeared, moved, or changed.
+
+   Usage:
+     const report = await window.__treelocator__.diff.captureDiff(() => {
+       document.querySelector('button.submit').click();
+     });
+     console.log(report.text);
+
+10. help()
    Displays this help message.
 
 PLAYWRIGHT EXAMPLES:
@@ -102,6 +164,19 @@ async function getComponentPath(page, selector) {
   }, selector);
 }
 
+// Debug CSS specificity conflicts
+const report = await page.evaluate(() => {
+  return window.__treelocator__.getCSSReport('.my-button', { properties: ['color', 'background'] });
+});
+console.log(report);
+
+// Get structured CSS data for assertions
+const css = await page.evaluate(() => {
+  return window.__treelocator__.getCSSRules('.my-button');
+});
+const colorRules = css?.properties.find(p => p.property === 'color');
+console.log('Winning rule:', colorRules?.rules.find(r => r.winning));
+
 PUPPETEER EXAMPLES:
 ------------------
 
@@ -159,6 +234,49 @@ export function createBrowserAPI(adapterId) {
         ancestry
       } : null);
     },
+    getStyles(elementOrSelector, options) {
+      const element = resolveElement(elementOrSelector);
+      if (!element) return null;
+      const ancestry = getAncestryForElement(element, adapterId);
+      const label = ancestry ? getElementLabel(ancestry) : undefined;
+      return extractComputedStyles(element, label || undefined, options);
+    },
+    getCSSRules(elementOrSelector) {
+      let element = null;
+      try {
+        element = resolveElement(elementOrSelector);
+      } catch {
+        return null;
+      }
+      if (!element) return null;
+      return inspectCSSRules(element);
+    },
+    getCSSReport(elementOrSelector, options) {
+      let element = null;
+      try {
+        element = resolveElement(elementOrSelector);
+      } catch {
+        return null;
+      }
+      if (!element) return null;
+      const result = inspectCSSRules(element);
+
+      // Filter to requested properties if specified
+      if (options?.properties && options.properties.length > 0) {
+        const filterSet = new Set(options.properties.map(p => p.toLowerCase()));
+        result.properties = result.properties.filter(p => filterSet.has(p.property.toLowerCase()));
+      }
+      return formatCSSInspection(result);
+    },
+    takeSnapshot(selector, snapshotId, options) {
+      return takeNamedSnapshot(selector, snapshotId, options);
+    },
+    getSnapshotDiff(snapshotId) {
+      return getNamedSnapshotDiff(snapshotId);
+    },
+    clearSnapshot(snapshotId) {
+      clearNamedSnapshot(snapshotId);
+    },
     help() {
       return HELP_TEXT;
     },
@@ -168,6 +286,29 @@ export function createBrowserAPI(adapterId) {
     replayWithRecord() {
       // Replaced by Runtime component once mounted
       return Promise.resolve(null);
+    },
+    diff: {
+      snapshot() {
+        return takeSnapshot();
+      },
+      computeDiff(before, after) {
+        return computeDiff(before, after);
+      },
+      async captureDiff(action, opts) {
+        const started = performance.now();
+        const before = takeSnapshot();
+        await action();
+        const settle = await waitForSettle(opts?.settleTimeoutMs);
+        const after = takeSnapshot();
+        const report = computeDiff(before, after);
+        report.elapsedMs = performance.now() - started;
+        report.settle = settle;
+        report.text = formatReport(report.entries, {
+          elapsedMs: report.elapsedMs,
+          settle
+        });
+        return report;
+      }
     }
   };
 }

package/dist/browserApi.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/browserApi.test.js

@@ -0,0 +1,287 @@
+import { describe, expect, test, vi, beforeEach, afterEach } from "vitest";
+import { createBrowserAPI, installBrowserAPI } from "./browserApi";
+
+// Mock the heavy dependencies
+vi.mock("./adapters/createTreeNode", () => ({
+  createTreeNode: vi.fn()
+}));
+vi.mock("./functions/enrichAncestrySourceMaps", () => ({
+  enrichAncestryWithSourceMaps: vi.fn()
+}));
+import { createTreeNode } from "./adapters/createTreeNode";
+import { enrichAncestryWithSourceMaps } from "./functions/enrichAncestrySourceMaps";
+describe("browserApi", () => {
+  beforeEach(() => {
+    // Reset window.__treelocator__ before each test
+    delete window.__treelocator__;
+  });
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+  describe("createBrowserAPI", () => {
+    test("returns an object with all expected method names", () => {
+      const api = createBrowserAPI();
+      expect(api).toHaveProperty("getPath");
+      expect(api).toHaveProperty("getAncestry");
+      expect(api).toHaveProperty("getPathData");
+      expect(api).toHaveProperty("help");
+      expect(api).toHaveProperty("replay");
+      expect(api).toHaveProperty("replayWithRecord");
+      expect(api).toHaveProperty("diff");
+    });
+    test("all methods are functions", () => {
+      const api = createBrowserAPI();
+      expect(typeof api.getPath).toBe("function");
+      expect(typeof api.getAncestry).toBe("function");
+      expect(typeof api.getPathData).toBe("function");
+      expect(typeof api.help).toBe("function");
+      expect(typeof api.replay).toBe("function");
+      expect(typeof api.replayWithRecord).toBe("function");
+      expect(typeof api.diff.snapshot).toBe("function");
+      expect(typeof api.diff.computeDiff).toBe("function");
+      expect(typeof api.diff.captureDiff).toBe("function");
+    });
+  });
+  describe("diff namespace", () => {
+    beforeEach(() => {
+      if (typeof document.getAnimations !== "function") {
+        document.getAnimations = () => [];
+      }
+    });
+    test("snapshot() returns an array", () => {
+      const api = createBrowserAPI();
+      const snaps = api.diff.snapshot();
+      expect(Array.isArray(snaps)).toBe(true);
+    });
+    test("computeDiff of identical snapshots has empty entries", () => {
+      const api = createBrowserAPI();
+      const snaps = api.diff.snapshot();
+      const report = api.diff.computeDiff(snaps, snaps);
+      expect(report.entries).toHaveLength(0);
+      expect(report.counts.added).toBe(0);
+    });
+    test("captureDiff returns a DeltaReport with settle and text populated", async () => {
+      const api = createBrowserAPI();
+      const report = await api.diff.captureDiff(() => {
+        // no-op action
+      }, {
+        settleTimeoutMs: 200
+      });
+      expect(report).toHaveProperty("entries");
+      expect(report).toHaveProperty("counts");
+      expect(report).toHaveProperty("text");
+      expect(typeof report.text).toBe("string");
+      expect(["clean", "timeout"]).toContain(report.settle);
+    });
+  });
+  describe("help()", () => {
+    test("returns a non-empty string", () => {
+      const api = createBrowserAPI();
+      const help = api.help();
+      expect(typeof help).toBe("string");
+      expect(help.length).toBeGreaterThan(0);
+    });
+    test("help text contains 'TreeLocatorJS'", () => {
+      const api = createBrowserAPI();
+      const help = api.help();
+      expect(help).toContain("TreeLocatorJS");
+    });
+    test("help text contains method descriptions", () => {
+      const api = createBrowserAPI();
+      const help = api.help();
+      expect(help).toContain("getPath");
+      expect(help).toContain("getAncestry");
+      expect(help).toContain("getPathData");
+    });
+  });
+  describe("replay()", () => {
+    test("does not throw when called", () => {
+      const api = createBrowserAPI();
+      expect(() => api.replay()).not.toThrow();
+    });
+    test("is a stub that does nothing", () => {
+      const api = createBrowserAPI();
+      // Should not throw and should return undefined
+      const result = api.replay();
+      expect(result).toBeUndefined();
+    });
+  });
+  describe("replayWithRecord()", () => {
+    test("returns a Promise that resolves to null (stub)", async () => {
+      const api = createBrowserAPI();
+      const result = api.replayWithRecord("div");
+      expect(result).toBeInstanceOf(Promise);
+      const resolved = await result;
+      expect(resolved).toBeNull();
+    });
+    test("handles both element and selector arguments without error", async () => {
+      const api = createBrowserAPI();
+      const div = document.createElement("div");
+
+      // Test with selector
+      const result1 = api.replayWithRecord("div");
+      expect(await result1).toBeNull();
+
+      // Test with element
+      const result2 = api.replayWithRecord(div);
+      expect(await result2).toBeNull();
+    });
+  });
+  describe("getPath()", () => {
+    test("returns Promise<string | null>", async () => {
+      const api = createBrowserAPI();
+      const result = api.getPath(document.body);
+      expect(result).toBeInstanceOf(Promise);
+      const resolved = await result;
+      expect(typeof resolved === "string" || resolved === null).toBe(true);
+    });
+    test("returns null when selector doesn't match any element", async () => {
+      const api = createBrowserAPI();
+      const result = await api.getPath(".non-existent-selector-xyz");
+      expect(result).toBeNull();
+    });
+    test("returns null when passed invalid selector string", async () => {
+      const api = createBrowserAPI();
+      // querySelector with invalid selector will throw; the function should handle it
+      const result = await api.getPath("div > > div");
+      expect(result).toBeNull();
+    });
+    test("returns null when createTreeNode returns null", async () => {
+      const mockCreateTreeNode = createTreeNode;
+      const mockEnrich = enrichAncestryWithSourceMaps;
+      mockCreateTreeNode.mockReturnValue(null);
+      mockEnrich.mockResolvedValue(null);
+      const api = createBrowserAPI();
+      const div = document.createElement("div");
+      const result = await api.getPath(div);
+      expect(result).toBeNull();
+    });
+  });
+  describe("getAncestry()", () => {
+    test("returns Promise<AncestryItem[] | null>", async () => {
+      const api = createBrowserAPI();
+      const result = api.getAncestry(document.body);
+      expect(result).toBeInstanceOf(Promise);
+      const resolved = await result;
+      expect(Array.isArray(resolved) || resolved === null).toBe(true);
+    });
+    test("returns null when selector doesn't match any element", async () => {
+      const api = createBrowserAPI();
+      const result = await api.getAncestry(".non-existent-selector-xyz");
+      expect(result).toBeNull();
+    });
+    test("returns null when createTreeNode returns null", async () => {
+      const mockCreateTreeNode = createTreeNode;
+      const mockEnrich = enrichAncestryWithSourceMaps;
+      mockCreateTreeNode.mockReturnValue(null);
+      mockEnrich.mockResolvedValue(null);
+      const api = createBrowserAPI();
+      const div = document.createElement("div");
+      const result = await api.getAncestry(div);
+      expect(result).toBeNull();
+    });
+  });
+  describe("getPathData()", () => {
+    test("returns Promise with path and ancestry properties or null", async () => {
+      const api = createBrowserAPI();
+      const result = api.getPathData(document.body);
+      expect(result).toBeInstanceOf(Promise);
+      const resolved = await result;
+      if (resolved !== null) {
+        expect(resolved).toHaveProperty("path");
+        expect(resolved).toHaveProperty("ancestry");
+      }
+    });
+    test("returns null when selector doesn't match any element", async () => {
+      const api = createBrowserAPI();
+      const result = await api.getPathData(".non-existent-selector-xyz");
+      expect(result).toBeNull();
+    });
+    test("returns null when createTreeNode returns null", async () => {
+      const mockCreateTreeNode = createTreeNode;
+      const mockEnrich = enrichAncestryWithSourceMaps;
+      mockCreateTreeNode.mockReturnValue(null);
+      mockEnrich.mockResolvedValue(null);
+      const api = createBrowserAPI();
+      const div = document.createElement("div");
+      const result = await api.getPathData(div);
+      expect(result).toBeNull();
+    });
+  });
+  describe("installBrowserAPI()", () => {
+    test("sets window.__treelocator__ to the created API object", () => {
+      expect(window.__treelocator__).toBeUndefined();
+      installBrowserAPI();
+      expect(window.__treelocator__).toBeDefined();
+      expect(typeof window.__treelocator__.getPath).toBe("function");
+    });
+    test("window.__treelocator__ has all expected methods after installation", () => {
+      installBrowserAPI();
+      const api = window.__treelocator__;
+      expect(api).toHaveProperty("getPath");
+      expect(api).toHaveProperty("getAncestry");
+      expect(api).toHaveProperty("getPathData");
+      expect(api).toHaveProperty("help");
+      expect(api).toHaveProperty("replay");
+      expect(api).toHaveProperty("replayWithRecord");
+      expect(api).toHaveProperty("diff");
+      expect(typeof api.diff.snapshot).toBe("function");
+    });
+    test("installBrowserAPI passes adapterId to createBrowserAPI", () => {
+      // We can't directly test this without spying on createBrowserAPI,
+      // but we can verify that the API is created with or without an adapterId
+      installBrowserAPI("react");
+      expect(window.__treelocator__).toBeDefined();
+      expect(typeof window.__treelocator__.help).toBe("function");
+    });
+  });
+  describe("API accepts HTMLElement or selector string", () => {
+    test("getPath accepts HTMLElement", async () => {
+      const api = createBrowserAPI();
+      const div = document.createElement("div");
+      document.body.appendChild(div);
+      const mockCreateTreeNode = createTreeNode;
+      const mockEnrich = enrichAncestryWithSourceMaps;
+      mockCreateTreeNode.mockReturnValue(null);
+      mockEnrich.mockResolvedValue(null);
+      const result = await api.getPath(div);
+      // With null ancestry, should return null
+      expect(result).toBeNull();
+      document.body.removeChild(div);
+    });
+    test("getPath accepts CSS selector string", async () => {
+      const api = createBrowserAPI();
+      const result = await api.getPath("body");
+      // Should not throw, result is either string or null
+      expect(typeof result === "string" || result === null).toBe(true);
+    });
+    test("getAncestry accepts HTMLElement", async () => {
+      const api = createBrowserAPI();
+      const div = document.createElement("div");
+      const result = await api.getAncestry(div);
+      expect(result === null || Array.isArray(result)).toBe(true);
+    });
+    test("getAncestry accepts CSS selector string", async () => {
+      const api = createBrowserAPI();
+      const result = await api.getAncestry("div");
+      expect(result === null || Array.isArray(result)).toBe(true);
+    });
+    test("getPathData accepts HTMLElement", async () => {
+      const api = createBrowserAPI();
+      const div = document.createElement("div");
+      const result = await api.getPathData(div);
+      if (result !== null) {
+        expect(result).toHaveProperty("path");
+        expect(result).toHaveProperty("ancestry");
+      }
+    });
+    test("getPathData accepts CSS selector string", async () => {
+      const api = createBrowserAPI();
+      const result = await api.getPathData("body");
+      if (result !== null) {
+        expect(result).toHaveProperty("path");
+        expect(result).toHaveProperty("ancestry");
+      }
+    });
+  });
+});

package/dist/components/RecordingPillButton.d.ts

@@ -0,0 +1,11 @@
+import type { RecordingState } from "../hooks/useRecordingState";
+type RecordingPillButtonProps = {
+    locatorActive: boolean;
+    recordingState: RecordingState;
+    settingsOpen: boolean;
+    onLocatorToggle: () => void;
+    onRecordClick: () => void;
+    onSettingsClick: () => void;
+};
+export declare function RecordingPillButton(props: RecordingPillButtonProps): import("solid-js").JSX.Element;
+export {};