@yahoo/uds-create-config 4.6.0 → 4.7.0

package/dist/entities/system/component-module.js

@@ -38,7 +38,7 @@ const componentsByFileCache = /* @__PURE__ */ new WeakMap();
 /** Documentation and examples never enter emitted component modules. */
 function buildEntityBody(kind, body) {
 	if (kind !== "component") return body;
-	const { previewProps: _preview, description: _description, ...buildBody } = body;
+	const { preview: _preview, description: _description, ...buildBody } = body;
 	return buildBody;
 }
 /**

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

@@ -1,5 +1,5 @@
 import { Ref as Ref$1 } from "../../framework/utils/refs.js";
-import { RegisteredModifiers, RegisteredStyleProps } from "../../framework/registered.js";
+import { RegisteredModifiers, RegisteredPaths, RegisteredStyleProps } from "../../framework/registered.js";
 import { Authored } from "../../framework/authoring.js";
 import { StyleValue } from "./style-bag.js";
 import { VariantValues } from "./Component.js";
@@ -73,8 +73,17 @@ type LayerPath<L extends LayerMap = LayerMap> = `${keyof L & string}/${string}`;
  * from anything else: a widened union left a slot prop inferring as `unknown` where the same prop
  * written by hand stayed a `ReactNode`.
  */
