@treelocator/runtime 0.5.2 → 0.6.0

package/dist/functions/namedSnapshots.js

@@ -0,0 +1,161 @@
+/**
+ * Named element snapshots persisted in localStorage.
+ *
+ * Workflow: takeSnapshot(selector, id) → change code → getSnapshotDiff(id).
+ * Stored snapshots are immutable — getSnapshotDiff never overwrites the
+ * baseline, so iterating on a fix always diffs against the original state.
+ */
+
+import { readSnapshot, formatSnapshotDiff } from "./extractComputedStyles";
+const STORAGE_KEY_PREFIX = "treelocator:snapshot:";
+export class NamedSnapshotError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = "NamedSnapshotError";
+    this.code = code;
+  }
+}
+function getStorage() {
+  try {
+    return typeof localStorage !== "undefined" ? localStorage : null;
+  } catch {
+    return null;
+  }
+}
+function storageKey(snapshotId) {
+  return `${STORAGE_KEY_PREFIX}${snapshotId}`;
+}
+function resolveElement(selector, index) {
+  let nodes;
+  try {
+    nodes = document.querySelectorAll(selector);
+  } catch {
+    throw new NamedSnapshotError("invalid_selector", `Invalid selector: ${selector}`);
+  }
+  const node = nodes.item(index);
+  if (!(node instanceof HTMLElement) && !(node instanceof SVGElement)) {
+    throw new NamedSnapshotError("element_not_found", `No element found for selector "${selector}" at index ${index}`);
+  }
+  return node;
+}
+function writeStored(stored) {
+  const storage = getStorage();
+  if (!storage) {
+    throw new NamedSnapshotError("storage_unavailable", "localStorage is not available in this environment");
+  }
+  try {
+    storage.setItem(storageKey(stored.snapshotId), JSON.stringify(stored));
+  } catch (error) {
+    throw new NamedSnapshotError("storage_write_failed", error instanceof Error ? error.message : "Failed to write snapshot");
+  }
+}
+function readStored(snapshotId) {
+  const storage = getStorage();
+  if (!storage) {
+    throw new NamedSnapshotError("storage_unavailable", "localStorage is not available in this environment");
+  }
+  const raw = storage.getItem(storageKey(snapshotId));
+  if (!raw) {
+    throw new NamedSnapshotError("snapshot_not_found", `No snapshot stored under id "${snapshotId}"`);
+  }
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    throw new NamedSnapshotError("snapshot_corrupt", error instanceof Error ? error.message : "Failed to parse stored snapshot");
+  }
+}
+export function takeNamedSnapshot(selector, snapshotId, options = {}) {
+  if (!selector) {
+    throw new NamedSnapshotError("invalid_args", "selector is required");
+  }
+  if (!snapshotId) {
+    throw new NamedSnapshotError("invalid_args", "snapshotId is required");
+  }
+  const index = options.index ?? 0;
+  const element = resolveElement(selector, index);
+  const snapshot = readSnapshot(element);
+  const takenAt = new Date().toISOString();
+  const stored = {
+    snapshotId,
+    selector,
+    index,
+    label: options.label,
+    takenAt,
+    snapshot
+  };
+  writeStored(stored);
+  return {
+    snapshotId,
+    selector,
+    index,
+    takenAt,
+    propertyCount: Object.keys(snapshot.properties).length,
+    boundingRect: snapshot.boundingRect
+  };
+}
+export function getNamedSnapshotDiff(snapshotId) {
+  if (!snapshotId) {
+    throw new NamedSnapshotError("invalid_args", "snapshotId is required");
+  }
+  const stored = readStored(snapshotId);
+  const element = resolveElement(stored.selector, stored.index);
+  const current = readSnapshot(element);
+  const changes = [];
+  const allProps = new Set([...Object.keys(stored.snapshot.properties), ...Object.keys(current.properties)]);
+  for (const prop of allProps) {
+    const before = stored.snapshot.properties[prop] || "";
+    const after = current.properties[prop] || "";
+    if (before === after) continue;
+    if (!before) {
+      changes.push({
+        type: "added",
+        property: prop,
+        after
+      });
+    } else if (!after) {
+      changes.push({
+        type: "removed",
+        property: prop,
+        before
+      });
+    } else {
+      changes.push({
+        type: "changed",
+        property: prop,
+        before,
+        after
+      });
+    }
+  }
+  const boundingRectChanges = [];
+  const rectKeys = ["x", "y", "width", "height"];
+  for (const key of rectKeys) {
+    const b = stored.snapshot.boundingRect[key];
+    const a = current.boundingRect[key];
+    if (b !== a) {
+      boundingRectChanges.push({
+        key,
+        before: b,
+        after: a
+      });
+    }
+  }
+  return {
+    snapshotId,
+    selector: stored.selector,
+    index: stored.index,
+    takenAt: stored.takenAt,
+    formatted: formatSnapshotDiff(stored.snapshot, current, stored.label),
+    changes,
+    boundingRectChanges
+  };
+}
+export function clearNamedSnapshot(snapshotId) {
+  const storage = getStorage();
+  if (!storage) return;
+  try {
+    storage.removeItem(storageKey(snapshotId));
+  } catch {
+    // Swallow — same rationale as getStorage fallbacks.
+  }
+}

