@yahoo/uds-create-config 4.16.0 → 4.18.0

package/dist/entities/system/composed-values.d.ts

@@ -0,0 +1,36 @@
+import { Transition } from "./transition.js";
+import { DerivedColor, Gradient } from "./color.js";
+import { z } from "zod";
+
+//#region src/entities/system/composed-values.d.ts
+type ComposedValue = DerivedColor | Gradient | Transition;
+/** How the write engine spells a stored value: the helper's name and its positional arguments. */
+interface ComposedValueAuthoring {
+  readonly helper: string;
+  readonly args: readonly unknown[];
+}
+interface ComposedValueForm<T extends ComposedValue = ComposedValue> {
+  readonly schema: z.ZodType<T>;
+  readonly is: (value: unknown) => value is T;
+  /** The value as CSS, with `render` resolving each part it holds. */
+  readonly render: (value: T, render: (part: unknown) => string) => string;
+  /**
+   * The helper call that builds this value, or `undefined` for a value no helper produces (a radial
+   * gradient, a `darken` in an unexpected space). Such a value is written as the object it is.
+   */
+  readonly authoring: (value: T) => ComposedValueAuthoring | undefined;
+}
+declare const composedValueForms: readonly ComposedValueForm[];
+/** The forms' schemas, in registry order, for a value union to spread. */
+declare const composedValueSchemas: readonly z.ZodType<ComposedValue>[];
+/** The form a value takes, or `undefined` for anything that is not composed. A string or a number
+ *  answers before the forms are asked, since every form is an object. */
+declare function composedValueFormOf(value: unknown): ComposedValueForm | undefined;
+/** Whether a value is one of the composed forms. */
+declare function isComposedValue(value: unknown): value is ComposedValue;
+/** A composed value as CSS, with `render` resolving each part it holds. */
+declare function renderComposedValue(value: ComposedValue, render: (part: unknown) => string): string;
+/** The helper call that authors a composed value, or `undefined` when none does. */
+declare function composedValueAuthoring(value: unknown): ComposedValueAuthoring | undefined;
+//#endregion
+export { ComposedValue, ComposedValueAuthoring, ComposedValueForm, composedValueAuthoring, composedValueFormOf, composedValueForms, composedValueSchemas, isComposedValue, renderComposedValue };

package/dist/entities/system/composed-values.js

@@ -0,0 +1,52 @@
+import { derivedColor, derivedColorAuthoring, gradient, gradientAuthoring, isDerivedColor, isGradient, renderDerivedColor, renderGradient } from "./color.js";
+import { isTransition, renderTransition, transitionAuthoring, transitionValue } from "./transition.js";
+//#region src/entities/system/composed-values.ts
+/** A form written against its own type, widened to the union the registry holds. `render` and
+*  `authoring` take the narrower type, which the union's signature cannot express without this. */
+function form(spec) {
+	return spec;
+}
+const composedValueForms = [
+	form({
+		schema: derivedColor,
+		is: isDerivedColor,
+		render: renderDerivedColor,
+		authoring: derivedColorAuthoring
+	}),
+	form({
+		schema: gradient,
+		is: isGradient,
+		render: renderGradient,
+		authoring: gradientAuthoring
+	}),
+	form({
+		schema: transitionValue,
+		is: isTransition,
+		render: renderTransition,
+		authoring: transitionAuthoring
+	})
+];
+/** The forms' schemas, in registry order, for a value union to spread. */
+const composedValueSchemas = composedValueForms.map((entry) => entry.schema);
+/** The form a value takes, or `undefined` for anything that is not composed. A string or a number
+*  answers before the forms are asked, since every form is an object. */
+function composedValueFormOf(value) {
+	if (typeof value !== "object" || value === null) return void 0;
+	return composedValueForms.find((entry) => entry.is(value));
+}
+/** Whether a value is one of the composed forms. */
+function isComposedValue(value) {
+	return composedValueFormOf(value) !== void 0;
+}
+/** A composed value as CSS, with `render` resolving each part it holds. */
+function renderComposedValue(value, render) {
+	const entry = composedValueFormOf(value);
+	if (!entry) throw new Error("not a composed value");
+	return entry.render(value, render);
+}
+/** The helper call that authors a composed value, or `undefined` when none does. */
+function composedValueAuthoring(value) {
+	return composedValueFormOf(value)?.authoring(value);
+}
+//#endregion
+export { composedValueAuthoring, composedValueFormOf, composedValueForms, composedValueSchemas, isComposedValue, renderComposedValue };

