@alexkroman1/aai-ui 6.11.0 → 7.0.0

package/dist/internal.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `@alexkroman1/aai-ui/internal` — the plumbing `client()` and the default
+ * client install for themselves, NOT part of the public client API and not
+ * covered by semver. A `client.tsx` should never import from here; everything
+ * an author writes a page or a custom chrome against lives on the root export
+ * and the documented subpaths.
+ *
+ * These names used to ride on the root barrel, tagged `@internal` and nothing
+ * else, which meant they were in a client author's autocomplete beside
+ * `client()`, `<Form>`, `useAgentState` and `useWorkflowRun` — eight symbols an
+ * author is invited to reach for and no capability contract covers. Keeping
+ * them on their own subpath keeps the root importable surface the same shape as
+ * the promise: what is on it is contracted.
+ *
+ * A release tag cannot do this from the barrel. API Extractor reads `@internal`
+ * at the DECLARATION site, so a tag written on a re-export clause member is
+ * silently ignored and the name stays `@public` in the report — and the
+ * contract exemption in `contracts/internal-surface.json` is per SUBPATH, so a
+ * tag on the root barrel buys an entry on that ratchet rather than removing
+ * one. A subpath is the mechanism, the same one `@alexkroman1/aai` and
+ * `@alexkroman1/aai-runtime` already use, and `NON_AUTHORING_SUBPATHS` in
+ * `scripts/_api-contracts-tree.mjs` carries the matching entry so a name
+ * arriving here joins no capability contract.
+ *
+ * The corollary is the rule for adding to this file, and it runs the other way
+ * too: a name that WANTS to be public gets its `@internal` tag removed and
+ * joins a capability contract — it does not stay on the barrel wearing a tag.
+ * That is what happened to `fetchClientConfig`, which the SDK's own `@public`
+ * prose told a workflow-app author to call while the export excluded it.
+ *
+ * Named re-exports rather than `export *`: the wildcard form needs a
+ * `noReExportAll` suppression, and the escape-hatch ratchet only moves down.
+ *
+ * @module internal
+ */
+export { buildAgentUrl, loadClientConfig } from "./client-config.ts";
+export { ToolConfigContext } from "./components/tool-config-context.ts";
+export { ApiUrlChip, SessionUrlChips, UiUrlChip } from "./components/url-chips.tsx";
+export { SessionProvider, ThemeProvider } from "./context.ts";
+export { VOICE_CAPTURE_CONSTRAINTS } from "./types.ts";

package/dist/internal.js

@@ -0,0 +1,6 @@
+import { r as loadClientConfig, t as buildAgentUrl } from "./client-config-B4nznRvH.js";
+import { SessionProvider, ThemeProvider } from "./context.js";
+import { n as SessionUrlChips, r as UiUrlChip, t as ApiUrlChip } from "./url-chips-DpM7Oocj.js";
+import { t as ToolConfigContext } from "./tool-config-context-DzAofqi_.js";
+import { VOICE_CAPTURE_CONSTRAINTS } from "./types.js";
+export { ApiUrlChip, SessionProvider, SessionUrlChips, ThemeProvider, ToolConfigContext, UiUrlChip, VOICE_CAPTURE_CONSTRAINTS, buildAgentUrl, loadClientConfig };

package/dist/{message-list-CpPV7dGx.js → message-list-DHddO4QC.js}

@@ -1,6 +1,6 @@
 import { useSessionSelector, useTheme } from "./context.js";
 import { i as primaryTint, r as inkTint } from "./_colors-CcAi2FOU.js";
-import { t as ToolCallBlock } from "./tool-call-block-D6pTEPrT.js";
+import { t as ToolCallBlock } from "./tool-call-block-DoF-cSIZ.js";
 import clsx from "clsx";
 import { StickToBottom } from "use-stick-to-bottom";
 import { jsx, jsxs } from "react/jsx-runtime";
