@yahoo/uds-create-config 5.70.0 → 5.71.0

package/dist/configs/system.js

@@ -37,6 +37,7 @@ import { componentMapPropsMigration } from "../migrations/20261030134149_compone
 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";
@@ -207,5 +208,6 @@ if (!registeredSchemaMigrations().has(20261030134149)) registerSchemaMigrations(
 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/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 = 20261102185610;
+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 > 20261102185610) 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/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 = 20261102185610;
+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 = 20261102185610;
+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 > 20261102185610) 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 ?? 20261102185610;
+	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 ?? 20261102185610;
+	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 ?? 20261102185610;
+	const target = options?.target ?? 20261102193912;
 	const entries = [];
 	const held = [];
 	const retired = [];

package/dist/migrations/20261102193912_map_props_from.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The `component/map-props` op takes `from` and `only`. `from` names a component the system no
+ * longer has (a rename or removal its design files didn't follow): the mapping moves that
+ * component's instances onto the op's own component, then maps their props, and with `from` the
+ * rules may be empty. `only` limits it to some nodes of one design file.
+ *
+ * Only the op's input moved. A mapping writes nothing to the config, so no stored config or draft
+ * patch holds one, and `up` is identity with no `upPatch`.
+ */
+import type { SchemaMigration } from '../framework/schema-version';
+export declare const MAP_PROPS_FROM_VERSION = 20261102193912;
+export declare const mapPropsFromMigration: SchemaMigration;

package/dist/migrations/20261102193912_map_props_from.js

@@ -0,0 +1,10 @@
+//#region src/migrations/20261102193912_map_props_from.ts
+const MAP_PROPS_FROM_VERSION = 20261102193912;
+const mapPropsFromMigration = {
+	version: MAP_PROPS_FROM_VERSION,
+	up(json) {
+		return json;
+	}
+};
+//#endregion
+export { MAP_PROPS_FROM_VERSION, mapPropsFromMigration };

package/dist/spec/index.d.ts

@@ -7,7 +7,7 @@ import { AcceptsChildNodes, ChildNodesClassification, ClassifyChildNodes, buildA
 import { CollapseTextLabelsResult, CollapsedTextLabel, collapseWrappedTextLabels } from "./collapse-text-labels.js";
 import { GlyphJsxForm, GlyphNodeResolver, glyphJsxForm, glyphMemberOf, jsxIdentifier, parseGlyphType } from "./glyph-jsx.js";
 import { JsxToSpecOptions, UNRESOLVED, hasUnresolvedProps, jsxToSpec, stripUnresolvedProps } from "./jsxToSpec.js";
-import { MappedInstance, MappedProps, MatchedValue, PropMapping, PropMappingConflict, PropMappingResult, PropMappingRule, applyPropMapping, mapComponentProps, onlyMapsProps, propMappingErrors, propMappingRuleSchema, propMappingRulesSchema, propMappingsIn } from "./prop-mapping.js";
+import { MappedInstance, MappedProps, MappingScope, MatchedValue, PropMapping, PropMappingConflict, PropMappingResult, PropMappingRule, applyPropMapping, mapComponentProps, mapPropsRulesSchema, mappingFromSchema, mappingScopeSchema, onlyMapsProps, propMappingErrors, propMappingRuleSchema, propMappingRulesSchema, propMappingsIn, swapMappingRulesSchema } from "./prop-mapping.js";
 import { SpecToJsxOptions, SpecToJsxResult, specToJsx } from "./specToJsx.js";
 
 //#region src/spec/index.d.ts
@@ -29,4 +29,4 @@ import { SpecToJsxOptions, SpecToJsxResult, specToJsx } from "./specToJsx.js";
  *  element, without changing the rendered layer hierarchy. */
 declare const SYNTHETIC_TEXT_SLOT_PROP = "data-uds-synthetic-text-slot";
 //#endregion
-export { type AcceptsChildNodes, type Cell, type CellSlot, type ChildNodesClassification, type ClassifyChildNodes, type CollapseTextLabelsResult, type CollapsedTextLabel, type DocumentRename, type GlyphJsxForm, type GlyphNodeResolver, type GraftableElement, type GraftableSpec, type JsxToSpecOptions, type MappedInstance, type MappedProps, type MatchedValue, type PreviewElement, type PreviewRef, type PreviewSpecNode, type PreviewValue, type PropMapping, type PropMappingConflict, type PropMappingResult, type PropMappingRule, type RewritableElement, type RewritableSpec, SYNTHETIC_TEXT_SLOT_PROP, type Slot, type SlotCell, type SpecRewrite, type SpecToJsxOptions, type SpecToJsxResult, UNRESOLVED, applyForcedModifiers, applyPropMapping, buildAcceptsChildNodes, buildClassifyChildNodes, collapseWrappedTextLabels, collectForcedModifierProps, componentPathAfter, composeRenames, documentRenamesFromPatches, documentRenamesFromSource, glyphJsxForm, glyphMemberOf, graftPreviewElements, graftSlotContent, hasPreviewElementDeep, hasUnresolvedProps, isComponentRef, isPreviewElement, isPreviewRef, jsxIdentifier, jsxToSpec, mapComponentProps, onlyMapsProps, parseGlyphType, previewElementNodes, previewElementType, propMappingErrors, propMappingRuleSchema, propMappingRulesSchema, propMappingsIn, rewriteSpecRefs, specToJsx, stripInjectedSlots, stripUnresolvedProps, styleNumberReadingRenames, withContainerChildSlots, withEmptyNodeSlots, withRenderSlots };
+export { type AcceptsChildNodes, type Cell, type CellSlot, type ChildNodesClassification, type ClassifyChildNodes, type CollapseTextLabelsResult, type CollapsedTextLabel, type DocumentRename, type GlyphJsxForm, type GlyphNodeResolver, type GraftableElement, type GraftableSpec, type JsxToSpecOptions, type MappedInstance, type MappedProps, type MappingScope, type MatchedValue, type PreviewElement, type PreviewRef, type PreviewSpecNode, type PreviewValue, type PropMapping, type PropMappingConflict, type PropMappingResult, type PropMappingRule, type RewritableElement, type RewritableSpec, SYNTHETIC_TEXT_SLOT_PROP, type Slot, type SlotCell, type SpecRewrite, type SpecToJsxOptions, type SpecToJsxResult, UNRESOLVED, applyForcedModifiers, applyPropMapping, buildAcceptsChildNodes, buildClassifyChildNodes, collapseWrappedTextLabels, collectForcedModifierProps, componentPathAfter, composeRenames, documentRenamesFromPatches, documentRenamesFromSource, glyphJsxForm, glyphMemberOf, graftPreviewElements, graftSlotContent, hasPreviewElementDeep, hasUnresolvedProps, isComponentRef, isPreviewElement, isPreviewRef, jsxIdentifier, jsxToSpec, mapComponentProps, mapPropsRulesSchema, mappingFromSchema, mappingScopeSchema, onlyMapsProps, parseGlyphType, previewElementNodes, previewElementType, propMappingErrors, propMappingRuleSchema, propMappingRulesSchema, propMappingsIn, rewriteSpecRefs, specToJsx, stripInjectedSlots, stripUnresolvedProps, styleNumberReadingRenames, swapMappingRulesSchema, withContainerChildSlots, withEmptyNodeSlots, withRenderSlots };

package/dist/spec/index.js

@@ -1,6 +1,6 @@
 import { graftPreviewElements, graftSlotContent, hasPreviewElementDeep, isComponentRef, isPreviewElement, isPreviewRef, previewElementNodes, previewElementType } from "./preview-elements.js";
 import { componentPathAfter, composeRenames, documentRenamesFromPatches, documentRenamesFromSource, rewriteSpecRefs, styleNumberReadingRenames } from "./rewrite-refs.js";
-import { applyPropMapping, mapComponentProps, onlyMapsProps, propMappingErrors, propMappingRuleSchema, propMappingRulesSchema, propMappingsIn } from "./prop-mapping.js";
+import { applyPropMapping, mapComponentProps, mapPropsRulesSchema, mappingFromSchema, mappingScopeSchema, onlyMapsProps, propMappingErrors, propMappingRuleSchema, propMappingRulesSchema, propMappingsIn, swapMappingRulesSchema } from "./prop-mapping.js";
 import { glyphJsxForm, glyphMemberOf, jsxIdentifier, parseGlyphType } from "./glyph-jsx.js";
 import { applyForcedModifiers, collectForcedModifierProps } from "./apply-forced-modifiers.js";
 import { collapseWrappedTextLabels } from "./collapse-text-labels.js";
@@ -26,4 +26,4 @@ import { specToJsx } from "./specToJsx.js";
 *  element, without changing the rendered layer hierarchy. */
 const SYNTHETIC_TEXT_SLOT_PROP = "data-uds-synthetic-text-slot";
 //#endregion
-export { SYNTHETIC_TEXT_SLOT_PROP, UNRESOLVED, applyForcedModifiers, applyPropMapping, buildAcceptsChildNodes, buildClassifyChildNodes, collapseWrappedTextLabels, collectForcedModifierProps, componentPathAfter, composeRenames, documentRenamesFromPatches, documentRenamesFromSource, glyphJsxForm, glyphMemberOf, graftPreviewElements, graftSlotContent, hasPreviewElementDeep, hasUnresolvedProps, isComponentRef, isPreviewElement, isPreviewRef, jsxIdentifier, jsxToSpec, mapComponentProps, onlyMapsProps, parseGlyphType, previewElementNodes, previewElementType, propMappingErrors, propMappingRuleSchema, propMappingRulesSchema, propMappingsIn, rewriteSpecRefs, specToJsx, stripInjectedSlots, stripUnresolvedProps, styleNumberReadingRenames, withContainerChildSlots, withEmptyNodeSlots, withRenderSlots };
+export { SYNTHETIC_TEXT_SLOT_PROP, UNRESOLVED, applyForcedModifiers, applyPropMapping, buildAcceptsChildNodes, buildClassifyChildNodes, collapseWrappedTextLabels, collectForcedModifierProps, componentPathAfter, composeRenames, documentRenamesFromPatches, documentRenamesFromSource, glyphJsxForm, glyphMemberOf, graftPreviewElements, graftSlotContent, hasPreviewElementDeep, hasUnresolvedProps, isComponentRef, isPreviewElement, isPreviewRef, jsxIdentifier, jsxToSpec, mapComponentProps, mapPropsRulesSchema, mappingFromSchema, mappingScopeSchema, onlyMapsProps, parseGlyphType, previewElementNodes, previewElementType, propMappingErrors, propMappingRuleSchema, propMappingRulesSchema, propMappingsIn, rewriteSpecRefs, specToJsx, stripInjectedSlots, stripUnresolvedProps, styleNumberReadingRenames, swapMappingRulesSchema, withContainerChildSlots, withEmptyNodeSlots, withRenderSlots };

package/dist/spec/prop-mapping.d.ts

@@ -15,10 +15,19 @@ interface PropMappingRule {
   readonly unset?: readonly string[];
 }
 interface PropMapping {
-  /** The component whose instances it rewrites, as a path. */
+  /** The component whose instances it rewrites, as a path. With `from`, the one they become. */
   readonly component: string;
+  /** The component whose instances become `component`'s, as a path; it needn't exist anymore. */
+  readonly from?: string;
+  /** Limits it to some nodes of one design file, by its canvas id and their ids: Create's alone. */
+  readonly only?: MappingScope;
   readonly rules: readonly PropMappingRule[];
 }
+/** Some nodes of one design file. */
+interface MappingScope {
+  readonly canvas: string;
+  readonly nodes: readonly string[];
+}
 /** A rule as a tool takes it: the shape every surface that applies a mapping parses its input with. */
 declare const propMappingRuleSchema: z.ZodObject<{
   when: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
@@ -31,6 +40,29 @@ declare const propMappingRulesSchema: z.ZodArray<z.ZodObject<{
   set: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
   unset: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>>;
+/** A swap's rules: none is a swap that keeps every prop, and `when: {}` reaches every swapped instance. */
+declare const swapMappingRulesSchema: 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>>;
+/**
+ * A mapping's rules as `map-props` takes them: at least one for a mapping, any number for a swap
+ * (`from`), where none keeps the swapped instances' props and `when: {}` reaches every one of them.
+ * Required by the op's own check rather than the schema, so one shape serves both.
+ */
+declare const mapPropsRulesSchema: 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>>>;
+/** `only` as a tool takes it. */
+declare const mappingScopeSchema: z.ZodObject<{
+  canvas: z.ZodString;
+  nodes: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+/** `from` as a tool takes it. */
+declare const mappingFromSchema: z.ZodString;
 /**
  * The mappings a batch of edits carries, in order: each `component/map-props` op as the mapping it
  * applies. The op changes nothing in the config, so the host that ran the batch applies these to the
@@ -94,4 +126,4 @@ type MappedProps = {
  */
 declare function mapComponentProps(config: Config, mapping: PropMapping, instances: readonly Record<string, unknown>[]): MappedProps;
 //#endregion
-export { MappedInstance, MappedProps, MatchedValue, PropMapping, PropMappingConflict, PropMappingResult, PropMappingRule, applyPropMapping, mapComponentProps, onlyMapsProps, propMappingErrors, propMappingRuleSchema, propMappingRulesSchema, propMappingsIn };
+export { MappedInstance, MappedProps, MappingScope, MatchedValue, PropMapping, PropMappingConflict, PropMappingResult, PropMappingRule, applyPropMapping, mapComponentProps, mapPropsRulesSchema, mappingFromSchema, mappingScopeSchema, onlyMapsProps, propMappingErrors, propMappingRuleSchema, propMappingRulesSchema, propMappingsIn, swapMappingRulesSchema };

package/dist/spec/prop-mapping.js

@@ -22,6 +22,11 @@ import { z } from "zod";
 * Positions follow the rename rewriter's: an element's own props, every modifier block nested in
 * them (`_hover: { variant: … }` is the same element's props under a condition), and each
 * `layerProps` bag whose layer renders the component.
+*
+* A mapping with `from` also swaps the component: instances of `from`, a component the system
+* may no longer have (the Bridge's `SelectContent`, after a take made in code replaced it), become
+* instances of `component`, and the rules move their props onto it. Which component replaces which
+* is as much a decision as a prop's new spelling, so it comes from the person too.
 */
 /** A rule as a tool takes it: the shape every surface that applies a mapping parses its input with. */
 const propMappingRuleSchema = z.object({
@@ -35,6 +40,21 @@ const propMappingRuleSchema = z.object({
 });
 /** The rules of a mapping, as a tool takes them. */
 const propMappingRulesSchema = z.array(propMappingRuleSchema).min(1).describe("Every rule whose `when` matches an instance as stored applies to it, so separate props are mapped by separate rules, and a combination by one rule naming both.");
+/** A swap's rules: none is a swap that keeps every prop, and `when: {}` reaches every swapped instance. */
+const swapMappingRulesSchema = z.array(propMappingRuleSchema).describe("The rules for the swapped instances, as a mapping has them. `when: {}` applies to every one of them (to `unset` a prop the new component lacks), and none keeps their props as they are.");
+/**
+* A mapping's rules as `map-props` takes them: at least one for a mapping, any number for a swap
+* (`from`), where none keeps the swapped instances' props and `when: {}` reaches every one of them.
+* Required by the op's own check rather than the schema, so one shape serves both.
+*/
+const mapPropsRulesSchema = z.array(propMappingRuleSchema).default([]).describe("Every rule whose `when` matches an instance as stored applies to it, so separate props are mapped by separate rules, and a combination by one rule naming both. A mapping needs at least one. With `from`, none keeps the swapped instances' props, and `when: {}` reaches every swapped instance.");
+/** `only` as a tool takes it. */
+const mappingScopeSchema = z.object({
+	canvas: z.string().min(1).describe("The design file's canvas id."),
+	nodes: z.array(z.string().min(1)).min(1).describe("The ids of the nodes it reaches, in that design file.")
+}).describe("Create only: limits the mapping to these nodes of one design file, for fixing one instance before asking about the rest. A checkout's call sites aren't nodes, so there it isn't taken.");
+/** `from` as a tool takes it. */
+const mappingFromSchema = z.string().min(1).describe("The component whose instances become this one's, as a path: the one a design file still names after the system lost it (`SelectContent`, replaced by `SelectMenu`). It needn't exist. Which component replaces which is the user's call: propose it, and apply it only once they confirm.");
 /**
 * The mappings a batch of edits carries, in order: each `component/map-props` op as the mapping it
 * applies. The op changes nothing in the config, so the host that ran the batch applies these to the
@@ -45,10 +65,15 @@ function propMappingsIn(edits) {
 	return edits.flatMap((edit) => {
 		const { op } = editOp(edit);
 		if (op.kind !== "component" || op.operation !== "map-props") return [];
-		const rules = propMappingRulesSchema.safeParse(op.data?.rules);
+		const data = op.data;
+		const from = typeof data?.from === "string" ? data.from : void 0;
+		const only = mappingScopeSchema.safeParse(data?.only);
+		const rules = (from ? swapMappingRulesSchema : propMappingRulesSchema).safeParse(data?.rules ?? (from ? [] : void 0));
 		if (!rules.success || typeof op.path !== "string") return [];
 		return [{
 			component: op.path.replace(/^component:/, ""),
+			...from ? { from: from.replace(/^component:/, "") } : {},
+			...only.success ? { only: only.data } : {},
 			rules: rules.data
 		}];
 	});
@@ -81,9 +106,10 @@ function valueRefusal(config, component, prop, value) {
 */
 function propMappingErrors(config, mapping) {
 	if (!config.resolve("component", mapping.component)) return [`No component "${mapping.component}"`];
+	if (mapping.from === mapping.component) return [`"${mapping.component}" can't replace itself: \`from\` names the component its instances are now`];
 	const errors = [];
 	mapping.rules.forEach((rule, i) => {
-		if (Object.keys(rule.when).length === 0) errors.push(`Rule ${i + 1} matches every instance: name what it matches in \`when\``);
+		if (Object.keys(rule.when).length === 0 && mapping.from === void 0) errors.push(`Rule ${i + 1} matches every instance: name what it matches in \`when\``);
 		for (const [name, value] of Object.entries(rule.set ?? {})) {
 			const prop = surfaceProp(config, mapping.component, name);
 			if (!prop) {
@@ -125,6 +151,11 @@ function mapBag(bag, rules) {
 		bag: next
 	};
 }
+/** A stored type naming `to` in place of what it names, keeping the source it was placed through. */
+function retyped(type, to) {
+	const at = type.lastIndexOf("@");
+	return `component:${to}${type.includes(":") && at > 0 ? type.slice(at) : ""}`;
+}
 /**
 * A props bag on `component`, with the mapping applied to it when it's the mapped component's, and
 * to the modifier blocks and layer overrides inside it either way. `undefined` when nothing moved.
@@ -192,8 +223,10 @@ function applyPropMapping(config, spec, mapping) {
 	let elements;
 	let changed = 0;
 	const conflicts = [];
+	const reached = mapping.only ? new Set(mapping.only.nodes) : void 0;
 	for (const [key, element] of Object.entries(spec.elements ?? {})) {
-		if (!element?.props) continue;
+		if (!element) continue;
+		if (reached && !reached.has(key)) continue;
 		const walk = {
 			config,
 			mapping,
@@ -201,14 +234,18 @@ function applyPropMapping(config, spec, mapping) {
 			conflicts,
 			changed: 0
 		};
-		const props = mapProps(walk, componentOf(element.type), element.props, "props");
-		if (!props) continue;
+		const component = componentOf(element.type);
+		const swapped = mapping.from !== void 0 && component === mapping.from && typeof element.type === "string";
+		if (!swapped && !element.props) continue;
+		const props = mapProps(walk, swapped ? mapping.component : component, element.props ?? {}, "props");
+		if (!props && !swapped) continue;
 		elements ??= { ...spec.elements };
 		elements[key] = {
 			...element,
-			props
+			...swapped ? { type: retyped(element.type, mapping.component) } : {},
+			...props ? { props } : {}
 		};
-		changed += walk.changed;
+		changed += walk.changed + (swapped && walk.changed === 0 ? 1 : 0);
 	}
 	return elements ? {
 		spec: {
@@ -236,7 +273,7 @@ function mapComponentProps(config, mapping, instances) {
 		errors
 	};
 	const { spec, conflicts } = applyPropMapping(config, { elements: Object.fromEntries(instances.map((props, i) => [String(i), {
-		type: `component:${mapping.component}`,
+		type: `component:${mapping.from ?? mapping.component}`,
 		props
 	}])) }, mapping);
 	return {
@@ -245,11 +282,11 @@ function mapComponentProps(config, mapping, instances) {
 			const after = spec.elements?.[String(i)]?.props ?? props;
 			return {
 				props: after,
-				changed: after !== props,
+				changed: after !== props || mapping.from !== void 0,
 				conflicts: conflicts.filter((conflict) => conflict.element === String(i)).flatMap((conflict) => conflict.props)
 			};
 		})
 	};
 }
 //#endregion
-export { applyPropMapping, mapComponentProps, onlyMapsProps, propMappingErrors, propMappingRuleSchema, propMappingRulesSchema, propMappingsIn };
+export { applyPropMapping, mapComponentProps, mapPropsRulesSchema, mappingFromSchema, mappingScopeSchema, onlyMapsProps, propMappingErrors, propMappingRuleSchema, propMappingRulesSchema, propMappingsIn, swapMappingRulesSchema };