@stigmer/react 0.3.4 → 0.4.0

package/internal/__tests__/useFetch-cache.test.js

@@ -0,0 +1,137 @@
+import { describe, it, expect, vi } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import { createElement } from "react";
+import { FetchCacheContext } from "../FetchCacheProvider";
+import { FetchCache } from "../fetch-cache";
+import { useFetch } from "../useFetch";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+async function flush() {
+    await act(async () => {
+        await Promise.resolve();
+    });
+}
+/**
+ * Build a wrapper that provides a specific FetchCache instance via
+ * context. Tests that need cross-mount caching share the same cache
+ * object, mirroring the production layout where FetchCacheProvider
+ * sits above the key-based remount boundary.
+ */
+function createCacheWrapper(cache) {
+    return function Wrapper({ children }) {
+        return createElement(FetchCacheContext.Provider, { value: cache }, children);
+    };
+}
+// ---------------------------------------------------------------------------
+// Tests: useFetch + FetchCacheProvider
+// ---------------------------------------------------------------------------
+describe("useFetch — cache integration", () => {
+    it("serves cached data on mount and skips isLoading", async () => {
+        const cache = new FetchCache();
+        const wrapper = createCacheWrapper(cache);
+        // First mount: populate the cache via a normal fetch.
+        const fetchFn = vi.fn(async () => "fetched-value");
+        const { result, unmount } = renderHook(() => useFetch(fetchFn, [], "init", { cacheKey: "test:1" }), { wrapper });
+        expect(result.current.isLoading).toBe(true);
+        await flush();
+        expect(result.current.data).toBe("fetched-value");
+        expect(result.current.isLoading).toBe(false);
+        unmount();
+        // Second mount (simulating remount after key change): should
+        // seed state from cache and never show isLoading.
+        const fetchFn2 = vi.fn(async () => "fresh-value");
+        const { result: result2 } = renderHook(() => useFetch(fetchFn2, [], "init", { cacheKey: "test:1" }), { wrapper });
+        // On mount, cached data is available immediately.
+        expect(result2.current.data).toBe("fetched-value");
+        expect(result2.current.isLoading).toBe(false);
+        expect(result2.current.isRefetching).toBe(true);
+        // Background fetch completes and updates data.
+        await flush();
+        expect(result2.current.data).toBe("fresh-value");
+        expect(result2.current.isRefetching).toBe(false);
+    });
+    it("falls back to initialData on cache miss", async () => {
+        const cache = new FetchCache();
+        const wrapper = createCacheWrapper(cache);
+        const fetchFn = vi.fn(async () => "fetched");
+        const { result } = renderHook(() => useFetch(fetchFn, [], "init", { cacheKey: "miss:1" }), { wrapper });
+        expect(result.current.data).toBe("init");
+        expect(result.current.isLoading).toBe(true);
+        await flush();
+        expect(result.current.data).toBe("fetched");
+    });
+    it("writes to cache on fetch success", async () => {
+        const cache = new FetchCache();
+        const wrapper = createCacheWrapper(cache);
+        const fetchFn = vi.fn(async () => "data-1");
+        const { result } = renderHook(() => useFetch(fetchFn, [], "init", { cacheKey: "write:1" }), { wrapper });
+        expect(cache.has("write:1")).toBe(false);
+        await flush();
+        expect(result.current.data).toBe("data-1");
+        expect(cache.get("write:1")).toBe("data-1");
+    });
+    it("does not interact with cache when cacheKey is undefined", async () => {
+        const cache = new FetchCache();
+        const wrapper = createCacheWrapper(cache);
+        const fetchFn = vi.fn(async () => "val");
+        const { result } = renderHook(() => useFetch(fetchFn, [], "init"), { wrapper });
+        await flush();
+        expect(result.current.data).toBe("val");
+        expect(cache.size).toBe(0);
+    });
+    it("works without FetchCacheProvider (graceful degradation)", async () => {
+        const fetchFn = vi.fn(async () => "value");
+        // No wrapper — no provider.
+        const { result } = renderHook(() => useFetch(fetchFn, [], "init", { cacheKey: "no-provider:1" }));
+        expect(result.current.data).toBe("init");
+        expect(result.current.isLoading).toBe(true);
+        await flush();
+        expect(result.current.data).toBe("value");
+        expect(result.current.isLoading).toBe(false);
+    });
+    it("does not read cache when fetchFn is null", async () => {
+        const cache = new FetchCache();
+        const wrapper = createCacheWrapper(cache);
+        const fetchFn1 = vi.fn(async () => "cached-val");
+        // First: populate cache.
+        const { unmount } = renderHook(() => useFetch(fetchFn1, [], "init", { cacheKey: "null-fn:1" }), { wrapper });
+        await flush();
+        unmount();
+        // Second: mount with fetchFn=null — should reset to initialData
+        // even though cache has data for this key.
+        const { result } = renderHook(() => useFetch(null, [], "fallback", {
+            cacheKey: "null-fn:1",
+        }), { wrapper });
+        expect(result.current.data).toBe("fallback");
+        expect(result.current.isLoading).toBe(false);
+    });
+    it("does not write to cache on fetch error", async () => {
+        const cache = new FetchCache();
+        const wrapper = createCacheWrapper(cache);
+        const fetchFn = vi.fn(async () => {
+            throw new Error("fail");
+        });
+        const { result } = renderHook(() => useFetch(fetchFn, [], "init", { cacheKey: "err:1" }), { wrapper });
+        await flush();
+        expect(result.current.error?.message).toBe("fail");
+        expect(cache.has("err:1")).toBe(false);
+    });
+    it("independent cache keys do not interfere", async () => {
+        const cache = new FetchCache();
+        const wrapper = createCacheWrapper(cache);
+        const fetchA = vi.fn(async () => "session-A");
+        const fetchB = vi.fn(async () => "session-B");
+        const { unmount: unmountA } = renderHook(() => useFetch(fetchA, [], null, { cacheKey: "session:A" }), { wrapper });
+        await flush();
+        unmountA();
+        const { unmount: unmountB } = renderHook(() => useFetch(fetchB, [], null, { cacheKey: "session:B" }), { wrapper });
+        await flush();
+        unmountB();
+        // Remount A — should get A's cached data, not B's.
+        const { result } = renderHook(() => useFetch(vi.fn(async () => "fresh-A"), [], null, { cacheKey: "session:A" }), { wrapper });
+        expect(result.current.data).toBe("session-A");
+        expect(result.current.isLoading).toBe(false);
+    });
+});
+//# sourceMappingURL=useFetch-cache.test.js.map

