npm - @cueplusplus/ui - Versions diffs - 0.7.0 → 0.9.0 - Mend

@cueplusplus/ui 0.7.0 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (67) hide show

package/CHANGELOG.md +272 -0
package/README.md +49 -0
package/dist/chat/message-list.js +2 -1
package/dist/configurator/_export.d.ts +1 -1
package/dist/configurator/_export.js +53 -13
package/dist/configurator/_overrides.d.ts +25 -6
package/dist/configurator/_overrides.js +30 -17
package/dist/configurator/configurator.js +8 -3
package/dist/configurator/panel-sections.js +43 -13
package/dist/elements/command-palette.js +1 -1
package/dist/elements/flow-graph.js +2 -2
package/dist/elements/markdown.js +1 -1
package/dist/elements/surfaces.js +4 -3
package/dist/index.d.ts +5 -2
package/dist/index.js +2 -1
package/dist/instruments/_ledger-disclosure.js +103 -0
package/dist/instruments/_ledger.d.ts +21 -0
package/dist/instruments/_ledger.js +5 -0
package/dist/instruments/ledger.d.ts +112 -13
package/dist/instruments/ledger.js +128 -38
package/dist/midi/piano-keyboard.js +5 -1
package/dist/primitives/chip.d.ts +1 -1
package/dist/styles.css +23 -1
package/dist/system/density.d.ts +17 -8
package/dist/system/density.js +39 -16
package/dist/system/index.d.ts +5 -2
package/dist/system/index.js +2 -1
package/dist/system/overrides.d.ts +43 -0
package/dist/system/overrides.js +238 -0
package/dist/system/portal.d.ts +4 -2
package/dist/system/portal.js +34 -3
package/dist/system/prepaint.d.ts +58 -7
package/dist/system/prepaint.js +72 -20
package/dist/system/theme-provider.d.ts +133 -8
package/dist/system/theme-provider.js +203 -72
package/dist/system/theme-registry.d.ts +53 -0
package/dist/system/theme-registry.js +66 -0
package/dist/system/use-density.d.ts +13 -5
package/dist/system/use-density.js +142 -13
package/dist/system/use-theme.d.ts +5 -3
package/dist/system/use-theme.js +5 -3
package/dist/system/vocabulary.d.ts +15 -0
package/dist/system/vocabulary.js +111 -0
package/dist/theming/contrast.d.ts +2 -122
package/dist/theming/contrast.js +2 -194
package/dist/theming/create-theme.d.ts +37 -11
package/dist/theming/create-theme.js +54 -17
package/dist/theming/index.d.ts +3 -4
package/dist/theming/index.js +3 -4
package/dist/theming/serialize.d.ts +24 -11
package/dist/theming/serialize.js +16 -18
package/manifest/components/colors-section.json +2 -3
package/manifest/components/cue-portal-frame.json +1 -1
package/manifest/components/data-tree.json +1 -0
package/manifest/components/density.json +1 -1
package/manifest/components/export-dialog.json +0 -3
package/manifest/components/ledger.json +82 -7
package/manifest/components/preset-section.json +2 -3
package/manifest/components/shape-section.json +2 -3
package/manifest/components/theme-configurator.json +0 -3
package/manifest/components/theme-provider.json +24 -9
package/manifest/components/token-editor.json +0 -3
package/manifest/manifest.json +148 -27
package/manifest/tokens.json +121 -11
package/package.json +15 -6
package/dist/theming/_presets.d.ts +0 -11
package/dist/theming/_presets.js +0 -678

package/dist/system/overrides.js ADDED Viewed

