@treelocator/runtime 0.5.2 → 0.6.0

package/dist/hooks/useLocatorStorage.test.js

@@ -0,0 +1,124 @@
+import { describe, expect, test, beforeAll, afterAll, beforeEach, vi } from "vitest";
+import { STORAGE_KEY, loadFromStorage, saveToStorage, clearStorage } from "./useLocatorStorage";
+const mockStorage = new Map();
+const mockLocalStorage = {
+  getItem(key) {
+    return mockStorage.has(key) ? mockStorage.get(key) : null;
+  },
+  setItem(key, value) {
+    mockStorage.set(key, String(value));
+  },
+  removeItem(key) {
+    mockStorage.delete(key);
+  },
+  clear() {
+    mockStorage.clear();
+  }
+};
+describe("useLocatorStorage", () => {
+  beforeAll(() => {
+    vi.stubGlobal("localStorage", mockLocalStorage);
+  });
+  afterAll(() => {
+    vi.unstubAllGlobals();
+  });
+  beforeEach(() => {
+    mockLocalStorage.clear();
+  });
+  describe("loadFromStorage", () => {
+    test("returns defaults when storage is empty", () => {
+      const result = loadFromStorage();
+      expect(result).toEqual({
+        last: null,
+        previous: null
+      });
+    });
+    test("returns parsed data from localStorage", () => {
+      const data = {
+        last: {
+          findings: [],
+          summary: null,
+          data: null,
+          elementPath: "div > button",
+          interactions: []
+        },
+        previous: null
+      };
+      localStorage.setItem(STORAGE_KEY, JSON.stringify(data));
+      const result = loadFromStorage();
+      expect(result).toEqual(data);
+    });
+    test("returns defaults on corrupt JSON", () => {
+      localStorage.setItem(STORAGE_KEY, "not-valid-json{{{");
+      const result = loadFromStorage();
+      expect(result).toEqual({
+        last: null,
+        previous: null
+      });
+    });
+  });
+  describe("saveToStorage", () => {
+    test("saves recording and shifts previous", () => {
+      const first = {
+        findings: [],
+        summary: null,
+        data: "first",
+        elementPath: "path1",
+        interactions: []
+      };
+      const second = {
+        findings: [],
+        summary: null,
+        data: "second",
+        elementPath: "path2",
+        interactions: []
+      };
+      saveToStorage(first);
+      let stored = JSON.parse(localStorage.getItem(STORAGE_KEY));
+      expect(stored.last.data).toBe("first");
+      expect(stored.previous).toBeNull();
+      saveToStorage(second);
+      stored = JSON.parse(localStorage.getItem(STORAGE_KEY));
+      expect(stored.last.data).toBe("second");
+      expect(stored.previous.data).toBe("first");
+    });
+  });
+  describe("clearStorage", () => {
+    test("removes the storage key", () => {
+      localStorage.setItem(STORAGE_KEY, "something");
+      clearStorage();
+      expect(localStorage.getItem(STORAGE_KEY)).toBeNull();
+    });
+    test("does not throw when key does not exist", () => {
+      expect(() => clearStorage()).not.toThrow();
+    });
+  });
+  describe("roundtrip", () => {
+    test("save then load returns correct data", () => {
+      const recording = {
+        findings: [{
+          type: "jitter",
+          severity: "low"
+        }],
+        summary: {
+          totalFindings: 1
+        },
+        data: {
+          frames: 100
+        },
+        elementPath: "App > Header > Button",
+        interactions: [{
+          t: 0,
+          type: "click",
+          target: "button",
+          x: 100,
+          y: 200
+        }]
+      };
+      saveToStorage(recording);
+      const loaded = loadFromStorage();
+      expect(loaded.last).toEqual(recording);
+      expect(loaded.previous).toBeNull();
+    });
+  });
+});

package/dist/hooks/useRecordingState.d.ts