package/internal/__tests__/useFetch-cache.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useFetch-cache.test.js","sourceRoot":"","sources":["../../../src/internal/__tests__/useFetch-cache.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,wBAAwB,CAAC;AAEzD,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AACtC,OAAO,EAAE,iBAAiB,EAAiB,MAAM,uBAAuB,CAAC;AACzE,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E,KAAK,UAAU,KAAK;IAClB,MAAM,GAAG,CAAC,KAAK,IAAI,EAAE;QACnB,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;IAC1B,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,SAAS,kBAAkB,CAAC,KAAiB;IAC3C,OAAO,SAAS,OAAO,CAAC,EAAE,QAAQ,EAA2B;QAC3D,OAAO,aAAa,CAAC,iBAAiB,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,QAAQ,CAAC,CAAC;IAC/E,CAAC,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,uCAAuC;AACvC,8EAA8E;AAE9E,QAAQ,CAAC,8BAA8B,EAAE,GAAG,EAAE;IAC5C,EAAE,CAAC,iDAAiD,EAAE,KAAK,IAAI,EAAE;QAC/D,MAAM,KAAK,GAAG,IAAI,UAAU,EAAE,CAAC;QAC/B,MAAM,OAAO,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;QAE1C,sDAAsD;QACtD,MAAM,OAAO,GAAG,EAAE,CAAC,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,eAAe,CAAC,CAAC;QAEnD,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,UAAU,CACpC,GAAG,EAAE,CAAC,QAAQ,CAAC,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,EAC3D,EAAE,OAAO,EAAE,CACZ,CAAC;QAEF,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC5C,MAAM,KAAK,EAAE,CAAC;QACd,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;QAClD,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAE7C,OAAO,EAAE,CAAC;QAEV,6DAA6D;QAC7D,kDAAkD;QAClD,MAAM,QAAQ,GAAG,EAAE,CAAC,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,aAAa,CAAC,CAAC;QAClD,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,UAAU,CACpC,GAAG,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,EAC5D,EAAE,OAAO,EAAE,CACZ,CAAC;QAEF,kDAAkD;QAClD,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;QACnD,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC9C,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAEhD,+CAA+C;QAC/C,MAAM,KAAK,EAAE,CAAC;QACd,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QACjD,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACnD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,yCAAyC,EAAE,KAAK,IAAI,EAAE;QACvD,MAAM,KAAK,GAAG,IAAI,UAAU,EAAE,CAAC;QAC/B,MAAM,OAAO,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;QAC1C,MAAM,OAAO,GAAG,EAAE,CAAC,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,SAAS,CAAC,CAAC;QAE7C,MAAM,EAAE,MAAM,EAAE,GAAG,UAAU,CAC3B,GAAG,EAAE,CAAC,QAAQ,CAAC,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,EAC3D,EAAE,OAAO,EAAE,CACZ,CAAC;QAEF,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACzC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAE5C,MAAM,KAAK,EAAE,CAAC;QACd,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAC9C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,kCAAkC,EAAE,KAAK,IAAI,EAAE;QAChD,MAAM,KAAK,GAAG,IAAI,UAAU,EAAE,CAAC;QAC/B,MAAM,OAAO,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;QAC1C,MAAM,OAAO,GAAG,EAAE,CAAC,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,QAAQ,CAAC,CAAC;QAE5C,MAAM,EAAE,MAAM,EAAE,GAAG,UAAU,CAC3B,GAAG,EAAE,CAAC,QAAQ,CAAC,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC,EAC5D,EAAE,OAAO,EAAE,CACZ,CAAC;QAEF,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAEzC,MAAM,KAAK,EAAE,CAAC;QACd,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC3C,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC9C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,yDAAyD,EAAE,KAAK,IAAI,EAAE;QACvE,MAAM,KAAK,GAAG,IAAI,UAAU,EAAE,CAAC;QAC/B,MAAM,OAAO,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;QAC1C,MAAM,OAAO,GAAG,EAAE,CAAC,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC;QAEzC,MAAM,EAAE,MAAM,EAAE,GAAG,UAAU,CAC3B,GAAG,EAAE,CAAC,QAAQ,CAAC,OAAO,EAAE,EAAE,EAAE,MAAM,CAAC,EACnC,EAAE,OAAO,EAAE,CACZ,CAAC;QAEF,MAAM,KAAK,EAAE,CAAC;QACd,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACxC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC7B,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,yDAAyD,EAAE,KAAK,IAAI,EAAE;QACvE,MAAM,OAAO,GAAG,EAAE,CAAC,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,OAAO,CAAC,CAAC;QAE3C,4BAA4B;QAC5B,MAAM,EAAE,MAAM,EAAE,GAAG,UAAU,CAAC,GAAG,EAAE,CACjC,QAAQ,CAAC,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,eAAe,EAAE,CAAC,CAC7D,CAAC;QAEF,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACzC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAE5C,MAAM,KAAK,EAAE,CAAC;QACd,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC1C,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC/C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,0CAA0C,EAAE,KAAK,IAAI,EAAE;QACxD,MAAM,KAAK,GAAG,IAAI,UAAU,EAAE,CAAC;QAC/B,MAAM,OAAO,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;QAE1C,MAAM,QAAQ,GAAG,EAAE,CAAC,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,YAAY,CAAC,CAAC;QAEjD,yBAAyB;QACzB,MAAM,EAAE,OAAO,EAAE,GAAG,UAAU,CAC5B,GAAG,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC,EAC/D,EAAE,OAAO,EAAE,CACZ,CAAC;QACF,MAAM,KAAK,EAAE,CAAC;QACd,OAAO,EAAE,CAAC;QAEV,gEAAgE;QAChE,2CAA2C;QAC3C,MAAM,EAAE,MAAM,EAAE,GAAG,UAAU,CAC3B,GAAG,EAAE,CACH,QAAQ,CAAC,IAAI,EAAE,EAAE,EAAE,UAA2B,EAAE;YAC9C,QAAQ,EAAE,WAAW;SACtB,CAAC,EACJ,EAAE,OAAO,EAAE,CACZ,CAAC;QAEF,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAC7C,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC/C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,wCAAwC,EAAE,KAAK,IAAI,EAAE;QACtD,MAAM,KAAK,GAAG,IAAI,UAAU,EAAE,CAAC;QAC/B,MAAM,OAAO,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;QAC1C,MAAM,OAAO,GAAG,EAAE,CAAC,EAAE,CAAC,KAAK,IAAI,EAAE;YAC/B,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC;QAC1B,CAAC,CAAC,CAAC;QAEH,MAAM,EAAE,MAAM,EAAE,GAAG,UAAU,CAC3B,GAAG,EAAE,CAAC,QAAQ,CAAC,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,EAC1D,EAAE,OAAO,EAAE,CACZ,CAAC;QAEF,MAAM,KAAK,EAAE,CAAC;QACd,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACnD,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACzC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,yCAAyC,EAAE,KAAK,IAAI,EAAE;QACvD,MAAM,KAAK,GAAG,IAAI,UAAU,EAAE,CAAC;QAC/B,MAAM,OAAO,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;QAE1C,MAAM,MAAM,GAAG,EAAE,CAAC,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,WAAW,CAAC,CAAC;QAC9C,MAAM,MAAM,GAAG,EAAE,CAAC,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,WAAW,CAAC,CAAC;QAE9C,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,UAAU,CACtC,GAAG,EAAE,CAAC,QAAQ,CAAC,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC,EAC3D,EAAE,OAAO,EAAE,CACZ,CAAC;QACF,MAAM,KAAK,EAAE,CAAC;QACd,QAAQ,EAAE,CAAC;QAEX,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,UAAU,CACtC,GAAG,EAAE,CAAC,QAAQ,CAAC,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC,EAC3D,EAAE,OAAO,EAAE,CACZ,CAAC;QACF,MAAM,KAAK,EAAE,CAAC;QACd,QAAQ,EAAE,CAAC;QAEX,mDAAmD;QACnD,MAAM,EAAE,MAAM,EAAE,GAAG,UAAU,CAC3B,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,SAAS,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC,EACjF,EAAE,OAAO,EAAE,CACZ,CAAC;QAEF,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QAC9C,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC/C,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=use-key-stability.test.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"use-key-stability.test.d.ts","sourceRoot":"","sources":["../../../../src/internal/dev/__tests__/use-key-stability.test.ts"],"names":[],"mappings":""}

