@alexkroman1/aai-ui 0.12.3 → 0.13.0

package/dist/chat-view-BCbI7gD4.js

@@ -0,0 +1,396 @@
+import { useSessionError, useSessionStatus, useTheme } from "./context.js";
+import { t as MessageList } from "./message-list-DHZcLhRA.js";
+import { a as inkTint, r as THINKING_COLOR, t as ERROR_COLOR } from "./_colors-CpZO-88A.js";
+import { t as AaiLogo } from "./aai-logo-D8pMVn9_.js";
+import { t as Eyebrow } from "./eyebrow-UfmSz9yy.js";
+import { Controls } from "./components/controls.js";
+import clsx from "clsx";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/agent-state-labels.ts
+/**
+* The default label per {@link AgentState}.
+*
+* Override the ones your page has a better word for and keep the rest:
+*
+* ```ts
+* import type { AgentState } from "@alexkroman1/aai-ui";
+* import { AGENT_STATE_LABELS } from "@alexkroman1/aai-ui";
+*
+* // A dispatch board that shouts, and renames one state.
+* const STATE_LABEL = { ...AGENT_STATE_LABELS, thinking: "Processing" };
+* const shout = (s: AgentState) => STATE_LABEL[s].toUpperCase();
+* ```
+*
+* **Sentence case, deliberately.** A template that wants caps applies its own
+* `.toUpperCase()`, and a template that wants Title Case is already there;
+* shipping the shouted form instead would leave the two chromes that do not
+* shout with a string they have to un-shout, which no case transform does
+* correctly.
+*
+* Two wordings are decisions rather than transliterations of the member name:
+*
+* - `disconnected` is **"Idle"**. It is the state a session is in BEFORE it has
+*   ever started as well as after it ends, so it is the first word most callers
+*   see; "Disconnected" reads as a fault on a page where nothing has gone
+*   wrong yet. Both chromes that mapped this state by hand chose "Idle" too.
+* - `connecting` and `thinking` carry an ellipsis, `listening` and `speaking`
+*   do not. The first two are waits with nothing for the caller to do; the
+*   other two describe someone actually talking. Same distinction
+*   `WORKFLOW_STATUS_LABELS` draws with its one "Working…".
+*
+* @public
+*/
+const AGENT_STATE_LABELS = {
+	disconnected: "Idle",
+	connecting: "Connecting…",
+	ready: "Ready",
+	listening: "Listening",
+	thinking: "Thinking…",
+	speaking: "Speaking",
+	error: "Error"
+};
+//#endregion
+//#region src/components/session-error-banner.tsx
+/** @jsxImportSource react */
+/**
+* The announced banner for a failed session: the error's message and code, or
+* nothing at all when the session is fine.
+*
+* **This used to be four lines inside `ConsoleShell`, and that is why it is its
+* own component.** The banner was the reason `ConsoleShell` was published —
+* `role="alert"` is the one part of that component a reviewer cannot see is
+* missing, since per the `fatalError` latch in `session/browser-session.ts` the banner is
+* the ONLY remaining signal a session died (the state eyebrow beside it goes
+* back to reading like a live session), and a screen reader is never told an
+* unannounced one appeared. But `ConsoleShell` is a whole FRAME: a centred
+* `max-w-190` column with its own header and footer. Every full-bleed chrome —
+* a two-pane board, a CRT — therefore could not adopt it, rebuilt the banner
+* instead, and the three that did had ALREADY drifted: one rendered
+* `ERROR: {message}` and dropped the code entirely, one `ERROR: {message}
+* ({code})`, one `{message} ({code})`. Splitting the banner out is what lets a
+* chrome take the announced-error decision without taking the layout, and
+* `ConsoleShell` composes this rather than keeping a second copy, so the two
+* cannot drift again.
+*
+* **It reads the session itself.** There is no `error` prop: a banner that
+* takes its text from the caller is a banner a caller can forget to wire, which
+* is exactly the failure above with an extra step. It subscribes narrowly via
+* {@link useSessionError}, so a page that renders it does not re-render with
+* the transcript.
+*
+* **The code is shown, always.** `SessionError.code` is the eight-member wire
+* union — it is what a user pastes into a bug report and the only part of the
+* error that is stable across wordings — and the chrome that dropped it left
+* its readers with a sentence and no way to say which failure it was.
+*
+* Must be rendered inside the providers `client()` installs.
+*
+* @example A full-bleed chrome that wants the banner and not the frame
+* ```tsx
+* import { SessionErrorBanner } from "@alexkroman1/aai-ui";
+*
+* function Board() {
+*   return (
+*     <div className="grid grid-cols-[1fr_320px] h-screen">
+*       <main>…</main>
+*       <aside>…</aside>
+*       <SessionErrorBanner className="col-span-2" />
+*     </div>
+*   );
+* }
+* ```
+*
+* @param props - See {@link SessionErrorBannerProps}.
+*
+* @public
+*/
+function SessionErrorBanner({ className }) {
+	const error = useSessionError();
+	if (!error) return null;
+	return /* @__PURE__ */ jsxs("div", {
+		role: "alert",
+		className: clsx("px-3.5 py-2.5 rounded-aai border text-[13px] leading-[130%] shrink-0", className),
+		style: {
+			borderColor: "rgba(179,38,30,0.35)",
+			background: "rgba(179,38,30,0.06)",
+			color: ERROR_COLOR
+		},
+		children: [
+			error.message,
+			" (",
+			error.code,
+			")"
+		]
+	});
+}
+//#endregion
+//#region src/components/session-state-dot.tsx
+/** @jsxImportSource react */
+/**
+* One `aai-pulse` cycle per pulsing state, in milliseconds. The two states
+* that pulse are the two in which the agent is DOING something the reader
+* cannot otherwise see — the microphone is open, or a reply is being worked
+* out — and `thinking` beats faster because it is the shorter wait. `speaking`
+* has the audio itself for a signal and stays still.
+*/
+const PULSE_MS = {
+	listening: 1500,
+	thinking: 800
+};
+/**
+* The dot itself: a coloured circle, pulsing or still.
+*
+* Shared by {@link SessionStateDot} and `ConsoleShell`, which computes its
+* colour from the theme rather than from a palette prop and decides for itself
+* when to pulse. Not on the package barrel — the public component is the one
+* that reads the session.
+*
+* The colour is written to `background` AND `color`, so a caller can extend
+* the dot with a `currentColor` utility (`shadow-[0_0_6px_currentColor]` for a
+* glow) without restating the palette.
+*
+* @internal
+*/
+function StateDot({ color, pulseMs, className, title }) {
+	return /* @__PURE__ */ jsx("span", {
+		className: clsx("rounded-full inline-block shrink-0", className),
+		style: {
+			background: color,
+			color,
+			animation: pulseMs === null ? "none" : `aai-pulse ${pulseMs}ms ease-in-out infinite`
+		},
+		title
+	});
+}
+/**
+* The live session state as a coloured dot and a word, on its own narrow
+* subscription.
+*
+* Three custom chromes had each written this: a `satisfies Record<AgentState,
+* string>` palette (kept — it is the prop), a `STATE_LABELS` spread over
+* {@link AGENT_STATE_LABELS} (kept — it is `labels`), and then the same
+* fourteen lines of markup around them, including the same two-arm ternary
+* deciding which states pulse and how fast. `agent-state-labels.ts` argued
+* against a dot component on the grounds that it would take the shared part
+* (the words) hostage to the part that is not (the palette); this takes the
+* palette as a prop precisely so it does not. What is shared is the structure
+* — the exhaustive colour lookup, the label fallback, the pulse rule, the
+* `useSessionStatus()` subscription that keeps the rest of the header from
+* re-rendering at STT-partial rate.
+*
+* Must be rendered inside the providers `mountClient()` installs.
+*
+* @example A dispatch board's readout: its own colours, three of its own words
+* ```tsx
+* import type { AgentState } from "@alexkroman1/aai-ui";
+* import { SessionStateDot } from "@alexkroman1/aai-ui";
+*
+* const STATE_COLORS = {
+*   disconnected: "#6b7280",
+*   connecting: "#6b7280",
+*   ready: "#22c55e",
+*   listening: "#22c55e",
+*   thinking: "#eab308",
+*   speaking: "#3b82f6",
+*   error: "#6b7280",
+* } satisfies Record<AgentState, string>;
+*
+* function StatusReadout() {
+*   return (
+*     <SessionStateDot
+*       colors={STATE_COLORS}
+*       labels={{ listening: "LISTENING", thinking: "PROCESSING", speaking: "TRANSMITTING" }}
+*       labelClassName="text-[11px] uppercase"
+*     />
+*   );
+* }
+* ```
+*
+* @param props - See {@link SessionStateDotProps}.
+*
+* @public
+*/
+function SessionStateDot({ colors, labels, pulse = true, className, dotClassName, labelClassName }) {
+	const state = useSessionStatus();
+	const pulseMs = pulse ? PULSE_MS[state] ?? null : null;
+	return /* @__PURE__ */ jsxs("span", {
+		className: clsx("inline-flex items-center gap-2", className),
+		"data-state": state,
+		children: [/* @__PURE__ */ jsx(StateDot, {
+			color: colors[state],
+			pulseMs,
+			className: dotClassName ?? "w-2 h-2",
+			title: state
+		}), /* @__PURE__ */ jsx("span", {
+			className: labelClassName,
+			children: labels?.[state] ?? AGENT_STATE_LABELS[state]
+		})]
+	});
+}
+//#endregion
+//#region src/components/console-shell.tsx
+/** @jsxImportSource react */
+/**
+* Indicator dot color per state.
+*
+* `idle` is the theme's own faint ink step rather than a fixed warm grey, so
+* the dot stays visible on a dark ground; the thinking amber and error red
+* are semantic and stay fixed.
+*
+* @internal
+*/
+function stateColor(state, primary, idle) {
+	switch (state) {
+		case "listening":
+		case "speaking":
+		case "ready": return primary;
+		case "thinking": return THINKING_COLOR;
+		case "error": return ERROR_COLOR;
+		default: return idle;
+	}
+}
+/**
+* The design-system "console" chrome: a 760px column on the themed page with a
+* header (icon + live-status eyebrow), an announced error banner, the main
+* content on a raised card, and a footer row beneath it.
+*
+* {@link ChatView} is this shell with `<MessageList>` inside it and
+* `<Controls>` under it, and until now that was the only way to get it — the
+* shell itself was internal, so a client wanting its own conversation markup
+* had to rebuild the chrome as well. Each one that did re-derived the error
+* banner WITHOUT `role="alert"`.
+*
+* **The banner is {@link SessionErrorBanner} now, composed here rather than
+* spelled out.** It was four lines of this file, and this file is a whole
+* FRAME — a centred `max-w-190` column — so the full-bleed chromes that needed
+* the announced banner could not take it without taking a layout that would
+* replace the design they exist to demonstrate. Composing means there is one
+* banner, and it means this component no longer takes an `error` prop: the
+* banner reads the session itself, which is one fewer thing a caller can wire
+* up wrong.
+*
+* Reach for it when the conversation is yours and the frame is not. Reach for
+* `<ChatView>` when both are ours. Reach for `<SessionErrorBanner>` alone when
+* neither is.
+*
+* Must be rendered inside the providers `mountClient()` installs.
+*
+* @example A custom conversation in the stock chrome
+* ```tsx
+* import {
+*   ConsoleShell,
+*   Controls,
+*   useConversation,
+*   useSessionStatus,
+* } from "@alexkroman1/aai-ui";
+*
+* function Console() {
+*   const state = useSessionStatus();
+*   const { items } = useConversation();
+*   return (
+*     <ConsoleShell
+*       title="Dispatch"
+*       state={state}
+*       pulsing={state === "listening"}
+*       footer={<Controls />}
+*     >
+*       <ul>
+*         {items.map((item) => (
+*           <li key={item.kind === "message" ? item.message.id : item.toolCall.callId}>
+*             {item.kind === "message" ? item.message.content : item.toolCall.name}
+*           </li>
+*         ))}
+*       </ul>
+*     </ConsoleShell>
+*   );
+* }
+* ```
+*
+* @param props - See {@link ConsoleShellProps}.
+*
+* @public
+*/
+function ConsoleShell({ icon, title, state, pulsing, children, footer, className }) {
+	const theme = useTheme();
+	return /* @__PURE__ */ jsxs("div", {
+		className: clsx("flex flex-col h-screen w-full max-w-190 mx-auto box-border px-6 py-8 gap-5 font-aai text-sm", className),
+		style: {
+			background: theme.bg,
+			color: theme.text
+		},
+		children: [
+			/* @__PURE__ */ jsxs("div", {
+				className: "flex items-center justify-between shrink-0",
+				children: [/* @__PURE__ */ jsxs("div", {
+					className: "flex items-center gap-3 min-w-0",
+					children: [icon ?? /* @__PURE__ */ jsx(AaiLogo, { size: 22 }), title && /* @__PURE__ */ jsx("span", {
+						className: "font-aai-serif text-[22px] leading-[1.2] font-normal truncate",
+						style: { color: theme.text },
+						children: title
+					})]
+				}), /* @__PURE__ */ jsxs(Eyebrow, {
+					className: "shrink-0",
+					"data-state": state,
+					children: [/* @__PURE__ */ jsx(StateDot, {
+						color: stateColor(state, theme.primary, inkTint(theme.text, theme.bg, 65)),
+						pulseMs: pulsing ? 1600 : null,
+						className: "w-[7px] h-[7px]"
+					}), state]
+				})]
+			}),
+			/* @__PURE__ */ jsx(SessionErrorBanner, {}),
+			/* @__PURE__ */ jsx("div", {
+				className: "flex flex-col flex-1 min-h-0 border rounded-lg overflow-hidden",
+				style: {
+					background: theme.surface,
+					borderColor: theme.border,
+					boxShadow: "0 1px 3px 0 rgb(20 18 12 / 0.06)"
+				},
+				children
+			}),
+			footer
+		]
+	});
+}
+//#endregion
+//#region src/components/chat-view.tsx
+const PULSING_STATES = /* @__PURE__ */ new Set(["listening", "speaking"]);
+/**
+* The main chat interface for a voice agent session — the design-system
+* "voice agent console": a 760px column on the cream page with a header
+* (logo + live-status eyebrow), the conversation on a raised white card,
+* and the session controls beneath it.
+*
+* Must be rendered inside a `SessionProvider`.
+*
+* @example
+* ```tsx
+* import { ChatView, StartScreen } from "@alexkroman1/aai-ui";
+*
+* function App() {
+*   return (
+*     <StartScreen icon="🍕" title="Pizza Palace">
+*       <ChatView />
+*     </StartScreen>
+*   );
+* }
+* ```
+*
+* @param props - Chat surface props.
+*
+* @public
+*/
+function ChatView({ icon, title, className }) {
+	const state = useSessionStatus();
+	return /* @__PURE__ */ jsx(ConsoleShell, {
+		icon,
+		title,
+		state,
+		pulsing: PULSING_STATES.has(state),
+		className,
+		footer: /* @__PURE__ */ jsx(Controls, {}),
+		children: /* @__PURE__ */ jsx(MessageList, {})
+	});
+}
+//#endregion
+export { AGENT_STATE_LABELS as a, SessionErrorBanner as i, ConsoleShell as n, SessionStateDot as r, ChatView as t };

