@data-club/ai-hub 0.0.1

package/src/stories/TpmBanner.stories.tsx

@@ -0,0 +1,93 @@
+/**
+ * Stories for `<TpmBanner />` — TPM-recovery banner with live
+ * countdown.
+ *
+ * The banner reads state from the provider; we mount each story under
+ * `<MockProvider>` and feed a fixed `nowProvider` so the countdown
+ * shows a deterministic value (60s / 5s) regardless of wall-clock.
+ *
+ * The "exhausted" path is gated on `lastTurnError` containing the word
+ * "rate" (case-insensitive) per the component's matching rule.
+ *
+ * @see SPECIFICATIONS.md §6.5 — TPM recovery
+ * @see SPECIFICATIONS.md §10.4 — phase-bound predicates
+ */
+import type { Meta, StoryObj } from "@storybook/react-vite";
+
+import { TpmBanner } from "../components/TpmBanner/index.js";
+
+import { MockProvider, type MockProviderOpts } from "./_mockProvider.js";
+
+/** Fixed "now" so the countdown is deterministic in the iframe. */
+const NOW_MS = Date.parse("2026-05-13T12:00:00Z");
+const RETRY_AT_60S = new Date(NOW_MS + 60_000).toISOString();
+const RETRY_AT_5S = new Date(NOW_MS + 5_000).toISOString();
+
+function withProvider(opts: MockProviderOpts) {
+  return (Story: () => React.ReactNode) => (
+    <MockProvider opts={opts}>
+      <Story />
+    </MockProvider>
+  );
+}
+
+const meta: Meta<typeof TpmBanner> = {
+  title: "Affordances/TpmBanner",
+  component: TpmBanner,
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Specialization of SystemNotice that renders during waiting_provider, briefly flashes Resumed on recovery, and surfaces a Retry action on tpm_exhausted. Renders nothing otherwise.",
+      },
+    },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof TpmBanner>;
+
+export const WaitingPhase60sLeft: Story = {
+  decorators: [
+    withProvider({
+      status: "running",
+      phase: "waiting_provider",
+      tpm_retry_at: RETRY_AT_60S,
+    }),
+  ],
+  args: { nowProvider: () => NOW_MS },
+};
+
+export const WaitingPhase5sLeft: Story = {
+  decorators: [
+    withProvider({
+      status: "running",
+      phase: "waiting_provider",
+      tpm_retry_at: RETRY_AT_5S,
+    }),
+  ],
+  args: { nowProvider: () => NOW_MS },
+};
+
+export const Exhausted: Story = {
+  decorators: [
+    withProvider({
+      status: "failed",
+      phase: null,
+      lastTurnError: "Provider rate limit exhausted after 5 retries.",
+    }),
+  ],
+  args: { onRetry: () => undefined },
+};
+
+export const NoBannerInIdleState: Story = {
+  decorators: [withProvider({ status: "idle", phase: null })],
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "When neither waiting_provider nor an exhausted error is present, the banner self-suppresses and renders nothing.",
+      },
+    },
+  },
+};

package/src/stories/TurnStatusIndicator.stories.tsx

