@yahoo/uds-create-config 4.25.1 → 4.26.1

package/dist/entities/system/Component.js

@@ -8,7 +8,7 @@ import { defineSubEntity } from "../../framework/defineSubEntity.js";
 import { derivedColor, gradient } from "./color.js";
 import { listedIn } from "../../framework/utils/enumerated.js";
 import { valueSchemaOf } from "../../framework/value-domain.js";
-import { glyphLeafOf } from "./glyph-identity.js";
+import { bindPreviewGlyphs, glyphLeafOf } from "./glyph-identity.js";
 import { Style, addBagKeyIssues, anatomyPropValue, bagNameEdges, bagRewriteName, bindBagTokens, collectBag, isPlainRecord, openBag, styleValue } from "./style-bag.js";
 import { storedPreview } from "../../framework/preview-store.js";
 import { glyphPropsOf, propValueDomain, refListOf, resolveComponentProps, stylePropValueLeaves, validateComponentProps } from "../../framework/projections.js";
@@ -21,7 +21,7 @@ import { File } from "./File.js";
 import { iconDomainInvariants } from "./icon-domain-invariants.js";
 import { rootLayerInvariants } from "./root-layer-invariants.js";
 import { Token } from "./Token.js";
-import { carriesContent, intoName, isValueSlot, routedPropIn, routesContent } from "../../framework/prop-surface.js";
+import { carriesContent, intoName, isValueSlot, renderBoundProp, routedPropIn, routesContent } from "../../framework/prop-surface.js";
 import { z } from "zod";
 //#region src/entities/system/Component.ts
 /**
@@ -985,7 +985,10 @@ const Preview = defineSubEntity({
 				for (const [name, decl] of Object.entries(body.props ?? {})) when[name] = conditionValue(name, decl, config).optional();
 				return z.strictObject({
 					when: z.strictObject(when, { error: previewShapeError }).nullable().default(null),
-					props: z.record(z.string(), z.unknown())
+					props: z.record(z.string(), z.unknown()).transform((props) => bindPreviewGlyphs({
+						config,
+						props
+					}))
 				}, { error: previewShapeError });
 			}
 		});
@@ -1329,11 +1332,13 @@ const AnatomyNode = defineSubEntity({
 					continue;
 				}
 				if (!isPlainObject(value) || !("$state" in value)) continue;
+				const read = renderBoundProp(value);
+				if (read !== void 0 && body.props && read in body.props) continue;
 				ctx.issues.push({
 					code: "custom",
 					input: value,
 					path: ["props", prop],
-					message: `\`${prop}\` is bound with \`$state\`, which anatomy uses for \`visible\` and for an \`element\` a prop chooses, never for a prop value: the object would reach the element as-is and paint nothing. Content reaches a node through the prop's declaration — \`{ "type": "forward", "target": "<layer>/children" }\` lands it in that layer, and a \`{ "element": "Slot", "props": { "name": "<prop>" } }\` node among a parent's \`children\` marks where a slot's content goes. To vary content by a prop, give each state its own node and choose between them with \`visible\`.`
+					message: `\`${prop}\` is bound with \`$state\`, which anatomy uses for \`visible\` and for an \`element\` a prop chooses, and for a bare read of one of this component's own props that the render passes down (\`{ "$state": "/<prop>" }\`); any other binding would reach the element as-is and paint nothing. Content reaches a node through the prop's declaration — \`{ "type": "forward", "target": "<layer>/children" }\` lands it in that layer, and a \`{ "element": "Slot", "props": { "name": "<prop>" } }\` node among a parent's \`children\` marks where a slot's content goes. To vary content by a prop, give each state its own node and choose between them with \`visible\`.`
 				});
 			}
 			const slotAnatomyProp = slotAnatomyPropOf({

package/dist/entities/system/Icon.js

@@ -1,6 +1,6 @@
 import { isRef, pathOf } from "../../framework/utils/refs.js";
 import { defineEntity } from "../../framework/defineEntity.js";
-import { glyphOfLibrary, recordGlyphIdentities } from "./glyph-identity.js";
+import { glyphOfLibrary, libraryGlyphFacts, recordGlyphIdentities } from "./glyph-identity.js";
 import { Package } from "./Package.js";
 import { iconDomainInvariants } from "./icon-domain-invariants.js";
 import { iconMemberMetadata, iconMetadataDeclaration } from "./icon-metadata.js";
@@ -93,15 +93,11 @@ glyphs: ({ input, body }) => {
 	* open-bag pass turned it into. Either is answered as the member name when the export is one of
 	* this library's and comes from the module its `package` names.
 	*/
