@theme-registry/refract 0.1.0

package/dist/core/media/defaults.d.ts

@@ -0,0 +1,3 @@
+export type DefaultBreakpointKey = "xs" | "sm" | "md" | "lg" | "xl";
+export type DefaultBreakpoints = Record<DefaultBreakpointKey, number>;
+export declare const DEFAULT_BREAKPOINTS: DefaultBreakpoints;

package/dist/core/media/descriptors.d.ts

@@ -0,0 +1,12 @@
+import type { MediaQueryOptions } from "./queries";
+export declare const BREAKPOINT_EPSILON = 0.02;
+export type MediaVariant = "min" | "max" | "exact";
+export type MediaGroupDescriptor = Record<MediaVariant, string>;
+export type MediaDescriptor<TBreakpoint extends string> = {
+    min: (key: TBreakpoint, options?: MediaQueryOptions) => string;
+    max: (key: TBreakpoint, options?: MediaQueryOptions) => string;
+    exact: (key: TBreakpoint, options?: MediaQueryOptions) => string;
+    between: (from: TBreakpoint, to: TBreakpoint, options?: MediaQueryOptions) => string;
+} & Record<TBreakpoint, MediaGroupDescriptor>;
+export declare const sortBreakpointKeys: <T extends string>(breakpoints: Record<T, number>) => T[];
+export declare const buildMediaDescriptor: <TBreakpoint extends string>(breakpoints: Record<TBreakpoint, number>, resolveQuery: (options: MediaQueryOptions) => string) => MediaDescriptor<TBreakpoint>;

package/dist/core/media/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Media types + helpers for the clean-room tree — breakpoints → `@media` builder.
+ *
+ * Self-contained (no intra-core deps): the numeric-breakpoint machinery core hands
+ * to adapters, which decorate it (`wrapMedia`) for their target. Ported from the
+ * original `core/media` during the barrel flip (Step 6).
+ */
+export * from "./descriptors";
+export * from "./queries";
+export * from "./defaults";
+export * from "./containers";

package/dist/core/media/queries.d.ts

@@ -0,0 +1,20 @@
+export type MediaUnit = "px" | "em" | "rem";
+export type MediaConfig = {
+    unit?: MediaUnit;
+    baseFontSize?: number;
+};
+export type MediaQueryOptions = {
+    min?: number;
+    max?: number;
+    orientation?: "landscape" | "portrait";
+};
+export declare const resolveMediaConfig: (config?: MediaConfig) => Required<MediaConfig>;
+export declare const formatWidth: (value: number, config: Required<MediaConfig>) => string;
+export declare const mediaQueryString: ({ min, max, orientation }: MediaQueryOptions, config: Required<MediaConfig>) => string;
+export declare const mediaQuery: (options: MediaQueryOptions, config?: MediaConfig) => string;
+/**
+ * Container-query prelude (§10.5) — the `@container <name> (…)` twin of {@link mediaQueryString}.
+ * Shares the width formatting (so container thresholds honor the same px/em/rem unit config), but
+ * has no `orientation` clause (invalid under `container-type: inline-size`; rejected in normalize).
+ */
+export declare const containerQueryString: (name: string, { min, max }: Pick<MediaQueryOptions, "min" | "max">, config: Required<MediaConfig>) => string;

