@yahoo/uds-create-config 5.57.0 → 5.58.0

package/dist/authoring/define-component.d.ts

@@ -17,6 +17,7 @@
  * The returned handle is a ref AND an `Authored`, so it composes into other components and
  * registers through the generic bridge.
  */
+import { type PropsOrRules } from '../entities/system/prop-rules';
 import type { Authored } from '../framework/authoring';
 import { type Ref } from '../framework/utils/refs';
 /** A component handle — a ref (import/reference it), an `Authored` (register it), and a
@@ -69,7 +70,7 @@ interface Body<L, SP extends string, MOD extends string, P extends Record<string
         when: Record<string, string>;
         layers: LayerOverrides<L, SP, MOD>;
     }>;
-    defaultProps?: Record<string, unknown>;
+    defaultProps?: PropsOrRules<Record<string, unknown>>;
     label?: string;
     description?: string;
 }

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

@@ -13,7 +13,8 @@ import { StoredDefaultCondition } from "../../framework/default-conditions.js";
 import { StoredPreviewCondition } from "../../framework/preview-store.js";
 import { RepeatSpec } from "../../framework/render-spec.js";
 import { ComponentSourceInput } from "./component-source-fields.js";
-import { AsInput, AuthoredDefaultsOf, LayerMap, PhantomCallProps, PhantomReadProps, PropMap, RenderArgs, StateMap, StyleRuleInput } from "./defineComponent.js";
+import { PropsOrRules } from "./prop-rules.js";
+import { AsInput, AuthoredDefaultsOf, LayerMap, PhantomCallProps, PhantomReadProps, PropMap, RenderArgs, StateMap, StyleRuleInput, UnconditionalDefaults } from "./defineComponent.js";
 import { listSlots, namedSlots, slotHostedBy, slotOf, slotsFor } from "../../spec/slot.js";
 import { cellAt } from "../../spec/cell.js";
 import { instanceAt } from "../../spec/instance.js";
@@ -871,7 +872,9 @@ declare const ComponentEntity: EntityClass<z.ZodObject<{
   }: ComputedInput) => string[];
 }, false, Record<never, never>, Record<never, never>>;
 /** Source extensions declare their structure through .render(). */
-type ComponentRefDelta = ComponentSourceInput<Partial<CreateInput<typeof componentFields>>>;
+type ComponentRefDelta = Omit<ComponentSourceInput<Partial<CreateInput<typeof componentFields>>>, 'defaultProps'> & {
+  /** A record, or `.defaultProps`'s rule list; checked against the props by `ExtensionDefaults`. */readonly defaultProps?: PropsOrRules<Record<string, unknown>>;
+};
 type ExactComponentDelta<Delta> = Delta & { [Key in Exclude<keyof Delta, keyof ComponentRefDelta>]: never };
 type ContractLayers<Contract> = Contract extends {
   layers: infer Layers;
@@ -908,7 +911,7 @@ type ResolvedDefaults<Contract, Delta> = Delta extends {
   readonly defaultProps: infer Defaults;
 } ? OverlayContract<Contract extends {
   defaultProps: infer Base;
-} ? Base : Record<never, never>, Defaults> : Contract extends {
+} ? Base : Record<never, never>, UnconditionalDefaults<Defaults>> : Contract extends {
   defaultProps: infer Defaults;
 } ? Defaults : Record<never, never>;
 type ResolvedForwards<Contract, Delta> = Delta extends {

package/dist/entities/system/Component.js

@@ -27,9 +27,9 @@ import { instanceAt } from "../../spec/instance.js";
 import { forwardOptions, forwardsWrite } from "./component-forwards.js";
 import { assertComponentSourceInput } from "./component-source-fields.js";
 import { checkStyleSet, styleSetEdits } from "./component-style-set.js";
-import { storedDefaults } from "./conditional-defaults.js";
 import { forwardRouteInvariants, refusedRoutes } from "./forward-route-invariants.js";
 import { iconDomainInvariants } from "./icon-domain-invariants.js";
+import { storedDefaults } from "./prop-rules.js";
 import { rootLayerInvariants } from "./root-layer-invariants.js";
 import { Token } from "./Token.js";
 import { z } from "zod";
@@ -1199,7 +1199,7 @@ const Preview = defineSubEntity({
 		});
 	}
 });