@@ -0,0 +1,43 @@
+import { type Accessor } from "solid-js";
+import { AdapterId } from "../consts";
+import { type DejitterFinding, type DejitterSummary } from "../dejitter/recorder";
+import type { InteractionEvent } from "../components/RecordingResults";
+import type { DeltaReport } from "../visualDiff/types";
+export type RecordingState = "idle" | "selecting" | "recording" | "results";
+export interface RecordingStateAPI {
+    recordingState: Accessor<RecordingState>;
+    recordedElement: Accessor<HTMLElement | null>;
+    recordingFindings: Accessor<DejitterFinding[]>;
+    recordingSummary: Accessor<DejitterSummary | null>;
+    recordingData: Accessor<any>;
+    recordingElementPath: Accessor<string>;
+    interactionLog: Accessor<InteractionEvent[]>;
+    visualDiff: Accessor<DeltaReport | null>;
+    replayBox: Accessor<{
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    } | null>;
+    replaying: Accessor<boolean>;
+    viewingPrevious: Accessor<boolean>;
+    handleRecordClick: () => void;
+    startRecording: (element: HTMLElement) => void;
+    stopRecording: () => Promise<void>;
+    replayRecording: () => void;
+    stopReplay: () => void;
+    replayWithRecord: (elementOrSelector: HTMLElement | string) => Promise<{
+        path: string;
+        findings: DejitterFinding[];
+        summary: DejitterSummary | null;
+        data: any;
+        interactions: InteractionEvent[];
+        visualDiff: DeltaReport | null;
+    } | null>;
+    dismissResults: () => void;
+    hasPreviousRecording: () => boolean;
+    loadPreviousRecording: () => void;
+    loadLatestRecording: () => void;
+    cleanup: () => void;
+}
+export declare function useRecordingState(adapterId?: AdapterId): RecordingStateAPI;

package/dist/hooks/useRecordingState.js