package/dist/client-config-C7fQrioM.js

@@ -0,0 +1,139 @@
+import { n as pageBaseUrl } from "./_utils-Mi-SCFA1.js";
+import { CLIENT_CONFIG_PATH, ClientConfigResponseSchema, SESSION_TICKET_HEADER } from "@alexkroman1/aai/protocol";
+//#region src/client-config.ts
+/**
+* Pre-connection client-config lookup.
+*
+* `GET client-config` (relative to the agent's base URL — see
+* `sdk/client-config.ts` in `@alexkroman1/aai`) gives the default client the
+* agent's display name and greeting before any connection exists. For that
+* use every failure path — network error, 404 from an older server,
+* malformed body — degrades to the empty default (`fetchClientConfig`), so
+* the lookup can never break an existing agent.
+*
+* The session's broker decision needs the opposite: `loadClientConfig`
+* keeps "the lookup failed" (`null`) distinct from "the server answered and
+* named no sessionUrl" (`{}`). See its doc comment.
+*/
+/**
+* Resolve a relative endpoint path against the agent's base URL.
+*
+* @internal
+*/
+function buildAgentUrl(platformUrl, endpointPath) {
+	return new URL(endpointPath, platformUrl.endsWith("/") ? platformUrl : `${platformUrl}/`);
+}
+const AGENT_DEFAULT = { page: "voice" };
+/**
+* Per-attempt deadline for the `client-config` lookup.
+*
+* A request issued while the platform is restarting or saturated can HANG
+* rather than fail — the proxy holds the socket open — and a browser fetch
+* has no timeout of its own. Every other failure here is already handled
+* (`null`, then the same-origin fallback), but a hang is not a failure: the
+* promise simply never settles.
+*
+* That is unrecoverable rather than merely slow, because this lookup runs
+* inside the session's WebSocket URL *provider*. partysocket awaits the
+* provider under `_connectLock` and arms its own `connectionTimeout` only
+* AFTER the URL resolves, so a hung lookup means no socket is ever
+* constructed, no `error`/`close` ever fires, and none of the 10 reconnect
+* attempts ever happen — the session sits on "connecting" forever, and stays
+* there long after the server is back. Reproduced: zero sockets opened.
+*
+* A timed-out attempt therefore degrades exactly like any other failed one —
+* `null`, so `configPerAttempt` stays unlatched and the attempt falls through
+* to the same-origin `websocket` path, whose failure re-enters the normal
+* backoff and re-fetches this on the next attempt.
+*
+* Sized well above the real work (one same-origin JSON GET that reads the
+* agent's row) and well under a user's patience — the same 10s the studio's
+* gating reads use for the identical hazard.
+*
+* @internal
+*/
+const CLIENT_CONFIG_ATTEMPT_TIMEOUT_MS = 1e4;
+/**
+* Fetch the agent's client config, reporting `null` when the lookup did not
+* produce an answer (network error, non-2xx, unparsable body).
+*
+* The distinction from `fetchClientConfig` matters for exactly one caller:
+* the session's per-attempt broker decision. A config that ARRIVED and named
+* no `sessionUrl` means "this server is not a broker" (`aai dev`, an older
+* server) — a durable fact worth latching. A lookup that FAILED means
+* nothing about the server, and treating the two alike is how a single 503
+* (a sandbox mid-boot, or one that failed to start) pinned a session to the
+* platform's `/:slug/websocket` — a WebSocket redirect browsers don't
+* follow, so every retry failed with no re-brokering even after the agent
+* recovered.
+*
+* @internal
+*/
+async function loadClientConfig(platformUrl, fetchFn, presentedTicket) {
+	const doFetch = fetchFn ?? ((input, init) => globalThis.fetch(input, init));
+	try {
+		const resp = await doFetch(buildAgentUrl(platformUrl, CLIENT_CONFIG_PATH).href, {
+			signal: AbortSignal.timeout(CLIENT_CONFIG_ATTEMPT_TIMEOUT_MS),
+			...presentedTicket === void 0 ? {} : { headers: { [SESSION_TICKET_HEADER]: presentedTicket } }
+		});
+		if (!resp.ok) return null;
+		const parsed = ClientConfigResponseSchema.safeParse(await resp.json());
+		return parsed.success ? parsed.data : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Fetch the agent's declared `name`, `greeting` and front door; any failure
+* yields the agent default (`{}`).
+*
+* **This is what a workflow app's own component calls instead of receiving the
+* config.** Both mounts fetch `GET client-config` for the shell they render
+* themselves — `mountClient()` for the chat shell, `mountPage()` for the
+* generated workflow shell — so neither DEFAULT has to be told the agent's
+* name. A `component:` replaces that shell, and with it the lookup, so a page
+* that wants the agent's own `name` or `greeting` asks for them here.
+*
+* Every failure path degrades to the empty default rather than throwing: a
+* network error, a 404 from a server older than the endpoint, a malformed
+* body, and a lookup that hangs past
+* `CLIENT_CONFIG_ATTEMPT_TIMEOUT_MS` all read as "the agent declared nothing".
+* So a page may render straight from the result and never needs a `catch` —
+* treat every field as optional, because an agent that declared none is a
+* normal agent.
+*
+* @param platformUrl - The agent's base URL. **Defaults to the page's own
+* origin and path** (`pageBaseUrl()`), which is the agent that served the page
+* and the only case a browser has — the argument was required while the default
+* sat one module away in this same package, so every caller wrote
+* `location.origin + location.pathname` for itself. Pass one for a page reading
+* a DIFFERENT agent. The endpoint is resolved relative to it.
+* @param fetchFn - Fetch implementation, for tests and for a caller that
+* supplies its own credentials. Defaults to the global `fetch`.
+* @returns The agent's config, or `{}` when the lookup produced no answer.
+*
+* @example
+* ```tsx
+* import { fetchClientConfig, mountPage } from "@alexkroman1/aai-ui";
+*
+* const { name, greeting } = await fetchClientConfig();
+*
+* function App() {
+*   return (
+*     <main>
+*       <h1>{name ?? "Workflows"}</h1>
+*       {greeting ? <p>{greeting}</p> : null}
+*     </main>
+*   );
+* }
+*
+* mountPage({ name: name ?? "Workflows", component: App });
+* ```
+*
+* @public
+*/
+async function fetchClientConfig(platformUrl = pageBaseUrl(), fetchFn) {
+	return await loadClientConfig(platformUrl, fetchFn) ?? AGENT_DEFAULT;
+}
+//#endregion
+export { fetchClientConfig as n, loadClientConfig as r, buildAgentUrl as t };

package/dist/client-config.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Pre-connection client-config lookup.
+ *
+ * `GET client-config` (relative to the agent's base URL — see
+ * `sdk/client-config.ts` in `@alexkroman1/aai`) gives the default client the
+ * agent's display name and greeting before any connection exists. For that
+ * use every failure path — network error, 404 from an older server,
+ * malformed body — degrades to the empty default (`fetchClientConfig`), so
+ * the lookup can never break an existing agent.
+ *
+ * The session's broker decision needs the opposite: `loadClientConfig`
+ * keeps "the lookup failed" (`null`) distinct from "the server answered and
+ * named no sessionUrl" (`{}`). See its doc comment.
+ */
+import { type ClientConfigResponse } from "@alexkroman1/aai/protocol";
+/** @internal Re-exported for the sibling modules; the SDK's `/protocol` subpath is the canonical home. */
+export type { ClientConfigResponse } from "@alexkroman1/aai/protocol";
+/**
+ * Resolve a relative endpoint path against the agent's base URL.
+ *
+ * @internal
+ */
+export declare function buildAgentUrl(platformUrl: string, endpointPath: string): URL;
+/**
+ * Per-attempt deadline for the `client-config` lookup.
+ *
+ * A request issued while the platform is restarting or saturated can HANG
+ * rather than fail — the proxy holds the socket open — and a browser fetch
+ * has no timeout of its own. Every other failure here is already handled
+ * (`null`, then the same-origin fallback), but a hang is not a failure: the
+ * promise simply never settles.
+ *
+ * That is unrecoverable rather than merely slow, because this lookup runs
+ * inside the session's WebSocket URL *provider*. partysocket awaits the
+ * provider under `_connectLock` and arms its own `connectionTimeout` only
+ * AFTER the URL resolves, so a hung lookup means no socket is ever
+ * constructed, no `error`/`close` ever fires, and none of the 10 reconnect
+ * attempts ever happen — the session sits on "connecting" forever, and stays
+ * there long after the server is back. Reproduced: zero sockets opened.
+ *
+ * A timed-out attempt therefore degrades exactly like any other failed one —
+ * `null`, so `configPerAttempt` stays unlatched and the attempt falls through
+ * to the same-origin `websocket` path, whose failure re-enters the normal
+ * backoff and re-fetches this on the next attempt.
+ *
+ * Sized well above the real work (one same-origin JSON GET that reads the
+ * agent's row) and well under a user's patience — the same 10s the studio's
+ * gating reads use for the identical hazard.
+ *
+ * @internal
+ */
+export declare const CLIENT_CONFIG_ATTEMPT_TIMEOUT_MS = 10000;
+/**
+ * Fetch the agent's client config, reporting `null` when the lookup did not
+ * produce an answer (network error, non-2xx, unparsable body).
+ *
+ * The distinction from `fetchClientConfig` matters for exactly one caller:
+ * the session's per-attempt broker decision. A config that ARRIVED and named
+ * no `sessionUrl` means "this server is not a broker" (`aai dev`, an older
+ * server) — a durable fact worth latching. A lookup that FAILED means
+ * nothing about the server, and treating the two alike is how a single 503
+ * (a sandbox mid-boot, or one that failed to start) pinned a session to the
+ * platform's `/:slug/websocket` — a WebSocket redirect browsers don't
+ * follow, so every retry failed with no re-brokering even after the agent
+ * recovered.
+ *
+ * @internal
+ */
+export declare function loadClientConfig(platformUrl: string, fetchFn?: typeof globalThis.fetch, presentedTicket?: string): Promise<ClientConfigResponse | null>;
+/**
+ * Fetch the agent's declared `name`, `greeting` and front door; any failure
+ * yields the agent default (`{}`).
+ *
+ * **This is what a workflow app's own component calls instead of receiving the
+ * config.** Both mounts fetch `GET client-config` for the shell they render
+ * themselves — `mountClient()` for the chat shell, `mountPage()` for the
+ * generated workflow shell — so neither DEFAULT has to be told the agent's
+ * name. A `component:` replaces that shell, and with it the lookup, so a page
+ * that wants the agent's own `name` or `greeting` asks for them here.
+ *
+ * Every failure path degrades to the empty default rather than throwing: a
+ * network error, a 404 from a server older than the endpoint, a malformed
+ * body, and a lookup that hangs past
+ * `CLIENT_CONFIG_ATTEMPT_TIMEOUT_MS` all read as "the agent declared nothing".
+ * So a page may render straight from the result and never needs a `catch` —
+ * treat every field as optional, because an agent that declared none is a
+ * normal agent.
+ *
+ * @param platformUrl - The agent's base URL. **Defaults to the page's own
+ * origin and path** (`pageBaseUrl()`), which is the agent that served the page
+ * and the only case a browser has — the argument was required while the default
+ * sat one module away in this same package, so every caller wrote
+ * `location.origin + location.pathname` for itself. Pass one for a page reading
+ * a DIFFERENT agent. The endpoint is resolved relative to it.
+ * @param fetchFn - Fetch implementation, for tests and for a caller that
+ * supplies its own credentials. Defaults to the global `fetch`.
+ * @returns The agent's config, or `{}` when the lookup produced no answer.
+ *
+ * @example
+ * ```tsx
+ * import { fetchClientConfig, mountPage } from "@alexkroman1/aai-ui";
+ *
+ * const { name, greeting } = await fetchClientConfig();
+ *
+ * function App() {
+ *   return (
+ *     <main>
+ *       <h1>{name ?? "Workflows"}</h1>
+ *       {greeting ? <p>{greeting}</p> : null}
+ *     </main>
+ *   );
+ * }
+ *
+ * mountPage({ name: name ?? "Workflows", component: App });
+ * ```
+ *
+ * @public
+ */
+export declare function fetchClientConfig(platformUrl?: string, fetchFn?: typeof globalThis.fetch): Promise<ClientConfigResponse>;