@yahoo/uds-create-config 2.45.0 → 3.0.1

package/dist/framework/utils/refs.d.ts

@@ -0,0 +1,194 @@
+import { z } from "zod";
+
+//#region src/framework/utils/refs.d.ts
+interface Ref {
+  readonly __ref: string;
+}
+/** A ref as the authoring API returns it. The method is non-enumerable, so an ordinary ref remains
+ * exactly `{ __ref }` in JSON and anywhere that walks its data. Calling it produces the explicit
+ * wire value below: a base ref plus the sparse fields this config owns. */
+type ExtendableRef<Delta extends Record<string, unknown>> = Ref & {
+  extend(delta: Delta): ExtendedRef<Delta>;
+};
+/** A linked entity plus the sparse local fields layered over it. `extend` is data here, not the
+ * authoring method: this is the value stored by Config after `.extend(delta)` is called. */
+interface ExtendedRef<Delta extends Record<string, unknown> = Record<string, unknown>> extends Ref {
+  readonly extend: Delta;
+}
+/**
+ * Whether `path` can be an entity's own path — the invariant {@link splitSource} rests on, so it is
+ * stated next to it.
+ *
+ * An `@` is legal only as the first character, where it opens an npm scope: `package:@ariakit/react`
+ * is that package, and `package:@yahoo/uds-create-config` is this one. Anywhere else it reads as the
+ * source marker, and the split is what every provenance surface believes.
+ *
+ * Without this, a legitimately-named entity misparses in silence. A token called `1@2x` under `size`
+ * is a plausible name for a retina scale and was storable, and `token:size/1@2x` then reports its path
+ * as `size/1` and invents a source called `2x` — which paints nothing (`renderStyleValue` takes its
+ * `if (!source) return ''` escape and the declaration vanishes), reports a false dangling ref naming a
+ * source that does not exist, and marks the item borrowed on every provenance surface. Nothing throws.
+ *
+ * Checked where a path becomes an identity — a create, a rename's target, an authored entry — and
+ * deliberately not on reads, so an existing bad path stays addressable and, more to the point,
+ * deletable.
+ */
+declare function isEntityPath(path: string): boolean;
+/** What a refused path should say, in one place, so a create, a rename and a register word it alike. */
+declare const ENTITY_PATH_MESSAGE = "An entity path may not contain \"@\" except as a leading npm scope \u2014 \"@\" marks the source a ref is drawn from, so a path carrying one cannot be told apart from a borrowed address.";
+/** A ref's parts. */
+interface RefParts {
+  readonly kind: string;
+  readonly source: string | undefined;
+  /** without the source — `pathOf`'s answer. */
+  readonly path: string;
+  /** with the source, when there is one — the form an authored value and an emitted union spell,
+   *  because a string in value position has nowhere to put a second argument. */
+  readonly qualifiedPath: string;
+  readonly member: string | undefined;
+  /** whether a `kind:` marker was present — without one, `kind` and `path` are both the whole
+   *  string, and each caller reads the one it means. */
+  readonly marked: boolean;
+}
+/**
+ * `kind:path[@source][#member]`, split — the one place a ref is read. This is the ref spelling of the
+ * address grammar written down whole in `framework/config-op.ts`.
+ *
+ * Every accessor below goes through this, and so does anything outside this file that needs a part of
+ * a ref. Code that slices at `indexOf(':')` or tests `startsWith('token:')` has its own copy of the
+ * grammar, which means the grammar cannot move without hunting for the copies — and a copy that is
+ * subtly wrong (a prefix test that a sourced ref fails) is silent.
+ */
+declare function splitRef(target: string | Ref): RefParts;
+/**
+ * A reference to another entity: `ref('token', 'color/brand')`. Resolution is prefix-or-leaf against
+ * the flat store.
+ *
+ * With a `source` it points into a linked system instead — `ref('token', 'color/brand', 'yahoo-os')`.
+ * That is the whole of what a per-entity link marker used to record: the kind is the ref's kind and
+ * the source key is its path, while the version lives once on the pin rather than being repeated on
+ * every linked entity.
+ */
+declare function ref(kind: string, path: string, source?: string): Ref;
+/** A reference to one member of an entity's sub-entity collection — a component's prop, a layer:
+ *  `memberRef('component', 'Pressable', 'props', 'gap')` → `component:Pressable#props/gap`. A
+ *  `source` qualifies the entity the member is reached through. */
+declare function memberRef(kind: string, path: string, sub: string, member: string, source?: string): Ref;
+/** The entity half of any ref — a plain entity ref is itself. This is the form the dependency
+ *  graph and kind-narrowing speak, so a member ref participates in both unchanged. */
+declare function entityRefOf(target: string): string;
+/** The member half (`props/gap`), or `undefined` for a plain entity ref. Takes the ref itself or its
+ *  string form, like {@link pathOf} / {@link kindOf} / {@link sourceOf}. */
+declare function memberOf(target: string | Ref): string | undefined;
+/** The path of the entity a ref points at — kind, source and any member stripped, so a member ref
+ *  resolves to the item that contains it (`component:buttons/Primary#props/gap` → `buttons/Primary`)
+ *  and a linked ref yields the path as its source spells it (`token:color/brand@yahoo-os` →
+ *  `color/brand`). Takes the ref itself or its string form, so a caller holding a ref field never
+ *  spells `__ref`. */
+declare function pathOf(target: string | Ref): string;
+/** The source half — the link slug a ref points through, or `undefined` when it points at something
+ *  in this config. This is the one question that distinguishes a linked entity from a local one, and
+ *  it replaces reading a per-entity provenance marker. */
+declare function sourceOf(target: string | Ref): string | undefined;
+/** The kind a ref points at (`component:buttons/Primary#props/gap` → `component`) — the twin of
+ *  {@link pathOf}, so a consumer holding a `kind:path` string (a `dependentsOf` result) never splits
+ *  it by hand. Takes the ref itself or its string form. */
+declare function kindOf(target: string | Ref): string;
+/** The zod schema of a ref value — used via {@link orRef} so a field never spells the
+ *  `{ __ref }` shape by hand. `.meta({ ref: true })` marks it as a ref for any consumer (JSON
+ *  Schema, an authoring UI) — this generic form carries no target kind (use an entity as the field
+ *  to bake one in). */
+declare const refSchema: z.ZodObject<{
+  __ref: z.ZodString;
+}, z.core.$strip>;
+/** Widen a field's value type to also accept a ref: `value: orRef(z.string())`. */
+declare function orRef<T extends z.ZodTypeAny>(schema: T): z.ZodUnion<readonly [T, z.ZodObject<{
+  __ref: z.ZodString;
+}, z.core.$strip>]>;
+declare function isRef(value: unknown): value is Ref;
+/** Whether a ref is the stored result of `.extend(delta)`. Kept separate from {@link isRef}: every
+ * existing ref consumer should continue to see the base pointer, while Config is the place that
+ * gives the sibling delta its merge semantics. */
+declare function isExtendedRef(value: unknown): value is ExtendedRef;
+/**
+ * The key marking a row the build minted rather than a person authored.
+ *
+ * A link declares what it took; the rows for everything it brings are made by the build, at the paths
+ * the source spells them, so they are stored — `list`, the rename gate and every emitter reach them
+ * on the way past — without ever having been written down. This is the one thing that tells the two
+ * apart, and three readers turn on it: `uds pull` skips a minted row, a write to one lands on the
+ * source's `options` instead of the row (`Config.apply`'s update handler), and a serialize keeps it
+ * distinguishable rather than laundering it into source.
+ *
+ * Not `DERIVED` — a config already has an unrelated `derived` KIND (`EntityKind.derived`, what
+ * `Package` is), and `Config.derive` clones state on every mutation. A third meaning of the same word
+ * on the one marker that most needs to read unambiguously.
+ *
+ * On the body rather than in a parallel set, so the mark rides with the row through every snapshot
+ * change instead of being a second thing to keep in step.
+ */
+declare const MINTED = "__minted";
+/** Whether a stored body is a row the build minted. See {@link MINTED}. */
+declare function isMintedRow(value: unknown): boolean;
+/**
+ * Every `kind:path` a definition points at — the one generic edge harvester.
+ *
+ * A ref can contribute more than one edge, at different granularities, so that a query at any of
+ * them resolves:
+ *   • a member ref contributes its entity edge too, so pointing at a component's prop still counts
+ *     as depending on that component;
+ * A sourced ref's edge at the link is not here. It needs the kind a `@slug` resolves against, which is
+ * whichever kind the config declared `sourceIdentity` on — and this is a pure walk with no config to
+ * ask. `Config.nameEdgeReaders` contributes it through the ref index's `extra` channel instead, so the
+ * grammar names no kind. This function used to hardcode `'linked-system'` for it.
+ */
+declare function collectRefs(value: unknown, acc?: string[]): string[];
+/**
+ * Deep-rewrite every ref whose target is `from` to `to`, returning a new structure — the generic
+ * rename-cascade the same way `collectRefs` is the generic edge walk.
+ *
+ * Matching is exact on the entity (or on the `#` boundary for members), which is also what keeps a
+ * local rename from reaching across a link: `token:color/brand` and `token:color/brand@yahoo-os` are
+ * different strings, so renaming ours leaves theirs alone. Your key and their key were never the
+ * same field. Don't loosen this to a prefix match.
+ */
+declare function rewriteRefs(value: unknown, from: string, to: string): unknown;
+/**
+ * A value that may be a ref, as the name it names.
+ *
+ * The read twin of {@link rewriteRefNamespace}: a relative ref namespaced under its owner
+ * (`value:variant/solid`) reads back as the leaf every consumer actually compares and emits
+ * (`solid`), so storing the ref costs no reader a branch.
+ *
+ * A non-ref is returned as it is, not stringified, so a condition keeps a real boolean rather than
+ * the string `"true"`. A condition compiles `true` to a bare truthiness test and `false` to
+ * `eq: false`, and both of those need the boolean to still be one by the time they are read.
+ */
+declare function refLeaf(value: unknown): unknown;
+/**
+ * Deep-rewrite the first path segment of every `kind` ref namespaced under `from`.
+ *
+ * The third rename axis, for a relative ref whose path is `<owner-member>/<name>` — a variant
+ * value (`value:variant/solid`) belongs to the prop that declares it, so renaming the prop has to
+ * move every value under it or they all dangle at once. {@link rewriteRefs} can't: it matches the
+ * whole entity or the `#` boundary, and this is a `/` boundary inside the path.
+ *
+ * Narrowed to one `kind` so it can't reach a same-named member of another collection — a layer
+ * called `variant` is `layer:variant` and is left alone.
+ *
+ * A sourced ref is skipped outright. {@link rewriteRefs} gets that property from exact-matching —
+ * `token:color/brand` and `token:color/brand@yahoo-os` are different strings — but a prefix match
+ * would catch both, and renaming our prop is no reason to rewrite a ref into someone else's values.
+ */
+declare function rewriteRefNamespace(value: unknown, kind: string, from: string, to: string): unknown;
+/**
+ * Deep-rewrite the source half of every ref pointing through link `from`, leaving what each one
+ * points at untouched — the cascade for renaming a link.
+ *
+ * The twin of {@link rewriteRefs} on the other axis: that one moves an entity and keeps the source,
+ * this one moves the source and keeps the entity. A link's slug is a local name like any other, so
+ * renaming it has to reach every ref that spells it or they all dangle at once.
+ */
+declare function rewriteRefSource(value: unknown, from: string, to: string): unknown;
+//#endregion
+export { ENTITY_PATH_MESSAGE, ExtendableRef, ExtendedRef, MINTED, Ref, collectRefs, entityRefOf, isEntityPath, isExtendedRef, isMintedRow, isRef, kindOf, memberOf, memberRef, orRef, pathOf, ref, refLeaf, refSchema, rewriteRefNamespace, rewriteRefSource, rewriteRefs, sourceOf, splitRef };

