basalt-ui 1.12.0 → 1.13.0

package/dist/agent-chat/thread-message.d.ts

@@ -1,5 +1,7 @@
 import type { JSX } from 'react';
 import type { AgentPartRenderers, ChatMessage, ForeignPart, PartRenderer, PartRenderers, StreamStatus, TranscriptPart } from '../agent/index.js';
+import type { MessageAffordances } from './message-affordances.js';
+import type { VirtualizeOptions, VirtualizeProps } from './virtualize.js';
 /**
  * Mantine overrides for `PartList`'s default headless renderers — the house style for rendering
  * an `AgentPart` inside a chat surface.
@@ -19,6 +21,165 @@ export declare const threadPartRenderers: Partial<AgentPartRenderers>;
 export declare const messageBlockRenderCounter: {
     count: number;
 };
+/** Caps `applyInitialScroll`'s clobber-recovery retries (see `./virtualize`'s fourth composition
+ * rule for the full mechanism this guards). A small fixed budget, not a time/frame-based deadline:
+ * every observed case of virtual-core's `_willUpdate` clobbering this effect's jump resolves within
+ * one extra commit, so this exists purely as a backstop against a pathological DOM that never
+ * reports settled — not as the expected path. Once exhausted, the effect gives up and marks the
+ * jump permanently done wherever the last attempt landed, rather than fighting the DOM (or a user
+ * who has since scrolled away) forever. Exported (like `messageBlockRenderCounter`) purely so its
+ * test can assert the exact bound without duplicating the number; not part of the public surface. */
+export declare const MAX_INITIAL_SCROLL_ATTEMPTS = 5;
+type TranscriptRow = {
+    readonly key: string;
+    readonly node: JSX.Element;
+};
+type VirtualizedTranscriptProps = {
+    readonly rows: readonly TranscriptRow[];
+    readonly height: number | string;
+    readonly overscan: number;
+    readonly estimateSize: number;
+    readonly initialScroll: NonNullable<VirtualizeOptions['initialScroll']>;
+};
+/**
+ * The degrade target: every row rendered unwindowed inside a fixed-height scroll container.
+ * This is what a `virtualize: true` transcript falls back to when `@tanstack/react-virtual` fails
+ * to resolve (peer absent) — same visual shape (a scrollable `height`-bound pane), just without
+ * windowing.
+ *
+ * NOT used as the `Suspense` fallback (see `VirtualizeSuspenseFallback` below) — mounting every
+ * real `MessageBlock` subtree for the one tick the lazy import takes to settle would make that
+ * settle a genuine unmount/remount of every rendered row, re-firing each row's effects once and
+ * risking hitting a message mid-stream during the resolve window.
+ */
+declare function NonVirtualizedRows({ rows, height }: VirtualizedTranscriptProps): JSX.Element;
+/** Test-only escape hatch (mirrors `messageBlockRenderCounter` above) — proves the peer-absent
+ * degrade target itself renders every row without windowing and without throwing, without having
+ * to fight `React.lazy`'s permanent once-per-module-instance resolution cache to simulate the
+ * peer's absence at the `import()` layer (see thread-message.test.tsx's virtualization describe
+ * block for why that approach was rejected). Not exported from `agent-chat/index.ts`. */
+export declare const nonVirtualizedRowsFallback: typeof NonVirtualizedRows;
+/**
+ * Minimal structural slice of `Virtualizer` (virtual-core 3.17.1) that
+ * {@link resolveGuardedMeasurement} needs — `indexFromElement`/`itemSizeCache`/`options` are all
+ * public instance members, but typing against the real (generic, peer-only) `Virtualizer` class
+ * would force this test-only-exported helper to import the peer's runtime types at module scope,
+ * the exact static-import-forces-the-peer problem the surrounding `lazy(() => import(...))` exists
+ * to avoid. A structural type sidesteps that without loosening to `any`. Generic over the item
+ * element type (rather than fixed at `Element`) so it stays exactly assignable FROM a real
+ * `Virtualizer<TScrollElement, TItemElement>` at the call site below — `indexFromElement` is
+ * declared with arrow-property (not method) syntax upstream, so it is checked contravariantly, and
+ * a fixed `Element` parameter there does not structurally match a real instance's narrower
+ * `TItemElement` parameter.
+ */
+type MeasurementCacheHost<TItemElement extends Element> = {
+    readonly indexFromElement: (node: TItemElement) => number;
+    readonly itemSizeCache: Map<unknown, number>;
+    readonly options: {
+        readonly getItemKey: (index: number) => unknown;
+        readonly estimateSize: (index: number) => number;
+    };
+};
+/**
+ * Resolves the size a `measureElement` implementation should report, given what the underlying
+ * (default or custom) measurement already produced: that value unchanged when it is a genuine
+ * measurement, or the row's own last-known size when it is `0` — never a real reading for a mounted
+ * row, so a `0` only ever means the ResizeObserver measured through a `display: none` (or otherwise
+ * unlaid-out) ancestor, e.g. a virtualized transcript sitting inside a collapsed `ThreadFeedRow`.
+ * Falling through to it unguarded is what corrupted `itemSizeCache`/`measurementsCache`: virtual-
+ * core's default `resizeItem` writes whatever `measureElement` returns with no floor, so every
+ * mounted row remeasures at 0px the instant an ancestor hides, `getTotalSize()` collapses within
+ * the same tick, and the collapse is never undone — a later real remeasurement only OVERWRITES
+ * entries the ResizeObserver happens to re-fire for, it does not restore ones that silently kept
+ * their poisoned 0 (see `virtualize.ts`'s composition-rule doc for the full mechanism and the
+ * measured numbers).
+ *
+ * Takes the already-computed `size` plus the {@link MeasurementCacheHost} slice, rather than
+ * wrapping the `measureElement` function itself, so this stays a plain, non-generic-over-a-
+ * generic-function call at its one call site below (`instance` there is `Virtualizer<TScrollElement,
+ * TItemElement>` for THAT call's concrete type arguments, not the peer's own generic
+ * `measureElement` export — wrapping the latter directly hits TS's higher-rank inference limits on
+ * a doubly-generic HOF). That shape is also what makes this unit-testable with a fake host object
+ * and no ResizeObserver/layout engine at all (happy-dom has neither). Not exported from
+ * `agent-chat/index.ts`: a test-only escape hatch, matching
+ * `messageBlockRenderCounter`/`nonVirtualizedRowsFallback` above.
+ */
+export declare function resolveGuardedMeasurement<TItemElement extends Element>(host: MeasurementCacheHost<TItemElement>, element: TItemElement, size: number): number;
+/**
+ * Decides what `VirtualizedRowsInner`'s one-shot initial-scroll effect should do this render,
+ * given the inputs the effect closes over. Pure and peer/DOM-free — pulled out of the lazy-loaded
+ * closure for the same reason `resolveGuardedMeasurement` is: it stays unit-testable without a
+ * real `Virtualizer` instance or `@tanstack/react-virtual` itself.
+ *
+ * `'start'` and an empty transcript resolve to `'skip-done'` — there is nothing to scroll to, and
+ * DONE is permanent (see `virtualize.ts`'s fourth composition rule: the real scroll must fire at
+ * most once, ever, so a later append never yanks a user who has scrolled up). A non-positive
+ * `containerHeight` — the transcript's own scroll node measuring `0`, e.g. mounted behind a
+ * `display: none` ancestor per `virtualize.ts`'s third composition rule — resolves to
+ * `'skip-retry'`: NOT done, so the caller's effect (which re-runs after EVERY commit until the jump
+ * lands — see {@link applyInitialScroll}) gets another chance the next time this subtree renders,
+ * instead of permanently stranding the transcript at the top the moment it becomes visible. Only a
+ * genuinely measured, non-empty, `'end'`-targeted mount resolves to `'scroll'`.
+ */
+export declare function resolveInitialScrollAction(initialScroll: NonNullable<VirtualizeOptions['initialScroll']>, rowCount: number, containerHeight: number): 'scroll' | 'skip-done' | 'skip-retry';
+/** The mutable half of the one-shot initial-scroll contract. `hasApplied` is whether it has
+ * PERMANENTLY finished — either there was nothing to do (`'start'`/empty transcript), or
+ * `scrollToEnd` fired and was subsequently CONFIRMED (via a real DOM read — see
+ * {@link applyInitialScroll}'s doc for why virtual-core's own tracked offset can't be trusted for
+ * this) to have survived whatever else committed since. `attempts` counts how many times
+ * `scrollToEnd` has been (re-)fired this mount; 0 means never attempted, and also gates whether a
+ * call re-derives {@link resolveInitialScrollAction} at all. One instance lives for the lifetime of
+ * a `VirtualizedRowsInner` mount, held in a `useRef` so it survives re-renders without itself
+ * triggering one. */
+export type InitialScrollState = {
+    hasApplied: boolean;
+    attempts: number;
+};
+/**
+ * The stateful half of "fires once, on first mount, and never again" (`virtualize.ts`'s fourth
+ * composition rule): wraps {@link resolveInitialScrollAction}'s per-call decision with the
+ * ACROSS-CALLS memory that decision alone can't carry. Exported (like `resolveGuardedMeasurement`)
+ * so `VirtualizedRowsInner`'s effect below calls this SAME function rather than a hand-mirrored
+ * copy for tests — a fake `scrollToEnd` is the only DOM/peer-free way to prove the guard, since a
+ * real `Virtualizer`'s own `followOnAppend` also calls the real DOM `scrollTo` on a later append,
+ * making that specific call indistinguishable from this one at the DOM boundary (see this
+ * function's test suite for the measurement that ruled that boundary out).
+ *
+ * Firing `scrollToEnd()` once is NOT the same as landing there: virtual-core 3.17.1's own
+ * `_willUpdate` (verified against the installed dist) writes to the SAME scroll container from
+ * `this.scrollOffset`, which updates only from the ASYNCHRONOUS native `scroll` event — never from
+ * the synchronous call that requested a scroll. A commit that runs `_willUpdate` before this
+ * effect gets a turn (element-attach) or that re-derives an anchor while `scrollOffset` still holds
+ * the pre-jump value writes that STALE offset straight back to `scrollTop`, undoing the jump within
+ * about one extra commit of it landing (see `./virtualize`'s fourth composition rule for the full
+ * trace this was diagnosed from). So `resolveInitialScrollAction`'s `'scroll'` outcome does not, by
+ * itself, set `hasApplied`: `isAtEnd` — a real `scrollTop`/`scrollHeight`/`clientHeight` read, the
+ * one piece of ground truth that is NEVER stale, unlike virtual-core's own tracked offset — is
+ * consulted on the NEXT call (i.e. the next commit, exactly the cadence this dependency-free effect
+ * already runs on) to confirm the jump survived. If it didn't, `scrollToEnd` fires again; if it did,
+ * `hasApplied` is set and the effect is inert for the rest of the mount. `MAX_INITIAL_SCROLL_ATTEMPTS`
+ * bounds this so a DOM that pathologically never reports settled — or a user who scrolls away mid-
+ * measurement — can never be fought forever; once exhausted, `hasApplied` is set regardless, wherever
+ * the last attempt left the container.
+ *
+ * `state.hasApplied` is the ONLY thing that can permanently stop this from calling `scrollToEnd`
+ * again: `'start'` and an empty transcript set it immediately (nothing to verify), and `'skip-retry'`
+ * deliberately leaves it `false` so a transcript that mounted behind a hidden ancestor gets another
+ * attempt on the caller's next commit, rather than being silently abandoned the moment it becomes
+ * visible. That retry — and the clobber-recovery above — is why the caller's effect carries NO
+ * dependency array: the commit that matters (a collapsed `ThreadFeedRow` flipping its body back to
+ * `display: block`, or virtual-core's own follow-up commit after this effect's own jump) changes
+ * neither the row count nor the virtualizer identity, so a dependency-keyed effect would never
+ * re-run for it.
+ *
+ * `getContainerHeight` is a THUNK, not a number, for the same reason: reading `offsetHeight` forces
+ * a synchronous layout, and it is read at most ONCE per mount — only on the very first call
+ * (`attempts === 0`) — never again while verifying or retrying, so a landed transcript still pays
+ * nothing for the effect it keeps re-running (a streaming transcript commits on every chunk).
+ * `isAtEnd` is cheaper (a plain property read, no forced reflow beyond what the browser already
+ * tracks) and is exactly what the verification/retry loop above consults instead.
+ */
+export declare function applyInitialScroll(state: InitialScrollState, initialScroll: NonNullable<VirtualizeOptions['initialScroll']>, rowCount: number, getContainerHeight: () => number, scrollToEnd: () => void, isAtEnd: () => boolean): void;
 type ThreadTranscriptBase = {
     /** Settled messages for the thread, oldest first. */
     readonly messages: readonly ChatMessage<TranscriptPart>[];
@@ -31,18 +192,38 @@ type ThreadTranscriptBase = {
     /** Called for a part whose type is neither an AgentPart variant nor a registered key. Defaults
      * to a visible `UnknownPartChip` outside production, `null` in production — never throws. */
     readonly fallbackRenderer?: PartRenderer<ForeignPart>;
+    /** Per-message hover-row affordances (timestamp/copy/regenerate/custom actions). Unset fields
+     * fall back to `DEFAULT_AFFORDANCES`. Never shown on the live/streaming message — see
+     * `MessageBlockProps.affordances`. */
+    readonly affordances?: MessageAffordances;
+    /** Suppresses the role label and surface chrome on a message whose predecessor shares its role
+     * and landed within 5 minutes — the Slack rhythm.
+     * @default true */
+    readonly groupConsecutive?: boolean;
 };
-export type ThreadTranscriptProps = ThreadTranscriptBase;
+export type ThreadTranscriptProps = ThreadTranscriptBase & VirtualizeProps;
 /**
  * Renders a thread's settled messages, each role-labelled ("You" / "Assistant"). Each part
  * resolves in order: a registered `renderers[part.type]` first, then basalt's own `PartList` for
  * the built-in six, then `fallbackRenderer`. When `liveParts` is non-empty, an extra in-progress
  * assistant block is appended at the tail.
  *
+ * Set `virtualize` (with a required `height`) to window a long thread over
+ * `@tanstack/react-virtual` (an optional peer) instead of rendering every message. The virtualized
+ * transcript owns its own fixed-height scroll container and must NOT be nested inside
+ * `BasaltStickToBottom` — see `./virtualize`'s module doc. With the peer absent, `virtualize` still
+ * renders (unwindowed, inside the same fixed-height pane) rather than throwing. A virtualized
+ * transcript scrolls itself to the newest message once, on mount (`initialScroll: 'start'` opts
+ * out) — see `./virtualize`'s fourth composition rule.
+ *
  * @example
  * import { ThreadTranscript } from 'basalt-ui'
  * <ThreadTranscript messages={thread.messages} liveParts={liveParts} liveStatus={runStatus} />
+ *
+ * @example
+ * // Windowed, for a long thread:
+ * <ThreadTranscript messages={thread.messages} virtualize height={480} />
  */
-export declare function ThreadTranscript({ messages, liveParts, liveStatus, renderers: renderersProp, fallbackRenderer, }: ThreadTranscriptProps): JSX.Element;
+export declare function ThreadTranscript(props: ThreadTranscriptProps): JSX.Element;
 export {};
 //# sourceMappingURL=thread-message.d.ts.map

package/dist/agent-chat/thread-message.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"thread-message.d.ts","sourceRoot":"","sources":["../../src/agent-chat/thread-message.tsx"],"names":[],"mappings":"AAiCA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,OAAO,CAAA;AAChC,OAAO,KAAK,EAEV,kBAAkB,EAClB,WAAW,EAEX,WAAW,EACX,YAAY,EACZ,aAAa,EAGb,YAAY,EAGZ,cAAc,EACf,MAAM,UAAU,CAAA;AAsGjB;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,EAAE,OAAO,CAAC,kBAAkB,CAM3D,CAAA;AAqID;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB;;CAAe,CAAA;AAmFrD,KAAK,oBAAoB,GAAG;IAC1B,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,EAAE,SAAS,WAAW,CAAC,cAAc,CAAC,EAAE,CAAA;IACzD,4FAA4F;IAC5F,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,cAAc,EAAE,CAAA;IAC9C,kFAAkF;IAClF,QAAQ,CAAC,UAAU,CAAC,EAAE,YAAY,CAAA;IAClC,kFAAkF;IAClF,QAAQ,CAAC,SAAS,CAAC,EAAE,aAAa,CAAA;IAClC;iGAC6F;IAC7F,QAAQ,CAAC,gBAAgB,CAAC,EAAE,YAAY,CAAC,WAAW,CAAC,CAAA;CACtD,CAAA;AAED,MAAM,MAAM,qBAAqB,GAAG,oBAAoB,CAAA;AAExD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,QAAQ,EACR,SAAS,EACT,UAAU,EACV,SAAS,EAAE,aAAa,EACxB,gBAA4C,GAC7C,EAAE,qBAAqB,GAAG,GAAG,CAAC,OAAO,CAgCrC"}
+{"version":3,"file":"thread-message.d.ts","sourceRoot":"","sources":["../../src/agent-chat/thread-message.tsx"],"names":[],"mappings":"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"}