package/dist/functions/namedSnapshots.test.d.ts

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

package/dist/functions/namedSnapshots.test.js

@@ -0,0 +1,85 @@
+// @vitest-environment jsdom
+import { describe, it, expect, beforeEach } from "vitest";
+import { takeNamedSnapshot, getNamedSnapshotDiff, clearNamedSnapshot, NamedSnapshotError } from "./namedSnapshots";
+describe("namedSnapshots", () => {
+  beforeEach(() => {
+    localStorage.clear();
+    document.body.innerHTML = "";
+  });
+  it("persists a snapshot under the given id and reports property count", () => {
+    document.body.innerHTML = `<button id="b">hi</button>`;
+    const result = takeNamedSnapshot("#b", "baseline");
+    expect(result.snapshotId).toBe("baseline");
+    expect(result.selector).toBe("#b");
+    expect(result.index).toBe(0);
+    expect(result.propertyCount).toBeGreaterThan(0);
+    expect(localStorage.getItem("treelocator:snapshot:baseline")).not.toBeNull();
+  });
+  it("returns no-op diff when nothing changed", () => {
+    document.body.innerHTML = `<button id="b" style="color: red">hi</button>`;
+    takeNamedSnapshot("#b", "baseline");
+    const diff = getNamedSnapshotDiff("baseline");
+    expect(diff.changes).toEqual([]);
+    expect(diff.boundingRectChanges).toEqual([]);
+    expect(diff.formatted).toContain("No changes detected");
+  });
+  it("reports property transitions without mutating the baseline", () => {
+    document.body.innerHTML = `<button id="b" style="color: rgb(255, 0, 0)">hi</button>`;
+    takeNamedSnapshot("#b", "baseline");
+    const button = document.getElementById("b");
+    button.style.color = "rgb(0, 128, 0)";
+    const first = getNamedSnapshotDiff("baseline");
+    const colorChange = first.changes.find(c => c.property === "color");
+    expect(colorChange).toBeDefined();
+    expect(colorChange).toMatchObject({
+      type: "changed",
+      before: "rgb(255, 0, 0)",
+      after: "rgb(0, 128, 0)"
+    });
+
+    // Revert and diff again — the baseline must still be the original red.
+    button.style.color = "rgb(255, 0, 0)";
+    const second = getNamedSnapshotDiff("baseline");
+    expect(second.changes.find(c => c.property === "color")).toBeUndefined();
+  });
+  it("overwrites baseline only when takeSnapshot is called again", () => {
+    document.body.innerHTML = `<button id="b" style="opacity: 1">hi</button>`;
+    takeNamedSnapshot("#b", "baseline");
+    const button = document.getElementById("b");
+    button.style.opacity = "0.5";
+
+    // Re-taking replaces baseline with current state.
+    takeNamedSnapshot("#b", "baseline");
+    const diff = getNamedSnapshotDiff("baseline");
+    expect(diff.changes.find(c => c.property === "opacity")).toBeUndefined();
+  });
+  it("throws snapshot_not_found for unknown id", () => {
+    expect(() => getNamedSnapshotDiff("nope")).toThrow(NamedSnapshotError);
+  });
+  it("throws element_not_found when baseline selector no longer resolves", () => {
+    document.body.innerHTML = `<button id="b">hi</button>`;
+    takeNamedSnapshot("#b", "baseline");
+    document.body.innerHTML = "";
+    expect(() => getNamedSnapshotDiff("baseline")).toThrow(/element_not_found|No element found/i);
+  });
+  it("clearNamedSnapshot removes the baseline", () => {
+    document.body.innerHTML = `<button id="b">hi</button>`;
+    takeNamedSnapshot("#b", "baseline");
+    clearNamedSnapshot("baseline");
+    expect(localStorage.getItem("treelocator:snapshot:baseline")).toBeNull();
+    expect(() => getNamedSnapshotDiff("baseline")).toThrow(NamedSnapshotError);
+  });
+  it("respects `index` option when multiple elements match", () => {
+    document.body.innerHTML = `
+      <button class="t" style="color: rgb(255, 0, 0)">one</button>
+      <button class="t" style="color: rgb(0, 0, 255)">two</button>
+    `;
+    takeNamedSnapshot(".t", "second", {
+      index: 1
+    });
+    const diff = getNamedSnapshotDiff("second");
+    expect(diff.selector).toBe(".t");
+    expect(diff.index).toBe(1);
+    expect(diff.changes).toEqual([]);
+  });
+});

