@yahoo/uds-v5-wip 1.60.0 → 1.62.0

package/dist/config/dist/types.d.ts

@@ -1,72 +1,705 @@
+import { ComponentRef, CompositeRef, ModeRef, TagRef, TokenGroupRef, TokenRef } from "./refs.js";
+import { ColorExpression } from "./colorExpressions.js";
+import { CssPropertyName, CssPropertyValues } from "./types/css-properties.js";
+import { IconAssetMetadata } from "./defineAssetGroup.js";
+
 //#region ../config/dist/types.d.ts
 //#region src/types.d.ts
 /**
- * Scalar DTCG-aligned token types. Composite types (shadow, gradient,
- * typography, border, transition, cubicBezier) are intentionally deferred
- * to a future RFC — they require structured (non-string) value shapes.
- *
- * `string` is the catch-all for raw CSS values (keywords like `inherit`,
- * `currentColor`, `transparent`, and anything else that does not fit a
- * more specific type). It is also the graceful fallback when no type
- * can be determined.
- */
-type TokenType = 'color' | 'dimension' | 'number' | 'fontFamily' | 'fontWeight' | 'duration' | 'strokeStyle' | 'string';
-/**
- * A single design token definition with a base value and optional modifier overrides.
- * Modifier keys use the `_` prefix convention (e.g., `_dark`, `_hover`).
- *
- * Modifier values can be flat strings (`_dark: '#88bcfb'`) or nested token defs
- * that introduce further modifiers — useful for stacking modes from different
- * sets (e.g. `_slate: { value: '#1167f4', _dark: '#88bcfb' }` for the slate
- * theme's dark variant). The emitter joins each level's selector to form a
- * compound CSS selector (`[data-theme="slate"].dark`).
- *
- * When `M` is narrowed (e.g., `'_dark' | '_light'`), only those modifier keys are
- * accepted — TypeScript will flag unknown modifiers like `_eggs` at compile time.
- *
- * The optional `$type` annotation lets individual tokens override the group-level
- * type (e.g. a `keyword`-valued token inside a `color` namespace).
- *
- * @example
- * { value: '#1167f4', _dark: '#88bcfb' }
- * { value: 'transparent', $type: 'string' }
- * { value: '#1167f4', _slate: { value: '#1167f4', _dark: '#88bcfb' } }
- */
-type VarTokenDef<M extends `_${string}` = `_${string}`> = {
-  value: string;
-  $type?: TokenType;
-} & { [K in M]?: string | VarTokenDef<M> };
-/**
- * A group of named tokens within a var namespace.
- *
- * The group may declare a `$type` that applies to all tokens in the group;
- * individual tokens may override it with their own `$type`. A `$description`
- * is free-form documentation surfaced in Studio (e.g. as the readonly subtitle
- * on the token group editor) and is otherwise inert at runtime.
- *
- * @example
- * {
- *   $type: 'color',
- *   $description: 'Brand-aligned semantic colors. Light/dark pairs only.',
- *   brand: { value: '#1167f4', _dark: '#88bcfb' },
- *   accent: { value: '#7c3aed' },
- * }
- */
-type VarGroupDef<M extends `_${string}` = `_${string}`> = {
-  $type?: TokenType;
-  $description?: string;
-} & {
-  [tokenName: string]: VarTokenDef<M> | TokenType | string | undefined;
+ * CSS value-type names used to tag a token. The scaffold leaves the
+ * union open so token-type tightening (a closed CSS-value-type union)
+ * lands as a follow-up — needs to ship with type-narrowing on
+ * `defineStyleProp({ values: ... })` to be useful.
+ */
+type TokenType = string;
+/**
+ * What a token's `value` can hold:
+ *
+ * - A literal — `string` (`'#1167f4'`, `'1rem'`), `number`, `boolean`.
+ * - A `token('ns/name')` marker pointing at another token.
+ * - A structured `ColorExpression` — `mix(...)`, `alpha(...)`,
+ *   `linearGradient(...)`, `radialGradient(...)`. Codegen resolves the
+ *   expression to a CSS function call (`color-mix(...)`,
+ *   `linear-gradient(...)`) via `resolveColorExpression`.
+ */
+type TokenValue = string | number | boolean | TokenRef | ColorExpression;
+type TokenModifierKey = `_${string}`;
+type TokenModifierValue = TokenValue | TokenDefinition;
+/**
+ * Authored shape for one token. Modifier values live as flat `_${key}`
+ * properties on the same object — matches the doc's example
+ * `{ value: '#1167f4', _dark: '#88bcfb' }` and the wire format.
+ *
+ * `Token` normalizes flat keys into a `modifiers` map at construction
+ * time so consumers reading the class instance work with the
+ * doc-described class shape.
+ */
+type TokenDefinition = {
+  value: TokenValue;
+  type?: TokenType;
+} & { [K in `_${string}`]?: TokenModifierValue };
+/**
+ * Authored shape — the bare tokens record. Mirrors the old `@uds/config`
+ * `defineTokenGroup(tokens)` signature: input is the tokens map; group
+ * metadata (label / description) is attached separately via the
+ * registration call, not nested under a wrapper.
+ */
+/**
+ * A token group: a tokens record + optional Studio-facing metadata.
+ * Mirrors main's `TokenGroupDef`. The parent record key in
+ * `registerTokenGroups({...})` carries the namespace, so it doesn't
+ * appear here. Tokens nest under `tokens` so a token named `'label'`
+ * (or any meta key) can never collide with group metadata.
+ */
+interface TokenGroupDefinition {
+  tokens: Record<string, TokenDefinition>;
+  label?: string;
+  description?: string;
+}
+/**
+ * Alias for the on-disk wire shape — structurally identical to
+ * `TokenGroupDefinition`. Used as the return type of
+ * `TokenGroup.toJSON()` so the serialization intent reads at call
+ * sites; consumers reading `config.json` see `SerializedTokenGroup`,
+ * authors writing `registerTokenGroups` see `TokenGroupDefinition`.
+ */
+type SerializedTokenGroup = TokenGroupDefinition;
+interface ModifierDefinition {
+  selector?: string | CompositeRef | ModeRef;
+  media?: string;
+  description?: string;
+}
+interface ModeOptionDefinition {
+  /**
+   * Modifier the option contributes. Defaults to `_${optionName}` —
+   * `colorMode: { options: { light: {...}, dark: {...} } }` produces
+   * modifiers `_light` and `_dark` without restating them. Override
+   * when the option name and the desired modifier should differ.
+   */
+  modifier?: TokenModifierKey;
+  label?: string;
+  description?: string;
+  /**
+   * CSS selector text the option produces — for `colorMode/dark`,
+   * `'.dark'` so consumers can write `<html class="dark">` and have
+   * the dark-mode tokens apply. Mirrors the old
+   * `@uds/config` `ModeOptionInput.css` field name.
+   */
+  css?: string;
+  media?: string;
+}
+type ModeDefinition = Record<string, ModeOptionDefinition>;
+type CompositeStyleObject = Record<string, unknown>;
+interface CompositeStyleDefinition {
+  label: string;
+  description?: string;
+  /**
+   * Named style variants keyed by variant name. Mirrors the old
+   * `@uds/config` `defineCompositeStyle({ styles })` field name —
+   * authors write `styles: { sm: {...}, md: {...} }`.
+   */
+  styles: Record<string, CompositeStyleObject>;
+}
+/**
+ * Any CSS property name `defineStyleProp` can target. Standard
+ * property names come from the `CssPropertyValues` registry; custom
+ * CSS properties (`--*`) are open template strings.
+ */
+type StylePropProperty = CssPropertyName | `--${string}`;
+/**
+ * Literal-keyword subset accepted by a CSS property. For standard
+ * properties, falls out of `CssPropertyValues[P]`. For custom CSS
+ * properties (`--*`), open string — narrowing happens via the
+ * `cssType` field on the style-prop spec.
+ */
+type LiteralFor<P extends StylePropProperty> = [P] extends [CssPropertyName] ? Extract<CssPropertyValues[P], string> : string;
+/**
+ * Author-friendly alias for a CSS keyword. `alias` is what the JSX
+ * value site uses (`flexDirection="col"`); `value` is the underlying
+ * CSS the prop resolves to.
+ *
+ *  - `string` — a single CSS keyword (`'column'`).
+ *  - `Record<string, string>` — a multi-property emission, used to
+ *    write vendor-prefixed pairs (`{ '-webkit-user-select': 'none',
+ *    'user-select': 'none' }`) so a single utility class sets both at
+ *    once and matches Tailwind's built-in body byte-for-byte (avoids
+ *    cascade overrides).
+ *
+ * `value` is kept un-narrowed here — per-property narrowing via
+ * `LiteralFor<P>` would explode the union across every CSS property
+ * and hit TS's "too complex" limit.
+ */
+interface ValueAlias {
+  alias: string | boolean | number;
+  value: string | Record<string, string>;
+}
+/**
+ * A single entry in a style-prop's `values` array. Narrowed against
+ * the chosen `cssProperty` so authoring sites like
+ * `values: ['banana']` on a `border-color` prop error at compile time.
+ *
+ *  - `TokenGroupRef` — pulls every token in the named namespace
+ *    into the prop's accepted value set.
+ *  - `LiteralFor<P>` — a CSS keyword the property accepts per spec
+ *    (e.g. `'transparent'` for `border-color`).
+ *  - `number` — bare numeric values where CSS itself accepts numbers
+ *    (e.g. `line-clamp: 3`).
+ *  - `ValueAlias<P>` — `{ alias, value }` pair for Tailwind-style
+ *    shorthands; the alias appears at the JSX value site and resolves
+ *    to the underlying CSS keyword at emit time.
+ */
+type ValuesEntry<P extends StylePropProperty = StylePropProperty> = TokenGroupRef | LiteralFor<P> | number | ValueAlias;
+interface ArbitrarySpec {
+  type?: TokenType;
+}
+/**
+ * One entry in a multi-shape `arbitrary` array. `toCss` lets the prop
+ * coerce a runtime value into the actual CSS string (e.g. wrapping a
+ * raw `'1px'` in `var(--...)` or stitching multi-property output). The
+ * `regex` variant accepts any string matching a pattern instead of
+ * binding to a named value type.
+ */
+type ArbitraryEntry = {
+  type: TokenType;
+  toCss?: (value: unknown) => string;
+} | {
+  type: 'regex';
+  pattern: RegExp;
+  toCss?: (value: string) => string;
 };
 /**
- * Top-level vars config — namespaces to groups of tokens.
+ * Author-time shape for `arbitrary`. Four forms:
+ *  - `true` — accept any bracketed value, passed through verbatim into the
+ *    prop's `cssProperty` (`arbitrary: true` → `blur="[blur(6px)]"` →
+ *    `filter: blur(6px)`). Use when the bracket already carries the full CSS
+ *    value and needs no data-type validation or transform.
+ *  - bare `TokenType` string (`arbitrary: 'length-percentage'`) —
+ *    shorthand for `{ type: ... }`.
+ *  - `ArbitrarySpec` object (`arbitrary: { type: 'color' }`).
+ *  - `ArbitraryEntry[]` for multi-shape props that accept several
+ *    value-type variants (e.g. `grid-template-rows` taking integers,
+ *    length-percentages, and full track lists).
+ * Normalized at `StyleProp` construction time (`true` → `{}`).
+ */
+type ArbitraryInput = boolean | TokenType | ArbitrarySpec | readonly ArbitraryEntry[];
+/**
+ * Authored shape attached by `defineStyleProp(spec).withOpacity({...})`.
+ * Declares a paired opacity sibling style-prop: the parent emits
+ * `${classPrefix}-${tokenName}` for the bare value AND
+ * `${classPrefix}-${tokenName}${separator}${opacityValue}` when the
+ * sibling prop is set. The sibling itself is registered alongside the
+ * parent at `registerStyleProps` time.
+ *
+ * `ref` (deprecated alias for `as`) is kept for back-compat with sites
+ * that read the opacity pair as `{ ref }` — codegen's `extractClasses.ts`
+ * checks `opacityPair.ref` directly.
+ */
+interface OpacityPairSpec {
+  /** JSX-prop name for the opacity sibling (e.g. `'bgOpacity'`). */
+  as: string;
+  /** Token group the opacity sibling pulls values from. */
+  values: TokenGroupRef;
+  /**
+   * Class-name separator between the parent's token suffix and the
+   * opacity value. Defaults to `'_'`. Pass `'/'` for Tailwind-flavored
+   * output (`bg-primary/75`).
+   */
+  separator?: string;
+  /** Back-compat alias of `as`. New code should use `as`. */
+  ref?: string;
+}
+/**
+ * Authoring metadata attached via `defineStyleProp(spec).metadata({...})`.
+ * Consumed by codegen prompt artifacts and Studio's UI. Kept open
+ * (`Readonly<Record<string, unknown>>`) — `label` / `description` are
+ * the conventional fields but the slot doesn't enforce.
+ */
+type StylePropMetadata = Readonly<Record<string, unknown>>;
+/**
+ * Authoring metadata attached via
+ * `defineComponent(...).config(...).metadata({...})`. `description`
+ * shows up in codegen's AI prompt artifact next to the component name;
+ * `events` lists React/HTML event handler names the component supports
+ * (`'focus'`, `'press'`, etc.) — when unset, the synthesizer falls
+ * back to the standard React event roster. `deprecated` keeps a component
+ * out of the AI prompt artifact while leaving it registered and renderable.
+ */
+interface ComponentMetadata {
+  /**
+   * Human-facing display name for Studio's palette. Defaults to the
+   * component's registered name when absent. Lets two components present
+   * the same label (e.g. both "Badge") while keeping distinct, stable
+   * identities (`uds:Badge` vs `uds:StudioBadge`) — identity stays the
+   * registered name, never this label.
+   */
+  readonly label?: string;
+  readonly description?: string;
+  readonly events?: readonly string[];
+  /**
+   * Marks the component as deprecated. Deprecated components are omitted
+   * from codegen's AI prompt artifact so the model won't reach for them in
+   * new work — they remain fully registered and renderable everywhere else.
+   */
+  readonly deprecated?: boolean;
+}
+/**
+ * Authored shape for `defineStyleProp`. `P` is the CSS property name
+ * (or names, when `cssProperty` is an array of side-shorthand props)
+ * — `values` narrows against `LiteralFor<P>` so unsupported keywords
+ * surface at the authoring site.
+ *
+ * No default for `P`: the wide case would force TypeScript to
+ * materialize `Extract<CssPropertyValues[CssPropertyName], string>`
+ * (a giant union) at every reference site. Wide-typed consumers
+ * (`Config.styleProps`, the wire format) use `AnyStylePropDefinition`
+ * instead.
+ */
+interface StylePropDefinition<P extends StylePropProperty> {
+  cssProperty: P | readonly P[];
+  classPrefix: string;
+  /**
+   * Token-group refs + literal keywords + bare numbers the prop accepts.
+   * Optional — `values: []` (or omitting it) is meaningful for props
+   * that only take arbitrary `[...]` escape values (e.g. `motion`).
+   */
+  values?: readonly ValuesEntry<P>[];
+  arbitrary?: ArbitraryInput;
+  /**
+   * Marks the prop as emitting a *negative* value: the resolved token or
+   * arbitrary value is wrapped in `calc(<value> * -1)` at emit time, so
+   * `offsetTop="3"` (a `negative` prop) paints
+   * `margin-top: calc(var(--uds-spacing-3) * -1)`. This flag is the single
+   * source of negativity — both the build-time emitter (`prepareCss`) and
+   * the runtime injector (`renderGetStyles`) read it, replacing the old
+   * `classPrefix.startsWith('-')` heuristic. It's also the structured signal
+   * the MCP / AI guidance / spec lint use to identify overlap-prone props.
+   *
+   * Negative props conventionally still use a `-`-led `classPrefix` (`-mt`)
+   * so the utility reads as a Tailwind negative class (`.-mt-3`) and stays
+   * distinct from a positive sibling (`marginTop` → `.mt-3`) — but the prefix
+   * only *names* the class; this flag *drives* the negation.
+   */
+  negative?: boolean;
+  cssType?: TokenType;
+  metadata?: StylePropMetadata;
+  opacityPair?: OpacityPairSpec;
+  /**
+   * Optional value coercion the renderer applies after token resolution.
+   * Takes the resolved value (number for bare-numeric tokens, string
+   * otherwise) and returns the final CSS string. Lets props like
+   * `gridTemplateColumns` accept `12` and emit
+   * `repeat(12, minmax(0, 1fr))`.
+   */
+  transform?: (value: string | number) => string;
+}
+/**
+ * Wide structural shape used by `Config.registerStyleProps` and the
+ * `StyleProp` class storage. Any concretely-narrowed
+ * `StylePropDefinition<P>` is assignable to this. `values` is the
+ * un-narrowed marker/literal/number union — runtime treats every
+ * entry uniformly, so the narrowing in `StylePropDefinition<P>` is
+ * purely an authoring-time check.
+ */
+interface AnyStylePropDefinition {
+  cssProperty: StylePropProperty | readonly StylePropProperty[];
+  classPrefix: string;
+  values?: readonly (TokenGroupRef | string | number | ValueAlias)[];
+  arbitrary?: ArbitraryInput;
+  /** See {@link StylePropDefinition.negative} — emit `calc(<value> * -1)`. */
+  negative?: boolean;
+  cssType?: TokenType;
+  metadata?: StylePropMetadata;
+  opacityPair?: OpacityPairSpec;
+  transform?: (value: string | number) => string;
+}
+type MotionKeyframes = Record<string, Record<string, unknown>>;
+interface MotionTransition {
+  duration?: number | string;
+  delay?: number | string;
+  ease?: string | readonly number[];
+  [key: string]: unknown;
+}
+interface MotionStateKeyframe {
+  [key: string]: unknown;
+}
+interface CssMotionDefinition {
+  runtime: 'css';
+  keyframes: MotionKeyframes;
+  transition?: MotionTransition;
+  /**
+   * Open index signature for `animation-*` CSS shorthand fields the
+   * old `@uds/config` placed directly on the motion def
+   * (`animationDuration`, `animationTimingFunction`, etc.). Codegen
+   * reads them off the toJSON'd shape and folds them into the emitted
+   * `animation: ...` declaration alongside the keyframes/transition.
+   */
+  [key: string]: unknown;
+}
+interface JsMotionDefinition {
+  runtime: 'js';
+  initial?: MotionStateKeyframe;
+  animate?: MotionStateKeyframe;
+  /**
+   * Exit keyframes — applied when the host element unmounts. Requires
+   * the consumer to render the slot conditionally so the JS runtime
+   * (`motion/react`'s `<AnimatePresence>`) can play the exit before the
+   * node detaches.
+   */
+  exit?: MotionStateKeyframe;
+  transition?: MotionTransition;
+  /** Keyframes applied while the element is hovered. */
+  whileHover?: MotionStateKeyframe;
+  /** Keyframes applied while the element is actively pressed. */
+  whileTap?: MotionStateKeyframe;
+}
+type MotionDefinitionInput = CssMotionDefinition | JsMotionDefinition;
+/**
+ * Layer-with-overrides shape — the old `@uds/config` authoring form
+ * where a layer carries its tag and its per-layer overrides
+ * (`defaultProps`, `base`, etc.) inline. Codegen reads `tag` to set
+ * the layer's element and the remaining fields contribute to the
+ * layer's emitted styles. Used in tests + legacy configs; the
+ * structured marker forms (`tag('div')` etc.) are preferred for new
+ * code because they round-trip cleanly through JSON.
+ */
+interface LayerWithOverrides {
+  tag: string | TagRef | ComponentRef;
+  defaultProps?: Record<string, unknown>;
+  base?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+/**
+ * What can appear as a layer's value in `defineComponent`'s `layers`
+ * map. Five authoring forms:
+ *
+ *  - bare tag name string — `'div'`, `'span'`. The old `@uds/config`
+ *    layer syntax; `Component` normalizes to a `TagRef` at construction.
+ *  - `TagRef` — `tag('div')` marker form (equivalent to the bare
+ *    string; both produce the same on-disk shape).
+ *  - `ComponentRef` — string-keyed reference to a registered
+ *    component (`component('Box')`).
+ *  - `ComponentDefinition` value — the registered component itself
+ *    (`{ root: Box, trigger: Pressable }`). Identity-keyed; codegen
+ *    resolves it back to a component name via its
+ *    `configToName` reverse map at type-narrowing + class-extraction
+ *    time. Permits ergonomic `.layers({ root: Box })` authoring.
+ *  - `LayerWithOverrides` — `{ tag, defaultProps?, base?, ... }`. The
+ *    old layer-with-overrides shape; `Component` lifts `tag` onto
+ *    `Layer.tag` and leaves the remaining fields on the layer entry
+ *    for codegen to read.
+ */
+type LayerInput = string | TagRef | ComponentRef | ComponentDefinition | LayerWithOverrides;
+type BaseStyles = Record<string, Record<string, unknown>>;
+interface CompoundPropsEntry {
+  when: Record<string, unknown>;
+  layers: Record<string, unknown>;
+}
+/**
+ * Per-layer framer-motion spec a component carries inline. Mirrors
+ * main's `SlotMotion`: every field is `unknown` because the framer-
+ * motion API surface is wide and we don't want to lock authoring to
+ * a particular `motion/react` version. Codegen passes the value
+ * through to the runtime renderer.
+ */
+interface SlotMotion {
+  readonly runtime?: 'js' | 'css';
+  readonly initial?: unknown;
+  readonly animate?: unknown;
+  readonly exit?: unknown;
+  readonly transition?: unknown;
+  readonly whileHover?: unknown;
+  readonly whileTap?: unknown;
+  readonly drag?: unknown;
+  readonly dragConstraints?: unknown;
+  readonly dragElastic?: unknown;
+}
+/**
+ * Component-level motion field. Three shapes:
+ *  - `string` — alias of a `registerMotion({...})` preset.
+ *  - `{ runtime, ... }` — inline `SlotMotion` applied to the root.
+ *  - `Record<string, SlotMotion>` — per-layer record keyed by layer
+ *    name (`{ icon: {...}, menu: {...} }`); each layer animates
+ *    independently with its own framer config.
+ */
+type ComponentMotionValue = string | SlotMotion | Record<string, SlotMotion>;
+type PropBinding = unknown;
+/**
+ * Extract the literal HTML tag from a `layers` map when it can be read
+ * statically. Returns the bare-tag literal (`'a' | 'div' | ...`) when:
+ *
+ *  - `layers.root` is a bare tag string (`'a'`),
+ *  - `layers.root` is a `TagRef<'a'>` marker,
+ *  - `layers.root` is a `LayerWithOverrides` (`{ tag: 'a', ... }`) where
+ *    `tag` is a bare string or `TagRef`, or
+ *  - `layers.root` is a value-extend wrapper carrying its own captured
+ *    root tag (recurses one level so `defineComponent(Box)` inherits
+ *    Box's `'div'` root tag).
+ *
+ * Returns `undefined` when `layers.root` is a value-extend wrapper
+ * without a captured tag, or when the field is absent. `Props<T>`
+ * reads this and substitutes `ComponentPropsWithRef<TTag>` for the
+ * generic `HTMLAttributes<HTMLElement>` when narrowable.
+ */
+type RootTag<TLayers> = TLayers extends {
+  root: infer R;
+} ? R extends string ? R : R extends {
+  __kind: 'tag';
+  ref: infer T extends string;
+} ? T : R extends {
+  tag: infer T extends string;
+} ? T : R extends {
+  tag: {
+    __kind: 'tag';
+    ref: infer T extends string;
+  };
+} ? T : R extends {
+  defaultProps: {
+    as: infer A extends string;
+  };
+} ? A : R extends ComponentDefinition<Record<string, LayerInput>, Record<string, PropBinding>, infer TInnerTag> ? TInnerTag : undefined : undefined;
+/**
+ * Structural shape of a `defineComponent` config. Parameterized over its
+ * `layers`, `props`, and the resolved root tag so a wrapping `Props<T>`
+ * walker can read each piece independently without unfolding the wide
+ * structural surface at every recursion.
+ *
+ * Defaults match the historic open shape so existing 70+ use sites that
+ * write `ComponentDefinition` un-parameterized continue to typecheck —
+ * the narrow forms only kick in when authoring chains thread literal
+ * generics through (`defineComponent('div')` → `TTag = 'div'`).
+ */
+interface ComponentDefinition<TLayers extends Record<string, LayerInput> = Record<string, LayerInput>, TProps extends Record<string, PropBinding> = Record<string, PropBinding>, TTag extends string | undefined = string | undefined> {
+  layers: TLayers;
+  props?: TProps;
+  base?: BaseStyles;
+  defaultProps?: Record<string, unknown>;
+  compoundProps?: readonly CompoundPropsEntry[];
+  motion?: ComponentMotionValue;
+  /**
+   * Phantom slot — populated only as a type marker (never read at
+   * runtime) so `RootTag<TLayers>` callers can fall back to this when
+   * the layer's root is a value-extend wrapper. The value-extend chain
+   * threads its captured `TTag` through here.
+   */
+  readonly __tag?: TTag;
+}
+/**
+ * Authored shape for a component's preview block — attached via
+ * `defineComponent({...}).preview({...})`. Carries the data Studio +
+ * codegen need to render a component tile: `defaultProps` is the
+ * baseline JSX prop bag; `matrix` declares the axes for the canvas
+ * grid view. Stored verbatim on `Component.preview` and round-trips
+ * through JSON unchanged.
+ *
+ * Named `PreviewDefinition` to match the package's `*Definition`
+ * convention and avoid confusion with json-render's `spec` (the
+ * canvas-renderable tree that lives at `ManifestPreviewEntry.spec`).
+ *
+ * `matrix.columns` / `matrix.rows` are typed as `unknown[]` — concrete
+ * axis-entry shapes (prop-axis, modifier-axis) belong to the renderer
+ * surface, not the authoring contract.
+ */
+interface PreviewDefinition<TProps extends Record<string, unknown> = Record<string, unknown>> {
+  /**
+   * Authored — passed to `.preview({ defaultProps })`. Narrowed against
+   * the component's resolved JSX prop shape so callback params
+   * (`onSubmit: (event) => ...`) infer from the component's declared
+   * `TExtra` rather than collapsing to `any`. Falls back to the wide
+   * `Record<string, unknown>` when the call site doesn't supply a
+   * `TProps` generic (Studio + codegen consume the loose shape).
+   */
+  readonly defaultProps?: Partial<TProps>;
+  /** Authored — passed to `.preview({ matrix })`. Drives the canvas grid view. */
+  readonly matrix?: {
+    readonly columns?: readonly unknown[];
+    readonly rows?: readonly unknown[];
+  };
+  /**
+   * Codegen-extracted — parsed json-render spec from
+   * `defaultProps.children` JSX. Studio's canvas + docs read this to
+   * render the preview tile. Plain JSON (no functions / React elements).
+   */
+  readonly spec?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Wire shape for a component — what lands in `config.json`. The
+ * authored `ComponentDefinition` plus the two enrichments that aren't
+ * authored at the call site: `preview` (added by the `.preview()`
+ * chain) and `sourceFilePath` (stack-walked by `captureCallerPath` at
+ * `defineComponent` time). Kept separate from `ComponentDefinition`
+ * so IDE completions inside `defineComponent({...})` don't suggest
+ * fields the author can't write directly.
+ */
+interface SerializedComponent extends ComponentDefinition {
+  preview?: PreviewDefinition;
+  /**
+   * Path of the file that defined the component. Relative to
+   * `meta.projectRoot` when `Config.toJSON({ projectRoot })` is used
+   * (CLI's path) — keeps `config.json` portable across machines.
+   * Absolute when serialized without a `projectRoot`.
+   */
+  sourceFilePath?: string;
+  /**
+   * Set on a sub-part — name of the parent that owns it. Mirrors
+   * `Component.derived.subcomponentOf`. The authored relationship is
+   * declared on the parent via `.subcomponents({...})`; this field is
+   * the wire-format echo so `Config.fromJSON` can rebuild the linkage
+   * without re-running the original `.subcomponents` chain.
+   */
+  subcomponentOf?: string;
+  /**
+   * Name of the component this one value-extends via `defineComponent(Source)`.
+   * Mirrors `Component.extendsFrom`; lets consumers diff a child's props
+   * against the parent's instead of re-listing the inherited surface.
+   */
+  extendsFrom?: string;
+  /**
+   * Set on a parent — child names declared via `.subcomponents({...})`.
+   * Mirrors `Component.derived.subcomponents`.
+   */
+  subcomponents?: readonly string[];
+}
+/**
+ * Authored shape for a component group — a labeled bundle of
+ * registered components surfaced together in the Studio palette,
+ * codegen catalog, and AI prompt.
+ *
+ * `components` is keyed by the registration name (same surface as
+ * `registerComponents`); each value is a plain `ComponentDefinition`.
+ * Registration flattens these into `Config.components` and stamps
+ * `componentGroup` on each member's `Component.derived`.
+ *
+ * The serialized form (`SerializedComponentGroup`) replaces
+ * `components: Record<string, ComponentDefinition>` with
+ * `components: readonly string[]` — names only — because the
+ * definitions themselves live under `config.components` on disk.
+ */
+interface ComponentGroupDefinition {
+  label: string;
+  description?: string;
+  components: Record<string, ComponentDefinition>;
+}
+interface SerializedComponentGroup {
+  label: string;
+  description?: string;
+  components: readonly string[];
+}
+/**
+ * One font-class asset member — a pure-JSON data record (no FC to
+ * render), mirroring `@yahoo/uds-fonts`' `FontDeclarationConfig`. The
+ * structural contract the font-class member guard enforces is
+ * `fontFamily` + `declarations[]`; everything else (`fallback`,
+ * weights/axes, `isVariableFont`, …) rides along through the open
+ * index so the registered record stays faithful to the source map
+ * without `@uds/config` depending on the font package's types.
+ */
+interface FontAssetMember {
+  /** CSS-facing family name (`'YA Sans VF'`). */
+  readonly fontFamily: string;
+  /**
+   * `@font-face` source declarations (CDN URLs, weights/axes) — pure
+   * JSON the browser loader derives `@font-face` rules from.
+   */
+  readonly declarations: readonly Record<string, unknown>[];
+  readonly [key: string]: unknown;
+}
+/**
+ * Wire shape for one asset group, discriminated by `assetKind` from
+ * day one so future asset classes extend the union without a wire
+ * migration. The member shape is per-class:
  *
- * @example
- * {
- *   color:   { $type: 'color', brand: { value: '#1167f4', _dark: '#88bcfb' } },
- *   spacing: { $type: 'dimension', 1: { value: '0.25rem' }, 2: { value: '0.5rem' } },
- * }
+ *  - `'icon'` — `members` is a member-*name* list. The React
+ *    components ship in the consumer bundle, so the serialized form
+ *    only needs names (mirrors `SerializedComponentGroup.components`).
+ *  - `'font'` — `members` is the full member-*record* map. Font
+ *    members are already plain JSON and the browser `@font-face`
+ *    loader needs the records themselves.
+ */
+interface SerializedIconAssetGroup {
+  assetKind: 'icon';
+  label: string;
+  description?: string;
+  /** Named size → px. The picker's size options are these keys. */
+  sizes: Readonly<Record<string, number>>;
+  /** Group-level variant superset (declared or harvested union). */
+  variants: readonly string[];
+  /**
+   * Authoring component for code export (`'Icon'`) — lets code views
+   * serialize a placed asset node as `<Icon name="Trophy" … />` and
+   * round-trip it. Also the component a placed member renders through on
+   * the canvas. Omitted for a component-less group (members render bare).
+   */
+  component?: string;
+  members: readonly string[];
+  /**
+   * Per-member harvested metadata (each icon's own variants, category,
+   * tags), keyed by asset name. Carried on the wire so the browser picker
+   * can narrow ragged variants and search tags/category from the resolved
+   * config alone — without introspecting live member components. Omitted
+   * when no member carried metadata (e.g. a metadata-less library).
+   */
+  memberMetadata?: Readonly<Record<string, IconAssetMetadata>>;
+}
+interface SerializedFontAssetGroup {
+  assetKind: 'font';
+  label: string;
+  description?: string;
+  members: Readonly<Record<string, FontAssetMember>>;
+}
+type SerializedAssetGroup = SerializedIconAssetGroup | SerializedFontAssetGroup;
+type GlobalStylesDef = Record<string, Record<string, unknown>>;
+/**
+ * Build-time knobs settable via `config.configure({ buildOptions })`. Read
+ * by the codegen pipeline (`@uds/codegen`) and the CLI to gate
+ * artifact emission. Authored on the config instance, propagated as-is.
+ */
+interface BuildOptions {
+  skipCssVariables?: boolean;
+  preflight?: boolean;
+  /**
+   * Scope every emitted CSS selector under this class name. The
+   * emitter's `:root` block becomes `.<cssScope>`; mode/theme blocks
+   * (e.g. `.dark` or `[data-theme="slate"]`) append `.<cssScope>` so
+   * they still apply when the attribute is on `<html>`. Utility
+   * classes nest under `.<cssScope>` so two UDS-powered packages on
+   * the same page don't collide.
+   */
+  cssScope?: string;
+}
+/**
+ * `Config.toJSON()` produces this shape. Mirrors authored fields exactly
+ * — derived data is never serialized. The `{ __kind, ref }` marker shape
+ * appears wherever a position can hold either a literal or a cross-ref.
  */
-type VarsConfig<M extends `_${string}` = `_${string}`> = Record<string, VarGroupDef<M>>; //#endregion
+interface SerializedConfig {
+  schemaVersion: number;
+  builtAt?: string;
+  prefix: string;
+  /** Registry namespace that prefixes component `registryKey`s
+   *  (`<namespace>:<Component>`). Absent for un-namespaced configs.
+   *  Declared via `configure({ namespace })`. */
+  namespace?: string;
+  preflight: boolean;
+  designPrinciples?: readonly string[];
+  globalStyles?: GlobalStylesDef;
+  /** Raw CSS strings included verbatim via `config.includeCss()` (e.g.
+   *  `@font-face` blocks). Emitted after compilation, ahead of generated CSS. */
+  rawCss?: readonly string[];
+  modes?: Record<string, ModeDefinition>;
+  modifiers?: Record<string, ModifierDefinition>;
+  tokenGroups?: Record<string, SerializedTokenGroup>;
+  styleProps?: Record<string, AnyStylePropDefinition>;
+  compositeStyles?: Record<string, CompositeStyleDefinition>;
+  motion?: Record<string, MotionDefinitionInput>;
+  components?: Record<string, SerializedComponent>;
+  componentGroups?: Record<string, SerializedComponentGroup>;
+  /**
+   * Registered asset groups, keyed by slug. Optional — old
+   * `config.json` files without it hydrate to an empty map; no
+   * `schemaVersion` bump.
+   */
+  assetGroups?: Record<string, SerializedAssetGroup>;
+  providers?: Record<string, Record<string, never>>;
+} //#endregion
 //#endregion
-export { TokenType, VarGroupDef, VarTokenDef, VarsConfig };
+export { AnyStylePropDefinition, ArbitraryEntry, ArbitrarySpec, BaseStyles, BuildOptions, ComponentDefinition, ComponentGroupDefinition, ComponentMetadata, ComponentMotionValue, CompositeStyleDefinition, CompositeStyleObject, CompoundPropsEntry, CssMotionDefinition, FontAssetMember, GlobalStylesDef, JsMotionDefinition, LayerInput, LiteralFor, ModeDefinition, ModeOptionDefinition, ModifierDefinition, MotionDefinitionInput, MotionKeyframes, MotionStateKeyframe, MotionTransition, OpacityPairSpec, PreviewDefinition, PropBinding, RootTag, SerializedAssetGroup, SerializedComponent, SerializedComponentGroup, SerializedConfig, SerializedFontAssetGroup, SerializedIconAssetGroup, SerializedTokenGroup, SlotMotion, StylePropDefinition, StylePropMetadata, StylePropProperty, TokenDefinition, TokenGroupDefinition, TokenModifierKey, TokenModifierValue, TokenType, TokenValue, ValuesEntry };