@yahoo/uds-create-config 5.69.0 → 5.71.0

package/dist/configs/system.js

@@ -36,6 +36,8 @@ import { lintIgnoreMigration } from "../migrations/20261027205147_lint_ignore.js
 import { componentMapPropsMigration } from "../migrations/20261030134149_component_map_props.js";
 import { layerPrefixMigration } from "../migrations/20261030163028_layer_prefix.js";
 import { defaultColorsMigration } from "../migrations/20261102143821_default_colors.js";
+import { linkReplaceMigration } from "../migrations/20261102185610_link_replace.js";
+import { mapPropsFromMigration } from "../migrations/20261102193912_map_props_from.js";
 import { CanvasRole } from "../entities/system/CanvasRole.js";
 import { GlobalStyle } from "../entities/system/GlobalStyle.js";
 import { Guidance } from "../entities/system/Guidance.js";
@@ -205,5 +207,7 @@ if (!registeredSchemaMigrations().has(20261027205147)) registerSchemaMigrations(
 if (!registeredSchemaMigrations().has(20261030134149)) registerSchemaMigrations(componentMapPropsMigration);
 if (!registeredSchemaMigrations().has(20261030163028)) registerSchemaMigrations(layerPrefixMigration);
 if (!registeredSchemaMigrations().has(20261102143821)) registerSchemaMigrations(defaultColorsMigration);
+if (!registeredSchemaMigrations().has(20261102185610)) registerSchemaMigrations(linkReplaceMigration);
+if (!registeredSchemaMigrations().has(20261102193912)) registerSchemaMigrations(mapPropsFromMigration);
 //#endregion
 export { System };

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

@@ -873,11 +873,16 @@ declare const ComponentEntity: EntityClass<z.ZodObject<{
     readonly input: z.ZodObject<{
       path: z.ZodType<string, string | undefined, z.core.$ZodTypeInternals<string, string | undefined>>;
       data: z.ZodObject<{
-        rules: z.ZodArray<z.ZodObject<{
+        from: z.ZodOptional<z.ZodString>;
+        only: z.ZodOptional<z.ZodObject<{
+          canvas: z.ZodString;
+          nodes: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>>;
+        rules: z.ZodDefault<z.ZodArray<z.ZodObject<{
           when: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
           set: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
           unset: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        }, z.core.$strip>>;
+        }, z.core.$strip>>>;
       }, z.core.$strip>;
     }, z.core.$strip>;
   };
@@ -885,11 +890,12 @@ declare const ComponentEntity: EntityClass<z.ZodObject<{
     readonly input: z.ZodObject<{
       path: z.ZodType<string, string | undefined, z.core.$ZodTypeInternals<string, string | undefined>>;
       data: z.ZodObject<{
-        rules: z.ZodArray<z.ZodObject<{
+        from: z.ZodOptional<z.ZodString>;
+        rules: z.ZodDefault<z.ZodArray<z.ZodObject<{
           when: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
           set: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
           unset: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        }, z.core.$strip>>;
+        }, z.core.$strip>>>;
         instances: z.ZodDefault<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
       }, z.core.$strip>;
     }, z.core.$strip>;

package/dist/entities/system/Component.js

@@ -24,7 +24,7 @@ import { slotAnatomyPropOf, slotTargetsOf, withoutTruthyTerm } from "../../frame
 import { listSlots, namedSlots, slotHostedBy, slotOf, slotsFor } from "../../spec/slot.js";
 import { cellAt } from "../../spec/cell.js";
 import { instanceAt } from "../../spec/instance.js";
-import { mapComponentProps, propMappingErrors, propMappingRulesSchema } from "../../spec/prop-mapping.js";
+import { mapComponentProps, mapPropsRulesSchema, mappingFromSchema, mappingScopeSchema, propMappingErrors } from "../../spec/prop-mapping.js";
 import { forwardOptions, forwardsWrite } from "./component-forwards.js";
 import { assertComponentSourceInput } from "./component-source-fields.js";
 import { checkStyleSet, styleSetEdits } from "./component-style-set.js";
@@ -2947,12 +2947,16 @@ element: refSchema })
 		"map-props": {
 			input: z.object({
 				path: pathInput("component"),
-				data: z.object({ rules: propMappingRulesSchema })
+				data: z.object({
+					from: mappingFromSchema.optional(),
+					only: mappingScopeSchema.optional(),
+					rules: mapPropsRulesSchema
+				})
 			}),
 			readOnly: false,
 			approval: "reference-change",
 			label: "Map props",
-			description: "Move a component's instances onto its props as they are now, after its API changed: `variant: 'primary'` becomes `color: 'brand', prominence: 'solid'`. It changes nothing in the config. Where it runs decides what it moves: in Create, the instances in the branch's design files; in a checkout (`uds config edit`, the local UDS MCP), the call sites in the project's source. Refuses a rule that writes a prop or value the component doesn't take. Run it with `plan: true` first: the plan says what it would move, and writes nothing.",
+			description: "Move a component's instances onto its props as they are now, after its API changed: `variant: 'primary'` becomes `color: 'brand', prominence: 'solid'`. It changes nothing in the config. Where it runs decides what it moves: in Create, the instances in the branch's design files; in a checkout (`uds config edit`, the local UDS MCP), the call sites in the project's source. With `from`, it swaps the component too: instances of `from`, a component the system may no longer have, become this component's, and the rules move their props onto it (`when: {}` reaches every swapped instance). Refuses a rule that writes a prop or value the component doesn't take. Run it with `plan: true` first: the plan says what it would move, and writes nothing.",
 			scope: "item",
 			title: (entity) => `Map ${entity} props`,
 			example: ({ config, path }) => {
@@ -2963,10 +2967,7 @@ element: refSchema })
 				};
 			},
 			handler: (input, config) => {
-				const errors = propMappingErrors(config, {
-					component: String(input.path),
-					rules: input.data.rules
-				});
+				const errors = propMappingErrors(config, mappingOf(String(input.path), input.data));
 				if (errors.length > 0) rejectData(errors.join(" "));
 				return config;
 			}
