@opengeni/react 2.2.0-canary.0 → 2.5.0-canary.0

package/src/components/tip-follow.ts

@@ -1,19 +1,22 @@
 /* ----------------------------------------------------------------------------
    Tip-follow camera (pure)
 
-   DOM truth is immediate; the camera eases down toward the layout tip.
+   DOM truth is immediate; while pinned, the viewport tracks new layout growth
+   immediately so already-rendered content is never hidden behind the camera.
+   Any debt that existed before the growth still closes through the camera.
    No React, no DOM — the shell reads metrics, calls step, writes scrollTop.
 
-   One law while pinned — second-order camera (no hard first bite):
+   One law for pre-existing debt — second-order camera:
 
      desiredVel = debt / τ
      scrollVel  → exponential approach to desiredVel (accel τ = k·τ)
      scrollTop += scrollVel · dt   (clamp: no overshoot past tip)
 
-   - Debt jumps with layout; velocity cannot — so motion eases in, then as
-     debt falls desiredVel→0 and velocity eases out (soft settle).
+   - Layout growth advances cameraTop by the same amount, preserving rather
+     than increasing existing debt. This keeps the visible stream truthful.
+   - Existing debt eases out as desiredVel→0 (soft settle).
    - τ still adapts (calm / catch-up / line / idle settle).
-   - maxStep is a speed ceiling only, never a one-frame glue.
+   - maxStep is a speed ceiling for catch-up, never a source of stream lag.
    - Shrink is separate: compensate Δh so collapse doesn't fight the ease
    - Snap only for first paint / reduced motion / cold oversized jumps
    -------------------------------------------------------------------------- */
