@epilot/volt-ui-experimental-griffel 0.2.3 → 0.3.1

package/ADOPTING.md

@@ -0,0 +1,416 @@
+# Putting a micro-frontend on this package
+
+For an agent doing the work in a **consumer repo**. `AGENTS.md` and `AUTHORING.md` govern files
+inside this package and do not apply to you; the README is the reference for individual APIs. This
+file is the procedure, and it exists because three pilot migrations — `variable-builder`,
+`scheduler-capability`, `flows-sidebar` — each rediscovered the same traps at their own expense.
+
+Every number below was measured on one of those three. Nothing here is inferred.
+
+---
+
+## The fast path
+
+```
+1  Toolchain: install, DO NOT externalize, prove an EMPTY tree builds.     ← before any UI
+2  Flag gate: parallel tree, flag off = byte-identical. Verify it turns ON.
+3  Token layer: /tokens subpath, semantic families, read the treatment cell.
+4  Components: five engine rules that fail silently.
+5  Host cascade: the consumer's own CSS is the adversary, not this package.
+6  Verify: typecheck, sweep, then a browser. In that order.
+```
+
+Two things decide whether this takes a day or a week, and both are in steps 1 and 2. Do them first,
+in full, and do not start writing UI until an empty tree builds and the flag demonstrably flips.
+
+---
+
+## 1. Toolchain
+
+**Bundled, not externalized.** The opposite of Volt UI v1. Never add this package to webpack
+`externals` and never give it an import-map entry — it is an ordinary per-MFE dependency, and the
+whole point of the architecture is that two MFEs can hold different versions. Externalizing it puts
+you back on a shared singleton.
+
+**`react/jsx-runtime` is the one to check.** String externals match the exact request, so `react`
+being external does **not** cover `react/jsx-runtime`, which means it is bundled from local
+`node_modules`. If your repo declares React 17 while the shell serves 18 — true in at least two
+epilot MFEs — you are bundling 17's jsx factory against the host's 18. That works today (17's
+factory produces `Symbol.for('react.element')` and reads the internals 18 still provides) and it is
+what `origin/main` already ships in those repos, verified by building both and diffing the
+`System.register` arrays. So it is pre-existing, not yours to fix, and worth a separate ticket
+rather than a detour here.
+
+**Tests.** Jest 26 and 27 ignore `exports`. Take the shipped preset:
+
+```js
+const griffel = require("@epilot/volt-ui-experimental-griffel/testing/jest-preset.cjs")
+module.exports = griffel.withGriffel(
+  { preset: "ts-jest" },
+  { alsoTransform: ["@xyflow"] }
+)
+```
+
+See the README's Testing section for why `withGriffel` replaces `transformIgnorePatterns` instead of
+merging, and why there is no CommonJS build.
+
+**Then stop and build.** `tsc`, lint, test and a production build must pass on a tree that contains
+the dependency and no components. That run is what proves your TypeScript can parse the package's
+declarations before you have written anything that would have to be rewritten. One pilot skipped it
+and spent the afternoon on a resolution problem it mistook for a styling problem.
+
+---
+
+## 2. The flag gate
+
+**The shape.** A parallel tree behind a feature flag, with the legacy tree untouched, so flag-off is
+byte-identical to today. All three pilots took this shape and none regretted it. It costs duplicated
+logic — roughly 600 lines in the scheduler — which is the right trade while the flag is short-lived,
+because the alternative is refactoring the renderer everyone currently depends on. Revisit if the
+flag will live for months.
+
+**Read the flag like this:**
+
+```ts
+const enabled = useFeatureFlagEnabled("<mfe>-griffel") === true
+```
+
+`=== true` matters: the hook returns `undefined` while PostHog resolves, and that must read as off
+rather than flickering the new UI in and out. A missing flag is correctly off.
+
+**The trap that cost the most time in this whole programme.** `useFeatureFlagEnabled` resolves its
+client from `PostHogContext`. With no provider mounted, that context yields the MFE's **own bundled,
+never-initialised** posthog-js instance — a different object from `window.posthog`. The hook then
+never returns `true`, whatever you do to the flag. In the variable-builder this was verified from the
+console: `window.posthog.isFeatureEnabled(flag)` was `true`, the override was persisted, the flag
+count was 1, and the gated `React.lazy` chunk was still never fetched, across a reload.
+
+So **prove the gate turns on before you build behind it.** Either mount the provider, or read
+`window.posthog` directly in the gate, or force a constant during development — but whichever you
+pick, watch the lazy chunk actually load in the network panel. A gate that cannot flip means every
+line you write behind it is unexercised.
+
+If you force a constant, that constant is item one on your pre-merge checklist. A `// REVERT BEFORE
+MERGE` comment is not a mechanism; one pilot shipped exactly that comment to the end of a session.
+
+**Lazy-load with exactly one dynamic import, and make it yours:**
+
+```ts
+// Right: one module of your own, which reaches the package by static import.
+const Tree = React.lazy(() => import("./components/mfe-griffel"))
+
+// Wrong: a dynamic import of the barrel. Webpack cannot statically prove the property accesses on
+// a namespace object, so tree-shaking is DISABLED for that module and the entire library lands in
+// the chunk — @dnd-kit, @tanstack/table-core, sonner, cmdk, every unused component.
+import("@epilot/volt-ui-experimental-griffel")
+```
+
+The scheduler measured that mistake at **846 KB**, falling to **29 KB** once the dynamic import
+named one of its own modules. The build succeeds either way and nothing warns. Flag-off cost after
+the fix: **5,227 bytes**, against 343,894 for an eager import.
+
+---
+
+## 3. The token layer
+
+**Import from the `/tokens` subpath, never the root `tokens` namespace.** A namespace object cannot
+be tree-shaken. Measured on the sixteen bindings one real consumer needed: 9,138 bytes gzip through
+the namespace, 207 through the subpath.
+
+**Prefer the semantic intent families over the decorative ones.** Two sheets ship: core installs
+itself on every use and carries `accent`, `gray`, `error`, `info`, `success`, `warning` and the whole
+`sem*` layer; the fifteen decorative families (`blue`, `green`, `yellow`, `teal`, …) live in an
+opt-in sheet. Name a decorative family without the sheet and you get a `var()` for a custom property
+nothing declares: no throw, no warning, nothing painted. The scheduler's SCSS coloured every
+schedule status from `--volt-blue-3`, `--volt-green-3` and `--volt-yellow-3`; ported literally, all
+three status colours would have vanished silently.
+
+The fix is almost never `ensurePaletteTokens()`. It is that status **is** semantic — pending is
+`info`, triggered is `success`, a pending change is `warning` — and those are in core. Two of the
+mappings are free:
+
+| decorative | semantic  | steps 3 and 6                                                |
+| ---------- | --------- | ------------------------------------------------------------ |
+| `blue`     | `info`    | byte-identical                                               |
+| `green`    | `success` | byte-identical                                               |
+| `yellow`   | `warning` | **not** identical — warning is amber, `#ffefd6` vs `#fffab8` |
+
+If you genuinely need a decorative family, the package installs the sheet for you whenever a
+`color`-prop component resolves to one. Call `ensurePaletteTokensFor(family)` yourself only if you
+are building your own coloured component.
+
+**Read the treatment cell before mapping roles.** Role names do not predict visual weight. In
+`plain` — the `:root` default, which reproduces today's portal — an **Object paints nothing**:
+`surfaceObject`, `borderObject` and `shadowObject` all resolve to transparent, while
+`surfaceContainer` is white with a shadow. The scheduler mapped its visible card onto Object from
+the role names, and every card would have disappeared with a clean typecheck, clean lint and a
+successful build. Open `dist/tokens/core.generated.js` and read the cell, or read the role/treatment
+table in the docs.
+
+**Ink on a soft fill is `on-soft`, not step 11.** Step 11 is documented as the low-contrast text
+step and is designed against steps 1–2. On step 3 — the natural fill for a tinted chip — it fails AA
+in light mode: info 4.26, success 4.27, warning 3.99. `sem<Family>OnSoft` lands between 10.27 and
+12.48 across every intent family in both modes.
+
+**Focus rings are `semFocusRing`.** Not `accentA8`, which reads like the obvious choice and
+composites to **2.36:1**, under the 3:1 that WCAG 2.1 SC 1.4.11 requires. Not `accent9` either: it
+passes light at 6.29 and **fails dark at 2.92**. Only steps 11 and 12 clear the bar in both modes.
+
+**Stamp treatments on `document.documentElement`.** Treatment blocks are bare attribute selectors,
+so a stamp on your MFE root looks like it works — until a popover, select or tooltip portals to
+`document.body`, leaves your subtree, and resolves against `:root` instead. See the README section.
+
+**Density is `[data-density]`, CSS-only, opt-in, and partial today.** Stamp
+`[data-density="compact"|"normal"|"comfortable"]` on `document.documentElement` (or any subtree
+ancestor) and `Button` (`base`/`icon` sizes), `Field` (root padding, `FieldSet` gap, and
+`FieldInput` height), `List`/`ListItemIndex`, and `Select` (`SelectItem`, `SelectContent` — see
+below) pick it up through ordinary CSS custom-property inheritance — no provider, no
+context, no JS density state to wire up, and an absent/invalid attribute is transparent (inherits
+an ancestor, or falls back to `normal` at the root). `Button[size="base"]`'s compact tier keeps the
+same 32px height as normal — the density lever there is horizontal padding, since a fixed
+line-height plus fixed vertical padding already floors the box at 32px; only comfortable grows it,
+the same way `lg` already does with an explicit `minHeight`. `Button`'s `xs`/`sm`/`lg`/`icon-xs`/
+`icon-sm`/`icon-lg` sizes, `FieldLabel` (fixed 16px at every tier), standalone `SelectTrigger`
+(Field-wrapped or not — a `SelectTrigger` inside a `Field` inherits the Field wrapper's now-bound
+padding, never its own height), `FieldComboboxInput` (`field-combobox.tsx` has its own separate
+`makeVoltStyles` call and its own unrelated `input` key with no height — this binding does not
+reach it), and every other component do **not** respond yet — density binding lands
+component-by-component; check `DENSITY-SPEC.md`'s matrix (§2) before assuming a given slot moves.
+`Table`/`DataTable` (`TableHead`'s height, `TableCell`'s vertical padding) are density-bound the
+same way as of TABLE-DENSITY-IMPLEMENTATION.md (2026-09-09) — see the dedicated paragraph below for
+the migration this required.
+
+**`List` is CSS-bound too, with two things worth knowing.** `ListItem`/`ListItemIndex` (min-height,
+padding, gap, index min-width, index horizontal padding) inherit from `[data-density]` exactly like
+Button/Field — omitted `density` writes no attribute at all (ambient CSS only); an explicit value
+(including `"relaxed"`) stamps a canonical `data-density` boundary. `"relaxed"` is a **permanent**
+alias for `"normal"` geometry — identical numbers, forever — but its **DOM representation** is
+normalized to `data-density="normal"`, not the literal string `"relaxed"`: the generator's three
+selector blocks only ever match `"compact"`/`"normal"`/`"comfortable"`, so a raw `"relaxed"`
+attribute would match none of them. Read the attribute back with `getAttribute("data-density")` if
+you need it, not the `density` prop value you passed. `List`'s `DragOverlay` (dnd-kit) is an
+ordinary DOM sibling of the `<ol>`, not a portal (confirmed from the installed
+`@dnd-kit/core` source) — an explicit `density` re-asserts the same canonical boundary directly on
+the dragged row's overlay clone; an omitted one inherits ambient CSS through the page's real DOM
+ancestors with no stamp at all, same rule as everywhere else. `ListGroupLabel`'s collapsible
+trigger shares `ListItem`'s bound geometry; its standalone (non-collapsible) variant is unrelated,
+unbound, unchanged.
+
+**A raw `data-density` attribute spread directly onto `<ol>` still wins over the `density` prop —
+same JSX spread order as always — but what that precedence now controls is new.** Before this
+binding, an attribute the caller spread onto `<ol>` was decorative: nothing in the CSS read it, so
+whichever one "won" was inert either way. Now it drives real geometry, so the same unchanged
+precedence rule has a real, visible consequence for the first time. It is also **narrower than it
+looks**: a raw attribute set only on the `<ol>` does not propagate to the sibling `DragOverlay` —
+the overlay clone reads only the `density` **prop**, never a raw attribute a caller set by hand on
+the list element. A caller who needs the dragged row's overlay to match a manually-overridden `<ol>`
+should use the `density` prop (or an ancestor `[data-density]` boundary) instead of a raw
+attribute — this gap is not closed in this pass, only documented.
+
+**`DensityProvider` is the explicit-override mechanism DENSITY-SPEC.md §4.4 specifies — reach for
+it only when the ambient CSS path above isn't enough.** Most callers never need it: an `<html
+data-density="compact">` (or any DOM ancestor `[data-density]`) already reaches every non-portalled
+element, and every portal-content component listed below, through ordinary CSS custom-property
+inheritance — no JavaScript, no import. `DensityProvider` exists for the one case that mechanism
+cannot cover: forcing a density onto content a Radix `Portal` moves to `document.body` (or a custom
+`container`), which is a DOM **sibling** of wherever it was written in JSX, not a descendant of any
+ancestor `[data-density]` boundary there. `<DensityProvider density="compact">` sets a real DOM
+`data-density` boundary (for its non-portalled descendants) **and** a React context value (read via
+`useDensity()`, `undefined` with no ancestor `DensityProvider` — never a JS reading of ambient CSS)
+in one component, so a portal-content component nested anywhere inside it — even many React levels
+deep, even past other portals — can re-stamp itself correctly. Ordinary `<div>` semantics: forwards
+`ref`/`className`/`style`/every other div prop, no `asChild`, no new polymorphic API. Runtime input
+outside `"compact"|"normal"|"comfortable"` normalizes to `"normal"`, matching the CSS fallback rule
+above.
+
+**Portal-content components stamp `data-density` themselves, from `useDensity()`, only when an
+explicit override exists.** `DialogContent`, `AlertDialogContent`, `DrawerContent`,
+`DropdownMenuContent`, `DropdownMenuSubContent`, `PopoverContent`, `SelectContent`, and
+`TooltipContent` each read `useDensity()` at their own portal root and spread `data-density` only
+when it is defined — omitted, they stamp nothing and inherit the ambient shell value through the
+real DOM tree (the portal container is still a descendant of `<html>`), exactly `List`'s
+`DragOverlay` rule extended to eight more components. A `Select` rendered inside a `Popover`'s
+content (or a `Dialog`'s, or nested inside a `DropdownMenu`) is proof this works even through
+**two** independent portals stacked in the React tree: both `PopoverContent`/`DialogContent` and
+the nested `SelectContent` read the *same* `DensityProvider` context value and stamp it
+independently, even though `SelectContent` is a DOM **sibling** of `PopoverContent`, not its
+descendant — real-Chromium-verified in `vr/density-provider-portal-interaction.test.ts`.
+`table-pagination.tsx`'s inline `SelectPrimitive.Portal`-based page-size menu (still built directly
+from raw Radix primitives, not the shared `select.tsx` component) now reads `useDensity()` and
+stamps `data-density` the same way as the eight components above — the gap this paragraph used to
+describe is closed; see the dedicated paragraph below.
+
+**`Table`/`DataTable` density (TABLE-DENSITY-IMPLEMENTATION.md, 2026-09-09) — resolves the
+compatibility question `TABLE-LIST-DENSITY-COMPATIBILITY-NOTE.md` (density/'s own worktree) left
+open, by user-approved decision: direct `TableDensityContext.Provider` consumers are no longer a
+supported way to control geometry.** `TableHead`'s height and `TableCell`'s vertical padding now
+read `tokens.tableHeadHeight`/`tokens.tableCellPaddingY` directly — the same `[data-density]`
+CSS-cascade mechanism as everywhere else, not a JS class switch. `Table`'s and `DataTable`'s own
+`density` prop is genuinely optional now (no more `= "normal"` default): omitted, no `data-density`
+is stamped and ambient shell/`DensityProvider` density inherits through ordinary DOM/CSS; explicit —
+including explicit `"normal"` under a non-normal ambient — always stamps its own value on the
+`<table>`/root element, resetting the subtree. `TableHead`/`TableCell`'s own `density` prop works
+the same way, stamped directly on that `<th>`/`<td>`, overriding locally; a nested, density-omitted
+`<Table>` (e.g. inside a custom `DataTable` cell renderer) inherits its nearest real `[data-density]`
+boundary exactly like any other nested content. A raw caller `data-density` attribute can never
+override the normalized `density` prop, on `Table`, `DataTable`, `TableHead` or `TableCell` alike.
+`table-pagination.tsx`'s portal calls `useDensity()` and stamps its own override the same way as the
+other eight portal-content components, reading whatever explicit density the nearest `Table`/
+`DataTable` ancestor established (via an internal, non-public context-only boundary — `Table` can't
+use `DensityProvider` itself, since its wrapping `<div>` cannot be injected inside `<table>` markup).
+`TableDensityContext` is still exported (its type and default are unchanged, so nothing to migrate
+at the type level) but is now a **deprecated, inert** compatibility export: `Table`/`DataTable` no
+longer provide a value into it, `TableHead`/`TableCell` no longer read it, and wrapping anything in
+a raw `<TableDensityContext.Provider>` no longer has any effect on rendered geometry. Migrate to the
+`density` prop on `Table`/`DataTable`/`TableHead`/`TableCell`, or wrap a subtree in
+`DensityProvider`. No real consumer of `TableDensityContext` was found in this package, the already-
+in-scope My Account app, or root-config (checked read-only) — if one exists elsewhere, it needs its
+own separate, bounded migration.
+
+**`Select`'s density bindings — `SelectItem` and `SelectContent` only.** `SelectItem`'s vertical
+padding (`select.item-padding-y`, 4/6/10px) and left padding (`select.item-padding-left`,
+4/8/12px; right padding stays a fixed 32px at every tier — it reserves the check-indicator's
+space) and `SelectContent`'s popup padding (`select.content-padding`, 4/8/12px) and gap
+(`select.content-gap`, 2/4/6px) now inherit from `[data-density]`. `SelectTrigger` (standalone or
+Field-wrapped) is **unchanged** — still intrinsic sizing at every tier, per `DENSITY-SPEC.md` §2.3;
+this pass did not invent new trigger geometry. `SelectContent`'s slide-in animation offsets reuse
+the same plain (non-density) primitive `SelectContent`'s padding used before this binding —
+deliberately left alone, since they are not in the approved matrix.
+
+---
+
+## 4. Components: the rules that fail silently
+
+Every one of these has already cost this library a real bug, and none is caught by a build, a
+typecheck or a passing test suite.
+
+1. **`&` must be the first token of a selector.** `"[data-open] &"` compiles to
+   `.hash[data-open] .hash` and can never match. Fifteen dead declarations were live when a gate
+   first caught it. Drive ancestor state through props instead.
+2. **Declaration order inside a slot is the precedence rule**, not specificity and not Tailwind's
+   ordering. Transcribing a v1 class order inverts results — 17% and 44% pixel diffs on Checkbox and
+   Radio. The state that must win goes **last**.
+3. **No CSS shorthands.** `padding: "8px"` paints nothing and breaks atom dedup; Griffel only warns,
+   at runtime, in dev. Use the re-exported `shorthands` — `import { shorthands } from
+"@epilot/volt-ui-experimental-griffel"`. Do not add a direct `@griffel/core` dependency: that is
+   a second engine copy in your graph.
+4. **Animations use the object form**, `animationName: { from, to }`. Keyframe names are
+   content-hashed but not salted, so a hand-written global `@keyframes` collides silently between
+   co-resident copies.
+5. **No reset ships.** `box-sizing: border-box` exists in the portal only because root-config
+   imports Tailwind's preflight. Set it on your own root **and** on descendants
+   (`"& *": { boxSizing: "border-box" }`). Note it cannot reach portalled package components, which
+   are exactly the ones with padded internals.
+
+**A typecheck catches less of this than it looks.** Before 0.2.1 the declarations imported types
+from a package consumers do not install, so every style object was silently `any`. That is fixed and
+`GriffelStyle` is real now — but measured against a real consumer's config, it catches invalid
+keyword **values** (`borderTopStyle: "wobbly"`) and little else. It cannot catch rule 3: csstype
+considers `padding` a perfectly ordinary property, and the value type is `string | 0`, so
+`width: 0` is legal by construction. So the two rules that fail silently at runtime are also the two
+a typecheck will not save you from. Both pilots ended up writing a small static gate for exactly
+these, and that is the right instinct.
+
+Dev-only noise to ignore: one `classNameHashSalt` console error per `makeStyles` call site. It is a
+false positive, documented in the README, absent in production.
+
+---
+
+## 5. The host cascade is the adversary
+
+Nothing in this package can beat a consumer's own stylesheet, and this is where flag-gated
+migrations actually break.
+
+**An ID-scoped Tailwind preflight outranks every Griffel atom.** `#mfe-root button { … }` carries
+specificity (1,0,1); a Griffel atom is (0,1,0). `:where()` and `@layer` both lose to a bare element
+reset, and an ID-scoped one is stronger still. The variable-builder's `variable-builder.css` nested
+`@tailwind base` under an ID selector; the fix was moving that import out of the shared router and
+into the legacy page chunks, so it loads with the legacy tree and never on the new path. Two lines,
+and flag-off is unchanged.
+
+**Global `!important` blocks keep applying.** The scheduler's `root.module.scss` ends ~90 lines of
+`!important` neutralising the portal's MUI globals, including a `:global([data-slot="popover-content"])`
+block that hits every popover in the document. It does not stop applying because your subtree
+changed. Two consequences: your new tree has to survive it without answering in kind, and a focus
+ring built from `boxShadow` is **erased** by `box-shadow: none !important` — under `:focus-visible`
+too, so keyboard users get no indicator at all. Use `outline` longhands; that reset does not touch
+them. Measured at 6.44:1 after the fix.
+
+**Verify the insertion anchor early.** Griffel's whole override model rests on its sheet being first
+in `<head>`, and the portal injects a lot. Call `assertAnchorIsFirstInHead()` at runtime and expect
+`{ ok: true }`. It held 10/10 rounds in the real portal for flows, but it is the highest-risk
+unknown in any new host.
+
+---
+
+## 6. Verifying, in the order that pays
+
+**Cheapest first, and know what each one cannot see.**
+
+```
+tsc + lint + build          resolution, and invalid keyword values. Not shorthands, not `0`.
+migration-sweep             catches the three defects nothing else can. Seconds.
+unit tests                  catch logic. They cannot see any of section 4.
+a browser                   the only thing that can see sections 3, 4 and 5.
+```
+
+**Run the sweep against your new tree**, not the repo:
+
+```sh
+node node_modules/@epilot/volt-ui-experimental-griffel/scripts/migration-sweep.mjs \
+  src/components/<name>-griffel src/surface
+```
+
+It finds orphaned `volt-`-prefixed classes, `var(--volt-*)` reads and unloaded token sheets — three
+things that all still _work today_ because v1's singleton is loaded at the portal root and is quietly
+supplying what you forgot to bring. They fail on the day that singleton retires, in several MFEs at
+once, with no error. All four earlier migrations shipped at least one. Pointed at a repo root during
+a flag-gated migration it will also report the legacy tree, which is correct and useless — scope it.
+
+**The suite is not your regression net.** The scheduler had **zero test files** with
+`passWithNoTests: true`, so a green vitest run said nothing at all. Check what your suite actually
+covers before citing it. A feature walkthrough of the old UI against the new one is what catches
+regressions here.
+
+**In the browser, check both flag states.** Flag off: the legacy tree renders, `document.head`
+carries zero Griffel sheets, and the gated chunk is never requested. Flag on: the chunk loads, tokens
+resolve to the treatment cell you expect, and portalled content is not painted in a different
+treatment from the tree that opened it. Capture at 1280×720 at `deviceScaleFactor: 1`, the platform
+minimum.
+
+---
+
+## What not to spend time on
+
+- **Don't fix pre-existing bugs.** Establish the baseline first — error counts, warning counts, test
+  counts — and hold your change to "no worse". The scheduler recorded two pre-existing lint warnings
+  and left them; that is the right instinct.
+- **Don't port a v1 defect faithfully when it makes something non-functional**, but do check which
+  v1 you are comparing against. The scheduler filed the time picker's missing column labels as a
+  package regression; v1 had in fact deleted them itself in June, and the repo's v1 was four minor
+  versions ahead of the copy that repo had installed (1.7.0 against 1.3.14). Read the version, not the vibe.
+- **Don't migrate a table to `DataTable` because it exists.** For a two-to-four-row price-tier table
+  it adds a TanStack column model and a context provider to render what `<table>` renders. Both
+  pilots kept the hand-built one and recorded the choice.
+- **Don't reach for `Card` inside a role recipe.** It is already an opinionated surface, so you get
+  two borders and two shadows. The role recipe _is_ the card.
+- **Don't trust a delegated report.** Grep the artifact. Every claim in this file that survived came
+  from reading a built bundle, a computed style or a pixel; several that did not survive came from
+  reading source and sounding right.
+
+---
+
+## Owe it back
+
+Keep two files in your tree as you go, because both pilots found them worth more than the commit
+messages:
+
+- **`LIBRARY.md`** — what you had to declare locally because the grammar does not express it, with
+  the literal values, so promoting it later is a move rather than a rediscovery.
+- **`DIVERGENCES.md`** — where you departed from the design, and why. A static mock has no data
+  model, no interaction states and no error states; the departures are the interesting part of the
+  work, not an embarrassment to bury.
+
+Anything that reads as a package defect goes to the package, not into a local workaround that the
+next MFE will write again. Every improvement in 0.2.1 through 0.2.3 came from a pilot doing exactly
+that.