package/internal/dev/__tests__/use-key-stability.test.js

@@ -0,0 +1,72 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { renderHook } from "@testing-library/react";
+import { useKeyStability } from "../use-key-stability";
+function makeItems(...specs) {
+    return specs.map(([key, kind]) => ({ key, kind }));
+}
+describe("useKeyStability", () => {
+    let warnSpy;
+    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];
+        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]);
+        const summaryCall = calls.find((m) => m.includes("key swaps detected"));
+        expect(summaryCall).toBeDefined();
+        expect(summaryCall).toContain("4 key swaps");
+    });
+});
+//# sourceMappingURL=use-key-stability.test.js.map

package/internal/dev/__tests__/use-key-stability.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-key-stability.test.js","sourceRoot":"","sources":["../../../../src/internal/dev/__tests__/use-key-stability.test.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=use-render-tracer.test.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"use-render-tracer.test.d.ts","sourceRoot":"","sources":["../../../../src/internal/dev/__tests__/use-render-tracer.test.ts"],"names":[],"mappings":""}

package/internal/dev/__tests__/use-render-tracer.test.js

@@ -0,0 +1,55 @@
+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;
+    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];
+        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];
+        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, b: 1 } });
+        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];
+        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];
+        expect(msg).toContain("count=42");
+        expect(msg).toContain("active=true");
+    });
+});
+//# sourceMappingURL=use-render-tracer.test.js.map