-const DEFAULT_CONDITIONS_DESCRIPTION = "Defaults that hold only under a condition on this component's other props, laid over `defaultProps` the way a style rule is over the unconditional one: a list of entries, each identified by its condition. `{ \"when\": { \"modal\": false }, \"props\": { \"includeScrim\": false } }` defaults `includeScrim` to `false` while `modal` is `false`, and to its `defaultProps` value otherwise. When several entries hold, the later one wins on the prop it sets. Both sides name the component's own variant, string, number or boolean props, a prop set here is never part of a condition, and a value the call site passes always wins. Authored as `conditionalDefault(fallback, [{ when, value }])` inside `.defaultProps`.";
+const DEFAULT_CONDITIONS_DESCRIPTION = "Defaults that hold only under a condition on this component's other props, laid over `defaultProps` the way a style rule is over the unconditional one: a list of entries, each identified by its condition. `{ \"when\": { \"modal\": false }, \"props\": { \"includeScrim\": false } }` defaults `includeScrim` to `false` while `modal` is `false`, and to its `defaultProps` value otherwise. When several entries hold, the later one wins on the prop it sets. Both sides name the component's own variant, string, number or boolean props, a prop set here is never part of a condition, and a value the call site passes always wins. Authored as a rule in `.defaultProps([{ when, props }])`.";
 const defaultConditionShapeError = "a conditional default is `{ \"when\": { \"<prop>\": <value> }, \"props\": { \"<prop>\": <value> } }`: both name this component's own variant, string, number or boolean props (not `as`), `when` at one of their values.";
 const defaultConditionBase = z.object({
 	when: z.record(z.string(), z.unknown()),
@@ -1811,9 +1811,9 @@ const componentFields = z.strictObject({
 	anatomy: AnatomyNode.optional().describe("The tree of what this component renders, keyed by node. Each node names what it renders (a layer, for anything a style rule reaches) and lists its `children`; the node keyed `root` is the top. A one-layer component may omit it. Anatomy read from an extension's own source file replaces the inherited tree; edits to a borrowed render merge into its tree."),
 	defaultProps: Style.optional(),
 	/** The defaults that hold only under a condition on the component's other props — see
-	*  `conditionalDefault`. */
+	*  `.defaultProps([{ when, props }])`. */
 	defaultPropsWhen: orList(DefaultCondition).optional().describe(DEFAULT_CONDITIONS_DESCRIPTION),
-	/** What the tile and the matrix render with — see `preview({ defaultProps, when })`. Read off
+	/** What the tile and the matrix render with — see `.preview({ defaultProps })`. Read off
 	*  `.preview()` at build, and written per cell from the matrix. */
 	preview: orList(Preview).optional().describe(PREVIEW_DESCRIPTION),
 	/**
@@ -2989,7 +2989,7 @@ function componentRef(path) {
 		assertComponentSourceInput(delta);
 		const extended = base.extend({
 			...delta,
-			...storedDefaults(delta)
+			...delta.defaultProps === void 0 ? {} : storedDefaults(delta.defaultProps)
 		});
 		Object.defineProperty(extended, "render", {
 			enumerable: false,

package/dist/entities/system/LinkedSystem.js

@@ -352,7 +352,7 @@ const LinkedSystemDefinition = defineEntity({
 			input: unlinkInput,
 			readOnly: false,
 			label: "Unlink from",
-			description: "Stop following a linked system's entities, in `link`'s shape or everything when `data` is omitted. The rows the declaration minted go with it, and so do the linked rows that point at them, since left linked they would bring them back; nothing of yours moves. A row of yours pointing at one of theirs refuses this — `copy` what is used first, or `break` with `keep: true`. `unlink-plan` names everything that goes.",
+			description: "Stop following a linked system's entities, in `link`'s shape or everything when `data` is omitted. The rows the declaration minted go with it, and so do the linked rows that point at them, since left linked they would bring them back, and the pin's `options` entries left with no row to adjust; nothing of yours moves. A row of yours pointing at one of theirs refuses this — `copy` what is used first, or `break` with `keep: true`. `unlink-plan` names everything that goes.",
 			scope: "item",
 			approval: "reference-change",
 			title: (entity) => `Unlink from ${entity}`,
@@ -374,7 +374,7 @@ const LinkedSystemDefinition = defineEntity({
 			input: unlinkInput,
 			readOnly: true,
 			label: "Plan an unlink",
-			description: "What `unlink` with the same input removes — the minted rows the narrower declaration no longer reaches, with the linked rows taken along because they point at them named in `cascade` — and why the config would refuse it, a collision it would leave among them. Writes nothing.",
+			description: "What `unlink` with the same input removes — the minted rows the narrower declaration no longer reaches, with the linked rows taken along because they point at them named in `cascade`, and the `options` entries of the pin that go with them in `dropped` — and why the config would refuse it, a collision it would leave among them. Writes nothing.",
 			scope: "item",
 			title: (entity) => `Plan unlinking from ${entity}`,
 			example: pinExample,

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

@@ -96,10 +96,20 @@ function planCopy({ config, input }) {
 	const taking = [];
 	const folders = [];
 	const reused = [];
+	/** Folders this config draws through another pin, which a copied ref binds to as it does a reused row. */
+	const heldFolders = /* @__PURE__ */ new Set();
 	/** Every `kind:path` `take` has answered, whichever way, so the walk below visits each once. */
 	const seen = /* @__PURE__ */ new Set();
 	const declared = declarationOf(config, slug);
 	const folder = (kind, path) => {
+		const through = config.groupBorrowedFrom({
+			kind,
+			groupPath: path
+		});
+		if (through !== void 0 && through !== slug && input.onConflict !== "replace") {
+			heldFolders.add(`${kind}:${path}`);
+			return;
+		}
 		if (!folders.some((f) => f.kind === kind && f.path === path)) folders.push({
 			kind,
 			path
@@ -258,6 +268,32 @@ function planCopy({ config, input }) {
 		}
 	}
 	if (taking.length === 0 && wholesale) rejectData(`"${slug}" has nothing to copy.`);
+	/**
+	* The files of a sibling a copied render imports, when the sibling itself isn't copied — this config
+	* holds that path already, through another pin or as its own. The render imports the source's
+	* module, not whatever answers the path here, so that module lands without the component, and so do
+	* the files of the siblings it imports in turn. A copied sibling brings its own files.
+	*/
+	const siblingFiles = ({ sibling, component }) => {
+		const key = `files:${sibling}`;
+		if (seen.has(key)) return;
+		seen.add(key);
+		if (taking.some((row) => row.kind === "component" && row.at === sibling)) return;
+		for (const path of renderSourceFiles({
+			source,
+			path: sibling
+		})) takeFile({
+			path,
+			component
+		});
+		for (const next of renderImportedComponents({
+			source,
+			path: sibling
+		})) siblingFiles({
+			sibling: next,
+			component
+		});
+	};
 	/** Take what `body` points at by ref. */
 	const follow = (body) => {
 		for (const target of collectRefs(body)) {
@@ -318,12 +354,18 @@ function planCopy({ config, input }) {
 			for (const sibling of renderImportedComponents({
 				source,
 				path: row.theirs
-			})) take({
-				kind: "component",
-				theirs: sibling,
-				at: sibling,
-				named: false
-			});
+			})) {
+				take({
+					kind: "component",
+					theirs: sibling,
+					at: sibling,
+					named: false
+				});
+				siblingFiles({
+					sibling,
+					component: row.theirs
+				});
+			}
 			for (const path of renderSourceFiles({
 				source,
 				path: row.theirs
@@ -336,11 +378,17 @@ function planCopy({ config, input }) {
 	const arriving = new Set([
 		...taking.map((row) => `${row.kind}:${row.at}`),
 		...reused.map((row) => `${row.kind}:${row.path}`),
+		...heldFolders,
 		...folders.map((folder) => `${folder.kind}:${folder.path}`)
 	]);
 	const patches = [];
 	for (const { kind, path } of folders) {
-		const meta = ownMeta(source.groups(kind).find((group) => group.path === path)?.meta ?? {});
+		const meta = ownMeta(config.copyOfGroup({
+			slug,
+			kind,
+			path,
+			alongside: arriving
+		}) ?? {});
 		const pointed = config.groupBorrowedFrom({
 			kind,
 			groupPath: path

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

@@ -3,7 +3,7 @@ import { RegisteredComponentHandles, RegisteredGroupPaths, RegisteredModifiers,
 import { Authored } from "../../framework/authoring.js";
 import { StyleValue } from "./style-bag.js";
 import { ComponentSourceInput } from "./component-source-fields.js";
-import { ConditionalDefault } from "./conditional-defaults.js";
+import { PropsOrRules } from "./prop-rules.js";
 import { VariantValues } from "./Component.js";
 import { AllHTMLAttributes, ComponentPropsWithRef, ComponentType, ElementType, JSX, ReactElement, ReactNode, Ref } from "react";
 
@@ -664,11 +664,17 @@ type ForwardedPropsOf<L extends LayerMap, F extends string> = [NonRootForward<L,
 type DefaultsOf<P extends PropMap> = Partial<DeclaredProps<P>> & {
   [key: string]: unknown;
 };
-/** {@link DefaultsOf} as `.defaultProps` takes it: a declared prop other than `as` may also default
- *  through {@link conditionalDefault}. */
-type AuthoredDefaultsOf<P extends PropMap> = { [K in keyof DeclaredProps<P>]?: K extends 'as' ? DeclaredProps<P>[K] : DeclaredProps<P>[K] | ConditionalDefault<DeclaredProps<P>[K]> } & {
-  [key: string]: unknown;
-};
+/** {@link DefaultsOf} as `.defaultProps` and `.extend({ defaultProps })` take it: the defaults, or
+ *  a list of rules giving them under conditions. */
+type AuthoredDefaultsOf<P extends PropMap> = PropsOrRules<DefaultsOf<P>>;
+/** The defaults a component applies with nothing set: a record as given, or its unconditional
+ *  rules folded together. */
+type UnconditionalDefaults<D> = D extends readonly (infer Rule)[] ? [UnconditionalProps<Rule>] extends [never] ? Record<never, never> : UnionToIntersection<UnconditionalProps<Rule>> : D;
+type UnconditionalProps<Rule> = Rule extends {
+  when: Readonly<Record<string, unknown>>;
+} ? never : Rule extends {
+  props: infer Props;
+} ? Props : never;
 /**
  * `T` without the keys in `K` — `Omit` that leaves an index signature alone.
  *
@@ -785,10 +791,11 @@ F extends string = never, /** The states `.states()` declared — what the rende
    * `const`, so an `as` keeps its literal type: without it `{ as: 'input' }` widens to `string` and
    * there's no tag left to resolve the element's props against.
    *
-   * A default that depends on another prop is a `conditionalDefault`:
-   * `includeScrim: conditionalDefault(true, [{ when: { modal: false }, value: false }])`.
+   * Defaults that depend on other props are rules, the way style rules are: a rule without `when`
+   * holds always, and a later rule wins on the props it sets.
+   * `[{ props: { includeScrim: true } }, { when: { modal: false }, props: { includeScrim: false } }]`.
    */
-  defaultProps<const D2 extends AuthoredDefaultsOf<P>>(defaults: D2): ComponentBuilder<L, P, E, D2, F, S>;
+  defaultProps<const D2 extends AuthoredDefaultsOf<P>>(defaults: D2): ComponentBuilder<L, P, E, UnconditionalDefaults<D2>, F, S>;
   /**
    * The layers whose element props this component ALSO exposes, keyed by layer.
    *
@@ -832,34 +839,23 @@ F extends string = never, /** The states `.states()` declared — what the rende
    */
   renderCanvas<E2 extends E = E>(fn: (args: Without<RenderArgs<L, P, S>, keyof E2> & E2) => unknown): ComponentBuilder<L, P, E, D, F, S>;
   /**
-   * What a preview of this component STARTS from — the props a single tile is rendered with.
+   * What a preview tile renders with. `defaultProps` takes what `.defaultProps` does: a record, or a
+   * list of rules.
    *
-   * Only `defaultProps`, because the grid itself is derived: every axis a matrix could sweep is
-   * already declared in `styles`, as the conditions the rules apply under, and the modifier columns
-   * are the `_hover`/`_active` blocks those rules contain. An authored matrix restated all of it and
-   * could disagree with it — a variant added to `styles` and forgotten in the matrix simply never
-   * appeared. See `previewMatrix`.
+   * Only content, because the grid itself is derived: every axis a matrix could sweep is declared in
+   * `styles`, as the conditions the rules apply under, and the modifier columns are the
+   * `_hover`/`_active` blocks those rules contain. See `previewMatrix`.
+   *
+   * A rule with `when` gives the content a cell needs at one point on an axis:
+   * `{ when: { type: 'image' }, props: { src } }` gives the image kind a photo. A condition naming a
+   * prop no rule styles makes that prop an axis too, with the value named.
    */
   preview(spec: {
-    defaultProps?: DefaultsOf<P>;
-    /**
-     * Preview props that hold only under a condition — the same `when` grammar a style rule uses.
-     * The grid is derived from the styles; what it cannot derive is the CONTENT a cell needs at a
-     * given point on an axis: `{ when: { type: 'image' }, props: { src } }` gives the image kind a
-     * photo, `{ when: { invalid: true }, props: { selected: true } }` shows the invalid state checked.
-     * A condition naming a prop no rule styles makes that prop an axis too, with the value named —
-     * so a preview can say a boolean is worth a column the way a rule would.
-     */
-    when?: readonly PreviewCondition<P>[];
+    defaultProps?: PropsOrRules<DefaultsOf<P>>;
   }): ComponentBuilder<L, P, E, D, F, S>;
   toStored(): Record<string, unknown>;
   assignPath(path: string): void;
 }
-/** Preview props that hold under a condition on the cell's props — see `preview({ when })`. */
-interface PreviewCondition<P extends PropMap = PropMap> {
-  readonly when: Partial<Record<keyof P & string, unknown>>;
-  readonly props: DefaultsOf<P>;
-}
 /** A component under authorship, with its declarations forgotten — what a registry holds. */
 type AuthoredComponent = ComponentBuilder<LayerMap, PropMap, unknown, unknown>;
 /**
@@ -901,4 +897,4 @@ interface DefineComponent {
 declare function definePropsFirst<const P extends PropMap<LayerPath>>(props: P & NoInfer<{ [K in keyof P]: Exact<P[K], AuthoredProp<LayerPath>> }>): ComponentBuilder<LayerMap, P>;
 declare const defineComponent: DefineComponent;
 //#endregion
-export { AsInput, AuthoredComponent, AuthoredDefaultsOf, AuthoredProp, ComponentBuilder, ComponentPropsOf, GlyphComponent, GlyphValue, LayerElement, LayerMap, LinkedHandle, ModifierProps, PhantomCallProps, PhantomReadProps, PropCondition, PropDecl, PropMap, RegisteredMembers, RenderArgs, SlotCodeForm, SlotDecl, StateMap, StyleProps, StyleRuleInput, defineComponent };
+export { AsInput, AuthoredComponent, AuthoredDefaultsOf, AuthoredProp, ComponentBuilder, ComponentPropsOf, GlyphComponent, GlyphValue, LayerElement, LayerMap, LinkedHandle, ModifierProps, PhantomCallProps, PhantomReadProps, PropCondition, PropDecl, PropMap, RegisteredMembers, RenderArgs, SlotCodeForm, SlotDecl, StateMap, StyleProps, StyleRuleInput, UnconditionalDefaults, defineComponent };

package/dist/entities/system/defineComponent.js

@@ -1,8 +1,7 @@
-import { canonicalCondition, isRef, kindOf, memberRef, pathOf } from "../../framework/utils/refs.js";
+import { isRef, kindOf, memberRef, pathOf } from "../../framework/utils/refs.js";
 import { glyphIdentityOf, glyphPackageRefOf, isComponentType } from "./glyph-identity.js";
-import "../../framework/preview-store.js";
 import { assertComponentSourceInput } from "./component-source-fields.js";
-import { isConditionalDefault, storedDefaults } from "./conditional-defaults.js";
+import { keyedPropRules, storedDefaults } from "./prop-rules.js";
 import { Component, layerRef, storedStyleRules } from "./Component.js";
 //#region src/entities/system/defineComponent.ts
 function build(body) {
@@ -25,10 +24,7 @@ function build(body) {
 		metadata: (meta) => next(meta),
 		render: () => handle,
 		renderCanvas: () => handle,
-		preview: (spec) => {
-			if (spec?.defaultProps === void 0 && !spec?.when?.length) return handle;
-			return next({ preview: spec });
-		},
+		preview: (spec) => spec?.defaultProps === void 0 ? handle : next({ preview: spec.defaultProps }),
 		toStored: () => toStored(body),
 		assignPath(path) {
 			handle.path = path;
@@ -146,7 +142,6 @@ function storableElement(value) {
 */
 function storableValue(value) {
 	if (value === null) return null;
-	if (isConditionalDefault(value)) throw new Error("`conditionalDefault` is a default, so it goes in `.defaultProps` or `.extend({ defaultProps })`. A preview conditions its props with `.preview({ when: [{ when, props }] })`.");
 	const type = typeof value;
 	if (type === "string" || type === "number" || type === "boolean") return value;
 	if (isComponentType(value)) return storableComponentRef(value);
@@ -376,21 +371,19 @@ function toStored(body) {
 	assertComponentSourceInput(body);
 	const stored = { ...body };
 	if (body.preview !== void 0) {
-		const authored = body.preview;
 		const keyed = {};
-		const defaults = authored.defaultProps !== void 0 ? storableProps(authored.defaultProps) : void 0;
-		if (defaults !== void 0) keyed["*"] = {
-			when: null,
-			props: defaults
-		};
-		for (const { when, props } of authored.when ?? []) keyed[canonicalCondition(when)] = {
-			when,
-			props: storableProps(props) ?? {}
-		};
+		for (const [key, { when, props }] of keyedPropRules(body.preview)) {
+			const storable = storableProps(props);
+			if (storable === void 0 && when === null) continue;
+			keyed[key] = {
+				when,
+				props: storable ?? {}
+			};
+		}
 		if (Object.keys(keyed).length === 0) delete stored.preview;
 		else stored.preview = keyed;
 	}
-	Object.assign(stored, storedDefaults(body));
+	if (body.defaultProps !== void 0) Object.assign(stored, storedDefaults(body.defaultProps));
 	if (body.props && typeof body.props === "object") {
 		const props = {};
 		for (const [name, decl] of Object.entries(body.props)) props[name] = storedProp(decl, body.layers);

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

@@ -64,6 +64,9 @@ interface UnlinkPlan {
   /** Linked rows unlinked with the named ones because they point at them: left linked, they would
    *  bring the named rows back on the next derive. */
   readonly cascade: readonly EntityAddress[];
+  /** The pin's `options` entries that go with the unlink: one on a path that stops deriving, and one
+   *  on a path drawn from elsewhere that names a row that goes. Neither has a row to adjust. */
+  readonly dropped: readonly EntityAddress[];
   /** Why the config would refuse. `undefined` when it would go through. */
   readonly blocked?: string;
   /** The paths the unlink would leave two linked systems offering as different entities, when that

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

@@ -329,6 +329,7 @@ function planUnlink({ config, input }) {
 		declared: void 0,
 		removed: [],
 		cascade: [],
+		dropped: [],
 		patches: []
 	};
 	let declared;
@@ -397,16 +398,39 @@ function planUnlink({ config, input }) {
 		}
 		if (input.data !== void 0 && removed.length === 0) blocked = stillReached({ slug });
 	}
+	const dropped = after ? deadDirectives({
+		config,
+		after,
+		slug,
+		removed
+	}) : [];
+	if (dropped.length > 0) {
+		const update = patches[patches.length - 1];
+		if (dropped.length === config.sourceDirectives(slug).length) update.data.options = null;
+		else for (const { accessor, path } of dropped) update.data[`options.${accessor}.${path}`] = null;
+	}
 	return {
 		declared,
 		removed,
 		cascade,
+		dropped: dropped.map(({ kind, path }) => ({
+			kind,
+			path
+		})),
 		...blocked === void 0 ? {} : { blocked },
 		...refused.collisions ? { collisions: refused.collisions } : {},
 		patches
 	};
 }
 /**
+* The pin's directives an unlink leaves with nothing to do: on a path that no longer derives through
+* the pin, and either on a row the unlink retires or naming one.
+*/
+function deadDirectives({ config, after, slug, removed }) {
+	const gone = new Set(removed.map(({ kind, path }) => `${kind}:${path}`));
+	return config.sourceDirectives(slug).filter((directive) => directive.kind !== void 0 && after.resolve(directive.kind, directive.path)?.borrowedFrom !== slug && (gone.has(`${directive.kind}:${directive.path}`) || collectRefs(config.sourceOverlay(slug, directive.kind, directive.path)).some((target) => gone.has(target))));
+}
+/**
 * Leave paths of a linked system out, with a `!` entry each in the pin's `link`. Stronger than
 * `unlink`: nothing derives there however the link reaches it, a linked token naming it included,
 * and the linked tokens' overrides under an excluded modifier are left out of the build. `link` with

package/dist/entities/system/prop-rules.d.ts

@@ -0,0 +1,10 @@
+//#region src/entities/system/prop-rules.d.ts
+/** One rule: `props` hold while every prop `when` names has its value, or always with no `when`. */
+interface PropRule<Props = Record<string, unknown>> {
+  readonly when?: Readonly<Record<string, unknown>> | null;
+  readonly props: Props;
+}
+/** The props given unconditionally, or a list of rules. */
+type PropsOrRules<Props> = Props | readonly PropRule<Props>[];
+//#endregion
+export { PropRule, PropsOrRules };

package/dist/entities/system/prop-rules.js

@@ -0,0 +1,42 @@
+import { canonicalCondition } from "../../framework/utils/refs.js";
+//#region src/entities/system/prop-rules.ts
+/**
+* Rules keyed by condition, `*` for the unconditional one. Two rules with the same condition are
+* one: their props merge, the later value winning, and the merged rule takes the later one's place.
+*/
+function keyedPropRules(authored) {
+	const rules = Array.isArray(authored) ? authored : [{ props: authored }];
+	const keyed = /* @__PURE__ */ new Map();
+	for (const rule of rules) {
+		const key = canonicalCondition(rule.when);
+		const prior = keyed.get(key);
+		keyed.delete(key);
+		keyed.set(key, {
+			when: key === "*" ? null : { ...rule.when },
+			props: {
+				...prior?.props,
+				...rule.props
+			}
+		});
+	}
+	return keyed;
+}
+/**
+* Authored defaults as stored: the unconditional rule in `defaultProps`, each other in
+* `defaultPropsWhen`. A plain record stores as it was written, with no `defaultPropsWhen`.
+*/
+function storedDefaults(authored) {
+	if (!Array.isArray(authored)) return { defaultProps: { ...authored } };
+	const keyed = keyedPropRules(authored);
+	const defaultPropsWhen = {};
+	for (const [key, { when, props }] of keyed) if (when) defaultPropsWhen[key] = {
+		when,
+		props
+	};
+	return {
+		defaultProps: keyed.get("*")?.props ?? {},
+		...Object.keys(defaultPropsWhen).length > 0 ? { defaultPropsWhen } : {}
+	};
+}
+//#endregion
+export { keyedPropRules, storedDefaults };

package/dist/framework/Config.d.ts

@@ -1942,6 +1942,42 @@ declare class Config {
     alongside?: ReadonlySet<string>;
     extend?: Record<string, unknown>;
   }): Record<string, unknown> | undefined;
+  /**
+   * One of a source's folders' meta as a copy stores it — its refs spelled from here as
+   * {@link copyOf} spells a body's. The meta as the source holds it names its own pins by their slugs
+   * there: the Bridge's `icons` folder names `package:@yahoo/uds-icons@yos`, and stored as it was that
+   * names a pin this config doesn't have. `undefined` when the source has no folder there.
+   */
+  copyOfGroup({
+    slug,
+    kind,
+    path,
+    alongside
+  }: {
+    slug: string;
+    kind: string;
+    path: string; /** `kind:path` targets landing as this config's own in the same edit. */
+    alongside?: ReadonlySet<string>;
+  }): Record<string, unknown> | undefined;
+  /**
+   * `body` with each ref routed through another system's pin (`@yos-v3~yos`) respelled through this
+   * config's own pin to the same system, where that pin's source holds the target too: a copy then
+   * names what this config reaches directly rather than keeping the pin it came through referenced.
+   * Bare when this config already holds the target as a pointer through that pin.
+   */
+  private throughDirectPins;
+  /**
+   * The pin of this config's own that reaches the system a routed source ends at — `yahoo-os` for
+   * `yos-v3~yos`, when this config pins directly what `yos-v3` pins as `yos`. Matched on the pin
+   * kind's `sourceOrigin`, so the two pins may name different versions. `undefined` for a source of
+   * one hop, or one whose system no pin here reaches.
+   *
+   * The two pins match when they agree on every origin field both set, and share at least one. Not on
+   * the whole key: a pin by path is stamped with its sibling's id when it's pushed, so the Bridge's
+   * `yos` reads `configPath` and `systemId` where this config's pin to the same system names only the
+   * id — and a `configPath` is relative to the config holding it, so it can't be compared across two.
+   */
+  private directRoute;
   /**
    * Whether a copied row no longer matches what its source offers at the path it was copied from.
    *
@@ -2255,6 +2291,16 @@ declare class Config {
    * that reaches derivation — a deleted extension whose source reached the row — says what it did.
    */
   private assertDerivedDropsUnreferenced;
+  /**
+   * Whether every directive of `pin` that names `target` sits on a path that no longer derives through
+   * it — retired by this derivation, or drawn from another source already. Such a directive lays its
+   * value over no row, so it goes with the link rather than being stranded by it: a pin's own
+   * `options` never refuse removing its link. A directive on a row the pin still mints does, since
+   * that row would be left pointing at nothing.
+   *
+   * `false` when `pin` is not a source, or names `target` somewhere other than a directive.
+   */
+  private directivesGoWith;
   /**
    * This config with a row for every entity it inherits — the build's output. A pin patch runs this
    * inside {@link apply}; a source attaching runs it through the session.
@@ -2513,6 +2559,8 @@ declare class Config {
    */
   sourceIdentityKey(kind: string, path: string): string | undefined;
   private sourceKey;
+  /** Each of a pin's `of` fields as it reads, `''` where unset, in the kind's order. */
+  private sourceFields;
   /**
    * Where what this config shows at `path` originates: the system it was first authored in, followed
    * through however many pins it took to get here. `undefined` for a row this config authored itself.