@signal9/era-ui 30.8.0 → 32.0.0

package/dist/generated-docs/llms-full.txt

@@ -63,9 +63,13 @@ Classes, not components — they need no import beyond the stylesheet. Reach for
 - `era-ink-center` — on a native single-line <input> (or the text layer that must mirror one) inside a fixed-height field — never alongside era-text-trim.
 - `era-token-ink` — the ink centring for a token pill — a badge, a KV value, any short caps-or-digits label in a fixed-height box, CENTRED horizontally and with no icon sibling. For a left-aligned sentence-case label use era-label-ink; when an icon really must sit beside the text, see the note there.
 - `era-label-ink` — the ink centring for a fixed-height control holding ONE line of sentence-case text and no icon — a menu item, a nav trigger, a button label. Never alongside `truncate` (the trimmed box becomes the clip).
-- `glass-blur` — the backdrop blur for a floating panel (popover, dialog, taskbar) — it applies only inside a data-surface="glass" subtree and is inert elsewhere, so it is safe to leave on a panel that renders under every surface.
-- `rounded-row` — the radius for a row inside a container that pads it by the gutter — a nav rail, a command list, any scrolling list of controls. For a row in a menu PANEL, whose inset is the surface-owned frame rather than the gutter, use rounded-menu-item.
+- `surface-backdrop` — the surface-aware backdrop treatment without choosing a fill or relief. Prefer material-popover/material-panel when the element is a complete surface.
+- `material-popover` — a floating transient surface: menus, popovers, tooltips, pickers, toasts. Binds its raised fill, floating relief, and backdrop treatment atomically.
+- `material-panel` — a floating persistent surface: dialogs, sheets, panes, inspectors. Binds its resting fill, floating relief, and backdrop treatment atomically.
+- `pressable` — the physical press contract on a control whose direct content plane is marked data-era-press-content. The surface owns relief/travel; the component may scale travel with --era-press-scale.
+- `tier-icon · tier-pill · tier-chip · tier-control · tier-bar` — BOUNDED GEOMETRY — height and radius are one decision.
 - `h-line` — the height of one line of the element's own text — a skeleton standing in for a line, a spacer that must match a line box.
+- `era-track-well` — instead of `shadow-well` on a track whose value is painted by a child that covers the box — a progress/meter/slider track, a custom gauge. For a well holding ordinary content, `shadow-well` is still right.
 - `era-skeleton-pulse` — Skeleton's pulse, on the MOTION AXIS.
 - `era-shimmer` — the in-progress text treatment — put it on a "working…" / "thinking…" label while a task streams, instead of a spinner beside the text.
 - `era-collapse` — the height sweep for a bits-ui Collapsible.Content — put it on the Content element itself (it carries its own overflow: hidden).
@@ -86,12 +90,12 @@ Classes, not components — they need no import beyond the stylesheet. Reach for
 - `bg-well · text-well · border-well · bg-elevated · text-elevated · border-elevated · bg-highlight · text-highlight · … (12 in all)` — Surface fills — bg-well is the surface's own resting fill (pairs with
 - `p-gutter · px-gutter · py-gutter · gap-gutter · p-panel · px-panel · py-panel · gap-panel · … (24 in all)` — THE SPACING SCALE — one entry per token, from which Tailwind derives the
 - `p-inset-pill · px-inset-pill · py-inset-pill · gap-inset-pill · p-inset-chip · px-inset-chip · py-inset-chip · gap-inset-chip · … (12 in all)` — text-symmetric content padding — (tier − text)/2, the inset that vertically centres body text in its tier; px-inset-control is a text button's side padding, p-inset-control a code block's.
-- `p-icon-inset-pill · px-icon-inset-pill · py-icon-inset-pill · gap-icon-inset-pill · p-icon-inset-chip · px-icon-inset-chip · py-icon-inset-chip · gap-icon-inset-chip · … (36 in all)` — the concentric inset for a nested pair — (h-container − h-child)/2, the gap that makes a child control sit evenly inside its container, and the radius step that keeps their corners concentric. Named for the pair it joins: gap-icon-inset-control seats an icon in a control.
+- `p-icon-inset-pill · px-icon-inset-pill · py-icon-inset-pill · gap-icon-inset-pill · p-icon-inset-chip · px-icon-inset-chip · py-icon-inset-chip · gap-icon-inset-chip · … (40 in all)` — the concentric inset for a nested pair — (h-container − h-child)/2, the gap that makes a child control sit evenly inside its container, and the radius step that keeps their corners concentric. Named for the pair it joins: gap-icon-inset-control seats an icon in a control.
 - `p-glyph-icon · px-glyph-icon · py-glyph-icon · gap-glyph-icon · p-glyph-pill · px-glyph-pill · py-glyph-pill · gap-glyph-pill` — the glyph size for a tier — the INK inside the box, not the box (size-glyph-pill is the dismiss × in a pill, size-pill is the pill).
 - `bg-field · text-field · border-field · bg-field-highlight · text-field-highlight · border-field-highlight` — the recessed field fill — bg-field is a text input's resting well, bg-field-highlight its focused/hovered face.
 - `ease-base` — Motion — bare transition utilities default to the motion axis, so
 - `bg-divider · text-divider · border-divider · bg-divider-faded · text-divider-faded · border-divider-faded · bg-background · text-background · … (66 in all)` — Surface divider colors: border-divider, bg-divider-faded, …
-- `bg-fill · text-fill · border-fill · bg-link · text-link · border-link · bg-primary · text-primary · … (33 in all)` — The standing pill fill — --era-fill, the latched counterpart of the
+- `bg-fill · text-fill · border-fill · bg-link · text-link · border-link · bg-primary · text-primary · … (39 in all)` — The standing pill fill — --era-fill, the latched counterpart of the
 
 Full reference (what each emits, when to use it): `/utilities.md`. Machine-readable list: `/utilities.json`.
 
@@ -153,7 +157,7 @@ The CSS classes era ships alongside the components — links, ink-centred text,
 
 ## Overview
 
