@signal9/era-ui 5.0.0 → 7.0.0

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

@@ -4,13 +4,32 @@
 
 ## Using the library
 
+**One entry point per component.** There is no barrel that re-exports everything — importing a component can never drag in another one, or another one's dependencies.
+
 ```ts
-import { Button, Table, Select } from "@sig-nine/era-ui";
-import "@sig-nine/era-ui/css";
+import { Button } from "@sig-nine/era-ui/button";
+import * as Select from "@sig-nine/era-ui/select";
+import * as Table from "@sig-nine/era-ui/table";
+
+// The root is the SYSTEM layer only: cn/tv, keybindings, the axis
+// registry, and Mode. It imports no component.
+import { cn, ModeProvider } from "@sig-nine/era-ui";
+
+import "@sig-nine/era-ui/styles";  // source CSS, scanned by your Tailwind
 ```
 
+The path is always the component's own kebab-case name — `/button`, `/dropdown-menu`, `/date-range-picker` — and the other layers are namespaced: `/ai` and `/ai/<part>`, `/apps/<app>`, `/os`, `/audit`.
+
 Named exports wrap a single primitive (`Button`, `Badge`, `Chip`, `Input`, …). Namespace exports compose primitives via sub-components (`Table.Root`, `Table.Row`, `Select.Trigger`, `Dialog.Content`, …). Every wrapper forwards unknown props to its underlying element or bits-ui primitive, so standard HTML attributes (`class`, `style`, event handlers, `aria-*`, `data-*`) work without ceremony.
 
+### Stylesheets
+
+`@sig-nine/era-ui/styles` is the source CSS — import it once and your own Tailwind build scans era's components and emits only the utilities they use. `@sig-nine/era-ui/css` is the prebuilt alternative for a project without Tailwind. Two stylesheets are opt-in because they are heavy and single-purpose: `/styles/video-player` (vidstack's vendor CSS, needed only with `VideoPlayer`) and `/styles/themes` (the raw theme tokens).
+
+### Optional peers
+
+era depends on five packages. Anything needed by ONE component is an optional peer you install only if you import that component: `vidstack` (VideoPlayer), `@neodrag/svelte` (Pane, and the `/os` shell), `marked` + `dompurify` (`/ai/response`), and the tiptap set (`/apps/notes`).
+
 ## Scoped overrides
 
 Five orthogonal axes are exposed as HTML attributes on any ancestor. The entire subtree re-tiers through CSS inheritance — no JS, no context provider.
@@ -39,7 +58,7 @@ Classes, not components — they need no import beyond the stylesheet. Reach for
 - `era-text-trim` — vertically center single-line control text (a label beside an icon, a button's own text) without a translateY nudge. Fixed-height, non-editable elements ONLY: never on an <input>/<textarea>, and never on the same element as `truncate` or any overflow clip — put it on the fixed-height ROW and let the truncating child centre inside it. See era-text-trim-caps for ALL-CAPS.
 - `truncate` — single-line horizontal truncation with an ellipsis — put it on the truncating CHILD inside a trimmed or leading-none row, never on the same element as era-text-trim; it will not clip ascenders or descenders.
 - `era-text-trim-caps` — the era-text-trim variant for ALL-CAPS single-line strings (kbd hints, acronym badges) — never for mixed-case text (a label like "System" reads high; use era-text-trim), and never on the same element as `truncate`.
-- `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 · era-ink-center` — the ink centring for a token pill — a badge, a KV value, any short caps-or-digits label in a fixed-height box; it needs no icon sibling (with one the box must stay flex, and the general trim applies).
 - `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).
 - `h-xs · h-xxs · h-sm · h-md · h-lg` — the tier-height ladder — h-xs (icon) · h-xxs (nested pill) · h-sm (standalone pill) · h-md (control) · h-lg (bar); the named form of h-(--era-h-*).
@@ -148,7 +167,7 @@ enough to stay var-form — `min-w-(--era-h-md)` etc. remain the escape hatch.
 | `era-text-trim` | vertically center single-line control text (a label beside an icon, a button's own text) without a translateY nudge. Fixed-height, non-editable elements ONLY: never on an <input>/<textarea>, and never on the same element as `truncate` or any overflow clip — put it on the fixed-height ROW and let the truncating child centre inside it. See era-text-trim-caps for ALL-CAPS. |
 | `truncate` | single-line horizontal truncation with an ellipsis — put it on the truncating CHILD inside a trimmed or leading-none row, never on the same element as era-text-trim; it will not clip ascenders or descenders. |
 | `era-text-trim-caps` | the era-text-trim variant for ALL-CAPS single-line strings (kbd hints, acronym badges) — never for mixed-case text (a label like "System" reads high; use era-text-trim), and never on the same element as `truncate`. |
-| `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` `era-ink-center` | the ink centring for a token pill — a badge, a KV value, any short caps-or-digits label in a fixed-height box; it needs no icon sibling (with one the box must stay flex, and the general trim applies). |
 | `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). |
 | `h-xs` `h-xxs` `h-sm` `h-md` `h-lg` | the tier-height ladder — h-xs (icon) · h-xxs (nested pill) · h-sm (standalone pill) · h-md (control) · h-lg (bar); the named form of h-(--era-h-*). |
