@yahoo/uds-create-config 2.44.0 → 3.0.0

package/dist/framework/defineEntity.js

@@ -0,0 +1,183 @@
+import { CONFIG_OPERATION_KIND } from "./config-operation-kind.js";
+import { isRef, kindOf, pathOf, ref, refSchema, sourceOf } from "./utils/refs.js";
+import { resolveFields } from "./schemas.js";
+import { buildKind } from "./registry.js";
+import { brandGroup } from "./utils/group.js";
+import { z } from "zod";
+//#region src/framework/defineEntity.ts
+/**
+* `defineEntity({ kind, fields, groupFields })` — the whole authoring toolkit for one
+* kind, derived from its `z.object` field schema. Declare the fields; get the typed
+* `item`/`group` constructors, the kind-bound `ref`, and a typed `get`. Pure: it builds the
+* kind's metadata (`kindDef`) and attaches it to the returned class — no process-global write.
+*
+* A config type (`defineConfig`) names this kind in its `entities` map; the resulting config's typed
+* `register({ <name>: items })` reads each class's `kindDef` into that config's own `#entities` and
+* loads its items. So a config's behavior depends on what was registered into that instance — not
+* import order.
+*/
+/** The options `extend` understands. Checked at runtime because `extend` shadows zod's: an
+*  unrecognized key is a typo, or raw zod fields from a caller expecting `ZodObject.extend`, and
+*  both should fail loudly instead of quietly building a kind that ignored them. `kind` is
+*  deliberately not here — a variant keeps its base's kind. */
+const EXTENDABLE_KEYS = new Set([
+	"fields",
+	"groupFields",
+	"subEntities",
+	"schemas",
+	"label",
+	"labelPlural",
+	"entityName"
+]);
+/** Merge an override into the base's shape, key by key — using zod's real `extend`/`omit` on the
+*  plain object, where they are the right tools. A named key replaces or adds a field; `null`
+*  removes one; everything unnamed is inherited. There is no implicit wipe: only declared fields
+*  survive save and load, so removal has to be said out loud, and removing a key the base never
+*  declared is a typo worth naming. */
+function extendShape(kind, area, base, override) {
+	if (override === void 0) return base;
+	if (!(base instanceof z.ZodObject)) throw new Error(`${kind}.extend: \`${area}\` merges into a plain z.object — a kind whose ${area} are a discriminated union cannot be extended here.`);
+	const entries = override instanceof z.ZodObject ? Object.entries(override.shape) : Object.entries(override);
+	const removed = entries.filter(([, value]) => value === null).map(([key]) => key);
+	const added = Object.fromEntries(entries.filter(([, value]) => value !== null));
+	for (const key of removed) if (!(key in base.shape)) throw new Error(`${kind}.extend: \`${area}.${key}: null\` removes nothing — the base declares no "${key}".`);
+	const kept = removed.length > 0 ? base.omit(Object.fromEntries(removed.map((key) => [key, true]))) : base;
+	return Object.keys(added).length > 0 ? kept.extend(added) : kept;
+}
+/** Merge a sub-entities override into the base's, key by key — same rule as the shapes: name one
+*  to swap it, `null` to drop it, the rest are inherited by reference (the framework locates a
+*  collection by object identity, so inheriting must pass the same instances through). */
+function extendSubEntities(base, override) {
+	if (override === void 0) return base;
+	const merged = { ...base };
+	for (const [key, value] of Object.entries(override)) if (value === null) delete merged[key];
+	else if (value !== void 0) merged[key] = value;
+	return merged;
+}
+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 kindDef = buildKind({
+		name: spec.kind,
+		fields: spec.fields,
+		groupFields,
+		subEntities: spec.subEntities,
+		label: spec.label,
+		labelPlural: spec.labelPlural,
+		entityName: spec.entityName,
+		schemas: spec.schemas,
+		computed: spec.computed,
+		sourceIdentity: spec.sourceIdentity,
+		sourceOrigin: spec.sourceOrigin,
+		authoredRefs: spec.authoredRefs,
+		linkable: spec.linkable,
+		localGroupFields: spec.localGroupFields,
+		emergentGroups: spec.emergentGroups,
+		singleton: spec.singleton,
+		bareMember: spec.bareMember,
+		sourceResolution: spec.sourceResolution,
+		bulkAdopts: spec.bulkAdopts,
+		bulkOverlay: spec.bulkOverlay,
+		bulkDirectives: spec.bulkDirectives,
+		bulkOverlayWrite: spec.bulkOverlayWrite,
+		nameEdges: spec.nameEdges,
+		styleBags: spec.styleBags,
+		rewriteName: spec.rewriteName,
+		uniqueLeaves: spec.uniqueLeaves,
+		invariants: spec.invariants
+	});
+	const schema = z.object({ __ref: z.string().refine((raw) => kindOf(raw) === spec.kind) }).meta({
+		ref: true,
+		refKind: spec.kind
+	});
+	/**
+	* The path a caller named — from a path, a ref object, or a ref string (`component:Box`, which is
+	* what a spec element's `type` is, so a caller reading one needn't take it apart first).
+	*
+	* `undefined` when the name belongs to a different kind: `icon:phosphor/StarIcon` asked of
+	* `Component` resolves to nothing, whichever form it arrives in. Kept separate from `get` so the
+	* parsing is stated once, where a reader looking for "what forms does a name come in" will find it.
+	*/
+	const pathNamed = (pathOrRef) => {
+		if (isRef(pathOrRef)) return kindOf(pathOrRef.__ref) === spec.kind ? pathOf(pathOrRef.__ref) : void 0;
+		if (!pathOrRef.includes(":")) return pathOrRef;
+		return kindOf(pathOrRef) === spec.kind ? pathOf(pathOrRef) : void 0;
+	};
+	return Object.assign(schema, {
+		kind: spec.kind,
+		schemas: spec.schemas ?? {},
+		kindDef,
+		ref: (path) => {
+			if (path === void 0 && !spec.singleton) throw new Error(`${spec.kind}.ref: a path is required — only a singleton's one item can be addressed without one`);
+			return ref(spec.kind, path ?? spec.kind);
+		},
+		item: (def) => def,
+		group: (meta) => brandGroup(meta),
+		singleton: spec.singleton ?? false,
+		get: (config, pathOrRef) => {
+			if (pathOrRef === void 0) {
+				if (!spec.singleton) throw new Error(`${spec.kind}.get: a path is required — only a singleton's one item can be read without one`);
+				return config.resolve(spec.kind, spec.kind);
+			}
+			const path = pathNamed(pathOrRef);
+			if (path === void 0) return void 0;
+			if ((isRef(pathOrRef) || pathOrRef.includes(":") ? sourceOf(pathOrRef) : void 0) !== void 0) return config.resolveRef(pathOrRef);
+			return config.resolve(spec.kind, path);
+		},
+		list: (config, opts) => config.list(spec.kind, opts),
+		tree: (config) => config.tree(spec.kind),
+		groups: (config, opts) => config.groups(spec.kind, opts),
+		dependents: (config, path, opts) => config.dependentsOf(spec.kind, path, opts),
+		create: (config, path, data) => config.apply({
+			kind: spec.kind,
+			operation: "create",
+			path,
+			data
+		}),
+		update: (config, path, data) => config.apply({
+			kind: spec.kind,
+			operation: "update",
+			path,
+			data
+		}),
+		delete: (config, path) => config.apply({
+			kind: spec.kind,
+			operation: "delete",
+			path
+		}),
+		rename: (config, path, to) => config.apply({
+			kind: spec.kind,
+			operation: "rename",
+			path,
+			to
+		}),
+		extend: (overrides) => {
+			const unknown = Object.keys(overrides).filter((key) => !EXTENDABLE_KEYS.has(key));
+			if (unknown.length > 0) throw new Error(`${spec.kind}.extend: unknown option ${unknown.map((key) => `"${key}"`).join(", ")} — expected one of ${[...EXTENDABLE_KEYS].join(", ")}. This is an entity extension, not \`ZodObject.extend\`.`);
+			const declared = spec.fields;
+			const fields = typeof declared === "function" ? (ctx) => extendShape(spec.kind, "fields", declared(ctx), overrides.fields) : extendShape(spec.kind, "fields", declared, overrides.fields);
+			const staticFields = resolveFields(fields);
+			const groupFields = extendShape(spec.kind, "groupFields", spec.groupFields ?? z.object({}), overrides.groupFields);
+			const subEntities = extendSubEntities(spec.subEntities, overrides.subEntities);
+			if (staticFields instanceof z.ZodObject) {
+				for (const key of Object.keys(subEntities ?? {})) if (!(key in staticFields.shape)) throw new Error(`${spec.kind}.extend: sub-entity "${key}" has no field — remove it too (\`subEntities: { ${key}: null }\`) or keep its field.`);
+			}
+			const schemas = spec.schemas || overrides.schemas ? {
+				...spec.schemas,
+				...overrides.schemas
+			} : void 0;
+			return defineEntity({
+				...spec,
+				...overrides,
+				kind: spec.kind,
+				fields,
+				groupFields,
+				subEntities,
+				schemas
+			});
+		}
+	});
+}
+//#endregion
+export { defineEntity };

