basalt-ui 1.11.0 → 1.13.0

package/dist/agent-chat/composer.d.ts

@@ -1,18 +1,140 @@
-import type { JSX } from 'react';
+import type { ClipboardEvent, JSX, ReactNode, Ref } from 'react';
+export type ComposerAttachment = {
+    readonly id: string;
+    readonly name: string;
+    readonly mediaType: string;
+    readonly size: number;
+    readonly url: string;
+};
+export type ComposerSubmit = {
+    readonly text: string;
+    readonly attachments: readonly ComposerAttachment[];
+};
+/**
+ * Imperative escape hatch for slot content that must write into the composer from OUTSIDE the
+ * render tree — a voice recorder streaming transcript chunks, a suggestion chip inserting at the
+ * cursor. Obtained via `ref`. Kept to exactly the three primitives that cover both real use cases
+ * (every method here is API surface fixed for a major, so this is deliberately not more):
+ *
+ *   - `insertText` — the one write primitive. Inserts at the CURRENT SELECTION, replacing it if
+ *     non-collapsed, so a mid-speech voice chunk lands where the caret is and a suggestion never
+ *     clobbers a selection the user made on purpose. See its own doc for what "current selection"
+ *     means when the textarea isn't focused.
+ *   - `setValue` — a whole-value replace (loading a canned reply, discarding the draft), for when
+ *     there is no meaningful selection to insert around.
+ *   - `focus` — hands focus back to the textarea (e.g. once a recorder finishes).
+ *
+ * All three write through the SAME draft store `onChange` does — same `draftKey` persistence,
+ * same subscriber notification, same value the existing submit/clear/restore logic already sees.
+ * There is no second source of truth.
+ *
+ * A slot control that inserts at the caret must not steal focus first. A plain `<button>` in
+ * `leftSection`/`rightSection` blurs the textarea on mousedown, which collapses the selection before
+ * `onClick` runs — so every insert silently lands at the end and the at-caret path is unreachable by
+ * mouse. Suppress it on the control, not here:
+ *
+ * ```tsx
+ * <ActionIcon onMouseDown={(e) => e.preventDefault()} onClick={record}>
+ * ```
+ */
+export type ComposerHandle = {
+    /**
+     * Inserts `text` at the textarea's current selection, replacing it if non-collapsed, then moves
+     * the caret to just after the inserted text.
+     *
+     * "Current selection" only exists while the textarea IS the focused element — a `<textarea>`'s
+     * `selectionStart`/`selectionEnd` are not a reliable caret once focus has moved elsewhere, so:
+     *   - **focused, collapsed caret**: inserts at that caret position.
+     *   - **focused, with a range selected**: replaces the selected range (never inserted alongside
+     *     it — that would silently keep text the user was in the middle of deleting).
+     *   - **not focused, including never focused**: appends to the end of the current value. This is
+     *     the safe default for a voice recorder streaming chunks before the user has clicked into
+     *     the box at all.
+     */
+    readonly insertText: (text: string) => void;
+    /** Replaces the whole draft value and moves the caret to the end. */
+    readonly setValue: (value: string) => void;
+    /** Focuses the textarea. */
+    readonly focus: () => void;
+};
 export type ComposerProps = {
-    /** Called with the trimmed, non-empty text on submit. The input is cleared afterward. */
-    readonly onSubmit: (text: string) => void;
-    /** Disables the textarea and the send action (e.g. while a run is streaming). */
-    readonly disabled?: boolean;
+    /** Imperative write/focus handle — see `ComposerHandle`. */
+    readonly ref?: Ref<ComposerHandle>;
+    /**
+     * Called with the trimmed text plus the pending attachments. May return `void` (fire-and-forget,
+     * validated only synchronously) or a `Promise<void>` (its outcome is awaited, its timing is not).
+     *
+     * The draft and attachments clear OPTIMISTICALLY, immediately, before this settles — a chat
+     * composer has to feel instant, so Composer never sits on the typed text for a round trip.
+     * Rejecting restores them instead:
+     *   - THROW synchronously to refuse a send outright (bad input, offline, …) — the clear never
+     *     runs, exactly as before this prop went async.
+     *   - Return a promise that REJECTS to report a failure discovered later (a network error) — the
+     *     text and attachments are put back, UNLESS something has since made that unsafe:
+     *       - the user already typed something new into the (now-empty) box — their new text wins;
+     *         the failed one is not restored (surface a retry via the failed message instead);
+     *       - a LATER submit has already gone through this same draft — that one's own optimistic
+     *         clear (whether it went on to succeed or fail) wins over restoring this older one;
+     *       - the attachments are no longer empty (the caller already put something else there), or
+     *         `draftKey` has since changed (this Composer now points at a different thread/consumer
+     *         destination) — either way the attachments are left as they are rather than risking a
+     *         leak into whatever is current now.
+     * A resolved promise clears and stays cleared, same as a `void` return.
+     */
+    readonly onSubmit: (payload: ComposerSubmit) => void | Promise<void>;
     readonly placeholder?: string;
     /** Autofocuses the textarea on mount. */
     readonly autoFocus?: boolean;
+    /** Autosize ceiling for the textarea. Default 6. */
+    readonly maxRows?: number;
+    /** Hard-disable, independent of streaming (e.g. offline). */
+    readonly disabled?: boolean;
+    /** A run is in flight on this thread. */
+    readonly streaming?: boolean;
+    /** Default false — preserves the historical `disabled={streaming}` behaviour. */
+    readonly allowSubmitWhileStreaming?: boolean;
+    /** When given, the send action becomes a Stop action while `streaming`. */
+    readonly onStop?: () => void;
+    /**
+     * Opaque slot rendered before the textarea (a voice recorder, a mode switch, …). Slot content
+     * that needs to WRITE into the composer — append a transcript, insert a suggestion — does so
+     * through the `ref` handle (`ComposerHandle`), not a callback prop here; see the file's
+     * `@example`.
+     */
+    readonly leftSection?: ReactNode;
+    /** Opaque slot rendered between the textarea and the send action (an attach button, …). */
+    readonly rightSection?: ReactNode;
+    /**
+     * Pending attachments, owned by the caller. Composer only forwards them on submit and asks for a
+     * reset afterwards — rendering previews is the caller's job, via `leftSection`/`rightSection`.
+     */
+    readonly attachments?: readonly ComposerAttachment[];
+    /**
+     * Called with `[]` optimistically the instant a submit goes out WITH pending attachments — a
+     * submit that had none to begin with skips the call rather than reporting a no-op change — and,
+     * subject to the restoration guards documented on `onSubmit`, with the original attachments
+     * again if that submit later rejects.
+     */
+    readonly onAttachmentsChange?: (next: readonly ComposerAttachment[]) => void;
+    readonly onPaste?: (event: ClipboardEvent<HTMLTextAreaElement>) => void;
+    /**
+     * Persists the unsent draft under `basalt:composer-draft:<key>`; switching keys swaps drafts, and
+     * the entry is removed (not blanked) on a successful submit.
+     *
+     * "Successful" means `onSubmit` returned (or resolved) without throwing or rejecting — a send
+     * that fails, synchronously or later over the network, restores this persisted draft instead of
+     * leaving it erased (subject to the restoration guards documented on `onSubmit`).
+     */
+    readonly draftKey?: string;
+    /** Replaces the whole Enter/Shift+Enter hint row. Pass `null` to drop it entirely. */
+    readonly hint?: ReactNode;
 };
 /**
- * An autosize Textarea + send ActionIcon. Enter submits, Shift+Enter inserts a newline.
+ * An autosize Textarea + send ActionIcon, with slots either side. Enter submits, Shift+Enter
+ * inserts a newline, and `draftKey` survives an unmount.
  *
  * @example
- * <Composer onSubmit={onSend} disabled={streaming} />
+ * <Composer onSubmit={({ text }) => onSend(text)} streaming={streaming} onStop={stop} />
  */
