@stigmer/react 3.7.0 → 3.8.0

package/src/internal/__tests__/useAutoScroll.layout.test.tsx

@@ -0,0 +1,143 @@
+// Scroll-behavior regression suite for useAutoScroll (channel-conversations
+// F-09). Runs in a real Chromium via `vitest.a11y.config.ts` — the defect
+// lives in IntersectionObserver/ResizeObserver timing against real layout,
+// which happy-dom cannot evaluate (there, every scrollHeight is 0 and the
+// observers are mocks).
+//
+// The production shape under test: a chat thread whose items arrive ASYNC
+// after mount, so the content wrapper renders inside a loading branch and
+// does not exist on the first render. The shipped bug: the hook attached
+// its ResizeObserver only at mount, so a late-mounting wrapper was never
+// observed — every conversation opened at the OLDEST message with "Jump to
+// latest" showing, and nothing ever scrolled the view again.
+//
+// Layout is driven by inline styles (not the shipped stylesheet): this
+// suite pins the hook's observer mechanics, not CSS — the real component's
+// rendering is covered by ConversationTimelineView.layout.test.tsx.
+
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { render, cleanup } from "@testing-library/react";
+import { useAutoScroll, type UseAutoScrollReturn } from "../useAutoScroll";
+
+const VIEWPORT_PX = 240;
+const ITEM_PX = 48;
+
+let latest: UseAutoScrollReturn;
+
+/**
+ * The production thread shape: scroller and sentinel always mounted, the
+ * content wrapper only once items exist (the loading branch renders a
+ * skeleton instead).
+ */
+function AsyncThread({ items }: { readonly items: readonly string[] }) {
+  const hook = useAutoScroll();
+  latest = hook;
+  return (
+    <div
+      ref={hook.scrollRef}
+      data-testid="scroller"
+      style={{ height: VIEWPORT_PX, overflowY: "auto" }}
+    >
+      {items.length === 0 ? (
+        <div data-testid="skeleton" style={{ height: 100 }} />
+      ) : (
+        <div ref={hook.contentRef} data-testid="content">
+          {items.map((text) => (
+            <div key={text} style={{ height: ITEM_PX }}>
+              {text}
+            </div>
+          ))}
+        </div>
+      )}
+      <div ref={hook.sentinelRef} aria-hidden="true" />
+    </div>
+  );
+}
+
+const messages = (count: number, offset = 0) =>
+  Array.from({ length: count }, (_, i) => `message ${i + offset}`);
+
+function scroller(): HTMLElement {
+  return document.querySelector('[data-testid="scroller"]') as HTMLElement;
+}
+
+const isPinnedToBottom = (el: HTMLElement) =>
+  Math.abs(el.scrollTop - (el.scrollHeight - el.clientHeight)) <= 1;
+
+/** Wait out rAF-batched scroll writes and async observer callbacks. */
+async function settled(assertion: () => void): Promise<void> {
+  await vi.waitFor(assertion, { timeout: 2000, interval: 20 });
+}
+
+// Determinism note: every case fills content AFTER mount on purpose. With
+// a late-mounting wrapper the mount-time scroll write is a no-op (the
+// skeleton does not overflow), so the bottom pin can only come from the
+// ResizeObserver pathway — "pinned" therefore PROVES the observer's
+// initial delivery and its rAF write have both run, and no pinning work
+// is pending when a case then simulates the reader's scroll. (Headless
+// Chromium delivers initial observations on its own schedule; waiting a
+// frame count instead was measured flaky.)
+
+afterEach(() => cleanup());
+
+describe("useAutoScroll under real layout (F-09)", () => {
+  it("pins to the newest content when items arrive after mount", async () => {
+    const { rerender } = render(<AsyncThread items={[]} />);
+
+    // The async first fill: 30 × 48px inside a 240px viewport.
+    rerender(<AsyncThread items={messages(30)} />);
+
+    await settled(() => {
+      expect(isPinnedToBottom(scroller()), "view must open at the newest message").toBe(true);
+      expect(latest.isFollowing).toBe(true);
+    });
+  });
+
+  it("keeps following growth that lands after an async first fill", async () => {
+    const { rerender } = render(<AsyncThread items={[]} />);
+    rerender(<AsyncThread items={messages(30)} />);
+    await settled(() => expect(isPinnedToBottom(scroller())).toBe(true));
+
+    // A new message lands (a poll tick): the pinned view must follow it.
+    rerender(<AsyncThread items={messages(31)} />);
+
+    await settled(() => {
+      expect(isPinnedToBottom(scroller())).toBe(true);
+      expect(latest.isFollowing).toBe(true);
+    });
+  });
+
+  it("leaves a reader who scrolled up alone, and jumpToLatest recovers", async () => {
+    const { rerender } = render(<AsyncThread items={[]} />);
+    rerender(<AsyncThread items={messages(30)} />);
+    await settled(() => {
+      expect(isPinnedToBottom(scroller())).toBe(true);
+      // Follow-STATE quiescence, not just position: the pin's own IO
+      // deliveries (a transient not-visible mid-pin, then visible)
+      // must have landed before the reader scrolls up — otherwise the
+      // disengage wait below can pass vacuously on the transient FALSE
+      // while a queued pre-scroll TRUE re-arms follow behind it, and
+      // the growth step yanks the reader (measured ~1-in-40 headless).
+      expect(latest.isFollowing).toBe(true);
+    });
+
+    // The reader scrolls up to read history — follow disengages.
+    scroller().scrollTop = 0;
+    await settled(() => expect(latest.isFollowing).toBe(false));
+
+    // Growth while disengaged (an incoming message, or the reader's own
+    // send arriving via refetch): the view must NOT move under them.
+    // This is the measured scroll-on-send posture — see the F-09 record.
+    rerender(<AsyncThread items={messages(31)} />);
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    expect(scroller().scrollTop).toBe(0);
+    expect(latest.isFollowing).toBe(false);
+
+    // The recovery affordance: jumpToLatest re-pins and re-engages.
+    latest.jumpToLatest();
+    await settled(() => {
+      expect(isPinnedToBottom(scroller())).toBe(true);
+      expect(latest.isFollowing).toBe(true);
+    });
+  });
+});

