@assistant-ui/react 0.15.23 → 0.15.25

package/dist/utils/smooth/useSmooth.js.map

@@ -1 +1 @@
-{"version":3,"file":"useSmooth.js","names":["useEffect","useMemo","useRef","useState","useAui","useAuiState","MessagePartStatus","ReasoningMessagePart","TextMessagePart","MessagePartState","useCallbackRef","useMediaQuery","useSmoothStatusStore","writableStore","SmoothOptions","drainMs","maxCharIntervalMs","maxCharsPerFrame","minCommitMs","DEFAULT_DRAIN_MS","DEFAULT_MAX_CHAR_INTERVAL_MS","TextStreamAnimator","animationFrameId","lastUpdateTime","Date","now","lastCommitTime","targetText","Infinity","currentText","setText","newText","constructor","start","animate","stop","cancelAnimationFrame","currentTime","deltaTime","timeToConsume","remainingChars","length","baseTimePerChar","Math","min","frameLimit","charsToAdd","requestAnimationFrame","slice","isComplete","SMOOTH_STATUS","Object","freeze","type","positiveOr","value","fallback","undefined","useSmooth","state","smooth","text","reduceMotion","options","enabled","displayedText","setDisplayedText","status","aui","part","prevPart","setPrevPart","startsWith","smoothStatusStore","optional","target","setState","animatorRef","animatorPartRef","partChanged","current"],"sources":["../../../src/utils/smooth/useSmooth.ts"],"sourcesContent":["\"use client\";\n\nimport { useEffect, useMemo, useRef, useState } from \"react\";\nimport { useAui, useAuiState } from \"@assistant-ui/store\";\nimport type {\n  MessagePartStatus,\n  ReasoningMessagePart,\n  TextMessagePart,\n  MessagePartState,\n} from \"@assistant-ui/core\";\nimport { useCallbackRef } from \"radix-ui/internal\";\nimport { useMediaQuery } from \"../hooks/useMediaQuery\";\nimport { useSmoothStatusStore } from \"./SmoothContext\";\nimport { writableStore } from \"../../context/ReadonlyStore\";\n\n/**\n * Tuning options for the smooth text streaming animation.\n */\nexport type SmoothOptions = {\n  /**\n   * Target time in milliseconds to drain the backlog of unrevealed\n   * characters. Larger values reveal long backlogs more gradually.\n   * @default 250\n   */\n  drainMs?: number | undefined;\n  /**\n   * Maximum time in milliseconds between revealed characters, i.e. the\n   * slowest reveal rate when the backlog is short.\n   * @default 5\n   */\n  maxCharIntervalMs?: number | undefined;\n  /**\n   * Maximum number of characters revealed per animation frame.\n   * @default Infinity\n   */\n  maxCharsPerFrame?: number | undefined;\n  /**\n   * Minimum time in milliseconds between committed updates. The reveal keeps\n   * advancing every frame, but the visible text (and the downstream re-render\n   * and markdown re-parse it triggers) is committed at most once per interval.\n   * The final frame always commits. `0` commits every frame.\n   * @default 0\n   */\n  minCommitMs?: number | undefined;\n};\n\nconst DEFAULT_DRAIN_MS = 250;\nconst DEFAULT_MAX_CHAR_INTERVAL_MS = 5;\n\nclass TextStreamAnimator {\n  private animationFrameId: number | null = null;\n  private lastUpdateTime: number = Date.now();\n  public lastCommitTime: number = 0;\n\n  public targetText: string = \"\";\n  public drainMs: number = DEFAULT_DRAIN_MS;\n  public maxCharIntervalMs: number = DEFAULT_MAX_CHAR_INTERVAL_MS;\n  public maxCharsPerFrame: number = Infinity;\n  public minCommitMs: number = 0;\n\n  public currentText: string;\n  private setText: (newText: string) => void;\n\n  constructor(currentText: string, setText: (newText: string) => void) {\n    this.currentText = currentText;\n    this.setText = setText;\n  }\n\n  start() {\n    if (this.animationFrameId !== null) return;\n    this.lastUpdateTime = Date.now();\n    this.animate();\n  }\n\n  stop() {\n    if (this.animationFrameId !== null) {\n      cancelAnimationFrame(this.animationFrameId);\n      this.animationFrameId = null;\n    }\n  }\n\n  private animate = () => {\n    const currentTime = Date.now();\n    const deltaTime = currentTime - this.lastUpdateTime;\n    let timeToConsume = deltaTime;\n\n    const remainingChars = this.targetText.length - this.currentText.length;\n    const baseTimePerChar = Math.min(\n      this.maxCharIntervalMs,\n      this.drainMs / remainingChars,\n    );\n\n    const frameLimit = Math.min(remainingChars, this.maxCharsPerFrame);\n    let charsToAdd = 0;\n    while (timeToConsume >= baseTimePerChar && charsToAdd < frameLimit) {\n      charsToAdd++;\n      timeToConsume -= baseTimePerChar;\n    }\n    // A cap-limited frame must not bank its surplus time, or the next\n    // frame would burst past the cap.\n    if (charsToAdd === frameLimit && frameLimit === this.maxCharsPerFrame) {\n      timeToConsume = 0;\n    }\n\n    if (charsToAdd !== remainingChars) {\n      this.animationFrameId = requestAnimationFrame(this.animate);\n    } else {\n      this.animationFrameId = null;\n    }\n    if (charsToAdd === 0) return;\n\n    this.currentText = this.targetText.slice(\n      0,\n      this.currentText.length + charsToAdd,\n    );\n    this.lastUpdateTime = currentTime - timeToConsume;\n\n    const isComplete = charsToAdd === remainingChars;\n    if (isComplete || currentTime - this.lastCommitTime >= this.minCommitMs) {\n      this.lastCommitTime = currentTime;\n      this.setText(this.currentText);\n    }\n  };\n}\n\nconst SMOOTH_STATUS: MessagePartStatus = Object.freeze({\n  type: \"running\",\n});\n\nconst positiveOr = (value: number | undefined, fallback: number): number =>\n  value !== undefined && value > 0 ? value : fallback;\n\n/**\n * Animates streamed message part text with a typewriter-style reveal.\n *\n * Takes the current part state and a `smooth` argument: `false` disables,\n * `true` uses the default rate, and a {@link SmoothOptions} object tunes\n * the reveal. Returns the part state with `text` replaced by the revealed\n * prefix and `status` reporting `running` until the reveal catches up.\n * If the source settles before any character has been revealed, the text\n * is committed immediately so a missed animation frame cannot leave an\n * empty bubble.\n *\n * The reveal auto-disables under `prefers-reduced-motion: reduce`,\n * committing the full text immediately; this takes precedence over an\n * explicit `smooth={true}`.\n *\n * @example\n * ```tsx\n * const { text, status } = useSmooth(useMessagePartText(), {\n *   drainMs: 500,\n *   maxCharsPerFrame: 30,\n * });\n * ```\n */\nexport const useSmooth = (\n  state: MessagePartState & (TextMessagePart | ReasoningMessagePart),\n  smooth: boolean | SmoothOptions = false,\n): MessagePartState & (TextMessagePart | ReasoningMessagePart) => {\n  const { text } = state;\n  const reduceMotion = useMediaQuery(\"(prefers-reduced-motion: reduce)\");\n  const options =\n    typeof smooth === \"object\" && smooth !== null ? smooth : undefined;\n  const enabled = smooth !== false && smooth !== null && !reduceMotion;\n  const drainMs = positiveOr(options?.drainMs, DEFAULT_DRAIN_MS);\n  const maxCharIntervalMs = positiveOr(\n    options?.maxCharIntervalMs,\n    DEFAULT_MAX_CHAR_INTERVAL_MS,\n  );\n  const maxCharsPerFrame = positiveOr(options?.maxCharsPerFrame, Infinity);\n  const minCommitMs = positiveOr(options?.minCommitMs, 0);\n\n  const [displayedText, setDisplayedText] = useState(\n    state.status.type === \"running\" ? \"\" : text,\n  );\n\n  // Render-phase resync on part flip or text discontinuity, so the\n  // first paint after a thread switch never shows the previous\n  // part's text (#4051). `displayedText` is already a prefix of\n  // `text` during normal streaming, so use it as the previous-text\n  // reference instead of carrying separate state — avoids the\n  // double render per streaming token. Read part identity through\n  // `useAuiState` so we actually subscribe to its changes instead\n  // of relying on a render-time proxy reference that may be stable\n  // across thread swaps.\n  const aui = useAui();\n  const part = useAuiState(() => aui.part);\n  const [prevPart, setPrevPart] = useState(part);\n  if (part !== prevPart || !text.startsWith(displayedText)) {\n    setPrevPart(part);\n    setDisplayedText(state.status.type === \"running\" ? \"\" : text);\n  }\n\n  const smoothStatusStore = useSmoothStatusStore({ optional: true });\n  const setText = useCallbackRef((text: string) => {\n    setDisplayedText(text);\n    if (smoothStatusStore) {\n      const target =\n        displayedText !== text || state.status.type === \"running\"\n          ? SMOOTH_STATUS\n          : state.status;\n      writableStore(smoothStatusStore).setState(target, true);\n    }\n  });\n\n  // TODO this is hacky\n  useEffect(() => {\n    if (smoothStatusStore) {\n      const target =\n        enabled && (displayedText !== text || state.status.type === \"running\")\n          ? SMOOTH_STATUS\n          : state.status;\n      writableStore(smoothStatusStore).setState(target, true);\n    }\n  }, [smoothStatusStore, enabled, text, displayedText, state.status]);\n\n  const [animatorRef] = useState<TextStreamAnimator>(\n    new TextStreamAnimator(displayedText, setText),\n  );\n\n  useEffect(() => {\n    animatorRef.drainMs = drainMs;\n    animatorRef.maxCharIntervalMs = maxCharIntervalMs;\n    animatorRef.maxCharsPerFrame = maxCharsPerFrame;\n    animatorRef.minCommitMs = minCommitMs;\n  }, [animatorRef, drainMs, maxCharIntervalMs, maxCharsPerFrame, minCommitMs]);\n\n  const animatorPartRef = useRef(part);\n  useEffect(() => {\n    if (!enabled) {\n      animatorRef.stop();\n      return;\n    }\n\n    const partChanged = animatorPartRef.current !== part;\n    animatorPartRef.current = part;\n    // A new part whose text shares a prefix with the previous target would\n    // keep the stale cursor and flicker without this reset.\n    if (partChanged || !text.startsWith(animatorRef.targetText)) {\n      if (state.status.type === \"running\") {\n        animatorRef.currentText = \"\";\n        animatorRef.targetText = text;\n        animatorRef.lastCommitTime = 0;\n        animatorRef.start();\n      } else {\n        animatorRef.currentText = text;\n        animatorRef.targetText = text;\n        animatorRef.stop();\n        setText(text);\n      }\n      return;\n    }\n\n    animatorRef.targetText = text;\n    if (state.status.type !== \"running\") {\n      // No character has painted. A pending frame that never runs would\n      // leave an empty bubble after settle.\n      if (animatorRef.currentText === \"\") {\n        animatorRef.currentText = text;\n        animatorRef.stop();\n        setText(text);\n        return;\n      }\n      animatorRef.start();\n      return;\n    }\n\n    animatorRef.start();\n  }, [animatorRef, enabled, text, state.status.type, part, setText]);\n\n  useEffect(() => {\n    return () => {\n      animatorRef.stop();\n    };\n  }, [animatorRef]);\n\n  return useMemo(\n    () =>\n      enabled\n        ? {\n            ...state,\n            text: displayedText,\n            status: text === displayedText ? state.status : SMOOTH_STATUS,\n          }\n        : state,\n    [enabled, displayedText, state, text],\n  );\n};\n"],"mappings":"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"}
+{"version":3,"file":"useSmooth.js","names":["useEffect","useMemo","useRef","useState","useAui","useAuiState","MessagePartStatus","ReasoningMessagePart","TextMessagePart","MessagePartState","useCallbackRef","useMediaQuery","useSmoothStatusStore","writableStore","SmoothOptions","drainMs","maxCharIntervalMs","maxCharsPerFrame","minCommitMs","DEFAULT_DRAIN_MS","DEFAULT_MAX_CHAR_INTERVAL_MS","TextStreamAnimator","animationFrameId","lastUpdateTime","lastCommitTime","Infinity","targetText","currentText","setText","newText","constructor","start","performance","now","animate","stop","cancelAnimationFrame","currentTime","deltaTime","timeToConsume","remainingChars","length","baseTimePerChar","Math","min","frameLimit","charsToAdd","requestAnimationFrame","slice","isComplete","SMOOTH_STATUS","Object","freeze","type","positiveOr","value","fallback","undefined","useSmooth","state","smooth","text","reduceMotion","options","enabled","displayedText","setDisplayedText","status","aui","part","prevPart","setPrevPart","startsWith","smoothStatusStore","optional","target","setState","animatorRef","animatorPartRef","partChanged","current"],"sources":["../../../src/utils/smooth/useSmooth.ts"],"sourcesContent":["\"use client\";\n\nimport { useEffect, useMemo, useRef, useState } from \"react\";\nimport { useAui, useAuiState } from \"@assistant-ui/store\";\nimport type {\n  MessagePartStatus,\n  ReasoningMessagePart,\n  TextMessagePart,\n  MessagePartState,\n} from \"@assistant-ui/core\";\nimport { useCallbackRef } from \"radix-ui/internal\";\nimport { useMediaQuery } from \"../hooks/useMediaQuery\";\nimport { useSmoothStatusStore } from \"./SmoothContext\";\nimport { writableStore } from \"../../context/ReadonlyStore\";\n\n/**\n * Tuning options for the smooth text streaming animation.\n */\nexport type SmoothOptions = {\n  /**\n   * Target time in milliseconds to drain the backlog of unrevealed\n   * characters. Larger values reveal long backlogs more gradually.\n   * @default 250\n   */\n  drainMs?: number | undefined;\n  /**\n   * Maximum time in milliseconds between revealed characters, i.e. the\n   * slowest reveal rate when the backlog is short.\n   * @default 5\n   */\n  maxCharIntervalMs?: number | undefined;\n  /**\n   * Maximum number of characters revealed per animation frame.\n   * @default Infinity\n   */\n  maxCharsPerFrame?: number | undefined;\n  /**\n   * Minimum time in milliseconds between committed updates. The reveal keeps\n   * advancing every frame, but the visible text (and the downstream re-render\n   * and markdown re-parse it triggers) is committed at most once per interval.\n   * The final frame always commits. `0` commits every frame.\n   * @default 0\n   */\n  minCommitMs?: number | undefined;\n};\n\nconst DEFAULT_DRAIN_MS = 250;\nconst DEFAULT_MAX_CHAR_INTERVAL_MS = 5;\n\nclass TextStreamAnimator {\n  private animationFrameId: number | null = null;\n  private lastUpdateTime: number = 0;\n  public lastCommitTime: number = -Infinity;\n\n  public targetText: string = \"\";\n  public drainMs: number = DEFAULT_DRAIN_MS;\n  public maxCharIntervalMs: number = DEFAULT_MAX_CHAR_INTERVAL_MS;\n  public maxCharsPerFrame: number = Infinity;\n  public minCommitMs: number = 0;\n\n  public currentText: string;\n  private setText: (newText: string) => void;\n\n  constructor(currentText: string, setText: (newText: string) => void) {\n    this.currentText = currentText;\n    this.setText = setText;\n  }\n\n  start() {\n    if (this.animationFrameId !== null) return;\n    this.lastUpdateTime = performance.now();\n    this.animate();\n  }\n\n  stop() {\n    if (this.animationFrameId !== null) {\n      cancelAnimationFrame(this.animationFrameId);\n      this.animationFrameId = null;\n    }\n  }\n\n  private animate = () => {\n    const currentTime = performance.now();\n    const deltaTime = currentTime - this.lastUpdateTime;\n    let timeToConsume = deltaTime;\n\n    const remainingChars = this.targetText.length - this.currentText.length;\n    const baseTimePerChar = Math.min(\n      this.maxCharIntervalMs,\n      this.drainMs / remainingChars,\n    );\n\n    const frameLimit = Math.min(remainingChars, this.maxCharsPerFrame);\n    let charsToAdd = 0;\n    while (timeToConsume >= baseTimePerChar && charsToAdd < frameLimit) {\n      charsToAdd++;\n      timeToConsume -= baseTimePerChar;\n    }\n    // A cap-limited frame must not bank its surplus time, or the next\n    // frame would burst past the cap.\n    if (charsToAdd === frameLimit && frameLimit === this.maxCharsPerFrame) {\n      timeToConsume = 0;\n    }\n\n    if (charsToAdd !== remainingChars) {\n      this.animationFrameId = requestAnimationFrame(this.animate);\n    } else {\n      this.animationFrameId = null;\n    }\n    if (charsToAdd === 0) return;\n\n    this.currentText = this.targetText.slice(\n      0,\n      this.currentText.length + charsToAdd,\n    );\n    this.lastUpdateTime = currentTime - timeToConsume;\n\n    const isComplete = charsToAdd === remainingChars;\n    if (isComplete || currentTime - this.lastCommitTime >= this.minCommitMs) {\n      this.lastCommitTime = currentTime;\n      this.setText(this.currentText);\n    }\n  };\n}\n\nconst SMOOTH_STATUS: MessagePartStatus = Object.freeze({\n  type: \"running\",\n});\n\nconst positiveOr = (value: number | undefined, fallback: number): number =>\n  value !== undefined && value > 0 ? value : fallback;\n\n/**\n * Animates streamed message part text with a typewriter-style reveal.\n *\n * Takes the current part state and a `smooth` argument: `false` disables,\n * `true` uses the default rate, and a {@link SmoothOptions} object tunes\n * the reveal. Returns the part state with `text` replaced by the revealed\n * prefix and `status` reporting `running` until the reveal catches up.\n * If the source settles before any character has been revealed, the text\n * is committed immediately so a missed animation frame cannot leave an\n * empty bubble.\n *\n * The reveal auto-disables under `prefers-reduced-motion: reduce`,\n * committing the full text immediately; this takes precedence over an\n * explicit `smooth={true}`.\n *\n * @example\n * ```tsx\n * const { text, status } = useSmooth(useMessagePartText(), {\n *   drainMs: 500,\n *   maxCharsPerFrame: 30,\n * });\n * ```\n */\nexport const useSmooth = (\n  state: MessagePartState & (TextMessagePart | ReasoningMessagePart),\n  smooth: boolean | SmoothOptions = false,\n): MessagePartState & (TextMessagePart | ReasoningMessagePart) => {\n  const { text } = state;\n  const reduceMotion = useMediaQuery(\"(prefers-reduced-motion: reduce)\");\n  const options =\n    typeof smooth === \"object\" && smooth !== null ? smooth : undefined;\n  const enabled = smooth !== false && smooth !== null && !reduceMotion;\n  const drainMs = positiveOr(options?.drainMs, DEFAULT_DRAIN_MS);\n  const maxCharIntervalMs = positiveOr(\n    options?.maxCharIntervalMs,\n    DEFAULT_MAX_CHAR_INTERVAL_MS,\n  );\n  const maxCharsPerFrame = positiveOr(options?.maxCharsPerFrame, Infinity);\n  const minCommitMs = positiveOr(options?.minCommitMs, 0);\n\n  const [displayedText, setDisplayedText] = useState(\n    state.status.type === \"running\" ? \"\" : text,\n  );\n\n  // Render-phase resync on part flip or text discontinuity, so the\n  // first paint after a thread switch never shows the previous\n  // part's text (#4051). `displayedText` is already a prefix of\n  // `text` during normal streaming, so use it as the previous-text\n  // reference instead of carrying separate state — avoids the\n  // double render per streaming token. Read part identity through\n  // `useAuiState` so we actually subscribe to its changes instead\n  // of relying on a render-time proxy reference that may be stable\n  // across thread swaps.\n  const aui = useAui();\n  const part = useAuiState(() => aui.part);\n  const [prevPart, setPrevPart] = useState(part);\n  if (part !== prevPart || !text.startsWith(displayedText)) {\n    setPrevPart(part);\n    setDisplayedText(state.status.type === \"running\" ? \"\" : text);\n  }\n\n  const smoothStatusStore = useSmoothStatusStore({ optional: true });\n  const setText = useCallbackRef((text: string) => {\n    setDisplayedText(text);\n    if (smoothStatusStore) {\n      const target =\n        displayedText !== text || state.status.type === \"running\"\n          ? SMOOTH_STATUS\n          : state.status;\n      writableStore(smoothStatusStore).setState(target, true);\n    }\n  });\n\n  // TODO this is hacky\n  useEffect(() => {\n    if (smoothStatusStore) {\n      const target =\n        enabled && (displayedText !== text || state.status.type === \"running\")\n          ? SMOOTH_STATUS\n          : state.status;\n      writableStore(smoothStatusStore).setState(target, true);\n    }\n  }, [smoothStatusStore, enabled, text, displayedText, state.status]);\n\n  const [animatorRef] = useState(\n    () => new TextStreamAnimator(displayedText, setText),\n  );\n\n  useEffect(() => {\n    animatorRef.drainMs = drainMs;\n    animatorRef.maxCharIntervalMs = maxCharIntervalMs;\n    animatorRef.maxCharsPerFrame = maxCharsPerFrame;\n    animatorRef.minCommitMs = minCommitMs;\n  }, [animatorRef, drainMs, maxCharIntervalMs, maxCharsPerFrame, minCommitMs]);\n\n  const animatorPartRef = useRef(part);\n  useEffect(() => {\n    if (!enabled) {\n      animatorRef.stop();\n      return;\n    }\n\n    const partChanged = animatorPartRef.current !== part;\n    animatorPartRef.current = part;\n    // A new part whose text shares a prefix with the previous target would\n    // keep the stale cursor and flicker without this reset.\n    if (partChanged || !text.startsWith(animatorRef.targetText)) {\n      if (state.status.type === \"running\") {\n        animatorRef.currentText = \"\";\n        animatorRef.targetText = text;\n        animatorRef.lastCommitTime = -Infinity;\n        animatorRef.start();\n      } else {\n        animatorRef.currentText = text;\n        animatorRef.targetText = text;\n        animatorRef.stop();\n        setText(text);\n      }\n      return;\n    }\n\n    animatorRef.targetText = text;\n    if (state.status.type !== \"running\") {\n      // No character has painted. A pending frame that never runs would\n      // leave an empty bubble after settle.\n      if (animatorRef.currentText === \"\") {\n        animatorRef.currentText = text;\n        animatorRef.stop();\n        setText(text);\n        return;\n      }\n      animatorRef.start();\n      return;\n    }\n\n    animatorRef.start();\n  }, [animatorRef, enabled, text, state.status.type, part, setText]);\n\n  useEffect(() => {\n    return () => {\n      animatorRef.stop();\n    };\n  }, [animatorRef]);\n\n  return useMemo(\n    () =>\n      enabled\n        ? {\n            ...state,\n            text: displayedText,\n            status: text === displayedText ? state.status : SMOOTH_STATUS,\n          }\n        : state,\n    [enabled, displayedText, state, text],\n  );\n};\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assistant-ui/react",
-  "version": "0.15.23",
+  "version": "0.15.25",
   "description": "Open-source TypeScript/React library for building production-grade AI chat experiences",
   "keywords": [
     "ai",
@@ -55,14 +55,14 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@assistant-ui/core": "^0.3.22",
-    "@assistant-ui/store": "^0.3.16",
-    "@assistant-ui/tap": "^0.9.20",
-    "assistant-cloud": "^0.2.4",
-    "assistant-stream": "^0.3.46",
+    "@assistant-ui/core": "^0.3.24",
+    "@assistant-ui/store": "^0.3.17",
+    "@assistant-ui/tap": "^0.9.21",
+    "assistant-cloud": "^0.2.5",
+    "assistant-stream": "^0.3.48",
     "radix-ui": "^1.6.7",
     "react-textarea-autosize": "^8.5.9",
-    "safe-content-frame": "^0.0.31",
+    "safe-content-frame": "^0.0.33",
     "zod": "^4.6.5",
     "zustand": "^5.0.15"
   },
@@ -81,18 +81,18 @@
     }
   },
   "devDependencies": {
-    "@assistant-ui/vite": "0.0.19",
-    "@assistant-ui/x-buildutils": "0.0.29",
+    "@assistant-ui/vite": "0.0.20",
+    "@assistant-ui/x-buildutils": "0.0.30",
     "@assistant-ui/x-react18": "0.0.0",
     "@testing-library/react": "^16.3.3",
     "@types/json-schema": "^7.0.15",
-    "@types/node": "^26.5.1",
+    "@types/node": "^26.6.3",
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",
     "jsdom": "^30.0.1",
     "react": "^19.3.0",
     "react-dom": "^19.3.0",
-    "vitest": "^5.0.1"
+    "vitest": "^5.0.3"
   },
   "publishConfig": {
     "access": "public",
@@ -110,6 +110,7 @@
   "scripts": {
     "build": "aui-build",
     "test": "vitest run",
+    "test:coverage": "vitest run --coverage --coverage.reporter=text --coverage.reporter=html --coverage.reporter=json-summary",
     "typecheck": "tsc --noEmit",
     "test:peer-react18": "vitest run --config vitest.peer-react18.config.ts",
     "test:watch": "vitest",

package/src/hooks/useToolCallElapsed.test.tsx

@@ -0,0 +1,35 @@
+// @vitest-environment jsdom
+
+import { renderToString } from "react-dom/server";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const { part } = vi.hoisted(() => ({
+  part: {
+    type: "tool-call" as const,
+    status: { type: "running" as const },
+    timing: { startedAt: 9000 },
+  },
+}));
+
+vi.mock("@assistant-ui/store", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("@assistant-ui/store")>()),
+  useAuiState: (
+    selector: (state: { optional: { part: typeof part } }) => unknown,
+  ) => selector({ optional: { part } }),
+}));
+
+import { useToolCallElapsed } from "./useToolCallElapsed";
+
+describe("useToolCallElapsed", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("does not read the wall clock during server render", () => {
+    const nowSpy = vi.spyOn(Date, "now");
+    const Probe = () => <span>{useToolCallElapsed() ?? "none"}</span>;
+
+    expect(renderToString(<Probe />)).toBe("<span>none</span>");
+    expect(nowSpy).not.toHaveBeenCalled();
+  });
+});

