@alexkroman1/aai-ui 0.17.0 → 0.18.0

package/dist/context-BF0KsI9X.js

@@ -0,0 +1,473 @@
+import { createContext, createElement, useContext, useEffect, useMemo, useSyncExternalStore } from "react";
+import { useSyncExternalStoreWithSelector } from "use-sync-external-store/with-selector";
+import { omitUndefined } from "@alexkroman1/aai/utils";
+//#region src/_theme.ts
+/**
+* One `ClientTheme` — either form — to the five resolved tokens.
+*
+* Its own module rather than a branch in `context.ts` (which is at the cap)
+* because the derivation is a decision worth a test of its own: the dark
+* neutrals are chosen to keep the components' derived tints (`_colors.ts`'s
+* `inkTint`, which walks from `text` toward the ground) above WCAG AA on a
+* dark surface, exactly as the light defaults do on a light one.
+*/
+const DEFAULT_THEME = Object.freeze({
+	bg: "#FAFAFA",
+	primary: "#18181B",
+	text: "#18181B",
+	surface: "#FFFFFF",
+	border: "#E4E4E7"
+});
+/**
+* The dark ground the preset form derives: the light defaults' zinc scale
+* read from the other end (zinc-950 ground, zinc-900 cards, zinc-800 borders,
+* near-white ink), so `inkTint` lands on the same steps mirrored.
+*/
+const DARK_NEUTRALS = Object.freeze({
+	bg: "#09090B",
+	surface: "#18181B",
+	text: "#FAFAFA",
+	border: "#27272A"
+});
+/** Is this the preset form? Only it carries `mode`; `{ primary }` alone is both and resolves alike. */
+function isPreset(theme) {
+	return "mode" in theme && theme.mode !== void 0;
+}
+/**
+* The theme without its BLANK tokens, each one warned about.
+*
+* `primary: ""` used to be written verbatim as `--aai-primary: ;`, an empty
+* custom property, so every primary-coloured control went transparent with
+* nothing anywhere saying why. An empty string is not a colour and not "unset"
+* either, so it is dropped — the default fills the hole as for an `undefined`
+* token — and said once per resolve. Colour SYNTAX is not validated: the
+* browser's own parsing is the authority on what a colour is.
+*/
+function withoutBlankTokens(theme) {
+	const kept = { ...theme };
+	for (const [token, value] of Object.entries(theme)) {
+		if (value !== "") continue;
+		console.warn(`[aai-ui] theme.${token} is "" and was ignored; the default is used. Pass a colour, or leave the token out.`);
+		delete kept[token];
+	}
+	return kept;
+}
+/**
+* Every token filled in: the preset's neutrals under its accent, or the given
+* tokens over the defaults. `undefined` is the default theme itself. A token
+* given as `""` is ignored with a warning ({@link withoutBlankTokens}).
+*/
+function resolveClientTheme(theme) {
+	if (theme === void 0) return DEFAULT_THEME;
+	if (isPreset(theme)) {
+		const neutrals = theme.mode === "dark" ? DARK_NEUTRALS : DEFAULT_THEME;
+		const { primary } = withoutBlankTokens({ primary: theme.primary });
+		return {
+			...neutrals,
+			primary: primary ?? neutrals.text
+		};
+	}
+	return {
+		...DEFAULT_THEME,
+		...omitUndefined(withoutBlankTokens(theme))
+	};
+}
+//#endregion
+//#region src/context.ts
+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] ?? 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(() => resolveClientTheme(value), [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"
+};
+/**
+* Every LIVE provider's theme, oldest first, and the page they all wrote over.
+*
+* Page-wide rather than per provider, because the page is: two providers that
+* each snapshot `:root` at mount and restore it at unmount only undo each other
+* in reverse order. Unmounted in MOUNT order (two `mountClient`s disposed as
+* they were created, or Testing Library's `cleanup`, which unmounts in render
+* order), the first restored the page and the second then wrote the first's
+* tokens back — a stale theme left on a page with no client on it. Now the
+* newest live theme paints, and the page is restored only when the last
+* provider goes, whichever order they go in.
+*/
+const liveThemes = [];
+let pageBefore = null;
+function readPageStyles() {
+	const { body, documentElement: html } = document;
+	return {
+		vars: Object.values(THEME_VARS).map((prop) => [prop, html.style.getPropertyValue(prop)]),
+		htmlBg: html.style.background,
+		bodyBg: body.style.background
+	};
+}
+function writePageStyles(page) {
+	const { body, documentElement: html } = document;
+	for (const [prop, value] of page.vars) if (value === "") html.style.removeProperty(prop);
+	else html.style.setProperty(prop, value);
+	html.style.background = page.htmlBg;
+	body.style.background = page.bodyBg;
+}
+function paintTheme(theme) {
+	const { body, documentElement: html } = document;
+	for (const [field, prop] of Object.entries(THEME_VARS)) html.style.setProperty(prop, theme[field]);
+	body.style.background = theme.bg;
+	html.style.background = theme.bg;
+}
+/**
+* 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 entry = {
+			bg,
+			surface,
+			text,
+			border,
+			primary
+		};
+		if (liveThemes.length === 0) pageBefore = readPageStyles();
+		liveThemes.push(entry);
+		paintTheme(entry);
+		return () => {
+			liveThemes.splice(liveThemes.indexOf(entry), 1);
+			const newest = liveThemes.at(-1);
+			if (newest) paintTheme(newest);
+			else if (pageBefore) {
+				writePageStyles(pageBefore);
+				pageBefore = null;
+			}
+		};
+	}, [
+		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 — a {@link ResolvedClientTheme}.
+*
+* @public
+*/
+function useTheme() {
+	return useContext(ThemeCtx);
+}
+//#endregion
+export { useSessionActions as a, useSessionSelector as c, useSession as i, useSessionStatus as l, ThemeProvider as n, useSessionCore as o, useOptionalSessionCore as r, useSessionError as s, SessionProvider as t, useTheme as u };