package/dist/framework/utils/refs.js

@@ -0,0 +1,403 @@
+import { z } from "zod";
+//#region src/framework/utils/refs.ts
+/**
+* Refs are imported, typed markers pointing at another entity by `kind` + qualified
+* path. Because a ref is just data inside a definition, the dependency graph falls out
+* of a generic walk (`collectRefs`) — no per-entity edge wiring.
+*/
+/** Separates the entity from the member it points inside — the URL convention (a path, then a
+*  fragment). Everything before it is byte-identical to a plain entity ref, which is what lets the
+*  existing machinery keep working; an entity path may contain `/`, so a distinct character is what
+*  keeps the boundary unambiguous. */
+const MEMBER = "#";
+/**
+* Qualifies an entity with the linked system it lives in — the link's local slug, not the source's
+* database id, so the ref stays readable and survives a rename on their side.
+*
+* It sits before {@link member} because it qualifies the entity: `component:Button@yahoo-os` is a
+* whole identity, and `#props/gap` points inside whatever that resolved to.
+*/
+const SOURCE = "@";
+/** The `@source` suffix for a ref, or `''` when it's local. */
+const qualifier = (source) => source === void 0 ? "" : `${SOURCE}${source}`;
+/**
+* Whether `path` can be an entity's own path — the invariant {@link splitSource} rests on, so it is
+* stated next to it.
+*
+* An `@` is legal only as the first character, where it opens an npm scope: `package:@ariakit/react`
+* is that package, and `package:@yahoo/uds-create-config` is this one. Anywhere else it reads as the
+* source marker, and the split is what every provenance surface believes.
+*
+* Without this, a legitimately-named entity misparses in silence. A token called `1@2x` under `size`
+* is a plausible name for a retina scale and was storable, and `token:size/1@2x` then reports its path
+* as `size/1` and invents a source called `2x` — which paints nothing (`renderStyleValue` takes its
+* `if (!source) return ''` escape and the declaration vanishes), reports a false dangling ref naming a
+* source that does not exist, and marks the item borrowed on every provenance surface. Nothing throws.
+*
+* Checked where a path becomes an identity — a create, a rename's target, an authored entry — and
+* deliberately not on reads, so an existing bad path stays addressable and, more to the point,
+* deletable.
+*/
+function isEntityPath(path) {
+	return path.lastIndexOf(SOURCE) <= 0;
+}
+/** What a refused path should say, in one place, so a create, a rename and a register word it alike. */
+const ENTITY_PATH_MESSAGE = "An entity path may not contain \"@\" except as a leading npm scope — \"@\" marks the source a ref is drawn from, so a path carrying one cannot be told apart from a borrowed address.";
+/**
+* Splits a qualified path into what it names and where from.
+*
+* A path can OPEN with `@`: a package's path is an npm specifier, and `package:@ariakit/react` is
+* scoped. So the source is the last `@`, and never a leading one — a scope opens a path, it doesn't
+* qualify it. `package:@ariakit/react@yahoo-os` is that package, as their system has it.
+*
+* Total for every path {@link isEntityPath} admits, which is what makes "the last `@`" a rule rather
+* than a heuristic: with at most a leading `@` in the path, any later one is the marker.
+*/
+function splitSource(qualified) {
+	const at = qualified.lastIndexOf(SOURCE);
+	if (at <= 0) return [qualified, void 0];
+	return [qualified.slice(0, at), qualified.slice(at + 1)];
+}
+/**
+* `kind:path[@source][#member]`, split — the one place a ref is read. This is the ref spelling of the
+* address grammar written down whole in `framework/config-op.ts`.
+*
+* Every accessor below goes through this, and so does anything outside this file that needs a part of
+* a ref. Code that slices at `indexOf(':')` or tests `startsWith('token:')` has its own copy of the
+* grammar, which means the grammar cannot move without hunting for the copies — and a copy that is
+* subtly wrong (a prefix test that a sourced ref fails) is silent.
+*/
+function splitRef(target) {
+	const raw = isRef(target) ? target.__ref : target;
+	const hash = raw.indexOf(MEMBER);
+	const entity = hash === -1 ? raw : raw.slice(0, hash);
+	const member = hash === -1 ? void 0 : raw.slice(hash + 1);
+	const colon = entity.indexOf(":");
+	const kind = colon === -1 ? entity : entity.slice(0, colon);
+	const qualifiedPath = colon === -1 ? entity : entity.slice(colon + 1);
+	const [path, source] = splitSource(qualifiedPath);
+	return {
+		kind,
+		source,
+		path,
+		qualifiedPath,
+		member,
+		marked: colon !== -1
+	};
+}
+/**
+* A reference to another entity: `ref('token', 'color/brand')`. Resolution is prefix-or-leaf against
+* the flat store.
+*
+* With a `source` it points into a linked system instead — `ref('token', 'color/brand', 'yahoo-os')`.
+* That is the whole of what a per-entity link marker used to record: the kind is the ref's kind and
+* the source key is its path, while the version lives once on the pin rather than being repeated on
+* every linked entity.
+*/
+function ref(kind, path, source) {
+	const value = { __ref: `${kind}:${path}${qualifier(source)}` };
+	Object.defineProperty(value, "extend", {
+		enumerable: false,
+		configurable: false,
+		value: (delta) => ({
+			__ref: value.__ref,
+			extend: delta
+		})
+	});
+	return value;
+}
+/** A reference to one member of an entity's sub-entity collection — a component's prop, a layer:
+*  `memberRef('component', 'Pressable', 'props', 'gap')` → `component:Pressable#props/gap`. A
+*  `source` qualifies the entity the member is reached through. */
+function memberRef(kind, path, sub, member, source) {
+	return { __ref: `${kind}:${path}${qualifier(source)}${MEMBER}${sub}/${member}` };
+}
+/**
+* A ref to a singleton kind, in the form the index and the resolver read: the item at the kind's own
+* name, with whatever path the ref named as its member path. `settings:css/prefix@ds` is
+* `settings:settings@ds#css/prefix`, and `settings:` is `settings:settings`. A ref already at the item
+* is handed back as it came. The caller knows the kind is a singleton; this is pure string work.
+*/
+function singletonRef(target) {
+	const { kind, source, path, member } = splitRef(target);
+	if (path === kind) return target;
+	const tail = [path === "" ? void 0 : path, member].filter((part) => part !== void 0).join("/");
+	return `${kind}:${kind}${qualifier(source)}${tail ? `${MEMBER}${tail}` : ""}`;
+}
+/** The entity half of any ref — a plain entity ref is itself. This is the form the dependency
+*  graph and kind-narrowing speak, so a member ref participates in both unchanged. */
+function entityRefOf(target) {
+	const at = target.indexOf(MEMBER);
+	return at === -1 ? target : target.slice(0, at);
+}
+/** The member half (`props/gap`), or `undefined` for a plain entity ref. Takes the ref itself or its
+*  string form, like {@link pathOf} / {@link kindOf} / {@link sourceOf}. */
+function memberOf(target) {
+	const raw = isRef(target) ? target.__ref : target;
+	const at = raw.indexOf(MEMBER);
+	return at === -1 ? void 0 : raw.slice(at + 1);
+}
+/** The path of the entity a ref points at — kind, source and any member stripped, so a member ref
+*  resolves to the item that contains it (`component:buttons/Primary#props/gap` → `buttons/Primary`)
+*  and a linked ref yields the path as its source spells it (`token:color/brand@yahoo-os` →
+*  `color/brand`). Takes the ref itself or its string form, so a caller holding a ref field never
+*  spells `__ref`. */
+function pathOf(target) {
+	return splitRef(target).path;
+}
+/** The source half — the link slug a ref points through, or `undefined` when it points at something
+*  in this config. This is the one question that distinguishes a linked entity from a local one, and
+*  it replaces reading a per-entity provenance marker. */
+function sourceOf(target) {
+	return splitRef(target).source;
+}
+/** The kind a ref points at (`component:buttons/Primary#props/gap` → `component`) — the twin of
+*  {@link pathOf}, so a consumer holding a `kind:path` string (a `dependentsOf` result) never splits
+*  it by hand. Takes the ref itself or its string form. */
+function kindOf(target) {
+	return splitRef(target).kind;
+}
+/** The zod schema of a ref value — used via {@link orRef} so a field never spells the
+*  `{ __ref }` shape by hand. `.meta({ ref: true })` marks it as a ref for any consumer (JSON
+*  Schema, an authoring UI) — this generic form carries no target kind (use an entity as the field
+*  to bake one in). */
+const refSchema = z.object({ __ref: z.string() }).meta({ ref: true });
+/** Widen a field's value type to also accept a ref: `value: orRef(z.string())`. */
+function orRef(schema) {
+	return z.union([schema, refSchema]);
+}
+function isRef(value) {
+	return typeof value === "object" && value !== null && "__ref" in value;
+}
+/** Whether a ref is the stored result of `.extend(delta)`. Kept separate from {@link isRef}: every
+* existing ref consumer should continue to see the base pointer, while Config is the place that
+* gives the sibling delta its merge semantics. */
+function isExtendedRef(value) {
+	return isRef(value) && "extend" in value && typeof value.extend === "object" && value.extend !== null && !Array.isArray(value.extend);
+}
+/**
+* The key marking a row the build minted rather than a person authored.
+*
+* A link declares what it took; the rows for everything it brings are made by the build, at the paths
+* the source spells them, so they are stored — `list`, the rename gate and every emitter reach them
+* on the way past — without ever having been written down. This is the one thing that tells the two
+* apart, and three readers turn on it: `uds pull` skips a minted row, a write to one lands on the
+* source's `options` instead of the row (`Config.apply`'s update handler), and a serialize keeps it
+* distinguishable rather than laundering it into source.
+*
+* Not `DERIVED` — a config already has an unrelated `derived` KIND (`EntityKind.derived`, what
+* `Package` is), and `Config.derive` clones state on every mutation. A third meaning of the same word
+* on the one marker that most needs to read unambiguously.
+*
+* On the body rather than in a parallel set, so the mark rides with the row through every snapshot
+* change instead of being a second thing to keep in step.
+*/
+const MINTED = "__minted";
+/** Whether a stored body is a row the build minted. See {@link MINTED}. */
+function isMintedRow(value) {
+	return typeof value === "object" && value !== null && value["__minted"] === true;
+}
+/**
+* Every `kind:path` a definition points at — the one generic edge harvester.
+*
+* A ref can contribute more than one edge, at different granularities, so that a query at any of
+* them resolves:
+*   • a member ref contributes its entity edge too, so pointing at a component's prop still counts
+*     as depending on that component;
+* A sourced ref's edge at the link is not here. It needs the kind a `@slug` resolves against, which is
+* whichever kind the config declared `sourceIdentity` on — and this is a pure walk with no config to
+* ask. `Config.nameEdgeReaders` contributes it through the ref index's `extra` channel instead, so the
+* grammar names no kind. This function used to hardcode `'linked-system'` for it.
+*/
+function collectRefs(value, acc = []) {
+	if (isRef(value)) {
+		const entity = entityRefOf(value.__ref);
+		if (entity !== value.__ref) acc.push(entity);
+		acc.push(value.__ref);
+		if (isExtendedRef(value)) collectRefs(value.extend, acc);
+	} else if (Array.isArray(value)) for (const item of value) collectRefs(item, acc);
+	else if (value && typeof value === "object") for (const nested of Object.values(value)) collectRefs(nested, acc);
+	return acc;
+}
+/**
+* Deep-rewrite every ref whose target is `from` to `to`, returning a new structure — the generic
+* rename-cascade the same way `collectRefs` is the generic edge walk.
+*
+* Matching is exact on the entity (or on the `#` boundary for members), which is also what keeps a
+* local rename from reaching across a link: `token:color/brand` and `token:color/brand@yahoo-os` are
+* different strings, so renaming ours leaves theirs alone. Your key and their key were never the
+* same field. Don't loosen this to a prefix match.
+*/
+function rewriteRefs(value, from, to) {
+	if (isRef(value)) {
+		const siblings = {
+			...isExtendedRef(value) ? { extend: rewriteRefs(value.extend, from, to) } : {},
+			...isMintedRow(value) ? { [MINTED]: true } : {}
+		};
+		if (value.__ref === from) return {
+			__ref: to,
+			...siblings
+		};
+		if (value.__ref.startsWith(`${from}${MEMBER}`)) return {
+			__ref: `${to}${value.__ref.slice(from.length)}`,
+			...siblings
+		};
+		return isExtendedRef(value) ? {
+			__ref: value.__ref,
+			...siblings
+		} : value;
+	}
+	if (Array.isArray(value)) return value.map((item) => rewriteRefs(item, from, to));
+	if (value && typeof value === "object") {
+		const out = {};
+		for (const [key, nested] of Object.entries(value)) out[key] = rewriteRefs(nested, from, to);
+		return out;
+	}
+	return value;
+}
+/**
+* A value that may be a ref, as the name it names.
+*
+* The read twin of {@link rewriteRefNamespace}: a relative ref namespaced under its owner
+* (`value:variant/solid`) reads back as the leaf every consumer actually compares and emits
+* (`solid`), so storing the ref costs no reader a branch.
+*
+* A non-ref is returned as it is, not stringified, so a condition keeps a real boolean rather than
+* the string `"true"`. A condition compiles `true` to a bare truthiness test and `false` to
+* `eq: false`, and both of those need the boolean to still be one by the time they are read.
+*/
+function refLeaf(value) {
+	if (!isRef(value)) return value;
+	const path = pathOf(value);
+	const slash = path.indexOf("/");
+	return slash === -1 ? path : path.slice(slash + 1);
+}
+/**
+* Deep-rewrite the first path segment of every `kind` ref namespaced under `from`.
+*
+* The third rename axis, for a relative ref whose path is `<owner-member>/<name>` — a variant
+* value (`value:variant/solid`) belongs to the prop that declares it, so renaming the prop has to
+* move every value under it or they all dangle at once. {@link rewriteRefs} can't: it matches the
+* whole entity or the `#` boundary, and this is a `/` boundary inside the path.
+*
+* Narrowed to one `kind` so it can't reach a same-named member of another collection — a layer
+* called `variant` is `layer:variant` and is left alone.
+*
+* A sourced ref is skipped outright. {@link rewriteRefs} gets that property from exact-matching —
+* `token:color/brand` and `token:color/brand@yahoo-os` are different strings — but a prefix match
+* would catch both, and renaming our prop is no reason to rewrite a ref into someone else's values.
+*/
+function rewriteRefNamespace(value, kind, from, to) {
+	if (isRef(value)) {
+		const siblings = isExtendedRef(value) ? { extend: rewriteRefNamespace(value.extend, kind, from, to) } : {};
+		if (sourceOf(value) !== void 0) return isExtendedRef(value) ? {
+			__ref: value.__ref,
+			...siblings
+		} : value;
+		const prefix = `${kind}:${from}/`;
+		return value.__ref.startsWith(prefix) ? {
+			__ref: `${kind}:${to}/${value.__ref.slice(prefix.length)}`,
+			...siblings
+		} : isExtendedRef(value) ? {
+			__ref: value.__ref,
+			...siblings
+		} : value;
+	}
+	if (Array.isArray(value)) return value.map((item) => rewriteRefNamespace(item, kind, from, to));
+	if (value && typeof value === "object") {
+		const out = {};
+		for (const [key, nested] of Object.entries(value)) out[key] = rewriteRefNamespace(nested, kind, from, to);
+		return out;
+	}
+	return value;
+}
+/**
+* Deep-qualify every unqualified ref with `source` — how a borrowed body's refs read once they have
+* been resolved into the config doing the borrowing.
+*
+* A source spells its own refs locally, because from where it was authored they are local. Merged
+* into a consumer unchanged, each one then names something that consumer was never supposed to own:
+* `file:components/card.tsx` is the publisher's sealed file and the borrower has no such file, so it
+* dangles. The quieter half is worse — a borrower that happens to declare its own `bg` binds
+* `style-property:bg` to its property rather than the one the render was written against, and
+* nothing reads as broken.
+*
+* `owns` decides what counts as an entity reference: only a kind the source actually owns. A ref to
+* a sub-entity (`layer:root`) is scoped to the body holding it and means the same thing on either
+* side of the seam, so qualifying it would invent a link no config could follow.
+*
+* A ref at the kind root (`motion:`, no path) is the same case one level up: it names the kind rather
+* than an entity — the domain a prop is bound to, as `Box`'s `motion` prop is bound to every motion —
+* and a domain means the same thing on either side of the seam too. Qualifying it produced
+* `motion:@uds`, which is not an entity anywhere and cannot be: borrowing a component whose prop is
+* bound to a whole kind left one dangling ref that no amount of linking could satisfy, because there
+* is nothing at that path to link.
+*
+* An already-qualified ref is left alone. It points through the source's own pin, which this config
+* has no slug for — a chain, and a different thing to report.
+*
+* And a ref the borrower already names is left alone too — see `namesItAlready`. That is the one case
+* where the quieter half above does not apply: the borrower's row at that path is a pointer at the very
+* entity the ref means, so binding to it is binding to the same thing, spelled the way everything local
+* spells it.
+*/
+function qualifyRefs({ value, source, owns, namesItAlready }) {
+	const walk = (node) => {
+		if (isRef(node)) {
+			const siblings = isExtendedRef(node) ? { extend: walk(node.extend) } : {};
+			if (sourceOf(node) !== void 0 || !owns(kindOf(node)) || pathOf(node) === "" || namesItAlready?.(node) === true) return isExtendedRef(node) ? {
+				__ref: node.__ref,
+				...siblings
+			} : node;
+			const member = memberOf(node.__ref);
+			const rebuilt = ref(kindOf(node), pathOf(node), source).__ref;
+			return {
+				__ref: member === void 0 ? rebuilt : `${rebuilt}${MEMBER}${member}`,
+				...siblings
+			};
+		}
+		if (Array.isArray(node)) return node.map(walk);
+		if (node && typeof node === "object") {
+			const out = {};
+			for (const [key, nested] of Object.entries(node)) out[key] = walk(nested);
+			return out;
+		}
+		return node;
+	};
+	return walk(value);
+}
+/**
+* Deep-rewrite the source half of every ref pointing through link `from`, leaving what each one
+* points at untouched — the cascade for renaming a link.
+*
+* The twin of {@link rewriteRefs} on the other axis: that one moves an entity and keeps the source,
+* this one moves the source and keeps the entity. A link's slug is a local name like any other, so
+* renaming it has to reach every ref that spells it or they all dangle at once.
+*/
+function rewriteRefSource(value, from, to) {
+	if (isRef(value)) {
+		const siblings = {
+			...isExtendedRef(value) ? { extend: rewriteRefSource(value.extend, from, to) } : {},
+			...isMintedRow(value) ? { [MINTED]: true } : {}
+		};
+		if (sourceOf(value) !== from) return isExtendedRef(value) ? {
+			__ref: value.__ref,
+			...siblings
+		} : value;
+		const member = memberOf(value.__ref);
+		const rebuilt = ref(kindOf(value), pathOf(value), to).__ref;
+		return {
+			__ref: member === void 0 ? rebuilt : `${rebuilt}${MEMBER}${member}`,
+			...siblings
+		};
+	}
+	if (Array.isArray(value)) return value.map((item) => rewriteRefSource(item, from, to));
+	if (value && typeof value === "object") {
+		const out = {};
+		for (const [key, nested] of Object.entries(value)) out[key] = rewriteRefSource(nested, from, to);
+		return out;
+	}
+	return value;
+}
+//#endregion
+export { ENTITY_PATH_MESSAGE, MINTED, collectRefs, entityRefOf, isEntityPath, isExtendedRef, isMintedRow, isRef, kindOf, memberOf, memberRef, orRef, pathOf, qualifyRefs, ref, refLeaf, refSchema, rewriteRefNamespace, rewriteRefSource, rewriteRefs, singletonRef, sourceOf, splitRef };

