@treelocator/runtime 0.4.6 → 0.5.2

package/dist/dejitter/recorder.d.ts

@@ -47,10 +47,15 @@ export interface DejitterConfig {
         outlier: {
             ratioThreshold: number;
         };
+        lag: {
+            minDelay: number;
+            highDelay: number;
+            medDelay: number;
+        };
     };
 }
 export interface DejitterFinding {
-    type: 'jitter' | 'flicker' | 'shiver' | 'jump' | 'stutter' | 'stuck' | 'outlier';
+    type: 'jitter' | 'flicker' | 'shiver' | 'jump' | 'stutter' | 'stuck' | 'outlier' | 'lag';
     severity: 'high' | 'medium' | 'low' | 'info';
     elem: string;
     elemLabel: {
@@ -85,6 +90,7 @@ export interface DejitterAPI {
     getRaw(): {
         rawFrames: any[];
         mutations: any[];
+        interactions: any[];
     };
     toJSON(): string;
 }

package/dist/dejitter/recorder.js

@@ -48,6 +48,11 @@ export function createDejitterRecorder() {
       },
       outlier: {
         ratioThreshold: 3
+      },
+      lag: {
+        minDelay: 50,
+        highDelay: 200,
+        medDelay: 100
       }
     }
   };
@@ -59,12 +64,14 @@ export function createDejitterRecorder() {
   let rafId = null;
   let stopTimer = null;
   let mutationObserver = null;
+  let interactionAbort = null;
   let onStopCallbacks = [];
   let lastSeen = new Map();
   let rawFrames = [];
   let lastChangeTime = 0;
   let hasSeenChange = false;
   let mutations = [];
+  let interactions = [];
   let nextElemId = 0;
   function elemId(el) {
     if (!el.__dj_id) {
@@ -210,6 +217,24 @@ export function createDejitterRecorder() {
       characterData: true
     });
   }
+  function startInteractionListeners() {
+    interactionAbort = new AbortController();
+    const opts = {
+      capture: true,
+      signal: interactionAbort.signal
+    };
+    const handler = e => {
+      if (!recording) return;
+      const t = Math.round(performance.now() - startTime);
+      interactions.push({
+        t,
+        type: e.type
+      });
+    };
+    for (const evt of ['click', 'pointerdown', 'keydown']) {
+      document.addEventListener(evt, handler, opts);
+    }
+  }
 
   // --- Downsampling ---
 
@@ -736,6 +761,39 @@ export function createDejitterRecorder() {
     }
     return findings;
   }