-era's styling API is pure class names — write `h-control rounded-control px-gutter shadow`,
+era's styling API is pure class names — write `tier-control px-gutter shadow`,
 never the `h-(--era-h-control)` var-class spelling. Everything below rides along
 with the stylesheet and needs no import:
 
@@ -162,7 +166,7 @@ import "@signal9/era-ui/css";
 ```
 
 ```svelte
-<button class="h-control rounded-control px-inset-control shadow text-body">era styled</button>
+<button class="tier-control px-inset-control shadow text-body">era styled</button>
 ```
 
 Alongside the `@utility` classes referenced below, era registers named theme
@@ -172,6 +176,7 @@ motion):
 
 | Stock-looking class | What it resolves to |
 |---|---|
+| `tier-icon/pill/chip/control/bar` | indivisible bounded height + concentric radius |
 | `rounded-icon/pill/chip/control/bar` | the concentric radius ladder (collapses on `data-corners="square"`) |
 | `rounded-menu-item` | menu-row radius, concentric inside a `rounded-control` panel |
 | `shadow` / `shadow-lg` | resting control edge / floating panel chrome, per surface |
@@ -197,10 +202,13 @@ The spacing names (`gutter`, `card`, `panel`, `content`, `menu`, `field`, the
 `inset-*` and concentric `*-inset-*` insets, `glyph-*`) are registered as a
 Tailwind spacing scale, so every prefix derives automatically: `p-`, `px-`,
 `pt-`, `mt-`, `gap-`, `gap-x-`, `inset-`, `translate-`, and the rest. The TIER
-names (`icon`, `pill`, `chip`, `control`, `bar`) are heights, not spacing, so
+names (`icon`, `pill`, `chip`, `control`, `bar`) are dimensions, not spacing, so
 they are registered per prefix instead — `h-`, `w-`, `min-h-`, `min-w-` and
 `size-` — and the two vocabularies deliberately share no word. Putting a tier
 in the spacing scale would silently make `px-control` mean 24px of padding.
+For chrome, use `tier-T`, which binds `h-T` and `rounded-T`; use the separate
+dimension/radius names only for width, minimums, unbounded surfaces, or
+asymmetric/docked corners.
 
 The var form (`h-(--era-h-control)`) still works and is the escape hatch for a
 token with no registered name — `--era-sp`, the press-sink offsets, anything
@@ -218,9 +226,13 @@ source uses it where a name exists.
 | `era-ink-center` | on a native single-line <input> (or the text layer that must mirror one) inside a fixed-height field — never alongside era-text-trim. |
 | `era-token-ink` | the ink centring for a token pill — a badge, a KV value, any short caps-or-digits label in a fixed-height box, CENTRED horizontally and with no icon sibling. For a left-aligned sentence-case label use era-label-ink; when an icon really must sit beside the text, see the note there. |
 | `era-label-ink` | the ink centring for a fixed-height control holding ONE line of sentence-case text and no icon — a menu item, a nav trigger, a button label. Never alongside `truncate` (the trimmed box becomes the clip). |
-| `glass-blur` | the backdrop blur for a floating panel (popover, dialog, taskbar) — it applies only inside a data-surface="glass" subtree and is inert elsewhere, so it is safe to leave on a panel that renders under every surface. |
-| `rounded-row` | the radius for a row inside a container that pads it by the gutter — a nav rail, a command list, any scrolling list of controls. For a row in a menu PANEL, whose inset is the surface-owned frame rather than the gutter, use rounded-menu-item. |
+| `surface-backdrop` | the surface-aware backdrop treatment without choosing a fill or relief. Prefer material-popover/material-panel when the element is a complete surface. |
+| `material-popover` | a floating transient surface: menus, popovers, tooltips, pickers, toasts. Binds its raised fill, floating relief, and backdrop treatment atomically. |
+| `material-panel` | a floating persistent surface: dialogs, sheets, panes, inspectors. Binds its resting fill, floating relief, and backdrop treatment atomically. |
+| `pressable` | the physical press contract on a control whose direct content plane is marked data-era-press-content. The surface owns relief/travel; the component may scale travel with --era-press-scale. |
+| `tier-icon` `tier-pill` `tier-chip` `tier-control` `tier-bar` | — |
 | `h-line` | the height of one line of the element's own text — a skeleton standing in for a line, a spacer that must match a line box. |
+| `era-track-well` | instead of `shadow-well` on a track whose value is painted by a child that covers the box — a progress/meter/slider track, a custom gauge. For a well holding ordinary content, `shadow-well` is still right. |
 | `era-skeleton-pulse` | — |
 | `era-shimmer` | the in-progress text treatment — put it on a "working…" / "thinking…" label while a task streams, instead of a spinner beside the text. |
 | `era-collapse` | the height sweep for a bits-ui Collapsible.Content — put it on the Content element itself (it carries its own overflow: hidden). |
@@ -241,12 +253,12 @@ source uses it where a name exists.
 | `bg-well` `text-well` `border-well` `bg-elevated` `text-elevated` `border-elevated` `bg-highlight` `text-highlight` `border-highlight` `bg-overlay` `text-overlay` `border-overlay` | — |
 | `p-gutter` `px-gutter` `py-gutter` `gap-gutter` `p-panel` `px-panel` `py-panel` `gap-panel` `p-card` `px-card` `py-card` `gap-card` `p-content` `px-content` `py-content` `gap-content` `p-menu` `px-menu` `py-menu` `gap-menu` `p-field` `px-field` `py-field` `gap-field` | — |
 | `p-inset-pill` `px-inset-pill` `py-inset-pill` `gap-inset-pill` `p-inset-chip` `px-inset-chip` `py-inset-chip` `gap-inset-chip` `p-inset-control` `px-inset-control` `py-inset-control` `gap-inset-control` | text-symmetric content padding — (tier − text)/2, the inset that vertically centres body text in its tier; px-inset-control is a text button's side padding, p-inset-control a code block's. |
-| `p-icon-inset-pill` `px-icon-inset-pill` `py-icon-inset-pill` `gap-icon-inset-pill` `p-icon-inset-chip` `px-icon-inset-chip` `py-icon-inset-chip` `gap-icon-inset-chip` `p-icon-inset-control` `px-icon-inset-control` `py-icon-inset-control` `gap-icon-inset-control` `p-icon-inset-bar` `px-icon-inset-bar` `py-icon-inset-bar` `gap-icon-inset-bar` `p-pill-inset-chip` `px-pill-inset-chip` `py-pill-inset-chip` `gap-pill-inset-chip` `p-pill-inset-control` `px-pill-inset-control` `py-pill-inset-control` `gap-pill-inset-control` `p-pill-inset-bar` `px-pill-inset-bar` `py-pill-inset-bar` `gap-pill-inset-bar` `p-chip-inset-control` `px-chip-inset-control` `py-chip-inset-control` `gap-chip-inset-control` `p-chip-inset-bar` `px-chip-inset-bar` `py-chip-inset-bar` `gap-chip-inset-bar` | the concentric inset for a nested pair — (h-container − h-child)/2, the gap that makes a child control sit evenly inside its container, and the radius step that keeps their corners concentric. Named for the pair it joins: gap-icon-inset-control seats an icon in a control. |
+| `p-icon-inset-pill` `px-icon-inset-pill` `py-icon-inset-pill` `gap-icon-inset-pill` `p-icon-inset-chip` `px-icon-inset-chip` `py-icon-inset-chip` `gap-icon-inset-chip` `p-icon-inset-control` `px-icon-inset-control` `py-icon-inset-control` `gap-icon-inset-control` `p-icon-inset-bar` `px-icon-inset-bar` `py-icon-inset-bar` `gap-icon-inset-bar` `p-pill-inset-chip` `px-pill-inset-chip` `py-pill-inset-chip` `gap-pill-inset-chip` `p-pill-inset-control` `px-pill-inset-control` `py-pill-inset-control` `gap-pill-inset-control` `p-pill-inset-bar` `px-pill-inset-bar` `py-pill-inset-bar` `gap-pill-inset-bar` `p-chip-inset-control` `px-chip-inset-control` `py-chip-inset-control` `gap-chip-inset-control` `p-chip-inset-bar` `px-chip-inset-bar` `py-chip-inset-bar` `gap-chip-inset-bar` `p-control-inset-bar` `px-control-inset-bar` `py-control-inset-bar` `gap-control-inset-bar` | the concentric inset for a nested pair — (h-container − h-child)/2, the gap that makes a child control sit evenly inside its container, and the radius step that keeps their corners concentric. Named for the pair it joins: gap-icon-inset-control seats an icon in a control. |
 | `p-glyph-icon` `px-glyph-icon` `py-glyph-icon` `gap-glyph-icon` `p-glyph-pill` `px-glyph-pill` `py-glyph-pill` `gap-glyph-pill` | the glyph size for a tier — the INK inside the box, not the box (size-glyph-pill is the dismiss × in a pill, size-pill is the pill). |
 | `bg-field` `text-field` `border-field` `bg-field-highlight` `text-field-highlight` `border-field-highlight` | the recessed field fill — bg-field is a text input's resting well, bg-field-highlight its focused/hovered face. |
 | `ease-base` | — |
 | `bg-divider` `text-divider` `border-divider` `bg-divider-faded` `text-divider-faded` `border-divider-faded` `bg-background` `text-background` `border-background` `bg-foreground` `text-foreground` `border-foreground` `bg-1` `text-1` `border-1` `bg-2` `text-2` `border-2` `bg-3` `text-3` `border-3` `bg-4` `text-4` `border-4` `bg-5` `text-5` `border-5` `bg-6` `text-6` `border-6` `bg-7` `text-7` `border-7` `bg-8` `text-8` `border-8` `bg-9` `text-9` `border-9` `bg-10` `text-10` `border-10` `bg-11` `text-11` `border-11` `bg-12` `text-12` `border-12` `bg-border` `text-border` `border-border` `bg-surface` `text-surface` `border-surface` `bg-hover` `text-hover` `border-hover` `bg-fg` `text-fg` `border-fg` `bg-bright` `text-bright` `border-bright` `bg-muted` `text-muted` `border-muted` | — |
-| `bg-fill` `text-fill` `border-fill` `bg-link` `text-link` `border-link` `bg-primary` `text-primary` `border-primary` `bg-primary-fg` `text-primary-fg` `border-primary-fg` `bg-primary-hover` `text-primary-hover` `border-primary-hover` `bg-destructive` `text-destructive` `border-destructive` `bg-destructive-fg` `text-destructive-fg` `border-destructive-fg` `bg-success` `text-success` `border-success` `bg-success-fg` `text-success-fg` `border-success-fg` `bg-warning` `text-warning` `border-warning` `bg-warning-fg` `text-warning-fg` `border-warning-fg` | — |
+| `bg-fill` `text-fill` `border-fill` `bg-link` `text-link` `border-link` `bg-primary` `text-primary` `border-primary` `bg-primary-fg` `text-primary-fg` `border-primary-fg` `bg-primary-hover` `text-primary-hover` `border-primary-hover` `bg-destructive` `text-destructive` `border-destructive` `bg-destructive-fg` `text-destructive-fg` `border-destructive-fg` `bg-success` `text-success` `border-success` `bg-success-fg` `text-success-fg` `border-success-fg` `bg-warning` `text-warning` `border-warning` `bg-warning-fg` `text-warning-fg` `border-warning-fg` `bg-info` `text-info` `border-info` `bg-info-fg` `text-info-fg` `border-info-fg` | — |
 
 ## era-interactive
 
@@ -599,64 +611,104 @@ Declared in `index.css`.
 }
 ```
 
