@treelocator/runtime 0.5.2 → 0.6.0

package/dist/visualDiff/diff.test.js

@@ -0,0 +1,253 @@
+import { describe, expect, test } from "vitest";
+import { computeDiff, formatReport } from "./diff";
+function snap(overrides = {}) {
+  return {
+    key: "1",
+    tagName: "div",
+    classes: [],
+    x: 0,
+    y: 0,
+    width: 100,
+    height: 100,
+    visible: true,
+    opacity: 1,
+    inViewport: true,
+    pointerEvents: "auto",
+    disabled: false,
+    ...overrides
+  };
+}
+describe("computeDiff", () => {
+  test("empty snapshots produce empty report", () => {
+    const r = computeDiff([], []);
+    expect(r.entries).toHaveLength(0);
+    expect(r.counts).toEqual({
+      added: 0,
+      removed: 0,
+      changed: 0,
+      moved: 0
+    });
+  });
+  test("identical snapshots produce no entries", () => {
+    const a = [snap({
+      key: "1"
+    }), snap({
+      key: "2"
+    })];
+    const b = [snap({
+      key: "1"
+    }), snap({
+      key: "2"
+    })];
+    const r = computeDiff(a, b);
+    expect(r.entries).toHaveLength(0);
+  });
+  test("+ for keys only in after (when visible)", () => {
+    const a = [snap({
+      key: "1"
+    })];
+    const b = [snap({
+      key: "1"
+    }), snap({
+      key: "2",
+      id: "new"
+    })];
+    const r = computeDiff(a, b);
+    expect(r.counts.added).toBe(1);
+    expect(r.entries[0].type).toBe("+");
+    expect(r.entries[0].key).toBe("2");
+  });
+  test("+ is skipped when newly-added element is invisible", () => {
+    const a = [];
+    const b = [snap({
+      key: "2",
+      visible: false
+    })];
+    const r = computeDiff(a, b);
+    expect(r.counts.added).toBe(0);
+  });
+  test("- for keys only in before (when visible)", () => {
+    const a = [snap({
+      key: "1"
+    }), snap({
+      key: "2"
+    })];
+    const b = [snap({
+      key: "1"
+    })];
+    const r = computeDiff(a, b);
+    expect(r.counts.removed).toBe(1);
+    expect(r.entries[0].type).toBe("-");
+  });
+  test("- when element becomes invisible in after", () => {
+    const a = [snap({
+      key: "1",
+      visible: true
+    })];
+    const b = [snap({
+      key: "1",
+      visible: false
+    })];
+    const r = computeDiff(a, b);
+    expect(r.counts.removed).toBe(1);
+    expect(r.entries[0].type).toBe("-");
+  });
+  test("~ when opacity changes by >= 0.05", () => {
+    const a = [snap({
+      key: "1",
+      opacity: 1
+    })];
+    const b = [snap({
+      key: "1",
+      opacity: 0.95
+    })];
+    const r = computeDiff(a, b);
+    expect(r.counts.changed).toBe(1);
+    expect(r.entries[0].type).toBe("~");
+    expect(r.entries[0].changedFields).toContain("opacity");
+  });
+  test("no entry when opacity changes by < 0.05", () => {
+    const a = [snap({
+      key: "1",
+      opacity: 1
+    })];
+    const b = [snap({
+      key: "1",
+      opacity: 0.97
+    })];
+    const r = computeDiff(a, b);
+    expect(r.entries).toHaveLength(0);
+  });
+  test("→ when only x/y change by >= 4px", () => {
+    const a = [snap({
+      key: "1",
+      x: 0,
+      y: 0
+    })];
+    const b = [snap({
+      key: "1",
+      x: 10,
+      y: 20
+    })];
+    const r = computeDiff(a, b);
+    expect(r.counts.moved).toBe(1);
+    expect(r.entries[0].type).toBe("→");
+  });
+  test("no entry when position changes by 3px (under threshold)", () => {
+    const a = [snap({
+      key: "1",
+      x: 0,
+      y: 0
+    })];
+    const b = [snap({
+      key: "1",
+      x: 3,
+      y: 3
+    })];
+    const r = computeDiff(a, b);
+    expect(r.entries).toHaveLength(0);
+  });
+  test("w/h: 2px delta triggers ~, 1px does not", () => {
+    const r1 = computeDiff([snap({
+      key: "1",
+      width: 100
+    })], [snap({
+      key: "1",
+      width: 102
+    })]);
+    expect(r1.counts.changed).toBe(1);
+    const r2 = computeDiff([snap({
+      key: "1",
+      width: 100
+    })], [snap({
+      key: "1",
+      width: 101
+    })]);
+    expect(r2.entries).toHaveLength(0);
+  });
+  test("mixed position + opacity change produces ~, not →", () => {
+    const a = [snap({
+      key: "1",
+      x: 0,
+      opacity: 1
+    })];
+    const b = [snap({
+      key: "1",
+      x: 20,
+      opacity: 0.5
+    })];
+    const r = computeDiff(a, b);
+    expect(r.counts.changed).toBe(1);
+    expect(r.counts.moved).toBe(0);
+    expect(r.entries[0].type).toBe("~");
+    expect(r.entries[0].changedFields).toContain("x");
+    expect(r.entries[0].changedFields).toContain("opacity");
+  });
+  test("text change is reported", () => {
+    const a = [snap({
+      key: "1",
+      text: "Submit"
+    })];
+    const b = [snap({
+      key: "1",
+      text: "Submitting..."
+    })];
+    const r = computeDiff(a, b);
+    expect(r.counts.changed).toBe(1);
+    expect(r.entries[0].changedFields).toContain("text");
+  });
+  test("class addition is reported", () => {
+    const a = [snap({
+      key: "1",
+      classes: ["foo"]
+    })];
+    const b = [snap({
+      key: "1",
+      classes: ["foo", "active"]
+    })];
+    const r = computeDiff(a, b);
+    expect(r.counts.changed).toBe(1);
+    expect(r.entries[0].changedFields).toContain("classes");
+  });
+  test("pointer-events change is reported", () => {
+    const a = [snap({
+      key: "1",
+      pointerEvents: "auto"
+    })];
+    const b = [snap({
+      key: "1",
+      pointerEvents: "none"
+    })];
+    const r = computeDiff(a, b);
+    expect(r.counts.changed).toBe(1);
+    expect(r.entries[0].changedFields).toContain("pointerEvents");
+  });
+});
+describe("formatReport", () => {
+  test("no-changes report contains header and divider", () => {
+    const out = formatReport([], {
+      elapsedMs: 100,
+      settle: "clean"
+    });
+    expect(out).toContain("Visual diff");
+    expect(out).toContain("(no changes)");
+  });
+  test("summary line counts match entry types", () => {
+    const a = [snap({
+      key: "1"
+    }), snap({
+      key: "2"
+    })];
+    const b = [snap({
+      key: "1",
+      x: 20
+    }), snap({
+      key: "3",
+      id: "added"
+    })];
+    const r = computeDiff(a, b);
+    expect(r.text).toContain("1 added");
+    expect(r.text).toContain("1 removed");
+    expect(r.text).toContain("1 moved");
+  });
+});

