@cueplusplus/ui 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,443 @@
 # @cueplusplus/ui
 
+## 0.10.0
+
+### Minor Changes
+
+- ddce99e: `@cueplusplus/ui/layout` — and the root barrel with it — now exports `Bento`, a grid of unequal
+  tiles whose span is a prop on the tile rather than a class you count out on the container.
+
+  **Nothing to do: it is a new export, and nothing that already compiled changed.** Adopt it where
+  you were writing a bare grid and hand-counting `col-span-*`:
+
+  ```tsx
+  import { Bento } from "@cueplusplus/ui/layout";
+
+  <Bento.Root cols={3} rows={2} gap={5}>
+    <Bento.Tile span={2} rowSpan={2} minHeight="hero" title="Kitchen sink">
+      Every component, on one page.
+    </Bento.Tile>
+    <Bento.Tile href="/docs/components" title="Components">
+      Props, variants and a live example.
+    </Bento.Tile>
+  </Bento.Root>;
+  ```
+
+  `Bento.Root` takes `cols` (2, 3 or 4; defaults to 3), `rows` (1–4), `dense`, and a `gap` off the
+  density space ladder (defaults to `4`). `Bento.Tile` takes a `span` (1–4) and a `rowSpan` (1–2)
+  from closed sets, plus `minHeight`, `eyebrow`, `title` and `meta`. The container clamps every span
+  to its own tracks on the way past — the columns always, and the rows wherever it declared any. The
+  column clamp is per breakpoint, because every bento is two tracks wide between 640 px and 1024 px
+  whatever it was asked for, and CSS Grid answers an over-wide span by growing an implicit track
+  rather than by refusing it.
+
+  Two things a props table cannot show you, both of them compile-time where a compiler can reach:
+
+  - **A tile is one thing or the other, in the type.** Either a **link** — `href`, optionally with
+    `render`, a router's own element which is cloned, keeps its own `href` because `next/link`
+    requires it to declare one, and has its `className` merged with the tile's rather than replaced
+    — whose whole surface is a single `<a>` and whose content is therefore static. Or a **panel**,
+    whose children may be live and whose link or control is a visible sibling in `action`. `href`
+    and `action` are mutually exclusive in the type, and a dev-time `console.error` names any tile
+    that puts an interactive child inside an anchor.
+  - **Static markup throughout** — no hooks and no `"use client"` — so a server component can draw a
+    bento without opening a client boundary. That is why the router escape hatch is an element to
+    clone rather than a render function: a directive is per module, and the hook that reads a render
+    function is a hook.
+
+  `manifest/manifest.json` and the new `manifest/components/bento.json` were regenerated with it.
+
+- 16d2cae: `@cueplusplus/ui/system` now exports `isSafeTokenValue(value: string): boolean` — whether a string
+  may be written into the density stylesheet `ThemeProvider` builds from its `overrides` prop.
+
+  **Nothing to do.** Nothing about that stylesheet changed: this is the rule `overridesCss()` has
+  always applied, exported. Adopt it if you assemble a `TokenOverrides` out of anything a person or
+  an API supplies, so a value is refused at your own input rather than discovered from a
+  `console.warn` one render later, with half of what you built never having reached the sheet:
+
+  ```ts
+  import {
+    isSafeTokenValue,
+    type TokenOverrides,
+  } from "@cueplusplus/ui/system";
+
+  isSafeTokenValue("Iosevka, monospace"); // → true
+  isSafeTokenValue("red;}"); // → false
+  ```
+
+  It lands against `./system`'s standing policy — that the prop's _shape_ is public while
+  `inlineOverrides()`, `overridesCss()` and `OverridesContext` stay internal, because a consumer
+  reaching for those would be writing the custom properties by hand — and it lands on the right side
+  of it: a _writer_ of custom properties is what the policy excludes, and a _reader_ that refuses a
+  value before it is ever written is the opposite of one. `@cueplusplus/ui/configurator`'s
+  `isSafeCssValue` is unchanged and unmoved; it is the same rule behind a subpath that also carries
+  `ThemeConfigurator`, `ExportDialog` and an optional `react-aria-components` peer, and a caller
+  that only wants the question answered should not have to take that graph to ask it.
+
+- 88cf751: The component manifest's `schemaVersion` is now `2`, and every `PropDoc` in it — root props and
+  every compound part's props alike — carries a required `control`: `{ kind, members?, min?, max?,
+nullable?, fixture? }`, where `kind` is one of `boolean`, `enum`, `number`, `string`, `node`,
+  `callback`, `array`, `object` or `opaque`. It answers the question `type` never could: _what edits
+  this prop_.
+
+  **What a reader of `manifest.json` must change: the version pin, and nothing else.** A consumer
+  that asserts `schemaVersion === 1` will reject every document this release publishes and has to
+  move to `2`; a consumer that ignores the field keeps working once the pin moves. Both published
+  manifests (`manifest/manifest.json` and every document under `manifest/components/`) were
+  regenerated, as was `manifest/tokens.json`, whose `schemaVersion` moves with them — so all three
+  have to be read at the same version.
+
+  A `variant` prop's `members` are its `cva` recipe's, in the recipe's order; a numeric literal union
+  carries its own `min`/`max`, and a prop whose JSDoc states a range with `@min`/`@max` carries that;
+  a union with an explicit `| null` is `nullable`.
+
+  ## Migrating
+  - **`type` is unchanged.** It still prints the TypeScript type verbatim, literal unions included,
+    and it is still the field to render when a reader wants to know what a prop _is_. `control` is a
+    new field beside it, not a replacement for it: nothing was renamed and nothing was removed.
+  - **A consumer pinned to `schemaVersion === 1` must move to `2`.** The number changed because
+    `control` is _required_: a consumer that reads it needs to know whether the document it fetched
+    has one, and an optional field could never tell it — absent would mean both "no control" and
+    "an older manifest". A consumer that ignores the field keeps working after changing the pin.
+
+### Patch Changes
+
+- c469f49: `Button` now **declares** `children` in `ButtonProps`, so the published manifest documents it and
+  the props table has a row for it.
+
+  **Nothing to do.** The component did not change — it has always taken children, through
+  `React.ComponentPropsWithoutRef<"button">`. What changed is what the package says about itself:
+  docgen documents a prop only where the library declares it, so the system's most used control
+  published no `children` at all. The page did not list it, and a propSet could not name it, which
+  is how `/play/button` came to preview an unlabelled `<button>` behind a standing accessibility
+  exemption. Declaring it is what lets that exemption expire.
+
+  If you read `manifest/components/button.json` to generate code or to drive a playground,
+  `children` is now in `props` and can be set like any other prop.
+
+- 481e8c5: `manifest/components/ledger.json` said `Ledger` could not fold. It can, and the note now says so.
+
+  **Nothing to do unless you read the manifest.** No API changed, no component moved, and nothing
+  you have written needs editing. The documentation that ships inside the package described the
+  plain bench as having "no disclosure anywhere — the ledger does not collapse", which was true
+  before 0.8.0 and false in it: `collapsible` puts a real
+  `button[aria-expanded aria-controls]` inside the `h2`/`h3` and folds the run of rows below it.
+
+  The corrected note says what shipped — folding is opt-in per heading, and a ledger nobody asks to
+  fold still emits no control and no expansion state at all. The manifest is the only published
+  surface this touches.
+
+- 64b4bab: Every package manifest's `repository` field now names `cueplusplus/cue-ui`, following the
+  repository's rename from an earlier working title.
+
+  **Nothing to do.** No code, no exports, no types, and no package name: the scope is the
+  organisation, not the repository, so every specifier you already import is the one you keep
+  importing. What moves is metadata — GitHub Packages matches a package to a repository through that
+  field, so from this release the "source" link on each package's registry page, and the repository
+  the next publish is attributed to, name `cue-ui`. The `directory` beside it is unchanged, so each
+  link still lands on that package rather than on the monorepo root.
+
+  If you have a bookmark or a script pointing at the old URL, GitHub's rename redirect answers it;
+  updating it to `https://github.com/cueplusplus/cue-ui` is tidiness rather than repair.
+
+- 3471a15: `tokensUsed` in the published component manifest is now scanned from code rather than from bytes,
+  so it stops attributing tokens to components that never resolve them.
+
+  **What to do: re-read the manifest before you trust a `tokensUsed` list you cached.** No API
+  changed and nothing you render moves, but the manifest says something different about 48 of 321
+  components, and the old answer was padded — in thirteen cases wholly wrong. If you read
+  `tokensUsed` to decide which tokens to define when restyling a component, the list you had was
+  too wide. It is narrower now, and true.
+
+  The scanner matched `--cue-*` anywhere in a file's text, comments included. A docblock sentence
+  naming a token published it as one the component uses, and a sentence arguing _against_ one
+  published the opposite of what it said: `forms/_chassis.ts` explains that the ring reads
+  `--cue-focus`, **not** `--cue-accent`, and eleven controls on that chassis published
+  `--cue-accent` because of it.
+
+  What moved, exactly:
+
+  - **Thirty-four components lose one to four tokens they never painted.**
+  - **Thirteen now correctly publish none** — `agent-surface`, `animated-number`,
+    `chart-container` and the ten container icons — because their lists were comment-derived in
+    their entirety: they paint through classes rather than resolving custom properties by name, and
+    the ten icons render no `className` at all. An empty array renders as no Tokens section rather
+    than an empty one, which is what the four components that already shipped one do.
+  - **One gains four.** `MarkdownText` painted `--cue-accent`, `--cue-fg`, `--cue-fg-muted` and
+    `--cue-fg-subtle` and published none of them: the literal pass pairs quotes across the whole
+    file, and the apostrophes in that file's prose desynced the pairing so the class strings below
+    were read as the insides of strings. Blanking the comments re-pairs them.
+  - **Two entries that were never tokens are gone**, `--cue-icon-` and `--cue-space-`: the regex had
+    been stopping at the `*` in `--cue-icon-*` and the `$` in `gap-(--cue-space-${n})`.
+
+- Updated dependencies [64b4bab]
+- Updated dependencies [362cdda]
+- Updated dependencies [c2238cc]
+  - @cueplusplus/tokens@0.10.0
+  - @cueplusplus/theme-base@1.0.1
+
+## 0.9.0
+
+### Minor Changes
+
+- 5eb0da2: The ten colour presets leave `@cueplusplus/tokens` and become packages of their
+  own. `@cueplusplus/ui/styles.css` now ships the blank base instead of a palette,
+  so a theme is something you install, import and register — the same way a
+  third-party theme always should have been, and now is.
+
+  `@cueplusplus/tokens` keeps the two axes it actually owns: the five density
+  rungs and the eight font pairings, plus the contracts, `base.json` and the
+  primitives a theme source aliases. It emits `axes.css` and no colour at all.
+  Each preset is `@cueplusplus/theme-<name>` — `cue`, `dusk`, `hivehub`, `luma`,
+  `quotamate`, `requestport`, `signal`, `snuffle`, `terminal`, `venu` — carrying
+  the stylesheet it always carried, byte for byte: nothing about any shipped
+  palette moved, and a frozen snapshot of what `tokens@0.8.0` emitted is committed
+  so that stays checkable rather than merely asserted.
+
+  ## Migrating
+
+  **The unattributed default stops being `cue`.** An app that imports
+  `@cueplusplus/ui/styles.css` and registers nothing now paints the blank base.
+  Nothing errors and nothing falls back: a `data-theme` value is styled by
+  whichever stylesheet declares it, and with no theme package imported, none does.
+
+  Ten custom properties move in dark and seven in light. Measured on a root
+  stamped `data-theme="cue"`, which is what every `ThemeProvider` stamped before
+  this release and still stamps, so this is the delta for an app that changes
+  nothing:
+
+  | token                                                | dark: `cue` → blank base                                                | light: `cue` → blank base      |
+  | ---------------------------------------------------- | ----------------------------------------------------------------------- | ------------------------------ |
+  | `--cue-accent`                                       | `#ffffff` → `#8a93a6`                                                   | `#0a0a0a` → `#3f4759`          |
+  | `--cue-accent-hover`                                 | `rgba(255,255,255,0.85)` → `#9aa3b6`                                    | `rgba(0,0,0,0.85)` → `#333a4a` |
+  | `--cue-accent-soft`                                  | follows `--cue-accent`: it is a 14% `color-mix` of it                   | same                           |
+  | `--cue-focus`                                        | `#ffffff` → `#8a93a6`                                                   | `#0a0a0a` → `#3f4759`          |
+  | `--cue-font-theme-mono`                              | JetBrains Mono → nothing; the base declares no theme mono               | same as dark                   |
+  | `--cue-font-mono`                                    | resolves through the line above, so JetBrains Mono → the platform stack | same as dark                   |
+  | `--cue-fg`                                           | `#f5f5f7` → `#f5f5f5`                                                   | unchanged                      |
+  | `--cue-hair`, `--cue-hair-strong`, `--cue-row-hover` | follow `--cue-fg`: each is a `color-mix` of it (6%, 12%, 3.5%)          | unchanged                      |
+  | `--cue-accent-fg`                                    | unchanged                                                               | `#fcfcfc` → `#ffffff`          |
+
+  The last four rows are the ones an eye catches and a list of "the accent and the
+  focus ring" would not have mentioned: four of the ten dark changes and the one
+  light change are tokens no theme file names directly, because they are mixes of
+  two that do.
+
+  To get `cue` back, exactly as it was:
+
+  ```bash
+  pnpm add @cueplusplus/theme-cue
+  ```
+
+  ```css
+  @import "@cueplusplus/ui/styles.css";
+  @import "@cueplusplus/theme-cue/theme.css";
+  ```
+
+  ```tsx
+  import cue from "@cueplusplus/theme-cue";
+
+  <ThemeProvider themes={[cue]} theme="cue">
+    {children}
+  </ThemeProvider>;
+  ```
+
+  The import order is load-bearing: a `[data-theme]` block and the base's bare
+  `:root` tie at (0,1,0), so the one declared later wins. Importing the theme
+  before `styles.css` paints the blank base over it. Importing the package from
+  its root, rather than the `manifest.json` subpath, also closes `ThemeName` to
+  the themes you installed, so a misspelt `theme=` is a type error.
+
+  Then the rest:
+
+  - **`@cueplusplus/tokens/theme.css` is a deprecated alias** of `axes.css` for
+    one minor. It still resolves and still delivers the geometry and type axes, so
+    a stylesheet naming it keeps building — it simply carries no palette. Change
+    the line to `@cueplusplus/tokens/axes.css`, or drop it: `ui/styles.css` already
+    brings the axes in through `@cueplusplus/theme-base/base.css`.
+  - **Gone from `@cueplusplus/tokens`:** the `themes/*.css` and
+    `registry/theme-*.json` subpaths, and the `THEMES`, `ThemeName`,
+    `THEME_SUPPORTS_LIGHT` and `DEFAULT_THEME` exports. `ThemeName` now comes from
+    `@cueplusplus/theme-base` (re-exported by `@cueplusplus/ui`) and widens with
+    each theme package installed, rather than naming the ten that happened to be
+    compiled in; whether a theme ships a light block is `supportsLight` on its own
+    `manifest.json`; and there is no default palette to name, because the library
+    contains none.
+  - **`@cueplusplus/tokens`' root entry is now `dist/tokens.js`**, with
+    `dist/tokens.d.ts` beside it, where it used to be the TypeScript source
+    `dist/tokens.ts`. The import specifier, the exported names and their values
+    are unchanged — `import { DENSITIES } from "@cueplusplus/tokens"` is the same
+    line it was — but the file behind it is one Node can execute. It could not
+    before: Node refuses to strip types for anything under `node_modules`, so the
+    package worked in a workspace and failed from a registry install, taking
+    `@cueplusplus/theme-base` and the `cue-theme` CLI with it. If you added
+    `@cueplusplus/tokens` to your bundler's transpile list to work around that
+    (Next.js' `transpilePackages`, or the equivalent), take it out.
+  - **`@cueplusplus/tokens` gains `base.json`'s `fonts.handshake`**: the three
+    literals of the monospace resolution (`font-pairing-mono`, `font-theme-mono`,
+    and the `var()` that resolves them), published as data so a theme built
+    anywhere spells them the same way this build does.
+  - **`@cueplusplus/ui`'s `THEME_NAME_PATTERN` and `RESOLVED_MONO` are now
+    re-exports** of `@cueplusplus/theme-base`'s. Same names, same values, one
+    definition instead of three.
+  - **`/r/tokens.json`'s `themes` are objects**, not strings:
+    `{ name, package, supportsLight, densities }`. A consumer reading the registry
+    for a theme list wants to know which package delivers it.
+  - **Every published tarball now carries a `README.md`.** On a registry the
+    package page _is_ the README, and `tokens`, `ui` and `brand-tokens` shipped
+    without one; `packages/release/test/publishable-packages.test.mjs` holds all
+    fifteen to it now, beside the same check for `CHANGELOG.md`.
+  - **`@cueplusplus/ui` depends on `@cueplusplus/theme-base@^1`**, a range rather
+    than a pin, deliberately: two copies of `theme-base` in one tree would break
+    the type registry, because a theme's `declare module` augments one copy while
+    `ui`'s re-exported `ThemeName` resolves against the other, and neither errors.
+
+- 1b98830: `ThemeProvider` takes `themes`, an ordered array of theme manifests, and the runtime reads
+  everything about a theme from its manifest instead of from a copy inside this package. Types open:
+  `ThemeName`, `DensityLevel` (`Density` on `@cueplusplus/theme-base`) and `FontName` are now `@cueplusplus/theme-base`'s, which a theme package
+  widens by declaration merging — `"foo"` is a valid theme in an app that installed
+  `@cueplusplus/theme-foo`, and `ThemeName` is `string` in one that installed none. Three hooks —
+  `useThemes()`, `useDensities()`, `useFonts()` — return what the active theme offers. Every place
+  that validated a persisted name against a frozen list validates against the registry. A typed
+  `overrides` prop layers colours, fonts and densities over the active theme, with a development
+  contrast report.
+
+  ## Migrating
+  - **`themes` is optional for this release.** An app that passes none gets the blank base and the
+    base axes, with one development warning. Pass `themes={[cue]}` from `@cueplusplus/theme-cue`
+    when it publishes. With nothing registered there is no theme vocabulary to be out of, so
+    `ThemeProvider` and `prepaintScript` no longer reject a persisted or default theme name they do
+    not recognise: a well-formed name is stamped as-is. Pass `themes` to close the vocabulary again.
+  - **`createTheme({ base })` takes a manifest, not a name.** `createTheme({ name, base: "terminal" })`
+    becomes `createTheme({ name, base: terminal })` with `import terminal from "@cueplusplus/theme-terminal"`.
+    With no `base` it starts from the blank base. `DEFAULT_THEME_BASE` is removed.
+  - **`createTheme`'s radius rules now emit both selector forms** — `[data-theme="x"] [data-density="y"]`
+    beside `[data-theme="x"][data-density="y"]` — so a `<Density>` island and `useControlHeight`'s probe
+    get the crossed value too. A byte-comparison against the old output will differ on those lines.
+  - **`ThemeScope` from `@cueplusplus/ui/configurator` gains `manifest: ThemeManifest | null`.** Every
+    function that takes a scope needs it — `baseValue`, `resolveValue`, `resolvedTokens`, `setOverride`,
+    `clearOverride`, `isOverridden`, `scopeKey`, `exportName`, `buildExports({ scope })` and
+    `<ExportDialog scope>`. Pass the active manifest (`useTheme().manifest`) or `null` for the blank
+    base. The panel's `create-theme` export now emits an import of the base theme's manifest instead
+    of `base: "<name>"`.
+  - **`overrides` is typed `TokenOverrides`**, exported from `@cueplusplus/ui` and `@cueplusplus/ui/system`.
+    It is unrelated to `ThemeOverrides` on `@cueplusplus/ui/configurator`, which is still the
+    configurator's edit snapshot.
+  - `THEME_COLOR_TOKENS` is now exactly `COLOR_CONTRACT` from `@cueplusplus/tokens`: the same 26 names
+    in the same order.
+  - **`ThemeProvider` opens on the active theme's `densities.default` and `fontPairings.default`** when
+    you pass no `density` or `font` — the rung and pairing a theme declares it prefers. Pass one to
+    override it for every theme. No first-party theme declares either, so nothing shipped moves.
+    `prepaintScript` opens on the same tier: `defaults.density` and `defaults.font` are both optional
+    in the options form, and an absent one falls to that theme's declared preference rather than to the
+    library's base rung, so the blocking script stamps exactly what the provider is about to commit
+    with no work on your side. Passing `defaults.density` or `defaults.font` is the same statement as
+    passing the prop — do both, or neither. One consequence for the positional form: its fourth
+    argument is now validated like the other three, so `prepaintScript(key, theme, density, font)` with
+    a pairing outside the base eight throws the same `defaults.font … is not offered by theme …` the
+    options form gives, where before the script silently fell back to `system`.
+  - **Three types 16 public signatures name are now exported** from `@cueplusplus/ui` and
+    `@cueplusplus/ui/system`: `ThemeManifest`, `DensityEntry` and `FontEntry`. They appear in
+    `ThemeProviderProps.themes`, `PrepaintOptions.themes`, `ThemeContextValue.manifest`,
+    `ThemeRegistry`, `useThemes()`, `useDensities()`, `useFonts()` and `ThemeScope.manifest`, so
+    `@cueplusplus/ui` re-exports them: an app that names one of those types in a signature of its own
+    need not reach past the package it installed.
+  - **`ThemeRegistry` is exported** from `@cueplusplus/ui/system` — the shape the three registry hooks
+    read: the registered manifests, the first one's name, and the rungs and pairings the _active_ theme
+    offers.
+  - **`RESOLVED_MONO` is exported** from `@cueplusplus/ui/theming`: the `var()` chain every theme block
+    sets `--cue-font-mono` to, pairing first. A tool that writes theme CSS beside `serializeThemeCss`
+    needs the same string.
+  - **`themeSelector`'s options gain `pair?: boolean`**, which emits the descendant form
+    `[data-theme="x"] [data-density="y"]` beside the compound one, as more than one selector when
+    `density` is set. Neither a `<Density>` island nor `useControlHeight`'s `document.body` probe
+    carries `data-theme` beside its `data-density`, so this is what reaches them. This function, and
+    `@cueplusplus/theme-tools`' `cue-theme build`, now emit three forms per rung instead of two — an
+    exact match, a structural fallback, and the unchanged compound — so that a rung a theme adds or
+    retunes no longer applies inside a nested provider of another theme: not through a `<Density>`
+    island, not through the nested provider's own root opening on a rung the outer theme happens to
+    retune, and not even when that outer theme is _re-entered_ after a detour through a different one
+    several levels in, which an ancestor-only structural check cannot always tell apart from the
+    outer detour alone. **`<Density>` and the internal measuring probe now also render
+    `data-cue-theme`**, stamped from the nearest `<ThemeProvider>` (or omitted where there is none) —
+    an inert attribute nothing in this library reads back except the exact-match selector above, which
+    needs it to resolve "nearest theme" the way `useContext` already does, rather than the "does some
+    ancestor carry this theme" a pure CSS selector is limited to. All three forms are wrapped in
+    `:where()`, which contributes no specificity, so together they tie with the `overrides` prop's own
+    document-scoped density rule at (0,2,0) — as they always did — rather than outranking it.
+
+- e587341: `contrastReport()` now measures the focus ring.
+
+  `CONTRAST_REQUIREMENTS` gains a second tier: nine **advisory** pairs holding
+  `--cue-focus` and `--cue-danger` — the two roles a form control paints as a
+  ring, and therefore WCAG 1.4.11 non-text contrast surfaces — to 3:1 against
+  every ground one can be painted over. `ContrastRequirement` carries
+  `advisory?: boolean`, `ContrastReport` carries `advisories` beside `failures`,
+  and `passes` still counts only the eleven required pairs. No theme that was
+  clean yesterday fails today; every theme now gets told about its ring.
+
+  The gap was known and the gate for it lived in a test file, which protected the
+  ten shipped presets and nobody who calls `createTheme()`. The dark block takes
+  the accent into `--cue-focus` verbatim, so
+  `createTheme({ name: "acme", base: snuffle, accent: "#3b3f8f" })` — the manifest
+  imported from `@cueplusplus/theme-snuffle`, and a brand colour straight into the
+  anchor, which is the documented use — came back
+  `passes: true` with twenty-two checks, none of which named `focus`, over a ring
+  measuring 2.01:1 down to 1.55:1 on the five grounds it can sit on. The same call
+  now returns those five pairs in `report.advisories`, each with its reason. It is
+  the failure 0.6.0 fixed in `luma`, `venu` and `hivehub` at 2.45:1, and a report
+  is the only place a consumer would ever meet it: an invisible focus ring is
+  invisible in code review and invisible in a screenshot taken with a mouse.
+
+  All ten shipped presets clear the new tier in both modes — two hundred ring
+  measurements, the tightest `terminal.dark --cue-danger` on `--cue-surface-3` at
+  3.13:1 — and the preset gate now runs through `contrastReport()` rather than
+  through its own copy of the same loop.
+
+  `danger/bg` is not restated in the ring tier: the status pairs have always held
+  the red against the page at this same floor, as a required pair, and one
+  measurement gets one id.
+
+  **If you iterate `CONTRAST_REQUIREMENTS` or render `report.checks`,** the array
+  goes from 11 entries to 20 and a two-block report from 22 checks to 40. Filter
+  on `advisory` to keep the old set.
+
+### Patch Changes
+
+- cf80a87: `FlowGraph` draws an edge faint until both of the nodes it joins have been
+  reached, which is what its `edges` prop has always said it does.
+
+  The behaviour was documented, published and unimplemented: the prop's
+  description — "An edge dims until both of its ends are visible" — ships in
+  `manifest/components/flow-graph.json` and in the type declarations, the
+  `transition-opacity duration-500` was already on the path, and the component
+  computed whether an edge was live and then never used the answer. Every edge
+  painted at full strength from the first frame, so a graph revealing itself
+  through `visibleCount` showed all of its connections before it had any of its
+  nodes.
+
+  Found by turning the lint gate on: the unused binding was the first thing it
+  reported.
+
+- 2737aec: `@cueplusplus/tokens` exports the contracts and the axes as data, so a theme
+  built outside this repository can resolve over the same base: `COLOR_CONTRACT`,
+  `GEOMETRY_CONTRACT` and `FONT_TOKENS` as typed tuples, `base.json` (every
+  density's geometry, the pairings' stacks, the derived templates, the defaults),
+  `primitives.tokens.json` (the tier-1 file a theme source aliases), and
+  `axes.css` — `theme.css` with the theme axis removed. Nothing that exists today
+  moves; `theme.css` is unchanged.
+
+  `@cueplusplus/ui/theming` keeps every export it had. The contrast arithmetic now
+  lives in `@cueplusplus/theme-base` and is re-exported here; `ui` gains that
+  package as a dependency. No behaviour changes.
+
+- Updated dependencies [cf80a87]
+- Updated dependencies [5eb0da2]
+- Updated dependencies [814c859]
+- Updated dependencies [2737aec]
+  - @cueplusplus/tokens@0.9.0
+  - @cueplusplus/theme-base@1.0.0
+
 ## 0.8.0
 
 ### Minor Changes
@@ -27,6 +465,25 @@
 
 ### Patch Changes
 
+- edb938d: `Table.Row interactive` draws a focus ring. The prop supplied the
+  pointer half — the row-hover wash and a pointer cursor — and nothing for
+  focus, while the row-activation reading above tells a caller to put `tabIndex`
+  on the `<tr>` so `activateRowFromKeyDown` has something to fire on. The two
+  together made a row a keyboard user could reach and activate with nothing on
+  screen changing. **This is a WCAG 2.4.7 (Focus Visible, AA) fix you inherit by
+  upgrading.**
+
+  The ring is the one `Row` already draws: 2px solid in `--cue-accent`, pulled
+  inside the row by `-outline-offset-2` rather than floating outside it, because
+  these tables live in clipped panes and scroll regions where an outset ring on
+  the first or last row is cut off by the pane's own rim. It is `focus-visible`,
+  so a pointer press still paints nothing, and it rides on `interactive` alone:
+  a static table of figures is untouched. Nothing to change — and if you drew a
+  ring of your own on a focusable row, the library's is now under it.
+
+  Added after the fact: this shipped in 0.7.0 with no changeset, and a late entry
+  beats a hole in the record.
+
 - @cueplusplus/tokens@0.7.0
 
 ## 0.6.0

package/README.md

@@ -0,0 +1,131 @@
+# @cueplusplus/ui
+
+Components for console software: dense, keyboard-first interfaces where a screen is mostly data.
+Base UI underneath for behaviour and accessibility, Tailwind v4 on top for the paint.
+
+## Install
+
+The `@cueplusplus` scope is served by **GitHub Packages**, not npmjs.com, and GitHub Packages
+authenticates *every* install. That is two settings, in two places, and the split is not
+cosmetic — pnpm ignores an env-expanded credential in a project `.npmrc` and the install fails
+with `401`.
+
+Commit the scope routing, and nothing else, at the root of your project:
+
+```ini
+# .npmrc
+@cueplusplus:registry=https://npm.pkg.github.com
+```
+
+Then write the credential once, at the **user** level, where pnpm reads it from. It is a
+**classic** personal access token with `read:packages` — GitHub Packages accepts neither
+fine-grained PATs nor OIDC:
+
+```sh
+pnpm config set //npm.pkg.github.com/:_authToken ghp_…
+```
+
+```sh
+pnpm add @cueplusplus/ui @cueplusplus/tokens @cueplusplus/theme-cue @base-ui/react
+```
+
+Three peers are required and declared: `react` ^19, `react-dom` ^19 and `@base-ui/react` ^1.7.
+`tailwindcss` ^4 is a declared peer too, but an optional one — needed for the default styling
+lane, and without it you own the CSS. Every other peer is optional and scoped to a subpath.
+`@cueplusplus/tokens` arrives as a dependency; installing it by name just makes the token
+constants importable in your own code. The theme package is not a peer at all — see below.
+
+CI, Vercel and the token's expiry are in
+[`docs/CONSUMING.md` §1](https://github.com/cueplusplus/cue-ui/blob/main/docs/CONSUMING.md#1-registry-access).
+
+## Quick start
+
+```css
+/* app/globals.css */
+@import "tailwindcss";
+@import "@cueplusplus/ui/styles.css";
+@import "@cueplusplus/theme-cue/theme.css";
+```
+
+```tsx
+import cue from "@cueplusplus/theme-cue";
+import { Button } from "@cueplusplus/ui";
+import { ThemeProvider } from "@cueplusplus/ui/system";
+
+export default function App() {
+  return (
+    <ThemeProvider themes={[cue]} theme="cue" density="compact" mode="system">
+      <Button variant="primary">Run cue</Button>
+    </ThemeProvider>
+  );
+}
+```
+
+The order of those three `@import`s is load-bearing, and the `themes` prop is not optional in
+practice: this library contains no palette. Install and register a `@cueplusplus/theme-*` package,
+or every surface paints `@cueplusplus/theme-base`'s blank base — greys, one desaturated accent,
+the platform monospace — with nothing erroring to tell you.
+
+To stop the defaults flashing on first paint, add `prepaintScript()` beside the provider and hand
+both the same array — [§4 of `CONSUMING.md`](https://github.com/cueplusplus/cue-ui/blob/main/docs/CONSUMING.md#4-the-provider)
+is the whole layout.
+
+## What it ships
+
+Common components come from the root entry. Groups that need an optional peer have a subpath of
+their own, so importing a button never pulls a charting library into your bundle.
+
+| Import specifier | What is in it |
+| --- | --- |
+| `@cueplusplus/ui` | the root barrel: every component that costs no optional peer, the brand marks and the container icons included |
+| `@cueplusplus/ui/primitives` | the leaves: buttons, chips, avatars, dots and the two loading shapes |
+| `@cueplusplus/ui/forms` | everything a user types into, toggles, picks from or drags |
+| `@cueplusplus/ui/overlays` | everything that floats: dialogs, sheets, menus, tooltips, the command palette |
+| `@cueplusplus/ui/chrome` | console furniture: panels, rows, bars, tabs and the tree outline |
+| `@cueplusplus/ui/layout` | page structure: cards, stacks, grids, `Bento`, disclosure and the navigation shapes |
+| `@cueplusplus/ui/layout/carousel` | needs `embla-carousel-react` |
+| `@cueplusplus/ui/layout/resizable` | needs `react-resizable-panels` |
+| `@cueplusplus/ui/instruments` | the readouts: meters, sparklines, tables, logs and the two device frames |
+| `@cueplusplus/ui/instruments/data-table` | needs `@tanstack/react-table` |
+| `@cueplusplus/ui/instruments/log-viewer` | needs `@tanstack/react-virtual`, `anser` |
+| `@cueplusplus/ui/charts` | Recharts in this system's tokens, plus the categorical palette and the ramps; needs `recharts` |
+| `@cueplusplus/ui/date` | calendars, pickers and segmented date/time fields; needs `react-day-picker`, `date-fns`, `react-aria-components`, `@internationalized/date` |
+| `@cueplusplus/ui/color` | the picker suite the configurator edits with, hex and oklch; needs `react-aria-components` |
+| `@cueplusplus/ui/configurator` | the floating panel that edits the token layer live and exports what it edited; needs `react-aria-components` |
+| `@cueplusplus/ui/flow` | React Flow wearing the tokens: node cards, handles, signal-carrying wires; needs `@xyflow/react` (+ `./flow.css`) |
+| `@cueplusplus/ui/chat` | the multi-agent transcript: messages, composer, HITL questions, agent colour |
+| `@cueplusplus/ui/agent-runtime` | the streaming layer under Chat; needs `@assistant-ui/react` |
+| `@cueplusplus/ui/elements` | the agent's own surface, vendored from assistant-ui and repainted onto the tokens; needs `lucide-react` and `heat-graph` (+ `./elements.css`) |
+| `@cueplusplus/ui/elements/markdown` | `MarkdownText`; needs `react-markdown`, `rehype-sanitize` |
+| `@cueplusplus/ui/elements/generative` | the generative-UI renderer and its spec (+ `./elements/generative.css`) |
+| `@cueplusplus/ui/elements/replay` | the scripted session-replay frame |
+| `@cueplusplus/ui/dmx` | 512 bytes at wire rate: the bar, the strip, the patch bar, the channel grid |
+| `@cueplusplus/ui/midi` | sequencer instruments: keyboard, musical clock, ruler, analyser, threshold rail |
+| `@cueplusplus/ui/system` | `ThemeProvider`, `prepaintScript`, the `Density` island, the portal frame, `isSafeTokenValue` |
+| `@cueplusplus/ui/theming` | `createTheme()`, `contrastReport()` and the `--cue-*` vocabulary as constants |
+
+Four stylesheet exports. `@cueplusplus/ui/styles.css` is always imported; the other three are
+imported only if you use what they paint — `@cueplusplus/ui/elements.css`,
+`@cueplusplus/ui/flow.css` and `@cueplusplus/ui/elements/generative.css`.
+
+## The machine-readable half
+
+This package ships its own manifest: `@cueplusplus/ui/manifest.json` is an index of every
+component with a SHA-256 for each companion document, and
+`@cueplusplus/ui/manifest/components/<name>.json` is one component in full — props, variants, the
+tokens it paints with, and the hand-written notes on when it is the wrong choice. Beside them,
+`@cueplusplus/ui/manifest/tokens.json` is the token vocabulary and
+`@cueplusplus/ui/manifest/fixtures.json` the playground fixture catalogue. An agent or a code
+generator should read those rather than guess a prop name.
+
+The same surfaces are published at <https://ui.cueplusplus.com>, with the docs site, the live
+kitchen sink and the CUE++ agent skills beside them.
+
+## Where the rest is
+
+- Installing and using it from another project: [`docs/CONSUMING.md`](https://github.com/cueplusplus/cue-ui/blob/main/docs/CONSUMING.md)
+- Every component, with props and a live example: <https://ui.cueplusplus.com/docs/components>
+- Theming, density and the `--cue-*` contract: <https://ui.cueplusplus.com/docs/theming>
+- The whole surface on one page: <https://ui.cueplusplus.com/kitchen-sink>
+- Every machine-readable surface, with copy-paste snippets: <https://ui.cueplusplus.com/ai>
+- What changed in the version you have: `node_modules/@cueplusplus/ui/CHANGELOG.md`

package/dist/chat/message-list.js

@@ -42,6 +42,7 @@ const MessageList = React.forwardRef(function MessageList({ className, children,
 	const [behind, setBehind] = React.useState(false);
 	const lastHeightRef = React.useRef(0);
 	const count = React.Children.count(children);
+	const isEmpty = count === 0;
 	const previousCountRef = React.useRef(count);
 	const jumpToLatest = React.useCallback(() => {
 		const element = scrollerRef.current;
@@ -90,7 +91,7 @@ const MessageList = React.forwardRef(function MessageList({ className, children,
 	}, [
 		follow,
 		pinned,
-		count === 0
+		isEmpty
 	]);
 	const onScroll = React.useCallback(() => {
 		const element = scrollerRef.current;

package/dist/configurator/_export.d.ts

@@ -61,7 +61,7 @@ interface BuildExportsOptions {
  * @param name - What the user typed, if anything.
  * @returns A usable CSS identifier.
  * @example
- * exportName({ theme: "terminal", mode: "dark" }); // → "terminal-custom"
+ * exportName({ theme: "terminal", mode: "dark", manifest: terminal }); // → "terminal-custom"
  */
 declare function exportName(scope: ThemeScope, name?: string): string;
 /**