-	authoredValue: ({ config, target, leaves }) => {
-		const meta = config.configFor(target)?.groupMeta("icon", pathOf(target));
-		const module = isRef(meta?.package) ? pathOf(meta.package) : void 0;
-		return glyphOfLibrary({
-			library: pathOf(target),
-			module,
-			leaves
-		});
-	},
+	authoredValue: ({ config, target, leaves }) => glyphOfLibrary(libraryGlyphFacts({
+		config,
+		target,
+		leaves
+	})),
 	invariants: (config) => iconDomainInvariants(config)
 });
 //#endregion

package/dist/entities/system/defineComponent.js

@@ -1,5 +1,5 @@
 import { canonicalCondition, isRef, kindOf, memberRef, pathOf } from "../../framework/utils/refs.js";
-import { isComponentType } from "./glyph-identity.js";
+import { glyphIdentityOf, glyphPackageRefOf, isComponentType } from "./glyph-identity.js";
 import "../../framework/preview-store.js";
 import { Component, canonicalWhen, layerRef } from "./Component.js";
 //#region src/entities/system/defineComponent.ts
@@ -46,13 +46,10 @@ function build(body) {
 * this runs when a config is registered, and a reader can't tell which made the config it holds.
 *
 * 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.
-*
-* OPEN: a foreign component (a Phosphor glyph) is dropped. Its export is known once its library has
-* handed `register` its namespace (`glyphIdentityOf`), but a preview entry's props are stored open
-* (`Preview.fields`) and never re-bound to a member, so a ref written here would reach the build as
-* a package export the package row never lists. An absent default renders nothing; the build fills
-* the prop from the import specifier (`extractPreviewProps`).
+* so the receiving component gets the component back rather than a node. A glyph of a registered
+* library stores as its package export, and the owner-bound pass (`Preview.fields`) binds that to
+* the library member, the spelling the build writes. A component neither side can name is dropped:
+* an absent default renders nothing, where a guessed ref would render the wrong thing.
 */
 function storableProps(props) {
 	if (props === void 0) return void 0;
@@ -68,9 +65,13 @@ function storableProps(props) {
 function isReactElement(value) {
 	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. */
+/** A component handed as a value, as the ref that names it: a component of this system under its
+*  path, a glyph a library handed `register` as its package export. `undefined` for one neither
+*  names. */
 function storableComponentRef(value) {
-	return isComponentElement(value) && value.path ? Component.ref(value.path) : void 0;
+	if (isComponentElement(value) && value.path) return Component.ref(value.path);
+	const identity = glyphIdentityOf(value);
+	return identity ? glyphPackageRefOf(identity) : void 0;
 }
 const FRAGMENT = Symbol.for("react.fragment");
 /**

package/dist/entities/system/glyph-identity.js

@@ -99,6 +99,25 @@ const glyphPackageRef = z.custom(isComponentType).transform((value, ctx) => {
 });
 glyphPackageRef._zod.toJSONSchema = () => ({ not: {} });
 /**
+* The facts for the library a target names. `target` is the library's ref (`icon:phosphor`, with a
+* source qualifier for a borrowed set), whose config answers for its `package`. `leaves` may be
+* handed in by a domain that has already expanded them.
+*/
+function libraryGlyphFacts({ config, target, leaves = memberLeaves(config, target) }) {
+	const library = pathOf(target);
+	const named = (config.configFor(target)?.groupMeta("icon", library))?.package;
+	return {
+		library,
+		module: isRef(named) ? pathOf(named) : void 0,
+		leaves
+	};
+}
+/** Whether a library ships a glyph: the identity's specifier is the library's package and its name
+*  is one of the members. */
+function libraryClaims(facts, identity) {
+	return facts.module === identity.specifier && facts.leaves.includes(identity.name);
+}
+/**
 * The owner-bound form of a glyph for one library: a component or its `package:` ref, answered as
 * the member name so the domain binds it like a written leaf. Refused, naming the reason, when the
 * export belongs to another module than the library draws from or is not one of its members.
@@ -138,16 +157,42 @@ function glyphOfLibrary({ library, module, leaves }) {
 * so a glyph of a library the key does not reach says so.
 */
 function glyphLeafOf({ config, libraries }) {
-	const arms = libraries.map((library) => {
-		const named = config.groupMeta("icon", library)?.package;
-		return glyphOfLibrary({
-			library,
-			module: isRef(named) ? pathOf(named) : void 0,
-			leaves: memberLeaves(config, `icon:${library}`)
-		});
-	});
+	const arms = libraries.map((library) => glyphOfLibrary(libraryGlyphFacts({
+		config,
+		target: `icon:${library}`
+	})));
 	if (arms.length === 1) return arms[0];
 	return z.union(arms);
 }
+/** `icon:<library>/<name>` for a glyph identity a library of this config claims; `undefined` when
+*  none does. */
+function glyphMemberRefOf(config, identity) {
+	for (const { path } of config.groups("icon")) if (libraryClaims(libraryGlyphFacts({
+		config,
+		target: `icon:${path}`
+	}), identity)) return { __ref: `icon:${path}/${identity.name}` };
+}
+/**
+* Preview props with every glyph bound to its library member.
+*
+* A glyph handed under `.preview()` is stored open as the package export it is
+* (`package:<specifier>#<name>`), since the props there are not each bound to a declared prop the
+* way `defaultProps` are. Once an owner is known, this pass binds each such ref to
+* `icon:<library>/<name>` through the library whose package ships it, at the top level and inside a
+* stored element's props, which is the spelling the build writes when it reads `.preview()` from
+* source. A `package:` ref no library claims is another package's export and stays as written.
+*/
+function bindPreviewGlyphs({ config, props }) {
+	const bind = (value) => {
+		if (typeof value !== "object" || value === null) return value;
+		if (Array.isArray(value)) return value.map(bind);
+		const identity = glyphIdentityOfRef(value);
+		if (identity) return glyphMemberRefOf(config, identity) ?? value;
+		const out = {};
+		for (const [key, member] of Object.entries(value)) out[key] = bind(member);
+		return out;
+	};
+	return bind(props);
+}
 //#endregion
-export { glyphLeafOf, glyphOfLibrary, glyphPackageRef, isComponentType, recordGlyphIdentities };
+export { bindPreviewGlyphs, glyphIdentityOf, glyphLeafOf, glyphOfLibrary, glyphPackageRef, glyphPackageRefOf, isComponentType, libraryGlyphFacts, recordGlyphIdentities };

package/dist/framework/bindings.d.ts

@@ -0,0 +1,97 @@
+import { Config } from "./Config.js";
+import { BindingKind } from "./prop-surface.js";
+
+//#region src/framework/bindings.d.ts
+/** Which marker a value is, by the key that makes it one. */
+type MarkerKind = 'state' | 'bindState' | 'cond' | 'item' | 'index' | 'computed' | 'template' | 'other';
+/**
+ * The marker a value is, or `undefined` for a literal. A record with any other `$`-prefixed key is
+ * `other`: a directive this module can name but not settle.
+ */
+declare function markerKind(value: unknown): MarkerKind | undefined;
+/** Whether a value reads state anywhere, however deep: a `$state` or `$bindState`, in a prop value or
+ *  in a condition. */
+declare function readsState(value: unknown): boolean;
+/** The state path a `$state` or `$bindState` reads, as written, or `undefined` for any other value. */
+declare function bindingPath(value: unknown): string | undefined;
+/** A `$cond` value's parts, or `undefined` for any other value. */
+declare function condArms(value: unknown): {
+  when: unknown;
+  ifTrue: unknown;
+  ifFalse: unknown;
+} | undefined;
+/** Whether a marker sits anywhere in a value, however deep. */
+declare function containsMarker(value: unknown): boolean;
+/** A value settled against a prop state, or the fact that it could not be. */
+type ResolvedBinding = {
+  readonly resolved: true;
+  readonly value: unknown;
+} | {
+  readonly resolved: false;
+};
+/**
+ * A value settled against `state`, the whole prop state of the instance being read: its defaults,
+ * overrides and cell coordinate.
+ *
+ * A `$state` or `$bindState` reads the state, and a prop the state lacks reads `undefined`. A
+ * `$cond` settles only when its condition reads props the state holds, since a capture can key a
+ * condition on a seed no prop state carries, and reading that seed as `undefined` would pick a
+ * branch the render never paints. Only the branch taken has to settle. Any other directive, and
+ * `$template` in particular, which interpolates an unread path to `''`, stays unresolved.
+ */
+declare function resolveBinding(value: unknown, state: Record<string, unknown>): ResolvedBinding;
+/** A read of one prop: `{ $state: '/tone' }`. */
+declare function stateRef(prop: string): {
+  $state: string;
+};
+/** A two-way read of one state key, for a control that writes it back: `{ $bindState: '/open' }`. */
+declare function bindStateRef(key: string): {
+  $bindState: string;
+};
+/**
+ * A test of one prop, in the grammar `visible` and `$cond` share: truthy, or equal to a value, and
+ * negated with `not`. Naming `eq` makes it a comparison even when its value is `undefined`.
+ */
+declare function stateTest(test: {
+  prop: string;
+  eq?: unknown;
+  not?: boolean;
+}): Record<string, unknown>;
+/** A value chosen by a condition: `{ $cond, $then, $else }`. */
+declare function condValue({
+  when,
+  ifTrue,
+  ifFalse
+}: {
+  when: unknown;
+  ifTrue: unknown;
+  ifFalse: unknown;
+}): {
+  $cond: unknown;
+  $then: unknown;
+  $else: unknown;
+};
+/** The component prop that drives one of a layer's props, and how it gets there. */
+interface LayerPropDriver {
+  /** The component prop, without a pointer slash. */
+  readonly prop: string;
+  /** A declared forward, or a binding the render recorded. */
+  readonly kind: BindingKind;
+  /** For a render binding, the anatomy node it sits on, which is what clearing it edits. */
+  readonly node?: string;
+}
+/**
+ * Every prop of `layer` a component prop drives, keyed by the layer prop. A declared forward wins
+ * where a render binding names the same layer prop.
+ */
+declare function layerPropDrivers({
+  config,
+  path,
+  layer
+}: {
+  config: Config;
+  path: string;
+  layer: string;
+}): Record<string, LayerPropDriver>;
+//#endregion
+export { LayerPropDriver, MarkerKind, ResolvedBinding, bindStateRef, bindingPath, condArms, condValue, containsMarker, layerPropDrivers, markerKind, readsState, resolveBinding, stateRef, stateTest };

package/dist/framework/bindings.js

@@ -0,0 +1,173 @@
+import { isExpression, readStatePointer, resolveVisibility, slotTargetsOf, valueForwardsOf } from "./render-spec.js";
+import { renderBindingsOf } from "./prop-surface.js";
+//#region src/framework/bindings.ts
+const KIND_BY_KEY = [
+	["$bindState", "bindState"],
+	["$cond", "cond"],
+	["$computed", "computed"],
+	["$template", "template"],
+	["$item", "item"],
+	["$index", "index"],
+	["$state", "state"]
+];
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* The marker a value is, or `undefined` for a literal. A record with any other `$`-prefixed key is
+* `other`: a directive this module can name but not settle.
+*/
+function markerKind(value) {
+	if (!isRecord(value)) return void 0;
+	for (const [key, kind] of KIND_BY_KEY) if (key in value) return kind;
+	return Object.keys(value).some((key) => key.startsWith("$")) ? "other" : void 0;
+}
+/** Whether a value reads state anywhere, however deep: a `$state` or `$bindState`, in a prop value or
+*  in a condition. */
+function readsState(value) {
+	if (Array.isArray(value)) return value.some(readsState);
+	if (!isRecord(value)) return false;
+	if ("$state" in value || "$bindState" in value) return true;
+	return Object.values(value).some(readsState);
+}
+/** The state path a `$state` or `$bindState` reads, as written, or `undefined` for any other value. */
+function bindingPath(value) {
+	if (!isRecord(value)) return void 0;
+	const kind = markerKind(value);
+	const path = kind === "state" ? value.$state : kind === "bindState" ? value.$bindState : void 0;
+	return typeof path === "string" ? path : void 0;
+}
+/** A `$cond` value's parts, or `undefined` for any other value. */
+function condArms(value) {
+	if (!isRecord(value) || markerKind(value) !== "cond") return void 0;
+	if (!Object.hasOwn(value, "$then") || !Object.hasOwn(value, "$else")) return;
+	return {
+		when: value.$cond,
+		ifTrue: value.$then,
+		ifFalse: value.$else
+	};
+}
+/** Whether a marker sits anywhere in a value, however deep. */
+function containsMarker(value) {
+	if (Array.isArray(value)) return value.some(containsMarker);
+	if (!isRecord(value)) return false;
+	if (isExpression(value) || markerKind(value) !== void 0) return true;
+	return Object.values(value).some(containsMarker);
+}
+const UNRESOLVED = { resolved: false };
+/**
+* A value settled against `state`, the whole prop state of the instance being read: its defaults,
+* overrides and cell coordinate.
+*
+* A `$state` or `$bindState` reads the state, and a prop the state lacks reads `undefined`. A
+* `$cond` settles only when its condition reads props the state holds, since a capture can key a
+* condition on a seed no prop state carries, and reading that seed as `undefined` would pick a
+* branch the render never paints. Only the branch taken has to settle. Any other directive, and
+* `$template` in particular, which interpolates an unread path to `''`, stays unresolved.
+*/
+function resolveBinding(value, state) {
+	if (Array.isArray(value)) {
+		const out = [];
+		for (const entry of value) {
+			const inner = resolveBinding(entry, state);
+			if (!inner.resolved) return UNRESOLVED;
+			out.push(inner.value);
+		}
+		return {
+			resolved: true,
+			value: out
+		};
+	}
+	if (!isRecord(value)) return {
+		resolved: true,
+		value
+	};
+	const kind = markerKind(value);
+	const directives = Object.keys(value).filter((key) => key.startsWith("$"));
+	if (kind === void 0) {
+		const out = {};
+		for (const [key, member] of Object.entries(value)) {
+			const inner = resolveBinding(member, state);
+			if (!inner.resolved) return UNRESOLVED;
+			out[key] = inner.value;
+		}
+		return {
+			resolved: true,
+			value: out
+		};
+	}
+	if (kind === "cond") {
+		if (directives.some((key) => !COND_KEYS.has(key))) return UNRESOLVED;
+		const holds = resolveVisibility(value.$cond, state, { seededOnly: true });
+		if (holds === void 0) return UNRESOLVED;
+		return resolveBinding(holds ? value.$then : value.$else, state);
+	}
+	if (directives.length !== 1) return UNRESOLVED;
+	const pointer = kind === "state" ? value.$state : value.$bindState;
+	if (kind !== "state" && kind !== "bindState" || typeof pointer !== "string") return UNRESOLVED;
+	return {
+		resolved: true,
+		value: readStatePointer(state, pointer)
+	};
+}
+const COND_KEYS = new Set([
+	"$cond",
+	"$then",
+	"$else"
+]);
+/** The JSON pointer json-render reads a prop by: `/tone`. */
+function pointerTo(prop) {
+	return prop.startsWith("/") ? prop : `/${prop}`;
+}
+/** A read of one prop: `{ $state: '/tone' }`. */
+function stateRef(prop) {
+	return { $state: pointerTo(prop) };
+}
+/** A two-way read of one state key, for a control that writes it back: `{ $bindState: '/open' }`. */
+function bindStateRef(key) {
+	return { $bindState: pointerTo(key) };
+}
+/**
+* A test of one prop, in the grammar `visible` and `$cond` share: truthy, or equal to a value, and
+* negated with `not`. Naming `eq` makes it a comparison even when its value is `undefined`.
+*/
+function stateTest(test) {
+	return {
+		...stateRef(test.prop),
+		...Object.hasOwn(test, "eq") ? { eq: test.eq } : {},
+		...test.not ? { not: true } : {}
+	};
+}
+/** A value chosen by a condition: `{ $cond, $then, $else }`. */
+function condValue({ when, ifTrue, ifFalse }) {
+	return {
+		$cond: when,
+		$then: ifTrue,
+		$else: ifFalse
+	};
+}
+/**
+* Every prop of `layer` a component prop drives, keyed by the layer prop. A declared forward wins
+* where a render binding names the same layer prop.
+*/
+function layerPropDrivers({ config, path, layer }) {
+	const out = {};
+	for (const route of [...slotTargetsOf(config, path), ...valueForwardsOf(config, path)]) {
+		if (route.layer !== layer || route.into in out) continue;
+		out[route.into] = {
+			prop: route.from,
+			kind: "forward"
+		};
+	}
+	for (const route of renderBindingsOf(config, path)) {
+		if (route.layer !== layer || route.into in out) continue;
+		out[route.into] = {
+			prop: route.from,
+			kind: "render",
+			...route.node !== void 0 ? { node: route.node } : {}
+		};
+	}
+	return out;
+}
+//#endregion
+export { bindStateRef, bindingPath, condArms, condValue, containsMarker, layerPropDrivers, markerKind, readsState, resolveBinding, stateRef, stateTest };

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

@@ -191,5 +191,27 @@ declare function forwardClaims(config: Config, componentPath: string): ForwardCl
  * surface editing the layer's values has nothing to write for it.
  */
 declare function layerPropRoutes(config: Config, componentPath: string, layer: string): ReadonlyMap<string, string>;
+/** How a component prop reaches a layer prop: a `forward` the config declares, or a read the render
+ *  records (`<Pill color={color} />`). */
+type BindingKind = 'forward' | 'render';
+/** A component prop delivered to one prop of one layer. */
+interface PropRoute {
+  readonly layer: string;
+  /** The component prop the value arrives as. */
+  readonly from: string;
+  /** The layer prop it lands on. */
+  readonly into: string;
+  /** The anatomy node the render binding sits on, for a route the render records; absent for a
+   *  declared forward. */
+  readonly node?: string;
+}
+/**
+ * The layer props a render binds to a component prop by name, as routes. `<ChipButton color={color} />`
+ * in a render is recorded on the layer's node as `color: { $state: '/color' }`, the same relationship a
+ * `forward` declares, so a surface routing a layer prop back to the instance prop that delivers it
+ * reads both. Only a bare, single-segment `$state` naming a declared prop counts: a nested pointer or
+ * a conditional is a value a surface shows, not a prop it edits.
+ */
+declare function renderBindingsOf(config: Config, componentPath: string): PropRoute[];
 //#endregion
-export { CodeSlot, ForwardClaims, SurfaceCompositeProp, SurfaceProp, SurfacePropCondition, SurfacePropKind, SurfaceScalarProp, SurfaceSlotProp, SurfaceStylePropertyProp, SurfaceVariantProp, codeSlotsOf, forwardClaims, forwardedLayers, intoName, isValueSlot, layerPropRoutes, propApplies, propRegistryRef, routedProp, routedPropIn, routesContent, slotCodeForms, standsInForCode, surfaceProp, surfaceProps };
+export { BindingKind, CodeSlot, ForwardClaims, PropRoute, SurfaceCompositeProp, SurfaceProp, SurfacePropCondition, SurfacePropKind, SurfaceScalarProp, SurfaceSlotProp, SurfaceStylePropertyProp, SurfaceVariantProp, codeSlotsOf, forwardClaims, forwardedLayers, intoName, isValueSlot, layerPropRoutes, propApplies, propRegistryRef, renderBindingsOf, routedProp, routedPropIn, routesContent, slotCodeForms, standsInForCode, surfaceProp, surfaceProps };

package/dist/framework/prop-surface.js

@@ -1,7 +1,7 @@
 import { isRef, kindOf, memberOf, pathOf, refLeaf } from "./utils/refs.js";
 import { forwardsOf, rootLayerOf } from "../entities/system/element.js";
 import { propValueDomain, refListOf, resolveComponentProps, takenByForward } from "./projections.js";
-import { slotHostLayer } from "./slot-host.js";
+import { layerOfElement, slotHostLayer } from "./slot-host.js";
 import { Component } from "../entities/system/Component.js";
 //#region src/framework/prop-surface.ts
 /**
@@ -461,7 +461,45 @@ function layerPropRoutes(config, componentPath, layer) {
 	}
 	const { forwarded } = computeForwardClaims(config, componentPath);
 	for (const [name, claimedBy] of forwarded) if (claimedBy === layer && !routes.has(name)) routes.set(name, name);
+	for (const route of renderBindingsOf(config, componentPath)) if (route.layer === layer && !routes.has(route.into)) routes.set(route.into, route.from);
 	return routes;
 }
+/**
+* The layer props a render binds to a component prop by name, as routes. `<ChipButton color={color} />`
+* in a render is recorded on the layer's node as `color: { $state: '/color' }`, the same relationship a
+* `forward` declares, so a surface routing a layer prop back to the instance prop that delivers it
+* reads both. Only a bare, single-segment `$state` naming a declared prop counts: a nested pointer or
+* a conditional is a value a surface shows, not a prop it edits.
+*/
+function renderBindingsOf(config, componentPath) {
+	const body = Component.get(config, componentPath)?.toJSON();
+	if (!body?.anatomy) return [];
+	const declared = resolveComponentProps(config, componentPath);
+	const routes = [];
+	for (const [key, node] of Object.entries(body.anatomy)) {
+		const layer = layerOfElement(node.element);
+		if (layer === void 0 || !node.props) continue;
+		for (const [into, value] of Object.entries(node.props)) {
+			const from = renderBoundProp(value);
+			if (from !== void 0 && from in declared) routes.push({
+				layer,
+				from,
+				into,
+				node: key
+			});
+		}
+	}
+	return routes;
+}
+/** The prop a bare `{ $state: '/name' }` reads, or `undefined` for any other value. */
+function renderBoundProp(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return;
+	const keys = Object.keys(value);
+	if (keys.length !== 1 || keys[0] !== "$state") return void 0;
+	const pointer = value.$state;
+	if (typeof pointer !== "string" || !pointer.startsWith("/")) return void 0;
+	const name = pointer.slice(1);
+	return name.length > 0 && !name.includes("/") ? name : void 0;
+}
 //#endregion
-export { carriesContent, codeSlotsOf, forwardClaims, forwardedLayers, intoName, isValueSlot, layerPropRoutes, propApplies, propRegistryRef, routedProp, routedPropIn, routesContent, routesIntoText, slotCodeForms, standsInForCode, surfaceProp, surfaceProps };
+export { carriesContent, codeSlotsOf, forwardClaims, forwardedLayers, intoName, isValueSlot, layerPropRoutes, propApplies, propRegistryRef, renderBindingsOf, renderBoundProp, routedProp, routedPropIn, routesContent, routesIntoText, slotCodeForms, standsInForCode, surfaceProp, surfaceProps };

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

@@ -67,6 +67,10 @@ interface ResolveContext {
    *  left for the renderer (and where fill routing reads it); on inside a `$computed`'s arguments
    *  and a repeat's source, which have to be values before the call. */
   readonly settle?: boolean;
+  /** Read a `$state` only when the bag holds its prop. A condition a capture keyed on a seed no prop
+   *  state carries would otherwise read that seed as `undefined` and pick a branch the render never
+   *  takes. */
+  readonly seededOnly?: boolean;
 }
 /**
  * The registry key of an element rendered THROUGH a package factory — `motion.create(Box)`, spelled

package/dist/framework/render-spec.js

@@ -6,7 +6,7 @@ import { authoredBag, authoredValue, declaredPropDefaults, memberFromLeaf, refLi
 import { componentLayerClass, componentPropClasses, componentRuleClasses, layerRoutedProps, splitStyleProps, styleRuleMotionClasses } from "./class-names.js";
 import { graftPreviewElements } from "../spec/preview-elements.js";
 import { slotHostLayer } from "./slot-host.js";
-import { forwardedLayers, intoName, isValueSlot, routesContent } from "./prop-surface.js";
+import { forwardedLayers, intoName, isValueSlot, renderBindingsOf, routesContent } from "./prop-surface.js";
 //#region src/framework/render-spec.ts
 const refOf = (value) => typeof value?.__ref === "string" ? value.__ref : void 0;
 const layerOf = (element) => {
@@ -578,7 +578,10 @@ const UNREADABLE = Symbol("unreadable");
 * `$index` read the row of a repeated node; outside one they read nothing.
 */
 function readBinding(test, state, context) {
-	if (typeof test.$state === "string") return readStatePointer(state, test.$state);
+	if (typeof test.$state === "string") {
+		if (context.seededOnly && !Object.hasOwn(state, statePointerProp(test.$state))) return UNREADABLE;
+		return readStatePointer(state, test.$state);
+	}
 	if (typeof test.$item === "string") {
 		if (!context.row) return UNREADABLE;
 		if (test.$item === "") return context.row.item;
@@ -989,17 +992,26 @@ function valueForwardsOf(config, path) {
 * instance prop's preview value, not a style.
 */
 function propInto({ config, path, layer, into }) {
-	return [...slotTargetsOf(config, path), ...valueForwardsOf(config, path)].find((route) => route.layer === layer && route.into === into)?.from;
+	return [
+		...slotTargetsOf(config, path),
+		...valueForwardsOf(config, path),
+		...renderBindingsOf(config, path)
+	].find((route) => route.layer === layer && route.into === into)?.from;
 }
 /** The route a prop's content or value takes into a layer, or `undefined` for a prop that reaches
 *  no layer. */
 function routeOf({ config, path, prop }) {
-	return [...slotTargetsOf(config, path), ...valueForwardsOf(config, path)].find((route) => route.from === prop);
+	return [
+		...slotTargetsOf(config, path),
+		...valueForwardsOf(config, path),
+		...renderBindingsOf(config, path)
+	].find((route) => route.from === prop);
 }
 function propsIntoLayer({ config, path, layer }) {
 	const names = /* @__PURE__ */ new Set();
 	for (const route of slotTargetsOf(config, path)) if (route.layer === layer) names.add(route.from);
 	for (const route of valueForwardsOf(config, path)) if (route.layer === layer) names.add(route.from);
+	for (const route of renderBindingsOf(config, path)) if (route.layer === layer) names.add(route.from);
 	for (const name of forwardedLayers(config, path).get(layer) ?? []) names.add(name);
 	return [...names];
 }
@@ -1413,4 +1425,4 @@ function expandComponent(config, path, props = {}, options = {}) {
 	return expandSpec(config, instanceSpec(path, props), options);
 }
 //#endregion
-export { ANATOMY_MARKER, anatomyElementComponent, anatomyTextProp, andListOf, boundElementType, componentSpec, deriveSpec, entryKeyOf, expandComponent, expandSpec, instanceSpec, layerTextProp, liveStateProps, previewSpec, propInto, propsIntoLayer, readStatePointer, resolveValue, resolveVisibility, routeOf, slotAnatomyPropOf, slotTargetsOf, specWithResolvedVisibility, spelled, statePointerProp, valueForwardsOf, visibilityStateProps, visibilityTerms, withoutTruthyTerm, wrappedElementKey };
+export { ANATOMY_MARKER, anatomyElementComponent, anatomyTextProp, andListOf, boundElementType, componentSpec, deriveSpec, entryKeyOf, expandComponent, expandSpec, instanceSpec, isExpression, layerTextProp, liveStateProps, previewSpec, propInto, propsIntoLayer, readStatePointer, resolveValue, resolveVisibility, routeOf, slotAnatomyPropOf, slotTargetsOf, specWithResolvedVisibility, spelled, statePointerProp, valueForwardsOf, visibilityStateProps, visibilityTerms, withoutTruthyTerm, wrappedElementKey };

package/dist/framework/slot-host.d.ts

@@ -5,6 +5,8 @@ interface AnatomyNode {
     readonly children?: readonly string[];
     readonly slots?: Record<string, string[]>;
 }
+/** The layer a node's element renders as: a `layer:<name>` ref, or the layer a prop-chosen element stands in for. */
+export declare function layerOfElement(element: unknown): string | undefined;
 /**
  * The layer holding a slot prop's content-position node: the nearest layer above the `Slot` node
  * named for the prop, itself included. `undefined` when the anatomy records no position for the

package/dist/framework/slot-host.js

@@ -38,4 +38,4 @@ function slotHostLayer(anatomy, from) {
 	}
 }
 //#endregion
-export { slotHostLayer };
+export { layerOfElement, slotHostLayer };