package/dist/agent-chat/thread-message.js

@@ -10,12 +10,16 @@ import {
   Text,
   UnstyledButton
 } from "@mantine/core";
-import { useDisclosure } from "@mantine/hooks";
-import { Fragment, memo, useMemo } from "react";
+import { useDisclosure, useFocusWithin, useHover, useMergedRef } from "@mantine/hooks";
+import { Fragment, lazy, memo, Suspense, useLayoutEffect, useMemo, useRef } from "react";
 import { coalesceParts, narrowAgentPart, PartList } from "../agent/index.js";
 import { Markdown } from "../content/markdown.js";
+import { CopyAction } from "../content/copy-action.js";
 import { VX } from "../tokens/index.js";
+import { DEFAULT_AFFORDANCES } from "./message-affordances.js";
+import { formatRelativeTime } from "./relative-time.js";
 import { ToolChip } from "./tool-chip.js";
+import { resolveVirtualize } from "./virtualize.js";
 const MICRO_LABEL_STYLE = {
   fontFamily: "var(--basalt-font-mono)",
   fontSize: VX.text.micro,
@@ -98,6 +102,51 @@ function resolveSegments(parts, renderers, fallbackRenderer) {
   flushBuffer();
   return segments;
 }
+function extractCoalescedText(segments) {
+  const chunks = [];
+  for (const segment of segments) {
+    if (segment.kind !== "agent") continue;
+    for (const part of segment.parts) {
+      if (part.type === "text") chunks.push(part.text);
+    }
+  }
+  return chunks.join("\n\n");
+}
+const GROUP_WINDOW_MS = 5 * 6e4;
+function isConsecutiveWithPredecessor(message, predecessor) {
+  if (predecessor === void 0) return false;
+  if (predecessor.role !== message.role) return false;
+  return message.createdAt - predecessor.createdAt <= GROUP_WINDOW_MS;
+}
+function MessageAffordanceRow({
+  message,
+  coalescedText,
+  affordances,
+  isLastAssistant,
+  visible
+}) {
+  const timestampMode = affordances.timestamp ?? DEFAULT_AFFORDANCES.timestamp;
+  const showTimestamp = timestampMode !== "none";
+  const showCopy = affordances.copy ?? DEFAULT_AFFORDANCES.copy;
+  const showRegenerate = isLastAssistant && affordances.onRegenerate !== void 0;
+  const customActions = affordances.actions?.({ message });
+  if (!showTimestamp && !showCopy && !showRegenerate && customActions === void 0) return null;
+  const timestampLabel = timestampMode === "absolute" ? new Date(message.createdAt).toLocaleString() : formatRelativeTime(message.createdAt);
+  return /* @__PURE__ */ jsxs(
+    Group,
+    {
+      gap: 8,
+      "data-testid": `message-affordances-${message.id}`,
+      style: { opacity: visible ? 1 : 0, transition: "opacity 120ms ease" },
+      children: [
+        showTimestamp && /* @__PURE__ */ jsx(Text, { size: "xs", c: "dimmed", children: timestampLabel }),
+        showCopy && /* @__PURE__ */ jsx(CopyAction, { value: coalescedText, ariaLabel: "Copy message" }),
+        showRegenerate && /* @__PURE__ */ jsx(UnstyledButton, { onClick: () => affordances.onRegenerate?.(message.id), children: /* @__PURE__ */ jsx(Text, { style: MICRO_LABEL_STYLE, children: "Regenerate" }) }),
+        customActions
+      ]
+    }
+  );
+}
 const ROLE_LABEL = {
   user: "You",
   assistant: "Assistant"
@@ -111,27 +160,43 @@ function MessageBlockImpl({
   message,
   streaming = false,
   renderers,
-  fallbackRenderer
+  fallbackRenderer,
+  grouped = false,
+  affordances,
+  isLastAssistant = false
 }) {
   messageBlockRenderCounter.count += 1;
   const settled = !streaming;
+  const { hovered, ref: hoverRef } = useHover();
+  const { focused, ref: focusWithinRef } = useFocusWithin();
+  const ref = useMergedRef(hoverRef, focusWithinRef);
   const segments = useMemo(
     () => resolveSegments(message.parts, renderers, fallbackRenderer),
     [message.parts, renderers, fallbackRenderer]
   );
   const finishIndicator = message.finish === void 0 ? void 0 : FINISH_INDICATOR[message.finish];
+  const coalescedText = useMemo(
+    () => affordances === void 0 ? "" : extractCoalescedText(segments),
+    [affordances, segments]
+  );
+  const showHeader = !grouped || streaming || finishIndicator !== void 0;
   return /* @__PURE__ */ jsx(
     Box,
     {
+      ref,
+      "data-testid": `agent-message-${message.id}`,
+      "data-grouped": grouped,
       style: {
         padding: "var(--vx-space-agent-message-inset-y) var(--vx-space-agent-message-inset-x)",
-        backgroundColor: message.role === "user" ? VX.surface.subtle : VX.surface.panel,
-        borderRadius: VX.radiusCard,
-        boxShadow: VX.shadowCard
+        ...grouped ? {} : {
+          backgroundColor: message.role === "user" ? VX.surface.subtle : VX.surface.panel,
+          borderRadius: VX.radiusCard,
+          boxShadow: VX.shadowCard
+        }
       },
       children: /* @__PURE__ */ jsxs(Stack, { gap: 6, children: [
-        /* @__PURE__ */ jsxs(Group, { gap: 6, align: "center", children: [
-          /* @__PURE__ */ jsx(Text, { style: MICRO_LABEL_STYLE, children: ROLE_LABEL[message.role] }),
+        showHeader && /* @__PURE__ */ jsxs(Group, { gap: 6, align: "center", children: [
+          !grouped && /* @__PURE__ */ jsx(Text, { style: MICRO_LABEL_STYLE, children: ROLE_LABEL[message.role] }),
           streaming && /* @__PURE__ */ jsx(Loader, { size: "xs" }),
           finishIndicator !== void 0 && /* @__PURE__ */ jsx(Text, { style: { ...MICRO_LABEL_STYLE, color: finishIndicator.statusToken }, children: finishIndicator.label })
         ] }),
@@ -151,51 +216,267 @@ function MessageBlockImpl({
             settled,
             role: message.role
           }) }, segment.key)
+        ),
+        affordances !== void 0 && /* @__PURE__ */ jsx(
+          MessageAffordanceRow,
+          {
+            message,
+            coalescedText,
+            affordances,
+            isLastAssistant,
+            visible: hovered || focused
+          }
         )
       ] })
     }
   );
 }
 function areMessageBlockPropsEqual(prev, next) {
-  return prev.message === next.message && prev.streaming === next.streaming && prev.renderers === next.renderers && prev.fallbackRenderer === next.fallbackRenderer;
+  return prev.message === next.message && prev.streaming === next.streaming && prev.renderers === next.renderers && prev.fallbackRenderer === next.fallbackRenderer && prev.grouped === next.grouped && prev.affordances === next.affordances && prev.isLastAssistant === next.isLastAssistant;
 }
 const MessageBlock = memo(MessageBlockImpl, areMessageBlockPropsEqual);
+const DEFAULT_VIRTUALIZE_OVERSCAN = 6;
+const DEFAULT_VIRTUALIZE_ESTIMATE_SIZE = 160;
+const DEFAULT_VIRTUALIZE_SCROLL_END_THRESHOLD = 64;
+const DEFAULT_VIRTUALIZE_INITIAL_SCROLL = "end";
+const MAX_INITIAL_SCROLL_ATTEMPTS = 5;
+function NonVirtualizedRows({ rows, height }) {
+  return (
+    // theme-allow — degrade target owns its own scroll node, same as the real virtualizer below.
+    /* @__PURE__ */ jsx(Box, { style: { height, overflow: "auto" }, children: /* @__PURE__ */ jsx(Stack, { gap: "sm", children: rows.map((row) => /* @__PURE__ */ jsx(Fragment, { children: row.node }, row.key)) }) })
+  );
+}
+const nonVirtualizedRowsFallback = NonVirtualizedRows;
+function resolveGuardedMeasurement(host, element, size) {
+  if (size > 0) return size;
+  const index = host.indexFromElement(element);
+  const key = host.options.getItemKey(index);
+  return host.itemSizeCache.get(key) ?? host.options.estimateSize(index);
+}
+function resolveInitialScrollAction(initialScroll, rowCount, containerHeight) {
+  if (initialScroll === "start") return "skip-done";
+  if (rowCount === 0) return "skip-done";
+  if (containerHeight <= 0) return "skip-retry";
+  return "scroll";
+}
+function applyInitialScroll(state, initialScroll, rowCount, getContainerHeight, scrollToEnd, isAtEnd) {
+  if (state.hasApplied) return;
+  if (state.attempts > 0) {
+    if (isAtEnd() || state.attempts >= MAX_INITIAL_SCROLL_ATTEMPTS) {
+      state.hasApplied = true;
+      return;
+    }
+    scrollToEnd();
+    state.attempts += 1;
+    return;
+  }
+  const action = resolveInitialScrollAction(initialScroll, rowCount, getContainerHeight());
+  if (action === "skip-retry") return;
+  if (action === "skip-done") {
+    state.hasApplied = true;
+    return;
+  }
+  scrollToEnd();
+  state.attempts += 1;
+}
+function isContainerAtEnd(container, threshold) {
+  if (container === null) return false;
+  const distanceFromEnd = container.scrollHeight - container.clientHeight - container.scrollTop;
+  return distanceFromEnd <= threshold;
+}
+const LazyVirtualizedRows = lazy(
+  () => import("@tanstack/react-virtual").then(({ useVirtualizer, measureElement: defaultMeasureElement }) => {
+    function VirtualizedRowsInner({
+      rows,
+      height,
+      overscan,
+      estimateSize,
+      initialScroll
+    }) {
+      const parentRef = useRef(null);
+      const initialScrollStateRef = useRef({
+        hasApplied: false,
+        attempts: 0
+      });
+      const virtualizer = useVirtualizer({
+        count: rows.length,
+        getScrollElement: () => parentRef.current,
+        estimateSize: () => estimateSize,
+        overscan,
+        getItemKey: (index) => rows[index]?.key ?? index,
+        anchorTo: "end",
+        followOnAppend: true,
+        scrollEndThreshold: DEFAULT_VIRTUALIZE_SCROLL_END_THRESHOLD,
+        useFlushSync: false,
+        // Guards against the hidden-ancestor cache-poisoning mechanism
+        // `resolveGuardedMeasurement`'s doc and `virtualize.ts`'s composition rules describe —
+        // NOT `enabled: false`, which virtual-core 3.17.1 wires to WIPE
+        // `itemSizeCache`/`measurementsCache` entirely (`getMeasurements`'s `!enabled` branch)
+        // rather than pause measurement, so toggling it off/on around a collapse would be
+        // strictly worse than the bug it was meant to fix.
+        measureElement: (element, entry, instance) => resolveGuardedMeasurement(
+          instance,
+          element,
+          defaultMeasureElement(element, entry, instance)
+        )
+      });
+      useLayoutEffect(() => {
+        applyInitialScroll(
+          initialScrollStateRef.current,
+          initialScroll,
+          rows.length,
+          () => parentRef.current?.offsetHeight ?? 0,
+          () => virtualizer.scrollToEnd({ behavior: "auto" }),
+          () => isContainerAtEnd(parentRef.current, DEFAULT_VIRTUALIZE_SCROLL_END_THRESHOLD)
+        );
+      });
+      return (
+        // theme-allow — TanStack Virtual measures/scrolls this element (never nest in BasaltStickToBottom, see ./virtualize).
+        /* @__PURE__ */ jsx(Box, { ref: parentRef, style: { height, overflow: "auto" }, children: /* @__PURE__ */ jsx(Box, { style: { height: virtualizer.getTotalSize(), position: "relative" }, children: virtualizer.getVirtualItems().map((virtualItem) => {
+          const row = rows[virtualItem.index];
+          if (row === void 0) return null;
+          return /* @__PURE__ */ jsx(
+            Box,
+            {
+              ref: virtualizer.measureElement,
+              "data-index": virtualItem.index,
+              style: {
+                position: "absolute",
+                top: 0,
+                left: 0,
+                width: "100%",
+                transform: `translateY(${virtualItem.start}px)`
+              },
+              children: row.node
+            },
+            row.key
+          );
+        }) }) })
+      );
+    }
+    return { default: VirtualizedRowsInner };
+  }).catch(() => ({ default: NonVirtualizedRows }))
+);
+function VirtualizeSuspenseFallback({ height }) {
+  return /* @__PURE__ */ jsx(Box, { style: { height, overflow: "auto" } });
+}
+function VirtualizedTranscript(props) {
+  return /* @__PURE__ */ jsx(Suspense, { fallback: /* @__PURE__ */ jsx(VirtualizeSuspenseFallback, { height: props.height }), children: /* @__PURE__ */ jsx(LazyVirtualizedRows, { ...props }) });
+}
 const EMPTY_RENDERERS = {};
-function ThreadTranscript({
-  messages,
-  liveParts,
-  liveStatus,
-  renderers: renderersProp,
-  fallbackRenderer = DEFAULT_FALLBACK_RENDERER
-}) {
+function useStableCallback(callback) {
+  const callbackRef = useRef(callback);
+  callbackRef.current = callback;
+  const stable = useMemo(
+    () => (...args) => callbackRef.current?.(...args),
+    []
+  );
+  return callback === void 0 ? void 0 : stable;
+}
+function ThreadTranscript(props) {
+  const {
+    messages,
+    liveParts,
+    liveStatus,
+    renderers: renderersProp,
+    fallbackRenderer = DEFAULT_FALLBACK_RENDERER,
+    affordances: affordancesProp,
+    groupConsecutive = true
+  } = props;
+  const virtualized = resolveVirtualize(props);
   const renderers = useMemo(() => renderersProp ?? EMPTY_RENDERERS, [renderersProp]);
   const liveMessage = useMemo(() => {
     if (liveParts === void 0 || liveParts.length === 0) return null;
     return { id: "__live__", role: "assistant", parts: liveParts, createdAt: 0 };
   }, [liveParts]);
-  return /* @__PURE__ */ jsxs(Stack, { gap: "sm", children: [
-    messages.map((message) => /* @__PURE__ */ jsx(
-      MessageBlock,
-      {
-        message,
-        renderers,
-        fallbackRenderer
-      },
-      message.id
-    )),
-    liveMessage !== null && /* @__PURE__ */ jsx("div", { "aria-live": "polite", "aria-atomic": "false", "aria-relevant": "additions", children: /* @__PURE__ */ jsx(
-      MessageBlock,
+  const lastAssistantMessageId = useMemo(() => {
+    for (let i = messages.length - 1; i >= 0; i -= 1) {
+      const candidate = messages[i];
+      if (candidate?.role === "assistant") return candidate.id;
+    }
+    return null;
+  }, [messages]);
+  const stableOnRegenerate = useStableCallback(affordancesProp?.onRegenerate);
+  const actions = affordancesProp?.actions;
+  const resolvedAffordances = useMemo(
+    () => ({
+      timestamp: affordancesProp?.timestamp ?? DEFAULT_AFFORDANCES.timestamp,
+      copy: affordancesProp?.copy ?? DEFAULT_AFFORDANCES.copy,
+      // `exactOptionalPropertyTypes` forbids assigning a possibly-`undefined` value to an optional
+      // property directly — spread each field in only when it is actually present, rather than
+      // widening `MessageAffordances` itself to accept an explicit `undefined`.
+      ...stableOnRegenerate !== void 0 && { onRegenerate: stableOnRegenerate },
+      ...actions !== void 0 && { actions }
+    }),
+    [affordancesProp?.timestamp, affordancesProp?.copy, stableOnRegenerate, actions]
+  );
+  const settledRows = useMemo(() => {
+    const out = [];
+    messages.forEach((message, index) => {
+      out.push({
+        key: message.id,
+        node: /* @__PURE__ */ jsx(
+          MessageBlock,
+          {
+            message,
+            renderers,
+            fallbackRenderer,
+            grouped: groupConsecutive && isConsecutiveWithPredecessor(message, messages[index - 1]),
+            isLastAssistant: message.id === lastAssistantMessageId,
+            affordances: resolvedAffordances
+          }
+        )
+      });
+    });
+    return out;
+  }, [
+    messages,
+    renderers,
+    fallbackRenderer,
+    groupConsecutive,
+    lastAssistantMessageId,
+    resolvedAffordances
+  ]);
+  const liveRow = useMemo(() => {
+    if (liveMessage === null) return null;
+    return {
+      key: liveMessage.id,
+      node: /* @__PURE__ */ jsx("div", { "aria-live": "polite", "aria-atomic": "false", "aria-relevant": "additions", children: /* @__PURE__ */ jsx(
+        MessageBlock,
+        {
+          message: liveMessage,
+          streaming: liveStatus === "streaming",
+          renderers,
+          fallbackRenderer
+        }
+      ) })
+    };
+  }, [liveMessage, liveStatus, renderers, fallbackRenderer]);
+  const rows = useMemo(
+    () => liveRow === null ? settledRows : [...settledRows, liveRow],
+    [settledRows, liveRow]
+  );
+  if (virtualized !== null) {
+    return /* @__PURE__ */ jsx(
+      VirtualizedTranscript,
       {
-        message: liveMessage,
-        streaming: liveStatus === "streaming",
-        renderers,
-        fallbackRenderer
+        rows,
+        height: virtualized.height,
+        overscan: virtualized.options.overscan ?? DEFAULT_VIRTUALIZE_OVERSCAN,
+        estimateSize: virtualized.options.estimateSize ?? DEFAULT_VIRTUALIZE_ESTIMATE_SIZE,
+        initialScroll: virtualized.options.initialScroll ?? DEFAULT_VIRTUALIZE_INITIAL_SCROLL
       }
-    ) })
-  ] });
+    );
+  }
+  return /* @__PURE__ */ jsx(Stack, { gap: "sm", children: rows.map((row) => /* @__PURE__ */ jsx(Fragment, { children: row.node }, row.key)) });
 }
 export {
+  MAX_INITIAL_SCROLL_ATTEMPTS,
   ThreadTranscript,
+  applyInitialScroll,
   messageBlockRenderCounter,
+  nonVirtualizedRowsFallback,
+  resolveGuardedMeasurement,
+  resolveInitialScrollAction,
   threadPartRenderers
 };

package/dist/agent-chat/thread-outcome-card.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"thread-outcome-card.d.ts","sourceRoot":"","sources":["../../src/agent-chat/thread-outcome-card.tsx"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,OAAO,CAAA;AAChC,OAAO,KAAK,EAAE,WAAW,EAAgB,MAAM,UAAU,CAAA;AAyHzD,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;IAC5B,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,gDAAgD;IAChD,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,CAAA;CAC9B,CAAA;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,MAAM,EACN,QAAQ,EACR,QAAQ,GACT,EAAE,sBAAsB,GAAG,GAAG,CAAC,OAAO,CA+BtC"}
+{"version":3,"file":"thread-outcome-card.d.ts","sourceRoot":"","sources":["../../src/agent-chat/thread-outcome-card.tsx"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,OAAO,CAAA;AAChC,OAAO,KAAK,EAAE,WAAW,EAAgB,MAAM,UAAU,CAAA;AAiGzD,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;IAC5B,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,gDAAgD;IAChD,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,CAAA;CAC9B,CAAA;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,MAAM,EACN,QAAQ,EACR,QAAQ,GACT,EAAE,sBAAsB,GAAG,GAAG,CAAC,OAAO,CA+BtC"}