@epilot/zenith-react 0.1.0-next.0 → 0.1.0-next.1

package/dist/index.d.ts

@@ -3771,32 +3771,16 @@ declare const shorthands: {
 };
 
 /**
- * Fed to Griffel as `classNameHashSalt`. Griffel hashes class names from
- * `salt + selector + atRules + property + value`, which makes the two cases exhaustive:
- *
- *   same salt      -> identical declarations produce identical class names AND identical rules.
- *                     A "collision" is content identity, so dedup is safe.
- *   different salt -> disjoint class namespaces. Collision is impossible, and dedup between those
- *                     copies is correctly forfeited.
- *
- * It is derived from the pinned `@griffel/core` version and NOTHING else — token isolation is the
- * job of the value-derived property namespaces, not of this salt. Never typed by hand; see
- * DECISIONS.md D4. There used to be a second name for this exact value (`CONTRACT_SALT`, aliasing
- * the generated `CONTRACT_ID`), which is how two documents came to describe a formula the code had
- * stopped using.
+ * Fed to Griffel as `classNameHashSalt`. Griffel hashes class names from `salt + selector +
+ * atRules + property + value`, which makes the two cases exhaustive: same salt -> identical
+ * declarations produce identical class names AND identical rules. A "collision" is content
+ * identity, so dedup is safe.
  */
 
 /**
- * v2-only slot marker, and the reason it has to exist.
- *
- * `data-slot` values are shared with v1 by design, so ANY selector keyed on one also matches
- * v1-rendered DOM — a v1 element nested inside a v2 component included, even though our own rule's
- * root is hash-scoped. The StyleX track hit exactly this: a v1 icon computed to 0x0 and went
- * through a green gate.
- *
- * So every internal descendant selector keys on THIS attribute, which only v2 emits. `data-slot`
- * is still set, but purely as a diagnostic — under content-hashed class names it is the only
- * human-readable identifier left on an element — and is never styled against.
+ * v2-only slot marker, and the reason it has to exist. `data-slot` values are shared with v1 by
+ * design, so ANY selector keyed on one also matches v1-rendered DOM — a v1 element nested inside a
+ * v2 component included, even though our own rule's root is hash-scoped.
  */
 declare const SLOT_ATTR = "data-zenith-slot";
 
@@ -3810,13 +3794,10 @@ declare function assertAnchorIsFirstInHead(doc?: Document): {
 };
 
 /**
- * One class per slot, atoms deduped against whatever is already on the page.
- *
- * **The generic is over the object, not over the key union, and that is load-bearing.** Inferring a
- * type parameter from `Record<Slots, …>` against an object literal widens `Slots` to `string`, so
- * every slot name typechecks including ones that do not exist. OptionCard read `styles.card` in two
- * places with no `card` slot declared and rendered with no card styling at all; tsc was clean and
- * 322 tests passed. Only a pixel diff caught it.
+ * One class per slot, atoms deduped against whatever is already on the page. **The generic is over
+ * the object, not over the key union, and that is load-bearing.** Inferring a type parameter from
+ * `Record<Slots, …>` against an object literal widens `Slots` to `string`, so every slot name
+ * typechecks including ones that do not exist.
  */
 declare function makeZenithStyles<S extends Record<string, GriffelStyle>>(styles: S): () => Record<keyof S & string, string>;
 /**
@@ -3830,26 +3811,6 @@ declare function makeZenithResetStyles(styles: GriffelResetStyle): () => string;
 /**
  * REFERENCE COMPONENT — the colour-matrix collapse. Read this before writing another component
  * that takes a `color` prop.
- *
- * v1 enumerates 20 colours x 3 styles as 60 `compoundVariants`, each a distinct class string like
- * `volt-bg-mint-soft`. Because those names are built by interpolation, Tailwind's scanner cannot
- * see them, which is what `safelist.css` exists to force — 9 lines that emit ~945 rules, 65.6 KB
- * and 59% of v1's entire rule count. The Griffel PoC carried the same shape forward as 60 static
- * style objects.
- *
- * Here the colour is a VALUE, not part of a class name. Three atoms read three custom properties;
- * the component sets those properties inline from the `color` prop. Total rules: one small set per
- * style variant, regardless of how many colours exist. Adding a 22nd palette family costs zero
- * rules.
- *
- * Two consequences worth knowing:
- *  - `color` may legitimately arrive from a runtime expression (`getColorForEntityLabel(label)` and
- *    `WCAG_BADGE_MAP[level].color` both exist in consumer code today), which no build step can
- *    resolve. That is exactly why the palette sheet cannot be statically shaken, and why this
- *    component calls `ensurePaletteTokens()`.
- *  - Selectors key on SLOT_ATTR, never on `data-slot`. `data-slot` values are shared with v1, so a
- *    rule keyed on one also matches v1-rendered DOM — the StyleX track had a v1 icon compute to
- *    0x0 through a green gate this way. `data-slot` is still emitted, purely as a diagnostic.
  */
 declare const COLORS$1: readonly ["accent", "neutral", "gray", "success", "warning", "error", "info", "blue", "sky", "mint", "lime", "green", "teal", "cyan", "indigo", "purple", "pink", "red", "orange", "yellow", "bronze"];
 type BadgeColor = (typeof COLORS$1)[number];
