# Theme override runtime

This directory implements the package-owned `ThemeOverride` contract. The public schema remains
`1.0.0`.

## Contract

An override requires exact metadata:

```json
{
  "$extensions": {
    "com.forge.ui.themeOverride": {
      "schemaVersion": "1.0.0"
    }
  }
}
```

The optional intent sections are:

- `inputs`: high-level seeds such as brand color and display font.
- `selections`: curated references expanded through package recipes.
- `overrides`: direct primitive or semantic token values.

Unknown additive fields are preserved with warnings. Unsafe prototypes, unsupported versions,
legacy mode buckets, invalid targets, and invalid values are rejected.

## Expansion

The generated artifact embeds the base token expressions. Runtime expansion does not load or walk
the source token JSON.

Precedence is:

1. generated baseline
2. generated input values
3. selection recipes
4. direct overrides

The result contains:

- a complete concrete `resolved` state for light and dark modes;
- sparse `writes` containing only requested changes;
- provenance for resolved values and writes;
- diagnostics and a deterministic artifact revision.

Metadata-only overrides resolve the baseline and produce no writes.

## Generated artifact

`runtime/override-artifacts.json` contains:

- base expressions and concrete primitive values;
- target metadata;
- executable input, source-set, selection, and recipe catalogs;
- rule definitions;
- runtime display-font face maps;
- the public display-font catalog;
- the expansion algorithm version;
- component hashes and the aggregate revision.

The artifact has no runtime format gate. Its shape is private and regenerated in lockstep with the
package.

## Files

- `contracts.ts` — public and internal TypeScript contracts.
- `parser.ts` — exact metadata and intent parsing with unknown-field preservation.
- `expand.ts` — baseline resolution and override precedence.
- `recipeEngine.ts` — selection recipe execution.
- `artifacts.ts` — generated artifact bindings and catalog queries.
- `catalogDefinitions.ts` — authored inputs, source sets, selections, and recipes.
- `ruleDefinitions.ts` / `ruleEvaluation.ts` — package validation rules.
- `diagnostics.ts` — stable diagnostic registry.

## Adapters and sessions

Expansion is platform-aware but target-agnostic. Adapters convert concrete token writes to Uniwind
CSS variable maps or MUI theme options.

Covering sessions retain the nonshrinking set of keys written by one editor-owned writer. Clearing
intent writes baseline values back for covered keys while leaving unrelated keys untouched.