@cascivo/react 0.11.1 → 0.13.0

package/dist/index.d.ts

@@ -21,12 +21,24 @@
  * Docs: https://cascivo.com/llms.txt — or fully offline, no website needed:
  *   npx -y @cascivo/docs            (index; `npx @cascivo/docs <component>` for one doc)
  */
-import { ErrorBoundary, FocusScope, LinkComponent, LinkComponentProps, Portal, RovingOrientation, Signal, SpaceStep, SuspenseBoundary, getLinkComponent, setLinkComponent } from "@cascivo/core";
+import { DismissableLayer, DismissableLayerProps, ErrorBoundary, FocusScope, LinkComponent, LinkComponentProps, Machine, MachineConfig, Portal, Presence, ProgressInput, RovingOrientation, Signal, Slot, SlotProps, SpaceStep, SuspenseBoundary, ToneInput, UseClipboardOptions, UseClipboardReturn, UseControllableSignalOptions, UseDisclosureOptions, UseDisclosureReturn, VisuallyHidden, VisuallyHiddenProps, batch, cn, composeRefs, computePosition, computed, createMachine, createScope, createStreamBuffer, effect, getLinkComponent, mergeProps, setLinkComponent, signal, useAnchorPosition, useClipboard, useComputed, useControllableSignal, useDisclosure, useEffectPropSignal, useId, useMachine, useMediaQuery, useRovingFocus, useScope, useScrollLock, useSignal, useSignalEffect, useSignals, useStreamBuffer, useTypeahead } from "@cascivo/core";
 import { AnchorHTMLAttributes, ButtonHTMLAttributes, FormHTMLAttributes, HTMLAttributes, ImgHTMLAttributes, InputHTMLAttributes, LabelHTMLAttributes, LiHTMLAttributes, MouseEvent, ReactElement, ReactNode, RefObject, SelectHTMLAttributes, TextareaHTMLAttributes, TimeHTMLAttributes } from "react";
 
 interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  /**
+   * Selects the visual style variant.
+   *
+   * @defaultValue `primary`
+   * @see the component manifest
+   */
   variant?: 'primary' | 'secondary' | 'ghost' | 'destructive';
   size?: 'sm' | 'md' | 'lg';
+  /**
+   * When true, shows a loading state.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   loading?: boolean;
   /**
    * Render the single child element instead of a native `<button>` so the button
@@ -63,7 +75,19 @@ declare function Input({
   ...props
 }: InputProps): import("react").JSX.Element;
 interface CardProps extends HTMLAttributes<HTMLDivElement> {
+  /**
+   * Selects the visual style variant.
+   *
+   * @defaultValue `default`
+   * @see the component manifest
+   */
   variant?: 'default' | 'outlined' | 'elevated';