@@ -310,7 +313,7 @@ export function tipFollowMaxStepPx(
     TIP_FOLLOW_CALM_MAX_PX_S +
     (TIP_FOLLOW_BURST_MAX_PX_S - TIP_FOLLOW_CALM_MAX_PX_S) * blend * blend;
   if (hot && frameGrowthPx > 0 && dtMs > 0) {
-    // Allow tracking this frame's growth rate (growthTrack uses a fraction).
+    // Allow pre-existing debt to close without falling behind current growth.
     maxPxS = Math.max(maxPxS, (frameGrowthPx / dtMs) * 1000);
   }
   if (hot && growthVelocityPxPerSec > TIP_FOLLOW_CALM_MAX_PX_S) {
@@ -502,6 +505,14 @@ export function tipFollowStep(
     );
   }
   const target = targetScrollTop(scrollHeight, clientHeight);
+  if (pinned && frameGrowth > 0) {
+    // Preserve the distance that existed before this layout growth instead of
+    // manufacturing new visual debt. The content is already in the DOM; while
+    // pinned, hiding it behind an eased scroll makes frontend streaming appear
+    // slower than the provider and leaves a visible catch-up tail after the
+    // final token. Existing debt still goes through the camera below.
+    cameraTop = Math.min(target, cameraTop + frameGrowth);
+  }
   const debt = target - cameraTop;
   const hot = now < noted.hotUntil;
   const settling = !hot && Math.abs(debt) < TIP_FOLLOW_CATCHUP_DEBT_PX;
@@ -550,7 +561,7 @@ export function tipFollowStep(
   const dtSec = dt / 1000;
   const tauSec = Math.max(tau / 1000, 1e-3);
   // P-gain: held desiredVel would close debt in ~τ. Velocity cannot jump —
-  // it eases toward desiredVel, so a new line accelerates in then settles out.
+  // pre-existing debt accelerates toward desiredVel and then settles out.
   const desiredVel = debt / tauSec;
   const accelTauSec = Math.max(tauSec * TIP_FOLLOW_ACCEL_TAU_FRAC, 0.02);
   const velAlpha = 1 - Math.exp(-dtSec / accelTauSec);

package/src/hooks/use-composer.ts

@@ -1984,10 +1984,12 @@ export function useComposer(
         },
         canRetry: true,
       };
-      replaceOptimisticSends((current) => [...current, operation]);
-      queueMicrotask(processOptimisticSends);
-      setError(null);
-      onSubmitted?.(sendText, input);
+      // The local submission acknowledgement owns the composer before any
+      // host callback or queued processor can observe it. Hosts commonly use
+      // onSubmitted to remove attachment/repository state, and those updates
+      // may synchronously re-render the controlled composer. Clear the refs
+      // first so that handoff cannot re-project the submitted text as the next
+      // draft. The immutable operation above still owns the exact retry input.
       if (explicit === undefined) {
         valueRef.current = "";
         annotationsRef.current = [];
@@ -1998,6 +2000,10 @@ export function useComposer(
         setAnnotationReviewTargetId(null);
         setRestoredResources([]);
       }
+      replaceOptimisticSends((current) => [...current, operation]);
+      queueMicrotask(processOptimisticSends);
+      setError(null);
+      onSubmitted?.(sendText, input);
       return true;
     },
     [
@@ -2529,9 +2535,17 @@ export function useComposer(
     setError(null);
     setDraftConflict(null);
   }, [targetKey]);
+  // `valueRef` is the synchronous composer authority. React state exists to
+  // schedule renders, but a concurrent autosave settlement can render the
+  // previous state lane after a newer input event has already updated the ref.
+  // Projecting that stale state into a controlled textarea rewrites the old
+  // draft for one commit, which moves the caret and can briefly resurrect a
+  // submitted message. Never let an incidental render outrank the latest
+  // local lifecycle decision.
+  const visibleValue = identityMatches ? valueRef.current : "";
 
   return {
-    value: identityMatches ? value : "",
+    value: visibleValue,
     setValue: updateValue,
     annotations: identityMatches ? annotations : [],
     addAnnotation,
@@ -2561,7 +2575,7 @@ export function useComposer(
       sendBlockedRef.current?.() !== true &&
       annotationsComplete &&
       (hasPendingOperation ||
-        value.trim().length > 0 ||
+        visibleValue.trim().length > 0 ||
         hasReadyResources ||
         annotations.length > 0),
     pause,

package/src/hooks/use-session-events.ts

@@ -1,6 +1,7 @@
 import type { SessionEvent, SessionStatus, StreamConnectionState } from "@opengeni/sdk";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useEmbeddedSession, type EmbeddedSessionClientOverride } from "../session-context";
+import { createOlderHistoryLoadReceipt, type OlderHistoryLoadReceipt } from "../older-history";
 import { buildTimeline, groupTimeline, sessionStatusFromEvents } from "../timeline/projection";
 import type { TimelineItem } from "../timeline/types";
 import type { EmbeddedSessionClientLike } from "../client";
@@ -38,7 +39,7 @@ export type UseSessionEventsResult = {
   /** True while an older window is being fetched. */
   loadingOlder: boolean;
   /** Prepend an older density-bounded window; resolves true when more remain. */
-  loadOlder: () => Promise<boolean>;
+  loadOlder: () => OlderHistoryLoadReceipt;
   /**
    * Durable events exist after the current window (history view jumped away
    * from the live tip, or a forward page is incomplete).
@@ -427,81 +428,88 @@ export function useSessionEvents(
     loadingOldestRef.current ||
     loadingLatestRef.current;
 
-  const loadOlder = useCallback(async (): Promise<boolean> => {
-    if (!sessionId || navigationBusy() || !hasOlderRef.current) {
-      return false;
-    }
-    const before = oldestSequenceRef.current;
-    if (before === null) {
-      hasOlderRef.current = false;
-      setHasOlder(false);
-      return false;
-    }
-    const generation = generationRef.current;
-    loadingOlderRef.current = true;
-    setLoadingOlder(true);
-    try {
-      const window = await loadEventWindow(client, workspaceId, sessionId, {
-        before,
-        pageSize: OLDER_PAGE_SIZE,
-        targetGroups: OLDER_GROUP_TARGET,
-        maxFetches: OLDER_FETCH_CAP,
-      });
-      if (generationRef.current !== generation) {
-        return false;
-      }
-      if (window.events.length === 0) {
-        oldestSequenceRef.current = null;
-        hasOlderRef.current = false;
-        setHasOlder(false);
-        return false;
-      }
-      const current = eventWindowRef.current;
-      assertPrependOrder(current.events, window.events);
-      // Freeze the live iterator before replacing its in-memory window. Rows
-      // pending in the aborted iterator were never cursor-committed and will
-      // be replayed from the retained high-water mark below.
-      streamAbortRef.current?.abort();
-      observeSessionStatus(window.events, sessionStatusRef, setSessionStatusProjection);
-      const next = boundBrowserSessionEventWindow([...window.events, ...current.events], {
-        direction: "oldest",
-      });
-      const retained = {
-        ...next,
-        truncated: current.truncated || next.truncated,
-      };
-      const retainedOldest = retained.events[0]?.sequence ?? null;
-      if (retainedOldest === null || retainedOldest >= before) {
-        throw new Error("@opengeni/react: loadOlder made no durable sequence progress");
-      }
-      const retainedNewest = retained.events.at(-1)?.sequence ?? null;
-      eventWindowRef.current = retained;
-      setEventWindow(retained);
-      oldestSequenceRef.current = retainedOldest;
-      newestSequenceRef.current = retainedNewest;
-      streamResumeSequenceRef.current = maxResumeSequence(retained.events);
-      // Oldest-directed eviction can discard newer in-memory rows. That fact
-      // keeps windowTruncated true, but it does not imply older durable rows
-      // exist; only the backward DB page can answer hasOlder truthfully.
-      const olderStillAvailable = window.hasOlder;
-      hasOlderRef.current = olderStillAvailable;
-      setHasOlder(olderStillAvailable);
-      if (viewModeRef.current === "history") {
-        const highWater = lastSequenceRef.current;
-        const newer = retainedNewest !== null && (retainedNewest < highWater || retained.truncated);
-        hasNewerRef.current = newer;
-        setHasNewer(newer);
-      } else {
-        // Live mode keeps the historical contract: reconnect and replay the
-        // evicted tip through SSE so the window stays one contiguous suffix.
-        setStreamEpoch((epoch) => epoch + 1);
-      }
-      return olderStillAvailable;
-    } finally {
-      loadingOlderRef.current = false;
-      setLoadingOlder(false);
-    }
-  }, [client, workspaceId, sessionId]);
+  const loadOlder = useCallback(
+    (): OlderHistoryLoadReceipt =>
+      createOlderHistoryLoadReceipt(async (markCommitted) => {
+        if (!sessionId || navigationBusy() || !hasOlderRef.current) {
+          return false;
+        }
+        const before = oldestSequenceRef.current;
+        if (before === null) {
+          oldestSequenceRef.current = null;
+          hasOlderRef.current = false;
+          setHasOlder(false);
+          return false;
+        }
+        const generation = generationRef.current;
+        loadingOlderRef.current = true;
+        setLoadingOlder(true);
+        try {
+          const window = await loadEventWindow(client, workspaceId, sessionId, {
+            before,
+            pageSize: OLDER_PAGE_SIZE,
+            targetGroups: OLDER_GROUP_TARGET,
+            maxFetches: OLDER_FETCH_CAP,
+          });
+          if (generationRef.current !== generation) {
+            return false;
+          }
+          if (window.events.length === 0) {
+            oldestSequenceRef.current = null;
+            hasOlderRef.current = false;
+            setHasOlder(false);
+            return false;
+          }
+          const current = eventWindowRef.current;
+          assertPrependOrder(current.events, window.events);
+          // Freeze the live iterator before replacing its in-memory window. Rows
+          // pending in the aborted iterator were never cursor-committed and will
+          // be replayed from the retained high-water mark below.
+          streamAbortRef.current?.abort();
+          observeSessionStatus(window.events, sessionStatusRef, setSessionStatusProjection);
+          const next = boundBrowserSessionEventWindow([...window.events, ...current.events], {
+            direction: "oldest",
+          });
+          const retained = {
+            ...next,
+            truncated: current.truncated || next.truncated,
+          };
+          const retainedOldest = retained.events[0]?.sequence ?? null;
+          if (retainedOldest === null || retainedOldest >= before) {
+            throw new Error("@opengeni/react: loadOlder made no durable sequence progress");
+          }
+          const retainedNewest = retained.events.at(-1)?.sequence ?? null;
+          eventWindowRef.current = retained;
+          markCommitted();
+          setEventWindow(retained);
+          oldestSequenceRef.current = retainedOldest;
+          newestSequenceRef.current = retainedNewest;
+          streamResumeSequenceRef.current = maxResumeSequence(retained.events);
+          // Oldest-directed eviction can discard newer in-memory rows. That fact
+          // keeps windowTruncated true, but it does not imply older durable rows
+          // exist; only the backward DB page can answer hasOlder truthfully.
+          const olderStillAvailable = window.hasOlder;
+          hasOlderRef.current = olderStillAvailable;
+          setHasOlder(olderStillAvailable);
+          if (viewModeRef.current === "history") {
+            const highWater = lastSequenceRef.current;
+            const newer =
+              retainedNewest !== null && (retainedNewest < highWater || retained.truncated);
+            hasNewerRef.current = newer;
+            setHasNewer(newer);
+          } else {
+            // Live mode keeps the historical contract: reconnect and replay the
+            // evicted tip through SSE so the window stays one contiguous suffix.
+            setStreamEpoch((epoch) => epoch + 1);
+          }
+          return olderStillAvailable;
+        } finally {
+          loadingOlderRef.current = false;
+          setLoadingOlder(false);
+        }
+      }),
+    [client, workspaceId, sessionId],
+  );
 
   const loadOldest = useCallback(async (): Promise<boolean> => {
     if (!sessionId || navigationBusy() || !hasOlderRef.current) {

package/src/hooks/use-session-lineage.ts

@@ -11,12 +11,16 @@ export type UseSessionLineageOptions = EmbeddedSessionLineageClientOverride & {
   /** Refresh interval (ms). Off by default. */
   pollIntervalMs?: number | undefined;
   enabled?: boolean | undefined;
+  /** Optional shared causal clock invoked when each network read starts. */
+  beginRead?: (() => number) | undefined;
 };
 
 export type UseSessionLineageResult = {
   lineage: SessionLineageResponse | null;
   loading: boolean;
   error: Error | null;
+  /** Causal generation captured when the accepted lineage read started. */
+  readGeneration: number;
   refresh: () => Promise<void>;
 };
 
@@ -63,13 +67,26 @@ export function useSessionLineage(
   const { client, workspaceId, workspaceControlEvent, registerSessionReconciler } =
     useEmbeddedSessionLineage(options);
   const enabled = (options.enabled ?? true) && Boolean(sessionId);
-  const load = useCallback(
-    async () =>
-      sessionId
-        ? await client.getSessionLineage(workspaceId, sessionId)
-        : { ancestors: [], children: [], truncated: false },
-    [client, workspaceId, sessionId],
-  );
+  const nextReadGeneration = useRef(0);
+  const beginRead = options.beginRead;
+  const load = useCallback(async () => {
+    if (!sessionId) {
+      return {
+        lineage: { ancestors: [], children: [], truncated: false },
+        readGeneration: 0,
+      };
+    }
+    let readGeneration = 0;
+    const lineage = await client.getSessionLineage(workspaceId, sessionId, {
+      onRequestStart: (sharedReadGeneration) => {
+        readGeneration = sharedReadGeneration ?? beginRead?.() ?? ++nextReadGeneration.current;
+      },
+    });
+    return {
+      lineage,
+      readGeneration,
+    };
+  }, [beginRead, client, workspaceId, sessionId]);
   const state = usePolledValue(load, { pollIntervalMs: options.pollIntervalMs, enabled });
   const refresh = state.refresh;
   useEffect(() => {
@@ -123,9 +140,10 @@ export function useSessionLineage(
     { events: options.events, enabled: enabled && options.events !== undefined },
   );
   return {
-    lineage: state.data,
+    lineage: state.data?.lineage ?? null,
     loading: state.loading,
     error: state.error,
+    readGeneration: state.data?.readGeneration ?? 0,
     refresh,
   };
 }

package/src/hooks/use-session.ts

@@ -1,5 +1,5 @@
 import type { Session, SessionEvent } from "@opengeni/sdk";
-import { useCallback, useEffect, useMemo, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useEmbeddedSessionRead, type EmbeddedSessionReadClientOverride } from "../session-context";
 import {
   useMutationRunner,
@@ -12,12 +12,18 @@ export type UseSessionOptions = EmbeddedSessionReadClientOverride &
   SessionEventFeedOptions & {
     /** Re-fetch on an interval (ms). Off by default — pair with `useSessionEvents` for live status. */
     pollIntervalMs?: number | undefined;
+    /** Optional shared causal clock invoked when each network read starts. */
+    beginRead?: (() => number) | undefined;
   };
 
 export type UseSessionResult = {
   session: Session | null;
   loading: boolean;
   error: Error | null;
+  /** Monotonic revision of accepted authoritative detail reads. */
+  readRevision: number;
+  /** Causal generation captured when the accepted network read started. */
+  readGeneration: number;
   refresh: () => Promise<void>;
   /** Manually rename the session (PATCH, source='user'). Returns the updated session, or null on failure. */
   updateTitle: (title: string) => Promise<Session | null>;
@@ -41,16 +47,29 @@ export function useSession(
     useEmbeddedSessionRead(options);
   const enabled = (options.enabled ?? true) && Boolean(sessionId);
   const [override, setOverride] = useState<Session | null>(null);
+  const nextReadRevision = useRef(0);
+  const nextReadGeneration = useRef(0);
+  const beginRead = options.beginRead;
   const { run, mutating, mutationError, clearMutationError } = useMutationRunner();
   const load = useCallback(async () => {
     if (!sessionId) {
       return null;
     }
-    const fetched = await client.getSession(workspaceId, sessionId);
+    let readGeneration = 0;
+    const fetched = await client.getSession(workspaceId, sessionId, {
+      fresh: true,
+      onRequestStart: () => {
+        readGeneration = beginRead?.() ?? ++nextReadGeneration.current;
+      },
+    });
     // A fresh server read supersedes any optimistic/event-driven override.
     setOverride(null);
-    return fetched;
-  }, [client, workspaceId, sessionId]);
+    return {
+      session: fetched,
+      revision: ++nextReadRevision.current,
+      readGeneration,
+    };
+  }, [beginRead, client, workspaceId, sessionId]);
   const { data, loading, error, refresh } = usePolledValue(load, {
     pollIntervalMs: options.pollIntervalMs,
     enabled,
@@ -63,7 +82,9 @@ export function useSession(
     return registerSessionReconciler(sessionId, "session", refresh);
   }, [enabled, refresh, registerSessionReconciler, sessionId]);
 
-  const base = data ?? null;
+  const base = data?.session ?? null;
+  const readRevision = data?.revision ?? 0;
+  const readGeneration = data?.readGeneration ?? 0;
   // The override only ever carries title/titleSource patches; it is reset on
   // every fresh load so it can never go stale against the server snapshot.
   const session = useMemo(
@@ -78,6 +99,13 @@ export function useSession(
   // the UI reflects the new title without polling or a full re-fetch.
   const onTitleEvent = useCallback(
     (event: SessionEvent) => {
+      // The fetched session row is the authoritative title projection through
+      // lastSequence. Shared feeds may replay that historical tail after the
+      // fetch; applying it would undo a row-only migration quarantine. Only an
+      // event committed after this snapshot may live-patch the title.
+      if (!base || event.sequence <= base.lastSequence) {
+        return;
+      }
       const payload = (event.payload ?? {}) as { title?: unknown; source?: unknown };
       const title = payload.title;
       if (typeof title !== "string") {
@@ -87,9 +115,6 @@ export function useSession(
         payload.source === "user" || payload.source === "agent" ? payload.source : null;
       setOverride((current): Session | null => {
         const next = current ?? base;
-        if (!next) {
-          return current;
-        }
         return { ...next, title, titleSource: source };
       });
     },
@@ -118,6 +143,8 @@ export function useSession(
     session,
     loading,
     error,
+    readRevision,
+    readGeneration,
     refresh,
     updateTitle,
     updating: mutating,

package/src/hooks/use-workspace-sessions.ts

@@ -14,6 +14,8 @@ export type UseWorkspaceSessionsOptions = ClientOverride & {
   /** Refresh interval (ms) for fleet/manager views. Off by default. */
   pollIntervalMs?: number | undefined;
   enabled?: boolean | undefined;
+  /** Optional shared causal clock invoked when each network read starts. */
+  beginRead?: (() => number) | undefined;
 };
 
 export type UseWorkspaceSessionsResult = {
@@ -29,6 +31,10 @@ export type UseWorkspaceSessionsResult = {
   nextCursor: string | null;
   loading: boolean;
   error: Error | null;
+  /** Monotonic revision of accepted authoritative list-page reads. */
+  readRevision: number;
+  /** Causal generation captured when the accepted network read started. */
+  readGeneration: number;
   refresh: () => Promise<void>;
 };
 
@@ -44,6 +50,9 @@ export function useWorkspaceSessions(
   const pinsOnly = options.pinsOnly;
   const archivedOnly = options.archivedOnly;
   const enabled = options.enabled ?? true;
+  const nextReadRevision = useRef(0);
+  const nextReadGeneration = useRef(0);
+  const beginRead = options.beginRead;
   const queryKey = [
     workspaceId,
     limit ?? "",
@@ -58,20 +67,34 @@ export function useWorkspaceSessions(
   useEffect(() => {
     previousQueryKey.current = queryKey;
   }, [queryKey]);
-  const load = useCallback(
-    async () => ({
+  const load = useCallback(async () => {
+    const readGeneration = beginRead?.() ?? ++nextReadGeneration.current;
+    const page = await client.listSessionPage(workspaceId, {
+      ...(limit !== undefined ? { limit } : {}),
+      ...(parentSessionId !== undefined ? { parentSessionId } : {}),
+      ...(cursor !== undefined ? { cursor } : {}),
+      ...(search !== undefined ? { search } : {}),
+      ...(pinsOnly ? { pinsOnly: true } : {}),
+      ...(archivedOnly ? { archivedOnly: true } : {}),
+    });
+    return {
       queryKey,
-      page: await client.listSessionPage(workspaceId, {
-        ...(limit !== undefined ? { limit } : {}),
-        ...(parentSessionId !== undefined ? { parentSessionId } : {}),
-        ...(cursor !== undefined ? { cursor } : {}),
-        ...(search !== undefined ? { search } : {}),
-        ...(pinsOnly ? { pinsOnly: true } : {}),
-        ...(archivedOnly ? { archivedOnly: true } : {}),
-      }),
-    }),
-    [client, workspaceId, limit, parentSessionId, cursor, search, pinsOnly, archivedOnly, queryKey],
-  );
+      page,
+      revision: ++nextReadRevision.current,
+      readGeneration,
+    };
+  }, [
+    beginRead,
+    client,
+    workspaceId,
+    limit,
+    parentSessionId,
+    cursor,
+    search,
+    pinsOnly,
+    archivedOnly,
+    queryKey,
+  ]);
   const state = usePolledValue(load, {
     pollIntervalMs: options.pollIntervalMs,
     enabled,
@@ -100,6 +123,8 @@ export function useWorkspaceSessions(
         queryKeyTransition ||
         (state.data !== null && state.data.queryKey !== queryKey)),
     error: state.error,
+    readRevision: page ? (state.data?.revision ?? 0) : 0,
+    readGeneration: page ? (state.data?.readGeneration ?? 0) : 0,
     refresh: state.refresh,
   };
 }

package/src/index.ts

@@ -41,12 +41,14 @@ export {
   boundBrowserSessionEventWindow,
   useSessionEvents,
 } from "./hooks/use-session-events";
+export { createOlderHistoryLoadReceipt } from "./older-history";
 export type {
   BrowserSessionEventWindow,
   SessionEventsConnectionState,
   UseSessionEventsOptions,
   UseSessionEventsResult,
 } from "./hooks/use-session-events";
+export type { OlderHistoryLoader, OlderHistoryLoadReceipt } from "./older-history";
 export {
   useComposer,
   composeSendInput,

package/src/older-history.ts

@@ -0,0 +1,69 @@
+/**
+ * Await-compatible older-history result with a causal commit receipt.
+ *
+ * `committed` flips synchronously before the accepted older window is exposed
+ * to React. Returning this exact object preserves the receipt directly;
+ * synchronous wrappers that discard it remain supported through receipt
+ * capture, while replacing it asynchronously with a plain promise does not.
+ */
+export type OlderHistoryLoadReceipt = Promise<boolean> & {
+  readonly committed: boolean;
+};
+
+/**
+ * Source-compatible public callback accepted by MessageTimeline.
+ *
+ * The callback historically returned `void`, which permits consumers to
+ * return any synchronous value or promise. Receipt-aware loaders opt into the
+ * stronger runtime contract by returning (or synchronously creating through a
+ * wrapper) an {@link OlderHistoryLoadReceipt}.
+ */
+export type OlderHistoryLoader = () => unknown;
+
+type MutableOlderHistoryLoadReceipt = Promise<boolean> & {
+  committed: boolean;
+};
+
+type OlderHistoryReceiptCapture = (receipt: OlderHistoryLoadReceipt) => void;
+
+let activeReceiptCapture: OlderHistoryReceiptCapture | undefined;
+
+/** Bind a receipt before a synchronous forwarding stack can publish state. */
+export function invokeOlderHistoryLoaderWithReceiptCapture(
+  load: OlderHistoryLoader,
+  capture: OlderHistoryReceiptCapture,
+): unknown {
+  const previousCapture = activeReceiptCapture;
+  activeReceiptCapture = capture;
+  try {
+    return load();
+  } finally {
+    activeReceiptCapture = previousCapture;
+  }
+}
+
+/**
+ * Build an await-compatible older-history receipt for custom timeline hosts.
+ * Call `markCommitted` immediately before publishing an accepted older window.
+ */
+export function createOlderHistoryLoadReceipt(
+  load: (markCommitted: () => void) => boolean | Promise<boolean>,
+): OlderHistoryLoadReceipt {
+  let resolveResult!: (value: boolean | PromiseLike<boolean>) => void;
+  let rejectResult!: (reason?: unknown) => void;
+  const result = new Promise<boolean>((resolve, reject) => {
+    resolveResult = resolve;
+    rejectResult = reject;
+  }) as MutableOlderHistoryLoadReceipt;
+  result.committed = false;
+  activeReceiptCapture?.(result);
+  try {
+    const loaded = load(() => {
+      result.committed = true;
+    });
+    Promise.resolve(loaded).then(resolveResult, rejectResult);
+  } catch (error) {
+    rejectResult(error);
+  }
+  return result;
+}

package/src/session-ui.ts

@@ -11,6 +11,8 @@ export { HumanInputSurface } from "./components/human-input-surface";
 export type { HumanInputSurfaceProps } from "./components/human-input-surface";
 export { MessageTimeline, TimelineRow } from "./components/message-timeline";
 export type { MessageTimelineProps } from "./components/message-timeline";
+export { createOlderHistoryLoadReceipt } from "./older-history";
+export type { OlderHistoryLoader, OlderHistoryLoadReceipt } from "./older-history";
 export { UserMessageBody, userMessageLikelyNeedsDisclosure } from "./components/user-message-body";
 export type { UserMessageBodyProps } from "./components/user-message-body";
 export { BUILT_IN_TURN_SUMMARY_FACET_IDS } from "./timeline/turn-summary";

package/src/session.ts

@@ -31,6 +31,8 @@ export type {
   UseSessionEventsOptions,
   UseSessionEventsResult,
 } from "./hooks/use-session-events";
+export { createOlderHistoryLoadReceipt } from "./older-history";
+export type { OlderHistoryLoader, OlderHistoryLoadReceipt } from "./older-history";
 export {
   useComposer,
   composeSendInput,