@@ -340,39 +359,48 @@ Declared in `index.css`.
 }
 ```
 
-## era-ink-center
+## era-token-ink · era-ink-center
 
-**Use it for:** on a native single-line <input> (or the text layer that must mirror one) inside a fixed-height field — never alongside era-text-trim.
+**Use it for:** the ink centring for a token pill — a badge, a KV value, any short caps-or-digits label in a fixed-height box; it needs no icon sibling (with one the box must stay flex, and the general trim applies).
 
-The EDITABLE counterpart of era-text-trim — for native <input>s, which the
-trim is forbidden on (it collapses the UA's inner editor box and slices the
-glyphs; see typography/collapsed-text-trim).
+TOKEN INK — the ink centring for a pill whose content is a TOKEN: an id, a
+count, a status, a tag. Font-independent, unlike everything it replaces.
 
-Without help, a tier-height input centres its text by FONT BOX, and the ui
-stacks' font box is deeply asymmetric: ascent ≈1.07em against descent
-≈0.29em. Centring that box parks the visible band (caps, x-height) ~0.115em
-LOW — so a field's text sat visibly below the trimmed label beside it.
+THE BUG IT FIXES, which had been shipping library-wide and invisibly:
+`text-box-trim` DOES NOTHING ON A FLEX CONTAINER. Era's controls are all
+flex, and a flex container's bare text becomes an ANONYMOUS flex item — a box
+no selector can reach and no non-inherited property can touch. So
+`era-text-trim` on a Badge, a Chip, a Button or a Bar contributed exactly one
+thing: `line-height: 1`. The ink was then centred by `align-items: center`
+on the LINE BOX, which is precisely the font-metric-dependent centring the
+trim exists to eliminate. Measured on the shipped mono stack: a badge reading
+"AC-2.1" sat 2px high in an 18px pill, and no amount of tuning the trim's
+BAND changed it, because the trim was never running.
 
-The value is OPTICAL, not the derivation's: pure x-band centring computes
-to ~0.23em of padding, but pixel-measured against real Title-Case text it
-over-lifts — the eye weighs the cap-to-baseline mass, which x-band
-centring parks ~2px high (caps 2.75px off the top against 5.7px of air
-under the baseline, measured at dense). 0.08em splits the difference
-between the x-band ideal and the cap-band ideal, landing caps ~3.7px in an
-18px field with ~4.7px under the baseline — the reading where neither
-band's partisans win and neither complains.
+The mechanism here restores it: a BLOCK box (where text-box-trim does apply)
+whose trimmed line box is then centred by `align-content` — block-container
+alignment, so no flex formatting context and no anonymous item. The browser
+computes the band from the font's own metrics, which is what makes it hold
+across ui-monospace, system-ui and ui-serif instead of needing a constant
+per stack.
 
-The lift is padding, not a translateY: an icon-less Input paints the field
-chrome itself, and a transform would drag the field along with the ink.
-padding-bottom shrinks the content box from below, and a single-line input
-re-centres its line box in what remains — the ink rises by exactly half the
-padding, the chrome doesn't move, and the caret and selection follow the
-text. In em on purpose: the correction is a fraction of the type, so it
-holds across every density and text size with one value.
+CAP band, not the x-height band the general trim uses, because the content
+class is different: a token is caps and digits (both cap-height), and
+centring the x-band parks them high by (cap − x)/2. Measured on the shipped
+stacks, cap-band centring takes an id/count/status from −2.0px to 0.0.
+Prose and sentence-case labels keep era-text-trim; this is for tokens.
 
 Declared in `index.css`.
 
 ```css
+@utility era-token-ink {
+	display: block;
+	align-content: center;
+	text-align: center;
+	line-height: 1;
+	text-box: trim-both cap alphabetic;
+}
+
 @utility era-ink-center {
 	padding-bottom: 0.08em;
 }

package/dist/generated-docs/llms.txt

@@ -38,13 +38,32 @@ Full derivations: `{{ORIGIN}}/spacing.md` (the ladder and every token), `{{ORIGI
 
 ## Using the library
 
+**One entry point per component.** There is no barrel that re-exports everything — importing a component can never drag in another one, or another one's dependencies.
+
 ```ts
