@athenaintel/react 0.23.2 → 0.24.0

package/dist/chat-ui/thread/statewire-history-edge.js

@@ -1,24 +1,9 @@
 import { jsx } from "react/jsx-runtime";
 import { useAuiState } from "@assistant-ui/react";
-import "../../packages/agent-runtime/src/generated/runconfig-contract.js";
 import { useState, useRef, useEffect, useLayoutEffect } from "react";
-import "@assistant-ui/tap";
-import "statewire";
-import { isStatewireChannelTeardown } from "../../packages/agent-runtime/src/errors.js";
-import "../../packages/agent-runtime/src/statewire-suspended.js";
-import "../../packages/agent-runtime/src/conversation-list.js";
-import "@tanstack/react-query";
-import "../../packages/agent-runtime/src/statewire-state.js";
-import "../../packages/agent-runtime/src/messages.js";
-import { useDeepAgentWindowSync } from "../../packages/agent-runtime/src/use-deep-agent-window-sync.js";
-import "@assistant-ui/store";
-import "../../packages/agent-runtime/src/quota-safe-local-storage-session.js";
-import "../../packages/agent-runtime/src/statewire-attach-observer.js";
-import "../../packages/agent-runtime/src/thread-status.js";
-import "@assistant-ui/react-statewire";
-import "@assistant-ui/core";
-import "../../packages/agent-runtime/src/thread-handoff.js";
 import { useStatewireToolOutputs } from "../../provider/statewire-window-context.js";
+import { useDeepAgentWindowSync } from "../../packages/agent-runtime/src/use-deep-agent-window-sync.js";
+import { isStatewireChannelTeardown } from "../../packages/agent-runtime/src/errors.js";
 import { cn } from "cnfast";
 const THREAD_VIEWPORT_ATTR = "data-aui-thread-viewport";
 const HISTORY_EDGE_NEAR_MARGIN_PX = 1500;

package/dist/chat-ui/thread/statewire-history-edge.js.map

