basalt-ui 1.11.0 → 1.13.0

package/dist/agent-chat/thread-feed-row.d.ts

@@ -0,0 +1,65 @@
+import type { JSX } from 'react';
+import type { AgentThread, ForeignPart, PartRenderer, PartRenderers, StreamStatus, TranscriptPart } from '../agent/index.js';
+import type { ComposerProps, ComposerSubmit } from './composer.js';
+import type { MessageAffordances } from './message-affordances.js';
+import type { VirtualizeProps } from './virtualize.js';
+type ThreadFeedRowBase = {
+    /**
+     * The thread this row projects. Typed against `AgentThread<TranscriptPart>` — not the plain,
+     * `AgentPart`-defaulted `AgentThread` `ThreadFeed` uses, and not a type parameter. A consumer
+     * with a registered `ForeignPart` union passes its own threads straight through with no generic
+     * argument and no cast, because `TranscriptPart` is the widest part type and arrays are
+     * structurally covariant: `AgentPart[]` and `ConsumerPart[]` both widen into `TranscriptPart[]`.
+     * Widening the row is what lets both `ThreadFeed` (non-generic, `AgentThread<AgentPart>`) and a
+     * part-registry consumer feed the same component.
+     */
+    readonly thread: AgentThread<TranscriptPart>;
+    /** Whether this row's transcript+composer body is currently visible. */
+    readonly expanded: boolean;
+    /** Called with the thread's id when the header is clicked/activated. */
+    readonly onToggle: (id: string) => void;
+    /** The live (in-flight) assistant turn's parts, when a run is streaming for this thread. */
+    readonly liveParts?: readonly TranscriptPart[];
+    /** The live run's status — drives the in-progress indicator on the live block. */
+    readonly liveStatus?: StreamStatus;
+    /** Consumer renderers keyed by part.type, forwarded to `ThreadTranscript`. */
+    readonly renderers?: PartRenderers;
+    /** Forwarded to `ThreadTranscript` — see its own prop doc. */
+    readonly fallbackRenderer?: PartRenderer<ForeignPart>;
+    /**
+     * Per-message hover-row contract (timestamp/copy/regenerate/actions), forwarded verbatim to the
+     * row's `ThreadTranscript`. Shared with it via `message-affordances.ts` so the two cannot drift
+     * on what an unset field means.
+     */
+    readonly affordances?: MessageAffordances;
+    /** Forwarded to `ThreadTranscript` — suppresses role label + chrome on same-speaker runs.
+     * @default true */
+    readonly groupConsecutive?: boolean;
+    /** Called with the composer's submit payload. */
+    readonly onSend: (payload: ComposerSubmit) => void;
+    /** Shown as the composer's Stop action while `liveStatus === 'streaming'`. */
+    readonly onStop?: () => void;
+    /** Forwarded to the row's `Composer`, minus the three props this component always wires itself
+     * (`onSubmit`, `onStop`, and `streaming` — the last derived from `liveStatus` so a consumer can't
+     * pass one that disagrees with the row's own live status). */
+    readonly composerProps?: Omit<ComposerProps, 'onSubmit' | 'onStop' | 'streaming'>;
+};
+/**
+ * `virtualize`/`height` are forwarded straight to the row's `ThreadTranscript`, carrying the same
+ * union guard: an inline row holding a very long thread can window it, and doing so REQUIRES a
+ * `height` (the transcript then owns a fixed-height scroll node inside the expanded body, instead
+ * of the body growing to the thread's full length). Omit both and the row's transcript is
+ * content-sized, as before.
+ */
+export type ThreadFeedRowProps = ThreadFeedRowBase & VirtualizeProps;
+/**
+ * One inline-expanding thread row: a header (title + relative timestamp) that toggles a lazily
+ * mounted, kept-mounted transcript + composer body. See the module doc for the mount lifecycle
+ * invariant this component exists to guarantee.
+ *
+ * @example
+ * <ThreadFeedRow thread={thread} expanded={expanded} onToggle={onToggle} onSend={onSend} />
+ */
+export declare function ThreadFeedRow(props: ThreadFeedRowProps): JSX.Element;
+export {};
+//# sourceMappingURL=thread-feed-row.d.ts.map

