@boost33/ui 0.5.1 → 0.7.0

package/CHANGELOG.md

@@ -0,0 +1,2973 @@
+# Changelog
+
+Changes to the published surface of `@boost33/ui` — what a consuming product
+sees when it takes a version bump.
+
+**This file is the only notice a consumer gets.** Consumers upgrade by hand and
+nothing watches this package for them (`CLAUDE.md`, "Versioning"): no bot opens a
+PR naming the version, and nobody reads a diff of `dist/`. Somebody decides to
+run `npm install @boost33/ui@<version>`, and what they read first to judge
+whether to is this file. A change that passes every automated gate and still
+alters behaviour has no other way to reach them. That is what belongs here.
+
+That makes an entry a **per-PR obligation** rather than a release chore. A change
+merged without one is not announced late, it is not announced at all — the
+release cut dates the section, it does not write it.
+
+**Not everything that lands belongs here.** `package.json` ships `dist/` and this
+file, and `dist/` is built from `src/index.ts` alone, so the specimen app, the scripts,
+the tests and anything in `src/` not reachable from `index.ts` never reach a
+consumer. Those changes are the repo's business, not the changelog's. Each
+release below names them separately, briefly, so the omission reads as a decision
+rather than a gap.
+
+Versions stay `0.x` until the Wallet and Score both render from this package.
+Under `0.x` a behaviour change can ship as a patch or a minor, which is precisely
+why the entry matters more than the number.
+
+## Unreleased
+
+Three components are built to Stage A on main and are not releasable until
+each passes its fidelity gate. Their entries wait here for the release that
+ships them.
+
+### Changed — `CHANGELOG.md` now ships inside the package
+
+`package.json` `files` adds `CHANGELOG.md` next to `dist`, so this file is in
+the tarball at `node_modules/@boost33/ui/CHANGELOG.md`. Until now it reached a
+consumer only through the repository, which is a strange place to keep the one
+notice a consumer gets. Nothing in `dist/` changes. 0.5.0 and earlier were
+published without it, and a published version cannot be amended, so the first
+release to carry it is the one after 0.5.0. Repo-only otherwise: no import,
+prop or rendering changes.
+
+### Added — `CommandPalette`, Stage A only. **Not releasable: it has not passed its fidelity gate** (B33-495)
+
+**Do not include this component in a release.** `CommandPalette` is exported from
+`src/index.ts` and will appear in `dist/`, and a consumer who finds it there and
+renders it is rendering an unapproved view. It is Stage A under `CLAUDE.md`'s
+presentational-first rule: static markup, reproduced from Paper's
+"CommandPalette — search" artboard, with **no state, no handlers and no data**.
+The Wallet never rendered a palette, so there is no captured referent and no
+approved measurement anywhere — `CLAUDE.md` is explicit that before the gate
+nothing is authoritative and Paper is only a starting drawing. It becomes
+releasable when a person opens the specimen route, approves it, captures the
+first *designed* baseline themselves, and writes the measurements they approved
+into the spec document in the same session. Until all three have happened, cut
+this out of the release or hold the release.
+
+What exists today, and what does not:
+
+| | |
+| --- | --- |
+| Draws | the search row, three result groups with their headings, the footer legend, and an empty state |
+| Takes | `groups`, `query`, `activeResultId`, `labels`, `linkComponent` |
+| Does **not** | open, close, trap focus, mark anything `inert`, register `⌘K`, dismiss on Escape or a backdrop click, or move a highlight |
+
+**It takes grouped results as props and owns no search index.** Pages, Products
+and Actions are all the host's, decided on B33-495 on 2026-10-06. There is no
+cross-suite index in any repo and this component does not imply one: a palette
+over one product's pages is a smaller promise than the artboard's description
+("across the whole suite") makes, and that is accepted so the component is not
+held behind an architectural gap. Taking results as props is scope-agnostic —
+four products' results render exactly as one product's do — so a real index later
+changes what is passed in, not what is here.
+
+A result that navigates renders through `linkComponent` (ADR-0011); one with no
+`href` is an action and stays a `<button>`, with no handler until Stage B. Each
+result's glyph is the host's `icon`, because the groups are the host's and
+nothing here can map one to a glyph without learning what a host's group means.
+The markup is the combobox-over-listbox ADR-0010 settled for this component —
+`role="combobox"` on the input naming the highlighted row through
+`aria-activedescendant`, `role="listbox"` on the list, `role="option"` on each
+result, `role="group"` on each group — and that is markup, not traversal; what
+the arrow keys do is Stage B's to implement.
+
+Every user-facing string is a prop with an English default
+(`defaultCommandPaletteLabels`, exported and frozen), resolved through the same
+`Partial` + `undefined`-skipping merge `WalletChip` uses, so one missed
+translation key falls back to English rather than leaving the panel's only
+control unnamed (B33-873, B33-877, and the contract B33-1007 asks the package to
+converge on).
+
+**New token: `--container-command-palette: 560px`**, the panel's width, read off
+the artboard and recorded in `data/paper-tokens.json` as **provisional** — it is
+the drawing's number, not an approved measurement, and the person at the gate may
+move it. It is the only token this change adds; everything else draws on tokens
+that already existed.
+
+`TopBar` is unchanged. There is still no `⌘K` badge in the bar and still no
+`aria-haspopup` on the search button — both arrive with the panel, in Stage B.
+
+Not in `dist/` and not a consumer's business: the specimen route showing the four
+states, their `SPECIMEN_ONLY` records (none of them is screenshot-gated, because
+a *designed* baseline is the gate's to capture and never an agent's), and
+`tests/command-palette.test.tsx`.
+### Added — `AccountMenu`, Stage A only, **not yet through its fidelity gate** (B33-493)
+
+> [!danger] Do not include this component in a release until a human has approved
+> it. `AccountMenu` has **not passed its fidelity gate.** Nobody has yet looked at
+> it beside a reference and said yes, no baseline exists for it, and no measurement
+> it draws with has been written into the spec. `CLAUDE.md` is explicit about what
+> that means for the three components the Wallet never rendered: "Before the gate,
+> nothing is authoritative", and the gate is where the referent is created rather
+> than checked. Until that session has happened — a person opening the specimen
+> route, judging the component, capturing the first baseline themselves, and
+> recording the approved measurements in the spec in the same pass — every number
+> this component renders is provisional and may change in a way that moves pixels
+> in your app. **If you are cutting a release, either hold this entry back or get
+> the gate done first.**
+
+The twelfth component. The account menu's **panel**: the signed-in person, the
+organisation they are acting in, and the rows into Settings and out of the
+session. Exported as `AccountMenu`, with `AccountMenuProps`,
+`AccountMenuPerson`, `AccountMenuOrg`, `AccountMenuGroup`, `AccountMenuItem`,
+`AccountMenuIcon`, `AccountMenuLabels` and `defaultAccountMenuLabels`.
+
+**It is the panel and nothing else — no trigger, no open state, no dismissal.**
+That is not an unfinished half of trigger-plus-panel; it is the part of this
+component the two reference drawings agree about. Paper's 004 Components artboard
+and its origin on 103 Identity are identical in every property of the panel, and
+they disagree about the anchor above it and about where the panel sits relative to
+that anchor. Choosing between them is the gate-holder's, so the component takes no
+anchor, does no positioning, and leaves `TopBar` untouched. Nothing in this release
+changes `TopBar`.
+
+**What a consumer does with it today: nothing.** Render it and you get a static
+panel. It holds no state, so it cannot be opened or closed, and it wires no
+handlers, so `Sign out` is a `<button>` that does nothing when pressed. Wiring it
+to `useAnchoredOverlay`, giving the anchor its `aria-expanded`, and deciding what
+each row does are Stage B, after the gate (`CLAUDE.md`, "Presentational-first").
+
+**The shape, so it is legible from here:**
+
+- `person` is `{ name, email, avatarUrl? }`. With no `avatarUrl` the circle draws
+  bare, which is what the drawings show; with one, the image is decorative and
+  takes an empty `alt`, because the person's name is on the line beside it.
+- `org` is `{ name, initials, role? }`. The initials are decorative; omitting
+  `role` draws no pill rather than an empty one.
+- `groups` is a list of `{ id, items }`, and **a hairline is drawn above every
+  group** — which is what separates the identity blocks from the first group as
+  well as each group from the last. Grouped rather than an `items` array plus a
+  named `footer`, because "footer" would be this package inventing a meaning for
+  the second group.
+- an item is `{ id, label, description?, href?, icon? }`. **Whether a row
+  navigates is decided by `href` and nothing else** (ADR-0011): with an `href` the
+  row is a link and renders through `linkComponent`; without one it is an action
+  and stays a `<button type="button">`. So the package never has to know which of
+  Profile, Settings, Switch account and Sign out your product treats as a
+  navigation. `icon` names one of four glyphs the package draws
+  (`'person' | 'settings' | 'switch' | 'signOut'`); omit it and the glyph lane
+  stays, empty, so the row labels still line up in one column.
+- `linkComponent` is the ADR-0011 escape hatch, unchanged from `NavItem` and
+  `AppSwitcher`: an `ElementType` defaulting to `'a'`, receiving `href`,
+  `className` and the row's `data-*`/`aria-*` through unchanged.
+- `labels` is `Partial<AccountMenuLabels>` and holds **one** field, `panel`,
+  default `"Account"` — the panel's accessible name, which a disclosure panel has
+  no other way to get (ADR-0010). Everything else a person reads is row data you
+  supply, and therefore translates by construction.
+
+**The label contract is the `WalletChip`'s, deliberately and in full.** `labels`
+is a `Partial`, a field supplied as `undefined` (what a missed next-intl key looks
+like) falls back to English rather than blanking the panel's name, and
+`defaultAccountMenuLabels` is frozen with no type annotation so the freeze
+survives into the emitted `.d.ts`. That is three of this repo's own fixed bugs
+(B33-873, B33-877, B33-916) taken as the starting point rather than repeated.
+B33-1007 records `AppSwitcher` still diverging on the last of the three; this
+component does not add a fourth dialect, and the switcher's remaining divergence
+is unchanged here and still that ticket's.
+
+**A disclosure, not a menu** (ADR-0010): no widget role on the panel, no role on
+the rows, every row the real `<a>` or `<button>` it already is, so Tab walks them
+in the document's own order.
+
+**Three new tokens, all three read off an unapproved drawing.** They reach your
+app through `./style.css` and `./theme.css` like every other token, and the
+derivation comment on each says in as many words that the value is not settled:
+
+- `--container-account-menu: 312px` — the panel's width.
+- `--spacing-3_5: 14px` — the person block's block padding.
+- `--spacing-9_5: 38px` — the person block's avatar, the largest in the package.
+
+Nothing else in the package reads any of the three, so no existing rendering
+moves, and **no baseline moved**: all 27 gated states come back unchanged, because
+every token here is additive and no shared value was touched.
+
+**Four places where this does not reproduce its drawing**, each named at its rule
+in `AccountMenu.module.css`, and each because the drawn value is not a step this
+package's token set holds and the nearest step is within about a pixel — the trade
+`PageHeader` already records for `--leading-tight` against Paper's 30px. The row's
+glyph-to-text gap (11px drawn, `--spacing-2_5` here); the person block's
+name-to-email gap (3px drawn, `--spacing-0_5`, which is what the rows draw for the
+same relationship); two 10px type sizes (`--text-2xs`); and every line-height,
+because the drawing sets them in px and this package holds only percentages.
+
+**One open design question, recorded rather than decided.** This panel picks a row
+out with `--color-neutral-50`, where every other popover in the package uses
+`--color-surface-muted`, one neutral step darker. Reproduced as drawn and raised
+at the gate — the drawing was cloned from an Identity screen that predates the
+shared token pass, which is why it is the only popover in its own file still bound
+to literals.
+
+#### Not in `dist/`, and so not your concern
+
+The specimen gains an `AccountMenu` route with two sections, neither screenshot-gated
+and both recorded in `SPECIMEN_ONLY` with reasons: the panel, whose first baseline
+is a *designed* baseline only the person at the fidelity gate may capture, and a
+row rendered through a stand-in link component, which draws identically to the
+default by design. `tests/account-menu.test.tsx` adds 28 cases covering the
+structure, the row elements, the hairline-per-group rule, the label fallbacks and
+the ADR-0011 pass-through — none of them asserting geometry, which jsdom cannot
+see.
+
+### Added — `NotificationCenter`, Stage A only, **not releasable yet** (B33-494)
+
+> [!danger] This component has not passed its fidelity gate and must not be
+> included in a release until it has.
+> `NotificationCenter` is exported from `src/index.ts`, which means it would be
+> published by any version cut from this state. Do not cut one. A human has not
+> yet opened the specimen route, judged the component, captured its first
+> baseline or written its measurements into the spec — and until all three happen
+> in one session, there is no referent for this component at all (`CLAUDE.md`,
+> "The three components the Wallet never rendered"). Nothing it draws is settled,
+> including the panel's 360px width and every space inside it.
+>
+> It is also only half built. Stage A is static: the panel renders and nothing
+> responds. The bell does not open it, Escape does not close it, the filters do
+> not filter and "Mark all as read" marks nothing. That is Stage B, and it lands
+> after the approval, not before.
+
+The panel behind the top bar's bell: everything the four products did, in one
+list, with the unread ones marked. Both states the design draws — populated and
+empty — ship from this package and appear in the specimen app.
+
+**It is presentational and it owns no feed.** The notifications arrive as a prop
+and this package neither fetches, stores nor subscribes to anything. There is no
+cross-product event source in any repo today, and a component that implied one
+would make the shared shell the place four services integrate — the opposite of
+the dependency direction every other component here has, and a straight
+contradiction of `CLAUDE.md`'s "it renders what it is given". That was decided on
+the ticket on 2026-10-06; the feed itself is separate work, outside 1.0.
+
+```tsx
+<NotificationCenter
+  items={[
+    {
+      id: 'n1',
+      slug: 'wallet',                       // optional: selects the ProductMark
+      title: 'Your granted tokens expire in 3 days',
+      source: 'Wallet',                     // the host's words, not a slug
+      time: '12 minutes ago',               // preformatted by the host
+      dateTime: '2026-10-06T09:48:00Z',     // optional: the <time> element's datetime
+      href: '/wallet/grants',               // optional: a row with nowhere to go is not a link
+      unread: true,                         // defaults to false
+    },
+  ]}
+  viewAllHref="/notifications"
+/>
+```
+
+**The time arrives formatted, and that is a decision rather than an omission.**
+The obvious move is the one `WalletChip` makes for numbers — take a `locale` and
+format from a `Date` — and three things separate the two cases. A number is a
+pure function of its value and a locale; a *relative* time needs a `now`, so the
+component would read a clock and then either re-read it on a timer or go stale on
+screen, which is state in a component whose contract is that it has none. It
+would also make this component's own fidelity gate unreproducible: a designed
+baseline showing "12 minutes ago" from `Date.now()` is a different image an hour
+later. And the hard part is editorial — where a product cuts over from "12
+minutes ago" to "Yesterday" to a date is a policy each product may differ on, and
+`Intl.RelativeTimeFormat` does not decide it. The optional `dateTime` is how the
+machine-readable instant still reaches the page without this package deciding how
+to say it.
+
+**Every string is a prop with an English default**, in the same shape
+`WalletChipLabels` uses: `labels` is a `Partial`, a missing key falls back to
+English rather than blanking the UI (B33-873), `defaultNotificationCenterLabels`
+is frozen in the B33-916 spelling so writing to it is a compile error, and the
+one value-carrying string — the row's `{source} · {time}` line — is a template or
+a function, so a locale owns the word order and the separator. `AppSwitcher`'s
+contract still differs on the freeze; B33-1007 closes that by bringing the
+switcher to this shape, not by adding a fourth.
+
+The panel is a disclosure, not a menu and not an ARIA tab set (ADR-0010): no
+widget role, real links and buttons, and Tab is the document's own order, so the
+header action, both filters, every row and the footer link are each their own tab
+stop. Rows that navigate render through `linkComponent` (ADR-0011). The unread
+state is announced in words as well as drawn as a dot, because a colour reaches
+nobody on a screen reader.
+
+Three further things it deliberately does not do: it does not sort, filter, page
+or truncate `items`, because each is a decision about data it does not own; it
+draws no "0" on the unread filter, because a zero pill reads as a state; and the
+empty rendering drops the filters, the header action and the footer rather than
+offering three controls over an empty list. The empty state is not an edge case —
+a host with no feed wired yet has nothing to pass, which makes it the rendering
+most consumers meet first.
+
+**`TopBar` is unchanged.** Its bell's `unread` prop still defaults to `false`, it
+still gains no `aria-haspopup`, and it still opens nothing. Connecting the two is
+Stage B.
+
+## 0.7.0 — not yet published
+
+**The redrawn marks' baselines were approved by Jamal on 29 October 2026**
+(`tests/baselines/README.md`, "The 29 October redraw"), so nothing holds this
+release on that account. Date the heading when it is published.
+
+**Not breaking. Nothing to do on upgrade, and every product mark looks
+different.** A minor: no export, prop or type changes. `ProductMark` draws new
+artwork for the four slugs it drew before, draws a mark for six slugs it drew as
+a bare tile before, and `hasProductMark` answers `true` for those six.
+
+### Changed — every product mark carries one orange accent, and all ten products have one (B33-1670)
+
+**What you will see.** Every `ProductMark`, in the switcher and wherever else you
+render one, is a new drawing: the near-black tile, a white glyph and **one
+orange accent** (`--color-primary`) on one element of it. This reverses the
+9 September 2026 rule that product marks carry no orange at all (Jamal,
+29 October 2026, B33-1669). Products are still told apart by shape: the accent
+is the same orange in every mark.
+
+| Slug | Mark | Before |
+| --- | --- | --- |
+| `wallet` | a wallet, an orange clasp | a card with a stripe |
+| `boostscore` | a target, an orange bull's-eye | a gauge |
+| `boostvoice` | the Content pencil, an orange line under it | a soundwave |
+| `boostoutbound` | a paper plane, its near wing orange | an arrow leaving top-right |
+| `brokers` | two people, the one behind in orange | bare tile |
+| `boosttrade` | a key, its bow orange | bare tile |
+| `boostfunding` | a banknote and coin, an orange note behind | bare tile |
+| `boostresults` | a pulse running into an orange dot | bare tile |
+| `passport` | a passport, an orange globe | bare tile |
+| `pipe` | a pipeline in three stages, the last orange | bare tile |
+
+The glyphs are lifted verbatim from `boostledger` at `ad4146f`, the merge that
+redrew them there, so the Wallet and this package draw the same marks.
+`boostvoice` keeps its slug and draws the Content pencil, because the product is
+being renamed Boost Content; the display name moves on Identity's side
+(B33-1672), and nothing changes for you here when it does.
+
+**A muted mark spends no orange.** `muted` (the switcher's unowned and unbuilt
+rows) still greys the tile to `--color-neutral-300`, and now also turns the
+accent white. Outbound gains a fold line between its wings and Passport's globe
+turns grey with white lines, so both stay readable without the accent. Every ink
+on a muted tile is still white, so ADR-0012's contrast reasoning, and its rule
+against combining `muted` with `title`, is unchanged.
+
+**A mark's orange is not your screen's orange moment.** The one-orange-moment
+rule (`--color-primary`: the primary action or the threshold marker, never both)
+is about emphasis. A product mark's accent is identity, as the Boost33
+monogram's orange is, and does not count against it (Jamal, 29 October 2026;
+ADR-0015). A switcher showing ten marks does not stop a screen having its primary
+button.
+
+**Passport drops two lines below 24px.** At the 20px default its globe's
+meridian and equator would fill the globe in, so they are drawn from 24px up.
+If you render Passport at 24px or larger you get them.
+
+**`hasProductMark` answers `true` for all ten slugs Identity serves.** If a test
+of yours asserted `hasProductMark('brokers') === false`, or that a Brokers row
+draws a bare tile, it now fails, correctly. Nothing else in your code needs to
+change: a slug you do not recognise still draws the bare tile, as ADR-0003
+requires.
+
+#### Not in `dist/`
+
+The specimen's ProductMark route (ten marks per row, a stand-in slug for the
+bare tile, Passport added to the sizes row), a new specimen route
+`AppSwitcherRegistrySpecimen` showing the switcher with all ten products,
+`tests/product-mark.test.tsx`'s new palette, muted and Passport cases and its
+re-pinned Identity transcription (ten slugs, re-read 29 October 2026),
+`tests/app-switcher.test.tsx`'s registry cases, ADR-0015, a note on ADR-0012, and
+`tests/baselines/README.md`'s record of the redraw. **Thirteen baselines changed,
+approved by Jamal**: seven replaced (`productmark-wallet`, `-boostscore`,
+`-boostvoice`, `-boostoutbound`, `appswitcher-closed`, `-open`, `-rail`) and six
+added (`productmark-brokers`, `-boosttrade`, `-boostfunding`, `-boostresults`,
+`-passport`, `-pipe`), which joined `STATES` and the border census. Note for
+anyone relying on the diff: a 20px mark is too small a share of its crop to reach
+the 5% threshold, so the diff would pass a full redraw of any one mark.
+
+## 0.6.0 — 2026-10-26
+
+**Not breaking. Nothing to do on upgrade unless you adopt the new component.**
+A minor: one new export, `SettingsFrame`, and three new tokens on `:root`.
+Nothing that 0.5.1 renders changes.
+
+### Added — `SettingsFrame`, the settings frame the hub and every product share (B33-1529)
+
+The settings frame the hub and every product draw their settings pages in, so
+a person moving from the hub's settings to a product's sees one settings area
+rather than two apps. It follows the estate decision of 22 Oct 2026: settings
+live in the hub's menu, and each product hosts its own settings pages
+(boost33-voice ADR-0008).
+
+**Approved at its fidelity gate on 26 Oct 2026.** Its referent is the hub's
+settings chrome, from which every value is copied. Jamal judged it on the
+specimen route, captured its three designed baselines and approved its
+measurements into the spec ("SettingsFrame, recorded at its gate"). Those
+measurements and baselines now bind; a drawing that disagrees is out of date.
+
+| | |
+| --- | --- |
+| Draws | the full-page takeover: a 264px sidebar (back link, title, groups, other accounts, sign out), a 48px header (breadcrumb, help links, the host's account menu), the page heading, and the page itself. Below 768px of its own width, the sidebar becomes one row of links that scrolls inside itself |
+| Takes | `back`, `groups`, `otherAccounts`, `signOutHref`, `helpLinks`, `breadcrumb`, `heading`, `accountMenu`, `children`, `labels`, `linkComponent` |
+| Does **not** | know which products, sections or roles exist; decide which item is active; fetch anything; sign anyone out (sign-out is a link to Identity) |
+
+**The groups are data.** The host decides which groups exist, what each is
+called, where each entry goes and which one is `active`. The frame names no
+product.
+
+**A link to another origin is a plain full-page link, decided by its href.** An
+href with a scheme (`https:`, `mailto:`) or starting `//` renders as a plain
+`<a>`; a path renders through `linkComponent` (ADR-0011). So the hub passes a
+product's pages as absolute URLs and its own as paths, and a product does the
+reverse. Writing one of your own pages as an absolute URL costs a full page
+load and is otherwise correct.
+
+**An item's `icon` is your glyph, inked by the frame.** The frame sets
+`color` on the 16px slot (muted at rest, foreground when active), so draw the
+glyph with `stroke="currentColor"` and mark it `aria-hidden`.
+
+**Set the font hooks if your faces load under generated names.** The frame
+draws in `--font-sans` and `--font-display`, which read `--boost33-font-sans`
+and `--boost33-font-display` (B33-848). `next/font` loads Inter and Outfit
+under hashed family names, so a Next host that sets neither hook gets the
+system fallback in the frame while its own pages draw in Inter. The hub needs
+this, once, in its global CSS:
+
+```css
+:root {
+  --boost33-font-sans: var(--font-inter);
+  --boost33-font-display: var(--font-outfit);
+}
+```
+
+**The narrow layout is a container query, not a media query.** The frame
+switches at 767px of its own width. Rendered full-width, which is how a host
+renders it, that is the viewport's width less any classic scrollbar, so it
+matches the hub's media query everywhere except within a scrollbar's width of
+the breakpoint on a desktop browser.
+
+**Three component-private tokens** reach `:root` in `style.css` and mint no
+Tailwind utility (ADR-0013): `--text-settings-group-label` (10px),
+`--tracking-settings-title` (-0.01em) and `--spacing-settings-crumb` (7px), each
+copied from the hub's chrome.
+
+Exported: `SettingsFrame`, `defaultSettingsFrameLabels`, and the types
+`SettingsFrameProps`, `SettingsFrameGroup`, `SettingsFrameItem`,
+`SettingsFrameAccount`, `SettingsFrameLink`, `SettingsFrameCrumb`,
+`SettingsFrameHeading` and `SettingsFrameLabels`.
+
+#### Not in `dist/`
+
+The specimen route (`specimen/routes/SettingsFrameSpecimen.tsx`), its three
+gated states and their border census, the three baselines,
+`tests/settings-frame.test.tsx`, and the private-token pins in
+`tests/theme-drift.test.ts`.
+
+## 0.5.1 — 2026-10-15
+
+**Not breaking. Nothing to do on upgrade, and something you may now delete.** A
+patch by the owner's decision: every 0.5.0 call still compiles and still runs.
+It changes what the launch screen looks like, which is why this entry is long.
+
+### Changed — `LaunchLoader` paints one Boost33 background for every product (B33-1401)
+
+**What you will see.** The per-product mesh is gone. Every launch screen is now
+the same: black (`--color-neutral-1000`), with one large blurred ellipse of
+brand orange (`--color-orange-500` at its heart through `-600` and `-700`, fading
+out) whose upper rim sits on the screen's horizontal midline. A hop from the hub
+to Score and a hop to the Wallet look identical apart from the caption. The
+dots, the bar, the caption, their blends and sizes and the caption's 80% are
+all unchanged.
+
+Approved by the owner in Paper on 15 October 2026 (Boost Products › 004
+Components › "LaunchLoader — brand background", 1440×900). LaunchLoader's
+referent was created at its fidelity gate on 14 October, so this is that
+referent being re-approved by the person who set it, not a refactor. He
+re-captured the three `launchloader-*` screenshot baselines himself the same
+day; the diff reads 31 of 31.
+
+**`stops` is ignored and deprecated.** `LaunchLoaderProps.stops` is now
+optional and marked `@deprecated`; passing it renders exactly what omitting it
+renders. `launchBackdropCss(stops?, selector = 'html')` ignores its first
+argument; `launchBackdropCss()` is the call to write now, and
+`launchBackdropCss(stops)` and `launchBackdropCss(stops, selector)` still work.
+`LaunchGradientStops` is still exported, also deprecated, so a file that names
+it keeps compiling. **You may drop your colour maps**: the hub's `launchStops`
+lookup and the Wallet's `WALLET_LAUNCH_STOPS` (and the luminance test guarding
+them) no longer reach the screen. Nothing breaks if you leave them for now.
+
+`launchBackdropCss()` now returns
+`html{min-height:100%;background-color:var(--color-neutral-1000,black)}` and the
+same black under `(prefers-contrast)`. It no longer throws on a stop it would
+once have refused, because it writes no stop.
+
+**What went.**
+
+- `launchGround(stops)` and `launchSolid(stops)` are no longer exported. They
+  returned the mesh's ground and darkest stop; there is no mesh. Neither the hub
+  nor the Wallet imports them. If you do, the ground is now
+  `--color-neutral-1000` in every mode.
+- The `--dur-drift` motion token (5000ms) is removed. Only the mesh's drift used
+  it, and nothing moves in the background now.
+- The drift itself: the background is still in every mode, so reduced motion
+  only parks the bar, as it did.
+
+**Contrast, measured in Chromium** (`npm run launch-contrast-check`, six
+viewports from 1920×1080 to 360×640). The caption and bar now sit on the glow's
+dark-orange shoulder on landscape screens, and on black on portrait ones, where
+the rim falls below the content.
+
+| | worst | where |
+| --- | --- | --- |
+| Caption, white at 80% | **6.34:1** | 1280×720 (13.06:1 and up on portrait) |
+| Bar fill against its track | **10.89:1** | 1920×1080 and 1280×720 |
+| Dots against the ground (decorative, exempt) | 1.00:1 | portrait, on black |
+
+**The dots and the track vanish on portrait screens.** Both are white
+soft-lit, and soft-light onto pure black draws nothing. On landscape they
+measure about 2:1, as before. The dots are `aria-hidden` and the fill still
+carries the bar at 21:1 on black, so WCAG holds, but on a phone the screen shows
+a caption and a moving white bar on black, with the glow below. **Known, and
+out of scope by the owner's decision of 15 October 2026 — not a defect.**
+
+`prefers-contrast` still drops the glow and any `backdrop`, leaving flat black,
+and still draws the dots and track in full white with no blend.
+
+**Repo-only, not in the package:** the specimen's three LaunchLoader frames no
+longer pass `stops` (the Wallet frame keeps its test id and caption, on the same
+background); `specimen/routes/launchStops.ts` is gone; the contrast check
+measures one frame at six viewports and reads the bar at every viewport rather
+than only 1440×900; its drift and seam sections are gone with the drift.
+
+## 0.5.0 — 2026-10-14
+
+**Breaking. Read the checklist before you bump.** 0.x puts breaking changes in
+the minor, so neither consumer's range (`^0.4.1`, `0.4.1`) picks this up on its
+own. Every item below has its own entry further down with the detail.
+
+**What a type check will catch:**
+
+- `AppShellProps.product` is now `label`, and `navLabel` is new (B33-1272).
+- `SidebarProps.label` is now `landmarkLabel` (B33-1271).
+- `AppShellProps.pageHeader` is gone; render your `PageHeader` inside `children`
+  (B33-1267).
+- `WalletChipProps` is a union on `unknown`. An unknown balance is still
+  `unknown: true`, now with no figures at all; annotate the helper that builds
+  it `: WalletChipProps`, or TypeScript widens the literal and neither member
+  matches (B33-483).
+- A label can no longer be a function; templates only (B33-1278).
+- `PRODUCT_SLUGS` and `ProductSlug` are gone; use `hasProductMark()` (B33-1269).
+- The eight `NAV_*_PX` constants and `measureNavHeight` are no longer exported
+  (B33-483).
+
+**What a type check will NOT catch** — check these by looking:
+
+- **No `onTopUp`, no Top-up button.** `WalletChip` draws it only when a
+  handler is passed. A consumer passing none loses the button in every state,
+  and past the threshold the chip gets shorter by it (B33-1270).
+- **No `account.onSelect`, no account control.** The switcher's account row
+  still shows the account but is no longer focusable or clickable (B33-1270).
+- **Translated label templates use `%name%`, not `{name}`.** An old template
+  renders its braces on screen (B33-1277).
+- **`AppShell` now renders a `<main>`.** If your page body draws its own,
+  remove it, or the page has two (B33-1265).
+
+**Added:** `LaunchLoader`, `DotMatrixLoader`, `launchBackdropCss`,
+`launchGround`, `launchSolid` (B33-1389), approved at its fidelity gate.
+
+**Not in this release**, though on main: `CommandPalette`, `AccountMenu` and
+`NotificationCenter`. They have not passed their fidelity gates, so they are not
+exported; their entries stay under Unreleased above.
+
+### Changed — **breaking**: `AppShellProps.product` is now `label`, and `navLabel` is new (B33-1272)
+
+**Rename the prop at your one call site.** It is required, so a missed rename
+fails the typecheck rather than going quiet:
+
+```tsx
+// before
+<AppShell product="Wallet" nav={nav} topBar={topBar}>
+
+// after
+<AppShell label="Wallet" nav={nav} topBar={topBar}>
+```
+
+- The Wallet: `boostledger/src/app/(wallet)/WalletShell.tsx` — `product="Wallet"`
+  becomes `label="Wallet"`.
+- Score: `boostscore/components/app-shell/index.tsx` — `product={PRODUCT_NAME}`
+  becomes `label={PRODUCT_NAME}`.
+
+**Then consider passing `navLabel`, because `label` alone still names two
+landmarks the same.** The sidebar is `<aside aria-label={label}>` and the nav
+inside it is `<nav aria-label={navLabel ?? label}>`. With no `navLabel` a
+screen-reader user pulling up a landmark list hears "Wallet complementary" then
+"Wallet navigation" — the name doing none of the distinguishing that is the one
+job a landmark label has. Pass a second string and they come apart:
+
+```tsx
+<AppShell label="Wallet" navLabel="Wallet sections" nav={nav} topBar={topBar}>
+```
+
+Something like "Wallet sections" or "Wallet pages", in your product's language.
+
+**`navLabel` defaults to `label`, so this release changes no assistive output on
+its own, and the duplicate is not fixed until you pass one.** Said plainly
+because the alternative reads better and is worse: a default of
+`` `${label} navigation` `` would put a hardcoded English word into the
+accessible name of a landmark in every consumer — including the two that default
+to French — and this package hardcodes no user-facing English
+(`tests/no-hardcoded-strings.test.ts`). The word that distinguishes these two
+landmarks is a word only you can write, so the fallback is the honest default
+and the fix is half API and half this paragraph.
+
+**Why `product` was the wrong name.** It was used in exactly two places, both
+`aria-label`s. Nothing branched on it, nothing was looked up with it, and no
+artwork or copy changed because of it — yet its doc comment called it "the whole
+of the shell's product-awareness", which sent readers looking for a mechanism
+that was not there. The shell is product-aware through `nav`, `switcher`,
+`wallet` and `footer`. It also sat next to `AppSwitcher.currentSlug`, which takes
+Identity's slug (`"wallet"`), while this takes a display string (`"Wallet"`) —
+two names for one product with nothing in the types connecting them. `label` says
+what it is, and now matches `NavSection.label` and `AppShellNavItem.label`, which
+are also names a person reads.
+
+**Nothing visual changed.** No markup moved and no rendered text moved; all 27
+gated screenshot states came back at the ratios they held before.
+
+**Check your app if** it renders `AppShell` — both consumers do, and this is the
+one line each has to change.
+
+### Changed — **breaking**: `SidebarProps.label` is now `landmarkLabel` (B33-1271)
+
+**If you render `Sidebar` directly, rename the prop.** It is required, so a
+missed rename is a failed typecheck rather than a silent one:
+
+```tsx
+// before
+<Sidebar label="Wallet">…</Sidebar>
+
+// after
+<Sidebar landmarkLabel="Wallet">…</Sidebar>
+```
+
+**Nothing else changes.** The value still reaches `aria-label` on the `<aside>`
+and is still never rendered as text. No markup moved, no rendered text moved,
+and all 27 gated screenshot states came back at the ratios they held before.
+
+**Why the rename.** `label` meant two opposite things on two components the
+shell composes a few lines apart. `Sidebar`'s was an accessible name only —
+announced, never seen. `NavSection`'s is visible text, the small uppercase
+header above the rows. So reading `label` in this package told you nothing about
+whether the string would appear on screen, and a consumer who learned the
+convention from one component and applied it to the other either shipped a
+visible string into an `aria-label` where nobody could read it, or put a
+screen-reader-only string where a person would. `NavSection.label` keeps the
+visible meaning — the one a reader's intuition matches — and the invisible one
+gets the longer, more specific name.
+
+**Check your app if** it imports `Sidebar`. Neither consumer does: both reach it
+through `AppShell`, which passed `label` for you and now passes `landmarkLabel`.
+The expected consumer-side churn for this entry alone is zero — but read the
+`AppShell` entry above, which is where your call site actually changes.
+
+### Removed — seven component-private measurements no longer mint Tailwind utility classes (B33-1274)
+
+**Read this if you import `@boost33/ui/theme.css`.** Ten class names stop
+existing, the custom properties behind them are unchanged, and the failure mode
+if you were typing one is silent: an unknown Tailwind class does not error, it
+compiles to nothing and the element renders without that declaration.
+
+**The class names that stop existing.** Measured through `@tailwindcss/cli` on
+`tailwindcss@4.3.3`:
+
+```
+bg-grant   text-grant   bg-purchased   text-3xs   text-nav-label
+p-topup-reserve   m-topup-reserve   w-topup-reserve
+w-wallet-segment-min   rounded-product-tile
+```
+
+Those are the ones probed. The rule is wider: **every** utility Tailwind derives
+from `--color-grant`, `--color-purchased`, `--text-3xs`, `--text-nav-label`,
+`--spacing-topup-reserve`, `--spacing-wallet-segment-min` and
+`--radius-product-tile` is gone, so `border-purchased`, `bg-grant/50`,
+`gap-topup-reserve` and the rest go with them.
+
+**The custom properties are unchanged and still readable.** All seven still land
+on `:root` through `@boost33/ui/style.css`, at exactly the values they have in
+0.4.0 — `var(--color-sand-600)`, `var(--color-neutral-950)`, `9px`, `14px`,
+`68px`, `3px`, `25%`. `var(--spacing-topup-reserve)` reads the same number it
+read before. Verified on the same build: a consumer importing both files declares
+133 custom properties before this change and 133 after, none absent and none
+moved. No system utility moves either — `bg-orange-500`, `text-sm`, `rounded-xl`,
+`p-4`, `w-sidebar` and the rest of the scale compile identically.
+
+**If you typed one of them, replace the class with an arbitrary value reading the
+property**, which keeps the package authoritative for the number and holds no
+value of your own (ADR-0011):
+
+```diff
+- <span className="rounded-full bg-purchased" />
++ <span className="rounded-full bg-[var(--color-purchased)]" />
+```
+
+`p-topup-reserve` becomes `p-[var(--spacing-topup-reserve)]`,
+`rounded-product-tile` becomes `rounded-[var(--radius-product-tile)]`, and so on.
+Where a system token means the same thing, prefer it — `--color-purchased`
+resolves to `var(--color-neutral-950)`, so `bg-foreground` paints the identical
+ink and stays a first-class utility.
+
+**One known binding exists today.** `boostscore/demo/src/Shell.tsx` writes
+`bg-purchased` at `:327` and `:335`; on the version bump that demo's purchased
+bar segment and its legend dot render with no background until the two lines
+above are applied. Nothing else in any consumer binds one of the seven. Score's
+`w-sidebar`, in `components/curator-shell.tsx` and nine `export-jsx/` files, is a
+system token and is untouched.
+
+**Why.** Each of the seven is a measurement of one component, hand-added only
+because a literal in a component is forbidden, and each is a number a fidelity
+gate is expected to move — `--spacing-topup-reserve`'s own comment ends by saying
+the real fix "restructures an approved view and needs a human". A minted class
+name is a published API that cannot be withdrawn after 1.0 without a major bump,
+so the package would have been choosing between that bump and a design change
+that is otherwise free. Unminting now costs the two lines above. ADR-0013 has the
+line between a system token and a component-private one, and amends ADR-0012.
+
+No rendering of any component in this package changes: `src/tokens.css`'s
+declarations are byte-identical, and all 27 screenshot baselines match at their
+existing ratios.
+
+### Removed — **breaking**: `AppShellProps.pageHeader` is gone (B33-1267)
+
+**If you pass `pageHeader`, your build now fails.** Move the header into the
+page body you already hand the shell as `children`:
+
+```tsx
+// before
+<AppShell product="Wallet" nav={nav} topBar={topBar}
+  pageHeader={{ title: 'Buy tokens', subtitle: 'Top up your balance.' }}>
+  <BuyTokens />
+</AppShell>
+
+// after
+<AppShell product="Wallet" nav={nav} topBar={topBar}>
+  <PageHeader title="Buy tokens" subtitle="Top up your balance." />
+  <BuyTokens />
+</AppShell>
+```
+
+`PageHeader` is unchanged and still exported. The shell renders `children`
+inside the page's `<main>`, so nothing needs a wrapper.
+
+**The header now scrolls, where the prop kept it pinned. Read this before you
+move one.** `.content` — the box the shell drops `children` into — is the
+shell's only `overflow-y: auto` element. A header passed through the prop sat
+*outside* it and stayed under the top bar while the page scrolled; a header
+rendered in `children` sits *inside* it and goes up with the content. At rest
+the two are pixel-identical and no screenshot can tell them apart, which is why
+this is spelled out here: a consumer moving a header across will see no
+difference until someone scrolls a long page, and then it will look like a
+regression rather than the documented consequence it is. If a pinned header is
+what your product wants, say so on B33-1267 — pinning it from `children` needs
+a layout change to the shell and a fidelity re-approval, not a prop.
+
+**Why it is going now rather than ever.** Nobody passed it. The Wallet renders a
+standalone `PageHeader` from eight page files and has never used the prop;
+Score forbids using it, with a test
+(`components/app-shell/heading-hierarchy.test.ts`), because the page below owns
+the sole `h1` and a second heading with the same name inverts the outline and
+reads the title twice. So the slot existed only because the Wallet's shell was
+once a single file that drew its own header, and the package inherited the
+shape. That is exactly what B33-483's second criterion covers: a prop that only
+exists because of how the Wallet happened to be built gets fixed while breaking
+changes are still free. Keeping it would have cost nothing today and a
+correctness trap forever, since the scroll difference above was documented
+nowhere.
+
+**Check your app if** it passes `pageHeader` — neither consumer does, so the
+expected blast radius of this one is zero, and the typecheck will say so either
+way.
+### Changed — breaking — two controls no longer render when nothing arms them (B33-1270)
+
+**If you want the chip's Top-up button, pass `onTopUp`. If you want the
+switcher's account row to be a control, pass `account.onSelect`.** Both used to
+render whether or not a handler came with them, so a consumer that passed
+neither got a visible control that did nothing and could not be removed —
+`.topUp` and `.accountRow` are CSS-Modules-hashed, so there is no selector to
+reach either one from outside this package. Both consumers are affected and both
+had already written the defect down in their own source.
+
+#### What disappears if you pass nothing
+
+- **No `onTopUp`: the chip draws no Top-up button at all**, in every state. Past
+  the threshold that button was `position: static` — a full-width block in flow —
+  so the chip is shorter by that block and the runway line becomes the last thing
+  in it. Resting it was absolutely positioned at `opacity: 0` until hover, so
+  nothing else moves.
+- **No `account.onSelect`: the switcher's account row stops being a control** but
+  keeps saying who the account is. The organisation's name and its workspace
+  count still render; the chevron, the hover step and the tab stop go, and the
+  row is a `<div>` rather than a `<button>`.
+
+#### Who this changes today
+
+- **The Wallet loses the Top-up button it was already shipping dead.**
+  `boostledger/src/app/(wallet)/WalletShell.tsx` passes no `onTopUp`, so the
+  button it draws today swallows the click. Pass a handler to keep it. Nothing
+  about how it draws has changed.
+- **Score keeps its button and needs no change to keep it.**
+  `boostscore/components/app-shell/wallet-chip-top-up.tsx` exists precisely to
+  arm it across a Server Component boundary, and it is the file whose doc comment
+  described this defect most exactly: "it renders that button whenever the chip is
+  not in its `unknown` state — the render is gated on `!unknown`, not on whether a
+  handler was supplied". That sentence is now out of date in the best way. **Keep
+  the wrapper** — it is still what supplies the callback — and note that its
+  "Upstream" paragraph is now half true: B33-1047 would still delete it, and the
+  unarmed-render half it describes is fixed here.
+- **Both consumers' account rows become non-interactive, which is what they
+  already were.** `boostscore/components/app-shell/product-switcher.tsx` says so
+  in a comment on the prop — "No `onSelect`. The row opens a workspace panel that
+  does not exist yet — the Wallet's migration left the same row inert for the same
+  reason" — and the Wallet's `WalletShell.tsx` says the same. Neither needs a
+  change; the row stops lying. Pass `onSelect` when B33-493's workspace panel
+  exists and the button and its chevron come back.
+
+#### Why absence is not `disabled`, and why the row is not removed
+
+A `disabled` button is still a control the consumer cannot take out, and ADR-0010
+settles that unavailable is not the same as disabled — so neither control grows a
+`disabled` or `aria-disabled` attribute in its unarmed shape.
+
+The two absences are deliberately different shapes, because the two controls
+carry different things. The Top-up button carries only its own affordance, so
+with nothing to press there is nothing to say and it renders nothing. The account
+row carries information — the organisation and its workspace count are facts
+about the account whether or not a panel opens — and ADR-0010's reasoning in "Not
+entitled is not disabled" is that a row carrying information is not the
+component's to withhold. So the row stays and only its interactivity goes.
+
+#### This is not B33-1047
+
+B33-1047 asks for a `topUpHref`, which would arm the button for a consumer that
+cannot pass a callback. It would not have fixed this: a consumer passing neither
+prop would still get the dead button, and it does nothing at all for the account
+row. The two are complementary and B33-1047 is still open.
+
+#### No baseline moved
+
+`walletchip-resting`, `walletchip-open`, `walletchip-threshold`,
+`walletchip-rail`, `walletchip-unknown`, `appswitcher-closed`, `appswitcher-open`
+and `appswitcher-rail` all come back at the ratio they have on `main`,
+`appswitcher-open` included at 0.000%. The gated specimen states now pass
+handlers, which is what they should always have passed: those baselines were
+captured from the Wallet's own shell, where topping up was a live affordance and
+the account row was a button with a chevron on it, so the armed shape is what
+they are photographs of. The unarmed shape is demonstrated on two new ungated
+specimen routes instead.
+### Removed — breaking — a label can no longer be a function; templates only (B33-1278)
+
+Five label fields were `string | ((…) => string)`. The function half is gone:
+
+```
+WalletChipLabels.grantExpiry          string | ((date) => string)                      -> string
+WalletChipLabels.railFigure           string | ((figure) => string)                    -> string
+WalletChipLabels.railBalance          string | ((balance) => string)                   -> string
+WalletChipLabels.bar                  string | ((g, p, r) => string)                   -> string
+NotificationCenterLabels.meta         string | ((source, time) => string)              -> string
+```
+
+**What to pass instead: a `%placeholder%` template, which is what the defaults
+already are.**
+
+```tsx
+// before, from a Client Component only
+labels={{ bar: (g, p, r) => `${r} restants : ${g} et ${p}` }}
+// now, from anywhere
+labels={{ bar: '%remaining% restants : %granted% et %purchased%' }}
+```
+
+The template is filled with the same preformatted figures the function was handed,
+in the same order, so the rendered string is identical. Word order is still
+yours — that is what the placeholders are for.
+
+**Why the hatch is closed rather than documented harder.** `WalletChip` is a client
+module and `AppShell.wallet` is a `ReactNode` slot, so it is the consumer's own
+page that constructs the element — and under the App Router that page is a Server
+Component by default, which is how both consumers render it, because reading the
+balance is a server read. A function cannot cross that boundary: React's Flight
+serializer walks the whole prop graph and throws on any function it finds, nested
+inside `labels` exactly as at the top level, in production as well as in
+development. So the function half was type-legal and fatal in production for the
+only way anyone uses this component, and nothing in the type said so. `tsc`
+accepted it, the dev server accepted it, and it threw at serialisation time. Score
+had to cover the hole from outside, with a runtime `typeof raw === "string"` guard
+and five tests walking the prop graph, because — in its own words — neither `tsc`
+nor the dev server will. `npm run typecheck` does now.
+
+**On plurals, plainly.** The function form was documented as the escape hatch for a
+sentence a template cannot express — ICU plurals, an `Intl.ListFormat` call — and
+this removes it. **No default label in this package needed it**, so nothing is
+degraded by the removal:
+
+- None of the five value-carrying labels is count-dependent. They interpolate a
+  preformatted date, an abbreviated balance, and three token figures; the
+  surrounding words do not change with the number.
+- The notification centre's unread count is rendered as a bare number beside the
+  `unread` tab, never interpolated into a sentence, so it needs no plural rule.
+- The one English-grammar wart is `unit`, which renders "1 tokens" at a balance of
+  one. It is pre-existing and untouched: `unit` has been a plain `string` since
+  B33-849 and never had a function form, so this change takes nothing away there.
+  Fixing it means a count-aware field, which is a decision for a human and not
+  something invented here.
+
+**If your locale does need plural selection**, do it where ICU already lives: select
+the form in your own catalogue and pass this package the finished string. That is
+what both consumers already do with next-intl, which is why the capability moves
+rather than disappears. No new mechanism was added here, and none should be added
+without deciding its shape first.
+
+**This also settles B33-1029** ("`defaultWalletChipLabels` being all-strings is a
+runtime fact pinned by a test, not a compile-time guarantee"). With the union gone
+the defaults are all-strings by construction: a function default is a type error at
+the `satisfies`, and `tests/wallet-chip-labels.type-test.ts` now asserts the
+interface's all-strings shape so re-widening one field fails typecheck rather than
+waiting for a runtime assertion to notice.
+
+### Changed — breaking — label templates are delimited `%name%`, not `{name}` (B33-1277)
+
+**If you have translated `grantExpiry`, `railFigure`, `railBalance`, `bar` or
+`meta`, your catalogue has to be edited to match.** Nothing else tells you: the
+placeholder text lives in your translation files, not in a type, so neither `tsc`
+nor a lint will find it. A template still carrying the old spelling renders the
+old spelling — `Granted expires {date}` reaches the screen with the braces in it
+and no date, because an unrecognised placeholder is left exactly as written rather
+than silently blanked.
+
+One real template, before and after:
+
+```diff
+- grantExpiry: 'Granted expires {date} · burns first'
++ grantExpiry: 'Granted expires %date% · burns first'
+```
+
+The five fields and their placeholders:
+
+| component | field | new default |
+| --- | --- | --- |
+| `WalletChip` | `grantExpiry` | `Granted expires %date% · burns first` |
+| `WalletChip` | `railFigure` | `%figure%k` |
+| `WalletChip` | `railBalance` | `Wallet balance %balance%` |
+| `WalletChip` | `bar` | `%granted% granted and %purchased% purchased of %remaining% remaining` |
+| `NotificationCenter` | `meta` | `%source% · %time%` |
+
+`AppSwitcherLabels`, `AccountMenuLabels` and `CommandPaletteLabels` have no
+value-carrying field, so they have no placeholder to rename. Each now records the
+spelling the first one will use, so the next field added does not re-decide this.
+
+**Why, in a consumer's own words.** `{\w+}` is *exactly* ICU MessageFormat
+argument syntax — what next-intl, FormatJS and every other ICU-backed library in
+the Next.js ecosystem parses. So a consumer that stores these defaults in the
+message catalogue it already has could not read them back through the formatter it
+already uses. Score's `wallet-chip.tsx` says what happens if you try: ICU *"treats
+`{date}` as an argument it was not given and renders an error string in place of
+the sentence."*
+
+**So `%name%` means a consumer reads these strings through its normal formatter.**
+`chip('grantExpiry')` is now the whole of it, and the second accessor Score had to
+write beside it can be deleted:
+
+```ts
+// boostscore/components/app-shell/wallet-chip.tsx — delete this
+const template = (key: string) => {
+  if (!chip.has(key)) return undefined;
+  const raw: unknown = chip.raw(key);
+  return typeof raw === "string" ? raw : undefined;
+};
+```
+
+Two accessors for one label bag, split on which fields happen to carry a value and
+with the wrong choice rendering formatter output in the sidebar, was the cost of
+the old delimiter. It is gone.
+
+**Why `%name%` and not the two spellings the ticket suggested.** Both keep a brace
+and so keep the bug. `%{date}` still contains `{date}` — ICU does not read `%` as
+an escape, parses the argument, and fails identically. `{{date}}` is worse: `{` is
+not a legal first character of an ICU argument name, so such a catalogue fails to
+parse at all rather than spoiling one sentence. A brace-free delimiter also clears
+i18next, Mustache, Handlebars and Vue's, Angular's and Svelte's template syntax,
+every one of which claims the double brace; and `%name%` is delimited at both
+ends, so it reads as one unit in a translator's editor where gettext's `%(name)s`
+leaves a bare `s` against the next word.
+
+**A `{braced}` name in a template is now ordinary text and is passed through
+untouched** — which is what lets the same string survive a round-trip through your
+own ICU formatter. `tests/wallet-labels-serializable.test.tsx` pins that directly,
+so the collision cannot come back by someone widening the filler's pattern.
+
+**Nothing renders differently** for a consumer that passes no `labels`, or passes
+the exported defaults: the new templates produce character-for-character what the
+old ones produced, and no screenshot baseline moves.
+
+### Changed — breaking — `WalletChipProps` no longer demands figures no product can supply (B33-483)
+
+**This makes the chip's threshold state reachable for the first time in either
+product.** It has never fired in the Wallet, and in Score it fires off a number
+Score keeps locally and says in its own comment it should not be the authority
+for. Two of the chip's three designed behaviours — the burn pill and the grown
+Top-up button — have been dead in the reference implementation since the component
+shipped. Nothing about how the threshold state *draws* changed; what changed is
+that a consumer can now get into it.
+
+**Why it was unreachable.** `grantCycle` was a required denominator, and the chip
+derived `burned = (grantCycle − granted) / grantCycle` from it. `grantCycle` is the
+Ledger's `grant_tokens_per_cycle`, and it cannot be reconstructed from a balance
+read: `cycleUsedPct` counts purchased-bucket spend too, it is not
+`(cycle total − remaining)` once a credit, refund or void has touched the account,
+and it is not bounded at 100. So the Wallet passed `grantCycle = granted`
+(`boostledger/src/app/(wallet)/layout.tsx`, commented "on purpose"), which pins
+`burned` at 0 forever, and Score passed `PLAN_MONTHLY_STOCK[plan]` instead
+(`boostscore/lib/pricing/tokens.ts`), which is its belief about the plan rather
+than the account's provisioned figure.
+
+The component was contradicting its own stated principle. `burnNote` is a prop
+precisely because "the burn estimate is the product's to make, not the chip's",
+while the burn *arithmetic* sat inside the component fed by a figure no product
+could pass. It is now the same shape as `burnNote`: **the consumer measures, the
+package decides what 80% means and draws it.**
+
+#### What changed
+
+- **`burnedFraction?: number` is new**, and is the threshold input: `0.88` for 88%.
+  Supplied, it wins. Absent, the chip derives the burn from `grantCycle` exactly as
+  before. Absent with no `grantCycle` either, nothing is claimed and the chip rests.
+  It is the figure the pill rounds, so it is a fraction and not a
+  `threshold?: boolean` — a boolean would leave the pill with nothing to print.
+- **`THRESHOLD_BURN` stays at 0.8 inside the package** and is deliberately not a
+  prop. Four products trip at the same place and cannot drift to four different
+  numbers. You supply the measurement; the policy is not yours to set.
+  `burnedFraction` is **not clamped**: a percentage passed where a fraction belongs
+  renders an absurd pill rather than a plausible "100%".
+- **`grantCycle` is now optional.** It remains the bar's denominator — what the
+  cycle started with, so the burned part of the grant draws as empty track.
+  Omitted, the denominator falls back to `granted + purchased`, the bar fills, and
+  nothing is claimed about what burned.
+- **The props are a discriminated union on `unknown`.** With `unknown: true` the
+  figures are not merely optional, they are **forbidden** (`?: never`), along with
+  `grantExpires` and `burnNote`, none of which that state renders. An explicit
+  `undefined` is still accepted, so a consumer that builds one props object rather
+  than branching can write `granted: undefined`.
+- **`WalletChipKnownProps` and `WalletChipUnknownProps` are now exported** beside
+  `WalletChipProps`, which is their union. See the `Omit` note below for why you
+  need them.
+
+#### What you need to change
+
+**The Wallet** — `boostledger/src/app/(wallet)/layout.tsx`:
+
+1. Delete `grantCycle: Number(balance.grantBalance)` and the paragraph of comment
+   explaining why it is `granted`. Pass `burnedFraction` from your own burn read,
+   or pass a real `grantCycle` and let the chip derive: `getBalance` has returned
+   `grantTokensPerCycle` since B33-1183 (ledger ADR 0013) and that function simply
+   never got wired to it. Either path reaches the threshold state; the fiction does
+   not.
+2. `if (!balance) return { granted: 0, purchased: 0, grantCycle: 0, unknown: true }`
+   becomes `return { unknown: true }`. The comment above it — "Zeroes behind
+   `unknown: true` are never rendered … but they must not be mistaken for a
+   balance" — can go with them.
+3. Annotate that helper's return type `: WalletChipProps`. Without it TypeScript
+   widens `unknown: true` in an object literal to `boolean`, which matches neither
+   member of the union, and the spread at the call site stops compiling.
+
+**Score** — `boostscore/components/app-shell/wallet-chip.tsx`:
+
+1. Delete `grantCycleFor()` and its import of `PLAN_MONTHLY_STOCK`, and pass
+   `burnedFraction` from your own burn read. Score's own comment already names this
+   as the right outcome: `PLAN_MONTHLY_STOCK` is "Score's *belief* about the plan's
+   stock" and "the authority is the Ledger's `grant_tokens_per_cycle`". The
+   `granted` floor that guarded against grant rollover goes with it — there is no
+   invented denominator left to floor. `PLAN_MONTHLY_STOCK` itself stays in
+   `lib/pricing/tokens.ts`; it is in `PRICED_CONSTANTS` and the version lock.
+2. Drop `granted={0} purchased={0} grantCycle={0}` from the `read.status ===
+   "unknown"` branch, and the comment apologising for them.
+3. Same again in `boostscore/components/app-shell/wallet-slot.tsx`, in the
+   `Suspense` fallback's pending chip.
+4. `boostscore/components/app-shell/wallet-chip-top-up.tsx` types itself
+   `Omit<WalletChipProps, "onTopUp">`, and **`Omit` over a union is not what it
+   looks like**: it flattens the union into one object and loses the discriminant,
+   so the spread back into `<WalletChip>` stops compiling. Omit from the members
+   instead:
+
+   ```ts
+   type Props = (Omit<WalletChipKnownProps, 'onTopUp'> | Omit<WalletChipUnknownProps, 'onTopUp'>) & {
+     topUpHref: string
+   }
+   ```
+
+   That is the one piece of friction the union adds, and it is the reason both
+   members are exported.
+5. `components/app-shell/wallet-bar.ts` — the dead record of B33-590's first fix —
+   can be deleted in the same pass.
+
+**Neither consumer can pass a real `burnedFraction` from the published
+`@boost33/ledger-client` yet.** The figure is on the wire (the route returns
+`getBalance` whole), but `BalanceSuccess` in
+`packages/ledger-client/src/types.ts` does not declare `grantTokensPerCycle`, so a
+typed consumer cannot read it. Until that ships, both products can take this
+version, drop their zeroes and their invented denominators, and render the resting
+chip they were already rendering — with no fiction in the props. That is strictly
+better than today and it is not a regression: `burned` resolved to 0 for the Wallet
+already.
+
+#### What did not change
+
+No class name, no markup, no accessible label, and none of the chip's visible
+states. **No fidelity baseline moved**: all five `walletchip-*` states, and every
+other gated state, come back at the identical pixel count they had before this
+change — not merely inside the tolerance, the same number. The specimen's threshold
+row keeps its `grantCycle={2400}` for the bar and now passes `burnedFraction={0.88}`
+alongside it, which is what that grant derives to exactly; the unknown row dropped
+its three zeroes, which the chip never rendered.
+
+Both defensive guards stay: B33-590's `max()` floor under a non-zero segment, and
+the `cycleTotal > 0` zero-division guard, which now also covers a chip with no
+`grantCycle` and a zero balance. B33-875's lazy `bar` label building stays too —
+the chip still defaults the absent figures to 0 internally, so a consumer's `bar`
+must still not be called on the degraded path.
+
+### Removed — the nav-budget constants and `measureNavHeight` are no longer exported (B33-483)
+
+**This is a breaking change to the published surface, and the expected migration
+is nothing.** Nine names are gone from the package entry point:
+
+```
+NAV_HEIGHT_BUDGET_PX            NAV_SHELL_FIXED_PX
+NAV_ITEM_PX                     NAV_SHELL_PACKAGE_FIXED_PX
+NAV_SECTION_HEADER_PX           NAV_SHELL_CONSUMER_SLOTS_PX
+NAV_SECTION_GAP_PX              measureNavHeight()
+NAV_FOCUS_GUTTER_PX
+```
+
+A grep of both consuming repos — `boostledger` and `boostscore`, the only two
+that depend on this package — found no importer of any of them outside
+`node_modules`. Between them they import `AppShell`, `AppSwitcher`, `WalletChip`,
+`PageHeader`, `Boost33Mark` and four types, and nothing from the nav budget. The
+Wallet's own duplicate of this arithmetic (`src/ui/shell/nav.ts`) was deleted
+whole when it migrated, so there is nothing left there to point at these either.
+If you are importing one, you are the first.
+
+**Everything useful is still published, and takes the same values it took
+before.** `navContentHeight()`, `navBudgetForViewport()` and
+`checkNavHeightBudget()` remain, with `NavHeightBudget`, `NavRowCosts` and
+`NavSectionShape`. Each function applies the withdrawn constants as its defaults,
+so the answers do not change by a pixel:
+
+- `navContentHeight(sections)` charges 33px a row, 30px a section header, 16px
+  between sections and 8px for the nav's scroll gutter.
+- `navBudgetForViewport(900)` is still 629. `navBudgetForViewport(viewport,
+  consumerSlotsPx)` still takes 185px of package furniture off, and defaults
+  `consumerSlotsPx` to the 86px specimen allowance.
+- `checkNavHeightBudget(usedPx)` still defaults its budget to 629.
+
+Overriding the two font-dependent costs is what `NavRowCosts` is for and it is
+untouched: `navContentHeight(sections, { itemPx: 35, sectionHeaderPx: 32 })`. So
+no caller needs to read a raw constant to use any of this — which is why
+withdrawing them costs nothing.
+
+**`measureNavHeight(nav)` was `return nav.scrollHeight`.** Read `scrollHeight`
+yourself.
+
+**Why they are withdrawn rather than left alone.** These are provisional numbers
+that were published as if settled, and 1.0 would freeze them:
+
+- **They have already moved silently.** B33-763 is four of these constants
+  changing value in a merged PR with no release note. Published, that is a
+  consumer's arithmetic shifting under them with no notice; internal, it is a
+  default inside a function whose behaviour change this file has to describe.
+- **The row costs are documented as unmeasured in the one direction that
+  matters.** Half of each row cost is the line box the *consumer's* font draws —
+  this package ships no face. Every family that could be measured on macOS draws
+  shorter than Inter, so the model over-counts, the safe direction. `Segoe UI`
+  sits in the fallback stack, is reported to draw a ~19px line box at 14px, and
+  would make the model *under*-count — a nav that scrolls reported as a fit. It
+  could not be measured because the pass ran on macOS, and B33-1009 is open for a
+  human on Windows to take it. When that measurement lands, `NAV_ITEM_PX` and
+  `NAV_SECTION_HEADER_PX` may move. As internal defaults they can; as nine frozen
+  exports each would have wanted a major bump.
+
+Pre-1.0 is when this is free, which is the whole reason it is happening now
+rather than after the Score migration.
+
+**Nothing else moved.** No component, prop, class name, token or rendered pixel:
+all baselines come back at their previous numbers, and
+`npm run nav-height-budget-check` reports the same eight passes against the same
+measured render. The constants are still exported from
+`src/nav-height-budget.ts`, which is where this repo's own tests, the browser
+check and `Sidebar`'s development-mode warning read them from — none of those go
+through the package entry point.
+### Added — four tokens the notification panel needed (B33-494)
+
+The tokens ship in this release; the panel they were added for does not (see
+Unreleased above).
+
+`--container-notification-panel` (360px), `--spacing-3_5` (14px), `--spacing-11`
+(44px) and `--spacing-0_25` (1px), each with its derivation in
+`data/paper-tokens.json`. **None of the four is a settled value**: they are read
+off the drawing and they move if the person at the fidelity gate moves them,
+which is exactly why they are tokens rather than literals. `--spacing-7` (28px)
+has a user again — the empty state's bell — after the compact page header stopped
+using it.
+### Removed — `PRODUCT_SLUGS` and the `ProductSlug` type, replaced by `hasProductMark()` (B33-1269)
+
+**A breaking change to the published surface, and the expected migration is
+nothing.** Two names are gone from the package entry point and one has arrived:
+
+```
+- PRODUCT_SLUGS                             the four slugs this package draws a mark for
+- ProductSlug                               the union derived from them
++ hasProductMark(slug: string): boolean     does this package draw a mark for this slug?
+```
+
+**A grep of both consuming repos found no importer of either name.**
+`boostledger` and `boostscore` are the only two that depend on this package, and
+neither references `PRODUCT_SLUGS` or `ProductSlug` in any file outside
+`node_modules`. Every hit in either repo is prose — comments explaining the 0.4.0
+rekey, none of them code.
+
+There was a real importer until 5 October, and what it was doing is worth reading,
+because it is the shape of the only call `hasProductMark` has to replace. The
+Wallet's copy of the B33-1043 slug workaround was tested by
+`boostledger/tests/product-artwork.test.ts`, which imported the list to check
+that the adapter only ever produced a key the package would draw:
+
+```ts
+const drawable: readonly string[] = PRODUCT_SLUGS;
+expect(drawable).toContain(artworkKeyFor(slug));   // then
+expect(hasProductMark(artworkKeyFor(slug))).toBe(true);   // now
+```
+
+Its own comment said why it imported the list rather than copying it: *"so it
+tracks whatever version is installed instead of a list that went stale the day it
+was typed."* That is precisely the question `hasProductMark` answers, and the
+predicate is the better way to ask it — the widening cast on the first line is
+only there because the published type was narrower than the strings being tested.
+That file and the workaround it tested were both deleted when the Wallet took
+0.4.0, as the 0.4.0 entry below instructed; Score's twin workaround went the same
+day and never imported the list at all. Two unmerged Wallet feature branches still
+carry the deleted test and will lose it when they take `main`. If you are
+importing either name today, you are the first.
+
+**The migration, line by line:**
+
+| On 0.4.0 | Now |
+| -- | -- |
+| `(PRODUCT_SLUGS as readonly string[]).includes(slug)` | `hasProductMark(slug)` |
+| `PRODUCT_SLUGS.includes(slug as ProductSlug)` | `hasProductMark(slug)` |
+| `[...PRODUCT_SLUGS]`, to list what can be drawn | `served.filter((p) => hasProductMark(p.slug))` — from the registry you were served, never from a list in your app |
+| `slug: ProductSlug` on a type of your own | `slug: string`, which is what every slug prop in this package already is |
+| `Record<ProductSlug, T>` | key it on the slugs your app itself handles, or `Record<string, T>` |
+| an exhaustive `switch (slug)` over the union | give it a `default:` — Identity can serve a slug your build has never heard of |
+
+`hasProductMark` is the whole replacement, and it answers for the version you
+have installed rather than the one you compiled against.
+
+**Why the union had to go before 1.0.** It was an artwork inventory wearing the
+clothes of a vocabulary. The four strings in `PRODUCT_SLUGS` are the slugs this
+package happens to hold a *drawing* for; which products exist is Identity's to
+say, and ADR-0003 settled that — the registry is served, and the package renders
+what it is served. Publishing the inventory as a `const` assertion handed a
+consumer a type to build on (`Record<ProductSlug, …>`, an exhaustive switch), and
+that made **adding a drawing a breaking change**: Identity serves five slugs
+today and this package draws four (`brokers`, B33-1158 above), so shipping the
+Brokers mark — the most ordinary thing this package can do — would have widened a
+published union and wanted a major bump. Frozen at 1.0 that is permanent. The
+asymmetry is what gives it away: **no exported prop was ever typed
+`ProductSlug`.** `ProductMark`'s `slug` and `AppSwitcherProduct.slug` are both
+`string`, on purpose, precisely so a registry running ahead of a mark release is
+not a type error. So the union's only real job was answering "does this slug have
+artwork", which is a question, not a type — and it is now a function.
+
+That asymmetry has already cost twice, both recorded in this file. B33-1043
+shipped as "breaking, and it breaks quietly" and needed a workaround file in each
+of the two consumer repos; the Score copy's header said it outright — *"Two copies
+of a package workaround is the cost of the package being wrong."* B33-1158 then
+had to explain in a release note that the exported union was deliberately
+narrower than the registry it claimed to describe.
+
+**What `hasProductMark` is for, and what it is not.** It is for a caller that
+needs to *know*: a consumer test asserting its own hardcoded fixtures still draw
+something, or a report of which served slugs have artwork yet. A `false` is not
+an error and needs no guard around it — `ProductMark` renders a slug it has no
+glyph for as the bare tile rather than throwing (ADR-0003's safe degrade), and in
+a switcher that row is still named, still linked and still clickable, with only
+the glyph missing. Do not use it to filter a served registry, to hide a product's
+row, or to substitute a drawing of your own: each of those turns a missing glyph
+into a missing product, and the registry running ahead of the artwork is the
+supported state, not a fault to route around.
+
+**Nothing rendered differently.** No component, prop, class name, token or pixel
+moved: the four `productmark-*` baselines come back at the ratios they had on
+0.4.0, and so does every other gated state. `PRODUCT_SLUGS` and `ProductSlug`
+still exist inside `src/components/ProductMark/ProductMark.tsx`, where `GLYPHS` is
+typed `Record<ProductSlug, ReactNode>` — so a slug added without a drawing still
+stops the build, which is the one part of this that must not go wrong quietly.
+That check is the reason the list stays a `const` assertion now that nobody
+outside the module can see it.
+
+**What it buys.** The Brokers mark (B33-1264) is now an ordinary addition: lift
+the glyph, add the slug, have a human approve `productmark-brokers.png` at a
+fidelity gate, and `hasProductMark('brokers')` flips from `false` to `true`. No
+published type widens, and no consumer has anything to do but take the version.
+
+### Fixed — a `WalletChip` segment holding tokens can no longer render below a visible width (B33-590)
+
+**This corrects a rendering defect present in every published version, 0.4.0
+included, and a seller who has bought tokens is looking at it now.** The bar
+sized each segment as a raw percentage of the cycle with no floor under it. Once
+purchased tokens sit beside the grant, the grant is a small share of the total,
+and a small share of the chip's 240px bar is a fraction of a pixel. Measured in
+Chromium against the package's own tokens:
+
+```
+                                                 before      after
+3,000 granted of a 1,000,000 cycle (0.3%)       0.719px     3.000px
+200 granted beside 100,000 purchased (0.2%)     0.469px     3.000px
+10 purchased on a spent 3,000 grant (0.33%)     0.797px     3.000px
+zero granted                                    0.000px     0.000px
+3,400 granted of 4,600 (73.9%)                177.391px   177.391px
+```
+
+Every one of the first three painted nothing on screen while the ledger still
+held those tokens. On the 56px rail, where the bar is about 40px, the same three
+painted 0.109px, 0.078px and 0.125px.
+
+A non-zero segment is now floored with `max()` against a new token,
+`--spacing-wallet-segment-min: 3px`, so the honest percentage still wins wherever
+the share clears the floor — the last row above is byte-identical, and so is
+every other width the chip has ever drawn above 1.25% of its bar.
+
+**A zero segment still collapses to `0%` and draws nothing.** That is the half a
+`min-width` in the stylesheet could not have delivered: no CSS length can tell 0%
+from 0.3%, so a `min-width` would have grown a phantom 3px sliver on a wallet
+that holds none of that kind of token — the same lie pointing the other way. The
+floor is therefore composed in the component, where the amount is known.
+
+**Both segments are floored, not only the grant.** Purchased burns second, so it
+drains to zero through every small number on the way; 10 purchased tokens beside
+a fully burned 3,000 grant is 0.33% of the cycle and is the seller's entire
+remaining balance.
+
+**What this changes for you.** Nothing in the API: no export, prop, class name or
+markup moved, and the bar's accessible label is untouched. Two things to know
+before you take it:
+
+- A segment that was painting under 3px now paints 3px, which by construction
+  over-reports its share — at 240px, 3px claims 1.25%, and on the rail's ~40px bar
+  it claims 7.5%. Taken on purpose: the alternative is a segment claiming 0%.
+- The component now writes `width: max(0.3%, var(--spacing-wallet-segment-min))`
+  where it wrote `width: 0.3%`. A consumer test asserting the inline `style`
+  string of `[data-testid="segment-granted"]` or `segment-purchased` needs
+  updating; one asserting rendered geometry does not.
+
+**It resolves through the stylesheet you already import.** The token is declared
+on `:root` in `./style.css` and in the Tailwind `@theme` entry `./theme.css`, and
+both ship it. An app rendering the chip without importing either has no bar to
+floor in the first place.
+
+Also fixed in passing: a known balance of zero on a cycle that granted zero
+(`granted={0} purchased={0} grantCycle={0}` without `unknown`) divided by zero and
+emitted `width: NaN%`, which browsers drop. It emits `0%`.
+
+**This is the second time the rendering has been reported, which is the part
+worth reading.** BoostScore raised it as B33-590 against its own wallet markup and
+fixed it there; B33-482 then replaced that markup with this component, which
+carried no floor, and the behaviour came straight back. Score's written record of
+the first fix is still on disk in that repo as dead code, at
+`components/app-shell/wallet-bar.ts` — it can be deleted once Score takes this
+version.
+
+**No baseline moved, and the screenshot gate could never have caught this.** No
+gated state has a segment under the floor — the resting chip's are 73.9%/26.1%,
+the threshold chip's 11.0%/8.1%, the rail's 60.6%/11.8% — so `max()` resolves to
+the percentage in all 27 states and each comes back at its previous number. The
+regression is pinned by behaviour tests instead, in both directions: the two
+reported ratios, and the zero cases that a naive floor would have broken.
+
+### Fixed — `AppShell` renders the page body in a `<main>` landmark, so every route of every consumer has one (B33-1265 is the Wallet's half)
+
+**Read this one before you upgrade even if you read nothing else here: if your app
+already wraps `children` in its own `<main>`, taking this version gives you two,
+and two main landmarks is worse than none.** Removing yours is part of the
+upgrade, not a follow-up.
+
+`AppShell` put `children` into a plain `<div className={content}>`. It gives the
+sidebar a `<nav>`, names it after the product, and gives the page an `<h1>`
+through `PageHeader` — and then stopped, so **no route of any consumer had a main
+landmark unless that consumer remembered a wrapper of its own.** What the absence
+costs is the first move a screen-reader user makes on an unfamiliar screen: jump
+to the main region and start reading. Without one they land at the top of the
+document and walk the wordmark, the product switcher, every nav row, the wallet
+chip, the footer links, the sidebar toggle, the search box and the avatar before
+the first word of the page — on every navigation, because the shell is a layout
+and does not remount.
+
+It is now `<main className={content}>`. The landmark is the page body alone, one
+level inside the product column: a `<main>` drawn around the column would satisfy
+any "has a landmark" check and buy the reader nothing, because jumping to it would
+land them back on the breadcrumb.
+
+**What each consumer has to do.**
+
+- **The Wallet has a wrapper and must drop it.**
+  `boostledger/src/app/(wallet)/layout.tsx` wraps `children` in its own `<main>`
+  — it patched this downstream first, and recorded in a comment there exactly what
+  the absence cost. **Until that wrapper is removed the Wallet has two `<main>`
+  elements on every route**, one from the package around one of its own. Drop it
+  in the same commit as `npm install`, and keep `FixtureBanner` where it is
+  relative to `children`. **B33-1265** carries this, including the prose in
+  `boostledger/tests/wallet-a11y.test.tsx` that says the package does not supply
+  the landmark. That test's assertions all still hold and should stay — its
+  `expect(…querySelectorAll("main")).toHaveLength(1)` is what fails the moment the
+  new package is installed with the wrapper still in place, so the upgrade cannot
+  land quietly and leave two.
+- **BoostScore has no wrapper and gains the landmark outright.** It passes
+  `children` straight through `components/app-shell/index.tsx`, and none of the
+  seventeen pages that render that shell draws a `<main>` of its own — checked,
+  not assumed. So all seventeen go from no main landmark to one with nothing to
+  change, and the thing to avoid is adding a wrapper now that the shell owns it.
+- **Any other consumer: search your shell routes for `<main`.** If you find one
+  inside `AppShell`, it is now the second.
+
+**Nothing else moved.** No export, prop, class name or style changed: `.content`
+keeps its class and every declaration behind it, and `main` and `div` are both
+`display: block`, so one is substituted for the other and the box is identical.
+All 27 gated screenshot states came back at the same pixel counts and the same
+ratios they held before the change, and no baseline was touched.
+
+**A consumer test asserting the element is what will notice.** A query for
+`div.content`, or a snapshot of the shell's markup, needs updating; a query for
+`getByRole('main')` starts passing where it used to fail.
+
+### Added — `LaunchLoader`, the screen a product shows while another one opens (B33-1389)
+
+New exports, all additive. **Nothing to do on upgrade**: no existing component,
+token value or baseline changes, and a consumer that does not import these
+renders exactly what it rendered on 0.4.0.
+
+- **`LaunchLoader`** — a full-screen launch screen: a dot-matrix loader, a
+  progress bar and a caption sitting straight on a blurred mesh in the
+  destination product's colours. The mesh drifts once — out from its
+  composition and back into it — over 5 seconds, then holds. Presentational: it
+  fetches nothing, knows no product and owns no timing. The page passes
+  `caption` (the whole sentence — word order is the language's), `stops` (four
+  colours, **darkest first**), `progress` (0–100, or `null` while
+  indeterminate), and optionally `dotColor` (default white), `busy` (drives
+  `aria-busy`, default `true`), `backdrop` and `className`. No `"use client"`:
+  it renders, its mesh paints and its dots animate from server HTML.
+- **`launchBackdropCss(stops, selector = 'html')`** — the screen's ground colour
+  as a raw CSS string, to inline in a `<style>` block in the first HTML chunk
+  with no stylesheet request. **The mesh itself is markup, not CSS**: its shapes
+  are styled inline, so it paints in the same chunk as the component on both
+  sides of a hop, from the same props — that is what keeps the hop seamless.
+  This string covers the instant before that markup parses. Also exported:
+  `launchGround(stops)` and `launchSolid(stops)`. A stop that is not a plain CSS
+  colour — anything carrying `;`, `{`, `}` or `<` — throws rather than being
+  inlined.
+- **`DotMatrixLoader`** — the 3×3 pulsing grid on its own, pure CSS, 0 KB of
+  animation runtime. `label` defaults to `"Loading"` (an indeterminate
+  progressbar with that name); `label={null}` hides it from the accessibility
+  tree entirely, which is what `LaunchLoader` passes.
+- **`LaunchGradientStops`**, `LaunchLoaderProps`, `DotMatrixLoaderProps` — types.
+
+Three new motion tokens in `motion-tokens.css`, beside the Hub's set and named
+in its scheme: `--dur-dots` (1000ms, one cycle of the dot wave),
+`--ease-in-out-quint` (`cubic-bezier(0.83, 0, 0.17, 1)`) and `--dur-drift`
+(5000ms, the mesh's single drift — a WCAG 2.2.2 ceiling, not a taste). None of
+the three names exists in the Hub, Tailwind's default theme or the Wallet, so
+none collides.
+
+**What to know before you render it.**
+
+- **It is `position: fixed; inset: 0`.** It covers the viewport, so the hub can
+  paint it over the page it is leaving. Stacking order against your own layers
+  is yours — pass a `className` with a `z-index`. To frame it instead (a
+  preview, a story), give an ancestor `contain: layout`.
+- **Accessibility is built in; do not add to it.** The caption is the single
+  source of the words: it carries `aria-live="polite"` and names the progress
+  bar, and the bar sits outside it so value ticks never re-announce the
+  caption. Rewrite `caption` to announce a new phase. Set `busy={false}` the
+  moment real content lands. Do not wrap it in another `role="status"` — that
+  is the double announcement this markup exists to remove.
+- **Your stops carry the caption's contrast. Read this before choosing them.**
+  There is no plate behind the words. The mesh is painted in six tones derived
+  from `stops[0..2]` — `stops[3]` is not painted — and its dark channel runs
+  through the centre, built from `stops[0]`, `stops[1]` and the mixes between
+  them. So **`stops[0]` and `stops[1]` must each be at or under relative
+  luminance 0.183**. Measured in Chromium at six viewports from 1920×1080 to
+  360×640, at rest and at every half second of the drift, on both provisional
+  palettes: the caption (white at 80%) is **8.41:1** at worst, and white over
+  the bar and dots **7.32:1** at worst. `prefers-contrast` (the boolean form)
+  drops the mesh for the flat `stops[0]`, drops `backdrop`, and draws the dots
+  and track in full white with no blend.
+- **The progress bar meets WCAG 1.4.11.** Its track blends into the mesh
+  (soft-light, 75%); its fill is solid white outside that blend, at **11.95:1**
+  against the track on Score and **10.93:1** on Wallet.
+- **The dots are quiet on purpose.** They blend soft-light at full strength and
+  measure 2.37:1 against the mesh on Score, 2.36:1 on Wallet — soft-light's
+  ceiling, which no opacity raises — and in Wallet's greens they nearly vanish.
+  They are decorative and `aria-hidden`, so WCAG 1.4.11 does not apply, and the
+  owner kept the blend on both palettes on 14 October 2026 with those figures in
+  hand. Not a defect; do not file it as one.
+- **If you built a stand-in against a pre-release description:** `launchGradient`
+  never shipped, and the seam no longer rests on a shared CSS string. Render
+  `<LaunchLoader>` server-side on the arriving page so its inline-styled mesh is
+  in the first HTML chunk on both sides, and inline `launchBackdropCss(stops)`
+  for the instant before it parses.
+- **`caption` can be one line.** The first consumers pass a single static
+  caption ("Opening Boost Score") for the whole launch. `aria-live` stays on it:
+  inert while the text holds still, and what announces a change if you do
+  rewrite it. If your stand-in removed `aria-live` with a comment saying why,
+  delete the comment at swap time; do not reinstate the removal.
+- **The drift never breaks the seamless hop.** It starts and ends on the
+  composition — measured at 1/255 at most — so a launch's first frame is the
+  same on both sides and its last is the designed one. It moves the blurred
+  mesh as one layer, a compositor transform, rather than re-blurring it each
+  frame.
+- **Reduced motion** keeps the mesh and stops the drift, and leaves nine solid
+  dots and a parked bar segment, all in CSS — there is no JavaScript preference
+  read to stub in tests.
+- **The `backdrop` slot is optional and must stay so.** It is where an animated
+  layer goes; the screen is complete without it. The drifting WebGL gradient is
+  **deferred out of v1** by the owner's decision of 14 October 2026, not
+  missing.
+
+**Approved at its fidelity gate on 14 October 2026.** No product had shown a
+launch screen, so there was no Wallet referent: the owner judged it on the
+specimen, captured its four designed baselines himself, and approved its
+measurements into the spec ("LaunchLoader, recorded at its gate"). Those are
+now binding; a change to them is a human re-approving, and its entry here will
+say what moved. The product colours are yours to pass and
+are themselves still provisional upstream. **A filter blur across the whole
+screen has a GPU cost that has not been measured on a budget phone.**
+
+### Internal — no consumer-visible change
+
+- `tests/wallet-chip-props.type-test.tsx` is new. B33-483's fix lives entirely in
+  the type — the chip never rendered those zeroes either way — so there is nothing
+  for a behaviour test to observe and `tsc` is the check. It is not a `.test.tsx`
+  by vitest's reckoning: `vitest.config.mts` includes only `tests/**/*.test.ts(x)`
+  while `tsconfig.json` includes all of `tests`, the same arrangement
+  `wallet-chip-labels.type-test.ts` already uses. Every `@ts-expect-error` in it
+  fails typecheck with TS2578 if the props loosen back.
+- `tests/wallet-chip.test.tsx` gains fifteen cases: the threshold reached through
+  `burnedFraction` with no denominator at all, precedence in both directions
+  against a `grantCycle` that disagrees, the 0.8 trip point pinned on both sides,
+  the bar's fallback denominator, and two cases asserting that the unknown chip's
+  markup is byte-identical with and without the figures it used to demand — which
+  is what holds `walletchip-unknown` still. Nine existing cases dropped the zeroes
+  they were passing behind `unknown`.
+- `specimen/routes/WalletChipSpecimen.tsx` renders the unknown row as a bare
+  `<WalletChip unknown />` and the threshold row with both `burnedFraction` and
+  `grantCycle`, so the new prop path appears in the specimen rather than only in
+  the tests (CLAUDE.md, build-once components).
+- `tests/app-shell.test.tsx` gains five cases on the landmark: that the body is
+  inside it, that there is exactly one, that the nav, the sidebar and the top
+  bar's controls are outside it, and that both a header-less screen and the rail
+  still get one.
+- Every specimen route frame is a `<div>` rather than a `<main>`. The stacked
+  specimen page put twelve route-level landmarks on one page and nested two of
+  them once the shell drew its own, so the only `<main>` elements there are now
+  the five the shells draw — what a consumer actually gets. Two new cases in
+  `tests/specimen-coverage.test.tsx` hold that: nothing nested, and no `<main>` on
+  the page containing chrome. `scripts/sidebar-overflow-check.mts` found the
+  Sidebar route by taking `main` first, which was that route only because it
+  renders first; it now reads a named `data-specimen-route="sidebar"` handle.
+  `sectionKey` in the coverage test reads the section's parent rather than the
+  nearest `<main>` for the same reason.
+- `tests/product-mark.test.tsx` gains a `hasProductMark` block held against the
+  component's rendering rather than against the list it is implemented from: a
+  `true` must mean a glyph draws, a `false` must mean the bare tile draws, and
+  `toString` / `constructor` are pinned false because `GLYPHS` is a plain object
+  literal and a predicate written as a property lookup would report both as
+  artworked. The Identity pin from B33-1043 is untouched and now asks the same
+  question through `hasProductMark` as well as through the internal list; it
+  reads the list by deep import, as every test here reads `src/`.
+- `tests/product-mark-surface.type-test.ts` is new, in the shape of
+  `wallet-chip-labels.type-test.ts`: a `@ts-expect-error` pin that fails
+  `npm run typecheck` if either name returns to `src/index.ts`. The runtime test
+  can only see the value, and a type cannot be absent from a runtime namespace —
+  re-exporting `ProductSlug` is one line and would otherwise pass everything.
+- `specimen/routes/ProductMarkSpecimen.tsx` reads `PRODUCT_SLUGS` from the
+  component module instead of the barrel. Same four frames, same testids, same
+  baselines.
+- `tests/wallet-chip.test.tsx` gains seven cases around the segment floor. Four
+  fail against the unfixed component and four fail against an unconditional
+  `max()`, which is the shape a floor written as a bare `min-width` would have
+  had. The existing `sizes segments against everything the cycle started with`
+  case is updated for the new spelling of the same percentage.
+- `fillTemplate` moves out of `WalletChip/labels.ts` into `src/fill-template.ts`,
+  flat at the root beside `anchored-overlay.ts` and unexported from the package.
+  Byte-identical behaviour and no API change — the point is that the third labels
+  module reuses it rather than copying it, which is how two of the five lines
+  would have drifted the day one of them was fixed (B33-1007's shape, one level
+  down).
+- The specimen gains a `NotificationCenter` route with both states, rendered last
+  in `specimen/main.tsx` so no gated state moves down the page and re-rasterizes
+  (B33-1012). Neither state is gated and both are recorded in `SPECIMEN_ONLY`
+  with the reason: their baselines are *designed* ones, and only the person at
+  the fidelity gate may capture them. `npm run screenshot-diff` reports all 27
+  existing states unchanged, `appswitcher-open` included at 0.000%.
+- Both `AppShell` specimen routes compose the page header the way both consumers
+  do — inside `children` — now that there is no other way (B33-1267). Only the
+  stress route ever passed the prop, and it is ungated in a fixed-height stage,
+  so nothing on the page moved: `npm run screenshot-diff` reports all 27 gated
+  states at the ratios they held before.
+- The `SKIPPED_BASELINES` reasons for `appshell-expanded` and `appshell-rail` are
+  rewritten for the same change, and the `SPECIMEN_ONLY` captions on the Wallet
+  reproduction corrected from "diffed against appshell-expanded.png" — which
+  stated an intent, not the present state — to "reproduces appshell-expanded.png,
+  not yet diffed against it". B33-1267 predicted the two baselines had been
+  captured through the prop path and would stop being reproducible; they had not,
+  and they are. Both PNGs are the Wallet's overview, which renders no title at
+  all, and the route carrying their testids never passed `pageHeader`. The
+  re-capture they wait on is still a human's, and it now pins a shell whose page
+  titles live in `children`. No baseline was written.
+- `tests/specimen-coverage.test.tsx`'s "every main on the page is a shell page
+  body" guard identifies a route frame by the `<section>` it contains rather than
+  by an `<h1>`. The `<h1>` was a proxy for "this is a frame, not a page body", and
+  it stopped discriminating the moment a page's own header legitimately lives in
+  `children` (B33-1267). The `aside` and `nav` halves are unchanged.
+- The specimen gains two ungated routes for the unarmed shapes B33-1270
+  introduces — `WalletChipUnarmedSpecimen` (resting and threshold with no
+  `onTopUp`) and `AppSwitcherUnarmedSpecimen` (the open panel with no
+  `account.onSelect`) — rendered last in `specimen/main.tsx` so no gated state
+  moves down the page (B33-1012). All three sections are recorded in
+  `SPECIMEN_ONLY` with the reason: there is no captured referent for either shape,
+  so a first picture of them is a *designed* baseline and a human's to take.
+- The gated states on `WalletChipSpecimen` and `AppSwitcherSpecimen` now pass
+  handlers. That is what keeps their baselines still: the chip's button and the
+  switcher's account-row chevron exist only where a handler arms them, and the
+  baselines are photographs of the Wallet's shell where both were live. The
+  "Stage A … no handlers" line at the top of each route is corrected, because it
+  is no longer what the route does.
+  `scripts/wallet-name-overflow-check.mts` depended on this from the other side:
+  it reads `chip.querySelector('button')` on three of those states to measure a
+  translated wallet name against the Top-up label, and throws on a chip with no
+  button. All 30 of its combinations still pass.
+- `tests/wallet-chip.test.tsx` gains six cases and `tests/app-switcher.test.tsx`
+  six: the control absent with no handler, absent for an explicitly `undefined`
+  one, no `disabled` or `aria-disabled` left in its place, everything around it
+  still rendered, and — in both files — the armed shape asserted in the same
+  breath, so the gate cannot be satisfied by never drawing the control at all.
+  The switcher's two real-Tab traversal walks now render the armed account row,
+  because ADR-0010's "every row is its own tab stop" is a claim about rows that
+  are real links and buttons; the unarmed row's absence from the tab order is its
+  own case.
+- `tests/public-api.test.ts` and `tests/public-api.type-test.ts` are new, and they
+  pin the published export surface — 24 value names with their runtime `typeof`,
+  37 type names — against two explicit sorted lists written in the test file
+  (B33-1280). Nothing imported `src/index.ts` before: every other test imports a
+  deep path and only the specimen routes import the barrel, so every name withdrawn
+  or added above in this section passed every gate in the repo on its way through.
+  Not a vitest snapshot, deliberately — a `.snap` is updated by a flag and nobody
+  reads one in a diff, and the whole value of the lists is that they are visible in
+  the pull request that changes them. The value half is read from the runtime module
+  namespace and the type half from the barrel's own export specifiers, because a
+  type-level check can prove a pinned name is still exported but can never report
+  one that *appeared*; the two meet where the parser's value names are asserted
+  equal to the namespace's keys. **What it changes for everyone else is the failure
+  message**: a surface change now fails naming what appeared or vanished, that a
+  removal is breaking, and that a deliberate change means updating the list *and*
+  writing an entry here. No consumer-visible change — `files` is `["dist"]` and
+  `dist/` is built from `src/index.ts` alone, so no test reaches a consumer.
+- `specimen/` gains a `LaunchLoader` route — Score's palette determinate and
+  indeterminate, Wallet's greens, and the dot matrix alone — rendered last so
+  it moves no gated state. Every row is recorded in `SPECIMEN_ONLY`. **No
+  baseline was captured**: the first one is a human's to take at the fidelity
+  gate.
+- `scripts/launch-contrast-check.mts` (`npm run launch-contrast-check`, a new
+  step in the screenshot job) measures the brightest composited pixel behind
+  the caption, bar and dots for both provisional palettes at six viewports and
+  at every 500ms of the drift; judges the 80% caption by the mix it composites
+  to; fails if the drift at rest differs from the composition by more than
+  4/255; and asserts the bar's fill against its track. Its arithmetic is
+  `scripts/launch-contrast.ts`.
+- `tests/launch-loader.test.tsx` covers the ARIA wiring, the screen with no
+  backdrop layer, the inline-styled mesh and its single blur, the
+  reduced-motion and `prefers-contrast` CSS paths, the drift's bounds, the bar
+  split, the content box staying out of the stacking order, the stops contract
+  against both provisional palettes, the contrast arithmetic, and the inlinable
+  CSS's refusal of unsafe stops. `tests/guards.test.ts` holds both new
+  components to the server-safe hook rule.
+
+## 0.4.1 — 2026-10-14
+
+### Changed — the Hub's motion standard: new motion tokens, shared button, spinner and skeleton classes, a reduced-motion backstop, and a top bar shadow on scroll (B33-1379)
+
+**Additive, with two things to check before you upgrade.** Cut from 0.4.0 with
+only this change; the unreleased breaking work on main is not in it. The old
+token names keep working for this release.
+
+**New tokens on `:root`**, from the Hub's `globals.css` and at its values
+(`src/motion-tokens.css`, `src/elevation-tokens.css`):
+
+| | |
+| --- | --- |
+| Durations | `--dur-instant` 80ms, `--dur-fast` 150ms, `--dur-base` 220ms, `--dur-slow` 320ms, `--dur-bold` 700ms, `--dur-hero` 900ms, `--dur-spin` 700ms, `--dur-pulse` 1600ms |
+| Easings | `--ease-out`, `--ease-in`, `--ease-spring` |
+| Distances | `--lift-sm` -1px, `--lift-md` -2px, `--rise` 8px, `--stagger` 40ms |
+| Shadows | `--shadow-lift`, `--shadow-scrolled` |
+
+**Deprecated: `--duration-fast` and `--easing-standard`.** They are now aliases,
+`var(--dur-fast)` and `var(--ease-out)`, and are removed in the release after
+this one. They carry the new values, not 120ms and `cubic-bezier(0.2, 0, 0, 1)`:
+the decision was to adopt the Hub's motion, not keep both. No product reads
+either today. Every component in the package now reads the new names, so the
+nav item, the switcher chevron and the wallet chip move at 150ms on the Hub's
+ease-out instead of 120ms on the old curve. Under reduced motion nothing
+changes.
+
+**New classes in `style.css`**, which you put on your own elements. Each owns
+colour, border and state (hover, press, disabled); you keep height, padding,
+radius and type, and `.btn-quiet`'s border, which it leaves to you as the Hub
+does:
+
+- `.btn-primary`, `.btn-quiet`, `.btn-danger`
+- `.spinner`, with `.spinner--sm` and `.spinner--primary` for a light ground
+- `.sk` (a pulsing placeholder), `.sk-group` (holds a skeleton back 150ms so a
+  fast read never shows one), `.reveal` (fades in the content that replaces it)
+
+The Hub can delete its own copies of these: the names and behaviour match.
+
+**The top bar casts a soft shadow once the shell's content has scrolled**,
+fading in over the first 40px. It is CSS only, with no prop and no markup
+change, and only inside `AppShell`; a `TopBar` you render on its own looks as
+before. It needs scroll-driven animations, `timeline-scope` and style queries;
+it was checked in Chromium, and a browser missing any of the three draws no
+shadow, as before.
+
+**Check your app: the reduced-motion backstop is app-wide.** Under
+`prefers-reduced-motion: reduce`, `style.css` now makes every animation in
+your app 0.01ms and plays it once, and every transition 0s, with `!important`,
+not only the package's. (The Hub writes 0.01ms for transitions; 0s is
+deliberate, see ADR-0014.) That is the standard's rule. **The Wallet should look at this
+first**: its own reduced-motion design keeps opacity fades at half duration
+("no travel, not no feedback"), and the backstop removes them. Only a layered
+`!important` rule of yours can override it.
+
+**Check your app if you declare `--ease-out` yourself, or use Tailwind's
+`ease-out`.** Tailwind v4's default theme declares `--ease-out:
+cubic-bezier(0, 0, 0.2, 1)`, and the Wallet's `src/ui/tokens/motion.css`
+declares `--ease-out: cubic-bezier(0.2, 0, 0, 1)`. Both sit in a cascade layer;
+the package's declaration does not, so it wins in either import order and those
+uses switch to the Hub's `cubic-bezier(0.22, 1, 0.36, 1)`. In the Wallet that
+is `Sheet`'s scrim and panel, and the comment above its
+`@import '@boost33/ui/style.css'` saying there is no collision is no longer
+true. `--ease-in` is declared with the same value in all three places, so it
+changes nothing.
+
+**To adopt it:**
+
+1. `npm install @boost33/ui@<version>`. No code change is needed to keep
+   working.
+2. Check the two items above against your app.
+3. Replace any `var(--duration-fast)` / `var(--easing-standard)` of your own
+   with `var(--dur-fast)` / `var(--ease-out)` before the aliases go.
+4. Optionally, use the new classes and tokens instead of your own copies, and
+   delete any local declaration of `--dur-*`, `--ease-*`, `--lift-*`,
+   `--rise`, `--stagger` or `--shadow-lift`. A copy of a package token is a
+   collision (ADR-0011).
+
+See `docs/adr/0014-the-package-adopts-the-hubs-motion-standard.md`.
+
+Repo-only: the specimen has a new, ungated "Motion classes" route at the
+bottom, recorded in `SPECIMEN_ONLY`, and `tests/motion.test.ts` builds the
+package and checks the classes reach `style.css`.
+
+## 0.4.0 — 2026-10-02
+
+### Added — `AppSwitcherProduct.live`, so an unbuilt product stops reading as an unbought one (B33-561)
+
+`AppSwitcherProduct` takes an optional `live?: boolean`, defaulting to `true`.
+`false` dims the mark and puts a **"Soon"** tag in the row's tag slot, in place
+of "Not on plan". `AppSwitcherLabels` gains `soon`, default `"Soon"`, so the word
+translates like every other string the switcher renders.
+
+**Nothing to do on upgrade.** `live` is optional and defaults to true, so a call
+site that does not mention it renders exactly what it rendered on 0.3.1 — the
+three `appswitcher-*` baselines come back at 0.000% against this version. This
+entry is here because it closes a defect you may be looking at, not because it
+asks anything of you.
+
+**What it fixes.** Identity has served `live` on every registry row since
+`GET /api/v1/products` existed, and this interface had nowhere to put it, so both
+consumers read the field and dropped it — each with a comment in its registry
+client saying so and calling it worth a package ticket. The visible cost: a
+product that has not shipped rendered identically to one the account had not
+bought. A client looking at Boost Voice saw "Not on plan" against a product
+nobody is on, and the row invited them to go and ask about buying something with
+no code behind it. That confusion is the reason Identity carries two fields
+rather than one (`live` in `boost33-identity/src/lib/productRegistry.ts`).
+
+**Why one tag slot and not two.** A product that has not shipped is held by
+nobody, so Identity serves every `live: false` row as `entitled: false` as well,
+and both conditions are true on the same row. The unbuilt word wins the slot:
+rendering both would stack two pills where there is room for one, and the second
+would answer a question the first has closed. `data-live="false"` is on the row
+alongside the existing `data-entitled="false"` if you need to style them apart.
+
+**Still a rendering hint, never an authorization decision.** Same rule as
+`entitled` (ADR-0010, "Not entitled is not disabled"; Identity contract §1.5). An
+unbuilt product's row stays an ordinary focusable link, because Identity serves a
+`url` for every slug whether or not anything answers on it — `?app=<slug>` has to
+resolve for a campaign link to grant anything on sign-up. Do not branch on `live`
+to decide access.
+
+**To wire it:** stop dropping the field. `switcherProducts` in both consumers
+maps the registry row into `AppSwitcherProduct` and is the single place it goes
+missing.
+
+### Known gap — Identity serves a fifth product and this package has no mark for it (B33-1158)
+
+**No action, and nothing regressed. Read this if a switcher row draws a blank
+tile under the name "Boost Brokers".**
+
+Identity's registry now serves five slugs: the four in `PRODUCT_SLUGS` plus
+`brokers`. This package has no `brokers` glyph, so `ProductMark` draws the bare
+tile through ADR-0003's safe degrade — the row is still named, still linked and
+still clickable, and only the artwork is missing. That is the same symptom
+B33-1043 describes above, with a different and much narrower cause: there, three
+of four rows were blank because the package had the slugs wrong. Here, one row is
+blank because the mark does not exist yet.
+
+**`PRODUCT_SLUGS` is now deliberately narrower than Identity's registry**, and
+its doc comment says so rather than claiming to be the whole list. The exported
+`ProductSlug` union is unchanged from 0.3.1 — still the same four strings — so
+this is additive documentation, not a type change.
+
+**Why the mark was not simply drawn.** The four existing glyphs were lifted
+verbatim out of `boostledger/src/ui/primitives/icons.tsx`, which types its own
+`GLYPHS` over exactly four display names and holds no Brokers mark. There is none
+in `boost33-brand-hub` either, and none here; the hub renders the product as a
+text quick-link with no mark at all. So there is nothing to transcribe, and
+drawing one from the name would be inventing the reference rather than matching
+it — which is the specific failure PR #4 already committed on all four marks, and
+which is worse for a fifth, because a human capturing the first baseline at the
+fidelity gate would make the invention the referent and it would look settled
+afterwards either way (`CLAUDE.md`).
+
+**It is the mildest version of this problem.** Identity serves `brokers` as
+`live: false`, so with the `live` field above wired the row reads "Soon" beside
+its bare tile — a product that has not arrived, rather than a drawing that failed
+to load. That stops being true the day Brokers ships, which is the deadline on
+closing it.
+
+**To close it:** get the mark drawn where the other four live, lift it here
+verbatim, add `brokers` to `PRODUCT_SLUGS`, and have a human approve
+`productmark-brokers.png` at a gate. `GLYPHS` is typed against `PRODUCT_SLUGS`,
+so adding the slug without the artwork stops the build rather than shipping a
+silent blank.
+
+### Not fixed here — a switcher showing only the product you are in is not this package
+
+**Stated because it is the obvious thing to expect of a version that touches the
+switcher, and it would be wrong.** If your panel lists one row, naming the
+product you are already standing in, nothing in any version of `@boost33/ui`
+causes that and nothing in this one fixes it. `AppSwitcher` renders every row in
+the `products` array it is handed, and filters none.
+
+What produces that symptom is an empty `products` array and the fallback each
+consumer applies to one: `switcherProducts` in both apps returns a single
+synthetic row for the current product when the registry comes back empty, which
+is the right degrade and is doing its job. The empty array is upstream of it. As
+of 2 October 2026 both consumers call `GET /api/v1/products` server-to-server
+with a service key and no `b33_sid` cookie, and that endpoint is a **browser**
+endpoint — Identity contract §4, and `boost33-identity`'s own test
+`is 401 for a caller with no session, never a registry`. So the call 401s on
+every render, for every account, and the fallback is all anybody ever sees. The
+fix is in the consumers' registry clients, not here.
+
+### Changed — `PRODUCT_SLUGS` now holds the slugs Identity actually serves (B33-1043)
+
+**Breaking, and it breaks quietly.**
+`PRODUCT_SLUGS` was `['wallet', 'score', 'voice', 'outbound']`. It is now
+`['wallet', 'boostscore', 'boostvoice', 'boostoutbound']`, which is what
+`GET /api/v1/products` returns — `REGISTRY_SLUGS` in `boost33-identity`,
+`src/lib/productRegistry.ts`. `GLYPHS` is rekeyed to match, so the exported
+`ProductSlug` union changes with it.
+
+Three of the four were wrong. The package dropped Identity's `boost` prefix on
+every product and kept only `wallet` by coincidence:
+
+| Identity serves | 0.3.1 expected | Now |
+| -- | -- | -- |
+| `boostscore` | `score` | `boostscore` |
+| `boostvoice` | `voice` | `boostvoice` |
+| `boostoutbound` | `outbound` | `boostoutbound` |
+| `wallet` | `wallet` | `wallet` |
+
+**What a consumer on 0.3.1 is seeing right now.** `ProductMark` draws the bare
+tile for a slug it has no glyph for rather than throwing (ADR-0003's safe
+degrade, and right in isolation). So an app that pipes the served registry
+straight into `AppSwitcher` — which is exactly what B33-472 and B33-479 intend —
+renders three of its four rows as blank tiles, with no exception, no console
+warning and no failing test. The rows are still named, still linked and still
+clickable; only the artwork is missing. If your switcher looks like that, this
+is why.
+
+**What breaks on the upgrade.** Anything that hand-writes `score`, `voice` or
+`outbound` — a `slug` prop, a `currentSlug`, a products array built in the app
+rather than fetched. Those are correct on 0.3.1 and draw a blank tile on this
+version, and **the compiler will not tell you**: `ProductMark`'s `slug` prop and
+`AppSwitcherProduct.slug` are typed `string` rather than `ProductSlug`, on
+purpose, so that a registry running ahead of a mark release is not a type error.
+A `typecheck` that stays green is not evidence here. Grep your app for the three
+old strings before upgrading — the only case that does fail loudly is code that
+imports the `ProductSlug` type and annotates with it. A products array that
+comes from Identity needs no change and starts drawing its marks.
+
+**The Wallet has a bridge to delete, not to update.** `boostledger` is on 0.3.1
+and carries `src/lib/product-artwork.ts`, which maps Identity's slug to the
+artwork key the old package expected (`boostscore` → `score`) at the single point
+where the prop is filled. Taking this version without deleting that file
+reinstates exactly the blank tiles it was written to prevent, because the mapping
+now translates a slug the package draws into one it does not. Its own test
+`only ever produces keys the installed package has artwork for` reads
+`PRODUCT_SLUGS` from the installed package at runtime, so it goes red on the
+upgrade and says so — the fix there is to delete the file, drop the
+`artworkKeyFor` call in `src/app/(wallet)/layout.tsx`, and delete the test with
+it. That is B33-481's work.
+
+**Identity is not the side that moves.** Its slugs match the `?app=` keys that
+live campaign URLs already carry, so renaming one stops those links granting the
+product on sign-up. ADR-0003 in this repo records the shorter slugs as considered
+and rejected for that reason — this package shipped the rejected option and
+described it in a comment as the accepted one.
+
+**Why it survived review.** `PRODUCT_SLUGS`'s doc comment asserted the list was
+Identity's, and nothing in either repository compared the two. A reader checking
+found the claim and stopped. The comment now names its source file and says it is
+a transcription, and `tests/product-mark.test.tsx` pins the list against a second
+transcription of the same source so the two repositories cannot part company in
+silence again.
+
+### Internal — no consumer-visible change
+
+- The switcher specimen gains an ungated `open — unbuilt products` row showing
+  the "Soon" tag, and the `ProductMark` specimen's degrade row now draws the real
+  `brokers` slug instead of the stand-in `nonesuch` it used to. Both are recorded
+  in `SPECIMEN_ONLY` in `scripts/screenshot-states.ts`: the Wallet never rendered
+  a "Soon" tag — it had no registry to read `live` from — so there is no captured
+  referent for it and the first baseline is a human's to take at a fidelity gate.
+  **No baseline was captured or regenerated.** All 27 gated states diff at
+  exactly the ratios they did on 0.3.1, `appswitcher-open` among them at 0.000%.
+- `tests/product-mark.test.tsx`'s Identity pin is re-transcribed against the
+  five-slug registry and now pins the gap as well as the overlap: `brokers` is
+  recorded as a served slug this package deliberately draws nothing for, and
+  separate cases assert it still draws the bare tile and is still a slug Identity
+  really serves. A sixth product, a rename, or artwork arriving for this one each
+  fail a test rather than passing quietly.
+- The four `productmark-*` baselines are renamed to follow the slugs
+  (`productmark-score.png` → `productmark-boostscore.png`, and the same for voice
+  and outbound), with `scripts/screenshot-states.ts` and `scripts/border-proof.ts`
+  following. **The files were renamed, never re-captured** — the PNG bytes are
+  untouched, and all four still diff at 0.000% against the component. The
+  switcher specimen's four rows carry the corrected slugs; `appswitcher-open` is
+  also 0.000%, which is the rename proving it moved no pixels anywhere.
+
+## 0.3.1 — 2026-09-23
+
+### Fixed — the `AppSwitcher` panel is drawn at the Wallet's measurements (B33-910)
+
+**This corrects a rendering defect that shipped in 0.3.0.** A consumer on 0.3.0
+has it, and it is visible. B33-479 corrected the marks and the type size before
+the component landed; the box around them was not corrected with them. In the
+open panel the product rows are 40px tall where the Wallet's are 36px on a 38px
+pitch, the row names are bold where the Wallet's are regular, the Hub's glyph
+and the account avatar are 28px where they are 20px and 24px, the rows are
+padded 10px and 12px where the Wallet pads them 8px, and the panel is 240×318
+where the Wallet's is 264×293. The visible consequence is that `Boost Outbound`
+truncates to `Boost O…` against its `Not on plan` tag — a product name a
+consumer supplies, cut off in a menu whose job is to name the products.
+
+Nothing about the fix is new information. The three `appswitcher-*` baselines
+are photographs of the Wallet's own switcher from 9 September 2026, and they
+were in the diff and passing the whole time. A 5% pixel-ratio threshold is loose
+enough that a panel 25px too tall, with every row inside it in the wrong place,
+still scores 4.835% — and the 24px the panel was too narrow moved no countable
+pixel at all, because the edge it moved is drawn in `--color-border` against
+`--color-surface`, which is under pixelmatch's colour cutoff at this threshold
+(`scripts/screenshot-diff.mts`, `PIXELMATCH_COLOR_THRESHOLD`). Against those
+baselines:
+
+```
+                      before                    after
+appswitcher-closed    768/115200    0.667%      3/115200      0.003%
+appswitcher-open    20052/414720    4.835%   1031/414720      0.249%
+appswitcher-rail     1312/36608     3.584%      0/36608       0.000%
+```
+
+No baseline was touched: `tests/baselines/` is unchanged, and the other 24
+states come back bit-identical to their previous numbers.
+
+**Where the numbers came from.** The spec document *The shared app shell*
+settles the trigger and only the trigger — a `--color-border-strong` hairline,
+9px block and 8px inline padding, `--radius-lg`, a 2px gap beneath it before the
+panel, and 14px nav-adjacent labels. Every one of those is unchanged here. Three
+things on the trigger that the spec does *not* settle were wrong and are
+corrected from `appswitcher-closed`: the label sits 8px from the mark rather
+than 10, it is semibold rather than bold, and the chevron is 12px rather than
+16. That state goes from 768 differing pixels to 3.
+
+Everything below the trigger is silent in the spec too, so it is measured off
+the approved baselines rather than re-derived from Paper, which CLAUDE.md
+forbids for exactly the reason the nav radius was corrected twice in opposite
+directions. The measurements, and what each one is evidence of: rows 36px tall
+at a 38px pitch (the current row's fill is 36px and the four product marks sit
+38px apart); 8px of block and inline row padding with 10px between mark and
+text (the mark's box starts 8px inside the row and the name's 10px after it);
+row names at 14px regular (`Boost Outbound` inks 105.5px — Inter's advance for
+it is 105.2px at 14/400 and 109.3px at 14/700); the Hub's second line at 12px
+(`All Boost33 products` inks 117.5px, against 117.6px at 12px); the account row
+one step down again at 13px over 11px, with 12px of inline padding and a 24px
+avatar; the `Not on plan` tag at 11px; the check at 16px and the trigger's
+chevron at 12px; and the panel 264px wide — the sidebar's full width, keeping
+the trigger's left edge and overhanging the sidebar's right, which is what the
+baseline shows, its right border landing flush against the frame.
+
+**The rail residual 0.3.0 recorded is closed, rather than traded away.** That
+entry noted the rail's mark sitting 8px below where the baseline puts it,
+because the 8px of block padding that dropped it was also what kept the
+collapsed trigger a 24px target. The button's box is invisible in that state —
+no border, no fill — so the two are independent: the mark is now flush with the
+switcher's top edge where the Wallet draws it, and a `min-height` keeps the
+target at 24px below it. `appswitcher-rail` is exact.
+
+> One residual, recorded rather than hidden. `appswitcher-open` lands at 1031
+> differing pixels rather than 0, and they are not spread over the panel: about
+> half are the Hub row's 2×2 glyph, which fills 17px of its 20px box where the
+> Wallet's fills 18px, and most of the rest are the current row's check and the
+> account row's chevron, each sitting about 1px off. Those are the proportions
+> of three drawings rather than measurements of the layout, and redrawing a
+> glyph to close a pixel is the kind of re-derivation this repo has been burned
+> by. Left as it is, and named here so the next person reading that number knows
+> it was looked at.
+
+**One new published token, `--text-3xs: 9px`**, the size of the initials in the
+account row's avatar, which were drawn at `--text-xs`. No existing token value
+changed. Everything else here is `AppSwitcher.module.css`, so it reaches a
+consumer through the compiled `./style.css` on the version bump: no export
+changed, no prop changed, and no markup moved.
+
+### Internal — no consumer-visible change
+
+- The switcher specimen lists its four products in Identity's registry order with
+  the right one locked (Boost Score, Boost Outbound, Boost Voice, Wallet; Voice is
+  the unbuilt product an account cannot hold). It previously had Voice and Outbound
+  the other way round, so the specimen demonstrated a live product as locked and an
+  unbuilt one as available. `appswitcher-open`'s baseline was re-approved by Jamal
+  for the corrected rows. Specimen and baselines only -- nothing in `dist` changed,
+  and the product list a consumer passes is Identity's, never this package's.
+
+## 0.3.0 — 2026-09-23
+
+### Fixed — a translated wallet name no longer paints under the Top up button (B33-913)
+
+B33-849 made `WalletChip`'s header name consumer-supplied. B33-881 then guarded
+it with `min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space:
+nowrap`, which stopped a multi-word name wrapping and reflowing the chip — and
+did **not** stop the overlap that ticket was named for. Those declarations cap
+the name to the chip's content box, and `.topUp` is absolutely positioned
+*inside* that same box, reserving no width of its own. Measured at the sidebar's
+240px chip: the header runs 210px wide, the button's left edge sits 170.4px into
+it. Everything in that last 39.6px was still painted over.
+
+So a French chip shipped a visible defect. `Solde du portefeuille électronique`
+ran 23.2px underneath the button with no ellipsis to warn anyone, and a name long
+enough to truncate put the ellipsis itself under it — and because the button is
+`opacity: 0` until hover or focus, the collision appeared exactly when someone
+reached for the chip.
+
+The header now gives up that strip. A new token, `--spacing-topup-reserve`
+(68px), is set as `padding-right` on the chip header in the states where the
+button floats over it, so the name re-clamps to the narrower row and B33-881's
+ellipsis fires where it always should have. 68px is the French `Recharger`
+(59.9px, wider than the English `Top up` at 39.6px) plus `--spacing-2` of
+clearance, and deliberately no more: it leaves the name 142px, which still holds
+`Portefeuille électronique` whole.
+
+**Nothing renders differently for a consumer on the English defaults.** `Wallet`
+is 35.4px and was never near the strip; the five wallet screenshot baselines come
+back bit-identical, to the pixel, with and without this change. The rendering
+that changes is the one that was already wrong.
+
+**Two things worth knowing if you translate the chip.** A `labels.name` longer
+than 142px at 12px now truncates with an ellipsis instead of running under the
+button — that is the fix, but it is a visible difference from what 0.2.0 drew.
+And the reserve is a fixed strip, so a `labels.topUp` wider than 60px (a phrase
+such as `Créditer le compte`, 107px, rather than a word) overruns it again. The
+only fix that holds for any label is putting the button in normal flow, which
+restructures a view approved at the fidelity gate and is a human's call.
+
+`--spacing-topup-reserve` ships in `style.css` like every other token, so a
+consumer can read it, and `dist/` is otherwise unchanged: no new exports, no prop
+changes, no markup changes.
+
+*Not in the published package:* `scripts/wallet-name-overflow-check.mts` and
+`scripts/name-clearance.ts`, a browser check (`npm run
+wallet-name-overflow-check`) that renders the chip with five translated names
+against two top-up labels in three states and fails if any name's painted box
+intersects the button's. It fails on 8 of those 30 renderings with this fix
+backed out, which is the thing the test it replaces could not do — that one read
+the stylesheet as text and stayed green throughout (B33-914).
+
+### Added — `AppSwitcher`, the switcher that actually switches (B33-479)
+
+A new component, and seven new names on the published surface: `AppSwitcher` and
+`defaultAppSwitcherLabels`, plus the types `AppSwitcherProps`,
+`AppSwitcherProduct`, `AppSwitcherHub`, `AppSwitcherAccount` and
+`AppSwitcherLabels`. **Purely additive.** No existing export changed and no
+signature moved; `AppShellProps.switcher` was already a `ReactNode` slot in
+`0.2.0`, so this drops into a shell a product is already rendering:
+
+```tsx
+<AppShell
+  switcher={
+    <AppSwitcher
+      products={products}
+      currentSlug="outbound"
+      hub={{ name: 'Hub', description: 'All Boost33 products', href: '/hub' }}
+      account={{ name: 'Acme Coaching', initials: 'AC', description: 'Admin · 2 workspaces', onSelect: openWorkspaces }}
+    />
+  }
+  {...rest}
+/>
+```
+
+**It fetches nothing.** `products` is the list Identity serves and the consuming
+app passes down; this package hardcodes no product list (CLAUDE.md). Every
+product renders whether or not the account holds it — `entitled: false` dims the
+mark and adds a "Not on plan" tag, and the row stays an ordinary focusable link,
+because not entitled is not disabled (ADR-0010) and hiding an unowned product is
+how nobody learns the family exists.
+
+**A disclosure, not a menu.** The panel carries no widget role, the rows are the
+links and buttons they already are, and Tab is the document's own tab order — so
+tabbing through the products does not close the panel on the first row.
+Dismissal, focus restoration and trigger ARIA come from the shared
+anchored-overlay contract (ADR-0009), and it never becomes a modal.
+
+**It is a client module.** `AppSwitcher` ships with `"use client"`, as
+`WalletChip` does (ADR-0004) — it holds open/closed state. `AppShell` takes it
+through a slot rather than importing it, so a shell rendered without a switcher
+still ships no client bundle for one.
+
+**Two things also arrive through `./style.css`**: the switcher's own rules, and
+one new published token, `--spacing-2_25: 9px` — the trigger's block padding,
+from the spec's 9 September recapture. No existing token value changed.
+
+`labels` carries the two strings that are not row data: `panel`, the panel's
+accessible name (default "Boost33 products"), and `notOnPlan` (default "Not on
+plan"). Pass it and you supply both — the prop is typed `AppSwitcherLabels`, not
+`Partial<AppSwitcherLabels>`, and a supplied object replaces the defaults rather
+than merging onto them. Product names, the hub's name and blurb and the account
+row's lines are not labels; they are Identity's data, passed per row.
+
+> One residual, recorded rather than hidden. On the 56px rail the trigger's mark
+> sits 8px lower than the fidelity baseline puts it: `.railTrigger` carries
+> `--spacing-2` of block padding, and dropping that to match the baseline leaves a
+> 20px-tall button, under WCAG 2.5.8's 24px target. The spec settles the expanded
+> trigger and says nothing about the rail one, so the trade is a decision for a
+> human rather than a measurement to re-derive.
+
+### Fixed — a long wallet name truncates instead of reflowing the chip (B33-881)
+
+`WalletChip`'s `.name` now truncates on one line rather than wrapping, through
+`min-width: 0`, `overflow: hidden`, `text-overflow: ellipsis` and
+`white-space: nowrap` — the idiom `NavItem` already uses. It is four
+declarations in `WalletChip.module.css`, and they reach every consumer through
+the compiled `./style.css` on the version bump. No prop changed and no markup
+moved.
+
+B33-849 made the name consumer-supplied, which dropped its guarantee of being a
+short English word. Unguarded, a longer name wrapped and pushed the chip off its
+approved 63px content box; and because the top-up button is absolutely positioned
+over the header's right strip and revealed on hover or focus, a long name painted
+underneath that button the moment someone hovered the chip. French runs 15–25%
+longer than English, so the first two consumers are precisely where this trips.
+
+**A consumer that passes no `labels` sees nothing change** — the default is
+"Wallet", never long enough to overflow, and the wallet baselines do not move.
+**Check your app if** it passes a long or multi-word `labels.name` and expected a
+second line: it now ellipses.
+
+The screenshot gate is blind here, because the specimen renders the English
+defaults (B33-878). The guard is asserted against the stylesheet source in
+`tests/wallet-name-overflow.test.ts` instead — the same file-as-text seam the
+token guards read at.
+### Added — an optional Tailwind v4 entry point, `@boost33/ui/theme.css` (B33-871)
+
+A Tailwind v4 consumer can now take this package's tokens as Tailwind theme
+names, holding **no token names and no token values of its own**:
+
+```css
+@import "tailwindcss";
+@import "@boost33/ui/style.css";
+@import "@boost33/ui/theme.css";
+```
+
+`bg-orange-500`, `rounded-xl`, `text-sm`, `w-sidebar`, `text-foreground-muted`
+and the rest now mean this package's values in that app, and keep meaning them
+across a version bump. Delete the `@theme` block you were maintaining; keep only
+your own additions, as aliases (`--color-chart-1: var(--color-orange-500)`).
+
+**This is additive and entirely optional. If you do not import it, nothing
+changes for you** — `dist/style.css` is byte-for-byte what it was, and a
+consumer with no Tailwind, or on Tailwind v3, is unaffected. No Tailwind
+dependency or peer dependency is added to the package.
+
+It is the same token set as `style.css`, not a second one: both files are
+generated from the same Paper dump by the same run, and a test fails the build
+if they ever disagree. Two notes worth knowing:
+
+- Motion and elevation (`--duration-fast`, `--easing-standard`,
+  `--shadow-overlay`) are **not** in it — they are hand-maintained rather than
+  generated. They still arrive on `:root` via `style.css`; what you do not get
+  is a `shadow-overlay` utility. Write `shadow-[var(--shadow-overlay)]`.
+- The font hooks work exactly as before. Keep declaring
+  `--boost33-font-sans` and friends; this package still only ever reads them.
+
+See `docs/adr/0012-an-optional-generated-tailwind-theme-entry-point.md`, which
+amends ADR-0002.
+
+### Fixed — the shell now renders under the Next.js App Router (B33-846)
+
+The published package shipped no `"use client"` directive, so a Next App Router
+consumer that rendered `AppShell` from a server component — the ordinary way, and
+the way Score does it — failed the build the moment the shell's tree reached an
+interactive component. It reached one immediately: `AppShell` renders `Sidebar`,
+which ran an effect.
+
+`WalletChip` and the sidebar's dev-mode nav-budget warning are now client
+modules; the rest of the shell (`AppShell`, `TopBar`, `PageHeader`, `NavSection`,
+`NavItem`, `Sidebar`, `Wordmark`) stays a Server Component, so a consumer ships
+no client bundle for the shell's static half. **Nothing renders differently** —
+same props, same markup, same behaviour, screenshot baselines unchanged.
+
+The public surface is unchanged: `import { AppShell } from '@boost33/ui'` and
+`'@boost33/ui/style.css'` resolve exactly as before. Internally `dist/` is now
+many files rather than one so the directive can sit on the two modules that need
+it and no others — see ADR-0004. A consumer that only imports through the package
+name (as the `exports` map requires) sees no difference beyond the shell finally
+rendering.
+
+### Added — a consumer's own link element for the nav, so a Next.js app stops full-page-reloading (B33-847)
+
+`NavItem` rendered its linked form as a literal `<a href>`, and `AppShell`
+threaded a row's `href` straight to it. In a Next.js App Router consumer that is
+a full document navigation on every sidebar click: the React tree is thrown away
+and rebuilt, in an app whose whole routing model exists to avoid exactly that.
+And the locale prefix goes with it, because the localised `Link` that writes the
+prefix into the path — next-intl's — never sees the click. For a consumer whose
+default locale is not English, and the first two are French-default, a bare
+`href` either 404s or drops the reader into the wrong language.
+
+**A new optional prop, `linkComponent?: ElementType`, on both `NavItemProps` and
+`AppShellProps`.** On `NavItem` it is the element the linked form renders
+through in place of the literal `<a>`, receiving `href`, `className`, `onClick`
+and the row's `data-*`/`aria-*` attributes unchanged — so a consumer's `Link`
+gets exactly what the anchor got, and the rendered markup is identical. On
+`AppShell` it is set once and threaded to every `NavItem` the shell composes out
+of `nav`, because which element draws a row is the consumer's one routing
+choice, not a per-row datum: `AppShellNavItem` still carries only the `href`.
+
+A Next.js consumer passes its own link once, on the shell:
+
+```tsx
+import Link from 'next/link'   // or next-intl's localised Link, for the prefix
+
+<AppShell product="Score" nav={nav} topBar={topBar} linkComponent={Link}>
+  {children}
+</AppShell>
+```
+
+**Unset, the row renders a plain `<a>`, exactly as before.** The prop is
+additive and opt-in — no existing signature moved, and the default DOM is
+byte-identical, which is why the behaviour tests and the fidelity baselines
+stayed green unmodified. **Nothing breaks by taking this version.** The flip
+side is the reason this entry matters: **a consumer that passes nothing keeps
+the full page reload.** If your app owns a router, this is the version to wire
+it into.
+
+**The prop is consulted only for the linked form.** A `NavItem` with no `href`
+is an action and stays a `<button>`; `linkComponent` on such a row is ignored
+rather than rendered.
+
+**Type safety stops at the boundary, deliberately.** `ElementType` does not
+check that what you pass accepts an `href`, so a component that ignores one
+typechecks and renders a row that goes nowhere. The prop is documented as
+receiving what the anchor received; enforcing that in the type was judged not
+worth the machinery.
+
+The name and the shape are settled for every link-bearing component this package
+grows, in
+`docs/adr/0011-a-linkcomponent-prop-is-how-a-component-takes-a-consumers-link.md`
+— not `as`, not `linkAs`, not a render prop. `AppSwitcher`, new in this release,
+already takes the same prop for its product and hub rows (B33-479).
+
+### Added — `WalletChip` takes its user-facing strings as props (B33-849, B33-873, B33-875, B33-877)
+
+Four tickets built this API and not one of them has shipped: B33-849 added it,
+and B33-873, B33-875 and B33-877 corrected it before any consumer saw it. It is
+described here once, as the surface a consumer actually takes on the next bump,
+rather than as one entry plus three corrections to something nobody has.
+
+`WalletChip` was the only component in the package that rendered words, and every
+one of them was an English literal. The first two consumers run next-intl with
+French as the default locale, so the chip rendered "Wallet", "Top up" and
+"Granted expires …" in English no matter what the app around it spoke.
+
+Every string is now a field on a new optional `labels` prop, typed
+`Partial<WalletChipLabels>`, each with an English default:
+
+| field | default |
+| --- | --- |
+| `region` | `Wallet balance` (the chip's accessible name) |
+| `name` | `Wallet` |
+| `unit` | `tokens` |
+| `balanceUnknown` | `Balance unknown` (screen-reader only) |
+| `granted` / `purchased` | `Granted` / `Purchased` |
+| `grantExpiry` | `Granted expires {date} · burns first` |
+| `topUp` | `Top up` |
+| `railBalance` | `Wallet balance {balance}` |
+| `railBalanceUnknown` | `Wallet balance unknown` |
+| `railUnknown` | `unknown` (screen-reader only) |
+| `bar` | `{granted} granted and {purchased} purchased of {remaining} remaining` |
+
+**A consumer that passes nothing renders exactly what it rendered before** — the
+defaults are today's strings, so the wallet baselines do not move. Pass a
+`labels` object to translate, overriding only the fields you need:
+
+```tsx
+<WalletChip granted={3400} purchased={1200} grantCycle={3400} labels={{ name: 'Portefeuille', topUp: 'Recharger' }} />
+```
+
+`WalletChipLabels` and the `defaultWalletChipLabels` object are exported, so a
+consumer can build on the English set rather than re-type all twelve. **Build on
+it by spreading it** — the object is frozen (B33-877), and writing into it throws:
+
+```tsx
+const fr = { ...defaultWalletChipLabels, name: 'Portefeuille' }   // correct
+const mine = defaultWalletChipLabels; mine.name = 'Portefeuille'  // TypeError
+Object.assign(defaultWalletChipLabels, { name: 'Portefeuille' })  // TypeError
+```
+
+**No shipped consumer breaks.** The export and the freeze reach npm in the same
+version, so there is no published build of this package in which writing to the
+defaults ever worked. What changed is that an idiom which *would* have worked —
+and would have renamed the header of every chip in the process, silently, because
+the object is a process-wide singleton — is now a thrown `TypeError` at the first
+write.
+
+It throws rather than failing quietly because this package is ESM-only and a
+module is strict-mode code. **Nothing in the types warns you**: the export is
+declared `WalletChipLabels`, not `Readonly<WalletChipLabels>`, so `tsc` accepts
+the assignment and the error arrives at runtime. That is the whole reason it is
+written down here rather than left to the typecheck.
+
+**A label supplied as `undefined` falls back to English (B33-873).** A next-intl
+`t('...')` returns `undefined` on a missed key, so one missing translation out of
+twelve reaches the chip as `labels={{ name: undefined }}` — explicit,
+indistinguishable at the call site from an unsupplied field, and typechecking
+cleanly, because `Partial<T>` without `exactOptionalPropertyTypes` accepts an
+explicit `undefined`. The merge is now per field and drops `undefined` entries
+before applying them, so that one key falls back to its English default. A plain
+object spread copied the `undefined` across, which blanked the chip header,
+shipped an unnamed top-up button, or crashed the render outright on a function
+label such as `bar` or `grantExpiry`.
+
+**The bar's accessible label is now supplied whole**, as one template around the
+three figures, rather than concatenated from fragments. Word order is not a
+property of English, and the old `"{n} granted and {n} purchased of {n}
+remaining"` could not be translated at all — a French consumer needs to put the
+numbers where French puts them. The three labels that carry a value —
+`grantExpiry`, `railBalance` and `bar` — name each value's position with a
+`{placeholder}`; see B33-880 below, which is also why they are strings rather
+than the functions this change originally shipped on `main`.
+
+**Your `bar` is called only where a bar renders (B33-875).** The unknown state
+draws no bar — it is the degraded render, the one that exists because fetching
+the balance already failed — but the label was assembled above every branch, so a
+consumer's `bar` ran on `0, 0, 0` figures there too. It is now built lazily and
+invoked at the two sites that actually render a bar, so a `bar` that divides by
+the total or does an `Intl` lookup no longer has a chance to throw on the one
+render the chip most needs to survive. Nothing changes for a consumer on the
+default, which is a template string that cannot fail.
+
+**No i18n dependency.** next-intl is not, and must not become, a peer dependency;
+the chip renders what it is given (CLAUDE.md). A new guard,
+`tests/no-hardcoded-strings.test.ts`, fails if a component grows a user-facing
+*phrase* — two words or more — or a string literal reaching an accessible-name
+attribute. It is the sibling of Score's gate of the same name.
+
+It does not catch a single word routed through a variable (`const cta =
+'Upgrade'` rendered as `<button>{cta}</button>`); the guard's own comment says
+so, and this line said otherwise until B33-874 corrected both.
+
+### Fixed — `WalletChip` labels now cross the Server Component boundary (B33-880)
+
+The two entries above are individually fine and together broke the documented
+way to translate the chip. B33-849 gave `labels` three **function**-valued
+fields; B33-846 made `WalletChip` a real client module. A function cannot be a
+prop of a Client Component rendered from a React Server Component, so the
+sentence this package told consumers to write —
+
+```tsx
+<WalletChip {...balance} labels={{ ...defaultWalletChipLabels, name: 'Portefeuille' }} />
+```
+
+— threw out of React's Flight serializer:
+
+> Functions cannot be passed directly to Client Components unless you explicitly
+> expose it by marking it with `"use server"`.
+
+Three things made that worse than it sounds. Nesting the function inside an
+object does not help: the serializer walks the whole prop graph. It is not
+`__DEV__`-gated, so it throws in production. And `AppShell.wallet` is a
+`ReactNode` slot, so it is the **consumer's own page** — under the App Router, a
+Server Component by default — that constructs the element. The pattern that
+throws was the pattern the specimen demonstrated.
+
+**The three fields now take a `{placeholder}` template as well as a function,
+and the English defaults are templates:**
+
+| field | default | placeholders |
+| --- | --- | --- |
+| `grantExpiry` | `Granted expires {date} · burns first` | `{date}` |
+| `railBalance` | `Wallet balance {balance}` | `{balance}` |
+| `bar` | `{granted} granted and {purchased} purchased of {remaining} remaining` | `{granted}`, `{purchased}`, `{remaining}` |
+
+A template is a plain string, so `labels` is data all the way down and survives
+the boundary intact. Word order stays the consumer's — that was the point of
+supplying these whole rather than as fragments, and a placeholder goes wherever
+the locale puts the figure:
+
+```tsx
+labels={{ bar: '{remaining} restants : {granted} et {purchased}' }}
+```
+
+A name the label does not define is left exactly as written, so a misspelled
+placeholder appears in the rendering instead of silently blanking, and copy that
+genuinely contains braces is not mangled. A template that names no placeholder
+renders as written: a locale that does not need the figure need not name it.
+
+**Nothing renders differently.** The templates produce character-for-character
+what the functions produced, a consumer that passes no `labels` is untouched, and
+the five `walletchip-*` baselines do not move.
+
+**The function form still works**, and is still the right shape when the sentence
+needs logic a template cannot express — ICU plurals, an `Intl.ListFormat` call.
+It is only ever reachable from a Client Component, which is where a consumer
+holding a function already is. Passing a mix of templates and functions in one
+object is fine.
+
+**One shape did change, and it reaches nobody published.** Reading a default
+*as a function* — `defaultWalletChipLabels.bar('3,400', '1,200', '4,600')` — is
+now a call on a string. The function-valued defaults have never been published:
+0.2.0 predates B33-849 and both changes are still unreleased above. The only
+code that could be affected is something written against `main` in the last few
+days, and the fix is to interpolate the template or keep a function of your own.
+
+`tests/wallet-labels-serializable.test.tsx` pins the property directly: the
+defaults survive `structuredClone` and a JSON round-trip with every field intact,
+no default is a function, and a function *is* still rejected by the clone, so the
+check cannot go quietly vacuous. jsdom has no RSC boundary — this is the nearest
+honest stand-in for one, and the reason the original bug was invisible to
+`typecheck`, to the behaviour tests and to the screenshot gate alike.
+
+### Fixed — `WalletChip` formats its numbers for a `locale` (B33-876)
+
+B33-849 made every *word* the chip renders a prop. Its **numbers** stayed
+English, and no prop could reach them. `format.ts` hardcoded
+`toLocaleString('en-US')` and a literal `k`, so a French-default consumer — and
+the first two consumers are French-default — read `4,600` where French writes
+`4 600`, and `4.6k` on the rail where French writes `4,6 k`. Those are the
+largest glyphs on the chip. The design also foreclosed the workaround: the label
+templates and functions receive the figures **already formatted**, by documented
+intent, so a consumer could translate "tokens" to "jetons" and still had no hook
+at all for the number in front of it.
+
+**`WalletChip` now takes an optional `locale`** — one BCP-47 language tag,
+defaulting to `en-US`, driving `Intl.NumberFormat`:
+
+```tsx
+<WalletChip granted={3400} purchased={1200} grantCycle={3400} locale="fr-FR" />
+```
+
+| what it renders | `en-US` (the default) | `fr-FR` |
+| --- | --- | --- |
+| the balance | `4,600` | `4 600` |
+| each side of the split | `3,400` / `1,200` | `3 400` / `1 200` |
+| the rail, abbreviated | `4.6k` | `4,6 k` |
+| the `bar` accessible name | `3,400 granted and 1,200 purchased of 4,600 remaining` | the same figures, French-grouped |
+
+French groups with a narrow no-break space (U+202F), not an ordinary space —
+worth knowing if you are writing an assertion against it.
+
+**It reaches the accessible names, not only the visible text.** The same
+formatted strings are interpolated into `bar` and `railBalance`, which the
+screenshot gate cannot see. A fix that stopped at the visible figures would have
+left a screen-reader user in a French app hearing en-US separators.
+
+**Why a locale tag, and not consumer-supplied formatters.** Both shapes were on
+the table. A `formatTokens` / `abbreviateThousands` prop pair is a **function**,
+and a function cannot cross the React Server Component boundary — which is the
+entire subject of the entry above. `AppShell.wallet` is a `ReactNode` slot, so a
+consumer's own page constructs the element, and under the App Router that page is
+a Server Component by default. Shipping injected formatters would have
+reintroduced B33-880 the same week it was fixed, and reintroduced it as the
+recommended path. A language tag is a plain string.
+
+The second reason is that numbers are not words. `labels` takes whole sentences
+because word order is a property of the consumer's language and no library can
+know it. Grouping and the decimal separator are the opposite: CLDR facts the
+platform already ships for every locale. Asking four products to each
+re-implement French grouping is asking four products to each get it slightly
+wrong. So "`labels` is already the injected shape, be consistent" reverses once
+you read *why* `labels` took that shape. The reasoning is written out at the top
+of `src/components/WalletChip/format.ts`, so reversing it is cheap.
+
+**One new label, `railFigure`, for the `k`.** The mark after the rail's
+abbreviated balance is a word rather than a number — English "k", German "Tsd.",
+and French puts a space in front of it that English does not — so it joins the
+chip's other words:
+
+| field | default | placeholder |
+| --- | --- | --- |
+| `railFigure` | `{figure}k` | `{figure}` |
+
+It takes a `{placeholder}` template or a function, exactly like `grantExpiry`,
+`railBalance` and `bar`, and a template rather than a bare suffix because a
+locale is entitled to put the mark somewhere other than the end. A French
+consumer writes `railFigure: '{figure} k'` and gets `4,6 k`.
+
+`Intl`'s own `notation: 'compact'` cannot supply this, which is why the rail is
+not simply handed to it: it renders `en-US` as `4.6K`, a capital the baselines do
+not have, and German does not abbreviate four digits at all, so it renders
+`4600,0` — six characters and a decimal, in a 56px rail, longer than the number
+it was meant to shorten. One decimal thousand is this package's decision about a
+fixed width; the separator inside it is CLDR's, and that is the part `locale`
+fixes.
+
+**Nothing renders differently for a consumer that passes nothing.** `en-US` is
+the default, `Intl.NumberFormat('en-US')` is the same CLDR data
+`toLocaleString('en-US')` reached, and `railFigure` defaults to `{figure}k`. That
+is asserted rather than assumed — `tests/wallet-format.test.ts` compares the
+default path against `toLocaleString('en-US')` value by value, and
+`tests/wallet-chip.test.tsx` compares the rendered markup with and without an
+explicit `en-US`. The five `walletchip-*` baselines do not move.
+
+**The change is additive.** `locale` is optional, `railFigure` has a default,
+`WalletChipLabels` gains a field rather than changing one, and an explicitly
+`undefined` `railFigure` still falls back to English the way every other label
+does (B33-873). The one thing that changed shape is internal and reaches no
+consumer: `format.ts` now exports `thousandsFigure`, which returns the figure
+without the mark, in place of `abbreviateThousands`. Neither has ever been
+exported from `src/index.ts`.
+
+**A malformed tag degrades rather than throwing.** `Intl.NumberFormat` raises a
+`RangeError` on a structurally invalid tag (`'en_US'`), and this chip sits in the
+sidebar of every screen in four products: one consumer's typo in a config file
+must mis-space a number, not take the shell down. A tag the platform refuses
+falls back to `en-US` and warns the developer once — `console` only, never
+rendered. A well-formed tag the platform has no data for (`'zz-ZZ'`) is not an
+error and is left to the platform to resolve.
+
+### Changed — the three font tokens now read a consumer-supplied hook (B33-848)
+
+`--font-display`, `--font-sans` and `--font-mono` are now generated as a `var()`
+read of a property this package never declares. Three lines of `src/tokens.css`
+changed, and they are the only lines that changed:
+
+| token | was | now |
+| --- | --- | --- |
+| `--font-display` | `Outfit, ui-sans-serif, …` | `var(--boost33-font-display, Outfit), ui-sans-serif, …` |
+| `--font-sans` | `Inter, ui-sans-serif, …` | `var(--boost33-font-sans, Inter), ui-sans-serif, …` |
+| `--font-mono` | `'Geist Mono', ui-monospace, …` | `var(--boost33-font-mono, 'Geist Mono'), ui-monospace, …` |
+
+**No token value changed, and an app that does nothing renders exactly as it
+did.** The Paper family stays in place as the `var()` fallback, so all four
+products are unchanged until one of them opts in. Take this bump and set nothing
+and nothing moves.
+
+**What a consuming app gains** is the ability to name the face its own loader
+minted. `next/font` mints a hashed family name at build time — something of the
+shape `__Inter_e8ce0c` — and exposes it only through a generated variable, a
+string nothing in this package can predict. A Next.js app can now say so
+directly:
+
+```css
+:root {
+  --boost33-font-sans: var(--font-inter);
+}
+```
+
+and the shell renders in the same face as the rest of the app.
+
+**What this fixes.** The package declares its tokens on `:root`, and a consumer
+that declared `--font-sans` on `:root` too had no defined winner — same selector,
+same specificity, same origin, so the cascade's last tie-break is document order
+and whichever stylesheet the bundler emitted last silently won. Nothing anywhere
+reported it: no build warning, no type error, no failing test. A lost race meant
+every screen in the app rendering in a different typeface with nothing failing.
+The package now reads a name it never declares, so the two stylesheets share no
+property name and load order has nothing left to decide.
+
+**The rule this sits under:** the package's token values are authoritative, and a
+consumer may alias a package token but may never redefine one — font family is
+the single carve-out, and it is a hook rather than an override for exactly that
+reason (ADR-0011).
+
+**Check your app if** it declares any `--color-*`, `--text-*`, `--spacing-*`,
+`--radius-*` or `--container-*` custom property on `:root` alongside this
+package. Those names still collide, and a collision is now a conflict to resolve
+rather than a race to win: where the two disagree the package's value is the
+correct one and yours moves. Two values are known to be wrong in the wild —
+`--color-neutral-600` must be `#6B6B6B` (the pre-fix `#737373` fails WCAG AA for
+muted text under 18.66px, ADR-0007) and `--color-orange-400` must be `#EB7147`.
+Live Paper was read on 2026-09-21 and holds both. Note that a textual diff of two
+token files under-reports this: `--color-foreground-muted` reads
+`var(--color-neutral-600)` on both sides and differs only in the paint
+underneath.
+
+> Two limits, recorded rather than hidden. A `--boost33-font-*` hook pointed at a
+> variable the app has not itself defined makes the whole declaration invalid at
+> computed-value time, and the face falls back to the Paper name rather than the
+> app's — the hook moves that hazard into the consumer, where the font loader is
+> visible, but it does not remove it. And the screenshot gate cannot see a wrong
+> typeface at all, so this is guarded by the browser load-order check and the
+> token guards, not by a baseline.
+
+### Changed — the nav height budget now agrees with what the nav renders (B33-752)
+
+`nav-height-budget` exists so a product can assert its nav fits *before*
+rendering it. Measured against a real render it was wrong in the one direction
+that matters: it under-counted the content and over-counted the column, and the
+two errors compounded toward a false "fits". A false "does not fit" costs someone
+a look; a false "fits" is how Boost Outbound's admin role pushed the wallet chip
+below the fold, which is the incident the module was written for.
+
+**Four exported constants changed value.** No export was removed and no signature
+changed, so nothing here fails a typecheck — which is exactly why it is written
+down.
+
+| export | was | now |
+| --- | --- | --- |
+| `NAV_HEIGHT_BUDGET_PX` | `700` (a literal) | `629` (derived: `navBudgetForViewport(900)`) |
+| `NAV_ITEM_PX` | `32` | `33` |
+| `NAV_SECTION_HEADER_PX` | `40` | `30` |
+| `NAV_SHELL_FIXED_PX` | `198` | `271` |
+
+**`navContentHeight()` returns a different number for every input.** Its
+signature is unchanged. It now returns the nav's whole box — rows, the 16px gaps
+the nav sets between sections, and its 8px scroll gutter — rather than the sum of
+row heights alone. It is the nav's rendered `scrollHeight`, which is what it
+always claimed to be.
+
+**Two constants are new**, both previously folded into the numbers above:
+`NAV_SECTION_GAP_PX` (`16`) and `NAV_FOCUS_GUTTER_PX` (`8`).
+
+#### What this changes for a consuming product
+
+Fewer nav items fit than the old model claimed. At the 900px reference viewport:
+
+| nav shape | fitted before | fits now |
+| --- | --- | --- |
+| one flat section, no header | 21 items | **18** |
+| two sections, one headed (the Wallet's shape) | 20 items | **17** |
+| four sections, three headed | 18 items | **14** |
+
+Nothing renders differently — no component, CSS or token changed in this work.
+The shell behaved this way already; only the prediction was wrong.
+
+**Check your app if** it imports any of the four constants and does its own
+arithmetic with them, or asserts on `navContentHeight()` in its own tests. A test
+pinned to the old numbers (`navContentHeight(shape) <= 700`) will now get a
+different answer. If you only call `checkNavHeightBudget()` and read `fits`, you
+need do nothing — you will simply get a truthful answer where you previously
+might not have.
+
+The model is now reconciled against a real browser render in CI, so the two
+cannot drift apart again silently.
+
+> Two known limits, both recorded rather than hidden. `NAV_SHELL_FIXED_PX` is
+> measured from the specimen's stress stage, whose footer is 12px taller than the
+> Wallet's, so the budget under-states by that much at the Wallet reference —
+> B33-762, and the safe direction. And the row costs include a line box that
+> comes from Inter's own metrics, so an app that renders the shell without Inter
+> loaded will drift from the model — B33-765.
+
+### Added — the nav height budget says what it is a model of, and lets you override it (B33-762)
+
+The two "known limits" recorded at the end of the B33-752 entry above turned out
+to be three, and all three were the same defect: **the model never said what it
+was a model of.** It did not say whose shell's furniture it had measured, which
+nav state its per-row costs described, or whose font metrics those costs came
+from. A consuming product importing the constants could not see any of it.
+
+**No exported constant changed value.** `NAV_SHELL_FIXED_PX` is still `271`,
+`NAV_HEIGHT_BUDGET_PX` still `629`, `NAV_ITEM_PX` still `33`,
+`NAV_SECTION_HEADER_PX` still `30`. Nothing renders differently — no component,
+CSS or token was touched, and every screenshot baseline still matches. If you
+take this version and change nothing, you get the same numbers you had.
+
+What is new is that the three assumptions are now named next to the constants
+that carry them, and two of them can be replaced by a caller who knows better.
+
+**Two constants are new**, both a decomposition of `NAV_SHELL_FIXED_PX` rather
+than a new measurement:
+
+| export | value | what it is |
+| --- | --- | --- |
+| `NAV_SHELL_PACKAGE_FIXED_PX` | `185` | the furniture this package draws — the wordmark block, the switcher wrapper's padding, `.foot`'s padding and gap, the expanded `WalletChip`, less the nav's negative gutter margin |
+| `NAV_SHELL_CONSUMER_SLOTS_PX` | `86` | an **allowance** for the slots this package does not own — a 42px switcher and a 44px sidebar footer, as the specimen's stress route fills them |
+
+`NAV_SHELL_FIXED_PX` is now defined as the sum of the two. The 185 is identical
+on both shell routes in the specimen, which is what makes it a number this
+package can defend; the rest is one consumer's markup and was being published as
+though it were ours.
+
+**`navBudgetForViewport()` takes an optional second argument**, your own slot
+total. `navBudgetForViewport(900)` is unchanged.
+
+```ts
+// Your footer is a 64px two-line block, not the 44px avatar row we assumed.
+const budget = navBudgetForViewport(900, switcherPx + 64)
+```
+
+**`navContentHeight()` takes an optional second argument**, per-row costs
+measured in your own font. `navContentHeight(sections)` is unchanged.
+
+```ts
+// Measured from a rendered row's offsetHeight in your app, not estimated.
+const used = navContentHeight(sections, { itemPx: 35, sectionHeaderPx: 32 })
+```
+
+`NavRowCosts` is exported for that object.
+
+#### The three assumptions, now written down
+
+**1. The column is the stress specimen's, and part of it is not ours.** The
+default stays pinned there rather than moving 12px toward the Wallet's shorter
+footer, because that move is 12px *toward* a false "fits" on the strength of one
+consumer's markup. A consumer with a taller footer than either route was, and
+still is, over-budgeted — but can now say so.
+
+**2. The per-row costs describe the expanded nav; the rail is out of scope.** A
+rail row is 32px, not 33 (the label goes out of flow), and a collapsed section
+renders no header element at all, so a `hasHeader: true` costs 30px the rail
+never draws. That is not modelled, deliberately: on the specimen's 13-item shape
+the rail renders 472px of content into a 587px column where the same data
+expanded renders 575px into 549px, so the expanded model over-counts a rail nav
+by 103px and under-counts its column by 38px — 141px of slack, both errors
+toward safety. Adding a `NAV_RAIL_ITEM_PX` and a `collapsed` flag on
+`NavSectionShape` would be a public API change to describe a state that cannot
+overflow. The browser check now drives the rail stage and asserts the bound, so
+it fails CI if that ever stops being true.
+
+**3. The line box belongs to your font, not to this package.** `NavItem` and
+`NavSection` set no `line-height`; the computed value is `normal`, so half of
+each row cost is token-derived padding and the rest is whatever line box your
+face draws. This package ships no font. Measured on the specimen by swapping
+`--font-sans`: Inter 33/30, system-ui 33/29, Helvetica 32/29, Arial and Georgia
+32/28 — every face shorter than Inter, so the model over-counts, the safe
+direction.
+
+> [!warning] One measurement is still outstanding, and it is the unsafe
+> direction.
+> `Segoe UI` is in the fallback stack and is reported to carry a ~1.33 `normal`
+> line-height factor, which at 14px would give a ~35px row — an **under**-count,
+> the one direction this module must never err in. It is not recorded above
+> because it could not be taken: this work ran on macOS, where Segoe UI is not
+> installed and a request for it silently resolves to the fallback. Nothing has
+> been tuned to a guessed number. **A Windows consumer on the fallback stack is
+> outside the model's stated scope** (a `normal` line box of 17px or less at
+> 14px) and is protected only by `Sidebar`'s development-mode warning, which
+> measures the real DOM and is correct whatever the font does. Pass measured
+> costs to `navContentHeight()` if this is you.
+
+Fixing it properly means setting an explicit `line-height` from the `--leading-*`
+tokens, the way `PageHeader` already does. That is not done here because
+`--leading-tight` at `--text-2xs` gives a 29px section header against today's 30,
+which moves three sets of screenshot baselines by a pixel — a design change that
+needs a human at the fidelity gate, not an agent making the diff green.
+
+**Check your app if** you import `NAV_SHELL_FIXED_PX` and do your own arithmetic
+with it, and your sidebar's switcher or footer is not roughly the specimen's
+42px and 44px. Nothing breaks; the answer was and remains approximate for you,
+and there is now a parameter that makes it exact.
+
+### Changed — the page header is 18px shorter in every state (B33-768)
+
+`PageHeader` was taking more vertical space than the screens wanted. It is now one line
+with no subtitle and two lines with one, and **18px shorter either way**:
+
+| state | was | now |
+| --- | --- | --- |
+| title only | 80.8px | **62.8px** |
+| title + subtitle | 105px | **87px** |
+| title + actions | 84px | **66px** |
+
+The saving is entirely padding — 28px/24px above and below became 18px/16px. The title
+is now semibold rather than bold and carries `-0.02em`; the subtitle keeps its size and
+its 4px gap. The metrics come from the Boost Outbound desktop screens, where every page
+header already renders this way.
+
+**Every screen in every consuming product moves up 18px.** Nothing else about the
+component changed — same props, same markup, same behaviour. A product that positions
+anything against the header's height, or screenshots its own pages, will see it.
+
+There is still no bottom border, and that is now a decision rather than an omission: it
+answers the question B33-477 left open.
+
+### Changed — a screen may now render without a page header (B33-750)
+
+`AppShellProps.pageHeader` is now optional (`pageHeader?: PageHeaderProps`). The
+frame still owns the page header and still renders it above the body; supplying
+one is what became optional. Omit it and the top bar's hairline sits directly on
+the body.
+
+Relaxing, not breaking: every existing call site that passes a `pageHeader` keeps
+working unchanged. It exists because the Wallet's overview screen renders no page
+header, and the shell could not previously reproduce that state at all.
+
+### Fixed — the `AppSwitcher` trigger is named even when the current slug is unknown (B33-919)
+
+`currentSlug` matching no row in `products` is a state this package supports on
+purpose: `AppSwitcherProduct.slug` is typed `string` rather than `ProductSlug` so
+an unrecognised slug degrades to a bare tile instead of failing, because Identity
+owns the product registry and can serve a product this package has no artwork for
+yet (ADR-0003). A fifth Identity product, or a `currentSlug` left stale by a
+rename, arrives there.
+
+The artwork degraded correctly. The accessible name degraded with it. The mark is
+`aria-hidden` unless it is handed a title, so on the rail — where the mark is the
+button's only content — **the trigger had no accessible name at all**. A screen
+reader reached the one control in the 56px collapsed shell and announced
+"button": no product, no purpose, nothing to act on, and no way to discover that
+this was the way back to a product it recognised. Expanded, the same path
+rendered an empty name between a blank tile and a chevron, so a sighted user saw
+the absence too.
+
+The trigger now falls back to a new label, **`switchProduct`**, defaulting to
+`Switch product`. It names the control rather than guessing at the product,
+because the product is exactly what this package does not know.
+
+**Nothing renders differently for a `currentSlug` that matches.** The fallback is
+reachable only when the lookup fails, the three `appswitcher-*` baselines were
+captured with the Wallet current, and they do not move.
+
+**`labels` now takes a `Partial<AppSwitcherLabels>`**, matching `WalletChip`.
+This is a relaxation, not a break: a consumer that wrote the object out in full
+keeps compiling, and one that supplies a subset now inherits English for the
+rest. Two things follow from it. Adding `switchProduct` to a required-field
+interface would otherwise have failed the typecheck of every app that had written
+all the fields out — an accessibility fix arriving as a compile error in four
+products on a patch bump. And a field supplied as `undefined`, which is what a
+missed next-intl key looks like at the call site, now keeps its English default
+instead of blanking the string — the same resolution `WalletChip` gained in
+B33-873.
+
+```tsx
+<AppSwitcher products={products} currentSlug={slug} hub={hub} account={account}
+  labels={{ switchProduct: 'Changer de produit' }} />
+```
+
+**Check your app if** it renders the switcher with a slug that may not be in the
+list it passes — the trigger now reads "Switch product" there rather than nothing,
+and if your app is not English it should pass a translation for it.
+
+### Internal — no consumer-visible change
+
+- A second specimen stage, `WalletShellSpecimen`, reproduces the Wallet's shell
+  at the baselines' own 1440×900 so the two `appshell-*` baselines finally have
+  something to be compared against (B33-750). Specimen only; it is not built into
+  `dist`. `@tabler/icons-react` was added as a **devDependency** for its glyphs —
+  icons stay a consumer's to pass, and the published package gains no dependency.
+- `useAnchoredOverlay` can now express "expanded, but not a menu": a trigger that
+  carries `aria-expanded` and `aria-controls` without claiming `aria-haspopup`,
+  which is what ADR-0010 asks three of the four overlays to be (B33-720). The
+  hook is still absent from `src/index.ts` and is not part of the public surface
+  — a consumer cannot import it by name. It is no longer absent from `dist`,
+  though: `AppSwitcher` imports it (B33-479), so from that ticket onward the
+  hook's code ships as the switcher's dependency. This corrects the claim this
+  bullet used to make, that "nothing reaches `dist` yet", which was true only
+  while nothing exported from `src/index.ts` used it.
+- `AppShell.module.css`'s `.content` comment no longer credits the page header
+  with a hairline it does not draw: the page header draws no border by decision
+  (B33-750), so the only rule in that column is the top bar's, and a guard in
+  `tests/guards.test.ts` now ties the comment to the borders actually declared
+  (B33-771). The net change under `src/` is a rewritten three-line CSS comment —
+  no declaration moved and nothing renders differently.
+- The three `appswitcher-*` fidelity baselines had been parked in
+  `SKIPPED_BASELINES` waiting for a component to compare against; B33-479 un-parks
+  them, so the screenshot gate now diffs 27 states rather than 24. No baseline was
+  regenerated.
+- The nav height budget is now checked against a real render in CI, in the
+  screenshot job, because jsdom has no layout engine and cannot see a
+  `scrollHeight` (B33-752, B33-760).
+- A static collision guard, `tests/token-cascade.test.ts` over
+  `scripts/token-cascade.mts`, asserts this package's sheets and a conforming
+  consumer token sheet declare no custom property name in common (B33-848).
+- A browser load-order check, `scripts/token-order-check.mts`, attaches both
+  sheets to a real page in both orders and asserts the resolved values match. It
+  runs in the `screenshot-diff` job as `npm run token-order-check`, because
+  jsdom never resolves `var()` and cannot observe the cascade (B33-848).
+- `WalletChipLocaleSpecimen` shows the chip in `fr-FR`, and renders **last** in
+  `specimen/main.tsx` on purpose (B33-876). The harness captures a full page and
+  clips to each state's box, so a route added above a gated state moves that
+  state down the page and Chromium re-rasterizes its text at a different
+  subpixel offset: putting these two examples inside `WalletChipSpecimen` took
+  `appswitcher-open` from 4.835% of pixels differing to 5.059%, through the 5%
+  threshold, in a component that change did not touch. Rendered after the last
+  gated state, they move nothing. The route is ungated by design — it carries no
+  `data-testid` and has no baseline, because capturing one is a human approving a
+  rendering.
+- The screenshot gate now asserts hairlines structurally, because it could not
+  see them at all: `--color-border` (`#E5E5EA`) on white scores 328.0 against
+  pixelmatch's 352.15 cutoff, so a 1px rule could be added to or removed from any
+  gated state and the pixel count did not move (B33-772). `scripts/border-proof.ts`
+  records the border edges each state draws and the harness reads the real ones
+  out of the DOM at capture time. Harness only — no component changed, no
+  baseline moved, and nothing in `dist/` is different. Named here rather than
+  omitted because it changes what a green screenshot job means: it is now a claim
+  about the package's hairlines, which it previously was not.
+- Baseline accounting now closes in both directions (B33-725). `SKIPPED_BASELINES`
+  accounts for every PNG on disk; a new `SPECIMEN_ONLY` list in
+  `scripts/screenshot-states.ts` accounts for every specimen section that
+  deliberately has no baseline, each with a written reason, and
+  `tests/specimen-coverage.test.tsx` fails if a section is in neither. Before
+  this, a row could be added to the specimen with no `data-testid`, shown to
+  every human who opens the page, and gated by nothing. Harness only — nothing
+  in `dist` changed.
+
+## 0.2.0 — 2026-09-17
+
+**The first version that is actually usable.** `0.1.0` exported `NavItem` and
+nothing else, so `npm install @boost33/ui` got you one nav row while ten
+components and the `AppShell` frame sat unpublished in the repo. This release
+ships them: `AppShell`, `Sidebar`, `TopBar`, `PageHeader`, `NavSection`,
+`NavItem`, `WalletChip`, `Wordmark`, `Boost33Mark` and `ProductMark`, plus the
+`nav-height-budget` helpers and the compiled `./style.css`.
+
+Also: `npm publish` could previously ship a stale `dist/`, or nothing at all, and
+neither was visible to whoever ran the command. `prepublishOnly` now re-runs
+typecheck, test and lint and rebuilds, and a guard fails if any of the four is
+dropped from it (B33-727).
+
+Held at `0.x` deliberately — see the note at the top of this file.
+
+## 0.1.0 — 2026-09-09
+
+First publish. `NavItem` only.