@@ -3867,27 +3828,7 @@ type BadgeProps = Omit<React.ComponentProps<"span">, "color"> & {
 };
 declare const Badge: React.ForwardRefExoticComponent<Omit<BadgeProps, "ref"> & React.RefAttributes<HTMLSpanElement>>;
 
-/**
- * Breadcrumb — Card's compound pattern applied to the nav / ol / li structure.
- *
- * v1's `Breadcrumb` walks its children and interleaves a presentational separator `<li>` between
- * them; `BreadcrumbItem` decides between a link and a plain page by whether a `href` exists. The
- * `nav` / `ol` / `li` semantics and the `aria-current="page"` handling are the real value of this
- * component and are reproduced exactly.
- *
- * v1 renders the link branch through Radix `Slot` when `asChild` is set — dropped here per
- * CONVENTIONS rule 6 (no Radix dependency). There is no `asChild` escape hatch; a consumer wanting
- * a non-`<a>` link anchors it themselves.
- *
- * `BreadcrumbItem` with a `href` renders an `<a>` (slot `breadcrumb-link`); without one, a `<span>`
- * (slot `breadcrumb-page`). Either way the item is wrapped in a `breadcrumb-item` `<li>`. The nav
- * itself has no base styles in v1 — it is left to the caller's className — so it carries only the
- * slot attributes.
- *
- * The link's `transition-colors` expands to Tailwind v4's default property list plus the 150ms
- * `cubic-bezier(0.4, 0, 0.2, 1)` easing — literals from the framework's default theme, which is
- * visible motion and cannot be read from the v1 file (Rule 0: flagged, not approximated away).
- */
+/** Breadcrumb — Card's compound pattern applied to the nav / ol / li structure. */
 type BreadcrumbProps = React.ComponentProps<"nav"> & {
     separator?: React.ReactNode;
 };
@@ -3965,17 +3906,7 @@ declare const Surface: React.ForwardRefExoticComponent<(Omit<Omit<React.Detailed
     children: React.ReactElement;
 }, "ref">) & React.RefAttributes<HTMLDivElement>>;
 
-/**
- * Pill — same colour-matrix collapse as Badge, plus a hover background.
- *
- * v1 enumerates 19 colours x 3 styles as 57 `compoundVariants`, each a distinct class string
- * built by interpolation (`volt-bg-${color}-soft`), which Tailwind's scanner cannot see and
- * `safelist.css` exists to force into existence. The hover state made that 57 more per-colour
- * rules. Here the colour is a VALUE, not part of a class name: the four atoms below read four
- * custom properties, the component sets those inline from the `color` prop, and a single `:hover`
- * atom reads the hover background. Total rules: one small set per style variant — 9 colours' worth
- * of rules cover all 19 x 3 combinations.
- */
+/** Pill — same colour-matrix collapse as Badge, plus a hover background. */
 declare const COLORS: readonly ["blue", "sky", "mint", "lime", "green", "teal", "cyan", "indigo", "purple", "pink", "red", "orange", "yellow", "bronze", "gray", "accent", "warning", "success", "error"];
 type PillColor = (typeof COLORS)[number];
 type PillVariant = "soft" | "solid" | "surface";
