@yahoo/uds-create-config 4.51.3 → 4.53.0

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

@@ -12,9 +12,10 @@ 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 { listSlots, namedSlots, slotHostedBy, slotOf } from "../../spec/slot.js";
+import { listSlots, namedSlots, slotHostedBy, slotOf, slotsFor } from "../../spec/slot.js";
 import { cellAt } from "../../spec/cell.js";
 import { instanceAt } from "../../spec/instance.js";
+import { ForwardOptions, forwardOptions } from "./component-forwards.js";
 import { Config } from "../../framework/Config.js";
 import { z } from "zod";
 
@@ -320,30 +321,6 @@ interface ComponentStyleBody {
    *  exposes), which no single static type can state — so the bag stays open here. */
   layers?: Record<string, Record<string, unknown> | undefined>;
 }
-declare const StyleRuleDefinition: SubEntityClass<z.ZodType<ComponentStyleBody, unknown, z.core.$ZodTypeInternals<ComponentStyleBody, unknown>>>;
-interface StyleRuleClass extends Named<typeof StyleRuleDefinition> {}
-/**
- * The props a cell previews with, keyed by the condition they hold under the way a style rule is:
- * `*` for every cell, a condition on the component's own props for some. `when` names those props,
- * so a prop rename moves it and a value rename moves the ref it stores; `props` is keyed by prop
- * too, which `Prop.keyedByNameIn` and `VariantValue.namedValuesIn` reach through `preview/*\/props`.
- * Deleting a prop or a value drops the entries conditioned on it.
- */
-declare const PreviewDefinition: SubEntityClass<z.ZodType<StoredPreviewCondition, unknown, z.core.$ZodTypeInternals<StoredPreviewCondition, unknown>>>;
-interface PreviewClass extends Named<typeof PreviewDefinition> {}
-/**
- * One node of an inserted subtree, in the shape the anatomy already stores.
- *
- * An insert takes a whole subtree because inserting one is a single user action: "restore this slot's
- * default" puts back a stack holding a text, and splitting that into one row per node would make one
- * gesture several rows in the changes panel and several things to undo. It is the same reason the op
- * already writes the layer and the node together.
- *
- * Flat, keyed, with `children` as an edge list of keys — because that is what anatomy is, and what a
- * json-render spec is. A nested form would need converting at both ends: the caller holds a flat spec
- * subtree, and the store keeps a flat edge list. Every descendant gets its own layer, for the reason
- * the root does: a thing a person added is added in order to be styled, and `styles` keys on layers.
- */
 declare const visibilityDefinition: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodPipe<z.ZodObject<{
   not: z.ZodOptional<z.ZodLiteral<true>>;
   eq: z.ZodOptional<z.ZodUnknown>;
@@ -669,11 +646,11 @@ declare const componentFields: z.ZodObject<{
   layers: LayerClass;
   props: z.ZodOptional<PropClass>;
   forwards: z.ZodOptional<ForwardClass>;
-  styles: z.ZodOptional<StyleRuleClass>;
+  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>>;
   anatomy: z.ZodOptional<AnatomyNodeClass>;
   defaultProps: z.ZodOptional<StyleClass>;
-  preview: z.ZodOptional<PreviewClass>;
+  preview: z.ZodOptional<z.ZodUnion<readonly [z.ZodPipe<z.ZodArray<z.ZodType<StoredPreviewCondition, unknown, z.core.$ZodTypeInternals<StoredPreviewCondition, unknown>>>, z.ZodTransform<Record<string, StoredPreviewCondition>, StoredPreviewCondition[]>>, SubEntityClass<z.ZodType<StoredPreviewCondition, unknown, z.core.$ZodTypeInternals<StoredPreviewCondition, unknown>>>]>>;
   file: z.ZodOptional<z.ZodObject<{
     __ref: z.ZodString;
   }, z.core.$strip>>;
@@ -703,11 +680,11 @@ declare const ComponentEntity: EntityClass<z.ZodObject<{
   layers: LayerClass;
   props: z.ZodOptional<PropClass>;
   forwards: z.ZodOptional<ForwardClass>;
-  styles: z.ZodOptional<StyleRuleClass>;
+  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>>;
   anatomy: z.ZodOptional<AnatomyNodeClass>;
   defaultProps: z.ZodOptional<StyleClass>;
-  preview: z.ZodOptional<PreviewClass>;
+  preview: z.ZodOptional<z.ZodUnion<readonly [z.ZodPipe<z.ZodArray<z.ZodType<StoredPreviewCondition, unknown, z.core.$ZodTypeInternals<StoredPreviewCondition, unknown>>>, z.ZodTransform<Record<string, StoredPreviewCondition>, StoredPreviewCondition[]>>, SubEntityClass<z.ZodType<StoredPreviewCondition, unknown, z.core.$ZodTypeInternals<StoredPreviewCondition, unknown>>>]>>;
   file: z.ZodOptional<z.ZodObject<{
     __ref: z.ZodString;
   }, z.core.$strip>>;
@@ -763,6 +740,26 @@ declare const ComponentEntity: EntityClass<z.ZodObject<{
       }, z.core.$strip>>;
     }, z.core.$strip>;
   };
+  readonly 'element-duplicate': {
+    readonly input: z.ZodObject<{
+      path: z.ZodType<string, string | undefined, z.core.$ZodTypeInternals<string, string | undefined>>;
+      key: z.ZodString;
+      data: z.ZodPrefault<z.ZodObject<{
+        count: z.ZodOptional<z.ZodNumber>;
+      }, z.core.$strip>>;
+    }, z.core.$strip>;
+  };
+  readonly 'layer-forward': {
+    readonly input: z.ZodObject<{
+      path: z.ZodType<string, string | undefined, z.core.$ZodTypeInternals<string, string | undefined>>;
+      key: z.ZodString;
+      data: z.ZodObject<{
+        props: z.ZodUnion<readonly [z.ZodLiteral<"*">, z.ZodArray<z.ZodString>]>;
+        except: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        replace: z.ZodOptional<z.ZodBoolean>;
+      }, z.core.$strip>;
+    }, z.core.$strip>;
+  };
   readonly 'element-delete': {
     readonly input: z.ZodObject<{
       path: z.ZodType<string, string | undefined, z.core.$ZodTypeInternals<string, string | undefined>>;
@@ -792,6 +789,17 @@ declare const ComponentEntity: EntityClass<z.ZodObject<{
     }, z.core.$strip>;
   };
 }, {
+  /**
+   * What each layer can forward, for the layers that render a component with props: every prop its
+   * element exposes, whether the layer forwards it now, and why one is blocked (the component
+   * declares it, or a sibling layer forwards it). Read before writing `forwards`, so "everything
+   * but icon" is a list the caller can spell.
+   */
+  readonly forwardable: ({
+    config,
+    path,
+    member
+  }: ComputedInput) => Record<string, ForwardOptions>;
   /**
    * The prop names an instance may fill through a spec element's `slots` field — every prop that
    * routes content: a `slot`, or a `forward` whose far end takes content. Resolved over the
@@ -872,9 +880,14 @@ type ExtensionDefaults<Contract, Delta> = {
 type ComponentCreateInput = CreateInput<typeof componentFields>;
 /** `Component.item`'s body: the stored fields, with `styles` also taking the rule list
  *  `defineComponent.styles` takes, checked against this item's own layers. */
-type ComponentItemInput<L extends LayerMap> = Omit<ComponentCreateInput, 'styles'> & {
+type ComponentItemInput<L extends LayerMap> = Omit<ComponentRecordInput, 'styles'> & {
   readonly layers: L;
-  readonly styles?: ComponentCreateInput['styles'] | readonly StyleRuleInput<L>[];
+  readonly styles?: ComponentRecordInput['styles'] | readonly StyleRuleInput<L>[];
+};
+/** A component body with its `styles` as the keyed record, so a rule list is checked by
+ *  {@link ComponentItemInput} against the item's own layers rather than taken unchecked. */
+type ComponentRecordInput = Omit<ComponentCreateInput, 'styles'> & {
+  readonly styles?: Exclude<ComponentCreateInput['styles'], readonly unknown[]>;
 };
 /**
  * Component keeps the generic entity surface, plus the questions only a component answers: its
@@ -887,12 +900,14 @@ interface ComponentClass extends Omit<typeof ComponentEntity, 'ref' | 'item'> {
   /** One component. `styles` takes the stored record or the rule list `defineComponent.styles`
    *  takes, and a list is stored as the record. */
   item<const L extends LayerMap>(def: ComponentItemInput<L>): ComponentCreateInput;
-  item(def: ComponentCreateInput | string | number | Ref$1): ComponentCreateInput | string | number | Ref$1;
+  item(def: ComponentRecordInput | string | number | Ref$1): ComponentCreateInput | string | number | Ref$1;
   ref<const Path extends PathOf<'component'>>(path: Path): ComponentReference<ComponentContractOf<Path>, Path>;
   slots: typeof listSlots;
   slot: typeof slotOf;
   slotHostedBy: typeof slotHostedBy;
   namedSlots: typeof namedSlots;
+  slotsFor: typeof slotsFor;
+  forwardOptions: typeof forwardOptions;
   cell: typeof cellAt;
   instance: typeof instanceAt;
 }

package/dist/entities/system/Component.js

@@ -5,7 +5,7 @@ import { pathInput } from "../../framework/schemas.js";
 import { derivedColor, gradient } from "./color.js";
 import { shadowValue } from "./shadow.js";
 import { defineEntity } from "../../framework/defineEntity.js";
-import { defineSubEntity } from "../../framework/defineSubEntity.js";
+import { defineSubEntity, orList } from "../../framework/defineSubEntity.js";
 import { childrenPolicy, forwardedPropName } from "./element.js";
 import { listedIn } from "../../framework/utils/enumerated.js";
 import { valueSchemaOf } from "../../framework/value-domain.js";
@@ -16,9 +16,10 @@ import { storedPreview } from "../../framework/preview-store.js";
 import { glyphPropsOf, propOwner, propValueDomain, refListOf, resolveComponentProps, stylePropValueLeaves, validateComponentProps } from "../../framework/projections.js";
 import { carriesContent, intoName, isValueSlot, renderBoundProp, routedPropIn, routesContent } from "../../framework/prop-surface.js";
 import { slotAnatomyPropOf, slotTargetsOf, withoutTruthyTerm } from "../../framework/render-spec.js";
-import { listSlots, namedSlots, slotHostedBy, slotOf } from "../../spec/slot.js";
+import { listSlots, namedSlots, slotHostedBy, slotOf, slotsFor } from "../../spec/slot.js";
 import { cellAt } from "../../spec/cell.js";
 import { instanceAt } from "../../spec/instance.js";
+import { forwardOptions, forwardsWrite } from "./component-forwards.js";
 import { File } from "./File.js";
 import { forwardRouteInvariants, refusedRoutes } from "./forward-route-invariants.js";
 import { iconDomainInvariants } from "./icon-domain-invariants.js";
@@ -275,6 +276,11 @@ const ForwardDefinition = defineSubEntity({
 					input: entry,
 					message: `"${name}" is not a prop of layer "${key}"'s element (${pathOf(element.__ref)}).`
 				});
+				if (name && body.props?.[name] != null) ctx.issues.push({
+					code: "custom",
+					input: entry,
+					message: `"${name}" is declared by the component itself, which wins over a forward.`
+				});
 			}
 			const mine = forwardedNames(config, element, ctx.value);
 			if (!mine) return;
@@ -934,18 +940,18 @@ function composedCreateExample(config, path) {
 					props: { name: "children" }
 				}
 			},