package/src/hooks/useToolCallElapsed.ts

@@ -1,6 +1,6 @@
 "use client";
 
-import { useEffect, useState } from "react";
+import { useLayoutEffect, useState } from "react";
 import { useAuiState } from "@assistant-ui/store";
 
 /**
@@ -10,7 +10,9 @@ import { useAuiState } from "@assistant-ui/store";
  * Reads `part.timing`. Returns `undefined` when the part is not a tool call,
  * carries no timing, ended without a recorded completion (the duration is
  * unknown), or when no message part scope is available (so kit components
- * stay renderable standalone, e.g. in docs previews).
+ * stay renderable standalone, e.g. in docs previews). A running call also
+ * returns `undefined` until the component mounts, so a server render never
+ * reads the clock.
  *
  * @example
  * ```tsx
@@ -32,12 +34,12 @@ export const useToolCallElapsed = (): number | undefined => {
   });
   const running =
     timing !== undefined && timing.completedAt === undefined && partRunning;
-  const [now, setNow] = useState(() => Date.now());
+  const [now, setNow] = useState<number | undefined>(undefined);
 
-  useEffect(() => {
+  useLayoutEffect(() => {
     if (!running) return undefined;
-    // The clock is an external source; this catches the elapsed value up before
-    // the interval takes over.
+    // The clock is read only after mount so a prerender never reads it; the
+    // layout effect still catches the elapsed value up before the first paint.
     // eslint-disable-next-line react-hooks/set-state-in-effect
     setNow(Date.now());
     const id = setInterval(() => setNow(Date.now()), 1000);
@@ -47,6 +49,6 @@ export const useToolCallElapsed = (): number | undefined => {
   if (timing === undefined) return undefined;
   if (timing.completedAt !== undefined)
     return Math.max(0, timing.completedAt - timing.startedAt);
-  if (!running) return undefined;
+  if (!running || now === undefined) return undefined;
   return Math.max(0, now - timing.startedAt);
 };

package/src/index.ts

@@ -333,6 +333,11 @@ export * as ThreadListItemMorePrimitive from "./primitives/threadListItemMore";
 export * as SelectionToolbarPrimitive from "./primitives/selectionToolbar";
 
 export { groupPartByType, type GroupByContext } from "@assistant-ui/core/react";
+export {
+  createThreadRowsSelector,
+  type ThreadRow,
+  type ThreadRowsOptions,
+} from "@assistant-ui/core/react";
 export { unstable_useThreadMessageIds } from "@assistant-ui/core/react";
 export { useMessagePartText } from "./primitives/messagePart/useMessagePartText";
 export { useMessagePartReasoning } from "./primitives/messagePart/useMessagePartReasoning";
@@ -375,8 +380,12 @@ export type {
   ToolApprovalDisplay,
   ToolApprovalOption,
   ToolApprovalOptionKind,
+  ToolApprovalAnswer,
+  ToolApprovalQuestion,
+  ToolApprovalQuestionOption,
   ToolApprovalResponse,
   ToolCallMessagePart,
+  MessagePartTiming,
   ToolCallTiming,
   ToolModelContentPart,
   MessageStatus,
@@ -494,16 +503,32 @@ export {
   useTriggerPopoverTriggers as unstable_useTriggerPopoverTriggers,
   useTriggerPopoverTriggersOptional as unstable_useTriggerPopoverTriggersOptional,
   type RegisteredTrigger as Unstable_RegisteredTrigger,
-  type TriggerMatch as Unstable_TriggerMatch,
-  type TriggerMatcher as Unstable_TriggerMatcher,
+  type TriggerMatch,
+  type TriggerMatcher,
   type TriggerBehavior as Unstable_TriggerBehavior,
 } from "./primitives/composer/trigger";
+import type {
+  TriggerMatch,
+  TriggerMatcher,
+} from "./primitives/composer/trigger";
+/** @deprecated Use `TriggerMatch` instead. */
+export type Unstable_TriggerMatch = TriggerMatch;
+/** @deprecated Use `TriggerMatcher` instead. */
+export type Unstable_TriggerMatcher = TriggerMatcher;
 export type {
+  DirectiveFormatter,
+  DirectiveSegment,
+  TriggerAdapter,
+  TriggerCategory,
+  TriggerItem,
   Unstable_DirectiveFormatter,
   Unstable_DirectiveSegment,
   Unstable_TriggerItem,
 } from "@assistant-ui/core";
