@qball-inc/react 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,2424 @@
+import * as react from 'react';
+import { PropsWithChildren, CSSProperties, ButtonHTMLAttributes, ReactNode, InputHTMLAttributes, ReactElement, ChangeEvent, ComponentPropsWithoutRef, HTMLAttributes, DependencyList, SVGProps } from 'react';
+import * as Dialog from '@radix-ui/react-dialog';
+import { ToasterProps } from 'sonner';
+export { ToasterProps } from 'sonner';
+import * as TabsPrimitive from '@radix-ui/react-tabs';
+import * as TooltipPrimitive from '@radix-ui/react-tooltip';
+import { RowData, ColumnDef, Row, RowSelectionState, OnChangeFn, ColumnMeta } from '@tanstack/react-table';
+import * as DropdownMenu from '@radix-ui/react-dropdown-menu';
+
+interface SurfaceProps extends PropsWithChildren {
+    /** Inline style overrides merged after the token-driven base. */
+    style?: CSSProperties;
+}
+/**
+ * Smoke primitive that proves the build harness end-to-end: the JSX transform,
+ * the DOM lib, the dual ESM/CJS emit, the `.d.ts` output, and the consumer
+ * import path (RB-3). It is styled ONLY via `@qball-inc/tokens` CSS custom
+ * properties — no hardcoded hex, no box-shadow, no pill radius (DESIGN.md FR4).
+ * The custom properties resolve at runtime from the consumer's token CSS import.
+ */
+declare function Surface({ children, style }: SurfaceProps): react.JSX.Element;
+
+/**
+ * Button — token-driven, framework-agnostic at the CSS layer.
+ *
+ * Styling is delivered entirely by the published `@qball-inc/tokens` CSS: this
+ * component only composes the shipped semantic class names (`.btn`, `.btn--*`)
+ * shown in the `preview/buttons*.html` oracle cards. There is NO component CSS,
+ * no hardcoded hex, no box-shadow, no Tailwind, and no shadcn runtime — the
+ * `.btn` rules (radius `--radius-sm`, border-only focus, the sanctioned loading
+ * spinner) live in `colors_and_type.css` and resolve from the consumer's token
+ * CSS import. DESIGN.md conformance is therefore inherited, not re-authored.
+ *
+ * `icon` and `loading` are layered MODIFIERS (per the oracle: `btn btn--secondary
+ * btn--icon`, `btn btn--primary btn--loading`), not standalone color variants.
+ */
+type ButtonVariant = "primary" | "secondary" | "tertiary" | "ghost" | "destructive";
+interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    /**
+     * Color treatment. Default `primary`. The `destructive` variant signals a
+     * dangerous action with color — always pair it with a text label (or, for an
+     * icon-only destructive control, an `aria-label`) so the meaning is not
+     * carried by color alone (DESIGN.md finance-color-plus-cue).
+     */
+    variant?: ButtonVariant;
+    /** Icon-only square treatment (`.btn--icon`). Pair with `variant` for color; provide an `aria-label`. */
+    icon?: boolean;
+    /** Loading state (`.btn--loading`): hides the label, shows the spinner, sets `aria-busy`, and blocks interaction. */
+    loading?: boolean;
+    /**
+     * Render the single child element instead of a `<button>` (Radix Slot). The
+     * `.btn` classes merge onto the child, so `<Button asChild><a href="…">…</a></Button>`
+     * renders an `<a>` with identical styling. Note: the forwarded `ref` is typed
+     * as `HTMLButtonElement` for the default case; under `asChild` it resolves to
+     * the child's element type at runtime (e.g. `HTMLAnchorElement`).
+     */
+    asChild?: boolean;
+    children?: ReactNode;
+}
+declare const Button: react.ForwardRefExoticComponent<ButtonProps & react.RefAttributes<HTMLButtonElement>>;
+
+/**
+ * Input — token-driven text/numeric input.
+ *
+ * Composes the shipped `.input` class from `@qball-inc/tokens`
+ * (`components.css`), matching the `preview/form-input.html` and
+ * `preview/form-controls.html` oracle cards. Border-only sage focus, error
+ * border, and tabular numerics all live in the published token CSS — this
+ * component authors no CSS and contains no hex.
+ *
+ * `numeric` opts into finance-grade tabular figures (`.num`) and an
+ * `inputMode="decimal"` keypad, following the oracle's `class="input num"
+ * inputmode="decimal"` cell rather than a native `type="number"` (which loses
+ * `inputMode` control and adds spinner chrome).
+ */
+interface InputProps extends InputHTMLAttributes<HTMLInputElement> {
+    /** Numeric variant: tabular figures (`.num`) + decimal keypad for finance contexts. */
+    numeric?: boolean;
+}
+declare const Input: react.ForwardRefExoticComponent<InputProps & react.RefAttributes<HTMLInputElement>>;
+
+/**
+ * Field — label + control + helper/error composition wrapper.
+ *
+ * Renders the shipped `.field` structure from `@qball-inc/tokens`
+ * (`components.css`), matching the `preview/form-controls.html` oracle: a
+ * `.field__label` associated to the control via `htmlFor`/`id`, optional
+ * `.field__help`, and a `.field__error` with `role="alert"`. When `errorText`
+ * is present it sets `aria-invalid` on the child control (which in turn applies
+ * the `.input--error` border) and points `aria-describedby` at the messages.
+ * No component CSS, no hex.
+ */
+type FieldControl = ReactElement<{
+    id?: string;
+    "aria-invalid"?: InputHTMLAttributes<HTMLInputElement>["aria-invalid"];
+    "aria-describedby"?: string | undefined;
+}>;
+interface FieldProps {
+    /** Visible label text, associated to the control. */
+    label: string;
+    /** Optional helper text shown below the control (`aria-describedby`). */
+    helpText?: string;
+    /** Optional error text; when set, marks the control invalid and renders a `role="alert"` message. */
+    errorText?: string;
+    /** Render a required marker (`*`) after the label. */
+    required?: boolean;
+    /** The control element (typically an `Input`); receives `id`, `aria-invalid`, and `aria-describedby`. */
+    children: FieldControl;
+}
+declare function Field({ label, helpText, errorText, required, children }: FieldProps): react.JSX.Element;
+
+/**
+ * Select — custom dropdown (no native `<select>`).
+ *
+ * Radix `@radix-ui/react-select` provides the behavior (keyboard navigation,
+ * focus management, typeahead, portalled panel — AC-2) while the visual surface
+ * is the shipped `@qball-inc/tokens` CSS: the trigger applies `.select` (whose
+ * chevron is a CSS background-image, so no icon dep is needed), and the panel +
+ * items apply `.menu` / `.menu__item` / `.menu__check` — matching the
+ * `preview/select.html` oracle. This is the same "Radix for behavior, shipped
+ * classes for style" pattern as Button's `asChild` Slot. No component CSS, no hex.
+ *
+ * NOTE (visual conformance / token-package concern): Radix exposes item highlight
+ * via `data-highlighted` and selection via `data-state`, whereas the shipped
+ * `.menu__item` tint keys on `:hover` + `[aria-selected]`. The selected item's
+ * check (`.menu__check`, via Radix `ItemIndicator`) always renders; refining the
+ * keyboard-highlight tint to `[data-highlighted]` is a tokens-package edit (a
+ * separate WP / semver event), not a React-component change here.
+ */
+interface SelectProps {
+    /** Controlled selected value. */
+    value?: string;
+    /** Uncontrolled initial value. */
+    defaultValue?: string;
+    /** Fired with the newly selected value. */
+    onValueChange?: (value: string) => void;
+    /** Shown on the trigger when no value is selected. */
+    placeholder?: string;
+    /** Disables the trigger (applies the shipped `.select:disabled` styling). */
+    disabled?: boolean;
+    /** Accessible name for the trigger when there is no associated `<label>`. */
+    "aria-label"?: string;
+    /** `SelectItem` children. */
+    children?: ReactNode;
+    /** className merged onto the `.select` trigger. */
+    className?: string;
+}
+declare const Select: react.ForwardRefExoticComponent<SelectProps & react.RefAttributes<HTMLButtonElement>>;
+interface SelectItemProps {
+    /** The value selected when this item is chosen. */
+    value: string;
+    /** Disables this option. */
+    disabled?: boolean;
+    /** The visible option label. */
+    children?: ReactNode;
+    /** className merged onto the `.menu__item` element. */
+    className?: string;
+}
+declare const SelectItem: react.ForwardRefExoticComponent<SelectItemProps & react.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Switch — token-driven on/off toggle.
+ *
+ * Composes the shipped `.switch` structure from `@qball-inc/tokens`
+ * (`components.css`), matching the `preview/toggle.html` oracle: a `<label class="switch">`
+ * wrapping a visually-hidden native `<input type="checkbox">` and a `.switch__ui`
+ * track. The brand-native SQUARED knob (4px / `var(--radius-sm)` — explicitly NOT
+ * a 9999px pill, FR4) and the sage on-state live entirely in the published token
+ * CSS, driven by the `.switch input:checked + .switch__ui` sibling selector. This
+ * component authors no CSS and contains no hex.
+ *
+ * This is deliberately NOT a Radix Switch wrapper: Radix renders a
+ * `<button role="switch" data-state>` with no native `:checked` input, so the
+ * shipped sibling-selector CSS would never fire. The native checkbox is
+ * keyboard-accessible for free; `role="switch"` upgrades the exposed semantics so
+ * assistive tech announces on/off rather than checked/unchecked.
+ */
+interface SwitchProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "type" | "role" | "children" | "onChange"> {
+    /** Controlled on/off state. Omit (with `defaultChecked`) for an uncontrolled switch. */
+    checked?: boolean;
+    /** Fired with the new boolean state whenever the user toggles. */
+    onCheckedChange?: (checked: boolean) => void;
+    /** Native change handler; fired alongside `onCheckedChange`. */
+    onChange?: (event: ChangeEvent<HTMLInputElement>) => void;
+    /** Optional visible label rendered beside the track (the oracle pattern). */
+    children?: ReactNode;
+    /** className applied to the outer `<label>` (`.switch`), not the hidden input. */
+    className?: string;
+}
+declare const Switch: react.ForwardRefExoticComponent<SwitchProps & react.RefAttributes<HTMLInputElement>>;
+
+interface SegmentedProps {
+    /** Controlled selected value. */
+    value?: string;
+    /** Uncontrolled initial value; ensures one item starts pressed. */
+    defaultValue?: string;
+    /** Fired with the newly selected value (never with empty — no full-deselect). */
+    onValueChange?: (value: string) => void;
+    /** Accessible group label (the control has no visible heading). */
+    "aria-label"?: string;
+    /** `SegmentedItem` children. */
+    children?: ReactNode;
+    /** className applied to the `.segmented` group container. */
+    className?: string;
+}
+declare function Segmented({ value, defaultValue, onValueChange, children, className, "aria-label": ariaLabel, }: SegmentedProps): react.JSX.Element;
+interface SegmentedItemProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "value" | "type" | "aria-pressed"> {
+    /** The value this segment selects. */
+    value: string;
+    children?: ReactNode;
+}
+declare const SegmentedItem: react.ForwardRefExoticComponent<SegmentedItemProps & react.RefAttributes<HTMLButtonElement>>;
+
+/**
+ * SecretInput — masked BYO-key / secret entry with reveal, set, rotate, remove.
+ *
+ * A token-driven className wrapper over the shipped `@qball-inc/tokens` surface
+ * (`components.css` / `colors_and_type.css`), matching the
+ * `preview/secret-input.html` oracle card: a `.field` composition wrapping an
+ * `.input-wrap` (the `.input num` masked field + an `.input-wrap__affix` reveal
+ * toggle) and a `.btn` action row. There is NO behavioral library and NO
+ * component CSS — masking is the native `<input type="password">`, the reveal
+ * toggle flips `type` to `text`, and every visual comes from the shipped token
+ * classes. The two inline styles are structural-only (`display:flex` row +
+ * `gap`/`color` from `var(--*)` tokens), mirroring the oracle's own
+ * `style="color:var(--data-down)"` Delete affordance — no hex, no shadow.
+ *
+ * Security posture (BINDING): the raw secret lives ONLY as the controlled
+ * input's value — it is never duplicated into another node, attribute, or text,
+ * and is never passed to `console.*`. The masked state relies on the native
+ * password mask; the reveal toggle is the only path to plaintext, and only
+ * while held in view. The leak gate in `SecretInput.test.tsx` asserts the
+ * secret is confined to that single input's value and is absent from every
+ * other attribute, all text content, web storage, cookies, and `console.*`.
+ *
+ * State model:
+ * - `isSet={false}` (unset): editable input + a single "Set" affordance.
+ * - `isSet` (set): masked read-only value + "Rotate" + "Remove". "Rotate" opens
+ *   an in-place edit (Update / Cancel) without round-tripping the stored secret.
+ */
+interface SecretInputProps {
+    /** Current input value (controlled). In the masked set-state this is what the consumer chooses to display. */
+    value: string;
+    /** Fired with the new string on each edit (the value, not the DOM event). */
+    onChange: (value: string) => void;
+    /** Commit handler — fired with the current value when the user confirms (Set / Update / Enter). */
+    onSet: (value: string) => void;
+    /** Clear/remove handler — fired when the user removes a stored secret; resets to the unset state. */
+    onRemove: () => void;
+    /** Visible label, associated to the input via `htmlFor`/`id`. */
+    label: string;
+    /** Whether a secret is currently stored. `false` → unset/entry; `true` → masked display with rotate/remove. */
+    isSet?: boolean;
+    /** Disable the whole control. */
+    disabled?: boolean;
+    /** Placeholder shown in the unset/entry state. */
+    placeholder?: string;
+    /** Form field name; pairs with `autocomplete="new-password"` to suppress credential autofill. */
+    name?: string;
+    /** Optional helper text below the field (`aria-describedby`). */
+    helpText?: string;
+    /** Render a required marker (`*`) after the label. */
+    required?: boolean;
+    /** Label for the commit button in the unset state. Default `"Set"`. */
+    setLabel?: string;
+    /** Label for the commit button while rotating an existing secret. Default `"Update"`. */
+    updateLabel?: string;
+    /** Label for the rotate affordance in the set state. Default `"Rotate"`. */
+    rotateLabel?: string;
+    /** Label for the remove affordance in the set state. Default `"Remove"`. */
+    removeLabel?: string;
+    /** Label for the cancel affordance while rotating. Default `"Cancel"`. */
+    cancelLabel?: string;
+    /** `aria-label` for the reveal toggle when masked. Default `"Show secret"`. */
+    showSecretLabel?: string;
+    /** `aria-label` for the reveal toggle when revealed. Default `"Hide secret"`. */
+    hideSecretLabel?: string;
+}
+declare const SecretInput: react.ForwardRefExoticComponent<SecretInputProps & react.RefAttributes<HTMLInputElement>>;
+
+/**
+ * Search — command-palette search/autocomplete built on `cmdk`.
+ *
+ * cmdk supplies the headless behavior (built-in fuzzy filtering, roving
+ * keyboard navigation, combobox/listbox ARIA), and the visuals come entirely
+ * from the shipped `@qball-inc/tokens` classes: the input is painted with
+ * `.input`, the results panel with `.menu`, and each result with `.menu__item`
+ * (the same dropdown surface `Select` paints). cmdk is additive — it ships no
+ * conflicting CSS, so applying the token classes on top is sufficient and no
+ * component CSS is authored (the loading/empty rows use structural padding +
+ * the `--text-muted` token only, mirroring the oracle's inline-token style).
+ *
+ * Filtering is cmdk's built-in matcher over each item's `label`; selecting a
+ * result (click or Enter) fires `onSelect` with the full item object.
+ */
+interface SearchItem {
+    /** Stable identity; used as the React key. */
+    id: string;
+    /** Visible text; also the value cmdk filters against. */
+    label: string;
+    /** Optional group heading the item is bucketed under. */
+    group?: string;
+}
+interface SearchProps {
+    /** The selectable items. */
+    items: SearchItem[];
+    /** Fired with the selected item when a result is chosen (click or Enter). */
+    onSelect: (item: SearchItem) => void;
+    /** Placeholder for the search input. */
+    placeholder?: string;
+    /** Text shown when the query matches no items. Default `"No results found."`. */
+    emptyText?: string;
+    /** Show a loading row instead of (or alongside) results. */
+    isLoading?: boolean;
+    /** Disable the input and all results. */
+    disabled?: boolean;
+    /** Accessible label for the search input + command region. Default `"Search"`. */
+    label?: string;
+}
+declare function Search({ items, onSelect, placeholder, emptyText, isLoading, disabled, label, }: SearchProps): react.JSX.Element;
+
+/** Modal root — owns the open state. Thin alias of Radix `Dialog.Root`. */
+declare const Modal: react.FC<Dialog.DialogProps>;
+/** Opens the modal; wrap a custom trigger element with `asChild`. Alias of `Dialog.Trigger`. */
+declare const ModalTrigger: react.ForwardRefExoticComponent<Dialog.DialogTriggerProps & react.RefAttributes<HTMLButtonElement>>;
+interface ModalContentProps extends ComponentPropsWithoutRef<typeof Dialog.Content> {
+    /** Close when Escape is pressed. Default `true`; set `false` to suppress (AC-6). */
+    closeOnEscape?: boolean;
+    /** Close when the scrim/overlay is clicked. Default `true`; set `false` to suppress (AC-6). */
+    closeOnOverlayClick?: boolean;
+}
+/**
+ * The portalled dialog surface: a `.scrim` overlay + the `.modal` content panel,
+ * fixed-centered. Must contain a `ModalTitle`. Escape / overlay-click close by
+ * default; pass `closeOnEscape={false}` / `closeOnOverlayClick={false}` to suppress.
+ */
+declare const ModalContent: react.ForwardRefExoticComponent<ModalContentProps & react.RefAttributes<HTMLDivElement>>;
+/** Dialog title (`.modal__title`). Required inside `ModalContent` for accessibility. */
+declare const ModalTitle: react.ForwardRefExoticComponent<Omit<Dialog.DialogTitleProps & react.RefAttributes<HTMLHeadingElement>, "ref"> & react.RefAttributes<HTMLHeadingElement>>;
+/** Dialog description / subtitle (`.modal__sub`). */
+declare const ModalDescription: react.ForwardRefExoticComponent<Omit<Dialog.DialogDescriptionProps & react.RefAttributes<HTMLParagraphElement>, "ref"> & react.RefAttributes<HTMLParagraphElement>>;
+/**
+ * Closes the modal. Defaults to the `.modal__x` icon button (for the head);
+ * pass `asChild` to style any element (e.g. a `.btn` Cancel in the footer).
+ */
+declare const ModalClose: react.ForwardRefExoticComponent<Omit<Dialog.DialogCloseProps & react.RefAttributes<HTMLButtonElement>, "ref"> & react.RefAttributes<HTMLButtonElement>>;
+interface AlertModalProps {
+    /** Controlled open state. */
+    open?: boolean;
+    /** Uncontrolled initial open state. */
+    defaultOpen?: boolean;
+    /** Fired when the open state changes. */
+    onOpenChange?: (open: boolean) => void;
+    /** Optional trigger element (wrapped with `asChild`). Omit when controlling `open` externally. */
+    trigger?: ReactNode;
+    /** Confirmation title (required for accessibility). */
+    title: ReactNode;
+    /** Supporting copy explaining the consequence. */
+    description?: ReactNode;
+    /** Optional extra body content between the description and the action row. */
+    children?: ReactNode;
+    /** Label for the confirm action. Default `"Confirm"`. */
+    confirmLabel?: string;
+    /** Label for the cancel action. Default `"Cancel"`. */
+    cancelLabel?: string;
+    /** Fired when the confirm action is chosen (the dialog then closes). */
+    onConfirm?: () => void;
+    /** Style the confirm button as destructive + show the warn badge. Default `true`. */
+    destructive?: boolean;
+    /** Accessible name for the dialog surface. */
+    "aria-label"?: string;
+    /** Structural style overrides merged onto the content panel (e.g. `maxWidth`). */
+    style?: CSSProperties;
+}
+/**
+ * AlertModal — a destructive/blocking confirmation built on Radix `AlertDialog`
+ * (Escape + overlay-click are intentionally NOT close-on-outside by Radix design;
+ * the user must choose Cancel or Confirm). Matches the `preview/modal.html`
+ * confirm-modal oracle: a warn badge + title + description and a ghost Cancel /
+ * destructive Confirm action row.
+ */
+declare function AlertModal({ open, defaultOpen, onOpenChange, trigger, title, description, children, confirmLabel, cancelLabel, onConfirm, destructive, "aria-label": ariaLabel, style, }: AlertModalProps): react.JSX.Element;
+
+interface ToastOptions {
+    /** Secondary body line under the title (`.toast__msg`). */
+    description?: ReactNode;
+    /** Auto-dismiss duration in ms. Default 4000. Pass `Infinity` to require manual dismiss. */
+    duration?: number;
+    /** Accessible label for the close button. Default `"Dismiss"`. */
+    dismissLabel?: string;
+}
+/**
+ * Imperative toast API. Each variant maps to a shipped `.toast--*` accent stripe
+ * + matching icon. Returns the toast id (pass to `toast.dismiss(id)`).
+ */
+declare const toast: {
+    info: (title: ReactNode, options?: ToastOptions) => string | number;
+    success: (title: ReactNode, options?: ToastOptions) => string | number;
+    warning: (title: ReactNode, options?: ToastOptions) => string | number;
+    error: (title: ReactNode, options?: ToastOptions) => string | number;
+    /** Dismiss a specific toast by id, or all toasts when called with no id. */
+    dismiss: (id?: string | number) => string | number;
+};
+/**
+ * Toast provider. Render once at the app root. Defaults to `top-center` (FR /
+ * AC-7) and `unstyled` toasts so the shipped `.toast` classes own all visuals;
+ * any `ToasterProps` may be overridden (e.g. `visibleToasts`, `expand`). Keep
+ * `unstyled` on — overriding it to `false` re-enables Sonner's default card
+ * chrome and breaks the token styling.
+ */
+declare function Toaster({ position, toastOptions, ...rest }: ToasterProps): react.JSX.Element;
+
+/**
+ * Callout — inline banner / message surface, painted with the shipped
+ * `@qball-inc/tokens` `.callout` classes from the `preview/banner.html` oracle.
+ *
+ * This is a purely presentational component (no behavioral library): a tinted
+ * semantic surface with an accent edge, a leading icon (the redundant non-color
+ * cue — finance-color-plus-cue, FR4), an optional title, and a `children` body
+ * slot. Every visual comes from the token CSS — `.callout` / `.callout--{warn,
+ * error,neutral}` / `.callout__{icon,body,title,msg,x}`; there is no component
+ * CSS, no hardcoded color, no box-shadow.
+ *
+ * Callout is the DESIGNATED HOST for app-level disclaimers (the persistent v1
+ * "not financial advice" notice, rate-limit / degraded-data warnings). The
+ * `children` slot accepts rich inline content (text, links, inline elements) so
+ * a disclaimer can carry a "read more" link. The `neutral` variant is the home
+ * for non-urgent informational disclaimers.
+ *
+ * Variant → shipped class (note the abbreviated `warn`): `info` is the base
+ * `.callout` (no modifier), `warning` → `.callout--warn`, `error` →
+ * `.callout--error`, `neutral` → `.callout--neutral`.
+ */
+type CalloutVariant = "info" | "warning" | "error" | "neutral";
+interface CalloutProps {
+    /** Semantic treatment. Default `info` (the base `.callout`). */
+    variant?: CalloutVariant;
+    /** Optional bold lead line (`.callout__title`). */
+    title?: ReactNode;
+    /** Body content (`.callout__msg`) — rich inline content allowed (links, etc.). */
+    children?: ReactNode;
+    /** Render a dismiss (`.callout__x`) button. Default `false` (disclaimers are persistent). */
+    dismissible?: boolean;
+    /** Fired when the dismiss button is clicked. */
+    onDismiss?: () => void;
+    /** Accessible label for the dismiss button. Default `"Dismiss"`. */
+    dismissLabel?: string;
+    /** Render the leading semantic icon. Default `true`. */
+    icon?: boolean;
+    /** className merged onto the `.callout` root. */
+    className?: string;
+}
+declare function Callout({ variant, title, children, dismissible, onDismiss, dismissLabel, icon, className, }: CalloutProps): react.JSX.Element;
+
+/**
+ * Skeleton — content placeholder, painted with the shipped `@qball-inc/tokens`
+ * `.skel` classes from the `preview/loading.html` oracle.
+ *
+ * A purely presentational shimmer placeholder for content that is still loading.
+ * Every visual comes from the token CSS — `.skel` + `.skel--{text,line,title,
+ * block,circle}`; there is no component CSS, no hardcoded color, no box-shadow.
+ *
+ * Reduced-motion is handled by the token CSS, not here: the shipped
+ * `@media (prefers-reduced-motion: reduce)` rule stops `.skel` shimmer entirely
+ * (falls back to a static `--bg-surface` tint), satisfying FR4/NFR5. The
+ * component only applies the class; the conformance is inherited.
+ *
+ * Skeletons are decorative, so the element is `aria-hidden` — announce the
+ * loading state on the surrounding region (e.g. `aria-busy` on the list) rather
+ * than on each placeholder. Prefer a skeleton over a {@link Spinner} for content
+ * that has a known shape (mirror the real layout so it doesn't jump on load).
+ */
+type SkeletonShape = "text" | "line" | "title" | "block" | "circle";
+interface SkeletonProps extends Omit<HTMLAttributes<HTMLSpanElement>, "children"> {
+    /**
+     * Placeholder shape (the shipped `.skel--*` set). Default `line`. The AC's
+     * "rect" is `block` (full-height fill); `circle` is for avatars/icons.
+     */
+    shape?: SkeletonShape;
+    /** Convenience width (e.g. `"46%"`, `120`). Merged onto `style`; overrides `style.width`. */
+    width?: string | number;
+    /** Convenience height (e.g. `32`). Merged onto `style`; overrides `style.height`. */
+    height?: string | number;
+}
+declare function Skeleton({ shape, width, height, className, style, ...rest }: SkeletonProps): react.JSX.Element;
+
+/**
+ * Spinner — the ONE sanctioned loading spinner for the library, painted with the
+ * shipped `@qball-inc/tokens` `.spinner` classes from the `preview/loading.html`
+ * oracle.
+ *
+ * There is exactly one spinner concept in `@qball-inc/react`. This component is
+ * it; no other component file may introduce an alternative rotating-SVG / loading
+ * pattern. The {@link Button} `loading` prop paints the SAME sanctioned loop via
+ * the shipped `.btn--loading` class (it does not compose this component), so a
+ * loading button needs no `<Spinner>`. For an inline wait next to text, or a
+ * spinner alongside button-like content, use `size="sm"` (the `.load-inline`
+ * pattern in the oracle). Every visual comes from the token CSS — `.spinner` +
+ * `.spinner--{sm,lg}`; there is no component CSS, no hardcoded color.
+ *
+ * Reduced-motion is handled by the token CSS, not here: the shipped
+ * `@media (prefers-reduced-motion: reduce)` rule stops `.spinner` rotation
+ * entirely (static ring, no spin), satisfying FR4/NFR5.
+ *
+ * Use a spinner only for true indeterminate waits (a submit in flight, an SSE
+ * reconnect). For content with a known shape, prefer a {@link Skeleton}.
+ */
+type SpinnerSize = "sm" | "md" | "lg";
+interface SpinnerProps extends Omit<HTMLAttributes<HTMLSpanElement>, "children"> {
+    /**
+     * Size. Default `md` — the base `.spinner` (18px). `sm` (13px, `.spinner--sm`)
+     * is the inline / inside-a-button size; `lg` (28px, `.spinner--lg`) is for
+     * full-panel waits. (There is no `--md` modifier — `md` is the base class.)
+     */
+    size?: SpinnerSize;
+    /** Accessible label announced to assistive tech. Default `"Loading"`. */
+    label?: string;
+}
+declare function Spinner({ size, label, className, ...rest }: SpinnerProps): react.JSX.Element;
+
+/**
+ * StateFig — empty- and error-state figures, painted with the shipped
+ * `@qball-inc/tokens` `.state-fig` classes from the `preview/states.html` oracle.
+ *
+ * A centered figure: an icon chip, a headline, an optional supporting line, and
+ * an actions row. Every visual comes from the token CSS — `.state-fig` +
+ * `.state-fig__{icon,title,msg,actions}` + the `--error` modifier; there is no
+ * component CSS, no hardcoded color, no box-shadow.
+ *
+ * Two named exports share the anatomy:
+ * - {@link EmptyStateFig} — the base `.state-fig` (neutral). For "nothing here
+ *   yet" / "no results". The consumer supplies the CTA via `action`.
+ * - {@link ErrorStateFig} — `.state-fig--error` (red icon chip). For a genuine
+ *   failure. A `retry` callback is MANDATORY and renders the primary Retry CTA;
+ *   an optional `onDismiss` renders a secondary Dismiss CTA.
+ *
+ * The icon is a consumer-provided React node (e.g. a `lucide-react` icon) so the
+ * figure stays token-only and icon-swappable. There is no default icon. The
+ * title renders as a `<p class="state-fig__title">` (consistent with the sibling
+ * `Callout`) rather than a fixed heading level, so it never disturbs the
+ * consumer's document outline.
+ */
+interface StateFigBaseProps {
+    /** Icon node rendered in the `.state-fig__icon` chip (e.g. a lucide-react icon). Optional. */
+    icon?: ReactNode;
+    /** Headline (`.state-fig__title`). */
+    title: ReactNode;
+    /** Optional supporting line (`.state-fig__msg`). */
+    body?: ReactNode;
+    /** className merged onto the `.state-fig` root. */
+    className?: string;
+}
+interface EmptyStateFigProps extends StateFigBaseProps {
+    /** CTA slot rendered in `.state-fig__actions` (e.g. a `<Button>` or a link). Optional. */
+    action?: ReactNode;
+}
+interface ErrorStateFigProps extends StateFigBaseProps {
+    /** REQUIRED. Fired when the Retry CTA is activated. */
+    retry: () => void;
+    /** Label for the Retry CTA. Default `"Retry"`. */
+    retryLabel?: string;
+    /** Optional. When provided, renders a secondary Dismiss CTA. */
+    onDismiss?: () => void;
+    /** Label for the Dismiss CTA. Default `"Dismiss"`. */
+    dismissLabel?: string;
+}
+declare function EmptyStateFig({ icon, title, body, action, className }: EmptyStateFigProps): react.JSX.Element;
+declare function ErrorStateFig({ icon, title, body, retry, retryLabel, onDismiss, dismissLabel, className, }: ErrorStateFigProps): react.JSX.Element;
+
+/**
+ * Stat — a single metric tile, painted with the shipped `@qball-inc/tokens`
+ * `.stat` classes from the `preview/stats-meters.html` oracle.
+ *
+ * A label, the main figure (Berkeley Mono tabular display font via `.stat__value`),
+ * an optional unit, an optional delta with a finance-direction treatment, and
+ * optional foot/sparkline slots. Every visual comes from the token CSS — `.stat`
+ * + `.stat__{label,row,value,unit,delta,foot,spark}` + the `--up/--down/--flat`
+ * delta modifiers; there is no component CSS, no hardcoded color, no box-shadow.
+ *
+ * Two binding rules from DESIGN.md (FR4):
+ * - **Missing value renders '—'.** When `value` is `null` or `undefined` the figure
+ *   renders '—' (U+2014 EM DASH) — NEVER '0', an empty string, or any other
+ *   placeholder. A stat with no data must read as "no data", not "zero".
+ * - **Finance color is always paired with a non-color cue.** The delta direction
+ *   drives both the `.stat__delta--{up,down,flat}` color AND a leading ▲/▼/—
+ *   glyph, so color is never the sole signal (RB-8). Matches the oracle's
+ *   '▲ +8.4%' / '▼ −4.7%' / '— flat'.
+ */
+type StatDirection = "up" | "down" | "flat";
+interface StatProps {
+    /** Eyebrow label (`.stat__label`). Optional. */
+    label?: ReactNode;
+    /**
+     * The main figure (`.stat__value`). `null`/`undefined` renders '—' (EM DASH),
+     * never '0'. Numbers render as-is; pre-format (thousands separators, etc.) upstream.
+     */
+    value: number | string | null | undefined;
+    /** Optional unit suffix (`.stat__unit`, e.g. '%'). */
+    unit?: ReactNode;
+    /**
+     * Delta direction. Drives the `.stat__delta--*` finance color AND the ▲/▼/—
+     * non-color cue (FR4). Omit for a stat with no change indicator.
+     */
+    direction?: StatDirection;
+    /** Delta text shown after the directional cue (e.g. '+8.4%'). Rendered only when `direction` is set. */
+    delta?: ReactNode;
+    /** Footnote (`.stat__foot`). Optional. */
+    foot?: ReactNode;
+    /** Inline sparkline slot (`.stat__spark`). Optional (e.g. a future <Sparkline>). */
+    spark?: ReactNode;
+    /** className merged onto the `.stat` root. */
+    className?: string;
+}
+declare function Stat({ label, value, unit, direction, delta, foot, spark, className }: StatProps): react.JSX.Element;
+
+/**
+ * Meter — a horizontal usage / progress bar, painted with the shipped
+ * `@qball-inc/tokens` `.meter` classes from the `preview/stats-meters.html` oracle.
+ *
+ * A head row (label + readout) over a track/fill bar. Every visual comes from the
+ * token CSS — `.meter` + `.meter__{head,label,val,track,fill}` + the `--warn`
+ * (gold) / `--over` (red) threshold modifiers; there is no component CSS, no
+ * hardcoded color, no box-shadow. The `.meter__track` 999px pill is the sanctioned
+ * track carve-out — it lives in `components.css`, not here, so the component never
+ * trips the ≤12px radius deny-rule (FR4).
+ *
+ * `value`/`max` drive the fill width (clamped 0–100%); `variant` selects the
+ * threshold treatment. The track carries `role="meter"` + `aria-valuenow/min/max`.
+ */
+type MeterVariant = "normal" | "warn" | "over";
+interface MeterProps {
+    /** Current value (numerator). */
+    value: number;
+    /** Maximum (denominator). Default `100`. */
+    max?: number;
+    /** Eyebrow label (`.meter__label`). Optional. */
+    label?: ReactNode;
+    /** Readout text (`.meter__val`). Default `"{value} / {max}"`. */
+    readout?: ReactNode;
+    /** Threshold treatment: `warn` (gold fill) / `over` (red fill). Default `normal` (base `.meter`). */
+    variant?: MeterVariant;
+    /** Accessible name for the meter when `label` is not a plain string. */
+    ariaLabel?: string;
+    /** className merged onto the `.meter` root. */
+    className?: string;
+}
+declare function Meter({ value, max, label, readout, variant, ariaLabel, className, }: MeterProps): react.JSX.Element;
+
+/**
+ * Badge — a small status / finance pill, painted with the shipped
+ * `@qball-inc/tokens` `.badge` classes (`components.css`) as shown in the
+ * `preview/colors-data.html` oracle (and in context in `preview/data-table.html`
+ * / the app-chrome previews).
+ *
+ * NOTE — this is the `.badge` finance/status pill, NOT the editorial `.tag`
+ * (`preview/tags.html`, `colors_and_type.css`): those are two distinct shipped
+ * components (SD1 finding D-09). Badge targets `.badge`, never `.tag`.
+ *
+ * Every visual comes from the token CSS — `.badge` + the `--*` variant modifiers
+ * + the optional `.badge__dot`; there is no component CSS, no hardcoded color, no
+ * box-shadow.
+ *
+ * Variants split into two families:
+ * - **Semantic**: `neutral` (base `.badge`), `info`, `success`, `warning`, `error`.
+ * - **Finance**: `up`, `down`, `flat`.
+ *
+ * Variant → shipped class (note the abbreviated `warn`, mirroring `Callout`):
+ * `neutral` is the base `.badge` (no modifier); `warning` → `.badge--warn`;
+ * `info`/`up`/`down` map to their existing classes; `success` → `.badge--success`,
+ * `error` → `.badge--error`, and `flat` → `.badge--flat` are shipped additions
+ * to `components.css` (success = gain green, error = loss red, flat = neutral stone).
+ *
+ * **Finance variants pair color with a non-color cue (FR4 / RB-8).** `up`/`down`/
+ * `flat` render a leading ▲/▼/— glyph so the finance color is never the sole
+ * signal. Semantic variants carry their meaning in the label text.
+ */
+type BadgeVariant = "neutral" | "info" | "success" | "warning" | "error" | "up" | "down" | "flat";
+interface BadgeProps {
+    /** Semantic or finance treatment. Default `neutral` (base `.badge`). */
+    variant?: BadgeVariant;
+    /** Badge content. */
+    children?: ReactNode;
+    /** Render a leading status dot (`.badge__dot`). Default `false`. */
+    dot?: boolean;
+    /** className merged onto the `.badge` root. */
+    className?: string;
+}
+declare function Badge({ variant, children, dot, className }: BadgeProps): react.JSX.Element;
+
+/**
+ * Card — a surface container, painted with the shipped `@qball-inc/tokens`
+ * `.card` class (`colors_and_type.css`) from the `preview/card-featured.html`
+ * and `preview/borders.html` oracles.
+ *
+ * The base `.card` is a static content surface: `var(--bg-surface)` background, a
+ * 0.5px `var(--border-default)` hairline border (intentional sub-pixel — renders
+ * as a hairline on retina; do NOT round up to 1px), `var(--radius-md)` (8px ≤12px)
+ * radius, and `var(--space-md)` padding. There is **no box-shadow** anywhere — the
+ * lift comes from the border weight + tonal surface step (DESIGN.md No-Shadows).
+ *
+ * Two optional states (the `.card--interactive` / `.card--selected`
+ * additions to `colors_and_type.css`):
+ * - `interactive` — a selectable card; the border lifts to sage
+ *   (`var(--color-signal)`) on hover, with a pointer cursor.
+ * - `selected` — applies the selected-surface treatment (sage border + faint sage
+ *   tint).
+ *
+ * All other `<div>` attributes (e.g. `onClick`, `role`, `tabIndex`, `aria-*`) pass
+ * through, so a consumer can make an interactive card fully keyboard-accessible.
+ */
+interface CardProps extends HTMLAttributes<HTMLDivElement> {
+    /** Card content. */
+    children?: ReactNode;
+    /** Selectable card: sage border on hover + pointer cursor. Default `false` (static content card). */
+    interactive?: boolean;
+    /** Apply the selected-surface treatment (`.card--selected`). Default `false`. */
+    selected?: boolean;
+}
+declare function Card({ children, interactive, selected, className, ...rest }: CardProps): react.JSX.Element;
+
+/**
+ * Divider — a horizontal separator, painted with the shipped `@qball-inc/tokens`
+ * `hr, .rule` style (`colors_and_type.css`) from the `preview/borders.html` oracle.
+ *
+ * Renders a native `<hr>` (implicit `role="separator"`, horizontal orientation)
+ * carrying the `.rule` class: a 1px `var(--border-top)` hairline via
+ * `var(--border-default)`, no box-shadow, no hardcoded hex (FR4). The `<hr>`
+ * element is the correct semantics for a thematic break and is announced as a
+ * separator by assistive tech.
+ *
+ * Horizontal only in v1 (the borders.html oracle ships horizontal dividers); a
+ * vertical variant is deferred (no shipped vertical-rule substrate).
+ */
+interface DividerProps extends HTMLAttributes<HTMLHRElement> {
+    /** className merged onto the `.rule` separator. */
+    className?: string;
+}
+declare function Divider({ className, ...rest }: DividerProps): react.JSX.Element;
+
+/**
+ * Tabs — accessible tabbed section switcher built on Radix `Tabs`, painted with
+ * the shipped `@qball-inc/tokens` classes (`.tabs`, `.tab-list`, `.tab`,
+ * `.tab-panel`) from the `preview/tabs.html` oracle.
+ *
+ * Radix supplies the behavior — roving-tabindex keyboard nav (Arrow / Home / End),
+ * the `role="tablist" / "tab" / "tabpanel"` wiring, and `aria-selected` on the
+ * active trigger — while the visual surface is the token CSS. This is the same
+ * "Radix for behavior, shipped classes for style" pattern as `Modal` / `Select`.
+ * There is NO component CSS and NO hardcoded color.
+ *
+ * The active tab's sage label + underline is driven by the shipped
+ * `.tab[aria-selected="true"]` rule, so selection MUST be expressed via
+ * `aria-selected` — which Radix's `Trigger` does. Keyboard focus uses the
+ * library's shared sage `:focus-visible` ring (also shipped in `components.css`).
+ *
+ * Distinct from `Segmented` (a compact boxed inline toggle): Tabs are an
+ * underline list for switching larger content regions.
+ *
+ * Composition (matches the oracle):
+ *   <Tabs defaultValue="overview">
+ *     <TabsList aria-label="Position detail">
+ *       <TabsTrigger value="overview">Overview</TabsTrigger>
+ *       <TabsTrigger value="holdings">Holdings</TabsTrigger>
+ *     </TabsList>
+ *     <TabsContent value="overview">…</TabsContent>
+ *     <TabsContent value="holdings">…</TabsContent>
+ *   </Tabs>
+ */
+type TabsProps = ComponentPropsWithoutRef<typeof TabsPrimitive.Root>;
+type TabsListProps = ComponentPropsWithoutRef<typeof TabsPrimitive.List>;
+type TabsTriggerProps = ComponentPropsWithoutRef<typeof TabsPrimitive.Trigger>;
+type TabsContentProps = ComponentPropsWithoutRef<typeof TabsPrimitive.Content>;
+/** Tabs root — owns the active-tab state (`value` / `defaultValue` / `onValueChange`). */
+declare const Tabs: react.ForwardRefExoticComponent<Omit<TabsPrimitive.TabsProps & react.RefAttributes<HTMLDivElement>, "ref"> & react.RefAttributes<HTMLDivElement>>;
+/** The `role="tablist"` row of triggers (`.tab-list`). */
+declare const TabsList: react.ForwardRefExoticComponent<Omit<TabsPrimitive.TabsListProps & react.RefAttributes<HTMLDivElement>, "ref"> & react.RefAttributes<HTMLDivElement>>;
+/**
+ * A single tab trigger (`.tab`). The active trigger shows the sage label +
+ * underline via `.tab[aria-selected="true"]`; `disabled` dims it.
+ */
+declare const TabsTrigger: react.ForwardRefExoticComponent<Omit<TabsPrimitive.TabsTriggerProps & react.RefAttributes<HTMLButtonElement>, "ref"> & react.RefAttributes<HTMLButtonElement>>;
+/** The panel shown for the active tab (`.tab-panel`). */
+declare const TabsContent: react.ForwardRefExoticComponent<Omit<TabsPrimitive.TabsContentProps & react.RefAttributes<HTMLDivElement>, "ref"> & react.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Sparkline — a tiny inline trend chart, drawn as a pure hand-authored SVG
+ * `<polyline>` over the shipped `@qball-inc/tokens` `.sparkline` wrapper, matching
+ * the `preview/stats-meters.html` oracle (and the in-context sparks in the
+ * app-chrome previews).
+ *
+ * **No chart library (BINDING).** The geometry is computed inline (min/max
+ * normalization to a viewport + linear interpolation between points). Recharts,
+ * D3, Victory, Chart.js, etc. are NOT imported — and although `d3` is an optional
+ * peerDependency of `@qball-inc/react` (for the Candlestick), the
+ * Sparkline must NOT pull it in: it is a lightweight atom.
+ *
+ * **Color comes from `direction`, never from the data (BINDING, FR4 / RB-8).** The
+ * stroke color is applied via the shipped `.trend-{up,down,flat}` helper class
+ * (which sets `color: var(--data-{up,down,flat})`) with `stroke="currentColor"`,
+ * so there is no hardcoded hex and no inline color. The `direction` prop is the
+ * single source of truth — the color is deliberately NOT computed from `data[0]`
+ * vs `data[last]`, which could contradict an explicit prop on stale/out-of-order
+ * data. `direction` IS the directional cue the finance-color-plus-cue rule
+ * requires (a parent embedding the spark should still pair it with a label/arrow).
+ *
+ * **Degenerate data renders safely.** Empty data, a single point, or an
+ * all-identical (genuinely flat) series cannot form a trend line, so the geometry
+ * collapses to a horizontal line at the vertical midpoint — a valid SVG, never a
+ * throw. The color still follows `direction` (pass `direction="flat"` for a flat
+ * series). There is no `box-shadow` anywhere (FR4).
+ */
+type SparklineDirection = "up" | "down" | "flat";
+interface SparklineProps {
+    /** The series to plot. Empty / single-point / all-identical renders a flat midline. */
+    data: number[];
+    /**
+     * Trend direction — the SOLE source of the stroke color (`.trend-{up,down,flat}`
+     * → `var(--data-{up,down,flat})`). Never computed from `data` (BINDING FR4).
+     */
+    direction: SparklineDirection;
+    /** Accessible name for the `role="img"` SVG (required — an unlabeled graphic is an a11y violation). */
+    ariaLabel: string;
+    /** Optional caption shown under the spark (`.sparkline__cap`, e.g. "NVDA · 30d"). */
+    caption?: ReactNode;
+    /** SVG viewport width in user units. Default 64 (a compact inline size; override for a larger context — the oracle uses 90–150). */
+    width?: number;
+    /** SVG viewport height in user units. Default 20 (override to ~30 for the oracle's standalone spark). */
+    height?: number;
+    /** className merged onto the `.sparkline` wrapper. */
+    className?: string;
+}
+declare function Sparkline({ data, direction, ariaLabel, caption, width, height, className, }: SparklineProps): react.JSX.Element;
+
+/**
+ * Tooltip — a hover/focus hint built on Radix `@radix-ui/react-tooltip`, painted
+ * with the shipped `@qball-inc/tokens` inverted-bubble visual from the
+ * `preview/tooltip-avatar.html` oracle. Same "Radix for behavior, shipped classes
+ * for style" pattern as `Modal` / `Select`.
+ *
+ * **Portaled to `<body>` (BINDING, RB-5).** `TooltipContent` renders inside a Radix
+ * `Portal`, so the bubble escapes any transformed / `backdrop-filter` ancestor —
+ * notably the floating `.dock`, which uses `transform: translateX(-50%)` and would
+ * otherwise clip or mis-place a parent-anchored tooltip. This is the same
+ * portal-to-body guarantee applied to `GroundingFlag`.
+ *
+ * **Why `.tip-pop`, not `.tip__pop`.** The shipped `.tip__pop` is a parent-anchored
+ * pure-CSS hover popover (`position:absolute` relative to `.tip`), which cannot be
+ * positioned once the node is portaled to `<body>` — Radix's popper owns placement.
+ * So the content carries the position-agnostic `.tip-pop` token class (an
+ * owner-approved additive variant): the SAME inverted-bubble look (`background: var(--text-primary)`,
+ * `radius-sm`, caret) MINUS the positioning. The lift is the brand no-shadow
+ * treatment — there is NO `box-shadow` (FR4). The caret is Radix's `Arrow`,
+ * token-filled via `.tip-pop__arrow`.
+ *
+ * Composition (wrap the tree once in `TooltipProvider`):
+ *   <TooltipProvider>
+ *     <Tooltip>
+ *       <TooltipTrigger asChild><button>…</button></TooltipTrigger>
+ *       <TooltipContent>Delayed ~15 min on the hobby tier.</TooltipContent>
+ *     </Tooltip>
+ *   </TooltipProvider>
+ */
+/** Wraps the tree (typically once at app root); owns the shared `delayDuration`. Alias of Radix `Tooltip.Provider`. */
+declare const TooltipProvider: react.FC<TooltipPrimitive.TooltipProviderProps>;
+/** A single tooltip; owns its open state. Alias of Radix `Tooltip.Root`. */
+declare const Tooltip: react.FC<TooltipPrimitive.TooltipProps>;
+/** The element the tooltip describes; wrap a custom element with `asChild`. Alias of Radix `Tooltip.Trigger`. */
+declare const TooltipTrigger: react.ForwardRefExoticComponent<TooltipPrimitive.TooltipTriggerProps & react.RefAttributes<HTMLButtonElement>>;
+type TooltipContentProps = ComponentPropsWithoutRef<typeof TooltipPrimitive.Content>;
+/**
+ * The portaled tooltip bubble (`.tip-pop`) + caret (`.tip-pop__arrow`). Defaults
+ * `sideOffset` to 8 (matching the shipped `.tip__pop` gap). Placement, flip, and
+ * collision handling are Radix's; the visual is the shipped token CSS.
+ */
+declare const TooltipContent: react.ForwardRefExoticComponent<Omit<TooltipPrimitive.TooltipContentProps & react.RefAttributes<HTMLDivElement>, "ref"> & react.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Avatar — a user/entity glyph, painted with the shipped `@qball-inc/tokens`
+ * `.avatar` family from the `preview/tooltip-avatar.html` oracle. Two display
+ * modes: an `<img>` (with graceful fallback to initials when it fails to load),
+ * or token-tiled initials derived from `name`. Every visual comes from the token
+ * CSS / token-valued custom properties — no hardcoded hex, no `box-shadow`.
+ *
+ * - **Size**: `sm` (`.avatar--sm`), `md` (the base `.avatar`, no modifier), `lg`
+ *   (`.avatar--lg`), `xl` (`.avatar--xl`). md = base mirrors the Spinner size model.
+ * - **Initials color is deterministic**: the same `name` always maps to the same
+ *   token-backed tile (a `charCodeAt`-sum hash into a small palette of `var(--*)`
+ *   background/foreground pairs). No hardcoded color.
+ * - **Status dot** (`online`/`offline`/`busy`/`away`): a presence indicator, NOT a
+ *   finance signal — so the dot shape itself is the cue and no paired arrow is
+ *   required (this carve-out is intentional, distinct from the finance-color-plus-
+ *   cue rule). `online` is the base `.avatar__status` (gain green); the other three
+ *   map to `--data-flat` / `--data-down` / `--data-warn`. Omitted ⇒ no dot.
+ */
+type AvatarSize = "sm" | "md" | "lg" | "xl";
+type AvatarStatus = "online" | "offline" | "busy" | "away";
+interface AvatarProps {
+    /** Image source. When set (and the image loads), renders an `<img>`; otherwise falls back to initials. */
+    src?: string;
+    /** Alt text for the image. Falls back to `name` then empty (decorative). */
+    alt?: string;
+    /** Display name — drives the initials AND the deterministic tile color; also the image-fallback content. */
+    name?: string;
+    /** Size variant. Default `md` (the base `.avatar`). */
+    size?: AvatarSize;
+    /** Presence status dot. Omitted ⇒ no dot. */
+    status?: AvatarStatus;
+    /** Round (circular) avatar (`.avatar--round`). Default `false` (squared, `--radius-sm`). */
+    round?: boolean;
+    /** className merged onto the `.avatar` root. */
+    className?: string;
+}
+declare function Avatar({ src, alt, name, size, status, round, className, }: AvatarProps): react.JSX.Element;
+interface AvatarGroupProps {
+    /** The `Avatar` instances to stack. */
+    children: ReactNode;
+    /** Cap the visible avatars; the remainder collapse into a `+N` overflow tile. */
+    max?: number;
+    /** Round the overflow tile to match round group members. Default `false`. */
+    round?: boolean;
+    /** className merged onto the `.avatar-group` root. */
+    className?: string;
+}
+/**
+ * AvatarGroup — overlapping stack of `Avatar`s (`.avatar-group`, negative-margin
+ * overlap from the token CSS). With `max`, the overflow collapses into a single
+ * token-tinted `+N` tile (info blue, matching the oracle).
+ */
+declare function AvatarGroup({ children, max, round, className }: AvatarGroupProps): react.JSX.Element;
+
+/**
+ * DataTable — a compact, finance-aware data table, painted with the shipped
+ * `@qball-inc/tokens` `.dt` classes from the `preview/data-table.html` oracle and
+ * built on **TanStack Table** (`@tanstack/react-table`) as the headless core.
+ *
+ * The visual surface is entirely the token CSS — `.dt` + `.dt thead th`,
+ * `.dt td.num`, `.dt .up/.down/.flat`, the `:hover` tint, the `[aria-selected]`
+ * sage selection, and `.dt__remove` actions — so there is no component CSS, no
+ * hardcoded color, no box-shadow. The component only wires the headless row model
+ * to that surface and composes the state figures.
+ *
+ * Headless-only for v1: it renders the core row model (no built-in sorting or
+ * filtering UI — the oracle shows none). Consumers drive sorting/selection via
+ * TanStack's APIs through the pass-through props.
+ *
+ * Three binding rules from DESIGN.md (FR4) carried by this surface:
+ * - **Finance color is always paired with a non-color cue.** A column marked
+ *   `meta.finance` renders the `.num .up/.down/.flat` color AND a leading `+`/`−`
+ *   sign (mirroring the oracle's `+1.24%` / `−2.34%`), so color is never the sole
+ *   signal (RB-8). The cue is the sign, not an arrow — matching `data-table.html`.
+ * - **One Skeleton, one StateFig.** Loading composes {@link Skeleton}; empty/error
+ *   compose {@link EmptyStateFig} / {@link ErrorStateFig} — never re-implemented.
+ * - **Reduced-motion is inherited**, not overridden: the only animation is the
+ *   Skeleton shimmer, whose `prefers-reduced-motion` rule lives in the token CSS.
+ */
+declare module "@tanstack/react-table" {
+    interface ColumnMeta<TData extends RowData, TValue> {
+        /** Right-aligned tabular `.num` cell (display font + tabular-nums). */
+        numeric?: boolean;
+        /**
+         * Directional finance cell: pairs the `--data-up/down/flat` color (`.up/.down/.flat`)
+         * with a leading `+`/`−` sign cue (FR4). Implies {@link numeric}. The column's
+         * accessor value MUST be a number; non-numbers fall back to the default cell.
+         */
+        finance?: boolean;
+        /**
+         * Formats a finance cell's number into its display string. The result must keep
+         * the directional sign as the non-color cue. Default: signed 2-decimal percent
+         * (`+1.24%` / `−2.34%`), matching the oracle's `sign()`.
+         */
+        financeFormat?: (value: number) => string;
+        /**
+         * Mobile card-list label. At <=640px (container width) the table
+         * reflows to stacked cards and each cell surfaces its column header inline via
+         * `td::before { content: attr(data-label) }`. CSS cannot read thead text, so the
+         * label is sourced from a `data-label` attribute the component sets: the column's
+         * `header` when it is a plain string, else this `meta.label`. A column with a
+         * non-string (ReactNode) header and NO `meta.label` renders an empty mobile label.
+         */
+        label?: string;
+    }
+}
+/** Public alias for a DataTable column's `meta` shape (the augmented ColumnMeta). */
+type DataTableColumnMeta = ColumnMeta<unknown, unknown>;
+interface DataTableProps<TData> {
+    /** TanStack column definitions. Mark numeric/finance columns via `meta`. */
+    columns: ColumnDef<TData, unknown>[];
+    /** Row data. An empty array (with `loading=false`, no `error`) renders the empty figure. */
+    data: TData[];
+    /** When true, the header renders but each body cell shows a {@link Skeleton}. Wins over error/empty. */
+    loading?: boolean;
+    /** Number of skeleton rows rendered while `loading`. Default `4`. */
+    skeletonRowCount?: number;
+    /** When set (and `loading=false`), renders {@link ErrorStateFig} in the body. */
+    error?: string | Error;
+    /** Title for the error figure. Default `"Couldn't load data"`. */
+    errorTitle?: ReactNode;
+    /**
+     * Wired to the error figure's Retry CTA. If omitted, the Retry button still
+     * renders but does nothing — provide it whenever an `error` is possible.
+     */
+    onRetry?: () => void;
+    /** Headline for the empty figure (overrides the default). */
+    emptyMessage?: ReactNode;
+    /**
+     * Optional trailing actions cell per row (e.g. a `.dt__remove` button),
+     * right-aligned. Adds a synthetic column with the reserved id `__actions` — do
+     * not define a column with that id.
+     */
+    actions?: (row: TData) => ReactNode;
+    /** Pin the hover-reveal actions visible (default: reveal on row hover). */
+    actionsAlwaysVisible?: boolean;
+    /** Enable TanStack row selection; selected rows get `aria-selected="true"` (sage tint). */
+    enableRowSelection?: boolean | ((row: Row<TData>) => boolean);
+    /**
+     * Controlled row-selection state. For controlled mode pass BOTH `rowSelection`
+     * AND `onRowSelectionChange`; passing only one freezes selection (TanStack's
+     * controlled-state contract). Omit both to let TanStack manage selection
+     * internally (uncontrolled).
+     */
+    rowSelection?: RowSelectionState;
+    /** Controlled row-selection change handler. Pair with `rowSelection`. */
+    onRowSelectionChange?: OnChangeFn<RowSelectionState>;
+    /** Stable row id (TanStack `getRowId`). Defaults to the row index. */
+    getRowId?: (originalRow: TData, index: number) => string;
+    /** className merged onto the `.dt` table root. */
+    className?: string;
+}
+declare function DataTable<TData>({ columns, data, loading, skeletonRowCount, error, errorTitle, onRetry, emptyMessage, actions, actionsAlwaysVisible, enableRowSelection, rowSelection, onRowSelectionChange, getRowId, className, }: DataTableProps<TData>): react.JSX.Element;
+
+/**
+ * Candlestick — a finance OHLC candlestick chart drawn with **D3** as a React
+ * "island", matching the `preview/chart-candlestick-color.html` (color) and
+ * `preview/chart-candlestick-chrome.html` (compact vs. detail chrome) oracles.
+ *
+ * **D3 owns the SVG subtree; React never reconciles its children (BINDING, RB-4).**
+ * All drawing happens inside a single `useEffect` keyed on
+ * `[data, range, theme, width, height, interactive, showGrid, showAxis]`. The
+ * effect's cleanup nulls every registered listener (`.on(type, null)`),
+ * interrupts any running transition, and clears the SVG (`selectAll('*').remove()`)
+ * so no D3 selection, event handler, or timer survives an unmount or a re-key —
+ * the no-leaked-listeners obligation. The only React-owned node is the HTML OHLC
+ * tooltip rendered OUTSIDE the `<svg>`.
+ *
+ * **No charting library but D3 (BINDING).** Recharts/Victory/Chart.js are NOT
+ * imported. `d3` is an OPTIONAL peerDependency of `@qball-inc/react` (it is large,
+ * ~580 KB, and consumers that already ship D3 must not double-bundle it). A
+ * consumer that renders `Candlestick` must install `d3` themselves; the optional
+ * meta only suppresses the install warning — it does not make the chart work
+ * without D3.
+ *
+ * **Color comes from tokens, never hardcoded hex (BINDING, FR4 / RB-8).** Up
+ * candles (close ≥ open) carry the shipped `.trend-up` class, down candles
+ * `.trend-down` (both set `color: var(--data-{up,down})`); the wick + body draw
+ * with `currentColor`, so the candle color is the token, theme-aware via the
+ * ambient `[data-theme]` cascade — exactly the Sparkline mechanism. Axes, grid,
+ * crosshair, and the SVG frame are styled inline with `var(--token)` references
+ * (`--text-muted`, `--border-default`, `--bg-surface`, …), so there is no
+ * hardcoded color anywhere and no component CSS is added to `@qball-inc/tokens`.
+ *
+ * **Color is never the sole finance signal (FR4).** The OHLC tooltip pairs the
+ * up/down color with a directional `▲`/`▼` arrow and a signed change value, so the
+ * direction reads without relying on color perception.
+ *
+ * **Controlled `range`; `theme` is a redraw signal.** `range` is a controlled prop
+ * — the range toggle calls `onRangeChange(next)` and the parent re-passes `range`
+ * (the component never mutates a passed `range`). The `theme` prop does not carry
+ * the palette (the tokens do, via `[data-theme]`); it is a dependency of the draw
+ * effect so a host theme flip re-keys the redraw (AC-6/AC-8) and no stale
+ * JS-derived value survives.
+ *
+ * **Degenerate data renders safely.** Empty or single-point data draws an empty,
+ * valid `<svg>` (axes/candles are skipped) rather than throwing.
+ */
+/** A discrete time range the chart can be toggled between. */
+type CandlestickRange = "1D" | "5D" | "1M" | "3M" | "1Y";
+/** One OHLCV bar. Price fields are in the instrument's quote currency. */
+interface CandlestickDatum {
+    /** Bar timestamp — a `Date` or any `Date`-parseable string (e.g. ISO 8601). */
+    date: Date | string;
+    /** Opening price. @unit quote currency (e.g. USD) */
+    open: number;
+    /** Session high. @unit quote currency (e.g. USD) */
+    high: number;
+    /** Session low. @unit quote currency (e.g. USD) */
+    low: number;
+    /** Closing price. @unit quote currency (e.g. USD) */
+    close: number;
+    /** Traded volume (optional; not plotted in v1). @unit shares */
+    volume?: number;
+}
+interface CandlestickProps {
+    /** The OHLC series, oldest-first. Empty / single-point renders a safe empty chart. */
+    data: CandlestickDatum[];
+    /** The selected range (controlled). The toggle calls `onRangeChange`; the parent re-passes this. */
+    range?: CandlestickRange;
+    /** Which range toggles to render. Default: all five. Pass `[]` to hide the toggle row. */
+    ranges?: CandlestickRange[];
+    /** Called when a range toggle is pressed, with the selected range. */
+    onRangeChange?: (range: CandlestickRange) => void;
+    /**
+     * Redraw signal. The tokens own the palette (via `[data-theme]`); this prop is a
+     * draw-effect dependency so a host theme flip re-keys the redraw. Optional.
+     */
+    theme?: "light" | "dark";
+    /** Explicit SVG viewport width (user units). Omit to fill the container via `ResizeObserver`. */
+    width?: number;
+    /** SVG viewport height (user units). Default 300. */
+    height?: number;
+    /** Crosshair + OHLC tooltip on pointer. Default `true`. `false` = the compact, static card view. */
+    interactive?: boolean;
+    /** Draw the dashed horizontal grid. Default: follows `interactive`. */
+    showGrid?: boolean;
+    /** Draw the price + date axes. Default `true`. `false` = bare candles (inline preview). */
+    showAxis?: boolean;
+    /** Accessible name for the chart's `role="img"` SVG. Default `"Candlestick chart"`. */
+    ariaLabel?: string;
+    /** Called after every (re)draw completes — useful for redraw assertions / screenshot timing. */
+    onDraw?: () => void;
+    /** className merged onto the `.candlestick` figure wrapper. */
+    className?: string;
+}
+declare function Candlestick({ data, range, ranges, onRangeChange, theme, width: widthProp, height: heightProp, interactive, showGrid, showAxis, ariaLabel, onDraw, className, }: CandlestickProps): react.JSX.Element;
+
+/**
+ * AppBar — the application top bar.
+ *
+ * Painted with the shipped `@qball-inc/tokens` classes `.appbar` / `.appbar__brand` /
+ * `.appnav` / `.appbar__spacer` / `.appbar__right` (matching the
+ * `preview/app-chrome-traditional.html` oracle). All content is injected via slots
+ * (`brand`, `nav`, `actions`) — no hardcoded brand assets or nav items.
+ *
+ * Hybrid chrome (owner decision, S83) — defaults to a plain in-flow bar; opts into the
+ * Stocky prototype's glass-floating + hide-on-scroll behavior:
+ *   - `floating`     — glass overlay (position:absolute top:0, z-index, backdrop-filter
+ *                      blur + translucent bg, transition). Mirrors
+ *                      docs/stocky-app/prototype/dashboard.css `.appbar`. The host shell
+ *                      should be `position: relative; overflow: hidden`. The shipped
+ *                      `.appbar` bottom hairline persists in float mode (the prototype
+ *                      keeps it too).
+ *   - `hidden`       — applies the hide transform (`translateY(-130%)` + fade). Use with
+ *                      `floating`. Drives the same `.appbar--hidden` look as the prototype.
+ *   - `hideOnScroll` — opt-in self-managed behavior reproducing the prototype: hide WHILE
+ *                      scrolling (either direction), spring back 220ms after scroll STOPS.
+ *                      Implies `floating`. `scrollContainer` selects the scroll source
+ *                      (default `window`; the prototype scrolls an inner `.main` pane).
+ *                      The listener is cleaned up on unmount (no leak).
+ *
+ * Glass + hide styles are applied as inline structural styles (no hex, no box-shadow) —
+ * DESIGN_DENY clean; `backdrop-filter` here is the sanctioned chrome-glass use.
+ */
+interface NotificationBellProps extends ComponentPropsWithoutRef<"button"> {
+    /**
+     * Unread count. Renders the `.badge-count` overlay when `>= 1`; omits it when `0` or
+     * `undefined`. The live value is produced by NotificationCenter; this is the
+     * passive data surface.
+     */
+    unreadCount?: number;
+    /** Custom bell icon node; defaults to the shipped outline bell SVG. */
+    children?: ReactNode;
+}
+/**
+ * The bell icon button + unread-count badge, for the AppBar `actions` cluster. A `.iconbtn`
+ * hosting the bell SVG; the `unreadCount` prop drives the overlaid `.badge-count` span.
+ */
+declare const NotificationBell: react.ForwardRefExoticComponent<NotificationBellProps & react.RefAttributes<HTMLButtonElement>>;
+interface AppBarProps extends Omit<ComponentPropsWithoutRef<"header">, "hidden"> {
+    /** Brand slot (logo / wordmark) — rendered in `.appbar__brand`. */
+    brand?: ReactNode;
+    /** Primary navigation slot — wrapped in `<nav className="appnav">`. */
+    nav?: ReactNode;
+    /** Right-cluster slot (search, NotificationBell, ThemeToggle, UserMenu) — `.appbar__right`. */
+    actions?: ReactNode;
+    /** Render as a glass floating overlay (position:absolute, z-index, backdrop blur). */
+    floating?: boolean;
+    /** Apply the hide transform (`translateY(-130%)` + fade). Use with `floating`. */
+    hidden?: boolean;
+    /** Self-manage hide-while-scrolling + 220ms spring-back (implies `floating`). */
+    hideOnScroll?: boolean;
+    /** Scroll source for `hideOnScroll`. Default `window`. */
+    scrollContainer?: HTMLElement | Window | null;
+}
+declare const AppBar: react.ForwardRefExoticComponent<AppBarProps & react.RefAttributes<HTMLElement>>;
+
+/**
+ * UserMenu — the app-bar user action menu, built on Radix `DropdownMenu`.
+ *
+ * Radix supplies the behavior (keyboard navigation — Arrow Up/Down cycle items,
+ * Enter activates, Escape closes, focus returns to the trigger — plus the portalled
+ * panel and focus management) while the visual surface is the shipped `@qball-inc/tokens`
+ * classes: the trigger applies `.usermenu` (whose hover/open tint keys on the
+ * `aria-expanded` Radix sets), and the panel + parts apply `.dropdown` / `.dropdown__head`
+ * / `.dropdown__sec` / `.dropdown__row` / `.dropdown__rule` — matching the
+ * `preview/app-chrome-traditional.html` oracle. Same "Radix for behavior, shipped classes
+ * for style" pattern as Select. No component CSS, no hex.
+ *
+ * The dropdown lift is the brand's no-shadow treatment: the shipped `.dropdown` is a
+ * heavier `1px solid var(--border-strong)` panel — there is NO `box-shadow` (FR4 / RB-8).
+ *
+ * Composition (matches the oracle):
+ *   <UserMenu>
+ *     <UserMenuTrigger><span className="wm"><span className="avatar">AK</span> Ashay</span></UserMenuTrigger>
+ *     <UserMenuContent>
+ *       <UserMenuHeader avatar={<span className="avatar avatar--lg">AK</span>} name="Ashay Kubal" email="ashay@…" />
+ *       <UserMenuGroup>
+ *         <UserMenuItem icon={<SettingsIcon />} onSelect={…}>Settings</UserMenuItem>
+ *         <UserMenuItem icon={<KeyIcon />} onSelect={…}>API key</UserMenuItem>
+ *       </UserMenuGroup>
+ *       <UserMenuSeparator />
+ *       <UserMenuGroup>
+ *         <UserMenuItem danger icon={<SignOutIcon />} onSelect={…}>Sign out</UserMenuItem>
+ *       </UserMenuGroup>
+ *     </UserMenuContent>
+ *   </UserMenu>
+ */
+/** Menu root — owns the open state. Thin alias of Radix `DropdownMenu.Root`. */
+declare const UserMenu: react.FC<DropdownMenu.DropdownMenuProps>;
+interface UserMenuTriggerProps extends ComponentPropsWithoutRef<typeof DropdownMenu.Trigger> {
+    /** Use a custom element as the trigger (no extra `.usermenu` wrapper DOM). */
+    asChild?: boolean;
+}
+/**
+ * The menu trigger. By default renders a `.usermenu` button hosting the avatar/name
+ * slot; pass `asChild` to make a custom element the trigger instead.
+ */
+declare const UserMenuTrigger: react.ForwardRefExoticComponent<UserMenuTriggerProps & react.RefAttributes<HTMLButtonElement>>;
+interface UserMenuContentProps extends ComponentPropsWithoutRef<typeof DropdownMenu.Content> {
+    /** Distance from the trigger, in px. Default `6`. */
+    sideOffset?: number;
+}
+/** The portalled `.dropdown` panel. Defaults to right-aligned under the trigger. */
+declare const UserMenuContent: react.ForwardRefExoticComponent<UserMenuContentProps & react.RefAttributes<HTMLDivElement>>;
+interface UserMenuHeaderProps {
+    /** Avatar node (e.g. `<span className="avatar avatar--lg">AK</span>`). */
+    avatar?: ReactNode;
+    /** Display name. */
+    name: ReactNode;
+    /** Secondary line, typically the email. */
+    email?: ReactNode;
+}
+/**
+ * Non-interactive identity header (`.dropdown__head`). Radix `Label` (skipped by nav).
+ * Render as a DIRECT child of `UserMenuContent` — NOT inside a `UserMenuGroup` — matching
+ * the oracle's `.dropdown__head` placement at the top of the `.dropdown` panel.
+ */
+declare function UserMenuHeader({ avatar, name, email }: UserMenuHeaderProps): react.JSX.Element;
+type UserMenuGroupProps = ComponentPropsWithoutRef<typeof DropdownMenu.Group>;
+/** A padded item group (`.dropdown__sec`). Wrap rows so they inset off the panel edge. */
+declare const UserMenuGroup: react.ForwardRefExoticComponent<Omit<DropdownMenu.DropdownMenuGroupProps & react.RefAttributes<HTMLDivElement>, "ref"> & react.RefAttributes<HTMLDivElement>>;
+interface UserMenuItemProps extends ComponentPropsWithoutRef<typeof DropdownMenu.Item> {
+    /** Tint the row as destructive (`.dropdown__row--danger`, e.g. Sign out). */
+    danger?: boolean;
+    /** Leading icon node (rendered before the label). */
+    icon?: ReactNode;
+}
+/** A menu row (`.dropdown__row`). Enter / click fire `onSelect`; Radix handles focus. */
+declare const UserMenuItem: react.ForwardRefExoticComponent<UserMenuItemProps & react.RefAttributes<HTMLDivElement>>;
+type UserMenuSeparatorProps = ComponentPropsWithoutRef<typeof DropdownMenu.Separator>;
+/** A hairline divider between groups (`.dropdown__rule`). */
+declare const UserMenuSeparator: react.ForwardRefExoticComponent<Omit<DropdownMenu.DropdownMenuSeparatorProps & react.RefAttributes<HTMLDivElement>, "ref"> & react.RefAttributes<HTMLDivElement>>;
+
+/**
+ * ThemeToggle — the single global light/dark switch.
+ *
+ * Painted with the shipped `@qball-inc/tokens` classes `.iconbtn` + `.theme-toggle`
+ * (matching the `preview/app-chrome-traditional.html` oracle). BOTH the sun and the
+ * moon are inline SVG icons wrapped in `.ic-sun` / `.ic-moon`; the shipped CSS swaps
+ * which one shows based on `html[data-theme]` (components.css:637-640) — so there is
+ * no icon library dependency and no React state needed for the icon swap.
+ *
+ * BINDING global-theme contract: a click flips `data-theme` on `document.documentElement`
+ * (`<html>`) — never a subtree element, a React context, or a CSS class. The `data-theme`
+ * attribute on `<html>` is the mechanism every preview card + the gallery use for theming
+ * (gallery.html:155). The current theme is read from the same attribute, defaulting to
+ * `"light"` when absent.
+ *
+ * Inline SVG only — no hardcoded color (the icons stroke with `currentColor`), no
+ * `box-shadow`. DESIGN_DENY (RB-8 layer (a)) clean.
+ */
+type Theme = "light" | "dark";
+interface ThemeToggleProps extends Omit<ComponentPropsWithoutRef<"button">, "onChange"> {
+    /** Fired with the new theme AFTER the toggle writes `data-theme` to `<html>`. */
+    onThemeChange?: (theme: Theme) => void;
+}
+declare const ThemeToggle: react.ForwardRefExoticComponent<ThemeToggleProps & react.RefAttributes<HTMLButtonElement>>;
+
+/**
+ * Scrim — the canonical library-wide scroll-lock primitive + dim backdrop.
+ *
+ * Painted with the shipped `.scrim` class (components.css:273-277): a full-viewport
+ * `position: fixed; inset: 0` layer dimmed with `var(--color-scrim)`. The shipped
+ * `.scrim` is DELIBERATELY flat — no `backdrop-filter` blur (the brand dims with a
+ * flat tone), so this is a pure className wrapper with no inline color and no shadow.
+ *
+ * Scrim OWNS scroll-lock: while `open` is true it sets `document.body` `overflow:hidden`,
+ * capturing the prior value, and restores that exact prior value when `open` becomes
+ * false OR when the component unmounts (no leaked lock).
+ *
+ * NOTE: Radix overlays (Modal/Dialog) keep their OWN robust scroll-lock
+ * (react-remove-scroll). This Scrim is the scroll-lock owner for NON-Radix / custom
+ * overlays; the Modal's overlay already shares this same `.scrim` class for the visual
+ * backdrop.
+ */
+interface ScrimProps extends ComponentPropsWithoutRef<"div"> {
+    /** When true, render the dim backdrop AND lock `document.body` scroll. */
+    open: boolean;
+}
+declare const Scrim: react.ForwardRefExoticComponent<ScrimProps & react.RefAttributes<HTMLDivElement>>;
+
+/** A discrete command surfaced in the dock's Search popover (and reused for Add suggestions). */
+interface CommandAction {
+    /** Stable identity. */
+    id: string;
+    /** Human label; the Search filter matches a case-insensitive substring of this. */
+    label: string;
+    /** Optional leading icon node. */
+    icon?: ReactNode;
+    /** Invoked when the row is chosen (click / Enter); the dock closes afterward. */
+    onSelect: () => void;
+}
+interface CommandDockProps extends Omit<ComponentPropsWithoutRef<"div">, "hidden"> {
+    /** The filterable command list shown in the Search popover. */
+    actions?: CommandAction[];
+    /** Search input placeholder. */
+    searchPlaceholder?: string;
+    /** Message shown in the Search popover when the filter matches nothing. */
+    noResultsLabel?: string;
+    /** Enable the AI composer. When `false` (default) the composer is disabled with a BYO-key message. */
+    aiEnabled?: boolean;
+    /** Called with the trimmed prompt when the AI composer is submitted; clears the input. */
+    onAiSubmit?: (prompt: string) => void;
+    /** AI composer placeholder. */
+    aiPlaceholder?: string;
+    /** BYO-key gate message shown when `aiEnabled` is false. */
+    aiDisabledLabel?: string;
+    /** Suggestions shown in the Add popover (filtered by the add input, case-insensitive). */
+    addSuggestions?: CommandAction[];
+    /** Add input placeholder. */
+    addPlaceholder?: string;
+    /** Notified as the user types in the Add input. */
+    onAddQueryChange?: (query: string) => void;
+    /** Self-manage hide-while-scrolling + 220ms idle spring-back (mirrors AppBar). */
+    hideOnScroll?: boolean;
+    /** Scroll source for `hideOnScroll`. Default `window`. */
+    scrollContainer?: HTMLElement | Window | null;
+    /** Manually apply the `.dock--hidden` hide transform. */
+    hidden?: boolean;
+}
+declare const CommandDock: react.ForwardRefExoticComponent<CommandDockProps & react.RefAttributes<HTMLDivElement>>;
+
+/**
+ * NotificationCenter — the app-bar bell dropdown, built on Radix `Popover`.
+ *
+ * The shipped `NotificationBell` is the Popover trigger; the panel paints the shipped
+ * `.dropdown` / `.notif` token classes (matching `preview/app-chrome-island.html`). ZERO token-CSS
+ * change. Radix supplies the behavior (portal to `<body>`, focus management, Escape/outside-click).
+ *
+ * Per-item visual treatment is SEMANTIC (owner sign-off, S84): each item's `kind`
+ * (`up` | `down` | `warn` | `info`) drives the shipped `.notif__mark--*` left mark — finance/status
+ * meaning, NOT a source-identity tag. Unread items are the sage-tinted `.notif__item--unread` row;
+ * clicking an unread row marks it read (`onMarkRead(id)`). The unread count is derived from `items`
+ * here (no shared store) and drives the bell's `.badge-count` badge — empty `items` → count 0 → no
+ * badge contract.
+ */
+/** Semantic meaning of a notification — drives the shipped `.notif__mark--*` left mark. */
+type NotificationKind = "up" | "down" | "warn" | "info";
+interface NotificationItemData {
+    /** Stable identity (passed to `onMarkRead`). */
+    id: string;
+    /** Semantic meaning → `.notif__mark--{kind}`. Omit for a neutral mark. */
+    kind?: NotificationKind;
+    /** Primary message (rich nodes allowed, e.g. a bold ticker + `.notif__num`). */
+    title: ReactNode;
+    /** Optional secondary detail, rendered after the title. */
+    body?: ReactNode;
+    /** Display timestamp (e.g. "2 min ago"). */
+    timestamp: ReactNode;
+    /** Read state. Unread renders the `.notif__item--unread` tint + the mark-read affordance. */
+    read: boolean;
+    /** Invoked with the item id when an unread row is marked read (click / Enter / Space). */
+    onMarkRead: (id: string) => void;
+}
+interface NotificationCenterProps {
+    /** The notifications to show. Unread count (drives the bell badge) is derived from this. */
+    items: NotificationItemData[];
+    /** Panel head title. Default "Notifications". */
+    title?: string;
+    /** When provided, a "Mark all read" head action renders and calls this. */
+    onMarkAllRead?: () => void;
+    /** "Mark all read" label. */
+    markAllLabel?: string;
+    /** Empty-state message when `items` is empty. Default "No notifications". */
+    emptyLabel?: string;
+    /** When provided, a footer "View all" link renders pointing here. */
+    viewAllHref?: string;
+    /** Footer link label. */
+    viewAllLabel?: string;
+    /** Bell trigger aria-label. Defaults to NotificationBell's "Notifications". */
+    bellLabel?: string;
+    /** Popover alignment relative to the bell. Default "end". */
+    align?: "start" | "center" | "end";
+    /** Popover distance from the bell, in px. Default 6. */
+    sideOffset?: number;
+}
+declare function NotificationCenter({ items, title, onMarkAllRead, markAllLabel, emptyLabel, viewAllHref, viewAllLabel, bellLabel, align, sideOffset, }: NotificationCenterProps): react.JSX.Element;
+
+/**
+ * Terminal — the Stocky AI conversation transcript, painted with the shipped
+ * `@qball-inc/tokens` `.term*` classes from the `preview/conversation-terminal.html`
+ * oracle. A scrollable, growable transcript of `you ›` / `stocky ›` turns with
+ * token-only styling (no component CSS, no hardcoded color, no box-shadow).
+ *
+ * Behaviour this surface owns: auto-scroll to the newest content on append, the
+ * blinking streaming cursor at the end of the in-progress assistant turn, a
+ * persistent (non-dismissible) AI disclaimer rendered via the shipped `Callout`
+ * (the DESIGNATED disclaimer host — owner decision S86, in place of the oracle's
+ * inline footer), and an error row that visually distinguishes a transient
+ * `Retrying…` frame (warning) from a fatal `Try again` frame (error).
+ *
+ * Streaming state comes from the `useStreaming` hook (`messages` / `streaming` /
+ * `error`), but `Terminal` is a pure display surface — it accepts that state as
+ * props. Grounding annotations (`[source]` / `[unverified]`) are OUT of scope:
+ * Grounding annotations are composed in afterward via `GroundingFlag`.
+ */
+/** Speaker for a transcript turn. */
+type TerminalRole = "user" | "assistant";
+/**
+ * A single streamed token. The streaming hook accumulates these into the
+ * in-progress assistant message; `Terminal` flattens them to display text.
+ */
+interface StreamToken {
+    /** The text fragment carried by this token. */
+    text: string;
+}
+/** One transcript turn. `content` is a plain string or an accumulating token list. */
+interface TerminalMessage {
+    /** Optional stable identity used as the React key; falls back to the index. */
+    id?: string | number;
+    role: TerminalRole;
+    content: string | StreamToken[];
+}
+/**
+ * A provider error surfaced into the transcript. Discriminated on `kind` so a
+ * retryable frame is never confused with a string sentinel
+ * (the `discriminated {kind}` pattern over a `string | "literal"` union).
+ */
+interface StreamError {
+    kind: "error";
+    /** Retryable → a transient `Retrying…` indicator; fatal → a `Try again` action. */
+    retryable: boolean;
+    message: string;
+}
+interface TerminalProps {
+    /** The transcript, oldest first. */
+    messages: TerminalMessage[];
+    /** While true, the last assistant turn shows the blinking streaming cursor. */
+    streaming?: boolean;
+    /** A provider error to surface as an error row (`null` / omitted = none). */
+    error?: StreamError | null;
+    /** Fired by the fatal-error row's `Try again` action. */
+    onRetry?: () => void;
+    /** Composer slot rendered in the terminal footer (e.g. a `<Composer/>`). */
+    composer?: ReactNode;
+    /** The persistent AI disclaimer. Defaults to the standard "not advice" notice. */
+    disclaimer?: ReactNode;
+    /** Header title (`.term__title`). Default `"stocky"`. */
+    title?: ReactNode;
+    /** Max height of the scrollable transcript body (a number is treated as px). */
+    maxHeight?: number | string;
+    /** className merged onto the `.term` root. */
+    className?: string;
+}
+declare function Terminal({ messages, streaming, error, onRetry, composer, disclaimer, title, maxHeight, className, }: TerminalProps): react.JSX.Element;
+
+/**
+ * Composer — the terminal's multiline input + inline send control, painted with
+ * the shipped `.term__composer` / `.term__prompt` / `.term__input` classes from
+ * the `preview/conversation-terminal.html` oracle. Standalone so it can sit in a
+ * `Terminal` footer (via the `composer` slot) or on its own.
+ *
+ * Send fires on Enter (without Shift) or a click of the inline `.iconbtn` send
+ * arrow; the textarea then clears and its auto-grown height resets. The BYO-key
+ * gate (`keyProvided={false}`) disables the input + send and shows an "Add your
+ * key" prompt — `onSend` is never invoked while gated. The Composer does NOT
+ * render the key-entry flow (that is `SecretInput`); it only reflects
+ * the `keyProvided` boolean and exposes the disabled visual state.
+ */
+interface ComposerProps {
+    /** Fired with the trimmed text on Enter (no Shift) or a send-click. */
+    onSend: (text: string) => void;
+    /** BYO-key gate. When `false`, the input + send are disabled and a prompt shows. Default `true`. */
+    keyProvided?: boolean;
+    /** Placeholder for the textarea. */
+    placeholder?: string;
+    /** The `.term__prompt` label. Default `"you ›"`. */
+    prompt?: ReactNode;
+    /** The gated-state prompt (must read as "add your key"). Default `"Add your key to start chatting."`. */
+    keyPrompt?: ReactNode;
+    /** Accessible label for the send button + the textarea. Defaults `"Send"` / `"Message"`. */
+    sendLabel?: string;
+    inputLabel?: string;
+    /** className merged onto the `.term__composer` root. */
+    className?: string;
+}
+declare function Composer({ onSend, keyProvided, placeholder, prompt, keyPrompt, sendLabel, inputLabel, className, }: ComposerProps): react.JSX.Element;
+
+/**
+ * Streaming — the SSE token-by-token consumption layer behind the `Terminal`.
+ *
+ * Three pieces:
+ *  - `parseStreamFrame` — a pure SSE-frame parser (`data:` / `event: error` /
+ *    `[DONE]`) → a discriminated {@link StreamEvent}. Provider error frames map
+ *    to `{ type: "error"; retryable; message }`, never a thrown exception.
+ *  - `streamFromResponse` — adapts a real `fetch` SSE `Response` body into an
+ *    `AsyncIterable<StreamEvent>` (wire framing on `\n\n`).
+ *  - `useStreaming` — the React hook: owns the transcript, appends each token to
+ *    the in-progress assistant turn (re-rendering per token), surfaces retryable
+ *    vs fatal errors, and clears the streaming flag on close (which removes the
+ *    Terminal's cursor).
+ *
+ * The error shape is discriminated on `kind` (`StreamError`) / `type`
+ * (`StreamEvent`) rather than a `string | "ERROR"` union, so a retryable frame
+ * can never be confused with a sentinel string.
+ */
+/** A parsed event from the SSE stream. */
+type StreamEvent = {
+    type: "token";
+    text: string;
+} | {
+    type: "error";
+    retryable: boolean;
+    message: string;
+} | {
+    type: "done";
+};
+/**
+ * Parse a single SSE frame (the text between `\n\n` separators) into a
+ * `StreamEvent`, or `null` if the frame carries no `data:` line. An
+ * `event: error` frame whose `data:` is a JSON `{ retryable, message }` becomes
+ * a discriminated error event; a `data: [DONE]` sentinel becomes a done event;
+ * anything else is a token whose text is the raw `data:` payload.
+ */
+declare function parseStreamFrame(frame: string): StreamEvent | null;
+/**
+ * Adapt a `fetch` SSE `Response` into an `AsyncIterable<StreamEvent>`. Reads the
+ * body reader, decodes incrementally, and splits on the `\n\n` SSE frame
+ * boundary, yielding one `StreamEvent` per non-empty frame.
+ */
+declare function streamFromResponse(response: Response): AsyncIterable<StreamEvent>;
+/** The state + actions returned by {@link useStreaming}. */
+interface UseStreamingResult {
+    /** The transcript, oldest first. */
+    messages: TerminalMessage[];
+    /** True while a stream is in flight (drives the Terminal cursor). */
+    streaming: boolean;
+    /** The current provider error, or `null`. Retryable → transient; fatal → terminal. */
+    error: StreamError | null;
+    /** Append a user turn (e.g. from the Composer's `onSend`). */
+    send: (text: string) => void;
+    /** Consume a parsed event stream, accumulating tokens into a fresh assistant turn. */
+    start: (events: AsyncIterable<StreamEvent>) => Promise<void>;
+    /** Clear the current error (e.g. before a retry). */
+    reset: () => void;
+}
+/**
+ * Token-by-token streaming state machine. One stream at a time: `start` opens a
+ * fresh assistant turn and accumulates tokens into it, re-rendering per token. A
+ * retryable error sets a transient indicator but keeps the stream open (the next
+ * token clears it); a fatal error terminates the stream and leaves the error for
+ * a `Try again` retry. The streaming flag always clears when the iterable ends.
+ */
+declare function useStreaming(initial?: TerminalMessage[]): UseStreamingResult;
+
+/**
+ * GroundingFlag — the inline `[source]` / `[unverified]` grounding annotation for
+ * AI answers, painted with the shipped `@qball-inc/tokens` grounding surface
+ * (`.ground-wave` wave-shimmer + the `.gtip*` explainer bubble) from the
+ * `preview/conversation-terminal.html` + `preview/briefing.html` oracles.
+ *
+ * **Standalone marker, NOT a value wrapper (oracle semantics).** The flag is the
+ * small shimmering `[source]`/`[unverified]` label itself; the flagged value
+ * (a price, a percent) lives in the surrounding prose — e.g. `NVDA leads [source]
+ * at +8.4%`. `children`, when supplied, OVERRIDES the label glyph; it is not a
+ * wrapped value.
+ *
+ * **Shimmer + reduced-motion are shipped CSS, not JS.** The wave-shimmer is the
+ * shipped `.ground-wave` + `.ground-wave--{source|unverified}` keyframe; a
+ * `@media (prefers-reduced-motion: reduce)` block in the same stylesheet swaps the
+ * animation for a static `var(--wave-base)` fill. The component applies BOTH
+ * classes (the modifier supplies `--wave-base`/`--wave-hi`); there is no
+ * `matchMedia` in here.
+ *
+ * **Portaled to `<body>` (BINDING, RB-5).** The explainer bubble composes
+ * `@radix-ui/react-tooltip` directly, so it portals to `<body>` and Radix's popper
+ * keeps it on-screen (collision-clamped) — the same portal-to-body guarantee as the
+ * sibling `Tooltip`. We do NOT reuse the shipped `TooltipContent` wrapper:
+ * it force-joins `.tip-pop` (the DARK inverted bubble), whereas grounding uses the
+ * deliberately LIGHT guardrail bubble. The position-agnostic `.gtip-pop` token class
+ * carries that light look minus the parent-anchored `.gtip` positioning (Radix owns
+ * placement); `.gtip__k`/`.gtip__src`/`.gtip--{cited,unverified}` descendants compose
+ * in unchanged.
+ *
+ * Self-contained: bundles its own `TooltipProvider`, so it drops into any tree
+ * (Terminal message content, a DigestCard narrated number) without app-root setup.
+ *
+ *   <p>NVDA leads <GroundingFlag variant="source" explainer="Live last-sale quote.">
+ *     <span className="gtip__src">Nasdaq · 3:42pm ET</span>
+ *   </GroundingFlag> at +8.4%.</p>
+ */
+type GroundingVariant = "source" | "unverified";
+interface GroundingFlagProps {
+    /** `'source'` renders the cited `[source]` flag; `'unverified'` renders `[unverified]`. */
+    variant: GroundingVariant;
+    /**
+     * The explainer body shown in the hover/focus bubble. Caller-supplied — this
+     * component owns the portal/clamp/shimmer, not the copy. A `.gtip__k` kicker
+     * (`Source` / `Unverified`) is rendered automatically above it.
+     */
+    explainer: ReactNode;
+    /** Optional override for the shimmer label glyph; defaults to `[source]` / `[unverified]`. */
+    children?: ReactNode;
+    /** Pin the explainer open (uncontrolled initial state) — useful for docs/specimens. */
+    defaultOpen?: boolean;
+}
+declare function GroundingFlag({ variant, explainer, children, defaultOpen }: GroundingFlagProps): react.JSX.Element;
+
+/**
+ * MarkdownRenderer — renders streamed assistant text (the Terminal's bot turns)
+ * as sanitized, token-styled markdown. Scoped to assistant prose; NOT
+ * a general-purpose HTML renderer (the element allowlist is the hard boundary).
+ *
+ * **Token styling is inherited, not declared (compose the shipped surface).** The
+ * renderer emits BARE semantic elements (`<h1>`-`<h4>`, `<p>`, `<blockquote>`,
+ * `<code>`, `<pre><code>`, `<a>`, `<em>`, `<strong>`, lists, `<hr>`). The shipped
+ * `@qball-inc/tokens` `colors_and_type.css` already styles every one of those bare
+ * elements token-backed (`h1,.h1` … `blockquote,.pullquote` … `pre,.codeblock` …
+ * `a,.link`), exactly as the `preview/code-block.html` + `preview/pull-quote.html`
+ * oracles do. So this component ships ZERO prose CSS, zero hardcoded hex, zero font
+ * strings — the styling rides the global stylesheet the consumer already imports.
+ * Anchors carry `.link` so the shared sage `:focus-visible` ring applies to prose
+ * links (the ring was extended to `.link:focus-visible` in this WP).
+ *
+ * **Safe-rendering strategy (BINDING, AC-3/AC-4).** No `dangerouslySetInnerHTML`,
+ * ever. Three layers, default-deny:
+ *  1. No `rehype-raw` + `skipHtml` → raw HTML in the source (`<script>`,
+ *     `<img onerror>`, `<iframe>`, `<style>`, `<svg onload>`) is never turned into
+ *     live DOM; it is stripped, not escaped-and-shown.
+ *  2. `allowedElements` (the {@link ALLOWED_ELEMENTS} allowlist) → only the scoped
+ *     prose set can render; anything else is dropped (`unwrapDisallowed` keeps the
+ *     inner text so content is never silently lost).
+ *  3. `urlTransform` → react-markdown's own hardened `defaultUrlTransform`, applied
+ *     at the prop AND re-applied defensively inside the anchor override. It tests the
+ *     ENTIRE pre-colon slice against a safe-scheme set, so only http/https/mailto/
+ *     irc/xmpp and scheme-less (relative/fragment/protocol-relative) URLs survive;
+ *     `javascript:`/`data:`/`vbscript:` — and control-char or zero-width-prefixed
+ *     scheme tricks a hand-rolled regex would miss — collapse to an empty href.
+ * The dual-assert XSS suite (AC-9) verifies each payload BOTH does not execute
+ * (`window.__xss` stays undefined) AND does not appear as a DOM element.
+ *
+ * **Streaming cursor is the shipped `.term__cursor` (compose, don't re-invent).**
+ * When `streaming`, a `.term__cursor` block is appended after the content — the
+ * same class the Terminal renders for an in-flight bot turn. Its blink keyframe and
+ * the `@media (prefers-reduced-motion: reduce) { animation: none }` static fallback
+ * (NFR5) are shipped CSS, so there is no `matchMedia` here and no new cursor rule.
+ * (When this renderer is later wired INTO the Terminal in place of its plain-text
+ * flatten, the Terminal's own cursor is de-duplicated against this one — a future
+ * WP; out of scope here.)
+ */
+/** The hard scope boundary: only these elements may render. Everything else drops. */
+declare const ALLOWED_ELEMENTS: readonly ["h1", "h2", "h3", "h4", "p", "code", "pre", "blockquote", "a", "em", "strong", "ol", "ul", "li", "hr"];
+interface MarkdownRendererProps {
+    /** The markdown source to render (a streamed assistant turn's accumulated text). */
+    content: string;
+    /** While true, append the shipped `.term__cursor` after the content. Default false. */
+    streaming?: boolean;
+    /** className merged onto the wrapper. */
+    className?: string;
+}
+declare function MarkdownRenderer({ content, streaming, className }: MarkdownRendererProps): react.JSX.Element;
+
+/**
+ * ToolUseIndicator — the compact, inline lifecycle chip for a skill / tool call
+ * inside the AI terminal transcript (the `Terminal`). It names the
+ * specific skill (`news-research`, `sec-filings-lookup`, …) and reports the state
+ * of its run, so a multi-second tool call never reads as a hang.
+ *
+ * Built to the **owner-signed-off** design spec
+ * (`docs/tool-use-indicator-design.md`) + `preview/tool-use-indicator.html`. It is a
+ * transient, status-bearing chip — it reports state, it is NOT a control.
+ *
+ * **All visuals come from the shipped `@qball-inc/tokens` `.tuf*` classes** (added in
+ * Built from the signed-off design — the Terminal/GroundingFlag token-CSS-port
+ * precedent). `data-state` drives the per-state color + tint; the color flows to the
+ * leading glyph + verb via `currentColor`. There is no component CSS and no hardcoded
+ * color (FR4 / DESIGN_DENY-clean — flat tonal tints, no elevation).
+ *
+ * **Glyph = the primary non-color cue (FR4).** Each state carries a distinct leading
+ * glyph — an inline SVG (Lucide geometry, stroke 1.5, 16px; matching the ThemeToggle /
+ * StateFig inline-SVG precedent, NOT a `lucide-react` import) — except `running`, which
+ * reuses the shipped `.spinner` (the one sanctioned loop) or, in `streaming` mode, the
+ * shipped `.term__cursor` blink. `partial` (caution gold) ALWAYS pairs its color with
+ * the glyph AND the literal verb word, so color never carries the meaning alone.
+ *
+ * **Reduced-motion is shipped CSS, not JS.** The `.spinner`, `.term__cursor`, and `.tuf`
+ * appear/cross-fade all stop under `@media (prefers-reduced-motion: reduce)` in the token
+ * stylesheet; the state stays fully legible from the static glyph + color + label. There
+ * is no `matchMedia` in here (the Skeleton / GroundingFlag contract).
+ *
+ * `idle` renders nothing — the chip is absent/collapsed (the approved "absent or
+ * collapsed" latitude); no looping idle animation.
+ *
+ *   <ToolUseIndicator state="running" skill="news-research" meta="3.1s" />
+ *   <ToolUseIndicator state="partial" skill="news-research" meta="rate-limited" />
+ *   <ToolUseIndicator state="running" streaming>analyzing filings</ToolUseIndicator>
+ */
+type ToolUseState = "idle" | "pending" | "running" | "success" | "error" | "partial";
+interface ToolUseIndicatorProps {
+    /** Lifecycle state. `idle` renders nothing (the chip is absent/collapsed). */
+    state: ToolUseState;
+    /** The skill / tool id, e.g. `"news-research"`. Rendered before the state verb. */
+    skill?: string;
+    /**
+     * Override the state verb (the default per state: queued / running / done /
+     * failed / partial). Ignored when `children` supplies a free-form label. For
+     * `state="partial"`, keep a caution word ("partial" / "rate-limited") so the
+     * FR4 non-color cue survives — the glyph is always present, but the word
+     * reinforces it; never suppress the text cue entirely.
+     */
+    verb?: string;
+    /** Optional trailing meta — elapsed time, result count, or `"rate-limited"`. */
+    meta?: ReactNode;
+    /**
+     * `running` only: render the streaming text-cursor (the shipped `.term__cursor`)
+     * after the label instead of the leading `.spinner` glyph — for the
+     * SSE-token-streaming variant.
+     */
+    streaming?: boolean;
+    /**
+     * Free-form label override (e.g. `"analyzing filings"`). When supplied, it
+     * replaces the constructed `{skill} · {verb}` label. `null`/`undefined` both
+     * fall through to the constructed label, so a conditional `children` never
+     * yields an empty chip.
+     */
+    children?: ReactNode;
+    /** Merged onto the `.tuf` root. */
+    className?: string;
+}
+declare function ToolUseIndicator({ state, skill, verb, meta, streaming, children, className, }: ToolUseIndicatorProps): react.JSX.Element | null;
+
+/**
+ * DigestCard — the LLM market-briefing / digest card, painted with the shipped
+ * `@qball-inc/tokens` `.digest` family from the `preview/briefing.html` oracle.
+ *
+ * A briefing is a self-contained `<article>` with an eyebrow period, a headline,
+ * a prose body, and a footer (timestamp + actions). Four states, controlled by
+ * `state`:
+ * - `unread` — `.digest--unread` (sage left-border) + a visible sage `.digest__dot`.
+ * - `read` — `.digest--read` (dimmed); NO dot.
+ * - `loading` — composes the shipped {@link Skeleton} placeholders in the digest layout.
+ * - `empty` — composes the shipped {@link EmptyStateFig} ("no briefings yet").
+ *
+ * **Pure className wrapper (S70 D-08).** Every visual comes from the shipped
+ * `.digest*` token CSS — there is no component CSS and no hardcoded color (FR4 /
+ * DESIGN_DENY-clean — flat tonal tints, no elevation). The sage accent (dot +
+ * border) is delivered by the `.digest__dot`
+ * / `.digest--unread` classes (which resolve `var(--color-signal)`, the sage
+ * token), so the component inlines no color of its own.
+ *
+ * **The sage dot is the non-color cue (FR4).** It is rendered ONLY in the `unread`
+ * state — its DOM presence/absence (not its color) signals unread vs read, so the
+ * status survives a monochrome rendering. (The oracle hides the read dot via CSS,
+ * but jsdom can't observe external CSS, so we render it conditionally instead.)
+ *
+ * **Grounding is composed by the caller, not owned here.** A narrated number in the
+ * body is annotated by dropping a {@link GroundingFlag} marker inline in `children`,
+ * NEXT TO the value (the oracle: `NVDA leads [source] at +8.4%`). DigestCard is the
+ * host; it does not wrap values itself.
+ *
+ *   <DigestCard state="unread" period="Morning briefing · 30 May"
+ *     title="Your watchlist is up 1.8% pre-open" time="Generated 7:02am ET">
+ *     <b>NVDA</b> leads{" "}
+ *     <GroundingFlag variant="source" explainer="Live last-sale quote.">
+ *       <span className="gtip__src">Nasdaq · 3:42pm ET</span>
+ *     </GroundingFlag>{" "}
+ *     at <b>+8.4%</b> on the week.
+ *   </DigestCard>
+ */
+type DigestState = "unread" | "read" | "loading" | "empty";
+interface DigestCardProps {
+    /** Display state. */
+    state: DigestState;
+    /** Eyebrow line, e.g. `"Morning briefing · 30 May"` (`.digest__period`). unread/read. */
+    period?: ReactNode;
+    /** Headline (`.digest__title`). unread/read. */
+    title?: ReactNode;
+    /** Body prose (`.digest__body`). Compose `<GroundingFlag>` markers inline. unread/read. */
+    children?: ReactNode;
+    /** Footer timestamp (`.digest__time`). unread/read. */
+    time?: ReactNode;
+    /** Footer actions slot (`.digest__actions`) — e.g. ghost icon buttons. unread/read. */
+    actions?: ReactNode;
+    /** `empty` state: icon node for the EmptyStateFig (e.g. an inline SVG). */
+    emptyIcon?: ReactNode;
+    /** `empty` state: headline. Default `"No briefings yet"`. */
+    emptyTitle?: ReactNode;
+    /** `empty` state: supporting line. */
+    emptyBody?: ReactNode;
+    /** `empty` state: optional CTA (e.g. a `<Button>`). */
+    emptyAction?: ReactNode;
+    /** Merged onto the `.digest` root. */
+    className?: string;
+}
+declare function DigestCard({ state, period, title, children, time, actions, emptyIcon, emptyTitle, emptyBody, emptyAction, className, }: DigestCardProps): react.JSX.Element;
+
+/**
+ * Props shared by the canvas background primitives. Standard `<canvas>` attributes
+ * (`className`, `style`, `id`, …) are spread onto the element so a consumer can
+ * size and position it (the backgrounds fill their parent via CSS). The `ref` is
+ * owned by the primitive (it drives the animation) and the canvas is always
+ * `aria-hidden` — these decorative surfaces carry no semantic content.
+ */
+type BackgroundProps = ComponentPropsWithoutRef<"canvas">;
+
+/**
+ * `GridBg` — a slowly pulsing dot matrix in the signal (sage) token color, faded
+ * toward the top-left so an overlaid headline stays readable. A decorative,
+ * `aria-hidden` `<canvas>` background.
+ *
+ * Token-driven (reads `--color-signal` at paint time; draws nothing if the token
+ * stylesheet is absent). Honors `prefers-reduced-motion` via {@link useCanvas2D} —
+ * one static frame, no animation loop. Brand rule: signal color only, very slow,
+ * no spring.
+ */
+declare function GridBg(props: BackgroundProps): react.JSX.Element;
+
+/**
+ * `AsciiBg` — slow falling streams of mono characters: bright amber (highlight) at
+ * each column head fading to sage (signal) down the tail. A decorative,
+ * `aria-hidden` `<canvas>` background.
+ *
+ * Token-driven (reads `--color-signal`, `--color-highlight`, and `--font-display`
+ * at paint time; draws nothing if the color tokens are absent). The glyph font is
+ * the design-system display font (`--font-display`), falling back to the public
+ * Fira Code default — never the private commercial display face. Honors
+ * `prefers-reduced-motion` via {@link useCanvas2D} (one static frame, no loop).
+ */
+declare function AsciiBg(props: BackgroundProps): react.JSX.Element;
+
+/**
+ * `GlyphsBg` — brand glyphs drifting slowly like a constellation, mostly in the
+ * signal (sage) token color with roughly one in six in amber (highlight), each
+ * breathing in opacity. A decorative, `aria-hidden` `<canvas>` background.
+ *
+ * Token-driven (reads `--color-signal`, `--color-highlight`, and `--font-display`
+ * at paint time; draws nothing if the color tokens are absent). The glyph font is
+ * the design-system display font (`--font-display`), falling back to the public
+ * Fira Code default — never the private commercial display face. Honors
+ * `prefers-reduced-motion` via {@link useCanvas2D} (one static frame, no loop).
+ */
+declare function GlyphsBg(props: BackgroundProps): react.JSX.Element;
+
+/**
+ * The per-frame context handed to a {@link CanvasDraw} callback. Sizes are in CSS
+ * pixels (the draw callback works in CSS-pixel space; the hook has already applied
+ * the device-pixel-ratio transform to the context).
+ */
+interface CanvasFrame {
+    /** Seconds elapsed since the animation started. */
+    t: number;
+    /** CSS-pixel width of the canvas (from `getBoundingClientRect`). */
+    w: number;
+    /** CSS-pixel height of the canvas. */
+    h: number;
+    /**
+     * `true` when the user prefers reduced motion. The hook draws a single static
+     * frame in that case (see the hook docs); a draw callback should additionally
+     * zero any time-derived motion so the one frame it paints is still.
+     */
+    reduceMotion: boolean;
+}
+/** A draw callback: paints one frame onto a 2D context. */
+type CanvasDraw = (ctx: CanvasRenderingContext2D, frame: CanvasFrame) => void;
+/**
+ * `useCanvas2D` — a DPR-aware (capped at 2×), `ResizeObserver`-refit driver for an
+ * animated `<canvas>`. Returns a ref to attach to a `<canvas>` element.
+ *
+ * **SSR/static-safe.** Every canvas / `window` / `ResizeObserver` access lives
+ * inside the effect, so the host component renders an inert `<canvas>` on the
+ * server and only begins drawing after hydration. If the 2D context is
+ * unavailable (server, jsdom without a canvas mock, or a browser without canvas),
+ * the hook no-ops — the `<canvas>` still renders, nothing throws.
+ *
+ * **Honors `prefers-reduced-motion` as a TRUE short-circuit.** When reduced motion
+ * is requested the hook paints exactly one static frame and starts **no** animation
+ * loop (`requestAnimationFrame` is never called). A later resize repaints that one
+ * frame so the canvas is never left blank. This differs from the original port,
+ * which kept the rAF loop spinning on a frozen frame.
+ *
+ * **No leaked work (RB-4).** The effect cleanup flips the running flag, cancels any
+ * pending frame, and disconnects the `ResizeObserver`, so no loop, frame, or
+ * observer survives an unmount or a dependency change.
+ *
+ * @param draw  Per-frame paint callback. Read theme/colors/state fresh inside it.
+ * @param deps  Dependencies that re-key the effect (default `[]`). The draw closure
+ *              reads its inputs fresh each frame, so most backgrounds pass none.
+ */
+declare function useCanvas2D(draw: CanvasDraw, deps?: DependencyList): react.RefObject<HTMLCanvasElement>;
+
+/**
+ * Shared prop surface for every icon in the system — the per-icon named exports
+ * (`<TrendingUp />`) and the dynamic registry (`<Icon name="trending-up" />`).
+ *
+ * Icons are **currentColor-only**: they never read a token. The placement wrapper
+ * owns color (e.g. `.iconbtn { color: var(--text-muted) }`), and a consumer
+ * recolors by setting `color` on any ancestor and resizes via `size`.
+ *
+ * `children` is omitted — an icon's geometry is baked at codegen time; it is not a
+ * slot. (The generated component supplies its paths to the shared `IconBase`.)
+ */
+interface IconProps extends Omit<SVGProps<SVGSVGElement>, "ref" | "children"> {
+    /** Render size in px → `width` and `height` on the fixed 24 viewBox. Default 24. */
+    size?: number;
+    /** Stroke width. Default 1.5 (the DS idiom; a few heavier marks use 1.6). */
+    strokeWidth?: number;
+    /** className merged after the base `ic` class. */
+    className?: string;
+    /**
+     * Accessible label. When present (or an `aria-label` is passed), the icon flips
+     * from decorative (`aria-hidden`) to `role="img"` + a linked `<title>`. Omit for
+     * decorative icons sitting next to text that already carries the meaning.
+     */
+    title?: string;
+}
+
+/** `chevron-up` — generated from lucide-react@1.17.0 (ISC). */
+declare function ChevronUp(props: IconProps): react.JSX.Element;
+
+/** `chevron-down` — generated from lucide-react@1.17.0 (ISC). */
+declare function ChevronDown(props: IconProps): react.JSX.Element;
+
+/** `chevron-left` — generated from lucide-react@1.17.0 (ISC). */
+declare function ChevronLeft(props: IconProps): react.JSX.Element;
+
+/** `chevron-right` — generated from lucide-react@1.17.0 (ISC). */
+declare function ChevronRight(props: IconProps): react.JSX.Element;
+
+/** `arrow-up` — generated from lucide-react@1.17.0 (ISC). */
+declare function ArrowUp(props: IconProps): react.JSX.Element;
+
+/** `arrow-down` — generated from lucide-react@1.17.0 (ISC). */
+declare function ArrowDown(props: IconProps): react.JSX.Element;
+
+/** `arrow-left` — generated from lucide-react@1.17.0 (ISC). */
+declare function ArrowLeft(props: IconProps): react.JSX.Element;
+
+/** `arrow-right` — generated from lucide-react@1.17.0 (ISC). */
+declare function ArrowRight(props: IconProps): react.JSX.Element;
+
+/** `arrow-up-right` — generated from lucide-react@1.17.0 (ISC). */
+declare function ArrowUpRight(props: IconProps): react.JSX.Element;
+
+/** `arrow-up-left` — generated from lucide-react@1.17.0 (ISC). */
+declare function ArrowUpLeft(props: IconProps): react.JSX.Element;
+
+/** `arrow-down-right` — generated from lucide-react@1.17.0 (ISC). */
+declare function ArrowDownRight(props: IconProps): react.JSX.Element;
+
+/** `arrow-down-left` — generated from lucide-react@1.17.0 (ISC). */
+declare function ArrowDownLeft(props: IconProps): react.JSX.Element;
+
+/** `external-link` — generated from lucide-react@1.17.0 (ISC). */
+declare function ExternalLink(props: IconProps): react.JSX.Element;
+
+/** `menu` — generated from lucide-react@1.17.0 (ISC). */
+declare function Menu(props: IconProps): react.JSX.Element;
+
+/** `x` — generated from lucide-react@1.17.0 (ISC). */
+declare function X(props: IconProps): react.JSX.Element;
+
+/** `search` — generated from lucide-react@1.17.0 (ISC). */
+declare function SearchIcon(props: IconProps): react.JSX.Element;
+
+/** `plus` — generated from lucide-react@1.17.0 (ISC). */
+declare function Plus(props: IconProps): react.JSX.Element;
+
+/** `minus` — generated from lucide-react@1.17.0 (ISC). */
+declare function Minus(props: IconProps): react.JSX.Element;
+
+/** `square-pen` — generated from lucide-react@1.17.0 (ISC). */
+declare function SquarePen(props: IconProps): react.JSX.Element;
+
+/** `trash-2` — generated from lucide-react@1.17.0 (ISC). */
+declare function Trash2(props: IconProps): react.JSX.Element;
+
+/** `download` — generated from lucide-react@1.17.0 (ISC). */
+declare function Download(props: IconProps): react.JSX.Element;
+
+/** `upload` — generated from lucide-react@1.17.0 (ISC). */
+declare function Upload(props: IconProps): react.JSX.Element;
+
+/** `copy` — generated from lucide-react@1.17.0 (ISC). */
+declare function Copy(props: IconProps): react.JSX.Element;
+
+/** `share-2` — generated from lucide-react@1.17.0 (ISC). */
+declare function Share2(props: IconProps): react.JSX.Element;
+
+/** `funnel` — generated from lucide-react@1.17.0 (ISC). */
+declare function Funnel(props: IconProps): react.JSX.Element;
+
+/** `arrow-up-down` — generated from lucide-react@1.17.0 (ISC). */
+declare function ArrowUpDown(props: IconProps): react.JSX.Element;
+
+/** `settings` — generated from lucide-react@1.17.0 (ISC). */
+declare function Settings(props: IconProps): react.JSX.Element;
+
+/** `refresh-cw` — generated from lucide-react@1.17.0 (ISC). */
+declare function RefreshCw(props: IconProps): react.JSX.Element;
+
+/** `check` — generated from lucide-react@1.17.0 (ISC). */
+declare function Check(props: IconProps): react.JSX.Element;
+
+/** `send` — generated from lucide-react@1.17.0 (ISC). */
+declare function Send(props: IconProps): react.JSX.Element;
+
+/** `eye` — generated from lucide-react@1.17.0 (ISC). */
+declare function Eye(props: IconProps): react.JSX.Element;
+
+/** `eye-off` — generated from lucide-react@1.17.0 (ISC). */
+declare function EyeOff(props: IconProps): react.JSX.Element;
+
+/** `bell` — generated from lucide-react@1.17.0 (ISC). */
+declare function Bell(props: IconProps): react.JSX.Element;
+
+/** `bell-off` — generated from lucide-react@1.17.0 (ISC). */
+declare function BellOff(props: IconProps): react.JSX.Element;
+
+/** `ellipsis` — generated from lucide-react@1.17.0 (ISC). */
+declare function Ellipsis(props: IconProps): react.JSX.Element;
+
+/** `ellipsis-vertical` — generated from lucide-react@1.17.0 (ISC). */
+declare function EllipsisVertical(props: IconProps): react.JSX.Element;
+
+/** `save` — generated from lucide-react@1.17.0 (ISC). */
+declare function Save(props: IconProps): react.JSX.Element;
+
+/** `info` — generated from lucide-react@1.17.0 (ISC). */
+declare function Info(props: IconProps): react.JSX.Element;
+
+/** `triangle-alert` — generated from lucide-react@1.17.0 (ISC). */
+declare function TriangleAlert(props: IconProps): react.JSX.Element;
+
+/** `circle-x` — generated from lucide-react@1.17.0 (ISC). */
+declare function CircleX(props: IconProps): react.JSX.Element;
+
+/** `circle-check` — generated from lucide-react@1.17.0 (ISC). */
+declare function CircleCheck(props: IconProps): react.JSX.Element;
+
+/** `circle-check-big` — generated from lucide-react@1.17.0 (ISC). */
+declare function CircleCheckBig(props: IconProps): react.JSX.Element;
+
+/** `clock` — generated from lucide-react@1.17.0 (ISC). */
+declare function Clock(props: IconProps): react.JSX.Element;
+
+/** `loader` — generated from lucide-react@1.17.0 (ISC). */
+declare function Loader(props: IconProps): react.JSX.Element;
+
+/** `sun` — generated from lucide-react@1.17.0 (ISC). */
+declare function Sun(props: IconProps): react.JSX.Element;
+
+/** `moon` — generated from lucide-react@1.17.0 (ISC). */
+declare function Moon(props: IconProps): react.JSX.Element;
+
+/** `lock` — generated from lucide-react@1.17.0 (ISC). */
+declare function Lock(props: IconProps): react.JSX.Element;
+
+/** `lock-open` — generated from lucide-react@1.17.0 (ISC). */
+declare function LockOpen(props: IconProps): react.JSX.Element;
+
+/** `circle-question-mark` — generated from lucide-react@1.17.0 (ISC). */
+declare function CircleQuestionMark(props: IconProps): react.JSX.Element;
+
+/** `ban` — generated from lucide-react@1.17.0 (ISC). */
+declare function Ban(props: IconProps): react.JSX.Element;
+
+/** `check-check` — generated from lucide-react@1.17.0 (ISC). */
+declare function CheckCheck(props: IconProps): react.JSX.Element;
+
+/** `octagon-alert` — generated from lucide-react@1.17.0 (ISC). */
+declare function OctagonAlert(props: IconProps): react.JSX.Element;
+
+/** `play` — generated from lucide-react@1.17.0 (ISC). */
+declare function Play(props: IconProps): react.JSX.Element;
+
+/** `pause` — generated from lucide-react@1.17.0 (ISC). */
+declare function Pause(props: IconProps): react.JSX.Element;
+
+/** `square` — generated from lucide-react@1.17.0 (ISC). */
+declare function Square(props: IconProps): react.JSX.Element;
+
+/** `globe` — generated from lucide-react@1.17.0 (ISC). */
+declare function Globe(props: IconProps): react.JSX.Element;
+
+/** `image` — generated from lucide-react@1.17.0 (ISC). */
+declare function Image(props: IconProps): react.JSX.Element;
+
+/** `file` — generated from lucide-react@1.17.0 (ISC). */
+declare function File(props: IconProps): react.JSX.Element;
+
+/** `link` — generated from lucide-react@1.17.0 (ISC). */
+declare function Link(props: IconProps): react.JSX.Element;
+
+/** `package` — generated from lucide-react@1.17.0 (ISC). */
+declare function Package(props: IconProps): react.JSX.Element;
+
+/** `rocket` — generated from lucide-react@1.17.0 (ISC). */
+declare function Rocket(props: IconProps): react.JSX.Element;
+
+/** `grid-3x3` — generated from lucide-react@1.17.0 (ISC). */
+declare function Grid3x3(props: IconProps): react.JSX.Element;
+
+/** `notebook-pen` — generated from lucide-react@1.17.0 (ISC). */
+declare function NotebookPen(props: IconProps): react.JSX.Element;
+
+/** `code-xml` — generated from lucide-react@1.17.0 (ISC). */
+declare function CodeXml(props: IconProps): react.JSX.Element;
+
+/** `trending-up` — generated from lucide-react@1.17.0 (ISC). */
+declare function TrendingUp(props: IconProps): react.JSX.Element;
+
+/** `trending-down` — generated from lucide-react@1.17.0 (ISC). */
+declare function TrendingDown(props: IconProps): react.JSX.Element;
+
+/** `chart-line` — generated from lucide-react@1.17.0 (ISC). */
+declare function ChartLine(props: IconProps): react.JSX.Element;
+
+/** `chart-column` — generated from lucide-react@1.17.0 (ISC). */
+declare function ChartColumn(props: IconProps): react.JSX.Element;
+
+/** `chart-candlestick` — generated from lucide-react@1.17.0 (ISC). */
+declare function ChartCandlestick(props: IconProps): react.JSX.Element;
+
+/** `chart-pie` — generated from lucide-react@1.17.0 (ISC). */
+declare function ChartPie(props: IconProps): react.JSX.Element;
+
+/** `wallet` — generated from lucide-react@1.17.0 (ISC). */
+declare function Wallet(props: IconProps): react.JSX.Element;
+
+/** `briefcase` — generated from lucide-react@1.17.0 (ISC). */
+declare function Briefcase(props: IconProps): react.JSX.Element;
+
+/** `calendar` — generated from lucide-react@1.17.0 (ISC). */
+declare function Calendar(props: IconProps): react.JSX.Element;
+
+/** `bookmark` — generated from lucide-react@1.17.0 (ISC). */
+declare function Bookmark(props: IconProps): react.JSX.Element;
+
+/** `percent` — generated from lucide-react@1.17.0 (ISC). */
+declare function Percent(props: IconProps): react.JSX.Element;
+
+/** `dollar-sign` — generated from lucide-react@1.17.0 (ISC). */
+declare function DollarSign(props: IconProps): react.JSX.Element;
+
+/** `activity` — generated from lucide-react@1.17.0 (ISC). */
+declare function Activity(props: IconProps): react.JSX.Element;
+
+/** `target` — generated from lucide-react@1.17.0 (ISC). */
+declare function Target(props: IconProps): react.JSX.Element;
+
+/** `scale` — generated from lucide-react@1.17.0 (ISC). */
+declare function Scale(props: IconProps): react.JSX.Element;
+
+/** `banknote` — generated from lucide-react@1.17.0 (ISC). */
+declare function Banknote(props: IconProps): react.JSX.Element;
+
+/** `ai-sparkle` — generated from lucide-react@1.17.0 (ISC). */
+declare function AiSparkle(props: IconProps): react.JSX.Element;
+
+/** `bot` — generated from lucide-react@1.17.0 (ISC). */
+declare function Bot(props: IconProps): react.JSX.Element;
+
+/** `bot-message-square` — generated from lucide-react@1.17.0 (ISC). */
+declare function BotMessageSquare(props: IconProps): react.JSX.Element;
+
+/** `cpu` — generated from lucide-react@1.17.0 (ISC). */
+declare function Cpu(props: IconProps): react.JSX.Element;
+
+/**
+ * `agent-stocky` — original DS art: the Stocky CRT-bot mascot rendered STATIC. A
+ * faithful 0.75-scale of the signed-off preview design (the preview drew it at the
+ * mascot's native 32-viewBox; the icon system is a fixed 24-viewBox), in the stroke
+ * idiom (antenna + screen + eyes + legs, no animation). A distinct, tree-shakeable
+ * icon; the animated `StockyIcon` in `CommandDock` stays unmigrated (§10).
+ * currentColor-only.
+ */
+declare function AgentStocky(props: IconProps): react.JSX.Element;
+
+/**
+ * `agent-orb` — original DS art (signed-off preview design): a core node radiating
+ * concentric signal arcs, in the 24-viewBox stroke idiom. No third-party source / IP.
+ * currentColor-only.
+ */
+declare function AgentOrb(props: IconProps): react.JSX.Element;
+
+/**
+ * `agent-droid` — original DS art (signed-off preview design): a domed droid head
+ * with a single antenna and a visor band, in the 24-viewBox stroke idiom. No
+ * third-party source / IP. currentColor-only.
+ */
+declare function AgentDroid(props: IconProps): react.JSX.Element;
+
+/**
+ * `agent-hex` — original DS art (signed-off preview design): a hexagonal agent badge
+ * with a two-eye face, in the 24-viewBox stroke idiom. No third-party source / IP.
+ * currentColor-only.
+ */
+declare function AgentHex(props: IconProps): react.JSX.Element;
+
+/** `github` — the GitHub mark, generated from simple-icons@16.24.0 (CC0-1.0). Nominative use only (§12, MARKS.md). */
+declare function GitHub(props: IconProps): react.JSX.Element;
+
+/** `npm` — the npm mark, generated from simple-icons@16.24.0 (CC0-1.0). Nominative use only (§12, MARKS.md). */
+declare function NPM(props: IconProps): react.JSX.Element;
+
+/** `figma` — the Figma mark, generated from simple-icons@16.24.0 (CC0-1.0). Nominative use only (§12, MARKS.md). */
+declare function Figma(props: IconProps): react.JSX.Element;
+
+/** `notion` — the Notion mark, generated from simple-icons@16.24.0 (CC0-1.0). Nominative use only (§12, MARKS.md). */
+declare function Notion(props: IconProps): react.JSX.Element;
+
+/** `vercel` — the Vercel mark, generated from simple-icons@16.24.0 (CC0-1.0). Nominative use only (§12, MARKS.md). */
+declare function Vercel(props: IconProps): react.JSX.Element;
+
+/** `chromestore` — the Chrome Web Store mark, generated from simple-icons@16.24.0 (CC0-1.0). Nominative use only (§12, MARKS.md). */
+declare function ChromeWebStore(props: IconProps): react.JSX.Element;
+
+/**
+ * `vscode` — a VSCodium stand-in (the real VS Code mark is trademark-withheld from
+ * CC0 sets, §12); swap in an official asset if one is provided. Nominative use only
+ * — VS Code / VSCodium are trademarks of their owners (see MARKS.md).
+ */
+declare function VSCode(props: IconProps): react.JSX.Element;
+
+/** `linear` — the Linear mark, generated from simple-icons@16.24.0 (CC0-1.0). Nominative use only (§12, MARKS.md). */
+declare function Linear(props: IconProps): react.JSX.Element;
+
+/**
+ * `linkedin` — the LinkedIn mark (in-repo stroke glyph carried from the consumer;
+ * Lucide removed brand icons, so it is NOT in lucide@1.17.0, §12). Stroke idiom —
+ * a minor, owner-accepted inconsistency vs the filled brand marks. Nominative use
+ * only — a trademark of its owner (see MARKS.md).
+ */
+declare function LinkedIn(props: IconProps): react.JSX.Element;
+
+/** `x-twitter` — the X mark, generated from simple-icons@16.24.0 (CC0-1.0). Nominative use only (§12, MARKS.md). */
+declare function XTwitter(props: IconProps): react.JSX.Element;
+
+/** `youtube` — the YouTube mark, generated from simple-icons@16.24.0 (CC0-1.0). Nominative use only (§12, MARKS.md). */
+declare function YouTube(props: IconProps): react.JSX.Element;
+
+/** `google` — the Google mark, generated from simple-icons@16.24.0 (CC0-1.0). Nominative use only (§12, MARKS.md). */
+declare function Google(props: IconProps): react.JSX.Element;
+
+/** `reddit` — the Reddit mark, generated from simple-icons@16.24.0 (CC0-1.0). Nominative use only (§12, MARKS.md). */
+declare function Reddit(props: IconProps): react.JSX.Element;
+
+/**
+ * `openai` — the OpenAI mark (owner-supplied asset; not in CC0 sets, §12). The
+ * source `#000000` fill is normalized to `currentColor` via the filled IconBase.
+ * Nominative use only — a trademark of its owner (see MARKS.md).
+ */
+declare function OpenAI(props: IconProps): react.JSX.Element;
+
+/** `anthropic` — the Anthropic mark, generated from simple-icons@16.24.0 (CC0-1.0). Nominative use only (§12, MARKS.md). */
+declare function Anthropic(props: IconProps): react.JSX.Element;
+
+/** `claude` — the Claude mark, generated from simple-icons@16.24.0 (CC0-1.0). Nominative use only (§12, MARKS.md). */
+declare function Claude(props: IconProps): react.JSX.Element;
+
+/** `gemini` — the Google Gemini mark, generated from simple-icons@16.24.0 (CC0-1.0). Nominative use only (§12, MARKS.md). */
+declare function Gemini(props: IconProps): react.JSX.Element;
+
+/** `deepseek` — the DeepSeek mark, generated from simple-icons@16.24.0 (CC0-1.0). Nominative use only (§12, MARKS.md). */
+declare function DeepSeek(props: IconProps): react.JSX.Element;
+
+/** `moonshot` — the Moonshot AI mark, generated from simple-icons@16.24.0 (CC0-1.0). Nominative use only (§12, MARKS.md). */
+declare function Moonshot(props: IconProps): react.JSX.Element;
+
+/**
+ * `glm` — the GLM / Zhipu mark (owner-supplied asset; not in CC0 sets, §12). Already
+ * `currentColor`; the multi-path mark uses an even-odd fill rule. Nominative use only
+ * — a trademark of its owner (see MARKS.md).
+ */
+declare function GLM(props: IconProps): react.JSX.Element;
+
+/** `mistral` — the Mistral AI mark, generated from simple-icons@16.24.0 (CC0-1.0). Nominative use only (§12, MARKS.md). */
+declare function Mistral(props: IconProps): react.JSX.Element;
+
+/** `perplexity` — the Perplexity mark, generated from simple-icons@16.24.0 (CC0-1.0). Nominative use only (§12, MARKS.md). */
+declare function Perplexity(props: IconProps): react.JSX.Element;
+
+/** `huggingface` — the Hugging Face mark, generated from simple-icons@16.24.0 (CC0-1.0). Nominative use only (§12, MARKS.md). */
+declare function HuggingFace(props: IconProps): react.JSX.Element;
+
+/** `ollama` — the Ollama mark, generated from simple-icons@16.24.0 (CC0-1.0). Nominative use only (§12, MARKS.md). */
+declare function Ollama(props: IconProps): react.JSX.Element;
+
+/** `qwen` — the QWen mark, generated from simple-icons@16.24.0 (CC0-1.0). Nominative use only (§12, MARKS.md). */
+declare function Qwen(props: IconProps): react.JSX.Element;
+
+/** `meta` — the Meta mark, generated from simple-icons@16.24.0 (CC0-1.0). Nominative use only (§12, MARKS.md). */
+declare function Meta(props: IconProps): react.JSX.Element;
+
+/** Every shipped icon name (canonical + aliases). A 1.0 stability contract. */
+type IconName = "chevron-up" | "chevron-down" | "chevron-left" | "chevron-right" | "arrow-up" | "arrow-down" | "arrow-left" | "arrow-right" | "arrow-up-right" | "arrow-up-left" | "arrow-down-right" | "arrow-down-left" | "external-link" | "menu" | "x" | "search" | "plus" | "minus" | "square-pen" | "trash-2" | "download" | "upload" | "copy" | "share-2" | "funnel" | "filter" | "arrow-up-down" | "settings" | "refresh-cw" | "check" | "send" | "eye" | "eye-off" | "bell" | "bell-off" | "ellipsis" | "ellipsis-vertical" | "save" | "info" | "triangle-alert" | "circle-x" | "circle-check" | "circle-check-big" | "clock" | "loader" | "sun" | "moon" | "lock" | "lock-open" | "circle-question-mark" | "circle-help" | "ban" | "check-check" | "octagon-alert" | "play" | "pause" | "square" | "globe" | "image" | "file" | "link" | "package" | "rocket" | "grid-3x3" | "notebook-pen" | "code-xml" | "trending-up" | "trending-down" | "chart-line" | "chart-column" | "chart-candlestick" | "chart-pie" | "wallet" | "briefcase" | "calendar" | "bookmark" | "percent" | "dollar-sign" | "activity" | "target" | "scale" | "banknote" | "ai-sparkle" | "bot" | "bot-message-square" | "cpu" | "agent-stocky" | "agent-orb" | "agent-droid" | "agent-hex";
+/** Runtime list of every IconName — the contract surface for dynamic name use. */
+declare const ICON_NAMES: readonly ["chevron-up", "chevron-down", "chevron-left", "chevron-right", "arrow-up", "arrow-down", "arrow-left", "arrow-right", "arrow-up-right", "arrow-up-left", "arrow-down-right", "arrow-down-left", "external-link", "menu", "x", "search", "plus", "minus", "square-pen", "trash-2", "download", "upload", "copy", "share-2", "funnel", "filter", "arrow-up-down", "settings", "refresh-cw", "check", "send", "eye", "eye-off", "bell", "bell-off", "ellipsis", "ellipsis-vertical", "save", "info", "triangle-alert", "circle-x", "circle-check", "circle-check-big", "clock", "loader", "sun", "moon", "lock", "lock-open", "circle-question-mark", "circle-help", "ban", "check-check", "octagon-alert", "play", "pause", "square", "globe", "image", "file", "link", "package", "rocket", "grid-3x3", "notebook-pen", "code-xml", "trending-up", "trending-down", "chart-line", "chart-column", "chart-candlestick", "chart-pie", "wallet", "briefcase", "calendar", "bookmark", "percent", "dollar-sign", "activity", "target", "scale", "banknote", "ai-sparkle", "bot", "bot-message-square", "cpu", "agent-stocky", "agent-orb", "agent-droid", "agent-hex"];
+/** Every shipped brand-mark name. Distinct from IconName (logos are not icons, AC-4). */
+type BrandIconName = "github" | "npm" | "figma" | "notion" | "vercel" | "chromestore" | "vscode" | "linear" | "linkedin" | "x-twitter" | "youtube" | "google" | "reddit" | "openai" | "anthropic" | "claude" | "gemini" | "deepseek" | "moonshot" | "glm" | "mistral" | "perplexity" | "huggingface" | "ollama" | "qwen" | "meta";
+/** Runtime list of every BrandIconName. */
+declare const BRAND_ICON_NAMES: readonly ["github", "npm", "figma", "notion", "vercel", "chromestore", "vscode", "linear", "linkedin", "x-twitter", "youtube", "google", "reddit", "openai", "anthropic", "claude", "gemini", "deepseek", "moonshot", "glm", "mistral", "perplexity", "huggingface", "ollama", "qwen", "meta"];
+
+interface IconComponentProps extends IconProps {
+    /** Icon name from the generated set — a canonical id or a recorded alias. */
+    name: IconName;
+}
+/**
+ * Dynamic, data-driven icon: `<Icon name="trending-up" />`. Use this when the icon
+ * is chosen at runtime. For static use, prefer the per-icon named export
+ * (`<TrendingUp />`) — it tree-shakes, whereas this registry intentionally retains
+ * the whole set (importing `Icon` pulls every icon).
+ */
+declare function Icon({ name, ...props }: IconComponentProps): react.JSX.Element | null;
+
+/**
+ * MediaSlot — an art-directed, sized, shaped container that displays
+ * heterogeneous media (static image / animated GIF / self-hosted video / an
+ * embedded remote video) with one unifying contract: shape mask, object-fit,
+ * object-position, aspect-ratio (CLS reserve), lazy-load, poster, placeholder,
+ * and a11y. Painted with the shipped `@qball-inc/tokens` `.media-slot` family
+ * from the `preview/media-slot.html` oracle — every visual comes from the token
+ * CSS / token-valued custom properties (no hardcoded hex, no `box-shadow`).
+ *
+ * **Pure React, SSR/static-safe by construction** (research Option A):
+ * renders native `<img>`/`<video>`/`<iframe>`; NO `window`/`document`/
+ * `customElements` access at module-eval OR render. The only client-side work —
+ * the embed facade's click→swap and the reduced-motion probe — lives in an event
+ * handler / effect, so it never runs during SSR.
+ *
+ * **Discriminated `type` → 4 render paths:**
+ * - `image`/`gif` → `<img>` (gif animates natively in the UA).
+ * - `video` → `<video poster preload="none">`, **default muted, NO autoplay**,
+ *   native `controls`. gif-as-video = `autoPlay loop muted` (adds `playsInline`;
+ *   autoplay is suppressed under `prefers-reduced-motion`).
+ * - `embed` → a **facade**: the provider's real thumbnail + a real `<button>` play
+ *   overlay on the shipped dark `--color-scrim`; the real `<iframe>` is swapped in
+ *   only on click — **no network until click** (consumer owns CSP/consent). The
+ *   facade resets when `src`/`provider` changes, so a reused instance never
+ *   auto-loads a new embed.
+ *
+ * The DISPLAY primitive only. Upload / drag-drop / reframe-crop / persistence /
+ * oEmbed resolution are the deferred authoring layer; `adapter` is a
+ * reserved, no-op seam that declares that future API for forward-compatibility.
+ */
+type MediaSlotType = "image" | "gif" | "video" | "embed";
+type MediaSlotShape = "rect" | "rounded" | "circle" | "pill";
+type MediaSlotFit = "cover" | "contain" | "fill";
+/**
+ * RESERVED no-op seam for the authoring layer (read/persist adapters).
+ * Declared in 1.0 so 1.1 can ship the authoring behavior backward-compatibly;
+ * MediaSlot ignores it entirely at 1.0 (zero persistence behavior).
+ */
+interface MediaSlotAdapter {
+    read?: (...args: never[]) => unknown;
+    write?: (...args: never[]) => unknown;
+}
+interface MediaSlotProps {
+    /** Image/GIF/video URL, or an embed URL. Absent ⇒ the empty-state placeholder. */
+    src?: string;
+    /** Discriminated render path. */
+    type: MediaSlotType;
+    /** Frame shape. Default `rounded`. Ignored when `mask` is set. */
+    shape?: MediaSlotShape;
+    /** Corner radius (px) for `shape="rounded"`. Defaults to the `--radius-md` token. */
+    radius?: number;
+    /** A CSS `clip-path` that overrides `shape`. */
+    mask?: string;
+    /** `object-fit` of the inner media. Default `cover`. */
+    fit?: MediaSlotFit;
+    /** `object-position` of the inner media. Default `50% 50%`. */
+    position?: string;
+    /** CSS `aspect-ratio` (e.g. `"16 / 9"`). Reserves the box → no CLS. Circle defaults to `1 / 1`. */
+    aspectRatio?: string;
+    /** `loading="lazy"` on `<img>` / `preload="none"` on `<video>`. Default `true`. */
+    lazy?: boolean;
+    /** `<video>` poster frame (`type="video"`). */
+    poster?: string;
+    /** Empty-state UI when `src` is absent. Defaults to a token-styled glyph placeholder. */
+    placeholder?: ReactNode;
+    /** Native `controls`. Default `true` (auto-`false` for a gif-as-video loop). */
+    controls?: boolean;
+    /** Autoplay. Default `false`. Suppressed under `prefers-reduced-motion`. */
+    autoPlay?: boolean;
+    /** Muted. Default `true`. */
+    muted?: boolean;
+    /** Loop. Default `false`. `autoPlay + loop + muted` = gif-as-video. */
+    loop?: boolean;
+    /** Provider override/fallback when URL inference can't determine it. Recognized
+     *  values: `"youtube"`, `"vimeo"`; any other value treats `src` as the embed URL. */
+    provider?: string;
+    /** Explicit facade thumbnail when the provider has no derivable thumb URL (e.g. Vimeo). */
+    thumbnail?: string;
+    /** Required for informative media; `alt=""` (the default) marks it decorative. */
+    alt?: string;
+    /** Optional in-frame type chip (e.g. "gif"). Rendered only when provided. */
+    badge?: ReactNode;
+    /** Merged onto the `.media-slot` root. The consumer owns WIDTH/layout here. */
+    className?: string;
+    /** RESERVED no-op in 1.0 (authoring seam). */
+    adapter?: MediaSlotAdapter;
+}
+declare function MediaSlot({ src, type, shape, radius, mask, fit, position, aspectRatio, lazy, poster, placeholder, controls, autoPlay, muted, loop, provider, thumbnail, alt, badge, className, }: MediaSlotProps): react.JSX.Element;
+
+export { ALLOWED_ELEMENTS, Activity, AgentDroid, AgentHex, AgentOrb, AgentStocky, AiSparkle, AlertModal, type AlertModalProps, Anthropic, AppBar, type AppBarProps, ArrowDown, ArrowDownLeft, ArrowDownRight, ArrowLeft, ArrowRight, ArrowUp, ArrowUpDown, ArrowUpLeft, ArrowUpRight, AsciiBg, Avatar, AvatarGroup, type AvatarGroupProps, type AvatarProps, type AvatarSize, type AvatarStatus, BRAND_ICON_NAMES, type BackgroundProps, Badge, type BadgeProps, type BadgeVariant, Ban, Banknote, Bell, BellOff, Bookmark, Bot, BotMessageSquare, type BrandIconName, Briefcase, Button, type ButtonProps, type ButtonVariant, Calendar, Callout, type CalloutProps, type CalloutVariant, Candlestick, type CandlestickDatum, type CandlestickProps, type CandlestickRange, type CanvasDraw, type CanvasFrame, Card, type CardProps, ChartCandlestick, ChartColumn, ChartLine, ChartPie, Check, CheckCheck, ChevronDown, ChevronLeft, ChevronRight, ChevronUp, ChromeWebStore, CircleCheck, CircleCheckBig, CircleQuestionMark as CircleHelp, CircleQuestionMark, CircleX, Claude, Clock, CodeXml, type CommandAction, CommandDock, type CommandDockProps, Composer, type ComposerProps, Copy, Cpu, DataTable, type DataTableColumnMeta, type DataTableProps, DeepSeek, DigestCard, type DigestCardProps, type DigestState, Divider, type DividerProps, DollarSign, Download, Ellipsis, EllipsisVertical, EmptyStateFig, type EmptyStateFigProps, ErrorStateFig, type ErrorStateFigProps, ExternalLink, Eye, EyeOff, Field, type FieldProps, Figma, File, Funnel as Filter, Funnel, GLM, Gemini, GitHub, Globe, GlyphsBg, Google, Grid3x3, GridBg, GroundingFlag, type GroundingFlagProps, type GroundingVariant, HuggingFace, ICON_NAMES, Icon, type IconName, type IconProps, Image, Info, Input, type InputProps, Linear, Link, LinkedIn, Loader, Lock, LockOpen, MarkdownRenderer, type MarkdownRendererProps, MediaSlot, type MediaSlotAdapter, type MediaSlotFit, type MediaSlotProps, type MediaSlotShape, type MediaSlotType, Menu, Meta, Meter, type MeterProps, type MeterVariant, Minus, Mistral, Modal, ModalClose, ModalContent, type ModalContentProps, ModalDescription, ModalTitle, ModalTrigger, Moon, Moonshot, NPM, NotebookPen, NotificationBell, type NotificationBellProps, NotificationCenter, type NotificationCenterProps, type NotificationItemData, type NotificationKind, Notion, OctagonAlert, Ollama, OpenAI, Package, Pause, Percent, Perplexity, Play, Plus, Qwen, Reddit, RefreshCw, Rocket, Save, Scale, Scrim, type ScrimProps, Search, SearchIcon, type SearchItem, type SearchProps, SecretInput, type SecretInputProps, Segmented, SegmentedItem, type SegmentedItemProps, type SegmentedProps, Select, SelectItem, type SelectItemProps, type SelectProps, Send, Settings, Share2, Skeleton, type SkeletonProps, type SkeletonShape, Sparkline, type SparklineDirection, type SparklineProps, Spinner, type SpinnerProps, type SpinnerSize, Square, SquarePen, Stat, type StatDirection, type StatProps, type StreamError, type StreamEvent, type StreamToken, Sun, Surface, type SurfaceProps, Switch, type SwitchProps, Tabs, TabsContent, type TabsContentProps, TabsList, type TabsListProps, type TabsProps, TabsTrigger, type TabsTriggerProps, Target, Terminal, type TerminalMessage, type TerminalProps, type TerminalRole, type Theme, ThemeToggle, type ThemeToggleProps, type ToastOptions, Toaster, ToolUseIndicator, type ToolUseIndicatorProps, type ToolUseState, Tooltip, TooltipContent, type TooltipContentProps, TooltipProvider, TooltipTrigger, Trash2, TrendingDown, TrendingUp, TriangleAlert, Upload, type UseStreamingResult, UserMenu, UserMenuContent, type UserMenuContentProps, UserMenuGroup, type UserMenuGroupProps, UserMenuHeader, type UserMenuHeaderProps, UserMenuItem, type UserMenuItemProps, UserMenuSeparator, type UserMenuSeparatorProps, UserMenuTrigger, type UserMenuTriggerProps, VSCode, Vercel, Wallet, X, XTwitter, YouTube, parseStreamFrame, streamFromResponse, toast, useCanvas2D, useStreaming };