@yahoo/uds-create-config 4.12.0 → 4.12.1

package/dist/configs/react-native-system.d.ts

@@ -1442,6 +1442,10 @@ declare const ReactNativeSystem: ConfigClass<{
       }, _$zod_v4_core0.$strip>;
       default: _$zod.ZodOptional<_$zod.ZodBoolean>;
       defaultProps: _$zod.ZodOptional<_$zod.ZodRecord<_$zod.ZodString, _$zod.ZodUnknown>>;
+      props: _$zod.ZodOptional<_$zod.ZodObject<{
+        glyph: _$zod.ZodString;
+        axes: _$zod.ZodOptional<_$zod.ZodArray<_$zod.ZodString>>;
+      }, _$zod_v4_core0.$strip>>;
     }, _$zod_v4_core0.$strip>>;
   }, _$zod_v4_core0.$strip>, _$zod.ZodObject<Record<never, never>, _$zod_v4_core0.$strip>, "canvas-role", {
     readonly create: {
@@ -3268,6 +3272,10 @@ declare const ReactNativeSystem: ConfigClass<{
         }, _$zod_v4_core0.$strip>;
         default: _$zod.ZodOptional<_$zod.ZodBoolean>;
         defaultProps: _$zod.ZodOptional<_$zod.ZodRecord<_$zod.ZodString, _$zod.ZodUnknown>>;
+        props: _$zod.ZodOptional<_$zod.ZodObject<{
+          glyph: _$zod.ZodString;
+          axes: _$zod.ZodOptional<_$zod.ZodArray<_$zod.ZodString>>;
+        }, _$zod_v4_core0.$strip>>;
       }, _$zod_v4_core0.$strip>>;
     }, _$zod_v4_core0.$strip>, _$zod.ZodObject<Record<never, never>, _$zod_v4_core0.$strip>, "canvas-role", {
       readonly create: {

package/dist/configs/system.d.ts

@@ -1296,6 +1296,10 @@ declare const System: ConfigClass<{
       }, _$zod_v4_core0.$strip>;
       default: _$zod.ZodOptional<_$zod.ZodBoolean>;
       defaultProps: _$zod.ZodOptional<_$zod.ZodRecord<_$zod.ZodString, _$zod.ZodUnknown>>;
+      props: _$zod.ZodOptional<_$zod.ZodObject<{
+        glyph: _$zod.ZodString;
+        axes: _$zod.ZodOptional<_$zod.ZodArray<_$zod.ZodString>>;
+      }, _$zod_v4_core0.$strip>>;
     }, _$zod_v4_core0.$strip>>;
   }, _$zod_v4_core0.$strip>, _$zod.ZodObject<Record<never, never>, _$zod_v4_core0.$strip>, "canvas-role", {
     readonly create: {
@@ -2994,6 +2998,10 @@ declare const System: ConfigClass<{
         }, _$zod_v4_core0.$strip>;
         default: _$zod.ZodOptional<_$zod.ZodBoolean>;
         defaultProps: _$zod.ZodOptional<_$zod.ZodRecord<_$zod.ZodString, _$zod.ZodUnknown>>;
+        props: _$zod.ZodOptional<_$zod.ZodObject<{
+          glyph: _$zod.ZodString;
+          axes: _$zod.ZodOptional<_$zod.ZodArray<_$zod.ZodString>>;
+        }, _$zod_v4_core0.$strip>>;
       }, _$zod_v4_core0.$strip>>;
     }, _$zod_v4_core0.$strip>, _$zod.ZodObject<Record<never, never>, _$zod_v4_core0.$strip>, "canvas-role", {
       readonly create: {

package/dist/configs/system.js

@@ -35,6 +35,7 @@ import { previewConditionsKeyedMigration } from "../migrations/20260920004019_pr
 import { prefixedTokenGroupMigration } from "../migrations/20260920161309_prefixed_token_group.js";
 import { iconLibraryWithoutComponentMigration } from "../migrations/20260921044042_icon_library_without_component.js";
 import { iconLibrariesMigration } from "../migrations/20260922013625_icon_libraries.js";
+import { iconCanvasToolMigration } from "../migrations/20260923005318_icon_canvas_tool.js";
 //#region src/configs/system.ts
 /**
 * `System` — the design-system config TYPE. Declares the exact kinds a design system owns (tokens,
@@ -90,5 +91,6 @@ if (!registeredSchemaMigrations().has(20260920004019)) registerSchemaMigrations(
 if (!registeredSchemaMigrations().has(20260920161309)) registerSchemaMigrations(prefixedTokenGroupMigration);
 if (!registeredSchemaMigrations().has(20260921044042)) registerSchemaMigrations(iconLibraryWithoutComponentMigration);
 if (!registeredSchemaMigrations().has(20260922013625)) registerSchemaMigrations(iconLibrariesMigration);
+if (!registeredSchemaMigrations().has(20260923005318)) registerSchemaMigrations(iconCanvasToolMigration);
 //#endregion
 export { System };

package/dist/entities/system/CanvasRole.d.ts

@@ -15,7 +15,7 @@ import { z } from "zod";
  * one ("mirrors `@yahoo/uds-create-config`'s `CanvasRole` union without importing it") — a second
  * source of truth wearing a comment admitting it.
  */
-declare const CANVAS_ROLES: readonly ["frame", "text", "image"];
+declare const CANVAS_ROLES: readonly ["frame", "text", "image", "icon"];
 type CanvasRoleName = (typeof CANVAS_ROLES)[number];
 declare const CanvasRole: EntityClass<z.ZodObject<{
   entries: z.ZodArray<z.ZodObject<{
@@ -24,6 +24,10 @@ declare const CanvasRole: EntityClass<z.ZodObject<{
     }, z.core.$strip>;
     default: z.ZodOptional<z.ZodBoolean>;
     defaultProps: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    props: z.ZodOptional<z.ZodObject<{
+      glyph: z.ZodString;
+      axes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
   }, z.core.$strip>>;
 }, z.core.$strip>, z.ZodObject<Record<never, never>, z.core.$strip>, "canvas-role", {
   readonly create: {

package/dist/entities/system/CanvasRole.js

@@ -30,14 +30,19 @@ import { z } from "zod";
 const CANVAS_ROLES = [
 	"frame",
 	"text",
-	"image"
+	"image",
+	"icon"
 ];
 const CanvasRole = defineEntity({
 	kind: "canvas-role",
 	fields: z.object({ entries: z.array(z.object({
 		component: Component.describe("The component this tool inserts, as a ref: `{ \"__ref\": \"component:<path>\" }`."),
 		default: z.boolean().optional().describe("The entry the tool inserts when none is chosen; mark one."),
-		defaultProps: z.record(z.string(), z.unknown()).optional().describe("Props the inserted component starts with, keyed by prop name.")
+		defaultProps: z.record(z.string(), z.unknown()).optional().describe("Props the inserted component starts with, keyed by prop name."),
+		props: z.object({
+			glyph: z.string().describe("The prop that takes the glyph: one whose domain is an icon library (`name: { type: \"variant\", value: Icon.ref(\"icons\") }`). Its libraries are what the picker offers."),
+			axes: z.array(z.string()).optional().describe("The props the picker offers as axes (`variant`, `size`), each with the values the prop itself declares.")
+		}).optional().describe("What the tool exposes of the component. Read by the `icon` role: the picker draws every glyph through this component and offers the named props as its axes.")
 	})).describe(`The components a canvas insert tool draws with. The entity's path is the tool: one of ${CANVAS_ROLES.map((role) => `\`${role}\``).join(", ")}. A role with no entity registered has its tool disabled.`) }),
 	schemas: { create: { description: `Register a canvas insert tool for this system. \`path\` is the role, one of ${CANVAS_ROLES.map((role) => `\`${role}\``).join(", ")}; \`data.entries\` names the components that tool inserts, one marked \`default\`. A system whose roles are unregistered has those canvas tools disabled, so register \`frame\` and \`text\` once a layout primitive and a text primitive exist.` } }
 });

package/dist/entities/system/Icon.d.ts

@@ -12,11 +12,13 @@ import { z } from "zod";
  *  - `{ export: { filled: '{name}Filled' } }`: a variant is another export, named by the template
  *    with `{name}` replaced by the member's name; a variant not listed draws the bare export (Tabler).
  */
+/** @deprecated With the group's `variantAs`; see there. */
 declare const iconVariantAs: z.ZodUnion<readonly [z.ZodObject<{
   prop: z.ZodString;
 }, z.core.$strict>, z.ZodObject<{
   export: z.ZodRecord<z.ZodString, z.ZodString>;
 }, z.core.$strict>]>;
+/** @deprecated With the group's `variantAs`; see there. */
 type IconVariantAs = z.infer<typeof iconVariantAs>;
 /**
  * Icon (`icons/AcornIcon`) — one glyph in an icon library. The library (`icons`) is an EMERGENT group

package/dist/entities/system/Icon.js

@@ -14,6 +14,7 @@ import { z } from "zod";
 *  - `{ export: { filled: '{name}Filled' } }`: a variant is another export, named by the template
 *    with `{name}` replaced by the member's name; a variant not listed draws the bare export (Tabler).
 */
+/** @deprecated With the group's `variantAs`; see there. */
 const iconVariantAs = z.union([z.strictObject({ prop: z.string().min(1) }), z.strictObject({ export: z.record(z.string().min(1), z.string().min(1)) })]);
 /**
 * Icon (`icons/AcornIcon`) — one glyph in an icon library. The library (`icons`) is an EMERGENT group
@@ -44,12 +45,17 @@ const Icon = defineEntity({
 		/** Where member metadata comes from and how to read it — `{ from, format }`. The build resolves
 		*  the source and bakes each member's fields; see `icon-metadata.ts`. */
 		metadata: iconMetadataDeclaration.optional(),
-		/** Named sizes the set ships (`sm: 16`). */
+		/** Named sizes the set ships (`sm: 16`).
+		*  @deprecated How a glyph is sized is the icon tool's component's business: the icon tool's component declares its own `size` and `variant` props, and every surface reads those. TODO: remove with a migration once no surface reads the library's copy. */
 		sizes: z.record(z.string(), z.number()).optional(),
-		/** Weights/styles the set ships (`regular`, `fill`). */
+		/** Weights/styles the set ships (`regular`, `fill`).
+		*  @deprecated Which styles a glyph takes is the icon tool's component's business: the icon tool's component declares its own `size` and `variant` props, and every surface reads those. TODO: remove with a migration once no surface reads the library's copy. */
 		variants: z.array(z.string()).optional(),
 		/** How a variant reaches the glyph; see {@link iconVariantAs}. Absent, a variant is dropped at
-		*  render. */
+		*  render.
+		*  @deprecated Only the framework's raw-draw path read it; the icon tool's component passes a
+		*  variant the way its package wants, and a set whose styles are separate exports lists them as
+		*  members. TODO: remove with `sizes` and `variants`. */
 		variantAs: iconVariantAs.optional()
 	}),
 	groupComputed: {

package/dist/entities/system/defineComponent.d.ts

@@ -247,10 +247,13 @@ type ValueOf<D> = D extends readonly (infer Member)[] ? Member : D extends {
 /**
  * A glyph as a value: the component an icon library exports. Its `displayName` is the member it is,
  * which is what register stores (`icon:phosphor/XIcon`) and what the renderer resolves back to the
- * component. Sizing is the placing component's business, so the one prop every glyph takes is `size`.
+ * component. Sizing is the placing component's business, and the vocabulary of `size` is the
+ * library's own (one package takes pixels, another a named bucket), so the type states nothing about
+ * it: with the default any glyph fits, and a component that knows its library narrows
+ * (`GlyphComponent<number>`).
  */
-type GlyphComponent = ComponentType<{
-  size?: number;
+type GlyphComponent<Size extends string | number = never> = ComponentType<{
+  size?: Size;
 }>;
 /**
  * The members a ref-delegated domain offers, read off the registered paths: a variant whose domain

package/dist/entities/system/icon-library.d.ts

@@ -5,24 +5,30 @@ import { Icon, IconVariantAs } from "./Icon.js";
 /**
  * An icon library as its group node reads: the path, the stored set facts (`sizes`, `variants`,
  * `package`, `variantAs`, `metadata`) and the computeds the entity declares (`members`, `module`,
- * `version`), plus the per-member and drawer-side facts this projection derives. Typed off
+ * `version`), plus the per-member and component-side facts this projection derives. Typed off
  * `Icon.groups`, so a field added on the entity is visible here without a second declaration.
  */
 type IconLibrary = {
   readonly path: string;
 } & Undefinable<Omit<ReturnType<typeof Icon.groups>[number]['meta'], 'items' | 'sizes' | 'variants'>> & {
+  /** @deprecated The library's copy of what the icon tool's component declares as `size`. TODO: remove
+   *  with the group field. */
   readonly sizes: Readonly<Record<string, number>>;
+  /** @deprecated The library's copy of what the icon tool's component declares as `variant`. TODO:
+   *  remove with the group field. */
   readonly variants: readonly string[];
   /** For a ragged set, the members whose own `variants` differ from the set's, by leaf. A member
    *  listing exactly the set's variants is left out, so the map stays as sparse as the
    *  raggedness. */
   readonly memberVariants?: Readonly<Record<string, readonly string[]>>;
-  /** The variant the library's drawer declares in its `defaultProps` — what a picker seeds when nothing is
+  /** The variant the component bound to the library declares in its `defaultProps` — what a picker seeds when nothing is
    *  stored. Passed through as declared; a policy read validates it against {@link variants}
-   *  before trusting it. */
+   *  before trusting it.
+   *  @deprecated The icon tool's entry carries `defaultProps`; read them through `iconToolOf`. */
   readonly defaultVariant?: string;
-  /** The size bucket the library's drawer declares in its `defaultProps`. Same contract as
-   *  {@link defaultVariant}: declared, not validated. */
+  /** The size bucket the component bound to the library declares in its `defaultProps`. Same contract as
+   *  {@link defaultVariant}: declared, not validated.
+   *  @deprecated As {@link defaultVariant}. */
   readonly defaultSizeKey?: string;
 };
 /** A field that may hold `undefined` may be left out: a computed's `string | undefined` reads as an
@@ -39,6 +45,8 @@ declare function iconLibrary(config: Config | null | undefined, path: string): I
  * With `variants`, the member's own list, only the templates for variants it ships are added: a
  * ragged set's member has no export for the rest, and naming one fails the module's bundle.
  */
+/** @deprecated Reads `variantAs`, which goes with it; a set whose styles are separate exports lists
+ *  them as members, and codegen imports members. */
 declare function glyphExportNames({
   variantAs,
   name,
@@ -85,6 +93,11 @@ declare function resolveIconLibraries({
  * binds nothing — `glyphLibrariesOf` is the one reading of the edge, shared with
  * {@link glyphComponentOf}.
  */
+/**
+ * The libraries the canvas's icon tool offers: those its component's glyph prop is bound to. Empty
+ * when the `icon` canvas role is unregistered, which is also when the tool is disabled.
+ */
+declare function iconToolLibraries(config: Config | null | undefined): IconLibrary[];
 declare function librariesBoundBy({
   config,
   component
@@ -112,6 +125,8 @@ declare function iconCategories(config: Config | null | undefined, libraryPath:
  * same across glyphs. A member listing only variants the set doesn't ship falls back to the set's,
  * so the axis is never empty for a set that ships one.
  */
+/** @deprecated The axis is the icon tool's (`iconToolAxisOptions`); a member's own `variants` stay
+ *  metadata to narrow it by. TODO: rewrite the callers over the tool and remove. */
 declare function memberVariantOptions(library: IconLibrary, member: string): readonly string[];
 /**
  * Whether an element type declares a prop that may survive layer-style projection. A placed
@@ -120,4 +135,4 @@ declare function memberVariantOptions(library: IconLibrary, member: string): rea
  */
 declare function isDeclaredElementProp(config: Config | null | undefined, elementType: string, propName: string): boolean;
 //#endregion
-export { IconLibrary, glyphExportNames, glyphType, iconCategories, iconLibraries, iconLibrary, isDeclaredElementProp, librariesBoundBy, libraryHolding, memberVariantOptions, placedGlyphElement, resolveIconLibraries };
+export { IconLibrary, glyphExportNames, glyphType, iconCategories, iconLibraries, iconLibrary, iconToolLibraries, isDeclaredElementProp, librariesBoundBy, libraryHolding, memberVariantOptions, placedGlyphElement, resolveIconLibraries };

package/dist/entities/system/icon-library.js

@@ -1,5 +1,5 @@
 import { createSliceMemo } from "../../framework/memo.js";
-import { glyphComponentOf, glyphLibrariesOf, resolveComponentProps } from "../../framework/projections.js";
+import { glyphComponentOf, glyphLibrariesOf, iconToolOf, resolveComponentProps } from "../../framework/projections.js";
 import { Component } from "./Component.js";
 import { parseGlyphType } from "../../spec/glyph-jsx.js";
 import { Icon } from "./Icon.js";
@@ -17,7 +17,7 @@ import { Icon } from "./Icon.js";
 *
 * This is the one home for the question "what icon sets does this system have" — Studio owns only
 * UI policy on top (picker state, grid geometry, recents, search ranking). A library is cached on
-* the slices it reads — the set (`icon`), its drawer's defaults (`component`) and the package row
+* the slices it reads — the set (`icon`), its component's defaults (`component`) and the package row
 * its version comes from (`package`) — so it is reference-stable across calls on one config and
 * safe in a dep array.
 */
@@ -40,7 +40,7 @@ function iconLibrary(config, path) {
 }
 /** Per-config cache of {@link iconLibrary} answers. `package` is in the key because the set's
 *  `version` resolves through the package row, not off the group node. The member walk underneath
-*  keys on the icon slice alone, so a component write re-reads only each library's drawer defaults. */
+*  keys on the icon slice alone, so a component write re-reads only each library's component defaults. */
 const librariesOf = createSliceMemo({
 	kinds: [
 		"icon",
@@ -65,21 +65,24 @@ function readIconLibrary(config, path) {
 		sizes: sizes ?? EMPTY_SIZES,
 		variants: variants ?? EMPTY_VARIANTS,
 		...set.memberVariants ? { memberVariants: set.memberVariants } : {},
-		...drawerDefaults({
+		...componentDefaults({
 			config,
 			library: path
 		})
 	};
 }
 /**
-* The defaults the set's drawer declares: the component whose own variant prop names this library
+* The defaults the set's component declares: the component whose own variant prop names this library
 * carries "what a bare glyph looks like", read back here so every picker seeds from that one
 * declaration rather than its own literal. A library no component draws from has no defaults.
+*
+* @deprecated The icon tool's entry carries `defaultProps`. TODO: remove with `defaultVariant` and
+* `defaultSizeKey`.
 */
-function drawerDefaults({ config, library }) {
-	const drawer = glyphComponentOf(config, library);
-	if (!drawer) return {};
-	const defaults = Component.get(config, drawer.path)?.defaultProps;
+function componentDefaults({ config, library }) {
+	const bound = glyphComponentOf(config, library);
+	if (!bound) return {};
+	const defaults = Component.get(config, bound.path)?.defaultProps;
 	const variant = defaults?.variant;
 	const size = defaults?.size;
 	return {
@@ -133,6 +136,8 @@ function sameVariants({ own, declared }) {
 * With `variants`, the member's own list, only the templates for variants it ships are added: a
 * ragged set's member has no export for the rest, and naming one fails the module's bundle.
 */
+/** @deprecated Reads `variantAs`, which goes with it; a set whose styles are separate exports lists
+*  them as members, and codegen imports members. */
 function glyphExportNames({ variantAs, name, variants }) {
 	const names = new Set([name]);
 	if (variantAs && "export" in variantAs) for (const [variant, template] of Object.entries(variantAs.export)) {
@@ -151,15 +156,18 @@ function glyphExportNames({ variantAs, name, variants }) {
 */
 function placedGlyphElement(config, glyph, props = {}) {
 	const parsed = parseGlyphType(glyph);
-	const drawer = parsed && config ? glyphComponentOf(config, parsed.slug) : void 0;
-	if (!parsed || !drawer) return {
+	const bound = parsed && config ? glyphComponentOf(config, parsed.slug) : void 0;
+	if (!parsed || !bound || !config) return {
 		type: glyph,
 		props
 	};
+	const tool = iconToolOf(config);
+	const defaults = tool && tool.component === bound.path ? tool.defaultProps : {};
 	return {
-		type: `component:${drawer.path}`,
+		type: `component:${bound.path}`,
 		props: {
-			[drawer.prop]: parsed.member,
+			...defaults,
+			[bound.prop]: parsed.member,
 			...props
 		}
 	};
@@ -197,6 +205,17 @@ function resolveIconLibraries({ config, hints }) {
 * binds nothing — `glyphLibrariesOf` is the one reading of the edge, shared with
 * {@link glyphComponentOf}.
 */
+/**
+* The libraries the canvas's icon tool offers: those its component's glyph prop is bound to. Empty
+* when the `icon` canvas role is unregistered, which is also when the tool is disabled.
+*/
+function iconToolLibraries(config) {
+	if (!config) return NO_LIBRARIES;
+	const tool = iconToolOf(config);
+	if (!tool) return NO_LIBRARIES;
+	const declaration = resolveComponentProps(config, tool.component)[tool.glyph];
+	return glyphLibrariesOf(declaration?.value).map((path) => iconLibrary(config, path)).filter((library) => library !== void 0);
+}
 function librariesBoundBy({ config, component }) {
 	if (!config) return NO_LIBRARIES;
 	const cache = boundLibrariesOf(config);
@@ -253,6 +272,8 @@ function iconCategories(config, libraryPath) {
 * same across glyphs. A member listing only variants the set doesn't ship falls back to the set's,
 * so the axis is never empty for a set that ships one.
 */
+/** @deprecated The axis is the icon tool's (`iconToolAxisOptions`); a member's own `variants` stay
+*  metadata to narrow it by. TODO: rewrite the callers over the tool and remove. */
 function memberVariantOptions(library, member) {
 	const own = library.memberVariants?.[member];
 	if (!own || own.length === 0) return library.variants;
@@ -281,4 +302,4 @@ function isDeclaredElementProp(config, elementType, propName) {
 	return false;
 }
 //#endregion
-export { glyphExportNames, glyphType, iconCategories, iconLibraries, iconLibrary, isDeclaredElementProp, librariesBoundBy, libraryHolding, memberVariantOptions, placedGlyphElement, resolveIconLibraries };
+export { glyphExportNames, glyphType, iconCategories, iconLibraries, iconLibrary, iconToolLibraries, isDeclaredElementProp, librariesBoundBy, libraryHolding, memberVariantOptions, placedGlyphElement, resolveIconLibraries };

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 = 20260922013625;
+declare const SERIALIZED_CONFIG_VERSION = 20260923005318;
 interface SerializedConfig {
   /** See {@link SERIALIZED_CONFIG_VERSION}. Always written; a stored artifact may lack it. */
   readonly version: number;

package/dist/framework/Config.js

@@ -4836,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 > 20260922013625) throw new SchemaVersionTooNew(claimed);
+		if (claimed > 20260923005318) 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/projections.d.ts

@@ -431,13 +431,31 @@ declare function glyphLibrariesOf(domain: unknown): string[];
  */
 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
+ * The canvas's icon tool: the `icon` canvas role's entry, as the component it inserts, the prop that
+ * takes the glyph, the props the picker offers as axes, and the props an inserted instance starts
+ * with. The default entry, else the first; `undefined` when the role is unregistered or its entry
+ * names no glyph prop, which disables the tool.
+ */
+interface IconTool {
+  readonly component: string;
+  readonly glyph: string;
+  readonly axes: readonly string[];
+  readonly defaultProps: Readonly<Record<string, unknown>>;
+}
+declare function iconToolOf(config: Config): IconTool | undefined;
+/** The values an icon tool's axis offers: the leaves of that prop's own domain on the tool's
+ *  component, whether it enumerates them or delegates to a library's facet. */
+declare function iconToolAxisOptions(config: Config, tool: IconTool, axis: string): string[];
+/**
+ * The component that draws a library's glyphs on their own, with the prop that takes the glyph. The
+ * icon tool's component when the `icon` canvas role names one whose glyph prop is bound to the
+ * library; otherwise the component whose own prop declares the library as its domain
+ * (`name: { type: 'variant', value: Icon.ref('phosphor') }`, or a list of libraries that includes
+ * it). 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 component binding several libraries or one per
  * library. Two components binding the same library resolve to the first in registration order.
  */
 declare function glyphComponentOf(config: Config, library: string): {
@@ -482,6 +500,7 @@ 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
@@ -556,4 +575,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, 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 };
+export { IconTool, IndexedPreviewCondition, PreviewMatrix, PropDeclaration, StylePropEntry, StylePropertyItem, authoredBag, authoredValue, className, cssPropValue, cssVar, cssVarRef, declaredPropDefaults, declaredPropRouting, glyphComponentOf, glyphLibrariesOf, glyphPropsOf, holdingPreviewConditions, iconToolAxisOptions, iconToolOf, 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

@@ -944,17 +944,46 @@ function glyphPropsOfBody({ config, body, seen = /* @__PURE__ */ new Set() }) {
 	}
 	return out;
 }
+function iconToolOf(config) {
+	const entries = (config.resolve("canvas-role", "icon")?.toJSON())?.entries ?? [];
+	const entry = entries.find((candidate) => candidate.default) ?? entries[0];
+	const glyph = entry?.props?.glyph;
+	if (!entry || !glyph || !isRef(entry.component)) return void 0;
+	return {
+		component: pathOf(entry.component),
+		glyph,
+		axes: entry.props?.axes ?? [],
+		defaultProps: entry.defaultProps ?? {}
+	};
+}
+/** The values an icon tool's axis offers: the leaves of that prop's own domain on the tool's
+*  component, whether it enumerates them or delegates to a library's facet. */
+function iconToolAxisOptions(config, tool, axis) {
+	const declaration = resolveComponentProps(config, tool.component)[axis];
+	if (!declaration) return [];
+	return propValueDomain(config, declaration)?.leaves ?? [];
+}
 /**
-* 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.
+* The component that draws a library's glyphs on their own, with the prop that takes the glyph. The
+* icon tool's component when the `icon` canvas role names one whose glyph prop is bound to the
+* library; otherwise the component whose own prop declares the library as its domain
+* (`name: { type: 'variant', value: Icon.ref('phosphor') }`, or a list of libraries that includes
+* it). 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
+* Asked per library, so a system may have one component binding several libraries or one per
 * library. Two components binding the same library resolve to the first in registration order.
 */
 function glyphComponentOf(config, library) {
+	const tool = iconToolOf(config);
+	if (tool) {
+		const declaration = resolveComponentProps(config, tool.component)[tool.glyph];
+		if (declaration && glyphLibrariesOf(declaration.value).includes(library)) return {
+			path: tool.component,
+			prop: tool.glyph
+		};
+	}
 	for (const component of config.list("component")) {
 		const { props = {} } = component.toJSON();
 		for (const [prop, declaration] of Object.entries(props)) {
@@ -1181,4 +1210,4 @@ function declaredPropDefaults(props) {
 	return out;
 }
 //#endregion
-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 };
+export { authoredBag, authoredValue, className, cssPropValue, cssVar, cssVarRef, declaredPropDefaults, declaredPropRouting, glyphComponentOf, glyphLibrariesOf, glyphPropsOf, glyphPropsOfBody, holdingPreviewConditions, iconToolAxisOptions, iconToolOf, 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/schema-version.d.ts

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

package/dist/framework/schema-version.js

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