package/dist/visualDiff/settle.d.ts

@@ -0,0 +1,3 @@
+export declare const DEFAULT_SETTLE_TIMEOUT_MS = 3000;
+export declare const MUTATION_SILENCE_MS = 150;
+export declare function waitForSettle(timeoutMs?: number, root?: Node): Promise<"clean" | "timeout">;

package/dist/visualDiff/settle.js

@@ -0,0 +1,50 @@
+export const DEFAULT_SETTLE_TIMEOUT_MS = 3000;
+export const MUTATION_SILENCE_MS = 150;
+function nextFrame() {
+  return new Promise(resolve => {
+    if (typeof requestAnimationFrame === "function") {
+      requestAnimationFrame(() => resolve());
+    } else {
+      setTimeout(() => resolve(), 16);
+    }
+  });
+}
+function animationsRunning() {
+  if (typeof document === "undefined" || typeof document.getAnimations !== "function") {
+    return false;
+  }
+  const anims = document.getAnimations();
+  for (const a of anims) {
+    if (a.playState === "running") return true;
+  }
+  return false;
+}
+export async function waitForSettle(timeoutMs = DEFAULT_SETTLE_TIMEOUT_MS, root) {
+  if (typeof document === "undefined" || typeof MutationObserver === "undefined") {
+    return "clean";
+  }
+  const observeTarget = root ?? document.documentElement;
+  const deadline = performance.now() + timeoutMs;
+  let lastMutation = performance.now();
+  const mo = new MutationObserver(() => {
+    lastMutation = performance.now();
+  });
+  mo.observe(observeTarget, {
+    childList: true,
+    subtree: true,
+    attributes: true,
+    characterData: true
+  });
+  try {
+    while (performance.now() < deadline) {
+      const sinceMutation = performance.now() - lastMutation;
+      if (!animationsRunning() && sinceMutation >= MUTATION_SILENCE_MS) {
+        return "clean";
+      }
+      await nextFrame();
+    }
+    return "timeout";
+  } finally {
+    mo.disconnect();
+  }
+}

