@theme-registry/refract 0.1.0

package/dist/core/normalize/recipes.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Recipe-group normalization.
+ *
+ * A recipe authors its base declarations inline, plus two optional condition axes — a
+ * grouped `states` map and a `responsive[]` list. Normalization splits both off the base
+ * and flattens them into one unified `overrides` list, each entry carrying an optional
+ * `state` and/or `breakpoint` (both present = the cross-product). References
+ * (`breakpoint` / `state` / `variant` / `target`) are validated against the allowed sets.
+ *
+ * §7A — before any of that, a pre-pass expands an optional `variants` modifier map on any
+ * recipe into flat sibling recipes (`<recipe>-<variant>`), so the rest of this module — the
+ * resolver, `interpretRecipe`, reference extraction, the Model, and every adapter — sees the
+ * same `RecipeGroupDefinition` authored today. Gated on the `variants` key: a group with no
+ * `variants` is returned by reference, byte-identical.
+ */
+import type { RecipeGroupDefinition, NormalizedRecipeGroup } from "./types";
+/** Allowed-reference sets threaded into recipe normalization for validation. */
+export type RecipeNormalizationOptions<TBreakpoint extends string> = {
+    propertyPath?: string;
+    allowedBreakpoints?: ReadonlyArray<TBreakpoint> | ReadonlySet<TBreakpoint>;
+    /** The adapter's known-state set; `state` values are validated against it (throw on unknown). */
+    allowedStates?: ReadonlyArray<string> | ReadonlySet<string>;
+    /** Container queries (§10.5): container name → its allowed size-names, validated on container overrides. */
+    allowedContainers?: ReadonlyMap<string, ReadonlySet<string>>;
+};
+/**
+ * Normalize a whole recipe group (variant name → variant definition).
+ *
+ * Sibling variant names become the group's `allowedVariants` / `allowedTargets` set,
+ * so a variant's responsive `variant` / `target` refs are validated against its peers.
+ *
+ * @param group   The authored group — `{ primary: {…}, danger: {…} }`.
+ * @param options `allowedBreakpoints` / `allowedStates` + `propertyPath` for error labels.
+ * @returns Each variant normalized to `{ base, responsive }` (states + responsive flattened).
+ * @throws If any entry references an unknown breakpoint / state / variant / target,
+ *   or a responsive entry is missing its breakpoint.
+ */
+export declare const normalizeRecipeGroup: <TProps extends Record<string, unknown>, TBreakpoint extends string>(group: RecipeGroupDefinition<TProps, TBreakpoint>, options?: RecipeNormalizationOptions<TBreakpoint>) => NormalizedRecipeGroup<TProps, TBreakpoint>;

package/dist/core/normalize/responsive.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Responsive-override normalization + reference validation.
+ *
+ * Normalizes a property's `responsive[]` entries (defaulting each `query`) and
+ * validates their `breakpoint` / `variant` / `target` references against the
+ * allowed sets threaded in via the normalization context.
+ */
+import type { NormalizedPropertyValue, NormalizedResponsiveOverride, PropertyNormalizationOptions, ResponsiveOverride, ResponsiveQuery } from "./types";
+/** The `query` a responsive entry gets when none is authored — an exact-width media match. */
+export declare const DEFAULT_RESPONSIVE_QUERY: ResponsiveQuery;
+type AllowedValues<T> = ReadonlyArray<T> | ReadonlySet<T>;
+type ResponsiveNormalizationContext<TBreakpoint extends string> = Pick<PropertyNormalizationOptions<unknown, TBreakpoint>, "propertyPath" | "allowedBreakpoints"> & {
+    allowedTargets?: AllowedValues<string>;
+    allowedVariants?: AllowedValues<string>;
+};
+/**
+ * Normalize a property's `responsive[]` list: default each entry's `query` and
+ * validate its references against the context's allowed sets.
+ *
+ * @param overrides The authored responsive entries (or `undefined` / empty → `[]`).
+ * @param context   Optional allowed sets — `allowedBreakpoints` / `allowedVariants`
+ *   / `allowedTargets` — plus `propertyPath` for error labels.
+ * @throws If an entry is missing a `breakpoint`, or references an unknown
+ *   breakpoint / variant / target.
+ */
+export declare function normalizeResponsiveOverrides<TValue, TExtra extends Record<string, unknown> = Record<string, never>, TBreakpoint extends string = string>(overrides: ResponsiveOverride<TValue, TExtra, TBreakpoint>[] | undefined, context?: ResponsiveNormalizationContext<TBreakpoint>): NormalizedResponsiveOverride<TValue, TExtra, TBreakpoint>[];
+/**
+ * Second-pass validation: once a property is fully normalized, confirm every
+ * responsive `variant` / `target` names a variant that actually exists on it.
+ *
+ * Complements {@link normalizeResponsiveOverrides}, which can't see the property's
+ * own variant set during the first pass (variants are normalized in parallel).
+ * A no-op when the property declares no variants.
+ *
+ * @throws If a responsive entry references a variant/target with no matching definition.
+ */
+export declare function validateNormalizedResponsiveRefs<TValue, TExtra extends Record<string, unknown> = Record<string, never>, TBreakpoint extends string = string>(normalized: NormalizedPropertyValue<TValue, TExtra, TBreakpoint>, options?: {
+    propertyPath?: string;
+}): void;
+export {};

