@yahoo/uds-create-config 2.45.0 → 3.0.1

package/dist/spec/collapse-text-labels.js

@@ -1,3 +1,6 @@
+import { kindOf, pathOf } from "../framework/utils/refs.js";
+import { childrenPolicy } from "../entities/system/element.js";
+import { resolveComponentProps } from "../framework/projections.js";
 //#region src/spec/collapse-text-labels.ts
 /** Child element keys an element references through its `children` array. */
 function childKeysOf(element) {
@@ -7,20 +10,14 @@ function childKeysOf(element) {
 /**
 * Count every parent→child edge in the spec so a wrapped Text node is only
 * deleted when nothing *else* still points at it. Covers `children` arrays and
-* top-level `$slot` prop refs (the two ways the renderer reaches an element).
+* `slots` entries (the two ways the renderer reaches an element).
 */
 function countReferences(elements) {
 	const counts = /* @__PURE__ */ new Map();
 	const bump = (key) => counts.set(key, (counts.get(key) ?? 0) + 1);
 	for (const element of Object.values(elements)) {
 		for (const child of childKeysOf(element)) bump(child);
-		if (!element.props) continue;
-		for (const value of Object.values(element.props)) {
-			if (typeof value !== "object" || value === null || !("$slot" in value)) continue;
-			const slot = value.$slot;
-			const refs = Array.isArray(slot) ? slot : [slot];
-			for (const ref of refs) if (typeof ref === "string") bump(ref);
-		}
+		for (const fills of Object.values(element.slots ?? {})) for (const ref of fills) bump(ref);
 	}
 	return counts;
 }
@@ -41,21 +38,32 @@ function bareLabelText(element) {
 	return text;
 }
 /**
+* The component a spec `type` names, or `undefined` when it names something else.
+*
+* A spec type is `<kind>:<path>` (`component:Badge`), and only a component has children this can
+* reason about — a `package:` member is somebody else's export, whose children are its own business,
+* and an intrinsic tag (`'div'`) carries no kind at all and isn't in the config. Asking `resolve`
+* with an unstripped marker finds nothing; asking it with the path of a NON-component would find a
+* component that merely shares the name.
+*/
+function componentPath(type) {
+	const kind = kindOf(type);
+	if (kind !== type && kind !== "component") return void 0;
+	return pathOf(type);
+}
+/**
 * Hoisting is only lossless when the wrapped child renders *nothing but* its
-* text — a Text-like leaf whose `children` binding renders directly (a scalar
+* text — a Text-like leaf whose `children` forward renders directly (a scalar
 * marker or an open/root slot). A component that forwards `children` into a
-* named layer (Badge's `slot('text/children')`) has chrome around the label,
+* named layer (Badge's `{ type: 'forward', target: 'text/children' }`) has chrome around the label,
 * so collapsing it would silently delete that chrome even when the element
 * carries no other props. An unresolvable child type stays collapsible — the
 * structural bare-leaf gate is all we can check, and generators emit known
 * types anyway.
 */
 function childCollapsible(child, config) {
-	const component = config.getComponent(child.type);
-	if (!component) return true;
-	const children = component.derived.prop?.("children");
-	if (!children) return true;
-	return children.kind !== "slot" || children.layer === void 0;
+	const path = componentPath(child.type);
+	return (path ? resolveComponentProps(config, path).children : void 0)?.type !== "forward";
 }
 /**
 * Return a copy of `spec` with every redundant Text-wrapped label folded into a
@@ -69,10 +77,9 @@ function collapseWrappedTextLabels(spec, config) {
 	const rewrites = /* @__PURE__ */ new Map();
 	const toDelete = /* @__PURE__ */ new Set();
 	for (const [key, element] of Object.entries(spec.elements)) {
-		const component = config.getComponent(element.type);
-		if (!component) continue;
-		const { acceptsChildren, acceptsChildNodes } = component.derived;
-		if (!acceptsChildren || acceptsChildNodes) continue;
+		const path = componentPath(element.type);
+		if (!path) continue;
+		if (childrenPolicy(config, path) !== "text") continue;
 		const childKeys = childKeysOf(element);
 		if (childKeys.length !== 1) continue;
 		const existingLabel = element.props?.children;

package/dist/spec/empty-node-slots.d.ts

@@ -1,21 +1,41 @@
-import { Component } from "../Component.js";
+import { Config } from "../framework/Config.js";
+import { SlotTarget } from "../framework/render-spec.js";
 import { Spec } from "@json-render/core";
 
 //#region src/spec/empty-node-slots.d.ts
+/**
+ * The component's named node slots — `slotTargetsOf` minus text slots and
+ * minus `children`. `children` is the open content hole every container has
+ * (a structural insert, not a named fill), and a text slot is an inline-edit
+ * surface, not a place a node goes.
+ *
+ * Text-ness is checked on BOTH ends of the route: the component's own decl
+ * (`title: { type: 'slot', text: true }`) and the prop the route lands on — a
+ * `forward` into `Text#children` is typed in place, not filled with a dropped
+ * node, and only the far end says so. A route whose host component doesn't
+ * declare the landing prop is dropped too: the fill op would refuse it, so it
+ * must never be offered as a target.
+ */
+declare function namedSlotTargets(config: Config, componentPath: string): SlotTarget[];
 /**
  * Materialize every EMPTY layer-bound node slot of `spec`'s root as a `Slot`
- * element wired through a `$slot` ref, so an unfilled slot is a stable element
- * in the spec rather than an absent prop — the studio canvas needs a drop
- * target, the layers panel a row, and the inspector an "Empty" state. Slots the
- * spec already fills are left as-is. Returns `spec` unchanged when there's
- * nothing to inject (no node slots, or all of them filled).
+ * element named in the root's `slots` record, so an unfilled slot is a stable
+ * element in the spec rather than an absent entry — the studio canvas needs a
+ * drop target, the layers panel a row, and the inspector an "Empty" state.
+ * Slots the spec already fills are left as-is. Returns `spec` unchanged when
+ * there's nothing to inject (no node slots, or all of them filled).
+ *
+ * `slotNames` is the component's named node slots — {@link namedSlotTargets}'
+ * `from` names. Callers pass names rather than a props record because which
+ * props are node slots is route-dependent (a `forward` into a text prop is
+ * not one), and only the config can answer that.
  */
-declare function withEmptyNodeSlots(spec: Spec, component: Pick<Component, 'derived'>): Spec;
+declare function withEmptyNodeSlots(spec: Spec, slotNames: readonly string[]): Spec;
 /**
  * Predicate over a spec element's `type`: does it name a component that forwards
  * renderable **node** children (a valid drop-*into* target)? This is the single
  * source of truth for "is a container" — studio builds it from the live Config
- * (`buildAcceptsChildren` → `Component.derived.acceptsChildNodes`), which is
+ * (`buildClassifyChildNodes` → `childrenPolicy`), which is
  * namespace-aware, so both bare (`Box`) and namespaced (`uds:Box`) spec types
  * resolve, along with any custom child-accepting component.
  */
@@ -27,26 +47,25 @@ type AcceptsChildNodes = (type: string | undefined) => boolean;
  */
 type ChildNodesClassification = true | false | undefined;
 type ClassifyChildNodes = (type: string | undefined) => ChildNodesClassification;
-/** The slice of a `Config` the predicate needs — structural so this stays
- *  decoupled from the `Config` class (and free of an import cycle). */
-interface ComponentResolver {
-  getComponent(type: string): {
-    derived: {
-      acceptsChildNodes: boolean;
-    };
-  } | undefined;
-}
 /**
  * Build the single, namespace-aware {@link AcceptsChildNodes} predicate from a
  * live config: an element type is a node container iff its resolved component's
- * `derived.acceptsChildNodes` is true. `getComponent` resolves both bare (`Box`)
- * and namespaced (`uds:Box`) types, so the predicate matches whichever form the
- * spec carries. Returns a constant `false` when there's no config (nothing can
+ * it takes child NODES. `Component.get` resolves a path or the ref a spec carries, so the predicate
+ * matches whichever form is in hand. Returns a constant `false` when there's no config (nothing can
  * be classified yet) — callers thread this into slot injection and drop
  * hit-testing so every surface agrees on what accepts children.
  */
-declare function buildAcceptsChildNodes(config: ComponentResolver | null | undefined): AcceptsChildNodes;
-declare function buildClassifyChildNodes(config: ComponentResolver | null | undefined): ClassifyChildNodes;
+declare function buildAcceptsChildNodes(config: Config | null | undefined): AcceptsChildNodes;
+/**
+ * Whether an element type takes child NODES — `true`, `false`, or `undefined` when nothing can say.
+ *
+ * `childrenPolicy` is the answer, and it is the same answer the spec validator, the emitted module and
+ * the anatomy schema use: a void element takes nothing, a text slot takes a string, and everything
+ * else takes nodes. v1 asked a flag stamped on each component at registration (`acceptsChildNodes`),
+ * which is the same fact computed once and stored — so it could be stale, and only registration could
+ * write it.
+ */
+declare function buildClassifyChildNodes(config: Config | null | undefined): ClassifyChildNodes;
 /**
  * Pin a persistent trailing `Slot` as the last child of every container element
  * in `spec` (tree-wide), so a container always exposes an insertion drop target
@@ -64,8 +83,8 @@ declare function buildClassifyChildNodes(config: ComponentResolver | null | unde
 declare function withContainerChildSlots(spec: Spec, acceptsChildNodes: AcceptsChildNodes): Spec;
 /**
  * Compose both slot injections into the canvas's render view: layer-bound node
- * slots on a component instance's root (`withEmptyNodeSlots`, needs the
- * component definition) plus a trailing insertion `Slot` in every container,
+ * slots on a component instance's root (`withEmptyNodeSlots`, keyed by the
+ * component's `namedSlotTargets`) plus a trailing insertion `Slot` in every container,
  * tree-wide (`withContainerChildSlots`). This is the spec the studio canvas
  * renders so empty slots show as drop targets — it is NEVER persisted. Stored
  * specs stay slot-free; `stripInjectedSlots` is the inverse, applied at every
@@ -73,20 +92,23 @@ declare function withContainerChildSlots(spec: Spec, acceptsChildNodes: AcceptsC
  * same reference when there's nothing to add, so this is cheap and idempotent —
  * re-running on an already-slotted spec adds nothing.
  */
-declare function withRenderSlots(spec: Spec, component: Pick<Component, 'derived'> | null | undefined, acceptsChildNodes: AcceptsChildNodes): Spec;
+declare function withRenderSlots(spec: Spec, slotNames: readonly string[] | null | undefined, acceptsChildNodes: AcceptsChildNodes): Spec;
 /**
  * Inverse of `withEmptyNodeSlots` + `withContainerChildSlots`: drop every
  * injected `Slot` element and scrub its references, so a spec carries no
- * editing scaffolding. A `Slot`-typed element is ALWAYS an injected content
- * hole (json-render's placeholder), never authored content — both injectors
- * emit `type: 'Slot'` — so removing all of them and their references is the
- * exact reversal: a trailing `children` Slot drops out of its parent's
+ * editing scaffolding. An injected `Slot` is render-only — both injectors
+ * emit `type: 'Slot'` with no `shown` — so removing them and their references
+ * is the exact reversal: a trailing `children` Slot drops out of its parent's
  * `children`, and an empty node slot drops both its `Slot` element and the
- * `{ $slot }` prop that pointed at it (a FILLED slot points at a real element,
- * which is not `Slot`-typed, so it survives). Use at export/serialization
- * boundaries (e.g. clipboard); the canvas re-injects fresh drop targets on
- * load. Idempotent: returns `spec` unchanged when there are no `Slot` elements.
+ * `slots` entry that named it (a FILLED slot names a real element,
+ * which is not `Slot`-typed, so it survives). A `shown: true` Slot is NOT
+ * scaffolding: it is the user-enabled Placeholder `setNodeSlot` deliberately
+ * persists, so it survives the strip — without the exemption, a slot fill
+ * (which strips the whole spec before persisting) would silently delete a
+ * sibling slot's placeholder. Use at export/serialization boundaries (e.g.
+ * clipboard); the canvas re-injects fresh drop targets on load. Idempotent:
+ * returns `spec` unchanged when there are no strippable `Slot` elements.
  */
 declare function stripInjectedSlots(spec: Spec): Spec;
 //#endregion
-export { AcceptsChildNodes, ChildNodesClassification, ClassifyChildNodes, buildAcceptsChildNodes, buildClassifyChildNodes, stripInjectedSlots, withContainerChildSlots, withEmptyNodeSlots, withRenderSlots };
+export { AcceptsChildNodes, ChildNodesClassification, ClassifyChildNodes, buildAcceptsChildNodes, buildClassifyChildNodes, namedSlotTargets, stripInjectedSlots, withContainerChildSlots, withEmptyNodeSlots, withRenderSlots };

package/dist/spec/empty-node-slots.js

@@ -1,40 +1,71 @@
+import { pathOf } from "../framework/utils/refs.js";
+import { childrenPolicy } from "../entities/system/element.js";
+import { resolveComponentProps } from "../framework/projections.js";
+import { slotTargetsOf } from "../framework/render-spec.js";
+import { Component } from "../entities/system/Component.js";
 //#region src/spec/empty-node-slots.ts
 const SLOT_TYPE = "Slot";
 /**
-* Layer-bound single-node slots — Button `startIcon`/`endIcon`, Item `media`:
-* a `slot()` bound to a named layer whose value is a renderable node. Open
-* `children` slots (no layer) are authored as child layers, and text/scalar
-* slots as inputs, so neither is materialized here.
+* The component's named node slots — `slotTargetsOf` minus text slots and
+* minus `children`. `children` is the open content hole every container has
+* (a structural insert, not a named fill), and a text slot is an inline-edit
+* surface, not a place a node goes.
+*
+* Text-ness is checked on BOTH ends of the route: the component's own decl
+* (`title: { type: 'slot', text: true }`) and the prop the route lands on — a
+* `forward` into `Text#children` is typed in place, not filled with a dropped
+* node, and only the far end says so. A route whose host component doesn't
+* declare the landing prop is dropped too: the fill op would refuse it, so it
+* must never be offered as a target.
 */
-function nodeSlotNames(component) {
-	return component.derived.props.filter((p) => p.kind === "slot" && p.layer !== void 0 && p.valueType === "ReactNode" && p.authoredType !== "string").map((p) => p.name);
+function namedSlotTargets(config, componentPath) {
+	const component = Component.get(config, componentPath);
+	const props = component?.props;
+	const layers = component?.layers;
+	return slotTargetsOf(config, componentPath).filter((target) => {
+		if (target.from === "children") return false;
+		const declared = props?.[target.from];
+		if (declared?.type === "slot" && declared.text === true) return false;
+		const hostRef = layers?.[target.layer];
+		if (!hostRef || !Component.get(config, hostRef)) return true;
+		const into = resolveComponentProps(config.configFor(hostRef) ?? config, pathOf(hostRef))[target.into];
+		if (!into) return false;
+		return !(into.type === "slot" && into.text === true);
+	});
 }
 /**
 * Materialize every EMPTY layer-bound node slot of `spec`'s root as a `Slot`
-* element wired through a `$slot` ref, so an unfilled slot is a stable element
-* in the spec rather than an absent prop — the studio canvas needs a drop
-* target, the layers panel a row, and the inspector an "Empty" state. Slots the
-* spec already fills are left as-is. Returns `spec` unchanged when there's
-* nothing to inject (no node slots, or all of them filled).
+* element named in the root's `slots` record, so an unfilled slot is a stable
+* element in the spec rather than an absent entry — the studio canvas needs a
+* drop target, the layers panel a row, and the inspector an "Empty" state.
+* Slots the spec already fills are left as-is. Returns `spec` unchanged when
+* there's nothing to inject (no node slots, or all of them filled).
+*
+* `slotNames` is the component's named node slots — {@link namedSlotTargets}'
+* `from` names. Callers pass names rather than a props record because which
+* props are node slots is route-dependent (a `forward` into a text prop is
+* not one), and only the config can answer that.
 */
-function withEmptyNodeSlots(spec, component) {
-	const names = nodeSlotNames(component);
+function withEmptyNodeSlots(spec, slotNames) {
+	const names = slotNames;
 	if (names.length === 0) return spec;
 	const rootKey = spec.root;
 	const next = structuredClone(spec);
 	const elements = next.elements;
 	const root = elements[rootKey];
 	if (!root) return spec;
-	root.props = root.props ?? {};
 	let injected = false;
 	for (const name of names) {
-		if (root.props[name] !== void 0) continue;
+		if (root.slots?.[name] !== void 0) continue;
 		const key = `${rootKey}__${name}__slot`;
 		elements[key] = {
 			type: SLOT_TYPE,
 			props: { name }
 		};
-		root.props[name] = { $slot: key };
+		root.slots = {
+			...root.slots,
+			[name]: [key]
+		};
 		injected = true;
 	}
 	return injected ? next : spec;
@@ -42,9 +73,8 @@ function withEmptyNodeSlots(spec, component) {
 /**
 * Build the single, namespace-aware {@link AcceptsChildNodes} predicate from a
 * live config: an element type is a node container iff its resolved component's
-* `derived.acceptsChildNodes` is true. `getComponent` resolves both bare (`Box`)
-* and namespaced (`uds:Box`) types, so the predicate matches whichever form the
-* spec carries. Returns a constant `false` when there's no config (nothing can
+* it takes child NODES. `Component.get` resolves a path or the ref a spec carries, so the predicate
+* matches whichever form is in hand. Returns a constant `false` when there's no config (nothing can
 * be classified yet) — callers thread this into slot injection and drop
 * hit-testing so every surface agrees on what accepts children.
 */
@@ -52,9 +82,23 @@ function buildAcceptsChildNodes(config) {
 	const classify = buildClassifyChildNodes(config);
 	return (type) => classify(type) === true;
 }
+/**
+* Whether an element type takes child NODES — `true`, `false`, or `undefined` when nothing can say.
+*
+* `childrenPolicy` is the answer, and it is the same answer the spec validator, the emitted module and
+* the anatomy schema use: a void element takes nothing, a text slot takes a string, and everything
+* else takes nodes. v1 asked a flag stamped on each component at registration (`acceptsChildNodes`),
+* which is the same fact computed once and stored — so it could be stale, and only registration could
+* write it.
+*/
 function buildClassifyChildNodes(config) {
 	if (!config) return () => void 0;
-	return (type) => type === void 0 ? void 0 : config.getComponent(type)?.derived.acceptsChildNodes;
+	return (type) => {
+		if (type === void 0) return void 0;
+		const component = Component.get(config, type);
+		if (!component) return void 0;
+		return childrenPolicy(config, component.path) === "nodes";
+	};
 }
 /**
 * Pin a persistent trailing `Slot` as the last child of every container element
@@ -98,8 +142,8 @@ function withContainerChildSlots(spec, acceptsChildNodes) {
 }
 /**
 * Compose both slot injections into the canvas's render view: layer-bound node
-* slots on a component instance's root (`withEmptyNodeSlots`, needs the
-* component definition) plus a trailing insertion `Slot` in every container,
+* slots on a component instance's root (`withEmptyNodeSlots`, keyed by the
+* component's `namedSlotTargets`) plus a trailing insertion `Slot` in every container,
 * tree-wide (`withContainerChildSlots`). This is the spec the studio canvas
 * renders so empty slots show as drop targets — it is NEVER persisted. Stored
 * specs stay slot-free; `stripInjectedSlots` is the inverse, applied at every
@@ -107,32 +151,29 @@ function withContainerChildSlots(spec, acceptsChildNodes) {
 * same reference when there's nothing to add, so this is cheap and idempotent —
 * re-running on an already-slotted spec adds nothing.
 */
-function withRenderSlots(spec, component, acceptsChildNodes) {
-	return withContainerChildSlots(component ? withEmptyNodeSlots(spec, component) : spec, acceptsChildNodes);
-}
-function slotRefKeys(value) {
-	if (typeof value !== "object" || value === null || !("$slot" in value)) return;
-	const ref = value.$slot;
-	if (typeof ref === "string") return [ref];
-	return Array.isArray(ref) ? ref : void 0;
+function withRenderSlots(spec, slotNames, acceptsChildNodes) {
+	return withContainerChildSlots(slotNames ? withEmptyNodeSlots(spec, slotNames) : spec, acceptsChildNodes);
 }
 /**
 * Inverse of `withEmptyNodeSlots` + `withContainerChildSlots`: drop every
 * injected `Slot` element and scrub its references, so a spec carries no
-* editing scaffolding. A `Slot`-typed element is ALWAYS an injected content
-* hole (json-render's placeholder), never authored content — both injectors
-* emit `type: 'Slot'` — so removing all of them and their references is the
-* exact reversal: a trailing `children` Slot drops out of its parent's
+* editing scaffolding. An injected `Slot` is render-only — both injectors
+* emit `type: 'Slot'` with no `shown` — so removing them and their references
+* is the exact reversal: a trailing `children` Slot drops out of its parent's
 * `children`, and an empty node slot drops both its `Slot` element and the
-* `{ $slot }` prop that pointed at it (a FILLED slot points at a real element,
-* which is not `Slot`-typed, so it survives). Use at export/serialization
-* boundaries (e.g. clipboard); the canvas re-injects fresh drop targets on
-* load. Idempotent: returns `spec` unchanged when there are no `Slot` elements.
+* `slots` entry that named it (a FILLED slot names a real element,
+* which is not `Slot`-typed, so it survives). A `shown: true` Slot is NOT
+* scaffolding: it is the user-enabled Placeholder `setNodeSlot` deliberately
+* persists, so it survives the strip — without the exemption, a slot fill
+* (which strips the whole spec before persisting) would silently delete a
+* sibling slot's placeholder. Use at export/serialization boundaries (e.g.
+* clipboard); the canvas re-injects fresh drop targets on load. Idempotent:
+* returns `spec` unchanged when there are no strippable `Slot` elements.
 */
 function stripInjectedSlots(spec) {
 	const elements = spec.elements;
 	if (!elements || typeof elements !== "object") return spec;
-	const slotKeys = new Set(Object.keys(elements).filter((k) => elements[k]?.type === SLOT_TYPE));
+	const slotKeys = new Set(Object.keys(elements).filter((k) => elements[k]?.type === SLOT_TYPE && elements[k]?.props?.shown !== true));
 	if (slotKeys.size === 0) return spec;
 	const next = structuredClone(spec);
 	const nextEls = next.elements;
@@ -140,16 +181,15 @@ function stripInjectedSlots(spec) {
 	for (const el of Object.values(nextEls)) {
 		if (!el) continue;
 		if (Array.isArray(el.children)) el.children = el.children.filter((c) => !slotKeys.has(c));
-		if (!el.props) continue;
-		for (const [propName, value] of Object.entries(el.props)) {
-			const refs = slotRefKeys(value);
-			if (!refs) continue;
-			const remaining = refs.filter((r) => !slotKeys.has(r));
-			if (remaining.length === 0) delete el.props[propName];
-			else if (remaining.length !== refs.length) el.props[propName] = { $slot: remaining };
+		if (!el.slots) continue;
+		for (const [name, fills] of Object.entries(el.slots)) {
+			const remaining = fills.filter((r) => !slotKeys.has(r));
+			if (remaining.length === 0) delete el.slots[name];
+			else if (remaining.length !== fills.length) el.slots[name] = remaining;
 		}
+		if (Object.keys(el.slots).length === 0) delete el.slots;
 	}
 	return next;
 }
 //#endregion
-export { buildAcceptsChildNodes, buildClassifyChildNodes, stripInjectedSlots, withContainerChildSlots, withEmptyNodeSlots, withRenderSlots };
+export { buildAcceptsChildNodes, buildClassifyChildNodes, namedSlotTargets, stripInjectedSlots, withContainerChildSlots, withEmptyNodeSlots, withRenderSlots };

package/dist/spec/index.d.ts

@@ -1,18 +1,29 @@
+import { AcceptsChildNodes, ChildNodesClassification, ClassifyChildNodes, buildAcceptsChildNodes, buildClassifyChildNodes, namedSlotTargets, stripInjectedSlots, withContainerChildSlots, withEmptyNodeSlots, withRenderSlots } from "./empty-node-slots.js";
+import { DocumentRename, RewritableSpec, SpecRewrite, rewriteSpecRefs } from "./rewrite-refs.js";
 import { applyForcedModifiers, collectForcedModifierProps } from "./apply-forced-modifiers.js";
-import { AssetComponentMap, AssetJsxForm, AssetNodeResolver, assetJsxForm, parseAssetType } from "./asset-jsx.js";
+import { AssetComponentMap, AssetJsxForm, AssetNodeResolver, assetJsxForm, jsxIdentifier, parseAssetType } from "./asset-jsx.js";
 import { CollapseTextLabelsResult, CollapsedTextLabel, collapseWrappedTextLabels } from "./collapse-text-labels.js";
-import { AcceptsChildNodes, ChildNodesClassification, ClassifyChildNodes, buildAcceptsChildNodes, buildClassifyChildNodes, stripInjectedSlots, withContainerChildSlots, withEmptyNodeSlots, withRenderSlots } from "./empty-node-slots.js";
 import { JsxToSpecOptions, UNRESOLVED, hasUnresolvedProps, jsxToSpec, stripUnresolvedProps } from "./jsxToSpec.js";
-import { ResolvableComponent, resolveAuthoredLayerProps, resolveRenderedLayerProps } from "./layer-props.js";
-import { PreviewControl, PreviewControlKind, derivePreviewControls, propOptions } from "./preview-controls.js";
-import { collectSlotRefs, isSlotRef } from "./slot-refs.js";
+import { GraftableElement, GraftableSpec, PreviewElement, PreviewSpecNode, PreviewValue, graftPreviewElements, hasPreviewElementDeep, isPreviewElement, previewElementNodes, previewElementType } from "./preview-elements.js";
 import { SpecToJsxOptions, SpecToJsxResult, specToJsx } from "./specToJsx.js";
 
 //#region src/spec/index.d.ts
-/** Internal render-spec provenance stamped on the Text node that preview
- * extraction creates for a scalar slot. The value is the originating slot
- * name. It lets Studio distinguish that generated proxy from a real authored
- * marker-less Text element without changing the rendered layer hierarchy. */
+/**
+ * Spec-format helpers — everything that reads or rewrites a json-render Spec in the UDS dialect
+ * (slot fills, forced modifier states, JSX ⇄ spec conversion).
+ *
+ * Nearly all of these are about the SPEC alone: a spec is a document, and asking what its elements
+ * are, which of them a slot pulls in, or what its JSX form looks like needs no design system to
+ * answer. What a component's layers are STYLED with is the config's question and lives with the
+ * config ({@link layerStyles}, {@link componentRuleClasses}).
+ *
+ * The exception is {@link collapseWrappedTextLabels}, which takes a `Config` — it decides whether a
+ * Text wrapper is redundant, and that depends on what the wrapping component takes as children. It
+ * belongs here anyway because the RESULT is a rewritten spec; it just can't answer without asking.
+ */
+/** Stamped on the Text node that preview extraction creates for a scalar slot; the value is the slot
+ *  it came from. It's what tells that generated proxy apart from an authored marker-less Text
+ *  element, without changing the rendered layer hierarchy. */
 declare const SYNTHETIC_TEXT_SLOT_PROP = "data-uds-synthetic-text-slot";
 //#endregion
-export { type AcceptsChildNodes, type AssetComponentMap, type AssetJsxForm, type AssetNodeResolver, type ChildNodesClassification, type ClassifyChildNodes, type CollapseTextLabelsResult, type CollapsedTextLabel, type JsxToSpecOptions, type PreviewControl, type PreviewControlKind, type ResolvableComponent, SYNTHETIC_TEXT_SLOT_PROP, type SpecToJsxOptions, type SpecToJsxResult, UNRESOLVED, applyForcedModifiers, assetJsxForm, buildAcceptsChildNodes, buildClassifyChildNodes, collapseWrappedTextLabels, collectForcedModifierProps, collectSlotRefs, derivePreviewControls, hasUnresolvedProps, isSlotRef, jsxToSpec, parseAssetType, propOptions, resolveAuthoredLayerProps, resolveRenderedLayerProps, specToJsx, stripInjectedSlots, stripUnresolvedProps, withContainerChildSlots, withEmptyNodeSlots, withRenderSlots };
+export { type AcceptsChildNodes, type AssetComponentMap, type AssetJsxForm, type AssetNodeResolver, type ChildNodesClassification, type ClassifyChildNodes, type CollapseTextLabelsResult, type CollapsedTextLabel, type DocumentRename, type GraftableElement, type GraftableSpec, type JsxToSpecOptions, type PreviewElement, type PreviewSpecNode, type PreviewValue, type RewritableSpec, SYNTHETIC_TEXT_SLOT_PROP, type SpecRewrite, type SpecToJsxOptions, type SpecToJsxResult, UNRESOLVED, applyForcedModifiers, assetJsxForm, buildAcceptsChildNodes, buildClassifyChildNodes, collapseWrappedTextLabels, collectForcedModifierProps, graftPreviewElements, hasPreviewElementDeep, hasUnresolvedProps, isPreviewElement, jsxIdentifier, jsxToSpec, namedSlotTargets, parseAssetType, previewElementNodes, previewElementType, rewriteSpecRefs, specToJsx, stripInjectedSlots, stripUnresolvedProps, withContainerChildSlots, withEmptyNodeSlots, withRenderSlots };

package/dist/spec/index.js

@@ -1,17 +1,28 @@
-import { collectSlotRefs, isSlotRef } from "./slot-refs.js";
+import { graftPreviewElements, hasPreviewElementDeep, isPreviewElement, previewElementNodes, previewElementType } from "./preview-elements.js";
+import { assetJsxForm, jsxIdentifier, parseAssetType } from "./asset-jsx.js";
+import { buildAcceptsChildNodes, buildClassifyChildNodes, namedSlotTargets, stripInjectedSlots, withContainerChildSlots, withEmptyNodeSlots, withRenderSlots } from "./empty-node-slots.js";
 import { applyForcedModifiers, collectForcedModifierProps } from "./apply-forced-modifiers.js";
-import { assetJsxForm, parseAssetType } from "./asset-jsx.js";
 import { collapseWrappedTextLabels } from "./collapse-text-labels.js";
-import { buildAcceptsChildNodes, buildClassifyChildNodes, stripInjectedSlots, withContainerChildSlots, withEmptyNodeSlots, withRenderSlots } from "./empty-node-slots.js";
 import { UNRESOLVED, hasUnresolvedProps, jsxToSpec, stripUnresolvedProps } from "./jsxToSpec.js";
-import { resolveAuthoredLayerProps, resolveRenderedLayerProps } from "./layer-props.js";
-import { derivePreviewControls, propOptions } from "./preview-controls.js";
+import { rewriteSpecRefs } from "./rewrite-refs.js";
 import { specToJsx } from "./specToJsx.js";
 //#region src/spec/index.ts
-/** Internal render-spec provenance stamped on the Text node that preview
-* extraction creates for a scalar slot. The value is the originating slot
-* name. It lets Studio distinguish that generated proxy from a real authored
-* marker-less Text element without changing the rendered layer hierarchy. */
+/**
+* Spec-format helpers — everything that reads or rewrites a json-render Spec in the UDS dialect
+* (slot fills, forced modifier states, JSX ⇄ spec conversion).
+*
+* Nearly all of these are about the SPEC alone: a spec is a document, and asking what its elements
+* are, which of them a slot pulls in, or what its JSX form looks like needs no design system to
+* answer. What a component's layers are STYLED with is the config's question and lives with the
+* config ({@link layerStyles}, {@link componentRuleClasses}).
+*
+* The exception is {@link collapseWrappedTextLabels}, which takes a `Config` — it decides whether a
+* Text wrapper is redundant, and that depends on what the wrapping component takes as children. It
+* belongs here anyway because the RESULT is a rewritten spec; it just can't answer without asking.
+*/
+/** Stamped on the Text node that preview extraction creates for a scalar slot; the value is the slot
+*  it came from. It's what tells that generated proxy apart from an authored marker-less Text
+*  element, without changing the rendered layer hierarchy. */
 const SYNTHETIC_TEXT_SLOT_PROP = "data-uds-synthetic-text-slot";
 //#endregion
-export { SYNTHETIC_TEXT_SLOT_PROP, UNRESOLVED, applyForcedModifiers, assetJsxForm, buildAcceptsChildNodes, buildClassifyChildNodes, collapseWrappedTextLabels, collectForcedModifierProps, collectSlotRefs, derivePreviewControls, hasUnresolvedProps, isSlotRef, jsxToSpec, parseAssetType, propOptions, resolveAuthoredLayerProps, resolveRenderedLayerProps, specToJsx, stripInjectedSlots, stripUnresolvedProps, withContainerChildSlots, withEmptyNodeSlots, withRenderSlots };
+export { SYNTHETIC_TEXT_SLOT_PROP, UNRESOLVED, applyForcedModifiers, assetJsxForm, buildAcceptsChildNodes, buildClassifyChildNodes, collapseWrappedTextLabels, collectForcedModifierProps, graftPreviewElements, hasPreviewElementDeep, hasUnresolvedProps, isPreviewElement, jsxIdentifier, jsxToSpec, namedSlotTargets, parseAssetType, previewElementNodes, previewElementType, rewriteSpecRefs, specToJsx, stripInjectedSlots, stripUnresolvedProps, withContainerChildSlots, withEmptyNodeSlots, withRenderSlots };

package/dist/spec/jsxToSpec.d.ts

@@ -19,17 +19,22 @@ interface JsxToSpecOptions {
    */
   moduleSource?: string;
   /**
-   * Set of known component names in the registry. When provided, any
-   * PascalCase JSX element whose tag is NOT in this set (e.g. providers,
-   * wrappers) is treated as a transparent fragment — its children are
-   * flattened into the parent.
+   * Every identifier a tag may name, mapped to the QUALIFIED TYPE it resolves to
+   * — `'Badge' → 'component:Badge'`, `'TrophyIcon' → 'icon:icons/TrophyIcon'`.
+   * Build it with Studio's `buildKnownComponentSet`, which walks the same
+   * components and icon libraries.
+   *
+   * It decides two things. A PascalCase tag the map doesn't know (a provider, a
+   * wrapper) is treated as a transparent fragment — its children flatten into the
+   * parent. A tag it does know emits that qualified type, so a round trip through
+   * JSX keeps the kind each element named.
    */
-  knownComponents?: Set<string>;
+  knownComponents?: ReadonlyMap<string, string>;
   /**
-   * Reconstructs placed asset nodes from authoring-component tags —
-   * `<Icon name="Trophy" …/>` → type `yahoo-os:asset:icons/Trophy`. The
-   * exact inverse of `specToJsx`'s `assetComponents` mapping; without it an
-   * `<Icon name=…/>` round-trips as a literal `Icon` component node.
+   * Reconstructs placed asset nodes from a rendering-component tag —
+   * `<Icon name="Trophy" …/>` → type `icon:icons/Trophy`. The exact inverse of
+   * `specToJsx`'s `assetComponents` mapping; without it an `<Icon name=…/>`
+   * round-trips as a literal `Icon` component node.
    */
   resolveAssetNode?: AssetNodeResolver;
 }

package/dist/spec/jsxToSpec.js

@@ -6,6 +6,16 @@ import { parse } from "@babel/parser";
 * and should be stripped — $bindState handles write-back automatically.
 */
 const STATE_SETTER = Symbol.for("jsxToSpec.stateSetter");
+/**
+* Wrapper `getAttributeValue` hands back for a JSX-element prop value. The
+* converted element is already in the context's `elements` map; the attribute
+* loop records its key on the owning element's `slots` record instead of
+* storing a prop.
+*/
+const SLOT_FILL = Symbol.for("jsxToSpec.slotFill");
+function isSlotFill(value) {
+	return typeof value === "object" && value !== null && SLOT_FILL in value;
+}
 function buildModuleScope(ast) {
 	const scope = {
 		values: /* @__PURE__ */ new Map(),
@@ -270,7 +280,7 @@ function getAttributeValue(valueNode, scope, ctx) {
 			const expr = valueNode.expression;
 			if (ctx && (expr.type === "JSXElement" || expr.type === "JSXFragment")) {
 				const slotKey = convertJsxNode(expr, ctx);
-				if (slotKey) return { $slot: slotKey };
+				if (slotKey) return { [SLOT_FILL]: slotKey };
 				return UNRESOLVED;
 			}
 			return evaluateExpression(expr, scope);
@@ -360,6 +370,7 @@ function convertElement(node, ctx) {
 	if (ctx.knownComponents && tagName[0] === tagName[0].toUpperCase() && !ctx.knownComponents.has(tagName)) return flattenChildrenAsFragment(node.children, ctx);
 	const key = nextKey(ctx);
 	const props = {};
+	const slots = {};
 	const onBindings = {};
 	for (const attr of node.openingElement.attributes) if (attr.type === "JSXAttribute") {
 		const jsxAttr = attr;
@@ -369,7 +380,12 @@ function convertElement(node, ctx) {
 			onBindings[binding.event] = binding.action;
 			continue;
 		}
-		props[propName] = getAttributeValue(jsxAttr.value, ctx.scope, ctx);
+		const propValue = getAttributeValue(jsxAttr.value, ctx.scope, ctx);
+		if (isSlotFill(propValue)) {
+			slots[propName] = [propValue[SLOT_FILL]];
+			continue;
+		}
+		props[propName] = propValue;
 	} else if (attr.type === "JSXSpreadAttribute") props.__spread__ = UNRESOLVED;
 	const childKeys = [];
 	const textContent = collectTextChildren(node.children);
@@ -381,10 +397,11 @@ function convertElement(node, ctx) {
 	const assetType = ctx.resolveAssetNode?.(tagName, props) ?? null;
 	if (assetType) delete props.name;
 	const element = {
-		type: assetType ?? tagName,
+		type: assetType ?? ctx.knownComponents?.get(tagName) ?? tagName,
 		props
 	};
 	if (childKeys.length > 0) element.children = childKeys;
+	if (Object.keys(slots).length > 0) element.slots = slots;
 	if (Object.keys(onBindings).length > 0) element.on = onBindings;
 	ctx.elements[key] = element;
 	return key;