@exponential-at/ui 0.0.0-stage → 0.1.0

package/dist/types/src/prompt.d.ts

@@ -0,0 +1,44 @@
+import type { ComponentDef, ExtensionDef } from "./types.js";
+/** The sections of the prompt, in print order (VAPP-108): an agent (or the
+ *  host serving it) asks for the ones it needs. `index` = one line per
+ *  component (name, group, description) instead of the full `components`
+ *  blocks: the agent reads the index, then asks for `componentPrompt(name)`
+ *  of the ones it will use. */
+export type PromptSection = `rules` | `components` | `index` | `shapes` | `functions` | `style` | `extensions`;
+export declare const PROMPT_SECTIONS: readonly PromptSection[];
+/** What `catalogPrompt()` prints without `sections`. */
+export declare const DEFAULT_SECTIONS: readonly PromptSection[];
+export interface PromptOptions {
+    extensions?: readonly ExtensionDef[];
+    /** The core-lite subset (the app-shaped vocabulary: no overlays, media, Chart, data tables or the rarer controls). */
+    lite?: boolean;
+    /** Omit the per-prop lines (names + types only). */
+    terse?: boolean;
+    /** VAPP-108: which sections to print (default `DEFAULT_SECTIONS`, in that order whatever the order given). */
+    sections?: readonly PromptSection[];
+    /** VAPP-108: print only these components (full blocks) and the shapes they reach; `index` still lists every one. */
+    only?: readonly string[];
+}
+/** The rules every surface author (a model) must follow, shared by the core
+ *  and the basic catalog. Kept to a few lines on purpose. */
+export declare const PROMPT_RULES: readonly string[];
+/** Props whose meaning is the same everywhere: described ONCE in the full
+ *  prompt (the per-prop line then carries only name, marks and type). The
+ *  catalog keeps every per-component description for the docs. */
+export declare const COMMON_PROPS: Readonly<Record<string, string>>;
+export declare function componentBlock(name: string, def: ComponentDef, enums: Record<string, readonly string[]>, terse: boolean): string;
+/** Every catalog function as `name(arg:type,…)→returns` (round 4: the
+ *  model sees the argument names, not just the function names). */
+export declare function functionSignatures(): string[];
+/** VAPP-108: one component's full block on demand (the per-component
+ *  section an agent requests after reading the index), with the shapes its
+ *  props reach. Unknown or hidden names give an empty string. */
+export declare function componentPrompt(name: string, options?: Pick<PromptOptions, `extensions` | `terse`>): string;
+/** VAPP-108: the index — every offered component on one line (name, group, kind, its sentence), grouped. */
+export declare function catalogIndex(options?: Pick<PromptOptions, `extensions` | `lite`>): string[];
+/** The system prompt for a surface author. */
+export declare function catalogPrompt(options?: PromptOptions): string;
+/** Characters per token the budget assumes (the same rule as the context
+ *  layout's `charsPerToken`): an estimate, not a tokenizer. */
+export declare const CHARS_PER_TOKEN = 4;
+export declare function estimateTokens(text: string): number;

package/dist/types/src/recipes.d.ts

@@ -0,0 +1,17 @@
+import type { ExtensionDef, MacroDef } from "./types.js";
+export declare const RECIPE_STATES: readonly string[];
+export declare const RECIPE_KEYS: readonly string[];
+export interface PartSpec {
+    parts: string[];
+    /** The prop names a `when` may use (besides `state`). */
+    props: string[];
+}
+/** A macro's parts and recipe props, read off its template. */
+export declare function macroParts(def: MacroDef): PartSpec;
+/** Every component (core + the given extensions) → its parts and `when`
+ *  props. An extension's natives declare `recipe: {parts, props}` on their
+ *  component def; without it a native gets `root` and its enum/boolean props. */
+export declare function recipeParts(extensions?: readonly ExtensionDef[]): Record<string, PartSpec>;
+/** The recipe query a NATIVE node answers to: its `when` props with the
+ *  catalog defaults filled in (a macro part carries its own `recipe`). */
+export declare function nativeRecipeProps(component: string, props: Record<string, unknown>, extensions?: readonly ExtensionDef[]): Record<string, unknown>;

package/dist/types/src/reducer.d.ts

