@cueplusplus/ui 0.1.0

package/dist/configurator/_export.d.ts

@@ -0,0 +1,78 @@
+import { ThemeOverrides, ThemeScope } from "./_overrides.js";
+//#region src/configurator/_export.d.ts
+/**
+ * The four things a configured theme can leave the browser as.
+ *
+ * A panel that only changes the page in front of you is a demo. These are what
+ * make it a tool: the stylesheet you paste, the token file your build reads, the
+ * generator call you check in, and the registry item someone else installs. All
+ * four are derived from the same `ThemeOverrides` value the panel is applying —
+ * the CSS one is *literally* the applied stylesheet — so an export can never
+ * describe a theme the page is not already wearing.
+ *
+ * Two of the four are lossy in a way worth stating out loud:
+ *
+ * - `createTheme()` takes **anchors**, not tokens. Move the accent and the call
+ *   reproduces it exactly; move `--cue-border` and there is no anchor to put it
+ *   in, because borders are derived from the ground. Rather than drop those
+ *   quietly the snippet lists them in a trailing comment and points at the CSS
+ *   export, which is lossless by construction.
+ * - The DTCG file speaks the tokens package's vocabulary, which is not quite the
+ *   CSS one: `--cue-density` is authored as `density-factor`, and
+ *   `--cue-font-scale` has no source token at all (the provider publishes it
+ *   inline, per render). The first is renamed, the second is omitted.
+ *
+ * @internal Not part of the public API.
+ */
+/** Which export a format id refers to. */
+type ExportFormatId = "css" | "dtcg" | "create-theme" | "registry";
+/** One export: what it is, what to call the file, and the text itself. */
+interface ThemeExport {
+  /** Stable id, used as the tab value. */
+  id: ExportFormatId;
+  /** Tab label. */
+  label: string;
+  /** Suggested download filename. */
+  filename: string;
+  /** MIME type for the download. */
+  mediaType: string;
+  /** One line saying what a reader does with it. */
+  description: string;
+  /** The exported text. */
+  text: string;
+}
+interface BuildExportsOptions {
+  /** The overrides to export. */
+  overrides: ThemeOverrides;
+  /** The theme and mode the panel is editing. */
+  scope: ThemeScope;
+  /** Name for the generated theme. Falls back to `"<preset>-custom"` when unusable. */
+  name?: string;
+}
+/**
+ * The name to put on a generated theme.
+ *
+ * The name lands inside `[data-theme="…"]`, a filename and a registry id, so
+ * anything that is not a CSS identifier is refused outright rather than escaped
+ * — and refusal means falling back to a name that always works, not throwing at
+ * a user who is halfway through typing one.
+ *
+ * @param scope - The theme being edited, used for the fallback.
+ * @param name - What the user typed, if anything.
+ * @returns A usable CSS identifier.
+ * @example
+ * exportName({ theme: "terminal", mode: "dark" }); // → "terminal-custom"
+ */
+declare function exportName(scope: ThemeScope, name?: string): string;
+/**
+ * The four exports for the current state of the panel.
+ *
+ * @param options - The overrides, the scope they were made in, and a name.
+ * @returns One entry per format, in the order the dialog shows them.
+ * @example
+ * const [css] = buildExports({ overrides, scope, name: "acme" });
+ * await navigator.clipboard.writeText(css.text);
+ */
+declare function buildExports(options: BuildExportsOptions): ThemeExport[];
+//#endregion
+export { BuildExportsOptions, ExportFormatId, ThemeExport, buildExports, exportName };

package/dist/configurator/_export.js