package/dist/framework/defineSubEntity.d.ts

@@ -0,0 +1,148 @@
+import { Ref } from "./utils/refs.js";
+import { FieldsCtx, UserSchemas } from "./schemas.js";
+import { Config } from "./Config.js";
+import { z } from "zod";
+
+//#region src/framework/defineSubEntity.d.ts
+/** A member's schema, or a FACTORY that builds one from its context — the config registry and the
+ *  owner being edited. A factory is what lets a member's schema depend on its owner (a slot's target
+ *  must be one of THAT component's layers), so the check is the schema rather than a refinement. */
+type MemberFields<F extends z.ZodTypeAny = z.ZodTypeAny> = F | ((ctx: FieldsCtx) => F);
+/** The zod schema a sub-entity IS — the COLLECTION (`{ [key]: member }`), so it can be used
+ *  directly as its owner's field: `fields: z.object({ layers: Layer })`. Generic over the member
+ *  so the owner's inferred body keeps the member's real type (`layers.root` is its element, a
+ *  prop narrows on `type`) instead of collapsing to an opaque record. */
+type CollectionSchema<F extends z.ZodTypeAny = z.ZodTypeAny> = z.ZodRecord<z.ZodString, F>;
+/** One keyed collection's definition — what a member is, what it's called, and any op overrides.
+ *  It IS a zod schema (the collection), mirroring how an entity class IS its ref schema, so an
+ *  owner declares the field by naming the sub-entity rather than restating its shape.
+ *
+ *  A singleton sub-entity (`singleton: true`) is the member itself rather than a collection of them:
+ *  the owner's field holds one body, at the field's own name. Its runtime schema is the member's, so
+ *  an owner declares the field as `fields: z.object({ css: cssFields.optional() })` and lists the
+ *  sub-entity under `subEntities`, where the framework finds it by identity. */
+type SubEntityClass<F extends z.ZodTypeAny = z.ZodTypeAny> = CollectionSchema<F> & {
+  readonly name: string;
+  /** Whether the owner's field holds ONE member rather than a keyed collection — a settings
+   *  section. A singleton offers `sub-get` and `sub-update` only: there is nothing to add, remove,
+   *  rename or order, and its address is the field with no key. */
+  readonly singleton?: true; /** Human label for one member (a row header, a tool label). Defaults to a title-cased `name`. */
+  readonly label: string; /** Human label for the collection. Defaults to `label + 's'`. */
+  readonly labelPlural: string; /** The MEMBER's schema — what one entry in the collection is. Declared, not inferred. */
+  readonly fields: MemberFields<F>; /** The member shape every owner shares, for a FACTORY `fields` — see the spec field below. */
+  readonly base?: z.ZodTypeAny;
+  /** Derive a member's key FROM ITS VALUE, when the member has a natural identity (a style rule IS
+   *  its condition). The framework then computes the key on write rather than taking one from the
+   *  caller, so key and value can't drift, two members with the same identity can't both exist, and
+   *  an edit that changes the identity moves the entry. Omit when the key is arbitrary. */
+  readonly key?: (member: unknown) => string;
+  /** Whether a member DECLARES nothing — a style rule whose every layer bag is empty. Asked only
+   *  when a \`sub-update\` would bring the member into being: a delta made entirely of removals has
+   *  nothing to remove from a member that is not there, so creating one files an entry that emits
+   *  nothing and that nobody asked for. An EXISTING member emptied by a delta is left alone; a rule
+   *  with an empty bag is still a rule, and \`sub-delete\` is how one goes away.
+   *
+   *  Omit when every member declares something by existing (a component layer is its element). */
+  readonly vacant?: (member: unknown) => boolean; /** Op-schema overrides/additions for this collection's sub-ops, same shape entities take. */
+  readonly schemas?: UserSchemas;
+  /** The ref KIND whose paths this collection's members namespace — `'value'` for a component's
+   *  props, whose variant values are `value:<prop>/<name>`. Renaming a member then moves every
+   *  ref under it, which a member rename alone can't reach (a `/` boundary inside the path, not
+   *  the `#` boundary {@link rewriteRefs} matches). Omit when nothing hangs off a member's name. */
+  readonly namespaces?: string;
+  /**
+   * Fields of THIS member that are a record keyed by another collection's member NAMES — a style
+   * rule's `when` is keyed by the component's own props.
+   *
+   * A key is not a ref, so the rename cascade cannot see it. Without this, renaming a prop leaves
+   * every rule conditioned on it filed under a prop that no longer exists: the rule stops
+   * applying, and because its own key is DERIVED from that condition, the key is stale too.
+   * Declared per field rather than inferred, since only the entity knows what its records mean.
+   */
+  readonly namesMembersOf?: Readonly<Record<string, string>>;
+  /**
+   * Collections nested INSIDE one member — a variant prop's `value`, which is a keyed set of the
+   * values that prop offers.
+   *
+   * One level, and only one: a nested collection is addressed by its owner's key (`props/value` +
+   * `owner: 'variant'`), and a second level would need a path rather than a key. Nothing has asked
+   * for one, and the addressing is the part that would stop being simple.
+   */
+  readonly subEntities?: Readonly<Record<string, SubEntityClass>>;
+  /**
+   * Fields of the OWNING ENTITY that hold this member's NAME as a VALUE, keyed by the member's
+   * owner — a component's `defaultProps` and `previewProps` are both `{ [prop]: value }`.
+   *
+   * The mirror of {@link namesMembersOf}, which covers a name held as a record KEY. Neither is
+   * reachable by a ref rewrite, and both leave the same kind of wreckage: a default naming a
+   * variant value that was renamed out from under it reads as "this component has no default",
+   * silently, on a surface nobody was looking at when the rename happened.
+   */
+  readonly namedValuesIn?: readonly string[];
+  /**
+   * Fields of the OWNING ENTITY that are KEYED by this member's name — a component's
+   * `defaultProps` and `previewProps` are both `{ [prop]: value }`, so the prop's name is the key
+   * rather than the value.
+   *
+   * The other half of {@link namedValuesIn}, which covers the same two fields from the value side
+   * (a variant VALUE's name). Both are needed because both positions hold a name no ref rewrite
+   * reaches: renaming a prop and leaving the key behind orphans its default under the old name, so
+   * the renamed prop reports no default and the component reports one for a prop it hasn't got.
+   */
+  readonly keyedByNameIn?: readonly string[];
+  /**
+   * Sibling collections whose members exist only to say something ABOUT one of these — a style
+   * rule IS its condition, so a rule conditioned on a variant value that has been removed has
+   * nothing left to test.
+   *
+   * Deleting them WITH the member rather than leaving them: a rule that can never match is inert,
+   * but it still lists itself in every surface that shows a component's styles, and its condition
+   * still names something gone. Declared per collection because "the dependents go too" is only
+   * true where the dependent is meaningless without its subject — a layer's deletion does NOT
+   * imply that of the rules targeting it, which have their own other layers to style.
+   */
+  readonly orphans?: readonly string[]; /** A ref to one member: `Prop.ref('component', 'Pressable', 'gap')`. */
+  ref(kind: string, path: string, member: string): Ref;
+  /** One member of this collection on `owner` (a path or a ref) — the sub-entity twin of
+   *  `Component.get`. A member ref resolves without naming the member twice. `ownerMember` names
+   *  the enclosing member for a NESTED collection (which prop's values are being read). */
+  get(config: Config, owner: string | Ref, member?: string, ownerMember?: string): unknown;
+  /** Every member of this collection on `owner`, as `{ key, ref, value }` — the sub-entity twin
+   *  of `Component.list`. */
+  list(config: Config, owner: string | Ref, ownerMember?: string): {
+    key: string;
+    ref: string;
+    value: unknown;
+  }[];
+};
+declare function defineSubEntity<F extends z.ZodTypeAny>(spec: {
+  name: string;
+  label?: string;
+  labelPlural?: string;
+  /** See {@link SubEntityClass.singleton}. A singleton's `fields` is the one member's schema and
+   *  may not be a factory: there is no owner-dependent shape to build. */
+  singleton?: true;
+  fields: MemberFields<F>;
+  /**
+   * The member shape every owner shares, when `fields` is a factory.
+   *
+   * This is what the COLLECTION schema validates, and so the only check a member gets at
+   * `register()`: a factory needs an owner to build its exact shape, and a body being registered has
+   * no owner yet. Without a `base` the member is `z.unknown()` there, which means an authoring
+   * mistake in a registered body is ACCEPTED and only surfaces as whatever the field's reader makes
+   * of it — for `forwards`, a list of prop names where member refs belong resolves to nothing at all,
+   * silently. Declare it as the same schema the factory returns for the no-owner case.
+   */
+  base?: z.ZodTypeAny;
+  key?: (member: unknown) => string;
+  vacant?: (member: unknown) => boolean;
+  schemas?: UserSchemas;
+  namespaces?: string;
+  namesMembersOf?: Readonly<Record<string, string>>;
+  subEntities?: Readonly<Record<string, SubEntityClass>>;
+  namedValuesIn?: readonly string[];
+  keyedByNameIn?: readonly string[];
+  orphans?: readonly string[];
+}): SubEntityClass<F>;
+//#endregion
+export { SubEntityClass, defineSubEntity };