@@ -3992,22 +3923,8 @@ type PillProps = Omit<React.ComponentProps<"span">, "color"> & {
 declare const Pill: React.ForwardRefExoticComponent<Omit<PillProps, "ref"> & React.RefAttributes<HTMLSpanElement>>;
 
 /**
- * Separator — v1's `@radix-ui/react-separator` ported to Griffel atoms with no Radix dependency.
- *
- * A separator needs no behaviour beyond correct semantics, so it is a plain `<div>`. The two
- * orientation variants are separate style slots selected in JS from the `orientation` prop — we
- * deliberately do NOT style off a `data-[orientation=...]` attribute, like v1 does. v1 keyed its
- * sizing on `data-[orientation=horizontal]`; doing that here would either key on `data-slot`-style
- * selectors (whose values are shared with v1, so the rule also matches v1-rendered DOM) or on the
- * custom-property slot marker. Two slots in the style object is simpler and cheaper. We still emit
- * `data-orientation` as a plain attribute — for diagnostics and for consumers — we just never style
- * off it.
- *
- * The accessibility surface is the whole point of the component, so it gets the full treatment:
- *  - `decorative` (default `true`): the divider is purely presentational, so it is hidden from
- *    assistive technology with `aria-hidden="true"` and carries no `role`.
- *  - `decorative={false}`: a meaningful separator, so it gets `role="separator"` and
- *    `aria-orientation` matching the `orientation` prop.
+ * Separator — v1's `@radix-ui/react-separator` ported to Griffel atoms with no Radix dependency. A
+ * separator needs no behaviour beyond correct semantics, so it is a plain `<div>`.
  */
 type SeparatorOrientation = "horizontal" | "vertical";
 type SeparatorProps = React.ComponentProps<"div"> & {
@@ -4022,58 +3939,22 @@ type SeparatorProps = React.ComponentProps<"div"> & {
 declare const Separator$3: React.ForwardRefExoticComponent<Omit<SeparatorProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
 
 /**
- * Skeleton — v1's loading placeholder ported to Griffel atoms.
- *
- * Two variants, `default` and `ai`. `default` is a gray block that pulses; `ai` is a gray field
- * that renders three decorative colour spots drifting behind the content. The spots are ported from
- * v1's global `skeleton-ai-spot-*` classes in `styles/utilities.css`, including their exact
- * gradients, durations (10s / 12s / 14s) and easing.
- *
- * The keyframes are the object form, so Griffel hashes each one from its content — a hand-authored
- * global `@keyframes` would collide across two co-resident copies of this package. The pulse is a
- * single three-stop animation; each spot carries its own.
- *
- * The spots are `purple-a4`, `pink-a4` and `indigo-a4`, none of which is a core token family
- * (accent / gray / error / warning / success / info ship in the core sheet; everything else lives
- * in the palette sheet, which is not loaded by default). `ai` therefore calls
- * `ensurePaletteTokens()` — CONVENTIONS rule 3. There is no `color` prop, so no inline custom
- * properties: the spot colours are constant and live inside the style objects.
+ * Skeleton — v1's loading placeholder ported to Griffel atoms. Two variants, `default` and `ai`.
  */
 type SkeletonVariant = "default" | "ai";
 type SkeletonProps = React.ComponentProps<"div"> & {
     /**
-     * `default` is the ordinary loading pulse.
-     *
-     * `ai` is the placeholder for content being generated, drawn with three
-     * drifting colour spots. It is not merely decorative: its spot colours
-     * (purple, pink, indigo) are palette families rather than core ones, so `ai`
-     * calls `ensurePaletteTokens()` and its colours arrive on a later frame than
-     * the rest of the surface.
-     *
-     * @default "default"
+     * `default` is the ordinary loading pulse. `ai` is the placeholder for content being generated,
+     * drawn with three drifting colour spots.
      */
     variant?: SkeletonVariant;
 };
 declare const Skeleton: React.ForwardRefExoticComponent<Omit<SkeletonProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
 
 /**
- * Spinner — v1's SVG spinner ported to a size-driven style object.
- *
- * v1 sizes this with Tailwind `size-*` utilities and deprecated the `size` prop in favour of a
- * `className` like `size-4`. There is no Tailwind here, so that escape hatch does not exist: `size`
+ * Spinner — v1's SVG spinner ported to a size-driven style object. v1 sizes this with Tailwind
+ * `size-*` utilities and deprecated the `size` prop in favour of a `className` like `size-4`.
  * is the supported API and the `@deprecated` tag is dropped (CONVENTIONS rule 9).
- *
- * The SVG markup, `viewBox` and stroke attributes are copied exactly from v1. Both animations are
- * the object form per CONVENTIONS rule 8: the outer `<g>` spins from a single `100%` stop, and the
- * dash sweep carries all three of v1's keyframe stops (`0%`, `47.5%`, `95%,100%`) from
- * `styles/animations.css`. The only mechanical changes are stylistic: sizes become width/height
- * atoms and the two `animate-*` classes become `animationName` + duration + timing + iteration.
- *
- * The five dimensions (1rem / 1.5rem / 2.5rem / 4rem / 6rem) are v1's Tailwind `size-N` values;
- * the v2 token set has no size or width/height family, so they are literals (CONVENTIONS rule 1).
- *
- * v1 also exposes a `variant` prop (`circle` | `line`) whose branches are both empty strings — it
- * produces no styles at all, so it is omitted here.
  */
 type SpinnerSize = "sm" | "base" | "lg" | "xl" | "2xl";
 type SpinnerProps = React.ComponentProps<"svg"> & {
@@ -4085,60 +3966,11 @@ declare const Spinner: React.ForwardRefExoticComponent<Omit<SpinnerProps, "ref">
  * Table — the primitive set (Table, TableHeader, TableBody, TableFooter, TableRow, TableHead,
  * TableCell, TableCaption) in Card's compound pattern: one `makeZenithStyles` call, one slot per
  * sub-component, each reading its own slot.
- *
- * Density (approved 2026-09-09, replacing the earlier context-only mechanism — and with it the
- * open question of whether Table and List could agree on one, now resolved; corrected in review
- * the same day, see the two notes below):
- * `TableHead`/`TableCell` read `tokens.tableHeadHeight`/`tokens.tableCellPaddingY` directly —
- * generated CSS custom properties that cascade from the nearest `[data-density]` ancestor, exactly
- * like Button/Field/Select. `Table`'s own `density` prop, when explicit, stamps `data-density` on
- * the `<table>` element itself; when omitted, no attribute is stamped and ambient shell density
- * (or an outer `DensityProvider`) inherits through ordinary DOM/CSS with no React involvement — a
- * shell attribute mutation restyles an already-mounted table without a rerender. Per-cell
- * `TableHead`/`TableCell` `density` props stamp their own `data-density` the same way, overriding
- * locally. `TableDensityContext` (below) is a deprecated, now-inert compatibility export — see its
- * own doc comment.
- *
- * Two corrections from that review, both applied identically to `Table`, `DataTable`
- * (`data-table.tsx`), `TableHead` and `TableCell`:
- *
- * 1. An explicit `density` establishes a `DensityContextBoundary`, not just a DOM stamp. A DOM
- *    attribute alone reaches ordinary CSS-inheriting descendants, but a Radix `Portal` (a real
- *    `Select`/`Popover`/etc. rendered inside a cell) is a DOM sibling, not descendant, of that cell
- *    — its own `useDensity()` read needs the REACT context updated too, or it silently reports a
- *    stale ancestor value instead of the cell's own override.
- * 2. The DOM stamp and the context value both run through the SAME `canonicalDensity` function
- *    (from `density-provider.tsx`, package-internal). Before this fix, `DensityContextBoundary`
- *    normalized invalid runtime input (e.g. a bad string bypassing TypeScript) for the context, but
- *    the DOM attribute was written raw/unnormalized — an invalid value could stamp `data-density`
- *    with something no generated CSS selector matches while `useDensity()` reported the normalized
- *    `"normal"`, disagreeing about what density is actually in effect.
- *
- * Selectors carry over untouched where they do not involve `data-slot`: `[&_tr]:border-b`,
- * `[&_tr:last-child]:border-0`, `data-[state=selected]:bg-accent-a3` (Radix selection state) and
- * the `role="checkbox"` column-reflow rules all obey the original attribute.
- *
- * Values explicit where no token exists: `px-3` (0.75rem) on head/cell. The row's
- * `transition-colors` expands to Tailwind v4's default property list plus the 150ms
- * `cubic-bezier(0.4, 0, 0.2, 1)` easing — visible motion from the framework's default theme,
- * which the v1 file does not state (Rule 0: flagged, not approximated away). The checkbox
- * `translate-y-[2px]` maps to the modern `translate` property, which is what Tailwind v4 emits.
  */
 type TableDensity = "compact" | "normal" | "comfortable";
 /**
+ * 2026-09-09).
  * @deprecated No longer a supported way to control Table/DataTable geometry (approved
- * 2026-09-09). `Table`/`DataTable` no longer provide a value into this
- * context, and `TableHead`/`TableCell` no longer read it — density now flows entirely through CSS
- * custom-property inheritance from the nearest `[data-density]` ancestor (ambient shell or
- * `DensityProvider`), plus each component's own `density` prop stamping its own `data-density`
- * when explicit. This context simply no longer controls or reports Table/DataTable geometry —
- * `useContext(TableDensityContext)` still returns whatever a consumer's own raw
- * `TableDensityContext.Provider` sets (or the bare `"normal"` default with no such Provider), it
- * just has no bearing on what actually renders any more. Kept only so existing
- * `import { TableDensityContext }` statements and `useContext(TableDensityContext)` call sites do
- * not hard-error. Use the `density` prop on `Table`/`DataTable`/`TableHead`/`TableCell`, or wrap a
- * subtree in `DensityProvider`, instead. This is a disclosed behavioural change; the context's own
- * type and default value are unchanged.
  */
 declare const TableDensityContext: React.Context<TableDensity>;
 type TableProps = React.ComponentProps<"table"> & {
@@ -4320,23 +4152,8 @@ type ButtonProps = Omit<React.ComponentProps<"button">, "variant" | "size" | "sh
 declare const Button: React.ForwardRefExoticComponent<Omit<ButtonProps, "ref"> & React.RefAttributes<HTMLButtonElement>>;
 
 /**
- * ButtonGroup — compound component family for grouping buttons, text, and separators.
- *
- * One `makeZenithStyles` call for the whole family, one slot per sub-component (following `card.tsx`).
- *
- * No Base UI primitive is needed: v1 only used Radix `Slot` for `asChild` on `ButtonGroupText`,
- * which CONVENTIONS rule 6 drops.
- *
- * `ButtonGroup` handles both `horizontal` and `vertical` orientations, removing adjoining border
- * radius and borders on adjacent children. Sibling focus-visible elements are elevated (`z-index: 10`)
- * and made relative so focus rings are never obscured by subsequent siblings.
- *
- * Nested button groups gain a gap via a `:has()` selector keyed on `SLOT_ATTR` (never on `data-slot`,
- * per CONVENTIONS rule 4).
- *
- * `ButtonGroupText` provides a matching text container (`gray-a4`, subtle border, `shadow-xs`).
- *
- * `ButtonGroupSeparator` composes `Separator` with transparent background and stretch alignment.
+ * ButtonGroup — compound component family for grouping buttons, text, and separators. One
+ * `makeZenithStyles` call for the whole family, one slot per sub-component (following `card.tsx`).
  */
 type ButtonGroupOrientation = "horizontal" | "vertical";
 type ButtonGroupProps = React.ComponentProps<"div"> & {
@@ -4361,19 +4178,7 @@ declare const Checkbox$1: React.ForwardRefExoticComponent<CheckboxProps$1 & Reac
 type CheckboxProps = React.ComponentProps<typeof Checkbox$1>;
 declare const Checkbox: React.ForwardRefExoticComponent<Omit<CheckboxProps$1 & React.RefAttributes<HTMLButtonElement>, "ref"> & React.RefAttributes<HTMLButtonElement>>;
 
-/**
- * Label — a native `<label>` element styled with Griffel atoms.
- *
- * Base UI has no Label primitive; v1 wrapped `@radix-ui/react-label`, which only added an
- * `onMouseDown` handler preventing text selection on double click while wrapping a `<label>`
- * to wire `htmlFor`. A native `<label>` natively associates with form controls via `htmlFor` or
- * nesting, so we render a native `<label>` directly with no Base UI or Radix dependency.
- *
- * Variants: `primary` (`gray-a12`) and `destructive` (`error-a12`), both from the core token
- * sheet so no palette install is required.
- *
- * Sizes: `sm` (`text-xs`), `base` (`text-sm`), and `lg` (`text-base`).
- */
+/** Label — a native `<label>` element styled with Griffel atoms. */
 type LabelVariant = "primary" | "destructive";
 type LabelSize = "sm" | "base" | "lg";
 type LabelProps = React.ComponentProps<"label"> & {
@@ -4471,13 +4276,9 @@ type SwitchVariant = "default" | "destructive" | "primary";
 type SwitchSize = "sm" | "base" | "lg";
 type SwitchProps = React.ComponentProps<typeof Root$b> & {
     /**
-     * `default` or `destructive`.
-     *
-     * `primary` is a **deprecated alias of `default`** with byte-identical styles,
-     * kept because v1 had it and consumers still pass it. Choosing it changes
+     * `default` or `destructive`. `primary` is a **deprecated alias of `default`** with byte-
+     * identical styles, kept because v1 had it and consumers still pass it. Choosing it changes
      * nothing; use `default`.
-     *
-     * @default "default"
      */
     variant?: SwitchVariant;
     /** @default "base" */
@@ -4903,38 +4704,6 @@ declare const AlertDialogCancel: React.ForwardRefExoticComponent<Omit<AlertDialo
 /**
  * A region that carries its own appearance — `packages/tokens/SPEC.md` §2 rule 3's document
  * boundary, as a component instead of two hand-written DOM attributes.
- *
- * **What it is for.** Mode is the page's: the shell stamps `data-theme` on `<html>` and every token
- * resolves from there through ordinary CSS inheritance. The one exception is a region that renders
- * content the page does not own — a variable, email or journey preview, a code editor — which brings
- * its own theme regardless of the shell's. The generated sheet already supports that: it emits every
- * treatment's light values under `.light[data-surface="<t>"], [data-theme="light"][data-surface="<t>"]`
- * after the dark blocks, and the dark compounds `[data-theme="dark"][data-surface="<t>"]` alongside
- * them, so an element carrying BOTH attributes wins over an ancestor's mode on specificity and
- * source order. This component is the supported way to stamp that pair.
- *
- * **Why both props are required.** The two attributes are one boundary, not two independent
- * switches. The role tokens (`surface.*`, `border.*`, `shadow.*`, `blur.*`) resolve through the
- * compound `[data-theme=…][data-surface=…]` selector; stamping only `data-theme` would reset the
- * mode while leaving the treatment to be inherited from whatever ancestor happens to declare one —
- * so a boundary would silently render the page's treatment under the region's mode, which is a
- * combination nobody designed. Requiring `surface` makes the caller say which treatment the region
- * is, rather than having this component fabricate a plausible one.
- *
- * **Without a boundary nothing changes.** No component reads `document.documentElement`, and none
- * of them consults this context for anything except re-stamping portalled content (below). A tree
- * with no `AppearanceBoundary` behaves exactly as it does today: live shell attributes stay
- * authoritative, including when the shell flips them after mount.
- *
- * **Density is a separate axis** and stays that way. `DensityProvider` is independent, its context
- * is a different context, and this component neither reads nor writes `data-density`. A region can
- * be inside both, in either nesting order.
- *
- * **Scope limit, stated plainly.** The React context below is per bundled copy of this package. Two
- * independently bundled micro-frontends do not share it, so a boundary in one does not reach
- * portalled content rendered by the other. The DOM attributes it stamps *are* shared — they are
- * ordinary CSS — so the non-portal case works across copies; it is only the portal re-stamp that is
- * copy-local. Each MFE wraps its own root.
  */
 type AppearanceMode = "light" | "dark";
 type AppearanceSurface = "plain" | "bordered" | "glass" | "tint" | "card";
@@ -4980,20 +4749,9 @@ declare const AppearanceBoundary: React.ForwardRefExoticComponent<(Omit<Omit<Rea
 
 /**
  * DENSITY-SPEC.md §4.4 — the two density mechanisms, and why this component is the only one that
- * does both:
- *
- * - CSS custom-property inheritance (no JavaScript) already delivers the shell's AMBIENT default
- *   to every element, portalled or not — a Radix portal root is still an ordinary DOM descendant
- *   of `<html>`, so it inherits `<html data-density="...">` with zero wiring. No provider needed
- *   for that common case.
- * - A bare `data-density` DOM attribute alone never reaches a portal that ISN'T a DOM descendant of
- *   it — setting a DOM attribute runs no React code, so `useDensity()` inside such a subtree (or a
- *   sibling-in-DOM, descendant-in-React-tree portal) sees nothing from it.
- *
- * `DensityProvider` sets both at once: a real DOM `data-density` boundary for ordinary (non-portal)
- * CSS inheritance, and a React context value that portal-content components (`SelectContent`,
- * `PopoverContent`, `DialogContent`, etc.) read via `useDensity()` to re-stamp themselves — since
- * portalled content is a React-tree descendant but a DOM sibling, only the context path reaches it.
+ * does both: - CSS custom-property inheritance (no JavaScript) already delivers the shell's
+ * AMBIENT default to every element, portalled or not — a Radix portal root is still an ordinary
+ * DOM descendant of `<html>`, so it inherits `<html data-density="...">` with zero wiring.
  */
 type Density = "compact" | "normal" | "comfortable";
 type DensityProviderProps = React.ComponentProps<"div"> & {
@@ -5637,23 +5395,18 @@ type ToastOffset = string | number | {
     left?: string | number;
 };
 /**
- * @slot-foreign-dom sonner renders and owns this DOM. `Toaster` returns `<Sonner.Toaster>`, whose
  * root element and entire subtree are sonner's; we style it through sonner's own `toastOptions`
  * class hooks rather than by selecting it. There is no element of ours here to put `data-slot` or
- * `SLOT_ATTR` on, and a marker set on sonner's root would name a node we do not control.
- *
+ * `SLOT_ATTR` on, and a marker set on sonner's root would name a node we do not control. knowingly
+ * skipped.
+ * @slot-foreign-dom sonner renders and owns this DOM. `Toaster` returns `<Sonner.Toaster>`, whose
  * This is ownership, not debt — distinct from `@slot-exempt`, which means our element, rule
- * knowingly skipped. See the public-surface audit for the related finding that `toast` itself is
- * re-exported verbatim out of sonner.
  */
 declare const Toaster: React.ForwardRefExoticComponent<ToasterProps & React.RefAttributes<HTMLElement>>;
 /**
- * Zenith's own per-toast options. Previously `Parameters<typeof Sonner.toast>[1]`,
- * which made every option sonner declared part of this package's public API.
- *
- * `onDismiss`/`onAutoClose` receive sonner's internal toast record. It is typed
- * as `unknown` on purpose: re-exporting that record would reintroduce exactly
- * the coupling this type exists to remove.
+ * Zenith's own per-toast options. Previously `Parameters<typeof Sonner.toast>[1]`, which made
+ * every option sonner declared part of this package's public API. `onDismiss`/`onAutoClose`
+ * receive sonner's internal toast record.
  */
 type ToastOptions = {
     id?: string | number;
@@ -5680,17 +5433,9 @@ type ToastOptions = {
 };
 declare function toastFn(message: React.ReactNode, options?: ToastOptions): string | number;
 /**
- * Zenith's toast entry point. Delegates to sonner, but the callable surface is
- * this package's own: a sonner release can no longer add, remove or reshape a
- * method here without a change in this repository.
- *
- * `promise` is the one member passed through rather than re-wrapped. Its generic
- * over the settled value is what callers depend on, and re-declaring it by hand
- * is where a narrowing bug would be introduced. That is a named exception, not
- * the previous situation where the entire object was sonner's.
- *
- * `custom` and `message` are intentionally absent -- neither is used anywhere in
- * this repository or its documentation.
+ * Zenith's toast entry point. Delegates to sonner, but the callable surface is this package's own:
+ * a sonner release can no longer add, remove or reshape a method here without a change in this
+ * repository. `promise` is the one member passed through rather than re-wrapped.
  */
 declare const toast: typeof toastFn & {
     success: (message: React.ReactNode, options?: ToastOptions) => string | number;
@@ -5700,12 +5445,10 @@ declare const toast: typeof toastFn & {
     loading: (message: React.ReactNode, options?: ToastOptions) => string | number;
     dismiss: (id?: string | number) => string | number;
     /**
-     * Declared here rather than passed through: sonner's own signature references
-     * types its bundle does not name publicly, which makes the emitted `.d.ts`
-     * unbuildable (TS4023). The return is `unknown` on purpose -- sonner returns an
-     * internally-typed handle, and every use in this repository and its docs
-     * ignores it. A caller who needs that handle must cast, which is a narrowing
-     * we accept in exchange for owning the type.
+     * Declared here rather than passed through: sonner's own signature references types its bundle
+     * does not name publicly, which makes the emitted `.d.ts` unbuildable (TS4023). The return is
+     * `unknown` on purpose -- sonner returns an internally-typed handle, and every use in this
+     * repository and its docs ignores it.
      */
     promise: <T>(promise: Promise<T> | (() => Promise<T>), data?: {
         loading?: React.ReactNode;
@@ -6194,11 +5937,7 @@ declare const FieldComboboxClearValue: React.ForwardRefExoticComponent<Omit<Reac
 
 /**
  * `relaxed` is a permanent compatibility alias for `normal` (DENSITY-SPEC.md §4.2,
- * WP9B2A-ACCEPTANCE-LIST) — identical geometry, forever, not deprecated. `compact`/`normal`/
- * `comfortable` are the three canonical CSS density tiers (`[data-density]`); `relaxed` never
- * appears as a DOM attribute value — an explicit `density="relaxed"` normalizes to the DOM's
- * canonical `data-density="normal"` (§ List, below), since the generator's three selector blocks
- * only ever match those three literal strings.
+ * WP9B2A-ACCEPTANCE-LIST) — identical geometry, forever, not deprecated.
  */
 type ListDensity = "compact" | "normal" | "comfortable" | "relaxed";
 type ListItemStatus = "default" | "error" | "warning" | "success";
@@ -6393,14 +6132,8 @@ type TimePickerProps = {
     minuteStep?: number;
     className?: string;
     /**
-     * Accessible name for the hours column. Pass a translated string.
-     *
-     * These are ACCESSIBLE NAMES, not visible headers, and the distinction is deliberate. v1 ≤1.3.x
-     * had `hoursLabel`/`minutesLabel` that rendered visible "HH"/"MM" headings; v1 deleted them in
-     * `138fe05` (2026-06-25) and this package mirrors v1's current output, which Rule 0 makes the
-     * fidelity target. But v1 replaced them with nothing, so both libraries now hand a screen reader
-     * two unnamed columns of bare numbers. Naming them via `aria-label` closes that without moving a
-     * pixel — the VR gate still matches v1 specimen for specimen.
+     * Accessible name for the hours column. Pass a translated string. These are ACCESSIBLE NAMES,
+     * not visible headers, and the distinction is deliberate.
      */
     hoursLabel?: string;
     /** Accessible name for the minutes column. Pass a translated string. See `hoursLabel`. */
@@ -6486,35 +6219,16 @@ type DateRangePickerProps = {
 declare const DateRangePicker: React.ForwardRefExoticComponent<DateRangePickerProps & React.RefAttributes<HTMLDivElement>>;
 
 /**
- * Text — the v1 text scale ported to Griffel atoms.
- *
- * v1 expressed the ten variants as cva classes (`text-3xl tracking-tighter font-bold` etc.), one
- * per variant. Here each variant is a small set of atoms that read design tokens instead of
- * literal values; the variant itself is the whole style, so there is exactly one slot per variant
- * and the caller's `className` is merged on top.
- *
- * Unlike Badge there is no `color` prop, so no palette install and no inline custom properties:
- * the only colour used (the helper variants) is `gray-a11`, a core token that ships in the core
- * sheet.
- *
- * Body and helper variants keep v1's `display: inline-block` — it lets inline text size to its
- * content inside flex/grid parents instead of collapsing to zero width. Titles and headings
- * inherit their display, exactly as v1.
+ * Text — the v1 text scale ported to Griffel atoms. v1 expressed the ten variants as cva classes
+ * (`text-3xl tracking-tighter font-bold` etc.), one per variant.
  */
 type TextVariant = "title3" | "title2" | "title1" | "heading3" | "heading2" | "heading1" | "body2" | "body1" | "helper2" | "helper1";
 type TextProps = React.ComponentProps<"span"> & {
     /**
-     * The role and size of the text, as one value.
-     *
-     * **The number runs opposite to HTML heading convention: 3 is the largest of
-     * its group and 1 the smallest.** `title3` is `text3xl` and `title1` is
-     * `textXl`; `heading3` is `textLg` and `heading1` is `textSm`. Reading
-     * `title1` as "the primary title" gives you the smallest one.
-     *
-     * The prefix carries the role rather than the size alone: `body1` and
-     * `helper1` are both `textXs` and differ in weight and colour.
-     *
-     * @default "body1"
+     * The role and size of the text, as one value. **The number runs opposite to HTML heading
+     * convention: 3 is the largest of its group and 1 the smallest.** `title3` is `text3xl` and
+     * `title1` is `textXl`; `heading3` is `textLg` and `heading1` is `textSm`. Reading `title1` as
+     * "the primary title" gives you the smallest one.
      */
     variant?: TextVariant;
 };
@@ -6602,38 +6316,22 @@ type CodeEditorProps = Omit<React.ComponentProps<"textarea">, "value" | "default
     /** Marks the control invalid: sets `aria-invalid` and the invalid styling. */
     invalid?: boolean;
     /**
-     * Render a line-number gutter, and mark the line the caret is on.
-     *
-     * Off by default: on the four-line snippets this component is for, numbers are a column of noise
-     * that also costs horizontal space. One property rather than two, because a gutter that does not
-     * say where you are and a band with nothing to count against are each half an affordance — this
-     * is `lineNumbers()`, `highlightActiveLine()` and `highlightActiveLineGutter()` as CodeMirror's
-     * own default setup bundles them.
+     * Render a line-number gutter, and mark the line the caret is on. Off by default: on the four-
+     * line snippets this component is for, numbers are a column of noise that also costs horizontal
+     * space.
      */
     showLineNumbers?: boolean;
     /**
-     * Problems the CALLER found, one per line. Nothing here computes them.
-     *
-     * Rendered as a wavy rule under the line and a coloured gutter number, and enumerated in a
-     * visually hidden list that is added to the control's `aria-describedby` — so a screen reader
-     * gets the text on focus rather than a colour it cannot see. Deliberately NOT announced live:
-     * diagnostics normally change on every keystroke, and a live region that fires on every keystroke
-     * is noise. A caller who wants an announcement owns the timing, and owns the data already.
+     * Problems the CALLER found, one per line. Nothing here computes them. Rendered as a wavy rule
+     * under the line and a coloured gutter number, and enumerated in a visually hidden list that is
+     * added to the control's `aria-describedby` — so a screen reader gets the text on focus rather
+     * than a colour it cannot see.
      */
     diagnostics?: readonly CodeDiagnostic[];
     /**
      * Reformat the buffer. The caller supplies the formatter; this component supplies the keystroke,
-     * the caret, and the announcement.
-     *
-     * Bound to **Shift+Alt+F**, VS Code's "Format Document", and to a quiet button revealed on hover.
-     * May be synchronous or async. While one call is in flight another is dropped rather than queued,
-     * a result whose request has been superseded is discarded, and a result that arrives after the
-     * author has typed is discarded too and reported through `onFormatError` — applying it would
-     * silently delete what they typed. Never runs on a `readOnly` or `disabled` editor.
-     *
-     * The returned string is committed exactly like a keystroke, through `onValueChange`: a
-     * controlled editor that does not accept it does not change, which is the same contract typing
-     * already has.
+     * the caret, and the announcement. Bound to **Shift+Alt+F**, VS Code's "Format Document", and to
+     * a quiet button revealed on hover.
      */
     onFormat?: (value: string) => string | Promise<string>;
     /** Called when the formatter threw, rejected, or its result had to be discarded. */
@@ -6660,29 +6358,12 @@ declare const CodeEditor: React.ForwardRefExoticComponent<Omit<CodeEditorProps,
 /**
  * Tokenization for the code surfaces. Prism grammars via refractor, on a registry that starts
  * empty and carries exactly the ten shipped languages.
- *
- * WHY refractor AND WHY ONLY TEN — CODE-HIGHLIGHTING-DECISION.md has the comparison, the measured
- * sizes and the rejected alternatives. The two facts that matter when editing this file:
- *
- *  - refractor emits DATA (a hast tree), never HTML, so nothing here needs `innerHTML` and there is
- *    no raw-markup entry point to guard. `highlightCode` takes a string and returns plain objects.
- *  - `refractor/core` starts with no grammars, and each grammar is its own module. The ten below
- *    cost 20,683 B gzip together; the all-languages entry would cost 219,904 B. Adding one here
- *    is a measurable decision, which is why `registerCodeLanguage` exists instead — a consumer who
- *    needs Python imports that one grammar module and pays for Python.
  */
 /**
- * A Prism grammar, as its own module default-exports it.
- *
- * Described STRUCTURALLY rather than as refractor's own `Syntax` type, and that is load-bearing:
- * this type reaches the published declarations, and a consumer has not installed refractor, so an
- * import of it there would resolve to nothing. TypeScript does not error on an unresolved import
- * inside a `.d.ts` under `skipLibCheck` — it widens the type to `any` and says nothing, which is
- * how a whole package's props once went untyped in two pilot MFEs. `gate:dts-self-contained` is
- * what catches that, and it caught this.
- *
- * A grammar is a function carrying these two properties; the call signature is refractor's
- * business, so only the properties are described here.
+ * A Prism grammar, as its own module default-exports it. Described STRUCTURALLY rather than as
+ * refractor's own `Syntax` type, and that is load-bearing: this type reaches the published
+ * declarations, and a consumer has not installed refractor, so an import of it there would resolve
+ * to nothing.
  */
 type CodeGrammar = {
     displayName: string;
@@ -6697,13 +6378,9 @@ type CodeGrammar = {
 declare const CODE_LANGUAGES: readonly ["bash", "css", "html", "javascript", "json", "jsx", "markdown", "tsx", "typescript", "yaml"];
 type CodeLanguage = (typeof CODE_LANGUAGES)[number];
 /**
- * Teach the code surfaces one more Prism grammar.
- *
- * Import the grammar module for the language you need from refractor and pass its default export;
- * the component docs carry a copyable example. You pay for that grammar and nothing else.
- *
- * Idempotent, synchronous, and safe to call during module initialization — it touches no DOM and
- * reads no browser global, so it is equally valid on a server.
+ * Teach the code surfaces one more Prism grammar. Import the grammar module for the language you
+ * need from refractor and pass its default export; the component docs carry a copyable example.
+ * You pay for that grammar and nothing else.
  */
 declare function registerCodeLanguage(syntax: CodeGrammar): void;
 /** True when `language` (name or alias) has a grammar and will actually be highlighted. */
@@ -9633,13 +9310,9 @@ type PaginationMeta = {
  */
 declare function calculatePagination(params: PaginationParams): PaginationMeta;
 /**
- * Clamp a page number to valid bounds.
- *
+ * Clamp a page number to valid bounds. ```tsx clampPage(5, 3) // Returns 3 (clamped to max)
+ * clampPage(0, 3) // Returns 1 (clamped to min) ```
  * @example
- * ```tsx
- * clampPage(5, 3) // Returns 3 (clamped to max)
- * clampPage(0, 3) // Returns 1 (clamped to min)
- * ```
  */
 declare function clampPage(page: number, totalPages: number): number;
 /** Represents a page number or an ellipsis marker in pagination */
@@ -9652,21 +9325,7 @@ type PageItem = {
 };
 /**
  * Generate page numbers with ellipsis for pagination UI.
- *
- * Pattern rules:
- * - Fixed slot count: always shows TOTAL_SLOTS items (default: 7)
- * - Right ellipsis when not near end: [pages..., ..., lastPage]
- * - Near end: expanded window with no ellipsis
- * - Ellipsis is clickable and jumps to midpoint
- *
  * @example
- * ```tsx
- * getPageNumbers(1, 10)   // [1, 2, 3, 4, 5, ellipsis→7, 10] (7 items)
- * getPageNumbers(5, 10)   // [3, 4, 5, 6, 7, ellipsis→8, 10] (7 items)
- * getPageNumbers(7, 10)   // [4, 5, 6, 7, 8, 9, 10] (7 items - expanded)
- * getPageNumbers(10, 10)  // [4, 5, 6, 7, 8, 9, 10] (7 items - expanded)
- * getPageNumbers(2, 5)    // [1, 2, 3, 4, 5] (5 items - small table)
- * ```
  */
 declare function getPageNumbers(currentPage: number, totalPages: number, siblingCount?: number): PageItem[];