package/dist/core/model/buildModel.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Model builder (clean-room port of `core/common/buildModel.ts`).
+ *
+ * Pure functions that assemble the format-neutral {@link ThemeModel} from data the
+ * pipeline computes — the normalized property collections and the interpreted recipe
+ * groups. `buildThemeModel` consumes each subsystem's already-interpreted rule-set
+ * groups (see `buildRuleSetGroupFromInterpreted`), whose declarations already carry
+ * format-neutral {@link Ref}s (`{ ref: "colors.primary" }` for a token-path reference,
+ * `{ value }` for a literal). The builder is a structural copy — it never string-parses
+ * `var(--…)`; the interpreter emits canonical token paths directly.
+ *
+ * `pathify*` rewrites refs via a supplied map (used by later subsystems that still emit
+ * var-name refs); `buildTokenMap` flattens the property tokens into a `path -> Ref` map.
+ */
+import type { NormalizedPropertyValue } from "../normalize";
+import type { InterpretedRecipeGroup, InterpretedRecipeVariant } from "./interpreted";
+import type { ContainerModel, Keyframe, PropertyModel, Ref, RuleSet, RuleSetGroup, SubsystemModel, ThemeModel } from "./model";
+/**
+ * One normalized property (`{ base, responsive, variants?, ...extras }`) → a
+ * {@link PropertyModel}. `base` and each variant become value refs; scalar sibling
+ * extras (e.g. colors' `text`) go in `extras`; the responsive list maps entry-for-entry.
+ */
+export declare const buildPropertyModel: (normalized: NormalizedPropertyValue<unknown, Record<string, unknown>>, propertyName?: string) => PropertyModel;
+/** A whole normalized collection (`name → normalized property`) → `name → PropertyModel`. */
+export declare const buildPropertiesModel: (collection: Record<string, NormalizedPropertyValue<unknown, Record<string, unknown>>>) => Record<string, PropertyModel>;
+/**
+ * One *interpreted* recipe variant → a {@link RuleSet}. The interpreter has already
+ * resolved every declaration to a {@link Ref} (`{ ref }` for token references, `{ value }`
+ * for literals) and separated the condition axes from the declarations, so this is a
+ * structural copy — **no string-parsing of `var(…)`**. Format-neutral by construction:
+ * refs are token paths, not var names.
+ */
+export declare const buildRuleSetFromInterpreted: (variant: InterpretedRecipeVariant<string>) => RuleSet;
+/** An interpreted recipe group (`variant → interpreted`) → a {@link RuleSetGroup} with refs. */
+export declare const buildRuleSetGroupFromInterpreted: (group: InterpretedRecipeGroup<string>) => RuleSetGroup;
+/**
+ * Rewrite a rule-set group's declaration refs from CSS var names to canonical **token paths**
+ * (e.g. `--dt-color--primary` → `colors.primary`) using `varToPath`. Refs already absent from the
+ * map are left untouched (var name preserved). Pure — returns a new group. Applied to the Model
+ * copy so `theme.model` is format-neutral; the CSS adapter's own lowering is unaffected.
+ */
+export declare const pathifyRuleSetGroup: (group: RuleSetGroup, varToPath: Record<string, string>) => RuleSetGroup;
+/**
+ * Rewrite property tokens' refs from CSS var names to canonical token paths using `varToPath`
+ * (base / variants / extras). Refs absent from the map are left untouched. Pure — returns a new
+ * map. Used to pathify layout's structural-config `extraProperties` in the Model.
+ */
+export declare const pathifyProperties: (properties: Record<string, PropertyModel>, varToPath: Record<string, string>) => Record<string, PropertyModel>;
+/**
+ * Extract `"subsystem:group.variant"` references from a component variant's normalized base, in
+ * **authored order** — the order the composition references were written (`{ effects, layout }` →
+ * `["effects:…", "layout:…"]`). The CSS adapter renders this ordered list into the className, so the
+ * Model `references` array IS the canonical composition order (the referenced recipe classes precede
+ * the component's own delta class). Only the cross-subsystem keys are recognised; other base keys
+ * (`css`, literals) are skipped.
+ */
+export declare const extractComponentReferences: (rawVariantBase: Record<string, unknown>) => string[];
+/**
+ * An interpreted component variant (its `css` delta) + its cross-subsystem `references`
+ * → a component {@link RuleSet} (`kind: "recipe"`, own delta declarations carry refs,
+ * cross-subsystem pointers kept as `references`).
+ */
+export declare const buildComponentRuleSetFromInterpreted: (variant: InterpretedRecipeVariant<string>, references: string[]) => RuleSet;
+/**
+ * One subsystem's Model input. `ruleSetGroups` carries the already-interpreted rule-sets
+ * (declarations with refs) that `createTheme` produces.
+ */
+export type SubsystemModelInput = {
+    properties?: Record<string, NormalizedPropertyValue<unknown, Record<string, unknown>>>;
+    ruleSetGroups?: Record<string, RuleSetGroup>;
+    /**
+     * Already-built {@link PropertyModel}s to merge into `properties` (after the normalized ones).
+     * Layout uses this to carry its structural config knobs (columns/container size, gutter, inset)
+     * as tokens — the subsystem's `buildStructural` hook emits them (see `subsystems/layout/structural.ts`).
+     */
+    extraProperties?: Record<string, PropertyModel>;
+    /**
+     * Named keyframe definitions (§10.2) — the animation subsystem's `buildStructural` output. Neither
+     * property nor rule-set; attached to {@link SubsystemModel.keyframes} verbatim.
+     */
+    keyframes?: Record<string, Keyframe>;
+};
+/** Everything `buildThemeModel` needs — read from `createTheme`'s live caches/sources. */
+export type BuildThemeModelInput = {
+    breakpoints: Record<string, number>;
+    /** Named query containers (§10.5) — carried onto the Model verbatim. Additive (absent → no field). */
+    containers?: Record<string, ContainerModel>;
+    colors?: SubsystemModelInput;
+    typography?: SubsystemModelInput;
+    layout?: SubsystemModelInput;
+    effects?: SubsystemModelInput;
+    /** Borders (§14): stroke geometry (width/style/offset/radius) + border/outline recipes. */
+    borders?: SubsystemModelInput;
+    animation?: SubsystemModelInput;
+    components?: {
+        ruleSetGroups?: Record<string, RuleSetGroup>;
+    };
+    globals?: SubsystemModelInput;
+};
+/**
+ * One subsystem's Model input → a {@link SubsystemModel} (normalized properties built into
+ * {@link PropertyModel}s, `extraProperties` merged in, rule-set groups attached). Returns
+ * `undefined` when the slice contributes nothing. Exported so `override` can turn a *partial*
+ * subsystem input into a Model fragment with the exact same shape the initial build produces.
+ */
+export declare const buildSubsystemModel: (slice: SubsystemModelInput | undefined) => SubsystemModel | undefined;
+/** Assemble the whole {@link ThemeModel} from the pipeline's normalized data + rule-set groups. */
+export declare const buildThemeModel: (input: BuildThemeModelInput) => ThemeModel;
+/**
+ * Flatten a {@link ThemeModel} into one `path -> Ref` map — one entry per property token:
+ * `"<subsystem>.<property>"` (base), `"<subsystem>.<property>.<variant>"`, and
+ * `"<subsystem>.<property>.<extra>"`. Rule-sets are not tokens and are excluded. Each entry is
+ * the Model's own `Ref` — `{ value }` for a literal, `{ ref }` for a reference. Additive source
+ * for `theme.tokens`; the flat, format-neutral replacement for the per-subsystem `tokens` shape.
+ */
+export declare const buildTokenMap: (model: ThemeModel) => Record<string, Ref>;