package/dist/visualDiff/settle.test.d.ts

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

package/dist/visualDiff/settle.test.js

@@ -0,0 +1,65 @@
+import { describe, expect, test, beforeEach, afterEach, vi } from "vitest";
+import { waitForSettle } from "./settle";
+describe("waitForSettle", () => {
+  beforeEach(() => {
+    document.body.innerHTML = "";
+    if (typeof document.getAnimations !== "function") {
+      document.getAnimations = () => [];
+    }
+  });
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+  test("returns 'clean' when no mutations and no animations", async () => {
+    const result = await waitForSettle(500);
+    expect(result).toBe("clean");
+  });
+  test("returns 'timeout' when mutations keep firing past the deadline", async () => {
+    const interval = setInterval(() => {
+      const d = document.createElement("div");
+      document.body.appendChild(d);
+      setTimeout(() => d.remove(), 0);
+    }, 20);
+    const result = await waitForSettle(400);
+    clearInterval(interval);
+    expect(result).toBe("timeout");
+  });
+  test("settles after mutations stop", async () => {
+    const start = performance.now();
+    let mutationCount = 0;
+    const interval = setInterval(() => {
+      if (mutationCount >= 3) {
+        clearInterval(interval);
+        return;
+      }
+      const d = document.createElement("div");
+      document.body.appendChild(d);
+      mutationCount++;
+    }, 30);
+    const result = await waitForSettle(2000);
+    const elapsed = performance.now() - start;
+    expect(result).toBe("clean");
+    expect(elapsed).toBeLessThan(2000);
+  });
+  test("ignores mutations outside the provided root", async () => {
+    const root = document.createElement("div");
+    document.body.appendChild(root);
+    const interval = setInterval(() => {
+      const d = document.createElement("div");
+      document.body.appendChild(d);
+      setTimeout(() => d.remove(), 0);
+    }, 20);
+    const result = await waitForSettle(500, root);
+    clearInterval(interval);
+    expect(result).toBe("clean");
+  });
+  test("treats animations as non-idle", async () => {
+    const fakeAnim = {
+      playState: "running"
+    };
+    const spy = vi.spyOn(document, "getAnimations").mockReturnValue([fakeAnim]);
+    const result = await waitForSettle(300);
+    expect(result).toBe("timeout");
+    spy.mockRestore();
+  });
+});

package/dist/visualDiff/snapshot.d.ts

@@ -0,0 +1,4 @@
+import type { ElementSnapshot } from "./types";
+export declare const MAX_SNAPSHOT_ELEMENTS = 2000;
+export declare function takeSnapshot(root?: HTMLElement | SVGElement | null): ElementSnapshot[];
+export declare function __resetSnapshotWarningForTests(): void;

