@yahoo/uds-create-config 5.51.0 → 5.52.0

package/dist/configs/system.js

@@ -28,6 +28,7 @@ import { linkedDirMigration } from "../migrations/20261020182408_linked_dir.js";
 import { lintSettingsMigration } from "../migrations/20261020183330_lint_settings.js";
 import { directLayerCompositesMigration } from "../migrations/20261022124223_direct_layer_composites.js";
 import { cssContentScriptsMigration } from "../migrations/20261022152120_css_content_scripts.js";
+import { linkTypeMigration } from "../migrations/20261022184639_link_type.js";
 import { CanvasRole } from "../entities/system/CanvasRole.js";
 import { GlobalStyle } from "../entities/system/GlobalStyle.js";
 import { Guidance } from "../entities/system/Guidance.js";
@@ -189,5 +190,6 @@ if (!registeredSchemaMigrations().has(20261020183330)) {
 	registerSchemaMigrations(directLayerCompositesMigration);
 }
 if (!registeredSchemaMigrations().has(20261022152120)) registerSchemaMigrations(cssContentScriptsMigration);
+if (!registeredSchemaMigrations().has(20261022184639)) registerSchemaMigrations(linkTypeMigration);
 //#endregion
 export { System };

package/dist/entities/native/NativeModifier.js