package/dist/functions/normalizeFilePath.test.d.ts

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

package/dist/functions/normalizeFilePath.test.js

@@ -0,0 +1,66 @@
+import { describe, expect, test } from "vitest";
+import { normalizeFilePath } from "./normalizeFilePath";
+describe("normalizeFilePath", () => {
+  test("relative path unchanged", () => {
+    const result = normalizeFilePath("src/App.tsx");
+    expect(result).toBe("src/App.tsx");
+  });
+  test("relative path with components unchanged", () => {
+    const result = normalizeFilePath("components/Button.tsx");
+    expect(result).toBe("components/Button.tsx");
+  });
+  test("absolute path with /src/ indicator", () => {
+    const result = normalizeFilePath("/Users/name/project/src/App.tsx");
+    expect(result).toBe("src/App.tsx");
+  });
+  test("absolute path with /app/ indicator", () => {
+    const result = normalizeFilePath("/workspace/apps/next-16/app/page.tsx");
+    expect(result).toBe("app/page.tsx");
+  });
+  test("absolute path with /pages/ indicator", () => {
+    const result = normalizeFilePath("/home/project/pages/index.tsx");
+    expect(result).toBe("pages/index.tsx");
+  });
+  test("absolute path with /components/ indicator", () => {
+    const result = normalizeFilePath("/home/project/components/Header.tsx");
+    expect(result).toBe("components/Header.tsx");
+  });
+  test("absolute path with /lib/ indicator", () => {
+    const result = normalizeFilePath("/home/project/lib/utils.ts");
+    expect(result).toBe("lib/utils.ts");
+  });
+  test("absolute path without indicator uses last 4 segments", () => {
+    const result = normalizeFilePath("/a/b/c/d/e/f/g.ts");
+    // Parts: ['', 'a', 'b', 'c', 'd', 'e', 'f', 'g.ts']
+    // Last 4: ['d', 'e', 'f', 'g.ts']
+    expect(result).toBe("d/e/f/g.ts");
+  });
+  test("absolute path with only 3 segments returns as-is", () => {
+    const result = normalizeFilePath("/home/project/file.ts");
+    expect(result).toBe("/home/project/file.ts");
+  });
+  test("absolute path with 2 segments returns as-is", () => {
+    const result = normalizeFilePath("/home/file.ts");
+    expect(result).toBe("/home/file.ts");
+  });
+  test("single segment path returns as-is", () => {
+    const result = normalizeFilePath("/file.ts");
+    expect(result).toBe("/file.ts");
+  });
+  test("deep nested path without indicator gets last 4 segments", () => {
+    const result = normalizeFilePath("/home/user/projects/nomarker/src/components/Button/index.tsx");
+    // Parts: ['', 'home', 'user', 'projects', 'nomarker', 'src', 'components', 'Button', 'index.tsx']
+    // But /src/ is in indicators, so it matches and returns from /src/ onwards
+    expect(result).toBe("src/components/Button/index.tsx");
+  });
+  test("uses first matching indicator when multiple present", () => {
+    const result = normalizeFilePath("/home/project/src/app/components/Header.tsx");
+    // /app/ comes before /src/ in the indicators array, and both are present
+    // /app/ is found first, so it returns from /app/ onwards
+    expect(result).toBe("app/components/Header.tsx");
+  });
+  test("empty string unchanged", () => {
+    const result = normalizeFilePath("");
+    expect(result).toBe("");
+  });
+});

