@yahoo/uds-create-config 4.54.0 → 4.55.0

package/dist/framework/Config.d.ts

@@ -72,7 +72,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 = 20261001131000;
+declare const SERIALIZED_CONFIG_VERSION = 20261001162046;
 interface SerializedConfig {
   /** See {@link SERIALIZED_CONFIG_VERSION}. Always written; a stored artifact may lack it. */
   readonly version: number;
@@ -1470,19 +1470,15 @@ declare class Config {
   /**
    * A slug this config doesn't declare, answered by a source that does.
    *
-   * It exists for a published chain two deep. Materializing keeps a ref whose target has no value to
-   * collapse into — a `style-property`, a component's `file` — so a component borrowed from `mid`
-   * arrives in `top` still spelling `style-property:bg@base`, where `base` is a pin only `mid` declared.
-   * `top` has no way to name it, because the slug belongs to the system that wrote the ref. Answering
-   * `undefined` makes the ref unresolvable, which surfaces as `Cannot inline "style-property:bg@base"`
-   * and takes the whole publish down. Depth one works only because there the slug is the consumer's own.
+   * It supports refs in older published chains that still spell a transitive slug directly. New
+   * borrowed bodies scope that name through their owner (`@mid~base`) so a consumer's own `base`
+   * cannot shadow it, but an artifact written before that scoping may still carry `@base`.
    *
    * Read the way {@link configFor} already describes resolution: it hops configs, each answering for
    * the links it declares. This is the same hop for the source address rather than the entity.
    *
-   * Local first, always. {@link sourceFor} tries {@link ownSourceFor} before reaching here, so a config
-   * that declares `base` itself keeps meaning its own, and a diamond resolves through the pin its owner
-   * wrote.
+   * Local first for an ordinary slug. {@link sourceFor} tries {@link ownSourceFor} before reaching
+   * here, so a config that declares `base` itself keeps meaning its own.
    *
    * Memoized per instance including the misses: a dangling sourced ref is read repeatedly, since
    * `list`, `sourceClosure` and `toJSON` all pass over it, and each miss would otherwise re-walk every
@@ -2422,19 +2418,19 @@ declare class Config {
    */
   recordedSources(): Record<string, RecordedSource>;
   private recordSources;
+  /** Record one source without walking every other link this config declares. */
+  private recordSource;
   /**
    * Every slug this config's refs name, declared here or not — what {@link recordSources} owes a
    * closure for.
    *
-   * Declared slugs are only half of it. Materializing a published chain keeps a ref whose target has no
-   * value to collapse into, so a component borrowed from `mid` arrives holding `style-property:bg@base`,
-   * a slug only `mid` declares. Recording only what this config pins leaves that ref with nothing behind
-   * it, and a consumer holding the artifact alone reads a borrowed component whose style property
-   * resolves to nothing.
+   * Declared slugs are only half of it. Materializing a published chain keeps a ref whose target has
+   * no value to collapse into, so a component borrowed from `mid` can arrive holding
+   * `style-property:bg@mid~base`. Recording only the pins this config declares would leave that
+   * routed ref with nothing behind it.
    *
-   * Reachability is already what a closure means; this applies the same rule to the source address
-   * rather than the target. {@link sourceThrough} is what answers for such a slug, and the pair is why
-   * the recorded artifact is self-contained.
+   * Reachability is already what a closure means; this applies the same rule to the source address.
+   * {@link sourceFor} follows the route, and the recorded artifact remains self-contained.
    *
    * Skipped entirely for a config that borrows nothing, so the common serialize walks nothing extra.
    */

package/dist/framework/Config.js

@@ -5,6 +5,7 @@ import { describePatch } from "./plan.js";
 import { applyPathDelta, isPlainObject, namedFields, pathSegments, sectionDelta, touchedFields } from "./utils/field-path.js";
 import { METADATA_KEYS, declaredField } from "./utils/field-schema.js";
 import { dataSchema, resolveInputSchema } from "./schemas.js";
+import { isComposedValue } from "../entities/system/composed-values.js";
 import { borrowedSlug, classifyOverlay } from "./source-integrity.js";
 import { kindBorrowable, titleCase } from "./registry.js";
 import { isGroupBody } from "./utils/group.js";
@@ -145,11 +146,13 @@ function movesSource(patch, sourceIdentity) {
 * nothing here.
 */
 function reslug(entries, { from, to }) {
-	if (!entries.has(from)) return entries;
-	const held = entries.get(from);
+	const moved = [...entries].filter(([slug]) => slug === from || slug.startsWith(`${from}~`));
+	if (moved.length === 0) return entries;
 	const next = new Map(entries);
-	next.delete(from);
-	if (to !== void 0) next.set(to, held);
+	for (const [slug, held] of moved) {
+		next.delete(slug);
+		if (to !== void 0) next.set(`${to}${slug.slice(from.length)}`, held);
+	}
 	return next;
 }
 /** A source as given — live, wrapped, or serialized — as the `LiveConfig` the state holds. */
@@ -2495,16 +2498,23 @@ var Config = class Config {
 	*/
 	extensionBody(kind, extension) {
 		const source = this.configFor(extension);
+		if (!source) return void 0;
 		const base = source?.resolve(kind, pathOf(extension));
 		if (!base) return void 0;
 		const slug = sourceOf(extension);
 		const owns = (kindName) => source?.ownedKinds().includes(kindName) ?? false;
-		return extendBody(slug ? qualifyRefs({
+		const merged = extendBody(slug ? qualifyRefs({
 			value: base.toJSON(),
 			source: slug,
 			owns,
 			namesItAlready: (target) => this.borrowsExactly(target, slug)
 		}) : base.toJSON(), extension.extend ?? {});
+		return this.entityOf(kind)?.prepareLinkedBody?.({
+			path: pathOf(extension),
+			body: merged,
+			source,
+			config: this
+		}) ?? merged;
 	}
 	/**
 	* Resolve one locally extended linked item: the pinned source body, shallowly overlaid by the fields
@@ -2531,7 +2541,16 @@ var Config = class Config {
 		if (cached === null && !strict) return void 0;
 		const entry = this.entityOf(kind);
 		if (!entry) return void 0;
-		const merged = this.extensionBody(kind, extension);
+		let merged;
+		try {
+			merged = this.extensionBody(kind, extension);
+		} catch (error) {
+			if (!strict) {
+				cache.set(cacheKey, null);
+				return;
+			}
+			throw error;
+		}
 		if (!merged) return void 0;
 		const parsed = dataSchema(entry.schemas, "create", {
 			config: this,
@@ -2573,10 +2592,18 @@ var Config = class Config {
 			ok: false,
 			error: `This system has no "${kind}", so nothing of that kind can be borrowed from "${slug}".`
 		};
-		const merged = this.extensionBody(kind, {
-			__ref: ref(kind, path, slug).__ref,
-			extend: extend ?? {}
-		});
+		let merged;
+		try {
+			merged = this.extensionBody(kind, {
+				__ref: ref(kind, path, slug).__ref,
+				extend: extend ?? {}
+			});
+		} catch (error) {
+			return {
+				ok: false,
+				error: String(error)
+			};
+		}
 		if (!merged) return { ok: true };
 		const parsed = dataSchema(entry.schemas, "create", {
 			config: this,
@@ -2834,6 +2861,14 @@ var Config = class Config {
 	* where the other side can change without us), and the Create badges.
 	*/
 	sourceFor(slug) {
+		const hop = slug.indexOf("~");
+		if (hop > 0 && hop < slug.length - 1) {
+			const head = slug.slice(0, hop);
+			const tail = slug.slice(hop + 1);
+			const live = this.liveSourceFor(head);
+			if (live) return live.sourceFor(tail) ?? this.ownSourceFor(slug);
+			return this.ownSourceFor(slug) ?? this.sourceFor(head)?.sourceFor(tail) ?? this.sourceThrough(slug);
+		}
 		return this.ownSourceFor(slug) ?? this.sourceThrough(slug);
 	}
 	/** This config's own answer for a slug — attached, else the closure it recorded. No hop, which is
@@ -2857,19 +2892,15 @@ var Config = class Config {
 	/**
 	* A slug this config doesn't declare, answered by a source that does.
 	*
-	* It exists for a published chain two deep. Materializing keeps a ref whose target has no value to
-	* collapse into — a `style-property`, a component's `file` — so a component borrowed from `mid`
-	* arrives in `top` still spelling `style-property:bg@base`, where `base` is a pin only `mid` declared.
-	* `top` has no way to name it, because the slug belongs to the system that wrote the ref. Answering
-	* `undefined` makes the ref unresolvable, which surfaces as `Cannot inline "style-property:bg@base"`
-	* and takes the whole publish down. Depth one works only because there the slug is the consumer's own.
+	* It supports refs in older published chains that still spell a transitive slug directly. New
+	* borrowed bodies scope that name through their owner (`@mid~base`) so a consumer's own `base`
+	* cannot shadow it, but an artifact written before that scoping may still carry `@base`.
 	*
 	* Read the way {@link configFor} already describes resolution: it hops configs, each answering for
 	* the links it declares. This is the same hop for the source address rather than the entity.
 	*
-	* Local first, always. {@link sourceFor} tries {@link ownSourceFor} before reaching here, so a config
-	* that declares `base` itself keeps meaning its own, and a diamond resolves through the pin its owner
-	* wrote.
+	* Local first for an ordinary slug. {@link sourceFor} tries {@link ownSourceFor} before reaching
+	* here, so a config that declares `base` itself keeps meaning its own.
 	*
 	* Memoized per instance including the misses: a dangling sourced ref is read repeatedly, since
 	* `list`, `sourceClosure` and `toJSON` all pass over it, and each miss would otherwise re-walk every
@@ -4823,47 +4854,66 @@ var Config = class Config {
 	recordSources() {
 		const recorded = new Map(this.state.recorded);
 		for (const slug of this.reachedSlugs()) {
-			const source = this.liveSourceFor(slug) ?? this.sourceThrough(slug);
-			if (!source) continue;
-			const items = {};
-			const kinds = /* @__PURE__ */ new Set();
-			for (const target of this.sourceClosure(slug)) {
-				const kind = kindOf(target);
-				const path = pathOf(target);
-				const entity = source.resolve(kind, path);
-				if (!entity) continue;
-				kinds.add(kind);
-				items[kind] ??= {};
-				items[kind][path] = entity.toJSON();
-			}
-			if (kinds.size === 0) continue;
-			const state = this.state.sourceStates.get(slug);
-			recorded.set(slug, {
-				...state?.status === "attached" ? { resolved: state.resolved } : {},
-				config: {
-					version: SERIALIZED_CONFIG_VERSION,
-					name: source.name,
-					ownedKinds: [...kinds],
-					items,
-					groups: groupsAbove(source, items)
-				}
-			});
+			const closure = this.recordSource(slug);
+			if (closure) recorded.set(slug, closure);
 		}
 		return recorded;
 	}
+	/** Record one source without walking every other link this config declares. */
+	recordSource(slug) {
+		const source = this.sourceFor(slug);
+		if (!source) return void 0;
+		if (this.state.recorded.has(slug) && !this.liveSourceFor(slug) && source === this.ownSourceFor(slug)) return;
+		const items = {};
+		const kinds = /* @__PURE__ */ new Set();
+		for (const target of this.sourceClosure(slug)) {
+			const kind = kindOf(target);
+			const path = pathOf(target);
+			const entity = source.resolve(kind, path);
+			if (!entity) continue;
+			kinds.add(kind);
+			items[kind] ??= {};
+			items[kind][path] = entity.toJSON();
+		}
+		const settings = source.resolve("settings", "settings");
+		if (settings && source.ownedKinds().includes("settings")) {
+			kinds.add("settings");
+			items.settings = { settings: settings.toJSON() };
+		}
+		if (kinds.size === 0) return void 0;
+		const nestedSlugs = /* @__PURE__ */ new Set();
+		for (const entries of Object.values(items)) for (const body of Object.values(entries)) for (const target of collectRefs(body)) {
+			const nested = sourceOf(target);
+			if (nested !== void 0) nestedSlugs.add(nested);
+		}
+		const nestedSources = Object.fromEntries([...nestedSlugs].flatMap((nested) => {
+			const closure = source.liveSourceFor(nested) ? source.recordSource(nested) : source.state.recorded.get(nested) ?? source.recordSource(nested);
+			return closure ? [[nested, closure]] : [];
+		}));
+		const state = this.state.sourceStates.get(slug);
+		return {
+			...state?.status === "attached" ? { resolved: state.resolved } : {},
+			config: {
+				version: SERIALIZED_CONFIG_VERSION,
+				name: source.name,
+				ownedKinds: [...kinds],
+				items,
+				...Object.keys(nestedSources).length > 0 ? { sources: nestedSources } : {},
+				groups: groupsAbove(source, items)
+			}
+		};
+	}
 	/**
 	* Every slug this config's refs name, declared here or not — what {@link recordSources} owes a
 	* closure for.
 	*
-	* Declared slugs are only half of it. Materializing a published chain keeps a ref whose target has no
-	* value to collapse into, so a component borrowed from `mid` arrives holding `style-property:bg@base`,
-	* a slug only `mid` declares. Recording only what this config pins leaves that ref with nothing behind
-	* it, and a consumer holding the artifact alone reads a borrowed component whose style property
-	* resolves to nothing.
+	* Declared slugs are only half of it. Materializing a published chain keeps a ref whose target has
+	* no value to collapse into, so a component borrowed from `mid` can arrive holding
+	* `style-property:bg@mid~base`. Recording only the pins this config declares would leave that
+	* routed ref with nothing behind it.
 	*
-	* Reachability is already what a closure means; this applies the same rule to the source address
-	* rather than the target. {@link sourceThrough} is what answers for such a slug, and the pair is why
-	* the recorded artifact is self-contained.
+	* Reachability is already what a closure means; this applies the same rule to the source address.
+	* {@link sourceFor} follows the route, and the recorded artifact remains self-contained.
 	*
 	* Skipped entirely for a config that borrows nothing, so the common serialize walks nothing extra.
 	*/
@@ -5264,7 +5314,7 @@ var Config = class Config {
 	*  links from the provided sources. A declared `linkedKind` with no provided source throws. */
 	hydrateFrom(stored, options) {
 		const claimed = schemaVersionOf(stored);
-		if (claimed > 20261001131e3) throw new SchemaVersionTooNew(claimed);
+		if (claimed > 20261001162046) throw new SchemaVersionTooNew(claimed);
 		const wire = upgradeSerializedConfig(stored);
 		if (!Array.isArray(wire.ownedKinds) || typeof wire.items !== "object" || wire.items === null) throw new ConfigFormatError(`Config "${stored.name ?? "system-config"}" cannot be hydrated: this is not a serialized config-v2 config (no "ownedKinds"/"items"). A pre-cutover build artifact converts through the registered cutover migration — import the config type's module (e.g. \`configs/system\`) before hydrating, or port the repo once with \`uds migrate\`.`);
 		const leftover = wire.options;
@@ -5369,7 +5419,7 @@ function refusePhantomsIn({ kind, path, body }) {
 	for (const phantom of phantomsIn(body)) rejectData(`${kind}:${path} ${phantom.at.join(".")} holds ${phantom.spelled}${PHANTOM_IN_DATA}`, phantom.at);
 }
 function isPathSegment(meta, kind, raw) {
-	if (typeof raw !== "object" || raw === null || Array.isArray(raw) || isRef(raw)) return false;
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw) || isRef(raw) || isComposedValue(raw)) return false;
 	const entry = meta.entities.get(kind);
 	if (!entry) return false;
 	const create = dataSchema(entry.schemas, "create");
@@ -5586,7 +5636,7 @@ function extensionChange(entry, kind, path, raw, validate = false) {
 * every load.
 */
 function itemChange(entry, kind, path, raw, validate = false) {
-	const def = isRef(raw) || typeof raw !== "object" || raw === null ? { [entry.primaryField]: raw } : raw;
+	const def = isRef(raw) || isComposedValue(raw) || typeof raw !== "object" || raw === null ? { [entry.primaryField]: raw } : raw;
 	if (validate) {
 		const parsed = wholeBodySchema(entry)?.safeParse(def);
 		if (parsed && !parsed.success) {

package/dist/framework/class-names.d.ts

@@ -232,12 +232,45 @@ declare function stylePropClassBase(config: Config, path: string): string;
  * The value is a LEAF, which is what a call site writes; an empty leaf is a boolean prop's `true`
  * arm, whose class is the bare stem (`uds-border`) because a flag names no value.
  *
- * A slash becomes a dash and a DOT an underscore, because a class name can hold neither: `.uds-p-0.5`
- * is not one selector but two (`uds-p-0` and `5`), so the rule the sheet wrote could never match the
- * element the module classed. `spacing/0.5` is a real token in a real system, which is how that
- * surfaced.
+ * A slash in a leaf is a group separator and becomes a dash (`red/500` → `bg-red-500`), except in a
+ * leaf that is a fraction, which keeps it (`w-1/2`). A dot is kept (`p-0.5`); the stylesheet writes
+ * the class through {@link classSelector}, which escapes both.
  */
 declare function stylePropClassName(config: Config, path: string, leaf: string): string;
+/** Each value of a prop that names its own class, as the class it is written as. Shared with the
+ *  emitted runtime, which writes the same class for the same value. */
+declare function stylePropOwnClasses(config: Config, path: string): Map<string, string>;
+/**
+ * A leaf as a class spells it. Whitespace becomes a hyphen: a class list splits on it, so
+ * `my custom background` would put three classes on the element and match none of the one rule.
+ * The emitted `_style-props` runtime applies the same transform to the values a call site passes.
+ */
+declare function classLeaf(leaf: string): string;
+/**
+ * A class as a selector: `.p-0\.5`, `.w-1\/2`, `.md\:flex`, `.\32xl\:p-4`. Every character outside
+ * an identifier's own is escaped, and a leading digit, which an identifier cannot start with, is
+ * written as its code point.
+ */
+declare function classSelector(name: string): string;
+/**
+ * Whether a prop's bracketed value has to be written as its arbitrary class rather than inline.
+ * An inline style sets each of the prop's `properties` on the element and nothing else, so a prop
+ * with a `selector`, its own `declarations`, or a property keyed by a token ref would paint wrong.
+ */
+declare function arbitraryNeedsClass(config: Config, path: string): boolean;
+/**
+ * The class a bracketed value is written as — `blur` and `[3px]` → `uds-blur-[3px]`. A space inside
+ * the brackets is spelled `_`, which the stylesheet reads back as one.
+ */
+declare function arbitraryClassName({
+  config,
+  path,
+  value
+}: {
+  readonly config: Config;
+  readonly path: string; /** The authored value, brackets included. */
+  readonly value: string;
+}): string;
 /** What a prop bag amounts to once styling is taken out of it. */
 interface SplitStyleProps {
   /** The classes the bag's style props produce, space-joined. */
@@ -254,8 +287,9 @@ interface SplitStyleProps {
  * but the CLASS NAMES both produce come from {@link stylePropClassName}, so the two can't disagree
  * about what a value is called.
  *
- * An off-scale value can't be a class, so it lands in `style` on the returned rest; an explicit
- * `style` the caller passed still wins, since that's the escape hatch of last resort.
+ * An off-scale value lands in `style` on the returned rest, unless the prop needs its arbitrary class
+ * ({@link arbitraryNeedsClass}); an explicit `style` the caller passed still wins, since that's the
+ * escape hatch of last resort.
  */
 declare function splitStyleProps({
   config,
@@ -296,5 +330,11 @@ declare function stylePropClasses(config: Config, path: string): Map<string, str
  * the system can predict it. Covering those needs the document as a second source of use.
  */
 declare function modifierUtilitiesUsed(config: Config): Set<string>;
+/**
+ * A class split at the colons that separate its modifiers, as `md:hover:[&_a]:bg-[url(a:b)]` is
+ * `md`, `hover`, `[&_a]` and `bg-[url(a:b)]`. A colon inside brackets or parentheses belongs to the
+ * value. The last segment is the utility.
+ */
+declare function splitVariants(cls: string): string[];
 //#endregion
-export { ComponentRuleClass, PickedComposite, SplitStyleProps, componentClassBase, componentCompositeClasses, componentLayerClass, componentMotionClasses, componentPropClasses, componentPropComposites, componentRuleClasses, forceModeAttribute, forceModeAttributeOf, forceModeProp, forceModePropGroup, forceModePropValue, forceModeProps, forceStateAttribute, inlineRuleComposites, isForceModeProp, kebabComponent, layerRoutedProps, modifierUtilitiesUsed, motionClassName, ruleCondition, splitStyleProps, stylePropClassBase, stylePropClassName, stylePropClasses, styleRuleMotionClasses };
+export { ComponentRuleClass, PickedComposite, SplitStyleProps, arbitraryClassName, arbitraryNeedsClass, classLeaf, classSelector, componentClassBase, componentCompositeClasses, componentLayerClass, componentMotionClasses, componentPropClasses, componentPropComposites, componentRuleClasses, forceModeAttribute, forceModeAttributeOf, forceModeProp, forceModePropGroup, forceModePropValue, forceModeProps, forceStateAttribute, inlineRuleComposites, isForceModeProp, kebabComponent, layerRoutedProps, modifierUtilitiesUsed, motionClassName, ruleCondition, splitStyleProps, splitVariants, stylePropClassBase, stylePropClassName, stylePropClasses, stylePropOwnClasses, styleRuleMotionClasses };

package/dist/framework/class-names.js

@@ -1,9 +1,9 @@
-import { isRef, kindOf, memberOf, pathOf, refLeaf } from "./utils/refs.js";
+import { isRef, kindOf, memberOf, pathOf, refLeaf, refOfKey } from "./utils/refs.js";
 import { forwardsOf, rootLayerOf } from "../entities/system/element.js";
 import { createSliceMemo } from "./memo.js";
-import { classPrefixOf, varPrefixOf } from "../entities/system/Settings.js";
+import { classPrefixOf, prefixed, varPrefixOf } from "../entities/system/Settings.js";
 import { storedPreview } from "./preview-store.js";
-import { authoredValue, className, negatedCssValue, renderStyleValue, resolveComponentProps, stylePropLeafForToken, stylePropValueLeaves, stylePropertyPathFor } from "./projections.js";
+import { authoredValue, className, negatedCssValue, renderStyleValue, resolveComponentProps, stylePropEntries, stylePropLeafForToken, stylePropValueLeaves, stylePropertyPathFor } from "./projections.js";
 import { ruleApplies } from "./layer-styles.js";
 //#region src/framework/class-names.ts
 /**
@@ -279,7 +279,10 @@ function componentCompositeClasses(config, path) {
 /** The class a CSS motion preset is applied by. Namespaced, so it doesn't share a space with the
 *  style-prop utilities; the `@keyframes` it runs keep their own name. */
 function motionClassName(config, path) {
-	return `${classPrefixOf(config)}-motion-${path.replaceAll("/", "-")}`;
+	return prefixed({
+		prefix: classPrefixOf(config),
+		name: `motion-${path.replaceAll("/", "-")}`
+	});
 }
 /**
 * Every MOTION class a component's style rules apply — a layer bag naming a preset (`motion: 'spin'`).
@@ -472,7 +475,10 @@ function inlineRuleComposites(config, element, bag) {
 		const at = member.indexOf("/");
 		inlined = mergeStyleBags(inlined ?? {}, {
 			...styles,
-			[`--${varPrefixOf(config)}-composite-${member.slice(0, at)}`]: member.slice(at + 1)
+			[`--${prefixed({
+				prefix: varPrefixOf(config),
+				name: `composite-${member.slice(0, at)}`
+			})}`]: member.slice(at + 1)
 		});
 	}
 	return inlined ? mergeStyleBags(inlined, rest) : bag;
@@ -587,15 +593,63 @@ function stylePropClassBase(config, path) {
 * The value is a LEAF, which is what a call site writes; an empty leaf is a boolean prop's `true`
 * arm, whose class is the bare stem (`uds-border`) because a flag names no value.
 *
-* A slash becomes a dash and a DOT an underscore, because a class name can hold neither: `.uds-p-0.5`
-* is not one selector but two (`uds-p-0` and `5`), so the rule the sheet wrote could never match the
-* element the module classed. `spacing/0.5` is a real token in a real system, which is how that
-* surfaced.
+* A slash in a leaf is a group separator and becomes a dash (`red/500` → `bg-red-500`), except in a
+* leaf that is a fraction, which keeps it (`w-1/2`). A dot is kept (`p-0.5`); the stylesheet writes
+* the class through {@link classSelector}, which escapes both.
 */
 function stylePropClassName(config, path, leaf) {
+	const own = ownClassNames(config, path).get(leaf);
+	if (own !== void 0) return prefixed({
+		prefix: classPrefixOf(config),
+		name: own
+	});
 	const base = stylePropClassBase(config, path);
-	const suffix = leaf.replaceAll("/", "-").replaceAll(".", "_").replace(/\s+/g, "-");
-	return suffix ? `${base}-${suffix}` : base;
+	const suffix = classLeaf(leaf);
+	if (!suffix) return base;
+	return base ? `${base}-${suffix}` : suffix;
+}
+/** Leaf → the class it names, per prop's entries, for the values that name their own. */
+const ownClassNameCache = /* @__PURE__ */ new WeakMap();
+/** The values of a prop that name their own class, by leaf. */
+function ownClassNames(config, path) {
+	const entries = stylePropEntries(config, path);
+	let own = ownClassNameCache.get(entries);
+	if (!own) {
+		const built = /* @__PURE__ */ new Map();
+		for (const entry of entries) if (entry.className !== void 0 && !built.has(entry.leaf)) built.set(entry.leaf, entry.className);
+		own = built;
+		ownClassNameCache.set(entries, own);
+	}
+	return own;
+}
+/** Each value of a prop that names its own class, as the class it is written as. Shared with the
+*  emitted runtime, which writes the same class for the same value. */
+function stylePropOwnClasses(config, path) {
+	const out = /* @__PURE__ */ new Map();
+	for (const leaf of ownClassNames(config, path).keys()) out.set(leaf, stylePropClassName(config, path, leaf));
+	return out;
+}
+/**
+* A leaf as a class spells it. Whitespace becomes a hyphen: a class list splits on it, so
+* `my custom background` would put three classes on the element and match none of the one rule.
+* The emitted `_style-props` runtime applies the same transform to the values a call site passes.
+*/
+function classLeaf(leaf) {
+	const spaced = leaf.replace(/\s+/g, "-");
+	return /^\d+\/\d+$/.test(spaced) ? spaced : spaced.replaceAll("/", "-");
+}
+/**
+* A class as a selector: `.p-0\.5`, `.w-1\/2`, `.md\:flex`, `.\32xl\:p-4`. Every character outside
+* an identifier's own is escaped, and a leading digit, which an identifier cannot start with, is
+* written as its code point.
+*/
+function classSelector(name) {
+	const escaped = name.replace(/[^A-Za-z0-9_\-\u00a0-\uffff]/g, (char) => `\\${char}`);
+	const leading = /^-?\d/.exec(escaped);
+	if (!leading) return `.${escaped}`;
+	const at = leading[0].length - 1;
+	const digit = escaped.charCodeAt(at).toString(16);
+	return `.${escaped.slice(0, at)}\\${digit} ${escaped.slice(at + 1)}`;
 }
 /** An off-scale value and what it really is — `[13px]` → `13px`, else `undefined`. The brackets mark
 *  a value the system doesn't tokenize; they aren't part of it. No class can exist for one, because a
@@ -613,6 +667,23 @@ function unescapeArbitrary(value) {
 	return value.replace(/url\([^)]*\)|_/g, (span) => span === "_" ? " " : span);
 }
 /**
+* Whether a prop's bracketed value has to be written as its arbitrary class rather than inline.
+* An inline style sets each of the prop's `properties` on the element and nothing else, so a prop
+* with a `selector`, its own `declarations`, or a property keyed by a token ref would paint wrong.
+*/
+function arbitraryNeedsClass(config, path) {
+	const { properties = [], declarations, selector } = config.resolve("style-property", path)?.toJSON() ?? {};
+	return Boolean(selector) || Object.keys(declarations ?? {}).length > 0 || properties.some((property) => refOfKey(property) !== void 0);
+}
+/**
+* The class a bracketed value is written as — `blur` and `[3px]` → `uds-blur-[3px]`. A space inside
+* the brackets is spelled `_`, which the stylesheet reads back as one.
+*/
+function arbitraryClassName({ config, path, value }) {
+	const inner = value.slice(1, -1).replace(/\s+/g, "_");
+	return `${stylePropClassBase(config, path)}-[${inner}]`;
+}
+/**
 * Split a prop bag into a class string and the props that aren't styling.
 *
 * This is the same dispatch the emitted `_style-props` runtime performs, over a live config instead
@@ -621,8 +692,9 @@ function unescapeArbitrary(value) {
 * but the CLASS NAMES both produce come from {@link stylePropClassName}, so the two can't disagree
 * about what a value is called.
 *
-* An off-scale value can't be a class, so it lands in `style` on the returned rest; an explicit
-* `style` the caller passed still wins, since that's the escape hatch of last resort.
+* An off-scale value lands in `style` on the returned rest, unless the prop needs its arbitrary class
+* ({@link arbitraryNeedsClass}); an explicit `style` the caller passed still wins, since that's the
+* escape hatch of last resort.
 */
 function splitStyleProps({ config, bag, through }) {
 	const classes = [];
@@ -656,6 +728,14 @@ function splitStyleProps({ config, bag, through }) {
 		if (value === void 0 || value === null) continue;
 		const { arbitrary, properties = [], negates } = prop.toJSON();
 		const off = arbitrary ? offScale(value) : void 0;
+		if (off !== void 0 && arbitraryNeedsClass(config, name)) {
+			classes.push(arbitraryClassName({
+				config,
+				path: name,
+				value: String(value)
+			}));
+			continue;
+		}
 		if (off !== void 0) {
 			const declared = negates ? negatedCssValue(off) : off;
 			for (const property of properties) style[reactStyleKey(property)] = declared;
@@ -827,5 +907,26 @@ function classesUsedBy(config, stored, token, bagsOf) {
 	byVocabulary.set(token, found);
 	return found;
 }
+/**
+* A class split at the colons that separate its modifiers, as `md:hover:[&_a]:bg-[url(a:b)]` is
+* `md`, `hover`, `[&_a]` and `bg-[url(a:b)]`. A colon inside brackets or parentheses belongs to the
+* value. The last segment is the utility.
+*/
+function splitVariants(cls) {
+	const segments = [];
+	let depth = 0;
+	let start = 0;
+	for (let at = 0; at < cls.length; at++) {
+		const char = cls[at];
+		if (char === "[" || char === "(") depth++;
+		else if ((char === "]" || char === ")") && depth > 0) depth--;
+		else if (char === ":" && depth === 0) {
+			segments.push(cls.slice(start, at));
+			start = at + 1;
+		}
+	}
+	segments.push(cls.slice(start));
+	return segments;
+}
 //#endregion
-export { componentClassBase, componentCompositeClasses, componentLayerClass, componentMotionClasses, componentPropClasses, componentPropComposites, componentRuleClasses, forceModeAttribute, forceModeAttributeOf, forceModeProp, forceModePropGroup, forceModePropValue, forceModeProps, forceStateAttribute, inlineRuleComposites, isForceModeProp, kebabComponent, layerRoutedProps, modifierUtilitiesUsed, motionClassName, ruleCondition, splitStyleProps, stylePropClassBase, stylePropClassName, stylePropClasses, styleRuleMotionClasses };
+export { arbitraryClassName, arbitraryNeedsClass, classLeaf, classSelector, componentClassBase, componentCompositeClasses, componentLayerClass, componentMotionClasses, componentPropClasses, componentPropComposites, componentRuleClasses, forceModeAttribute, forceModeAttributeOf, forceModeProp, forceModePropGroup, forceModePropValue, forceModeProps, forceStateAttribute, inlineRuleComposites, isForceModeProp, kebabComponent, layerRoutedProps, modifierUtilitiesUsed, motionClassName, ruleCondition, splitStyleProps, splitVariants, stylePropClassBase, stylePropClassName, stylePropClasses, stylePropOwnClasses, styleRuleMotionClasses };

package/dist/framework/defineEntity.d.ts

@@ -192,6 +192,7 @@ GI extends GroupInputs = Record<never, never>> = Omit<RefSchema, 'extend'> & {
    * does call zod's `extend` on it.
    */
   extend<F2 extends ShapeOverride = Record<never, never>, G2 extends ShapeOverride = Record<never, never>, S2 extends UserSchemas = never>(overrides: {
+    prepareLinkedBody?: EntityKind['prepareLinkedBody'];
     fields?: F2;
     groupFields?: G2;
     subEntities?: Partial<Record<string, SubEntityClass | null>>;
@@ -353,7 +354,8 @@ declare function defineEntity<F extends FieldsSchema, G extends FieldsSchema = z
    * Declare it alongside `bulkOverlay` for a kind whose minted rows should stay editable; without it,
    * an edit to one has nowhere to land.
    */
-  bulkOverlayWrite?: (args: BulkOverlayWrite) => Record<string, unknown>;
+  bulkOverlayWrite?: (args: BulkOverlayWrite) => Record<string, unknown>; /** Adapt a pinned source body before linked validation. */
+  prepareLinkedBody?: EntityKind['prepareLinkedBody'];
   /**
    * Edges this kind's data implies by name rather than by ref, and how to rewrite one — the pair that
    * makes a record keyed by another kind's item names behave like a reference: reported by

package/dist/framework/defineEntity.js

@@ -27,7 +27,8 @@ const EXTENDABLE_KEYS = new Set([
 	"schemas",
 	"label",
 	"labelPlural",
-	"entityName"
+	"entityName",
+	"prepareLinkedBody"
 ]);
 /** Merge an override into the base's shape, key by key — using zod's real `extend`/`omit` on the
 *  plain object, where they are the right tools. A named key replaces or adds a field; `null`
@@ -122,6 +123,7 @@ function defineEntity(spec) {
 		bulkOverlay: spec.bulkOverlay,
 		bulkDirectives: spec.bulkDirectives,
 		bulkOverlayWrite: spec.bulkOverlayWrite,
+		prepareLinkedBody: spec.prepareLinkedBody,
 		nameEdges: spec.nameEdges,
 		styleBags: spec.styleBags,
 		rewriteName: spec.rewriteName,

package/dist/framework/inline-sources.d.ts

@@ -13,9 +13,9 @@ import { Ref } from "./utils/refs.js";
  * to become ours must not keep pointing anywhere.
  */
 /**
- * What to do with a sourced ref that names something with no value — a component, a `file`, a style
- * property. There is nothing to substitute for one, so it needs its own answer, and which answer
- * depends on whether the pin survives the edit.
+ * What to do with a sourced identity ref — a modifier, component, `file`, or style property. There is
+ * no token value to substitute for one, so it needs its own answer, and which answer depends on
+ * whether the pin survives the edit.
  *
  * **It survives** for publishing and for reading a repo-local chain. The seam stays, so the ref stays:
  * `keepIdentityRefs`. A borrowed component's `file` has to keep naming the system that owns the

package/dist/framework/inline-sources.js

@@ -40,7 +40,7 @@ function inlineSourcedRefs(value, config, slug, options) {
 		const target = config.resolveRef(value);
 		const body = target?.toJSON();
 		if (!target && !declaresGroup(owner, value)) rejectData(`Cannot inline "${value.__ref}": "${source}" has no ${kindOf(value)} at "${pathOf(value)}". A pin is exact, so this is a ref into a version that does not declare it.`);
-		if (body?.value === void 0) {
+		if (kindOf(value) !== "token" || body?.value === void 0) {
 			if (options?.keepIdentityRefs) return value;
 			const adopted = options?.adopted?.get(entityRefOf(value.__ref));
 			if (adopted !== void 0) return rewriteRefs(value, entityRefOf(value.__ref), adopted);