package/dist/framework/defineSubEntity.js

@@ -0,0 +1,121 @@
+import { kindOf, memberOf, memberRef, pathOf } from "./utils/refs.js";
+import { resolveSchema } from "./schemas.js";
+import { titleCase } from "./registry.js";
+import { z } from "zod";
+//#region src/framework/defineSubEntity.ts
+/**
+* `defineSubEntity({ name, fields })` — the toolkit for one KEYED COLLECTION inside an entity (a
+* component's `layers` / `props`, an AI flow's `sections`). Previously these were bare names
+* (`subEntities: ['layers']`) whose member shape had to be INFERRED from the parent's field type,
+* which meant a member could carry no labels, no op overrides, and no schema of its own.
+*
+* A sub-entity now declares the same things an entity does — its member `fields`, display labels,
+* and `schemas` overrides for its own sub-ops — so `subEntities: { layers: Layer }` reads like
+* `entities: { components: Component }` one level down. PURE: it returns metadata; the parent's
+* `buildKind` reads it when deriving that collection's ops.
+*/
+function defineSubEntity(spec) {
+	const label = spec.label ?? titleCase(spec.name);
+	const member = typeof spec.fields === "function" ? spec.base ?? resolveSchema(spec.fields, {}) : spec.fields;
+	if (spec.singleton && typeof spec.fields === "function") throw new Error(`defineSubEntity: singleton "${spec.name}" takes a member schema, not a factory — its one member has no owner-dependent shape.`);
+	const schema = spec.singleton ? member : z.record(z.string(), member);
+	/** Where this collection sits on `kind` — its own field, plus the field of the collection it is
+	*  nested INSIDE when it is one. Found by identity, so the same sub-entity can be reused and a
+	*  collection is never addressed by a hardcoded field name. */
+	const fieldOn = (config, kind) => {
+		const subs = config.entityOf(kind)?.subEntities ?? {};
+		for (const [field, def] of Object.entries(subs)) {
+			if (def === api) return { field };
+			const nested = Object.entries(def.subEntities ?? {}).find(([, inner]) => inner === api);
+			if (nested) return {
+				field: nested[0],
+				ownerField: field
+			};
+		}
+	};
+	/** The owner's kind + path. A ref carries both; a bare path can't say its kind, so the caller
+	*  must pass a ref to reach a collection. */
+	const ownerParts = (owner) => {
+		const target = typeof owner === "string" ? owner : owner.__ref;
+		return {
+			path: pathOf(target),
+			kind: typeof owner === "string" ? void 0 : kindOf(target)
+		};
+	};
+	const collectionOn = (config, owner, ownerMember) => {
+		const { path, kind } = ownerParts(owner);
+		if (!kind) return void 0;
+		const found = fieldOn(config, kind);
+		if (!found) return void 0;
+		const body = config.resolve(kind, path)?.toJSON();
+		let holder = body;
+		if (found.ownerField) {
+			if (ownerMember === void 0) return void 0;
+			holder = (body?.[found.ownerField])?.[ownerMember];
+		}
+		const collection = holder?.[found.field];
+		const items = collection !== null && typeof collection === "object" && !Array.isArray(collection) ? collection : {};
+		return {
+			kind,
+			path,
+			field: found.field,
+			items
+		};
+	};
+	/** A singleton's one member on `owner` — the owner's field, read whole. */
+	const memberOn = (config, owner) => {
+		const { path, kind } = ownerParts(owner);
+		if (!kind) return void 0;
+		const found = fieldOn(config, kind);
+		if (!found || found.ownerField) return void 0;
+		return (config.resolve(kind, path)?.toJSON())?.[found.field];
+	};
+	const api = Object.assign(schema, {
+		name: spec.name,
+		...spec.singleton ? { singleton: true } : {},
+		label,
+		labelPlural: spec.labelPlural ?? (spec.singleton ? label : `${label}s`),
+		fields: spec.fields,
+		base: spec.base,
+		key: spec.key,
+		vacant: spec.vacant,
+		schemas: spec.schemas,
+		namespaces: spec.namespaces,
+		namesMembersOf: spec.namesMembersOf,
+		subEntities: spec.subEntities,
+		namedValuesIn: spec.namedValuesIn,
+		keyedByNameIn: spec.keyedByNameIn,
+		orphans: spec.orphans,
+		ref: (kind, path, member) => memberRef(kind, path, spec.name, member),
+		get: (config, owner, member, ownerMember) => {
+			if (spec.singleton) return memberOn(config, owner);
+			const raw = typeof owner === "string" ? void 0 : memberOf(owner.__ref);
+			const fromRef = raw?.includes("/") ? raw.split("/")[1] : raw;
+			const key = member ?? fromRef;
+			if (key === void 0) return void 0;
+			return collectionOn(config, owner, ownerMember)?.items[key];
+		},
+		list: (config, owner, ownerMember) => {
+			if (spec.singleton) {
+				const value = memberOn(config, owner);
+				if (value === void 0) return [];
+				const { path, kind } = ownerParts(owner);
+				return [{
+					key: spec.name,
+					ref: `${kind}:${path}#${spec.name}`,
+					value
+				}];
+			}
+			const found = collectionOn(config, owner, ownerMember);
+			if (!found) return [];
+			return Object.entries(found.items).map(([key, value]) => ({
+				key,
+				ref: memberRef(found.kind, found.path, spec.name, ownerMember === void 0 ? key : `${ownerMember}/${key}`).__ref,
+				value
+			}));
+		}
+	});
+	return api;
+}
+//#endregion
+export { defineSubEntity };