@@ -0,0 +1,41 @@
+import type { ChildTemplate, ExtensionDef, FlatComponent, NestedNode, ReduceIssue, UiNode, Visible, WireChildTemplate } from "./types.js";
+/** The keys of a flat component that are not props (round 1 adds `visible`). */
+export declare const RESERVED_KEYS: readonly string[];
+export interface ReduceOptions {
+    /** The surface's catalog: the core, the lite subset, the basic catalog or an extension's id. */
+    catalogId: string;
+    extensions?: readonly ExtensionDef[];
+    /** The root component id (A2UI: `root`). */
+    rootId?: string;
+    /** Expand macros (default true); false keeps the pre-expansion tree. */
+    expand?: boolean;
+    /** Record prop validation issues (default true). */
+    validate?: boolean;
+}
+export interface ReduceResult {
+    root: UiNode;
+    issues: ReduceIssue[];
+    /** Round 2 (docs/round-2-contract.md §4): the nodes a data `template`
+     *  renders per item, by component id, LIFTED out of the tree (a template
+     *  node listed as a child too never renders in place), validated and
+     *  expanded like the root; in discovery order. Absent without templates. */
+    templates?: Record<string, UiNode>;
+}
+/** A `visible` value is a boolean or a dynamic value (a binding or a call). */
+export declare function validVisible(value: unknown): value is Visible;
+export declare function childTemplate(value: WireChildTemplate): ChildTemplate;
+/** Reduce a flat component list. Children are resolved from the root down, so
+ *  components nothing references (a basic Button's consumed Text child) do
+ *  not appear. A missing or cyclic reference becomes an Unknown placeholder
+ *  plus an issue. VAPP-103: an id placed a second time (two parents, or one
+ *  parent twice) renders at its first place only (`id used twice`), a node
+ *  deeper than `maxDepth` is an Unknown placeholder, and past
+ *  `maxComponents` nodes the rest is dropped (catalog/limits.json). */
+export declare function reduceSurface(components: readonly FlatComponent[], options: ReduceOptions): ReduceResult;
+/** A component's slot list admits a name when it lists it or lists `*`. */
+export declare function slotAllowed(slots: readonly string[] | undefined, name: string): boolean;
+/** The nested authoring form → a normalized tree (same validation and
+ *  expansion as reduceSurface). */
+export declare function reduceNested(tree: NestedNode, options: Omit<ReduceOptions, `rootId`>): ReduceResult;
+/** Pre-order ids of a tree, the painters' accessibility order. */
+export declare function preorder(root: UiNode): string[];

package/dist/types/src/resizable.d.ts

@@ -0,0 +1,38 @@
+/** One panel's limits (Resizable `panels[i]`), percent. */
+export interface PanelLimits {
+    min?: number;
+    max?: number;
+    /** Dragging below half its `min` collapses it to 0; Enter toggles. */
+    collapsible?: boolean;
+}
+export { PANEL_MIN, RESIZE_HANDLE_HIT, RESIZE_STEP } from "./layout.js";
+/** The sizes a group of `count` panels starts with: the valid given sizes
+ *  (finite, ≥ 0), the missing ones sharing what is left of 100 (equal split
+ *  when nothing is given), scaled to sum 100, then each clamped into its
+ *  [min, max] (a collapsible panel may stay at 0) with the difference handed
+ *  to the panels that still have room, in order. A `min` above 100 / count
+ *  is lowered to it. */
+export declare function normalizeSizes(sizes: readonly unknown[] | undefined, count: number, limits?: readonly PanelLimits[]): number[];
+/** Move handle `handle` (between panels `handle` and `handle + 1`) by
+ *  `delta` percentage points (positive = the first panel grows). Always
+ *  computed from the sizes at the START of a drag (no drift). The move is
+ *  clamped so both panels stay in their [min, max]; a collapsible panel
+ *  dragged below half its min collapses to 0 (the other takes its space, if
+ *  it can), and a collapsed one dragged past half its min reopens: at its
+ *  min, or where the pointer is when that is further (clamped as above).
+ *  Other panels never change. */
+export declare function resizePanels(sizes: readonly number[], handle: number, delta: number, limits?: readonly PanelLimits[]): number[];
+export type ResizeKey = `ArrowLeft` | `ArrowRight` | `ArrowUp` | `ArrowDown` | `Home` | `End` | `Enter`;
+/** A key on a focused handle. Arrows move the HANDLE on screen by
+ *  RESIZE_STEP (horizontal group: Left/Right — in rtl the first panel sits
+ *  on the right, so ArrowRight shrinks it; vertical group: Up/Down); Home /
+ *  End take the first panel to its min / max (as far as the second allows);
+ *  Enter collapses the first panel when collapsible (else the second),
+ *  reopening a collapsed one at its min. Other keys change nothing. */
+export declare function keyboardResize(sizes: readonly number[], handle: number, key: ResizeKey | string, orientation: `horizontal` | `vertical`, direction?: `ltr` | `rtl`, limits?: readonly PanelLimits[]): number[];
+/** Panel lengths in px on the main axis: the container minus every handle
+ *  (`handleExtent` each, `$control.hairline`), shared by the sizes. */
+export declare function panelExtents(sizes: readonly number[], container: number, handleExtent?: number): number[];
+/** A pointer movement (px on the main axis, screen direction) as the
+ *  percentage delta `resizePanels` takes (rtl horizontal groups flip it). */
+export declare function dragDelta(px: number, container: number, panelCount: number, orientation: `horizontal` | `vertical`, direction?: `ltr` | `rtl`, handleExtent?: number): number;

