@yahoo/uds-create-config 5.25.2 → 5.26.0

package/dist/configs/system.js

@@ -66,6 +66,7 @@ import { startingStyleModifierMigration } from "../migrations/20261009022722_sta
 import { cssMotionStrictMigration } from "../migrations/20261009181635_css_motion_strict.js";
 import { linkOverrideRefMigration } from "../migrations/20261009193004_link_override_ref.js";
 import { linkedComponentModulesMigration } from "../migrations/20261012200606_linked_component_modules.js";
+import { componentStatesMigration } from "../migrations/20261013154037_component_states.js";
 const System = defineConfig({
 	name: WEB_CONFIG_NAME,
 	description: "A design system: the values, primitives and compositions an app is built from. A ref is written `{ \"__ref\": \"<kind>:<path>\" }`, so a token is `{ \"__ref\": \"token:<group>/<name>\" }` and a token group is `{ \"__ref\": \"token:<group>\" }`. Build it in this order. Tokens first, in groups by purpose (colors, spacing, radii, type sizes), since everything else names them. Then style properties, each with `values` holding one ref to the token group whose members it accepts (`{ \"__ref\": \"token:color\" }`), so a prop takes token names rather than raw CSS; add a string keyword only for a value no token holds. A style rule's bag holds a prop's values (`\"padding\": \"4\"`, `\"bg\": \"brand\"`), never raw CSS. Then a few primitive components, one layer each, whose props are style properties (a box for layout and surface, a text for type, a pressable for interaction). Then every other component composed from those primitives: its layers name a primitive or an element, its anatomy places them (a node renders a layer, a tag or `Slot` where a slot prop's content lands; `children` is the edge list; `visible` is `{ \"$state\": \"<prop>\" }`; a prop shown in a nested layer is a `forward` route, and `$state` never sits in a node's props), and its style rules set style-property values per layer, keyed by prop values when a variant changes them. Modes (a dark mode is `{ type: \"selector\", value: \".dark\" }`) change token values through a token's `overrides`, so a component never restyles for a mode; modifiers (hover, focus, disabled) name a state, and a style rule applies under one as a `_hover` block inside a layer bag. Composites bundle style values that recur. Last, register canvas roles: the canvas draws with them, one entity per tool (`frame` for the layout primitive, `text` for the text primitive, `image`) whose entries name the components that tool inserts, and a tool whose role is unregistered is disabled. Give each component a `preview` entry under `*` so it shows content, and never write a CSS property name where a style-property name belongs.",
@@ -143,5 +144,6 @@ if (!registeredSchemaMigrations().has(20261009022722)) registerSchemaMigrations(
 if (!registeredSchemaMigrations().has(20261009181635)) registerSchemaMigrations(cssMotionStrictMigration);
 if (!registeredSchemaMigrations().has(20261009193004)) registerSchemaMigrations(linkOverrideRefMigration);
 if (!registeredSchemaMigrations().has(20261012200606)) registerSchemaMigrations(linkedComponentModulesMigration);
+if (!registeredSchemaMigrations().has(20261013154037)) registerSchemaMigrations(componentStatesMigration);
 //#endregion
 export { System };

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

@@ -11,7 +11,7 @@ import { StyleClass } from "./style-bag.js";
 import { TokenClass } from "./Token.js";
 import { StoredPreviewCondition } from "../../framework/preview-store.js";
 import { RepeatSpec } from "../../framework/render-spec.js";
-import { AsInput, DefaultsOf, LayerMap, PhantomCallProps, PhantomReadProps, PropMap, RenderArgs, StyleRuleInput } from "./defineComponent.js";
+import { AsInput, DefaultsOf, LayerMap, PhantomCallProps, PhantomReadProps, PropMap, RenderArgs, StateMap, StyleRuleInput } from "./defineComponent.js";
 import { listSlots, namedSlots, slotHostedBy, slotOf, slotsFor } from "../../spec/slot.js";
 import { cellAt } from "../../spec/cell.js";
 import { instanceAt } from "../../spec/instance.js";
@@ -645,6 +645,13 @@ interface AnatomyNodeClass extends Named<typeof AnatomyNodeDefinition> {}
 declare const componentFields: z.ZodObject<{
   layers: LayerClass;
   props: z.ZodOptional<PropClass>;
+  states: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"boolean">;
+  }, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"variant">;
+    value: z.ZodArray<z.ZodString>;
+    default: z.ZodOptional<z.ZodString>;
+  }, z.core.$strict>], "type">>>;
   forwards: z.ZodOptional<ForwardClass>;
   styles: z.ZodOptional<z.ZodUnion<readonly [z.ZodPipe<z.ZodArray<z.ZodType<ComponentStyleBody, unknown, z.core.$ZodTypeInternals<ComponentStyleBody, unknown>>>, z.ZodTransform<Record<string, ComponentStyleBody>, ComponentStyleBody[]>>, SubEntityClass<z.ZodType<ComponentStyleBody, unknown, z.core.$ZodTypeInternals<ComponentStyleBody, unknown>>>]>>;
   renderProps: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -679,6 +686,13 @@ declare function blankComponentBody(): ComponentBody;
 declare const ComponentEntity: EntityClass<z.ZodObject<{
   layers: LayerClass;
   props: z.ZodOptional<PropClass>;
+  states: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"boolean">;
+  }, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"variant">;
+    value: z.ZodArray<z.ZodString>;
+    default: z.ZodOptional<z.ZodString>;
+  }, z.core.$strict>], "type">>>;
   forwards: z.ZodOptional<ForwardClass>;
   styles: z.ZodOptional<z.ZodUnion<readonly [z.ZodPipe<z.ZodArray<z.ZodType<ComponentStyleBody, unknown, z.core.$ZodTypeInternals<ComponentStyleBody, unknown>>>, z.ZodTransform<Record<string, ComponentStyleBody>, ComponentStyleBody[]>>, SubEntityClass<z.ZodType<ComponentStyleBody, unknown, z.core.$ZodTypeInternals<ComponentStyleBody, unknown>>>]>>;
   renderProps: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -780,6 +794,19 @@ declare const ComponentEntity: EntityClass<z.ZodObject<{
       }, z.core.$strip>>;
     }, z.core.$strip>;
   };