package/internal/dev/__tests__/use-render-tracer.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-render-tracer.test.js","sourceRoot":"","sources":["../../../../src/internal/dev/__tests__/use-render-tracer.test.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,14 @@
+import { type RefObject } from "react";
+/**
+ * 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 declare function useDomNodeCount(containerRef: RefObject<HTMLElement | null>, label: string): void;
+//# sourceMappingURL=dom-counter.d.ts.map

package/internal/dev/dom-counter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom-counter.d.ts","sourceRoot":"","sources":["../../../src/internal/dev/dom-counter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAqB,MAAM,OAAO,CAAC;AAO1D;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,YAAY,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,EAC3C,KAAK,EAAE,MAAM,GACZ,IAAI,CAyBN"}

package/internal/dev/dom-counter.js

@@ -0,0 +1,39 @@
+import { 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, label) {
+    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);
+    });
+}
+//# sourceMappingURL=dom-counter.js.map

package/internal/dev/dom-counter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom-counter.js","sourceRoot":"","sources":["../../../src/internal/dev/dom-counter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,SAAS,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AAE1D,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY,CAAC;AAElD,4CAA4C;AAC5C,MAAM,SAAS,GAAG,EAAE,CAAC;AAErB;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAC7B,YAA2C,EAC3C,KAAa;IAEb,MAAM,eAAe,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IAElC,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,CAAC,GAAG;YAAE,OAAO;QAEjB,eAAe,CAAC,OAAO,IAAI,CAAC,CAAC;QAC7B,IAAI,eAAe,CAAC,OAAO,GAAG,SAAS,KAAK,CAAC;YAAE,OAAO;QAEtD,MAAM,EAAE,GAAG,YAAY,CAAC,OAAO,CAAC;QAChC,IAAI,CAAC,EAAE;YAAE,OAAO;QAEhB,MAAM,OAAO,GAAG,GAAG,EAAE;YACnB,MAAM,KAAK,GAAG,EAAE,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC;YAC9C,OAAO,CAAC,KAAK,CAAC,mBAAmB,KAAK,WAAW,KAAK,EAAE,CAAC,CAAC;QAC5D,CAAC,CAAC;QAEF,IAAI,OAAO,mBAAmB,KAAK,UAAU,EAAE,CAAC;YAC9C,MAAM,MAAM,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC;YAC5C,OAAO,GAAG,EAAE,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC;QAC1C,CAAC;QAED,MAAM,MAAM,GAAG,UAAU,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;QACtC,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;AACL,CAAC"}

package/internal/dev/index.d.ts

@@ -0,0 +1,6 @@
+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";
+//# sourceMappingURL=index.d.ts.map

package/internal/dev/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/internal/dev/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,KAAK,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC1E,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC"}

package/internal/dev/index.js

@@ -0,0 +1,6 @@
+export { useRenderTracer } from "./use-render-tracer";
+export { useKeyStability } from "./use-key-stability";
+export { useStreamRate } from "./use-stream-rate";
+export { DevProfiler } from "./profiler-wrapper";
+export { useDomNodeCount } from "./dom-counter";
+//# sourceMappingURL=index.js.map

package/internal/dev/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/internal/dev/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,aAAa,EAA0B,MAAM,mBAAmB,CAAC;AAC1E,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC"}

package/internal/dev/profiler-wrapper.d.ts

@@ -0,0 +1,16 @@
+import { type ReactNode } from "react";
+/**
+ * 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 declare function DevProfiler({ id, children, }: {
+    readonly id: string;
+    readonly children: ReactNode;
+}): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | import("react/jsx-runtime").JSX.Element | null | undefined;
+//# sourceMappingURL=profiler-wrapper.d.ts.map

package/internal/dev/profiler-wrapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profiler-wrapper.d.ts","sourceRoot":"","sources":["../../../src/internal/dev/profiler-wrapper.tsx"],"names":[],"mappings":"AAEA,OAAO,EAA2C,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAyBhF;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,EAC1B,EAAE,EACF,QAAQ,GACT,EAAE;IACD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;CAC9B,2UAQA"}

package/internal/dev/profiler-wrapper.js

@@ -0,0 +1,31 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Profiler } 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 = (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, }) {
+    if (!DEV)
+        return children;
+    return (_jsx(Profiler, { id: id, onRender: onRender, children: children }));
+}
+//# sourceMappingURL=profiler-wrapper.js.map

package/internal/dev/profiler-wrapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profiler-wrapper.js","sourceRoot":"","sources":["../../../src/internal/dev/profiler-wrapper.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAC;;AAEb,OAAO,EAAE,QAAQ,EAAiD,MAAM,OAAO,CAAC;AAEhF,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY,CAAC;AAElD,oEAAoE;AACpE,MAAM,SAAS,GAAG,EAAE,CAAC;AAErB,IAAI,WAAW,GAAG,CAAC,CAAC;AAEpB,MAAM,QAAQ,GAA6B,CACzC,EAAE,EACF,KAAK,EACL,cAAc,EACd,YAAY,EACZ,EAAE;IACF,WAAW,IAAI,CAAC,CAAC;IACjB,IAAI,WAAW,GAAG,SAAS,KAAK,CAAC,IAAI,WAAW,KAAK,CAAC,EAAE,CAAC;QACvD,OAAO,CAAC,KAAK,CACX,wBAAwB,EAAE,WAAW,KAAK,IAAI;YAC5C,kBAAkB,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM;YACjD,gBAAgB,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAC9C,CAAC;IACJ,CAAC;AACH,CAAC,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CAAC,EAC1B,EAAE,EACF,QAAQ,GAIT;IACC,IAAI,CAAC,GAAG;QAAE,OAAO,QAAQ,CAAC;IAE1B,OAAO,CACL,KAAC,QAAQ,IAAC,EAAE,EAAE,EAAE,EAAE,QAAQ,EAAE,QAAQ,YACjC,QAAQ,GACA,CACZ,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,22 @@
+/** 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 declare function useKeyStability(items: readonly KeyedItem[]): void;
+export {};
+//# sourceMappingURL=use-key-stability.d.ts.map

package/internal/dev/use-key-stability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-key-stability.d.ts","sourceRoot":"","sources":["../../../src/internal/dev/use-key-stability.ts"],"names":[],"mappings":"AAIA,uDAAuD;AACvD,UAAU,SAAS;IACjB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,GAAG,IAAI,CA6DjE"}

package/internal/dev/use-key-stability.js

@@ -0,0 +1,67 @@
+import { useRef } from "react";
+const DEV = process.env.NODE_ENV !== "production";
+/**
+ * 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) {
+    const prevRef = useRef(null);
+    if (!DEV)
+        return;
+    // Detect duplicate keys within the current render.
+    const seen = new Map();
+    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();
+    for (let i = 0; i < prev.length; i++) {
+        prevKeys.set(prev[i].key, i);
+    }
+    const curKeys = new Set(seen.keys());
+    const removed = [];
+    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.");
+    }
+}
+//# sourceMappingURL=use-key-stability.js.map

package/internal/dev/use-key-stability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-key-stability.js","sourceRoot":"","sources":["../../../src/internal/dev/use-key-stability.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,13 @@
+/**
+ * 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 declare function useRenderTracer(componentName: string, props: Record<string, unknown>): void;
+//# sourceMappingURL=use-render-tracer.d.ts.map

package/internal/dev/use-render-tracer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-render-tracer.d.ts","sourceRoot":"","sources":["../../../src/internal/dev/use-render-tracer.ts"],"names":[],"mappings":"AAUA;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,IAAI,CA6CN"}

package/internal/dev/use-render-tracer.js

@@ -0,0 +1,57 @@
+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, props) {
+    const countRef = useRef(0);
+    const prevRef = useRef(null);
+    if (!DEV)
+        return;
+    countRef.current += 1;
+    const count = countRef.current;
+    const prev = prevRef.current;
+    if (count % LOG_EVERY === 0 || count === 1) {
+        const changed = [];
+        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 };
+}
+//# sourceMappingURL=use-render-tracer.js.map