package/src/internal/__tests__/useAutoScroll.test.tsx

@@ -22,6 +22,29 @@ function Harness() {
   );
 }
 
+/**
+ * The conversation-timeline shape (channel-conversations F-09): the content
+ * wrapper legitimately sits inside a loading branch, so it does NOT exist on
+ * the first render — the hook must attach its ResizeObserver whenever the
+ * wrapper appears, not only at mount.
+ */
+function LateContentHarness({ showContent }: { readonly showContent: boolean }) {
+  const result = useAutoScroll();
+  latestResult = result;
+  return (
+    <div ref={result.scrollRef} data-testid="scroller">
+      {showContent ? (
+        <div ref={result.contentRef} data-testid="content">
+          <p>Hello</p>
+        </div>
+      ) : (
+        <div data-testid="skeleton" />
+      )}
+      <div ref={result.sentinelRef} data-testid="sentinel" />
+    </div>
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Observer mocks
 // ---------------------------------------------------------------------------
@@ -91,12 +114,22 @@ afterEach(() => {
 // Helpers
 // ---------------------------------------------------------------------------
 
-function fireIO(isIntersecting: boolean) {
+/**
+ * Deliver an IO notification with the scroller's LIVE geometry staged to
+ * match the scenario. The hook measures live geometry at delivery time
+ * rather than trusting the entry payload — an entry snapshots
+ * observation-time geometry and can be delivered after the reader has
+ * scrolled again (the stale-payload race pinned in the browser suite) —
+ * so the entry list itself is deliberately empty here.
+ */
+function fireIO(nearBottom: boolean) {
+  const scroller = screen.getByTestId("scroller");
+  Object.defineProperty(scroller, "scrollHeight", { value: 1000, configurable: true });
+  Object.defineProperty(scroller, "clientHeight", { value: 200, configurable: true });
+  // Within the 80px near-bottom margin, or far above it.
+  scroller.scrollTop = nearBottom ? 800 : 0;
   act(() => {
-    ioCallback(
-      [{ isIntersecting } as IntersectionObserverEntry],
-      {} as IntersectionObserver,
-    );
+    ioCallback([], {} as IntersectionObserver);
   });
 }
 
@@ -126,6 +159,30 @@ describe("useAutoScroll", () => {
     expect(roObserve).toHaveBeenCalledWith(screen.getByTestId("content"));
   });
 
+  it("observes content that mounts after the first render (F-09: loading-branch consumers)", () => {
+    const { rerender } = render(<LateContentHarness showContent={false} />);
+    expect(roObserve).not.toHaveBeenCalled();
+
+    // The async first fill: the skeleton gives way to real content.
+    rerender(<LateContentHarness showContent />);
+    expect(roObserve).toHaveBeenCalledWith(screen.getByTestId("content"));
+  });
+
+  it("disconnects and re-observes across content unmount/remount round-trips", () => {
+    const { rerender } = render(<LateContentHarness showContent />);
+    expect(roObserve).toHaveBeenCalledTimes(1);
+
+    // Back to a loading state (e.g. an identity switch resets the data
+    // hook): the observer must let go of the dead node…
+    rerender(<LateContentHarness showContent={false} />);
+    expect(roDisconnect).toHaveBeenCalled();
+
+    // …and adopt the replacement when content returns.
+    rerender(<LateContentHarness showContent />);
+    expect(roObserve).toHaveBeenCalledTimes(2);
+    expect(roObserve).toHaveBeenLastCalledWith(screen.getByTestId("content"));
+  });
+
   it("configures IO with 80px bottom root margin", () => {
     render(<Harness />);
     const IOConstructor = vi.mocked(IntersectionObserver);

package/src/internal/__tests__/useFetch-poll-under-render-pressure.test.tsx

@@ -0,0 +1,79 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { act, render, cleanup } from "@testing-library/react";
+import { useEffect, useState } from "react";
+import { useFetch } from "../useFetch";
+import { advanceInSlices } from "./fake-timer-slices";
+
+/**
+ * The F-14 starvation net (channel-conversations T06): a polling
+ * `useFetch` must keep its interval's phase across re-renders of its
+ * host component.
+ *
+ * Every real consumer passes an inline closure as `fetchFn`, which is
+ * referentially new on each render. If the interval effect keys on that
+ * identity, any co-mounted render source with a period shorter than the
+ * poll interval tears the timer down before it can ever fire — the
+ * interval needs an uninterrupted `refetchInterval` window that
+ * structurally never arrives. In production this starved the
+ * conversation timeline (5s poll) and inbox (20s poll) under
+ * `useConversation`'s 5s render cadence, deterministically.
+ *
+ * The ticker period here (600ms) is deliberately SHORTER than the poll
+ * interval (1000ms) and misaligned with it. Do not "simplify" this to
+ * aligned periods: when both timers share a phase under fake timers,
+ * both callbacks fire inside the same advanced instant — before React
+ * commits the re-render that would tear the poll timer down — and the
+ * starvation never manifests, leaving a test that cannot fail.
+ */
+
+/** Calls `useFetch` the way every real consumer does: inline closure. */
+function PollingConsumer({ onFetch }: { readonly onFetch: () => void }) {
+  useFetch(
+    async () => {
+      onFetch();
+      return "ok";
+    },
+    [],
+    "",
+    { refetchInterval: 1000 },
+  );
+  return null;
+}
+
+/** Re-renders its subtree every 600ms — the fast co-mounted render source. */
+function RenderPressureHost({ onFetch }: { readonly onFetch: () => void }) {
+  const [, setTick] = useState(0);
+  useEffect(() => {
+    const id = setInterval(() => setTick((t) => t + 1), 600);
+    return () => clearInterval(id);
+  }, []);
+  return <PollingConsumer onFetch={onFetch} />;
+}
+
+describe("useFetch — polling under render pressure (F-14)", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    cleanup();
+    vi.useRealTimers();
+  });
+
+  it("keeps polling while a faster sibling re-renders the consumer every 600ms", async () => {
+    const onFetch = vi.fn();
+    render(<RenderPressureHost onFetch={onFetch} />);
+
+    // Flush the initial fetch.
+    await act(async () => {
+      await Promise.resolve();
+    });
+    expect(onFetch).toHaveBeenCalledTimes(1);
+
+    // 3 seconds under render pressure: the ticker re-renders at 600ms,
+    // 1200ms, 1800ms, 2400ms, 3000ms. The poll interval must still fire
+    // at 1000ms, 2000ms, and 3000ms — its phase survives the renders.
+    await advanceInSlices(3000);
+    expect(onFetch).toHaveBeenCalledTimes(4);
+  });
+});

package/src/internal/tooltip.tsx

@@ -40,7 +40,12 @@ function TooltipContent({
   const portalContainer = useStigmerPortalContainer();
 
   return (
-    <TooltipPrimitive.Portal container={portalContainer}>
+    // `?? undefined`, never a raw null: Base UI treats an EXPLICIT null
+    // container as "wait for one" and renders the popup nowhere, while
+    // undefined falls back to document.body — the standalone behavior
+    // `useStigmerPortalContainer` documents. Without the coalesce, a
+    // tooltip outside a StigmerProvider opens invisibly.
+    <TooltipPrimitive.Portal container={portalContainer ?? undefined}>
       <TooltipPrimitive.Positioner
         className="isolate z-50 outline-none"
         side={side}

package/src/internal/useAutoScroll.ts

@@ -11,12 +11,20 @@ import { useCallback, useEffect, useRef, useState } from "react";
 const NEAR_BOTTOM_MARGIN_PX = 80;
 
 export interface UseAutoScrollReturn {
-  /** Attach to the scrollable container. */
+  /** Attach to the scrollable container. Must be mounted from the first render. */
   readonly scrollRef: React.RefObject<HTMLDivElement | null>;
-  /** Attach to a zero-height div as the last child of the scroll container. */
+  /**
+   * Attach to a zero-height div as the last child of the scroll container.
+   * Must be mounted from the first render.
+   */
   readonly sentinelRef: React.RefObject<HTMLDivElement | null>;
-  /** Attach to a wrapper div around the thread content (ResizeObserver target). */
-  readonly contentRef: React.RefObject<HTMLDivElement | null>;
+  /**
+   * Attach to a wrapper div around the thread content (ResizeObserver
+   * target). MAY mount late or round-trip through unmount — a callback
+   * ref, so consumers whose content sits inside a loading branch (the
+   * conversation timeline) are observed the moment the wrapper appears.
+   */
+  readonly contentRef: React.RefCallback<HTMLDivElement>;
   /** True when the thread auto-scrolls to follow new content. */
   readonly isFollowing: boolean;
   /** Scroll to the latest content and re-engage follow mode. */
@@ -39,12 +47,24 @@ export interface UseAutoScrollReturn {
  * detects height growth and triggers rAF-batched scroll writes when
  * in the Following state.
  *
+ * Ref contract (asymmetric on purpose): the scroller and sentinel must
+ * exist from the first render — every thread renders its scroll pane
+ * unconditionally, and the observers that need them attach once at
+ * mount. The CONTENT wrapper may appear later or round-trip through
+ * unmount: chat threads legitimately render a loading skeleton first
+ * (the conversation timeline does), so `contentRef` is a callback ref
+ * that owns the ResizeObserver's lifecycle — React hands it the node on
+ * attach and `null` on detach, so the observer follows the wrapper
+ * wherever it goes, with no render cost. Attaching only at mount
+ * shipped channel-conversations F-09: a late-mounting wrapper was never
+ * observed, so every conversation opened at its oldest message and
+ * nothing ever scrolled the view.
+ *
  * @internal Not part of the public API.
  */
 export function useAutoScroll(): UseAutoScrollReturn {
   const scrollRef = useRef<HTMLDivElement | null>(null);
   const sentinelRef = useRef<HTMLDivElement | null>(null);
-  const contentRef = useRef<HTMLDivElement | null>(null);
 
   const [isFollowing, setIsFollowing] = useState(true);
   const isFollowingRef = useRef(true);
@@ -67,10 +87,20 @@ export function useAutoScroll(): UseAutoScrollReturn {
     scroller.scrollTop = scroller.scrollHeight;
 
     const io = new IntersectionObserver(
-      (entries) => {
-        const entry = entries[0];
-        if (!entry) return;
-        const visible = entry.isIntersecting;
+      () => {
+        // The delivery is the signal; the LIVE geometry is the truth.
+        // An entry snapshots geometry at OBSERVATION time and can be
+        // delivered after the reader has scrolled again — measured in
+        // the F-09 net: a stale "visible" (captured at the pinned
+        // instant) landed after a scroll-up, re-engaged follow, and the
+        // next growth yanked the reader to the bottom. Measuring at
+        // delivery time keeps the observer as a poll-free change
+        // detector without trusting its stale payload.
+        const el = scrollRef.current;
+        if (!el) return;
+        const visible =
+          el.scrollHeight - el.scrollTop - el.clientHeight <=
+          NEAR_BOTTOM_MARGIN_PX;
         isFollowingRef.current = visible;
         setIsFollowing(visible);
       },
@@ -86,25 +116,41 @@ export function useAutoScroll(): UseAutoScrollReturn {
   }, []);
 
   // --- ResizeObserver: scroll on content height growth while following ---
-  useEffect(() => {
-    const content = contentRef.current;
-    if (!content || !scrollRef.current) return;
+  // Lifecycle lives in the callback ref (not a run-once effect): the
+  // observer must adopt a wrapper that mounts after a loading branch and
+  // let go of one that unmounts — including on component unmount, where
+  // React also calls the ref with null. Its initial delivery on observe()
+  // doubles as the first-fill bottom pin. The scroller is read lazily at
+  // fire time (deliveries are async, after every commit's refs are set).
+  const resizeObserverRef = useRef<ResizeObserver | null>(null);
+  const contentRef = useCallback((node: HTMLDivElement | null) => {
+    resizeObserverRef.current?.disconnect();
+    resizeObserverRef.current = null;
+    cancelAnimationFrame(rafIdRef.current);
+    if (!node) return;
 
     const ro = new ResizeObserver(() => {
       if (!isFollowingRef.current) return;
       cancelAnimationFrame(rafIdRef.current);
+      // The reader-took-control guard, decided at WRITE time: a frame
+      // can lag (headless and busy tabs throttle rAF) long enough for
+      // the reader to scroll up between scheduling and writing, and a
+      // stale pin then yanks them back to the bottom (the F-09 suite's
+      // scrolled-up case, flaking ~1-in-5 under real Chromium). The
+      // discriminator is scrollTop itself: content growth never moves
+      // it, only the reader does — `isFollowingRef` cannot arbitrate
+      // here because growth makes the sentinel leave the viewport
+      // transiently, so the flag reads false mid-pin by design.
+      const scheduledAt = scrollRef.current?.scrollTop ?? null;
       rafIdRef.current = requestAnimationFrame(() => {
         const el = scrollRef.current;
-        if (el) el.scrollTop = el.scrollHeight;
+        if (!el) return;
+        if (scheduledAt !== null && el.scrollTop !== scheduledAt) return;
+        el.scrollTop = el.scrollHeight;
       });
     });
-
-    ro.observe(content);
-
-    return () => {
-      ro.disconnect();
-      cancelAnimationFrame(rafIdRef.current);
-    };
+    ro.observe(node);
+    resizeObserverRef.current = ro;
   }, []);
 
   const jumpToLatest = useCallback(() => {

package/src/internal/useFetch.ts

@@ -182,18 +182,29 @@ export function useFetch<T>(
     };
   }, [...deps, fetchKey]);
 
+  // The two effects below use `fetchFn` only as an enabled/disabled
+  // signal — they trigger fetches through `refetch()`, and the fetch
+  // effect above already closes over the current render's `fetchFn`.
+  // Keying them on this boolean instead of on `fetchFn` itself is
+  // load-bearing: consumers pass inline closures (referentially new
+  // every render), so an identity dep tears the interval down on every
+  // render — and under any co-mounted faster render source the timer
+  // never completes a period and the consumer never polls at all
+  // (channel-conversations F-14; pinned by the render-pressure tests).
+  const fetchEnabled = fetchFn !== null;
+
   const refetchInterval = options?.refetchInterval;
   useEffect(() => {
-    if (!refetchInterval || refetchInterval <= 0 || !fetchFn) return;
+    if (!refetchInterval || refetchInterval <= 0 || !fetchEnabled) return;
     const id = setInterval(() => {
       if (!isFetchingRef.current) refetch();
     }, refetchInterval);
     return () => clearInterval(id);
-  }, [refetchInterval, fetchFn, refetch]);
+  }, [refetchInterval, fetchEnabled, refetch]);
 
   const refetchOnWindowFocus = options?.refetchOnWindowFocus;
   useEffect(() => {
-    if (!refetchOnWindowFocus || !fetchFn) return;
+    if (!refetchOnWindowFocus || !fetchEnabled) return;
     if (typeof window === "undefined") return;
     const onActive = () => {
       if (!isFetchingRef.current) refetch();
@@ -207,7 +218,7 @@ export function useFetch<T>(
       window.removeEventListener("focus", onActive);
       document.removeEventListener("visibilitychange", onVisible);
     };
-  }, [refetchOnWindowFocus, fetchFn, refetch]);
+  }, [refetchOnWindowFocus, fetchEnabled, refetch]);
 
   const isLoading = isFetching && !hasDataRef.current;
   const isRefetching = isFetching && hasDataRef.current;