@yahoo/uds-create-config 5.59.0 → 5.59.2

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

@@ -1004,4 +1004,4 @@ interface ComponentClass extends Omit<typeof ComponentEntity, 'ref' | 'item'> {
   instance: typeof instanceAt;
 }
 //#endregion
-export { AuthoredPropBody, Component, ComponentBody, ComponentClass, ComponentCreateInput, ComponentElementBody, ComponentItemInput, ComponentPropBody, ComponentReference, ComponentStyleBody, ContractStyleRules, ElementVisibility, ElementVisibilityInput, ElementVisibilitySchema, ExtendedComponentRef, ProjectedVisibility, PropShapeSchema, SLOT_CODE_FORMS, VariantValueBody, VariantValues, blankComponentBody, canonicalWhen, forwardedNames, layerRef, ownValues, ownsItsValues, valueRef };
+export { AnatomyNodeClass, AuthoredPropBody, Component, ComponentBody, ComponentClass, ComponentCreateInput, ComponentElementBody, ComponentItemInput, ComponentPropBody, ComponentReference, ComponentStyleBody, ContractStyleRules, ElementVisibility, ElementVisibilityInput, ElementVisibilitySchema, ExtendedComponentRef, ForwardClass, LayerClass, ProjectedVisibility, PropClass, PropShapeSchema, SLOT_CODE_FORMS, VariantValueBody, VariantValues, blankComponentBody, canonicalWhen, forwardedNames, layerRef, ownValues, ownsItsValues, valueRef };

package/dist/entities/system/LinkedSystem.js

