@treelocator/runtime 0.4.7 → 0.6.0

package/src/visualDiff/diff.test.ts

@@ -0,0 +1,167 @@
+import { describe, expect, test } from "vitest";
+import { computeDiff, formatReport } from "./diff";
+import type { ElementSnapshot } from "./types";
+
+function snap(overrides: Partial<ElementSnapshot> = {}): ElementSnapshot {
+  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: ElementSnapshot[] = [];
+    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/src/visualDiff/diff.ts

@@ -0,0 +1,242 @@
+import type { DeltaEntry, DeltaReport, ElementSnapshot } from "./types";
+
+export const POS_THRESHOLD = 4;
+export const SIZE_THRESHOLD = 2;
+export const OPACITY_THRESHOLD = 0.05;
+
+function arrayEq(a: string[], b: string[]): boolean {
+  if (a.length !== b.length) return false;
+  const set = new Set(b);
+  for (const v of a) if (!set.has(v)) return false;
+  return true;
+}
+
+function labelFor(snap: ElementSnapshot): string {
+  let label = snap.tagName;
+  if (snap.id) label += "#" + snap.id;
+  if (snap.classes.length > 0) label += "." + snap.classes[0];
+  if (snap.text) {
+    const t = snap.text.length > 30 ? snap.text.slice(0, 30) + "…" : snap.text;
+    label += ` "${t}"`;
+  }
+  return label;
+}
+
+function comparePair(
+  before: ElementSnapshot,
+  after: ElementSnapshot
+): { changed: string[] } {
+  const changed: string[] = [];
+
+  if (Math.abs(after.x - before.x) >= POS_THRESHOLD) changed.push("x");
+  if (Math.abs(after.y - before.y) >= POS_THRESHOLD) changed.push("y");
+  if (Math.abs(after.width - before.width) >= SIZE_THRESHOLD) {
+    changed.push("width");
+  }
+  if (Math.abs(after.height - before.height) >= SIZE_THRESHOLD) {
+    changed.push("height");
+  }
+  if (Math.abs(after.opacity - before.opacity) >= OPACITY_THRESHOLD) {
+    changed.push("opacity");
+  }
+  if (after.text !== before.text) changed.push("text");
+  if (after.disabled !== before.disabled) changed.push("disabled");
+  if (after.pointerEvents !== before.pointerEvents) {
+    changed.push("pointerEvents");
+  }
+  if (!arrayEq(after.classes, before.classes)) changed.push("classes");
+  if (after.inViewport !== before.inViewport) changed.push("inViewport");
+
+  return { changed };
+}
+
+export function computeDiff(
+  before: ElementSnapshot[],
+  after: ElementSnapshot[]
+): DeltaReport {
+  const beforeMap = new Map<string, ElementSnapshot>();
+  const afterMap = new Map<string, ElementSnapshot>();
+  for (const s of before) beforeMap.set(s.key, s);
+  for (const s of after) afterMap.set(s.key, s);
+
+  const entries: DeltaEntry[] = [];
+  let added = 0;
+  let removed = 0;
+  let changed = 0;
+  let moved = 0;
+
+  for (const [key, afterSnap] of afterMap) {
+    const beforeSnap = beforeMap.get(key);
+    if (!beforeSnap) {
+      if (afterSnap.visible) {
+        entries.push({
+          type: "+",
+          key,
+          label: labelFor(afterSnap),
+          after: afterSnap,
+        });
+        added++;
+      }
+      continue;
+    }
+
+    if (beforeSnap.visible && !afterSnap.visible) {
+      entries.push({
+        type: "-",
+        key,
+        label: labelFor(beforeSnap),
+        before: beforeSnap,
+      });
+      removed++;
+      continue;
+    }
+
+    const { changed: changedFields } = comparePair(beforeSnap, afterSnap);
+    if (changedFields.length === 0) continue;
+
+    const onlyPosition =
+      changedFields.length > 0 &&
+      changedFields.every((f) => f === "x" || f === "y");
+
+    if (onlyPosition) {
+      entries.push({
+        type: "→",
+        key,
+        label: labelFor(afterSnap),
+        before: beforeSnap,
+        after: afterSnap,
+        changedFields,
+      });
+      moved++;
+    } else {
+      entries.push({
+        type: "~",
+        key,
+        label: labelFor(afterSnap),
+        before: beforeSnap,
+        after: afterSnap,
+        changedFields,
+      });
+      changed++;
+    }
+  }
+
+  for (const [key, beforeSnap] of beforeMap) {
+    if (afterMap.has(key)) continue;
+    if (!beforeSnap.visible) continue;
+    entries.push({
+      type: "-",
+      key,
+      label: labelFor(beforeSnap),
+      before: beforeSnap,
+    });
+    removed++;
+  }
+
+  const meta = { elapsedMs: 0, settle: "clean" as const };
+  const text = formatReport(entries, meta);
+
+  return {
+    elapsedMs: 0,
+    settle: "clean",
+    counts: { added, removed, changed, moved },
+    entries,
+    text,
+  };
+}
+
+function fmtNum(n: number): string {
+  return Math.round(n).toString();
+}
+
+function fieldDelta(
+  field: string,
+  before: ElementSnapshot,
+  after: ElementSnapshot
+): string {
+  switch (field) {
+    case "x":
+      return `x ${fmtNum(before.x)}→${fmtNum(after.x)}`;
+    case "y":
+      return `y ${fmtNum(before.y)}→${fmtNum(after.y)}`;
+    case "width":
+      return `w ${fmtNum(before.width)}→${fmtNum(after.width)}`;
+    case "height":
+      return `h ${fmtNum(before.height)}→${fmtNum(after.height)}`;
+    case "opacity":
+      return `opacity ${before.opacity.toFixed(2)}→${after.opacity.toFixed(2)}`;
+    case "text":
+      return `text "${before.text ?? ""}"→"${after.text ?? ""}"`;
+    case "disabled":
+      return `disabled ${before.disabled}→${after.disabled}`;
+    case "pointerEvents":
+      return `pointer-events ${before.pointerEvents}→${after.pointerEvents}`;
+    case "classes":
+      return `classes [${before.classes.join(" ")}]→[${after.classes.join(" ")}]`;
+    case "inViewport":
+      return `inViewport ${before.inViewport}→${after.inViewport}`;
+    default:
+      return field;
+  }
+}
+
+export function formatReport(
+  entries: DeltaEntry[],
+  meta: { elapsedMs: number; settle: "clean" | "timeout" }
+): string {
+  const header = `Visual diff (${Math.round(meta.elapsedMs)}ms, settle: ${meta.settle})`;
+  const divider = "────────────────────────────────";
+
+  if (entries.length === 0) {
+    return `${header}\n${divider}\n(no changes)\n${divider}`;
+  }
+
+  const lines: string[] = [header, divider];
+
+  let added = 0;
+  let removed = 0;
+  let changed = 0;
+  let moved = 0;
+
+  for (const entry of entries) {
+    switch (entry.type) {
+      case "+": {
+        added++;
+        const s = entry.after!;
+        lines.push(
+          `+ ${entry.label}  (${fmtNum(s.x)},${fmtNum(s.y)}) ${fmtNum(s.width)}×${fmtNum(s.height)}`
+        );
+        break;
+      }
+      case "-": {
+        removed++;
+        lines.push(`- ${entry.label}`);
+        break;
+      }
+      case "~": {
+        changed++;
+        const deltas = (entry.changedFields ?? [])
+          .map((f) => fieldDelta(f, entry.before!, entry.after!))
+          .join(", ");
+        lines.push(`~ ${entry.label}: ${deltas}`);
+        break;
+      }
+      case "→": {
+        moved++;
+        const b = entry.before!;
+        const a = entry.after!;
+        lines.push(
+          `→ ${entry.label}: (${fmtNum(b.x)},${fmtNum(b.y)})→(${fmtNum(a.x)},${fmtNum(a.y)})`
+        );
+        break;
+      }
+    }
+  }
+
+  lines.push(divider);
+  lines.push(
+    `${entries.length} changes: ${added} added, ${removed} removed, ${changed} changed, ${moved} moved`
+  );
+
+  return lines.join("\n");
+}

package/src/visualDiff/settle.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, test, beforeEach, afterEach, vi } from "vitest";
+import { waitForSettle } from "./settle";
+
+describe("waitForSettle", () => {
+  beforeEach(() => {
+    document.body.innerHTML = "";
+    if (typeof (document as any).getAnimations !== "function") {
+      (document as any).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" } as unknown as Animation;
+    const spy = vi
+      .spyOn(document, "getAnimations")
+      .mockReturnValue([fakeAnim]);
+
+    const result = await waitForSettle(300);
+    expect(result).toBe("timeout");
+    spy.mockRestore();
+  });
+});

package/src/visualDiff/settle.ts

@@ -0,0 +1,62 @@
+export const DEFAULT_SETTLE_TIMEOUT_MS = 3000;
+export const MUTATION_SILENCE_MS = 150;
+
+function nextFrame(): Promise<void> {
+  return new Promise((resolve) => {
+    if (typeof requestAnimationFrame === "function") {
+      requestAnimationFrame(() => resolve());
+    } else {
+      setTimeout(() => resolve(), 16);
+    }
+  });
+}
+
+function animationsRunning(): boolean {
+  if (
+    typeof document === "undefined" ||
+    typeof (document as Document).getAnimations !== "function"
+  ) {
+    return false;
+  }
+  const anims = (document as Document).getAnimations();
+  for (const a of anims) {
+    if (a.playState === "running") return true;
+  }
+  return false;
+}
+
+export async function waitForSettle(
+  timeoutMs: number = DEFAULT_SETTLE_TIMEOUT_MS,
+  root?: Node
+): Promise<"clean" | "timeout"> {
+  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();
+  }
+}