@data-club/ai-hub 0.0.1

package/src/components/CacheBadge/index.tsx

@@ -0,0 +1,245 @@
+/**
+ * `<CacheBadge />` — small per-message badge surfacing provider token
+ * usage on an assistant bubble. Renders an inline icon + a compact
+ * token count, with the full breakdown in a `title`-attribute tooltip
+ * on hover.
+ *
+ * **What it shows.** Letta reports five things per assistant turn (via
+ * `AIHubMessageUsage`): input tokens, output tokens, cache-read tokens
+ * (prompt-cache HIT — provider charged ~0.1x), cache-write tokens
+ * (provider charged ~1.25x, Anthropic only), reasoning tokens, and a
+ * rolling context-window estimate.
+ *
+ * The headline number we show in the badge is the **cache-hit
+ * percentage of the prompt** — `cache_read / (input + cache_read +
+ * cache_write)`. That number is the single most useful at-a-glance
+ * signal:
+ *   - 0%  → cache is cold (cost is the worst case)
+ *   - 80% → ~10x cheaper system prompt than a cold turn
+ *
+ * The full numbers live in the tooltip. We use the native `title`
+ * attribute instead of a custom popover to keep the component
+ * lightweight and dependency-free (no portals, no animation, no
+ * focus management — perfect for a peripheral info chip).
+ *
+ * **When to render.** Only when the parent passes a `usage` prop with
+ * at least one non-null number. Messages without a usage stamp (e.g.
+ * historical conversations from before this feature shipped, or
+ * tool-only assistant turns where Letta didn't report anything)
+ * simply don't render the badge.
+ *
+ * Exported under `AIHub.CacheBadge` (re-exported via the namespace).
+ *
+ * @see AIHubMessageUsage in `../../types.ts`
+ * @see SPECIFICATIONS.md §9.4 — `usage` SSE event
+ */
+
+import type { ReactNode } from "react";
+
+import type { AIHubMessageUsage } from "../../types.js";
+
+/** BEM class names emitted by `<CacheBadge />`. */
+export interface CacheBadgeClassNames {
+  /** Outer span; `data-cache-state="hot|warm|cold|none"` for skinning. */
+  root: string;
+  /** The leading icon character (default 💾). */
+  icon: string;
+  /** The headline percentage label. */
+  label: string;
+}
+
+const DEFAULT_CLASS_NAMES: CacheBadgeClassNames = Object.freeze({
+  root: "data-club-ai-hub__cache-badge",
+  icon: "data-club-ai-hub__cache-badge__icon",
+  label: "data-club-ai-hub__cache-badge__label",
+}) as CacheBadgeClassNames;
+
+/** Localizable strings for the badge headline + tooltip. */
+export interface CacheBadgeTexts {
+  /** Headline shown when there's no cache info at all (e.g. providers that don't report). */
+  noCacheLabel: string;
+  /** Headline shown when this turn was a full cache miss (no tokens served from cache). */
+  missLabel: string;
+  /** Headline shown when this turn was a cache priming write — read=0 but write>0. */
+  writePrimingLabel: string;
+  /** Headline prefix for cache hits — full text is `${hitLabel} ${N}%`. */
+  hitLabel: string;
+  /** Tooltip line prefixes. Keep short — the tooltip is `title` only. */
+  hitTooltipLabel: string;
+  writeTooltipLabel: string;
+  inputLabel: string;
+  outputLabel: string;
+  reasoningLabel: string;
+  contextLabel: string;
+  totalLabel: string;
+}
+
+export const DEFAULT_TEXTS: CacheBadgeTexts = Object.freeze({
+  noCacheLabel: "no data",
+  missLabel: "MISS",
+  writePrimingLabel: "PRIMING",
+  hitLabel: "HIT",
+  hitTooltipLabel: "Cache hit",
+  writeTooltipLabel: "Cache write",
+  inputLabel: "Input",
+  outputLabel: "Output",
+  reasoningLabel: "Reasoning",
+  contextLabel: "Context",
+  totalLabel: "Total",
+}) as CacheBadgeTexts;
+
+/** Props for `<CacheBadge />`. */
+export interface CacheBadgeProps {
+  /** Per-message usage, as returned by `GET /sessions/:id/messages`. */
+  usage: AIHubMessageUsage;
+  /** Optional class-name overrides. */
+  classNames?: Partial<CacheBadgeClassNames>;
+  /** Optional text overrides (l10n). */
+  texts?: Partial<CacheBadgeTexts>;
+}
+
+/**
+ * Computes the cache-hit ratio (0..1) over the prompt-side tokens.
+ *
+ * Denominator: `input + cache_read + cache_write` — every prompt
+ * token the provider saw, regardless of whether it served from cache
+ * or wrote new. We exclude `output` and `reasoning` because those
+ * are completion-side and can't benefit from prompt caching.
+ *
+ * Exported so the test suite can assert numerically.
+ */
+export function computeCacheHitRatio(usage: AIHubMessageUsage): number | null {
+  const read = usage.cache_read ?? 0;
+  const write = usage.cache_write ?? 0;
+  const input = usage.input ?? 0;
+  const denom = read + write + input;
+  if (denom === 0) return null;
+  return read / denom;
+}
+
+/**
+ * Bucket the usage into a discrete state for skinning + label choice.
+ *
+ *   - `none`    — no prompt-side tokens reported at all (provider
+ *                 didn't expose usage, or empty turn). Badge shows
+ *                 the "no data" label.
+ *   - `miss`    — full cache miss: `cache_read = 0` AND
+ *                 `cache_write = 0` (or not reported). The provider
+ *                 had to reinitialize the whole prompt. Badge shows
+ *                 "MISS" in cold (grey) styling.
+ *   - `priming` — `cache_read = 0` but `cache_write > 0`. This
+ *                 turn's prompt was a CACHE WRITE — the provider
+ *                 paid full price now and future turns benefit.
+ *                 Anthropic only (the other providers don't report
+ *                 writes). Badge shows "PRIMING".
+ *   - `cold`    — `cache_read > 0` but ratio < 10%. Hit registered
+ *                 but most of the prompt was new.
+ *   - `warm`    — 10–60% of the prompt was cached.
+ *   - `hot`     — 60%+ of the prompt was cached.
+ */
+type CacheState = "none" | "miss" | "priming" | "cold" | "warm" | "hot";
+
+function bucketState(usage: AIHubMessageUsage, ratio: number | null): CacheState {
+  if (ratio === null) return "none";
+  if (ratio === 0) {
+    // No cache hit. Distinguish full-miss (nothing cached anywhere)
+    // from priming (we WROTE to the cache this turn — next turn will
+    // benefit). The latter is good news, the former is bad news, so
+    // the user-facing labels should differ.
+    return (usage.cache_write ?? 0) > 0 ? "priming" : "miss";
+  }
+  if (ratio >= 0.6) return "hot";
+  if (ratio >= 0.1) return "warm";
+  return "cold";
+}
+
+/** Formats a token count as a compact human-readable string: 1234 → 1.2k. */
+function formatTokens(n: number | null | undefined): string {
+  if (n === null || n === undefined) return "—";
+  if (n < 1000) return String(n);
+  if (n < 1_000_000) return `${(n / 1000).toFixed(1)}k`;
+  return `${(n / 1_000_000).toFixed(2)}M`;
+}
+
+/** Builds the `title`-attribute tooltip text from the usage object. */
+function buildTooltip(usage: AIHubMessageUsage, texts: CacheBadgeTexts): string {
+  const lines: string[] = [];
+  if (usage.cache_read !== null && usage.cache_read !== undefined) {
+    lines.push(`${texts.hitTooltipLabel}: ${formatTokens(usage.cache_read)}`);
+  }
+  if (usage.cache_write !== null && usage.cache_write !== undefined) {
+    lines.push(`${texts.writeTooltipLabel}: ${formatTokens(usage.cache_write)}`);
+  }
+  if (usage.input !== null && usage.input !== undefined) {
+    lines.push(`${texts.inputLabel}: ${formatTokens(usage.input)}`);
+  }
+  if (usage.output !== null && usage.output !== undefined) {
+    lines.push(`${texts.outputLabel}: ${formatTokens(usage.output)}`);
+  }
+  if (usage.reasoning !== null && usage.reasoning !== undefined && usage.reasoning > 0) {
+    lines.push(`${texts.reasoningLabel}: ${formatTokens(usage.reasoning)}`);
+  }
+  if (usage.context !== null && usage.context !== undefined) {
+    lines.push(`${texts.contextLabel}: ${formatTokens(usage.context)}`);
+  }
+  if (usage.total !== null && usage.total !== undefined) {
+    lines.push(`${texts.totalLabel}: ${formatTokens(usage.total)}`);
+  }
+  return lines.join("\n");
+}
+
+/** Returns true when the usage object has at least one usable numeric field. */
+function hasAnyData(usage: AIHubMessageUsage): boolean {
+  return (
+    (usage.input ?? null) !== null ||
+    (usage.output ?? null) !== null ||
+    (usage.cache_read ?? null) !== null ||
+    (usage.cache_write ?? null) !== null ||
+    (usage.reasoning ?? null) !== null ||
+    (usage.context ?? null) !== null ||
+    (usage.total ?? null) !== null
+  );
+}
+
+export function CacheBadge({
+  usage,
+  classNames,
+  texts,
+}: CacheBadgeProps): ReactNode {
+  if (!hasAnyData(usage)) return null;
+  const cls: CacheBadgeClassNames = { ...DEFAULT_CLASS_NAMES, ...(classNames ?? {}) };
+  const t: CacheBadgeTexts = { ...DEFAULT_TEXTS, ...(texts ?? {}) };
+
+  const ratio = computeCacheHitRatio(usage);
+  const state = bucketState(usage, ratio);
+  // Headline label — varies by state so the user gets an immediate
+  // diagnostic signal at-a-glance.
+  let headline: string;
+  if (state === "none") {
+    headline = t.noCacheLabel;
+  } else if (state === "miss") {
+    headline = t.missLabel;
+  } else if (state === "priming") {
+    headline = t.writePrimingLabel;
+  } else {
+    // hot / warm / cold — ratio is guaranteed non-null here.
+    headline = `${t.hitLabel} ${Math.round((ratio ?? 0) * 100)}%`;
+  }
+  const tooltip = buildTooltip(usage, t);
+
+  return (
+    <span
+      className={cls.root}
+      data-testid="cache-badge"
+      data-cache-state={state}
+      title={tooltip}
+      role="status"
+      aria-label={tooltip}
+    >
+      <span className={cls.icon} aria-hidden="true">
+        💾
+      </span>
+      <span className={cls.label}>{headline}</span>
+    </span>
+  );
+}