package/dist/types/src/schema.d.ts

@@ -0,0 +1,7 @@
+import type { ExtensionDef } from "./types.js";
+type Json = Record<string, unknown>;
+/** The core catalog's JSON Schema. */
+export declare function coreSchema(iconNames: readonly string[]): Json;
+/** An extension's JSON Schema: its own id, `extends` the core, its components. */
+export declare function extensionSchema(ext: ExtensionDef, iconNames: readonly string[]): Json;
+export {};

package/dist/types/src/strings.d.ts

@@ -0,0 +1,13 @@
+export declare const DEFAULT_STRINGS: Readonly<Record<string, string>>;
+export declare const STRING_IDS: readonly string[];
+/** `$string.choose` → `choose`; null for any other value. */
+export declare function parseStringRef(value: unknown): string | null;
+/** True for a well-formed reference to a KNOWN id. */
+export declare function isStringRef(value: unknown): boolean;
+/** The host's overrides merged over the defaults. */
+export declare function stringTable(overrides?: Readonly<Record<string, string>>): Record<string, string>;
+/** `{name}` placeholders filled from `params`; unknown ones stay. */
+export declare function formatString(template: string, params?: Record<string, unknown>): string;
+/** A prop value with any `$string.<id>` reference replaced by the table's
+ *  text (an unknown id resolves to the id itself); other values pass. */
+export declare function resolveString(value: unknown, table?: Readonly<Record<string, string>>): unknown;

package/dist/types/src/style.d.ts

