@yahoo/uds-create-config 5.25.2 → 5.27.0

package/dist/configs/react-native-system.d.ts

@@ -69,10 +69,19 @@ declare const ReactNativeSystemDefinition: ConfigClass<{
   tokens: EntityClass<_$zod.ZodObject<Omit<{
     value: _$zod.ZodType<string | number | Ref | ComposedValue, unknown, _$zod_v4_core0.$ZodTypeInternals<string | number | Ref | ComposedValue, unknown>>;
     type: _$zod.ZodOptional<_$zod.ZodString>;
-    overrides: _$zod.ZodOptional<SubEntityClass<_$zod.ZodObject<{
+    overrides: _$zod.ZodOptional<_$zod.ZodUnion<readonly [_$zod.ZodPipe<_$zod.ZodArray<_$zod.ZodObject<{
       on: _$zod.ZodType<OverrideCondition, unknown, _$zod_v4_core0.$ZodTypeInternals<OverrideCondition, unknown>>;
       value: _$zod.ZodType<string | number | Ref | ComposedValue, unknown, _$zod_v4_core0.$ZodTypeInternals<string | number | Ref | ComposedValue, unknown>>;
-    }, _$zod_v4_core0.$strip>>>;
+    }, _$zod_v4_core0.$strip>>, _$zod.ZodTransform<Record<string, {
+      on: OverrideCondition;
+      value: string | number | Ref | ComposedValue;
+    }>, {
+      on: OverrideCondition;
+      value: string | number | Ref | ComposedValue;
+    }[]>>, SubEntityClass<_$zod.ZodObject<{
+      on: _$zod.ZodType<OverrideCondition, unknown, _$zod_v4_core0.$ZodTypeInternals<OverrideCondition, unknown>>;
+      value: _$zod.ZodType<string | number | Ref | ComposedValue, unknown, _$zod_v4_core0.$ZodTypeInternals<string | number | Ref | ComposedValue, unknown>>;
+    }, _$zod_v4_core0.$strip>>]>>;
     utility: _$zod.ZodOptional<_$zod.ZodBoolean>;
     property: _$zod.ZodOptional<_$zod.ZodObject<{
       syntax: _$zod.ZodOptional<_$zod.ZodString>;
@@ -81,10 +90,19 @@ declare const ReactNativeSystemDefinition: ConfigClass<{
     cssVariable: _$zod.ZodOptional<_$zod.ZodUnion<readonly [_$zod.ZodString, _$zod.ZodLiteral<false>]>>;
   }, "value" | "property" | "overrides" | "cssVariable"> & {
     value: _$zod.ZodType<string | number | boolean | Ref | DerivedColor, unknown, _$zod_v4_core0.$ZodTypeInternals<string | number | boolean | Ref | DerivedColor, unknown>>;
-    overrides: _$zod.ZodOptional<SubEntityClass<_$zod.ZodObject<{
+    overrides: _$zod.ZodOptional<_$zod.ZodUnion<readonly [_$zod.ZodPipe<_$zod.ZodArray<_$zod.ZodObject<{
+      on: _$zod.ZodType<OverrideCondition, unknown, _$zod_v4_core0.$ZodTypeInternals<OverrideCondition, unknown>>;
+      value: _$zod.ZodType<string | number | boolean | Ref | DerivedColor, unknown, _$zod_v4_core0.$ZodTypeInternals<string | number | boolean | Ref | DerivedColor, unknown>>;
+    }, _$zod_v4_core0.$strip>>, _$zod.ZodTransform<Record<string, {
+      on: OverrideCondition;
+      value: string | number | boolean | Ref | DerivedColor;
+    }>, {
+      on: OverrideCondition;
+      value: string | number | boolean | Ref | DerivedColor;
+    }[]>>, SubEntityClass<_$zod.ZodObject<{
       on: _$zod.ZodType<OverrideCondition, unknown, _$zod_v4_core0.$ZodTypeInternals<OverrideCondition, unknown>>;
       value: _$zod.ZodType<string | number | boolean | Ref | DerivedColor, unknown, _$zod_v4_core0.$ZodTypeInternals<string | number | boolean | Ref | DerivedColor, unknown>>;
-    }, _$zod_v4_core0.$strip>>>;
+    }, _$zod_v4_core0.$strip>>]>>;
   }, _$zod_v4_core0.$strip>, _$zod.ZodObject<Omit<{
     cssPrefix: _$zod.ZodOptional<_$zod.ZodString>;
     cssVariables: _$zod.ZodOptional<_$zod.ZodBoolean>;

package/dist/configs/system.js

@@ -66,6 +66,8 @@ import { startingStyleModifierMigration } from "../migrations/20261009022722_sta
 import { cssMotionStrictMigration } from "../migrations/20261009181635_css_motion_strict.js";
 import { linkOverrideRefMigration } from "../migrations/20261009193004_link_override_ref.js";
 import { linkedComponentModulesMigration } from "../migrations/20261012200606_linked_component_modules.js";
+import { componentStatesMigration } from "../migrations/20261013154037_component_states.js";
+import { tokenOverridesListMigration } from "../migrations/20261013164300_token_overrides_list.js";
 const System = defineConfig({
 	name: WEB_CONFIG_NAME,
 	description: "A design system: the values, primitives and compositions an app is built from. A ref is written `{ \"__ref\": \"<kind>:<path>\" }`, so a token is `{ \"__ref\": \"token:<group>/<name>\" }` and a token group is `{ \"__ref\": \"token:<group>\" }`. Build it in this order. Tokens first, in groups by purpose (colors, spacing, radii, type sizes), since everything else names them. Then style properties, each with `values` holding one ref to the token group whose members it accepts (`{ \"__ref\": \"token:color\" }`), so a prop takes token names rather than raw CSS; add a string keyword only for a value no token holds. A style rule's bag holds a prop's values (`\"padding\": \"4\"`, `\"bg\": \"brand\"`), never raw CSS. Then a few primitive components, one layer each, whose props are style properties (a box for layout and surface, a text for type, a pressable for interaction). Then every other component composed from those primitives: its layers name a primitive or an element, its anatomy places them (a node renders a layer, a tag or `Slot` where a slot prop's content lands; `children` is the edge list; `visible` is `{ \"$state\": \"<prop>\" }`; a prop shown in a nested layer is a `forward` route, and `$state` never sits in a node's props), and its style rules set style-property values per layer, keyed by prop values when a variant changes them. Modes (a dark mode is `{ type: \"selector\", value: \".dark\" }`) change token values through a token's `overrides`, so a component never restyles for a mode; modifiers (hover, focus, disabled) name a state, and a style rule applies under one as a `_hover` block inside a layer bag. Composites bundle style values that recur. Last, register canvas roles: the canvas draws with them, one entity per tool (`frame` for the layout primitive, `text` for the text primitive, `image`) whose entries name the components that tool inserts, and a tool whose role is unregistered is disabled. Give each component a `preview` entry under `*` so it shows content, and never write a CSS property name where a style-property name belongs.",
@@ -143,5 +145,7 @@ if (!registeredSchemaMigrations().has(20261009022722)) registerSchemaMigrations(
 if (!registeredSchemaMigrations().has(20261009181635)) registerSchemaMigrations(cssMotionStrictMigration);
 if (!registeredSchemaMigrations().has(20261009193004)) registerSchemaMigrations(linkOverrideRefMigration);
 if (!registeredSchemaMigrations().has(20261012200606)) registerSchemaMigrations(linkedComponentModulesMigration);
+if (!registeredSchemaMigrations().has(20261013154037)) registerSchemaMigrations(componentStatesMigration);
+if (!registeredSchemaMigrations().has(20261013164300)) registerSchemaMigrations(tokenOverridesListMigration);
 //#endregion
 export { System };

package/dist/entities/native/NativeToken.d.ts

@@ -12,10 +12,19 @@ declare const nativeTokenValue: z.ZodType<number | boolean | string | Ref$1 | De
 declare const NativeToken: EntityClass<z.ZodObject<Omit<{
   value: z.ZodType<string | number | Ref | ComposedValue, unknown, z.core.$ZodTypeInternals<string | number | Ref | ComposedValue, unknown>>;
   type: z.ZodOptional<z.ZodString>;
-  overrides: z.ZodOptional<SubEntityClass<z.ZodObject<{
+  overrides: z.ZodOptional<z.ZodUnion<readonly [z.ZodPipe<z.ZodArray<z.ZodObject<{
     on: z.ZodType<OverrideCondition, unknown, z.core.$ZodTypeInternals<OverrideCondition, unknown>>;
     value: z.ZodType<string | number | Ref | ComposedValue, unknown, z.core.$ZodTypeInternals<string | number | Ref | ComposedValue, unknown>>;
-  }, z.core.$strip>>>;
+  }, z.core.$strip>>, z.ZodTransform<Record<string, {
+    on: OverrideCondition;
+    value: string | number | Ref | ComposedValue;
+  }>, {
+    on: OverrideCondition;
+    value: string | number | Ref | ComposedValue;
+  }[]>>, SubEntityClass<z.ZodObject<{
+    on: z.ZodType<OverrideCondition, unknown, z.core.$ZodTypeInternals<OverrideCondition, unknown>>;
+    value: z.ZodType<string | number | Ref | ComposedValue, unknown, z.core.$ZodTypeInternals<string | number | Ref | ComposedValue, unknown>>;
+  }, z.core.$strip>>]>>;
   utility: z.ZodOptional<z.ZodBoolean>;
   property: z.ZodOptional<z.ZodObject<{
     syntax: z.ZodOptional<z.ZodString>;
@@ -24,10 +33,19 @@ declare const NativeToken: EntityClass<z.ZodObject<Omit<{
   cssVariable: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodLiteral<false>]>>;
 }, "value" | "property" | "overrides" | "cssVariable"> & {
   value: z.ZodType<string | number | boolean | Ref | DerivedColor, unknown, z.core.$ZodTypeInternals<string | number | boolean | Ref | DerivedColor, unknown>>;
-  overrides: z.ZodOptional<SubEntityClass<z.ZodObject<{
+  overrides: z.ZodOptional<z.ZodUnion<readonly [z.ZodPipe<z.ZodArray<z.ZodObject<{
+    on: z.ZodType<OverrideCondition, unknown, z.core.$ZodTypeInternals<OverrideCondition, unknown>>;
+    value: z.ZodType<string | number | boolean | Ref | DerivedColor, unknown, z.core.$ZodTypeInternals<string | number | boolean | Ref | DerivedColor, unknown>>;
+  }, z.core.$strip>>, z.ZodTransform<Record<string, {
+    on: OverrideCondition;
+    value: string | number | boolean | Ref | DerivedColor;
+  }>, {
+    on: OverrideCondition;
+    value: string | number | boolean | Ref | DerivedColor;
+  }[]>>, SubEntityClass<z.ZodObject<{
     on: z.ZodType<OverrideCondition, unknown, z.core.$ZodTypeInternals<OverrideCondition, unknown>>;
     value: z.ZodType<string | number | boolean | Ref | DerivedColor, unknown, z.core.$ZodTypeInternals<string | number | boolean | Ref | DerivedColor, unknown>>;
-  }, z.core.$strip>>>;
+  }, z.core.$strip>>]>>;
 }, z.core.$strip>, z.ZodObject<Omit<{
   cssPrefix: z.ZodOptional<z.ZodString>;
   cssVariables: z.ZodOptional<z.ZodBoolean>;

package/dist/entities/native/NativeToken.js

@@ -1,5 +1,6 @@
 import { refSchema } from "../../framework/utils/refs.js";
 import { oklchColor } from "../system/color.js";
+import { orList } from "../../framework/defineSubEntity.js";
 import { Font } from "../system/Font.js";
 import { NATIVE_CONFIG_NAME } from "../../configs/platform.js";
 import { prepareLinkedTokenBody } from "../system/linked-token-values.js";
@@ -66,7 +67,7 @@ const NativeToken = Token.extend({
 	entityName: "NativeToken",
 	fields: {
 		value: nativeTokenValue,
-		overrides: NativeOverride.optional(),
+		overrides: orList(NativeOverride).optional(),
 		cssVariable: null,
 		property: null
 	},

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

@@ -11,7 +11,7 @@ import { StyleClass } from "./style-bag.js";
 import { TokenClass } from "./Token.js";
 import { StoredPreviewCondition } from "../../framework/preview-store.js";
 import { RepeatSpec } from "../../framework/render-spec.js";
-import { AsInput, DefaultsOf, LayerMap, PhantomCallProps, PhantomReadProps, PropMap, RenderArgs, StyleRuleInput } from "./defineComponent.js";
+import { AsInput, DefaultsOf, LayerMap, PhantomCallProps, PhantomReadProps, PropMap, RenderArgs, StateMap, StyleRuleInput } from "./defineComponent.js";
 import { listSlots, namedSlots, slotHostedBy, slotOf, slotsFor } from "../../spec/slot.js";
 import { cellAt } from "../../spec/cell.js";
 import { instanceAt } from "../../spec/instance.js";
@@ -645,6 +645,13 @@ interface AnatomyNodeClass extends Named<typeof AnatomyNodeDefinition> {}
 declare const componentFields: z.ZodObject<{
   layers: LayerClass;
   props: z.ZodOptional<PropClass>;
+  states: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"boolean">;
+  }, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"variant">;
+    value: z.ZodArray<z.ZodString>;
+    default: z.ZodOptional<z.ZodString>;
+  }, z.core.$strict>], "type">>>;
   forwards: z.ZodOptional<ForwardClass>;
   styles: z.ZodOptional<z.ZodUnion<readonly [z.ZodPipe<z.ZodArray<z.ZodType<ComponentStyleBody, unknown, z.core.$ZodTypeInternals<ComponentStyleBody, unknown>>>, z.ZodTransform<Record<string, ComponentStyleBody>, ComponentStyleBody[]>>, SubEntityClass<z.ZodType<ComponentStyleBody, unknown, z.core.$ZodTypeInternals<ComponentStyleBody, unknown>>>]>>;
   renderProps: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -679,6 +686,13 @@ declare function blankComponentBody(): ComponentBody;
 declare const ComponentEntity: EntityClass<z.ZodObject<{
   layers: LayerClass;
   props: z.ZodOptional<PropClass>;
+  states: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"boolean">;
+  }, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"variant">;
+    value: z.ZodArray<z.ZodString>;
+    default: z.ZodOptional<z.ZodString>;
+  }, z.core.$strict>], "type">>>;
   forwards: z.ZodOptional<ForwardClass>;
   styles: z.ZodOptional<z.ZodUnion<readonly [z.ZodPipe<z.ZodArray<z.ZodType<ComponentStyleBody, unknown, z.core.$ZodTypeInternals<ComponentStyleBody, unknown>>>, z.ZodTransform<Record<string, ComponentStyleBody>, ComponentStyleBody[]>>, SubEntityClass<z.ZodType<ComponentStyleBody, unknown, z.core.$ZodTypeInternals<ComponentStyleBody, unknown>>>]>>;
   renderProps: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -780,6 +794,19 @@ declare const ComponentEntity: EntityClass<z.ZodObject<{
       }, z.core.$strip>>;
     }, z.core.$strip>;
   };
+  readonly 'element-wrap': {
+    readonly input: z.ZodObject<{
+      path: z.ZodType<string, string | undefined, z.core.$ZodTypeInternals<string, string | undefined>>;
+      key: z.ZodOptional<z.ZodString>;
+      data: z.ZodObject<{
+        elements: z.ZodArray<z.ZodString>;
+        element: z.ZodDefault<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+          __ref: z.ZodString;
+        }, z.core.$strip>]>>;
+        props: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+      }, z.core.$strip>;
+    }, z.core.$strip>;
+  };
   readonly validate: {
     readonly input: z.ZodObject<{
       path: z.ZodType<string, string | undefined, z.core.$ZodTypeInternals<string, string | undefined>>;
@@ -841,6 +868,12 @@ type ResolvedForwards<Contract, Delta> = Delta extends {
 } ? Forwards : Contract extends {
   forwards: infer Forwards;
 } ? Forwards : Record<never, never>;
+/** The states an extension ends up with: its delta's, else the linked contract's. */
+type ResolvedStates<Contract, Delta> = Delta extends {
+  readonly states: infer States extends StateMap;
+} ? States : Contract extends {
+  states: infer States extends StateMap;
+} ? States : Record<never, never>;
 type ForwardedLayerNames<Contract, Delta> = ResolvedForwards<Contract, Delta> extends Record<string, unknown> ? keyof ResolvedForwards<Contract, Delta> & string : never;
 /** The source-only half of a linked component extension. The callback is deliberately absent from
  * {@link ExtendedRef}: it is code, so ts-morph reads it from the authoring file while Config stores
@@ -852,7 +885,7 @@ type ExtendedComponentRef<Contract = ComponentContractOf<string>, Delta extends
    * read signature for `ComponentProps`. */
   <As extends AsInput = never>(props: PhantomCallProps<ResolvedLayers<Contract, Delta>, ResolvedProps<Contract, Delta>, ResolvedDefaults<Contract, Delta>, Extra, ForwardedLayerNames<Contract, Delta>, As>): null;
   <As extends AsInput = never>(props: PhantomReadProps<ResolvedLayers<Contract, Delta>, ResolvedProps<Contract, Delta>, ResolvedDefaults<Contract, Delta>, Extra, ForwardedLayerNames<Contract, Delta>, As>): null;
-  render<E = Extra>(fn: (args: RenderArgs<ResolvedLayers<Contract, Delta>, ResolvedProps<Contract, Delta>> & E) => unknown): ExtendedComponentRef<Contract, Delta, E>;
+  render<E = Extra>(fn: (args: RenderArgs<ResolvedLayers<Contract, Delta>, ResolvedProps<Contract, Delta>, ResolvedStates<Contract, Delta>> & E) => unknown): ExtendedComponentRef<Contract, Delta, E>;
   /**
    * Style rules for the extension, typed against the layers it ends up with — the linked contract's,
    * with the delta's replacing them when it declares its own.

package/dist/entities/system/Component.js

@@ -7,6 +7,7 @@ import { shadowValue } from "./shadow.js";
 import { defineEntity } from "../../framework/defineEntity.js";
 import { defineSubEntity, orList } from "../../framework/defineSubEntity.js";
 import { childrenPolicy, forwardedPropName } from "./element.js";
+import { interactionKey, interactionModifiers } from "../../framework/interaction-conditions.js";
 import { listedIn } from "../../framework/utils/enumerated.js";
 import { valueSchemaOf } from "../../framework/value-domain.js";
 import { Package } from "./Package.js";
@@ -712,25 +713,38 @@ function bagFor(config, layerElement) {
 	bags.set(key, built);
 	return built;
 }
+/**
+* A content prop's value in a rule, or `false` for none: a state that drops a Button's start icon
+* says so with `startIcon: false`, since leaving the key out keeps whatever the rule beneath gives.
+* Not for a required prop, whose content is the component's to have.
+*/
+function withNone(value, declaration) {
+	if (declaration?.required === true) return value;
+	return z.union([value, z.literal(false)]);
+}
 /** One element's bag, built. Reached only through the memo above. */
 function buildBagFor(config, layerElement) {
 	const shape = { ...stylePropShape(config) };
 	const component = isRef(layerElement) && config.resolveRef(layerElement.__ref) ? pathOf(layerElement.__ref) : void 0;
 	const glyphProps = component ? glyphPropsOf(config, component) : {};
-	for (const [name, decl] of Object.entries(component ? resolveComponentProps(config, component) : {})) shape[name] = styleBagValue({
-		config,
-		declaration: decl,
-		name,
-		glyphLibraries: decl?.type === "forward" ? glyphProps[name] : void 0
-	}).optional();
+	for (const [name, decl] of Object.entries(component ? resolveComponentProps(config, component) : {})) {
+		const forwarded = decl?.type === "forward";
+		const value = styleBagValue({
+			config,
+			declaration: decl,
+			name,
+			glyphLibraries: forwarded ? glyphProps[name] : void 0
+		});
+		shape[name] = (forwarded ? withNone(value, decl) : value).optional();
+	}
 	const declared = component ? (config.resolve("component", component)?.toJSON())?.props ?? {} : {};
 	for (const [name, decl] of Object.entries(declared)) {
 		if (decl?.type !== "slot" || name in shape) continue;
-		shape[name] = styleBagValue({
+		shape[name] = withNone(styleBagValue({
 			config,
 			declaration: decl,
 			name
-		}).optional();
+		}), decl).optional();
 	}
 	shape.as ??= z.string().optional();
 	for (const [key, owned] of config.layerKeys()) shape[key] = owned.schema(shape[key]).optional();
@@ -808,6 +822,18 @@ function conditionValue(prop, declaration, config) {
 	if (!ownsItsValues(declaration)) return domain;
 	return z.union([domain, refSchema]).transform((value) => isRef(value) ? value : valueRef(prop, String(value)));
 }
+/** The condition on a STATE: a boolean's `true`/`false`, or one of a variant state's names. A state
+*  has no value members to ref, so a variant's condition is the name itself. */
+function stateConditionValue(declaration) {
+	const decl = declaration;
+	if (decl?.type === "variant" && Array.isArray(decl.value)) return z.enum(decl.value);
+	return scalarConditionValue({ type: "boolean" }) ?? z.boolean();
+}
+/** An interaction condition's value: `true` (the root), or the layer whose interaction it is. */
+function interactionConditionValue(layers) {
+	const truthy = z.union([z.literal(true), z.literal("true").transform(() => true)]);
+	return layers.length > 0 ? z.union([truthy, z.enum(layers)], { error: `an interaction condition is \`true\` (the component's root) or one of its layers: ${layers.join(", ")}` }) : truthy;
+}
 /**
 * The condition on a boolean or number prop, in the prop's type. A preview axis spells every value
 * as a string and a rule's key stringifies it, so a writer reading either hands back `'true'` where
@@ -1022,6 +1048,13 @@ const StyleRule = defineSubEntity({
 			build: () => {
 				const when = {};
 				for (const [name, decl] of Object.entries(body.props ?? {})) when[name] = conditionValue(name, decl, config).optional();
+				for (const [name, decl] of Object.entries(body.states ?? {})) when[name] = stateConditionValue(decl).optional();
+				const layerNames = Object.keys(body.layers ?? {});
+				for (const modifier of interactionModifiers(config)) {
+					const key = interactionKey(modifier);
+					if (key in when) continue;
+					when[key] = interactionConditionValue(layerNames).optional();
+				}
 				const layers = {};
 				for (const [name, el] of Object.entries(body.layers ?? {})) layers[name] = bagFor(config, el).optional();
 				return z.strictObject({
@@ -1049,10 +1082,11 @@ function perOwner({ cache, config, owner, build }) {
 		cache.set(config, perConfig);
 	}
 	const hit = perConfig.get(owner);
-	if (hit && hit.props === owner.props && hit.layers === owner.layers) return hit.schema;
+	if (hit && hit.props === owner.props && hit.states === owner.states && hit.layers === owner.layers) return hit.schema;
 	const schema = build();
 	perConfig.set(owner, {
 		props: owner.props,
+		states: owner.states,
 		layers: owner.layers,
 		schema
 	});
@@ -1089,6 +1123,7 @@ const Preview = defineSubEntity({
 			build: () => {
 				const when = {};
 				for (const [name, decl] of Object.entries(body.props ?? {})) when[name] = conditionValue(name, decl, config).optional();
+				for (const [name, decl] of Object.entries(body.states ?? {})) when[name] = stateConditionValue(decl).optional();
 				return z.strictObject({
 					when: z.strictObject(when, { error: previewShapeError }).nullable().default(null),
 					props: z.record(z.string(), z.unknown()).transform((props) => bindPreviewGlyphs({
@@ -1347,6 +1382,83 @@ function anatomySubtreeContains(anatomy, ancestor, key) {
 function resolveMoveBody(config, path) {
 	return config.resolve("component", path)?.toJSON();
 }
+/**
+* Wrap a component's root: the container becomes `root`, and what the root was — its element, its
+* children and slots, its props, the style rules and forwards that name it — moves onto `inner`, the
+* container's one child. Props the config doesn't model (`id`, an `onClick`) keep landing on `root`,
+* which is now the container.
+*/
+function wrapRoot({ config, path, inner, element, props }) {
+	const body = config.resolve("component", path)?.toJSON();
+	const root = body?.anatomy?.root;
+	if (!body || !root) reject("NOT_FOUND", `"${path}" has no root to wrap.`);
+	const { element: _element, ...rootRest } = root;
+	let next = config.apply({
+		kind: "component",
+		operation: "sub-create",
+		path,
+		field: "layers",
+		key: inner,
+		data: body?.layers?.root
+	}).apply({
+		kind: "component",
+		operation: "sub-create",
+		path,
+		field: "anatomy",
+		key: inner,
+		data: {
+			...rootRest,
+			element: layerRef(inner)
+		}
+	}).apply({
+		kind: "component",
+		operation: "sub-upsert",
+		path,
+		field: "layers",
+		key: "root",
+		data: asElementRef(config, element)
+	}).apply({
+		kind: "component",
+		operation: "sub-upsert",
+		path,
+		field: "anatomy",
+		key: "root",
+		data: {
+			element: layerRef("root"),
+			children: [inner],
+			...props ? { props } : {}
+		}
+	});
+	for (const [key, rule] of Object.entries(body?.styles ?? {})) {
+		const bag = rule.layers?.root;
+		if (bag === void 0) continue;
+		next = next.apply({
+			kind: "component",
+			operation: "sub-update",
+			path,
+			field: "styles",
+			key,
+			data: {
+				when: rule.when ?? null,
+				[`layers.${inner}`]: bag,
+				"layers.root": null
+			}
+		});
+	}
+	for (const [name, decl] of Object.entries(body?.props ?? {})) {
+		const target = decl.target;
+		if (!(isRef(target) ? kindOf(target) === "layer" && pathOf(target) === "root" : typeof target === "string" && target.startsWith("root/"))) continue;
+		next = next.apply({
+			kind: "component",
+			operation: "sub-update",
+			path,
+			field: "props",
+			key: name,
+			data: { target: isRef(target) ? layerRef(inner) : `${inner}/${String(target).slice(5)}` }
+		});
+	}
+	return next;
+}
 const AnatomyNode = defineSubEntity({
 	name: "element",
 	label: "Element",
@@ -1538,6 +1650,18 @@ const componentFields = z.strictObject({
 	}),
 	props: Prop.optional(),
 	/**
+	* What the RENDER knows and a style rule keys on — the field has a value, the image loaded, the
+	* indicator is sliding. Not props: a caller never passes one, so none is part of the component's
+	* API. The render passes them to `states(props, { … })` and spreads the layers it hands back;
+	* the rules naming one follow the values given, and the root carries each as a `data-<name>`
+	* attribute. Studio and tests force one through the module's internal channel, never a prop.
+	*/
+	states: z.record(z.string(), z.discriminatedUnion("type", [z.strictObject({ type: z.literal("boolean") }), z.strictObject({
+		type: z.literal("variant"),
+		value: z.array(z.string()).min(1),
+		default: z.string().optional()
+	})])).optional().describe("What the render knows and a style rule keys on, by name: `{ \"filled\": { \"type\": \"boolean\" } }`, or `{ \"phase\": { \"type\": \"variant\", \"value\": [\"idle\", \"sliding\"], \"default\": \"idle\" } }`. Not props, so not part of the component's API: the render passes its `props` and the values it knows to `const layers = states(props, { filled: value !== \"\" })` and spreads those layers (`{...layers.root}`) instead of `props`; a rule naming a state in `when` (`{ \"filled\": true }`, `{ \"phase\": \"sliding\" }`) is tested against the values given, and the root carries each as a `data-<name>` attribute. A value a caller controls is a prop instead, which the render reports the state from."),
+	/**
 	* Which layers' element props this component also exposes — see {@link Forward}.
 	*
 	* Replaced `inherits`, which named one layer and meant `{ [layer]: '*' }`. That field and its
@@ -1598,6 +1722,34 @@ const componentFields = z.strictObject({
 			message: `\`${name}\` conditions on itself. \`when\` names a sibling prop and one of its values.`
 		});
 	}
+	if (isPlainObject(body.states) && Object.keys(body.states).length > 0) {
+		const props = isPlainObject(body.props) ? body.props : {};
+		if (Object.hasOwn(props, "states")) ctx.issues.push({
+			code: "custom",
+			input: props.states,
+			path: ["props", "states"],
+			message: "A component with states hands its render a `states` helper, so no prop of its own can be named `states`."
+		});
+		for (const [name, decl] of Object.entries(body.states)) {
+			if (Object.hasOwn(props, name)) ctx.issues.push({
+				code: "custom",
+				input: decl,
+				path: ["states", name],
+				message: `\`${name}\` is both a prop and a state. A state is what the render knows, never a value a caller passes; a caller-controlled value is a prop the render reports the state from.`
+			});
+			const variant = decl;
+			if (variant?.type === "variant" && variant.default !== void 0 && Array.isArray(variant.value) && !variant.value.includes(variant.default)) ctx.issues.push({
+				code: "custom",
+				input: variant.default,
+				path: [
+					"states",
+					name,
+					"default"
+				],
+				message: `\`${name}\`'s default \`${String(variant.default)}\` is not one of its values (${variant.value.join(", ")}).`
+			});
+		}
+	}
 	if (body.forwards || body.file || isRef(body.props)) return;
 	const declared = body.props ?? {};
 	if (Object.hasOwn(declared, "children") && declared.children !== null) return;
@@ -2328,6 +2480,69 @@ subtree: z.boolean().default(true) }).optional()
 				});
 			}
 		},
+		"element-wrap": {
+			input: z.object({
+				path: pathInput("component"),
+				/** The new layer's name: the wrapper's, or — wrapping the root — the old root's new name. The
+				*  entity mints a free one when the caller doesn't care. */
+				key: z.string().optional(),
+				data: z.object({
+					/** The layers to wrap: siblings under one parent, wrapped in their order, or `['root']`. */
+					elements: z.array(z.string()).min(1),
+					/** What the wrapper renders — a frame component or a tag. */
+					element: z.union([z.string(), refSchema]).default("div"),
+					/** The wrapper's own props. */
+					props: z.record(z.string(), z.unknown()).optional()
+				})
+			}),
+			readOnly: false,
+			label: "Wrap elements",
+			description: "Wrap a component's sibling layers in a new container. Wrapping `root` makes the container the root and moves the old root — its element, children, slots, styles and forwards — onto a new layer inside it.",
+			scope: "item",
+			creates: true,
+			title: (entity) => `Wrap ${entity} elements`,
+			handler: (input, config) => {
+				const payload = input.data;
+				const path = String(input.path);
+				const keys = payload.elements;
+				const anatomy = resolveMoveBody(config, path)?.anatomy ?? {};
+				for (const k of keys) if (!anatomy[k]) reject("NOT_FOUND", `"${path}" has no element "${k}" to wrap.`);
+				if (keys.includes("root")) {
+					if (keys.length > 1) rejectData("The root wraps on its own: it has no siblings to wrap with it.", ["elements"]);
+					return wrapRoot({
+						config,
+						path,
+						inner: input.key ? String(input.key) : freeLayerKey(config, path, "content"),
+						element: payload.element,
+						props: payload.props
+					});
+				}
+				const parent = Object.entries(anatomy).find(([, node]) => keys.every((k) => node.children?.includes(k)));
+				if (!parent) rejectData("Only layers that share a parent wrap together — wrap each parent's layers on their own.", ["elements"]);
+				const [parentKey, parentNode] = parent;
+				const order = (parentNode.children ?? []).filter((c) => keys.includes(c));
+				const index = (parentNode.children ?? []).indexOf(order[0]);
+				const wrapper = input.key ? String(input.key) : freeLayerKey(config, path, "wrap");
+				return config.run([{
+					kind: "component",
+					operation: "element-insert",
+					path,
+					key: wrapper,
+					data: {
+						element: payload.element,
+						parent: parentKey,
+						index,
+						...payload.props ? { props: payload.props } : {}
+					}
+				}, ...order.map((k) => ({
+					kind: "component",
+					operation: "element-move",
+					path,
+					key: k,
+					data: { parent: wrapper }
+				}))]);
+			}
+		},
 		validate: {
 			input: z.object({
 				path: pathInput("component"),

package/dist/entities/system/LinkedSystem.js

@@ -753,8 +753,9 @@ displayName: ({ member, path }) => typeof member.name === "string" && member.nam
 	bulkOverlayWrite: ({ accessor, path, overlay }) => ({ [`options.${accessor}.${path}`]: overlay })
 });
 /** An `override` or `extend` body with its `styles` as a list, in the stored form: the record keyed by
-*  each rule's condition, as `Component.item` stores one. Only a component's `styles` is a rule list —
-*  every other kind's is a record — so a list here is one whatever accessor it sits under. */
+*  each rule's condition, as `Component.item` stores one. Only a component has `styles`, so a list
+*  there is a rule list whatever accessor it sits under. A token's `overrides` list is stored as
+*  written and keyed where the overlay is read. */
 function storedPinBody(body) {
 	if (!isPlainObject(body) || !Array.isArray(body.styles)) return body;
 	return {

package/dist/entities/system/Settings.js

@@ -1,9 +1,9 @@
 import { splitRef } from "../../framework/utils/refs.js";
 import { defineEntity } from "../../framework/defineEntity.js";
 import { defineSubEntity } from "../../framework/defineSubEntity.js";
+import { createSliceMemo } from "../../framework/memo.js";
 import { buildFields } from "../../configs/build-options.js";
 import { parseRootFontSize } from "../../css/root-font-size.js";
-import { createSliceMemo } from "../../framework/memo.js";
 import { resolveInputDir } from "../../framework/registry-dir.js";
 import { safelistSchema } from "./safelist.js";
 import { z } from "zod";

package/dist/entities/system/StyleProperty.js

@@ -1,8 +1,8 @@
 import { declarationText, isRef, kindOf, pathOf, ref, refOfKey, refSchema, replaceRefMarkers, sourceOf, splitRef } from "../../framework/utils/refs.js";
 import { defineEntity } from "../../framework/defineEntity.js";
+import { createSliceMemo } from "../../framework/memo.js";
 import { cssValueIssue, isCssProperty } from "../../css/values.js";
 import { camelCase } from "./style-bag.js";
-import { createSliceMemo } from "../../framework/memo.js";
 import { isIdentifier } from "../../framework/utils/identifier.js";
 import { cssVar, declaresCssVariable } from "../../framework/projections.js";
 import { z } from "zod";

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

@@ -44,10 +44,19 @@ declare function defineOverride<TValue extends z.ZodTypeAny>(value: TValue): Sub
 declare const tokenFields: z.ZodObject<{
   value: z.ZodType<string | number | Ref | ComposedValue, unknown, z.core.$ZodTypeInternals<string | number | Ref | ComposedValue, unknown>>;
   type: z.ZodOptional<z.ZodString>;
-  overrides: z.ZodOptional<SubEntityClass<z.ZodObject<{
+  overrides: z.ZodOptional<z.ZodUnion<readonly [z.ZodPipe<z.ZodArray<z.ZodObject<{
     on: z.ZodType<OverrideCondition, unknown, z.core.$ZodTypeInternals<OverrideCondition, unknown>>;
     value: z.ZodType<string | number | Ref | ComposedValue, unknown, z.core.$ZodTypeInternals<string | number | Ref | ComposedValue, unknown>>;
-  }, z.core.$strip>>>;
+  }, z.core.$strip>>, z.ZodTransform<Record<string, {
+    on: OverrideCondition;
+    value: string | number | Ref | ComposedValue;
+  }>, {
+    on: OverrideCondition;
+    value: string | number | Ref | ComposedValue;
+  }[]>>, SubEntityClass<z.ZodObject<{
+    on: z.ZodType<OverrideCondition, unknown, z.core.$ZodTypeInternals<OverrideCondition, unknown>>;
+    value: z.ZodType<string | number | Ref | ComposedValue, unknown, z.core.$ZodTypeInternals<string | number | Ref | ComposedValue, unknown>>;
+  }, z.core.$strip>>]>>;
   utility: z.ZodOptional<z.ZodBoolean>;
   property: z.ZodOptional<z.ZodObject<{
     syntax: z.ZodOptional<z.ZodString>;
@@ -61,10 +70,19 @@ type TokenBody = z.infer<typeof tokenFields>;
 declare const TokenEntity: EntityClass<z.ZodObject<{
   value: z.ZodType<string | number | Ref | ComposedValue, unknown, z.core.$ZodTypeInternals<string | number | Ref | ComposedValue, unknown>>;
   type: z.ZodOptional<z.ZodString>;
-  overrides: z.ZodOptional<SubEntityClass<z.ZodObject<{
+  overrides: z.ZodOptional<z.ZodUnion<readonly [z.ZodPipe<z.ZodArray<z.ZodObject<{
+    on: z.ZodType<OverrideCondition, unknown, z.core.$ZodTypeInternals<OverrideCondition, unknown>>;
+    value: z.ZodType<string | number | Ref | ComposedValue, unknown, z.core.$ZodTypeInternals<string | number | Ref | ComposedValue, unknown>>;
+  }, z.core.$strip>>, z.ZodTransform<Record<string, {
+    on: OverrideCondition;
+    value: string | number | Ref | ComposedValue;
+  }>, {
+    on: OverrideCondition;
+    value: string | number | Ref | ComposedValue;
+  }[]>>, SubEntityClass<z.ZodObject<{
     on: z.ZodType<OverrideCondition, unknown, z.core.$ZodTypeInternals<OverrideCondition, unknown>>;
     value: z.ZodType<string | number | Ref | ComposedValue, unknown, z.core.$ZodTypeInternals<string | number | Ref | ComposedValue, unknown>>;
-  }, z.core.$strip>>>;
+  }, z.core.$strip>>]>>;
   utility: z.ZodOptional<z.ZodBoolean>;
   property: z.ZodOptional<z.ZodObject<{
     syntax: z.ZodOptional<z.ZodString>;

package/dist/entities/system/Token.js

@@ -1,7 +1,7 @@
 import { isRef, kindOf, pathOf, ref, refKey, sourceOf } from "../../framework/utils/refs.js";
 import { composedValueSchemas } from "./composed-values.js";
 import { defineEntity } from "../../framework/defineEntity.js";
-import { defineSubEntity } from "../../framework/defineSubEntity.js";
+import { defineSubEntity, orList } from "../../framework/defineSubEntity.js";
 import { Font } from "./Font.js";
 import { Modifier } from "./Modifier.js";
 import { spellTokenRead } from "./token-values.js";
@@ -112,7 +112,8 @@ function defineOverride(value) {
 			on: config ? declaredCondition(config) : overrideConditionSchema,
 			value
 		}),
-		key: (override) => overrideKey(override.on)
+		key: (override) => overrideKey(override.on),
+		listed: true
 	});
 }
 const Override = defineOverride(tokenValue);
@@ -128,7 +129,7 @@ const TokenEntity = defineEntity({
 	fields: z.object({
 		value: tokenValue.describe("The base value: a literal, a ref to another token, or a composed value such as a gradient."),
 		type: z.string().optional().describe("The CSS value type, when the value alone does not say it."),
-		overrides: Override.optional().describe("Per-mode values, keyed by the condition they apply under."),
+		overrides: orList(Override).optional().describe("Per-mode values, a list of `{ on, value }`. Stored keyed by the condition each applies under."),
 		utility: z.boolean().optional().describe("`false` keeps the token out of its group's values, so a style prop that takes the group writes no class for it — `spacing/scale` powers `--spacing` without becoming a `p-scale`. A ref naming the token still resolves."),
 		property: z.strictObject({
 			syntax: z.string().optional().describe("The `@property` syntax, as `<length>`. Defaults to `*`."),