@yahoo/uds-create-config 2.45.0 → 3.0.0

package/dist/entities/system/Component.js

@@ -0,0 +1,1840 @@
+import { reject, rejectData } from "../../framework/rejection.js";
+import { 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";
+import { defineSubEntity } from "../../framework/defineSubEntity.js";
+import { derivedColor, gradient } from "./color.js";
+import { childrenPolicy } from "./element.js";
+import { listedIn } from "../../framework/utils/enumerated.js";
+import { valueSchemaOf } from "../../framework/value-domain.js";
+import { Style, addBagKeyIssues, bagNameEdges, bagRewriteName, bindBagTokens, collectBag, isPlainRecord, openBag, styleValue } from "./style-bag.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 { Package } from "./Package.js";
+import { File } from "./File.js";
+import { z } from "zod";
+//#region src/entities/system/Component.ts
+/**
+* Component — three things, in order:
+*
+*   1. `layers`  — a custom name → the element it points at. A layer is its element.
+*   2. `props`   — what this component exposes (its public API). Each carries its own domain
+*                  under `value`, so what may be assigned through it needs no second declaration.
+*   3. `styles`  — *when props are X, apply these props to these layers.*
+*
+* Step 3 replaces four shapes that were the same statement with a different condition: `base`
+* (no condition), a variant value's bags (one), a boolean's `true`/`false` (one), and
+* `compoundProps` (two or more). They are now one collection of rules, each keyed by its own
+* condition — so a rule's identity is its condition, duplicates are structurally impossible, and
+* precedence is specificity rather than stored order.
+*
+* There is no leaf/composite union: `inherits` names a layer whose element's props this component
+* also exposes, which is the only thing that distinction really encoded (a leaf `extends`ing a
+* Component inherited its API; a composite's layer pointing at one did not).
+*
+* The style-rule schema is built per owner (a `fields` factory): a rule may only target layers this
+* Component declares, may only set props those layers' elements actually expose, and may only
+* condition on this component's own props with their own values — all enforced by the schema
+* itself, so none of it is a refinement.
+*/
+/**
+* Write an inserted subtree: every node first, then every edge.
+*
+* Two passes because a node's stored `children` is narrowed to the component's existing node names —
+* so an edge written before its target exists is refused. Creating all of them first means the edges
+* validate against a component that already has every node they name, and no ordering of the caller's
+* map matters.
+*/
+function insertSubtree(config, path, nodes) {
+	let next = config;
+	for (const [key, node] of Object.entries(nodes)) next = next.apply({
+		kind: "component",
+		operation: "sub-create",
+		path,
+		field: "layers",
+		key,
+		data: asElementRef(config, node.element ?? "div")
+	}).apply({
+		kind: "component",
+		operation: "sub-create",
+		path,
+		field: "anatomy",
+		key,
+		data: {
+			element: layerRef(key),
+			...node.props ? { props: node.props } : {},
+			...node.visible !== void 0 ? { visible: node.visible } : {},
+			...node.text !== void 0 ? { text: node.text } : {}
+		}
+	});
+	for (const [key, node] of Object.entries(nodes)) {
+		if (!node.children?.length && !node.slots) continue;
+		next = next.apply({
+			kind: "component",
+			operation: "sub-update",
+			path,
+			field: "anatomy",
+			key,
+			data: {
+				...node.children?.length ? { children: node.children } : {},
+				...node.slots ? { slots: node.slots } : {}
+			}
+		});
+	}
+	return next;
+}
+/** A component-relative reference to one of the enclosing component's own layers — a slot's
+*  `target`. Relative (no component path) because a slot only ever targets a sibling layer, so a
+*  Component rename can't break it; a layer rename cascades through it. */
+function layerRef(layerKey) {
+	return ref("layer", layerKey);
+}
+/** The layer a node is styled through — the target of a `layer:` ref — or undefined for anything else. */
+function layerRefTarget(element) {
+	const target = element?.__ref;
+	if (typeof target !== "string") return void 0;
+	const { kind, qualifiedPath } = splitRef(target);
+	return kind === "layer" ? qualifiedPath : void 0;
+}
+/**
+* The name a subtree-local key lands under once grafted onto a component.
+*
+* A caller holds a subtree whose keys are local to it (`root`, `label`) and the component holds one
+* flat namespace, so the two have to be reconciled. Both directions live here, together, because a
+* convention split across packages drifts: the writer grafts and a reader ungrafts, and the reader
+* only works if it inverts exactly what the writer did.
+*/
+function graftKey(layer, local) {
+	return `${layer}__${local}`;
+}
+/**
+* A layer name nothing is using yet.
+*
+* The entity owns the anatomy namespace, so it is the only thing that can answer this without
+* guessing — callers were threading a `mintLayerKey` through six planner signatures to do it from
+* outside, each defaulting to its own copy of the same `el_ins_<uuid8>` convention.
+*
+* An ordinal rather than a uuid, for two reasons: the key becomes part of the emitted class name, so
+* it is read by people; and a uuid makes two replays of one patch produce different names, where the
+* point of a stored patch is that replaying it lands the same config.
+*
+* `layers` and `anatomy` share a namespace in practice — an insert writes both under one key — so
+* both are checked.
+*/
+function freeLayerKey(config, path, hint = "el") {
+	const body = config.resolve("component", path)?.toJSON();
+	const taken = new Set([...Object.keys(body?.layers ?? {}), ...Object.keys(body?.anatomy ?? {})]);
+	if (!taken.has(hint)) return hint;
+	let ordinal = 1;
+	while (taken.has(`${hint}${ordinal}`)) ordinal += 1;
+	return `${hint}${ordinal}`;
+}
+/**
+* A `kind:path` marker string as the ref it means.
+*
+* A spec element stores its type as a marker (`component:primitives/Box`), and `element` accepts a
+* union of string-or-ref whose first arm is the string — so a marker matched the string arm and was
+* stored as one. It still rendered, because the readers accept markers too, which is what made this
+* invisible: the value was simply absent from the dependency graph, so deleting the target passed its
+* referrer check and renaming it never cascaded.
+*
+* Coerced against the config rather than by pattern, so a tag that merely contains a colon isn't
+* mistaken for a reference to a kind nothing has registered.
+*/
+function asElementRef(config, value) {
+	if (typeof value !== "string") return value;
+	const { kind, qualifiedPath } = splitRef(value);
+	if (!kind || kind === value) return value;
+	return config.entityOf(kind) ? ref(kind, qualifiedPath) : value;
+}
+/**
+* A component-relative reference to one value of one of the enclosing component's own variant
+* props — what a style rule conditions on.
+*
+* Relative for the same reason {@link layerRef} is: a value only ever belongs to a sibling prop, so
+* a component rename can't break it. What it buys is the other direction — a value rename is an
+* ordinary ref rewrite, and because a rule's key is derived from its condition, the rules holding it
+* re-key themselves. Without the ref the name sits in a plain string, invisible to that rewrite, and
+* every rule conditioned on the old name silently stops applying.
+*/
+function valueRef(prop, value) {
+	return ref("value", `${prop}/${value}`);
+}
+/** What a layer renders as: a native tag (`'div'`), a ref to another Component, or a package
+*  export (a `package:` ref). A native import (`import { View } from 'react-native'`) arrives as
+*  that ref already: the loader virtualizes the package and binds each export to
+*  `package:<module>#<export>` (codegen's `nativePackagesPlugin`). Lazy + typed on the Component
+*  arm because this is the same self-referential kind. */
+const element = z.union([
+	z.string(),
+	z.lazy(() => Component),
+	Package
+], { error: "a layer renders an intrinsic tag (`div`), a component (`{ \"__ref\": \"component:<path>\" }`) or a package export (`{ \"__ref\": \"package:<export>\" }`). A glyph is not a layer: it is an anatomy node, `{ \"element\": { \"__ref\": \"icon:<library>/<Name>\" } }`, listed in the `children` of the layer node that holds it." });
+/** A `children` or `slots` entry that is not a string: the writer inlined the node instead of naming it. */
+const childKeyError = (issue) => issue.code === "invalid_type" ? "a child is the KEY of a sibling node, written as a string; define the node under its own key in `anatomy` and name that key here" : void 0;
+const Layer = defineSubEntity({
+	name: "layer",
+	label: "Layer",
+	fields: element,
+	/**
+	* A slot's `target` is a `layer:` ref, so deleting the layer has to take the slot with it — the
+	* same cascade `VariantValue` declares for the rules conditioned on it. Without this, deleting a
+	* targeted layer left the prop pointing at nothing: `dependentsOf` cannot see it (a `layer:` ref
+	* is component-relative and so is not in the graph), and nothing else was checking, so the
+	* Component kept a slot that routed content to an element that no longer existed.
+	*/
+	orphans: ["props", "forwards"],
+	keyedByNameIn: ["forwards", "styles/*/layers"]
+});
+/**
+* Which of a layer's element's props this component also exposes at its own top level, so
+* `<Field disabled />` means the `input` layer's `disabled` and no caller reaches through
+* `layerProps`.
+*
+* Keyed by layer, like `layers` itself — a layer cannot acquire two conflicting entries by
+* construction, each entry is addressable on its own (`sub-update` on `forwards`, key `input`), and
+* nothing downstream has to learn a new shape.
+*
+* The member is the selection, with no options wrapper, because there is exactly one thing to say
+* and there always will be: `'*'` for everything that element exposes, or a list of member refs
+* naming the props to take. Removing a forwarded prop is the existing `props: { x: null }` tombstone,
+* so there is no `except` — and renaming is the singular `bind()` form, so there is no rename here.
+*
+* A list holds refs rather than names so the dependency graph sees the edge: `collectRefs` harvests
+* every `{__ref}` generically, which is what makes `dependents('component:Input#props/disabled')`
+* name this component, so a rename cascades and a delete is refused. `'*'` holds no ref and so
+* cannot rot — it tracks a rename for free.
+*/
+/** The prop name a forwarding member ref identifies, or `undefined` for any other ref shape. */
+function forwardedPropName(value) {
+	if (!isRef(value) || kindOf(value.__ref) !== "component") return void 0;
+	const member = memberOf(value);
+	if (!member?.startsWith("props/")) return void 0;
+	const name = member.slice(6);
+	return name && !name.includes("/") ? name : void 0;
+}
+const forwardedPropRef = refSchema.check((ctx) => {
+	if (forwardedPropName(ctx.value) !== void 0) return;
+	ctx.issues.push({
+		code: "custom",
+		input: ctx.value,
+		message: "a narrowed forward must contain component prop MEMBER REFS (`component:Input#props/disabled`)"
+	});
+});
+const forwardMember = z.union([z.literal("*"), z.array(forwardedPropRef)], { error: "a forward is '*' or a list of component prop MEMBER REFS — a bare prop name is neither. `.forwards({ layer: ['disabled'] })` mints the refs from names; a patch supplies them. `forwards` exposes a layer's element props (`{ \"<layer>\": \"*\" }`); to route a prop's content into a layer, declare the prop in `props` as `{ \"type\": \"forward\", \"target\": \"<layer>/children\" }`." });
+/** The prop names one entry exposes — `null` when the config can't say (an unresolved element). */
+function forwardedNames(config, element, entry) {
+	if (Array.isArray(entry)) return entry.map(forwardedPropName).filter((name) => !!name);
+	if (entry !== "*" || !isRef(element)) return null;
+	return Object.keys(resolveComponentProps(config, pathOf(element.__ref)));
+}
+const Forward = defineSubEntity({
+	name: "forward",
+	label: "Forward",
+	labelPlural: "Forwards",
+	base: forwardMember,
+	fields: ({ config, parent, key }) => {
+		const body = parent;
+		if (!config || !body || !key) return forwardMember;
+		const layers = body.layers ?? {};
+		const element = layers[key];
+		return forwardMember.check((ctx) => {
+			if (!(key in layers)) {
+				ctx.issues.push({
+					code: "custom",
+					input: ctx.value,
+					message: `"${key}" is not one of this component's layers (${Object.keys(layers).join(", ") || "none"}).`
+				});
+				return;
+			}
+			if (!isRef(element)) {
+				ctx.issues.push({
+					code: "custom",
+					input: ctx.value,
+					message: `layer "${key}" renders ${typeof element === "string" ? `<${element}>` : "no component"}, which declares no props to forward.`
+				});
+				return;
+			}
+			const exposes = resolveComponentProps(config, pathOf(element.__ref));
+			if (Array.isArray(ctx.value)) for (const entry of ctx.value) {
+				const name = forwardedPropName(entry);
+				if (name && !(name in exposes)) ctx.issues.push({
+					code: "custom",
+					input: entry,
+					message: `"${name}" is not a prop of layer "${key}"'s element (${pathOf(element.__ref)}).`
+				});
+			}
+			const mine = forwardedNames(config, element, ctx.value);
+			if (!mine) return;
+			for (const [otherKey, otherEntry] of Object.entries(body.forwards ?? {})) {
+				if (otherKey === key) continue;
+				if (ctx.value === "*" && otherEntry === "*") {
+					ctx.issues.push({
+						code: "custom",
+						input: ctx.value,
+						message: `only one layer may forward '*' — "${otherKey}" already does. List the props this layer should expose instead, or route one with bind().`
+					});
+					continue;
+				}
+				const theirs = forwardedNames(config, layers[otherKey], otherEntry);
+				if (!theirs) continue;
+				const shared = mine.filter((name) => theirs.includes(name));
+				if (shared.length > 0) ctx.issues.push({
+					code: "custom",
+					input: ctx.value,
+					message: `layers "${key}" and "${otherKey}" would both forward ${shared.slice(0, 3).map((n) => `"${n}"`).join(", ")}${shared.length > 3 ? ` (+${shared.length - 3} more)` : ""}. Route one explicitly with bind().`
+				});
+			}
+		});
+	}
+});
+const VariantValue = defineSubEntity({
+	name: "value",
+	label: "Value",
+	fields: z.strictObject({
+		/** What to call it, and what it's for, where it is offered — a picker row, the AI's catalogue.
+		*  The name is an identifier and reads like one (`ui6`, `xs`); this is the human half. */
+		label: z.string().optional(),
+		description: z.string().optional(),
+		/** Withdrawn from new work, exactly as a component's own `deprecated` is: still valid wherever
+		*  it is already used, left out of surfaces that offer values. The alternative to deleting it,
+		*  which takes its styling with it. */
+		deprecated: z.boolean().optional()
+	}),
+	namedValuesIn: ["defaultProps", "previewProps"],
+	orphans: ["styles"]
+});
+/**
+* A variant's domain: the values it owns, or a ref that delegates to whatever owns them.
+*
+* The array form is what an author writes (`['solid', 'ghost']`) and is coerced here into the
+* collection it is stored as, so every reader below this line sees one shape. In the schema rather
+* than in the authoring adapter because there are four doors into stored state — `register`, an
+* item create/update, a sub-op, and the artifact loader — and a coercion outside the schema only
+* covers the one it is written in.
+*/
+const variantDomain = z.union([
+	z.array(z.string()).transform((names) => Object.fromEntries(names.map((name) => [name, {}]))),
+	refSchema,
+	VariantValue
+]);
+/** Every prop type names its domain `value`, so one generic rule (`valueSchemaOf`) derives what
+*  may be assigned through it: a keyed collection enumerates, a ref delegates to whatever owns the
+*  values, a plain value gives its type (and doubles as the default). */
+/**
+* A routed prop's target, as authored: `<layer>/<prop>`.
+*
+* One segment either side, so `'label'` alone is refused rather than silently splitting into a layer
+* with an empty prop name — the mistake the `layer()` helper's type used to catch.
+*/
+const layerPath = z.string().regex(/^[^/]+\/[^/]+$/, "expected `<layer>/<prop>`");
+/**
+* Split an authored `<layer>/<prop>` target into the pair the readers want.
+*
+* In the schema rather than in the authoring adapter, for the reason `variantDomain` gives: there are
+* four doors into stored state — `register`, an item create/update, a sub-op, and the artifact loader —
+* and a coercion outside the schema only covers the one it is written in. A prop written by a Studio
+* Patch comes through a different door than one written in a config file, and both mean the same thing.
+*/
+function routedTarget(decl) {
+	if (!("target" in decl) || typeof decl.target !== "string") return decl;
+	const separator = decl.target.indexOf("/");
+	return {
+		...decl,
+		target: layerRef(decl.target.slice(0, separator)),
+		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 }\`.`;
+} });
+/** The prop types, for the refusal that names them. */
+const PROP_TYPES = [
+	"slot",
+	"variant",
+	"forward",
+	"styleProperty",
+	"composite",
+	"motion",
+	"string",
+	"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.";
+/** 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({
+	name: "prop",
+	label: "Prop",
+	/**
+	* A factory, for one rule the shape alone can't state: `accepts` narrows content, so it is valid on a
+	* slot and on a route whose target prop is a slot — and meaningless on a route that carries a value,
+	* where what may be passed is the target prop's own domain.
+	*
+	* Whether a route carries content is computed (`routesContent`) from the target's layer and prop, which
+	* is the same question every reader asks, so the rule and the readers cannot disagree about an answer
+	* neither of them stores. It needs the owner's layers, which is what makes this a factory rather than a
+	* schema — the check is part of the schema, not a refinement bolted beside it.
+	*/
+	fields: ({ config, parent }) => {
+		if (!config || !isPlainObject(parent)) return propShape.nullable().describe(PROP_DESCRIPTION);
+		return perOwner({
+			cache: propSchemas,
+			config,
+			owner: parent,
+			build: () => propSchemaFor(config, parent).describe(PROP_DESCRIPTION)
+		});
+	},
+	namespaces: "value",
+	subEntities: { value: VariantValue },
+	keyedByNameIn: ["defaultProps", "previewProps"],
+	orphans: ["styles"]
+});
+/** {@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) => {
+		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 ?? "?");
+		const prop = intoName(decl.into);
+		const routed = routedPropIn(config, layers, decl);
+		ctx.issues.push({
+			code: "custom",
+			input: decl,
+			path: ["accepts"],
+			message: routed ? `\`accepts\` says what may FILL a content hole — an icon set, so any glyph it registers can be dropped in (\`Button.startIcon\` accepts \`Icon.ref('phosphor')\`), or a component. \`${layer}/${prop}\` is a ${routed.type} prop, so it takes a value rather than content. Remove \`accepts\`, or point \`target\` at a prop declared \`{ type: 'slot' }\`.` : `\`accepts\` says what may FILL a content hole — an icon set, or a component. The \`${layer}\` layer is a plain tag, and \`children\` is the only prop a tag carries content through — so either target \`${layer}/children\`, or remove \`accepts\`.`
+		});
+	});
+}
+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("&");
+}
+/**
+* What a rule may set one prop to: the prop's own value domain, plus — for a prop that writes CSS —
+* the value forms a style value takes whatever values it enumerates.
+*
+* `styleValue`, the bag a layer gets when its element isn'T a resolvable component, has always
+* modelled a computed colour and a gradient. Narrowing to a prop's leaves has to add precision to
+* the leaf case rather than drop those forms, or the same rule validates or not depending on whether
+* the layer's element happens to resolve — which is a property of the config, not of the rule.
+*/
+function styleBagValue(config, declaration, name = "<prop>") {
+	const domain = valueSchemaOf(declaration, config);
+	const bound = declaration?.value;
+	if (declaration?.type === "slot") return z.union([domain, z.never()], { error: () => `\`${name}\` is a slot, so a rule may set it to a string of content and nothing else. A glyph or a nested element is an anatomy node under the layer's node — \`{ "element": { "__ref": "icon:<library>/<Name>" }, "visible": { "$state": "<prop>", "eq": "<value>" } }\` to show one per variant value — and the instance's own content arrives through the prop.` });
+	if (!isRef(bound) || kindOf(bound.__ref) !== "style-property") return domain;
+	const property = pathOf(bound.__ref);
+	return z.union([
+		domain,
+		derivedColor,
+		gradient,
+		refSchema
+	], { error: () => {
+		const leaves = stylePropValueLeaves(config, property);
+		const shown = leaves.slice(0, 12).map((leaf) => `\`${leaf}\``);
+		const more = leaves.length > 12 ? `, … (${leaves.length} in all)` : "";
+		const arbitrary = (config.resolve("style-property", property)?.toJSON())?.arbitrary === true ? ", or a bracketed literal such as `[13px]`" : "";
+		return `\`${name}\` takes one of ${shown.join(", ")}${more}${arbitrary}, or a token ref. A value the system has no token for is added to the style property's \`values\` first.`;
+	} });
+}
+/**
+* What a rule may set on one layer.
+*
+* A layer bag is props for that layer, under the rule's condition — not a stylesheet fragment. Some
+* of those props are style properties, and a style property is only a projection rule (prop value →
+* CSS property), so the emitter can bake them into the layer's class instead of passing them; the
+* rest are routed to the element as ordinary props. Both halves are the same kind of thing, which is
+* why they live in one bag.
+*
+* So the bag is OPEN, like the raw-tag case below, and narrowing is about values rather than keys:
+*
+*  - a prop the element declares is typed by its own domain, so `variant: 'bogus'` is still caught;
+*  - every registered style property is typed as a style value, whatever the element declares —
+*    a layer backed by a primitive and one backed by a closed component must accept the same rule,
+*    since which of the two it happens to be says nothing about the rule (the same objection
+*    {@link styleBagValue} already records for the resolvable-vs-not case);
+*  - anything else is an attribute of the element (`type`, `aria-*`, `data-*`), which can't be
+*    enumerated and so can't be checked — exactly the position a `div` layer is already in.
+*
+* A modifier block (`_hover`) nests a bag of the same shape.
+*/
+function bagFor(config, layerElement) {
+	const key = isRef(layerElement) ? layerElement.__ref : "";
+	let bags = layerBags.get(config);
+	if (!bags) {
+		bags = /* @__PURE__ */ new Map();
+		layerBags.set(config, bags);
+	}
+	const cached = bags.get(key);
+	if (cached) return cached;
+	const built = buildBagFor(config, layerElement);
+	bags.set(key, built);
+	return built;
+}
+/** One element's bag, built. Reached only through the memo above. */
+function buildBagFor(config, layerElement) {
+	const shape = { ...stylePropShape(config) };
+	const component = isRef(layerElement) && config.resolveRef(layerElement.__ref) ? pathOf(layerElement.__ref) : void 0;
+	for (const [name, decl] of Object.entries(component ? resolveComponentProps(config, component) : {})) shape[name] = styleBagValue(config, decl, name).optional();
+	const declared = component ? (config.resolve("component", component)?.toJSON())?.props ?? {} : {};
+	for (const [name, decl] of Object.entries(declared)) {
+		if (decl?.type !== "slot" || name in shape) continue;
+		shape[name] = styleBagValue(config, decl, name).optional();
+	}
+	shape.as ??= z.string().optional();
+	let bag;
+	const nested = z.lazy(() => bag).optional();
+	for (const mod of config.list("modifier")) shape[`_${mod.leaf}`] = nested;
+	bag = z.object(shape).catchall(styleValue).superRefine((parsed, ctx) => addBagKeyIssues({
+		config,
+		bag: parsed,
+		ctx,
+		nested: false,
+		declared: new Set(Object.keys(shape))
+	})).transform((parsed) => bindBagTokens(config, parsed));
+	return bag;
+}
+/**
+* Every registered style property as a bag key, built once per config.
+*
+* `bagFor` runs per layer and there are a couple of hundred style properties, so building their
+* value schemas per bag would put the cost back that pointing the modifier keys at one bag took out
+* (see below). The shape is a pure function of the config's style properties, so one copy serves
+* every layer of every component — callers spread it and then overwrite with the element's own
+* declarations, so the shared object is never mutated.
+*/
+const stylePropShapes = /* @__PURE__ */ new WeakMap();
+/** {@link bagFor}'s memo — per config, then per element ref (`''` for every element that resolves to
+*  no component, which all share the one open bag). */
+const layerBags = /* @__PURE__ */ new WeakMap();
+function stylePropShape(config) {
+	const cached = stylePropShapes.get(config);
+	if (cached) return cached;
+	const shape = {};
+	for (const prop of config.list("style-property")) shape[prop.path] = styleBagValue(config, {
+		type: "styleProperty",
+		value: { __ref: `style-property:${prop.path}` }
+	}, prop.path).optional();
+	stylePropShapes.set(config, shape);
+	return shape;
+}
+/**
+* Whether a prop's values belong to this component — an enumerated variant, whose values exist
+* nowhere else and so have no identity until one is given here.
+*
+* A variant that delegates its domain to a ref (an icon prop drawing on the icon library) names
+* values another entity already owns; those rename through their owner's own cascade, and minting a
+* Component-relative identity for them would be a second name for the same thing.
+*/
+function ownsItsValues(declaration) {
+	const decl = declaration;
+	if (decl?.type !== "variant") return false;
+	return decl.value !== void 0 && !isRef(decl.value);
+}
+/** The values a variant prop declares, in order — empty for one that delegates its domain. */
+function ownValues(declaration) {
+	if (!ownsItsValues(declaration)) return [];
+	return listedIn(declaration.value) ?? [];
+}
+/**
+* What a rule may condition one prop on: any of that prop's values, written bare and stored as a
+* {@link valueRef}.
+*
+* The coercion is the whole point of putting it in the schema. `Config.apply` stores the parsed
+* output, so authors, AI tools and patches keep writing `{ variant: 'solid' }` and the ref form
+* never surfaces above this line — while the ref graph, the rename cascade and `dependentsOf` all
+* see a real edge. Accepting a ref as well is what lets stored data re-validate on update.
+*/
+function conditionValue(prop, declaration, config) {
+	const domain = valueSchemaOf(declaration, config);
+	if (!ownsItsValues(declaration)) return domain;
+	return z.union([domain, refSchema]).transform((value) => isRef(value) ? value : valueRef(prop, String(value)));
+}
+/** `ExampleComponent`, or the first numbered name no component holds. Models copy examples
+*  literally, so the path has to be one a create would take. */
+function freeExamplePath(config) {
+	let path = "ExampleComponent";
+	for (let n = 2; config.resolve("component", path); n += 1) path = `ExampleComponent${n}`;
+	return path;
+}
+/**
+* What a `forwards` entry is, for the ops that write one. Shared by add, set and update, since the
+* member is the same value under each verb and a model reads whichever it reaches first.
+*/
+const FORWARDS_DESCRIPTION = "Expose a layer's props at this component's top level. `key` is one of the component's own layer names; `data` is `\"*\"` for every prop that layer's element takes, or a list of component prop member refs (`[{ \"__ref\": \"component:Box#props/width\" }]`) for a selection, each naming the component that declares the prop — `Button` forwarding `width` from a `Pressable` root names `Box`, where `Pressable` takes it from. This is how `<Button width=\"full\">` reaches the root's `width` with no `width` entry in `props`; a prop the layer already exposes is forwarded, never redeclared. Two entries may not offer the same prop, and removing one forwarded prop is a `null` tombstone under `props`.";
+/**
+* A runnable `sub-create/forwards` example: the first local component that forwards nothing and has
+* a layer rendering a component, forwarding all of that layer. A component that already forwards is
+* skipped rather than reasoned about, since a second `"*"` entry collides with the first. `undefined`
+* when no component qualifies, since an example the op would refuse teaches a refusal.
+*/
+function forwardsCreateExample(config) {
+	for (const component of config.list("component")) {
+		if (component.borrowedFrom !== void 0) continue;
+		const body = component.toJSON();
+		if (Object.keys(body.forwards ?? {}).length) continue;
+		for (const [key, element] of Object.entries(body.layers ?? {})) {
+			if (!isRef(element) || kindOf(element.__ref) !== "component") continue;
+			return {
+				path: component.path,
+				key,
+				data: "*"
+			};
+		}
+	}
+}
+/**
+* A small, valid style bag for a layer that renders `primitivePath`: up to three of the style props
+* that primitive exposes, each set to the first value it accepts. Drawn from the config so the bag is
+* copy-paste-valid, and only there to show that a composed component sets style-prop values in a rule.
+*/
+function exampleStyleBag(config, primitivePath) {
+	const props = (config.resolve("component", primitivePath)?.toJSON())?.props ?? {};
+	const inert = new Set([
+		"inherit",
+		"initial",
+		"unset",
+		"none",
+		"auto",
+		"normal",
+		"transparent",
+		"current",
+		"currentColor",
+		"0"
+	]);
+	const bag = {};
+	for (const [name, prop] of Object.entries(props)) {
+		if (prop?.type !== "styleProperty" || !isRef(prop.value)) continue;
+		const leaves = stylePropValueLeaves(config, pathOf(prop.value.__ref));
+		const value = leaves.find((leaf) => !inert.has(leaf)) ?? leaves[0];
+		if (value !== void 0) bag[name] = value;
+		if (Object.keys(bag).length >= 3) break;
+	}
+	return bag;
+}
+/**
+* The create example on a system that has primitives, built on them: a root and an icon layer on the
+* first local component that takes nodes, a label and a body on the first that takes text, a glyph from
+* the first icon library when there is one. It is the grammar the build records off a render, in the
+* forms a real component in this system would use — a route for text (`forward`), a node gated on a
+* prop (`visible`), a glyph as a node of its own, the edge list, a style rule that sets the primitives'
+* own style props, and preview content. `undefined` when the system has no primitive of each kind,
+* which the intrinsic-tag example then covers.
+*/
+function composedCreateExample(config, path) {
+	const locals = config.list("component").filter((component) => component.borrowedFrom === void 0);
+	const nodesHost = locals.find((component) => childrenPolicy(config, component.path) === "nodes");
+	const textHost = locals.find((component) => childrenPolicy(config, component.path) === "text");
+	if (!nodesHost || !textHost) return void 0;
+	const glyph = config.list("icon")[0];
+	const container = { __ref: `component:${nodesHost.path}` };
+	const text = { __ref: `component:${textHost.path}` };
+	const styleLayers = {};
+	const rootStyles = exampleStyleBag(config, nodesHost.path);
+	const labelStyles = exampleStyleBag(config, textHost.path);
+	if (Object.keys(rootStyles).length) styleLayers.root = rootStyles;
+	if (Object.keys(labelStyles).length) styleLayers.label = labelStyles;
+	return {
+		path,
+		data: {
+			layers: {
+				root: container,
+				icon: container,
+				label: text,
+				body: container
+			},
+			props: {
+				icon: { type: "boolean" },
+				label: {
+					type: "forward",
+					target: "label/children"
+				},
+				children: { type: "slot" }
+			},
+			anatomy: {
+				root: {
+					element: { __ref: "layer:root" },
+					children: [
+						"icon",
+						"label",
+						"body"
+					]
+				},
+				icon: {
+					element: { __ref: "layer:icon" },
+					visible: { $state: "icon" },
+					...glyph ? { children: ["glyph"] } : {}
+				},
+				...glyph ? { glyph: { element: { __ref: `icon:${glyph.path}` } } } : {},
+				label: { element: { __ref: "layer:label" } },
+				body: {
+					element: { __ref: "layer:body" },
+					children: ["content"]
+				},
+				content: {
+					element: "Slot",
+					props: { name: "children" }
+				}
+			},
+			...Object.keys(styleLayers).length ? { styles: { "*": {
+				when: null,
+				layers: styleLayers
+			} } } : {},
+			previewProps: {
+				icon: true,
+				label: "Example",
+				children: "Body text"
+			}
+		}
+	};
+}
+/**
+* The shape of an anatomy node, for one written in the canvas spec's spelling. A spec element is
+* `{ type, props, children }` with `$prop` bindings; an anatomy node is `{ element, props, children,
+* visible, text, slots }` with keys naming sibling nodes, and content routed by the prop.
+*/
+const nodeShapeError = (issue) => {
+	if (issue.code !== "unrecognized_keys") return void 0;
+	const keys = issue.keys ?? [];
+	if (keys.filter((key) => [
+		"type",
+		"tag",
+		"name",
+		"$prop"
+	].includes(key)).length === 0) return void 0;
+	return `an anatomy node is \`{ "element", "children"?, "visible"?, "props"?, "text"?, "slots"? }\`, not a canvas spec element: \`element\` is what the node renders (\`{ "__ref": "layer:<name>" }\`, \`{ "__ref": "icon:<library>/<Name>" }\`, an intrinsic tag, or \`Slot\`), \`children\` lists sibling node KEYS, and a prop's content is routed by declaring the prop \`{ "type": "forward", "target": "<layer>/children" }\` rather than bound with \`$prop\`. Unknown here: ${keys.map((key) => `\`${key}\``).join(", ")}.`;
+};
+/** Whether two layer elements spell the same thing — a tag, or a ref to the same target. */
+function sameElement(left, right) {
+	if (isRef(left) && isRef(right)) return left.__ref === right.__ref;
+	return typeof left === "string" && left === right;
+}
+/** Whether a node keyed like a layer spells that layer — as the layer's own element, or as the bare
+*  layer name where an intrinsic tag would go. Either is read as the layer. */
+function spellsLayer(element, key, layer) {
+	return element === key || sameElement(element, layer);
+}
+/** The shape of a rule, for a bag written where the rule belongs or a rule with no `layers`. */
+const ruleShapeError = (issue) => issue.code === "invalid_type" || issue.code === "unrecognized_keys" ? "a style rule is `{ \"when\": null, \"layers\": { \"<layer>\": { \"<styleProp>\": \"<value>\" } } }` under a key of your own (`*` for the unconditional rule), or with `\"when\": { \"<prop>\": \"<value>\" }` for a variant; the layer bags sit under `layers`, never directly under the rule" : void 0;
+const StyleRule = defineSubEntity({
+	name: "style",
+	label: "Style",
+	labelPlural: "Styles",
+	key: (rule) => canonicalWhen(rule?.when),
+	vacant: (rule) => {
+		const layers = rule?.layers;
+		if (!layers) return true;
+		return Object.values(layers).every((bag) => !bag || Object.keys(bag).length === 0);
+	},
+	namesMembersOf: { when: "props" },
+	fields: ({ config, parent }) => {
+		const body = parent;
+		if (!config || !body) return z.object({
+			when: z.record(z.string(), z.unknown()).nullable().default(null),
+			layers: z.record(z.string(), z.record(z.string(), z.union([styleValue, z.never()], { error: "a layer bag value is a style-prop value — a token leaf such as `surface`, a keyword, a bracketed literal such as `[13px]` — or a modifier block holding more of them. Content is not set in a style rule: a glyph or a nested element is an anatomy node under the layer's node, `{ \"element\": { \"__ref\": \"icon:<library>/<Name>\" }, \"visible\": { \"$state\": \"<prop>\", \"eq\": \"<value>\" } }` to show one per variant value." })), { error: ruleShapeError })
+		}, { error: ruleShapeError });
+		return perOwner({
+			cache: ruleSchemas,
+			config,
+			owner: body,
+			build: () => {
+				const when = {};
+				for (const [name, decl] of Object.entries(body.props ?? {})) when[name] = conditionValue(name, decl, config).optional();
+				const layers = {};
+				for (const [name, el] of Object.entries(body.layers ?? {})) layers[name] = bagFor(config, el).optional();
+				return z.strictObject({
+					when: z.strictObject(when).nullable().default(null),
+					layers: z.strictObject(layers, { error: ruleShapeError })
+				}, { error: ruleShapeError });
+			}
+		});
+	}
+});
+/**
+* A per-owner member schema, built once per owner rather than once per member.
+*
+* A factory is called for every member it validates, and Zod does its first-parse setup on each fresh
+* schema, so a component with thirty rules would build its `when` shape and its layer bags thirty times
+* over. The schema reads only the owner's `props` and `layers`, so it is keyed on those two objects: the
+* owner is a body under construction whose collections are swapped as each one is coerced, and a key on
+* the body alone would answer for `props` it has since replaced. A `Config` is immutable, so under one
+* config the same two objects always build the same schema.
+*/
+function perOwner({ cache, config, owner, build }) {
+	let perConfig = cache.get(config);
+	if (!perConfig) {
+		perConfig = /* @__PURE__ */ new WeakMap();
+		cache.set(config, perConfig);
+	}
+	const hit = perConfig.get(owner);
+	if (hit && hit.props === owner.props && hit.layers === owner.layers) return hit.schema;
+	const schema = build();
+	perConfig.set(owner, {
+		props: owner.props,
+		layers: owner.layers,
+		schema
+	});
+	return schema;
+}
+const ruleSchemas = /* @__PURE__ */ new WeakMap();
+/** 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
+*  rather than a list copied in here. A content-position node is the string `'Slot'` — the registry
+*  primitive — with the prop it stands for in `props.name`; the place an untargeted slot prop's
+*  instance content lands, whose position among its siblings only the edge list can state. */
+const nodeElement = z.union([
+	refSchema.describe("A ref. `layer:<name>` renders through one of this component's layers, which is the only way a node can be styled; `component:<path>`, `icon:<path>` or `package:<export>` renders that directly, unstyled."),
+	z.string().describe("An intrinsic tag such as `div`, rendered unstyled, or `Slot`: the position where an untargeted slot prop's content lands, with the prop named in `props.name`, listed in the `children` of a layer that takes nodes. A text layer shows a prop through a `forward` declared on the prop instead."),
+	z.strictObject({ $state: z.string() }).describe("An element the instance chooses: the value of the prop `$state` names, from that prop's own domain (an icon prop whose value is a glyph). It carries no per-value table; to show a different fixed glyph per variant value, give each glyph its own node with `visible: { \"$state\": \"<prop>\", \"eq\": \"<value>\" }`.")
+], { error: "an element is `{ \"__ref\": \"layer:<name>\" }` for one of this component's layers, `{ \"__ref\": \"icon:<library>/<Name>\" }` for a glyph, `{ \"__ref\": \"component:<path>\" }` for a component rendered unstyled, an intrinsic tag such as `div`, `Slot` for where a slot prop's content lands, or `{ \"$state\": \"<prop>\" }` for an element the prop chooses" }).describe("What this node renders. Name a layer (`{ \"__ref\": \"layer:<name>\" }`) for anything a style rule should reach.");
+/** The operand each comparison accepts. Checked against the framework's operator set both ways, so
+*  the schema can neither drop an operator the readers handle nor accept one they don't. */
+const comparisonOperands = {
+	eq: z.unknown().optional(),
+	neq: z.unknown().optional(),
+	gt: z.number().optional(),
+	gte: z.number().optional(),
+	lt: z.number().optional(),
+	lte: z.number().optional()
+};
+/** json-render's own visibility grammar, which is why nothing here is invented: a bare condition is
+*  a truthiness test, an array is the implicit and, `$or` is the explicit or.
+*
+*  `$state` is stored as a JSON pointer, so a missing leading slash is added. Both spellings name the
+*  same prop, and storing one of them is what lets a reader compare conditions as values. */
+const stateCondition = z.strictObject({
+	$state: z.string().refine((s) => !s.replace(/^\//, "").includes("/"), { message: "`$state` names one prop of this component; a nested JSON pointer has nothing to descend into." }),
+	...comparisonOperands,
+	not: z.literal(true).optional()
+}).transform((test) => ({
+	...test,
+	$state: test.$state.startsWith("/") ? test.$state : `/${test.$state}`
+}));
+const orCondition = z.strictObject({ $or: z.array(stateCondition) });
+/**
+* The flat condition an editor collects — `{ variant: 'solid' }` — compiled to the grammar above.
+*
+* The same shape a style rule's `when` takes, and for the same reason: a surface scoping something to
+* a variant has a prop and a value, not a query language. Compiled here rather than at the caller so
+* both spellings mean the same thing wherever a condition is written — and so the value goes through
+* `refLeaf`, which is what lets a condition hold the ref form it is stored as.
+*
+* A `true` operand compiles to the bare truthiness test rather than to `eq: true`, so the condition a
+* surface writes for "this prop is set" is the one spelling of it. `false` keeps its `eq`, since
+* unset and explicitly false are different states.
+*/
+const flatCondition = z.record(z.string(), z.union([
+	z.string(),
+	z.number(),
+	z.boolean(),
+	refSchema
+])).check((ctx) => {
+	for (const key of Object.keys(ctx.value)) {
+		if (!key.startsWith("$")) continue;
+		ctx.issues.push({
+			code: "custom",
+			input: ctx.value,
+			message: `\`${key}\` is json-render's grammar, so this condition is read as one — and it has an operator that isn't part of it. Use \`$state\` with one of eq/neq/gt/gte/lt/lte/not, or drop the \`$\` keys for a plain { prop: value } condition.`
+		});
+	}
+}).transform((flat) => {
+	const conditions = Object.entries(flat).sort(([a], [b]) => a.localeCompare(b)).map(([state, value]) => {
+		const operand = refLeaf(value);
+		if (operand === true) return { $state: `/${state}` };
+		return {
+			$state: `/${state}`,
+			eq: operand
+		};
+	});
+	return conditions.length === 1 ? conditions[0] : conditions;
+});
+const visibility = z.union([
+	stateCondition,
+	orCondition,
+	z.array(z.union([stateCondition, orCondition])),
+	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" });
+/** One inserted node's accepted shape — {@link InsertedNode}, as the op validates it. Declared after
+*  {@link visibility} because a descendant may carry its own condition. */
+const insertedNode = z.strictObject({
+	element: z.union([z.string(), refSchema]).default("div"),
+	props: z.record(z.string(), z.unknown()).optional(),
+	children: z.array(z.string()).optional(),
+	/** Slot fills among the inserted nodes — the same native grammar the stored node keeps. */
+	slots: z.record(z.string(), z.array(z.string())).optional(),
+	visible: visibility.optional(),
+	/** A declared field of the stored node that the op had no input for, so an inserted element could
+	*  never arrive with its text and had to be given it by a second write. */
+	text: z.string().optional()
+});
+/** The component a node renders, for asking what it may be given as children. `undefined` when the
+*  node isn't a component (an intrinsic tag, a glyph, a bound element) — none of which this config
+*  can answer for, so nothing is claimed about them. */
+function nodeComponent(body, element) {
+	let target = element;
+	if (isRef(target) && kindOf(target.__ref) === "layer") target = body?.layers?.[pathOf(target.__ref)];
+	return isRef(target) && kindOf(target.__ref) === "component" ? pathOf(target.__ref) : void 0;
+}
+/**
+* The write a slot fill makes on the host node, shared by `element-insert` and `element-move`:
+* the host's `slots` entry pointing at the filled node, in json-render's own native grammar — the
+* renderer resolves the element's `slots` field itself — so this writes a mechanism the renderer
+* has, rather than inventing one.
+*
+* Whose prop `slotProp` is varies with how the fill was addressed, which makes it the field most
+* likely to be wrong — and it was the one never checked, so a typo stored a fill under a name no
+* prop routes and it simply never appeared. Checked only when the parent resolves to a component
+* this config describes: an unknown target is not "a component with no props", so claiming
+* otherwise would refuse a legitimate write.
+*
+* `visible`: filling the slot is the statement that the host now holds content, so the same write
+* spends the host's collapse-while-empty gate on the prop the config routes into this fill — the
+* bare truthiness test of that prop, and nothing else. Button's `startIcon` Box carries
+* `visible: { $state: '/startIcon' }`, and the fill writes the slot ref rather than the prop, so
+* without this the accepted fill paints nowhere. In an and-list the terms beside it survive; an `$or`
+* group holding it goes whole, since the fill makes the group true. A test that compares the prop to
+* anything but `true`, or negates it, is untouched. `undefined` leaves
+* the field alone and `null` clears it, so a caller writes the field only when there is a change.
+* 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 }) {
+	const host = nodeComponent({ layers }, node?.element ?? layers?.[parent]);
+	if (host && config.resolve("component", host)) {
+		const declared = resolveComponentProps(config, host);
+		if (!declared[slotProp]) reject("NOT_FOUND", `"${host}" has no \`${slotProp}\` prop to fill — its slots are ${Object.keys(declared).join(", ") || "(none)"}.`);
+	}
+	const current = node?.slots?.[slotProp] ?? [];
+	const slots = {
+		...node?.slots,
+		[slotProp]: current.includes(key) ? current : [...current, key]
+	};
+	const parentElement = node?.element;
+	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 };
+	return {
+		slots,
+		visible: withoutTruthyTerm({
+			condition: node?.visible,
+			prop: route.from
+		})
+	};
+}
+/**
+* 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)
+* and the node's other slots are never restated.
+*/
+function staleSlotEntries(slots, doomed) {
+	return Object.entries(slots ?? {}).map(([name, fills]) => [name, fills.filter((fill) => !doomed.has(fill))]).filter(([name, kept]) => kept.length !== (slots?.[name]?.length ?? 0));
+}
+/**
+* Whether `key` sits at or inside `ancestor`'s subtree in the stored anatomy — following both the
+* `children` edges and the `slots` entries, since a slotted node nests in render without a child
+* edge. What it guards: a move whose target parent lives inside the moved node
+* would store a cycle no parent names, and everything in it silently vanishes from every surface
+* that walks from the root.
+*/
+function anatomySubtreeContains(anatomy, ancestor, key) {
+	if (ancestor === key) return true;
+	const queue = [ancestor];
+	const seen = new Set(queue);
+	while (queue.length > 0) {
+		const current = queue.shift();
+		if (current === void 0) continue;
+		const node = anatomy[current];
+		const reached = [...node?.children ?? []];
+		for (const fills of Object.values(node?.slots ?? {})) reached.push(...fills);
+		for (const child of reached) {
+			if (child === key) return true;
+			if (seen.has(child)) continue;
+			seen.add(child);
+			queue.push(child);
+		}
+	}
+	return false;
+}
+/** The component body as `element-move` reads it — re-resolved between writes so each step builds
+*  on the previous one's result rather than the pre-move snapshot. */
+function resolveMoveBody(config, path) {
+	return config.resolve("component", path)?.toJSON();
+}
+const AnatomyNode = defineSubEntity({
+	name: "element",
+	label: "Element",
+	labelPlural: "Anatomy",
+	fields: ({ config, parent, key }) => {
+		const body = parent;
+		const shape = {
+			element: nodeElement,
+			visible: visibility.optional().describe("When the node renders: a condition on a prop value (`{ \"$state\": \"<prop>\", \"eq\": <value> }`), an `$or` of them, or a list that must all hold. Omit for a node that always renders."),
+			props: (config ? openBag(config, { cssBehind: false }) : z.record(z.string(), styleValue)).optional().describe("Props passed to what the node renders, keyed by prop or style-property name, as literal values. Content is not set here: a `slot` prop's content lands where a `{ \"element\": \"Slot\", \"props\": { \"name\": \"<prop>\" } }` node sits among a parent's `children` (on the root when there is none), and a `forward` prop (`{ \"type\": \"forward\", \"target\": \"label/children\" }`) routes it into that layer with no node entry. `$state` belongs to `visible` and to an `element` a prop chooses."),
+			text: z.string().optional().describe("Literal text content, for a node that renders a fixed string.")
+		};
+		if (!config || !body) return z.object({
+			...shape,
+			children: z.array(z.string({ error: childKeyError })).optional().describe("The keys of sibling nodes nested here, in render order — never a prop name. A slot prop's content is not listed here: once the slot prop is declared in `props`, its content fills `root` by default, so it needs no anatomy node — a `{ \"element\": \"Slot\", \"props\": { \"name\": \"<prop>\" } }` node listed here only moves that content into a nested layer. The tree is this edge list: the node keyed `root` is the top, and a node no other node names does not render."),
+			slots: z.record(z.string(), z.array(z.string())).optional().describe("Default fills for this node's slot props: the slot prop's name to the keys of the sibling nodes that fill it — node keys, never the prop's own name, and never where the instance's content lands (that fills `root` or a `Slot` node). A node placed by a slot is not also listed in `children`.")
+		});
+		const siblings = Object.keys(body.anatomy ?? {});
+		const siblingKey = siblings.length === 0 ? z.string() : z.string({ error: childKeyError }).check((ctx) => {
+			if (siblings.includes(ctx.value)) return;
+			if (body.props?.[ctx.value]) {
+				ctx.issues.push({
+					code: "custom",
+					input: ctx.value,
+					message: `"${ctx.value}" is a prop, not an anatomy node. Where a slot prop's content lands is a node of its own, \`"${ctx.value}Slot": { "element": "Slot", "props": { "name": "${ctx.value}" } }\`, and its key is what goes here; text a prop supplies to a text layer is routed by declaring the prop \`{ "type": "forward", "target": "<layer>/children" }\`, with nothing listed for it.`
+				});
+				return;
+			}
+			ctx.issues.push({
+				code: "custom",
+				input: ctx.value,
+				message: `anatomy node "${ctx.value}" does not exist yet — create it earlier in the batch. \`children\` and \`slots\` list the keys of sibling nodes in this component's anatomy.`
+			});
+		});
+		return z.strictObject({
+			...shape,
+			children: z.array(siblingKey).optional().describe("The keys of sibling nodes nested here, in render order — never a prop name. A slot prop's content is not listed here: once the slot prop is declared in `props`, its content fills `root` by default, so it needs no anatomy node — a `{ \"element\": \"Slot\", \"props\": { \"name\": \"<prop>\" } }` node listed here only moves that content into a nested layer. The tree is this edge list: the node keyed `root` is the top, and a node no other node names does not render."),
+			slots: z.record(z.string(), z.array(siblingKey)).optional().describe("Default fills for this node's slot props: the slot prop's name to the keys of the sibling nodes that fill it — node keys, never the prop's own name, and never where the instance's content lands (that fills `root` or a `Slot` node). A node placed by a slot is not also listed in `children`.")
+		}, { error: nodeShapeError }).check((ctx) => {
+			const node = ctx.value;
+			const current = key ? body.anatomy?.[key] : void 0;
+			const element = node.element ?? current?.element;
+			if (key !== void 0 && body.layers && key in body.layers) {
+				const rendersLayer = isRef(element) && element.__ref === `layer:${key}`;
+				if (element !== void 0 && !rendersLayer && !spellsLayer(element, key, body.layers[key])) {
+					const spelled = isRef(element) ? `\`${element.__ref}\`` : JSON.stringify(element);
+					ctx.issues.push({
+						code: "custom",
+						input: node,
+						path: ["element"],
+						message: `node "${key}" is keyed like the layer "${key}", so it renders that layer: \`{ "__ref": "layer:${key}" }\`. Written as ${spelled} it would paint the element directly, unstyled, outside every style rule that reaches the layer.`
+					});
+				}
+			}
+			if (typeof node.text === "string" && body.props !== void 0 && node.text in body.props) ctx.issues.push({
+				code: "custom",
+				input: node,
+				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\`.`
+			});
+			for (const [prop, value] of Object.entries(node.props ?? {})) {
+				if (isRef(value) && [
+					"icon",
+					"component",
+					"package",
+					"layer"
+				].includes(kindOf(value.__ref))) {
+					ctx.issues.push({
+						code: "custom",
+						input: value,
+						path: ["props", prop],
+						message: `\`${prop}\` holds a ref to \`${value.__ref}\`, which would reach the element as an object and paint nothing. What a node contains is a node: add \`"${key ?? "<key>"}Glyph": { "element": { "__ref": "${value.__ref}" } }\` to \`anatomy\` and list that key in this node's \`children\`.`
+					});
+					continue;
+				}
+				if (!isPlainObject(value) || !("$state" in value)) 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\`.`
+				});
+			}
+			const slotAnatomyProp = slotAnatomyPropOf({
+				element,
+				props: {
+					...current?.props,
+					...node.props
+				}
+			});
+			if (slotAnatomyProp !== void 0) {
+				if (node.children?.length || node.slots || node.text !== void 0 || node.visible !== void 0 || Object.keys(node.props ?? {}).some((prop) => prop !== "name")) ctx.issues.push({
+					code: "custom",
+					input: node,
+					message: "a Slot node carries nothing of its own — its content arrives from the instance"
+				});
+				const decl = body.props?.[slotAnatomyProp];
+				if (decl && decl.type !== "slot" && !(decl.type === "forward" && decl.target === void 0)) ctx.issues.push({
+					code: "custom",
+					input: node,
+					message: `a Slot node must name a slot prop — "${slotAnatomyProp}" routes no content`
+				});
+				for (const [sibling, member] of Object.entries(body.anatomy ?? {})) {
+					if (sibling === key) continue;
+					if (slotAnatomyPropOf(member) === slotAnatomyProp) {
+						ctx.issues.push({
+							code: "custom",
+							input: node,
+							message: `"${sibling}" already places the content of "${slotAnatomyProp}"`
+						});
+						break;
+					}
+				}
+				return;
+			}
+			const target = nodeComponent(body, element);
+			if (!target) return;
+			const policy = childrenPolicy(config, target);
+			if (policy === "none" && (node.children?.length || node.text)) ctx.issues.push({
+				code: "custom",
+				input: node,
+				message: `"${target}" takes no children — it declares no \`children\` slot, so what this node nests inside it would never render. Declare \`children: { "type": "slot" }\` on "${target}" (with \`"text": true\` for text only), or nest these under a layer whose element takes content.`
+			});
+			if (policy === "text" && node.children?.length) {
+				const layer = isRef(element) && kindOf(element.__ref) === "layer" ? pathOf(element.__ref) : "<layer>";
+				ctx.issues.push({
+					code: "custom",
+					input: node,
+					message: `"${target}" takes text, not nodes, so nothing nested under this node would render. Text a prop supplies is routed into the layer by declaring the prop \`{ "type": "forward", "target": "${layer}/children" }\`, with no node for it; a fixed string is this node's \`text\`.`
+				});
+			}
+		}).overwrite((node) => key !== void 0 && body.layers && key in body.layers && node.element !== void 0 && spellsLayer(node.element, key, body.layers[key]) ? {
+			...node,
+			element: { __ref: `layer:${key}` }
+		} : node);
+	}
+});
+const componentFields = z.strictObject({
+	/**
+	* name → element. **One of them must be called `root`.**
+	*
+	* The root layer is where every prop the config does not model ends up — `id`, `onClick`, `aria-*`,
+	* `data-*`, `ref`. No config can enumerate those, so their destination is the only part that can be
+	* made explicit, and requiring the name is how. Without it the root was whichever layer happened to
+	* be declared first, so reordering `layers` silently moved every un-modelled prop to a different
+	* element — the one implicit thing left in a model whose point is that routing is declared.
+	*
+	* Required for every component, single-layer ones included. A single layer is unambiguous today,
+	* but the day it grows a second layer the addition would first have to rename the existing one —
+	* a restructuring event for what should be an additive change, and one every editing surface would
+	* have to special-case. Naming the root up front makes layer structure uniform: growing a
+	* Component never moves its root, and swapping the root element looks the same everywhere.
+	*
+	* All 100 components in a real system already name one `root`, so this refuses nothing anybody
+	* wrote. It also removes the only gesture it would have blocked — moving a component's root —
+	* which is not a thing we want to be possible.
+	*
+	* Enforced where components are defined (authoring, `create`, `update`, `hydrate`). A per-member
+	* `sub-delete` does not re-validate its owner, so `rootLayerOf` still answers defensively rather
+	* than assuming.
+	*/
+	layers: Layer.check((ctx) => {
+		if (isRef(ctx.value)) return;
+		const names = Object.keys(ctx.value);
+		if (names.includes("root")) return;
+		ctx.issues.push({
+			code: "custom",
+			input: ctx.value,
+			message: `a component's layers must name one \`root\` — it is where every prop the config doesn't model (\`id\`, \`onClick\`, \`data-*\`) is sent, and otherwise that is decided by declaration ORDER. Declared: ${names.join(", ") || "(none)"}.`
+		});
+	}),
+	props: Prop.optional(),
+	/**
+	* Which layers' element props this component also exposes — see {@link Forward}.
+	*
+	* Replaced `inherits`, which named one layer and meant `{ [layer]: '*' }`. That field and its
+	* compatibility reader are gone: nothing mints it, and a stored config still carrying one now
+	* forwards nothing rather than being quietly translated.
+	*/
+	forwards: Forward.optional(),
+	styles: StyleRule.optional(),
+	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."),
+	/**
+	* The source that implements this component — a ref, because the file is an entity the seal owns.
+	*
+	* Kind-typed rather than `orRef(...)`, the way a token override's `on: Modifier` is: only a file
+	* can implement a component. Being a ref is also what makes a borrowed implementation ordinary —
+	* `configFor(ref)` answers with the config that owns it, so its root comes from that config's own
+	* pin, and a chain never has to resolve a bare relative path against the wrong tree.
+	*
+	* Absent for a data-authored component, which has a definition and no render of its own.
+	*/
+	file: File.optional(),
+	/**
+	* The binding inside that file — `export const Card = …`.
+	*
+	* On the component rather than on the file because that is where it belongs: one file may export
+	* two components, and a borrower registers the publisher's `Card` under its own name. Nothing
+	* recovers that binding from a path.
+	*/
+	export: z.string().optional()
+}).check((ctx) => {
+	const body = ctx.value;
+	if (body.forwards || body.file || isRef(body.props)) return;
+	const declared = body.props ?? {};
+	for (const field of ["previewProps", "defaultProps"]) {
+		const values = body[field];
+		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" }\`.`
+		});
+	}
+});
+/**
+* Where a component keeps its bags: each style rule's per-layer bag, each anatomy node's props, and
+* the component's own defaults.
+*
+* The three are the same kind of thing — a set of declarations keyed by the property being set — so
+* they share one walk, and the hooks built from it are the shared ones. Missing a position is not a
+* partial fix but a silent one: the graph reports the positions it knows and says nothing about the
+* rest, which reads as "nothing depends on this".
+*/
+const componentBags = (data) => {
+	const body = data;
+	const out = [];
+	for (const rule of Object.values(body?.styles ?? {})) {
+		const layers = rule?.layers;
+		if (!isPlainRecord(layers)) continue;
+		for (const [layer, bag] of Object.entries(layers)) collectBag(bag, (next) => {
+			layers[layer] = next;
+		}, out);
+	}
+	for (const node of Object.values(body?.anatomy ?? {})) {
+		if (!isPlainRecord(node)) continue;
+		collectBag(node.props, (next) => {
+			node.props = next;
+		}, out);
+	}
+	collectBag(body?.defaultProps, (next) => {
+		if (body) body.defaultProps = next;
+	}, out);
+	return out;
+};
+const ComponentEntity = defineEntity({
+	kind: "component",
+	fields: componentFields,
+	groupFields: z.object({ icon: z.string().optional() }),
+	subEntities: {
+		layers: Layer,
+		props: Prop,
+		forwards: Forward,
+		styles: StyleRule,
+		anatomy: AnatomyNode,
+		defaultProps: Style
+	},
+	computed: { 
+	/**
+	* The prop names an instance may fill through a spec element's `slots` field — every prop that
+	* routes content: a `slot`, or a `forward` whose far end takes content. Resolved over the
+	* inheritance chain, since an inherited slot is as fillable as a declared one. This is the
+	* `slots: string[]` json-render's catalog metadata declares per component, computed here so the
+	* emitted catalog, the validator, and every picker read one answer.
+	*/
+slots: ({ config, path, member }) => {
+		const layers = member.layers;
+		const names = [];
+		for (const [name, decl] of Object.entries(resolveComponentProps(config, path))) {
+			const body = decl;
+			if (!body) continue;
+			if (body.type === "slot" || body.type === "forward" && routesContent(config, layers, body)) names.push(name);
+		}
+		return names;
+	} },
+	nameEdges: bagNameEdges(componentBags),
+	styleBags: componentBags,
+	rewriteName: bagRewriteName(componentBags),
+	schemas: {
+		create: {
+			data: componentFields,
+			description: "Create a component at a new qualified `path`. 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.",
+			example: ({ config }) => {
+				const path = freeExamplePath(config);
+				const composed = composedCreateExample(config, path);
+				if (composed) return composed;
+				return {
+					path,
+					data: {
+						layers: {
+							root: "button",
+							icon: "span"
+						},
+						props: {
+							icon: {
+								type: "forward",
+								target: "icon/children"
+							},
+							children: {
+								type: "slot",
+								text: true
+							}
+						},
+						anatomy: {
+							icon: {
+								element: { __ref: "layer:icon" },
+								visible: { $state: "icon" }
+							},
+							content: {
+								element: "Slot",
+								props: { name: "children" }
+							},
+							root: {
+								element: { __ref: "layer:root" },
+								children: ["icon", "content"]
+							}
+						},
+						previewProps: { children: "Example" }
+					}
+				};
+			}
+		},
+		"sub-create/anatomy": { description: "Add one anatomy node (`key` + `data`) to a component. In a batch, create child nodes before a parent whose `children` or `slots` names them; each referenced node must already exist when this operation runs." },
+		"sub-create/props": { description: "Declare a prop this component owns (`key` + `data`): a `variant`, a `slot`, a `styleProperty` or `composite` on a primitive, a `forward` routing this prop into a layer's (`{ \"type\": \"forward\", \"target\": \"<layer>/<prop>\" }`), or `null` to drop a forwarded prop from the surface. A prop one of its layers already exposes — `width` on a root that renders `Box` — is not declared here; `sub-create/forwards` exposes it at the top level." },
+		"sub-create/forwards": {
+			description: FORWARDS_DESCRIPTION,
+			example: ({ config }) => forwardsCreateExample(config)
+		},
+		"sub-upsert/forwards": { description: `Set what one layer forwards, added when absent and replaced whole when present. ${FORWARDS_DESCRIPTION}` },
+		"sub-update/forwards": { description: `Replace what one layer forwards: the member is \`'*'\` or a list, so \`data\` is the whole new value. ${FORWARDS_DESCRIPTION}` },
+		/**
+		* Add an element to a composition — a layer and the node that targets it, together.
+		*
+		* Two writes, one op, because either alone is broken: a node whose element is a component ref
+		* directly can never be styled (`styles` keys on layer names, and it has none), and a layer no
+		* node places renders nowhere. Making it one op is also what keeps the parent's `children` from
+		* being left dangling between two patches.
+		*
+		* That the new element gets a layer is the whole difference between a read component and an
+		* authored one. A render's inline glyph stays unnamed because the source never named it; a thing
+		* a person adds is added in order to be styled.
+		*
+		* The layer name is what makes this survive a second platform: native replaces `layers` (a `div`
+		* becomes a `View`) and inherits the styles and the structure, because both address the name
+		* rather than the element.
+		*/
+		"element-insert": {
+			input: z.object({
+				path: pathInput("component"),
+				/** The layer name to insert under. Optional: the entity owns the namespace, so it mints a
+				*  free one ({@link freeLayerKey}) when the caller doesn't care what it is called. */
+				key: z.string().optional(),
+				data: z.object({
+					element: z.union([z.string(), refSchema]).default("div"),
+					parent: z.string().optional(),
+					index: z.number().optional(),
+					props: z.record(z.string(), z.unknown()).optional(),
+					/**
+					* Fill the parent's slot with the new element, by name of the parent's prop.
+					*
+					* A slot fill is one user action — "put a Text in the label slot" — and it is two writes:
+					* the element has to exist, and the host's `slots` entry has to point at it. Splitting them
+					* would be two rows in the changes panel and two things to undo for one gesture, which is
+					* the same reason this op already writes the layer and the anatomy node together rather
+					* than making a caller do both.
+					*
+					* The entry is json-render's own `slots` field, which its renderer resolves itself — so
+					* this writes a mechanism the renderer has, rather than inventing one.
+					*/
+					slotProp: z.string().optional(),
+					/**
+					* A condition on the new node — json-render's `visible` grammar, or the flat
+					* `{ prop: value }` an editor collects, which is compiled to it.
+					*
+					* Typed rather than `z.unknown()`, which is the whole fix: an untyped input accepted the
+					* flat form at the op boundary and failed two writes later inside the anatomy create, so
+					* every variant-scoped fill was refused while its draft row still displayed it.
+					*/
+					visible: visibility.optional(),
+					/** Text content for the new element — a declared field of the stored node the op had no
+					*  input for, so an inserted element could not arrive with its text. */
+					text: z.string().optional(),
+					/** The new element's own children, by key — the same edge list the anatomy node stores. */
+					children: z.array(z.string()).optional(),
+					/** The new element's own slot fills — json-render's native grammar, keys into `nodes`. */
+					slots: z.record(z.string(), z.array(z.string())).optional(),
+					/** The subtree that lands with it: every descendant, keyed, in the stored shape. See
+					*  {@link InsertedNode}. */
+					nodes: z.record(z.string(), insertedNode).optional(),
+					/**
+					* The same subtree in the caller's own key space — `root` names which of `elements` is the
+					* one being inserted, and every key is grafted onto the component's namespace by
+					* {@link graftKey}.
+					*
+					* The form a caller actually holds. Without it, Studio re-keyed the subtree itself, hoisted
+					* its root out into the flat fields and renamed `type` to `element` before every insert —
+					* the graft convention living at the caller, where the reader that inverts it could drift
+					* from it. Mutually exclusive with `key`/`element`/`props`/`children`/`nodes`.
+					*/
+					subtree: z.object({
+						root: z.string(),
+						elements: z.record(z.string(), insertedNode)
+					}).optional()
+				}).prefault({})
+			}),
+			readOnly: false,
+			label: "Add element",
+			description: "Add an element to a component: creates the LAYER it is styled through and the anatomy node that places it, under `parent`.",
+			scope: "item",
+			creates: true,
+			title: (entity) => `Add ${entity} element`,
+			handler: (input, config) => {
+				const payload = input.data ?? {};
+				const path = String(input.path);
+				const parent = payload.parent ? String(payload.parent) : void 0;
+				const key = input.key ? String(input.key) : freeLayerKey(config, path, "el");
+				const given = payload.subtree;
+				let element = payload.element;
+				let props = payload.props;
+				let text = payload.text;
+				let visible = payload.visible;
+				let ownChildren = payload.children;
+				let ownSlots = payload.slots;
+				let nodes = payload.nodes ?? {};
+				if (given) {
+					const local = (k) => k === given.root ? key : graftKey(key, k);
+					const localSlots = (slots) => slots ? Object.fromEntries(Object.entries(slots).map(([name, fills]) => [name, fills.map(local)])) : void 0;
+					const rootNode = given.elements[given.root];
+					element = rootNode?.element ?? element;
+					props = rootNode?.props ?? props;
+					text = rootNode?.text ?? text;
+					visible = rootNode?.visible ?? visible;
+					ownChildren = rootNode?.children?.map(local) ?? ownChildren;
+					ownSlots = localSlots(rootNode?.slots) ?? ownSlots;
+					nodes = Object.fromEntries(Object.entries(given.elements).filter(([k]) => k !== given.root).map(([k, node]) => [local(k), {
+						...node,
+						children: node.children?.map(local),
+						slots: localSlots(node.slots)
+					}]));
+				}
+				let next = config.apply({
+					kind: "component",
+					operation: "sub-create",
+					path,
+					field: "layers",
+					key,
+					data: asElementRef(config, element)
+				}).apply({
+					kind: "component",
+					operation: "sub-create",
+					path,
+					field: "anatomy",
+					key,
+					data: {
+						element: layerRef(key),
+						...props ? { props } : {},
+						...visible !== void 0 ? { visible } : {},
+						...text !== void 0 ? { text } : {}
+					}
+				});
+				next = insertSubtree(next, path, nodes);
+				if (ownChildren?.length || ownSlots) next = next.apply({
+					kind: "component",
+					operation: "sub-update",
+					path,
+					field: "anatomy",
+					key,
+					data: {
+						...ownChildren?.length ? { children: ownChildren } : {},
+						...ownSlots ? { slots: ownSlots } : {}
+					}
+				});
+				if (!parent) return next;
+				let body = next.resolve("component", path)?.toJSON();
+				if (!body?.anatomy?.[parent] && body?.layers && parent in body.layers) {
+					next = next.apply({
+						kind: "component",
+						operation: "sub-create",
+						path,
+						field: "anatomy",
+						key: parent,
+						data: { element: layerRef(parent) }
+					});
+					body = next.resolve("component", path)?.toJSON();
+				}
+				const throughSlot = Boolean(payload.slotProp);
+				const siblings = [...body?.anatomy?.[parent]?.children ?? []];
+				if (!throughSlot) {
+					const at = typeof payload.index === "number" ? payload.index : siblings.length;
+					siblings.splice(at, 0, key);
+				}
+				const slotProp = payload.slotProp ? String(payload.slotProp) : void 0;
+				const fill = slotProp ? slotFillHostWrites({
+					config: next,
+					path,
+					parent,
+					key,
+					slotProp,
+					node: body?.anatomy?.[parent],
+					layers: body?.layers
+				}) : void 0;
+				return next.apply({
+					kind: "component",
+					operation: "sub-update",
+					path,
+					field: "anatomy",
+					key: parent,
+					data: {
+						...throughSlot ? {} : { children: siblings },
+						...fill ? { slots: fill.slots } : {},
+						...fill?.visible !== void 0 ? { visible: fill.visible } : {}
+					}
+				});
+			}
+		},
+		/**
+		* Remove an element from a composition — the node, its layer, and everything that named it.
+		*
+		* A custom op for the same reason `element-insert` is: it writes more than one thing and either
+		* half alone is broken. `sub-delete/layers` drops the layer and leaves the anatomy node holding
+		* a dangling `layer:<key>` ref, its parent's `children` still naming it, and every style rule
+		* still carrying a bag for a layer that no longer exists. `sub-delete/anatomy` leaves the parent
+		* edge — a value the stored `children` enum would now refuse on the next write to that node.
+		*
+		* The rule bags are the part `orphans` cannot express: a rule targeting a deleted layer is not
+		* itself orphaned (it has other layers to style), so what has to go is the layer's entry inside
+		* each rule. That is a delta, which is what the merge verb is for — the rule is left alone when
+		* it still styles something and pruned by the caller's own `sub-delete` when it doesn't.
+		*/
+		"element-delete": {
+			input: z.object({
+				path: pathInput("component"),
+				key: z.string(),
+				data: z.object({ 
+				/** Remove everything under it too. Default true: a node's children are placed by it and
+				*  nothing else, so leaving them would strand a subtree no parent names. */
+subtree: z.boolean().default(true) }).optional()
+			}),
+			readOnly: false,
+			label: "Remove element",
+			description: "Remove an element from a component: its anatomy node, the layer it is styled through, its subtree, every parent edge naming it, and its entry in every style rule.",
+			scope: "item",
+			approval: "destructive",
+			title: (entity) => `Remove ${entity} element`,
+			handler: (input, config) => {
+				const payload = input.data ?? {};
+				const path = String(input.path);
+				const key = String(input.key);
+				const body = config.resolve("component", path)?.toJSON();
+				const anatomy = body?.anatomy ?? {};
+				const doomed = new Set([key]);
+				if (payload.subtree !== false) {
+					const queue = [key];
+					while (queue.length > 0) {
+						const current = queue.shift();
+						if (current === void 0) continue;
+						for (const child of anatomy[current]?.children ?? []) {
+							if (doomed.has(child)) continue;
+							doomed.add(child);
+							queue.push(child);
+						}
+					}
+				}
+				const stillBound = /* @__PURE__ */ new Set();
+				for (const [name, node] of Object.entries(anatomy)) {
+					if (doomed.has(name)) continue;
+					const bound = layerRefTarget(node.element);
+					if (bound !== void 0) stillBound.add(bound);
+				}
+				const layersGoing = new Set([...doomed].filter((name) => body?.layers !== void 0 && name in body.layers && !stillBound.has(name)));
+				let next = config;
+				for (const [name, node] of Object.entries(anatomy)) {
+					if (doomed.has(name)) continue;
+					const keptChildren = (node.children ?? []).filter((child) => !doomed.has(child));
+					const staleSlots = staleSlotEntries(node.slots, doomed);
+					if (keptChildren.length === (node.children ?? []).length && staleSlots.length === 0) continue;
+					next = next.apply({
+						kind: "component",
+						operation: "sub-update",
+						path,
+						field: "anatomy",
+						key: name,
+						data: {
+							...keptChildren.length !== (node.children ?? []).length ? { children: keptChildren } : {},
+							...Object.fromEntries(staleSlots.map(([slot, kept]) => [`slots.${slot}`, kept.length ? kept : null]))
+						}
+					});
+				}
+				for (const [condition, rule] of Object.entries(body?.styles ?? {})) {
+					const targeted = Object.keys(rule.layers ?? {}).filter((layer) => layersGoing.has(layer));
+					if (targeted.length === 0) continue;
+					next = next.apply({
+						kind: "component",
+						operation: "sub-update",
+						path,
+						field: "styles",
+						key: condition,
+						data: Object.fromEntries(targeted.map((layer) => [`layers.${layer}`, null]))
+					});
+				}
+				for (const name of doomed) {
+					if (anatomy[name]) next = next.apply({
+						kind: "component",
+						operation: "sub-delete",
+						path,
+						field: "anatomy",
+						key: name
+					});
+					if (layersGoing.has(name)) next = next.apply({
+						kind: "component",
+						operation: "sub-delete",
+						path,
+						field: "layers",
+						key: name
+					});
+				}
+				return next;
+			}
+		},
+		/**
+		* Move a node to a different parent, or to a different place under the same one.
+		*
+		* Sibling order lives in a parent's `children`, so a move is two updates — one per parent — and
+		* both have to land or the node is in neither list or in both.
+		*
+		* A node can also be held by a slot rather than a child edge (`slots: { icon: [key] }`),
+		* and a move treats both as the home being left: every child edge naming the key is detached,
+		* and every stale slot entry naming it is cleared, whichever new home the move names. With
+		* `slotProp` the new home is the parent's slot instead of its `children` — the same statement
+		* `element-insert` makes about a new node, made about one that already exists, so the moved
+		* element keeps its key, props, styles and subtree.
+		*/
+		"element-move": {
+			input: z.object({
+				path: pathInput("component"),
+				key: z.string(),
+				data: z.object({
+					parent: z.string().default("root"),
+					index: z.number().optional(),
+					/** Fill the parent's slot with the moved node — by name of the parent's prop — instead of
+					*  splicing it into `children`. `index` is inert when set: a slot holds one ref, not a
+					*  position. */
+					slotProp: z.string().optional()
+				}).prefault({})
+			}),
+			readOnly: false,
+			label: "Move element",
+			description: "Move a component's anatomy node under a different parent, to a different position under the same one, or — with `slotProp` — into a parent's slot.",
+			scope: "item",
+			approval: "reference-change",
+			title: (entity) => `Move ${entity} element`,
+			handler: (input, config) => {
+				const payload = input.data ?? {};
+				const path = String(input.path);
+				const key = String(input.key);
+				const parent = String(payload.parent);
+				const slotProp = payload.slotProp ? String(payload.slotProp) : void 0;
+				const body = resolveMoveBody(config, path);
+				const anatomy = body?.anatomy ?? {};
+				const isKnown = (name) => Boolean(anatomy[name] || body?.layers && name in body.layers);
+				if (!isKnown(key)) reject("NOT_FOUND", `"${path}" has no element "${key}" to move.`);
+				if (!isKnown(parent)) reject("NOT_FOUND", `"${path}" has no element "${parent}" to move under.`);
+				if (anatomySubtreeContains(anatomy, key, parent)) rejectData(`Moving "${key}" under "${parent}" would nest it inside itself.`, ["parent"]);
+				let next = config;
+				for (const [name, node] of Object.entries(anatomy)) {
+					const children = !(name === parent && !slotProp) && node.children?.includes(key) ? node.children.filter((c) => c !== key) : void 0;
+					const staleSlots = staleSlotEntries(node.slots, new Set([key]));
+					if (children === void 0 && staleSlots.length === 0) continue;
+					next = next.apply({
+						kind: "component",
+						operation: "sub-update",
+						path,
+						field: "anatomy",
+						key: name,
+						data: {
+							...children !== void 0 ? { children } : {},
+							...Object.fromEntries(staleSlots.map(([slot, kept]) => [`slots.${slot}`, kept.length ? kept : null]))
+						}
+					});
+				}
+				let moved = next === config ? body : resolveMoveBody(next, path);
+				if (!slotProp) {
+					const siblings = [...(moved?.anatomy?.[parent]?.children ?? []).filter((c) => c !== key)];
+					const at = typeof payload.index === "number" ? payload.index : siblings.length;
+					siblings.splice(at, 0, key);
+					return next.apply({
+						kind: "component",
+						operation: "sub-update",
+						path,
+						field: "anatomy",
+						key: parent,
+						data: { children: siblings }
+					});
+				}
+				if (!moved?.anatomy?.[parent] && moved?.layers && parent in moved.layers) {
+					next = next.apply({
+						kind: "component",
+						operation: "sub-create",
+						path,
+						field: "anatomy",
+						key: parent,
+						data: { element: layerRef(parent) }
+					});
+					moved = resolveMoveBody(next, path);
+				}
+				const occupant = moved?.anatomy?.[parent]?.slots?.[slotProp];
+				if (occupant?.length) reject("ALREADY_EXISTS", `"${parent}" already fills \`${slotProp}\` with "${occupant[0]}" — move that element out first.`);
+				const fill = slotFillHostWrites({
+					config: next,
+					path,
+					parent,
+					key,
+					slotProp,
+					node: moved?.anatomy?.[parent],
+					layers: moved?.layers
+				});
+				return next.apply({
+					kind: "component",
+					operation: "sub-update",
+					path,
+					field: "anatomy",
+					key: parent,
+					data: {
+						slots: fill.slots,
+						...fill.visible !== void 0 ? { visible: fill.visible } : {}
+					}
+				});
+			}
+		},
+		validate: {
+			input: z.object({
+				path: pathInput("component"),
+				data: z.object({ props: z.record(z.string(), z.unknown()) })
+			}),
+			readOnly: true,
+			label: "Validate props",
+			description: "Check a bag of prop VALUES against a component — rejects unknown props and out-of-domain values.",
+			scope: "item",
+			title: (entity) => `Validate ${entity} props`,
+			example: ({ config, path }) => ({
+				path,
+				data: { props: exampleProps(config, path) }
+			}),
+			handler: (input, config) => validateComponentProps(config, String(input.path), input.data.props ?? {})
+		}
+	}
+});
+const baseComponentRef = ComponentEntity.ref.bind(ComponentEntity);
+/** Component refs add the source-only authoring steps to the generic ref-extension value. All of them
+* are non-enumerable: evaluating the config produces the same small wire marker that a hydrated config
+* receives, while the build independently reads `.render(fn)` from this file. */
+function componentRef(path) {
+	const base = baseComponentRef(path);
+	const value = { __ref: base.__ref };
+	/**
+	* One extension value, with its authoring steps attached.
+	*
+	* `render` is a no-op that hands the value back — the build reads the callback out of this file
+	* rather than from the stored data, which is why it is source-only. `styles` is not a no-op: it
+	* folds the rules into the delta and re-extends, so however many steps a chain has, the wire form
+	* stays one `{ __ref, extend }`.
+	*/
+	const step = (delta) => {
+		const extended = base.extend(delta);
+		Object.defineProperty(extended, "render", {
+			enumerable: false,
+			configurable: false,
+			value: () => extended
+		});
+		Object.defineProperty(extended, "styles", {
+			enumerable: false,
+			configurable: false,
+			value: (rules) => {
+				const styles = {};
+				for (const rule of rules) styles[canonicalWhen(rule.when)] = {
+					when: rule.when ?? null,
+					layers: rule.layers
+				};
+				return step({
+					...delta,
+					styles
+				});
+			}
+		});
+		return extended;
+	};
+	Object.defineProperty(value, "extend", {
+		enumerable: false,
+		configurable: false,
+		value: (delta) => step(delta)
+	});
+	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 });
+/** 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
+*  (`name: Icon.ref('phosphor')`) owns nothing, but its leaves are exactly what an example should show. */
+function exampleProps(config, componentPath) {
+	const props = (config.resolve("component", componentPath)?.toJSON())?.props ?? {};
+	for (const [name, decl] of Object.entries(props)) {
+		if (decl?.type !== "variant") continue;
+		const leaves = propValueDomain(config, decl)?.leaves ?? [];
+		if (leaves.length > 0) return { [name]: leaves[0] };
+	}
+	return {};
+}
+//#endregion
+export { Component, canonicalWhen, forwardedNames, layerRef, ownValues, ownsItsValues, valueRef };