package/dist/core/normalize/types.d.ts

@@ -0,0 +1,261 @@
+/**
+ * The normalize-layer vocabulary — the authored-input and normalized-output
+ * shapes the normalizer speaks. Distinct from the Model types (`../model`): these
+ * describe raw theme config and its normalized form; the Model is the downstream
+ * format-neutral representation built from them (Step 0c).
+ *
+ * Ported verbatim from the proven `core/common/types.ts` (self-contained, no imports).
+ */
+export type PrimitiveValue = string | number;
+export type Breakpoints<TKey extends string = string> = Record<TKey, number>;
+export type NormalizedBreakpoints<TKey extends string = string> = Record<TKey, {
+    base: number;
+}>;
+/** `container-type` on a named query container. `inline-size` (default) contains the inline axis only. */
+export type ContainerType = "inline-size" | "size";
+/**
+ * One named container (§10.5) — its `container-type` + its threshold scale (`sizeName → px`). The
+ * config key is the CSS `container-name`. Parallel to a breakpoint scale, but a *component-slot*
+ * scale, not a device scale. A recipe override references it as `{ container: <name>, size: <sizeName> }`.
+ */
+export type ContainerDefinition = {
+    type?: ContainerType;
+    sizes: Record<string, number>;
+};
+/** The authored `rawTheme.containers` map — `containerName → {@link ContainerDefinition}`. */
+export type Containers = Record<string, ContainerDefinition>;
+export type ResponsiveQuery = "min" | "max" | "exact";
+export type ResponsiveOrientation = "landscape" | "portrait";
+export type ResponsiveOverride<TValue, TExtra extends Record<string, unknown> = {}, TBreakpoint extends string = string> = {
+    breakpoint: TBreakpoint;
+    query?: ResponsiveQuery;
+    /** dec.5 — READ source: at this breakpoint the destination var swaps to this variant's var
+     *  (`var(--<prop>-<ref>)`). Replaces the old swap-only `variant`. Composes with `target` (write). */
+    ref?: string;
+    /** dec.9 — appearance-mode CONDITION: the override applies only in this mode (mirror of a recipe
+     *  responsive's `state`). A property-side axis; validated against the `modes` registry (dec.1). */
+    mode?: string;
+    target?: string;
+    orientation?: ResponsiveOrientation;
+} & Partial<{
+    base: TValue;
+} & TExtra>;
+export type NormalizedResponsiveOverride<TValue, TExtra extends Record<string, unknown> = {}, TBreakpoint extends string = string> = Omit<ResponsiveOverride<TValue, TExtra, TBreakpoint>, "query"> & {
+    query: ResponsiveQuery;
+};
+export type VariantValue<TValue, TExtra extends Record<string, unknown> = {}, TBreakpoint extends string = string> = TValue | ({
+    base: TValue;
+} & TExtra);
+/** dec.2 — one modifier dial in a derivation chain: a single-key object `{ [fn]: args }`
+ *  (`{ darken: 10 }`, `{ alpha: 40 }`, `{ adjust: { l, c, h } }`). */
+export type DerivationModifier = Record<string, unknown>;
+/**
+ * A derivation (§10.3, dec.2) — read `ref` (defaults to the property's OWN base), then fold the
+ * ordered `modifiers` chain of `{ [fn]: args }` dials over it: `value = modifiers.reduce((v, {fn,arg})
+ * => fn(v, arg), resolve(ref))`. The owning subsystem hook (colors) bakes it (mirror of tonal steps).
+ * Replaces the old single `{ fn, arg }` shorthand.
+ */
+export type ModeDerivation = {
+    ref?: string;
+    modifiers: DerivationModifier[];
+};
+/**
+ * One authored appearance-mode override (§10.3) — the value payload of a {@link ModeOverride}. A
+ * `{ ref?, modifiers }` derivation derives the base; a `{ base?, …extra }` object overrides the base
+ * (literal) and/or sibling extras (literal only in v1). Parallel to {@link VariantValue}. (The bare
+ * `TValue` shorthand is gone — modes are an array of `{ mode, … }` entries, so the value is spelled
+ * with an explicit `base:`.)
+ */
+export type ModeValue<TValue, TExtra extends Record<string, unknown> = {}> = (ModeDerivation & Partial<TExtra>) | ({
+    base?: TValue;
+} & Partial<TExtra>);
+/**
+ * One entry in a property's `modes` **array** — its `mode` name (the WHEN, validated against the
+ * `modes` registry, dec.1), an optional `target` (the WHERE — scope the override into a variant's
+ * var), plus the {@link ModeValue} payload (the WHAT). Mirrors a {@link ResponsiveOverride} entry;
+ * shares the WHEN/WHERE/WHAT spine with recipe states.
+ */
+export type ModeOverride<TValue, TExtra extends Record<string, unknown> = {}> = {
+    mode: string;
+    target?: string;
+} & ModeValue<TValue, TExtra>;
+export type ExtendedProperty<TValue, TExtra extends Record<string, unknown> = {}, TBreakpoint extends string = string> = {
+    base: TValue;
+    responsive?: ResponsiveOverride<TValue, TExtra, TBreakpoint>[];
+    variants?: Record<string, VariantValue<TValue, TExtra, TBreakpoint>>;
+    modes?: ModeOverride<TValue, TExtra>[];
+} & TExtra;
+/**
+ * §W6b — an **external-token** property: a passthrough to a CSS variable a *parent* theme owns.
+ * `external` is a refract token path (`"colors.brand"` → `var(--<extends.prefix>-colors-brand)`) or a
+ * literal CSS variable (`"--mat-sys-bg"`, leading `--`). The rest of the theme references it like any
+ * token, but it is never defined locally and is not tonally derivable.
+ */
+export type ExternalProperty = {
+    external: string;
+};
+export type PropertyValue<TValue, TExtra extends Record<string, unknown> = {}, TBreakpoint extends string = string> = TValue | ExtendedProperty<TValue, TExtra, TBreakpoint> | ExternalProperty;
+export type NormalizedVariantValue<TValue, TExtra extends Record<string, unknown> = {}, TBreakpoint extends string = string> = {
+    /**
+     * The variant's primary value. Normally present (a literal, or the cached resolution of a
+     * `derive`). **Absent** only for a dec.4 **cross-property** derivation, whose source lives in
+     * another property and so cannot be baked during this property's single normalize pass — the
+     * post-build `bakeCrossPropertyDerivations` pass fills it (via `derive.ref` + `derive.modifiers`).
+     */
+    base?: TValue;
+    /**
+     * Synthesized variants (e.g. colors' `light`/`dark` steps) carry a fully-qualified derivation
+     * so the Model can store them as a derived `Ref` (`{ ref, fn, arg }`) instead of an opaque baked
+     * value — enabling free override propagation. Set by a subsystem's `normalizeProperty`; the
+     * `base` value is retained (it's the cached resolution the CSS lowering still reads) — except for
+     * a cross-property `derive`, where `base` is filled post-build (see above).
+     */
+    derive?: {
+        ref: string;
+        fn?: string;
+        arg?: unknown;
+        modifiers?: Array<{
+            fn: string;
+            arg?: unknown;
+        }>;
+    };
+} & TExtra;
+/**
+ * One appearance mode after normalization (§10.3). `base` is the baked literal (core fills it
+ * for a literal mode; the colors hook fills it for a derived one) — absent when the mode overrides
+ * only extras. `derive` carries a base derivation the colors hook resolves/bakes (`ref` filled by
+ * the subsystem that owns the fn). Extra fields are literal siblings (e.g. colors' `text`).
+ */
+export type NormalizedModeValue<TValue, TExtra extends Record<string, unknown> = {}> = {
+    base?: TValue;
+    derive?: {
+        ref?: string;
+        fn?: string;
+        arg?: unknown;
+        modifiers?: Array<{
+            fn: string;
+            arg?: unknown;
+        }>;
+    };
+} & Partial<TExtra>;
+/** One entry in the normalized `modes` **array** — the mode name + optional target + the normalized
+ *  value payload. Mirrors {@link NormalizedResponsiveOverride}. */
+export type NormalizedModeOverride<TValue, TExtra extends Record<string, unknown> = {}> = {
+    mode: string;
+    target?: string;
+} & NormalizedModeValue<TValue, TExtra>;
+export type NormalizedPropertyValue<TValue, TExtra extends Record<string, unknown> = {}, TBreakpoint extends string = string> = {
+    base: TValue;
+    responsive: NormalizedResponsiveOverride<TValue, TExtra, TBreakpoint>[];
+    variants?: Record<string, NormalizedVariantValue<TValue, TExtra, TBreakpoint>>;
+    modes?: NormalizedModeOverride<TValue, TExtra>[];
+    /** §W6b — set (to the literal parent var name) when this property is an external-token passthrough. */
+    external?: string;
+} & TExtra;
+export type PropertyNormalizationOptions<TValue, TBreakpoint extends string = string> = {
+    propertyPath?: string;
+    coerceValue?: (value: TValue) => TValue;
+    fallbackBase?: TValue;
+    allowedBreakpoints?: ReadonlyArray<TBreakpoint> | ReadonlySet<TBreakpoint>;
+    /**
+     * §15 object-leaf subsystems (effects shadow / transitions): the set of value-field names that,
+     * when present at a property/variant top level WITHOUT an explicit `base` key, are assembled into
+     * the base value object. Keys not in this set (and not the structural `variants`/`responsive`/
+     * `modes`) are treated as `TExtra` siblings. An explicit `base` key is the escape hatch — it is
+     * the base of any shape (object/array/string), bypassing assembly. Absent for scalar subsystems.
+     */
+    leafFields?: readonly string[];
+};
+export type RecipeResponsiveOverride<TProps extends Record<string, unknown>, TBreakpoint extends string = string> = {
+    /** Present for breakpoint-conditioned overrides; absent for pure-state / container overrides. */
+    breakpoint?: TBreakpoint;
+    query?: ResponsiveQuery;
+    /** Recipe-only condition axis; validated against the adapter's known-state set in normalize. */
+    state?: string;
+    variant?: string;
+    target?: string;
+    orientation?: ResponsiveOrientation;
+    /** Container-query axis (§10.5): the named container this override responds to (replaces `breakpoint`). */
+    container?: string;
+    /** The size-name in that container's threshold scale (used with `container`, like `breakpoint`). */
+    size?: string;
+} & Partial<TProps>;
+/**
+ * One entry in a recipe / globals-element `states` **array** — its `state` name (WHEN, validated
+ * against the adapter's known-state set), an optional `target` (WHERE — scope the override onto the
+ * `<item>-<target>` sibling selector, dec.8), plus the flat recipe-prop deltas (WHAT). Mirrors a
+ * {@link RecipeResponsiveOverride} entry with no breakpoint; shares the WHEN/WHERE/WHAT spine with a
+ * property {@link ModeOverride}. A list (not a `state → delta` map) so two same-state entries can
+ * target different siblings.
+ */
+export type RecipeStateOverride<TProps extends Record<string, unknown>> = {
+    state: string;
+    target?: string;
+} & Partial<TProps>;
+/**
+ * The authored `states` value — the canonical **array** of {@link RecipeStateOverride}s (dec.8), or a
+ * legacy `{ state: {…delta} }` **map** (no `target`, one entry per state) still accepted for authoring
+ * convenience. Both normalize to the same flattened override list; docs teach the array form.
+ */
+export type RecipeStates<TProps extends Record<string, unknown>> = RecipeStateOverride<TProps>[] | Record<string, Partial<TProps>>;
+/**
+ * Strip a string/number index signature from `T`, keeping only its explicitly
+ * declared keys. Needed so the reserved `responsive` / `states` keys below aren't
+ * clobbered by a recipe-prop index signature like `[property: string]: string`
+ * (which would otherwise force them to be `undefined` and reject authoring).
+ */
+type RemoveIndexSignature<T> = {
+    [K in keyof T as string extends K ? never : number extends K ? never : K]: T[K];
+};
+/**
+ * dec.7 — one modifier delta inside a **recipe's** `variants` map (§7A). Layered onto the recipe's
+ * own props by `mergeRecipe` to desugar into a flat sibling `<recipe>-<variant>` recipe. **FLAT**: a
+ * prop delta (delta wins) or `null` to drop an inherited ref. A variant's conditional behaviour lives
+ * in the ITEM's `states`/`responsive` — NOT nested here (no nested `states`/`responsive`/`variants`).
+ * (A property variant is a token value → flat; a recipe variant is a sibling recipe → still authored
+ * flat here, its states come from the item. Globals is the exception, see {@link GlobalsElementVariantModifier}.)
+ */
+export type RecipeVariantModifier<TProps extends Record<string, unknown>, TBreakpoint extends string = string> = Partial<TProps> & {
+    /** A prop delta (delta wins) or `null` to drop an inherited ref. */
+    [property: string]: unknown;
+};
+/**
+ * §9 — one modifier delta inside a **globals element's** `variants` map. Unlike a recipe variant
+ * (dec.7, flat), a globals element variant KEEPS the conditional axes (`states`/`responsive`) — each
+ * desugars into a higher-specificity element variant (`a.subtle`) that can carry its own hover, etc.
+ * Globals is the non-generic exception to the flat recipe-variant rule.
+ */
+export type GlobalsElementVariantModifier<TProps extends Record<string, unknown>, TBreakpoint extends string = string> = {
+    responsive?: RecipeResponsiveOverride<TProps, TBreakpoint>[];
+    states?: RecipeStates<TProps>;
+    /** A prop delta (delta wins) or `null` to drop an inherited ref. */
+    [property: string]: unknown;
+};
+export type RecipeVariantDefinition<TProps extends Record<string, unknown>, TBreakpoint extends string = string, 
+/** dec.7 — the variant-modifier shape. Recipes default to the FLAT modifier; globals pass the rich one. */
+TVariantMod = RecipeVariantModifier<TProps, TBreakpoint>> = RemoveIndexSignature<TProps> & {
+    responsive?: RecipeResponsiveOverride<TProps, TBreakpoint>[];
+    /** Grouped state condition map — `{ hover: {…decls}, disabled: {…decls} }`; flattened into overrides. */
+    states?: RecipeStates<TProps>;
+    /**
+     * §7A — modifier deltas layered on this recipe/element. A pre-pass in `normalizeRecipeGroup` expands
+     * each into a flat sibling named `<recipe>-<variant>` (via `mergeRecipe`), then the ordinary
+     * normalization runs unchanged. Reserved, like `states` / `responsive`.
+     */
+    variants?: Record<string, TVariantMod>;
+    /** Additional style declarations beyond the named recipe props. */
+    [property: string]: unknown;
+};
+export type RecipeGroupDefinition<TProps extends Record<string, unknown>, TBreakpoint extends string = string> = Record<string, RecipeVariantDefinition<TProps, TBreakpoint>>;
+/**
+ * The authored `recipes:` block — a map of group name → {@link RecipeGroupDefinition}
+ * (`{ solid: { primary: {…}, danger: {…} }, outline: {…} }`). The per-subsystem
+ * authoring-input types (`ColorsRaw`/… ) key their `recipes?` on this.
+ */
+export type RecipeBlock<TProps extends Record<string, unknown>, TBreakpoint extends string = string> = Record<string, RecipeGroupDefinition<TProps, TBreakpoint>>;
+export type NormalizedRecipeVariant<TProps extends Record<string, unknown>, TBreakpoint extends string = string> = {
+    base: TProps;
+    responsive: RecipeResponsiveOverride<TProps, TBreakpoint>[];
+};
+export type NormalizedRecipeGroup<TProps extends Record<string, unknown>, TBreakpoint extends string = string> = Record<string, NormalizedRecipeVariant<TProps, TBreakpoint>>;
+export {};