package/dist/core/model/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Model layer for the clean-room tree (Step 0c).
+ *
+ * The format-neutral {@link ThemeModel} types + the pure builders that assemble it
+ * from normalized properties and interpreted rule-set groups. Ported from
+ * `core/common/{model,buildModel}.ts`; the interpreted-recipe shape the builders
+ * consume lives in `./interpreted`. No CSS lowering here — that's the CSS adapter (step 1).
+ */
+export type { Literal, ShadowLayer, TransitionPart, StructuredValue, Ref, ResponsiveQueryKind, Orientation, PropertyResponsiveOverride, PropertyModel, VariantModel, OverrideCondition, RuleSetOverride, GlobalsVariant, RuleSet, RuleSetGroup, KeyframeStep, Keyframe, ContainerModel, SubsystemModel, ThemeModel, } from "./model";
+export type { RecipeDeclarations, InterpretedRecipeOverride, InterpretedRecipeVariant, InterpretedRecipeGroup, } from "./interpreted";
+export { buildPropertyModel, buildPropertiesModel, buildRuleSetFromInterpreted, buildRuleSetGroupFromInterpreted, pathifyRuleSetGroup, pathifyProperties, extractComponentReferences, buildComponentRuleSetFromInterpreted, buildSubsystemModel, buildThemeModel, buildTokenMap, } from "./buildModel";
+export type { SubsystemModelInput, BuildThemeModelInput, } from "./buildModel";
+export type { MergedResponsiveEntry, MergedRuleSet, RuleSetReference, } from "./mergeRuleSet";
+export { mergeComponentRuleSet, parseRuleSetReference, } from "./mergeRuleSet";

package/dist/core/model/interpreted.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Interpreted-recipe shape consumed by the Model builders.
+ *
+ * A subsystem's `interpretRecipe` resolves each authored recipe declaration to a
+ * format-neutral {@link Ref} — a token-path reference (`{ ref: "colors.primary" }`,
+ * optionally carrying the resolved literal in `value`) or a plain literal
+ * (`{ value: "12px 20px" }`). It emits refs **directly**; the Model builder no longer
+ * string-parses `var(--…)` back into refs (that coupling is gone). Serialization to a
+ * concrete format (the `var(--…)` string, an `$…`, an inlined value) is the adapter's
+ * job (step 1).
+ *
+ * The two condition axes (state / breakpoint …) are kept **separate** from the
+ * declarations, so an override is `{ …condition, declarations }` — no flat object
+ * mixing string condition keys with declaration refs.
+ */
+import type { Ref } from "./model";
+/** A recipe variant's declarations after interpretation — property → resolved {@link Ref}. */
+export type RecipeDeclarations = Record<string, Ref>;
+/** One interpreted override: its condition (state and/or breakpoint …) + declaration refs. */
+export type InterpretedRecipeOverride<TBreakpoint extends string> = {
+    /** Present for breakpoint-conditioned overrides; absent for pure-state / container overrides. */
+    breakpoint?: TBreakpoint;
+    query?: "min" | "max" | "exact";
+    state?: string;
+    variant?: string;
+    target?: string;
+    orientation?: "landscape" | "portrait";
+    /** Container-query axis (§10.5): the named container + its size-name (in place of `breakpoint`). */
+    container?: string;
+    size?: string;
+    declarations: RecipeDeclarations;
+};
+export type InterpretedRecipeVariant<TBreakpoint extends string> = {
+    base: RecipeDeclarations;
+    responsive: InterpretedRecipeOverride<TBreakpoint>[];
+};
+export type InterpretedRecipeGroup<TBreakpoint extends string> = Record<string, InterpretedRecipeVariant<TBreakpoint>>;

