@theme-registry/refract 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,191 @@
+# @theme-registry/refract
+
+[![CI](https://github.com/theme-registry/refract/actions/workflows/ci.yml/badge.svg)](https://github.com/theme-registry/refract/actions/workflows/ci.yml)
+
+A framework-agnostic design-token toolkit. You author one **raw theme**; refract
+compiles it into a single, format-neutral **Model** and lowers that Model to whatever
+output you need through an **adapter** — CSS custom properties, styled-components,
+SCSS `$variables`, or plain JSON. One source of truth, many targets.
+
+```
+raw theme ──▶ Model (format-neutral) ──▶ adapter ──▶ CSS │ styled-components │ SCSS │ JSON
+```
+
+> **Status: `0.x` (pinned).** Published on npm as `@theme-registry/refract`. Pin exact versions
+> through `0.x`. **Docs, live playground & API reference:** <https://theme-registry.github.io/refract/>
+
+## Stability
+
+| Surface | Package | Tier |
+| --- | --- | --- |
+| Core + CLI (incl. DTCG interop at `/dtcg`) | `@theme-registry/refract` | **Stable** |
+| CSS adapter | `@theme-registry/refract-css` | **Stable** |
+| styled-components adapter | `@theme-registry/refract-styled-components` | **Stable** |
+| MCP server (agent query surface) | `@theme-registry/refract-mcp` | **Stable** |
+| SCSS adapter | `@theme-registry/refract-scss` | Experimental |
+| JSON adapter | `@theme-registry/refract-json` | Experimental |
+
+**Stable** — breaking changes are deliberate, announced events. **Experimental** — the shape may
+still change; these adapters are reachable via the npm `experimental` dist-tag.
+
+## Versioning
+
+All packages share **one lockstep version** through the `0.x` line (a Changesets `fixed` group) and
+publish together. Tiers are signalled by npm dist-tag, not by divergent versions. **Pin exact
+versions** until `1.0`, when the group splits into independent lines. Details: **[RELEASING.md](RELEASING.md)**.
+
+**Token paths are stable identifiers.** A token path (`colors.brand.dark`) is treated as public API —
+it won't change or disappear within a minor/patch release, so agents, the `guide` manifest (`schema`-
+versioned), and DTCG round-trips can bind to it. Removals/renames are breaking (major) changes.
+
+## Install
+
+```bash
+npm install @theme-registry/refract
+```
+
+`styled-components` and `typescript` are **optional** peers — only needed if you use the
+styled-components adapter or the `.ts` build config, respectively.
+
+## Quick start
+
+`createTheme(raw, { adapter })` builds the theme. The `adapter` is **required** — core
+ships no default, which is what keeps it format-neutral.
+
+```ts
+import { createTheme } from "@theme-registry/refract";
+import { createCssAdapter } from "@theme-registry/refract-css"; // adapters are separate packages
+
+const theme = createTheme(
+  {
+    breakpoints: { sm: 576, md: 768, lg: 1024 },
+    colors: {
+      brand: { base: "#4c6ef5", text: "#ffffff" },   // → brand, brand.text, brand.light/dark/…
+      recipes: {
+        solid: { brand: { background: "brand", color: "brand.text" } },
+      },
+    },
+  },
+  { adapter: createCssAdapter() },
+);
+
+theme.css;                       // the full stylesheet (:root vars + .classes)
+theme.tokens["colors.brand"];    // { ref?: string, value?: … } — the flat token map
+theme.resolveToken("colors.brand.dark"); // "#3d58c4" — derived step (follows aliases + runs derivations)
+theme.classes;                   // recipe → className map
+```
+
+Swap the adapter, keep the raw theme:
+
+```ts
+import { createScssAdapter } from "@theme-registry/refract-scss"; // each adapter is its own package
+const scss = createTheme(raw, { adapter: createScssAdapter() }); // scss.scss → $variables + classes
+```
+
+## Authoring the raw theme
+
+The raw theme is the file you live in. It is one key per **subsystem**, each with
+properties and an optional nested `recipes` block:
+
+```ts
+import type { RawTheme } from "@theme-registry/refract/build";
+
+const raw = {
+  breakpoints: { sm: 576, md: 768, lg: 1024 },
+
+  colors:     { /* palettes: hex | { base, text, variants, steps, responsive } + recipes */ },
+  typography: { /* fontFamily/Size/Weight/lineHeight/… (modular scale) + recipes */ },
+  effects:    { /* radius/shadow/transitions/opacity/zIndex/blur/… + recipes */ },
+  layout:     { /* spacing/gutters + columns/grids/stacks/container + recipes */ },
+  components: { /* composition-only: recipes that reference other subsystems' recipes */ },
+} satisfies RawTheme;
+```
+
+Property values can be **literals** (`"#4c6ef5"`, `16`), **references** to other tokens
+(`color: "brand.text"`), and carry **responsive / variant / target** overrides keyed on
+your breakpoints. Recipes group reusable rule-sets with **states** (`hover`, `disabled`, …).
+Full field-by-field walkthrough: **[docs/authoring.md](https://github.com/theme-registry/refract/blob/main/docs/authoring.md)**.
+
+## Adapters — the multi-format thesis
+
+Every adapter consumes the same Model and decides how to realize it. Four ship in-box:
+
+Core ships **zero** adapters; each is its own installable package (`npm i @theme-registry/refract-<name>`).
+
+| Adapter | Package | Output | Notes |
+| --- | --- | --- | --- |
+| **CSS** | `@theme-registry/refract-css` | `:root` custom properties + classes | the batteries-included default |
+| **styled-components** | `@theme-registry/refract-styled-components` | `css` blocks + `createGlobalStyle` + `theme.media` | needs the `styled-components` peer |
+| **SCSS** | `@theme-registry/refract-scss` | compile-time `$variables` + classes from Sass | `TUnit = string`, a genuinely distinct format |
+| **JSON** | `@theme-registry/refract-json` | the full Model as address-keyed data | `TUnit = object` — proves the contract is format-generic |
+
+Write your own with `defineAdapter(spec)` — you fill four primitives (`recipeName`,
+`renderRecipe`, `renderVariables`, `join`) and core supplies the rest. See
+**[docs/extending.md](https://github.com/theme-registry/refract/blob/main/docs/extending.md)** or run the `adapter-scaffold` skill.
+
+## Build to disk (CLI)
+
+```bash
+npx refract init      # scaffold a theme.config.(ts|js|mjs)
+npx refract build     # load the config → write every target's files to its outDir
+npx refract tokens    # export theme.tokens as a DTCG tokens.json (adapter-free)
+```
+
+`theme.config.ts` is your code — it imports the adapters (and the raw theme) it wants:
+
+```ts
+import { defineConfig } from "@theme-registry/refract/build";
+import { createCssAdapter } from "@theme-registry/refract-css";
+import { raw } from "./theme.raw"; // a native, RawTheme-typed sibling .ts (graph-compiled)
+
+export default defineConfig({
+  raw,
+  targets: [
+    { name: "css", adapter: createCssAdapter(), outDir: "dist/theme" },
+    { name: "split", adapter: createCssAdapter(), outDir: "dist/split", emit: { type: "split" } },
+  ],
+});
+```
+
+### `emit` — how output is written
+
+Each target's `emit` picks the output shape (CSS adapter):
+
+| Mode | Result |
+| --- | --- |
+| `single` (default) | one `theme.css` — all `:root` vars + all rules |
+| `split` | `styles.css` + `variables.css` (load-order contract, no `@import`) |
+| `subsystem` | a styles+variables pair per subsystem (`colors.css`, `colors.variables.css`, …) |
+| `components` | each component variant flattened into one self-contained file (`inline: true` bakes values; `inline: false` emits `var(--…)` + a tree-shaken `variables.css`) |
+
+## DTCG round-trip
+
+The `./dtcg` subpath reads/writes the W3C Design Token Community Group `tokens.json`
+format, so a theme round-trips through Figma / Style Dictionary / other DTCG tooling.
+It is data-interchange, **not** an output adapter — property tokens only.
+
+```ts
+import { fromDTCG, toDTCG } from "@theme-registry/refract/dtcg";
+
+const raw   = fromDTCG(designTokensJson);        // DTCG document → createTheme raw input
+const doc   = toDTCG(theme);                     // built theme's tokens → DTCG document
+```
+
+## Package entry points
+
+| Subpath | Contents |
+| --- | --- |
+| `@theme-registry/refract` | `createTheme`, `createCssAdapter`, `createStyledComponentsAdapter`, `defineAdapter`, the Model/adapter types, subsystem descriptors |
+| `…/css` · `…/styled-components` · `…/json` · `…/scss` | each adapter's factory + types, as its own bundle |
+| `…/dtcg` | `fromDTCG` / `toDTCG` / `parseDTCGDocument` (pure, no runtime adapter graph) |
+| `…/build` | `defineConfig`, `emitTheme`, the `RawTheme` authoring types, the `Emit` vocabulary (Node-only) |
+
+## Documentation
+
+- **[docs/authoring.md](https://github.com/theme-registry/refract/blob/main/docs/authoring.md)** — author a theme + consume its output (the user guide).
+- **[docs/extending.md](https://github.com/theme-registry/refract/blob/main/docs/extending.md)** — write a subsystem or an adapter against the frozen contract.
+- **[AGENTS.md](AGENTS.md)** — orientation for AI coding agents.
+
+## License
+
+MIT © Petyo Stoyanov

package/dist/_errors-be768b25.cjs.js.map

@@ -1 +1 @@
-{"version":3,"file":"_errors-be768b25.cjs.js","sources":["../src/core/errors.ts"],"sourcesContent":["/**\n * Stable, machine-readable error codes (§P2-3). Every error refract throws for a theme authoring /\n * build problem — everything reachable from {@link createTheme} (subsystem normalization, token\n * derivation, DTCG parsing) — is a {@link RefractError} carrying a `code` from {@link RefractErrorCode}:\n * a stable identifier an agent (or a catch block) can branch on without string-matching the human\n * message. The message text stays human-first and unchanged; the code is additive.\n *\n * Scope: authoring/build errors. Pure CLI-tooling failures in `src/build/*` (bad arguments, a missing\n * file, an unknown command) stay plain `Error`s — they're usage errors from `refract <cmd>`, not a\n * problem with the theme an agent is editing.\n *\n * Dependency-free leaf on purpose, so any module (including the standalone `adapter-kit`) can throw one\n * without pulling in the core graph.\n */\nexport type RefractErrorCode =\n  | \"REFRACT_E_COLOR_INPUT\" // a colour value wasn't a derivable colour\n  | \"REFRACT_E_COLOR_TUPLE\" // an [r,g,b] tuple was malformed\n  | \"REFRACT_E_STEPS\" // colors.<name>.steps out of range / non-numeric\n  | \"REFRACT_E_VARIANT\" // a derivation-spec variant / modifier chain was malformed\n  | \"REFRACT_E_VARIANT_REF\" // a variant referenced an unknown source\n  | \"REFRACT_E_CYCLE\" // a cyclic reference (colour variant, token, recipe, DTCG alias)\n  | \"REFRACT_E_ADJUST\" // an adjust dial was out of range\n  | \"REFRACT_E_HARMONY\" // an invalid harmony scheme\n  | \"REFRACT_E_VALIDATION\" // aggregate: one or more post-build ref-validation failures (see `failures`)\n  | \"REFRACT_E_RECIPE_PROPERTY\" // a recipe declaration key is neither a known CSS property nor a reserved key\n  | \"REFRACT_E_TOKEN_PATH\" // a token path is unknown / malformed / uses an unknown derivation fn\n  | \"REFRACT_E_BREAKPOINT\" // a responsive entry omitted or named an unknown breakpoint\n  | \"REFRACT_E_STATE\" // a recipe state entry named a state the adapter doesn't know\n  | \"REFRACT_E_CONTAINER\" // a container-query entry named an unknown container / size / unsupported axis\n  | \"REFRACT_E_RESPONSIVE\" // a responsive/mode override was malformed (variant+target conflict, unknown ref)\n  | \"REFRACT_E_MEDIA\" // an invalid media / container query range (min > max)\n  | \"REFRACT_E_MODE\" // an appearance-mode override with no base to override\n  | \"REFRACT_E_PRESET\" // an unknown globals preset name\n  | \"REFRACT_E_EFFECTS\" // a malformed effects value (shadow / transition layer)\n  | \"REFRACT_E_LAYOUT\" // a malformed layout scale (ratio+step, bad rung)\n  | \"REFRACT_E_UNITS\" // a malformed units config\n  | \"REFRACT_E_PROPERTY\" // a property couldn't be normalized (no resolvable base value)\n  | \"REFRACT_E_REFERENCE\" // a composition / rule-set reference didn't resolve\n  | \"REFRACT_E_NAMING\" // a naming override / default path produced a collision\n  | \"REFRACT_E_DTCG_VERSION\" // an unreadable DTCG refract-extension version\n  | \"REFRACT_E_AUDIT\"; // a strict contrast audit failed\n\n/**\n * An authoring / build error with a stable {@link RefractErrorCode}. For an aggregate (collect-all)\n * error, `failures` lists each individual message so a caller can report them all at once.\n */\nexport class RefractError extends Error {\n  readonly code: RefractErrorCode;\n  readonly failures?: readonly string[];\n\n  constructor(code: RefractErrorCode, message: string, failures?: readonly string[]) {\n    super(message);\n    this.name = \"RefractError\";\n    this.code = code;\n    if (failures) this.failures = failures;\n    // Keep `instanceof RefractError` working after transpilation to ES5-ish targets.\n    Object.setPrototypeOf(this, RefractError.prototype);\n  }\n}\n"],"names":["RefractError","Error","constructor","code","message","failures","super","this","name","Object","setPrototypeOf","prototype"],"mappings":"aA8CM,MAAOA,UAAqBC,MAIhC,WAAAC,CAAYC,EAAwBC,EAAiBC,GACnDC,MAAMF,GACNG,KAAKC,KAAO,eACZD,KAAKJ,KAAOA,EACRE,IAAUE,KAAKF,SAAWA,GAE9BI,OAAOC,eAAeH,KAAMP,EAAaW,UAC1C"}
+{"version":3,"file":"_errors-be768b25.cjs.js","sources":["../src/core/errors.ts"],"sourcesContent":["/**\n * Stable, machine-readable error codes (§P2-3). Every error refract throws for a theme authoring /\n * build problem — everything reachable from {@link createTheme} (subsystem normalization, token\n * derivation, DTCG parsing) — is a {@link RefractError} carrying a `code` from {@link RefractErrorCode}:\n * a stable identifier an agent (or a catch block) can branch on without string-matching the human\n * message. The message text stays human-first and unchanged; the code is additive.\n *\n * Scope: authoring/build errors. Pure CLI-tooling failures in `src/build/*` (bad arguments, a missing\n * file, an unknown command) stay plain `Error`s — they're usage errors from `refract <cmd>`, not a\n * problem with the theme an agent is editing. The one build-layer exception is `REFRACT_E_RAW_SHAPE`:\n * a value handed to `diff` / `validate` (or the MCP server) where a `RawTheme` is required but the\n * value isn't theme-shaped — that IS a theme problem, and a governance tool must fail loud + coded on\n * it (see {@link assertRawTheme}) rather than emit a nonsense \"everything removed\" diff at exit 0.\n *\n * Dependency-free leaf on purpose, so any module (including the standalone `adapter-kit`) can throw one\n * without pulling in the core graph.\n */\nexport type RefractErrorCode =\n  | \"REFRACT_E_COLOR_INPUT\" // a colour value wasn't a derivable colour\n  | \"REFRACT_E_COLOR_TUPLE\" // an [r,g,b] tuple was malformed\n  | \"REFRACT_E_STEPS\" // colors.<name>.steps out of range / non-numeric\n  | \"REFRACT_E_VARIANT\" // a derivation-spec variant / modifier chain was malformed\n  | \"REFRACT_E_VARIANT_REF\" // a variant referenced an unknown source\n  | \"REFRACT_E_CYCLE\" // a cyclic reference (colour variant, token, recipe, DTCG alias)\n  | \"REFRACT_E_ADJUST\" // an adjust dial was out of range\n  | \"REFRACT_E_HARMONY\" // an invalid harmony scheme\n  | \"REFRACT_E_VALIDATION\" // aggregate: one or more post-build ref-validation failures (see `failures`)\n  | \"REFRACT_E_RECIPE_PROPERTY\" // a recipe declaration key is neither a known CSS property nor a reserved key\n  | \"REFRACT_E_TOKEN_PATH\" // a token path is unknown / malformed / uses an unknown derivation fn\n  | \"REFRACT_E_BREAKPOINT\" // a responsive entry omitted or named an unknown breakpoint\n  | \"REFRACT_E_STATE\" // a recipe state entry named a state the adapter doesn't know\n  | \"REFRACT_E_CONTAINER\" // a container-query entry named an unknown container / size / unsupported axis\n  | \"REFRACT_E_RESPONSIVE\" // a responsive/mode override was malformed (variant+target conflict, unknown ref)\n  | \"REFRACT_E_MEDIA\" // an invalid media / container query range (min > max)\n  | \"REFRACT_E_MODE\" // an appearance-mode override with no base to override\n  | \"REFRACT_E_PRESET\" // an unknown globals preset name\n  | \"REFRACT_E_EFFECTS\" // a malformed effects value (shadow / transition layer)\n  | \"REFRACT_E_LAYOUT\" // a malformed layout scale (ratio+step, bad rung)\n  | \"REFRACT_E_UNITS\" // a malformed units config\n  | \"REFRACT_E_PROPERTY\" // a property couldn't be normalized (no resolvable base value)\n  | \"REFRACT_E_REFERENCE\" // a composition / rule-set reference didn't resolve\n  | \"REFRACT_E_NAMING\" // a naming override / default path produced a collision\n  | \"REFRACT_E_DTCG_VERSION\" // an unreadable DTCG refract-extension version\n  | \"REFRACT_E_AUDIT\" // a strict contrast audit failed\n  | \"REFRACT_E_RAW_SHAPE\"; // a value passed where a RawTheme is required isn't theme-shaped (e.g. a defineConfig, an array, null)\n\n/**\n * An authoring / build error with a stable {@link RefractErrorCode}. For an aggregate (collect-all)\n * error, `failures` lists each individual message so a caller can report them all at once.\n */\nexport class RefractError extends Error {\n  readonly code: RefractErrorCode;\n  readonly failures?: readonly string[];\n\n  constructor(code: RefractErrorCode, message: string, failures?: readonly string[]) {\n    super(message);\n    this.name = \"RefractError\";\n    this.code = code;\n    if (failures) this.failures = failures;\n    // Keep `instanceof RefractError` working after transpilation to ES5-ish targets.\n    Object.setPrototypeOf(this, RefractError.prototype);\n  }\n}\n"],"names":["RefractError","Error","constructor","code","message","failures","super","this","name","Object","setPrototypeOf","prototype"],"mappings":"aAkDM,MAAOA,UAAqBC,MAIhC,WAAAC,CAAYC,EAAwBC,EAAiBC,GACnDC,MAAMF,GACNG,KAAKC,KAAO,eACZD,KAAKJ,KAAOA,EACRE,IAAUE,KAAKF,SAAWA,GAE9BI,OAAOC,eAAeH,KAAMP,EAAaW,UAC1C"}

package/dist/_errors-d75a5c74.esm.js.map

@@ -1 +1 @@
-{"version":3,"file":"_errors-d75a5c74.esm.js","sources":["../src/core/errors.ts"],"sourcesContent":["/**\n * Stable, machine-readable error codes (§P2-3). Every error refract throws for a theme authoring /\n * build problem — everything reachable from {@link createTheme} (subsystem normalization, token\n * derivation, DTCG parsing) — is a {@link RefractError} carrying a `code` from {@link RefractErrorCode}:\n * a stable identifier an agent (or a catch block) can branch on without string-matching the human\n * message. The message text stays human-first and unchanged; the code is additive.\n *\n * Scope: authoring/build errors. Pure CLI-tooling failures in `src/build/*` (bad arguments, a missing\n * file, an unknown command) stay plain `Error`s — they're usage errors from `refract <cmd>`, not a\n * problem with the theme an agent is editing.\n *\n * Dependency-free leaf on purpose, so any module (including the standalone `adapter-kit`) can throw one\n * without pulling in the core graph.\n */\nexport type RefractErrorCode =\n  | \"REFRACT_E_COLOR_INPUT\" // a colour value wasn't a derivable colour\n  | \"REFRACT_E_COLOR_TUPLE\" // an [r,g,b] tuple was malformed\n  | \"REFRACT_E_STEPS\" // colors.<name>.steps out of range / non-numeric\n  | \"REFRACT_E_VARIANT\" // a derivation-spec variant / modifier chain was malformed\n  | \"REFRACT_E_VARIANT_REF\" // a variant referenced an unknown source\n  | \"REFRACT_E_CYCLE\" // a cyclic reference (colour variant, token, recipe, DTCG alias)\n  | \"REFRACT_E_ADJUST\" // an adjust dial was out of range\n  | \"REFRACT_E_HARMONY\" // an invalid harmony scheme\n  | \"REFRACT_E_VALIDATION\" // aggregate: one or more post-build ref-validation failures (see `failures`)\n  | \"REFRACT_E_RECIPE_PROPERTY\" // a recipe declaration key is neither a known CSS property nor a reserved key\n  | \"REFRACT_E_TOKEN_PATH\" // a token path is unknown / malformed / uses an unknown derivation fn\n  | \"REFRACT_E_BREAKPOINT\" // a responsive entry omitted or named an unknown breakpoint\n  | \"REFRACT_E_STATE\" // a recipe state entry named a state the adapter doesn't know\n  | \"REFRACT_E_CONTAINER\" // a container-query entry named an unknown container / size / unsupported axis\n  | \"REFRACT_E_RESPONSIVE\" // a responsive/mode override was malformed (variant+target conflict, unknown ref)\n  | \"REFRACT_E_MEDIA\" // an invalid media / container query range (min > max)\n  | \"REFRACT_E_MODE\" // an appearance-mode override with no base to override\n  | \"REFRACT_E_PRESET\" // an unknown globals preset name\n  | \"REFRACT_E_EFFECTS\" // a malformed effects value (shadow / transition layer)\n  | \"REFRACT_E_LAYOUT\" // a malformed layout scale (ratio+step, bad rung)\n  | \"REFRACT_E_UNITS\" // a malformed units config\n  | \"REFRACT_E_PROPERTY\" // a property couldn't be normalized (no resolvable base value)\n  | \"REFRACT_E_REFERENCE\" // a composition / rule-set reference didn't resolve\n  | \"REFRACT_E_NAMING\" // a naming override / default path produced a collision\n  | \"REFRACT_E_DTCG_VERSION\" // an unreadable DTCG refract-extension version\n  | \"REFRACT_E_AUDIT\"; // a strict contrast audit failed\n\n/**\n * An authoring / build error with a stable {@link RefractErrorCode}. For an aggregate (collect-all)\n * error, `failures` lists each individual message so a caller can report them all at once.\n */\nexport class RefractError extends Error {\n  readonly code: RefractErrorCode;\n  readonly failures?: readonly string[];\n\n  constructor(code: RefractErrorCode, message: string, failures?: readonly string[]) {\n    super(message);\n    this.name = \"RefractError\";\n    this.code = code;\n    if (failures) this.failures = failures;\n    // Keep `instanceof RefractError` working after transpilation to ES5-ish targets.\n    Object.setPrototypeOf(this, RefractError.prototype);\n  }\n}\n"],"names":["RefractError","Error","constructor","code","message","failures","super","this","name","Object","setPrototypeOf","prototype"],"mappings":"AA8CM,MAAOA,UAAqBC,MAIhC,WAAAC,CAAYC,EAAwBC,EAAiBC,GACnDC,MAAMF,GACNG,KAAKC,KAAO,eACZD,KAAKJ,KAAOA,EACRE,IAAUE,KAAKF,SAAWA,GAE9BI,OAAOC,eAAeH,KAAMP,EAAaW,UAC1C"}
+{"version":3,"file":"_errors-d75a5c74.esm.js","sources":["../src/core/errors.ts"],"sourcesContent":["/**\n * Stable, machine-readable error codes (§P2-3). Every error refract throws for a theme authoring /\n * build problem — everything reachable from {@link createTheme} (subsystem normalization, token\n * derivation, DTCG parsing) — is a {@link RefractError} carrying a `code` from {@link RefractErrorCode}:\n * a stable identifier an agent (or a catch block) can branch on without string-matching the human\n * message. The message text stays human-first and unchanged; the code is additive.\n *\n * Scope: authoring/build errors. Pure CLI-tooling failures in `src/build/*` (bad arguments, a missing\n * file, an unknown command) stay plain `Error`s — they're usage errors from `refract <cmd>`, not a\n * problem with the theme an agent is editing. The one build-layer exception is `REFRACT_E_RAW_SHAPE`:\n * a value handed to `diff` / `validate` (or the MCP server) where a `RawTheme` is required but the\n * value isn't theme-shaped — that IS a theme problem, and a governance tool must fail loud + coded on\n * it (see {@link assertRawTheme}) rather than emit a nonsense \"everything removed\" diff at exit 0.\n *\n * Dependency-free leaf on purpose, so any module (including the standalone `adapter-kit`) can throw one\n * without pulling in the core graph.\n */\nexport type RefractErrorCode =\n  | \"REFRACT_E_COLOR_INPUT\" // a colour value wasn't a derivable colour\n  | \"REFRACT_E_COLOR_TUPLE\" // an [r,g,b] tuple was malformed\n  | \"REFRACT_E_STEPS\" // colors.<name>.steps out of range / non-numeric\n  | \"REFRACT_E_VARIANT\" // a derivation-spec variant / modifier chain was malformed\n  | \"REFRACT_E_VARIANT_REF\" // a variant referenced an unknown source\n  | \"REFRACT_E_CYCLE\" // a cyclic reference (colour variant, token, recipe, DTCG alias)\n  | \"REFRACT_E_ADJUST\" // an adjust dial was out of range\n  | \"REFRACT_E_HARMONY\" // an invalid harmony scheme\n  | \"REFRACT_E_VALIDATION\" // aggregate: one or more post-build ref-validation failures (see `failures`)\n  | \"REFRACT_E_RECIPE_PROPERTY\" // a recipe declaration key is neither a known CSS property nor a reserved key\n  | \"REFRACT_E_TOKEN_PATH\" // a token path is unknown / malformed / uses an unknown derivation fn\n  | \"REFRACT_E_BREAKPOINT\" // a responsive entry omitted or named an unknown breakpoint\n  | \"REFRACT_E_STATE\" // a recipe state entry named a state the adapter doesn't know\n  | \"REFRACT_E_CONTAINER\" // a container-query entry named an unknown container / size / unsupported axis\n  | \"REFRACT_E_RESPONSIVE\" // a responsive/mode override was malformed (variant+target conflict, unknown ref)\n  | \"REFRACT_E_MEDIA\" // an invalid media / container query range (min > max)\n  | \"REFRACT_E_MODE\" // an appearance-mode override with no base to override\n  | \"REFRACT_E_PRESET\" // an unknown globals preset name\n  | \"REFRACT_E_EFFECTS\" // a malformed effects value (shadow / transition layer)\n  | \"REFRACT_E_LAYOUT\" // a malformed layout scale (ratio+step, bad rung)\n  | \"REFRACT_E_UNITS\" // a malformed units config\n  | \"REFRACT_E_PROPERTY\" // a property couldn't be normalized (no resolvable base value)\n  | \"REFRACT_E_REFERENCE\" // a composition / rule-set reference didn't resolve\n  | \"REFRACT_E_NAMING\" // a naming override / default path produced a collision\n  | \"REFRACT_E_DTCG_VERSION\" // an unreadable DTCG refract-extension version\n  | \"REFRACT_E_AUDIT\" // a strict contrast audit failed\n  | \"REFRACT_E_RAW_SHAPE\"; // a value passed where a RawTheme is required isn't theme-shaped (e.g. a defineConfig, an array, null)\n\n/**\n * An authoring / build error with a stable {@link RefractErrorCode}. For an aggregate (collect-all)\n * error, `failures` lists each individual message so a caller can report them all at once.\n */\nexport class RefractError extends Error {\n  readonly code: RefractErrorCode;\n  readonly failures?: readonly string[];\n\n  constructor(code: RefractErrorCode, message: string, failures?: readonly string[]) {\n    super(message);\n    this.name = \"RefractError\";\n    this.code = code;\n    if (failures) this.failures = failures;\n    // Keep `instanceof RefractError` working after transpilation to ES5-ish targets.\n    Object.setPrototypeOf(this, RefractError.prototype);\n  }\n}\n"],"names":["RefractError","Error","constructor","code","message","failures","super","this","name","Object","setPrototypeOf","prototype"],"mappings":"AAkDM,MAAOA,UAAqBC,MAIhC,WAAAC,CAAYC,EAAwBC,EAAiBC,GACnDC,MAAMF,GACNG,KAAKC,KAAO,eACZD,KAAKJ,KAAOA,EACRE,IAAUE,KAAKF,SAAWA,GAE9BI,OAAOC,eAAeH,KAAMP,EAAaW,UAC1C"}