@cascivo/react 1.1.0 → 1.2.0

package/dist/index.d.ts

@@ -1332,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[];
@@ -1387,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({
@@ -1760,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;
   /**
@@ -3544,6 +3563,18 @@ 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.
    *
@@ -3558,6 +3589,8 @@ declare function SegmentedControl({
   onValueChange,
   size,
   disabled,
+  ariaLabel,
+  label,
   className,
   ...props
 }: SegmentedControlProps): import("react").JSX.Element;
@@ -4185,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;
@@ -4229,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;
 }
 /**
@@ -4246,6 +4300,7 @@ declare function LogViewer({
   ansi,
   search,
   maxHeight,
+  timestampWidth,
   labels,
   className,
   ...props
@@ -5071,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.
    *
@@ -5099,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,
@@ -5106,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;
@@ -6468,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
@@ -6687,7 +6832,9 @@ export {
   CopyButton,
   CopyButtonProps,
   DataList,
+  DataListEntry,
   DataListItem,
+  DataListItemProps,
   DataListProps,
   DataTable,
   DataTableLabels,
@@ -6731,6 +6878,9 @@ export {
   FilterProps,
   FilterVariant,
   Flex,
+  FlexItem,
+  FlexItemProps,
+  FlexItemSize,
   FlexProps,
   FocusScope,
   Form,
@@ -6941,6 +7091,7 @@ export {
   SideNavLinkProps,
   SideNavLinkSubItem,
   SideNavProps,
+  SideNavSlotContext,
   SideNavSubItem,
   SideNavTone,
   Skeleton,
@@ -7093,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;
+// }
+//