package/dist/core/model/mergeRuleSet.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Format-neutral component merge (§9c).
+ *
+ * `mergeComponentRuleSet` flattens one component variant into a single
+ * self-contained rule-set: its referenced recipes' declarations + its own `css`
+ * delta, unioned. The result is pure Model data — declarations stay as {@link Ref}s
+ * carrying `{ ref, value }` — so an adapter renders it as baked values (inline) or
+ * `var(--…)` / `theme.…` (referenced) without any format decision leaking in here.
+ *
+ * This is the ONLY new machinery the `components` emit mode needs, shared by the CSS
+ * and future SC adapters. It is **on-demand** (an adapter calls it in `emit()`), never
+ * materialized on `ThemeModel` / the runtime `theme`. It does NOT mutate the authored
+ * `RuleSet` / declarations — the merged view is freshly derived (Refs shallow-cloned).
+ *
+ * Precedence (LOCKED, §9): authored **reference order** first (later refs override
+ * earlier per property key), then the component's own declarations **last / highest**
+ * (`css` delta wins over subsystem recipes). Same rule per condition bucket.
+ */
+import type { Orientation, Ref, ResponsiveQueryKind, ThemeModel } from "./model";
+/**
+ * One flattened conditioned bucket — a distinct `(breakpoint, query, orientation, state, container, size)`
+ * key. A **viewport** entry carries `breakpoint`; a **container** entry (§10.5) carries `container` + `size`
+ * (and no `breakpoint`). The adapter emits the former as `@media`, the latter as `@container`.
+ */
+export type MergedResponsiveEntry = {
+    breakpoint?: string;
+    query?: ResponsiveQueryKind;
+    orientation?: Orientation;
+    state?: string;
+    container?: string;
+    size?: string;
+    declarations: Record<string, Ref>;
+};
+/**
+ * A component variant flattened into one self-contained rule-set.
+ *
+ * - `base`            — merged no-condition declarations.
+ * - `states`          — merged declarations keyed by `state` (no breakpoint).
+ * - `responsive`      — one entry per distinct `(breakpoint, query, orientation, state)` merge key.
+ * - `referencedPaths` — every distinct token path (`Ref.ref`) appearing across all buckets,
+ *                        first-appearance order. What non-inline rendering tree-shakes the vars file to.
+ */
+export type MergedRuleSet = {
+    base: Record<string, Ref>;
+    states: Record<string, Record<string, Ref>>;
+    responsive: MergedResponsiveEntry[];
+    referencedPaths: string[];
+};
+/** The address parts of a component reference (`"colors:solid.primary"`). */
+export type RuleSetReference = {
+    subsystem: string;
+    group: string;
+    variant: string;
+};
+/**
+ * Parse a component reference (`"subsystem:group.variant"`) into its address parts.
+ * Format-neutral core twin of the CSS adapter's `parseComponentReference` (which stays
+ * for the option-C class-list path). Returns `undefined` on a malformed reference.
+ */
+export declare const parseRuleSetReference: (reference: string) => RuleSetReference | undefined;
+/**
+ * Flatten one component variant into a self-contained {@link MergedRuleSet}.
+ *
+ * Reads `model.subsystems.components.ruleSets[group][variant]` — its `references`
+ * (resolved in authored order), own base `declarations`, and `overrides` — and unions
+ * them under the locked precedence. Throws on a missing component or an unresolved reference.
+ */
+export declare const mergeComponentRuleSet: (model: ThemeModel, group: string, variant: string) => MergedRuleSet;

package/dist/core/model/model.d.ts