-## glass-blur
+## surface-backdrop
 
-**Use it for:** the backdrop blur for a floating panel (popover, dialog, taskbar) — it applies only inside a data-surface="glass" subtree and is inert elsewhere, so it is safe to leave on a panel that renders under every surface.
+**Use it for:** the surface-aware backdrop treatment without choosing a fill or relief. Prefer material-popover/material-panel when the element is a complete surface.
 
-Tailwind v4 cannot resolve var() inside backdrop-blur-[], so the filter
-is a registered utility, gated to glass subtrees.
+Declared in `index.css`.
 
-It lives HERE rather than in surfaces/glass.css, where a surface's own
-chrome would naturally sit, because glass.css is imported into a cascade
-layer and `@utility` cannot be nested inside one. Surface-scoped RULES stay
-in their surface file; surface-scoped UTILITIES have to come out.
+```css
+@utility surface-backdrop {
+	backdrop-filter: var(--era-backdrop-filter);
+	-webkit-backdrop-filter: var(--era-backdrop-filter);
+}
+```
+
+## material-popover
+
+**Use it for:** a floating transient surface: menus, popovers, tooltips, pickers, toasts. Binds its raised fill, floating relief, and backdrop treatment atomically.
 
 Declared in `index.css`.
 
 ```css
-@utility` cannot be nested inside one. Surface-scoped RULES stay
- * in their surface file; surface-scoped UTILITIES have to come out.
- *
- * @use the backdrop blur for a floating panel (popover, dialog, taskbar) — it
- * applies only inside a data-surface="glass" subtree and is inert elsewhere,
- * so it is safe to leave on a panel that renders under every surface. */
-@utility glass-blur {
-	[data-surface='glass'] & {
-		backdrop-filter: blur(var(--era-blur)) saturate(var(--era-saturate));
-		-webkit-backdrop-filter: blur(var(--era-blur)) saturate(var(--era-saturate));
-	}
+@utility material-popover {
+	background-color: var(--era-surface-bg-elevated);
+	box-shadow: var(--era-shadow-lg);
+	backdrop-filter: var(--era-backdrop-filter);
+	-webkit-backdrop-filter: var(--era-backdrop-filter);
 }
 ```
 
-## rounded-row
+## material-panel
 
-**Use it for:** the radius for a row inside a container that pads it by the gutter — a nav rail, a command list, any scrolling list of controls. For a row in a menu PANEL, whose inset is the surface-owned frame rather than the gutter, use rounded-menu-item.
+**Use it for:** a floating persistent surface: dialogs, sheets, panes, inspectors. Binds its resting fill, floating relief, and backdrop treatment atomically.
 
-THE ROW RADIUS — concentricity for a row that is inset, WITH its inset intact.
+Declared in `index.css`.
 
-The law is rd_outer − rd_inner = gap. A row inside a container that pads it by
-the gutter therefore takes the container's radius MINUS the gutter — and no
-tier radius equals that at more than one density, which is why reaching for
-`rounded-control` and hoping looks wrong: in a control-radius pane the row and
-the pane end up with identical curvature separated by 5px of gap, two arcs at
-one corner with no relationship.
+```css
+@utility material-panel {
+	background-color: var(--era-surface-bg);
+	box-shadow: var(--era-shadow-lg);
+	backdrop-filter: var(--era-backdrop-filter);
+	-webkit-backdrop-filter: var(--era-backdrop-filter);
+}
+```
 
-The alternative — deleting the gap so equal radii become legal — is the wrong
-trade and was briefly shipped. The ladder exists so a gap and concentric
-corners COEXIST; spending one to buy the other gives up the thing it is for.
+## pressable
 
-The calc runs on the ROW, not on the container, which is what makes it
-automatic: `--era-container-rd` is inherited, so a container that is not
-control-radius publishes its own and every row inside re-derives. era's
-command palette does exactly that — it is rd-bar, so its rows resolve to
-rd-bar − gap, which IS rd-control (control-inset-bar is the gutter), and the
-palette's geometry is unchanged by this.
+**Use it for:** the physical press contract on a control whose direct content plane is marked data-era-press-content. The surface owns relief/travel; the component may scale travel with --era-press-scale.
 
 Declared in `index.css`.
 
 ```css
-@utility rounded-row {
-	border-radius: max(0px, calc(var(--era-container-rd, var(--era-rd-control)) - var(--era-gap)));
+@utility pressable {
+	&:active {
+		box-shadow: var(--era-shadow-pressed);
+	}
+
+	&:active > [data-era-press-content] {
+		translate: var(--era-press-effective-x, var(--era-press-sink-x))
+			var(--era-press-effective-y, var(--era-press-sink-y));
+	}
+}
+```
+
+## tier-icon · tier-pill · tier-chip · tier-control · tier-bar
+
+BOUNDED GEOMETRY — height and radius are one decision.
+
+A tier is a geometric type, not two classes a caller must remember to keep in
+sync. `tier-control` establishes h-control AND rd-control; the radius ladder
+then guarantees rd_outer − rd_inner = (h_outer − h_inner)/2 for every pair.
+Width remains the component's decision: a row stretches, a button adds
+min-w-control, and a square control adds w-control.
+
+Declared in `index.css`.
+
+```css
+@utility tier-icon {
+	height: var(--era-h-icon);
+	border-radius: var(--era-rd-icon);
+}
+
+@utility tier-pill {
+	height: var(--era-h-pill);
+	border-radius: var(--era-rd-pill);
+}
+
+@utility tier-chip {
+	height: var(--era-h-chip);
+	border-radius: var(--era-rd-chip);
+}
+
+@utility tier-control {
+	height: var(--era-h-control);
+	border-radius: var(--era-rd-control);
+}
+
+@utility tier-bar {
+	height: var(--era-h-bar);
+	border-radius: var(--era-rd-bar);
 }
 ```
 
@@ -681,6 +733,50 @@ Declared in `index.css`.
 }
 ```
 
+## era-track-well
+
+**Use it for:** instead of `shadow-well` on a track whose value is painted by a child that covers the box — a progress/meter/slider track, a custom gauge. For a well holding ordinary content, `shadow-well` is still right.
+
+A WELL THAT SURVIVES BEING FILLED.
+
+`shadow-well` is an INSET shadow, and an inset shadow belongs to the
+element's background layer — it paints under the element's own descendants.
+That is invisible on a well holding text (a checkbox, a code block: the
+chrome runs around the content) and wrong the moment something paints the
+whole box. Meter, Progress and the Slider track all do exactly that: an
+opaque child, `translateX`-ed to the value. So the well survived only where
+the track was EMPTY — a half-full meter on bevel had a chisel to the right
+of the value and none to the left, which reads as a hole with a sticker
+over it rather than a level inside a well.
+
+The fix is painting order, not geometry: the same `--era-shadow-well` on a
+pseudo-element that is the element's LAST child, so it lands above the fill.
+The fill still spans the full box — nothing is inset, no radius is
+re-derived, and 0% and 100% keep their exact ends. The `position: relative`
+is load-bearing (the overlay resolves against this box) and `inherit` on the
+radius keeps it honest under `data-corners="square"`.
+
+Surface-agnostic on purpose. It reads the same token every well reads, so
+glass's hairline rim is restored by the same line that restores bevel's
+chisel, and flat — where the token is `none` — renders exactly as before.
+Reported against bevel by a consumer; it was never a bevel bug.
+
+Declared in `index.css`.
+
+```css
+@utility era-track-well {
+	position: relative;
+	&::after {
+		content: '';
+		position: absolute;
+		inset: 0;
+		border-radius: inherit;
+		box-shadow: var(--era-shadow-well);
+		pointer-events: none;
+	}
+}
+```
+
 ## era-skeleton-pulse
 
 Skeleton's pulse, on the MOTION AXIS.
@@ -1106,8 +1202,8 @@ Declared in `index.css`.
 ## bg-well · text-well · border-well · bg-elevated · text-elevated · border-elevated · bg-highlight · text-highlight · … (12 in all)
 
 Surface fills — bg-well is the surface's own resting fill (pairs with
-shadow-well for recessed chrome), bg-elevated the raised tier (pairs with
-shadow-lg + glass-blur for floating chrome), bg-highlight the transient
+shadow-well for recessed chrome), bg-elevated the raised tier,
+bg-highlight the transient
 hover/focus/keyboard wash (pairs with shadow-highlight; latched states
 stay on opaque bg-hover), bg-overlay the modal scrim.
 