@@ -2975,7 +2976,8 @@ element: refSchema })
 			input: z.object({
 				path: pathInput("component"),
 				data: z.object({
-					rules: propMappingRulesSchema,
+					from: mappingFromSchema.optional(),
+					rules: mapPropsRulesSchema,
 					instances: z.array(z.record(z.string(), z.unknown())).default([]).describe("Instances' props as they are stored or written: each comes back with the rules applied.")
 				})
 			}),
@@ -2987,10 +2989,7 @@ element: refSchema })
 			example: ({ config, path }) => exampleMapping(config, path),
 			handler: (input, config) => {
 				const data = input.data;
-				return mapComponentProps(config, {
-					component: String(input.path),
-					rules: data.rules
-				}, data.instances ?? []);
+				return mapComponentProps(config, mappingOf(String(input.path), input.data), data.instances ?? []);
 			}
 		}
 	},
@@ -3140,6 +3139,17 @@ function exampleProps(config, componentPath) {
 	}
 	return {};
 }
+/** The mapping a `map-props` op's input names, refused when a mapping without `from` has no rule. */
+function mappingOf(component, data) {
+	const { from, only, rules = [] } = data ?? {};
+	if (from === void 0 && rules.length === 0) rejectData("Name at least one rule in `rules`, or `from` to swap another component's instances onto this one.");
+	return {
+		component,
+		...from === void 0 ? {} : { from: from.replace(/^component:/, "") },
+		...only === void 0 ? {} : { only },
+		rules
+	};
+}
 /** A runnable `map-props-plan` example: an instance holding the first variant prop's first value, and
 *  a rule moving it onto the prop's second value (or the same one, for a prop with a single value).
 *  A component with no variant gets the other common case, dropping a prop it no longer has.

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

@@ -123,6 +123,7 @@ declare const LinkedSystemDefinition: EntityClass<z.ZodObject<{
         keep: "keep";
         take: "take";
       }>>;
+      replace: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>>>;
     }, z.core.$strip>;
   };
   readonly 'link-plan': {
@@ -133,6 +134,7 @@ declare const LinkedSystemDefinition: EntityClass<z.ZodObject<{
         keep: "keep";
         take: "take";
       }>>;
+      replace: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>>>;
     }, z.core.$strip>;
   };
   readonly unlink: {

package/dist/entities/system/LinkedSystem.js

@@ -171,7 +171,16 @@ const linkInput = z.object({
 	data: z.union([z.literal("*"), z.record(z.string(), copyPaths)]),
 	/** What to do at a path another linked system provides: `'take'` makes it follow this source,
 	*  `'keep'` leaves it where it comes from. Required when there is one; `link-plan` lists them. */