@@ -0,0 +1,260 @@
+/**
+ * Format-neutral Model types (clean-room port of `core/common/model.ts`).
+ *
+ * The representation every subsystem produces. The Model has just two kinds of
+ * thing — **tokens** (`PropertyModel`) and **rule-sets** (`RuleSet`) — and one
+ * shared reference node (`Ref`) for every leaf. Adapters lower the Model to
+ * CSS / SCSS / styled-components / JSON; the Model itself commits to no format.
+ *
+ * See `.notes/reference/model-first-pipeline-plan.md` for the full design.
+ */
+/** A resolved literal value a `Ref` can carry (unit-less, no `var()` / `$`). */
+export type Literal = string | number;
+export type ResponsiveQueryKind = "min" | "max" | "exact";
+export type Orientation = "landscape" | "portrait";
+import type { Unit, ShadowDimension } from "../units";
+/**
+ * A structured box-shadow layer (§15) — geometry as unit-less px numbers, `color` a **token-path
+ * ref** (`"colors.shadow"`) the adapter resolves late (CSS `var(--…)`, RN `shadowColor`). Kept
+ * structured (not a pre-serialized CSS string) so non-CSS adapters can lower each field; the CSS
+ * adapter composes `<offsetX> <offsetY> <blur> <spread> var(--color)`. A box-shadow value is one
+ * or more layers ({@link StructuredValue}).
+ */
+export type ShadowLayer = {
+    offsetX?: ShadowDimension;
+    offsetY?: ShadowDimension;
+    blur?: ShadowDimension;
+    spread?: ShadowDimension;
+    /** Canonical `colors.*` token path (never an embedded literal — §15.1). Translucency comes from
+     * the referenced colour itself — an `alpha` colour variant (§13.3) — not a shadow-level field. */
+    color?: string;
+    inset?: boolean;
+};
+/**
+ * A structured transition part (§15) — `property` + `duration`/`delay` in **ms** (numbers) +
+ * `timingFunction` (keyword or `cubic-bezier(…)` string, not a ref in v1 — §15.5). Kept structured
+ * so RN/JSON can lower it; the CSS adapter composes `<property> <duration>ms <timing> <delay>ms`.
+ * A transition value is one or more parts ({@link StructuredValue}).
+ */
+export type TransitionPart = {
+    property: string;
+    duration?: number;
+    timingFunction?: string;
+    delay?: number;
+};
+/**
+ * A structured compound leaf value (§15) — the Model's format-neutral carriage for shadow /
+ * transition tokens whose value is not a single {@link Literal}. Always an **array** (canonicalized
+ * in the owning subsystem's coerce step): a single-layer/part token is a one-element array, so
+ * adapters map+join uniformly. Carried on {@link Ref.struct}; `Ref.value` stays a `Literal` cache.
+ */
+export type StructuredValue = ShadowLayer[] | TransitionPart[];
+/**
+ * The one shared reference node — every leaf in both the property and rule-set
+ * models is a `Ref`. At least one of `ref` / `value` is present.
+ *
+ * - `ref`   — canonical token path in the model namespace, e.g. `"color.primary.dark"`.
+ *             A property leaf's `ref` is its own address; a rule-set declaration's
+ *             `ref` points into that namespace. The adapter turns it into
+ *             `var(--…)` / `$…` / `theme.…` / the inlined value.
+ * - `value` — the resolved literal (for inlining, or when there is no token).
+ * - `fn`    — value-derivation fn name (run by the derivation registry), e.g. `"darken"`:
+ *             the token's value = `fn(resolve(ref), arg)`. Requires `ref`.
+ * - `arg`   — argument passed to the derivation `fn` (also where synthesis config is retained).
+ * - `wrap`  — adapter OUTPUT wrap on a rule-set declaration, e.g. `"blur"` → CSS `blur(<value>)`.
+ *             Distinct from `fn`; never appears on a token.
+ * - `struct`— a structured compound value (§15) for shadow / transition tokens whose value is not a
+ *             single `Literal` (an array of {@link ShadowLayer} / {@link TransitionPart}). Additive:
+ *             adapters that understand the structure compose it; `value` remains the `Literal` cache
+ *             (undefined for a purely-structured token). Never appears on a rule-set declaration ref.
+ * - `unit`  — the resolved length unit on a length leaf (§21). Present only after unit resolution has
+ *             tagged this leaf (`{ value: 24, unit: "rem" }`); absent means unit-less (opacity/zIndex)
+ *             or a raw-string value. Adapters stringify a length leaf as `value + (unit ?? "")`.
+ */
+export type Ref = {
+    ref?: string;
+    value?: Literal;
+    fn?: string;
+    arg?: unknown;
+    /**
+     * dec.2 — an ordered derivation CHAIN applied to the resolved `ref` (folded left-to-right by
+     * `resolveToken`: `value = modifiers.reduce((v, {fn,arg}) => registry[fn](v, arg), resolve(ref))`).
+     * Set by the `{ ref, modifiers }` authoring grammar; single-step synthesized derivations
+     * (tonal steps / harmony) still use the flat `fn`/`arg`. Present ⇒ `fn`/`arg` are absent.
+     */
+    modifiers?: Array<{
+        fn: string;
+        arg?: unknown;
+    }>;
+    wrap?: string;
+    struct?: StructuredValue;
+    unit?: Unit;
+    /**
+     * §W6b — an **external** token: a passthrough to a CSS variable a *parent* theme defines. The
+     * string is the literal parent var name (`--dt-colors-brand` / `--mat-sys-bg`). When present the
+     * token is never emitted as a definition (the parent owns it); references lower to `var(<external>)`
+     * verbatim, `resolveToken` yields that `var(…)` string, and colour synthesis is skipped.
+     */
+    external?: string;
+};
+/**
+ * A property (token) after `buildPropertyModel`: resolved values kept as `Ref`s,
+ * variants, and responsive as structured data. Subsystem-specific sibling nodes
+ * (e.g. colors' `text`) live in `extras`. ({@link PropertyOverride} + {@link OverrideCondition}
+ * are defined below, in the shared rule-set section — modes/responsive/states share that spine.)
+ */
+/**
+ * dec.3 — one property variant in the Model. `base` is the variant's primary value (a literal or
+ * derived `Ref`, or an alias to the property base when the author omitted it — base optional + inherit).
+ * `extras` are the variant's own sibling values (e.g. colours' `text`), each lowered to
+ * `--<prop>-<variant>-<extra>`, exactly like the property-level {@link PropertyModel.extras}.
+ */
+export type VariantModel = {
+    base: Ref;
+    extras?: Record<string, Ref>;
+};
+export type PropertyModel = {
+    base: Ref;
+    variants?: Record<string, VariantModel>;
+    /**
+     * Appearance-mode overrides (§10.3) — a **list** of {@link PropertyOverride}s, each carrying its
+     * `mode` (+ optional `target` to scope into a variant's var) and an `overrides` field-map (`base`
+     * + subsystem extras like colours' `text`, each a literal or derived `Ref`). A list (not a
+     * `mode → fields` map) so one mode can carry several targeted entries. Adapters group by `mode`
+     * and realize each as conditional blocks (CSS: `prefers-color-scheme` media + `[data-theme]`).
+     */
+    modes?: PropertyOverride[];
+    responsive?: PropertyOverride[];
+    extras?: Record<string, Ref>;
+};
+/**
+ * The **shared override spine** — the one condition/target structure every override array entry
+ * carries (property `modes` / `responsive`, recipe `states` / `responsive`). Each array fills only
+ * the axes meaningful to it; all are optional here. Three axes of intent:
+ *  - **WHEN** — `mode` (appearance mode) · `state` (recipe pseudo-state) · `breakpoint` (+`query` /
+ *    `orientation`) · `container` + `size` (container-query, in place of `breakpoint`).
+ *  - **WHERE** — `target`: scope the override into a variant's var / a `<item>-<variant>` sibling
+ *    rule (omit → the base var / base rule).
+ *  - **READ** — `ref` (dec.5 read-source: the destination swaps to this variant's var) · `variant`
+ *    (recipe swap to a sibling rule-set of the same group).
+ * `PropertyOverride` and `RuleSetOverride` extend this with their respective payload record.
+ */
+export type OverrideCondition = {
+    /** appearance-mode condition (property modes; property responsive via dec.9). */
+    mode?: string;
+    /** recipe pseudo-state condition (recipe states + responsive). */
+    state?: string;
+    breakpoint?: string;
+    query?: ResponsiveQueryKind;
+    orientation?: Orientation;
+    /** Container-query axis (§10.5): the named container this override responds to (in place of `breakpoint`). */
+    container?: string;
+    /** The size-name in that container's threshold scale (used with `container`). */
+    size?: string;
+    /** dec.5 READ source: the destination var swaps to this variant's var (`var(--<prop>-<ref>)`). */
+    ref?: string;
+    /** swap to a sibling rule-set of the same group (recipe responsive). */
+    variant?: string;
+    /** WHERE — scope the override into a variant's var / a sibling rule-set's rule. */
+    target?: string;
+};
+/**
+ * One conditioned override on a **property's tokens** (a `modes` or `responsive` entry). The payload
+ * is `field → Ref` (`base` + subsystem extras like colours' `text`), each a literal or derived `Ref`.
+ * Shares {@link OverrideCondition} with recipe overrides; a mode entry carries `mode`, a responsive
+ * entry carries `breakpoint` (+ optionally `mode`), either may carry `target`.
+ */
+export type PropertyOverride = OverrideCondition & {
+    overrides?: Record<string, Ref>;
+};
+/**
+ * @deprecated Use {@link PropertyOverride}. Retained as an alias during the unified-override-array
+ * migration; a property `responsive` entry is a `PropertyOverride`.
+ */
+export type PropertyResponsiveOverride = PropertyOverride;
+/** One conditioned override on a rule-set — `state` and/or `breakpoint` + its declarations. */
+export type RuleSetOverride = OverrideCondition & {
+    declarations?: Record<string, Ref>;
+};
+/**
+ * One `globals` element variant (§9) — a named, delta-only modifier on a themed element rule-set.
+ * Carries just what it changes (its own `declarations` + condition `overrides`); the cascade
+ * supplies the base. Adapters render it as a higher-specificity selector — the CSS adapter as a
+ * self-scoped class (`a.subtle`), the styled-components / SCSS adapters as a nested `&.<name>`
+ * block. Kept structural (a base selector + this named-variant map) so each adapter builds its own
+ * idiom, rather than a pre-joined selector baked into the Model.
+ */
+export type GlobalsVariant = {
+    declarations: Record<string, Ref>;
+    overrides: RuleSetOverride[];
+};
+/**
+ * A named `{ declarations, overrides }` block — the one shape for everything on the
+ * non-token side. Recipes are the authored flavor; layout grids/stacks/container/columns
+ * are presets/generated; reset/base rule-sets target raw element selectors. Keyed by real
+ * kebab-case CSS properties (`"box-sizing"`, `"font-size"`).
+ *
+ * - `kind`         — `"recipe"` (composable; default), `"utility"` (apply-in-markup, e.g. columns),
+ *                    `"reset"` (the `globals` normalization preset layer — targets an explicit
+ *                    `selector` at specificity-0 `:where(sel)`), or `"globals"` (a themed element
+ *                    rule — targets a bare `selector` at a higher tier, carrying `variants`).
+ * - `selector`     — `kind:"reset"` / `kind:"globals"` only: the raw selector this rule-set targets
+ *                    (element `h1` / grouped `h1,h2` / universal `*` / attribute `[hidden]` / pseudo
+ *                    `::placeholder`). `reset` wraps it for specificity-0 (`:where(sel)`); `globals`
+ *                    emits it bare; absent for minted classes.
+ * - `references`   — components only: `"subsystem:group.variant"` recipe-level refs (composition).
+ * - `declarations` — base (no condition).
+ * - `overrides`    — the unified state/breakpoint condition list.
+ * - `variants`     — `kind:"globals"` only: named delta modifiers (§9), each an adapter-scoped
+ *                    higher-specificity variant of the element (`a.subtle` / `&.subtle`).
+ */
+export type RuleSet = {
+    kind?: "recipe" | "utility" | "reset" | "globals";
+    selector?: string;
+    references?: string[];
+    declarations: Record<string, Ref>;
+    overrides: RuleSetOverride[];
+    variants?: Record<string, GlobalsVariant>;
+};
+/** A named group of rule-sets: variant/name → `RuleSet` (e.g. `solid`, `grids`, `columns`). */
+export type RuleSetGroup = Record<string, RuleSet>;
+/**
+ * One step of a keyframe — its stop position + the declarations at that stop. The `stop` is the
+ * authored key kept **verbatim** (`"from"`, `"to"`, `"0%"`, `"50%"`, even a grouped `"0%, 100%"`),
+ * so the representation commits to no format — a CSS adapter renders `<stop> { … }`, an SC adapter
+ * feeds its `keyframes` helper, an RN adapter maps stops to `Animated` interpolation points.
+ * Declarations are `Ref`s: a literal geometric value (`{ value: 0 }`) or a token-path reference
+ * (`{ ref: "colors.surface" }`) resolved late by the adapter, so a keyframe can animate a themed value.
+ */
+export type KeyframeStep = {
+    stop: string;
+    declarations: Record<string, Ref>;
+};
+/**
+ * A named keyframe definition — an **ordered** list of steps (authoring order preserved). The first
+ * Model member that is neither a token ({@link PropertyModel}) nor a class/selector rule-set
+ * ({@link RuleSet}): an `@keyframes`-shaped at-rule with nested step selectors. Adapters realize it
+ * (CSS: an `@keyframes name { … }` at-rule).
+ */
+export type Keyframe = {
+    steps: KeyframeStep[];
+};
+/** One subsystem's slice of the Model: its tokens, its rule-set groups, and its keyframes. */
+export type SubsystemModel = {
+    properties?: Record<string, PropertyModel>;
+    ruleSets?: Record<string, RuleSetGroup>;
+    /** Named keyframe definitions (§10.2) — `name → {@link Keyframe}`. Present only for the animation subsystem. */
+    keyframes?: Record<string, Keyframe>;
+};
+/** One named query container (§10.5) — its `container-type` + `sizeName → px` threshold scale. */
+export type ContainerModel = {
+    type: "inline-size" | "size";
+    sizes: Record<string, number>;
+};
+/** The whole theme as format-neutral data — serializable as-is (build-time emit). */
+export type ThemeModel = {
+    breakpoints: Record<string, number>;
+    /** Named query containers (§10.5) — present only when the theme authors `containers`. Additive. */
+    containers?: Record<string, ContainerModel>;
+    subsystems: Record<string, SubsystemModel>;
+};