@@ -1 +1 @@
-{"version":3,"file":"statewire-history-edge.js","sources":["../../../src/chat-ui/thread/statewire-history-edge.tsx"],"sourcesContent":["import { useAuiState } from \"@assistant-ui/react\";\nimport {\n  type DeepAgentHistoryLoadEvent,\n  type DeepAgentToolOutputStore,\n  isStatewireChannelTeardown,\n  useDeepAgentWindowSync,\n} from \"@athenaintel/agent-runtime\";\nimport type { FC } from \"react\";\nimport { useEffect, useLayoutEffect, useRef, useState } from \"react\";\nimport { cn } from \"../../lib/utils\";\nimport { useStatewireToolOutputs } from \"../../provider/statewire-window-context\";\n\n/** The attribute `ChatThreadShell` stamps on the scroll viewport. */\nexport const THREAD_VIEWPORT_ATTR = \"data-aui-thread-viewport\";\n\n/**\n * How far above the viewport the edge row counts as near: the row sits above\n * the first loaded message, so reaching it means the user has scrolled past\n * everything loaded and the next page should already be on its way.\n */\nexport const HISTORY_EDGE_NEAR_MARGIN_PX = 1500;\n\nexport interface HistoryEdgeRowProps {\n  /** Whether the server holds messages older than the loaded window. */\n  hasOlder: boolean;\n  /** Whether the next page can be asked for; `false` with `hasOlder` is the connection's loading depth spent. Defaults to `hasOlder`. */\n  canLoadOlder?: boolean;\n  /** A page of older history is in flight. */\n  loading: boolean;\n  onLoadOlder: () => void;\n  className?: string;\n  /** The row element, for the viewport observer. */\n  rowRef?: (element: HTMLElement | null) => void;\n}\n\n/**\n * The top edge of the LOADED history: a manual way to load the next page of\n * older messages, and the in-flight state. Renders nothing when the whole\n * transcript is loaded (or the head interest has not resolved).\n */\nexport const HistoryEdgeRow: FC<HistoryEdgeRowProps> = ({\n  hasOlder,\n  canLoadOlder = hasOlder,\n  loading,\n  onLoadOlder,\n  className,\n  rowRef,\n}) => {\n  if (!hasOlder) return null;\n  return (\n    <div\n      ref={rowRef}\n      data-testid=\"thread-history-edge\"\n      className={cn(\n        \"flex w-full max-w-(--thread-max-width) items-center justify-center py-1 text-xs text-muted-foreground\",\n        className,\n      )}\n    >\n      {loading ? (\n        <span data-testid=\"thread-history-edge-loading\">Loading earlier messages…</span>\n      ) : canLoadOlder ? (\n        <button\n          type=\"button\"\n          data-testid=\"thread-history-edge-load\"\n          onClick={onLoadOlder}\n          className=\"rounded-lg px-2.5 py-1 text-xs font-medium text-muted-foreground transition-colors hover:bg-accent hover:text-foreground\"\n        >\n          Load earlier messages\n        </button>\n      ) : (\n        <span data-testid=\"thread-history-edge-limit\">Earlier messages can't be loaded here</span>\n      )}\n    </div>\n  );\n};\n\nexport interface StatewireHistoryEdgeProps {\n  /**\n   * The thread's tool-output store (the one its converter substitutes from).\n   * Defaults to `AthenaProvider`'s; hosts mounting the runtime themselves pass\n   * the store they gave `useDeepAgentRuntime({ toolOutputs })`.\n   */\n  toolOutputs?: DeepAgentToolOutputStore;\n  className?: string;\n  /** A page interest resolved (telemetry). */\n  onHistoryLoad?: (event: DeepAgentHistoryLoadEvent) => void;\n}\n\n/**\n * The client half of the interest window for a DOM thread — mounted once per\n * thread, inside the scroll viewport above the messages (`ChatThreadShell`'s\n * `beforeMessages` slot):\n *\n * - renders the \"Load earlier messages\" edge row and loads the next page when\n *   the row comes near the viewport (scrolling up) or on its button, keeping\n *   the reading position when the page lands above the view;\n * - fetches cut tool outputs whole for the rendered cards, so they re-render\n *   complete through the converter (`toolOutputs`).\n *\n * Inert until the head interest resolves: no row, no reads.\n */\nexport const StatewireHistoryEdge: FC<StatewireHistoryEdgeProps> = ({\n  toolOutputs: toolOutputsProp,\n  className,\n  onHistoryLoad,\n}) => {\n  const providerToolOutputs = useStatewireToolOutputs();\n  const toolOutputs = toolOutputsProp ?? providerToolOutputs ?? undefined;\n  const messages = useAuiState((s) => s.thread.messages);\n  const [nearTop, setNearTop] = useState(false);\n  const [nearTopEpoch, setNearTopEpoch] = useState(0);\n  const nearTopRef = useRef(false);\n  const [rowEl, setRowEl] = useState<HTMLElement | null>(null);\n  const { hasOlder, canLoadOlder, loading, loadOlder } = useDeepAgentWindowSync({\n    messages,\n    toolOutputs,\n    nearTop,\n    nearTopEpoch,\n    onHistoryLoad,\n    onError: (error, command) => {\n      // Leaving the thread settles an in-flight read as lost: lifecycle, not a failure.\n      if (error instanceof Error && isStatewireChannelTeardown(error)) return;\n      console.warn(`[StatewireHistoryEdge] ${command} failed:`, error);\n    },\n  });\n\n  // The row's own visibility is the near-top level: a level, not an edge, so\n  // pages chain while the user stays at the top and stop once the prepended\n  // content has pushed the row away again.\n  useEffect(() => {\n    if (!rowEl || !hasOlder || typeof IntersectionObserver === \"undefined\") return;\n    const observer = new IntersectionObserver(\n      (entries) => {\n        for (const entry of entries) {\n          const near = entry.isIntersecting;\n          if (nearTopRef.current === near) continue;\n          nearTopRef.current = near;\n          setNearTop(near);\n          if (near) setNearTopEpoch((epoch) => epoch + 1);\n        }\n      },\n      {\n        root: rowEl.closest<HTMLElement>(`[${THREAD_VIEWPORT_ATTR}]`),\n        rootMargin: `${HISTORY_EDGE_NEAR_MARGIN_PX}px 0px`,\n      },\n    );\n    observer.observe(rowEl);\n    return () => {\n      observer.disconnect();\n      nearTopRef.current = false;\n      setNearTop(false);\n    };\n  }, [rowEl, hasOlder]);\n\n  // A prepend (older history landing) keeps the reading position: the\n  // viewport scrolls by the height the page added above the view, so the\n  // message the user was on stays put. The pre-prepend height is measured\n  // only while a page is in flight (a layout read per render would force a\n  // reflow on every streamed token otherwise).\n  const shapeRef = useRef<{ firstId: string | undefined; length: number; scrollHeight: number } | null>(\n    null,\n  );\n  const firstId = messages[0]?.id;\n  const length = messages.length;\n  useLayoutEffect(() => {\n    const viewport = rowEl?.closest<HTMLElement>(`[${THREAD_VIEWPORT_ATTR}]`) ?? null;\n    const prev = shapeRef.current;\n    const prepended =\n      viewport !== null &&\n      prev !== null &&\n      prev.firstId !== undefined &&\n      firstId !== prev.firstId &&\n      length > prev.length;\n    if (prepended) viewport.scrollTop += viewport.scrollHeight - prev.scrollHeight;\n    shapeRef.current =\n      loading || prepended || prev === null\n        ? { firstId, length, scrollHeight: viewport?.scrollHeight ?? 0 }\n        : { firstId, length, scrollHeight: prev.scrollHeight };\n  });\n\n  return (\n    <HistoryEdgeRow\n      rowRef={setRowEl}\n      hasOlder={hasOlder}\n      canLoadOlder={canLoadOlder}\n      loading={loading}\n      onLoadOlder={loadOlder}\n      className={className}\n    />\n  );\n};\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"statewire-history-edge.js","sources":["../../../src/chat-ui/thread/statewire-history-edge.tsx"],"sourcesContent":["import { useAuiState } from \"@assistant-ui/react\";\nimport {\n  type DeepAgentHistoryLoadEvent,\n  type DeepAgentToolOutputStore,\n  isStatewireChannelTeardown,\n  useDeepAgentWindowSync,\n} from \"@athenaintel/agent-runtime\";\nimport type { FC } from \"react\";\nimport { useEffect, useLayoutEffect, useRef, useState } from \"react\";\nimport { cn } from \"../../lib/utils\";\nimport { useStatewireToolOutputs } from \"../../provider/statewire-window-context\";\n\n/** The attribute `ChatThreadShell` stamps on the scroll viewport. */\nexport const THREAD_VIEWPORT_ATTR = \"data-aui-thread-viewport\";\n\n/**\n * How far above the viewport the edge row counts as near: the row sits above\n * the first loaded message, so reaching it means the user has scrolled past\n * everything loaded and the next page should already be on its way.\n */\nexport const HISTORY_EDGE_NEAR_MARGIN_PX = 1500;\n\nexport interface HistoryEdgeRowProps {\n  /** Whether the server holds messages older than the loaded window. */\n  hasOlder: boolean;\n  /** Whether the next page can be asked for; `false` with `hasOlder` is the connection's loading depth spent. Defaults to `hasOlder`. */\n  canLoadOlder?: boolean;\n  /** A page of older history is in flight. */\n  loading: boolean;\n  onLoadOlder: () => void;\n  className?: string;\n  /** The row element, for the viewport observer. */\n  rowRef?: (element: HTMLElement | null) => void;\n}\n\n/**\n * The top edge of the LOADED history: a manual way to load the next page of\n * older messages, and the in-flight state. Renders nothing when the whole\n * transcript is loaded (or the head interest has not resolved).\n */\nexport const HistoryEdgeRow: FC<HistoryEdgeRowProps> = ({\n  hasOlder,\n  canLoadOlder = hasOlder,\n  loading,\n  onLoadOlder,\n  className,\n  rowRef,\n}) => {\n  if (!hasOlder) return null;\n  return (\n    <div\n      ref={rowRef}\n      data-testid=\"thread-history-edge\"\n      className={cn(\n        \"flex w-full max-w-(--thread-max-width) items-center justify-center py-1 text-xs text-muted-foreground\",\n        className,\n      )}\n    >\n      {loading ? (\n        <span data-testid=\"thread-history-edge-loading\">Loading earlier messages…</span>\n      ) : canLoadOlder ? (\n        <button\n          type=\"button\"\n          data-testid=\"thread-history-edge-load\"\n          onClick={onLoadOlder}\n          className=\"rounded-lg px-2.5 py-1 text-xs font-medium text-muted-foreground transition-colors hover:bg-accent hover:text-foreground\"\n        >\n          Load earlier messages\n        </button>\n      ) : (\n        <span data-testid=\"thread-history-edge-limit\">Earlier messages can't be loaded here</span>\n      )}\n    </div>\n  );\n};\n\nexport interface StatewireHistoryEdgeProps {\n  /**\n   * The thread's tool-output store (the one its converter substitutes from).\n   * Defaults to `AthenaProvider`'s; hosts mounting the runtime themselves pass\n   * the store they gave `useDeepAgentRuntime({ toolOutputs })`.\n   */\n  toolOutputs?: DeepAgentToolOutputStore;\n  className?: string;\n  /** A page interest resolved (telemetry). */\n  onHistoryLoad?: (event: DeepAgentHistoryLoadEvent) => void;\n}\n\n/**\n * The client half of the interest window for a DOM thread — mounted once per\n * thread, inside the scroll viewport above the messages (`ChatThreadShell`'s\n * `beforeMessages` slot):\n *\n * - renders the \"Load earlier messages\" edge row and loads the next page when\n *   the row comes near the viewport (scrolling up) or on its button, keeping\n *   the reading position when the page lands above the view;\n * - fetches cut tool outputs whole for the rendered cards, so they re-render\n *   complete through the converter (`toolOutputs`).\n *\n * Inert until the head interest resolves: no row, no reads.\n */\nexport const StatewireHistoryEdge: FC<StatewireHistoryEdgeProps> = ({\n  toolOutputs: toolOutputsProp,\n  className,\n  onHistoryLoad,\n}) => {\n  const providerToolOutputs = useStatewireToolOutputs();\n  const toolOutputs = toolOutputsProp ?? providerToolOutputs ?? undefined;\n  const messages = useAuiState((s) => s.thread.messages);\n  const [nearTop, setNearTop] = useState(false);\n  const [nearTopEpoch, setNearTopEpoch] = useState(0);\n  const nearTopRef = useRef(false);\n  const [rowEl, setRowEl] = useState<HTMLElement | null>(null);\n  const { hasOlder, canLoadOlder, loading, loadOlder } = useDeepAgentWindowSync({\n    messages,\n    toolOutputs,\n    nearTop,\n    nearTopEpoch,\n    onHistoryLoad,\n    onError: (error, command) => {\n      // Leaving the thread settles an in-flight read as lost: lifecycle, not a failure.\n      if (error instanceof Error && isStatewireChannelTeardown(error)) return;\n      console.warn(`[StatewireHistoryEdge] ${command} failed:`, error);\n    },\n  });\n\n  // The row's own visibility is the near-top level: a level, not an edge, so\n  // pages chain while the user stays at the top and stop once the prepended\n  // content has pushed the row away again.\n  useEffect(() => {\n    if (!rowEl || !hasOlder || typeof IntersectionObserver === \"undefined\") return;\n    const observer = new IntersectionObserver(\n      (entries) => {\n        for (const entry of entries) {\n          const near = entry.isIntersecting;\n          if (nearTopRef.current === near) continue;\n          nearTopRef.current = near;\n          setNearTop(near);\n          if (near) setNearTopEpoch((epoch) => epoch + 1);\n        }\n      },\n      {\n        root: rowEl.closest<HTMLElement>(`[${THREAD_VIEWPORT_ATTR}]`),\n        rootMargin: `${HISTORY_EDGE_NEAR_MARGIN_PX}px 0px`,\n      },\n    );\n    observer.observe(rowEl);\n    return () => {\n      observer.disconnect();\n      nearTopRef.current = false;\n      setNearTop(false);\n    };\n  }, [rowEl, hasOlder]);\n\n  // A prepend (older history landing) keeps the reading position: the\n  // viewport scrolls by the height the page added above the view, so the\n  // message the user was on stays put. The pre-prepend height is measured\n  // only while a page is in flight (a layout read per render would force a\n  // reflow on every streamed token otherwise).\n  const shapeRef = useRef<{ firstId: string | undefined; length: number; scrollHeight: number } | null>(\n    null,\n  );\n  const firstId = messages[0]?.id;\n  const length = messages.length;\n  useLayoutEffect(() => {\n    const viewport = rowEl?.closest<HTMLElement>(`[${THREAD_VIEWPORT_ATTR}]`) ?? null;\n    const prev = shapeRef.current;\n    const prepended =\n      viewport !== null &&\n      prev !== null &&\n      prev.firstId !== undefined &&\n      firstId !== prev.firstId &&\n      length > prev.length;\n    if (prepended) viewport.scrollTop += viewport.scrollHeight - prev.scrollHeight;\n    shapeRef.current =\n      loading || prepended || prev === null\n        ? { firstId, length, scrollHeight: viewport?.scrollHeight ?? 0 }\n        : { firstId, length, scrollHeight: prev.scrollHeight };\n  });\n\n  return (\n    <HistoryEdgeRow\n      rowRef={setRowEl}\n      hasOlder={hasOlder}\n      canLoadOlder={canLoadOlder}\n      loading={loading}\n      onLoadOlder={loadOlder}\n      className={className}\n    />\n  );\n};\n"],"names":[],"mappings":"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"}