package/dist/core/rawTheme.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The `RawTheme` authoring type (§8a) — the top-level shape a user's raw theme is authored in.
+ *
+ * The raw theme is the file users *live in* (edited/extended constantly), so it's richly typed for
+ * autocomplete + typo detection. It composes the per-subsystem authoring-input types (each defined
+ * beside its subsystem and built from the `core/normalize` vocabulary) under their nested keys.
+ *
+ * **Strict-closed** (no top-level index signature): an unknown/misspelled top-level key is a type
+ * error on a literal — that's the whole point. The `createTheme` spine still ignores unknown
+ * top-level keys at runtime, and a power user who genuinely needs to bypass can cast. Breakpoint
+ * names stay loose `string` in v1 (TS can't infer them from the sibling `breakpoints` key within one
+ * literal anyway) — the normalize vocabulary underneath is generic, so generic threading is a
+ * documented future enhancement.
+ *
+ * Authoring type ONLY — no runtime/output change. `createTheme` bridges to its loose spine with a
+ * single boundary cast; the subsystem hooks still consume each `rawTheme[key]` slice as
+ * `Record<string, unknown>`.
+ */
+import type { Breakpoints, Containers } from "./normalize";
+import type { ColorsRaw, TypographyRaw, EffectsRaw, BordersRaw, AnimationRaw, LayoutRaw, ComponentsRaw, GlobalsRaw } from "../subsystems";
+export interface RawTheme {
+    /**
+     * §W6b — borrow tokens from a *parent* theme you don't own. `prefix` is that theme's CSS-variable
+     * prefix, so a path-form external (`{ external: "colors.brand" }`) lowers to `var(--<prefix>-colors-brand)`.
+     * A literal-form external (`{ external: "--mat-sys-bg" }`) needs no prefix. Defaults to `"dt"`.
+     */
+    extends?: {
+        prefix?: string;
+    };
+    /** Breakpoint name → min-width (px). Omit for the default breakpoints. */
+    breakpoints?: Breakpoints;
+    /** Named query containers (§10.5) — `name → { type?, sizes }`; referenced by recipe container overrides. */
+    containers?: Containers;
+    /**
+     * Appearance-mode registry — the declared set of mode names. Every property-level `modes` key is
+     * validated against this (typo-detection, like breakpoints/containers). Omit for the default
+     * `["dark", "light"]`. `dark`/`light` auto-bind to `@media (prefers-color-scheme)`; any other name
+     * is a `[data-theme="…"]` manual toggle only.
+     */
+    modes?: string[];
+    colors?: ColorsRaw;
+    typography?: TypographyRaw;
+    effects?: EffectsRaw;
+    /** Stroke geometry (width/style/offset/radius) + border/outline recipes (§14). Color = value-level `colors.*` ref. */
+    borders?: BordersRaw;
+    /** Motion tokens (duration/easing/delay) + keyframes + animation-shorthand recipes (§10.2). */
+    animation?: AnimationRaw;
+    layout?: LayoutRaw;
+    components?: ComponentsRaw;
+    /** Bare-element base layer (§9) — a normalization `preset` + themed `elements` (declarations +
+     *  states / responsive / variants) bound to raw selectors. */
+    globals?: GlobalsRaw;
+}