package/dist/framework/derived-mutations.d.ts

@@ -0,0 +1,20 @@
+//#region src/framework/derived-mutations.d.ts
+/**
+ * `DERIVED_MUTATIONS` — every mutation verb the framework derives for a kind, in BASE form
+ * (`sub-create`, not `sub-create/layers`).
+ *
+ * ASKED of `defaultSchemas` rather than listed, because the list has a consumer that has to keep up
+ * with it: the write engine (`@yahoo/uds-create-codegen`) promises to author every op a config
+ * accepts, and its coverage test reads this set. A hand-kept copy would have let a new derived op
+ * ship writable-in-name-only — the config takes the patch, the file it came from never learns of it.
+ *
+ * Derived from a PROBE kind, not from a real config, because this vocabulary is a property of the
+ * FRAMEWORK. An entity's own custom ops (`linked-system`'s `link`, a canvas `element-insert`) mean
+ * whatever that entity says and carry a handler to match, so they are absent by construction rather
+ * than filtered out — nothing else is obliged to implement them.
+ *
+ * Reads are excluded: nothing is written, so there is nothing to write back.
+ */
+declare const DERIVED_MUTATIONS: ReadonlySet<string>;
+//#endregion
+export { DERIVED_MUTATIONS };

package/dist/framework/derived-mutations.js

