@yahoo/uds-create-config 5.68.5 → 5.70.0

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

@@ -76,6 +76,24 @@ declare const ReactNativeSystemDefinition: ConfigClass<{
         reason: _$zod.ZodString;
       }, _$zod_v4_core0.$strict>>>;
     }, _$zod_v4_core0.$strict>>;
+    defaults: _$zod.ZodOptional<_$zod.ZodObject<{
+      background: _$zod.ZodOptional<_$zod.ZodUnion<readonly [_$zod.ZodUnion<readonly [_$zod.ZodString, _$zod.ZodObject<{
+        __ref: _$zod.ZodString;
+      }, _$zod_v4_core0.$strip>]>, _$zod.ZodObject<{
+        value: _$zod.ZodUnion<readonly [_$zod.ZodString, _$zod.ZodObject<{
+          __ref: _$zod.ZodString;
+        }, _$zod_v4_core0.$strip>]>;
+        output: _$zod.ZodOptional<_$zod.ZodBoolean>;
+      }, _$zod_v4_core0.$strict>]>>;
+      color: _$zod.ZodOptional<_$zod.ZodUnion<readonly [_$zod.ZodUnion<readonly [_$zod.ZodString, _$zod.ZodObject<{
+        __ref: _$zod.ZodString;
+      }, _$zod_v4_core0.$strip>]>, _$zod.ZodObject<{
+        value: _$zod.ZodUnion<readonly [_$zod.ZodString, _$zod.ZodObject<{
+          __ref: _$zod.ZodString;
+        }, _$zod_v4_core0.$strip>]>;
+        output: _$zod.ZodOptional<_$zod.ZodBoolean>;
+      }, _$zod_v4_core0.$strict>]>>;
+    }, _$zod_v4_core0.$strict>>;
   }, "css" | "playground" | "canvas"> & {
     canvas: _$zod.ZodOptional<_$zod.ZodObject<{
       packageAliases: _$zod.ZodOptional<_$zod.ZodRecord<_$zod.ZodString, _$zod.ZodString>>;

package/dist/configs/system.js

@@ -35,6 +35,8 @@ import { variantValuesListWithBodiesMigration } from "../migrations/202610271844
 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 { CanvasRole } from "../entities/system/CanvasRole.js";
 import { GlobalStyle } from "../entities/system/GlobalStyle.js";
 import { Guidance } from "../entities/system/Guidance.js";
@@ -203,5 +205,7 @@ if (!registeredSchemaMigrations().has(20261027184442)) registerSchemaMigrations(
 if (!registeredSchemaMigrations().has(20261027205147)) registerSchemaMigrations(lintIgnoreMigration);
 if (!registeredSchemaMigrations().has(20261030134149)) registerSchemaMigrations(componentMapPropsMigration);
 if (!registeredSchemaMigrations().has(20261030163028)) registerSchemaMigrations(layerPrefixMigration);
+if (!registeredSchemaMigrations().has(20261102143821)) registerSchemaMigrations(defaultColorsMigration);
+if (!registeredSchemaMigrations().has(20261102185610)) registerSchemaMigrations(linkReplaceMigration);
 //#endregion
 export { System };

package/dist/entities/native/NativeSettings.d.ts

@@ -65,6 +65,24 @@ declare const NativeSettings: EntityClass<z.ZodObject<Omit<{
       reason: z.ZodString;
     }, z.core.$strict>>>;
   }, z.core.$strict>>;
+  defaults: z.ZodOptional<z.ZodObject<{
+    background: z.ZodOptional<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+      __ref: z.ZodString;
+    }, z.core.$strip>]>, z.ZodObject<{
+      value: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        __ref: z.ZodString;
+      }, z.core.$strip>]>;
+      output: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>]>>;
+    color: z.ZodOptional<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+      __ref: z.ZodString;
+    }, z.core.$strip>]>, z.ZodObject<{
+      value: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        __ref: z.ZodString;
+      }, z.core.$strip>]>;
+      output: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>]>>;
+  }, z.core.$strict>>;
 }, "css" | "playground" | "canvas"> & {
   canvas: z.ZodOptional<z.ZodObject<{
     packageAliases: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;

package/dist/entities/system/Component.js

@@ -152,6 +152,19 @@ function freeLayerKey(config, path, hint = "el") {
 	return `${hint}${ordinal}`;
 }
 /**
+* The name a duplicate of the layer `source` takes: its name without a trailing number, numbered
+* from 2 past every name the component already holds, so `box` copies to `box2` and `box2` to
+* `box3` rather than `box21`.
+*/
+function duplicateLayerKey({ config, path, source }) {
+	const body = config.resolve("component", path)?.toJSON();
+	const taken = new Set([...Object.keys(body?.layers ?? {}), ...Object.keys(body?.anatomy ?? {})]);
+	const base = source.replace(/\d+$/, "") || source;
+	let ordinal = 2;
+	while (taken.has(`${base}${ordinal}`)) ordinal += 1;
+	return `${base}${ordinal}`;
+}
+/**
 * A `kind:path` marker string as the ref it means.
 *
 * A spec element stores its type as a marker (`component:primitives/Box`), and `element` accepts a
@@ -2026,6 +2039,7 @@ function withoutProps(conditions, names) {
 }
 const ComponentEntity = defineEntity({
 	kind: "component",
+	parts: true,
 	rebaseLinkedBody: (args) => {
 		const body = { ...translateLinkedStyleBags({
 			...args,
@@ -2427,7 +2441,11 @@ count: z.number().int().min(1).max(50).optional() }).prefault({})
 				let next = config;
 				let previous = source;
 				for (let n = 0; n < count; n++) {
-					const key = freeLayerKey(next, path, source);
+					const key = duplicateLayerKey({
+						config: next,
+						path,
+						source
+					});
 					const siblings = (next.resolve("component", path)?.toJSON())?.anatomy?.[parent]?.children ?? [];
 					const index = siblings.indexOf(previous) + 1;
 					next = next.run([{

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/Settings.d.ts

@@ -121,6 +121,59 @@ declare const LintSectionDefinition: SubEntityClass<z.ZodObject<{
 }, z.core.$strict>>;
 interface LintSectionClass extends Named<typeof LintSectionDefinition> {}
 declare const LintSection: LintSectionClass;
+/** A default colour: a CSS colour as written, or a token, which follows the modes it is painted
+ *  under. `refTo` rather than the `Token` class, which imports back into this module. */
+declare const defaultColorValue: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+  __ref: z.ZodString;
+}, z.core.$strip>]>;
+type DefaultColorValue = z.output<typeof defaultColorValue>;
+/** A default colour on its own, or with `output` saying whether the stylesheet's body rule carries
+ *  it. */
+declare const defaultColor: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+  __ref: z.ZodString;
+}, z.core.$strip>]>, z.ZodObject<{
+  value: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+    __ref: z.ZodString;
+  }, z.core.$strip>]>;
+  output: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>]>;
+/** The `defaults` section — the background and text colour a system's components sit on. */
+declare const DefaultsSectionDefinition: SubEntityClass<z.ZodObject<{
+  background: z.ZodOptional<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+    __ref: z.ZodString;
+  }, z.core.$strip>]>, z.ZodObject<{
+    value: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+      __ref: z.ZodString;
+    }, z.core.$strip>]>;
+    output: z.ZodOptional<z.ZodBoolean>;
+  }, z.core.$strict>]>>;
+  color: z.ZodOptional<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+    __ref: z.ZodString;
+  }, z.core.$strip>]>, z.ZodObject<{
+    value: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+      __ref: z.ZodString;
+    }, z.core.$strip>]>;
+    output: z.ZodOptional<z.ZodBoolean>;
+  }, z.core.$strict>]>>;
+}, z.core.$strict>>;
+interface DefaultsSectionClass extends Named<typeof DefaultsSectionDefinition> {}
+declare const DefaultsSection: DefaultsSectionClass;
+/** One default colour in its long form: the value, and whether the body rule carries it. */
+interface DefaultColor {
+  readonly value: DefaultColorValue;
+  readonly output: boolean;
+}
+/** A system's default colours, each in its long form; an unset one is absent. */
+interface DefaultColors {
+  readonly background?: DefaultColor;
+  readonly color?: DefaultColor;
+}
+/** A default colour as authored: the value alone, or `{ value, output }`. */
+type AuthoredDefaultColor = z.output<typeof defaultColor>;
+/** One default colour in its long form, whichever form it was written in. */
+declare function defaultColorOf(authored: AuthoredDefaultColor | undefined): DefaultColor | undefined;
+/** The `defaults` section as every reader takes it, whichever form each colour was written in. */
+declare function defaultColorsOf(config: Config): DefaultColors;
 /**
  * {@link derivedInputDir} over paths alone, for a build that has walked its source graph but not yet
  * written the `file` rows the computed `inputDir` reads. `components` are the config-relative paths
@@ -175,6 +228,24 @@ declare const SettingsDefinition: EntityClass<z.ZodObject<{
       reason: z.ZodString;
     }, z.core.$strict>>>;
   }, z.core.$strict>>;
+  defaults: z.ZodOptional<z.ZodObject<{
+    background: z.ZodOptional<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+      __ref: z.ZodString;
+    }, z.core.$strip>]>, z.ZodObject<{
+      value: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        __ref: z.ZodString;
+      }, z.core.$strip>]>;
+      output: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>]>>;
+    color: z.ZodOptional<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+      __ref: z.ZodString;
+    }, z.core.$strip>]>, z.ZodObject<{
+      value: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        __ref: z.ZodString;
+      }, z.core.$strip>]>;
+      output: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>]>>;
+  }, z.core.$strict>>;
 }, z.core.$strict>, z.ZodObject<Record<never, never>, z.core.$strip>, "settings", {}, {
   /**
    * The directory this system's component files are laid out beneath, always defined:
@@ -189,4 +260,4 @@ declare const SettingsDefinition: EntityClass<z.ZodObject<{
 interface SettingsClass extends Named<typeof SettingsDefinition> {}
 declare const Settings: SettingsClass;
 //#endregion
-export { BuildSection, BuildSectionClass, CSS_DEFAULTS, CssPrefix, CssSection, CssSectionClass, LintSection, LintSectionClass, PLAYGROUND_DEFAULTS, PlaygroundSection, PlaygroundSectionClass, Settings, SettingsClass, SystemSection, SystemSectionClass, classPrefixOf, cssPrefixes, deriveInputDir, layerPrefixOf, prefixed, varPrefixOf };
+export { AuthoredDefaultColor, BuildSection, BuildSectionClass, CSS_DEFAULTS, CssPrefix, CssSection, CssSectionClass, DefaultColor, DefaultColorValue, DefaultColors, DefaultsSection, DefaultsSectionClass, LintSection, LintSectionClass, PLAYGROUND_DEFAULTS, PlaygroundSection, PlaygroundSectionClass, Settings, SettingsClass, SystemSection, SystemSectionClass, classPrefixOf, cssPrefixes, defaultColorOf, defaultColorsOf, deriveInputDir, layerPrefixOf, prefixed, varPrefixOf };

package/dist/entities/system/Settings.js

@@ -1,4 +1,4 @@
-import { splitRef } from "../../framework/utils/refs.js";
+import { refTo, splitRef } from "../../framework/utils/refs.js";
 import { defineEntity } from "../../framework/defineEntity.js";
 import { defineSubEntity } from "../../framework/defineSubEntity.js";
 import { createSliceMemo } from "../../framework/memo.js";
@@ -23,8 +23,9 @@ import { z } from "zod";
 * field, and a clone emits only what the system chose. The defaults are the `*_DEFAULTS` constants
 * beside each section, which the readers fall back to.
 *
-* Not borrowed and not refed today. `linkable: false` is a statement about this kind, not about
-* singletons: a consumer's `link: '*'` must not inherit a source's build directories or CSS prefix.
+* Not borrowed and not refed. A `defaults` colour may ref a token, so renaming that token cascades
+* into it. `linkable: false` is a statement about this kind, not about singletons: a consumer's
+* `link: '*'` must not inherit a source's build directories or CSS prefix.
 */
 const systemFields = z.strictObject({ 
 /**
@@ -222,6 +223,55 @@ const LintSection = defineSubEntity({
 	singleton: true,
 	fields: lintFields
 });
+/** A default colour: a CSS colour as written, or a token, which follows the modes it is painted
+*  under. `refTo` rather than the `Token` class, which imports back into this module. */
+const defaultColorValue = z.union([z.string().min(1), refTo("token")]);
+/** A default colour on its own, or with `output` saying whether the stylesheet's body rule carries
+*  it. */
+const defaultColor = z.union([defaultColorValue, z.strictObject({
+	value: defaultColorValue,
+	output: z.boolean().optional()
+})]);
+const defaultsFields = z.strictObject({
+	background: defaultColor.meta({
+		title: "Background",
+		valueType: "color",
+		description: "The background this system's components sit on: a CSS colour (`#ffffff`) or a token (`Token.ref('color/surface')`). The stylesheet sets it on `body`, and Create paints it behind a component's matrix cells, under the modes picked there. `{ value, output: false }` keeps it out of the stylesheet. Unset, neither paints one."
+	}).optional(),
+	color: defaultColor.meta({
+		title: "Text color",
+		valueType: "color",
+		description: "The text colour this system's components inherit: a CSS colour or a token. The stylesheet sets it on `body`, and Create applies it to a component's matrix cells, under the modes picked there. `{ value, output: false }` keeps it out of the stylesheet. Unset, neither sets one."
+	}).optional()
+});
+const DefaultsSection = defineSubEntity({
+	name: "defaults",
+	label: "Defaults",
+	singleton: true,
+	fields: defaultsFields
+});
+/** One default colour in its long form, whichever form it was written in. */
+function defaultColorOf(authored) {
+	if (authored === void 0) return void 0;
+	if (typeof authored === "object" && "value" in authored) return {
+		value: authored.value,
+		output: authored.output ?? true
+	};
+	return {
+		value: authored,
+		output: true
+	};
+}
+/** The `defaults` section as every reader takes it, whichever form each colour was written in. */
+function defaultColorsOf(config) {
+	const defaults = Settings.get(config)?.defaults;
+	const background = defaultColorOf(defaults?.background);
+	const color = defaultColorOf(defaults?.color);
+	return {
+		...background ? { background } : {},
+		...color ? { color } : {}
+	};
+}
 /** The folders of a path, file name dropped. */
 const foldersOf = (file) => file.split("/").slice(0, -1);
 /** The folders every one of `lists` starts with. */
@@ -322,14 +372,16 @@ const Settings = defineEntity({
 		build: buildFields.meta({ title: "Build" }).optional(),
 		css: cssFields.meta({ title: "CSS" }).optional(),
 		playground: playgroundFields.meta({ title: "Playground" }).optional(),
-		lint: lintFields.meta({ title: "Lint" }).optional()
+		lint: lintFields.meta({ title: "Lint" }).optional(),
+		defaults: defaultsFields.meta({ title: "Defaults" }).optional()
 	}),
 	subEntities: {
 		system: SystemSection,
 		build: BuildSection,
 		css: CssSection,
 		playground: PlaygroundSection,
-		lint: LintSection
+		lint: LintSection,
+		defaults: DefaultsSection
 	},
 	computed: { 
 	/**
@@ -340,4 +392,4 @@ const Settings = defineEntity({
 inputDir: ({ member, config }) => resolveInputDir(member.build) ?? derivedInputDir(config) }
 });
 //#endregion
-export { BuildSection, CSS_DEFAULTS, CssSection, LintSection, PLAYGROUND_DEFAULTS, PlaygroundSection, Settings, SystemSection, classPrefixOf, cssPrefixes, deriveInputDir, layerPrefixOf, prefixed, varPrefixOf };
+export { BuildSection, CSS_DEFAULTS, CssSection, DefaultsSection, LintSection, PLAYGROUND_DEFAULTS, PlaygroundSection, Settings, SystemSection, classPrefixOf, cssPrefixes, defaultColorOf, defaultColorsOf, deriveInputDir, layerPrefixOf, prefixed, varPrefixOf };

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.
 *