package/dist/core/noopAdapter.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `createNoopAdapter` — the trivial, built-in null adapter (monorepo split, friction 2).
+ *
+ * `createTheme` requires an `adapter`, but some consumers of the built `Theme` never touch
+ * adapter-produced strings — they read only the format-neutral `theme.tokens` / `theme.resolveToken`
+ * / `theme.model` (the DTCG export is the canonical example: `toDTCG` walks the flat token map and the
+ * breakpoints, never a rendered rule). Those callers need *a* valid adapter purely to satisfy the
+ * contract; the output is discarded.
+ *
+ * Before the split the CLI's `tokens` command reached for `createCssAdapter` as that throwaway builder
+ * — which forced a core→adapter dependency (`src/build` importing `src/adapters/css`). The monorepo
+ * guiding rule is that the dependency arrow points ONLY into core, so core now ships its own null
+ * object: `createNoopAdapter()` emits nothing (empty strings, an empty `emit()`), lets `createTheme`
+ * build the Model + token map exactly as any adapter would, and keeps `src/build` free of every
+ * adapter package.
+ *
+ * It's a `ThemeAdapter` like any other (built through {@link defineAdapter}, so it gets the defaulted
+ * aggregators for free), just with render primitives that produce empty output.
+ */
+import type { ThemeAdapter } from "./ThemeAdapter";
+/**
+ * A no-op adapter: every render primitive returns an empty string and `emit()` writes no files. Use it
+ * whenever a `Theme` is needed only for its format-neutral data (`tokens` / `resolveToken` / `model`)
+ * and the rendered output is irrelevant — e.g. the `refract tokens` DTCG export.
+ */
+export declare function createNoopAdapter(): ThemeAdapter<string>;

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