@@ -1170,7 +1266,7 @@ Declared in `index.css`.
 }
 ```
 
-## p-icon-inset-pill · px-icon-inset-pill · py-icon-inset-pill · gap-icon-inset-pill · p-icon-inset-chip · px-icon-inset-chip · py-icon-inset-chip · gap-icon-inset-chip · … (36 in all)
+## p-icon-inset-pill · px-icon-inset-pill · py-icon-inset-pill · gap-icon-inset-pill · p-icon-inset-chip · px-icon-inset-chip · py-icon-inset-chip · gap-icon-inset-chip · … (40 in all)
 
 **Use it for:** the concentric inset for a nested pair — (h-container − h-child)/2, the gap that makes a child control sit evenly inside its container, and the radius step that keeps their corners concentric. Named for the pair it joins: gap-icon-inset-control seats an icon in a control.
 
@@ -1187,6 +1283,7 @@ Declared in `index.css`.
 	--spacing-pill-inset-bar: var(--era-pill-inset-bar);
 	--spacing-chip-inset-control: var(--era-chip-inset-control);
 	--spacing-chip-inset-bar: var(--era-chip-inset-bar);
+	--spacing-control-inset-bar: var(--era-control-inset-bar);
 }
 ```
 
@@ -1265,7 +1362,7 @@ Declared in `index.css`.
 }
 ```
 
-## bg-fill · text-fill · border-fill · bg-link · text-link · border-link · bg-primary · text-primary · … (33 in all)
+## bg-fill · text-fill · border-fill · bg-link · text-link · border-link · bg-primary · text-primary · … (39 in all)
 
 The standing pill fill — --era-fill, the latched counterpart of the
 transient highlight. Surface-owned: a composing wash on flat/bevel, the
@@ -1286,6 +1383,8 @@ Declared in `index.css`.
 	--color-success-fg: var(--color-success-fg);
 	--color-warning: var(--color-warning);
 	--color-warning-fg: var(--color-warning-fg);
+	--color-info: var(--color-info);
+	--color-info-fg: var(--color-info-fg);
 }
 ```
 