package/dist/core/ref.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `ref(path)` — author a token **reference** inside a `css` delta or a globals element rule.
+ *
+ * Inside a `css` block (and globals element declarations) a bare string is a **literal** CSS value —
+ * `display: "flex"` emits `flex`. To emit a token reference instead, wrap the token path in `ref()`:
+ * `color: ref("colors.brand.text")` → `var(--…)`. The JSON-safe equivalent is the plain object form
+ * `{ ref: "colors.brand.text" }`; both produce the same Model reference, so a `theme.raw.json` needs no
+ * function. (Top-level recipe composition fields — `colors: "solid.brand"` — are unaffected: a bare
+ * string there is always a reference.)
+ */
+export declare const ref: (path: string) => {
+    ref: string;
+};

package/dist/core/subsystem.d.ts

@@ -0,0 +1,115 @@
+/**
+ * The minimal subsystem descriptor (Step 0d).
+ *
+ * `createTheme`'s spine loops a `SUBSYSTEMS` list of these — never subsystem-specific
+ * control flow. Growing the pipeline = pushing a `Subsystem` (or filling a hook on the
+ * type), so the spine's shape is fixed while its coverage grows step by step.
+ *
+ * Day one carries a single hook — `normalizeProperties` — enough for the colors
+ * property slice. Recipe / slice hooks land alongside their steps (recipes: step 1+).
+ */
+import type { NormalizedPropertyValue, NormalizedRecipeVariant } from "./normalize";
+import type { DerivationRegistry } from "./derive";
+import type { InterpretedRecipeVariant, Keyframe, PropertyModel, RuleSetGroup } from "./model";
+import type { MediaConfig, MediaDescriptor } from "./media";
+/** A subsystem's normalized property collection (`name → normalized property`). */
+export type NormalizedProperties = Record<string, NormalizedPropertyValue<unknown, Record<string, unknown>>>;
+/** Context threaded into a subsystem's normalize hooks by the spine. */
+export interface SubsystemNormalizeContext {
+    /** The theme's breakpoint keys — responsive references are validated against these. */
+    readonly allowedBreakpoints: string[];
+}
+/** Context threaded into a subsystem's `buildStructural` hook by the spine. */
+export interface StructuralContext {
+    readonly breakpoints: Record<string, number>;
+    readonly media: MediaDescriptor<string>;
+    /** Media unit config (§10.5) — so breakpoint-DERIVED lengths (fixed-container widths) can format in
+     *  the same px/em/rem unit the `@media` thresholds use. Absent → px. */
+    readonly mediaConfig?: MediaConfig;
+    /**
+     * The adapter's known-state set (§9) — a structural subsystem whose rule-sets carry recipe-style
+     * condition axes (globals' themed element `states`) validates its `state:` refs against this, the
+     * same set the generic recipe path uses. Absent ⇒ no state validation (generator subsystems that
+     * emit no conditions, e.g. layout).
+     */
+    readonly allowedStates?: ReadonlyArray<string>;
+    /** Container queries (§10.5) — `name → allowed size-names`, validated on a structural rule-set's
+     *  container overrides (globals element `responsive` container entries). */
+    readonly allowedContainers?: ReadonlyMap<string, ReadonlySet<string>>;
+}
+/**
+ * A subsystem's structural (generator-driven) Model contribution — rule-set groups that aren't
+ * authored recipes (layout's columns/grids/stacks/container), plus already-built config
+ * `PropertyModel`s to merge into the subsystem's tokens (Model `extraProperties`). Declarations
+ * carry token-path refs, never CSS — the CSS adapter lowers them.
+ */
+export interface StructuralOutput {
+    readonly ruleSetGroups: Record<string, RuleSetGroup>;
+    readonly configProperties: Record<string, PropertyModel>;
+    /**
+     * Named keyframe definitions (§10.2) — the animation subsystem's contribution. Neither a
+     * rule-set nor a config token, so it rides its own slot; threaded into
+     * {@link SubsystemModelInput.keyframes} and attached to {@link SubsystemModel.keyframes}. Absent
+     * ⇒ no keyframes (the common case — layout/reset return none).
+     */
+    readonly keyframes?: Record<string, Keyframe>;
+}
+/**
+ * Context threaded into a subsystem's `interpretRecipe` hook by the generic recipe path.
+ *
+ * The subsystem resolves each recipe declaration against its **own** normalized
+ * `properties` (reference-syntax knowledge is subsystem-specific), emitting token-path
+ * refs. `resolveRecipeVariant` pulls a sibling's already-interpreted form (cycle-safe).
+ */
+export interface RecipeInterpretContext {
+    readonly breakpoints: Record<string, number>;
+    readonly media: MediaDescriptor<string>;
+    /** The subsystem's own normalized property collection — the reference resolution source. */
+    readonly properties: NormalizedProperties;
+    /** Resolve a sibling variant in the same group (for responsive `variant:` swaps). */
+    readonly resolveRecipeVariant: (variantName: string) => InterpretedRecipeVariant<string>;
+    /** `"<subsystem>.recipes.<group>"` — used for error labels. */
+    readonly groupPath: string;
+}
+/** A subsystem plugged into the `createTheme` spine. */
+export interface Subsystem {
+    /** The `rawTheme[key]` slice this subsystem owns (also its Model namespace). */
+    readonly key: string;
+    /**
+     * Normalize the subsystem's raw property slice into the canonical shape the Model
+     * builder consumes. Reserved sub-keys (e.g. `recipes`) are the subsystem's to skip.
+     */
+    normalizeProperties(rawSlice: Record<string, unknown> | undefined, ctx: SubsystemNormalizeContext): NormalizedProperties;
+    /**
+     * Interpret one normalized recipe variant into declaration {@link InterpretedRecipeVariant}
+     * refs. Required for a subsystem with recipes; the generic recipe path (in `createTheme`)
+     * drives it through the shared normalize + cycle-safe resolver, then builds the Model
+     * rule-sets from the interpreted output. Absent ⇒ the subsystem contributes no rule-sets.
+     */
+    interpretRecipe?(variantName: string, variant: NormalizedRecipeVariant<Record<string, unknown>, string>, ctx: RecipeInterpretContext): InterpretedRecipeVariant<string>;
+    /**
+     * Extract cross-subsystem recipe references (`"colors:solid.primary"`, …) from a normalized
+     * variant's base — the composition (components) subsystem's hook. When present, the generic recipe
+     * path builds each rule-set via `buildComponentRuleSetFromInterpreted` (keeping the references as
+     * Model pointers, so the referenced recipe's own states ride along on its shared class) instead of
+     * the plain `buildRuleSetFromInterpreted`. Absent ⇒ a subsystem contributes no references (the
+     * common case). Keeps the spine generic: the recipe path is reference-aware without a
+     * components-specific branch.
+     */
+    extractReferences?(normalizedVariantBase: Record<string, unknown>): string[];
+    /**
+     * Emit generator-driven rule-sets + config tokens (layout's columns/grids/stacks/container).
+     * The spine calls this once per subsystem that provides it, merging the structural rule-set
+     * groups **ahead of** the recipe groups and passing the config tokens as `extraProperties`.
+     * Absent ⇒ the subsystem has no structural output. Kept generic: no subsystem-specific
+     * control flow in the spine — pushing a subsystem with this hook is enough.
+     */
+    buildStructural?(rawSlice: Record<string, unknown>, ctx: StructuralContext): StructuralOutput;
+    /**
+     * The subsystem's value-derivation fns (`fn name -> DerivationFn`), keeping the spine
+     * generic: the spine collects `derivations` across `SUBSYSTEMS` into one registry rather
+     * than importing any subsystem's fns. Colors contributes `{ lighten, darken }`; a subsystem
+     * with no synthesized steps omits it. Duplicate fn names across subsystems throw.
+     */
+    readonly derivations?: DerivationRegistry;
+}