package/dist/functions/parseDataId.test.d.ts

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

package/dist/functions/parseDataId.test.js

@@ -0,0 +1,101 @@
+import { describe, expect, test } from "vitest";
+import { parseDataId, parseDataPath, splitFullPath } from "./parseDataId";
+describe("parseDataId", () => {
+  test("happy path with valid dataId", () => {
+    const result = parseDataId("path/file.tsx::0");
+    expect(result).toEqual(["path/file.tsx", "0"]);
+  });
+  test("throws on missing double colon separator", () => {
+    expect(() => parseDataId("path/file.tsx:0")).toThrow("locatorjsId is malformed");
+  });
+  test("throws on missing file path", () => {
+    expect(() => parseDataId("::0")).toThrow("locatorjsId is malformed");
+  });
+  test("throws on missing id", () => {
+    expect(() => parseDataId("path/file.tsx::")).toThrow("locatorjsId is malformed");
+  });
+  test("throws on empty string", () => {
+    expect(() => parseDataId("")).toThrow("locatorjsId is malformed");
+  });
+  test("handles complex paths with multiple slashes", () => {
+    const result = parseDataId("/home/user/projects/src/components/Button.tsx::abc123");
+    expect(result).toEqual(["/home/user/projects/src/components/Button.tsx", "abc123"]);
+  });
+});
+describe("parseDataPath", () => {
+  test("standard unix path with line and column", () => {
+    const result = parseDataPath("/path/file.tsx:12:3");
+    expect(result).toEqual(["/path/file.tsx", 12, 3]);
+  });
+  test("Windows path with line and column", () => {
+    const result = parseDataPath("C:\\path\\file.tsx:12:3");
+    expect(result).toEqual(["C:\\path\\file.tsx", 12, 3]);
+  });
+  test("complex absolute path", () => {
+    const result = parseDataPath("/home/user/projects/src/components/Button.tsx:42:15");
+    expect(result).toEqual(["/home/user/projects/src/components/Button.tsx", 42, 15]);
+  });
+  test("returns null when missing colon", () => {
+    const result = parseDataPath("/path/file.tsx12:3");
+    expect(result).toBeNull();
+  });
+  test("returns null when only one colon", () => {
+    const result = parseDataPath("/path/file.tsx:12");
+    expect(result).toBeNull();
+  });
+  test("returns null when line is not numeric", () => {
+    const result = parseDataPath("/path/file.tsx:abc:3");
+    expect(result).toBeNull();
+  });
+  test("returns null when column is not numeric", () => {
+    const result = parseDataPath("/path/file.tsx:12:xyz");
+    expect(result).toBeNull();
+  });
+  test("returns null when no colons present", () => {
+    const result = parseDataPath("/path/file.tsx");
+    expect(result).toBeNull();
+  });
+  test("handles zero as valid line and column numbers", () => {
+    const result = parseDataPath("/path/file.tsx:0:0");
+    expect(result).toEqual(["/path/file.tsx", 0, 0]);
+  });
+});
+describe("splitFullPath", () => {
+  test("splits on /src/ indicator", () => {
+    const result = splitFullPath("/home/user/project/src/components/Button.tsx");
+    expect(result).toEqual(["/home/user/project", "/src/components/Button.tsx"]);
+  });
+  test("splits on /app/ indicator", () => {
+    const result = splitFullPath("/workspace/myapp/app/page.tsx");
+    expect(result).toEqual(["/workspace/myapp", "/app/page.tsx"]);
+  });
+  test("splits on /pages/ indicator", () => {
+    const result = splitFullPath("/home/project/pages/index.tsx");
+    expect(result).toEqual(["/home/project", "/pages/index.tsx"]);
+  });
+  test("splits on /components/ indicator", () => {
+    const result = splitFullPath("/home/project/components/Header.tsx");
+    expect(result).toEqual(["/home/project", "/components/Header.tsx"]);
+  });
+  test("uses first matching indicator when multiple present", () => {
+    const result = splitFullPath("/home/project/src/pages/index.tsx");
+    // /src/ comes first in the indicators array
+    expect(result).toEqual(["/home/project", "/src/pages/index.tsx"]);
+  });
+  test("fallback to last slash when no indicator found", () => {
+    const result = splitFullPath("/home/user/myfile.txt");
+    expect(result).toEqual(["/home/user/", "myfile.txt"]);
+  });
+  test("handles path with no slashes", () => {
+    const result = splitFullPath("filename.txt");
+    expect(result).toEqual(["filename.txt", ""]);
+  });
+  test("handles empty path", () => {
+    const result = splitFullPath("");
+    expect(result).toEqual(["", ""]);
+  });
+  test("handles root path", () => {
+    const result = splitFullPath("/");
+    expect(result).toEqual(["/", ""]);
+  });
+});