-export { unstable_defaultDirectiveFormatter } from "@assistant-ui/core";
+export {
+  defaultDirectiveFormatter,
+  unstable_defaultDirectiveFormatter,
+} from "@assistant-ui/core";
 
 // Unstable - composer input history (terminal-style ArrowUp/ArrowDown recall)
 export {

package/src/model-context/makeAssistantVisible.test.tsx

@@ -8,6 +8,11 @@ import {
   type ChangeEvent,
 } from "react";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  mergeModelContexts,
+  type ModelContextProvider,
+} from "@assistant-ui/core";
+import type { Tool } from "assistant-stream";
 
 const { registerMock, auiMock } = vi.hoisted(() => {
   const register = vi.fn((_provider: unknown) => () => {});
@@ -30,10 +35,15 @@ type EditTool = {
   execute: (args: { editId: string; value: string }) => Promise<unknown>;
 };
 
-type ModelContextProvider = {
+type ClickTool = {
+  execute: (args: { clickId: string }) => Promise<unknown>;
+};
+
+type VisibleToolsProvider = {
   getModelContext: () => {
     tools: {
-      edit: EditTool;
+      edit?: EditTool;
+      click?: ClickTool;
     };
   };
 };
@@ -79,6 +89,36 @@ const ControlledTextarea = forwardRef<
   );
 });
 
