@cueplusplus/ui 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,705 @@
+# @cueplusplus/ui
+
+## 0.3.0
+
+### Minor Changes
+
+- 31e3607: Ship the linked RequestPort preset release across tokens, UI, and brand tokens.
+
+  The release adds the typed RequestPort preset and its generated dark, light, and
+  system selectors; system SSR, prepaint, provider, and portal behavior; the
+  `persistPreferences={false}` and authoritative prepaint options contracts; the
+  typed `fontFamilies` provider/portal override; the deterministic package
+  manifest and companion checksums; and the accessible `TableScrollRegion`.
+
+  All three linked tarballs receive the same minor version and changelog entry.
+  The Version Packages path regenerates the package manifest after applying those
+  versions and rejects stale or nondeterministic output before publication.
+
+### Patch Changes
+
+- Updated dependencies [31e3607]
+  - @cueplusplus/tokens@0.3.0
+
+## 0.2.0
+
+### Minor Changes
+
+- 33a95c4: Typeface is a third axis, beside theme and density.
+
+  `data-font` selects one of eight font pairings — a sans and a monospace — the
+  same way `data-theme` selects a palette and `data-density` selects a geometry.
+  `<ThemeProvider font>`, `useTheme().font` / `setFont`, persistence beside the
+  other two, the pre-paint script, and every portal root carry it.
+
+  ```tsx
+  <ThemeProvider theme="cue" density="normal" font="plex">
+    <App />
+  </ThemeProvider>
+  ```
+
+  | id       | sans                   | mono                | what your app has to do            |
+  | -------- | ---------------------- | ------------------- | ---------------------------------- |
+  | `system` | the platform's UI sans | **the theme's own** | nothing — this is the default      |
+  | `geist`  | Geist                  | JetBrains Mono      | deliver two faces                  |
+  | `inter`  | Inter                  | IBM Plex Mono       | deliver two faces                  |
+  | `plex`   | IBM Plex Sans          | IBM Plex Mono       | deliver two faces                  |
+  | `roboto` | Roboto                 | Roboto Mono         | deliver two faces                  |
+  | `source` | Source Sans 3          | Source Code Pro     | deliver two faces                  |
+  | `apple`  | SF Pro Text            | SF Mono             | nothing — and nothing you _may_ do |
+  | `office` | Calibri (Carlito)      | Cascadia Mono       | nothing — and nothing you _may_ do |
+
+  New exports from `@cueplusplus/tokens`: `FONTS`, `FontName`, `DEFAULT_FONT`,
+  `FONT_PAIRINGS`, `FONT_FACES`, `FontDelivery`, `FontPairing`, `faceProperty`.
+  `prepaintScript()` takes a fourth argument, the default pairing.
+
+  ## You have to load the fonts. We will not.
+
+  **This package ships no font file and no `@font-face`, and that is deliberate.**
+  A library that injected one would be choosing your network requests, your
+  content-security policy and your font licensing, in a stylesheet you imported
+  for its colours. What a pairing emits instead is a hook with the family name as
+  its fallback:
+
+  ```css
+  [data-font="inter"] {
+    --cue-font-sans: var(--cue-face-inter, Inter), ui-sans-serif, system-ui, …;
+    --cue-font-mono:
+      var(--cue-face-ibm-plex-mono, "IBM Plex Mono"), ui-monospace, …;
+  }
+  ```
+
+  Assign nothing and the stack still resolves — a local install first, then the
+  platform — so no pairing ever renders as nothing. Assign the property and
+  everything painted from the token follows. With `next/font`, the property name
+  _is_ the option:
+
+  ```tsx
+  const inter = Inter({ subsets: ["latin"], display: "swap", preload: false, variable: "--cue-face-inter" });
+  <html className={inter.variable}>
+  ```
+
+  `preload: false` matters: with preloading on, a site offering five webfont
+  pairings makes every visitor download all of them to render in one.
+  `FONT_PAIRINGS[name].faces` is the list of properties one pairing needs;
+  `FONT_FACES` is every face at once, as `property → family`.
+
+  **`apple` and `office` are stacks and must stay stacks.** SF Pro and SF Mono are
+  Apple-licensed and may not be served as webfonts; Calibri is Microsoft's and
+  ships with Windows and Office rather than with anybody's site (Carlito is its
+  metric-compatible libre twin, and is in the stack). They light up where
+  installed and fall through cleanly where they are not. Do not bundle them.
+
+  ## A theme's monospace still applies — until somebody picks a pairing
+
+  Seven presets name a monospace of their own, and seven pairings name one, so
+  one token was claimed twice.
+  Neither axis writes it now: a theme publishes `--cue-font-theme-mono`, a pairing
+  publishes `--cue-font-pairing-mono`, and `--cue-font-mono` resolves the two,
+  pairing first. **A chosen pairing wins**, at whatever element each was stamped
+  on — a pairing is what a person picked out of a menu and a preset's mono is what
+  its author chose in the absence of a person. The default pairing, `system`,
+  declines the question, so an app that never touches the axis keeps exactly the
+  monospace it has today.
+
+  ## Two things that change without you asking
+
+  **The base sans no longer names `Geist`.** It named a font this package has
+  never delivered, so for almost every visitor it resolved to the next entry
+  anyway. `--cue-font-sans` and `--cue-font-display` are now the platform stack;
+  Geist is the head of the `geist` pairing, which your app can actually deliver.
+  If you want it back, deliver it: `font="geist"` plus the two `--cue-face-*`
+  assignments.
+
+  **A generated theme's mono moves with it.** `createTheme({ fonts: { mono } })`
+  now writes `--cue-font-theme-mono`. Nothing to change unless you read the
+  generated `tokens` map by key.
+
+  ## Migrating
+
+  Nothing is required. Two things are worth doing:
+
+  1. **Pass the pairing to the pre-paint script**, as its fourth argument, if your
+     app's default is not `system`:
+     `prepaintScript(DEFAULT_STORAGE_KEY, "cue", "normal", "geist")`. A theme that
+     arrives one frame late is a flash of the wrong colour; a _family_ that
+     arrives one frame late reflows every line under the reader.
+  2. **If your own CSS overrides `--cue-font-mono`** under a `[data-theme]` block
+     of your own, move it to `--cue-font-theme-mono` — otherwise your override
+     beats the typeface picker and yours is the one theme it cannot move.
+
+  `font` is a root-level prop: there is no font island, and a nested provider
+  forwards the axis (and `setFont`) to the root. A specimen that genuinely wants
+  one face beside another needs nothing from this library but `data-font` on a
+  `<div>`.
+
+- 038837d: `AppShell`: the console frame, and the mobile navigation that goes with it.
+
+  Every console screen is the same five parts in the same arrangement — title bar,
+  navigation column, toolbar, one scrolling work area, status bar — and until now
+  each one arranged them by hand. `AppShell` is that arrangement, with the
+  arithmetic that actually holds it up: `h-dvh` rather than `min-h-dvh`, an
+  unbroken `min-h-0` chain from the frame down to the scroller, `min-w-0` on the
+  content column, and a scroller that is not the document, so the chrome stays put
+  with no `sticky` anywhere.
+
+  ```tsx
+  import {
+    AppShell,
+    Sidebar,
+    StatusBar,
+    TitleBar,
+    Toolbar,
+  } from "@cueplusplus/ui";
+
+  <AppShell.Root>
+    <TitleBar center="main-stage.cue">
+      <AppShell.NavTrigger />
+    </TitleBar>
+    <AppShell.Body>
+      <AppShell.Sidebar aria-label="Console" drawerTitle="Console">
+        <Sidebar.Section label="Show">
+          <Sidebar.Item icon={List} active>
+            Cues
+          </Sidebar.Item>
+        </Sidebar.Section>
+      </AppShell.Sidebar>
+      <AppShell.Content>
+        <Toolbar.Root aria-label="Playback">…</Toolbar.Root>
+        <AppShell.Scroller>…</AppShell.Scroller>
+      </AppShell.Content>
+      <AppShell.Aside aria-label="Inspector">…</AppShell.Aside>
+    </AppShell.Body>
+    <StatusBar>…</StatusBar>
+  </AppShell.Root>;
+  ```
+
+  Seven parts: `Root` (the frame), `Body` (the middle row), `Sidebar` (the
+  navigation), `NavTrigger` (the control that opens it on a phone), `Content` (the
+  `<main>` column — pass `main={false}` when the shell is embedded in a page that
+  already has one), `Scroller` (the only element that may scroll) and `Aside` (a
+  trailing column with a scroller of its own). `TitleBar` and `StatusBar` go in as
+  ordinary children: both are already `shrink-0`, so a wrapper would only repeat
+  that.
+
+  **`AppShell` is the one component in this library with a viewport breakpoint.**
+  `AppShell.Sidebar` renders the same children twice — as the 14rem column at
+  Tailwind's stock `md` (48rem) and up, and as a `Drawer` below it, opened by
+  `AppShell.NavTrigger` from the bar. It is a CSS-only dual render, both shapes in
+  the markup with one hidden per viewport: no `useMediaQuery`, nothing to measure,
+  and a first server-rendered frame that is already correct. The switch decides
+  navigation shape and nothing else; everything else in the library stays
+  intrinsically responsive, and a later component that wants a breakpoint is a new
+  decision rather than a precedent this one set.
+
+  `PageShell` and `Container` now offer the same four measures.
+
+  `narrow` (42rem) and `wide` (54rem) are unchanged. `broad` (84rem) is new on
+  both: the application measure, wide enough for a two-column documentation page
+  or a device frame. `full` is new on `PageShell`, which had no uncapped rung at
+  all while `Container` did. Nothing existing moves — `narrow` is still the
+  default on both.
+
+  ```tsx
+  <PageShell width="broad" title="Components">…</PageShell>
+  <PageShell width="full" title="Gallery">…</PageShell>
+  ```
+
+- 7eeb1c4: New component group, `brand`: the CUE++ marks, as components rather than files.
+
+  `CueMark` is the circular mark, `CueLogotype` is the wordmark and mark locked up
+  at 778:367, and `Plussie` is the character — the same circle and the same two
+  `+` glyphs the mark draws, out of the same geometry module, with the eyes in
+  their own groups so a pose can move them. All three come from the root barrel
+  (`@cueplusplus/ui`), pull no optional peer, and are static markup, so a
+  server-rendered header costs no client bundle.
+
+  ```tsx
+  import { CueLogotype, CueMark, Plussie } from "@cueplusplus/ui";
+
+  <CueMark size="sm" />
+  <CueLogotype size="lg" title="CUE++" />
+  <Plussie size={96} expression="wink" />
+  ```
+
+  Props on all three: `size` (`"sm" | "md" | "lg"`, or a height in px), which sets
+  the height and lets the artwork's ratio decide the width; `tone`
+  (`"inherit" | "fg" | "accent"`, default `"inherit"` = `currentColor`); and an
+  optional `title`, which turns a decorative `aria-hidden` mark into a labelled
+  `role="img"`. `Plussie` adds `expression` (`default`, `blink`, `wink`,
+  `look-left`, `look-right`, `look-up`, `look-down` — each one a still from the
+  character's own animations) and `idle`, a CSS-only blink that is off by default
+  and switched off again under `prefers-reduced-motion`.
+
+  There is no light/dark pair to choose between. `@cueplusplus/brand-tokens` still
+  ships the four source SVGs as files for the places that need a URL — a favicon,
+  an `<img>`, an email — and those hard-code `white`, `black` and `#1E1E1E`.
+  These components take their ink from the token layer instead, so one element is
+  correct in all eight presets and both modes. The path data is the same artwork,
+  copied verbatim.
+
+- b86f482: The density ladder is five rungs, and the two names in the middle have moved.
+
+  `ultra-compact` · `normal` · `large` was never a ladder anyone could reason
+  about: the rung called `normal` is what every other design system calls
+  _compact_, the rung called `large` is what everyone else calls _normal_, and
+  above that there was nothing at all — no level for a touch panel, a stage
+  monitor, or a reader who needs the whole screen a size up. This renames the two
+  misnamed rungs to what they always were and adds the two that were missing.
+
+  **Minor rather than major because the package is pre-1.0** — 0.x's breaking rung
+  is the minor one, and this is breaking.
+
+  **Read the migration before you upgrade.** One of its four steps is a prop
+  rename a compiler catches. The other three are not: CSS of your own keyed on
+  `[data-density]`, a label map with one entry per level, and a persisted
+  preference all keep working after this release and quietly mean something else.
+
+  ## The mapping
+
+  | you wrote       | you now write     | geometry                                             |
+  | --------------- | ----------------- | ---------------------------------------------------- |
+  | `ultra-compact` | `ultra-compact`   | unchanged                                            |
+  | `normal`        | **`compact`**     | **unchanged** — the name moved, not a pixel          |
+  | `large`         | **`normal`**      | **unchanged** — the name moved, not a pixel          |
+  | —               | **`large`**       | new: a rung above what the ladder used to top out at |
+  | —               | **`ultra-large`** | new: the top, and the mirror of `ultra-compact`      |
+
+  Nothing that existed changed size. `<ThemeProvider density="normal">` used to
+  render 24px controls and now renders 32px ones — not because the geometry moved
+  but because `normal` now names the rung above the one it used to name.
+
+  ## Migrating
+
+  Four things move. Only the first and the last are visible to a compiler; the two
+  in the middle are the ones that ship a wrong-looking screen with a green build.
+
+  ### 1. Rename every level you name, one step down the ladder
+
+  Everywhere you write a density — the provider, a `<Density>` island, a prop you pass
+  through, a test:
+
+  ```diff
+  -<ThemeProvider theme="cue" density="normal">
+  +<ThemeProvider theme="cue" density="compact">
+  ```
+
+  ```diff
+  -<Density density="large">
+  +<Density density="normal">
+  ```
+
+  `ultra-compact` is unchanged and needs no edit. Do the two renames in that
+  order, or in one pass — `normal` → `compact` and `large` → `normal` — and your
+  screens render exactly as they did before.
+
+  **If you never passed a `density`, this step is a no-op.** The default moved
+  from `normal` to `compact`, which is the same geometry it always was: an app
+  that never chose a level renders identically before and after.
+
+  ### 2. Rename your own `[data-density]` CSS — and add blocks for the two new rungs
+
+  **This is the half that fails silently.** If your app keys any of its own CSS on
+  `data-density` — a per-rung scalar you multiply your lengths by, a per-rung
+  override, anything — those selectors still match a valid attribute value after
+  this release. They just match a _different rung_. Nothing throws, nothing logs,
+  no build fails: your rows simply stop matching the controls inside them.
+
+  ```diff
+   :root { --app-type: 1; --app-space: 1; }
+  -[data-density="normal"] { --app-type: 1;     --app-space: 1; }
+  -[data-density="large"]  { --app-type: 1.111; --app-space: 1.333; }
+  +[data-density="compact"] { --app-type: 1;     --app-space: 1; }
+  +[data-density="normal"]  { --app-type: 1.111; --app-space: 1.333; }
+  +/* and two blocks that did not exist before — continue your own step, or read
+  +   the ratio off the library's ladder: --cue-density is 0.85 / 1 / 1.3 / 1.6 / 1.9
+  +   and the spacing sequence shifts one place per rung. */
+  +[data-density="large"]       { --app-type: …; --app-space: …; }
+  +[data-density="ultra-large"] { --app-type: …; --app-space: …; }
+  ```
+
+  What each rung does if you rename the props and stop there:
+
+  | rung            | if you only renamed the props                   | what the reader sees                                                            |
+  | --------------- | ----------------------------------------------- | ------------------------------------------------------------------------------- |
+  | `ultra-compact` | your `ultra-compact` block still matches        | correct                                                                         |
+  | `compact`       | **no block matches** — falls through to `:root` | your scalars sit at their base values while the library's geometry is a rung up |
+  | `normal`        | your old `normal` block matches                 | your scalars are a rung behind the library's                                    |
+  | `large`         | your old `large` block matches                  | your scalars are two rungs behind                                               |
+  | `ultra-large`   | **no block matches** — falls through to `:root` | base scalars against the largest geometry the ladder has                        |
+
+  A rung with no block of yours does not fall back to the nearest one. It falls
+  through to whatever `:root` declares, which is almost always the smallest value
+  you own. Grep your stylesheets for `data-density` before you upgrade:
+
+  ```sh
+  rg 'data-density' --glob '!node_modules'
+  ```
+
+  ### 3. Fix anything that enumerates the ladder
+
+  A label map, a switcher, a segmented control, a settings screen, a persisted
+  preference — anything with one entry per density level is now missing two and
+  mis-naming two. A map keyed by the old three names does not error; it returns
+  `undefined`, and most switchers render the raw slug:
+
+  ```diff
+   const DENSITY_LABELS = {
+     "ultra-compact": "Ultra compact",
+  -  normal: "Normal",
+  -  large: "Large",
+  +  compact: "Compact",
+  +  normal: "Normal",
+  +  large: "Large",
+  +  "ultra-large": "Ultra large",
+   };
+  ```
+
+  `DENSITIES` from `@cueplusplus/tokens` is the list to derive from rather than
+  restate — it is five entries now and it will be right next time too. If your map
+  is typed `Record<Density, string>` TypeScript will fail the build for you; if it
+  is a plain object literal, nothing will.
+
+  **A persisted preference that says `"normal"` is now a bigger screen.** The
+  provider stores the level under `localStorage` and validates it against the
+  ladder, so `"normal"` is still a valid value — it just means a different rung.
+  Migrate the stored value the same way you migrate the code, or accept that
+  returning users move up one rung once.
+
+  ### 4. `density-ultra:` is now `density-ultra-compact:`
+
+  The stylesheet registers one Tailwind variant per rung, each named after the
+  rung it matches: `density-ultra-compact:`, `density-compact:`,
+  `density-normal:`, `density-large:`, `density-ultra-large:`. `density-ultra:` is
+  gone, because with an `ultra-large` rung on the ladder "ultra" names neither end
+  of it — and an unknown variant is a build error, so this one tells you.
+  `density-large:` keeps its name and changes meaning with its rung, which does
+  not.
+
+  ## The two new rungs
+
+  Every axis continues the step the three existing rungs already walk, rather than
+  scaling anything by a factor:
+
+  |                  | ultra-compact | compact | normal   | **large**    | **ultra-large** |
+  | ---------------- | ------------- | ------- | -------- | ------------ | --------------- |
+  | `control-md`     | 20px          | 24px    | 32px     | **40px**     | **48px**        |
+  | `chip-h`         | 16px          | 18px    | 22px     | **26px**     | **30px**        |
+  | `icon-md`        | 10px          | 12px    | 16px     | **20px**     | **24px**        |
+  | `text-body`      | 10px          | 11px    | 13px     | **15px**     | **17px**        |
+  | `pad-row`        | 2 × 6px       | 4 × 8px | 6 × 12px | **8 × 16px** | **10 × 20px**   |
+  | `chrome-toolbar` | 32px          | 36px    | 44px     | **52px**     | **60px**        |
+  | `--cue-density`  | 0.85          | 1       | 1.3      | **1.6**      | **1.9**         |
+
+  `large` is a touch and presentation rung: 40px controls clear the WCAG 2.2
+  SC 2.5.8 target floor with room to spare. `ultra-large` is for a wall display, a
+  kiosk, a stage monitor read from two metres, and for a low-vision reader who
+  wants the whole interface a size up rather than the browser's zoom.
+
+  The `@media (pointer: coarse)` re-raise still applies to `ultra-compact` alone,
+  and still raises it to exactly the same heights it always did — `compact`'s.
+  `compact` is the rung the raise lands on, so raising it too would mean promoting
+  it to `normal` and moving today's default geometry on every touch device.
+
+  ## The type ladder got a top
+
+  `text-title` and `text-emphasis` are bigger at every rung. `text-micro`,
+  `text-label`, `text-ui` and `text-body` are untouched — consoles are built out
+  of those four and none of them moves.
+
+  |                 | ultra-compact | compact       | normal        | large    | ultra-large |
+  | --------------- | ------------- | ------------- | ------------- | -------- | ----------- |
+  | `text-emphasis` | 11 → **13px** | 12 → **14px** | 14 → **17px** | **20px** | **23px**    |
+  | `text-title`    | 12 → **16px** | 13 → **18px** | 16 → **22px** | **26px** | **30px**    |
+
+  A page heading was 1.18× a paragraph, which is not a hierarchy — it is six sizes
+  within four points of each other, and every screen built on it came out flat. It
+  is now 1.6–1.76×, and the whole ladder spans 2× to 2.7× from `micro` to `title`
+  depending on the rung. If you set a page title in `text-title` it will look like
+  one now; if you were compensating with a hand-written size, delete the
+  compensation.
+
+  ## Also
+
+  `prepaintScript()` takes a third argument, `defaultDensity`, alongside
+  `defaultTheme`. An app whose provider names a level other than `compact` should
+  pass the same level here, or the first frame paints at one rung and every frame
+  after it at another:
+
+  ```tsx
+  prepaintScript(DEFAULT_STORAGE_KEY, "cue", "normal");
+  ```
+
+- a382b68: A ninth theme preset, `quotamate`, with a light pair.
+
+  `THEMES` gains `"quotamate"` and `ThemeName` widens with it, so a consumer can write
+  `theme="quotamate"` without a cast. `dist/themes/quotamate.css` is built alongside the other
+  eight, and `THEME_PRESETS.quotamate` is available to `createTheme()` and the configurator.
+
+  ```tsx
+  <ThemeProvider theme="quotamate" density="ultra-compact" mode="dark">
+  ```
+
+  A blue-black ramp at hue 240 under a cyan accent (`#00e5e5`). Not a new design — quotamate is
+  a shipping product whose palette was already fixed in a private stylesheet, so the values are
+  the same colours in hex that it authored in HSL. Adopting the preset is a no-op for the
+  running product rather than a restyle, which is the only reason it can be adopted at all.
+
+  **Its status hues are deliberately not the accent**, which is where this preset differs from
+  `cue`. quotamate's whole job is to say whether an account is usable right now, so `ok`, `warn`
+  and `danger` have to stay separable at a glance from the colour that means "interactive" — a
+  dashboard where "healthy" and "clickable" are the same green cannot be read quickly.
+
+  Light drops the accent to a deepened teal (`#0d7d7d`) rather than the near-black the product
+  itself used. `#00e5e5` on `#fcfcfc` fails contrast for text and for a hairline rim alike, so
+  the product's instinct was right; an accent that is merely dark, though, loses the brand.
+  Same hue, enough chroma to read as the product's colour, dark enough to carry white text on a
+  filled control.
+
+  Two tests encoded "eight presets" and were corrected rather than bumped:
+
+  - `build.test.mjs` listed the theme names, which is the point of that assertion.
+  - `disjoint.test.mjs` asserted `sources === 16` as a stand-in for "each preset has a dark and
+    a light source". A count is a poor proxy — eight darks and eight lights is 16, and so is
+    nine darks and seven lights — and it failed a geometry test for a reason unrelated to
+    geometry. It now asserts the pairing directly and will not go stale on the tenth preset.
+
+- 236d09b: The bars: `AppBar`, `Footer`, and one overflow behaviour for every strip that can
+  outgrow its box.
+
+  ### One overflow behaviour, not three bespoke fixes
+
+  `Toolbar` had neither wrap nor scroll and its buttons are `shrink-0
+whitespace-nowrap`, so a bar wider than its container ran off the edge with no
+  way to reach it. `SegmentedControl` did the same with five segments in a page
+  header. Both now scroll, from one module, with the affordance
+  `ScrollableTabsList` has shipped since the tab strip was written: a fade mask at
+  whichever edge still hides something, and a chevron there — because what sits at
+  an overflowing edge is usually the gap _between_ two controls, and fading empty
+  space produces nothing anyone can see.
+
+  ```tsx
+  <Toolbar.Root aria-label="Playback" />          // scrolls by default
+  <Toolbar.Root aria-label="Playback" overflow="clip" />   // the old behaviour
+  <SegmentedControl aria-label="View" items={items} overflow="clip" />
+  ```
+
+  Not wrapping: every bar here is one rung of the chrome ladder tall and sits in a
+  layout that has already subtracted that height, so a bar that quietly becomes
+  two rows steals it from the work area. Not a "more" menu: `Toolbar` takes
+  arbitrary children and there is no honest conversion from one into a menu item,
+  so it would need a parallel data model, a measuring pass on every resize, and it
+  would lift the surplus controls out of Base UI's roving-focus group. A bar whose
+  controls fit renders exactly as it did before — no mask, no chevrons, no
+  compositing layer.
+
+  `AppBar.Nav` and `ScrollableTabsList` use the same module, so the library has one
+  implementation of this and four consumers.
+
+  ### `AppBar` — the horizontal bar
+
+  ```tsx
+  <AppBar.Root>
+    <AppBar.Brand render={<NextLink href="/" />}>
+      <Eyebrow>@cueplusplus/ui</Eyebrow>
+      <Chip tone="accent" variant="outline">
+        0.1.0
+      </Chip>
+    </AppBar.Brand>
+
+    <AppBar.Nav aria-label="Sections">
+      <AppBar.Link render={<NextLink href="/docs" />}>
+        Getting started
+      </AppBar.Link>
+      <AppBar.Separator />
+      <AppBar.Link render={<NextLink href="/gallery" />} register="strong">
+        Gallery
+      </AppBar.Link>
+      <AppBar.Link
+        external
+        render={<a href="https://skills.cueplusplus.com" />}
+      >
+        Skills
+      </AppBar.Link>
+    </AppBar.Nav>
+
+    <AppBar.Actions>
+      <ThemePicker />
+    </AppBar.Actions>
+  </AppBar.Root>
+  ```
+
+  Sticky, `--cue-chrome-toolbar` tall, brand and actions `shrink-0` with the
+  navigation between them giving up the width. `AppBar.Link` is set in one of two
+  registers — `muted` is furniture, `strong` is a destination — and `active` is a
+  third thing rather than a louder register: accent ink _and_ `aria-current="page"`.
+
+  This is a **bar**, not a menu: `NavigationMenu` goes inside `AppBar.Nav` when a
+  section has children. It is also not `TitleBar`, which is window furniture.
+
+  **It adds no viewport breakpoint.** `AppShell` still holds the library's only
+  one, for navigation shape. A horizontal bar never faces that question: at 390px
+  it is the same bar with a shorter window onto the same links.
+
+  `app-bar.tsx` carries no `"use client"` directive, so the bar renders from a
+  server component — which a site header has to, because that is where a framework
+  reads its data. The client boundary is around the navigation's scroller alone.
+
+  ### `Footer` — the landmark, the hairline, the measure
+
+  ```tsx
+  <Footer
+    meta={
+      <>
+        <span>© 2026 CUE++</span>
+        <Link href="/legal">Legal</Link>
+      </>
+    }
+  >
+    <Grid minItemWidth="12rem" gap={5}>
+      <Stack gap={2}>
+        <Eyebrow>Docs</Eyebrow>
+        <Link href="/docs">Getting started</Link>
+      </Stack>
+    </Grid>
+  </Footer>
+  ```
+
+  The `contentinfo` landmark, a full-bleed hairline, a centred column on the same
+  four measures `Container` and `PageShell` offer (`broad` by default), and a
+  `meta` slot whose fine print hangs under a rule of its own.
+
+  Deliberately **not** a link-list component. A complex footer is `Grid` + `Stack`
+  - `Link` inside this one — components that already exist, already read the
+    density ladder, and already handle a column that is a paragraph rather than a
+    list. `Grid`'s `minItemWidth` collapses the columns on a phone with no breakpoint
+    and no prop for how many to draw. Static markup, no `"use client"`.
+
+- 2c6aca1: `AppShell` and `Sidebar`: the four defects the shell's first independent consumer found, and the landmark it was announcing twice.
+
+  `AppShell` was drawn from the console specimens. The documentation site is the
+  first thing outside them to wear it, and putting a real 30-row navigation and a
+  few hundred visually-hidden labels through it turned up four things the
+  specimens never could. All four are fixed in the library rather than at the call
+  site, which is the whole point of a shell.
+
+  **Minor rather than major because the package is pre-1.0** — 0.x's breaking rung
+  is the minor one, and two of these changes are breaking. The migration is at the
+  bottom.
+
+  **`AppShell.Root` keeps its own `documentScrolls: false` promise.** The frame is
+  now `relative overflow-clip`. The flex arithmetic it already had only governs
+  boxes in the flow; an absolutely positioned descendant is laid out against its
+  containing block, and a frame that is neither positioned nor clipping is not
+  one — so the _initial_ containing block was, and the descendant's scrollable
+  overflow landed on `<html>`. `.sr-only` is `position: absolute`, so this was an
+  everyday case rather than an exotic one: a page carrying 308 hidden labels
+  measured a 7,068px document inside a 900px frame with every visible box on
+  screen, and a browser scrollbar that scrolled nothing. `clip` rather than
+  `hidden`, so the frame is not a scroll container something can shove sideways
+  with no scrollbar to put it back. The emitters are fixed too — `StatusDot`,
+  `OTPField`, `Message`, `AskBox` and `Sidebar.Item` now position the box their
+  hidden label is laid out against, so the leak stops at source as well as at the
+  frame.
+
+  **One navigation, one landmark.** `Sidebar.Root` rendered `<aside>` while
+  `AppShell.Sidebar`'s drawer half rendered `<nav>`, so the same navigation
+  announced as two different landmarks depending on the viewport — and a call site
+  whose column is the site's primary navigation had to hand-patch
+  `role="navigation"` over the part. Both halves now take one `landmark` prop:
+
+  ```tsx
+  <AppShell.Sidebar aria-label="Console">…</AppShell.Sidebar>              {/* <nav>, both shapes */}
+  <Sidebar.Root aria-label="Filters" landmark="complementary">…</Sidebar.Root>  {/* <aside> */}
+  ```
+
+  `"navigation"` is the default, because a column of `Sidebar.Item`s with one of
+  them marked `aria-current="page"` is primary navigation and not complementary.
+
+  **The column scrolls, and the rail does not scroll with it.** `Sidebar.Root` had
+  no scroller at all, so a navigation taller than the frame simply lost its last
+  rows; the fix is an inner scroller rather than `overflow-y-auto` on the root,
+  because `Sidebar.Rail` is `absolute inset-y-0` and would otherwise slide away
+  with the third screenful. Its containing block is the root and the scroller is
+  the element inside it, so the rail spans the whole column and holds its edge
+  however far the sections are scrolled. Measured: a 828px column of navigation in
+  a 318px frame, scrolled 400px, rail unmoved and unclipped.
+
+  **`AppShell.NavTrigger` is a target a finger can hit.** It defaulted to
+  `size="sm"` — 20px at normal density — on a control that renders _only_ below
+  the `md` breakpoint, which is to say only on a touch screen, under the 24×24
+  floor WCAG 2.2 SC 2.5.8 sets. The default is `size="md"` now: 24px at normal and
+  large, and 24px at ultra-compact too, where the token layer's
+  `@media (pointer: coarse)` rule already lifts the control ladder. It is also
+  `shrink-0`, because every other slot in `AppBar` is and this was the one that
+  gave — measured at 14px wide in a crowded 390px bar.
+
+  `Footer` gained no code, but its guidance was wrong in a way that cost a site its
+  footer: it listed "inside `AppShell`" under _when not to use_. Inside a shell a
+  footer belongs to the content scroller, at the end of the work area — bounded by
+  the content column, scrolling with the page. What does not belong is a footer as
+  a sibling of the navigation column. `Footer` and `StatusBar` are different
+  objects and a shell can carry both.
+
+  ### Migrating
+  - **`Sidebar.Root` renders `<nav>`.** A stylesheet or a test selecting
+    `aside[data-slot="sidebar"]` needs `[data-slot="sidebar"]`, and a column that
+    really is complementary needs `landmark="complementary"`. A call site passing
+    `role="navigation"` to work around the old element can drop it.
+  - **`Sidebar.Root` has one more element inside it.** Its children are wrapped in
+    `[data-slot="sidebar-scroller"]`, which now carries the column's padding and
+    gap. A `> *` selector aimed at the sections needs re-aiming; `overflow-y-auto`
+    passed in at the call site can go.
+  - **`AppShell.NavTrigger` is 4px bigger.** Pass `size="sm"` back if a bar really
+    needs the old height, and read WCAG 2.5.8 first.
+
+### Patch Changes
+
+- 6ce0c7d: The release notes now ship inside the package.
+
+  `files` was `dist` alone, so the `CHANGELOG.md` this repository writes on every
+  release stayed in a private git repository and reached nobody: `npm pack` left it
+  out, and the tarball a consumer installs from GitHub Packages carried the code
+  with no record of what had changed in it. Anyone asking "what moved between the
+  version I have and the version I am upgrading to" had to have access to the
+  source repository to find out.
+
+  `CHANGELOG.md` is now on the `files` allowlist of all three published packages,
+  so it lands in `node_modules/@cueplusplus/<package>/CHANGELOG.md` beside the code
+  it describes. `packages/release` has the test that keeps it there.
+
+  No code changes and no API changes — the same `dist`, plus one file.
+
+  The same notes are published, alongside the CUE++ agent skills' own, at
+  <https://skills.cueplusplus.com/releases>.
+
+- Updated dependencies [33a95c4]
+- Updated dependencies [b86f482]
+- Updated dependencies [a382b68]
+- Updated dependencies [6ce0c7d]
+  - @cueplusplus/tokens@0.2.0
+
+## 0.1.0
+
+### Minor Changes
+
+- First release of the CUE++ design system.
+
+  `@cueplusplus/tokens` ships eight theme presets (`cue`, `terminal`, `signal`, `venu`, `hivehub`,
+  `dusk`, `luma`, `snuffle`) in dark and light, three density levels (`ultra-compact`, `normal`,
+  `large`), and the Tailwind v4 `@theme inline` mapping — colour scoped to `[data-theme]`, geometry to
+  `[data-density]`, never mixed.
+
+  `@cueplusplus/ui` ships 146 components on Base UI: the core entry plus the `/layout`, `/forms`,
+  `/overlays`, `/chrome`, `/instruments`, `/chat`, `/theming`, `/configurator`, `/color`, `/date`
+  subpaths and the four opt-in ones (`/charts`, `/dmx`, `/midi`, `/flow`) whose heavy dependencies stay
+  optional peers. `ThemeProvider`, the density islands, `createTheme()` with its contrast report and the
+  floating `ThemeConfigurator` come with it.
+
+  `@cueplusplus/brand-tokens` ships the CUE++ brand layer — the white-alpha ramp, the mono stack, the
+  eyebrow and motion treatments, and the wordmark and Plussie marks.
+
+### Patch Changes
+
+- Updated dependencies
+  - @cueplusplus/tokens@0.1.0