@@ -0,0 +1,387 @@
+import { createSignal } from "solid-js";
+import { createDejitterRecorder } from "../dejitter/recorder";
+import { isLocatorsOwnElement } from "../functions/isLocatorsOwnElement";
+import { collectAncestry, formatAncestryChain } from "../functions/formatAncestryChain";
+import { createTreeNode } from "../adapters/createTreeNode";
+import { loadFromStorage, saveToStorage, clearStorage } from "./useLocatorStorage";
+import { settings } from "./useSettings";
+import { takeSnapshot } from "../visualDiff/snapshot";
+import { computeDiff, formatReport } from "../visualDiff/diff";
+import { waitForSettle } from "../visualDiff/settle";
+function buildDejitterConfig() {
+  const s = settings();
+  return {
+    selector: "[data-treelocator-recording]",
+    props: ["opacity", "transform", "boundingRect", "width", "height"],
+    sampleRate: s.sampleRate,
+    maxDuration: s.maxDurationMs,
+    idleTimeout: 0,
+    mutations: true,
+    thresholds: {
+      jump: {
+        minAbsolute: s.jumpMinAbsolute
+      },
+      lag: {
+        minDelay: s.lagMinDelay
+      }
+    }
+  };
+}
+export function useRecordingState(adapterId) {
+  // Restore last results on mount
+  const restored = loadFromStorage();
+  const restoredLast = restored.last;
+  const [recordingState, setRecordingState] = createSignal(restoredLast ? "results" : "idle");
+  const [recordedElement, setRecordedElement] = createSignal(null);
+  const [recordingFindings, setRecordingFindings] = createSignal(restoredLast?.findings ?? []);
+  const [recordingSummary, setRecordingSummary] = createSignal(restoredLast?.summary ?? null);
+  const [interactionLog, setInteractionLog] = createSignal(restoredLast?.interactions ?? []);
+  const [recordingData, setRecordingData] = createSignal(restoredLast?.data ?? null);
+  const [recordingElementPath, setRecordingElementPath] = createSignal(restoredLast?.elementPath ?? "");
+  const [visualDiff, setVisualDiff] = createSignal(restoredLast?.visualDiff ?? null);
+  const [replayBox, setReplayBox] = createSignal(null);
+  const [replaying, setReplaying] = createSignal(false);
+  const [viewingPrevious, setViewingPrevious] = createSignal(false);
+  let dejitterInstance = null;
+  let interactionClickHandler = null;
+  let recordingStartTime = 0;
+  let recordingStartPerf = 0;
+  let replayTimerId = null;
+  let visualDiffContext = null;
+  async function finalizeVisualDiff() {
+    if (!visualDiffContext) return null;
+    const {
+      before,
+      root
+    } = visualDiffContext;
+    visualDiffContext = null;
+    const settle = await waitForSettle(1000, root);
+    const after = takeSnapshot(root);
+    const report = computeDiff(before, after);
+    report.elapsedMs = performance.now() - recordingStartPerf;
+    report.settle = settle;
+    report.text = formatReport(report.entries, {
+      elapsedMs: report.elapsedMs,
+      settle
+    });
+    return report;
+  }
+  function collectElementPath(el) {
+    const treeNode = createTreeNode(el, adapterId);
+    if (treeNode) {
+      const ancestry = collectAncestry(treeNode);
+      return formatAncestryChain(ancestry);
+    }
+    return "";
+  }
+
+  // --- Recording lifecycle ---
+
+  function handleRecordClick() {
+    switch (recordingState()) {
+      case "idle":
+        setRecordingState("selecting");
+        break;
+      case "selecting":
+        setRecordingState("idle");
+        break;
+      case "recording":
+        stopRecording();
+        break;
+      case "results":
+        dismissResults();
+        setRecordingState("selecting");
+        break;
+    }
+  }
+  function startRecording(element) {
+    element.setAttribute("data-treelocator-recording", "true");
+    setRecordedElement(element);
+    recordingStartPerf = performance.now();
+    visualDiffContext = settings().visualDiff ? {
+      before: takeSnapshot(element),
+      root: element
+    } : null;
+    dejitterInstance = createDejitterRecorder();
+    dejitterInstance.configure(buildDejitterConfig());
+    dejitterInstance.start();
+    startInteractionTracker();
+    setRecordingState("recording");
+  }
+  async function stopRecording() {
+    const instance = dejitterInstance;
+    if (!instance) return;
+    dejitterInstance = null;
+    instance.stop();
+    const anomalyEnabled = settings().anomalyTracking;
+    const findings = anomalyEnabled ? instance.findings(true) : [];
+    const summary = instance.summary(true);
+    const data = anomalyEnabled ? instance.getData() : null;
+    const el = recordedElement();
+    const elementPath = el ? collectElementPath(el) : "";
+    stopInteractionTracker();
+    const diffReport = await finalizeVisualDiff();
+    setRecordingFindings(findings);
+    setRecordingSummary(summary);
+    setRecordingData(data);
+    setRecordingElementPath(elementPath);
+    setVisualDiff(diffReport);
+    saveToStorage({
+      findings,
+      summary,
+      data,
+      elementPath,
+      interactions: interactionLog(),
+      visualDiff: diffReport
+    });
+    el?.removeAttribute("data-treelocator-recording");
+    setRecordingState("results");
+  }
+  function replayRecording() {
+    const events = interactionLog();
+    if (events.length === 0) return;
+    stopReplay();
+    setReplaying(true);
+    let eventIdx = 0;
+    function scheduleNext() {
+      if (eventIdx >= events.length) {
+        stopReplay();
+        return;
+      }
+      const evt = events[eventIdx];
+      const delay = eventIdx === 0 ? 100 : evt.t - events[eventIdx - 1].t;
+      replayTimerId = window.setTimeout(() => {
+        setReplayBox({
+          x: evt.x - 12,
+          y: evt.y - 12,
+          w: 24,
+          h: 24
+        });
+        const target = document.elementFromPoint(evt.x, evt.y);
+        if (target) {
+          target.dispatchEvent(new MouseEvent("click", {
+            bubbles: true,
+            cancelable: true,
+            clientX: evt.x,
+            clientY: evt.y,
+            view: window
+          }));
+        }
+        window.setTimeout(() => setReplayBox(null), 200);
+        eventIdx++;
+        scheduleNext();
+      }, Math.max(delay, 50));
+    }
+    scheduleNext();
+  }
+  function stopReplay() {
+    if (replayTimerId) {
+      clearTimeout(replayTimerId);
+      replayTimerId = null;
+    }
+    setReplaying(false);
+    setReplayBox(null);
+  }
+  function replayWithRecord(elementOrSelector) {
+    let element;
+    if (typeof elementOrSelector === "string") {
+      const found = document.querySelector(elementOrSelector);
+      element = found instanceof HTMLElement ? found : null;
+    } else {
+      element = elementOrSelector;
+    }
+    if (!element) return Promise.resolve(null);
+    const stored = loadFromStorage();
+    const events = stored.last?.interactions ?? interactionLog();
+    if (events.length === 0) return Promise.resolve(null);
+    return new Promise(resolve => {
+      element.setAttribute("data-treelocator-recording", "true");
+      setRecordedElement(element);
+      recordingStartPerf = performance.now();
+      visualDiffContext = settings().visualDiff ? {
+        before: takeSnapshot(element),
+        root: element
+      } : null;
+      dejitterInstance = createDejitterRecorder();
+      dejitterInstance.configure(buildDejitterConfig());
+      dejitterInstance.start();
+      setRecordingState("recording");
+      setReplaying(true);
+      let eventIdx = 0;
+      async function finishRecording() {
+        setReplaying(false);
+        setReplayBox(null);
+        const instance = dejitterInstance;
+        if (!instance) {
+          resolve(null);
+          return;
+        }
+        dejitterInstance = null;
+        instance.stop();
+        const anomalyEnabled = settings().anomalyTracking;
+        const findings = anomalyEnabled ? instance.findings(true) : [];
+        const summary = instance.summary(true);
+        const data = anomalyEnabled ? instance.getData() : null;
+        const el = recordedElement();
+        const elementPath = el ? collectElementPath(el) : "";
+        const diffReport = await finalizeVisualDiff();
+        setRecordingFindings(findings);
+        setRecordingSummary(summary);
+        setRecordingData(data);
+        setRecordingElementPath(elementPath);
+        setInteractionLog(events);
+        setVisualDiff(diffReport);
+        saveToStorage({
+          findings,
+          summary,
+          data,
+          elementPath,
+          interactions: events,
+          visualDiff: diffReport
+        });
+        el?.removeAttribute("data-treelocator-recording");
+        setRecordingState("results");
+        resolve({
+          path: elementPath,
+          findings,
+          summary,
+          data,
+          interactions: events,
+          visualDiff: diffReport
+        });
+      }
+      function scheduleNext() {
+        if (eventIdx >= events.length) {
+          replayTimerId = window.setTimeout(finishRecording, 500);
+          return;
+        }
+        const evt = events[eventIdx];
+        const delay = eventIdx === 0 ? 100 : evt.t - events[eventIdx - 1].t;
+        replayTimerId = window.setTimeout(() => {
+          setReplayBox({
+            x: evt.x - 12,
+            y: evt.y - 12,
+            w: 24,
+            h: 24
+          });
+          const target = document.elementFromPoint(evt.x, evt.y);
+          if (target) {
+            target.dispatchEvent(new MouseEvent("click", {
+              bubbles: true,
+              cancelable: true,
+              clientX: evt.x,
+              clientY: evt.y,
+              view: window
+            }));
+          }
+          window.setTimeout(() => setReplayBox(null), 200);
+          eventIdx++;
+          scheduleNext();
+        }, Math.max(delay, 50));
+      }
+      scheduleNext();
+    });
+  }
+  function dismissResults() {
+    stopReplay();
+    setRecordingFindings([]);
+    setRecordingSummary(null);
+    setRecordingData(null);
+    setRecordingElementPath("");
+    setInteractionLog([]);
+    setVisualDiff(null);
+    setRecordedElement(null);
+    setViewingPrevious(false);
+    setRecordingState("idle");
+    clearStorage();
+  }
+  function hasPreviousRecording() {
+    return loadFromStorage().previous !== null;
+  }
+  function loadPreviousRecording() {
+    const stored = loadFromStorage();
+    if (!stored.previous) return;
+    const prev = stored.previous;
+    setRecordingFindings(prev.findings);
+    setRecordingSummary(prev.summary);
+    setRecordingData(prev.data);
+    setRecordingElementPath(prev.elementPath);
+    setInteractionLog(prev.interactions);
+    setVisualDiff(prev.visualDiff ?? null);
+    setViewingPrevious(true);
+    setRecordingState("results");
+  }
+  function loadLatestRecording() {
+    const stored = loadFromStorage();
+    if (!stored.last) return;
+    const last = stored.last;
+    setRecordingFindings(last.findings);
+    setRecordingSummary(last.summary);
+    setRecordingData(last.data);
+    setRecordingElementPath(last.elementPath);
+    setInteractionLog(last.interactions);
+    setVisualDiff(last.visualDiff ?? null);
+    setViewingPrevious(false);
+    setRecordingState("results");
+  }
+
+  // --- Interaction tracking ---
+
+  function startInteractionTracker() {
+    recordingStartTime = performance.now();
+    setInteractionLog([]);
+    interactionClickHandler = e => {
+      if (isLocatorsOwnElement(e.target)) return;
+      const el = e.target;
+      const tag = el.tagName?.toLowerCase() || "unknown";
+      const id = el.id ? "#" + el.id : "";
+      const cls = el.className && typeof el.className === "string" ? "." + el.className.split(" ")[0] : "";
+      setInteractionLog(prev => [...prev, {
+        t: Math.round(performance.now() - recordingStartTime),
+        type: "click",
+        target: `${tag}${id}${cls}`,
+        x: e.clientX,
+        y: e.clientY
+      }]);
+    };
+    document.addEventListener("click", interactionClickHandler, {
+      capture: true
+    });
+  }
+  function stopInteractionTracker() {
+    if (interactionClickHandler) {
+      document.removeEventListener("click", interactionClickHandler, {
+        capture: true
+      });
+      interactionClickHandler = null;
+    }
+  }
+  function cleanup() {
+    stopReplay();
+    stopInteractionTracker();
+  }
+  return {
+    recordingState,
+    recordedElement,
+    recordingFindings,
+    recordingSummary,
+    recordingData,
+    recordingElementPath,
+    interactionLog,
+    visualDiff,
+    replayBox,
+    replaying,
+    viewingPrevious,
+    handleRecordClick,
+    startRecording,
+    stopRecording,
+    replayRecording,
+    stopReplay,
+    replayWithRecord,
+    dismissResults,
+    hasPreviousRecording,
+    loadPreviousRecording,
+    loadLatestRecording,
+    cleanup
+  };
+}