@@ -0,0 +1,38 @@
+import { defaultSchemas } from "./schemas.js";
+import { defineSubEntity } from "./defineSubEntity.js";
+import { z } from "zod";
+//#region src/framework/derived-mutations.ts
+/**
+* `DERIVED_MUTATIONS` — every mutation verb the framework derives for a kind, in BASE form
+* (`sub-create`, not `sub-create/layers`).
+*
+* ASKED of `defaultSchemas` rather than listed, because the list has a consumer that has to keep up
+* with it: the write engine (`@yahoo/uds-create-codegen`) promises to author every op a config
+* accepts, and its coverage test reads this set. A hand-kept copy would have let a new derived op
+* ship writable-in-name-only — the config takes the patch, the file it came from never learns of it.
+*
+* Derived from a PROBE kind, not from a real config, because this vocabulary is a property of the
+* FRAMEWORK. An entity's own custom ops (`linked-system`'s `link`, a canvas `element-insert`) mean
+* whatever that entity says and carry a handler to match, so they are absent by construction rather
+* than filtered out — nothing else is obliged to implement them.
+*
+* Reads are excluded: nothing is written, so there is nothing to write back.
+*/
+/** One collection, so the `sub-*` half of the surface is derived too. Its member shape is irrelevant
+*  — the verbs a collection declares don't depend on what a member is. */
+const PROBE_COLLECTION = defineSubEntity({
+	name: "member",
+	fields: z.unknown()
+});
+function derivedMutations() {
+	const schemas = defaultSchemas("probe", z.object({}), z.object({}), { members: PROBE_COLLECTION });
+	const verbs = /* @__PURE__ */ new Set();
+	for (const [verb, entry] of Object.entries(schemas)) {
+		if (entry.readOnly) continue;
+		verbs.add(verb.split("/")[0]);
+	}
+	return verbs;
+}
+const DERIVED_MUTATIONS = derivedMutations();
+//#endregion
+export { DERIVED_MUTATIONS };

