@yahoo/uds-create-config 5.25.2 → 5.27.0

package/dist/framework/config-ops.js

@@ -75,6 +75,19 @@ function authoringSignature(schema, options) {
 	const json = jsonSchema(schema);
 	return json === void 0 ? void 0 : renderSignature(withoutMetadata(json), options);
 }
+/**
+* A real entry, spelled the way it is authored. A collection whose schema offers only a list (see
+* `withDeprecated`) is stored as the record keyed by its members, so the example writes its members
+* as that list, and a reader copying it never learns the deprecated record.
+*/
+function authoredExample({ item, fields }) {
+	const body = item.toJSON();
+	const properties = fields?.properties;
+	if (!properties) return { [item.path]: body };
+	const authored = { ...body };
+	for (const [field, value] of Object.entries(body)) if (properties[field]?.type === "array" && value && typeof value === "object" && !Array.isArray(value)) authored[field] = Object.values(value);
+	return { [item.path]: authored };
+}
 /** Every owned kind's authoring shape as signatures, with a real example where the config has one. */
 function authoringSignatures(config, { depth, memberDepth = depth } = {}) {
 	return config.ownedKinds().flatMap((kind) => {
@@ -87,14 +100,18 @@ function authoringSignatures(config, { depth, memberDepth = depth } = {}) {
 			if (signature) collections[field] = singleton ? `one section, no key (\`sub-update/${field}\`): ${signature}` : signature;
 		}
 		const first = config.list(kind)[0];
+		const create = dataSchemaOf(config, entity.schemas.create);
 		return [{
 			kind,
 			label: entity.label,
 			refHelper: entity.entityName,
-			create: authoringSignature(dataSchemaOf(config, entity.schemas.create), { depth }),
+			create: authoringSignature(create, { depth }),
 			collections,
 			group: authoringSignature(entity.groupCreateSchema, { depth }),
-			example: first ? { [first.path]: first.toJSON() } : void 0
+			example: first ? authoredExample({
+				item: first,
+				fields: jsonSchema(create)
+			}) : void 0
 		}];
 	});
 }
@@ -137,14 +154,18 @@ function authoringReference(config) {
 			collections[field] = jsonSchema(dataSchemaOf(config, entity.schemas[`sub-create/${field}`]));
 		}
 		const first = config.list(kind)[0];
+		const fields = jsonSchema(dataSchemaOf(config, entity.schemas.create));
 		return [{
 			kind,
 			label: entity.label,
 			refHelper: entity.entityName,
-			fields: jsonSchema(dataSchemaOf(config, entity.schemas.create)),
+			fields,
 			collections,
 			groupFields: jsonSchema(entity.groupCreateSchema),
-			example: first ? { [first.path]: first.toJSON() } : void 0
+			example: first ? authoredExample({
+				item: first,
+				fields
+			}) : void 0
 		}];
 	}) };
 }

package/dist/framework/defineSubEntity.d.ts

@@ -36,6 +36,9 @@ type SubEntityClass<F extends z.ZodTypeAny = z.ZodTypeAny> = CollectionSchema<F>
    *  caller, so key and value can't drift, two members with the same identity can't both exist, and
    *  an edit that changes the identity moves the entry. Omit when the key is arbitrary. */
   readonly key?: (member: unknown) => string;
+  /** The collection is authored as a list of its members, which carry their own `key`. The keyed
+   *  record it is stored as is still read but no longer offered: see {@link orList}. */
+  readonly listed?: true;
   /** Whether a member DECLARES nothing — a style rule whose every layer bag is empty. Asked only
    *  when a \`sub-update\` would bring the member into being: a delta made entirely of removals has
    *  nothing to remove from a member that is not there, so creating one files an entry that emits
@@ -143,6 +146,7 @@ declare function defineSubEntity<F extends z.ZodTypeAny>(spec: {
    */
   base?: z.ZodTypeAny;
   key?: (member: unknown) => string;
+  listed?: true;
   vacant?: (member: unknown) => boolean;
   schemas?: UserSchemas;
   namespaces?: string;