package/dist/hooks/getStorage.d.ts

@@ -0,0 +1,3 @@
+type StorageLike = Pick<Storage, "getItem" | "setItem" | "removeItem">;
+export declare function getStorage(): StorageLike | null;
+export {};

package/dist/hooks/getStorage.js

@@ -0,0 +1,17 @@
+function isStorageLike(value) {
+  if (!value || typeof value !== "object") return false;
+  const candidate = value;
+  return typeof candidate.getItem === "function" && typeof candidate.setItem === "function" && typeof candidate.removeItem === "function";
+}
+export function getStorage() {
+  try {
+    if (typeof window !== "undefined" && isStorageLike(window.localStorage)) {
+      return window.localStorage;
+    }
+  } catch {
+    // Ignore localStorage access errors (SSR, permissions, opaque origin)
+  }
+  const candidate = globalThis.localStorage;
+  if (isStorageLike(candidate)) return candidate;
+  return null;
+}

package/dist/hooks/useEventListeners.d.ts

@@ -0,0 +1,15 @@
+export interface EventListenerCallbacks {
+    mouseOverListener: (e: MouseEvent) => void;
+    mouseMoveListener: (e: MouseEvent) => void;
+    keyDownListener: (e: KeyboardEvent) => void;
+    keyUpListener: (e: KeyboardEvent) => void;
+    clickListener: (e: MouseEvent) => void;
+    mouseDownUpListener: (e: MouseEvent) => void;
+    scrollListener: () => void;
+    onCleanup?: () => void;
+}
+/**
+ * Wire up event listeners across the document and all shadow roots,
+ * and clean them up when the component unmounts.
+ */
+export declare function useEventListeners(callbacks: EventListenerCallbacks): void;

package/dist/hooks/useEventListeners.js