@@ -1456,7 +1555,7 @@ Inherits all props from `HTMLAttributes<HTMLSpanElement>`.
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
 | `ref?` | `HTMLSpanElement \| null` | `null` | bindable |
-| `tone?` | `'default' \| 'accent' \| 'destructive' \| 'success' \| 'warning'` | `'default'` | — |
+| `tone?` | `'default' \| 'accent' \| 'destructive' \| 'success' \| 'warning' \| 'info'` | `'default'` | — |
 | `lead?` | `Snippet` | — | Icon rendered BEFORE the label, outside it. Use this rather than putting
 an icon in `children`: the label then gets its own box, which is the only
 place era's ink centring can reach. |
@@ -1547,10 +1646,28 @@ Inherits all props from `HTMLAttributes<HTMLDivElement>`.
 |------|------|---------|-------|
 | `ref?` | `HTMLDivElement \| null` | `null` | bindable |
 | `size?` | `'chip' \| 'control' \| 'bar'` | `'bar'` | Height tier (scales with density). Default `lg` — a full toolbar. |
-| `content?` | `'tier' \| 'pill'` | `'tier'` | Tier of the controls inside — drives the bar's padding and gap so they
-stay concentric to them. `tier` (default) is one tier smaller; `pill` is
-the compact pairing (pills/fields in an sm or md bar). |
-| `divider?` | `boolean` | `false` | The flush cap-a-panel chrome: outset divider below, bottom rd-md. |
+| `content?` | `BarContent` | — | Tier of the controls inside — drives the bar's padding and gap so they
+stay concentric to them. Omit this for the next canonical rung, or name
+the actual tier when the contents are smaller. |
+| `divider?` | `boolean` | `false` | The flush cap-a-panel chrome: an outset rule below, and a rounded
+BOTTOM only — the top defers to the panel's own radius.
+THE BOTTOM RADIUS IS LOAD-BEARING FOR THE RULE. The divider is an
+outset `box-shadow`, so it follows the box's corners: the rounded
+bottom is what curves the line up at the ends and makes the bar read
+as a long pill. Overriding the radius therefore changes the RULE, not
+just the corners. Measured against `cn`:
+- `rounded-none` drops both — a square bar with a dead-straight rule.
+  That is the intended square mode (an in-app Notes bar passes it).
+- `rounded-b-*` or `rounded-b-none` replaces the curve — this is the
+  one that surprises, because the rule changes shape when the caller
+  thought they were only squaring a corner.
+- `rounded-t-*` is SAFE: it wins against `rounded-t-none` and leaves
+  `rounded-b-control` standing, so the curve survives.
+A consumer lost the curve this way. The coupling was already written
+down — on the variant, inside `<script module>`, where someone
+hovering this prop never reaches it. Docs are only as good as the
+place the reader is standing. |
+| `topology?` | `'nested' \| 'docked'` | `'nested'` | `docked` removes one or more exposed curves; strict radius nesting does not apply. |
 | `children?` | `Snippet` | — | — |
 
 <!-- end: bar -->
