@yahoo/uds-create-config 4.6.0 → 4.7.0

package/dist/framework/preview-store.js

@@ -0,0 +1,18 @@
+//#region src/framework/preview-store.ts
+/** The `*` entry the `preview` collection stores — see `preview({ defaultProps })`. */
+const UNCONDITIONAL_PREVIEW_KEY = "*";
+/** Every `preview` entry a body stores, keyed as stored. Empty for a body that stores none. */
+function storedPreview(body) {
+	const preview = body?.preview;
+	return preview && typeof preview === "object" && !Array.isArray(preview) ? preview : {};
+}
+/** The props the `*` entry previews with, `undefined` when the body stores no such entry. */
+function unconditionalPreviewProps(body) {
+	return storedPreview(body)["*"]?.props;
+}
+/** Whether an entry holds under a condition rather than for every cell. */
+function isConditionalPreview(entry) {
+	return entry.when !== null && Object.keys(entry.when).length > 0;
+}
+//#endregion
+export { UNCONDITIONAL_PREVIEW_KEY, isConditionalPreview, storedPreview, unconditionalPreviewProps };

package/dist/framework/projections.d.ts

@@ -2,6 +2,7 @@ import { Ref } from "./utils/refs.js";
 import { ItemOf } from "./defineEntity.js";
 import { Config } from "./Config.js";
 import { StylePropLeaf, StyleProperty } from "../entities/system/StyleProperty.js";
+import { StoredPreviewCondition, UNCONDITIONAL_PREVIEW_KEY, storedPreview, unconditionalPreviewProps } from "./preview-store.js";
 
 //#region src/framework/projections.d.ts
 /**
@@ -410,10 +411,10 @@ declare function propValueDomain(config: Config, decl: PropDeclaration): {
  *  `component/validate` op's truth is config-defined and the pipeline only renders it. */
 declare function validateComponentProps(config: Config, componentPath: string, props: Record<string, unknown>): string[];
 /**
- * The props one preview tile starts from: the component's `defaultProps` with its `previewProps`
+ * The props one preview tile starts from: the component's `defaultProps` with its `*` preview entry
  * over the top.
  *
- * Preview wins, and that direction is the whole reason this exists once. `previewProps` is the state
+ * Preview wins, and that direction is the whole reason this exists once. The `*` entry is the state
  * a person chose to show a component in — Button's `variant`, an Icon prop's example glyph — so a
  * surface showing that tile has to agree with it, while `defaultProps` remains the baseline for every
  * prop the tile doesn't pin. Get the order backwards and the panel reports a value the canvas isn't
@@ -421,7 +422,7 @@ declare function validateComponentProps(config: Config, componentPath: string, p
  *
  * THE PRECEDENCE RULE, stated once: only a RENDER surface — a preview tile, the catalogue card, slot
  * text seeding — reads this merge. An EDIT surface reads and writes the single field it owns
- * (`defaultProps` OR `previewProps`, never the merge), and anything that SEEDS committed data — a
+ * (`defaultProps` OR the `*` entry, never the merge), and anything that SEEDS committed data — a
  * prop binding, a forward's re-seed, a stored instance prop, a default-value form — reads raw
  * `defaultProps`. A preview value that reaches any of those stops being staging and becomes a real
  * default the moment it is saved, which is exactly the leak UDS-3514 closed. Before adding a caller,
@@ -451,16 +452,33 @@ cell?: Record<string, unknown>): Record<string, unknown>;
  * without restating defaults that would shadow an edit.
  */
 declare function previewConditionalProps(config: Config, path: string, cell: Record<string, unknown>): Record<string, unknown>;
