@treelocator/runtime 0.3.1 → 0.4.0

package/dist/functions/enrichAncestrySourceMaps.js

@@ -3,14 +3,21 @@ import { normalizeFilePath } from "./normalizeFilePath";
 
 /**
  * Check if any DOM element has React 19 fibers (with _debugStack instead of _debugSource).
+ * Must walk the _debugOwner chain because DOM element fibers (HostComponent) never have
+ * _debugStack — only function component fibers do.
  */
 function isReact19Environment() {
   const el = document.querySelector("[class]") || document.body;
   if (!el) return false;
   const fiberKey = Object.keys(el).find(k => k.startsWith("__reactFiber$"));
   if (!fiberKey) return false;
-  const fiber = el[fiberKey];
-  return !fiber?._debugSource && !!fiber?._debugStack;
+  let fiber = el[fiberKey];
+  while (fiber) {
+    if (fiber._debugSource) return false; // React 18
+    if (fiber._debugStack) return true; // React 19
+    fiber = fiber._debugOwner || null;
+  }
+  return false;
 }
 
 /**

package/dist/functions/formatAncestryChain.js

@@ -105,6 +105,22 @@ export function collectAncestry(node) {
   }
   return items;
 }
+function getInnermostNamedComponent(item) {
+  if (!item) return undefined;
+  if (item.ownerComponents && item.ownerComponents.length > 0) {
+    // Find the innermost non-Anonymous component
+    for (let i = item.ownerComponents.length - 1; i >= 0; i--) {
+      if (item.ownerComponents[i].name !== "Anonymous") {
+        return item.ownerComponents[i].name;
+      }
+    }
+  }
+  // Fall back to componentName if it's not Anonymous
+  if (item.componentName && item.componentName !== "Anonymous") {
+    return item.componentName;
+  }
+  return undefined;
+}
 export function formatAncestryChain(items) {
   if (items.length === 0) {
     return "";
@@ -118,11 +134,12 @@ export function formatAncestryChain(items) {
     const prefix = index === 0 ? "" : "└─ ";
 
     // Get the previous item's component to detect component boundaries
+    // Ignore "Anonymous" when resolving component names — these are framework internals
     const prevItem = index > 0 ? reversed[index - 1] : null;
-    const prevComponentName = prevItem?.componentName || prevItem?.ownerComponents?.[prevItem.ownerComponents.length - 1]?.name;
+    const prevComponentName = getInnermostNamedComponent(prevItem);
 
-    // Get current item's innermost component
-    const currentComponentName = item.ownerComponents?.[item.ownerComponents.length - 1]?.name || item.componentName;
+    // Get current item's innermost named component
+    const currentComponentName = getInnermostNamedComponent(item);
 
     // Determine the display name for the element
     // Use component name ONLY when crossing a component boundary (root element of a component)
@@ -132,14 +149,17 @@ export function formatAncestryChain(items) {
     const isComponentBoundary = currentComponentName && currentComponentName !== prevComponentName;
     if (isComponentBoundary) {
       if (item.ownerComponents && item.ownerComponents.length > 0) {
-        // Use innermost component as display name, show outer ones in "in X > Y"
-        const innermost = item.ownerComponents[item.ownerComponents.length - 1];
+        // Use innermost named component as display name, show outer ones in "in X > Y"
+        // Filter out "Anonymous" components — these are framework-internal wrappers
+        // (e.g. Next.js App Router) that add noise without useful context
+        const named = item.ownerComponents.filter(c => c.name !== "Anonymous");
+        const innermost = named[named.length - 1];
         if (innermost) {
           displayName = innermost.name;
           // Outer components (excluding innermost)
-          outerComponents = item.ownerComponents.slice(0, -1).map(c => c.name);
+          outerComponents = named.slice(0, -1).map(c => c.name);
         }
-      } else if (item.componentName) {
+      } else if (item.componentName && item.componentName !== "Anonymous") {
         displayName = item.componentName;
       }
     }

package/dist/functions/formatAncestryChain.test.js

@@ -125,4 +125,118 @@ describe("formatAncestryChain", () => {
     // Single component becomes the display name, no "in X" needed
     expect(result).toBe("Button at src/Button.tsx:10");
   });
+  describe("Anonymous component filtering", () => {
+    it("filters Anonymous from outer components in 'in X > Y' display", () => {
+      const items = [{
+        elementName: "div",
+        nthChild: 2,
+        componentName: "Anonymous",
+        filePath: "app/page.tsx",
+        line: 82,
+        ownerComponents: [{
+          name: "Anonymous"
+        }, {
+          name: "Home",
+          filePath: "app/page.tsx",
+          line: 82
+        }]
+      }, {
+        elementName: "div",
+        componentName: "App",
+        filePath: "src/App.tsx",
+        line: 1
+      }];
+      const result = formatAncestryChain(items);
+      // "Anonymous" should be filtered out — just "Home" as display name, no "in Anonymous"
+      expect(result).toBe(`App at src/App.tsx:1
+    └─ Home:nth-child(2) at app/page.tsx:82`);
+    });
+    it("filters Anonymous from component boundary detection", () => {
+      // When prev item's innermost component is Anonymous, it shouldn't count
+      // as a different component from the current item
+      const items = [{
+        elementName: "p",
+        componentName: "Home",
+        filePath: "app/page.tsx",
+        line: 100
+      }, {
+        elementName: "div",
+        componentName: "Anonymous",
+        filePath: "app/page.tsx",
+        line: 82,
+        ownerComponents: [{
+          name: "Anonymous"
+        }, {
+          name: "Home",
+          filePath: "app/page.tsx",
+          line: 82
+        }]
+      }];
+      const result = formatAncestryChain(items);
+      // Both items resolve to "Home" — no boundary crossing, so element name for child
+      expect(result).toBe(`Home at app/page.tsx:82
+    └─ p at app/page.tsx:100`);
+    });
+    it("handles all-Anonymous owner chain gracefully", () => {
+      const items = [{
+        elementName: "div",
+        componentName: "Anonymous",
+        filePath: "app/layout.tsx",
+        line: 10,
+        ownerComponents: [{
+          name: "Anonymous"
+        }, {
+          name: "Anonymous"
+        }]
+      }];
+      const result = formatAncestryChain(items);
+      // All components are Anonymous — falls back to element name
+      expect(result).toBe("div at app/layout.tsx:10");
+    });
+    it("skips Anonymous-only componentName without ownerComponents", () => {
+      const items = [{
+        elementName: "main",
+        componentName: "Anonymous",
+        filePath: "app/page.tsx",
+        line: 50
+      }, {
+        elementName: "div",
+        componentName: "App",
+        filePath: "src/App.tsx",
+        line: 1
+      }];
+      const result = formatAncestryChain(items);
+      // "Anonymous" componentName should not be used as display name
+      expect(result).toBe(`App at src/App.tsx:1
+    └─ main at app/page.tsx:50`);
+    });
+    it("preserves named components when mixed with Anonymous", () => {
+      const items = [{
+        elementName: "div",
+        componentName: "Sidebar",
+        filePath: "src/Sidebar.tsx",
+        line: 20,
+        ownerComponents: [{
+          name: "Sidebar",
+          filePath: "src/Sidebar.tsx",
+          line: 20
+        }, {
+          name: "Anonymous"
+        }, {
+          name: "GlassPanel",
+          filePath: "src/GlassPanel.tsx",
+          line: 5
+        }]
+      }, {
+        elementName: "div",
+        componentName: "App",
+        filePath: "src/App.tsx",
+        line: 1
+      }];
+      const result = formatAncestryChain(items);
+      // Anonymous in the middle is filtered, Sidebar (outer) and GlassPanel (inner) remain
+      expect(result).toBe(`App at src/App.tsx:1
+    └─ GlassPanel in Sidebar at src/Sidebar.tsx:20`);
+    });
+  });
 });

package/dist/functions/getUsableName.js

@@ -32,16 +32,38 @@ export function getUsableName(fiber) {
   if (fiber.elementType.name) {
     return fiber.elementType.name;
   }
-  // Not sure about this
   if (fiber.elementType.displayName) {
     return fiber.elementType.displayName;
   }
-  // Used in rect.memo
+  // Used in React.memo
   if (fiber.elementType.type?.name) {
     return fiber.elementType.type.name;
   }
+  if (fiber.elementType.type?.displayName) {
+    return fiber.elementType.type.displayName;
+  }
+  // React.forwardRef wraps the render function in .render
+  if (fiber.elementType.render?.name) {
+    return fiber.elementType.render.name;
+  }
+  if (fiber.elementType.render?.displayName) {
+    return fiber.elementType.render.displayName;
+  }
+  // React lazy components store resolved module in _payload._result
   if (fiber.elementType._payload?._result?.name) {
     return fiber.elementType._payload._result.name;
   }
+  if (fiber.elementType._payload?._result?.displayName) {
+    return fiber.elementType._payload._result.displayName;
+  }
+  // fiber.type can differ from elementType in some React internals
+  if (fiber.type && typeof fiber.type !== "string" && fiber.type !== fiber.elementType) {
+    if (fiber.type.name) {
+      return fiber.type.name;
+    }
+    if (fiber.type.displayName) {
+      return fiber.type.displayName;
+    }
+  }
   return "Anonymous";
 }

package/dist/output.css

@@ -827,6 +827,10 @@ input:where([type='file']):focus {
   position: relative;
 }
 
+.sticky {
+  position: sticky;
+}
+
 .-bottom-7 {
   bottom: -1.75rem;
 }
@@ -1758,10 +1762,19 @@ input:where([type='file']):focus {
   --tw-ring-color: rgb(30 64 175 / var(--tw-ring-opacity, 1));
 }
 
+.blur {
+  --tw-blur: blur(8px);
+  filter: var(--tw-blur) var(--tw-brightness) var(--tw-contrast) var(--tw-grayscale) var(--tw-hue-rotate) var(--tw-invert) var(--tw-saturate) var(--tw-sepia) var(--tw-drop-shadow);
+}
+
 .filter {
   filter: var(--tw-blur) var(--tw-brightness) var(--tw-contrast) var(--tw-grayscale) var(--tw-hue-rotate) var(--tw-invert) var(--tw-saturate) var(--tw-sepia) var(--tw-drop-shadow);
 }
 
+.backdrop-filter {
+  backdrop-filter: var(--tw-backdrop-blur) var(--tw-backdrop-brightness) var(--tw-backdrop-contrast) var(--tw-backdrop-grayscale) var(--tw-backdrop-hue-rotate) var(--tw-backdrop-invert) var(--tw-backdrop-opacity) var(--tw-backdrop-saturate) var(--tw-backdrop-sepia);
+}
+
 .transition {
   transition-property: color, background-color, border-color, text-decoration-color, fill, stroke, opacity, box-shadow, transform, filter, backdrop-filter;
   transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@treelocator/runtime",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "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",
@@ -73,5 +73,5 @@
     "directory": "packages/runtime"
   },
   "license": "MIT",
-  "gitHead": "f53c9d698aaee64837698b5c6803df5485d2a229"
+  "gitHead": "4f74117d9076e063c072c6b172f785e5572b3be9"
 }

package/src/browserApi.ts

@@ -6,6 +6,8 @@ import {
   AncestryItem,
 } from "./functions/formatAncestryChain";
 import { enrichAncestryWithSourceMaps } from "./functions/enrichAncestrySourceMaps";
+import type { DejitterFinding, DejitterSummary } from "./dejitter/recorder";
+import type { InteractionEvent } from "./components/RecordingResults";
 
 export interface LocatorJSAPI {
   /**
@@ -107,6 +109,53 @@ export interface LocatorJSAPI {
    * console.log(help);
    */
   help(): string;
