@alexkroman1/aai-ui 0.12.3 → 0.14.0

package/dist/context.d.ts

@@ -0,0 +1,288 @@
+import { type ReactNode } from "react";
+import type { BrowserSession, SendTextOptions, SessionSnapshot } from "./session/index.ts";
+import type { AgentState, ClientTheme, SessionError } from "./types.ts";
+/**
+ * Provides the {@link BrowserSession} the session hooks read. `mountClient()`
+ * installs it automatically; a custom tree only needs it when bypassing
+ * `mountClient()` and mounting React itself.
+ *
+ * @internal
+ */
+export declare function SessionProvider({ value, children, }: {
+    value: BrowserSession;
+    children?: ReactNode;
+}): import("react").FunctionComponentElement<import("react").ProviderProps<BrowserSession | null>>;
+/**
+ * The session's control methods, and nothing else — what a `client.tsx` may
+ * legitimately CALL on a session, as against what it may read.
+ *
+ * Declared once and merged into {@link Session} rather than written out at both
+ * places: the two lists have to be the same list, and a member added to one and
+ * not the other is a hook that cannot do what `useSession()` can.
+ *
+ * DECLARED here rather than picked out of {@link BrowserSession}: that handle is
+ * sealed and grows, and a `Pick` made every member it gained a candidate for
+ * this list without anyone deciding. Push-to-talk is the case in point — its
+ * three edges are `session.userTurn`, reached through `usePushToTalk`, and not
+ * actions every chrome is handed. `createBrowserSession` is what keeps each of
+ * these assignable from the session's own methods.
+ *
+ * @public
+ */
+export type SessionActions = {
+    /** Start the call for the first time — see {@link BrowserSession.start}. */
+    start(): void;
+    /** Cancel the current agent turn and discard in-flight TTS audio. */
+    cancel(): void;
+    /** Send a typed user turn, answered as if spoken — see {@link BrowserSession.sendText}. */
+    sendText(text: string, options?: SendTextOptions): void;
+    /** Mute or unmute the mic without dropping the session — see {@link BrowserSession.setMicMuted}. */
+    setMicMuted(muted: boolean): void;
+    /** Clear messages, transcripts and error state, keeping the connection. */
+    resetState(): void;
+    /** Clear state and reopen the connection — the same session id. */
+    reset(): void;
+    /** End the call and begin a fresh one — see {@link BrowserSession.restart}. */
+    restart(): void;
+    /** Continue an earlier session by its id — see {@link BrowserSession.resume}. */
+    resume(sessionId: string): void;
+    /** Close the WebSocket and release all audio resources. */
+    disconnect(): void;
+    /** Toggle between connected and disconnected (after `start()`). */
+    toggle(): void;
+    /** End the call and return to the not-started state — see {@link BrowserSession.end}. */
+    end(): void;
+};
+/**
+ * What {@link useSession} returns: the live {@link SessionSnapshot} fields
+ * (`state`, `messages`, `toolCalls`, `agentState`, live transcripts, `error`,
+ * `apiUrl`, `started`/`running`/`recording`, …) merged with the session's
+ * control methods (`start`, `toggle`, `reset`, `restart`, `resume`, `resetState`,
+ * `disconnect`, `cancel`, `end`, `sendText`, `setMicMuted`).
+ *
+ * `sendText(text)` is the one input besides the microphone: a typed turn the
+ * agent answers aloud, as if it had been spoken.
+ *
+ * @public
+ */
+export type Session = SessionSnapshot & SessionActions;
+/**
+ * Return the raw {@link BrowserSession} from context without subscribing to
+ * snapshot changes. Useful for accessing stable methods (`start`, `toggle`,
+ * `reset`, …) from components that select narrow state via
+ * {@link useSessionSelector}.
+ *
+ * Not part of the package's public export surface — internal to aai-ui
+ * components.
+ */
+export declare function useSessionCore(): BrowserSession;
+/** The session from context, or `null` outside the provider (`useRoute` on a `mountPage()` page). */
+export declare function useOptionalSessionCore(): BrowserSession | null;
+/**
+ * The session's control methods — `start`, `cancel`, `sendText`,
+ * `setMicMuted`, `resetState`, `reset`, `restart`, `resume`, `disconnect`,
+ * `toggle`, `end` — with **no snapshot subscription**.
+ * Push-to-talk is not among them: that is `usePushToTalk`.
+ *
+ * This is the narrow half of {@link useSession}, and it is the half a custom
+ * chrome could not reach. `<Controls>` and `<StartScreen>` in this package pair
+ * a one-field `useSessionSelector` with this package's own `useSessionCore`
+ * (`context.ts`, unpublished); a `client.tsx`
+ * could not, because that hook is not published — so a footer needing `start`
+ * and `toggle` held a WHOLE-SNAPSHOT `useSession()`, and `session/browser-session.ts`
+ * rebuilds the snapshot object on every change. Measured consequence: four
+ * components across three templates re-rendered on every STT partial and every
+ * streaming delta, in files whose every other component is narrowly subscribed
+ * on purpose. One of them (`text-adventure-agent`'s `TitleScreen`) reads nothing
+ * from the snapshot at all and subscribes to all of it for `session.start`.
+ *
+ * **Why publishing this does not reopen what `/internal` closed.**
+ * `useSessionCore` hands back the STORE — `subscribe`, `getSnapshot`,
+ * `connect`, `Symbol.dispose` — which is the framework's own plumbing, the same
+ * category as the providers and `buildAgentUrl` that live on
+ * `@alexkroman1/aai-ui/internal`. A client that holds it can subscribe out of
+ * band of React, dial a socket the mount did not, and dispose the session under
+ * the tree that is rendering it. What comes back from here is the SAME
+ * methods `useSession()` already publishes on its result, built into a fresh
+ * object rather than passed through, so the store is not reachable from it.
+ * There is no new capability here — only the existing one without the
+ * subscription tax.
+ *
+ * Identity-stable per core, so it is safe in a dependency array and in a
+ * `memo()` child's props: the methods are closures created once by
+ * `createBrowserSession`, and the object wrapping them is memoized on the core.
+ *
+ * Throws outside the provider `mountClient()` installs, like every session hook.
+ *
+ * @example A footer that acts on the session without re-rendering with it
+ * ```tsx
+ * import { useSessionActions, useSessionSelector } from "@alexkroman1/aai-ui";
+ *
+ * function Footer() {
+ *   // Two narrow subscriptions and no snapshot read: this row re-renders when
+ *   // `running` flips, and not on every transcript delta.
+ *   const running = useSessionSelector((s) => s.running);
+ *   const { toggle, end } = useSessionActions();
+ *   return (
+ *     <>
+ *       <button onClick={toggle}>{running ? "Pause" : "Resume"}</button>
+ *       <button onClick={end}>Hang up</button>
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @returns The control methods — see {@link SessionActions}.
+ *
+ * @public
+ */
+export declare function useSessionActions(): SessionActions;
+/**
+ * Return the live {@link Session}: the current snapshot fields plus the
+ * control methods (`start`, `toggle`, `reset`, `resetState`, `disconnect`,
+ * `cancel`, `end`).
+ *
+ * Throws if used outside the provider `mountClient()` installs (the error names
+ * `<SessionProvider>` — you only mount that yourself when bypassing
+ * `mountClient()`). Re-renders the component on *every* snapshot change; for a
+ * component that reads one field, prefer {@link useSessionSelector} for a
+ * targeted subscription.
+ *
+ * @example
+ * ```tsx
+ * import { useSession } from "@alexkroman1/aai-ui";
+ *
+ * function Controls() {
+ *   const session = useSession();
+ *   if (!session.started) return <button onClick={session.start}>Start</button>;
+ *   return <button onClick={session.toggle}>{session.running ? "Pause" : "Resume"}</button>;
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function useSession(): Session;
+/**
+ * Subscribe to a narrow slice of the session snapshot.
+ *
+ * Unlike {@link useSession} — which re-renders the component on *every*
+ * snapshot change — this only triggers a re-render when the selected value
+ * changes (per `isEqual`, default `Object.is`). Use it for components that
+ * read a single field, e.g. `useSessionSelector((s) => s.running)`.
+ *
+ * The selector must be pure. It may run on every snapshot change, so keep it
+ * cheap; when it returns a derived object, pass a custom `isEqual` to avoid
+ * re-renders on referentially-new-but-equal results.
+ *
+ * @example
+ * ```tsx
+ * import { useSessionSelector } from "@alexkroman1/aai-ui";
+ *
+ * // Re-renders when `running` flips, and on nothing else — not on every
+ * // transcript delta the way `useSession()` would.
+ * function MicDot() {
+ *   const running = useSessionSelector((snapshot) => snapshot.running);
+ *   return <span>{running ? "●" : "○"}</span>;
+ * }
+ * ```
+ *
+ * @param selector - Reads the slice out of the snapshot. Must be pure.
+ * @param isEqual - Compares two selected values. Defaults to `Object.is`.
+ * @returns The selected slice.
+ *
+ * @public
+ */
+export declare function useSessionSelector<T>(selector: (snapshot: SessionSnapshot) => T, isEqual?: (a: T, b: T) => boolean): T;
+/**
+ * The agent's live {@link AgentState} — `disconnected`, `connecting`, `ready`,
+ * `listening`, `thinking`, `speaking`, `error` — on its own narrow
+ * subscription.
+ *
+ * `useSessionSelector((s) => s.state)` spelled once. It is one of exactly two
+ * snapshot fields that more than one custom chrome ever selects (the other is
+ * {@link useSessionError}), and it had been written inline at eight sites —
+ * including inside this package and, worse, in `ConsoleShell`'s own `@example`,
+ * which taught the inline form to everyone who read it.
+ *
+ * **Named `useSessionStatus`, not `useSessionState`.** `useAgentState` is the
+ * SLOT hook — the agent's own synced application state, whatever a
+ * `sessionSlot()` projects — and `AgentState` here is the phase of the CALL.
+ * Two different concepts one letter apart, so the shorter-sounding name is the
+ * one deliberately not taken.
+ *
+ * Pair it with {@link AGENT_STATE_LABELS} for a rendered word; the raw member
+ * is a wire value, not a label.
+ *
+ * @example
+ * ```tsx
+ * import { AGENT_STATE_LABELS, useSessionStatus } from "@alexkroman1/aai-ui";
+ *
+ * function StatusDot() {
+ *   const status = useSessionStatus();
+ *   return <span data-state={status}>{AGENT_STATE_LABELS[status]}</span>;
+ * }
+ * ```
+ *
+ * @returns The current agent state.
+ *
+ * @public
+ */
+export declare function useSessionStatus(): AgentState;
+/**
+ * The session's current {@link SessionError}, or `null` when there is none, on
+ * its own narrow subscription.
+ *
+ * The other half of {@link useSessionStatus} — the second of the two fields a
+ * custom chrome reads over and over, and the one whose absence is invisible:
+ * per the `fatalError` latch in `session/browser-session.ts` the error is the ONLY
+ * remaining signal that a session died, since the state beside it goes back to
+ * reading like a live one.
+ *
+ * A chrome rendering it owes `role="alert"` — which is what
+ * {@link SessionErrorBanner} is for, and why reaching for that beats reaching
+ * for this.
+ *
+ * @returns The current error, or `null`.
+ *
+ * @public
+ */
+export declare function useSessionError(): SessionError | null;
+/**
+ * Provides the theme the components read via `useTheme`. `mountClient()` installs
+ * it automatically (from `ClientConfig.theme`); a custom tree only needs it
+ * when bypassing `mountClient()` and mounting React itself.
+ *
+ * @internal
+ */
+export declare function ThemeProvider({ value, children, }: {
+    value?: ClientTheme | undefined;
+    children?: ReactNode;
+}): import("react").FunctionComponentElement<import("react").ProviderProps<Required<ClientTheme>>>;
+/**
+ * Read the resolved theme (every {@link ClientTheme} field filled with its
+ * default) from the nearest theme context. Returns the default theme when no
+ * provider is present, so components can call it unconditionally.
+ *
+ * This is how a custom component stays on the agent's palette: a
+ * `mountClient({ theme })` override reaches it here, where a hardcoded colour or a
+ * Tailwind class cannot see it.
+ *
+ * @example
+ * ```tsx
+ * import { useTheme } from "@alexkroman1/aai-ui";
+ *
+ * function Total({ amount }: { amount: string }) {
+ *   const theme = useTheme();
+ *   return (
+ *     <strong style={{ color: theme.primary, background: theme.surface }}>
+ *       {amount}
+ *     </strong>
+ *   );
+ * }
+ * ```
+ *
+ * @returns Every {@link ClientTheme} field, filled in.
+ *
+ * @public
+ */
+export declare function useTheme(): Required<ClientTheme>;