-			...Object.keys(styleLayers).length ? { styles: { "*": {
+			...Object.keys(styleLayers).length ? { styles: [{
 				when: null,
 				layers: styleLayers
-			} } } : {},
-			preview: { ["*"]: {
+			}] } : {},
+			preview: [{
 				when: null,
 				props: {
 					icon: true,
 					label: "Example",
 					children: "Body text"
 				}
-			} }
+			}]
 		}
 	};
 }
@@ -983,7 +989,7 @@ function rendersLayer(element, key) {
 	return typeof element === "object" && element !== null && "$state" in element && element.layer === key;
 }
 /** The shape of a rule, for a bag written where the rule belongs or a rule with no `layers`. */
-const ruleShapeError = (issue) => issue.code === "invalid_type" || issue.code === "unrecognized_keys" ? "a style rule is `{ \"when\": null, \"layers\": { \"<layer>\": { \"<styleProp>\": \"<value>\" } } }` under a key of your own (`*` for the unconditional rule), or with `\"when\": { \"<prop>\": \"<value>\" }` for a variant; the layer bags sit under `layers`, never directly under the rule" : void 0;
+const ruleShapeError = (issue) => issue.code === "invalid_type" || issue.code === "unrecognized_keys" ? "a style rule is `{ \"when\": null, \"layers\": { \"<layer>\": { \"<styleProp>\": \"<value>\" } } }` for the unconditional rule, or with `\"when\": { \"<prop>\": \"<value>\" }` for a variant, and `styles` is a list of them; the layer bags sit under `layers`, never directly under the rule" : void 0;
 /** Whether a rule declares nothing: no `layers`, or every bag empty. A rule is its declarations, so
 *  such a rule emits no CSS and styles no layer. */
 function ruleStylesNothing(rule) {
@@ -1048,7 +1054,7 @@ function perOwner({ cache, config, owner, build }) {
 	return schema;
 }
 const ruleSchemas = /* @__PURE__ */ new WeakMap();
-const PREVIEW_DESCRIPTION = "What the catalogue tile and the matrix render with, keyed by condition the way `styles` is. The `*` entry, `{ \"when\": null, \"props\": { ... } }`, is what every cell starts from; an entry with a condition, `{ \"when\": { \"type\": \"image\" }, \"props\": { \"src\": \"…\" } }`, adds its props to the cells whose values match, in the grammar a style rule uses. A slot prop previews with a stored element, `{ \"element\": { \"__ref\": \"component:<Name>\" } }`. A condition on a prop no rule styles makes that prop a preview axis with the value named. A component whose root takes children renders empty until an entry or `defaultProps` carries some.";
+const PREVIEW_DESCRIPTION = "What the catalogue tile and the matrix render with: a list of entries, each identified by its condition the way a style rule is. The entry `{ \"when\": null, \"props\": { ... } }` is what every cell starts from; an entry with a condition, `{ \"when\": { \"type\": \"image\" }, \"props\": { \"src\": \"…\" } }`, adds its props to the cells whose values match, in the grammar a style rule uses. A slot prop previews with a stored element, `{ \"element\": { \"__ref\": \"component:<Name>\" } }`. A condition on a prop no rule styles makes that prop a preview axis with the value named. A component whose root takes children renders empty until an entry or `defaultProps` carries some.";
 const previewShapeError = "a preview entry is `{ \"when\": null | { \"<prop>\": \"<value>\" }, \"props\": { \"<prop>\": <value> } }`: `when` names this component's own props at one of their values (`null` for the entry every cell reads) and `props` the props the matching cells preview with.";
 const previewBase = z.object({
 	when: z.record(z.string(), z.unknown()).nullable().default(null),
@@ -1534,7 +1540,7 @@ const componentFields = z.strictObject({
 	* forwards nothing rather than being quietly translated.
 	*/
 	forwards: Forward.optional(),
-	styles: StyleRule.optional(),
+	styles: orList(StyleRule).optional(),
 	/** The props the render reads that the component neither declares nor forwards — its render
 	*  extras (`.render<{ swatchColor?: string }>()`). Read off the render at build like `anatomy`,
 	*  never authored as data. The module consumes them; a component painted out of its anatomy has
@@ -1544,7 +1550,7 @@ const componentFields = z.strictObject({
 	defaultProps: Style.optional(),
 	/** What the tile and the matrix render with — see `preview({ defaultProps, when })`. Read off
 	*  `.preview()` at build, and written per cell from the matrix. */
-	preview: Preview.optional().describe(PREVIEW_DESCRIPTION),
+	preview: orList(Preview).optional().describe(PREVIEW_DESCRIPTION),
 	/**
 	* The source that implements this component — a ref, because the file is an entity the seal owns.
 	*
@@ -1671,31 +1677,52 @@ const ComponentEntity = defineEntity({
 		anatomy: AnatomyNode,
 		defaultProps: Style
 	},
-	computed: { 
-	/**
-	* The prop names an instance may fill through a spec element's `slots` field — every prop that
-	* routes content: a `slot`, or a `forward` whose far end takes content. Resolved over the
-	* inheritance chain, since an inherited slot is as fillable as a declared one. This is the
-	* `slots: string[]` json-render's catalog metadata declares per component, computed here so the
-	* emitted catalog, the validator, and every picker read one answer.
-	*/
-slots: ({ config, path, member }) => {
-		const layers = member.layers;
-		const names = [];
-		for (const [name, decl] of Object.entries(resolveComponentProps(config, path))) {
-			const body = decl;
-			if (!body) continue;
-			if (carriesContent(config, layers, body)) names.push(name);
+	computed: {
+		/**
+		* What each layer can forward, for the layers that render a component with props: every prop its
+		* element exposes, whether the layer forwards it now, and why one is blocked (the component
+		* declares it, or a sibling layer forwards it). Read before writing `forwards`, so "everything
+		* but icon" is a list the caller can spell.
+		*/
+		forwardable: ({ config, path, member }) => {
+			const out = {};
+			const body = member;
+			for (const layer of Object.keys(body.layers ?? {})) {
+				const options = forwardOptions({
+					config,
+					path,
+					layer,
+					member: body
+				});
+				if (options) out[layer] = options;
+			}
+			return out;
+		},
+		/**
+		* The prop names an instance may fill through a spec element's `slots` field — every prop that
+		* routes content: a `slot`, or a `forward` whose far end takes content. Resolved over the
+		* inheritance chain, since an inherited slot is as fillable as a declared one. This is the
+		* `slots: string[]` json-render's catalog metadata declares per component, computed here so the
+		* emitted catalog, the validator, and every picker read one answer.
+		*/
+		slots: ({ config, path, member }) => {
+			const layers = member.layers;
+			const names = [];
+			for (const [name, decl] of Object.entries(resolveComponentProps(config, path))) {
+				const body = decl;
+				if (!body) continue;
+				if (carriesContent(config, layers, body)) names.push(name);
+			}
+			return names;
 		}
-		return names;
-	} },
+	},
 	nameEdges: bagNameEdges(componentBags),
 	styleBags: componentBags,
 	rewriteName: bagRewriteName(componentBags),
 	schemas: {
 		create: {
 			data: componentFields,
-			description: "Create a component at a new qualified `path`. For a component with nothing in it yet, one to design on the canvas before it has props or variants, use `create-blank` with only a `path` instead of authoring a minimal body here. When its complete body is known, include all layers, anatomy, props, defaults, and styles in this one operation. `data.layers` maps each stable layer name to the element it renders and must include `root` — a tag for a primitive (`{ \"layers\": { \"root\": \"div\" } }`), and for anything built on top, a ref to a primitive (`{ \"root\": { \"__ref\": \"component:Box\" }, \"label\": { \"__ref\": \"component:Text\" } }`), which is what lets the layer take that primitive's style props. A primitive exposes style props as `{ \"type\": \"styleProperty\", \"value\": { \"__ref\": \"style-property:bg\" } }` and declares `children: { \"type\": \"slot\", \"text\": true }` when it holds content — without the slot, nothing nested inside it renders. A composed component exposes a layer's props at its own top level through `forwards`, keyed by layer: `{ \"forwards\": { \"root\": \"*\" } }` passes every prop the root's element takes (so `<Button width=\"full\">` reaches the root's `width`), and a list of member refs (`[{ \"__ref\": \"component:Box#props/width\" }]`, each naming the component that declares the prop) passes only those. A prop a layer already exposes is forwarded, never redeclared in `props`; a `props` entry of `{ \"type\": \"forward\" }` is the reverse route, one of this component's props into a layer's. `anatomy` is the tree the build would read off a render: each node renders a layer (`{ \"__ref\": \"layer:<name>\" }`), an intrinsic tag, or `Slot` (`{ \"element\": \"Slot\", \"props\": { \"name\": \"children\" } }`, where a slot prop's content lands — but a declared slot fills `root` by default, so a primitive still declares its `children` slot prop yet needs no `Slot` node or `children` entry for it, and a `Slot` node is only for landing that content in a nested layer); `children` lists sibling node keys from the `root` node, never a prop name; `text` is a fixed string; `visible` is a condition on a prop (`{ \"$state\": \"<prop>\" }`, or with `eq`); content shown in a nested layer is a route, `children: { \"type\": \"forward\", \"target\": \"label/children\" }`. `$state` appears only in `visible` and in an `element` a prop chooses, never as a prop value. A glyph is a node of its own, `{ \"element\": { \"__ref\": \"icon:<library>/<Name>\" } }`, listed in the `children` of the layer node that holds it, never a prop value. Text a prop supplies to a text layer is never a node either: declare the prop `{ \"type\": \"forward\", \"target\": \"<layer>/children\" }` and the layer shows it; a `Slot` node goes only under a layer that takes nodes. A style rule is `\"styles\": { \"*\": { \"when\": null, \"layers\": { \"root\": { \"bg\": \"surface\" } } } }`, keyed by a name, with each layer's bag under `layers`. A composed component carries its own styles: give it an unconditional (`\"*\"`) rule that lays out and surfaces it through the system's style properties — spacing, alignment and gap on the container, a background and color where it has one — rather than leaning on the bare primitives, which paint flat. Style a layer only with the style props the primitive it renders exposes, set to the values those props accept: `component/get` on the primitive lists both, so read it and choose from that rather than reaching for a CSS name or value the system has no style property for. Set `preview` (`{ \"*\": { \"when\": null, \"props\": { \"children\": \"Example\" } } }`) or `defaultProps` so the component previews with content; a root that takes children renders empty otherwise. A style rule's layer bag is keyed by style-prop name (`fontWeight`, `color`), never by CSS property name, and each value is one of that prop's values.",
+			description: "Create a component at a new qualified `path`. For a component with nothing in it yet, one to design on the canvas before it has props or variants, use `create-blank` with only a `path` instead of authoring a minimal body here. When its complete body is known, include all layers, anatomy, props, defaults, and styles in this one operation. `data.layers` maps each stable layer name to the element it renders and must include `root` — a tag for a primitive (`{ \"layers\": { \"root\": \"div\" } }`), and for anything built on top, a ref to a primitive (`{ \"root\": { \"__ref\": \"component:Box\" }, \"label\": { \"__ref\": \"component:Text\" } }`), which is what lets the layer take that primitive's style props. A primitive exposes style props as `{ \"type\": \"styleProperty\", \"value\": { \"__ref\": \"style-property:bg\" } }` and declares `children: { \"type\": \"slot\", \"text\": true }` when it holds content — without the slot, nothing nested inside it renders. A composed component exposes a layer's props at its own top level through `forwards`, keyed by layer: `{ \"forwards\": { \"root\": \"*\" } }` passes every prop the root's element takes (so `<Button width=\"full\">` reaches the root's `width`), and a list of member refs (`[{ \"__ref\": \"component:Box#props/width\" }]`, each naming the component that declares the prop) passes only those. A prop a layer already exposes is forwarded, never redeclared in `props`; a `props` entry of `{ \"type\": \"forward\" }` is the reverse route, one of this component's props into a layer's. `anatomy` is the tree the build would read off a render: each node renders a layer (`{ \"__ref\": \"layer:<name>\" }`), an intrinsic tag, or `Slot` (`{ \"element\": \"Slot\", \"props\": { \"name\": \"children\" } }`, where a slot prop's content lands — but a declared slot fills `root` by default, so a primitive still declares its `children` slot prop yet needs no `Slot` node or `children` entry for it, and a `Slot` node is only for landing that content in a nested layer); `children` lists sibling node keys from the `root` node, never a prop name; `text` is a fixed string; `visible` is a condition on a prop (`{ \"$state\": \"<prop>\" }`, or with `eq`); content shown in a nested layer is a route, `children: { \"type\": \"forward\", \"target\": \"label/children\" }`. `$state` appears only in `visible` and in an `element` a prop chooses, never as a prop value. A glyph is a node of its own, `{ \"element\": { \"__ref\": \"icon:<library>/<Name>\" } }`, listed in the `children` of the layer node that holds it, never a prop value. Text a prop supplies to a text layer is never a node either: declare the prop `{ \"type\": \"forward\", \"target\": \"<layer>/children\" }` and the layer shows it; a `Slot` node goes only under a layer that takes nodes. `styles` is a list of rules, `\"styles\": [{ \"when\": null, \"layers\": { \"root\": { \"bg\": \"surface\" } } }]`, each identified by its `when`, with each layer's bag under `layers`. A composed component carries its own styles: give it an unconditional (`\"when\": null`) rule that lays out and surfaces it through the system's style properties — spacing, alignment and gap on the container, a background and color where it has one — rather than leaning on the bare primitives, which paint flat. Style a layer only with the style props the primitive it renders exposes, set to the values those props accept: `component/get` on the primitive lists both, so read it and choose from that rather than reaching for a CSS name or value the system has no style property for. Set `preview` (`[{ \"when\": null, \"props\": { \"children\": \"Example\" } }]`) or `defaultProps` so the component previews with content; a root that takes children renders empty otherwise. A style rule's layer bag is keyed by style-prop name (`fontWeight`, `color`), never by CSS property name, and each value is one of that prop's values.",
 			example: ({ config }) => {
 				const path = freeExamplePath(config);
 				const composed = composedCreateExample(config, path);
@@ -1731,10 +1758,10 @@ slots: ({ config, path, member }) => {
 								children: ["icon", "content"]
 							}
 						},
-						preview: { ["*"]: {
+						preview: [{
 							when: null,
 							props: { children: "Example" }
-						} }
+						}]
 					}
 				};
 			}
@@ -1956,6 +1983,126 @@ slots: ({ config, path, member }) => {
 			}
 		},
 		/**
+		* Copy an element of a composition, with everything beneath it, right after it: each copy gets
+		* layers of its own, and every style rule that styles a copied layer styles its copy the same.
+		* One op for the reason `element-insert` is one: the layers, the nodes, the parent's edge and the
+		* rule bags are one gesture, and any of them alone is a copy that renders wrong.
+		*/
+		"element-duplicate": {
+			input: z.object({
+				path: pathInput("component"),
+				key: z.string(),
+				data: z.object({ 
+				/** How many copies, each after the last. */
+count: z.number().int().min(1).max(50).optional() }).prefault({})
+			}),
+			readOnly: false,
+			label: "Duplicate element",
+			description: "Copy an element of a component, with its subtree and its styles, right after it: each copy gets its own layers, and every style rule styling a copied layer styles the copy the same.",
+			scope: "item",
+			creates: true,
+			title: (entity) => `Duplicate ${entity} element`,
+			handler: (input, config) => {
+				const path = String(input.path);
+				const source = String(input.key);
+				const count = input.data?.count ?? 1;
+				const body = config.resolve("component", path)?.toJSON();
+				const anatomy = body?.anatomy ?? {};
+				if (!anatomy[source]) return rejectData(`"${source}" is not an element of ${path}.`, ["key"]);
+				const parentEntry = Object.entries(anatomy).find(([, node]) => [...node.children ?? [], ...Object.values(node.slots ?? {}).flat()].includes(source));
+				if (!parentEntry) return rejectData(`"${source}" is the root of ${path}; it has no place to copy into.`, ["key"]);
+				const [parent, parentNode] = parentEntry;
+				const slotProp = Object.entries(parentNode.slots ?? {}).find(([, fills]) => fills.includes(source))?.[0];
+				const subtree = [];
+				const visit = (at) => {
+					subtree.push(at);
+					const node = anatomy[at];
+					for (const kid of [...node?.children ?? [], ...Object.values(node?.slots ?? {}).flat()]) visit(kid);
+				};
+				visit(source);
+				const elements = Object.fromEntries(subtree.map((at) => {
+					const node = anatomy[at] ?? {};
+					return [at, {
+						element: body?.layers?.[at] ?? "div",
+						...node.props ? { props: node.props } : {},
+						...node.children?.length ? { children: node.children } : {},
+						...node.slots ? { slots: node.slots } : {},
+						...node.visible !== void 0 ? { visible: node.visible } : {},
+						...node.text !== void 0 ? { text: node.text } : {}
+					}];
+				}));
+				let next = config;
+				let previous = source;
+				for (let n = 0; n < count; n++) {
+					const key = freeLayerKey(next, path, source);
+					const siblings = (next.resolve("component", path)?.toJSON())?.anatomy?.[parent]?.children ?? [];
+					const index = siblings.indexOf(previous) + 1;
+					next = next.run([{
+						kind: "component",
+						operation: "element-insert",
+						path,
+						key,
+						data: {
+							parent,
+							...slotProp ? { slotProp } : { index: index > 0 ? index : siblings.length },
+							subtree: {
+								root: source,
+								elements
+							}
+						}
+					}]);
+					const writes = {};
+					for (const [rule, entry] of Object.entries(body?.styles ?? {})) for (const at of subtree) {
+						const bag = entry.layers?.[at];
+						if (bag === void 0) continue;
+						const copy = at === source ? key : graftKey(key, at);
+						writes[`styles.${rule}.layers.${copy}`] = bag;
+					}
+					if (Object.keys(writes).length > 0) next = next.apply({
+						kind: "component",
+						operation: "update",
+						path,
+						data: writes
+					});
+					previous = key;
+				}
+				return next;
+			}
+		},
+		/**
+		* Make a layer forward the props a request names. The stored write is the generic `forwards`
+		* `sub-upsert` or `sub-delete`; this op works out which, from what the layer forwards now.
+		*/
+		"layer-forward": {
+			input: z.object({
+				path: pathInput("component"),
+				/** The layer whose element's props are forwarded. */
+				key: z.string(),
+				data: z.object({
+					/** Every prop the layer can forward, or the ones to add to what it forwards now. */
+					props: z.union([z.literal("*"), z.array(z.string().min(1))]),
+					/** Props to leave out of either. */
+					except: z.array(z.string().min(1)).optional(),
+					/** Forward exactly `props`, dropping what the layer forwards now. */
+					replace: z.boolean().optional()
+				})
+			}),
+			readOnly: false,
+			label: "Forward layer props",
+			description: "Expose a layer's props at the component's top level (\"forward everything from the root but icon\", \"also forward width\"): `props` is `\"*\"` for every prop the layer's element takes, or a list added to what the layer forwards now, or that replaces it with `replace`; `except` leaves props out of either. A prop the element lacks, one the component declares itself, and one a sibling layer already forwards are refused. Read `component/get` for what a layer forwards now.",
+			scope: "item",
+			title: (entity) => `Forward ${entity} layer props`,
+			handler: (input, config) => {
+				const patch = forwardsWrite({
+					config,
+					path: String(input.path),
+					layer: String(input.key),
+					request: input.data
+				});
+				return patch ? config.apply(patch) : config;
+			}
+		},
+		/**
 		* Remove an element from a composition — the node, its layer, and everything that named it.
 		*
 		* A custom op for the same reason `element-insert` is: it writes more than one thing and either
@@ -2271,6 +2418,10 @@ const Component = Object.assign(ComponentEntity, {
 	slotHostedBy,
 	/** The named node slots alone, without a positioned `children`. */
 	namedSlots,
+	/** Every component slot whose `accepts` names an element. */
+	slotsFor,
+	/** What one layer can forward, and why a prop is blocked. */
+	forwardOptions,
 	/** The component under one coordinate of its matrix. */
 	cell: cellAt,
 	/** The component a design file's spec element places, with what the file put in its slots. */

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

@@ -248,9 +248,11 @@ type PinComponentAdjustment<E, P extends string> = {
 type PinComponentBody<E, P extends string> = Omit<PartialBodyOf<E>, 'styles'> & {
   styles?: StoredStylesOf<PartialBodyOf<E>> | PinStyleRules<P>;
 };
+/** The keyed record a body's `styles` is stored as, so a rule list is checked by
+ *  {@link PinStyleRules} against the linked component's layers rather than taken unchecked. */
 type StoredStylesOf<Body> = Body extends {
   styles?: infer Styles;
-} ? Styles : never;
+} ? Exclude<Styles, readonly unknown[]> : never;
 /** The linked contracts registered at `path`, from whichever source. */
 type LinkedContractKey<P extends string> = Extract<keyof RegisteredComponentContracts, `${P}@${string}`>;
 type PinStyleRules<P extends string> = [LinkedContractKey<P>] extends [never] ? readonly StyleRuleInput<LayerMap>[] : ContractStyleRules<RegisteredComponentContracts[LinkedContractKey<P>]>;
@@ -259,10 +261,15 @@ type LinkDeclaration = '*' | Record<string, '*' | readonly string[]>;
 /** One `options` entry, checked against the kind its accessor addresses. The runtime floor — that an
  *  entry names at least one of the three — is the schema's `refine`, which reports the path. */
 type PinAdjustment<E> = {
-  override?: PartialBodyOf<E>;
-  extend?: PartialBodyOf<E>;
+  override?: StoredBodyOf<PartialBodyOf<E>>;
+  extend?: StoredBodyOf<PartialBodyOf<E>>;
   hidden?: boolean;
 };
+/** A body with its `styles` as the keyed record it is stored as. A rule list is taken only where
+ *  {@link PinOptionsInput} checks it against the linked component's layers. */
+type StoredBodyOf<Body> = 'styles' extends keyof Body ? Omit<Body, 'styles'> & {
+  styles?: StoredStylesOf<Body>;
+} : Body;
 /**
  * One `options` entry as stored — what this config does to that path, with the two bodies left open.
  *

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

@@ -3,6 +3,9 @@ import { Named } from "../../framework/named.js";
 import { z } from "zod";
 
 //#region src/entities/system/Motion.d.ts
+/** The fields of a JS preset that `motion.create` reads as props, in schema order. The emitter
+ *  reads this rather than restating the schema, so a field added here reaches every emitted preset. */
+declare const jsMotionPropFields: readonly string[];
 declare const MotionDefinition: EntityClass<z.ZodDiscriminatedUnion<[z.ZodObject<{
   runtime: z.ZodLiteral<"css">;
   keyframes: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>;
@@ -16,6 +19,7 @@ declare const MotionDefinition: EntityClass<z.ZodDiscriminatedUnion<[z.ZodObject
   runtime: z.ZodLiteral<"js">;
   initial: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
   animate: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  exit: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
   transition: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
   whileHover: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
   whileTap: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
@@ -28,4 +32,4 @@ declare const MotionDefinition: EntityClass<z.ZodDiscriminatedUnion<[z.ZodObject
 interface MotionClass extends Named<typeof MotionDefinition> {}
 declare const Motion: MotionClass;
 //#endregion
-export { Motion, MotionClass };
+export { Motion, MotionClass, jsMotionPropFields };

package/dist/entities/system/Motion.js

@@ -6,7 +6,8 @@ import { z } from "zod";
 * coupled to how it animates, not loosely optional:
 *  - `css` → `keyframes` REQUIRED (codegen emits `@keyframes` from them); a css preset with
 *    no keyframes — which used to validate and silently emit nothing — is now rejected.
-*  - `js`  → no keyframes; carries the interaction state the client drives.
+*  - `js`  → no keyframes; carries the interaction state the client drives, `exit` included,
+*    which runs under an `AnimatePresence` ancestor when the element unmounts.
 * Illegal cross-runtime mixes (a css preset with `animate`, a js preset with `keyframes`)
 * can't be represented — each member is strict.
 *
@@ -30,6 +31,7 @@ const JsMotion = z.strictObject({
 	runtime: z.literal("js").describe(RUNTIME),
 	initial: gesture.describe("The starting values, as `motion/react` reads them."),
 	animate: gesture.describe("The values to animate to."),
+	exit: gesture.describe("The values to animate to as the element leaves."),
 	transition: gesture.describe("How the animation moves, such as a spring."),
 	whileHover: gesture.describe("Values held while the element is hovered."),
 	whileTap: gesture.describe("Values held while the element is pressed."),
@@ -39,6 +41,9 @@ const JsMotion = z.strictObject({
 	dragConstraints: z.record(z.string(), z.number()).optional().describe("The box a drag stays within."),
 	dragElastic: z.number().optional().describe("How far past its constraints a drag can stretch.")
 });
+/** The fields of a JS preset that `motion.create` reads as props, in schema order. The emitter
+*  reads this rather than restating the schema, so a field added here reaches every emitted preset. */
+const jsMotionPropFields = Object.keys(JsMotion.shape).filter((field) => field !== "runtime");
 const Motion = defineEntity({
 	kind: "motion",
 	label: "Motion",
@@ -46,4 +51,4 @@ const Motion = defineEntity({
 	fields: z.discriminatedUnion("runtime", [CssMotion, JsMotion])
 });
 //#endregion
-export { Motion };
+export { Motion, jsMotionPropFields };

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

@@ -0,0 +1,46 @@
+import { ComponentBody } from "./Component.js";
+import { Config } from "../../framework/Config.js";
+
+//#region src/entities/system/component-forwards.d.ts
+/** Why a prop can't be forwarded from a layer: the component declares it itself, which always wins
+ *  over a forward, or a sibling layer's entry already delivers it. */
+type ForwardBlockedReason = {
+  readonly by: 'own';
+} | {
+  readonly by: 'layer';
+  readonly layer: string;
+};
+/** One prop a layer's element exposes, as a forward from that layer sees it. */
+interface ForwardOption {
+  readonly name: string;
+  /** Whether the layer's `forwards` entry covers it now. */
+  readonly forwarded: boolean;
+  readonly blocked?: ForwardBlockedReason;
+}
+/** What one layer of a component can forward, and what it forwards now. */
+interface ForwardOptions {
+  /** Every prop the layer's element exposes, in name order. */
+  readonly options: readonly ForwardOption[];
+  /** Whether the layer has a `forwards` entry at all. */
+  readonly forwarded: boolean;
+}
+/**
+ * What `layer` of the component at `path` can forward. An option the component declares itself, or a
+ * sibling layer already delivers, is listed with the reason it's blocked rather than left out. Null
+ * when the layer renders a tag, or its element declares no props.
+ */
+declare function forwardOptions(args: {
+  config: Config;
+  path: string;
+  layer: string;
+  member?: ComponentBody;
+}): ForwardOptions | null;
+/** What a forward asks for: every prop, or a list that joins what the layer forwards now unless it
+ *  replaces it, less `except`. */
+interface ForwardRequest {
+  readonly props: '*' | readonly string[];
+  readonly except?: readonly string[];
+  readonly replace?: boolean;
+}
+//#endregion
+export { ForwardBlockedReason, ForwardOption, ForwardOptions, ForwardRequest, forwardOptions };