-	onLinked: z.enum(["keep", "take"]).optional()
+	onLinked: z.enum(["keep", "take"]).optional(),
+	/**
+	* A component this config holds under one name, replaced with the source's of another name, keyed
+	* by accessor: `{ components: { SelectContent: 'SelectMenu' } }` replaces the `SelectContent` this
+	* config holds with the source's `SelectMenu`. Every ref to `SelectContent` is renamed to
+	* `SelectMenu`, so design files and code follow the way they follow a rename, and the system
+	* `SelectContent` came through stops deriving it unless its own rows still use it. Each source path
+	* is one `data` names; `link-plan` lists each in `replaced`. A take at the same name is `onLinked`.
+	*/
+	replace: z.record(z.string(), z.record(z.string().min(1), z.string().min(1))).optional()
 });
 const unlinkInput = z.object({
 	path: pathInput("linked-system"),
@@ -216,7 +225,8 @@ function linkPlanInputOf(input) {
 	return {
 		path: String(input.path),
 		data: input.data,
-		...input.onLinked === void 0 ? {} : { onLinked: input.onLinked }
+		...input.onLinked === void 0 ? {} : { onLinked: input.onLinked },
+		...input.replace === void 0 ? {} : { replace: input.replace }
 	};
 }
 /** A `link` or `unlink` example: one entity the source offers, under the accessor this config files it by. */
@@ -310,7 +320,7 @@ const LinkedSystemDefinition = defineEntity({
 			input: linkInput,
 			readOnly: false,
 			label: "Link from",
-			description: "Draw entities from a linked system, following the source: `data` names them by accessor — `{ tokens: ['color/brand', 'color'] }` takes an entity and a folder's members, `{ tokens: '*' }` every token, and `'*'` the whole system. What this config already holds at those paths is replaced by theirs, so run `linked-system/link-plan` with the same input first to see what that is. To hold their values as your own instead, `copy`.",
+			description: "Draw entities from a linked system, following the source: `data` names them by accessor — `{ tokens: ['color/brand', 'color'] }` takes an entity and a folder's members, `{ tokens: '*' }` every token, and `'*'` the whole system. What this config already holds at those paths is replaced by theirs, so run `linked-system/link-plan` with the same input first to see what that is. To replace something this config holds under another name (the `SelectContent` it has with the source's `SelectMenu`), name the pair in `replace` (`{ components: { SelectContent: 'SelectMenu' } }`): every reference to the old name moves to the new one, in design files and code too. To hold their values as your own instead, `copy`.",
 			scope: "item",
 			approval: "reference-change",
 			title: (entity) => `Link something from ${entity}`,
@@ -333,7 +343,7 @@ const LinkedSystemDefinition = defineEntity({
 			input: linkInput,
 			readOnly: true,
 			label: "Plan a link",
-			description: "What `link` with the same input replaces — rows of yours deleted so the source shows through, every path another linked system provides (`linked`, turned into extensions when `onLinked` says take), the `options` entries another linked system holds at what a take moves, which it removes since they would apply to nothing (`dropped`), members left alone because they are already here from the same origin, paths another linked system declares that the link reaches as a different entity (`settled`), whose row stays, and why the config would refuse the link (`blocked`), a collision it would leave among them. Writes nothing.",
+			description: "What `link` with the same input replaces — rows of yours deleted so the source shows through, every path another linked system provides (`linked`, turned into extensions when `onLinked` says take), the `options` entries another linked system holds at what a take moves, which it removes since they would apply to nothing (`dropped`), members left alone because they are already here from the same origin, paths another linked system declares that the link reaches as a different entity (`settled`), whose row stays, what `replace` replaces under another name (`replaced`: each path, what replaces it, the pin it came through, and whether it is left out of that pin or kept because rows of that pin still use it), and why the config would refuse the link (`blocked`), a collision it would leave among them. Writes nothing.",
 			scope: "item",
 			title: (entity) => `Plan a link from ${entity}`,
 			example: linkExample,

package/dist/entities/system/link-plan.d.ts

@@ -9,12 +9,22 @@ type LinkPaths = '*' | Readonly<Record<string, '*' | readonly string[]>>;
 /** What a link does at a path held through another linked system: `'take'` makes the row follow this
  *  source, `'keep'` leaves it with the system it comes from. */
 type OnLinked = 'keep' | 'take';
+/** Per accessor, a path this config holds → the source's path that replaces it under another name. */
+type LinkReplacements = Readonly<Record<string, Readonly<Record<string, string>>>>;
 interface LinkPlanInput {
   /** The pin's slug. */
   readonly path: string;
   readonly data: LinkPaths;
   /** Planned as `'take'` when omitted; the `link` op refuses without it while `linked` is not empty. */
   readonly onLinked?: OnLinked;
+  /**
+   * What this config holds under one name that the source's entity replaces under another:
+   * `{ components: { SelectContent: 'SelectMenu' } }` replaces the `SelectContent` this config holds
+   * with the source's `SelectMenu`, and everything that pointed at `SelectContent` points at
+   * `SelectMenu` after it. Each source path is one `data` names. A take at the same path is
+   * `onLinked: 'take'`, not this.
+   */
+  readonly replace?: LinkReplacements;
 }
 /** A path the link reaches that another linked system provides, or declares under a row of this
  *  config's own. */
@@ -40,6 +50,22 @@ interface StrandedDirective extends DroppedDirective {
 interface LinkArrival extends EntityAddress {
   readonly named: boolean;
 }
+/** A row this config held that a `replace` entry replaces with the source's entity of another name.
+ *  `path` is the row's; every ref to it is renamed to `with`. */
+interface LinkReplacement extends EntityAddress {
+  /** The source's path that replaces it, which is where the row lands. */
+  readonly with: string;
+  /** The slug of the pin the replaced row came through; absent for a row of this config's own. */
+  readonly from?: string;
+  /** Whether the replaced path was left out of that pin, so it no longer derives here. */
+  readonly excluded: boolean;
+  /** That pin's own rows still drawing on the replaced path, which keep it held. */
+  readonly keptFor?: readonly EntityAddress[];
+  /** Why the replaced path couldn't be left out of that pin, when it couldn't. */
+  readonly keptBecause?: string;
+  /** That pin's `options` entries at the replaced path, removed with it. */
+  readonly dropped: readonly EntityAddress[];
+}
 interface LinkPlan {
   /** The pin's `link` once the op has run. */
   readonly declared: LinkDeclaration | undefined;
@@ -53,6 +79,8 @@ interface LinkPlan {
   readonly linked: readonly LinkedElsewhere[];
   /** Rows held through another pin, turned into extensions through this one. */
   readonly extended: readonly EntityAddress[];
+  /** What `replace` replaces, each with the source's entity it's replaced with. */
+  readonly replaced: readonly LinkReplacement[];
   /** The other pins' `options` entries at what the take moves, removed with it: they adjust only the
    *  rows their pin derives, and the row there follows this one now. Not carried onto the taken row,
    *  since an entry corrects what that pin brings rather than stating a value of this config's own. */
@@ -156,6 +184,11 @@ interface SourceRowState {
  * that leaves a referrer dangling until the declaration covers the path. A member
  * already here from the source's own origin is left alone and kept out of the declaration, so a
  * folder that holds one is declared by its other members.
+ *
+ * A `replace` entry replaces a row this config holds with the source's entity of another name: that
+ * row becomes an extension of the source's, is renamed to the source's path so every ref follows
+ * (`replacementTakes`), and is left out of the pin it came through unless that pin's own rows still
+ * draw on it.
  */
 declare function planLink({
   config,
@@ -214,4 +247,4 @@ declare function sourceRowStates({
   readonly slug: string;
 }): SourceRowState[];
 //#endregion
-export { BreakOutcome, BreakPlan, BreakPlanInput, BreakPlanRow, BreakReach, DroppedDirective, LinkArrival, LinkPaths, LinkPlan, LinkPlanInput, LinkedElsewhere, OnLinked, SourceRowState, UnlinkPlan, UnlinkPlanInput, planBreak, planLink, planUnlink, sourceRowStates };
+export { BreakOutcome, BreakPlan, BreakPlanInput, BreakPlanRow, BreakReach, DroppedDirective, LinkArrival, LinkPaths, LinkPlan, LinkPlanInput, LinkReplacement, LinkReplacements, LinkedElsewhere, OnLinked, SourceRowState, UnlinkPlan, UnlinkPlanInput, planBreak, planLink, planUnlink, sourceRowStates };

package/dist/entities/system/link-plan.js

@@ -71,6 +71,11 @@ function declaredElsewhere({ config, slug, kind, path }) {
 * that leaves a referrer dangling until the declaration covers the path. A member
 * already here from the source's own origin is left alone and kept out of the declaration, so a
 * folder that holds one is declared by its other members.
+*
+* A `replace` entry replaces a row this config holds with the source's entity of another name: that
+* row becomes an extension of the source's, is renamed to the source's path so every ref follows
+* (`replacementTakes`), and is left out of the pin it came through unless that pin's own rows still
+* draw on it.
 */
 function planLink({ config, input }) {
 	return planLinkApplied({
@@ -116,7 +121,15 @@ function planLinkApplied({ config, input }) {
 	/** Per accessor, what the declaration gains: the kind whole, or paths. */
 	const gains = /* @__PURE__ */ new Map();
 	let leftAnywhere = false;
+	const replacements = replacementTakes({
+		config,
+		slug,
+		source,
+		input
+	});
+	const landing = new Set(replacements.entries.map(({ kind, path }) => `${kind}:${path}`));
 	const shadow = (kind, path) => {
+		if (landing.has(`${kind}:${path}`)) return true;
 		const held = config.resolve(kind, path);
 		if (!held || held.borrowedFrom === slug) return true;
 		if (sharedWithOrigin({
@@ -261,12 +274,13 @@ function planLinkApplied({ config, input }) {
 		declared = Object.keys(next).length === 0 ? current : next;
 	}
 	const planned = [
+		...replacements.patches,
 		...takes,
 		...declares,
 		...shadows
 	];
 	let result = planned.length > 0 ? applied(config, planned) : void 0;
-	if (takes.length > 0 && result && "failed" in result) throw result.failed;
+	if ((takes.length > 0 || replacements.patches.length > 0) && result && "failed" in result) throw result.failed;
 	const { dropped, stranded, patches: drops } = takes.length > 0 && result && "config" in result ? directivesTakenFrom({
 		config,
 		slug,
@@ -277,7 +291,74 @@ function planLinkApplied({ config, input }) {
 		patches: []
 	};
 	if (drops.length > 0 && result && "config" in result) result = applied(result.config, drops);
-	const patches = [...planned, ...drops];
+	const taken = [];
+	const leaves = [];
+	for (const entry of replacements.entries) {
+		const { kind, accessor, path, replaces, from } = entry;
+		if (from === void 0 || !result || !("config" in result)) {
+			taken.push({
+				kind,
+				path: replaces,
+				with: path,
+				...from ? { from } : {},
+				excluded: false,
+				dropped: []
+			});
+			continue;
+		}
+		const leftOut = { [accessor]: [replaces] };
+		const keptFor = linkedDependents({
+			config: result.config,
+			slug: from,
+			data: leftOut
+		});
+		if (keptFor.length > 0) {
+			taken.push({
+				kind,
+				path: replaces,
+				with: path,
+				from,
+				excluded: false,
+				keptFor,
+				dropped: []
+			});
+			continue;
+		}
+		const exclusion = planExclude({
+			config: result.config,
+			input: {
+				path: from,
+				data: leftOut
+			}
+		});
+		if (exclusion.blocked !== void 0) {
+			taken.push({
+				kind,
+				path: replaces,
+				with: path,
+				from,
+				excluded: false,
+				keptBecause: exclusion.blocked,
+				dropped: []
+			});
+			continue;
+		}
+		leaves.push(...exclusion.patches);
+		result = applied(result.config, exclusion.patches);
+		taken.push({
+			kind,
+			path: replaces,
+			with: path,
+			from,
+			excluded: true,
+			dropped: exclusion.dropped
+		});
+	}
+	const patches = [
+		...planned,
+		...drops,
+		...leaves
+	];
 	return {
 		plan: {
 			declared,
@@ -291,6 +372,7 @@ function planLinkApplied({ config, input }) {
 			addresses,
 			linked,
 			extended,
+			replaced: taken,
 			dropped,
 			shared,
 			patches,
@@ -303,6 +385,79 @@ function planLinkApplied({ config, input }) {
 	};
 }
 /**
+* The edits that take each `replace` entry: the replaced row becomes this config's own extension of
+* the source's entity, still at the old path, and is then renamed to the source's path. A rename is
+* the edit that moves every ref, and the one design files and code follow, so the replaced name's
+* instances arrive on the taken entity the way a rename's would. The config refuses to rename a row
+* held under its source's own name, so the extension comes first: what it holds is then a name this
+* config gave.
+*/
+function replacementTakes({ config, slug, source, input }) {
+	const entries = [];
+	const patches = [];
+	const accessors = config.accessors();
+	const landing = /* @__PURE__ */ new Map();
+	for (const [accessor, pairs] of Object.entries(input.replace ?? {})) {
+		const kind = accessors[accessor]?.kind;
+		if (!kind) rejectData(`Cannot replace anything through "${slug}" — this system has no "${accessor}".`, ["replace", accessor]);
+		for (const [replaces, path] of Object.entries(pairs)) {
+			const at = [
+				"replace",
+				accessor,
+				replaces
+			];
+			if (input.data !== "*" && !covers({
+				declared: input.data,
+				accessor,
+				path
+			})) rejectData(`Cannot replace "${replaces}" with "${path}" — \`data\` doesn't link "${path}" through "${slug}". Name it there too.`, at);
+			if (!source.resolve(kind, path)) rejectData(`Cannot replace "${replaces}" with "${path}" — "${slug}" has no ${kind} "${path}".`, at);
+			if (path === replaces) rejectData(`Cannot replace "${path}" with itself — taking the source's "${path}" over it is \`onLinked: 'take'\`.`, at);
+			const twice = landing.get(`${kind}:${path}`);
+			if (twice !== void 0) rejectData(`Cannot replace both "${twice}" and "${replaces}" with "${path}".`, at);
+			const held = config.resolve(kind, replaces);
+			if (!held) rejectData(`Cannot replace "${replaces}" — this system has no ${kind} "${replaces}".`, at);
+			if (held.borrowedFrom === slug) rejectData(`Cannot replace "${replaces}" with "${path}" — "${replaces}" already comes from "${slug}".`, at);
+			const occupied = config.storedBody(kind, path);
+			if (occupied !== void 0 && !isMintedRow(occupied)) rejectData(`Cannot replace "${replaces}" with "${path}" — this system already has a ${kind} of its own at "${path}".`, at);
+			landing.set(`${kind}:${path}`, replaces);
+			const from = held.borrowedFrom ?? declaredElsewhere({
+				config,
+				slug,
+				kind,
+				path: replaces
+			});
+			const stored = config.storedBody(kind, replaces);
+			const minted = stored !== void 0 && isMintedRow(stored);
+			entries.push({
+				kind,
+				accessor,
+				path,
+				replaces,
+				...from ? { from } : {}
+			});
+			patches.push({
+				kind,
+				operation: minted ? "create" : "replace",
+				path: replaces,
+				data: {
+					...ref(kind, path, slug),
+					extend: {}
+				}
+			}, {
+				kind,
+				operation: "rename",
+				path: replaces,
+				to: path
+			});
+		}
+	}
+	return {
+		entries,
+		patches
+	};
+}
+/**
 * The other pins' `options` entries a take leaves applying to nothing, and the pin edits that remove
 * them.
 *

package/dist/framework/Config.d.ts

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

package/dist/framework/Config.js

@@ -6391,7 +6391,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 > 20261102143821) throw new SchemaVersionTooNew(claimed);
+		if (claimed > 20261102193912) 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.`);
 		const leftover = wire.options;

package/dist/framework/component-api-changes.d.ts

@@ -25,6 +25,11 @@ interface ComponentApiChange {
   readonly component: string;
   /** `true` when `after` has no such component: every instance of it names nothing. */
   readonly removed: boolean;
+  /**
+   * The path `after` holds the component at, when a rename moved it: its instances follow the rename,
+   * and `breaks` are what its props lose against the component they land on.
+   */
+  readonly renamedTo?: string;
   readonly breaks: readonly ComponentApiBreak[];
   /** Props `after` exposes that `before` didn't, in declaration order. */
   readonly added: readonly string[];
@@ -33,7 +38,15 @@ interface ComponentApiChange {
  * The components whose API `after` broke for instances stored against `before`, in `before`'s
  * order. A component that only gained props isn't listed. `components` narrows the read to those
  * paths, for a caller that already knows what a change touched.
+ *
+ * `renames` are the component renames between the two, oldest first (`documentRenamesFromPatches`
+ * reads them off a draft). A renamed component's instances follow the rename, so it isn't removed:
+ * its props are compared with the component it lands on, which is what replacing a component with
+ * a source's of another name breaks, and a rename that keeps every prop breaks nothing.
  */
-declare function componentApiChanges(before: Config, after: Config, components?: readonly string[]): ComponentApiChange[];
+declare function componentApiChanges(before: Config, after: Config, components?: readonly string[], renames?: readonly {
+  readonly from: string;
+  readonly to: string;
+}[]): ComponentApiChange[];
 //#endregion
 export { ComponentApiBreak, ComponentApiChange, componentApiChanges };

package/dist/framework/component-api-changes.js

@@ -43,8 +43,8 @@ function breaksOf(configs, component, before, after) {
 			});
 			continue;
 		}
-		const wasValues = valuesOf(configs.before, component, was);
-		const isValues = valuesOf(configs.after, component, is);
+		const wasValues = valuesOf(configs.before, component.before, was);
+		const isValues = valuesOf(configs.after, component.after, is);
 		if (wasValues && isValues) {
 			const kept = new Set(isValues);
 			const gone = wasValues.filter((value) => !kept.has(value));
@@ -65,14 +65,26 @@ function breaksOf(configs, component, before, after) {
 * The components whose API `after` broke for instances stored against `before`, in `before`'s
 * order. A component that only gained props isn't listed. `components` narrows the read to those
 * paths, for a caller that already knows what a change touched.
+*
+* `renames` are the component renames between the two, oldest first (`documentRenamesFromPatches`
+* reads them off a draft). A renamed component's instances follow the rename, so it isn't removed:
+* its props are compared with the component it lands on, which is what replacing a component with
+* a source's of another name breaks, and a rename that keeps every prop breaks nothing.
 */
-function componentApiChanges(before, after, components) {
+function componentApiChanges(before, after, components, renames = []) {
 	const paths = components ?? before.list("component").map((entity) => entity.path);
 	const changes = [];
+	const landsAt = (path) => {
+		let at = path;
+		for (const rename of renames) if (rename.from === at) at = rename.to;
+		return at;
+	};
 	for (const component of paths) {
 		if (!before.resolve("component", component)) continue;
 		const was = surfaceProps(before, component);
-		if (!after.resolve("component", component)) {
+		const target = landsAt(component);
+		const renamedTo = target === component ? void 0 : target;
+		if (!after.resolve("component", target)) {
 			changes.push({
 				component,
 				removed: true,
@@ -81,16 +93,20 @@ function componentApiChanges(before, after, components) {
 			});
 			continue;
 		}
-		const is = surfaceProps(after, component);
+		const is = surfaceProps(after, target);
 		const breaks = breaksOf({
 			before,
 			after
-		}, component, was, is);
+		}, {
+			before: component,
+			after: target
+		}, was, is);
 		if (breaks.length === 0) continue;
 		const had = new Set(was.map((prop) => prop.name));
 		changes.push({
 			component,
 			removed: false,
+			...renamedTo ? { renamedTo } : {},
 			breaks,
 			added: is.filter((prop) => !had.has(prop.name)).map((prop) => prop.name)
 		});

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 = 20261102143821;
+declare const CURRENT_SCHEMA_VERSION = 20261102193912;
 /** 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 = 20261102143821;
+const CURRENT_SCHEMA_VERSION = 20261102193912;
 /** 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 > 20261102143821) 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 > 20261102193912) 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 ?? 20261102143821;
+	const target = options?.target ?? 20261102193912;
 	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 ?? 20261102143821;
+	const target = options?.target ?? 20261102193912;
 	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 ?? 20261102143821;
+	const target = options?.target ?? 20261102193912;
 	const entries = [];
 	const held = [];
 	const retired = [];