@@ -1580,7 +1697,7 @@ Inherits all props from `HTMLAttributes<HTMLElement>`.
 |------|------|---------|-------|
 | `ref?` | `HTMLElement \| null` | `null` | bindable |
 | `size?` | `'chip' \| 'control' \| 'bar'` | `'bar'` | Height tier, exactly as Bar's — the geometry is Bar's, not a second copy. |
-| `content?` | `'tier' \| 'pill'` | `'tier'` | Tier of the items inside, so the wall stays concentric to them. |
+| `content?` | `BarContent` | — | Tier of the items inside, so the wall stays concentric to them. |
 | `divider?` | `boolean` | `false` | Draw Bar's flush cap-a-panel rule beneath the bar. Off by default,
 because a nav that sits in a page already has whatever separation the
 layout gives it — and a link-variant nav in particular reads as text,
@@ -1605,6 +1722,13 @@ Inherits all props from `HTMLAnchorAttributes`.
 drops the chrome entirely and renders running text, for a primary nav
 that should read as links rather than a row of raised keycaps. Existing
 bars are byte-identical. |
+| `currentCue?` | `'thickness' \| 'ink' \| 'none'` | `'thickness'` | WHAT MARKS THE CURRENT ITEM. `thickness` (default) is the three-state
+decoration — portable across every theme and font because it is one
+ink at three strengths. `ink` brightens the current item instead, and
+is theme-dependent by construction: era's default themes point
+--color-link at --color-bright, so its delta there is zero. `none`
+silences era's cue entirely, for a consumer painting their own.
+See navItemVariants above for the measurements behind each. |
 | `current?` | `boolean` | `false` | Whether this item points at the page you are on.
 There is deliberately no `active` prop beside this one. `active` would
 be a second source of truth for one fact, and the two drift the moment
@@ -1644,14 +1768,47 @@ Inherits all props from `Button.RootProps`.
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `tone?` | `'default' \| 'accent' \| 'destructive' \| 'success' \| 'warning'` | `'default'` | — |
+| `tone?` | `'default' \| 'accent' \| 'destructive' \| 'success' \| 'warning' \| 'info'` | `'default'` | — |
 | `size?` | `'control' \| 'chip' \| 'pill' \| 'icon'` | `'control'` | — |
 | `variant?` | `'filled' \| 'link'` | `'filled'` | — |
 | `active?` | `boolean` | `false` | — |
 | `icon?` | `boolean` | `false` | — |
-| `loading?` | `boolean` | `false` | When true, disables the button, sets `aria-busy`, and prepends a
-spinner. The existing label stays rendered so focus, click targets,
-and screen-reader accessible names don't change shape mid-flight. |
+| `loading?` | `boolean` | `false` | In flight: disables the button, sets `aria-busy`, and puts a spinner
+over the label.
+THE GEOMETRY DOES NOT MOVE. That is the requirement, not a detail. A
+button is loading because it was just CLICKED, so anything `loading`
+changes about the box moves the page under the pointer that is still
+on it — and a spinner PREPENDED to the label (what this used to do)
+costs an icon's width plus a gap, measured on a wrapping header row
+that reflowed everything beside it. A consumer hit exactly that and
+stopped using the prop, hand-rolling `disabled` + `aria-busy`
+instead, which is the report that produced this note.
+So the spinner is absolutely positioned and takes no part in the
+flex layout, and the label goes to `opacity-0` rather than being
+unmounted: the box that holds the width stays, and the text stays in
+the accessibility tree as the button's accessible name.
+The visible label is therefore HIDDEN in flight — the one thing this
+trades away, and the reason `loadingLabel` exists.
+IF YOU DO NOT WANT A SPINNER, use `busy`. Not showing one is a
+supported posture, not a legacy one — see that prop. |
+| `busy?` | `boolean` | `false` | In flight, WITHOUT a spinner: disables the button and sets `aria-busy`,
+and changes nothing else. The label stays visible and legible.
+This exists because "show a spinner" is a taste, not a requirement,
+and era had only one answer. A consumer whose house style is that
+spinners should not appear had to spell the posture out themselves —
+`disabled` plus a restated `aria-busy` — and rely on knowing that
+`restProps` spreads last, which is a real fact about this component
+that no reader should have to depend on. Two words for two postures
+is clearer than one word plus a workaround.
+`loading` implies this: it is `busy` plus the spinner and the hidden
+label. What you get from `busy` alone is a control that is visibly
+disabled (the era-interactive opacity) and announced as busy, with
+its geometry and its ink untouched — which is also why it needs no
+`loadingLabel`: nothing about the button changed except that you
+cannot press it.
+Reported by a consumer whose user asked for no spinners anywhere.
+They were right that a fix for the width shift did not answer it: a
+spinner that no longer moves its neighbours is still a spinner. |
 | `loadingLabel?` | `string` | — | Screen-reader-only label announced while `loading` is true. |
 | `lead?` | `Snippet` | — | Icon rendered BEFORE the label, outside it. Use this rather than putting
 an icon in `children`: the label then gets its own box, which is the only