@@ -0,0 +1,261 @@
+import { THEME_NAME_PATTERN, tokenProperty } from "../theming/serialize.js";
+import { COLOR_TOKENS, FONT_TOKENS, configuratorCss, isOverridden, resolveValue, scopeKey, tokenKind } from "./_overrides.js";
+//#region src/configurator/_export.ts
+/** The anchors `ThemeAnchors` exposes at the top level, and the token each maps to. */
+const DIRECT_ANCHORS = [
+	["bg", "bg"],
+	["fg", "fg"],
+	["accent", "accent"]
+];
+/** The surface ladder, as `ThemeAnchors.surfaces` spells it. */
+const SURFACE_ANCHORS = [
+	"sunken",
+	"surface-1",
+	"surface-2",
+	"surface-3"
+];
+/** The status tones, as `ThemeAnchors.status` spells them. */
+const STATUS_ANCHORS = [
+	"ok",
+	"busy",
+	"warn",
+	"danger",
+	"info"
+];
+/** `--cue-font-mono` → the `fonts.mono` key `ThemeAnchors` uses. */
+const FONT_ANCHORS = {
+	"font-sans": "sans",
+	"font-mono": "mono",
+	"font-display": "display"
+};
+/** The DTCG source key a token is authored under, where it differs from the CSS name. */
+const DTCG_ALIASES = { density: "density-factor" };
+/**
+* The name to put on a generated theme.
+*
+* The name lands inside `[data-theme="…"]`, a filename and a registry id, so
+* anything that is not a CSS identifier is refused outright rather than escaped
+* — and refusal means falling back to a name that always works, not throwing at
+* a user who is halfway through typing one.
+*
+* @param scope - The theme being edited, used for the fallback.
+* @param name - What the user typed, if anything.
+* @returns A usable CSS identifier.
+* @example
+* exportName({ theme: "terminal", mode: "dark" }); // → "terminal-custom"
+*/
+function exportName(scope, name) {
+	const proposed = name?.trim() ?? "";
+	return THEME_NAME_PATTERN.test(proposed) ? proposed : `${scope.theme}-custom`;
+}
+/** 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. */
+function bothModes(scope) {
+	return [{
+		theme: scope.theme,
+		mode: "dark"
+	}, {
+		theme: scope.theme,
+		mode: "light"
+	}];
+}
+/** The `--cue-*` properties of one kind that the user has actually moved. */
+function movedTokens(overrides, scope, kind) {
+	const scoped = overrides.themes[scopeKey(scope)] ?? {};
+	const candidates = kind === "color" || kind === "font" ? scoped : overrides.global;
+	return Object.keys(candidates).filter((property) => tokenKind(property) === 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 —
+* `color` for the palette, `type` for the stacks, `density` for the multipliers
+* — and appear only when they carry something.
+*/
+function dtcgFile(overrides, scope, name) {
+	const color = { $type: "color" };
+	for (const token of COLOR_TOKENS) color[token] = { $value: resolveValue(overrides, scope, token) };
+	const file = {
+		$description: `Theme: ${name} — exported from the CUE++ theme configurator, based on ${scope.theme} (${scope.mode}).`,
+		color
+	};
+	const fonts = movedTokens(overrides, scope, "font");
+	const tracking = movedTokens(overrides, scope, "flat");
+	if (fonts.length > 0 || tracking.length > 0) {
+		const type = { $type: "fontFamily" };
+		for (const property of fonts) type[property.slice(6)] = { $value: resolveValue(overrides, scope, property) };
+		for (const property of tracking) type[property.slice(6)] = {
+			$type: "dimension",
+			$value: resolveValue(overrides, scope, property)
+		};
+		file["type"] = type;
+	}
+	const multipliers = movedTokens(overrides, scope, "scaled");
+	if (multipliers.length > 0) {
+		const density = {
+			$description: "Multipliers only. They belong to the density axis, so they cross with every level rather than replacing one.",
+			$type: "dimension"
+		};
+		for (const property of multipliers) {
+			const bare = property.slice(6);
+			density[DTCG_ALIASES[bare] ?? bare] = {
+				$type: "number",
+				$value: Number(resolveValue(overrides, scope, property))
+			};
+		}
+		file["density"] = density;
+	}
+	return json(file);
+}
+/**
+* A string literal a human would have typed.
+*
+* Single quotes when the value carries double ones — a font stack is
+* `"Berkeley Mono", monospace`, and `"\"Berkeley Mono\", monospace"` is a thing
+* nobody writes on purpose.
+*/
+function quote(value) {
+	return value.includes("\"") && !value.includes("'") && !value.includes("\\") ? `'${value}'` : JSON.stringify(value);
+}
+/** 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)},`;
+}
+/**
+* ③ The `createTheme()` call.
+*
+* Anchors in, stylesheet out — the same two lines a human would have written,
+* with whatever the user moved filled in. Tokens the generator derives rather
+* than accepts are listed underneath instead of being silently dropped, because
+* 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 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));
+	if (surfaces.length > 0) {
+		lines.push("  surfaces: {");
+		for (const token of surfaces) lines.push(property(token, resolveValue(overrides, scope, token), "    "));
+		lines.push("  },");
+	}
+	const statuses = STATUS_ANCHORS.filter((token) => isOverridden(overrides, scope, token));
+	if (statuses.length > 0) {
+		lines.push("  status: {");
+		for (const token of statuses) lines.push(property(token, resolveValue(overrides, scope, token), "    "));
+		lines.push("  },");
+	}
+	const fonts = FONT_TOKENS.filter((token) => isOverridden(overrides, scope, token));
+	if (fonts.length > 0) {
+		lines.push("  fonts: {");
+		for (const token of fonts) lines.push(property(FONT_ANCHORS[token], resolveValue(overrides, scope, token), "    "));
+		lines.push("  },");
+	}
+	if (isOverridden(overrides, scope, "radius-scale")) lines.push(`  radiusScale: ${Number(resolveValue(overrides, scope, "radius-scale"))},`);
+	const anchored = new Set([
+		...DIRECT_ANCHORS.map(([, token]) => token),
+		...SURFACE_ANCHORS,
+		...STATUS_ANCHORS,
+		...FONT_TOKENS,
+		"radius-scale"
+	].map(tokenProperty));
+	for (const moved of [...Object.keys(overrides.themes[scopeKey(scope)] ?? {}), ...Object.keys(overrides.global)]) {
+		if (anchored.has(moved)) continue;
+		unrepresentable.push(`${moved}: ${resolveValue(overrides, scope, moved)}`);
+	}
+	const footer = unrepresentable.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}`),
+		""
+	].join("\n");
+	return [
+		"import { createTheme } from \"@cueplusplus/ui/theming\";",
+		"",
+		`export const ${/^[A-Za-z_$][\w$]*$/.test(name) ? name : "theme"} = createTheme({`,
+		...lines,
+		"});",
+		footer
+	].join("\n");
+}
+/**
+* ④ The shadcn registry item.
+*
+* `cssVars` is keyed the way shadcn keys it — no leading dashes, and a `theme`
+* bucket for the variables that do not belong to a mode. Both palettes are
+* written in full, including the one the user was not looking at, because an
+* installer has no way to ask.
+*/
+function registryItem(overrides, scope, name) {
+	const strip = (property) => property.replace(/^--/, "");
+	const palette = (mode) => Object.fromEntries(COLOR_TOKENS.map((token) => [strip(tokenProperty(token)), resolveValue(overrides, mode, token)]));
+	const [dark, light] = bothModes(scope);
+	const shared = {};
+	for (const moved of [...FONT_TOKENS.map(tokenProperty), ...Object.keys(overrides.global)]) {
+		if (!isOverridden(overrides, scope, moved)) continue;
+		shared[strip(moved)] = resolveValue(overrides, scope, moved);
+	}
+	return json({
+		$schema: "https://ui.shadcn.com/schema/registry-item.json",
+		name,
+		type: "registry:theme",
+		cssVars: {
+			...Object.keys(shared).length === 0 ? null : { theme: shared },
+			light: palette(light),
+			dark: palette(dark)
+		}
+	});
+}
+/**
+* The four exports for the current state of the panel.
+*
+* @param options - The overrides, the scope they were made in, and a name.
+* @returns One entry per format, in the order the dialog shows them.
+* @example
+* const [css] = buildExports({ overrides, scope, name: "acme" });
+* await navigator.clipboard.writeText(css.text);
+*/
+function buildExports(options) {
+	const { overrides, scope } = options;
+	const name = exportName(scope, options.name);
+	return [
+		{
+			id: "css",
+			label: "CSS",
+			filename: `${name}.css`,
+			mediaType: "text/css",
+			description: "The override stylesheet, exactly as the panel is applying it.",
+			text: configuratorCss(overrides)
+		},
+		{
+			id: "dtcg",
+			label: "Tokens",
+			filename: `${name}.tokens.json`,
+			mediaType: "application/json",
+			description: "A DTCG token file, in the shape packages/tokens builds from.",
+			text: dtcgFile(overrides, scope, name)
+		},
+		{
+			id: "create-theme",
+			label: "createTheme()",
+			filename: `${name}.theme.ts`,
+			mediaType: "text/plain",
+			description: "The generator call that reproduces the anchors you moved.",
+			text: createThemeSnippet(overrides, scope, name)
+		},
+		{
+			id: "registry",
+			label: "Registry",
+			filename: `${name}.registry.json`,
+			mediaType: "application/json",
+			description: "A shadcn registry:theme item, both modes resolved.",
+			text: registryItem(overrides, scope, name)
+		}
+	];
+}
+//#endregion
+export { buildExports, exportName };

package/dist/configurator/_glyphs.js

@@ -0,0 +1,92 @@
+import "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/configurator/_glyphs.tsx
+/**
+* The configurator's own glyphs.
+*
+* Drawn inline, like every other group's, so a panel that edits the design
+* system does not put an icon package on its render path. `currentColor`
+* throughout — the tone comes from the button underneath.
+*
+* @internal Not part of the public API.
+*/
+/** A counter-clockwise arrow: put this one token back. */
+function ResetGlyph(props) {
+	return /* @__PURE__ */ jsxs("svg", {
+		viewBox: "0 0 16 16",
+		fill: "none",
+		stroke: "currentColor",
+		strokeWidth: "1.5",
+		strokeLinecap: "round",
+		strokeLinejoin: "round",
+		"aria-hidden": "true",
+		...props,
+		children: [/* @__PURE__ */ jsx("path", { d: "M3 8a5 5 0 1 0 1.6-3.7" }), /* @__PURE__ */ jsx("path", { d: "M3 3v3.2h3.2" })]
+	});
+}
+/** Two short rules: the grab surface of the title bar. */
+function GripGlyph(props) {
+	return /* @__PURE__ */ jsxs("svg", {
+		viewBox: "0 0 16 16",
+		fill: "none",
+		stroke: "currentColor",
+		strokeWidth: "1.5",
+		strokeLinecap: "round",
+		"aria-hidden": "true",
+		...props,
+		children: [/* @__PURE__ */ jsx("path", { d: "M3 6h10" }), /* @__PURE__ */ jsx("path", { d: "M3 10h10" })]
+	});
+}
+/** A frame with a rail down its right edge: dock the panel. */
+function DockGlyph(props) {
+	return /* @__PURE__ */ jsxs("svg", {
+		viewBox: "0 0 16 16",
+		fill: "none",
+		stroke: "currentColor",
+		strokeWidth: "1.5",
+		strokeLinejoin: "round",
+		"aria-hidden": "true",
+		...props,
+		children: [/* @__PURE__ */ jsx("rect", {
+			x: "2",
+			y: "3",
+			width: "12",
+			height: "10",
+			rx: "1.5"
+		}), /* @__PURE__ */ jsx("path", { d: "M10 3v10" })]
+	});
+}
+/** A chevron, rotated by the caller to point at the state it will move to. */
+function ChevronGlyph(props) {
+	return /* @__PURE__ */ jsx("svg", {
+		viewBox: "0 0 16 16",
+		fill: "none",
+		stroke: "currentColor",
+		strokeWidth: "1.5",
+		strokeLinecap: "round",
+		strokeLinejoin: "round",
+		"aria-hidden": "true",
+		...props,
+		children: /* @__PURE__ */ jsx("path", { d: "M4 6.5 8 10.5l4-4" })
+	});
+}
+/** An arrow into a tray: save this export to a file. */
+function DownloadGlyph(props) {
+	return /* @__PURE__ */ jsxs("svg", {
+		viewBox: "0 0 16 16",
+		fill: "none",
+		stroke: "currentColor",
+		strokeWidth: "1.5",
+		strokeLinecap: "round",
+		strokeLinejoin: "round",
+		"aria-hidden": "true",
+		...props,
+		children: [
+			/* @__PURE__ */ jsx("path", { d: "M8 2.5v7" }),
+			/* @__PURE__ */ jsx("path", { d: "M5 7l3 3 3-3" }),
+			/* @__PURE__ */ jsx("path", { d: "M3 12.5h10" })
+		]
+	});
+}
+//#endregion
+export { ChevronGlyph, DockGlyph, DownloadGlyph, GripGlyph, ResetGlyph };

package/dist/configurator/_overrides.d.ts

@@ -0,0 +1,247 @@
+import { ResolvedMode } from "../system/theme-provider.js";
+import { Density, ThemeName } from "@cueplusplus/tokens";
+//#region src/configurator/_overrides.d.ts
+/**
+ * The override model behind the theme configurator: what a user may move, where
+ * the declaration has to land for it to win, and how the whole thing survives a
+ * reload.
+ *
+ * Everything here is a pure function of an immutable `ThemeOverrides` value,
+ * apart from the three functions at the bottom that talk to the document and to
+ * `localStorage`. That split is deliberate — the panel is a view over this
+ * model, the export dialog is a second view over the same model, and neither is
+ * allowed a private opinion about what the tokens are.
+ *
+ * ## Why the scoping is this fussy
+ *
+ * The token layer declares its values under *attribute* selectors on two
+ * disjoint axes (`[data-theme]` for colour, `[data-density]` for geometry), and
+ * both axes are re-declared at every element that carries the attribute — the
+ * `<html>` element, the provider root, a `<Density>` island, a portal container.
+ * An override is therefore not "set the variable on `:root`": that loses in
+ * three separate ways.
+ *
+ * - A colour written under a bare `[data-theme="x"]` (0,1,0) is outranked by the
+ *   shipped `[data-theme="x"][data-mode="light"]` block (0,2,0), so the moment
+ *   the user switches to light the override vanishes. Colours are therefore
+ *   written **crossed with the mode**, which is also honest: a theme's two modes
+ *   are two palettes, and editing one should not silently edit the other.
+ * - A geometry multiplier written flat outranks the density block that set it,
+ *   freezing `ultra-compact`'s 0.75 radius scale at 1 — the same trap
+ *   `createTheme()` documents. Multipliers are therefore **crossed with the
+ *   density ladder**, one rule per level, with the level's own value folded in.
+ * - `--cue-font-scale` is published by `<ThemeProvider>` as an *inline* custom
+ *   property, and no stylesheet outranks an inline declaration. It is the one
+ *   token here that needs `!important`, and it gets its own rule so that the
+ *   flag never spreads to anything that does not need it.
+ *
+ * @internal Not part of the public API; `./configurator` re-exports what a host
+ *   app needs.
+ */
+/** The one style element the configurator writes into. */
+declare const OVERRIDE_STYLE_ID = "cue-configurator-overrides";
+/** Default `localStorage` key for the persisted snapshot. */
+declare const DEFAULT_CONFIGURATOR_STORAGE_KEY = "cue-configurator";
+/**
+ * Schema version of the persisted snapshot.
+ *
+ * A blob from another version is discarded rather than migrated: the payload is
+ * a design preference a user can rebuild in a minute, and a wrong migration
+ * would paint a page with values nobody chose.
+ */
+declare const CONFIGURATOR_VERSION = 1;
+/** Banner printed at the top of the applied — and exported — stylesheet. */
+declare const OVERRIDE_BANNER = "@cueplusplus/ui — theme configurator overrides";
+/** The authored label tracking, and the value the "reset" arrow returns to. */
+declare const BASE_TRACKING_LABEL = "0.12em";
+/** The colour tokens the panel edits — the same list a theme block declares. */
+declare const COLOR_TOKENS: readonly ["bg", "sunken", "surface-1", "surface-2", "surface-3", "fg", "fg-muted", "fg-subtle", "border", "border-strong", "border-overlay", "accent", "accent-hover", "accent-fg", "ok", "busy", "warn", "danger", "info", "selection", "focus", "data-ground", "scrim"];
+/** The type stacks the panel edits. Mode-independent: a typeface is not a palette. */
+declare const FONT_TOKENS: readonly ["font-sans", "font-mono", "font-display"];
+/** Every token the configurator is allowed to write, as `--cue-*` properties, in contract order. */
+declare const MANAGED_TOKENS: readonly string[];
+/** Where in the cascade a token's declaration has to go. */
+type TokenKind = "color" | "font" | "scaled" | "flat" | "inline";
+/** A theme and the mode being looked at: the scope a colour override belongs to. */
+interface ThemeScope {
+  /** The active preset. */
+  theme: ThemeName;
+  /** The mode as resolved — `"system"` never reaches here. */
+  mode: ResolvedMode;
+}
+/** Every override the user has made, ready to serialize. Treat as immutable. */
+interface ThemeOverrides {
+  /** Theme-scoped declarations, keyed by `"<theme>/<mode>"` then by `--cue-*` property. */
+  themes: Record<string, Record<string, string>>;
+  /** Axis-free declarations, keyed by `--cue-*` property. */
+  global: Record<string, string>;
+}
+/** The nothing-has-moved state. Frozen: it is shared by every caller. */
+declare const EMPTY_OVERRIDES: ThemeOverrides;
+/** Where the panel is sitting. */
+type ConfiguratorPosition = "floating" | "docked-right";
+/** Everything the configurator persists between visits. */
+interface ConfiguratorSnapshot {
+  /** {@link CONFIGURATOR_VERSION} at the time of writing. */
+  version: number;
+  /** The overrides themselves. */
+  overrides: ThemeOverrides;
+  /** Root zoom valve position. */
+  zoom: number;
+  /** Panel placement and whether it is furled to its title bar. */
+  panel: {
+    position: ConfiguratorPosition;
+    x: number;
+    y: number;
+    collapsed: boolean;
+  };
+}
+/** Which of the five buckets a token belongs to, or `null` if it is not ours to write. */
+declare function tokenKind(token: string): TokenKind | null;
+/** The key a theme+mode pair is stored under. */
+declare function scopeKey(scope: ThemeScope): string;
+/**
+ * Whether a value can be printed into a declaration without escaping it.
+ *
+ * Colours arrive from the picker already re-formatted, but a font stack is free
+ * text a user typed, and it ends up inside a stylesheet. This is the same check
+ * `theming/serialize.ts` makes — asked as a question instead of thrown as an
+ * error, so a field can mark itself invalid while the user is still typing.
+ *
+ * @param value - The proposed declaration value.
+ * @returns `true` when it stays inside its declaration.
+ * @example
+ * isSafeCssValue("Iosevka, monospace"); // → true
+ */
+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.
+ *
+ * @param scope - Theme and mode 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%)"
+ */
+declare function baseValue(scope: ThemeScope, token: string): string;
+/**
+ * Move a token, returning a new state.
+ *
+ * Setting a token back to the value the preset ships is a *reset*, not an
+ * override — otherwise "I put it back" would still export a declaration and the
+ * user would carry a no-op forever.
+ *
+ * @param overrides - Current state. Never mutated.
+ * @param scope - Theme and mode being edited.
+ * @param token - A bare token name or a `--cue-*` property.
+ * @param value - The new CSS value.
+ * @returns The new state.
+ * @throws TypeError if the token is not one the configurator manages, or the
+ *   value could break out of its declaration.
+ * @example
+ * setOverride(overrides, { theme: "terminal", mode: "dark" }, "accent", "#ff8800");
+ */
+declare function setOverride(overrides: ThemeOverrides, scope: ThemeScope, token: string, value: string): ThemeOverrides;
+/**
+ * Put a token back to its shipped value, returning a new state.
+ *
+ * @param overrides - Current state. Never mutated.
+ * @param scope - Theme and mode being edited.
+ * @param token - A bare token name or a `--cue-*` property.
+ * @returns The new state.
+ * @example
+ * clearOverride(overrides, scope, "--cue-accent");
+ */
+declare function clearOverride(overrides: ThemeOverrides, scope: ThemeScope, token: string): ThemeOverrides;
+/** Whether a token currently carries an override in this scope. */
+declare function isOverridden(overrides: ThemeOverrides, scope: ThemeScope, token: string): boolean;
+/**
+ * How many declarations the user has made.
+ *
+ * Counted as declarations rather than as decisions: a font family is one choice
+ * that produces two declarations, one per mode, and the number in the panel is
+ * the number that will appear in the export.
+ */
+declare function overrideCount(overrides: ThemeOverrides): number;
+/** The value a token has right now: the override if there is one, else the shipped value. */
+declare function resolveValue(overrides: ThemeOverrides, scope: ThemeScope, token: string): string;
+/**
+ * Every token the configurator manages, resolved for one scope.
+ *
+ * This is what `onChange` hands a host app and what the registry export writes:
+ * a complete picture, not a diff, so a consumer never has to know which preset
+ * the values came from.
+ *
+ * @param overrides - Current state.
+ * @param scope - Theme and mode to resolve for.
+ * @returns `--cue-*` property → CSS value.
+ */
+declare function resolvedTokens(overrides: ThemeOverrides, scope: ThemeScope): Record<string, string>;
+interface SerializeOverrideOptions {
+  /** Text of the leading `/*! … *\/` banner. Omit for a bare stylesheet. */
+  banner?: string;
+}
+/**
+ * Print the overrides as a stylesheet.
+ *
+ * Returns `""` when nothing has moved — an empty stylesheet is not a stylesheet
+ * with an empty rule in it, and the runtime uses the empty string as its signal
+ * to remove the style element entirely.
+ *
+ * @param overrides - Current state.
+ * @param options - Banner text.
+ * @returns The stylesheet, newline-terminated, or `""`.
+ * @example
+ * serializeOverrideCss(overrides, { banner: OVERRIDE_BANNER });
+ */
+declare function serializeOverrideCss(overrides: ThemeOverrides, options?: SerializeOverrideOptions): string;
+/**
+ * The stylesheet the panel applies — and, byte for byte, the one its CSS export
+ * hands you. One function so the two can never drift.
+ *
+ * @param overrides - Current state.
+ * @returns The banner-topped stylesheet, or `""` when nothing has moved.
+ */
+declare function configuratorCss(overrides: ThemeOverrides): string;
+/**
+ * Put the stylesheet into the document, creating the style element if needed.
+ *
+ * One element, identified by {@link OVERRIDE_STYLE_ID}, appended to `<head>`
+ * after everything else — later in the cascade is half of how these overrides
+ * win. An empty stylesheet removes the element instead of leaving an empty one
+ * behind, so "reset all" leaves the document exactly as it found it.
+ *
+ * @param css - The stylesheet, from {@link configuratorCss}.
+ * @param doc - Document to write into. Defaults to the ambient one.
+ * @returns The style element, or `null` when there was nothing to apply.
+ */
+declare function applyOverrideCss(css: string, doc?: Document | undefined): HTMLStyleElement | null;
+/** Take the override stylesheet back out of the document. */
+declare function removeOverrideStyles(doc?: Document | undefined): void;
+/** The snapshot a first-time visitor gets. */
+declare function defaultSnapshot(): ConfiguratorSnapshot;
+/**
+ * Read the persisted snapshot.
+ *
+ * Every field is validated, and anything that fails validation is dropped
+ * rather than repaired — the blob is text a user can edit in devtools, and its
+ * values are printed straight into a stylesheet.
+ *
+ * @param storageKey - The `localStorage` key.
+ * @returns The snapshot, or `null` when there is nothing usable stored.
+ */
+declare function readSnapshot(storageKey: string): ConfiguratorSnapshot | null;
+/**
+ * Persist the snapshot. A full quota or a private-mode failure is swallowed —
+ * a preference is a nicety, never a hard failure.
+ *
+ * @param storageKey - The `localStorage` key.
+ * @param snapshot - What to store.
+ */
+declare function writeSnapshot(storageKey: string, snapshot: ConfiguratorSnapshot): void;
+//#endregion
+export { BASE_TRACKING_LABEL, COLOR_TOKENS, CONFIGURATOR_VERSION, ConfiguratorPosition, ConfiguratorSnapshot, DEFAULT_CONFIGURATOR_STORAGE_KEY, EMPTY_OVERRIDES, FONT_TOKENS, MANAGED_TOKENS, OVERRIDE_BANNER, OVERRIDE_STYLE_ID, SerializeOverrideOptions, ThemeOverrides, ThemeScope, TokenKind, applyOverrideCss, baseValue, clearOverride, configuratorCss, defaultSnapshot, isOverridden, isSafeCssValue, overrideCount, readSnapshot, removeOverrideStyles, resolveValue, resolvedTokens, scopeKey, serializeOverrideCss, setOverride, tokenKind, writeSnapshot };