package/dist/core/types.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Free-standing theme-surface data types. Adapters expose render *methods*; the
+ * only plain data structures the surface needs are the recipe-name map and the
+ * (deferred) self-contained lazy-recipe shape.
+ */
+/**
+ * Recipe names for one subsystem: group → variant → identity string.
+ * `createTheme` builds it by looping the Model and calling `adapter.recipeName`
+ * (not an adapter method itself). Surfaced per subsystem, e.g. `theme.colors.classes`.
+ */
+export type NameMap = Record<string, Record<string, string>>;
+/**
+ * The self-contained result of lazily rendering one recipe: the rule PLUS the
+ * variables it needs, kept SEPARATE and addressable so a delivery layer can dedup.
+ *
+ * Both halves are `{ identity, render }` — the delivery layer dedups variables by
+ * `path` (and recipes by `name` if the same recipe appears twice), then inserts.
+ * Produced by the core helper `renderRecipeStandalone`, composed from `recipeRefs`
+ * (core) + `renderToken` (adapter) + `renderRecipe` (adapter). Not produced yet —
+ * the lazy per-recipe delivery path is deferred.
+ */
+export interface RecipeStandalone<TUnit = string> {
+    readonly recipe: {
+        readonly name: string;
+        readonly render: TUnit;
+    };
+    readonly variables: ReadonlyArray<{
+        readonly path: string;
+        readonly render: TUnit;
+    }>;
+}