@@ -1689,6 +1846,7 @@ snippet's text cannot be read before it renders.
 Only reaches the label when `lead`/`trail` give it its own box. Without
 one the label is an anonymous flex item that no selector can address,
 which is the whole reason those snippets exist. |
+| `topology?` | `'bounded' \| 'docked'` | `'bounded'` | `docked` joins this control to a neighbour and removes one or more curves. |
 | `children?` | `Snippet` | — | — |
 | `ref?` | `(forwarded)` | `null` | bindable |
 
@@ -1799,11 +1957,41 @@ Inherits all props from `ButtonBits`.
 |------|------|---------|-------|
 | `ref?` | `CardElement \| null` | `null` | bindable |
 | `tone?` | `'elevated' \| 'surface' \| 'well' \| 'flat'` | `'elevated'` | Surface tier the card paints on.
-- `elevated` (default): the lifted surface. Use on the page background.
-- `surface`: the base surface tier. Use when nesting cards inside another elevated container.
-- `well`: recessed. For content the surrounding UI puts INTO the card — a tool's
-  output pane, a transcript body — the container twin of a text field's fill.
-- `flat`: no background; only the rounded/padded shell. For grouping content visually without adding contrast. |
+- `elevated` (default): the lifted surface, with a resting shadow. Use
+  on the page background.
+- `surface`: the base surface tier, no shadow. Use when nesting cards
+  inside another elevated container.
+- `well`: recessed. For content the surrounding UI puts INTO the card —
+  a tool's output pane, a transcript body — the container twin of a
+  text field's fill.
+- `flat`: no background; only the rounded/padded shell. For grouping
+  content visually without adding contrast.
+READ THE CLASSES AND THEY LOOK SWAPPED. They are not, and this is
+worth a sentence because a consumer read them, believed it, and
+shipped flat cards for months. `surface` paints `bg-well` and `well`
+paints `bg-field`, because era's utility names describe FILLS rather
+than tiers: `bg-well` is the surface's own resting fill (it is what a
+panel is painted with, and it pairs with `shadow-well` when you want
+recessed chrome), and `bg-field` is the recessed fill a text input
+sits in. The tone names are the tiers; the class names are the paints.
+A CARD THAT IS PRESSABLE SHOULD USUALLY BE `elevated`. Passing `href`
+or `onclick` turns on the interactive face — hover, focus, press — but
+it deliberately does NOT override the tier you asked for, so a
+`surface` link card does not get the raised tier's separation and can
+read flatter than the static cards around it. That combination was
+reported as a bug and it is a choice: a tone that silently changed
+under an event handler would be a worse one.
+HOW THE TIERS DIFFER IS SURFACE-DEPENDENT, so do not go looking for a
+fill difference on every surface. `base` mixes the elevated fill 6%
+toward `--color-bright` and adds a resting shadow, so there the tiers
+differ in COLOUR. `bevel` sets `--era-surface-bg-elevated` to
+`--era-surface-bg` outright — elevation is a chisel, not a tone, which
+is bevel's whole premise — so `surface` and `elevated` paint the
+IDENTICAL fill there and differ only in relief. A consumer measured
+exactly that on 30.8.0 bevel: both tones `oklch(0.195 0 none)` in dark,
+`0.863` in light, one variable, side by side. `glass` splits the tiers
+its own way again. So the tier is real on every surface; the thing
+carrying it is not always the fill. |
 | `header?` | `Snippet` | — | Rendered above the body with a subtle divider. |
 | `footer?` | `Snippet` | — | Rendered below the body with a subtle divider. |
 | `children?` | `Snippet` | — | — |
@@ -1832,6 +2020,22 @@ Inherits all props from `HTMLAttributes<HTMLDivElement>`.
 | `size?` | `'chip' \| 'pill'` | `'chip'` | `sm` (default) is the standalone free chip; `pill` is the smaller pill
 that nests inside an md container (a select trigger, a button). |
 | `ondismiss?` | `() => void` | — | — |
+| `dismissAs?` | `'button' \| 'span'` | `'button'` | What the dismiss control RENDERS AS. `button` (the default) is right
+for a free-standing chip. Use `span` when the chip lives inside
+another control.
+A <button> inside a <button> is not merely bad manners: it is invalid,
+and the HTML parser repairs it by CLOSING the outer control before the
+inner one. So the server's markup and the client's DOM disagree, Svelte
+discards the page's hydration and re-renders from scratch, and the
+chips briefly sit outside the trigger they belong to. era's own
+multi-select shipped exactly that (a Chip with `ondismiss` inside
+Select.Trigger) and logged node_invalid_placement_ssr on every load.
+`span` also drops the control from the accessibility tree rather than
+announcing a button inside a button — which is the honest description
+of what it is there: a pointer shortcut. The accessible way to remove
+a selection is the listbox itself, which is unaffected. Keyboard focus
+order is unchanged, because a nested button was never reachable in a
+sensible order anyway. |
 | `lead?` | `Snippet` | — | Icon rendered BEFORE the label, outside it. Use this rather than putting
 an icon in `children`: the label then gets its own box, which is the only
 place era's ink centring can reach. |
@@ -1997,6 +2201,24 @@ Inherits all props from `Separator.RootProps`.
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
 | `variant?` | `'line' \| 'slant'` | `'line'` | Use `slant` for inline dividers in breadcrumbs, titles, and compact metadata. |
+| `size?` | `keyof typeof SIZES` | — | Give a VERTICAL rule a height of its own, from the tier ladder, instead
+of stretching to whatever line it lands in. Ignored when horizontal.
+WHY YOU WOULD WANT IT. A stretched rule is a passenger: it has no
+intrinsic height, so it measures whatever its neighbours measure and
+contributes nothing back. That is right inside a Bar, whose height is
+already fixed — and it is why a rule in an auto-height row cannot hold
+that row's height steady. A consumer whose site header gained and lost
+a qualifier between pages watched the chrome resize, and pinned a
+`min-h-[calc(...)]` on the header to stop it. Sizing the rule removes
+that calc: it becomes the piece that stands the row up.
+(For the record, since the report named the wrong mechanism: a
+stretched rule does not GROW its row. Measured in an 18px auto-height
+row, adding one leaves the row at 18px and the rule resolves to 10px —
+the line minus its two gutter margins. It can only ever be shorter
+than the row it divides, which is the whole problem here.)
+A sized rule drops the gutter margins with the stretch: the height is
+now a deliberate number, and silently adding 2 x gutter to it would
+make it the one element on the page you cannot reason about. |
 | `ref?` | `(forwarded)` | `null` | bindable |
 
 ## Usage