package/README.md

@@ -140,12 +140,6 @@ fails on the insertion-point count and `gate:class-salt-skew` fails on atom-name
 `Collapsible` has no equivalent here, and neither does v1 — depend on `@radix-ui/react-collapsible`
 directly, as both pilot MFEs do.
 
-**Corrected in 0.2.2:** this section used to say `DataTable` was unported and "the only component
-still missing". It has shipped since 0.2.0 — `DataTable`, `DataTableBody`, `DataTableContent`,
-`DataTableHeader`, `DataTableLoading`, `DataTableError` and `TablePagination` are all exported. The
-stale sentence cost real work: the Variable Builder read it and hand-built its list page on the
-`Table` primitives.
-
 There is no `--volt-*` compatibility layer. Consumer CSS reading v1's variable names by hand needs
 migrating to this package's exported token bindings — 217 references across six MFEs, two thirds of
 them in `entity`.
@@ -188,12 +182,10 @@ keeps its mode inside a dark page.
 
 ## Testing
 
-The package is ESM-only, and Jest 26 and 27 ignore the `exports` field. Before 0.2.2 that made a
-bare import resolve to nothing: `Cannot find module '@epilot/volt-ui-experimental-griffel'`, in a
-suite that had been green only because no test rendered one of these components yet. 0.2.2 adds a
-`main` field, so those resolvers find `dist/index.js` themselves.
+The package is ESM-only. Jest 26 and 27 ignore the `exports` field, so they resolve through `main`,
+which points at the same ESM entry.
 
