@treelocator/runtime 0.4.7 → 0.6.0

package/src/browserApi.ts

@@ -3,11 +3,33 @@ import { createTreeNode } from "./adapters/createTreeNode";
 import {
   collectAncestry,
   formatAncestryChain,
+  getElementLabel,
   AncestryItem,
 } from "./functions/formatAncestryChain";
 import { enrichAncestryWithSourceMaps } from "./functions/enrichAncestrySourceMaps";
+import {
+  inspectCSSRules,
+  formatCSSInspection,
+  CSSInspectionResult,
+} from "./functions/cssRuleInspector";
+import {
+  extractComputedStyles,
+  ComputedStylesResult,
+  ExtractOptions,
+} from "./functions/extractComputedStyles";
+import {
+  takeNamedSnapshot,
+  getNamedSnapshotDiff,
+  clearNamedSnapshot,
+  TakeSnapshotResult,
+  SnapshotDiffResult,
+} from "./functions/namedSnapshots";
 import type { DejitterFinding, DejitterSummary } from "./dejitter/recorder";
 import type { InteractionEvent } from "./components/RecordingResults";
+import { takeSnapshot } from "./visualDiff/snapshot";
+import { computeDiff, formatReport } from "./visualDiff/diff";
+import { waitForSettle } from "./visualDiff/settle";
+import type { DeltaReport, ElementSnapshot } from "./visualDiff/types";
 
 export interface LocatorJSAPI {
   /**
@@ -93,6 +115,40 @@ export interface LocatorJSAPI {
     elementOrSelector: HTMLElement | string
   ): Promise<{ 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.
@@ -110,6 +166,98 @@ export interface LocatorJSAPI {
    */
   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.
@@ -155,14 +303,59 @@ 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>;
+  };
 }
 
 function resolveElement(
   elementOrSelector: HTMLElement | string
 ): HTMLElement | null {
   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: Element | null = null;
+    try {
+      element = document.querySelector(elementOrSelector);
+    } catch {
+      return null;
+    }
     return element instanceof HTMLElement ? element : null;
   }
   return elementOrSelector;
@@ -227,13 +420,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.
 
@@ -242,7 +474,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:
@@ -267,6 +509,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:
 ------------------
 
@@ -338,6 +593,74 @@ export function createBrowserAPI(
       );
     },
 
+    getStyles(
+      elementOrSelector: HTMLElement | string,
+      options?: ExtractOptions
+    ): ComputedStylesResult | null {
+      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: HTMLElement | string
+    ): CSSInspectionResult | null {
+      let element: HTMLElement | null = null;
+      try {
+        element = resolveElement(elementOrSelector);
+      } catch {
+        return null;
+      }
+      if (!element) return null;
+      return inspectCSSRules(element);
+    },
+
+    getCSSReport(
+      elementOrSelector: HTMLElement | string,
+      options?: { properties?: string[] }
+    ): string | null {
+      let element: HTMLElement | null = 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: string,
+      snapshotId: string,
+      options?: { index?: number; label?: string }
+    ): TakeSnapshotResult {
+      return takeNamedSnapshot(selector, snapshotId, options);
+    },
+
+    getSnapshotDiff(snapshotId: string): SnapshotDiffResult {
+      return getNamedSnapshotDiff(snapshotId);
+    },
+
+    clearSnapshot(snapshotId: string): void {
+      clearNamedSnapshot(snapshotId);
+    },
+
     help(): string {
       return HELP_TEXT;
     },
@@ -350,6 +673,30 @@ export function createBrowserAPI(
       // 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;
+      },
+    },
   };
 }