+const Button = forwardRef<HTMLButtonElement, ComponentProps<"button">>(
+  (props, ref) => <button {...props} ref={ref} />,
+);
+
+const SplitRefButton = forwardRef<HTMLButtonElement, ComponentProps<"div">>(
+  ({ children, ...props }, ref) => (
+    <div {...props}>
+      <button ref={ref}>{children}</button>
+    </div>
+  ),
+);
+
+const getRegisteredTools = () => {
+  const provider = registerMock.mock.calls[0]![0] as VisibleToolsProvider;
+  return provider.getModelContext().tools;
+};
+
+const executeTool = (tool: Tool | undefined, args: Record<string, unknown>) => {
+  if (!tool?.execute) throw new Error("Missing executable tool");
+  return Promise.resolve(
+    tool.execute(args, {
+      toolCallId: "test-call",
+      abortSignal: new AbortController().signal,
+      human: async () => {
+        throw new Error("Unexpected human input request");
+      },
+    }),
+  );
+};
+
 const runEditTool = async (
   element: HTMLInputElement | HTMLTextAreaElement,
   value: string,
@@ -86,8 +126,9 @@ const runEditTool = async (
   const editId = element.dataset.editId;
   if (editId === undefined) throw new Error("Missing edit id");
 
-  const provider = registerMock.mock.calls[0]![0] as ModelContextProvider;
-  const task = provider.getModelContext().tools.edit.execute({
+  const edit = getRegisteredTools().edit;
+  if (!edit) throw new Error("Missing edit tool");
+  const task = edit.execute({
     editId,
     value,
   });
@@ -95,7 +136,7 @@ const runEditTool = async (
   await task;
 };
 
-describe("makeAssistantVisible editable components", () => {
+describe("makeAssistantVisible", () => {
   beforeEach(() => {
     registerMock.mockClear();
     vi.stubGlobal("CSS", { escape: (value: string) => value });
@@ -143,4 +184,273 @@ describe("makeAssistantVisible editable components", () => {
     expect(textarea.getAttribute("data-react-value")).toBe("updated");
     expect(onChange).toHaveBeenCalledOnce();
   });
+
+  it("preserves the default action settle delay", async () => {
+    const EditableInput = makeAssistantVisible(ControlledInput, {
+      editable: true,
+    });
+    const input = render(<EditableInput />).getByRole("textbox");
+    const editId = (input as HTMLInputElement).dataset.editId!;
+    const setTimeoutSpy = vi.spyOn(globalThis, "setTimeout");
+
+    expect(
+      (input as HTMLInputElement).dataset.actionSettleDelay,
+    ).toBeUndefined();
+
+    const task = getRegisteredTools().edit!.execute({
+      editId,
+      value: "updated",
+    });
+
+    expect(setTimeoutSpy).toHaveBeenCalledWith(expect.any(Function), 2000);
+    await vi.runAllTimersAsync();
+    await task;
+    setTimeoutSpy.mockRestore();
+  });
+
+  it("uses the default when the rendered settle delay is invalid", async () => {
+    const ClickableButton = makeAssistantVisible(Button, {
+      clickable: true,
+      settleDelayMs: 25,
+    });
+    const button = render(<ClickableButton>Run</ClickableButton>).getByRole(
+      "button",
+    );
+    const clickId = (button as HTMLButtonElement).dataset.clickId!;
+    (button as HTMLButtonElement).dataset.actionSettleDelay = "invalid";
+    const setTimeoutSpy = vi.spyOn(globalThis, "setTimeout");
+
+    const task = getRegisteredTools().click!.execute({ clickId });
+
+    expect(setTimeoutSpy).toHaveBeenCalledWith(expect.any(Function), 2000);
+    await vi.runAllTimersAsync();
+    await task;
+    setTimeoutSpy.mockRestore();
+  });
+
+  it.each(["", "   "])(
+    "uses the default for a blank rendered settle delay of %j",
+    async (renderedDelay) => {
+      const VisibleInput = makeAssistantVisible(ControlledInput, {
+        clickable: true,
+        editable: true,
+        settleDelayMs: 25,
+      });
+      const input = render(<VisibleInput />).getByRole("textbox");
+      const clickId = (input as HTMLInputElement).dataset.clickId!;
+      const editId = (input as HTMLInputElement).dataset.editId!;
+      const setTimeoutSpy = vi.spyOn(globalThis, "setTimeout");
+      input.dataset.actionSettleDelay = renderedDelay;
+
+      const clickTask = getRegisteredTools().click!.execute({ clickId });
+      expect(setTimeoutSpy).toHaveBeenLastCalledWith(
+        expect.any(Function),
+        2000,
+      );
+      await vi.runAllTimersAsync();
+      await clickTask;
+
+      setTimeoutSpy.mockClear();
+      const editTask = getRegisteredTools().edit!.execute({
+        editId,
+        value: "updated",
+      });
+      expect(setTimeoutSpy).toHaveBeenLastCalledWith(
+        expect.any(Function),
+        2000,
+      );
+      await vi.runAllTimersAsync();
+      await editTask;
+      setTimeoutSpy.mockRestore();
+    },
+  );
+
+  it("uses the configured settle delay for click actions", async () => {
+    const ClickableButton = makeAssistantVisible(Button, {
+      clickable: true,
+      settleDelayMs: 25,
+    });
+    const onClick = vi.fn();
+    const button = render(
+      <ClickableButton onClick={onClick}>Run</ClickableButton>,
+    ).getByRole("button");
+    const clickId = (button as HTMLButtonElement).dataset.clickId!;
+    const settled = vi.fn();
+
+    const task = getRegisteredTools().click!.execute({ clickId });
+    void task.then(settled);
+
+    expect(onClick).toHaveBeenCalledOnce();
+    await vi.advanceTimersByTimeAsync(24);
+    expect(settled).not.toHaveBeenCalled();
+
+    await vi.advanceTimersByTimeAsync(1);
+    await task;
+    expect(settled).toHaveBeenCalledOnce();
+  });
+
+  it("uses the action id when the forwarded ref targets a child", async () => {
+    const ClickableButton = makeAssistantVisible(SplitRefButton, {
+      clickable: true,
+      settleDelayMs: 25,
+    });
+    const onClick = vi.fn();
+    const view = render(
+      <ClickableButton data-testid="action" onClick={onClick}>
+        Run
+      </ClickableButton>,
+    );
+    const action = view.getByTestId("action");
+    const clickId = action.dataset.clickId!;
+    const settled = vi.fn();
+
+    const task = getRegisteredTools().click!.execute({ clickId });
+    void task.then(settled);
+
+    expect(onClick).toHaveBeenCalledOnce();
+    await vi.advanceTimersByTimeAsync(24);
+    expect(settled).not.toHaveBeenCalled();
+
+    await vi.advanceTimersByTimeAsync(1);
+    await task;
+    expect(settled).toHaveBeenCalledOnce();
+  });
+
+  it("shares tools across wrappers while keeping per-element delays", async () => {
+    const SlowButton = makeAssistantVisible(Button, {
+      clickable: true,
+      editable: true,
+      settleDelayMs: 25,
+    });
+    const ImmediateButton = makeAssistantVisible(Button, {
+      clickable: true,
+      editable: true,
+      settleDelayMs: 0,
+    });
+    const view = render(
+      <>
+        <SlowButton>Slow</SlowButton>
+        <ImmediateButton>Immediate</ImmediateButton>
+      </>,
+    );
+    const providers = registerMock.mock.calls.map(
+      ([provider]) => provider as ModelContextProvider,
+    );
+    const mergedContext = mergeModelContexts(new Set(providers));
+
+    expect(mergedContext.tools?.click).toBe(
+      providers[0]!.getModelContext().tools?.click,
+    );
+    expect(mergedContext.tools?.click).toBe(
+      providers[1]!.getModelContext().tools?.click,
+    );
+    expect(mergedContext.tools?.edit).toBe(
+      providers[0]!.getModelContext().tools?.edit,
+    );
+    expect(mergedContext.tools?.edit).toBe(
+      providers[1]!.getModelContext().tools?.edit,
+    );
+
+    const [slowButton, immediateButton] = view.getAllByRole("button");
+    const click = mergedContext.tools!.click!;
+    const slowTask = executeTool(click, {
+      clickId: (slowButton as HTMLButtonElement).dataset.clickId!,
+    });
+    const immediateTask = executeTool(click, {
+      clickId: (immediateButton as HTMLButtonElement).dataset.clickId!,
+    });
+
+    await immediateTask;
+    let slowSettled = false;
+    void slowTask.then(() => {
+      slowSettled = true;
+    });
+    await vi.advanceTimersByTimeAsync(24);
+    expect(slowSettled).toBe(false);
+    await vi.advanceTimersByTimeAsync(1);
+    await slowTask;
+  });
+
+  it("shares the edit tool across wrappers while keeping per-element delays", async () => {
+    const SlowInput = makeAssistantVisible(ControlledInput, {
+      editable: true,
+      settleDelayMs: 25,
+    });
+    const ImmediateInput = makeAssistantVisible(ControlledInput, {
+      editable: true,
+      settleDelayMs: 0,
+    });
+    const view = render(
+      <>
+        <SlowInput aria-label="Slow" />
+        <ImmediateInput aria-label="Immediate" />
+      </>,
+    );
+    const providers = registerMock.mock.calls.map(
+      ([provider]) => provider as ModelContextProvider,
+    );
+    const mergedContext = mergeModelContexts(new Set(providers));
+
+    expect(mergedContext.tools?.edit).toBe(
+      providers[0]!.getModelContext().tools?.edit,
+    );
+    expect(mergedContext.tools?.edit).toBe(
+      providers[1]!.getModelContext().tools?.edit,
+    );
+
+    const slowInput = view.getByRole("textbox", { name: "Slow" });
+    const immediateInput = view.getByRole("textbox", { name: "Immediate" });
+    const edit = mergedContext.tools!.edit!;
+    const slowTask = executeTool(edit, {
+      editId: (slowInput as HTMLInputElement).dataset.editId!,
+      value: "slow update",
+    });
+    const immediateTask = executeTool(edit, {
+      editId: (immediateInput as HTMLInputElement).dataset.editId!,
+      value: "immediate update",
+    });
+
+    await immediateTask;
+    expect(immediateInput).toHaveProperty("value", "immediate update");
+    let slowSettled = false;
+    void slowTask.then(() => {
+      slowSettled = true;
+    });
+    await vi.advanceTimersByTimeAsync(24);
+    expect(slowSettled).toBe(false);
+
+    await vi.advanceTimersByTimeAsync(1);
+    await slowTask;
+    expect(slowInput).toHaveProperty("value", "slow update");
+  });
+
+  it("allows the action settle delay to be disabled", async () => {
+    const EditableInput = makeAssistantVisible(ControlledInput, {
+      editable: true,
+      settleDelayMs: 0,
+    });
+    const input = render(<EditableInput />).getByRole("textbox");
+    const editId = (input as HTMLInputElement).dataset.editId!;
+    const timersBefore = vi.getTimerCount();
+
+    const task = getRegisteredTools().edit!.execute({
+      editId,
+      value: "updated",
+    });
+
+    expect(vi.getTimerCount()).toBe(timersBefore);
+    await task;
+    expect(input).toHaveProperty("value", "updated");
+  });
+
+  it.each([-1, Number.NaN, Number.POSITIVE_INFINITY, 2_147_483_648])(
+    "rejects an invalid action settle delay of %s",
+    (settleDelayMs) => {
+      expect(() =>
+        makeAssistantVisible(Button, { clickable: true, settleDelayMs }),
+      ).toThrow(
+        new RangeError("settleDelayMs must be between 0 and 2147483647"),
+      );
+    },
+  );
 });