-export declare function Composer({ onSubmit, disabled, placeholder, autoFocus, }: ComposerProps): JSX.Element;
+export declare function Composer({ ref, onSubmit, placeholder, autoFocus, maxRows, disabled, streaming, allowSubmitWhileStreaming, onStop, leftSection, rightSection, attachments, onAttachmentsChange, onPaste, draftKey, hint, }: ComposerProps): JSX.Element;
 //# sourceMappingURL=composer.d.ts.map

package/dist/agent-chat/composer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"composer.d.ts","sourceRoot":"","sources":["../../src/agent-chat/composer.tsx"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAkB,GAAG,EAAiB,MAAM,OAAO,CAAA;AAoB/D,MAAM,MAAM,aAAa,GAAG;IAC1B,yFAAyF;IACzF,QAAQ,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IACzC,iFAAiF;IACjF,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,yCAAyC;IACzC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAC7B,CAAA;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,EACvB,QAAQ,EACR,QAAgB,EAChB,WAAW,EACX,SAAS,GACV,EAAE,aAAa,GAAG,GAAG,CAAC,OAAO,CA8E7B"}
+{"version":3,"file":"composer.d.ts","sourceRoot":"","sources":["../../src/agent-chat/composer.tsx"],"names":[],"mappings":"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"}

package/dist/agent-chat/composer.js

@@ -1,6 +1,7 @@
 import { jsx, jsxs } from "react/jsx-runtime";
 import { ActionIcon, Group, Kbd, Stack, Text, Textarea } from "@mantine/core";
-import { useState } from "react";
+import { useImperativeHandle, useLayoutEffect, useRef, useSyncExternalStore } from "react";
+import { readPersistedValue } from "../state.js";
 import { VX } from "../tokens/index.js";
 function SendGlyph() {
   return /* @__PURE__ */ jsx("svg", { width: 16, height: 16, viewBox: "0 0 24 24", fill: "none", "aria-hidden": true, children: /* @__PURE__ */ jsx(
@@ -14,21 +15,178 @@ function SendGlyph() {
     }
   ) });
 }
+function StopGlyph() {
+  return /* @__PURE__ */ jsx("svg", { width: 16, height: 16, viewBox: "0 0 24 24", "aria-hidden": true, children: /* @__PURE__ */ jsx("rect", { x: 7, y: 7, width: 10, height: 10, rx: 2, fill: "currentColor" }) });
+}
+const DRAFT_VERSION = 1;
+function createDraftStore(key) {
+  const storageKey = key === null ? null : `basalt:composer-draft:${key}`;
+  const listeners = /* @__PURE__ */ new Set();
+  let cache = key === null ? "" : null;
+  let storageHandler = null;
+  let submissionId = 0;
+  const notify = () => {
+    for (const cb of listeners) cb();
+  };
+  return {
+    subscribe: (cb) => {
+      listeners.add(cb);
+      if (storageKey !== null && storageHandler === null) {
+        storageHandler = (e) => {
+          if (e.key !== storageKey) return;
+          cache = null;
+          notify();
+        };
+        window.addEventListener("storage", storageHandler);
+      }
+      return () => {
+        listeners.delete(cb);
+        if (listeners.size === 0 && storageHandler !== null) {
+          window.removeEventListener("storage", storageHandler);
+          storageHandler = null;
+        }
+      };
+    },
+    get: () => {
+      if (cache === null) {
+        const persisted = key === null ? null : readPersistedValue(`composer-draft:${key}`, DRAFT_VERSION);
+        cache = typeof persisted === "string" ? persisted : "";
+      }
+      return cache;
+    },
+    set: (next) => {
+      cache = next;
+      if (storageKey !== null) {
+        try {
+          if (next.length === 0) window.localStorage.removeItem(storageKey);
+          else
+            window.localStorage.setItem(
+              storageKey,
+              JSON.stringify({ v: DRAFT_VERSION, value: next })
+            );
+        } catch {
+        }
+      }
+      notify();
+    },
+    bumpSubmissionId: () => {
+      submissionId += 1;
+      return submissionId;
+    },
+    currentSubmissionId: () => submissionId
+  };
+}
+const draftStores = /* @__PURE__ */ new Map();
+function persistedDraftStore(key) {
+  const existing = draftStores.get(key);
+  if (existing !== void 0) return existing;
+  const created = createDraftStore(key);
+  draftStores.set(key, created);
+  return created;
+}
+const isServer = typeof window === "undefined";
+const noopSubscribe = (_cb) => () => {
+};
+const emptyDraft = () => "";
+const NO_ATTACHMENTS = [];
+function liveSelection(el) {
+  if (document.activeElement !== el) return null;
+  const { selectionStart, selectionEnd } = el;
+  if (selectionStart === null || selectionEnd === null) return null;
+  return { start: selectionStart, end: selectionEnd };
+}
+function DefaultHint() {
+  return /* @__PURE__ */ jsxs(Group, { gap: 4, children: [
+    /* @__PURE__ */ jsx(Kbd, { size: "xs", children: "Enter" }),
+    /* @__PURE__ */ jsx(Text, { size: "xs", c: "dimmed", style: { fontFamily: "var(--basalt-font-mono)" }, children: "to send" }),
+    /* @__PURE__ */ jsx(Kbd, { size: "xs", children: "Shift" }),
+    /* @__PURE__ */ jsx(Text, { size: "xs", c: "dimmed", style: { fontFamily: "var(--basalt-font-mono)" }, children: "+" }),
+    /* @__PURE__ */ jsx(Kbd, { size: "xs", children: "Enter" }),
+    /* @__PURE__ */ jsx(Text, { size: "xs", c: "dimmed", style: { fontFamily: "var(--basalt-font-mono)" }, children: "for a new line" })
+  ] });
+}
 function Composer({
+  ref,
   onSubmit,
-  disabled = false,
   placeholder,
-  autoFocus
+  autoFocus,
+  maxRows = 6,
+  disabled = false,
+  streaming = false,
+  allowSubmitWhileStreaming = false,
+  onStop,
+  leftSection,
+  rightSection,
+  attachments,
+  onAttachmentsChange,
+  onPaste,
+  draftKey,
+  hint
 }) {
-  const [value, setValue] = useState("");
+  const memoryStore = useRef(null);
+  memoryStore.current ??= createDraftStore(null);
+  const store = draftKey === void 0 ? memoryStore.current : persistedDraftStore(draftKey);
+  const value = useSyncExternalStore(
+    isServer ? noopSubscribe : store.subscribe,
+    isServer ? emptyDraft : store.get,
+    emptyDraft
+  );
+  const inputDisabled = disabled || streaming && !allowSubmitWhileStreaming;
+  const showStop = streaming && onStop !== void 0;
+  const showSend = !showStop || allowSubmitWhileStreaming;
+  const pending = attachments ?? NO_ATTACHMENTS;
+  const trimmed = value.trim();
+  const hasPayload = trimmed.length > 0 || pending.length > 0;
+  const attachmentsRef = useRef(pending);
+  attachmentsRef.current = pending;
+  const draftKeyRef = useRef(draftKey);
+  draftKeyRef.current = draftKey;
+  const textareaRef = useRef(null);
+  const pendingCaretRef = useRef(null);
+  useLayoutEffect(() => {
+    const caret = pendingCaretRef.current;
+    if (caret === null) return;
+    pendingCaretRef.current = null;
+    textareaRef.current?.setSelectionRange(caret, caret);
+  }, [value]);
+  const insertText = (text) => {
+    const current = store.get();
+    const selection = textareaRef.current === null ? null : liveSelection(textareaRef.current);
+    const start = selection?.start ?? current.length;
+    const end = selection?.end ?? current.length;
+    const next = current.slice(0, start) + text + current.slice(end);
+    store.set(next);
+    pendingCaretRef.current = next === value ? null : start + text.length;
+  };
+  const setValue = (next) => {
+    store.set(next);
+    pendingCaretRef.current = next === value ? null : next.length;
+  };
+  const focusTextarea = () => {
+    textareaRef.current?.focus();
+  };
+  useImperativeHandle(ref, () => ({ insertText, setValue, focus: focusTextarea }));
   const submit = () => {
-    const trimmed = value.trim();
-    if (trimmed.length === 0 || disabled) return;
-    onSubmit(trimmed);
-    setValue("");
+    if (inputDisabled || !hasPayload) return;
+    const submittedText = trimmed;
+    const submittedAttachments = pending;
+    const submittedDraftKey = draftKey;
+    const mySubmissionId = store.bumpSubmissionId();
+    const result = onSubmit({ text: submittedText, attachments: submittedAttachments });
+    store.set("");
+    if (submittedAttachments.length > 0) onAttachmentsChange?.([]);
+    void Promise.resolve(result).catch(() => {
+      if (store.currentSubmissionId() === mySubmissionId && store.get() === "") {
+        store.set(submittedText);
+      }
+      if (submittedAttachments.length > 0 && attachmentsRef.current.length === 0 && draftKeyRef.current === submittedDraftKey) {
+        onAttachmentsChange?.(submittedAttachments);
+      }
+    });
   };
   const handleKeyDown = (event) => {
     if (event.key !== "Enter" || event.shiftKey) return;
+    if (event.nativeEvent.isComposing) return;
     event.preventDefault();
     submit();
   };
@@ -36,10 +194,10 @@ function Composer({
     flex: 1,
     autosize: true,
     minRows: 1,
-    maxRows: 6,
+    maxRows,
     value,
-    disabled,
-    onChange: (event) => setValue(event.currentTarget.value),
+    disabled: inputDisabled,
+    onChange: (event) => store.set(event.currentTarget.value),
     onKeyDown: handleKeyDown,
     // Composer input surface (docs/DESIGN-SPEC.md §5): panel + control radius (6px, VX.radiusCtrl);
     // the ring lives in the shadow, so the input carries no separate border. Depth is deliberately
@@ -56,30 +214,38 @@ function Composer({
   };
   if (placeholder !== void 0) textareaProps.placeholder = placeholder;
   if (autoFocus !== void 0) textareaProps.autoFocus = autoFocus;
+  if (onPaste !== void 0) textareaProps.onPaste = onPaste;
   return /* @__PURE__ */ jsxs(Stack, { gap: 6, children: [
     /* @__PURE__ */ jsxs(Group, { gap: "xs", align: "flex-end", wrap: "nowrap", children: [
-      /* @__PURE__ */ jsx(Textarea, { ...textareaProps }),
-      /* @__PURE__ */ jsx(
+      leftSection,
+      /* @__PURE__ */ jsx(Textarea, { ...textareaProps, ref: textareaRef }),
+      rightSection,
+      showStop ? /* @__PURE__ */ jsx(
+        ActionIcon,
+        {
+          size: 42,
+          radius: "md",
+          variant: "filled",
+          color: "red",
+          onClick: onStop,
+          "aria-label": "Stop generating",
+          children: /* @__PURE__ */ jsx(StopGlyph, {})
+        }
+      ) : null,
+      showSend ? /* @__PURE__ */ jsx(
         ActionIcon,
         {
           size: 42,
           radius: "md",
           variant: "filled",
           onClick: submit,
-          disabled: disabled || value.trim().length === 0,
+          disabled: inputDisabled || !hasPayload,
           "aria-label": "Send message",
           children: /* @__PURE__ */ jsx(SendGlyph, {})
         }
-      )
+      ) : null
     ] }),
-    /* @__PURE__ */ jsxs(Group, { gap: 4, children: [
-      /* @__PURE__ */ jsx(Kbd, { size: "xs", children: "Enter" }),
-      /* @__PURE__ */ jsx(Text, { size: "xs", c: "dimmed", style: { fontFamily: "var(--basalt-font-mono)" }, children: "to send" }),
-      /* @__PURE__ */ jsx(Kbd, { size: "xs", children: "Shift" }),
-      /* @__PURE__ */ jsx(Text, { size: "xs", c: "dimmed", style: { fontFamily: "var(--basalt-font-mono)" }, children: "+" }),
-      /* @__PURE__ */ jsx(Kbd, { size: "xs", children: "Enter" }),
-      /* @__PURE__ */ jsx(Text, { size: "xs", c: "dimmed", style: { fontFamily: "var(--basalt-font-mono)" }, children: "for a new line" })
-    ] })
+    hint === void 0 ? /* @__PURE__ */ jsx(DefaultHint, {}) : hint
   ] });
 }
 export {

package/dist/agent-chat/composer.test.d.ts

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

package/dist/agent-chat/composer.test.d.ts.map

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

package/dist/agent-chat/index.d.ts

@@ -14,12 +14,16 @@ export { ThreadWorkspace } from './thread-workspace.js';
 export type { ThreadWorkspaceProps } from './thread-workspace.js';
 export { ThreadFeed } from './thread-feed.js';
 export type { ThreadFeedProps } from './thread-feed.js';
+export { ThreadFeedRow } from './thread-feed-row.js';
+export type { ThreadFeedRowProps } from './thread-feed-row.js';
+export type { MessageAffordances } from './message-affordances.js';
+export type { VirtualizeOptions, VirtualizeProps } from './virtualize.js';
 export { ThreadOutcomeCard } from './thread-outcome-card.js';
 export type { ThreadOutcomeCardProps } from './thread-outcome-card.js';
 export { ThreadDetailPanel } from './thread-detail-panel.js';
 export type { ThreadDetailPanelProps } from './thread-detail-panel.js';
 export { Composer } from './composer.js';
-export type { ComposerProps } from './composer.js';
+export type { ComposerAttachment, ComposerHandle, ComposerProps, ComposerSubmit } from './composer.js';
 export { threadPartRenderers, ThreadTranscript } from './thread-message.js';
 export type { ThreadTranscriptProps } from './thread-message.js';
 export { ToolChip } from './tool-chip.js';

package/dist/agent-chat/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent-chat/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AACpD,YAAY,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AAG9D,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAC1C,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAGpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AACzD,YAAY,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAA;AAGnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AACzD,YAAY,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAA;AAGnE,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AACrC,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAG/C,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AACxE,YAAY,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAA;AAG7D,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AACtC,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent-chat/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AACpD,YAAY,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AAG9D,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAC1C,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAGpD,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACjD,YAAY,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAO3D,YAAY,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAA;AAC/D,YAAY,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAGtE,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AACzD,YAAY,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAA;AAGnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AACzD,YAAY,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAA;AAGnE,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AACrC,YAAY,EAAE,kBAAkB,EAAE,cAAc,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAGnG,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AACxE,YAAY,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAA;AAG7D,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AACtC,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA"}

package/dist/agent-chat/index.js

@@ -1,5 +1,6 @@
 import { ThreadWorkspace } from "./thread-workspace.js";
 import { ThreadFeed } from "./thread-feed.js";
+import { ThreadFeedRow } from "./thread-feed-row.js";
 import { ThreadOutcomeCard } from "./thread-outcome-card.js";
 import { ThreadDetailPanel } from "./thread-detail-panel.js";
 import { Composer } from "./composer.js";
@@ -9,6 +10,7 @@ export {
   Composer,
   ThreadDetailPanel,
   ThreadFeed,
+  ThreadFeedRow,
   ThreadOutcomeCard,
   ThreadTranscript,
   ThreadWorkspace,

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

@@ -0,0 +1,59 @@
+/**
+ * MessageAffordances — the per-message hover-row/action contract shared by `ThreadTranscript` and
+ * a virtualized `ThreadFeedRow` (both render `MessageBlock`, so the affordance surface lives here
+ * rather than being redeclared on each consumer).
+ *
+ * Type-only module — the rendering (the actual hover row, copy button, regenerate button) lives in
+ * `thread-message.tsx`. `MessageAffordances` itself IS public (re-exported, type-only, from the
+ * agent-chat barrel and the root): it is named in `ThreadTranscriptProps.affordances` and
+ * `ThreadFeedRowProps.affordances`, so a consumer has to be able to name it. `DEFAULT_AFFORDANCES`
+ * stays internal — resolving unset fields is the components' job, not the consumer's.
+ */
+import type { ReactNode } from 'react';
+import type { ChatMessage, TranscriptPart } from '../agent/index.js';
+export type MessageAffordances = {
+    /**
+     * How the per-message timestamp renders.
+     * @default 'relative'
+     */
+    readonly timestamp?: 'relative' | 'absolute' | 'none';
+    /**
+     * Whether a copy action is offered on the hover row. Copies the message's COALESCED text (the
+     * same merged/de-duplicated text `coalesceParts` produces for display), not the raw `parts`
+     * array — a message can accumulate multiple adjacent/by-id text parts while streaming, and
+     * copying the raw parts would either duplicate text or copy fragments the user never saw
+     * assembled.
+     * @default true
+     */
+    readonly copy?: boolean;
+    /**
+     * Regenerate action, shown on the LAST ASSISTANT message only (never on earlier turns, never on
+     * user messages). Receives that message's `id`. `useAgentThreadRuns`'s `retry` is
+     * THREAD-keyed (`retry: (threadId: string) => void`), replaying the last user input for the
+     * whole thread — the consumer bridges this messageId-keyed callback to that thread-keyed retry;
+     * the framework only ever hands back the messageId, it does not know about threads.
+     */
+    readonly onRegenerate?: (messageId: string) => void;
+    /**
+     * Extra actions appended to the hover row, after the built-in copy/regenerate actions.
+     *
+     * This is a RENDER prop, not an event handler — it is called during render, once per message,
+     * and its return value is rendered. That means it is treated differently from `onRegenerate`:
+     * `onRegenerate` is identity-stabilized internally (a fresh inline literal every render costs
+     * nothing), while `actions` is compared by REFERENCE, because its reference is the only signal
+     * that its output may have changed. A fresh inline `actions={() => …}` literal therefore
+     * re-renders every message block on every render of the transcript. That is correct — an action
+     * whose output depends on consumer state (a pin/star toggle) must be allowed to update — but on
+     * a long thread it is worth avoiding: wrap `actions` in the consumer's own `useCallback`, keyed
+     * on whatever state it actually reads.
+     */
+    readonly actions?: (ctx: {
+        readonly message: ChatMessage<TranscriptPart>;
+    }) => ReactNode;
+};
+/**
+ * Resolved defaults for the optional {@link MessageAffordances} fields — one place, so
+ * `ThreadTranscript` and a virtualized `ThreadFeedRow` cannot drift on what "unset" means.
+ */
+export declare const DEFAULT_AFFORDANCES: Required<Pick<MessageAffordances, 'timestamp' | 'copy'>>;
+//# sourceMappingURL=message-affordances.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"message-affordances.d.ts","sourceRoot":"","sources":["../../src/agent-chat/message-affordances.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AACtC,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAE3D,MAAM,MAAM,kBAAkB,GAAG;IAC/B;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,UAAU,GAAG,UAAU,GAAG,MAAM,CAAA;IACrD;;;;;;;OAOG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;IACvB;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAA;IACnD;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,cAAc,CAAC,CAAA;KAAE,KAAK,SAAS,CAAA;CACzF,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,IAAI,CAAC,kBAAkB,EAAE,WAAW,GAAG,MAAM,CAAC,CAGxF,CAAA"}

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

@@ -0,0 +1,7 @@
+const DEFAULT_AFFORDANCES = {
+  timestamp: "relative",
+  copy: true
+};
+export {
+  DEFAULT_AFFORDANCES
+};

package/dist/agent-chat/relative-time.d.ts

@@ -0,0 +1,27 @@
+/**
+ * formatRelativeTime — dependency-free relative-time formatting (no date-fns).
+ *
+ * Shared between `ThreadOutcomeCard` (inbox row timestamps) and `ThreadTranscript` (per-message
+ * timestamps). 'en'-hardcoded for now — see the module-level note below for the deferred locale
+ * seam.
+ *
+ * Internal to `agent-chat/` — not part of the public barrel.
+ */
+/**
+ * Formats an epoch-ms timestamp as a short relative string ("3 hours ago", "just now").
+ *
+ * A non-finite `timestamp` — `NaN`, `±Infinity`, or a non-number value that slipped past the
+ * `ChatMessage.createdAt: number` type at runtime (an ISO string or `undefined`/`null` from a
+ * hand-rolled `ThreadsStoreAdapter`, or from JSON-deserialized `localStorage` state) renders as an
+ * empty string rather than reaching `Intl.RelativeTimeFormat.format`, which throws a `RangeError`
+ * on any non-finite input. This is render-path code — one bad `createdAt` on one message must not
+ * blank the whole transcript (the standing rule `spliceText`/`coalesceParts` already hold) — so it
+ * degrades instead of throwing, and warns in dev, matching `mergePart`'s clamp-and-warn precedent
+ * (`clampOffset` in `../agent/merge.ts`). The warning is NOT deduplicated, also matching that
+ * precedent — but note the call sites differ: `clampOffset` runs once per wire event, whereas this
+ * runs during render, once per message, so a single bad `createdAt` in a long transcript warns
+ * once per message per render. That is loud on purpose (a `createdAt` that isn't a number is an
+ * adapter bug worth fixing, not worth muting), and it costs nothing in production.
+ */
+export declare function formatRelativeTime(timestamp: number): string;
+//# sourceMappingURL=relative-time.d.ts.map

package/dist/agent-chat/relative-time.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relative-time.d.ts","sourceRoot":"","sources":["../../src/agent-chat/relative-time.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAgBH;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAc5D"}

package/dist/agent-chat/relative-time.js

@@ -0,0 +1,27 @@
+const RELATIVE_TIME_FORMAT = new Intl.RelativeTimeFormat("en", { numeric: "auto" });
+const RELATIVE_TIME_UNITS = [
+  { unit: "year", ms: 31536e6 },
+  { unit: "month", ms: 2628e6 },
+  { unit: "week", ms: 6048e5 },
+  { unit: "day", ms: 864e5 },
+  { unit: "hour", ms: 36e5 },
+  { unit: "minute", ms: 6e4 }
+];
+function formatRelativeTime(timestamp) {
+  if (!Number.isFinite(timestamp)) {
+    if (process.env["NODE_ENV"] !== "production") {
+      console.warn(
+        `[basalt] formatRelativeTime: non-finite timestamp ${String(timestamp)} \u2014 rendering empty string`
+      );
+    }
+    return "";
+  }
+  const diffMs = timestamp - Date.now();
+  const absMs = Math.abs(diffMs);
+  if (absMs < 6e4) return "just now";
+  const unit = RELATIVE_TIME_UNITS.find(({ ms }) => absMs >= ms) ?? RELATIVE_TIME_UNITS.at(-1);
+  return RELATIVE_TIME_FORMAT.format(Math.round(diffMs / unit.ms), unit.unit);
+}
+export {
+  formatRelativeTime
+};

package/dist/agent-chat/relative-time.test.d.ts

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

package/dist/agent-chat/relative-time.test.d.ts.map

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

package/dist/agent-chat/thread-detail-panel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"thread-detail-panel.d.ts","sourceRoot":"","sources":["../../src/agent-chat/thread-detail-panel.tsx"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,OAAO,CAAA;AAChC,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAiDpE,MAAM,MAAM,sBAAsB,GAAG;IACnC,uFAAuF;IACvF,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAA;IACnC,0FAA0F;IAC1F,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,EAAE,CAAA;IAChC,4FAA4F;IAC5F,QAAQ,CAAC,SAAS,CAAC,EAAE,YAAY,CAAA;IACjC,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,IAAI,CAAA;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAA;IAC5B;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;CAC9B,CAAA;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,MAAM,EACN,SAAS,EACT,SAAS,EACT,MAAM,EACN,MAAM,EACN,OAAO,EACP,OAAO,GACR,EAAE,sBAAsB,GAAG,GAAG,CAAC,OAAO,CAuFtC"}
+{"version":3,"file":"thread-detail-panel.d.ts","sourceRoot":"","sources":["../../src/agent-chat/thread-detail-panel.tsx"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,OAAO,CAAA;AAChC,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAiDpE,MAAM,MAAM,sBAAsB,GAAG;IACnC,uFAAuF;IACvF,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAA;IACnC,0FAA0F;IAC1F,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,EAAE,CAAA;IAChC,4FAA4F;IAC5F,QAAQ,CAAC,SAAS,CAAC,EAAE,YAAY,CAAA;IACjC,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,IAAI,CAAA;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAA;IAC5B;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;CAC9B,CAAA;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,MAAM,EACN,SAAS,EACT,SAAS,EACT,MAAM,EACN,MAAM,EACN,OAAO,EACP,OAAO,GACR,EAAE,sBAAsB,GAAG,GAAG,CAAC,OAAO,CAyFtC"}

package/dist/agent-chat/thread-detail-panel.js

@@ -90,7 +90,7 @@ function ThreadDetailPanel({
     ) }),
     /* @__PURE__ */ jsx(Divider, { color: "var(--vx-divider)" }),
     /* @__PURE__ */ jsx(Box, { p: "sm", children: /* @__PURE__ */ jsxs(Stack, { gap: "xs", children: [
-      /* @__PURE__ */ jsx(Composer, { onSubmit: onSend, disabled: streaming }),
+      /* @__PURE__ */ jsx(Composer, { onSubmit: ({ text }) => onSend(text), streaming }),
       streaming && /* @__PURE__ */ jsx(Button, { size: "compact-sm", variant: "subtle", color: "red", onClick: onStop, children: "Stop" })
     ] }) })
   ] });