+/**
+ * When a prop applies — the record a style rule's `when` holds: each key a sibling prop, each value
+ * one of that prop's values or a list of them. A prop with no condition always applies. Stored with
+ * the values as refs (`value:type/color`), which is what lets a value rename cascade into it.
+ */
+type PropCondition = Readonly<Record<string, ConditionValue | ConditionValue[]>>;
+/** A value as authored, or the `value:` ref it is stored as. */
+type ConditionValue = string | number | boolean | Ref$1;
 interface SlotDecl {
   type: 'slot';
+  when?: PropCondition;
   /**
    * What may FILL this hole, as refs. Two shapes, both in this repo:
    *
@@ -131,6 +140,7 @@ interface ForwardDecl<Path extends string = string> {
   accepts?: Ref$1 | Ref$1[];
   text?: boolean;
   required?: boolean;
+  when?: PropCondition;
 }
 /**
  * One prop's declaration, in both the form it is AUTHORED in and the form it is STORED in.
@@ -154,20 +164,25 @@ type PropDecl<Path extends string = string> = SlotDecl | ForwardDecl<Path> | {
   type: 'variant';
   value: readonly string[] | VariantValues | Ref$1;
   required?: boolean;
+  when?: PropCondition;
 } | {
   type: 'styleProperty';
   value: Ref$1;
   required?: boolean;
+  when?: PropCondition;
 } | {
   type: 'composite';
   value: Ref$1;
   required?: boolean;
+  when?: PropCondition;
 } | {
   type: 'motion';
   required?: boolean;
+  when?: PropCondition;
 } | {
   type: 'string' | 'number' | 'boolean';
   required?: boolean;
+  when?: PropCondition;
 };
 /**
  * One prop as AUTHORED — a declaration, or one of the two bare forms that already say what they are:
@@ -228,6 +243,13 @@ type ValueOf<D> = D extends readonly (infer Member)[] ? Member : D extends {
     __ref: `style-property:${infer Target}`;
   };
 } ? StylePropValue<Target> : ValueOfDeclaration<D>;
+/**
+ * The members a ref-delegated domain offers, read off the registered paths: a variant whose domain
+ * is `icon:phosphor` takes every registered `phosphor/<Name>` as `<Name>`, so a misspelled glyph is
+ * a compile error once the system is built. A facet ref (`icon:phosphor#variants`), a kind the build
+ * did not register, or an unbuilt consumer stays `string`.
+ */
+type RegisteredMembers<Kind extends string, Path extends string> = Path extends `${string}#${string}` ? string : Kind extends keyof RegisteredPaths ? [Extract<RegisteredPaths[Kind], `${Path}/${string}`>] extends [never] ? string : Extract<RegisteredPaths[Kind], `${Path}/${string}`> extends `${Path}/${infer Name}` ? Name : string : string;
 /**
  * A style prop's values, read off the registry by the path the declaration points at. By the target
  * and not the prop's own name, since a component may expose a property under a name of its own —
@@ -240,7 +262,9 @@ type StylePropValue<Target extends string> = Target extends keyof RegisteredStyl
 type ValueOfDeclaration<D> = D extends {
   type: 'variant';
   value: infer V;
-} ? V extends readonly (infer Member)[] ? Member : V extends VariantValues ? keyof V & string : string : D extends {
+} ? V extends readonly (infer Member)[] ? Member : V extends VariantValues ? keyof V & string : V extends {
+  __ref: `${infer Kind}:${infer Path}`;
+} ? RegisteredMembers<Kind, Path> : string : D extends {
   type: 'string';
 } ? string : D extends {
   type: 'number';
@@ -267,7 +291,21 @@ type ValueOfDeclaration<D> = D extends {
 type Declared<T> = { [K in keyof T as string extends K ? never : number extends K ? never : K]: T[K] };
 /** What a prop map really exposes: each declaration's value type, with the `null` tombstones — the
  *  props it DROPS from what it inherits — gone from the surface entirely. */
-type DeclaredProps<P> = { [K in keyof P as P[K] extends null ? never : K]: ValueOf<P[K]> };
+type DeclaredProps<P, L extends LayerMap = LayerMap> = { [K in keyof P as P[K] extends null ? never : K]: RoutedValueOf<L, P[K]> };
+/**
+ * A forward's consumer type is the far prop's: a route onto a layer component's `name` takes what
+ * that component's `name` takes, and a route onto `<input disabled>` takes a boolean. The layers
+ * are in scope here, which is what {@link ValueOf} lacks. A text forward is a string whatever it
+ * lands on. A route onto `children`, or onto a layer the map doesn't hold (an open `LayerMap`, as in
+ * a defaults bag), keeps `ValueOf`'s answer.
+ */
+type RoutedValueOf<L extends LayerMap, D> = D extends {
+  type: 'forward';
+  text: true;
+} ? string : D extends {
+  type: 'forward';
+  target: `${infer Layer}/${infer Prop}`;
+} ? Prop extends 'children' ? ReactNode : Layer extends keyof L ? Prop extends keyof ElementPropsOf<L[Layer]> ? ElementPropsOf<L[Layer]>[Prop] : unknown : unknown : ValueOf<D>;
 /**
  * The props the rendered ELEMENT contributes, `ref` included.
  *
@@ -348,7 +386,7 @@ type RequiredKey<P, D> = { [K in keyof P]: P[K] extends {
  * is checked against its interface by relating two generic signatures, and a name type that reads
  * `P` is not identical on the two sides of that comparison — a name type reading only `E` is.
  */
-type ConsumerDeclaredProps<P, D, E> = Without<Partial<DeclaredProps<P>>, Redefined<E>> & { [K in Exclude<RequiredKey<P, D>, Redefined<E>>]-?: K extends keyof DeclaredProps<P> ? DeclaredProps<P>[K] : never };
+type ConsumerDeclaredProps<P, D, E, L extends LayerMap = LayerMap> = Without<Partial<DeclaredProps<P, L>>, Redefined<E>> & { [K in Exclude<RequiredKey<P, D>, Redefined<E>>]-?: K extends keyof DeclaredProps<P, L> ? DeclaredProps<P, L>[K] : never };
 /**
  * The keys a render extra redefines: the ones it names. An open extra (`extends Record<string,
  * unknown>`) names nothing through its index signature, but a key it declares beside that signature
@@ -395,7 +433,7 @@ type OpenTail<L extends LayerMap> = Registered extends true ? StyleProps & Modif
  *
  * Ends in {@link OpenTail}: the system's own surface, open until the system's build has named it.
  */
-type ComponentPropsOf<L extends LayerMap, P extends PropMap, D = Record<never, never>, E = Record<never, never>, F extends string = never, As = never> = ConsumerDeclaredProps<P, D, E> & Partial<E> & Redeclared<RootSurface<L, D, As>, P, E> & Redeclared<ForwardedPropsOf<L, F>, P, E> & AsPropsOf<As, P, E> & Redeclared<OpenTail<L>, P, E>;
+type ComponentPropsOf<L extends LayerMap, P extends PropMap, D = Record<never, never>, E = Record<never, never>, F extends string = never, As = never> = ConsumerDeclaredProps<P, D, E, L> & Partial<E> & Redeclared<RootSurface<L, D, As>, P, E> & Redeclared<ForwardedPropsOf<L, F>, P, E> & AsPropsOf<As, P, E> & Redeclared<OpenTail<L>, P, E>;
 /**
  * `T` less the keys the component declares and the keys its render extra names — each taken out on
  * its own, because {@link Without} leaves `T` whole when the key set is open, and an open render
@@ -502,7 +540,7 @@ type RenderArgs<L extends LayerMap, P extends PropMap> = {
    * `<input ref={ref}>` in another — and which element is the render's decision.
    */
   readonly ref?: Ref<any>;
-} & DeclaredProps<P> & Record<string, unknown>;
+} & DeclaredProps<P, L> & Record<string, unknown>;
 interface ComponentBuilder<L extends LayerMap, P extends PropMap,
 /** Props the RENDER takes that the config doesn't describe — React handlers, mostly (`onPress`).
  *  They're part of the component's surface but not of its data, which is why they're declared at
@@ -652,4 +690,4 @@ interface DefineComponent {
 declare function definePropsFirst<const P extends PropMap<LayerPath>>(props: P & NoInfer<{ [K in keyof P]: Exact<P[K], AuthoredProp<LayerPath>> }>): ComponentBuilder<LayerMap, P>;
 declare const defineComponent: DefineComponent;
 //#endregion
-export { AsInput, AuthoredComponent, AuthoredProp, ComponentBuilder, ComponentPropsOf, LayerElement, LayerMap, PhantomCallProps, PhantomReadProps, PropDecl, PropMap, RenderArgs, StyleRuleInput, defineComponent };
+export { AsInput, AuthoredComponent, AuthoredProp, ComponentBuilder, ComponentPropsOf, LayerElement, LayerMap, PhantomCallProps, PhantomReadProps, PropCondition, PropDecl, PropMap, RegisteredMembers, RenderArgs, StyleRuleInput, defineComponent };

package/dist/entities/system/defineComponent.js

@@ -1,4 +1,5 @@
-import { isRef, kindOf, memberRef, pathOf } from "../../framework/utils/refs.js";
+import { canonicalCondition, isRef, kindOf, memberRef, pathOf } from "../../framework/utils/refs.js";
+import "../../framework/preview-store.js";
 import { Component, canonicalWhen, layerRef } from "./Component.js";
 //#region src/entities/system/defineComponent.ts
 function build(body) {
@@ -20,10 +21,8 @@ function build(body) {
 		render: () => handle,
 		renderCanvas: () => handle,
 		preview: (spec) => {
-			const patch = {};
-			if (spec?.defaultProps !== void 0) patch.previewProps = spec.defaultProps;
-			if (spec?.when?.length) patch.previewWhen = spec.when;
-			return Object.keys(patch).length === 0 ? handle : next(patch);
+			if (spec?.defaultProps === void 0 && !spec?.when?.length) return handle;
+			return next({ preview: spec });
 		},
 		toStored: () => toStored(body),
 		assignPath(path) {
@@ -45,12 +44,15 @@ function build(body) {
 * only one of them runs for any given config: the build reads `.preview()` from source with ts-morph,
 * this runs when a config is registered, and a reader can't tell which made the config it holds.
 *
-* What this path CANNOT do is name an element the source could. A tag is its own name and a component
-* handle carries its adopted path, but a foreign function (a Phosphor glyph, say) is just a function
-* at runtime — its `displayName` is a label, not an identity, and two libraries may both export
-* `StarIcon`. Such a prop is DROPPED: an absent default renders nothing, while a guessed ref renders
-* the wrong glyph and reads as authored. The build resolves those from the import specifier, which is
-* why ~a third of the element-valued preview props in a real system only survive a build.
+* A component handed as a VALUE (`icon: PlusIcon`) stores as the bare ref the registry keys it under,
+* so the receiving component gets the component back rather than a node.
+*
+* What this path CANNOT do is name a component the source could. A tag is its own name and a
+* component handle carries its adopted path, but a foreign function (a Phosphor glyph, say) is just
+* a function at runtime — its `displayName` is a label, not an identity, and two libraries may both
+* export `StarIcon`. Such a prop is DROPPED: an absent default renders nothing, while a guessed ref
+* renders the wrong glyph and reads as authored. The build resolves those from the import specifier,
+* which is why ~a third of the element-valued preview props in a real system only survive a build.
 */
 function storableProps(props) {
 	if (props === void 0) return void 0;
@@ -61,9 +63,19 @@ function storableProps(props) {
 	}
 	return Object.keys(out).length === 0 ? void 0 : out;
 }