package/dist/composer/composer-handoff.cjs

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const react$1 = require("react");
+const react = require("@assistant-ui/react");
+const athenaDiagnostics = require("../diagnostics/athena-diagnostics.cjs");
+const errors = require("../diagnostics/errors.cjs");
+const statewireThreadList = require("../threads/statewire-thread-list.cjs");
+function createComposerHandoffStore() {
+  return { pending: [], focusOnNextMirror: false, focusEnd: null };
+}
+const ComposerHandoffContext = react$1.createContext(null);
+function useComposerHandoffStore() {
+  return react$1.useContext(ComposerHandoffContext);
+}
+function useComposerReady() {
+  const list = statewireThreadList.useAthenaStatewireThreadList();
+  const threadLoading = react.useAuiState((s) => {
+    var _a;
+    return ((_a = s.optional.thread) == null ? void 0 : _a.isLoading) ?? false;
+  });
+  return !((list == null ? void 0 : list.isLoading) ?? false) && !threadLoading;
+}
+function mergeComposerDraft({
+  current,
+  write
+}) {
+  if (write.replace || !current) return write.text;
+  return `${current}
+${write.text}`;
+}
+function applyComposerWrite({
+  target,
+  store,
+  write
+}) {
+  var _a;
+  const current = target.composer.getState().text ?? "";
+  const next = mergeComposerDraft({ current, write });
+  target.composer.setText(next);
+  if (write.focus && store) {
+    if (next === current) (_a = store.focusEnd) == null ? void 0 : _a.call(store);
+    else store.focusOnNextMirror = true;
+  }
+  athenaDiagnostics.athenaDiagnostics.emit("composer.handoff", {
+    level: "debug",
+    data: { phase: "applied", send: write.send, focus: write.focus, chars: next.length }
+  });
+  if (write.send) {
+    return Promise.resolve(target.composer.send({ steer: false })).then(() => void 0);
+  }
+  return void 0;
+}
+function queueComposerWrite({
+  store,
+  write
+}) {
+  const last = store.pending[store.pending.length - 1];
+  const foldable = last !== void 0 && !last.send && !write.send && !write.replace && last.threadId === write.threadId && last.resolve === void 0 && write.resolve === void 0;
+  if (foldable) {
+    last.text = mergeComposerDraft({ current: last.text, write });
+    last.focus = last.focus || write.focus;
+  } else {
+    store.pending.push(write);
+  }
+  athenaDiagnostics.athenaDiagnostics.emit("composer.handoff", {
+    level: "debug",
+    data: { phase: "deferred", send: write.send, focus: write.focus, queued: store.pending.length }
+  });
+}
+function dropWrite({ write, reason }) {
+  var _a;
+  const error = new errors.AthenaSdkError({
+    code: "composer_write_dropped",
+    message: `A composer ${write.send ? "send" : "draft"} queued before the chat was ready was dropped: ${reason}.`,
+    hint: "Make the write again from the chat that is active now.",
+    context: { threadId: write.threadId, send: write.send }
+  });
+  athenaDiagnostics.athenaDiagnostics.emit("composer.handoff", {
+    level: "warn",
+    error,
+    data: { phase: "dropped", send: write.send, reason, threadId: write.threadId }
+  });
+  (_a = write.reject) == null ? void 0 : _a.call(write, error);
+}
+function drainComposerHandoff({
+  store,
+  target,
+  threadId
+}) {
+  var _a;
+  const writes = store.pending;
+  if (writes.length === 0) return;
+  store.pending = [];
+  for (const write of writes) {
+    if (write.threadId !== null && threadId !== null && write.threadId !== threadId) {
+      dropWrite({ write, reason: `it was made for thread ${write.threadId}, thread ${threadId} is active` });
+      continue;
+    }
+    const outcome = applyComposerWrite({ target, store, write });
+    (_a = write.resolve) == null ? void 0 : _a.call(write, outcome);
+  }
+}
+function clearComposerHandoff({
+  store,
+  reason
+}) {
+  const writes = store.pending;
+  if (writes.length === 0) return;
+  store.pending = [];
+  for (const write of writes) dropWrite({ write, reason });
+}
+exports.ComposerHandoffContext = ComposerHandoffContext;
+exports.applyComposerWrite = applyComposerWrite;
+exports.clearComposerHandoff = clearComposerHandoff;
+exports.createComposerHandoffStore = createComposerHandoffStore;
+exports.drainComposerHandoff = drainComposerHandoff;
+exports.mergeComposerDraft = mergeComposerDraft;
+exports.queueComposerWrite = queueComposerWrite;
+exports.useComposerHandoffStore = useComposerHandoffStore;
+exports.useComposerReady = useComposerReady;
+//# sourceMappingURL=composer-handoff.cjs.map