@@ -0,0 +1,15 @@
+/**
+ * Shared normalize primitives + the normalize-layer vocabulary (Step 0b).
+ *
+ * Pure, format-neutral: raw theme config to normalized property / recipe shapes,
+ * validating breakpoint / variant / target / state references along the way.
+ * Subsystem normalizeProperty hooks (colors steps, typography scale, layout none)
+ * live under src/next/subsystems/-star-/normalize.ts and layer on top.
+ */
+export * from "./types";
+export { normalizePropertyValue } from "./properties";
+export { DEFAULT_RESPONSIVE_QUERY, normalizeResponsiveOverrides, validateNormalizedResponsiveRefs, } from "./responsive";
+export { normalizeRecipeGroup } from "./recipes";
+export type { RecipeNormalizationOptions } from "./recipes";
+export { createRecipeVariantResolver } from "./recipeResolver";
+export type { RecipeInterpreter, RecipeVariantResolver, CreateRecipeVariantResolverOptions, } from "./recipeResolver";

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

@@ -0,0 +1,20 @@
+/**
+ * Property normalization — the entry point that turns any authored property value
+ * into the canonical {@link NormalizedPropertyValue} shape.
+ *
+ * Collapses the three authoring forms (a bare value, or an extended object with
+ * `base` / `variants` / `responsive`, plus subsystem `extra` fields) into one shape:
+ * a resolved `base`, a normalized `variants` map, and a normalized `responsive` list.
+ */
+import { NormalizedPropertyValue, PropertyNormalizationOptions, PropertyValue } from "./types";
+/**
+ * Normalize any authored property value into the canonical {@link NormalizedPropertyValue}.
+ *
+ * @param value   A bare value or an extended `{ base, variants?, responsive?, …extra }` object.
+ * @param options `propertyPath` (error labels), `fallbackBase`, `coerceValue`, and
+ *   `allowedBreakpoints` (responsive breakpoint validation).
+ * @returns `{ base, responsive, variants?, …extra }` — `responsive` always an array,
+ *   each entry with its `query` defaulted; `variants` normalized or `undefined`.
+ * @throws If no base value can be resolved, or a responsive entry fails validation.
+ */
+export declare const normalizePropertyValue: <TValue, TExtra extends Record<string, unknown> = Record<string, never>, TBreakpoint extends string = string>(value: PropertyValue<TValue, TExtra, TBreakpoint>, options?: PropertyNormalizationOptions<TValue, TBreakpoint>) => NormalizedPropertyValue<TValue, TExtra, TBreakpoint>;

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