package/dist/hooks/useSettings.d.ts

@@ -0,0 +1,13 @@
+import { type Accessor } from "solid-js";
+export type TreelocatorSettings = {
+    anomalyTracking: boolean;
+    visualDiff: boolean;
+    computedStyles: boolean;
+    computedStylesIncludeDefaults: boolean;
+    sampleRate: number;
+    maxDurationMs: number;
+    jumpMinAbsolute: number;
+    lagMinDelay: number;
+};
+export declare const DEFAULT_SETTINGS: TreelocatorSettings;
+export declare const settings: Accessor<TreelocatorSettings>, setSetting: <K extends keyof TreelocatorSettings>(key: K, value: TreelocatorSettings[K]) => void, resetSettings: () => void;

package/dist/hooks/useSettings.js

@@ -0,0 +1,66 @@
+import { createRoot, createSignal } from "solid-js";
+import { getStorage } from "./getStorage";
+export const DEFAULT_SETTINGS = {
+  anomalyTracking: true,
+  visualDiff: true,
+  computedStyles: true,
+  computedStylesIncludeDefaults: false,
+  sampleRate: 15,
+  maxDurationMs: 30000,
+  jumpMinAbsolute: 50,
+  lagMinDelay: 50
+};
+const STORAGE_KEY = "__treelocator_settings__";
+function loadSettings() {
+  const storage = getStorage();
+  if (!storage) return {
+    ...DEFAULT_SETTINGS
+  };
+  try {
+    const raw = storage.getItem(STORAGE_KEY);
+    if (raw) return {
+      ...DEFAULT_SETTINGS,
+      ...JSON.parse(raw)
+    };
+  } catch {
+    // Ignore localStorage errors (SSR, permissions, quota)
+  }
+  return {
+    ...DEFAULT_SETTINGS
+  };
+}
+function persistSettings(next) {
+  const storage = getStorage();
+  if (!storage) return;
+  try {
+    storage.setItem(STORAGE_KEY, JSON.stringify(next));
+  } catch {
+    // Ignore localStorage errors (SSR, permissions, quota)
+  }
+}
+export const {
+  settings,
+  setSetting,
+  resetSettings
+} = createRoot(() => {
+  const [settings, setSettingsSignal] = createSignal(loadSettings());
+  function setSetting(key, value) {
+    const next = {
+      ...settings(),
+      [key]: value
+    };
+    setSettingsSignal(next);
+    persistSettings(next);
+  }
+  function resetSettings() {
+    setSettingsSignal({
+      ...DEFAULT_SETTINGS
+    });
+    persistSettings(DEFAULT_SETTINGS);
+  }
+  return {
+    settings,
+    setSetting,
+    resetSettings
+  };
+});

