@yahoo/uds-create-config 4.5.2 → 4.7.0

package/dist/entities/system/Component.js

@@ -1,5 +1,5 @@
 import { reject, rejectData } from "../../framework/rejection.js";
-import { isRef, kindOf, memberOf, pathOf, ref, refLeaf, refSchema, splitRef } from "../../framework/utils/refs.js";
+import { canonicalCondition, isRef, kindOf, memberOf, pathOf, ref, refLeaf, refSchema, splitRef } from "../../framework/utils/refs.js";
 import { isPlainObject } from "../../framework/utils/field-path.js";
 import { pathInput } from "../../framework/schemas.js";
 import { defineEntity } from "../../framework/defineEntity.js";
@@ -9,9 +9,13 @@ import { childrenPolicy } from "./element.js";
 import { listedIn } from "../../framework/utils/enumerated.js";
 import { valueSchemaOf } from "../../framework/value-domain.js";
 import { Style, addBagKeyIssues, anatomyPropValue, bagNameEdges, bagRewriteName, bindBagTokens, collectBag, isPlainRecord, openBag, styleValue } from "./style-bag.js";
+import { storedPreview } from "../../framework/preview-store.js";
 import { propValueDomain, resolveComponentProps, stylePropValueLeaves, validateComponentProps } from "../../framework/projections.js";
 import { intoName, routedPropIn, routesContent } from "../../framework/prop-surface.js";
 import { slotAnatomyPropOf, slotTargetsOf, withoutTruthyTerm } from "../../framework/render-spec.js";
+import { listSlots, namedSlots, slotHostedBy, slotOf } from "../../spec/slot.js";
+import { cellAt } from "../../spec/cell.js";
+import { instanceAt } from "../../spec/instance.js";
 import { Package } from "./Package.js";
 import { File } from "./File.js";
 import { z } from "zod";
@@ -303,8 +307,8 @@ const VariantValue = defineSubEntity({
 		*  which takes its styling with it. */
 		deprecated: z.boolean().optional()
 	}),