@@ -0,0 +1,238 @@
+"use client";
+import { noteOnce, warnOnce } from "./vocabulary.js";
+import * as React from "react";
+import { THEME_NAME_PATTERN, resolve } from "@cueplusplus/theme-base";
+import { contrastReport } from "@cueplusplus/theme-base/contrast";
+//#region src/system/overrides.ts
+/**
+* `overrides` — the one theme edit an application may make without owning a
+* theme package.
+*
+* A theme is a package now, and the honest way to change one is to publish
+* another. But there is a real band of edits below that: one accent for a
+* customer's tenant, a font stack an app already loads, a rung that needs two
+* more pixels for a touch build. Making each of those a package would be a
+* build step for a value that changes per request, and the alternative every
+* application reaches for otherwise — a stray `<style>` with `!important` in it
+* — outranks the token layer everywhere at once and takes the density islands
+* and the portals down with it.
+*
+* So the edits are typed, and they land where the cascade already expects them:
+*
+* - **Colours and fonts are inline custom properties on the provider root.**
+*   Inline beats every stylesheet, needs no `!important`, is scoped to the
+*   subtree by inheritance, and — because a portal mounts on `<body>` and
+*   inherits nothing from its owner — is re-stamped onto the portal container
+*   through {@link OverridesContext}, exactly like `--cue-font-scale` already is.
+* - **Densities are one document-scoped `<style>`.** A rung is selected by
+*   attribute, not inherited, so it cannot be an inline declaration at all; and
+*   `useControlHeight`'s probe hangs off `document.body`, outside every provider
+*   root, so a subtree-scoped rule would leave the measurement and the paint
+*   disagreeing by exactly the override. See {@link overridesCss}.
+*
+* The dev pass measures the result: an override is a colour decision made
+* without the generator that would have checked it, so this file checks it
+* instead. See {@link reportOverrides}.
+*/
+/**
+* The prefix every token in this system is published under.
+*
+* Restated here rather than imported from `../theming`: that group reaches
+* `culori` and the whole generator, and `system/` is in the import graph of
+* every component in the package. One six-character constant is the cheaper
+* copy. `test/system/overrides.test.tsx` holds it to `CUE_TOKEN_PREFIX`.
+*/
+const PREFIX = "--cue-";
+/**
+* The already-flattened, referentially stable inline record the provider
+* publishes for portals.
+*
+* Flattened and stable both matter. `usePortalStamp()` builds a fresh object on
+* every render, so a `TokenOverrides` handed down raw would be a new dependency
+* on every render of every overlay, and every open popover would re-write its
+* container's custom properties for nothing. The provider computes this once,
+* keyed on the serialised prop and the resolved mode, and hands the *same*
+* object down until one of those actually moves.
+*
+* `null` means "nothing to stamp" — either no provider above, or a provider
+* whose overrides publish no colour or font for this mode.
+*
+* Internal: consumers get this through the provider, never directly.
+*/
+const OverridesContext = React.createContext(null);
+/**
+* The inline declarations for the resolved mode: colours and fonts.
+*
+* Only one colour block is ever emitted. The mode is a fact about the document
+* at this instant, and publishing both blocks would mean the dark edit sat as a
+* dead custom property under a light palette, waiting for somebody to `var()`
+* it by mistake.
+*
+* No validation of the *values* here, deliberately: these go through React's
+* `style` prop and `CSSStyleDeclaration.setProperty`, and the CSSOM drops a
+* declaration it cannot parse. A bad colour is a colour that does not apply,
+* not an injection — which is exactly the difference between this half of the
+* feature and {@link overridesCss}, where the text is written into a stylesheet
+* by hand and has to be guarded.
+*
+* @param overrides - The prop, or `undefined`.
+* @param mode - The mode after `"system"` has been resolved.
+* @returns Custom property name → value; empty when there is nothing to say.
+* @example
+* inlineOverrides({ colors: { light: { accent: "#b35900" } } }, "light");
+* // → { "--cue-accent": "#b35900" }
+*/
+function inlineOverrides(overrides, mode) {
+	const inline = {};
+	for (const [token, value] of Object.entries(overrides?.colors?.[mode] ?? {})) if (value !== void 0) inline[`${PREFIX}${token}`] = value;
+	const fonts = overrides?.fonts;
+	if (fonts?.sans !== void 0) inline[`${PREFIX}font-sans`] = fonts.sans;
+	if (fonts?.mono !== void 0) inline[`${PREFIX}font-mono`] = fonts.mono;
+	if (fonts?.display !== void 0) inline[`${PREFIX}font-display`] = fonts.display;
+	return inline;
+}
+/**
+* A value that can be written into a stylesheet without closing the rule.
+*
+* The inline half needs no such guard — the CSSOM parses each declaration on
+* its own — but this text is concatenated into a `<style>` by hand, so a value
+* carrying `;`, `}` or `<` would end the declaration, the block or the element
+* and let whatever follows be parsed as CSS. An override value can easily come
+* from a tenant record or a query string, so the check is not theoretical.
+*/
+const SAFE_VALUE = /^[^;{}<>\\]+$/;
+/**
+* The document-scoped stylesheet text for the density layer.
+*
+* **Why the selector says the attribute twice.** A rung a theme retunes ships
+* as `[data-theme="t"] [data-density="x"]` — specificity (0,2,0). An override
+* that has to beat the base rung *and* tie the theme's own has to reach (0,2,0)
+* as well, and the honest way to write that on a single element is to repeat
+* the attribute: no invented ancestor, no `!important`, no `:is()` trick whose
+* specificity depends on its longest argument. Tied on specificity, source
+* order decides — and the provider's element is appended to `<body>`, after
+* every stylesheet in `<head>`, so the override wins. The same arithmetic puts
+* it above the configurator's persisted snapshot, which writes bare
+* `[data-density="x"]` at (0,1,0) into `<head>`.
+*
+* **Why it is document-scoped rather than nested under the provider root.**
+* `useControlHeight()` measures `--cue-control-<size>` on a throwaway element
+* appended to `document.body`, which is outside `[data-cue-root]`. A rule
+* scoped under the root would leave that probe reading unoverridden geometry
+* while the control beside it painted the override, and every consumer of the
+* measured height — virtualised rows, canvas layout, the DMX grid — would be
+* off by exactly the override. The cost of the document scope is stated in
+* `ThemeProviderProps.overrides`: a nested provider's rung edits reach the
+* whole page, the same way a theme's own rung rules do.
+*
+* @param overrides - The prop, or `undefined`.
+* @returns One rule per rung, newline-separated; `""` when there is nothing to
+*   emit, which is the provider's signal to render no element at all.
+* @example
+* overridesCss({ densities: { compact: { "control-md": "1.75rem" } } });
+* // → '[data-density="compact"][data-density="compact"]{--cue-control-md:1.75rem}'
+*/
+function overridesCss(overrides) {
+	const rules = [];
+	for (const [rung, patch] of Object.entries(overrides?.densities ?? {})) {
+		if (!THEME_NAME_PATTERN.test(rung)) {
+			warnOnce(`overrides: density "${rung}" is not a usable rung name; its overrides are dropped`);
+			continue;
+		}
+		const declarations = [];
+		for (const [token, value] of Object.entries(patch ?? {})) {
+			if (value === void 0) continue;
+			if (!SAFE_VALUE.test(value)) {
+				warnOnce(`overrides: value ${JSON.stringify(value)} for "${token}" is not a CSS value`);
+				continue;
+			}
+			declarations.push(`${PREFIX}${token}:${value}`);
+		}
+		if (declarations.length === 0) continue;
+		rules.push(`[data-density="${rung}"][data-density="${rung}"]{${declarations.join(";")}}`);
+	}
+	return rules.join("\n");
+}
+/**
+* Measure the palette an override actually produces, and name what it broke.
+*
+* `createTheme()` hands back a contrast report because a generated palette that
+* nobody measured is a colour toy. An `overrides.colors` edit is the same
+* decision made *without* the generator — one hex, dropped over a theme whose
+* own build already cleared the eleven pairs — so it is measured here instead,
+* against the palette it is layered onto.
+*
+* **Only what the override is answerable for is reported.** The palette is
+* measured twice, once without the edit and once with it, and a pair is named
+* when the edit introduced its failure, lowered its ratio, or *named either of
+* its tokens*. Five of the ten themes this repository ships carry a **waived**
+* required failure — a pair their own build recorded as known-bad — and
+* reporting the overridden result flat would blame a tenant's accent for a pair
+* it never touched, under a message that begins with the word `overrides:`. A
+* report a reader learns to ignore is worse than no report. But a waiver covers
+* the ink the *theme* shipped: the moment an app writes one of the two tokens
+* itself, the pair is the app's, whichever way the ratio moved. See `caused()`.
+*
+* Failures `console.warn` and advisories `console.info`, matching the two tiers
+* `contrastReport()` itself keeps: a failure is what makes a screen unreadable,
+* an advisory is a ring nobody has been failed on yet.
+*
+* With no manifest registered for the active name the baseline is the blank
+* base, which is what `resolve(null, …)` returns and what an unregistered theme
+* can be measured against — the numbers are then the base's, not the palette
+* the document is painted in. The message still names the theme the document is
+* *stamped* with, because that is the screen the reader is looking at.
+*
+* Development only, and once per distinct message per process.
+*
+* @param manifest - The active theme's manifest, or `null` when unregistered.
+* @param mode - The mode after `"system"` has been resolved.
+* @param overrides - The prop, or `undefined`.
+* @param theme - The name on `data-theme`, for the message.
+*/
+function reportOverrides(manifest, mode, overrides, theme) {
+	if (process.env.NODE_ENV === "production") return;
+	const patch = overrides?.colors?.[mode];
+	if (patch === void 0 || Object.keys(patch).length === 0) return;
+	const base = resolve(manifest, { mode }).colors;
+	let before;
+	let after;
+	try {
+		before = new Map(contrastReport([{
+			mode,
+			tokens: base
+		}]).checks.map((check) => [check.id, check]));
+		after = contrastReport([{
+			mode,
+			tokens: {
+				...base,
+				...patch
+			}
+		}]);
+	} catch {
+		warnOnce(`overrides: a value in the ${mode} block is not a colour this can measure; the contrast pass was skipped`);
+		return;
+	}
+	/**
+	* A pair the edit is answerable for.
+	*
+	* Three of these clauses are about the *result* moving — newly measurable,
+	* newly failing, failing worse. The fourth is about authorship, and it is the
+	* one that took a review to find: an override that names either token of a
+	* pair has adopted that pair, even when the theme was already failing it and
+	* even when the edit improved the ratio without clearing the floor. Under
+	* `venu`, whose own build waived `accent-fg/accent` at 2.67, an app setting
+	* `accent-fg` to something that lands at 3.60 has made a colour decision of
+	* its own and is still under the 4.5 floor — and the theme's waiver covers
+	* the theme's ink, not the app's. Without the clause the report would go
+	* quiet on exactly the pair the app just took responsibility for.
+	*/
+	const caused = (check) => {
+		const was = before.get(check.id);
+		return was === void 0 || was.passes || check.ratio < was.ratio || check.foreground in patch || check.background in patch;
+	};
+	for (const check of after.failures) if (caused(check)) warnOnce(`overrides: ${check.id} at ${check.ratio.toFixed(2)}:1 fails its ${check.minimum} floor under theme "${theme}"`);
+	for (const check of after.advisories) if (caused(check)) noteOnce(`overrides: ${check.id} at ${check.ratio.toFixed(2)}:1 misses its ${check.minimum} advisory floor under theme "${theme}"`);
+}
+//#endregion
+export { OverridesContext, inlineOverrides, overridesCss, reportOverrides };