-import { Button, Table, Select } from "@sig-nine/era-ui";
-import "@sig-nine/era-ui/css";
+import { Button } from "@sig-nine/era-ui/button";
+import * as Select from "@sig-nine/era-ui/select";
+import * as Table from "@sig-nine/era-ui/table";
+
+// The root is the SYSTEM layer only: cn/tv, keybindings, the axis
+// registry, and Mode. It imports no component.
+import { cn, ModeProvider } from "@sig-nine/era-ui";
+
+import "@sig-nine/era-ui/styles";  // source CSS, scanned by your Tailwind
 ```
 
+The path is always the component's own kebab-case name — `/button`, `/dropdown-menu`, `/date-range-picker` — and the other layers are namespaced: `/ai` and `/ai/<part>`, `/apps/<app>`, `/os`, `/audit`.
+
 Named exports wrap a single primitive (`Button`, `Badge`, `Chip`, `Input`, …). Namespace exports compose primitives via sub-components (`Table.Root`, `Table.Row`, `Select.Trigger`, `Dialog.Content`, …). Every wrapper forwards unknown props to its underlying element or bits-ui primitive, so standard HTML attributes (`class`, `style`, event handlers, `aria-*`, `data-*`) work without ceremony.
 
+### Stylesheets
+
+`@sig-nine/era-ui/styles` is the source CSS — import it once and your own Tailwind build scans era's components and emits only the utilities they use. `@sig-nine/era-ui/css` is the prebuilt alternative for a project without Tailwind. Two stylesheets are opt-in because they are heavy and single-purpose: `/styles/video-player` (vidstack's vendor CSS, needed only with `VideoPlayer`) and `/styles/themes` (the raw theme tokens).
+
+### Optional peers
+
+era depends on five packages. Anything needed by ONE component is an optional peer you install only if you import that component: `vidstack` (VideoPlayer), `@neodrag/svelte` (Pane, and the `/os` shell), `marked` + `dompurify` (`/ai/response`), and the tiptap set (`/apps/notes`).
+
 ## Scoped overrides
 
 Five orthogonal axes are exposed as HTML attributes on any ancestor. The entire subtree re-tiers through CSS inheritance — no JS, no context provider.
@@ -77,7 +96,7 @@ Classes, not components — they need no import beyond the stylesheet. Reach for
 - `era-text-trim` — vertically center single-line control text (a label beside an icon, a button's own text) without a translateY nudge. Fixed-height, non-editable elements ONLY: never on an <input>/<textarea>, and never on the same element as `truncate` or any overflow clip — put it on the fixed-height ROW and let the truncating child centre inside it. See era-text-trim-caps for ALL-CAPS.
 - `truncate` — single-line horizontal truncation with an ellipsis — put it on the truncating CHILD inside a trimmed or leading-none row, never on the same element as era-text-trim; it will not clip ascenders or descenders.
 - `era-text-trim-caps` — the era-text-trim variant for ALL-CAPS single-line strings (kbd hints, acronym badges) — never for mixed-case text (a label like "System" reads high; use era-text-trim), and never on the same element as `truncate`.
-- `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 · era-ink-center` — the ink centring for a token pill — a badge, a KV value, any short caps-or-digits label in a fixed-height box; it needs no icon sibling (with one the box must stay flex, and the general trim applies).
 - `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).
 - `h-xs · h-xxs · h-sm · h-md · h-lg` — the tier-height ladder — h-xs (icon) · h-xxs (nested pill) · h-sm (standalone pill) · h-md (control) · h-lg (bar); the named form of h-(--era-h-*).

package/dist/generated-docs/manifest.json

@@ -44,7 +44,7 @@
       "slug": "utilities",
       "title": "Utilities",
       "summary": "The CSS classes era ships alongside the components — links, ink-centred text, shimmer, hidden scrollbars.",
