@stigmer/react 3.12.8 → 3.12.9

package/src/execution/__tests__/message-thread-recalled-memories.test.tsx

@@ -0,0 +1,216 @@
+// Thread emission rules for the retriever transparency card
+// (stigmer/stigmer#293 Phase 3a, DD-008 D5). The load-bearing pins:
+//
+//   1. The card is a PER-SEGMENT item derived from each execution's own
+//      spec+status — NOT a live-only tail indicator like setup-progress.
+//      A historical (non-active) execution keeps its card forever; that
+//      is the audit property, and the regression this file exists to
+//      catch (a live-only mechanism would render correctly during
+//      streaming and silently lose the record afterwards).
+//   2. Absent report and selection_active=false both render NOTHING —
+//      wholesale is the unchanged majority behavior and earns no noise.
+//   3. The card is gated on the REPORT, not the prompt bubble:
+//      syntheticUserPrompt deliberately skips some user turns (empty
+//      prompt), and those executions can still be selection-active.
+
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, screen, cleanup } from "@testing-library/react";
+import { create } from "@bufbuild/protobuf";
+import {
+  AgentExecutionSchema,
+  AgentExecutionStatusSchema,
+  RecalledMemoriesReportSchema,
+  type AgentExecution,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import {
+  AgentExecutionSpecSchema,
+  RecalledMemoriesSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
+import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+import { AgentMessageSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import {
+  ExecutionPhase,
+  MessageType,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+import { MessageThread } from "../MessageThread";
+
+// useAutoScroll depends on browser APIs not available in happy-dom.
+beforeEach(() => {
+  vi.stubGlobal(
+    "IntersectionObserver",
+    vi.fn(() => ({
+      observe: vi.fn(),
+      unobserve: vi.fn(),
+      disconnect: vi.fn(),
+      takeRecords: vi.fn(() => []),
+      root: null,
+      rootMargin: "",
+      thresholds: [0],
+    })),
+  );
+  vi.stubGlobal(
+    "ResizeObserver",
+    vi.fn(() => ({ observe: vi.fn(), unobserve: vi.fn(), disconnect: vi.fn() })),
+  );
+});
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+function makeExecution(opts: {
+  id: string;
+  specMessage?: string;
+  facts?: ReadonlyArray<{ id: string; content: string }>;
+  report?: { selectionActive: boolean; injectedMemoryIds?: string[] };
+}): AgentExecution {
+  const exec = create(AgentExecutionSchema);
+  exec.metadata = create(ApiResourceMetadataSchema, { id: opts.id });
+
+  const spec = create(AgentExecutionSpecSchema);
+  spec.message = opts.specMessage ?? "Hello";
+  if (opts.facts) {
+    spec.recalledMemories = create(RecalledMemoriesSchema, {
+      enabled: true,
+      facts: opts.facts.map((f) => ({ memoryId: f.id, content: f.content })),
+    });
+  }
+  exec.spec = spec;
+
+  const status = create(AgentExecutionStatusSchema);
+  status.phase = ExecutionPhase.EXECUTION_COMPLETED;
+  status.messages = [
+    create(AgentMessageSchema, { type: MessageType.MESSAGE_AI, content: "Done." }),
+  ];
+  if (opts.report) {
+    status.recalledMemoriesReport = create(RecalledMemoriesReportSchema, {
+      selectionActive: opts.report.selectionActive,
+      injectedMemoryIds: opts.report.injectedMemoryIds ?? [],
+      embeddingModel: opts.report.selectionActive ? "text-embedding-3-small" : "",
+    });
+  }
+  exec.status = status;
+  return exec;
+}
+
+const FACTS = [
+  { id: "mem_a", content: "Prefers concise answers." },
+  { id: "mem_b", content: "Deploys with Bazel." },
+  { id: "mem_c", content: "Reviews PRs on Fridays." },
+];
+
+describe("MessageThread recalled-memories item", () => {
+  it("emits the card inside a selection-active execution's segment, after the user turn", () => {
+    render(
+      <MessageThread
+        executions={[
+          makeExecution({
+            id: "e1",
+            specMessage: "prompt text",
+            facts: FACTS,
+            report: { selectionActive: true, injectedMemoryIds: ["mem_a", "mem_c"] },
+          }),
+        ]}
+      />,
+    );
+
+    const card = screen.getByRole("status", { name: "Recalled 2 of 3 memories" });
+    const userBubble = screen.getByRole("article", { name: "User message" });
+    // Segment order: user turn first, then the card the turn's prompt selected.
+    expect(
+      userBubble.compareDocumentPosition(card) & Node.DOCUMENT_POSITION_FOLLOWING,
+    ).toBeTruthy();
+  });
+
+  it("emits nothing for an absent report (pre-3a and no-injection executions read identically)", () => {
+    render(
+      <MessageThread
+        executions={[makeExecution({ id: "e1", facts: FACTS })]}
+      />,
+    );
+    expect(screen.queryByRole("status", { name: /Recalled/ })).toBeNull();
+  });
+
+  it("emits nothing for a wholesale report (selection_active=false)", () => {
+    render(
+      <MessageThread
+        executions={[
+          makeExecution({
+            id: "e1",
+            facts: FACTS,
+            report: { selectionActive: false },
+          }),
+        ]}
+      />,
+    );
+    expect(screen.queryByRole("status", { name: /Recalled/ })).toBeNull();
+  });
+
+  it("keeps the card on a HISTORICAL execution while another execution streams", () => {
+    // The audit pin: the card derives from the execution's own segment, so
+    // it must survive the execution no longer being the active stream — a
+    // live-only mechanism (the setup-progress shape) would lose it here.
+    const historical = makeExecution({
+      id: "e-old",
+      specMessage: "earlier turn",
+      facts: FACTS,
+      report: { selectionActive: true, injectedMemoryIds: ["mem_b"] },
+    });
+    const live = makeExecution({ id: "e-live", specMessage: "current turn" });
+    live.status!.phase = ExecutionPhase.EXECUTION_IN_PROGRESS;
+
+    render(
+      <MessageThread executions={[historical]} activeStreamExecution={live} />,
+    );
+
+    expect(
+      screen.getByRole("status", { name: "Recalled 1 of 3 memories" }),
+    ).toBeTruthy();
+  });
+
+  it("emits one card per selection-active execution", () => {
+    render(
+      <MessageThread
+        executions={[
+          makeExecution({
+            id: "e1",
+            facts: FACTS,
+            report: { selectionActive: true, injectedMemoryIds: ["mem_a"] },
+          }),
+          makeExecution({ id: "e2", facts: FACTS }),
+          makeExecution({
+            id: "e3",
+            facts: FACTS,
+            report: { selectionActive: true, injectedMemoryIds: ["mem_a", "mem_b"] },
+          }),
+        ]}
+      />,
+    );
+
+    expect(screen.getByRole("status", { name: "Recalled 1 of 3 memories" })).toBeTruthy();
+    expect(screen.getByRole("status", { name: "Recalled 2 of 3 memories" })).toBeTruthy();
+    expect(screen.getAllByRole("status", { name: /Recalled/ })).toHaveLength(2);
+  });
+
+  it("emits the card even when the user-turn bubble is skipped (empty prompt)", () => {
+    render(
+      <MessageThread
+        executions={[
+          makeExecution({
+            id: "e1",
+            specMessage: "",
+            facts: FACTS,
+            report: { selectionActive: true, injectedMemoryIds: ["mem_c"] },
+          }),
+        ]}
+      />,
+    );
+
+    expect(screen.queryByRole("article", { name: "User message" })).toBeNull();
+    expect(
+      screen.getByRole("status", { name: "Recalled 1 of 3 memories" }),
+    ).toBeTruthy();
+  });
+});

package/src/execution/__tests__/message-thread-scroll-on-send.test.tsx

@@ -0,0 +1,141 @@
+// Scroll-on-send wiring pins for MessageThread (stigmer-cloud#267): the
+// send moment is the optimistic message's empty→present transition, and it
+// must pin the thread exactly once — default-ON, opt-out via
+// `scrollOnSend={false}` (the ratified DD-011 divergence). The REAL scroll
+// mechanics (pin + follow re-engagement under real layout) are pinned in
+// `internal/__tests__/useAutoScroll.layout.test.tsx`; this file pins the
+// surface's signal derivation through a spied `jumpToLatest`, with the real
+// `usePinToLatestOnSignal` connecting them.
+
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { render, cleanup } from "@testing-library/react";
+import { create } from "@bufbuild/protobuf";
+import {
+  AgentExecutionSchema,
+  type AgentExecution,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { AgentExecutionSpecSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
+import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+
+const jumpToLatestSpy = vi.fn();
+
+// The fake replaces only the scroll machine (browser observers happy-dom
+// lacks); `usePinToLatestOnSignal` stays REAL, so these tests exercise the
+// actual signal contract between MessageThread and its render paths.
+vi.mock("../../internal/useAutoScroll", async (importOriginal) => {
+  const original =
+    await importOriginal<typeof import("../../internal/useAutoScroll")>();
+  return {
+    ...original,
+    useAutoScroll: () => ({
+      scrollRef: { current: null },
+      sentinelRef: { current: null },
+      contentRef: () => {},
+      isFollowing: true,
+      jumpToLatest: jumpToLatestSpy,
+    }),
+  };
+});
+
+import { MessageThread } from "../MessageThread";
+
+afterEach(() => {
+  cleanup();
+  jumpToLatestSpy.mockClear();
+});
+
+function makeExecution(id: string, message: string): AgentExecution {
+  const exec = create(AgentExecutionSchema);
+  const meta = create(ApiResourceMetadataSchema);
+  meta.id = id;
+  exec.metadata = meta;
+  const spec = create(AgentExecutionSpecSchema);
+  spec.message = message;
+  exec.spec = spec;
+  return exec;
+}
+
+describe("MessageThread — scroll-on-send (stigmer-cloud#267)", () => {
+  it("pins the thread exactly once when the optimistic message appears (default-on)", () => {
+    const executions = [makeExecution("aex_1", "earlier turn")];
+    const { rerender } = render(
+      <MessageThread executions={executions} pendingUserMessage={null} />,
+    );
+    expect(jumpToLatestSpy).not.toHaveBeenCalled();
+
+    // The send: the composer sets the optimistic message.
+    rerender(
+      <MessageThread executions={executions} pendingUserMessage="do the thing" />,
+    );
+    expect(jumpToLatestSpy).toHaveBeenCalledTimes(1);
+
+    // Re-renders while the message stays pending must not re-pin — the
+    // reader may have scrolled up again to read history mid-turn.
+    rerender(
+      <MessageThread executions={executions} pendingUserMessage="do the thing" />,
+    );
+    expect(jumpToLatestSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("pins again on the NEXT send after the pending message clears", () => {
+    const executions = [makeExecution("aex_1", "earlier turn")];
+    const { rerender } = render(
+      <MessageThread executions={executions} pendingUserMessage={null} />,
+    );
+
+    rerender(
+      <MessageThread executions={executions} pendingUserMessage="first send" />,
+    );
+    rerender(<MessageThread executions={executions} pendingUserMessage={null} />);
+    rerender(
+      <MessageThread executions={executions} pendingUserMessage="second send" />,
+    );
+
+    expect(jumpToLatestSpy).toHaveBeenCalledTimes(2);
+  });
+
+  it("does not re-pin on a failed send's retry — pending stays present throughout, and the reader was already brought to it", () => {
+    const executions = [makeExecution("aex_1", "earlier turn")];
+    const { rerender } = render(
+      <MessageThread executions={executions} pendingUserMessage={null} />,
+    );
+
+    rerender(
+      <MessageThread executions={executions} pendingUserMessage="flaky send" />,
+    );
+    rerender(
+      <MessageThread
+        executions={executions}
+        pendingUserMessage="flaky send"
+        pendingMessageFailed
+        onRetrySend={() => {}}
+      />,
+    );
+    rerender(
+      <MessageThread executions={executions} pendingUserMessage="flaky send" />,
+    );
+
+    expect(jumpToLatestSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("never pins with scrollOnSend={false} — the opt-out preserves today's leave-the-reader-alone behavior", () => {
+    const executions = [makeExecution("aex_1", "earlier turn")];
+    const { rerender } = render(
+      <MessageThread
+        executions={executions}
+        pendingUserMessage={null}
+        scrollOnSend={false}
+      />,
+    );
+
+    rerender(
+      <MessageThread
+        executions={executions}
+        pendingUserMessage="do the thing"
+        scrollOnSend={false}
+      />,
+    );
+
+    expect(jumpToLatestSpy).not.toHaveBeenCalled();
+  });
+});

package/src/execution/__tests__/message-thread-slots.test.tsx

@@ -5,11 +5,13 @@ import { create } from "@bufbuild/protobuf";
 import {
   AgentExecutionSchema,
   AgentExecutionStatusSchema,
+  RecalledMemoriesReportSchema,
   type AgentExecution,
 } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
 import {
   AgentExecutionSpecSchema,
   ExecutionConfigSchema,
+  RecalledMemoriesSchema,
 } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
 import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
 import { AgentMessageSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
@@ -32,6 +34,7 @@ import type { ExecutionErrorNoticeProps } from "../ExecutionErrorNotice";
 import type { TodoCardProps } from "../TodoCard";
 import type { TodoRowProps } from "../TodoList";
 import type { SetupProgressProps } from "../SetupProgress";
+import type { RecalledMemoriesCardProps } from "../RecalledMemoriesCard";
 import type { LivenessStatusLineProps } from "../LivenessStatusLine";
 import type { PlanCompletionCardProps } from "../PlanCompletionCard";
 import type { PlanArtifactCardProps } from "../PlanArtifactCard";
@@ -318,6 +321,39 @@ describe("MessageThread slots", () => {
     expect(screen.getByTestId("custom-setup").textContent).toBe("waiting");
   });
 
+  it("renders the RecalledMemoriesCard slot for a selection-active execution", () => {
+    const CustomRecalled = ({ report, facts }: RecalledMemoriesCardProps) => (
+      <div data-testid="custom-recalled">
+        {report.injectedMemoryIds.length} of {facts.length}
+      </div>
+    );
+
+    const exec = makeExecution({ id: "e1" });
+    exec.spec!.recalledMemories = create(RecalledMemoriesSchema, {
+      enabled: true,
+      facts: [
+        { memoryId: "mem_a", content: "Prefers concise answers." },
+        { memoryId: "mem_b", content: "Deploys with Bazel." },
+      ],
+    });
+    exec.status!.recalledMemoriesReport = create(RecalledMemoriesReportSchema, {
+      selectionActive: true,
+      injectedMemoryIds: ["mem_a"],
+      embeddingModel: "text-embedding-3-small",
+    });
+
+    render(
+      <MessageThread
+        executions={[exec]}
+        slots={{ RecalledMemoriesCard: CustomRecalled }}
+      />,
+    );
+
+    expect(screen.getByTestId("custom-recalled").textContent).toBe("1 of 2");
+    // The built-in card must not render alongside the override.
+    expect(screen.queryByRole("status", { name: /Recalled/ })).toBeNull();
+  });
+
   it("renders the LivenessStatusLine slot while the execution is live between events", () => {
     const CustomLiveness = ({ label }: LivenessStatusLineProps) => (
       <div data-testid="custom-liveness">{label ?? "custom-live"}</div>

package/src/execution/index.ts

@@ -42,6 +42,8 @@ export type { SummarizationBadgeProps } from "./SummarizationBadge.js";
 
 export { SummarizationCard } from "./SummarizationCard.js";
 export type { SummarizationCardProps } from "./SummarizationCard.js";
+export { RecalledMemoriesCard, resolveInjectedFacts } from "./RecalledMemoriesCard.js";
+export type { RecalledMemoriesCardProps } from "./RecalledMemoriesCard.js";
 
 export { PlanCompletionCard } from "./PlanCompletionCard.js";
 export type { PlanCompletionCardProps } from "./PlanCompletionCard.js";

package/src/identity-account/AccountPreferencesPanel.tsx

@@ -416,7 +416,7 @@ function AccountPreferencesForm({
         onToggle={(next) => void handleMemoryToggle(next)}
         saving={isSavingMemoryFlag}
         error={memoryFlagError}
-        helperText="When on, agents may propose facts to remember about you; only facts you confirm are stored. Confirmed memories are shared with your future sessions and appear on those executions' records. Requires your organization to have memory enabled. Changes apply immediately."
+        helperText="When on, agents may propose facts to remember about you; only facts you confirm are stored. Confirmed memories are shared with your future sessions and appear on those executions' records; once you have many, each conversation recalls the most relevant ones, shown on the execution. Requires your organization to have memory enabled. Changes apply immediately."
       />
 
       {updateError && (

package/src/index.ts

@@ -286,6 +286,8 @@ export {
   ContextGauge,
   SummarizationBadge,
   SummarizationCard,
+  RecalledMemoriesCard,
+  resolveInjectedFacts,
   PlanCompletionCard,
   PlanArtifactCard,
   PlanStreamingCard,
@@ -412,6 +414,7 @@ export type {
   ContextGaugeProps,
   SummarizationBadgeProps,
   SummarizationCardProps,
+  RecalledMemoriesCardProps,
   PlanCompletionCardProps,
   PlanArtifactCardProps,
   PlanStreamingCardProps,

package/src/internal/VirtualizedThread.tsx

@@ -25,6 +25,7 @@ import { ApprovalContext, type ApprovalContextValue } from "../execution/Approva
 import { FileReviewContext, type FileReviewContextValue } from "../execution/FileReviewContext.js";
 import { DevProfiler, useDomNodeCount } from "./dev/index.js";
 import { JumpToLatestButton } from "./JumpToLatestButton.js";
+import { usePinToLatestOnSignal } from "./useAutoScroll.js";
 import { ApprovalPeekBar } from "./ApprovalPeekBar.js";
 import { ThreadItemWrapper } from "./ThreadItemWrapper.js";
 
@@ -57,6 +58,8 @@ export interface VirtualizedThreadProps {
   readonly onRetryExecution?: (message: string) => void;
   readonly onEditMessage?: (text: string) => void;
   readonly slots?: MessageThreadSlots;
+  /** Scroll-on-send counter from `MessageThread` (see `usePinToLatestOnSignal`). */
+  readonly pinToLatestSignal?: number;
 }
 
 // ---------------------------------------------------------------------------
@@ -127,6 +130,7 @@ export function VirtualizedThread({
   onRetryExecution,
   onEditMessage,
   slots,
+  pinToLatestSignal,
 }: VirtualizedThreadProps) {
   const virtuosoRef = useRef<VirtuosoHandle>(null);
   const scrollerRef = useRef<HTMLDivElement | null>(null);
@@ -149,6 +153,7 @@ export function VirtualizedThread({
       behavior: "smooth",
     });
   }, []);
+  usePinToLatestOnSignal(pinToLatestSignal, jumpToLatest);
 
   const renderProps = useMemo(
     () => ({

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

@@ -17,7 +17,11 @@
 
 import { describe, it, expect, vi, afterEach } from "vitest";
 import { render, cleanup } from "@testing-library/react";
-import { useAutoScroll, type UseAutoScrollReturn } from "../useAutoScroll";
+import {
+  useAutoScroll,
+  usePinToLatestOnSignal,
+  type UseAutoScrollReturn,
+} from "../useAutoScroll";
 
 const VIEWPORT_PX = 240;
 const ITEM_PX = 48;
@@ -125,9 +129,11 @@ describe("useAutoScroll under real layout (F-09)", () => {
     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.
+    // Growth while disengaged (an INCOMING message): the view must NOT
+    // move under them. Unchanged by scroll-on-send (stigmer-cloud#267):
+    // the reader's OWN send now pins via the surface-driven signal
+    // (`usePinToLatestOnSignal`, suite below) — the hook's growth pathway
+    // itself still never moves a scrolled-up reader.
     rerender(<AsyncThread items={messages(31)} />);
     await new Promise((resolve) => setTimeout(resolve, 100));
     expect(scroller().scrollTop).toBe(0);
@@ -141,3 +147,98 @@ describe("useAutoScroll under real layout (F-09)", () => {
     });
   });
 });
+
+// ---------------------------------------------------------------------------
+// Scroll-on-send: the surface-driven pin signal (stigmer-cloud#267)
+// ---------------------------------------------------------------------------
+
+/**
+ * AsyncThread plus the send-signal seam every thread surface wires — same
+ * late-mounting wrapper shape (see the determinism note above: the bottom
+ * pin coming from the ResizeObserver pathway is what makes the scroll-up
+ * steps race-free).
+ */
+function SignalThread({
+  items,
+  signal,
+}: {
+  readonly items: readonly string[];
+  readonly signal: number | undefined;
+}) {
+  const hook = useAutoScroll();
+  latest = hook;
+  usePinToLatestOnSignal(signal, hook.jumpToLatest);
+  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>
+  );
+}
+
+describe("usePinToLatestOnSignal under real layout (stigmer-cloud#267)", () => {
+  it("a signal increment pins a scrolled-up reader to the latest content and re-engages follow", async () => {
+    const { rerender } = render(<SignalThread items={[]} signal={0} />);
+    rerender(<SignalThread items={messages(30)} signal={0} />);
+    await settled(() => {
+      expect(isPinnedToBottom(scroller())).toBe(true);
+      // Follow-STATE quiescence before the reader scrolls (the F-09
+      // case's own discipline) — a queued pre-scroll TRUE must not
+      // re-arm follow behind the scroll-up.
+      expect(latest.isFollowing).toBe(true);
+    });
+
+    // The reader deliberately scrolls up — follow disengages.
+    scroller().scrollTop = 0;
+    await settled(() => expect(latest.isFollowing).toBe(false));
+
+    // Their OWN send: the surface increments the signal. The pin fires
+    // AND re-engages follow, so the reply that streams in next stays in
+    // view — the whole point of stigmer-cloud#267.
+    rerender(<SignalThread items={messages(30)} signal={1} />);
+    await settled(() => {
+      expect(isPinnedToBottom(scroller())).toBe(true);
+      expect(latest.isFollowing).toBe(true);
+    });
+
+    // And subsequent growth (the streamed reply) keeps following.
+    rerender(<SignalThread items={messages(31)} signal={1} />);
+    await settled(() => expect(isPinnedToBottom(scroller())).toBe(true));
+  });
+
+  it("never pins on mount, on an unchanged signal, or on the undefined→number transition (opt-out and prop-appearing are not sends)", async () => {
+    // Mount without a signal: no pin beyond the hook's own first-fill.
+    const { rerender } = render(<SignalThread items={[]} signal={undefined} />);
+    rerender(<SignalThread items={messages(30)} signal={undefined} />);
+    await settled(() => {
+      expect(isPinnedToBottom(scroller())).toBe(true);
+      expect(latest.isFollowing).toBe(true);
+    });
+
+    scroller().scrollTop = 0;
+    await settled(() => expect(latest.isFollowing).toBe(false));
+
+    // undefined → number (the surface flips scrollOnSend back on, or the
+    // prop gets wired late): a prop appearing is not a send.
+    rerender(<SignalThread items={messages(30)} signal={3} />);
+    // Unchanged signal on a later render: also not a send.
+    rerender(<SignalThread items={messages(30)} signal={3} />);
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    expect(scroller().scrollTop).toBe(0);
+    expect(latest.isFollowing).toBe(false);
+  });
+});

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

@@ -121,13 +121,20 @@ afterEach(() => {
  * 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.
+ *
+ * The far-from-bottom position is 100, not 0, and that is load-bearing:
+ * the hook disengages only when the READER moved (scrollTop differs from
+ * the hook's own last write — the growth-vs-reader discriminator,
+ * stigmer-cloud#267), and in this harness the mount write landed at 0
+ * (happy-dom scrollHeight is 0 at mount). A real reader's scroll-up always
+ * moves scrollTop off the pin position; 100 simulates exactly that.
  */
 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;
+  scroller.scrollTop = nearBottom ? 800 : 100;
   act(() => {
     ioCallback([], {} as IntersectionObserver);
   });
@@ -212,6 +219,39 @@ describe("useAutoScroll", () => {
     expect(latestResult.isFollowing).toBe(true);
   });
 
+  it("holds follow when a not-visible delivery measures growth under the hook's own pin — only the READER may disengage (stigmer-cloud#267)", () => {
+    render(<Harness />);
+    const scroller = screen.getByTestId("scroller");
+    Object.defineProperty(scroller, "clientHeight", { value: 200, configurable: true });
+
+    // The hook pins: jumpToLatest writes scrollTop = scrollHeight and
+    // records the write.
+    Object.defineProperty(scroller, "scrollHeight", { value: 1000, configurable: true });
+    act(() => {
+      latestResult.jumpToLatest();
+    });
+    expect(scroller.scrollTop).toBe(1000);
+
+    // Content grows UNDER the pin before the RO write runs; a queued IO
+    // delivery measures the post-growth geometry: far from the bottom,
+    // yet scrollTop still sits exactly on the hook's own write — the
+    // reader never moved. Disengaging here would make the imminent RO
+    // callback drop its write and strand the thread (the deadlock the
+    // browser suite reproduced ~1-in-5 before the discriminator).
+    Object.defineProperty(scroller, "scrollHeight", { value: 2000, configurable: true });
+    act(() => {
+      ioCallback([], {} as IntersectionObserver);
+    });
+    expect(latestResult.isFollowing).toBe(true);
+
+    // The READER escapes (scrollTop moves off the pin): disengage holds.
+    scroller.scrollTop = 500;
+    act(() => {
+      ioCallback([], {} as IntersectionObserver);
+    });
+    expect(latestResult.isFollowing).toBe(false);
+  });
+
   it("jumpToLatest re-engages follow mode", () => {
     render(<Harness />);
     fireIO(false);