@yahoo/uds-create-config 4.10.2 → 4.10.4

package/dist/entities/system/style-bag.js

@@ -3,7 +3,8 @@ import { defineSubEntity } from "../../framework/defineSubEntity.js";
 import { derivedColor, gradient } from "./color.js";
 import { isCssProperty, kebabCase } from "../../css/values.js";
 import { valueSchemaOf } from "../../framework/value-domain.js";
-import { stylePropTokenPath } from "../../framework/projections.js";
+import { glyphLeafOf, glyphPackageRef } from "./glyph-identity.js";
+import { glyphPropsOfBody, refListOf, stylePropTokenPath } from "../../framework/projections.js";
 import { z } from "zod";
 //#region src/entities/system/style-bag.ts
 /** The explicit type annotation breaks the `z.lazy` self-reference cycle and keeps the
@@ -15,6 +16,7 @@ const styleValue = z.lazy(() => z.union([
 	refSchema,
 	derivedColor,
 	gradient,
+	glyphPackageRef,
 	z.record(z.string(), styleValue)
 ]));
 const anatomyPropValue = z.lazy(() => z.union([
@@ -63,7 +65,17 @@ const Style = defineSubEntity({
 		if (key.startsWith("_")) return openBag(config);
 		const bound = (config, declaration) => z.union([valueSchemaOf(declaration, config), styleValue]);
 		const declared = parent?.props?.[key];
-		if (isRef(declared?.value)) return bound(config, declared);
+		if (isRef(declared?.value) || refListOf(declared?.value) !== void 0) return bound(config, declared);
+		if (declared?.type === "forward") {
+			const libraries = glyphPropsOfBody({
+				config,
+				body: parent
+			})[key];
+			if (libraries && libraries.length > 0) return z.union([glyphLeafOf({
+				config,
+				libraries
+			}), styleValue]);
+		}
 		if (declared) return styleValue;
 		if (!config.resolve("style-property", key)) return styleValue;
 		return bound(config, {

package/dist/framework/Config.d.ts

@@ -72,7 +72,7 @@ interface RecordedSource {
  * The dense-counter `2` a short-lived scheme stamped before the chain existed reads as the mint
  * that replaced it (see `detectedWireVersion`).
  */
