@stigmer/react 0.3.3 → 0.4.0

package/src/execution/__tests__/virtualized-thread.test.tsx

@@ -0,0 +1,401 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, screen, cleanup } from "@testing-library/react";
+import React from "react";
+import { create } from "@bufbuild/protobuf";
+import {
+  AgentExecutionSchema,
+  AgentExecutionStatusSchema,
+} 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";
+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 {
+  buildThreadItems,
+  ThreadItemRenderer,
+  type ThreadItem,
+} from "../MessageThread";
+
+// ---------------------------------------------------------------------------
+// Mock react-virtuoso — Virtuoso's internal scroll/resize machinery
+// does not work in happy-dom. We mock the component to capture props
+// and verify configuration.
+// ---------------------------------------------------------------------------
+
+let capturedVirtuosoProps: Record<string, unknown> = {};
+
+vi.mock("react-virtuoso", () => ({
+  Virtuoso: React.forwardRef(function MockVirtuoso(
+    props: Record<string, unknown>,
+    ref: React.Ref<unknown>,
+  ) {
+    capturedVirtuosoProps = props;
+    const data = props.data as ThreadItem[];
+    const itemContent = props.itemContent as (
+      index: number,
+      item: ThreadItem,
+    ) => React.ReactNode;
+
+    React.useImperativeHandle(ref, () => ({
+      scrollToIndex: vi.fn(),
+    }));
+
+    const Scroller =
+      (
+        props.components as {
+          Scroller?: React.ComponentType<Record<string, unknown>>;
+        }
+      )?.Scroller ?? "div";
+
+    return (
+      <Scroller data-testid="virtuoso-scroller">
+        {data.map((item, i) => (
+          <div key={item.key} data-testid={`virtuoso-item-${i}`}>
+            {itemContent(i, item)}
+          </div>
+        ))}
+      </Scroller>
+    );
+  }),
+}));
+
+// ---------------------------------------------------------------------------
+// Observer / rAF mocks (required for useAutoScroll in non-virtualized path)
+// ---------------------------------------------------------------------------
+
+beforeEach(() => {
+  capturedVirtuosoProps = {};
+
+  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(),
+    })),
+  );
+
+  vi.stubGlobal(
+    "requestAnimationFrame",
+    vi.fn((cb: FrameRequestCallback) => {
+      cb(performance.now());
+      return 1;
+    }),
+  );
+
+  vi.stubGlobal("cancelAnimationFrame", vi.fn());
+});
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeExecution(id: string, specMessage: string, aiContent: string) {
+  const exec = create(AgentExecutionSchema);
+
+  const meta = create(ApiResourceMetadataSchema);
+  meta.id = id;
+  exec.metadata = meta;
+
+  const spec = create(AgentExecutionSpecSchema);
+  spec.message = specMessage;
+  exec.spec = spec;
+
+  const status = create(AgentExecutionStatusSchema);
+  status.phase = ExecutionPhase.EXECUTION_COMPLETED;
+  const humanMsg = create(AgentMessageSchema);
+  humanMsg.type = MessageType.MESSAGE_HUMAN;
+  humanMsg.content = specMessage;
+  const aiMsg = create(AgentMessageSchema);
+  aiMsg.type = MessageType.MESSAGE_AI;
+  aiMsg.content = aiContent;
+  status.messages = [humanMsg, aiMsg];
+  exec.status = status;
+
+  return exec;
+}
+
+// Lazy import — must import after mocks are set up
+async function importMessageThread() {
+  const mod = await import("../MessageThread");
+  return mod.MessageThread;
+}
+
+// ---------------------------------------------------------------------------
+// Tests: ThreadItemRenderer
+// ---------------------------------------------------------------------------
+
+describe("ThreadItemRenderer", () => {
+  it("renders a message item", () => {
+    const msg = create(AgentMessageSchema);
+    msg.type = MessageType.MESSAGE_HUMAN;
+    msg.content = "Hello world";
+
+    const item: ThreadItem = { kind: "message", message: msg, key: "test-1" };
+
+    render(<ThreadItemRenderer item={item} />);
+    expect(screen.getByText("Hello world")).toBeTruthy();
+  });
+
+  it("renders a pending message with opacity", () => {
+    const msg = create(AgentMessageSchema);
+    msg.type = MessageType.MESSAGE_HUMAN;
+    msg.content = "Sending...";
+
+    const item: ThreadItem = {
+      kind: "message",
+      message: msg,
+      key: "pending",
+      isPending: true,
+    };
+
+    const { container } = render(<ThreadItemRenderer item={item} />);
+    const root = container.firstElementChild as HTMLElement;
+    expect(root?.className).toContain("opacity-70");
+  });
+
+  it("renders a phase badge item", () => {
+    const item: ThreadItem = {
+      kind: "phase-badge",
+      phase: ExecutionPhase.EXECUTION_FAILED,
+      key: "phase-1",
+    };
+
+    render(<ThreadItemRenderer item={item} />);
+    expect(screen.getByText(/failed/i)).toBeTruthy();
+  });
+
+  it("renders a setup progress item", () => {
+    const item: ThreadItem = {
+      kind: "setup-progress",
+      workspaceEntries: [],
+      key: "setup",
+    };
+
+    render(<ThreadItemRenderer item={item} />);
+    expect(document.querySelector("[class]")).toBeTruthy();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Tests: MessageThread with virtualized=false (default, regression)
+// ---------------------------------------------------------------------------
+
+describe("MessageThread (non-virtualized)", () => {
+  it("renders items in a role=log container by default", async () => {
+    const MessageThread = await importMessageThread();
+    const exec = makeExecution("e1", "Hello", "Hi there");
+
+    render(<MessageThread executions={[exec]} />);
+
+    const log = screen.getByRole("log");
+    expect(log).toBeTruthy();
+    expect(log.getAttribute("aria-live")).toBe("polite");
+    expect(log.getAttribute("aria-relevant")).toBe("additions");
+  });
+
+  it("does not render Virtuoso when virtualized is false", async () => {
+    const MessageThread = await importMessageThread();
+    const exec = makeExecution("e1", "Hello", "Hi");
+
+    render(<MessageThread executions={[exec]} />);
+    expect(capturedVirtuosoProps.data).toBeUndefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Tests: MessageThread with virtualized=true
+// ---------------------------------------------------------------------------
+
+describe("MessageThread (virtualized)", () => {
+  it("renders via Virtuoso when virtualized=true", async () => {
+    const MessageThread = await importMessageThread();
+    const exec = makeExecution("e1", "Hello", "Hi there");
+
+    render(<MessageThread executions={[exec]} virtualized />);
+
+    // Wait for lazy import to resolve
+    await vi.waitFor(() => {
+      expect(capturedVirtuosoProps.data).toBeDefined();
+    });
+
+    const data = capturedVirtuosoProps.data as ThreadItem[];
+    expect(data.length).toBeGreaterThan(0);
+  });
+
+  it("passes alignToBottom=true to Virtuoso", async () => {
+    const MessageThread = await importMessageThread();
+    const exec = makeExecution("e1", "Hello", "Hi");
+
+    render(<MessageThread executions={[exec]} virtualized />);
+
+    await vi.waitFor(() => {
+      expect(capturedVirtuosoProps.alignToBottom).toBe(true);
+    });
+  });
+
+  it("passes followOutput callback to Virtuoso", async () => {
+    const MessageThread = await importMessageThread();
+    const exec = makeExecution("e1", "Hello", "Hi");
+
+    render(<MessageThread executions={[exec]} virtualized />);
+
+    await vi.waitFor(() => {
+      expect(typeof capturedVirtuosoProps.followOutput).toBe("function");
+    });
+
+    const followOutput = capturedVirtuosoProps.followOutput as (
+      atBottom: boolean,
+    ) => string | false;
+    expect(followOutput(true)).toBe("smooth");
+    expect(followOutput(false)).toBe(false);
+  });
+
+  it("uses stable semantic keys via computeItemKey", async () => {
+    const MessageThread = await importMessageThread();
+    const exec = makeExecution("exec-42", "Hello", "Hi");
+
+    render(<MessageThread executions={[exec]} virtualized />);
+
+    await vi.waitFor(() => {
+      expect(capturedVirtuosoProps.computeItemKey).toBeDefined();
+    });
+
+    const data = capturedVirtuosoProps.data as ThreadItem[];
+    const computeItemKey = capturedVirtuosoProps.computeItemKey as (
+      index: number,
+      item: ThreadItem,
+    ) => string;
+
+    for (let i = 0; i < data.length; i++) {
+      expect(computeItemKey(i, data[i])).toBe(data[i].key);
+    }
+  });
+
+  it("sets atBottomThreshold matching the non-virtualized 80px margin", async () => {
+    const MessageThread = await importMessageThread();
+    const exec = makeExecution("e1", "Hello", "Hi");
+
+    render(<MessageThread executions={[exec]} virtualized />);
+
+    await vi.waitFor(() => {
+      expect(capturedVirtuosoProps.atBottomThreshold).toBe(80);
+    });
+  });
+
+  it("applies a11y attributes to the scroller", async () => {
+    const MessageThread = await importMessageThread();
+    const exec = makeExecution("e1", "Hello", "Hi");
+
+    render(<MessageThread executions={[exec]} virtualized />);
+
+    await vi.waitFor(() => {
+      const scroller = screen.getByTestId("virtuoso-scroller");
+      expect(scroller.getAttribute("role")).toBe("log");
+      expect(scroller.getAttribute("aria-live")).toBe("polite");
+      expect(scroller.getAttribute("aria-relevant")).toBe("additions");
+    });
+  });
+
+  it("renders actual thread item content through Virtuoso", async () => {
+    const MessageThread = await importMessageThread();
+    const exec = makeExecution("e1", "Hello from user", "Hello from AI");
+
+    render(<MessageThread executions={[exec]} virtualized />);
+
+    await vi.waitFor(() => {
+      expect(screen.getAllByText("Hello from user").length).toBeGreaterThan(0);
+      expect(screen.getByText("Hello from AI")).toBeTruthy();
+    });
+  });
+
+  it("sets increaseViewportBy for overscan", async () => {
+    const MessageThread = await importMessageThread();
+    const exec = makeExecution("e1", "Hello", "Hi");
+
+    render(<MessageThread executions={[exec]} virtualized />);
+
+    await vi.waitFor(() => {
+      expect(capturedVirtuosoProps.increaseViewportBy).toEqual({
+        top: 200,
+        bottom: 200,
+      });
+    });
+  });
+
+  it("builds the same items for both paths", async () => {
+    const exec = makeExecution("e1", "Hello", "Hi there");
+    const items = buildThreadItems([exec], null, null, false, undefined);
+
+    const MessageThread = await importMessageThread();
+    render(<MessageThread executions={[exec]} virtualized />);
+
+    await vi.waitFor(() => {
+      const data = capturedVirtuosoProps.data as ThreadItem[];
+      expect(data.map((d) => d.key)).toEqual(items.map((i) => i.key));
+    });
+  });
+
+  it("applies entry animation only to tail items (last 2)", async () => {
+    const execs = [
+      makeExecution("e1", "First", "Response 1"),
+      makeExecution("e2", "Second", "Response 2"),
+      makeExecution("e3", "Third", "Response 3"),
+    ];
+
+    const MessageThread = await importMessageThread();
+    render(<MessageThread executions={execs} virtualized />);
+
+    await vi.waitFor(() => {
+      const data = capturedVirtuosoProps.data as ThreadItem[];
+      expect(data.length).toBeGreaterThan(2);
+    });
+
+    const data = capturedVirtuosoProps.data as ThreadItem[];
+    const itemContent = capturedVirtuosoProps.itemContent as (
+      index: number,
+      item: ThreadItem,
+    ) => React.ReactNode;
+    const tailThreshold = data.length - 2;
+
+    // Non-tail item: no animation wrapper
+    const earlyResult = render(
+      <div data-testid="early">{itemContent(0, data[0])}</div>,
+    );
+    expect(
+      earlyResult.container.querySelector(".stgm-thread-item-enter"),
+    ).toBeNull();
+    earlyResult.unmount();
+
+    // Tail item: has animation wrapper
+    const lastIdx = data.length - 1;
+    const tailResult = render(
+      <div data-testid="tail">{itemContent(lastIdx, data[lastIdx])}</div>,
+    );
+    expect(
+      tailResult.container.querySelector(".stgm-thread-item-enter"),
+    ).toBeTruthy();
+    tailResult.unmount();
+  });
+});

package/src/execution/index.ts

@@ -87,6 +87,9 @@ export type { MessageEntryProps } from "./MessageEntry";
 export { MessageThread } from "./MessageThread";
 export type { MessageThreadProps } from "./MessageThread";
 
+export { ThreadSkeleton } from "./ThreadSkeleton";
+export type { ThreadSkeletonProps } from "./ThreadSkeleton";
+
 export { FollowUpInput } from "./FollowUpInput";
 export type { FollowUpInputProps } from "./FollowUpInput";
 

package/src/execution/useExecutionStream.ts

@@ -1,10 +1,24 @@
 "use client";
 
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import {
+  startTransition,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  useSyncExternalStore,
+} from "react";
 import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
 import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { useStigmer } from "../hooks";
 import { toError } from "../internal/toError";
+import { useStreamRate } from "../internal/dev";
+import {
+  StreamController,
+  type StreamControllerSink,
+} from "../internal/stream-controller";
+import { ConversationStore, type StreamState } from "../internal/store";
 import { isTerminalPhase } from "./execution-phases";
 
 /** Return value of {@link useExecutionStream}. */
@@ -14,9 +28,9 @@ export interface UseExecutionStreamReturn {
   /**
    * Convenience extraction of `execution.status.phase`.
    *
-   * Derived from `execution` via `useMemo` — always consistent with the
-   * current snapshot. Returns `EXECUTION_PHASE_UNSPECIFIED` when
-   * `execution` is `null`.
+   * Derived from `execution` — always consistent with the current
+   * snapshot. Returns `EXECUTION_PHASE_UNSPECIFIED` when `execution`
+   * is `null`.
    */
   readonly phase: ExecutionPhase;
   /** `true` while receiving non-terminal updates from the server stream. */
@@ -35,17 +49,42 @@ export interface UseExecutionStreamReturn {
   readonly reconnect: () => void;
 }
 
+/**
+ * Options for {@link useExecutionStream}.
+ */
+export interface UseExecutionStreamOptions {
+  /**
+   * External `ConversationStore` to ingest snapshots into.
+   *
+   * When provided, the hook writes directly to this store and reads
+   * the execution snapshot back via `useSyncExternalStore`. This
+   * allows `useSessionConversation` to share a single store instance
+   * across the stream hook and the rendering tree.
+   *
+   * When omitted, an internal store is created automatically —
+   * preserving backward compatibility for standalone usage.
+   */
+  readonly store?: ConversationStore;
+}
+
 /**
  * Behavior hook that subscribes to real-time {@link AgentExecution}
  * updates via `stigmer.agentExecution.subscribe()`.
  *
- * Manages the full subscription lifecycle: connection establishment,
- * snapshot streaming, terminal-phase detection, error handling, and
- * manual reconnection. Each server message replaces the previous
- * snapshot atomically — no delta merging.
+ * Manages the full subscription lifecycle through a finite state
+ * machine: connection establishment, rAF-coalesced snapshot streaming,
+ * terminal-phase detection, error handling, and manual reconnection.
+ *
+ * **Performance characteristics:**
+ * - Non-terminal snapshots are coalesced via `requestAnimationFrame`
+ *   so React commits at most once per display frame (~60Hz)
+ * - Terminal snapshots (complete/failed/cancelled) flush immediately
+ * - Store updates are wrapped in `startTransition` so thread renders
+ *   don't block urgent interactions (e.g. composer typing)
  *
- * Pass `null` to skip subscribing (stable no-op). When `executionId`
- * changes, the previous subscription is aborted and a fresh one begins.
+ * Pass `null` as `executionId` to skip subscribing (stable no-op).
+ * When `executionId` changes, the previous subscription is aborted
+ * and a fresh one begins.
  *
  * @example
  * ```tsx
@@ -69,82 +108,118 @@ export interface UseExecutionStreamReturn {
  */
 export function useExecutionStream(
   executionId: string | null,
+  options?: UseExecutionStreamOptions,
 ): UseExecutionStreamReturn {
   const stigmer = useStigmer();
 
-  const [execution, setExecution] = useState<AgentExecution | null>(null);
-  const [isConnecting, setIsConnecting] = useState(false);
-  const [isStreaming, setIsStreaming] = useState(false);
-  const [error, setError] = useState<Error | null>(null);
-  const [connectKey, setConnectKey] = useState(0);
-
-  const abortRef = useRef<AbortController | null>(null);
+  // -- Store setup ----------------------------------------------------------
+  // Use the externally provided store, or create a private one for
+  // standalone usage. The ref ensures the internal store is stable
+  // across re-renders.
+  const internalStoreRef = useRef<ConversationStore | null>(null);
+  if (!options?.store && !internalStoreRef.current) {
+    internalStoreRef.current = new ConversationStore();
+  }
+  const store = options?.store ?? internalStoreRef.current!;
+
+  // -- Controller setup -----------------------------------------------------
+  const controllerRef = useRef<StreamController | null>(null);
+  if (!controllerRef.current) {
+    const sink: StreamControllerSink = {
+      ingestSnapshot(snapshot) {
+        startTransition(() => {
+          store.ingestSnapshot(snapshot);
+        });
+      },
+      setStreamState(state) {
+        startTransition(() => {
+          store.setStreamState(state);
+        });
+      },
+    };
+    controllerRef.current = new StreamController(sink);
+  }
+  const controller = controllerRef.current;
 
+  // -- Reconnect ------------------------------------------------------------
+  const [connectKey, setConnectKey] = useState(0);
   const reconnect = useCallback(() => {
-    setError(null);
     setConnectKey((k) => k + 1);
   }, []);
 
+  // -- Stream rate instrumentation ------------------------------------------
+  const streamRate = useStreamRate();
+  const streamRateRef = useRef(streamRate);
+  streamRateRef.current = streamRate;
+
+  // -- Subscription effect --------------------------------------------------
+  // Note: controller, store, and streamRate are ref-backed stable objects —
+  // they MUST NOT appear in the deps array. Including them would cause
+  // infinite re-renders because useStreamRate returns a new object per render.
   useEffect(() => {
     if (!executionId) {
-      setExecution(null);
-      setIsConnecting(false);
-      setIsStreaming(false);
-      setError(null);
+      controller.reset();
+      store.reset();
       return;
     }
 
-    abortRef.current?.abort();
-    const controller = new AbortController();
-    abortRef.current = controller;
-
-    setExecution(null);
-    setIsConnecting(true);
-    setIsStreaming(false);
-    setError(null);
+    const abortController = new AbortController();
+    controller.start(executionId);
 
     (async () => {
       try {
         for await (const snapshot of stigmer.agentExecution.subscribe(
           executionId,
-          controller.signal,
+          abortController.signal,
         )) {
-          if (controller.signal.aborted) return;
+          if (abortController.signal.aborted) return;
+
+          controller.handleSnapshot(snapshot);
+          streamRateRef.current.tick(
+            snapshot.status?.messages?.length ?? 0,
+          );
 
-          const currentPhase =
+          const phase =
             snapshot.status?.phase ??
             ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED;
-          const isTerminal = isTerminalPhase(currentPhase);
-
-          setExecution(snapshot);
-          setIsConnecting(false);
-          setIsStreaming(!isTerminal);
-
-          if (isTerminal) break;
+          if (isTerminalPhase(phase)) break;
         }
 
-        if (!controller.signal.aborted) {
-          setIsStreaming(false);
+        if (!abortController.signal.aborted) {
+          controller.handleStreamEnd();
+          streamRateRef.current.summary();
         }
       } catch (err) {
-        if (controller.signal.aborted) return;
-
-        setError(toError(err));
-        setIsConnecting(false);
-        setIsStreaming(false);
+        if (abortController.signal.aborted) return;
+        controller.handleError(toError(err));
       }
     })();
 
     return () => {
-      controller.abort();
+      abortController.abort();
+      controller.reset();
+      store.reset();
     };
   }, [executionId, stigmer, connectKey]);
 
+  // -- Read from store via useSyncExternalStore ------------------------------
+  const execution = useSyncExternalStore(store.subscribe, store.getExecution);
+  const streamState = useSyncExternalStore(
+    store.subscribe,
+    store.getStreamState,
+  );
+
+  // -- Derive public return values ------------------------------------------
   const phase = useMemo(
     () =>
       execution?.status?.phase ?? ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED,
     [execution],
   );
 
+  const isStreaming = streamState.stage === "streaming";
+  const isConnecting = streamState.stage === "connecting";
+  const error =
+    streamState.stage === "error" ? streamState.error : null;
+
   return { execution, phase, isStreaming, isConnecting, error, reconnect };
 }

package/src/execution/useSessionVariables.ts

@@ -180,16 +180,21 @@ export function useSessionVariables(): UseSessionVariablesReturn {
     [entries],
   );
 
-  return {
-    entries,
-    addEntry,
-    removeEntry,
-    updateEntry,
-    clear,
-    isEmpty: entries.length === 0,
-    hasValidEntries,
-    toRuntimeEnv,
-    toSaveForFutureEnv,
-    hasSaveForFutureEntries,
-  };
+  const isEmpty = entries.length === 0;
+
+  return useMemo(
+    () => ({
+      entries,
+      addEntry,
+      removeEntry,
+      updateEntry,
+      clear,
+      isEmpty,
+      hasValidEntries,
+      toRuntimeEnv,
+      toSaveForFutureEnv,
+      hasSaveForFutureEntries,
+    }),
+    [entries, addEntry, removeEntry, updateEntry, clear, isEmpty, hasValidEntries, toRuntimeEnv, toSaveForFutureEnv, hasSaveForFutureEntries],
+  );
 }