package/dist/framework/validate-spec.d.ts

@@ -0,0 +1,27 @@
+import { Config } from "./Config.js";
+
+//#region src/framework/validate-spec.d.ts
+/**
+ * A node in a render spec — what it renders, its prop values, its children. The spec is the
+ * HIERARCHY half of rendering and config-v2 does not render: it validates a spec against the config
+ * (are these things real, are these prop values in domain) and leaves drawing to codegen's emitted
+ * components. This type lives here because validation is what config-v2 does with a spec.
+ *
+ * `type` is a REF — the same string an entity ref serializes to, so what a design file stores is
+ * what the config resolves:
+ *
+ *   component:studio/Button          — a component of this system
+ *   icon:phosphor/TrophyIcon         — a glyph from one of its libraries
+ *   package:ariakit/TooltipAnchor    — an export of a package it renders through
+ */
+interface SpecNode {
+  readonly type: string;
+  readonly props?: Record<string, unknown>;
+  readonly children?: readonly SpecNode[];
+  readonly text?: string;
+}
+/** Validate a design-file spec against the config — every node's `type` a real component and its
+ *  props that component's props. Returns per-node error strings (empty = a valid design). */
+declare function validateSpec(config: Config, spec: SpecNode): string[];
+//#endregion
+export { SpecNode, validateSpec };