package/dist/context.js

@@ -0,0 +1,382 @@
+import { createContext, createElement, useContext, useEffect, useMemo, useSyncExternalStore } from "react";
+import { useSyncExternalStoreWithSelector } from "use-sync-external-store/with-selector";
+//#region src/context.ts
+const DEFAULT_THEME = {
+	bg: "#FBF8F2",
+	primary: "#3F2BC1",
+	text: "#1B1A18",
+	surface: "#FFFFFF",
+	border: "#DCD7CC"
+};
+const SessionCtx = createContext(null);
+/**
+* Provides the {@link BrowserSession} the session hooks read. `mountClient()`
+* installs it automatically; a custom tree only needs it when bypassing
+* `mountClient()` and mounting React itself.
+*
+* @internal
+*/
+function SessionProvider({ value, children }) {
+	return createElement(SessionCtx.Provider, { value }, children);
+}
+/**
+* Return the raw {@link BrowserSession} from context without subscribing to
+* snapshot changes. Useful for accessing stable methods (`start`, `toggle`,
+* `reset`, …) from components that select narrow state via
+* {@link useSessionSelector}.
+*
+* Not part of the package's public export surface — internal to aai-ui
+* components.
+*/
+function useSessionCore() {
+	const core = useContext(SessionCtx);
+	if (!core) throw new Error("Session hooks must be used within <SessionProvider>");
+	return core;
+}
+/** The session from context, or `null` outside the provider (`useRoute` on a `mountPage()` page). */
+function useOptionalSessionCore() {
+	return useContext(SessionCtx);
+}
+/**
+* The session's control methods — `start`, `cancel`, `sendText`,
+* `setMicMuted`, `resetState`, `reset`, `restart`, `resume`, `disconnect`,
+* `toggle`, `end` — with **no snapshot subscription**.
+* Push-to-talk is not among them: that is `usePushToTalk`.
+*
+* This is the narrow half of {@link useSession}, and it is the half a custom
+* chrome could not reach. `<Controls>` and `<StartScreen>` in this package pair
+* a one-field `useSessionSelector` with this package's own `useSessionCore`
+* (`context.ts`, unpublished); a `client.tsx`
+* could not, because that hook is not published — so a footer needing `start`
+* and `toggle` held a WHOLE-SNAPSHOT `useSession()`, and `session/browser-session.ts`
+* rebuilds the snapshot object on every change. Measured consequence: four
+* components across three templates re-rendered on every STT partial and every
+* streaming delta, in files whose every other component is narrowly subscribed
+* on purpose. One of them (`text-adventure-agent`'s `TitleScreen`) reads nothing
+* from the snapshot at all and subscribes to all of it for `session.start`.
+*
+* **Why publishing this does not reopen what `/internal` closed.**
+* `useSessionCore` hands back the STORE — `subscribe`, `getSnapshot`,
+* `connect`, `Symbol.dispose` — which is the framework's own plumbing, the same
+* category as the providers and `buildAgentUrl` that live on
+* `@alexkroman1/aai-ui/internal`. A client that holds it can subscribe out of
+* band of React, dial a socket the mount did not, and dispose the session under
+* the tree that is rendering it. What comes back from here is the SAME
+* methods `useSession()` already publishes on its result, built into a fresh
+* object rather than passed through, so the store is not reachable from it.
+* There is no new capability here — only the existing one without the
+* subscription tax.
+*
+* Identity-stable per core, so it is safe in a dependency array and in a
+* `memo()` child's props: the methods are closures created once by
+* `createBrowserSession`, and the object wrapping them is memoized on the core.
+*
+* Throws outside the provider `mountClient()` installs, like every session hook.
+*
+* @example A footer that acts on the session without re-rendering with it
+* ```tsx
+* import { useSessionActions, useSessionSelector } from "@alexkroman1/aai-ui";
+*
+* function Footer() {
+*   // Two narrow subscriptions and no snapshot read: this row re-renders when
+*   // `running` flips, and not on every transcript delta.
+*   const running = useSessionSelector((s) => s.running);
+*   const { toggle, end } = useSessionActions();
+*   return (
+*     <>
+*       <button onClick={toggle}>{running ? "Pause" : "Resume"}</button>
+*       <button onClick={end}>Hang up</button>
+*     </>
+*   );
+* }
+* ```
+*
+* @returns The control methods — see {@link SessionActions}.
+*
+* @public
+*/
+function useSessionActions() {
+	const core = useSessionCore();
+	return useMemo(() => ({
+		start: core.start,
+		cancel: core.cancel,
+		sendText: core.sendText,
+		setMicMuted: core.setMicMuted,
+		resetState: core.resetState,
+		reset: core.reset,
+		restart: core.restart,
+		resume: core.resume,
+		disconnect: core.disconnect,
+		toggle: core.toggle,
+		end: core.end
+	}), [core]);
+}
+/**
+* Return the live {@link Session}: the current snapshot fields plus the
+* control methods (`start`, `toggle`, `reset`, `resetState`, `disconnect`,
+* `cancel`, `end`).
+*
+* Throws if used outside the provider `mountClient()` installs (the error names
+* `<SessionProvider>` — you only mount that yourself when bypassing
+* `mountClient()`). Re-renders the component on *every* snapshot change; for a
+* component that reads one field, prefer {@link useSessionSelector} for a
+* targeted subscription.
+*
+* @example
+* ```tsx
+* import { useSession } from "@alexkroman1/aai-ui";
+*
+* function Controls() {
+*   const session = useSession();
+*   if (!session.started) return <button onClick={session.start}>Start</button>;
+*   return <button onClick={session.toggle}>{session.running ? "Pause" : "Resume"}</button>;
+* }
+* ```
+*
+* @public
+*/
+function useSession() {
+	const core = useSessionCore();
+	const snapshot = useSyncExternalStore(core.subscribe, core.getSnapshot);
+	const actions = useSessionActions();
+	return useMemo(() => ({
+		...snapshot,
+		...actions
+	}), [snapshot, actions]);
+}
+/**
+* Subscribe to a narrow slice of the session snapshot.
+*
+* Unlike {@link useSession} — which re-renders the component on *every*
+* snapshot change — this only triggers a re-render when the selected value
+* changes (per `isEqual`, default `Object.is`). Use it for components that
+* read a single field, e.g. `useSessionSelector((s) => s.running)`.
+*
+* The selector must be pure. It may run on every snapshot change, so keep it
+* cheap; when it returns a derived object, pass a custom `isEqual` to avoid
+* re-renders on referentially-new-but-equal results.
+*
+* @example
+* ```tsx
+* import { useSessionSelector } from "@alexkroman1/aai-ui";
+*
+* // Re-renders when `running` flips, and on nothing else — not on every
+* // transcript delta the way `useSession()` would.
+* function MicDot() {
+*   const running = useSessionSelector((snapshot) => snapshot.running);
+*   return <span>{running ? "●" : "○"}</span>;
+* }
+* ```
+*
+* @param selector - Reads the slice out of the snapshot. Must be pure.
+* @param isEqual - Compares two selected values. Defaults to `Object.is`.
+* @returns The selected slice.
+*
+* @public
+*/
+function useSessionSelector(selector, isEqual = Object.is) {
+	const core = useSessionCore();
+	return useSyncExternalStoreWithSelector(core.subscribe, core.getSnapshot, core.getSnapshot, selector, isEqual);
+}
+/**
+* The two selectors below are MODULE-SCOPE functions, and that is load-bearing
+* rather than tidy.
+*
+* `useSyncExternalStoreWithSelector` caches its selection keyed on the selector
+* it was handed: a fresh arrow per render invalidates that memo every render,
+* so the selector re-runs and the `isEqual` short-circuit protects only the
+* re-RENDER, never the work. Hoisting them means the two fields more than one
+* chrome ever reads are selected by one stable function for the life of the
+* program — which is also the thing a caller writing the arrow inline cannot
+* do for themselves, and the reason these two are hooks at all rather than a
+* documented one-liner.
+*/
+const selectState = (s) => s.state;
+const selectError = (s) => s.error;
+/**
+* The agent's live {@link AgentState} — `disconnected`, `connecting`, `ready`,
+* `listening`, `thinking`, `speaking`, `error` — on its own narrow
+* subscription.
+*
+* `useSessionSelector((s) => s.state)` spelled once. It is one of exactly two
+* snapshot fields that more than one custom chrome ever selects (the other is
+* {@link useSessionError}), and it had been written inline at eight sites —
+* including inside this package and, worse, in `ConsoleShell`'s own `@example`,
+* which taught the inline form to everyone who read it.
+*
+* **Named `useSessionStatus`, not `useSessionState`.** `useAgentState` is the
+* SLOT hook — the agent's own synced application state, whatever a
+* `sessionSlot()` projects — and `AgentState` here is the phase of the CALL.
+* Two different concepts one letter apart, so the shorter-sounding name is the
+* one deliberately not taken.
+*
+* Pair it with {@link AGENT_STATE_LABELS} for a rendered word; the raw member
+* is a wire value, not a label.
+*
+* @example
+* ```tsx
+* import { AGENT_STATE_LABELS, useSessionStatus } from "@alexkroman1/aai-ui";
+*
+* function StatusDot() {
+*   const status = useSessionStatus();
+*   return <span data-state={status}>{AGENT_STATE_LABELS[status]}</span>;
+* }
+* ```
+*
+* @returns The current agent state.
+*
+* @public
+*/
+function useSessionStatus() {
+	return useSessionSelector(selectState);
+}
+/**
+* The session's current {@link SessionError}, or `null` when there is none, on
+* its own narrow subscription.
+*
+* The other half of {@link useSessionStatus} — the second of the two fields a
+* custom chrome reads over and over, and the one whose absence is invisible:
+* per the `fatalError` latch in `session/browser-session.ts` the error is the ONLY
+* remaining signal that a session died, since the state beside it goes back to
+* reading like a live one.
+*
+* A chrome rendering it owes `role="alert"` — which is what
+* {@link SessionErrorBanner} is for, and why reaching for that beats reaching
+* for this.
+*
+* @returns The current error, or `null`.
+*
+* @public
+*/
+function useSessionError() {
+	return useSessionSelector(selectError);
+}
+const ThemeCtx = createContext(DEFAULT_THEME);
+/**
+* Provides the theme the components read via `useTheme`. `mountClient()` installs
+* it automatically (from `ClientConfig.theme`); a custom tree only needs it
+* when bypassing `mountClient()` and mounting React itself.
+*
+* @internal
+*/
+function ThemeProvider({ value, children }) {
+	const merged = useMemo(() => value ? {
+		...DEFAULT_THEME,
+		...value
+	} : DEFAULT_THEME, [value]);
+	useThemeStyles(merged);
+	return createElement(ThemeCtx.Provider, { value: merged }, children);
+}
+/**
+* The custom property each {@link ClientTheme} field is published as.
+*
+* Named after the field, so `theme.surface` and `--aai-surface` are obviously
+* the same thing, and prefixed for the reason `--aai-btn-bg` and
+* `--aai-sidebar-w` already are: these land on `:root`, where an app's own
+* variables live too.
+*
+* @internal
+*/
+const THEME_VARS = {
+	bg: "--aai-bg",
+	surface: "--aai-surface",
+	text: "--aai-text",
+	border: "--aai-border",
+	primary: "--aai-primary"
+};
+/**
+* Publish the theme to CSS, and paint the page with it.
+*
+* Two jobs on one element deliberately — both are about the parts of the page
+* React does not own.
+*
+* **The variables.** {@link useTheme} hands a component a JavaScript object, so
+* everything it styles carries an inline `style={{ }}`; measured across the
+* template tree the ratio of `theme.` reads to inline style objects is
+* essentially one to one. A Tailwind class cannot see a JavaScript object — so
+* the five values are written to `:root` as custom properties, `styles.css`
+* maps them into the `@theme` block's `--color-*` namespace, and
+* `className="bg-aai-surface text-aai-text border-aai-border"` works. This is
+* ADDITIVE: `useTheme()` stays, because the derived tints in
+* `components/_colors.ts` `color-mix` on the resolved values and a page is
+* entitled to read them for a `satisfies`-pinned palette.
+*
+* **The background.** Components paint `theme.bg` on their own containers, but
+* the page behind them keeps whatever the static `<style>` in index.html set.
+* Any viewport wider (or taller) than the app column then shows that color as a
+* border around the UI — which is how a cream theme ended up letterboxed in
+* black. It stays an explicit `background` on `html` AND `body` rather than
+* riding on the new variable: a variable only paints where some rule consumes
+* it, and the two elements this is about are the two nothing in this package
+* renders.
+*/
+function useThemeStyles(theme) {
+	const { bg, surface, text, border, primary } = theme;
+	useEffect(() => {
+		if (typeof document === "undefined") return;
+		const { body, documentElement: html } = document;
+		const values = {
+			bg,
+			surface,
+			text,
+			border,
+			primary
+		};
+		const previousVars = Object.entries(THEME_VARS).map(([field, prop]) => [
+			prop,
+			html.style.getPropertyValue(prop),
+			values[field]
+		]);
+		for (const [prop, , next] of previousVars) html.style.setProperty(prop, next);
+		const previousBg = {
+			body: body.style.background,
+			html: html.style.background
+		};
+		body.style.background = bg;
+		html.style.background = bg;
+		return () => {
+			for (const [prop, before] of previousVars) if (before === "") html.style.removeProperty(prop);
+			else html.style.setProperty(prop, before);
+			body.style.background = previousBg.body;
+			html.style.background = previousBg.html;
+		};
+	}, [
+		bg,
+		surface,
+		text,
+		border,
+		primary
+	]);
+}
+/**
+* Read the resolved theme (every {@link ClientTheme} field filled with its
+* default) from the nearest theme context. Returns the default theme when no
+* provider is present, so components can call it unconditionally.
+*
+* This is how a custom component stays on the agent's palette: a
+* `mountClient({ theme })` override reaches it here, where a hardcoded colour or a
+* Tailwind class cannot see it.
+*
+* @example
+* ```tsx
+* import { useTheme } from "@alexkroman1/aai-ui";
+*
+* function Total({ amount }: { amount: string }) {
+*   const theme = useTheme();
+*   return (
+*     <strong style={{ color: theme.primary, background: theme.surface }}>
+*       {amount}
+*     </strong>
+*   );
+* }
+* ```
+*
+* @returns Every {@link ClientTheme} field, filled in.
+*
+* @public
+*/
+function useTheme() {
+	return useContext(ThemeCtx);
+}
+//#endregion
+export { SessionProvider, ThemeProvider, useOptionalSessionCore, useSession, useSessionActions, useSessionCore, useSessionError, useSessionSelector, useSessionStatus, useTheme };