@opengeni/react 3.5.1-canary.0 → 3.7.0-canary.0

package/dist/session-ui.js

@@ -11,14 +11,14 @@ import {
   sessionChromeGoalPillLabel,
   sessionChromeGoalPillState,
   userMessageLikelyNeedsDisclosure
-} from "./chunk-WY3MELVJ.js";
+} from "./chunk-DOK4KZF2.js";
 import "./chunk-W3OUAH6M.js";
 import "./chunk-JVYQRRC4.js";
 import "./chunk-7EAFGICR.js";
 import "./chunk-VZTQ73XT.js";
 import {
   createOlderHistoryLoadReceipt
-} from "./chunk-TJFMMDQU.js";
+} from "./chunk-FJBOU2TH.js";
 import "./chunk-VTOREEXF.js";
 import "./chunk-22KP6LR5.js";
 export {

package/dist/session.js

@@ -17,7 +17,7 @@ import {
   useSessionLineage,
   useSessionMcpApprovalPolicy,
   useTurnQueue
-} from "./chunk-IB27C53Y.js";
+} from "./chunk-C6WDLHBA.js";
 import {
   FILE_ONLY_MESSAGE_TEXT,
   composeSendInput,
@@ -37,7 +37,7 @@ import {
   projectPendingHumanInputRequests,
   sessionStatusFromEvents,
   toolDisplayName
-} from "./chunk-TJFMMDQU.js";
+} from "./chunk-FJBOU2TH.js";
 import "./chunk-VTOREEXF.js";
 export {
   FILE_ONLY_MESSAGE_TEXT,

package/dist/timeline/registry.d.ts

@@ -22,6 +22,8 @@ export type ToolRegistryEntry = {
     match: "name";
     name: string;
     render: ToolRenderer;
+    /** Disable untrusted `<server>__${name}` leaf matching for identity-sensitive renderers. */
+    matchPrefixedLeaf?: boolean | undefined;
 };
 export type ToolRegistry = {
     /** Resolve the renderer for a call (never null — falls back to generic). */

package/dist/timeline/types.d.ts

@@ -228,7 +228,7 @@ export type FleetDecisionItem = {
     policyVersion: "adaptive-shadow-v1";
     actualOutcome: "selected" | "waiting" | "none";
     actualCandidateKey: string | null;
-    actualReason: "lease_reused" | "pin" | "rotation" | "active" | "all_capped" | "none";
+    actualReason: "lease_reused" | "pin" | "rotation" | "active" | "all_capped" | "allocator_disabled" | "none";
     shadowOutcome: "selected" | "paced" | "none";
     shadowCandidateKey: string | null;
     shadowReason: "fenced_in_flight" | "fenced_candidate_missing" | "admission_paced" | "no_eligible_candidate" | "overlay_isolated_empty" | "best_score" | "affinity_best" | "hysteresis_hold";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/react",
-  "version": "3.5.1-canary.0",
+  "version": "3.7.0-canary.0",
   "description": "React hooks and styled components for OpenGeni: live session streaming, chat composer, message timeline, session status, and fleet views — token-themed (CSS variables), dark-first, built on Tailwind v4 + Radix + Motion.",
   "license": "Apache-2.0",
   "repository": {
@@ -120,7 +120,7 @@
     "@dnd-kit/utilities": "3.2.2",
     "@fontsource-variable/noto-sans-arabic": "5.2.10",
     "@fontsource-variable/noto-sans-jp": "5.2.10",
-    "@opengeni/sdk": "^3.5.1-canary.0",
+    "@opengeni/sdk": "^3.7.0-canary.0",
     "clsx": "^2.1.1",
     "dequal": "2.0.3",
     "lucide-react": "^1.8.0",

package/src/artifacts.ts

@@ -18,6 +18,8 @@ export {
   PresentationProjectionEditor,
   PublishedHtmlArtifactFrame,
   PUBLISHED_HTML_ARTIFACT_IFRAME_SANDBOX,
+  openGeniSiteBridgePortFromBootstrap,
+  publishedHtmlArtifactDocument,
   SpreadsheetArtifactSurface,
   SpreadsheetGrid,
   SpreadsheetProjectionGrid,
@@ -62,6 +64,7 @@ export {
   type PresentationProjectionConnector,
   type PresentationProjectionEditorProps,
   type PublishedHtmlArtifactFrameProps,
+  type PublishedHtmlArtifactToolBridge,
   type PresentationProjectionElementMetadata,
   type PresentationProjectionElement,
   type PresentationProjectionFill,

package/src/client.ts

@@ -246,7 +246,8 @@ export type EmbeddedSessionLineageClientLike = EmbeddedSessionEventClientLike &
   Pick<OpenGeniClient, "getSessionLineage">;
 
 /** Exact client surface required by {@link useFileAttachments}. */
-export type EmbeddedFileAttachmentClientLike = Pick<OpenGeniClient, "uploadFile">;
+export type EmbeddedFileAttachmentClientLike = Pick<OpenGeniClient, "uploadFile"> &
+  Partial<Pick<OpenGeniClient, "createFileDownloadUrl">>;
 
 /** Exact client surface required by structured human-input hooks. */
 export type EmbeddedHumanInputSessionClientLike = EmbeddedSessionEventClientLike &

package/src/components/artifacts/index.ts

@@ -6,7 +6,10 @@ export {
 export {
   PUBLISHED_HTML_ARTIFACT_IFRAME_SANDBOX,
   PublishedHtmlArtifactFrame,
+  openGeniSiteBridgePortFromBootstrap,
+  publishedHtmlArtifactDocument,
   type PublishedHtmlArtifactFrameProps,
+  type PublishedHtmlArtifactToolBridge,
 } from "./published-html-artifact-frame";
 export {
   SpreadsheetArtifactSurface,

package/src/components/artifacts/published-html-artifact-frame.tsx

@@ -1,4 +1,21 @@
-import type { CSSProperties } from "react";
+import {
+  OPENGENI_SITE_BRIDGE_BOOTSTRAP_GLOBAL,
+  OPENGENI_SITE_BRIDGE_READY,
+  OPENGENI_SITE_BRIDGE_RESPONSE,
+  OPENGENI_SITE_BRIDGE_VERSION,
+  isOpenGeniSiteBridgeCancelMessage,
+  isOpenGeniSiteBridgeConnectMessage,
+  isOpenGeniSiteBridgeRequestMessage,
+  sanitizeOpenGeniSiteToolCallRequest,
+  type OpenGeniSiteBridgeResponseMessage,
+  type OpenGeniSiteToolCatalog,
+} from "@opengeni/sdk/site";
+import type {
+  ToolGatewayCallRequest,
+  ToolGatewayCallResponse,
+  ToolGatewayDeclarationsResponse,
+} from "@opengeni/sdk";
+import { useEffect, useRef, type CSSProperties } from "react";
 
 export const PUBLISHED_HTML_ARTIFACT_IFRAME_SANDBOX = [
   "allow-downloads",
@@ -17,22 +34,285 @@ export type PublishedHtmlArtifactFrameProps = {
   title: string;
   className?: string;
   style?: CSSProperties;
+  toolBridge?: PublishedHtmlArtifactToolBridge;
 };
 
+export type PublishedHtmlArtifactToolBridge = {
+  catalog: (options: { signal: AbortSignal }) => Promise<OpenGeniSiteToolCatalog>;
+  call: (
+    request: ToolGatewayCallRequest,
+    options: { signal: AbortSignal },
+  ) => Promise<ToolGatewayCallResponse>;
+  declarations?: (options: { signal: AbortSignal }) => Promise<ToolGatewayDeclarationsResponse>;
+};
+
+const SITE_BRIDGE_BOOTSTRAP_SCRIPT = `<script>(()=>{const key=${JSON.stringify(
+  OPENGENI_SITE_BRIDGE_BOOTSTRAP_GLOBAL,
+)};const parentWindow=window.parent;if(parentWindow===window)return;window.addEventListener("message",event=>{const data=event.data;if(event.source!==parentWindow||!data||data.type!==${JSON.stringify(
+  OPENGENI_SITE_BRIDGE_READY,
+)}||data.version!==${OPENGENI_SITE_BRIDGE_VERSION}||event.ports.length!==1)return;const port=event.ports[0];const previous=window[key]?.port;if(previous&&previous!==port)previous.close();Object.defineProperty(window,key,{configurable:true,value:{port}});port.start();});})();</script>`;
+
+export function publishedHtmlArtifactDocument(html: string, toolBridgeEnabled: boolean): string {
+  if (!toolBridgeEnabled) return html;
+  const doctypeEnd = leadingDoctypeEnd(html);
+  if (doctypeEnd >= 0) {
+    return `${html.slice(0, doctypeEnd + 1)}${SITE_BRIDGE_BOOTSTRAP_SCRIPT}${html.slice(doctypeEnd + 1)}`;
+  }
+  return `${SITE_BRIDGE_BOOTSTRAP_SCRIPT}${html}`;
+}
+
+function leadingDoctypeEnd(html: string): number {
+  const lower = html.toLowerCase();
+  let cursor = html.charCodeAt(0) === 0xfeff ? 1 : 0;
+  while (cursor < html.length) {
+    while (/\s/.test(html[cursor] ?? "")) cursor += 1;
+    if (!html.startsWith("<!--", cursor)) break;
+    const commentEnd = html.indexOf("-->", cursor + 4);
+    if (commentEnd < 0) return -1;
+    cursor = commentEnd + 3;
+  }
+  if (!lower.startsWith("<!doctype", cursor)) return -1;
+  return html.indexOf(">", cursor + 9);
+}
+
 /**
  * Render exact published HTML in an opaque-origin iframe. Artifact scripts,
- * external resources, forms, popups, and downloads work without granting
- * parent-origin authority, shared cookies/storage, or top-level navigation.
+ * external resources, forms, popups, downloads, and the host-filtered tool
+ * bridge work without granting parent-origin authority, shared cookies/storage,
+ * or top-level navigation.
  */
 export function PublishedHtmlArtifactFrame(props: PublishedHtmlArtifactFrameProps) {
+  const frameRef = useRef<HTMLIFrameElement | null>(null);
+  const bridgeRef = useRef(props.toolBridge);
+  const onFrameLoadRef = useRef<() => void>(() => undefined);
+  const frameLoadPendingRef = useRef(false);
+  const toolBridgeEnabled = props.toolBridge !== undefined;
+  useEffect(() => {
+    bridgeRef.current = props.toolBridge;
+  }, [props.toolBridge]);
+  useEffect(() => {
+    if (!toolBridgeEnabled || typeof window === "undefined") return;
+    const requests = new SiteBridgeRequestRegistry();
+    const attachToolPort = (data: unknown, ports: readonly MessagePort[]) => {
+      const port = openGeniSiteBridgePortFromBootstrap(data, ports);
+      if (!port) return;
+      requests.replacePort(port);
+      port.addEventListener("message", (portEvent: MessageEvent<unknown>) => {
+        const message = portEvent.data;
+        if (isOpenGeniSiteBridgeCancelMessage(message)) {
+          requests.cancel(port, message.requestId);
+          return;
+        }
+        if (!isOpenGeniSiteBridgeRequestMessage(message)) return;
+        const controller = requests.start(port, message.requestId);
+        if (!controller) {
+          port.postMessage({
+            type: OPENGENI_SITE_BRIDGE_RESPONSE,
+            version: OPENGENI_SITE_BRIDGE_VERSION,
+            requestId: message.requestId,
+            ok: false,
+            error: {
+              code: "duplicate_request_id",
+              message: "A Site tool request with this id is already running",
+              retryable: false,
+            },
+          } satisfies OpenGeniSiteBridgeResponseMessage);
+          return;
+        }
+        void handleSiteBridgeRequest(bridgeRef.current, message, controller.signal)
+          .then((value) => {
+            if (!controller.signal.aborted) {
+              port.postMessage({
+                type: OPENGENI_SITE_BRIDGE_RESPONSE,
+                version: OPENGENI_SITE_BRIDGE_VERSION,
+                requestId: message.requestId,
+                ok: true,
+                value,
+              } satisfies OpenGeniSiteBridgeResponseMessage);
+            }
+          })
+          .catch((error) => {
+            if (!controller.signal.aborted) {
+              port.postMessage({
+                type: OPENGENI_SITE_BRIDGE_RESPONSE,
+                version: OPENGENI_SITE_BRIDGE_VERSION,
+                requestId: message.requestId,
+                ok: false,
+                error: siteBridgeError(error),
+              } satisfies OpenGeniSiteBridgeResponseMessage);
+            }
+          })
+          .finally(() => requests.complete(port, message.requestId, controller));
+      });
+      port.addEventListener("messageerror", () => requests.closePort(port));
+      port.start();
+      port.postMessage({
+        type: OPENGENI_SITE_BRIDGE_READY,
+        version: OPENGENI_SITE_BRIDGE_VERSION,
+      });
+    };
+    const documentLease = new SiteBridgeDocumentLease(attachToolPort, () => requests.closeAll());
+    const onFrameLoad = () => {
+      frameLoadPendingRef.current = false;
+      const frameWindow = frameRef.current?.contentWindow ?? null;
+      if (!frameWindow) return;
+      documentLease.load(frameWindow);
+    };
+    onFrameLoadRef.current = onFrameLoad;
+    if (frameLoadPendingRef.current) {
+      frameLoadPendingRef.current = false;
+      onFrameLoad();
+    }
+    return () => {
+      onFrameLoadRef.current = () => undefined;
+      documentLease.close();
+    };
+  }, [props.html, toolBridgeEnabled]);
   return (
     <iframe
+      ref={frameRef}
       title={props.title}
       sandbox={PUBLISHED_HTML_ARTIFACT_IFRAME_SANDBOX}
       referrerPolicy="no-referrer"
-      srcDoc={props.html}
+      srcDoc={publishedHtmlArtifactDocument(props.html, toolBridgeEnabled)}
+      onLoad={() => {
+        frameLoadPendingRef.current = true;
+        onFrameLoadRef.current();
+      }}
       className={props.className}
       style={props.style}
     />
   );
 }
+
+export class SiteBridgeRequestRegistry {
+  private readonly controllersByPort = new Map<MessagePort, Map<string, AbortController>>();
+
+  replacePort(port: MessagePort): void {
+    this.closeAll();
+    this.controllersByPort.set(port, new Map());
+  }
+
+  start(port: MessagePort, requestId: string): AbortController | null {
+    const controllers = this.controllersByPort.get(port);
+    if (!controllers || controllers.has(requestId)) return null;
+    const controller = new AbortController();
+    controllers.set(requestId, controller);
+    return controller;
+  }
+
+  cancel(port: MessagePort, requestId: string): void {
+    const controllers = this.controllersByPort.get(port);
+    const controller = controllers?.get(requestId);
+    if (!controller) return;
+    controller.abort(new Error("Site tool request cancelled"));
+    controllers!.delete(requestId);
+  }
+
+  complete(port: MessagePort, requestId: string, controller: AbortController): void {
+    const controllers = this.controllersByPort.get(port);
+    if (controllers?.get(requestId) === controller) controllers.delete(requestId);
+  }
+
+  closePort(port: MessagePort): void {
+    const controllers = this.controllersByPort.get(port);
+    if (!controllers) return;
+    for (const controller of controllers.values()) {
+      controller.abort(new Error("Site tool bridge port closed"));
+    }
+    controllers.clear();
+    this.controllersByPort.delete(port);
+    port.close();
+  }
+
+  closeAll(): void {
+    for (const port of [...this.controllersByPort.keys()]) this.closePort(port);
+  }
+}
+
+export class SiteBridgeDocumentLease {
+  private loaded = false;
+  private bootstrapPort: MessagePort | null = null;
+
+  constructor(
+    private readonly attachToolPort: (data: unknown, ports: readonly MessagePort[]) => void,
+    private readonly closeActivePorts: () => void,
+    private readonly createMessageChannel: () => MessageChannel = () => new MessageChannel(),
+  ) {}
+
+  load(frameWindow: Pick<Window, "postMessage">): boolean {
+    if (this.loaded) {
+      this.close();
+      return false;
+    }
+    this.loaded = true;
+    const channel = this.createMessageChannel();
+    this.bootstrapPort = channel.port1;
+    channel.port1.addEventListener("message", (event: MessageEvent<unknown>) => {
+      this.attachToolPort(event.data, event.ports);
+    });
+    channel.port1.start();
+    frameWindow.postMessage(
+      {
+        type: OPENGENI_SITE_BRIDGE_READY,
+        version: OPENGENI_SITE_BRIDGE_VERSION,
+      },
+      "*",
+      [channel.port2],
+    );
+    return true;
+  }
+
+  close(): void {
+    this.bootstrapPort?.close();
+    this.bootstrapPort = null;
+    this.closeActivePorts();
+  }
+}
+
+export function openGeniSiteBridgePortFromBootstrap(
+  data: unknown,
+  ports: readonly MessagePort[],
+): MessagePort | null {
+  if (!isOpenGeniSiteBridgeConnectMessage(data)) return null;
+  return ports.length === 1 ? ports[0]! : null;
+}
+
+async function handleSiteBridgeRequest(
+  bridge: PublishedHtmlArtifactToolBridge | undefined,
+  message: Parameters<typeof isOpenGeniSiteBridgeRequestMessage>[0] & {
+    method: "catalog" | "call" | "declarations";
+    requestId: string;
+    payload?: ToolGatewayCallRequest;
+  },
+  signal: AbortSignal,
+): Promise<OpenGeniSiteToolCatalog | ToolGatewayCallResponse | ToolGatewayDeclarationsResponse> {
+  if (!bridge) throw new Error("Site tool bridge is unavailable");
+  if (message.method === "catalog") return await bridge.catalog({ signal });
+  if (message.method === "declarations") {
+    if (!bridge.declarations) throw new Error("Site tool declarations are unavailable");
+    return await bridge.declarations({ signal });
+  }
+  return await bridge.call(sanitizeOpenGeniSiteToolCallRequest(message.payload!), { signal });
+}
+
+export function siteBridgeError(error: unknown): {
+  code: string;
+  message: string;
+  retryable: boolean;
+  outcomeUnknown: boolean;
+} {
+  const candidate = error as {
+    code?: unknown;
+    message?: unknown;
+    retryable?: unknown;
+    outcomeUnknown?: unknown;
+  };
+  return {
+    code: typeof candidate?.code === "string" ? candidate.code : "site_tool_call_failed",
+    message:
+      typeof candidate?.message === "string" ? candidate.message : "Site tool request failed",
+    retryable: candidate?.retryable === true,
+    outcomeUnknown: candidate?.outcomeUnknown === true,
+  };
+}

package/src/components/composer.tsx

@@ -137,6 +137,7 @@ export type ChatComposerMessages = {
   uploading: string;
   uploadFailed: string;
   previewAttachment: (name: string) => string;
+  previewUnavailable?: string | undefined;
   attachmentPreviewLabel: string;
   downloadAttachment: (name: string) => string;
   closeAttachmentPreview: string;
@@ -204,6 +205,7 @@ export const defaultChatComposerMessages: ChatComposerMessages = {
   uploading: "Uploading",
   uploadFailed: "Upload failed",
   previewAttachment: (name) => `Preview ${name}`,
+  previewUnavailable: "Preview unavailable",
   attachmentPreviewLabel: "Attachment preview",
   downloadAttachment: (name) => `Download ${name}`,
   closeAttachmentPreview: "Close",
@@ -947,6 +949,7 @@ export function Attachments() {
       onRemove={controller.attachments.remove}
       onRetry={controller.attachments.retry}
       onRetainPreview={controller.attachments.retainPreview}
+      onLoadPreview={controller.attachments.loadPreview}
     />
   );
 }
@@ -1638,21 +1641,83 @@ function AttachmentChips({
   onRemove,
   onRetry,
   onRetainPreview,
+  onLoadPreview,
 }: {
   attachments: UseFileAttachmentsResult["attachments"];
   messages: ChatComposerMessages;
   onRemove: (id: string) => void;
   onRetry?: ((id: string) => void) | undefined;
   onRetainPreview: UseFileAttachmentsResult["retainPreview"];
+  onLoadPreview: UseFileAttachmentsResult["loadPreview"];
 }) {
   const lightbox = useLightboxOptional();
+  const previewRequest = useRef<AbortController | null>(null);
+  const [previewLoadingId, setPreviewLoadingId] = useState<string | null>(null);
+  const [previewErrorId, setPreviewErrorId] = useState<string | null>(null);
+
+  useEffect(() => () => previewRequest.current?.abort(), [onLoadPreview]);
+
+  async function openPreview(
+    attachment: UseFileAttachmentsResult["attachments"][number],
+    source: HTMLButtonElement,
+    canLoadPreview: boolean,
+  ) {
+    previewRequest.current?.abort();
+    const attachmentId = attachment.id;
+    const releaseSource = onRetainPreview(attachmentId);
+    let src = attachment.previewUrl;
+    if (!releaseSource && canLoadPreview) {
+      const controller = new AbortController();
+      previewRequest.current = controller;
+      setPreviewLoadingId(attachmentId);
+      setPreviewErrorId(null);
+      try {
+        src = await onLoadPreview!(attachmentId, controller.signal);
+        if (controller.signal.aborted) return;
+        if (!src) {
+          setPreviewErrorId(attachmentId);
+          return;
+        }
+      } catch {
+        if (!controller.signal.aborted) setPreviewErrorId(attachmentId);
+        return;
+      } finally {
+        if (previewRequest.current === controller) {
+          setPreviewLoadingId(null);
+        }
+      }
+    }
+    lightbox!.open(
+      src!,
+      attachment.name,
+      source,
+      messages.attachmentPreviewLabel,
+      attachment.name,
+      {
+        download: messages.downloadAttachment(attachment.name),
+        close: messages.closeAttachmentPreview,
+      },
+      releaseSource,
+    );
+  }
+
   return (
     <div className="flex flex-wrap gap-2 px-3 py-2">
       {attachments.map((attachment) => {
         const failed = attachment.status === "failed";
         const secureContextRequired = attachment.errorCode === "secure_context_required";
-        const statusText =
-          attachment.status === "uploading"
+        const previewFailed = previewErrorId === attachment.id;
+        const previewLoading = previewLoadingId === attachment.id;
+        const canLoadPreview = Boolean(
+          lightbox &&
+          onLoadPreview &&
+          attachment.status === "ready" &&
+          attachment.file &&
+          attachment.contentType.startsWith("image/"),
+        );
+        const statusText = previewFailed
+          ? (messages.previewUnavailable ?? "Preview unavailable")
+          : attachment.status === "uploading"
             ? messages.uploading
             : failed
               ? attachment.error || messages.uploadFailed
@@ -1672,32 +1737,31 @@ function AttachmentChips({
                 : "max-w-[240px] border-og-border bg-og-surface-2",
             )}
           >
-            {attachment.previewUrl && lightbox ? (
+            {lightbox && (attachment.previewUrl || canLoadPreview) ? (
               <button
                 type="button"
-                className="size-8 shrink-0 overflow-hidden rounded outline-hidden focus-visible:ring-2 focus-visible:ring-og-accent"
+                className={cn(
+                  "size-8 shrink-0 overflow-hidden rounded outline-hidden focus-visible:ring-2 focus-visible:ring-og-accent",
+                  !attachment.previewUrl && "flex items-center justify-center disabled:cursor-wait",
+                )}
                 aria-label={messages.previewAttachment(attachment.name)}
-                onClick={(event) => {
-                  const releasePreview = onRetainPreview(attachment.id);
-                  lightbox.open(
-                    attachment.previewUrl!,
-                    attachment.name,
-                    event.currentTarget,
-                    messages.attachmentPreviewLabel,
-                    attachment.name,
-                    {
-                      download: messages.downloadAttachment(attachment.name),
-                      close: messages.closeAttachmentPreview,
-                    },
-                    releasePreview,
-                  );
-                }}
+                aria-busy={previewLoading || undefined}
+                disabled={previewLoading}
+                onClick={(event) =>
+                  void openPreview(attachment, event.currentTarget, canLoadPreview)
+                }
               >
-                <img
-                  src={attachment.previewUrl}
-                  alt=""
-                  className="h-full w-full object-cover transition-opacity hover:opacity-80"
-                />
+                {attachment.previewUrl ? (
+                  <img
+                    src={attachment.previewUrl}
+                    alt=""
+                    className="h-full w-full object-cover transition-opacity hover:opacity-80"
+                  />
+                ) : previewLoading ? (
+                  <LoaderCircleIcon className="size-4 animate-og-spin text-og-fg-muted" />
+                ) : (
+                  <ImageIcon className="size-4 text-og-fg-muted" />
+                )}
               </button>
             ) : attachment.previewUrl ? (
               <img
@@ -1716,7 +1780,7 @@ function AttachmentChips({
                 <div className="break-words text-og-xs leading-4 text-og-status-failed">
                   {statusText}
                 </div>
-              ) : failed ? (
+              ) : failed || previewFailed ? (
                 <ComposerTip tip={statusText}>
                   <div className="truncate text-og-xs text-og-status-failed">{statusText}</div>
                 </ComposerTip>

package/src/components/message-timeline.tsx

@@ -1183,17 +1183,23 @@ export function MessageTimeline({
         applyPinned(false);
       }
     } else if (prepended) {
+      const olderAttemptState = olderLoadAttemptRef.current?.[1];
+      const underfillOwned =
+        !!olderLoadAttemptRef.current &&
+        olderAttemptState !== 1 &&
+        olderAttemptState !== 2 &&
+        olderAttemptState !== 3;
       if (
         autoFollow &&
         pinnedRef.current &&
         !hasNewer &&
         !pendingReaderLeaveRef.current &&
-        (wasAtLiveTailBeforeCommit || olderLoadAttemptRef.current)
+        (wasAtLiveTailBeforeCommit || underfillOwned)
       ) {
-        // A pending short-window load owns the prepend even when live growth
-        // has left its still-pinned camera with raw geometry debt. Unrelated
-        // prepends retain the prior-tip fallback so a stale pin after an
-        // extension/programmatic history jump still restores its row anchor.
+        // Still following the live tip: underfill, or a prefetch the reader
+        // started and then returned from. Park at the new tip. A stale pin
+        // while they are actually up in a short window (gap is not inside
+        // PIN_THRESHOLD of maxScroll, so wasAtLiveTail is false) restores.
         clearPendingReaderLeave();
         snapToBottom(node);
       } else {
@@ -1598,6 +1604,19 @@ export function MessageTimeline({
       return;
     }
 
+    if (programmatic && !pinnedRef.current) {
+      // Restore/camera writes while reading history are not a return to the tip.
+      // Still expire a pending Jump-to-latest latch: the in-window jump itself
+      // is a programmatic snap, and a later reader scroll-away can arrive
+      // before that echo is consumed. Skipping this left the latch armed and
+      // snapped the reader when hasNewer later flipped false.
+      syncScrollBaseline(node);
+      if (wantPinRef.current && !isNearBottom(node)) {
+        wantPinRef.current = false;
+      }
+      return;
+    }
+
     if (autoFollow && pinnedRef.current && !hasNewer) {
       // Fold / composer / SessionChrome: viewport shrink raises maxScroll without
       // growing content. Must hit tipFollow before we adopt the new clientHeight
@@ -1659,10 +1678,15 @@ export function MessageTimeline({
     syncScrollBaseline(node);
     const nearBottom = isNearBottom(node);
 
-    // Re-pin only when the reader moved toward/at the tip — not when a fold
-    // clamp dragged scrollTop down onto nearBottom.
+    // Re-pin only when the reader moved toward/at the tip without a content
+    // insertion. Prepend restore and overflow-anchor raise scrollTop by
+    // roughly the same amount as maxScroll; treating that as a scroll-down
+    // re-pinned a compact-tail history reader (their preserved gap falls
+    // inside PIN_THRESHOLD once the window is tall) and snapped them back.
+    const inserted = Math.max(0, nextMaxScroll - previousMaxScroll);
+    const towardTip = nextTop - previousTop - inserted;
     const nextPinned =
-      !hasNewer && nearBottom && nextTop >= previousTop - TIP_FOLLOW_READER_UP_EPS_PX;
+      !hasNewer && nearBottom && towardTip >= -TIP_FOLLOW_READER_UP_EPS_PX && inserted <= 1;
     if (!nextPinned) {
       stopFollow();
     }