-	namedValuesIn: ["defaultProps", "previewProps"],
-	orphans: ["styles"]
+	namedValuesIn: ["defaultProps", "preview/*/props"],
+	orphans: ["styles", "preview"]
 });
 /**
 * A variant's domain: the values it owns, or a ref that delegates to whatever owns them.
@@ -347,60 +351,87 @@ function routedTarget(decl) {
 		into: decl.target.slice(separator + 1)
 	};
 }
-const propShape = z.discriminatedUnion("type", [
-	z.strictObject({
-		type: z.literal("slot"),
-		text: z.boolean().optional(),
-		accepts: z.union([refSchema, z.array(refSchema)]).optional(),
-		required: z.boolean().optional()
-	}),
-	z.strictObject({
-		type: z.literal("variant"),
-		value: variantDomain,
-		required: z.boolean().optional()
-	}),
-	z.strictObject({
-		type: z.literal("forward"),
-		target: z.union([layerPath, refSchema]),
-		into: z.union([z.string(), refSchema]).optional(),
-		accepts: z.union([refSchema, z.array(refSchema)]).optional(),
-		text: z.boolean().optional(),
-		required: z.boolean().optional()
-	}).transform(routedTarget),
-	z.strictObject({
-		type: z.literal("styleProperty"),
-		value: refSchema
-	}),
-	z.strictObject({
-		type: z.literal("composite"),
-		value: refSchema
-	}),
-	z.strictObject({
-		type: z.literal("motion"),
-		value: refSchema.default({ __ref: "motion:" })
-	}),
-	z.strictObject({
-		type: z.literal("string"),
-		value: z.string().optional(),
-		required: z.boolean().optional()
-	}),
-	z.strictObject({
-		type: z.literal("number"),
-		value: z.number().optional(),
-		required: z.boolean().optional()
-	}),
-	z.strictObject({
-		type: z.literal("boolean"),
-		value: z.boolean().optional(),
-		required: z.boolean().optional()
-	})
-], { error: (issue) => {
-	const type = issue.input?.type;
-	if (typeof type !== "string") return void 0;
-	const types = PROP_TYPES.join(", ");
-	if (/^style-?property$/i.test(type)) return `\`${type}\` is not a prop type; a style property is exposed as \`{ "type": "styleProperty", "value": { "__ref": "style-property:<name>" } }\`. The types are ${types}.`;
-	return `\`${type}\` is not a prop type. The types are ${types}; a style property is \`{ "type": "styleProperty", "value": { "__ref": "style-property:<name>" } }\`, content is \`{ "type": "slot", "text": true }\`.`;
-} });
+/** A prop that applies only under a condition on its siblings — the record a style rule's `when`
+*  holds. Open here, where no owner is known; `propSchemaFor` narrows it to the owner's props. */
+const conditionLeaf = z.union([
+	z.string(),
+	z.number(),
+	z.boolean(),
+	refSchema
+]);
+const propCondition = z.record(z.string(), z.union([conditionLeaf, z.array(conditionLeaf)])).optional();
+/**
+* The declaration shape over a given condition schema: the generic one with `when` open, and one
+* per owner with `when` narrowed to that component's props. A factory rather than a per-owner
+* transform over the generic shape, because a field-path write (`sub-update` at `value.warning`)
+* derives its schema from the arms' object shapes, which a transform would hide.
+*/
+function propShapeWith(when) {
+	return z.discriminatedUnion("type", [
+		z.strictObject({
+			type: z.literal("slot"),
+			text: z.boolean().optional(),
+			accepts: z.union([refSchema, z.array(refSchema)]).optional(),
+			required: z.boolean().optional(),
+			when
+		}),
+		z.strictObject({
+			type: z.literal("variant"),
+			value: variantDomain,
+			required: z.boolean().optional(),
+			when
+		}),
+		z.strictObject({
+			type: z.literal("forward"),
+			target: z.union([layerPath, refSchema]),
+			into: z.union([z.string(), refSchema]).optional(),
+			accepts: z.union([refSchema, z.array(refSchema)]).optional(),
+			text: z.boolean().optional(),
+			required: z.boolean().optional(),
+			when
+		}).transform(routedTarget),
+		z.strictObject({
+			type: z.literal("styleProperty"),
+			value: refSchema,
+			when
+		}),
+		z.strictObject({
+			type: z.literal("composite"),
+			value: refSchema,
+			when
+		}),
+		z.strictObject({
+			type: z.literal("motion"),
+			value: refSchema.default({ __ref: "motion:" }),
+			when
+		}),
+		z.strictObject({
+			type: z.literal("string"),
+			value: z.string().optional(),
+			required: z.boolean().optional(),
+			when
+		}),
+		z.strictObject({
+			type: z.literal("number"),
+			value: z.number().optional(),
+			required: z.boolean().optional(),
+			when
+		}),
+		z.strictObject({
+			type: z.literal("boolean"),
+			value: z.boolean().optional(),
+			required: z.boolean().optional(),
+			when
+		})
+	], { error: (issue) => {
+		const type = issue.input?.type;
+		if (typeof type !== "string") return void 0;
+		const types = PROP_TYPES.join(", ");
+		if (/^style-?property$/i.test(type)) return `\`${type}\` is not a prop type; a style property is exposed as \`{ "type": "styleProperty", "value": { "__ref": "style-property:<name>" } }\`. The types are ${types}.`;
+		return `\`${type}\` is not a prop type. The types are ${types}; a style property is \`{ "type": "styleProperty", "value": { "__ref": "style-property:<name>" } }\`, content is \`{ "type": "slot", "text": true }\`.`;
+	} });
+}
+const propShape = propShapeWith(propCondition);
 /** The prop types, for the refusal that names them. */
 const PROP_TYPES = [
 	"slot",
@@ -413,7 +444,7 @@ const PROP_TYPES = [
 	"number",
 	"boolean"
 ];
-const PROP_DESCRIPTION = "What the prop is. A style property the component exposes, `{ \"type\": \"styleProperty\", \"value\": { \"__ref\": \"style-property:<name>\" } }`, which is what a primitive's props mostly are and what makes a style rule's bag key valid on it; a closed set of names a style rule keys on, `{ \"type\": \"variant\", \"value\": [\"sm\", \"lg\"] }`; content, `{ \"type\": \"slot\", \"text\": true }`; or a plain `string`, `number` or `boolean`. `null` hides a prop an inherited layer would expose.";
+const PROP_DESCRIPTION = "What the prop is. A style property the component exposes, `{ \"type\": \"styleProperty\", \"value\": { \"__ref\": \"style-property:<name>\" } }`, which is what a primitive's props mostly are and what makes a style rule's bag key valid on it; a closed set of names a style rule keys on, `{ \"type\": \"variant\", \"value\": [\"sm\", \"lg\"] }`; content, `{ \"type\": \"slot\", \"text\": true }`; or a plain `string`, `number` or `boolean`. `null` hides a prop an inherited layer would expose. A prop that applies only under a condition on a sibling carries `when`, the record a style rule uses: `{ \"type\": \"string\", \"when\": { \"type\": \"color\" } }` shows it for one value, `{ \"when\": { \"type\": [\"default\", \"header\"] } }` for several.";
 /** Nullable because `null` is the omit tombstone: a component that `inherits` its element's props
 *  drops one by declaring it `null`, rather than needing a second "don't expose" mechanism. */
 const Prop = defineSubEntity({
@@ -439,14 +470,15 @@ const Prop = defineSubEntity({
 		});
 	},
 	namespaces: "value",
+	namesMembersOf: { when: "props" },
 	subEntities: { value: VariantValue },
-	keyedByNameIn: ["defaultProps", "previewProps"],
-	orphans: ["styles"]
+	keyedByNameIn: ["defaultProps", "preview/*/props"],
+	orphans: ["styles", "preview"]
 });
 /** {@link Prop}'s per-owner schema. Reached only through the memo in its `fields`. */
 function propSchemaFor(config, owner) {
 	const layers = owner.layers;
-	return propShape.nullable().check((ctx) => {
+	return propShapeWith(ownerCondition(config, owner)).nullable().check((ctx) => {
 		const decl = ctx.value;
 		if (decl === null || !isPlainObject(decl) || decl.type !== "forward" || decl.accepts === void 0 || routesContent(config, layers, decl)) return;
 		const layer = isRef(decl.target) ? pathOf(decl.target) : String(decl.target ?? "?");
@@ -460,13 +492,30 @@ function propSchemaFor(config, owner) {
 		});
 	});
 }
+/**
+* A condition narrowed to one owner's props: each key a sibling, each value one of that sibling's
+* values or a list of them. Values are stored as refs the way a style rule's condition is
+* (`conditionValue`), so a value rename cascades into the condition and a delete finds it.
+*/
+function ownerCondition(config, owner) {
+	const shape = {};
+	for (const [name, decl] of Object.entries(owner.props ?? {})) {
+		if (decl === null || decl === void 0) continue;
+		const value = conditionValue(name, decl, config);
+		shape[name] = z.union([value, z.array(value).min(1)]).optional();
+	}
+	return z.strictObject(shape, { error: (issue) => {
+		const { code, keys } = issue;
+		if (code !== "unrecognized_keys" || !keys) return void 0;
+		return `\`when\` names ${keys.map((key) => `\`${key}\``).join(", ")}, which is not a prop of this component. A condition names a sibling prop and one of its values, \`{ "when": { "type": "color" } }\`, or a list of them.`;
+	} }).optional();
+}
 const propSchemas = /* @__PURE__ */ new WeakMap();
 /** A rule's identity is its condition, as a canonical query string (`*`, `size=xs`,
 *  `size=xs&variant=tertiary`) — sorted, so the same condition always yields the same key however
 *  the editor collected it. */
 function canonicalWhen(when) {
-	const entries = Object.entries(when ?? {}).filter(([, v]) => v !== void 0 && v !== null).sort(([a], [b]) => a.localeCompare(b));
-	return entries.length === 0 ? "*" : entries.map(([k, v]) => `${k}=${String(refLeaf(v))}`).join("&");
+	return canonicalCondition(when);
 }
 /**
 * What a rule may set one prop to: the prop's own value domain, plus — for a prop that writes CSS —
@@ -752,11 +801,14 @@ function composedCreateExample(config, path) {
 				when: null,
 				layers: styleLayers
 			} } } : {},
-			previewProps: {
-				icon: true,
-				label: "Example",
-				children: "Body text"
-			}
+			preview: { ["*"]: {
+				when: null,
+				props: {
+					icon: true,
+					label: "Example",
+					children: "Body text"
+				}
+			} }
 		}
 	};
 }
@@ -859,6 +911,56 @@ function perOwner({ cache, config, owner, build }) {
 	return schema;
 }
 const ruleSchemas = /* @__PURE__ */ new WeakMap();