package/dist/composer/composer-handoff.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"composer-handoff.cjs","sources":["../../src/composer/composer-handoff.ts"],"sourcesContent":["/**\n * Composer handoff: writes to the chat composer from host UI that lives\n * outside `<AthenaChat>` (a sidebar, an agenda card, a workflow button).\n *\n * Two problems it solves for `useAppendToComposer` / `useSendMessage`:\n *\n * 1. A write before the chat is ready is lost. While the thread list is still\n *    resolving the active thread, or the thread's history is still loading,\n *    the composer the hooks write to belongs to a mount that is about to be\n *    replaced (thread-list mode keys the statewire subtree by thread), and\n *    the draft goes with it. The store below lives ABOVE that mount, so a\n *    write made too early waits here and the ready mount drains it.\n * 2. A prefilled draft should put the caret after the text so the user can\n *    keep typing or dictating. The Tiptap editor mirrors runtime text on a\n *    later tick; the `focusOnNextMirror` flag asks it to focus at the end\n *    right after that mirror lands, instead of the host guessing a delay.\n *\n * Every queued write is bound to the statewire thread it was made for and\n * drains only into that thread's mount; a thread switch, an identity change\n * or a provider unmount drops what waits with a `composer_write_dropped`\n * error, never into another user's or another thread's composer.\n */\nimport { createContext, useContext } from 'react';\nimport { useAuiState } from '@assistant-ui/react';\nimport { athenaDiagnostics } from '../diagnostics/athena-diagnostics';\nimport { AthenaSdkError } from '../diagnostics/errors';\nimport { useAthenaStatewireThreadList } from '../threads/statewire-thread-list';\n\n/** The slice of the assistant-ui client the handoff writes to. */\nexport interface ComposerTarget {\n  composer: {\n    getState: () => { text: string };\n    setText: (text: string) => void;\n    send: (options?: { steer?: boolean }) => unknown;\n  };\n}\n\nexport interface ComposerWrite {\n  text: string;\n  /** Replace the draft instead of appending on a new line. */\n  replace: boolean;\n  /** Submit right after writing. */\n  send: boolean;\n  /** Put the caret at the end of the draft once the editor shows it. */\n  focus: boolean;\n  /** The statewire thread the write was made for; it drains only into that thread's mount. */\n  threadId: string | null;\n  /** Settled once the write has been applied (and, for `send`, with the send's outcome). */\n  resolve?: (outcome: Promise<void> | void) => void;\n  /** Settled with `composer_write_dropped` when the write can no longer land. */\n  reject?: (error: AthenaSdkError) => void;\n}\n\nexport interface ComposerHandoffStore {\n  /** Writes waiting for a ready composer, oldest first. Adjacent plain appends fold together. */\n  pending: ComposerWrite[];\n  /** Set by a `focus` write; the editor consumes it after mirroring the draft. */\n  focusOnNextMirror: boolean;\n  /** Registered by the mounted editor: place the caret at the end of the draft. */\n  focusEnd: (() => void) | null;\n}\n\nexport function createComposerHandoffStore(): ComposerHandoffStore {\n  return { pending: [], focusOnNextMirror: false, focusEnd: null };\n}\n\nexport const ComposerHandoffContext = createContext<ComposerHandoffStore | null>(null);\n\n/** The provider's handoff store, or null outside `AthenaProvider`. */\nexport function useComposerHandoffStore(): ComposerHandoffStore | null {\n  return useContext(ComposerHandoffContext);\n}\n\n/**\n * Whether a composer write lands now: in thread-list mode the list has\n * resolved which thread is active, and that thread's history has loaded.\n * Until then the composer the hooks write to is the one of a mount that is\n * about to be replaced, and the draft goes with it.\n *\n * Deliberately not the socket status: a never-started chat sits in\n * `standby` until its first send and must still take a prefill.\n */\nexport function useComposerReady(): boolean {\n  const list = useAthenaStatewireThreadList();\n  const threadLoading = useAuiState((s) => s.optional.thread?.isLoading ?? false);\n  return !(list?.isLoading ?? false) && !threadLoading;\n}\n\n/** The draft after `write`: `replace` (or an empty draft) takes the text as is. */\nexport function mergeComposerDraft({\n  current,\n  write,\n}: {\n  current: string;\n  write: Pick<ComposerWrite, 'text' | 'replace'>;\n}): string {\n  if (write.replace || !current) return write.text;\n  return `${current}\\n${write.text}`;\n}\n\n/**\n * Write into the live composer. Returns the send's outcome for a `send`\n * write so callers can await it.\n */\nexport function applyComposerWrite({\n  target,\n  store,\n  write,\n}: {\n  target: ComposerTarget;\n  store: ComposerHandoffStore | null;\n  write: ComposerWrite;\n}): Promise<void> | void {\n  const current = target.composer.getState().text ?? '';\n  const next = mergeComposerDraft({ current, write });\n  target.composer.setText(next);\n  if (write.focus && store) {\n    // An unchanged draft never re-mirrors, so focus at once; otherwise the\n    // editor focuses itself right after it has shown the new text.\n    if (next === current) store.focusEnd?.();\n    else store.focusOnNextMirror = true;\n  }\n  athenaDiagnostics.emit('composer.handoff', {\n    level: 'debug',\n    data: { phase: 'applied', send: write.send, focus: write.focus, chars: next.length },\n  });\n  if (write.send) {\n    return Promise.resolve(target.composer.send({ steer: false })).then(() => undefined);\n  }\n  return undefined;\n}\n\n/**\n * Hold a write until the composer is ready. Writes keep their order; a plain\n * append folds into a directly preceding plain append for the same thread\n * (one draft, not two), while a replace or a send is kept as its own step so\n * no message is lost and every send settles on its own.\n */\nexport function queueComposerWrite({\n  store,\n  write,\n}: {\n  store: ComposerHandoffStore;\n  write: ComposerWrite;\n}): void {\n  const last = store.pending[store.pending.length - 1];\n  const foldable =\n    last !== undefined &&\n    !last.send &&\n    !write.send &&\n    !write.replace &&\n    last.threadId === write.threadId &&\n    last.resolve === undefined &&\n    write.resolve === undefined;\n  if (foldable) {\n    last.text = mergeComposerDraft({ current: last.text, write });\n    last.focus = last.focus || write.focus;\n  } else {\n    store.pending.push(write);\n  }\n  athenaDiagnostics.emit('composer.handoff', {\n    level: 'debug',\n    data: { phase: 'deferred', send: write.send, focus: write.focus, queued: store.pending.length },\n  });\n}\n\nfunction dropWrite({ write, reason }: { write: ComposerWrite; reason: string }): void {\n  const error = new AthenaSdkError({\n    code: 'composer_write_dropped',\n    message: `A composer ${write.send ? 'send' : 'draft'} queued before the chat was ready was dropped: ${reason}.`,\n    hint: 'Make the write again from the chat that is active now.',\n    context: { threadId: write.threadId, send: write.send },\n  });\n  athenaDiagnostics.emit('composer.handoff', {\n    level: 'warn',\n    error,\n    data: { phase: 'dropped', send: write.send, reason, threadId: write.threadId },\n  });\n  write.reject?.(error);\n}\n\n/**\n * Deliver the pending writes, in order, into a now-ready composer. A write\n * made for another thread is dropped (rejected), never applied here.\n */\nexport function drainComposerHandoff({\n  store,\n  target,\n  threadId,\n}: {\n  store: ComposerHandoffStore;\n  target: ComposerTarget;\n  /** The statewire thread of the mount that is draining. */\n  threadId: string | null;\n}): void {\n  const writes = store.pending;\n  if (writes.length === 0) return;\n  store.pending = [];\n  for (const write of writes) {\n    if (write.threadId !== null && threadId !== null && write.threadId !== threadId) {\n      dropWrite({ write, reason: `it was made for thread ${write.threadId}, thread ${threadId} is active` });\n      continue;\n    }\n    const outcome = applyComposerWrite({ target, store, write });\n    write.resolve?.(outcome);\n  }\n}\n\n/** Drop every pending write (identity changed, provider unmounted). */\nexport function clearComposerHandoff({\n  store,\n  reason,\n}: {\n  store: ComposerHandoffStore;\n  reason: string;\n}): void {\n  const writes = store.pending;\n  if (writes.length === 0) return;\n  store.pending = [];\n  for (const write of writes) dropWrite({ write, reason });\n}\n"],"names":["createContext","useContext","useAthenaStatewireThreadList","useAuiState","athenaDiagnostics","AthenaSdkError"],"mappings":"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"}

package/dist/composer/composer-handoff.d.ts