@@ -0,0 +1,19 @@
+/**
+ * Lazy, memoized, cycle-safe recipe-variant resolver (clean-room port of
+ * `core/common/recipeResolver.ts`).
+ *
+ * A recipe variant may reference a sibling variant (responsive `variant:` swaps). The
+ * resolver interprets each variant on demand, caches the result, and detects cycles
+ * (throwing with the offending chain). The interpret callback receives a `resolve`
+ * function so it can pull a sibling's already-interpreted form.
+ */
+import type { NormalizedRecipeGroup, NormalizedRecipeVariant } from "./types";
+export type RecipeInterpreter<TProps extends Record<string, unknown>, TBreakpoint extends string, TInterpreted> = (variantName: string, variant: NormalizedRecipeVariant<TProps, TBreakpoint>, resolve: (variantName: string) => TInterpreted) => TInterpreted;
+export type RecipeVariantResolver<TInterpreted> = {
+    resolve: (variantName: string) => TInterpreted;
+    resolveAll: () => Record<string, TInterpreted>;
+};
+export type CreateRecipeVariantResolverOptions = {
+    groupPath?: string;
+};
+export declare const createRecipeVariantResolver: <TProps extends Record<string, unknown>, TBreakpoint extends string, TInterpreted>(group: NormalizedRecipeGroup<TProps, TBreakpoint>, interpret: RecipeInterpreter<TProps, TBreakpoint, TInterpreted>, options?: CreateRecipeVariantResolverOptions) => RecipeVariantResolver<TInterpreted>;