@@ -46,19 +46,7 @@ import remarkGfm from "remark-gfm";
 * }
 * ```
 *
-* @param children - The scrollable content.
-* @param className - Classes for the outer container. It must be given a
-*   bounded height (`flex-1 min-h-0`, `h-full`, a fixed height) — an unbounded
-*   one grows with its content and never scrolls, so nothing pins.
-* @param contentClassName - Classes for the inner content element, where
-*   padding and the children's own layout belong.
-* @param scrollClassName - Classes for the scrolling element itself. Defaults
-*   to hiding the scrollbar; pass `"overflow-y-auto"` to show a native one.
-* @param style - Inline styles for the outer container.
-* @param initial - Scroll behavior on mount. Defaults to `"instant"` (start at
-*   the latest content without animating a scroll the reader did not ask for).
-* @param resize - Scroll behavior when pinned content grows. Defaults to
-*   `"smooth"`.
+* @param props - Scroll container props.
 *
 * @public
 */
@@ -77,6 +65,196 @@ function AutoScroll({ children, className, contentClassName, scrollClassName = "
 	});
 }
 //#endregion
+//#region use-user-transcript.ts
+/**
+* `useUserTranscript` — what the caller is saying RIGHT NOW, read correctly.
+*
+* `SessionSnapshot.userTranscript` is `string | null`, and the two falsy values
+* mean different things:
+*
+* - `null` — nobody is speaking. There is no partial turn.
+* - `""` — speech HAS been detected and no words have come back yet. A live
+*   session sits here for a few hundred milliseconds at the start of every turn.
+*
+* Read as one falsy check, those collapse and the indicator never appears at the
+* start of a turn — which is the moment it is for. So every custom chrome writes
+* `transcript !== null && (transcript === "" ? "…" : transcript)`, three
+* templates did exactly that, and each one re-derived a protocol distinction
+* from the type rather than from anything that told them.
+*
+* This is the same distinction as two named booleans, so a component can say
+* what it means: render on `speaking`, show `text`, and use the SDK's own
+* placeholder when there is nothing to show yet.
+*/
+/**
+* Placeholder for "listening, no words yet" — the `""` case above.
+*
+* A one-character ellipsis rather than three dots, because it is read by a
+* screen reader as an ellipsis and it does not reflow the row when the first
+* real word replaces it.
+*
+* @public
+*/
+const TRANSCRIBING_PLACEHOLDER = "…";
+/**
+* Subscribe to the caller's in-progress turn.
+*
+* Narrowly subscribed — a component using this re-renders at STT-partial rate,
+* which is exactly what it is for and exactly what a whole-page `useSession()`
+* should not do.
+*
+* @example
+* ```tsx
+* import { useUserTranscript } from "@alexkroman1/aai-ui";
+*
+* function LiveTranscript() {
+*   const { speaking, text } = useUserTranscript();
+*   if (!speaking) return null;
+*   return <div className="italic opacity-60">{text}</div>;
+* }
+* ```
+*
+* @public
+*/
+function useUserTranscript() {
+	const partial = useSessionSelector((snapshot) => snapshot.userTranscript);
+	return {
+		speaking: partial !== null,
+		text: displayText(partial),
+		partial
+	};
+}
+/** The three cases, spelled out: silent, detected-but-wordless, and words. */
+function displayText(partial) {
+	if (partial === null) return "";
+	return partial === "" ? "…" : partial;
+}
+//#endregion
+//#region use-conversation.ts
+/**
+* `useConversation` — the exchange, already assembled, with nothing rendered.
+*
+* `<MessageList>` owns four decisions that are not obvious and are not
+* derivable from the snapshot by eye: the message/tool-call INTERLEAVE, the
+* streaming agent utterance, the live user transcript with its `null`-vs-`""`
+* protocol distinction, and the thinking indicator's suppression rule. Its only
+* prop is `className`, so the moment a client wants its own bubble markup it
+* drops all four at once — and the three hand-rolled chromes in the template
+* tree each shipped a strictly worse conversation for exactly that reason. One
+* of them runs fifteen tools and its operator sees none of them, because the
+* tool calls live in a second array nothing in that page ever reads.
+*
+* This is the headless half. `<MessageList>` is now a thin consumer of it —
+* which is the only way to know the hook is complete, since a hook that the
+* package's own list cannot be built from is a hook a custom chrome will find a
+* hole in.
+*
+* ## It subscribes NARROWLY, and that is half the value
+*
+* The three custom chromes also call whole-page `useSession()`, which re-renders
+* on *every* snapshot change — so a dispatch board re-renders at STT-partial
+* rate. `<ChatView>` deliberately avoids that with per-field
+* {@link useSessionSelector} calls, and so does this: a component that reads the
+* conversation gets the conversation's own update rate, not the session's.
+*/
+/**
+* Interleave messages and tool calls, ordered by insertion time.
+*
+* Each tool call belongs immediately after its anchor message
+* (`afterMessageId`); tool calls whose anchor slid out of the retained window —
+* or that were inserted before any message existed — come first, since there is
+* nothing left for them to follow.
+*/
+function interleave(messages, toolCalls) {
+	const items = [];
+	let tci = 0;
+	const pushToolCallsThrough = (maxAfterId) => {
+		let tc = toolCalls[tci];
+		while (tc && tc.afterMessageId <= maxAfterId) {
+			items.push({
+				kind: "tool",
+				toolCall: tc
+			});
+			tci++;
+			tc = toolCalls[tci];
+		}
+	};
+	const firstMessage = messages[0];
+	if (firstMessage) pushToolCallsThrough(firstMessage.id - 1);
+	for (const message of messages) {
+		items.push({
+			kind: "message",
+			message
+		});
+		pushToolCallsThrough(message.id);
+	}
+	pushToolCallsThrough(Number.POSITIVE_INFINITY);
+	return items;
+}
+/**
+* Whether the thinking indicator should show — see
+* {@link UseConversationResult.thinking} for the rule and the argument.
+*/
+function isThinking(state, messages, toolCalls) {
+	if (state !== "thinking") return false;
+	const last = toolCalls.at(-1);
+	if (last?.status === "pending") return false;
+	const lastMessage = messages.at(-1);
+	return !lastMessage || lastMessage.role === "user" || Boolean(last);
+}
+/**
+* Subscribe to the conversation: the interleaved exchange, the streaming
+* utterance, the live transcript and the thinking rule — with no markup.
+*
+* Must be used inside the provider `client()` installs.
+*
+* @example A custom bubble, keeping every rule `<MessageList>` knows
+* ```tsx
+* import { useConversation } from "@alexkroman1/aai-ui";
+*
+* function Transcript() {
+*   const { items, streaming, transcript, thinking } = useConversation();
+*   return (
+*     <div>
+*       {items.map((item) =>
+*         item.kind === "message" ? (
+*           <p key={item.message.id} data-role={item.message.role}>
+*             {item.message.content}
+*           </p>
+*         ) : (
+*           <code key={item.toolCall.callId}>{item.toolCall.name}</code>
+*         ),
+*       )}
+*       {streaming !== null && <p data-role="assistant">{streaming}</p>}
+*       {transcript.speaking && <p data-role="user">{transcript.text}</p>}
+*       {thinking && <p>…</p>}
+*     </div>
+*   );
+* }
+* ```
+*
+* @returns See {@link UseConversationResult}.
+*
+* @public
+*/
+function useConversation() {
+	const state = useSessionSelector((s) => s.state);
+	const messages = useSessionSelector((s) => s.messages);
+	const toolCalls = useSessionSelector((s) => s.toolCalls);
+	const streaming = useSessionSelector((s) => s.agentTranscript);
+	const transcript = useUserTranscript();
+	return {
+		items: useMemo(() => interleave(messages, toolCalls), [messages, toolCalls]),
+		streaming,
+		transcript,
+		thinking: useMemo(() => isThinking(state, messages, toolCalls), [
+			state,
+			messages,
+			toolCalls
+		])
+	};
+}
+//#endregion
 //#region components/markdown.tsx
 /** @jsxImportSource react */
 const BARE_ORDERED_MARKER = /^(\s*)(\d{1,9})([.)])\s*$/;
@@ -137,6 +315,18 @@ const SCALE_CLASSES = {
 * Memoized alongside `MessageBubble`: message content is referentially
 * stable across snapshots, so only the streaming row re-parses.
 *
+* @example
+* ```tsx
+* import { Markdown, useSessionSelector } from "@alexkroman1/aai-ui";
+*
+* // The agent's reply as it streams, rendered rather than shown as literal
+* // asterisks and backticks.
+* function LiveReply() {
+*   const text = useSessionSelector((snapshot) => snapshot.agentTranscript);
+*   return text === null ? null : <Markdown text={text} variant="compact" />;
+* }
+* ```
+*
 * @public
 */
 const Markdown = memo(function Markdown({ text, variant = "default" }) {
@@ -339,32 +529,6 @@ const MessageBubble = memo(function MessageBubble({ message, theme }) {
 	});
 });
 /**
-* Interleave messages and tool calls into render items, ordered by insertion
-* time. Each tool call renders immediately after its anchor message
-* (`afterMessageId`); tool calls whose anchor slid out of the retained window
-* (or that were inserted before any message existed) render first.
-*/
-function interleave(messages, toolCalls, renderMessage, renderToolCall) {
-	const items = [];
-	let tci = 0;
-	const pushToolCallsThrough = (maxAfterId) => {
-		let tc = toolCalls[tci];
-		while (tc && tc.afterMessageId <= maxAfterId) {
-			items.push(renderToolCall(tc));
-			tci++;
-			tc = toolCalls[tci];
-		}
-	};
-	const firstMessage = messages[0];
-	if (firstMessage) pushToolCallsThrough(firstMessage.id - 1);
-	for (const msg of messages) {
-		items.push(renderMessage(msg));
-		pushToolCallsThrough(msg.id);
-	}
-	pushToolCallsThrough(Number.POSITIVE_INFINITY);
-	return items;
-}
-/**
 * Scrollable list of all chat messages, tool-call blocks, live transcript,
 * streaming agent utterance, and a thinking indicator.
 *
@@ -382,58 +546,39 @@ function interleave(messages, toolCalls, renderMessage, renderToolCall) {
 * }
 * ```
 *
