@yahoo/uds-create-config 4.5.2 → 4.7.0

package/dist/framework/render-spec.js

@@ -1,7 +1,9 @@
-import { kindOf, memberOf, pathOf, ref, splitRef } from "./utils/refs.js";
+import { isRef, kindOf, memberOf, pathOf, ref, splitRef } from "./utils/refs.js";
+import { renderedElement } from "../entities/system/element.js";
 import { createSliceMemo } from "./memo.js";
-import { authoredBag, memberFromLeaf, resolveComponentProps } from "./projections.js";
-import { intoName, routesContent } from "./prop-surface.js";
+import { unconditionalPreviewProps } from "./preview-store.js";
+import { authoredBag, authoredValue, declaredPropDefaults, memberFromLeaf, resolveComponentProps, stylePropertyPathFor } from "./projections.js";
+import { forwardedLayers, intoName, routesContent } from "./prop-surface.js";
 import { graftPreviewElements } from "../spec/preview-elements.js";
 import { componentLayerClass, componentPropClasses, componentRuleClasses, layerRoutedProps, splitStyleProps, styleRuleMotionClasses } from "./class-names.js";
 //#region src/framework/render-spec.ts
@@ -181,6 +183,27 @@ function authoredProps(config, props) {
 * and that was always stated rather than run.
 */
 function deriveSpec(config, path) {
+	const projected = componentSpec(config, path);
+	return projected.kind === "composition" ? projected.spec : void 0;
+}
+/**
+* Per slice, the projected spec of each component asked for so far. The matrix, the layers rail and
+* the designer panel each ask per cell or per row, and a projection walks the anatomy and reads every
+* node prop's leaf back, so one answer serves them all until the config they read from changes.
+*
+* Keyed on the kinds a projection reads: the component's body, and the style properties and the
+* token and composite members its node props' refs are read back through.
+*/
+const componentSpecCache = createSliceMemo({
+	kinds: [
+		"component",
+		"style-property",
+		"token",
+		"composite"
+	],
+	compute: (_config) => /* @__PURE__ */ new Map()
+});
+function projectSpec(config, path) {
 	const body = bodyOf(config, path) ?? {};
 	const layers = body.layers ?? {};
 	const anatomy = body.anatomy;
@@ -210,11 +233,13 @@ function deriveSpec(config, path) {
 		const props = {
 			...authoredProps(config, node.props),
 			...node.text !== void 0 ? { children: node.text } : {},
+			...layer === void 0 ? { [ANATOMY_MARKER]: key } : {},
 			...layer !== void 0 ? {
 				"data-uds-layer": layer,
 				"data-uds-component": path
 			} : {}
 		};
+		markReadOnlyField(config, type, props);
 		const children = node.children?.length ? [...node.children] : void 0;
 		elements[key] = {
 			type,
@@ -291,7 +316,15 @@ function instanceSpec(path, props = {}) {
 * surface reads `kind` to decide whether to offer composition tools, and `reason` to explain why not.
 */
 function componentSpec(config, path) {
-	const derived = deriveSpec(config, path);
+	const cache = componentSpecCache(config);
+	const hit = cache.get(path);
+	if (hit) return hit;
+	const built = buildComponentSpec(config, path);
+	cache.set(path, built);
+	return built;
+}
+function buildComponentSpec(config, path) {
+	const derived = projectSpec(config, path);
 	if (derived) return {
 		spec: derived,
 		kind: "composition"
@@ -334,7 +367,7 @@ function componentSpec(config, path) {
 function previewSpec(config, path) {
 	const body = bodyOf(config, path);
 	if (!body) return void 0;
-	const values = body.previewProps ?? {};
+	const values = unconditionalPreviewProps(body) ?? {};
 	return graftPreviewElements(instanceSpec(path, values), values);
 }
 /** A key no emitted element is using yet. Anatomy keys are namespaced under the instance they belong
@@ -439,6 +472,63 @@ function readStatePointer(state, pointer) {
 function statePointerProp(pointer) {
 	return pointer.replace(/^\//, "").split("/")[0] ?? "";
 }
+/**
+* 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.
+*/
+const ANATOMY_MARKER = "data-uds-anatomy";
+/** The string or number prop `node` binds into `into` (`{ $state: '/<prop>' }`), when it does. */
+function boundValueProp({ config, path, node, into }) {
+	const pointer = (node.props?.[into])?.$state;
+	if (typeof pointer !== "string") return void 0;
+	const prop = statePointerProp(pointer);
+	const decl = resolveComponentProps(config, path)[prop];
+	return decl?.type === "string" || decl?.type === "number" ? prop : void 0;
+}
+/**
+* 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.
+*/
+function layerTextProp({ config, path, layer }) {
+	const body = bodyOf(config, path);
+	if (!body) return void 0;
+	for (const node of Object.values(body.anatomy ?? {})) {
+		if (layerOf(node.element) !== layer) continue;
+		const prop = boundValueProp({
+			config,
+			path,
+			node,
+			into: "children"
+		});
+		if (prop) return prop;
+	}
+}
+/**
+* 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`).
+*/
+function anatomyTextProp({ config, path, element, into }) {
+	const node = bodyOf(config, path)?.anatomy?.[element];
+	if (!node) return void 0;
+	return boundValueProp({
+		config,
+		path,
+		node,
+		into
+	});
+}
+/** The component an inline anatomy element renders, when it is one (`component:<path>`). */
+function anatomyElementComponent({ config, path, element }) {
+	const target = refOf(bodyOf(config, path)?.anatomy?.[element]?.element);
+	if (target === void 0) return void 0;
+	const { kind, qualifiedPath } = splitRef(target);
+	return kind === "component" ? qualifiedPath : void 0;
+}
 /** 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. */
 function resolveVisibility(condition, state) {
@@ -593,18 +683,28 @@ function collectTerms({ condition, junction, group, sink }) {
 * spellings are the same test.
 */
 function withoutTruthyTerm({ condition, prop }) {
-	if (spentBy({
-		condition,
-		prop
-	})) return null;
-	if (!Array.isArray(condition)) return void 0;
-	const kept = condition.filter((entry) => !spentBy({
+	const list = andListOf(condition);
+	const kept = list.filter((entry) => !spentBy({
 		condition: entry,
 		prop
 	}));
-	if (kept.length === condition.length) return void 0;
-	if (kept.length === 0) return null;
-	return kept.length === 1 ? kept[0] : kept;
+	if (kept.length === list.length) return void 0;
+	return spelled(kept);
+}
+/** A condition as the and-list it is: a bare clause is a list of one, nothing (or a projection's
+*  baked `true`) is empty. `false` is a position nothing at rest shows, which no clause can add to
+*  or take from, so it reads as a list holding itself. */
+function andListOf(condition) {
+	if (condition === void 0 || condition === true) return [];
+	if (Array.isArray(condition)) return [...condition];
+	return [condition];
+}
+/** The stored spelling of an and-list: nothing clears the field, one clause is bare, several stay
+*  the list. */
+function spelled(list) {
+	if (list.length === 0) return null;
+	if (list.length === 1) return list[0];
+	return list;
 }
 /** Whether a single term of an and-list is one `prop` being present makes true: the bare test, an
 *  `eq: true` test (content is never the boolean `true`, so presence is the only reading that can
@@ -672,9 +772,31 @@ function computeConsumedProps(config, path, body) {
 	const consumed = new Set(["className", "layerProps"]);
 	const declared = body.props ?? {};
 	for (const [name, decl] of Object.entries(declared)) if (decl && decl.type !== "styleProperty") consumed.add(name);
+	for (const name of body.renderProps ?? []) consumed.add(name);
 	for (const rule of componentRuleClasses(config, path)) for (const prop of Object.keys(rule.when)) if (declared[prop]) consumed.add(prop);
 	return consumed;
 }
+/** The elements React treats as controlled once given a `value`. HTML's list, not the config's. */
+const FORM_FIELDS = new Set([
+	"input",
+	"textarea",
+	"select"
+]);
+/**
+* A projected field has no handler: the render's `onChange` does not survive into the anatomy, so a
+* controlled `value` is read-only here, and the element says so, which is what React requires of a
+* value it cannot change. The element counts as a field when it renders as one of
+* {@link FORM_FIELDS}, through a component or as the tag.
+*/
+function markReadOnlyField(config, type, props) {
+	if (props.value === void 0 || props.readOnly !== void 0) return;
+	const tag = kindOf(type) === "component" ? renderedElement(config, pathOf(type)) : type;
+	if (FORM_FIELDS.has(tag)) props.readOnly = true;
+}
+/** A slot value that is text rather than elements. */
+function isText(value) {
+	return typeof value === "string" || typeof value === "number";
+}
 /** The prop JSX children arrive on — json-render's content channel, and the same name
 *  `childrenPolicy` reads to answer whether a component accepts any. Not a system-defined name: a
 *  design system names its components and tokens, and this one names the channel. */
@@ -731,8 +853,9 @@ function computeSlotTargets(config, body) {
 * 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.
 */
 function slotTargetsOf(config, path) {
 	const body = bodyOf(config, path);
@@ -743,11 +866,85 @@ function slotTargetsOf(config, path) {
 		layer,
 		from: decl.from,
 		into: intoName(decl.into)
-	})), ...root ? untargeted.map((decl) => ({
-		layer: root,
-		from: decl.from,
-		into: intoName(decl.into)
-	})) : []];
+	})), ...untargeted.flatMap((decl) => {
+		const layer = slotHostLayer(body.anatomy, decl.from) ?? root;
+		return layer ? [{
+			layer,
+			from: decl.from,
+			into: intoName(decl.into)
+		}] : [];
+	})];
+}
+/**
+* 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
+* prop, or the node hangs under no layer.
+*/
+function slotHostLayer(anatomy, from) {
+	if (!anatomy) return void 0;
+	const parents = /* @__PURE__ */ new Map();
+	for (const [key, node] of Object.entries(anatomy)) for (const child of heldKeys(node)) parents.set(child, key);
+	let key = Object.keys(anatomy).find((candidate) => slotAnatomyPropOf(anatomy[candidate]) === from);
+	const seen = /* @__PURE__ */ new Set();
+	while (key !== void 0 && !seen.has(key)) {
+		seen.add(key);
+		const layer = layerOf(anatomy[key]?.element);
+		if (layer !== void 0) return layer;
+		key = parents.get(key);
+	}
+}
+/**
+* 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.
+*/
+function valueForwardsOf(config, path) {
+	const body = bodyOf(config, path);
+	return body ? valueForwards(config, body) : [];
+}
+/**
+* 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.
+*/
+function propInto({ config, path, layer, into }) {
+	return [...slotTargetsOf(config, path), ...valueForwardsOf(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);
+}
+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 name of forwardedLayers(config, path).get(layer) ?? []) names.add(name);
+	return [...names];
+}
+function valueForwards(config, body) {
+	const routes = [];
+	for (const [from, decl] of Object.entries(body.props ?? {})) {
+		if (decl?.type !== "forward") continue;
+		if (routesContent(config, body.layers, decl)) continue;
+		const target = refOf(decl.target);
+		if (!target) continue;
+		routes.push({
+			layer: pathOf(target),
+			from,
+			into: intoName(decl.into)
+		});
+	}
+	return routes;
 }
 /** The className a layer wears for one instance: its own class, every style rule whose condition
 *  holds, and — on the root only — what the call site passed. */
@@ -779,12 +976,53 @@ function place(sink, type, props, children, hint, slots) {
 	const key = freeKey(sink, hint);
 	sink.elements[key] = {
 		type: tag,
-		props: own,
+		props: moduleProps(sink.config, tag, own),
 		...children.length ? { children: [...children] } : {},
 		...slots && Object.keys(slots).length ? { slots } : {}
 	};
 	return key;
 }
+/**
+* An element's props as the component behind it reads them.
+*
+* A style prop's token arrives as the stored ref when an instance's defaults come from the config
+* (`bg` as `token:bg/primary`). The expansion reads such a ref through the prop's domain and paints
+* the class; a compiled module reads a value string and paints nothing for an object. So an element
+* left to its registry entry gets the same leaf the expansion would have named, resolved through
+* the component's own prop routing (`gap` on a `VStack` writes `gapY`). A modifier block nests a bag
+* of the same shape. Only a token ref on a key that writes a style property is touched: a component
+* ref handed as a prop value stays the ref it is.
+*/
+function moduleProps(config, type, props) {
+	const through = type.includes(":") && kindOf(type) === "component" ? [pathOf(type)] : [];
+	const modifiers = new Set(config.list("modifier").map((modifier) => `_${modifier.leaf}`));
+	const walk = (bag) => {
+		let changed = false;
+		const out = {};
+		for (const [key, value] of Object.entries(bag)) {
+			if (modifiers.has(key) && value && typeof value === "object" && !Array.isArray(value) && !isRef(value)) {
+				const inner = walk(value);
+				out[key] = inner;
+				changed ||= inner !== value;
+				continue;
+			}
+			if (isRef(value) && kindOf(value.__ref) === "token") {
+				const property = stylePropertyPathFor({
+					config,
+					through,
+					key
+				});
+				const leaf = property === void 0 ? value : authoredValue(config, property, value);
+				out[key] = leaf;
+				changed ||= leaf !== value;
+				continue;
+			}
+			out[key] = value;
+		}
+		return changed ? out : bag;
+	};
+	return walk(props);
+}
 /** Whether any node under `key` (itself excluded) binds `prop` as its content. */
 function subtreeBinds(anatomy, key, prop) {
 	const seen = /* @__PURE__ */ new Set();
@@ -812,10 +1050,13 @@ function expandInstance(sink, path, instanceProps, content, hint, instanceSlots)
 	const { config } = sink;
 	const body = bodyOf(config, path) ?? {};
 	const layers = body.layers ?? {};
-	const anatomy = body.anatomy && Object.keys(body.anatomy).length > 0 ? body.anatomy : { root: { element: { __ref: `layer:${rootKeyOf(layers)}` } } };
+	const stored = body.anatomy && Object.keys(body.anatomy).length > 0;
+	const anatomy = stored ? body.anatomy : { root: { element: { __ref: `layer:${rootKeyOf(layers)}` } } };
 	const filled = {};
 	for (const [from, fills] of Object.entries(instanceSlots ?? {})) if (fills.length > 0 && instanceProps[from] === void 0) filled[from] = true;
+	const declaredDefaults = declaredPropDefaults(body.props);
 	const state = {
+		...declaredDefaults,
 		...body.defaultProps,
 		...filled,
 		...instanceProps
@@ -823,19 +1064,13 @@ function expandInstance(sink, path, instanceProps, content, hint, instanceSlots)
 	const consumed = consumedProps(config, path, body);
 	const { byLayer: targets } = slotTargets(config, path, body);
 	const valueRoutes = /* @__PURE__ */ new Map();
-	for (const [from, decl] of Object.entries(body.props ?? {})) {
-		if (decl?.type !== "forward") continue;
-		if (routesContent(config, layers, decl)) continue;
-		const target = refOf(decl.target);
-		if (!target) continue;
-		const routes = valueRoutes.get(pathOf(target)) ?? [];
-		routes.push({
-			from,
-			into: intoName(decl.into)
-		});
-		valueRoutes.set(pathOf(target), routes);
+	for (const route of valueForwards(config, body)) {
+		const routes = valueRoutes.get(route.layer) ?? [];
+		routes.push(route);
+		valueRoutes.set(route.layer, routes);
 	}
 	const supplied = {
+		...declaredDefaults,
 		...body.defaultProps ?? {},
 		...instanceProps
 	};
@@ -887,6 +1122,7 @@ function expandInstance(sink, path, instanceProps, content, hint, instanceSlots)
 		const layer = layerOf(node.element);
 		const isRoot = key === hostNode;
 		let type = typeOf(layers, node.element);
+		if (!stored && isRoot && type !== void 0 && kindOf(type) === "component") type = renderedElement(config, path);
 		const bound = boundPropOf(node.element);
 		if (bound) type = boundChoice(config, path, node.element, state[bound]);
 		type = wrappedTypeOf(node, type);
@@ -904,7 +1140,7 @@ function expandInstance(sink, path, instanceProps, content, hint, instanceSlots)
 			return key;
 		}
 		const slot = layer ? targets.get(layer) : void 0;
-		const slotValue = slot && !subtreeBinds(anatomy, key, slot.from) ? instanceProps[slot.from] : void 0;
+		const slotValue = slot && !subtreeBinds(anatomy, key, slot.from) && !(positioned.has(slot.from) && isText(instanceProps[slot.from])) ? instanceProps[slot.from] : void 0;
 		const props = layer ? {
 			...authoredProps(config, node.props),
 			"data-uds-component": path,
@@ -919,12 +1155,16 @@ function expandInstance(sink, path, instanceProps, content, hint, instanceSlots)
 				isRoot ? instanceProps.className : void 0,
 				layerProps[layer]?.className
 			]) || void 0
-		} : authoredProps(config, node.props);
+		} : {
+			...authoredProps(config, node.props),
+			[ANATOMY_MARKER]: key
+		};
 		if (node.text !== void 0) props.children = node.text;
 		for (const [name, value] of Object.entries(props)) {
 			const settled = resolveChosenValue(value, state);
 			if (settled !== value) props[name] = settled;
 		}
+		markReadOnlyField(config, type, props);
 		const children = [];
 		const boundFills = {};
 		for (const [name, value] of Object.entries(props)) {
@@ -935,9 +1175,16 @@ function expandInstance(sink, path, instanceProps, content, hint, instanceSlots)
 			if (name === "children") children.push(...fills);
 			else boundFills[name] = [...fills];
 		}
+		let positionedText;
 		for (const child of node.children ?? []) {
 			const childSlot = slotAnatomyPropOf(anatomy[child]);
 			if (childSlot !== void 0) {
+				if (resolveVisibility(anatomy[child]?.visible, state) === false) continue;
+				const given = state[childSlot];
+				if (isText(given)) {
+					positionedText = String(given);
+					contentPlaced = contentPlaced || childSlot === untargetedSlot;
+				}
 				if (childSlot === untargetedSlot) {
 					const fills = instanceSlots?.[childSlot] ?? [];
 					if (allContent.length > 0 || fills.length > 0) {
@@ -951,6 +1198,7 @@ function expandInstance(sink, path, instanceProps, content, hint, instanceSlots)
 			if (placed) children.push(placed);
 		}
 		if (isRoot && allContent.length > 0 && !contentPlaced) children.push(...allContent);
+		if (positionedText !== void 0 && props.children === void 0) props.children = positionedText;
 		const slots = { ...boundFills };
 		const routed = slot ? instanceSlots?.[slot.from] : void 0;
 		const overridden = routed?.length && slot && !slot.untargeted ? intoName(slot.into) : void 0;
@@ -1041,4 +1289,4 @@ function expandComponent(config, path, props = {}, options = {}) {
 	return expandSpec(config, instanceSpec(path, props), options);
 }
 //#endregion
-export { boundElementType, componentSpec, deriveSpec, entryKeyOf, expandComponent, expandSpec, instanceSpec, liveStateProps, previewSpec, readStatePointer, resolveVisibility, slotAnatomyPropOf, slotTargetsOf, specWithResolvedVisibility, statePointerProp, visibilityStateProps, visibilityTerms, withoutTruthyTerm, wrappedElementKey };
+export { ANATOMY_MARKER, anatomyElementComponent, anatomyTextProp, andListOf, boundElementType, componentSpec, deriveSpec, entryKeyOf, expandComponent, expandSpec, instanceSpec, layerTextProp, liveStateProps, previewSpec, propInto, propsIntoLayer, readStatePointer, resolveVisibility, routeOf, slotAnatomyPropOf, slotTargetsOf, specWithResolvedVisibility, spelled, statePointerProp, valueForwardsOf, visibilityStateProps, visibilityTerms, withoutTruthyTerm, wrappedElementKey };

package/dist/framework/schema-version.d.ts

@@ -15,7 +15,7 @@ import { Patch, SerializedConfig } from "./Config.js";
  * sets this constant to its own older timestamp; the merge ref then carries a registered migration
  * newer than the constant, and the assertion fails until the author re-mints.
  */
-declare const CURRENT_SCHEMA_VERSION = 20260918161049;
+declare const CURRENT_SCHEMA_VERSION = 20260920161309;
 /** What the walkers need to see of an envelope — loose on purpose, so a typed `SerializedConfig`
  *  and a raw old-shape record both flow in without casts. */
 interface VersionStamped {

package/dist/framework/schema-version.js

@@ -13,7 +13,7 @@ import { ConfigFormatError } from "./rejection.js";
 * sets this constant to its own older timestamp; the merge ref then carries a registered migration
 * newer than the constant, and the assertion fails until the author re-mints.
 */
-const CURRENT_SCHEMA_VERSION = 20260918161049;
+const CURRENT_SCHEMA_VERSION = 20260920161309;
 /** The mint that moved `options` into the `settings` kind — restated here, rather than imported
 *  from the migration that owns it, because that migration imports this module. */
 const SETTINGS_AS_KIND_VERSION = 20260908171448;
@@ -45,7 +45,7 @@ function registerSchemaMigrations(...migrations) {
 	for (const migration of migrations) {
 		if (migration.version !== 1 && !isMintTimestamp(migration.version)) throw new Error(`Schema migration version ${migration.version} is not a mint timestamp — mint one with \`date +%Y%m%d%H%M%S\`, like a supabase migration.`);
 		if (REGISTERED.has(migration.version)) throw new Error(`A schema migration at version ${migration.version} is already registered.`);
-		if (migration.version > 20260918161049) throw new Error(`Schema migration ${migration.version} is newer than CURRENT_SCHEMA_VERSION (${CURRENT_SCHEMA_VERSION}) — a stale branch merged, or the mint forgot to bump the constant. Re-mint: set CURRENT_SCHEMA_VERSION to the newest migration version.`);
+		if (migration.version > 20260920161309) throw new Error(`Schema migration ${migration.version} is newer than CURRENT_SCHEMA_VERSION (${CURRENT_SCHEMA_VERSION}) — a stale branch merged, or the mint forgot to bump the constant. Re-mint: set CURRENT_SCHEMA_VERSION to the newest migration version.`);
 		REGISTERED.set(migration.version, migration);
 	}
 }
@@ -102,7 +102,7 @@ function pendingFor(version, target, options) {
 * Already-current input passes through untouched — same reference, so hot paths pay nothing.
 */
 function upgradeSerializedConfig(json, options) {
-	const target = options?.target ?? 20260918161049;
+	const target = options?.target ?? 20260920161309;
 	const version = detectedWireVersion(json);
 	if (version > target) throw new SchemaVersionTooNew(version, target);
 	const raw = json;
@@ -160,7 +160,7 @@ function upgradedSources(json, options) {
 * meaning under the current schema and replay skips it — reported by the caller, not swallowed here.
 */
 function upgradePatch(patch, writtenAt, options) {
-	const target = options?.target ?? 20260918161049;
+	const target = options?.target ?? 20260920161309;
 	if (writtenAt > target) throw new SchemaVersionTooNew(writtenAt, target);
 	let current = patch;
 	for (const migration of pendingFor(writtenAt, target, options)) {
@@ -179,7 +179,7 @@ function upgradePatch(patch, writtenAt, options) {
 * stamp would cause.
 */
 function upgradeDraftEntries(draft, options) {
-	const target = options?.target ?? 20260918161049;
+	const target = options?.target ?? 20260920161309;
 	const entries = [];
 	const held = [];
 	const retired = [];

package/dist/framework/source-integrity.d.ts

@@ -162,6 +162,19 @@ declare function overlayVerb(overlay: LocalOverlay, field: LeafAddress): Overlay
  * have to call it one or the other.
  */
 declare function misdeclaredOverlays(config: Config): MisdeclaredOverlay[];
+/**
+ * Split a merged body into `override`/`extend` by judging each leaf against the source — the forward
+ * direction of the walk {@link misdeclaredOverlays} runs to check one. A leaf the source defines
+ * differently is an override; one it lacks is an extension; one it spells the same is neither, and is
+ * left out.
+ *
+ * What a directive written this way can never do is trip the check that classified it: every leaf
+ * lands on the side the live source agrees it belongs on, by construction.
+ */
+declare function classifyOverlay(local: Record<string, unknown>, theirs: unknown): {
+  override?: Record<string, unknown>;
+  extend?: Record<string, unknown>;
+};
 /** A directive aimed at a path whose kind the pin never adopted. */
 interface UnadoptedDirective {
   slug: string;
@@ -223,4 +236,4 @@ interface UnstatableCondition {
  */
 declare function unstatableConditions(config: Config): UnstatableCondition[];
 //#endregion
-export { DanglingDirective, DanglingRef, LeafAddress, MisdeclaredOverlay, OverlayVerb, RedundantQualifier, UnadoptedDirective, UnreadableBorrow, UnstatableCondition, danglingDirectives, danglingSourcedRefs, leafAddresses, leafVerb, misdeclaredOverlays, overlayVerb, redundantQualifiers, unadoptedDirectives, unreadableBorrows, unstatableConditions, valueAt };
+export { DanglingDirective, DanglingRef, LeafAddress, MisdeclaredOverlay, OverlayVerb, RedundantQualifier, UnadoptedDirective, UnreadableBorrow, UnstatableCondition, classifyOverlay, danglingDirectives, danglingSourcedRefs, leafAddresses, leafVerb, misdeclaredOverlays, overlayVerb, redundantQualifiers, unadoptedDirectives, unreadableBorrows, unstatableConditions, valueAt };

package/dist/framework/utils/refs.js

@@ -399,5 +399,14 @@ function rewriteRefSource(value, from, to) {
 	}
 	return value;
 }
+/**
+* A condition's identity: its entries sorted by prop, each value read to its leaf, so a bare name
+* and the ref it is stored as spell the same key. `*` for no condition. A style rule and a preview
+* condition are both keyed by this.
+*/
+function canonicalCondition(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("&");
+}
 //#endregion
-export { ENTITY_PATH_MESSAGE, MINTED, collectRefs, entityRefOf, isEntityPath, isExtendedRef, isMintedRow, isRef, kindOf, memberOf, memberRef, orRef, pathOf, qualifyRefs, ref, refLeaf, refSchema, rewriteRefNamespace, rewriteRefSource, rewriteRefs, singletonRef, sourceOf, splitRef };
+export { ENTITY_PATH_MESSAGE, MINTED, canonicalCondition, collectRefs, entityRefOf, isEntityPath, isExtendedRef, isMintedRow, isRef, kindOf, memberOf, memberRef, orRef, pathOf, qualifyRefs, ref, refLeaf, refSchema, rewriteRefNamespace, rewriteRefSource, rewriteRefs, singletonRef, sourceOf, splitRef };

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

@@ -18,6 +18,8 @@ interface SpecNode {
   readonly type: string;
   readonly props?: Record<string, unknown>;
   readonly children?: readonly SpecNode[];
+  /** Named slot fills, each a list of nodes under the slot prop they fill. */
+  readonly slots?: Readonly<Record<string, readonly SpecNode[]>>;
   readonly text?: string;
 }
 /** Validate a design-file spec against the config — every node's `type` a real component and its

package/dist/framework/validate-spec.js

@@ -1,6 +1,7 @@
 import { kindOf, memberOf, pathOf, splitRef } from "./utils/refs.js";
 import { childrenPolicy } from "../entities/system/element.js";
 import { resolveComponentProps } from "./projections.js";
+import { slotOf } from "../spec/slot.js";
 import { refResolves } from "./ref-integrity.js";
 //#region src/framework/validate-spec.ts
 /**
@@ -29,6 +30,18 @@ function walk(config, node, path, errors) {
 		const props = resolveComponentProps(config, target);
 		for (const name of Object.keys(node.props ?? {})) if (!(name in props)) errors.push(`${path}: unknown prop "${name}" on "${node.type}"`);
 		if (node.children?.length && childrenPolicy(config, target) === "none") errors.push(`${path}: "${node.type}" takes no children`);
+		for (const [name, fills] of Object.entries(node.slots ?? {})) {
+			const slot = slotOf({
+				config,
+				path: target,
+				slot: name
+			});
+			if (!slot) errors.push(`${path}: "${node.type}" has no slot "${name}"`);
+			fills.forEach((fill, i) => {
+				if (slot && !slot.takes(fill.type)) errors.push(`${path}: slot "${name}" of "${node.type}" takes ${slot.accepts.join(", ")}, not "${fill.type}"`);
+				walk(config, fill, `${path} > ${node.type}.${name}[${i}]`, errors);
+			});
+		}
 	}
 	(node.children ?? []).forEach((child, i) => {
 		walk(config, child, `${path} > ${node.type}[${i}]`, errors);