package/dist/entities/system/style-bag.d.ts

@@ -1,4 +1,4 @@
-import { DerivedColor, Gradient } from "./color.js";
+import { ComposedValue } from "./composed-values.js";
 import { z } from "zod";
 
 //#region src/entities/system/style-bag.d.ts
@@ -13,7 +13,7 @@ import { z } from "zod";
  */
 type StyleValue = string | number | boolean | {
   readonly __ref: string;
-} | DerivedColor | Gradient | {
+} | ComposedValue | {
   readonly [key: string]: StyleValue;
 };
 //#endregion

package/dist/entities/system/style-bag.js

@@ -1,6 +1,6 @@
 import { isExtendedRef, isRef, ref, refSchema, splitRef } from "../../framework/utils/refs.js";
 import { defineSubEntity } from "../../framework/defineSubEntity.js";
-import { derivedColor, gradient } from "./color.js";
+import { composedValueSchemas } from "./composed-values.js";
 import { isCssProperty, kebabCase } from "../../css/values.js";
 import { valueSchemaOf } from "../../framework/value-domain.js";
 import { glyphLeafOf, glyphPackageRef } from "./glyph-identity.js";
@@ -14,8 +14,7 @@ const styleValue = z.lazy(() => z.union([
 	z.number(),
 	z.boolean(),
 	refSchema,
-	derivedColor,
-	gradient,
+	...composedValueSchemas,
 	glyphPackageRef,
 	z.record(z.string(), styleValue)
 ]));