@@ -3910,12 +4132,90 @@ Inherits all props from `Meter.RootProps`.
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| `tone?` | `'default' \| 'accent' \| 'destructive' \| 'success' \| 'warning'` | `'default'` | The band this reading falls in. Tone is the fill's colour only — the
+| `tone?` | `'default' \| 'accent' \| 'destructive' \| 'success' \| 'warning' \| 'info'` | `'default'` | The band this reading falls in. Tone is the fill's colour only — the
 track stays neutral, because the well belongs to the control and the
 fill belongs to the value.
 Tone carries no semantics on its own: a meter in the destructive band
 still needs an accessible label saying what has run out. Pair it with
 `aria-label` / a visible label, never rely on the hue alone. |
+| `threshold?` | `number` | — | A BOUNDARY INSIDE THE RANGE — in the same units as `value`, not a
+percentage. A quota with a soft limit before the hard one; a plan that
+includes 30 hours of the 50 it bills against; a temperature that is
+fine until it is not. The bar fills against `max`, and the mark says
+where the number the reader is actually deciding about sits.
+WHY THE MARK HAS NO COLOUR OF ITS OWN. It has to read against both
+sides of itself: over the empty track before the value reaches it, and
+over the fill afterwards. One token cannot do that — a colour tuned
+against the track disappears into the fill the moment the value
+crosses, which is exactly what a consumer hit hand-rolling this. So
+the mark is painted in the colour of the side it is NOT on: the fill's
+paint while the value is short of it, the track's fill once the value
+has passed. That contrast is not a new promise — it is the meter's
+own. A fill that did not stand out from its track would not be a
+meter, so borrowing the pair is the one choice that cannot be wrong in
+a theme, a tone, or a surface era has not seen.
+IT IS DECORATION, and silent on purpose. There is no `role` and
+nothing to announce: a screen reader gets `value`/`min`/`max` and the
+meter's own accessible name, and a boundary it cannot position adds
+nothing. If the threshold is part of the reading — it usually is —
+put the figure in `aria-label` and in a caption, where it is a number
+rather than a position.
+PASS `aria-valuetext` IF YOUR STORED UNIT IS NOT YOUR DISPLAYED ONE.
+`value`, `max` and `threshold` all have to sit in one unit for this
+arithmetic to work, and `aria-valuenow` is `value` verbatim — so a bar
+stored in minutes and read in hours announces "2640 of 3000", a figure
+the customer was never quoted. Converting the props is not available
+to you (it would move the mark), which makes `aria-valuetext` the only
+lever; it passes through `restProps` onto the same element. Reported
+by a consumer billing minutes and quoting hours.
+Outside `[min, max]` it renders NOTHING rather than clamping to an
+end, because a mark pinned to the edge of the bar would claim a
+boundary that is not in the range. |
+| `buffer?` | `number` | — | A REGION FROM `min` THAT IS A DIFFERENT KIND OF QUANTITY — painted
+under the fill, over the track, in the same units as `value`.
+The media player's buffered-progress shape, and the name is borrowed
+from it, but the reading is more general: some of the range is already
+accounted for. A plan whose first 30 of 50 hours are included in the
+monthly minimum is not "24 hours into a bill", it is "24 of 30 hours
+you have already paid for" — money spent against money that will be
+spent, which is a distinction the bar could not draw.
+NO COLOUR OF ITS OWN, for the reason `threshold` has none: it has to
+be legible over the track while never competing with the fill that
+crosses it, and a token tuned for one of those is wrong for the other.
+It is the fill's own paint at 30%, so it cannot be wrong in a theme,
+a tone or a surface era has not seen, and it is the same 30% Slider's
+`progress` has used for a seek bar's buffer since it shipped.
+UNDER the fill, so it disappears as the value consumes it. That is the
+reading, not a limitation: once you are past your included hours, the
+included region IS spent, and `threshold` is what goes on marking
+where it ended.
+CLAMPED to the range rather than dropped, which is where it differs
+from `threshold`. A region can be honestly truncated — a buffer past
+`max` means the whole visible bar is accounted for, and painting it
+all says exactly that. A point cannot: a mark pinned to the edge would
+claim a boundary that is not in the range, so an out-of-range
+`threshold` renders nothing instead.
+Silent, like the mark. `aria-valuetext` already carries the reading,
+and a second region a screen reader cannot position adds nothing.
+(Slider spells its equivalent `progress` and takes a 0–1 FRACTION.
+Here every positional prop is in the value's own units — `value`,
+`max`, `threshold`, `buffer` — because a component that mixed the two
+would be a bug generator. The names differ because on a Meter
+`progress` would be a synonym for `value`.) |
+| `start?` | `Snippet` | — | Captions under the two ends of the bar — what the range MEANS.
+A meter states a proportion and leaves the reader to work out what of.
+"0m used" on the left and "50h before approval" on the right is not
+decoration, it is the reading; every consumer of a bare meter ends up
+hand-rolling the same flex row underneath it, which is where this came
+from. `start` is left, `end` is right, either may stand alone.
+NOT ANNOUNCED. They are captions, so a screen reader gets the meter's
+value and its own `aria-label`, not these. If the range needs saying
+out loud, say it in the label too — the same rule `tone` carries.
+THE DOM IS UNCHANGED WITHOUT THEM. With neither snippet this renders
+exactly the element it always did, so `class` still lands on the track
+and the geometry audits still walk the same box. Passing one wraps the
+track in a column, and `class` still lands on the track. |
+| `end?` | `Snippet` | — | — |
 | `ref?` | `(forwarded)` | `null` | bindable |
 
 <!-- end: meter -->