@@ -0,0 +1,201 @@
+export declare const STYLE_KEYS: readonly string[];
+export declare const STYLE_LAYOUT_KEYS: readonly string[];
+export declare const STYLE_VISUAL_KEYS: readonly string[];
+/** The visual keys that move layout (`borderWidth` and the four sides). */
+export declare const STYLE_LAYOUT_EFFECT_KEYS: readonly string[];
+export declare const STYLE_MEDIA: RegExp;
+export declare const STYLE_TRANSFORM: RegExp;
+/** The state keys in the order they apply (the last wins). */
+export declare const STYLE_STATES: readonly string[];
+export declare const STYLE_MEDIA_PATTERN: string;
+export declare const STYLE_TRANSFORM_PATTERN: string;
+type Len = number | `${number}%` | `${number}px` | `auto` | `$${string}`;
+type Color = `$color.${string}`;
+type Align = `flex-start` | `flex-end` | `start` | `end` | `center` | `stretch` | `baseline`;
+type Distribute = Align | `space-between` | `space-around` | `space-evenly`;
+type Overflow = `visible` | `hidden` | `clip` | `scroll` | `auto`;
+/** A gradient painted over `backgroundColor`: CSS angle (0 = up, 90 = right)
+ *  and colour stops at 0..1 offsets. */
+export interface Gradient {
+    angle: number;
+    stops: {
+        color: Color;
+        offset: number;
+    }[];
+}
+/** Typed keys = editor autocomplete + a compile error for anything else. */
+export interface StyleProps {
+    display?: `flex` | `grid` | `block` | `none`;
+    flexDirection?: `row` | `column` | `row-reverse` | `column-reverse`;
+    flexWrap?: `nowrap` | `wrap` | `wrap-reverse`;
+    justifyContent?: Distribute;
+    alignItems?: Align;
+    alignContent?: Distribute;
+    alignSelf?: Align;
+    justifySelf?: Align;
+    flexGrow?: number;
+    flexShrink?: number;
+    flexBasis?: Len;
+    gap?: Len;
+    rowGap?: Len;
+    columnGap?: Len;
+    direction?: `ltr` | `rtl`;
+    overflow?: Overflow;
+    overflowX?: Overflow;
+    overflowY?: Overflow;
+    width?: Len;
+    height?: Len;
+    minWidth?: Len;
+    minHeight?: Len;
+    maxWidth?: Len;
+    maxHeight?: Len;
+    aspectRatio?: number | `${number}/${number}`;
+    position?: `relative` | `absolute` | `sticky`;
+    top?: Len;
+    right?: Len;
+    bottom?: Len;
+    left?: Len;
+    inset?: Len;
+    insetInlineStart?: Len;
+    insetInlineEnd?: Len;
+    insetBlockStart?: Len;
+    insetBlockEnd?: Len;
+    padding?: Len;
+    paddingTop?: Len;
+    paddingRight?: Len;
+    paddingBottom?: Len;
+    paddingLeft?: Len;
+    paddingHorizontal?: Len;
+    paddingVertical?: Len;
+    paddingInlineStart?: Len;
+    paddingInlineEnd?: Len;
+    margin?: Len;
+    marginTop?: Len;
+    marginRight?: Len;
+    marginBottom?: Len;
+    marginLeft?: Len;
+    marginHorizontal?: Len;
+    marginVertical?: Len;
+    marginInlineStart?: Len;
+    marginInlineEnd?: Len;
+    /** Track list: px, %, fr, auto, min-content, max-content, minmax(a, b), repeat(n, …). */
+    gridTemplateColumns?: string;
+    gridTemplateRows?: string;
+    /** One string per row (`["nav main", "nav footer"]`). */
+    gridTemplateAreas?: ReadonlyArray<string>;
+    gridArea?: string;
+    gridColumn?: string;
+    gridRow?: string;
+    backgroundColor?: Color;
+    backgroundGradient?: Gradient;
+    color?: Color;
+    borderWidth?: number | `$border.${string}`;
+    borderTopWidth?: number | `$border.${string}`;
+    borderRightWidth?: number | `$border.${string}`;
+    borderBottomWidth?: number | `$border.${string}`;
+    borderLeftWidth?: number | `$border.${string}`;
+    borderColor?: Color;
+    borderStyle?: `solid` | `dashed` | `dotted`;
+    borderRadius?: Len;
+    borderTopLeftRadius?: Len;
+    borderTopRightRadius?: Len;
+    borderBottomRightRadius?: Len;
+    borderBottomLeftRadius?: Len;
+    opacity?: number | `$opacity.${string}`;
+    boxShadow?: `$shadow.${string}`;
+    fontSize?: Len;
+    fontWeight?: 300 | 400 | 500 | 600 | 700 | 800;
+    lineHeight?: Len;
+    letterSpacing?: Len;
+    textAlign?: `left` | `right` | `center` | `start` | `end` | `justify`;
+    textDecoration?: `none` | `underline` | `line-through`;
+    textTransform?: `none` | `uppercase` | `lowercase` | `capitalize`;
+    fontStyle?: `normal` | `italic`;
+    fontFamily?: `$type.family.${string}`;
+    transition?: `$motion.${string}`;
+    transitionEasing?: `$ease.${string}`;
+    /** `translate(Xpx, Ypx) scale(N) rotate(Ndeg)`, paint-only. */
+    transform?: string;
+    visibility?: `visible` | `hidden`;
+    pointerEvents?: `auto` | `none`;
+    userSelect?: `auto` | `none` | `text`;
+    cursor?: `auto` | `default` | `pointer` | `text` | `not-allowed` | `grab` | `grabbing` | `move` | `col-resize` | `row-resize`;
+    /** Round 2: `$blur.<name>`; blurs what is behind the box. */
+    backdropBlur?: `$blur.${string}`;
+    /** Round 2: a keyframe set (style.json `animations`). */
+    animation?: `pulse` | `spin` | `fade-in` | `slide-in-up` | `slide-in-down` | `slide-in-left` | `slide-in-right` | `shimmer`;
+    /** Round 2: `$motion.<name>` instead of the animation's own token. */
+    animationDuration?: `$motion.${string}`;
+}
+export type MediaKey = `@media (${string})`;
+export type StateKey = `:hover` | `:focus-visible` | `:pressed`;
+/** A style = base props + media condition blocks + state blocks, one level. */
+export type Style = StyleProps & {
+    [K in MediaKey]?: StyleProps;
+} & {
+    [K in StateKey]?: StyleProps;
+};
+export interface StyleIssue {
+    path: string;
+    message: string;
+}
+/** The enum a style key takes (`borderStyle` → solid|dashed|dotted), if any. */
+export declare function styleKeyEnum(key: string): readonly (string | number)[] | undefined;
+/** The value type a style key takes (`length`, `color`, `token`, …). */
+export declare function styleKeyType(key: string): string | undefined;
+/** A `@media` or state condition key. */
+export declare function isConditionKey(key: string): boolean;
+/** Every rule the client resolver relies on: whitelisted keys, well-typed
+ *  values, conditions one level deep (round 2: `direction` on any node). */
+export declare function validateStyle(style: unknown, options?: {
+    path?: string;
+    root?: boolean;
+}): StyleIssue[];
+/** Identity + validation, frozen so a render cannot mutate a shared style.
+ *  `Record<K, Style>` (not a generic) keeps the excess-property check on the
+ *  literal, so an unknown key is a compile error too. */
+export declare function create<K extends string>(styles: Record<K, Style>): Readonly<Record<K, Style>>;
+type Falsy = false | null | undefined | 0 | ``;
+/** Merge in order (last wins, StyleX semantics). Condition blocks merge KEY
+ *  BY KEY with the same rule, and stay nested: the output is exactly what the
+ *  wire carries (plain JSON) and what the client resolver reads. */
+export declare function props(...styles: ReadonlyArray<Style | Falsy | ReadonlyArray<Style | Falsy>>): Style;
+/** What a client knows when it flattens a style: the SURFACE box, the
+ *  platform's pointer and motion preference, the node's interaction states
+ *  and the theme's breakpoint values (px). */
+export interface ConditionContext {
+    width: number;
+    height?: number;
+    /** A hover-capable pointer (mouse, trackpad); false on touch. */
+    hover?: boolean;
+    /** The platform asks for reduced motion. */
+    reducedMotion?: boolean;
+    /** The node's active states, as the state keys without the colon
+     *  (`hover`, `focus-visible`, `pressed`). */
+    states?: readonly string[];
+    /** `$breakpoint.<name>` → px; a block naming an unknown token never matches. */
+    breakpoints?: Record<string, number>;
+}
+export interface MediaCondition {
+    feature: `min-width` | `max-width` | `min-height` | `max-height` | `orientation` | `hover` | `prefers-reduced-motion`;
+    /** The px value or the `$breakpoint.<name>` token for the size features;
+     *  the keyword for the others. */
+    value: string;
+}
+/** `"@media (min-width: $breakpoint.md)"` → `{feature, value}`; null when the
+ *  key is not a media condition of the grammar. */
+export declare function parseMediaCondition(key: string): MediaCondition | null;
+/** Does a media condition hold for the context? `min-*` = size >= N,
+ *  `max-*` = size < N, orientation portrait = height >= width (landscape
+ *  when the height is unknown). */
+export declare function mediaMatches(condition: MediaCondition, ctx: ConditionContext): boolean;
+/** Flatten a style for one pass: the base keys, then every matching `@media`
+ *  block in source order, then the matching state blocks in STYLE_STATES
+ *  order. Token values pass through untouched (the theme resolves them). */
+export declare function resolveConditions(style: Record<string, unknown>, ctx: ConditionContext): Record<string, unknown>;
+/** The breakpoint a surface of this width is in: the LAST `$breakpoint`
+ *  name (tokens.json order, ascending) whose px is <= width; null below the
+ *  first (= `base`). A native's responsive prop takes
+ *  `responsiveAt(value, activeBreakpoint(width, theme.tokens.breakpoint))`. */
+export declare function activeBreakpoint(width: number, breakpoints: Record<string, number>): string | null;
+export {};

