@sovereignfs/ui 0.45.0 → 0.83.1

package/dist/index.d.ts

@@ -1,13 +1,96 @@
 import * as react from 'react';
-import { ReactNode, ButtonHTMLAttributes, SelectHTMLAttributes, ReactElement, CSSProperties, InputHTMLAttributes, TextareaHTMLAttributes, HTMLAttributes, TdHTMLAttributes, ThHTMLAttributes, LabelHTMLAttributes, ElementType, PointerEvent, KeyboardEvent, MouseEvent } from 'react';
+import { ReactNode, ButtonHTMLAttributes, SelectHTMLAttributes, ReactElement, CSSProperties, InputHTMLAttributes, Ref, TextareaHTMLAttributes, HTMLAttributes, TdHTMLAttributes, ThHTMLAttributes, LabelHTMLAttributes, ElementType, PointerEvent, KeyboardEvent, MouseEvent, RefObject } from 'react';
+import * as _dnd_kit_core from '@dnd-kit/core';
+
+interface LegalLinksProps {
+    privacyHref?: string;
+    tosHref?: string;
+    /** Renders a linked item. Defaults to a plain `<a href>`, which causes a
+     * full page reload — pass Next's `<Link>` (or equivalent) to keep
+     * navigation client-side. Not needed for a full-reload navigation away
+     * from a standalone auth page, but matters if this is ever mounted inside
+     * an SPA-like shell. */
+    renderLink?: (href: string, label: string) => ReactNode;
+    className?: string;
+}
+declare function LegalLinks({ privacyHref, tosHref, renderLink, className, }: LegalLinksProps): react.JSX.Element;
+
+interface ConsentPromptProps {
+    /** The plugin requesting access. */
+    consumerName: string;
+    /** The plugin whose data would be read. */
+    providerName: string;
+    /** The named contract being requested (e.g. `"expenses"`). */
+    contract: string;
+    /**
+     * The provider's own manifest-declared explanation of what this contract
+     * exposes (`data.provides[].description`) — never caller-supplied at
+     * request time, so a consuming plugin can't write its own persuasive copy
+     * for what it's asking to read.
+     */
+    description?: string | null;
+    onAllow: () => void;
+    onDeny?: () => void;
+    allowLabel?: string;
+    denyLabel?: string;
+    /** Disables both buttons and shows a busy state on Allow while a request is in flight. */
+    pending?: boolean;
+    className?: string;
+}
+/**
+ * The consent screen shown before one plugin is allowed to read another
+ * plugin's data (RFC 0002 §4) — the step that was previously missing between
+ * a `ConsentRequiredError` and a grant actually being created. Presentational
+ * only: holds no state of its own, so it renders identically wherever it's
+ * used (currently Account → Data's pending-requests list).
+ */
+declare function ConsentPrompt({ consumerName, providerName, contract, description, onAllow, onDeny, allowLabel, denyLabel, pending, className, }: ConsentPromptProps): react.JSX.Element;
+
+interface MarkdownProps {
+    /** Raw markdown source. Supports: headings (#/##/###), paragraphs,
+     * **bold**, *italic*, `code`, [links](url), unordered lists (-), ordered
+     * lists (1. / 1)), fenced code blocks (```), and blockquotes (>),
+     * including soft-wrapped continuation lines within a paragraph or list
+     * item. Not a general-purpose CommonMark parser — no tables, images, or
+     * nested blocks. */
+    content: string;
+    /** Renders every line within a paragraph on its own visual line (a
+     * `<br>` between them) instead of the default CommonMark-style soft-wrap
+     * (consecutive lines joined with a single space, requiring a blank line
+     * for a new paragraph). Off by default — the soft-wrap behavior is
+     * correct for this component's primary use (long-form, first-party
+     * content authored *as* markdown, where a hard line break is a
+     * deliberate `\`  ` or blank-line choice). Turn this on when rendering
+     * plain, user-typed multi-line text that happens to be passed through
+     * this component (e.g. a card description or comment body edited in an
+     * ordinary `<textarea>`) — there, every Enter press is a real,
+     * intentional line break the user typed, and silently collapsing it
+     * into one run-on paragraph reads as broken, not as "markdown
+     * formatting applied." */
+    preserveLineBreaks?: boolean;
+    className?: string;
+}
+/** Renders a constrained markdown subset (see MarkdownProps) as styled React
+ * elements built from Typography — no HTML string injection. Primarily
+ * meant for long-form, first-party content pages (privacy policy, terms of
+ * service) sourced from a single markdown file — not a general-purpose
+ * CommonMark renderer for arbitrary markdown. Also fine for plain,
+ * user-typed multi-line text (a card description, a comment body) edited
+ * in an ordinary `<textarea>` and passed through unchanged, as long as
+ * `preserveLineBreaks` is set — see that prop's own doc comment for why it
+ * isn't the default. */
+declare function Markdown({ content, preserveLineBreaks, className }: MarkdownProps): react.JSX.Element;
 
 type BadgeVariant = 'role' | 'status' | 'mono';