@@ -25,8 +24,7 @@ const anatomyPropValue = z.lazy(() => z.union([
 	z.boolean(),
 	z.null(),
 	refSchema,
-	derivedColor,
-	gradient,
+	...composedValueSchemas,
 	z.array(z.union([
 		z.string(),
 		z.number(),

package/dist/entities/system/token-index.js

@@ -1,6 +1,6 @@
 import { isRef, splitRef } from "../../framework/utils/refs.js";
-import { resolveTokenValueUnder } from "../../framework/projections.js";
 import { resolveValueType } from "../../css/value-type.js";
+import { resolveTokenValueUnder } from "../../framework/projections.js";
 import { matchEntities, searchEntities } from "../../framework/entity-search.js";
 //#region src/entities/system/token-index.ts
 /**

package/dist/entities/system/token-values.d.ts

@@ -0,0 +1,138 @@
+import { Ref } from "../../framework/utils/refs.js";
+import { Config } from "../../framework/Config.js";
+import { RootFontSize } from "../../css/root-font-size.js";
+
+//#region src/entities/system/token-values.d.ts
+/**
+ * A resolved value and the numbers a JS caller reads off it. `px` is present for a length in `px`,
+ * for a unitless number, and for a length in `rem` when the page's root font size fixes one; `ms` for
+ * a time in `s` or `ms`. Anything else — a color, a font stack, a percentage — is its CSS string only.
+ */
+interface TokenValueEntry {
+  readonly css: string;
+  readonly px?: number;
+  readonly ms?: number;
+}
+/** What a token resolved to, or why it did not. */
+type TokenValueState = /** One value, the same under every mode and state. */{
+  readonly kind: 'value';
+  readonly value: TokenValueEntry;
+}
+/** A modifier decides it — an override on the token or on one it aliases — so it is only ever a
+ *  `var()` on the page. */
+| {
+  readonly kind: 'conditional';
+}
+/** Nothing to resolve to: an alias chain that never ends, a linked source this config did not
+ *  reach, or a value that is not one scalar. */
+| {
+  readonly kind: 'unresolved';
+};
+/** One token as the runtime module carries it. */
+interface TokenValueRow {
+  readonly path: string;
+  /** The first path segment, which is the group a reader is addressed by. */
+  readonly group: string;
+  /** The rest of the path — `2.5` for `spacing/2.5`, `blue/3` for `spectrum/blue/3`. A path with no
+   *  slash is its own group and alias. */
+  readonly alias: string;
+  /** The custom property the stylesheet declares it as, spelled by the config that owns it. */
+  readonly variable: string;
+  readonly state: TokenValueState;
+}
+/** The root font size of the page this config's sheet is for, as stated or the browser's own. A
+ *  stored value already passed the setting's own check, so it parses. */
+declare function rootFontSize(config: Config): RootFontSize;
+/**
+ * Every token this config lists, in list order, as {@link TokenValueRow}s.
+ *
+ * Keyed on the token and settings slices, plus the attached sources every memo keys on: a token edit
+ * or a `rem` change recomputes, a component edit does not. A source's values reach here through the
+ * closure the artifact recorded whether or not the source is attached, so the two answer the same.
+ */
+declare const tokenValueRows: (config: Config) => readonly TokenValueRow[];
+/**
+ * One token's row by ref or path, qualified or not. A qualified target is read in the source it
+ * names, so the row spells that source's variable and value; an unqualified one is this config's,
+ * including a row this config derived from a link.
+ */
+declare function tokenValueRow({
+  config,
+  target
+}: {
+  config: Config;
+  target: string | Ref;
+}): TokenValueRow | undefined;
+/**
+ * Whether a `token:` target names something this config can answer for — an item, qualified or not,
+ * or a group. A group is what a read whose path a prop completes is an edge to.
+ */
+declare function tokenExists({
+  config,
+  target
+}: {
+  config: Config;
+  target: string | Ref;
+}): boolean;
+/**
+ * Token path → what the build resolved it to, the augmentation the emitted `uds-env.d.ts` fills:
+ *
+ * ```ts
+ * declare module '@yahoo/uds-create-config' {
+ *   interface RegisteredTokenValues {
+ *     'spacing/1': { css: '0.25rem'; px: 4 };
+ *     'motion/fast': { css: '200ms'; ms: 200 };
+ *     'color/brand': {};
+ *   }
+ * }
+ * ```
+ *
+ * Every token is a key, so `var()` types against all of them; `css`, `px` and `ms` are present only
+ * where the token resolves to one value, which is what makes `px('brand')` on a colour an error.
+ */
+interface RegisteredTokenValues {}
+/**
+ * One token group's readers. `var` is available for every token; the others only for the tokens the
+ * build resolved to one value, so a mode-dependent token is a type error everywhere but `var`.
+ */
+interface TokenGroupReader<All extends string = string, Static extends string = string, Px extends string = string, Ms extends string = string> {
+  /** `var(--uds-spacing-2_5)` — the reference the stylesheet's own rules use, so it follows modes. */
+  var(alias: All): string;
+  /** The resolved CSS value, `'0.625rem'`. */
+  value(alias: Static): string;
+  /** The value as CSS pixels: `rem` against the page's root font size (`settings.css.rem`), `px`
+   *  as written, a unitless number as itself. */
+  px(alias: Px): number;
+  /** The value in milliseconds, for a duration or a delay. */
+  ms(alias: Ms): number;
+}
+/**
+ * The readers a token ref offers, by what the build resolved that path to. A path the augmentation
+ * knows narrows to the readers its value supports, so `.px()` on a colour is a compile error; a path it
+ * does not know — before a build, or a template a prop fills in — keeps all four.
+ */
+type TokenReaders<P extends string> = P extends keyof RegisteredTokenValues ? ReadersOf<RegisteredTokenValues[P]> : ReadersOf<{
+  css: string;
+  px: number;
+  ms: number;
+}>;
+type ReadersOf<V> = {
+  /** `var(--uds-spacing-2_5)` — the reference the stylesheet's own rules use, so it follows modes. */var(): string;
+} & (V extends {
+  css: string;
+} ? {
+  value(): string;
+} : unknown) & (V extends {
+  px: number;
+} ? {
+  px(): number;
+} : unknown) & (V extends {
+  ms: number;
+} ? {
+  ms(): number;
+} : unknown);
+/** The reader names, which is what the build recognizes on a `Token.ref(…)`. */
+declare const TOKEN_READERS: readonly ["var", "value", "px", "ms"];
+type TokenReader = (typeof TOKEN_READERS)[number];
+//#endregion
+export { RegisteredTokenValues, TOKEN_READERS, TokenGroupReader, TokenReader, TokenReaders, TokenValueEntry, TokenValueRow, TokenValueState, rootFontSize, tokenExists, tokenValueRow, tokenValueRows };

package/dist/entities/system/token-values.js

@@ -0,0 +1,154 @@
+import { isRef, kindOf, pathOf, ref, splitRef } from "../../framework/utils/refs.js";
+import { parseRootFontSize } from "../../css/root-font-size.js";
+import { CSS_DEFAULTS, Settings } from "./Settings.js";
+import { createSliceMemo } from "../../framework/memo.js";
+import { cssVar, resolveTokenValue } from "../../framework/projections.js";
+//#region src/entities/system/token-values.ts
+/**
+* A token as a VALUE a module can compute with.
+*
+* The stylesheet carries every token as a custom property, which is all a style prop needs. A render
+* that hands a token to something outside the stylesheet — a third-party prop that wants a number, a
+* layout measured in JS — needs the value itself, and the config is the only place it can come from
+* without a hand-written table that drifts. This is that answer, computed once per build: a render
+* reads it as `Token.ref('spacing/2.5').px()`, which the build resolves in place, and the emitted
+* `components/_tokens.ts` module carries the tables a read through a prop needs. The readers are typed
+* per path off {@link RegisteredTokenValues}, which the emitted `uds-env.d.ts` fills in.
+*
+* A token has a value only when nothing changes it: a token with an override, or aliasing one, is
+* whatever the viewer's mode or state says on the page, so it is only ever reachable as its `var()`.
+*/
+const NUMERIC = /^(-?(?:\d+(?:\.\d*)?|\.\d+))(px|rem|ms|s)?$/;
+function tokenValueEntry({ value, rem }) {
+	if (typeof value === "number") return {
+		css: String(value),
+		px: value
+	};
+	const css = value.trim();
+	const match = NUMERIC.exec(css);
+	if (!match) return { css };
+	const amount = Number(match[1]);
+	switch (match[2]) {
+		case void 0:
+		case "px": return {
+			css,
+			px: amount
+		};
+		case "rem": return rem === void 0 ? { css } : {
+			css,
+			px: amount * rem
+		};
+		case "ms": return {
+			css,
+			ms: amount
+		};
+		case "s": return {
+			css,
+			ms: amount * 1e3
+		};
+		default: return { css };
+	}
+}
+/** The root font size of the page this config's sheet is for, as stated or the browser's own. A
+*  stored value already passed the setting's own check, so it parses. */
+function rootFontSize(config) {
+	const css = Settings.get(config)?.css?.rem ?? CSS_DEFAULTS.rem;
+	return parseRootFontSize(css) ?? {
+		css,
+		px: void 0
+	};
+}
+/**
+* Every token this config lists, in list order, as {@link TokenValueRow}s.
+*
+* Keyed on the token and settings slices, plus the attached sources every memo keys on: a token edit
+* or a `rem` change recomputes, a component edit does not. A source's values reach here through the
+* closure the artifact recorded whether or not the source is attached, so the two answer the same.
+*/
+const tokenValueRows = createSliceMemo({
+	kinds: ["token", "settings"],
+	compute: (config) => {
+		const rem = rootFontSize(config).px;
+		return config.list("token").map((token) => {
+			const { path } = token;
+			const slash = path.indexOf("/");
+			const owner = config.configFor(ref("token", path)) ?? config;
+			return {
+				path,
+				group: slash > 0 ? path.slice(0, slash) : path,
+				alias: slash > 0 ? path.slice(slash + 1) : path,
+				variable: cssVar(owner, "token", path),
+				state: stateOf({
+					config,
+					path,
+					rem
+				})
+			};
+		});
+	}
+});
+function stateOf({ config, path, rem }) {
+	if (modeDecides(config, path)) return { kind: "conditional" };
+	const resolved = resolveTokenValue(config, path);
+	if (resolved === void 0) return { kind: "unresolved" };
+	return {
+		kind: "value",
+		value: tokenValueEntry({
+			value: resolved,
+			rem
+		})
+	};
+}
+/** Path → its row, over the same memo as {@link tokenValueRows}. */
+const tokenValueIndex = createSliceMemo({
+	kinds: ["token", "settings"],
+	compute: (config) => new Map(tokenValueRows(config).map((row) => [row.path, row]))
+});
+/** A bare path or a ref string, as a `token:` ref string. */
+function tokenTarget(target) {
+	return typeof target === "string" && !target.includes(":") ? `token:${target}` : target;
+}
+/**
+* One token's row by ref or path, qualified or not. A qualified target is read in the source it
+* names, so the row spells that source's variable and value; an unqualified one is this config's,
+* including a row this config derived from a link.
+*/
+function tokenValueRow({ config, target }) {
+	const { path, source } = splitRef(tokenTarget(target));
+	const owner = source === void 0 ? config : config.sourceFor(source);
+	return owner ? tokenValueIndex(owner).get(path) : void 0;
+}
+/**
+* Whether a `token:` target names something this config can answer for — an item, qualified or not,
+* or a group. A group is what a read whose path a prop completes is an edge to.
+*/
+function tokenExists({ config, target }) {
+	const { path, qualifiedPath } = splitRef(tokenTarget(target));
+	if (config.resolve("token", qualifiedPath)) return true;
+	return config.groups("token").some((group) => group.path === path);
+}
+/**
+* Whether a token's value depends on a modifier: it carries an override itself, or it aliases a token
+* that does, however many hops away. Chased through the config each alias was authored in, the way
+* `resolveTokenValue` chases the value.
+*/
+function modeDecides(config, path, seen = /* @__PURE__ */ new Set()) {
+	const body = config.resolve("token", path)?.toJSON();
+	if (!body) return false;
+	if (body.overrides && Object.keys(body.overrides).length > 0) return true;
+	const { value } = body;
+	if (!isRef(value) || kindOf(value) !== "token") return false;
+	if (seen.has(value.__ref)) return false;
+	seen.add(value.__ref);
+	const source = config.configFor(value);
+	return source ? modeDecides(source, pathOf(value), seen) : false;
+}
+/** The reader names, which is what the build recognizes on a `Token.ref(…)`. */
+const TOKEN_READERS = [
+	"var",
+	"value",
+	"px",
+	"ms"
+];
+//#endregion
+export { TOKEN_READERS, rootFontSize, tokenExists, tokenValueRow, tokenValueRows };

package/dist/entities/system/transition.d.ts

@@ -0,0 +1,35 @@
+import { Ref } from "../../framework/utils/refs.js";
+import { z } from "zod";
+
+//#region src/entities/system/transition.d.ts
+/** A timing part of a transition: a literal (`'150ms ease-out'`) or a ref to the entity that names it,
+ *  a token or a motion role. */
+type TimingValue = string | Ref;
+interface TransitionSegment {
+  /** The CSS properties this segment animates. Each renders as its own `<property> <timing>` entry. */
+  readonly properties: readonly string[];
+  /** The duration and easing, together, as a ref to the entity that names them or a literal. */
+  readonly timing: TimingValue;
+  readonly delay?: TimingValue;
+}
+interface Transition {
+  readonly transition: readonly TransitionSegment[];
+}
+/** Whether a value is a composed transition — the test the renderers branch on. Every segment must
+ *  carry its properties and timing, so a record that merely holds a list under `transition` is not
+ *  one. */
+declare function isTransition(value: unknown): value is Transition;
+/**
+ * `transition({ properties: ['translate', 'scale'], timing: Token.ref('motion/expressive') })`.
+ * Several segments compose one transition whose properties run on different roles.
+ */
+declare function transition(...segments: readonly TransitionSegment[]): Transition;
+/**
+ * A transition as CSS — `background-color var(--uds-motion-color), box-shadow var(--uds-motion-color)`.
+ *
+ * `render` resolves the timing parts. It is passed in rather than imported because resolving a ref
+ * to a `var()` is the projection layer's job and this module is the value's shape.
+ */
+declare function renderTransition(value: Transition, render: (part: TimingValue) => string): string;
+//#endregion
+export { TimingValue, Transition, TransitionSegment, isTransition, renderTransition, transition };

package/dist/entities/system/transition.js

@@ -0,0 +1,57 @@
+import { refSchema } from "../../framework/utils/refs.js";
+import { z } from "zod";
+//#region src/entities/system/transition.ts
+/**
+* A CSS transition composed from the properties it animates and the timing they run on —
+* `transition({ properties: ['background-color', 'box-shadow'], timing: Token.ref('motion/color') })`.
+*
+* A design system names its timing once, as a motion role (`motion/color` is "150ms linear"), and a
+* transition is that role applied to some properties. Spelled as one string the role is copied into
+* the transition and stops following the token: retune the duration and the transition keeps the old
+* one. Held as parts, the role is a ref, so it renders as a `var()` and the dependency graph sees it.
+*
+* Usable wherever a style value is — a token's value, a style bag — for the same reason a gradient
+* is: it is a value, not its own kind.
+*/
+const timingValue = z.union([z.string(), refSchema]);
+const transitionValue = z.strictObject({ transition: z.array(z.strictObject({
+	properties: z.array(z.string()).min(1),
+	timing: timingValue,
+	delay: timingValue.optional()
+})).min(1) });
+/** Whether a value is a composed transition — the test the renderers branch on. Every segment must
+*  carry its properties and timing, so a record that merely holds a list under `transition` is not
+*  one. */
+function isTransition(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const segments = value.transition;
+	return Array.isArray(segments) && segments.every((segment) => typeof segment === "object" && segment !== null && Array.isArray(segment.properties) && "timing" in segment);
+}
+/**
+* `transition({ properties: ['translate', 'scale'], timing: Token.ref('motion/expressive') })`.
+* Several segments compose one transition whose properties run on different roles.
+*/
+function transition(...segments) {
+	return { transition: segments };
+}
+/** The `transition(...)` call that authors a stored value: its segments are the arguments. */
+function transitionAuthoring(value) {
+	return {
+		helper: "transition",
+		args: value.transition
+	};
+}
+/**
+* A transition as CSS — `background-color var(--uds-motion-color), box-shadow var(--uds-motion-color)`.
+*
+* `render` resolves the timing parts. It is passed in rather than imported because resolving a ref
+* to a `var()` is the projection layer's job and this module is the value's shape.
+*/
+function renderTransition(value, render) {
+	return value.transition.flatMap((segment) => {
+		const timing = [segment.timing, segment.delay].filter((part) => part !== void 0).map(render);
+		return segment.properties.map((property) => [property, ...timing].join(" "));
+	}).join(", ");
+}
+//#endregion
+export { isTransition, renderTransition, transition, transitionAuthoring, transitionValue };

package/dist/framework/Config.d.ts

@@ -72,7 +72,7 @@ interface RecordedSource {
  * The dense-counter `2` a short-lived scheme stamped before the chain existed reads as the mint
  * that replaced it (see `detectedWireVersion`).
  */
-declare const SERIALIZED_CONFIG_VERSION = 20260923112910;
+declare const SERIALIZED_CONFIG_VERSION = 20260923160425;
 interface SerializedConfig {
   /** See {@link SERIALIZED_CONFIG_VERSION}. Always written; a stored artifact may lack it. */
   readonly version: number;

package/dist/framework/Config.js

@@ -4836,7 +4836,7 @@ var Config = class Config {
 	*  links from the provided sources. A declared `linkedKind` with no provided source throws. */
 	hydrateFrom(stored, options) {
 		const claimed = schemaVersionOf(stored);
-		if (claimed > 20260923112910) throw new SchemaVersionTooNew(claimed);
+		if (claimed > 20260923160425) throw new SchemaVersionTooNew(claimed);
 		const wire = upgradeSerializedConfig(stored);
 		if (!Array.isArray(wire.ownedKinds) || typeof wire.items !== "object" || wire.items === null) throw new ConfigFormatError(`Config "${stored.name ?? "system-config"}" cannot be hydrated: this is not a serialized config-v2 config (no "ownedKinds"/"items"). A pre-cutover build artifact converts through the registered cutover migration — import the config type's module (e.g. \`configs/system\`) before hydrating, or port the repo once with \`uds migrate\`.`);
 		const leftover = wire.options;

package/dist/framework/defineEntity.d.ts

@@ -355,4 +355,4 @@ type OpInput<E extends {
   input: infer I extends z.ZodTypeAny;
 } ? z.input<I> : never;
 //#endregion
-export { EntityClass, GroupComputedInput, ItemOf, OpInput, defineEntity };
+export { EntityClass, GroupComputedInput, ItemOf, KindRef, OpInput, defineEntity };

package/dist/framework/defineEntity.js

@@ -1,4 +1,4 @@
-import { isRef, kindOf, pathOf, ref, refSchema, sourceOf } from "./utils/refs.js";
+import { isRef, kindOf, pathOf, ref, refSchema, refTo, sourceOf } from "./utils/refs.js";
 import { CONFIG_OPERATION_KIND } from "./config-operation-kind.js";
 import { resolveFields } from "./schemas.js";
 import { buildKind } from "./registry.js";
@@ -129,10 +129,7 @@ function defineEntity(spec) {
 		authoredValue: spec.authoredValue,
 		invariants: spec.invariants
 	});
-	const schema = z.object({ __ref: z.string().refine((raw) => kindOf(raw) === spec.kind) }).meta({
-		ref: true,
-		refKind: spec.kind
-	});
+	const schema = refTo(spec.kind);
 	/**
 	* The path a caller named — from a path, a ref object, or a ref string (`component:Box`, which is
 	* what a spec element's `type` is, so a caller reading one needn't take it apart first).

package/dist/framework/projections.js

@@ -1,7 +1,7 @@
 import { isRef, kindOf, memberOf, pathOf, ref, refLeaf, sourceOf, splitRef } from "./utils/refs.js";
 import { forwardedPropName, forwardsOf } from "../entities/system/element.js";
 import { classPrefixOf, varPrefixOf } from "../entities/system/Settings.js";
-import { isDerivedColor, isGradient, renderDerivedColor, renderGradient } from "../entities/system/color.js";
+import { isComposedValue, renderComposedValue } from "../entities/system/composed-values.js";
 import { fontFamilyStack } from "../entities/system/Font.js";
 import { listedIn } from "./utils/enumerated.js";
 import { modifierCategory } from "../entities/system/Modifier.js";
@@ -488,8 +488,7 @@ function resolveTokenValueUnder(config, path, condition, seen = /* @__PURE__ */
 *  ordinary call — it is `config`'s own prefix. */
 function renderStyleValue(config, value, varPrefix) {
 	if (Array.isArray(value)) return value.map((part) => renderStyleValue(config, part, varPrefix)).join(" ");
-	if (isDerivedColor(value)) return renderDerivedColor(value, (color) => renderStyleValue(config, color, varPrefix));
-	if (isGradient(value)) return renderGradient(value, (color) => renderStyleValue(config, color, varPrefix));
+	if (isComposedValue(value)) return renderComposedValue(value, (part) => renderStyleValue(config, part, varPrefix));
 	if (isRef(value)) {
 		const source = config.configFor(value);
 		if (!source) return "";

package/dist/framework/schema-version.d.ts

@@ -15,7 +15,7 @@ import { Patch, SerializedConfig } from "./Config.js";
  * sets this constant to its own older timestamp; the merge ref then carries a registered migration
  * newer than the constant, and the assertion fails until the author re-mints.
  */
-declare const CURRENT_SCHEMA_VERSION = 20260923112910;
+declare const CURRENT_SCHEMA_VERSION = 20260923160425;
 /** What the walkers need to see of an envelope — loose on purpose, so a typed `SerializedConfig`
  *  and a raw old-shape record both flow in without casts. */
 interface VersionStamped {

package/dist/framework/schema-version.js

@@ -13,7 +13,7 @@ import { ConfigFormatError } from "./rejection.js";
 * sets this constant to its own older timestamp; the merge ref then carries a registered migration
 * newer than the constant, and the assertion fails until the author re-mints.
 */
-const CURRENT_SCHEMA_VERSION = 20260923112910;
+const CURRENT_SCHEMA_VERSION = 20260923160425;
 /** The mint that moved `options` into the `settings` kind — restated here, rather than imported
 *  from the migration that owns it, because that migration imports this module. */
 const SETTINGS_AS_KIND_VERSION = 20260908171448;
@@ -45,7 +45,7 @@ function registerSchemaMigrations(...migrations) {
 	for (const migration of migrations) {
 		if (migration.version !== 1 && !isMintTimestamp(migration.version)) throw new Error(`Schema migration version ${migration.version} is not a mint timestamp — mint one with \`date +%Y%m%d%H%M%S\`, like a supabase migration.`);
 		if (REGISTERED.has(migration.version)) throw new Error(`A schema migration at version ${migration.version} is already registered.`);
-		if (migration.version > 20260923112910) throw new Error(`Schema migration ${migration.version} is newer than CURRENT_SCHEMA_VERSION (${CURRENT_SCHEMA_VERSION}) — a stale branch merged, or the mint forgot to bump the constant. Re-mint: set CURRENT_SCHEMA_VERSION to the newest migration version.`);
+		if (migration.version > 20260923160425) throw new Error(`Schema migration ${migration.version} is newer than CURRENT_SCHEMA_VERSION (${CURRENT_SCHEMA_VERSION}) — a stale branch merged, or the mint forgot to bump the constant. Re-mint: set CURRENT_SCHEMA_VERSION to the newest migration version.`);
 		REGISTERED.set(migration.version, migration);
 	}
 }
@@ -102,7 +102,7 @@ function pendingFor(version, target, options) {
 * Already-current input passes through untouched — same reference, so hot paths pay nothing.
 */
 function upgradeSerializedConfig(json, options) {
-	const target = options?.target ?? 20260923112910;
+	const target = options?.target ?? 20260923160425;
 	const version = detectedWireVersion(json);
 	if (version > target) throw new SchemaVersionTooNew(version, target);
 	const raw = json;
@@ -160,7 +160,7 @@ function upgradedSources(json, options) {
 * meaning under the current schema and replay skips it — reported by the caller, not swallowed here.
 */
 function upgradePatch(patch, writtenAt, options) {
-	const target = options?.target ?? 20260923112910;
+	const target = options?.target ?? 20260923160425;
 	if (writtenAt > target) throw new SchemaVersionTooNew(writtenAt, target);
 	let current = patch;
 	for (const migration of pendingFor(writtenAt, target, options)) {
@@ -179,7 +179,7 @@ function upgradePatch(patch, writtenAt, options) {
 * stamp would cause.
 */
 function upgradeDraftEntries(draft, options) {
-	const target = options?.target ?? 20260923112910;
+	const target = options?.target ?? 20260923160425;
 	const entries = [];
 	const held = [];
 	const retired = [];

package/dist/framework/utils/identifier.d.ts

@@ -0,0 +1,8 @@
+//#region src/framework/utils/identifier.d.ts
+/** What may be written as one JavaScript identifier — a prop name, an export, a binding. */
+/** Whether `name` has the shape of an identifier. A reserved word has the shape and still cannot be
+ *  bound; {@link isReservedWord} is that question. */
+declare function isIdentifier(name: string): boolean;
+declare function isReservedWord(name: string): boolean;
+//#endregion
+export { isIdentifier, isReservedWord };