package/dist/framework/entity-search.d.ts

@@ -0,0 +1,29 @@
+import { Config } from "./Config.js";
+
+//#region src/framework/entity-search.d.ts
+/**
+ * Collapse a typed name into a comparable key: lowercased, with every run of separators
+ * (`/ . - _` and whitespace) folded to a single `-`. This is what makes `purple/9`, `purple.9`,
+ * `Purple 9` and `purple-9` name the same thing, and it applies to `Card/Header` just as well.
+ */
+declare function normalizeName(input: string): string;
+/**
+ * Paths of the given kind that this name names EXACTLY, separator- and case-insensitively.
+ *
+ * Empty means nothing matched. More than one means the name is genuinely ambiguous — the same leaf in
+ * several groups — and the caller has to disambiguate rather than take the first.
+ */
+declare function matchEntities(config: Config, kind: string, query: string): string[];
+/**
+ * Paths of the given kind that a partial query might mean, best first.
+ *
+ * `filter` is how a caller narrows on something only it knows — a value type, a group, whether the
+ * entity is already used. It runs against the resolved entity, after ranking and before the limit, so
+ * a limit counts what survives rather than what was considered.
+ */
+declare function searchEntities(config: Config, kind: string, query: string, opts?: {
+  limit?: number;
+  filter?: (path: string) => boolean;
+}): string[];
+//#endregion
+export { matchEntities, normalizeName, searchEntities };

