@animus-ui/system 0.1.9 → 0.1.12

package/dist/index.js

@@ -1,10 +1,8 @@
-import { n as createClassResolver, r as createComponent, t as createComposedFamily } from "./createComposedFamily-3ZugjBpU.js";
+import { t as createClassResolver } from "./createClassResolver-EpwTL9Sa.js";
+import { n as createComponent, t as createComposedFamily } from "./createComposedFamily-C4NovMcd.js";
 import { compose } from "./compose.js";
-import { a as borderShorthand, c as numericScale, d as createTransform, i as gridItemRatio, l as stringScale, n as size, o as createScale, r as gridItem, s as numericOrStringScale, t as percentageOrAbsolute, u as areTransformsEqual } from "./size-DHdmBc64.js";
+import { a as borderShorthand, c as numericScale, d as createTransform, i as gridItemRatio, l as stringScale, n as size, o as createScale, r as gridItem, s as numericOrStringScale, t as percentageOrAbsolute, u as areTransformsEqual } from "./size-C6jqxiQy.js";
 //#region src/utils/deepMerge.ts
-/**
-* Deep merge utility — replaces lodash.merge for variant accumulation.
-*/
 const isMergeable = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
 function deepMerge(target, source) {
 	const result = { ...target };
@@ -37,17 +35,20 @@ var AnimusExtendedWithAll = class {
 		return new AnimusExtended(this.propRegistry, this.groupRegistry, this.baseStyles, this.variants, this.statesConfig, this.activeGroups, this.custom, this.compounds);
 	}
 	asElement(component) {
-		const Component = createComponent(component, "", this._buildComponentConfig());
+		const config = this._buildComponentConfig();
+		const Component = createComponent(component, "", config);
 		const extendFn = this.extend.bind(this);
 		return Object.assign(Component, { extend: extendFn });
 	}
 	asComponent(AsComponent) {
-		const Component = createComponent(AsComponent, "", this._buildComponentConfig());
+		const config = this._buildComponentConfig();
+		const Component = createComponent(AsComponent, "", config);
 		const extendFn = this.extend.bind(this);
 		return Object.assign(Component, { extend: extendFn });
 	}
 	asClass() {
-		return createClassResolver("", this._buildComponentConfig());
+		const config = this._buildComponentConfig();
+		return createClassResolver("", config);
 	}
 	_buildComponentConfig() {
 		const variantConfig = {};
@@ -136,17 +137,20 @@ var AnimusWithAll = class {
 		return new AnimusExtended(this.propRegistry, this.groupRegistry, this.baseStyles, this.variants, this.statesConfig, this.activeGroups, this.custom, this.compounds);
 	}
 	asElement(component) {
-		const Component = createComponent(component, "", this._buildComponentConfig());
+		const config = this._buildComponentConfig();
+		const Component = createComponent(component, "", config);
 		const extendFn = this.extend.bind(this);
 		return Object.assign(Component, { extend: extendFn });
 	}
 	asComponent(AsComponent) {
-		const Component = createComponent(AsComponent, "", this._buildComponentConfig());
+		const config = this._buildComponentConfig();
+		const Component = createComponent(AsComponent, "", config);
 		const extendFn = this.extend.bind(this);
 		return Object.assign(Component, { extend: extendFn });
 	}
 	asClass() {
-		return createClassResolver("", this._buildComponentConfig());
+		const config = this._buildComponentConfig();
+		return createClassResolver("", config);
 	}
 	_buildComponentConfig() {
 		const variantConfig = {};
@@ -230,14 +234,10 @@ var Animus = class extends AnimusWithBase {
 };
 //#endregion
 //#region src/asset.ts
-/** The reserved scheme marking an unsubstituted asset reference. */
 const ASSET_PLACEHOLDER_PREFIX = "animus-asset:";
 /**
-* Reference a package-owned asset (e.g. a font file) by module specifier:
-* `asset('@acme/tokens/fonts/inter.woff2')`. Resolution — aliases, exports
-* maps, `base`, content hashing — belongs to the host bundler; this function
-* only brands the specifier into its placeholder form. A literal URL string
-* (`'/fonts/inter.woff2'`) remains the pass-through alternative.
+* Brands the specifier only — aliases, exports maps and hashing belong to the
+* host bundler. A literal URL string stays a valid alternative.
 */
 function asset(specifier) {
 	return ASSET_PLACEHOLDER_PREFIX + specifier;
@@ -245,27 +245,8 @@ function asset(specifier) {
 //#endregion
 //#region src/conditions.ts
 /**
-* Built-in condition aliases (design D8, increment 06).
-*
-* The Panda-compatible media-feature set: motion, print, orientation, contrast,
-* and OS color-scheme preferences. Every alias is a pure `@media` feature query
-* (`kind: 'media'`). Color-mode aliases (`_dark` / `_light`) are DELIBERATELY
-* excluded — they are selector-kind (`[data-color-mode]`) surface owned by the
-* `system-color-scheme` change, not media features.
-*
-* ORDER BAND (inc-03 full-pass): built-ins occupy a reserved band BELOW the user
-* band — one slot of 10 per alias in table row order, 300–380. The user band
-* starts at 500 (`mergeConditions` floors allocation at 490 → first user alias
-* is 500), so built-ins and user registrations never interleave on collision.
-* This mirrors the selector registry's real layout (built-ins 10–440, users
-* 500+).
-*
-* The static type-level mirror is `BuiltInConditionAlias` in `types/config.ts`
-* (added to `KnownUnderscoreKey`'s VALIDATING branch, exactly like
-* `BuiltInSelectorAlias`). Built-ins are NOT members of the augmentable
-* `Conditions` interface: interface members would make publication permanently
-* non-empty, killing inc-04's graceful-degradation contract. The
-* `types.test-d.tsx` drift positives keep the two in sync.
+* Media-feature aliases only — color-mode aliases are selector-kind. The
+* reserved order band (300–380) sits below the user band (500+).
 */
 const BUILT_IN_CONDITIONS = {
 	_motionReduce: {
@@ -314,38 +295,22 @@ const BUILT_IN_CONDITIONS = {
 		kind: "media"
 	}
 };
-/** The supported at-rule prefixes, longest-first so `@media`/`@container`/
-*  `@supports` match unambiguously. */
 const CONDITION_PREFIXES = [
 	["@media", "media"],
 	["@container", "container"],
 	["@supports", "supports"]
 ];
 /**
-* Infer the condition kind from an at-rule value's prefix (design D3).
-* Throws (fail-loud, build time) when the value does not begin with a
-* supported at-rule name. The compile-time complement is `addConditions()`'s
-* value constraint (`@media`/`@container`/`@supports`-prefixed template
-* literals); this runtime throw remains the backstop for untyped callers.
+* Throws on an unsupported prefix — the runtime backstop for untyped
+* callers, complementing `addConditions()`'s value constraint.
 */
 function inferConditionKind(value) {
 	for (const [prefix, kind] of CONDITION_PREFIXES) if (value.startsWith(prefix)) return kind;
 	throw new Error(`addConditions: value "${value}" must begin with @media, @container, or @supports`);
 }
 /**
-* Merge user-provided condition aliases with a base map.
-*
-* - User aliases override built-ins of the same name, preserving the existing
-*   order (mirrors `mergeSelectors`).
-* - New aliases allocate orders CONTINUING from the highest existing order
-*   (floored at 490, so the first user alias lands at 500) rather than
-*   restarting at 500 each call — chained `.addConditions()` calls must not
-*   collide on order 500.
-* - Fails loud when a condition alias name is already reserved by the SELECTOR
-*   alias registry (`reservedSelectorNames`): the two registries share the `_`
-*   namespace at the call site and their names MUST be disjoint, else a block
-*   key would be ambiguous. The error names the offending alias and both
-*   registries.
+* Overrides keep the existing order; new aliases continue past the highest
+* existing order (floor 490) so chained calls never collide on 500.
 */
 function mergeConditions(base, custom, reservedSelectorNames = /* @__PURE__ */ new Set()) {
 	const merged = { ...base };
@@ -369,16 +334,12 @@ function mergeConditions(base, custom, reservedSelectorNames = /* @__PURE__ */ n
 	}
 	return merged;
 }
-/** Get the sorted alias keys for deterministic cascade ordering. */
 function getSortedConditionKeys(map) {
 	return Object.keys(map).sort((a, b) => map[a].order - map[b].order);
 }
 /**
-* Serialize the condition map for the extraction pipeline.
-* Emits `alias → { value, order, kind }` in registry (cascade) order so the
-* JSON is deterministic. Distinct in SHAPE from the selector map (which
-* flattens to `alias → selector`) — the object entry is forward-compatible
-* with a future multi-valued `values: string[]` property (design D3).
+* Emits `alias → { value, order, kind }` in cascade order so the JSON is
+* deterministic.
 */
 function serializeConditionMap(map) {
 	const conditions = {};
@@ -432,12 +393,6 @@ function keyframes(map) {
 }
 //#endregion
 //#region src/selectors.ts
-/**
-* Built-in selector aliases.
-*
-* Compound selectors (e.g. `_disabled`) target multiple CSS selectors
-* via comma-separation to cover native, ARIA, and data attribute conventions.
-*/
 const BUILT_IN_SELECTORS = {
 	_link: {
 		selector: "&:link",
@@ -541,13 +496,8 @@ const BUILT_IN_SELECTORS = {
 	}
 };
 /**
-* Merge user-provided selectors with built-in defaults.
-* User selectors override built-in aliases of the same name.
-* New aliases allocate orders CONTINUING from the highest existing order
-* (floored at 490, so the first user alias lands at 500) rather than
-* restarting at 500 each call (mirrors `mergeConditions`) — aliases from
-* successive `.addSelectors()`/`extend()` merges must not collide on
-* order 500.
+* Order allocation continues past the highest existing order (floor 490, so
+* the first custom alias is 500); restarting per call would collide.
 */
 function mergeSelectors(base, custom) {
 	const merged = { ...base };
@@ -565,15 +515,9 @@ function mergeSelectors(base, custom) {
 	}
 	return merged;
 }
-/** Get the sorted alias keys for deterministic cascade ordering. */
 function getSortedAliasKeys(map) {
 	return Object.keys(map).sort((a, b) => map[a].order - map[b].order);
 }
-/**
-* Serialize the selector map for the extraction pipeline.
-* Emits a flat `Record<string, string>` (alias → selector) plus
-* the ordered key list for cascade determinism.
-*/
 function serializeSelectorMap(map) {
 	const selectors = {};
 	const order = getSortedAliasKeys(map);
@@ -585,6 +529,68 @@ function serializeSelectorMap(map) {
 }
 //#endregion
 //#region src/SystemBuilder.ts
+/**
+* No console output: a warn here would ship in production consumer bundles,
+* and the extraction host shims `console`. The record is the witness.
+*/
+function legacyVerbWitness(source, verb, sourceIndex) {
+	const record = source.getVocabularyRecord?.();
+	if (!record) return null;
+	const names = [...record.keyframes.map((entry) => entry.name), ...record.globalStyles.map((entry) => entry.name)];
+	if (names.length === 0) return null;
+	return {
+		code: "animus.vocabulary.legacy-verb",
+		verb,
+		source: `${verb} source #${sourceIndex}`,
+		names
+	};
+}
+/**
+* Frozen two levels deep (frame entries + stop bodies) so later mutation of
+* the caller's collection cannot reach a sealed record; deeper values alias.
+*/
+function snapshotFrameData(frames) {
+	const copy = {};
+	for (const [key, entry] of Object.entries(frames)) {
+		const stops = {};
+		for (const [stop, body] of Object.entries(entry.frames ?? {})) stops[stop] = Object.freeze({ ...body });
+		copy[key] = Object.freeze({
+			name: entry.name,
+			frames: Object.freeze(stops)
+		});
+	}
+	return Object.freeze(copy);
+}
+/**
+* A name collision resolves to the incoming side, and the winner takes the
+* incoming declaration position so record order stays declaration order.
+*/
+function mergeVocabularyEntries(existingEntries, existingCollisions, incoming, incomingOrigin) {
+	const entries = existingEntries.map((entry) => ({ ...entry }));
+	const collisions = [...existingCollisions];
+	for (const input of incoming) {
+		const existingIndex = entries.findIndex((entry) => entry.name === input.name);
+		if (existingIndex !== -1) {
+			const loser = entries[existingIndex];
+			collisions.push({
+				code: "animus.vocabulary.collision",
+				name: input.name,
+				winner: incomingOrigin,
+				loser: loser.origin
+			});
+			console.warn(`animus: vocabulary "${input.name}" is registered by both ${loser.origin} and ${incomingOrigin} — ${incomingOrigin} wins; rename one entry (animus.vocabulary.collision)`);
+			entries.splice(existingIndex, 1);
+		}
+		entries.push({
+			...input,
+			origin: incomingOrigin
+		});
+	}
+	return {
+		entries,
+		collisions
+	};
+}
 const snapshotTransformBySource = /* @__PURE__ */ new WeakMap();
 function snapshotTransform(source) {
 	const cached = snapshotTransformBySource.get(source);
@@ -607,12 +613,10 @@ function snapshotTransform(source) {
 	return wrapper;
 }
 /**
-* The one runtime discriminator for a library bundle: `system.toConfig`
-* being callable. A built system instance also has a `.system()` CHAIN
-* METHOD, so presence of a `system` key alone cannot discriminate the two
-* shapes. Both builders' `from()` use this guard; the QuickJS capture
-* script in the Rust system-loader mirrors it by necessity (it cannot
-* import TS) and points back here.
+* A built system also carries a `.system()` chain method, so only
+* `system.toConfig` being callable discriminates a bundle from an instance.
+* The QuickJS capture script in the Rust system-loader reimplements the same
+* discriminator — it cannot import this file, so change both together.
 */
 function isLibraryBundle(value) {
 	const system = value?.system;
@@ -639,13 +643,6 @@ function arePropDefinitionsEqual(existing, incoming, structuralScale = false) {
 function orderedMembersEqual(existing, incoming) {
 	return existing.length === incoming.length && existing.every((member, index) => member === incoming[index]);
 }
-/**
-* Divergent-prop error naming both definitions AND both origins — used by the
-* `extend()` merge (sibling/dual-version conflicts, design D3/G4) and by
-* `addGroup`/`addProps` when the colliding entry arrived through `extend()`
-* (origin labels "extended source #n" / "builder state"). When no extension
-* provenance exists, the pre-existing origin-less messages are kept verbatim.
-*/
 function divergentPropError(key, existing, incoming, existingOrigin, incomingOrigin) {
 	return /* @__PURE__ */ new Error(`Prop "${key}" already registered with a different definition. Existing (${existingOrigin}): property="${existing.property}", scale="${String(existing.scale)}". Incoming (${incomingOrigin}): property="${incoming.property}", scale="${String(incoming.scale)}".`);
 }
@@ -657,7 +654,10 @@ var SystemBuilder = class SystemBuilder {
 	#conditionRegistry;
 	#extendProvenance;
 	#extendCount;
-	constructor(propRegistry, groupRegistry, selectorRegistry, includesRegistry, conditionRegistry, extendProvenance, extendCount) {
+	#vocabularyRegistry;
+	#vocabularyCollisions;
+	#legacyVerbWitnesses;
+	constructor(propRegistry, groupRegistry, selectorRegistry, includesRegistry, conditionRegistry, extendProvenance, extendCount, vocabularyRegistry, vocabularyCollisions, legacyVerbWitnesses) {
 		this.#propRegistry = propRegistry || {};
 		this.#groupRegistry = groupRegistry || {};
 		this.#selectorRegistry = selectorRegistry || { ...BUILT_IN_SELECTORS };
@@ -665,6 +665,9 @@ var SystemBuilder = class SystemBuilder {
 		this.#conditionRegistry = conditionRegistry || { ...BUILT_IN_CONDITIONS };
 		this.#extendProvenance = extendProvenance || /* @__PURE__ */ new Map();
 		this.#extendCount = extendCount || 0;
+		this.#vocabularyRegistry = vocabularyRegistry || [];
+		this.#vocabularyCollisions = vocabularyCollisions || [];
+		this.#legacyVerbWitnesses = legacyVerbWitnesses || [];
 	}
 	#originOf(provenanceKey) {
 		const index = this.#extendProvenance.get(provenanceKey);
@@ -672,7 +675,9 @@ var SystemBuilder = class SystemBuilder {
 	}
 	from(source) {
 		const instance = isLibraryBundle(source) ? source.system : source;
-		return new SystemBuilder(this.#propRegistry, this.#groupRegistry, this.#selectorRegistry, [...this.#includesRegistry, instance], this.#conditionRegistry, this.#extendProvenance, this.#extendCount);
+		const fromCount = this.#legacyVerbWitnesses.filter((entry) => entry.verb === "from").length;
+		const witness = legacyVerbWitness(instance, "from", fromCount + 1);
+		return new SystemBuilder(this.#propRegistry, this.#groupRegistry, this.#selectorRegistry, [...this.#includesRegistry, instance], this.#conditionRegistry, this.#extendProvenance, this.#extendCount, this.#vocabularyRegistry, this.#vocabularyCollisions, witness ? [...this.#legacyVerbWitnesses, witness] : this.#legacyVerbWitnesses);
 	}
 	extend(source) {
 		const instance = isLibraryBundle(source) ? source.system : source;
@@ -750,57 +755,43 @@ var SystemBuilder = class SystemBuilder {
 			...this.#conditionRegistry,
 			...conditionOverrides
 		}, newConditions, new Set(Object.keys(nextSelectors)));
-		return new SystemBuilder(nextProps, nextGroups, nextSelectors, [...this.#includesRegistry, instance], nextConditions, provenance, sourceIndex);
+		const sourceRecord = instance.getVocabularyRecord?.();
+		if (!sourceRecord) throw new Error("extend: source system is not sealed (or was built by an older @animus-ui/system) — registered vocabulary travels only on sealed instances. Call seal() on the source bundle and export the sealed instance.");
+		let nextVocabulary = this.#vocabularyRegistry;
+		let nextVocabularyCollisions = this.#vocabularyCollisions;
+		const inheritedEntries = [...sourceRecord.keyframes.map((entry) => ({
+			kind: "keyframes",
+			name: entry.name,
+			frames: entry.frames
+		})), ...sourceRecord.globalStyles.map((entry) => ({
+			kind: "globalStyles",
+			name: entry.name,
+			styles: entry.styles,
+			...entry.fontFaces ? { fontFaces: entry.fontFaces } : {}
+		}))];
+		if (inheritedEntries.length > 0) {
+			const merged = mergeVocabularyEntries(this.#vocabularyRegistry, this.#vocabularyCollisions, inheritedEntries, incomingOrigin);
+			nextVocabulary = merged.entries;
+			nextVocabularyCollisions = merged.collisions;
+		}
+		return new SystemBuilder(nextProps, nextGroups, nextSelectors, [...this.#includesRegistry, instance], nextConditions, provenance, sourceIndex, nextVocabulary, nextVocabularyCollisions, this.#legacyVerbWitnesses);
 	}
 	/**
-	* Register custom selector aliases (`_hoverChild`, …) → `&`-relative selector
-	* strings. Overriding a built-in SELECTOR alias is legal; a name owned by the
-	* CONDITION registry (built-in or registered earlier in this chain) maps to
-	* the branded `ReservedByConditionRegistry` instead of its selector string —
-	* the compile-time complement of the cross-registry throw below. The clash is
-	* checked in VALUE position so `S` stays a naked inference site; subtracting
-	* the reserved names from the KEY position is impossible — `Exclude` is a
-	* silent no-op against a template-literal pattern. `NarrowedAliases` keeps a
-	* widened `Conds` from swallowing the whole `_` namespace.
-	*
-	* It wraps the ACCUMULATION too: a widened registration contributes nothing
-	* to `Sels` rather than widening it, so the pattern can never reach the
-	* published `RegistryBrand` — see `addConditions` for the full argument.
+	* Registers `_` aliases → `&`-relative selectors. The cross-registry clash
+	* is checked in VALUE position: `Exclude` on a `_${string}` key is a no-op.
 	*/
 	addSelectors(selectors) {
 		for (const name of Object.keys(selectors)) if (name in this.#conditionRegistry) throw new Error(`addSelectors: "${name}" is already registered as a condition alias; a name resolves through exactly one registry. Pick a distinct name.`);
 		const merged = mergeSelectors(this.#selectorRegistry, selectors);
-		return new SystemBuilder(this.#propRegistry, this.#groupRegistry, merged, this.#includesRegistry, this.#conditionRegistry, this.#extendProvenance, this.#extendCount);
+		return new SystemBuilder(this.#propRegistry, this.#groupRegistry, merged, this.#includesRegistry, this.#conditionRegistry, this.#extendProvenance, this.#extendCount, this.#vocabularyRegistry, this.#vocabularyCollisions, this.#legacyVerbWitnesses);
 	}
 	/**
-	* Register condition aliases (`_motionReduce`, `_cardSm`, …) → at-rule
-	* condition strings (`@media …` / `@container …` / `@supports …`).
-	* Recognized as block keys in style objects; user aliases override built-ins
-	* of the same name (design D3). Keys are constrained to `_`-prefixed aliases
-	* and values to `@`-prefixed at-rule strings — a value that does not begin
-	* with an at-rule name is a compile-time type error (design D9; the runtime
-	* `inferConditionKind` throw is defense-in-depth). The registered keys are
-	* accumulated into the phantom `Conds` union and surfaced on `build()`.
-	*
-	* A key owned by the SELECTOR registry (built-in or registered earlier in
-	* this chain) maps to the branded `ReservedBySelectorRegistry` — see
-	* `addSelectors` for why the clash is checked in value position. Overriding a
-	* built-in CONDITION alias stays legal (design D3); only the OPPOSITE
-	* registry is subtracted.
-	*
-	* `NarrowedAliases` wraps the ACCUMULATION, not just the gate: a widened
-	* registration (`Record<`_${string}`, …>`) contributes nothing to `Conds`.
-	* Accumulating the pattern instead would carry it out through `build()`'s
-	* `RegistryBrand`, and a consumer publishing `ConditionsOf` into the
-	* augmentable `Conditions` interface would then have every `_` key type as
-	* registered — `UnknownConditionAlias` would never fire again, anywhere in
-	* that project. The gate keeps its own `NarrowedAliases` regardless:
-	* `extend()`-sourced unions can still arrive widened from a system built
-	* before this narrowing.
+	* Registers `_` aliases → at-rule strings; user aliases override built-ins
+	* of the same name. A selector-owned key maps to the branded rejection.
 	*/
 	addConditions(conditions) {
 		const merged = mergeConditions(this.#conditionRegistry, conditions, new Set(Object.keys(this.#selectorRegistry)));
-		return new SystemBuilder(this.#propRegistry, this.#groupRegistry, this.#selectorRegistry, this.#includesRegistry, merged, this.#extendProvenance, this.#extendCount);
+		return new SystemBuilder(this.#propRegistry, this.#groupRegistry, this.#selectorRegistry, this.#includesRegistry, merged, this.#extendProvenance, this.#extendCount, this.#vocabularyRegistry, this.#vocabularyCollisions, this.#legacyVerbWitnesses);
 	}
 	addGroup(name, config) {
 		if (name in this.#propRegistry) throw new Error(`Group name "${name}" collides with an existing prop name. Group names and prop names must be disjoint.`);
@@ -817,10 +808,11 @@ var SystemBuilder = class SystemBuilder {
 			...config
 		};
 		const newGroup = { [name]: Object.keys(config) };
-		return new SystemBuilder(nextProps, {
+		const nextGroups = {
 			...this.#groupRegistry,
 			...newGroup
-		}, this.#selectorRegistry, this.#includesRegistry, this.#conditionRegistry, this.#extendProvenance, this.#extendCount);
+		};
+		return new SystemBuilder(nextProps, nextGroups, this.#selectorRegistry, this.#includesRegistry, this.#conditionRegistry, this.#extendProvenance, this.#extendCount, this.#vocabularyRegistry, this.#vocabularyCollisions, this.#legacyVerbWitnesses);
 	}
 	addProps(config) {
 		for (const key of Object.keys(config)) if (key in this.#groupRegistry) throw new Error(`Prop name "${key}" collides with an existing group name. Group names and prop names must be disjoint.`);
@@ -832,42 +824,123 @@ var SystemBuilder = class SystemBuilder {
 				throw new Error(`Prop "${key}" already registered with a different definition.`);
 			}
 		}
-		return new SystemBuilder({
+		const nextProps = {
 			...this.#propRegistry,
 			...config
-		}, this.#groupRegistry, this.#selectorRegistry, this.#includesRegistry, this.#conditionRegistry, this.#extendProvenance, this.#extendCount);
+		};
+		return new SystemBuilder(nextProps, this.#groupRegistry, this.#selectorRegistry, this.#includesRegistry, this.#conditionRegistry, this.#extendProvenance, this.#extendCount, this.#vocabularyRegistry, this.#vocabularyCollisions, this.#legacyVerbWitnesses);
 	}
 	build() {
-		const animus = new Animus(Object.fromEntries(Object.entries(this.#propRegistry).map(([key, entry]) => [key, { ...entry }])), Object.fromEntries(Object.entries(this.#groupRegistry).map(([key, members]) => [key, [...members]])));
+		const propSource = Object.fromEntries(Object.entries(this.#propRegistry).map(([key, entry]) => [key, { ...entry }]));
+		const groupSource = Object.fromEntries(Object.entries(this.#groupRegistry).map(([key, members]) => [key, [...members]]));
 		const snapshot = createRegistrySnapshot(this.#propRegistry, this.#groupRegistry, this.#selectorRegistry, this.#conditionRegistry);
-		const system = Object.assign(animus, { toConfig: () => {
-			return serializeInstance(snapshot.props, snapshot.groups, snapshot.selectors, snapshot.conditions);
-		} });
-		Object.defineProperty(system, "getRegistrySnapshot", {
-			value: () => snapshot,
-			enumerable: false
-		});
+		const mintInstance = () => {
+			const animus = new Animus(Object.fromEntries(Object.entries(propSource).map(([key, entry]) => [key, { ...entry }])), Object.fromEntries(Object.entries(groupSource).map(([key, members]) => [key, [...members]])));
+			const instance = Object.assign(animus, { toConfig: () => {
+				return serializeInstance(snapshot.props, snapshot.groups, snapshot.selectors, snapshot.conditions);
+			} });
+			Object.defineProperty(instance, "getRegistrySnapshot", {
+				value: () => snapshot,
+				enumerable: false
+			});
+			return instance;
+		};
+		const system = mintInstance();
+		const legacyVerbWitnessRecord = this.#legacyVerbWitnesses;
 		const createGlobalStyles = ((styles, options) => ({
 			__brand: "GlobalStyleBlock",
 			styles,
 			...options?.fontFaces?.length ? { fontFaces: [...options.fontFaces] } : {}
 		}));
 		const createKeyframes = ((frames) => keyframes(frames));
-		return {
-			system,
-			createGlobalStyles,
-			createKeyframes
+		const makeBundle = (entries, collisions, localCallCount) => {
+			let consumedBy;
+			const registerEntries = (label, incoming) => {
+				if (consumedBy === "seal") throw new Error(`${label}: this system is already sealed — registration happens between build() and seal().`);
+				if (consumedBy === "register") throw new Error(`${label}: this bundle was superseded by a later registration call — registration is linear; chain the calls and seal the final bundle.`);
+				const merged = mergeVocabularyEntries(entries, collisions, incoming, `local registration #${localCallCount + 1}`);
+				consumedBy = "register";
+				return makeBundle(merged.entries, merged.collisions, localCallCount + 1);
+			};
+			const registerKeyframes = (map) => {
+				const incoming = [];
+				for (const [name, collection] of Object.entries(map)) {
+					if (!collection || collection.__brand !== "Keyframes" || typeof collection.__frames !== "object") throw new TypeError(`registerKeyframes: "${name}" is not a createKeyframes collection — register the factory return value itself.`);
+					incoming.push({
+						kind: "keyframes",
+						name,
+						frames: snapshotFrameData(collection.__frames)
+					});
+				}
+				return registerEntries("registerKeyframes", incoming);
+			};
+			const registerGlobalStyles = (map) => {
+				const incoming = [];
+				for (const [name, block] of Object.entries(map)) {
+					if (!block || block.__brand !== "GlobalStyleBlock" || typeof block.styles !== "object") throw new TypeError(`registerGlobalStyles: "${name}" is not a createGlobalStyles block — register the factory return value itself.`);
+					const blockValue = block;
+					const styles = Object.freeze(Object.fromEntries(Object.entries(blockValue.styles).map(([selector, body]) => [selector, Object.freeze({ ...body })])));
+					incoming.push({
+						kind: "globalStyles",
+						name,
+						styles,
+						...blockValue.fontFaces?.length ? { fontFaces: Object.freeze(blockValue.fontFaces.map((face) => Object.freeze({ ...face }))) } : {}
+					});
+				}
+				return registerEntries("registerGlobalStyles", incoming);
+			};
+			const seal = () => {
+				if (consumedBy === "seal") throw new Error("seal: this system is already sealed — seal() returns exactly one instance per build().");
+				if (consumedBy === "register") throw new Error("seal: this bundle was superseded by a later registration call — registration is linear; seal the final bundle.");
+				const record = Object.freeze({
+					version: 1,
+					keyframes: Object.freeze(entries.filter((entry) => entry.kind === "keyframes").map((entry) => Object.freeze({
+						name: entry.name,
+						frames: entry.frames
+					}))),
+					globalStyles: Object.freeze(entries.filter((entry) => entry.kind === "globalStyles").map((entry) => Object.freeze({
+						name: entry.name,
+						styles: entry.styles,
+						...entry.fontFaces ? { fontFaces: entry.fontFaces } : {}
+					}))),
+					collisions: Object.freeze(collisions.map((entry) => Object.freeze({ ...entry }))),
+					legacyVerbs: Object.freeze(legacyVerbWitnessRecord.map((entry) => ({
+						...entry,
+						names: entry.names.filter((name) => !entries.some((kept) => kept.name === name))
+					})).filter((entry) => entry.names.length > 0).map((entry) => Object.freeze({
+						...entry,
+						names: Object.freeze([...entry.names])
+					})))
+				});
+				const sealed = mintInstance();
+				Object.defineProperty(sealed, "getVocabularyRecord", {
+					value: () => record,
+					enumerable: false
+				});
+				for (const member of ["registerKeyframes", "registerGlobalStyles"]) Object.defineProperty(sealed, member, {
+					value: () => {
+						throw new Error(`${member}: this system is sealed — registration happens between build() and seal().`);
+					},
+					enumerable: false
+				});
+				consumedBy = "seal";
+				return sealed;
+			};
+			return {
+				system,
+				createGlobalStyles,
+				createKeyframes,
+				registerKeyframes,
+				registerGlobalStyles,
+				seal
+			};
 		};
+		return makeBundle(this.#vocabularyRegistry.map((entry) => ({ ...entry })), [...this.#vocabularyCollisions], 0);
 	}
 };
 /**
-* Freeze the builder's registries into the build-time snapshot (design D7):
-* containers, per-entry objects, and the mutable values nested inside a prop
-* (`properties` arrays, object/array scales) are copies, so neither the
-* builder's onward chaining nor post-build mutation of the instance's public
-* registry fields reaches serialized or merged output. Transform functions
-* are cached immutable forwarding wrappers: behavior survives without keeping
-* mutable serialization metadata live.
+* Copies and freezes containers, entries, and the mutable values inside a
+* prop, so later mutation reaches neither serialized nor merged output.
 */
 function createRegistrySnapshot(propRegistry, groupRegistry, selectorRegistry, conditionRegistry) {
 	const props = {};
@@ -933,33 +1006,24 @@ function serializeInstance(propRegistry, groupRegistry, selectorRegistry, condit
 	};
 }
 function createSystem(config) {
-	return new SystemBuilder(void 0, void 0, void 0, config?.includes ?? []);
+	const includes = config?.includes ?? [];
+	const witnesses = [];
+	includes.forEach((source, index) => {
+		const witness = legacyVerbWitness(source, "includes", index + 1);
+		if (witness) witnesses.push(witness);
+	});
+	return new SystemBuilder(void 0, void 0, void 0, includes, void 0, void 0, void 0, void 0, void 0, witnesses);
 }
 //#endregion
 //#region src/theme/resolveReferences.ts
 /**
-* Late-binding token-reference resolution over the flattened theme (D4,
-* openspec change first-class-extension).
-*
-* Replaces the old single-pass, insertion-order-dependent rewrite: references
-* resolve against the COMPLETE flattened map via depth-first traversal of the
-* reference DAG, so declaration order is never observable (G3), references
-* inside emitted scales resolve into the emitted variable declarations
-* instead of leaking literally into CSS (G2), and a token resolves to the
-* same value whether its scale is emitted or inlined (G1 — an emitted target
-* substitutes as `var()`, which the cascade late-binds to exactly the value
-* the inlined form substitutes directly).
-*
-* Pure module: consumes the flatten pass's maps, returns fresh maps, mutates
-* nothing. Runs in QuickJS — ES built-ins only, no Node/WHATWG APIs.
+* Runs inside QuickJS: ES built-ins only, no Node or WHATWG APIs.
 */
-/** Token ref pattern: {scale.key}, {scale.key.sub}, or {path/NN} (opacity). */
 const TOKEN_REF_RE$1 = /\{([^}]+)\}/g;
-/** DFS node states for cycle detection. */
 const UNVISITED = 0;
 const RESOLVING = 1;
 const RESOLVED = 2;
-/** Parse every `{...}` occurrence via matchAll — no shared lastIndex. */
+/** `matchAll`, not `exec`: a shared global regex would carry `lastIndex`. */
 function parseReferences(value) {
 	const references = [];
 	for (const match of value.matchAll(TOKEN_REF_RE$1)) {
@@ -977,26 +1041,12 @@ function parseReferences(value) {
 	return references;
 }
 /**
-* Resolve token references over the complete flattened maps.
-*
-* - `tokenMap`/`variableMap`/`variables` are `flattenTheme`'s outputs: an
-*   emitted path's tokenMap entry is its `var()` indirection and its RAW
-*   authored value is parked in `variables`; a non-emitted path's tokenMap
-*   entry IS its raw value.
-* - Substitution per reference: emitted target → `var(--target)`; non-emitted
-*   target → its resolved literal; `{path/NN}` keeps the existing
-*   `color-mix` output shape (`/0` → `transparent`, `/100` → the base).
-* - Unresolvable target: warn once per missing path, keep the literal — a
-*   SUPPORTED pattern (a kit theme may reference tokens its consumer
-*   provides later). Dangling-reference errors arrive with the explicit
-*   replacement form (D5, increment 04).
-* - Reference cycle: hard error naming the cycle's token paths in traversal
-*   order, regardless of emission flags (emission-invariant failure, G1).
+* An unresolvable reference warns and keeps its literal: a kit theme may
+* reference tokens its consumer supplies later.
 */
 function resolveReferences(tokenMap, variableMap, variables) {
 	const paths = Object.keys(tokenMap).sort();
 	const known = new Set(paths);
-	/** The authored (raw) value behind a path — see the contract note above. */
 	const rawValueOf = (path) => {
 		const varName = variableMap[path];
 		if (varName !== void 0 && variables[varName] !== void 0) return variables[varName];
@@ -1012,7 +1062,6 @@ function resolveReferences(tokenMap, variableMap, variables) {
 	}
 	const state = /* @__PURE__ */ new Map();
 	const resolved = /* @__PURE__ */ new Map();
-	/** Active DFS trail — the cycle report slices it from the revisited node. */
 	const trail = [];
 	const warnedMissing = /* @__PURE__ */ new Set();
 	const substitute = (reference, match) => {
@@ -1075,7 +1124,6 @@ function resolveReferences(tokenMap, variableMap, variables) {
 }
 //#endregion
 //#region src/theme/utils.ts
-/** Type guard: true for non-null, non-array objects */
 function isObject(value) {
 	return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -1091,11 +1139,6 @@ function merge(target, ...sources) {
 	}
 	return target;
 }
-/**
-* Resolve a dot-path string against a nested object.
-* walkDotPath({ gray: { 50: '#fafafa' } }, 'gray.50') → '#fafafa'
-* The `_` identity key is handled: 'primary' resolves to obj.primary._ if obj.primary is an object with _.
-*/
 function walkDotPath(obj, path) {
 	const parts = path.split(".");
 	let current = obj;
@@ -1106,11 +1149,7 @@ function walkDotPath(obj, path) {
 	return current;
 }
 /**
-* Flatten a nested object into a flat Record with dot-path keys.
-* The `_` key is an identity marker — it produces the parent key without suffix.
-* { gray: { 50: '#fafafa' } } → { 'gray.50': '#fafafa' }
-* { primary: { _: 'ember', hover: 'x' } } → { 'primary': 'ember', 'primary.hover': 'x' }
-* CSS variable names use dash-join, computed at the serialization boundary (not here).
+* A `_` key is an identity marker: it takes the parent path with no suffix.
 */
 function flattenToDotPaths(object, path) {
 	const result = {};
@@ -1122,15 +1161,9 @@ function flattenToDotPaths(object, path) {
 	}
 	return result;
 }
-/**
-* Convert a dot-path key to a dash-join key for CSS variable naming.
-* 'gray.50' → 'gray-50'
-* 'primary.hover' → 'primary-hover'
-*/
 function dotToDash(dotPath) {
 	return dotPath.replace(/\./g, "-");
 }
-/** Map over object values — matches lodash.mapValues overload signatures */
 //#endregion
 //#region src/theme/createTheme.ts
 const COLOR_FUNCTION_PREFIXES = [
@@ -1145,7 +1178,6 @@ const COLOR_FUNCTION_PREFIXES = [
 	"color(",
 	"color-mix("
 ];
-/** Validate that a value is a valid CSS <color>. */
 function isValidCSSColor(value) {
 	if (typeof value !== "string") return false;
 	const v = value.trim();
@@ -1156,10 +1188,6 @@ function isValidCSSColor(value) {
 	if (/^[a-zA-Z]+$/.test(v)) return true;
 	return false;
 }
-/**
-* Validate that mode aliases reference existing color keys via dot-path traversal.
-* Aliases are dot-path strings like 'gray.50' that must resolve in the nested color structure.
-*/
 function validateModeAliases(modeName, aliases, nestedColors, flatColorKeys, prefix) {
 	for (const [key, value] of Object.entries(aliases)) {
 		const aliasPath = prefix ? `${prefix}.${key}` : key;
@@ -1173,12 +1201,11 @@ function validateModeAliases(modeName, aliases, nestedColors, flatColorKeys, pre
 	}
 }
 /**
-* Reserved mode name (D4). "System" is modeled as the ABSENCE of
-* `data-color-mode`, never as a mode: an attribute value `system` would defeat
-* the `:root:not([data-color-mode])` guard while matching no mode block.
+* The system preference is the ABSENCE of `data-color-mode`; a mode named
+* `system` would defeat the `:root:not([data-color-mode])` guard.
 */
 const RESERVED_MODE_NAME = "system";
-const RESERVED_THEME_KEYS = new Set([
+const RESERVED_THEME_KEYS = /* @__PURE__ */ new Set([
 	"breakpoints",
 	"modes",
 	"mode",
@@ -1190,22 +1217,16 @@ const RESERVED_THEME_KEYS = new Set([
 	"serialize",
 	"varRef"
 ]);
-const COLOR_SCHEME_VALUES = new Set([
+const COLOR_SCHEME_VALUES = /* @__PURE__ */ new Set([
 	"light",
 	"dark",
 	"normal"
 ]);
-/**
-* The axis → scheme pairs the mapping forces: the mode named for the OS light
-* preference must classify `light`, the dark one `dark`. Single source for
-* BOTH the default fill and the conflict check in
-* {@link resolveColorModeOptions} — one rule, one table.
-*/
+/** OS-preference axis → the `color-scheme` a mode mapped to it must carry. */
 const MAPPING_FORCED_SCHEMES = [["light", "light"], ["dark", "dark"]];
 /**
-* Merge an incoming option object over the one already on the theme, mirroring
-* `merge`'s per-key override. Returns `undefined` when neither side supplied
-* one, so an unconfigured theme never gains the key (byte parity, G4).
+* `undefined` when neither side supplied one, so an unconfigured theme never
+* gains the key.
 */
 function mergeOptionObject(existing, incoming) {
 	const hasExisting = isObject(existing);
@@ -1216,31 +1237,12 @@ function mergeOptionObject(existing, incoming) {
 		...hasIncoming ? incoming : {}
 	};
 }
-/** Reject the reserved mode name (D4) wherever a mode set is declared or merged. */
 function validateReservedModeNames(modeNames) {
 	for (const modeName of modeNames) if (modeName === RESERVED_MODE_NAME) throw new Error(`addColorModes: '${RESERVED_MODE_NAME}' is a reserved mode name — the system preference is represented by the absence of the data-color-mode attribute, never by a declared mode. Rename it. Declared modes: ${modeNames.join(", ")}`);
 }
 /**
-* Normalize AND validate the optional system-participation options against the
-* declared modes, returning the normalized classification. One entry point on
-* purpose: the D3-amendment fill (mapping-named modes default to their forced
-* schemes) must always run before totality is checked, so exposing fill and
-* validation separately would make "validate an unfilled map" representable.
-* An explicit entry survives the fill's spread and is still conflict-checked,
-* so a wrong value errors rather than being silently corrected. `undefined`
-* passes through untouched — the classification stays opt-in, and a theme with
-* only `systemPreference` emits no `color-scheme` (byte parity, G4).
-*
-* ALWAYS called with MERGED state — `theme.modes` unions across `addColorModes`
-* calls and `from()` composition, so a per-call view both misses invalidation
-* (a later mode declaration un-totals a carried classification) and invents
-* false rejections (a mapping naming a mode declared by an earlier call).
-* Run at both gates: `addColorModes` (fail fast) and `build()` (authoritative —
-* `from()` composition never passes through `addColorModes`; only build()'s
-* resolved map feeds emission and the manifest).
-*
-* Error tone mirrors `validateModeAliases`: `addColorModes:` prefix plus the
-* available names.
+* Fills mapping-named modes with their forced schemes, then validates. Takes
+* the MERGED mode set: a later declaration can un-total a carried map.
 */
 function resolveColorModeOptions(modeNames, systemPreference, suppliedBrowserColorScheme) {
 	let browserColorScheme = suppliedBrowserColorScheme;
@@ -1278,12 +1280,8 @@ function resolveColorModeOptions(modeNames, systemPreference, suppliedBrowserCol
 	return browserColorScheme;
 }
 /**
-* Validate the D6 `basedOn` mode-base map against the MERGED mode set: every
-* key and every base must name a declared mode, self-bases are rejected, and
-* base chains must terminate (a cycle can never fill coverage). Runs at both
-* gates like the other mode options — `addColorModes` (fail fast) and
-* `build()` (authoritative: extend/from composition merges modes without
-* passing through `addColorModes`).
+* Validates against the MERGED mode set: composition merges modes without
+* passing through `addColorModes`, so `build()` runs this again.
 */
 function validateModeBases(modeNames, modeBases) {
 	if (!modeBases) return;
@@ -1304,7 +1302,6 @@ function validateModeBases(modeNames, modeBases) {
 		}
 	}
 }
-/** Validate all color entries, throwing on invalid values. */
 function validateColors(colors) {
 	for (const [key, value] of Object.entries(colors)) if (isObject(value)) validateColors(value);
 	else if (!isValidCSSColor(value)) throw new Error(`addColors: '${String(value)}' is not a valid CSS <color> value for key '${key}'. Expected hex (#fff), rgb(), hsl(), oklch(), named color, transparent, or currentColor.`);
@@ -1341,12 +1338,8 @@ function copyState(state, nextTheme) {
 	return next;
 }
 /**
-* Exact leaf-path flatten for extend() provenance: like `flattenToDotPaths`
-* but WITHOUT the `_` identity-key collapse, so a leaf and a branch can
-* never share a path spelling. A prefix relation between two tracked paths
-* is then a GENUINE structural divergence (one sibling authored a leaf
-* value where the other authored a nested branch) — the review-F1 case that
-* per-leaf value comparison alone cannot see.
+* Leaf-path flatten WITHOUT the `_` identity collapse, so a leaf and a branch
+* can never share a spelling and a prefix relation is a real divergence.
 */
 function flattenLeafPathsExact(object, path) {
 	const result = {};
@@ -1359,12 +1352,8 @@ function flattenLeafPathsExact(object, path) {
 	return result;
 }
 /**
-* Deep copy of plain theme data (records, arrays, primitives). `merge`
-* adopts and MUTATES nested source objects in place, so EVERY builder step
-* copies before folding: a consumed kit's built theme must never be
-* corrupted by composition, and prior builder state must never be shared by
-* reference — a one-level copy lets branching a builder cross-contaminate
-* both branches and lets build() outputs mutate after the fact.
+* `merge` adopts and MUTATES nested source objects, so every builder step deep
+* copies first: a consumed kit's theme and prior state must survive intact.
 */
 function deepCopyPlain(value) {
 	if (Array.isArray(value)) return value.map(deepCopyPlain);
@@ -1376,7 +1365,6 @@ function deepCopyPlain(value) {
 	}
 	return value;
 }
-/** Structural equality over plain theme data (records, arrays, primitives). */
 function plainDataEqual(a, b) {
 	if (Object.is(a, b)) return true;
 	if (Array.isArray(a) && Array.isArray(b)) return a.length === b.length && a.every((item, index) => plainDataEqual(item, b[index]));
@@ -1389,10 +1377,8 @@ function plainDataEqual(a, b) {
 	return false;
 }
 /**
-* Re-seed builder state from a source theme's manifest. This is `from()`'s
-* manifest read, factored out verbatim so `extend()` inherits the SAME
-* emitted-scale/contextual-var/manifest-v2 carry semantics: the manifest is
-* non-enumerable, so the ordinary key-copy loop never sees it (D6/D8).
+* Re-seeds emitted scales, contextual vars and the manifest-v2 carry from a
+* source manifest — non-enumerable, so key-copy loops never see it.
 */
 function reseedStateFromManifest(state, manifest, mergeExtensionState = false) {
 	if (manifest?.emittedScales) for (const scale of manifest.emittedScales) state.emittedScales.add(scale);
@@ -1405,29 +1391,27 @@ function reseedStateFromManifest(state, manifest, mergeExtensionState = false) {
 	}
 	if (manifest?.contextualVars) for (const [scale, vars] of Object.entries(manifest.contextualVars)) {
 		const existing = mergeExtensionState ? state.contextualVars.get(scale) : void 0;
-		state.contextualVars.set(scale, existing ? [...new Set([...existing, ...vars])] : [...vars]);
-	}
-	if (manifest) if (manifest.manifestVersion === 2) {
-		state.carriedManifestV2 = {
-			tokenDefinitions: manifest.tokenDefinitions,
-			emittedScales: manifest.emittedScales,
-			modeAliasDefinitions: manifest.modeAliasDefinitions,
-			registrations: manifest.registrations,
-			emitterVersion: manifest.emitterVersion,
-			contractHash: manifest.contractHash,
-			cssFragments: manifest.cssFragments
-		};
-		if (manifest.registrations) for (const [name, registration] of Object.entries(manifest.registrations)) {
-			const existing = state.contextualVarRegistrations.get(name);
-			if (mergeExtensionState && existing && (existing.syntax !== registration.syntax || existing.inherits !== registration.inherits || existing.initialValue !== registration.initialValue)) throw new Error(`extend: contextual variable '${name}' has divergent @property registrations across extended themes`);
-			state.contextualVarRegistrations.set(name, registration);
-		}
-	} else state.hasLegacyManifestSource = true;
+		state.contextualVars.set(scale, existing ? [.../* @__PURE__ */ new Set([...existing, ...vars])] : [...vars]);
+	}
+	if (manifest) {
+		if (manifest.manifestVersion === 2) {
+			state.carriedManifestV2 = {
+				tokenDefinitions: manifest.tokenDefinitions,
+				emittedScales: manifest.emittedScales,
+				modeAliasDefinitions: manifest.modeAliasDefinitions,
+				registrations: manifest.registrations,
+				emitterVersion: manifest.emitterVersion,
+				contractHash: manifest.contractHash,
+				cssFragments: manifest.cssFragments
+			};
+			if (manifest.registrations) for (const [name, registration] of Object.entries(manifest.registrations)) {
+				const existing = state.contextualVarRegistrations.get(name);
+				if (mergeExtensionState && existing && (existing.syntax !== registration.syntax || existing.inherits !== registration.inherits || existing.initialValue !== registration.initialValue)) throw new Error(`extend: contextual variable '${name}' has divergent @property registrations across extended themes`);
+				state.contextualVarRegistrations.set(name, registration);
+			}
+		} else state.hasLegacyManifestSource = true;
+	}
 }
-/**
-* ThemeScales — the final phase. Has addScale, extendScale, declareContextualVars, build.
-* Also allows addColors and addColorModes for augmentation.
-*/
 var ThemeBuilder = class ThemeBuilder {
 	/** @internal */ _state;
 	constructor(state) {
@@ -1439,15 +1423,8 @@ var ThemeBuilder = class ThemeBuilder {
 		return new ThemeBuilder(copyState(this._state, nextTheme));
 	}
 	/**
-	* FROZEN for the deprecation window (D1/G6): source-WINS precedence over
-	* prior builder state, callable at ANY stage — the phantom Stage passes
-	* through unchanged. Do not add a stage gate; do not flip the merge
-	* direction. Those semantics ship under the new verb only.
-	*
-	* @deprecated Use `extend(source)` — the single extension verb on both
-	* builders: the extended source seeds the base and later local calls win.
-	* `from()` keeps these frozen source-wins semantics for at least one minor
-	* release after `extend()` ships.
+	* Source-WINS precedence over prior builder state, callable at any stage.
+	* @deprecated Use `extend(source)` — the source seeds the base, local wins.
 	*/
 	from(builtTheme) {
 		const source = isLibraryBundle(builtTheme) ? builtTheme.theme ?? builtTheme.tokens ?? {} : builtTheme;
@@ -1462,19 +1439,8 @@ var ThemeBuilder = class ThemeBuilder {
 		return next;
 	}
 	/**
-	* Extend this theme from a consumed library (D1/D2): the source's complete
-	* configuration — tokens, modes, preferences, registrations, emitted-scale
-	* set — seeds the builder as the BASE, and local calls made after
-	* `extend()` win on conflict (the mirror of `from()`'s source-wins).
-	* Chainable and repeatable, but only before augmentation methods ("inherit
-	* first, then extend" — enforced by the phantom builder stage). Accepts a
-	* built theme or a library bundle, consuming the bundle's theme half
-	* (`theme ?? tokens`, D9) and ignoring the rest.
-	*
-	* Sibling conflicts fail loud (D3/G4): a leaf path defined divergently by
-	* two extended sources throws naming the path and both sources
-	* positionally; equal values coalesce silently, and the consumer's own
-	* post-extend `add*` calls override silently (NS-4).
+	* Inherits a built theme or library bundle as the BASE; local calls after
+	* `extend()` win, and leaves that two sources define divergently throw.
 	*/
 	extend(source) {
 		const themeHalf = isLibraryBundle(source) ? source.theme ?? source.tokens ?? {} : source;
@@ -1585,10 +1551,6 @@ var ThemeBuilder = class ThemeBuilder {
 		const nextTheme = merge(deepCopyPlain(this._state.theme), { [key]: updateFn(this._state.theme[key]) });
 		return new ThemeBuilder(copyState(this._state, nextTheme));
 	}
-	/**
-	* Finalize the theme build.
-	* Flattens nested data at the boundary — produces manifest and serialize().
-	*/
 	build() {
 		const theme = deepCopyPlain(this._state.theme);
 		const emittedScales = this._state.emittedScales;
@@ -1721,14 +1683,11 @@ var ThemeBuilder = class ThemeBuilder {
 function createTheme() {
 	return new ThemeBuilder(createState());
 }
-/** Token ref pattern: {scale.key} or {scale.key.sub} */
+/** Authored token reference: `{scale.key}` or `{scale.key/opacity}`. */
 const TOKEN_REF_RE = /\{([^}]+)\}/g;
 /**
-* Flatten the nested theme into dot-path keyed token map and CSS variable declarations.
-* This is the ONLY place where flattening happens. Mode VALUE maps are no
-* longer computed here — they resolve AFTER `resolveReferences` (see
-* {@link resolveModeValueMaps}), closing the G2 gap where mode-override
-* declarations bypassed the resolver.
+* The only flatten pass: nested theme → dot-path token map and variable
+* declarations. Mode value maps resolve later, after `resolveReferences`.
 */
 function flattenTheme(theme, emittedScales, effectiveModes) {
 	const tokenMap = {};
@@ -1775,17 +1734,15 @@ function flattenTheme(theme, emittedScales, effectiveModes) {
 		tokenDefinitions
 	};
 }
-/** Rebuild a record with lexicographically sorted keys (wire determinism, G3). */
+/** Sorted-key rebuild — the serialized wire must not expose insertion order. */
 function sortRecordByKey(record) {
 	const sorted = {};
 	for (const key of Object.keys(record).sort()) sorted[key] = record[key];
 	return sorted;
 }
 /**
-* Collect the AUTHORED mode alias graph: mode name → alias dot-path → the
-* authored color dot-path (manifest v2, D6 — never a resolved value).
-* Empty when the theme has no modes or no colors, mirroring the original
-* flatten-pass guard.
+* The AUTHORED alias graph: mode → alias dot-path → authored color dot-path,
+* never a resolved value.
 */
 function collectAuthoredModeAliases(theme) {
 	const authored = {};
@@ -1802,13 +1759,8 @@ function collectAuthoredModeAliases(theme) {
 	return authored;
 }
 /**
-* D6 coverage over the merged mode set: a CONSUMER-declared mode leaving
-* inherited aliases uncovered must name a base (`basedOn`) whose chain
-* covers them — otherwise the build fails listing the uncovered set.
-* Inherited modes are exempt (a kit's own asymmetry is pre-existing
-* behavior and must round-trip byte-identically). Returns the effective
-* alias map per mode (base-chain fills + authored, authored winning) and
-* one aggregated fill report per mode for the build diagnostic.
+* A CONSUMER-declared mode leaving inherited aliases uncovered must name a
+* base whose chain covers them; inherited modes are exempt.
 */
 function resolveModeCoverage(authoredModeAliases, modeBases, inheritedModes, inheritedModeAliases) {
 	const effectiveModes = {};
@@ -1824,7 +1776,7 @@ function resolveModeCoverage(authoredModeAliases, modeBases, inheritedModes, inh
 				const stillUncovered = [];
 				for (const alias of uncovered) {
 					let cursor = base;
-					const seen = new Set([modeName]);
+					const seen = /* @__PURE__ */ new Set([modeName]);
 					let resolved;
 					while (cursor !== void 0 && !seen.has(cursor)) {
 						seen.add(cursor);
@@ -1854,12 +1806,8 @@ function resolveModeCoverage(authoredModeAliases, modeBases, inheritedModes, inh
 	};
 }
 /**
-* Resolve the per-mode value maps AFTER reference resolution: every mode
-* declaration carries the RESOLVED value of its target color (emitted →
-* the resolved declaration value; inlined → the resolved literal), never
-* the raw flattened string — the G2 closure for `[data-color-mode]` blocks.
-* Modes iterate in sorted name order and lines in sorted property-name
-* order, so mode declaration/insertion order is never observable (G3).
+* Per-mode declarations carry the RESOLVED value of their target color, never
+* the raw flattened string. Modes and lines sort, hiding authoring order.
 */
 function resolveModeValueMaps(effectiveModes, variableMap, variables, tokenMap) {
 	const modeVariables = {};
@@ -1892,12 +1840,8 @@ function resolveModeValueMaps(effectiveModes, variableMap, variables, tokenMap)
 	};
 }
 /**
-* D5 enforcement: a reference whose target is absent from the merged map
-* AND was dropped by an explicit `addScale({ replace: true })` fails the
-* build — unconditional on usage — naming the referencing token (with its
-* positional origin), the replacement call's scale, and the dropped keys.
-* Targets never defined ANYWHERE stay warn-and-literal (supported kit
-* pattern); a re-added key is simply known again and passes.
+* A reference to a target dropped by `addScale({ replace: true })` fails the
+* build. Targets never defined anywhere stay warn-and-literal.
 */
 function assertNoDroppedReferences(tokenDefinitions, flatTokenMap, droppedTokenPaths, extendProvenance) {
 	if (droppedTokenPaths.size === 0) return;
@@ -1918,9 +1862,8 @@ function assertNoDroppedReferences(tokenDefinitions, flatTokenMap, droppedTokenP
 	}
 	if (violations.length > 0) throw new Error(`build: dangling token reference(s) after explicit scale replacement — ${violations.join("; ")}. Dropped keys: ${[...droppedNamed].sort().join(", ")}.`);
 }
-/** A resolved value still carrying a `{…}` reference — never shippable (G2). */
+/** A resolved value still carrying a `{…}` reference — never shippable. */
 const UNRESOLVED_REF_RE = /\{[^}]+\}/;
-/** Custom-property names referenced through `var(--name)` in a value. */
 const VAR_REF_NAME_RE = /var\(\s*(--[\w-]+)/g;
 function varRefNames(value) {
 	const names = [];
@@ -1928,18 +1871,8 @@ function varRefNames(value) {
 	return names;
 }
 /**
-* Split root and mode variable maps into shippable declarations and omitted
-* var names (G2): any value still containing `{…}` after resolution — a
-* direct or TRANSITIVE never-defined target — is withheld from emitted CSS.
-*
-* Withholding must follow `var()` indirection too: flattenTheme synthesizes
-* the initial mode's aliases as `var(--target)` BEFORE resolution, so a
-* withheld target would otherwise leave an emitted alias pointing at a
-* declaration that exists nowhere. A declaration is dangling when a var()
-* target of its value was DECLARED in this build but withheld everywhere
-* the declaration can see (:root for root declarations; the same mode
-* block or :root for mode declarations); chains drop to a fixpoint. Var
-* names never declared here (breakpoints, contextual vars) are exempt.
+* Withholds any declaration whose value still contains `{…}`, then — to a
+* fixpoint — any whose `var()` target was withheld everywhere it can see.
 */
 function omitUnresolvedDeclarations(variables, modeVariables) {
 	const omitted = [];
@@ -1988,11 +1921,8 @@ function omitUnresolvedDeclarations(variables, modeVariables) {
 	};
 }
 /**
-* Classify a RAW token value into its authored form (manifest v2, D6). MUST
-* run before `resolveReferences` — resolution rewrites the string, and the
-* authored graph cannot be reconstructed from resolved CSS (D8). Uses
-* `matchAll` so the shared global {@link TOKEN_REF_RE} never carries a stale
-* `lastIndex` between callers.
+* Classifies a RAW token value into its authored form. `matchAll` keeps the
+* shared global {@link TOKEN_REF_RE} from carrying a stale `lastIndex`.
 */
 function parseTokenDefinition(rawValue) {
 	const references = [];
@@ -2016,15 +1946,12 @@ function parseTokenDefinition(rawValue) {
 }
 /**
 * Version of the CSS emitter that composed a manifest's fragments. Bump when
-* ANY emitted byte changes for the same authored input — composition (D8)
-* regenerates dirty sections "under the pinned emitter version", and this is
-* that pin.
+* any emitted byte changes for the same authored input.
 */
 const EMITTER_VERSION = 1;
 /**
-* Sorted-key canonical form for hashing: object keys are emitted in sorted
-* order at every depth so the digest is independent of insertion order;
-* arrays keep authored order (reference order is contractual).
+* Keys sort at every depth so the digest ignores insertion order; arrays keep
+* authored order, which is contractual.
 */
 function canonicalize(value) {
 	if (Array.isArray(value)) return value.map(canonicalize);
@@ -2037,13 +1964,8 @@ function canonicalize(value) {
 	return value;
 }
 /**
-* sha256 hex digest. Primary path is `node:crypto` `createHash('sha256')`,
-* reached via `process.getBuiltinModule` so this module gains NO static
-* `node:crypto` import edge: built themes execute inside client bundles today
-* (e2e fixtures inline `createTheme(…).build()` at module init), and a static
-* builtin import is exactly what `./bootstrap` documents as forbidden in app
-* bundles. Non-Node runtimes use the pure fallback below, which produces
-* identical hex for identical input — determinism holds across environments.
+* Reached through `process.getBuiltinModule` so this module gains no static
+* `node:crypto` import edge — built themes run inside client bundles.
 */
 function sha256Hex(input) {
 	const nodeCrypto = globalThis.process?.getBuiltinModule?.("node:crypto");
@@ -2121,11 +2043,8 @@ function rotr(x, n) {
 	return (x >>> n | x << 32 - n) >>> 0;
 }
 /**
-* UTF-8 bytes of `input` without WHATWG `TextEncoder`: the Rust system-loader
-* evaluates the system bundle in QuickJS, which provides ES built-ins only —
-* no Node globals and no WHATWG APIs. Iterating by code point handles
-* surrogate pairs; lone surrogates cannot reach this path because the input
-* is well-formed `JSON.stringify` output (ES2019 escapes them as `\uXXXX`).
+* UTF-8 bytes without `TextEncoder`: the Rust system-loader evaluates this
+* bundle in QuickJS, which provides ES built-ins only.
 */
 function utf8Bytes(input) {
 	const bytes = [];
@@ -2139,9 +2058,8 @@ function utf8Bytes(input) {
 	return new Uint8Array(bytes);
 }
 /**
-* Pure SHA-256 (FIPS 180-4) over the UTF-8 bytes of `input` — the non-Node
-* fallback for {@link sha256Hex}. Not a security surface: the contract hash
-* is a content digest for composition-identity comparison only.
+* Pure SHA-256 (FIPS 180-4), the non-Node fallback for {@link sha256Hex}. Not
+* a security surface — the contract hash is a content digest only.
 */
 function sha256HexFallback(input) {
 	const bytes = utf8Bytes(input);
@@ -2163,7 +2081,7 @@ function sha256HexFallback(input) {
 		528734635,
 		1541459225
 	]);
-	const w = new Uint32Array(64);
+	const w = /* @__PURE__ */ new Uint32Array(64);
 	for (let offset = 0; offset < paddedLength; offset += 64) {
 		for (let i = 0; i < 16; i++) w[i] = view.getUint32(offset + i * 4);
 		for (let i = 16; i < 64; i++) {
@@ -2206,20 +2124,13 @@ function sha256HexFallback(input) {
 	for (const word of state) hex += word.toString(16).padStart(8, "0");
 	return hex;
 }
-/**
-* Stable digest over the canonical authored inputs. Identical authored input
-* ⇒ identical hash, across processes: keys sort at every depth and
-* `JSON.stringify` drops `undefined`-valued members deterministically.
-*/
+/** Identical authored input ⇒ identical hash, across processes. */
 function computeContractHash(input) {
 	return sha256Hex(JSON.stringify(canonicalize(input)));
 }
 /**
-* Build `@property` registration rules for registered contextual vars.
-* The emitted custom property is `--${name}` — the same name the Rust resolver
-* maps a bare contextual var value to. Rules emit in declaration order and only
-* for names that are genuinely declared contextual vars. Returns `''` when no
-* registration metadata was supplied (opt-in / byte-identical guarantee).
+* `@property` rules for registered contextual vars, emitted as `--${name}` —
+* the name the Rust resolver maps a bare contextual var to. `''` when none.
 */
 function buildPropertyRegistrationCss(contextualVars, registrations) {
 	if (registrations.size === 0) return "";
@@ -2234,7 +2145,6 @@ function buildPropertyRegistrationCss(contextualVars, registrations) {
 	}
 	return blocks.join("\n");
 }
-/** Build CSS variable blocks from flattened data. */
 function buildVariableCss(rootVariables, breakpointVariables, modeVariables, systemEmission = {}) {
 	const { initialMode, systemPreference, browserColorScheme } = systemEmission;
 	const parts = [];