@@ -0,0 +1,89 @@
+import { AthenaSdkError } from '../diagnostics/errors';
+/** The slice of the assistant-ui client the handoff writes to. */
+export interface ComposerTarget {
+    composer: {
+        getState: () => {
+            text: string;
+        };
+        setText: (text: string) => void;
+        send: (options?: {
+            steer?: boolean;
+        }) => unknown;
+    };
+}
+export interface ComposerWrite {
+    text: string;
+    /** Replace the draft instead of appending on a new line. */
+    replace: boolean;
+    /** Submit right after writing. */
+    send: boolean;
+    /** Put the caret at the end of the draft once the editor shows it. */
+    focus: boolean;
+    /** The statewire thread the write was made for; it drains only into that thread's mount. */
+    threadId: string | null;
+    /** Settled once the write has been applied (and, for `send`, with the send's outcome). */
+    resolve?: (outcome: Promise<void> | void) => void;
+    /** Settled with `composer_write_dropped` when the write can no longer land. */
+    reject?: (error: AthenaSdkError) => void;
+}
+export interface ComposerHandoffStore {
+    /** Writes waiting for a ready composer, oldest first. Adjacent plain appends fold together. */
+    pending: ComposerWrite[];
+    /** Set by a `focus` write; the editor consumes it after mirroring the draft. */
+    focusOnNextMirror: boolean;
+    /** Registered by the mounted editor: place the caret at the end of the draft. */
+    focusEnd: (() => void) | null;
+}
+export declare function createComposerHandoffStore(): ComposerHandoffStore;
+export declare const ComposerHandoffContext: import("react").Context<ComposerHandoffStore | null>;
+/** The provider's handoff store, or null outside `AthenaProvider`. */
+export declare function useComposerHandoffStore(): ComposerHandoffStore | null;
+/**
+ * Whether a composer write lands now: in thread-list mode the list has
+ * resolved which thread is active, and that thread's history has loaded.
+ * Until then the composer the hooks write to is the one of a mount that is
+ * about to be replaced, and the draft goes with it.
+ *
+ * Deliberately not the socket status: a never-started chat sits in
+ * `standby` until its first send and must still take a prefill.
+ */
+export declare function useComposerReady(): boolean;
+/** The draft after `write`: `replace` (or an empty draft) takes the text as is. */
+export declare function mergeComposerDraft({ current, write, }: {
+    current: string;
+    write: Pick<ComposerWrite, 'text' | 'replace'>;
+}): string;
+/**
+ * Write into the live composer. Returns the send's outcome for a `send`
+ * write so callers can await it.
+ */
+export declare function applyComposerWrite({ target, store, write, }: {
+    target: ComposerTarget;
+    store: ComposerHandoffStore | null;
+    write: ComposerWrite;
+}): Promise<void> | void;
+/**
+ * Hold a write until the composer is ready. Writes keep their order; a plain
+ * append folds into a directly preceding plain append for the same thread
+ * (one draft, not two), while a replace or a send is kept as its own step so
+ * no message is lost and every send settles on its own.
+ */
+export declare function queueComposerWrite({ store, write, }: {
+    store: ComposerHandoffStore;
+    write: ComposerWrite;
+}): void;
+/**
+ * Deliver the pending writes, in order, into a now-ready composer. A write
+ * made for another thread is dropped (rejected), never applied here.
+ */
+export declare function drainComposerHandoff({ store, target, threadId, }: {
+    store: ComposerHandoffStore;
+    target: ComposerTarget;
+    /** The statewire thread of the mount that is draining. */
+    threadId: string | null;
+}): void;
+/** Drop every pending write (identity changed, provider unmounted). */
+export declare function clearComposerHandoff({ store, reason, }: {
+    store: ComposerHandoffStore;
+    reason: string;
+}): void;

package/dist/composer/composer-handoff.js

@@ -0,0 +1,121 @@
+import { createContext, useContext } from "react";
+import { useAuiState } from "@assistant-ui/react";
+import { athenaDiagnostics } from "../diagnostics/athena-diagnostics.js";
+import { AthenaSdkError } from "../diagnostics/errors.js";
+import { useAthenaStatewireThreadList } from "../threads/statewire-thread-list.js";
+function createComposerHandoffStore() {
+  return { pending: [], focusOnNextMirror: false, focusEnd: null };
+}
+const ComposerHandoffContext = createContext(null);
+function useComposerHandoffStore() {
+  return useContext(ComposerHandoffContext);
+}
+function useComposerReady() {
+  const list = useAthenaStatewireThreadList();
+  const threadLoading = useAuiState((s) => {
+    var _a;
+    return ((_a = s.optional.thread) == null ? void 0 : _a.isLoading) ?? false;
+  });
+  return !((list == null ? void 0 : list.isLoading) ?? false) && !threadLoading;
+}
+function mergeComposerDraft({
+  current,
+  write
+}) {
+  if (write.replace || !current) return write.text;
+  return `${current}
+${write.text}`;
+}
+function applyComposerWrite({
+  target,
+  store,
+  write
+}) {
+  var _a;
+  const current = target.composer.getState().text ?? "";
+  const next = mergeComposerDraft({ current, write });
+  target.composer.setText(next);
+  if (write.focus && store) {
+    if (next === current) (_a = store.focusEnd) == null ? void 0 : _a.call(store);
+    else store.focusOnNextMirror = true;
+  }
+  athenaDiagnostics.emit("composer.handoff", {
+    level: "debug",
+    data: { phase: "applied", send: write.send, focus: write.focus, chars: next.length }
+  });
+  if (write.send) {
+    return Promise.resolve(target.composer.send({ steer: false })).then(() => void 0);
+  }
+  return void 0;
+}
+function queueComposerWrite({
+  store,
+  write
+}) {
+  const last = store.pending[store.pending.length - 1];
+  const foldable = last !== void 0 && !last.send && !write.send && !write.replace && last.threadId === write.threadId && last.resolve === void 0 && write.resolve === void 0;
+  if (foldable) {
+    last.text = mergeComposerDraft({ current: last.text, write });
+    last.focus = last.focus || write.focus;
+  } else {
+    store.pending.push(write);
+  }
+  athenaDiagnostics.emit("composer.handoff", {
+    level: "debug",
+    data: { phase: "deferred", send: write.send, focus: write.focus, queued: store.pending.length }
+  });
+}
+function dropWrite({ write, reason }) {
+  var _a;
+  const error = new AthenaSdkError({
+    code: "composer_write_dropped",
+    message: `A composer ${write.send ? "send" : "draft"} queued before the chat was ready was dropped: ${reason}.`,
+    hint: "Make the write again from the chat that is active now.",
+    context: { threadId: write.threadId, send: write.send }
+  });
+  athenaDiagnostics.emit("composer.handoff", {
+    level: "warn",
+    error,
+    data: { phase: "dropped", send: write.send, reason, threadId: write.threadId }
+  });
+  (_a = write.reject) == null ? void 0 : _a.call(write, error);
+}
+function drainComposerHandoff({
+  store,
+  target,
+  threadId
+}) {
+  var _a;
+  const writes = store.pending;
+  if (writes.length === 0) return;
+  store.pending = [];
+  for (const write of writes) {
+    if (write.threadId !== null && threadId !== null && write.threadId !== threadId) {
+      dropWrite({ write, reason: `it was made for thread ${write.threadId}, thread ${threadId} is active` });
+      continue;
+    }
+    const outcome = applyComposerWrite({ target, store, write });
+    (_a = write.resolve) == null ? void 0 : _a.call(write, outcome);
+  }
+}
+function clearComposerHandoff({
+  store,
+  reason
+}) {
+  const writes = store.pending;
+  if (writes.length === 0) return;
+  store.pending = [];
+  for (const write of writes) dropWrite({ write, reason });
+}
+export {
+  ComposerHandoffContext,
+  applyComposerWrite,
+  clearComposerHandoff,
+  createComposerHandoffStore,
+  drainComposerHandoff,
+  mergeComposerDraft,
+  queueComposerWrite,
+  useComposerHandoffStore,
+  useComposerReady
+};
+//# sourceMappingURL=composer-handoff.js.map