package/dist/agent-chat/thread-feed-row.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"thread-feed-row.d.ts","sourceRoot":"","sources":["../../src/agent-chat/thread-feed-row.tsx"],"names":[],"mappings":"AAmCA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,OAAO,CAAA;AAEhC,OAAO,KAAK,EACV,WAAW,EACX,WAAW,EACX,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,cAAc,EACf,MAAM,UAAU,CAAA;AAEjB,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAE/D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAA;AAI/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AA6BnD,KAAK,iBAAiB,GAAG;IACvB;;;;;;;;OAQG;IACH,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,cAAc,CAAC,CAAA;IAC5C,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;IAC1B,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAA;IACvC,4FAA4F;IAC5F,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,cAAc,EAAE,CAAA;IAC9C,kFAAkF;IAClF,QAAQ,CAAC,UAAU,CAAC,EAAE,YAAY,CAAA;IAClC,8EAA8E;IAC9E,QAAQ,CAAC,SAAS,CAAC,EAAE,aAAa,CAAA;IAClC,8DAA8D;IAC9D,QAAQ,CAAC,gBAAgB,CAAC,EAAE,YAAY,CAAC,WAAW,CAAC,CAAA;IACrD;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,kBAAkB,CAAA;IACzC;uBACmB;IACnB,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAA;IACnC,iDAAiD;IACjD,QAAQ,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,CAAA;IAClD,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,IAAI,CAAA;IAC5B;;kEAE8D;IAC9D,QAAQ,CAAC,aAAa,CAAC,EAAE,IAAI,CAAC,aAAa,EAAE,UAAU,GAAG,QAAQ,GAAG,WAAW,CAAC,CAAA;CAClF,CAAA;AAED;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG,iBAAiB,GAAG,eAAe,CAAA;AASpE;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,GAAG,CAAC,OAAO,CA8HpE"}

package/dist/agent-chat/thread-feed-row.js

