@stigmer/react 0.3.3 → 0.4.0

package/src/internal/useFetch.ts

@@ -1,6 +1,7 @@
 "use client";
 
 import { type DependencyList, useCallback, useEffect, useRef, useState } from "react";
+import { useFetchCache } from "./FetchCacheProvider";
 import { toError } from "./toError";
 
 /** Options for {@link useFetch}. */
@@ -13,6 +14,21 @@ export interface UseFetchOptions {
    * request piling on slow connections.
    */
   readonly refetchInterval?: number | false;
+
+  /**
+   * Stable string key for cross-mount caching.
+   *
+   * When provided (and a {@link FetchCacheProvider} is mounted above
+   * this component), the hook reads cached data on mount to avoid a
+   * loading skeleton, and writes fresh data to the cache on every
+   * successful fetch.
+   *
+   * Pass `undefined` to opt out of caching for a given call.
+   *
+   * @example `session:${id}`
+   * @example `session-executions:${sessionId}`
+   */
+  readonly cacheKey?: string;
 }
 
 /** Return value of {@link useFetch}. */
@@ -59,14 +75,33 @@ export function useFetch<T>(
   initialData: T,
   options?: UseFetchOptions,
 ): UseFetchReturn<T> {
-  const [data, setData] = useState<T>(initialData);
+  const cache = useFetchCache();
+  const cacheKey = options?.cacheKey;
+
+  // Resolve initial state from cache when available. The initializer
+  // function runs once on mount — exactly the right time to seed state
+  // from a previous mount's result and skip the loading skeleton.
+  const [data, setData] = useState<T>(() => {
+    if (cacheKey && cache) {
+      const cached = cache.get<T>(cacheKey);
+      if (cached !== undefined) return cached;
+    }
+    return initialData;
+  });
   const [error, setError] = useState<Error | null>(null);
   const [fetchKey, setFetchKey] = useState(0);
 
-  const hasDataRef = useRef(false);
+  const hasDataRef = useRef(
+    cacheKey && cache ? cache.has(cacheKey) : false,
+  );
   const isFetchingRef = useRef(false);
   const [isFetching, setIsFetching] = useState(false);
 
+  // Stable ref for cache — avoids adding cache to effect deps while
+  // still letting the effect body access the current instance.
+  const cacheRef = useRef(cache);
+  cacheRef.current = cache;
+
   const refetch = useCallback(() => setFetchKey((k) => k + 1), []);
 
   useEffect(() => {
@@ -79,6 +114,17 @@ export function useFetch<T>(
       return;
     }
 
+    // On dep change (without remount), check cache for the new key so
+    // we can show cached data immediately rather than stale data from
+    // a different identity (e.g. session A's data while session B loads).
+    if (cacheKey && cacheRef.current) {
+      const cached = cacheRef.current.get<T>(cacheKey);
+      if (cached !== undefined) {
+        setData(cached);
+        hasDataRef.current = true;
+      }
+    }
+
     const cancelled = { current: false };
     setIsFetching(true);
     isFetchingRef.current = true;
@@ -91,6 +137,9 @@ export function useFetch<T>(
         hasDataRef.current = true;
         setIsFetching(false);
         isFetchingRef.current = false;
+        if (cacheKey && cacheRef.current) {
+          cacheRef.current.set(cacheKey, result);
+        }
       },
       (err) => {
         if (cancelled.current) return;

package/src/session/__tests__/useNewSessionFlow.test.tsx

@@ -190,6 +190,28 @@ describe("useNewSessionFlow", () => {
       // DEFAULT_MODEL_ID (anthropic) is not in cursor registry
       expect(result.current.modelId).not.toBe(DEFAULT_MODEL_ID);
     });
+
+    it("strips compound keys before persisting to localStorage", () => {
+      localStorage.setItem(STORAGE_KEY_HARNESS, "cursor");
+      const { result } = renderHook(() => useNewSessionFlow(defaultOptions()));
+
+      // Simulate compound key from unified mode ModelSelector
+      act(() => result.current.setModelId("cursor/default"));
+
+      // Should store plain modelId, not compound key
+      expect(localStorage.getItem(STORAGE_KEY_MODEL_CURSOR)).toBe("default");
+    });
+
+    it("restores compound keys from localStorage as plain modelId", () => {
+      localStorage.setItem(STORAGE_KEY_HARNESS, "cursor");
+      // Legacy: compound key was stored before fix
+      localStorage.setItem(STORAGE_KEY_MODEL_CURSOR, "cursor/default");
+
+      const { result } = renderHook(() => useNewSessionFlow(defaultOptions()));
+
+      // Should extract plain modelId and validate against registry
+      expect(result.current.modelId).toBe(DEFAULT_CURSOR_MODEL_ID);
+    });
   });
 
   describe("submit with harness", () => {

package/src/session/__tests__/usePersistedModel.test.tsx

@@ -0,0 +1,117 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import { usePersistedModel } from "../usePersistedModel";
+import { DEFAULT_MODEL_ID, DEFAULT_CURSOR_MODEL_ID } from "../../models/registry";
+
+const STORAGE_KEY_NATIVE = "stigmer:session:model";
+const STORAGE_KEY_CURSOR = "stigmer:session:model:cursor";
+
+describe("usePersistedModel", () => {
+  beforeEach(() => {
+    localStorage.clear();
+  });
+
+  afterEach(() => {
+    localStorage.clear();
+  });
+
+  describe("basic persistence", () => {
+    it("returns undefined when localStorage is empty", () => {
+      const { result } = renderHook(() => usePersistedModel({ harness: "native" }));
+      expect(result.current[0]).toBeUndefined();
+    });
+
+    it("restores a valid model from localStorage", () => {
+      localStorage.setItem(STORAGE_KEY_NATIVE, DEFAULT_MODEL_ID);
+      const { result } = renderHook(() => usePersistedModel({ harness: "native" }));
+      expect(result.current[0]).toBe(DEFAULT_MODEL_ID);
+    });
+
+    it("returns undefined for an invalid model in localStorage", () => {
+      localStorage.setItem(STORAGE_KEY_NATIVE, "nonexistent-model-xyz");
+      const { result } = renderHook(() => usePersistedModel({ harness: "native" }));
+      expect(result.current[0]).toBeUndefined();
+    });
+
+    it("persists model on change", () => {
+      const { result } = renderHook(() => usePersistedModel({ harness: "native" }));
+
+      act(() => result.current[1](DEFAULT_MODEL_ID));
+
+      expect(localStorage.getItem(STORAGE_KEY_NATIVE)).toBe(DEFAULT_MODEL_ID);
+      expect(result.current[0]).toBe(DEFAULT_MODEL_ID);
+    });
+
+    it("uses cursor-specific key for cursor harness", () => {
+      localStorage.setItem(STORAGE_KEY_CURSOR, DEFAULT_CURSOR_MODEL_ID);
+      const { result } = renderHook(() => usePersistedModel({ harness: "cursor" }));
+      expect(result.current[0]).toBe(DEFAULT_CURSOR_MODEL_ID);
+    });
+  });
+
+  describe("compound key handling", () => {
+    it("extracts plain modelId from compound key in localStorage", () => {
+      localStorage.setItem(STORAGE_KEY_CURSOR, "cursor/default");
+      const { result } = renderHook(() => usePersistedModel({ harness: "cursor" }));
+      expect(result.current[0]).toBe(DEFAULT_CURSOR_MODEL_ID);
+    });
+
+    it("extracts plain modelId from native compound key", () => {
+      localStorage.setItem(STORAGE_KEY_NATIVE, `native/${DEFAULT_MODEL_ID}`);
+      const { result } = renderHook(() => usePersistedModel({ harness: "native" }));
+      expect(result.current[0]).toBe(DEFAULT_MODEL_ID);
+    });
+
+    it("handles non-compound values unchanged", () => {
+      localStorage.setItem(STORAGE_KEY_CURSOR, DEFAULT_CURSOR_MODEL_ID);
+      const { result } = renderHook(() => usePersistedModel({ harness: "cursor" }));
+      expect(result.current[0]).toBe(DEFAULT_CURSOR_MODEL_ID);
+    });
+  });
+
+  describe("harness transition (key change re-sync)", () => {
+    it("re-reads from new localStorage key when harness changes", () => {
+      localStorage.setItem(STORAGE_KEY_NATIVE, DEFAULT_MODEL_ID);
+      localStorage.setItem(STORAGE_KEY_CURSOR, DEFAULT_CURSOR_MODEL_ID);
+
+      const { result, rerender } = renderHook(
+        ({ harness }: { harness: "native" | "cursor" }) => usePersistedModel({ harness }),
+        { initialProps: { harness: "native" } },
+      );
+
+      expect(result.current[0]).toBe(DEFAULT_MODEL_ID);
+
+      rerender({ harness: "cursor" });
+
+      expect(result.current[0]).toBe(DEFAULT_CURSOR_MODEL_ID);
+    });
+
+    it("returns undefined after harness change when new key has no stored value", () => {
+      localStorage.setItem(STORAGE_KEY_NATIVE, DEFAULT_MODEL_ID);
+
+      const { result, rerender } = renderHook(
+        ({ harness }: { harness: "native" | "cursor" }) => usePersistedModel({ harness }),
+        { initialProps: { harness: "native" } },
+      );
+
+      expect(result.current[0]).toBe(DEFAULT_MODEL_ID);
+
+      rerender({ harness: "cursor" });
+
+      expect(result.current[0]).toBeUndefined();
+    });
+
+    it("handles compound key in new storage key after harness transition", () => {
+      localStorage.setItem(STORAGE_KEY_CURSOR, "cursor/default");
+
+      const { result, rerender } = renderHook(
+        ({ harness }: { harness: "native" | "cursor" }) => usePersistedModel({ harness }),
+        { initialProps: { harness: "native" } },
+      );
+
+      rerender({ harness: "cursor" });
+
+      expect(result.current[0]).toBe(DEFAULT_CURSOR_MODEL_ID);
+    });
+  });
+});

package/src/session/__tests__/useSession.test.tsx

@@ -0,0 +1,187 @@
+import { describe, it, expect, vi } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { create } from "@bufbuild/protobuf";
+import {
+  SessionSchema,
+  type Session,
+} from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
+import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+import type { Stigmer } from "@stigmer/sdk";
+import { StigmerContext } from "../../context";
+import { FetchCacheContext } from "../../internal/FetchCacheProvider";
+import { FetchCache } from "../../internal/fetch-cache";
+import { useSession } from "../useSession";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeSession(id: string): Session {
+  const session = create(SessionSchema);
+  const metadata = create(ApiResourceMetadataSchema);
+  metadata.id = id;
+  session.metadata = metadata;
+  return session;
+}
+
+function createMockStigmer(sessionGet: ReturnType<typeof vi.fn>): Stigmer {
+  return {
+    session: { get: sessionGet },
+  } as unknown as Stigmer;
+}
+
+async function flush(): Promise<void> {
+  await act(async () => {
+    await Promise.resolve();
+  });
+}
+
+/**
+ * Wrapper that provides both the Stigmer client and a shared FetchCache
+ * instance via context. Sharing the cache instance across renderHook
+ * calls mirrors the production layout where FetchCacheProvider sits
+ * above the key-based remount boundary.
+ */
+function createWrapper(client: Stigmer, cache: FetchCache) {
+  return function Wrapper({ children }: { children: ReactNode }) {
+    return (
+      <FetchCacheContext.Provider value={cache}>
+        <StigmerContext.Provider value={client}>
+          {children}
+        </StigmerContext.Provider>
+      </FetchCacheContext.Provider>
+    );
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("useSession — cache behavior", () => {
+  it("first visit shows loading then resolves data", async () => {
+    const session = makeSession("ses_1");
+    const sessionGet = vi.fn().mockResolvedValue(session);
+    const cache = new FetchCache();
+    const wrapper = createWrapper(createMockStigmer(sessionGet), cache);
+
+    const { result } = renderHook(() => useSession("ses_1"), { wrapper });
+
+    expect(result.current.isLoading).toBe(true);
+    expect(result.current.session).toBeNull();
+
+    await flush();
+
+    expect(result.current.isLoading).toBe(false);
+    expect(result.current.session).toBe(session);
+    expect(sessionGet).toHaveBeenCalledOnce();
+  });
+
+  it("remount serves cached data instantly (no isLoading)", async () => {
+    const session1 = makeSession("ses_1");
+    const sessionGet = vi.fn().mockResolvedValue(session1);
+    const client = createMockStigmer(sessionGet);
+    const cache = new FetchCache();
+    const wrapper = createWrapper(client, cache);
+
+    // First mount — populates the cache.
+    const { result: r1, unmount } = renderHook(
+      () => useSession("ses_1"),
+      { wrapper },
+    );
+    await flush();
+    expect(r1.current.session).toBe(session1);
+    unmount();
+
+    // Second mount (simulates remount after key={activeSessionId} change).
+    const freshSession = makeSession("ses_1");
+    sessionGet.mockResolvedValue(freshSession);
+
+    const { result: r2 } = renderHook(
+      () => useSession("ses_1"),
+      { wrapper },
+    );
+
+    // Cached data is served synchronously — no loading skeleton.
+    expect(r2.current.isLoading).toBe(false);
+    expect(r2.current.session).toBe(session1);
+    expect(r2.current.isRefetching).toBe(true);
+
+    // Background fetch completes with fresh data.
+    await flush();
+    expect(r2.current.session).toBe(freshSession);
+    expect(r2.current.isRefetching).toBe(false);
+  });
+
+  it("different session IDs have independent cache entries", async () => {
+    const sessionA = makeSession("ses_A");
+    const sessionB = makeSession("ses_B");
+    const sessionGet = vi.fn()
+      .mockResolvedValueOnce(sessionA)
+      .mockResolvedValueOnce(sessionB)
+      .mockResolvedValue(sessionA);
+    const cache = new FetchCache();
+    const wrapper = createWrapper(createMockStigmer(sessionGet), cache);
+
+    // Mount session A.
+    const { unmount: unmountA } = renderHook(
+      () => useSession("ses_A"),
+      { wrapper },
+    );
+    await flush();
+    unmountA();
+
+    // Mount session B.
+    const { unmount: unmountB } = renderHook(
+      () => useSession("ses_B"),
+      { wrapper },
+    );
+    await flush();
+    unmountB();
+
+    // Remount session A — should get A's cached data, not B's.
+    const { result } = renderHook(
+      () => useSession("ses_A"),
+      { wrapper },
+    );
+
+    expect(result.current.isLoading).toBe(false);
+    expect(result.current.session?.metadata?.id).toBe("ses_A");
+  });
+
+  it("works without FetchCacheProvider (standard loading flow)", async () => {
+    const session = makeSession("ses_1");
+    const sessionGet = vi.fn().mockResolvedValue(session);
+    const client = createMockStigmer(sessionGet);
+
+    function NoCacheWrapper({ children }: { children: ReactNode }) {
+      return (
+        <StigmerContext.Provider value={client}>
+          {children}
+        </StigmerContext.Provider>
+      );
+    }
+
+    const { result } = renderHook(() => useSession("ses_1"), {
+      wrapper: NoCacheWrapper,
+    });
+
+    expect(result.current.isLoading).toBe(true);
+    await flush();
+    expect(result.current.session).toBe(session);
+  });
+
+  it("null id skips fetching and caching", async () => {
+    const sessionGet = vi.fn();
+    const cache = new FetchCache();
+    const wrapper = createWrapper(createMockStigmer(sessionGet), cache);
+
+    const { result } = renderHook(() => useSession(null), { wrapper });
+
+    expect(result.current.isLoading).toBe(false);
+    expect(result.current.session).toBeNull();
+    expect(sessionGet).not.toHaveBeenCalled();
+    expect(cache.size).toBe(0);
+  });
+});

package/src/session/useNewSessionFlow.ts

@@ -5,6 +5,7 @@ import { getUserMessage, type McpServerUsageInput, type ResourceRef } from "@sti
 import type { AgentResolution } from "../agent";
 import { useDefaultAgent } from "../agent";
 import { useModelRegistry } from "../models";
+import { parseModelKey } from "../models/registry";
 import { DEFAULT_HARNESS, type HarnessOption } from "../models/harness";
 import { useWorkspaceEntries, type UseWorkspaceEntriesReturn } from "../workspace";
 import { useSessionVariables, type UseSessionVariablesReturn } from "../execution/useSessionVariables";
@@ -184,9 +185,9 @@ export function useNewSessionFlow(
   const setHarness = useCallback(
     (h: HarnessOption) => {
       setHarnessRaw(h);
-      // Restore per-harness model preference, or clear if none stored
       const storedModel = localStorage.getItem(modelStorageKey(h));
-      setModelId(storedModel ?? undefined);
+      const plain = storedModel ? (parseModelKey(storedModel)?.modelId ?? storedModel) : undefined;
+      setModelId(plain);
     },
     [],
   );
@@ -194,15 +195,20 @@ export function useNewSessionFlow(
   // Restore persisted model on mount (using current harness key)
   useEffect(() => {
     const stored = localStorage.getItem(modelStorageKey(harness));
-    if (stored && getModel(stored)) {
-      setModelId(stored);
+    if (stored) {
+      const plain = parseModelKey(stored)?.modelId ?? stored;
+      if (getModel(plain)) {
+        setModelId(plain);
+      }
     }
   }, [getModel, harness]);
 
-  // Persist model on change (using current harness key)
+  // Persist model on change (using current harness key).
+  // Strip compound keys (e.g. "cursor/default") to plain modelId before storing.
   useEffect(() => {
     if (modelId) {
-      localStorage.setItem(modelStorageKey(harness), modelId);
+      const plain = parseModelKey(modelId)?.modelId ?? modelId;
+      localStorage.setItem(modelStorageKey(harness), plain);
     }
   }, [modelId, harness]);
 

package/src/session/usePersistedModel.ts

@@ -1,7 +1,8 @@
 "use client";
 
-import { useEffect, useState } from "react";
+import { useEffect, useRef, useState } from "react";
 import { useModelRegistry } from "../models";
+import { parseModelKey } from "../models/registry";
 import type { HarnessOption } from "../models/harness";
 
 /** Options for {@link usePersistedModel}. */
@@ -28,6 +29,16 @@ function storageKey(harness?: HarnessOption): string {
     : "stigmer:session:model";
 }
 
+/**
+ * Extract the plain modelId from a value that might be a compound key
+ * (e.g. `"cursor/default"` → `"default"`). Returns the value unchanged
+ * if it's already a plain ID.
+ */
+function extractPlainModelId(value: string): string {
+  const parsed = parseModelKey(value);
+  return parsed ? parsed.modelId : value;
+}
+
 /**
  * Model selection with localStorage persistence.
  *
@@ -39,6 +50,9 @@ function storageKey(harness?: HarnessOption): string {
  * When `options.harness` is provided, the stored model is read from a
  * harness-specific key and validated against the harness-filtered registry.
  *
+ * Handles legacy compound keys (`"cursor/default"`) gracefully by
+ * extracting the plain modelId portion before validation.
+ *
  * Used by both the session launcher (new session) and session page
  * (follow-up messages) to maintain a consistent model preference.
  */
@@ -48,12 +62,24 @@ export function usePersistedModel(
   const harness = options?.harness;
   const { getModel } = useModelRegistry({ harness });
   const key = storageKey(harness);
+  const prevKeyRef = useRef(key);
 
   const [modelId, setModelId] = useState<string | undefined>(() => {
     if (typeof window === "undefined") return undefined;
-    return localStorage.getItem(key) ?? undefined;
+    const raw = localStorage.getItem(key);
+    return raw ? extractPlainModelId(raw) : undefined;
   });
 
+  // Re-read from localStorage when the storage key changes (harness transition).
+  useEffect(() => {
+    if (prevKeyRef.current === key) return;
+    prevKeyRef.current = key;
+
+    if (typeof window === "undefined") return;
+    const raw = localStorage.getItem(key);
+    setModelId(raw ? extractPlainModelId(raw) : undefined);
+  }, [key]);
+
   useEffect(() => {
     if (modelId) {
       localStorage.setItem(key, modelId);

package/src/session/useSession.ts

@@ -62,6 +62,7 @@ export function useSession(id: string | null): UseSessionReturn {
     id ? () => stigmer.session.get(id) : null,
     [id, stigmer],
     null as Session | null,
+    { cacheKey: id ? `session:${id}` : undefined },
   );
 
   return { session, isLoading, isRefetching, error, refetch };

package/src/session/useSessionConversation.ts

@@ -17,6 +17,7 @@ import type {
 } from "@stigmer/sdk";
 import { isTerminalPhase } from "../execution/execution-phases";
 import { useStigmer } from "../hooks";
+import { useConversationStoreRef } from "../internal/store";
 import { useCreateAgentExecution } from "../execution/useCreateAgentExecution";
 import { useExecutionStream } from "../execution/useExecutionStream";
 import { useSubmitApproval } from "../execution/useSubmitApproval";
@@ -248,7 +249,14 @@ export function useSessionConversation(
 
   const activeExecutionId = pendingExecutionId ?? listActiveId;
 
-  const stream = useExecutionStream(activeExecutionId);
+  // The conversation store is shared between useExecutionStream (which
+  // ingests snapshots with structural sharing + rAF coalescing) and the
+  // rendering tree. This eliminates the duplicate structuralShare that
+  // was previously done in this hook.
+  const conversationStore = useConversationStoreRef();
+  const stream = useExecutionStream(activeExecutionId, {
+    store: conversationStore,
+  });
 
   // Clear pendingExecutionId once the execution appears in the fetched list
   useEffect(() => {
@@ -291,7 +299,8 @@ export function useSessionConversation(
     );
   }, [executions, activeExecutionId]);
 
-  const activeStreamExecution = stream.execution ?? fetchedActiveExecution;
+  const activeStreamExecution =
+    stream.execution ?? fetchedActiveExecution;
 
   const activePhase = useMemo<ExecutionPhase | null>(() => {
     if (!activeExecutionId) return null;

package/src/session/useSessionExecutions.ts

@@ -73,6 +73,7 @@ export function useSessionExecutions(
       : null,
     [sessionId, stigmer],
     [] as AgentExecution[],
+    { cacheKey: sessionId ? `session-executions:${sessionId}` : undefined },
   );
 
   return { executions, isLoading, isRefetching, error, refetch };

package/src/session/useSessionPageFlow.ts

@@ -253,7 +253,7 @@ export function useSessionPageFlow(
 
       sessionVariables.clear();
     },
-    [conv, modelId, workspace, mcpServerUsages, skillRefs, sessionVariables, resolution, agentRef, sessionInstanceId, stigmer],
+    [conv.sendFollowUp, modelId, workspace, mcpServerUsages, skillRefs, sessionVariables.clear, resolution, agentRef, sessionInstanceId, stigmer],
   );
 
   // -------------------------------------------------------------------------