package/dist/composer/composer-handoff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"composer-handoff.js","sources":["../../src/composer/composer-handoff.ts"],"sourcesContent":["/**\n * Composer handoff: writes to the chat composer from host UI that lives\n * outside `<AthenaChat>` (a sidebar, an agenda card, a workflow button).\n *\n * Two problems it solves for `useAppendToComposer` / `useSendMessage`:\n *\n * 1. A write before the chat is ready is lost. While the thread list is still\n *    resolving the active thread, or the thread's history is still loading,\n *    the composer the hooks write to belongs to a mount that is about to be\n *    replaced (thread-list mode keys the statewire subtree by thread), and\n *    the draft goes with it. The store below lives ABOVE that mount, so a\n *    write made too early waits here and the ready mount drains it.\n * 2. A prefilled draft should put the caret after the text so the user can\n *    keep typing or dictating. The Tiptap editor mirrors runtime text on a\n *    later tick; the `focusOnNextMirror` flag asks it to focus at the end\n *    right after that mirror lands, instead of the host guessing a delay.\n *\n * Every queued write is bound to the statewire thread it was made for and\n * drains only into that thread's mount; a thread switch, an identity change\n * or a provider unmount drops what waits with a `composer_write_dropped`\n * error, never into another user's or another thread's composer.\n */\nimport { createContext, useContext } from 'react';\nimport { useAuiState } from '@assistant-ui/react';\nimport { athenaDiagnostics } from '../diagnostics/athena-diagnostics';\nimport { AthenaSdkError } from '../diagnostics/errors';\nimport { useAthenaStatewireThreadList } from '../threads/statewire-thread-list';\n\n/** The slice of the assistant-ui client the handoff writes to. */\nexport interface ComposerTarget {\n  composer: {\n    getState: () => { text: string };\n    setText: (text: string) => void;\n    send: (options?: { steer?: boolean }) => unknown;\n  };\n}\n\nexport interface ComposerWrite {\n  text: string;\n  /** Replace the draft instead of appending on a new line. */\n  replace: boolean;\n  /** Submit right after writing. */\n  send: boolean;\n  /** Put the caret at the end of the draft once the editor shows it. */\n  focus: boolean;\n  /** The statewire thread the write was made for; it drains only into that thread's mount. */\n  threadId: string | null;\n  /** Settled once the write has been applied (and, for `send`, with the send's outcome). */\n  resolve?: (outcome: Promise<void> | void) => void;\n  /** Settled with `composer_write_dropped` when the write can no longer land. */\n  reject?: (error: AthenaSdkError) => void;\n}\n\nexport interface ComposerHandoffStore {\n  /** Writes waiting for a ready composer, oldest first. Adjacent plain appends fold together. */\n  pending: ComposerWrite[];\n  /** Set by a `focus` write; the editor consumes it after mirroring the draft. */\n  focusOnNextMirror: boolean;\n  /** Registered by the mounted editor: place the caret at the end of the draft. */\n  focusEnd: (() => void) | null;\n}\n\nexport function createComposerHandoffStore(): ComposerHandoffStore {\n  return { pending: [], focusOnNextMirror: false, focusEnd: null };\n}\n\nexport const ComposerHandoffContext = createContext<ComposerHandoffStore | null>(null);\n\n/** The provider's handoff store, or null outside `AthenaProvider`. */\nexport function useComposerHandoffStore(): ComposerHandoffStore | null {\n  return useContext(ComposerHandoffContext);\n}\n\n/**\n * Whether a composer write lands now: in thread-list mode the list has\n * resolved which thread is active, and that thread's history has loaded.\n * Until then the composer the hooks write to is the one of a mount that is\n * about to be replaced, and the draft goes with it.\n *\n * Deliberately not the socket status: a never-started chat sits in\n * `standby` until its first send and must still take a prefill.\n */\nexport function useComposerReady(): boolean {\n  const list = useAthenaStatewireThreadList();\n  const threadLoading = useAuiState((s) => s.optional.thread?.isLoading ?? false);\n  return !(list?.isLoading ?? false) && !threadLoading;\n}\n\n/** The draft after `write`: `replace` (or an empty draft) takes the text as is. */\nexport function mergeComposerDraft({\n  current,\n  write,\n}: {\n  current: string;\n  write: Pick<ComposerWrite, 'text' | 'replace'>;\n}): string {\n  if (write.replace || !current) return write.text;\n  return `${current}\\n${write.text}`;\n}\n\n/**\n * Write into the live composer. Returns the send's outcome for a `send`\n * write so callers can await it.\n */\nexport function applyComposerWrite({\n  target,\n  store,\n  write,\n}: {\n  target: ComposerTarget;\n  store: ComposerHandoffStore | null;\n  write: ComposerWrite;\n}): Promise<void> | void {\n  const current = target.composer.getState().text ?? '';\n  const next = mergeComposerDraft({ current, write });\n  target.composer.setText(next);\n  if (write.focus && store) {\n    // An unchanged draft never re-mirrors, so focus at once; otherwise the\n    // editor focuses itself right after it has shown the new text.\n    if (next === current) store.focusEnd?.();\n    else store.focusOnNextMirror = true;\n  }\n  athenaDiagnostics.emit('composer.handoff', {\n    level: 'debug',\n    data: { phase: 'applied', send: write.send, focus: write.focus, chars: next.length },\n  });\n  if (write.send) {\n    return Promise.resolve(target.composer.send({ steer: false })).then(() => undefined);\n  }\n  return undefined;\n}\n\n/**\n * Hold a write until the composer is ready. Writes keep their order; a plain\n * append folds into a directly preceding plain append for the same thread\n * (one draft, not two), while a replace or a send is kept as its own step so\n * no message is lost and every send settles on its own.\n */\nexport function queueComposerWrite({\n  store,\n  write,\n}: {\n  store: ComposerHandoffStore;\n  write: ComposerWrite;\n}): void {\n  const last = store.pending[store.pending.length - 1];\n  const foldable =\n    last !== undefined &&\n    !last.send &&\n    !write.send &&\n    !write.replace &&\n    last.threadId === write.threadId &&\n    last.resolve === undefined &&\n    write.resolve === undefined;\n  if (foldable) {\n    last.text = mergeComposerDraft({ current: last.text, write });\n    last.focus = last.focus || write.focus;\n  } else {\n    store.pending.push(write);\n  }\n  athenaDiagnostics.emit('composer.handoff', {\n    level: 'debug',\n    data: { phase: 'deferred', send: write.send, focus: write.focus, queued: store.pending.length },\n  });\n}\n\nfunction dropWrite({ write, reason }: { write: ComposerWrite; reason: string }): void {\n  const error = new AthenaSdkError({\n    code: 'composer_write_dropped',\n    message: `A composer ${write.send ? 'send' : 'draft'} queued before the chat was ready was dropped: ${reason}.`,\n    hint: 'Make the write again from the chat that is active now.',\n    context: { threadId: write.threadId, send: write.send },\n  });\n  athenaDiagnostics.emit('composer.handoff', {\n    level: 'warn',\n    error,\n    data: { phase: 'dropped', send: write.send, reason, threadId: write.threadId },\n  });\n  write.reject?.(error);\n}\n\n/**\n * Deliver the pending writes, in order, into a now-ready composer. A write\n * made for another thread is dropped (rejected), never applied here.\n */\nexport function drainComposerHandoff({\n  store,\n  target,\n  threadId,\n}: {\n  store: ComposerHandoffStore;\n  target: ComposerTarget;\n  /** The statewire thread of the mount that is draining. */\n  threadId: string | null;\n}): void {\n  const writes = store.pending;\n  if (writes.length === 0) return;\n  store.pending = [];\n  for (const write of writes) {\n    if (write.threadId !== null && threadId !== null && write.threadId !== threadId) {\n      dropWrite({ write, reason: `it was made for thread ${write.threadId}, thread ${threadId} is active` });\n      continue;\n    }\n    const outcome = applyComposerWrite({ target, store, write });\n    write.resolve?.(outcome);\n  }\n}\n\n/** Drop every pending write (identity changed, provider unmounted). */\nexport function clearComposerHandoff({\n  store,\n  reason,\n}: {\n  store: ComposerHandoffStore;\n  reason: string;\n}): void {\n  const writes = store.pending;\n  if (writes.length === 0) return;\n  store.pending = [];\n  for (const write of writes) dropWrite({ write, reason });\n}\n"],"names":[],"mappings":"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"}

package/dist/composer/index.d.ts

@@ -1,6 +1,8 @@
 export { useAppendToComposer } from './useAppendToComposer';
+export type { AppendToComposerOptions } from './useAppendToComposer';
 export { useSendMessage } from './useSendMessage';
 export type { SendMessageOptions } from './useSendMessage';