package/src/components/ChangePassword/index.tsx

@@ -0,0 +1,375 @@
+/**
+ * `<DataClubAIHubChangePassword />` — the built-in change-password screen.
+ *
+ * Two variants in one component:
+ *
+ * - **Forced** (`variant="forced"`) — auto-rendered after login when
+ *   `useAIHubAuth().mustChangePassword === true`. No `current_password`
+ *   field, no cancel button (there is nowhere else to go), with an
+ *   `intro_message` explaining the requirement. Submit calls
+ *   `client.changePassword(null, newPassword)` — the change-only token
+ *   is itself the proof of authentication.
+ * - **Voluntary** (`variant="voluntary"`) — opened from the user-menu
+ *   ([00-shell.md](ui-sketches/00-shell.md)). Includes `current_password`
+ *   and a `Cancel` button that fires `onCancel`. Submit calls
+ *   `client.changePassword(currentPassword, newPassword)`.
+ *
+ * Each password field carries its own `show_password_toggle` — the
+ * regression-guard for the per-field pattern is in
+ * `__tests__/components/ChangePassword.test.tsx`.
+ *
+ * The client mirrors the §8.5 password policy via
+ * `validatePasswordPolicyClient` so the form surfaces too-short /
+ * too-simple errors *before* sending; the server is authoritative and
+ * its banner wins if the two ever disagree.
+ *
+ * @see SPECIFICATIONS.md §7.2.1 (and §7.3 — auth is owned by the library)
+ * @see SPECIFICATIONS.md §8.5  — password policy + forced/voluntary semantics
+ * @see ui-sketches/02-change-password.md — visual contract
+ */
+
+import { useState, type FormEvent, type ReactNode } from "react";
+
+import { AIHubRequestError } from "../../client/AIHubClient.js";
+import { useAIHubAuth } from "../../context/useAIHubAuth.js";
+import {
+  resolveAIHubTexts,
+  type AIHubTexts,
+  type DeepPartial,
+} from "../../auth/texts.js";
+import { validatePasswordPolicyClient } from "../../auth/passwordPolicy.js";
+import { PasswordInput } from "../internal/PasswordInput.js";
+
+/**
+ * BEM class names emitted by `<DataClubAIHubChangePassword />`. Wrappers
+ * pass a partial map via `classNames` to override individual entries for
+ * utility-CSS frameworks.
+ */
+export interface AIHubChangePasswordClassNames {
+  /** Outer page wrapper (centers the card in the viewport). */
+  root: string;
+  /** The card itself. */
+  card: string;
+  /** Gradient title at the top. */
+  title: string;
+  /** Intro message (forced variant only). */
+  intro: string;
+  /** Error banner shown above the form on failure. */
+  errorBanner: string;
+  /** Form container. */
+  form: string;
+  /** Label / field group wrapper. */
+  fieldGroup: string;
+  /** `<label>` for an input. */
+  fieldLabel: string;
+  /** Inline field-level error message. */
+  fieldError: string;
+  /** Password input wrapper (input + show toggle). */
+  passwordWrapper: string;
+  /** The password `<input>` itself. */
+  passwordInput: string;
+  /** The show/hide-password toggle button. */
+  passwordToggle: string;
+  /** Submit button. */
+  submitButton: string;
+  /** Cancel button (voluntary variant only). */
+  cancelButton: string;
+  /** Spinner glyph rendered inside the submit button while saving. */
+  spinner: string;
+}
+
+/**
+ * Default BEM class names. Stable, kebab-case, scoped under
+ * `data-club-ai-hub__change-password`. Wrappers override individual entries
+ * via `classNames`.
+ */
+const DEFAULT_CLASS_NAMES: AIHubChangePasswordClassNames = Object.freeze({
+  root: "data-club-ai-hub__change-password",
+  card: "data-club-ai-hub__change-password-card",
+  title: "data-club-ai-hub__change-password-card__title",
+  intro: "data-club-ai-hub__change-password-card__intro",
+  errorBanner: "data-club-ai-hub__change-password-card__error",
+  form: "data-club-ai-hub__change-password-card__form",
+  fieldGroup: "data-club-ai-hub__change-password-card__field",
+  fieldLabel: "data-club-ai-hub__change-password-card__label",
+  fieldError: "data-club-ai-hub__change-password-card__field-error",
+  passwordWrapper: "data-club-ai-hub__change-password-card__password",
+  passwordInput:
+    "data-club-ai-hub__change-password-card__input data-club-ai-hub__change-password-card__input--password",
+  passwordToggle: "data-club-ai-hub__change-password-card__toggle",
+  submitButton: "data-club-ai-hub__change-password-card__submit",
+  cancelButton: "data-club-ai-hub__change-password-card__cancel",
+  spinner: "data-club-ai-hub__spinner",
+}) as AIHubChangePasswordClassNames;
+
+/**
+ * Props for `<DataClubAIHubChangePassword />`. See §7.2.1.
+ */
+export interface DataClubAIHubChangePasswordProps {
+  /**
+   * Which variant to render. **`"forced"`** (default — what `AuthGate`
+   * mounts after a successful login with `is_initial_password=true`) hides
+   * the current-password field + cancel button, and shows an intro
+   * message. **`"voluntary"`** (from the user-menu) shows all three fields
+   * + a cancel button.
+   */
+  variant?: "forced" | "voluntary";
+  /**
+   * Fires after a successful password change. The provider has already
+   * stored the fresh session token + refreshed `/auth/me` when this fires,
+   * so the caller can read the now-updated `useAIHubAuth().user` directly.
+   */
+  onChanged?: () => void;
+  /**
+   * Fires when the user clicks Cancel on the voluntary variant. Ignored on
+   * the forced variant (there is nowhere else to go).
+   */
+  onCancel?: () => void;
+  /** Extra class merged onto the root wrapper alongside the BEM defaults. */
+  className?: string;
+  /** Per-element class-name overrides. */
+  classNames?: Partial<AIHubChangePasswordClassNames>;
+  /**
+   * Wrapper-supplied i18n. Missing keys fall back to English defaults.
+   * Only the `changePassword` namespace is consulted by this component.
+   */
+  texts?: DeepPartial<AIHubTexts>;
+}
+
+/**
+ * Renders the change-password card.
+ *
+ * @param props - see `DataClubAIHubChangePasswordProps`.
+ * @returns the rendered card.
+ */
+export function DataClubAIHubChangePassword(
+  props: DataClubAIHubChangePasswordProps,
+): ReactNode {
+  const auth = useAIHubAuth();
+  const variant = props.variant ?? "forced";
+  const classes = { ...DEFAULT_CLASS_NAMES, ...(props.classNames ?? {}) };
+  const texts = resolveAIHubTexts(props.texts).changePassword;
+
+  const [currentPassword, setCurrentPassword] = useState("");
+  const [newPassword, setNewPassword] = useState("");
+  const [confirmPassword, setConfirmPassword] = useState("");
+  const [submitting, setSubmitting] = useState(false);
+  const [errorMessage, setErrorMessage] = useState<string | null>(null);
+
+  // Client-side validation produces an inline field-error message — separate
+  // from the top-of-card error banner, which is reserved for server errors.
+  const fieldError: string | null = (() => {
+    if (newPassword.length === 0 && confirmPassword.length === 0) return null;
+    const policy = validatePasswordPolicyClient(newPassword);
+    if (!policy.ok) {
+      if (policy.code === "password_too_short") return texts.passwordTooShortError;
+      return texts.passwordTooSimpleError;
+    }
+    if (confirmPassword.length > 0 && newPassword !== confirmPassword) {
+      return texts.passwordsMustMatchError;
+    }
+    return null;
+  })();
+
+  // Submit-disable predicate: voluntary needs all three; forced needs two.
+  const fieldsFilled =
+    newPassword.length > 0 &&
+    confirmPassword.length > 0 &&
+    newPassword === confirmPassword &&
+    (variant === "forced" || currentPassword.length > 0);
+
+  const submitDisabled = submitting || !fieldsFilled || fieldError !== null;
+
+  const handleSubmit = async (e: FormEvent<HTMLFormElement>): Promise<void> => {
+    e.preventDefault();
+    if (submitDisabled) return;
+
+    setSubmitting(true);
+    setErrorMessage(null);
+    try {
+      await auth.changePassword(
+        variant === "voluntary" ? currentPassword : null,
+        newPassword,
+      );
+      props.onChanged?.();
+    } catch (err) {
+      if (err instanceof AIHubRequestError) {
+        // Map the wire error code to a localized banner. Server's
+        // password-policy errors trump the client mirror — the server is
+        // authoritative (§8.5).
+        if (err.code === "password_too_short") {
+          setErrorMessage(texts.passwordTooShortError);
+        } else if (err.code === "password_too_simple") {
+          setErrorMessage(texts.passwordTooSimpleError);
+        } else if (err.code === "unauthorized" || err.status === 401) {
+          setErrorMessage(texts.invalidCurrentPasswordError);
+        } else if (err.code === "network") {
+          setErrorMessage(texts.networkError);
+        } else {
+          // Fall back to the server message — it's safe to surface per §9.
+          setErrorMessage(err.message || texts.networkError);
+        }
+      } else {
+        setErrorMessage(texts.networkError);
+      }
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  const rootClass =
+    props.className !== undefined
+      ? `${classes.root} ${props.className}`
+      : classes.root;
+
+  return (
+    <div
+      className={rootClass}
+      data-testid="change-password-root"
+      data-variant={variant}
+    >
+      <div
+        className={classes.card}
+        role="form"
+        aria-labelledby="dc-aih-change-password-title"
+      >
+        <h1
+          id="dc-aih-change-password-title"
+          className={classes.title}
+        >
+          {texts.title}
+        </h1>
+
+        {variant === "forced" ? (
+          <p className={classes.intro} data-testid="change-password-intro">
+            {texts.forcedChangePasswordIntro}
+          </p>
+        ) : null}
+
+        {errorMessage !== null ? (
+          <div
+            className={classes.errorBanner}
+            role="alert"
+            aria-live="polite"
+            data-testid="change-password-error"
+          >
+            {errorMessage}
+          </div>
+        ) : null}
+
+        <form className={classes.form} onSubmit={handleSubmit} noValidate>
+          {variant === "voluntary" ? (
+            <div className={classes.fieldGroup}>
+              <label
+                htmlFor="dc-aih-change-current"
+                className={classes.fieldLabel}
+              >
+                {texts.currentPasswordLabel}
+              </label>
+              <PasswordInput
+                id="dc-aih-change-current"
+                value={currentPassword}
+                onChange={setCurrentPassword}
+                name="current_password"
+                autoComplete="current-password"
+                disabled={submitting}
+                required
+                autoFocus
+                showAriaLabel={texts.showPasswordAriaLabel}
+                hideAriaLabel={texts.hidePasswordAriaLabel}
+                wrapperClassName={classes.passwordWrapper}
+                inputClassName={classes.passwordInput}
+                toggleClassName={classes.passwordToggle}
+                testId="change-current-field"
+              />
+            </div>
+          ) : null}
+
+          <div className={classes.fieldGroup}>
+            <label htmlFor="dc-aih-change-new" className={classes.fieldLabel}>
+              {texts.newPasswordLabel}
+            </label>
+            <PasswordInput
+              id="dc-aih-change-new"
+              value={newPassword}
+              onChange={setNewPassword}
+              name="new_password"
+              autoComplete="new-password"
+              disabled={submitting}
+              required
+              {...(variant === "forced" ? { autoFocus: true } : {})}
+              showAriaLabel={texts.showPasswordAriaLabel}
+              hideAriaLabel={texts.hidePasswordAriaLabel}
+              wrapperClassName={classes.passwordWrapper}
+              inputClassName={classes.passwordInput}
+              toggleClassName={classes.passwordToggle}
+              testId="change-new-field"
+            />
+          </div>
+
+          <div className={classes.fieldGroup}>
+            <label
+              htmlFor="dc-aih-change-confirm"
+              className={classes.fieldLabel}
+            >
+              {texts.confirmPasswordLabel}
+            </label>
+            <PasswordInput
+              id="dc-aih-change-confirm"
+              value={confirmPassword}
+              onChange={setConfirmPassword}
+              name="confirm_password"
+              autoComplete="new-password"
+              disabled={submitting}
+              required
+              showAriaLabel={texts.showPasswordAriaLabel}
+              hideAriaLabel={texts.hidePasswordAriaLabel}
+              wrapperClassName={classes.passwordWrapper}
+              inputClassName={classes.passwordInput}
+              toggleClassName={classes.passwordToggle}
+              testId="change-confirm-field"
+            />
+            {fieldError !== null ? (
+              <div
+                className={classes.fieldError}
+                role="status"
+                aria-live="polite"
+                data-testid="change-password-field-error"
+              >
+                {fieldError}
+              </div>
+            ) : null}
+          </div>
+
+          <button
+            type="submit"
+            className={classes.submitButton}
+            disabled={submitDisabled}
+            data-testid="change-password-submit"
+          >
+            {submitting ? (
+              <>
+                <span className={classes.spinner} aria-hidden="true" />
+                {texts.savingButton}
+              </>
+            ) : (
+              texts.changePasswordButton
+            )}
+          </button>
+
+          {variant === "voluntary" ? (
+            <button
+              type="button"
+              className={classes.cancelButton}
+              onClick={() => props.onCancel?.()}
+              disabled={submitting}
+              data-testid="change-password-cancel"
+            >
+              {texts.cancelButton}
+            </button>
+          ) : null}
+        </form>
+      </div>
+    </div>
+  );
+}

package/src/components/ChatShell/ShellHeader.tsx

@@ -0,0 +1,80 @@
+/**
+ * `<ShellHeader />` — the sticky top bar wrapping every authenticated
+ * view ([00-shell.md]).
+ *
+ * Lives in both the chat shell AND the admin shell — Step 11 split it
+ * out of `<ChatShell />` so the admin view doesn't lose the user-menu /
+ * log-out / theme toggle / Open Letta ADE affordances when the user
+ * navigates from chat to admin.
+ *
+ * Left side: wrapper-supplied slot (`customShellHeaderLeft`) or default
+ * gradient text logo derived from `productName`. **Right side:
+ * library-owned** — the `<UserMenu />` is non-customizable per
+ * [00-shell.md] because it carries session, role, and `Open Letta ADE`
+ * affordances ai-hub controls.
+ *
+ * @see ui-sketches/00-shell.md
+ */
+import type { ReactNode } from "react";
+
+import type { AIHubChatTexts } from "../../auth/texts.js";
+
+import { UserMenu } from "./UserMenu.js";
+
+/**
+ * Props for `<ShellHeader />`.
+ */
+export interface ShellHeaderProps {
+  /** Default-logo source (when `customShellHeaderLeft` is unset). */
+  productName: string;
+  /** Wrapper-supplied logo / nav-links slot. */
+  customShellHeaderLeft?: ReactNode;
+  /** Resolved chat texts (the user-menu copy lives under `texts.chat`). */
+  texts: AIHubChatTexts;
+  /**
+   * Fired when the user picks "Admin" from the user menu. Wired to the
+   * monolith's chat ↔ admin route swap; omitted by Tier-3 wrappers that
+   * handle navigation themselves.
+   */
+  onOpenAdmin?: () => void;
+}
+
+/**
+ * Renders the sticky shell header.
+ *
+ * @param props - see `ShellHeaderProps`.
+ * @returns the rendered header.
+ */
+export function ShellHeader(props: ShellHeaderProps): ReactNode {
+  return (
+    <header
+      className="data-club-ai-hub__shell-header"
+      data-testid="shell-header"
+    >
+      <div
+        className="data-club-ai-hub__shell-header-left"
+        data-testid="shell-header-left"
+      >
+        {props.customShellHeaderLeft ?? (
+          <span
+            className="data-club-ai-hub__shell-header-logo"
+            data-testid="shell-header-default-logo"
+          >
+            {props.productName}
+          </span>
+        )}
+      </div>
+      <div
+        className="data-club-ai-hub__shell-header-right"
+        data-testid="shell-header-right"
+      >
+        <UserMenu
+          texts={props.texts}
+          {...(props.onOpenAdmin !== undefined
+            ? { onOpenAdmin: props.onOpenAdmin }
+            : {})}
+        />
+      </div>
+    </header>
+  );
+}