+
+  /**
+   * Replay the last recorded interaction sequence.
+   * Dispatches the recorded clicks at the original positions and timing.
+   * Must have a completed recording with interactions to replay.
+   *
+   * @example
+   * // In browser console
+   * window.__treelocator__.replay();
+   *
+   * @example
+   * // In Playwright
+   * await page.evaluate(() => window.__treelocator__.replay());
+   */
+  replay(): void;
+
+  /**
+   * Replay the last recorded interaction sequence while recording an element's property changes.
+   * Combines replay and dejitter recording: plays back stored clicks at original timing while
+   * tracking visual changes (opacity, transform, position, size) on the target element.
+   * Returns the dejitter analysis results when replay completes.
+   *
+   * @param elementOrSelector - HTMLElement or CSS selector for the element to record during replay
+   * @returns Promise resolving to recording results with findings, summary, and interaction log
+   *
+   * @example
+   * // Record the sliding panel while replaying user clicks
+   * const results = await window.__treelocator__.replayWithRecord('[data-locatorjs-id="SlidingPanel"]');
+   * console.log(results.findings); // anomaly analysis
+   * console.log(results.path);     // component ancestry
+   *
+   * @example
+   * // In Playwright - automated regression test
+   * const results = await page.evaluate(async () => {
+   *   return await window.__treelocator__.replayWithRecord('.my-panel');
+   * });
+   * expect(results.findings.filter(f => f.severity === 'high')).toHaveLength(0);
+   */
+  replayWithRecord(
+    elementOrSelector: HTMLElement | string
+  ): Promise<{
+    path: string;
+    findings: DejitterFinding[];
+    summary: DejitterSummary | null;
+    data: any;
+    interactions: InteractionEvent[];
+  } | null>;
 }
 
 let adapterId: AdapterId | undefined;
