@yahoo/uds-create-config 2.20.0 → 2.21.1

package/dist/Component.d.ts

@@ -320,5 +320,11 @@ interface StylePropKeyword {
   readonly styleProp: string;
   readonly value: string;
 }
+/**
+ * HTML void elements — tags that must never receive children (React throws).
+ * Mirrors the HTML spec's void-element list; codegen's registry descriptor
+ * derives its `voidComponents` set from the same tags.
+ */
+declare const VOID_HTML_TAGS: ReadonlySet<string>;
 //#endregion
-export { Component, ComponentKind, CompositeInfo, FunctionInfo, Layer, PrimitivePropKind, PropBase, PropInfo, PropKind, ResolvedCompoundOverrides, SlotInfo, SlotValueKind, StylePropInfo, StylePropKeyword, StylePropTokenUsage, VariantInfo };
+export { Component, ComponentKind, CompositeInfo, FunctionInfo, Layer, PrimitivePropKind, PropBase, PropInfo, PropKind, ResolvedCompoundOverrides, SlotInfo, SlotValueKind, StylePropInfo, StylePropKeyword, StylePropTokenUsage, VOID_HTML_TAGS, VariantInfo };

package/dist/Component.js

@@ -285,6 +285,7 @@ var Component = class {
 				propsIndex.set(propName, info);
 			}
 			const styleUsage = collectStyleUsage(this.base, this.props, this.compoundProps, this.#resolveStylePropValueToken, this.#isStyleProp);
+			const refusesChildren = this.#rootRefusesChildren();
 			this.#derived = {
 				layers: Array.from(this.layers.values()),
 				classNames: componentClassNames(this.#prefixGetter?.() ?? "", this.name),
@@ -300,8 +301,8 @@ var Component = class {
 				stylePropTokenUsages: styleUsage.stylePropTokenUsages,
 				stylePropKeywords: styleUsage.stylePropKeywords,
 				kind: this.#deriveKind(),
-				acceptsChildren: derivesAcceptsChildren(this.layers, propsArray),
-				acceptsChildNodes: derivesAcceptsChildNodes(this.layers, propsArray),
+				acceptsChildren: !refusesChildren && derivesAcceptsChildren(this.layers, propsArray),
+				acceptsChildNodes: !refusesChildren && derivesAcceptsChildNodes(this.layers, propsArray),
 				prop(propName) {
 					return propsIndex.get(propName);
 				}
@@ -309,6 +310,36 @@ var Component = class {
 		}
 		return this.#derived;
 	}
+	/**
+	* Whether this component's root element can never hold children, making
+	* `acceptsChildren`/`acceptsChildNodes` false regardless of the structural
+	* signals those derivations read. Two authored facts qualify (UDS-3068):
+	*
+	*  - **A void root tag.** A single-primitive-root component whose effective
+	*    tag (own `defaultProps.as`, else the root layer's tag, else the
+	*    value-extends chain's) is a void HTML element (`input`, `img`, …) —
+	*    React throws if such an element receives children, so treating it as a
+	*    container injects drop-target Slots that crash every spec render of it.
+	*    Gated on the single-primitive-root shape: a composed component's render
+	*    decides where children go, so its root tag says nothing about them.
+	*
+	*  - **An explicitly dropped `children` prop.** The authored
+	*    `children: undefined` (the documented pattern for void/value elements —
+	*    Input, Image, Textarea) is detected two ways: authored configs keep the
+	*    key with an `undefined` value, which IS the drop; hydrated configs
+	*    compact the key away, so there it's absence-against-ancestry (the
+	*    merged props lack `children` while an ancestor declares it — only a
+	*    drop can produce that, since value-extension inherits the parent's
+	*    full prop surface). This catches `textarea`, which isn't HTML-void yet
+	*    still rejects element children in React.
+	*/
+	#rootRefusesChildren() {
+		if (hasSinglePrimitiveRoot(this.layers)) {
+			const tag = resolveRootHtmlTag(this, this.#componentResolver, /* @__PURE__ */ new Set());
+			if (tag !== void 0 && VOID_HTML_TAGS.has(tag)) return true;
+		}
+		return droppedInheritedChildren(this, this.#componentResolver);
+	}
 	/** Classify authoring shape: `extends` wins (value-extension is the defining
 	*  trait), then anything with multiple layers or a custom render is
 	*  `multi-layer`, else a bare single-tag `primitive`. */
@@ -880,6 +911,76 @@ function hasSinglePrimitiveRoot(layers) {
 	return false;
 }
 /**
+* HTML void elements — tags that must never receive children (React throws).
+* Mirrors the HTML spec's void-element list; codegen's registry descriptor
+* derives its `voidComponents` set from the same tags.
+*/
+const VOID_HTML_TAGS = new Set([
+	"area",
+	"base",
+	"br",
+	"col",
+	"embed",
+	"hr",
+	"img",
+	"input",
+	"link",
+	"meta",
+	"param",
+	"source",
+	"track",
+	"wbr"
+]);
+/**
+* The HTML tag a component's root element renders as: own `defaultProps.as`
+* wins (the `Box as="input"` value-extension pattern), else the root layer's
+* tag, else the value-extends chain's answer. Undefined when nothing resolves
+* (composed roots, unknown parents) — callers treat that as "no tag fact".
+* The `seen` guard stops extends cycles.
+*
+* Mirrors codegen's `resolveHtmlTag` (getReactArtifacts.ts), which reads the
+* same facts off `derived.layers[*].renders` — keep the precedence order
+* (`as` → root tag → extends chain) in sync.
+*/
+function resolveRootHtmlTag(component, resolve, seen) {
+	if (seen.has(component.name)) return void 0;
+	seen.add(component.name);
+	const as = component.defaultProps?.as;
+	if (typeof as === "string") return as;
+	const t = component.layers.get("root")?.tag;
+	if (typeof t === "string") return t;
+	if (typeof t === "object" && t !== null) {
+		const marker = t;
+		if (marker.__kind === "tag" && typeof marker.ref === "string") return marker.ref;
+	}
+	const parent = component.extendsFrom && resolve ? resolve(component.extendsFrom) : void 0;
+	return parent ? resolveRootHtmlTag(parent, resolve, seen) : void 0;
+}
+/**
+* Whether the author dropped an inherited `children` prop (`children:
+* undefined` in a value-extension — Input/Image/Textarea dropping Box's
+* slot). Two-tier detection: authored configs keep the dropped key with an
+* `undefined` value (the direct trace); hydrated configs compact the key
+* away, leaving absence-against-ancestry — this component's merged props
+* lack `children` while some ancestor declares it. A component that never
+* had a `children` prop anywhere in its chain isn't a drop — it just
+* doesn't participate.
+*/
+function droppedInheritedChildren(component, resolve) {
+	if (Object.hasOwn(component.props, "children")) return component.props.children === void 0;
+	if (!resolve) return false;
+	const seen = new Set([component.name]);
+	let parentName = component.extendsFrom;
+	while (parentName && !seen.has(parentName)) {
+		seen.add(parentName);
+		const parent = resolve(parentName);
+		if (!parent) return false;
+		if (parent.props.children !== void 0) return true;
+		parentName = parent.extendsFrom;
+	}
+	return false;
+}
+/**
 * `acceptsChildren` is true when either:
 *   - the component has a single primitive root layer, OR
 *   - the component declares a `children` slot prop (`children: slot(...)`).
@@ -938,4 +1039,4 @@ function buildCompoundOverrides(entries) {
 	return out;
 }
 //#endregion
-export { Component, Layer, assertDefinitionAcceptsPlaceable };
+export { Component, Layer, VOID_HTML_TAGS, assertDefinitionAcceptsPlaceable };

package/dist/Config.d.ts

@@ -1,5 +1,5 @@
 import { CssVarRef } from "./types/css-values.js";
-import { AnyStylePropDefinition, BuildOptions, CanvasRole, CanvasRoleEntry, CanvasRolesDefinitionInput, CanvasRolesInputConstraint, ComponentDefinition, ComponentGroupDefinition, CompositeStyleDefinition, GlobalStylesDef, LinkedComponentsInput, LinkedSystemEntry, ModeDefinition, ModifierDefinition, MotionDefinitionInput, PlaygroundOptions, SerializedConfig, TokenGroupDefinition, TokenModifierKey } from "./types.js";
+import { AnyStylePropDefinition, BuildOptions, CanvasRole, CanvasRoleEntry, CanvasRolesDefinitionInput, CanvasRolesInputConstraint, ComponentDefinition, ComponentGroupDefinition, CompositeStyleDefinition, GlobalStylesDef, LinkedSystemPin, LinkedSystemsInput, ModeDefinition, ModifierDefinition, MotionDefinitionInput, PlaygroundOptions, SerializedConfig, SystemLink, TokenGroupDefinition, TokenModifierKey } from "./types.js";
 import { AssetGroupDefinition } from "./defineAssetGroup.js";
 import { AssetGroup } from "./AssetGroup.js";
 import { cssVar } from "./brands.js";
@@ -94,11 +94,12 @@ declare class Config {
   readonly motion: Map<string, MotionDef>;
   readonly canvasRoles: Map<CanvasRole, readonly CanvasRoleEntry[]>;
   /**
-   * Components linked from other systems via {@link registerLinkedComponents},
-   * keyed by the source system's database UUID. Declaration only — resolution
-   * (materialized sources, rendering) is a separate, later concern.
+   * Source systems pinned via {@link registerLinkedSystems}, keyed by the
+   * source system's database UUID. A pin anchors every linked value from that
+   * system to one exact published version — registration validates each
+   * link-marked value against it.
    */
-  readonly linkedComponents: Map<string, LinkedSystemEntry>;
+  readonly linkedSystems: Map<string, LinkedSystemPin>;
   /**
    * Set top-level config metadata in one call — the single scalar-setter,
    * replacing the former `withPrefix` / `withPreflight` / `withName` /
@@ -149,20 +150,6 @@ declare class Config {
    * `config.components.get(type)` when `type` may be a spec/registry key.
    */
   getComponent(type: string): Component | undefined;
-  /**
-   * Identify an id-qualified linked-component reference
-   * (`'<systemId>:<Name>'`, e.g. `'96d1678f-…:Button'`). Returns the parsed
-   * `{ systemId, name }` when the system id is a registered
-   * {@link linkedComponents} entry AND the bare name is declared in its
-   * `components` list; `undefined` otherwise (including bare names and
-   * namespaced registry keys). This is declaration-lookup only — it never
-   * returns a renderable {@link Component}; resolution is deferred to the
-   * materialization/rendering work.
-   */
-  getLinkedComponentRef(type: string): {
-    systemId: string;
-    name: string;
-  } | undefined;
   /**
    * The bare, human-readable component name for a spec `type` — strips this
    * registry's `<namespace>:` prefix (`'uds:Text'` → `'Text'`) for display, and
@@ -331,18 +318,19 @@ declare class Config {
   registerComposites(composites: Record<string, CompositeStyleDefinition>): this;
   registerMotion(motion: Record<string, MotionDefinitionInput>): this;
   /**
-   * Declare components linked from other systems. Each record key is the
-   * source system's database UUID (the identity — globally unique, immutable,
-   * rename-proof); the entry carries the system's display-name snapshot at
-   * link time, an exact published version pin, and the bare names of the
-   * linked components.
+   * Pin the source systems this config links values from. Each record key is
+   * the source system's database UUID (the identity — globally unique,
+   * immutable, rename-proof); the pin carries the system's display-name
+   * snapshot at link time and an exact published version.
    *
-   * This is a data-only declaration: no imported component values, no
-   * layer/prop specs. A linked component's qualified reference is
-   * `<systemId>:<Name>` (see {@link getLinkedComponentRef}); resolution to a
-   * renderable component is deferred to the materialization/rendering work.
+   * One pin per system, one version per pin. Every linked value registered
+   * afterwards (a barrel value carrying a `link` marker) is validated against
+   * its pin — an unpinned system or a version mismatch throws at
+   * registration, so pins must appear before the `register*` calls that use
+   * them. The pin's `name` also feeds the registry folder slug the pull
+   * pipeline derives.
    */
-  registerLinkedComponents(input: LinkedComponentsInput): this;
+  registerLinkedSystems(input: LinkedSystemsInput): this;
   registerComponents(components: Record<string, ComponentDefinition>): this;
   /**
    * Build a single component from its definition with this config's context
@@ -437,6 +425,13 @@ declare class Config {
   registerProviders(providers: Record<string, ProviderComponent<Record<never, never>>>): this;
   get derived(): {
     readonly tokens: ReadonlyMap<string, Token>;
+    /**
+     * Provenance index for linked tokens — `"<systemId>:<sourceKey>"` →
+     * token. A `token()` ref authored inside a linked token names SOURCE-
+     * system groups, so it resolves through this index (rename-proof: the
+     * consumer's local group name never appears in the key).
+     */
+    readonly tokensBySource: ReadonlyMap<string, Token>;
     readonly cssVarRefs: Readonly<Record<string, Readonly<Record<string, CssVarRef>>>>;
     /**
      * Reverse lookup: a style modifier key (`_dark`) → the mode option that
@@ -446,6 +441,16 @@ declare class Config {
      */
     readonly modeOptionsByModifier: ReadonlyMap<TokenModifierKey, ModeOption>;
   };
+  /**
+   * Resolve a `token()` ref, provenance-aware — the ONE lookup every ref
+   * consumer (registration wiring, `validate()`, codegen emission) should
+   * use. A ref authored on a linked token (`context` set) names the SOURCE
+   * system's groups, so it resolves through the provenance index only —
+   * falling back to the consumer's own keys would let a coincidentally-named
+   * local group silently shadow a missing source group. Local refs resolve
+   * against consumer keys.
+   */
+  resolveTokenRef(ref: string, context?: SystemLink): Token | undefined;
   /**
    * Validate cross-references. Throws on cycles in token aliases or on
    * unknown refs in markers (`token()`, `composite()`, `mode()`,

package/dist/Config.js

@@ -65,11 +65,12 @@ var Config = class Config {
 	motion = /* @__PURE__ */ new Map();
 	canvasRoles = /* @__PURE__ */ new Map();
 	/**
-	* Components linked from other systems via {@link registerLinkedComponents},
-	* keyed by the source system's database UUID. Declaration only — resolution
-	* (materialized sources, rendering) is a separate, later concern.
+	* Source systems pinned via {@link registerLinkedSystems}, keyed by the
+	* source system's database UUID. A pin anchors every linked value from that
+	* system to one exact published version — registration validates each
+	* link-marked value against it.
 	*/
-	linkedComponents = /* @__PURE__ */ new Map();
+	linkedSystems = /* @__PURE__ */ new Map();
 	#derived;
 	/**
 	* Set top-level config metadata in one call — the single scalar-setter,
@@ -134,27 +135,6 @@ var Config = class Config {
 		if (namespace !== void 0 && namespace === this.namespace) return this.components.get(name);
 	}
 	/**
-	* Identify an id-qualified linked-component reference
-	* (`'<systemId>:<Name>'`, e.g. `'96d1678f-…:Button'`). Returns the parsed
-	* `{ systemId, name }` when the system id is a registered
-	* {@link linkedComponents} entry AND the bare name is declared in its
-	* `components` list; `undefined` otherwise (including bare names and
-	* namespaced registry keys). This is declaration-lookup only — it never
-	* returns a renderable {@link Component}; resolution is deferred to the
-	* materialization/rendering work.
-	*/
-	getLinkedComponentRef(type) {
-		const { namespace: systemId, name } = parseRegistryKey(type);
-		if (systemId === void 0) return void 0;
-		const entry = this.linkedComponents.get(systemId);
-		if (!entry) return void 0;
-		if (entry.components !== "all" && !entry.components.includes(name)) return;
-		return {
-			systemId,
-			name
-		};
-	}
-	/**
 	* The bare, human-readable component name for a spec `type` — strips this
 	* registry's `<namespace>:` prefix (`'uds:Text'` → `'Text'`) for display, and
 	* the `foreign:` sentinel third-party leaves carry (`'foreign:CopyIcon'` →
@@ -900,13 +880,16 @@ var Config = class Config {
 		return this;
 	}
 	registerTokenGroups(groups) {
-		for (const [namespace, def] of Object.entries(groups)) this.tokenGroups.set(namespace, new TokenGroup({
-			namespace,
-			prefixGetter: () => this.prefix,
-			definition: def,
-			tokenLookup: (ref) => this.derived.tokens.get(ref),
-			stylePropertiesLookup: (ns) => this.#stylePropertiesFor(ns)
-		}));
+		for (const [namespace, def] of Object.entries(groups)) {
+			for (const [tokenName, tokenDef] of Object.entries(def.tokens)) this.#assertLinkedTokenPinned(namespace, tokenName, tokenDef.link);
+			this.tokenGroups.set(namespace, new TokenGroup({
+				namespace,
+				prefixGetter: () => this.prefix,
+				definition: def,
+				tokenLookup: (ref, context) => this.resolveTokenRef(ref, context),
+				stylePropertiesLookup: (ns) => this.#stylePropertiesFor(ns)
+			}));
+		}
 		this.#invalidate();
 		return this;
 	}
@@ -938,24 +921,24 @@ var Config = class Config {
 		return this;
 	}
 	/**
-	* Declare components linked from other systems. Each record key is the
-	* source system's database UUID (the identity — globally unique, immutable,
-	* rename-proof); the entry carries the system's display-name snapshot at
-	* link time, an exact published version pin, and the bare names of the
-	* linked components.
+	* Pin the source systems this config links values from. Each record key is
+	* the source system's database UUID (the identity — globally unique,
+	* immutable, rename-proof); the pin carries the system's display-name
+	* snapshot at link time and an exact published version.
 	*
-	* This is a data-only declaration: no imported component values, no
-	* layer/prop specs. A linked component's qualified reference is
-	* `<systemId>:<Name>` (see {@link getLinkedComponentRef}); resolution to a
-	* renderable component is deferred to the materialization/rendering work.
+	* One pin per system, one version per pin. Every linked value registered
+	* afterwards (a barrel value carrying a `link` marker) is validated against
+	* its pin — an unpinned system or a version mismatch throws at
+	* registration, so pins must appear before the `register*` calls that use
+	* them. The pin's `name` also feeds the registry folder slug the pull
+	* pipeline derives.
 	*/
-	registerLinkedComponents(input) {
-		for (const [systemId, entry] of Object.entries(input)) {
-			validateLinkedSystemEntry(systemId, entry, this.linkedComponents);
-			this.linkedComponents.set(systemId, {
-				name: entry.name,
-				version: entry.version,
-				components: entry.components === "all" ? "all" : [...entry.components]
+	registerLinkedSystems(input) {
+		for (const [systemId, pin] of Object.entries(input)) {
+			validateLinkedSystemPin(systemId, pin, this.linkedSystems);
+			this.linkedSystems.set(systemId, {
+				name: pin.name,
+				version: pin.version
 			});
 		}
 		return this;
@@ -1254,11 +1237,13 @@ var Config = class Config {
 	get derived() {
 		if (!this.#derived) {
 			const tokens = /* @__PURE__ */ new Map();
+			const tokensBySource = /* @__PURE__ */ new Map();
 			const cssVarRefs = {};
 			for (const [namespace, group] of this.tokenGroups) {
 				const groupRefs = {};
 				for (const [name, token] of group.tokens) {
 					tokens.set(`${namespace}/${name}`, token);
+					if (token.link) tokensBySource.set(`${token.link.systemId}:${token.link.sourceKey}`, token);
 					groupRefs[name] = token.derived.cssVarRef;
 				}
 				cssVarRefs[namespace] = groupRefs;
@@ -1272,12 +1257,39 @@ var Config = class Config {
 			}
 			this.#derived = {
 				tokens,
+				tokensBySource,
 				cssVarRefs,
 				modeOptionsByModifier
 			};
 		}
 		return this.#derived;
 	}
+	/**
+	* Resolve a `token()` ref, provenance-aware — the ONE lookup every ref
+	* consumer (registration wiring, `validate()`, codegen emission) should
+	* use. A ref authored on a linked token (`context` set) names the SOURCE
+	* system's groups, so it resolves through the provenance index only —
+	* falling back to the consumer's own keys would let a coincidentally-named
+	* local group silently shadow a missing source group. Local refs resolve
+	* against consumer keys.
+	*/
+	resolveTokenRef(ref, context) {
+		if (context) return this.derived.tokensBySource.get(`${context.systemId}:${ref}`);
+		return this.derived.tokens.get(ref);
+	}
+	/**
+	* Pin-consistency gate for a link-marked token entering the registry.
+	* Catches hand-forged markers (unpinned system), stale registry barrels
+	* (version mismatch), and mis-kinded markers before they poison lookups.
+	*/
+	#assertLinkedTokenPinned(groupName, tokenName, link) {
+		if (!link) return;
+		const label = `Config.registerTokenGroups: token "${groupName}/${tokenName}"`;
+		if (link.kind !== "token") throw new Error(`${label} carries a "${link.kind}" link marker — a token entry can only carry kind "token" (a token-group link spreads to per-token markers).`);
+		const pin = this.linkedSystems.get(link.systemId);
+		if (!pin) throw new Error(`${label} is linked from system "${link.systemId}", which has no registerLinkedSystems pin — pin the system (name + exact version) before registering values linked from it.`);
+		if (pin.version !== link.systemVersion) throw new Error(`${label} is linked at version "${link.systemVersion}" but system "${pin.name}" is pinned at "${pin.version}" — the registry barrel is stale; re-run \`uds pull\`.`);
+	}
 	#invalidate() {
 		this.#derived = void 0;
 	}
@@ -1334,7 +1346,7 @@ var Config = class Config {
 	*/
 	validate() {
 		const tokens = this.derived.tokens;
-		for (const [qualified, token] of tokens) visit(qualified, token, tokens, /* @__PURE__ */ new Set());
+		for (const [qualified, token] of tokens) visit(qualified, token, (ref, context) => this.resolveTokenRef(ref, context), /* @__PURE__ */ new Set());
 		for (const styleProp of this.styleProps.values()) for (const groupName of styleProp.consumedTokenGroups()) if (!this.tokenGroups.has(groupName)) throw new Error(`Style prop '${styleProp.name}' references unknown token group '${groupName}'`);
 		for (const modifier of this.modifiers.values()) {
 			const selector = modifier.selector;
@@ -1422,10 +1434,7 @@ var Config = class Config {
 			out.canvasRoles = canvasRoles;
 		}
 		if (this.playgroundOptions.port !== void 0) out.playgroundOptions = { port: this.playgroundOptions.port };
-		if (this.linkedComponents.size > 0) out.linkedComponents = mapToRecord(this.linkedComponents, (entry) => ({
-			...entry,
-			components: entry.components === "all" ? "all" : [...entry.components]
-		}));
+		if (this.linkedSystems.size > 0) out.linkedSystems = mapToRecord(this.linkedSystems, (pin) => ({ ...pin }));
 		return out;
 	}
 	/**
@@ -1444,12 +1453,12 @@ var Config = class Config {
 		if (json.globalStyles) config.globalStyles = json.globalStyles;
 		if (json.rawCss) config.rawCss = [...json.rawCss];
 		if (json.modes) config.registerModes(json.modes);
+		if (json.linkedSystems) config.registerLinkedSystems(json.linkedSystems);
 		if (json.tokenGroups) config.registerTokenGroups(json.tokenGroups);
 		if (json.styleProps) config.registerStyleProps(json.styleProps);
 		if (json.modifiers) config.registerModifiers(json.modifiers);
 		if (json.compositeStyles) config.registerComposites(json.compositeStyles);
 		if (json.motion) config.registerMotion(json.motion);
-		if (json.linkedComponents) config.registerLinkedComponents(json.linkedComponents);
 		const componentsByName = json.components ?? {};
 		for (const def of Object.values(componentsByName)) if (def.sourceFilePath) attachSourcePath(def, def.sourceFilePath);
 		const isSubcomponent = /* @__PURE__ */ new Set();
@@ -1569,20 +1578,15 @@ function parseRegistryKey(type) {
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 /** Exact `major.minor.patch` with optional prerelease/build — no ranges. */
 const EXACT_SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
-function validateLinkedSystemEntry(systemId, entry, existing) {
-	const label = `Config.registerLinkedComponents: system id "${systemId}"`;
-	if (!UUID_RE.test(systemId)) throw new Error(`${label} must be a UUID — links are keyed by the source system's database id, not its slug or name.`);
-	if (existing.has(systemId)) throw new Error(`${label} is already linked ("${existing.get(systemId)?.name}") — update or remove the existing entry instead of re-linking.`);
-	if (entry.name.trim().length === 0) throw new Error(`${label}: name must be non-empty — it's the system's display-name snapshot at link time.`);
-	if (!EXACT_SEMVER_RE.test(entry.version)) throw new Error(`${label}: version "${entry.version}" must be an exact semver literal (e.g. "1.3.1") — ranges and tags are not supported.`);
-	if (entry.components === "all") return;
-	if (entry.components.length === 0) throw new Error(`${label}: at least one component name is required (or pass 'all' to link every component).`);
-	const seen = /* @__PURE__ */ new Set();
-	for (const name of entry.components) {
-		if (name.trim().length === 0) throw new Error(`${label}: component names must be non-empty strings.`);
-		if (seen.has(name)) throw new Error(`${label}: duplicate component "${name}".`);
-		seen.add(name);
-	}
+function validateLinkedSystemPin(systemId, pin, existing) {
+	const label = `Config.registerLinkedSystems: system id "${systemId}"`;
+	if (!UUID_RE.test(systemId)) throw new Error(`${label} must be a UUID — pins are keyed by the source system's database id, not its slug or name.`);
+	if (existing.has(systemId)) {
+		const prior = existing.get(systemId);
+		throw new Error(`${label} is already pinned ("${prior?.name}" @ ${prior?.version}) — a config pins one version per system; update the existing pin instead of re-pinning.`);
+	}
+	if (pin.name.trim().length === 0) throw new Error(`${label}: name must be non-empty — it's the system's display-name snapshot at link time and feeds the registry folder slug.`);
+	if (!EXACT_SEMVER_RE.test(pin.version)) throw new Error(`${label}: version "${pin.version}" must be an exact semver literal (e.g. "1.3.1") — ranges and tags are not supported.`);
 }
 function validateNamespace(value) {
 	if (value.length === 0) throw new Error("Config.configure: namespace must be non-empty.");
@@ -1591,15 +1595,39 @@ function validateNamespace(value) {
 	if (value === "foreign") throw new Error(`Config.configure: namespace "${FOREIGN_NAMESPACE}" is reserved for third-party leaf components (the \`${FOREIGN_NAMESPACE}:<Component>\` sentinel).`);
 	return value;
 }
-function visit(qualified, token, tokens, seen) {
+/**
+* Cross-reference walk for one token's alias chain, provenance-aware.
+* `resolve` is the config's `resolveTokenRef` — a ref on a linked token
+* resolves through the provenance index (source-system keys), a local ref
+* through consumer keys. A dangling ref on a linked token is a closure
+* violation (the source group it names was never linked), which gets its own
+* actionable error; a dangling local ref stays the classic unknown-token
+* error. Modifier refs are checked for linked tokens only — the closure rule
+* is new with linking, and local modifier behavior is unchanged.
+*/
+function visit(qualified, token, resolve, seen) {
 	if (seen.has(qualified)) throw new Error(`Token cycle detected at '${qualified}'`);
-	const value = token.value;
-	if (typeof value === "object" && value !== null && "ref" in value && typeof value.ref === "string") {
-		const next = tokens.get(value.ref);
-		if (!next) throw new Error(`Token '${qualified}' references unknown token '${value.ref}'`);
-		visit(value.ref, next, tokens, new Set(seen).add(qualified));
+	const followRef = (ref) => {
+		const next = resolve(ref, token.link);
+		if (!next) {
+			if (token.link) {
+				const [sourceGroup] = ref.split("/");
+				throw new Error(`Token '${qualified}' is linked from system "${token.link.systemId}" and references its token '${ref}', which nothing in this config provides — link the source system's "${sourceGroup}" group too (refs on linked tokens resolve by provenance, not by local group names).`);
+			}
+			throw new Error(`Token '${qualified}' references unknown token '${ref}'`);
+		}
+		visit(`${next.namespace}/${next.name}`, next, resolve, new Set(seen).add(qualified));
+	};
+	if (isTokenRefValue(token.value)) followRef(token.value.ref);
+	if (token.link && token.modifiers) for (const value of Object.values(token.modifiers)) {
+		const inner = typeof value === "object" && value !== null && "value" in value ? value.value : value;
+		if (isTokenRefValue(inner)) followRef(inner.ref);
 	}
 }
+/** A `token()` ref marker — `{ ref: 'ns/name' }` — in a value position. */
+function isTokenRefValue(value) {
+	return typeof value === "object" && value !== null && "ref" in value && typeof value.ref === "string";
+}
 function stripName(entity) {
 	const { name: _name, namespace: _namespace, ...rest } = entity.toJSON();
 	return rest;

package/dist/Token.d.ts

@@ -12,8 +12,15 @@ type ResolvedTokenLiteral = string | number | boolean | undefined;
  * Looks up another token by `namespace/name`. Injected by the parent
  * Config so `Token.derived.value` can chase `token()` aliases without
  * holding a back-ref to the whole config object.
+ *
+ * `context` is the provenance of the token the ref was authored on. A ref
+ * inside a linked token is written against the SOURCE system's group names
+ * (`token('base/carbon-5')` in a group linked from Yahoo OS means Yahoo OS's
+ * `base` group, whatever the consumer renamed it to), so the lookup resolves
+ * it through the link markers instead of the consumer's own keys. Local
+ * tokens pass no context and resolve against the consumer's keys directly.
  */
-type TokenSiblingLookup = (qualifiedName: string) => Token | undefined;
+type TokenSiblingLookup = (qualifiedName: string, context?: SystemLink) => Token | undefined;
 declare class Token {
   #private;
   readonly name: string;

package/dist/Token.js

@@ -43,6 +43,7 @@ var Token = class {
 			const tokenValue = this.value;
 			const tokenType = this.type;
 			const modifiers = this.modifiers;
+			const link = this.link;
 			const prefixGetter = this.#prefixGetter;
 			const lookup = this.#lookup;
 			const groupTypeGetter = this.#groupTypeGetter;
@@ -57,10 +58,10 @@ var Token = class {
 					return `var(${buildCssVar(prefixGetter(), namespace, name)})`;
 				},
 				get value() {
-					return chaseLiteral(tokenValue, lookup);
+					return chaseLiteral(tokenValue, lookup, link);
 				},
 				get cssValueType() {
-					const literal = chaseLiteral(tokenValue, lookup);
+					const literal = chaseLiteral(tokenValue, lookup, link);
 					return resolveTokenValueType({
 						value: typeof literal === "string" ? literal : String(tokenValue),
 						type: tokenType
@@ -68,7 +69,7 @@ var Token = class {
 				},
 				*modifierValues() {
 					if (!modifiers) return;
-					for (const [key, value] of Object.entries(modifiers)) yield [key, resolveModifierLiteral(value, lookup)];
+					for (const [key, value] of Object.entries(modifiers)) yield [key, resolveModifierLiteral(value, lookup, link)];
 				}
 			};
 		}
@@ -99,19 +100,20 @@ function collectModifiers(definition) {
 	}
 	return count > 0 ? modifiers : void 0;
 }
-function chaseLiteral(value, lookup, seen = /* @__PURE__ */ new Set()) {
+function chaseLiteral(value, lookup, context, seen = /* @__PURE__ */ new Set()) {
 	if (isTokenRef(value)) {
-		if (seen.has(value.ref)) return void 0;
-		seen.add(value.ref);
-		const next = lookup(value.ref);
+		const seenKey = `${context?.systemId ?? ""}:${value.ref}`;
+		if (seen.has(seenKey)) return void 0;
+		seen.add(seenKey);
+		const next = lookup(value.ref, context);
 		if (!next) return void 0;
-		return chaseLiteral(next.value, lookup, seen);
+		return chaseLiteral(next.value, lookup, next.link, seen);
 	}
 	if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return value;
 }
-function resolveModifierLiteral(value, lookup) {
-	if (typeof value === "object" && value !== null && "value" in value) return chaseLiteral(value.value, lookup);
-	return chaseLiteral(value, lookup);
+function resolveModifierLiteral(value, lookup, context) {
+	if (typeof value === "object" && value !== null && "value" in value) return chaseLiteral(value.value, lookup, context);
+	return chaseLiteral(value, lookup, context);
 }
 //#endregion
 export { Token };