@xoroh/axis 0.0.0-stage → 0.1.0

package/dist/models-DM_HxYGZ.d.cts

@@ -0,0 +1,1890 @@
+import { ReactElement, ReactNode } from 'react';
+
+/**
+ * Accessibility plumbing — visually-hidden styling, stable ids, direction.
+ *
+ * ## Why this is a primitive
+ *
+ * Every labelled surface needs three things that have nothing to do with how
+ * it looks: a way to hide content visually while keeping it announced
+ * (icon-only labels, descriptions), a stable id to link triggers to surfaces,
+ * and a text direction both renderers agree on. Both renderers hand-roll all
+ * three today with independent implementations.
+ *
+ * ## What is genuinely shared, and what is not — stated carefully
+ *
+ * The VALUES are shared: the visually-hidden declaration is fixed CSS-in-JS
+ * (not a token read — it names no colour, spacing, shape or type value), the
+ * id algorithm is a prefixed counter, and direction resolution is a pure
+ * fallback. The APPLICATION is not — web spreads the style object onto an
+ * element, native maps it onto its own hidden-text host.
+ */
+type A11yDir = "ltr" | "rtl" | "auto";
+type IdScope = {
+    /** Next stable id in this scope: `prefix` + `-` + a 1-based counter. */
+    nextId(): string;
+    prefix: string;
+};
+/**
+ * Create an id scope. Counters are per-scope so two scopes never collide, and
+ * 1-based so the first id reads `prefix-1`, never `prefix-0`.
+ */
+declare function createIdScope(prefix: string): IdScope;
+/**
+ * Resolve text direction: the explicit `dir` wins, else the host default,
+ * else `"ltr"`. Never returns `undefined` — a renderer branching on direction
+ * must always have an answer.
+ */
+declare function resolveDir(options?: {
+    dir?: A11yDir;
+    defaultDir?: A11yDir;
+}): A11yDir;
+
+/**
+ * The attachments model — picked files with upload progress and
+ * composer limits.
+ *
+ * ## Why this is a primitive
+ *
+ * The composer on both renderers tracks the same list: picked files
+ * awaiting or completing upload, each with an id, a size, and a
+ * transfer phase, bounded by the same limits (at most N files, at
+ * most M bytes each). If the web side caps at ten files while native
+ * caps at five, the same conversation refuses the same photo per
+ * renderer — a limit is behavior, and behavior belongs here once.
+ *
+ * ## What is genuinely shared, and what is not
+ *
+ * The LIST and the LIMITS are shared: add/remove/update/clear over
+ * `{id, name, size, mimeType, uri, state}`, with `maxFiles` /
+ * `maxFileSize` validation reporting a typed error the caller
+ * surfaces. The PICKING and the UPLOAD are not — image pickers,
+ * drag-drop, paste, and the async transfer are platform code the app
+ * owns; the app marks uploads finished through `update`. Rendering
+ * (chips, previews, progress bars) is styled composition in Kern.
+ */
+/**
+ * One file's transfer phase, mirroring the channel-SDK shape both
+ * native chat lists already use: accepted and moving, moved, or moved
+ * and acknowledged by the transport.
+ */
+type AttachmentState = "uploading" | "finished" | "uploaded";
+/** One picked file in the composer. `size` is bytes; `uri` is local. */
+type ChatAttachment = {
+    /** Stable identity, used as the list key. */
+    id: string;
+    /** Display name with extension. */
+    name: string;
+    /** Byte size, when the picker reported one. */
+    size?: number;
+    /** MIME type, when the picker reported one. */
+    mimeType?: string;
+    /** Local URI for previews; remote URL only after upload. */
+    uri?: string;
+    state: AttachmentState;
+};
+/** Composer limits. Both optional; absent means unbounded. */
+type AttachmentLimits = {
+    /** Maximum attachments held at once. */
+    maxFiles?: number;
+    /** Maximum bytes per attachment. */
+    maxFileSize?: number;
+};
+/** Why a candidate was refused. The caller surfaces this, never a throw. */
+type AttachmentError = "too-many" | "too-large" | "duplicate";
+/**
+ * Whether `candidate` may join `current` under `limits`: duplicate
+ * ids, the per-file byte cap, and the list cap, in that order — a
+ * file that is both a duplicate and oversized reports `duplicate`,
+ * the identity problem first.
+ */
+declare function validateAttachment(current: readonly ChatAttachment[], candidate: Pick<ChatAttachment, "id" | "size">, limits?: AttachmentLimits): AttachmentError | null;
+/** Apply a patch to one attachment by id; unknown ids leave the list alone. */
+declare function updateAttachment(current: readonly ChatAttachment[], id: string, patch: Partial<Pick<ChatAttachment, "state" | "uri" | "name">>): ChatAttachment[];
+/**
+ * The composer attachment list, controlled or uncontrolled. `add`
+ * validates first: refused candidates report through `onError` and
+ * never enter the list. Accepted candidates enter as `uploading`
+ * unless the caller states otherwise (a synchronously-available file
+ * reports `finished` at add time); the app moves them on through
+ * `update` as its transfer progresses. `remove` by id is a no-op for
+ * unknown ids.
+ */
+declare function useAttachments(options?: {
+    value?: readonly ChatAttachment[];
+    defaultValue?: readonly ChatAttachment[];
+    onChange?: (next: readonly ChatAttachment[]) => void;
+    maxFiles?: number;
+    maxFileSize?: number;
+    onError?: (error: AttachmentError, candidate: ChatAttachment) => void;
+}): {
+    attachments: readonly ChatAttachment[];
+    add: (candidate: ChatAttachment) => void;
+    addMany: (candidates: readonly ChatAttachment[]) => void;
+    update: (id: string, patch: Partial<Pick<ChatAttachment, "state" | "uri" | "name">>) => void;
+    remove: (id: string) => void;
+    clear: () => void;
+};
+
+/**
+ * Calendar behavior — month-grid date logic as pure functions.
+ *
+ * No React, no React Native: month-grid generation, roving-focus key
+ * mapping, min/max + `isDateDisabled`, single + range selection,
+ * locale weekday names, `firstDayOfWeek`, and `dir` live here. Moved
+ * from the removed `Calendar` component (ADR-012) without rewriting
+ * the date math — state ownership (controlled/uncontrolled value and
+ * month) stays with consumers via `useControllableState`.
+ *
+ * Date math uses plain `Date` UTC construction only
+ * (`new Date(Date.UTC(y, m, d))`; no date library). Nothing here
+ * throws on caller input: invalid strings parse to `null`, invalid
+ * month keys build an empty grid.
+ */
+type CalendarDateParts = {
+    year: number;
+    monthIndex: number;
+    day: number;
+};
+type CalendarMonthParts = {
+    year: number;
+    monthIndex: number;
+};
+/** 0 = Sunday … 6 = Saturday (matches `getUTCDay`). */
+type FirstDayOfWeek = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+/** Month-name length for `resolveCalendarMonthNames`. */
+type CalendarMonthNameStyle = "long" | "short" | "narrow";
+type CalendarDirection = "ltr" | "rtl";
+type CalendarSelectionMode = "single" | "range";
+/** Inclusive range, ordered (`start <= end`). `null` for none. */
+type CalendarRange = {
+    start: string;
+    end: string;
+} | null;
+type CalendarRangePosition = "start" | "end" | "inside" | null;
+type CalendarCell = {
+    /** ISO `yyyy-mm-dd`. */
+    iso: string;
+    /** Day of month. */
+    day: number;
+    disabled: boolean;
+    selected: boolean;
+    range: CalendarRangePosition;
+};
+type CalendarGrid = {
+    /** Week rows of seven: day cells with `null` leading/trailing blanks. */
+    weeks: Array<Array<CalendarCell | null>>;
+    /** Seven weekday names, rotated to `firstDayOfWeek`. */
+    weekdayNames: string[];
+};
+type CalendarKey = "ArrowLeft" | "ArrowRight" | "ArrowUp" | "ArrowDown" | "Home" | "End" | "PageUp" | "PageDown";
+type CalendarGridOptions = {
+    /** 0 = Sunday … 6 = Saturday. Default `0` (the removed component's grid). */
+    firstDayOfWeek?: FirstDayOfWeek;
+    /** BCP 47 locale for weekday names. Default `"en-US"`. */
+    locale?: string;
+    /** Earliest selectable date (ISO). Earlier days are disabled. */
+    minDate?: string;
+    /** Latest selectable date (ISO). Later days are disabled. */
+    maxDate?: string;
+    /** Extra per-day disable predicate. */
+    isDateDisabled?: (iso: string) => boolean;
+    /** Whole-grid terminal flag. Default `false`. */
+    disabled?: boolean;
+    /** Selected date (ISO) for single mode. */
+    selected?: string | null;
+    /** Active range for range mode. */
+    range?: CalendarRange;
+};
+/**
+ * Strict ISO date parse with a UTC round-trip guard (`2026-02-30`
+ * constructs to March, so the mismatch rejects it). Returns `null`
+ * for anything invalid — never throws.
+ */
+declare function parseCalendarDate(value: string | null | undefined): CalendarDateParts | null;
+/** Strict month-key parse. Returns `null` for anything invalid — never throws. */
+declare function parseCalendarMonth(value: string | null | undefined): CalendarMonthParts | null;
+declare function toCalendarDate(year: number, monthIndex: number, day: number): string;
+declare function toCalendarMonth(year: number, monthIndex: number): string;
+/** Month length via UTC overflow: day 0 of the next month is the last day of this one. */
+declare function daysInCalendarMonth(year: number, monthIndex: number): number;
+/** Month arithmetic without date construction — plain year/month rollover. */
+declare function shiftCalendarMonth(year: number, monthIndex: number, delta: 1 | -1): CalendarMonthParts;
+/** Leading blanks before the 1st, rotated to `firstDayOfWeek`. */
+declare function leadingBlankCount(year: number, monthIndex: number, firstDayOfWeek?: FirstDayOfWeek): number;
+/**
+ * Seven short weekday names starting at `firstDayOfWeek`, via `Intl`
+ * (`short` weekday over a known Sunday-start week). Falls back to the
+ * Sunday-first `Su…Sa` labels when `Intl` is unavailable — never throws.
+ */
+declare function resolveCalendarWeekdayNames(locale?: string, firstDayOfWeek?: FirstDayOfWeek): string[];
+/**
+ * Twelve month names for a locale, in calendar order.
+ * Formatted at UTC noon mid-month so neither DST edges nor month ends
+ * can shift the read. Falls back to English on missing `Intl` —
+ * never throws.
+ */
+declare function resolveCalendarMonthNames(locale?: string, style?: CalendarMonthNameStyle): string[];
+/**
+ * Locale-aware week start (0 = Sunday … 6 = Saturday).
+ *
+ * An explicit Unicode `-u-fw-` extension wins over everything else.
+ * Otherwise prefers live `Intl.Locale` week info — `getWeekInfo()` or
+ * the `weekInfo` property when either exists (`firstDay` numbers days
+ * 1 = Monday … 7 = Sunday). Otherwise falls back to an embedded
+ * region table (CLDR supplemental weekData, firstDay only):
+ * Saturday-start and Friday-start regions are listed; the listed
+ * Sunday-start regions return 0; every other or unknown region
+ * returns 1 (Monday, the CLDR `001` root default). The region resolves
+ * via `Intl.Locale.maximize()` when available, then a bare-language
+ * likely-region map (CLDR likelySubtags), then a plain BCP-47 subtag
+ * parse as the last resort. Never throws.
+ */
+declare function resolveLocaleFirstDay(locale?: string): FirstDayOfWeek;
+/**
+ * Whether an ISO date is unselectable: whole-grid `disabled`, outside
+ * `[minDate, maxDate]`, or rejected by `isDateDisabled`. Invalid bounds
+ * are ignored (never throw on caller input).
+ */
+declare function isCalendarDateDisabled(iso: string, options?: Pick<CalendarGridOptions, "minDate" | "maxDate" | "isDateDisabled" | "disabled">): boolean;
+/**
+ * Month grid for a month key: week rows of seven with `null` leading
+ * blanks, day cells carrying selection, range, and disabled state.
+ * An invalid month key builds an empty grid — never throws.
+ */
+declare function buildCalendarGrid(monthKey: string, options?: CalendarGridOptions): CalendarGrid;
+/**
+ * Roving-focus key mapping: the next focused ISO date for a grid key.
+ * Arrows move within the week (`±1`) and across rows (`±7`), crossing
+ * month (and year) boundaries through DST-safe UTC arithmetic — no
+ * clamping at month ends, so grids that paint outside days stay
+ * reachable. `dir` swaps Left/Right. Home/End jump to the visual row
+ * edges and stay grid-local (clamped to the visible month).
+ * PageUp/PageDown move the same day across months (clamped to the
+ * month length). Returns `null` for invalid input — never throws.
+ */
+declare function resolveCalendarFocus(currentISO: string | null | undefined, key: CalendarKey, options?: {
+    firstDayOfWeek?: FirstDayOfWeek;
+    dir?: CalendarDirection;
+}): string | null;
+type CalendarSelection = {
+    /** Single-mode value (and the latest tapped date in range mode). */
+    value: string | null;
+    /** Range-mode range (`null` until two taps complete it). */
+    range: CalendarRange;
+};
+/**
+ * Selection resolution for a tapped ISO date. Single mode selects it.
+ * Range mode: the first tap anchors `start`, the second tap completes
+ * the ordered range, a tap with a complete range re-anchors. A tap on a
+ * disabled date is a no-op (`null`) — never throws.
+ */
+declare function resolveCalendarSelection(iso: string, options?: {
+    mode?: CalendarSelectionMode;
+    value?: string | null;
+    range?: CalendarRange;
+} & Pick<CalendarGridOptions, "minDate" | "maxDate" | "isDateDisabled" | "disabled">): CalendarSelection | null;
+
+/**
+ * The branch model — the edit-and-retry pager over answer variants.
+ *
+ * ## Why this is a primitive
+ *
+ * Regenerating or editing resubmits a turn and leaves several answers
+ * where one was; the pager (`< 1/2 >`) on both renderers walks the
+ * same index over the same count. If the web side wraps around while
+ * native clamps, the same Next press lands on different answers per
+ * renderer — pager motion is behavior, and behavior belongs here once.
+ *
+ * ## What is genuinely shared, and what is not
+ *
+ * The INDEX is shared: normalise, step, stop-at-the-ends, and the
+ * hide-when-single rule, following the `selection`-model precedent
+ * (pure transitions plus a controlled/uncontrolled hook). The TREE is
+ * not — persisted message trees stay transport-owned; this models the
+ * local pager over `count` variants, the cheap v1 the research
+ * recommends until a consumer proves it needs more.
+ */
+/** Clamp `index` into `0..count-1`; an empty branch has index `0`. */
+declare function normalizeBranchIndex(index: number, count: number): number;
+/** Step forward, stopping at the last variant: Next on the last is a no-op. */
+declare function nextBranchIndex(index: number, count: number): number;
+/** Step back, stopping at the first variant: Previous on the first is a no-op. */
+declare function previousBranchIndex(index: number, count: number): number;
+/**
+ * Whether the pager hides: a single variant has nowhere to step, and
+ * callers hide it by default (opt out only for a pager that reserves
+ * layout while variants load).
+ */
+declare function shouldHideBranchPicker(count: number, hideWhenSingleBranch?: boolean): boolean;
+/**
+ * The pager index, controlled or uncontrolled. `count` changes
+ * normalise immediately rather than waiting for a press: a variant
+ * list that shrinks below the shown index falls back to the last
+ * remaining variant, so the pager never points past its own list
+ * (the `useSelection` narrowing precedent).
+ */
+declare function useBranch(options: {
+    count: number;
+    value?: number;
+    defaultValue?: number;
+    onChange?: (index: number) => void;
+}): {
+    index: number;
+    count: number;
+    previous: () => void;
+    next: () => void;
+    goTo: (index: number) => void;
+};
+
+/**
+ * The message model — identity, role, and the accessible name.
+ *
+ * ## Why this is a primitive
+ *
+ * Every renderer draws the same distinction: the reader's own turns
+ * (end-aligned bubble) versus everyone else's (full-width row), and a
+ * screen reader must announce whose turn each one is. If the web side
+ * labels "You" while native labels the raw user id, the same
+ * conversation reads differently per renderer for the users who can
+ * least afford the ambiguity.
+ *
+ * ## What is genuinely shared, and what is not
+ *
+ * The SHAPE and the NAME are shared: the role vocabulary, the message
+ * identity, and the speaker label both renderers announce. The LAYOUT
+ * is not — bubbles, rows, grouping, and markdown rendering are styled
+ * composition in Kern (there is no markdown renderer here by design:
+ * renderer/highlighter dependencies would break the token-free,
+ * platform-neutral boundary). Message PARTS (text/image/reasoning/
+ * tool-call part trees) are transport-owned and stay out: this model
+ * names the turn, never its payload.
+ */
+/** Whose turn a message is. `tool` is a tool result rendered as a turn. */
+type ChatRole = "user" | "assistant" | "system" | "tool";
+/** The identity of one conversation turn. Payload stays transport-owned. */
+type ChatMessage = {
+    /** Stable turn identity, used as the list key. */
+    id: string;
+    role: ChatRole;
+    /** Milliseconds since epoch; ordering aid only, never rendered here. */
+    createdAt?: number;
+};
+/**
+ * The announced speaker for a role: the explicit author name wins
+ * (a named agent, a display name), else the role's plain-language
+ * fallback. Never returns `""` — a renderer branching on the speaker
+ * must always have an answer.
+ */
+declare function resolveChatMessageSpeaker(options: {
+    role: ChatRole;
+    authorName?: string;
+}): string;
+/**
+ * The accessible name for a turn: `Speaker: text`, or the bare
+ * speaker when there is no plain-text preview (a turn carrying only
+ * tool calls or attachments has nothing quotable — the speaker alone
+ * is the honest label, never an empty string or a placeholder).
+ */
+declare function resolveChatMessageLabel(options: {
+    role: ChatRole;
+    authorName?: string;
+    text?: string;
+}): string;
+/** Whether the turn is the reader's own (end-aligned bubble side). */
+declare function isUserMessage(message: Pick<ChatMessage, "role">): boolean;
+
+/**
+ * The source model — cited references behind a citation chip.
+ *
+ * ## Why this is a primitive
+ *
+ * Tool and web-search rows on both renderers cite the same
+ * references: an `href` with an optional human title. The shared part
+ * is deliberately thin — a shape plus list hygiene — because
+ * everything visual (chips, cards, footnotes, inline citations) is
+ * styled composition in Kern. Thin is not nothing: without the shared
+ * dedupe rule, the same URL cited twice renders two chips on one
+ * renderer and one on the other.
+ *
+ * ## What is genuinely shared, and what is not
+ *
+ * The SHAPE and the HYGIENE are shared: `{href, title?}`,
+ * whitespace trimming, empty-href dropping, and first-wins dedupe by
+ * `href`. The FETCHING is not — resolving, opening, and previewing
+ * sources are app and platform code.
+ */
+/** One cited reference: where it points, plus what to call it. */
+type ChatSource = {
+    /** Cited URL. The dedupe key; surrounding whitespace is trimmed. */
+    href: string;
+    /** Human title; falls back to the href when absent. */
+    title?: string;
+};
+/**
+ * Clean a source list: trim hrefs, drop empties, dedupe by href with
+ * first-wins (the earliest citation keeps its position and title).
+ * Never throws on `undefined` — a turn with no sources normalises to
+ * `[]`, not a crash.
+ */
+declare function normalizeChatSources(sources: readonly ChatSource[] | undefined): ChatSource[];
+/**
+ * The announced label for a citation: the title when it says
+ * something, else the href. Never returns `""` — a chip the screen
+ * reader cannot name is a silent control.
+ */
+declare function resolveChatSourceLabel(source: ChatSource): string;
+
+/**
+ * The shared generation-status vocabulary for every chat model.
+ *
+ * ## Why this is a primitive
+ *
+ * The composer (send/stop swap), the message list (streaming cursor),
+ * reasoning disclosure (auto-open while streaming), and tool cards
+ * (running vs settled) all branch on the same question: what is the
+ * run doing right now. Four independent spellings of that answer is
+ * how a composer offers Send mid-generation on one renderer and Stop
+ * on the other.
+ *
+ * ## What is genuinely shared, and what is not
+ *
+ * The VOCABULARY is shared: one `ChatStatus` every model reads, so
+ * `usePromptInput`'s send gate and `resolveReasoningOpen`'s auto-open
+ * can never disagree about what "streaming" means. The TRANSPORT is
+ * not — the app brings its own AI SDK / AG-UI / channel client and
+ * maps its status onto this type at the edge. Attachment upload
+ * states (`uploading | finished | uploaded`) stay separate on purpose:
+ * they describe file transfer, not generation, and conflating the two
+ * would gate sending on uploads the transport may handle inline.
+ */
+/**
+ * Where the current run stands. `idle` is the rest state (composer
+ * accepts input); `submitted` is waiting on the transport before the
+ * first token; `streaming` is tokens flowing; `error` is a failed run
+ * the caller may retry from.
+ */
+type ChatStatus = "idle" | "submitted" | "streaming" | "error";
+/** A run is in flight: the composer must offer Stop, never Send. */
+declare function isChatBusy(status: ChatStatus): boolean;
+/** Tokens are flowing now: stream cursors show, reasoning auto-opens. */
+declare function isChatStreaming(status: ChatStatus): boolean;
+/** The last run failed: the composer may offer retry. */
+declare function isChatError(status: ChatStatus): boolean;
+
+/**
+ * The collection model — ordered item identity for filtering and lookup.
+ *
+ * ## Why this is a primitive
+ *
+ * Combobox filtering, menu filtering, and select value-label lookup
+ * all reduce to the same two questions: which registered items match
+ * a query, and what text belongs to a key. Three independent
+ * implementations drift on exactly the edge users feel — whether
+ * `"mango"` matches `" Mango"` — so the same query filters
+ * differently per component.
+ *
+ * ## What is genuinely shared, and what is not
+ *
+ * The REGISTRY and the MATCH are shared: keyed item identity in
+ * registration order, the default case-insensitive substring match,
+ * and the filter/lookup helpers every consumer reads. The PARTS are
+ * not — which components register (select items publish labels,
+ * menu items publish filter text, combobox options are data and
+ * never register) is per-family composition. Keyboard traversal
+ * over the registry (active index, typeahead focus) is NOT here:
+ * the contract's conditional-keyboard rule admits it only where a
+ * section adopts it, and no section does yet.
+ */
+/** One registered item: stable identity plus its matchable text. */
+type CollectionItem = {
+    /** Stable identity, unique within its registry. */
+    key: string;
+    /** Matchable text (label, filter text, option text). */
+    text: string;
+};
+/** Whether `text` matches `query`. The default is substring; callers pass ranking. */
+type CollectionMatch = (query: string, text: string) => boolean;
+/**
+ * The shared default match: trimmed, case-insensitive substring. An
+ * empty query matches everything (an unfiltered list shows all
+ * items, never none).
+ */
+declare function defaultCollectionMatch(query: string, text: string): boolean;
+/**
+ * Keys of `items` matching `query`, in registration order. Pure —
+ * data-driven consumers (combobox options) filter without
+ * registering anything.
+ */
+declare function filterCollectionKeys(items: readonly CollectionItem[], query: string, match?: CollectionMatch): string[];
+/** The registered text for `key`, or `undefined` when unregistered. */
+declare function findCollectionText(items: readonly CollectionItem[], key: string): string | undefined;
+/**
+ * The item registry for children-driven consumers (select items
+ * publish labels, menu items publish filter text). Re-registering a
+ * key replaces its text in place (a label edit never reorders the
+ * list); unregistering drops it. Registration order is the list
+ * order — filtering never re-sorts.
+ */
+declare function useCollectionRegistry(): {
+    items: readonly CollectionItem[];
+    register: (item: CollectionItem) => void;
+    unregister: (key: string) => void;
+};
+
+/**
+ * The Slot composition model — prop merging for element substitution.
+ *
+ * ## Why this is a primitive
+ *
+ * Every overlay part (`Dialog.Trigger`, `Popover.Trigger`, `Menu.Trigger`, …)
+ * lets the consumer substitute the rendered element while the part keeps its
+ * own behaviour props (event handlers, `aria-*`, refs). Both renderers do that
+ * merge today with independent inline spreads, so a fix to handler ordering on
+ * one side silently does not reach the other — the `useControllableState`
+ * failure mode repeating.
+ *
+ * ## What is genuinely shared, and what is not
+ *
+ * The MERGE is shared and belongs here: event handlers chain (the part's own
+ * handler runs, then the consumer's), `className` concatenates, `style` merges
+ * shallow with the consumer winning, and every other prop takes the consumer's
+ * value unless it is `undefined`. The ELEMENT is not — cloning a React element
+ * is the web renderer's job, and the native renderer maps the merged props onto
+ * its own host. So this returns merged props; each renderer applies them.
+ *
+ * That split is what keeps it a primitive rather than a component: pure data
+ * over plain objects, with no element type in sight.
+ */
+type SlotProps = Record<string, unknown>;
+/**
+ * Chain two optional event handlers into one.
+ *
+ * The part's own handler runs first so its behaviour (opening, selecting)
+ * cannot be swallowed by a consumer handler that stops propagation; the
+ * consumer's runs second so it still observes the event. Either side may be
+ * absent. Neither return value is used — an event handler that needs to veto
+ * must do so through state, not through merge order.
+ */
+declare function composeEventHandlers<E>(partHandler: ((event: E) => void) | undefined, consumerHandler: ((event: E) => void) | undefined): ((event: E) => void) | undefined;
+/**
+ * Merge part props with consumer (slot child) props.
+ *
+ * - `on*` function props chain via {@link composeEventHandlers}
+ * - `className` concatenates with a space (consumer last, so equal-specificity
+ *   utilities resolve toward the consumer)
+ * - `style` flattens RN arrays (later entries win) then merges shallow
+ *   with the consumer winning per key
+ * - every other prop takes the consumer's value unless it is `undefined`,
+ *   in which case the part's stands
+ *
+ * Later consumer sets win over earlier ones, left to right.
+ */
+declare function mergeSlotProps<T extends SlotProps>(partProps: T, ...consumerSets: readonly (Partial<T> | undefined | null)[]): T;
+
+/**
+ * The `render`-prop composition model — Base UI parity for element
+ * substitution on React Native.
+ *
+ * Base UI parts accept `render` (an element or a function of props
+ * and state) plus `className`/`style` as values or functions of
+ * state. The merge itself is the shared `slot` model
+ * (`mergeSlotProps`: part handler first, consumer style winning);
+ * what lives here is the native-renderer application: resolving the
+ * prop into a node.
+ *
+ * Rules, mirroring Base UI semantics where the platform allows:
+ * - `render` absent → `null`, and the part renders its default host.
+ * - element form → cloned with the part props merged UNDER the
+ *   element's own props (consumer wins, except composed handlers).
+ * - function form → called with `(props, state)`, where `props` are
+ *   the part props to spread and `state` is the part's state object.
+ * - `className` never reaches a host with a value: React Native warns
+ *   on unknown props, and there is no stylesheet engine to consume
+ *   it. It is overridden to `undefined` on the clone (documented
+ *   deviation — state styling flows through function `style`/`render`
+ *   props instead). `undefined` props are skipped by the renderer,
+ *   so no warning fires.
+ * - `style` accepts a value or a function of state (Base UI parity);
+ *   `resolveStyle` applies it. Arrays merge caller-last, matching
+ *   the slot rule.
+ */
+type RenderProp<State, Props extends SlotProps> = ReactElement | ((props: Props, state: State) => ReactNode);
+type StateStyle<State, Style> = Style | ((state: State) => Style);
+/**
+ * Apply a value-or-function style prop against part state.
+ */
+declare function resolveStyle<State, Style>(style: StateStyle<State, Style> | undefined, state: State): Style | undefined;
+/**
+ * Resolve a part's `render` prop into a node, or `null` when absent
+ * (the part renders its default host). Never spreads `className`
+ * onto the clone — see the module note.
+ */
+declare function resolveRender<State, Props extends SlotProps>(render: RenderProp<State, Props> | undefined | null, partProps: Props, state: State): ReactNode;
+
+/**
+ * Dismiss wiring — which platform signal closes which surface.
+ *
+ * ## Why this is a primitive
+ *
+ * `dismissPolicy.ts` owns the POLICY (may this surface dismiss; must a close
+ * affordance exist). This owns the WIRING: which concrete signal — pointer
+ * outside the surface, focus leaving it, the Escape key, the system back
+ * gesture — is bound on a given surface. Both renderers bind the same SET of
+ * signals for the same surface kind today with independent conditionals, so a
+ * surface that gains a binding on web silently keeps the old set natively.
+ *
+ * ## What is genuinely shared, and what is not
+ *
+ * The DECLARATION is shared: a modal surface wires outside-pointer, focus-out
+ * and escape; a non-modal one wires none of those and only its visible close
+ * control. The BINDING is not — a DOM pointerdown listener and an RN hardware
+ * back handler are platform code. So this returns the branch set, and each
+ * renderer binds its own listeners to it.
+ *
+ * Branch/surface language: a BRANCH is one dismiss signal; a SURFACE declares
+ * which branches it wires. A branch fires only when declared AND the surface is
+ * open AND the policy allows dismissal — the declaration is consulted, never
+ * decorative (the `dismissTriggersFor` lesson).
+ */
+/** One concrete dismiss signal a renderer can bind. */
+type DismissSource = 
+/** Pointer contact outside the surface (scrim press, backdrop tap). */
+"outside-pointer"
+/** Focus moved outside the surface while it is open. */
+ | "focus-out"
+/** The Escape key (web) or dismiss key equivalent. */
+ | "escape"
+/** The system back affordance (Android hardware back, swipe-back). */
+ | "system-back"
+/** A visible close affordance inside the surface was activated. */
+ | "close";
+type DismissBranches = Record<DismissSource, boolean>;
+/**
+ * Why an overlay open state changed. Base UI
+ * `Dialog.Root.ChangeEventReason` parity subset: `trigger-press`
+ * (trigger toggle, either direction), `outside-press` (scrim/backdrop
+ * press), `escape-key` (Android hardware back and iOS VoiceOver
+ * scrub — the native escape equivalents; RN has no Escape key),
+ * `close-press` (close affordance). `focus-out` is declared but never
+ * bound on native (no global key listener); `imperative-action` and
+ * `none` cover programmatic closes without a user gesture — notably
+ * drag-release dismissal reports `none`, because Base UI has no
+ * gesture-dismiss reason and a drag is neither an outside press nor a
+ * close press. DOM-only details (`event`, `cancel()`, the trigger
+ * element) are omitted: there is no DOM event to carry on native.
+ */
+type OverlayOpenChangeReason = "trigger-press" | "outside-press" | "escape-key" | "close-press" | "focus-out" | "imperative-action" | "none";
+/** Open-change details: the reason, and nothing else (see above). */
+type OverlayOpenChangeDetails = {
+    reason: OverlayOpenChangeReason;
+};
+type DismissWiringOptions = {
+    /** A modal surface locks interaction outside itself, so outside signals dismiss. */
+    modal: boolean;
+    /** Whether the surface may dismiss at all (the policy's `canDismiss`). */
+    dismissible: boolean;
+    /**
+     * Whether a visible close affordance is rendered. A surface with no control
+     * cannot wire the `close` branch: the branch would be declared and never
+     * fire, which is worse than not declaring it.
+     */
+    hasVisibleClose: boolean;
+};
+/**
+ * The branches a surface wires, given what it is.
+ *
+ * Modal + dismissible wires every branch; anything else wires only what it can
+ * honestly offer. A non-modal surface never wires outside-pointer or focus-out
+ * — the content behind it stays interactive by definition, so treating outside
+ * contact as dismissal would close a surface the user never left.
+ */
+declare function dismissBranchesFor(options: DismissWiringOptions): DismissBranches;
+/**
+ * Whether `source` dismisses a surface that is currently `enabled` (open), per
+ * the branches the surface declared. An undeclared branch never fires,
+ * whatever the open state.
+ */
+declare function shouldDismissOn(source: DismissSource, enabled: boolean, branches: DismissBranches): boolean;
+
+/**
+ * Anchor positioning math — where a floating surface goes relative to its trigger.
+ *
+ * ## Why this is a primitive
+ *
+ * Popover, menu, select, tooltip, combobox and preview-card all place a surface
+ * next to an anchor with a gap, then clamp it into the viewport. Both renderers
+ * do that arithmetic today with independent implementations, so a clamping fix
+ * on one side silently does not reach the other.
+ *
+ * ## What is genuinely shared, and what is not
+ *
+ * The MATH is shared and belongs here: given an anchor rect, a floating size,
+ * a placement and a gap, which origin the surface takes, and how it clamps into
+ * a viewport. The MEASUREMENT is not — reading DOM rects or RN `measure` is
+ * platform code. So the renderer measures, this computes.
+ *
+ * All values are plain numbers in the same unit space the caller measured in
+ * (CSS px on web, dp on native). Nothing here names a token: the gap is a
+ * caller-supplied number, not a spacing value.
+ */
+type Rect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+type Placement = "top" | "bottom" | "left" | "right";
+/** Cross-axis alignment of the surface against the anchor (Base UI parity). */
+type Align = "start" | "center" | "end";
+type PositioningOptions = {
+    /** Which side of the anchor the surface prefers. Defaults to `"bottom"`. */
+    placement?: Placement;
+    /** Gap between anchor and surface edges. Defaults to `0`. */
+    offset?: number;
+    /**
+     * Cross-axis alignment. Defaults to `"center"` (the historical
+     * behavior — every existing caller centers). `"start"`/`"end"`
+     * pin the surface's leading/trailing edge to the anchor's.
+     */
+    align?: Align;
+    /** Shift along the cross axis after alignment. Defaults to `0`. */
+    alignOffset?: number;
+};
+/**
+ * One call for the common path: preferred origin, then clamped. `viewport`
+ * defaults to unbounded when the renderer has not measured one yet — the
+ * preferred origin stands rather than clamping against a zero rect.
+ */
+/**
+ * Determine the effective placement side for `anchor` and `size`,
+ * flipping to the opposite side if the preferred placement overflows
+ * `viewport` and the opposite side fits.
+ */
+declare function resolveFloatingSide(anchor: Rect, size: {
+    width: number;
+    height: number;
+}, options?: PositioningOptions & {
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    viewportPadding?: number;
+}): Placement;
+declare function resolveFloatingRect(anchor: Rect, size: {
+    width: number;
+    height: number;
+}, options?: PositioningOptions & {
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    viewportPadding?: number;
+    flip?: boolean;
+}): {
+    x: number;
+    y: number;
+};
+
+/**
+ * Form validation plumbing — error maps and emptiness checks as pure
+ * functions. No React, no React Native.
+ *
+ * Errors travel as plain strings keyed by field name; a field is
+ * invalid while its list is non-empty. Server errors take precedence
+ * over locally computed ones while present (the caller explicitly set
+ * them); editing a field drops its server entry so a fix is never
+ * shadowed by a stale server message. Nothing here throws on caller
+ * input.
+ */
+/** Per-field error messages, keyed by field `name`. */
+type FieldErrors = Record<string, string | string[]>;
+/** Normalize one field's errors to a list. Missing means none. */
+declare function normalizeFieldErrors(error: string | string[] | undefined): string[];
+/**
+ * Merge locally computed errors under server errors: a field shows
+ * its server entry while one exists, else its local entries.
+ */
+declare function mergeFormErrors(internal: FieldErrors, server: FieldErrors): FieldErrors;
+/** Whether a value counts as empty: `undefined`, `null`, or `""`. */
+declare function isEmptyValue(value: unknown): boolean;
+
+/**
+ * Wave 1 of the P2c-3 extraction (`docs/conventions/primitives.md` §3): one
+ * owner for behaviour that exists in BOTH renderers today with independent
+ * implementations, so a fix to one cannot silently fail to reach the other.
+ *
+ * Overlay modality is the "is this overlay the active one" fact: everything
+ * behind an open sheet/dialog/menu must become inert, and only the topmost
+ * overlay may respond. Each renderer has to implement it — DOM via `inert` and
+ * the `aria-hidden`/focus-trap dance, RN via `AccessibilityInfo` and
+ * `pointerEvents` — and the LOGIC of which overlay is on top, and what becomes
+ * inert when it opens and closes, is identical.
+ *
+ * What stays in each renderer is the ACT of applying inertness (it needs the
+ * platform), which is exactly the split the spec asks for: the decision is
+ * shared, the surface is not.
+ */
+/** An overlay's identity within the stack. Any stable key will do. */
+type OverlayId = string;
+type OverlayModalityState = {
+    /** The topmost registered overlay, or `null` when the stack is empty. */
+    readonly top: OverlayId | null;
+    /** Every registered overlay, bottom-first. */
+    readonly stack: readonly OverlayId[];
+    /** The topmost registered MODAL overlay, or `null` when none is open. */
+    readonly modalTop: OverlayId | null;
+    /** True when at least one modal overlay is registered (i.e. open). */
+    readonly isModalActive: boolean;
+    /** True when `id` is the topmost overlay — i.e. it is the interactive one. */
+    isTop(id: OverlayId): boolean;
+    /**
+     * True when content OUTSIDE `id` must be inert. False for the top overlay and
+     * false for an empty stack, so a consumer can wire this straight to `inert`
+     * without a special case for "nothing is open".
+     */
+    isInertOutside(id: OverlayId): boolean;
+};
+/**
+ * Registry of open overlays, in one place, shared by every renderer.
+ *
+ * Registration is a stack rather than a counter because the topmost overlay is
+ * the only interactive one, and a counter cannot express that. Registering the
+ * same id twice is a no-op rather than a second stack entry: a re-render that
+ * re-registers must not make one overlay look two-deep.
+ *
+ * Modality travels with the registration (`{ modal: true }` for modal
+ * surfaces): the Android app-root hook (`useModalActive`) needs to know
+ * whether ANY modal is open, and the registry is the one owner that sees
+ * every overlay. Non-modal overlays (popovers, tooltips, non-modal drawers)
+ * register without it and never count as modal.
+ */
+declare function createOverlayModality(): {
+    register(id: OverlayId, options?: {
+        modal?: boolean;
+    }): () => void;
+    subscribe(listener: () => void): () => void;
+    getState(): OverlayModalityState;
+};
+/**
+ * Register an overlay for as long as this component is mounted.
+ *
+ * `active: false` unregisters without unmounting, which is what a sheet that is
+ * mounted-but-closed needs — an overlay that is present in the tree but not
+ * open must not make content outside it inert. `modal` marks modal surfaces
+ * so the shared registry can answer "is any modal open" (the Android
+ * app-root hook); non-modal overlays register without it.
+ */
+declare function useOverlayRegistration(registry: ReturnType<typeof createOverlayModality>, id: OverlayId, active?: boolean, modal?: boolean): void;
+/** Subscribe to the overlay stack. Returns the current state, re-rendering on change. */
+declare function useOverlayModality(registry: ReturnType<typeof createOverlayModality>): OverlayModalityState;
+type OverlayModalityRegistry = ReturnType<typeof createOverlayModality>;
+/**
+ * Shared overlay modality registry for global stacking, top-detection,
+ * and dismissal order across the application.
+ */
+declare function getSharedOverlayModality(): OverlayModalityRegistry;
+
+/**
+ * The Presence model — exit-animation suspension for unmounting surfaces.
+ *
+ * ## Why this is a primitive
+ *
+ * A surface that disappears the instant `open` flips to `false` cannot play an
+ * exit animation; a surface that stays mounted forever leaks. Both renderers
+ * need the same rule — stay mounted while exiting, unmount when the exit
+ * finishes — and each wires a different finish signal (web: CSS
+ * `animationend`; native: the `Modal` close / Animated callback). One owner for
+ * the state machine, per-renderer finish signals.
+ *
+ * ## What is genuinely shared, and what is not
+ *
+ * The MACHINE is shared: `mounted → exiting → unmounted`, where closing moves
+ * to `exiting` (still rendered) and only the renderer's `finishExit()` moves to
+ * `unmounted`. Reopening from `exiting` returns to `mounted` without ever
+ * unmounting. The SIGNAL is not — no DOM event or Animated value appears here.
+ */
+/** Where a surface is in its mount lifecycle. */
+type PresenceState = "mounted" | "exiting" | "unmounted";
+/**
+ * Pure transition: which lifecycle state follows `open` from `current`.
+ *
+ * Closing from `mounted` suspends in `exiting` (the renderer keeps painting
+ * until its exit animation reports done); reopening from `exiting` restores
+ * `mounted` directly. Nothing here touches a timer or an event.
+ */
+declare function nextPresenceState(current: PresenceState, open: boolean): PresenceState;
+type PresenceModel = {
+    subscribe(listener: () => void): () => void;
+    getState(): PresenceState;
+    /** The renderer reports its controlled `open` value. */
+    setOpen(open: boolean): void;
+    /** The renderer reports its exit animation finished. No-op unless exiting. */
+    finishExit(): void;
+    /** True while the surface must stay in the tree (mounted or exiting). */
+    isPresent(): boolean;
+};
+/** Create a presence model starting from `initialOpen`. */
+declare function createPresenceModel(initialOpen: boolean): PresenceModel;
+/**
+ * React binding for the presence model. `open` is the controlled value; the
+ * renderer calls the returned `finishExit` from its own animation-done signal.
+ * The surface renders while `present` is true.
+ */
+declare function usePresence(open: boolean): {
+    present: boolean;
+    state: PresenceState;
+    finishExit: () => void;
+};
+
+/**
+ * Slider behavior — range math as pure functions.
+ *
+ * No React, no React Native: clamping, step snapping, percent
+ * mapping, single/range normalization, grant-target resolution, and
+ * commit transforms (including `minStepsBetweenValues` gap
+ * enforcement for range sliders). The compound `Slider` parts own
+ * state via `useControllableState` and gestures via `PanResponder`;
+ * every number they commit flows through here first. Nothing here
+ * throws on caller input: degenerate ranges collapse, garbage
+ * resolves to the nearest sane value.
+ */
+type SliderOrientation = "horizontal" | "vertical";
+/** Options shared by the commit path. */
+type SliderCommitOptions = {
+    min: number;
+    max: number;
+    /** Snap increment. Values `<= 0` (or non-finite) mean continuous. */
+    step: number;
+    /**
+     * Minimum gap between values in a range slider, in `step` units.
+     * When `step <= 0` the gap applies in raw value units. Default `0`.
+     */
+    minStepsBetweenValues: number;
+};
+/** Clamp `value` into `[min, max]`. Degenerate `min > max` collapses to the single point `min`. */
+declare function clampSliderValue(value: number, min: number, max: number): number;
+/**
+ * Snap `value` (assumed clamped) to the nearest `min + k * step`.
+ * Values `<= 0` (or non-finite `step`) mean continuous — returned unchanged.
+ */
+declare function snapSliderValue(value: number, min: number, step: number): number;
+/** Percentage (0–100) of `value` along `[min, max]`. Degenerate ranges report `0`. */
+declare function sliderValuePercent(value: number, min: number, max: number): number;
+/**
+ * Normalize a caller `value` (single or array) into a clamped
+ * array of at least one entry. Non-finite entries fall back to
+ * `min`. Snapping is deliberately NOT applied here: the displayed
+ * value stays clamped-but-raw until a commit snaps it (a slider
+ * that jumps on mount is a worse experience than one that snaps
+ * on first commit). Never throws; empty arrays resolve to
+ * `[min]`.
+ */
+declare function normalizeSliderValues(value: number | readonly number[] | undefined, min: number, max: number): number[];
+/**
+ * Ratio (0–1) of a touch location along the track extent. Vertical
+ * sliders invert (track top is `max`).
+ */
+declare function sliderRatioFromLocation(location: number, extent: number, orientation: SliderOrientation): number;
+/** Value at a track ratio. */
+declare function sliderValueFromRatio(ratio: number, min: number, max: number): number;
+/** Index of the entry nearest to `target` (ties go to the lower index). */
+declare function nearestSliderThumbIndex(values: readonly number[], target: number): number;
+/**
+ * Commit transform: replace `values[index]` with `next` (clamped +
+ * snapped), then enforce the `minStepsBetweenValues` gap against
+ * neighbours (range sliders only — single values pass through).
+ * Returns a new array; inputs are never mutated.
+ */
+declare function resolveSliderCommit(values: readonly number[], index: number, next: number, options: SliderCommitOptions): number[];
+
+/**
+ * The dismissal POLICY for a kern surface — what closes it, and whether a
+ * visible close affordance must be rendered.
+ *
+ * ## Why this is a primitive
+ *
+ * P2c-2 §3 Wave 1: give behaviour that exists on BOTH renderers with
+ * independent implementations one owner. Dismissal is that behaviour.
+ *
+ * The native `SheetSurface` already encodes the rule in one line, with a
+ * comment recording the defect it fixed:
+ *
+ *     // a sheet that declares `dismissible` but renders no close control for it
+ *     const showClose = dismissible ?? Boolean(onDismiss);
+ *
+ * The web `SheetSurface` encodes the same decision differently — the close
+ * button is rendered when `onClose` is passed. Both are one rule wearing two
+ * renderers, which is the `useControllableState` failure mode repeating: a fix
+ * to one silently does not reach the other.
+ *
+ * ## What is genuinely shared, and what is not
+ *
+ * The POLICY is shared and belongs here: which triggers dismiss, and whether a
+ * close affordance must exist. The TRIGGERS are not — a scrim `Pressable` and a
+ * `Portal`/`Backdrop` are DOM, `onRequestClose` and hardware back are RN. So
+ * this returns the decisions, and each renderer wires its own triggers to them.
+ *
+ * That split is what keeps it a primitive rather than contract data: a rule both
+ * renderers must apply identically, with no platform type in sight.
+ */
+/** How a surface is dismissed. Each renderer binds its own triggers to these. */
+type DismissTriggers = {
+    /** The scrim/backdrop outside the surface was pressed. */
+    scrim?: boolean;
+    /** Escape (web) or the hardware/gesture back (native). */
+    escape?: boolean;
+    /** A visible close affordance was activated. */
+    closeButton?: boolean;
+};
+type DismissPolicyOptions = {
+    /**
+     * Whether the surface can be dismissed at all. `undefined` means "follow
+     * whether a dismiss handler was supplied" — which is how a mandatory surface
+     * (a dialog the user must answer) is expressed without a separate API.
+     */
+    dismissible?: boolean;
+    /**
+     * Whether the surface declares a dismissal path at all. A surface with no
+     * handler cannot show a close control: the control would render and do nothing,
+     * which is worse than not rendering it.
+     */
+    hasDismissHandler: boolean;
+};
+type DismissPolicy = {
+    /** True when at least one trigger may dismiss. */
+    canDismiss: boolean;
+    /**
+     * A visible close affordance MUST be rendered.
+     *
+     * This is the part the scrim-only shell got wrong: it could render a surface
+     * that declared a dismissal path and showed no control for it, so the declared
+     * path was unreachable. Deriving `showClose` from the same value the triggers
+     * use means a sheet cannot declare dismissal and render nothing.
+     */
+    showClose: boolean;
+    /**
+     * Bind to a platform trigger. `enabled` is the caller's current OPEN state:
+     * a trigger on a closed surface must do nothing, whatever the policy says.
+     *
+     * `triggers` is what `dismissTriggersFor()` returned. It is REQUIRED rather
+     * than optional: while it was absent this parameter was accepted and ignored,
+     * which made `dismissTriggersFor` decorative — a docked surface could declare
+     * no scrim and still be dismissed by one, because the declaration was never
+     * consulted. The lint rule that caught it (`noUnusedFunctionParameters`) was
+     * right and this is the fix it was pointing at.
+     */
+    shouldDismiss: (trigger: keyof DismissTriggers, enabled: boolean, triggers: DismissTriggers) => boolean;
+};
+/**
+ * Resolve the dismissal policy. Pure — the caller supplies the current open
+ * state as `enabled`.
+ */
+declare function createDismissPolicy(options: DismissPolicyOptions): DismissPolicy;
+/**
+ * The triggers a renderer should wire, given what it can actually offer.
+ *
+ * A docked surface has no scrim and no Escape — it is persistent, not modal — so
+ * it declares those `false` rather than binding handlers that can never fire. That
+ * is the `DockSheet` reasoning (role="region", no elevation token) expressed as a
+ * data decision instead of scattered conditionals.
+ */
+declare function dismissTriggersFor(surface: {
+    modal: boolean;
+    hasVisibleClose: boolean;
+}): DismissTriggers;
+
+/**
+ * The FocusTrap model — tab looping and autofocus events for modal surfaces.
+ *
+ * ## Why this is a primitive
+ *
+ * A modal surface must keep keyboard focus inside itself while open and move
+ * focus into itself when it opens. Both renderers implement that today — web
+ * through the dialog primitive's trap, native through explicit first-focusable
+ * management — with independent loop arithmetic, so an off-by-one on one side
+ * silently does not reach the other.
+ *
+ * ## What is genuinely shared, and what is not
+ *
+ * The LOOP is shared: given an ordered list of `count` focusable stops, which
+ * stop follows a Tab / Shift+Tab, and where focus lands on open. The STOPS are
+ * not — querying tabbable DOM nodes and RN focus targets is platform code. So
+ * this works over indices; each renderer maps indices to its own stops.
+ *
+ * Autofocus is an EVENT descriptor, not an imperative call: the model returns
+ * which index to focus (`{ type: "focus-stop", index }` or `{ type: "none" }`)
+ * and the renderer performs it. Returning a description keeps DOM/RN focus
+ * calls out of the kernel.
+ */
+type TrapMove = "next" | "previous" | "first" | "last";
+/** Pure index arithmetic for one trap move. */
+declare function nextTrapIndex(current: number, count: number, move: TrapMove, loop: boolean): number;
+/** Where focus goes when the trap opens. A description, not a focus() call. */
+type AutofocusEvent = {
+    type: "focus-stop";
+    index: number;
+} | {
+    type: "none";
+};
+/**
+ * Which stop to focus on open: the caller's explicit `autoFocusIndex` when it
+ * names a real stop, else the first stop, else no event (an empty trap has
+ * nothing to focus and must not invent a target).
+ */
+declare function resolveAutofocus(count: number, autoFocusIndex?: number): AutofocusEvent;
+type FocusTrapModel = {
+    /** Currently focused stop, or -1 when the trap holds no stops. */
+    getCurrent(): number;
+    getCount(): number;
+    move(move: TrapMove): number;
+    /** Tab from the last stop wraps exactly when `loop` is true. */
+    loops(): boolean;
+    autofocus(autoFocusIndex?: number): AutofocusEvent;
+};
+
+/**
+ * Number field behavior — locale-aware parse/format and step math as
+ * pure functions. No React, no React Native.
+ *
+ * The value is always a plain `number` (or `null` for empty) whatever
+ * the input renders. Formatting is display-only: typing parses back
+ * through the same locale, so a formatted value never drifts from the
+ * state it represents. Nothing here throws on caller input.
+ */
+type NumberFormatSpec = {
+    /** BCP 47 locale for grouping/decimal separators. Defaults to runtime locale. */
+    locale?: string;
+    /** `Intl.NumberFormat` options for display. */
+    format?: Intl.NumberFormatOptions;
+};
+/**
+ * Format a value for display. `null` renders empty. Falls back to
+ * `String(value)` when `Intl` is unavailable — never throws.
+ */
+declare function formatNumberValue(value: number | null, spec?: NumberFormatSpec): string;
+/**
+ * Parse display text back to a number through the same locale:
+ * grouping separators are stripped, the locale decimal separator is
+ * mapped to `.`. Returns `null` for empty or unparseable text —
+ * never throws.
+ */
+declare function parseNumberValue(text: string | null | undefined, spec?: NumberFormatSpec): number | null;
+/** Clamp into `[min, max]`; undefined bounds are open. */
+declare function clampNumberValue(value: number, min?: number, max?: number): number;
+/**
+ * Step from a value by `direction`, snapping to the step grid when
+ * `snapOnStep` is set, then clamping to `[min, max]`.
+ */
+declare function stepNumberValue(value: number, direction: 1 | -1, options?: {
+    step?: number;
+    snapOnStep?: boolean;
+    min?: number;
+    max?: number;
+}): number;
+
+/**
+ * The owned Portal registry — kern's own overlay host, alongside Base UI.
+ *
+ * ## Why this is a primitive, and why it does NOT replace Base UI on web
+ *
+ * Every overlay renders its surface somewhere other than its trigger's DOM
+ * parent: that "somewhere else" needs an owner (ordering, mount/unmount,
+ * cleanup on unmount). Today the web renderer borrows that owner from Base UI's
+ * `Portal` and native borrows it from `Modal`. D12 rules the extraction as
+ * DUAL-PATH: kern gains its OWN portal registry that both renderers can host
+ * through, while web KEEPS its Base UI usage. Removing the borrowed owner
+ * before the owned one is proven would strand every overlay on a host nobody
+ * exercises; adding alongside lets the owned path prove itself per surface.
+ *
+ * ## What is genuinely shared, and what is not
+ *
+ * The REGISTRY is shared: which overlay ids are mounted, in what order, and
+ * the rule that unmounting removes exactly one registration. The HOST is not —
+ * a DOM container element and an RN `Modal` stack are platform code. So this
+ * returns mount state, and each renderer paints it.
+ */
+type PortalEntry = {
+    /** Stable overlay identity, bottom-first in `order()`. */
+    id: string;
+    /** Monotonic sequence so two mounts in one frame still order deterministically. */
+    sequence: number;
+};
+type PortalRegistry = {
+    subscribe(listener: () => void): () => void;
+    /** Mount `id`. Re-mounting an open id refreshes nothing — it is a no-op. */
+    mount(id: string): void;
+    /** Unmount `id`. Unknown ids are a no-op, never an error. */
+    unmount(id: string): void;
+    /** Mounted ids, bottom-first. */
+    order(): readonly string[];
+    isMounted(id: string): boolean;
+};
+/** Create an empty portal registry. Pure — no DOM, no RN. */
+declare function createPortalRegistry(): PortalRegistry;
+/**
+ * Resolve where a surface renders: the caller's explicit host wins, else the
+ * shared default. A description, not a container lookup — finding the DOM node
+ * or RN host is the renderer's job.
+ */
+declare function resolvePortalTarget(options: {
+    ownerProvided?: string;
+    defaultTarget?: string;
+}): string;
+
+/**
+ * The Press model — press/activation behaviour shared by every pressable.
+ *
+ * ## Why this is a primitive
+ *
+ * Pressed-state tracking (pressed visual while held, cancelled when the pointer
+ * leaves) and keyboard activation (Enter and Space activate a pressable) exist
+ * on BOTH renderers with independent implementations: web spreads `onClick` /
+ * `onKeyDown`, native spreads `onPress`. A fix to which keys activate on one
+ * side silently does not reach the other.
+ *
+ * ## What is genuinely shared, and what is not
+ *
+ * The MODEL is shared: pressed-or-not, and which keys count as activation.
+ * The EVENTS are not — DOM keyboard/pointer events and RN press events are
+ * platform types. So this exposes `begin`/`end`/`cancel` plus the key
+ * predicate, and each renderer binds its own events to them.
+ */
+/** Pressed-or-not. Cancelled returns to idle without ever reporting a press. */
+type PressPhase = "idle" | "pressed";
+type PressModel = {
+    getPhase(): PressPhase;
+    isPressed(): boolean;
+    /** Pointer/key went down on the target. No-op when disabled. */
+    begin(): void;
+    /** Release over the target: reports a press via the caller's `onPress`. */
+    end(): void;
+    /** Release off-target or interrupted: back to idle, no press reported. */
+    cancel(): void;
+    /** Whether the model accepts input at all. */
+    isDisabled(): boolean;
+};
+/**
+ * React binding for the press model. Returns the pressed bit plus
+ * platform-free `begin`/`end`/`cancel` the renderer binds to its own events —
+ * web to pointer/key handlers, native to `onPressIn`/`onPressOut`.
+ */
+declare function usePress(options?: {
+    disabled?: boolean;
+    onPress?: () => void;
+}): {
+    pressed: boolean;
+    begin: () => void;
+    end: () => void;
+    cancel: () => void;
+};
+
+/**
+ * The prompt-input model — draft value, the send gate, submit keys,
+ * and composer sizing.
+ *
+ * ## Why this is a primitive
+ *
+ * The composer on both renderers answers the same questions on every
+ * keystroke: is there anything sendable, does this key submit or
+ * newline, and how tall is the multiline field. If the web side sends
+ * on Enter while native needs Ctrl+Enter, the same keyboard habit
+ * submits on one renderer and litters newlines on the other — a
+ * submit mode is behavior, and behavior belongs here once.
+ *
+ * ## What is genuinely shared, and what is not
+ *
+ * The DRAFT PROTOCOL is shared: value state, the `canSend` gate over
+ * the shared `ChatStatus` vocabulary, the submit-key rule per
+ * `submitMode`, Escape cancellation, and the clamped composer height.
+ * The FIELD is not — the text host, autosize measurement, focus, and
+ * the model-picker / tools-menu / mic chrome are styled composition
+ * in Kern. Sending itself stays app-owned: `submit` reports the draft
+ * through `onSubmit` and leaves clearing to the caller, so controlled
+ * and uncontrolled drafts behave identically.
+ */
+
+/** Which key commits the draft. `none` submits from the Send affordance only. */
+type PromptInputSubmitMode = "enter" | "ctrlEnter" | "none";
+/**
+ * Whether the draft may send now: non-blank text, no run in flight
+ * (a busy composer offers Stop instead — the `isChatBusy` half of
+ * the shared vocabulary), and within `maxLength` when one is set.
+ * An `error` status sends: retry reuses the draft.
+ */
+declare function resolveCanSend(options: {
+    text: string;
+    status: ChatStatus;
+    maxLength?: number;
+}): boolean;
+/**
+ * Whether a key event commits the draft under `submitMode`: plain
+ * Enter submits in `enter` mode (Shift+Enter holds the newline
+ * convention both renderers share); `ctrlEnter` needs Ctrl or Cmd;
+ * `none` never submits by key. Key names are plain strings — each
+ * renderer maps its own key events onto them.
+ */
+declare function shouldSubmitOnKey(options: {
+    key: string;
+    shiftKey?: boolean;
+    ctrlKey?: boolean;
+    metaKey?: boolean;
+    submitMode: PromptInputSubmitMode;
+}): boolean;
+/**
+ * Whether an Escape key cancels the draft when `cancelOnEscape` is
+ * set. The renderer owns blur; this only answers the key question so
+ * both renderers clear-or-keep identically.
+ */
+declare function shouldCancelOnEscapeKey(key: string, cancelOnEscape: boolean): boolean;
+/**
+ * The composer height for `lineCount` lines at `lineHeight` per line,
+ * clamped to `minLines`..`maxLines` (defaults `1`..`5`, the range
+ * every flagship composer grows through before scrolling). The
+ * renderer counts lines from its own measurement; this clamps.
+ */
+declare function resolveComposerHeight(options: {
+    lineCount: number;
+    lineHeight: number;
+    minLines?: number;
+    maxLines?: number;
+}): number;
+/**
+ * The composer draft, controlled or uncontrolled, gated on the run
+ * status. `submit` reports the draft through `onSubmit` when
+ * `canSend` holds and is otherwise a terminal no-op (no callbacks
+ * from an empty or busy composer). `submit` never clears, by
+ * decision: the caller clears after handing the draft to its
+ * transport (`onSubmit={(text) => { send(text); clear(); }}`), so
+ * the clear visibly follows the send on every renderer and
+ * controlled drafts behave exactly like uncontrolled ones. A hook
+ * that cleared internally could not clear controlled drafts, and
+ * two behaviors under one name is the bug farm.
+ */
+declare function usePromptInput(options?: {
+    value?: string;
+    defaultValue?: string;
+    onChange?: (next: string) => void;
+    status?: ChatStatus;
+    submitMode?: PromptInputSubmitMode;
+    cancelOnEscape?: boolean;
+    maxLength?: number;
+    onSubmit?: (text: string) => void;
+}): {
+    value: string;
+    setValue: (next: string) => void;
+    canSend: boolean;
+    submit: () => void;
+    clear: () => void;
+    handleKey: (event: {
+        key: string;
+        shiftKey?: boolean;
+        ctrlKey?: boolean;
+        metaKey?: boolean;
+    }) => boolean;
+};
+
+/**
+ * The reasoning helper — streaming auto-open over the existing
+ * `Collapsible`.
+ *
+ * ## Why this reuses Collapsible instead of adding a primitive
+ *
+ * A reasoning block is a disclosure unit: a trigger ("Thought for
+ * 4s") with a panel (the thinking stream) that mounts while open.
+ * That is exactly what `Collapsible` already is — same boolean
+ * domain, same mount-on-open presence, same button-with-expanded
+ * trigger. The only chat-specific behavior is WHEN it opens: live
+ * thinking auto-opens while streaming and returns to caller control
+ * once settled. A one-line resolver expresses that; a new primitive
+ * would duplicate `Collapsible` to own a single conditional.
+ *
+ * ## How Kern wires it
+ *
+ * `open={resolveReasoningOpen(callerOpen, status)}` on the
+ * `Collapsible`, with the caller's toggle feeding back through
+ * `onOpenChange`. No hook, no component, no state here — the open
+ * bit stays where `Collapsible` already keeps it.
+ */
+
+/**
+ * Whether the reasoning disclosure reads open: streaming thinking
+ * auto-opens (the reader watches the thought form); settled thinking
+ * follows the caller's `open` (`undefined` reads closed — an
+ * uncontrolled disclosure starts collapsed, the `Collapsible`
+ * default).
+ */
+declare function resolveReasoningOpen(open: boolean | undefined, status: ChatStatus): boolean;
+
+/**
+ * Roving index — one tab stop per group, arrow traversal within it.
+ *
+ * ## Why this is a primitive and not a component
+ *
+ * A composite control (a list of segments, a carousel's item track, a
+ * time-picker's three fields) is ONE tab stop, not N. Inside it, arrow keys move
+ * between items. That is "roving focus", and it is a model — an active index plus
+ * the invariant that only the active item is in the tab order — not a widget.
+ *
+ * The mechanism is platform-specific and deliberately NOT here: web presses
+ * ArrowLeft/ArrowRight; React Native has no arrow keys at all, because a touch
+ * device has no keyboard. So the two renderers supply their own input handling
+ * and this model supplies only the state and the derived per-item facts. Folding
+ * key handling in would make the "platform-free" claim false, which is the same
+ * mistake the SheetSurface extraction would have made.
+ *
+ * ## What callers get
+ *
+ * `describe(index)` returns `isActive` and `isTabbable`. Those are deliberately
+ * NOT named `tabIndex` or `focused`: `tabIndex` is web vocabulary, and a native
+ * renderer maps `isTabbable` onto `accessibilityState.selected` instead. The
+ * model must not encode which platform is consuming it, or a future third
+ * renderer has to work around the web one.
+ *
+ * ## Wrap and disabled
+ *
+ * `loop: true` wraps from last to first. `loop: false` stops, and the
+ * corresponding `next()`/`previous()` at the end is a no-op that returns the
+ * same index — callers that need to know can compare. Disabled items are
+ * skipped by traversal but keep their own position, so `count` and the index
+ * stable: skipping by deletion would renumber everything after it.
+ */
+type RovingOrientation = "horizontal" | "vertical" | "both";
+type RovingOptions = {
+    /** Number of items in the group. */
+    count: number;
+    /** Which arrow keys move. `both` accepts either axis. */
+    orientation?: RovingOrientation;
+    /** Wrap from last to first. Default: no wrap. */
+    loop?: boolean;
+    /** Controlled active index. */
+    activeIndex?: number;
+    defaultActiveIndex?: number;
+    onActiveIndexChange?: (index: number) => void;
+    /** Items to skip during traversal. Position is preserved in the index space. */
+    isDisabled?: (index: number) => boolean;
+};
+type RovingItem = {
+    index: number;
+    /** This is the item that holds the group's single tab stop. */
+    isActive: boolean;
+    /** True only for the active item — the "one tab stop" invariant. */
+    isTabbable: boolean;
+    disabled: boolean;
+};
+type RovingModel = {
+    activeIndex: number;
+    setActive: (index: number) => void;
+    next: () => number;
+    previous: () => number;
+    first: () => number;
+    last: () => number;
+    describe: (index: number) => RovingItem;
+    orientation: RovingOrientation;
+    loop: boolean;
+};
+/**
+ * React binding.
+ *
+ * The model is plain and synchronous, but a React caller needs the re-render
+ * that follows a change of active index, so state is held here rather than
+ * inside `createRovingModel`. Uncontrolled changes bump a counter to force the
+ * re-render and read the value back out of the model; controlled callers are
+ * driven by their own prop and are not re-rendered from here.
+ */
+declare function useRovingModel(options: RovingOptions): RovingModel;
+
+/**
+ * The collection/selection model shared by every Kern control that selects.
+ *
+ * ## Why this is a primitive
+ *
+ * SegmentedButton, ToggleGroup, Accordion and Select all reduce to the same two
+ * questions: is this key selected, and what happens when it is activated. The
+ * answer differs in exactly one way — whether selection is exclusive or additive
+ * — and that difference is a Kern decision (M3's segmented button is multi-select;
+ * its radio group is not), not a platform detail.
+ *
+ * So the model is shared and the rendering is not. On web the selection axis is
+ * Base UI's `multiple`; on native it is `accessibilityRole` switching between
+ * `radio` and `checkbox`. Neither belongs in this file, which is why it can be a
+ * real primitive rather than contract data.
+ *
+ * ## Why the key is generic
+ *
+ * SegmentedButton and ToggleGroup select by string value; Accordion selects by
+ * INDEX, and `expanded: number[]` is public API. Pinning this to `string` would
+ * have left Accordion out and made the "shared model" claim half true. The
+ * selection rules never inspect the key, so there is nothing to gain from
+ * narrowing it.
+ *
+ * ## Representation
+ *
+ * Selection is ALWAYS an array, including in single mode where it holds at most
+ * one entry. Normalising to one shape removes the branch every consumer otherwise
+ * writes (`isMultiple ? values : [value]`).
+ */
+/** The identity of a selectable item: string for value-keyed, number for index-keyed. */
+type SelectionKey = string | number;
+type SelectionMode = 
+/**
+ * Radio semantics: activating replaces, and re-activating the selected item
+ * does NOTHING — it does not deselect. A radio group with nothing selected is
+ * not a state M3 describes, and a control that empties itself on a second tap
+ * surprises pointer users.
+ */
+"single"
+/**
+ * Accordion / disclosure semantics: activating replaces, and re-activating the
+ * CURRENT item COLLAPSES it. Distinct from `single` because "the one open
+ * section" closing is the entire point of a disclosure.
+ *
+ * Found by a test: the first version of this primitive had only `single` and
+ * applying it to Accordion broke the collapse that component exists to provide.
+ */
+ | "single-toggle"
+/** Multi-select: activating adds or removes. */
+ | "multiple";
+/** At most one entry in `single` mode; any number in `multiple`. */
+type Selection<K extends SelectionKey = string> = readonly K[];
+/** Coerce a caller's single-or-array value into the array representation. */
+declare function normalizeSelection<K extends SelectionKey>(value: K | readonly K[] | undefined, mode: SelectionMode): Selection<K>;
+/** Whether `key` is currently selected. */
+declare function isSelected<K extends SelectionKey>(selected: Selection<K>, key: K): boolean;
+/**
+ * Apply an activation to the selection.
+ *
+ * In `single` mode an activation always REPLACES, even re-activating the current
+ * key — that is what a radio group does. Deselecting would leave the group with
+ * nothing selected, which M3 does not describe. (A hand-rolled implementation
+ * this replaced set `""` on re-activation, producing a phantom empty-string
+ * selection instead.)
+ */
+declare function toggleSelection<K extends SelectionKey>(selected: Selection<K>, key: K, mode: SelectionMode): Selection<K>;
+/**
+ * The selection state, controlled or uncontrolled, with a stable `select`
+ * callback.
+ *
+ * `mode` changes normalise immediately rather than waiting for an interaction:
+ * widening single -> multiple keeps the selection, narrowing multiple -> single
+ * keeps the FIRST entry, so a control never reports more selected items than its
+ * mode permits.
+ */
+declare function useSelection<K extends SelectionKey>({ value, defaultValue, onChange, mode, }: {
+    value?: K | readonly K[];
+    defaultValue?: K | readonly K[];
+    onChange?: (next: Selection<K>) => void;
+    mode: SelectionMode;
+}): [Selection<K>, (key: K) => void];
+
+/**
+ * The stick-to-bottom model — auto-scroll that pauses when the reader
+ * scrolls up and resumes at the bottom.
+ *
+ * ## Why this is a primitive
+ *
+ * Message lists on both renderers answer the same two questions on
+ * every scroll event and every content growth: is the viewport pinned
+ * to the newest edge, and should new content pull it there. Two
+ * independent implementations drift on exactly the edge that matters —
+ * the threshold that decides "at the bottom" — so streaming text
+ * yanks one renderer away from history the reader is re-reading.
+ *
+ * ## What is genuinely shared, and what is not
+ *
+ * The MATH and the STUCK BIT are shared: given plain rect numbers,
+ * whether the viewport counts as pinned, and the `stuck` state with
+ * its pause-on-scroll-up / resume-at-bottom transitions. The
+ * MEASUREMENT and the SCROLLING are not — reading content/viewport
+ * sizes and calling `scrollToEnd` are platform code. So the renderer
+ * measures and reports, this decides; the renderer performs the
+ * scroll this returns true for.
+ *
+ * All values are plain numbers in the same unit space the caller
+ * measured in (CSS px on web, dp on native), following the
+ * `positioning` precedent. `scrollOffset` is the distance scrolled
+ * from the start edge (top); inverted RN lists report the same
+ * quantity from their own metrics before calling in.
+ */
+/** Plain-rect snapshot of the scroll container. All values `>= 0`. */
+type StickToBottomMetrics = {
+    /** Total scrollable content extent. */
+    contentHeight: number;
+    /** Visible viewport extent. */
+    viewportHeight: number;
+    /** Distance scrolled from the start (top) edge. */
+    scrollOffset: number;
+};
+/**
+ * Whether the viewport counts as pinned to the newest edge: the
+ * remaining distance is within `threshold` (default `24`, about one
+ * text line — sub-line drift from fractional layout must not unpin).
+ * Content shorter than the viewport is trivially at the bottom.
+ */
+declare function isAtBottom(metrics: StickToBottomMetrics, threshold?: number): boolean;
+/**
+ * Whether the scroll-to-bottom affordance shows: the reader has left
+ * the bottom AND there is somewhere to go (content overflows the
+ * viewport). A short list never shows the button, stuck or not.
+ */
+declare function resolveScrollButtonVisible(options: {
+    stuck: boolean;
+    contentHeight: number;
+    viewportHeight: number;
+}): boolean;
+/**
+ * The stuck bit, controlled or uncontrolled, with the two transitions
+ * every renderer wires:
+ *
+ * - `handleScroll`: the reader moved — stuck follows `isAtBottom`,
+ *   so scrolling up pauses and reaching the bottom resumes.
+ * - `handleContentChange`: new content arrived (a streamed token, a
+ *   new message) — returns whether the caller scrolls to the newest
+ *   edge now (true only while stuck; a paused reader is never yanked).
+ * - `scrollToBottom`: the scroll-button press — re-pins (the caller
+ *   performs the scroll, then feeds the resulting metrics back
+ *   through `handleScroll`).
+ */
+declare function useStickToBottom(options?: {
+    stuck?: boolean;
+    defaultStuck?: boolean;
+    onStuckChange?: (stuck: boolean) => void;
+    /** "At the bottom" tolerance. Default `24`. */
+    threshold?: number;
+}): {
+    stuck: boolean;
+    showScrollButton: (metrics: StickToBottomMetrics) => boolean;
+    handleScroll: (metrics: StickToBottomMetrics) => void;
+    handleContentChange: (metrics: StickToBottomMetrics) => boolean;
+    scrollToBottom: () => void;
+};
+
+/**
+ * Time picker value normalisation — the substantive contract, as pure logic.
+ *
+ * The value is ALWAYS 24-hour internally, whatever the picker renders. Choosing
+ * "3 PM" reports `hours: 15`; re-opening in 24-hour mode shows `15`. A picker
+ * that kept 12-hour state would drift the moment a consumer persisted it, and
+ * the drift would be invisible until someone compared two records.
+ *
+ * `step` is the minute granularity and must divide 60. A step that does not
+ * falls back to 1 rather than silently producing minutes no control could have
+ * produced — and the reported value is then minute-accurate, so the fallback is
+ * visible in the data rather than hidden in the rendering.
+ */
+type TimePickerValue = {
+    /** 0–23. Always 24-hour internally, whatever is rendered. */
+    hours: number;
+    /** 0–59. */
+    minutes: number;
+};
+type TimePickerFormat = "12h" | "24h";
+/** Display-ready parts: localized digits with a localized day period. */
+type TimeParts = {
+    /** Hours as displayed (no leading zero in 12h mode, two digits in 24h). */
+    hours: string;
+    /** Two-digit minutes. */
+    minutes: string;
+    /** Localized day period in 12h mode (`AM`/`PM` for en-US), else `null`. */
+    period: string | null;
+};
+/**
+ * Minute options for a step, as 0-based offsets from the hour.
+ *
+ * A valid step is a POSITIVE INTEGER that divides 60. The integer requirement
+ * matters on its own: 60/1.5 is exactly 40, so a divisibility test alone
+ * accepts 1.5 and yields fractional minutes (0, 1.5, 3.0…) that no picker can
+ * display. Falls back to 1 rather than shipping 18:75.
+ */
+declare function minutesForStep(step: number): readonly number[];
+/** Clamp to a whole hour: hours into 0–23, minutes onto the step grid. */
+declare function normalizeTimeValue(value: Partial<TimePickerValue> | undefined, step?: number): TimePickerValue;
+/** The value `format` renders, derived from the 24-hour state. Never stored. */
+declare function formatTimeValue(value: TimePickerValue, format: TimePickerFormat): {
+    hours: number;
+    period: "AM" | "PM";
+};
+/** Convert a 12-hour choice back into the 24-hour state it represents. */
+declare function toTwentyFourHour(twelveHour: number, period: "AM" | "PM"): number;
+/**
+ * Display-ready parts for a value: localized digits plus, in 12h mode,
+ * the locale's day-period name (`AM`/`PM` for en-US). The state stays
+ * 24-hour; only the presentation localizes. Never throws.
+ */
+declare function formatTimeParts(value: TimePickerValue, format?: TimePickerFormat, locale?: string): TimeParts;
+/**
+ * Step a value by minutes on the clock: wraps past midnight in both
+ * directions (clock arithmetic, not clamping — stepping is cyclic),
+ * then snaps down onto the step grid (the `normalizeTimeValue`
+ * contract). Negative steps move backward. Never throws.
+ */
+declare function addTimeMinutes(value: TimePickerValue | undefined, deltaMinutes: number, step?: number): TimePickerValue;
+
+/**
+ * The toast queue — ordered open-toast identity with subscribe/notify.
+ *
+ * ## Why this is a primitive, and what it does NOT own
+ *
+ * A single-shot `ToastRoot` (open/duration/action) covers one notification;
+ * an app needs a QUEUE: several toasts alive at once, added from
+ * anywhere, dismissed individually or all at once, painted in mount
+ * order. The QUEUE is shared and belongs here: which toast ids are
+ * open, in what order, and the rule that dismissing removes exactly
+ * one registration. The PAYLOAD is not — message content, action
+ * labels, and durations are caller data held by the rendered
+ * `ToastProvider` (components zone), which owns this queue and maps
+ * each id to its content. So this returns mount state, and the
+ * renderer paints it.
+ *
+ * The `version` counter exists for `useSyncExternalStore`: the
+ * snapshot must be a stable primitive, so subscribers read the
+ * counter (bumped on every mutation) rather than a fresh array.
+ */
+type ToastQueue = {
+    subscribe(listener: () => void): () => void;
+    /** Queue a toast id. Re-adding an open id is a no-op — it keeps its original order. */
+    add(id: string): void;
+    /** Dismiss `id`. Unknown ids are a no-op, never an error. */
+    dismiss(id: string): void;
+    /** Dismiss every queued toast. */
+    clear(): void;
+    /** Open ids, oldest-first. */
+    order(): readonly string[];
+    /** Whether `id` is currently queued. */
+    isOpen(id: string): boolean;
+    /** Queued toast count. */
+    count(): number;
+    /** Mutation counter for store snapshots. */
+    version(): number;
+};
+/** Create an empty toast queue. Pure — no DOM, no RN. */
+declare function createToastQueue(): ToastQueue;
+
+/**
+ * The tool-call model — run state plus the human-approval handshake.
+ *
+ * ## Why this is a primitive
+ *
+ * Tool progress rows on both renderers branch on the same question:
+ * is this call still running, did it settle, did it fail, or is it
+ * waiting on the human. Two spellings of "waiting on the human" is
+ * how one renderer shows an Approve/Deny row while the other shows a
+ * spinner — the approval a safety review demanded, silently missing
+ * on one platform.
+ *
+ * ## What is genuinely shared, and what is not
+ *
+ * The STATE MACHINE is shared: the AI SDK v5 `ToolUIPart` vocabulary
+ * (`input-streaming`, `input-available`, `output-available`,
+ * `output-error`, `output-denied`, `approval-requested`), the
+ * running/error/approval predicates every card reads, and the
+ * approve/deny transitions (approve resumes the run, deny settles it
+ * as denied). The REGISTRY is not — which tools exist and how they
+ * execute is app state; this model tracks one call the transport
+ * owns, never the catalogue. Rendering (header/content/input/output
+ * cards) is styled composition in Kern.
+ */
+/**
+ * One tool call's lifecycle, mirroring the AI SDK v5 `ToolUIPart`
+ * states: arguments still streaming in, arguments complete and queued,
+ * output produced, output failed, denied by the human, or paused for
+ * an approval decision.
+ */
+type ToolCallState = "input-streaming" | "input-available" | "output-available" | "output-error" | "output-denied" | "approval-requested";
+/** Arguments flowing or queued: progress UI shows, no result yet. */
+declare function isToolCallRunning(state: ToolCallState): boolean;
+/** The call settled with a result the card can render. */
+declare function isToolCallComplete(state: ToolCallState): boolean;
+/** The call failed: the card shows `errorText`, never output. */
+declare function isToolCallError(state: ToolCallState): boolean;
+/** The run is paused on the human: the card must offer approve/deny. */
+declare function isToolCallApproval(state: ToolCallState): boolean;
+/**
+ * The announced label for a call: tool name plus its plain-language
+ * phase, with the error text appended on failure so the announcement
+ * never reports "error" without saying which one.
+ */
+declare function resolveToolCallLabel(options: {
+    name: string;
+    state: ToolCallState;
+    errorText?: string;
+}): string;
+/**
+ * One call's state, controlled or uncontrolled, with the approval
+ * handshake. `approve` resumes the run (`approval-requested` →
+ * `input-available`) and `deny` settles it (`approval-requested` →
+ * `output-denied`); from any other state both are terminal no-ops —
+ * no transitions, no callbacks — following the `disabled` precedent
+ * that a control which cannot act reports nothing.
+ */
+declare function useToolCall(options?: {
+    state?: ToolCallState;
+    defaultState?: ToolCallState;
+    onStateChange?: (state: ToolCallState) => void;
+    onApprove?: () => void;
+    onDeny?: () => void;
+}): {
+    state: ToolCallState;
+    approve: () => void;
+    deny: () => void;
+};
+
+/**
+ * The typeahead model — character-buffer matching over collection items.
+ *
+ * ## Why this is a primitive
+ *
+ * Select, menu, and combobox lists on both renderers answer the same
+ * question when character keys arrive: which item does the typed
+ * buffer point at. The rules that make typeahead feel right —
+ * prefix matching, same-character cycling, buffer expiry — are
+ * identical per renderer, so two spellings drift on exactly the
+ * behavior touch-typists memorize.
+ *
+ * ## What is genuinely shared, and what is not
+ *
+ * The BUFFER and the MATCH are shared: timed buffer accumulation
+ * over `CollectionItem`s, prefix matching, and same-character
+ * cycling with wrap-around. The KEY PLUMBING is not — no Axis list
+ * part receives character key events on touch hardware (there is no
+ * text field to type into), so no rendered part consumes this yet:
+ * the first consumer is hardware-keyboard forwarding (Kern P1),
+ * which reads this model without pulling any renderer. Filtering
+ * while typing (combobox entry, menu filter input) already flows
+ * through the `collection` match; this covers highlight-to-match,
+ * not filter-to-match.
+ */
+
+/** The typed buffer: accumulated characters plus the last-key time (ms). */
+type TypeaheadBuffer = {
+    text: string;
+    /** `Date.now()`-space timestamp of the last appended character. */
+    at: number;
+};
+/**
+ * Append `char` to the buffer, restarting it when `now` arrives
+ * later than `timeout` (default `500`) after the previous key.
+ * Non-single inputs are ignored — keys arrive one character at a
+ * time, and pasting a word is not typing.
+ */
+declare function appendTypeaheadQuery(previous: TypeaheadBuffer | null, char: string, now: number, timeout?: number): TypeaheadBuffer;
+/** Whether the buffer has gone stale with no new key by `now`. */
+declare function isTypeaheadExpired(buffer: TypeaheadBuffer | null, now: number, timeout?: number): boolean;
+/**
+ * The key the buffer points at: the first item whose text starts
+ * with the buffer (case-insensitive). A buffer of one repeated
+ * character (`"aaa"`) cycles instead — it matches that single
+ * initial, searching forward from `fromKey` (exclusive) with
+ * wrap-around, so repeated presses walk the same-initial items.
+ * An unknown `fromKey` searches from the start.
+ */
+declare function matchTypeaheadKey(items: readonly CollectionItem[], query: string, fromKey?: string | null): string | undefined;
+
+type StateAction<T> = T | ((previous: T | undefined) => T);
+/** Controlled/uncontrolled state with updater support and mode-change warning. */
+declare function useControllableState<T>(value: T | undefined, defaultValue: T | undefined, onChange?: (next: T, details?: OverlayOpenChangeDetails) => void): [
+    T | undefined,
+    (next: StateAction<T>, details?: OverlayOpenChangeDetails) => void
+];
+
+export { type PromptInputSubmitMode as $, type Align as A, type ChatStatus as B, type CalendarCell as C, type DismissBranches as D, type CollectionItem as E, type FieldErrors as F, type CollectionMatch as G, type DismissPolicy as H, type DismissPolicyOptions as I, type DismissSource as J, type DismissTriggers as K, type DismissWiringOptions as L, type FirstDayOfWeek as M, type FocusTrapModel as N, type OverlayOpenChangeDetails as O, type Placement as P, type IdScope as Q, type RenderProp as R, type SlotProps as S, type NumberFormatSpec as T, type OverlayModalityState as U, type PortalEntry as V, type PortalRegistry as W, type PositioningOptions as X, type PresenceModel as Y, type PressModel as Z, type PressPhase as _, type StateStyle as a, normalizeChatSources as a$, type Rect as a0, type RovingItem as a1, type RovingModel as a2, type RovingOptions as a3, type RovingOrientation as a4, type Selection as a5, type SelectionKey as a6, type SelectionMode as a7, type SliderCommitOptions as a8, type StateAction as a9, formatNumberValue as aA, formatTimeParts as aB, formatTimeValue as aC, getSharedOverlayModality as aD, isAtBottom as aE, isCalendarDateDisabled as aF, isChatBusy as aG, isChatError as aH, isChatStreaming as aI, isEmptyValue as aJ, isSelected as aK, isToolCallApproval as aL, isToolCallComplete as aM, isToolCallError as aN, isToolCallRunning as aO, isTypeaheadExpired as aP, isUserMessage as aQ, leadingBlankCount as aR, matchTypeaheadKey as aS, mergeFormErrors as aT, mergeSlotProps as aU, minutesForStep as aV, nearestSliderThumbIndex as aW, nextBranchIndex as aX, nextPresenceState as aY, nextTrapIndex as aZ, normalizeBranchIndex as a_, type StickToBottomMetrics as aa, type TimeParts as ab, type TimePickerFormat as ac, type TimePickerValue as ad, type ToastQueue as ae, type ToolCallState as af, type TrapMove as ag, type TypeaheadBuffer as ah, addTimeMinutes as ai, appendTypeaheadQuery as aj, buildCalendarGrid as ak, clampNumberValue as al, clampSliderValue as am, composeEventHandlers as an, createDismissPolicy as ao, createIdScope as ap, createOverlayModality as aq, createPortalRegistry as ar, createPresenceModel as as, createToastQueue as at, daysInCalendarMonth as au, defaultCollectionMatch as av, dismissBranchesFor as aw, dismissTriggersFor as ax, filterCollectionKeys as ay, findCollectionText as az, type OverlayId as b, normalizeFieldErrors as b0, normalizeSelection as b1, normalizeSliderValues as b2, normalizeTimeValue as b3, parseCalendarDate as b4, parseCalendarMonth as b5, parseNumberValue as b6, previousBranchIndex as b7, resolveAutofocus as b8, resolveCalendarFocus as b9, sliderValuePercent as bA, snapSliderValue as bB, stepNumberValue as bC, toCalendarDate as bD, toCalendarMonth as bE, toTwentyFourHour as bF, toggleSelection as bG, updateAttachment as bH, useAttachments as bI, useBranch as bJ, useCollectionRegistry as bK, useControllableState as bL, useOverlayModality as bM, useOverlayRegistration as bN, usePresence as bO, usePress as bP, usePromptInput as bQ, useRovingModel as bR, useSelection as bS, useStickToBottom as bT, useToolCall as bU, validateAttachment as bV, resolveCalendarMonthNames as ba, resolveCalendarSelection as bb, resolveCalendarWeekdayNames as bc, resolveCanSend as bd, resolveChatMessageLabel as be, resolveChatMessageSpeaker as bf, resolveChatSourceLabel as bg, resolveComposerHeight as bh, resolveDir as bi, resolveFloatingRect as bj, resolveFloatingSide as bk, resolveLocaleFirstDay as bl, resolvePortalTarget as bm, resolveReasoningOpen as bn, resolveRender as bo, resolveScrollButtonVisible as bp, resolveSliderCommit as bq, resolveStyle as br, resolveToolCallLabel as bs, shiftCalendarMonth as bt, shouldCancelOnEscapeKey as bu, shouldDismissOn as bv, shouldHideBranchPicker as bw, shouldSubmitOnKey as bx, sliderRatioFromLocation as by, sliderValueFromRatio as bz, type OverlayOpenChangeReason as c, type PresenceState as d, type OverlayModalityRegistry as e, type SliderOrientation as f, type A11yDir as g, type AttachmentError as h, type AttachmentLimits as i, type AttachmentState as j, type AutofocusEvent as k, type CalendarDateParts as l, type CalendarDirection as m, type CalendarGrid as n, type CalendarGridOptions as o, type CalendarKey as p, type CalendarMonthNameStyle as q, type CalendarMonthParts as r, type CalendarRange as s, type CalendarRangePosition as t, type CalendarSelection as u, type CalendarSelectionMode as v, type ChatAttachment as w, type ChatMessage as x, type ChatRole as y, type ChatSource as z };