@molecule/app-ui-react 1.3.2 → 1.3.4

package/README.md

@@ -3,20 +3,20 @@ AUTO-GENERATED — DO NOT EDIT THIS FILE.
 Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
 Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
 To change this document, edit the module-level JSDoc in src/index.ts.
-Generated: 2026-10-03T14:45:44.646Z
+Generated: 2026-10-16T23:38:48.542Z
 -->
 
 # @molecule/app-ui-react
 
-> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
-> It is written to be read by coding agents as much as by people, and is generated from this
-> package's source — edit `src/index.ts` JSDoc, not this file.
-
 React UI components for molecule.dev.
 
 Provides React implementations of the `@molecule/app-ui` component
 interfaces using the UIClassMap abstraction from `@molecule/app-ui`.
 
+> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
+> It is written to be read by coding agents as much as by people, and is generated from this
+> package's source — edit `src/index.ts` JSDoc, not this file.
+
 ## Quick Start
 
 ```tsx
@@ -66,331 +66,385 @@ npm install -D @types/react @types/react-dom
 
 ### Interfaces
 
-#### `AccordionItem`
+#### `CSSProperties`
 
-A single item in an Accordion component.
+Framework-agnostic CSS properties.
+Mirrors React.CSSProperties but without React dependency.
 
 ```typescript