-What they still need is a transform, because the file is ESM and Jest's default
+What they need is a transform, because that file is ESM and Jest's default
 `transformIgnorePatterns` skips everything under `node_modules`. Take it from here:
 
 ```js
@@ -226,26 +218,35 @@ Every check below has a `GATE_NEGATIVE_CONTROL` mode that has been demonstrated
 property it checks breaks, and to trip only the checks it should. `bun run gates` runs them
 fail-fast. A green gate is evidence for that gate's own assertions and nothing wider:
 
-| check                           | what it proves                                                                                    |
-| ------------------------------- | ------------------------------------------------------------------------------------------------- |
-| `bun run gate:vr`               | 270 specimens rendered under v1 and v2 and diffed pixel by pixel                                  |
-| `bun run gate:isolation`        | two copies mount separately, emit no global selectors, share one insertion point and one renderer |
-| `bun run gate:token-value-skew` | two builds differing only in token VALUES paint independently                                     |
-| `bun run gate:class-salt-skew`  | two builds differing only in CLASS SALT keep disjoint atom names                                  |
-| `bun run gate:cascade`          | a consumer utility can still override a component, in a real browser                              |
-| `bun run gate:griffel-contract` | `insertionCache` still dedups, and every copy resolves the same renderer                          |
-| `bunx vitest run`               | 493 tests, plus 497 under React 18                                                                |
-
-`AGENTS.md` is the normative rule set and overrides every other document in the package.
-`AUTHORING.md` states the defect behind each rule. **Both ship in the tarball as of 0.2.2** — before
-that this paragraph cited four documents that `files` excluded, so a consumer was told the normative
-rules existed and had no way to read them.
-
-The other two stay in the repository, on branch
-[`experiment/griffel`](https://gitlab.com/e-pilot/product/frontend/volt-ui/-/tree/experiment/griffel):
-`DECISIONS.md` at the root holds the architecture rationale, and
-`packages/experimental-griffel/STATUS.md` is a dated snapshot of measurements — more current than
-this file on numbers, but not authoritative on rules.
+| check                             | what it proves                                                                                    |
+| --------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `bun run gate:vr`                 | 270 specimens rendered under v1 and v2 and diffed pixel by pixel                                  |
+| `bun run gate:isolation`          | two copies mount separately, emit no global selectors, share one insertion point and one renderer |
+| `bun run gate:token-value-skew`   | two builds differing only in token VALUES paint independently                                     |
+| `bun run gate:class-salt-skew`    | two builds differing only in CLASS SALT keep disjoint atom names                                  |
+| `bun run gate:cascade`            | a consumer utility can still override a component, in a real browser                              |
+| `bun run gate:griffel-contract`   | `insertionCache` still dedups, and every copy resolves the same renderer                          |
+| `bun run gate:dts-self-contained` | the published declarations resolve with nothing installed but this package and React              |
+| `bunx vitest run`                 | 494 tests, plus 495 under React 18                                                                |
+
+`gate:one-bare-specifier` exists but is **not** in `bun run gates`, and fails on purpose: it asserts
+that `dist` externalises the engine, and this release bundles it. Externalising is deferred, so the
+gate returns to the aggregate on the day that lands.
+
+**Migrating a micro-frontend onto this package? Read `ADOPTING.md` first.** It is the procedure,
+ordered so nothing gets written twice, with each pitfall attached to the step where it bites. Three
+pilot migrations paid for it separately.
+
+`ADOPTING.md` ships beside this file and is the only other document a consumer needs.
+
+The rest govern editing the package itself, so they stay in the repository rather than in your
+`node_modules`, on branch
+[`experiment/griffel`](https://gitlab.com/e-pilot/product/frontend/volt-ui/-/tree/experiment/griffel).
+`AGENTS.md` is the normative rule set for changing a component and `AUTHORING.md` gives the defect
+behind each rule; both are about authoring this package, which is why they are not in the tarball.
+`DECISIONS.md` at the repository root holds the architecture rationale, and `STATUS.md` and
+`MEASUREMENT.md` are dated snapshots of measurement and provenance — more current than this file on
+numbers, never authoritative on rules.
 
 ## Releasing