@yahoo/uds-create-config 2.44.0 → 3.0.0

package/dist/migrations/2.0.0/v1-artifact.js

@@ -0,0 +1,1018 @@
+import { isRef, pathOf, splitRef } from "../../framework/utils/refs.js";
+import { alpha, darken, lighten, mix } from "../../entities/system/color.js";
+import { isCssProperty, kebabCase } from "../../css/values.js";
+import { Composite } from "../../entities/system/Composite.js";
+import { Modifier } from "../../entities/system/Modifier.js";
+import { StyleProperty } from "../../entities/system/StyleProperty.js";
+import { Component, canonicalWhen } from "../../entities/system/Component.js";
+import { Icon } from "../../entities/system/Icon.js";
+import { stableStringify } from "../../framework/utils/content-key.js";
+import { CanvasRole } from "../../entities/system/CanvasRole.js";
+import { Font } from "../../entities/system/Font.js";
+import { GlobalStyle, globalStyleName } from "../../entities/system/GlobalStyle.js";
+import { Guidance } from "../../entities/system/Guidance.js";
+import { Motion } from "../../entities/system/Motion.js";
+import { Token, overrideKey } from "../../entities/system/Token.js";
+import { danglingLocalRefs } from "../../framework/ref-integrity.js";
+import { parseRawCss } from "./raw-css.js";
+import { System } from "../../configs/system.js";
+//#region src/migrations/2.0.0/v1-artifact.ts
+/**
+* The v1 → config-v2 reader, for `uds migrate` and nothing else.
+*
+* A v1 system's authoring vocabulary is gone, so its `uds.config.ts` cannot be imported — but what
+* that config DESCRIBED survives in the flat `config.json` its last build wrote. This reads that
+* artifact into a config-v2 `System`, which `uds migrate` then renders back out as v2 source.
+*
+* **Runtime code must not come through here.** Every stored artifact is the config-v2 wire form and
+* `Config.fromJSON` is the one door to it; this exists for the one-time port of a repo that never
+* built on the new version. It is also best-effort in a way a runtime path must not be: the few old
+* shapes config-v2 doesn't model (color expressions, component `preview`) pass through or drop
+* rather than failing the load, so a config read through here is the
+* starting point for a migration, not a faithful copy of a system.
+*/
+/**
+* Default authoring guidance seeded onto a system that declares none — the stop-gap that fills
+* the "guidance gap" until a design system authors its own `guidance` entities. These are the
+* design-quality rules whose absence the ai-eval judges flagged; the pipeline derives them via
+* `ctx.guidance()`, keeping guidance on the system rather than hardcoded in the flow.
+*/
+const DEFAULT_GUIDANCE = {
+	completeness: Guidance.group({
+		label: "Completeness",
+		description: "How much of the request to build, and with what content.",
+		items: { "build-everything": Guidance.item({ text: ["Build the ENTIRE request — every section and item, with REALISTIC content (real labels, numbers, names). Never leave empty rows/containers or use placeholders like \"Product Name\"."] }) }
+	}),
+	hierarchy: Guidance.group({
+		label: "Hierarchy",
+		description: "How to rank elements by importance.",
+		items: { "size-text-by-role": Guidance.item({ text: ["Size text by role (page title > section heading > body > caption); never make a label larger than its value."] }) }
+	}),
+	semantics: Guidance.group({
+		label: "Semantics",
+		description: "How to match components and prop values to intent.",
+		items: { "match-props-to-intent": Guidance.item({ text: ["Pick the right component for each job and match prop values to INTENT, using the names the reference lists: the emphasis/primary variant for the main action, the destructive variant for a delete, and contrasting colors for positive vs negative figures."] }) }
+	}),
+	accessibility: Guidance.group({
+		label: "Accessibility",
+		description: "The bar every generated design is held to.",
+		items: {
+			"contrast-in-every-mode": Guidance.item({ text: ["Target WCAG 2.1 AA contrast in every color mode. On colored or photographic backgrounds use neutral text roles, and check the pair each token RESOLVES to per mode rather than how its base value looks."] }),
+			"protect-image-text": Guidance.item({ text: ["When the request places copy over a background image or layered media, keep the overlay. Make the text fully opaque and put a strong enough surface, gradient, or scrim behind it to reach WCAG 2.1 AA."] })
+		}
+	})
+};
+/** Markers that compute a colour rather than name one — a VALUE in config-v2, not a ref. */
+const COLOR_OPS = new Set([
+	"darken",
+	"lighten",
+	"alpha",
+	"mix"
+]);
+/** Gradient markers, by the CSS function each names. */
+const GRADIENTS = {
+	"linear-gradient": "linear",
+	"radial-gradient": "radial",
+	"conic-gradient": "conic"
+};
+/** Old marker `{ __kind, ref }` → the config-v2 ref kind that fronts it. */
+const REF_KIND = {
+	token: "token",
+	tokenGroup: "token",
+	styleProperty: "style-property",
+	composite: "composite",
+	assetGroup: "font",
+	component: "component",
+	mode: "mode"
+};
+/** A converted element that points at another component (`{ __ref: 'component:Box' }`) rather
+*  than naming a native tag. */
+const isConfigRef = (v) => typeof v === "object" && v !== null && "__ref" in v;
+const isMarker = (v) => typeof v === "object" && v !== null && "__kind" in v;
+/** Deep-convert a value: old `{ __kind:'token', ref }` markers become `{ __ref:'token:…' }`,
+*  objects/arrays recurse, primitives pass through. Handles style bags, variant maps, etc. */
+/**
+* Asset library name → the config-v2 kind that fronts it, for the config being loaded.
+*
+* Module-scoped because `convertValue` is called from a dozen places and threading a resolver
+* through all of them would obscure them; a load is synchronous, so the map is only ever the one in
+* flight. Without it every `assetGroup('icons')` marker resolved to `font:icons` — a slot that
+* accepts an ICON library, typed as a font.
+*/
+let assetKinds = {};
+/**
+* What the reader could not carry, by a fixed code so a caller can tell an intended drop from a loss.
+* `loss` is the code's verdict: a hole never held anything, where an unrecognized marker did.
+*/
+const V1_DIAGNOSTIC_CODES = {
+	/** A prop the artifact stores as `null`: a declaration that named no marker. */
+	"prop-hole-dropped": { loss: false },
+	/** A prop marker config-v2 has no type for. */
+	"prop-unrecognized": { loss: true },
+	/** A layer value that is neither a tag, a component ref, nor an inline component body. */
+	"layer-unrecognized": { loss: true },
+	/** A style bag addressed to a layer the component does not declare. */
+	"style-layer-undeclared": { loss: true },
+	/** A component that took content without declaring `children`; the slot is declared for it. */
+	"children-slot-inferred": { loss: false },
+	/** CSS whose syntax or ordered entries cannot be represented by a global style. */
+	"raw-css-unparsed": { loss: true },
+	/** A selector modifier v1 also guarded with a media query; a v2 modifier activates one way. The
+	*  guard only kept `:hover` off touch devices, which is accepted rather than carried. */
+	"modifier-media-dropped": { loss: false },
+	/** A component with layers and no `root`; the first layer is renamed, and the render must follow. */
+	"root-layer-renamed": { loss: true },
+	/** A ref the artifact spells to something it never declares; v1 emitted nothing, v2 refuses. A
+	*  loss when carried; a note under `dropUnresolved`, since what is removed painted nothing. */
+	"ref-unresolved": { loss: true },
+	/** A style bag key that is neither a style prop, a CSS property, nor a prop of the layer's
+	*  element. v1 wrote it as a declaration no browser parses, so it painted nothing. */
+	"style-key-unrecognized": { loss: false }
+};
+/** Module-scoped for the same reason `assetKinds` is: one load is in flight at a time. */
+let diagnose = () => {};
+function report(code, path, detail) {
+	diagnose({
+		code,
+		path,
+		detail,
+		loss: V1_DIAGNOSTIC_CODES[code].loss
+	});
+}
+/**
+* The config-v2 kind an asset marker fronts, or `undefined` when it isn't one.
+*
+* v1 had two spellings for the same split-in-two model: `assetGroup` names a whole LIBRARY (its ref
+* IS the library), `asset` names one MEMBER of one (`fonts/yas`), and neither says which class it
+* holds — that lived on the group's `assetKind`. So both resolve through the same lookup, differing
+* only in where the library name sits in the ref.
+*
+* The member spelling is what a `font-family` token's value used, and it had no entry at all: it
+* fell through to `REF_KIND[undefined]`, converted to `undefined`, and took the token's required
+* `value` with it — so a system whose fonts are referenced by token, which is every system that
+* declares fonts seriously, was REJECTED at load rather than loaded without the edge.
+*/
+function assetLibraryKind(value) {
+	if (!value.ref) return void 0;
+	if (value.__kind === "assetGroup") return assetKinds[value.ref] ?? REF_KIND.assetGroup;
+	if (value.__kind === "asset") {
+		const library = value.ref.slice(0, value.ref.indexOf("/"));
+		return assetKinds[library] ?? REF_KIND.assetGroup;
+	}
+}
+/**
+* A v1 colour-function marker as a config-v2 derived colour.
+*
+* Built through the AUTHORING HELPERS rather than as object literals, so there's one constructor for
+* the stored shape and this can't drift from what a person writing `darken(...)` produces. The old
+* model spelled shading and blending as separate markers with different amount units (`darken`'s 10
+* is a percent, `mix`'s is the string `'20%'`, `alpha`'s is a 0–1 fraction); the helpers take each
+* unit as authored and normalize, so that knowledge lives in one place too.
+*
+* The result is validated on the way into the store like any other body, so a conversion that
+* produced the wrong shape fails here instead of surfacing as a colour that doesn't render.
+*/
+function convertColor(marker) {
+	const raw = marker;
+	const amount = typeof raw.amount === "string" ? Number.parseFloat(raw.amount) : raw.amount ?? 0;
+	if (marker.__kind === "mix") return mix(convertValue(raw.from), convertValue(raw.to), amount, raw.colorSpace ?? "oklch");
+	const color = convertValue(raw.color);
+	if (marker.__kind === "alpha") return alpha(color, amount);
+	return marker.__kind === "lighten" ? lighten(color, amount) : darken(color, amount);
+}
+/**
+* The CSS a bare number meant for v1's grid props. Their `transform` lived in source, which the
+* artifact never recorded, so the number is all that arrived.
+*/
+const GRID_NUMERIC_CSS = {
+	"grid-template-columns": (n) => `repeat(${n}, minmax(0, 1fr))`,
+	"grid-template-rows": (n) => `repeat(${n}, minmax(0, 1fr))`,
+	"grid-column": (n) => `span ${n} / span ${n}`,
+	"grid-row": (n) => `span ${n} / span ${n}`
+};
+/** A style prop's values, with each bare number aliased to the CSS v1 painted for it. */
+function withGridAliases(properties, values) {
+	const css = properties.length === 1 ? GRID_NUMERIC_CSS[properties[0]] : void 0;
+	if (!css) return values;
+	return values.map((entry) => typeof entry === "number" ? {
+		alias: entry,
+		value: css(entry)
+	} : entry);
+}
+/**
+* v1 resolved a leaf two entries offered by the LAST entry; v2 by the first. A literal listed after a
+* group holding a token of the same leaf (`[tokenGroup('letterSpacing'), 'normal']` with
+* `letterSpacing/normal`) painted the literal, so it moves ahead of that group.
+*/
+function withV1Precedence(values, tokenRecord) {
+	const out = [];
+	for (const entry of values) {
+		const leaf = typeof entry === "string" || typeof entry === "number" ? String(entry) : void 0;
+		const shadowed = leaf === void 0 ? -1 : out.findIndex((prior) => isRef(prior) && `${pathOf(prior)}/${leaf}` in tokenRecord);
+		if (shadowed === -1) out.push(entry);
+		else out.splice(shadowed, 0, entry);
+	}
+	return out;
+}
+function convertValue(value) {
+	if (isMarker(value)) {
+		if (COLOR_OPS.has(value.__kind)) return convertColor(value);
+		const gradientKind = GRADIENTS[value.__kind];
+		if (gradientKind) {
+			const raw = value;
+			return {
+				gradient: gradientKind,
+				...raw.angle ? { angle: raw.angle } : {},
+				stops: (raw.stops ?? []).map((stop) => ({
+					color: convertValue(stop.color),
+					...stop.at ? { at: stop.at } : {}
+				})),
+				...raw.interpolation ? { space: raw.interpolation } : {},
+				...raw.repeating ? { repeating: raw.repeating } : {}
+			};
+		}
+		const kind = value.ref ? assetLibraryKind(value) ?? REF_KIND[value.__kind] : REF_KIND[value.__kind];
+		if (kind && value.ref) return { __ref: `${kind}:${value.ref}` };
+		return;
+	}
+	if (Array.isArray(value)) return value.map(convertValue);
+	if (value && typeof value === "object") {
+		const out = {};
+		for (const [key, nested] of Object.entries(value)) {
+			const converted = convertValue(nested);
+			if (converted !== void 0) out[key] = converted;
+		}
+		return out;
+	}
+	return value;
+}
+/** An old `fallback` (a comma list OR an array) → the list config-v2 stores. */
+function fallbackList(fallback) {
+	if (Array.isArray(fallback)) return fallback.filter((f) => f.length > 0);
+	if (typeof fallback === "string") return fallback.split(",").map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+	return [];
+}
+/**
+* Old `declarations[]` → config-v2's keyed `files`. Every entry converts, not just the first: a
+* family's weights live in its files, and keeping one dropped the rest.
+*
+* Field naming differs by source (an upload writes `url`, the v3 declaration map writes
+* `src`/`fontWeight`/`fontStyle`), so both spellings are read. The key prefers the PostScript name —
+* it identifies the exact file — then a `<weight>-<style>` slug, then the index, so it stays
+* meaningful and stable rather than positional.
+*/
+function convertFontFiles(declarations) {
+	const files = {};
+	declarations.forEach((declaration, index) => {
+		const src = declaration.src ?? declaration.url;
+		if (!src) return;
+		const weight = declaration.weight ?? declaration.fontWeight;
+		const style = declaration.style ?? declaration.fontStyle;
+		let key = declaration.postscriptName;
+		if (!key && weight !== void 0) key = style ? `${weight}-${style}` : String(weight);
+		files[key ?? String(index)] = {
+			src,
+			...declaration.format !== void 0 ? { format: declaration.format } : {},
+			...weight !== void 0 ? { weight } : {},
+			...style !== void 0 ? { style } : {},
+			...declaration.postscriptName !== void 0 ? { postscriptName: declaration.postscriptName } : {}
+		};
+	});
+	return files;
+}
+/**
+* Old modes and modifiers as one `modifier` record.
+*
+* A mode option becomes an item under a group typed `mode`, and the old modifier that rode it is
+* absorbed into that item: the option lands at the MODIFIER's name, since that is what every bag key
+* and override in the old config spells. A fragment modifier lands under a `state` group, except a
+* pseudo-element or a child combinator, which addresses a part of the element and stays plain.
+*/
+function buildModifiers(studio) {
+	const record = {};
+	const optionNames = /* @__PURE__ */ new Map();
+	for (const [key, def] of Object.entries(studio.modifiers ?? {})) {
+		const selector = def.selector;
+		if (isMarker(selector) && selector.__kind === "mode" && selector.ref) optionNames.set(selector.ref, modifierName(key));
+	}
+	for (const [group, options] of Object.entries(studio.modes ?? {})) {
+		record[group] = Modifier.group({
+			type: "mode",
+			label: group
+		});
+		for (const [option, def] of Object.entries(options)) {
+			const leaf = optionNames.get(`${group}/${option}`) ?? option;
+			record[`${group}/${leaf}`] = def.css ? Modifier.item({
+				type: "selector",
+				value: def.css
+			}) : Modifier.item({
+				type: "media-query",
+				value: def.media ?? ""
+			});
+		}
+	}
+	let stateGroup = false;
+	for (const [key, def] of Object.entries(studio.modifiers ?? {})) {
+		const selector = def.selector;
+		if (isMarker(selector) && selector.__kind === "mode") continue;
+		const value = typeof selector === "string" ? selector : String(selector);
+		const name = modifierName(key);
+		if (def.media) report("modifier-media-dropped", name, `v1 wrapped \`${value}\` in \`@media ${def.media}\`; a v2 modifier is a selector or a query, not both`);
+		if (addressesPart(value)) {
+			record[name] = Modifier.item({
+				type: "selector",
+				value
+			});
+			continue;
+		}
+		if (!stateGroup) {
+			record.state = Modifier.group({
+				type: "state",
+				label: "State"
+			});
+			stateGroup = true;
+		}
+		record[`state/${name}`] = Modifier.item({
+			type: "selector",
+			value
+		});
+	}
+	return record;
+}
+/** A pseudo-element or a child/sibling combinator styles a part of the element rather than the
+*  element under a condition, so it is a plain modifier rather than a state. */
+const addressesPart = (value) => /^\s*(::|>|~|\+)/.test(value);
+/** A modifier's config-v2 name. Old configs key modifiers by their style-bag form (`_dark`), but
+*  the underscore is bag SYNTAX, not identity — so the entity is `dark`, which is what a ref points
+*  at and what codegen already looks up after stripping a bag key's `_`. */
+const modifierName = (key) => key.replace(/^_/, "");
+/**
+* A token body: base value + `_<modifier>` overrides folded into `overrides`, each naming the
+* modifier it applies under. Whether that modifier activates by wrapping (a mode) or by composing
+* a selector is the MODIFIER's business, so this needs no mode lookup of its own.
+*
+* An old override may NEST — `_ocean: { value: '#0e7490', _dark: '#22d3ee' }` is one value for the
+* ocean theme and another for ocean-and-dark-together. The nesting was v1 shorthand for a compound
+* condition, which config-v2 spells as an override naming both modifiers in `on`, keyed by the pair.
+*/
+function buildTokenBody(raw) {
+	const body = {};
+	const overrides = {};
+	const put = (names, value) => {
+		const on = names.length === 1 ? Modifier.ref(names[0]) : names.map((name) => Modifier.ref(name));
+		overrides[overrideKey(on)] = {
+			on,
+			value: convertValue(value)
+		};
+	};
+	for (const [key, value] of Object.entries(raw)) {
+		if (key === "value" || key === "type") {
+			body[key] = convertValue(value);
+			continue;
+		}
+		if (!key.startsWith("_")) continue;
+		const name = modifierName(key);
+		if (!isOverrideBlock(value)) {
+			put([name], value);
+			continue;
+		}
+		if ("value" in value) put([name], value.value);
+		for (const [innerKey, innerValue] of Object.entries(value)) {
+			if (!innerKey.startsWith("_")) continue;
+			put([name, modifierName(innerKey)], innerValue);
+		}
+	}
+	if (Object.keys(overrides).length > 0) body.overrides = overrides;
+	return body;
+}
+/**
+* An override written as a BLOCK — `{ value }`, `{ _dark }`, or both — rather than as the value
+* itself. A token value is a literal, a ref or a computed-colour marker, so an object carrying
+* `value` or a `_<modifier>` key is the block form and never a value that merely looks like one.
+*/
+function isOverrideBlock(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	if (isMarker(value) || isConfigRef(value)) return false;
+	return Object.keys(value).some((key) => key === "value" || key.startsWith("_"));
+}
+/** A v1 layer written as a component body with no marker: `{ layers, props?, defaultProps? }`. */
+function isInlineComponent(layer) {
+	return typeof layer === "object" && layer !== null && !isMarker(layer) && typeof layer.layers === "object";
+}
+/** The v1 component body a layer renders, or `undefined` for a tag. */
+function componentOfLayer(layer, components) {
+	if (isInlineComponent(layer)) return layer;
+	if (isMarker(layer) && layer.__kind === "component" && layer.ref) return components[layer.ref];
+}
+/** The v1 declaration of `prop` on `body`, following `extendsFrom` since the v1 build flattened it. */
+function v1PropOf(body, prop, components, seen = /* @__PURE__ */ new Set()) {
+	const own = body.props?.[prop];
+	if (own !== void 0 || seen.has(body)) return own;
+	const parent = typeof body.extendsFrom === "string" ? components[body.extendsFrom] : void 0;
+	if (!parent) return void 0;
+	return v1PropOf(parent, prop, components, seen.add(body));
+}
+/**
+* Whether a v1 route lands on content, decided from the artifact: the config's own `routesContent`
+* asks a registered config, and every component here registers in one call. A tag carries content
+* only through `children`; a component carries it through a prop it declares as a slot.
+*/
+function routeCarriesContent(ctx, layer, into) {
+	const target = componentOfLayer(ctx.layers[layer], ctx.components);
+	if (!target) return into === "children";
+	const routed = v1PropOf(target, into, ctx.components);
+	if (routed === void 0) return into === "children";
+	return isMarker(routed) && routed.__kind === "slot";
+}
+function convertProp(name, prop, ctx) {
+	switch (prop.__kind) {
+		case "slot": {
+			const text = prop.__valueType === "string";
+			const accepts = prop.__accepts?.length ? prop.__accepts.map((entry) => typeof entry === "string" ? Component.ref(entry) : convertValue(entry)) : void 0;
+			if (prop.layer) {
+				const layer = String(prop.layer);
+				const into = typeof prop.layerProp === "string" ? prop.layerProp : "children";
+				const out = {
+					type: "forward",
+					target: { __ref: `layer:${layer}` },
+					into
+				};
+				if (routeCarriesContent(ctx, layer, into)) {
+					if (text) out.text = true;
+					if (accepts) out.accepts = accepts;
+				}
+				return {
+					decl: out,
+					rules: []
+				};
+			}
+			const out = { type: "slot" };
+			if (text) out.text = true;
+			if (accepts) out.accepts = accepts;
+			return {
+				decl: out,
+				rules: []
+			};
+		}
+		case "variant": {
+			const values = prop.values;
+			if (Array.isArray(values)) return {
+				decl: {
+					type: "variant",
+					value: values.map(String)
+				},
+				rules: []
+			};
+			const map = values ?? {};
+			return {
+				decl: {
+					type: "variant",
+					value: Object.keys(map)
+				},
+				rules: Object.entries(map).map(([value, bags]) => ({
+					when: { [name]: value },
+					layers: bagsToLayers(bags)
+				}))
+			};
+		}
+		case "styleProp":
+		case "styleProperty": return {
+			decl: {
+				type: "styleProperty",
+				value: { __ref: `style-property:${prop.ref}` }
+			},
+			rules: []
+		};
+		case "composite": return {
+			decl: {
+				type: "composite",
+				value: { __ref: `composite:${prop.ref}` }
+			},
+			rules: []
+		};
+		case "motion": return {
+			decl: { type: "motion" },
+			rules: []
+		};
+		case "boolean": {
+			const branches = prop.values ?? {};
+			return {
+				decl: { type: "boolean" },
+				rules: Object.entries(branches).map(([branch, bags]) => ({
+					when: { [name]: branch === "true" },
+					layers: bagsToLayers(bags)
+				}))
+			};
+		}
+		case "string":
+		case "number": return {
+			decl: { type: prop.__kind },
+			rules: []
+		};
+		default:
+			report("prop-unrecognized", `${ctx.name}/${name}`, `prop marker ${JSON.stringify(prop.__kind)} has no config-v2 type`);
+			return { rules: [] };
+	}
+}
+/** The per-layer bags an old variant value / boolean branch carried, as a rule's `layers`. */
+function bagsToLayers(raw) {
+	const converted = convertValue(raw);
+	if (!converted || typeof converted !== "object") return {};
+	return converted;
+}
+/** An old layer value (`{ __kind:'tag'|'component', ref }`) → the element it names. A layer IS
+*  its element now, so there's nothing to wrap. `undefined` for an unrecognized marker. */
+function convertLayer(layer) {
+	if (typeof layer === "string") return layer;
+	if (!isMarker(layer)) return void 0;
+	if (layer.__kind === "tag") return layer.ref;
+	if (layer.__kind === "component") return { __ref: `component:${layer.ref}` };
+}
+/**
+* A v1 component could declare layers and no `root`; v2 requires one, since it is where unmodelled
+* props land. The first declared layer takes the name, in every place the body spells it — layers,
+* bags, routes — and the rename is a loss because the render still says `layers.<old>`.
+*/
+function withRootLayer(name, raw) {
+	const layers = raw.layers;
+	if (!layers || "root" in layers) return raw;
+	const first = Object.keys(layers)[0];
+	if (first === void 0) return raw;
+	report("root-layer-renamed", `${name}/${first}`, `declares no root layer; \`${first}\` is renamed to \`root\`, and the render's \`layers.${first}\` has to follow`);
+	const renameKeys = (bags) => {
+		if (!bags || typeof bags !== "object" || Array.isArray(bags)) return bags;
+		return Object.fromEntries(Object.entries(bags).map(([key, value]) => [key === first ? "root" : key, value]));
+	};
+	const props = Object.fromEntries(Object.entries(raw.props ?? {}).map(([prop, decl]) => {
+		if (!decl) return [prop, decl];
+		const next = { ...decl };
+		if (next.layer === first) next.layer = "root";
+		if (next.values && typeof next.values === "object" && !Array.isArray(next.values)) next.values = Object.fromEntries(Object.entries(next.values).map(([value, bags]) => [value, renameKeys(bags)]));
+		return [prop, next];
+	}));
+	return {
+		...raw,
+		layers: renameKeys(layers),
+		...raw.props ? { props } : {},
+		...raw.base ? { base: renameKeys(raw.base) } : {},
+		...Array.isArray(raw.compoundProps) ? { compoundProps: raw.compoundProps.map((entry) => ({
+			...entry,
+			layers: renameKeys(entry.layers)
+		})) } : {}
+	};
+}
+/**
+* An old component → the three steps: `layers` (name → element), `props` (the public API), and
+* `styles` (condition → what to apply). Old config spread its styling across four shapes that
+* differ only in condition — a top-level `base`, a variant value's bags, a boolean branch's bags,
+* and `compoundProps` — so the conversion funnels all four into one rule collection keyed by
+* `canonicalWhen`. Two sources landing on the same condition merge per layer rather than
+* clobbering, which is how a `base` and a `compoundProps` entry on the same layer used to stack.
+*/
+function convertComponent({ name, raw: given, parent, components }) {
+	const out = {};
+	const parts = {};
+	const parentName = parent && typeof given.extendsFrom === "string" ? given.extendsFrom : void 0;
+	const raw = parentName ? given : withRootLayer(name, given);
+	const rawLayers = raw.layers ?? {};
+	const layers = {};
+	for (const [layerName, layer] of Object.entries(rawLayers)) {
+		if (isInlineComponent(layer)) {
+			const path = `${name}/${name.slice(name.lastIndexOf("/") + 1)}${layerName.charAt(0).toUpperCase()}${layerName.slice(1)}`;
+			const hoisted = convertComponent({
+				name: path,
+				raw: layer,
+				components
+			});
+			parts[path] = hoisted.body;
+			Object.assign(parts, hoisted.parts);
+			layers[layerName] = Component.ref(path);
+			continue;
+		}
+		const element = convertLayer(layer);
+		if (element !== void 0) {
+			layers[layerName] = element;
+			continue;
+		}
+		report("layer-unrecognized", `${name}/${layerName}`, `layer value ${JSON.stringify(layer)} names no tag or component`);
+	}
+	if (parentName) layers.root = Component.ref(parentName);
+	if (Object.keys(layers).length > 0) out.layers = layers;
+	const ctx = {
+		name,
+		layers: rawLayers,
+		components
+	};
+	const drafts = [];
+	const rawProps = raw.props;
+	const parentProps = parent?.props ?? {};
+	const props = {};
+	for (const [propName, prop] of Object.entries(rawProps ?? {})) {
+		if (!prop) {
+			report("prop-hole-dropped", `${name}/${propName}`, "declared with no marker; nothing to carry");
+			continue;
+		}
+		if (parentName && propName in parentProps && stableStringify(prop) === stableStringify(parentProps[propName])) continue;
+		const { decl, rules } = convertProp(propName, prop, ctx);
+		if (decl) props[propName] = decl;
+		drafts.push(...rules);
+	}
+	if (parentName) {
+		const parentCtx = {
+			name: parentName,
+			layers: parent?.layers ?? {},
+			components
+		};
+		for (const [propName, prop] of Object.entries(parentProps)) {
+			if (!prop || rawProps?.[propName]) continue;
+			if (convertProp(propName, prop, parentCtx).decl) props[propName] = null;
+		}
+	}
+	if (rawProps || parentName) out.props = props;
+	const layerNames = Object.keys(layers);
+	const onlyElement = layers[layerNames[0]];
+	if (parentName) out.forwards = { root: "*" };
+	else if (layerNames.length === 1 && isConfigRef(onlyElement)) out.forwards = { [layerNames[0]]: "*" };
+	if (raw.base) drafts.unshift({
+		when: null,
+		layers: bagsToLayers(raw.base)
+	});
+	const compound = raw.compoundProps ?? [];
+	for (const entry of compound) drafts.push({
+		when: entry.when ?? null,
+		layers: bagsToLayers(entry.layers)
+	});
+	const styles = {};
+	for (const draft of drafts) {
+		const key = canonicalWhen(draft.when);
+		const targeted = {};
+		for (const [layerName, bag] of Object.entries(draft.layers)) {
+			if (layerName in layers) {
+				targeted[layerName] = bag;
+				continue;
+			}
+			report("style-layer-undeclared", `${name}/${key}/${layerName}`, `a style bag targets layer "${layerName}", which the component does not declare`);
+		}
+		if (Object.keys(targeted).length === 0) continue;
+		const existing = styles[key];
+		if (!existing) {
+			styles[key] = {
+				when: draft.when,
+				layers: targeted
+			};
+			continue;
+		}
+		for (const [layerName, bag] of Object.entries(targeted)) existing.layers[layerName] = {
+			...existing.layers[layerName],
+			...bag
+		};
+	}
+	if (Object.keys(styles).length > 0) out.styles = styles;
+	if (raw.defaultProps) out.defaultProps = convertValue(raw.defaultProps);
+	const meta = raw.metadata;
+	if (meta?.label) out.label = meta.label;
+	if (meta?.description) out.description = meta.description;
+	return {
+		body: out,
+		parts
+	};
+}
+/**
+* A v1 render took React's own `children` without declaring it, and the artifact still shows where
+* that happened: another component routes content into the layer, or the component's own preview
+* passes `children`. v2 refuses both against an undeclared prop, so the slot is declared.
+*/
+function inferChildrenSlots(record, raw) {
+	const bodies = record;
+	const evidence = /* @__PURE__ */ new Map();
+	const cite = (target, why) => {
+		if (!(target in bodies)) return;
+		if (bodies[target]?.props && "children" in bodies[target].props) return;
+		evidence.set(target, [...evidence.get(target) ?? [], why]);
+	};
+	for (const [name, body] of Object.entries(bodies)) {
+		for (const [prop, decl] of Object.entries(body.props ?? {})) {
+			if (decl?.type !== "forward" || !isConfigRef(decl.target)) continue;
+			if (decl.into !== "children") continue;
+			const layer = decl.target.__ref.slice(6);
+			const element = body.layers?.[layer];
+			if (!isConfigRef(element)) continue;
+			cite(element.__ref.slice(10), `${name}.${prop} routes into it`);
+		}
+		const preview = raw[name]?.preview;
+		if (preview?.defaultProps && "children" in preview.defaultProps) cite(name, "its preview passes children");
+	}
+	for (const [target, why] of evidence) {
+		const body = bodies[target];
+		body.props = {
+			...body.props,
+			children: { type: "slot" }
+		};
+		const shown = why.slice(0, 3).join("; ");
+		const more = why.length > 3 ? `; and ${why.length - 3} more` : "";
+		report("children-slot-inferred", `${target}/children`, `declared no children prop, but ${shown}${more}`);
+	}
+}
+/**
+* The components a v1 artifact marks as parts of another, as the renames that move each to its
+* owner path.
+*
+* v1 recorded the edge twice, `subcomponentOf: 'Card'` on the part and `subcomponents: ['Header']`
+* on the owner, and either spelling alone counts. config-v2 has no field for it: `Card/Header` is a
+* part of `Card` by being named that way. A part of a part lands under the owner's own owner path.
+*
+* The list is what a canvas conversion hands to `rewriteSpecRefs`, so a node whose type still names
+* the bare component follows it to the owner path. `convert` runs the same list as component renames.
+*/
+function v1ComponentRenames(studio) {
+	const components = studio.components ?? {};
+	const ownerOf = {};
+	for (const [name, raw] of Object.entries(components)) {
+		const declared = raw.subcomponentOf;
+		if (typeof declared === "string" && declared in components) ownerOf[name] = declared;
+		const parts = Array.isArray(raw.subcomponents) ? raw.subcomponents : [];
+		for (const part of parts) {
+			if (typeof part !== "string") continue;
+			const bare = part.slice(part.lastIndexOf("/") + 1);
+			if (bare !== name && bare in components) ownerOf[bare] ??= name;
+		}
+	}
+	const ownedPath = (name, seen) => {
+		const owner = ownerOf[name];
+		if (!owner || seen.has(name)) return name;
+		return `${ownedPath(owner, new Set(seen).add(name))}/${name}`;
+	};
+	return Object.keys(ownerOf).map((from) => ({
+		kind: "component",
+		from,
+		to: ownedPath(from, /* @__PURE__ */ new Set())
+	}));
+}
+/**
+* Read a v1 build artifact as a config-v2 `System`.
+*
+* One shape in, and only one: the flat pre-cutover bag. A config-v2 artifact does not come through
+* here — `Config.fromJSON` reads it directly, and it refuses this shape outright rather than
+* hydrating an empty config from fields it cannot see.
+*/
+function loadV1Artifact(studio, options = {}) {
+	diagnose = options.onDiagnostic ?? (() => {});
+	try {
+		return convert(studio, options);
+	} finally {
+		diagnose = () => {};
+	}
+}
+/** The pre-cutover conversion. */
+function convert(studio, options) {
+	const settings = {
+		...studio.buildOptions?.registryDir ? { build: { registryDir: studio.buildOptions.registryDir } } : {},
+		css: {
+			prefix: studio.prefix ?? "uds",
+			...studio.buildOptions?.cssScope ? { scope: studio.buildOptions.cssScope } : {},
+			...studio.preflight !== void 0 ? { preflight: studio.preflight } : {}
+		}
+	};
+	assetKinds = Object.fromEntries(Object.entries(studio.assetGroups ?? {}).map(([name, meta]) => [name, meta.assetKind === "font" ? "font" : "icon"]));
+	const modifierRecord = buildModifiers(studio);
+	const tokenRecord = {};
+	for (const [group, meta] of Object.entries(studio.tokenGroups ?? {})) {
+		tokenRecord[group] = Token.group({
+			label: meta.label,
+			description: meta.description
+		});
+		for (const [tokenPath, raw] of Object.entries(meta.tokens ?? {})) tokenRecord[`${group}/${tokenPath}`] = Token.item(buildTokenBody(raw));
+	}
+	for (const [path, raw] of Object.entries(studio.tokens ?? {})) tokenRecord[path] = Token.item(buildTokenBody(raw));
+	const stylePropRecord = {};
+	for (const [name, sp] of Object.entries(studio.styleProps ?? {})) {
+		const properties = Array.isArray(sp.cssProperty) ? [...sp.cssProperty] : [sp.cssProperty];
+		stylePropRecord[name] = StyleProperty.item({
+			properties,
+			values: sp.values ? withV1Precedence(withGridAliases(properties, convertValue(sp.values).map((entry) => typeof entry === "boolean" ? {
+				alias: entry,
+				value: String(entry)
+			} : entry)), tokenRecord) : void 0,
+			arbitrary: Boolean(sp.arbitrary),
+			...sp.classPrefix !== void 0 ? { classPrefix: sp.classPrefix } : {},
+			...sp.responsive !== void 0 ? { responsive: sp.responsive } : {},
+			label: sp.metadata?.label
+		});
+		const sibling = sp.opacityPair?.as ?? sp.opacityPair?.ref;
+		if (sibling) stylePropRecord[sibling] = StyleProperty.item({
+			properties: [],
+			values: sp.opacityPair?.values ? convertValue([sp.opacityPair.values]) : void 0,
+			arbitrary: false,
+			opacityOf: StyleProperty.ref(name)
+		});
+	}
+	const compositeRecord = {};
+	for (const [name, cs] of Object.entries(studio.compositeStyles ?? {})) {
+		compositeRecord[name] = Composite.group({
+			label: cs.label,
+			description: cs.description
+		});
+		for (const [level, styles] of Object.entries(cs.styles)) compositeRecord[`${name}/${level}`] = Composite.item({ styles: convertValue(styles) });
+	}
+	const motionRecord = {};
+	for (const [name, m] of Object.entries(studio.motion ?? {})) motionRecord[name] = Motion.item(convertValue(m));
+	const componentRecord = {};
+	for (const [group, meta] of Object.entries(studio.componentGroups ?? {})) componentRecord[group] = Component.group({
+		icon: meta.icon,
+		label: meta.label,
+		description: meta.description
+	});
+	const components = studio.components ?? {};
+	for (const [name, raw] of Object.entries(components)) {
+		const { body, parts } = convertComponent({
+			name,
+			raw,
+			parent: typeof raw.extendsFrom === "string" ? components[raw.extendsFrom] : void 0,
+			components
+		});
+		componentRecord[name] = body;
+		Object.assign(componentRecord, parts);
+	}
+	inferChildrenSlots(componentRecord, components);
+	const fontRecord = {};
+	const iconRecord = {};
+	for (const [group, meta] of Object.entries(studio.assetGroups ?? {})) {
+		if (meta.assetKind === "font") fontRecord[group] = Font.group({
+			version: meta.version,
+			label: meta.label
+		});
+		else iconRecord[group] = Icon.group({
+			version: meta.version,
+			sizes: meta.sizes,
+			variants: meta.variants,
+			...meta.component ? { component: Component.ref(meta.component) } : {},
+			label: meta.label
+		});
+		const members = meta.members;
+		if (Array.isArray(members)) for (const name of members) iconRecord[`${group}/${name}`] = Icon.item({});
+		else if (members) for (const [name, font] of Object.entries(members)) fontRecord[`${group}/${name}`] = Font.item({
+			fontFamily: font.fontFamily ?? name,
+			files: convertFontFiles(font.declarations ?? []),
+			...fallbackList(font.fallback).length > 0 ? { fallbackStack: fallbackList(font.fallback) } : {},
+			...font.deprecated !== void 0 ? { deprecated: font.deprecated } : {},
+			...font.isVariableFont !== void 0 ? { isVariableFont: font.isVariableFont } : {}
+		});
+	}
+	const canvasRoleRecord = {};
+	for (const [role, entries] of Object.entries(studio.canvasRoles ?? {})) canvasRoleRecord[role] = CanvasRole.item({ entries: entries.map((entry) => ({
+		component: Component.ref(entry.component),
+		...entry.default !== void 0 ? { default: entry.default } : {},
+		...entry.defaultProps ? { defaultProps: entry.defaultProps } : {}
+	})) });
+	const globalStyleRecord = {};
+	const globalStyleNames = /* @__PURE__ */ new Set();
+	for (const [selector, declarations] of Object.entries(studio.globalStyles ?? {})) {
+		const name = globalStyleName(selector, globalStyleNames);
+		globalStyleNames.add(name);
+		globalStyleRecord[name] = GlobalStyle.item({
+			selector,
+			declarations
+		});
+	}
+	const rawCss = Array.isArray(studio.rawCss) ? studio.rawCss : [studio.rawCss ?? ""];
+	for (const [index, css] of rawCss.entries()) {
+		const { rules, unparsed } = parseRawCss(css);
+		for (const statement of unparsed) report("raw-css-unparsed", `rawCss/${index}`, statement);
+		for (const { selector, declarations } of rules) {
+			const name = globalStyleName(selector, globalStyleNames);
+			globalStyleNames.add(name);
+			globalStyleRecord[name] = GlobalStyle.item({
+				selector,
+				declarations
+			});
+		}
+	}
+	declareRawCssKeys(componentRecord, stylePropRecord);
+	const records = {
+		globalStyles: globalStyleRecord,
+		canvasRoles: canvasRoleRecord,
+		modifiers: modifierRecord,
+		tokens: tokenRecord,
+		styleProps: stylePropRecord,
+		composites: compositeRecord,
+		motion: motionRecord,
+		components: componentRecord,
+		fonts: fontRecord,
+		icons: iconRecord
+	};
+	const renames = v1ComponentRenames(studio);
+	let config = assemble({
+		settings,
+		records,
+		renames
+	});
+	const dangling = danglingLocalRefs(config);
+	for (const { from, ref } of dangling) diagnose({
+		code: "ref-unresolved",
+		path: from,
+		detail: `refers to ${ref}, which the artifact does not declare${options.dropUnresolved ? "; dropped, since v1 emitted nothing for it" : ""}`,
+		loss: !options.dropUnresolved
+	});
+	if (options.dropUnresolved && dangling.length > 0) {
+		pruneDanglingRefs({
+			records,
+			dangling,
+			renames
+		});
+		config = assemble({
+			settings,
+			records,
+			renames
+		});
+	}
+	return config;
+}
+/** The registered config: every record, then parts moved under their owners, then default guidance. */
+function assemble({ settings, records, renames }) {
+	let config = new System().register({ settings }).register(records);
+	if (renames.length > 0) config = config.run(renames.map(({ from, to }) => ({
+		kind: "component",
+		operation: "rename",
+		path: from,
+		to
+	})));
+	if (config.list("guidance").length === 0) config = config.register({ guidance: DEFAULT_GUIDANCE });
+	return config;
+}
+/** Kind → the record `register` takes it under. Read at call time: `System` is a cycle away. */
+function recordOfKind() {
+	return Object.fromEntries(Object.entries(System.entities).map(([accessor, entity]) => [entity.kind, accessor]));
+}
+/**
+* Remove each dangling ref from the body that holds it, in place: a slot's `accepts` loses the
+* entry, a bag loses the key. The holder is named after the part renames, so the record key is the
+* name before them.
+*/
+function pruneDanglingRefs({ records, dangling, renames }) {
+	const before = new Map(renames.map(({ from, to }) => [to, from]));
+	const recordOf = recordOfKind();
+	for (const { from, ref } of dangling) {
+		const { kind, path } = splitRef(from);
+		const body = records[recordOf[kind] ?? ""]?.[before.get(path) ?? path];
+		if (body) removeRef(body, ref);
+	}
+}
+function removeRef(node, ref) {
+	if (!node || typeof node !== "object") return;
+	if (Array.isArray(node)) {
+		for (let i = node.length - 1; i >= 0; i -= 1) {
+			const entry = node[i];
+			if (isRef(entry) && entry.__ref === ref) node.splice(i, 1);
+			else removeRef(entry, ref);
+		}
+		return;
+	}
+	for (const [key, value] of Object.entries(node)) if (isRef(value) && value.__ref === ref) delete node[key];
+	else removeRef(value, ref);
+}
+/**
+* A v1 bag could set a CSS property the system declared no style prop for, and v1 wrote the key as a
+* declaration (`boxShadow: 'inset …'` → `box-shadow: inset …`). v2 writes only what a style property
+* declares, so each such key becomes an arbitrary-valued style property of the same name. A key that
+* is neither CSS nor a prop of the layer's element painted nothing in v1 and is dropped with a note.
+*/
+function declareRawCssKeys(componentRecord, stylePropRecord) {
+	const bodyOf = (path) => componentRecord[path];
+	/** The props a layer's element takes: the component's own, and its root element's beneath it. */
+	const elementProps = (element, seen = /* @__PURE__ */ new Set()) => {
+		const out = /* @__PURE__ */ new Set();
+		if (!isRef(element)) return out;
+		const path = pathOf(element);
+		if (seen.has(path)) return out;
+		seen.add(path);
+		const body = bodyOf(path);
+		for (const [prop, decl] of Object.entries(body?.props ?? {})) if (decl !== null) out.add(prop);
+		for (const prop of elementProps(body?.layers?.root, seen)) out.add(prop);
+		return out;
+	};
+	const audit = (bag, accepted, at) => {
+		for (const [key, value] of Object.entries(bag)) {
+			if (key.startsWith("_")) {
+				if (value && typeof value === "object" && !Array.isArray(value)) audit(value, accepted, `${at}/${key}`);
+				continue;
+			}
+			if (key.startsWith("--") || key in stylePropRecord || accepted.has(key)) continue;
+			if (isCssProperty(key)) {
+				stylePropRecord[key] = StyleProperty.item({
+					properties: [kebabCase(key)],
+					arbitrary: true
+				});
+				continue;
+			}
+			report("style-key-unrecognized", `${at}/${key}`, `names no style property, CSS property, or prop of the layer's element; v1 painted nothing for it`);
+			delete bag[key];
+		}
+	};
+	for (const [name, body] of Object.entries(componentRecord)) {
+		const { layers, styles } = body;
+		if (!styles) continue;
+		for (const [when, rule] of Object.entries(styles)) for (const [layer, bag] of Object.entries(rule.layers ?? {})) audit(bag, elementProps(layers?.[layer]), `${name}/${when}/${layer}`);
+	}
+}
+//#endregion
+export { V1_DIAGNOSTIC_CODES, loadV1Artifact, v1ComponentRenames };