@etamong-playground/ui 0.34.2

package/dist/index.d.ts

@@ -0,0 +1,1800 @@
+import * as react from 'react';
+import { ReactNode, AnchorHTMLAttributes, MouseEvent } from 'react';
+
+/** A single command-palette entry. */
+interface CommandItem {
+    /** Stable unique id (used as the React key). */
+    id: string;
+    /** Visible label in the active locale. */
+    label: string;
+    /** Right-aligned secondary text (e.g. a parent group name). */
+    sublabel?: string;
+    /**
+     * The string cmdk filters on. To make search work across languages, build
+     * this with `crossLocaleKeywords` so it contains the label in every locale.
+     * Defaults to `label` when omitted.
+     */
+    keywords?: string;
+    /** Leading icon — any node (lucide, inline SVG). Icon library stays the app's choice. */
+    icon?: ReactNode;
+    /** Navigation target; selecting calls `onNavigate(href)`. */
+    href?: string;
+    /** Action callback; selecting invokes it. Takes precedence over `href`. */
+    onSelect?: () => void;
+    /** Hidden unless the palette is rendered with `isAdmin`. */
+    adminOnly?: boolean;
+}
+/** An ordered, headed group of items. */
+interface CommandSection {
+    id: string;
+    heading: string;
+    items: CommandItem[];
+    /** Keep the group mounted even with no text match (e.g. a "search for …" row). */
+    forceMount?: boolean;
+}
+/**
+ * A bottom, always-mounted "search for …" action that receives the live query.
+ * Selecting one typically pushes to a search/list route carrying the text, so an
+ * unmatched query still becomes a real search.
+ */
+interface CommandSearchAction {
+    id: string;
+    label: string;
+    keywords?: string;
+    icon?: ReactNode;
+    /** Called with the current input text on select. */
+    run: (query: string) => void;
+}
+/** Overridable UI strings (defaults are English). */
+interface CommandPaletteLabels {
+    placeholder: string;
+    noResults: string;
+    /** Heading for the always-mounted search-actions group. */
+    searchHeading: string;
+}
+
+interface CommandPaletteProps {
+    /** Ordered groups rendered top-to-bottom. */
+    sections: CommandSection[];
+    /** Always-mounted "search for …" actions, rendered last; receive the live query. */
+    searchActions?: CommandSearchAction[];
+    /** Called with an item's `href` on select (e.g. `router.push`). */
+    onNavigate?: (href: string) => void;
+    /** When false, items marked `adminOnly` are filtered out. Default false. */
+    isAdmin?: boolean;
+    /** Override the input placeholder / empty-state text. */
+    labels?: Partial<CommandPaletteLabels>;
+    /** Also open on "/" (ignored inside inputs). Default true. */
+    openOnSlash?: boolean;
+    /** Controlled open state. Omit to let the palette own it (⌘K / "/" / event). */
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+}
+/**
+ * A configurable ⌘K command palette built on cmdk and styled from the
+ * @etamong-playground/ui tokens (import "@etamong-playground/ui/styles.css"). Mount it once,
+ * globally, when the user is authenticated.
+ *
+ * Opens on ⌘K / Ctrl+K, on "/" (unless typing), and on the
+ * `command-palette:open` DOM event. Search filters on each item's `keywords`
+ * (build them with `crossLocaleKeywords` for cross-language matching).
+ */
+declare function CommandPalette({ sections, searchActions, onNavigate, isAdmin, labels, openOnSlash, open: controlledOpen, onOpenChange, }: CommandPaletteProps): react.JSX.Element;
+
+interface CommandPaletteTriggerProps {
+    /** Visible placeholder-style label, e.g. "Search…". */
+    label?: string;
+    /** Extra class merged with `etu-palette-trigger`. */
+    className?: string;
+}
+/**
+ * A search-box-styled button that opens the command palette — so users discover
+ * it exists. Shows a magnifier + label + the ⌘K / Ctrl+K hint and dispatches the
+ * `command-palette:open` event. Styled from @etamong-playground/ui tokens; drop it in a
+ * sidebar/header.
+ */
+declare function CommandPaletteTrigger({ label, className }: CommandPaletteTriggerProps): react.JSX.Element;
+
+interface GoToRoute {
+    /** Second key after the "g" prefix (e.g. "s" for `g s`). */
+    key: string;
+    /** Destination passed to `onNavigate`. */
+    href: string;
+    /** Skipped unless `isAdmin`. */
+    adminOnly?: boolean;
+}
+interface GoToOptions {
+    isAdmin?: boolean;
+    /** How long the "g" prefix stays armed, ms. Default 1500. */
+    timeoutMs?: number;
+}
+/**
+ * Two-key "go-to" navigation: press `g`, then a letter within the timeout, to
+ * jump. Korean-IME-safe (resolves the logical key via `shortcutKey`/`e.code`),
+ * ignores text-entry targets, modifier combos, and key repeats.
+ *
+ * Returns the armed prefix ("g") or null — render it as a small indicator.
+ *
+ * @example
+ *   const pending = useGoToShortcuts(
+ *     [{ key: "h", href: "/" }, { key: "s", href: "/schedules" }],
+ *     (href) => router.push(href),
+ *     { isAdmin },
+ *   );
+ */
+declare function useGoToShortcuts(routes: GoToRoute[], onNavigate: (href: string) => void, options?: GoToOptions): string | null;
+
+/**
+ * Concatenate one label across every locale dictionary so cmdk search matches
+ * regardless of the active language — a Korean user typing an English term (or
+ * vice-versa) still finds the item. This is mandatory in a ko-first ecosystem.
+ *
+ * @example
+ *   import ko from "./locales/ko";
+ *   import en from "./locales/en";
+ *   const dicts = [ko, en];
+ *   crossLocaleKeywords(dicts, (d) => d.nav.schedules) // "일정 Schedules"
+ */
+declare function crossLocaleKeywords<D>(dicts: readonly D[], getter: (dict: D) => string): string;
+/** True when the keyboard event originates from a text-entry control. */
+declare function isInputTarget(e: KeyboardEvent): boolean;
+/**
+ * Map physical key codes to logical keys so shortcuts survive a Korean IME:
+ * when an IME is active `e.key` is a Hangul syllable, not the Latin letter, so
+ * single-letter shortcuts must fall back to `e.code`.
+ */
+declare const CODE_TO_KEY: Readonly<Record<string, string>>;
+/**
+ * Resolve the logical shortcut key for an event. Prefers `e.key` when it is
+ * already an ASCII shortcut (`/`, `?`, or a–z); otherwise falls back to the
+ * physical-code map (covers IME output).
+ */
+declare function shortcutKey(e: KeyboardEvent): string;
+/** The custom DOM event any UI affordance can dispatch to open the palette. */
+declare const COMMAND_PALETTE_OPEN_EVENT = "command-palette:open";
+/** Dispatch `command-palette:open` so a button/menu can open the palette. */
+declare function openCommandPalette(): void;
+
+/**
+ * Theme helpers for the `[data-theme]` mechanism that styles.css implements.
+ *
+ * `data-theme` must be set on <html> BEFORE first paint, or the page flashes
+ * the default theme before flipping to the user's choice. Inject
+ * `noFlashThemeScript` synchronously in <head> — for Next, in a <script
+ * dangerouslySetInnerHTML>; for a Vite app, inline in index.html.
+ *
+ * Resolution order (matches the fleet rule in
+ * planning/wiki/concepts/theme-system-dark-fallback.md):
+ *
+ *   1. saved user choice in localStorage
+ *   2. OS preference via `prefers-color-scheme`
+ *   3. dark — the fleet-wide fallback when we can't tell
+ *
+ * Prior to v0.28 the fallback was "light"; the fleet now treats dark as
+ * the audience-of-record default (most surfaces are dark; designs assume
+ * dark first).
+ */
+type Theme = "light" | "dark";
+/**
+ * A self-contained <head> snippet (no deps) that sets `data-theme` from the
+ * saved choice, falling back to the OS preference, then dark. Pass the same
+ * `appKey` you pass to `getTheme`/`setTheme`.
+ */
+declare function noFlashThemeScript(appKey: string): string;
+/** Read the active theme (saved choice → OS preference → dark). */
+declare function getTheme(appKey: string): Theme;
+/** Persist and apply a theme to <html>. */
+declare function setTheme(appKey: string, theme: Theme): void;
+
+type ToastKind = "ok" | "err" | "info";
+interface ToastItem {
+    id: number;
+    message: ReactNode;
+    kind: ToastKind;
+}
+/** Show a transient toast. Returns the id (so callers can dismiss early). */
+declare function toast(message: ReactNode, kind?: ToastKind, durationMs?: number): number;
+/** Dismiss a toast by id. */
+declare function dismissToast(id: number): void;
+/**
+ * Mount once at the app root (alongside the router/shell). Renders the toast
+ * queue bottom-center, styled from the @etamong-playground/ui tokens
+ * (import "@etamong-playground/ui/styles.css").
+ */
+declare function Toaster(): react.JSX.Element | null;
+
+interface BaseReq {
+    title?: ReactNode;
+    body?: ReactNode;
+    confirmLabel?: string;
+    cancelLabel?: string;
+}
+interface ConfirmReq extends BaseReq {
+    kind: "confirm";
+    danger?: boolean;
+    resolve: (ok: boolean) => void;
+}
+interface PromptReq extends BaseReq {
+    kind: "prompt";
+    placeholder?: string;
+    defaultValue?: string;
+    resolve: (value: string | null) => void;
+}
+/** Promise-based confirm — replaces window.confirm(). Resolves true/false. */
+declare function uiConfirm(opts: Omit<ConfirmReq, "kind" | "resolve">): Promise<boolean>;
+/** Promise-based prompt — replaces window.prompt(). Resolves the text or null. */
+declare function uiPrompt(opts: Omit<PromptReq, "kind" | "resolve">): Promise<string | null>;
+/**
+ * Mount once at the app root. Renders the pending uiConfirm/uiPrompt dialog with
+ * Escape (cancel), Enter (confirm), and backdrop-click (cancel) handling. Styled
+ * from the @etamong-playground/ui tokens (import "@etamong-playground/ui/styles.css").
+ */
+declare function DialogHost(): react.JSX.Element | null;
+
+/**
+ * Build-version + deploy-time badge. Apps bake the deployed commit SHA and the
+ * build timestamp into their frontend at build time (CI build-arg →
+ * `VITE_BUILD_SHA`/`NEXT_PUBLIC_BUILD_SHA` etc.) and render this in a
+ * backoffice/console footer so operators can see *what* is live and *when* it
+ * shipped. Styled from the @etamong-playground/ui tokens.
+ */
+interface DeployInfoProps {
+    /** Deployed commit SHA (full or short). Displayed shortened to 7 chars. */
+    version?: string;
+    /** ISO-8601 build/deploy timestamp. Rendered relative; absolute in the tooltip. */
+    builtAt?: string;
+    /** Leading label. Default "deployed". */
+    label?: string;
+    /** If set, the version renders as a link (e.g. the commit URL). */
+    href?: string;
+    /** Extra class merged with `etu-deploy-info`. */
+    className?: string;
+}
+/**
+ * Renders e.g. `deployed a1b2c3d · 2 days ago`. Returns null when neither a
+ * version nor a timestamp is available (e.g. a local dev build), so callers can
+ * mount it unconditionally.
+ */
+declare function DeployInfo({ version, builtAt, label, href, className }: DeployInfoProps): react.JSX.Element | null;
+
+/**
+ * PWA install affordance — a small dismissable mobile banner that shows the
+ * right thing per platform:
+ *
+ *  - Chrome / Android: captures `beforeinstallprompt`, shows an "Install"
+ *    button that fires the native prompt.
+ *  - iOS Safari: no programmatic install — show a short "Share → Add to Home
+ *    Screen" hint instead.
+ *  - Anywhere already installed (`display-mode: standalone`): renders nothing.
+ *
+ * The banner is mobile-only by default (hides on `min-width: 768px`); for a
+ * desktop affordance, ship a small inline button or call `useInstallPrompt`
+ * yourself.
+ *
+ * Per-app: drop `<InstallBanner />` once near the root (same boundary as
+ * `<Toaster />`). Renders nothing in unsupported environments, so it's safe to
+ * mount unconditionally.
+ */
+interface InstallBannerProps {
+    /** Banner body text on supported (Chrome/Android) platforms. */
+    label?: string;
+    /** Banner body text on iOS Safari (where no programmatic prompt is possible). */
+    iosHint?: string;
+    /** Install button label (Chrome/Android only). */
+    installLabel?: string;
+    /** Aria-label for the close button. */
+    dismissLabel?: string;
+    /** Custom icon node rendered at the start of the banner. */
+    icon?: React.ReactNode;
+    /** Cooldown between re-shows after a dismiss, in ms. Default 3 days. */
+    cooldownMs?: number;
+    /** Stop offering after this many dismisses. Default 3. */
+    maxDismiss?: number;
+    /** localStorage key for persistence. Pick a per-app value to avoid clashes. */
+    storageKey?: string;
+    /** Extra class merged with `etu-install-banner`. */
+    className?: string;
+}
+/**
+ * Lower-level hook for apps that want to render their own UI.
+ *
+ *  - `canPrompt` — Chrome/Android has fired `beforeinstallprompt`; call `promptInstall()` to show it.
+ *  - `isIOS` — render iOS guidance text.
+ *  - `isStandalone` — the app is already installed; render nothing.
+ */
+declare function useInstallPrompt(): {
+    canPrompt: boolean;
+    promptInstall: () => Promise<"accepted" | "dismissed" | "unsupported">;
+    isIOS: boolean;
+    isStandalone: boolean;
+};
+declare function InstallBanner({ label, iosHint, installLabel, dismissLabel, icon, cooldownMs, maxDismiss, storageKey, className, }: InstallBannerProps): react.JSX.Element | null;
+
+/**
+ * Polls the per-host status feed and returns the parsed banner state.
+ * Lower-level than `<StatusBanner>` — use this when you want to render your
+ * own UI (e.g. a header pill, a notifications page entry) instead of the
+ * default banner strip.
+ */
+type Severity = "outage" | "degraded" | "maintenance";
+interface StatusBannerData {
+    enabled: boolean;
+    severity: Severity | null;
+    message_ko: string;
+    message_en: string;
+    eta_iso: string | null;
+    retry_after_seconds: number | null;
+    tags: string[];
+    updated_at: string | null;
+}
+interface UseStatusBannerOptions {
+    /** Endpoint to poll. Default `/.well-known/maintenance.json` (same-origin). */
+    endpoint?: string;
+    /** Poll interval in ms. Default 60_000 (the endpoint sends `max-age=30`, so
+     *  a 60s tick guarantees the cached layer rotates between polls). */
+    pollMs?: number;
+}
+/**
+ * Returns the latest parsed status, or `null` while loading / on error.
+ * Pauses polling while the document is hidden (visibilitychange) and resumes
+ * with an immediate fetch when it returns to the foreground.
+ */
+declare function useStatusBanner(opts?: UseStatusBannerOptions): StatusBannerData | null;
+
+interface StatusBannerProps {
+    /** Override the polling endpoint. Default `/.well-known/maintenance.json`
+     *  (same-origin). Use a cross-origin URL only for an embedded view of
+     *  another fleet host's status; the worker endpoint sends `cache-control: max-age=30`. */
+    endpoint?: string;
+    /** Override the JSON poll interval (ms). Default 60_000 (the endpoint caches
+     *  for 30s, so two polls/minute is the floor that's useful). */
+    pollMs?: number;
+    /** Force-pick a language; default reads `document.documentElement.lang`. */
+    lang?: "ko" | "en";
+    /** Override class on the outer banner. Merged with `etu-status-banner`. */
+    className?: string;
+    /** Render the dismiss "x" button. Dismissal lasts for the session only;
+     *  a fresh banner of a different severity reappears. Default true. */
+    dismissible?: boolean;
+}
+declare function StatusBanner({ endpoint, pollMs, lang, className, dismissible, }: StatusBannerProps): react.JSX.Element | null;
+
+interface ErrorPageProps {
+    /** Headline (e.g. "문제가 발생했어요"). */
+    title?: string;
+    /** A user-friendly sentence — what happened + what to do. */
+    description?: string;
+    /**
+     * The 8-hex `ref` code from the backend / log (the `httperr` reference). Shown
+     * to the user so they can quote it in a report. Omit when there's no ref.
+     */
+    refCode?: string;
+    /** Optional retry handler; renders a "다시 시도" button when set. */
+    onRetry?: () => void;
+    /** Optional home handler; renders a "홈으로" button when set. */
+    onHome?: () => void;
+    /**
+     * Override the labels on the buttons / ref line. Defaults are Korean.
+     */
+    labels?: Partial<{
+        retry: string;
+        home: string;
+        refLabel: string;
+    }>;
+    /** Custom icon node (defaults to a circle-alert glyph). */
+    icon?: ReactNode;
+    /** Extra class merged with `etu-error-page`. */
+    className?: string;
+}
+declare function ErrorPage({ title, description, refCode, onRetry, onHome, labels, icon, className, }: ErrorPageProps): react.JSX.Element;
+
+/**
+ * Router-agnostic in-page state hooks for the SPA navigation/state contract
+ * (planning concepts/spa-navigation-state).
+ *
+ * Two flavors:
+ *
+ * - `useRouteState(key, initial, opts?)` — backed by the URL query string.
+ *   Use for state the user benefits from sharing or restoring after refresh:
+ *   which tab is open, filter, sort, search term, expanded row id.
+ *
+ * - `useSessionState(key, initial, opts?)` — backed by `sessionStorage`,
+ *   keyed by route. Use for truly local state you don't want in the URL:
+ *   scroll position, cmdk query, unsubmitted form draft.
+ *
+ * Both hooks:
+ *   - Hydrate from their backing store on mount.
+ *   - Listen to `popstate` / `hashchange` so back/forward and direct URL
+ *     edits stay in sync.
+ *   - Are SSR-safe: on the server they just return `initial` until mount.
+ *   - Don't assume a router; they read/write `window.history` directly.
+ *
+ * URL serialization defaults to `JSON.stringify` so booleans / numbers /
+ * arrays round-trip. Pass `{ serialize, deserialize }` for a cleaner
+ * representation when you want pretty URLs (e.g. tab names as plain
+ * strings instead of `"overview"` with the quotes).
+ */
+type Updater<T> = T | ((prev: T) => T);
+interface UseRouteStateOptions<T> {
+    /** How to encode the value into the URL. Default: `JSON.stringify`. */
+    serialize?: (value: T) => string;
+    /** How to decode the URL value back. Default: `JSON.parse`. */
+    deserialize?: (raw: string) => T;
+    /**
+     * Replace the entry instead of pushing a new one. Useful for noisy state
+     * (search-as-you-type filter) that shouldn't fill the back history.
+     * Default: `true` (replace).
+     */
+    replace?: boolean;
+}
+interface UseSessionStateOptions<T> {
+    serialize?: (value: T) => string;
+    deserialize?: (raw: string) => T;
+    /**
+     * Override the per-route scope. Default: `window.location.pathname +
+     * window.location.hash` so each in-app view gets its own slot. Pass a
+     * static string when you want the state to span routes.
+     */
+    scope?: string;
+}
+declare function useRouteState<T>(key: string, initial: T, opts?: UseRouteStateOptions<T>): [T, (next: Updater<T>) => void];
+declare function useSessionState<T>(key: string, initial: T, opts?: UseSessionStateOptions<T>): [T, (next: Updater<T>) => void];
+
+/**
+ * In-app history stack for the SPA navigation contract Rule 2
+ * (planning concepts/spa-navigation-state): the browser back button — and
+ * any in-UI "back" button — should stay inside the app instead of bouncing
+ * the user out to whatever site they came from.
+ *
+ * How it works:
+ *   - Every in-app navigation goes through `push(url)` / `replace(url)`,
+ *     which writes a marker into `history.state` (`{ etuInApp: true,
+ *     etuDepth: N }`).
+ *   - `canGoBack` is true when the current entry has `etuDepth > 0` — i.e.
+ *     there's at least one in-app entry behind us.
+ *   - `goBack()` calls `history.back()` when `canGoBack`; otherwise it
+ *     runs the `fallback` handler (e.g. router.push("/more")) so the UI
+ *     button still does something sensible on a cold entry.
+ *
+ * Composes cleanly with `useRouteState`: that hook uses `replaceState`,
+ * so URL-synced in-page state (tab, filter) doesn't grow the back stack
+ * and doesn't confuse the depth counter.
+ *
+ * The hook is router-agnostic — it reads and writes `window.history`
+ * directly. Pair it with whatever you use for routing.
+ *
+ * Most consumers should just render `<BackButton fallback="/more" />` —
+ * BackButton mounts this hook internally so apps don't have to plumb the
+ * canGoBack/goBack split themselves. The standalone hook is exposed for
+ * apps that need the values somewhere besides the button (e.g. a swipe
+ * gesture, a keyboard shortcut, a custom layout).
+ */
+interface UseInAppBackResult {
+    /** True when there's at least one in-app entry behind the current one. */
+    canGoBack: boolean;
+    /**
+     * Go to the previous in-app view. When `canGoBack` is false, runs the
+     * `fallback` passed to the hook (or `onExit` for legacy callers; no-op
+     * if neither is set).
+     */
+    goBack: () => void;
+    /** Push a new in-app entry (URL + depth increment). */
+    push: (url: string) => void;
+    /** Replace the current entry without growing the stack. */
+    replace: (url: string) => void;
+}
+/**
+ * Where to go when the user clicks "back" but there's no in-app history
+ * behind them (cold entry from an external link, or after the browser
+ * dropped the state on reload).
+ *
+ * - **string** — treated as a URL. Calls `history.pushState(null, "", url)`
+ *   and dispatches a synthetic `popstate` so hash/path routers re-render.
+ *   Use for hash-routed apps and other vanilla setups.
+ * - **function** — called as-is. Use for Next.js / React Router etc:
+ *   `fallback={() => router.push("/more")}`.
+ */
+type InAppBackFallback = string | (() => void);
+interface UseInAppBackOptions {
+    /**
+     * Where to go when `canGoBack` is false. Accepts a URL string or a
+     * callback (most consumers want the callback when they already have a
+     * router instance).
+     */
+    fallback?: InAppBackFallback;
+    /**
+     * @deprecated since v0.27.0 — use `fallback`. Kept for back-compat with
+     * v0.8.0–v0.26.0 callers; behaves identically when `fallback` is unset.
+     */
+    onExit?: () => void;
+}
+/**
+ * Runs a fallback. String fallbacks pushState + fire popstate so the
+ * caller's router picks up the URL change without a full reload.
+ */
+declare function runInAppBackFallback(fallback: InAppBackFallback): void;
+declare function useInAppBack(opts?: UseInAppBackOptions): UseInAppBackResult;
+
+interface BackButtonProps {
+    /**
+     * From `useInAppBack().canGoBack`. Omit if you're using the canonical
+     * one-liner — BackButton mounts the hook internally.
+     */
+    canGoBack?: boolean;
+    /**
+     * From `useInAppBack().goBack`. Omit if you're using the canonical
+     * one-liner — BackButton mounts the hook internally.
+     */
+    goBack?: () => void;
+    /**
+     * Direct click handler — use when you don't want to thread the hook
+     * result through. If passed, takes precedence over `goBack`.
+     */
+    onClick?: () => void;
+    /**
+     * Where to go when there's no in-app history behind us (cold entry).
+     * String → URL (pushState + popstate). Function → run as-is (typical
+     * for Next.js: `() => router.push("/more")`). Used when no explicit
+     * `goBack`/`onClick` is provided.
+     */
+    fallback?: InAppBackFallback;
+    /** Default: "뒤로". */
+    label?: string;
+    /** Replace the default chevron-left glyph. */
+    icon?: ReactNode;
+    /** Extra class merged onto `etu-back-button`. */
+    className?: string;
+    /**
+     * Render the button even when there's nowhere to go. Useful when the
+     * caller wants a stable layout — the click is a no-op unless an
+     * `onClick` / `goBack` / `fallback` is also wired.
+     */
+    alwaysShow?: boolean;
+}
+declare function BackButton({ canGoBack, goBack, onClick, fallback, label, icon, className, alwaysShow, }: BackButtonProps): react.JSX.Element | null;
+
+/**
+ * Tiny `fetch` wrapper with the etamong-lab house conventions baked in:
+ *
+ *   - **httperr `ref` parsing** — non-2xx JSON bodies shaped like
+ *     `{ error: string, ref: string }` (planning concepts/user-facing-
+ *     error-messages, shared/libs/httperr) become an `HttpError` whose
+ *     `ref` drops straight into `<ErrorPage refCode={err.ref}>`.
+ *   - **OIDC sign-in on 401** — 401 responses trigger `onAuthError`,
+ *     which by default redirects to `oauth2-proxy`'s sign-in flow with
+ *     the current URL as `rd`.
+ *   - **JSON in / JSON out by default** — request bodies that are plain
+ *     objects get `Content-Type: application/json` + serialized; non-empty
+ *     2xx responses with a JSON content type are parsed.
+ *
+ * Designed to be the one fetch wrapper an etamong-lab app needs.
+ * Compose with route-state / error-page / toast on the consumer side.
+ */
+interface CreateFetchOptions {
+    /**
+     * Base URL prepended to relative paths. `"/api"` (default: empty —
+     * paths are used as-is).
+     */
+    baseUrl?: string;
+    /**
+     * Called on a 401 response. Default: redirect the browser to
+     * `/oauth2/start?rd=<current url>`. Pass a no-op when the app handles
+     * auth elsewhere (e.g. inside its router).
+     */
+    onAuthError?: () => void;
+    /**
+     * Called for every non-2xx response after the `HttpError` is built but
+     * before it's thrown. Use for telemetry / global toast. Doesn't affect
+     * the throw — the caller still gets the error.
+     */
+    onError?: (err: HttpError) => void;
+    /**
+     * Extra headers to add to every request. Static object or a function
+     * (evaluated per request). Common use: an `Authorization` header for
+     * token-based callers (not browser sessions).
+     */
+    headers?: HeadersInit | (() => HeadersInit);
+    /**
+     * Override the global `fetch` (for tests / SSR). Default: `globalThis.fetch`.
+     */
+    fetchImpl?: typeof fetch;
+}
+interface HttpErrorBody {
+    /** Server-supplied user-facing message. */
+    error?: string;
+    /** 8-hex correlation id from the server log (httperr). */
+    ref?: string;
+    /** Any extra fields the server included. */
+    [extra: string]: unknown;
+}
+/**
+ * Error thrown for every non-2xx response. The `ref` field is the join
+ * key into the server-side error log and is what `<ErrorPage>` shows.
+ */
+declare class HttpError extends Error {
+    status: number;
+    ref?: string;
+    body?: HttpErrorBody | string;
+    url: string;
+    constructor(status: number, url: string, body: HttpErrorBody | string | undefined);
+}
+interface RequestOptions {
+    /** Query-string params; values are stringified. */
+    query?: Record<string, string | number | boolean | null | undefined>;
+    /** Per-call header override (merged on top of the factory headers). */
+    headers?: HeadersInit;
+    /** Per-call body. Objects → JSON. `FormData` / `Blob` / strings pass through. */
+    body?: unknown;
+    /** Abort signal. */
+    signal?: AbortSignal;
+    /**
+     * Skip JSON parsing and return the raw `Response` instead. Useful for
+     * downloads / streaming.
+     */
+    raw?: boolean;
+}
+interface FetchClient {
+    request<T = unknown>(method: string, path: string, opts?: RequestOptions): Promise<T>;
+    get<T = unknown>(path: string, opts?: RequestOptions): Promise<T>;
+    post<T = unknown>(path: string, body?: unknown, opts?: RequestOptions): Promise<T>;
+    put<T = unknown>(path: string, body?: unknown, opts?: RequestOptions): Promise<T>;
+    patch<T = unknown>(path: string, body?: unknown, opts?: RequestOptions): Promise<T>;
+    delete<T = unknown>(path: string, opts?: RequestOptions): Promise<T>;
+}
+declare function createFetch(opts?: CreateFetchOptions): FetchClient;
+
+/**
+ * `useMe()` + OIDC sign-in/out URL helpers — the small auth-status surface
+ * every etamong-lab app reimplements.
+ *
+ * Pairs with `oauth2-proxy` (the fleet's standard auth proxy): the sign-in
+ * URL is `/oauth2/start?rd=<return-url>`, sign-out is `/oauth2/sign_out`.
+ *
+ * The `/me` endpoint and the exact shape are app-specific, so the hook is
+ * generic over the body type. Pass a `fetcher` (typically from
+ * `createFetch`) and a type — the hook handles the loading/error/refresh
+ * state machine + listens for an `etu:me-refresh` event so other
+ * components can ask for a re-fetch.
+ */
+interface BaseMe {
+    /** Always present — the authenticated identity. */
+    email: string;
+    /** OIDC `preferred_username` if the IdP supplies it. */
+    preferred_username?: string;
+    /** OIDC `name` claim — full display name. */
+    name?: string;
+    /** OIDC `picture` claim — URL of the user's profile picture. */
+    picture?: string;
+    /** Server-side admin flag (use this, not allowlist-by-email on the client). */
+    is_admin?: boolean;
+    /** Role claims from the IdP. */
+    roles?: string[];
+}
+interface UseMeOptions<T extends BaseMe> {
+    /**
+     * URL to fetch. Default: `/api/me`. Ignored when `fetcher` is set.
+     */
+    endpoint?: string;
+    /**
+     * Custom fetcher — usually the `api.get<T>("/me")` from your
+     * `createFetch` client. Use this when the app's API is mounted under a
+     * non-default base path or needs custom headers.
+     */
+    fetcher?: () => Promise<T>;
+    /**
+     * When `true` (default), 401 from the default fetcher counts as
+     * "anonymous" rather than an error — `me` becomes `null`, `error`
+     * stays `null`. Useful when the app has public surfaces. Ignored when
+     * a custom `fetcher` is set.
+     */
+    treat401AsAnonymous?: boolean;
+}
+interface UseMeResult<T extends BaseMe> {
+    me: T | null;
+    loading: boolean;
+    error: Error | null;
+    /** Re-fetch /me. Also fires `etu:me-refresh` so other readers re-fetch too. */
+    refresh: () => void;
+}
+declare function useMe<T extends BaseMe = BaseMe>(opts?: UseMeOptions<T>): UseMeResult<T>;
+/**
+ * Build the oauth2-proxy sign-in URL. Pass `rd` to override the
+ * post-sign-in redirect target (default: the current URL).
+ */
+declare function signInUrl(rd?: string): string;
+/**
+ * Build the oauth2-proxy sign-out URL. Pass `rd` for the post-sign-out
+ * redirect (default: `/`).
+ */
+declare function signOutUrl(rd?: string): string;
+/** Navigate to the sign-in URL. */
+declare function signIn(rd?: string): void;
+/** Navigate to the sign-out URL. */
+declare function signOut(rd?: string): void;
+
+interface EmptyStateProps {
+    /** Headline. */
+    title: string;
+    /** Optional one-line description. */
+    description?: ReactNode;
+    /** Optional CTA / footnote node (typically a button or a hint). */
+    action?: ReactNode;
+    /** Replace the default empty-box glyph. Pass `null` to omit. */
+    icon?: ReactNode;
+    /** Smaller padding + smaller type — for inline / sidebar usage. */
+    compact?: boolean;
+    /** Extra class merged with `etu-empty-state`. */
+    className?: string;
+}
+declare function EmptyState({ title, description, action, icon, compact, className, }: EmptyStateProps): react.JSX.Element;
+
+interface UseClipboardOptions {
+    /** Default: 1500ms. How long `copied` stays true after a successful copy. */
+    resetMs?: number;
+    /** Toast text on success. Default: "복사됨". Pass `null` to suppress. */
+    toastOnSuccess?: string | null;
+    /** Toast text on failure. Default: "복사 실패". Pass `null` to suppress. */
+    toastOnError?: string | null;
+}
+interface UseClipboardResult {
+    copied: boolean;
+    copy: (value: string) => Promise<boolean>;
+}
+declare function useClipboard(opts?: UseClipboardOptions): UseClipboardResult;
+interface CopyButtonProps extends UseClipboardOptions {
+    /** The string to copy on click. */
+    value: string;
+    /** Button label. Default: "복사" (switches to "복사됨" briefly after success). */
+    label?: string;
+    /** Label shown right after a successful copy. Default: "복사됨". */
+    successLabel?: string;
+    /** Replace the default copy glyph. Pass `null` to omit. */
+    icon?: ReactNode;
+    /** Extra class merged with `etu-copy-button`. */
+    className?: string;
+    /**
+     * Render only the icon (no label). Good for inline placement next to a
+     * value display.
+     */
+    iconOnly?: boolean;
+    /** ARIA label when `iconOnly`. Default: "복사". */
+    ariaLabel?: string;
+}
+declare function CopyButton({ value, label, successLabel, icon, className, iconOnly, ariaLabel, resetMs, toastOnSuccess, toastOnError, }: CopyButtonProps): react.JSX.Element;
+
+interface OpenInBrowserButtonProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href" | "target" | "rel"> {
+    /** The URL to open. */
+    href: string;
+    /** Button label. Default: "브라우저에서 열기". */
+    label?: string;
+    /** Replace the default external-link glyph. Pass `null` to omit. */
+    icon?: ReactNode;
+    /**
+     * Render only the icon (no label). Good for inline placement next to a URL
+     * display or inside a toolbar.
+     */
+    iconOnly?: boolean;
+    /** ARIA label when `iconOnly`. Default: same as `label`. */
+    ariaLabel?: string;
+    /**
+     * Visual variant. `ghost` (default) = transparent button with border,
+     * matches `<CopyButton>`. `primary` = filled accent.
+     */
+    variant?: "ghost" | "primary";
+    /** Extra class merged with `etu-open-in-browser-button`. */
+    className?: string;
+}
+declare function OpenInBrowserButton({ href, label, icon, iconOnly, ariaLabel, variant, className, ...rest }: OpenInBrowserButtonProps): react.JSX.Element;
+
+/**
+ * Service-worker helpers for the etamong-lab PWA recipe (planning
+ * concepts/pwa-service-worker). Two pieces:
+ *
+ *  - `registerServiceWorker(url, opts)` — client-side registration with
+ *    the update flow baked in: aggressive `registration.update()` checks
+ *    (on load + visibilitychange + a slow interval), a "새 버전" toast on
+ *    a waiting SW, and an auto-reload on `controllerchange`.
+ *
+ *  - `networkFirstSwSource({ version, navigateAllowlist })` — returns the
+ *    canonical hand-rolled SW source as a string. Apps write it to
+ *    `public/sw.js` (or generate it at build time). The recipe:
+ *      • Never intercepts non-GET or `/api/*` (fresh auth + live state).
+ *      • Navigation requests: **network-first** with a short timeout, cache
+ *        as the offline fallback. So online users always see the latest
+ *        deploy; offline still works.
+ *      • Static assets: **network-first** with a short timeout too, cache
+ *        as the offline fallback. Same bias toward "fresh wins".
+ *      • Caches are versioned by `version`; on `activate` older versions
+ *        are deleted, then `clients.claim()`.
+ *      • The SW calls `skipWaiting()` immediately on `install` so updates
+ *        propagate on the next nav.
+ *
+ *    This is the "online-first" preset. Apps with a tighter cache budget
+ *    or a hand-rolled scoped strategy (minccino's specific endpoints, the
+ *    shortener single-segment-route guard) should stick with their
+ *    bespoke SW.
+ */
+interface RegisterServiceWorkerOptions {
+    /**
+     * Show a "새 버전이 있어요" toast when a new SW finishes installing and
+     * is waiting. Clicking it activates the new SW and reloads. Default: true.
+     */
+    notifyOnUpdate?: boolean;
+    /**
+     * Auto-activate the waiting SW + reload as soon as it's detected, with
+     * no user prompt. Use when you don't care about transient state loss.
+     * Default: false (the toast is the canonical path).
+     */
+    autoReloadOnUpdate?: boolean;
+    /**
+     * Override the toast text. Default: "새 버전이 준비됐어요. 새로고침할까요?".
+     */
+    updateToastText?: string;
+    /**
+     * Interval (ms) between background `registration.update()` calls — so
+     * long-lived installed tabs catch new deploys without a reload. Default:
+     * 2 minutes. Pass `0` to disable the interval (still updates on load
+     * + visibilitychange).
+     */
+    updateIntervalMs?: number;
+    /**
+     * Service-worker `register()` options (typically `{ scope }`).
+     */
+    registerOptions?: RegistrationOptions;
+    /**
+     * Called when the new SW activates and the page is about to reload.
+     * Last chance to persist transient state.
+     */
+    onActivate?: () => void;
+    /**
+     * The current build identifier — typically the deploy SHA from
+     * `DeployInfo`. When supplied, a dev-mode assertion fires a
+     * `console.warn` if this changes across reloads but the SW file body
+     * is byte-for-byte identical. That signal means the SW source isn't
+     * stamped per build, so browsers never observe a new SW and never
+     * roll over to the new deploy — the canonical iOS PWA staleness
+     * trigger (see planning concepts/pwa-cache-and-ios-shell and the
+     * `viewport-fit-assertions` companion pattern).
+     *
+     * Dev-only — production short-circuits via `NODE_ENV === "production"`.
+     */
+    currentBuild?: string;
+}
+interface ServiceWorkerHandle {
+    /** The underlying registration once it resolves. */
+    readonly registration: ServiceWorkerRegistration | null;
+    /** True while a waiting SW exists (update available). */
+    readonly hasUpdate: boolean;
+    /** Force the waiting SW to take over + reload. No-op if no waiting SW. */
+    applyUpdate: () => void;
+    /** Manually trigger `registration.update()`. */
+    checkForUpdate: () => Promise<void>;
+    /** Unregister this SW. Useful in tests / when toggling off. */
+    unregister: () => Promise<boolean>;
+}
+/**
+ * Register a service worker with the etamong-lab update-flow conventions.
+ * Returns a handle for programmatic control. Safe to call from `useEffect`
+ * (no React dependency — works from any client-side bootstrap).
+ */
+declare function registerServiceWorker(url: string, opts?: RegisterServiceWorkerOptions): ServiceWorkerHandle;
+interface NetworkFirstSwOptions {
+    /**
+     * Cache version suffix. Use a build SHA so caches roll over on every
+     * deploy. Required.
+     */
+    version: string;
+    /**
+     * Network timeout (ms) before the SW falls back to the cached
+     * navigation/asset. Default: 3000.
+     */
+    networkTimeoutMs?: number;
+    /**
+     * Extra URL prefixes the SW should leave alone (in addition to the
+     * always-skipped `/api/`). Use for OIDC callbacks, webhook routes,
+     * single-segment apiserver routes. Default: `[]`.
+     *
+     * Each entry is a prefix match against `url.pathname`.
+     */
+    passThroughPrefixes?: string[];
+}
+/**
+ * Returns the canonical "online-first" SW source as a string. Write it to
+ * `public/sw.js` at build time (most apps already have a build step that
+ * inlines a `SW_VERSION` constant):
+ *
+ *   import { networkFirstSwSource } from "@etamong-playground/ui";
+ *   await fs.writeFile(
+ *     "public/sw.js",
+ *     networkFirstSwSource({ version: process.env.BUILD_SHA }),
+ *   );
+ *
+ * Or serve it dynamically from the app's own backend at `/sw.js`.
+ *
+ * The recipe:
+ *   - Never intercepts non-GET or anything under `/api/` (or the
+ *     `passThroughPrefixes`) — auth & live state always hit the network.
+ *   - Navigation requests: network-first with `networkTimeoutMs`, cache
+ *     fallback for offline. So a new deploy lands the moment the next
+ *     navigation succeeds.
+ *   - Static assets: network-first with the same timeout, cache fallback.
+ *   - On `activate`, all caches not matching `version` are deleted.
+ *   - `skipWaiting()` on install + `clients.claim()` on activate so the
+ *     new SW takes over the next time the page navigates.
+ */
+declare function networkFirstSwSource(opts: NetworkFirstSwOptions): string;
+
+interface AdminCheckInput<T extends BaseMe = BaseMe> {
+    /** The current identity (from `useMe`). `null` = anonymous. */
+    me: T | null | undefined;
+    /** App-managed allowlist (case-insensitive on the local part / domain). */
+    emails?: string[];
+    /** Pass if `me.roles` intersects this set. */
+    roles?: string[];
+    /** Last-resort custom check (e.g. flags like `can_create_apps`). */
+    predicate?: (me: T) => boolean;
+}
+/**
+ * Returns `true` when *any* of the configured signals says the user is
+ * allowed in. With nothing configured, only `me.is_admin` counts.
+ */
+declare function isAdminLike<T extends BaseMe>(input: AdminCheckInput<T>): boolean;
+interface AdminGateProps<T extends BaseMe = BaseMe> extends AdminCheckInput<T> {
+    /** Rendered when the user is allowed in. */
+    children: ReactNode;
+    /**
+     * Rendered when the user is NOT allowed in. Default: `null` (nothing).
+     * Pass a friendly "권한이 없어요" surface or a redirect-trigger here.
+     */
+    fallback?: ReactNode;
+}
+declare function AdminGate<T extends BaseMe = BaseMe>(props: AdminGateProps<T>): react.JSX.Element;
+interface AdminBadgeProps {
+    /** Default: "관리자 전용". */
+    label?: string;
+    /** Extra class merged with `etu-admin-badge`. */
+    className?: string;
+}
+/**
+ * Small inline badge that marks a page / section as admin-only. Pair with
+ * `AdminGate` so users without access never see it in the first place,
+ * but admins always know the surface they're on.
+ */
+declare function AdminBadge({ label, className }: AdminBadgeProps): react.JSX.Element;
+interface BackofficeLayoutProps {
+    /** Page title. */
+    title: ReactNode;
+    /** Optional subtitle line below the title. */
+    description?: ReactNode;
+    /** Right-side actions (buttons, search, filter). */
+    actions?: ReactNode;
+    /** Override the "관리자 전용" badge — pass `null` to hide it entirely. */
+    badge?: ReactNode | null;
+    /** Page body. */
+    children: ReactNode;
+    /** Extra class merged with `etu-backoffice`. */
+    className?: string;
+}
+/**
+ * Standard page-head layout for a backoffice route: title + AdminBadge +
+ * optional actions, then the page body.
+ */
+declare function BackofficeLayout({ title, description, actions, badge, children, className, }: BackofficeLayoutProps): react.JSX.Element;
+
+interface AppInfoLink {
+    label: string;
+    href: string;
+    /** Default: opens in a new tab when `href` is absolute. */
+    external?: boolean;
+}
+interface AppInfoSectionProps {
+    /** App display name (e.g. "schedule-manager", "🎪 Festplan"). */
+    name?: ReactNode;
+    /** Optional one-liner under the name. */
+    description?: ReactNode;
+    /** Optional logo / icon node to the left of the name. */
+    icon?: ReactNode;
+    /**
+     * Semver / release version (`package.json` `version` — e.g. "1.4.2").
+     * Distinct from the commit SHA, which goes through `version`.
+     */
+    appVersion?: string;
+    /** Deployed commit SHA — forwarded to `<DeployInfo>`. */
+    version?: string;
+    /** Build timestamp (ISO 8601) — forwarded to `<DeployInfo>`. */
+    builtAt?: string;
+    /**
+     * Extra link rows ("도움말", "이용약관", "개인정보처리방침"). External
+     * links open in a new tab.
+     */
+    links?: AppInfoLink[];
+    /**
+     * Free-form rows under the standard fields. Use for app-specific
+     * meta (plan name, quota, owner email, …).
+     */
+    children?: ReactNode;
+    /** Section heading. Default: "앱 정보". Pass `null` to omit. */
+    heading?: ReactNode | null;
+    /** Extra class merged with `etu-app-info`. */
+    className?: string;
+}
+declare function AppInfoSection({ name, description, icon, appVersion, version, builtAt, links, children, heading, className, }: AppInfoSectionProps): react.JSX.Element;
+
+/**
+ * Time-format helpers — the small piece every etamong-lab app reimplements.
+ *
+ * Two surfaces:
+ *
+ *  - `formatRelTime(when, now?)` — "3 minutes ago" / "3분 전" via the
+ *    browser's `Intl.RelativeTimeFormat`. Locale comes from the
+ *    document by default; pass `locale` to force.
+ *  - `formatAbsTime(when, opts?)` — absolute formatting via
+ *    `Intl.DateTimeFormat`. Defaults to a KST (`Asia/Seoul`) Korean
+ *    rendering — the fleet's de-facto wall clock.
+ *
+ *  - `<RelTime when />` — small React component that auto-refreshes the
+ *    relative label on a timer (every 30 s under a minute, every minute
+ *    under an hour, then every 10 minutes). Title attribute always shows
+ *    the absolute time so hovering reveals the exact timestamp.
+ *
+ * `when` accepts a `Date`, an ISO string, or an epoch milliseconds
+ * number. Invalid inputs render to empty strings rather than throwing —
+ * makes the helpers safe to use directly on partial data.
+ */
+type TimeLike = Date | string | number;
+interface FormatRelTimeOptions {
+    /** Locale tag (e.g. "ko", "en"). Default: browser default. */
+    locale?: string | string[];
+    /**
+     * `Intl.RelativeTimeFormat` numeric mode. Default: `"auto"` (gives
+     * "yesterday" / "어제" instead of "1 day ago").
+     */
+    numeric?: "auto" | "always";
+    /** Reference time for "now". Default: `Date.now()`. */
+    now?: TimeLike;
+}
+/**
+ * Returns e.g. `"3분 전"` / `"in 2 hours"`. Empty string for invalid
+ * inputs.
+ */
+declare function formatRelTime(when: TimeLike, opts?: FormatRelTimeOptions): string;
+interface FormatAbsTimeOptions {
+    /** Locale tag. Default: `"ko-KR"`. */
+    locale?: string | string[];
+    /** Time zone. Default: `"Asia/Seoul"` (KST — the fleet's wall clock). */
+    timeZone?: string;
+    /** `Intl.DateTimeFormat` style preset. Default: `"datetime"`. */
+    style?: "date" | "time" | "datetime" | "datetime-seconds";
+    /** Custom `Intl.DateTimeFormat` options — overrides `style`. */
+    formatOptions?: Intl.DateTimeFormatOptions;
+    /** Wrap the result so it's tagged with the timezone (e.g. `… KST`). */
+    withZoneSuffix?: boolean;
+}
+/**
+ * Returns e.g. `"2026. 06. 13. 12:34"` in KST. Empty string for invalid
+ * inputs.
+ */
+declare function formatAbsTime(when: TimeLike, opts?: FormatAbsTimeOptions): string;
+interface RelTimeProps {
+    /** The timestamp. */
+    when: TimeLike;
+    /** Forwarded to `formatRelTime`. */
+    locale?: string | string[];
+    /** Forwarded to `formatRelTime`. */
+    numeric?: "auto" | "always";
+    /**
+     * Absolute-time options for the `title` attribute. Defaults to KST
+     * datetime with the zone suffix.
+     */
+    absoluteOptions?: FormatAbsTimeOptions;
+    /** Render as a different tag. Default: `<time>`. */
+    as?: "time" | "span";
+    /** Extra class. */
+    className?: string;
+}
+/**
+ * Auto-refreshing relative-time label. Renders as a `<time>` element
+ * with `dateTime` + a `title` showing the absolute time.
+ */
+declare function RelTime({ when, locale, numeric, absoluteOptions, as, className, }: RelTimeProps): react.JSX.Element | null;
+
+interface AvatarProps {
+    /** Picture URL — typically `me.picture`. */
+    src?: string;
+    /** Initial / fallback when no picture is available — typically `me.preferred_username || me.email`. */
+    fallback?: string;
+    /** px size of the rendered circle. Default: 32. */
+    size?: number;
+    /** Extra class merged with `etu-avatar`. */
+    className?: string;
+    /** ARIA label — defaults to "프로필". */
+    alt?: string;
+}
+/**
+ * Round avatar — renders the picture if `src` is given, otherwise an
+ * initial letter on a token-colored circle. Use stand-alone or inside
+ * `<UserMenu>`.
+ */
+declare function Avatar({ src, fallback, size, className, alt }: AvatarProps): react.JSX.Element;
+interface UserMenuProps<T extends BaseMe = BaseMe> {
+    /** Current identity. `null` shows the signed-out affordance. */
+    me: T | null | undefined;
+    /** Avatar size. Default: 32. */
+    avatarSize?: number;
+    /**
+     * URL of the "내 정보" page. Default: `/me`. Pass `null` to hide the row.
+     */
+    myInfoHref?: string | null;
+    /** Override the "내 정보" label. */
+    myInfoLabel?: string;
+    /**
+     * Logout handler. Default: `signOut()` (navigates to
+     * `/oauth2/sign_out?rd=/`). Pass a custom handler for apps that have
+     * their own logout POST (e.g. minccino's `/api/auth/logout`).
+     */
+    onSignOut?: () => void;
+    /** Override the "로그아웃" label. */
+    signOutLabel?: string;
+    /**
+     * Rendered in place of the avatar when `me` is `null`. Default: a
+     * "로그인" link pointing at `signInUrl()`.
+     */
+    signedOutAction?: ReactNode;
+    /**
+     * Extra rows above 내 정보 / 로그아웃. Use for app-specific quick links
+     * (e.g. "내 사이트", "결제"). Pass an array of `{ label, href? | onClick? }`.
+     */
+    extraItems?: UserMenuItem[];
+    /** Extra class merged with `etu-user-menu`. */
+    className?: string;
+    /**
+     * Render an admin badge inside the dropdown when `me.is_admin` is true.
+     * Default: true.
+     */
+    showAdminBadge?: boolean;
+    /**
+     * Preferred placement of the dropdown relative to the trigger.
+     * Default: `"bottom-right"`. Use `"top-right"` when the trigger sits at the
+     * bottom of a sidebar foot (pages / festplan layouts) so the menu opens
+     * *upward* instead of pointing at the viewport edge.
+     *
+     * The horizontal half controls the dropdown's right/left alignment; the
+     * vertical half controls open-up vs open-down. The component auto-flips
+     * either axis on open when the requested side doesn't fit — so a layout
+     * that becomes a horizontal topbar on mobile won't strand the menu above
+     * the viewport.
+     */
+    placement?: "bottom-right" | "bottom-left" | "top-right" | "top-left";
+}
+interface UserMenuItem {
+    label: ReactNode;
+    href?: string;
+    onClick?: () => void;
+    /** Open `href` in a new tab. Default: false. */
+    external?: boolean;
+}
+declare function UserMenu<T extends BaseMe = BaseMe>({ me, avatarSize, myInfoHref, myInfoLabel, onSignOut, signOutLabel, signedOutAction, extraItems, className, showAdminBadge, placement, }: UserMenuProps<T>): react.JSX.Element;
+
+interface MobileTabBarItem {
+    /** Stable key used for React reconciliation. */
+    id: string;
+    /** Short label shown under the icon. Keep ~5 chars to fit 5 tabs on a 360px viewport. */
+    label: ReactNode;
+    /** Icon node — typically a lucide-react `<Home size={24} />` or an inline SVG. */
+    icon: ReactNode;
+    /** Whether this tab is the current one. The caller computes this from its route. */
+    active?: boolean;
+    /** Click handler. Use this for SPA-style in-app navigation. */
+    onClick?: () => void;
+    /** Link target. Renders an `<a>` instead of a `<button>`. */
+    href?: string;
+}
+interface MobileTabBarProps {
+    items: MobileTabBarItem[];
+    /** ARIA label for the nav landmark. Default: "주요 메뉴". */
+    ariaLabel?: string;
+    /** Extra class merged with `etu-mobile-tab-bar`. */
+    className?: string;
+}
+declare function MobileTabBar({ items, ariaLabel, className }: MobileTabBarProps): react.JSX.Element;
+
+interface NotificationBellItem {
+    id: string;
+    /** Rendered as a single row in the panel. */
+    content: ReactNode;
+}
+interface NotificationBellProps {
+    items: NotificationBellItem[];
+    /**
+     * Override the badge count. Defaults to `items.length`. Pass when the
+     * server-side pending count is higher than what's currently rendered
+     * (paginated list, partial fetch).
+     */
+    count?: number;
+    /** Called when the panel opens — use to refresh `items`. */
+    onOpen?: () => void;
+    /** Aria label for the trigger button. Default: `"알림"`. */
+    ariaLabel?: string;
+    /** Title shown at the top of the panel. Default: `"알림"`. */
+    title?: ReactNode;
+    /** Empty-state body when `items` is empty. Default: `"새 알림이 없습니다."`. */
+    emptyMessage?: ReactNode;
+    /** Optional footer — typically a "View all" link or "Mark all read". */
+    footer?: ReactNode;
+    /** Custom trigger icon — defaults to a bell SVG. */
+    icon?: ReactNode;
+    /** Extra class merged with `etu-notif-bell`. */
+    className?: string;
+    /**
+     * Preferred placement of the desktop dropdown. Default: `"bottom-right"`.
+     * Auto-flips on open when the requested side doesn't fit, same contract
+     * as `<UserMenu>`. Ignored on mobile (always bottom sheet).
+     */
+    placement?: "bottom-right" | "bottom-left" | "top-right" | "top-left";
+}
+declare function NotificationBell({ items, count, onOpen, ariaLabel, title, emptyMessage, footer, icon, className, placement, }: NotificationBellProps): react.JSX.Element;
+
+interface SidebarItem {
+    /** Stable key used for React reconciliation. */
+    id: string;
+    /** Display label. */
+    label: ReactNode;
+    /** Icon node — typically a lucide-react icon. */
+    icon?: ReactNode;
+    /** Whether this item is the current route. Caller computes from its router. */
+    active?: boolean;
+    /** Click handler for SPA-style navigation. */
+    onClick?: () => void;
+    /** Link target. Renders an `<a>` instead of a `<button>`. */
+    href?: string;
+}
+/**
+ * Captioned secondary subsection — used by large apps whose `/more` content
+ * grows past ~6 rows and benefits from concern-based grouping
+ * (`OPERATE / INVENTORY / GOVERNANCE`, …). Each group renders as its own
+ * `<nav>` with an optional caption header above the items. Within a section
+ * items are still frequency-ordered.
+ */
+interface SidebarSecondarySection {
+    /** Stable key used for React reconciliation. Falls back to array index. */
+    id?: string;
+    /** Caption text shown above the section's items. Omit for a header-less group. */
+    caption?: ReactNode;
+    /** Items in this section — same row markup as the flat secondary list. */
+    items: SidebarItem[];
+}
+interface SidebarProps {
+    /** App display name shown in the header (e.g. "schedule-manager", "🎪 Festplan"). */
+    appName?: ReactNode;
+    /** Optional logo / icon node to the left of the name. */
+    appIcon?: ReactNode;
+    /** Optional element rendered under the app name (org switcher, plan badge, …). */
+    appHeaderExtra?: ReactNode;
+    /**
+     * Primary destinations — mirror the same array that feeds
+     * `<MobileTabBar items={primary.slice(0, 4).concat([moreTab])} />`.
+     */
+    primary: SidebarItem[];
+    /**
+     * Secondary destinations as a flat list — mirror the array that feeds the
+     * `/more` page (Settings, Admin, …). Suitable for small apps. Pass an empty
+     * array if the app has no secondary nav. When `secondarySections` is also
+     * supplied, `secondarySections` wins and this prop is ignored (a dev-only
+     * `console.warn` is emitted so consumers notice the override).
+     */
+    secondary?: SidebarItem[];
+    /**
+     * Secondary destinations grouped into captioned subsections — for large apps
+     * whose `/more` grows past ~6 rows. Each group is concern-based
+     * (`OPERATE / INVENTORY / GOVERNANCE`, …) and renders as a separate `<nav>`
+     * with an optional caption header. Within a section items are still
+     * frequency-ordered. Overrides `secondary` when both are supplied.
+     * The same array shape drives the mobile `/more` drill-down rows; see
+     * `planning/wiki/concepts/sidebar-composition.md` for the contract.
+     */
+    secondarySections?: SidebarSecondarySection[];
+    /**
+     * Caption above the flat secondary list. Default: "더보기". Pass `null` to
+     * omit. Applies only when `secondary` is rendered — `secondarySections`
+     * carry their own captions per group.
+     */
+    secondaryCaption?: ReactNode | null;
+    /**
+     * Footer node — identity + Logout + build info. The convention is to
+     * render an inline `<AppInfoSection>`-style identity row plus a
+     * `[Logout]` button; `<DeployInfo>` may go inline at the very bottom.
+     * Pass `null` for an anonymous shell (login routes, public-only hosts).
+     */
+    footer?: ReactNode;
+    /** ARIA label for the nav landmark. Default: "주 메뉴". */
+    ariaLabel?: string;
+    /** Extra class merged with `etu-sidebar`. */
+    className?: string;
+    /**
+     * Behavior at the tablet tier (720–1023px). Default: `"rail"`.
+     *   - "rail"   icon-only ~64px rail
+     *   - "drawer" hidden until `open` is true; mount `<SidebarToggle>` in
+     *              your app bar to flip it
+     *   - "full"   v0.27 behavior — full 240px sidebar at all ≥720px widths
+     * Has no effect at the mobile (<720) or desktop (≥1024) tier.
+     */
+    tabletMode?: "rail" | "drawer" | "full";
+    /**
+     * Drawer open state (drawer mode only). Controlled — pair with
+     * `onOpenChange`. Auto-flips to `false` when the route changes (the
+     * parent component is expected to call `onOpenChange(false)` after
+     * navigation; or use the built-in `<SidebarToggle>` helper which wires
+     * this up). Ignored unless `tabletMode === "drawer"`.
+     */
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+}
+declare function Sidebar({ appName, appIcon, appHeaderExtra, primary, secondary, secondarySections, secondaryCaption, footer, ariaLabel, className, tabletMode, open, onOpenChange, }: SidebarProps): react.JSX.Element;
+interface SidebarToggleProps {
+    /** Whether the drawer is currently open. */
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    /** ARIA label. Default: "메뉴 열기" / "메뉴 닫기" via `labelOpen`/`labelClose`. */
+    labelOpen?: string;
+    labelClose?: string;
+    /** Extra class merged with `etu-sidebar-toggle`. */
+    className?: string;
+}
+/**
+ * Hamburger button that flips the `<Sidebar tabletMode="drawer">` open
+ * state. Visible only at the tablet tier (≥720 and <1024). Mobile users
+ * use `<MobileTabBar>`; desktop users see the full sidebar already.
+ */
+declare function SidebarToggle({ open, onOpenChange, labelOpen, labelClose, className, }: SidebarToggleProps): react.JSX.Element;
+/**
+ * State hook for the drawer mode. Persists open/closed in sessionStorage
+ * (not localStorage — drawer state is per-session, not a preference) and
+ * auto-closes when `routeKey` changes (pass your current path/hash).
+ */
+declare function useSidebarDrawer(appKey: string, routeKey?: string): [boolean, (open: boolean) => void];
+
+/**
+ * React-free i18n primitives — safe to import from `helpers.ts`, server
+ * runtimes, or the index.html-adjacent script that emits the no-flash
+ * snippet. The React provider/hooks live in `i18n.tsx` and re-export
+ * everything from here.
+ */
+type Locale = "ko" | "en";
+declare const SUPPORTED_LOCALES: Locale[];
+type Messages = Record<string, string>;
+type MessageBundle = Record<Locale, Messages>;
+/** Read the active locale (saved choice → system → "en"). */
+declare function getLocale(appKey: string): Locale;
+/** Persist and apply a locale to <html lang>. */
+declare function setLocale(appKey: string, locale: Locale): void;
+/**
+ * <head> snippet (no deps) that sets <html lang> from the saved choice,
+ * falling back to system languages, then "en".
+ */
+declare function noFlashLocaleScript(appKey: string): string;
+/** Render `{name}` placeholders. Unknown placeholders pass through. */
+declare function interpolate(template: string, vars?: Record<string, string | number>): string;
+
+interface I18nContextValue {
+    locale: Locale;
+    setLocale: (next: Locale) => void;
+    t: (key: string, vars?: Record<string, string | number>) => string;
+}
+interface I18nProviderProps {
+    /** Per-app namespace key — same one you pass to `<ThemeProvider>`. */
+    appKey: string;
+    /** Localized messages keyed by locale. EN entries act as the fallback. */
+    messages: MessageBundle;
+    children: ReactNode;
+}
+declare function I18nProvider({ appKey, messages, children }: I18nProviderProps): react.JSX.Element;
+/** Returns the active `t(key, vars?)` translator + current locale + setter. */
+declare function useI18n(): I18nContextValue;
+/** Convenience: just the translator. Equivalent to `useI18n().t`. */
+declare function useT(): I18nContextValue["t"];
+/** Convenience: just `[locale, setLocale]`. */
+declare function useLocale(): [Locale, (next: Locale) => void];
+
+/**
+ * React-free viewport primitives — safe to import from `helpers.ts`.
+ * React provider/hook lives in `viewport.tsx`.
+ */
+type ViewportTier = "mobile" | "tablet" | "desktop";
+declare const TABLET_MIN = 720;
+declare const DESKTOP_MIN = 1024;
+/** SSR-safe — returns "desktop" on the server. */
+declare function getViewport(): ViewportTier;
+declare const noFlashViewportScript: string;
+
+declare function ViewportProvider({ children }: {
+    children: ReactNode;
+}): react.JSX.Element;
+declare function useViewport(): ViewportTier;
+
+interface NavigationBarProps {
+    title: string;
+    back?: boolean | string | (() => void);
+    /** Default: "뒤로". */
+    backLabel?: string;
+    leading?: ReactNode;
+    trailing?: ReactNode;
+    /** Default: true. When true, sticks to top + applies safe-area-inset-top. */
+    sticky?: boolean;
+    /**
+     * Default: true. When false, the sticky bar omits `padding-top:
+     * env(safe-area-inset-top)` — for apps that already have a global top
+     * chrome bar (brand/avatar/bell row) above the per-page nav. Avoids
+     * double safe-area stacking that pushed iOS-PWA page titles below the
+     * visible viewport on notched devices.
+     */
+    safeAreaTop?: boolean;
+    /** Default: false. When true, omits the bottom hairline border. */
+    borderless?: boolean;
+    /**
+     * Default: true. Bar starts at 0.8 opacity and strengthens to 1 with a
+     * heavier shadow after the page scrolls past 24px. Pure-CSS via the
+     * `etu-navbar--scrolled` class toggled on a scroll listener.
+     */
+    fadeOnScroll?: boolean;
+    /** ARIA label for the inner <nav>. Default: title. */
+    ariaLabel?: string;
+    /** Extra class merged onto `etu-navbar`. */
+    className?: string;
+}
+declare function NavigationBar({ title, back, backLabel, leading, trailing, sticky, safeAreaTop, borderless, fadeOnScroll, ariaLabel, className, }: NavigationBarProps): react.JSX.Element;
+
+/**
+ * Tag the document with PWA / iOS-PWA classes and harden the iOS standalone
+ * shell against the two recurring complaints:
+ *
+ *   - Korean body text "shrinks" when the app is launched from the home screen
+ *     because iOS's text-size-adjust kicks in without the Safari toolbar. The
+ *     `@etamong-playground/ui/styles.css` reset locks this declaratively; this helper
+ *     re-applies the lock via an explicit inline style, defensively, for hosts
+ *     that mount their own stylesheet after ours.
+ *   - Tapping a `<input>` whose font-size is below 16px triggers a zoom that
+ *     never zooms back out. Opt-in: set `<html data-etu-lock-zoom>` and we set
+ *     `maximum-scale=1` on the viewport meta in iOS PWA mode.
+ *
+ * Call once from app bootstrap (before or after first paint, both fine — it's
+ * idempotent). No React; safe from any client-side entry.
+ */
+declare function installIOSPwaShell(): void;
+
+/** Production legal hub host. Override via `manifestUrl` / `hubBaseUrl` props. */
+declare const LEGAL_HUB_BASE_URL = "https://legal.m.etamong.com";
+/** Default manifest endpoint. Override per-prop for tests / staging. */
+declare const LEGAL_MANIFEST_URL = "https://legal.m.etamong.com/api/public-manifest";
+/** Recognized L2 doc kinds. The hub may add more; unknown kinds render with a humanized label. */
+type LegalKind = "terms" | "privacy" | (string & {});
+interface LegalAvailability {
+    /** Doc kinds the hub reports as published for this app, in fixed render order. */
+    kinds: LegalKind[];
+    /** "loaded" = fresh fetch; "stale" = cached over the soft TTL; "loading" = no value yet; "error" = no cached fallback either. */
+    status: "loaded" | "stale" | "loading" | "error";
+    /** Force a re-fetch (e.g. after the operator publishes a new doc). */
+    refresh: () => void;
+}
+interface UseLegalAvailabilityOptions {
+    /** Override the manifest URL — useful for tests or self-hosted hubs. */
+    manifestUrl?: string;
+    /** Disable the network fetch (e.g. SSR / Storybook). The hook returns `{kinds: [], status: "loading"}`. */
+    disabled?: boolean;
+}
+declare function useLegalAvailability(appSlug: string, options?: UseLegalAvailabilityOptions): LegalAvailability;
+interface LegalRowProps {
+    icon: ReactNode;
+    label: ReactNode;
+    /** `›` for in-app nav, `↗` for external. Default chosen from `external`. */
+    trailing?: ReactNode;
+    href: string;
+    /** When set, called instead of the default link navigation. */
+    onClick?: (event: MouseEvent<HTMLAnchorElement>) => void;
+    /** When true, opens the link in a new tab with `rel="noopener noreferrer"`. */
+    external?: boolean;
+    /**
+     * When `false` (default), the row renders a top divider (matches "second-row-onwards"
+     * inside a multi-row card). Set `true` for the first row of a card to suppress it.
+     * `<LegalMenuItem>` and `<LegalPage>` set this automatically.
+     */
+    isFirst?: boolean;
+}
+/** A single row inside an `.etu-legal-card`. Use when you want to compose your own
+ *  card with a `<LegalMenuItem>` and additional rows (e.g. 문의하기 mailto). */
+declare function LegalRow({ icon, label, trailing, href, onClick, external, isFirst, }: LegalRowProps): react.JSX.Element;
+interface LegalMenuItemProps {
+    /** Hub `serviceId` — the codename slug, e.g. `alert-ops`, `xatu`. */
+    appSlug: string;
+    /** Route the in-app `/more/legal` page lives at. Default `/more/legal`. */
+    to?: string;
+    /** SPA navigation handler. Called instead of full-page navigation. */
+    onNavigate?: (to: string) => void;
+    /** Override the leading emoji / icon. Pass `null` to omit. */
+    icon?: ReactNode | null;
+    /** Override the row label. Default: `법률 정보`. */
+    label?: ReactNode;
+    /**
+     * Set `true` when this is the first row inside its enclosing
+     * `.etu-legal-card` (suppresses the top divider). Default `false` — the row
+     * draws a top border so it sits cleanly under sibling rows like 문의하기.
+     */
+    isFirst?: boolean;
+}
+/**
+ * `법률 정보 ›` row. Renders only the row — the caller wraps it (and any
+ * sibling rows like 문의하기) in an `.etu-legal-card` so the legal entry
+ * shares the same visual card as adjacent contact/help rows (matches
+ * planning concepts/mobile-more-page diagram).
+ */
+declare function LegalMenuItem({ appSlug: _appSlug, to, onNavigate, icon, label, isFirst, }: LegalMenuItemProps): react.JSX.Element;
+interface LegalPageProps {
+    /** Hub `serviceId` — the codename slug, e.g. `alert-ops`, `xatu`. */
+    appSlug: string;
+    /** Override the L1 identity row label. Default: `로그인 정책`. */
+    identityLabel?: ReactNode;
+    /** Override the legal hub base URL (e.g. for staging). */
+    hubBaseUrl?: string;
+    /** Override per-kind row labels (extends the defaults: terms → 이용약관, privacy → 개인정보처리방침). */
+    kindLabels?: Record<string, ReactNode>;
+    /** Override anchor for a specific (kind) — by default `<appSlug>-<kind>`. */
+    anchorOverride?: Partial<Record<string, string>>;
+    /** Forwarded to `useLegalAvailability`. */
+    manifestUrl?: string;
+    /** Empty-state line shown when the manifest reports zero L2 kinds. */
+    emptyMessage?: ReactNode;
+    /** Extra class merged with the wrapping card. */
+    className?: string;
+}
+declare function LegalPage({ appSlug, identityLabel, hubBaseUrl, kindLabels, anchorOverride, manifestUrl, emptyMessage, className, }: LegalPageProps): react.JSX.Element;
+
+/**
+ * PolicyChangeBanner — a hub-driven amber banner that surfaces upcoming
+ * legal-document changes for the current app. Fetches `/status.json` from
+ * the legal hub, filters to this app's service ID, and renders a
+ * dismissible full-width strip linking to the hub page.
+ *
+ * Renders null when nothing is pending, the hub is unreachable, or the
+ * current pending set was already dismissed.
+ */
+interface PolicyChangeBannerProps {
+    /** Hub `serviceId` — the codename slug, e.g. `"schedule-manager"`. */
+    appSlug: string;
+    /** Display language. Default `"ko"`. */
+    locale?: "ko" | "en";
+    /** Override the legal hub origin. Default `LEGAL_HUB_BASE_URL`. */
+    hubBaseUrl?: string;
+    /**
+     * Router-agnostic link renderer. Default: `<a target="_blank" rel="noopener noreferrer">`.
+     * Pass your framework's `<Link>` component when the hub is same-origin.
+     */
+    renderLink?: (href: string, children: React.ReactNode) => React.ReactNode;
+    /** Extra class merged with the outer banner element. */
+    className?: string;
+}
+declare function PolicyChangeBanner({ appSlug, locale, hubBaseUrl, renderLink, className, }: PolicyChangeBannerProps): react.JSX.Element | null;
+
+/**
+ * `<DataTable>` — house-pattern tabular display per
+ * `etamong-lab/planning` wiki concept `tabular-fit-and-nowrap.md`.
+ *
+ * At wide viewports renders a real `<table>`. Below the configured
+ * breakpoint (default 720px), or whenever the carrier element is
+ * narrower than that, the rows collapse to one stacked card each
+ * (the column header becomes a label, the cell value the value).
+ * Never `overflow-x: auto`. Every column stays visible at every
+ * viewport.
+ *
+ *   <DataTable
+ *     columns={[
+ *       { key: "name", label: "App", nowrap: true,
+ *         render: a => <a href={...}>{a.slug}</a> },
+ *       { key: "version", label: "Version", nowrap: true },
+ *       { key: "built", label: "Built", nowrap: true,
+ *         render: a => a.builtAt ?? "—" },
+ *     ]}
+ *     rows={apps}
+ *     rowKey={a => a.slug}
+ *     primaryColumn="name"
+ *   />
+ *
+ * `primaryColumn` (default = first column) is the row's identifying
+ * field. In wide mode it's just the first cell; in card mode it's
+ * the card header (rendered without the label).
+ */
+
+interface DataTableColumn<R> {
+    /** Stable key — used for React keys and the optional render fallback. */
+    key: string;
+    /** Header label / card-row label. */
+    label: ReactNode;
+    /** Apply `white-space: nowrap` to this column's `<td>` and to the value side of the stacked card. Default false. */
+    nowrap?: boolean;
+    /** Render the cell for this row. Default: read `row[key]` if it's a primitive. */
+    render?: (row: R) => ReactNode;
+    /** Hide the column entirely (wide and narrow). Useful for conditional surfaces. */
+    hidden?: boolean;
+    /** Hide in narrow card mode only (e.g. action buttons that live in a separate row). */
+    hiddenNarrow?: boolean;
+    /** Hide in wide table mode only — rare; for fields that only make sense in the card view. */
+    hiddenWide?: boolean;
+    /** Optional `<th>` width hint (CSS value). */
+    width?: string;
+    /** Optional alignment. Default left. */
+    align?: "left" | "right" | "center";
+    /** Extra class merged onto both `<th>` and `<td>` for this column. */
+    className?: string;
+}
+interface DataTableProps<R> {
+    columns: DataTableColumn<R>[];
+    rows: R[];
+    rowKey: (row: R, index: number) => string | number;
+    /** Column key whose value is the row's primary identifier (appears as the card header). Defaults to the first non-hidden column. */
+    primaryColumn?: string;
+    /** Optional below-card action row (buttons). Hidden in wide mode unless rendered as a column. */
+    rowActions?: (row: R) => ReactNode;
+    /** Shown when `rows` is empty. */
+    emptyState?: ReactNode;
+    /** Extra class merged onto the outer wrapper. */
+    className?: string;
+    /** Force a mode. Default: container-query driven (`auto`). */
+    mode?: "auto" | "wide" | "cards";
+}
+declare function DataTable<R>(props: DataTableProps<R>): ReactNode;
+
+interface DocsHubSection {
+    /** Stable key used in the left nav + as the section anchor. */
+    id: string;
+    /** Sidebar label. */
+    label: ReactNode;
+    /** Optional one-line summary shown under the section heading. */
+    summary?: ReactNode;
+    /** Body content — apps supply their own JSX (or rendered markdown). */
+    content: ReactNode;
+}
+interface DocsHubSkill {
+    /** Skill slug — used as the download filename `<name>.md`. */
+    name: string;
+    /** One-line description (skill frontmatter `description:`). */
+    description: string;
+    /** The skill body in markdown. */
+    body: string;
+    /**
+     * Stable public URL serving the same skill markdown bytes as the
+     * download button. Convention: `https://<app>.m.etamong.com/skill.md`.
+     * When set, DocsHub shows a `curl … -o ~/.claude/skills/<slug>/SKILL.md`
+     * one-liner as the primary install path (download stays as fallback).
+     * The endpoint must be unauthenticated and return `text/markdown`.
+     * See wiki/concepts/docs-hub.md.
+     */
+    publicUrl?: string;
+    /** Optional CTA label override. Default: "📥 Claude skill 받기". */
+    buttonLabel?: ReactNode;
+    /**
+     * Override or hide the auto-appended "Claude skill 사용법" section.
+     * - `undefined` (default): DocsHub appends a standard usage section
+     *   (Claude Code, Codex, plain LLM context).
+     * - A custom `DocsHubSection`: use that instead.
+     * - `null`: skip the auto-section entirely.
+     */
+    usageSection?: DocsHubSection | null;
+}
+interface DocsHubProps {
+    /** App display name shown in the page head (left of the skill button). */
+    appName?: ReactNode;
+    /** Optional sub-heading under `appName`. */
+    description?: ReactNode;
+    /** Section list. At least one section. */
+    sections: DocsHubSection[];
+    /** Skill artifact downloaded by the top-right button. Omit to hide it. */
+    skill?: DocsHubSkill;
+    /** Controlled active section. Pair with `onSectionChange`. */
+    sectionId?: string;
+    /** Active-section callback (controlled mode). */
+    onSectionChange?: (id: string) => void;
+    /** Initial section id (uncontrolled). Default: first section. */
+    defaultSectionId?: string;
+    /** Extra class merged with `etu-docs-hub`. */
+    className?: string;
+}
+declare function DocsHub({ appName, description, sections, skill, sectionId, onSectionChange, defaultSectionId, className, }: DocsHubProps): react.JSX.Element;
+/** Exported for apps that want to render or share the skill markdown without
+ *  triggering a download (e.g., a "copy to clipboard" affordance). */
+declare function buildSkillMarkdownText(skill: DocsHubSkill): string;
+
+/**
+ * Fleet-auth primitives — implements the route contract documented at
+ * `planning/wiki/concepts/fleet-auth.md` (planning#252).
+ *
+ *   GET /auth/login?rd=<path>      OIDC authorization
+ *   GET /auth/callback              token exchange + session cookie
+ *   GET /auth/logout                clear session
+ *   GET /api/me                     { sub, email, name, groups }
+ *
+ * Apps still on the older `oauth2-proxy` paths (`/oauth2/start`,
+ * `/oauth2/sign_out`) use `useMe()` / `signInUrl()` / `signOutUrl()`
+ * from `./useMe` directly — those keep their legacy default. This
+ * module is the forward path that fleet apps standardise on.
+ */
+
+declare const SHARE_CRAWLER_UA_SUBSTRINGS: readonly ["kakaotalk-scrap", "slackbot", "facebookexternalhit", "twitterbot", "discordbot", "linkedinbot", "telegrambot", "whatsapp", "line-poker"];
+/** Returns true if `ua` matches any advertised share-preview crawler. */
+declare function isShareCrawler(ua: string | null | undefined): boolean;
+/** Fleet-contract sign-in URL: `/auth/login?rd=<current or override>`. */
+declare function fleetLoginUrl(rd?: string): string;
+/** Fleet-contract sign-out URL: `/auth/logout?rd=<override or "/">`. */
+declare function fleetLogoutUrl(rd?: string): string;
+declare function fleetSignIn(rd?: string): void;
+declare function fleetSignOut(rd?: string): void;
+/**
+ * Thin wrapper over `useMe()` with fleet defaults — `/api/me`, 401 treated
+ * as anonymous. Returns the same shape plus `signIn`/`signOut` bound to
+ * the fleet contract URLs.
+ */
+interface UseIdentityResult<T extends BaseMe> extends UseMeResult<T> {
+    signIn: (rd?: string) => void;
+    signOut: (rd?: string) => void;
+}
+declare function useIdentity<T extends BaseMe = BaseMe>(opts?: UseMeOptions<T>): UseIdentityResult<T>;
+/**
+ * Renders `children` only for authenticated users. Anonymous browser
+ * navigation triggers a `window.location` redirect to the fleet login.
+ * Share-preview crawlers (UA match) and SSR/Next get `children`
+ * unconditionally so the static `<meta og:*>` block remains readable.
+ */
+interface AuthGateProps {
+    children: React.ReactNode;
+    /** Override the post-login redirect target. Default = current location. */
+    rd?: string;
+    /** What to show while `/api/me` is in flight. Default = `null`. */
+    loadingFallback?: React.ReactNode;
+    /**
+     * Pre-resolved User-Agent for SSR/Next environments. When supplied and
+     * matching a known crawler, the gate is bypassed and `children` render
+     * directly. In CSR `navigator.userAgent` is used.
+     */
+    userAgent?: string;
+    /** When true, skip the redirect (render `null` instead). */
+    disableRedirect?: boolean;
+}
+declare function AuthGate({ children, rd, loadingFallback, userAgent, disableRedirect, }: AuthGateProps): JSX.Element | null;
+interface LoginButtonProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "onClick"> {
+    /** Override the post-login redirect target. */
+    rd?: string;
+    /** Label override. Default: "Sign in". */
+    label?: React.ReactNode;
+}
+declare function LoginButton({ rd, label, style, ...rest }: LoginButtonProps): JSX.Element;
+interface LogoutButtonProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "onClick"> {
+    rd?: string;
+    label?: React.ReactNode;
+}
+declare function LogoutButton({ rd, label, style, ...rest }: LogoutButtonProps): JSX.Element;
+interface SessionBadgeProps {
+    /** Override the identity. By default, `useIdentity()` is used. */
+    me?: BaseMe | null;
+    /** Click target. Default: do nothing; consumers usually navigate to /more. */
+    onClick?: () => void;
+    /** Class hook for app-side overrides. */
+    className?: string;
+}
+declare function SessionBadge({ me: overrideMe, onClick, className, }: SessionBadgeProps): JSX.Element | null;
+/**
+ * Listens for `etu:session-expired` events and mounts a single
+ * dialog directing the user to sign in again. Apps trigger it by
+ * dispatching the event from their XHR error handler when /api/* returns
+ * 401 after the initial `/api/me` succeeded.
+ */
+interface SessionExpiredDialogProps {
+    title?: React.ReactNode;
+    message?: React.ReactNode;
+    signInLabel?: React.ReactNode;
+    /** Optional class hook for the dialog root. */
+    className?: string;
+}
+declare function SessionExpiredDialog({ title, message, signInLabel, className, }: SessionExpiredDialogProps): JSX.Element | null;
+/** Dispatch the `etu:session-expired` event. Call from your XHR layer. */
+declare function notifySessionExpired(): void;
+/** Dispatch the `etu:me-refresh` event so any mounted `useMe`/`useIdentity` re-fetches. */
+declare function refreshIdentity(): void;
+
+export { AdminBadge, type AdminBadgeProps, type AdminCheckInput, AdminGate, type AdminGateProps, type AppInfoLink, AppInfoSection, type AppInfoSectionProps, AuthGate, type AuthGateProps, Avatar, type AvatarProps, BackButton, type BackButtonProps, BackofficeLayout, type BackofficeLayoutProps, type BaseMe, CODE_TO_KEY, COMMAND_PALETTE_OPEN_EVENT, type CommandItem, CommandPalette, type CommandPaletteLabels, type CommandPaletteProps, CommandPaletteTrigger, type CommandPaletteTriggerProps, type CommandSearchAction, type CommandSection, CopyButton, type CopyButtonProps, type CreateFetchOptions, DESKTOP_MIN, DataTable, type DataTableColumn, type DataTableProps, DeployInfo, type DeployInfoProps, DialogHost, DocsHub, type DocsHubProps, type DocsHubSection, type DocsHubSkill, EmptyState, type EmptyStateProps, ErrorPage, type ErrorPageProps, type FetchClient, type FormatAbsTimeOptions, type FormatRelTimeOptions, type GoToOptions, type GoToRoute, HttpError, type HttpErrorBody, I18nProvider, type I18nProviderProps, type InAppBackFallback, InstallBanner, type InstallBannerProps, LEGAL_HUB_BASE_URL, LEGAL_MANIFEST_URL, type LegalAvailability, type LegalKind, LegalMenuItem, type LegalMenuItemProps, LegalPage, type LegalPageProps, LegalRow, type LegalRowProps, type Locale, LoginButton, type LoginButtonProps, LogoutButton, type LogoutButtonProps, type MessageBundle, type Messages, MobileTabBar, type MobileTabBarItem, type MobileTabBarProps, NavigationBar, type NavigationBarProps, type NetworkFirstSwOptions, NotificationBell, type NotificationBellItem, type NotificationBellProps, OpenInBrowserButton, type OpenInBrowserButtonProps, PolicyChangeBanner, type PolicyChangeBannerProps, type RegisterServiceWorkerOptions, RelTime, type RelTimeProps, type RequestOptions, SHARE_CRAWLER_UA_SUBSTRINGS, SUPPORTED_LOCALES, type ServiceWorkerHandle, SessionBadge, type SessionBadgeProps, SessionExpiredDialog, type SessionExpiredDialogProps, Sidebar, type SidebarItem, type SidebarProps, type SidebarSecondarySection, SidebarToggle, type SidebarToggleProps, StatusBanner, type StatusBannerData, type StatusBannerProps, type Severity as StatusBannerSeverity, TABLET_MIN, type Theme, type TimeLike, type ToastItem, type ToastKind, Toaster, type UseClipboardOptions, type UseClipboardResult, type UseIdentityResult, type UseInAppBackOptions, type UseInAppBackResult, type UseLegalAvailabilityOptions, type UseMeOptions, type UseMeResult, type UseRouteStateOptions, type UseSessionStateOptions, type UseStatusBannerOptions, UserMenu, type UserMenuItem, type UserMenuProps, ViewportProvider, type ViewportTier, buildSkillMarkdownText, createFetch, crossLocaleKeywords, dismissToast, fleetLoginUrl, fleetLogoutUrl, fleetSignIn, fleetSignOut, formatAbsTime, formatRelTime, getLocale, getTheme, getViewport, installIOSPwaShell, interpolate, isAdminLike, isInputTarget, isShareCrawler, networkFirstSwSource, noFlashLocaleScript, noFlashThemeScript, noFlashViewportScript, notifySessionExpired, openCommandPalette, refreshIdentity, registerServiceWorker, runInAppBackFallback, setLocale, setTheme, shortcutKey, signIn, signInUrl, signOut, signOutUrl, toast, uiConfirm, uiPrompt, useClipboard, useGoToShortcuts, useI18n, useIdentity, useInAppBack, useInstallPrompt, useLegalAvailability, useLocale, useMe, useRouteState, useSessionState, useSidebarDrawer, useStatusBanner, useT, useViewport };