-type BadgeSize = 'sm' | 'md' | 'lg';
+type BadgeSize = 'xs' | 'sm' | 'md' | 'lg';
 type BadgeStatus = 'active' | 'enabled' | 'deactivated' | 'failed' | 'invited' | 'pending' | 'neutral';
 interface BadgeProps {
     variant?: BadgeVariant;
-    /** 'sm' | 'md' (default) | 'lg'. 'md' is the badge's original — and until
-     * now, only — size, so the default renders unchanged. */
+    /** 'xs' | 'sm' | 'md' (default) | 'lg'. 'md' is the badge's original — and
+     * until now, only — size, so the default renders unchanged. 'xs' is the
+     * smallest tier (`--sv-font-size-2xs`, 10px) — for a badge sitting inline
+     * next to larger text (e.g. a status chip beside a card's headline value)
+     * where even 'sm' still reads oversized next to it. */
     size?: BadgeSize;
     /** Only relevant when variant="status" — determines the dot colour. */
     status?: BadgeStatus;
@@ -25,12 +108,12 @@ interface BadgeProps {
  * - `status` tinted chip with leading colour dot — for Active / Deactivated / etc.
  * - `mono`   monospace font, neutral surface — for platform / community / v0.1.0
  *
- * Three sizes (`sm`/`md`/`lg`, default `md`). ALL CAPS by default
+ * Four sizes (`xs`/`sm`/`md`/`lg`, default `md`). ALL CAPS by default
  * (`uppercase`) — set `uppercase={false}` for a title-case badge instead.
  */
 declare function Badge({ variant, size, status, uppercase, children, }: BadgeProps): react.JSX.Element;
 
-type IconName = 'house' | 'settings' | 'log-out' | 'chevron-right' | 'chevron-left' | 'chevron-down' | 'chevron-up' | 'x' | 'check' | 'plus' | 'trash-2' | 'pencil' | 'rotate-ccw' | 'search' | 'user' | 'shield' | 'lock' | 'eye' | 'eye-off' | 'mail' | 'bell' | 'activity' | 'package' | 'grid-2x2' | 'info' | 'alert-triangle' | 'circle-check' | 'circle-x' | 'calendar' | 'sliders-horizontal' | 'ellipsis-vertical' | 'file' | 'upload' | 'external-link' | 'banana' | 'apple' | 'carrot' | 'egg' | 'beef' | 'fish' | 'coffee' | 'wine' | 'beer' | 'cookie' | 'pizza' | 'candy' | 'salad' | 'milk' | 'drumstick' | 'croissant' | 'cup-soda' | 'spray-can' | 'snowflake' | 'shopping-basket';
+type IconName = 'house' | 'settings' | 'log-out' | 'smartphone' | 'chevron-right' | 'chevron-left' | 'chevron-down' | 'chevron-up' | 'circle-chevron-left' | 'menu' | 'x' | 'check' | 'plus' | 'trash-2' | 'pencil' | 'rotate-ccw' | 'search' | 'copy' | 'user' | 'users' | 'user-round-plus' | 'shield' | 'lock' | 'eye' | 'eye-off' | 'hat-glasses' | 'mail' | 'bell' | 'inbox' | 'activity' | 'package' | 'database' | 'layers' | 'grid-2x2' | 'layout-dashboard' | 'layout-grid' | 'square-kanban' | 'info' | 'alert-triangle' | 'circle-check' | 'circle-x' | 'calendar' | 'sliders-horizontal' | 'ellipsis-vertical' | 'rectangle-ellipsis' | 'file' | 'folder' | 'upload' | 'download' | 'external-link' | 'arrow-left-right' | 'send' | 'list' | 'list-ordered' | 'link' | 'code' | 'rotate-cw' | 'refresh-cw' | 'history' | 'minus' | 'table' | 'sheet' | 'folders' | 'folder-closed' | 'file-text' | 'folder-open' | 'share-2' | 'luggage' | 'map-pin' | 'route' | 'bold' | 'italic' | 'paint-bucket' | 'banana' | 'apple' | 'carrot' | 'egg' | 'beef' | 'fish' | 'coffee' | 'wine' | 'beer' | 'cookie' | 'pizza' | 'candy' | 'salad' | 'milk' | 'drumstick' | 'croissant' | 'cup-soda' | 'spray-can' | 'snowflake' | 'shopping-basket' | 'panel-left' | 'pin' | 'credit-card';
 
 /** Decorative icon — visually meaningful but described by surrounding text. */
 type DecorativeProps = {
@@ -177,6 +260,17 @@ interface PopoverProps {
      * regardless of CSS module load order, unlike passing an extra className.
      */
     panelStyle?: CSSProperties;
+    /**
+     * Class applied to the popover's own wrapper around `trigger` — the
+     * element that participates in the caller's layout.
+     *
+     * Mostly needed for flex sizing: the wrapper is an `inline-flex` box with
+     * the default `min-width: auto`, which pins it to the trigger's content
+     * width. Inside a flex row that has to shrink, that stops a truncatable
+     * trigger from ever giving up space, and pushes its siblings out of the
+     * container instead. Pass a class setting `min-width: 0` there.
+     */
+    className?: string;
     'aria-label': string;
     children: ReactNode;
 }
@@ -203,7 +297,7 @@ interface PopoverProps {
  *
  * Closes on outside click or Escape. Does not trap focus (it is non-modal).
  */
-declare function Popover({ trigger, open, onClose, align, width, panelStyle, 'aria-label': ariaLabel, children, }: PopoverProps): react.JSX.Element;
+declare function Popover({ trigger, open, onClose, align, width, panelStyle, className, 'aria-label': ariaLabel, children, }: PopoverProps): react.JSX.Element;
 
 type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'destructive';
 type ButtonSize = 'sm' | 'md' | 'lg';
@@ -222,7 +316,13 @@ interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
  */
 declare function Button({ variant, size, type, loading, disabled, className, children, ...rest }: ButtonProps): react.JSX.Element;
 
-type InputProps = InputHTMLAttributes<HTMLInputElement>;
+type InputProps = InputHTMLAttributes<HTMLInputElement> & {
+    /** React 19 ref-as-prop — no `forwardRef` needed. Not part of
+     *  `InputHTMLAttributes` (refs aren't a DOM attribute), so it's added
+     *  explicitly here; left out of the destructure below so it flows through
+     *  `...rest` straight onto the underlying `<input>`. */
+    ref?: Ref<HTMLInputElement>;
+};
 /**
  * Input — the primitive text field. Presentational and RSC-safe: it forwards
  * all native input props to the underlying `<input>`. Styling references
@@ -230,14 +330,23 @@ type InputProps = InputHTMLAttributes<HTMLInputElement>;
  */
 declare function Input({ type, className, ...rest }: InputProps): react.JSX.Element;
 
-type TextareaProps = TextareaHTMLAttributes<HTMLTextAreaElement>;
+interface TextareaProps extends TextareaHTMLAttributes<HTMLTextAreaElement> {
+    /** Grows the field's own height to fit its content as it's typed, instead
+     *  of scrolling internally or leaving the user to drag-resize — e.g. an
+     *  editable title that should read as a heading, not a fixed-size form
+     *  field. Disables manual resize (`resize: none`) since a height driven by
+     *  content and a user-draggable height would fight each other. `rows` is
+     *  still honoured as the starting/minimum height. */
+    autoGrow?: boolean;
+}
 /**
  * Textarea — the primitive multi-line text field. Presentational and
- * RSC-safe: it forwards all native textarea props to the underlying
+ * RSC-safe unless `autoGrow` is used (client-only, needs a layout
+ * measurement). Forwards all native textarea props to the underlying
  * `<textarea>`. Styling references `--sv-*` tokens via CSS Modules; there
  * are no hardcoded values.
  */
-declare function Textarea({ className, rows, ...rest }: TextareaProps): react.JSX.Element;
+declare function Textarea({ className, rows, autoGrow, ...rest }: TextareaProps): react.JSX.Element;
 
 interface CodeTextareaProps extends TextareaHTMLAttributes<HTMLTextAreaElement> {
     invalid?: boolean;
@@ -308,11 +417,13 @@ declare function TagInput({ value, onChange, id, name, placeholder, disabled, re
 /**
  * Lets content deep inside a `Dialog` (e.g. a plugin's own route layout,
  * rendered several levels below wherever the `Dialog` itself is
- * instantiated) supply the second-row content of the Dialog's mobile
- * `OverlayHeader` — typically a tab strip. Solves the "double header"
- * problem: without this, a plugin's own tab strip has no way to reach the
- * Dialog's header and ends up rendered a second time, as its own sticky bar,
- * inside the scrolling content area.
+ * instantiated) supply the second-row content of the Dialog's `OverlayHeader`
+ * — typically a tab strip. Solves the "double header" problem: without this,
+ * a plugin's own tab strip has no way to reach the Dialog's header and ends
+ * up rendered a second time, as its own sticky bar, inside the scrolling
+ * content area. Reaches the header regardless of whether it's showing via
+ * the `header` prop (both breakpoints) or the default `title`-driven mobile
+ * bar (mobile only) — see `DialogProps.header`'s own doc comment.
  *
  * A no-op when there is no enclosing `Dialog` (e.g. the same plugin layout
  * also rendered on a plain, non-overlay route) — safe to call unconditionally.
@@ -329,7 +440,7 @@ declare function TagInput({ value, onChange, id, name, placeholder, disabled, re
  * ```
  */
 declare function useOverlaySecondRow(node: ReactNode | null): boolean;
-type DialogSize = 'sm' | 'md' | 'lg' | 'full';
+type DialogSize = 'sm' | 'md' | 'lg' | 'auto' | 'fixed';
 interface DialogProps {
     /** Whether the dialog is shown. When false, nothing renders. */
     open: boolean;
@@ -337,11 +448,42 @@ interface DialogProps {
     onClose: () => void;
     /** Panel size on desktop. Mobile always renders as a full-screen sheet. */
     size?: DialogSize;
-    /** Accessible name for the dialog (sets `aria-label` on the panel). */
+    /** Accessible name for the dialog (sets `aria-label` on the panel). Falls
+     *  back to `title` when omitted — this still applies even when `header` is
+     *  used instead of `title` for the visible header (see `header`'s own doc
+     *  comment), so pass `aria-label` explicitly in that case if `title` is
+     *  also omitted. */
     'aria-label'?: string;
-    /** On mobile: shown in the top bar alongside the close button so the title
-     *  and dismiss affordance occupy the same row instead of stacking. */
+    /** Shown in the top bar alongside the close button, on mobile only —
+     *  desktop has no header row by default (see `header` for that). Ignored
+     *  as visible content when `header` is provided; still used as the
+     *  `aria-label` fallback either way. */
     title?: string;
+    /** Renders a persistent header row (via the same `OverlayHeader` component
+     *  `title` alone only shows on mobile) on **both** desktop and mobile —
+     *  the "Header + Body" / "Header + Body + Footer" shapes. Supersedes
+     *  `title` for visible content when provided; `title` remains the
+     *  `aria-label` fallback if `aria-label` is also omitted. Omitting both
+     *  `header` and `footer` is "Body only" — today's default, unchanged. */
+    header?: ReactNode;
+    /** Renders a persistent footer row below the scrollable body — pinned on
+     *  both desktop and mobile the same way `header`/the mobile title bar are
+     *  (a non-scrolling flex sibling, not `position: sticky`): only the region
+     *  between header and footer scrolls. Typically action buttons (Save/
+     *  Cancel). Omit for no footer — today's default, where any actions live
+     *  inside `children` and scroll with the rest of the body. Layout-agnostic
+     *  (no built-in button alignment) — arrange the footer's own content as
+     *  needed, same as `children`. */
+    footer?: ReactNode;
+    /** Forwarded to the active `OverlayHeader` instance's own `rowClassName`
+     *  (whichever is showing — `header` or the mobile `title` bar) — restyle
+     *  the title row (e.g. tighter padding to match a consumer's own compact
+     *  header elsewhere) without changing its title/close layout. */
+    rowClassName?: string;
+    /** Forwarded to the active `OverlayHeader` instance's own `titleClassName`
+     *  — restyle the title text (e.g. a smaller font size to match a
+     *  consumer's own compact header elsewhere). */
+    titleClassName?: string;
     children: ReactNode;
 }
 /**
@@ -359,8 +501,14 @@ interface DialogProps {
  * `onClose` API is unchanged — closing still stays mounted internally for the
  * exit transition before actually unmounting; `prefers-reduced-motion: reduce`
  * collapses both to near-instant.
+ *
+ * Three composition shapes, chosen by which of `header`/`footer` are passed:
+ * Body only (both omitted — today's default), Header + Body (`header` only),
+ * Header + Body + Footer (`header` and `footer`). Whichever of header/footer
+ * are present render as non-scrolling flex siblings around `.content`, which
+ * stays the only scrollable region in every shape.
  */
-declare function Dialog({ open, onClose, size, 'aria-label': ariaLabel, title, children, }: DialogProps): react.JSX.Element | null;
+declare function Dialog({ open, onClose, size, 'aria-label': ariaLabel, title, header, footer, rowClassName, titleClassName, children, }: DialogProps): react.JSX.Element | null;
 
 interface DrawerProps {
     /** Whether the drawer is shown. When false, nothing renders. */
@@ -374,6 +522,12 @@ interface DrawerProps {
      *  "half screen or less" convention for Drawer, this is the only other
      *  supported size; taller content should use `Sheet` instead. */
     snapHeight?: 'content' | 'half';
+    /** Renders a built-in `OverlayHeader` (title + close) below the grab
+     *  handle. Omit when the content supplies its own header, or none is
+     *  needed at all — e.g. the mobile shell's Apps drawer, whose grab handle
+     *  and swipe-down/scrim-tap dismissal are enough on their own. Mirrors
+     *  `Sheet`'s identical `title` prop. */
+    title?: string;
     children: ReactNode;
 }
 /**
@@ -398,13 +552,17 @@ interface DrawerProps {
  * scroll, the same reasoning behind the tasks plugin's edge-zone-only
  * swipe-to-reveal technique.
  */
-declare function Drawer({ open, onClose, 'aria-label': ariaLabel, snapHeight, children, }: DrawerProps): react.JSX.Element | null;
+declare function Drawer({ open, onClose, 'aria-label': ariaLabel, snapHeight, title, children, }: DrawerProps): react.JSX.Element | null;
 
 interface OverlayHeaderProps {
     /** Overlay title, shown between the optional back button and the trailing
      *  slots. Optional — some consumers (e.g. `Dialog`'s mobile bar) need the
-     *  row's close button present even when no title applies. */
-    title?: string;
+     *  row's close button present even when no title applies. Accepts any
+     *  `ReactNode`, not just a string — e.g. `Dialog`'s `header` prop passes
+     *  arbitrary content through here (an icon next to text, etc.); the
+     *  row's title slot still assumes single-line content sized like text
+     *  (see the component's own doc comment for the line this doesn't cross). */
+    title?: ReactNode;
     /** Always renders a close button; called on click. */
     onClose: () => void;
     /** When provided, renders a back-chevron button before the title (for
@@ -416,6 +574,15 @@ interface OverlayHeaderProps {
     /** A second row below the title row — e.g. a tab strip. */
     secondRow?: ReactNode;
     className?: string;
+    /** Override the title row's own className (e.g. tighter padding to match
+     *  a consumer's own compact header elsewhere in the same surface) — the
+     *  row keeps its standard title/back/action/close layout, just restyled.
+     *  For a genuinely different shape, don't use `OverlayHeader` at all (see
+     *  this component's own doc comment). */
+    rowClassName?: string;
+    /** Override the title text's own className (e.g. a smaller font size to
+     *  match a consumer's own compact header elsewhere in the same surface). */
+    titleClassName?: string;
 }
 /**
  * OverlayHeader — the shared fixed secondary header for `Dialog`'s mobile
@@ -431,7 +598,7 @@ interface OverlayHeaderProps {
  * component — render its own header row instead; `Sheet`'s `title` prop is
  * optional specifically to leave that escape hatch open.
  */
-declare function OverlayHeader({ title, onClose, onBack, action, secondRow, className, }: OverlayHeaderProps): react.JSX.Element;
+declare function OverlayHeader({ title, onClose, onBack, action, secondRow, className, rowClassName, titleClassName, }: OverlayHeaderProps): react.JSX.Element;
 
 interface SheetProps {
     /** Whether the sheet is shown. When false, nothing renders. */
@@ -526,7 +693,16 @@ declare function ConfirmDialog({ open, onClose, title, message, onConfirm, confi
 interface MenuItem {
     type?: 'item';
     label: string;
-    onSelect: () => void;
+    /** Optional when `href` is provided (a pure navigation entry needs no
+     *  extra callback) — required otherwise. Called before the surface closes
+     *  is the caller's job to avoid; `Menu`'s own wiring always closes first,
+     *  then calls this. */
+    onSelect?: () => void;
+    /** Renders the entry as a link (`<a href>`, `role="menuitem"`) instead of
+     *  a `<button>` — same href-vs-onClick convention as `MobileAppsDrawer`'s
+     *  items. Framework-agnostic (a plain anchor, not `next/link`), matching
+     *  every other `packages/ui` href slot. */
+    href?: string;
     icon?: IconName;
     /** Styles the item as a destructive action (e.g. "Delete list"). */
     destructive?: boolean;
@@ -562,6 +738,15 @@ interface MenuProps {
     /** Forwarded to `Popover` on desktop. Has no effect on mobile, where the
      *  menu is always a full-width `Drawer`. */
     align?: 'left' | 'right';
+    /** Forwarded to `Popover` on desktop (same default: 288). Has no effect
+     *  on mobile. Narrow this when the trigger lives inside a column
+     *  narrower than the default width — e.g. a per-row "⋯" menu in a
+     *  sidebar list — so the panel fits within that column's own bounds
+     *  instead of overflowing past its edge, where a scrollable ancestor's
+     *  `overflow-y: auto` (which the CSS Overflow spec computes the paired
+     *  `overflow-x` to `auto` as well, not `visible`, once either axis is
+     *  set) would clip it. */
+    width?: number | 'trigger';
 }
 /**
  * Menu — an adaptive action menu: `Popover` on desktop, a bottom-sheet
@@ -592,7 +777,148 @@ declare function MenuEntries({ items, onSelect, }: {
     /** Called after an item's own onSelect — typically the surface's onClose. */
     onSelect: (entry: MenuItem) => void;
 }): react.JSX.Element;
-declare function Menu({ trigger, open, onClose, items, 'aria-label': ariaLabel, align }: MenuProps): react.JSX.Element;
+declare function Menu({ trigger, open, onClose, items, 'aria-label': ariaLabel, align, width, }: MenuProps): react.JSX.Element;
+
+interface UserMenuItem {
+    label: string;
+    icon: IconName;
+    /** Optional when `href` is provided (a pure navigation entry needs no
+     *  extra callback). Required otherwise (e.g. "Sign out"). */
+    onSelect?: () => void;
+    /** Renders the entry as a link (`<a href>`) instead of a button — same
+     *  href-vs-onClick convention as `MobileAppsDrawer`'s items. */
+    href?: string;
+    destructive?: boolean;
+}
+interface UserMenuProps {
+    name?: string;
+    email?: string;
+    avatarUrl?: string;
+    items: UserMenuItem[];
+    /** Trigger button's accessible label. Defaults to "Account". */
+    'aria-label'?: string;
+    align?: 'left' | 'right';
+    /** Trigger avatar size: `'md'` (36px) matches the platform sidebar's own
+     *  `.avatar` exactly — the default, for that context. `'sm'` (32px) suits
+     *  the more compact `Header` top-bar context instead. The panel's own
+     *  user-info avatar (38px) is unaffected either way — only the trigger
+     *  scales. */
+    size?: 'sm' | 'md';
+}
+/**
+ * UserMenu — the account avatar trigger + dropdown, generalized from the
+ * runtime shell's own `AccountMenu.tsx` (the real, currently-shipped
+ * component that every `shell: minimal` plugin would otherwise have to
+ * hand-rebuild locally instead of importing). Same visual structure and
+ * copy: an accent-filled avatar trigger (36px, matching the sidebar's own
+ * `.avatar`), a name+email header block (38px avatar) above a divider, then
+ * a plain item list.
+ *
+ * Presentational only — no auth/session/routing logic of its own. The
+ * consumer supplies `items`, each with its own `onSelect` and/or `href`,
+ * matching `MobileHeader`'s "consumer wires it up" boundary; a real
+ * "Sign out" is just an item whose `onSelect` does whatever the consuming
+ * app's sign-out actually requires. Built on the shared `Popover` primitive
+ * (self-contained open state, matching the original's own architecture)
+ * rather than a hand-rolled outside-click/Escape listener — the original
+ * `AccountMenu` and every plugin-local rebuild of it independently re-derive
+ * that same logic; one primitive here means one implementation to get
+ * right. Always a small anchored dropdown, never a full-width sheet —
+ * this is deliberately not built on the adaptive `Menu` component (which
+ * becomes a bottom `Drawer` on mobile): the real account menu is a compact
+ * floating panel on every surface, mobile included.
+ */
+declare function UserMenu({ name, email, avatarUrl, items, 'aria-label': ariaLabel, align, size, }: UserMenuProps): react.JSX.Element;
+
+interface AppsLauncherItem {
+    /** Stable identity for this tile — used as the React key. */
+    key: string;
+    icon: ReactNode;
+    label: string;
+    /** Renders an `<a>` when set; otherwise a `<button>` calling `onClick` —
+     *  same dual-mode convention as `MobileAppsDrawer`'s items. */
+    href?: string;
+    onClick?: () => void;
+}
+interface AppsLauncherProps {
+    items: AppsLauncherItem[];
+    /** Shows a spinner in place of the grid — e.g. while the tile list is
+     *  still being fetched. */
+    loading?: boolean;
+    /** Shows an error message in place of the grid. */
+    error?: boolean;
+    errorMessage?: string;
+    /** Trigger button's icon. Defaults to a generic grid glyph — pass the
+     *  real Launcher plugin's own icon for pixel parity with the platform. */
+    triggerIcon?: ReactNode;
+    /** Trigger button's accessible label, and the popover's own. Defaults to "Apps". */
+    'aria-label'?: string;
+    align?: 'left' | 'right';
+}
+/**
+ * AppsLauncher — the desktop "Apps" switcher: a 28px grid-icon trigger that
+ * opens a `Popover` with a 3-column tile grid. The desktop counterpart to
+ * `MobileAppsDrawer` — same `items` shape (`key`/`icon`/`label`/`href`/
+ * `onClick`), different chrome (floating panel vs. bottom sheet), matching
+ * how `Header`/`MobileHeader` already split the same way.
+ *
+ * Presentational only — no plugin-list fetching of its own. The consumer
+ * supplies `items` already resolved (and `loading`/`error` while it isn't
+ * yet), matching `MobileAppsDrawer`'s own boundary.
+ */
+declare function AppsLauncher({ items, loading, error, errorMessage, triggerIcon, 'aria-label': ariaLabel, align, }: AppsLauncherProps): react.JSX.Element;
+
+interface NotificationsPanelItem {
+    id: string;
+    /** Category icon, already resolved (sized + colored) by the consumer —
+     *  this component doesn't own category → color mapping. */
+    icon: ReactNode;
+    title: string;
+    /** Pre-formatted relative time (e.g. "2d ago") — formatting stays
+     *  consumer-side so this component needs no Date/clock dependency. */
+    timeLabel: string;
+    read: boolean;
+    /** Renders the title as a link when set. */
+    href?: string;
+    /** Called when the title is clicked/tapped — typically "mark as read". */
+    onOpen?: () => void;
+    onDismiss: () => void;
+}
+interface NotificationsPanelProps {
+    items: NotificationsPanelItem[];
+    unreadCount: number;
+    onMarkAllRead?: () => void;
+    onClearAll?: () => void;
+    emptyMessage?: string;
+    /** Trigger button's accessible label base — the unread count is appended
+     *  automatically, matching the real NotificationBell. Defaults to
+     *  "Notifications". */
+    'aria-label'?: string;
+    align?: 'left' | 'right';
+    /** Optional footer link (e.g. to the consumer's own full notification
+     *  list/detail view — RFC 0048) — mirrors the real `NotificationBell`'s
+     *  "View all" link. Omit to render no footer, matching this component's
+     *  behavior before this prop existed. */
+    viewAllHref?: string;
+}
+/**
+ * NotificationsPanel — the bell trigger + dropdown, generalized from the
+ * runtime shell's own `NotificationBell.tsx` visual structure and copy
+ * (title / Mark all read / Clear all / close, then a list of category-icon +
+ * title + time + unread-dot + dismiss rows, or an empty state).
+ *
+ * Deliberately **presentational only** — no fetch/SSE/polling, no
+ * category → color mapping, no mark-read/dismiss networking. The real
+ * `NotificationBell` owns real platform data (`/api/account/notifications`,
+ * a shared cross-instance store); this component can't and shouldn't know
+ * about that (SDK boundary). The consumer supplies `items` already resolved
+ * and wires `onOpen`/`onDismiss`/`onMarkAllRead`/`onClearAll` to whatever
+ * its own data layer needs, against a shared panel instead of a
+ * `shell: minimal` plugin hand-rebuilding one locally. Built on the shared
+ * `Popover` primitive (self-contained open state) rather than the
+ * original's hand-rolled outside-click/Escape listener.
+ */
+declare function NotificationsPanel({ items, unreadCount, onMarkAllRead, onClearAll, emptyMessage, 'aria-label': ariaLabel, align, viewAllHref, }: NotificationsPanelProps): react.JSX.Element;
 
 interface ToastItem {
     id: string;
@@ -624,6 +950,64 @@ interface CardProps extends HTMLAttributes<HTMLElement> {
 }
 declare function Card({ as: Tag, interactive, padding, className, children, ...rest }: CardProps): react.JSX.Element;
 
+interface CardTileGridProps {
+    children: ReactNode;
+    /** Minimum tile width (px) before the grid wraps to fewer columns. */
+    minTileWidth?: number;
+    className?: string;
+    /**
+     * Tight spacing with tiles that keep their natural width instead of
+     * stretching to fill the row — for small `variant="icon"` tiles (e.g. a
+     * folder grid), where the default grid's spacious gap and `1fr`-stretched
+     * columns leave a lot of empty space around a tile that's really just an
+     * icon + short label.
+     */
+    dense?: boolean;
+}
+/** Responsive grid of `CardTile`/`NewCardTile` children — `repeat(auto-fill, minmax(minTileWidth, 1fr))`, or `minmax(minTileWidth, max-content)` with a tighter gap when `dense`. */
+declare function CardTileGrid({ children, minTileWidth, className, dense, }: CardTileGridProps): react.JSX.Element;
+interface CardTileProps extends HTMLAttributes<HTMLDivElement> {
+    /** Content centered in the tile's full-bleed top banner — typically an `<Icon>`. Omit for a plain strip. */
+    banner?: ReactNode;
+    /** Banner background color (applied inline). Falls back to a neutral sunken-surface strip when omitted. Ignored by `variant="icon"`, which has no banner box. */
+    bannerColor?: string;
+    /** Tile footer content — typically the item's name. */
+    children: ReactNode;
+    /**
+     * `"card"` (default): a bordered card with a colored/iconed banner strip
+     * over a footer label. `"icon"`: a plain "Finder icon" tile — no card
+     * chrome at all, just a large centered icon with a label beneath it. Use
+     * `"icon"` for entities that read as a single glyph + name (e.g. a
+     * folder), where a bordered card reads as heavier than the content needs.
+     */
+    variant?: 'card' | 'icon';
+}
+/**
+ * A colored/iconed banner over a footer label — a card shape `Card` can't
+ * express, since `Card`'s `padding` prop always pads its single box with no
+ * way for a top region to bleed to the edges. Not link-aware: wrap it in the
+ * host framework's own link component (e.g. Next's `<Link>`) to make it
+ * navigable, same as every existing consumer of this pattern does.
+ */
+declare function CardTile({ banner, bannerColor, children, className, variant, ...rest }: CardTileProps): react.JSX.Element;
+interface NewCardTileProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    /** Icon shown beside the label (`"card"`) or alone (`"icon"`). Defaults to `"plus"`. */
+    icon?: IconName;
+    /** Visible next to the icon for `"card"`. For `"icon"`, not rendered as text — used as the button's `aria-label` instead, since the tile is icon-only. */
+    label: string;
+    /**
+     * `"card"` (default): a dashed box matching a `variant="card"` `CardTile`'s
+     * footprint — icon beside a visible label. `"icon"`: matches a
+     * `variant="icon"` `CardTile`'s footprint instead, but icon-only, no
+     * visible label — a plain "+" reads as self-explanatory once every
+     * sibling tile in the same `dense` grid is already an unlabeled icon
+     * (the dashed border alone marks it as the "add new" affordance).
+     */
+    variant?: 'card' | 'icon';
+}
+/** Dashed ghost tile matching a real `CardTile`'s footprint — the grid's own "add new" affordance. */
+declare function NewCardTile({ icon, label, type, variant, className, ...rest }: NewCardTileProps): react.JSX.Element;
+
 /** Props to spread onto the field's actual form control. */
 interface FormFieldRenderProps {
     id: string;
@@ -654,10 +1038,252 @@ declare function FormField({ label, hint, error, id, required, className, childr
 interface PageHeaderProps {
     title: string;
     description?: string;
+    /** Optional icon rendered inline before the title text, on both breakpoints — e.g. `folder-open` next to a folder's name. */
+    icon?: IconName;
+    /**
+     * Page-level controls — anywhere from one button to a whole toolbar.
+     * Renders on both breakpoints unchanged; if it needs to look different on
+     * mobile (e.g. collapsing into its own "⋮" trigger), that's the action
+     * content's own responsibility — same pattern Shopper's `ListHeaderActions`
+     * already follows (it calls `useIsMobile()` internally). `PageHeader`
+     * itself has no opinion on what's inside this slot.
+     */
     action?: ReactNode;
     className?: string;
+    /** Heading level for the title. Defaults to `1` for standalone use; pass
+     * `2` or `3` when the page already sits under a shell/plugin `<h1>`, to
+     * avoid a duplicate top-level heading. Visual style is unchanged at every
+     * level — only the rendered tag changes. Applies on both breakpoints. */
+    headingLevel?: 1 | 2 | 3;
+    /** Mobile only — shows a back button (calling this) to the left of the
+     *  title when provided. Omit it to render without one. */
+    onBack?: () => void;
+    /** Mobile only — shows a vertical-ellipsis icon button (calling this) at
+     *  the far right when provided, typically to open a drawer/menu. PageHeader
+     *  has no opinion on what that menu contains — it only renders the trigger
+     *  and calls back. Separate from `action`, which renders identically on
+     *  both breakpoints; this is a mobile-only affordance with no web
+     *  equivalent. */
+    onMenuClick?: () => void;
 }
-declare function PageHeader({ title, description, action, className }: PageHeaderProps): react.JSX.Element;
+/**
+ * PageHeader — a page's title section. Web: title + description on the
+ * left, action on the right. Mobile: an optional back button, a single-line
+ * title, and the same action slot — a compact single row, matching Kanban's
+ * own hand-rolled MobileBoardHeader this was generalized from. The
+ * web/mobile fork is `ResponsiveSurface` — only one tree is ever mounted.
+ */
+declare function PageHeader({ title, description, icon, action, className, headingLevel, onBack, onMenuClick, }: PageHeaderProps): react.JSX.Element;
+
+interface PageContainerProps extends HTMLAttributes<HTMLDivElement> {
+    /**
+     * Constrains and centers content width. The bound includes `padding`
+     * (the container is `border-box`). Defaults to `'full'` — narrowing is
+     * opt-in, so wrapping a page in `PageContainer` never silently clamps it.
+     */
+    maxWidth?: 'sm' | 'md' | 'lg' | 'full';
+    /**
+     * The page gutter. Responsive — each step is tighter at ≤768px. Defaults
+     * to `'md'`, which is exactly what the runtime shell used to apply
+     * (`--sv-space-8` desktop / `--sv-space-4` mobile), so a bare
+     * `<PageContainer>` is the correct wrapper for a plugin that previously
+     * relied on the shell for its padding.
+     *
+     * Use `'none'` when an ancestor already supplies the gutter — inside a
+     * `Dialog`, whose own content region is padded.
+     */
+    padding?: 'none' | 'sm' | 'md' | 'lg';
+    children: ReactNode;
+}
+/**
+ * The shared page wrapper every plugin's own layout or page renders through.
+ *
+ * A plugin owns its page gutter; the runtime shell does not impose one
+ * (task 9.25). The shell still reserves space for chrome a plugin cannot
+ * know about — the offline banner's height and the mobile footer's — but it
+ * contributes no inset of its own, so this component is the single place a
+ * plugin's four-sided padding comes from.
+ */
+declare function PageContainer({ maxWidth, padding, className, children, ...rest }: PageContainerProps): react.JSX.Element;
+
+interface HeaderPlugin {
+    /** Plugin display name, rendered next to its icon. */
+    name: string;
+    /** Plugin icon — already sized (28px) and built by the consumer (typically
+     * an `<img src="/plugin-icons/<id>.svg">`), matching `MobileHeader`'s own
+     * router-agnostic convention for icon-shaped slots. */
+    icon?: ReactNode;
+    /** Where the plugin name/icon links to — typically the plugin's own
+     * `routePrefix`. Omit to render plain (non-interactive) text instead of a
+     * link — e.g. a plugin's own home page linking to itself would be a no-op. */
+    href?: string;
+}
+interface HeaderProps extends HTMLAttributes<HTMLElement> {
+    /** Instance name — derives the brand badge's initial (its first character,
+     * uppercased) and the badge's accessible label. Does not render as text
+     * anywhere in this component (unlike `MobileHeader`'s optional `title`). */
+    instanceName: string;
+    /** Optional instance logo image; falls back to `instanceName`'s initial
+     * (matching the runtime shell's own sidebar/mobile-header fallback). */
+    instanceLogoUrl?: string;
+    /** Where the brand badge links — typically the Launcher plugin's route. */
+    homeHref: string;
+    /** The active plugin, rendered next to the brand badge. Omit for a page
+     * with no single active plugin (e.g. the Launcher itself). */
+    plugin?: HeaderPlugin;
+    /** Apps launcher trigger — already wired by the consumer (icon button plus
+     * whatever popover/drawer it opens). Always rendered, matching
+     * `MobileHeader`'s bell/avatarMenu boundary: this component owns layout
+     * only, never launcher/notification/account interaction logic. */
+    launcher: ReactNode;
+    /** Notification bell trigger — always rendered; not overridable. Same
+     * "just an icon slot" boundary as `MobileHeader`'s own `bell` prop. */
+    notifications: ReactNode;
+    /** Avatar / account menu trigger — always rendered; not overridable. */
+    avatarMenu: ReactNode;
+}
+/**
+ * The web top-bar header: brand badge (+ optional active plugin) on the
+ * left, launcher · notifications · avatar menu on the right. This is the
+ * `shell: minimal` counterpart to the runtime shell's own sidebar — a plugin
+ * that owns its whole viewport (no platform sidebar) renders this instead,
+ * the same way it renders `MobileHeader` in place of the platform's mobile
+ * chrome. Extracted into a shared component so a `shell: minimal` plugin
+ * doesn't have to hand-roll its own top bar from scratch.
+ *
+ * Presentational only — no data fetching, no account/notification/launcher
+ * logic of its own. `launcher`/`notifications`/`avatarMenu` are supplied
+ * fully built, exactly like `MobileHeader`'s `bell`/`avatarMenu`: this
+ * component stays router-agnostic and interaction-agnostic, and never
+ * duplicates a real `AccountMenu`/notification-panel/apps-switcher
+ * implementation.
+ */
+declare function Header({ instanceName, instanceLogoUrl, homeHref, plugin, launcher, notifications, avatarMenu, className, ...rest }: HeaderProps): react.JSX.Element;
+
+interface MobileHeaderProps extends HTMLAttributes<HTMLDivElement> {
+    /** The brand/logo element — already a complete, clickable link home (e.g. an
+     * instance logo wrapped in the consumer's own router `Link`). Always
+     * rendered. `MobileHeader` stays router-agnostic, so this is provided
+     * fully built rather than as a bare icon + href. Optional — omit it to get
+     * a default "S" badge (matching the runtime shell's own fallback brand
+     * icon when no instance logo is configured), sized and styled to the same
+     * 36px/radius-md convention a custom logo is expected to follow. */
+    logo?: ReactNode;
+    /** Optional contextual title rendered beside the logo (e.g. the active
+     * plugin's name). Absent by default — this is the one overridable part of
+     * the header. See RFC 0088. */
+    title?: string;
+    /** Notification bell — always rendered; not overridable.
+     * TODO: this is just an icon slot today (the consumer wires up its own
+     * click handler/content) — it doesn't yet accommodate a full notification
+     * feature (unread badge, dropdown panel, etc. — see the runtime shell's
+     * own NotificationBell). Deferred; revisit once a plugin actually needs
+     * more than a bare bell icon here. */
+    bell: ReactNode;
+    /** Avatar / account menu trigger — always rendered; not overridable. */
+    avatarMenu: ReactNode;
+}
+/**
+ * The mobile header bar: brand/logo (always shown), an optional contextual
+ * title, and a fixed bell + avatar-menu cluster. Owns its own chrome —
+ * background, border-bottom, sticky positioning, safe-area-aware padding,
+ * and a 768px max-width (so it never stretches full-bleed if mounted outside
+ * an actual mobile viewport) — matching the runtime shell's own mobile
+ * header exactly, since this component is meant to replace that hand-rolled
+ * markup. Presentational only — no data fetching; the consumer supplies
+ * `bell`/`avatarMenu` (and, optionally, `logo`) as already-wired components
+ * (their own sizing — 36px logo/avatar, 44px bell tap target — is the
+ * consumer's responsibility, matching the reference implementation in the
+ * runtime shell). See RFC 0088 for the immutable/overridable boundary this
+ * enforces.
+ *
+ * Self-measures its own rendered height and publishes it as
+ * `--sv-shell-header-height` on the shell root — see
+ * `usePublishShellChromeHeight`'s own doc comment for why this exists (it's
+ * what makes a self-rendered header, the `shellConfig.mobileHeader: false`
+ * pattern, correctly position `Dialog`'s inset and any other consumer of
+ * that variable instead of being overlapped by it).
+ */
+declare function MobileHeader({ logo, title, bell, avatarMenu, className, ...rest }: MobileHeaderProps): react.JSX.Element;
+
+interface FooterIcon {
+    icon: ReactNode;
+    label: string;
+    href?: string;
+    onClick?: () => void;
+    active?: boolean;
+}
+interface MobileFooterProps extends HTMLAttributes<HTMLElement> {
+    /** Opens the app drawer/launcher. Always rendered as the centered slot;
+     * not overridable. */
+    onOpenApps: () => void;
+    /** Custom launcher icon (e.g. a plugin-supplied image). Defaults to a
+     * generic grid icon. */
+    launcherIcon?: ReactNode;
+    /** Whether the launcher's own drawer is currently open (applies the
+     * pressed/active visual state). */
+    launcherOpen?: boolean;
+    /** 1 or 2 icons rendered to the left of the centered launcher. */
+    leftIcons: FooterIcon[];
+    /** 1 or 2 icons rendered to the right of the centered launcher. Must match
+     * `leftIcons.length` — the launcher stays visually centered, so a mismatch
+     * is flagged (dev-mode only, never thrown) rather than silently allowed. */
+    rightIcons: FooterIcon[];
+}
+/**
+ * The mobile footer bar: a centered, fixed "Apps" launcher flanked by 1 or 2
+ * overridable icons on each side (3 or 5 total, matching standard
+ * iOS/Android bottom-nav conventions). Owns its own chrome — background,
+ * border-top, safe-area-aware bottom padding, and a 768px max-width (so it
+ * never stretches full-bleed if mounted outside an actual mobile viewport)
+ * — matching the runtime shell's own mobile footer (MobileNav) exactly,
+ * since this component is meant to replace that hand-rolled markup.
+ * Presentational only — no data fetching; the consumer owns the
+ * drawer/overlay `onOpenApps` opens. See RFC 0088 for the
+ * immutable/overridable boundary this enforces.
+ *
+ * Self-measures its own rendered height and publishes it as
+ * `--sv-shell-footer-height` on the shell root — see
+ * `usePublishShellChromeHeight`'s own doc comment for why this exists (it's
+ * what makes a self-rendered footer, the `shellConfig.mobileFooter: false`
+ * pattern, correctly clear `Sheet`/`Drawer`/`Dialog` instead of being
+ * overlapped by them).
+ */
+declare function MobileFooter({ onOpenApps, launcherIcon, launcherOpen, leftIcons, rightIcons, className, ...rest }: MobileFooterProps): react.JSX.Element;
+
+interface MobileAppsDrawerItem {
+    /** Stable identity for this tile — used as the React key. */
+    key: string;
+    icon: ReactNode;
+    label: string;
+    /** Renders an `<a>` when set; otherwise a `<button>` calling `onClick`. */
+    href?: string;
+    onClick?: () => void;
+}
+interface MobileAppsDrawerProps {
+    open: boolean;
+    onClose: () => void;
+    /** Accessible name for the drawer panel — required since there's no
+     *  visible title to fall back to (Drawer's grab handle plus swipe-down /
+     *  scrim-tap already cover dismissal, so no header row is rendered). */
+    'aria-label': string;
+    /** The grid tiles — supplied by the consumer (e.g. installed plugins,
+     *  a plugin's own sections). MobileAppsDrawer owns only the drawer
+     *  chrome/grid layout, never the item list itself. */
+    items: MobileAppsDrawerItem[];
+}
+/**
+ * The mobile "Apps" drawer: a bottom sheet with a 3-column grid of icon
+ * tiles — same tile size (56px, radius 14px) and grid layout as the runtime
+ * shell's own Apps drawer (MobileNav's Drawer content), generalized so the
+ * tile list comes from the consumer (the shell passes installed plugins; a
+ * plugin composing its own MobileFooter launcher passes whatever its own
+ * "apps" are, e.g. a section index) rather than being hardcoded to plugins
+ * specifically. No header row (title/close button) — Drawer's own grab
+ * handle plus swipe-down/scrim-tap dismissal are enough, and a header ate
+ * into the limited vertical space a launcher grid needs most.
+ */
+declare function MobileAppsDrawer({ open, onClose, items, ...rest }: MobileAppsDrawerProps): react.JSX.Element;
 
 interface EmptyStateProps {
     icon?: IconName;
@@ -668,6 +1294,121 @@ interface EmptyStateProps {
 }
 declare function EmptyState({ icon, heading, description, action, className }: EmptyStateProps): react.JSX.Element;
 
+interface OfflineGateProps {
+    children: ReactNode;
+    /** Defaults to a generic "this section" phrasing — pass the surface's own name. */
+    surfaceName?: string;
+    className?: string;
+}
+/**
+ * OfflineGate — blocks administrative/settings surfaces from rendering
+ * (possibly stale) cached content while the device has no network, showing an
+ * explanatory empty state instead (research 0012, epic task 2.32).
+ *
+ * Distinct from `OfflineBanner`: the banner is an informational overlay that
+ * coexists with normal content everywhere in the shell. This is a hard block
+ * for surfaces where operating against stale data is actively wrong — e.g. a
+ * Console user list or an Account billing page reflects a point-in-time
+ * snapshot the moment it's server-rendered, and any cached copy replayed
+ * later has no way to signal that it may already be stale. `OfflineGate`
+ * doesn't try to tell staleness apart from freshness; it removes the
+ * question by not rendering the content at all while offline.
+ *
+ * `children` is rendered unconditionally while online, so this adds no cost
+ * to the common case — it only decides what to show, never how the wrapped
+ * content itself is fetched or cached.
+ */
+declare function OfflineGate({ children, surfaceName, className }: OfflineGateProps): react.JSX.Element;
+
+interface DeviceOnlyGateProps {
+    children: ReactNode;
+    /** Defaults to a generic "this app" phrasing — pass the plugin's own name. */
+    surfaceName?: string;
+    /**
+     * The caller's own `isDeviceOnlyTierAvailable()` result (from
+     * `@sovereignfs/sdk/device-client`) — taken as a plain boolean rather than
+     * computed inside this component, so `@sovereignfs/ui` never depends on
+     * `@sovereignfs/sdk` (this package must stay usable standalone, outside the
+     * plugin runtime — RFC 0073).
+     */
+    available: boolean;
+    className?: string;
+}
+/**
+ * DeviceOnlyGate — blocks a `device-only`-tier plugin's content from
+ * rendering on a surface that cannot provide the durable, encrypted,
+ * device-auth-gated store that tier requires, showing an explanatory empty
+ * state instead of a broken screen (research 0012, epic tasks 2.33 + 3.36).
+ *
+ * A `device-only` plugin wraps its own root content in this the same way
+ * Console and Account wrap theirs in `OfflineGate` — an opt-in pattern each
+ * surface applies to itself, not a platform-level route gate. The launcher
+ * tile's own "Phone only" badge (`useOfflineTileState`) is advisory UI on top
+ * of this; this component is the actual gate, since a user can always reach a
+ * route directly (a bookmark, a deep link) without passing through the
+ * launcher tile at all.
+ *
+ * **Not a security boundary.** Availability here is a capability signal, not
+ * an authorization check — the real protection for `device-only` data is
+ * that it is encrypted and the key requires device auth to release (epic task
+ * 1.22), so it stays inaccessible regardless of whether this gate is present,
+ * bypassed, or simply never reached (e.g. a hand-crafted request against the
+ * plugin's own API routes).
+ */
+declare function DeviceOnlyGate({ children, surfaceName, available, className, }: DeviceOnlyGateProps): react.JSX.Element;
+
+/**
+ * `'checking'` covers the moment before the caller's own async status check
+ * resolves — same transitional-state pattern `EncryptionSection`'s local
+ * `LocalState` uses, so this gate never flashes an empty state before the
+ * real answer is known. `'no-device-auth'` is the hard-block case (RFC 0093
+ * §5, epic task 1.22): the environment supports the tier, but this device
+ * has no passcode, fingerprint, or face unlock configured, so a key cannot
+ * be created here at all — distinct from `'not-set-up'`, where it can.
+ */
+type DeviceStorageKeyGateStatus = 'checking' | 'unsupported' | 'no-device-auth' | 'not-set-up' | 'set-up';
+interface DeviceStorageKeyGateProps {
+    children: ReactNode;
+    /** Defaults to a generic "This app" phrasing — pass the plugin's own name. */
+    surfaceName?: string;
+    /**
+     * The caller's own `getDeviceStorageKeyStatus()` result (from
+     * `@sovereignfs/sdk/device-only-storage`) — taken as a plain status rather
+     * than computed inside this component, so `@sovereignfs/ui` never depends
+     * on `@sovereignfs/sdk` (same boundary `DeviceOnlyGate`'s `available` prop
+     * draws — this package must stay usable standalone, outside the plugin
+     * runtime — RFC 0073).
+     */
+    status: DeviceStorageKeyGateStatus;
+    /**
+     * Rendered under the "not set up" message — typically a link to Account →
+     * Security. Not built in here: this package depends on no router, so the
+     * caller supplies its own navigable element (a plain `<a>`, a framework
+     * `<Link>`, whatever the host app uses).
+     */
+    setupAction?: ReactNode;
+    className?: string;
+}
+/**
+ * DeviceStorageKeyGate — blocks a `device-only`-tier plugin's content until
+ * the user has set up their Device Storage Key (RFC 0093 §2, epic task
+ * 1.22). Distinct from `DeviceOnlyGate`: that one checks whether the *tier
+ * itself* is available on this surface (native shell, secure-storage bridge
+ * present); this one checks whether the user has actually completed the
+ * one-time, per-device enrollment that tier depends on. A `device-only`
+ * plugin typically wants both — `DeviceOnlyGate` outermost (no point
+ * checking enrollment on a surface that cannot offer the tier at all), this
+ * gate inside it.
+ *
+ * Enrollment is centralized and decoupled from any single plugin (RFC 0093
+ * §2): a plugin that finds no key set up does not run its own enrollment
+ * ceremony inline. It stops here and points the user at Account → Security —
+ * the one place enrollment happens for every `device-only` plugin on this
+ * device — via `setupAction`, the same opt-in, self-applied pattern
+ * `OfflineGate`/`DeviceOnlyGate` already use for their own surfaces.
+ */
+declare function DeviceStorageKeyGate({ children, surfaceName, status, setupAction, className, }: DeviceStorageKeyGateProps): react.JSX.Element | null;
+
 interface SpinnerProps {
     size?: 'sm' | 'md' | 'lg';
     label?: string;
@@ -688,12 +1429,25 @@ interface NavTabItem {
     href: string;
     active?: boolean;
 }
+/** Props to spread onto a consumer-supplied link element — keeps NavTabs' own
+ * class names and a11y attributes in sync with whatever the consumer renders. */
+interface NavTabLinkProps {
+    href: string;
+    className: string;
+    'aria-current': 'page' | undefined;
+    children: ReactNode;
+}
 interface NavTabsProps {
     items: NavTabItem[];
     className?: string;
     'aria-label'?: string;
+    /** Render a tab as something other than a plain `<a href>` — e.g. Next's
+     * `<Link replace>` inside an overlay-shell plugin, where a full page
+     * navigation would break the dialog's history contract. Receives the item
+     * plus the class name/aria attributes NavTabs would otherwise apply. */
+    renderLink?: (item: NavTabItem, linkProps: NavTabLinkProps) => ReactNode;
 }
-declare function NavTabs({ items, className, 'aria-label': ariaLabel }: NavTabsProps): react.JSX.Element;
+declare function NavTabs({ items, className, 'aria-label': ariaLabel, renderLink }: NavTabsProps): react.JSX.Element;
 
 interface TooltipProps {
     content: string;
@@ -1043,6 +1797,17 @@ interface MessageScrollerProps {
  * content does not yank them back down — a "New messages" button appears
  * instead, matching the pattern every chat product (Slack, Discord,
  * ChatGPT) already uses.
+ *
+ * A short conversation is bottom-anchored, not left floating at the top of
+ * the container with empty space below it — a leading flex-grow spacer
+ * absorbs the leftover space and collapses to nothing once messages
+ * overflow. Deliberately not `justify-content: flex-end` on the scroll
+ * container itself: Chromium miscomputes `scrollHeight` as equal to
+ * `clientHeight` for an overflowing flex-end-packed column, which makes the
+ * container look fully scrolled to the bottom and permanently hides the
+ * start of a long conversation (confirmed live before choosing this
+ * approach). The spacer keeps `justify-content` at its default, so overflow
+ * scrolling is unaffected.
  */
 declare function MessageScroller({ children, className }: MessageScrollerProps): react.JSX.Element;
 
@@ -1313,6 +2078,48 @@ interface DragHandleRowProps extends HTMLAttributes<HTMLDivElement> {
  */
 declare function DragHandleRow({ children, handleProps, isDragging, className, ...rest }: DragHandleRowProps): react.JSX.Element;
 
+interface GripIconProps {
+    size?: number;
+    className?: string;
+}
+/** Six-dot drag-handle affordance. No baked-in pointer-events or color —
+ *  a consumer that needs `pointer-events: none` (e.g. a button wrapping it)
+ *  or a specific color passes those via `className`/`currentColor`. */
+declare function GripIcon({ size, className }: GripIconProps): react.JSX.Element;
+
+interface StepStripItem {
+    id: string;
+}
+interface StepStripProps<T extends StepStripItem> {
+    items: T[];
+    activeId: string | null;
+    /** Full control over each chip's content, click handling, and (if needed) drag-reorder wiring. */
+    renderItem: (item: T, state: {
+        isActive: boolean;
+        index: number;
+    }) => ReactNode;
+    /** Trailing dashed "add" chip — omit to render the strip with no add affordance. */
+    onAdd?: () => void;
+    addLabel?: string;
+    className?: string;
+    'aria-label'?: string;
+}
+/**
+ * StepStrip — a horizontal, connected sequence of steps (a route or
+ * itinerary strip): ordered chips joined by a thin connector line, with an
+ * optional trailing dashed "add" chip. Purely presentational — it owns
+ * layout and the connector lines, nothing else.
+ *
+ * Each chip's content, active styling, and click handling are entirely up
+ * to `renderItem`; if a consumer needs drag-reorder, `renderItem` attaches
+ * its own dnd-kit `useSortable` ref/listeners to whatever it returns. This
+ * mirrors `DragHandleRow`'s existing split (DS owns chrome, consumer wires
+ * dnd-kit via passed-through props) generalized for a horizontal,
+ * handle-less strip where the whole rendered item — not a separate handle
+ * icon — is both the click target and the drag surface.
+ */
+declare function StepStrip<T extends StepStripItem>({ items, activeId, renderItem, onAdd, addLabel, className, 'aria-label': ariaLabel, }: StepStripProps<T>): react.JSX.Element;
+
 interface FileDropzoneProps {
     /** Native `<input type="file">` `name` attribute — set this to submit the
      * file as part of a native `<form action={...}>` (Server Action) request. */
@@ -1461,6 +2268,63 @@ interface IconPickerProps {
  */
 declare function IconPicker({ value, onChange, options, 'aria-label': ariaLabel, triggerLabel, disabled, className, }: IconPickerProps): react.JSX.Element;
 
+interface ColorPickerSwatch {
+    /** Accessible name and tooltip, e.g. "Sky". */
+    label: string;
+    /** 6-digit hex, e.g. "#b5c9e8". */
+    value: string;
+}
+interface ColorPickerProps {
+    /** Curated quick-pick suggestions, in display order. */
+    swatches: readonly ColorPickerSwatch[];
+    /** Current hex value, or `null` for no color. Compared case-insensitively
+     *  against `swatches` — a value that doesn't match any swatch renders as
+     *  the active "custom" selection instead. */
+    value: string | null;
+    onChange: (value: string | null) => void;
+    /**
+     * Fires once after a discrete, complete pick — a swatch click or the "no
+     * color" click. Optional; most callers don't need it. Deliberately NOT
+     * fired from the native custom-color `<input type="color">`'s `onChange`
+     * — that can fire repeatedly while the user is still dragging inside the
+     * browser's own color dialog, so a caller using this to auto-close a
+     * wrapping `Popover` would otherwise slam it shut mid-adjustment.
+     */
+    onSelectionComplete?: () => void;
+    /** Shows a leading "no color" option. Off by default — most consumers
+     *  (anything painting a fixed-size chip) always need a real color; only
+     *  a board canvas-style consumer typically wants "none" as a real choice. */
+    allowNone?: boolean;
+    noneLabel?: string;
+    /** Accessible name for the native color-input trigger that lets a user
+     *  pick any color, not just a curated swatch. */
+    customLabel?: string;
+    disabled?: boolean;
+    'aria-label': string;
+    className?: string;
+}
+/**
+ * ColorPicker — a row of curated swatch suggestions plus a native
+ * `<input type="color">` trigger for picking any color, not just the
+ * curated set. The native color input is deliberately not a custom-built
+ * hue/saturation picker: it already gives every browser's own full-spectrum
+ * picker (with an eyedropper tool in most), guarantees valid hex output, and
+ * needs no bespoke a11y work of its own.
+ *
+ * `value` drives which affordance reads as selected: a hex matching a
+ * swatch highlights that swatch; a hex matching none of them highlights the
+ * custom trigger instead (its own dial shows that color); `null` (only
+ * meaningful with `allowNone`) highlights the "no color" option.
+ *
+ * The custom trigger shows a plain "+" on a neutral dashed box until a
+ * genuinely custom color is active — it never previews an arbitrary dial
+ * color the user hasn't actually chosen. The underlying native color input
+ * still needs *some* real hex to hold internally at all times (it has no
+ * true empty state), so that starting value stays invisible (`opacity: 0`
+ * on the input itself) rather than painted as this trigger's own swatch.
+ */
+declare function ColorPicker({ swatches, value, onChange, onSelectionComplete, allowNone, noneLabel, customLabel, disabled, 'aria-label': ariaLabel, className, }: ColorPickerProps): react.JSX.Element;
+
 interface QuantityStepperProps {
     value: number;
     onChange: (value: number) => void;
@@ -1711,6 +2575,57 @@ declare const MOBILE_BREAKPOINT_PX = 768;
  */
 declare function useIsMobile(breakpointPx?: number): boolean;
 
+/**
+ * useIsOffline — whether the browser currently has no network connection.
+ *
+ * SSR-safe: always initialises to `false` (online) so the server-rendered HTML
+ * matches the first client render, then reads the real `navigator.onLine`
+ * value in `useEffect`. This picks up the case where the page loaded already
+ * offline (e.g. served from the service-worker cache) at the cost of an
+ * imperceptible one-frame delay before the offline state appears — the same
+ * trade-off `OfflineBanner` makes, which this hook was extracted from so every
+ * consumer shares one connectivity source instead of re-deriving it slightly
+ * differently (research 0012, epic task 2.32).
+ *
+ * Reflects only `navigator.onLine` — true whenever the OS reports a network
+ * interface is up, even without real upstream connectivity (e.g. Wi-Fi with no
+ * internet). That is a known limitation of the browser API itself, not of this
+ * hook; there is currently no better cross-browser signal available.
+ */
+declare function useIsOffline(): boolean;
+
+/**
+ * The two reasons an app tile can be non-interactive, kept structurally
+ * distinct because they have different causes and must never read as the same
+ * thing to a user (research 0012, epic task 2.33):
+ *
+ * - `'connectivity-dimmed'` — a no-offline-tier app, dimmed only while the
+ *   device is **actually offline right now**. Reactive and temporary; clears
+ *   the instant connectivity returns.
+ * - `'capability-restricted'` — a `device-only` app on a surface without the
+ *   durable, encrypted, device-auth-gated store it needs. Static and
+ *   unrelated to connectivity — it stays restricted even when fully online,
+ *   and must never say "offline" to a user who plainly isn't.
+ */
+type OfflineTileState = 'connectivity-dimmed' | 'capability-restricted' | null;
+/**
+ * Which of the two states, if any, applies to an app tile given its declared
+ * offline tier.
+ *
+ * `deviceOnlyAvailable` is the caller's own
+ * `isDeviceOnlyTierAvailable()` result (from
+ * `@sovereignfs/sdk/device-client`) — deliberately taken as a plain boolean
+ * parameter rather than computed inside this hook, so `@sovereignfs/ui` never
+ * depends on `@sovereignfs/sdk` (this package must stay usable standalone,
+ * outside the plugin runtime — RFC 0073).
+ *
+ * An `offline-first` app is never restricted by either state: that tier's
+ * whole point is working with no network, so it stays fully interactive both
+ * online and offline. A `device-only` app that *is* available behaves the
+ * same way — the restriction is about availability, not connectivity.
+ */
+declare function useOfflineTileState(offline: 'offline-first' | 'device-only' | undefined, deviceOnlyAvailable: boolean): OfflineTileState;
+
 interface CommitOnEnterOrBlurHandlers {
     onKeyDown: (e: KeyboardEvent<HTMLInputElement | HTMLTextAreaElement>) => void;
     onBlur: () => void;
@@ -1739,4 +2654,739 @@ interface CommitOnEnterOrBlurHandlers {
  */
 declare function useCommitOnEnterOrBlur(onCommit: () => void): CommitOnEnterOrBlurHandlers;
 
-export { Accordion, type AccordionItem, type AccordionProps, Alert, type AlertProps, type AlertVariant, AspectRatio, type AspectRatioProps, Avatar, type AvatarProps, Badge, type BadgeProps, type BadgeStatus, type BadgeVariant, BalanceChip, type BalanceChipProps, type BannerVariant, Breadcrumb, type BreadcrumbItem, type BreadcrumbProps, Button, ButtonGroup, type ButtonGroupProps, type ButtonProps, type ButtonSize, type ButtonVariant, Calendar, type CalendarProps, Card, type CardProps, CheckableListRow, type CheckableListRowProps, Checkbox, type CheckboxProps, CodeTextarea, type CodeTextareaProps, Collapsible, type CollapsibleProps, Combobox, type ComboboxOption, type ComboboxProps, Command, type CommandItem, type CommandProps, type CommitOnEnterOrBlurHandlers, ConfirmDialog, type ConfirmDialogProps, ContextMenu, type ContextMenuProps, CurrencyInput, type CurrencyInputProps, DataTable, type DataTableColumn, type DataTableProps, DatePicker, type DatePickerProps, Dialog, type DialogProps, type DialogSize, DragHandleRow, type DragHandleRowProps, Drawer, type DrawerProps, EmptyState, type EmptyStateProps, FileDropzone, type FileDropzoneProps, FormField, type FormFieldProps, type FormFieldRenderProps, HoverCard, type HoverCardProps, Icon, type IconName, IconPicker, type IconPickerProps, type IconProps, Input, type InputProps, Item, type ItemProps, Kbd, type KbdProps, Label, type LabelProps, type LongPressHandlers, MOBILE_BREAKPOINT_PX, Marker, type MarkerProps, MemberMultiSelect, type MemberMultiSelectOption, type MemberMultiSelectProps, Menu, MenuEntries, type MenuEntry, type MenuItem, type MenuLabel, type MenuProps, type MenuSeparator, Menubar, type MenubarMenu, type MenubarProps, Message, type MessageProps, MessageScroller, type MessageScrollerProps, type MessageSender, type NavTabItem, NavTabs, type NavTabsProps, NavigationMenu, type NavigationMenuItem, type NavigationMenuProps, OverlayHeader, type OverlayHeaderProps, PageHeader, type PageHeaderProps, Pagination, type PaginationProps, Popover, type PopoverProps, Progress, type ProgressProps, QuantityStepper, type QuantityStepperProps, RadioGroup, type RadioGroupItem, type RadioGroupProps, type ResizableDirection, ResizableHandle, type ResizableHandleProps, ResizablePanel, ResizablePanelGroup, type ResizablePanelGroupProps, type ResizablePanelProps, ScrollArea, type ScrollAreaProps, SegmentedControl, type SegmentedControlProps, type SegmentedOption, Select, type SelectProps, Sheet, type SheetProps, Slider, type SliderProps, type SortDirection, Spinner, type SpinnerProps, type SplitMethod, SplitMethodSelector, type SplitMethodSelectorProps, SplitPane, type SplitPaneProps, StatusBadge, type StatusBadgeProps, type StatusBadgeStatus, SuggestionInput, type SuggestionInputProps, type SuggestionOption, SystemBanner, type SystemBannerProps, type TabItem, Table, TableBody, TableCell, TableHead, TableHeaderCell, type TableProps, TableRow, Tabs, type TabsProps, TagInput, type TagInputProps, Textarea, type TextareaProps, type ToastContextValue, type ToastItem, ToastProvider, Toggle, type ToggleProps, Tooltip, type TooltipProps, Typography, type TypographyProps, type TypographyVariant, type UseLongPressOptions, useCommitOnEnterOrBlur, useDoubleTapHandler, useIsMobile, useLongPress, useOverlaySecondRow, useSingleOrDoubleTap, useToast };
+interface UseSwipeRevealOptions {
+    /** Max reveal distance in px — the row translates by `-revealWidth` when open. */
+    revealWidth: number;
+    /** Whether the reveal is currently open. Controlled by the caller so a
+     *  list of rows can coordinate "only one open at a time" — this hook has
+     *  no open state of its own. */
+    open: boolean;
+    /** Called when a drag releases past the halfway point — the caller should
+     *  set `open` to true. */
+    onOpen: () => void;
+    /** Called when a drag releases before the halfway point — the caller
+     *  should set `open` to false. */
+    onClose: () => void;
+    /** Skip entirely (hooks can't be called conditionally). */
+    disabled?: boolean;
+}
+interface UseSwipeRevealHandlers {
+    onPointerDown: (e: PointerEvent) => void;
+    onPointerMove: (e: PointerEvent) => void;
+    onPointerUp: (e: PointerEvent) => void;
+    onPointerCancel: (e: PointerEvent) => void;
+}
+interface UseSwipeRevealResult {
+    /** Attach to the swipeable row element — the hook writes a live transform
+     *  to it directly during the drag (not via React state) so the row tracks
+     *  the finger at 60fps with no re-render per pointermove. */
+    rowRef: RefObject<HTMLDivElement | null>;
+    /** Spread onto the row's pointer event handlers. */
+    handlers: UseSwipeRevealHandlers;
+}
+/**
+ * useSwipeReveal — horizontal swipe-to-reveal (e.g. Done/Delete actions
+ * behind a list row), extracted from `sovereign-tasks`'s `TaskItem`/
+ * `ListSidebar`, which independently hand-rolled the identical gesture twice
+ * with only `revealWidth` differing (RFC 0079, epic task 9.20).
+ *
+ * Axis-locks on the first 8px of movement (so a vertical scroll or the
+ * carousel's own horizontal swipe-between-slides gesture isn't hijacked by a
+ * diagonal drag) and only resolves to open/closed on release, past the
+ * halfway point of `revealWidth`.
+ */
+declare function useSwipeReveal({ revealWidth, open, onOpen, onClose, disabled, }: UseSwipeRevealOptions): UseSwipeRevealResult;
+
+interface UseSnapCarouselOptions {
+    /** Total number of slides — settle detection clamps to this range. */
+    itemCount: number;
+    /** Called when the user's scroll gesture settles on a different slide
+     *  index than the last one reported. */
+    onSettle?: (index: number) => void;
+    /** Debounce delay (ms) after the last `scroll` event before checking where
+     *  the container settled. Default 120 — matches the value this hook was
+     *  extracted from. Debounced rather than keyed to the `scrollend` event,
+     *  which pre-17.4 iOS Safari/WKWebView doesn't support. */
+    debounceMs?: number;
+    /** The index to seed `liveIndex` with before any scroll event has fired —
+     *  must match whatever the caller initially scrolls/renders to (typically
+     *  the same value used for `SwipableMobileCarousel`'s `activeIndex`).
+     *  Without this, `liveIndex` would start at 0 regardless of where the
+     *  carousel actually opens (e.g. a deep link straight to slide 8),
+     *  briefly unmounting every slide except the first few until the first
+     *  scroll event arrives to correct it. */
+    initialIndex?: number;
+}
+interface UseSnapCarouselResult {
+    /** Attach to the `scroll-snap-type: x` scroll container. */
+    scrollRef: RefObject<HTMLDivElement | null>;
+    /** Imperatively scrolls the container to a slide index. */
+    scrollToIndex: (index: number, behavior?: ScrollBehavior) => void;
+    /** The slide index nearest the container's *current* scroll position,
+     *  updated synchronously on every `scroll` event — not debounced, and not
+     *  the same thing as the last-reported `onSettle` index. See its own
+     *  assignment below for why a consumer needs both. */
+    liveIndex: number;
+}
+/**
+ * useSnapCarousel — debounced "settled slide" detection over a native
+ * `scroll-snap-type: x` container, extracted from `sovereign-tasks`'s
+ * `MobileTasksCarousel` and independently reimplemented in
+ * `sovereign-shopper`'s `MobileShopperCarousel` (RFC 0079, epic task 9.20).
+ * Gives swipe-between-slides physics for free via native scroll-snap, with
+ * this hook only handling "which slide did we land on."
+ */
+declare function useSnapCarousel({ itemCount, onSettle, debounceMs, initialIndex, }: UseSnapCarouselOptions): UseSnapCarouselResult;
+
+interface UseResponsiveLayoutOptions<TWeb, TMobile> {
+    web: TWeb;
+    mobile: TMobile;
+    breakpointPx?: number;
+}
+interface UseResponsiveLayoutResult<TWeb, TMobile> {
+    isMobile: boolean;
+    value: TWeb | TMobile;
+}
+/**
+ * useResponsiveLayout — picks between a `web` and `mobile` value for the
+ * current viewport, built on `useIsMobile` (same breakpoint/SSR-safe-default
+ * behavior, not reimplemented here). Generic over the value type so it works
+ * for JSX (the common case — forking an entire component tree, not just a
+ * class name) or any other per-breakpoint value a plugin wants to pick
+ * without repeating the isMobile-ternary boilerplate every call site.
+ *
+ * This formalizes the `if (isMobile) return <mobile/>; return <web/>;` fork
+ * plugins have hand-rolled per-plugin (e.g. a `MobileAwareShell` component
+ * that swaps an entire routed page tree for a client-only mobile one) —
+ * see `ResponsiveSurface` for the equivalent as a plain JSX component.
+ */
+declare function useResponsiveLayout<TWeb, TMobile>({ web, mobile, breakpointPx, }: UseResponsiveLayoutOptions<TWeb, TMobile>): UseResponsiveLayoutResult<TWeb, TMobile>;
+
+interface UseCarouselRouteSyncOptions {
+    /** Maps the current pathname to a slide index — the caller's own routing
+     *  logic (e.g. special-casing a virtual "starred" slide), unchanged from
+     *  whatever a plugin already has today. This hook has no idea what a
+     *  plugin's routes look like, by design — it never imports a router. */
+    indexForPathname: (pathname: string) => number;
+    /** Inverse mapping — given a settled slide index, the path to navigate to. */
+    pathForIndex: (index: number) => string;
+    /** The current pathname. The caller reads this via their own router (e.g.
+     *  `usePathname()` from `next/navigation`) and passes it in every render —
+     *  this package stays framework-generic and has zero runtime dependencies. */
+    pathname: string;
+    /** Called when this hook wants to navigate — typically
+     *  `(path) => router.replace(path, { scroll: false })`. */
+    onNavigate: (path: string) => void;
+}
+interface UseCarouselRouteSyncResult {
+    /** Feed directly into SwipableMobileCarousel's `activeIndex` prop. */
+    activeIndex: number;
+    /** Feed directly into SwipableMobileCarousel's `onSettle` prop. */
+    onSettle: (index: number) => void;
+}
+/**
+ * useCarouselRouteSync — centralizes the pathname↔slide-index mapping and the
+ * "was this pathname change our own settle, or an external navigation"
+ * distinction that carousel-driving plugins otherwise hand-roll per plugin
+ * (a tapped `<Link>`, browser back/forward, vs. this hook's own
+ * `router.replace` after a swipe settles). Router-agnostic on purpose: the
+ * caller owns the actual `usePathname()`/`router.replace()` calls and only
+ * hands this hook plain values/callbacks.
+ *
+ * Deliberately does not own neighbor-prefetch (SwipableMobileCarousel's
+ * `prefetchDistance`/mount-window covers that) or scroll mechanics (the
+ * carousel component reacts to `activeIndex` changes itself) — this hook is
+ * pathname↔index mapping only, keeping routing glue decoupled from
+ * data-fetching and DOM scrolling.
+ */
+declare function useCarouselRouteSync({ indexForPathname, pathForIndex, pathname, onNavigate, }: UseCarouselRouteSyncOptions): UseCarouselRouteSyncResult;
+
+/**
+ * True when a drag should be allowed to start from `target`. Refused when
+ * `target` sits inside an element marked `data-no-dnd` — a nested control
+ * (e.g. a visibility toggle) opts out so tapping it fires its own handler
+ * instead of lifting the row. Exported standalone so it's unit-testable
+ * without spinning up dnd-kit.
+ */
+declare function shouldHandleDndEvent(target: EventTarget | null): boolean;
+interface UseReorderSensorsOptions {
+    mouseActivationDistancePx?: number;
+    touchActivationDelayMs?: number;
+    touchActivationTolerancePx?: number;
+}
+/**
+ * Sensor set for a `data-no-dnd`-aware drag-reorder list — MouseSensor for
+ * desktop's handle-initiated drag, TouchSensor for mobile's long-press lift
+ * (fixes reordering being unusable on iOS PWA/Safari, which never implements
+ * the native HTML5 Drag-and-Drop API for touch input), KeyboardSensor
+ * unchanged. A bare call keeps the historical 8px/300ms/8px defaults.
+ */
+declare function useReorderSensors(options?: UseReorderSensorsOptions): _dnd_kit_core.SensorDescriptor<_dnd_kit_core.SensorOptions>[];
+
+type SwipeDirection = 'left' | 'right' | 'up' | 'down';
+/** Duration (ms) of both the commit fling-out and the spring-back-under-
+ *  threshold transition. Exported so SwipeStack can hold a just-committed
+ *  card in place for exactly this long before advancing to the next one. */
+declare const SWIPE_STACK_TRANSITION_MS = 220;
+interface UseSwipeStackOptions {
+    /** Directions this drag can move toward and resolve to. A direction left
+     *  out of this list is a wall, not just an unreachable outcome — the card
+     *  will not visually move that way at all (see clampToLiveDirections). */
+    directions: readonly SwipeDirection[];
+    /** Effective distance (px) a drag must cross before release commits to
+     *  that direction instead of springing back. No velocity component — a
+     *  fast short flick under this distance still springs back. */
+    threshold?: number;
+    /** Fires once, synchronously, when a drag (or triggerCommit) resolves to
+     *  a live direction past threshold. This hook has already started the
+     *  fling-out animation on cardRef's element by the time this is called —
+     *  the caller only needs to react to the outcome, not drive the motion. */
+    onCommit: (direction: SwipeDirection) => void;
+    /** Disables both the drag and triggerCommit — e.g. while there is no
+     *  current card to act on. */
+    disabled?: boolean;
+}
+interface UseSwipeStackHandlers {
+    onPointerDown: (e: PointerEvent) => void;
+    onPointerMove: (e: PointerEvent) => void;
+    onPointerUp: (e: PointerEvent) => void;
+    onPointerCancel: (e: PointerEvent) => void;
+}
+interface UseSwipeStackResult {
+    /** Attach to the card element that should translate/rotate with the drag. */
+    cardRef: RefObject<HTMLDivElement | null>;
+    /** Attach to the ancestor of both the card and any direction-stamp
+     *  overlays. The hook writes live drag progress here as CSS custom
+     *  properties (--sv-stack-progress-left/right/up/down, each 0–1) so
+     *  stamps — siblings of the card, not the card itself — can react without
+     *  a re-render per pointermove. */
+    wrapRef: RefObject<HTMLDivElement | null>;
+    handlers: UseSwipeStackHandlers;
+    /** CSS touch-action for the card, derived from which directions are live
+     *  — an axis with nothing configured on it stays native (pan-x/pan-y) so
+     *  a page can still scroll through a stack that only uses the other axis;
+     *  `none` only once both axes are actually needed. */
+    touchAction: string;
+    /** Programmatically commits a direction — the same fling animation and
+     *  onCommit call a real drag past threshold would produce. Backs the
+     *  non-gesture fallback buttons: they are not a separate code path, just
+     *  a different way to call this. No-ops if the direction isn't live or
+     *  the hook is disabled. */
+    triggerCommit: (direction: SwipeDirection) => void;
+}
+/**
+ * useSwipeStack — hand-rolled 4-directional free drag, extending
+ * useSwipeReveal's pattern (raw Pointer Events, a deadzone, transform
+ * written straight to a ref, resolved only on release) from one axis with
+ * two outcomes to four directions with a tilt. Threshold-only on purpose,
+ * matching useSwipeReveal — no velocity tracking, so a fast short flick
+ * under `threshold` still springs back.
+ */
+declare function useSwipeStack({ directions, threshold, onCommit, disabled, }: UseSwipeStackOptions): UseSwipeStackResult;
+
+interface ResponsiveSurfaceProps {
+    web: ReactNode;
+    mobile: ReactNode;
+    breakpointPx?: number;
+}
+/**
+ * ResponsiveSurface — thin JSX convenience wrapper around
+ * `useResponsiveLayout` for the common two-tree case: render an entirely
+ * different component tree below the breakpoint, not a CSS squeeze of the
+ * same one. Renders only whichever side is active — the other tree is never
+ * mounted.
+ *
+ * This does not replace a plugin's own shell component (e.g. a
+ * `MobileAwareShell` that also threads plugin-specific props like a refresh
+ * signal) — those stay a thin per-plugin wrapper around this.
+ */
+declare function ResponsiveSurface({ web, mobile, breakpointPx }: ResponsiveSurfaceProps): react.JSX.Element;
+
+interface SwipableMobileCarouselDotsProps {
+    count: number;
+    activeIndex: number;
+    onJump: (index: number) => void;
+    /** Per-dot accessible names, e.g. ["Lists", "Starred", "Groceries"]. Falls
+     *  back to "Slide N of count" for any index without one. */
+    labels?: (string | undefined)[];
+    /** Labels the whole group — required, no generic fallback (mirrors
+     *  SwipableMobileCarousel's own required aria-label). */
+    'aria-label': string;
+    /** `'compact'` halves the gap between dots (`--sv-space-2` → `--sv-space-1`)
+     *  and shrinks each dot's own hit target (20px → 16px) — for a carousel
+     *  with enough slides that even the reduced gap alone still reads as too
+     *  wide on a narrow viewport (e.g. a many-list mobile app). The visible
+     *  6px dot itself is unchanged; only its surrounding tap-target box
+     *  shrinks. Defaults to `'default'` — every existing consumer's spacing is
+     *  unaffected unless it opts in. */
+    density?: 'default' | 'compact';
+    className?: string;
+}
+/**
+ * SwipableMobileCarouselDots — a real, tappable, labeled slide indicator.
+ * Standalone (not carousel-only): reusable anywhere a set of positions needs
+ * a dot indicator (e.g. an image gallery, an onboarding stepper), and is also
+ * SwipableMobileCarousel's default `renderIndicator`.
+ *
+ * Replaces the `aria-hidden`, non-interactive dots pattern both
+ * sovereign-tasks and sovereign-shopper currently hand-roll — every dot here
+ * is a real `role="tab"` button with its own accessible name, reachable by
+ * keyboard. No roving tabIndex/arrow-key handling: `Tabs` (this library's
+ * other `role="tablist"` component) has none either, so this stays
+ * consistent with it rather than gold-plating past its sibling.
+ */
+declare function SwipableMobileCarouselDots({ count, activeIndex, onJump, labels, 'aria-label': ariaLabel, density, className, }: SwipableMobileCarouselDotsProps): react.JSX.Element;
+
+interface SwipableMobileCarouselIndicatorProps {
+    count: number;
+    activeIndex: number;
+    labels: (string | undefined)[];
+    onJump: (index: number) => void;
+}
+interface SwipableMobileCarouselProps {
+    /** Controlled active slide index — the caller owns this (typically via
+     *  useCarouselRouteSync, or plain useState). */
+    activeIndex: number;
+    /** Called when a swipe gesture settles on a different index, or when the
+     *  reorder-jump fix re-snaps after the active slide's position changes.
+     *  The caller is responsible for updating `activeIndex` in response. */
+    onSettle: (index: number) => void;
+    /** How many slides on each side of the active one stay mounted. Default 1
+     *  matches both sovereign-tasks' and sovereign-shopper's existing "swipe
+     *  never shows a spinner" behavior. Slides outside this window keep their
+     *  DOM slot (so scroll-snap's position-based indexing stays correct) but
+     *  their children are not mounted at all. */
+    prefetchDistance?: number;
+    /** Passed straight through to the internal useSnapCarousel. */
+    settleDebounceMs?: number;
+    /** Required — labels the scroller region for assistive tech. No generic
+     *  fallback, since one would be wrong for every actual consumer. */
+    'aria-label': string;
+    /** Renders the indicator. Defaults to SwipableMobileCarouselDots. Pass
+     *  `null` to render no indicator at all. */
+    renderIndicator?: null | ((props: SwipableMobileCarouselIndicatorProps) => ReactNode);
+    className?: string;
+    /** Must be SwipableMobileCarouselSlide elements (nullish/boolean children
+     *  are safely skipped for conditional slides). A dev-mode warning is
+     *  logged for any other child type — see resolveSlides below. */
+    children: ReactNode;
+}
+/**
+ * SwipableMobileCarousel — a compound component for swiping between full-
+ * width slides (each an independent route/view on mobile), wrapping
+ * useSnapCarousel. This library's first compound component: every other
+ * component here is flat/prop-based, but slide content is large, arbitrary,
+ * per-plugin subtrees that need a header-known/body-loading split an
+ * array-of-objects prop would only express with worse JSX ergonomics.
+ *
+ * Owns rendering and mount-window mechanics only — it has no opinion on
+ * where slide data lives. Do NOT: (a) aggregate cross-slide data inside a
+ * SwipableMobileCarouselSlideBody (that recomputes on every slide render
+ * regardless of which slide is active — belongs in the parent, which
+ * already knows every slide exists); (b) mount a detail overlay (Sheet,
+ * Dialog) inside a Slide's children — mount it as a sibling of
+ * SwipableMobileCarousel instead, controlled by the same state that would
+ * otherwise drive a routed page's overlay. sovereign-tasks' current
+ * hand-rolled carousel does both and is measurably laggier than
+ * sovereign-shopper's equivalent, which keeps its overlay in the routed pane.
+ */
+declare function SwipableMobileCarousel({ activeIndex, onSettle, prefetchDistance, settleDebounceMs, 'aria-label': ariaLabel, renderIndicator, className, children, }: SwipableMobileCarouselProps): react.JSX.Element;
+
+interface SwipableMobileCarouselSlideProps {
+    /** Stable identity for this slide, independent of its position among
+     *  siblings — required. This is what makes SwipableMobileCarousel's
+     *  reorder-jump fix possible: a plain array index can't distinguish "this
+     *  slide moved to position 2" from "this slide was removed and a
+     *  different one is now at position 2." Reuse whatever id the caller
+     *  already keys their `.map()` on (e.g. a list's own id). */
+    slideKey: string;
+    /** Accessible label surfaced to the default dots indicator (e.g.
+     *  "Groceries"). Falls back to "Slide N of count" if omitted — omitting it
+     *  logs a dev-mode warning, since every real slide usually has a title
+     *  available synchronously already. */
+    label?: string;
+    /** SwipableMobileCarouselSlideHeader/Body/Footer, in any order/subset. */
+    children: ReactNode;
+}
+/**
+ * SwipableMobileCarouselSlide — a single slide of a SwipableMobileCarousel.
+ * Renders its children only while within the carousel's mount window (the
+ * active slide ± its configured prefetchDistance); outside that window it
+ * renders nothing, matching both sovereign-tasks and sovereign-shopper's
+ * existing "never fetch/render a non-neighbor slide" behavior, now
+ * centralized instead of hand-rolled per plugin.
+ */
+declare function SwipableMobileCarouselSlide({ children }: SwipableMobileCarouselSlideProps): react.JSX.Element | null;
+
+interface SwipableMobileCarouselSlideHeaderProps {
+    children: ReactNode;
+    className?: string;
+}
+/**
+ * SwipableMobileCarouselSlideHeader — always renders its children, no
+ * loading concept. Meant for content already known synchronously (a list's
+ * title, color, item count from data the caller already has) so it can
+ * render immediately even while SwipableMobileCarouselSlideBody's own
+ * content is still loading — see that component's doc comment.
+ */
+declare function SwipableMobileCarouselSlideHeader({ children, className, }: SwipableMobileCarouselSlideHeaderProps): react.JSX.Element;
+
+interface SwipableMobileCarouselSlideBodyProps {
+    children: ReactNode;
+    /** While true, renders `loadingFallback` INSTEAD OF children — scoped to
+     *  just this region, not the whole slide. This is what fixes the
+     *  "whole slide blanks out, title included, until its own fetch resolves"
+     *  bug: a caller renders `<SwipableMobileCarouselSlideHeader>` from
+     *  already-known metadata unconditionally, and gates only this component's
+     *  `loading` on the slower fetch — the natural way to compose
+     *  Header/Body/Footer as siblings already produces that behavior, instead
+     *  of gating the entire slide behind one boolean. */
+    loading?: boolean;
+    loadingFallback?: ReactNode;
+    className?: string;
+}
+/**
+ * SwipableMobileCarouselSlideBody — the scrollable region of a slide.
+ *
+ * Deliberately does not set `touch-action: pan-y` on its scroll container
+ * (see SwipableMobileCarouselSlideParts.module.css's `.body` rule) — that
+ * would intersect-to-empty against the carousel's own horizontal
+ * touch-action handling (docs/architecture-rules.md's touch-action
+ * intersection rule), breaking both the vertical scroll here and the
+ * horizontal swipe between slides.
+ */
+declare function SwipableMobileCarouselSlideBody({ children, loading, loadingFallback, className, }: SwipableMobileCarouselSlideBodyProps): react.JSX.Element;
+
+interface SwipableMobileCarouselSlideFooterProps {
+    children: ReactNode;
+    className?: string;
+}
+/**
+ * SwipableMobileCarouselSlideFooter — always renders its children, no
+ * loading concept. See SwipableMobileCarouselSlideHeader's doc comment.
+ */
+declare function SwipableMobileCarouselSlideFooter({ children, className, }: SwipableMobileCarouselSlideFooterProps): react.JSX.Element;
+
+interface SwipeDirectionMeta {
+    /** Visible text on the fallback button and the in-drag stamp. */
+    label: string;
+    icon?: IconName;
+}
+interface SwipeStackProps {
+    /** Required — labels the swipeable region for assistive tech. No generic
+     *  fallback, since one would be wrong for every actual consumer. */
+    'aria-label': string;
+    /** Which of the 4 directions are live, and what each is called. A
+     *  direction absent here cannot be dragged toward at all (useSwipeStack
+     *  treats it as a wall) and gets no fallback button or stamp. SwipeStack
+     *  itself has no opinion on what a direction *means* — that vocabulary
+     *  belongs entirely to the caller. */
+    directions: Partial<Record<SwipeDirection, SwipeDirectionMeta>>;
+    /** Fires once a drag (or a fallback button) commits to a direction. Every
+     *  configured direction behaves the same way: the card leaves for good —
+     *  there is no reversible "go back" state. SwipeStack has no opinion on
+     *  where card data lives; the caller is responsible for eventually no
+     *  longer including this cardId in children (e.g. once a mutation lands). */
+    onSwipe: (direction: SwipeDirection, cardId: string) => void;
+    /** Effective drag distance (px) required to commit. Passed straight
+     *  through to useSwipeStack. */
+    threshold?: number;
+    className?: string;
+    /** Must be SwipeStackCard elements (nullish/boolean children are safely
+     *  skipped for conditional cards). A dev-mode warning is logged for any
+     *  other child type — see resolveCards below. */
+    children: ReactNode;
+}
+/**
+ * SwipeStack — a compound component for triaging one card at a time by
+ * dragging it left/right/up/down (wrapping useSwipeStack), plus an
+ * always-visible non-gesture fallback: a button per configured direction,
+ * wired to the identical commit path and exit animation as a real drag.
+ *
+ * Every direction is independently optional and behaves the same way once
+ * triggered — the card leaves for good, there is no reversible "go back".
+ * SwipeStack owns rendering, drag physics, and the stamp/fallback UI only;
+ * it has no opinion on where card data lives or what a direction means —
+ * see SwipeStackProps.onSwipe.
+ */
+declare function SwipeStack({ 'aria-label': ariaLabel, directions, onSwipe, threshold, className, children, }: SwipeStackProps): react.JSX.Element;
+
+interface SwipeStackCardProps {
+    /** Stable identity for this card, independent of its position among
+     *  siblings — required. This is what SwipeStack reads (via child.props,
+     *  not React's own `key`, which a component can't see on itself) to know
+     *  which card is on top and what id to report through onSwipe. Reuse
+     *  whatever id the caller already keys their `.map()` on. */
+    cardId: string;
+    children: ReactNode;
+}
+/**
+ * SwipeStackCard — a single card of a SwipeStack. Unlike
+ * SwipableMobileCarouselSlide, this has no mount-window logic of its own:
+ * SwipeStack only ever renders the top two cards' elements at all (there is
+ * no scroll-position reason to keep every sibling in the DOM the way the
+ * carousel's scroll-snap track does), so there is nothing here to gate.
+ */
+declare function SwipeStackCard({ children }: SwipeStackCardProps): react.JSX.Element;
+
+interface ThreeColumnLayoutProps {
+    /**
+     * Exactly 2 (sidebar, main) or 3 (sidebar, main, detail) elements. Omit
+     * the third child entirely to render two columns — e.g.
+     * `{selected && <Detail />}` — React.Children.toArray drops falsy
+     * children, so no separate `detail` prop is needed to make that
+     * conditional.
+     */
+    children: ReactNode;
+    /** px. Fixed width of the first (leftmost) column. Default 280. */
+    sidebarWidth?: number;
+    /** px. Fixed width of the third column, when present. Default 360. */
+    detailWidth?: number;
+    /**
+     * Hides the sidebar column entirely — no width, no border, no layout box
+     * — while keeping it mounted and every sibling in its own stable position.
+     *
+     * Prefer this over conditionally omitting the sidebar child, or swapping
+     * to a different wrapper when collapsed. Omitting it shifts `main` into
+     * the sidebar slot, and swapping the surrounding element type unmounts
+     * `main`'s entire subtree — silently discarding its React state (a live
+     * stream, unsent composer text, an in-memory-only conversation) on every
+     * collapse toggle. Found live in Warden, whose chat column lost all of
+     * that each time the sidebar was shown or hidden.
+     */
+    sidebarHidden?: boolean;
+    className?: string;
+}
+/**
+ * ThreeColumnLayout — sidebar + main + optional detail column, for the
+ * common "list app" shape (a list sidebar, a primary content list, and a
+ * detail pane that only takes up space once something is selected).
+ *
+ * Purely positional and structural — it has no awareness of what's inside
+ * each slot (no injected landmarks/labels; those belong to the children
+ * themselves) and no responsive behavior of its own. Collapsing further at
+ * narrow desktop/tablet widths (e.g. swapping the detail column for an
+ * overlay) is the consuming plugin's decision; below the mobile breakpoint,
+ * compose with ResponsiveSurface to fork to a different tree entirely.
+ */
+declare function ThreeColumnLayout({ children, sidebarWidth, detailWidth, sidebarHidden, className, }: ThreeColumnLayoutProps): react.JSX.Element;
+
+interface HeaderFooterLayoutProps {
+    /** Main content — required, always fills whatever height header/footer don't claim. */
+    children: ReactNode;
+    header?: ReactNode;
+    footer?: ReactNode;
+    /** px. Fixed height of the header, when present. Default 60 (matches
+     *  MobileHeader/--sv-shell-header-height's own default). */
+    headerHeight?: number;
+    /** px. Fixed height of the footer, when present. Default 60 (matches
+     *  MobileFooter/--sv-shell-footer-height's own default). */
+    footerHeight?: number;
+    className?: string;
+}
+/**
+ * HeaderFooterLayout — header + main + optional footer, both fixed-height
+ * and independently optional, with main always claiming the remaining
+ * height. The vertical counterpart to ThreeColumnLayout: same purely
+ * structural approach (no color/background opinions, no awareness of what's
+ * inside each slot, no responsive behavior of its own — a plain flex
+ * column), just rotated. "Footer always at the bottom" falls out of flex
+ * layout alone; there is no position: fixed or safe-area handling here, so
+ * a caller composing this with the platform shell's own chrome still owns
+ * that separately.
+ */
+declare function HeaderFooterLayout({ children, header, footer, headerHeight, footerHeight, className, }: HeaderFooterLayoutProps): react.JSX.Element;
+
+type RootLayoutVariant = 'plain' | 'sidebar' | 'header' | 'shell';
+interface RootLayoutProps {
+    /**
+     * Which chrome shape this page uses. Children are positional and their
+     * count is fixed per variant:
+     *  - `'plain'` — 1 child: `[main]`. No chrome on either breakpoint.
+     *  - `'sidebar'` — 2 children: `[sidebar, main]`. Sidebar + main on web
+     *    only — on mobile, sidebar is dropped and only main renders.
+     *  - `'header'` — 2 children: `[header, main]`. Header + main on both
+     *    breakpoints — same structure, but the header's own height differs
+     *    per breakpoint (`headerHeight` on web, `mobileHeaderHeight` on
+     *    mobile), matching how real `shell: minimal` plugins actually do
+     *    this (a compact web top bar vs. the platform's mobile chrome
+     *    height).
+     *  - `'shell'` — 3 children: `[header, main, footer]`. Header + main +
+     *    footer on mobile only — on web, header/footer are dropped and only
+     *    main renders.
+     * Default `'plain'`.
+     */
+    variant?: RootLayoutVariant;
+    children: ReactNode;
+    /** px. Default 64 — matches the platform's own persistent nav rail
+     *  (`--sv-shell-sidebar-width`, runtime/app/(platform)/shell.module.css).
+     *  Only used by `'sidebar'`. */
+    sidebarWidth?: number;
+    /** px. Default 48 — matches a real `shell: minimal` plugin's own compact
+     *  web header (e.g. Kanban's `KanbanHeader`, deliberately not the
+     *  platform's 60px shell header since a `shell: minimal` plugin owns its
+     *  whole viewport). Web only — used by `'header'` on web. */
+    headerHeight?: number;
+    /** px. Default 60 — matches the platform's own mobile chrome
+     *  (`--sv-shell-header-height`, `MobileHeader`'s default). Mobile only —
+     *  used by `'header'` and `'shell'` on mobile. */
+    mobileHeaderHeight?: number;
+    /** px. Default 60 — matches the platform's own mobile chrome
+     *  (`--sv-shell-footer-height`, `MobileFooter`'s default). Mobile only —
+     *  used by `'shell'`. */
+    footerHeight?: number;
+    className?: string;
+}
+/**
+ * RootLayout — the root-level layout a plugin's page tree sits in. Enforces
+ * only structure and dimensions (`width: 100%; height: 100%`, filling
+ * whatever real height the platform shell's own ancestor chain already
+ * establishes — not viewport units, since a plugin isn't alone on the
+ * page). A definite height, not min-height: ThreeColumnLayout/
+ * HeaderFooterLayout's own .shell need one to resolve their own height:
+ * 100% against (see RootLayout.module.css's comment). All content comes
+ * from children; RootLayout has no opinion on what's inside any region.
+ *
+ * The web/mobile fork is `ResponsiveSurface` — only one of
+ * `RootLayoutWeb`/`RootLayoutMobile` is ever mounted, never a CSS squeeze of
+ * the same tree. Each variant's actual shape is delegated entirely to
+ * `ThreeColumnLayout`/`HeaderFooterLayout`; RootLayout itself contains no
+ * media queries.
+ */
+declare function RootLayout({ variant, children, sidebarWidth, headerHeight, mobileHeaderHeight, footerHeight, className, }: RootLayoutProps): react.JSX.Element;
+
+type PageLayoutPadding = 'none' | 'sm' | 'md' | 'lg';
+interface PageLayoutProps {
+    /**
+     * A page-specific header — e.g. a board title + search/share toolbar.
+     * Not the app-level header (that's `RootLayout`'s `header`/`shell`
+     * variants) — this is a second, contextual row scoped to this one page.
+     * Renders edge-to-edge above the padded content, outside `padding`.
+     */
+    header?: ReactNode;
+    /** The page gutter. Default `'none'` — unlike `PageContainer`, a bare
+     *  `PageLayout` applies no padding at all; opt in per page. Same four-step
+     *  scale and `--sv-page-gutter` stand-down hook as `PageContainer` (steps
+     *  down at the same 768px breakpoint `Dialog`/`MobileHeader` use). */
+    padding?: PageLayoutPadding;
+    children: ReactNode;
+    className?: string;
+}
+/**
+ * PageLayout — a single page's content area within a plugin (nested inside
+ * `RootLayout`'s `main` slot, not a replacement for it). Enforces only
+ * structure and dimensions; content always comes from props/children.
+ *
+ * `min-width: 100%; min-height: 100%` — safe here (unlike `RootLayout`'s own
+ * root) because `PageLayout` is always nested inside an already
+ * flex-stretched region (`ThreeColumnLayout`/`HeaderFooterLayout`'s
+ * `.main`), and a stretched flex item's cross-size is definite for its
+ * descendants' percentage resolution, so no separate height-cascading fix
+ * is needed the way `RootLayout`'s root required one.
+ */
+declare function PageLayout({ header, padding, children, className }: PageLayoutProps): react.JSX.Element;
+
+interface NavListItem {
+    id: string;
+    label: string;
+    href: string;
+    icon: IconName;
+    /** Trailing content, e.g. a count — reserved for a future consumer, not used by `variant="drilldown"`'s own chevron slot. */
+    badge?: ReactNode;
+    /**
+     * Only meaningful for `variant="static"` — whether this row represents the
+     * current page. Computed by the consumer (e.g. via `usePathname()` plus a
+     * longest-prefix match against every item's `href`), since this package
+     * doesn't depend on `next/navigation` — same reasoning as `NavTabs`.
+     */
+    active?: boolean;
+}
+interface NavListGroup {
+    id: string;
+    /** Omit for an ungrouped leading item/group — e.g. a pinned "Overview" row above the grouped sections. */
+    label?: string;
+    items: NavListItem[];
+}
+/** Props to spread onto a consumer-supplied link element — mirrors `NavTabs`' `NavTabLinkProps`. */
+interface NavListLinkProps {
+    href: string;
+    className: string;
+    'aria-current': 'page' | undefined;
+    children: ReactNode;
+}
+interface NavListProps {
+    groups: NavListGroup[];
+    /**
+     * `"static"`: active row highlighted via `item.active`, no chevron — a
+     * persistent sidebar nav. `"drilldown"`: every row gets a trailing chevron
+     * and no active-state, tapping navigates to a full-screen section — a
+     * native Settings-app style index.
+     */
+    variant: 'static' | 'drilldown';
+    /**
+     * `"default"`: each row is a full `--sv-touch-target-min` tall tap target
+     * — the right choice for `variant="drilldown"`'s mobile index, and for any
+     * `static` sidebar list long enough that scanability matters more than
+     * density. `"compact"` shrinks row height/padding for a short, always-
+     * visible `static` list (e.g. 2-4 items above a longer scrollable list of
+     * something else) where the default's touch-target height reads as
+     * needlessly spaced out. Only meaningful for `variant="static"` —
+     * `drilldown` rows stay full-height regardless, since that variant is
+     * mobile-only and touch-target size there isn't optional. Defaults to
+     * `"default"` so every existing consumer (e.g. Console's own sidebar) is
+     * visually unchanged.
+     */
+    density?: 'default' | 'compact';
+    'aria-label': string;
+    className?: string;
+    /**
+     * Render a row as something other than a plain `<a href>` — e.g. Next's
+     * `<Link>`. Receives the item plus the class name/aria attributes NavList
+     * would otherwise apply, matching `NavTabs`' `renderLink` contract.
+     */
+    renderLink?: (item: NavListItem, linkProps: NavListLinkProps) => ReactNode;
+}
+/**
+ * NavList — a vertical list of icon+label rows, optionally grouped under
+ * section headers. Two presentations of the same `groups` data: `static` (a
+ * persistent sidebar, active item highlighted) and `drilldown` (a
+ * native-Settings-app style index, every row navigates to a full section).
+ *
+ * Framework-agnostic like `NavTabs` — no `next/navigation`/`next/link`
+ * import, no internal pathname reading. Active state and navigation behavior
+ * are supplied by the consumer via `item.active` and `renderLink`.
+ */
+declare function NavList({ groups, variant, density, 'aria-label': ariaLabel, className, renderLink, }: NavListProps): react.JSX.Element;
+
+/**
+ * Sovereign Design System — theme presets (RFC 0094).
+ *
+ * The single source of truth for every built-in theme preset's token
+ * overrides. Deliberately plain data (no CSS-in-JS, no build dependency) so
+ * it can be consumed two ways with zero duplication:
+ *   - `scripts/generate-theme-presets-css.ts` (`pnpm generate:theme-presets`)
+ *     reads this file and emits `theme-presets.css` for Storybook/standalone
+ *     consumers.
+ *   - `runtime/src/instance-style.ts` (RFC 0095) imports `THEME_PRESETS`
+ *     directly and flattens the selected preset into the existing
+ *     `:root { ... }` instance-style injection — no CSS parsing, no second
+ *     copy of these values to drift out of sync.
+ *
+ * Presets are closed and built-in (RFC 0094's "Alternatives considered") —
+ * add a new one here and re-run the generator, never accept arbitrary
+ * operator-supplied values into this shape.
+ *
+ * `'default'` MUST stay `{ light: {}, dark: {} }` — an empty override set is
+ * what guarantees today's look stays byte-identical for every instance that
+ * never opts into a different preset.
+ */
+type ThemePresetName = 'default' | 'neobrutalism';
+declare const THEME_PRESET_NAMES: readonly ThemePresetName[];
+interface ThemePresetTokens {
+    /** Sparse — only tokens this preset overrides. Everything else falls through to the default. */
+    light: Record<string, string>;
+    dark: Record<string, string>;
+}
+declare const THEME_PRESETS: Record<ThemePresetName, ThemePresetTokens>;
+
+export { Accordion, type AccordionItem, type AccordionProps, Alert, type AlertProps, type AlertVariant, AppsLauncher, type AppsLauncherItem, type AppsLauncherProps, AspectRatio, type AspectRatioProps, Avatar, type AvatarProps, Badge, type BadgeProps, type BadgeStatus, type BadgeVariant, BalanceChip, type BalanceChipProps, type BannerVariant, Breadcrumb, type BreadcrumbItem, type BreadcrumbProps, Button, ButtonGroup, type ButtonGroupProps, type ButtonProps, type ButtonSize, type ButtonVariant, Calendar, type CalendarProps, Card, type CardProps, CardTile, CardTileGrid, type CardTileGridProps, type CardTileProps, CheckableListRow, type CheckableListRowProps, Checkbox, type CheckboxProps, CodeTextarea, type CodeTextareaProps, Collapsible, type CollapsibleProps, ColorPicker, type ColorPickerProps, type ColorPickerSwatch, Combobox, type ComboboxOption, type ComboboxProps, Command, type CommandItem, type CommandProps, type CommitOnEnterOrBlurHandlers, ConfirmDialog, type ConfirmDialogProps, ConsentPrompt, type ConsentPromptProps, ContextMenu, type ContextMenuProps, CurrencyInput, type CurrencyInputProps, DataTable, type DataTableColumn, type DataTableProps, DatePicker, type DatePickerProps, DeviceOnlyGate, type DeviceOnlyGateProps, DeviceStorageKeyGate, type DeviceStorageKeyGateProps, type DeviceStorageKeyGateStatus, Dialog, type DialogProps, type DialogSize, DragHandleRow, type DragHandleRowProps, Drawer, type DrawerProps, EmptyState, type EmptyStateProps, FileDropzone, type FileDropzoneProps, type FooterIcon, FormField, type FormFieldProps, type FormFieldRenderProps, GripIcon, type GripIconProps, Header, HeaderFooterLayout, type HeaderFooterLayoutProps, type HeaderPlugin, type HeaderProps, HoverCard, type HoverCardProps, Icon, type IconName, IconPicker, type IconPickerProps, type IconProps, Input, type InputProps, Item, type ItemProps, Kbd, type KbdProps, Label, type LabelProps, LegalLinks, type LegalLinksProps, type LongPressHandlers, MOBILE_BREAKPOINT_PX, Markdown, type MarkdownProps, Marker, type MarkerProps, MemberMultiSelect, type MemberMultiSelectOption, type MemberMultiSelectProps, Menu, MenuEntries, type MenuEntry, type MenuItem, type MenuLabel, type MenuProps, type MenuSeparator, Menubar, type MenubarMenu, type MenubarProps, Message, type MessageProps, MessageScroller, type MessageScrollerProps, type MessageSender, MobileAppsDrawer, type MobileAppsDrawerItem, type MobileAppsDrawerProps, MobileFooter, type MobileFooterProps, MobileHeader, type MobileHeaderProps, NavList, type NavListGroup, type NavListItem, type NavListLinkProps, type NavListProps, type NavTabItem, type NavTabLinkProps, NavTabs, type NavTabsProps, NavigationMenu, type NavigationMenuItem, type NavigationMenuProps, NewCardTile, type NewCardTileProps, NotificationsPanel, type NotificationsPanelItem, type NotificationsPanelProps, OfflineGate, type OfflineGateProps, type OfflineTileState, OverlayHeader, type OverlayHeaderProps, PageContainer, type PageContainerProps, PageHeader, type PageHeaderProps, PageLayout, type PageLayoutPadding, type PageLayoutProps, Pagination, type PaginationProps, Popover, type PopoverProps, Progress, type ProgressProps, QuantityStepper, type QuantityStepperProps, RadioGroup, type RadioGroupItem, type RadioGroupProps, type ResizableDirection, ResizableHandle, type ResizableHandleProps, ResizablePanel, ResizablePanelGroup, type ResizablePanelGroupProps, type ResizablePanelProps, ResponsiveSurface, type ResponsiveSurfaceProps, RootLayout, type RootLayoutProps, type RootLayoutVariant, SWIPE_STACK_TRANSITION_MS, ScrollArea, type ScrollAreaProps, SegmentedControl, type SegmentedControlProps, type SegmentedOption, Select, type SelectProps, Sheet, type SheetProps, Slider, type SliderProps, type SortDirection, Spinner, type SpinnerProps, type SplitMethod, SplitMethodSelector, type SplitMethodSelectorProps, SplitPane, type SplitPaneProps, StatusBadge, type StatusBadgeProps, type StatusBadgeStatus, StepStrip, type StepStripItem, type StepStripProps, SuggestionInput, type SuggestionInputProps, type SuggestionOption, SwipableMobileCarousel, SwipableMobileCarouselDots, type SwipableMobileCarouselDotsProps, type SwipableMobileCarouselIndicatorProps, type SwipableMobileCarouselProps, SwipableMobileCarouselSlide, SwipableMobileCarouselSlideBody, type SwipableMobileCarouselSlideBodyProps, SwipableMobileCarouselSlideFooter, type SwipableMobileCarouselSlideFooterProps, SwipableMobileCarouselSlideHeader, type SwipableMobileCarouselSlideHeaderProps, type SwipableMobileCarouselSlideProps, type SwipeDirection, type SwipeDirectionMeta, SwipeStack, SwipeStackCard, type SwipeStackCardProps, type SwipeStackProps, SystemBanner, type SystemBannerProps, THEME_PRESETS, THEME_PRESET_NAMES, type TabItem, Table, TableBody, TableCell, TableHead, TableHeaderCell, type TableProps, TableRow, Tabs, type TabsProps, TagInput, type TagInputProps, Textarea, type TextareaProps, type ThemePresetName, type ThemePresetTokens, ThreeColumnLayout, type ThreeColumnLayoutProps, type ToastContextValue, type ToastItem, ToastProvider, Toggle, type ToggleProps, Tooltip, type TooltipProps, Typography, type TypographyProps, type TypographyVariant, type UseCarouselRouteSyncOptions, type UseCarouselRouteSyncResult, type UseLongPressOptions, type UseReorderSensorsOptions, type UseResponsiveLayoutOptions, type UseResponsiveLayoutResult, type UseSnapCarouselOptions, type UseSnapCarouselResult, type UseSwipeRevealHandlers, type UseSwipeRevealOptions, type UseSwipeRevealResult, type UseSwipeStackHandlers, type UseSwipeStackOptions, type UseSwipeStackResult, UserMenu, type UserMenuItem, type UserMenuProps, shouldHandleDndEvent, useCarouselRouteSync, useCommitOnEnterOrBlur, useDoubleTapHandler, useIsMobile, useIsOffline, useLongPress, useOfflineTileState, useOverlaySecondRow, useReorderSensors, useResponsiveLayout, useSingleOrDoubleTap, useSnapCarousel, useSwipeReveal, useSwipeStack, useToast };