@@ -179,7 +228,22 @@ METHODS:
      console.log(data.path)      // formatted string
      console.log(data.ancestry)  // structured array
 
-4. help()
+4. replay()
+   Replays the last recorded interaction sequence as a macro.
+
+   Usage:
+     window.__treelocator__.replay()
+
+5. replayWithRecord(elementOrSelector)
+   Replays stored interactions while recording element changes.
+   Returns dejitter analysis when replay completes.
+
+   Usage:
+     const results = await window.__treelocator__.replayWithRecord('[data-locatorjs-id="SlidingPanel"]')
+     console.log(results.findings)  // anomaly analysis
+     console.log(results.path)      // component ancestry
+
+6. help()
    Displays this help message.
 
 PLAYWRIGHT EXAMPLES:
@@ -280,6 +344,15 @@ export function createBrowserAPI(
     help(): string {
       return HELP_TEXT;
     },
+
+    replay() {
+      // Replaced by Runtime component once mounted
+    },
+
+    replayWithRecord() {
+      // Replaced by Runtime component once mounted
+      return Promise.resolve(null);
+    },
   };
 }
 

package/src/components/RecordingOutline.tsx

@@ -0,0 +1,66 @@
+import { createSignal, onCleanup, onMount } from "solid-js";
+
+type RecordingOutlineProps = {
+  element: HTMLElement;
+};
+
+export function RecordingOutline(props: RecordingOutlineProps) {
+  const [box, setBox] = createSignal(props.element.getBoundingClientRect());
+
+  let rafId: number;
+  const updateBox = () => {
+    setBox(props.element.getBoundingClientRect());
+    rafId = requestAnimationFrame(updateBox);
+  };
+  onMount(() => {
+    rafId = requestAnimationFrame(updateBox);
+  });
+  onCleanup(() => cancelAnimationFrame(rafId));
+
+  return (
+    <div
+      style={{
+        position: "fixed",
+        "z-index": "2",
+        left: box().x + "px",
+        top: box().y + "px",
+        width: box().width + "px",
+        height: box().height + "px",
+        border: "2px dashed #ef4444",
+        "border-radius": "2px",
+        "pointer-events": "none",
+      }}
+    >
+      <div
+        style={{
+          position: "absolute",
+          top: "-22px",
+          left: "4px",
+          display: "flex",
+          "align-items": "center",
+          gap: "4px",
+          padding: "2px 8px",
+          background: "rgba(239, 68, 68, 0.9)",
+          "border-radius": "4px",
+          color: "#fff",
+          "font-size": "10px",
+          "font-family": "system-ui, sans-serif",
+          "font-weight": "600",
+          "letter-spacing": "0.5px",
+          "white-space": "nowrap",
+        }}
+      >
+        <div
+          style={{
+            width: "6px",
+            height: "6px",
+            "border-radius": "50%",
+            background: "#fff",
+            animation: "treelocator-rec-pulse 1s ease-in-out infinite",
+          }}
+        />
+        REC
+      </div>
+    </div>
+  );
+}