@@ -303,8 +303,8 @@ const LinkedSystemDefinition = defineEntity({
 		* Draw entities from a linked system: the pin's `link` declaration grows to cover them and the
 		* build mints a pointer row per entity, in this one op. A row of this config's own at a covered
 		* path is deleted so theirs shows through; a row held through another pin becomes an extension
-		* through this one when `onLinked` is `'take'`. `link-plan` says what that replaces before anything
-		* is written.
+		* through this one when `onLinked` is `'take'`, and the other pin's `options` entry there goes with
+		* it. `link-plan` says what that replaces before anything is written.
 		*/
 		link: {
 			input: linkInput,
@@ -332,7 +332,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), 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, 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/Motion.d.ts

@@ -33,7 +33,7 @@ declare const inlineJsMotion: z.ZodObject<{
 /** The fields of a JS preset that `motion.create` reads as props, in schema order. The emitter
  *  reads this rather than restating the schema, so a field added here reaches every emitted preset. */
 declare const jsMotionPropFields: readonly string[];
-declare const Motion: EntityClass<z.ZodDiscriminatedUnion<[z.ZodObject<{
+declare const MotionEntity: EntityClass<z.ZodDiscriminatedUnion<[z.ZodObject<{
   type: z.ZodLiteral<"react-native-reanimated">;
   value: z.ZodUnion<readonly [z.ZodObject<{
     transitionProperty: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
@@ -1003,6 +1003,7 @@ declare const Motion: EntityClass<z.ZodDiscriminatedUnion<[z.ZodObject<{
     }, z.core.$strip>;
   };
 }, Record<never, never>, false, Record<never, never>, Record<never, never>>;
-type MotionClass = Named<typeof Motion>;
+interface MotionClass extends Named<typeof MotionEntity> {}
+declare const Motion: MotionClass;
 //#endregion
 export { Motion, MotionClass, inlineJsMotion, jsMotionPropFields };

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

@@ -1,7 +1,9 @@
 import { Ref as Ref$1 } from "../../framework/utils/refs.js";
 import { RegisteredComponentHandles, RegisteredGroupPaths, RegisteredModifiers, RegisteredPaths, RegisteredStyleProps } from "../../framework/registered.js";
 import { Authored } from "../../framework/authoring.js";
+import { KindRef } from "../../framework/defineEntity.js";
 import { StyleValue } from "./style-bag.js";
+import { StylePropertyClass } from "./StyleProperty.js";
 import { ComponentSourceInput } from "./component-source-fields.js";
 import { PropsOrRules } from "./prop-rules.js";
 import { VariantValues } from "./Component.js";
@@ -725,6 +727,30 @@ type RenderArgs<L extends LayerMap, P extends PropMap, S extends StateMap = Reco
 } & ([keyof S] extends [never] ? Record<never, never> : {
   readonly states: StatesHelper<S, L>;
 }) & DeclaredProps<P, L, unknown, 'render'> & Record<string, unknown>;
+/** A prop map's entries that are the style property of their own name: `bg: StyleProperty.ref('bg')`. */
+type StyleRefs<K extends string> = { readonly [Q in K]: KindRef<StylePropertyClass, 'style-property', Q> };
+/** The same entries in their declared form: `bg: { type: 'styleProperty', value: StyleProperty.ref('bg') }`. */
+type StyleRefProps<K extends string> = { readonly [Q in K]: {
+  readonly type: 'styleProperty';
+  readonly value: KindRef<StylePropertyClass, 'style-property', Q>;
+} };
+/** The keys of `P` whose entry is exactly the one `M` gives that key. */
+type MatchingKeys<P, M> = { [K in keyof P]: K extends keyof M ? [P[K]] extends [M[K]] ? [M[K]] extends [P[K]] ? K : never : never : never }[keyof P];
+type StyleRefKeys<P> = MatchingKeys<P, StyleRefs<keyof P & string>>;
+type StyleRefPropKeys<P> = MatchingKeys<P, StyleRefProps<keyof P & string>>;
+/** `T`, or nothing to intersect when `K` is empty. */
+type WhenAny<K, T> = [K] extends [never] ? unknown : T;
+/**
+ * `P` with its entries that are the style property of their own name gathered into a
+ * {@link StyleRefs} and a {@link StyleRefProps}. It's the same type, but a declaration writes it as a
+ * list of key names rather than a `KindRef` per entry. A component's type holds the prop map of every
+ * layer it reaches, so a system's Box, with an entry for each style property, is otherwise restated in
+ * full at every layer that renders it, until the declaration is too long to write (TS7056).
+ *
+ * The rest of `P` is a mapped type with `as` rather than an `Omit`, which a declaration would write
+ * with `P` in full as its type argument.
+ */
+type CompactProps<P extends PropMap> = [StyleRefKeys<P> | StyleRefPropKeys<P>] extends [never] ? P : { [K in keyof P as K extends StyleRefKeys<P> | StyleRefPropKeys<P> ? never : K]: P[K] } & WhenAny<StyleRefKeys<P>, StyleRefs<StyleRefKeys<P> & string>> & WhenAny<StyleRefPropKeys<P>, StyleRefProps<StyleRefPropKeys<P> & string>>;
 interface ComponentBuilder<L extends LayerMap, P extends PropMap,
 /** Props the RENDER takes that the config doesn't describe — React handlers, mostly (`onPress`).
  *  They're part of the component's surface but not of its data, which is why they're declared at
@@ -767,7 +793,7 @@ F extends string = never, /** The states `.states()` declared — what the rende
    * provide. The callback and its `layer`/`bind` helpers are gone — they only ever split a path string
    * that the parameter's own type now checks.
    */
-  props<const P2 extends PropMap<LayerPath<L>>>(props: P2 & NoInfer<{ [K in keyof P2]: Exact<P2[K], AuthoredProp<LayerPath<L>>> }>): ComponentBuilder<L, P2, E, D, F, S>;
+  props<const P2 extends PropMap<LayerPath<L>>>(props: P2 & NoInfer<{ [K in keyof P2]: Exact<P2[K], AuthoredProp<LayerPath<L>>> }>): ComponentBuilder<L, CompactProps<P2>, E, D, F, S>;
   /**
    * What the render knows that a style rule keys on — the field has a value, the image loaded, the
    * indicator is sliding: `{ filled: { type: 'boolean' } }`, `{ phase: { type: 'variant', value:
@@ -873,9 +899,10 @@ type AuthoredComponent = ComponentBuilder<LayerMap, PropMap, unknown, unknown>;
  *   forward through it (HStack's `root: Box`) then offers what the linked Box takes.
  *
  * Everything else (the render's extras, the defaults, the forwards, the states) is read off the
- * handle's type rather than restated, so the two can't drift.
+ * handle's type rather than restated, so the two can't drift. The laid-over props are compacted
+ * again, since laying them over spells the source's {@link StyleRefs} out entry by entry.
  */
-type LinkedHandle<Handle, Props extends PropMap = Record<never, never>, Layers extends Record<string, LayerElement> = Record<never, never>> = Handle extends ComponentBuilder<infer L extends LayerMap, infer P extends PropMap, infer E, infer D, infer F extends string, infer S extends StateMap> ? ComponentBuilder<Without<L, keyof Layers> & Layers extends infer Swapped extends LayerMap ? Swapped : L, Without<P, keyof Props> & Props, E, D, F, S> : Handle;
+type LinkedHandle<Handle, Props extends PropMap = Record<never, never>, Layers extends Record<string, LayerElement> = Record<never, never>> = Handle extends ComponentBuilder<infer L extends LayerMap, infer P extends PropMap, infer E, infer D, infer F extends string, infer S extends StateMap> ? ComponentBuilder<Without<L, keyof Layers> & Layers extends infer Swapped extends LayerMap ? Swapped : L, CompactProps<Without<P, keyof Props> & Props>, E, D, F, S> : Handle;
 interface DefineComponent {
   /** The one-layer form: the element IS the component. */
   <const El extends LayerElement>(element: El): ComponentBuilder<{
@@ -894,7 +921,7 @@ interface DefineComponent {
  * The type argument is explicit so the builder does not INFER `P2` from an already-exact value: it
  * would then apply the guard over its own output, which nothing satisfies.
  */
-declare function definePropsFirst<const P extends PropMap<LayerPath>>(props: P & NoInfer<{ [K in keyof P]: Exact<P[K], AuthoredProp<LayerPath>> }>): ComponentBuilder<LayerMap, P>;
+declare function definePropsFirst<const P extends PropMap<LayerPath>>(props: P & NoInfer<{ [K in keyof P]: Exact<P[K], AuthoredProp<LayerPath>> }>): ComponentBuilder<LayerMap, CompactProps<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, UnconditionalDefaults, 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, StyleRefProps, StyleRefs, StyleRuleInput, UnconditionalDefaults, defineComponent };

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

@@ -22,6 +22,13 @@ interface LinkedElsewhere extends EntityAddress {
   /** The slug of the pin it comes through. */
   readonly from: string;
 }
+/** An entry in another pin's `options` that a take leaves applying to nothing, and removes. */
+interface DroppedDirective extends EntityAddress {
+  /** The slug of the pin whose entry it was. */
+  readonly from: string;
+  /** The accessor the entry sits under in that pin's `options`. */
+  readonly accessor: string;
+}
 /** One row a link mints. `named` when a path the call named covers it; otherwise it comes along
  *  because something linked points at it. */
 interface LinkArrival extends EntityAddress {
@@ -40,6 +47,10 @@ interface LinkPlan {
   readonly linked: readonly LinkedElsewhere[];
   /** Rows held through another pin, turned into extensions through this one. */
   readonly extended: readonly EntityAddress[];
+  /** 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. */
+  readonly dropped: readonly DroppedDirective[];
   /** Members already here from the source's own origin, left alone and kept out of the declaration. */
   readonly shared: readonly EntityAddress[];
   /** Paths another pin offers that a `hybrid` link reaches as a different entity. The other pin's
@@ -193,4 +204,4 @@ declare function sourceRowStates({
   readonly slug: string;
 }): SourceRowState[];
 //#endregion
-export { BreakOutcome, BreakPlan, BreakPlanInput, BreakPlanRow, BreakReach, LinkArrival, LinkPaths, LinkPlan, LinkPlanInput, LinkedElsewhere, OnLinked, SourceRowState, UnlinkPlan, UnlinkPlanInput, planBreak, planLink, planUnlink, sourceRowStates };
+export { BreakOutcome, BreakPlan, BreakPlanInput, BreakPlanRow, BreakReach, DroppedDirective, LinkArrival, LinkPaths, LinkPlan, LinkPlanInput, LinkedElsewhere, OnLinked, SourceRowState, UnlinkPlan, UnlinkPlanInput, planBreak, planLink, planUnlink, sourceRowStates };

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

@@ -1,7 +1,7 @@
 import { collectRefs, isMintedRow, ref, sourceOf, splitRef } from "../../framework/utils/refs.js";
 import { isConfigRejection, rejectData } from "../../framework/rejection.js";
 import { blockedBy } from "../../framework/plan.js";
-import { excludedCondition } from "../../framework/source-integrity.js";
+import { danglingDirectives, excludedCondition } from "../../framework/source-integrity.js";
 import { sameOrigin } from "../../framework/Config.js";
 import { PIN_KIND, covers, declarationOf, entriesFor, excludePaths, excludes, includePaths, narrowDeclaration } from "./link-declaration.js";
 import { planCopy, sourceEntries } from "./copy-plan.js";
@@ -238,11 +238,20 @@ function planLink({ config, input }) {
 		}
 		declared = Object.keys(next).length === 0 ? current : next;
 	}
-	const patches = [
+	const planned = [
 		...takes,
 		...declares,
 		...shadows
 	];
+	const { dropped, patches: drops } = takes.length > 0 ? directivesTakenFrom({
+		config,
+		slug,
+		patches: planned
+	}) : {
+		dropped: [],
+		patches: []
+	};
+	const patches = [...planned, ...drops];
 	return {
 		declared,
 		...outcome({
@@ -255,10 +264,74 @@ function planLink({ config, input }) {
 		addresses,
 		linked,
 		extended,
+		dropped,
 		shared,
 		patches
 	};
 }
+/**
+* The other pins' `options` entries a take leaves applying to nothing, and the pin edits that remove
+* them.
+*
+* An entry adjusts the rows its pin derives. A take writes this config's own row at the path, one that
+* follows `slug`, so the other pin's entry stays in its `options` reading as though it still applied,
+* and the build refuses it ({@link danglingDirectives}). Read off the config the take leaves, so a
+* folder whose members all moved counts the way the build will count it, and only what the take
+* itself left behind: an entry that already applied to nothing is the build's to report, not this
+* take's to remove.
+*
+* Nothing when the take is refused; `outcome` says why.
+*/
+function directivesTakenFrom({ config, slug, patches }) {
+	let after;
+	try {
+		after = config.applyAll(patches).withDerivedRows();
+	} catch (error) {
+		if (!isConfigRejection(error)) throw error;
+		return {
+			dropped: [],
+			patches: []
+		};
+	}
+	const key = (at) => `${at.slug}\u0000${at.accessor}\u0000${at.path}`;
+	const already = new Set(danglingDirectives(config).map(key));
+	const dropped = [];
+	for (const at of danglingDirectives(after)) {
+		if (at.missing !== "row" || at.heldBy !== slug || already.has(key(at))) continue;
+		dropped.push({
+			kind: config.accessors()[at.accessor]?.kind ?? at.accessor,
+			path: at.path,
+			from: at.slug,
+			accessor: at.accessor
+		});
+	}
+	const edits = [];
+	for (const pin of new Set(dropped.map((at) => at.from))) {
+		const options = config.storedBody("linked-system", pin).options ?? {};
+		const data = {};
+		let emptied = 0;
+		for (const [accessor, entries] of Object.entries(options)) {
+			const going = dropped.filter((at) => at.from === pin && at.accessor === accessor).map((at) => at.path);
+			if (going.length === 0) continue;
+			if (Object.keys(entries ?? {}).filter((path) => !going.includes(path)).length > 0) {
+				for (const path of going) data[`options.${accessor}.${path}`] = null;
+				continue;
+			}
+			data[`options.${accessor}`] = null;
+			emptied += 1;
+		}
+		edits.push({
+			kind: PIN_KIND,
+			operation: "update",
+			path: pin,
+			data: emptied === Object.keys(options).length ? { options: null } : data
+		});
+	}
+	return {
+		dropped,
+		patches: edits
+	};
+}
 /** What a plan reports of a refusal: its message, and the collisions when that's what it names. */
 function refusal(error) {
 	const collisions = error.issues.flatMap((issue) => issue.collisions ?? []);

package/dist/framework/Config.js

@@ -5138,6 +5138,40 @@ var Config = class Config {
 		const folders = [];
 		/** Folders this pass leaves as they stand — already held, over rows it still claims. */
 		const standing = /* @__PURE__ */ new Set();
+		const taken = [];
+		for (const kind of this.ownedKinds()) for (const [path, stored] of this.state.snapshot.slice(kind).items) {
+			const body = stored.toJSON();
+			if (!isExtendedRef(body) || isMintedRow(body)) continue;
+			if (pathOf(body) !== path) continue;
+			const slug = sourceOf(body);
+			if (slug !== void 0) taken.push({
+				kind,
+				path,
+				slug
+			});
+		}
+		/** Every folder a pin has a member under this pass, claimed or taken, as `slug kind path`. */
+		const occupied = /* @__PURE__ */ new Set();
+		const occupy = (slug, kind, path) => {
+			const segments = path.split("/");
+			for (let depth = 1; depth < segments.length; depth++) occupied.add(`${slug}\u0000${kind}\u0000${segments.slice(0, depth).join("/")}`);
+		};
+		for (const [target, slug] of claimedFrom) occupy(slug, kindOf(target), pathOf(target));
+		for (const { kind, path, slug } of taken) occupy(slug, kind, path);
+		/**
+		* Whether a folder already here stays as it is. One this config authored does, and so does one
+		* minted through a pin that still has a member under it. One minted through a pin that has none
+		* left there goes to the pin its members follow now: after a take, a `colorMode` whose modes all
+		* follow Yahoo OS kept pointing at the Bridge's, its fields read from a system none of it follows.
+		*/
+		const stands = (kind, path) => {
+			const held = this.state.snapshot.group(kind, path)?.toJSON();
+			if (held === void 0) return false;
+			if (!isMintedRow(held)) return true;
+			const pointer = held.ref;
+			const through = isRef(pointer) ? sourceOf(pointer) : void 0;
+			return through !== void 0 && occupied.has(`${through}\u0000${kind}\u0000${path}`);
+		};
 		for (const [slug, paths] of offeredBy) {
 			const source = this.sourceFor(slug);
 			if (!source) continue;
@@ -5149,7 +5183,7 @@ var Config = class Config {
 				for (const group of source.groups(kind)) {
 					const prefix = `${group.path}/`;
 					if (!under.some((path) => path.startsWith(prefix))) continue;
-					if (this.state.snapshot.group(kind, group.path)) {
+					if (stands(kind, group.path)) {
 						standing.add(`group:${kind}:${group.path}`);
 						continue;
 					}
@@ -5162,6 +5196,27 @@ var Config = class Config {
 				}
 			}
 		}
+		const derivedFolders = new Set(folders.map(({ kind, path }) => `${kind}:${path}`));
+		for (const { kind, path, slug } of taken) {
+			const source = this.sourceFor(slug);
+			if (!source || !this.entityOf(kind)) continue;
+			for (const group of source.groups(kind)) {
+				if (!path.startsWith(`${group.path}/`)) continue;
+				const target = `${kind}:${group.path}`;
+				if (derivedFolders.has(target) || standing.has(`group:${target}`)) continue;
+				if (stands(kind, group.path)) {
+					standing.add(`group:${target}`);
+					continue;
+				}
+				derivedFolders.add(target);
+				folders.push({
+					kind,
+					path: group.path,
+					slug
+				});
+				claimedFrom.set(target, slug);
+			}
+		}
 		for (const [target, slug] of claimedFrom) {
 			if (folders.some(({ kind, path }) => `${kind}:${path}` === target)) continue;
 			changes.push(derivedItemChange(kindOf(target), pathOf(target), ref(kindOf(target), pathOf(target), slug).__ref, overlayBody({
@@ -5324,7 +5379,22 @@ var Config = class Config {
 		const source = this.sourceFor(slug);
 		if (!source) return [];
 		const members = /* @__PURE__ */ new Set();
-		const walked = /* @__PURE__ */ new Set();
+		/**
+		* Every entity or folder visited, and whether a linked row reached it.
+		*
+		* A taken row is visited twice — first as an authored row, then as one its pin adopts — and only a
+		* linked visit lands the items a body points at. Remembering only THAT a target was visited let the
+		* unlinked pass claim the style properties and token folders it found, so the linked pass skipped
+		* them and a mode their tokens vary under never got a row. A target reached unlinked is visited
+		* again when a linked row reaches it; one reached linked is done.
+		*/
+		const reached = /* @__PURE__ */ new Map();
+		const reaching = (target, linked) => {
+			const prior = reached.get(target);
+			if (prior === true || prior === false && !linked) return false;
+			reached.set(target, linked);
+			return true;
+		};
 		/**
 		* A style bag's KEYS name style properties, and a borrowed bag's name the SOURCE's.
 		*
@@ -5342,11 +5412,11 @@ var Config = class Config {
 			if (!sites) return;
 			for (const { bag } of sites(body)) for (const prop of Object.keys(bag)) {
 				const target = `style-property:${prop}`;
-				if (members.has(target)) continue;
 				const local = this.storedBody("style-property", prop);
 				if (local && !isMintedRow(local)) continue;
 				const declared = source.resolve("style-property", prop);
 				if (!declared) continue;
+				if (!reaching(target, linked)) continue;
 				members.add(target);
 				visitEntity("style-property", declared.toJSON(), true, linked);
 			}
@@ -5377,19 +5447,19 @@ var Config = class Config {
 				const target = `${kind}:${path}`;
 				const item = source.resolve(kind, path);
 				if (item) {
-					if (!linked || members.has(target)) continue;
+					if (!linked || !reaching(target, true)) continue;
 					members.add(target);
 					visitEntity(kind, item.toJSON(), true, true);
 					continue;
 				}
-				if (walked.has(target)) continue;
-				walked.add(target);
+				if (!reaching(target, linked)) continue;
 				if (!source.groups(kind).some((node) => node.path === path)) continue;
 				const prefix = `${path}/`;
 				for (const member of source.list(kind)) {
 					if (!member.path.startsWith(prefix)) continue;
-					members.add(`${kind}:${member.path}`);
-					visitEntity(kind, member.toJSON(), true, linked);
+					const at = `${kind}:${member.path}`;
+					members.add(at);
+					if (reaching(at, linked)) visitEntity(kind, member.toJSON(), true, linked);
 				}
 			}
 		};

package/dist/framework/defineEntity.d.ts

@@ -60,6 +60,9 @@ type Read<F extends FieldsSchema, C extends ComputedFields> = Entity & z.infer<F
 type KindRef<E, K extends string, P extends string> = ExtendableRef<Partial<CreateInputOf<E>>> & {
   readonly __ref: `${K}:${P}`;
 };
+/** What an entity's `item` hands back: a body `E` creates from, or the shorthand for its primary
+ *  field. */
+type ItemInput<E> = CreateInputOf<E> | string | number | Ref;
 /** The body `E` creates an item from, read off its `create`. Open when `E` is no entity, as for a
  *  `ref` called detached from one. */
 type CreateInputOf<E> = E extends {
@@ -94,7 +97,7 @@ type OpInputsOf<S extends UserSchemas> = { readonly [V in keyof S as S[V] extend
 } ? {
   readonly input: I;
 } : never };
-type EntityClass<F extends FieldsSchema, G extends FieldsSchema,
+interface EntityClass<F extends FieldsSchema, G extends FieldsSchema,
 /** The kind as a literal, so `ref` can narrow to the paths a consumer's config declares. Defaults
  *  to `string`, which is what every 2-argument use of this type keeps getting. */
 K extends string = string,
@@ -112,7 +115,7 @@ Single extends boolean = false,
 GC extends GroupComputedFields = Record<never, never>,
 /** The kind's `groupInputs` as written, so `group()` takes each input key at its handler's declared
  *  type. Defaults to none. */
-GI extends GroupInputs = Record<never, never>> = Omit<RefSchema, 'extend'> & {
+GI extends GroupInputs = Record<never, never>> extends Omit<RefSchema, 'extend'> {
   readonly kind: K;
   /** Whether the kind has exactly one item — see `singleton` on `defineEntity`. A property rather than
    *  only a type parameter so a conditional type can tell the two apart: `get`'s signature differs by
@@ -136,7 +139,7 @@ GI extends GroupInputs = Record<never, never>> = Omit<RefSchema, 'extend'> & {
   readonly ref: Single extends true ? <E, P extends PathOf<K>>(this: E, path?: P) => KindRef<E, K, P> : <E, P extends PathOf<K>>(this: E, path: P) => KindRef<E, K, P>;
   /** Typed constructor for one item — a full body, or a bare value/ref that's shorthand
    *  for the kind's primary field. Returned as-is; `register` normalizes the shorthand. */
-  item(def: CreateInput<F> | string | number | Ref): CreateInput<F> | string | number | Ref;
+  item(def: CreateInput<F> | string | number | Ref): ItemInput<this>;
   /** Typed constructor for a group node — branded so `register` routes it to the group
    *  store; input is the group fields' create body, plus any registration-time input the kind
    *  declares (`groupInputs`), which is consumed here and never stored. */
@@ -148,7 +151,8 @@ GI extends GroupInputs = Record<never, never>> = Omit<RefSchema, 'extend'> & {
   get(config: Config, ...pathOrRef: Single extends true ? [pathOrRef?: string | Ref] : [pathOrRef: string | Ref]): Read<F, C> | undefined;
   /** Every item of this kind, typed off the fields — `Component.list(config)`. Total by default;
    *  `{ retired: false }` is the offer surface's read (see `Config.list`). */
-  list(config: Config, opts?: ListOptions): Read<F, C>[]; /** This kind's items as a folder/file tree — `Component.tree(config)` (the sidebar). */
+  list(config: Config, opts?: ListOptions): Read<F, C>[];
+  /** This kind's items as a folder/file tree — `Component.tree(config)` (the sidebar). */
   tree(config: Config): TreeNode[];
   /** This kind's group nodes and their metadata — `Package.groups(config)`, the packages a system
    *  depends on. The enumeration `list`/`tree` can't give: both derive from item paths, so a group
@@ -162,11 +166,13 @@ GI extends GroupInputs = Record<never, never>> = Omit<RefSchema, 'extend'> & {
   dependents(config: Config, path: string, opts?: TraverseOptions): string[];
   /** Create an item of this kind — `Component.create(config, 'Button', {…})`. Typed body; returns
    *  the config for chaining. (The typed twin of `config.apply({kind, operation:'create', …})`.) */
-  create<C extends Config>(config: C, path: string, data: CreateInput<F>): C; /** Update an item — a partial patch merged over the current value. */
+  create<C extends Config>(config: C, path: string, data: CreateInput<F>): C;
+  /** Update an item — a partial patch merged over the current value. */
   update<C extends Config>(config: C, path: string, data: Partial<z.infer<F>>): C;
   /** Delete an item, with whatever cannot exist without it ({@link EntityKind.structuralBody}). Refused
    *  while anything else still references it. */
-  delete<C extends Config>(config: C, path: string): C; /** Rename an item's path — references cascade. */
+  delete<C extends Config>(config: C, path: string): C;
+  /** Rename an item's path — references cascade. */
   rename<C extends Config>(config: C, path: string, to: string): C;
   /**
    * Make a variant of this kind — same kind, different rules, stating only the differences.
@@ -206,7 +212,7 @@ GI extends GroupInputs = Record<never, never>> = Omit<RefSchema, 'extend'> & {
      *  Config that never imported it. See {@link EntityKind.entityName}. */
     entityName?: string;
   }): EntityClass<ExtendedFields<F, F2>, ExtendedFields<G, G2>, K, [S2] extends [never] ? S : OpInputsOf<S2>, C, Single, GC, GI>;
-};
+}
 declare function defineEntity<F extends FieldsSchema, G extends FieldsSchema = z.ZodObject<Record<never, never>>, K extends string = string, const S extends UserSchemas = Record<never, never>, const C extends ComputedFields = Record<never, never>, Single extends boolean = false, const GC extends GroupComputedFields = Record<never, never>, const GI extends GroupInputs = Record<never, never>>(spec: {
   kind: K;
   /** The kind's fields, or a factory over the write's context (`config`, `body`) when a field's
@@ -401,4 +407,4 @@ type OpInput<E extends {
   input: infer I extends z.ZodTypeAny;
 } ? z.input<I> : never;
 //#endregion
-export { EntityClass, GroupComputedInput, ItemOf, KindRef, OpInput, defineEntity };
+export { EntityClass, GroupComputedInput, ItemInput, ItemOf, KindRef, OpInput, defineEntity };

package/dist/framework/source-integrity.d.ts

@@ -239,12 +239,17 @@ interface DanglingDirective {
   /** The accessor as written — this config may have no kind under it. */
   accessor: string;
   path: string;
-  /** `accessor` when no kind is registered under that name, `path` when the source has no such entity. */
-  missing: 'accessor' | 'path';
+  /**
+   * `accessor` when no kind is registered under that name, `path` when the source has no such entity,
+   * `row` when the source has it but the row here isn't one the pin derives.
+   */
+  missing: 'accessor' | 'path' | 'row';
+  /** With `row`: the pin the row there follows instead, absent when it is this config's own. */
+  heldBy?: string;
 }
 /**
- * Every directive aimed at nothing — an accessor this config has no kind for, or a path the source
- * does not have.
+ * Every directive aimed at nothing — an accessor this config has no kind for, a path the source
+ * does not have, or a path where the row here isn't one the pin derives.
  *
  * The one mistake the other checks structurally cannot see. Each of them answers for a path it is
  * already holding, so it asks "does the declaration mention this one" — and a name nobody has is
@@ -254,6 +259,10 @@ interface DanglingDirective {
  * Also what notices the source dropping a path. A directive written against an entity a later version
  * removed keeps parsing and keeps doing nothing, which is the same failure the declared verb exists to
  * catch one level down.
+ *
+ * And what notices a path leaving the pin. A row taken through another pin (`linked-system/link` with
+ * `onLinked: 'take'`), or authored here, stands where the pin's row stood, and the entry the pin
+ * still carries for it applies to nothing.
  */
 declare function danglingDirectives(config: Config): DanglingDirective[];
 /** A borrowed token whose condition is missing or has a different category here. */

package/dist/framework/source-integrity.js

@@ -489,8 +489,25 @@ function unadoptedDirectives(config) {
 	return found;
 }
 /**
-* Every directive aimed at nothing — an accessor this config has no kind for, or a path the source
-* does not have.
+* Who holds the row at a path a directive names, when it isn't the directive's own pin: the slug of
+* the pin the row follows instead, `null` for a row of this config's own, `undefined` when the pin's
+* row is there or nothing is.
+*
+* A pin's `options` lay over the rows its declaration derives, and nothing else. A row taken through
+* another pin, or authored here, stands at the path in its place, so the entry applies to nothing.
+*/
+function heldElsewhere(config, { slug, kind, path }) {
+	const item = config.storedBody(kind, path);
+	const group = item === void 0 ? config.groupMeta(kind, path) : void 0;
+	if (item === void 0 && group === void 0) return void 0;
+	const pointer = item ?? group?.ref;
+	const through = isRef(pointer) ? sourceOf(pointer) : void 0;
+	if (through === slug) return void 0;
+	return through ?? null;
+}
+/**
+* Every directive aimed at nothing — an accessor this config has no kind for, a path the source
+* does not have, or a path where the row here isn't one the pin derives.
 *
 * The one mistake the other checks structurally cannot see. Each of them answers for a path it is
 * already holding, so it asks "does the declaration mention this one" — and a name nobody has is
@@ -500,6 +517,10 @@ function unadoptedDirectives(config) {
 * Also what notices the source dropping a path. A directive written against an entity a later version
 * removed keeps parsing and keeps doing nothing, which is the same failure the declared verb exists to
 * catch one level down.
+*
+* And what notices a path leaving the pin. A row taken through another pin (`linked-system/link` with
+* `onLinked: 'take'`), or authored here, stands where the pin's row stood, and the entry the pin
+* still carries for it applies to nothing.
 */
 function danglingDirectives(config) {
 	const found = [];
@@ -516,7 +537,23 @@ function danglingDirectives(config) {
 				});
 				continue;
 			}
-			if (source.resolve(kind, path) || source.members(kind, path).length > 0) continue;
+			if (source.resolve(kind, path) || source.members(kind, path).length > 0) {
+				if (config.sourceOverlay(slug, kind, path)?.hidden === true) continue;
+				const heldBy = heldElsewhere(config, {
+					slug,
+					kind,
+					path
+				});
+				if (heldBy === void 0) continue;
+				found.push({
+					slug,
+					accessor,
+					path,
+					missing: "row",
+					...heldBy === null ? {} : { heldBy }
+				});
+				continue;
+			}
 			found.push({
 				slug,
 				accessor,