package/dist/visualDiff/snapshot.js

@@ -0,0 +1,84 @@
+import { getReferenceId } from "../functions/getReferenceId";
+import { isLocatorsOwnElement } from "../functions/isLocatorsOwnElement";
+export const MAX_SNAPSHOT_ELEMENTS = 2000;
+const TEXT_LIMIT = 80;
+let warnedOverflow = false;
+function truncateText(raw) {
+  if (!raw) return undefined;
+  const trimmed = raw.trim();
+  if (!trimmed) return undefined;
+  return trimmed.length > TEXT_LIMIT ? trimmed.slice(0, TEXT_LIMIT) : trimmed;
+}
+function snapshotElement(el) {
+  const rect = el.getBoundingClientRect();
+  const style = getComputedStyle(el);
+  const viewportWidth = typeof window !== "undefined" ? window.innerWidth : 0;
+  const viewportHeight = typeof window !== "undefined" ? window.innerHeight : 0;
+  const inViewport = rect.x + rect.width > 0 && rect.y + rect.height > 0 && rect.x < viewportWidth && rect.y < viewportHeight;
+  if (!inViewport) return null;
+  const opacity = parseFloat(style.opacity || "1");
+  const displayNone = style.display === "none";
+  const hidden = style.visibility === "hidden";
+  const zeroSize = rect.width <= 0 || rect.height <= 0;
+  const visible = !displayNone && !hidden && !zeroSize;
+  const rawClasses = typeof el.className === "string" ? el.className.split(/\s+/).filter(Boolean) : Array.from(el.classList);
+  const classes = rawClasses.filter(c => !c.startsWith("locatorjs-"));
+  const disabled = el.disabled === true;
+  const hasElementChildren = el.children.length > 0;
+  const text = hasElementChildren ? undefined : truncateText(el.textContent);
+  return {
+    key: String(getReferenceId(el)),
+    tagName: el.tagName.toLowerCase(),
+    id: el.id || undefined,
+    classes,
+    x: rect.x,
+    y: rect.y,
+    width: rect.width,
+    height: rect.height,
+    visible,
+    opacity: Number.isFinite(opacity) ? opacity : 1,
+    inViewport,
+    pointerEvents: style.pointerEvents || "auto",
+    disabled,
+    text
+  };
+}
+export function takeSnapshot(root) {
+  if (typeof document === "undefined") return [];
+  const out = [];
+  const candidates = [];
+  if (root) {
+    if (root instanceof HTMLElement || root instanceof SVGElement) {
+      candidates.push(root);
+    }
+    const descendants = root.querySelectorAll("*");
+    for (let i = 0; i < descendants.length; i++) {
+      candidates.push(descendants[i]);
+    }
+  } else {
+    const all = document.querySelectorAll("*");
+    for (let i = 0; i < all.length; i++) {
+      candidates.push(all[i]);
+    }
+  }
+  for (let i = 0; i < candidates.length; i++) {
+    const el = candidates[i];
+    if (!(el instanceof HTMLElement) && !(el instanceof SVGElement)) continue;
+    if (el instanceof HTMLElement && isLocatorsOwnElement(el)) continue;
+    const snap = snapshotElement(el);
+    if (!snap) continue;
+    out.push(snap);
+    if (out.length >= MAX_SNAPSHOT_ELEMENTS) {
+      if (!warnedOverflow) {
+        warnedOverflow = true;
+        // eslint-disable-next-line no-console
+        console.warn(`[treelocator/visualDiff] snapshot capped at ${MAX_SNAPSHOT_ELEMENTS} elements`);
+      }
+      break;
+    }
+  }
+  return out;
+}
+export function __resetSnapshotWarningForTests() {
+  warnedOverflow = false;
+}

package/dist/visualDiff/snapshot.test.d.ts

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