+const PREVIEW_DESCRIPTION = "What the catalogue tile and the matrix render with, keyed by condition the way `styles` is. The `*` entry, `{ \"when\": null, \"props\": { ... } }`, is what every cell starts from; an entry with a condition, `{ \"when\": { \"type\": \"image\" }, \"props\": { \"src\": \"…\" } }`, adds its props to the cells whose values match, in the grammar a style rule uses. A slot prop previews with a stored element, `{ \"element\": { \"__ref\": \"component:<Name>\" } }`. A condition on a prop no rule styles makes that prop a preview axis with the value named. A component whose root takes children renders empty until an entry or `defaultProps` carries some.";
+const previewShapeError = "a preview entry is `{ \"when\": null | { \"<prop>\": \"<value>\" }, \"props\": { \"<prop>\": <value> } }`: `when` names this component's own props at one of their values (`null` for the entry every cell reads) and `props` the props the matching cells preview with.";
+const previewBase = z.object({
+	when: z.record(z.string(), z.unknown()).nullable().default(null),
+	props: z.record(z.string(), z.unknown())
+});
+const previewSchemas = /* @__PURE__ */ new WeakMap();
+/** Whether a preview entry previews nothing: its `props` are empty. */
+function previewShowsNothing(entry) {
+	const props = entry?.props;
+	return !props || Object.keys(props).length === 0;
+}
+/**
+* The props a cell previews with, keyed by the condition they hold under the way a style rule is:
+* `*` for every cell, a condition on the component's own props for some. `when` names those props,
+* so a prop rename moves it and a value rename moves the ref it stores; `props` is keyed by prop
+* too, which `Prop.keyedByNameIn` and `VariantValue.namedValuesIn` reach through `preview/*\/props`.
+* Deleting a prop or a value drops the entries conditioned on it.
+*/
+const Preview = defineSubEntity({
+	name: "preview",
+	label: "Preview",
+	labelPlural: "Previews",
+	key: (entry) => canonicalWhen(entry?.when),
+	vacant: previewShowsNothing,
+	namesMembersOf: { when: "props" },
+	base: previewBase,
+	fields: ({ config, parent }) => {
+		const body = parent;
+		if (!config || !body) return previewBase;
+		return perOwner({
+			cache: previewSchemas,
+			config,
+			owner: body,
+			build: () => {
+				const when = {};
+				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())
+				}, { error: previewShapeError });
+			}
+		});
+	}
+});
+/** Why a slot refuses an element, for a write the config turns away. */
+function slotRefusal({ slot, element }) {
+	const named = isRef(element) ? element.__ref : String(element);
+	return `\`${slot.from}\` takes ${slot.accepts.join(", ")}; \`${named}\` is outside it.`;
+}
 /** What one node renders. The order is the resolution order the build reads a tag by: one of this
 *  Component's layers, then something the config names, then a package export — plus `$state` for an
 *  element the instance chooses (`GLYPHS[name]`), whose legal values are the prop's own domain
@@ -906,7 +1008,7 @@ const stateCondition = z.strictObject({
 	...test,
 	$state: test.$state.startsWith("/") ? test.$state : `/${test.$state}`
 }));
-const orCondition = z.strictObject({ $or: z.array(stateCondition) });
+const orCondition = z.strictObject({ $or: z.array(z.union([stateCondition, z.array(stateCondition)])) });
 /**
 * The flat condition an editor collects — `{ variant: 'solid' }` — compiled to the grammar above.
 *
@@ -948,8 +1050,9 @@ const visibility = z.union([
 	stateCondition,
 	orCondition,
 	z.array(z.union([stateCondition, orCondition])),
+	z.literal(false),
 	flatCondition
-], { error: "a condition is `{ \"$state\": \"<prop>\" }` for a prop that is set, `{ \"$state\": \"<prop>\", \"eq\": \"<value>\" }` for one value of it (`neq`, `gt`, `gte`, `lt`, `lte` and `not: true` also work), `{ \"$or\": [ … ] }` for any of several, or a list of conditions that must all hold" });
+], { error: "a condition is `{ \"$state\": \"<prop>\" }` for a prop that is set, `{ \"$state\": \"<prop>\", \"eq\": \"<value>\" }` for one value of it (`neq`, `gt`, `gte`, `lt`, `lte` and `not: true` also work), `{ \"$or\": [ … ] }` for any of several, a list of conditions that must all hold, or `false` for a position only an interaction shows" });
 /** What an event on a node does to the state model: json-render's own `setState`, its path and the
 *  value to write, which may itself be a choice on the state (`{ $cond, $then, $else }`). */
 const stateAction = z.strictObject({
@@ -1005,7 +1108,7 @@ function nodeComponent(body, element) {
 * Owned by the op rather than by each fill surface, so one gesture stays one patch per node and
 * every caller agrees the fill will actually paint.
 */
-function slotFillHostWrites({ config, path, parent, key, slotProp, node, layers }) {
+function slotFillHostWrites({ config, path, parent, key, slotProp, node, layers, element }) {
 	const host = nodeComponent({ layers }, node?.element ?? layers?.[parent]);
 	if (host && config.resolve("component", host)) {
 		const declared = resolveComponentProps(config, host);
@@ -1020,6 +1123,16 @@ function slotFillHostWrites({ config, path, parent, key, slotProp, node, layers
 	const parentLayer = isRef(parentElement) && kindOf(parentElement.__ref) === "layer" ? pathOf(parentElement.__ref) : parent;
 	const route = slotTargetsOf(config, path).find((t) => t.layer === parentLayer && t.into === slotProp);
 	if (!route) return { slots };
+	const filled = nodeTypeOf(element, layers);
+	const slot = filled !== void 0 ? slotOf({
+		config,
+		path,
+		slot: route.from
+	}) : void 0;
+	if (slot && filled !== void 0 && !slot.takes(filled)) rejectData(slotRefusal({
+		slot,
+		element: filled
+	}), ["slots", slotProp]);
 	return {
 		slots,
 		visible: withoutTruthyTerm({
@@ -1028,6 +1141,14 @@ function slotFillHostWrites({ config, path, parent, key, slotProp, node, layers
 		})
 	};
 }
+/** What a node renders, as a type `Slot.takes` reads: a layer ref through the layer's element. */
+function nodeTypeOf(element, layers) {
+	if (isRef(element) && kindOf(element.__ref) === "layer") {
+		const layer = layers?.[pathOf(element.__ref)];
+		return typeof layer === "string" || isRef(layer) ? layer : void 0;
+	}
+	if (typeof element === "string" || isRef(element)) return element;
+}
 /**
 * The `slots` entries of `node` naming any of `doomed` — each answered with what survives, so a
 * caller writes the filtered list back at the entry's own address (or `null` when nothing does)
@@ -1135,13 +1256,16 @@ const AnatomyNode = defineSubEntity({
 				path: ["text"],
 				message: `\`text\` is a fixed string, and "${node.text}" is one of this component's props. To show the prop's value here, declare it \`{ "type": "forward", "target": "${isRef(element) && kindOf(element.__ref) === "layer" ? pathOf(element.__ref) : "<layer>"}/children" }\` and give this node no \`text\`.`
 			});
+			let placed = element;
+			if (isRef(placed) && kindOf(placed.__ref) === "layer") placed = body.layers?.[pathOf(placed.__ref)];
+			const instanceProps = isRef(placed) && kindOf(placed.__ref) === "component" ? resolveComponentProps(config, pathOf(placed.__ref)) : void 0;
 			for (const [prop, value] of Object.entries(node.props ?? {})) {
 				if (isRef(value) && [
 					"icon",
 					"component",
 					"package",
 					"layer"
-				].includes(kindOf(value.__ref))) {
+				].includes(kindOf(value.__ref)) && !(instanceProps && prop in instanceProps)) {
 					ctx.issues.push({
 						code: "custom",
 						input: value,
@@ -1256,18 +1380,16 @@ const componentFields = z.strictObject({
 	*/
 	forwards: Forward.optional(),
 	styles: StyleRule.optional(),
+	/** The props the render reads that the component neither declares nor forwards — its render
+	*  extras (`.render<{ swatchColor?: string }>()`). Read off the render at build like `anatomy`,
+	*  never authored as data. The module consumes them; a component painted out of its anatomy has
+	*  no module, so the expansion keeps them off the root rather than wearing them as attributes. */
+	renderProps: z.array(z.string()).optional().describe("Props the render reads beyond those declared, read off the source at build. Not authored: declare a prop in `props` instead."),
 	anatomy: AnatomyNode.optional().describe("The tree of what this component renders, keyed by node. Each node names what it renders (a layer, for anything a style rule reaches) and lists its `children`; the node keyed `root` is the top. A one-layer component may omit it."),
 	defaultProps: Style.optional(),
-	/** The state a person chose to show one catalogue tile in. Not anatomy: the capture bakes these
-	*  into the tree by invoking a render with them, so a tile's example icon ends up stored as
-	*  part of the component itself. */
-	previewProps: z.record(z.string(), z.unknown()).optional().describe("The props the catalogue tile and the variant matrix render with. A component whose root takes children renders empty until this or `defaultProps` carries some."),
-	/** Preview props that hold under a condition on the cell — see `preview({ when })`. Like
-	*  `previewProps`, read off `.preview()` at build and never authored as data. */
-	previewWhen: z.array(z.object({
-		when: z.record(z.string(), z.unknown()),
-		props: z.record(z.string(), z.unknown())
-	})).optional().describe("Preview props that hold only when the cell matches `when`, in the grammar a style rule uses: `{ \"when\": { \"type\": \"image\" }, \"props\": { \"src\": \"…\" } }`. A condition on a prop no rule styles makes that prop a preview axis with the value named."),
+	/** What the tile and the matrix render with — see `preview({ defaultProps, when })`. Read off
+	*  `.preview()` at build, and written per cell from the matrix. */
+	preview: Preview.optional().describe(PREVIEW_DESCRIPTION),
 	/**
 	* The source that implements this component — a ref, because the file is an entity the seal owns.
 	*
@@ -1289,17 +1411,43 @@ const componentFields = z.strictObject({
 	export: z.string().optional()
 }).check((ctx) => {
 	const body = ctx.value;
+	if (isPlainObject(body.props)) for (const [name, decl] of Object.entries(body.props)) {
+		const when = decl?.when;
+		if (!isPlainObject(when) || !(name in when)) continue;
+		ctx.issues.push({
+			code: "custom",
+			input: decl,
+			path: [
+				"props",
+				name,
+				"when",
+				name
+			],
+			message: `\`${name}\` conditions on itself. \`when\` names a sibling prop and one of its values.`
+		});
+	}
 	if (body.forwards || body.file || isRef(body.props)) return;
 	const declared = body.props ?? {};
-	for (const field of ["previewProps", "defaultProps"]) {
-		const values = body[field];
+	if (Object.hasOwn(declared, "children") && declared.children !== null) return;
+	const content = [{
+		values: body.defaultProps,
+		path: ["defaultProps", "children"]
+	}, ...Object.entries(storedPreview(body)).map(([key, entry]) => ({
+		values: entry?.props,
+		path: [
+			"preview",
+			key,
+			"props",
+			"children"
+		]
+	}))];
+	for (const { values, path } of content) {
 		if (!isPlainObject(values) || !("children" in values)) continue;
-		if (Object.hasOwn(declared, "children") && declared.children !== null) continue;
 		ctx.issues.push({
 			code: "custom",
 			input: values,
-			path: [field, "children"],
-			message: `\`${field}.children\` has nowhere to land — this component declares no \`children\` prop, so the content is dropped and the component renders empty. Declare \`"children": { "type": "slot", "text": true }\` in \`props\` — or, to land it in a nested layer, \`"children": { "type": "forward", "target": "<layer>/children" }\`.`
+			path,
+			message: `\`${path.join(".")}\` has nowhere to land — this component declares no \`children\` prop, so the content is dropped and the component renders empty. Declare \`"children": { "type": "slot", "text": true }\` in \`props\` — or, to land it in a nested layer, \`"children": { "type": "forward", "target": "<layer>/children" }\`.`
 		});
 	}
 });
@@ -1358,6 +1506,7 @@ const ComponentEntity = defineEntity({
 		props: Prop,
 		forwards: Forward,
 		styles: StyleRule,
+		preview: Preview,
 		anatomy: AnatomyNode,
 		defaultProps: Style
 	},
@@ -1385,7 +1534,7 @@ slots: ({ config, path, member }) => {
 	schemas: {
 		create: {
 			data: componentFields,
-			description: "Create a component at a new qualified `path`. For a component with nothing in it yet, one to design on the canvas before it has props or variants, use `create-blank` with only a `path` instead of authoring a minimal body here. When its complete body is known, include all layers, anatomy, props, defaults, and styles in this one operation. `data.layers` maps each stable layer name to the element it renders and must include `root` — a tag for a primitive (`{ \"layers\": { \"root\": \"div\" } }`), and for anything built on top, a ref to a primitive (`{ \"root\": { \"__ref\": \"component:Box\" }, \"label\": { \"__ref\": \"component:Text\" } }`), which is what lets the layer take that primitive's style props. A primitive exposes style props as `{ \"type\": \"styleProperty\", \"value\": { \"__ref\": \"style-property:bg\" } }` and declares `children: { \"type\": \"slot\", \"text\": true }` when it holds content — without the slot, nothing nested inside it renders. A composed component exposes a layer's props at its own top level through `forwards`, keyed by layer: `{ \"forwards\": { \"root\": \"*\" } }` passes every prop the root's element takes (so `<Button width=\"full\">` reaches the root's `width`), and a list of member refs (`[{ \"__ref\": \"component:Box#props/width\" }]`, each naming the component that declares the prop) passes only those. A prop a layer already exposes is forwarded, never redeclared in `props`; a `props` entry of `{ \"type\": \"forward\" }` is the reverse route, one of this component's props into a layer's. `anatomy` is the tree the build would read off a render: each node renders a layer (`{ \"__ref\": \"layer:<name>\" }`), an intrinsic tag, or `Slot` (`{ \"element\": \"Slot\", \"props\": { \"name\": \"children\" } }`, where a slot prop's content lands — but a declared slot fills `root` by default, so a primitive still declares its `children` slot prop yet needs no `Slot` node or `children` entry for it, and a `Slot` node is only for landing that content in a nested layer); `children` lists sibling node keys from the `root` node, never a prop name; `text` is a fixed string; `visible` is a condition on a prop (`{ \"$state\": \"<prop>\" }`, or with `eq`); content shown in a nested layer is a route, `children: { \"type\": \"forward\", \"target\": \"label/children\" }`. `$state` appears only in `visible` and in an `element` a prop chooses, never as a prop value. A glyph is a node of its own, `{ \"element\": { \"__ref\": \"icon:<library>/<Name>\" } }`, listed in the `children` of the layer node that holds it, never a prop value. Text a prop supplies to a text layer is never a node either: declare the prop `{ \"type\": \"forward\", \"target\": \"<layer>/children\" }` and the layer shows it; a `Slot` node goes only under a layer that takes nodes. A style rule is `\"styles\": { \"*\": { \"when\": null, \"layers\": { \"root\": { \"bg\": \"surface\" } } } }`, keyed by a name, with each layer's bag under `layers`. A composed component carries its own styles: give it an unconditional (`\"*\"`) rule that lays out and surfaces it through the system's style properties — spacing, alignment and gap on the container, a background and color where it has one — rather than leaning on the bare primitives, which paint flat. Style a layer only with the style props the primitive it renders exposes, set to the values those props accept: `component/get` on the primitive lists both, so read it and choose from that rather than reaching for a CSS name or value the system has no style property for. Set `previewProps` (or `defaultProps`) so the component previews with content; a root that takes children renders empty otherwise. A style rule's layer bag is keyed by style-prop name (`fontWeight`, `color`), never by CSS property name, and each value is one of that prop's values.",
+			description: "Create a component at a new qualified `path`. For a component with nothing in it yet, one to design on the canvas before it has props or variants, use `create-blank` with only a `path` instead of authoring a minimal body here. When its complete body is known, include all layers, anatomy, props, defaults, and styles in this one operation. `data.layers` maps each stable layer name to the element it renders and must include `root` — a tag for a primitive (`{ \"layers\": { \"root\": \"div\" } }`), and for anything built on top, a ref to a primitive (`{ \"root\": { \"__ref\": \"component:Box\" }, \"label\": { \"__ref\": \"component:Text\" } }`), which is what lets the layer take that primitive's style props. A primitive exposes style props as `{ \"type\": \"styleProperty\", \"value\": { \"__ref\": \"style-property:bg\" } }` and declares `children: { \"type\": \"slot\", \"text\": true }` when it holds content — without the slot, nothing nested inside it renders. A composed component exposes a layer's props at its own top level through `forwards`, keyed by layer: `{ \"forwards\": { \"root\": \"*\" } }` passes every prop the root's element takes (so `<Button width=\"full\">` reaches the root's `width`), and a list of member refs (`[{ \"__ref\": \"component:Box#props/width\" }]`, each naming the component that declares the prop) passes only those. A prop a layer already exposes is forwarded, never redeclared in `props`; a `props` entry of `{ \"type\": \"forward\" }` is the reverse route, one of this component's props into a layer's. `anatomy` is the tree the build would read off a render: each node renders a layer (`{ \"__ref\": \"layer:<name>\" }`), an intrinsic tag, or `Slot` (`{ \"element\": \"Slot\", \"props\": { \"name\": \"children\" } }`, where a slot prop's content lands — but a declared slot fills `root` by default, so a primitive still declares its `children` slot prop yet needs no `Slot` node or `children` entry for it, and a `Slot` node is only for landing that content in a nested layer); `children` lists sibling node keys from the `root` node, never a prop name; `text` is a fixed string; `visible` is a condition on a prop (`{ \"$state\": \"<prop>\" }`, or with `eq`); content shown in a nested layer is a route, `children: { \"type\": \"forward\", \"target\": \"label/children\" }`. `$state` appears only in `visible` and in an `element` a prop chooses, never as a prop value. A glyph is a node of its own, `{ \"element\": { \"__ref\": \"icon:<library>/<Name>\" } }`, listed in the `children` of the layer node that holds it, never a prop value. Text a prop supplies to a text layer is never a node either: declare the prop `{ \"type\": \"forward\", \"target\": \"<layer>/children\" }` and the layer shows it; a `Slot` node goes only under a layer that takes nodes. A style rule is `\"styles\": { \"*\": { \"when\": null, \"layers\": { \"root\": { \"bg\": \"surface\" } } } }`, keyed by a name, with each layer's bag under `layers`. A composed component carries its own styles: give it an unconditional (`\"*\"`) rule that lays out and surfaces it through the system's style properties — spacing, alignment and gap on the container, a background and color where it has one — rather than leaning on the bare primitives, which paint flat. Style a layer only with the style props the primitive it renders exposes, set to the values those props accept: `component/get` on the primitive lists both, so read it and choose from that rather than reaching for a CSS name or value the system has no style property for. Set `preview` (`{ \"*\": { \"when\": null, \"props\": { \"children\": \"Example\" } } }`) or `defaultProps` so the component previews with content; a root that takes children renders empty otherwise. A style rule's layer bag is keyed by style-prop name (`fontWeight`, `color`), never by CSS property name, and each value is one of that prop's values.",
 			example: ({ config }) => {
 				const path = freeExamplePath(config);
 				const composed = composedCreateExample(config, path);
@@ -1421,7 +1570,10 @@ slots: ({ config, path, member }) => {
 								children: ["icon", "content"]
 							}
 						},
-						previewProps: { children: "Example" }
+						preview: { ["*"]: {
+							when: null,
+							props: { children: "Example" }
+						} }
 					}
 				};
 			}
@@ -1625,7 +1777,8 @@ slots: ({ config, path, member }) => {
 					key,
 					slotProp,
 					node: body?.anatomy?.[parent],
-					layers: body?.layers
+					layers: body?.layers,
+					element
 				}) : void 0;
 				return next.apply({
 					kind: "component",
@@ -1922,9 +2075,27 @@ function componentRef(path) {
 	});
 	return value;
 }
-/** Component keeps the generic entity surface; only its ref authoring result knows about the
-* source-only `.render()` step. */
-const Component = Object.assign(ComponentEntity, { ref: componentRef });
+/**
+* Component keeps the generic entity surface, plus the questions only a component answers: its
+* slots (`Slot`, in `spec/slot`), what one of its matrix cells shows (`Cell`, in `spec/cell`) and
+* what a design file put in a placed instance's slots (`Instance`, in `spec/instance`).
+* Only its ref authoring result knows about the source-only `.render()` step.
+*/
+const Component = Object.assign(ComponentEntity, {
+	ref: componentRef,
+	/** Every slot content can be placed in, with what each takes. */
+	slots: listSlots,
+	/** One slot by the prop it arrives as. */
+	slot: slotOf,
+	/** The slot whose content lands in a layer. */
+	slotHostedBy,
+	/** The named node slots alone, without a positioned `children`. */
+	namedSlots,
+	/** The component under one coordinate of its matrix. */
+	cell: cellAt,
+	/** The component a design file's spec element places, with what the file put in its slots. */
+	instance: instanceAt
+});
 /** A valid example prop bag — the first variant prop's first value, else empty. Lives here because
 *  it reads a component's stored props; the generic example filler only knows address fields.
 *  Resolved through the domain (not `ownValues`): a variant that delegates its values to a group

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

@@ -1,7 +1,7 @@
 import { Ref } from "../../framework/utils/refs.js";
 import { SubEntityClass } from "../../framework/defineSubEntity.js";
-import { EntityClass } from "../../framework/defineEntity.js";
 import { ComputedInput } from "../../framework/registry.js";
+import { EntityClass } from "../../framework/defineEntity.js";
 import { z } from "zod";
 
 //#region src/entities/system/File.d.ts

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

@@ -1,11 +1,11 @@
 import { CopyPlan } from "./copy-plan.js";
-import { RegisteredEntities } from "../../framework/registered.js";
 import { SourceResolver, SourceState } from "../../framework/sources.js";
+import { ComputedInput } from "../../framework/registry.js";
+import { RegisteredEntities } from "../../framework/registered.js";
 import { EntityClass, ItemOf } from "../../framework/defineEntity.js";
 import { PartialBodyOf } from "../../framework/defineConfig.js";
 import { BreakPlan, LinkPlan, SourceRowState, UnlinkPlan } from "./link-plan.js";
 import { Config } from "../../framework/Config.js";
-import { ComputedInput } from "../../framework/registry.js";
 import { z } from "zod";
 
 //#region src/entities/system/LinkedSystem.d.ts

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

@@ -1,6 +1,6 @@
+import { ComputedInput } from "../../framework/registry.js";
 import { DerivedEntityClass } from "../../framework/defineDerivedEntity.js";
 import { Config } from "../../framework/Config.js";
-import { ComputedInput } from "../../framework/registry.js";
 import { z } from "zod";
 
 //#region src/entities/system/Operation.d.ts

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

@@ -25,6 +25,14 @@ declare const STYLE_PROP_VALUE_FORMS: {
   }?: StylePropValueCtx) => z.ZodObject<{
     __ref: z.ZodString;
   }, z.core.$strip>;
+  readonly tokenGroupPrefixed: ({
+    config
+  }?: StylePropValueCtx) => z.ZodObject<{
+    value: z.ZodObject<{
+      __ref: z.ZodString;
+    }, z.core.$strip>;
+    prefix: z.ZodString;
+  }, z.core.$strict>;
   readonly flag: (_ctx?: StylePropValueCtx) => z.ZodObject<{
     alias: z.ZodBoolean;
     value: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{

package/dist/entities/system/StyleProperty.js

@@ -71,7 +71,7 @@ const namesItem = (config, wanted) => (ctx) => {
 * of one string too, so `aliasToken` comes before `aliasDeclarations`; a boolean alias is a flag
 * whatever its value holds, so `flag` comes before the named aliases. `token` and `tokenGroup` are
 * one stored shape; with a config each refuses what the other admits, and without one a ref reads
-* as `token`.
+* as `token`. A prefixed group is a group ref beside the prefix its leaves carry.
 */
 /** A declaration bag's key. A ref is a record of one string too, so the ref marker is not a key here,
 *  or a ref no ref form admits would read as a bag. */
@@ -93,6 +93,13 @@ const STYLE_PROP_VALUE_FORMS = {
 		title: "Token group",
 		description: "A ref to a token group, which offers every token in it and follows the group as it changes."
 	}).check(namesItem(config, false)),
+	tokenGroupPrefixed: ({ config } = {}) => z.strictObject({
+		value: refSchema.check(namesItem(config, false)),
+		prefix: z.string().min(1)
+	}).meta({
+		title: "Prefixed token group",
+		description: "A ref to a token group whose every token is offered under `<prefix>/<name>`, so a group bound beside others reads as its own: `{ value: <ref to canvas>, prefix: \"canvas\" }` offers `canvas/slot`."
+	}),
 	flag: (_ctx = {}) => z.strictObject({
 		alias: z.boolean(),
 		value: z.union([
@@ -159,6 +166,10 @@ const STYLE_PROP_VALUE_LEAVES = {
 		leaf,
 		value: path
 	})),
+	tokenGroupPrefixed: (entry, members) => members(entry.value).map(({ leaf, path }) => ({
+		leaf: `${entry.prefix}/${leaf}`,
+		value: path
+	})),
 	flag: (entry, members) => entry.alias ? flagValue(entry.value, members).map((rest) => ({
 		leaf: "",
 		...rest

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

@@ -1,6 +1,6 @@
+import { ComputedInput } from "../../framework/registry.js";
 import { DerivedEntityClass } from "../../framework/defineDerivedEntity.js";
 import { Config } from "../../framework/Config.js";
-import { ComputedInput } from "../../framework/registry.js";
 import { z } from "zod";
 
 //#region src/entities/system/Tool.d.ts