+  /**
+   * Inner padding of the component.
+   *
+   * @defaultValue `md`
+   * @see the component manifest
+   */
   padding?: 'none' | 'sm' | 'md' | 'lg';
 }
 declare function Card({
@@ -73,8 +97,20 @@ declare function Card({
   children,
   ...props
 }: CardProps): import("react").JSX.Element;
-interface CardHeaderProps extends HTMLAttributes<HTMLDivElement> {}
+interface CardHeaderProps extends HTMLAttributes<HTMLDivElement> {
+  /**
+   * Trailing content pinned to the inline-end of the header — an overflow menu, a status
+   * badge, a link. Without it the header is a column (title over description), which is
+   * why `justify-content: space-between` alone does nothing: the most common dashboard
+   * card layout is title-left / action-right, and it needs a row.
+   *
+   * The title column keeps `min-inline-size: 0`, so a long title truncates instead of
+   * pushing the actions out of the card.
+   */
+  actions?: ReactNode;
+}
 declare function CardHeader({
+  actions,
   className,
   children,
   ...props
@@ -97,8 +133,16 @@ declare function CardFooter({
   children,
   ...props
 }: CardFooterProps): import("react").JSX.Element;
+/** Badge-only looks that aren't a severity tone. */
+type BadgeShape = 'secondary' | 'outline' | 'primary';
 interface BadgeProps extends HTMLAttributes<HTMLSpanElement> {
-  variant?: 'default' | 'secondary' | 'success' | 'warning' | 'destructive' | 'outline';
+  /**
+   * Severity tone or badge-specific look. Accepts the catalog-wide `Tone` vocabulary
+   * (`neutral | info | success | warning | danger`) as well as Badge's historical spellings
+   * (`default`, `destructive`, `error`) — they are aliases of the same tones, so one domain
+   * enum can drive `Badge`, `Tag`, `Status` and `Notification` with no lookup table.
+   */
+  variant?: ToneInput | BadgeShape;
   size?: 'sm' | 'md';
 }
 declare function Badge({
@@ -109,6 +153,12 @@ declare function Badge({
   ...props
 }: BadgeProps): import("react").JSX.Element;
 interface ModalProps {
+  /**
+   * Whether the component is open (controlled).
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   open?: boolean;
   onClose?: () => void;
   title?: string;
@@ -116,7 +166,12 @@ interface ModalProps {
   children?: ReactNode;
   className?: string;
   size?: 'sm' | 'md' | 'lg';
-  /** Allow dragging the dialog by its header (opt-in; CSS translate, no animation library). */
+  /**
+   * Allow dragging the dialog by its header
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   draggable?: boolean;
 }
 declare function Modal({
@@ -131,6 +186,12 @@ declare function Modal({
 }: ModalProps): import("react").JSX.Element;
 interface SpinnerProps extends HTMLAttributes<HTMLSpanElement> {
   size?: 'sm' | 'md' | 'lg';
+  /**
+   * Accessible label announced by screen readers
+   *
+   * @defaultValue `Loading`
+   * @see the component manifest
+   */
   label?: string;
 }
 declare function Spinner({
@@ -140,7 +201,19 @@ declare function Spinner({
   ...props
 }: SpinnerProps): import("react").JSX.Element;
 interface SeparatorProps extends HTMLAttributes<HTMLElement> {
+  /**
+   * Layout orientation of the component.
+   *
+   * @defaultValue `horizontal`
+   * @see the component manifest
+   */
   orientation?: 'horizontal' | 'vertical';
+  /**
+   * When true, the separator is purely visual and hidden from assistive tech
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   decorative?: boolean;
 }
 declare function Separator({
@@ -150,9 +223,21 @@ declare function Separator({
   ...props
 }: SeparatorProps): import("react").JSX.Element;
 interface AlertProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'> {
+  /**
+   * Selects the visual style variant.
+   *
+   * @defaultValue `default`
+   * @see the component manifest
+   */
   variant?: 'default' | 'info' | 'success' | 'warning' | 'destructive';
   title?: string;
   icon?: ReactNode;
+  /**
+   * When true, shows a control to dismiss the component.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   dismissible?: boolean;
   onDismiss?: () => void;
   action?: {
@@ -173,6 +258,12 @@ declare function Alert({
 }: AlertProps): import("react").JSX.Element | null;
 interface AvatarProps extends HTMLAttributes<HTMLSpanElement> {
   src?: string;
+  /**
+   * Alternative text describing the image.
+   *
+   * @defaultValue ``
+   * @see the component manifest
+   */
   alt?: string;
   /** Full name — used to derive initials for the fallback and as the accessible label. */
   name?: string;
@@ -200,9 +291,19 @@ interface AvatarGroupProps extends HTMLAttributes<HTMLDivElement> {
   max?: number;
   /** Override the total count used for the +N chip (when more exist than rendered). */
   total?: number;
-  /** Overlap amount. */
+  /**
+   * Spacing between items.
+   *
+   * @defaultValue `md`
+   * @see the component manifest
+   */
   spacing?: 'sm' | 'md' | 'lg';
-  /** Wrap into a grid instead of an overlapping row. */
+  /**
+   * When true, lays the avatars out in a grid instead of an overlapping stack.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   isGrid?: boolean;
   labels?: AvatarGroupLabels;
   /** The <Avatar> children. */
@@ -240,17 +341,38 @@ declare function User({
 }: UserProps): import("react").JSX.Element;
 interface ImageProps extends Omit<ImgHTMLAttributes<HTMLImageElement>, 'placeholder'> {
   src?: string;
+  /**
+   * Alternative text describing the image.
+   *
+   * @defaultValue ``
+   * @see the component manifest
+   */
   alt?: string;
   /** Image shown if `src` fails to load. Without it, a neutral fallback box renders. */
   fallbackSrc?: string;
   width?: string | number;
   height?: string | number;
   radius?: 'none' | 'sm' | 'md' | 'lg' | 'full';
-  /** Hover-zoom the image (reduced-motion-safe). */
+  /**
+   * When true, zooms the image on hover.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   zoom?: boolean;
-  /** Render a bare <img> with no wrapper, placeholder, or zoom (HeroUI parity). */
+  /**
+   * Render a bare <img> with no wrapper, placeholder, or zoom
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   removeWrapper?: boolean;
-  /** Show a blurred placeholder while loading. */
+  /**
+   * When true, renders a blurred backdrop behind the image.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   isBlurred?: boolean;
 }
 declare function Image({
@@ -288,6 +410,12 @@ declare function Textarea({
 interface SelectOption {
   value: string;
   label: string;
+  /**
+   * When true, disables the control and removes it from the tab order.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   disabled?: boolean;
 }
 interface SelectProps extends Omit<SelectHTMLAttributes<HTMLSelectElement>, 'size'> {
@@ -315,6 +443,12 @@ declare function Select({
 }: SelectProps): import("react").JSX.Element;
 interface CheckboxProps extends InputHTMLAttributes<HTMLInputElement> {
   label?: string;
+  /**
+   * When true, renders the mixed/indeterminate state.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   indeterminate?: boolean;
 }
 declare function Checkbox({
@@ -357,6 +491,12 @@ declare function RadioGroup({
 }: RadioGroupProps): import("react").JSX.Element;
 interface ToggleProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'onChange'> {
   checked?: boolean;
+  /**
+   * Whether the control is checked on first render (uncontrolled).
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   defaultChecked?: boolean;
   /** Called with the new checked state when the switch is toggled. */
   onValueChange?: (checked: boolean) => void;
@@ -397,8 +537,20 @@ declare function Slider({
 }: SliderProps): import("react").JSX.Element;
 interface TooltipProps {
   content: ReactNode;
+  /**
+   * Placement relative to the trigger.
+   *
+   * @defaultValue `top`
+   * @see the component manifest
+   */
   placement?: 'top' | 'right' | 'bottom' | 'left';
   children: ReactElement;
+  /**
+   * Milliseconds to wait before showing
+   *
+   * @defaultValue `200`
+   * @see the component manifest
+   */
   delay?: number;
 }
 declare function Tooltip({
@@ -418,6 +570,12 @@ interface DropdownProps {
   trigger: ReactElement;
   items: DropdownItem[];
   onSelect?: (value: string) => void;
+  /**
+   * Placement relative to the trigger.
+   *
+   * @defaultValue `bottom-start`
+   * @see the component manifest
+   */
   placement?: 'bottom-start' | 'bottom-end';
   open?: boolean;
   onOpenChange?: (open: boolean) => void;
@@ -434,7 +592,19 @@ type ToastVariant = 'default' | 'success' | 'warning' | 'destructive';
 interface ToastOptions {
   title: string;
   description?: string;
+  /**
+   * Selects the visual style variant.
+   *
+   * @defaultValue `default`
+   * @see the component manifest
+   */
   variant?: ToastVariant;
+  /**
+   * How long (ms) the toast stays visible before auto-dismiss.
+   *
+   * @defaultValue `5000`
+   * @see the component manifest
+   */
   duration?: number;
 }
 declare function enqueue(options: ToastOptions): void;
@@ -534,7 +704,12 @@ interface ActionSheetProps {
   title?: ReactNode;
   /** Optional supporting message under the title. */
   description?: ReactNode;
-  /** Show the separate Cancel button. Default true. */
+  /**
+   * When true, shows a cancel button below the actions.
+   *
+   * @defaultValue `true`
+   * @see the component manifest
+   */
   showCancel?: boolean;
   labels?: {
     cancel?: string;
@@ -570,14 +745,37 @@ declare function Kbd({
   ...props
 }: KbdProps): import("react").JSX.Element;
 interface LinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
+  /**
+   * `standalone` (default) owns its own typography and underlines on hover;
+   * `inline` inherits the surrounding prose font and is always underlined.
+   */
   variant?: 'standalone' | 'inline';
   size?: 'sm' | 'md' | 'lg';
+  /**
+   * When true, treats the link as external (opens in a new tab with rel safety).
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   external?: boolean;
+  /**
+   * Render the single child element instead of cascivo's own `<a>`, so the link
+   * styling lands on your router's `Link`. **This is the supported way to style an
+   * in-content router link** — `setLinkComponent` only covers the config-driven nav
+   * components (SideNav, ShellHeader, Breadcrumb, …), not links you write in page
+   * content. See `docs/USING-WITH-A-ROUTER.md`.
+   *
+   * ```tsx
+   * <Link asChild><RouterLink to="/projects/a">Project A</RouterLink></Link>
+   * ```
+   */
+  asChild?: boolean;
 }
 declare function Link({
   variant,
   size,
   external,
+  asChild,
   className,
   children,
   ...props
@@ -590,7 +788,12 @@ interface BreadcrumbProps {
   items: BreadcrumbItem[];
   maxVisible?: number;
   className?: string;
-  /** Accessible label for the nav landmark */
+  /**
+   * Accessible label for the component.
+   *
+   * @defaultValue `Breadcrumb`
+   * @see the component manifest
+   */
   ariaLabel?: string;
 }
 declare function Breadcrumb({
@@ -652,6 +855,12 @@ interface HeaderProps extends HTMLAttributes<HTMLElement> {
   brand?: ReactNode;
   links?: HeaderLink[];
   actions?: ReactNode;
+  /**
+   * When true, the header sticks to the top on scroll.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   sticky?: boolean;
   labels?: HeaderLabels;
 }
@@ -751,12 +960,48 @@ interface SideNavProps {
   items?: SideNavItem[];
   groups?: SideNavGroup[];
   collapsed?: boolean;
+  /**
+   * Whether the rail is collapsed on first render (uncontrolled).
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   defaultCollapsed?: boolean;
   onCollapsedChange?: (collapsed: boolean) => void;
+  /**
+   * Accessible label for the component.
+   *
+   * @defaultValue `Side navigation`
+   * @see the component manifest
+   */
   ariaLabel?: string;
+  /**
+   * Accessible label for the collapse control.
+   *
+   * @defaultValue `Collapse navigation`
+   * @see the component manifest
+   */
   collapseLabel?: string;
+  /**
+   * Accessible label for the expand control.
+   *
+   * @defaultValue `Expand navigation`
+   * @see the component manifest
+   */
   expandLabel?: string;
+  /**
+   * Widens the rail as an overlay on hover/focus-within; suppresses tooltips/flyouts
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   expandOnHover?: boolean;
+  /**
+   * Show the collapse/expand toggle control.
+   *
+   * @defaultValue `true`
+   * @see the component manifest
+   */
   showCollapseToggle?: boolean;
   /** Content rendered above the items, inside the item padding context. */
   header?: ReactNode;
@@ -792,6 +1037,12 @@ interface PaginationProps {
   totalItems: number;
   onPageChange: (page: number) => void;
   onPageSizeChange?: (size: number) => void;
+  /**
+   * Options for the page size select
+   *
+   * @defaultValue `[10, 25, 50, 100]`
+   * @see the component manifest
+   */
   pageSizeOptions?: number[];
   labels?: PaginationLabels;
   className?: string;
@@ -813,6 +1064,12 @@ interface ProgressStep {
 interface ProgressIndicatorProps {
   steps: ProgressStep[];
   currentIndex: number;
+  /**
+   * When true, lays the steps out vertically.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   vertical?: boolean;
   className?: string;
 }
@@ -823,9 +1080,20 @@ declare function ProgressIndicator({
   className
 }: ProgressIndicatorProps): import("react").JSX.Element;
 interface TagProps extends HTMLAttributes<HTMLSpanElement> {
-  variant?: 'default' | 'info' | 'success' | 'warning' | 'error';
+  /**
+   * Severity tone. Accepts the catalog-wide `Tone` vocabulary
+   * (`neutral | info | success | warning | danger`) plus Tag's historical spellings
+   * (`default`, `error`, `destructive`).
+   */
+  variant?: ToneInput;
   size?: 'sm' | 'md';
   onDismiss?: () => void;
+  /**
+   * Accessible label for the dismiss button.
+   *
+   * @defaultValue `Remove`
+   * @see the component manifest
+   */
   dismissLabel?: string;
 }
 declare function Tag({
@@ -838,9 +1106,21 @@ declare function Tag({
   ...props
 }: TagProps): import("react").JSX.Element;
 interface SkeletonProps extends HTMLAttributes<HTMLDivElement> {
+  /**
+   * Selects the visual style variant.
+   *
+   * @defaultValue `text`
+   * @see the component manifest
+   */
   variant?: 'text' | 'circle' | 'rect';
   width?: string;
   height?: string;
+  /**
+   * Number of bars for the text variant; the last bar renders shorter
+   *
+   * @defaultValue `1`
+   * @see the component manifest
+   */
   lines?: number;
 }
 declare function Skeleton({
@@ -855,10 +1135,22 @@ declare function Skeleton({
 interface ProgressBarProps {
   /** Current value from 0 to max. Omit for an indeterminate bar. */
   value?: number;
+  /**
+   * Maximum allowed value.
+   *
+   * @defaultValue `100`
+   * @see the component manifest
+   */
   max?: number;
   label?: string;
   helperText?: string;
   size?: 'sm' | 'md';
+  /**
+   * success/error tint the fill and show a glyph next to the label
+   *
+   * @defaultValue `active`
+   * @see the component manifest
+   */
   status?: 'active' | 'success' | 'error';
   className?: string;
 }
@@ -905,7 +1197,12 @@ interface FabProps {
   onClick?: () => void;
   /** Speed-dial actions revealed above the button when opened. */
   actions?: FabAction[];
-  /** Screen corner to anchor to. */
+  /**
+   * Position of the component.
+   *
+   * @defaultValue `bottom-end`
+   * @see the component manifest
+   */
   position?: 'bottom-end' | 'bottom-start';
   /** Controlled speed-dial open state. */
   open?: boolean;
@@ -935,15 +1232,41 @@ declare function Fab({
 }: FabProps): import("react").JSX.Element;
 interface OverflowMenuItem {
   label: string;
-  value: string;
+  /**
+   * Item identity — what `onSelect` receives. `value` is the catalog convention for the
+   * identity of an item in a collection (see the accessible-name/item-identity table in
+   * `docs/AI-RULES.md`); `id` is accepted as an alias because `CommandMenu`-shaped `id`
+   * is the common wrong guess and cost an adopter a compile round-trip. Pass either.
+   */
+  value?: string;
+  /** Alias of {@link OverflowMenuItem.value}. Exactly one of the two is required. */
+  id?: string;
   icon?: ReactNode;
+  /**
+   * When true, disables the control and removes it from the tab order.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   disabled?: boolean;
   destructive?: boolean;
 }
 interface OverflowMenuProps {
   items: OverflowMenuItem[];
   onSelect?: (value: string) => void;
+  /**
+   * Placement relative to the trigger.
+   *
+   * @defaultValue `bottom-end`
+   * @see the component manifest
+   */
   placement?: 'bottom-start' | 'bottom-end';
+  /**
+   * Accessible label for the component.
+   *
+   * @defaultValue `More actions`
+   * @see the component manifest
+   */
   ariaLabel?: string;
   size?: 'sm' | 'md';
   disabled?: boolean;
@@ -966,11 +1289,44 @@ interface SearchProps {
   /** @deprecated Use `onValueChange` — it receives the same string. */
   onChange?: (value: string) => void;
   onSearch?: (value: string) => void;
+  /**
+   * Debounce delay (ms) before onSearch fires.
+   *
+   * @defaultValue `300`
+   * @see the component manifest
+   */
   debounceMs?: number;
+  /**
+   * Placeholder text shown when the field is empty.
+   *
+   * @defaultValue `Search`
+   * @see the component manifest
+   */
   placeholder?: string;
   size?: 'sm' | 'md' | 'lg';
+  /**
+   * Accessible name for the control. Rendered as a real `<label>` that is **visually
+   * hidden** by design — it changes the accessible name, not the visible UI. If you can see
+   * it, the component stylesheet did not load (import `@cascivo/react/styles.css` or the
+   * per-component CSS).
+   *
+   * @defaultValue `Search`
+   * @see the component manifest
+   */
   label?: string;
+  /**
+   * When true, disables the control and removes it from the tab order.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   disabled?: boolean;
+  /**
+   * Accessible label for the clear button.
+   *
+   * @defaultValue `Clear search`
+   * @see the component manifest
+   */
   clearLabel?: string;
   id?: string;
   className?: string;
@@ -999,6 +1355,12 @@ interface NumberInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, '
   onChange?: (value: number | null) => void;
   min?: number;
   max?: number;
+  /**
+   * Increment between allowed values.
+   *
+   * @defaultValue `1`
+   * @see the component manifest
+   */
   step?: number;
   precision?: number;
   formatOptions?: Intl.NumberFormatOptions;
@@ -1006,7 +1368,19 @@ interface NumberInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, '
   hint?: string;
   error?: string;
   size?: 'sm' | 'md' | 'lg';
+  /**
+   * Accessible label for the increment button.
+   *
+   * @defaultValue `Increment`
+   * @see the component manifest
+   */
   incrementLabel?: string;
+  /**
+   * Accessible label for the decrement button.
+   *
+   * @defaultValue `Decrement`
+   * @see the component manifest
+   */
   decrementLabel?: string;
 }
 declare function NumberInput({
@@ -1039,7 +1413,23 @@ interface Column<Row> {
   sortable?: boolean;
   render?: (row: Row) => ReactNode;
   align?: 'start' | 'end';
+  /**
+   * Preferred column width, any CSS length (`'8rem'`, `'120px'`, `'12%'`). Set it on
+   * identifier-shaped columns (commit hashes, IDs, timestamps) — default sizing doesn't
+   * consider content shape, so a hash wraps mid-hash.
+   *
+   * **Mixing sized and unsized columns is supported**: unsized columns absorb the
+   * remaining width and never collapse below their content. Only when *every* column
+   * declares a width does the table switch to a fixed layout (which keeps widths
+   * identical across pages); otherwise widths are preferred sizes, not hard ones.
+   */
   width?: string;
+  /**
+   * Floor for the column's width, any CSS length. Use it on a free-form column
+   * (a commit message, a description) that must stay readable when the table is narrow —
+   * the table then scrolls horizontally rather than squeezing the column to nothing.
+   */
+  minWidth?: string;
 }
 type SortDirection = 'asc' | 'desc';
 interface SortState {
@@ -1064,6 +1454,12 @@ interface DataTableProps<Row> {
   defaultSort?: SortState;
   sortMode?: 'client' | 'server';
   onSortChange?: (sort: SortState | undefined) => void;
+  /**
+   * When true, shows a search/filter input.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   searchable?: boolean;
   pagination?: {
     pageSize: number;
@@ -1081,17 +1477,59 @@ interface DataTableProps<Row> {
   }[];
   renderExpandedRow?: (row: Row) => ReactNode;
   density?: 'compact' | 'normal' | 'relaxed';
+  /**
+   * When true, applies alternating row striping.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   zebra?: boolean;
+  /**
+   * When true, the header stays fixed while the body scrolls.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   stickyHeader?: boolean;
+  /**
+   * When true, shows a loading state.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   loading?: boolean;
   emptyState?: ReactNode;
   title?: string;
   description?: string;
   labels?: DataTableLabels;
   className?: string;
+  /**
+   * Render only the visible row window for large datasets.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   virtualized?: boolean;
+  /**
+   * Fixed row height in px, used to compute the virtualized window.
+   *
+   * @defaultValue `40`
+   * @see the component manifest
+   */
   rowHeight?: number;
+  /**
+   * Number of rows rendered in the virtualized window.
+   *
+   * @defaultValue `20`
+   * @see the component manifest
+   */
   windowSize?: number;
+  /**
+   * Extra rows rendered above/below the window to smooth scrolling.
+   *
+   * @defaultValue `3`
+   * @see the component manifest
+   */
   overscan?: number;
 }
 declare function DataTable<Row>({
@@ -1122,6 +1560,12 @@ declare function DataTable<Row>({
   overscan
 }: DataTableProps<Row>): import("react").JSX.Element;
 interface CommandPage {
+  /**
+   * Placeholder text shown when the field is empty.
+   *
+   * @defaultValue `Type a command or search…`
+   * @see the component manifest
+   */
   placeholder?: string;
   groups: CommandGroup[];
 }
@@ -1176,12 +1620,43 @@ interface CommandMenuProps {
   onOpenChange: (open: boolean) => void;
   groups: CommandGroup[];
   placeholder?: string;
+  /**
+   * Text shown when no commands match the query.
+   *
+   * @defaultValue `No results found`
+   * @see the component manifest
+   */
   emptyLabel?: string;
+  /**
+   * Global Cmd/Ctrl+K toggles the menu via onOpenChange
+   *
+   * @defaultValue `true`
+   * @see the component manifest
+   */
   hotkey?: boolean;
+  /**
+   * Text label for the control.
+   *
+   * @defaultValue `Command menu`
+   * @see the component manifest
+   */
   label?: string;
+  /**
+   * Shows a loading spinner in place of the empty state (for async items)
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   loading?: boolean;
   onQueryChange?: (query: string) => void;
-  /** Selectable filter scopes; enables the scope bar, chip, prefixes, and Tab cycling. */
+  /**
+   * Selectable filter scopes. Renders a scope bar + chip; a scope activates by clicking its
+   * pill, typing its prefix (c:/c ), or cycling with Tab, and filters to groups tagged with
+   * a matching scope (plus untagged groups).
+   *
+   * @defaultValue `[]`
+   * @see the component manifest
+   */
   scopes?: CommandScope[];
   className?: string;
 }
@@ -1284,6 +1759,12 @@ declare function Form<T extends Record<string, unknown>>({
 interface ComboboxOption {
   value: string;
   label: string;
+  /**
+   * When true, disables the control and removes it from the tab order.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   disabled?: boolean;
 }
 interface ComboboxLabels {
@@ -1300,7 +1781,19 @@ interface ComboboxProps {
   onValueChange?: (value: string | undefined) => void;
   /** @deprecated Use `onValueChange` — it receives the same `string | undefined`. */
   onChange?: (value: string | undefined) => void;
+  /**
+   * When true, shows a control to clear the selected value.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   clearable?: boolean;
+  /**
+   * When true, shows a search/filter input.
+   *
+   * @defaultValue `true`
+   * @see the component manifest
+   */
   searchable?: boolean;
   label?: string;
   hint?: string;
@@ -1343,11 +1836,29 @@ interface DatePickerProps {
   onChange?: (value: string | undefined) => void;
   min?: string;
   max?: string;
+  /**
+   * Shows a clear button
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   clearable?: boolean;
   label?: string;
   hint?: string;
   error?: string;
+  /**
+   * Field size
+   *
+   * @defaultValue `md`
+   * @see the component manifest
+   */
   size?: 'sm' | 'md' | 'lg';
+  /**
+   * Disables the picker
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   disabled?: boolean;
   labels?: DatePickerLabels;
   className?: string;
@@ -1386,9 +1897,21 @@ interface FileUploaderLabels {
   error?: string;
 }
 interface FileUploaderProps {
+  /**
+   * Controlled file list
+   *
+   * @defaultValue `[]`
+   * @see the component manifest
+   */
   files?: UploaderFile[];
   onFilesAdded?: (files: File[]) => void;
   onRemove?: (id: string) => void;
+  /**
+   * Allow multiple files
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   multiple?: boolean;
   accept?: string;
   maxSize?: number;
@@ -1396,6 +1919,12 @@ interface FileUploaderProps {
   label?: string;
   hint?: string;
   labels?: FileUploaderLabels;
+  /**
+   * Disables the upload zone
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   disabled?: boolean;
   className?: string;
 }
@@ -1520,6 +2049,12 @@ interface AlertDialogProps {
   onConfirm: () => void;
   onCancel: () => void;
   labels?: AlertDialogLabels;
+  /**
+   * Selects the visual style variant.
+   *
+   * @defaultValue `default`
+   * @see the component manifest
+   */
   variant?: 'destructive' | 'default';
 }
 declare function AlertDialog({
@@ -1537,6 +2072,12 @@ interface SheetProps {
   /** Optional heading. Accepts rich nodes; when present it labels the dialog via `aria-labelledby`. */
   title?: ReactNode;
   children: ReactNode;
+  /**
+   * Edge the component is anchored to.
+   *
+   * @defaultValue `end`
+   * @see the component manifest
+   */
   side?: 'start' | 'end' | 'top' | 'bottom';
 }
 declare function Sheet({
@@ -1560,7 +2101,12 @@ interface BottomSheetProps {
   snapPoints?: number[];
   /** Controlled active detent index into `snapPoints`. */
   activeSnap?: number;
-  /** Initial active detent index for uncontrolled use. Defaults to the lowest detent. */
+  /**
+   * The initial snap-point index when uncontrolled.
+   *
+   * @defaultValue `0`
+   * @see the component manifest
+   */
   defaultSnap?: number;
   /** Called when the active detent changes via drag. */
   onSnapChange?: (index: number) => void;
@@ -1619,11 +2165,27 @@ interface ComparisonProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange
   before: ReactNode;
   /** Divider position as a percentage 0–100. Controlled when provided. */
   position?: number;
-  /** Initial divider position for uncontrolled use. Default 50. */
+  /**
+   * The initial divider position (0–100) when uncontrolled.
+   *
+   * @defaultValue `50`
+   * @see the component manifest
+   */
   defaultPosition?: number;
   onPositionChange?: (position: number) => void;
+  /**
+   * Layout orientation of the component.
+   *
+   * @defaultValue `horizontal`
+   * @see the component manifest
+   */
   orientation?: 'horizontal' | 'vertical';
-  /** Percentage the Arrow keys move the divider. Default 5. */
+  /**
+   * How far the divider moves per arrow-key press.
+   *
+   * @defaultValue `5`
+   * @see the component manifest
+   */
   keyboardStep?: number;
   /** Accessible label for the divider slider. */
   label?: string;
@@ -1642,7 +2204,19 @@ declare function Comparison({
 }: ComparisonProps): import("react").JSX.Element;
 interface HoverCardProps {
   children: ReactNode;
+  /**
+   * Delay (ms) before the card opens on hover/focus.
+   *
+   * @defaultValue `300`
+   * @see the component manifest
+   */
   openDelay?: number;
+  /**
+   * Delay (ms) before the card closes after hover/focus leaves.
+   *
+   * @defaultValue `100`
+   * @see the component manifest
+   */
   closeDelay?: number;
 }
 declare function HoverCard({
@@ -1670,6 +2244,12 @@ interface PasswordInputLabels {
   strengthLabel?: (level: string) => string;
 }
 interface PasswordInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'type' | 'size'> {
+  /**
+   * When true, shows a password-strength meter.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   showStrengthMeter?: boolean;
   size?: 'sm' | 'md' | 'lg';
   labels?: PasswordInputLabels;
@@ -1688,6 +2268,12 @@ declare function PasswordInput({
 interface MultiSelectOption {
   label: string;
   value: string;
+  /**
+   * When true, disables the control and removes it from the tab order.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   disabled?: boolean;
 }
 interface MultiSelectLabels {
@@ -1721,6 +2307,12 @@ interface TagsInputProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange'
   placeholder?: string;
   validate?: (tag: string) => boolean;
   max?: number;
+  /**
+   * When true, disables the control and removes it from the tab order.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   disabled?: boolean;
 }
 declare function TagsInput({
@@ -1734,9 +2326,21 @@ declare function TagsInput({
   ...props
 }: TagsInputProps): import("react").JSX.Element;
 interface OtpInputProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange'> {
+  /**
+   * Number of input cells.
+   *
+   * @defaultValue `6`
+   * @see the component manifest
+   */
   length?: number;
   value: string;
   onValueChange: (v: string) => void;
+  /**
+   * When true, disables the control and removes it from the tab order.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   disabled?: boolean;
   type?: 'numeric' | 'alphanumeric';
 }
@@ -1752,6 +2356,12 @@ declare function OtpInput({
 interface SegmentedControlOption {
   label: string;
   value: string;
+  /**
+   * When true, disables the control and removes it from the tab order.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   disabled?: boolean;
 }
 interface SegmentedControlProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange'> {
@@ -1800,9 +2410,27 @@ interface RatingGroupLabels {
 interface RatingGroupProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange'> {
   value: number;
   onValueChange?: (v: number) => void;
+  /**
+   * Maximum allowed value.
+   *
+   * @defaultValue `5`
+   * @see the component manifest
+   */
   max?: number;
   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 value is shown but cannot be edited.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   readOnly?: boolean;
   labels?: RatingGroupLabels;
 }
@@ -1821,7 +2449,19 @@ interface EditableProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange'>
   value: string;
   onValueChange: (v: string) => void;
   placeholder?: string;
+  /**
+   * When true, disables the control and removes it from the tab order.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   disabled?: boolean;
+  /**
+   * When true, commits the edit when the field loses focus.
+   *
+   * @defaultValue `true`
+   * @see the component manifest
+   */
   submitOnBlur?: boolean;
   onCancel?: () => void;
 }
@@ -1961,6 +2601,12 @@ type SwitcherEntry = SwitcherLink | {
 };
 interface SwitcherProps {
   items: SwitcherEntry[];
+  /**
+   * Text label for the control.
+   *
+   * @defaultValue `Switch application`
+   * @see the component manifest
+   */
   label?: string;
   className?: string | undefined;
 }
@@ -2007,6 +2653,14 @@ interface StatProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
   delta?: string;
   trend?: 'up' | 'down' | 'flat';
   helpText?: string;
+  /**
+   * Wrap the tile in the same card chrome (surface, border, radius, padding) that
+   * `@cascivo/charts`' `Kpi` ships. `Stat` is layout-only by default so it can sit inside
+   * a `Card` you control; `Kpi` always brings its own chrome, which made a `Stat` row and
+   * a `Kpi` row on adjacent pages of one dashboard look like different products. Set this
+   * when you are mixing the two, or use it instead of hand-wrapping every `Stat` in a `Card`.
+   */
+  card?: boolean;
   /** Trailing visual, e.g. a `Sparkline` from the separate `@cascivo/charts` package (not exported from `@cascivo/react`; `pnpm add @cascivo/charts`). Purely decorative — mark it `aria-hidden` yourself if it duplicates the value/delta already announced. */
   visual?: ReactNode;
 }
@@ -2016,13 +2670,24 @@ declare function Stat({
   delta,
   trend,
   helpText,
+  card,
   visual,
   className,
   ...props
 }: StatProps): import("react").JSX.Element;
 interface StatusProps extends HTMLAttributes<HTMLSpanElement> {
-  status?: 'success' | 'warning' | 'error' | 'info' | 'neutral';
-  /** Pulses the dot — only when the user allows motion. */
+  /**
+   * Severity tone. Accepts the catalog-wide `Tone` vocabulary
+   * (`neutral | info | success | warning | danger`) plus Status's historical spellings
+   * (`error`, `destructive`, `default`).
+   */
+  status?: ToneInput;
+  /**
+   * Pulses the dot — gated behind prefers-reduced-motion: no-preference
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   pulse?: boolean;
 }
 declare function Status({
@@ -2032,15 +2697,13 @@ declare function Status({
   children,
   ...props
 }: StatusProps): import("react").JSX.Element;
-interface VisuallyHiddenProps extends HTMLAttributes<HTMLSpanElement> {
-  children: ReactNode;
-}
-declare function VisuallyHidden({
-  children,
-  className,
-  ...props
-}: VisuallyHiddenProps): import("react").JSX.Element;
 interface SkipNavLinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> {
+  /**
+   * SkipNavLink: id of the SkipNavTarget to jump to
+   *
+   * @defaultValue `cascade-skip-target`
+   * @see the component manifest
+   */
   targetId?: string;
   labels?: {
     label?: string;
@@ -2054,6 +2717,12 @@ declare function SkipNavLink({
   ...props
 }: SkipNavLinkProps): import("react").JSX.Element;
 interface SkipNavTargetProps extends HTMLAttributes<HTMLDivElement> {
+  /**
+   * SkipNavTarget: anchor id — must match the link targetId
+   *
+   * @defaultValue `cascade-skip-target`
+   * @see the component manifest
+   */
   id?: string;
 }
 /** Place where the main content starts; the link's hash navigation moves focus here. */
@@ -2066,8 +2735,22 @@ type ProgressSize = 'sm' | 'md' | 'lg';
 interface ProgressProps {
   /** 0–100. Omit for indeterminate state. */
   value?: number;
+  /**
+   * Selects the visual style variant.
+   *
+   * @defaultValue `primary`
+   * @see the component manifest
+   */
   variant?: ProgressVariant;
   size?: ProgressSize;
+  /**
+   * Invisible accessible name. `ariaLabel` is the catalog convention (see the
+   * accessible-name table in `docs/AI-RULES.md`); the DOM spelling `aria-label` is accepted
+   * too, so either guess compiles. Two spellings of one idea inside a package was a coin
+   * flip on every component.
+   */
+  ariaLabel?: string;
+  /** DOM-spelled alias of {@link ariaLabel}. */
   'aria-label'?: string;
   'aria-describedby'?: string;
   className?: string;
@@ -2077,14 +2760,26 @@ declare function Progress({
   variant,
   size,
   className,
+  ariaLabel,
   ...aria
 }: ProgressProps): import("react").JSX.Element;
 interface ProgressCircleProps extends HTMLAttributes<HTMLDivElement> {
   /** Current value from 0 to max — clamped. */
   value: number;
+  /**
+   * Maximum allowed value.
+   *
+   * @defaultValue `100`
+   * @see the component manifest
+   */
   max?: number;
   size?: 'sm' | 'md' | 'lg';
-  /** Renders the rounded percentage in the center — pairs best with md and lg. */
+  /**
+   * Renders the rounded percentage in the center — pairs best with md and lg
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   showValue?: boolean;
   /** Accessible name for the progressbar. */
   label?: string;
@@ -2101,6 +2796,12 @@ declare function ProgressCircle({
 type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
 type HeadingSize = 'sm' | 'md' | 'lg' | 'xl' | '2xl';
 interface HeadingProps extends HTMLAttributes<HTMLHeadingElement> {
+  /**
+   * Heading level (1–6) mapping to h1–h6.
+   *
+   * @defaultValue `2`
+   * @see the component manifest
+   */
   level?: HeadingLevel;
   size?: HeadingSize;
 }
@@ -2112,9 +2813,21 @@ declare function Heading({
   ...props
 }: HeadingProps): import("react").JSX.Element;
 interface TextProps extends HTMLAttributes<HTMLElement> {
+  /**
+   * The HTML element to render as.
+   *
+   * @defaultValue `p`
+   * @see the component manifest
+   */
   as?: 'p' | 'span' | 'div';
   size?: 'sm' | 'md' | 'lg';
   weight?: 'normal' | 'medium' | 'semibold';
+  /**
+   * When true, renders in a muted/subtle color.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   muted?: boolean;
 }
 declare function Text({
@@ -2136,6 +2849,12 @@ declare function Code({
   ...props
 }: CodeProps): import("react").JSX.Element;
 interface BlockquoteProps extends HTMLAttributes<HTMLQuoteElement> {
+  /**
+   * URL of the quote’s source (sets the HTML cite attribute).
+   *
+   * @defaultValue `undefined`
+   * @see the component manifest
+   */
   cite?: string;
 }
 declare function Blockquote({
@@ -2145,6 +2864,12 @@ declare function Blockquote({
   ...props
 }: BlockquoteProps): import("react").JSX.Element;
 interface ListProps extends HTMLAttributes<HTMLElement> {
+  /**
+   * The HTML element to render as.
+   *
+   * @defaultValue `ul`
+   * @see the component manifest
+   */
   as?: 'ul' | 'ol';
   marker?: 'disc' | 'decimal' | 'none';
 }
@@ -2185,14 +2910,29 @@ interface LogViewerProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'
   lines: {
     readonly value: readonly LogLine[];
   } | readonly LogLine[];
-  /** Pixel height of one row. Default 20. */
+  /**
+   * Height of each row in pixels, used for virtualization.
+   *
+   * @defaultValue `20`
+   * @see the component manifest
+   */
   rowHeight?: number;
-  /** Extra rows rendered above/below the viewport. Default 8. */
+  /**
+   * Number of extra rows rendered above and below the viewport.
+   *
+   * @defaultValue `8`
+   * @see the component manifest
+   */
   overscan?: number;
   /** Controlled pin-to-bottom. Omit for uncontrolled (defaults to following). */
   follow?: boolean;
   onFollowChange?: (follow: boolean) => void;
-  /** Parse ANSI SGR color escapes. Default false (use `level` instead). */
+  /**
+   * When true, parses ANSI color escape codes into colored spans.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   ansi?: boolean;
   /** Seed the search/highlight box. */
   search?: string;
@@ -2229,8 +2969,19 @@ interface PullToRefreshProps {
   /** Invoked when the pull passes the threshold; the spinner shows until it settles. */
   onRefresh: () => Promise<unknown> | unknown;
   children: ReactNode;
-  /** Pull distance (px) required to trigger a refresh. Default 64. */
+  /**
+   * Pull distance (px) required to trigger a refresh.
+   *
+   * @defaultValue `64`
+   * @see the component manifest
+   */
   threshold?: number;
+  /**
+   * When true, disables the control and removes it from the tab order.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   disabled?: boolean;
   labels?: {
     pull?: string;
@@ -2268,13 +3019,28 @@ interface QrCodeProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
   value: string;
   /** Rendered size in pixels (width and height). Default 128. */
   size?: number;
-  /** Error-correction level. Higher tolerates more damage but holds less data. Default 'M'. */
+  /**
+   * Higher levels tolerate more damage but hold less data
+   *
+   * @defaultValue `M`
+   * @see the component manifest
+   */
   errorCorrection?: ErrorCorrection;
   /** CSS length rounding the code's corners (applied to the container). */
   radius?: string;
-  /** Module color. Default `currentColor` so the code inherits text color. */
+  /**
+   * Foreground color of the QR modules.
+   *
+   * @defaultValue `currentColor`
+   * @see the component manifest
+   */
   fill?: string;
-  /** Background color behind the modules. Default `transparent`. */
+  /**
+   * Background color behind the QR code.
+   *
+   * @defaultValue `transparent`
+   * @see the component manifest
+   */
   background?: string;
   /** Accessible label. Defaults to the i18n built-in "QR code". */
   label?: string;
@@ -2294,7 +3060,12 @@ declare function QrCode({
 interface RelativeTimeProps extends Omit<TimeHTMLAttributes<HTMLTimeElement>, 'dateTime'> {
   /** The instant to describe relative to now. */
   date: Date | number | string;
-  /** Auto-update as time passes. Default true. */
+  /**
+   * When true, updates the relative time as it elapses.
+   *
+   * @defaultValue `true`
+   * @see the component manifest
+   */
   sync?: boolean;
   /** Override "now" (ms since epoch). Mainly for deterministic tests; disables the interval. */
   now?: number;
@@ -2310,11 +3081,27 @@ declare function RelativeTime({
   ...props
 }: RelativeTimeProps): import("react").JSX.Element;
 interface LabelProps extends LabelHTMLAttributes<HTMLLabelElement> {
-  /** Renders into the child element (Slot composition) instead of a native `<label>`. */
+  /**
+   * When true, renders the child element as the root via Slot, merging props (polymorphic
+   * rendering).
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   asChild?: boolean;
-  /** Shows a required marker after the label text. */
+  /**
+   * When true, marks the field as required.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   required?: boolean;
-  /** Dims the label to match an associated disabled control. */
+  /**
+   * When true, disables the control and removes it from the tab order.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   disabled?: boolean;
   children: ReactNode;
   /** Override built-in strings (e.g. the required-marker accessible text). */
@@ -2338,9 +3125,19 @@ interface FieldProps {
   description?: ReactNode;
   /** Error message; sets aria-invalid on the control and is announced via role="alert". */
   error?: ReactNode;
-  /** Marks the field required (forwarded to the Label marker). */
+  /**
+   * When true, marks the field as required.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   required?: boolean;
-  /** Dims the label and is forwarded to the cloned control. */
+  /**
+   * When true, disables the control and removes it from the tab order.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   disabled?: boolean;
   /** Explicit id for the control; auto-generated when omitted. */
   id?: string;
@@ -2371,13 +3168,39 @@ interface FilterOption {
 interface FilterProps {
   options: FilterOption[];
   value?: string[];
+  /**
+   * Initial selected values for uncontrolled use
+   *
+   * @defaultValue `[]`
+   * @see the component manifest
+   */
   defaultValue?: string[];
   /** Called with the selected values whenever the selection changes. */
   onValueChange?: (selected: string[]) => void;
   /** @deprecated Use `onValueChange` — it receives the same `string[]`. */
   onChange?: (selected: string[]) => void;
+  /**
+   * Allow multiple items to be selected simultaneously
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   multi?: boolean;
+  /**
+   * Selects the visual style variant.
+   *
+   * @defaultValue `pill`
+   * @see the component manifest
+   */
   variant?: FilterVariant;
+  /**
+   * Invisible accessible name. `ariaLabel` is the catalog convention (see the
+   * accessible-name table in `docs/AI-RULES.md`); the DOM spelling `aria-label` is accepted
+   * too, so either guess compiles. Two spellings of one idea inside a package was a coin
+   * flip on every component.
+   */
+  ariaLabel?: string;
+  /** DOM-spelled alias of {@link ariaLabel}. */
   'aria-label'?: string;
   className?: string;
 }
@@ -2390,25 +3213,66 @@ declare function Filter({
   multi,
   variant,
   className,
+  ariaLabel,
   ...aria
 }: FilterProps): import("react").JSX.Element;
-interface IconButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
-  /** Accessible name for the icon-only control. Required — there is no visible text. */
-  label: string;
+interface IconButtonBaseProps extends ButtonHTMLAttributes<HTMLButtonElement> {
   /** The icon to render. Alias for `children`. Any ReactNode — `@cascivo/icons`
    * ships ~440 ready-made SVG icon components, or pass your own. */
   icon?: ReactNode;
   size?: 'sm' | 'md' | 'lg';
+  /**
+   * Selects the visual style variant.
+   *
+   * @defaultValue `ghost`
+   * @see the component manifest
+   */
   variant?: 'ghost' | 'outline' | 'filled';
-  /** Render the single child element instead of a `<button>` (composition). */
+  /**
+   * When true, renders the child element as the root via Slot, merging props (polymorphic
+   * rendering).
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   asChild?: boolean;
 }
+/**
+ * Exactly one of `label` / `ariaLabel` is required — an icon-only control with no
+ * accessible name is a bug, so this stays enforced by the type rather than a dev warning.
+ * `ariaLabel` is the catalog's convention for an invisible accessible name; `IconButton`
+ * predates it and shipped `label`, so both work and neither is deprecated.
+ */
+type IconButtonProps = IconButtonBaseProps & ({
+  label: string;
+  ariaLabel?: never;
+} | {
+  ariaLabel: string;
+  label?: never;
+});
 declare const IconButton: import("react").ForwardRefExoticComponent<IconButtonProps & import("react").RefAttributes<HTMLButtonElement>>;
 interface ButtonGroupProps extends HTMLAttributes<HTMLDivElement> {
+  /**
+   * Layout orientation of the component.
+   *
+   * @defaultValue `horizontal`
+   * @see the component manifest
+   */
   orientation?: 'horizontal' | 'vertical';
   size?: 'sm' | 'md' | 'lg';
-  /** Enable arrow-key roving focus across the group's focusable buttons. */
+  /**
+   * When true, uses roving tabindex so arrow keys move focus between buttons.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   roving?: boolean;
+  /**
+   * When true, navigation wraps around from end to start.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   loop?: boolean;
 }
 declare const ButtonGroup: import("react").ForwardRefExoticComponent<ButtonGroupProps & import("react").RefAttributes<HTMLDivElement>>;
@@ -2416,6 +3280,12 @@ interface ToggleGroupItem {
   value: string;
   label?: string;
   icon?: ReactNode;
+  /**
+   * When true, disables the control and removes it from the tab order.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   disabled?: boolean;
 }
 interface ToggleGroupProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue'> {
@@ -2424,6 +3294,12 @@ interface ToggleGroupProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChang
   defaultValue?: string | string[];
   onValueChange?: (value: string | string[]) => void;
   items: ToggleGroupItem[];
+  /**
+   * Layout orientation of the component.
+   *
+   * @defaultValue `horizontal`
+   * @see the component manifest
+   */
   orientation?: 'horizontal' | 'vertical';
   size?: 'sm' | 'md' | 'lg';
   disabled?: boolean;
@@ -2446,11 +3322,23 @@ declare function InlineLoading({
   className,
   ...props
 }: InlineLoadingProps): import("react").JSX.Element;
-type NotificationVariant = 'info' | 'success' | 'warning' | 'error';
+/** The value Notification's stylesheet and icon set key on. */
+type NotificationVariant = 'neutral' | 'info' | 'success' | 'warning' | 'error';
 interface NotificationProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'> {
   title: ReactNode;
   description?: ReactNode;
-  variant?: NotificationVariant;
+  /**
+   * Severity tone. Accepts the catalog-wide `Tone` vocabulary
+   * (`neutral | info | success | warning | danger`) plus Notification's historical
+   * spellings (`error`, `destructive`).
+   */
+  variant?: ToneInput;
+  /**
+   * When true, shows a control to dismiss the component.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   dismissible?: boolean;
   onDismiss?: () => void;
   actions?: ReactNode;
@@ -2462,7 +3350,7 @@ interface NotificationProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'
 declare function Notification({
   title,
   description,
-  variant,
+  variant: variantProp,
   dismissible,
   onDismiss,
   actions,
@@ -2476,9 +3364,19 @@ interface ScrollAreaProps extends HTMLAttributes<HTMLDivElement> {
   height?: string;
   /** Max inline size of the scroll container (any CSS length). */
   width?: string;
-  /** Which axes may scroll. */
+  /**
+   * Which axes may scroll
+   *
+   * @defaultValue `vertical`
+   * @see the component manifest
+   */
   orientation?: 'vertical' | 'horizontal' | 'both';
-  /** Edge affordance: box-shadow (default), a mask-image fade (HeroUI ScrollShadow), or none. */
+  /**
+   * Edge affordance: box-shadow, a mask-image fade, or none
+   *
+   * @defaultValue `shadow`
+   * @see the component manifest
+   */
   edges?: 'shadow' | 'mask' | 'none';
   children?: ReactNode;
 }
@@ -2495,13 +3393,23 @@ declare function ScrollArea({
 interface CollapsibleProps {
   /** Controlled open state. */
   open?: boolean;
-  /** Initial open state for uncontrolled use. */
+  /**
+   * Initial open state for uncontrolled use
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   defaultOpen?: boolean;
   /** Called whenever the open state should change. */
   onOpenChange?: (open: boolean) => void;
   /** Content rendered inside the trigger button. */
   trigger: ReactNode;
-  /** Disables the trigger. */
+  /**
+   * Disables the trigger button
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   disabled?: boolean;
   className?: string;
   children?: ReactNode;
@@ -2516,7 +3424,12 @@ declare function Collapsible({
   children
 }: CollapsibleProps): import("react").JSX.Element;
 interface AspectRatioProps extends HTMLAttributes<HTMLDivElement> {
-  /** Width-to-height ratio (e.g. 16 / 9). Defaults to 16/9. */
+  /**
+   * Width-to-height ratio applied via the CSS aspect-ratio property
+   *
+   * @defaultValue `16 / 9`
+   * @see the component manifest
+   */
   ratio?: number;
   children?: ReactNode;
 }
@@ -2531,6 +3444,12 @@ interface MenuButtonItem {
   id: string;
   label: ReactNode;
   onSelect?: () => void;
+  /**
+   * Disables the trigger
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   disabled?: boolean;
 }
 interface MenuButtonProps {
@@ -2562,6 +3481,12 @@ interface ToggletipProps {
   /** The popover content. Interactive and selectable. */
   children: ReactNode;
   placement?: ToggletipPlacement;
+  /**
+   * Initial open state when uncontrolled
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   defaultOpen?: boolean;
   open?: boolean;
   onOpenChange?: (open: boolean) => void;
@@ -2610,6 +3535,12 @@ interface NavigationMenuItem {
 interface NavigationMenuProps {
   items: NavigationMenuItem[];
   'aria-label'?: string;
+  /**
+   * Layout orientation of the component.
+   *
+   * @defaultValue `horizontal`
+   * @see the component manifest
+   */
   orientation?: RovingOrientation;
   className?: string;
 }
@@ -2662,11 +3593,25 @@ interface StructuredListItem {
 interface StructuredListProps {
   items: StructuredListItem[];
   headers?: ReactNode[];
+  /**
+   * When true, rows can be selected.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   selectable?: boolean;
   value?: string;
   defaultValue?: string;
   onSelect?: (id: string) => void;
   className?: string;
+  /**
+   * Invisible accessible name. `ariaLabel` is the catalog convention (see the
+   * accessible-name table in `docs/AI-RULES.md`); the DOM spelling `aria-label` is accepted
+   * too, so either guess compiles. Two spellings of one idea inside a package was a coin
+   * flip on every component.
+   */
+  ariaLabel?: string;
+  /** DOM-spelled alias of {@link ariaLabel}. */
   'aria-label'?: string;
 }
 declare function StructuredList(props: StructuredListProps): import("react").JSX.Element;
@@ -2700,7 +3645,19 @@ interface DataListItem {
 }
 interface DataListProps extends HTMLAttributes<HTMLDListElement> {
   items: DataListItem[];
+  /**
+   * Layout orientation of the component.
+   *
+   * @defaultValue `horizontal`
+   * @see the component manifest
+   */
   orientation?: 'horizontal' | 'vertical';
+  /**
+   * When true, shows dividers between items.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   dividers?: boolean;
   size?: 'sm' | 'md';
 }
@@ -2718,10 +3675,22 @@ interface TimelineItem {
   description?: ReactNode;
   time?: string;
   icon?: ReactNode;
-  status?: 'complete' | 'current' | 'upcoming';
+  /**
+   * Where this entry sits in the sequence. Accepts the catalog-wide `Progress` vocabulary
+   * (`pending | active | complete | error`) as well as Timeline's own `current` / `upcoming`
+   * — they are aliases of `active` / `pending`, so one status enum drives both `Timeline`
+   * and `Steps` with no translation.
+   */
+  status?: ProgressInput;
 }
 interface TimelineProps extends HTMLAttributes<HTMLOListElement> {
   items: TimelineItem[];
+  /**
+   * Layout orientation of the component.
+   *
+   * @defaultValue `vertical`
+   * @see the component manifest
+   */
   orientation?: 'vertical' | 'horizontal';
 }
 declare function Timeline({
@@ -2731,7 +3700,20 @@ declare function Timeline({
   ...props
 }: TimelineProps): import("react").JSX.Element;
 interface ItemProps extends HTMLAttributes<HTMLDivElement> {
+  /**
+   * When true, renders the child element as the root via Slot, merging props (polymorphic
+   * rendering).
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   asChild?: boolean;
+  /**
+   * Selects the visual style variant.
+   *
+   * @defaultValue `default`
+   * @see the component manifest
+   */
   variant?: 'default' | 'muted';
   size?: 'sm' | 'md';
 }
@@ -2785,6 +3767,12 @@ interface CalendarProps {
   max?: Date;
   disabled?: (date: Date) => boolean;
   locale?: string;
+  /**
+   * Grid cell size
+   *
+   * @defaultValue `md`
+   * @see the component manifest
+   */
   size?: 'sm' | 'md' | 'lg';
   labels?: CalendarLabels;
   className?: string;
@@ -2804,7 +3792,12 @@ interface CalendarProps {
     month: number;
     year: number;
   }) => void;
-  /** Hide the prev/next header nav (parent drives navigation). */
+  /**
+   * Hides the prev/next nav so a parent can drive navigation
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   hideNav?: boolean;
 }
 declare function Calendar({
@@ -2855,6 +3848,12 @@ interface DateRangePickerProps {
   presets?: DateRangePreset[];
   locale?: string;
   placeholder?: string;
+  /**
+   * Field/grid size
+   *
+   * @defaultValue `md`
+   * @see the component manifest
+   */
   size?: 'sm' | 'md' | 'lg';
   labels?: DateRangePickerLabels;
   className?: string;
@@ -2875,17 +3874,35 @@ declare function DateRangePicker({
 }: DateRangePickerProps): import("react").JSX.Element;
 interface ColorPickerLabels {
   hue?: string;
+  /**
+   * When true, enables alpha (opacity) selection.
+   *
+   * @defaultValue `true`
+   * @see the component manifest
+   */
   alpha?: string;
   colorArea?: string;
   eyedropper?: string;
 }
 interface ColorPickerProps {
   value?: string;
+  /**
+   * The initial value when uncontrolled.
+   *
+   * @defaultValue `#3b82f6`
+   * @see the component manifest
+   */
   defaultValue?: string;
   onValueChange?: (value: string) => void;
   presets?: string[];
   alpha?: boolean;
   label?: string;
+  /**
+   * When true, disables the control and removes it from the tab order.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   disabled?: boolean;
   size?: 'sm' | 'md' | 'lg';
   className?: string;
@@ -2912,8 +3929,20 @@ interface CarouselProps {
   children?: ReactNode;
   slides?: ReactNode[];
   index?: number;
+  /**
+   * The initial slide index when uncontrolled.
+   *
+   * @defaultValue `0`
+   * @see the component manifest
+   */
   defaultIndex?: number;
   onIndexChange?: (index: number) => void;
+  /**
+   * When true, navigation wraps around from end to start.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   loop?: boolean;
   className?: string;
   labels?: CarouselLabels;
@@ -2930,10 +3959,34 @@ declare function Carousel({
 }: CarouselProps): import("react").JSX.Element;
 interface ResizableProps {
   children: ReactNode;
+  /**
+   * Layout orientation of the component.
+   *
+   * @defaultValue `horizontal`
+   * @see the component manifest
+   */
   orientation?: 'horizontal' | 'vertical';
+  /**
+   * The initial split ratio when uncontrolled.
+   *
+   * @defaultValue `0.5`
+   * @see the component manifest
+   */
   defaultRatio?: number;
   ratio?: number;
+  /**
+   * Minimum allowed split ratio.
+   *
+   * @defaultValue `0.1`
+   * @see the component manifest
+   */
   minRatio?: number;
+  /**
+   * Maximum allowed split ratio.
+   *
+   * @defaultValue `0.9`
+   * @see the component manifest
+   */
   maxRatio?: number;
   onRatioChange?: (ratio: number) => void;
   className?: string;
@@ -2976,7 +4029,12 @@ interface DrawerProps {
   defaultOpen?: boolean;
   /** Called whenever the open state should change. */
   onOpenChange?: (open: boolean) => void;
-  /** Edge the panel is anchored to. Drives the slide direction. */
+  /**
+   * Edge the panel is anchored to. Drives the slide direction.
+   *
+   * @defaultValue `end`
+   * @see the component manifest
+   */
   side?: 'start' | 'end' | 'top' | 'bottom';
   /** Panel size along its cross axis (width for start/end, height for top/bottom). */
   size?: string;
@@ -2989,7 +4047,12 @@ interface DrawerProps {
     close?: string;
   };
   className?: string;
-  /** Allow dragging the header toward its edge to dismiss (opt-in; CSS translate, no animation library). */
+  /**
+   * Allow dragging the header toward its edge to dismiss (opt-in).
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   swipeToDismiss?: boolean;
 }
 /**
@@ -3048,7 +4111,12 @@ type CodeLang = 'bash' | 'css' | 'js' | 'ts';
 interface CodeSnippetProps {
   /** The code to display (and copy). */
   code: string;
-  /** inline = a <code> span; single = one-line <pre>; multi = multi-line <pre>. */
+  /**
+   * inline = a <code> span; single = one-line <pre>; multi = multi-line <pre>.
+   *
+   * @defaultValue `single`
+   * @see the component manifest
+   */
   variant?: 'inline' | 'single' | 'multi';
   /**
    * Enables lightweight, dependency-free syntax highlighting for the block
@@ -3090,13 +4158,25 @@ declare function CodeSnippet({
   labels,
   className
 }: CodeSnippetProps): import("react").JSX.Element;
+/**
+ * The catalog-wide progress vocabulary. `Timeline`'s `current` / `upcoming` are accepted as
+ * aliases of `active` / `pending`, so one status enum drives both components — writing
+ * `state: 'upcoming'` here used to be a type error with no hint that `pending` was the word.
+ */
 type StepState = 'pending' | 'active' | 'complete' | 'error';
 interface Step {
   label: string;
-  state?: StepState;
+  /** Accepts `StepState` plus Timeline's `current` / `upcoming` aliases. */
+  state?: ProgressInput;
 }
 interface StepsProps {
   steps: Step[];
+  /**
+   * Index of the currently active step (0-based)
+   *
+   * @defaultValue `0`
+   * @see the component manifest
+   */
   activeStep?: number;
   orientation?: 'horizontal' | 'vertical';
   className?: string;
@@ -3119,7 +4199,12 @@ interface TileProps {
   defaultSelected?: boolean;
   /** Called with this tile's value whenever it is toggled on (or off for multi). */
   onSelect?: (value: string) => void;
-  /** Single = radio semantics (toggle on); multi = checkbox semantics (toggle on/off). */
+  /**
+   * Single = radio semantics (toggle on); multi = checkbox semantics (toggle on/off).
+   *
+   * @defaultValue `single`
+   * @see the component manifest
+   */
   selectable?: 'single' | 'multi';
   disabled?: boolean;
   /** Optional leading icon/visual. */
@@ -3149,6 +4234,12 @@ type IndicatorPlacement = 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end
 interface IndicatorProps {
   children: React.ReactNode;
   overlay: React.ReactNode;
+  /**
+   * Placement relative to the trigger.
+   *
+   * @defaultValue `top-end`
+   * @see the component manifest
+   */
   placement?: IndicatorPlacement;
   className?: string;
 }
@@ -3161,6 +4252,12 @@ declare function Indicator({
 type JoinOrientation = 'horizontal' | 'vertical';
 interface JoinProps {
   children: React.ReactNode;
+  /**
+   * Layout orientation of the component.
+   *
+   * @defaultValue `horizontal`
+   * @see the component manifest
+   */
   orientation?: JoinOrientation;
   className?: string;
 }
@@ -3171,6 +4268,13 @@ declare function Join({
 }: JoinProps): import("react").JSX.Element;
 interface StackProps {
   children: React.ReactNode;
+  /**
+   * Pixel offset applied per overlapped layer in both axes. This is NOT a spacing `gap` —
+   * for gap-based vertical/horizontal layout use `Flex`/`Grid` and their `gap` prop.
+   *
+   * @defaultValue `4`
+   * @see the component manifest
+   */
   offset?: number;
   className?: string;
 }
@@ -3179,7 +4283,17 @@ declare function Stack({
   offset,
   className
 }: StackProps): import("react").JSX.Element;
-interface AppShellProps {
+/**
+ * `AppShell` extends `HTMLAttributes<HTMLDivElement>`, like every other layout primitive,
+ * so `className` **and `style`** pass through to its root element. That matters because the
+ * shell's documented design tokens (`--cascivo-shell-aside-inline-size`,
+ * `--cascivo-shell-panel-inline-size`, `--cascivo-shell-header-block-size`) have to be set
+ * *somewhere*: set them here —
+ * `<AppShell style={{ '--cascivo-shell-aside-inline-size': '15.5rem' }}>` — or on any
+ * ancestor, since they inherit. Before this the props were a closed list with no `style`,
+ * so the tokens had no documented application point and adopters set them on `#root`.
+ */
+interface AppShellProps extends HTMLAttributes<HTMLDivElement> {
   /**
    * Top bar — typically a `<ShellHeader>`. If it is a React element, AppShell
    * binds its burger (`onMenuClick`/`menuExpanded`) to the nav open state so the
@@ -3212,6 +4326,11 @@ interface AppShellProps {
  * Rail vs full-hide reconcile cleanly: AppShell owns the full show/hide (this
  * `open` state); the SideNav you pass owns its own rail collapse
  * (`showCollapseToggle`). They compose on different axes and never fight.
+ *
+ * **Visual regression note:** the shell is `100dvh` with an internal scroll container (that
+ * is what makes the header sticky and the nav full-height). The page body therefore never
+ * grows, so a Playwright `fullPage: true` screenshot captures only the viewport. To capture
+ * the whole page, screenshot the scroll container element or set a tall viewport.
  */
 declare function AppShell({
   header,
@@ -3221,11 +4340,18 @@ declare function AppShell({
   open,
   defaultOpen,
   onOpenChange,
-  className
+  className,
+  ...props
 }: AppShellProps): import("react").JSX.Element;
 type ChatBubbleSide = 'start' | 'end';
 interface ChatBubbleProps {
   children: React.ReactNode;
+  /**
+   * Edge the component is anchored to.
+   *
+   * @defaultValue `start`
+   * @see the component manifest
+   */
   side?: ChatBubbleSide;
   avatar?: React.ReactNode;
   name?: string;
@@ -3245,6 +4371,12 @@ type RadialProgressVariant = 'primary' | 'info' | 'success' | 'warning' | 'error
 interface RadialProgressProps {
   value: number;
   size?: RadialProgressSize;
+  /**
+   * Selects the visual style variant.
+   *
+   * @defaultValue `primary`
+   * @see the component manifest
+   */
   variant?: RadialProgressVariant;
   children?: React.ReactNode;
   'aria-label'?: string;
@@ -3262,6 +4394,12 @@ type SwapMode = 'rotate' | 'flip';
 interface SwapProps {
   on: React.ReactNode;
   off: React.ReactNode;
+  /**
+   * Whether the control is checked (controlled).
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   checked?: boolean;
   /** Called with the new checked state when the swap is toggled. */
   onValueChange?: (checked: boolean) => void;
@@ -3294,9 +4432,19 @@ interface SwipeAction {
 interface SwipeItemProps {
   /** The row content. */
   children: ReactNode;
-  /** Actions revealed by dragging the row toward its end edge (shown on the start edge). */
+  /**
+   * Actions revealed by dragging toward the end edge (shown on the start edge)
+   *
+   * @defaultValue `[]`
+   * @see the component manifest
+   */
   leadingActions?: SwipeAction[];
-  /** Actions revealed by dragging the row toward its start edge (shown on the end edge). */
+  /**
+   * Actions revealed by dragging toward the start edge (shown on the end edge)
+   *
+   * @defaultValue `[]`
+   * @see the component manifest
+   */
   trailingActions?: SwipeAction[];
   className?: string;
 }
@@ -3318,8 +4466,21 @@ type Responsive<T> = T | Partial<Record<'base' | 'sm' | 'md' | 'lg' | 'xl', T>>;
 /** Grid track alignment keyword (maps directly to `align-items` / `justify-items`). */
 type GridAlign = 'start' | 'center' | 'end' | 'stretch';
 interface GridProps extends HTMLAttributes<HTMLDivElement> {
-  /** Column count. A number, or `{ base, sm, md, lg, xl }` for responsive columns. */
+  /**
+   * Column count — a number, or a per-breakpoint object (base/sm/md/lg/xl) for responsive
+   * columns
+   *
+   * @defaultValue `12`
+   * @see the component manifest
+   */
   cols?: Responsive<number>;
+  /**
+   * Spacing token step. Maps to the --cascivo-space-* scale, which intentionally skips
+   * 7/9/11 — use 6 or 8.
+   *
+   * @defaultValue `4`
+   * @see the component manifest
+   */
   gap?: SpaceStep;
   /** Block-axis alignment of items within their cells (`align-items`). Defaults to `stretch`. */
   align?: GridAlign;
@@ -3347,10 +4508,30 @@ declare function GridItem({
   ...props
 }: GridItemProps): import("react").JSX.Element;
 interface FlexProps extends HTMLAttributes<HTMLDivElement> {
+  /**
+   * Flex direction. ⚠ Defaults to `vertical`, unlike CSS `flex-direction` (and unlike
+   * Chakra/MUI/Radix `Flex`, which default to a row) — `<Flex justify="between">` alone
+   * produces a centered vertical stack.
+   *
+   * @defaultValue `vertical`
+   * @see the component manifest
+   */
   direction?: 'vertical' | 'horizontal';
+  /**
+   * Spacing token step
+   *
+   * @defaultValue `4`
+   * @see the component manifest
+   */
   gap?: SpaceStep;
   align?: 'start' | 'center' | 'end' | 'stretch';
   justify?: 'start' | 'center' | 'end' | 'between';
+  /**
+   * Allow wrapping
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   wrap?: boolean;
 }
 declare function Flex({
@@ -3364,7 +4545,19 @@ declare function Flex({
   ...props
 }: FlexProps): import("react").JSX.Element;
 interface ColumnsProps extends HTMLAttributes<HTMLDivElement> {
+  /**
+   * Number of equal columns
+   *
+   * @defaultValue `2`
+   * @see the component manifest
+   */
   count?: 2 | 3 | 4;
+  /**
+   * Spacing token step
+   *
+   * @defaultValue `4`
+   * @see the component manifest
+   */
   gap?: SpaceStep;
 }
 declare function Columns({
@@ -3376,6 +4569,12 @@ declare function Columns({
   ...props
 }: ColumnsProps): import("react").JSX.Element;
 interface CenterProps extends HTMLAttributes<HTMLDivElement> {
+  /**
+   * CSS max-width value
+   *
+   * @defaultValue `48rem`
+   * @see the component manifest
+   */
   maxWidth?: string;
 }
 declare function Center({
@@ -3385,6 +4584,12 @@ declare function Center({
   ...props
 }: CenterProps): import("react").JSX.Element;
 interface SpacerProps extends HTMLAttributes<HTMLDivElement> {
+  /**
+   * Spacing token step
+   *
+   * @defaultValue `4`
+   * @see the component manifest
+   */
   size?: SpaceStep;
 }
 declare function Spacer({
@@ -3394,8 +4599,20 @@ declare function Spacer({
   ...props
 }: SpacerProps): import("react").JSX.Element;
 interface AutoGridProps extends HTMLAttributes<HTMLDivElement> {
-  /** Minimum track size before items wrap to fewer columns. */
+  /**
+   * Minimum track width before items wrap to fewer columns
+   *
+   * @defaultValue `"16rem"`
+   * @see the component manifest
+   */
   min?: string;
+  /**
+   * Spacing token step. Maps to the --cascivo-space-* scale, which intentionally skips
+   * 7/9/11 — use 6 or 8.
+   *
+   * @defaultValue `4`
+   * @see the component manifest
+   */
   gap?: SpaceStep;
   className?: string | undefined;
 }
@@ -3406,6 +4623,20 @@ declare function AutoGrid({
   style,
   ...props
 }: AutoGridProps): import("react").JSX.Element;
+interface PageHeaderProps {
+  title: string;
+  description?: string;
+  breadcrumb?: ReactNode;
+  actions?: ReactNode;
+  className?: string;
+}
+declare function PageHeader({
+  title,
+  description,
+  breadcrumb,
+  actions,
+  className
+}: PageHeaderProps): import("react").JSX.Element;
 /**
  * Set the active theme imperatively, from anywhere. Persists the choice and
  * drives the `data-theme` attribute through the mounted {@link ThemeProvider}.
@@ -3522,4 +4753,4 @@ declare function themePreloadScript(options?: {
   attribute?: string;
   defaultTheme?: string;
 }): string;
-export { Accordion, AccordionContent, AccordionItem, AccordionItemProps, AccordionProps, AccordionTrigger, ActionSheet, ActionSheetAction, ActionSheetProps, Alert, AlertDialog, AlertDialogLabels, AlertDialogProps, AlertProps, AppShell, AppShellProps, AspectRatio, AspectRatioProps, AutoGrid, AutoGridProps, Avatar, AvatarGroup, AvatarGroupLabels, AvatarGroupProps, AvatarProps, Badge, BadgeProps, Blockquote, BlockquoteProps, BottomSheet, BottomSheetProps, Breadcrumb, BreadcrumbItem, BreadcrumbProps, Button, ButtonGroup, ButtonGroupProps, ButtonProps, Calendar, CalendarLabels, CalendarProps, Card, CardContent, CardContentProps, CardFooter, CardFooterProps, CardHeader, CardHeaderProps, CardProps, CardTitle, CardTitleProps, Carousel, CarouselLabels, CarouselProps, Center, CenterProps, ChatBubble, ChatBubbleProps, ChatBubbleSide, Checkbox, CheckboxCard, CheckboxCardProps, CheckboxProps, Code, type CodeLang, CodeProps, CodeSnippet, CodeSnippetProps, Collapsible, CollapsibleProps, ColorPicker, ColorPickerLabels, ColorPickerProps, Column, Columns, ColumnsProps, Combobox, ComboboxLabels, ComboboxOption, ComboboxProps, CommandAction, CommandGroup, CommandItem, CommandMenu, CommandMenuProps, CommandPage, CommandScope, CommandStatus, Comparison, ComparisonProps, ContainedList, ContainedListItem, ContainedListItemProps, ContainedListProps, ContextMenu, ContextMenuItem, ContextMenuItemProps, ContextMenuProps, CopyButton, CopyButtonProps, DataList, DataListItem, DataListProps, DataTable, DataTableLabels, DataTableProps, DatePicker, DatePickerLabels, DatePickerProps, DateRange, DateRangePicker, DateRangePickerLabels, DateRangePickerProps, DateRangePreset, Dock, DockItem, DockProps, Drawer, DrawerProps, Dropdown, DropdownItem, DropdownProps, Editable, EditableProps, EmptyState, EmptyStateProps, ErrorBoundary, Fab, FabAction, FabProps, Field, FieldProps, FileUploader, FileUploaderLabels, FileUploaderProps, Filter, FilterOption, FilterProps, FilterVariant, Flex, FlexProps, FocusScope, Form, FormConfig, FormProps, FormStore, FuzzyMatch, Grid, GridAlign, GridItem, GridItemProps, GridProps, Header, HeaderLabels, HeaderLink, HeaderPanel, HeaderPanelLabels, HeaderPanelProps, HeaderProps, Heading, HeadingLevel, HeadingProps, HeadingSize, HoverCard, HoverCardContent, HoverCardContentProps, HoverCardProps, HoverCardTrigger, HoverCardTriggerProps, IconButton, IconButtonProps, Image, ImageProps, Indicator, IndicatorPlacement, IndicatorProps, InlineLoading, InlineLoadingProps, InlineLoadingStatus, Input, InputGroup, InputGroupAddon, type InputGroupAddonProps, type InputGroupProps, InputProps, Item, ItemActions, ItemActionsProps, ItemContent, ItemContentProps, ItemDescription, ItemDescriptionProps, ItemMedia, ItemMediaProps, ItemProps, ItemTitle, ItemTitleProps, Join, JoinOrientation, JoinProps, Kbd, KbdProps, Label, LabelProps, Link, type LinkComponent, type LinkComponentProps, LinkProps, List, ListItem, ListItemProps, ListProps, LogLevel, LogLine, LogViewer, LogViewerLabels, LogViewerProps, Menu, MenuButton, MenuButtonItem, MenuButtonProps, MenuItem, MenuItemProps, MenuProps, MenuSeparator, MenuTrigger, MenuTriggerProps, Menubar, MenubarItem, MenubarMenu, MenubarProps, Modal, ModalProps, MultiSelect, MultiSelectLabels, MultiSelectOption, MultiSelectProps, NativeSelect, NativeSelectOption, NativeSelectProps, NavigationMenu, NavigationMenuItem, NavigationMenuProps, Notification, NotificationProps, NotificationVariant, NumberInput, NumberInputProps, OtpInput, OtpInputProps, OverflowMenu, OverflowMenuItem, OverflowMenuProps, Pagination, PaginationLabels, PaginationProps, PasswordInput, PasswordInputLabels, PasswordInputProps, Popover, PopoverContent, PopoverContentProps, PopoverProps, PopoverTrigger, PopoverTriggerProps, Portal, Progress, ProgressBar, ProgressBarProps, ProgressCircle, ProgressCircleProps, ProgressIndicator, ProgressIndicatorProps, ProgressProps, ProgressSize, ProgressStep, ProgressVariant, Prose, ProseProps, PullToRefresh, PullToRefreshProps, QrCode, QrCodeProps, RadialProgress, RadialProgressProps, RadialProgressSize, RadialProgressVariant, Radio, RadioCard, RadioCardGroup, RadioCardGroupProps, RadioCardProps, RadioGroup, RadioGroupProps, RadioProps, RatingGroup, RatingGroupLabels, RatingGroupProps, RelativeTime, RelativeTimeProps, Resizable, ResizableProps, Responsive, ScrollArea, ScrollAreaProps, Search, SearchProps, SegmentedControl, SegmentedControlOption, SegmentedControlProps, Select, SelectOption, SelectProps, Separator, SeparatorProps, Sheet, SheetProps, ShellHeader, ShellHeaderAction, ShellHeaderBrand, ShellHeaderLabels, ShellHeaderNavItem, ShellHeaderNavLink, ShellHeaderNavMenu, ShellHeaderNavMenuItem, ShellHeaderProps, SideNav, SideNavGroup, SideNavItem, SideNavLinkProps, SideNavLinkSubItem, SideNavProps, SideNavSubItem, SideNavTone, Skeleton, SkeletonProps, SkipNavLink, SkipNavLinkProps, SkipNavTarget, SkipNavTargetProps, Slider, SliderProps, SortDirection, SortState, Spacer, SpacerProps, Spinner, SpinnerProps, Stack, StackProps, type StandardSchemaV1, Stat, StatProps, Status, StatusProps, Step, StepState, Steps, StepsProps, StructuredList, StructuredListItem, StructuredListProps, SuspenseBoundary, Swap, SwapMode, SwapProps, SwipeAction, SwipeItem, SwipeItemProps, Switcher, SwitcherEntry, SwitcherLink, SwitcherProps, Tabs, TabsContent, TabsContentProps, TabsList, TabsProps, TabsTrigger, TabsTriggerProps, Tag, TagProps, TagsInput, TagsInputProps, Text, TextProps, Textarea, TextareaProps, ThemeProvider, type ThemeProviderProps, Tile, TileProps, TimePicker, TimePickerProps, Timeline, TimelineItem, TimelineProps, ToastOptions, ToastProvider, ToastVariant, Toc, TocItem, TocProps, Toggle, ToggleGroup, ToggleGroupItem, ToggleGroupProps, ToggleProps, Toggletip, ToggletipPlacement, ToggletipProps, Tooltip, TooltipProps, TreeNode, TreeView, TreeViewProps, UploaderFile, type UsePopoverOptions, type UsePopoverReturn, type UseTocFromRegionOptions, User, UserProps, VisuallyHidden, VisuallyHiddenProps, createForm, dismissAllToasts, fuzzyMatch, fuzzyScore, getLinkComponent, setLinkComponent, setTheme, themePreloadScript, themeSignal, treeViewMessages, useForm, usePopover, useTheme, useToast, useTocFromRegion };
+export { Accordion, AccordionContent, AccordionItem, AccordionItemProps, AccordionProps, AccordionTrigger, ActionSheet, ActionSheetAction, ActionSheetProps, Alert, AlertDialog, AlertDialogLabels, AlertDialogProps, AlertProps, AppShell, AppShellProps, AspectRatio, AspectRatioProps, AutoGrid, AutoGridProps, Avatar, AvatarGroup, AvatarGroupLabels, AvatarGroupProps, AvatarProps, Badge, BadgeProps, Blockquote, BlockquoteProps, BottomSheet, BottomSheetProps, Breadcrumb, BreadcrumbItem, BreadcrumbProps, Button, ButtonGroup, ButtonGroupProps, ButtonProps, Calendar, CalendarLabels, CalendarProps, Card, CardContent, CardContentProps, CardFooter, CardFooterProps, CardHeader, CardHeaderProps, CardProps, CardTitle, CardTitleProps, Carousel, CarouselLabels, CarouselProps, Center, CenterProps, ChatBubble, ChatBubbleProps, ChatBubbleSide, Checkbox, CheckboxCard, CheckboxCardProps, CheckboxProps, Code, type CodeLang, CodeProps, CodeSnippet, CodeSnippetProps, Collapsible, CollapsibleProps, ColorPicker, ColorPickerLabels, ColorPickerProps, Column, Columns, ColumnsProps, Combobox, ComboboxLabels, ComboboxOption, ComboboxProps, CommandAction, CommandGroup, CommandItem, CommandMenu, CommandMenuProps, CommandPage, CommandScope, CommandStatus, Comparison, ComparisonProps, ContainedList, ContainedListItem, ContainedListItemProps, ContainedListProps, ContextMenu, ContextMenuItem, ContextMenuItemProps, ContextMenuProps, CopyButton, CopyButtonProps, DataList, DataListItem, DataListProps, DataTable, DataTableLabels, DataTableProps, DatePicker, DatePickerLabels, DatePickerProps, DateRange, DateRangePicker, DateRangePickerLabels, DateRangePickerProps, DateRangePreset, DismissableLayer, type DismissableLayerProps, Dock, DockItem, DockProps, Drawer, DrawerProps, Dropdown, DropdownItem, DropdownProps, Editable, EditableProps, EmptyState, EmptyStateProps, ErrorBoundary, Fab, FabAction, FabProps, Field, FieldProps, FileUploader, FileUploaderLabels, FileUploaderProps, Filter, FilterOption, FilterProps, FilterVariant, Flex, FlexProps, FocusScope, Form, FormConfig, FormProps, FormStore, FuzzyMatch, Grid, GridAlign, GridItem, GridItemProps, GridProps, Header, HeaderLabels, HeaderLink, HeaderPanel, HeaderPanelLabels, HeaderPanelProps, HeaderProps, Heading, HeadingLevel, HeadingProps, HeadingSize, HoverCard, HoverCardContent, HoverCardContentProps, HoverCardProps, HoverCardTrigger, HoverCardTriggerProps, IconButton, IconButtonProps, Image, ImageProps, Indicator, IndicatorPlacement, IndicatorProps, InlineLoading, InlineLoadingProps, InlineLoadingStatus, Input, InputGroup, InputGroupAddon, type InputGroupAddonProps, type InputGroupProps, InputProps, Item, ItemActions, ItemActionsProps, ItemContent, ItemContentProps, ItemDescription, ItemDescriptionProps, ItemMedia, ItemMediaProps, ItemProps, ItemTitle, ItemTitleProps, Join, JoinOrientation, JoinProps, Kbd, KbdProps, Label, LabelProps, Link, type LinkComponent, type LinkComponentProps, LinkProps, List, ListItem, ListItemProps, ListProps, LogLevel, LogLine, LogViewer, LogViewerLabels, LogViewerProps, type Machine, type MachineConfig, Menu, MenuButton, MenuButtonItem, MenuButtonProps, MenuItem, MenuItemProps, MenuProps, MenuSeparator, MenuTrigger, MenuTriggerProps, Menubar, MenubarItem, MenubarMenu, MenubarProps, Modal, ModalProps, MultiSelect, MultiSelectLabels, MultiSelectOption, MultiSelectProps, NativeSelect, NativeSelectOption, NativeSelectProps, NavigationMenu, NavigationMenuItem, NavigationMenuProps, Notification, NotificationProps, NotificationVariant, NumberInput, NumberInputProps, OtpInput, OtpInputProps, OverflowMenu, OverflowMenuItem, OverflowMenuProps, PageHeader, PageHeaderProps, Pagination, PaginationLabels, PaginationProps, PasswordInput, PasswordInputLabels, PasswordInputProps, Popover, PopoverContent, PopoverContentProps, PopoverProps, PopoverTrigger, PopoverTriggerProps, Portal, Presence, Progress, ProgressBar, ProgressBarProps, ProgressCircle, ProgressCircleProps, ProgressIndicator, ProgressIndicatorProps, ProgressProps, ProgressSize, ProgressStep, ProgressVariant, Prose, ProseProps, PullToRefresh, PullToRefreshProps, QrCode, QrCodeProps, RadialProgress, RadialProgressProps, RadialProgressSize, RadialProgressVariant, Radio, RadioCard, RadioCardGroup, RadioCardGroupProps, RadioCardProps, RadioGroup, RadioGroupProps, RadioProps, RatingGroup, RatingGroupLabels, RatingGroupProps, RelativeTime, RelativeTimeProps, Resizable, ResizableProps, Responsive, ScrollArea, ScrollAreaProps, Search, SearchProps, SegmentedControl, SegmentedControlOption, SegmentedControlProps, Select, SelectOption, SelectProps, Separator, SeparatorProps, Sheet, SheetProps, ShellHeader, ShellHeaderAction, ShellHeaderBrand, ShellHeaderLabels, ShellHeaderNavItem, ShellHeaderNavLink, ShellHeaderNavMenu, ShellHeaderNavMenuItem, ShellHeaderProps, SideNav, SideNavGroup, SideNavItem, SideNavLinkProps, SideNavLinkSubItem, SideNavProps, SideNavSubItem, SideNavTone, Skeleton, SkeletonProps, SkipNavLink, SkipNavLinkProps, SkipNavTarget, SkipNavTargetProps, Slider, SliderProps, Slot, type SlotProps, SortDirection, SortState, Spacer, SpacerProps, Spinner, SpinnerProps, Stack, StackProps, type StandardSchemaV1, Stat, StatProps, Status, StatusProps, Step, StepState, Steps, StepsProps, StructuredList, StructuredListItem, StructuredListProps, SuspenseBoundary, Swap, SwapMode, SwapProps, SwipeAction, SwipeItem, SwipeItemProps, Switcher, SwitcherEntry, SwitcherLink, SwitcherProps, Tabs, TabsContent, TabsContentProps, TabsList, TabsProps, TabsTrigger, TabsTriggerProps, Tag, TagProps, TagsInput, TagsInputProps, Text, TextProps, Textarea, TextareaProps, ThemeProvider, type ThemeProviderProps, Tile, TileProps, TimePicker, TimePickerProps, Timeline, TimelineItem, TimelineProps, ToastOptions, ToastProvider, ToastVariant, Toc, TocItem, TocProps, Toggle, ToggleGroup, ToggleGroupItem, ToggleGroupProps, ToggleProps, Toggletip, ToggletipPlacement, ToggletipProps, Tooltip, TooltipProps, TreeNode, TreeView, TreeViewProps, UploaderFile, type UseClipboardOptions, type UseClipboardReturn, type UseControllableSignalOptions, type UseDisclosureOptions, type UseDisclosureReturn, type UsePopoverOptions, type UsePopoverReturn, type UseTocFromRegionOptions, User, UserProps, VisuallyHidden, VisuallyHiddenProps, batch, cn, composeRefs, computePosition, computed, createForm, createMachine, createScope, createStreamBuffer, dismissAllToasts, effect, fuzzyMatch, fuzzyScore, getLinkComponent, mergeProps, setLinkComponent, setTheme, signal, themePreloadScript, themeSignal, treeViewMessages, useAnchorPosition, useClipboard, useComputed, useControllableSignal, useDisclosure, useEffectPropSignal, useForm, useId, useMachine, useMediaQuery, usePopover, useRovingFocus, useScope, useScrollLock, useSignal, useSignalEffect, useSignals, useStreamBuffer, useTheme, useToast, useTocFromRegion, useTypeahead };