@@ -20,6 +20,7 @@ const NATIVE_ACTIVATIONS = [
 const NativeModifier = defineEntity({
 	kind: "modifier",
 	entityName: "NativeModifier",
+	answeredHere: true,
 	fields: z.object({
 		type: z.enum(NATIVE_ACTIVATIONS),
 		value: z.union([z.string(), z.number()])

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

@@ -109,6 +109,10 @@ declare const LinkedSystemDefinition: EntityClass<z.ZodObject<{
   systemId: z.ZodOptional<z.ZodString>;
   modules: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
   name: z.ZodOptional<z.ZodString>;
+  type: z.ZodOptional<z.ZodEnum<{
+    linked: "linked";
+    hybrid: "hybrid";
+  }>>;
   version: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>, z.ZodObject<Record<never, never>, z.core.$strip>, "linked-system", {
   readonly link: {

package/dist/entities/system/LinkedSystem.js

@@ -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), and members left alone because they are already here from the same origin. 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), 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,
@@ -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. 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 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,
@@ -739,6 +739,22 @@ const LinkedSystemDefinition = defineEntity({
 		/** Display only, never identity: what to call this source in the UI. Defaults to the slug. */
 		name: z.string().optional().describe("Display only. Defaults to the slug."),
 		/**
+		* How this source joins the system. `linked`, the default, brings in everything a linked entity
+		* references as a row from this link, and refuses a path another link offers as a different
+		* entity. `hybrid` brings in only what no other link offers: where another link offers a path, that
+		* link's row stands and what this one brings uses it, while a component it renders stays this
+		* source's own.
+		*
+		* A product moving from one system to another adds the new one as `hybrid`: taking Yahoo OS's
+		* `Popover` over the v3 Bridge keeps the product's tokens from the Bridge, and the Popover renders
+		* Yahoo OS's own Button. Once the old link is gone, the new one can become `linked`.
+		*
+		* OPEN: motion presets and composites don't follow it yet. A taken component plays this system's
+		* motion preset of the name it uses, and a composite is the source's in a style rule and this
+		* system's as a prop.
+		*/
+		type: z.enum(["linked", "hybrid"]).optional().describe("How this source joins the system: `linked` (the default) brings in everything its entities reference and refuses a path another link offers differently; `hybrid` brings in only what no other link offers and uses this system's tokens wherever it has one of the same name."),
+		/**
 		* The exact published version every ref through this link resolves against.
 		*
 		* For a `configPath` link this is **observed rather than pinned**: push records what the sibling was
@@ -808,6 +824,7 @@ displayName: ({ member, path }) => typeof member.name === "string" && member.nam
 		accessor: accessor ?? kind,
 		path
 	}),
+	sourceType: (body) => body.type === "hybrid" ? "hybrid" : "linked",
 	bulkExcludes: ({ body, kind, accessor, path }) => excludes({
 		declared: body.link,
 		accessor: accessor ?? kind,

package/dist/entities/system/Modifier.js

@@ -55,6 +55,7 @@ const Modifier = defineEntity({
 	}),
 	groupFields: modifierGroupFields,
 	uniqueLeaves: true,
+	answeredHere: true,
 	invariants: (config) => modifierInvariants(config)
 });
 /** A path's last segment. */

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

@@ -1,6 +1,6 @@
 import { EntityAddress } from "../../framework/plan.js";
 import { LinkDeclaration } from "./LinkedSystem.js";
-import { Config, Patch, TreeNode } from "../../framework/Config.js";
+import { Config, Patch, SettledSource, SourceCollision, TreeNode } from "../../framework/Config.js";
 
 //#region src/entities/system/link-plan.d.ts
 /** What one op names, keyed by accessor the way the pin's `link` is: every entry of the kind, or the
@@ -42,6 +42,14 @@ interface LinkPlan {
   readonly extended: readonly EntityAddress[];
   /** 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
+   *  row stays at the path, and what the link brings is drawn with it. */
+  readonly settled: readonly SettledSource[];
+  /** Why the config would refuse the link. `undefined` when it would go through. */
+  readonly blocked?: string;
+  /** The paths the link would leave two linked systems offering as different entities, when that is
+   *  why it's refused. */
+  readonly collisions?: readonly SourceCollision[];
   readonly patches: readonly Patch[];
 }
 interface UnlinkPlanInput {
@@ -58,6 +66,9 @@ interface UnlinkPlan {
   readonly cascade: 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
+   *  is why it's refused. */
+  readonly collisions?: readonly SourceCollision[];
   readonly patches: readonly Patch[];
 }
 interface BreakPlanInput {
@@ -109,15 +120,16 @@ interface SourceRowState {
   readonly sharedOrigin?: string;
 }
 /**
- * Link paths of a source: the declaration that mints them, then the edits that let them show through
+ * Link paths of a source: the declaration that mints them, and the edits that let them show through
  * where this config already holds something.
  *
- * The declaration goes first. A row of this config's own that other rows point at can only be deleted
- * once the declaration covers the path, since the config refuses a delete that leaves a referrer
- * dangling. A row held through another pin is not deleted — that pin's declaration would mint it
- * again, and declaring one path on two pins is a collision nothing derives. With `onLinked: 'take'` it
- * becomes an extension through this pin: a row of this config's own that shadows the other pin's and
- * follows this source. With `'keep'` it stays with the other pin and out of the declaration. A member
+ * A row held through another pin is not deleted — that pin's declaration would mint it again, and
+ * declaring one path on two pins is a collision nothing derives. With `onLinked: 'take'` it becomes an
+ * extension through this pin: a row of this config's own that shadows the other pin's and follows
+ * this source. The extensions are written before the declaration, so it never finds the path declared
+ * twice. With `'keep'` it stays with the other pin and out of the declaration. A row of this config's
+ * own that other rows point at is deleted after the declaration, since the config refuses a delete
+ * that leaves a referrer dangling until the declaration covers the path. A member
  * already here from the source's own origin is left alone and kept out of the declaration, so a
  * folder that holds one is declared by its other members.
  */

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

@@ -1,4 +1,4 @@
-import { rejectData } from "../../framework/rejection.js";
+import { isConfigRejection, rejectData } from "../../framework/rejection.js";
 import { collectRefs, isMintedRow, ref, sourceOf, splitRef } from "../../framework/utils/refs.js";
 import { blockedBy } from "../../framework/plan.js";
 import { excludedCondition } from "../../framework/source-integrity.js";
@@ -58,15 +58,16 @@ function declaredElsewhere({ config, slug, kind, path }) {
 	}
 }
 /**
-* Link paths of a source: the declaration that mints them, then the edits that let them show through
+* Link paths of a source: the declaration that mints them, and the edits that let them show through
 * where this config already holds something.
 *
-* The declaration goes first. A row of this config's own that other rows point at can only be deleted
-* once the declaration covers the path, since the config refuses a delete that leaves a referrer
-* dangling. A row held through another pin is not deleted — that pin's declaration would mint it
-* again, and declaring one path on two pins is a collision nothing derives. With `onLinked: 'take'` it
-* becomes an extension through this pin: a row of this config's own that shadows the other pin's and
-* follows this source. With `'keep'` it stays with the other pin and out of the declaration. A member
+* A row held through another pin is not deleted — that pin's declaration would mint it again, and
+* declaring one path on two pins is a collision nothing derives. With `onLinked: 'take'` it becomes an
+* extension through this pin: a row of this config's own that shadows the other pin's and follows
+* this source. The extensions are written before the declaration, so it never finds the path declared
+* twice. With `'keep'` it stays with the other pin and out of the declaration. A row of this config's
+* own that other rows point at is deleted after the declaration, since the config refuses a delete
+* that leaves a referrer dangling until the declaration covers the path. A member
 * already here from the source's own origin is left alone and kept out of the declaration, so a
 * folder that holds one is declared by its other members.
 */
@@ -85,6 +86,9 @@ function planLink({ config, input }) {
 	const linked = [];
 	const extended = [];
 	const shared = [];
+	/** Rows held through another pin, written as extensions through this one. */
+	const takes = [];
+	/** Rows of this config's own that make way for the source's. */
 	const shadows = [];
 	/** Per accessor, what the declaration gains: the kind whole, or paths. */
 	const gains = /* @__PURE__ */ new Map();
@@ -144,7 +148,7 @@ function planLink({ config, input }) {
 			kind,
 			path
 		});
-		shadows.push({
+		takes.push({
 			kind,
 			operation: minted ? "create" : "replace",
 			path,
@@ -233,10 +237,14 @@ function planLink({ config, input }) {
 		}
 		declared = Object.keys(next).length === 0 ? current : next;
 	}
-	const patches = [...declares, ...shadows];
+	const patches = [
+		...takes,
+		...declares,
+		...shadows
+	];
 	return {
 		declared,
-		arriving: arrivals({
+		...outcome({
 			config,
 			slug,
 			patches,
@@ -250,12 +258,27 @@ function planLink({ config, input }) {
 		patches
 	};
 }
+/** 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 ?? []);
+	return {
+		blocked: error.message,
+		...collisions.length > 0 ? { collisions } : {}
+	};
+}
+const addressed = (rows) => new Set(rows.map(({ kind, path }) => `${kind}:${path}`));
 /**
-* The rows a link mints, read by running its patches on a scratch config and deriving: what is held
-* through the pin afterwards and was not before. Nothing when the op would refuse; the op says why.
+* What a link leaves, read by running its patches on a scratch config and deriving: the rows held
+* through the pin afterwards that were not before, and the paths settled afterwards that were not
+* before. When the config would refuse the patches, a collision they would leave among them,
+* nothing arrives and `blocked` says why.
 */
-function arrivals({ config, slug, patches, named }) {
-	if (patches.length === 0) return [];
+function outcome({ config, slug, patches, named }) {
+	const nothing = {
+		arriving: [],
+		settled: []
+	};
+	if (patches.length === 0) return nothing;
 	const through = (at) => {
 		const held = /* @__PURE__ */ new Set();
 		for (const kind of at.borrowableKinds(slug)) for (const item of at.list(kind)) if (item.borrowedFrom === slug) held.add(`${kind}:${item.path}`);
@@ -264,8 +287,12 @@ function arrivals({ config, slug, patches, named }) {
 	let after;
 	try {
 		after = config.applyAll(patches).withDerivedRows();
-	} catch {
-		return [];
+	} catch (error) {
+		if (!isConfigRejection(error)) return nothing;
+		return {
+			...nothing,
+			...refusal(error)
+		};
 	}
 	const before = through(config);
 	const arriving = [];
@@ -283,7 +310,11 @@ function arrivals({ config, slug, patches, named }) {
 			})
 		});
 	}
-	return arriving;
+	const settledBefore = addressed(config.settledSources());
+	return {
+		arriving,
+		settled: after.settledSources().filter(({ kind, path }) => !settledBefore.has(`${kind}:${path}`))
+	};
 }
 /**
 * Stop drawing paths of a source. The declaration narrows, or clears, and the rows it minted retire
@@ -345,10 +376,17 @@ function planUnlink({ config, input }) {
 			data: { link: declared === void 0 ? null : declared }
 		});
 	}
-	let blocked = blockedBy(() => config.applyAll(patches));
+	let after;
+	let refused = {};
+	try {
+		after = config.applyAll(patches);
+	} catch (error) {
+		if (!isConfigRejection(error)) throw error;
+		refused = refusal(error);
+	}
+	let { blocked } = refused;
 	const removed = [];
-	if (blocked === void 0) {
-		const after = config.applyAll(patches);
+	if (after) {
 		for (const kind of config.borrowableKinds(slug)) for (const item of config.list(kind)) {
 			if (item.borrowedFrom !== slug) continue;
 			if (after.resolve(kind, item.path)?.borrowedFrom === slug) continue;
@@ -364,6 +402,7 @@ function planUnlink({ config, input }) {
 		removed,
 		cascade,
 		...blocked === void 0 ? {} : { blocked },
+		...refused.collisions ? { collisions: refused.collisions } : {},
 		patches
 	};
 }

package/dist/framework/Config.d.ts

@@ -9,7 +9,7 @@ import { RefGraph, TraverseOptions } from "./ref-graph.js";
 import { FieldsSchema } from "./utils/field-schema.js";
 import { SubEntityClass } from "./defineSubEntity.js";
 import { LocalOverlay, SourceAnswer, SourceOverlay, SourceResolver, SourceState } from "./sources.js";
-import { EntityKind, LayerKey } from "./registry.js";
+import { EntityKind, LayerKey, SourceType } from "./registry.js";
 import { AuthoredEntry } from "./utils/group.js";
 import { EntityClass } from "./defineEntity.js";
 import { BreakPlan, LinkPlan, SourceRowState, UnlinkPlan } from "../entities/system/link-plan.js";
@@ -73,7 +73,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 = 20261022152120;
+declare const SERIALIZED_CONFIG_VERSION = 20261022184639;
 interface SerializedConfig {
   /** See {@link SERIALIZED_CONFIG_VERSION}. Always written; a stored artifact may lack it. */
   readonly version: number;
@@ -567,6 +567,26 @@ interface ConfigState {
 type ListOptions = {
   readonly retired?: boolean;
 };
+/** A path offered as different entities with nothing able to keep it: two or more pins, or a
+ *  `linked` pin and a row of this config's own ({@link Config.collidingSources}). */
+interface SourceCollision {
+  readonly kind: string;
+  readonly path: string;
+  /** The slugs of the pins offering it. */
+  readonly slugs: readonly string[];
+  /** This config's own row at the path is one of the entities. */
+  readonly local?: true;
+}
+/** A path a `hybrid` pin reaches as a different entity from the one another pin offers there: the
+ *  other pin's row stands at the path ({@link Config.settledSources}). */
+interface SettledSource {
+  readonly kind: string;
+  readonly path: string;
+  /** The slug of the pin whose row stands at the path. */
+  readonly kept: string;
+  /** The slugs of the pins that reach a different entity there. */
+  readonly over: readonly string[];
+}
 declare class Config {
   #private;
   /** All of this config's state. `protected`, not a `#private` field, so a derived config can be
@@ -1093,8 +1113,8 @@ declare class Config {
   /**
    * Whether patches on kinds that name no source can change the rows a derive mints between `before`
    * and `after`: they wrote a pin (an edit to a minted row lands in its pin's `options`), or a row
-   * they touched points at a source, changes which source-qualified refs it holds, or appears or
-   * vanishes at a path a source offers. An authored style bag's keys are this config's own
+   * they touched points at a source, changes which source-qualified refs it holds, appears or vanishes
+   * at a path a source offers, or is a row of this config's own that a linked pin reaches. An authored style bag's keys are this config's own
    * properties, so they don't count.
    *
    * Asked of the patches' own paths rather than of every row, so a batch pays per patch.
@@ -2216,11 +2236,21 @@ declare class Config {
    * and its sources are fixed.
    */
   private computeSourceClosure;
+  /**
+   * A refusal for a pin patch that would leave paths two sources offer as different entities, which
+   * derive neither and fail the build. Named here, when the patch is made, with the two ways out.
+   */
+  private assertNoNewCollisions;
+  /** {@link assertNoNewCollisions} against the collisions a derivation already found. */
+  private assertNoNewCollisionsIn;
   /**
    * A refusal for a patch whose derive pass would retire a minted row that something authored here
    * still points at. A minted row has no body of its own, so once it goes the referrer dangles;
    * copying what is used, or breaking the link with `keep`, is how the value stays.
    *
+   * A row retired because two sources now offer its path as different entities is refused as that
+   * collision instead, since resolving the collision is what keeps the row.
+   *
    * `action` names what is refused, after "Cannot": a pin patch removes the link, and any other patch
    * that reaches derivation — a deleted extension whose source reached the row — says what it did.
    */
@@ -2273,6 +2303,8 @@ declare class Config {
    * A session derives every value it advances to, so without the mark the same edit would pay for two
    * derive passes: this one and the session's. The mark covers this instance only, and any later
    * write is a new config, so each edit still gets exactly one pass, as it did from the session alone.
+   *
+   * `before` is the config the edit was made on, when the edit is refused for a collision it adds.
    */
   private derivedForEdit;
   /**
@@ -2296,11 +2328,13 @@ declare class Config {
    * So neither derives, and this names them. The way out is an authored row at that path extending the
    * one you meant, which settles it as an ordinary local shadow and is reviewable in a diff.
    */
-  collidingSources(): {
-    kind: string;
-    path: string;
-    slugs: string[];
-  }[];
+  collidingSources(): SourceCollision[];
+  /**
+   * The paths a `hybrid` pin reaches as a different entity from the one another pin offers there.
+   * The other pin's row stands at the path, and what the hybrid pin brings is drawn with it
+   * ({@link drawsWithLocalRow}). Nothing here is refused, so this is what says the two differ.
+   */
+  settledSources(): readonly SettledSource[];
   /**
    * The derivation made for the snapshot this one came from, when this edit could not have changed
    * it: the same sources, no change to a pin or to which paths exist, and every row that did change
@@ -2313,8 +2347,9 @@ declare class Config {
    */
   private inheritedDerivation;
   /**
-   * Same paths in the same order, and every row that changed is authored on both sides and reaches
-   * the same sources the same way — see {@link inheritedDerivation}. Order counts because the walk
+   * Same paths in the same order, and every row that changed is authored on both sides, isn't one a
+   * linked pin reaches (`shadowed`), and reaches the same sources the same way — see
+   * {@link inheritedDerivation}. Order counts because the walk
    * visits rows in stored order and mints in the order it reaches them, and key order is meaning
    * downstream.
    */
@@ -2325,13 +2360,15 @@ declare class Config {
    */
   private derivationFacts;
   /**
-   * Which of several sources offering `target` takes it, when exactly one pin's `link` declares it and
-   * every other source only reaches it through a borrowed style bag. `undefined` leaves it a collision.
+   * Which of several sources offering `target` takes it. `undefined` leaves it a collision.
+   *
+   * A path one pin's `link` declares goes to that pin when every other source only reaches it and
+   * either holds the same entity there or is `hybrid`, which brings in only what no other pin offers.
+   * A `linked` source reaching a different entity at a declared path is a collision.
    *
-   * A reaching source counts only while its copy reads the same as the declarer's: one system built on
-   * another, pinned beside that other, reaches the same entity twice. Identity can't be traced instead,
-   * because an attached sibling arrives with what it borrowed inlined to literals. A copy that reads
-   * differently is its own entity, and picking either would hide the other.
+   * A path no pin declares goes to the first `linked` source when every `linked` source holding it
+   * reads the same entity, the `hybrid` ones yielding to them. With only `hybrid` sources it goes to
+   * the first on the same condition. Two pins declaring one path is a collision either way.
    */
   private declaringClaimant;
   /**
@@ -2340,6 +2377,29 @@ declare class Config {
    * to literals and no pointer is left to trace.
    */
   private sameEntityThrough;
+  /** Whether `other`'s entity at `kind:path` reads as `body`, spelled the way this config spells it. */
+  private sameEntityAs;
+  /** How `slug`'s source joins this config ({@link EntityKind.sourceType}): `linked` unless its pin
+   *  says otherwise. */
+  sourceTypeOf(slug: string): SourceType;
+  /**
+   * Whether a value `slug` brings is drawn with this config's row at `kind:path` rather than declared
+   * under the pin's own name: a token that something taken through `slug` names.
+   *
+   * A `hybrid` pin binds to any row here that isn't its own, authored or held through another pin, so
+   * what it brings uses this config's values. A `linked` pin binds only to a row held through another
+   * pin that is the same entity, the way {@link heldThroughAnotherPin} reads it; a different one there
+   * is a collision, and a row this config authored is its own entity under the same name.
+   */
+  drawsWithLocalRow({
+    slug,
+    kind,
+    path
+  }: {
+    slug: string;
+    kind: string;
+    path: string;
+  }): boolean;
   /**
    * Whether `slug`'s entity at `kind:path` is one this config already holds through another pin, so a
    * qualified `path@slug` would be a second spelling of the same entity.
@@ -2792,4 +2852,4 @@ declare class Config {
   protected hydrateFrom(stored: StoredConfig, options?: HydrationOptions): this;
 }
 //#endregion
-export { AppliedOp, AttachedSources, BatchReceipt, Config, CssGrammar, Edition, HydrationOptions, ListOptions, LiveConfig, Patch, RecordedSource, SERIALIZED_CONFIG_VERSION, SerializedConfig, SkippedOp, SourcesBySlug, StoredConfig, SubPatch, TreeNode };
+export { AppliedOp, AttachedSources, BatchReceipt, Config, CssGrammar, Edition, HydrationOptions, ListOptions, LiveConfig, Patch, RecordedSource, SERIALIZED_CONFIG_VERSION, SerializedConfig, SettledSource, SkippedOp, SourceCollision, SourcesBySlug, StoredConfig, SubPatch, TreeNode };