-* @param className - Additional CSS class names applied to the outer list container.
+* @param props - Container props.
 *
 * @public
 */
 const MessageList = memo(function MessageList({ className }) {
-	const state = useSessionSelector((s) => s.state);
-	const messages = useSessionSelector((s) => s.messages);
-	const toolCalls = useSessionSelector((s) => s.toolCalls);
-	const userTranscript = useSessionSelector((s) => s.userTranscript);
-	const agentTranscript = useSessionSelector((s) => s.agentTranscript);
+	const { items, streaming, transcript, thinking } = useConversation();
 	const theme = useTheme();
-	const showThinking = useMemo(() => {
-		if (state !== "thinking") return false;
-		const last = toolCalls.at(-1);
-		if (last?.status === "pending") return false;
-		const lastMsg = messages.at(-1);
-		return !lastMsg || lastMsg.role === "user" || Boolean(last);
-	}, [
-		state,
-		toolCalls,
-		messages
-	]);
-	const streamingMessage = useMemo(() => agentTranscript ? {
+	const streamingMessage = useMemo(() => streaming ? {
 		role: "assistant",
-		content: agentTranscript
-	} : null, [agentTranscript]);
-	const items = useMemo(() => interleave(messages, toolCalls, (msg) => /* @__PURE__ */ jsx(MessageBubble, {
-		message: msg,
-		theme
-	}, msg.id), (tc) => /* @__PURE__ */ jsx(ToolCallBlock, { toolCall: tc }, tc.callId)), [
-		messages,
-		toolCalls,
+		content: streaming
+	} : null, [streaming]);
+	const rows = useMemo(() => items.map((item) => item.kind === "message" ? /* @__PURE__ */ jsx(MessageBubble, {
+		message: item.message,
 		theme
-	]);
+	}, item.message.id) : /* @__PURE__ */ jsx(ToolCallBlock, { toolCall: item.toolCall }, item.toolCall.callId)), [items, theme]);
 	return /* @__PURE__ */ jsxs(AutoScroll, {
 		className,
 		style: { background: theme.surface },
 		contentClassName: "flex flex-col gap-4 p-7",
 		children: [
-			items,
+			rows,
 			streamingMessage && /* @__PURE__ */ jsx(MessageBubble, {
 				message: streamingMessage,
 				theme
 			}),
-			userTranscript !== null && /* @__PURE__ */ jsx(UserBubble, {
+			transcript.speaking && /* @__PURE__ */ jsx(UserBubble, {
 				theme,
 				color: inkTint(theme.text, theme.surface, 65),
-				children: userTranscript ? userTranscript : /* @__PURE__ */ jsx(ThinkingDots, {})
+				children: transcript.partial ? transcript.partial : /* @__PURE__ */ jsx(ThinkingDots, {})
 			}),
-			showThinking && /* @__PURE__ */ jsx(ThinkingDots, {})
+			thinking && /* @__PURE__ */ jsx(ThinkingDots, {})
 		]
 	});
 });
 //#endregion
-export { Markdown as n, AutoScroll as r, MessageList as t };
+export { useUserTranscript as a, TRANSCRIBING_PLACEHOLDER as i, Markdown as n, AutoScroll as o, useConversation as r, MessageList as t };