-/** A live React element, by the marker anything pretending to be one also carries. */
+/** A live React element, by the marker anything pretending to be one also carries. A `forwardRef` or
+*  `memo` component carries the marker too and is told apart by having no `props`: it is a type. */
 function isReactElement(value) {
-	return typeof value === "object" && value !== null && "$$typeof" in value;
+	return typeof value === "object" && value !== null && "$$typeof" in value && "props" in value;
+}
+/** A component TYPE handed as a value: a function, or the object `forwardRef` / `memo` return. */
+function isComponentType(value) {
+	if (typeof value === "function") return true;
+	return typeof value === "object" && value !== null && "$$typeof" in value && !("props" in value);
+}
+/** A component handed as a value, as the ref that names it — `undefined` for one this path can't name. */
+function storableComponentRef(value) {
+	return isComponentElement(value) && value.path ? Component.ref(value.path) : void 0;
 }
 const FRAGMENT = Symbol.for("react.fragment");
 /**
@@ -74,12 +86,20 @@ function storableElementName(type) {
 	if (typeof type === "string") return type;
 	if (isComponentElement(type) && type.path) return Component.ref(type.path);
 }
-/** The scalar half of an element's props — what `PreviewElement.props` may hold. */
+/** The scalar half of an element's props, plus a component handed as one — what
+*  `PreviewElement.props` may hold. */
 function storableAttributes(props) {
 	const out = {};
 	for (const [key, value] of Object.entries(props)) {
 		if (key === "children") continue;
-		if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") out[key] = value;
+		if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+			out[key] = value;
+			continue;
+		}
+		if (isComponentType(value)) {
+			const ref = storableComponentRef(value);
+			if (ref) out[key] = ref;
+		}
 	}
 	return out;
 }
