@cascivo/react 1.0.0 → 1.2.0

package/dist/index.d.ts

@@ -368,6 +368,45 @@ declare function Separator({
   className,
   ...props
 }: SeparatorProps): import("react").JSX.Element;
+type LogoVariant = 'mark' | 'mark-accent' | 'horizontal' | 'stacked' | 'nav';
+interface LogoProps extends HTMLAttributes<HTMLSpanElement> {
+  /**
+   * The logo renders the mark and, in a lockup, the wordmark — there is no slot for
+   * anything else. `never` rather than `Omit<>` because omitting a key off
+   * `HTMLAttributes` loses the `style` widening that the signals JSX augmentation
+   * applies in an adopter's project, and the spread below then fails to compile there.
+   */
+  children?: never;
+  /**
+   * `mark` and `mark-accent` render the square alone; `horizontal`, `stacked` and `nav`
+   * add the wordmark. `nav` is the only lockup permitted below 24px.
+   *
+   * @defaultValue `mark`
+   * @see the component manifest
+   */
+  variant?: LogoVariant;
+  /**
+   * Mark height in px. Clamped to a 16px floor — below that the notch closes optically.
+   *
+   * @defaultValue `18` for `nav`, `32` otherwise
+   * @see the component manifest
+   */
+  size?: number;
+}
+/**
+ * The cascivo logo: the mark on its own, or one of the three sanctioned lockups.
+ *
+ * Renders inline SVG rather than an `<img>` on purpose — `currentColor` and
+ * `--cascivo-color-accent` only resolve when the SVG is part of the document, which is
+ * what lets the logo repaint with whatever `data-theme` subtree it is dropped into.
+ */
+declare function Logo({
+  variant,
+  size,
+  className,
+  style,
+  ...props
+}: LogoProps): import("react").JSX.Element;
 interface AlertProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'> {
   /**
    * Severity tone: `default` (neutral), `info`, `success`, `warning` or `destructive`. Sets
@@ -556,6 +595,16 @@ interface TextareaProps extends TextareaHTMLAttributes<HTMLTextAreaElement> {
   hint?: string;
   error?: string;
   resize?: 'none' | 'vertical' | 'both';
+  /**
+   * Grow the control with its content instead of holding the fixed rows height. rows becomes
+   * the minimum and --cascivo-textarea-max-block-size (default 20lh) the ceiling. Pure CSS
+   * (field-sizing: content) — no measurement and no listener; where unsupported the fixed
+   * rows height is kept.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
+  autosize?: boolean;
 }
 /**
  * `forwardRef` so `ref` reaches the underlying `<textarea>` — and so it is TYPED.
@@ -1283,6 +1332,11 @@ interface SideNavGroup {
   label?: string;
   items: SideNavItem[];
 }
+/** What the `header` / `footer` render functions receive. */
+interface SideNavSlotContext {
+  /** `true` while the nav is collapsed to its icon rail. */
+  collapsed: boolean;
+}
 interface SideNavProps {
   items?: SideNavItem[];
   groups?: SideNavGroup[];
@@ -1338,11 +1392,20 @@ interface SideNavProps {
    * @see the component manifest
    */
   showCollapseToggle?: boolean;
-  /** Content rendered above the items, inside the item padding context. */
-  header?: ReactNode;
+  /**
+   * Content rendered above the items, inside the item padding context.
+   *
+   * Accepts a render function as well as a node: `header={({ collapsed }) => …}` receives
+   * the live rail state, so a team switcher can shrink to its avatar on the rail instead of
+   * being clipped. `SideNavItem.render` already worked this way; the slots did not, which is
+   * what forced an adopter to control `collapsed` from outside purely to read it
+   * (2026-08-31 report §18).
+   */
+  header?: ReactNode | ((ctx: SideNavSlotContext) => ReactNode);
   /** Content rendered above the collapse toggle, inside the item padding context —
-   * it lines up with the nav items above it, exactly as `header` does. */
-  footer?: ReactNode;
+   * it lines up with the nav items above it, exactly as `header` does. Accepts the same
+   * `({ collapsed }) => …` render function. */
+  footer?: ReactNode | ((ctx: SideNavSlotContext) => ReactNode);
   className?: string;
 }
 declare function SideNav({
@@ -1641,7 +1704,19 @@ interface OverflowMenuProps {
    */
   label?: string;
   size?: 'sm' | 'md';
+  /**
+   * When true, disables the control and removes it from the tab order.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   disabled?: boolean;
+  /**
+   * Tab-order position of the trigger. A composite widget that manages its own focus (a
+   * `DataTable` in grid keyboard mode) passes `-1` so the menu stays reachable by Enter on
+   * its cell without becoming an extra Tab stop.
+   */
+  tabIndex?: number;
   className?: string;
 }
 declare function OverflowMenu({
@@ -1652,6 +1727,7 @@ declare function OverflowMenu({
   label,
   size,
   disabled,
+  tabIndex,
   className
 }: OverflowMenuProps): import("react").JSX.Element;
 interface SearchProps {
@@ -1698,13 +1774,18 @@ interface SearchProps {
    */
   label?: string;
   /**
-   * Invisible accessible name, for when a visible element outside this component already
-   * labels it and `label` would render that text a second time.
+   * Accessible name set through `aria-label` instead of a rendered `<label>` element.
    *
-   * `label` on this component is **visible**. `IconButton.label` and `Sparkline.label` are
-   * invisible names, so an adopter arriving with that prior writes `label` here and gets the
-   * text twice (2026-08-22 report item 13). Both props are listed side by side, each saying
-   * which it is.
+   * ⚠ On `Search`, **both** props give an invisible name — `label` renders a real `<label>`
+   * that the stylesheet visually hides (see it above). The two differ in mechanism, not in
+   * what you see: `label` names the control through a `<label for>` association, `ariaLabel`
+   * through the attribute. Use `ariaLabel` when a visible element outside the component
+   * already labels the field, so nothing is announced twice; use `label` otherwise.
+   *
+   * This docblock previously read "`label` on this component is **visible**", copied from
+   * `Input`/`Select`/`Toggle` where that is true. It is not true here, and the contradiction
+   * sat inside the `.d.ts` the docs tell you to trust over everything else (2026-08-31
+   * report §20).
    */
   ariaLabel?: string;
   /**
@@ -1798,12 +1879,94 @@ interface NumberInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, '
  * incomplete, which is why the rule is a guard and not a checklist.
  */
 declare const NumberInput: import("react").ForwardRefExoticComponent<NumberInputProps & import("react").RefAttributes<HTMLInputElement>>;
+/**
+ * Per-column filtering, kept pure so the table's filter pipeline is testable without a DOM
+ * and stays O(rows) per change — never per render.
+ *
+ * Three filter shapes cover what dashboards actually ask for (the same three TanStack's
+ * column-filtering guide leads with): a substring on text, a set of allowed values on an
+ * enumerated column, and a numeric range. Values arrive from the table's own inputs or from
+ * a controlled `filters` prop, so the shape is a plain serialisable object — it round-trips
+ * through a URL or storage unchanged.
+ */
+/** The kind of filter control a column offers. */
+type ColumnFilterKind = 'text' | 'select' | 'range';
+/** The current value of one column's filter. An inactive filter is simply absent. */
+type ColumnFilterValue = {
+  kind: 'text';
+  value: string;
+} | {
+  kind: 'select';
+  values: string[];
+} | {
+  kind: 'range';
+  min?: number;
+  max?: number;
+};
+/** Active filters by column key. */
+type ColumnFilters = Record<string, ColumnFilterValue>;
+/**
+ * Column layout as data: which columns show, in what order, how wide, and which stick to
+ * an edge. Every transition the header menu and the resize handle perform is a pure
+ * function here, so the table never reasons about layout in JSX and each rule is
+ * testable on its own.
+ *
+ * The shape is deliberately a plain object of keys (`ColumnState`): it round-trips through
+ * storage or a URL, and it survives the column definitions changing underneath it — a key
+ * that no longer exists is ignored, a new column simply takes its definition position.
+ */
+/** Which edge a pinned column sticks to. */
+type PinSide = 'start' | 'end';
+/** User-adjustable column layout. All fields optional; an absent field means "as defined". */
+interface ColumnState {
+  /** Keys of hidden columns. At least one column always stays visible. */
+  hidden?: string[];
+  /** Display order of column keys; keys not listed follow in definition order. */
+  order?: string[];
+  /** Explicit widths in px, by key — what the resize handle writes. */
+  widths?: Record<string, number>;
+  /** Pinned columns by key. Pinned-start columns render first, pinned-end last. */
+  pinned?: Record<string, PinSide>;
+}
+/**
+ * Row grouping, aggregation and column-group spans as data. The table's body is a flat
+ * list either way — grouping just interleaves group rows with the leaf rows they own, so
+ * paging, the virtual window and the grid keyboard model need no notion of a tree.
+ */
+/** Built-in aggregations for `Column.aggregate`. */
+type AggregateKind = 'sum' | 'avg' | 'min' | 'max' | 'count';
+/** A band of columns under one header (`columnGroups`). */
+interface ColumnGroup {
+  header: string;
+  /** Column keys in the band. Non-adjacent keys render as separate spans. */
+  columns: string[];
+}
 interface Column<Row> {
   key: string;
   header: string;
   sortable?: boolean;
   render?: (row: Row) => ReactNode;
   align?: 'start' | 'end';
+  /**
+   * Offer a per-column filter in a row under the header: `'text'` is a substring input,
+   * `'select'` a faceted checklist of the column's distinct values with counts, `'range'` a
+   * numeric min/max pair. Filters AND together and combine with the global search; the
+   * current values are readable and controllable through the `filters` props.
+   */
+  filter?: ColumnFilterKind;
+  /**
+   * Let the user edit this column's cells in place. Each cell renders an `Editable`
+   * (click, Enter or F2 to start; Enter commits, Escape cancels) and commits through the
+   * table's `onCellEdit`. Ignored when the column has a `render` — a custom cell brings its
+   * own control — or the table has no `onCellEdit`.
+   */
+  editable?: boolean;
+  /**
+   * What a group row and the `totals` row show for this column: a built-in reduction over
+   * the numeric cell values (`'count'` counts rows), or a function of the rows for anything
+   * else — a formatted currency, a distinct count, a sparkline.
+   */
+  aggregate?: AggregateKind | ((rows: Row[]) => ReactNode);
   /**
    * Preferred column width, any CSS length (`'8rem'`, `'120px'`, `'12%'`). Set it on
    * identifier-shaped columns (ids, statuses, dates) so they stop stealing space from the
@@ -1841,10 +2004,64 @@ interface Column<Row> {
   minWidth?: string;
 }
 type SortDirection = 'asc' | 'desc';
-interface SortState {
+/** One sorted column. */
+interface SortKey {
   key: string;
   direction: SortDirection;
 }
+/**
+ * The active sort. `thenBy` lists the secondary columns that break ties, in order — set
+ * by Shift-clicking headers when `multiSort` is on, or passed directly.
+ */
+interface SortState extends SortKey {
+  thenBy?: SortKey[];
+}
+/** One entry in a row's actions menu (`rowActions`). */
+interface RowAction<Row> {
+  id: string;
+  label: string;
+  /** Activation handler; receives the row the menu belongs to. */
+  onSelect: (row: Row) => void;
+  destructive?: boolean;
+  disabled?: boolean;
+  icon?: ReactNode;
+}
+/** Everything the table needs the server to apply, when `server` is set. */
+interface TableQuery {
+  sort: SortState | undefined;
+  /** Trimmed global search text; empty when the box is blank. */
+  search: string;
+  filters: ColumnFilters;
+  /** 1-based page. */
+  page: number;
+  pageSize: number;
+}
+/**
+ * Server-driven mode: the table renders `rows` as the current page verbatim and asks the
+ * server for anything that would change them. Sort, search, per-column filters and paging
+ * all stop running on the client at once — one switch, not four.
+ */
+interface DataTableServer {
+  /** Total rows across every page; drives the pager and the range label. */
+  totalItems?: number;
+  /**
+   * Called with the full query whenever sort, search, a filter, the page or the page size
+   * changes. Not called on mount: the rows you passed for the initial render are the first
+   * page.
+   */
+  onQueryChange: (query: TableQuery) => void;
+}
+/** Which column-layout controls the table offers. All off by default. */
+interface ColumnSettings {
+  /** A "Columns" menu in the toolbar that shows and hides columns. */
+  visibility?: boolean;
+  /** A drag handle on each header's trailing edge; arrow keys nudge it, Home resets to auto. */
+  resizable?: boolean;
+  /** "Move left" / "Move right" in each column's header menu. */
+  reorderable?: boolean;
+  /** "Pin to start" / "Pin to end" in each column's header menu; pinned columns stay put while the rest scroll. */
+  pinnable?: boolean;
+}
 interface DataTableLabels {
   search?: string;
   empty?: string;
@@ -1854,6 +2071,31 @@ interface DataTableLabels {
   expandRow?: string;
   previousPage?: string;
   nextPage?: string;
+  columns?: string;
+  actions?: string;
+  noResults?: string;
+  clearFilters?: string;
+  filterColumn?: (column: string) => string;
+  min?: string;
+  max?: string;
+  all?: string;
+  columnMenu?: (column: string) => string;
+  sortAscending?: string;
+  sortDescending?: string;
+  clearSort?: string;
+  moveLeft?: string;
+  moveRight?: string;
+  pinStart?: string;
+  pinEnd?: string;
+  unpin?: string;
+  hideColumn?: string;
+  resizeColumn?: (column: string) => string;
+  /** Accessible name of an editable cell's control; receives the column header. */
+  editCell?: (column: string) => string;
+  /** Label of the `totals` row. */
+  totals?: string;
+  /** The export button. */
+  exportCsv?: string;
 }
 interface DataTableProps<Row> {
   columns: Column<Row>[];
@@ -1870,9 +2112,15 @@ interface DataTableProps<Row> {
    * @see the component manifest
    */
   searchable?: boolean;
+  /**
+   * Client-side paging, or the pager for a `server`-driven table. `page` makes the current
+   * page controlled; with `server`, `pageSize`/`page` are echoed back in every `TableQuery`.
+   */
   pagination?: {
     pageSize: number;
     pageSizeOptions?: number[];
+    page?: number;
+    onPageChange?: (page: number) => void;
   };
   selection?: {
     mode: 'single' | 'multi';
@@ -1885,6 +2133,109 @@ interface DataTableProps<Row> {
     onClick: (selectedIds: string[]) => void;
   }[];
   renderExpandedRow?: (row: Row) => ReactNode;
+  /** Per-column filter values (controlled). Columns opt in with `Column.filter`. */
+  filters?: ColumnFilters;
+  /** Initial per-column filter values (uncontrolled). */
+  defaultFilters?: ColumnFilters;
+  /** Called with the full filter map whenever any column filter changes. */
+  onFiltersChange?: (filters: ColumnFilters) => void;
+  /**
+   * Shown instead of `emptyState` when there ARE rows but the search or filters match none
+   * of them — a different message from "no data", and the moment to offer a reset.
+   */
+  noResultsState?: ReactNode;
+  /** Extra controls rendered in the toolbar, next to the search box (exports, primary actions). */
+  toolbar?: ReactNode;
+  /**
+   * Per-row actions. Returns the menu entries for a row; the table renders them as a
+   * trailing "⋯" overflow menu column, keyboard-reachable like every other cell control.
+   */
+  rowActions?: (row: Row) => RowAction<Row>[];
+  /** Column layout (controlled): hidden, order, widths, pinned. See {@link ColumnState}. */
+  columnState?: ColumnState;
+  /** Initial column layout (uncontrolled). */
+  defaultColumnState?: ColumnState;
+  /** Called with the full column layout whenever the user changes it. */
+  onColumnStateChange?: (state: ColumnState) => void;
+  /** Which column-layout controls to offer; see {@link ColumnSettings}. */
+  columnSettings?: ColumnSettings;
+  /** Hand sort, search, filters and paging to the server; see {@link DataTableServer}. */
+  server?: DataTableServer;
+  /**
+   * Allow sorting by more than one column: Shift-click a header adds it as a tie-breaker
+   * (`SortState.thenBy`); a plain click replaces the whole sort. Sorted headers show their
+   * level.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
+  multiSort?: boolean;
+  /**
+   * Remember the user's column layout and sort across reloads, in local storage under this
+   * key. Applies when the corresponding props are uncontrolled; a controlled `columnState`
+   * or `sort` still wins. Two tables with the same key share the preference.
+   */
+  stateKey?: string;
+  /**
+   * How the keyboard moves through the table. `'row'` keeps every control in the Tab order
+   * and lets the arrows step between them. `'grid'` is the APG data-grid pattern: the table
+   * is ONE Tab stop, the arrows move a focused cell, Home/End jump within the row,
+   * Ctrl+Home/End to the corners, PageUp/PageDown by a screenful, Enter or F2 enters the
+   * cell's control and Escape returns to the cell. Cells outside the virtualized window are
+   * scrolled to. Prefer `'grid'` for wide or editable tables, where tabbing through every
+   * control is the complaint.
+   *
+   * @defaultValue `row`
+   * @see the component manifest
+   */
+  keyboardNavigation?: 'row' | 'grid';
+  /**
+   * Commits an inline edit: the row, the edited column's key and the new text. Enables
+   * editing for every column marked `editable`; the table does not mutate `rows` itself.
+   */
+  onCellEdit?: (row: Row, key: string, value: string) => void;
+  /**
+   * Group the rows by one or more columns, in order. Each group is a collapsible row
+   * showing its value, its row count and every `aggregate` column's reduction; leaves keep
+   * the current sort inside their group. Groups appear in order of first occurrence, so
+   * sort by the grouped column to order them.
+   */
+  groupBy?: string | string[];
+  /**
+   * Show a totals row under the body with each `aggregate` column's reduction over every
+   * row that passes the search and filters (not just the page). Sticks to the bottom of
+   * the scroller.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
+  totals?: boolean;
+  /**
+   * Rows kept in view outside sort, search, filters, paging and the virtual window: `top`
+   * rows sit under the header (stuck there with `stickyHeader`), `bottom` rows above the
+   * totals. Rendered with the same columns as the body.
+   */
+  pinnedRows?: {
+    top?: Row[];
+    bottom?: Row[];
+  };
+  /**
+   * Bands of columns under a shared header, rendered as a row above the column headers.
+   * A band's columns should be adjacent; reordering them apart splits the band.
+   */
+  columnGroups?: ColumnGroup[];
+  /**
+   * An "Export CSV" button in the toolbar: every row passing the search and filters (all
+   * pages; with `server`, the rows given), in the current sort, visible columns as headers,
+   * raw cell values as fields (RFC 4180, UTF-8 with BOM). Pass `{ filename }` to name the
+   * file; it defaults to the `title`.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
+  exportable?: boolean | {
+    filename?: string;
+  };
   /**
    * Row height preset.
    *
@@ -1941,17 +2292,16 @@ interface DataTableProps<Row> {
    */
   virtualized?: boolean;
   /**
-   * Fixed row height in px, used to compute the virtualized window.
+   * Row height in px for the virtualized window.
    *
-   * @defaultValue `40`
-   * @see the component manifest
+   * Measured from the first rendered row when omitted, so the density presets stay correct
+   * — the old fixed default of 40 never matched them (rows are 36/48/60 px plus a border),
+   * and a wrong value scales the whole scrollbar. Set it only for custom-sized rows.
    */
   rowHeight?: number;
   /**
-   * Number of rows rendered in the virtualized window.
-   *
-   * @defaultValue `20`
-   * @see the component manifest
+   * Rows rendered per window. Derived from the scroller's height when omitted; set it only
+   * to render a fixed count regardless of height.
    */
   windowSize?: number;
   /**
@@ -1975,6 +2325,26 @@ declare function DataTable<Row>({
   selection,
   batchActions,
   renderExpandedRow,
+  filters,
+  defaultFilters,
+  onFiltersChange,
+  noResultsState,
+  toolbar,
+  rowActions,
+  columnState,
+  defaultColumnState,
+  onColumnStateChange,
+  columnSettings,
+  server,
+  multiSort,
+  stateKey,
+  keyboardNavigation,
+  onCellEdit,
+  groupBy,
+  totals,
+  pinnedRows,
+  columnGroups,
+  exportable,
   density,
   zebra,
   stickyHeader,
@@ -2050,6 +2420,12 @@ interface CommandMenuProps {
   open: boolean;
   onOpenChange: (open: boolean) => void;
   groups: CommandGroup[];
+  /**
+   * Placeholder text shown when the field is empty.
+   *
+   * @defaultValue `Type a command or search…`
+   * @see the component manifest
+   */
   placeholder?: string;
   /**
    * Text shown when no commands match the query.
@@ -2196,22 +2572,49 @@ declare function Form<T extends Record<string, unknown>>({
   className,
   ...props
 }: FormProps<T>): import("react").JSX.Element;
+/**
+ * Option filtering, grouping and match highlighting for `Combobox`, kept pure so the list
+ * pipeline is testable without a DOM and runs once per query change rather than per render.
+ *
+ * Matching folds diacritics: a user typing `zurich` expects `Zürich`, and a filtered option
+ * list is exactly where that gap bites, because the user cannot see why their query returns
+ * nothing. Folding is done per code point so the folded string stays index-aligned with the
+ * original — that alignment is what lets `highlightSegments` mark the match on the label the
+ * user actually reads rather than on a normalised copy of it.
+ *
+ * `MultiSelect` carries the same four operations against its own option type. They are
+ * deliberately not shared: a registry component is copied into an adopter's project as a
+ * self-contained folder, so a cross-component import would make `cascivo add combobox`
+ * drag in a sibling component's files. The catalog already accepts this for the menu /
+ * context-menu navigation pair.
+ */
+/** One selectable option. A list mixing grouped and ungrouped options renders the ungrouped ones first. */
 interface ComboboxOption {
-  value: string;
   label: string;
+  value: string;
   /**
-   * When true, disables the control and removes it from the tab order.
+   * When true, the option cannot be selected and is skipped by keyboard navigation.
    *
    * @defaultValue `false`
    * @see the component manifest
    */
   disabled?: boolean;
+  /** Optional group heading this option belongs to. */
+  group?: string;
 }
 interface ComboboxLabels {
   placeholder?: string;
   empty?: string;
   clear?: string;
+  /**
+   * @deprecated Named the in-popup search input, which no longer exists — the field itself is
+   * the combobox. Ignored; removed in 2.0.
+   */
   search?: string;
+  /** Text shown in place of the empty message while `loading` is true. */
+  loading?: string;
+  /** Template for the "create" row; `{label}` is replaced with the typed text. */
+  create?: string;
 }
 interface ComboboxProps {
   /**
@@ -2240,7 +2643,9 @@ interface ComboboxProps {
    */
   clearable?: boolean;
   /**
-   * When true, shows a search/filter input.
+   * When true the field is a text input that filters the list as the user types (the APG
+   * editable combobox). When false it is a button that opens the list, and type-to-select
+   * jumps to a matching option (the APG select-only combobox).
    *
    * @defaultValue `true`
    * @see the component manifest
@@ -2260,7 +2665,49 @@ interface ComboboxProps {
   hint?: string;
   error?: string;
   size?: 'sm' | 'md' | 'lg';
+  /**
+   * When true, disables the control and removes it from the tab order.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   disabled?: boolean;
+  /**
+   * When true, the list reports itself as busy and shows a loading row instead of the empty
+   * message.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
+  loading?: boolean;
+  /** Called with the search text on every keystroke. Pair it with `filter={() => true}` for a server-driven list. */
+  onSearchChange?: (query: string) => void;
+  /** Replaces the built-in diacritic-insensitive matcher. */
+  filter?: (option: ComboboxOption, query: string) => boolean;
+  /**
+   * When true, offers the current search text as a new option.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
+  creatable?: boolean;
+  /** Called with the typed label when the user picks the "create" row. */
+  onCreate?: (label: string) => void;
+  /** Submitted with a surrounding form — a hidden input carrying the selected value. */
+  name?: string;
+  /** Marks the control as required for assistive technology. */
+  required?: boolean;
+  /** Controlled open state of the listbox. */
+  open?: boolean;
+  /**
+   * The initial open state when uncontrolled.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
+  defaultOpen?: boolean;
+  /** Called when the listbox opens or closes. */
+  onOpenChange?: (open: boolean) => void;
   labels?: ComboboxLabels;
   className?: string;
   id?: string;
@@ -2278,6 +2725,16 @@ declare function Combobox({
   error,
   size,
   disabled,
+  loading,
+  onSearchChange,
+  filter,
+  creatable,
+  onCreate,
+  name,
+  required,
+  open,
+  defaultOpen,
+  onOpenChange,
   labels,
   className,
   id,
@@ -2290,6 +2747,8 @@ interface DatePickerLabels {
   previousMonth?: string;
   nextMonth?: string;
   clear?: string;
+  open?: string;
+  today?: string;
 }
 interface DatePickerProps {
   /**
@@ -2311,6 +2770,8 @@ interface DatePickerProps {
   onValueChange?: (value: string | undefined) => void;
   min?: string;
   max?: string;
+  /** Rejects individual dates the bounds allow — holidays, weekends, taken slots. */
+  disabledDate?: (date: Date) => boolean;
   /**
    * Shows a clear button
    *
@@ -2345,6 +2806,30 @@ interface DatePickerProps {
    * @see the component manifest
    */
   disabled?: boolean;
+  /**
+   * When true, the field accepts a typed date as well as one picked from the calendar.
+   *
+   * @defaultValue `true`
+   * @see the component manifest
+   */
+  typeable?: boolean;
+  /** Formatting options for the displayed date. Defaults to the locale's numeric form. */
+  format?: Intl.DateTimeFormatOptions;
+  /**
+   * When true, the calendar offers a button that jumps to the current month.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
+  showToday?: boolean;
+  /** Submitted with a surrounding form — a hidden input carrying the ISO value. */
+  name?: string;
+  /** Marks the control as required for assistive technology. */
+  required?: boolean;
+  /** Controlled open state of the calendar popup. */
+  open?: boolean;
+  /** Called when the popup opens or closes. */
+  onOpenChange?: (open: boolean) => void;
   labels?: DatePickerLabels;
   className?: string;
   id?: string;
@@ -2355,6 +2840,7 @@ declare function DatePicker({
   onValueChange,
   min,
   max,
+  disabledDate,
   clearable,
   label,
   ariaLabel,
@@ -2362,6 +2848,13 @@ declare function DatePicker({
   error,
   size,
   disabled,
+  typeable,
+  format,
+  showToday,
+  name,
+  required,
+  open,
+  onOpenChange,
   labels,
   className,
   id,
@@ -2793,16 +3286,29 @@ interface PasswordInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>,
  * incomplete, which is why the rule is a guard and not a checklist.
  */
 declare const PasswordInput: import("react").ForwardRefExoticComponent<PasswordInputProps & import("react").RefAttributes<HTMLInputElement>>;
+/**
+ * Option filtering, grouping and match highlighting, kept pure so the list pipeline is
+ * testable without a DOM and runs once per query change rather than per render.
+ *
+ * Matching folds diacritics because a German user typing `zurich` expects `Zürich`, and an
+ * option list is exactly where that gap bites: the user cannot see why their query returns
+ * nothing. Folding is done per code point so the folded string stays index-aligned with the
+ * original — that alignment is what lets `highlightSegments` mark the match on the label the
+ * user actually reads rather than on a normalised copy of it.
+ */
+/** One selectable option. `group` is optional; a list mixing grouped and ungrouped options renders the ungrouped ones first. */
 interface MultiSelectOption {
   label: string;
   value: string;
   /**
-   * When true, disables the control and removes it from the tab order.
+   * When true, the option cannot be selected and is skipped by keyboard navigation.
    *
    * @defaultValue `false`
    * @see the component manifest
    */
   disabled?: boolean;
+  /** Optional group heading this option belongs to. */
+  group?: string;
 }
 interface MultiSelectLabels {
   label?: string;
@@ -2810,23 +3316,155 @@ interface MultiSelectLabels {
   selected?: (count: number) => string;
   search?: string;
   noResults?: string;
+  /** Text shown in place of the no-results message while `loading` is true. */
+  loading?: string;
+  clear?: string;
+  remove?: string;
+  /** Text on the select-all row while nothing is selected. */
+  selectAll?: string;
+  clearAll?: string;
+  create?: string;
 }
-interface MultiSelectProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange'> {
+interface MultiSelectProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue'> {
+  /**
+   * Wired automatically by a wrapping `Field` — its label id. Forwarded to the focusable
+   * control so the Field's label names it.
+   */
+  'aria-labelledby'?: string;
+  /**
+   * Wired automatically by a wrapping `Field` — the ids of its hint/error text. **Merged**
+   * with this component's own `hint`/`error` ids rather than replacing them, so both are
+   * announced.
+   */
+  'aria-describedby'?: string;
+  /** Wired automatically by a wrapping `Field` when it is in an error state. */
+  'aria-invalid'?: boolean;
   options: MultiSelectOption[];
-  value: string[];
-  onValueChange: (v: string[]) => void;
+  /** The controlled value. Omit it and pass `defaultValue` to let the component own the selection. */
+  value?: string[];
+  /**
+   * The initial value when uncontrolled.
+   *
+   * @defaultValue `[]`
+   * @see the component manifest
+   */
+  defaultValue?: string[];
+  /** Called with the new value when it changes. */
+  onValueChange?: (value: string[]) => void;
   placeholder?: string;
+  /** Visible field label. */
+  label?: string;
+  /**
+   * Invisible accessible name, for when a visible element outside this component already
+   * labels it and `label` would render that text a second time.
+   *
+   * `label` on this component is **visible**. `IconButton.label` and `Sparkline.label` are
+   * invisible names, so an adopter arriving with that prior writes `label` here and gets the
+   * text twice (2026-08-22 report item 13). Both props are listed side by side, each saying
+   * which it is.
+   */
+  ariaLabel?: string;
+  hint?: string;
+  error?: string;
+  /**
+   * How the trigger summarises the selection: a count, or one removable chip per value.
+   *
+   * @defaultValue `'count'`
+   * @see the component manifest
+   */
+  display?: 'count' | 'chips';
+  /**
+   * When true, disables the control and removes it from the tab order.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   disabled?: boolean;
+  /**
+   * When true, shows a control that clears every selected value.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
+  clearable?: boolean;
+  /**
+   * When true, shows a row that selects or clears every enabled option at once.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
+  selectAll?: boolean;
+  /** Maximum number of values that may be selected. Further options become unselectable once reached. */
+  max?: number;
+  /**
+   * When true, offers the current search text as a new option.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
+  creatable?: boolean;
+  /** Called with the typed label when the user picks the "create" row. */
+  onCreate?: (label: string) => void;
+  /**
+   * When true, the list reports itself as busy and shows a loading row instead of the
+   * no-results message.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
+  loading?: boolean;
+  /** Called with the search text on every keystroke. Pair it with `filter={() => true}` for a server-driven list. */
+  onSearchChange?: (query: string) => void;
+  /** Replaces the built-in diacritic-insensitive matcher. */
+  filter?: (option: MultiSelectOption, query: string) => boolean;
+  /**
+   * When true, shows the search field. The list is keyboard-navigable either way.
+   *
+   * @defaultValue `true`
+   * @see the component manifest
+   */
+  searchable?: boolean;
+  /**
+   * Field height.
+   *
+   * @defaultValue `'md'`
+   * @see the component manifest
+   */
+  size?: 'sm' | 'md' | 'lg';
+  /** Submitted with a surrounding form — one hidden input per selected value. */
+  name?: string;
   labels?: MultiSelectLabels;
+  id?: string;
 }
 declare function MultiSelect({
   options,
   value,
+  defaultValue,
   onValueChange,
   placeholder,
+  label,
+  ariaLabel,
+  hint,
+  error,
+  display,
   disabled,
+  clearable,
+  selectAll,
+  max,
+  creatable,
+  onCreate,
+  loading,
+  onSearchChange,
+  filter,
+  searchable,
+  size,
+  name,
   labels,
   className,
+  id,
+  'aria-labelledby': ariaLabelledBy,
+  'aria-describedby': ariaDescribedBy,
+  'aria-invalid': ariaInvalid,
   ...props
 }: MultiSelectProps): import("react").JSX.Element;
 interface TagsInputProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange'> {
@@ -2925,6 +3563,24 @@ interface SegmentedControlProps extends Omit<HTMLAttributes<HTMLDivElement>, 'on
   value: string;
   onValueChange: (v: string) => void;
   size?: 'sm' | 'md' | 'lg';
+  /**
+   * Accessible name for the group. Invisible — it names the `role="group"`, it renders
+   * nothing.
+   *
+   * This component extended `HTMLAttributes` and nothing else, so it took the raw DOM
+   * `aria-label` while every sibling in the catalog took `ariaLabel` — the one control in an
+   * adopter's filter toolbar where the catalog spelling was a type error (2026-08-31 report
+   * §21). Both spellings work now; the raw `aria-label` still wins if you pass both.
+   */
+  ariaLabel?: string;
+  /** Alias of `ariaLabel` — same invisible accessible name, the other spelling. Not rendered. */
+  label?: string;
+  /**
+   * When true, disables the control and removes it from the tab order.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   disabled?: boolean;
 }
 declare function SegmentedControl({
@@ -2933,6 +3589,8 @@ declare function SegmentedControl({
   onValueChange,
   size,
   disabled,
+  ariaLabel,
+  label,
   className,
   ...props
 }: SegmentedControlProps): import("react").JSX.Element;
@@ -3042,9 +3700,11 @@ declare function Editable({
   onCancel,
   className,
   id,
+  'aria-label': ariaLabel,
   'aria-labelledby': ariaLabelledBy,
   'aria-describedby': ariaDescribedBy,
   'aria-invalid': ariaInvalid,
+  tabIndex,
   ...props
 }: EditableProps): import("react").JSX.Element;
 interface RadioCardGroupProps {
@@ -3558,6 +4218,19 @@ interface LogLine {
   text: string;
   /** Semantic level driving the row color when `ansi` is off. */
   level?: LogLevel;
+  /**
+   * Timestamp for the line, rendered in its own dimmed, column-aligned gutter.
+   *
+   * Pass it here rather than prefixing `text` by hand. A timestamp inside `text` cannot be
+   * dimmed or aligned independently and pollutes the built-in search — typing `08:59` matched
+   * every line of a build log (2026-08-31 report §23). This gutter is excluded from both
+   * search and the match count, and from the text the copy button writes; `timestampWidth`
+   * sizes it.
+   *
+   * Pre-formatted on purpose: every console formats its clock differently (relative offsets,
+   * ISO, locale time), and `@cascivo/i18n`'s formatters already cover that.
+   */
+  timestamp?: string;
 }
 interface LogViewerLabels {
   searchPlaceholder?: string;
@@ -3602,6 +4275,14 @@ interface LogViewerProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'
   search?: string;
   /** Max block size of the scroll region (CSS length). Default '24rem'. */
   maxHeight?: string;
+  /**
+   * Width of the `LogLine.timestamp` gutter (CSS length). Widen it for an ISO stamp, narrow
+   * it for a relative offset.
+   *
+   * @defaultValue `'6.5rem'`
+   * @see the component manifest
+   */
+  timestampWidth?: string;
   labels?: LogViewerLabels;
 }
 /**
@@ -3619,6 +4300,7 @@ declare function LogViewer({
   ansi,
   search,
   maxHeight,
+  timestampWidth,
   labels,
   className,
   ...props
@@ -4008,6 +4690,12 @@ interface ToggleGroupProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChang
    */
   orientation?: 'horizontal' | 'vertical';
   size?: 'sm' | 'md' | 'lg';
+  /**
+   * When true, disables the control and removes it from the tab order.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   disabled?: boolean;
 }
 declare const ToggleGroup: import("react").ForwardRefExoticComponent<ToggleGroupProps & import("react").RefAttributes<HTMLDivElement>>;
@@ -4167,6 +4855,12 @@ interface MenuButtonProps {
   items: MenuButtonItem[];
   variant?: 'primary' | 'secondary' | 'ghost';
   size?: 'sm' | 'md' | 'lg';
+  /**
+   * Disables the trigger
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   disabled?: boolean;
   align?: 'start' | 'end';
   labels?: {
@@ -4294,13 +4988,34 @@ interface TreeNode {
   label: ReactNode;
   icon?: ReactNode;
   children?: TreeNode[];
+  /**
+   * When true, the node cannot be selected and is skipped by keyboard navigation and
+   * type-to-select.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
+  disabled?: boolean;
+  /**
+   * Plain-text form of `label`, for type-to-select when the label is JSX.
+   *
+   * Typeahead matched `typeof label === 'string'`, so it silently did nothing for any node
+   * rendering an icon beside its text — the common case.
+   */
+  textValue?: string;
 }
 interface TreeViewProps {
   items: TreeNode[];
   selectionMode?: 'single' | 'multi';
   selected?: string | string[];
   defaultSelected?: string | string[];
+  /**
+   * @deprecated Use `onValueChange`. The catalog names a value-carrying handler
+   * `onValueChange`; `onSelectChange` appears on this component alone. Still honoured.
+   */
   onSelectChange?: (selected: string | string[]) => void;
+  /** Called with the new selection. */
+  onValueChange?: (selected: string | string[]) => void;
   expanded?: string[];
   defaultExpanded?: string[];
   onExpandedChange?: (expanded: string[]) => void;
@@ -4326,6 +5041,7 @@ declare function TreeView({
   selected,
   defaultSelected,
   onSelectChange,
+  onValueChange,
   expanded,
   defaultExpanded,
   onExpandedChange,
@@ -4410,13 +5126,30 @@ declare function ContainedListItem({
   children,
   ...props
 }: ContainedListItemProps): import("react").JSX.Element;
-interface DataListItem {
+/** One label/value pair in a config-driven `DataList`. */
+interface DataListEntry {
   id?: string;
   label: ReactNode;
   value: ReactNode;
 }
+/**
+ * The label/value pair shape.
+ *
+ * @deprecated Use `DataListEntry`. `DataListItem` is now also the **component** — every
+ * structural sibling in the catalog is one (`AccordionItem`, `ContextMenuItem`,
+ * `TimelineItem`, `ListItem`, `ContainedListItem`, `StructuredListItem`, `SwipeItem`), so an
+ * adopter wrote `<DataList><DataListItem label="Domain">…</DataListItem></DataList>` and hit
+ * a type where a component belonged (2026-08-31 report §22). TypeScript keeps a type and a
+ * function of the same name in separate spaces, so this alias holds existing
+ * `DataListItem[]` annotations compiling while the JSX now works; it is removed at 2.0.
+ */
+type DataListItem = DataListEntry;
 interface DataListProps extends HTMLAttributes<HTMLDListElement> {
-  items: DataListItem[];
+  /**
+   * The pairs to render. Omit it and pass `<DataListItem>` children instead when a value
+   * needs surrounding JSX (a `Status`, a `CopyButton`) that reads better inline.
+   */
+  items?: DataListEntry[];
   /**
    * Where each **value** sits relative to its own label — not the axis of the list.
    *
@@ -4438,6 +5171,8 @@ interface DataListProps extends HTMLAttributes<HTMLDListElement> {
    */
   dividers?: boolean;
   size?: 'sm' | 'md';
+  /** `<DataListItem>` rows, as an alternative to `items`. */
+  children?: ReactNode;
 }
 declare function DataList({
   items,
@@ -4445,8 +5180,26 @@ declare function DataList({
   dividers,
   size,
   className,
+  children,
   ...props
 }: DataListProps): import("react").JSX.Element;
+interface DataListItemProps {
+  /** The term. Rendered as the row's `<dt>`. */
+  label: ReactNode;
+  /** The value. Rendered as the row's `<dd>`. */
+  children: ReactNode;
+}
+/**
+ * One row of a `DataList`, for when a value needs surrounding JSX that reads better inline
+ * than inside an `items` array.
+ *
+ * Must be a direct child of `DataList` — it renders the `<dt>`/`<dd>` pair that a `<dl>`
+ * expects, and inherits every layout token (`orientation`, `size`, `dividers`) from it.
+ */
+declare function DataListItem({
+  label,
+  children
+}: DataListItemProps): import("react").JSX.Element;
 interface TimelineItem {
   id: string;
   title: ReactNode;
@@ -4554,6 +5307,8 @@ declare function ItemActions({
 interface CalendarLabels {
   previousMonth?: string;
   nextMonth?: string;
+  today?: string;
+  weekNumber?: string;
 }
 interface CalendarProps {
   value?: Date | null;
@@ -4572,6 +5327,15 @@ interface CalendarProps {
   size?: 'sm' | 'md' | 'lg';
   labels?: CalendarLabels;
   className?: string;
+  /**
+   * Accessible name for the grid. Defaults to the visible month label.
+   *
+   * Calendar has no visible label slot — the month heading is its own — so `label` and
+   * `ariaLabel` are aliases for the same invisible name. `ariaLabel` wins if both are given.
+   */
+  ariaLabel?: string;
+  /** Alias for `ariaLabel`. See the note there. */
+  label?: string;
   /** Highlight predicate for range previews (date-range-picker). */
   isInRange?: (date: Date) => boolean;
   /** Range endpoint markers for styling. */
@@ -4595,6 +5359,20 @@ interface CalendarProps {
    * @see the component manifest
    */
   hideNav?: boolean;
+  /**
+   * When true, shows a button that jumps the view to the current month and focuses today.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
+  showToday?: boolean;
+  /**
+   * When true, prefixes each row with its ISO-8601 week number.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
+  showWeekNumbers?: boolean;
 }
 declare function Calendar({
   value,
@@ -4607,6 +5385,8 @@ declare function Calendar({
   size,
   labels,
   className,
+  ariaLabel,
+  label,
   isInRange,
   isRangeStart,
   isRangeEnd,
@@ -4614,7 +5394,9 @@ declare function Calendar({
   month,
   year,
   onViewChange,
-  hideNav
+  hideNav,
+  showToday,
+  showWeekNumbers
 }: CalendarProps): import("react").JSX.Element;
 interface DateRange {
   start: Date;
@@ -4675,17 +5457,18 @@ declare function DateRangePicker({
   labels,
   className
 }: DateRangePickerProps): import("react").JSX.Element;
+/** The output formats an adopter can ask for. */
+type ColorFormat = 'hex' | 'rgb' | 'hsl';
 interface ColorPickerLabels {
   hue?: string;
-  /**
-   * When true, enables alpha (opacity) selection.
-   *
-   * @defaultValue `true`
-   * @see the component manifest
-   */
+  /** Accessible name for the alpha slider. */
   alpha?: string;
   colorArea?: string;
+  saturation?: string;
+  brightness?: string;
   eyedropper?: string;
+  presets?: string;
+  hex?: string;
 }
 interface ColorPickerProps {
   /**
@@ -4712,7 +5495,21 @@ interface ColorPickerProps {
   defaultValue?: string;
   onValueChange?: (value: string) => void;
   presets?: string[];
+  /**
+   * When true, enables alpha (opacity) selection.
+   *
+   * @defaultValue `true`
+   * @see the component manifest
+   */
   alpha?: boolean;
+  /**
+   * Notation for the emitted value. Alpha is included whenever `alpha` is on, so the width
+   * of the emitted string is stable.
+   *
+   * @defaultValue `'hex'`
+   * @see the component manifest
+   */
+  format?: ColorFormat;
   label?: string;
   /**
    * Invisible accessible name, for when a visible element outside this component already
@@ -4731,23 +5528,27 @@ interface ColorPickerProps {
    * @see the component manifest
    */
   disabled?: boolean;
+  /** Submitted with a surrounding form — a hidden input carrying the current value. */
+  name?: string;
   size?: 'sm' | 'md' | 'lg';
   className?: string;
   labels?: ColorPickerLabels;
 }
 declare function ColorPicker({
+  id,
   value,
   defaultValue,
   onValueChange,
   presets,
   alpha,
+  format,
   label,
   ariaLabel,
   disabled,
+  name,
   size,
   className,
   labels,
-  id,
   'aria-labelledby': ariaLabelledBy,
   'aria-describedby': ariaDescribedBy,
   'aria-invalid': ariaInvalid
@@ -4756,6 +5557,8 @@ interface CarouselLabels {
   region?: string;
   previous?: string;
   next?: string;
+  play?: string;
+  pause?: string;
 }
 interface CarouselProps {
   children?: ReactNode;
@@ -4776,6 +5579,14 @@ interface CarouselProps {
    * @see the component manifest
    */
   loop?: boolean;
+  /**
+   * Milliseconds between automatic advances. Omit or set 0 to leave rotation off.
+   *
+   * Auto-rotation pauses on hover, on focus within the carousel, while the tab is hidden and
+   * under `prefers-reduced-motion`, and always renders a play/pause control — APG requires
+   * one for any carousel that rotates on its own.
+   */
+  autoplay?: number;
   className?: string;
   labels?: CarouselLabels;
 }
@@ -4786,6 +5597,7 @@ declare function Carousel({
   defaultIndex,
   onIndexChange,
   loop,
+  autoplay,
   className,
   labels
 }: CarouselProps): import("react").JSX.Element;
@@ -5186,6 +5998,10 @@ interface NativeSelectProps extends Omit<SelectHTMLAttributes<HTMLSelectElement>
  * A styled native `<select>` — keeps the platform's open/close, keyboard, and form behavior, and
  * layers on a custom chevron and focus/invalid rings via CSS only. No JS interactivity, so no
  * signals: the browser owns all state. Distinct from the custom-rendered `Select` listbox.
+ *
+ * Where `appearance: base-select` is supported the dropdown surface is themed from
+ * `[data-theme]` too, matching `Dropdown` — see the `@supports` block in the stylesheet. It is
+ * progressive enhancement: elsewhere the OS draws the option list, exactly as before.
  */
 /**
  * `forwardRef` so `ref` reaches the underlying `<select>` — and so it is TYPED. See
@@ -5676,12 +6492,22 @@ interface GridProps extends HTMLAttributes<HTMLDivElement> {
   align?: GridAlign;
   /** Inline-axis alignment of items within their cells (`justify-items`). Defaults to `stretch`. */
   justify?: GridAlign;
+  /**
+   * Align the internal bands of adjacent children via CSS subgrid — every CardHeader in a
+   * row shares one row track, every CardContent the next, every CardFooter the last. Where
+   * subgrid is unsupported the grid renders as it does without this prop.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
+  alignRows?: boolean;
 }
 declare function Grid({
   cols,
   gap,
   align,
   justify,
+  alignRows,
   className,
   style,
   children,
@@ -5734,6 +6560,59 @@ declare function Flex({
   style,
   ...props
 }: FlexProps): import("react").JSX.Element;
+/**
+ * How a `Flex` child sizes itself along the main axis.
+ *
+ * `'auto'` grows and shrinks (`flex: 1 1 auto`); `'fixed'` does neither (`flex: 0 0 auto`),
+ * which is what a fixed-width child like `Sparkline` needs; `'grow'` takes the leftover space
+ * without shrinking below its content; `'shrink'` gives way but never grows.
+ */
+type FlexItemSize = 'auto' | 'fixed' | 'grow' | 'shrink';
+interface FlexItemProps extends HTMLAttributes<HTMLDivElement> {
+  /**
+   * Main-axis sizing behaviour.
+   *
+   * `Flex` had no item-level control at all, so the documented fix for a fixed-width child —
+   * pull it out of flex sizing — was unwritable in cascivo and every dashboard reached for a
+   * raw `style={{ flex: '0 0 auto' }}` wrapper. All four raw-CSS escapes in one 1,500-line
+   * app were this (2026-08-31 report §24).
+   *
+   * @defaultValue `auto`
+   * @see the component manifest
+   */
+  size?: FlexItemSize;
+  /**
+   * `flex-basis` — the child's size before free space is distributed. Any CSS length; `0`
+   * with `size="grow"` gives equal-width columns regardless of content.
+   */
+  basis?: string;
+  /**
+   * Allow the child to shrink below its intrinsic content width.
+   *
+   * A flex item defaults to `min-width: auto`, so a long unbreakable string (a deployment
+   * URL, a commit sha) refuses to shrink and pushes its siblings out of the row. This is the
+   * `minWidth: 0` every layout eventually writes by hand.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
+  truncate?: boolean;
+}
+/**
+ * A `Flex` child with main-axis sizing, the counterpart to `GridItem`.
+ *
+ * Only needed for a child that must NOT size like the rest — a fixed-width `Sparkline`, the
+ * one field in a toolbar that should absorb the leftover width, a cell whose text must be
+ * allowed to ellipsize. Children with no special sizing need no wrapper.
+ */
+declare function FlexItem({
+  size,
+  basis,
+  truncate,
+  className,
+  style,
+  ...props
+}: FlexItemProps): import("react").JSX.Element;
 interface ColumnsProps extends HTMLAttributes<HTMLDivElement> {
   /**
    * Number of equal columns
@@ -5856,6 +6735,7 @@ export {
   ActionSheet,
   ActionSheetAction,
   ActionSheetProps,
+  type AggregateKind,
   Alert,
   AlertDialog,
   AlertDialogLabels,
@@ -5917,15 +6797,19 @@ export {
   CodeSnippetProps,
   Collapsible,
   CollapsibleProps,
+  type ColorFormat,
   ColorPicker,
   ColorPickerLabels,
   ColorPickerProps,
   Column,
+  type ColumnGroup,
+  ColumnSettings,
+  type ColumnState,
   Columns,
   ColumnsProps,
   Combobox,
   ComboboxLabels,
-  ComboboxOption,
+  type ComboboxOption,
   ComboboxProps,
   CommandAction,
   CommandGroup,
@@ -5948,11 +6832,14 @@ export {
   CopyButton,
   CopyButtonProps,
   DataList,
+  DataListEntry,
   DataListItem,
+  DataListItemProps,
   DataListProps,
   DataTable,
   DataTableLabels,
   DataTableProps,
+  DataTableServer,
   DatePicker,
   DatePickerLabels,
   DatePickerProps,
@@ -5991,6 +6878,9 @@ export {
   FilterProps,
   FilterVariant,
   Flex,
+  FlexItem,
+  FlexItemProps,
+  FlexItemSize,
   FlexProps,
   FocusScope,
   Form,
@@ -6072,6 +6962,9 @@ export {
   LogViewer,
   LogViewerLabels,
   LogViewerProps,
+  Logo,
+  LogoProps,
+  LogoVariant,
   type Machine,
   type MachineConfig,
   Menu,
@@ -6093,7 +6986,7 @@ export {
   ModalProps,
   MultiSelect,
   MultiSelectLabels,
-  MultiSelectOption,
+  type MultiSelectOption,
   MultiSelectProps,
   NativeSelect,
   NativeSelectOption,
@@ -6119,6 +7012,7 @@ export {
   PasswordInput,
   PasswordInputLabels,
   PasswordInputProps,
+  type PinSide,
   Popover,
   PopoverContent,
   PopoverContentProps,
@@ -6167,6 +7061,7 @@ export {
   Resizable,
   ResizableProps,
   Responsive,
+  RowAction,
   ScrollArea,
   ScrollAreaProps,
   Search,
@@ -6196,6 +7091,7 @@ export {
   SideNavLinkProps,
   SideNavLinkSubItem,
   SideNavProps,
+  SideNavSlotContext,
   SideNavSubItem,
   SideNavTone,
   Skeleton,
@@ -6209,6 +7105,7 @@ export {
   Slot,
   type SlotProps,
   SortDirection,
+  SortKey,
   SortState,
   Spacer,
   SpacerProps,
@@ -6243,6 +7140,7 @@ export {
   SwitcherEntry,
   SwitcherLink,
   SwitcherProps,
+  TableQuery,
   Tabs,
   TabsContent,
   TabsContentProps,
@@ -6346,4 +7244,589 @@ export {
   useToast,
   useTocFromRegion,
   useTypeahead,
-};
+};
+// ════ Re-exported from `@cascivo/core` ═══════════════════════════════════════════
+//
+// The declarations below live in `@cascivo/core`, a TRANSITIVE dependency on this path —
+// do not add it to your package.json. Their docblocks are reproduced here so this file
+// stays the one place to read, and to grep, for every name it exports.
+//
+// ── applyTheme ──────────────────────────────────────────────────────────────────
+// /**
+//  * Write a theme onto an element directly, with no provider and no React.
+//  *
+//  * The escape hatch for imperative setups: a theme toggle in a non-React shell, a
+//  * pre-hydration inline script, a Storybook decorator, an e2e test. Also updates the theme
+//  * signal, so a React tree reading {@link useTheme} stays in sync.
+//  *
+//  * `setTheme` deliberately does **not** do this itself: it is SSR-callable, and
+//  * `ThemeProvider` can scope a theme to any subtree via its `target` ref. A direct document
+//  * write inside `setTheme` would break scoped theming and touch `document` on the server.
+//  *
+//  * ```ts
+//  * applyTheme('midnight')                       // <html data-theme="midnight">
+//  * applyTheme('warm', panelRef.current)         // scope to a subtree
+//  * ```
+//  *
+//  * No-op on the server (no `document`).
+//  */
+// declare function applyTheme(next: string, target?: HTMLElement | null): void;
+//
+// ── cn ──────────────────────────────────────────────────────────────────────────
+// declare function cn(...classes: (string | undefined | null | false | 0)[]): string;
+//
+// ── composeRefs ─────────────────────────────────────────────────────────────────
+// declare function composeRefs<T>(...refs: (Ref<T> | undefined)[]): RefCallback<T>;
+//
+// ── computePosition ─────────────────────────────────────────────────────────────
+// declare function computePosition(anchor: {
+//
+// ── createMachine ───────────────────────────────────────────────────────────────
+// declare function createMachine<S extends string, I extends S = S>(config: MachineConfig<S, I>): Machine<S>;
+//
+// ── createScope ─────────────────────────────────────────────────────────────────
+// /**
+//  * A disposable owner for a set of signals/computeds/effects. Use one scope per
+//  * tenant boundary — a workspace, an org, a repository group. When the user
+//  * switches scope, call `dispose()` and create a fresh scope: every effect the
+//  * old scope started stops firing at once, with no orphaned subscriptions or
+//  * stale state left running against unmounted UI.
+//  *
+//  * This is a thin ownership wrapper over `@cascivo/core` signals — not a store,
+//  * not a context, not a DI container. Prefer it over accumulating per-workspace
+//  * state in a single global signal root, which leaks effects across switches.
+//  */
+// declare function createScope(): SignalScope;
+//
+// ── createStreamBuffer ──────────────────────────────────────────────────────────
+// /**
+//  * A fixed-capacity ring buffer with O(1) append and once-per-frame flushing —
+//  * the primitive for high-frequency streams (build logs, live metrics).
+//  *
+//  * Memory is O(capacity), not O(total appended): the backing array is allocated
+//  * once and overwritten in place. A burst of N appends within one animation
+//  * frame produces a single `signal` write (one render), so ingestion rate is
+//  * decoupled from render rate.
+//  *
+//  * This replaces the O(n)-per-line anti-pattern
+//  * `logsSignal.value = [...logsSignal.value.slice(1), line]`, which reallocates
+//  * and re-copies the whole array on every append and renders once per line.
+//  */
+// declare function createStreamBuffer<T>(options: StreamBufferOptions): StreamBuffer<T>;
+//
+// ── DismissableLayer ────────────────────────────────────────────────────────────
+// /**
+//  * Wraps its children and dismisses on an outside pointer press or Escape. One tested implementation
+//  * of the dismissal logic every overlay reinvents. Nested layers form a stack — only the top-most
+//  * responds to Escape and outside pointers. All listeners run inside `useSignalEffect`.
+//  */
+// declare function DismissableLayer( {
+//
+// ── DismissableLayerProps ───────────────────────────────────────────────────────
+// interface DismissableLayerProps {
+//   children: ReactNode;
+//   /** Called when an outside pointer lands or Escape is pressed (when this is the top-most layer). */
+//   onDismiss?: () => void;
+//   /** Disable the outside-pointer dismissal (Escape still works unless escapeDismisses is false). */
+//   disableOutsidePointer?: boolean;
+//   /** Whether Escape dismisses the top-most layer. Default true. */
+//   escapeDismisses?: boolean;
+// }
+//
+// ── ErrorBoundary ───────────────────────────────────────────────────────────────
+// declare class ErrorBoundary extends Component<ErrorBoundaryProps, State> {
+//
+// ── FocusScope ──────────────────────────────────────────────────────────────────
+// declare function FocusScope( {
+//
+// ── getLinkComponent ────────────────────────────────────────────────────────────
+// declare function getLinkComponent(): LinkComponent;
+//
+// ── LinkComponent ───────────────────────────────────────────────────────────────
+// /**
+//  * A component (or intrinsic tag) that renders a navigation link. It receives a
+//  * {@link LinkComponentProps} bag (an `href` plus anchor passthrough) and must
+//  * render an actual `<a>` (or equivalent) so the browser and the router see a real
+//  * link. `'a'` is the default.
+//  */
+// type LinkComponent = ElementType;
+//
+// ── LinkComponentProps ──────────────────────────────────────────────────────────
+// /**
+//  * The prop bag cascivo's config-driven nav components spread onto the link they
+//  * render — the exact contract a custom {@link LinkComponent} receives. Map `href`
+//  * to your router's destination prop (TanStack Router uses `to`) and spread the
+//  * rest so active-state and accessibility attributes carry over. Because navigation
+//  * stays a real `<a>`, middle-click / open-in-new-tab keep working — you do not need
+//  * to intercept `onClick`.
+//  */
+// interface LinkComponentProps {
+//   /** Destination URL. Undefined for a disabled item. Map to your router's prop. */
+//   href?: string | undefined;
+//   /** Class names cascivo computes (layout + active-state styling). */
+//   className?: string | undefined;
+//   /** Rendered link content — cascivo's computed icon + label + trailing nodes. */
+//   children?: ReactNode;
+//   /**
+//    * Click handler cascivo attaches. It only calls `preventDefault()` for a disabled
+//    * item; otherwise it is inert. Spread it onto your router `<Link>` — routers
+//    * compose their own click handling with a passed-through `onClick`.
+//    */
+//   onClick?: (e: MouseEvent<HTMLAnchorElement>) => void;
+//   /** `'page'` on the active item (assistive tech + active styling). */
+//   'aria-current'?: 'page' | undefined;
+//   'aria-label'?: string | undefined;
+//   'aria-disabled'?: boolean | undefined;
+//   /** `'active'` on the current item — a style hook mirroring `aria-current`. */
+//   'data-state'?: 'active' | undefined;
+//   tabIndex?: number | undefined;
+//   /**
+//    * Additional computed `data-*` attributes cascivo may attach (e.g. `data-tone`).
+//    * Spread the whole bag so future attributes carry over without an adapter change.
+//    */
+//   [dataAttr: `data-${string}`]: string | undefined;
+// }
+//
+// ── Machine ─────────────────────────────────────────────────────────────────────
+// interface Machine<S extends string = string> {
+//   initial: S;
+//   states: Record<S, StateConfig>;
+// }
+//
+// ── MachineConfig ───────────────────────────────────────────────────────────────
+// interface MachineConfig<S extends string = string, I extends S = S> {
+//   initial: I;
+//   states: Record<S, StateConfig>;
+// }
+//
+// ── mergeProps ──────────────────────────────────────────────────────────────────
+// declare function mergeProps<T extends Record<string, unknown>>(...propsList: Partial<T>[]): T;
+//
+// ── Portal ──────────────────────────────────────────────────────────────────────
+// declare function Portal( {
+//
+// ── Presence ────────────────────────────────────────────────────────────────────
+// /**
+//  * The return type is declared rather than inferred. Inferred, it widened to
+//  * `ReactElement<…, string | JSXElementConstructor<any>>`, which leaked React's internal
+//  * `any` into cascivo's published `.d.ts` — the only such leak the surface had that was
+//  * cascivo's own to fix.
+//  */
+// declare function Presence( {
+//
+// ── ProgressInput ───────────────────────────────────────────────────────────────
+// type ProgressInput = Progress | ProgressAlias;
+//
+// ── RovingOrientation ───────────────────────────────────────────────────────────
+// type RovingOrientation = 'horizontal' | 'vertical' | 'both';
+//
+// ── setLinkComponent ────────────────────────────────────────────────────────────
+// /**
+//  * Register the component cascivo's config-driven nav components (SideNav,
+//  * ShellHeader, Header, Breadcrumb, Switcher, Dock) use to render links. Call once
+//  * at app startup. The component receives the full {@link LinkComponentProps} bag —
+//  * spread it so active-state and a11y attributes carry over, and so middle-click /
+//  * open-in-new-tab keep working (no `onClick` interception needed). Framework recipes:
+//  *
+//  * ```tsx
+//  * // TanStack Router — its Link takes `to`, so map href → to and spread the rest:
+//  * import { Link } from '@tanstack/react-router'
+//  * import type { LinkComponentProps } from '@cascivo/react' // or '@cascivo/core' for copied source
+//  * setLinkComponent(({ href, ...rest }: LinkComponentProps) => <Link to={href} {...rest} />)
+//  *
+//  * // React Router — its Link takes `to`, and `to` is REQUIRED, so supply a fallback
+//  * // for the disabled-item case where cascivo passes `href: undefined`:
+//  * import { Link } from 'react-router'
+//  * import type { LinkComponentProps } from '@cascivo/react' // or '@cascivo/core' for copied source
+//  * setLinkComponent(({ href, ...rest }: LinkComponentProps) => <Link to={href ?? '#'} {...rest} />)
+//  *
+//  * // Next.js — its Link takes `href` directly:
+//  * import Link from 'next/link'
+//  * setLinkComponent(Link)
+//  * ```
+//  *
+//  * Full guide: https://cascivo.com/docs/using-with-a-router.md — offline:
+//  * `npx -y @cascivo/docs guide using-with-a-router`.
+//  */
+// declare function setLinkComponent(component: (props: LinkComponentProps) => ReactElement | null): void;
+//
+// ── setTheme ────────────────────────────────────────────────────────────────────
+// /**
+//  * Set the active theme imperatively, from anywhere. Persists the choice and
+//  * drives the `data-theme` attribute through the mounted {@link ThemeProvider}.
+//  *
+//  * Requires a mounted {@link ThemeProvider} — this writes the signal, the provider writes
+//  * the DOM. Without one, nothing restyles (dev builds warn). To write the attribute
+//  * directly, with no provider and no React, use {@link applyTheme}.
+//  */
+// declare function setTheme(next: string): void;
+//
+// ── Signal ──────────────────────────────────────────────────────────────────────
+// /**
+//  * The base class for plain and computed signals.
+//  */
+// declare class Signal<T = any> {
+//
+// ── Slot ────────────────────────────────────────────────────────────────────────
+// /**
+//  * Slot renders its single child element while merging the Slot's own props and ref onto it —
+//  * the Radix-style `asChild` composition primitive, built on cascivo's existing
+//  * `mergeProps`/`composeRefs`/`cn`.
+//  *
+//  * - Non-handler props: child wins (so the consumer's element controls its own identity).
+//  * - `on*` handlers: chained (Slot's runs, then the child's) via `mergeProps`.
+//  * - `className`: unioned via `cn`. `style`: shallow-merged (child wins on conflicts).
+//  * - `ref`: composed so both the Slot consumer's ref and the child's own ref receive the node.
+//  *
+//  * Fails fast if `children` is not exactly one valid React element.
+//  */
+// declare const Slot: import("react").ForwardRefExoticComponent<Omit<SlotProps, "ref"> & import("react").RefAttributes<unknown>>;
+//
+// ── SlotProps ───────────────────────────────────────────────────────────────────
+// interface SlotProps {
+//   children?: ReactNode;
+//   className?: string;
+//   style?: CSSProperties;
+//   [key: string]: unknown;
+// }
+//
+// ── SpaceStep ───────────────────────────────────────────────────────────────────
+// /**
+//  * A step on cascivo's spacing scale, mapping to the `--cascivo-space-*` design
+//  * tokens. Used by the `gap` (and related) props of the layout primitives.
+//  *
+//  * The scale is deliberately non-linear and **skips 7** — it mirrors the token
+//  * scale (`--cascivo-space-1 … -6, -8, -10, -12`), which has no `space-7`. So
+//  * `gap={7}` is a type error by design; use `6` or `8`.
+//  *
+//  * Note the props take a **number**, not a string: write `gap={4}`, not `gap="4"`
+//  * (a string is not assignable to `SpaceStep`).
+//  *
+//  * Lives in `@cascivo/core` (a dependency every layout primitive already has) as a
+//  * single shared declaration, so the published `@cascivo/react` types name it
+//  * `SpaceStep` everywhere — never the dts bundler's deduped `SpaceStep$N` aliases —
+//  * and each copied layout component resolves it from its `@cascivo/core` dep.
+//  */
+// type SpaceStep = 1 | 2 | 3 | 4 | 5 | 6 | 8 | 10 | 12;
+//
+// ── SuspenseBoundary ────────────────────────────────────────────────────────────
+// declare function SuspenseBoundary( {
+//
+// ── themePreloadScript ──────────────────────────────────────────────────────────
+// /**
+//  * A tiny script to inline in your document `<head>` (before the app bundle) so
+//  * the persisted theme paints on the first byte — no flash of the wrong theme on
+//  * SSR or a hard reload. Pass the same `storageKey`/`attribute`/`defaultTheme`
+//  * you give {@link ThemeProvider}.
+//  *
+//  * Precedence matches {@link ThemeProvider}: persisted value > `defaultTheme`
+//  * (if set) > OS `prefers-color-scheme` > `'light'`. Passing `defaultTheme`
+//  * suppresses the OS check, so a "dark by default" app stays dark on a light-OS
+//  * visitor.
+//  *
+//  * The script sets `data-theme` **before** React hydrates, so add
+//  * `suppressHydrationWarning` to the element that carries the attribute (usually
+//  * `<html>`) — the mutation is intentional, and without the flag React 19 logs a
+//  * hydration mismatch.
+//  *
+//  * ```tsx
+//  * // Next.js app/layout.tsx
+//  * <html suppressHydrationWarning>
+//  *   <head>
+//  *     <script dangerouslySetInnerHTML={{ __html: themePreloadScript({ defaultTheme: 'dark' }) }} />
+//  *   </head>
+//  * </html>
+//  * ```
+//  */
+// declare function themePreloadScript(options?: {
+//
+// ── ThemeProvider ───────────────────────────────────────────────────────────────
+// /**
+//  * Binds the active theme signal to a `data-theme` attribute and persists the
+//  * choice — the reusable, SSR-safe form of the wiring apps otherwise hand-roll.
+//  *
+//  * - No flash of the wrong theme: pair with {@link themePreloadScript} in your
+//  *   document `<head>` so the correct theme paints on first byte.
+//  * - No banned React hooks: the DOM write happens in `useSignalEffect`, not
+//  *   `useEffect`; there is no `useState`/`useContext`.
+//  * - Uncontrolled by default (persists to localStorage); pass `value` to control.
+//  * - SSR-safe when controlled: with a `value` (and no scoped `target`), the
+//  *   provider renders a tiny inline script that sets `data-theme` during HTML
+//  *   parsing, so the server-rendered first paint is themed — no flash, no
+//  *   hydration mismatch (the same markup renders on both sides; the client effect
+//  *   owns every update after hydration). For the uncontrolled/persisted flow, pair
+//  *   with {@link themePreloadScript} in `<head>` instead.
+//  */
+// declare function ThemeProvider( {
+//
+// ── ThemeProviderProps ──────────────────────────────────────────────────────────
+// interface ThemeProviderProps {
+//   /**
+//    * Theme to use when nothing is persisted yet. When set, it **wins over** the
+//    * visitor's OS `prefers-color-scheme` — pass it for a "dark by default" or
+//    * custom-theme (`'midnight'`, …) app. Omit it to follow the OS (light/dark),
+//    * falling back to `'light'`. Precedence: persisted value > `defaultTheme` (if
+//    * set) > OS preference > `'light'`.
+//    */
+//   defaultTheme?: string;
+//   /**
+//    * Controlled theme. When set, the provider mirrors it on every render and the
+//    * persisted value is ignored — the parent owns the state (React semantics).
+//    */
+//   value?: string;
+//   /** localStorage key for the persisted choice. Defaults to `cascivo-theme`. */
+//   storageKey?: string;
+//   /** Attribute written to the target element. Defaults to `data-theme`. */
+//   attribute?: string;
+//   /**
+//    * Element to theme. Omit to theme the whole document (`<html>`). Pass a ref to
+//    * a container to scope the theme to a subtree — cascivo themes resolve against
+//    * the nearest `data-theme`, so a scoped subtree can differ from the page.
+//    */
+//   target?: RefObject<HTMLElement | null>;
+//   /** Called whenever the active theme changes. */
+//   onChange?: (theme: string) => void;
+//   /**
+//    * CSP nonce forwarded to the inline attribute-setter script emitted for the
+//    * controlled ({@link ThemeProviderProps.value}) SSR flow. Set it to match your
+//    * Content-Security-Policy `script-src 'nonce-…'`.
+//    */
+//   nonce?: string;
+//   children?: ReactNode;
+// }
+//
+// ── themeSignal ─────────────────────────────────────────────────────────────────
+// /**
+//  * The underlying theme signal, for signal-native code — `computed()`, `effect()`,
+//  * or a Preact app where signals are natively reactive. Most React apps want
+//  * {@link useTheme}, which hands back a plain string and handles subscription.
+//  */
+// declare function themeSignal(): Signal<string>;
+//
+// ── ToneInput ───────────────────────────────────────────────────────────────────
+// type ToneInput = Tone | ToneAlias;
+//
+// ── useAnchorPosition ───────────────────────────────────────────────────────────
+// /**
+//  * Positions a floating element relative to an anchor. Primary path: CSS anchor positioning
+//  * (Chrome-leading) — emits `anchor-name`/`position-anchor` + `anchor()` insets. Fallback (behind
+//  * `CSS.supports`): JS `getBoundingClientRect` placement recomputed on scroll/resize inside
+//  * `useSignalEffect`. Small by design — not a collision/flip engine (deferred).
+//  */
+// declare function useAnchorPosition(options: UseAnchorPositionOptions): UseAnchorPositionReturn;
+//
+// ── useClipboard ────────────────────────────────────────────────────────────────
+// /**
+//  * Copy-to-clipboard helper that de-dupes the inline logic in `copy-button`.
+//  * `copy(text)` writes via `navigator.clipboard.writeText`; `copied` flips true then resets after
+//  * `timeout`. The reset timer is cleared on unmount via `useSignalEffect` (no `useEffect`).
+//  */
+// declare function useClipboard(options?: UseClipboardOptions): UseClipboardReturn;
+//
+// ── UseClipboardOptions ─────────────────────────────────────────────────────────
+// interface UseClipboardOptions {
+//   /** How long `copied` stays true after a successful copy, in ms. */
+//   timeout?: number;
+// }
+//
+// ── UseClipboardReturn ──────────────────────────────────────────────────────────
+// interface UseClipboardReturn {
+//   copied: ReadonlySignal<boolean>;
+//   copy: (text: string) => Promise<void>;
+// }
+//
+// ── useComputed ─────────────────────────────────────────────────────────────────
+// /**
+//  * Derived reactive state (use instead of a `useMemo`/`useState` pair). Recomputes only when a
+//  * signal it reads changes.
+//  *
+//  * Calls `useSignals()` internally — same contract and same tracking-window caveat as
+//  * {@link useSignal}.
+//  */
+// declare function useComputed<T>(compute: () => T): ReadonlySignal<T>;
+//
+// ── useControllableSignal ───────────────────────────────────────────────────────
+// /**
+//  * Codifies the controlled/uncontrolled pattern documented by hand in CLAUDE.md
+//  * (`const x = useSignal(open); x.value = open`).
+//  *
+//  * Returns a `[signal, setValue]` pair:
+//  * - **Controlled** (`value` provided): the signal mirrors `value` on every render; `setValue`
+//  *   does not mutate the signal locally — it only routes the request through `onChange` so the
+//  *   parent owns the state (React semantics).
+//  * - **Uncontrolled** (`value` undefined): the signal owns the state seeded from `defaultValue`;
+//  *   `setValue` updates it locally and also calls `onChange`.
+//  *
+//  * Whether a component is controlled is fixed for its life, exactly like React.
+//  */
+// declare function useControllableSignal<T>(options: UseControllableSignalOptions<T>): [Signal<T>, (next: T) => void];
+//
+// ── UseControllableSignalOptions ────────────────────────────────────────────────
+// interface UseControllableSignalOptions<T> {
+//   /** Controlled value. When provided, the component is controlled for its whole life. */
+//   value?: T | undefined;
+//   /** Initial value for uncontrolled use. */
+//   defaultValue?: T | undefined;
+//   /** Called on every write, in both controlled and uncontrolled modes. */
+//   onChange?: ((value: T) => void) | undefined;
+// }
+//
+// ── useDisclosure ───────────────────────────────────────────────────────────────
+// /**
+//  * Open/close state for overlays (modal, drawer, popover, …), replacing the
+//  * per-component `useSignal(open)` boilerplate. Backed by `useControllableSignal`
+//  * so it is controlled when `isOpen` is passed and uncontrolled otherwise.
+//  * Replaces HeroUI's `@heroui/use-disclosure`. No `useState`/`useEffect`.
+//  */
+// declare function useDisclosure(options?: UseDisclosureOptions): UseDisclosureReturn;
+//
+// ── UseDisclosureOptions ────────────────────────────────────────────────────────
+// interface UseDisclosureOptions {
+//   /** Initial open state for uncontrolled use. */
+//   defaultOpen?: boolean;
+//   /** Controlled open state. When provided, the parent owns the state. */
+//   isOpen?: boolean;
+//   /** Called whenever open/close/toggle is requested. */
+//   onOpenChange?: (open: boolean) => void;
+// }
+//
+// ── UseDisclosureReturn ─────────────────────────────────────────────────────────
+// interface UseDisclosureReturn {
+//   isOpen: ReadonlySignal<boolean>;
+//   open: () => void;
+//   close: () => void;
+//   toggle: () => void;
+// }
+//
+// ── useEffectPropSignal ─────────────────────────────────────────────────────────
+// /**
+//  * Mirror a controlled React prop into a signal that is read **inside effects**, not in
+//  * render. The write is deferred to a microtask, so a prop change never runs a subscribed
+//  * `useSignalEffect` body during React's render phase.
+//  *
+//  * ## Which mirror do I want?
+//  *
+//  * | The signal is read… | Use | Why |
+//  * | --- | --- | --- |
+//  * | in render (JSX, a `data-*` attribute, a derived value) | `useControllableSignal` — or the plain `const s = useSignal(prop); s.value = prop` idiom | The write must be synchronous or the component renders one tick stale. A render-phase write that only notifies the *writing* component's own subscription is a legal same-fiber render-phase update. |
+//  * | only inside `useSignalEffect` | **this** | Preact signals run effects **synchronously on write**, so a render-phase write executes effect bodies mid-render — imperative DOM calls (`showModal()`), listener registration against a pre-commit ref, and parent `setState` callbacks, all inside React's render phase. React warns `Cannot update a component while rendering a different component`; the behavior is wrong even when it doesn't. |
+//  *
+//  * That distinction is the rule; it is documented in `CLAUDE.md` ("Syncing a controlled React
+//  * prop into a signal"), `docs/HEADLESS.md`, and `docs/AI-RULES.md`.
+//  *
+//  * ## Constraints
+//  *
+//  * - **Do not read the returned signal in render.** It lags the prop by one microtask by
+//  *   design. Read the prop itself, or use `useControllableSignal`.
+//  * - **Pass a primitive.** A value with a new identity every render (an inline object or
+//  *   array literal) never compares equal, so the effect would re-run every render. Mirror
+//  *   its identity-stable parts instead.
+//  * - SSR-safe: on the server the first render's value already matches, so nothing is ever
+//  *   scheduled and no work can leak between requests.
+//  */
+// declare function useEffectPropSignal<T>(value: T): ReadonlySignal<T>;
+//
+// ── useId ───────────────────────────────────────────────────────────────────────
+// /**
+//  * SSR-safe stable id for aria wiring (Label/Field). Wraps React's `useId` and strips the
+//  * non-selector-safe colons React emits, prefixing for readability (default `cascivo`).
+//  */
+// declare function useId(prefix?: string): string;
+//
+// ── useMachine ──────────────────────────────────────────────────────────────────
+// declare function useMachine<S extends string>(machine: Machine<S>): readonly [Signal<S>, (event: string) => void];
+//
+// ── useMediaQuery ───────────────────────────────────────────────────────────────
+// /**
+//  * `useMediaQuery(query)` → a `ReadonlySignal<boolean>` that tracks whether the media query matches.
+//  * SSR-safe (defaults to `false` when `window`/`matchMedia` is unavailable). Subscribes to changes
+//  * inside `useSignalEffect`; the listener is cleaned up on teardown.
+//  */
+// declare function useMediaQuery(query: string): ReadonlySignal<boolean>;
+//
+// ── useRovingFocus ──────────────────────────────────────────────────────────────
+// /**
+//  * Roving tabindex without context. The parent calls `useRovingFocus(...)` and spreads
+//  * `getItemProps(i)` onto each item. Only the active item is tabbable (`tabIndex={0}`); arrow keys
+//  * move focus (Home/End jump; `loop` wraps). State lives in a signal; this hook calls `useSignals()`
+//  * for you, so a plain React consumer that reads the active index in render stays reactive.
+//  */
+// declare function useRovingFocus(options?: UseRovingFocusOptions): UseRovingFocusReturn;
+//
+// ── useScope ────────────────────────────────────────────────────────────────────
+// /**
+//  * Bind a {@link createScope} to a component's lifetime: created once on mount,
+//  * disposed on unmount. The scope's effects stop when the component unmounts.
+//  */
+// declare function useScope(): SignalScope;
+//
+// ── useScrollLock ───────────────────────────────────────────────────────────────
+// /**
+//  * Locks `document.body` scroll while `locked` is true, compensating for the scrollbar width to
+//  * avoid a layout shift. Accepts a plain boolean or a `Signal<boolean>` (reactive). The previous
+//  * inline styles are restored on unlock/teardown. DOM work runs inside `useSignalEffect`.
+//  */
+// declare function useScrollLock(locked: Signal<boolean> | boolean): void;
+//
+// ── useSignal ───────────────────────────────────────────────────────────────────
+// /**
+//  * Local reactive state — the signal IS the state (use instead of `useState`).
+//  *
+//  * Calls `useSignals()` internally, so a component that reads the returned signal during
+//  * render re-renders on writes **without** the Babel signals transform and without calling
+//  * `useSignals()` itself.
+//  *
+//  * Caveat: the tracking window opens where this hook is called. A signal read that happens
+//  * *earlier* in the render body than the first `useSignal`/`useComputed` call is not tracked —
+//  * so call these before any signal read, or call `useSignals()` first. (Reading a signal before
+//  * any hook runs is unusual; the case is locked by a test.)
+//  */
+// declare function useSignal<T>(initial: T): Signal<T>;
+//
+// ── useStreamBuffer ─────────────────────────────────────────────────────────────
+// /**
+//  * Component-scoped {@link createStreamBuffer}. Created once and stable across
+//  * renders; cancels any pending flush on unmount. Read `buffer.signal.value` in
+//  * render to subscribe the component to the stream.
+//  */
+// declare function useStreamBuffer<T>(options: StreamBufferOptions): StreamBuffer<T>;
+//
+// ── useTheme ────────────────────────────────────────────────────────────────────
+// /**
+//  * Read and set the active theme. Returns the current theme **name** (a plain
+//  * string) and a setter — the component re-renders when the theme changes with no
+//  * signal handling on your part (this hook calls `useSignals()` for you, so it
+//  * works in React apps with no Babel transform). This is the React-idiomatic shape;
+//  * for signal-native code (`computed()`, `effect()`, Preact) use {@link themeSignal}.
+//  *
+//  * ```tsx
+//  * const [theme, setTheme] = useTheme()
+//  * return <button onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}>
+//  *   {theme}
+//  * </button>
+//  * ```
+//  */
+// declare function useTheme(): readonly [string, (next: string) => void];
+//
+// ── useTypeahead ────────────────────────────────────────────────────────────────
+// /**
+//  * Type-to-select buffer, without context. The consumer calls `useTypeahead({ onMatch })`
+//  * and spreads `onKeyDown` onto the focusable list container; each printable key extends
+//  * the query and fires `onMatch(query)`. The buffer resets after `resetMs` of inactivity.
+//  *
+//  * Space is treated as a query character only while a query is already in progress, so a
+//  * leading Space stays available for activation (WAI-ARIA menu/listbox convention). Repeated
+//  * identical characters are passed through verbatim (e.g. "aa"); consumers that want the
+//  * "press 'a' repeatedly to cycle A-items" behavior can detect an all-same-char query.
+//  */
+// declare function useTypeahead(options: UseTypeaheadOptions): UseTypeaheadReturn;
+//
+// ── VisuallyHidden ──────────────────────────────────────────────────────────────
+// declare function VisuallyHidden( {
+//
+// ── VisuallyHiddenProps ─────────────────────────────────────────────────────────
+// interface VisuallyHiddenProps extends HTMLAttributes<HTMLSpanElement> {
+//   children: ReactNode;
+//   showOnFocus?: boolean;
+// }
+//