@data-club/ai-hub 0.0.1

package/src/context/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Re-exports for the `context/` directory.
+ *
+ * @see SPECIFICATIONS.md §7.2 — provider + hooks
+ */
+
+export { AIHubProvider, type AIHubProviderProps } from "./AIHubProvider.js";
+export { useAIHub, type UseAIHubResult } from "./useAIHub.js";
+export { useAIHubAuth, type UseAIHubAuthResult } from "./useAIHubAuth.js";

package/src/context/theme.ts

@@ -0,0 +1,76 @@
+/**
+ * Theme resolution helpers used by `<AIHubProvider>`.
+ *
+ * The §7.6 precedence:
+ *
+ * 1. `user.theme_preference` when `deployment.theme_switcher_enabled` is true.
+ * 2. Otherwise `deployment.theme_default`.
+ *
+ * The unauthenticated case (no `/auth/me` yet) falls back to a value cached
+ * in `localStorage` so the first paint matches the last-known theme and
+ * the user doesn't see a flash of unstyled content.
+ *
+ * @see SPECIFICATIONS.md §7.6 — theming
+ */
+
+import type { AIHubDeployment, AIHubUser } from "../types.js";
+
+/** localStorage key for the last-resolved theme. Namespaced to ai-hub. */
+const CACHE_KEY = "data-club-ai-hub:theme";
+
+/** The two themes the library ships. */
+export type ResolvedTheme = "light" | "dark";
+
+/**
+ * Computes the resolved theme from the inputs on the `/auth/me` envelope.
+ *
+ * @param user - authenticated user, or null when unauthenticated.
+ * @param deployment - deployment context, or null when unauthenticated.
+ * @param fallback - default applied when both inputs are null
+ *   (typically the React-prop `defaultTheme`).
+ * @returns the resolved theme.
+ */
+export function resolveTheme(
+  user: AIHubUser | null,
+  deployment: AIHubDeployment | null,
+  fallback: ResolvedTheme,
+): ResolvedTheme {
+  if (!deployment) return fallback;
+  if (deployment.theme_switcher_enabled && user?.theme_preference) {
+    return user.theme_preference;
+  }
+  return deployment.theme_default;
+}
+
+/**
+ * Reads the cached theme from `localStorage`. Returns null when no cache
+ * exists, the value is malformed, or storage is unavailable (Safari
+ * private mode, SSR, etc.).
+ *
+ * @returns the cached theme or null.
+ */
+export function readCachedTheme(): ResolvedTheme | null {
+  try {
+    if (typeof window === "undefined" || !window.localStorage) return null;
+    const raw = window.localStorage.getItem(CACHE_KEY);
+    if (raw === "light" || raw === "dark") return raw;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Persists the resolved theme into `localStorage` for FOUC avoidance on
+ * the next page load. Silent no-op on storage failures.
+ *
+ * @param theme - the theme to cache.
+ */
+export function writeCachedTheme(theme: ResolvedTheme): void {
+  try {
+    if (typeof window === "undefined" || !window.localStorage) return;
+    window.localStorage.setItem(CACHE_KEY, theme);
+  } catch {
+    /* ignore */
+  }
+}

package/src/context/useAIHub.ts

@@ -0,0 +1,151 @@
+/**
+ * `useAIHub()` — primary hook for chat state (agents, sessions, messages,
+ * streaming), theme controls, effort, and direct SDK access.
+ *
+ * Step 9 wires the chat surface on top of the Step-7 foundation. The
+ * remaining affordances (TPM banner, reasoning view, theme switcher
+ * primitive, server-toggle precedence) layer in Step 10.
+ *
+ * @see SPECIFICATIONS.md §7.2 — provider + hooks
+ */
+
+import { useContext } from "react";
+
+import { aiHubContext, type AIHubContextValue } from "./AIHubContext.js";
+
+/**
+ * The shape `useAIHub()` returns. Mirrors `AIHubContextValue` minus the
+ * auth-only fields (`user`, `role`, `mustChangePassword`, `login`,
+ * `logout`, `changePassword`) — those live on `useAIHubAuth()`.
+ */
+export interface UseAIHubResult {
+  /** The underlying SDK client. */
+  client: AIHubContextValue["client"];
+  /** Active turn's reducer state. */
+  state: AIHubContextValue["state"];
+  /** Per-message reasoning effort selector value. */
+  effort: AIHubContextValue["effort"];
+  /** Updates `effort`. */
+  setEffort: AIHubContextValue["setEffort"];
+  /** Resolved theme (`light` | `dark`). */
+  theme: AIHubContextValue["theme"];
+  /**
+   * Flips the theme. Throws `AIHubRequestError` (`code:
+   * "theme_switcher_disabled"`) when the deployment has the switcher off.
+   */
+  setTheme: AIHubContextValue["setTheme"];
+  /** Mirror of `deployment.theme_switcher_enabled`. */
+  themeSwitcherEnabled: AIHubContextValue["themeSwitcherEnabled"];
+  /** Non-archived agents available to the caller. */
+  agents: AIHubContextValue["agents"];
+  /** True while the initial `/agents` request is in flight. */
+  agentsLoading: AIHubContextValue["agentsLoading"];
+  /** Refetches `/agents`. */
+  refreshAgents: AIHubContextValue["refreshAgents"];
+  /** Opened agent id, or `null` when on the picker. */
+  activeAgentId: AIHubContextValue["activeAgentId"];
+  /** Opens an agent (`id`) or returns to the picker (`null`). */
+  setActiveAgent: AIHubContextValue["setActiveAgent"];
+  /** Sessions for the active agent + current user. */
+  sessions: AIHubContextValue["sessions"];
+  /** True while sessions are loading. */
+  sessionsLoading: AIHubContextValue["sessionsLoading"];
+  /** Refetches sessions for the active agent. */
+  refreshSessions: AIHubContextValue["refreshSessions"];
+  /** Whether archived rows are included in `sessions`. */
+  includeArchivedSessions: AIHubContextValue["includeArchivedSessions"];
+  /** Toggles the archived filter. */
+  setIncludeArchivedSessions: AIHubContextValue["setIncludeArchivedSessions"];
+  /** Opened session id. */
+  activeSessionId: AIHubContextValue["activeSessionId"];
+  /** Opens a session (`id`) or clears the selection (`null`). */
+  setActiveSession: AIHubContextValue["setActiveSession"];
+  /** Creates + selects a new session. Title required (1..80 chars). */
+  createSession: AIHubContextValue["createSession"];
+  /** Patches a session (rename / archive / unarchive). */
+  patchSession: AIHubContextValue["patchSession"];
+  /** Messages for the active session. */
+  messages: AIHubContextValue["messages"];
+  /** True while the active session's message history is loading. */
+  messagesLoading: AIHubContextValue["messagesLoading"];
+  /** Streaming assistant text accumulator (null when nothing is streaming). */
+  streamingAssistantText: AIHubContextValue["streamingAssistantText"];
+  /** Streaming reasoning text accumulator (null when no reasoning is in flight). */
+  streamingReasoning: AIHubContextValue["streamingReasoning"];
+  /** In-progress tool calls being assembled from SSE events. */
+  streamingToolCalls: AIHubContextValue["streamingToolCalls"];
+  /** Sends a message against the active session. */
+  sendMessage: AIHubContextValue["sendMessage"];
+  /** Cancels the in-flight turn. */
+  stop: AIHubContextValue["stop"];
+  /** True while a Stop is in flight and we're waiting for stream_end. */
+  isStoppingTurn: AIHubContextValue["isStoppingTurn"];
+  /** Text the input should prefill (from a rolled-back send). */
+  pendingDraft: AIHubContextValue["pendingDraft"];
+  /** Reads + clears `pendingDraft` in one step. */
+  consumePendingDraft: AIHubContextValue["consumePendingDraft"];
+  /** Last turn's unrecoverable error message, or null. */
+  lastTurnError: AIHubContextValue["lastTurnError"];
+  /**
+   * Deployment-wide UI feature toggles (§8.4) — `null` until the fetch
+   * resolves. Most consumers should NOT branch on this directly; the
+   * `useAffordanceFlags()` helper composes server toggle > React prop >
+   * built-in default and is the supported way to read flag state.
+   */
+  featureToggles: AIHubContextValue["featureToggles"];
+  /** Re-fetches the toggles (used after a super-admin save). */
+  refreshFeatureToggles: AIHubContextValue["refreshFeatureToggles"];
+}
+
+/**
+ * Returns the chat / theme / SDK surface from the nearest `<AIHubProvider>`.
+ *
+ * Throws when called outside a provider — surface mounting bugs early
+ * instead of cascading through context-null deref in components.
+ *
+ * @returns the chat surface.
+ */
+export function useAIHub(): UseAIHubResult {
+  const ctx = useContext(aiHubContext);
+  if (!ctx) {
+    throw new Error(
+      "useAIHub() was called outside <AIHubProvider>. Wrap the tree in <AIHubProvider> first.",
+    );
+  }
+  return {
+    client: ctx.client,
+    state: ctx.state,
+    effort: ctx.effort,
+    setEffort: ctx.setEffort,
+    theme: ctx.theme,
+    setTheme: ctx.setTheme,
+    themeSwitcherEnabled: ctx.themeSwitcherEnabled,
+    agents: ctx.agents,
+    agentsLoading: ctx.agentsLoading,
+    refreshAgents: ctx.refreshAgents,
+    activeAgentId: ctx.activeAgentId,
+    setActiveAgent: ctx.setActiveAgent,
+    sessions: ctx.sessions,
+    sessionsLoading: ctx.sessionsLoading,
+    refreshSessions: ctx.refreshSessions,
+    includeArchivedSessions: ctx.includeArchivedSessions,
+    setIncludeArchivedSessions: ctx.setIncludeArchivedSessions,
+    activeSessionId: ctx.activeSessionId,
+    setActiveSession: ctx.setActiveSession,
+    createSession: ctx.createSession,
+    patchSession: ctx.patchSession,
+    messages: ctx.messages,
+    messagesLoading: ctx.messagesLoading,
+    streamingAssistantText: ctx.streamingAssistantText,
+    streamingReasoning: ctx.streamingReasoning,
+    streamingToolCalls: ctx.streamingToolCalls,
+    sendMessage: ctx.sendMessage,
+    stop: ctx.stop,
+    isStoppingTurn: ctx.isStoppingTurn,
+    pendingDraft: ctx.pendingDraft,
+    consumePendingDraft: ctx.consumePendingDraft,
+    lastTurnError: ctx.lastTurnError,
+    featureToggles: ctx.featureToggles,
+    refreshFeatureToggles: ctx.refreshFeatureToggles,
+  };
+}

package/src/context/useAIHubAuth.ts

@@ -0,0 +1,65 @@
+/**
+ * `useAIHubAuth()` — auth-only hook for apps building their own login UI
+ * or rendering role-aware affordances.
+ *
+ * Separate from `useAIHub()` so consumers that only need the user's role
+ * (e.g. for menu visibility) don't subscribe to chat-state changes.
+ *
+ * @see SPECIFICATIONS.md §7.2 — provider + hooks
+ */
+
+import { useContext } from "react";
+
+import { aiHubContext, type AIHubContextValue } from "./AIHubContext.js";
+
+/**
+ * The shape `useAIHubAuth()` returns.
+ */
+export interface UseAIHubAuthResult {
+  /** Currently authenticated user, or null when unauthenticated. */
+  user: AIHubContextValue["user"];
+  /** Convenience echo of `user.role`. */
+  role: AIHubContextValue["role"];
+  /** Deployment-wide context returned by `/auth/me`. */
+  deployment: AIHubContextValue["deployment"];
+  /**
+   * True until the first `/auth/me` resolves. Consumers should render a
+   * loading state (or render nothing) rather than flashing the login screen
+   * while the cached token is being validated.
+   */
+  hydrating: AIHubContextValue["hydrating"];
+  /** True when the user must complete the change-password flow. */
+  mustChangePassword: AIHubContextValue["mustChangePassword"];
+  /** Logs in with username + password. */
+  login: AIHubContextValue["login"];
+  /** Clears the token and the local auth state. */
+  logout: AIHubContextValue["logout"];
+  /** Changes the password (voluntary or forced flow — see §8.5). */
+  changePassword: AIHubContextValue["changePassword"];
+}
+
+/**
+ * Returns the auth surface from the nearest `<AIHubProvider>`.
+ *
+ * Throws when called outside a provider.
+ *
+ * @returns the auth surface.
+ */
+export function useAIHubAuth(): UseAIHubAuthResult {
+  const ctx = useContext(aiHubContext);
+  if (!ctx) {
+    throw new Error(
+      "useAIHubAuth() was called outside <AIHubProvider>. Wrap the tree in <AIHubProvider> first.",
+    );
+  }
+  return {
+    user: ctx.user,
+    role: ctx.role,
+    deployment: ctx.deployment,
+    hydrating: ctx.hydrating,
+    mustChangePassword: ctx.mustChangePassword,
+    login: ctx.login,
+    logout: ctx.logout,
+    changePassword: ctx.changePassword,
+  };
+}

package/src/index.ts

@@ -0,0 +1,275 @@
+/**
+ * Public entry point for `@data-club/ai-hub`.
+ *
+ * Step 7 shipped the non-visual foundation: client SDK, state reducer,
+ * React provider + hooks, `defineWebComponent` helper, and the `AIHub.*`
+ * namespace (stubs for the visible primitives). **Step 8 fills in the
+ * auth screens**: `<DataClubAIHubLogin />`,
+ * `<DataClubAIHubChangePassword />` (forced + voluntary variants),
+ * `AIHub.AuthGate`, and a minimal `<DataClubAIHub />` skeleton that
+ * threads branding / i18n into both screens. The chat layout
+ * (`AIHub.AgentsPicker`, `Layout`, `SessionsPanel`, …) lands in Step 9;
+ * the affordances (TPM banner, theme switcher, reasoning view, …) in
+ * Step 10; the admin UI in Steps 11–12.
+ *
+ * @see SPECIFICATIONS.md §7.1 — exports
+ */
+
+/* ── Types ────────────────────────────────────────────────────────── */
+
+export type {
+  AIHubRole,
+  AIHubUser,
+  AIHubDeployment,
+  AIHubAuthContext,
+  AIHubFeatureToggles,
+  Session,
+  AIHubMessage,
+  AIHubMessageOverride,
+  AIHubMessageUsage,
+  AIHubToolCallRecord,
+  TurnStatus,
+  RunningPhase,
+  AIHubState,
+  AIHubEventState,
+  AIHubEvent,
+  AIHubError,
+  AIHubMessageActionRenderer,
+  AIHubMessageBubbleRenderer,
+  AIHubSlotProps,
+} from "./types.js";
+
+/* ── State reducer + affordance helpers ──────────────────────────── */
+
+export { initialAIHubState, reduceAIHubState } from "./state/stateReducer.js";
+export {
+  DEFAULT_AFFORDANCE_FLAGS,
+  FEATURE_TOGGLE_KEY_MAP,
+  resolveAffordanceFlags,
+  chatAffordances,
+  turnStatusVisual,
+} from "./state/affordances.js";
+export type {
+  AIHubAffordanceFlags,
+  AIHubChatAffordances,
+  AIHubTurnStatusVisual,
+} from "./state/affordances.js";
+
+/* ── Client SDK ───────────────────────────────────────────────────── */
+
+export {
+  AIHubClient,
+  AIHubRequestError,
+  parseSseStream,
+  createMemoryTokenStorage,
+  resolveTokenStorage,
+} from "./client/index.js";
+export type {
+  AIHubClientOptions,
+  LoginResponse,
+  ListSessionsOptions,
+  CreateSessionOptions,
+  PatchSessionOptions,
+  PatchSessionReasoningOptions,
+  AIHubEffort,
+  StreamChatBody,
+  StreamChatOptions,
+  AgentSummary,
+  CancelTurnResponse,
+  AdminUserView,
+  CreateUserBody,
+  AdminUserPasswordReveal,
+  CreateUserResponse,
+  TokenStorage,
+  TokenStorageMode,
+} from "./client/index.js";
+
+/* ── Provider + hooks ─────────────────────────────────────────────── */
+
+export {
+  AIHubProvider,
+  useAIHub,
+  useAIHubAuth,
+} from "./context/index.js";
+export type {
+  AIHubProviderProps,
+  UseAIHubResult,
+  UseAIHubAuthResult,
+} from "./context/index.js";
+
+/* ── Web Component packaging ──────────────────────────────────────── */
+
+export {
+  defineWebComponent,
+  isValidCustomElementName,
+} from "./webcomponent/index.js";
+export type { DefineWebComponentOptions } from "./webcomponent/index.js";
+
+/* ── Built-in screens (auto-rendered by `<DataClubAIHub />`) ─────── */
+
+export {
+  DataClubAIHubLogin,
+} from "./components/DataClubAIHubLogin/index.js";
+export type {
+  DataClubAIHubLoginProps,
+  AIHubLoginClassNames,
+} from "./components/DataClubAIHubLogin/index.js";
+
+export {
+  DataClubAIHubChangePassword,
+} from "./components/ChangePassword/index.js";
+export type {
+  DataClubAIHubChangePasswordProps,
+  AIHubChangePasswordClassNames,
+} from "./components/ChangePassword/index.js";
+
+export {
+  DataClubAIHub,
+} from "./components/DataClubAIHub/index.js";
+export type {
+  DataClubAIHubProps,
+} from "./components/DataClubAIHub/index.js";
+
+export {
+  DataClubAIHubAdmin,
+} from "./components/DataClubAIHubAdmin/index.js";
+export type {
+  DataClubAIHubAdminProps,
+  AdminPage,
+} from "./components/DataClubAIHubAdmin/index.js";
+
+/* ── Chat primitives (also exported under the `AIHub` namespace) ── */
+
+export { AgentsPicker } from "./components/AgentsPicker/index.js";
+export type {
+  AgentsPickerProps,
+  AgentsPickerClassNames,
+} from "./components/AgentsPicker/index.js";
+
+export { Layout } from "./components/Layout/index.js";
+export type { LayoutProps, LayoutClassNames } from "./components/Layout/index.js";
+
+export { SessionsPanel } from "./components/SessionsPanel/index.js";
+export type {
+  SessionsPanelProps,
+  SessionsPanelClassNames,
+} from "./components/SessionsPanel/index.js";
+
+export { MainColumn } from "./components/MainColumn/index.js";
+export type {
+  MainColumnProps,
+  MainColumnClassNames,
+} from "./components/MainColumn/index.js";
+
+export { MessageList } from "./components/MessageList/index.js";
+export type {
+  MessageListProps,
+  MessageListClassNames,
+} from "./components/MessageList/index.js";
+
+export { MessageInput } from "./components/MessageInput/index.js";
+export type {
+  MessageInputProps,
+  MessageInputClassNames,
+} from "./components/MessageInput/index.js";
+
+export { MarkdownRenderer } from "./components/MarkdownRenderer/index.js";
+export type {
+  MarkdownRendererProps,
+  MarkdownRendererClassNames,
+} from "./components/MarkdownRenderer/index.js";
+
+/* ── Affordance primitives (Step 10) ─────────────────────────────── */
+
+export { EffortControl, EFFORT_VALUES } from "./components/EffortControl/index.js";
+export type {
+  EffortControlProps,
+  EffortControlClassNames,
+} from "./components/EffortControl/index.js";
+
+export { ReasoningSelector } from "./components/ReasoningSelector/index.js";
+export type {
+  ReasoningSelectorProps,
+  ReasoningSelectorClassNames,
+} from "./components/ReasoningSelector/index.js";
+
+export { TurnStatusIndicator } from "./components/TurnStatusIndicator/index.js";
+export type {
+  TurnStatusIndicatorProps,
+  TurnStatusIndicatorClassNames,
+} from "./components/TurnStatusIndicator/index.js";
+
+export { ThemeSwitcher } from "./components/ThemeSwitcher/index.js";
+export type {
+  ThemeSwitcherProps,
+  ThemeSwitcherClassNames,
+} from "./components/ThemeSwitcher/index.js";
+
+export { SystemNotice } from "./components/SystemNotice/index.js";
+export type {
+  SystemNoticeProps,
+  SystemNoticeClassNames,
+} from "./components/SystemNotice/index.js";
+
+export { TpmBanner } from "./components/TpmBanner/index.js";
+export type { TpmBannerProps } from "./components/TpmBanner/index.js";
+
+export { ReasoningView } from "./components/ReasoningView/index.js";
+export type {
+  ReasoningViewProps,
+  ReasoningViewClassNames,
+} from "./components/ReasoningView/index.js";
+
+export { ToolCallView } from "./components/ToolCallView/index.js";
+export type {
+  ToolCallStatus,
+  ToolCallViewProps,
+  ToolCallViewClassNames,
+} from "./components/ToolCallView/index.js";
+export { formatToolContentForDisplay } from "./components/ToolCallView/formatContent.js";
+
+export { CacheBadge, computeCacheHitRatio } from "./components/CacheBadge/index.js";
+export type {
+  CacheBadgeProps,
+  CacheBadgeClassNames,
+  CacheBadgeTexts,
+} from "./components/CacheBadge/index.js";
+
+export { ScrollToPresentButton } from "./components/ScrollToPresentButton/index.js";
+export type {
+  ScrollToPresentButtonProps,
+  ScrollToPresentButtonClassNames,
+} from "./components/ScrollToPresentButton/index.js";
+
+/* ── i18n / branding surface ─────────────────────────────────────── */
+
+export {
+  defaultAIHubTexts,
+  resolveAIHubTexts,
+} from "./auth/texts.js";
+export type {
+  AIHubTexts,
+  AIHubLoginTexts,
+  AIHubChangePasswordTexts,
+  AIHubChatTexts,
+  AIHubAdminTexts,
+  DeepPartial,
+} from "./auth/texts.js";
+
+/* ── Password policy (client-side mirror of §8.5) ────────────────── */
+
+export {
+  PASSWORD_MIN_LENGTH,
+  PASSWORD_REQUIRED_CATEGORIES,
+  validatePasswordPolicyClient,
+  countCharacterCategoriesClient,
+} from "./auth/passwordPolicy.js";
+export type {
+  ClientPasswordPolicyResult,
+  ClientPasswordPolicyErrorCode,
+} from "./auth/passwordPolicy.js";
+
+/* ── AIHub.* namespace (Tier-3 composition primitives) ───────────── */
+
+export { AIHub } from "./primitives/index.js";
+export type { AIHubNamespace } from "./primitives/index.js";

package/src/primitives/index.ts

@@ -0,0 +1,101 @@
+/**
+ * The `AIHub.*` namespace — Tier-3 composition primitives.
+ *
+ * Every primitive is real after Step 10. Tier-3 wrappers compose them
+ * directly; the default monolith `<DataClubAIHub />` is itself a Tier-3
+ * composition that lives in the library as a reference (~50 lines of
+ * internal body code).
+ *
+ * The namespace is intentionally a single object literal so consumers
+ * can do `import { AIHub } from "@data-club/ai-hub"` and reach every
+ * primitive via dotted access (`<AIHub.MessageList renderMessageActions={…} />`).
+ *
+ * @see SPECIFICATIONS.md §7.1 — exports
+ * @see SPECIFICATIONS.md §7.9 — Tier 3 composition
+ */
+
+import { AIHubProvider } from "../context/AIHubProvider.js";
+import { AgentsPicker } from "../components/AgentsPicker/index.js";
+import { AuthGate } from "../components/AuthGate/index.js";
+import { DataClubAIHubAdmin } from "../components/DataClubAIHubAdmin/index.js";
+import { EffortControl } from "../components/EffortControl/index.js";
+import { Layout } from "../components/Layout/index.js";
+import { MainColumn } from "../components/MainColumn/index.js";
+import { MarkdownRenderer } from "../components/MarkdownRenderer/index.js";
+import { MessageInput } from "../components/MessageInput/index.js";
+import { MessageList } from "../components/MessageList/index.js";
+import { ReasoningSelector } from "../components/ReasoningSelector/index.js";
+import { ReasoningView } from "../components/ReasoningView/index.js";
+import { ScrollToPresentButton } from "../components/ScrollToPresentButton/index.js";
+import { SessionsPanel } from "../components/SessionsPanel/index.js";
+import { SystemNotice } from "../components/SystemNotice/index.js";
+import { ThemeSwitcher } from "../components/ThemeSwitcher/index.js";
+import { ToolCallView } from "../components/ToolCallView/index.js";
+import { TpmBanner } from "../components/TpmBanner/index.js";
+import { TurnStatusIndicator } from "../components/TurnStatusIndicator/index.js";
+
+/**
+ * Tier-3 composition primitives. Build a custom layout by composing
+ * `AIHub.Provider` + `AIHub.AuthGate` + `AIHub.Layout` + sub-primitives.
+ *
+ * @example
+ * ```tsx
+ * <AIHub.Provider baseUrl="/api/ai-hub">
+ *   <AIHub.AuthGate>
+ *     <AIHub.Layout>
+ *       <AIHub.SessionsPanel />
+ *       <AIHub.MainColumn>
+ *         <AIHub.MessageList />
+ *         <AIHub.Input toolbar={<AIHub.EffortControl />} />
+ *       </AIHub.MainColumn>
+ *     </AIHub.Layout>
+ *   </AIHub.AuthGate>
+ * </AIHub.Provider>
+ * ```
+ *
+ * @see SPECIFICATIONS.md §7.9
+ */
+export const AIHub = {
+  /** Root context provider. */
+  Provider: AIHubProvider,
+  /** Auth gate — renders Login / ChangePassword when needed. */
+  AuthGate,
+  /** Post-login landing view. */
+  AgentsPicker,
+  /** Flex layout container for SessionsPanel + MainColumn. */
+  Layout,
+  /** Sessions sidebar. */
+  SessionsPanel,
+  /** Main chat column. */
+  MainColumn,
+  /** Scrollable message list. */
+  MessageList,
+  /** Input area with send/stop buttons + toolbar. */
+  Input: MessageInput,
+  /** Markdown renderer for assistant message bodies (GFM + math). */
+  MarkdownRenderer,
+  /** Standalone reasoning-effort selector (per-message, legacy §7.4 path). */
+  EffortControl,
+  /** Capability-driven per-session reasoning UI. Renders 0–3 dropdowns/inputs
+   *  based on the active agent's model. Returns null for no-reasoning models. */
+  ReasoningSelector,
+  /** System-notice banner (TPM wait / resumed / error). */
+  SystemNotice,
+  /** TPM-recovery banner with countdown. */
+  TpmBanner,
+  /** `(status, phase)` indicator dot + label (§10.4). */
+  TurnStatusIndicator,
+  /** Sun/moon theme toggle. */
+  ThemeSwitcher,
+  /** Floating "↓ Jump to latest" button. */
+  ScrollToPresentButton,
+  /** Collapsible reasoning block inside an assistant bubble. */
+  ReasoningView,
+  /** Collapsible tool-call card. */
+  ToolCallView,
+  /** Role-gated admin UI (returns null for `user`-role callers). */
+  AdminShell: DataClubAIHubAdmin,
+} as const;
+
+/** The `AIHub` namespace type — exported for consumers that type-spread it. */
+export type AIHubNamespace = typeof AIHub;