@@ -0,0 +1,156 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+import { Box, Group, Stack, Text, UnstyledButton } from "@mantine/core";
+import { useState } from "react";
+import { VX } from "../tokens/index.js";
+import { Composer } from "./composer.js";
+import { formatRelativeTime } from "./relative-time.js";
+import { ThreadTranscript } from "./thread-message.js";
+import { resolveVirtualize } from "./virtualize.js";
+function ChevronGlyph({ expanded }) {
+  return /* @__PURE__ */ jsx(
+    "svg",
+    {
+      width: 14,
+      height: 14,
+      viewBox: "0 0 24 24",
+      fill: "none",
+      "aria-hidden": true,
+      style: {
+        transform: expanded ? "rotate(90deg)" : "rotate(0deg)",
+        transition: "transform 120ms ease",
+        flexShrink: 0
+      },
+      children: /* @__PURE__ */ jsx(
+        "path",
+        {
+          d: "M9 6l6 6l-6 6",
+          stroke: "currentColor",
+          strokeWidth: 2,
+          strokeLinecap: "round",
+          strokeLinejoin: "round"
+        }
+      )
+    }
+  );
+}
+function rowTitle(thread) {
+  return thread.outcome?.title ?? "Untitled thread";
+}
+function ThreadFeedRow(props) {
+  const {
+    thread,
+    expanded,
+    onToggle,
+    liveParts,
+    liveStatus,
+    renderers,
+    fallbackRenderer,
+    affordances,
+    groupConsecutive,
+    onSend,
+    onStop,
+    composerProps
+  } = props;
+  const virtualized = resolveVirtualize(props);
+  const virtualizeProps = virtualized === null ? {} : { virtualize: virtualized.options, height: virtualized.height };
+  const [hasOpened, setHasOpened] = useState(expanded);
+  if (expanded && !hasOpened) {
+    setHasOpened(true);
+  }
+  const summary = thread.outcome?.summary ?? "";
+  const streaming = liveStatus === "streaming";
+  return /* @__PURE__ */ jsxs(
+    Box,
+    {
+      style: {
+        borderRadius: VX.radiusCard,
+        boxShadow: VX.shadowCard,
+        backgroundColor: VX.surface.panel,
+        overflow: "hidden"
+      },
+      children: [
+        /* @__PURE__ */ jsx(
+          UnstyledButton,
+          {
+            onClick: () => onToggle(thread.id),
+            w: "100%",
+            "aria-expanded": expanded,
+            style: {
+              display: "block",
+              padding: "var(--mantine-spacing-xs) var(--mantine-spacing-sm)"
+            },
+            children: /* @__PURE__ */ jsxs(Group, { justify: "space-between", gap: "xs", wrap: "nowrap", align: "center", children: [
+              /* @__PURE__ */ jsxs(Stack, { gap: 2, style: { flex: 1, minWidth: 0 }, children: [
+                /* @__PURE__ */ jsx(
+                  Text,
+                  {
+                    fw: 550,
+                    lineClamp: 1,
+                    style: {
+                      fontFamily: "var(--basalt-font-head)",
+                      fontSize: VX.text.md,
+                      fontStretch: "88%"
+                    },
+                    children: rowTitle(thread)
+                  }
+                ),
+                summary.length > 0 && /* @__PURE__ */ jsx(Text, { size: "xs", c: "dimmed", lineClamp: 1, children: summary })
+              ] }),
+              /* @__PURE__ */ jsx(
+                Text,
+                {
+                  style: {
+                    fontFamily: "var(--basalt-font-mono)",
+                    fontSize: VX.text.micro,
+                    color: VX.faint,
+                    flexShrink: 0
+                  },
+                  children: formatRelativeTime(thread.updatedAt)
+                }
+              ),
+              /* @__PURE__ */ jsx(ChevronGlyph, { expanded })
+            ] })
+          }
+        ),
+        hasOpened && /* @__PURE__ */ jsx(
+          Box,
+          {
+            "data-testid": "thread-feed-row-body",
+            style: {
+              display: expanded ? "block" : "none",
+              padding: "var(--mantine-spacing-sm)",
+              paddingTop: 0
+            },
+            children: /* @__PURE__ */ jsxs(Stack, { gap: "sm", children: [
+              /* @__PURE__ */ jsx(
+                ThreadTranscript,
+                {
+                  messages: thread.messages,
+                  ...liveParts !== void 0 ? { liveParts } : {},
+                  ...liveStatus !== void 0 ? { liveStatus } : {},
+                  ...renderers !== void 0 ? { renderers } : {},
+                  ...fallbackRenderer !== void 0 ? { fallbackRenderer } : {},
+                  ...affordances !== void 0 ? { affordances } : {},
+                  ...groupConsecutive !== void 0 ? { groupConsecutive } : {},
+                  ...virtualizeProps
+                }
+              ),
+              /* @__PURE__ */ jsx(
+                Composer,
+                {
+                  onSubmit: onSend,
+                  streaming,
+                  ...onStop !== void 0 ? { onStop } : {},
+                  ...composerProps
+                }
+              )
+            ] })
+          }
+        )
+      ]
+    }
+  );
+}
+export {
+  ThreadFeedRow
+};

package/dist/agent-chat/thread-feed-row.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=thread-feed-row.test.d.ts.map

package/dist/agent-chat/thread-feed-row.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"thread-feed-row.test.d.ts","sourceRoot":"","sources":["../../src/agent-chat/thread-feed-row.test.tsx"],"names":[],"mappings":""}

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

@@ -1,18 +1,47 @@
-import type { JSX } from 'react';
+import type { JSX, ReactNode } from 'react';
 import type { AgentThread } from '../agent/index.js';
