@treelocator/runtime 0.3.2 → 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/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.2",
+  "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": "511af51703d71e9a5c4d4990c66140b283f05afe"
+  "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>
+  );
+}

package/src/components/RecordingResults.tsx

@@ -0,0 +1,287 @@
+import { For, Show } from "solid-js";
+import type { DejitterFinding, DejitterSummary } from "../dejitter/recorder";
+
+export type InteractionEvent = {
+  t: number;
+  type: string;
+  target: string;
+  x: number;
+  y: number;
+};
+
+type RecordingResultsProps = {
+  findings: DejitterFinding[];
+  summary: DejitterSummary | null;
+  data: any;
+  elementPath: string;
+  interactions: InteractionEvent[];
+  onDismiss: () => void;
+  onReplay?: () => void;
+  replaying?: boolean;
+  onToast?: (msg: string) => void;
+  hasPrevious?: boolean;
+  onLoadPrevious?: () => void;
+  hasNext?: boolean;
+  onLoadNext?: () => void;
+};
+
+const SEVERITY_COLORS: Record<string, string> = {
+  high: "#ef4444",
+  medium: "#f59e0b",
+  low: "#eab308",
+  info: "#9ca3af",
+};
+
+function formatDataForClipboard(
+  data: any,
+  elementPath: string,
+  summary: DejitterSummary | null,
+  findings: DejitterFinding[],
+  interactions: InteractionEvent[]
+): string {
+  const lines: string[] = [];
+
+  // Element ancestry path from treelocator
+  if (elementPath) {
+    lines.push(`Element: ${elementPath}`);
+  }
+
+  // Header
+  lines.push(`Recording: ${Math.round(summary?.duration ?? 0)}ms, ${summary?.rawFrameCount ?? 0} frames`);
+  lines.push('');
+
+  // Property changes
+  if (data?.propStats?.props && data.propStats.props.length > 0) {
+    lines.push('Changed properties:');
+    for (const p of data.propStats.props) {
+      if (p.raw === 0) continue;
+      lines.push(`  ${p.prop}: ${p.raw} changes (${p.mode})`);
+    }
+    lines.push('');
+  }
+
+  // Samples with actual values — replace dejitter element IDs with the ancestry path
+  if (data?.samples && data.samples.length > 0) {
+    lines.push('Timeline:');
+    for (const frame of data.samples) {
+      for (const change of frame.changes) {
+        const { id, ...props } = change;
+        const propEntries = Object.entries(props);
+        if (propEntries.length > 0) {
+          const vals = propEntries.map(([k, v]) => `${k}=${v}`).join(', ');
+          lines.push(`  ${frame.t}ms: ${vals}`);
+        }
+      }
+    }
+    lines.push('');
+  }
+
+  // Findings — replace dejitter element IDs in descriptions
+  if (findings.length > 0) {
+    lines.push('Anomalies:');
+    for (const f of findings) {
+      lines.push(`  [${f.severity}] ${f.type}: ${f.description}`);
+    }
+    lines.push('');
+  }
+
+  // Interactions
+  if (interactions.length > 0) {
+    lines.push('User interactions:');
+    for (const evt of interactions) {
+      lines.push(`  ${evt.t}ms ${evt.type} ${evt.target} (${evt.x},${evt.y})`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+const buttonStyle = (active?: boolean) => ({
+  cursor: "pointer",
+  padding: "4px 10px",
+  "border-radius": "4px",
+  background: active ? "rgba(59, 130, 246, 0.2)" : "rgba(255, 255, 255, 0.08)",
+  color: active ? "#60a5fa" : "#9ca3af",
+  "font-size": "11px",
+  "font-weight": "600",
+  "line-height": "1.4",
+  transition: "background 0.15s, color 0.15s",
+});
+
+export function RecordingResults(props: RecordingResultsProps) {
+  const duration = () => props.summary?.duration ?? 0;
+  const frameCount = () => props.summary?.rawFrameCount ?? 0;
+
+  function handleCopy() {
+    const text = formatDataForClipboard(props.data, props.elementPath, props.summary, props.findings, props.interactions);
+    navigator.clipboard.writeText(text).then(() => {
+      props.onToast?.("Copied to clipboard");
+    });
+  }
+
+  return (
+    <div
+      style={{
+        position: "fixed",
+        bottom: "84px",
+        right: "20px",
+        "z-index": "2147483646",
+        width: "340px",
+        "max-height": "400px",
+        "overflow-y": "auto",
+        background: "rgba(15, 15, 15, 0.92)",
+        "backdrop-filter": "blur(12px)",
+        "border-radius": "12px",
+        border: "1px solid rgba(255, 255, 255, 0.1)",
+        "box-shadow": "0 8px 32px rgba(0, 0, 0, 0.4)",
+        color: "#e5e5e5",
+        "font-family": "system-ui, -apple-system, sans-serif",
+        "font-size": "12px",
+        "pointer-events": "auto",
+      }}
+    >
+      {/* Header */}
+      <div
+        style={{
+          display: "flex",
+          "align-items": "center",
+          "justify-content": "space-between",
+          padding: "12px 14px 8px",
+          "border-bottom": "1px solid rgba(255, 255, 255, 0.08)",
+        }}
+      >
+        <div>
+          <div style={{ "font-weight": "600", "font-size": "13px", color: "#fff" }}>
+            Recording Results
+          </div>
+          <div style={{ color: "#9ca3af", "margin-top": "2px" }}>
+            {Math.round(duration())}ms &middot; {frameCount()} frames
+          </div>
+        </div>
+        <div style={{ display: "flex", "align-items": "center", gap: "4px" }}>
+          <div style={buttonStyle()} onClick={handleCopy}>
+            Copy
+          </div>
+          {props.onReplay && (
+            <div style={buttonStyle(props.replaying)} onClick={props.onReplay}>
+              {props.replaying ? "Replaying..." : "Replay"}
+            </div>
+          )}
+          {props.hasPrevious && props.onLoadPrevious && (
+            <div style={buttonStyle()} onClick={props.onLoadPrevious}>
+              Prev
+            </div>
+          )}
+          {props.hasNext && props.onLoadNext && (
+            <div style={buttonStyle()} onClick={props.onLoadNext}>
+              Next
+            </div>
+          )}
+          <div
+            style={{
+              cursor: "pointer",
+              padding: "4px 8px",
+              "border-radius": "4px",
+              color: "#9ca3af",
+              "font-size": "16px",
+              "line-height": "1",
+            }}
+            onClick={props.onDismiss}
+          >
+            &times;
+          </div>
+        </div>
+      </div>
+
+      {/* Findings */}
+      <div style={{ padding: "8px 14px" }}>
+        <Show
+          when={props.findings.length > 0}
+          fallback={
+            <div
+              style={{
+                display: "flex",
+                "align-items": "center",
+                gap: "6px",
+                padding: "8px 0",
+                color: "#4ade80",
+              }}
+            >
+              <span style={{ "font-size": "14px" }}>&#10003;</span>
+              No anomalies detected
+            </div>
+          }
+        >
+          <div style={{ "margin-bottom": "4px", color: "#9ca3af", "font-size": "11px", "text-transform": "uppercase", "letter-spacing": "0.5px" }}>
+            Findings ({props.findings.length})
+          </div>
+          <For each={props.findings}>
+            {(finding) => (
+              <div
+                style={{
+                  display: "flex",
+                  "align-items": "flex-start",
+                  gap: "8px",
+                  padding: "6px 0",
+                  "border-bottom": "1px solid rgba(255, 255, 255, 0.05)",
+                }}
+              >
+                <div
+                  style={{
+                    width: "8px",
+                    height: "8px",
+                    "border-radius": "50%",
+                    background: SEVERITY_COLORS[finding.severity] || "#9ca3af",
+                    "flex-shrink": "0",
+                    "margin-top": "3px",
+                  }}
+                />
+                <div style={{ "min-width": "0" }}>
+                  <div style={{ display: "flex", gap: "6px", "align-items": "center" }}>
+                    <span style={{ "font-weight": "600", color: "#fff" }}>{finding.type}</span>
+                    <span style={{ color: SEVERITY_COLORS[finding.severity], "font-size": "11px" }}>
+                      {finding.severity}
+                    </span>
+                  </div>
+                  <div
+                    style={{
+                      color: "#a1a1aa",
+                      "margin-top": "2px",
+                      "line-height": "1.4",
+                      "word-break": "break-word",
+                    }}
+                  >
+                    {finding.description}
+                  </div>
+                </div>
+              </div>
+            )}
+          </For>
+        </Show>
+      </div>
+
+      {/* Interactions */}
+      <Show when={props.interactions.length > 0}>
+        <div
+          style={{
+            padding: "8px 14px 12px",
+            "border-top": "1px solid rgba(255, 255, 255, 0.08)",
+          }}
+        >
+          <div style={{ "margin-bottom": "4px", color: "#9ca3af", "font-size": "11px", "text-transform": "uppercase", "letter-spacing": "0.5px" }}>
+            Interactions ({props.interactions.length})
+          </div>
+          <For each={props.interactions}>
+            {(evt) => (
+              <div style={{ padding: "3px 0", color: "#a1a1aa", "font-family": "monospace", "font-size": "11px" }}>
+                <span style={{ color: "#9ca3af" }}>{evt.t}ms</span>{" "}
+                <span style={{ color: "#60a5fa" }}>{evt.type}</span>{" "}
+                <span>{evt.target}</span>
+              </div>
+            )}
+          </For>
+        </div>
+      </Show>
+    </div>
+  );
+}