@@ -161,6 +165,9 @@ declare function defineSubEntity<F extends z.ZodTypeAny>(spec: {
  * Two members with the same key are one member, the later one, as the key derivation on write
  * already treats a record whose keys disagree with their members — unless `merge` says how the two
  * combine, in which case the member is `merge(earlier, later)`, placed where the later one was.
+ *
+ * A collection declared `listed` still takes the keyed record but offers only the list, see
+ * {@link withDeprecated}.
  */
 declare function orList<F extends z.ZodTypeAny>(collection: SubEntityClass<F>, {
   merge

package/dist/framework/defineSubEntity.js

@@ -1,6 +1,7 @@
 import { kindOf, memberOf, memberRef, pathOf } from "./utils/refs.js";
 import { resolveSchema } from "./schemas.js";
 import { titleCase } from "./registry.js";
+import { withDeprecated } from "./utils/deprecated.js";
 import { z } from "zod";
 //#region src/framework/defineSubEntity.ts
 /**
@@ -78,6 +79,7 @@ function defineSubEntity(spec) {
 		fields: spec.fields,
 		base: spec.base,
 		key: spec.key,
+		...spec.listed ? { listed: true } : {},
 		vacant: spec.vacant,
 		schemas: spec.schemas,
 		namespaces: spec.namespaces,
@@ -126,6 +128,9 @@ function defineSubEntity(spec) {
 * Two members with the same key are one member, the later one, as the key derivation on write
 * already treats a record whose keys disagree with their members — unless `merge` says how the two
 * combine, in which case the member is `merge(earlier, later)`, placed where the later one was.
+*
+* A collection declared `listed` still takes the keyed record but offers only the list, see
+* {@link withDeprecated}.
 */
 function orList(collection, { merge } = {}) {
 	const key = collection.key;
@@ -142,6 +147,10 @@ function orList(collection, { merge } = {}) {
 		}
 		return keyed;
 	});
+	if (collection.listed) return withDeprecated({
+		offered: listed,
+		deprecated: collection
+	});
 	return z.union([listed, collection]);
 }
 //#endregion

package/dist/framework/interaction-conditions.d.ts

@@ -0,0 +1,48 @@
+import { Config } from "./Config.js";
+
+//#region src/framework/interaction-conditions.d.ts
+/** One interaction a rule keys on: the bag key, the modifier it resolves to, and whose it is. */
+interface InteractionCondition {
+  /** As written in `when`: `_hover`. */
+  readonly key: string;
+  /** The modifier's path: `state/hover`. */
+  readonly modifier: string;
+  /** The layer whose interaction it is — the root for `true`. */
+  readonly layer: string;
+}
+/** Whether `modifier` (a path or leaf) can be a rule's interaction condition. */
+declare function isInteractionModifier(config: Config, modifier: string): boolean;
+/** The `when` key an interaction modifier is written under: its leaf, `_hover`. */
+declare function interactionKey(modifier: string): string;
+/** Every interaction modifier the config declares, by path. */
+declare function interactionModifiers(config: Config): ReadonlySet<string>;
+/**
+ * A rule's condition split in two: the props and states the render tests, and the interactions the
+ * stylesheet (or, for what CSS can't do, the module's own event tracking) holds it under.
+ */
+declare function whenParts({
+  config,
+  when,
+  layers
+}: {
+  config: Config;
+  when: Readonly<Record<string, unknown>> | null | undefined; /** The component's layers, for the root an interaction's `true` names. */
+  layers?: Readonly<Record<string, unknown>>;
+}): {
+  props: Record<string, unknown>;
+  interactions: InteractionCondition[];
+};
+/** Whether `when` names any interaction — what tells the readers a rule holds only under one. */
+declare function hasInteraction(config: Config, when: Readonly<Record<string, unknown>> | null | undefined): boolean;
+/** One interaction a component's rules key on, with the selector that tells whether it holds. */
+interface ComponentInteraction extends InteractionCondition {
+  /** The modifier's own selector, without its leading `&` (`:hover`): what `element.matches` asks. */
+  readonly selector: string;
+}
+/**
+ * Every interaction a component's rules key on, once per key and layer — what a surface that renders
+ * the component from its config, with no module to track them, watches on the live element.
+ */
+declare function componentInteractions(config: Config, path: string): ComponentInteraction[];
+//#endregion
+export { ComponentInteraction, InteractionCondition, componentInteractions, hasInteraction, interactionKey, interactionModifiers, isInteractionModifier, whenParts };

package/dist/framework/interaction-conditions.js

@@ -0,0 +1,104 @@
+import { modifierCategory } from "../entities/system/modifier-axis.js";
+import { rootLayerOf } from "../entities/system/element.js";
+import { createSliceMemo } from "./memo.js";
+//#region src/framework/interaction-conditions.ts
+/**
+* A style rule's interaction conditions: `when: { _hover: true }`, "while the component is hovered".
+*
+* A rule's `when` names props and states, which the render knows. An interaction is the browser's —
+* the pointer is over an element, it is pressed, it has focus — and a rule may key on one the same
+* way, so the rule's whole reach (styles, an instance's props, content) applies while it holds. The
+* value names whose interaction it is: `true` is the component's own root, and a layer name is that
+* layer (`_hover: 'closeButton'`, "while the close button is hovered").
+*
+* Only an interaction modifier qualifies: a selector modifier that isn't a mode and names a state of
+* the element itself (`:hover`, `[aria-checked="true"]`), never a pseudo-element (`::placeholder`)
+* or a relation to another element (`[data-group]:hover &`).
+*/
+/** Whether `modifier` (a path or leaf) can be a rule's interaction condition. */
+function isInteractionModifier(config, modifier) {
+	return interactionModifiers(config).has(config.resolve("modifier", modifier)?.path ?? "");
+}
+/** The `when` key an interaction modifier is written under: its leaf, `_hover`. */
+function interactionKey(modifier) {
+	return `_${modifier.slice(modifier.lastIndexOf("/") + 1)}`;
+}
+/** Every interaction modifier the config declares, by path. */
+function interactionModifiers(config) {
+	return interactionMemo(config);
+}
+const interactionMemo = createSliceMemo({
+	kinds: ["modifier"],
+	compute: (config) => {
+		const paths = /* @__PURE__ */ new Set();
+		for (const modifier of config.list("modifier")) {
+			const { type, value } = modifier.toJSON() ?? {};
+			if (type !== "selector" || typeof value !== "string") continue;
+			if (modifierCategory(config, modifier.path) === "mode") continue;
+			const own = value.trim().replace(/^&/, "");
+			if (own.includes("::") || own.includes("&") || /\s/.test(own)) continue;
+			paths.add(modifier.path);
+		}
+		return paths;
+	}
+});
+/**
+* A rule's condition split in two: the props and states the render tests, and the interactions the
+* stylesheet (or, for what CSS can't do, the module's own event tracking) holds it under.
+*/
+function whenParts({ config, when, layers }) {
+	const props = {};
+	const interactions = [];
+	const root = layers ? rootLayerOf(layers)[0] : "root";
+	for (const [key, value] of Object.entries(when ?? {})) {
+		const modifier = key.startsWith("_") ? config.resolve("modifier", key.slice(1)) : void 0;
+		if (modifier && interactionModifiers(config).has(modifier.path)) {
+			if (value === false || value === "false" || value == null) continue;
+			interactions.push({
+				key,
+				modifier: modifier.path,
+				layer: value === true || value === "true" ? root : String(value)
+			});
+			continue;
+		}
+		props[key] = value;
+	}
+	return {
+		props,
+		interactions
+	};
+}
+/** Whether `when` names any interaction — what tells the readers a rule holds only under one. */
+function hasInteraction(config, when) {
+	return whenParts({
+		config,
+		when
+	}).interactions.length > 0;
+}
+/**
+* Every interaction a component's rules key on, once per key and layer — what a surface that renders
+* the component from its config, with no module to track them, watches on the live element.
+*/
+function componentInteractions(config, path) {
+	const body = config.resolve("component", path)?.toJSON();
+	const out = [];
+	for (const rule of Object.values(body?.styles ?? {})) {
+		const { interactions } = whenParts({
+			config,
+			when: rule.when,
+			layers: body?.layers
+		});
+		for (const interaction of interactions) {
+			if (out.some((seen) => seen.key === interaction.key && seen.layer === interaction.layer)) continue;
+			const value = (config.resolve("modifier", interaction.modifier)?.toJSON())?.value;
+			if (typeof value !== "string") continue;
+			out.push({
+				...interaction,
+				selector: value.trim().replace(/^&/, "")
+			});
+		}
+	}
+	return out;
+}
+//#endregion
+export { componentInteractions, hasInteraction, interactionKey, interactionModifiers, isInteractionModifier, whenParts };

package/dist/framework/layer-styles.d.ts

@@ -2,7 +2,11 @@ import { Config } from "./Config.js";
 
 //#region src/framework/layer-styles.d.ts
 /** Whether every prop a rule names holds the value it asks for. Compared as strings, because a
- *  condition is canonicalized into the rule's key and a variant value is a string there. */
+ *  condition is canonicalized into the rule's key and a variant value is a string there.
+ *
+ *  An interaction (`_hover`, see `interaction-conditions`) holds only when the state says it does —
+ *  `{ _hover: true }`, a surface forcing it — whichever layer the rule names: no prop bag is ever
+ *  hovered, so at rest the rule is out. */
 declare function ruleApplies(when: Record<string, unknown> | null | undefined, state: Record<string, unknown>): boolean;
 interface LayerStyleOptions {
   /**

package/dist/framework/layer-styles.js

@@ -2,9 +2,20 @@ import { isRef, refLeaf } from "./utils/refs.js";
 import { authoredBag } from "./projections.js";
 //#region src/framework/layer-styles.ts
 /** Whether every prop a rule names holds the value it asks for. Compared as strings, because a
-*  condition is canonicalized into the rule's key and a variant value is a string there. */
+*  condition is canonicalized into the rule's key and a variant value is a string there.
+*
+*  An interaction (`_hover`, see `interaction-conditions`) holds only when the state says it does —
+*  `{ _hover: true }`, a surface forcing it — whichever layer the rule names: no prop bag is ever
+*  hovered, so at rest the rule is out. */
 function ruleApplies(when, state) {
-	return Object.entries(when ?? {}).every(([prop, value]) => String(state[prop]) === String(refLeaf(value)));
+	return Object.entries(when ?? {}).every(([prop, value]) => prop.startsWith("_") ? interactionHolds(state, prop, value) : String(state[prop]) === String(refLeaf(value)));
+}
+/** Whether an interaction holds: forced for the whole component (`_hover: true`, a surface's pin), or
+*  reported for the layer the condition names (`'_hover@close': true`, a live pointer). */
+function interactionHolds(state, key, value) {
+	const on = (held) => held === true || held === "true";
+	if (on(state[key])) return true;
+	return on(state[`${key}@${value === true || value === "true" ? "root" : String(value)}`]);
 }
 /**
 * Merge a bag over another, flattening any forced modifier block as it goes.
@@ -14,15 +25,17 @@ function ruleApplies(when, state) {
 * with" for a panel and a matrix cell, and a picker's options are leaves.
 */
 function mergeBag(into, bag, forced) {
+	const forcedBlocks = [];
 	for (const [key, value] of Object.entries(bag)) {
 		const modifier = key.startsWith("_") ? key.slice(1) : void 0;
 		if (modifier && value && typeof value === "object" && !isRef(value)) {
-			if (forced.includes(modifier)) mergeBag(into, value, forced);
+			if (forced.includes(modifier)) forcedBlocks.push(value);
 			else into[key] = value;
 			continue;
 		}
 		into[key] = value;
 	}
+	for (const block of forcedBlocks) mergeBag(into, block, forced);
 }
 /**
 * The resolved style bag per layer, for the props an instance was given.
@@ -36,7 +49,8 @@ function layerStyles(config, path, props = {}, options = {}) {
 		...defaultProps,
 		...props
 	};
-	const forced = options.forced ?? [];
+	const forced = (options.forced ?? []).map((name) => name.replace(/^_/, ""));
+	for (const name of forced) state[`_${name}`] = true;
 	const applicable = Object.values(styles).filter((rule) => ruleApplies(rule.when, state)).sort((left, right) => Object.keys(left.when ?? {}).length - Object.keys(right.when ?? {}).length);
 	const out = {};
 	for (const rule of applicable) for (const [layer, bag] of Object.entries(rule.layers ?? {})) {

package/dist/framework/projections.js

@@ -4,12 +4,13 @@ import { isOklchColor, renderOklch } from "../entities/system/color.js";
 import { isComposedValue, renderComposedValue } from "../entities/system/composed-values.js";
 import { modifierCategory } from "../entities/system/modifier-axis.js";
 import { forwardedPropName, forwardsOf, rootLayerOf } from "../entities/system/element.js";
+import { createSliceMemo } from "./memo.js";
 import { fontFamilyStack } from "../entities/system/Font.js";
 import { listedIn } from "./utils/enumerated.js";
 import "../entities/system/Modifier.js";
-import { createSliceMemo } from "./memo.js";
 import { classPrefixOf, prefixed, varPrefixOf } from "../entities/system/Settings.js";
 import { StyleProperty, leavesOfStylePropValue, numberUnitRefusal } from "../entities/system/StyleProperty.js";
+import { componentStates } from "./component-states.js";
 import { isConditionalPreview, storedPreview, unconditionalPreviewProps } from "./preview-store.js";
 //#region src/framework/projections.ts
 /**
@@ -797,6 +798,10 @@ function authoredBag(config, bag) {
 				continue;
 			}
 		}
+		if (isComposedValue(value)) {
+			out[key] = value;
+			continue;
+		}
 		if (value && typeof value === "object" && !Array.isArray(value) && !isRef(value)) {
 			const inner = authoredBag(config, value);
 			out[key] = inner;
@@ -1792,8 +1797,34 @@ function validateComponentProps(config, componentPath, props) {
 		value: props[LAYER_PROPS],
 		where: componentPath
 	});
+	const states = Object.fromEntries(componentStates(config, componentPath).map((state) => [state.name, {
+		type: state.type,
+		value: state.values
+	}]));
+	const checkState = (name, value) => {
+		if (name.startsWith("_")) {
+			if (modifierCategory(config, name.slice(1)) !== "state") errors.push(`\`${name}\` is not a state modifier`);
+			else if (!["true", "false"].includes(String(value))) errors.push(`\`${name}\` is \`true\` or \`false\`, not \`${String(value)}\``);
+			return;
+		}
+		const state = states[name];
+		if (!state) {
+			errors.push(`\`${name}\` is not a state`);
+			return;
+		}
+		const allowed = state.type === "variant" && Array.isArray(state.value) ? state.value.map(String) : ["true", "false"];
+		if (!allowed.includes(String(value))) errors.push(`state \`${name}\` is ${allowed.map((v) => `\`${v}\``).join(" or ")}, not \`${String(value)}\``);
+	};
 	for (const [name, value] of Object.entries(props)) {
 		if (name === "layerProps") continue;
+		if (name === "__udsForceStates") {
+			for (const [pinned, pin] of Object.entries(value ?? {})) checkState(pinned, pin);
+			continue;
+		}
+		if (states[name]) {
+			errors.push(`\`${name}\` is a state, not a prop — pin it as \`__udsForceStates: { ${name}: … }\``);
+			continue;
+		}
 		const decl = declared[name];
 		if (!decl) {
 			errors.push(`unknown prop \`${name}\``);
@@ -1957,7 +1988,13 @@ function previewMatrix(config, path) {
 		props[prop] = values;
 	};
 	for (const rule of Object.values(styles)) {
-		for (const [prop, stored] of Object.entries(rule.when ?? {})) nameAxisPoint(prop, stored);
+		for (const [prop, stored] of Object.entries(rule.when ?? {})) {
+			if (prop.startsWith("_")) {
+				if (modifierCategory(config, prop.slice(1)) === "state") modifiers.add(prop);
+				continue;
+			}
+			nameAxisPoint(prop, stored);
+		}
 		for (const bag of Object.values(rule.layers ?? {})) for (const key of Object.keys(bag ?? {})) {
 			if (!key.startsWith("_")) continue;
 			if (modifierCategory(config, key.slice(1)) === "state") modifiers.add(key);
@@ -1975,6 +2012,10 @@ function previewMatrix(config, path) {
 			if (values.length > 0) props[name] = values;
 		}
 	}
+	for (const state of componentStates(config, path)) {
+		if (state.type === "boolean") props[state.name] = declaredFirst(["false", "true"], props[state.name] ?? []);
+		if (state.type === "variant") props[state.name] = declaredFirst([...state.values ?? []], props[state.name] ?? []);
+	}
 	return {
 		props,
 		modifiers: [...modifiers]
@@ -1995,6 +2036,7 @@ function declaredFirst(declared, ruleNamed) {
 function propValueFromAxis(config, path, prop, value) {
 	const declared = resolveComponentProps(config, path)[prop];
 	if (declared?.type === "boolean") return value === "true";
+	if (componentStates(config, path).some((state) => state.name === prop && state.type === "boolean")) return value === "true";
 	if (declared?.type === "number") {
 		const parsed = Number(value);
 		return Number.isFinite(parsed) ? parsed : value;

package/dist/framework/render-spec.js

@@ -1,6 +1,7 @@
 import { isRef, kindOf, memberOf, pathOf, ref, splitRef } from "./utils/refs.js";
 import { renderedElement } from "../entities/system/element.js";
 import { createSliceMemo } from "./memo.js";
+import { componentStateDefaults, componentStates } from "./component-states.js";
 import { unconditionalPreviewProps } from "./preview-store.js";
 import { authoredBag, authoredValue, declaredPropDefaults, memberFromLeaf, refListOf, resolveComponentProps, stylePropertyPathFor } from "./projections.js";
 import { slotHostLayer } from "./slot-host.js";
@@ -8,7 +9,7 @@ import { forwardRoutes, forwardedLayers, intoName, isValueSlot, renderBindingsOf
 import { withRequiredContentHidden } from "../entities/system/required-content-layers.js";
 import { inlineMotionProps, jsMotionPresets } from "../entities/system/motion-presets.js";
 import { graftPreviewElements } from "../spec/preview-elements.js";
-import { componentLayerClass, componentPropClasses, componentRuleClasses, layerJsMotionPresets, layerRoutedProps, splitStyleProps, styleRuleMotionClasses } from "./class-names.js";
+import { componentLayerClass, componentPropClasses, componentRuleClasses, componentStateAttributes, forcedModifierAttributes, layerJsMotionPresets, layerRoutedProps, splitStyleProps, styleRuleMotionClasses } from "./class-names.js";
 //#region src/framework/render-spec.ts
 /** A repeat source that is one prop binding: `{ "$state": "/stops" }`, settled by the cell alone. */
 function isStateSource(source) {
@@ -1202,11 +1203,14 @@ function expandInstance(sink, path, instanceProps, content, hint, instanceSlots)
 	const filled = {};
 	for (const [from, fills] of Object.entries(instanceSlots ?? {})) if (fills.length > 0 && instanceProps[from] === void 0) filled[from] = true;
 	const declaredDefaults = declaredPropDefaults(body.props);
+	const pins = instanceProps["__udsForceStates"] ?? {};
 	const state = {
 		...declaredDefaults,
 		...body.defaultProps,
+		...componentStateDefaults(config, path),
 		...filled,
-		...instanceProps
+		...instanceProps,
+		...Object.fromEntries(Object.entries(pins).map(([key, value]) => key.startsWith("_") ? [key, value === true || value === "true"] : [key, value]))
 	};
 	const consumed = consumedProps(config, path, body);
 	const { byLayer: targets } = slotTargets(config, path, body);
@@ -1222,8 +1226,12 @@ function expandInstance(sink, path, instanceProps, content, hint, instanceSlots)
 		...body.defaultProps ?? {},
 		...instanceProps
 	};
+	const stateNames = new Set(componentStates(config, path).map(({ name }) => name));
 	const bag = {};
-	for (const [name, value] of Object.entries(supplied)) if (!consumed.has(name)) bag[name] = value;
+	for (const [name, value] of Object.entries(supplied)) {
+		if (name === "__udsForceStates") continue;
+		if (!consumed.has(name) && !stateNames.has(name)) bag[name] = value;
+	}
 	const { className: styleClasses, rest } = splitStyleProps({
 		config,
 		bag,
@@ -1352,6 +1360,8 @@ function expandInstance(sink, path, instanceProps, content, hint, instanceSlots)
 			...forwarded[layer],
 			...motionPreset !== void 0 ? withoutKey(presetProps[motionPreset], "reducedMotion") : {},
 			...Object.fromEntries((valueRoutes.get(layer) ?? []).filter(({ from }) => state[from] !== void 0).map(({ from, into }) => [into, state[from]])),
+			...isRoot ? componentStateAttributes(componentStates(config, path), state) : {},
+			...isRoot || type === void 0 || kindOf(type) !== "component" ? forcedModifierAttributes(pins, path) : {},
 			...isRoot ? rest : {},
 			...slot && slotValue !== void 0 ? { [intoName(slot.into)]: slotValue } : {},
 			...layerProps[layer],
@@ -1365,7 +1375,7 @@ function expandInstance(sink, path, instanceProps, content, hint, instanceSlots)
 			...authoredProps(config, node.props),
 			[ANATOMY_MARKER]: key
 		};
-		if (node.text !== void 0) props.children = node.text;
+		if (node.text !== void 0 && props.children === void 0) props.children = node.text;
 		for (const [name, value] of Object.entries(props)) {
 			const settled = resolveValue(value, state, resolving);
 			if (settled !== value) props[name] = settled;

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 = 20261012200606;
+declare const CURRENT_SCHEMA_VERSION = 20261013164300;
 /** 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 = 20261012200606;
+const CURRENT_SCHEMA_VERSION = 20261013164300;
 /** 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 > 20261012200606) 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 > 20261013164300) 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 ?? 20261012200606;
+	const target = options?.target ?? 20261013164300;
 	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 ?? 20261012200606;
+	const target = options?.target ?? 20261013164300;
 	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 ?? 20261012200606;
+	const target = options?.target ?? 20261013164300;
 	const entries = [];
 	const held = [];
 	const retired = [];

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

@@ -0,0 +1,18 @@
+/**
+ * A schema that still takes a deprecated form but no longer offers it.
+ *
+ * Parsing accepts `offered` or `deprecated`, so stored data and older config files keep loading.
+ * Rendered as JSON Schema, which is what tool signatures, `config/api`, the MCP's input schemas and
+ * the docs are built from, it shows only `offered`, so nothing that reads a schema learns the old
+ * form.
+ */
+import { z } from 'zod';
+/**
+ * `read` with every deprecated form shown in the JSON Schema it renders. The schema-version tripwire
+ * reads through this, since it guards everything a client accepts, offered or not.
+ */
+export declare function includingDeprecated<T>(read: () => T): T;
+export declare function withDeprecated<O extends z.ZodTypeAny, D extends z.ZodTypeAny>({ offered, deprecated, }: {
+    offered: O;
+    deprecated: D;
+}): z.ZodUnion<readonly [O, D]>;

package/dist/framework/utils/deprecated.js

@@ -0,0 +1,12 @@
+import { z } from "zod";
+function withDeprecated({ offered, deprecated }) {
+	const schema = z.union([offered, deprecated]);
+	const offeredOnly = () => {
+		const { $schema: _dialect, ...json } = z.toJSONSchema(offered, { io: "input" });
+		return json;
+	};
+	schema._zod.toJSONSchema = () => offeredOnly();
+	return schema;
+}
+//#endregion
+export { withDeprecated };

package/dist/framework/validate-spec.js

@@ -1,6 +1,9 @@
 import { kindOf, memberOf, pathOf, splitRef } from "./utils/refs.js";
+import { modifierCategory } from "../entities/system/modifier-axis.js";
 import { childrenPolicy } from "../entities/system/element.js";
+import { UDS_FORCE_STATES, componentStates } from "./component-states.js";
 import { LAYER_PROPS, layerPropsErrors, resolveComponentProps } from "./projections.js";
+import "./class-names.js";
 import { slotOf } from "../spec/slot.js";
 import { refResolves } from "./ref-integrity.js";
 //#region src/framework/validate-spec.ts
@@ -28,8 +31,19 @@ function walk(config, node, path, errors) {
 		errors.push(`${path}: unknown ${kind} "${named}"`);
 	} else if (kind === "component") {
 		const props = resolveComponentProps(config, target);
+		const states = new Set(componentStates(config, target).map(({ name }) => name));
 		for (const name of Object.keys(node.props ?? {})) {
 			if (name === "layerProps") continue;
+			if (name === "__udsForceStates") {
+				for (const pinned of Object.keys(node.props?.["__udsForceStates"] ?? {})) if (pinned.startsWith("_")) {
+					if (modifierCategory(config, pinned.slice(1)) !== "state") errors.push(`${path}: "${pinned}" is not a state modifier`);
+				} else if (!states.has(pinned)) errors.push(`${path}: "${pinned}" is not a state of "${node.type}"`);
+				continue;
+			}
+			if (states.has(name)) {
+				errors.push(`${path}: "${name}" is a state of "${node.type}", not a prop — pin it as ${UDS_FORCE_STATES}: { ${name}: … }`);
+				continue;
+			}
 			if (!(name in props)) errors.push(`${path}: unknown prop "${name}" on "${node.type}"`);
 		}
 		errors.push(...layerPropsErrors({