-/** One preview condition as stored — see `defineComponent`'s `PreviewCondition`. */
-interface StoredPreviewCondition {
-  readonly when: Record<string, unknown>;
-  readonly props: Record<string, unknown>;
+/** One conditional `preview` entry with the key it is stored under, which is how a write addresses it. */
+interface IndexedPreviewCondition {
+  readonly key: string;
+  readonly condition: StoredPreviewCondition;
 }
+/**
+ * The conditional `preview` entries that hold for a cell, in stored order: every prop a condition names
+ * holds the value it asks for in the defaults under the cell's own values. The same test
+ * `ruleApplies` makes for a style rule, kept here because `layer-styles` imports this module.
+ */
+declare function holdingPreviewConditions({
+  config,
+  path,
+  cell
+}: {
+  config: Config;
+  path: string;
+  cell: Readonly<Record<string, unknown>>;
+}): IndexedPreviewCondition[];
 /**
  * A component's conditional preview props, in authored order. Empty for a component that declares
  * none, or a path that names no component.
  */
 declare function previewConditions(config: Config, path: string): readonly StoredPreviewCondition[];
+/** The conditional entries under the keys they are stored at, the `*` entry left out. Empty for a
+ *  component that declares none. */
+declare function keyedPreviewConditions(config: Config, path: string): Readonly<Record<string, StoredPreviewCondition>>;
 /** A preview grid, derived. Rows sweep a prop's declared values; columns are the states the
  *  Component actually styles for. */
 interface PreviewMatrix {
@@ -497,5 +515,7 @@ declare function previewMatrix(config: Config, path: string): PreviewMatrix;
  * stored as the string `'true'` and never equals the `true` an author writes.
  */
 declare function propValueFromAxis(config: Config, path: string, prop: string, value: string): unknown;
+/** The `value` a string, number or boolean prop declares as its default, per prop. */
+declare function declaredPropDefaults(props: Record<string, unknown> | undefined): Record<string, unknown>;
 //#endregion
-export { PreviewMatrix, PropDeclaration, StoredPreviewCondition, StylePropEntry, StylePropertyItem, authoredBag, authoredValue, className, cssPropValue, cssVar, cssVarRef, declaredPropRouting, memberFromLeaf, memberLeaves, negatedCssValue, opacityPercentage, previewConditionalProps, previewConditions, previewDefaults, previewMatrix, propOwner, propValueDomain, propValueFromAxis, renderStyleValue, resolveComponentProps, resolveFieldValue, resolveTokenValue, resolveTokenValueUnder, routedBag, sourceVarPrefix, styleAliasesOf, styleDeclarations, stylePropEntries, stylePropLeafForToken, stylePropNegates, stylePropTokenGroup, stylePropTokenPath, stylePropTokenValues, stylePropValueFromLeaf, stylePropValueLeaves, stylePropValues, stylePropertiesWriting, stylePropertyAccepts, stylePropertyFor, stylePropertyPathFor, validateComponentProps };
+export { IndexedPreviewCondition, PreviewMatrix, PropDeclaration, StylePropEntry, StylePropertyItem, authoredBag, authoredValue, className, cssPropValue, cssVar, cssVarRef, declaredPropDefaults, declaredPropRouting, holdingPreviewConditions, keyedPreviewConditions, memberFromLeaf, memberLeaves, negatedCssValue, opacityPercentage, previewConditionalProps, previewConditions, previewDefaults, previewMatrix, propOwner, propValueDomain, propValueFromAxis, renderStyleValue, resolveComponentProps, resolveFieldValue, resolveTokenValue, resolveTokenValueUnder, routedBag, sourceVarPrefix, styleAliasesOf, styleDeclarations, stylePropEntries, stylePropLeafForToken, stylePropNegates, stylePropTokenGroup, stylePropTokenPath, stylePropTokenValues, stylePropValueFromLeaf, stylePropValueLeaves, stylePropValues, stylePropertiesWriting, stylePropertyAccepts, stylePropertyFor, stylePropertyPathFor, validateComponentProps };

package/dist/framework/projections.js

@@ -7,6 +7,7 @@ import { modifierCategory } from "../entities/system/Modifier.js";
 import { classPrefixOf, varPrefixOf } from "../entities/system/Settings.js";
 import { StyleProperty, leavesOfStylePropValue } from "../entities/system/StyleProperty.js";
 import { createSliceMemo } from "./memo.js";
+import { isConditionalPreview, storedPreview, unconditionalPreviewProps } from "./preview-store.js";
 //#region src/framework/projections.ts
 /**
 * Expanded value domains, cached per config instance.
@@ -903,10 +904,10 @@ function validateComponentProps(config, componentPath, props) {
 	return errors;
 }
 /**
-* The props one preview tile starts from: the component's `defaultProps` with its `previewProps`
+* The props one preview tile starts from: the component's `defaultProps` with its `*` preview entry
 * over the top.
 *
-* Preview wins, and that direction is the whole reason this exists once. `previewProps` is the state
+* Preview wins, and that direction is the whole reason this exists once. The `*` entry is the state
 * a person chose to show a component in — Button's `variant`, an Icon prop's example glyph — so a
 * surface showing that tile has to agree with it, while `defaultProps` remains the baseline for every
 * prop the tile doesn't pin. Get the order backwards and the panel reports a value the canvas isn't
@@ -914,7 +915,7 @@ function validateComponentProps(config, componentPath, props) {
 *
 * THE PRECEDENCE RULE, stated once: only a RENDER surface — a preview tile, the catalogue card, slot
 * text seeding — reads this merge. An EDIT surface reads and writes the single field it owns
-* (`defaultProps` OR `previewProps`, never the merge), and anything that SEEDS committed data — a
+* (`defaultProps` OR the `*` entry, never the merge), and anything that SEEDS committed data — a
 * prop binding, a forward's re-seed, a stored instance prop, a default-value form — reads raw
 * `defaultProps`. A preview value that reaches any of those stops being staging and becomes a real
 * default the moment it is saved, which is exactly the leak UDS-3514 closed. Before adding a caller,
@@ -935,8 +936,10 @@ function validateComponentProps(config, componentPath, props) {
 function previewDefaults(config, path, cell) {
 	const component = config.resolve("component", path);
 	if (!component) return {};
-	const { defaultProps, previewProps } = component.body;
+	const { props, defaultProps } = component.body;
+	const previewProps = unconditionalPreviewProps(component.body);
 	const base = {
+		...declaredPropDefaults(props),
 		...defaultProps,
 		...previewProps
 	};
@@ -953,28 +956,48 @@ function previewDefaults(config, path, cell) {
 * without restating defaults that would shadow an edit.
 */
 function previewConditionalProps(config, path, cell) {
+	const conditional = {};
+	for (const { condition } of holdingPreviewConditions({
+		config,
+		path,
+		cell
+	})) Object.assign(conditional, condition.props);
+	return conditional;
+}
+/**
+* The conditional `preview` entries that hold for a cell, in stored order: every prop a condition names
+* holds the value it asks for in the defaults under the cell's own values. The same test
+* `ruleApplies` makes for a style rule, kept here because `layer-styles` imports this module.
+*/
+function holdingPreviewConditions({ config, path, cell }) {
 	const component = config.resolve("component", path);
-	if (!component) return {};
-	const { defaultProps, previewProps } = component.body;
+	if (!component) return [];
+	const { defaultProps } = component.body;
 	const state = {
 		...defaultProps,
-		...previewProps,
+		...unconditionalPreviewProps(component.body),
 		...cell
 	};
-	const holds = (when) => Object.entries(when).every(([prop, value]) => String(state[prop]) === String(refLeaf(value)));
-	const conditional = {};
-	for (const { when, props } of previewConditions(config, path)) if (holds(when)) Object.assign(conditional, props);
-	return conditional;
+	return Object.entries(keyedPreviewConditions(config, path)).flatMap(([key, condition]) => {
+		return Object.entries(condition.when ?? {}).every(([prop, value]) => String(state[prop]) === String(refLeaf(value))) ? [{
+			key,
+			condition
+		}] : [];
+	});
 }
 /**
 * A component's conditional preview props, in authored order. Empty for a component that declares
 * none, or a path that names no component.
 */
 function previewConditions(config, path) {
+	return Object.values(keyedPreviewConditions(config, path));
+}
+/** The conditional entries under the keys they are stored at, the `*` entry left out. Empty for a
+*  component that declares none. */
+function keyedPreviewConditions(config, path) {
 	const component = config.resolve("component", path);
-	if (!component) return [];
-	const { previewWhen } = component.body;
-	return Array.isArray(previewWhen) ? previewWhen : [];
+	if (!component) return {};
+	return Object.fromEntries(Object.entries(storedPreview(component.body)).filter(([, entry]) => isConditionalPreview(entry)));
 }
 /**
 * The preview grid a component implies.
@@ -1014,7 +1037,7 @@ function previewMatrix(config, path) {
 			if (modifierCategory(config, key.slice(1)) === "state") modifiers.add(key);
 		}
 	}
-	for (const { when } of previewConditions(config, path)) for (const [prop, stored] of Object.entries(when)) nameAxisPoint(prop, stored);
+	for (const { when } of previewConditions(config, path)) for (const [prop, stored] of Object.entries(when ?? {})) nameAxisPoint(prop, stored);
 	for (const [name, decl] of Object.entries(declared)) {
 		if (decl?.type === "composite" && isRef(decl.value)) {
 			const values = declaredFirst([...memberLeaves(config, decl.value)], props[name] ?? []);
@@ -1052,5 +1075,16 @@ function propValueFromAxis(config, path, prop, value) {
 	}
 	return value;
 }
+/** The `value` a string, number or boolean prop declares as its default, per prop. */
+function declaredPropDefaults(props) {
+	const out = {};
+	for (const [name, decl] of Object.entries(props ?? {})) {
+		if (!decl || typeof decl !== "object") continue;
+		const { type, value } = decl;
+		if (type !== "string" && type !== "number" && type !== "boolean") continue;
+		if (value !== void 0) out[name] = value;
+	}
+	return out;
+}
 //#endregion
-export { authoredBag, authoredValue, className, cssPropValue, cssVar, cssVarRef, declaredPropRouting, memberFromLeaf, memberLeaves, negatedCssValue, opacityPercentage, previewConditionalProps, previewConditions, previewDefaults, previewMatrix, propOwner, propValueDomain, propValueFromAxis, renderStyleValue, resolveComponentProps, resolveFieldValue, resolveTokenValue, resolveTokenValueUnder, routedBag, sourceVarPrefix, styleAliasesOf, styleDeclarations, stylePropEntries, stylePropLeafForToken, stylePropNegates, stylePropTokenGroup, stylePropTokenPath, stylePropTokenValues, stylePropValueFromLeaf, stylePropValueLeaves, stylePropValues, stylePropertiesWriting, stylePropertyAccepts, stylePropertyFor, stylePropertyPathFor, validateComponentProps };
+export { authoredBag, authoredValue, className, cssPropValue, cssVar, cssVarRef, declaredPropDefaults, declaredPropRouting, holdingPreviewConditions, keyedPreviewConditions, memberFromLeaf, memberLeaves, negatedCssValue, opacityPercentage, previewConditionalProps, previewConditions, previewDefaults, previewMatrix, propOwner, propValueDomain, propValueFromAxis, renderStyleValue, resolveComponentProps, resolveFieldValue, resolveTokenValue, resolveTokenValueUnder, routedBag, sourceVarPrefix, styleAliasesOf, styleDeclarations, stylePropEntries, stylePropLeafForToken, stylePropNegates, stylePropTokenGroup, stylePropTokenPath, stylePropTokenValues, stylePropValueFromLeaf, stylePropValueLeaves, stylePropValues, stylePropertiesWriting, stylePropertyAccepts, stylePropertyFor, stylePropertyPathFor, validateComponentProps };

package/dist/framework/prop-surface.d.ts

@@ -3,9 +3,14 @@ import { Config } from "./Config.js";
 //#region src/framework/prop-surface.d.ts
 /** What a prop IS — the config's own prop types, and nothing invented. */
 type SurfacePropKind = 'variant' | 'styleProperty' | 'composite' | 'motion' | 'slot' | 'string' | 'number' | 'boolean';
+/** When a prop applies, as leaves: each key a sibling prop, each value the leaves it must hold one
+ *  of. What a control compares the values in force against — see {@link propApplies}. */
+type SurfacePropCondition = Readonly<Record<string, readonly unknown[]>>;
 interface SurfacePropBase {
   readonly name: string;
   readonly required: boolean;
+  /** Absent when the prop always applies. */
+  readonly when?: SurfacePropCondition;
 }
 interface SurfaceVariantProp extends SurfacePropBase {
   readonly kind: 'variant';
@@ -62,7 +67,16 @@ interface PropDecl extends Record<string, unknown> {
   into?: string;
   text?: boolean;
   accepts?: unknown;
+  when?: unknown;
 }
+/**
+ * Whether a prop applies under the values in force — every prop its condition names holds one of the
+ * leaves listed for it. A prop with no condition always applies; an unset prop satisfies nothing.
+ * Compared as strings, since a control hands back what it displays.
+ */
+declare function propApplies(prop: {
+  readonly when?: SurfacePropCondition;
+}, values: Readonly<Record<string, unknown>>): boolean;
 /**
  * The prop a slot routes INTO, resolved through the layer it targets: the layer's element is a
  * component, and `into` names one of that component's props. `undefined` when the slot targets
@@ -110,6 +124,12 @@ declare function surfaceProps(config: Config, componentPath: string, /** Forward
 seen?: ReadonlySet<string>): SurfaceProp[];
 /** One prop by name, or `undefined` when the component doesn't expose it. */
 declare function surfaceProp(config: Config, componentPath: string, name: string): SurfaceProp | undefined;
+/**
+ * The registry entity a prop writes through, as a path: its composite, its style property, or the
+ * ref a variant's values come from. Resolved through a route, so a prop forwarded into a layer's
+ * composite names that composite. `undefined` for a prop with none.
+ */
+declare function propRegistryRef(config: Config, componentPath: string, name: string): string | undefined;
 /**
  * Each non-root layer a component forwards to, and the sorted prop names each one receives — the
  * emitter's view, which writes a literal key set per layer. Root is absent on purpose: it takes
@@ -129,4 +149,4 @@ interface ForwardClaims {
 }
 declare function forwardClaims(config: Config, componentPath: string): ForwardClaims;
 //#endregion
-export { ForwardClaims, SurfaceCompositeProp, SurfaceProp, SurfacePropKind, SurfaceScalarProp, SurfaceSlotProp, SurfaceStylePropertyProp, SurfaceVariantProp, forwardClaims, forwardedLayers, intoName, routedProp, routedPropIn, routesContent, surfaceProp, surfaceProps };
+export { ForwardClaims, SurfaceCompositeProp, SurfaceProp, SurfacePropCondition, SurfacePropKind, SurfaceScalarProp, SurfaceSlotProp, SurfaceStylePropertyProp, SurfaceVariantProp, forwardClaims, forwardedLayers, intoName, propApplies, propRegistryRef, routedProp, routedPropIn, routesContent, surfaceProp, surfaceProps };

package/dist/framework/prop-surface.js

@@ -1,4 +1,4 @@
-import { isRef, kindOf, memberOf, pathOf } from "./utils/refs.js";
+import { isRef, kindOf, memberOf, pathOf, refLeaf } from "./utils/refs.js";
 import { forwardsOf, rootLayerOf } from "../entities/system/element.js";
 import { propValueDomain, resolveComponentProps } from "./projections.js";
 import { Component } from "../entities/system/Component.js";
@@ -19,6 +19,34 @@ import { Component } from "../entities/system/Component.js";
 * its domain (an icon prop drawing its names from the icon library rather than copying them in),
 * which is why value lists are never read straight off `value`.
 */
+/** A stored condition as leaves, one list per prop it names; `undefined` for none. */
+function conditionLeaves(when) {
+	if (when === null || typeof when !== "object" || Array.isArray(when)) return;
+	const entries = Object.entries(when).filter(([, value]) => value !== void 0 && value !== null).map(([name, value]) => [name, (Array.isArray(value) ? value : [value]).map(refLeaf)]);
+	return entries.length > 0 ? Object.fromEntries(entries) : void 0;
+}
+/** The projected prop under ITS OWN condition. A forward resolved through carries the far prop's
+*  condition, which speaks of that component's siblings and means nothing here. */
+function conditioned(prop, when) {
+	const { when: _far, ...own } = prop;
+	return when ? {
+		...own,
+		when
+	} : own;
+}
+/**
+* Whether a prop applies under the values in force — every prop its condition names holds one of the
+* leaves listed for it. A prop with no condition always applies; an unset prop satisfies nothing.
+* Compared as strings, since a control hands back what it displays.
+*/
+function propApplies(prop, values) {
+	if (!prop.when) return true;
+	return Object.entries(prop.when).every(([name, leaves]) => {
+		const value = values[name];
+		if (value === void 0 || value === null) return false;
+		return leaves.some((leaf) => String(leaf) === String(value));
+	});
+}
 /** The tail of a ref, when the value is one. */
 function refPath(value) {
 	return isRef(value) ? pathOf(value.__ref) : void 0;
@@ -82,25 +110,62 @@ function routedProp(config, componentPath, decl) {
 	return routedPropIn(config, body?.layers, decl);
 }
 function routesContent(config, layers, decl) {
-	const routed = routedPropIn(config, layers, decl);
-	if (routed) return routed.type === "slot";
-	return refPath(decl.target) !== void 0 && intoName(decl.into) === "children";
+	const end = routeEnd(config, layers, decl);
+	if (!end) return false;
+	if (end.decl) return end.decl.type === "slot";
+	return refPath(end.route.target) !== void 0 && intoName(end.route.into) === "children";
+}
+/**
+* Whether a route is typed in place once every forward between is followed: it lands on a text slot,
+* or the last forward it follows says `text` itself. A message's `badge` routes into `Badge.children`,
+* which forwards onto Badge's text layer, so the route is text although neither end of the first hop
+* says so. The declaration the route starts from is the caller's to read.
+*/
+function routesIntoText(config, layers, decl) {
+	const end = routeEnd(config, layers, decl);
+	if (!end) return false;
+	if (end.decl?.type === "slot" && end.decl.text === true) return true;
+	return end.route.text === true;
+}
+/**
+* Where a route ends once every forward between is followed. A message's `badge` routes into
+* `Badge.children`, which is itself a forward onto Badge's text layer; the route ends where that one
+* does. `decl` is the declaration it lands on, absent for a layer that renders a tag or a prop nobody
+* declares, and `route` is the last forward followed, whose `into` names what it asked that layer
+* for. `undefined` for a route that comes back around to itself.
+*/
+function routeEnd(config, layers, decl, seen = /* @__PURE__ */ new Set()) {
+	const landed = routedPropIn(config, layers, decl);
+	if (landed?.type !== "forward") return {
+		decl: landed,
+		route: decl
+	};
+	const layerKey = refPath(decl.target);
+	const target = layerKey ? refPath(layers?.[layerKey]) : void 0;
+	if (!target) return {
+		decl: landed,
+		route: decl
+	};
+	const key = `${target}#${intoName(decl.into)}`;
+	if (seen.has(key)) return void 0;
+	const farLayers = (Component.get(config, target)?.toJSON())?.layers;
+	return routeEnd(config, farLayers, landed, new Set([...seen, key]));
 }
 function slotProp(config, componentPath, name, decl) {
 	const refs = acceptsRefs(decl.accepts);
 	const icons = refs.find((ref) => kindOf(ref) === "icon");
-	const routed = routedProp(config, componentPath, decl);
+	const layers = (Component.get(config, componentPath)?.toJSON())?.layers;
+	const routed = routeEnd(config, layers, decl)?.decl;
 	const routedKind = routed?.type;
 	const targetLayer = refPath(decl.target);
-	const routesIntoText = routed?.type === "slot" && routed.text === true;
 	return {
 		name,
 		kind: "slot",
 		required: decl.required === true,
-		text: decl.text === true || routesIntoText,
+		text: decl.text === true || routesIntoText(config, layers, decl),
 		...targetLayer ? {
 			targetLayer,
-			into: decl.into ?? "children"
+			into: intoName(decl.into)
 		} : {},
 		accepts: refs.filter((ref) => kindOf(ref) === "component").map((ref) => pathOf(ref)),
 		...icons ? { acceptsIconLibrary: pathOf(icons) } : {},
@@ -121,61 +186,62 @@ function surfaceProps(config, componentPath, seen = /* @__PURE__ */ new Set()) {
 	const props = [];
 	for (const [name, decl] of Object.entries(declared)) {
 		const required = decl.required === true;
+		const when = conditionLeaves(decl.when);
 		if (decl.type === "forward") {
 			if (routesContent(config, layers, decl)) {
-				props.push(slotProp(config, componentPath, name, decl));
+				props.push(conditioned(slotProp(config, componentPath, name, decl), when));
 				continue;
 			}
 			const routed = boundProp(config, layers, decl, seen);
-			if (routed) props.push({
+			if (routed) props.push(conditioned({
 				...routed,
 				name,
 				required
-			});
+			}, when));
 			continue;
 		}
 		if (decl.type === "slot") {
-			props.push(slotProp(config, componentPath, name, decl));
+			props.push(conditioned(slotProp(config, componentPath, name, decl), when));
 			continue;
 		}
 		if (decl.type === "variant") {
 			const iconLibrary = variantIconLibrary(config, decl.value);
-			props.push({
+			props.push(conditioned({
 				name,
 				kind: "variant",
 				required,
 				values: propValueDomain(config, decl)?.leaves ?? [],
 				...iconLibrary !== void 0 ? { iconLibrary } : {}
-			});
+			}, when));
 			continue;
 		}
 		if (decl.type === "styleProperty") {
 			const styleProperty = refPath(decl.value);
 			if (!styleProperty) continue;
-			props.push({
+			props.push(conditioned({
 				name,
 				kind: "styleProperty",
 				required,
 				styleProperty
-			});
+			}, when));
 			continue;
 		}
 		if (decl.type === "composite") {
 			const compositeName = refPath(decl.value);
 			if (!compositeName) continue;
-			props.push({
+			props.push(conditioned({
 				name,
 				kind: "composite",
 				required,
 				compositeName
-			});
+			}, when));
 			continue;
 		}
-		if (decl.type === "string" || decl.type === "number" || decl.type === "boolean" || decl.type === "motion") props.push({
+		if (decl.type === "string" || decl.type === "number" || decl.type === "boolean" || decl.type === "motion") props.push(conditioned({
 			name,
 			kind: decl.type,
 			required
-		});
+		}, when));
 	}
 	return props;
 }
@@ -198,6 +264,18 @@ function surfaceProp(config, componentPath, name) {
 	return surfaceProps(config, componentPath).find((prop) => prop.name === name);
 }
 /**
+* The registry entity a prop writes through, as a path: its composite, its style property, or the
+* ref a variant's values come from. Resolved through a route, so a prop forwarded into a layer's
+* composite names that composite. `undefined` for a prop with none.
+*/
+function propRegistryRef(config, componentPath, name) {
+	const surfaced = surfaceProp(config, componentPath, name);
+	if (surfaced?.kind === "composite") return surfaced.compositeName;
+	if (surfaced?.kind === "styleProperty") return surfaced.styleProperty;
+	const decl = resolveComponentProps(config, componentPath)[name];
+	return decl?.type === "variant" ? refPath(decl.value) : void 0;
+}
+/**
 * The one precedence walk behind {@link forwardedLayers} and {@link forwardClaims}: every name a
 * `forwards` entry exposes, attributed to the layer that delivers it.
 *
@@ -275,4 +353,4 @@ function forwardClaims(config, componentPath) {
 	};
 }
 //#endregion
-export { forwardClaims, forwardedLayers, intoName, routedProp, routedPropIn, routesContent, surfaceProp, surfaceProps };
+export { forwardClaims, forwardedLayers, intoName, propApplies, propRegistryRef, routedProp, routedPropIn, routesContent, routesIntoText, surfaceProp, surfaceProps };

package/dist/framework/render-spec.d.ts

@@ -204,6 +204,54 @@ type VisibilityOperator = Exclude<keyof StateCondition, '$state' | 'not'>;
 declare function readStatePointer(state: Record<string, unknown>, pointer: string): unknown;
 /** The prop a `$state` pointer reads — its first segment, for a pointer into an object prop. */
 declare function statePointerProp(pointer: string): string;
+/**
+ * The marker on an element a render placed inline, naming its anatomy node. A layer is addressed by
+ * `data-uds-layer`; this is for the node between layers that has no bag of its own. Stamped by the
+ * emitted module and by both projections, so a rendered element and a projected one read alike.
+ */
+declare const ANATOMY_MARKER = "data-uds-anatomy";
+/**
+ * The value prop a component paints as a layer's text: the anatomy node rendering `layer` binds its
+ * `children` to `{ $state: '/<prop>' }`, and that prop is declared a string or number. A forward
+ * surfaces its layer on the prop itself; this answers for a render that reads a value prop and
+ * writes it into a layer by hand, the way a `title` string reaches a heading.
+ */
+declare function layerTextProp({
+  config,
+  path,
+  layer
+}: {
+  config: Config;
+  path: string;
+  layer: string;
+}): string | undefined;
+/**
+ * The value prop a component hands an element it placed inline: the anatomy node `element` binds
+ * `into` to `{ $state: '/<prop>' }`, and that prop is a string or number. `into` is `children` for
+ * text the element shows itself, or the far component's prop the render passed it to
+ * (`<CommentHeader title={title} />` binds `title`).
+ */
+declare function anatomyTextProp({
+  config,
+  path,
+  element,
+  into
+}: {
+  config: Config;
+  path: string;
+  element: string;
+  into: string;
+}): string | undefined;
+/** The component an inline anatomy element renders, when it is one (`component:<path>`). */
+declare function anatomyElementComponent({
+  config,
+  path,
+  element
+}: {
+  config: Config;
+  path: string;
+  element: string;
+}): string | undefined;
 /** A value in json-render's `visible` grammar, resolved against a prop bag. `undefined` when this
  *  reader can't settle it, which leaves the condition on the element for the renderer to judge. */
 declare function resolveVisibility(condition: unknown, state: Record<string, unknown>): boolean | undefined;
@@ -301,10 +349,62 @@ interface SlotTarget {
  * the layer meant to hold it renders empty. Every one of Studio's own components shaped that way
  * (`Badge`, `StudioButton`, `Toggle`, …) painted as an empty shell in the component editor.
  *
- * Exported so the answer has ONE owner. An untargeted slot still resolves to the root here — that is
- * `slotTargets`' rule, not a caller's assumption, and it is the same rule the expansion renders by.
+ * Exported so the answer has ONE owner. An untargeted slot is hosted by the layer the anatomy
+ * places its content-position node in — a row's `leading` slot sits in its `leading` Box — and by the
+ * root when the anatomy records no position for it, which is where the expansion renders it.
  */
 declare function slotTargetsOf(config: Config, path: string): SlotTarget[];
+/**
+ * Layer → the forwards that hand a VALUE to one of its props.
+ *
+ * `startIcon: { type: 'forward', target: 'startIcon/name' }` and `swatch: { type: 'forward', target:
+ * 'swatch/swatchColor' }` are this shape: the instance's value lands on the layer's element as the
+ * prop the forward names, the way the emitted module spreads it into that layer's bundle. A forward
+ * whose target prop is a slot is content instead, and {@link slotTargetsOf} answers for it.
+ */
+declare function valueForwardsOf(config: Config, path: string): SlotTarget[];
+/**
+ * The instance props whose values or content reach `layer`: content routed into it, values
+ * forwarded onto one of its props, and the props the layer exposes through `forwards`. A file
+ * editing a placed instance can change exactly these about the layer; the layer's own styles are
+ * the component's.
+ */
+/**
+ * The instance prop whose content or value lands on `into` of `layer`, or `undefined` when the
+ * layer owns that prop itself. A change to the layer's prop in a cell is then a change to the
+ * instance prop's preview value, not a style.
+ */
+declare function propInto({
+  config,
+  path,
+  layer,
+  into
+}: {
+  config: Config;
+  path: string;
+  layer: string;
+  into: string;
+}): string | undefined;
+/** The route a prop's content or value takes into a layer, or `undefined` for a prop that reaches
+ *  no layer. */
+declare function routeOf({
+  config,
+  path,
+  prop
+}: {
+  config: Config;
+  path: string;
+  prop: string;
+}): SlotTarget | undefined;
+declare function propsIntoLayer({
+  config,
+  path,
+  layer
+}: {
+  config: Config;
+  path: string;
+  layer: string;
+}): string[];
 /**
  * Expand every component element the renderer can't name into the tree it is made of.
  *
@@ -323,4 +423,4 @@ declare function expandSpec(config: Config, spec: RenderSpec, options?: ExpandOp
  */
 declare function expandComponent(config: Config, path: string, props?: Record<string, unknown>, options?: ExpandOptions): ExpansionResult;
 //#endregion
-export { ComponentSpec, ComponentSpecs, ExpandOptions, ExpansionResult, RenderElement, RenderSpec, SlotTarget, VisibilityOperator, VisibilityTerm, boundElementType, componentSpec, deriveSpec, entryKeyOf, expandComponent, expandSpec, instanceSpec, liveStateProps, previewSpec, readStatePointer, resolveVisibility, slotTargetsOf, specWithResolvedVisibility, statePointerProp, visibilityStateProps, visibilityTerms, withoutTruthyTerm, wrappedElementKey };
+export { ANATOMY_MARKER, ComponentSpec, ComponentSpecs, ExpandOptions, ExpansionResult, RenderElement, RenderSpec, SlotTarget, VisibilityOperator, VisibilityTerm, anatomyElementComponent, anatomyTextProp, boundElementType, componentSpec, deriveSpec, entryKeyOf, expandComponent, expandSpec, instanceSpec, layerTextProp, liveStateProps, previewSpec, propInto, propsIntoLayer, readStatePointer, resolveVisibility, routeOf, slotTargetsOf, specWithResolvedVisibility, statePointerProp, valueForwardsOf, visibilityStateProps, visibilityTerms, withoutTruthyTerm, wrappedElementKey };