-      "tokenEstimate": 6097,
+      "tokenEstimate": 6197,
       "sections": [
         "Overview",
         "era-interactive",
@@ -53,7 +53,7 @@
         "era-text-trim",
         "truncate",
         "era-text-trim-caps",
-        "era-ink-center",
+        "era-token-ink · era-ink-center",
         "era-shimmer",
         "era-collapse",
         "h-xs · h-xxs · h-sm · h-md · h-lg",
@@ -1023,14 +1023,15 @@
       "css": "@utility era-text-trim-caps {\n\tline-height: 1;\n\ttext-box: trim-both cap alphabetic;\n}"
     },
     {
-      "name": "era-ink-center",
+      "name": "era-token-ink",
       "names": [
+        "era-token-ink",
         "era-ink-center"
       ],
       "file": "index.css",
-      "useCase": "on a native single-line <input> (or the text layer that must mirror one) inside a fixed-height field — never alongside era-text-trim.",
-      "description": "The EDITABLE counterpart of era-text-trim — for native <input>s, which the\ntrim is forbidden on (it collapses the UA's inner editor box and slices the\nglyphs; see typography/collapsed-text-trim).\n\nWithout help, a tier-height input centres its text by FONT BOX, and the ui\nstacks' font box is deeply asymmetric: ascent ≈1.07em against descent\n≈0.29em. Centring that box parks the visible band (caps, x-height) ~0.115em\nLOW — so a field's text sat visibly below the trimmed label beside it.\n\nThe value is OPTICAL, not the derivation's: pure x-band centring computes\nto ~0.23em of padding, but pixel-measured against real Title-Case text it\nover-lifts — the eye weighs the cap-to-baseline mass, which x-band\ncentring parks ~2px high (caps 2.75px off the top against 5.7px of air\nunder the baseline, measured at dense). 0.08em splits the difference\nbetween the x-band ideal and the cap-band ideal, landing caps ~3.7px in an\n18px field with ~4.7px under the baseline — the reading where neither\nband's partisans win and neither complains.\n\nThe lift is padding, not a translateY: an icon-less Input paints the field\nchrome itself, and a transform would drag the field along with the ink.\npadding-bottom shrinks the content box from below, and a single-line input\nre-centres its line box in what remains — the ink rises by exactly half the\npadding, the chrome doesn't move, and the caret and selection follow the\ntext. In em on purpose: the correction is a fraction of the type, so it\nholds across every density and text size with one value.",
-      "css": "@utility era-ink-center {\n\tpadding-bottom: 0.08em;\n}"
+      "useCase": "the ink centring for a token pill — a badge, a KV value, any short caps-or-digits label in a fixed-height box; it needs no icon sibling (with one the box must stay flex, and the general trim applies).",
+      "description": "TOKEN INK — the ink centring for a pill whose content is a TOKEN: an id, a\ncount, a status, a tag. Font-independent, unlike everything it replaces.\n\nTHE BUG IT FIXES, which had been shipping library-wide and invisibly:\n`text-box-trim` DOES NOTHING ON A FLEX CONTAINER. Era's controls are all\nflex, and a flex container's bare text becomes an ANONYMOUS flex item — a box\nno selector can reach and no non-inherited property can touch. So\n`era-text-trim` on a Badge, a Chip, a Button or a Bar contributed exactly one\nthing: `line-height: 1`. The ink was then centred by `align-items: center`\non the LINE BOX, which is precisely the font-metric-dependent centring the\ntrim exists to eliminate. Measured on the shipped mono stack: a badge reading\n\"AC-2.1\" sat 2px high in an 18px pill, and no amount of tuning the trim's\nBAND changed it, because the trim was never running.\n\nThe mechanism here restores it: a BLOCK box (where text-box-trim does apply)\nwhose trimmed line box is then centred by `align-content` — block-container\nalignment, so no flex formatting context and no anonymous item. The browser\ncomputes the band from the font's own metrics, which is what makes it hold\nacross ui-monospace, system-ui and ui-serif instead of needing a constant\nper stack.\n\nCAP band, not the x-height band the general trim uses, because the content\nclass is different: a token is caps and digits (both cap-height), and\ncentring the x-band parks them high by (cap − x)/2. Measured on the shipped\nstacks, cap-band centring takes an id/count/status from −2.0px to 0.0.\nProse and sentence-case labels keep era-text-trim; this is for tokens.",
+      "css": "@utility era-token-ink {\n\tdisplay: block;\n\talign-content: center;\n\ttext-align: center;\n\tline-height: 1;\n\ttext-box: trim-both cap alphabetic;\n}\n\n@utility era-ink-center {\n\tpadding-bottom: 0.08em;\n}"
     },
     {
       "name": "era-shimmer",

package/dist/generated-docs/utilities.json

@@ -61,14 +61,15 @@
       "css": "@utility era-text-trim-caps {\n\tline-height: 1;\n\ttext-box: trim-both cap alphabetic;\n}"
     },
     {
-      "name": "era-ink-center",
+      "name": "era-token-ink",
       "names": [
+        "era-token-ink",
         "era-ink-center"
       ],
       "file": "index.css",
-      "useCase": "on a native single-line <input> (or the text layer that must mirror one) inside a fixed-height field — never alongside era-text-trim.",
-      "description": "The EDITABLE counterpart of era-text-trim — for native <input>s, which the\ntrim is forbidden on (it collapses the UA's inner editor box and slices the\nglyphs; see typography/collapsed-text-trim).\n\nWithout help, a tier-height input centres its text by FONT BOX, and the ui\nstacks' font box is deeply asymmetric: ascent ≈1.07em against descent\n≈0.29em. Centring that box parks the visible band (caps, x-height) ~0.115em\nLOW — so a field's text sat visibly below the trimmed label beside it.\n\nThe value is OPTICAL, not the derivation's: pure x-band centring computes\nto ~0.23em of padding, but pixel-measured against real Title-Case text it\nover-lifts — the eye weighs the cap-to-baseline mass, which x-band\ncentring parks ~2px high (caps 2.75px off the top against 5.7px of air\nunder the baseline, measured at dense). 0.08em splits the difference\nbetween the x-band ideal and the cap-band ideal, landing caps ~3.7px in an\n18px field with ~4.7px under the baseline — the reading where neither\nband's partisans win and neither complains.\n\nThe lift is padding, not a translateY: an icon-less Input paints the field\nchrome itself, and a transform would drag the field along with the ink.\npadding-bottom shrinks the content box from below, and a single-line input\nre-centres its line box in what remains — the ink rises by exactly half the\npadding, the chrome doesn't move, and the caret and selection follow the\ntext. In em on purpose: the correction is a fraction of the type, so it\nholds across every density and text size with one value.",
-      "css": "@utility era-ink-center {\n\tpadding-bottom: 0.08em;\n}"
+      "useCase": "the ink centring for a token pill — a badge, a KV value, any short caps-or-digits label in a fixed-height box; it needs no icon sibling (with one the box must stay flex, and the general trim applies).",
+      "description": "TOKEN INK — the ink centring for a pill whose content is a TOKEN: an id, a\ncount, a status, a tag. Font-independent, unlike everything it replaces.\n\nTHE BUG IT FIXES, which had been shipping library-wide and invisibly:\n`text-box-trim` DOES NOTHING ON A FLEX CONTAINER. Era's controls are all\nflex, and a flex container's bare text becomes an ANONYMOUS flex item — a box\nno selector can reach and no non-inherited property can touch. So\n`era-text-trim` on a Badge, a Chip, a Button or a Bar contributed exactly one\nthing: `line-height: 1`. The ink was then centred by `align-items: center`\non the LINE BOX, which is precisely the font-metric-dependent centring the\ntrim exists to eliminate. Measured on the shipped mono stack: a badge reading\n\"AC-2.1\" sat 2px high in an 18px pill, and no amount of tuning the trim's\nBAND changed it, because the trim was never running.\n\nThe mechanism here restores it: a BLOCK box (where text-box-trim does apply)\nwhose trimmed line box is then centred by `align-content` — block-container\nalignment, so no flex formatting context and no anonymous item. The browser\ncomputes the band from the font's own metrics, which is what makes it hold\nacross ui-monospace, system-ui and ui-serif instead of needing a constant\nper stack.\n\nCAP band, not the x-height band the general trim uses, because the content\nclass is different: a token is caps and digits (both cap-height), and\ncentring the x-band parks them high by (cap − x)/2. Measured on the shipped\nstacks, cap-band centring takes an id/count/status from −2.0px to 0.0.\nProse and sentence-case labels keep era-text-trim; this is for tokens.",
+      "css": "@utility era-token-ink {\n\tdisplay: block;\n\talign-content: center;\n\ttext-align: center;\n\tline-height: 1;\n\ttext-box: trim-both cap alphabetic;\n}\n\n@utility era-ink-center {\n\tpadding-bottom: 0.08em;\n}"
     },
     {
       "name": "era-shimmer",

package/dist/generated-docs/utilities.md

@@ -44,7 +44,7 @@ enough to stay var-form — `min-w-(--era-h-md)` etc. remain the escape hatch.
 | `era-text-trim` | vertically center single-line control text (a label beside an icon, a button's own text) without a translateY nudge. Fixed-height, non-editable elements ONLY: never on an <input>/<textarea>, and never on the same element as `truncate` or any overflow clip — put it on the fixed-height ROW and let the truncating child centre inside it. See era-text-trim-caps for ALL-CAPS. |
 | `truncate` | single-line horizontal truncation with an ellipsis — put it on the truncating CHILD inside a trimmed or leading-none row, never on the same element as era-text-trim; it will not clip ascenders or descenders. |
 | `era-text-trim-caps` | the era-text-trim variant for ALL-CAPS single-line strings (kbd hints, acronym badges) — never for mixed-case text (a label like "System" reads high; use era-text-trim), and never on the same element as `truncate`. |
-| `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` `era-ink-center` | the ink centring for a token pill — a badge, a KV value, any short caps-or-digits label in a fixed-height box; it needs no icon sibling (with one the box must stay flex, and the general trim applies). |
 | `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). |
 | `h-xs` `h-xxs` `h-sm` `h-md` `h-lg` | the tier-height ladder — h-xs (icon) · h-xxs (nested pill) · h-sm (standalone pill) · h-md (control) · h-lg (bar); the named form of h-(--era-h-*). |
@@ -236,39 +236,48 @@ Declared in `index.css`.
 }
 ```
 
-## era-ink-center
-
-**Use it for:** on a native single-line <input> (or the text layer that must mirror one) inside a fixed-height field — never alongside era-text-trim.
-
-The EDITABLE counterpart of era-text-trim — for native <input>s, which the
-trim is forbidden on (it collapses the UA's inner editor box and slices the
-glyphs; see typography/collapsed-text-trim).
-
-Without help, a tier-height input centres its text by FONT BOX, and the ui
-stacks' font box is deeply asymmetric: ascent ≈1.07em against descent
-≈0.29em. Centring that box parks the visible band (caps, x-height) ~0.115em
-LOW — so a field's text sat visibly below the trimmed label beside it.
-
-The value is OPTICAL, not the derivation's: pure x-band centring computes
-to ~0.23em of padding, but pixel-measured against real Title-Case text it
-over-lifts — the eye weighs the cap-to-baseline mass, which x-band
-centring parks ~2px high (caps 2.75px off the top against 5.7px of air
-under the baseline, measured at dense). 0.08em splits the difference
-between the x-band ideal and the cap-band ideal, landing caps ~3.7px in an
-18px field with ~4.7px under the baseline — the reading where neither
-band's partisans win and neither complains.
-
-The lift is padding, not a translateY: an icon-less Input paints the field
-chrome itself, and a transform would drag the field along with the ink.
-padding-bottom shrinks the content box from below, and a single-line input
-re-centres its line box in what remains — the ink rises by exactly half the
-padding, the chrome doesn't move, and the caret and selection follow the
-text. In em on purpose: the correction is a fraction of the type, so it
-holds across every density and text size with one value.
+## era-token-ink · era-ink-center
+
+**Use it for:** the ink centring for a token pill — a badge, a KV value, any short caps-or-digits label in a fixed-height box; it needs no icon sibling (with one the box must stay flex, and the general trim applies).
+
+TOKEN INK — the ink centring for a pill whose content is a TOKEN: an id, a
+count, a status, a tag. Font-independent, unlike everything it replaces.
+
+THE BUG IT FIXES, which had been shipping library-wide and invisibly:
+`text-box-trim` DOES NOTHING ON A FLEX CONTAINER. Era's controls are all
+flex, and a flex container's bare text becomes an ANONYMOUS flex item — a box
+no selector can reach and no non-inherited property can touch. So
+`era-text-trim` on a Badge, a Chip, a Button or a Bar contributed exactly one
+thing: `line-height: 1`. The ink was then centred by `align-items: center`
+on the LINE BOX, which is precisely the font-metric-dependent centring the
+trim exists to eliminate. Measured on the shipped mono stack: a badge reading
+"AC-2.1" sat 2px high in an 18px pill, and no amount of tuning the trim's
+BAND changed it, because the trim was never running.
+
+The mechanism here restores it: a BLOCK box (where text-box-trim does apply)
+whose trimmed line box is then centred by `align-content` — block-container
+alignment, so no flex formatting context and no anonymous item. The browser
+computes the band from the font's own metrics, which is what makes it hold
+across ui-monospace, system-ui and ui-serif instead of needing a constant
+per stack.
+
+CAP band, not the x-height band the general trim uses, because the content
+class is different: a token is caps and digits (both cap-height), and
+centring the x-band parks them high by (cap − x)/2. Measured on the shipped
+stacks, cap-band centring takes an id/count/status from −2.0px to 0.0.
+Prose and sentence-case labels keep era-text-trim; this is for tokens.
 
 Declared in `index.css`.
 
 ```css
+@utility era-token-ink {
+	display: block;
+	align-content: center;
+	text-align: center;
+	line-height: 1;
+	text-box: trim-both cap alphabetic;
+}
+
 @utility era-ink-center {
 	padding-bottom: 0.08em;
 }

package/dist/index.d.ts

@@ -1,6 +1,35 @@
-export * from './ui/index.js';
-export * as OS from './os/index.js';
-export * as AI from './ai/index.js';
-export type { Point, Size, Rect, Insets, Frame, Workspace, PaneState, JsonValue, PaneSnapshot, WorkspaceSnapshot, SnapZone, AppPane, AppDefinition, AppComponent, AppProps } from './os/index.js';
-export { PaneManager, SNAPSHOT_VERSION, readSnapshot, persistWorkspace, loadWorkspace, saveWorkspace, clearWorkspace, WORKSPACE_STORAGE_KEY } from './os/index.js';
+/**
+ * The SYSTEM layer — and deliberately nothing else.
+ *
+ * This used to be `export * from './ui/index.js'` plus the OS and AI
+ * namespaces: one import that could reach every component in the library. A
+ * barrel like that is a guarantee that the whole graph is reachable, and
+ * reachable is what matters — `import { Button } from '@signal9/era-ui'` put
+ * vidstack (4MB, needed by exactly one component nobody was rendering) into the
+ * module graph, where a production bundler MIGHT prove it away and a dev server
+ * pre-bundles it regardless. Selectivity that depends on a bundler proving
+ * purity is not selectivity; it is luck with good tooling.
+ *
+ * So the root now carries only what is genuinely cross-cutting and weightless:
+ * the class utilities every consumer composes with, the keybinding helpers, and
+ * the AXIS REGISTRY plus `Mode` — the design system's own contract, the thing
+ * you reach for to set up density/surface/corners/font/motion for a subtree.
+ * None of it imports a component; none of it imports a third-party runtime
+ * beyond clsx / tailwind-merge / tailwind-variants.
+ *
+ * Everything else is one import away, at its own entry point:
+ *
+ *   import { Button }   from '@signal9/era-ui/button';
+ *   import * as Select  from '@signal9/era-ui/select';
+ *   import { Swarm }    from '@signal9/era-ui/ai/swarm';
+ *   import { Desktop }  from '@signal9/era-ui/os';
+ *   import { Notes }    from '@signal9/era-ui/apps/notes';
+ *   import { runAudit } from '@signal9/era-ui/audit';
+ *
+ * The `./*` wildcard in package.json means a new component is importable the
+ * moment it exists, with no export map to maintain — and it means no component
+ * can ever be pulled in by accident, because nothing re-exports them together.
+ */
 export { cn, tv, hotkeys, keys, parseKeybinding, matchKeyBindingPress, createKeybindingsHandler, formatKeybinding, isApplePlatform, modKey, type KeyBindingMap, type KeyBindingPress, type KeyBindingOptions, type PartProps, type VariantProps } from './utils/index.js';
+export { modes, defaultMode, surfaces, defaultSurface, surfaceRegistry, corners, defaultCorners, fonts, defaultFont, motions, defaultMotion, axisRegistry, axisKeys, type Mode, type Surface, type SurfaceMeta, type Corners, type Font, type Motion, type AxisKey, type AxisMeta, type AxisLevel } from './ui/provider/index.js';
+export { Mode as ModeProvider } from './ui/mode/index.js';

package/dist/index.js

@@ -1,9 +1,43 @@
-export * from './ui/index.js';
-export * as OS from './os/index.js';
-export * as AI from './ai/index.js';
-// The snapshot + persistence API, flat for the same reason: saving and restoring
-// a desktop is a first-class thing consumers do, not an OS-namespace detail.
-// PaneManager comes with them because it is what every one of these functions
-// takes — without it the flat surface cannot type its own arguments.
-export { PaneManager, SNAPSHOT_VERSION, readSnapshot, persistWorkspace, loadWorkspace, saveWorkspace, clearWorkspace, WORKSPACE_STORAGE_KEY } from './os/index.js';
+/**
+ * The SYSTEM layer — and deliberately nothing else.
+ *
+ * This used to be `export * from './ui/index.js'` plus the OS and AI
+ * namespaces: one import that could reach every component in the library. A
+ * barrel like that is a guarantee that the whole graph is reachable, and
+ * reachable is what matters — `import { Button } from '@signal9/era-ui'` put
+ * vidstack (4MB, needed by exactly one component nobody was rendering) into the
+ * module graph, where a production bundler MIGHT prove it away and a dev server
+ * pre-bundles it regardless. Selectivity that depends on a bundler proving
+ * purity is not selectivity; it is luck with good tooling.
+ *
+ * So the root now carries only what is genuinely cross-cutting and weightless:
+ * the class utilities every consumer composes with, the keybinding helpers, and
+ * the AXIS REGISTRY plus `Mode` — the design system's own contract, the thing
+ * you reach for to set up density/surface/corners/font/motion for a subtree.
+ * None of it imports a component; none of it imports a third-party runtime
+ * beyond clsx / tailwind-merge / tailwind-variants.
+ *
+ * Everything else is one import away, at its own entry point:
+ *
+ *   import { Button }   from '@signal9/era-ui/button';
+ *   import * as Select  from '@signal9/era-ui/select';
+ *   import { Swarm }    from '@signal9/era-ui/ai/swarm';
+ *   import { Desktop }  from '@signal9/era-ui/os';
+ *   import { Notes }    from '@signal9/era-ui/apps/notes';
+ *   import { runAudit } from '@signal9/era-ui/audit';
+ *
+ * The `./*` wildcard in package.json means a new component is importable the
+ * moment it exists, with no export map to maintain — and it means no component
+ * can ever be pulled in by accident, because nothing re-exports them together.
+ */
+/* The composition utilities: `cn` for class merging (era-aware — it knows the
+ * tier/radius/shadow scales), `tv` for variants, and the keybinding layer. */
 export { cn, tv, hotkeys, keys, parseKeybinding, matchKeyBindingPress, createKeybindingsHandler, formatKeybinding, isApplePlatform, modKey } from './utils/index.js';
+/* The axis contract — the five orthogonal display axes, their levels, their
+ * defaults, and the registry that drives every picker built on top of them.
+ * Pure data: no component, no DOM, no dependency. */
+export { modes, defaultMode, surfaces, defaultSurface, surfaceRegistry, corners, defaultCorners, fonts, defaultFont, motions, defaultMotion, axisRegistry, axisKeys } from './ui/provider/index.js';
+/* `Mode` applies those axes (plus optional accent overrides) to a subtree. It
+ * is the one component that belongs here: it configures the system rather than
+ * being a piece of UI, and it imports nothing but types. */
+export { Mode as ModeProvider } from './ui/mode/index.js';

package/dist/os/workspace-storage.svelte.js

@@ -81,7 +81,7 @@ function stores() {
  */
 export function loadWorkspace(pm, key = WORKSPACE_STORAGE_KEY) {
     for (const store of stores()) {
-        let raw = null;
+        let raw;
         try {
             raw = store.getItem(key);
         }

package/dist/styles/index.css

@@ -11,21 +11,31 @@
 @import './surfaces/bevel.css';
 @import './typography.css';
 
-/* vidstack base layout + slider/button primitives for the VideoPlayer component.
- * Scoped internally to `:where(media-player)` so these rules don't affect
- * anything outside of a media-player subtree. Design-token theming is applied
- * on the component itself via CSS variables. */
-@import 'vidstack/styles/base.css';
-@import 'vidstack/styles/ui/buttons.css';
-@import 'vidstack/styles/ui/sliders.css';
-@import 'vidstack/styles/ui/buffering.css';
-@import 'vidstack/styles/ui/captions.css';
-@import 'vidstack/styles/ui/live.css';
-@import 'vidstack/styles/ui/menus.css';
-@import 'vidstack/styles/ui/tooltips.css';
+/* WHAT IS NOT HERE: vidstack's stylesheets, which the VideoPlayer needs and
+ * nothing else does. They were imported right here, so every consumer of this
+ * file paid 46KB — 37% of the built stylesheet — for a component almost none of
+ * them render. They now live in ./video-player.css, published as
+ * `@signal9/era-ui/styles/video-player`, and only a consumer using the player
+ * imports them.
+ *
+ * The split is by DEPENDENCY WEIGHT, not by layer, and that is deliberate.
+ * Tailwind utilities DEDUPE — 60-odd components share one small vocabulary of
+ * flex/h-md/items-center, so scanning every layer below costs almost nothing
+ * and cannot be forgotten. Third-party CSS is the opposite: it is unshared,
+ * heavy, and belongs to exactly one component. Split what is unshared; keep
+ * what is shared whole. */
 
-/* Tell Tailwind to scan this package's components for utility classes */
+/* Scan every SHIPPED layer for utility classes, not just ui.
+ *
+ * This read `@source '../ui'` alone, so a consumer on the source-CSS path got
+ * no utilities generated for any ai/, os/ or apps/ component — those rendered
+ * structurally correct and completely unstyled, silently. The scan follows the
+ * package's layers so that adding a layer means adding a line here, and
+ * nothing else. */
 @source '../ui';
+@source '../ai';
+@source '../os';
+@source '../apps';
 
 /* Lucide icons use an SVG presentation attribute for stroke width by default.
  * Set it from an Era token globally so every imported Lucide component tracks
@@ -261,6 +271,44 @@
  *
  * @use on a native single-line <input> (or the text layer that must mirror
  * one) inside a fixed-height field — never alongside era-text-trim. */
+/* TOKEN INK — the ink centring for a pill whose content is a TOKEN: an id, a
+ * count, a status, a tag. Font-independent, unlike everything it replaces.
+ *
+ * THE BUG IT FIXES, which had been shipping library-wide and invisibly:
+ * `text-box-trim` DOES NOTHING ON A FLEX CONTAINER. Era's controls are all
+ * flex, and a flex container's bare text becomes an ANONYMOUS flex item — a box
+ * no selector can reach and no non-inherited property can touch. So
+ * `era-text-trim` on a Badge, a Chip, a Button or a Bar contributed exactly one
+ * thing: `line-height: 1`. The ink was then centred by `align-items: center`
+ * on the LINE BOX, which is precisely the font-metric-dependent centring the
+ * trim exists to eliminate. Measured on the shipped mono stack: a badge reading
+ * "AC-2.1" sat 2px high in an 18px pill, and no amount of tuning the trim's
+ * BAND changed it, because the trim was never running.
+ *
+ * The mechanism here restores it: a BLOCK box (where text-box-trim does apply)
+ * whose trimmed line box is then centred by `align-content` — block-container
+ * alignment, so no flex formatting context and no anonymous item. The browser
+ * computes the band from the font's own metrics, which is what makes it hold
+ * across ui-monospace, system-ui and ui-serif instead of needing a constant
+ * per stack.
+ *
+ * CAP band, not the x-height band the general trim uses, because the content
+ * class is different: a token is caps and digits (both cap-height), and
+ * centring the x-band parks them high by (cap − x)/2. Measured on the shipped
+ * stacks, cap-band centring takes an id/count/status from −2.0px to 0.0.
+ * Prose and sentence-case labels keep era-text-trim; this is for tokens.
+ *
+ * @use the ink centring for a token pill — a badge, a KV value, any short
+ * caps-or-digits label in a fixed-height box; it needs no icon sibling (with
+ * one the box must stay flex, and the general trim applies). */
+@utility era-token-ink {
+	display: block;
+	align-content: center;
+	text-align: center;
+	line-height: 1;
+	text-box: trim-both cap alphabetic;
+}
+
 @utility era-ink-center {
 	padding-bottom: 0.08em;
 }