@yahoo/uds-create-config 5.68.4 → 5.69.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,7 @@ 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 { CanvasRole } from "../entities/system/CanvasRole.js";
 import { GlobalStyle } from "../entities/system/GlobalStyle.js";
 import { Guidance } from "../entities/system/Guidance.js";
@@ -203,5 +204,6 @@ 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);
 //#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/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/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 = 20261030163028;
+declare const SERIALIZED_CONFIG_VERSION = 20261102143821;
 interface SerializedConfig {
   /** See {@link SERIALIZED_CONFIG_VERSION}. Always written; a stored artifact may lack it. */
   readonly version: number;
@@ -1382,6 +1382,16 @@ declare class Config {
    * subgroup (`color/brand/primary`) belongs to `color` too. Getting either wrong is silent: one drags
    * an unrelated group along, the other skips half of what the user sees under the heading.
    */
+  /**
+   * The parts a rename of `from` to `to` moves with it, for a kind that declares
+   * {@link EntityKind.parts}: every item named under `from`, at any depth.
+   */
+  private partMoves;
+  /** The parts renaming `path` to `to` would move with it — see {@link EntityKind.parts}. */
+  renamedParts(kind: string, path: string, to: string): {
+    from: string;
+    to: string;
+  }[];
   private groupMembers;
   /**
    * The declared group nodes nested under `group`, at any depth. Sub-groups are stored apart from a

package/dist/framework/Config.js

@@ -2169,10 +2169,23 @@ var Config = class Config {
 			if (borrowed !== void 0 && isRef(storedBody) && pathOf(storedBody) === patch.path) reject("UNSUPPORTED", `Cannot rename ${patch.kind} "${patch.path}" — it carries "${borrowed}"'s own name for it. Place it at a path of your own to name it, or link it as a value.`);
 			const { value } = extension ? extensionChange(entry, patch.kind, patch.to, extension, false) : itemChange(entry, patch.kind, patch.to, stored);
 			const moved = snapshot.withRenamed(patch.kind, "item", patch.path, patch.to, value);
-			return this.cascadeRename(moved, `${patch.kind}:${patch.path}`, `${patch.kind}:${patch.to}`, this.entityOf(patch.kind)?.sourceIdentity ? {
+			let next = this.cascadeRename(moved, `${patch.kind}:${patch.path}`, `${patch.kind}:${patch.to}`, this.entityOf(patch.kind)?.sourceIdentity ? {
 				from: patch.path,
 				to: patch.to
 			} : void 0);
+			const parts = this.partMoves(snapshot, entry, patch.path, patch.to);
+			for (const part of parts) {
+				const taken = snapshot.get(patch.kind, part.to);
+				if (taken && !isMintedRow(taken.toJSON())) reject("ALREADY_EXISTS", `Cannot rename ${patch.kind} "${patch.path}" to "${patch.to}" — its part "${part.from}" would land on the ${patch.kind} already at "${part.to}".`);
+			}
+			for (const part of parts) {
+				const current = next.get(patch.kind, part.from);
+				if (!current) continue;
+				const { value } = itemChange(entry, patch.kind, part.to, current.toJSON());
+				next = next.withRenamed(patch.kind, "item", part.from, part.to, value);
+				next = this.cascadeRename(next, `${patch.kind}:${part.from}`, `${patch.kind}:${part.to}`);
+			}
+			return next;
 		}
 		const updateSchema = dataSchema(entry.schemas, "update");
 		if (!updateSchema) reject("UNSUPPORTED", `${patch.kind} has no update operation`);
@@ -2796,6 +2809,22 @@ var Config = class Config {
 	* subgroup (`color/brand/primary`) belongs to `color` too. Getting either wrong is silent: one drags
 	* an unrelated group along, the other skips half of what the user sees under the heading.
 	*/
+	/**
+	* The parts a rename of `from` to `to` moves with it, for a kind that declares
+	* {@link EntityKind.parts}: every item named under `from`, at any depth.
+	*/
+	partMoves(snapshot, entry, from, to) {
+		if (!entry.parts || from === to) return [];
+		return this.groupMembers(snapshot, entry.name, from).map(({ path }) => ({
+			from: path,
+			to: `${to}${path.slice(from.length)}`
+		}));
+	}
+	/** The parts renaming `path` to `to` would move with it — see {@link EntityKind.parts}. */
+	renamedParts(kind, path, to) {
+		const entry = this.entityOf(kind);
+		return entry ? this.partMoves(this.state.snapshot, entry, path, to) : [];
+	}
 	groupMembers(snapshot, kind, group) {
 		const members = [];
 		for (const [path, entity] of snapshot.slice(kind).items) if (path.startsWith(`${group}/`)) members.push({
@@ -6362,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 > 20261030163028) throw new SchemaVersionTooNew(claimed);
+		if (claimed > 20261102143821) 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/class-names.d.ts

@@ -1,5 +1,5 @@
 import { Config } from "./Config.js";
-import { ComponentState, UDS_FORCE_STATES, componentStateDefaults, componentStates } from "./component-states.js";
+import { ComponentState, UDS_FORCE_STATES, componentStateDefaults, componentStates, instanceStatePins } from "./component-states.js";
 
 //#region src/framework/class-names.d.ts
 /** `HStack` → `hstack`, `AvatarItem` → `avatar-item`. A dash only between a lower/digit and an

package/dist/framework/component-states.d.ts

@@ -36,5 +36,20 @@ declare function componentStates(config: Config, path: string): readonly Compone
  * variant state with no default has no rest value, so a rule naming one of its values waits for one.
  */
 declare function componentStateDefaults(config: Config, path: string): Record<string, string | boolean>;
+/**
+ * The states a placed instance is pinned in, read off its props: its pins under
+ * {@link UDS_FORCE_STATES}, and a value stored under a state's own name where no pin names that
+ * state. The render reads a stored instance the same way, so a surface showing the pins shows what
+ * paints.
+ */
+declare function instanceStatePins({
+  config,
+  path,
+  props
+}: {
+  config: Config;
+  path: string;
+  props: Readonly<Record<string, unknown>> | undefined;
+}): Record<string, unknown>;
 //#endregion
-export { ComponentState, UDS_FORCE_STATES, componentStateDefaults, componentStates };
+export { ComponentState, UDS_FORCE_STATES, componentStateDefaults, componentStates, instanceStatePins };

package/dist/framework/component-states.js

@@ -49,5 +49,21 @@ function componentStateDefaults(config, path) {
 	else if (state.default !== void 0) out[state.name] = state.default;
 	return out;
 }
+/**
+* The states a placed instance is pinned in, read off its props: its pins under
+* {@link UDS_FORCE_STATES}, and a value stored under a state's own name where no pin names that
+* state. The render reads a stored instance the same way, so a surface showing the pins shows what
+* paints.
+*/
+function instanceStatePins({ config, path, props }) {
+	const held = props?.[UDS_FORCE_STATES];
+	const pins = held && typeof held === "object" && !Array.isArray(held) ? held : {};
+	const out = {};
+	for (const { name } of componentStates(config, path)) if (props?.[name] !== void 0) out[name] = props[name];
+	return {
+		...out,
+		...pins
+	};
+}
 //#endregion
-export { UDS_FORCE_STATES, componentStateDefaults, componentStates };
+export { UDS_FORCE_STATES, componentStateDefaults, componentStates, instanceStatePins };

package/dist/framework/defineEntity.d.ts

@@ -316,7 +316,8 @@ declare function defineEntity<F extends FieldsSchema, G extends FieldsSchema = z
    * mean the ref has to say which.
    */
   bareMember?: string; /** Whether a leaf names an item on its own — see {@link EntityKind.uniqueLeaves}. */
-  uniqueLeaves?: boolean; /** For a source kind: how a pin's source joins this config. See {@link EntityKind.sourceType}. */
+  uniqueLeaves?: boolean; /** Whether an item nested under another is a part of it — see {@link EntityKind.parts}. */
+  parts?: boolean; /** For a source kind: how a pin's source joins this config. See {@link EntityKind.sourceType}. */
   sourceType?: (body: Record<string, unknown>) => SourceType; /** This config answers for every item of the kind. See {@link EntityKind.answeredHere}. */
   answeredHere?: boolean;
   /**

package/dist/framework/defineEntity.js

@@ -131,6 +131,7 @@ function defineEntity(spec) {
 		styleBags: spec.styleBags,
 		rewriteName: spec.rewriteName,
 		uniqueLeaves: spec.uniqueLeaves,
+		parts: spec.parts,
 		authoredValue: spec.authoredValue,
 		mentionFields: spec.mentionFields,
 		invariants: spec.invariants,

package/dist/framework/plan.d.ts

@@ -32,6 +32,11 @@ interface RenamePlan {
   /** Rows that use the entity through a source, whose body names it there. The cascade can't rewrite
    *  them, so after the rename they name a path this config no longer holds. */
   readonly throughSource: readonly EntityAddress[];
+  /** The parts that move with it, each to its place under the new path. Absent when there are none. */
+  readonly moves?: readonly {
+    readonly from: string;
+    readonly to: string;
+  }[];
   /** Why the rename would be refused. `undefined` when it would go through. */
   readonly blocked?: string;
 }

package/dist/framework/plan.js

@@ -34,6 +34,9 @@ function blockedBy(attempt) {
 		throw error;
 	}
 }
+function unique(refs) {
+	return [...new Set(refs)];
+}
 function addresses(targets) {
 	return targets.map((target) => {
 		const { kind, qualifiedPath } = splitRef(target);
@@ -50,13 +53,17 @@ function planRename({ config, kind, path, to }) {
 		path,
 		to
 	}]));
-	const throughSource = config.sourceDependentsOf(kind, path);
+	const moves = config.renamedParts(kind, path, to);
+	const moving = [path, ...moves.map((move) => move.from)];
+	const throughSource = unique(moving.flatMap((from) => config.sourceDependentsOf(kind, from)));
 	const drawn = new Set(throughSource);
+	const moved = new Set(moving.map((from) => `${kind}:${from}`));
 	return {
 		from: path,
 		to,
-		rewrites: addresses(config.dependentsOf(kind, path).filter((ref) => !drawn.has(ref))),
+		rewrites: addresses(unique(moving.flatMap((from) => config.dependentsOf(kind, from))).filter((ref) => !drawn.has(ref) && !moved.has(ref))),
 		throughSource: addresses(throughSource),
+		...moves.length > 0 ? { moves } : {},
 		...blocked === void 0 ? {} : { blocked }
 	};
 }

package/dist/framework/registry.d.ts

@@ -330,6 +330,11 @@ interface EntityKind {
    * leaf, since neither can hold a slash.
    */
   readonly uniqueLeaves?: boolean;
+  /**
+   * Whether an item named under another item of the kind is a part of it — `Card/Header` of `Card`.
+   * A rename of the item then moves its parts to the new path with it, and their refs follow.
+   */
+  readonly parts?: boolean;
   /**
    * An extra authored form for a value whose domain is this kind, beside the leaf and the ref every
    * domain takes. Asked when a ref domain's schema is built, with the target the domain names and the

package/dist/framework/registry.js

@@ -30,7 +30,7 @@ function titleCase(kind) {
 	return kind.split(/[-_]/).filter(Boolean).map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
 }
 function buildKind(spec) {
-	const { name, prepareLinkedBody, rebaseLinkedBody, layerKeys, fields, groupFields, subEntities = {}, computed, label, labelPlural, schemas: userSchemas, derived, sourceIdentity, sourceOrigin, authoredRefs, linkable, localGroupFields, emergentGroups, singleton = false, bareMember, sourceResolution, bulkAdopts, bulkExcludes, bulkOverlay, bulkDirectives, bulkOverlayWrite, nameEdges, rewriteName, styleBags, uniqueLeaves, authoredValue, mentionFields, invariants, structuralBody, authoredBody, sourceType, answeredHere } = spec;
+	const { name, prepareLinkedBody, rebaseLinkedBody, layerKeys, fields, groupFields, subEntities = {}, computed, label, labelPlural, schemas: userSchemas, derived, sourceIdentity, sourceOrigin, authoredRefs, linkable, localGroupFields, emergentGroups, singleton = false, bareMember, sourceResolution, bulkAdopts, bulkExcludes, bulkOverlay, bulkDirectives, bulkOverlayWrite, nameEdges, rewriteName, styleBags, uniqueLeaves, parts, authoredValue, mentionFields, invariants, structuralBody, authoredBody, sourceType, answeredHere } = spec;
 	const allComputed = {
 		sources: ({ member, config }) => sourceSlugs(member, config),
 		borrowedFrom: ({ config, path }) => config.borrowedFrom(name, path),
@@ -79,6 +79,7 @@ function buildKind(spec) {
 		rewriteName,
 		styleBags,
 		...uniqueLeaves ? { uniqueLeaves } : {},
+		...parts ? { parts } : {},
 		...authoredValue ? { authoredValue } : {},
 		...mentionFields?.length ? { mentionFields } : {},
 		...invariants ? { invariants } : {},

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