-declare const SERIALIZED_CONFIG_VERSION = 20260920161309;
+declare const SERIALIZED_CONFIG_VERSION = 20260922013625;
 interface SerializedConfig {
   /** See {@link SERIALIZED_CONFIG_VERSION}. Always written; a stored artifact may lack it. */
   readonly version: number;

package/dist/framework/Config.js

@@ -526,14 +526,36 @@ const isCopiedRow = (data) => isPlainObject(data) && typeof data.copiedFrom ===
 /** Whether a refusal is authored invariants only — the issues a replay and a hydrate let stand. */
 const customOnly = (error) => error.issues.every((issue) => issue.code === "custom");
 function coerceFieldwise(schema, member) {
-	if (!(schema instanceof z.ZodObject) || !isPlainObject(member)) return member;
+	const object = objectSchemaOf(schema);
+	if (!object || !isPlainObject(member)) return member;
 	const out = { ...member };
-	for (const [field, fieldSchema] of Object.entries(schema.shape)) {
+	const shape = object.shape;
+	const catchall = object._zod.def.catchall;
+	for (const field of new Set([...Object.keys(shape), ...Object.keys(out)])) {
+		const fieldSchema = shape[field] ?? catchall;
+		if (!fieldSchema) continue;
 		const parsed = fieldSchema.safeParse(out[field]);
-		if (parsed.success && parsed.data !== void 0) out[field] = parsed.data;
+		if (parsed.success) {
+			if (parsed.data !== void 0) out[field] = parsed.data;
+			continue;
+		}
+		if (out[field] !== void 0) out[field] = coerceFieldwise(fieldSchema, out[field]);
 	}
 	return out;
 }
+/** The object schema a field is, once the wrappers that add nothing to its keys are taken off: an
+*  optional layer bag, a nullable condition, a defaulted field, a lazy self-reference. */
+function objectSchemaOf(schema) {
+	let current = schema;
+	for (let depth = 0; depth < 8; depth += 1) {
+		if (current instanceof z.ZodObject) return current;
+		if (current instanceof z.ZodOptional || current instanceof z.ZodNullable || current instanceof z.ZodDefault || current instanceof z.ZodLazy) {
+			current = current.unwrap();
+			continue;
+		}
+		return;
+	}
+}
 var Config = class Config {
 	/** All of this config's state. `protected`, not a `#private` field, so a derived config can be
 	*  built with `Object.create` — JS private fields are installed by a constructor, and an O(1)
@@ -3492,7 +3514,14 @@ var Config = class Config {
 		if (!theirs && !overlay) return body;
 		const inherited = {};
 		const local = new Set(this.entityOf(kind)?.localGroupFields ?? []);
-		for (const [field, value] of Object.entries(theirs ?? {})) if (!local.has(field)) inherited[field] = value;
+		for (const [field, value] of Object.entries(theirs ?? {})) {
+			if (local.has(field)) continue;
+			inherited[field] = qualifyRefs({
+				value,
+				source: slug,
+				owns: (refKind) => from.entityOf(refKind) !== void 0
+			});
+		}
 		return {
 			...inherited,
 			...overlay?.override,
@@ -4807,7 +4836,7 @@ var Config = class Config {
 	*  links from the provided sources. A declared `linkedKind` with no provided source throws. */
 	hydrateFrom(stored, options) {
 		const claimed = schemaVersionOf(stored);
-		if (claimed > 20260920161309) throw new SchemaVersionTooNew(claimed);
+		if (claimed > 20260922013625) throw new SchemaVersionTooNew(claimed);
 		const wire = upgradeSerializedConfig(stored);
 		if (!Array.isArray(wire.ownedKinds) || typeof wire.items !== "object" || wire.items === null) throw new ConfigFormatError(`Config "${stored.name ?? "system-config"}" cannot be hydrated: this is not a serialized config-v2 config (no "ownedKinds"/"items"). A pre-cutover build artifact converts through the registered cutover migration — import the config type's module (e.g. \`configs/system\`) before hydrating, or port the repo once with \`uds migrate\`.`);
 		const leftover = wire.options;

package/dist/framework/defineConfig.d.ts

@@ -7,7 +7,9 @@ import { Config, HydrationOptions, ListOptions, StoredConfig, TreeNode } from ".
 import { z } from "zod";
 
 //#region src/framework/defineConfig.d.ts
-type AnyEntityClass = EntityClass<any, any, string, any, any, boolean> | DerivedEntityClass<any, any>;
+type AnyEntityClass = (Omit<EntityClass<any, any, string, any, any, boolean>, 'ref'> & {
+  readonly ref: unknown;
+}) | DerivedEntityClass<any, any>;
 /** A named map of entity classes — the shape of `entities` / `derivedEntities`. */
 type EntityMap = Record<string, AnyEntityClass>;
 /** One entity class's kind, as the literal it declared. Distributive on purpose, so a UNION of
@@ -41,7 +43,8 @@ type ConfigKind<C> = C extends {
  * which is the one shape nothing downstream can resolve. An array is a leaf too: a partial of its
  * elements describes no gesture anyone makes, and a caller replacing one writes the whole list.
  */
-type PartialBodyOf<E> = E extends EntityClass<infer F extends FieldsSchema, FieldsSchema> ? DeepPartial<CreateInput<F>> : never;
+type Matched = any;
+type PartialBodyOf<E> = E extends EntityClass<infer F extends FieldsSchema, FieldsSchema, infer _K, Matched, Matched, Matched> ? DeepPartial<CreateInput<F>> : never;
 /** Optional at every depth, stopping at refs, arrays and primitives. */
 type DeepPartial<T> = T extends Ref | readonly unknown[] ? T : T extends object ? { [K in keyof T]?: DeepPartial<T[K]> } : T;
 /**
@@ -65,7 +68,7 @@ declare function kindsOf<T extends readonly {
  *  mean. */
 type RecordFor<E> = E extends {
   readonly singleton: true;
-} ? E extends EntityClass<infer F, FieldsSchema, string, any, any, true> ? Partial<z.input<F>> : never : E extends EntityClass<infer F, infer G> ? Record<string, AuthoredEntry<F, G>> : never;
+} ? E extends EntityClass<infer F, FieldsSchema, infer _K, Matched, Matched, true> ? Partial<z.input<F>> : never : E extends EntityClass<infer F, infer G, infer _K, Matched, Matched, Matched> ? Record<string, AuthoredEntry<F, G>> : never;
 /**
  * What a config DRAWS ON — keyed by the accessor name of the kind whose items ARE the sources, valued
  * by a thunk yielding the config type each one resolves to.

package/dist/framework/defineEntity.d.ts

@@ -5,9 +5,9 @@ import { CreateInput, FieldsSchema } from "./utils/field-schema.js";
 import { FieldsCtx, UserSchemas } from "./schemas.js";
 import { SubEntityClass } from "./defineSubEntity.js";
 import { BulkOverlayWrite, BulkQuery, SourceOverlay, SourceResolutionSchemas } from "./sources.js";
-import { ComputedFields, EntityKind, Linkable } from "./registry.js";
+import { AuthoredValueForm, ComputedFields, EntityKind, Linkable } from "./registry.js";
 import { PathOf } from "./registered.js";
-import { GroupBody } from "./utils/group.js";
+import { GroupBody, GroupInputValues, GroupInputs } from "./utils/group.js";
 import { Config, ListOptions, TreeNode } from "./Config.js";
 import { z } from "zod";
 
@@ -49,6 +49,26 @@ type ItemOf<E> = E extends {
 } ? NonNullable<R> : never;
 /** An entity as a read returns it — its declared fields, plus the return type of every computed. */
 type Read<F extends FieldsSchema, C extends ComputedFields> = Entity & z.infer<F> & { readonly [K in keyof C]: ReturnType<C[K]> };
+/** What an entity's `ref` hands back: the extendable marker, with kind and path as literals. */
+type KindRef<F extends FieldsSchema, K extends string, P extends string> = ExtendableRef<Partial<CreateInput<F>>> & {
+  readonly __ref: `${K}:${P}`;
+};
+/** What a group computed reads: the config, the group's path and its stored meta. */
+interface GroupComputedInput {
+  readonly config: Config;
+  readonly path: string;
+  readonly meta: Record<string, unknown>;
+}
+/** A group node's virtual fields: `({ config, path, meta }) => value`, recomputed on every read of
+ *  `groups` and never serialized — the group-level twin of an item's `computed`. */
+type GroupComputedFields = Record<string, (input: GroupComputedInput) => unknown>;
+/** What a kind's group computeds add to a group's meta on read. */
+type GroupComputedValues<GC extends GroupComputedFields> = { readonly [K in keyof GC]: ReturnType<GC[K]> };
+/** A group node as `groups` reads it: its stored meta with the kind's group computeds attached. */
+type GroupRead<F extends FieldsSchema, G extends FieldsSchema, GC extends GroupComputedFields = Record<never, never>> = {
+  path: string;
+  meta: GroupBody<F, G> & GroupComputedValues<GC>;
+};
 type EntityClass<F extends FieldsSchema, G extends FieldsSchema,
 /** The kind as a literal, so `ref` can narrow to the paths a consumer's config declares. Defaults
  *  to `string`, which is what every 2-argument use of this type keeps getting. */
@@ -61,7 +81,13 @@ S extends UserSchemas = UserSchemas,
 C extends ComputedFields = Record<never, never>,
 /** Whether the kind has exactly one item — see `singleton` on `defineEntity`. Read off the spec so
  *  `get` can drop its path argument for exactly the kinds whose one item needs none. */
-Single extends boolean = false> = Omit<RefSchema, 'extend'> & {
+Single extends boolean = false,
+/** The kind's `groupComputed` map as written, so `Icon.groups(...)[n].meta.members` is typed off
+ *  the function that produces it. Defaults to none. */
+GC extends GroupComputedFields = Record<never, never>,
+/** The kind's `groupInputs` as written, so `group()` takes each input key at its handler's declared
+ *  type. Defaults to none. */
+GI extends GroupInputs = Record<never, never>> = Omit<RefSchema, 'extend'> & {
   readonly kind: K;
   /** Whether the kind has exactly one item — see `singleton` on `defineEntity`. A property rather than
    *  only a type parameter so a conditional type can tell the two apart: `get`'s signature differs by
@@ -81,13 +107,14 @@ Single extends boolean = false> = Omit<RefSchema, 'extend'> & {
   /** The kind-bound member-ref maker — `Component.ref('Card')` → `{ __ref: 'component:Card' }`.
    *  Called on the entity itself; a kind never re-exports it under a second, lowercase name. A
    *  singleton's one item sits at the kind's own name, so its path may be left out: `Settings.ref()`. */
-  ref(...path: Single extends true ? [path?: PathOf<K>] : [path: PathOf<K>]): ExtendableRef<Partial<CreateInput<F>>>;
+  readonly ref: Single extends true ? <P extends PathOf<K>>(path?: P) => KindRef<F, K, P> : <P extends PathOf<K>>(path: P) => KindRef<F, K, P>;
   /** Typed constructor for one item — a full body, or a bare value/ref that's shorthand
    *  for the kind's primary field. Returned as-is; `register` normalizes the shorthand. */
   item(def: CreateInput<F> | string | number | Ref): CreateInput<F> | string | number | Ref;
   /** Typed constructor for a group node — branded so `register` routes it to the group
-   *  store; input is the group fields' create body. */
-  group(meta: GroupBody<F, G>): GroupBody<F, G>;
+   *  store; input is the group fields' create body, plus any registration-time input the kind
+   *  declares (`groupInputs`), which is consumed here and never stored. */
+  group(meta: GroupBody<F, G> & GroupInputValues<GI>): GroupBody<F, G>;
   /** Resolve one item, typed off the fields — `Component.get(config, 'Button')`. Ref-aware: also
    *  accepts a `Ref` (`Node.component` → `Component.get(config, node.component)`), rejecting a
    *  wrong-kind ref. A singleton's one item sits at the kind's own name, so its path may be left out:
@@ -101,10 +128,7 @@ Single extends boolean = false> = Omit<RefSchema, 'extend'> & {
    *  depends on. The enumeration `list`/`tree` can't give: both derive from item paths, so a group
    *  declared with no members yet (a package the host supplies, which no render names) is invisible
    *  to them. */
-  groups(config: Config, opts?: ListOptions): {
-    path: string;
-    meta: GroupBody<F, G>;
-  }[];
+  groups(config: Config, opts?: ListOptions): GroupRead<F, G, GC>[];
   /** What references a given item (`kind:path` strings) — the reverse dependency graph.
    *  `{ transitive: true }` returns the whole closure rather than the direct edges, which is what
    *  a chain like `font → token → composite → component` needs: every hop is a different kind, so
@@ -152,9 +176,9 @@ Single extends boolean = false> = Omit<RefSchema, 'extend'> & {
      *  from the kind can name it — and a source writer that guesses emits the base's class into a
      *  Config that never imported it. See {@link EntityKind.entityName}. */
     entityName?: string;
-  }): EntityClass<ExtendedFields<F, F2>, ExtendedFields<G, G2>, K, S2, C, Single>;
+  }): EntityClass<ExtendedFields<F, F2>, ExtendedFields<G, G2>, K, S2, C, Single, GC, GI>;
 };
