@yahoo/uds-create-config 4.26.4 → 4.26.6

package/dist/capture/capture-to-spec.d.ts

@@ -32,7 +32,7 @@ interface CaptureToSpecOptions {
   readonly config: Config;
   /** CSS selector for the subtree to convert; the whole document by default. */
   readonly selector?: string;
-  /** Wraps every top-level element under this root; required when the capture has several. */
+  /** Wraps every top-level element under this root; several are otherwise wrapped in the canvas frame. */
   readonly root?: {
     type: string;
     props?: Record<string, unknown>;

package/dist/capture/capture-to-spec.js

@@ -1,9 +1,12 @@
+import { isRef, pathOf } from "../framework/utils/refs.js";
+import { authoredValue } from "../framework/projections.js";
+import { intoName } from "../framework/prop-surface.js";
+import { Component } from "../entities/system/Component.js";
 import { elementFromCaptured, isCapturedElement } from "./captured-tree.js";
 import { classGrammar, normalizeCssValue } from "./class-grammar.js";
 //#region src/capture/capture-to-spec.ts
 /** Inline declarations that are rendering plumbing rather than a prop. */
 const SKIP_INLINE_PROPERTY = new Set([
-	"display",
 	"visibility",
 	"box-sizing",
 	"touch-action",
@@ -72,18 +75,23 @@ const ROOT_LAYER = "[data-uds-component][data-uds-layer=\"root\"]";
 const DEFAULT_CHILD_CAP = 12;
 const isElement = isCapturedElement;
 function specFromCapture(options) {
-	const tree = elementFromCaptured(options.tree);
+	const tree = elementFromCaptured(markOrphanLayers(options.tree));
 	let scope = tree;
 	if (options.selector) scope = tree.closest(options.selector) ?? tree.querySelector(options.selector);
 	if (!scope) throw new Error(`Nothing matches "${options.selector}" in the capture.`);
 	const converter = new Converter(options, classGrammar(options.config));
 	const top = scope.closest(ROOT_LAYER) === scope || scope.tagName === "svg" ? converter.convertTop(scope) : converter.convertChildren(scope);
+	const frameRole = canvasRole(options.config, "frame");
+	const wrapper = options.root ?? (top.length > 1 && frameRole ? {
+		type: `component:${frameRole.component}`,
+		props: converter.artboardProps(frameRole.component)
+	} : void 0);
 	let rootKey;
-	if (options.root) {
+	if (wrapper) {
 		rootKey = "root";
 		converter.elements.root = {
-			type: options.root.type,
-			props: { ...options.root.props ?? {} },
+			type: wrapper.type,
+			props: { ...wrapper.props ?? {} },
 			children: top
 		};
 	} else if (top.length === 1) rootKey = top[0];
@@ -99,6 +107,39 @@ function specFromCapture(options) {
 		unresolvedIcons: converter.unresolvedIcons
 	};
 }
+/** Marks a layer whose component's root is not in the DOM with `<component>#<layer>`. */
+const ORPHAN_LAYER = "data-uds-orphan-layer";
+/**
+* The tree with each layer of a component whose root is not in the DOM unmarked, and named in
+* {@link ORPHAN_LAYER} instead. A tooltip renders only its anchor around the trigger and portals the
+* bubble; the anchor is placed as a frame carrying the anchor's own styles, since there is no root for
+* an instance of the component to paint.
+*/
+function markOrphanLayers(tree) {
+	const visit = (node, open) => {
+		const path = node.attrs?.["data-uds-component"];
+		const layer = node.attrs?.["data-uds-layer"];
+		let marked = node;
+		let inside = open;
+		if (path && layer && !open.has(path)) if (layer === "root") inside = new Set([...open, path]);
+		else {
+			const { "data-uds-component": _path, "data-uds-layer": _layer, ...attrs } = node.attrs ?? {};
+			marked = {
+				...node,
+				attrs: {
+					...attrs,
+					[ORPHAN_LAYER]: `${path}#${layer}`
+				}
+			};
+		}
+		if (!marked.children?.length) return marked;
+		return {
+			...marked,
+			children: marked.children.map((child) => typeof child === "string" ? child : visit(child, inside))
+		};
+	};
+	return visit(tree, /* @__PURE__ */ new Set());
+}
 /**
 * A capture lands on a design file, where an element's content is its structural `children` and
 * `slots` holds named slots only: that is what a hand-built container has, and what the chrome, the
@@ -160,6 +201,7 @@ var Converter = class {
 			if (!isElement(node)) continue;
 			if (node.getAttribute("data-uds-component") === path && node.getAttribute("data-uds-layer") !== "root") continue;
 			if (node.tagName.toLowerCase() === "svg" || node.hasAttribute("data-uds-component") && node.getAttribute("data-uds-layer") === "root") out.push(...this.convert(node));
+			else if (visible(node) && framesItself(node)) out.push(...this.frame(node));
 			else if (visible(node)) out.push(...this.convertOutsideLayers(node, path));
 		}
 		return out;
@@ -172,8 +214,111 @@ var Converter = class {
 			return key ? [key] : [];
 		}
 		if (el.tagName.toLowerCase() === "svg") return this.icon(el);
+		if (isField(el)) return this.field(el);
+		if (framesItself(el)) return this.frame(el);
 		return this.convertChildren(el);
 	}
+	/**
+	* An unmarked element with an inline style, which is what the page drew it with, as the canvas's
+	* frame component carrying that style. One with nothing inline only groups its children and is
+	* folded away, and an empty one that paints nothing of its own (a portal's container) places
+	* nothing.
+	*/
+	frame(el) {
+		const children = this.convertChildren(el);
+		if (children.length === 0 && !paintsItself(el)) return [];
+		const role = canvasRole(this.options.config, "frame");
+		const grammar = role ? this.grammar.component(role.component) : void 0;
+		if (!role || !grammar) return children;
+		const props = this.orphanLayerProps(el, grammar);
+		this.propsFromInlineStyle(el, grammar, props);
+		if (Object.keys(props).length === 0) return children;
+		const key = this.key(role.component);
+		this.elements[key] = {
+			type: `component:${role.component}`,
+			props,
+			...children.length > 0 ? { children } : {}
+		};
+		return [key];
+	}
+	/**
+	* The styles the config gives an orphaned layer, as the frame's props: the rules that always apply
+	* and the ones its classes say are on, in authored order. Only values the frame component declares,
+	* spelled as an author writes them, are kept.
+	*/
+	orphanLayerProps(el, frame) {
+		const [path, layer] = (el.getAttribute(ORPHAN_LAYER) ?? "").split("#");
+		if (!path || !layer) return {};
+		const active = {};
+		const own = this.grammar.component(path);
+		for (const cls of classesOf(el)) Object.assign(active, own?.conditions.get(cls));
+		const props = {};
+		const styles = Component.get(this.options.config, path)?.styles ?? {};
+		for (const rule of Object.values(styles)) {
+			const when = rule?.when ?? {};
+			if (!Object.entries(when).every(([key, value]) => active[key] === value)) continue;
+			for (const [key, value] of Object.entries(rule.layers?.[layer] ?? {})) {
+				if (!(key in frame.declared)) continue;
+				const authored = authoredValue(this.options.config, key, value);
+				if (typeof authored === "string" || typeof authored === "boolean") props[key] = authored;
+			}
+		}
+		return props;
+	}
+	/** The props that make `component` an artboard: what its content is placed against and clipped to. */
+	artboardProps(component) {
+		const props = {};
+		const grammar = this.grammar.component(component);
+		if (grammar) this.propsFromDeclarations(ARTBOARD, grammar, props);
+		return props;
+	}
+	/**
+	* What `el`'s render placed outside its stamped slot layers and claimed layers, walking down to
+	* the first thing on each branch that is a piece of its own: a nested component, a glyph (unless
+	* `el` draws its own), a field it does not read, or an unmarked element with an inline style.
+	*/
+	looseContent({ el, claimed, takesGlyphs, takesFields }) {
+		const out = [];
+		const walk = (node) => {
+			for (let i = 0; i < node.childNodes.length; i += 1) {
+				if (this.childCap > 0 && out.length >= this.childCap) return;
+				const child = node.childNodes[i];
+				if (!isElement(child) || !visible(child) || claimed.has(child)) continue;
+				if (child.hasAttribute("data-uds-slot")) continue;
+				const tag = child.tagName.toLowerCase();
+				if (child.hasAttribute("data-uds-component") && child.getAttribute("data-uds-layer") === "root") out.push(...this.convert(child));
+				else if (tag === "svg") {
+					if (takesGlyphs) out.push(...this.convert(child));
+				} else if (isField(child)) {
+					if (takesFields) out.push(...this.field(child));
+				} else if (framesItself(child)) out.push(...this.frame(child));
+				else walk(child);
+			}
+		};
+		walk(el);
+		return out;
+	}
+	/** A form field no component reads, placed as the text it shows through the canvas's text role. */
+	field(field) {
+		const text = fieldText(field);
+		const role = canvasRole(this.options.config, "text");
+		if (!text || !role) return [];
+		const props = { ...role.defaultProps };
+		const grammar = this.grammar.component(role.component);
+		if (grammar) {
+			if (field.tagName.toLowerCase() === "input") this.propsFromDeclarations(INPUT_LINE, grammar, props);
+			this.propsFromInlineStyle(field, grammar, props);
+		}
+		const key = this.key(role.component);
+		this.elements[key] = {
+			type: `component:${role.component}`,
+			props: {
+				...props,
+				children: text
+			}
+		};
+		return [key];
+	}
 	/** A bare `<svg>` placed as the component its library renders it with. */
 	icon(svg) {
 		const answer = this.options.icons?.resolve(svgOf(svg));
@@ -251,22 +396,40 @@ var Converter = class {
 				if (text) props[prop] = text;
 			}
 		}
+		for (const [prop, declaration] of Object.entries(declared)) {
+			if (props[prop] !== void 0 || slots[prop]) continue;
+			const route = declaration;
+			if (route?.type !== "forward" || !isRef(route.target)) continue;
+			const into = intoName(route.into);
+			if (into === "children") continue;
+			const layer = layerOf(el, path, pathOf(route.target.__ref));
+			if (!layer || !visible(layer) || hiddenBetween(layer, el)) continue;
+			const svg = layer.tagName.toLowerCase() === "svg" ? layer : layer.querySelector("svg");
+			const drawn = asArray(layer.querySelectorAll(ROOT_LAYER)).find((inner) => nearestRoot(inner) === el);
+			const glyph = svg ? this.options.icons?.resolve(svgOf(svg))?.props[into] : drawn && stampedProps(drawn)[into];
+			if (glyph === void 0) continue;
+			props[prop] = glyph;
+			claimed.add(layer);
+		}
 		if ("value" in declared && props.value === void 0) {
 			const field = fieldValue(el, declared.value);
 			if (field !== void 0) props.value = field;
 		}
-		const loose = [];
-		const looseSelector = renders ? ROOT_LAYER : `${ROOT_LAYER}, svg`;
-		for (const nested of asArray(el.querySelectorAll(looseSelector))) {
-			if (this.childCap > 0 && loose.length >= this.childCap) break;
-			if (nearestRoot(nested) !== el) continue;
-			if (hiddenBetween(nested, el)) continue;
-			const stampedLayer = nested.parentElement?.closest("[data-uds-slot]") ?? null;
-			if (stampedLayer && nearestRoot(stampedLayer) === el) continue;
-			if (withinAny(nested, claimed, el)) continue;
-			loose.push(...this.convert(nested));
+		const loose = this.looseContent({
+			el,
+			claimed,
+			takesGlyphs: !renders,
+			takesFields: !("value" in declared)
+		});
+		const filled = new Set(Object.keys(slots));
+		for (const nested of loose) {
+			const slot = grammar ? looseSlot({
+				grammar,
+				filled,
+				type: this.elements[nested].type
+			}) : "children";
+			if (slot) slots[slot] = [...slots[slot] ?? [], nested];
 		}
-		if (loose.length > 0 && !slots.children) slots.children = loose;
 		if (Object.keys(slots).length > 0) element.slots = slots;
 		const aria = el.getAttribute("aria-label");
 		if (aria) {
@@ -323,28 +486,32 @@ var Converter = class {
 	* The element's inline styles as props: a component's own `style` is the one place a size the
 	* classes do not carry lives, so `width: 300px` becomes the declared width prop with `[300px]`,
 	* and `column-gap: var(--uds-spacing-2)` becomes the gap leaf `2`. A value with no leaf lands as
-	* an off-scale `[value]` only on a property that takes one. Rendering plumbing (display, box
-	* sizing, transitions, browser defaults) is not a prop and is skipped.
+	* an off-scale `[value]` only on a property that takes one. Rendering plumbing (box sizing,
+	* transitions, browser defaults) is not a prop and is skipped.
 	*/
 	propsFromInlineStyle(el, grammar, props) {
-		const style = el.getAttribute("style");
-		if (!style) return;
-		for (const declaration of style.split(";")) {
-			const at = declaration.indexOf(":");
-			if (at < 0) continue;
-			const property = declaration.slice(0, at).trim().toLowerCase();
-			let value = normalizeCssValue(declaration.slice(at + 1));
+		this.propsFromDeclarations(inlineDeclarations(el), grammar, props);
+	}
+	/** {@link propsFromInlineStyle} over declarations the caller supplies. */
+	propsFromDeclarations(declarations, grammar, props) {
+		for (const [property, raw] of declarations) {
+			let value = normalizeCssValue(raw);
 			if (!value || SKIP_INLINE_PROPERTY.has(property) || SKIP_INLINE_VALUE.has(value)) continue;
 			if (property === "position" && value === "fixed") value = "absolute";
 			if (VIEWPORT_VALUE.test(value) && !WHOLE_VIEWPORT.test(value)) value = frameUnits(value, this.options.width, this.options.height);
 			for (const option of this.grammar.stylePropsFor(property)) {
 				const prop = grammar.propForStyleProperty.get(option.path);
 				if (!prop) continue;
+				const css = option.negates ? negated(value) : value;
+				if (css === void 0) continue;
 				let next;
-				const leaf = option.leafFor(value);
-				if (WHOLE_VIEWPORT.test(value)) next = option.fullLeaf;
+				const leaf = equivalents({
+					property,
+					value: css
+				}).map((spelling) => option.leafFor(spelling)).find((found) => found !== void 0);
+				if (WHOLE_VIEWPORT.test(css)) next = option.fullLeaf;
 				else if (leaf !== void 0) next = leaf === "" ? true : leaf;
-				else if (option.arbitrary) next = `[${value.replaceAll(" ", "_")}]`;
+				else if (option.arbitrary) next = `[${css.replaceAll(" ", "_")}]`;
 				if (next === void 0) continue;
 				props[prop] = next;
 				break;
@@ -352,6 +519,107 @@ var Converter = class {
 		}
 	}
 };
+/**
+* The prop a nested component the render placed outside every stamped layer belongs to: `children`
+* first, then the other slots in declaration order, taking the first that is not already filled and
+* accepts the component's type. `children` also holds it when it forwards into a layer's children,
+* unless that route only takes text.
+*/
+function looseSlot({ grammar, filled, type }) {
+	const names = Object.keys(grammar.declared);
+	const ordered = names.includes("children") ? ["children", ...names.filter((name) => name !== "children")] : names;
+	const path = pathOf(type);
+	for (const name of ordered) {
+		if (filled.has(name)) continue;
+		const declaration = grammar.declared[name];
+		const route = grammar.layerProps.get(name);
+		if (!(declaration?.type === "slot" || name === "children" && route?.content === true && route.text !== true && (route.into ?? "children") === "children")) continue;
+		const accepts = Array.isArray(declaration?.accepts) ? declaration.accepts : [];
+		if (accepts.length > 0 && !accepts.some((ref) => refPath(ref) === path)) continue;
+		return name;
+	}
+}
+function refPath(ref) {
+	if (typeof ref === "string") return pathOf(ref);
+	if (ref && typeof ref === "object" && "__ref" in ref) return pathOf(ref.__ref);
+}
+/** How an artboard holds a page: the containing block for its positioned chrome, clipped to its box. */
+const ARTBOARD = [["position", "relative"], ["overflow", "hidden"]];
+/** How a single-line input lays out its text: centred across its height. */
+const INPUT_LINE = [["display", "flex"], ["align-items", "center"]];
+function isField(el) {
+	const tag = el.tagName.toLowerCase();
+	return tag === "input" || tag === "textarea";
+}
+/** The text a field shows: a text input's `value`, a textarea's content, else its placeholder. */
+function fieldText(field) {
+	const placeholder = collapse(field.getAttribute("placeholder") ?? "");
+	if (field.tagName.toLowerCase() === "textarea") return collapse(field.textContent ?? "") || placeholder;
+	const type = (field.getAttribute("type") ?? "text").toLowerCase();
+	if (NON_TEXT_INPUT.has(type)) return "";
+	return collapse(field.getAttribute("value") ?? "") || placeholder;
+}
+/** The component a canvas role places with (`text`, `frame`), and the props it places it with. */
+function canvasRole(config, name) {
+	const entries = (config.resolve("canvas-role", name)?.toJSON())?.entries ?? [];
+	const entry = entries.find((candidate) => candidate.default) ?? entries[0];
+	if (!entry || !isRef(entry.component)) return void 0;
+	return {
+		component: pathOf(entry.component.__ref),
+		defaultProps: entry.defaultProps ?? {}
+	};
+}
+/** An unmarked element the page gave an inline style, or an orphaned layer: kept as a frame. */
+function framesItself(el) {
+	if (el.hasAttribute("data-uds-component")) return false;
+	if (inlineDeclarations(el).some(([property, value]) => property === "display" && value.trim() === "contents")) return false;
+	if (el.hasAttribute(ORPHAN_LAYER)) return true;
+	return /\S/.test((el.getAttribute("style") ?? "").replace(/;/g, ""));
+}
+const NOTHING = new Set([
+	"none",
+	"transparent",
+	"0",
+	"0px",
+	"initial"
+]);
+/** Whether an element's inline style draws something of its own: a fill, a border or a shadow. */
+function paintsItself(el) {
+	return inlineDeclarations(el).some(([property, value]) => {
+		const drawn = !NOTHING.has(value.trim().toLowerCase());
+		if (property === "background-color" || property === "background-image") return drawn;
+		return drawn && (property === "box-shadow" || property === "border" || /^border(-[a-z]+)?-width$/.test(property));
+	});
+}
+/** An element's inline declarations as `[property, value]` pairs. */
+function inlineDeclarations(el) {
+	const out = [];
+	for (const declaration of (el.getAttribute("style") ?? "").split(";")) {
+		const at = declaration.indexOf(":");
+		if (at < 0) continue;
+		const property = declaration.slice(0, at).trim().toLowerCase();
+		if (property === "transform") continue;
+		const value = declaration.slice(at + 1).trim();
+		if (property === "background") {
+			if (!/url\(|gradient\(/.test(value)) out.push(["background-color", value]);
+			continue;
+		}
+		out.push([property, value]);
+	}
+	return out;
+}
+/** A single negative length or number without its sign; `undefined` for anything else. */
+function negated(value) {
+	return /^-\d*\.?\d+[a-z%]*$/.test(value) ? value.slice(1) : void 0;
+}
+/**
+* A value with the other spellings that paint the same, for matching against a leaf: a grid line
+* that only spans (`span 6`) is the same six tracks as `span 6 / span 6`.
+*/
+function equivalents({ property, value }) {
+	if ((property === "grid-column" || property === "grid-row") && /^span \d+$/.test(value)) return [value, `${value} / ${value}`];
+	return [value];
+}
 function stampedProps(el) {
 	const raw = el.getAttribute("data-uds-props");
 	if (!raw) return {};
@@ -386,7 +654,6 @@ function visible(el) {
 	if (/display:\s*none/.test(style) || /visibility:\s*hidden/.test(style)) return false;
 	if (/(^|;)\s*opacity:\s*0+(\.0+)?\s*(;|$)/.test(style)) return false;
 	if (el.hasAttribute("hidden")) return false;
-	if (el.getAttribute("aria-hidden") === "true" && el.tagName.toLowerCase() !== "svg") return false;
 	if (el.getAttribute("role") === "tooltip") return false;
 	if (el.getAttribute("data-uds-props")?.includes("\"hidden\":true")) return false;
 	return true;
@@ -419,15 +686,6 @@ function hiddenBetween(el, root) {
 	}
 	return false;
 }
-/** Whether `el` sits inside one of `layers`, below `root`. */
-function withinAny(el, layers, root) {
-	let node = el.parentElement;
-	while (node && node !== root) {
-		if (layers.has(node)) return true;
-		node = node.parentElement;
-	}
-	return false;
-}
 /** The component's own layer named `layer`, when the DOM marks one under this root. */
 function layerOf(root, path, layer) {
 	for (const candidate of asArray(root.querySelectorAll(`[data-uds-component="${path}"][data-uds-layer="${layer}"]`))) if (nearestRoot(candidate) === root) return candidate;

package/dist/capture/class-grammar.d.ts

@@ -35,6 +35,7 @@ interface ComponentGrammar {
     layer: string;
     content: boolean;
     into?: string;
+    text?: boolean;
   }>;
   /** Layer classes → layer name. */
   readonly layers: ReadonlyMap<string, string>;
@@ -44,6 +45,8 @@ interface CssPropertyMatch {
   readonly path: string;
   /** Whether the property takes an off-scale `[value]`. */
   readonly arbitrary: boolean;
+  /** The property writes the negation of the prop's value (`offsetLeft` → `margin-left: -<value>`). */
+  readonly negates: boolean;
   /** The leaf whose value is this CSS value, as `var(--…)` or as the literal it resolves to. */
   leafFor(cssValue: string): string | undefined;
   /** The leaf that fills the container (`100%`), which is what a viewport unit means inside a frame. */

package/dist/capture/class-grammar.js

@@ -1,7 +1,7 @@
 import { isRef, pathOf } from "../framework/utils/refs.js";
 import { className, cssVarRef, resolveComponentProps, resolveTokenValue, stylePropEntries } from "../framework/projections.js";
+import { intoName, routesContent, routesIntoText } from "../framework/prop-surface.js";
 import { componentLayerClass, componentRuleClasses, stylePropClasses } from "../framework/class-names.js";
-import { intoName, routesContent } from "../framework/prop-surface.js";
 //#region src/capture/class-grammar.ts
 const VIEWPORT_UNIT = /\d(vh|vw|dvh|dvw|svh|svw|lvh|lvw|vmin|vmax)\b/;
 /** `0px` → `0`, collapsed spaces, lowercase keywords; what two spellings of one value share. */
@@ -36,9 +36,10 @@ function classGrammar(config) {
 		leafValues.set(path, known);
 		return known;
 	};
-	const matchFor = (path, arbitrary) => ({
+	const matchFor = ({ path, arbitrary, negates }) => ({
 		path,
 		arbitrary,
+		negates,
 		leafFor(cssValue) {
 			const wanted = normalizeCssValue(cssValue);
 			for (const [leaf, spellings] of valuesOf(path)) if (spellings.includes(wanted)) return leaf;
@@ -52,13 +53,25 @@ function classGrammar(config) {
 		const properties = body.properties ?? [];
 		for (const property of properties) {
 			const list = byCss.get(property) ?? [];
-			list.push(matchFor(entity.path, body.arbitrary === true));
+			list.push(matchFor({
+				path: entity.path,
+				arbitrary: body.arbitrary === true,
+				negates: body.negates === true
+			}));
 			byCss.set(property, list);
 		}
 	}
 	const propertyCount = /* @__PURE__ */ new Map();
-	for (const entity of config.list("style-property")) propertyCount.set(entity.path, (entity.toJSON().properties ?? []).length);
-	for (const list of byCss.values()) list.sort((a, b) => (propertyCount.get(a.path) ?? 0) - (propertyCount.get(b.path) ?? 0));
+	const classPrefix = /* @__PURE__ */ new Map();
+	for (const entity of config.list("style-property")) {
+		const body = entity.toJSON();
+		propertyCount.set(entity.path, (body.properties ?? []).length);
+		classPrefix.set(entity.path, body.classPrefix);
+	}
+	for (const [property, list] of byCss) {
+		const whole = (path) => classPrefix.get(path) === property ? 0 : 1;
+		list.sort((a, b) => (propertyCount.get(a.path) ?? 0) - (propertyCount.get(b.path) ?? 0) || whole(a.path) - whole(b.path));
+	}
 	const components = /* @__PURE__ */ new Map();
 	const componentGrammar = (path) => {
 		const component = config.resolve("component", path);
@@ -96,7 +109,8 @@ function classGrammar(config) {
 				if (isRef(target)) layerProps.set(prop, {
 					layer: pathOf(target.__ref),
 					content: true,
-					into: intoName(declaration.into)
+					into: intoName(declaration.into),
+					text: routesIntoText(config, body.layers, declaration)
 				});
 			} else if (declaration.type === "string" && body.layers?.[prop] !== void 0 && prop !== "root") layerProps.set(prop, {
 				layer: prop,

package/dist/capture/icon-resolver.d.ts

@@ -9,10 +9,10 @@ import { IconLibrary } from "../entities/system/icon-library.js";
  *
  * Everything about a library is read off its group node: the package its glyphs come from
  * (`metadata.from`), the named sizes (`sizes`) and the weights it ships (`variants`). The component
- * that renders them is the one whose variant prop names the library; its props are found by what
- * they reference: the prop bound to the library is the glyph name, the one bound to `#variants` is
- * the weight, and the prop whose values are the library's size names is the size. The host reads
- * the glyph files, since a package's layout on disk is the host's to know.
+ * that renders them, and the prop that picks the glyph, are the ones `glyphComponentOf` answers; the
+ * other props are found by what they reference: the one bound to `#variants` is the weight, and the
+ * one whose values are the library's size names is the size. The host reads the glyph files, since a
+ * package's layout on disk is the host's to know.
  */
 /** Where a library's glyph files come from: the catalogue package its metadata names, and its format. */
 interface GlyphSource {

package/dist/capture/icon-resolver.js

@@ -33,18 +33,15 @@ function indexLibrary(config, library, glyphs) {
 	if (!drawer) return void 0;
 	const component = drawer.path;
 	const declared = resolveComponentProps(config, component);
-	let nameProp;
 	let variantProp;
 	let sizeProp;
 	const sizeNames = Object.keys(library.sizes);
+	const nameProp = drawer.prop;
 	for (const [prop, decl] of Object.entries(declared)) {
-		if (decl?.type !== "variant") continue;
-		const ref = refOf(decl);
-		if (ref === `icon:${library.path}`) nameProp = prop;
-		else if (ref === `icon:${library.path}#variants`) variantProp = prop;
+		if (prop === nameProp || decl?.type !== "variant") continue;
+		if (refOf(decl) === `icon:${library.path}#variants`) variantProp = prop;
 		else if (sizeNames.length > 0 && sizeNames.every((size) => listedValues(decl).includes(size))) sizeProp = prop;
 	}
-	if (!nameProp) return void 0;
 	const defaultVariant = library.defaultVariant ?? library.variants[0];
 	const ordered = [...glyphs].sort((a, b) => {
 		const rank = (g) => g.variant === defaultVariant ? 0 : 1;

package/dist/capture/node-ops.js

@@ -1,7 +1,7 @@
-import { CapturedNode } from "./captured-tree.js";
-import { pathOf } from "../framework/utils/refs.js";
 import { rejectData } from "../framework/rejection.js";
+import { pathOf } from "../framework/utils/refs.js";
 import { pathInput } from "../framework/schemas.js";
+import { CapturedNode } from "./captured-tree.js";
 import { specFromCapture } from "./capture-to-spec.js";
 import { specToNodePatches } from "./node-patches.js";
 import { z } from "zod";
@@ -29,7 +29,7 @@ const fromHtmlData = z.object({
 	width: z.number().min(100).max(4e3).optional(),
 	/** The captured viewport's height, what `100vh` measures inside the frame. */
 	height: z.number().min(100).max(8e3).optional(),
-	/** Wraps the capture's top-level components; required when there are several. */
+	/** Wraps the capture's top-level components; several are otherwise wrapped in the canvas frame. */
 	frame: frameSchema.optional(),
 	/** Convert only the subtree this selector finds. */
 	selector: z.string().optional(),