@@ -0,0 +1,56 @@
+import { onCleanup } from "solid-js";
+/**
+ * Wire up event listeners across the document and all shadow roots,
+ * and clean them up when the component unmounts.
+ */
+export function useEventListeners(callbacks) {
+  const roots = [document];
+  document.querySelectorAll("*").forEach(node => {
+    if (node.id === "locatorjs-wrapper") {
+      return;
+    }
+    if (node.shadowRoot) {
+      roots.push(node.shadowRoot);
+    }
+  });
+  for (const root of roots) {
+    root.addEventListener("mouseover", callbacks.mouseOverListener, {
+      capture: true
+    });
+    root.addEventListener("mousemove", callbacks.mouseMoveListener, {
+      capture: true
+    });
+    root.addEventListener("keydown", callbacks.keyDownListener);
+    root.addEventListener("keyup", callbacks.keyUpListener);
+    root.addEventListener("click", callbacks.clickListener, {
+      capture: true
+    });
+    root.addEventListener("mousedown", callbacks.mouseDownUpListener, {
+      capture: true
+    });
+    root.addEventListener("mouseup", callbacks.mouseDownUpListener, {
+      capture: true
+    });
+    root.addEventListener("scroll", callbacks.scrollListener);
+  }
+  onCleanup(() => {
+    callbacks.onCleanup?.();
+    for (const root of roots) {
+      root.removeEventListener("keyup", callbacks.keyUpListener);
+      root.removeEventListener("keydown", callbacks.keyDownListener);
+      root.removeEventListener("mouseover", callbacks.mouseOverListener, {
+        capture: true
+      });
+      root.removeEventListener("click", callbacks.clickListener, {
+        capture: true
+      });
+      root.removeEventListener("mousedown", callbacks.mouseDownUpListener, {
+        capture: true
+      });
+      root.removeEventListener("mouseup", callbacks.mouseDownUpListener, {
+        capture: true
+      });
+      root.removeEventListener("scroll", callbacks.scrollListener);
+    }
+  });
+}

package/dist/hooks/useLocatorStorage.d.ts

@@ -0,0 +1,18 @@
+import type { DejitterFinding, DejitterSummary } from "../dejitter/recorder";
+import type { InteractionEvent } from "../components/RecordingResults";
+import type { DeltaReport } from "../visualDiff/types";
+export declare const STORAGE_KEY = "__treelocator_recording__";
+export type SavedRecording = {
+    findings: DejitterFinding[];
+    summary: DejitterSummary | null;
+    data: any;
+    elementPath: string;
+    interactions: InteractionEvent[];
+    visualDiff?: DeltaReport | null;
+};
+export declare function loadFromStorage(): {
+    last: SavedRecording | null;
+    previous: SavedRecording | null;
+};
+export declare function saveToStorage(current: SavedRecording): void;
+export declare function clearStorage(): void;

package/dist/hooks/useLocatorStorage.js

@@ -0,0 +1,41 @@
+import { getStorage } from "./getStorage";
+export const STORAGE_KEY = "__treelocator_recording__";
+export function loadFromStorage() {
+  const storage = getStorage();
+  if (!storage) return {
+    last: null,
+    previous: null
+  };
+  try {
+    const raw = storage.getItem(STORAGE_KEY);
+    if (raw) return JSON.parse(raw);
+  } catch {
+    // Ignore localStorage errors (SSR, permissions, quota)
+  }
+  return {
+    last: null,
+    previous: null
+  };
+}
+export function saveToStorage(current) {
+  const storage = getStorage();
+  if (!storage) return;
+  try {
+    const stored = loadFromStorage();
+    storage.setItem(STORAGE_KEY, JSON.stringify({
+      last: current,
+      previous: stored.last
+    }));
+  } catch {
+    // Ignore localStorage errors (SSR, permissions, quota)
+  }
+}
+export function clearStorage() {
+  const storage = getStorage();
+  if (!storage) return;
+  try {
+    storage.removeItem(STORAGE_KEY);
+  } catch {
+    // Ignore localStorage errors (SSR, permissions, quota)
+  }
+}

package/dist/hooks/useLocatorStorage.test.d.ts

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