-declare function defineEntity<F extends FieldsSchema, G extends FieldsSchema = z.ZodObject<Record<never, never>>, K extends string = string, const S extends UserSchemas = Record<never, never>, const C extends ComputedFields = Record<never, never>, Single extends boolean = false>(spec: {
+declare function defineEntity<F extends FieldsSchema, G extends FieldsSchema = z.ZodObject<Record<never, never>>, K extends string = string, const S extends UserSchemas = Record<never, never>, const C extends ComputedFields = Record<never, never>, Single extends boolean = false, const GC extends GroupComputedFields = Record<never, never>, const GI extends GroupInputs = Record<never, never>>(spec: {
   kind: K;
   /** The kind's fields, or a factory over the write's context (`config`, `body`) when a field's
    *  schema depends on the config or on its sibling fields. See {@link FieldsDeclaration}. */
@@ -191,6 +215,12 @@ declare function defineEntity<F extends FieldsSchema, G extends FieldsSchema = z
    * into an artifact and then contradict the value it was derived from.
    */
   computed?: C;
+  /**
+   * Virtual fields of a GROUP node, recomputed on every `groups` read and never serialized —
+   * `({ config, path, meta }) => value`. For a fact about the set that derives from what the node
+   * and the config already hold: an icon library's members, or the module its package names.
+   */
+  groupComputed?: GC;
   /**
    * For a kind whose items name an external source: the fields that decide which source.
    *
@@ -251,7 +281,16 @@ declare function defineEntity<F extends FieldsSchema, G extends FieldsSchema = z
    * mean the ref has to say which.
    */
   bareMember?: string; /** Whether a leaf names an item on its own — see {@link EntityKind.uniqueLeaves}. */
-  uniqueLeaves?: boolean; /** Cross-item rules the kind holds — see {@link EntityKind.invariants}. */
+  uniqueLeaves?: boolean;
+  /**
+   * Registration-time inputs `group()` takes beside the group's fields, keyed by body key. Each is
+   * handed to its handler with the rest of the body and stripped before the body is branded, so the
+   * stored node, `groupFields` and the schema hash never see it. For a value that exists only while
+   * the config file is evaluated: a module namespace a library reads identities off, which no
+   * artifact can hold. See {@link GroupInputHandler}.
+   */
+  groupInputs?: GI; /** An extra authored form for a value whose domain is this kind — see {@link EntityKind.authoredValue}. */
+  authoredValue?: AuthoredValueForm; /** Cross-item rules the kind holds — see {@link EntityKind.invariants}. */
   invariants?: (config: Config) => string[];
   /**
    * For a source kind that can be resolved: the two schemas its resolutions are validated against —
@@ -302,7 +341,7 @@ declare function defineEntity<F extends FieldsSchema, G extends FieldsSchema = z
     element?: unknown;
   }[];
   rewriteName?: (data: unknown, from: string, to: string) => unknown;
-}): EntityClass<F, G, K, S, C, Single>;
+}): EntityClass<F, G, K, S, C, Single, GC, GI>;
 /**
  * The input type of one of an entity's operations — `OpInput<typeof Component, 'element-insert'>`.
  *
@@ -316,4 +355,4 @@ type OpInput<E extends {
   input: infer I extends z.ZodTypeAny;
 } ? z.input<I> : never;
 //#endregion
-export { EntityClass, ItemOf, OpInput, defineEntity };
+export { EntityClass, GroupComputedInput, ItemOf, OpInput, defineEntity };

package/dist/framework/defineEntity.js

@@ -54,10 +54,51 @@ function extendSubEntities(base, override) {
 	else if (value !== void 0) merged[key] = value;
 	return merged;
 }
+/**
+* A kind's group computeds, attached to the groups a config lists. Lazy getters, so a field nobody
+* reads is never paid for; memoized per config and per list, since `config.groups` hands back the
+* same array while nothing changed.
+*/
+function groupsWithComputedFor(computed) {
+	if (!computed || Object.keys(computed).length === 0) return (_config, groups) => groups;
+	const memo = /* @__PURE__ */ new WeakMap();
+	return (config, groups) => {
+		const hit = memo.get(groups);
+		if (hit) return hit;
+		const decorated = groups.map(({ path, meta }) => {
+			const read = { ...meta };
+			for (const [field, compute] of Object.entries(computed)) {
+				let value;
+				let done = false;
+				Object.defineProperty(read, field, {
+					enumerable: true,
+					get: () => {
+						if (!done) {
+							value = compute({
+								config,
+								path,
+								meta
+							});
+							done = true;
+						}
+						return value;
+					}
+				});
+			}
+			return {
+				path,
+				meta: read
+			};
+		});
+		memo.set(groups, decorated);
+		return decorated;
+	};
+}
 function defineEntity(spec) {
 	if (spec.kind === "config") throw new Error(`Entity kind "${CONFIG_OPERATION_KIND}" is reserved: it is the address segment of the config's own operations (\`config/info\`). Name the kind for what it holds.`);
 	const declaredGroupFields = spec.groupFields ?? z.object({});
 	const groupFields = declaredGroupFields instanceof z.ZodObject ? declaredGroupFields.extend({ ref: refSchema.optional() }) : declaredGroupFields;
+	const groupsWithComputed = groupsWithComputedFor(spec.groupComputed);
 	const kindDef = buildKind({
 		name: spec.kind,
 		fields: spec.fields,
@@ -85,6 +126,7 @@ function defineEntity(spec) {
 		styleBags: spec.styleBags,
 		rewriteName: spec.rewriteName,
 		uniqueLeaves: spec.uniqueLeaves,
+		authoredValue: spec.authoredValue,
 		invariants: spec.invariants
 	});
 	const schema = z.object({ __ref: z.string().refine((raw) => kindOf(raw) === spec.kind) }).meta({
@@ -113,7 +155,19 @@ function defineEntity(spec) {
 			return ref(spec.kind, path ?? spec.kind);
 		},
 		item: (def) => def,
-		group: (meta) => brandGroup(meta),
+		group: (meta) => {
+			const body = { ...meta };
+			for (const [key, consume] of Object.entries(spec.groupInputs ?? {})) {
+				if (!(key in body)) continue;
+				const input = body[key];
+				delete body[key];
+				consume({
+					input,
+					body
+				});
+			}
+			return brandGroup(body);
+		},
 		singleton: spec.singleton ?? false,
 		get: (config, pathOrRef) => {
 			if (pathOrRef === void 0) {
@@ -127,7 +181,7 @@ function defineEntity(spec) {
 		},
 		list: (config, opts) => config.list(spec.kind, opts),
 		tree: (config) => config.tree(spec.kind),
-		groups: (config, opts) => config.groups(spec.kind, opts),
+		groups: (config, opts) => groupsWithComputed(config, config.groups(spec.kind, opts)),
 		dependents: (config, path, opts) => config.dependentsOf(spec.kind, path, opts),
 		create: (config, path, data) => config.apply({
 			kind: spec.kind,

package/dist/framework/projections.d.ts

@@ -62,6 +62,9 @@ declare function memberLeaves(config: Config, target: string | Ref): string[];
 /** Resolve a group-bound leaf back to its qualified path (`display2` → `textVariant/display2`).
  *  `undefined` when the leaf isn't a member — what validation rejects. */
 declare function memberFromLeaf(config: Config, target: string | Ref, leaf: string): string | undefined;
+/** The refs of a domain written as a list of them, else `undefined`. A string list, a single ref
+ *  and a keyed collection all answer `undefined`, so this is the one test for the list form. */
+declare function refListOf(domain: unknown): string[] | undefined;
 declare function stylePropEntries(config: Config, path: string): StylePropEntry[];
 /**
  * A style prop's leaf value domain — what a consumer/model actually authors (`warning`, `carbon/2`),
@@ -405,6 +408,42 @@ declare function propValueDomain(config: Config, decl: PropDeclaration): {
   leaves: string[];
   accepts: (value: string) => boolean;
 } | null;
+/**
+ * The icon libraries a prop's domain delegates to, in declaration order: the group path of each
+ * `icon:` ref in the domain, whether the domain is one ref or a list of them. A facet ref
+ * (`icon:phosphor#variants`) offers the set's variants rather than its glyphs and is left out. Empty
+ * for a domain that names no library. The one reading of the edge from a component to the libraries
+ * it draws from; {@link glyphPropsOf} and {@link glyphComponentOf} both walk it.
+ */
+declare function glyphLibrariesOf(domain: unknown): string[];
+/**
+ * The props of a component that hold a glyph, each mapped to the icon libraries that are its
+ * domain, in declaration order (`{ name: ['phosphor'] }` for a component whose `name` declares
+ * `Icon.ref('phosphor')`; two entries when it declares a list). A forward onto a layer component's
+ * glyph prop (`icon` → `icon/name`, the layer an `Icon`) is one too, under the libraries that prop
+ * names. A facet ref (`icon:phosphor#variants`) offers the set's variants, not its glyphs, so it is
+ * not one.
+ *
+ * A glyph is authored as the member's component and stored as its leaf, so every surface that
+ * hands a stored value to a render — the module's routed rule props, the renderer's registry —
+ * resolves these keys back to a component through the libraries named here, taking the first that
+ * holds the leaf.
+ */
+declare function glyphPropsOf(config: Config, path: string, seen?: ReadonlySet<string>): Record<string, readonly string[]>;
+/**
+ * The component that draws a library's glyphs on their own — the one whose own prop declares the
+ * library as its domain (`name: { type: 'variant', value: Icon.ref('phosphor') }`, or a list of
+ * libraries that includes it), with that prop. Derived from the components, never declared on the
+ * set: the edge runs from the component to the library. `undefined` when no component draws from
+ * it, in which case a placed glyph is the member drawn raw.
+ *
+ * Asked per library, so a system may have one drawer binding several libraries or one drawer per
+ * library. Two components binding the same library resolve to the first in registration order.
+ */
+declare function glyphComponentOf(config: Config, library: string): {
+  path: string;
+  prop: string;
+} | undefined;
 /** Validate a prop bag against a component's declared props — unknown props + per-value domain
  *  checks. Generic: it resolves each prop's domain via {@link propValueDomain} and checks membership;
  *  no per-prop-type logic here. Returns the error strings (empty = valid). Lives in config so the
@@ -443,7 +482,6 @@ declare function validateComponentProps(config: Config, componentPath: string, p
 declare function previewDefaults(config: Config, path: string,
 /** The cell's own prop values. Given, every `preview({ when })` entry that holds for the cell —
  *  tested against the defaults under these values, as a rule's `when` is — adds its props. */
-
 cell?: Record<string, unknown>): Record<string, unknown>;
 /**
  * Only what the `preview({ when })` entries add for a cell — the props of every condition that holds
@@ -518,4 +556,4 @@ declare function propValueFromAxis(config: Config, path: string, prop: string, v
 /** The `value` a string, number or boolean prop declares as its default, per prop. */
 declare function declaredPropDefaults(props: Record<string, unknown> | undefined): Record<string, unknown>;
 //#endregion
-export { IndexedPreviewCondition, PreviewMatrix, PropDeclaration, StylePropEntry, StylePropertyItem, authoredBag, authoredValue, className, cssPropValue, cssVar, cssVarRef, declaredPropDefaults, declaredPropRouting, holdingPreviewConditions, keyedPreviewConditions, memberFromLeaf, memberLeaves, negatedCssValue, opacityPercentage, previewConditionalProps, previewConditions, previewDefaults, previewMatrix, propOwner, propValueDomain, propValueFromAxis, renderStyleValue, resolveComponentProps, resolveFieldValue, resolveTokenValue, resolveTokenValueUnder, routedBag, sourceVarPrefix, styleAliasesOf, styleDeclarations, stylePropEntries, stylePropLeafForToken, stylePropNegates, stylePropTokenGroup, stylePropTokenPath, stylePropTokenValues, stylePropValueFromLeaf, stylePropValueLeaves, stylePropValues, stylePropertiesWriting, stylePropertyAccepts, stylePropertyFor, stylePropertyPathFor, validateComponentProps };
+export { IndexedPreviewCondition, PreviewMatrix, PropDeclaration, StylePropEntry, StylePropertyItem, authoredBag, authoredValue, className, cssPropValue, cssVar, cssVarRef, declaredPropDefaults, declaredPropRouting, glyphComponentOf, glyphLibrariesOf, glyphPropsOf, holdingPreviewConditions, keyedPreviewConditions, memberFromLeaf, memberLeaves, negatedCssValue, opacityPercentage, previewConditionalProps, previewConditions, previewDefaults, previewMatrix, propOwner, propValueDomain, propValueFromAxis, refListOf, renderStyleValue, resolveComponentProps, resolveFieldValue, resolveTokenValue, resolveTokenValueUnder, routedBag, sourceVarPrefix, styleAliasesOf, styleDeclarations, stylePropEntries, stylePropLeafForToken, stylePropNegates, stylePropTokenGroup, stylePropTokenPath, stylePropTokenValues, stylePropValueFromLeaf, stylePropValueLeaves, stylePropValues, stylePropertiesWriting, stylePropertyAccepts, stylePropertyFor, stylePropertyPathFor, validateComponentProps };

package/dist/framework/projections.js

@@ -187,6 +187,12 @@ function memberLeaves(config, target) {
 function memberFromLeaf(config, target, leaf) {
 	return memberEntries(config, target).find((entry) => entry.leaf === leaf)?.path;
 }
+/** The refs of a domain written as a list of them, else `undefined`. A string list, a single ref
+*  and a keyed collection all answer `undefined`, so this is the one test for the list form. */
+function refListOf(domain) {
+	if (!Array.isArray(domain) || domain.length === 0 || !domain.every(isRef)) return;
+	return domain.map((entry) => entry.__ref);
+}
 function stylePropEntries(config, path) {
 	const cache = domainCache(stylePropEntryCache, config);
 	const hit = cache.get(path);
@@ -843,9 +849,10 @@ function propOwner(config, path, prop, seen = /* @__PURE__ */ new Set()) {
 function propValueDomain(config, decl) {
 	const domainRef = () => decl.value?.__ref;
 	if (decl.type === "variant") {
-		const target = domainRef();
-		if (target) {
-			const leaves = memberLeaves(config, target);
+		const single = domainRef();
+		const targets = refListOf(decl.value) ?? (single ? [single] : []);
+		if (targets.length > 0) {
+			const leaves = [...new Set(targets.flatMap((target) => memberLeaves(config, target)))];
 			if (leaves.length === 0) return null;
 			return {
 				leaves,
@@ -881,6 +888,93 @@ function propValueDomain(config, decl) {
 	}
 	return null;
 }
+/**
+* The icon libraries a prop's domain delegates to, in declaration order: the group path of each
+* `icon:` ref in the domain, whether the domain is one ref or a list of them. A facet ref
+* (`icon:phosphor#variants`) offers the set's variants rather than its glyphs and is left out. Empty
+* for a domain that names no library. The one reading of the edge from a component to the libraries
+* it draws from; {@link glyphPropsOf} and {@link glyphComponentOf} both walk it.
+*/
+function glyphLibrariesOf(domain) {
+	return (refListOf(domain) ?? (isRef(domain) ? [domain.__ref] : [])).filter((ref) => kindOf(ref) === "icon" && memberOf(ref) === void 0).map(pathOf);
+}
+/**
+* The props of a component that hold a glyph, each mapped to the icon libraries that are its
+* domain, in declaration order (`{ name: ['phosphor'] }` for a component whose `name` declares
+* `Icon.ref('phosphor')`; two entries when it declares a list). A forward onto a layer component's
+* glyph prop (`icon` → `icon/name`, the layer an `Icon`) is one too, under the libraries that prop
+* names. A facet ref (`icon:phosphor#variants`) offers the set's variants, not its glyphs, so it is
+* not one.
+*
+* A glyph is authored as the member's component and stored as its leaf, so every surface that
+* hands a stored value to a render — the module's routed rule props, the renderer's registry —
+* resolves these keys back to a component through the libraries named here, taking the first that
+* holds the leaf.
+*/
+function glyphPropsOf(config, path, seen = /* @__PURE__ */ new Set()) {
+	return glyphPropsOfBody({
+		config,
+		body: config.resolve("component", path)?.toJSON(),
+		seen: new Set([...seen, path])
+	});
+}
+/**
+* {@link glyphPropsOf} over a body in hand rather than a stored path: what a member schema has while
+* the owner is being written, before or without a path to resolve it by. `seen` holds the paths
+* already on the way down, the owner's own included.
+*/
+function glyphPropsOfBody({ config, body, seen = /* @__PURE__ */ new Set() }) {
+	const { props = {}, layers = {} } = body ?? {};
+	const out = {};
+	for (const [prop, declaration] of Object.entries(props)) {
+		const domain = declaration?.value;
+		if (isRef(domain) || refListOf(domain) !== void 0) {
+			const libraries = glyphLibrariesOf(domain);
+			if (libraries.length > 0) out[prop] = libraries;
+			continue;
+		}
+		const target = declaration?.target;
+		if (declaration?.type !== "forward" || !isRef(target) || kindOf(target) !== "layer") continue;
+		const element = layers[pathOf(target)];
+		if (!isRef(element) || kindOf(element) !== "component") continue;
+		const receiver = pathOf(element);
+		if (seen.has(receiver)) continue;
+		const libraries = glyphPropsOf(config, receiver, seen)[forwardIntoName(declaration.into, prop)];
+		if (libraries) out[prop] = libraries;
+	}
+	return out;
+}
+/**
+* The component that draws a library's glyphs on their own — the one whose own prop declares the
+* library as its domain (`name: { type: 'variant', value: Icon.ref('phosphor') }`, or a list of
+* libraries that includes it), with that prop. Derived from the components, never declared on the
+* set: the edge runs from the component to the library. `undefined` when no component draws from
+* it, in which case a placed glyph is the member drawn raw.
+*
+* Asked per library, so a system may have one drawer binding several libraries or one drawer per
+* library. Two components binding the same library resolve to the first in registration order.
+*/
+function glyphComponentOf(config, library) {
+	for (const component of config.list("component")) {
+		const { props = {} } = component.toJSON();
+		for (const [prop, declaration] of Object.entries(props)) {
+			if (declaration?.type !== "variant") continue;
+			if (!glyphLibrariesOf(declaration.value).includes(library)) continue;
+			return {
+				path: component.path,
+				prop
+			};
+		}
+	}
+}
+/** The receiver prop a forward lands in: as spelled, the leaf of the member ref it names
+*  (`component:Icon#props/name` → `name`), or the forward's own name when it names none. */
+function forwardIntoName(into, own) {
+	if (typeof into === "string") return into;
+	if (!isRef(into)) return own;
+	const member = memberOf(into) ?? into.__ref;
+	return member.slice(member.indexOf("/") + 1);
+}
 /** Validate a prop bag against a component's declared props — unknown props + per-value domain
 *  checks. Generic: it resolves each prop's domain via {@link propValueDomain} and checks membership;
 *  no per-prop-type logic here. Returns the error strings (empty = valid). Lives in config so the
@@ -1045,7 +1139,7 @@ function previewMatrix(config, path) {
 		}
 		if (decl?.type === "boolean" && props[name]) props[name] = declaredFirst(["false", "true"], props[name] ?? []);
 		if (decl?.type === "variant") {
-			const values = declaredFirst(isRef(decl.value) ? [] : listedIn(decl.value) ?? [], props[name] ?? []);
+			const values = declaredFirst(isRef(decl.value) || refListOf(decl.value) !== void 0 ? [] : listedIn(decl.value) ?? [], props[name] ?? []);
 			if (values.length > 0) props[name] = values;
 		}
 	}
@@ -1087,4 +1181,4 @@ function declaredPropDefaults(props) {
 	return out;
 }
 //#endregion
-export { authoredBag, authoredValue, className, cssPropValue, cssVar, cssVarRef, declaredPropDefaults, declaredPropRouting, holdingPreviewConditions, keyedPreviewConditions, memberFromLeaf, memberLeaves, negatedCssValue, opacityPercentage, previewConditionalProps, previewConditions, previewDefaults, previewMatrix, propOwner, propValueDomain, propValueFromAxis, renderStyleValue, resolveComponentProps, resolveFieldValue, resolveTokenValue, resolveTokenValueUnder, routedBag, sourceVarPrefix, styleAliasesOf, styleDeclarations, stylePropEntries, stylePropLeafForToken, stylePropNegates, stylePropTokenGroup, stylePropTokenPath, stylePropTokenValues, stylePropValueFromLeaf, stylePropValueLeaves, stylePropValues, stylePropertiesWriting, stylePropertyAccepts, stylePropertyFor, stylePropertyPathFor, validateComponentProps };
+export { authoredBag, authoredValue, className, cssPropValue, cssVar, cssVarRef, declaredPropDefaults, declaredPropRouting, glyphComponentOf, glyphLibrariesOf, glyphPropsOf, glyphPropsOfBody, holdingPreviewConditions, keyedPreviewConditions, memberFromLeaf, memberLeaves, negatedCssValue, opacityPercentage, previewConditionalProps, previewConditions, previewDefaults, previewMatrix, propOwner, propValueDomain, propValueFromAxis, refListOf, renderStyleValue, resolveComponentProps, resolveFieldValue, resolveTokenValue, resolveTokenValueUnder, routedBag, sourceVarPrefix, styleAliasesOf, styleDeclarations, stylePropEntries, stylePropLeafForToken, stylePropNegates, stylePropTokenGroup, stylePropTokenPath, stylePropTokenValues, stylePropValueFromLeaf, stylePropValueLeaves, stylePropValues, stylePropertiesWriting, stylePropertyAccepts, stylePropertyFor, stylePropertyPathFor, validateComponentProps };

package/dist/framework/prop-surface.d.ts

@@ -16,11 +16,12 @@ interface SurfaceVariantProp extends SurfacePropBase {
   readonly kind: 'variant';
   /** The values it offers, as the leaves a consumer authors. */
   readonly values: string[];
-  /** An icon LIBRARY the values delegate to, when the domain is the group itself — a surface
-   *  offers the glyph picker rather than a select over every member. A FACET ref
-   *  (`icon:phosphor#variants`) stays a plain list: its leaves are the group node's own field
-   *  values, a menu-sized set. Mirrors {@link SurfaceSlotProp.acceptsIconLibrary}. */
-  readonly iconLibrary?: string;
+  /** The icon libraries the values delegate to, when the domain is a group itself or a list of
+   *  groups — a surface offers the glyph picker rather than a select over every member, with a
+   *  library switcher when there is more than one. A facet ref (`icon:phosphor#variants`) stays a
+   *  plain list: its leaves are the group node's own field values, a menu-sized set. Mirrors
+   *  {@link SurfaceSlotProp.acceptsIconLibrary}. */
+  readonly iconLibraries?: readonly string[];
 }
 interface SurfaceStylePropertyProp extends SurfacePropBase {
   readonly kind: 'styleProperty';