@@ -118,13 +138,14 @@ function storableElement(value) {
 /**
 * One preview-prop value as the config stores it, or `undefined` to drop the prop.
 *
-* Mirrors the arms the build reads from source: a literal, an element, a fragment (several elements
-* under one prop), an array, and a nested record.
+* Mirrors the arms the build reads from source: a literal, a component, an element, a fragment
+* (several elements under one prop), an array, and a nested record.
 */
 function storableValue(value) {
 	if (value === null) return null;
 	const type = typeof value;
 	if (type === "string" || type === "number" || type === "boolean") return value;
+	if (isComponentType(value)) return storableComponentRef(value);
 	if (type !== "object") return void 0;
 	if (isReactElement(value)) {
 		if (value.type === FRAGMENT) {
@@ -299,15 +320,21 @@ function storedForwards(forwards, layers) {
 /** The authored body as the entity's stored shape — which differs in exactly four places. */
 function toStored(body) {
 	const stored = { ...body };
-	if (body.previewProps !== void 0) {
-		const previewProps = storableProps(body.previewProps);
-		if (previewProps === void 0) delete stored.previewProps;
-		else stored.previewProps = previewProps;
+	if (body.preview !== void 0) {
+		const authored = body.preview;
+		const keyed = {};
+		const defaults = authored.defaultProps !== void 0 ? storableProps(authored.defaultProps) : void 0;
+		if (defaults !== void 0) keyed["*"] = {
+			when: null,
+			props: defaults
+		};
+		for (const { when, props } of authored.when ?? []) keyed[canonicalCondition(when)] = {
+			when,
+			props: storableProps(props) ?? {}
+		};
+		if (Object.keys(keyed).length === 0) delete stored.preview;
+		else stored.preview = keyed;
 	}
-	if (Array.isArray(body.previewWhen)) stored.previewWhen = body.previewWhen.map(({ when, props }) => ({
-		when,
-		props: storableProps(props) ?? {}
-	}));
 	if (body.props && typeof body.props === "object") {
 		const props = {};
 		for (const [name, decl] of Object.entries(body.props)) props[name] = storedProp(decl, body.layers);

package/dist/framework/Config.d.ts

@@ -8,12 +8,12 @@ import { RefGraph, TraverseOptions } from "./ref-graph.js";
 import { FieldsSchema } from "./utils/field-schema.js";
 import { SubEntityClass } from "./defineSubEntity.js";
 import { LocalOverlay, SourceAnswer, SourceOverlay, SourceResolver, SourceState } from "./sources.js";
+import { EntityKind } from "./registry.js";
 import { AuthoredEntry } from "./utils/group.js";
 import { EntityClass } from "./defineEntity.js";
 import { BreakPlan, LinkPlan, SourceRowState, UnlinkPlan } from "../entities/system/link-plan.js";
 import { InlineOptions } from "./inline-sources.js";
 import { Snapshot } from "./snapshot.js";
-import { EntityKind } from "./registry.js";
 
 //#region src/framework/Config.d.ts
 /**
@@ -72,7 +72,7 @@ interface RecordedSource {
  * The dense-counter `2` a short-lived scheme stamped before the chain existed reads as the mint
  * that replaced it (see `detectedWireVersion`).
  */
-declare const SERIALIZED_CONFIG_VERSION = 20260918161049;
+declare const SERIALIZED_CONFIG_VERSION = 20260920161309;
 interface SerializedConfig {
   /** See {@link SERIALIZED_CONFIG_VERSION}. Always written; a stored artifact may lack it. */
   readonly version: number;

package/dist/framework/Config.js

@@ -367,31 +367,82 @@ function dropOrphans(sub, def, target, namespace) {
 }
 /**
 * Follow a member's name where the item holds it as a value keyed by that member's owner — a
-* Component's `defaultProps` and `previewProps`, which are both `{ [prop]: value }`.
+* Component's `defaultProps`, and the `props` of every `preview` entry, which are all
+* `{ [prop]: value }`.
 *
 * The third rename axis, after refs and record keys, and the only one where the name appears as
 * neither. `to: undefined` is the delete case: a default naming a value that no longer exists isn't
 * a dangling pointer anyone sees, it's a component that quietly reports a default it hasn't got.
+* A field is a `/` path, and a `*` segment stands for every key at that level, as in
+* {@link rekeyAt}.
 */
 function renameNamedValues(sub, def, owner, from, to) {
 	if (!sub?.namedValuesIn?.length || owner === void 0) return def;
 	let out = def;
 	for (const field of sub.namedValuesIn) {
-		const record = out[field];
-		if (!isPlainObject(record) || record[owner] !== from) continue;
+		const next = renameValueAt(out, field.split("/"), owner, from, to);
+		if (isPlainObject(next)) out = next;
+	}
+	return out;
+}
+/** Rewrite the value under `owner` in the record `path` addresses, from `from` to `to` (or drop it). */
+function renameValueAt(node, path, owner, from, to) {
+	if (!isPlainObject(node)) return node;
+	const [head, ...rest] = path;
+	if (head === void 0) return node;
+	if (rest.length === 0) {
+		const record = node[head];
+		if (!isPlainObject(record) || record[owner] !== from) return node;
 		const next = { ...record };
 		if (to === void 0) delete next[owner];
 		else next[owner] = to;
-		out = {
+		return {
+			...node,
+			[head]: next
+		};
+	}
+	if (head === "*") {
+		let changed = false;
+		const next = {};
+		for (const [key, value] of Object.entries(node)) {
+			const updated = renameValueAt(value, rest, owner, from, to);
+			next[key] = updated;
+			if (updated !== value) changed = true;
+		}
+		return changed ? next : node;
+	}
+	const updated = renameValueAt(node[head], rest, owner, from, to);
+	return updated === node[head] ? node : {
+		...node,
+		[head]: updated
+	};
+}
+/**
+* Drop the members a name removal left declaring nothing. A `keyedByNameIn` path through another
+* collection (`preview/*\/props`) removes a key from each of that collection's members, and a member
+* that held only that key now says nothing; the collection's own `vacant` decides, the same test a
+* `sub-update` asks before bringing one into being.
+*/
+function dropVacated(entry, sub, def) {
+	if (!sub?.keyedByNameIn?.length) return def;
+	let out = def;
+	for (const path of sub.keyedByNameIn) {
+		const [field, wildcard] = path.split("/");
+		if (wildcard !== "*") continue;
+		const collectionSub = entry.subEntities[field];
+		const collection = out[field];
+		if (!collectionSub?.vacant || !isPlainObject(collection)) continue;
+		const kept = Object.fromEntries(Object.entries(collection).filter(([, member]) => collectionSub.vacant?.(member) !== true));
+		if (Object.keys(kept).length !== Object.keys(collection).length) out = {
 			...out,
-			[field]: next
+			[field]: kept
 		};
 	}
 	return out;
 }
 /**
 * Follow a member's name where the item holds it as a record key — a component's `defaultProps` and
-* `previewProps` are both `{ [prop]: value }`.
+* every `preview` entry's `props` are `{ [prop]: value }`.
 *
 * The other half of {@link renameNamedValues}, which reaches the same two fields from the value side.
 * `to: undefined` is the delete case, and it matters as much as the rename: a default left under the
@@ -1669,6 +1720,7 @@ var Config = class Config {
 			def = store(def, collection);
 			def = renameNamedValues(sub, def, patch.owner, patch.key, void 0);
 			def = renameKeyedByName(sub, def, patch.key, void 0);
+			def = dropVacated(entry, sub, def);
 			def = dropOrphans(sub, def, `${leafOf(patch.field).replace(/s$/, "")}:${refPathOf(patch, patch.key)}`, sub?.namespaces ? {
 				kind: sub.namespaces,
 				path: patch.key
@@ -4739,7 +4791,7 @@ var Config = class Config {
 	*  links from the provided sources. A declared `linkedKind` with no provided source throws. */
 	hydrateFrom(stored, options) {
 		const claimed = schemaVersionOf(stored);
-		if (claimed > 20260918161049) throw new SchemaVersionTooNew(claimed);
+		if (claimed > 20260920161309) throw new SchemaVersionTooNew(claimed);
 		const wire = upgradeSerializedConfig(stored);
 		if (!Array.isArray(wire.ownedKinds) || typeof wire.items !== "object" || wire.items === null) throw new ConfigFormatError(`Config "${stored.name ?? "system-config"}" cannot be hydrated: this is not a serialized config-v2 config (no "ownedKinds"/"items"). A pre-cutover build artifact converts through the registered cutover migration — import the config type's module (e.g. \`configs/system\`) before hydrating, or port the repo once with \`uds migrate\`.`);
 		const leftover = wire.options;

package/dist/framework/class-names.d.ts

@@ -150,8 +150,10 @@ declare function componentPropClasses(config: Config, path: string, state?: Reco
  * travels to it as one, whether or not the element declares it: a composite (`variant` on a
  * `Text`-backed layer, which the receiver resolves to its own class), the receiver's own variant or
  * scalar prop (`size: 'sm'` on an Icon layer), or an attribute of a plain element (`as: 'div'`,
- * `type: 'button'`, `aria-hidden`). A receiver prop with a channel of its own — a style property
- * under another name, a slot, a forward, motion — stays out, since that channel already carries it.
+ * `type: 'button'`, `aria-hidden`), or a value the rule hands a receiver's forward or slot
+ * (`children: 'AI'` on a badge layer, `icon: 'XIcon'` on a button layer), which the emitted module
+ * routes the same way. A style property under another name and motion stay out, since the
+ * stylesheet and the motion classes already carry them.
  *
  * Forwarding rather than resolving is what makes a layer's styling live-editable at all: a class only
  * exists once a build has emitted the stylesheet, so an edit that makes a NEW style rule paints

package/dist/framework/class-names.js

@@ -1,7 +1,8 @@
-import { isRef, kindOf, pathOf, refLeaf } from "./utils/refs.js";
-import { rootLayerOf } from "../entities/system/element.js";
+import { isRef, kindOf, memberOf, pathOf, refLeaf } from "./utils/refs.js";
+import { forwardsOf, rootLayerOf } from "../entities/system/element.js";
 import { classPrefixOf } from "../entities/system/Settings.js";
 import { createSliceMemo } from "./memo.js";
+import { storedPreview } from "./preview-store.js";
 import { authoredValue, className, negatedCssValue, renderStyleValue, resolveComponentProps, stylePropLeafForToken, stylePropValueLeaves, stylePropertyPathFor } from "./projections.js";
 import { ruleApplies } from "./layer-styles.js";
 //#region src/framework/class-names.ts
@@ -295,38 +296,74 @@ function componentMotionClasses(config, path) {
 function componentPropClasses(config, path, state = {}) {
 	const declared = compositePropsOf(config, path);
 	if (!declared) return {};
-	const { root, groups, defaultProps } = declared;
+	const { groups, defaultProps } = declared;
 	if (groups.length === 0) return {};
 	const resolved = {
 		...defaultProps,
 		...state
 	};
-	const classes = [];
-	for (const [prop, group] of groups) {
+	const out = {};
+	for (const [prop, group, layer] of groups) {
 		const value = resolved[prop];
 		const target = memberNamed(group, value);
 		if (target === void 0) continue;
 		if (!config.resolve("composite", target)) continue;
+		const classes = out[layer] ?? [];
 		classes.push(className(config, "composite", target));
+		out[layer] = classes;
 	}
-	return classes.length > 0 ? { [root]: classes } : {};
+	return out;
 }
 /** The part of {@link componentPropClasses} that depends on the component alone, once per slice:
 *  an expansion asks it for every instance it paints. `undefined` for a path no component answers. */
-function compositePropsOf(config, path) {
+function compositePropsOf(config, path, seen = /* @__PURE__ */ new Set()) {
 	const cache = compositePropsCache(config);
 	if (cache.has(path)) return cache.get(path);
 	const component = config.resolve("component", path);
 	let declared;
 	if (component) {
-		const { layers = {}, props = {}, defaultProps = {} } = component.toJSON();
+		const body = component.toJSON();
+		const { layers = {}, props = {} } = body;
 		const [root] = rootLayerOf(layers);
 		const groups = [];
+		let defaultProps = {};
 		for (const [prop, decl] of Object.entries(props)) {
 			if (decl?.type !== "composite") continue;
 			const group = isRef(decl.value) ? decl.value.__ref : void 0;
-			if (group) groups.push([prop, group]);
+			if (group) groups.push([
+				prop,
+				group,
+				root
+			]);
 		}
+		const inner = new Set([...seen, path]);
+		for (const [layer, entry] of Object.entries(forwardsOf(body))) {
+			const element = layers[layer];
+			if (!isRef(element) || kindOf(element.__ref) !== "component") continue;
+			const from = pathOf(element.__ref);
+			if (inner.has(from)) continue;
+			const exposed = compositePropsOf(config, from, inner);
+			if (!exposed) continue;
+			const names = Array.isArray(entry) ? new Set(entry.flatMap((r) => isRef(r) ? [memberOf(r.__ref)?.split("/").pop()] : [])) : void 0;
+			for (const [prop, group, at] of exposed.groups) {
+				if (at !== exposed.root) continue;
+				if (prop in props) continue;
+				if (entry !== "*" && !names?.has(prop)) continue;
+				groups.push([
+					prop,
+					group,
+					layer
+				]);
+			}
+			defaultProps = {
+				...exposed.defaultProps,
+				...defaultProps
+			};
+		}
+		defaultProps = {
+			...defaultProps,
+			...body.defaultProps
+		};
 		declared = {
 			root,
 			groups,
@@ -349,8 +386,10 @@ const compositePropsCache = createSliceMemo({
 * travels to it as one, whether or not the element declares it: a composite (`variant` on a
 * `Text`-backed layer, which the receiver resolves to its own class), the receiver's own variant or
 * scalar prop (`size: 'sm'` on an Icon layer), or an attribute of a plain element (`as: 'div'`,
-* `type: 'button'`, `aria-hidden`). A receiver prop with a channel of its own — a style property
-* under another name, a slot, a forward, motion — stays out, since that channel already carries it.
+* `type: 'button'`, `aria-hidden`), or a value the rule hands a receiver's forward or slot
+* (`children: 'AI'` on a badge layer, `icon: 'XIcon'` on a button layer), which the emitted module
+* routes the same way. A style property under another name and motion stay out, since the
+* stylesheet and the motion classes already carry them.
 *
 * Forwarding rather than resolving is what makes a layer's styling live-editable at all: a class only
 * exists once a build has emitted the stylesheet, so an edit that makes a NEW style rule paints
@@ -377,7 +416,7 @@ function layerRoutedProps(config, path, state = {}) {
 			}) ?? prop;
 			if (config.resolve("style-property", styleKey)) continue;
 			const decl = declared[prop];
-			if (decl?.type === "styleProperty" || decl?.type === "slot" || decl?.type === "forward" || decl?.type === "motion") continue;
+			if (decl?.type === "styleProperty" || decl?.type === "motion") continue;
 			out[layer] ??= {};
 			out[layer][prop] = authoredValue(config, prop, value);
 		}
@@ -598,7 +637,7 @@ function modifierUtilitiesUsed(config) {
 /**
 * Every style bag a COMPONENT states it wants, each with the definitions its keys resolve against.
 *
-* Not uniform, which is the whole reason it travels with the bag. `defaultProps` and `previewProps`
+* Not uniform, which is the whole reason it travels with the bag. `defaultProps` and a preview entry's `props`
 * are the component's OWN props, and nothing else has a claim. A style rule's per-layer bag and an
 * anatomy node's props are set on a LAYER'S ELEMENT, so that element answers too — after the
 * component itself, whose own declaration of a name is what that name means throughout its
@@ -606,14 +645,14 @@ function modifierUtilitiesUsed(config) {
 */
 function componentBags(entity) {
 	const { path } = entity;
-	const { defaultProps, previewProps, styles, anatomy, layers } = entity.toJSON();
+	const { defaultProps, styles, anatomy, layers } = entity.toJSON();
 	const bags = [{
 		bag: defaultProps,
 		through: [path]
-	}, {
-		bag: previewProps,
+	}, ...Object.values(storedPreview(entity.toJSON())).map((entry) => ({
+		bag: entry?.props,
 		through: [path]
-	}];
+	}))];
 	for (const rule of Object.values(styles ?? {})) for (const [layer, bag] of Object.entries(rule?.layers ?? {})) bags.push({
 		bag,
 		through: [path, componentElementOf(layers?.[layer])]

package/dist/framework/defineDerivedEntity.d.ts

@@ -2,8 +2,8 @@ import { Entity } from "./Entity.js";
 import { Ref } from "./utils/refs.js";
 import { TraverseOptions } from "./ref-graph.js";
 import { FieldsSchema } from "./utils/field-schema.js";
-import { Config } from "./Config.js";
 import { ComputedInput, EntityKind } from "./registry.js";
+import { Config } from "./Config.js";
 import { z } from "zod";
 
 //#region src/framework/defineDerivedEntity.d.ts

package/dist/framework/defineEntity.d.ts

@@ -4,11 +4,11 @@ import { TraverseOptions } from "./ref-graph.js";
 import { CreateInput, FieldsSchema } from "./utils/field-schema.js";
 import { FieldsCtx, UserSchemas } from "./schemas.js";
 import { SubEntityClass } from "./defineSubEntity.js";
-import { PathOf } from "./registered.js";
 import { BulkOverlayWrite, BulkQuery, SourceOverlay, SourceResolutionSchemas } from "./sources.js";
+import { ComputedFields, EntityKind, Linkable } from "./registry.js";
+import { PathOf } from "./registered.js";
 import { GroupBody } from "./utils/group.js";
 import { Config, ListOptions, TreeNode } from "./Config.js";
-import { ComputedFields, EntityKind, Linkable } from "./registry.js";
 import { z } from "zod";
 
 //#region src/framework/defineEntity.d.ts

package/dist/framework/defineSubEntity.d.ts

@@ -71,7 +71,8 @@ type SubEntityClass<F extends z.ZodTypeAny = z.ZodTypeAny> = CollectionSchema<F>
   readonly subEntities?: Readonly<Record<string, SubEntityClass>>;
   /**
    * Fields of the OWNING ENTITY that hold this member's NAME as a VALUE, keyed by the member's
-   * owner — a component's `defaultProps` and `previewProps` are both `{ [prop]: value }`.
+   * owner — a component's `defaultProps` and each `preview` entry's `props` are `{ [prop]: value }`.
+   * A field is a `/` path; `*` stands for every key at that level.
    *
    * The mirror of {@link namesMembersOf}, which covers a name held as a record KEY. Neither is
    * reachable by a ref rewrite, and both leave the same kind of wreckage: a default naming a
@@ -81,7 +82,7 @@ type SubEntityClass<F extends z.ZodTypeAny = z.ZodTypeAny> = CollectionSchema<F>
   readonly namedValuesIn?: readonly string[];
   /**
    * Fields of the OWNING ENTITY that are KEYED by this member's name — a component's
-   * `defaultProps` and `previewProps` are both `{ [prop]: value }`, so the prop's name is the key
+   * `defaultProps` and each `preview` entry's `props` are `{ [prop]: value }`, so the prop's name is the key
    * rather than the value.
    *
    * The other half of {@link namedValuesIn}, which covers the same two fields from the value side

package/dist/framework/preview-store.d.ts

@@ -0,0 +1,19 @@
+//#region src/framework/preview-store.d.ts
+/**
+ * A component's stored `preview` collection, read off a body with nothing else in scope: the render
+ * spec builder and the class scanner read it without reaching the projections module.
+ */
+/** One `preview` entry as stored: the condition it holds under, `null` for the `*` entry every
+ *  cell reads, and the props the matching cells preview with. */
+interface StoredPreviewCondition {
+  readonly when: Record<string, unknown> | null;
+  readonly props: Record<string, unknown>;
+}
+/** The `*` entry the `preview` collection stores — see `preview({ defaultProps })`. */
+declare const UNCONDITIONAL_PREVIEW_KEY = "*";
+/** Every `preview` entry a body stores, keyed as stored. Empty for a body that stores none. */
+declare function storedPreview(body: unknown): Readonly<Record<string, StoredPreviewCondition>>;
+/** The props the `*` entry previews with, `undefined` when the body stores no such entry. */
+declare function unconditionalPreviewProps(body: unknown): Record<string, unknown> | undefined;
+//#endregion
+export { StoredPreviewCondition, UNCONDITIONAL_PREVIEW_KEY, storedPreview, unconditionalPreviewProps };