+export { useComposerReady } from './composer-handoff';
 export { useComposerAttachment } from './useComposerAttachment';
 export { useFileUpload } from './useFileUpload';
 export type { UploadedAsset, UploadProgress, UseFileUploadReturn } from './useFileUpload';

package/dist/composer/useAppendToComposer.cjs

@@ -2,19 +2,31 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const react$1 = require("react");
 const react = require("@assistant-ui/react");
+const threadIdContext = require("../threads/thread-id-context.cjs");
+const composerHandoff = require("./composer-handoff.cjs");
 function useAppendToComposer() {
   const aui = react.useAui();
+  const store = composerHandoff.useComposerHandoffStore();
+  const threadId = react$1.useContext(threadIdContext.AthenaStatewireThreadIdContext);
+  const ready = composerHandoff.useComposerReady();
+  const readyRef = react$1.useRef(ready);
+  readyRef.current = ready;
   return react$1.useCallback(
     (text, opts) => {
-      if (opts == null ? void 0 : opts.replace) {
-        aui.composer.setText(text);
-      } else {
-        const current = aui.composer.getState().text;
-        aui.composer.setText(current ? `${current}
-${text}` : text);
+      const write = {
+        text,
+        replace: (opts == null ? void 0 : opts.replace) ?? false,
+        send: false,
+        focus: (opts == null ? void 0 : opts.focus) ?? false,
+        threadId
+      };
+      if (store && !readyRef.current) {
+        composerHandoff.queueComposerWrite({ store, write });
+        return;
       }
+      composerHandoff.applyComposerWrite({ target: aui, store, write });
     },
-    [aui]
+    [aui, store, threadId]
   );
 }
 exports.useAppendToComposer = useAppendToComposer;

package/dist/composer/useAppendToComposer.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"useAppendToComposer.cjs","sources":["../../src/composer/useAppendToComposer.ts"],"sourcesContent":["import { useCallback } from 'react';\nimport { useAui } from '@assistant-ui/react';\n\n/**\n * Hook to programmatically append text to the composer without sending it.\n *\n * Use `useSendMessage()` for workflow shortcuts or other UI that should\n * immediately submit a prompt.\n *\n * Usage:\n *   const append = useAppendToComposer();\n *   append(\"some text to add\");\n *   append(\"quoted text\", { replace: true }); // replaces existing text\n */\nexport function useAppendToComposer() {\n  const aui = useAui();\n\n  return useCallback(\n    (text: string, opts?: { replace?: boolean }) => {\n      if (opts?.replace) {\n        aui.composer.setText(text);\n      } else {\n        const current = aui.composer.getState().text;\n        aui.composer.setText(current ? `${current}\\n${text}` : text);\n      }\n    },\n    [aui],\n  );\n}\n"],"names":["useAui","useCallback"],"mappings":";;;;AAcO,SAAS,sBAAsB;AACpC,QAAM,MAAMA,MAAAA,OAAA;AAEZ,SAAOC,QAAAA;AAAAA,IACL,CAAC,MAAc,SAAiC;AAC9C,UAAI,6BAAM,SAAS;AACjB,YAAI,SAAS,QAAQ,IAAI;AAAA,MAC3B,OAAO;AACL,cAAM,UAAU,IAAI,SAAS,SAAA,EAAW;AACxC,YAAI,SAAS,QAAQ,UAAU,GAAG,OAAO;AAAA,EAAK,IAAI,KAAK,IAAI;AAAA,MAC7D;AAAA,IACF;AAAA,IACA,CAAC,GAAG;AAAA,EAAA;AAER;;"}
+{"version":3,"file":"useAppendToComposer.cjs","sources":["../../src/composer/useAppendToComposer.ts"],"sourcesContent":["import { useCallback, useContext, useRef } from 'react';\nimport { useAui } from '@assistant-ui/react';\nimport { AthenaStatewireThreadIdContext } from '../threads/thread-id-context';\nimport {\n  applyComposerWrite,\n  queueComposerWrite,\n  useComposerHandoffStore,\n  useComposerReady,\n  type ComposerWrite,\n} from './composer-handoff';\n\nexport interface AppendToComposerOptions {\n  /** Replace the current draft instead of appending on a new line. */\n  replace?: boolean;\n  /**\n   * Focus the composer with the caret after the text once the editor shows\n   * it — for a prefilled draft the user is meant to finish by typing or\n   * dictating. Defaults to false.\n   */\n  focus?: boolean;\n}\n\n/**\n * Hook to programmatically append text to the composer without sending it.\n *\n * Safe to call at any time: a write made before the chat is ready (the\n * thread list still resolving the active thread, or the thread's history\n * still loading) waits in the provider and lands once the composer is\n * ready, instead of being lost with the mount it was written into. A\n * never-started chat is ready without a live socket. The write is bound to\n * the thread it was made for: if the user switches threads first, it is\n * dropped (a `composer.handoff` diagnostic says so), never written into\n * another thread.\n *\n * Use `useSendMessage()` for workflow shortcuts or other UI that should\n * immediately submit a prompt.\n *\n * Usage:\n *   const append = useAppendToComposer();\n *   append(\"some text to add\");\n *   append(\"quoted text\", { replace: true });            // replaces existing text\n *   append(\"Here is what happened: \", { replace: true, focus: true }); // caret after the text\n */\nexport function useAppendToComposer() {\n  const aui = useAui();\n  const store = useComposerHandoffStore();\n  const threadId = useContext(AthenaStatewireThreadIdContext);\n  const ready = useComposerReady();\n  // The callback stays identity-stable across readiness changes.\n  const readyRef = useRef(ready);\n  readyRef.current = ready;\n\n  return useCallback(\n    (text: string, opts?: AppendToComposerOptions) => {\n      const write: ComposerWrite = {\n        text,\n        replace: opts?.replace ?? false,\n        send: false,\n        focus: opts?.focus ?? false,\n        threadId,\n      };\n      if (store && !readyRef.current) {\n        queueComposerWrite({ store, write });\n        return;\n      }\n      applyComposerWrite({ target: aui, store, write });\n    },\n    [aui, store, threadId],\n  );\n}\n"],"names":["useAui","useComposerHandoffStore","useContext","AthenaStatewireThreadIdContext","useComposerReady","useRef","useCallback","queueComposerWrite","applyComposerWrite"],"mappings":";;;;;;AA2CO,SAAS,sBAAsB;AACpC,QAAM,MAAMA,MAAAA,OAAA;AACZ,QAAM,QAAQC,gBAAAA,wBAAA;AACd,QAAM,WAAWC,QAAAA,WAAWC,8CAA8B;AAC1D,QAAM,QAAQC,gBAAAA,iBAAA;AAEd,QAAM,WAAWC,QAAAA,OAAO,KAAK;AAC7B,WAAS,UAAU;AAEnB,SAAOC,QAAAA;AAAAA,IACL,CAAC,MAAc,SAAmC;AAChD,YAAM,QAAuB;AAAA,QAC3B;AAAA,QACA,UAAS,6BAAM,YAAW;AAAA,QAC1B,MAAM;AAAA,QACN,QAAO,6BAAM,UAAS;AAAA,QACtB;AAAA,MAAA;AAEF,UAAI,SAAS,CAAC,SAAS,SAAS;AAC9BC,2CAAmB,EAAE,OAAO,OAAO;AACnC;AAAA,MACF;AACAC,sBAAAA,mBAAmB,EAAE,QAAQ,KAAK,OAAO,OAAO;AAAA,IAClD;AAAA,IACA,CAAC,KAAK,OAAO,QAAQ;AAAA,EAAA;AAEzB;;"}

package/dist/composer/useAppendToComposer.d.ts