package/dist/framework/entity-search.js

@@ -0,0 +1,117 @@
+import { createSliceMemo } from "./memo.js";
+//#region src/framework/entity-search.ts
+/**
+* Collapse a typed name into a comparable key: lowercased, with every run of separators
+* (`/ . - _` and whitespace) folded to a single `-`. This is what makes `purple/9`, `purple.9`,
+* `Purple 9` and `purple-9` name the same thing, and it applies to `Card/Header` just as well.
+*/
+function normalizeName(input) {
+	return input.trim().toLowerCase().replace(/[\s/._-]+/g, "-").replace(/^-|-$/g, "");
+}
+function push(index, key, path) {
+	const existing = index.get(key);
+	if (existing) existing.push(path);
+	else index.set(key, [path]);
+}
+/**
+* One memo per kind, built on first use.
+*
+* A per-render scan is the whole reason an index earns its keep: separator-insensitive matching can't
+* be a path comparison, and an icon library is thousands of entries.
+*
+* A linked kind is handled without declaring anything: `createSliceMemo` keys a kind on the CHAIN of
+* slices down its links, so an index over a kind this config borrows tracks the SOURCE's slice too.
+* That matters here because `Config.list` reads through to a linked kind's source, and a consumer that
+* owns nothing of that kind has a slice which never changes — so keying on it alone would cache the
+* source's first answer forever.
+*/
+const indexes = /* @__PURE__ */ new Map();
+function indexFor(config, kind) {
+	let memo = indexes.get(kind);
+	if (!memo) {
+		memo = createSliceMemo({
+			kinds: [kind],
+			compute: (c) => {
+				const byQualified = /* @__PURE__ */ new Map();
+				const byLeaf = /* @__PURE__ */ new Map();
+				const entries = [];
+				for (const entity of c.list(kind)) {
+					const { path } = entity;
+					const qualified = normalizeName(path);
+					push(byQualified, qualified, path);
+					const slash = path.lastIndexOf("/");
+					const leaf = slash > 0 ? normalizeName(path.slice(slash + 1)) : qualified;
+					if (slash > 0) push(byLeaf, leaf, path);
+					entries.push({
+						path,
+						qualified,
+						leaf
+					});
+				}
+				return {
+					byQualified,
+					byLeaf,
+					entries
+				};
+			}
+		});
+		indexes.set(kind, memo);
+	}
+	return memo(config);
+}
+/**
+* Paths of the given kind that this name names EXACTLY, separator- and case-insensitively.
+*
+* Empty means nothing matched. More than one means the name is genuinely ambiguous — the same leaf in
+* several groups — and the caller has to disambiguate rather than take the first.
+*/
+function matchEntities(config, kind, query) {
+	const key = normalizeName(query);
+	if (!key) return [];
+	const { byQualified, byLeaf } = indexFor(config, kind);
+	const paths = [];
+	for (const path of [...byQualified.get(key) ?? [], ...byLeaf.get(key) ?? []]) if (!paths.includes(path)) paths.push(path);
+	return paths;
+}
+/**
+* How well an entry answers a partial query. Lower first; `undefined` is no match.
+*
+* A prefix beats a substring because a list that ranks them together buries the obvious answer —
+* typing `purple` should offer `purple-9` above `deep-purple`. The leaf beats the qualified name for
+* the same reason: people type the name, not the group.
+*/
+function rankOf(entry, query) {
+	if (entry.leaf.startsWith(query)) return 0;
+	if (entry.qualified.startsWith(query)) return 1;
+	if (entry.leaf.includes(query)) return 2;
+	if (entry.qualified.includes(query)) return 3;
+}
+/**
+* Paths of the given kind that a partial query might mean, best first.
+*
+* `filter` is how a caller narrows on something only it knows — a value type, a group, whether the
+* entity is already used. It runs against the resolved entity, after ranking and before the limit, so
+* a limit counts what survives rather than what was considered.
+*/
+function searchEntities(config, kind, query, opts) {
+	const key = normalizeName(query);
+	if (!key) return [];
+	const ranked = [];
+	for (const entry of indexFor(config, kind).entries) {
+		const rank = rankOf(entry, key);
+		if (rank !== void 0) ranked.push({
+			rank,
+			path: entry.path
+		});
+	}
+	ranked.sort((a, b) => a.rank - b.rank);
+	const paths = [];
+	for (const { path } of ranked) {
+		if (opts?.filter && !opts.filter(path)) continue;
+		paths.push(path);
+		if (opts?.limit !== void 0 && paths.length >= opts.limit) break;
+	}
+	return paths;
+}
+//#endregion
+export { matchEntities, normalizeName, searchEntities };