package/dist/types/src/test-preload.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/src/text-shimmer.d.ts

@@ -0,0 +1,24 @@
+export declare const TEXT_SHIMMER: {
+    $comment: string;
+    durationMs: number;
+    angleDeg: number;
+    spreadPx: number;
+    highlightLightnessMin: number;
+    highlightLightnessBoost: number;
+    highlightAlphaBoost: number;
+    lightAlphaFactor: number;
+};
+export interface TextShimmer {
+    /** The text colour (`#rrggbb[aa]`). */
+    base: string;
+    /** The band's centre. */
+    highlight: string;
+    /** The 50% OKLab mix at ± spread/2. */
+    mid: string;
+    durationMs: number;
+    angleDeg: number;
+    spreadPx: number;
+}
+/** The shimmer colours for a text colour (`#rrggbb[aa]`); `dark` = the
+ *  surface's dark mode. An unparsable colour shimmers from black. */
+export declare function textShimmer(color: string, dark: boolean): TextShimmer;

package/dist/types/src/theme-types.d.ts

@@ -0,0 +1,162 @@
+/** `#rrggbb` or `#rrggbbaa`, lowercase. The only colour form a theme carries
+ *  (the builder converts oklch/hsl/rgb on import, `src/color.ts`). */
+export type HexColor = `#${string}`;
+export interface Shadow {
+    x: number;
+    y: number;
+    blur: number;
+    spread: number;
+    color: HexColor;
+}
+/** `cubic-bezier(x1, y1, x2, y2)` control points, P0 = (0,0) and P3 = (1,1)
+ *  implicit — the one form web, Compose, SwiftUI and gpui all accept. */
+export type Easing = [number, number, number, number];
+/** The per-mode values: colours and shadows (shadows differ in the dark). */
+export interface ThemeMode {
+    color: Record<string, HexColor>;
+    shadow: Record<string, Shadow[]>;
+}
+export type ModeName = `light` | `dark`;
+/** What a host asks for: a mode, or `system` = the platform's preference. */
+export type ModeSetting = ModeName | `system`;
+/** The surface density; `default` = the tokens as written. */
+export type Density = `compact` | `default` | `comfortable`;
+export interface ThemeTokens {
+    spacing: Record<string, number>;
+    radius: Record<string, number>;
+    type: {
+        size: Record<string, number>;
+        lineHeight: Record<string, number>;
+        weight: Record<string, number>;
+        /** Family NAMES (`Inter`); `fonts` describes how the host registers them. */
+        family: Record<string, string>;
+    };
+    control: Record<string, number>;
+    shadow?: never;
+    opacity: Record<string, number>;
+    border: Record<string, number>;
+    /** Milliseconds. */
+    motion: Record<string, number>;
+    /** Surface widths in px the style conditions may name (`$breakpoint.md`). */
+    breakpoint: Record<string, number>;
+    ease: Record<string, Easing>;
+    /** Multipliers over `control` and `spacing` for the non-default densities. */
+    density: Record<string, number>;
+    /** Round 2: backdrop blur radii in px (`backdropBlur: $blur.md`). */
+    blur: Record<string, number>;
+    /** EXP-1259: the motion scale multipliers painters read (`press`, `popoverFrom`). */
+    scale: Record<string, number>;
+}
+/** How a host registers a family the theme names: the files are the host's
+ *  (per platform); the theme only says what to fall back to. */
+export interface FontSpec {
+    fallback?: string;
+    weights?: number[];
+    /** `system` = the platform's own family of that kind, nothing to load. */
+    source?: `system` | `host`;
+}
+/** The values a recipe style may set (catalog/recipes.json `keys`): the
+ *  whitelisted subset of the Box visual keys, token references allowed. */
+export interface RecipeStyle {
+    backgroundColor?: string;
+    color?: string;
+    borderColor?: string;
+    borderWidth?: number | string;
+    borderTopWidth?: number | string;
+    borderRightWidth?: number | string;
+    borderBottomWidth?: number | string;
+    borderLeftWidth?: number | string;
+    borderRadius?: number | string;
+    borderStyle?: string;
+    padding?: number | string;
+    paddingHorizontal?: number | string;
+    paddingVertical?: number | string;
+    gap?: number | string;
+    width?: number | string;
+    height?: number | string;
+    minWidth?: number | string;
+    minHeight?: number | string;
+    fontSize?: number | string;
+    fontWeight?: number | string;
+    lineHeight?: number | string;
+    fontFamily?: string;
+    letterSpacing?: number;
+    textDecoration?: string;
+    textTransform?: string;
+    fontStyle?: string;
+    boxShadow?: string;
+    opacity?: number | string;
+    /** `$motion.<name>`: the duration this part's changes animate with. */
+    transition?: string;
+    /** `$ease.<name>`. */
+    transitionEasing?: string;
+    /** `translate(…) scale(…) rotate(…)`, paint-only. */
+    transform?: string;
+    /** Round 2: `$blur.<name>`: blur what is behind the part. */
+    backdropBlur?: string;
+    /** Round 2: a keyframe set of catalog/style.json `animations`. */
+    animation?: string;
+    /** The painter may use the platform's own control for this part. */
+    native?: boolean;
+}
+export type RecipeWhenValue = string | number | boolean | (string | number | boolean)[];
+/** One rule: applies when every `when` entry matches (`state` = every listed
+ *  state is active; any other key = the recipe prop equals the value or is
+ *  in the list). Rules merge by specificity, ties in order, later wins; a
+ *  child theme's rules come after its parent's. No `when` = the part's base. */
+export interface RecipeRule {
+    when?: Record<string, RecipeWhenValue>;
+    style: RecipeStyle;
+}
+/** Component → part → rules. */
+export type ThemeRecipes = Record<string, Record<string, RecipeRule[]>>;
+/** The theme FILE. With `extends`, every section is optional and overrides
+ *  the parent's; without it, every token name needs a value. */
+export interface ThemeSource {
+    /** Required: `THEME_SCHEMA_ID` (round 4: a loader refuses any other). */
+    $schema: string;
+    $comment?: string;
+    id: string;
+    name: string;
+    extends?: string;
+    modes?: Partial<Record<ModeName, Partial<ThemeMode>>>;
+    /** Round 1: PARTIAL colour/shadow overlays a renderer applies over the
+     *  mode when the platform asks for high contrast (`applyContrast`). */
+    contrast?: Partial<Record<ModeName, Partial<ThemeMode>>>;
+    tokens?: Partial<Omit<ThemeTokens, `type`>> & {
+        type?: Partial<ThemeTokens[`type`]>;
+    };
+    fonts?: Record<string, FontSpec>;
+    recipes?: ThemeRecipes;
+}
+/** What a painter receives: complete, flat, `extends` gone. Recipes keep
+ *  their token references (colours depend on the mode); `resolveRecipe`
+ *  turns a part's rules into concrete values for one mode. */
+export interface ResolvedTheme {
+    id: string;
+    name: string;
+    /** The chain this theme was built from, root first. */
+    chain: string[];
+    modes: Record<ModeName, ThemeMode>;
+    /** The high-contrast overlays per mode (partial tables, may be empty). */
+    contrast: Record<ModeName, ThemeMode>;
+    tokens: ThemeTokens;
+    fonts: Record<string, FontSpec>;
+    recipes: ThemeRecipes;
+}
+/** The question a painter asks: which part of which component, with which
+ *  recipe props and which interaction states. */
+export interface RecipeQuery {
+    component: string;
+    part: string;
+    props?: Record<string, unknown>;
+    states?: readonly string[];
+}
+/** A recipe's concrete values for one mode: colours as hex, lengths as
+ *  numbers, shadows as lists, families as names, easings as 4 numbers. */
+export type ResolvedValue = number | string | boolean | Shadow[] | Easing;
+export type ResolvedStyle = Record<string, ResolvedValue>;
+export interface ThemeIssue {
+    path: string;
+    message: string;
+}