@@ -0,0 +1,86 @@
+/**
+ * Stories for `<TurnStatusIndicator />` — one per row of the §10.4
+ * turn-status table.
+ *
+ * Each story passes an explicit `state` prop AND wraps the component
+ * in `<MockProvider>`, because `TurnStatusIndicator` reads the context
+ * for the default but accepts the override prop for stories + tests.
+ *
+ * @see SPECIFICATIONS.md §10.4 — turn-status indicator table
+ */
+import type { Meta, StoryObj } from "@storybook/react-vite";
+
+import { TurnStatusIndicator } from "../components/TurnStatusIndicator/index.js";
+import type { AIHubState, RunningPhase, TurnStatus } from "../types.js";
+
+import { MockProvider } from "./_mockProvider.js";
+
+function makeState(status: TurnStatus, phase: RunningPhase | null): AIHubState {
+  return {
+    status,
+    phase,
+    last_seq: -1,
+    turn_id: status !== "idle" ? "t-mock" : null,
+    session_id: null,
+    tpm_retry_at: null,
+  };
+}
+
+const meta: Meta<typeof TurnStatusIndicator> = {
+  title: "Affordances/TurnStatusIndicator",
+  component: TurnStatusIndicator,
+  decorators: [
+    (Story) => (
+      <MockProvider>
+        <Story />
+      </MockProvider>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Renders the active turn's (status, phase) as a colored dot + label. Pure function of state; see SPECIFICATIONS.md §10.4.",
+      },
+    },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof TurnStatusIndicator>;
+
+export const Idle: Story = {
+  args: { state: makeState("idle", null) },
+};
+
+export const Running_ModelText: Story = {
+  args: { state: makeState("running", "model_text") },
+};
+
+export const Running_ModelReasoning: Story = {
+  args: { state: makeState("running", "model_reasoning") },
+};
+
+export const Running_ModelToolInput: Story = {
+  args: { state: makeState("running", "model_tool_input") },
+};
+
+export const Running_ToolExecuting: Story = {
+  args: { state: makeState("running", "tool_executing") },
+};
+
+export const Running_WaitingProvider: Story = {
+  args: { state: makeState("running", "waiting_provider") },
+};
+
+export const Done: Story = {
+  args: { state: makeState("done", null) },
+};
+
+export const Cancelled: Story = {
+  args: { state: makeState("cancelled", null) },
+};
+
+export const Failed: Story = {
+  args: { state: makeState("failed", null) },
+};

package/src/stories/_mockProvider.tsx

@@ -0,0 +1,116 @@
+/**
+ * Minimal `<AIHubProvider>` stand-in for Storybook.
+ *
+ * The real provider boots a network client and a pile of `useEffect`s
+ * that fetch `/auth/me`, `/feature-toggles`, etc. — none of which work
+ * in the Storybook iframe. The stories only need the context shape
+ * (status / phase / theme / lastTurnError / messages / …) so we mount
+ * a hand-built `AIHubContextValue` directly.
+ *
+ * Mirrors the pattern in `__tests__/components/Affordances.test.tsx` so
+ * tests + stories share the same minimal context.
+ *
+ * @see packages/ai-hub/__tests__/components/Affordances.test.tsx
+ */
+import { type ReactNode } from "react";
+
+import { aiHubContext, type AIHubContextValue } from "../context/AIHubContext.js";
+import type { AIHubEffort } from "../client/AIHubClient.js";
+import type {
+  AIHubFeatureToggles,
+  AIHubMessage,
+  AIHubState,
+  RunningPhase,
+  TurnStatus,
+} from "../types.js";
+
+/** Options accepted by `<MockProvider>`. Everything is optional. */
+export interface MockProviderOpts {
+  status?: TurnStatus;
+  phase?: RunningPhase | null;
+  tpm_retry_at?: string | null;
+  lastTurnError?: string | null;
+  themeSwitcherEnabled?: boolean;
+  theme?: "light" | "dark";
+  effort?: AIHubEffort;
+  messages?: AIHubMessage[];
+  streamingAssistantText?: string | null;
+  streamingReasoning?: string | null;
+  streamingToolCalls?: AIHubContextValue["streamingToolCalls"];
+  activeSessionId?: string | null;
+  featureToggles?: AIHubFeatureToggles | null;
+}
+
+function noopAsync(): Promise<void> {
+  return Promise.resolve();
+}
+
+function makeState(opts: MockProviderOpts): AIHubState {
+  return {
+    status: opts.status ?? "idle",
+    phase: opts.phase ?? null,
+    last_seq: -1,
+    turn_id: opts.status && opts.status !== "idle" ? "t-mock" : null,
+    session_id: opts.activeSessionId ?? null,
+    tpm_retry_at: opts.tpm_retry_at ?? null,
+  };
+}
+
+/**
+ * Wraps `children` in a fully-populated `aiHubContext.Provider`. Every
+ * function-shaped field is a no-op; non-functional fields fall back to
+ * sensible defaults. The story decides which ones matter via `opts`.
+ */
+export function MockProvider(props: {
+  opts?: MockProviderOpts;
+  children: ReactNode;
+}): ReactNode {
+  const opts = props.opts ?? {};
+  const value: AIHubContextValue = {
+    client: {} as never,
+    user: null,
+    role: null,
+    deployment: null,
+    mustChangePassword: false,
+    hydrating: false,
+    login: (() => Promise.resolve({} as never)) as never,
+    logout: noopAsync,
+    changePassword: noopAsync,
+    state: makeState(opts),
+    effort: opts.effort ?? "medium",
+    setEffort: () => undefined,
+    theme: opts.theme ?? "light",
+    setTheme: noopAsync,
+    themeSwitcherEnabled: opts.themeSwitcherEnabled ?? true,
+    agents: [],
+    agentsLoading: false,
+    refreshAgents: noopAsync,
+    activeAgentId: null,
+    setActiveAgent: () => undefined,
+    sessions: [],
+    sessionsLoading: false,
+    refreshSessions: noopAsync,
+    includeArchivedSessions: false,
+    setIncludeArchivedSessions: () => undefined,
+    activeSessionId: opts.activeSessionId ?? null,
+    setActiveSession: () => undefined,
+    createSession: (() => Promise.resolve({} as never)) as never,
+    patchSession: (() => Promise.resolve({} as never)) as never,
+    messages: opts.messages ?? [],
+    messagesLoading: false,
+    streamingAssistantText: opts.streamingAssistantText ?? null,
+    streamingReasoning: opts.streamingReasoning ?? null,
+    streamingToolCalls: opts.streamingToolCalls ?? [],
+    sendMessage: noopAsync,
+    stop: noopAsync,
+    isStoppingTurn: false,
+    pendingDraft: null,
+    consumePendingDraft: () => null,
+    lastTurnError: opts.lastTurnError ?? null,
+    featureToggles: opts.featureToggles ?? null,
+    refreshFeatureToggles: noopAsync,
+  };
+  return (
+    <aiHubContext.Provider value={value}>{props.children}</aiHubContext.Provider>
+  );
+}

package/src/styles/CLASSES.md

@@ -0,0 +1,356 @@
+# `@data-club/ai-hub` — BEM class contract
+
+> The class names below are the **public contract** every per-customer
+> wrapper relies on for theming. Step 7 ships the root + theme scaffolding;
+> Steps 8–12 fill in the per-component classes as those components land.
+> When a new component class is introduced, append it here so wrappers
+> have one place to grep.
+
+## Root + theming
+
+| Class | What it scopes | When it's set |
+|---|---|---|
+| `.data-club-ai-hub` | Every chat-side component (login, change-password, chat, primitives). Applied to the wrapper `<div>` rendered by `<AIHubProvider>`. | Always present once the provider mounts. |
+| `.data-club-ai-hub-admin` | Every admin-side component (`<DataClubAIHubAdmin />` and sub-pages). Applied to the admin root. | Only when an admin component is rendered. |
+| `.data-club-ai-hub-mount` | Internal: the `<div>` `defineWebComponent` mounts the React root onto. Wrappers should not target this; theme via `.data-club-ai-hub` instead. | Inside Web Component shadow roots. |
+
+### Theme attribute
+
+The active theme is selected by `data-theme="light"` or `data-theme="dark"`
+on the provider's root `<div>`. CSS custom properties redefine themselves
+under the dark-theme attribute selector — components reference the custom
+properties only, never the attribute directly.
+
+```css
+.data-club-ai-hub               { --dc-aih-bg: #ffffff; }
+.data-club-ai-hub[data-theme="dark"] { --dc-aih-bg: #0f1117; }
+```
+
+## CSS custom properties (theming tokens)
+
+Per-customer wrappers override these to brand the UI; they don't fork the
+stylesheet.
+
+### Surface
+
+| Variable | Default (light) | Default (dark) |
+|---|---|---|
+| `--dc-aih-bg` | `#ffffff` | `#0f1117` |
+| `--dc-aih-bg-elevated` | `#f8f9fb` | `#181b23` |
+| `--dc-aih-bg-overlay` | `rgba(255,255,255,0.92)` | `rgba(15,17,23,0.9)` |
+| `--dc-aih-border` | `#e2e5ec` | `#2a2e38` |
+| `--dc-aih-border-strong` | `#c8ccd6` | `#3c4250` |
+
+### Text
+
+| Variable | Default (light) | Default (dark) |
+|---|---|---|
+| `--dc-aih-fg` | `#1a1d24` | `#e8eaef` |
+| `--dc-aih-fg-muted` | `#5c6473` | `#a1a7b3` |
+| `--dc-aih-fg-subtle` | `#8a909c` | `#6c727e` |
+| `--dc-aih-fg-inverse` | `#ffffff` | `#0f1117` |
+
+### Accent (per-customer override target)
+
+| Variable | Default (light) | Default (dark) |
+|---|---|---|
+| `--dc-aih-accent` | `#4a6cf7` | `#7a96ff` |
+| `--dc-aih-accent-hover` | `#3b58d8` | `#95acff` |
+| `--dc-aih-accent-fg` | `#ffffff` | `#0f1117` |
+
+### State + focus
+
+| Variable | Default (light) | Default (dark) |
+|---|---|---|
+| `--dc-aih-success` | `#2f9e44` | `#51cf66` |
+| `--dc-aih-warning` | `#d97706` | `#f59f00` |
+| `--dc-aih-danger` | `#d92d20` | `#ff6b6b` |
+| `--dc-aih-focus-ring` | `rgba(74,108,247,0.4)` | `rgba(122,150,255,0.4)` |
+
+### Scrollbar (themable, applies to every scrollable region in the chat / admin scope)
+
+| Variable | Default (light) | Default (dark) |
+|---|---|---|
+| `--dc-aih-scrollbar-thumb` | `#c8ccd6` | `#3c4250` |
+| `--dc-aih-scrollbar-thumb-hover` | `#a1a7b3` | `#4a5160` |
+| `--dc-aih-scrollbar-track` | `transparent` | `transparent` |
+
+The library styles every scrollable element inside `.data-club-ai-hub` / `.data-club-ai-hub-admin` via Firefox's `scrollbar-color` + WebKit's `::-webkit-scrollbar*` selectors. Override these properties on the root to match brand chrome.
+
+### Markdown renderer (assistant bubble bodies)
+
+| Variable | Default |
+|---|---|
+| `--dc-aih-markdown-code-bg` | `color-mix(in srgb, var(--dc-aih-fg) 6%, transparent)` |
+| `--dc-aih-markdown-code-fg` | `var(--dc-aih-fg)` |
+| `--dc-aih-markdown-quote-border` | `var(--dc-aih-border-strong)` |
+| `--dc-aih-markdown-table-border` | `var(--dc-aih-border)` |
+| `--dc-aih-markdown-table-header-bg` | `var(--dc-aih-bg-elevated)` |
+| `--dc-aih-markdown-link-fg` | `var(--dc-aih-accent)` |
+
+These theme the markdown elements emitted by `<MarkdownRenderer />` (GFM tables, code blocks, blockquotes, links). User bubbles automatically remap them to legible variants against the accent background. KaTeX math styling is governed by `katex/dist/katex.min.css`, which consumers import alongside `default.css` — see [`react/markdown-rendering.md`](../../../docs/react/markdown-rendering.md).
+
+### Sizing / type / motion
+
+| Variable | Default |
+|---|---|
+| `--dc-aih-radius-sm` / `-md` / `-lg` | `4px` / `8px` / `12px` |
+| `--dc-aih-space-xs..xl` | `4px` / `8px` / `16px` / `24px` / `32px` |
+| `--dc-aih-font-sans` | `system-ui, -apple-system, "Segoe UI", Roboto, sans-serif` |
+| `--dc-aih-font-mono` | `ui-monospace, "SF Mono", Menlo, Consolas, monospace` |
+| `--dc-aih-font-size-sm` / `-md` / `-lg` | `0.875rem` / `1rem` / `1.125rem` |
+| `--dc-aih-transition` | `150ms ease-in-out` |
+
+## Component classes
+
+Filled in by Steps 8–12 as each component lands. Convention: BEM,
+kebab-case, with `__` separating block and element and `--` separating
+block and modifier.
+
+### Login screen (Step 8 — `ui-sketches/01-login.md`)
+
+| Class | Where it's applied |
+|---|---|
+| `data-club-ai-hub__login` | Outer wrapper that centers the card. |
+| `data-club-ai-hub__login-card` | The card itself. |
+| `data-club-ai-hub__login-card__title` | Gradient product-name title. |
+| `data-club-ai-hub__login-card__error` | Server-error banner above the form. |
+| `data-club-ai-hub__login-card__form` | The `<form>`. |
+| `data-club-ai-hub__login-card__field` | Each label + input group. |
+| `data-club-ai-hub__login-card__label` | `<label>` element. |
+| `data-club-ai-hub__login-card__input` | Plain inputs (username). |
+| `data-club-ai-hub__login-card__input--password` | Modifier added to the password `<input>` so themers can target it directly. |
+| `data-club-ai-hub__login-card__password` | Wrapper around the password input + toggle (relative positioning). |
+| `data-club-ai-hub__login-card__toggle` | Show/hide eye-icon button. |
+| `data-club-ai-hub__login-card__submit` | Submit button. |
+| `data-club-ai-hub__login-card__forgot` | The static "contact your administrator" note. |
+
+### Change-password screen (Step 8 — `ui-sketches/02-change-password.md`)
+
+| Class | Where it's applied |
+|---|---|
+| `data-club-ai-hub__change-password` | Outer wrapper. |
+| `data-club-ai-hub__change-password-card` | The card itself. |
+| `data-club-ai-hub__change-password-card__title` | Gradient title. |
+| `data-club-ai-hub__change-password-card__intro` | Intro message (forced variant only). |
+| `data-club-ai-hub__change-password-card__error` | Server-error banner. |
+| `data-club-ai-hub__change-password-card__form` | The `<form>`. |
+| `data-club-ai-hub__change-password-card__field` | Each label + input group. |
+| `data-club-ai-hub__change-password-card__label` | `<label>` element. |
+| `data-club-ai-hub__change-password-card__input` | Password inputs. |
+| `data-club-ai-hub__change-password-card__input--password` | Modifier added to all three password inputs. |
+| `data-club-ai-hub__change-password-card__field-error` | Inline client-side validation error under the confirm field. |
+| `data-club-ai-hub__change-password-card__password` | Wrapper around each password input + toggle. |
+| `data-club-ai-hub__change-password-card__toggle` | Per-field show/hide eye button. |
+| `data-club-ai-hub__change-password-card__submit` | Submit button. |
+| `data-club-ai-hub__change-password-card__cancel` | Cancel button (voluntary variant only). |
+
+### Shared
+
+| Class | Where it's applied |
+|---|---|
+| `data-club-ai-hub__spinner` | Inline submit-button spinner (login + change-password). |
+| `data-club-ai-hub__chat-placeholder` | Step-8 chat placeholder (now unused — the real chat replaces it from Step 9). |
+| `data-club-ai-hub__chat-placeholder__body` | Inner block of the placeholder. |
+
+### Shell — Step 9 (`ui-sketches/00-shell.md`)
+
+| Class | Where it's applied |
+|---|---|
+| `data-club-ai-hub__shell` | Outer authenticated shell — flex column wrapping header + main + footer. |
+| `data-club-ai-hub__shell-header` | Sticky top bar (logo on the left, user menu on the right). |
+| `data-club-ai-hub__shell-header-left` | Wrapper-owned slot. When unset, the default gradient logo lives inside. |
+| `data-club-ai-hub__shell-header-logo` | Default gradient text logo derived from `productName`. |
+| `data-club-ai-hub__shell-header-right` | Library-owned right-side region of the shell header (user menu + Step-10 affordances). |
+| `data-club-ai-hub__shell-main` | The body between header and footer. |
+| `data-club-ai-hub__shell-footer` | Wrapper-owned slot; only rendered when `customShellFooter` is set. |
+
+### User menu — Step 9 (`ui-sketches/00-shell.md`)
+
+| Class | Where it's applied |
+|---|---|
+| `data-club-ai-hub__user-menu` | Wrapper holding the button + dropdown. |
+| `data-club-ai-hub__user-menu__button` | The avatar + username button. |
+| `data-club-ai-hub__user-menu__avatar` | Circular avatar inside the button. |
+| `data-club-ai-hub__user-menu__username` | Username text next to the avatar. |
+| `data-club-ai-hub__user-menu__dropdown` | Dropdown rendered when the button is open. |
+| `data-club-ai-hub__user-menu__header` | Header row inside the dropdown (username + role). |
+| `data-club-ai-hub__user-menu__username-large` | Larger username text in the dropdown header. |
+| `data-club-ai-hub__user-menu__role` | Role label below the username. |
+| `data-club-ai-hub__user-menu__item` | A menu item (Sign out today; Theme / Admin / Letta ADE in Steps 10–11). |
+
+### Agents picker — Step 9 (`ui-sketches/03-chat.md`)
+
+| Class | Where it's applied |
+|---|---|
+| `data-club-ai-hub__agents-picker` | Outer wrapper. |
+| `data-club-ai-hub__agents-picker__heading` | Page heading. |
+| `data-club-ai-hub__agents-picker__loading` | Loading state line. |
+| `data-club-ai-hub__agents-picker__error` | Error state banner. |
+| `data-club-ai-hub__agents-picker__empty` | Empty-state container (zero agents). |
+| `data-club-ai-hub__agents-picker__empty-heading` | Empty-state heading. |
+| `data-club-ai-hub__agents-picker__empty-body` | Empty-state body text. |
+| `data-club-ai-hub__agents-picker__grid` | Card grid container. |
+| `data-club-ai-hub__agent-card` | A single clickable agent tile. |
+| `data-club-ai-hub__agent-card__name` | Agent display name. |
+| `data-club-ai-hub__agent-card__subtitle` | Per-caller session-count subtitle. |
+
+### Chat layout — Step 9 (`ui-sketches/03-chat.md`)
+
+| Class | Where it's applied |
+|---|---|
+| `data-club-ai-hub__layout` | Flex container of sessions panel + main column. |
+| `data-club-ai-hub__layout--panel-left` | Modifier when the panel is on the left (default). |
+| `data-club-ai-hub__layout--panel-right` | Modifier when the panel is on the right. |
+| `data-club-ai-hub__sessions-panel` | The sessions sidebar. |
+| `data-club-ai-hub__sessions-panel--collapsed` | Collapsed state (thin reveal strip). |
+| `data-club-ai-hub__sessions-panel__custom-header` | Slot wrapper at the top of the panel. |
+| `data-club-ai-hub__sessions-panel__new-button` | "+ New chat" button. |
+| `data-club-ai-hub__sessions-panel__reveal` | Reveal-strip button shown in collapsed state. |
+| `data-club-ai-hub__sessions-panel__collapse-toggle` | Collapse button shown in expanded state. |
+| `data-club-ai-hub__sessions-panel__list` | Scrollable list region. |
+| `data-club-ai-hub__sessions-panel__empty` | Empty-state line ("No chats yet."). |
+| `data-club-ai-hub__sessions-panel__loading` | Loading state line. |
+| `data-club-ai-hub__sessions-panel__item` | Session row. |
+| `data-club-ai-hub__sessions-panel__item--active` | Modifier for the currently-selected row. |
+| `data-club-ai-hub__sessions-panel__item--archived` | Modifier for archived rows (only visible with the filter on). |
+| `data-club-ai-hub__sessions-panel__item-title` | Row title button (opens the session). |
+| `data-club-ai-hub__sessions-panel__item-meta` | Row meta (relative timestamp). |
+| `data-club-ai-hub__sessions-panel__item-actions` | Hover-revealed action group on the right of the row. |
+| `data-club-ai-hub__sessions-panel__action-button` | Edit / archive / unarchive button. |
+| `data-club-ai-hub__sessions-panel__footer` | Footer wrapping the archived filter + custom slot. |
+| `data-club-ai-hub__sessions-panel__archived-toggle` | Show / hide archived filter. |
+| `data-club-ai-hub__sessions-panel__custom-footer` | Slot wrapper at the bottom of the panel. |
+
+### Main column + message list + input — Step 9 (`ui-sketches/03-chat.md`)
+
+| Class | Where it's applied |
+|---|---|
+| `data-club-ai-hub__main-column` | Right side of the layout (header + body). |
+| `data-club-ai-hub__main-column__body` | Body region under the chat header. |
+| `data-club-ai-hub__chat-header` | The strip above the messages with back-link + agent name. |
+| `data-club-ai-hub__chat-header__back` | `[← Agents]` back-to-picker link. |
+| `data-club-ai-hub__chat-header__title` | Agent display-name text. |
+| `data-club-ai-hub__chat-header__extras` | Slot for `customHeaderContent`. |
+| `data-club-ai-hub__messages` | Scroll container for the message list. |
+| `data-club-ai-hub__messages__inner` | Inner block; `aria-live="polite"` is on this element. |
+| `data-club-ai-hub__messages__empty` | Empty-session placeholder body. |
+| `data-club-ai-hub__messages__no-session` | Placeholder when no session is selected. |
+| `data-club-ai-hub__messages__loading` | Loading state line. |
+| `data-club-ai-hub__messages__error` | Turn-failure banner — surfaced when the send loop ended with an `error` event or no assistant output. Step 10 pairs this with a Retry button. |
+| `data-club-ai-hub__message-bubble` | Per-bubble wrapper. |
+| `data-club-ai-hub__message-bubble--user` | User variant — right-aligned. |
+| `data-club-ai-hub__message-bubble--assistant` | Assistant variant — left-aligned. |
+| `data-club-ai-hub__message-bubble__role` | Role label inside the bubble. |
+| `data-club-ai-hub__message-bubble__body` | Text body inside the bubble. |
+| `data-club-ai-hub__message-bubble__caret` | Thin blinking caret at the end of the streaming-assistant bubble. Step 10 replaces it with the proper §10.4 streaming-dots affordance; until then it's the typing signal. Width / color / animation are themable. |
+| `data-club-ai-hub__input-area` | Outer wrapper for the input. |
+| `data-club-ai-hub__input-area__form` | The `<form>` element. |
+| `data-club-ai-hub__input-area__row` | Row holding the textarea + send/stop button. |
+| `data-club-ai-hub__input-area__textarea` | The auto-growing textarea. |
+| `data-club-ai-hub__input-area__send` | Send button. |
+| `data-club-ai-hub__input-area__stop` | Stop button (replaces send while streaming). |
+| `data-club-ai-hub__input-area__toolbar` | Toolbar slot under the textarea (Step 10 fills it with the effort dropdown). |
+
+### Generic modal — Step 9 (used by SessionTitleModal; reused by Step 11/12 admin modals)
+
+| Class | Where it's applied |
+|---|---|
+| `data-club-ai-hub__modal-overlay` | Backdrop covering the page. |
+| `data-club-ai-hub__modal` | The modal card. |
+| `data-club-ai-hub__modal__title` | Modal heading. |
+| `data-club-ai-hub__modal__form` | `<form>` inside the modal. |
+| `data-club-ai-hub__modal__field` | Field group (label + input). |
+| `data-club-ai-hub__modal__label` | Field label. |
+| `data-club-ai-hub__modal__input` | Text input. |
+| `data-club-ai-hub__modal__field-error` | Inline validation / server error. |
+| `data-club-ai-hub__modal__actions` | Button row at the bottom. |
+| `data-club-ai-hub__modal__cancel` | Cancel button. |
+| `data-club-ai-hub__modal__confirm` | Primary confirm button (Create / Save). |
+
+### Affordance classes — Step 10
+
+| Class | Where it's applied |
+|---|---|
+| `data-club-ai-hub__message-bubble--system` | System-role bubble — centered, italic. Gated by `system_messages_visible` (§8.4). |
+| `data-club-ai-hub__message-bubble--tool` | Tool-role bubble — monospace, dashed border. Gated by `system_messages_visible`. |
+| `data-club-ai-hub__message-bubble--failed` | The latest assistant bubble of a failed turn — danger border, retry button visible. |
+| `data-club-ai-hub__message-bubble--cancelled` | The latest assistant bubble of a cancelled turn — reduced opacity, "Stopped" stamp visible. |
+| `data-club-ai-hub__message-bubble__actions` | Action row inside the bubble (retry, cancelled stamp, custom action slot). |
+| `data-club-ai-hub__message-bubble__retry` | Retry button on `--failed` bubbles. |
+| `data-club-ai-hub__message-bubble__cancelled-stamp` | "Stopped" stamp on `--cancelled` bubbles. |
+| `data-club-ai-hub__turn-status` | Turn-status indicator (chat header). |
+| `data-club-ai-hub__turn-status__dot` | The dot. |
+| `data-club-ai-hub__turn-status__dot--idle` | Dot variant — gray static. |
+| `data-club-ai-hub__turn-status__dot--running` | Dot variant — accent pulsing. |
+| `data-club-ai-hub__turn-status__dot--warning` | Dot variant — yellow pulsing (rate-limit wait). |
+| `data-club-ai-hub__turn-status__dot--error` | Dot variant — red static. |
+| `data-club-ai-hub__turn-status__dot--pulse` | Modifier added when motion is allowed. |
+| `data-club-ai-hub__turn-status__label` | Label next to the dot. |
+| `data-club-ai-hub__theme-switcher` | Theme toggle button. |
+| `data-club-ai-hub__theme-switcher--light` | Modifier when light is active. |
+| `data-club-ai-hub__theme-switcher--dark` | Modifier when dark is active. |
+| `data-club-ai-hub__theme-switcher__icon` | Sun/moon icon span. |
+| `data-club-ai-hub__theme-switcher__label` | Label text next to the icon. |
+| `data-club-ai-hub__system-notice` | Generic banner — base. |
+| `data-club-ai-hub__system-notice--tpm-wait` | TPM-wait variant (warning yellow). |
+| `data-club-ai-hub__system-notice--resumed` | Recovery-resumed variant (success green). |
+| `data-club-ai-hub__system-notice--error` | Non-recoverable variant (danger red). |
+| `data-club-ai-hub__system-notice__icon` | Icon glyph. |
+| `data-club-ai-hub__system-notice__body` | Body text. |
+| `data-club-ai-hub__system-notice__action` | Optional inline action button. |
+| `data-club-ai-hub__reasoning-block` | Reasoning-view wrapper. |
+| `data-club-ai-hub__reasoning-block--collapsed` / `--expanded` | Expansion state. |
+| `data-club-ai-hub__reasoning-block__header` | Header row. |
+| `data-club-ai-hub__reasoning-block__title` | Title text. |
+| `data-club-ai-hub__reasoning-block__toggle` | Expand/collapse toggle. |
+| `data-club-ai-hub__reasoning-block__body` | Body content (monospace, scrollable). |
+| `data-club-ai-hub__tool-call-card` | Tool-call card wrapper. |
+| `data-club-ai-hub__tool-call-card--running` / `--done` / `--error` | Status modifiers. |
+| `data-club-ai-hub__tool-call-card--collapsed` / `--expanded` | Expansion state. |
+| `data-club-ai-hub__tool-call-card__header` | Header row. |
+| `data-club-ai-hub__tool-call-card__tool-name` | Tool name + 🔧 emoji. |
+| `data-club-ai-hub__tool-call-card__status` | Status text. |
+| `data-club-ai-hub__tool-call-card__duration` | Duration text (monospace). |
+| `data-club-ai-hub__tool-call-card__toggle` | Expand/collapse toggle. |
+| `data-club-ai-hub__tool-call-card__body` | Body — input + output/error. |
+| `data-club-ai-hub__tool-call-card__body--error` | Body modifier — error variant. |
+| `data-club-ai-hub__tool-call-card__input-section` / `__output-section` | Sections. |
+| `data-club-ai-hub__tool-call-card__section-label` | Section heading. |
+| `data-club-ai-hub__tool-call-card__section-content` | `<pre>` content. |
+| `data-club-ai-hub__messages-wrapper` | Non-scrolling wrapper around the scroll container; lets the scroll-to-present button stay anchored to the visible chat area instead of sliding off with the content. |
+| `data-club-ai-hub__scroll-to-present-button` | Floating "↓ Jump to latest" button — bottom-center of the wrapper. |
+| `data-club-ai-hub__effort-control` | Effort dropdown wrapper (`<label>`). |
+| `data-club-ai-hub__effort-control__label` | "Effort" label. |
+| `data-club-ai-hub__effort-control__select` | The `<select>` element. |
+| `data-club-ai-hub__markdown` | Wrapper around an assistant bubble's rendered markdown. |
+| `data-club-ai-hub__markdown__p` | Paragraph. |
+| `data-club-ai-hub__markdown__heading` (+ `--1` … `--6`) | Headings + level modifier. |
+| `data-club-ai-hub__markdown__ul` / `__ol` / `__li` | Lists + items. |
+| `data-club-ai-hub__markdown__a` | Markdown link (`target="_blank" rel="noopener noreferrer"`). |
+| `data-club-ai-hub__markdown__blockquote` | Blockquote. |
+| `data-club-ai-hub__markdown__hr` | Horizontal rule. |
+| `data-club-ai-hub__markdown__code--inline` | Inline `<code>` (no language). |
+| `data-club-ai-hub__markdown__pre` | Fenced-code `<pre>` (inner `<code>` keeps `language-<lang>` for highlighters). |
+| `data-club-ai-hub__markdown__table-wrapper` | Horizontal-scroll `<div>` around tables. |
+| `data-club-ai-hub__markdown__table` / `__thead` / `__tbody` / `__tr` / `__th` / `__td` | Table parts. |
+
+## Customizing in a wrapper
+
+The library accepts a `className` prop on every visible component plus a
+`classNames` partial map for individual sub-elements (§7.3). For
+theme-only customizations, prefer overriding the custom properties on
+`.data-club-ai-hub` in the wrapper's `theme.css`:
+
+```css
+/* per-customer wrapper theme.css */
+bankxyz-chat::part(root),
+.data-club-ai-hub {
+  --dc-aih-accent: #d70000;
+  --dc-aih-radius-md: 14px;
+  --dc-aih-font-sans: "Brand Sans", system-ui, sans-serif;
+}
+```
+
+For layout-level changes ("move the input above the messages"), drop to
+**Tier 3** and compose the `AIHub.*` primitives directly.