+  function detectLagFindings(elements) {
+    const findings = [];
+    if (interactions.length === 0 || rawFrames.length === 0) return findings;
+    const lt = config.thresholds.lag;
+    for (const interaction of interactions) {
+      let firstFrame = null;
+      for (const frame of rawFrames) {
+        if (frame.t > interaction.t) {
+          firstFrame = frame;
+          break;
+        }
+      }
+      if (!firstFrame) continue;
+      const delay = firstFrame.t - interaction.t;
+      if (delay < lt.minDelay) continue;
+      const severity = delay >= lt.highDelay ? 'high' : delay >= lt.medDelay ? 'medium' : 'low';
+      const firstChange = firstFrame.changes[0];
+      const label = firstChange && elements[firstChange.id] || {
+        tag: '?',
+        cls: '',
+        text: ''
+      };
+      findings.push(makeFinding('lag', severity, firstChange?.id || '?', label, interaction.type, `${delay}ms between ${interaction.type} at t=${interaction.t}ms and first visual change at t=${firstFrame.t}ms`, {
+        lag: {
+          interactionType: interaction.type,
+          interactionT: interaction.t,
+          firstChangeT: firstFrame.t,
+          delay
+        }
+      }));
+    }
+    return findings;
+  }
   function deduplicateShivers(findings) {
     const shiverFindings = findings.filter(f => f.type === 'shiver');
     const otherFindings = findings.filter(f => f.type !== 'shiver');
@@ -769,6 +827,7 @@ export function createDejitterRecorder() {
     findings = findings.concat(detectJumpFindings(propStats, elements));
     findings = findings.concat(detectStutterFindings(propStats, elements));
     findings = findings.concat(detectStuckFindings(propStats, elements));
+    findings = findings.concat(detectLagFindings(elements));
     findings = deduplicateShivers(findings);
     const sevOrder = {
       high: 0,
@@ -810,6 +869,7 @@ export function createDejitterRecorder() {
     start() {
       rawFrames = [];
       mutations = [];
+      interactions = [];
       lastSeen = new Map();
       nextElemId = 0;
       recording = true;
@@ -818,6 +878,7 @@ export function createDejitterRecorder() {
       hasSeenChange = false;
       onStopCallbacks = [];
       startMutationObserver();
+      startInteractionListeners();
       rafId = requestAnimationFrame(loop);
       if (config.maxDuration > 0) {
         stopTimer = setTimeout(() => api.stop(), config.maxDuration);
@@ -830,6 +891,7 @@ export function createDejitterRecorder() {
       if (rafId) cancelAnimationFrame(rafId);
       if (stopTimer) clearTimeout(stopTimer);
       mutationObserver?.disconnect();
+      interactionAbort?.abort();
       const msg = `Stopped. ${rawFrames.length} raw frames, ${mutations.length} mutation events.`;
       for (const cb of onStopCallbacks) {
         try {
@@ -892,7 +954,8 @@ export function createDejitterRecorder() {
     getRaw() {
       return {
         rawFrames,
-        mutations
+        mutations,
+        interactions
       };
     },
     toJSON() {

package/dist/functions/formatAncestryChain.d.ts

@@ -20,8 +20,9 @@ export interface AncestryItem {
 export declare function collectAncestry(node: TreeNode): AncestryItem[];
 /**
  * Truncate ancestry to keep only the local context.
- * - If the clicked element has no filePath: keep up to the first ancestor with a file.
- * - If the clicked element has a filePath: keep up to the first ancestor with a DIFFERENT file.
+ * - If the clicked element has no file: keep up to the first ancestor with a file.
+ * - If the clicked element has a file: keep up to the first ancestor with a DIFFERENT file.
+ * Checks both client filePath and serverComponents for file info.
  * The ancestry array is bottom-up: index 0 = clicked element, last = root.
  */
 export declare function truncateAtFirstFile(items: AncestryItem[]): AncestryItem[];

package/dist/functions/formatAncestryChain.js

@@ -122,25 +122,41 @@ function getInnermostNamedComponent(item) {
   return undefined;
 }
 
+/**
+ * Get the effective file path from an AncestryItem, checking both
+ * client filePath and serverComponents (Next.js RSC, Phoenix, etc.).
+ */
+function getItemFilePath(item) {
+  if (item.filePath) return item.filePath;
+  if (item.serverComponents && item.serverComponents.length > 0) {
+    const comp = item.serverComponents.find(sc => sc.type === "component");
+    if (comp) return comp.filePath;
+    return item.serverComponents[0].filePath;
+  }
+  return undefined;
+}
+
 /**
  * Truncate ancestry to keep only the local context.
- * - If the clicked element has no filePath: keep up to the first ancestor with a file.
- * - If the clicked element has a filePath: keep up to the first ancestor with a DIFFERENT file.
+ * - If the clicked element has no file: keep up to the first ancestor with a file.
+ * - If the clicked element has a file: keep up to the first ancestor with a DIFFERENT file.
+ * Checks both client filePath and serverComponents for file info.
  * The ancestry array is bottom-up: index 0 = clicked element, last = root.
  */
 export function truncateAtFirstFile(items) {
   if (items.length === 0) return items;
-  const clickedFile = items[0]?.filePath;
+  const clickedFile = getItemFilePath(items[0]);
   if (!clickedFile) {
     // Clicked element has no file: find first ancestor with any file
-    const firstWithFile = items.findIndex(item => item.filePath);
+    const firstWithFile = items.findIndex(item => getItemFilePath(item));
     if (firstWithFile === -1) return items;
     return items.slice(0, firstWithFile + 1);
   }
 
   // Clicked element has a file: find first ancestor with a different file
   for (let i = 1; i < items.length; i++) {
-    if (items[i].filePath && items[i].filePath !== clickedFile) {
+    const ancestorFile = getItemFilePath(items[i]);
+    if (ancestorFile && ancestorFile !== clickedFile) {
       return items.slice(0, i + 1);
     }
   }

package/dist/functions/formatAncestryChain.test.js

@@ -367,6 +367,64 @@ describe("formatAncestryChain", () => {
       const result = truncateAtFirstFile(items);
       expect(result).toEqual(items);
     });
+    it("uses serverComponents file path when filePath is missing", () => {
+      const items = [{
+        elementName: "div",
+        componentName: "TurnActivityBox",
+        serverComponents: [{
+          name: "TurnActivityBox",
+          filePath: "components/MessageRow.tsx",
+          line: 921,
+          type: "component"
+        }]
+      }, {
+        elementName: "div",
+        componentName: "MessageRow",
+        serverComponents: [{
+          name: "MessageRow",
+          filePath: "components/chat/ChatViewport.tsx",
+          line: 917,
+          type: "component"
+        }]
+      }, {
+        elementName: "main",
+        componentName: "Home",
+        serverComponents: [{
+          name: "Home",
+          filePath: "app/page.tsx",
+          line: 817,
+          type: "component"
+        }]
+      }];
+      const result = truncateAtFirstFile(items);
+      expect(result).toEqual([items[0], items[1]]);
+    });
+    it("uses serverComponents when clicked element has no filePath but has serverComponents", () => {
+      const items = [{
+        elementName: "span",
+        componentName: "Button"
+      }, {
+        elementName: "div",
+        componentName: "Card",
+        serverComponents: [{
+          name: "Card",
+          filePath: "src/Card.tsx",
+          line: 10,
+          type: "component"
+        }]
+      }, {
+        elementName: "div",
+        componentName: "App",
+        serverComponents: [{
+          name: "App",
+          filePath: "src/App.tsx",
+          line: 1,
+          type: "component"
+        }]
+      }];
+      const result = truncateAtFirstFile(items);
+      expect(result).toEqual([items[0], items[1]]);
+    });
     it("returns empty array for empty input", () => {
       expect(truncateAtFirstFile([])).toEqual([]);
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@treelocator/runtime",
-  "version": "0.4.6",
+  "version": "0.5.2",
   "description": "TreeLocatorJS runtime for component ancestry tracking. Alt+click any element to copy its component tree to clipboard. Exposes window.__treelocator__ API for browser automation (Playwright, Puppeteer, Selenium, Cypress).",
   "keywords": [
     "locator",

package/src/dejitter/recorder.ts

@@ -20,11 +20,12 @@ export interface DejitterConfig {
     stutter: { velocityRatio: number; maxFrames: number; minVelocity: number };
     stuck: { minStillFrames: number; maxDelta: number; minSurroundingVelocity: number; highDuration: number; medDuration: number };
     outlier: { ratioThreshold: number };
+    lag: { minDelay: number; highDelay: number; medDelay: number };
   };
 }
 
 export interface DejitterFinding {
-  type: 'jitter' | 'flicker' | 'shiver' | 'jump' | 'stutter' | 'stuck' | 'outlier';
+  type: 'jitter' | 'flicker' | 'shiver' | 'jump' | 'stutter' | 'stuck' | 'outlier' | 'lag';
   severity: 'high' | 'medium' | 'low' | 'info';
   elem: string;
   elemLabel: { tag: string; cls: string; text: string };
@@ -50,7 +51,7 @@ export interface DejitterAPI {
   getData(): any;
   summary(json?: boolean): string | DejitterSummary;
   findings(json?: boolean): string | DejitterFinding[];
-  getRaw(): { rawFrames: any[]; mutations: any[] };
+  getRaw(): { rawFrames: any[]; mutations: any[]; interactions: any[] };
   toJSON(): string;
 }
 
@@ -70,6 +71,7 @@ export function createDejitterRecorder(): DejitterAPI {
       stutter: { velocityRatio: 0.3, maxFrames: 3, minVelocity: 0.5 },
       stuck: { minStillFrames: 3, maxDelta: 0.5, minSurroundingVelocity: 1, highDuration: 500, medDuration: 200 },
       outlier: { ratioThreshold: 3 },
+      lag: { minDelay: 50, highDelay: 200, medDelay: 100 },
     },
   };
 
@@ -79,6 +81,7 @@ export function createDejitterRecorder(): DejitterAPI {
   let rafId: number | null = null;
   let stopTimer: ReturnType<typeof setTimeout> | null = null;
   let mutationObserver: MutationObserver | null = null;
+  let interactionAbort: AbortController | null = null;
   let onStopCallbacks: Array<() => void> = [];
 
   let lastSeen = new Map<string, Record<string, any>>();
@@ -86,6 +89,7 @@ export function createDejitterRecorder(): DejitterAPI {
   let lastChangeTime = 0;
   let hasSeenChange = false;
   let mutations: any[] = [];
+  let interactions: Array<{ t: number; type: string }> = [];
   let nextElemId = 0;
 
   function elemId(el: any): string {
@@ -212,6 +216,19 @@ export function createDejitterRecorder(): DejitterAPI {
     });
   }
 
+  function startInteractionListeners(): void {
+    interactionAbort = new AbortController();
+    const opts: AddEventListenerOptions & { signal: AbortSignal } = { capture: true, signal: interactionAbort.signal };
+    const handler = (e: Event): void => {
+      if (!recording) return;
+      const t = Math.round(performance.now() - startTime);
+      interactions.push({ t, type: e.type });
+    };
+    for (const evt of ['click', 'pointerdown', 'keydown'] as const) {
+      document.addEventListener(evt, handler, opts);
+    }
+  }
+
   // --- Downsampling ---
 
   function downsample(): any[] {
@@ -778,6 +795,49 @@ export function createDejitterRecorder(): DejitterAPI {
     return findings;
   }
 
+  function detectLagFindings(elements: Record<string, any>): DejitterFinding[] {
+    const findings: DejitterFinding[] = [];
+    if (interactions.length === 0 || rawFrames.length === 0) return findings;
+
+    const lt = config.thresholds.lag;
+
+    for (const interaction of interactions) {
+      let firstFrame: { t: number; changes: any[] } | null = null;
+      for (const frame of rawFrames) {
+        if (frame.t > interaction.t) {
+          firstFrame = frame;
+          break;
+        }
+      }
+
+      if (!firstFrame) continue;
+
+      const delay = firstFrame.t - interaction.t;
+      if (delay < lt.minDelay) continue;
+
+      const severity = delay >= lt.highDelay ? 'high' : delay >= lt.medDelay ? 'medium' : 'low';
+
+      const firstChange = firstFrame.changes[0];
+      const label = (firstChange && elements[firstChange.id]) || { tag: '?', cls: '', text: '' };
+
+      findings.push(makeFinding(
+        'lag', severity,
+        firstChange?.id || '?', label, interaction.type,
+        `${delay}ms between ${interaction.type} at t=${interaction.t}ms and first visual change at t=${firstFrame.t}ms`,
+        {
+          lag: {
+            interactionType: interaction.type,
+            interactionT: interaction.t,
+            firstChangeT: firstFrame.t,
+            delay,
+          },
+        }
+      ));
+    }
+
+    return findings;
+  }
+
   function deduplicateShivers(findings: DejitterFinding[]): DejitterFinding[] {
     const shiverFindings = findings.filter((f) => f.type === 'shiver');
     const otherFindings = findings.filter((f) => f.type !== 'shiver');
@@ -814,6 +874,7 @@ export function createDejitterRecorder(): DejitterAPI {
     findings = findings.concat(detectJumpFindings(propStats, elements));
     findings = findings.concat(detectStutterFindings(propStats, elements));
     findings = findings.concat(detectStuckFindings(propStats, elements));
+    findings = findings.concat(detectLagFindings(elements));
     findings = deduplicateShivers(findings);
 
     const sevOrder: Record<string, number> = { high: 0, medium: 1, low: 2, info: 3 };
@@ -842,6 +903,7 @@ export function createDejitterRecorder(): DejitterAPI {
     start() {
       rawFrames = [];
       mutations = [];
+      interactions = [];
       lastSeen = new Map();
       nextElemId = 0;
       recording = true;
@@ -851,6 +913,7 @@ export function createDejitterRecorder(): DejitterAPI {
       onStopCallbacks = [];
 
       startMutationObserver();
+      startInteractionListeners();
       rafId = requestAnimationFrame(loop);
 
       if (config.maxDuration > 0) {
@@ -865,6 +928,7 @@ export function createDejitterRecorder(): DejitterAPI {
       if (rafId) cancelAnimationFrame(rafId);
       if (stopTimer) clearTimeout(stopTimer);
       mutationObserver?.disconnect();
+      interactionAbort?.abort();
 
       const msg = `Stopped. ${rawFrames.length} raw frames, ${mutations.length} mutation events.`;
 
@@ -921,7 +985,7 @@ export function createDejitterRecorder(): DejitterAPI {
     },
 
     getRaw() {
-      return { rawFrames, mutations };
+      return { rawFrames, mutations, interactions };
     },
 
     toJSON() {

package/src/functions/formatAncestryChain.test.ts

@@ -336,6 +336,34 @@ describe("formatAncestryChain", () => {
       expect(result).toEqual(items);
     });
 
+    it("uses serverComponents file path when filePath is missing", () => {
+      const items: AncestryItem[] = [
+        { elementName: "div", componentName: "TurnActivityBox", serverComponents: [{ name: "TurnActivityBox", filePath: "components/MessageRow.tsx", line: 921, type: "component" }] },
+        { elementName: "div", componentName: "MessageRow", serverComponents: [{ name: "MessageRow", filePath: "components/chat/ChatViewport.tsx", line: 917, type: "component" }] },
+        { elementName: "main", componentName: "Home", serverComponents: [{ name: "Home", filePath: "app/page.tsx", line: 817, type: "component" }] },
+      ];
+
+      const result = truncateAtFirstFile(items);
+      expect(result).toEqual([
+        items[0],
+        items[1],
+      ]);
+    });
+
+    it("uses serverComponents when clicked element has no filePath but has serverComponents", () => {
+      const items: AncestryItem[] = [
+        { elementName: "span", componentName: "Button" },
+        { elementName: "div", componentName: "Card", serverComponents: [{ name: "Card", filePath: "src/Card.tsx", line: 10, type: "component" }] },
+        { elementName: "div", componentName: "App", serverComponents: [{ name: "App", filePath: "src/App.tsx", line: 1, type: "component" }] },
+      ];
+
+      const result = truncateAtFirstFile(items);
+      expect(result).toEqual([
+        items[0],
+        items[1],
+      ]);
+    });
+
     it("returns empty array for empty input", () => {
       expect(truncateAtFirstFile([])).toEqual([]);
     });

package/src/functions/formatAncestryChain.ts

@@ -164,27 +164,43 @@ function getInnermostNamedComponent(item: AncestryItem | null | undefined): stri
   return undefined;
 }
 
+/**
+ * Get the effective file path from an AncestryItem, checking both
+ * client filePath and serverComponents (Next.js RSC, Phoenix, etc.).
+ */
+function getItemFilePath(item: AncestryItem): string | undefined {
+  if (item.filePath) return item.filePath;
+  if (item.serverComponents && item.serverComponents.length > 0) {
+    const comp = item.serverComponents.find((sc) => sc.type === "component");
+    if (comp) return comp.filePath;
+    return item.serverComponents[0]!.filePath;
+  }
+  return undefined;
+}
+
 /**
  * Truncate ancestry to keep only the local context.
- * - If the clicked element has no filePath: keep up to the first ancestor with a file.
- * - If the clicked element has a filePath: keep up to the first ancestor with a DIFFERENT file.
+ * - If the clicked element has no file: keep up to the first ancestor with a file.
+ * - If the clicked element has a file: keep up to the first ancestor with a DIFFERENT file.
+ * Checks both client filePath and serverComponents for file info.
  * The ancestry array is bottom-up: index 0 = clicked element, last = root.
  */
 export function truncateAtFirstFile(items: AncestryItem[]): AncestryItem[] {
   if (items.length === 0) return items;
 
-  const clickedFile = items[0]?.filePath;
+  const clickedFile = getItemFilePath(items[0]!);
 
   if (!clickedFile) {
     // Clicked element has no file: find first ancestor with any file
-    const firstWithFile = items.findIndex((item) => item.filePath);
+    const firstWithFile = items.findIndex((item) => getItemFilePath(item));
     if (firstWithFile === -1) return items;
     return items.slice(0, firstWithFile + 1);
   }
 
   // Clicked element has a file: find first ancestor with a different file
   for (let i = 1; i < items.length; i++) {
-    if (items[i]!.filePath && items[i]!.filePath !== clickedFile) {
+    const ancestorFile = getItemFilePath(items[i]!);
+    if (ancestorFile && ancestorFile !== clickedFile) {
       return items.slice(0, i + 1);
     }
   }