package/dist/types/src/theme.d.ts

@@ -0,0 +1,73 @@
+import type { ExtensionDef, UiNode } from "./types.js";
+import type { Density, Easing, ModeName, ModeSetting, RecipeQuery, RecipeRule, RecipeStyle, ResolvedStyle, ResolvedTheme, ResolvedValue, Shadow, ThemeIssue, ThemeMode, ThemeRecipes, ThemeSource, ThemeTokens } from "./theme-types.js";
+export declare const MODES: readonly ModeName[];
+export declare const DENSITIES: readonly Density[];
+export declare const THEME_SCHEMA_ID = "https://ui.exponential.at/schemas/theme/v1.json";
+export declare function isFontText(value: unknown): value is string;
+export declare class ThemeError extends Error {
+    readonly issues: ThemeIssue[];
+    constructor(id: string, issues: ThemeIssue[]);
+}
+export interface ThemeOptions {
+    /** Themes an `extends` may name (sources or already resolved). */
+    themes?: readonly (ThemeSource | ResolvedTheme)[];
+    extensions?: readonly ExtensionDef[];
+}
+/** Every problem in ONE theme file, each with a path and a readable
+ *  message. Never throws: a non-object is one issue. */
+export declare function validateTheme(source: unknown, options?: ThemeOptions): ThemeIssue[];
+/** Validate + flatten, returning issues instead of throwing. */
+export declare function tryLoadTheme(source: unknown, options?: ThemeOptions): {
+    theme: ResolvedTheme | null;
+    issues: ThemeIssue[];
+};
+/** A theme file → the flat theme a painter uses. Throws `ThemeError` with
+ *  every issue listed, never anything else. */
+export declare function loadTheme(source: unknown, options?: ThemeOptions): ResolvedTheme;
+/** `system` → what the platform prefers; a mode stays itself. */
+export declare function resolveMode(setting: ModeSetting, systemPrefersDark: boolean): ModeName;
+/** The theme a surface of this density runs with: `control` and `spacing`
+ *  scaled by the theme's `$density.<name>` multiplier and rounded to whole
+ *  px; `default` returns the theme itself. Done once per surface, so every
+ *  resolver and fixture stays density-agnostic. */
+export declare function applyDensity(theme: ResolvedTheme, density: Density): ResolvedTheme;
+/** The theme with its high-contrast overlays merged into the modes (the
+ *  platform asked for more contrast). A theme without overlays is unchanged. */
+export declare function applyContrast(theme: ResolvedTheme): ResolvedTheme;
+/** `$color.primary` in `dark` → `#e5e5e5`; `$spacing.md` → 12; `$shadow.sm`
+ *  → the layers; `$type.family.sans` → `Inter`; `$ease.standard` → the four
+ *  control points. Undefined when not a token. */
+export declare function resolveToken(theme: ResolvedTheme, ref: unknown, mode: ModeName): ResolvedValue | undefined;
+/** A media key with its `$breakpoint.<name>` replaced by the theme's px. */
+export declare function resolveConditionKey(theme: ResolvedTheme, key: string): string;
+/** Every token reference in a style object replaced by its value for the
+ *  mode (nested condition blocks, gradients and arrays included, and the
+ *  `$breakpoint` tokens inside media keys); other values pass through. */
+export declare function resolveStyleValues<T extends Record<string, unknown>>(theme: ResolvedTheme, style: T, mode: ModeName): T;
+/** How specific a rule is: one point per `when` condition (a `state` list
+ *  counts each state). VAPP-90: rules merge in SPECIFICITY order, like the
+ *  CSS the web renderer compiles them to — a base rule (no `when`) never
+ *  shadows a `checked`/`focus`/`variant` rule that sits before it, which is
+ *  what a child theme's appended base override used to do under plain
+ *  source order. Ties keep source order (later wins). */
+export declare function ruleSpecificity(rule: RecipeRule): number;
+/** The matching rules' styles merged by specificity (token refs kept). */
+export declare function recipeStyle(theme: ResolvedTheme, query: RecipeQuery): RecipeStyle;
+/** A part's concrete visuals for one mode: the fixture
+ *  `theme-recipes.json` locks this per theme × component. */
+export declare function resolveRecipe(theme: ResolvedTheme, query: RecipeQuery, mode: ModeName): ResolvedStyle;
+/** The recipe query a NORMALIZED node answers to: its macro part, or the
+ *  native's root with its own recipe props. */
+export declare function nodeRecipeQuery(node: UiNode, extensions?: readonly ExtensionDef[]): RecipeQuery;
+/** What a painter paints a node with: native recipe < node style < macro
+ *  part recipe, token references resolved, condition blocks kept nested
+ *  (the client resolves `@media` and the state keys itself). */
+export declare function resolveNodeStyle(theme: ResolvedTheme, node: UiNode, mode: ModeName, states?: readonly string[], extensions?: readonly ExtensionDef[]): ResolvedStyle;
+/** The shadow layers as one CSS `box-shadow` string (for web painters). */
+export declare function shadowCss(layers: Shadow[]): string;
+/** An easing as CSS `cubic-bezier(…)`. */
+export declare function easingCss(curve: Easing): string;
+/** The parts of the theme a mode-less consumer may list (the builder). */
+export declare function themeTokens(theme: ResolvedTheme): ThemeTokens;
+export declare function themeMode(theme: ResolvedTheme, mode: ModeName): ThemeMode;
+export type { ThemeRecipes };