package/dist/framework/validate-spec.js

@@ -0,0 +1,45 @@
+import { kindOf, memberOf, pathOf, splitRef } from "./utils/refs.js";
+import { childrenPolicy } from "../entities/system/element.js";
+import { resolveComponentProps } from "./projections.js";
+import { refResolves } from "./ref-integrity.js";
+//#region src/framework/validate-spec.ts
+/**
+* `validateSpec` — validate a design-file spec (a tree of component INSTANCES) against a config.
+* Every node is checked against the REAL component: its `type` must be a registered component and
+* its props must be that component's (effective, inheritance included) props. Returns per-node
+* error strings so a caller can reject a bad node and self-correct — the config-v2 edge over
+* composing against loosely-checked tools.
+*
+* Pure over a Config (no mutation): a design file is a document. This is the check the design-file
+* config's `Artboard` entity runs on its `spec` against the SYSTEM config.
+*/
+/** `package:@ariakit/react#Menu` → `@ariakit/react#Menu` — the whole address a node named, minus
+*  the kind, for a message that has to say WHICH export was not found. */
+function qualifiedPathOf(target) {
+	const { qualifiedPath, member } = splitRef(target);
+	return member === void 0 ? qualifiedPath : `${qualifiedPath}#${member}`;
+}
+function walk(config, node, path, errors) {
+	const kind = kindOf(node.type);
+	const target = pathOf(node.type);
+	if (!refResolves(config, node.type)) {
+		const named = config.resolve(kind, target) !== void 0 && memberOf(node.type) ? qualifiedPathOf(node.type) : target;
+		errors.push(`${path}: unknown ${kind} "${named}"`);
+	} else if (kind === "component") {
+		const props = resolveComponentProps(config, target);
+		for (const name of Object.keys(node.props ?? {})) if (!(name in props)) errors.push(`${path}: unknown prop "${name}" on "${node.type}"`);
+		if (node.children?.length && childrenPolicy(config, target) === "none") errors.push(`${path}: "${node.type}" takes no children`);
+	}
+	(node.children ?? []).forEach((child, i) => {
+		walk(config, child, `${path} > ${node.type}[${i}]`, errors);
+	});
+}
+/** Validate a design-file spec against the config — every node's `type` a real component and its
+*  props that component's props. Returns per-node error strings (empty = a valid design). */
+function validateSpec(config, spec) {
+	const errors = [];
+	walk(config, spec, "root", errors);
+	return errors;
+}
+//#endregion
+export { validateSpec };