+import type { ComposerSubmit } from './composer.js';
 export type ThreadFeedProps = {
     readonly threads: AgentThread[];
     /** The currently open thread id, or null when none is selected. */
     readonly activeId: string | null;
-    /** Called with a thread's id when its row is selected. */
+    /** Called with a thread's id when its row is selected. Never called to report a collapse — see
+     * `variant`'s doc for how the built-in `'inline'` row's expand/collapse is decoupled from this. */
     readonly onSelect: (id: string) => void;
+    /**
+     * Row shape: `'outcome'` (default) renders today's `ThreadOutcomeCard` inbox row, unchanged.
+     * `'inline'` renders `ThreadFeedRow`, the Slack-style inline-expanding row, wired to this feed's
+     * own `activeId` for which row is open (so at most one row is open at a time, mirroring the
+     * inbox's single-selection model) — with its OWN collapse tracking layered on top, not a raw
+     * pass-through of `onSelect` as `onToggle`. `onSelect` is documented as a selection event, and
+     * collapsing a row that remains the active thread isn't one; wiring `onToggle={onSelect}`
+     * directly (the previous shape) meant a plain `onSelect={setActiveId}` consumer could never
+     * collapse a row, since re-selecting the same id is a no-op state update. Collapsing here is
+     * local, UI-only state, reset whenever `activeId` changes to point at a DIFFERENT thread. Since
+     * this reset is a `useEffect` keyed on `activeId`, re-driving it to the SAME id from outside
+     * this component is a no-op React dep comparison, so it does not clear the override.
+     */
+    readonly variant?: 'outcome' | 'inline';
+    /**
+     * Wires the built-in `'inline'` row's composer to a real send channel — called with the thread
+     * and the composer's submit payload. Omit it and the row's composer renders disabled (visibly
+     * inert) instead of a live control that silently discards whatever is typed into it; a consumer
+     * that needs the composer live must supply this (or `renderRow`, for full control over the row).
+     */
+    readonly onSend?: (thread: AgentThread, payload: ComposerSubmit) => void;
+    /** Overrides row rendering entirely, for BOTH variants — when supplied, this is called for every
+     * thread instead of either built-in row. Gives full control over live-run wiring
+     * (`onStop`/`liveParts`/`liveStatus`) the built-in `'inline'` row doesn't expose; see `variant`
+     * and `onSend`. */
+    readonly renderRow?: (thread: AgentThread) => ReactNode;
 };
 /**
- * A scrollable feed of thread rows, animated on add/remove/reorder. Each row renders via
- * `ThreadOutcomeCard`; selection highlighting is derived from `activeId`.
+ * A scrollable feed of thread rows, animated on add/remove/reorder. Row content comes from
+ * `renderRow` when supplied, else from the built-in `variant` row (`ThreadOutcomeCard` or
+ * `ThreadFeedRow`) — see `ThreadFeedProps` for the full contract.
  *
  * @example
  * <ThreadFeed threads={threads} activeId={activeId} onSelect={(id) => select(id)} />
  */
-export declare function ThreadFeed({ threads, activeId, onSelect }: ThreadFeedProps): JSX.Element;
+export declare function ThreadFeed({ threads, activeId, onSelect, variant, onSend, renderRow, }: ThreadFeedProps): JSX.Element;
 //# sourceMappingURL=thread-feed.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"thread-feed.d.ts","sourceRoot":"","sources":["../../src/agent-chat/thread-feed.tsx"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,OAAO,CAAA;AAChC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAI3C,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,OAAO,EAAE,WAAW,EAAE,CAAA;IAC/B,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IAChC,0DAA0D;IAC1D,QAAQ,CAAC,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAA;CACxC,CAAA;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE,eAAe,GAAG,GAAG,CAAC,OAAO,CA4CxF"}