-interface AccordionItem<T = string> {
-  /**
-   * Item value/id.
-   */
-  value: T
-  /**
-   * Item header/trigger.
-   */
-  header: Children
-  /**
-   * Item content.
-   */
-  content: Children
-  /**
-   * Whether the item is disabled.
-   */
-  disabled?: boolean
+interface CSSProperties {
+  [key: string]: string | number | undefined
 }
 ```
 
-#### `AccordionProps`
+#### `BaseProps`
 
-Props for the Accordion component.
+Base props shared by all components.
 
 ```typescript
-interface AccordionProps<T = string> extends BaseProps {
+interface BaseProps {
   /**
-   * Accordion items.
+   * Additional CSS class name(s).
    */
-  items: AccordionItem<T>[]
+  className?: string
   /**
-   * Expanded item(s).
+   * Inline styles.
    */
-  value?: T | T[]
+  style?: CSSProperties
   /**
-   * Default expanded item(s).
+   * Test ID for automated testing.
    */
-  defaultValue?: T | T[]
+  testId?: string
   /**
-   * Change handler.
+   * Automation ID for AI agents and E2E tests. Maps to the `data-mol-id`
+   * HTML attribute. Use `molId()` from `./automation.js` to generate
+   * semantic IDs. (Tooling only — screen readers do not expose `data-*`
+   * attributes; accessible names come from labels/`aria-*`.)
    */
-  onChange?: (value: T | T[]) => void
+  automationId?: string
   /**
-   * Whether multiple items can be expanded.
+   * Whether the component is disabled.
    */
-  multiple?: boolean
+  disabled?: boolean
+}
+```
+
+#### `HTMLElementProps`
+
+Base props for HTML elements.
+Framework bindings should extend this with framework-specific attributes.
+
+```typescript
+interface HTMLElementProps extends BaseProps {
+  id?: string
+  title?: string
+  tabIndex?: number
+  role?: string
+  'aria-label'?: string
+  'aria-labelledby'?: string
+  'aria-describedby'?: string
+  'aria-hidden'?: boolean
+  'aria-disabled'?: boolean
+  'aria-expanded'?: boolean
+  'aria-selected'?: boolean
+  'aria-checked'?: boolean | 'mixed'
+  'aria-pressed'?: boolean | 'mixed'
+  'aria-invalid'?: boolean
+  'aria-required'?: boolean
+  'aria-readonly'?: boolean
+  'aria-busy'?: boolean
+  'aria-live'?: 'off' | 'polite' | 'assertive'
+  onClick?: MouseEventHandler
+  onDoubleClick?: MouseEventHandler
+  onMouseEnter?: MouseEventHandler
+  onMouseLeave?: MouseEventHandler
+  onFocus?: FocusEventHandler
+  onBlur?: FocusEventHandler
+  onKeyDown?: KeyboardEventHandler
+  onKeyUp?: KeyboardEventHandler
+  onKeyPress?: KeyboardEventHandler
+}
+```
+
+#### `InputElementProps`
+
+Base props for input elements.
+
+```typescript
+interface InputElementProps extends HTMLElementProps {
+  name?: string
+  value?: string | number | readonly string[]
+  defaultValue?: string | number | readonly string[]
+  placeholder?: string
+  required?: boolean
+  readOnly?: boolean
+  autoFocus?: boolean
+  autoComplete?: string
+  maxLength?: number
+  minLength?: number
+  pattern?: string
+  onChange?: ChangeEventHandler
+  onInput?: FormEventHandler
+}
+```
+
+#### `ButtonElementProps`
+
+Base props for button elements.
+
+```typescript
+interface ButtonElementProps extends HTMLElementProps {
   /**
-   * Whether items can be collapsed.
+   * Defaults to `'button'` in every framework binding, so a button never submits a
+   * form by accident. A form's primary action must set `type="submit"`: Enter then
+   * submits the form, and tests that select `button[type="submit"]` find it.
    */
-  collapsible?: boolean
+  type?: 'button' | 'submit' | 'reset'
+  name?: string
+  value?: string
+  form?: string
 }
 ```
 
-#### `AlertProps`
+#### `TextareaElementProps`
 
-Props for the Alert component.
+Base props for textarea elements.
 
 ```typescript
-interface AlertProps extends HTMLElementProps {
+interface TextareaElementProps extends HTMLElementProps {
+  name?: string
+  value?: string
+  defaultValue?: string
+  placeholder?: string
+  required?: boolean
+  readOnly?: boolean
+  autoFocus?: boolean
+  rows?: number
+  cols?: number
+  maxLength?: number
+  minLength?: number
+  wrap?: 'hard' | 'soft' | 'off'
+  onChange?: ChangeEventHandler
+  onInput?: FormEventHandler
+}
+```
+
+#### `SelectElementProps`
+
+Base props for select elements.
+
+```typescript
+interface SelectElementProps extends HTMLElementProps {
+  name?: string
+  required?: boolean
+  autoFocus?: boolean
+  multiple?: boolean
+  onChange?: ChangeEventHandler
+}
+```
+
+#### `FormElementProps`
+
+Base props for form elements.
+
+```typescript
+interface FormElementProps extends HTMLElementProps {
+  action?: string
+  method?: 'get' | 'post'
+  encType?: string
+  target?: string
+  noValidate?: boolean
+  autoComplete?: 'on' | 'off'
+  onSubmit?: FormEventHandler
+  onReset?: FormEventHandler
+}
+```
+
+#### `ButtonProps`
+
+Props for the Button component.
+
+```typescript
+interface ButtonProps extends ButtonElementProps {
   /**
-   * Alert content.
+   * Button content.
    */
   children?: Children
   /**
-   * Alert title.
+   * Visual variant.
    */
-  title?: string
+  variant?: ButtonVariant
   /**
-   * Alert status/type.
+   * Color scheme.
    */
-  status?: ColorVariant
+  color?: ColorVariant
   /**
-   * Alert variant.
+   * Button size.
    */
-  variant?: 'solid' | 'subtle' | 'outline' | 'left-accent'
+  size?: ButtonSize
   /**
-   * Whether the alert is dismissible.
+   * Whether the button is in a loading state.
    */
-  dismissible?: boolean
+  loading?: boolean
   /**
-   * Called when dismissed.
+   * Loading text to display.
    */
-  onDismiss?: () => void
+  loadingText?: string
   /**
-   * Icon to display.
+   * Whether the button takes full width.
    */
-  icon?: Children
+  fullWidth?: boolean
   /**
-   * Accessible label for the dismiss button.
-   * @default 'Dismiss'
+   * Icon to display before the label.
    */
-  dismissLabel?: string
+  leftIcon?: Children
+  /**
+   * Icon to display after the label.
+   */
+  rightIcon?: Children
 }
 ```
 
-#### `AuthGuardProps`
-
-Props for {@link AuthGuard}.
+#### `InputProps`
 
-All props are optional — the default behavior (loading tag → redirect
-to `/login` → `<Outlet />`) matches the bare-bones guard apps were
-shipping locally. The props let apps customize per-call without
-forking the component.
+Props for the Input component (text field, email, password, etc.).
 
 ```typescript
-interface AuthGuardProps {
+interface InputProps extends InputElementProps {
   /**
-   * Element rendered while `useAuth().state.initialized` is `false`.
-   * Overrides the default `<div data-mol-id="auth-guard-loading">…</div>`
-   * loading tag — pass a full-page spinner or any other UI you want
-   * during the auth bootstrap window.
+   * Input type.
    */
-  loadingFallback?: ReactNode
+  type?: InputType
   /**
-   * i18n key used for the default loading-tag text. Defaults to
-   * `'common.loading'`. Ignored when `loadingFallback` is set.
+   * Input size.
    */
-  loadingKey?: string
+  size?: Size
   /**
-   * Fallback text if the i18n key is missing. Defaults to `'Loading...'`
-   * (the project-canonical ASCII glyph — Phase C of the locale
-   * canonicalization plan). Ignored when `loadingFallback` is set.
-   */
-  loadingDefault?: string
-  /**
-   * Path to redirect to when the user is not authenticated. Defaults to
-   * `'/login'`. The current `useLocation()` is preserved as `state.from`
-   * for post-login restoration.
+   * Horizontal text alignment inside the input (see
+   * {@link InputClassOptions.align}). Defaults to the bond's own style.
    */
-  loginPath?: string
+  align?: 'left' | 'center'
   /**
-   * Callback invoked when `isAuthenticated` transitions to `true` (or is
-   * already `true` on first render). Useful for one-shot per-app
-   * bootstrap effects (e.g. seeding fixture data). The caller is
-   * responsible for idempotency if the auth state can flip back and
-   * forth — this fires on every transition.
+   * Label text.
    */
-  onAuthenticated?: () => void
+  label?: string
   /**
-   * Children to render when authenticated. Defaults to `<Outlet />`,
-   * which is the React Router pattern this guard is designed for.
+   * Error message.
    */
-  children?: ReactNode
-}
-```
-
-#### `AvatarProps`
-
-Props for the Avatar component.
-
-```typescript
-interface AvatarProps extends HTMLElementProps {
+  error?: string
   /**
-   * Image source URL.
+   * Hint/help text.
    */
-  src?: string
+  hint?: string
   /**
-   * Alt text for the image.
+   * Element to display on the left.
    */
-  alt?: string
+  leftElement?: Children
   /**
-   * Name for fallback initials.
+   * Element to display on the right.
    */
-  name?: string
+  rightElement?: Children
   /**
-   * Avatar size.
+   * Whether to show a clear button.
    */
-  size?: Size | number
+  clearable?: boolean
   /**
-   * Whether the avatar is rounded.
+   * Called when the clear button is clicked.
    */
-  rounded?: boolean
+  onClear?: () => void
   /**
-   * Fallback element when no image.
+   * Accessible label for the clear button.
+   * @default 'Clear'
    */
-  fallback?: Children
+  clearLabel?: string
 }
 ```
 
-#### `BadgeProps`
+#### `TextareaProps`
 
-Props for the Badge component (status labels, counts, tags).
+Props for the Textarea component.
 
 ```typescript
-interface BadgeProps extends HTMLElementProps {
+interface TextareaProps extends TextareaElementProps {
   /**
-   * Badge content.
+   * Text size tier (see {@link TextareaClassOptions.size}) — pass the same
+   * `size` as a neighboring Input for identical font sizes.
    */
-  children?: Children
+  size?: Size
   /**
-   * Badge color.
+   * Label text.
    */
-  color?: ColorVariant
+  label?: string
   /**
-   * Badge variant.
+   * Error message.
    */
-  variant?: 'solid' | 'outline' | 'subtle'
+  error?: string
   /**
-   * Badge size.
+   * Hint/help text.
    */
-  size?: Size
+  hint?: string
   /**
-   * Whether the badge is rounded.
+   * Whether the textarea auto-resizes.
    */
-  rounded?: boolean
+  autoResize?: boolean
+  /**
+   * Minimum number of rows.
+   */
+  minRows?: number
+  /**
+   * Maximum number of rows.
+   */
+  maxRows?: number
 }
 ```
 
-#### `BaseProps`
+#### `SelectOption`
 
-Base props shared by all components.
+A single option in a Select dropdown.
 
 ```typescript
-interface BaseProps {
-  /**
-   * Additional CSS class name(s).
-   */
-  className?: string
+interface SelectOption<T = string> {
   /**
-   * Inline styles.
+   * Option value.
    */
-  style?: CSSProperties
+  value: T
   /**
-   * Test ID for automated testing.
+   * Display label.
    */
-  testId?: string
+  label: string
   /**
-   * Automation ID for AI agents and E2E tests. Maps to the `data-mol-id`
-   * HTML attribute. Use `molId()` from `./automation.js` to generate
-   * semantic IDs. (Tooling only — screen readers do not expose `data-*`
-   * attributes; accessible names come from labels/`aria-*`.)
+   * Whether the option is disabled.
    */
-  automationId?: string
+  disabled?: boolean
   /**
-   * Whether the component is disabled.
+   * Option group (for grouped selects).
    */
-  disabled?: boolean
-}
-```
-
-#### `ButtonElementProps`
-
-Base props for button elements.
-
-```typescript
-interface ButtonElementProps extends HTMLElementProps {
-  type?: 'button' | 'submit' | 'reset'
-  name?: string
-  value?: string
-  form?: string
+  group?: string
 }
 ```
 
-#### `ButtonProps`
+#### `SelectProps`
 
-Props for the Button component.
+Props for the Select dropdown component (single or multi-select).
 
 ```typescript
-interface ButtonProps extends ButtonElementProps {
-  /**
-   * Button content.
-   */
-  children?: Children
-  /**
-   * Visual variant.
-   */
-  variant?: ButtonVariant
-  /**
-   * Color scheme.
-   */
-  color?: ColorVariant
-  /**
-   * Button size.
-   */
-  size?: ButtonSize
+interface SelectProps<T = string> extends SelectElementProps {
   /**
-   * Whether the button is in a loading state.
+   * Select options.
    */
-  loading?: boolean
+  options: SelectOption<T>[]
   /**
-   * Loading text to display.
+   * Current value.
    */
-  loadingText?: string
+  value?: T
   /**
-   * Whether the button takes full width.
+   * Change handler (with typed value).
    */
-  fullWidth?: boolean
+  onValueChange?: (value: T) => void
   /**
-   * Icon to display before the label.
+   * Select size.
    */
-  leftIcon?: Children
+  size?: Size
   /**
-   * Icon to display after the label.
+   * Label text.
    */
-  rightIcon?: Children
-}
-```
-
-#### `CardProps`
-
-Props for the Card container component (elevated, outlined, or filled surface).
-
-```typescript
-interface CardProps extends HTMLElementProps {
+  label?: string
   /**
-   * Card content.
+   * Placeholder text.
    */
-  children?: Children
+  placeholder?: string
   /**
-   * Card variant.
+   * Error message.
    */
-  variant?: 'elevated' | 'outlined' | 'filled'
+  error?: string
   /**
-   * Whether the card is interactive (clickable).
+   * Hint/help text.
    */
-  interactive?: boolean
+  hint?: string
   /**
-   * Padding size.
+   * Whether to allow clearing the selection.
    */
-  padding?: Size | 'none'
+  clearable?: boolean
 }
 ```
 
@@ -423,1027 +477,813 @@ interface CheckboxProps extends InputElementProps {
 }
 ```
 
-#### `ConfirmButtonProps`
+#### `RadioOption`
 
-Props for {@link ConfirmButton}.
+A single option in a RadioGroup.
 
 ```typescript
-interface ConfirmButtonProps extends Omit<
-  ButtonProps,
-  'onClick' | 'children' | 'onConfirm' | keyof React.DOMAttributes<HTMLButtonElement>
-> {
+interface RadioOption<T = string> {
   /**
-   * Fired ONLY on the confirming (second) click — i.e. when the action
-   * actually commits. Errors should be handled by the caller (render an
-   * inline banner); while the returned promise is pending the button stays
-   * in its confirming state and ignores further clicks.
+   * Option value.
    */
-  onConfirm: () => void | Promise<void>
+  value: T
   /**
-   * Visible label in the idle (armed-to-be-clicked) state.
+   * Display label.
    */
-  label: React.ReactNode
+  label: Children
   /**
-   * Visible label in the armed state — the "click again to confirm" step.
-   * Defaults to a localized "Confirm?" via the i18n bond.
+   * Whether the option is disabled.
    */
-  confirmLabel?: React.ReactNode
+  disabled?: boolean
+}
+```
+
+#### `RadioGroupProps`
+
+Props for the RadioGroup component.
+
+```typescript
+interface RadioGroupProps<T = string> extends BaseProps {
   /**
-   * Visible label while {@link onConfirm} is pending. Defaults to a
-   * localized "Working…".
+   * Radio options.
    */
-  pendingLabel?: React.ReactNode
+  options: RadioOption<T>[]
   /**
-   * Seconds before the armed state auto-disarms back to idle. Low-stakes
-   * actions tolerate a long window; destructive ones should keep it short.
-   * `0` disables auto-disarm (not recommended — a stray click then leaves
-   * the button armed forever).
+   * Current value.
    */
-  disarmSeconds?: number
+  value?: T
   /**
-   * Disable the control entirely (idle and confirming states).
+   * Change handler.
    */
-  disabled?: boolean
+  onChange?: (value: T) => void
   /**
-   * data-mol-id for the button (all states share one element).
+   * Radio size.
    */
-  testId?: string
-}
-```
-
-#### `ConfirmDialogProps`
-
-Props for {@link ConfirmDialog}.
-
-```typescript
-interface ConfirmDialogProps {
-  /** Whether the dialog is open. */
-  open: boolean
-  /** Called when the dialog should close (escape, backdrop, cancel). */
-  onClose: () => void
-  /** Title. */
-  title: ReactNode
-  /** Body / warning text. */
-  description: ReactNode
-  /** Confirm-button label (e.g. "Delete"). */
-  confirmLabel?: ReactNode
-  /** Cancel-button label. */
-  cancelLabel?: ReactNode
-  /** Called when the user confirms. */
-  onConfirm: () => void | Promise<void>
-  /** Is the confirm action destructive? Defaults to true. */
-  destructive?: boolean
-  /** Extra body content between description and footer. */
-  children?: ReactNode
-  /** Disables both buttons. Set it yourself while your `onConfirm` promise is pending — the dialog does not track it and does not auto-close. */
-  loading?: boolean
-}
-```
-
-#### `ContainerProps`
-
-Props for the Container layout component.
-
-```typescript
-interface ContainerProps extends HTMLElementProps {
+  size?: Size
   /**
-   * Container content.
+   * Group label.
    */
-  children?: Children
+  label?: string
   /**
-   * Maximum width.
+   * Shared `name` attribute for the group's radio inputs (used for native
+   * form submission). When omitted, a unique per-instance name is generated
+   * so separate groups never merge — the visible `label` is deliberately
+   * NOT used as the name, because two groups with the same label (e.g. two
+   * "Size" pickers) would otherwise form ONE native radio group and
+   * deselect each other.
    */
-  maxWidth?: 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'full' | string
+  name?: string
   /**
-   * Whether to center the container.
+   * Layout direction.
    */
-  centered?: boolean
+  direction?: 'horizontal' | 'vertical'
   /**
-   * Horizontal padding.
+   * Error message.
    */
-  paddingX?: Size | string
+  error?: string
 }
 ```
 
-#### `CSSProperties`
+#### `SwitchProps`
 
-Framework-agnostic CSS properties.
-Mirrors React.CSSProperties but without React dependency.
+Props for the Switch/Toggle component.
 
 ```typescript
-interface CSSProperties {
-  [key: string]: string | number | undefined
+interface SwitchProps extends InputElementProps {
+  /**
+   * Switch label.
+   */
+  label?: Children
+  /**
+   * Whether the switch is on.
+   */
+  checked?: boolean
+  /**
+   * Switch size.
+   */
+  size?: Size
+  /**
+   * Color when on.
+   */
+  color?: ColorVariant
 }
 ```
 
-#### `FlexProps`
+#### `ModalProps`
 
-Flex container props.
+Props for the Modal/Dialog component.
 
 ```typescript
-interface FlexProps extends HTMLElementProps {
+interface ModalProps extends HTMLElementProps {
   /**
-   * Flex content.
+   * Whether the modal is open.
+   */
+  open: boolean
+  /**
+   * Called when the modal should close.
+   */
+  onClose: () => void
+  /**
+   * Modal title.
+   */
+  title?: string
+  /**
+   * Modal content.
    */
   children?: Children
   /**
-   * Flex direction.
+   * Modal size.
    */
-  direction?: 'row' | 'column' | 'row-reverse' | 'column-reverse'
+  size?: ModalSize
   /**
-   * Justify content.
+   * Whether to show a close button.
    */
-  justify?: 'start' | 'end' | 'center' | 'between' | 'around' | 'evenly'
+  showCloseButton?: boolean
   /**
-   * Align items.
+   * Whether clicking the overlay closes the modal.
    */
-  align?: 'start' | 'end' | 'center' | 'baseline' | 'stretch'
+  closeOnOverlayClick?: boolean
   /**
-   * Flex wrap.
+   * Whether pressing Escape closes the modal.
    */
-  wrap?: 'wrap' | 'nowrap' | 'wrap-reverse'
+  closeOnEscape?: boolean
   /**
-   * Gap between items.
+   * Footer content (typically action buttons).
    */
-  gap?: Size | string | number
+  footer?: Children
+  /**
+   * Whether the modal is centered vertically.
+   */
+  centered?: boolean
+  /**
+   * Whether to prevent body scroll when open.
+   */
+  preventScroll?: boolean
+  /**
+   * Accessible label for the close button.
+   * @default 'Close'
+   */
+  closeLabel?: string
 }
 ```
 
-#### `FormElementProps`
+#### `SpinnerProps`
 
-Base props for form elements.
+Props for the Spinner/loading indicator component.
 
 ```typescript
-interface FormElementProps extends HTMLElementProps {
-  action?: string
-  method?: 'get' | 'post'
-  encType?: string
-  target?: string
-  noValidate?: boolean
-  autoComplete?: 'on' | 'off'
-  onSubmit?: FormEventHandler
-  onReset?: FormEventHandler
+interface SpinnerProps extends BaseProps {
+  /**
+   * Spinner size.
+   */
+  size?: Size
+  /**
+   * Spinner color.
+   */
+  color?: ColorVariant | string
+  /**
+   * Loading label (for accessibility).
+   */
+  label?: string
+  /**
+   * Spinner thickness.
+   */
+  thickness?: number
 }
 ```
 
-#### `FormFieldProps`
+#### `AvatarProps`
 
-Form field wrapper props.
+Props for the Avatar component.
 
 ```typescript
-interface FormFieldProps extends HTMLElementProps {
+interface AvatarProps extends HTMLElementProps {
   /**
-   * Field content.
+   * Image source URL.
    */
-  children?: Children
+  src?: string
   /**
-   * Field label.
+   * Alt text for the image.
    */
-  label?: string
+  alt?: string
   /**
-   * Field name.
+   * Name for fallback initials.
    */
   name?: string
   /**
-   * Error message.
+   * Avatar size.
    */
-  error?: string
+  size?: Size | number
   /**
-   * Hint/help text.
+   * Whether the avatar is rounded.
    */
-  hint?: string
+  rounded?: boolean
   /**
-   * Whether the field is required.
+   * Fallback element when no image.
    */
-  required?: boolean
+  fallback?: Children
 }
 ```
 
-#### `FormProps`
+#### `BadgeProps`
 
-Props for the Form component (wraps inputs with submission handling and validation).
+Props for the Badge component (status labels, counts, tags).
 
 ```typescript
-interface FormProps extends FormElementProps {
+interface BadgeProps extends HTMLElementProps {
   /**
-   * Form content.
+   * Badge content.
    */
   children?: Children
   /**
-   * Submit handler with form data.
+   * Badge color.
    */
-  onFormSubmit?: (data: Record<string, unknown>) => void | Promise<void>
+  color?: ColorVariant
   /**
-   * Whether the form is submitting.
+   * Badge variant.
    */
-  submitting?: boolean
+  variant?: 'solid' | 'outline' | 'subtle'
+  /**
+   * Badge size.
+   */
+  size?: Size
+  /**
+   * Whether the badge is rounded.
+   */
+  rounded?: boolean
 }
 ```
 
-#### `GridProps`
+#### `TooltipProps`
 
-Grid container props.
+Props for the Tooltip component (hover/focus popover with informational text).
 
 ```typescript
-interface GridProps extends HTMLElementProps {
-  /**
-   * Grid content.
-   */
-  children?: Children
+interface TooltipProps extends HTMLElementProps {
   /**
-   * Number of columns.
+   * Tooltip content.
    */
-  columns?: number | string
+  content: Children
   /**
-   * Number of rows.
+   * Element that triggers the tooltip.
    */
-  rows?: number | string
+  children: Children
   /**
-   * Gap between items.
+   * Tooltip placement.
    */
-  gap?: Size | string | number
+  placement?: TooltipPlacement
   /**
-   * Column gap.
+   * Delay before showing (ms).
    */
-  columnGap?: Size | string | number
+  delay?: number
   /**
-   * Row gap.
+   * Whether the tooltip has an arrow.
    */
-  rowGap?: Size | string | number
+  hasArrow?: boolean
 }
 ```
 
-#### `HTMLElementProps`
+#### `CardProps`
 
-Base props for HTML elements.
-Framework bindings should extend this with framework-specific attributes.
+Props for the Card container component (elevated, outlined, or filled surface).
 
 ```typescript
-interface HTMLElementProps extends BaseProps {
-  id?: string
-  title?: string
-  tabIndex?: number
-  role?: string
-  'aria-label'?: string
-  'aria-labelledby'?: string
-  'aria-describedby'?: string
-  'aria-hidden'?: boolean
-  'aria-disabled'?: boolean
-  'aria-expanded'?: boolean
-  'aria-selected'?: boolean
-  'aria-checked'?: boolean | 'mixed'
-  'aria-pressed'?: boolean | 'mixed'
-  'aria-invalid'?: boolean
-  'aria-required'?: boolean
-  'aria-readonly'?: boolean
-  'aria-busy'?: boolean
-  'aria-live'?: 'off' | 'polite' | 'assertive'
-  onClick?: MouseEventHandler
-  onDoubleClick?: MouseEventHandler
-  onMouseEnter?: MouseEventHandler
-  onMouseLeave?: MouseEventHandler
-  onFocus?: FocusEventHandler
-  onBlur?: FocusEventHandler
-  onKeyDown?: KeyboardEventHandler
-  onKeyUp?: KeyboardEventHandler
-  onKeyPress?: KeyboardEventHandler
-}
-```
-
-#### `IconProps`
-
-Props for {@link Icon}.
-
-Extends `SVGProps<SVGSVGElement>` so callers can pass any SVG / HTML
-attribute the underlying `<svg>` accepts, including `data-mol-id`,
-`aria-*`, `role`, event handlers, `style`, etc. — without the
-component needing to enumerate them.
-
-```typescript
-interface IconProps extends Omit<SVGProps<SVGSVGElement>, 'width' | 'height' | 'viewBox' | 'fill'> {
+interface CardProps extends HTMLElementProps {
   /**
-   * Name of the glyph to look up in the bonded icon set. Typed as
-   * {@link IconName} so a typo fails the type-check instead of throwing at
-   * render time; sets with extra glyphs augment `CustomIconNames` in
-   * `@molecule/app-icons` to widen it.
+   * Card content.
    */
-  name: IconName
-  /** Width and height of the rendered SVG in pixels. Defaults to 20. */
-  size?: number
-  /** Class name forwarded to the root `<svg>`. */
-  className?: string
+  children?: Children
+  /**
+   * Card variant.
+   */
+  variant?: 'elevated' | 'outlined' | 'filled'
+  /**
+   * Whether the card is interactive (clickable).
+   */
+  interactive?: boolean
+  /**
+   * Padding size.
+   */
+  padding?: Size | 'none'
 }
 ```
 
-#### `InputElementProps`
+#### `ContainerProps`
 
-Base props for input elements.
+Props for the Container layout component.
 
 ```typescript
-interface InputElementProps extends HTMLElementProps {
-  name?: string
-  value?: string | number | readonly string[]
-  defaultValue?: string | number | readonly string[]
-  placeholder?: string
-  required?: boolean
-  readOnly?: boolean
-  autoFocus?: boolean
-  autoComplete?: string
-  maxLength?: number
-  minLength?: number
-  pattern?: string
-  onChange?: ChangeEventHandler
-  onInput?: FormEventHandler
+interface ContainerProps extends HTMLElementProps {
+  /**
+   * Container content.
+   */
+  children?: Children
+  /**
+   * Maximum width.
+   */
+  maxWidth?: 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'full' | string
+  /**
+   * Whether to center the container.
+   */
+  centered?: boolean
+  /**
+   * Horizontal padding.
+   */
+  paddingX?: Size | string
 }
 ```
 
-#### `InputProps`
+#### `FlexProps`
 
-Props for the Input component (text field, email, password, etc.).
+Flex container props.
 
 ```typescript
-interface InputProps extends InputElementProps {
+interface FlexProps extends HTMLElementProps {
   /**
-   * Input type.
+   * Flex content.
    */
-  type?: InputType
+  children?: Children
   /**
-   * Input size.
+   * Flex direction.
    */
-  size?: Size
+  direction?: 'row' | 'column' | 'row-reverse' | 'column-reverse'
   /**
-   * Horizontal text alignment inside the input (see
-   * {@link InputClassOptions.align}). Defaults to the bond's own style.
+   * Justify content.
    */
-  align?: 'left' | 'center'
+  justify?: 'start' | 'end' | 'center' | 'between' | 'around' | 'evenly'
   /**
-   * Label text.
+   * Align items.
    */
-  label?: string
+  align?: 'start' | 'end' | 'center' | 'baseline' | 'stretch'
   /**
-   * Error message.
+   * Flex wrap.
    */
-  error?: string
+  wrap?: 'wrap' | 'nowrap' | 'wrap-reverse'
   /**
-   * Hint/help text.
+   * Gap between items.
    */
-  hint?: string
+  gap?: Size | string | number
+}
+```
+
+#### `GridProps`
+
+Grid container props.
+
+```typescript
+interface GridProps extends HTMLElementProps {
   /**
-   * Element to display on the left.
+   * Grid content.
    */
-  leftElement?: Children
+  children?: Children
   /**
-   * Element to display on the right.
+   * Number of columns.
    */
-  rightElement?: Children
+  columns?: number | string
   /**
-   * Whether to show a clear button.
+   * Number of rows.
    */
-  clearable?: boolean
+  rows?: number | string
   /**
-   * Called when the clear button is clicked.
+   * Gap between items.
    */
-  onClear?: () => void
+  gap?: Size | string | number
   /**
-   * Accessible label for the clear button.
-   * @default 'Clear'
+   * Column gap.
    */
-  clearLabel?: string
+  columnGap?: Size | string | number
+  /**
+   * Row gap.
+   */
+  rowGap?: Size | string | number
 }
 ```
 
-#### `LanguagePickerProps`
-
-Props for {@link LanguagePicker}.
+#### `SpacerProps`
 
-Extends standard `<button>` attributes so callers can pass any extra
-`data-*`, `aria-*`, event handler, or `style` prop without forking the
-component. The named props let apps customize the trigger label, icon,
-size, and modal heading without spreading attribute concerns.
+Props for the Spacer layout component (adds whitespace between elements).
 
 ```typescript
-interface LanguagePickerProps extends Omit<
-  ButtonHTMLAttributes<HTMLButtonElement>,
-  'aria-label' | 'onClick' | 'type' | 'children'
-> {
-  /** i18n key for the trigger button label / aria-label. Defaults to `'footer.language'`. */
-  labelKey?: string
-  /** Fallback label if the i18n key is missing. Defaults to `'Language'`. */
-  labelDefault?: string
-  /** i18n key for the modal title. Defaults to `'languagePicker.modalTitle'`. */
-  modalTitleKey?: string
-  /** Fallback modal title if the i18n key is missing. Defaults to `'Choose language'`. */
-  modalTitleDefault?: string
-  /** Icon glyph to render before the current locale name. Defaults to `'globe'`. */
-  icon?: IconName
-  /** Pixel size for the rendered icon. Defaults to `16`. */
-  iconSize?: number
+interface SpacerProps extends BaseProps {
   /**
-   * What to render inside the trigger button.
-   *
-   * - `'name'` — globe icon + current locale's native name (e.g. `🌐 English`).
-   *   This is the default; matches the molecule-dev footer pattern.
-   * - `'code'` — globe icon + lowercase locale code (e.g. `🌐 en`). Useful in
-   *   tight chrome where the long native name (e.g. "Bahasa Indonesia") would wrap.
-   * - `'icon'` — globe icon only. Useful in icon-bar headers.
+   * Space size.
    */
-  display?: 'name' | 'code' | 'icon'
-  /** Optional className appended to the trigger button. */
-  className?: string
-  /** Optional render override: receives `{ open }` and replaces the default trigger. */
-  renderTrigger?: (open: () => void) => ReactNode
+  size?: Size | string | number
+  /**
+   * Whether the spacer is horizontal.
+   */
+  horizontal?: boolean
 }
 ```
 
-#### `LoadErrorBannerProps`
+#### `FormProps`
 
-Props for {@link LoadErrorBanner}. Rest props are forwarded to the root
-`<div>`, so they are typed as its attributes.
+Props for the Form component (wraps inputs with submission handling and validation).
 
 ```typescript
-interface LoadErrorBannerProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children'> {
-  /** The primary error line (e.g. the localized "Could not load X."). */
-  message: React.ReactNode
-  /** Secondary line under the message (status code, hint). */
-  detail?: React.ReactNode
+interface FormProps extends FormElementProps {
   /**
-   * Called when Retry is clicked. Return the promise; while pending, the
-   * button is disabled and shows "Retrying…". Omit for a display-only
-   * banner.
+   * Form content.
    */
-  onRetry?: () => void | Promise<void>
-  /** Retry-button label. Falls back to a localized "Retry". */
-  retryLabel?: React.ReactNode
-  /** `data-mol-id` for the retry button (default `load-error-retry`). */
-  retryMolId?: string
-  /** Extra content between message and retry row (e.g. an error code). */
-  children?: React.ReactNode
+  children?: Children
+  /**
+   * Submit handler with form data.
+   */
+  onFormSubmit?: (data: Record<string, unknown>) => void | Promise<void>
+  /**
+   * Whether the form is submitting.
+   */
+  submitting?: boolean
 }
 ```
 
-#### `ModalProps`
+#### `FormFieldProps`
 
-Props for the Modal/Dialog component.
+Form field wrapper props.
 
 ```typescript
-interface ModalProps extends HTMLElementProps {
+interface FormFieldProps extends HTMLElementProps {
   /**
-   * Whether the modal is open.
+   * Field content.
    */
-  open: boolean
+  children?: Children
   /**
-   * Called when the modal should close.
+   * Field label.
    */
-  onClose: () => void
+  label?: string
   /**
-   * Modal title.
+   * Field name.
    */
-  title?: string
+  name?: string
   /**
-   * Modal content.
+   * Error message.
    */
-  children?: Children
+  error?: string
   /**
-   * Modal size.
+   * Hint/help text.
    */
-  size?: ModalSize
+  hint?: string
   /**
-   * Whether to show a close button.
+   * Whether the field is required.
    */
-  showCloseButton?: boolean
+  required?: boolean
+}
+```
+
+#### `AlertProps`
+
+Props for the Alert component.
+
+```typescript
+interface AlertProps extends HTMLElementProps {
   /**
-   * Whether clicking the overlay closes the modal.
+   * Alert content.
    */
-  closeOnOverlayClick?: boolean
+  children?: Children
   /**
-   * Whether pressing Escape closes the modal.
+   * Alert title.
    */
-  closeOnEscape?: boolean
+  title?: string
   /**
-   * Footer content (typically action buttons).
+   * Alert status/type.
    */
-  footer?: Children
+  status?: ColorVariant
   /**
-   * Whether the modal is centered vertically.
+   * Alert variant.
    */
-  centered?: boolean
+  variant?: 'solid' | 'subtle' | 'outline' | 'left-accent'
   /**
-   * Whether to prevent body scroll when open.
+   * Whether the alert is dismissible.
    */
-  preventScroll?: boolean
+  dismissible?: boolean
   /**
-   * Accessible label for the close button.
-   * @default 'Close'
+   * Called when dismissed.
    */
-  closeLabel?: string
+  onDismiss?: () => void
+  /**
+   * Icon to display.
+   */
+  icon?: Children
+  /**
+   * Accessible label for the dismiss button.
+   * @default 'Dismiss'
+   */
+  dismissLabel?: string
 }
 ```
 
-#### `PaginationProps`
+#### `ToastProps`
 
-Props for the Pagination component (page navigation with current page, total, page size, and change callbacks).
+Props for the Toast/notification component.
 
 ```typescript
-interface PaginationProps extends BaseProps {
+interface ToastProps extends HTMLElementProps {
   /**
-   * Current page (1-indexed).
+   * Toast content.
    */
-  page: number
+  children?: Children
   /**
-   * Total number of pages.
+   * Toast title.
    */
-  totalPages: number
+  title?: string
   /**
-   * Page change handler.
+   * Toast description.
    */
-  onChange: (page: number) => void
+  description?: string
   /**
-   * Number of sibling pages to show.
+   * Toast status/type.
    */
-  siblings?: number
+  status?: ColorVariant
   /**
-   * Number of boundary pages to show.
+   * Duration in milliseconds (0 for persistent).
    */
-  boundaries?: number
+  duration?: number
   /**
-   * Pagination size.
+   * Whether the toast is dismissible.
    */
-  size?: Size
+  dismissible?: boolean
   /**
-   * Whether to show first/last buttons.
+   * Called when dismissed.
    */
-  showFirstLast?: boolean
+  onDismiss?: () => void
   /**
-   * Whether to show previous/next buttons.
+   * Toast position.
    */
-  showPrevNext?: boolean
+  position?: 'top' | 'top-right' | 'top-left' | 'bottom' | 'bottom-right' | 'bottom-left'
   /**
-   * Accessible labels for pagination controls.
+   * Accessible label for the close button.
+   * @default 'Close'
    */
-  labels?: {
-    nav?: string
-    first?: string
-    previous?: string
-    next?: string
-    last?: string
-    goToPage?: (page: number) => string
-  }
-}
-```
-
-#### `PanelCloseProviderProps`
-
-Props for {@link PanelCloseProvider}.
-
-```typescript
-interface PanelCloseProviderProps {
-  /** Callback that dismisses the enclosing drawer/modal. */
-  close: () => void
-  /** Panel content that may call {@link usePanelClose}. */
-  children: ReactNode
+  closeLabel?: string
 }
 ```
 
-#### `ProgressProps`
+#### `TabItem`
 
-Props for the Progress component.
+A single tab in a Tabs component.
 
 ```typescript
-interface ProgressProps extends BaseProps {
-  /**
-   * Progress value (0-100).
-   */
-  value: number
-
-  /**
-   * Maximum value.
-   */
-  max?: number
-
+interface TabItem<T = string> {
   /**
-   * Progress size.
+   * Tab value/id.
    */
-  size?: Size
-
+  value: T
   /**
-   * Progress color.
+   * Tab label.
    */
-  color?: ColorVariant
-
+  label: Children
   /**
-   * Whether to show the value label.
+   * Tab content.
    */
-  showValue?: boolean
-
+  content?: Children
   /**
-   * Accessible label.
+   * Whether the tab is disabled.
    */
-  label?: string
-
+  disabled?: boolean
   /**
-   * Whether the progress is indeterminate.
+   * Icon to display.
    */
-  indeterminate?: boolean
+  icon?: Children
 }
 ```
 
-#### `PromptDialogProps`
+#### `TabsProps`
 
-Props for {@link PromptDialog}.
+Props for the Tabs component (switchable tabbed content panels).
 
 ```typescript
-interface PromptDialogProps {
-  /** Whether the dialog is open. */
-  open: boolean
-  /** Called when the dialog should close (escape, backdrop, cancel, or a fulfilled {@link PromptDialogProps.onSubmit}). */
-  onClose: () => void
-  /** Dialog heading. */
-  title: React.ReactNode
-  /** Explanatory line under the title. */
-  description?: React.ReactNode
-  /** Input placeholder. */
-  placeholder?: string
-  /** Value the input starts from every time the dialog opens. */
-  initialValue?: string
+interface TabsProps<T = string> extends BaseProps {
   /**
-   * Called with the entered value on confirm. Resolve to close the dialog;
-   * reject or throw to keep it open (show the error via {@link PromptDialogProps.children}).
+   * Tab items.
    */
-  onSubmit: (value: string) => void | Promise<void>
-  /** Confirm-button label. Falls back to a localized "Confirm". */
-  confirmLabel?: React.ReactNode
-  /** Cancel-button label. Falls back to a localized "Cancel". */
-  cancelLabel?: React.ReactNode
-  /** Render the confirm button in the error color (e.g. an irreversible reset). */
-  destructive?: boolean
-  /** `data-mol-id` for the text input. */
-  inputMolId?: string
-  /** `data-mol-id` for the confirm button. */
-  confirmMolId?: string
-  /** `data-mol-id` for the cancel button. */
-  cancelMolId?: string
-  /** Extra body content under the input (error banners, hints). */
-  children?: React.ReactNode
-}
-```
-
-#### `RadioGroupProps`
-
-Props for the RadioGroup component.
-
-```typescript
-interface RadioGroupProps<T = string> extends BaseProps {
+  items: TabItem<T>[]
   /**
-   * Radio options.
+   * Current active tab.
    */
-  options: RadioOption<T>[]
+  value?: T
   /**
-   * Current value.
+   * Default active tab.
    */
-  value?: T
+  defaultValue?: T
   /**
    * Change handler.
    */
   onChange?: (value: T) => void
   /**
-   * Radio size.
-   */
-  size?: Size
-  /**
-   * Group label.
-   */
-  label?: string
-  /**
-   * Shared `name` attribute for the group's radio inputs (used for native
-   * form submission). When omitted, a unique per-instance name is generated
-   * so separate groups never merge — the visible `label` is deliberately
-   * NOT used as the name, because two groups with the same label (e.g. two
-   * "Size" pickers) would otherwise form ONE native radio group and
-   * deselect each other.
+   * Tab variant.
    */
-  name?: string
+  variant?: 'line' | 'enclosed' | 'soft-rounded' | 'solid-rounded'
   /**
-   * Layout direction.
+   * Tab size.
    */
-  direction?: 'horizontal' | 'vertical'
+  size?: Size
   /**
-   * Error message.
+   * Whether tabs are fitted (take full width).
    */
-  error?: string
+  fitted?: boolean
 }
 ```
 
-#### `RadioOption`
+#### `AccordionItem`
 
-A single option in a RadioGroup.
+A single item in an Accordion component.
 
 ```typescript
-interface RadioOption<T = string> {
+interface AccordionItem<T = string> {
   /**
-   * Option value.
+   * Item value/id.
    */
   value: T
   /**
-   * Display label.
+   * Item header/trigger.
    */
-  label: Children
+  header: Children
   /**
-   * Whether the option is disabled.
+   * Item content.
+   */
+  content: Children
+  /**
+   * Whether the item is disabled.
    */
   disabled?: boolean
 }
 ```
 
-#### `ResponsiveAppShellContentProps`
+#### `AccordionProps`
 
-Props for the {@link ResponsiveAppShellContent} sub-component.
-
-```typescript
-interface ResponsiveAppShellContentProps {
-  /** The routed page content — typically an `<Outlet />`. */
-  children: ReactNode
-  /** Extra classes on the `<main>`. */
-  className?: string
-  /** Inline styles on the `<main>` (rarely needed — layout is owned). */
-  style?: React.CSSProperties
-  /** `data-mol-id` override. Default: `'shell-content'`. */
-  dataMolId?: string
-  /** `data-testid` override. */
-  testId?: string
-}
-```
-
-#### `ResponsiveAppShellDrawerProps`
-
-Props for the {@link ResponsiveAppShellDrawer} sub-component.
+Props for the Accordion component.
 
 ```typescript
-interface ResponsiveAppShellDrawerProps {
+interface AccordionProps<T = string> extends BaseProps {
   /**
-   * Nav content — the links, same as (or adapted from) the Sidebar's. Only
-   * mounted while the drawer is open on a below-breakpoint viewport.
+   * Accordion items.
    */
-  children: ReactNode
+  items: AccordionItem<T>[]
   /**
-   * Header row content (typically the brand), rendered next to the close
-   * button.
+   * Expanded item(s).
    */
-  header?: ReactNode
+  value?: T | T[]
   /**
-   * Accessible name for the dialog and its `<nav>` landmark. Defaults to the
-   * `appShell.primaryNav` translation (English fallback `"Primary
-   * navigation"`).
+   * Default expanded item(s).
    */
-  navLabel?: string
-  /** Below-nav content (user card, sign-out), after the `<nav>`. */
-  footer?: ReactNode
-  /** Whether the panel shows a close (X) button. Default: `true`. */
-  showCloseButton?: boolean
-  /** Extra classes on the dialog panel. */
-  className?: string
-  /** `data-mol-id` override for the panel. Default: `'shell-drawer'`. */
-  dataMolId?: string
-  /** `data-mol-id` override for the close button. Default: `'shell-drawer-close'`. */
-  closeDataMolId?: string
-  /** `data-testid` override for the panel. */
-  testId?: string
-}
-```
-
-#### `ResponsiveAppShellProps`
-
-Props for the {@link ResponsiveAppShell} root.
-
-```typescript
-interface ResponsiveAppShellProps {
+  defaultValue?: T | T[]
   /**
-   * The shell sub-components — `<ResponsiveAppShell.TopBar />`,
-   * `<ResponsiveAppShell.Sidebar />`, `<ResponsiveAppShell.Drawer />` and
-   * `<ResponsiveAppShell.Content />`.
+   * Change handler.
    */
-  children: ReactNode
+  onChange?: (value: T | T[]) => void
   /**
-   * Sidebar (and drawer) width: `'sm'` (208px), `'md'` (240px, default),
-   * `'lg'` (256px) or an exact pixel number.
+   * Whether multiple items can be expanded.
    */
-  sidebarWidth?: ShellSidebarWidth
-  /** Extra classes on the root flex-row container. */
-  className?: string
+  multiple?: boolean
   /**
-   * `data-mol-id` for the root container. Defaults to `'shell-root'`.
+   * Whether items can be collapsed.
    */
-  dataMolId?: string
+  collapsible?: boolean
 }
 ```
 
-#### `ResponsiveAppShellSidebarProps`
+#### `TableColumn`
 
-Props for the {@link ResponsiveAppShellSidebar} sub-component.
+Table column definition.
 
 ```typescript
-interface ResponsiveAppShellSidebarProps {
+interface TableColumn<T> {
   /**
-   * Nav content — the links (they land inside the sidebar's `<nav>` landmark;
-   * pass `aria-current="page"` from the active one yourself). Typically the
-   * SAME element variable the Drawer receives, so only the mounted
-   * breakpoint's copy ever instantiates.
+   * Column key (data property).
    */
-  children: ReactNode
+  key: keyof T | string
   /**
-   * Accessible name for the sidebar's `<nav>` landmark. Defaults to the
-   * `appShell.primaryNav` translation (English fallback `"Primary
-   * navigation"`).
+   * Column header.
    */
-  navLabel?: string
+  header: Children
   /**
-   * Below-nav content (user card, quick action) — rendered after the `<nav>`
-   * in a bordered footer row, so it does not sit inside the nav landmark.
+   * Custom cell renderer.
    */
-  footer?: ReactNode
-  /** Extra classes on the `<aside>`. */
-  className?: string
-  /** `data-mol-id` override. Default: `'shell-sidebar'`. */
-  dataMolId?: string
-  /** `data-testid` override. */
-  testId?: string
-}
-```
-
-#### `ResponsiveAppShellTopBarProps`
-
-Props for the {@link ResponsiveAppShellTopBar} sub-component.
-
-```typescript
-interface ResponsiveAppShellTopBarProps {
+  render?: (value: unknown, row: T, index: number) => Children
   /**
-   * Brand/title node, rendered after the menu trigger — typically a
-   * `<Link to="/…">` with the app name or logo. The shell wraps it in a
-   * flex row; style the node itself.
+   * Column width.
    */
-  brand?: ReactNode
-  /** Trailing actions — user menu, theme toggle, search, etc. */
-  actions?: ReactNode
+  width?: string | number
   /**
-   * Render the top bar only below the breakpoint (mount-conditioned, not
-   * CSS-hidden — no dead DOM on desktop). For apps whose desktop shell has
-   * no top bar (e.g. the sidebar carries everything). Default: `false`
-   * (top bar on every breakpoint).
+   * Whether the column is sortable.
    */
-  mobileOnly?: boolean
-  /** Extra classes on the `<header>`. */
-  className?: string
-  /** `data-mol-id` override. Default: `'shell-topbar'`. */
-  dataMolId?: string
-  /** `data-testid` override. */
-  testId?: string
-}
-```
-
-#### `SelectElementProps`
-
-Base props for select elements.
-
-```typescript
-interface SelectElementProps extends HTMLElementProps {
-  name?: string
-  required?: boolean
-  autoFocus?: boolean
-  multiple?: boolean
-  onChange?: ChangeEventHandler
+  sortable?: boolean
+  /**
+   * Text alignment.
+   */
+  align?: 'left' | 'center' | 'right'
 }
 ```
 
-#### `SelectOption`
+#### `TableProps`
 
-A single option in a Select dropdown.
+Props for the Table component.
 
 ```typescript
-interface SelectOption<T = string> {
-  /**
-   * Option value.
-   */
-  value: T
+interface TableProps<T> extends HTMLElementProps {
   /**
-   * Display label.
+   * Table data.
    */
-  label: string
+  data: T[]
   /**
-   * Whether the option is disabled.
+   * Column definitions.
    */
-  disabled?: boolean
+  columns: TableColumn<T>[]
   /**
-   * Option group (for grouped selects).
+   * Row key extractor.
    */
-  group?: string
-}
-```
-
-#### `SelectProps`
-
-Props for the Select dropdown component (single or multi-select).
-
-```typescript
-interface SelectProps<T = string> extends SelectElementProps {
+  rowKey?: keyof T | ((row: T) => string | number)
   /**
-   * Select options.
+   * Whether to show borders.
    */
-  options: SelectOption<T>[]
+  bordered?: boolean
   /**
-   * Current value.
+   * Whether rows are striped.
    */
-  value?: T
+  striped?: boolean
   /**
-   * Change handler (with typed value).
+   * Whether rows are hoverable.
    */
-  onValueChange?: (value: T) => void
+  hoverable?: boolean
   /**
-   * Select size.
+   * Table size.
    */
   size?: Size
   /**
-   * Label text.
+   * Empty state content.
    */
-  label?: string
+  emptyContent?: Children
   /**
-   * Placeholder text.
+   * Loading state.
    */
-  placeholder?: string
+  loading?: boolean
   /**
-   * Error message.
+   * Sort configuration.
    */
-  error?: string
+  sort?: {
+    key: string
+    direction: 'asc' | 'desc'
+  }
   /**
-   * Hint/help text.
+   * Sort change handler.
    */
-  hint?: string
+  onSort?: (key: string, direction: 'asc' | 'desc') => void
   /**
-   * Whether to allow clearing the selection.
+   * Row click handler.
    */
-  clearable?: boolean
+  onRowClick?: (row: T, index: number) => void
 }
 ```
 
-#### `SeparatorProps`
+#### `PaginationProps`
 
-Props for the Separator component.
+Props for the Pagination component (page navigation with current page, total, page size, and change callbacks).
 
 ```typescript
-interface SeparatorProps extends BaseProps {
+interface PaginationProps extends BaseProps {
   /**
-   * Orientation of the separator.
+   * Current page (1-indexed).
    */
-  orientation?: 'horizontal' | 'vertical'
-
+  page: number
   /**
-   * Decorative separators are purely visual.
+   * Total number of pages.
    */
-  decorative?: boolean
-}
-```
-
-#### `SidebarUserCardProps`
-
-Props for the {@link SidebarUserCard} component.
-
-Extends standard `<button>` attributes so callers can pass extra
-`data-*`, `aria-*`, `style`, or event handler props onto the trigger
-button without forking. The named props below cover the common
-customization points.
-
-```typescript
-interface SidebarUserCardProps extends Omit<
-  ButtonHTMLAttributes<HTMLButtonElement>,
-  'aria-label' | 'onClick' | 'children'
-> {
+  totalPages: number
   /**
-   * Panel content shown inside the drawer/modal (typically the app's
-   * `SettingsPanel`). It can dismiss the drawer by calling
-   * `usePanelClose()` — no `onClose` prop-threading required.
+   * Page change handler.
    */
-  children: ReactNode
+  onChange: (page: number) => void
   /**
-   * Display name override. When omitted, falls back to
-   * `useAuth().user?.name`, then `email`, then a guest label.
+   * Number of sibling pages to show.
    */
-  name?: string
+  siblings?: number
   /**
-   * Secondary line under the name (role, plan, status, etc.).
-   * Apps typically pass something like `t('sidebar.memberStatus', {}, { defaultValue: 'Premium Member' })`.
-   * When omitted and the auth user has an email, the email is shown instead.
+   * Number of boundary pages to show.
    */
-  secondaryLine?: string
-  /** Optional avatar image URL — overrides `useAuth().user?.avatarUrl`. */
-  avatarUrl?: string
-  /** i18n key for the trigger button's aria-label. Default: `'sidebarUserCard.open'`. */
-  ariaLabelKey?: string
-  /** Fallback aria-label if the i18n key is missing. Default: `'Open account menu'`. */
-  ariaLabelDefault?: string
+  boundaries?: number
   /**
-   * `data-mol-id` for the trigger button. Defaults to
-   * `'sidebar-user-card'`. Pass a different value (e.g. `'user-menu'`)
-   * to disambiguate or align with an app's existing e2e selectors.
+   * Pagination size.
    */
-  dataMolId?: string
+  size?: Size
+  /**
+   * Whether to show first/last buttons.
+   */
+  showFirstLast?: boolean
+  /**
+   * Whether to show previous/next buttons.
+   */
+  showPrevNext?: boolean
+  /**
+   * Accessible labels for pagination controls.
+   */
+  labels?: {
+    nav?: string
+    first?: string
+    previous?: string
+    next?: string
+    last?: string
+    goToPage?: (page: number) => string
+  }
 }
 ```
 
@@ -1476,290 +1316,530 @@ interface SkeletonProps extends BaseProps {
 }
 ```
 
-#### `SpacerProps`
+#### `AuthGuardProps`
 
-Props for the Spacer layout component (adds whitespace between elements).
+Props for {@link AuthGuard}.
+
+All props are optional — the default behavior (loading tag → redirect
+to `/login` → `<Outlet />`) matches the bare-bones guard apps were
+shipping locally. The props let apps customize per-call without
+forking the component.
 
 ```typescript
-interface SpacerProps extends BaseProps {
+interface AuthGuardProps {
   /**
-   * Space size.
+   * Element rendered while `useAuth().state.initialized` is `false`.
+   * Overrides the default `<div data-mol-id="auth-guard-loading">…</div>`
+   * loading tag — pass a full-page spinner or any other UI you want
+   * during the auth bootstrap window.
    */
-  size?: Size | string | number
+  loadingFallback?: ReactNode
   /**
-   * Whether the spacer is horizontal.
+   * i18n key used for the default loading-tag text. Defaults to
+   * `'common.loading'`. Ignored when `loadingFallback` is set.
    */
-  horizontal?: boolean
-}
-```
-
-#### `SpinnerProps`
-
-Props for the Spinner/loading indicator component.
-
-```typescript
-interface SpinnerProps extends BaseProps {
+  loadingKey?: string
   /**
-   * Spinner size.
+   * Fallback text if the i18n key is missing. Defaults to `'Loading...'`
+   * (the project-canonical ASCII glyph — Phase C of the locale
+   * canonicalization plan). Ignored when `loadingFallback` is set.
    */
-  size?: Size
+  loadingDefault?: string
   /**
-   * Spinner color.
+   * Path to redirect to when the user is not authenticated. Defaults to
+   * `'/login'`. The current `useLocation()` is preserved as `state.from`
+   * for post-login restoration.
    */
-  color?: ColorVariant | string
+  loginPath?: string
   /**
-   * Loading label (for accessibility).
+   * Callback invoked when `isAuthenticated` transitions to `true` (or is
+   * already `true` on first render). Useful for one-shot per-app
+   * bootstrap effects (e.g. seeding fixture data). The caller is
+   * responsible for idempotency if the auth state can flip back and
+   * forth — this fires on every transition.
    */
-  label?: string
+  onAuthenticated?: () => void
   /**
-   * Spinner thickness.
+   * Children to render when authenticated. Defaults to `<Outlet />`,
+   * which is the React Router pattern this guard is designed for.
    */
-  thickness?: number
+  children?: ReactNode
 }
 ```
 
-#### `SwitchProps`
+#### `ConfirmButtonProps`
 
-Props for the Switch/Toggle component.
+Props for {@link ConfirmButton}.
 
 ```typescript
-interface SwitchProps extends InputElementProps {
-  /**
-   * Switch label.
-   */
-  label?: Children
-  /**
-   * Whether the switch is on.
-   */
-  checked?: boolean
+interface ConfirmButtonProps extends Omit<
+  ButtonProps,
+  'onClick' | 'children' | 'onConfirm' | keyof React.DOMAttributes<HTMLButtonElement>
+> {
   /**
-   * Switch size.
+   * Fired ONLY on the confirming (second) click — i.e. when the action
+   * actually commits. Errors should be handled by the caller (render an
+   * inline banner); while the returned promise is pending the button stays
+   * in its confirming state and ignores further clicks.
    */
-  size?: Size
+  onConfirm: () => void | Promise<void>
   /**
-   * Color when on.
+   * Visible label in the idle (armed-to-be-clicked) state.
    */
-  color?: ColorVariant
-}
-```
-
-#### `TabItem`
-
-A single tab in a Tabs component.
-
-```typescript
-interface TabItem<T = string> {
+  label: React.ReactNode
   /**
-   * Tab value/id.
+   * Visible label in the armed state — the "click again to confirm" step.
+   * Defaults to a localized "Confirm?" via the i18n bond.
    */
-  value: T
+  confirmLabel?: React.ReactNode
   /**
-   * Tab label.
+   * Visible label while {@link onConfirm} is pending. Defaults to a
+   * localized "Working…".
    */
-  label: Children
+  pendingLabel?: React.ReactNode
   /**
-   * Tab content.
+   * Seconds before the armed state auto-disarms back to idle. Low-stakes
+   * actions tolerate a long window; destructive ones should keep it short.
+   * `0` disables auto-disarm (not recommended — a stray click then leaves
+   * the button armed forever).
    */
-  content?: Children
+  disarmSeconds?: number
   /**
-   * Whether the tab is disabled.
+   * Disable the control entirely (idle and confirming states).
    */
   disabled?: boolean
   /**
-   * Icon to display.
+   * data-mol-id for the button (all states share one element).
    */
-  icon?: Children
+  testId?: string
 }
 ```
 
-#### `TableColumn`
+#### `ConfirmDialogProps`
 
-Table column definition.
+Props for {@link ConfirmDialog}.
 
 ```typescript
-interface TableColumn<T> {
-  /**
-   * Column key (data property).
-   */
-  key: keyof T | string
-  /**
-   * Column header.
-   */
-  header: Children
-  /**
-   * Custom cell renderer.
-   */
-  render?: (value: unknown, row: T, index: number) => Children
-  /**
-   * Column width.
-   */
-  width?: string | number
-  /**
-   * Whether the column is sortable.
-   */
-  sortable?: boolean
-  /**
-   * Text alignment.
-   */
-  align?: 'left' | 'center' | 'right'
+interface ConfirmDialogProps {
+  /** Whether the dialog is open. */
+  open: boolean
+  /** Called when the dialog should close (escape, backdrop, cancel). */
+  onClose: () => void
+  /** Title. */
+  title: ReactNode
+  /** Body / warning text. */
+  description: ReactNode
+  /** Confirm-button label (e.g. "Delete"). */
+  confirmLabel?: ReactNode
+  /** Cancel-button label. */
+  cancelLabel?: ReactNode
+  /** Called when the user confirms. */
+  onConfirm: () => void | Promise<void>
+  /** Is the confirm action destructive? Defaults to true. */
+  destructive?: boolean
+  /** Extra body content between description and footer. */
+  children?: ReactNode
+  /** Disables both buttons. Set it yourself while your `onConfirm` promise is pending — the dialog does not track it and does not auto-close. */
+  loading?: boolean
 }
 ```
 
-#### `TableProps`
+#### `IconProps`
 
-Props for the Table component.
+Props for {@link Icon}.
+
+Extends `SVGProps<SVGSVGElement>` so callers can pass any SVG / HTML
+attribute the underlying `<svg>` accepts, including `data-mol-id`,
+`aria-*`, `role`, event handlers, `style`, etc. — without the
+component needing to enumerate them.
 
 ```typescript
-interface TableProps<T> extends HTMLElementProps {
-  /**
-   * Table data.
-   */
-  data: T[]
-  /**
-   * Column definitions.
-   */
-  columns: TableColumn<T>[]
-  /**
-   * Row key extractor.
-   */
-  rowKey?: keyof T | ((row: T) => string | number)
-  /**
-   * Whether to show borders.
-   */
-  bordered?: boolean
-  /**
-   * Whether rows are striped.
-   */
-  striped?: boolean
-  /**
-   * Whether rows are hoverable.
-   */
-  hoverable?: boolean
+interface IconProps extends Omit<SVGProps<SVGSVGElement>, 'width' | 'height' | 'viewBox' | 'fill'> {
   /**
-   * Table size.
+   * Name of the glyph to look up in the bonded icon set. Typed as
+   * {@link IconName} so a typo fails the type-check instead of throwing at
+   * render time; sets with extra glyphs augment `CustomIconNames` in
+   * `@molecule/app-icons` to widen it.
    */
-  size?: Size
-  /**
-   * Empty state content.
+  name: IconName
+  /** Width and height of the rendered SVG in pixels. Defaults to 20. */
+  size?: number
+  /** Class name forwarded to the root `<svg>`. */
+  className?: string
+}
+```
+
+#### `LanguagePickerProps`
+
+Props for {@link LanguagePicker}.
+
+Extends standard `<button>` attributes so callers can pass any extra
+`data-*`, `aria-*`, event handler, or `style` prop without forking the
+component. The named props let apps customize the trigger label, icon,
+size, and modal heading without spreading attribute concerns.
+
+```typescript
+interface LanguagePickerProps extends Omit<
+  ButtonHTMLAttributes<HTMLButtonElement>,
+  'aria-label' | 'onClick' | 'type' | 'children'
+> {
+  /** i18n key for the trigger button label / aria-label. Defaults to `'footer.language'`. */
+  labelKey?: string
+  /** Fallback label if the i18n key is missing. Defaults to `'Language'`. */
+  labelDefault?: string
+  /** i18n key for the modal title. Defaults to `'languagePicker.modalTitle'`. */
+  modalTitleKey?: string
+  /** Fallback modal title if the i18n key is missing. Defaults to `'Choose language'`. */
+  modalTitleDefault?: string
+  /** Icon glyph to render before the current locale name. Defaults to `'globe'`. */
+  icon?: IconName
+  /** Pixel size for the rendered icon. Defaults to `16`. */
+  iconSize?: number
+  /**
+   * What to render inside the trigger button.
+   *
+   * - `'name'` — globe icon + current locale's native name (e.g. `🌐 English`).
+   *   This is the default; matches the molecule-dev footer pattern.
+   * - `'code'` — globe icon + lowercase locale code (e.g. `🌐 en`). Useful in
+   *   tight chrome where the long native name (e.g. "Bahasa Indonesia") would wrap.
+   * - `'icon'` — globe icon only. Useful in icon-bar headers.
    */
-  emptyContent?: Children
+  display?: 'name' | 'code' | 'icon'
+  /** Optional className appended to the trigger button. */
+  className?: string
+  /** Optional render override: receives `{ open }` and replaces the default trigger. */
+  renderTrigger?: (open: () => void) => ReactNode
+}
+```
+
+#### `LoadErrorBannerProps`
+
+Props for {@link LoadErrorBanner}. Rest props are forwarded to the root
+`<div>`, so they are typed as its attributes.
+
+```typescript
+interface LoadErrorBannerProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children'> {
+  /** The primary error line (e.g. the localized "Could not load X."). */
+  message: React.ReactNode
+  /** Secondary line under the message (status code, hint). */
+  detail?: React.ReactNode
   /**
-   * Loading state.
+   * Called when Retry is clicked. Return the promise; while pending, the
+   * button is disabled and shows "Retrying…". Omit for a display-only
+   * banner.
    */
-  loading?: boolean
+  onRetry?: () => void | Promise<void>
+  /** Retry-button label. Falls back to a localized "Retry". */
+  retryLabel?: React.ReactNode
+  /** `data-mol-id` for the retry button (default `load-error-retry`). */
+  retryMolId?: string
+  /** Extra content between message and retry row (e.g. an error code). */
+  children?: React.ReactNode
+}
+```
+
+#### `PanelCloseProviderProps`
+
+Props for {@link PanelCloseProvider}.
+
+```typescript
+interface PanelCloseProviderProps {
+  /** Callback that dismisses the enclosing drawer/modal. */
+  close: () => void
+  /** Panel content that may call {@link usePanelClose}. */
+  children: ReactNode
+}
+```
+
+#### `ProgressProps`
+
+Props for the Progress component.
+
+```typescript
+interface ProgressProps extends BaseProps {
   /**
-   * Sort configuration.
+   * Progress value (0-100).
    */
-  sort?: {
-    key: string
-    direction: 'asc' | 'desc'
-  }
+  value: number
+
   /**
-   * Sort change handler.
+   * Maximum value.
    */
-  onSort?: (key: string, direction: 'asc' | 'desc') => void
+  max?: number
+
   /**
-   * Row click handler.
+   * Progress size.
    */
-  onRowClick?: (row: T, index: number) => void
+  size?: Size
+
+  /**
+   * Progress color.
+   */
+  color?: ColorVariant
+
+  /**
+   * Whether to show the value label.
+   */
+  showValue?: boolean
+
+  /**
+   * Accessible label.
+   */
+  label?: string
+
+  /**
+   * Whether the progress is indeterminate.
+   */
+  indeterminate?: boolean
 }
 ```
 
-#### `TabsProps`
+#### `PromptDialogProps`
 
-Props for the Tabs component (switchable tabbed content panels).
+Props for {@link PromptDialog}.
 
 ```typescript
-interface TabsProps<T = string> extends BaseProps {
+interface PromptDialogProps {
+  /** Whether the dialog is open. */
+  open: boolean
+  /** Called when the dialog should close (escape, backdrop, cancel, or a fulfilled {@link PromptDialogProps.onSubmit}). */
+  onClose: () => void
+  /** Dialog heading. */
+  title: React.ReactNode
+  /** Explanatory line under the title. */
+  description?: React.ReactNode
+  /** Input placeholder. */
+  placeholder?: string
+  /** Value the input starts from every time the dialog opens. */
+  initialValue?: string
   /**
-   * Tab items.
+   * Called with the entered value on confirm. Resolve to close the dialog;
+   * reject or throw to keep it open (show the error via {@link PromptDialogProps.children}).
    */
-  items: TabItem<T>[]
+  onSubmit: (value: string) => void | Promise<void>
+  /** Confirm-button label. Falls back to a localized "Confirm". */
+  confirmLabel?: React.ReactNode
+  /** Cancel-button label. Falls back to a localized "Cancel". */
+  cancelLabel?: React.ReactNode
+  /** Render the confirm button in the error color (e.g. an irreversible reset). */
+  destructive?: boolean
+  /** `data-mol-id` for the text input. */
+  inputMolId?: string
+  /** `data-mol-id` for the confirm button. */
+  confirmMolId?: string
+  /** `data-mol-id` for the cancel button. */
+  cancelMolId?: string
+  /** Extra body content under the input (error banners, hints). */
+  children?: React.ReactNode
+}
+```
+
+#### `ResponsiveAppShellProps`
+
+Props for the {@link ResponsiveAppShell} root.
+
+```typescript
+interface ResponsiveAppShellProps {
   /**
-   * Current active tab.
+   * The shell sub-components — `<ResponsiveAppShell.TopBar />`,
+   * `<ResponsiveAppShell.Sidebar />`, `<ResponsiveAppShell.Drawer />` and
+   * `<ResponsiveAppShell.Content />`.
    */
-  value?: T
+  children: ReactNode
   /**
-   * Default active tab.
+   * Sidebar (and drawer) width: `'sm'` (208px), `'md'` (240px, default),
+   * `'lg'` (256px) or an exact pixel number.
    */
-  defaultValue?: T
+  sidebarWidth?: ShellSidebarWidth
+  /** Extra classes on the root flex-row container. */
+  className?: string
   /**
-   * Change handler.
+   * `data-mol-id` for the root container. Defaults to `'shell-root'`.
    */
-  onChange?: (value: T) => void
+  dataMolId?: string
+}
+```
+
+#### `ResponsiveAppShellTopBarProps`
+
+Props for the {@link ResponsiveAppShellTopBar} sub-component.
+
+```typescript
+interface ResponsiveAppShellTopBarProps {
   /**
-   * Tab variant.
+   * Brand/title node, rendered after the menu trigger — typically a
+   * `<Link to="/…">` with the app name or logo. The shell wraps it in a
+   * flex row; style the node itself.
    */
-  variant?: 'line' | 'enclosed' | 'soft-rounded' | 'solid-rounded'
+  brand?: ReactNode
+  /** Trailing actions — user menu, theme toggle, search, etc. */
+  actions?: ReactNode
   /**
-   * Tab size.
+   * Render the top bar only below the breakpoint (mount-conditioned, not
+   * CSS-hidden — no dead DOM on desktop). For apps whose desktop shell has
+   * no top bar (e.g. the sidebar carries everything). Default: `false`
+   * (top bar on every breakpoint).
    */
-  size?: Size
+  mobileOnly?: boolean
+  /** Extra classes on the `<header>`. */
+  className?: string
+  /** `data-mol-id` override. Default: `'shell-topbar'`. */
+  dataMolId?: string
+  /** `data-testid` override. */
+  testId?: string
+}
+```
+
+#### `ResponsiveAppShellSidebarProps`
+
+Props for the {@link ResponsiveAppShellSidebar} sub-component.
+
+```typescript
+interface ResponsiveAppShellSidebarProps {
   /**
-   * Whether tabs are fitted (take full width).
+   * Nav content — the links (they land inside the sidebar's `<nav>` landmark;
+   * pass `aria-current="page"` from the active one yourself). Typically the
+   * SAME element variable the Drawer receives, so only the mounted
+   * breakpoint's copy ever instantiates.
    */
-  fitted?: boolean
+  children: ReactNode
+  /**
+   * Accessible name for the sidebar's `<nav>` landmark. Defaults to the
+   * `appShell.primaryNav` translation (English fallback `"Primary
+   * navigation"`).
+   */
+  navLabel?: string
+  /**
+   * Below-nav content (user card, quick action) — rendered after the `<nav>`
+   * in a bordered footer row, so it does not sit inside the nav landmark.
+   */
+  footer?: ReactNode
+  /** Extra classes on the `<aside>`. */
+  className?: string
+  /** `data-mol-id` override. Default: `'shell-sidebar'`. */
+  dataMolId?: string
+  /** `data-testid` override. */
+  testId?: string
 }
 ```
 
-#### `TextareaElementProps`
+#### `ResponsiveAppShellDrawerProps`
 
-Base props for textarea elements.
+Props for the {@link ResponsiveAppShellDrawer} sub-component.
 
 ```typescript
-interface TextareaElementProps extends HTMLElementProps {
-  name?: string
-  value?: string
-  defaultValue?: string
-  placeholder?: string
-  required?: boolean
-  readOnly?: boolean
-  autoFocus?: boolean
-  rows?: number
-  cols?: number
-  maxLength?: number
-  minLength?: number
-  wrap?: 'hard' | 'soft' | 'off'
-  onChange?: ChangeEventHandler
-  onInput?: FormEventHandler
+interface ResponsiveAppShellDrawerProps {
+  /**
+   * Nav content — the links, same as (or adapted from) the Sidebar's. Only
+   * mounted while the drawer is open on a below-breakpoint viewport.
+   */
+  children: ReactNode
+  /**
+   * Header row content (typically the brand), rendered next to the close
+   * button.
+   */
+  header?: ReactNode
+  /**
+   * Accessible name for the dialog and its `<nav>` landmark. Defaults to the
+   * `appShell.primaryNav` translation (English fallback `"Primary
+   * navigation"`).
+   */
+  navLabel?: string
+  /** Below-nav content (user card, sign-out), after the `<nav>`. */
+  footer?: ReactNode
+  /** Whether the panel shows a close (X) button. Default: `true`. */
+  showCloseButton?: boolean
+  /** Extra classes on the dialog panel. */
+  className?: string
+  /** `data-mol-id` override for the panel. Default: `'shell-drawer'`. */
+  dataMolId?: string
+  /** `data-mol-id` override for the close button. Default: `'shell-drawer-close'`. */
+  closeDataMolId?: string
+  /** `data-testid` override for the panel. */
+  testId?: string
+}
+```
+
+#### `ResponsiveAppShellContentProps`
+
+Props for the {@link ResponsiveAppShellContent} sub-component.
+
+```typescript
+interface ResponsiveAppShellContentProps {
+  /** The routed page content — typically an `<Outlet />`. */
+  children: ReactNode
+  /** Extra classes on the `<main>`. */
+  className?: string
+  /** Inline styles on the `<main>` (rarely needed — layout is owned). */
+  style?: React.CSSProperties
+  /** `data-mol-id` override. Default: `'shell-content'`. */
+  dataMolId?: string
+  /** `data-testid` override. */
+  testId?: string
 }
 ```
 
-#### `TextareaProps`
+#### `SeparatorProps`
 
-Props for the Textarea component.
+Props for the Separator component.
 
 ```typescript
-interface TextareaProps extends TextareaElementProps {
-  /**
-   * Text size tier (see {@link TextareaClassOptions.size}) — pass the same
-   * `size` as a neighboring Input for identical font sizes.
-   */
-  size?: Size
+interface SeparatorProps extends BaseProps {
   /**
-   * Label text.
+   * Orientation of the separator.
    */
-  label?: string
+  orientation?: 'horizontal' | 'vertical'
+
   /**
-   * Error message.
+   * Decorative separators are purely visual.
    */
-  error?: string
+  decorative?: boolean
+}
+```
+
+#### `SidebarUserCardProps`
+
+Props for the {@link SidebarUserCard} component.
+
+Extends standard `<button>` attributes so callers can pass extra
+`data-*`, `aria-*`, `style`, or event handler props onto the trigger
+button without forking. The named props below cover the common
+customization points.
+
+```typescript
+interface SidebarUserCardProps extends Omit<
+  ButtonHTMLAttributes<HTMLButtonElement>,
+  'aria-label' | 'onClick' | 'children'
+> {
   /**
-   * Hint/help text.
+   * Panel content shown inside the drawer/modal (typically the app's
+   * `SettingsPanel`). It can dismiss the drawer by calling
+   * `usePanelClose()` — no `onClose` prop-threading required.
    */
-  hint?: string
+  children: ReactNode
   /**
-   * Whether the textarea auto-resizes.
+   * Display name override. When omitted, falls back to
+   * `useAuth().user?.name`, then `email`, then a guest label.
    */
-  autoResize?: boolean
+  name?: string
   /**
-   * Minimum number of rows.
+   * Secondary line under the name (role, plan, status, etc.).
+   * Apps typically pass something like `t('sidebar.memberStatus', {}, { defaultValue: 'Premium Member' })`.
+   * When omitted and the auth user has an email, the email is shown instead.
    */
-  minRows?: number
+  secondaryLine?: string
+  /** Optional avatar image URL — overrides `useAuth().user?.avatarUrl`. */
+  avatarUrl?: string
+  /** i18n key for the trigger button's aria-label. Default: `'sidebarUserCard.open'`. */
+  ariaLabelKey?: string
+  /** Fallback aria-label if the i18n key is missing. Default: `'Open account menu'`. */
+  ariaLabelDefault?: string
   /**
-   * Maximum number of rows.
+   * `data-mol-id` for the trigger button. Defaults to
+   * `'sidebar-user-card'`. Pass a different value (e.g. `'user-menu'`)
+   * to disambiguate or align with an app's existing e2e selectors.
    */
-  maxRows?: number
+  dataMolId?: string
 }
 ```
 
@@ -1790,101 +1870,58 @@ interface ThemeToggleProps extends Omit<
 }
 ```
 
-#### `ToastProps`
-
-Props for the Toast/notification component.
-
-```typescript
-interface ToastProps extends HTMLElementProps {
-  /**
-   * Toast content.
-   */
-  children?: Children
-  /**
-   * Toast title.
-   */
-  title?: string
-  /**
-   * Toast description.
-   */
-  description?: string
-  /**
-   * Toast status/type.
-   */
-  status?: ColorVariant
-  /**
-   * Duration in milliseconds (0 for persistent).
-   */
-  duration?: number
-  /**
-   * Whether the toast is dismissible.
-   */
-  dismissible?: boolean
-  /**
-   * Called when dismissed.
-   */
-  onDismiss?: () => void
-  /**
-   * Toast position.
-   */
-  position?: 'top' | 'top-right' | 'top-left' | 'bottom' | 'bottom-right' | 'bottom-left'
-  /**
-   * Accessible label for the close button.
-   * @default 'Close'
-   */
-  closeLabel?: string
-}
-```
+#### `UserMenuProps`
 
-#### `TooltipProps`
+Props for {@link UserMenu}.
 
-Props for the Tooltip component (hover/focus popover with informational text).
+The inner trigger is a Molecule `<Button>` whose own prop set
+conflicts with raw `ButtonHTMLAttributes` (color, value, size enums),
+so this component exposes a curated set of customization points
+instead of extending HTML attributes. For one-off extra attributes,
+pass them via `dataMolId` / `className` / `style` props.
 
 ```typescript
-interface TooltipProps extends HTMLElementProps {
-  /**
-   * Tooltip content.
-   */
-  content: Children
+interface UserMenuProps {
   /**
-   * Element that triggers the tooltip.
+   * Panel content shown inside the drawer/modal (typically the app's
+   * `SettingsPanel`). It can dismiss the drawer by calling
+   * `usePanelClose()` — no `onClose` prop-threading required.
    */
-  children: Children
+  children: ReactNode
   /**
-   * Tooltip placement.
+   * i18n key for the trigger button's aria-label. Defaults to
+   * `'userMenu.open'`. Apps whose existing locales use a different key
+   * (e.g. `'userMenu.openButton'`) can override.
    */
-  placement?: TooltipPlacement
+  ariaLabelKey?: string
+  /** Fallback aria-label if the i18n key is missing. Defaults to `"Open user menu"`. */
+  ariaLabelDefault?: string
+  /** Icon name for the trigger button. Defaults to `'user'`. */
+  triggerIcon?: IconName
+  /** Pixel size for the trigger icon. Defaults to 20. */
+  triggerIconSize?: number
   /**
-   * Delay before showing (ms).
+   * `data-mol-id` for the trigger button. Defaults to `'user-menu'`.
+   * Pass an explicit value to disambiguate when the same page mounts
+   * more than one UserMenu.
    */
-  delay?: number
+  dataMolId?: string
+  /** Extra className composed onto the trigger button. */
+  className?: string
+  /** Whether the trigger button is disabled. */
+  disabled?: boolean
   /**
-   * Whether the tooltip has an arrow.
+   * Override the trigger button's click handler. When provided, called
+   * instead of opening the panel — hosts use this to intercept the click
+   * (e.g. to open an auth modal for guest users).
    */
-  hasArrow?: boolean
-}
-```
-
-#### `UserMenuPopoverPanelProps`
-
-Props for {@link UserMenuPopoverPanel}.
-
-```typescript
-interface UserMenuPopoverPanelProps {
+  onClick?: () => void
   /**
-   * Panel body — typically a set of `<Link>` nav items and a
-   * `<UserMenuPopoverSignOut />`. Rendered inside a `<nav>` below the
-   * built-in identity header.
+   * Which side of the viewport the panel opens from. Defaults to
+   * `'right'`. Apps whose sidebar trigger sits on the left should pass
+   * `'left'` so the panel opens adjacent to the trigger.
    */
-  children: ReactNode
-  /** Extra className composed onto the absolute-positioned panel. */
-  className?: string
-  /** i18n key for the panel's aria-label. Default: `'userMenu.panelLabel'`. */
-  ariaLabelKey?: string
-  /** Fallback aria-label if the i18n key is missing. Default: `'Account menu'`. */
-  ariaLabelDefault?: string
-  /** `data-mol-id` for the panel. Default: `'user-menu-panel'`. */
-  dataMolId?: string
+  side?: 'left' | 'right'
 }
 ```
 
@@ -1909,23 +1946,6 @@ interface UserMenuPopoverProps {
 }
 ```
 
-#### `UserMenuPopoverSignOutProps`
-
-Props for {@link UserMenuPopoverSignOut}.
-
-```typescript
-interface UserMenuPopoverSignOutProps {
-  /** i18n key for the button label. Default: `'userMenu.signOut'`. */
-  labelKey?: string
-  /** Fallback label if the i18n key is missing. Default: `'Sign out'`. */
-  labelDefault?: string
-  /** `data-mol-id` for the button. Default: `'user-menu-sign-out'`. */
-  dataMolId?: string
-  /** Extra className composed onto the button. */
-  className?: string
-}
-```
-
 #### `UserMenuPopoverTriggerProps`
 
 Props for {@link UserMenuPopoverTrigger}.
@@ -1933,89 +1953,58 @@ Props for {@link UserMenuPopoverTrigger}.
 ```typescript
 interface UserMenuPopoverTriggerProps {
   /** i18n key for the trigger's aria-label. Default: `'userMenu.open'`. */
-  ariaLabelKey?: string
-  /** Fallback aria-label if the i18n key is missing. Default: `'Open user menu'`. */
-  ariaLabelDefault?: string
-  /** `data-mol-id` for the trigger button. Default: `'user-menu'`. */
-  dataMolId?: string
-  /** Extra className composed onto the trigger button. */
-  className?: string
-}
-```
-
-#### `UserMenuProps`
-
-Props for {@link UserMenu}.
-
-The inner trigger is a Molecule `<Button>` whose own prop set
-conflicts with raw `ButtonHTMLAttributes` (color, value, size enums),
-so this component exposes a curated set of customization points
-instead of extending HTML attributes. For one-off extra attributes,
-pass them via `dataMolId` / `className` / `style` props.
-
-```typescript
-interface UserMenuProps {
-  /**
-   * Panel content shown inside the drawer/modal (typically the app's
-   * `SettingsPanel`). It can dismiss the drawer by calling
-   * `usePanelClose()` — no `onClose` prop-threading required.
-   */
-  children: ReactNode
-  /**
-   * i18n key for the trigger button's aria-label. Defaults to
-   * `'userMenu.open'`. Apps whose existing locales use a different key
-   * (e.g. `'userMenu.openButton'`) can override.
-   */
-  ariaLabelKey?: string
-  /** Fallback aria-label if the i18n key is missing. Defaults to `"Open user menu"`. */
-  ariaLabelDefault?: string
-  /** Icon name for the trigger button. Defaults to `'user'`. */
-  triggerIcon?: IconName
-  /** Pixel size for the trigger icon. Defaults to 20. */
-  triggerIconSize?: number
-  /**
-   * `data-mol-id` for the trigger button. Defaults to `'user-menu'`.
-   * Pass an explicit value to disambiguate when the same page mounts
-   * more than one UserMenu.
-   */
+  ariaLabelKey?: string
+  /** Fallback aria-label if the i18n key is missing. Default: `'Open user menu'`. */
+  ariaLabelDefault?: string
+  /** `data-mol-id` for the trigger button. Default: `'user-menu'`. */
   dataMolId?: string
   /** Extra className composed onto the trigger button. */
   className?: string
-  /** Whether the trigger button is disabled. */
-  disabled?: boolean
-  /**
-   * Override the trigger button's click handler. When provided, called
-   * instead of opening the panel — hosts use this to intercept the click
-   * (e.g. to open an auth modal for guest users).
-   */
-  onClick?: () => void
-  /**
-   * Which side of the viewport the panel opens from. Defaults to
-   * `'right'`. Apps whose sidebar trigger sits on the left should pass
-   * `'left'` so the panel opens adjacent to the trigger.
-   */
-  side?: 'left' | 'right'
 }
 ```
 
-### Types
-
-#### `ButtonVariant`
+#### `UserMenuPopoverPanelProps`
 
-Button visual variant styles.
+Props for {@link UserMenuPopoverPanel}.
 
 ```typescript
-type ButtonVariant = 'solid' | 'outline' | 'ghost' | 'link'
+interface UserMenuPopoverPanelProps {
+  /**
+   * Panel body — typically a set of `<Link>` nav items and a
+   * `<UserMenuPopoverSignOut />`. Rendered inside a `<nav>` below the
+   * built-in identity header.
+   */
+  children: ReactNode
+  /** Extra className composed onto the absolute-positioned panel. */
+  className?: string
+  /** i18n key for the panel's aria-label. Default: `'userMenu.panelLabel'`. */
+  ariaLabelKey?: string
+  /** Fallback aria-label if the i18n key is missing. Default: `'Account menu'`. */
+  ariaLabelDefault?: string
+  /** `data-mol-id` for the panel. Default: `'user-menu-panel'`. */
+  dataMolId?: string
+}
 ```
 
-#### `ChangeEventHandler`
+#### `UserMenuPopoverSignOutProps`
 
-Framework-agnostic change event handler.
+Props for {@link UserMenuPopoverSignOut}.
 
 ```typescript
-type ChangeEventHandler = EventHandler<Event>
+interface UserMenuPopoverSignOutProps {
+  /** i18n key for the button label. Default: `'userMenu.signOut'`. */
+  labelKey?: string
+  /** Fallback label if the i18n key is missing. Default: `'Sign out'`. */
+  labelDefault?: string
+  /** `data-mol-id` for the button. Default: `'user-menu-sign-out'`. */
+  dataMolId?: string
+  /** Extra className composed onto the button. */
+  className?: string
+}
 ```
 
+### Types
+
 #### `Children`
 
 Framework-agnostic child content.
@@ -2025,20 +2014,30 @@ Use `unknown` to allow any framework's node type (ReactNode, VNode, etc.).
 type Children = unknown
 ```
 
-#### `ColorVariant`
+#### `EventHandler`
 
-Semantic color variants used across components for status indication.
+Framework-agnostic event handler.
 
 ```typescript
-type ColorVariant = 'primary' | 'secondary' | 'success' | 'warning' | 'error' | 'info'
+type EventHandler<E = Event> = (event: E) => void
 ```
 
-#### `EventHandler`
+- `event` — The DOM event object.
 
-Framework-agnostic event handler.
+#### `MouseEventHandler`
+
+Framework-agnostic mouse event handler.
 
 ```typescript
-type EventHandler<E = Event> = (event: E) => void
+type MouseEventHandler = EventHandler<MouseEvent>
+```
+
+#### `KeyboardEventHandler`
+
+Framework-agnostic keyboard event handler.
+
+```typescript
+type KeyboardEventHandler = EventHandler<KeyboardEvent>
 ```
 
 #### `FocusEventHandler`
@@ -2049,6 +2048,14 @@ Framework-agnostic focus event handler.
 type FocusEventHandler = EventHandler<FocusEvent>
 ```
 
+#### `ChangeEventHandler`
+
+Framework-agnostic change event handler.
+
+```typescript
+type ChangeEventHandler = EventHandler<Event>
+```
+
 #### `FormEventHandler`
 
 Framework-agnostic form event handler.
@@ -2057,6 +2064,30 @@ Framework-agnostic form event handler.
 type FormEventHandler = EventHandler<Event>
 ```
 
+#### `Size`
+
+Standard size scale used across all molecule UI components (buttons, inputs, badges, etc.).
+
+```typescript
+type Size = 'xs' | 'sm' | 'md' | 'lg' | 'xl'
+```
+
+#### `ColorVariant`
+
+Semantic color variants used across components for status indication.
+
+```typescript
+type ColorVariant = 'primary' | 'secondary' | 'success' | 'warning' | 'error' | 'info'
+```
+
+#### `ButtonVariant`
+
+Button visual variant styles.
+
+```typescript
+type ButtonVariant = 'solid' | 'outline' | 'ghost' | 'link'
+```
+
 #### `InputType`
 
 Allowed HTML input type attribute values for the Input component.
@@ -2075,14 +2106,6 @@ type InputType =
   | 'datetime-local'
 ```
 
-#### `KeyboardEventHandler`
-
-Framework-agnostic keyboard event handler.
-
-```typescript
-type KeyboardEventHandler = EventHandler<KeyboardEvent>
-```
-
 #### `ModalSize`
 
 Modal size variants including full-screen.
@@ -2091,12 +2114,13 @@ Modal size variants including full-screen.
 type ModalSize = 'sm' | 'md' | 'lg' | 'xl' | 'full'
 ```
 
-#### `MouseEventHandler`
+#### `TooltipPlacement`
 
-Framework-agnostic mouse event handler.
+Position where a tooltip renders relative to its trigger element (top, bottom, left, right, and corner variants).
 
 ```typescript
-type MouseEventHandler = EventHandler<MouseEvent>
+type TooltipPlacement =
+  'top' | 'bottom' | 'left' | 'right' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end'
 ```
 
 #### `ShellSidebarWidth`
@@ -2112,23 +2136,6 @@ as a token" case).
 type ShellSidebarWidth = 'sm' | 'md' | 'lg' | number
 ```
 
-#### `Size`
-
-Standard size scale used across all molecule UI components (buttons, inputs, badges, etc.).
-
-```typescript
-type Size = 'xs' | 'sm' | 'md' | 'lg' | 'xl'
-```
-
-#### `TooltipPlacement`
-
-Position where a tooltip renders relative to its trigger element (top, bottom, left, right, and corner variants).
-
-```typescript
-type TooltipPlacement =
-  'top' | 'bottom' | 'left' | 'right' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end'
-```
-
 ### Functions
 
 #### `AuthGuard(props)`
@@ -2159,18 +2166,6 @@ function AuthGuard({
 
 - `props` — {@link AuthGuardProps}
 
-#### `cn(inputs)`
-
-Merge class name strings, filtering out falsy values (undefined, null, false).
-
-```typescript
-function cn(inputs?: (string | false | null | undefined)[]): string
-```
-
-- `inputs` — Class name strings or falsy values to be filtered out.
-
-**Returns:** A single space-separated class string.
-
 #### `ConfirmDialog(props)`
 
 Are-you-sure-style confirmation modal for destructive actions.
@@ -2293,6 +2288,19 @@ function PanelCloseProvider({ close, children }: PanelCloseProviderProps): JSX.E
 
 **Returns:** The children wrapped in the close-context provider.
 
+#### `usePanelClose()`
+
+Returns the callback that dismisses the drawer the current panel is
+mounted in. Safe to call anywhere — returns a no-op when no enclosing
+`UserMenu` / `SidebarUserCard` provides one (e.g. a `SettingsPanel`
+rendered as a standalone page).
+
+```typescript
+function usePanelClose(): () => void
+```
+
+**Returns:** A function that closes the enclosing drawer, or a no-op.
+
 #### `PromptDialog(props)`
 
 Modal that asks the user for a short string, replacing `window.prompt`.
@@ -2318,54 +2326,50 @@ function PromptDialog({
 
 - `props` — Component props (see {@link PromptDialogProps}).
 
-#### `ResponsiveAppShellContent(props)`
+#### `useIsDesktop(query)`
 
-The shell's `<main>` landmark. Grows to fill the row and may shrink below
-its content width, so page-level `overflow-x` strips scroll inside the
-page instead of widening the whole shell.
+Whether the viewport is at least 768px wide (the fleet's `md` breakpoint).
+
+Reads `window.matchMedia` synchronously in the state initializer, so the
+FIRST client render is already correct — no mobile-then-desktop swap frame
+(this is time-tracking's QA-hardened version; the naive
+"state starts false, sync in an effect" variant mounts the wrong shell for
+one frame and double-fetches route data on desktop). Subscribes to
+`change` events afterwards. Guarded for non-browser environments
+(SSR/node): returns `false` (the mobile shell) when no `window.matchMedia`
+exists.
 
 ```typescript
-function ResponsiveAppShellContent({
-  children,
-  className,
-  style,
-  dataMolId = 'shell-content',
-  testId,
-}: ResponsiveAppShellContentProps): JSX.Element
+function useIsDesktop(query?: string): boolean
 ```
 
-- `props` — The page content and class/id overrides.
+- `query` — Override the media query. Defaults to `(min-width: 768px)`.
 
-**Returns:** The main landmark.
+**Returns:** Whether the desktop shell should mount.
 
-#### `ResponsiveAppShellDrawer(props)`
+#### `ResponsiveAppShellTopBar(props)`
 
-The mobile nav drawer (<768px): a left-anchored dialog panel over a
-backdrop, opened by the menu trigger the TopBar renders.
+The shell's `<header>` landmark: menu trigger (mobile, when a Drawer is
+composed), brand, and trailing actions.
 
-Implements the WAI-ARIA APG dialog pattern — focus moves into the panel on
-open and returns to the previously focused element (the trigger) on close,
-Tab is trapped inside, Escape and backdrop clicks close, body scroll locks
-(reference-counted with any stacked `<Modal>`), and the shell closes it on
-SPA navigation. Renders nothing on desktop or while closed.
+Sticks to the top of the viewport by default. The menu trigger renders
+only while a `ResponsiveAppShell.Drawer` is part of the composition AND
+the viewport is below the breakpoint.
 
 ```typescript
-function ResponsiveAppShellDrawer({
-  children,
-  header,
-  navLabel,
-  footer,
-  showCloseButton = true,
+function ResponsiveAppShellTopBar({
+  brand,
+  actions,
+  mobileOnly = false,
   className,
-  dataMolId = 'shell-drawer',
-  closeDataMolId = 'shell-drawer-close',
+  dataMolId = 'shell-topbar',
   testId,
-}: ResponsiveAppShellDrawerProps): JSX.Element | null
+}: ResponsiveAppShellTopBarProps): JSX.Element | null
 ```
 
-- `props` — Nav children, header/nav-label/footer slots, close-button and class/id overrides.
+- `props` — Brand/actions slots, `mobileOnly`, and class/id overrides.
 
-**Returns:** The drawer portal while open on mobile, otherwise `null`.
+**Returns:** The header landmark, or `null` when `mobileOnly` is set on desktop.
 
 #### `ResponsiveAppShellSidebar(props)`
 
@@ -2390,29 +2394,54 @@ function ResponsiveAppShellSidebar({
 
 **Returns:** The sidebar landmarks, or `null` below the breakpoint.
 
-#### `ResponsiveAppShellTopBar(props)`
+#### `ResponsiveAppShellDrawer(props)`
+
+The mobile nav drawer (<768px): a left-anchored dialog panel over a
+backdrop, opened by the menu trigger the TopBar renders.
+
+Implements the WAI-ARIA APG dialog pattern — focus moves into the panel on
+open and returns to the previously focused element (the trigger) on close,
+Tab is trapped inside, Escape and backdrop clicks close, body scroll locks
+(reference-counted with any stacked `<Modal>`), and the shell closes it on
+SPA navigation. Renders nothing on desktop or while closed.
+
+```typescript
+function ResponsiveAppShellDrawer({
+  children,
+  header,
+  navLabel,
+  footer,
+  showCloseButton = true,
+  className,
+  dataMolId = 'shell-drawer',
+  closeDataMolId = 'shell-drawer-close',
+  testId,
+}: ResponsiveAppShellDrawerProps): JSX.Element | null
+```
+
+- `props` — Nav children, header/nav-label/footer slots, close-button and class/id overrides.
+
+**Returns:** The drawer portal while open on mobile, otherwise `null`.
 
-The shell's `<header>` landmark: menu trigger (mobile, when a Drawer is
-composed), brand, and trailing actions.
+#### `ResponsiveAppShellContent(props)`
 
-Sticks to the top of the viewport by default. The menu trigger renders
-only while a `ResponsiveAppShell.Drawer` is part of the composition AND
-the viewport is below the breakpoint.
+The shell's `<main>` landmark. Grows to fill the row and may shrink below
+its content width, so page-level `overflow-x` strips scroll inside the
+page instead of widening the whole shell.
 
 ```typescript
-function ResponsiveAppShellTopBar({
-  brand,
-  actions,
-  mobileOnly = false,
+function ResponsiveAppShellContent({
+  children,
   className,
-  dataMolId = 'shell-topbar',
+  style,
+  dataMolId = 'shell-content',
   testId,
-}: ResponsiveAppShellTopBarProps): JSX.Element | null
+}: ResponsiveAppShellContentProps): JSX.Element
 ```
 
-- `props` — Brand/actions slots, `mobileOnly`, and class/id overrides.
+- `props` — The page content and class/id overrides.
 
-**Returns:** The header landmark, or `null` when `mobileOnly` is set on desktop.
+**Returns:** The main landmark.
 
 #### `SidebarUserCard(props)`
 
@@ -2474,6 +2503,16 @@ function ThemeToggle({
 
 - `props` — {@link ThemeToggleProps}
 
+#### `useToast()`
+
+Hook to access the toast context for adding and removing toasts.
+
+```typescript
+function useToast(): ToastContextValue
+```
+
+**Returns:** The toast context value with toast management methods.
+
 #### `ToastProvider(props)`
 
 Provider component that manages global toast state.
@@ -2491,40 +2530,6 @@ function ToastProvider({
 
 **Returns:** The rendered provider with toast container.
 
-#### `useIsDesktop(query)`
-
-Whether the viewport is at least 768px wide (the fleet's `md` breakpoint).
-
-Reads `window.matchMedia` synchronously in the state initializer, so the
-FIRST client render is already correct — no mobile-then-desktop swap frame
-(this is time-tracking's QA-hardened version; the naive
-"state starts false, sync in an effect" variant mounts the wrong shell for
-one frame and double-fetches route data on desktop). Subscribes to
-`change` events afterwards. Guarded for non-browser environments
-(SSR/node): returns `false` (the mobile shell) when no `window.matchMedia`
-exists.
-
-```typescript
-function useIsDesktop(query?: string): boolean
-```
-
-- `query` — Override the media query. Defaults to `(min-width: 768px)`.
-
-**Returns:** Whether the desktop shell should mount.
-
-#### `usePanelClose()`
-
-Returns the callback that dismisses the drawer the current panel is
-mounted in. Safe to call anywhere — returns a no-op when no enclosing
-`UserMenu` / `SidebarUserCard` provides one (e.g. a `SettingsPanel`
-rendered as a standalone page).
-
-```typescript
-function usePanelClose(): () => void
-```
-
-**Returns:** A function that closes the enclosing drawer, or a no-op.
-
 #### `UserMenu(props)`
 
 Avatar-style trigger that opens the app's settings panel in a drawer.
@@ -2570,6 +2575,24 @@ function UserMenuPopover({
 
 **Returns:** The relative-positioned popover container.
 
+#### `UserMenuPopoverTrigger(props)`
+
+The trigger button: an initials avatar plus the account name and email,
+styled as a full-width sidebar card. Toggles the popover panel.
+
+```typescript
+function UserMenuPopoverTrigger({
+  ariaLabelKey = 'userMenu.open',
+  ariaLabelDefault = 'Open user menu',
+  dataMolId = 'user-menu',
+  className,
+}: UserMenuPopoverTriggerProps): React.JSX.Element
+```
+
+- `props` — aria-label overrides, `data-mol-id`, and className.
+
+**Returns:** The popover trigger button.
+
 #### `UserMenuPopoverPanel(props)`
 
 The popover panel: an absolutely-positioned card with a built-in
@@ -2597,6 +2620,19 @@ function UserMenuPopoverPanel({
 
 **Returns:** The popover panel, or `null` when closed.
 
+#### `useUserMenuPopoverClose()`
+
+Returns a callback that closes the enclosing `UserMenuPopover`. Useful
+for nav-item `onClick` handlers that should dismiss the popover even
+when they don't change the route. Returns a no-op when called outside
+a `UserMenuPopover`.
+
+```typescript
+function useUserMenuPopoverClose(): () => void
+```
+
+**Returns:** A function that closes the popover.
+
 #### `UserMenuPopoverSignOut(props)`
 
 The sign-out nav item — closes the popover and calls `auth.logout()`.
@@ -2615,46 +2651,17 @@ function UserMenuPopoverSignOut({
 
 **Returns:** The sign-out button.
 
-#### `UserMenuPopoverTrigger(props)`
-
-The trigger button: an initials avatar plus the account name and email,
-styled as a full-width sidebar card. Toggles the popover panel.
-
-```typescript
-function UserMenuPopoverTrigger({
-  ariaLabelKey = 'userMenu.open',
-  ariaLabelDefault = 'Open user menu',
-  dataMolId = 'user-menu',
-  className,
-}: UserMenuPopoverTriggerProps): React.JSX.Element
-```
-
-- `props` — aria-label overrides, `data-mol-id`, and className.
-
-**Returns:** The popover trigger button.
-
-#### `useToast()`
+#### `cn(inputs)`
 
-Hook to access the toast context for adding and removing toasts.
+Merge class name strings, filtering out falsy values (undefined, null, false).
 
 ```typescript
-function useToast(): ToastContextValue
+function cn(inputs?: (string | false | null | undefined)[]): string
 ```
 
-**Returns:** The toast context value with toast management methods.
-
-#### `useUserMenuPopoverClose()`
-
-Returns a callback that closes the enclosing `UserMenuPopover`. Useful
-for nav-item `onClick` handlers that should dismiss the popover even
-when they don't change the route. Returns a no-op when called outside
-a `UserMenuPopover`.
-
-```typescript
-function useUserMenuPopoverClose(): () => void
-```
+- `inputs` — Class name strings or falsy values to be filtered out.
 
-**Returns:** A function that closes the popover.
+**Returns:** A single space-separated class string.
 
 ### Constants
 
@@ -2724,53 +2731,53 @@ const Card: React.ForwardRefExoticComponent<
 >
 ```
 
-#### `CardContent`
+#### `CardHeader`
 
-Card content component.
+Card header component.
 
 ```typescript
-const CardContent: React.ForwardRefExoticComponent<
+const CardHeader: React.ForwardRefExoticComponent<
   React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>
 >
 ```
 
-#### `CardDescription`
+#### `CardTitle`
 
-Card description component.
+Card title component.
 
 ```typescript
-const CardDescription: React.ForwardRefExoticComponent<
-  React.HTMLAttributes<HTMLParagraphElement> & React.RefAttributes<HTMLParagraphElement>
+const CardTitle: React.ForwardRefExoticComponent<
+  React.HTMLAttributes<HTMLHeadingElement> & React.RefAttributes<HTMLHeadingElement>
 >
 ```
 
-#### `CardFooter`
+#### `CardDescription`
 
-Card footer component.
+Card description component.
 
 ```typescript
-const CardFooter: React.ForwardRefExoticComponent<
-  React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>
+const CardDescription: React.ForwardRefExoticComponent<
+  React.HTMLAttributes<HTMLParagraphElement> & React.RefAttributes<HTMLParagraphElement>
 >
 ```
 
-#### `CardHeader`
+#### `CardContent`
 
-Card header component.
+Card content component.
 
 ```typescript
-const CardHeader: React.ForwardRefExoticComponent<
+const CardContent: React.ForwardRefExoticComponent<
   React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>
 >
 ```
 
-#### `CardTitle`
+#### `CardFooter`
 
-Card title component.
+Card footer component.
 
 ```typescript
-const CardTitle: React.ForwardRefExoticComponent<
-  React.HTMLAttributes<HTMLHeadingElement> & React.RefAttributes<HTMLHeadingElement>
+const CardFooter: React.ForwardRefExoticComponent<
+  React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>
 >
 ```
 
@@ -2802,16 +2809,6 @@ const ConfirmButton: React.ForwardRefExoticComponent<
 >
 ```
 
-#### `Container`
-
-Container component.
-
-```typescript
-const Container: React.ForwardRefExoticComponent<
-  ContainerProps & React.RefAttributes<HTMLDivElement>
->
-```
-
 #### `Dropdown`
 
 Dropdown component.
@@ -2868,14 +2865,6 @@ const EmptyState: React.ForwardRefExoticComponent<
 >
 ```
 
-#### `Flex`
-
-Flex container component.
-
-```typescript
-const Flex: React.ForwardRefExoticComponent<FlexProps & React.RefAttributes<HTMLDivElement>>
-```
-
 #### `FloatingInput`
 
 An input with a floating label.
@@ -2917,12 +2906,16 @@ const FormField: React.ForwardRefExoticComponent<
 >
 ```
 
-#### `Grid`
+#### `Label`
 
-Grid container component.
+Label component.
 
 ```typescript
-const Grid: React.ForwardRefExoticComponent<GridProps & React.RefAttributes<HTMLDivElement>>
+const Label: React.ForwardRefExoticComponent<
+  React.LabelHTMLAttributes<HTMLLabelElement> & {
+    required?: boolean
+  } & React.RefAttributes<HTMLLabelElement>
+>
 ```
 
 #### `Input`
@@ -2933,18 +2926,40 @@ Input component.
 const Input: React.ForwardRefExoticComponent<InputProps & React.RefAttributes<HTMLInputElement>>
 ```
 
-#### `Label`
+#### `Container`
 
-Label component.
+Container component.
 
 ```typescript
-const Label: React.ForwardRefExoticComponent<
-  React.LabelHTMLAttributes<HTMLLabelElement> & {
-    required?: boolean
-  } & React.RefAttributes<HTMLLabelElement>
+const Container: React.ForwardRefExoticComponent<
+  ContainerProps & React.RefAttributes<HTMLDivElement>
 >
 ```
 
+#### `Flex`
+
+Flex container component.
+
+```typescript
+const Flex: React.ForwardRefExoticComponent<FlexProps & React.RefAttributes<HTMLDivElement>>
+```
+
+#### `Grid`
+
+Grid container component.
+
+```typescript
+const Grid: React.ForwardRefExoticComponent<GridProps & React.RefAttributes<HTMLDivElement>>
+```
+
+#### `Spacer`
+
+Spacer component.
+
+```typescript
+const Spacer: React.ForwardRefExoticComponent<SpacerProps & React.RefAttributes<HTMLDivElement>>
+```
+
 #### `Modal`
 
 Modal component.
@@ -3073,16 +3088,6 @@ Skeleton component.
 const Skeleton: React.ForwardRefExoticComponent<SkeletonProps & React.RefAttributes<HTMLDivElement>>
 ```
 
-#### `SkeletonCircle`
-
-Skeleton circle (avatar placeholder).
-
-```typescript
-const SkeletonCircle: React.ForwardRefExoticComponent<
-  { size?: number; className?: string } & React.RefAttributes<HTMLDivElement>
->
-```
-
 #### `SkeletonText`
 
 Skeleton text line.
@@ -3093,12 +3098,14 @@ const SkeletonText: React.ForwardRefExoticComponent<
 >
 ```
 
-#### `Spacer`
+#### `SkeletonCircle`
 
-Spacer component.
+Skeleton circle (avatar placeholder).
 
 ```typescript
-const Spacer: React.ForwardRefExoticComponent<SpacerProps & React.RefAttributes<HTMLDivElement>>
+const SkeletonCircle: React.ForwardRefExoticComponent<
+  { size?: number; className?: string } & React.RefAttributes<HTMLDivElement>
+>
 ```
 
 #### `Spinner`
@@ -3176,6 +3183,8 @@ const ToastContainer: React.ForwardRefExoticComponent<
 >
 ```
 
+**Returns:** The rendered toast container element.
+
 #### `Tooltip`
 
 Tooltip component.