package/dist/index.d.ts

@@ -1,11 +1,14 @@
 import { Target } from "@locator/shared";
 import { AdapterId } from "./consts";
+import type { MCPBridgeConfig } from "./mcpBridge";
 export * from "./adapters/jsx/runtimeStore";
 export declare const MAX_ZINDEX = 2147483647;
-export declare function setup({ adapter, targets, }?: {
+export interface SetupOptions {
     adapter?: AdapterId;
     targets?: {
         [k: string]: Target | string;
     };
-}): void;
+    mcp?: MCPBridgeConfig;
+}
+export declare function setup({ adapter, targets, mcp, }?: SetupOptions): void;
 export default setup;

package/dist/index.js

@@ -3,11 +3,13 @@ export * from "./adapters/jsx/runtimeStore";
 export const MAX_ZINDEX = 2147483647;
 export function setup({
   adapter,
-  targets
+  targets,
+  mcp
 } = {}) {
   setTimeout(() => initRuntime({
     adapter,
-    targets
+    targets,
+    mcp
   }), 0);
 }
 export default setup;

package/dist/initRuntime.d.ts

@@ -1,8 +1,10 @@
 import { Target } from "@locator/shared";
 import { AdapterId } from "./consts";
-export declare function initRuntime({ adapter, targets, }?: {
+import type { MCPBridgeConfig } from "./mcpBridge";
+export declare function initRuntime({ adapter, targets, mcp, }?: {
     adapter?: AdapterId;
     targets?: {
         [k: string]: Target | string;
     };
+    mcp?: MCPBridgeConfig;
 }): void;

package/dist/initRuntime.js

@@ -3,9 +3,11 @@ import { fontFamily } from "./consts";
 import generatedStyles from "./_generated_styles";
 import { MAX_ZINDEX } from "./index";
 import { installBrowserAPI } from "./browserApi";
+import { startMCPBridge } from "./mcpBridge";
 export function initRuntime({
   adapter,
-  targets
+  targets,
+  mcp
 } = {}) {
   if (typeof window === "undefined" || typeof document === "undefined") {
     return;
@@ -17,6 +19,7 @@ export function initRuntime({
 
   // Install browser API on window.__treelocator__
   installBrowserAPI(adapter);
+  startMCPBridge(mcp);
 
   // add style tag to head
   const style = document.createElement("style");