@cueplusplus/ui 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,277 @@
 # @cueplusplus/ui
 
+## 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
+
+- 4c7b963: `Ledger.Tier` and `Ledger.Group` take `collapsible`: the heading stays the `h2`/`h3` element it always was and gains a real `button[aria-expanded aria-controls]` inside it, which folds the run of rows below away. The heading outline is untouched, so a page that offers the same dataset folded and unfolded does not move a screen-reader user's heading list. Expansion is controlled or uncontrolled — `expanded`, `defaultExpanded`, `onExpandedChange` — and the library stores nothing: which places a reader folded is the caller's to keep. A folded run of rows is hidden rather than unmounted, so a group holding its own fold inside a tier still holds it after the tier above has been shut and opened again. A ledger nobody asks to fold renders exactly as before, with no client boundary.
+
+### Patch Changes
+
+- @cueplusplus/tokens@0.8.0
+
 ## 0.7.0
 
 ### Minor Changes

package/README.md

@@ -0,0 +1,49 @@
+# @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.
+
+```sh
+pnpm add @cueplusplus/ui @cueplusplus/tokens @cueplusplus/theme-cue @base-ui/react
+```
+
+```css
+@import "tailwindcss";
+@import "@cueplusplus/ui/styles.css";
+@import "@cueplusplus/theme-cue/theme.css";
+```
+
+```tsx
+import cue from "@cueplusplus/theme-cue";
+import { ThemeProvider } from "@cueplusplus/ui/system";
+
+<ThemeProvider themes={[cue]} theme="cue" density="compact" mode="system">
+  <App />
+</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.
+
+Common components come from the root entry. Groups that need an optional peer have a subpath of
+their own (`/charts`, `/date`, `/flow`, `/color`, `/agent-runtime`, and the rest), so importing a
+button never pulls a charting library into your bundle.
+
+## 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. An agent or a
+code generator should read that 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.
+
+## Full documentation
+
+- Installing and using it from another project: [`docs/CONSUMING.md`](https://github.com/cueplusplus/product-design-system/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>

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;
 /**

package/dist/configurator/_export.js

@@ -43,7 +43,7 @@ const DTCG_ALIASES = { density: "density-factor" };
 * @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"
 */
 function exportName(scope, name) {
 	const proposed = name?.trim() ?? "";
@@ -51,13 +51,22 @@ function exportName(scope, name) {
 }
 /** A JSON string, printed the way a hand-written source file would print it. */
 const json = (value) => `${JSON.stringify(value, null, 2)}\n`;
-/** Both modes of a scope, so an export can carry the palette the user is not looking at. */
+/**
+* Both modes of a scope, so an export can carry the palette the user is not
+* looking at.
+*
+* Spread rather than rebuilt: a fresh literal would have to restate `manifest`,
+* and the shape of that mistake is a `null` that resolves the off-mode palette
+* to the blank base — so the `dtcg` and `registry` exports would carry the right
+* colours for the mode on screen and the neutral ramp for the other one, with
+* nothing to see until somebody installed the theme.
+*/
 function bothModes(scope) {
 	return [{
-		theme: scope.theme,
+		...scope,
 		mode: "dark"
 	}, {
-		theme: scope.theme,
+		...scope,
 		mode: "light"
 	}];
 }
@@ -71,8 +80,11 @@ function movedTokens(overrides, scope, kind) {
 * ② The DTCG token file.
 *
 * A whole theme rather than a diff: the point of this format is that the result
-* can be dropped into `packages/tokens/src/themes/` (or anyone else's DTCG
-* pipeline) and built, which a patch file cannot. Groups follow the sources —
+* can be dropped into a theme package's `src/` — `cue-theme init` scaffolds one,
+* and `packages/theme-<name>/src/<name>.dark.tokens.json` is the shape — or into
+* anyone else's DTCG pipeline, and built, which a patch file cannot. (It used to
+* say `packages/tokens/src/themes/`; that directory is gone, and a palette is a
+* package now.) Groups follow the sources —
 * `color` for the palette, `type` for the stacks, `density` for the multipliers
 * — and appear only when they carry something.
 */
@@ -121,9 +133,25 @@ function dtcgFile(overrides, scope, name) {
 function quote(value) {
 	return value.includes("\"") && !value.includes("'") && !value.includes("\\") ? `'${value}'` : JSON.stringify(value);
 }
+/** What a JavaScript binding may be called, and what a printed key may go unquoted as. */
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
 /** One `key: "value"` line of an object literal, quoting the key only when it must. */
 function property(key, value, indent) {
-	return `${indent}${/^[A-Za-z_$][\w$]*$/.test(key) ? key : JSON.stringify(key)}: ${quote(value)},`;
+	return `${indent}${IDENTIFIER.test(key) ? key : JSON.stringify(key)}: ${quote(value)},`;
+}
+/**
+* What to call the imported base manifest in the snippet.
+*
+* The theme's own name where that is a legal binding — `terminal` reads as what
+* it is — and `base` where it is not (a theme may be called `acme-dark`, which
+* is a fine `data-theme` value and not an identifier). The suffix exists for the
+* one collision this can produce: a user who names their export exactly what the
+* base theme is called would otherwise get `const terminal = createTheme({ base:
+* terminal })`, which is a snippet that does not run.
+*/
+function baseIdentifier(theme, exported) {
+	const proposed = IDENTIFIER.test(theme) ? theme : "base";
+	return proposed === exported ? `${proposed}Base` : proposed;
 }
 /**
 * ③ The `createTheme()` call.
@@ -134,7 +162,17 @@ function property(key, value, indent) {
 * a snippet that quietly loses half an edit is worse than no snippet.
 */
 function createThemeSnippet(overrides, scope, name) {
-	const lines = [`  name: ${JSON.stringify(name)},`, `  base: ${JSON.stringify(scope.theme)},`];
+	const exported = IDENTIFIER.test(name) ? name : "theme";
+	const base = scope.manifest;
+	let baseImport = null;
+	let baseAnchor = null;
+	if (base !== null) {
+		const ident = baseIdentifier(scope.theme, exported);
+		baseImport = `import ${ident} from ${JSON.stringify(base.package)};`;
+		baseAnchor = `  base: ${ident},`;
+	}
+	const lines = [`  name: ${JSON.stringify(name)},`];
+	if (baseAnchor !== null) lines.push(baseAnchor);
 	const unrepresentable = [];
 	for (const [anchor, token] of DIRECT_ANCHORS) if (isOverridden(overrides, scope, token)) lines.push(property(anchor, resolveValue(overrides, scope, token), "  "));
 	const surfaces = SURFACE_ANCHORS.filter((token) => isOverridden(overrides, scope, token));
@@ -167,17 +205,19 @@ function createThemeSnippet(overrides, scope, name) {
 		if (anchored.has(moved)) continue;
 		unrepresentable.push(`${moved}: ${resolveValue(overrides, scope, moved)}`);
 	}
-	const footer = unrepresentable.length === 0 ? "" : [
+	const notes = [];
+	if (base === null) notes.push(`// no manifest is registered for "${scope.theme}"; this call starts from the blank base.`);
+	if (unrepresentable.length > 0) notes.push("// createTheme() derives these rather than taking them as anchors, so they are not", "// in the call above. Ship the CSS export alongside it — that one is lossless.", ...unrepresentable.map((entry) => `// ${entry}`));
+	const footer = notes.length === 0 ? "" : [
 		"",
-		"// createTheme() derives these rather than taking them as anchors, so they are not",
-		"// in the call above. Ship the CSS export alongside it — that one is lossless.",
-		...unrepresentable.map((entry) => `// ${entry}`),
+		...notes,
 		""
 	].join("\n");
 	return [
 		"import { createTheme } from \"@cueplusplus/ui/theming\";",
+		...baseImport === null ? [] : [baseImport],
 		"",
-		`export const ${/^[A-Za-z_$][\w$]*$/.test(name) ? name : "theme"} = createTheme({`,
+		`export const ${exported} = createTheme({`,
 		...lines,
 		"});",
 		footer

package/dist/configurator/_overrides.d.ts

@@ -1,5 +1,6 @@
 import { ResolvedMode } from "../system/theme-provider.js";
-import { Density, ThemeName } from "@cueplusplus/tokens";
+import { Density } from "@cueplusplus/tokens";
+import { ThemeManifest, ThemeName } from "@cueplusplus/theme-base";
 //#region src/configurator/_overrides.d.ts
 /**
  * The override model behind the theme configurator: what a user may move, where
@@ -68,6 +69,18 @@ interface ThemeScope {
   theme: ThemeName;
   /** The mode as resolved — `"system"` never reaches here. */
   mode: ResolvedMode;
+  /**
+   * The active theme's manifest, or `null` for the blank base.
+   *
+   * Required, not optional, and that is the point. {@link baseValue} branches on
+   * `manifest === null` to mean *the blank base*; an absent field would take
+   * that branch by accident, and normalising `undefined` to `null` would make
+   * every caller that has not been updated resolve blank-base colours under a
+   * name that is not the blank base — silently, and only visibly wrong to
+   * somebody comparing swatches. A compile error naming the property is the
+   * right way for a stale caller to find out. Pass `useTheme().manifest`.
+   */
+  manifest: ThemeManifest | null;
 }
 /** Every override the user has made, ready to serialize. Treat as immutable. */
 interface ThemeOverrides {
@@ -117,15 +130,21 @@ declare function isSafeCssValue(value: string): boolean;
 /**
  * The value a token has before the user touches anything.
  *
- * Colours come from the preset for *this mode*; fonts from the preset's own
- * override, else the base stack; the multipliers are 1 by definition, because
- * what the panel edits is the multiplier and not the ladder underneath it.
+ * Everything a theme actually declares comes from `theme-base`'s `resolve()`,
+ * which is the one implementation of the layering rule — the theme's block for
+ * this mode, the theme's own font override under the base stack — so the panel
+ * and the runtime cannot disagree about what "shipped" means. A `null` manifest
+ * is the blank base, which resolves to the neutral ramp rather than to nothing:
+ * every scope answers, including one naming a theme no manifest was passed for.
+ * The multipliers are 1 by definition, because what the panel edits is the
+ * multiplier and not the ladder underneath it.
  *
- * @param scope - Theme and mode being edited.
+ * @param scope - Theme, mode and manifest being edited.
  * @param token - A bare token name or a `--cue-*` property.
  * @returns The shipped value, as a CSS string.
  * @example
- * baseValue({ theme: "terminal", mode: "dark" }, "accent"); // → "hsl(180 100% 50%)"
+ * baseValue({ theme: "terminal", mode: "dark", manifest: terminal }, "accent");
+ * // → "hsl(180 100% 50%)"
  */
 declare function baseValue(scope: ThemeScope, token: string): string;
 /**

package/dist/configurator/_overrides.js

@@ -1,5 +1,6 @@
-import { BASE_FONT_STACKS, DEFAULT_DENSITY_LEVEL, DENSITY_RADIUS_SCALE, THEME_COLOR_TOKENS, THEME_PRESETS } from "../theming/_presets.js";
-import { THEME_NAME_PATTERN, assertCssValue, serializeSystemModeAliases, serializeThemeBlock, tokenProperty } from "../theming/serialize.js";
+import { THEME_NAME_PATTERN as THEME_NAME_PATTERN$1, assertCssValue, serializeSystemModeAliases, serializeThemeBlock, tokenProperty } from "../theming/serialize.js";
+import { DEFAULT_DENSITY_LEVEL, DENSITY_RADIUS_SCALE, THEME_COLOR_TOKENS } from "../theming/create-theme.js";
+import { resolve } from "@cueplusplus/theme-base";
 //#region src/configurator/_overrides.ts
 /**
 * The override model behind the theme configurator: what a user may move, where
@@ -55,11 +56,10 @@ const OVERRIDE_BANNER = "@cueplusplus/ui — theme configurator overrides";
 /**
 * The unitless density multiplier each level publishes.
 *
-* A copy of `packages/tokens/src/density/*.tokens.json`, for the same reason
-* `theming/_presets.ts` copies the palettes: the tokens package emits CSS, and a
-* value this module has to *multiply* cannot be read out of a stylesheet.
-* `test/configurator/overrides.test.ts` re-reads the DTCG sources and fails on
-* the first number that has drifted.
+* A copy of `packages/tokens/src/density/*.tokens.json`: the tokens package
+* emits CSS, and a value this module has to *multiply* cannot be read out of a
+* stylesheet. `test/configurator/overrides.test.ts` re-reads the DTCG sources
+* and fails on the first number that has drifted.
 */
 const DENSITY_FACTOR = {
 	"ultra-compact": .85,
@@ -120,13 +120,21 @@ function tokenKind(token) {
 function scopeKey(scope) {
 	return `${scope.theme}/${scope.mode}`;
 }
-/** The inverse of {@link scopeKey}, rejecting anything that would not be safe in a selector. */
+/**
+* The inverse of {@link scopeKey}, rejecting anything that would not be safe in
+* a selector.
+*
+* A bare `{ theme, mode }` rather than a {@link ThemeScope}: a storage key
+* carries a *name*, and this module has no registry to look a manifest up in.
+* Both callers below want only the selector halves. A caller that needs the
+* manifest attaches it from the registry it holds.
+*/
 function parseScopeKey(key) {
 	const slash = key.lastIndexOf("/");
 	if (slash === -1) return null;
 	const theme = key.slice(0, slash);
 	const mode = key.slice(slash + 1);
-	if (!THEME_NAME_PATTERN.test(theme)) return null;
+	if (!THEME_NAME_PATTERN$1.test(theme)) return null;
 	if (mode !== "dark" && mode !== "light") return null;
 	return {
 		theme,
@@ -157,23 +165,28 @@ function isSafeCssValue(value) {
 /**
 * The value a token has before the user touches anything.
 *
-* Colours come from the preset for *this mode*; fonts from the preset's own
-* override, else the base stack; the multipliers are 1 by definition, because
-* what the panel edits is the multiplier and not the ladder underneath it.
+* Everything a theme actually declares comes from `theme-base`'s `resolve()`,
+* which is the one implementation of the layering rule — the theme's block for
+* this mode, the theme's own font override under the base stack — so the panel
+* and the runtime cannot disagree about what "shipped" means. A `null` manifest
+* is the blank base, which resolves to the neutral ramp rather than to nothing:
+* every scope answers, including one naming a theme no manifest was passed for.
+* The multipliers are 1 by definition, because what the panel edits is the
+* multiplier and not the ladder underneath it.
 *
-* @param scope - Theme and mode being edited.
+* @param scope - Theme, mode and manifest being edited.
 * @param token - A bare token name or a `--cue-*` property.
 * @returns The shipped value, as a CSS string.
 * @example
-* baseValue({ theme: "terminal", mode: "dark" }, "accent"); // → "hsl(180 100% 50%)"
+* baseValue({ theme: "terminal", mode: "dark", manifest: terminal }, "accent");
+* // → "hsl(180 100% 50%)"
 */
 function baseValue(scope, token) {
 	const property = tokenProperty(token);
 	const name = property.slice(6);
-	const preset = THEME_PRESETS[scope.theme];
 	switch (tokenKind(property)) {
-		case "color": return ((scope.mode === "light" ? preset?.light : preset?.dark) ?? preset?.dark)?.[name] ?? "";
-		case "font": return preset?.fonts[name] ?? BASE_FONT_STACKS[name] ?? "";
+		case "color": return resolve(scope.manifest, { mode: scope.mode }).colors[name] ?? "";
+		case "font": return resolve(scope.manifest, { mode: scope.mode }).fonts[name] ?? "";
 		case "scaled":
 		case "inline": return "1";
 		case "flat": return BASE_TRACKING_LABEL;

package/dist/configurator/configurator.js

@@ -56,11 +56,16 @@ const clamp = (value, min, max) => Math.min(max, Math.max(min, value));
 * <ThemeConfigurator position="docked-right" onChange={(tokens) => report(tokens)} />
 */
 function ThemeConfigurator({ position: positionProp, defaultPosition = "floating", onPositionChange, defaultCollapsed = false, storageKey = DEFAULT_CONFIGURATOR_STORAGE_KEY, onChange, zoomShortcuts = true, title = "Theme", className }) {
-	const { theme, resolvedMode } = useTheme();
+	const { theme, resolvedMode, manifest } = useTheme();
 	const scope = React.useMemo(() => ({
 		theme,
-		mode: resolvedMode
-	}), [theme, resolvedMode]);
+		mode: resolvedMode,
+		manifest
+	}), [
+		theme,
+		resolvedMode,
+		manifest
+	]);
 	const [snapshot, setSnapshot] = React.useState(() => {
 		const initial = defaultSnapshot();
 		return {