+{"version":3,"file":"thread-feed.d.ts","sourceRoot":"","sources":["../../src/agent-chat/thread-feed.tsx"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAE3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAE3C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAShD,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,OAAO,EAAE,WAAW,EAAE,CAAA;IAC/B,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IAChC;uGACmG;IACnG,QAAQ,CAAC,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAA;IACvC;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAA;IACvC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,cAAc,KAAK,IAAI,CAAA;IACxE;;;uBAGmB;IACnB,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,SAAS,CAAA;CACxD,CAAA;AAgCD;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,EACzB,OAAO,EACP,QAAQ,EACR,QAAQ,EACR,OAAmB,EACnB,MAAM,EACN,SAAS,GACV,EAAE,eAAe,GAAG,GAAG,CAAC,OAAO,CAkE/B"}

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

@@ -1,21 +1,61 @@
 import { jsx } from "react/jsx-runtime";
-import { ScrollArea, Stack } from "@mantine/core";
+import { Box, ScrollArea, Stack } from "@mantine/core";
 import { useReducedMotion } from "@mantine/hooks";
 import { AnimatePresence, motion } from "motion/react";
+import { useEffect, useState } from "react";
 import { MOTION_SPRING } from "../motion/index.js";
+import { ThreadFeedRow } from "./thread-feed-row.js";
 import { ThreadOutcomeCard } from "./thread-outcome-card.js";
-function ThreadFeed({ threads, activeId, onSelect }) {
-  const reduceMotion = useReducedMotion();
-  if (reduceMotion) {
-    return /* @__PURE__ */ jsx(ScrollArea, { style: { height: "100%" }, children: /* @__PURE__ */ jsx(Stack, { gap: "sm", p: "sm", children: threads.map((thread) => /* @__PURE__ */ jsx(
-      ThreadOutcomeCard,
+function noopSend() {
+}
+function defaultRow(thread, variant, activeId, collapsedId, onToggle, onSelect, onSend) {
+  if (variant === "inline") {
+    const expanded = thread.id === activeId && thread.id !== collapsedId;
+    return /* @__PURE__ */ jsx(
+      ThreadFeedRow,
       {
         thread,
-        selected: thread.id === activeId,
-        onSelect: () => onSelect(thread.id)
-      },
-      thread.id
-    )) }) });
+        expanded,
+        onToggle,
+        onSend: onSend !== void 0 ? (payload) => onSend(thread, payload) : noopSend,
+        ...onSend === void 0 ? { composerProps: { disabled: true } } : {}
+      }
+    );
+  }
+  return /* @__PURE__ */ jsx(
+    ThreadOutcomeCard,
+    {
+      thread,
+      selected: thread.id === activeId,
+      onSelect: () => onSelect(thread.id)
+    }
+  );
+}
+function ThreadFeed({
+  threads,
+  activeId,
+  onSelect,
+  variant = "outcome",
+  onSend,
+  renderRow
+}) {
+  const reduceMotion = useReducedMotion();
+  const [collapsedId, setCollapsedId] = useState(null);
+  useEffect(() => {
+    setCollapsedId(null);
+  }, [activeId]);
+  function handleInlineToggle(id) {
+    const isOpen = id === activeId && id !== collapsedId;
+    if (isOpen) {
+      setCollapsedId(id);
+      return;
+    }
+    setCollapsedId(null);
+    onSelect(id);
+  }
+  const rowFor = (thread) => renderRow !== void 0 ? renderRow(thread) : defaultRow(thread, variant, activeId, collapsedId, handleInlineToggle, onSelect, onSend);
+  if (reduceMotion) {
+    return /* @__PURE__ */ jsx(ScrollArea, { style: { height: "100%" }, children: /* @__PURE__ */ jsx(Stack, { gap: "sm", p: "sm", children: threads.map((thread) => /* @__PURE__ */ jsx(Box, { children: rowFor(thread) }, thread.id)) }) });
   }
   return /* @__PURE__ */ jsx(ScrollArea, { style: { height: "100%" }, children: /* @__PURE__ */ jsx(Stack, { gap: "sm", p: "sm", children: /* @__PURE__ */ jsx(AnimatePresence, { mode: "popLayout", initial: false, children: threads.map((thread) => /* @__PURE__ */ jsx(
     motion.div,
@@ -25,14 +65,7 @@ function ThreadFeed({ threads, activeId, onSelect }) {
       animate: { opacity: 1, y: 0 },
       exit: { opacity: 0, scale: 0.97 },
       transition: MOTION_SPRING,
-      children: /* @__PURE__ */ jsx(
-        ThreadOutcomeCard,
-        {
-          thread,
-          selected: thread.id === activeId,
-          onSelect: () => onSelect(thread.id)
-        }
-      )
+      children: rowFor(thread)
     },
     thread.id
   )) }) }) });

package/dist/agent-chat/thread-feed.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=thread-feed.test.d.ts.map

package/dist/agent-chat/thread-feed.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"thread-feed.test.d.ts","sourceRoot":"","sources":["../../src/agent-chat/thread-feed.test.tsx"],"names":[],"mappings":""}

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;AAkFjB;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,EAAE,OAAO,CAAC,kBAAkB,CAM3D,CAAA;AAqID;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB;;CAAe,CAAA;AA8ErD,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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"}