package/dist/core/units.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Length units as a property of the value (§21).
+ *
+ * A length's unit belongs to the value, not to one global adapter switch. This module owns the whole
+ * length-unit story: the CSS unit set, parsing an authored length input into a canonical dimension,
+ * the three-layer role resolution, and the format-neutral **Model pass** that bakes a fully-resolved
+ * `{ value, unit }` onto every length leaf. Adapters downstream only stringify (`value + unit`).
+ *
+ * Resolution order for a length leaf's unit (most-specific wins):
+ *   ① value-level unit  — the token pinned `"1px"`; trusted verbatim, never converted
+ *   ② role default      — `units["<sub>.<prop>"]` → `units["<sub>"]` → `units.default`
+ *   ③ built-in seed     — length subsystems seed `px`; `lineHeight` → none; `letterSpacing` → em
+ *
+ * A bare number is **deferred** (px-intended magnitude, unit resolved by ②/③); `rem` is the one unit
+ * whose resolution divides (`value ÷ baseFontSize`). An explicit unit is **pinned** — passed through.
+ * Functions / keywords (`calc(…)`, `clamp(…)`, `var(…)`, `none`) are raw-string escapes, never parsed.
+ */
+import type { Ref, ThemeModel } from "./model";
+/**
+ * The CSS length / relative unit set we parse + validate (§21 D2 — support every unit, exclude only
+ * functions). A `<number><unit>` whose suffix is here becomes a pinned dimension; an unknown suffix is
+ * an authoring error; anything with parens / whitespace / no digits is a raw-string escape.
+ */
+export declare const CSS_UNITS: readonly ["px", "cm", "mm", "q", "in", "pc", "pt", "rem", "em", "ex", "cap", "ch", "ic", "lh", "rlh", "%", "vw", "vh", "vi", "vb", "vmin", "vmax", "svw", "svh", "lvw", "lvh", "dvw", "dvh", "cqw", "cqh", "cqi", "cqb", "cqmin", "cqmax"];
+export type Unit = (typeof CSS_UNITS)[number];
+/** A resolved role: a concrete unit, or `"none"` (a length leaf that stays unit-less, e.g. lineHeight). */
+export type RoleUnit = Unit | "none";
+/** A parsed length: a magnitude + optional unit (absent ⇒ deferred), or a raw escape string. */
+export type ParsedLength = {
+    value: number;
+    unit?: Unit;
+} | {
+    raw: string;
+};
+/**
+ * Parse one authored length input into a {@link ParsedLength}. A number, or a bare numeric string, is
+ * deferred (`{ value }`). A `<number><unit>` with a known CSS unit is pinned (`{ value, unit }`). A
+ * `<number><unknown>` is an authoring error (a typo — real functions/keywords carry parens or letters
+ * with no leading number and fall through to `{ raw }`).
+ */
+export declare const parseLength: (input: number | string) => ParsedLength;
+/**
+ * The build/theme-level unit config (§21 D3). Keys are token-path prefixes — `units.default` (global),
+ * `units["<subsystem>"]` (subsystem grain), `units["<subsystem>.<property>"]` (property grain). Values
+ * are a concrete unit or `"none"`. Most-specific wins; falls back to the built-in seed, then `px`.
+ */
+export type UnitsConfig = {
+    default?: RoleUnit;
+} & Record<string, RoleUnit | undefined>;
+export type UnitResolutionConfig = {
+    units?: UnitsConfig;
+    /** Divisor for a deferred magnitude resolving to `rem` (matches typography + media). Default `16`. */
+    baseFontSize?: number;
+};
+export declare const DEFAULT_BASE_FONT_SIZE = 16;
+/**
+ * Resolve the role unit for a length leaf at `pathKey` (`"typography.letterSpacing"`). Precedence is
+ * by **grain**, most-specific first, with the built-in property-grain seed slotted at its own grain —
+ * so `SEED["typography.lineHeight"] = "none"` beats a blunt subsystem-grain `units.typography = "rem"`
+ * (§21 D1: property grain beats subsystem grain), while a user can still force it with the property key.
+ */
+export declare const resolveRoleUnit: (pathKey: string, units: UnitsConfig | undefined) => RoleUnit;
+/**
+ * Resolve one length leaf {@link Ref} against its role. A pure token reference (`{ ref }`, no baked
+ * value) is left untouched (its unit resolves at its own address). A **derived** length leaf
+ * (`{ ref, fn, arg, value }` — §10.6 scale steps) carries its own baked `value`, emitted as a literal,
+ * so its unit IS resolved here. A numeric or numeric-string value is deferred → resolved via the role;
+ * a `<number><unit>` string is pinned → carried verbatim onto `{ value, unit }`; a raw escape
+ * (`calc()`, keyword) is left as its string value. Returns a NEW ref when anything changed, else the
+ * original (structural sharing preserved for byte-identical untouched branches).
+ */
+export declare const resolveLengthRef: (ref: Ref, role: RoleUnit, baseFontSize: number) => Ref;
+/** A shadow geometry field after §21 widening — a deferred magnitude or a pinned `{ value, unit }`. */
+export type ShadowDimension = number | {
+    value: number;
+    unit: Unit;
+};
+/** How a length-bearing property carries its value: a scalar leaf, or the shadow struct geometry. */
+export type LengthKind = "length" | "shadow";
+/**
+ * The length-field declaration (formalizes the scattered `PX_*_KEYS` of §16). Which `<subsystem>.<property>`
+ * tokens are length-valued, and how they carry it. Anything absent (opacity, zIndex, aspectRatio, easing,
+ * durations) is left untouched by the resolver. `lineHeight` is a length that seeds to `none` — listed so a
+ * theme CAN opt it into a unit, resolving to unit-less by default.
+ */
+export declare const LENGTH_REGISTRY: Record<string, Record<string, LengthKind>>;
+/**
+ * Resolve every length leaf in the {@link ThemeModel} to a concrete `{ value, unit }` (§21 D3). Pure and
+ * **reference-preserving**: a subsystem / property / leaf that gains no unit keeps its object identity, so
+ * the default px path stays byte-identical AND `override`'s structural sharing survives the re-run
+ * (already-resolved parent branches are returned as-is). The single point where `units` is consulted.
+ */
+export declare const resolveModelUnits: (model: ThemeModel, config?: UnitResolutionConfig) => ThemeModel;