package/dist/types/src/themes.d.ts

@@ -0,0 +1,22 @@
+import type { ResolvedTheme, ThemeIssue, ThemeSource } from "./theme-types.js";
+export declare const neutralTheme: ThemeSource;
+export declare const exponentialTheme: ThemeSource;
+export declare const playfulTheme: ThemeSource;
+export declare const orangeTheme: ThemeSource;
+/** Source order = resolution order: a built-in may only extend one before it. */
+export declare const BUILTIN_THEMES: readonly ThemeSource[];
+export declare const BUILTIN_THEME_IDS: readonly string[];
+export declare const DEFAULT_THEME_ID = "exponential";
+/** A built-in, resolved once per process. */
+export declare function builtinTheme(id: string): ResolvedTheme;
+/** Round 4 (VAPP-103): the theme a host paints with, NEVER a throw: a
+ *  built-in id or a theme file over the built-ins; anything unusable (an
+ *  unknown id, a bad `$schema`, an unknown token, a missing value) falls back
+ *  to the default theme with the issues saying why (Rust
+ *  `themes::theme_or_default`, Swift/Kotlin `ThemeHandle.loadOrDefault`). */
+export declare function themeOrDefault(input: unknown): {
+    theme: ResolvedTheme;
+    issues: ThemeIssue[];
+};
+/** Every built-in resolved, in source order. */
+export declare function builtinThemes(): ResolvedTheme[];