+  readonly 'element-wrap': {
+    readonly input: z.ZodObject<{
+      path: z.ZodType<string, string | undefined, z.core.$ZodTypeInternals<string, string | undefined>>;
+      key: z.ZodOptional<z.ZodString>;
+      data: z.ZodObject<{
+        elements: z.ZodArray<z.ZodString>;
+        element: z.ZodDefault<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+          __ref: z.ZodString;
+        }, z.core.$strip>]>>;
+        props: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+      }, z.core.$strip>;
+    }, z.core.$strip>;
+  };
   readonly validate: {
     readonly input: z.ZodObject<{
       path: z.ZodType<string, string | undefined, z.core.$ZodTypeInternals<string, string | undefined>>;
@@ -841,6 +868,12 @@ type ResolvedForwards<Contract, Delta> = Delta extends {
 } ? Forwards : Contract extends {
   forwards: infer Forwards;
 } ? Forwards : Record<never, never>;
+/** The states an extension ends up with: its delta's, else the linked contract's. */
+type ResolvedStates<Contract, Delta> = Delta extends {
+  readonly states: infer States extends StateMap;
+} ? States : Contract extends {
+  states: infer States extends StateMap;
+} ? States : Record<never, never>;
 type ForwardedLayerNames<Contract, Delta> = ResolvedForwards<Contract, Delta> extends Record<string, unknown> ? keyof ResolvedForwards<Contract, Delta> & string : never;
 /** The source-only half of a linked component extension. The callback is deliberately absent from
  * {@link ExtendedRef}: it is code, so ts-morph reads it from the authoring file while Config stores
@@ -852,7 +885,7 @@ type ExtendedComponentRef<Contract = ComponentContractOf<string>, Delta extends
    * read signature for `ComponentProps`. */
   <As extends AsInput = never>(props: PhantomCallProps<ResolvedLayers<Contract, Delta>, ResolvedProps<Contract, Delta>, ResolvedDefaults<Contract, Delta>, Extra, ForwardedLayerNames<Contract, Delta>, As>): null;
   <As extends AsInput = never>(props: PhantomReadProps<ResolvedLayers<Contract, Delta>, ResolvedProps<Contract, Delta>, ResolvedDefaults<Contract, Delta>, Extra, ForwardedLayerNames<Contract, Delta>, As>): null;
-  render<E = Extra>(fn: (args: RenderArgs<ResolvedLayers<Contract, Delta>, ResolvedProps<Contract, Delta>> & E) => unknown): ExtendedComponentRef<Contract, Delta, E>;
+  render<E = Extra>(fn: (args: RenderArgs<ResolvedLayers<Contract, Delta>, ResolvedProps<Contract, Delta>, ResolvedStates<Contract, Delta>> & E) => unknown): ExtendedComponentRef<Contract, Delta, E>;
   /**
    * Style rules for the extension, typed against the layers it ends up with — the linked contract's,
    * with the delta's replacing them when it declares its own.

package/dist/entities/system/Component.js

@@ -7,6 +7,7 @@ import { shadowValue } from "./shadow.js";
 import { defineEntity } from "../../framework/defineEntity.js";
 import { defineSubEntity, orList } from "../../framework/defineSubEntity.js";
 import { childrenPolicy, forwardedPropName } from "./element.js";
+import { interactionKey, interactionModifiers } from "../../framework/interaction-conditions.js";
 import { listedIn } from "../../framework/utils/enumerated.js";
 import { valueSchemaOf } from "../../framework/value-domain.js";
 import { Package } from "./Package.js";
@@ -712,25 +713,38 @@ function bagFor(config, layerElement) {
 	bags.set(key, built);
 	return built;
 }
+/**
+* A content prop's value in a rule, or `false` for none: a state that drops a Button's start icon
+* says so with `startIcon: false`, since leaving the key out keeps whatever the rule beneath gives.
+* Not for a required prop, whose content is the component's to have.
+*/
+function withNone(value, declaration) {
+	if (declaration?.required === true) return value;
+	return z.union([value, z.literal(false)]);
+}
 /** One element's bag, built. Reached only through the memo above. */
 function buildBagFor(config, layerElement) {
 	const shape = { ...stylePropShape(config) };
 	const component = isRef(layerElement) && config.resolveRef(layerElement.__ref) ? pathOf(layerElement.__ref) : void 0;
 	const glyphProps = component ? glyphPropsOf(config, component) : {};
-	for (const [name, decl] of Object.entries(component ? resolveComponentProps(config, component) : {})) shape[name] = styleBagValue({
-		config,
-		declaration: decl,
-		name,
-		glyphLibraries: decl?.type === "forward" ? glyphProps[name] : void 0
-	}).optional();
+	for (const [name, decl] of Object.entries(component ? resolveComponentProps(config, component) : {})) {
+		const forwarded = decl?.type === "forward";
+		const value = styleBagValue({
+			config,
+			declaration: decl,
+			name,
+			glyphLibraries: forwarded ? glyphProps[name] : void 0
+		});
+		shape[name] = (forwarded ? withNone(value, decl) : value).optional();
+	}
 	const declared = component ? (config.resolve("component", component)?.toJSON())?.props ?? {} : {};
 	for (const [name, decl] of Object.entries(declared)) {
 		if (decl?.type !== "slot" || name in shape) continue;
-		shape[name] = styleBagValue({
+		shape[name] = withNone(styleBagValue({
 			config,
 			declaration: decl,
 			name
-		}).optional();
+		}), decl).optional();
 	}
 	shape.as ??= z.string().optional();
 	for (const [key, owned] of config.layerKeys()) shape[key] = owned.schema(shape[key]).optional();
@@ -808,6 +822,18 @@ function conditionValue(prop, declaration, config) {
 	if (!ownsItsValues(declaration)) return domain;
 	return z.union([domain, refSchema]).transform((value) => isRef(value) ? value : valueRef(prop, String(value)));
 }
+/** The condition on a STATE: a boolean's `true`/`false`, or one of a variant state's names. A state
+*  has no value members to ref, so a variant's condition is the name itself. */
+function stateConditionValue(declaration) {
+	const decl = declaration;
+	if (decl?.type === "variant" && Array.isArray(decl.value)) return z.enum(decl.value);
+	return scalarConditionValue({ type: "boolean" }) ?? z.boolean();
+}
+/** An interaction condition's value: `true` (the root), or the layer whose interaction it is. */
+function interactionConditionValue(layers) {
+	const truthy = z.union([z.literal(true), z.literal("true").transform(() => true)]);
+	return layers.length > 0 ? z.union([truthy, z.enum(layers)], { error: `an interaction condition is \`true\` (the component's root) or one of its layers: ${layers.join(", ")}` }) : truthy;
+}
 /**
 * The condition on a boolean or number prop, in the prop's type. A preview axis spells every value
 * as a string and a rule's key stringifies it, so a writer reading either hands back `'true'` where
@@ -1022,6 +1048,13 @@ const StyleRule = defineSubEntity({
 			build: () => {
 				const when = {};
 				for (const [name, decl] of Object.entries(body.props ?? {})) when[name] = conditionValue(name, decl, config).optional();
+				for (const [name, decl] of Object.entries(body.states ?? {})) when[name] = stateConditionValue(decl).optional();
+				const layerNames = Object.keys(body.layers ?? {});
+				for (const modifier of interactionModifiers(config)) {
+					const key = interactionKey(modifier);
+					if (key in when) continue;
+					when[key] = interactionConditionValue(layerNames).optional();
+				}
 				const layers = {};
 				for (const [name, el] of Object.entries(body.layers ?? {})) layers[name] = bagFor(config, el).optional();
 				return z.strictObject({
@@ -1049,10 +1082,11 @@ function perOwner({ cache, config, owner, build }) {
 		cache.set(config, perConfig);
 	}
 	const hit = perConfig.get(owner);
-	if (hit && hit.props === owner.props && hit.layers === owner.layers) return hit.schema;
+	if (hit && hit.props === owner.props && hit.states === owner.states && hit.layers === owner.layers) return hit.schema;
 	const schema = build();
 	perConfig.set(owner, {
 		props: owner.props,
+		states: owner.states,
 		layers: owner.layers,
 		schema
 	});
@@ -1089,6 +1123,7 @@ const Preview = defineSubEntity({
 			build: () => {
 				const when = {};
 				for (const [name, decl] of Object.entries(body.props ?? {})) when[name] = conditionValue(name, decl, config).optional();
+				for (const [name, decl] of Object.entries(body.states ?? {})) when[name] = stateConditionValue(decl).optional();
 				return z.strictObject({
 					when: z.strictObject(when, { error: previewShapeError }).nullable().default(null),
 					props: z.record(z.string(), z.unknown()).transform((props) => bindPreviewGlyphs({
@@ -1347,6 +1382,83 @@ function anatomySubtreeContains(anatomy, ancestor, key) {
 function resolveMoveBody(config, path) {
 	return config.resolve("component", path)?.toJSON();
 }
+/**
+* Wrap a component's root: the container becomes `root`, and what the root was — its element, its
+* children and slots, its props, the style rules and forwards that name it — moves onto `inner`, the
+* container's one child. Props the config doesn't model (`id`, an `onClick`) keep landing on `root`,
+* which is now the container.
+*/
+function wrapRoot({ config, path, inner, element, props }) {
+	const body = config.resolve("component", path)?.toJSON();
+	const root = body?.anatomy?.root;
+	if (!body || !root) reject("NOT_FOUND", `"${path}" has no root to wrap.`);
+	const { element: _element, ...rootRest } = root;
+	let next = config.apply({
+		kind: "component",
+		operation: "sub-create",
+		path,
+		field: "layers",
+		key: inner,
+		data: body?.layers?.root
+	}).apply({
+		kind: "component",
+		operation: "sub-create",
+		path,
+		field: "anatomy",
+		key: inner,
+		data: {
+			...rootRest,
+			element: layerRef(inner)
+		}
+	}).apply({
+		kind: "component",
+		operation: "sub-upsert",
+		path,
+		field: "layers",
+		key: "root",
+		data: asElementRef(config, element)
+	}).apply({
+		kind: "component",
+		operation: "sub-upsert",
+		path,
+		field: "anatomy",
+		key: "root",
+		data: {
+			element: layerRef("root"),
+			children: [inner],
+			...props ? { props } : {}
+		}
+	});
+	for (const [key, rule] of Object.entries(body?.styles ?? {})) {
+		const bag = rule.layers?.root;
+		if (bag === void 0) continue;
+		next = next.apply({
+			kind: "component",
+			operation: "sub-update",
+			path,
+			field: "styles",
+			key,
+			data: {
+				when: rule.when ?? null,
+				[`layers.${inner}`]: bag,
+				"layers.root": null
+			}
+		});
+	}
+	for (const [name, decl] of Object.entries(body?.props ?? {})) {
+		const target = decl.target;
+		if (!(isRef(target) ? kindOf(target) === "layer" && pathOf(target) === "root" : typeof target === "string" && target.startsWith("root/"))) continue;
+		next = next.apply({
+			kind: "component",
+			operation: "sub-update",
+			path,
+			field: "props",
+			key: name,
+			data: { target: isRef(target) ? layerRef(inner) : `${inner}/${String(target).slice(5)}` }
+		});
+	}
+	return next;
+}
 const AnatomyNode = defineSubEntity({
 	name: "element",
 	label: "Element",
@@ -1538,6 +1650,18 @@ const componentFields = z.strictObject({
 	}),
 	props: Prop.optional(),
 	/**
+	* What the RENDER knows and a style rule keys on — the field has a value, the image loaded, the
+	* indicator is sliding. Not props: a caller never passes one, so none is part of the component's
+	* API. The render passes them to `states(props, { … })` and spreads the layers it hands back;
+	* the rules naming one follow the values given, and the root carries each as a `data-<name>`
+	* attribute. Studio and tests force one through the module's internal channel, never a prop.
+	*/
+	states: z.record(z.string(), z.discriminatedUnion("type", [z.strictObject({ type: z.literal("boolean") }), z.strictObject({
+		type: z.literal("variant"),
+		value: z.array(z.string()).min(1),
+		default: z.string().optional()
+	})])).optional().describe("What the render knows and a style rule keys on, by name: `{ \"filled\": { \"type\": \"boolean\" } }`, or `{ \"phase\": { \"type\": \"variant\", \"value\": [\"idle\", \"sliding\"], \"default\": \"idle\" } }`. Not props, so not part of the component's API: the render passes its `props` and the values it knows to `const layers = states(props, { filled: value !== \"\" })` and spreads those layers (`{...layers.root}`) instead of `props`; a rule naming a state in `when` (`{ \"filled\": true }`, `{ \"phase\": \"sliding\" }`) is tested against the values given, and the root carries each as a `data-<name>` attribute. A value a caller controls is a prop instead, which the render reports the state from."),
+	/**
 	* Which layers' element props this component also exposes — see {@link Forward}.
 	*
 	* Replaced `inherits`, which named one layer and meant `{ [layer]: '*' }`. That field and its
@@ -1598,6 +1722,34 @@ const componentFields = z.strictObject({
 			message: `\`${name}\` conditions on itself. \`when\` names a sibling prop and one of its values.`
 		});
 	}
+	if (isPlainObject(body.states) && Object.keys(body.states).length > 0) {
+		const props = isPlainObject(body.props) ? body.props : {};
+		if (Object.hasOwn(props, "states")) ctx.issues.push({
+			code: "custom",
+			input: props.states,
+			path: ["props", "states"],
+			message: "A component with states hands its render a `states` helper, so no prop of its own can be named `states`."
+		});
+		for (const [name, decl] of Object.entries(body.states)) {
+			if (Object.hasOwn(props, name)) ctx.issues.push({
+				code: "custom",
+				input: decl,
+				path: ["states", name],
+				message: `\`${name}\` is both a prop and a state. A state is what the render knows, never a value a caller passes; a caller-controlled value is a prop the render reports the state from.`
+			});
+			const variant = decl;
+			if (variant?.type === "variant" && variant.default !== void 0 && Array.isArray(variant.value) && !variant.value.includes(variant.default)) ctx.issues.push({
+				code: "custom",
+				input: variant.default,
+				path: [
+					"states",
+					name,
+					"default"
+				],
+				message: `\`${name}\`'s default \`${String(variant.default)}\` is not one of its values (${variant.value.join(", ")}).`
+			});
+		}
+	}
 	if (body.forwards || body.file || isRef(body.props)) return;
 	const declared = body.props ?? {};
 	if (Object.hasOwn(declared, "children") && declared.children !== null) return;
@@ -2328,6 +2480,69 @@ subtree: z.boolean().default(true) }).optional()
 				});
 			}
 		},
+		"element-wrap": {
+			input: z.object({
+				path: pathInput("component"),
+				/** The new layer's name: the wrapper's, or — wrapping the root — the old root's new name. The
+				*  entity mints a free one when the caller doesn't care. */
+				key: z.string().optional(),
+				data: z.object({
+					/** The layers to wrap: siblings under one parent, wrapped in their order, or `['root']`. */
+					elements: z.array(z.string()).min(1),
+					/** What the wrapper renders — a frame component or a tag. */
+					element: z.union([z.string(), refSchema]).default("div"),
+					/** The wrapper's own props. */
+					props: z.record(z.string(), z.unknown()).optional()
+				})
+			}),
+			readOnly: false,
+			label: "Wrap elements",
+			description: "Wrap a component's sibling layers in a new container. Wrapping `root` makes the container the root and moves the old root — its element, children, slots, styles and forwards — onto a new layer inside it.",
+			scope: "item",
+			creates: true,
+			title: (entity) => `Wrap ${entity} elements`,
+			handler: (input, config) => {
+				const payload = input.data;
+				const path = String(input.path);
+				const keys = payload.elements;
+				const anatomy = resolveMoveBody(config, path)?.anatomy ?? {};
+				for (const k of keys) if (!anatomy[k]) reject("NOT_FOUND", `"${path}" has no element "${k}" to wrap.`);
+				if (keys.includes("root")) {
+					if (keys.length > 1) rejectData("The root wraps on its own: it has no siblings to wrap with it.", ["elements"]);
+					return wrapRoot({
+						config,
+						path,
+						inner: input.key ? String(input.key) : freeLayerKey(config, path, "content"),
+						element: payload.element,
+						props: payload.props
+					});
+				}
+				const parent = Object.entries(anatomy).find(([, node]) => keys.every((k) => node.children?.includes(k)));
+				if (!parent) rejectData("Only layers that share a parent wrap together — wrap each parent's layers on their own.", ["elements"]);
+				const [parentKey, parentNode] = parent;
+				const order = (parentNode.children ?? []).filter((c) => keys.includes(c));
+				const index = (parentNode.children ?? []).indexOf(order[0]);
+				const wrapper = input.key ? String(input.key) : freeLayerKey(config, path, "wrap");
+				return config.run([{
+					kind: "component",
+					operation: "element-insert",
+					path,
+					key: wrapper,
+					data: {
+						element: payload.element,
+						parent: parentKey,
+						index,
+						...payload.props ? { props: payload.props } : {}
+					}
+				}, ...order.map((k) => ({
+					kind: "component",
+					operation: "element-move",
+					path,
+					key: k,
+					data: { parent: wrapper }
+				}))]);
+			}
+		},
 		validate: {
 			input: z.object({
 				path: pathInput("component"),

package/dist/entities/system/Settings.js

@@ -1,9 +1,9 @@
 import { splitRef } from "../../framework/utils/refs.js";
 import { defineEntity } from "../../framework/defineEntity.js";
 import { defineSubEntity } from "../../framework/defineSubEntity.js";
+import { createSliceMemo } from "../../framework/memo.js";
 import { buildFields } from "../../configs/build-options.js";
 import { parseRootFontSize } from "../../css/root-font-size.js";
-import { createSliceMemo } from "../../framework/memo.js";
 import { resolveInputDir } from "../../framework/registry-dir.js";
 import { safelistSchema } from "./safelist.js";
 import { z } from "zod";

package/dist/entities/system/StyleProperty.js

@@ -1,8 +1,8 @@
 import { declarationText, isRef, kindOf, pathOf, ref, refOfKey, refSchema, replaceRefMarkers, sourceOf, splitRef } from "../../framework/utils/refs.js";
 import { defineEntity } from "../../framework/defineEntity.js";
+import { createSliceMemo } from "../../framework/memo.js";
 import { cssValueIssue, isCssProperty } from "../../css/values.js";
 import { camelCase } from "./style-bag.js";
-import { createSliceMemo } from "../../framework/memo.js";
 import { isIdentifier } from "../../framework/utils/identifier.js";
 import { cssVar, declaresCssVariable } from "../../framework/projections.js";
 import { z } from "zod";

package/dist/entities/system/component-module.d.ts

@@ -26,6 +26,22 @@ interface ComponentModuleSource {
     readonly version: string;
   };
 }
+/** The directory, under the system's input root, a component made in Create is built from. No file
+ *  is ever written there: the server writes the source `uds pull` would, and builds it in place. */
+declare const CREATED_COMPONENT_DIRECTORY = "__created__";
+/** The virtual source path a component made in Create builds from. */
+declare function createdComponentFilePath(config: Config, path: string): string;
+/** The component a virtual created path names, when it names one this config made in Create. */
+declare function createdComponentPathOf(config: Config, filePath: string): string | undefined;
+/** Whether a component was made in Create: a web component no file holds, whose structure is its
+ *  anatomy. */
+declare function isCreatedComponent(config: Config, path: string): boolean;
+/**
+ * A component made in Create's module key: the runtime every module embeds, the component's own
+ * build body, and the bodies of the components its layers place — whose props decide how it routes
+ * and emits. Computed from the config alone, so the browser and the server spell it the same.
+ */
+declare function createdModuleKey(config: Config, path: string): string | undefined;
 /**
  * The static an emitted module stamps a component's registry-entry facts on: what
  * `makeComponentEntry` takes beyond the component (`childless`, `computed`). A static and not an
@@ -110,4 +126,4 @@ declare function linkedComponentModule(config: Config, componentPathOrRef: strin
   readonly view: Config;
 } | undefined;
 //#endregion
-export { COMPONENT_ENTRY_STATIC, ComponentModuleSource, ComponentRegistryImport, ComponentRegistryImportBinding, componentModuleFilePaths, componentModuleKey, componentModuleSource, componentRegistryImports, linkedComponentModule, linkedModuleView };
+export { COMPONENT_ENTRY_STATIC, CREATED_COMPONENT_DIRECTORY, ComponentModuleSource, ComponentRegistryImport, ComponentRegistryImportBinding, componentModuleFilePaths, componentModuleKey, componentModuleSource, componentRegistryImports, createdComponentFilePath, createdComponentPathOf, createdModuleKey, isCreatedComponent, linkedComponentModule, linkedModuleView };

package/dist/entities/system/component-module.js

@@ -1,4 +1,4 @@
-import { ref, routedSource, sourceHops, splitRef } from "../../framework/utils/refs.js";
+import { isRef, kindOf, pathOf, ref, routedSource, sourceHops, splitRef } from "../../framework/utils/refs.js";
 import { createSliceMemo } from "../../framework/memo.js";
 import { Settings, classPrefixOf, prefixed, varPrefixOf } from "./Settings.js";
 import { File } from "./File.js";
@@ -28,6 +28,58 @@ const WEB_RUNTIME_KINDS = [
 	"motion",
 	"composite"
 ];
+/** The directory, under the system's input root, a component made in Create is built from. No file
+*  is ever written there: the server writes the source `uds pull` would, and builds it in place. */
+const CREATED_COMPONENT_DIRECTORY = "__created__";
+/** The virtual source path a component made in Create builds from. */
+function createdComponentFilePath(config, path) {
+	return `${createdComponentDirectory(config)}${path}.tsx`;
+}
+/** The directory, with its trailing slash, a config's created paths start with. An empty input
+*  root puts it at the top, since a sealed path never starts with a slash. */
+function createdComponentDirectory(config) {
+	const root = (Settings.get(config)?.inputDir ?? "src").replace(/\/+$/, "");
+	return root ? `${root}/${CREATED_COMPONENT_DIRECTORY}/` : `${CREATED_COMPONENT_DIRECTORY}/`;
+}
+/** The component a virtual created path names, when it names one this config made in Create. */
+function createdComponentPathOf(config, filePath) {
+	const directory = createdComponentDirectory(config);
+	if (!filePath.startsWith(directory) || !filePath.endsWith(".tsx")) return;
+	const path = filePath.slice(directory.length, -4);
+	return isCreatedComponent(config, path) ? path : void 0;
+}
+/** Whether a component was made in Create: a web component no file holds, whose structure is its
+*  anatomy. */
+function isCreatedComponent(config, path) {
+	if (isNativeConfig(config)) return false;
+	const component = Component.get(config, path);
+	if (!component || component.source !== void 0) return false;
+	const { file, export: exportName, anatomy } = component.body;
+	return !file && !exportName && Object.keys(anatomy ?? {}).length > 0;
+}
+/**
+* A component made in Create's module key: the runtime every module embeds, the component's own
+* build body, and the bodies of the components its layers place — whose props decide how it routes
+* and emits. Computed from the config alone, so the browser and the server spell it the same.
+*/
+function createdModuleKey(config, path) {
+	const component = Component.get(config, path);
+	if (!component) return void 0;
+	const body = component.toJSON();
+	const placed = {};
+	for (const element of Object.values(body.layers ?? {})) {
+		if (!isRef(element) || kindOf(element) !== "component") continue;
+		const target = Component.get(config, pathOf(element.__ref));
+		if (target) placed[target.path] = buildEntityBody("component", target.toJSON());
+	}
+	return contentKey({
+		version: COMPONENT_MODULE_BUILD_VERSION,
+		runtimeKey: componentRuntimeKey(config),
+		created: path,
+		body: buildEntityBody("component", body),
+		placed
+	});
+}
 /**
 * The static an emitted module stamps a component's registry-entry facts on: what
 * `makeComponentEntry` takes beyond the component (`childless`, `computed`). A static and not an
@@ -393,4 +445,4 @@ function publishedPin(config, slug) {
 	}
 }
 //#endregion
-export { COMPONENT_ENTRY_STATIC, componentModuleFilePaths, componentModuleKey, componentModuleSource, componentRegistryImports, linkedComponentModule, linkedModuleView };
+export { COMPONENT_ENTRY_STATIC, CREATED_COMPONENT_DIRECTORY, componentModuleFilePaths, componentModuleKey, componentModuleSource, componentRegistryImports, createdComponentFilePath, createdComponentPathOf, createdModuleKey, isCreatedComponent, linkedComponentModule, linkedModuleView };