@@ -1,14 +1,32 @@
+export interface AppendToComposerOptions {
+    /** Replace the current draft instead of appending on a new line. */
+    replace?: boolean;
+    /**
+     * Focus the composer with the caret after the text once the editor shows
+     * it — for a prefilled draft the user is meant to finish by typing or
+     * dictating. Defaults to false.
+     */
+    focus?: boolean;
+}
 /**
  * Hook to programmatically append text to the composer without sending it.
  *
+ * Safe to call at any time: a write made before the chat is ready (the
+ * thread list still resolving the active thread, or the thread's history
+ * still loading) waits in the provider and lands once the composer is
+ * ready, instead of being lost with the mount it was written into. A
+ * never-started chat is ready without a live socket. The write is bound to
+ * the thread it was made for: if the user switches threads first, it is
+ * dropped (a `composer.handoff` diagnostic says so), never written into
+ * another thread.
+ *
  * Use `useSendMessage()` for workflow shortcuts or other UI that should
  * immediately submit a prompt.
  *
  * Usage:
  *   const append = useAppendToComposer();
  *   append("some text to add");
- *   append("quoted text", { replace: true }); // replaces existing text
+ *   append("quoted text", { replace: true });            // replaces existing text
+ *   append("Here is what happened: ", { replace: true, focus: true }); // caret after the text
  */
-export declare function useAppendToComposer(): (text: string, opts?: {
-    replace?: boolean;
-}) => void;
+export declare function useAppendToComposer(): (text: string, opts?: AppendToComposerOptions) => void;

package/dist/composer/useAppendToComposer.js

@@ -1,18 +1,30 @@
-import { useCallback } from "react";
+import { useContext, useRef, useCallback } from "react";
 import { useAui } from "@assistant-ui/react";
+import { AthenaStatewireThreadIdContext } from "../threads/thread-id-context.js";
+import { useComposerHandoffStore, useComposerReady, queueComposerWrite, applyComposerWrite } from "./composer-handoff.js";
 function useAppendToComposer() {
   const aui = useAui();
+  const store = useComposerHandoffStore();
+  const threadId = useContext(AthenaStatewireThreadIdContext);
+  const ready = useComposerReady();
+  const readyRef = useRef(ready);
+  readyRef.current = ready;
   return useCallback(
     (text, opts) => {
-      if (opts == null ? void 0 : opts.replace) {
-        aui.composer.setText(text);
-      } else {
-        const current = aui.composer.getState().text;
-        aui.composer.setText(current ? `${current}
-${text}` : text);
+      const write = {
+        text,
+        replace: (opts == null ? void 0 : opts.replace) ?? false,
+        send: false,
+        focus: (opts == null ? void 0 : opts.focus) ?? false,
+        threadId
+      };
+      if (store && !readyRef.current) {
+        queueComposerWrite({ store, write });
+        return;
       }
+      applyComposerWrite({ target: aui, store, write });
     },
-    [aui]
+    [aui, store, threadId]
   );
 }
 export {

package/dist/composer/useAppendToComposer.js.map

@@ -1 +1 @@
-{"version":3,"file":"useAppendToComposer.js","sources":["../../src/composer/useAppendToComposer.ts"],"sourcesContent":["import { useCallback } from 'react';\nimport { useAui } from '@assistant-ui/react';\n\n/**\n * Hook to programmatically append text to the composer without sending it.\n *\n * Use `useSendMessage()` for workflow shortcuts or other UI that should\n * immediately submit a prompt.\n *\n * Usage:\n *   const append = useAppendToComposer();\n *   append(\"some text to add\");\n *   append(\"quoted text\", { replace: true }); // replaces existing text\n */\nexport function useAppendToComposer() {\n  const aui = useAui();\n\n  return useCallback(\n    (text: string, opts?: { replace?: boolean }) => {\n      if (opts?.replace) {\n        aui.composer.setText(text);\n      } else {\n        const current = aui.composer.getState().text;\n        aui.composer.setText(current ? `${current}\\n${text}` : text);\n      }\n    },\n    [aui],\n  );\n}\n"],"names":[],"mappings":";;AAcO,SAAS,sBAAsB;AACpC,QAAM,MAAM,OAAA;AAEZ,SAAO;AAAA,IACL,CAAC,MAAc,SAAiC;AAC9C,UAAI,6BAAM,SAAS;AACjB,YAAI,SAAS,QAAQ,IAAI;AAAA,MAC3B,OAAO;AACL,cAAM,UAAU,IAAI,SAAS,SAAA,EAAW;AACxC,YAAI,SAAS,QAAQ,UAAU,GAAG,OAAO;AAAA,EAAK,IAAI,KAAK,IAAI;AAAA,MAC7D;AAAA,IACF;AAAA,IACA,CAAC,GAAG;AAAA,EAAA;AAER;"}
+{"version":3,"file":"useAppendToComposer.js","sources":["../../src/composer/useAppendToComposer.ts"],"sourcesContent":["import { useCallback, useContext, useRef } from 'react';\nimport { useAui } from '@assistant-ui/react';\nimport { AthenaStatewireThreadIdContext } from '../threads/thread-id-context';\nimport {\n  applyComposerWrite,\n  queueComposerWrite,\n  useComposerHandoffStore,\n  useComposerReady,\n  type ComposerWrite,\n} from './composer-handoff';\n\nexport interface AppendToComposerOptions {\n  /** Replace the current draft instead of appending on a new line. */\n  replace?: boolean;\n  /**\n   * Focus the composer with the caret after the text once the editor shows\n   * it — for a prefilled draft the user is meant to finish by typing or\n   * dictating. Defaults to false.\n   */\n  focus?: boolean;\n}\n\n/**\n * Hook to programmatically append text to the composer without sending it.\n *\n * Safe to call at any time: a write made before the chat is ready (the\n * thread list still resolving the active thread, or the thread's history\n * still loading) waits in the provider and lands once the composer is\n * ready, instead of being lost with the mount it was written into. A\n * never-started chat is ready without a live socket. The write is bound to\n * the thread it was made for: if the user switches threads first, it is\n * dropped (a `composer.handoff` diagnostic says so), never written into\n * another thread.\n *\n * Use `useSendMessage()` for workflow shortcuts or other UI that should\n * immediately submit a prompt.\n *\n * Usage:\n *   const append = useAppendToComposer();\n *   append(\"some text to add\");\n *   append(\"quoted text\", { replace: true });            // replaces existing text\n *   append(\"Here is what happened: \", { replace: true, focus: true }); // caret after the text\n */\nexport function useAppendToComposer() {\n  const aui = useAui();\n  const store = useComposerHandoffStore();\n  const threadId = useContext(AthenaStatewireThreadIdContext);\n  const ready = useComposerReady();\n  // The callback stays identity-stable across readiness changes.\n  const readyRef = useRef(ready);\n  readyRef.current = ready;\n\n  return useCallback(\n    (text: string, opts?: AppendToComposerOptions) => {\n      const write: ComposerWrite = {\n        text,\n        replace: opts?.replace ?? false,\n        send: false,\n        focus: opts?.focus ?? false,\n        threadId,\n      };\n      if (store && !readyRef.current) {\n        queueComposerWrite({ store, write });\n        return;\n      }\n      applyComposerWrite({ target: aui, store, write });\n    },\n    [aui, store, threadId],\n  );\n}\n"],"names":[],"mappings":";;;;AA2CO,SAAS,sBAAsB;AACpC,QAAM,MAAM,OAAA;AACZ,QAAM,QAAQ,wBAAA;AACd,QAAM,WAAW,WAAW,8BAA8B;AAC1D,QAAM,QAAQ,iBAAA;AAEd,QAAM,WAAW,OAAO,KAAK;AAC7B,WAAS,UAAU;AAEnB,SAAO;AAAA,IACL,CAAC,MAAc,SAAmC;AAChD,YAAM,QAAuB;AAAA,QAC3B;AAAA,QACA,UAAS,6BAAM,YAAW;AAAA,QAC1B,MAAM;AAAA,QACN,QAAO,6BAAM,UAAS;AAAA,QACtB;AAAA,MAAA;AAEF,UAAI,SAAS,CAAC,SAAS,SAAS;AAC9B,2BAAmB,EAAE,OAAO,OAAO;AACnC;AAAA,MACF;AACA,yBAAmB,EAAE,QAAQ,KAAK,OAAO,OAAO;AAAA,IAClD;AAAA,IACA,CAAC,KAAK,OAAO,QAAQ;AAAA,EAAA;AAEzB;"}