package/dist/system/portal.d.ts CHANGED Viewed

@@ -6,7 +6,8 @@ import * as React from "react";
  *
  * Returns a `container` element appended to `document.body` and stamped with
  * `data-theme` / `data-density` / `data-font` / `data-mode` (plus
- * `--cue-font-scale`) copied from the nearest provider and density island, and
+ * `--cue-font-scale` and any `ThemeProvider` `overrides` colour or font
+ * property) copied from the nearest provider and density island, and
  * with `data-cue-skin` / `data-cue-fidelity` when the caller sits inside an
  * `AgentSurface` island. The container is
  * `display: contents`, so it changes no layout and creates no containing block —
@@ -41,7 +42,8 @@ interface CuePortalFrameProps {
  *
  * Wraps `children` in a `display: contents` element carrying the same
  * `data-theme` / `data-density` / `data-font` / `data-mode` / `data-cue-skin` /
- * `data-cue-fidelity` stamp and `--cue-font-scale` as {@link useCuePortalProps}. Prefer the hook — a stamped container costs one
+ * `data-cue-fidelity` stamp, `--cue-font-scale` and `overrides` properties as
+ * {@link useCuePortalProps}. Prefer the hook — a stamped container costs one
  * element per overlay instead of one per render tree — and reach for this only
  * when the container prop is not available.
  *

package/dist/system/portal.js CHANGED Viewed

@@ -2,6 +2,7 @@
 import { useIsomorphicLayoutEffect } from "./use-isomorphic-layout-effect.js";
 import { AgentSkinContext } from "./agent-skin.js";
 import { DensityContext } from "./density.js";
+import { OverridesContext } from "./overrides.js";
 import { FontFamiliesContext, FontScaleContext, ThemeContext } from "./theme-provider.js";
 import * as React from "react";
 import { jsx } from "react/jsx-runtime";
@@ -19,13 +20,15 @@ const FONT_MONO_PROPERTY = "--cue-font-mono";
 * read the *body's* theme, which is exactly the bug this contract exists to
 * prevent. The same detachment is why `--cue-font-scale` travels here too: the
 * provider publishes it as an inline custom property, which a body-level portal
-* would otherwise never inherit.
+* would otherwise never inherit — and why the provider's `overrides` do, for
+* exactly the same reason and by the same route.
 */
 function usePortalStamp() {
 	const theme = React.useContext(ThemeContext);
 	const island = React.useContext(DensityContext);
 	const fontScale = React.useContext(FontScaleContext);
 	const fontFamilies = React.useContext(FontFamiliesContext);
+	const overrides = React.useContext(OverridesContext);
 	const skin = React.useContext(AgentSkinContext);
 	return {
 		theme: theme?.theme ?? DEFAULT_THEME,
@@ -34,6 +37,7 @@ function usePortalStamp() {
 		font: theme?.font ?? DEFAULT_FONT,
 		fontScale,
 		fontFamilies,
+		overrides,
 		skin: skin?.skin ?? null,
 		fidelity: skin?.fidelity ?? null
 	};
@@ -44,7 +48,8 @@ function usePortalStamp() {
 *
 * Returns a `container` element appended to `document.body` and stamped with
 * `data-theme` / `data-density` / `data-font` / `data-mode` (plus
-* `--cue-font-scale`) copied from the nearest provider and density island, and
+* `--cue-font-scale` and any `ThemeProvider` `overrides` colour or font
+* property) copied from the nearest provider and density island, and
 * with `data-cue-skin` / `data-cue-fidelity` when the caller sits inside an
 * `AgentSurface` island. The container is
 * `display: contents`, so it changes no layout and creates no containing block —
@@ -92,11 +97,29 @@ function useCuePortalProps() {
 		stamp.fontScale,
 		stamp.fontFamilies?.sans,
 		stamp.fontFamilies?.mono,
+		stamp.overrides,
 		stamp.skin,
 		stamp.fidelity
 	]);
 	return React.useMemo(() => container === null ? {} : { container }, [container]);
 }
+/**
+* The override property names last written to each container.
+*
+* A stamp is applied over the top of the previous one, and `style.setProperty`
+* only ever adds. So a key that *disappears* — the app switching to a mode
+* whose block names different tokens, or dropping the prop — would leave its
+* `--cue-*` on the container for the life of the overlay, with the in-tree
+* content already painting without it. This is the record of what to take off.
+*
+* A `WeakMap` keyed on the element rather than an attribute on it: the same
+* bookkeeping written as `data-cue-override-keys` would be one more
+* document-visible mutation on every write, a second place for the truth to
+* live, and a new `data-` attribute in a file whose whole contract is which
+* `data-` attributes a portal carries. Containers are removed with the overlay
+* and collected with it, which is what makes the weak reference the right one.
+*/
+const stampedOverrides = /* @__PURE__ */ new WeakMap();
 /** Write a stamp onto a live element (the imperative half of the contract). */
 function applyStamp(element, stamp) {
 	element.setAttribute("data-theme", stamp.theme);
@@ -107,10 +130,16 @@ function applyStamp(element, stamp) {
 	else element.setAttribute("data-cue-skin", stamp.skin);
 	if (stamp.fidelity === null) element.removeAttribute("data-cue-fidelity");
 	else element.setAttribute("data-cue-fidelity", stamp.fidelity);
+	const overrides = stamp.overrides ?? {};
+	for (const property of stampedOverrides.get(element) ?? []) if (!(property in overrides)) element.style.removeProperty(property);
 	if (stamp.fontScale === null) element.style.removeProperty(FONT_SCALE_PROPERTY);
 	else element.style.setProperty(FONT_SCALE_PROPERTY, String(stamp.fontScale));
 	setOptionalProperty(element, FONT_SANS_PROPERTY, stamp.fontFamilies?.sans);
 	setOptionalProperty(element, FONT_MONO_PROPERTY, stamp.fontFamilies?.mono);
+	for (const [property, value] of Object.entries(overrides)) element.style.setProperty(property, value);
+	const keys = Object.keys(overrides);
+	if (keys.length === 0) stampedOverrides.delete(element);
+	else stampedOverrides.set(element, keys);
 }
 function setOptionalProperty(element, property, value) {
 	if (value === void 0) element.style.removeProperty(property);
@@ -122,7 +151,8 @@ function setOptionalProperty(element, property, value) {
 *
 * Wraps `children` in a `display: contents` element carrying the same
 * `data-theme` / `data-density` / `data-font` / `data-mode` / `data-cue-skin` /
-* `data-cue-fidelity` stamp and `--cue-font-scale` as {@link useCuePortalProps}. Prefer the hook — a stamped container costs one
+* `data-cue-fidelity` stamp, `--cue-font-scale` and `overrides` properties as
+* {@link useCuePortalProps}. Prefer the hook — a stamped container costs one
 * element per overlay instead of one per render tree — and reach for this only
 * when the container prop is not available.
 *
@@ -136,6 +166,7 @@ function CuePortalFrame({ children, className, style }) {
 		...stamp.fontScale === null ? null : { [FONT_SCALE_PROPERTY]: stamp.fontScale },
 		...stamp.fontFamilies?.sans === void 0 ? null : { [FONT_SANS_PROPERTY]: stamp.fontFamilies.sans },
 		...stamp.fontFamilies?.mono === void 0 ? null : { [FONT_MONO_PROPERTY]: stamp.fontFamilies.mono },
+		...stamp.overrides,
 		...style
 	};
 	return /* @__PURE__ */ jsx("div", {

package/dist/system/prepaint.d.ts CHANGED Viewed

@@ -1,4 +1,4 @@
-import { Density, FontName, Mode, ThemeName } from "@cueplusplus/tokens";
+import { Density, FontName, Mode, ThemeManifest, ThemeName } from "@cueplusplus/theme-base";
 //#region src/system/prepaint.d.ts
 /** localStorage key the ThemeProvider and the pre-paint script share by default. */
 declare const DEFAULT_STORAGE_KEY = "cue-ui";
@@ -13,22 +13,49 @@ interface PersistedPreferences {
   /** Last font pairing the user picked. */
   font?: string;
 }
-/** Complete server-authoritative fallback stamped when storage is absent or ignored. */
+/**
+ * The server-authoritative fallback stamped when storage is absent or ignored.
+ *
+ * `theme` and `mode` are required because nothing else can supply them: the
+ * theme is the app's own decision and the mode has no per-theme preference to
+ * fall back to. `density` and `font` are optional on purpose — leave either out
+ * and the script opens on the rung or the pairing `defaults.theme` itself
+ * declares (§5's `densities.default` / `fontPairings.default`), which is
+ * exactly what `<ThemeProvider>` opens on when the consumer passes no `density`
+ * or `font`. Naming one here is therefore the same statement as passing the
+ * prop: it overrides the theme's preference for the first paint, and the
+ * provider must be given the matching prop or the two disagree by a frame.
+ */
 interface PrepaintDefaults {
   theme: ThemeName;
-  density: Density;
+  /** Initial density rung. Omitted, the theme's own `densities.default` decides. */
+  density?: Density;
   mode: Mode;
-  /** Initial document-wide font pairing. Defaults to the token package's system pairing. */
+  /** Initial document-wide font pairing. Omitted, the theme's own `fontPairings.default` decides. */
   font?: FontName;
 }
 /** Options form for apps whose server projection, not localStorage, owns first paint. */
 interface PrepaintOptions {
   /** localStorage key shared with ThemeProvider. */
   storageKey?: string;
-  /** Complete validated fallback triple. */
+  /** The validated fallback: `theme` and `mode` always, `density` and `font` only to override the theme's own. */
   defaults: PrepaintDefaults;
   /** Whether valid stored axes may override `defaults`. Defaults to `true`. */
   readStoredPreferences?: boolean;
+  /**
+   * The manifests this app registers, in the same order and of the same shape
+   * as `<ThemeProvider themes>`. The script inlines their names, and per theme
+   * the rungs and pairings that theme offers, so a stored preference is judged
+   * before paint by exactly the rule the provider applies after it.
+   *
+   * Omitted — and it is omitted by the positional overload, which cannot carry
+   * it — the script gets the empty-registry rule: any well-formed theme name is
+   * accepted, and density and font validate against the base axes alone. That
+   * is deliberate rather than lax. An app that registers nothing has whatever
+   * theme its stylesheet paints, and refusing the name it stored would repaint
+   * every returning visitor's first frame in a theme they did not choose.
+   */
+  themes?: readonly ThemeManifest[];
 }
 /**
  * Build the blocking inline script that stamps `data-theme`, `data-density`,
@@ -38,8 +65,32 @@ interface PrepaintOptions {
  * Render it as `<script dangerouslySetInnerHTML={{ __html: prepaintScript() }} />`
  * in `<head>`, above everything else. The output never contains `</script>` and
  * never throws: private-mode localStorage failures degrade to the dark-first
- * defaults (`cue` / `compact` / `system` / `dark`), which are also what bare
- * `:root` in `@cueplusplus/tokens/theme.css` already paints.
+ * defaults (`cue` / `compact` / `system` / `dark`). Two of those four are what
+ * bare `:root` already carries — `compact` geometry and the dark palette, from
+ * `@cueplusplus/theme-base/base.css` and the `@cueplusplus/tokens/axes.css` it
+ * imports. `cue` is not: since this release no stylesheet the library ships
+ * declares a `[data-theme="cue"]` block, so stamping that name paints the blank
+ * base unless the app imported `@cueplusplus/theme-cue/theme.css` itself. The
+ * script's job is to make the first frame agree with the first commit, and it
+ * still does — both are whatever the page's stylesheets say `cue` means.
+ *
+ * What the script *accepts* out of storage is decided by the same rule the
+ * provider applies a moment later. Pass the options form with `themes` — the
+ * array `<ThemeProvider themes>` is given — and the registered names are
+ * inlined, along with the rungs and pairings each theme offers, so a rung one
+ * theme adds is not accepted on first paint under a theme that does not have
+ * it. Pass nothing and the empty-registry rule applies: any well-formed theme
+ * name, and the base density and font axes. The positional overload below
+ * cannot carry a registry and always gets that rule.
+ *
+ * What it *stamps* for a visitor with nothing stored is decided the same way.
+ * The options form needs only `defaults.theme` and `defaults.mode`: leave
+ * `defaults.density` or `defaults.font` out and the script opens on the rung
+ * and the pairing that theme itself declares (§5's `densities.default` /
+ * `fontPairings.default`), which is precisely what `<ThemeProvider>` opens on
+ * when no `density` or `font` prop names one. Name either here and you are
+ * making the same statement the prop makes — so pass the matching prop, or the
+ * first paint and the first commit disagree by a frame.
  *
  * @param storageKey - localStorage key to read. Must match the `storageKey`
  *   passed to `<ThemeProvider>`. Defaults to {@link DEFAULT_STORAGE_KEY}.

package/dist/system/prepaint.js CHANGED Viewed

@@ -1,9 +1,20 @@
-import { DEFAULT_DENSITY, DEFAULT_FONT, DENSITIES, FONTS, MODES, THEMES } from "@cueplusplus/tokens";
+import { vocabulary } from "./vocabulary.js";
+import { DEFAULT_DENSITY, DEFAULT_FONT } from "@cueplusplus/tokens";
+import { MODES } from "@cueplusplus/theme-base";
 //#region src/system/prepaint.ts
 /**
 * Pre-paint stamping. Server-safe by design: no `"use client"`, no React, no
 * DOM access at module scope — `app/layout.tsx` calls `prepaintScript()` on the
 * server and inlines the result before hydration.
+*
+* That is also why the vocabulary comes from `./vocabulary` and never from
+* `./theme-registry`: the registry's React half carries a `"use client"`
+* directive, and a module reached through a client boundary arrives in a server
+* graph as a client *reference* rather than a function — calling one throws at
+* prerender, in the app's root layout, where nothing has rendered yet.
+* `test/system/server-safe.test.ts` pins the exact set of files this one
+* reaches, so the next import that would break the rule fails a test instead of
+* a deployment.
 */
 /** localStorage key the ThemeProvider and the pre-paint script share by default. */
 const DEFAULT_STORAGE_KEY = "cue-ui";
@@ -22,39 +33,80 @@ function prepaintScript(storageKeyOrOptions = DEFAULT_STORAGE_KEY, defaultTheme
 		defaults: {
 			theme: defaultTheme,
 			density: defaultDensity,
-			mode: "dark"
+			mode: "dark",
+			font: defaultFont
 		},
 		readStoredPreferences: true
 	} : storageKeyOrOptions;
-	if (options === null || typeof options !== "object" || options.defaults === void 0) throw new TypeError("prepaintScript options require a complete default triple");
+	if (options === null || typeof options !== "object" || options.defaults === void 0) throw new TypeError("prepaintScript options require a defaults object with theme and mode");
 	const defaults = options.defaults;
-	if (defaults.theme === void 0 || defaults.density === void 0 || defaults.mode === void 0) throw new TypeError("prepaintScript options require a complete default triple");
-	if (!THEMES.includes(defaults.theme)) throw new TypeError("prepaintScript defaults contain an invalid theme");
-	if (!DENSITIES.includes(defaults.density)) throw new TypeError("prepaintScript defaults contain an invalid density");
-	if (!MODES.includes(defaults.mode)) throw new TypeError("prepaintScript defaults contain an invalid mode");
-	if (defaults.font !== void 0 && !FONTS.includes(defaults.font)) throw new TypeError("prepaintScript defaults contain an invalid font");
+	if (defaults.theme === void 0 || defaults.mode === void 0) throw new TypeError("prepaintScript options require defaults.theme and defaults.mode");
+	const vocab = vocabulary(options.themes ?? []);
+	if (!vocab.acceptsTheme(defaults.theme)) throw new TypeError(vocab.themes === null ? `prepaintScript defaults.theme ${JSON.stringify(defaults.theme)} is not a valid theme name` : `prepaintScript defaults.theme ${JSON.stringify(defaults.theme)} is not a registered theme`);
+	if (defaults.density !== void 0 && !vocab.acceptsDensity(defaults.theme, defaults.density)) throw new TypeError(`prepaintScript defaults.density ${JSON.stringify(defaults.density)} is not offered by theme ${JSON.stringify(defaults.theme)}`);
+	if (!MODES.includes(defaults.mode)) throw new TypeError(`prepaintScript defaults.mode ${JSON.stringify(defaults.mode)} is not one of ${MODES.join(", ")}`);
+	if (defaults.font !== void 0 && !vocab.acceptsFont(defaults.theme, defaults.font)) throw new TypeError(`prepaintScript defaults.font ${JSON.stringify(defaults.font)} is not offered by theme ${JSON.stringify(defaults.theme)}`);
 	if (options.readStoredPreferences !== void 0 && typeof options.readStoredPreferences !== "boolean") throw new TypeError("prepaintScript readStoredPreferences must be boolean");
 	const storageKey = options.storageKey ?? "cue-ui";
 	if (typeof storageKey !== "string") throw new TypeError("prepaintScript storageKey must be a string");
 	const readStoredPreferences = options.readStoredPreferences ?? true;
 	const key = jsStringLiteral(storageKey);
 	const fallbackTheme = jsStringLiteral(defaults.theme);
-	const fallbackDensity = jsStringLiteral(defaults.density);
+	const fallbackDensity = jsStringLiteral(defaults.density ?? vocab.preferredDensity(defaults.theme));
 	const fallbackMode = jsStringLiteral(defaults.mode);
-	const fallbackFont = jsStringLiteral(defaults.font ?? defaultFont);
-	const themes = scriptSafe(JSON.stringify([...THEMES]));
-	const densities = scriptSafe(JSON.stringify([...DENSITIES]));
-	const modes = scriptSafe(JSON.stringify([...MODES]));
+	const fallbackFont = jsStringLiteral(defaults.font ?? vocab.preferredFont(defaults.theme));
+	const baseDensity = jsStringLiteral(DEFAULT_DENSITY);
+	const baseFont = jsStringLiteral(DEFAULT_FONT);
+	/**
+	* The registered names, or `null`.
+	*
+	* `null` tells the script "any well-formed name", which is the empty-registry
+	* rule (see `vocabulary`) and is what the positional overload — every app
+	* that has not migrated — gets. Anything else is the exact list the provider
+	* will validate against a moment later, inlined so the two cannot disagree.
+	*/
+	const themes = scriptSafe(JSON.stringify(vocab.themes));
 	/**
-	* The pairings, from the package that authors them, for the same reason.
+	* The other two axes, `supportsLight`, and each theme's own preference, **per theme**.
 	*
-	* This is also the axis where an unvalidated read is worst: a stale or
-	* hand-edited `font` would stamp an attribute the stylesheet has no block
-	* for, `--cue-font-sans` would keep the base stack, and the page would render
-	* in a family the picker says is not selected.
+	* Per theme, because a rung a theme adds is scoped by the cascade to that
+	* theme's `data-theme`; accepting it under another theme stamps an attribute
+	* no block will match, and the page renders at the rung it fell back from
+	* while the picker says otherwise. The keys are short (`d`, `f`, `l`, `p`,
+	* `q`) because this is inlined into every document this app serves, once per
+	* response, and with ten themes registered the long names would cost more
+	* bytes than the whole rest of the script.
+	*
+	* `p` and `q` are §5's `densities.default` / `fontPairings.default` — the
+	* rung and the pairing that theme prefers when nobody named one — read
+	* through `vocabulary()`, which is the same function `acceptedPreferences()`
+	* asks on the client. Two implementations of one rule, one of them written
+	* out as a string of JavaScript, is exactly the asymmetry the round-trip
+	* tests exist to catch; inlining the *answers* rather than re-deriving them
+	* is what makes the two sides agree by construction.
+	*
+	* They are omitted when they equal the base default, which is what every one
+	* of the ten shipped presets does — none of them declares either. The final
+	* clause already ends at the base literal, so an entry that repeats it is
+	* bytes in every response that change no answer. `a.p&&…` below is what
+	* reads an absent key as "no opinion".
+	*
+	* With nothing registered there is one entry under the empty key: the base
+	* ladder, the base pairings, and a light block, which the blank base has.
 	*/
-	const pairings = scriptSafe(JSON.stringify([...FONTS]));
-	return `!function(){try{var k=${key},e=document.documentElement,s=null;` + (readStoredPreferences ? "try{var r=localStorage.getItem(k);s=r?JSON.parse(r):null}catch(_){}" : "") + `s=s&&typeof s=="object"?s:{};var t=${themes}.indexOf(s.theme)>-1?s.theme:${fallbackTheme};var d=${densities}.indexOf(s.density)>-1?s.density:${fallbackDensity};var f=${pairings}.indexOf(s.font)>-1?s.font:${fallbackFont};var m=${modes}.indexOf(s.mode)>-1?s.mode:${fallbackMode};e.setAttribute("data-theme",t);e.setAttribute("data-density",d);e.setAttribute("data-font",f);e.setAttribute("data-mode",m);e.style.colorScheme=m==="system"?"light dark":m}catch(_){}}()`;
+	const axes = scriptSafe(JSON.stringify(Object.fromEntries((vocab.themes ?? [null]).map((name) => {
+		const preferredDensity = vocab.preferredDensity(name);
+		const preferredFont = vocab.preferredFont(name);
+		return [name ?? "", {
+			d: vocab.densitiesFor(name),
+			f: vocab.fontsFor(name),
+			l: vocab.supportsLight(name),
+			...preferredDensity === DEFAULT_DENSITY ? {} : { p: preferredDensity },
+			...preferredFont === DEFAULT_FONT ? {} : { q: preferredFont }
+		}];
+	}))));
+	const modes = scriptSafe(JSON.stringify([...MODES]));
+	return `!function(){try{var k=${key},e=document.documentElement,s=null;` + (readStoredPreferences ? "try{var r=localStorage.getItem(k);s=r?JSON.parse(r):null}catch(_){}" : "") + `s=s&&typeof s=="object"?s:{};var T=${themes},A=${axes},P=/^[a-z][a-z0-9-]*$/i;var t=T?(T.indexOf(s.theme)>-1?s.theme:${fallbackTheme}):(typeof s.theme=="string"&&P.test(s.theme)?s.theme:${fallbackTheme});var a=A[T?t:""]||A[""]||{d:[],f:[]};var d=a.d.indexOf(s.density)>-1?s.density:(a.d.indexOf(${fallbackDensity})>-1?${fallbackDensity}:(a.p&&a.d.indexOf(a.p)>-1?a.p:${baseDensity}));var f=a.f.indexOf(s.font)>-1?s.font:(a.f.indexOf(${fallbackFont})>-1?${fallbackFont}:(a.q&&a.f.indexOf(a.q)>-1?a.q:${baseFont}));var m=${modes}.indexOf(s.mode)>-1?s.mode:${fallbackMode};e.setAttribute("data-theme",t);e.setAttribute("data-density",d);e.setAttribute("data-font",f);e.setAttribute("data-mode",m);e.style.colorScheme=a.l===false?"dark":(m==="system"?"light dark":m)}catch(_){}}()`;
 }
 //#endregion
 export { DEFAULT_STORAGE_KEY, prepaintScript };