@stigmer/react 0.3.3 → 0.4.0

package/src/internal/dev/__tests__/use-key-stability.test.ts

@@ -0,0 +1,124 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { renderHook } from "@testing-library/react";
+import { useKeyStability } from "../use-key-stability";
+
+interface KeyedItem {
+  readonly key: string;
+  readonly kind: string;
+}
+
+function makeItems(...specs: Array<[string, string]>): KeyedItem[] {
+  return specs.map(([key, kind]) => ({ key, kind }));
+}
+
+describe("useKeyStability", () => {
+  let warnSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    warnSpy.mockRestore();
+  });
+
+  it("stays silent on first render (no previous to compare)", () => {
+    renderHook(() =>
+      useKeyStability(makeItems(["msg-1", "message"], ["msg-2", "message"])),
+    );
+
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it("stays silent when keys are stable across renders", () => {
+    const { rerender } = renderHook(
+      ({ items }) => useKeyStability(items),
+      {
+        initialProps: {
+          items: makeItems(["msg-1", "message"], ["msg-2", "message"]),
+        },
+      },
+    );
+
+    rerender({
+      items: makeItems(["msg-1", "message"], ["msg-2", "message"]),
+    });
+
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it("stays silent when items are appended (no swap)", () => {
+    const { rerender } = renderHook(
+      ({ items }) => useKeyStability(items),
+      {
+        initialProps: {
+          items: makeItems(["msg-1", "message"]),
+        },
+      },
+    );
+
+    rerender({
+      items: makeItems(["msg-1", "message"], ["msg-2", "message"]),
+    });
+
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it("warns when a key is swapped at the same index", () => {
+    const { rerender } = renderHook(
+      ({ items }) => useKeyStability(items),
+      {
+        initialProps: {
+          items: makeItems(
+            ["e0-m0", "message"],
+            ["e0-m1", "message"],
+          ),
+        },
+      },
+    );
+
+    rerender({
+      items: makeItems(
+        ["e0-m0", "message"],
+        ["e1-m0", "message"],
+      ),
+    });
+
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    const msg = warnSpy.mock.calls[0][0] as string;
+    expect(msg).toContain("[stgm:perf:keys]");
+    expect(msg).toContain("e0-m1");
+    expect(msg).toContain("e1-m0");
+    expect(msg).toContain("index 1");
+  });
+
+  it("warns about widespread instability when many keys swap", () => {
+    const { rerender } = renderHook(
+      ({ items }) => useKeyStability(items),
+      {
+        initialProps: {
+          items: makeItems(
+            ["a", "message"],
+            ["b", "message"],
+            ["c", "message"],
+            ["d", "message"],
+          ),
+        },
+      },
+    );
+
+    rerender({
+      items: makeItems(
+        ["w", "message"],
+        ["x", "message"],
+        ["y", "message"],
+        ["z", "message"],
+      ),
+    });
+
+    const calls = warnSpy.mock.calls.map((c) => c[0] as string);
+    const summaryCall = calls.find((m) => m.includes("key swaps detected"));
+    expect(summaryCall).toBeDefined();
+    expect(summaryCall).toContain("4 key swaps");
+  });
+});

package/src/internal/dev/__tests__/use-render-tracer.test.ts

@@ -0,0 +1,78 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { renderHook } from "@testing-library/react";
+import { useRenderTracer } from "../use-render-tracer";
+
+describe("useRenderTracer", () => {
+  let debugSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    debugSpy = vi.spyOn(console, "debug").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    debugSpy.mockRestore();
+  });
+
+  it("logs on the first render", () => {
+    renderHook(() => useRenderTracer("TestComponent", { foo: "bar" }));
+
+    expect(debugSpy).toHaveBeenCalledTimes(1);
+    const msg = debugSpy.mock.calls[0][0] as string;
+    expect(msg).toContain("[stgm:perf:render]");
+    expect(msg).toContain("TestComponent");
+    expect(msg).toContain("render=#1");
+  });
+
+  it("samples output — skips intermediate renders, logs every 10th", () => {
+    const { rerender } = renderHook(
+      ({ count }) => useRenderTracer("Counter", { count }),
+      { initialProps: { count: 0 } },
+    );
+
+    debugSpy.mockClear();
+
+    // Renders 2-9: no output (sampled every 10th, first was #1)
+    for (let i = 1; i < 9; i++) {
+      rerender({ count: i });
+    }
+    expect(debugSpy).not.toHaveBeenCalled();
+
+    // Render #10: should log
+    rerender({ count: 9 });
+    expect(debugSpy).toHaveBeenCalledTimes(1);
+    const msg = debugSpy.mock.calls[0][0] as string;
+    expect(msg).toContain("render=#10");
+  });
+
+  it("reports changed props on sampled renders", () => {
+    const stableRef = {};
+    const { rerender } = renderHook(
+      ({ a, b }) => useRenderTracer("Diff", { a, b }),
+      { initialProps: { a: stableRef as unknown, b: 1 as unknown } },
+    );
+
+    debugSpy.mockClear();
+
+    // Drive to render #10 with only `b` changing each time
+    for (let i = 1; i < 9; i++) {
+      rerender({ a: stableRef, b: i + 1 });
+    }
+
+    // Render #10
+    rerender({ a: stableRef, b: 10 });
+    expect(debugSpy).toHaveBeenCalledTimes(1);
+
+    const msg = debugSpy.mock.calls[0][0] as string;
+    expect(msg).toContain("changed=[b]");
+  });
+
+  it("includes primitive prop values in output", () => {
+    renderHook(() =>
+      useRenderTracer("Props", { count: 42, active: true }),
+    );
+
+    const msg = debugSpy.mock.calls[0][0] as string;
+    expect(msg).toContain("count=42");
+    expect(msg).toContain("active=true");
+  });
+});

package/src/internal/dev/dom-counter.ts

@@ -0,0 +1,47 @@
+import { type RefObject, useEffect, useRef } from "react";
+
+const DEV = process.env.NODE_ENV !== "production";
+
+/** Log the node count every Nth trigger. */
+const LOG_EVERY = 10;
+
+/**
+ * Dev-only hook that periodically counts DOM nodes under a container
+ * element and logs the result.
+ *
+ * Measurement runs inside `requestIdleCallback` (with a `setTimeout`
+ * fallback for environments that don't support it) so it never blocks
+ * rendering or scroll.
+ *
+ * @param containerRef - Ref to the DOM element whose subtree to count.
+ * @param label - Identifier for the console output.
+ */
+export function useDomNodeCount(
+  containerRef: RefObject<HTMLElement | null>,
+  label: string,
+): void {
+  const triggerCountRef = useRef(0);
+
+  useEffect(() => {
+    if (!DEV) return;
+
+    triggerCountRef.current += 1;
+    if (triggerCountRef.current % LOG_EVERY !== 0) return;
+
+    const el = containerRef.current;
+    if (!el) return;
+
+    const measure = () => {
+      const count = el.querySelectorAll("*").length;
+      console.debug(`[stgm:perf:dom] ${label}  nodes=${count}`);
+    };
+
+    if (typeof requestIdleCallback === "function") {
+      const handle = requestIdleCallback(measure);
+      return () => cancelIdleCallback(handle);
+    }
+
+    const handle = setTimeout(measure, 0);
+    return () => clearTimeout(handle);
+  });
+}

package/src/internal/dev/index.ts

@@ -0,0 +1,5 @@
+export { useRenderTracer } from "./use-render-tracer";
+export { useKeyStability } from "./use-key-stability";
+export { useStreamRate, type StreamRateTracker } from "./use-stream-rate";
+export { DevProfiler } from "./profiler-wrapper";
+export { useDomNodeCount } from "./dom-counter";

package/src/internal/dev/profiler-wrapper.tsx

@@ -0,0 +1,52 @@
+"use client";
+
+import { Profiler, type ProfilerOnRenderCallback, type ReactNode } from "react";
+
+const DEV = process.env.NODE_ENV !== "production";
+
+/** Log every Nth commit to avoid console flood during streaming. */
+const LOG_EVERY = 10;
+
+let commitCount = 0;
+
+const onRender: ProfilerOnRenderCallback = (
+  id,
+  phase,
+  actualDuration,
+  baseDuration,
+) => {
+  commitCount += 1;
+  if (commitCount % LOG_EVERY === 0 || commitCount === 1) {
+    console.debug(
+      `[stgm:perf:profiler] ${id}  phase=${phase}  ` +
+        `actualDuration=${actualDuration.toFixed(1)}ms  ` +
+        `baseDuration=${baseDuration.toFixed(1)}ms`,
+    );
+  }
+};
+
+/**
+ * Thin wrapper around React's `<Profiler>`.
+ *
+ * In dev mode, logs commit-level timing (`actualDuration`,
+ * `baseDuration`, mount vs update phase) with sampled output.
+ *
+ * In production, React strips Profiler callbacks automatically, and
+ * our dev gate ensures this component renders children with zero
+ * overhead regardless.
+ */
+export function DevProfiler({
+  id,
+  children,
+}: {
+  readonly id: string;
+  readonly children: ReactNode;
+}) {
+  if (!DEV) return children;
+
+  return (
+    <Profiler id={id} onRender={onRender}>
+      {children}
+    </Profiler>
+  );
+}

package/src/internal/dev/use-key-stability.ts

@@ -0,0 +1,86 @@
+import { useRef } from "react";
+
+const DEV = process.env.NODE_ENV !== "production";
+
+/** Minimal shape expected from a keyed thread item. */
+interface KeyedItem {
+  readonly key: string;
+  readonly kind: string;
+}
+
+/**
+ * Dev-only hook that detects key instability in a list of keyed items.
+ *
+ * Compares the current render's key set against the previous render's
+ * and warns when:
+ *
+ * - Duplicate keys exist in the current render (collision bug).
+ * - A key disappears and a new key appears at the same list index
+ *   (suggests a remount caused by key change, not a logical add/remove).
+ * - The total number of key replacements in a single render exceeds a
+ *   threshold, indicating widespread instability.
+ *
+ * In production builds the entire function body is dead-code-eliminated.
+ */
+export function useKeyStability(items: readonly KeyedItem[]): void {
+  const prevRef = useRef<readonly KeyedItem[] | null>(null);
+
+  if (!DEV) return;
+
+  // Detect duplicate keys within the current render.
+  const seen = new Map<string, number>();
+  for (let i = 0; i < items.length; i++) {
+    const prevIdx = seen.get(items[i].key);
+    if (prevIdx !== undefined) {
+      console.warn(
+        `[stgm:perf:keys] Duplicate key "${items[i].key}" at indices ${prevIdx} and ${i} ` +
+          `(${items[prevIdx].kind}, ${items[i].kind}). React will silently drop one.`,
+      );
+    } else {
+      seen.set(items[i].key, i);
+    }
+  }
+
+  const prev = prevRef.current;
+  prevRef.current = items;
+
+  if (!prev || prev.length === 0) return;
+
+  const prevKeys = new Map<string, number>();
+  for (let i = 0; i < prev.length; i++) {
+    prevKeys.set(prev[i].key, i);
+  }
+
+  const curKeys = new Set<string>(seen.keys());
+
+  const removed: string[] = [];
+  for (const key of prevKeys.keys()) {
+    if (!curKeys.has(key)) removed.push(key);
+  }
+
+  if (removed.length === 0) return;
+
+  let swapCount = 0;
+
+  for (const removedKey of removed) {
+    const idx = prevKeys.get(removedKey)!;
+    if (idx < items.length) {
+      const replacement = items[idx];
+      if (!prevKeys.has(replacement.key)) {
+        swapCount++;
+        console.warn(
+          `[stgm:perf:keys] Key swap at index ${idx}: ` +
+            `"${removedKey}" (${prev[idx].kind}) → "${replacement.key}" (${replacement.kind}). ` +
+            "This causes React to unmount/remount the row.",
+        );
+      }
+    }
+  }
+
+  if (swapCount > 3) {
+    console.warn(
+      `[stgm:perf:keys] ${swapCount} key swaps detected in a single render. ` +
+        "Thread items may be using unstable keys.",
+    );
+  }
+}

package/src/internal/dev/use-render-tracer.ts

@@ -0,0 +1,70 @@
+import { useRef } from "react";
+
+const DEV = process.env.NODE_ENV !== "production";
+
+/**
+ * Sampling interval: log every Nth render to avoid flooding the
+ * console during high-frequency streaming (10-15 ticks/s).
+ */
+const LOG_EVERY = 10;
+
+/**
+ * Dev-only hook that tracks render count and reports which props
+ * changed (by shallow referential equality) since the last render.
+ *
+ * In production builds the function body is dead-code-eliminated by
+ * bundlers that replace `process.env.NODE_ENV` with `"production"`.
+ *
+ * @param componentName - Stable label for console output.
+ * @param props - Key/value map of props to track. Pass only the props
+ *   you care about — typically the ones that drive re-renders.
+ */
+export function useRenderTracer(
+  componentName: string,
+  props: Record<string, unknown>,
+): void {
+  const countRef = useRef(0);
+  const prevRef = useRef<Record<string, unknown> | null>(null);
+
+  if (!DEV) return;
+
+  countRef.current += 1;
+  const count = countRef.current;
+  const prev = prevRef.current;
+
+  if (count % LOG_EVERY === 0 || count === 1) {
+    const changed: string[] = [];
+    if (prev) {
+      for (const key of Object.keys(props)) {
+        if (!Object.is(props[key], prev[key])) {
+          changed.push(key);
+        }
+      }
+    }
+
+    const parts = [
+      `[stgm:perf:render] ${componentName}`,
+      `render=#${count}`,
+    ];
+
+    for (const [key, value] of Object.entries(props)) {
+      if (typeof value === "string") {
+        parts.push(`${key}=${value.length > 40 ? value.slice(0, 40) + "…" : value}`);
+      } else if (typeof value === "number" || typeof value === "boolean") {
+        parts.push(`${key}=${String(value)}`);
+      }
+    }
+
+    if (prev) {
+      parts.push(
+        changed.length > 0
+          ? `changed=[${changed.join(",")}]`
+          : "changed=[]",
+      );
+    }
+
+    console.debug(parts.join("  "));
+  }
+
+  prevRef.current = { ...props };
+}

package/src/internal/dev/use-stream-rate.ts

@@ -0,0 +1,138 @@
+import { useRef } from "react";
+
+const DEV = process.env.NODE_ENV !== "production";
+
+/** Rolling window size for interval statistics. */
+const WINDOW_SIZE = 30;
+
+/** Log a sampled line every Nth tick. */
+const LOG_EVERY = 10;
+
+/** Mutable state tracked across stream ticks. */
+interface StreamRateState {
+  tickCount: number;
+  /** Timestamps (ms) of recent ticks for interval stats. */
+  timestamps: number[];
+  /** Message count from the previous tick, for delta calculation. */
+  prevMessageCount: number;
+}
+
+/**
+ * Imperative tracker returned by {@link useStreamRate}.
+ *
+ * Call `tick()` on each stream snapshot inside the `for await` loop.
+ * Call `summary()` when the stream ends to log aggregate stats.
+ */
+export interface StreamRateTracker {
+  /** Record a stream snapshot arrival. */
+  tick(messageCount: number): void;
+  /** Log aggregate statistics for the completed stream. */
+  summary(): void;
+}
+
+const NOOP_TRACKER: StreamRateTracker = {
+  tick() {},
+  summary() {},
+};
+
+/**
+ * Dev-only hook that returns an imperative {@link StreamRateTracker}.
+ *
+ * The tracker is designed to be called inside a `useEffect` async
+ * loop (not during render), so it uses a ref-backed mutable object
+ * rather than React state.
+ *
+ * In production the hook returns a no-op tracker.
+ */
+export function useStreamRate(): StreamRateTracker {
+  const stateRef = useRef<StreamRateState | null>(null);
+
+  if (!DEV) return NOOP_TRACKER;
+
+  if (!stateRef.current) {
+    stateRef.current = {
+      tickCount: 0,
+      timestamps: [],
+      prevMessageCount: 0,
+    };
+  }
+
+  const state = stateRef.current;
+
+  const tracker: StreamRateTracker = {
+    tick(messageCount: number) {
+      const now = performance.now();
+      state.tickCount += 1;
+      state.timestamps.push(now);
+      if (state.timestamps.length > WINDOW_SIZE) {
+        state.timestamps.shift();
+      }
+
+      const delta = messageCount - state.prevMessageCount;
+      state.prevMessageCount = messageCount;
+
+      if (state.tickCount % LOG_EVERY === 0 || state.tickCount === 1) {
+        const intervals = computeIntervals(state.timestamps);
+        const parts = [
+          `[stgm:perf:stream] tick #${state.tickCount}`,
+          `messages=${messageCount}`,
+          `delta=+${delta}`,
+        ];
+        if (intervals) {
+          parts.push(
+            `interval=${intervals.avg.toFixed(0)}ms`,
+            `rate=${intervals.rate.toFixed(1)}/s`,
+          );
+        }
+        console.debug(parts.join("  "));
+      }
+    },
+
+    summary() {
+      if (state.tickCount === 0) return;
+
+      const intervals = computeIntervals(state.timestamps);
+      const parts = [
+        `[stgm:perf:stream] ✓ stream complete`,
+        `totalTicks=${state.tickCount}`,
+        `finalMessages=${state.prevMessageCount}`,
+      ];
+      if (intervals) {
+        parts.push(
+          `avgInterval=${intervals.avg.toFixed(0)}ms`,
+          `minInterval=${intervals.min.toFixed(0)}ms`,
+          `maxInterval=${intervals.max.toFixed(0)}ms`,
+          `avgRate=${intervals.rate.toFixed(1)}/s`,
+        );
+      }
+      console.debug(parts.join("  "));
+
+      state.tickCount = 0;
+      state.timestamps.length = 0;
+      state.prevMessageCount = 0;
+    },
+  };
+
+  return tracker;
+}
+
+function computeIntervals(timestamps: number[]) {
+  if (timestamps.length < 2) return null;
+
+  let min = Infinity;
+  let max = 0;
+  let sum = 0;
+  const count = timestamps.length - 1;
+
+  for (let i = 1; i < timestamps.length; i++) {
+    const dt = timestamps[i] - timestamps[i - 1];
+    sum += dt;
+    if (dt < min) min = dt;
+    if (dt > max) max = dt;
+  }
+
+  const avg = sum / count;
+  const rate = avg > 0 ? 1000 / avg : 0;
+
+  return { min, max, avg, rate };
+}