@theme-registry/refract 0.1.0

package/dist/_errors-be768b25.cjs.js

@@ -0,0 +1,2 @@
+"use strict";class r extends Error{constructor(t,e,s){super(e),this.name="RefractError",this.code=t,s&&(this.failures=s),Object.setPrototypeOf(this,r.prototype)}}exports.RefractError=r;
+//# sourceMappingURL=_errors-be768b25.cjs.js.map

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

@@ -0,0 +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"}

package/dist/_errors-d75a5c74.esm.js

@@ -0,0 +1,2 @@
+class t extends Error{constructor(r,e,s){super(e),this.name="RefractError",this.code=r,s&&(this.failures=s),Object.setPrototypeOf(this,t.prototype)}}export{t as R};
+//# sourceMappingURL=_errors-d75a5c74.esm.js.map

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

@@ -0,0 +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"}

package/dist/adapter-kit.cjs.js

@@ -0,0 +1,2 @@
+"use strict";var e=require("./_errors-be768b25.cjs.js");const a=e=>e.trim().replace(/\s+/g,"-").replace(/[^a-zA-Z0-9-_]/g,"-").replace(/-+/g,"-").replace(/^-+/,"").replace(/-+$/,"").toLowerCase(),n=(e,n)=>`--${e}-${n.split(".").map(a).filter(Boolean).join("-")}`,r=(e,n,r,s)=>[e.classToken,n,r,s].map(a).filter(Boolean).join("-");exports.createNamer=(s,t)=>{const o=new Map,i=new Map,l=!!(null==t?void 0:t.variableName),c=!!(null==t?void 0:t.className),m=(a,n)=>{const r=o.get(a);if(void 0!==r&&r!==n)throw new e.RefractError("REFRACT_E_NAMING",l?`naming override: variable name "${a}" is produced by both "${r}" and "${n}" — variableName must map distinct token paths to distinct names`:`naming collision: token paths "${r}" and "${n}" both produce the variable name "${a}" — segment sanitization collapses spaces / punctuation to "-", so rename one so their sanitized names differ`);o.set(a,n)},d=(a,n)=>{const r=i.get(a);if(void 0!==r&&r!==n)throw new e.RefractError("REFRACT_E_NAMING",c?`naming override: class name "${a}" is produced by both "${r}" and "${n}" — className must map distinct rule-sets to distinct names`:`naming collision: rule-sets "${r}" and "${n}" both produce the class name "${a}" — segment sanitization collapses spaces / punctuation to "-", so rename one so they differ`);i.set(a,n)};return{naming:s,variableName:r=>{const o=n(s.varToken,r);if(!(null==t?void 0:t.variableName))return m(o,r),o;const i=(n=>{const r=a(n.replace(/^-+/,""));if(!r)throw new e.RefractError("REFRACT_E_NAMING",`naming override: variableName returned an empty/invalid name ("${n}")`);return`--${r}`})(t.variableName({path:r,segments:r.split(".")},{varToken:s.varToken,name:o}));return m(i,r),i},className:(n,o,i,l)=>{const c="container"===n?`${s.classToken}-cq-${a(l)}`:r(s,o,i,l),m=`${n}:${o}.${i}.${l}`;if(!(null==t?void 0:t.className))return d(c,m),c;const p=t.className({kind:n,subsystem:o,group:i,variant:l},{classToken:s.classToken,name:c}),u=a(p);if(!u)throw new e.RefractError("REFRACT_E_NAMING",`naming override: className returned an empty/invalid name for "${n}:${o}.${i}.${l}"`);return d(u,m),u}}},exports.recipeClassName=r,exports.resolveNaming=e=>{var n,r,s;return{varToken:a(null!==(n=e.prefix)&&void 0!==n?n:"dt")||"dt",classToken:a(null!==(s=null!==(r=e.classPrefix)&&void 0!==r?r:e.prefix)&&void 0!==s?s:"dt")||"dt"}},exports.sanitizeSegment=a,exports.varNameFromPath=n;
+//# sourceMappingURL=adapter-kit.cjs.js.map

package/dist/adapter-kit.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-kit.cjs.js","sources":["../src/adapter-kit.ts"],"sourcesContent":["/**\n * Uniform text-adapter naming (§17) — a single adapter-wide `prefix` (+ optional `classPrefix`\n * defaulting to it) drives every CSS variable and class name. Shared by the CSS and SC adapters so\n * the two text formats emit the SAME names from a token path — no per-subsystem infixes, no\n * per-subsystem defaults, single-dash separators. Lives at the adapters root (like `length.ts`) so\n * neither adapter depends on its sibling.\n *\n *   variable: `varNameFromPath(token, \"colors.primary.dark\")` → `--<token>-colors-primary-dark`\n *   class:    `recipeClassName(naming, \"colors\", \"solid\", \"primary\")` → `<classToken>-colors-solid-primary`\n */\n\nimport { RefractError } from \"./core/errors\";\n\n/** Kebab/underscore-safe identifier segment. */\nexport const sanitizeSegment = (segment: string): string =>\n  segment\n    .trim()\n    .replace(/\\s+/g, \"-\")\n    .replace(/[^a-zA-Z0-9-_]/g, \"-\")\n    .replace(/-+/g, \"-\")\n    .replace(/^-+/, \"\")\n    .replace(/-+$/, \"\")\n    .toLowerCase();\n\n/** Resolved naming tokens for one bound theme. */\nexport type AdapterNaming = {\n  /** Leading segment of every CSS variable name (`app` → `--app-colors-primary`). */\n  varToken: string;\n  /** Leading segment of every class name (`app` → `app-colors-solid-primary`). */\n  classToken: string;\n};\n\n/** Resolve the adapter-wide tokens: `classPrefix` falls back to `prefix`, both default to `dt`. */\nexport const resolveNaming = (options: { prefix?: string; classPrefix?: string }): AdapterNaming => {\n  const varToken = sanitizeSegment(options.prefix ?? \"dt\") || \"dt\";\n  const classToken = sanitizeSegment(options.classPrefix ?? options.prefix ?? \"dt\") || \"dt\";\n  return { varToken, classToken };\n};\n\n/** A token path → its CSS variable name: `colors.primary.dark` → `--<token>-colors-primary-dark`. */\nexport const varNameFromPath = (varToken: string, path: string): string =>\n  `--${varToken}-${path.split(\".\").map(sanitizeSegment).filter(Boolean).join(\"-\")}`;\n\n/** The recipe/rule-set identity: `<classToken>-<sub>-<group>-<variant>` (sanitized). */\nexport const recipeClassName = (\n  naming: AdapterNaming,\n  subsystem: string,\n  group: string,\n  variant: string,\n): string =>\n  [naming.classToken, subsystem, group, variant].map(sanitizeSegment).filter(Boolean).join(\"-\");\n\n// ---------------------------------------------------------------------------\n// §7B — adapter naming-override hook\n// ---------------------------------------------------------------------------\n\n/**\n * A token path → its (possibly overridden) CSS variable name. The resolver the CSS + SC lowering\n * thread in place of a raw `varToken`, so a variable's `:root` definition and every `var(--…)`\n * usage funnel through the same (optionally overridden) name.\n */\nexport type VarNamer = (path: string) => string;\n\n/**\n * Optional per-adapter formatters that swap how class + variable names are generated. Each receives\n * the structured address plus the computed built-in `name` (decorate it or replace it). Shared by\n * the two text adapters (CSS + SC); JSON keys its own way and stays out. The adapter enforces a\n * three-part contract on every result: **deterministic** (a pure fn of the address), **collision-free**\n * (distinct addresses must yield distinct names — a duplicate throws), and a **valid identifier**\n * (the result is run through {@link sanitizeSegment}).\n */\nexport type NamingOverrides = {\n  /**\n   * Remap a recipe class (`kind: \"recipe\"`) or a container-context utility (`kind: \"container\"`,\n   * the `-cq-<name>` class). `address.variant` is the recipe variant, or — for a container — its\n   * name. Return `defaults.name` to keep the built-in name for the kinds you don't care about.\n   */\n  className?(\n    address: { kind: \"recipe\" | \"container\"; subsystem: string; group: string; variant: string },\n    defaults: { classToken: string; name: string },\n  ): string;\n  /**\n   * Remap a CSS variable, addressed by its dotted token `path` (and its `segments`). The returned\n   * name is normalized to a valid custom property (`--` + sanitized body).\n   */\n  variableName?(\n    address: { path: string; segments: string[] },\n    defaults: { varToken: string; name: string },\n  ): string;\n};\n\n/** Normalize an overridden variable name to a valid custom property: `--` + sanitized body. */\nconst sanitizeVarName = (name: string): string => {\n  const body = sanitizeSegment(name.replace(/^-+/, \"\"));\n  if (!body) throw new RefractError(\"REFRACT_E_NAMING\", `naming override: variableName returned an empty/invalid name (\"${name}\")`);\n  return `--${body}`;\n};\n\n/** The bound naming surface for one theme: the resolved tokens + the two override-aware namers. */\nexport interface AdapterNamer {\n  readonly naming: AdapterNaming;\n  /** A token path → its (possibly overridden) CSS variable name. */\n  variableName: VarNamer;\n  /** A recipe or container-context class → its (possibly overridden) class name. */\n  className(\n    kind: \"recipe\" | \"container\",\n    subsystem: string,\n    group: string,\n    variant: string,\n  ): string;\n}\n\n/**\n * Bind the resolved {@link AdapterNaming} + optional {@link NamingOverrides} into an {@link AdapterNamer}.\n * Every emitted name is collision-checked on **both** the default and the override path: two distinct\n * addresses (token paths / rule-sets) that resolve to the same output name throw a path-labelled error,\n * so a silent merge — e.g. palettes `\"brand accent\"` and `\"brand-accent\"` both sanitizing to\n * `--dt-colors-brand-accent` — fails loud instead. The SAME address re-resolving to the same name is\n * fine (definitions + usages call repeatedly). With no overrides the namer returns the built-in name\n * verbatim (byte-identical); the bookkeeping is checked but never rewrites the name.\n * The container-context class keeps its own `<classToken>-cq-<name>` default, distinct from the recipe formula.\n */\nexport const createNamer = (naming: AdapterNaming, overrides?: NamingOverrides): AdapterNamer => {\n  const varSeen = new Map<string, string>(); // output var name → source path\n  const classSeen = new Map<string, string>(); // output class name → source address key\n  const hasVarOverride = !!overrides?.variableName;\n  const hasClassOverride = !!overrides?.className;\n\n  const trackVar = (name: string, path: string): void => {\n    const prev = varSeen.get(name);\n    if (prev !== undefined && prev !== path) {\n      throw new RefractError(\n        \"REFRACT_E_NAMING\",\n        hasVarOverride\n          ? `naming override: variable name \"${name}\" is produced by both \"${prev}\" and \"${path}\" — ` +\n              `variableName must map distinct token paths to distinct names`\n          : `naming collision: token paths \"${prev}\" and \"${path}\" both produce the variable name ` +\n              `\"${name}\" — segment sanitization collapses spaces / punctuation to \"-\", so rename one ` +\n              `so their sanitized names differ`,\n      );\n    }\n    varSeen.set(name, path);\n  };\n\n  const trackClass = (name: string, key: string): void => {\n    const prev = classSeen.get(name);\n    if (prev !== undefined && prev !== key) {\n      throw new RefractError(\n        \"REFRACT_E_NAMING\",\n        hasClassOverride\n          ? `naming override: class name \"${name}\" is produced by both \"${prev}\" and \"${key}\" — ` +\n              `className must map distinct rule-sets to distinct names`\n          : `naming collision: rule-sets \"${prev}\" and \"${key}\" both produce the class name \"${name}\" — ` +\n              `segment sanitization collapses spaces / punctuation to \"-\", so rename one so they differ`,\n      );\n    }\n    classSeen.set(name, key);\n  };\n\n  return {\n    naming,\n    variableName: (path) => {\n      const def = varNameFromPath(naming.varToken, path);\n      if (!overrides?.variableName) {\n        trackVar(def, path);\n        return def;\n      }\n      const raw = overrides.variableName(\n        { path, segments: path.split(\".\") },\n        { varToken: naming.varToken, name: def },\n      );\n      const name = sanitizeVarName(raw);\n      trackVar(name, path);\n      return name;\n    },\n    className: (kind, subsystem, group, variant) => {\n      const def =\n        kind === \"container\"\n          ? `${naming.classToken}-cq-${sanitizeSegment(variant)}`\n          : recipeClassName(naming, subsystem, group, variant);\n      const key = `${kind}:${subsystem}.${group}.${variant}`;\n      if (!overrides?.className) {\n        trackClass(def, key);\n        return def;\n      }\n      const raw = overrides.className(\n        { kind, subsystem, group, variant },\n        { classToken: naming.classToken, name: def },\n      );\n      const name = sanitizeSegment(raw);\n      if (!name) {\n        throw new RefractError(\n          \"REFRACT_E_NAMING\",\n          `naming override: className returned an empty/invalid name for ` +\n            `\"${kind}:${subsystem}.${group}.${variant}\"`,\n        );\n      }\n      trackClass(name, key);\n      return name;\n    },\n  };\n};\n"],"names":["sanitizeSegment","segment","trim","replace","toLowerCase","varNameFromPath","varToken","path","split","map","filter","Boolean","join","recipeClassName","naming","subsystem","group","variant","classToken","overrides","varSeen","Map","classSeen","hasVarOverride","variableName","hasClassOverride","className","trackVar","name","prev","get","undefined","RefractError","set","trackClass","key","def","body","sanitizeVarName","segments","kind","raw","options","_a","prefix","_c","_b","classPrefix"],"mappings":"8DAcaA,EAAmBC,GAC9BA,EACGC,OACAC,QAAQ,OAAQ,KAChBA,QAAQ,kBAAmB,KAC3BA,QAAQ,MAAO,KACfA,QAAQ,MAAO,IACfA,QAAQ,MAAO,IACfC,cAkBQC,EAAkB,CAACC,EAAkBC,IAChD,KAAKD,KAAYC,EAAKC,MAAM,KAAKC,IAAIT,GAAiBU,OAAOC,SAASC,KAAK,OAGhEC,EAAkB,CAC7BC,EACAC,EACAC,EACAC,IAEA,CAACH,EAAOI,WAAYH,EAAWC,EAAOC,GAASR,IAAIT,GAAiBU,OAAOC,SAASC,KAAK,yBAwEhE,CAACE,EAAuBK,KACjD,MAAMC,EAAU,IAAIC,IACdC,EAAY,IAAID,IAChBE,KAAmBJ,aAAA,EAAAA,EAAWK,cAC9BC,KAAqBN,aAAA,EAAAA,EAAWO,WAEhCC,EAAW,CAACC,EAAcrB,KAC9B,MAAMsB,EAAOT,EAAQU,IAAIF,GACzB,QAAaG,IAATF,GAAsBA,IAAStB,EACjC,MAAM,IAAIyB,EAAAA,aACR,mBACAT,EACI,mCAAmCK,2BAA8BC,WAActB,oEAE/E,kCAAkCsB,WAActB,sCAC1CqB,kHAIdR,EAAQa,IAAIL,EAAMrB,IAGd2B,EAAa,CAACN,EAAcO,KAChC,MAAMN,EAAOP,EAAUQ,IAAIF,GAC3B,QAAaG,IAATF,GAAsBA,IAASM,EACjC,MAAM,IAAIH,EAAAA,aACR,mBACAP,EACI,gCAAgCG,2BAA8BC,WAAcM,+DAE5E,gCAAgCN,WAAcM,mCAAqCP,iGAI3FN,EAAUW,IAAIL,EAAMO,IAGtB,MAAO,CACLrB,SACAU,aAAejB,IACb,MAAM6B,EAAM/B,EAAgBS,EAAOR,SAAUC,GAC7C,KAAKY,aAAA,EAAAA,EAAWK,cAEd,OADAG,EAASS,EAAK7B,GACP6B,EAET,MAIMR,EA/EY,CAACA,IACvB,MAAMS,EAAOrC,EAAgB4B,EAAKzB,QAAQ,MAAO,KACjD,IAAKkC,EAAM,MAAM,IAAIL,EAAYA,aAAC,mBAAoB,kEAAkEJ,OACxH,MAAO,KAAKS,KA4EKC,CAJDnB,EAAUK,aACpB,CAAEjB,OAAMgC,SAAUhC,EAAKC,MAAM,MAC7B,CAAEF,SAAUQ,EAAOR,SAAUsB,KAAMQ,KAIrC,OADAT,EAASC,EAAMrB,GACRqB,GAETF,UAAW,CAACc,EAAMzB,EAAWC,EAAOC,KAClC,MAAMmB,EACK,cAATI,EACI,GAAG1B,EAAOI,iBAAiBlB,EAAgBiB,KAC3CJ,EAAgBC,EAAQC,EAAWC,EAAOC,GAC1CkB,EAAM,GAAGK,KAAQzB,KAAaC,KAASC,IAC7C,KAAKE,aAAA,EAAAA,EAAWO,WAEd,OADAQ,EAAWE,EAAKD,GACTC,EAET,MAAMK,EAAMtB,EAAUO,UACpB,CAAEc,OAAMzB,YAAWC,QAAOC,WAC1B,CAAEC,WAAYJ,EAAOI,WAAYU,KAAMQ,IAEnCR,EAAO5B,EAAgByC,GAC7B,IAAKb,EACH,MAAM,IAAII,EAAYA,aACpB,mBAEE,kEAAIQ,KAAQzB,KAAaC,KAASC,MAIxC,OADAiB,EAAWN,EAAMO,GACVP,qDArKiBc,cAG5B,MAAO,CAAEpC,SAFQN,EAAkC,QAAlB2C,EAAAD,EAAQE,cAAU,IAAAD,EAAAA,EAAA,OAAS,KAEzCzB,WADAlB,EAAqD,QAArC6C,EAAuB,QAAvBC,EAAAJ,EAAQK,mBAAe,IAAAD,EAAAA,EAAAJ,EAAQE,cAAM,IAAAC,EAAAA,EAAI,OAAS"}

package/dist/adapter-kit.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Uniform text-adapter naming (§17) — a single adapter-wide `prefix` (+ optional `classPrefix`
+ * defaulting to it) drives every CSS variable and class name. Shared by the CSS and SC adapters so
+ * the two text formats emit the SAME names from a token path — no per-subsystem infixes, no
+ * per-subsystem defaults, single-dash separators. Lives at the adapters root (like `length.ts`) so
+ * neither adapter depends on its sibling.
+ *
+ *   variable: `varNameFromPath(token, "colors.primary.dark")` → `--<token>-colors-primary-dark`
+ *   class:    `recipeClassName(naming, "colors", "solid", "primary")` → `<classToken>-colors-solid-primary`
+ */
+/** Kebab/underscore-safe identifier segment. */
+export declare const sanitizeSegment: (segment: string) => string;
+/** Resolved naming tokens for one bound theme. */
+export type AdapterNaming = {
+    /** Leading segment of every CSS variable name (`app` → `--app-colors-primary`). */
+    varToken: string;
+    /** Leading segment of every class name (`app` → `app-colors-solid-primary`). */
+    classToken: string;
+};
+/** Resolve the adapter-wide tokens: `classPrefix` falls back to `prefix`, both default to `dt`. */
+export declare const resolveNaming: (options: {
+    prefix?: string;
+    classPrefix?: string;
+}) => AdapterNaming;
+/** A token path → its CSS variable name: `colors.primary.dark` → `--<token>-colors-primary-dark`. */
+export declare const varNameFromPath: (varToken: string, path: string) => string;
+/** The recipe/rule-set identity: `<classToken>-<sub>-<group>-<variant>` (sanitized). */
+export declare const recipeClassName: (naming: AdapterNaming, subsystem: string, group: string, variant: string) => string;
+/**
+ * A token path → its (possibly overridden) CSS variable name. The resolver the CSS + SC lowering
+ * thread in place of a raw `varToken`, so a variable's `:root` definition and every `var(--…)`
+ * usage funnel through the same (optionally overridden) name.
+ */
+export type VarNamer = (path: string) => string;
+/**
+ * Optional per-adapter formatters that swap how class + variable names are generated. Each receives
+ * the structured address plus the computed built-in `name` (decorate it or replace it). Shared by
+ * the two text adapters (CSS + SC); JSON keys its own way and stays out. The adapter enforces a
+ * three-part contract on every result: **deterministic** (a pure fn of the address), **collision-free**
+ * (distinct addresses must yield distinct names — a duplicate throws), and a **valid identifier**
+ * (the result is run through {@link sanitizeSegment}).
+ */
+export type NamingOverrides = {
+    /**
+     * Remap a recipe class (`kind: "recipe"`) or a container-context utility (`kind: "container"`,
+     * the `-cq-<name>` class). `address.variant` is the recipe variant, or — for a container — its
+     * name. Return `defaults.name` to keep the built-in name for the kinds you don't care about.
+     */
+    className?(address: {
+        kind: "recipe" | "container";
+        subsystem: string;
+        group: string;
+        variant: string;
+    }, defaults: {
+        classToken: string;
+        name: string;
+    }): string;
+    /**
+     * Remap a CSS variable, addressed by its dotted token `path` (and its `segments`). The returned
+     * name is normalized to a valid custom property (`--` + sanitized body).
+     */
+    variableName?(address: {
+        path: string;
+        segments: string[];
+    }, defaults: {
+        varToken: string;
+        name: string;
+    }): string;
+};
+/** The bound naming surface for one theme: the resolved tokens + the two override-aware namers. */
+export interface AdapterNamer {
+    readonly naming: AdapterNaming;
+    /** A token path → its (possibly overridden) CSS variable name. */
+    variableName: VarNamer;
+    /** A recipe or container-context class → its (possibly overridden) class name. */
+    className(kind: "recipe" | "container", subsystem: string, group: string, variant: string): string;
+}
+/**
+ * Bind the resolved {@link AdapterNaming} + optional {@link NamingOverrides} into an {@link AdapterNamer}.
+ * Every emitted name is collision-checked on **both** the default and the override path: two distinct
+ * addresses (token paths / rule-sets) that resolve to the same output name throw a path-labelled error,
+ * so a silent merge — e.g. palettes `"brand accent"` and `"brand-accent"` both sanitizing to
+ * `--dt-colors-brand-accent` — fails loud instead. The SAME address re-resolving to the same name is
+ * fine (definitions + usages call repeatedly). With no overrides the namer returns the built-in name
+ * verbatim (byte-identical); the bookkeeping is checked but never rewrites the name.
+ * The container-context class keeps its own `<classToken>-cq-<name>` default, distinct from the recipe formula.
+ */
+export declare const createNamer: (naming: AdapterNaming, overrides?: NamingOverrides) => AdapterNamer;

package/dist/adapter-kit.esm.js

@@ -0,0 +1,2 @@
+import{R as e}from"./_errors-d75a5c74.esm.js";const a=e=>e.trim().replace(/\s+/g,"-").replace(/[^a-zA-Z0-9-_]/g,"-").replace(/-+/g,"-").replace(/^-+/,"").replace(/-+$/,"").toLowerCase(),n=e=>{var n,s,t;return{varToken:a(null!==(n=e.prefix)&&void 0!==n?n:"dt")||"dt",classToken:a(null!==(t=null!==(s=e.classPrefix)&&void 0!==s?s:e.prefix)&&void 0!==t?t:"dt")||"dt"}},s=(e,n)=>`--${e}-${n.split(".").map(a).filter(Boolean).join("-")}`,t=(e,n,s,t)=>[e.classToken,n,s,t].map(a).filter(Boolean).join("-"),o=(n,o)=>{const i=new Map,r=new Map,l=!!(null==o?void 0:o.variableName),m=!!(null==o?void 0:o.className),c=(a,n)=>{const s=i.get(a);if(void 0!==s&&s!==n)throw new e("REFRACT_E_NAMING",l?`naming override: variable name "${a}" is produced by both "${s}" and "${n}" — variableName must map distinct token paths to distinct names`:`naming collision: token paths "${s}" and "${n}" both produce the variable name "${a}" — segment sanitization collapses spaces / punctuation to "-", so rename one so their sanitized names differ`);i.set(a,n)},d=(a,n)=>{const s=r.get(a);if(void 0!==s&&s!==n)throw new e("REFRACT_E_NAMING",m?`naming override: class name "${a}" is produced by both "${s}" and "${n}" — className must map distinct rule-sets to distinct names`:`naming collision: rule-sets "${s}" and "${n}" both produce the class name "${a}" — segment sanitization collapses spaces / punctuation to "-", so rename one so they differ`);r.set(a,n)};return{naming:n,variableName:t=>{const i=s(n.varToken,t);if(!(null==o?void 0:o.variableName))return c(i,t),i;const r=(n=>{const s=a(n.replace(/^-+/,""));if(!s)throw new e("REFRACT_E_NAMING",`naming override: variableName returned an empty/invalid name ("${n}")`);return`--${s}`})(o.variableName({path:t,segments:t.split(".")},{varToken:n.varToken,name:i}));return c(r,t),r},className:(s,i,r,l)=>{const m="container"===s?`${n.classToken}-cq-${a(l)}`:t(n,i,r,l),c=`${s}:${i}.${r}.${l}`;if(!(null==o?void 0:o.className))return d(m,c),m;const p=o.className({kind:s,subsystem:i,group:r,variant:l},{classToken:n.classToken,name:m}),u=a(p);if(!u)throw new e("REFRACT_E_NAMING",`naming override: className returned an empty/invalid name for "${s}:${i}.${r}.${l}"`);return d(u,c),u}}};export{o as createNamer,t as recipeClassName,n as resolveNaming,a as sanitizeSegment,s as varNameFromPath};
+//# sourceMappingURL=adapter-kit.esm.js.map

package/dist/adapter-kit.esm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-kit.esm.js","sources":["../src/adapter-kit.ts"],"sourcesContent":["/**\n * Uniform text-adapter naming (§17) — a single adapter-wide `prefix` (+ optional `classPrefix`\n * defaulting to it) drives every CSS variable and class name. Shared by the CSS and SC adapters so\n * the two text formats emit the SAME names from a token path — no per-subsystem infixes, no\n * per-subsystem defaults, single-dash separators. Lives at the adapters root (like `length.ts`) so\n * neither adapter depends on its sibling.\n *\n *   variable: `varNameFromPath(token, \"colors.primary.dark\")` → `--<token>-colors-primary-dark`\n *   class:    `recipeClassName(naming, \"colors\", \"solid\", \"primary\")` → `<classToken>-colors-solid-primary`\n */\n\nimport { RefractError } from \"./core/errors\";\n\n/** Kebab/underscore-safe identifier segment. */\nexport const sanitizeSegment = (segment: string): string =>\n  segment\n    .trim()\n    .replace(/\\s+/g, \"-\")\n    .replace(/[^a-zA-Z0-9-_]/g, \"-\")\n    .replace(/-+/g, \"-\")\n    .replace(/^-+/, \"\")\n    .replace(/-+$/, \"\")\n    .toLowerCase();\n\n/** Resolved naming tokens for one bound theme. */\nexport type AdapterNaming = {\n  /** Leading segment of every CSS variable name (`app` → `--app-colors-primary`). */\n  varToken: string;\n  /** Leading segment of every class name (`app` → `app-colors-solid-primary`). */\n  classToken: string;\n};\n\n/** Resolve the adapter-wide tokens: `classPrefix` falls back to `prefix`, both default to `dt`. */\nexport const resolveNaming = (options: { prefix?: string; classPrefix?: string }): AdapterNaming => {\n  const varToken = sanitizeSegment(options.prefix ?? \"dt\") || \"dt\";\n  const classToken = sanitizeSegment(options.classPrefix ?? options.prefix ?? \"dt\") || \"dt\";\n  return { varToken, classToken };\n};\n\n/** A token path → its CSS variable name: `colors.primary.dark` → `--<token>-colors-primary-dark`. */\nexport const varNameFromPath = (varToken: string, path: string): string =>\n  `--${varToken}-${path.split(\".\").map(sanitizeSegment).filter(Boolean).join(\"-\")}`;\n\n/** The recipe/rule-set identity: `<classToken>-<sub>-<group>-<variant>` (sanitized). */\nexport const recipeClassName = (\n  naming: AdapterNaming,\n  subsystem: string,\n  group: string,\n  variant: string,\n): string =>\n  [naming.classToken, subsystem, group, variant].map(sanitizeSegment).filter(Boolean).join(\"-\");\n\n// ---------------------------------------------------------------------------\n// §7B — adapter naming-override hook\n// ---------------------------------------------------------------------------\n\n/**\n * A token path → its (possibly overridden) CSS variable name. The resolver the CSS + SC lowering\n * thread in place of a raw `varToken`, so a variable's `:root` definition and every `var(--…)`\n * usage funnel through the same (optionally overridden) name.\n */\nexport type VarNamer = (path: string) => string;\n\n/**\n * Optional per-adapter formatters that swap how class + variable names are generated. Each receives\n * the structured address plus the computed built-in `name` (decorate it or replace it). Shared by\n * the two text adapters (CSS + SC); JSON keys its own way and stays out. The adapter enforces a\n * three-part contract on every result: **deterministic** (a pure fn of the address), **collision-free**\n * (distinct addresses must yield distinct names — a duplicate throws), and a **valid identifier**\n * (the result is run through {@link sanitizeSegment}).\n */\nexport type NamingOverrides = {\n  /**\n   * Remap a recipe class (`kind: \"recipe\"`) or a container-context utility (`kind: \"container\"`,\n   * the `-cq-<name>` class). `address.variant` is the recipe variant, or — for a container — its\n   * name. Return `defaults.name` to keep the built-in name for the kinds you don't care about.\n   */\n  className?(\n    address: { kind: \"recipe\" | \"container\"; subsystem: string; group: string; variant: string },\n    defaults: { classToken: string; name: string },\n  ): string;\n  /**\n   * Remap a CSS variable, addressed by its dotted token `path` (and its `segments`). The returned\n   * name is normalized to a valid custom property (`--` + sanitized body).\n   */\n  variableName?(\n    address: { path: string; segments: string[] },\n    defaults: { varToken: string; name: string },\n  ): string;\n};\n\n/** Normalize an overridden variable name to a valid custom property: `--` + sanitized body. */\nconst sanitizeVarName = (name: string): string => {\n  const body = sanitizeSegment(name.replace(/^-+/, \"\"));\n  if (!body) throw new RefractError(\"REFRACT_E_NAMING\", `naming override: variableName returned an empty/invalid name (\"${name}\")`);\n  return `--${body}`;\n};\n\n/** The bound naming surface for one theme: the resolved tokens + the two override-aware namers. */\nexport interface AdapterNamer {\n  readonly naming: AdapterNaming;\n  /** A token path → its (possibly overridden) CSS variable name. */\n  variableName: VarNamer;\n  /** A recipe or container-context class → its (possibly overridden) class name. */\n  className(\n    kind: \"recipe\" | \"container\",\n    subsystem: string,\n    group: string,\n    variant: string,\n  ): string;\n}\n\n/**\n * Bind the resolved {@link AdapterNaming} + optional {@link NamingOverrides} into an {@link AdapterNamer}.\n * Every emitted name is collision-checked on **both** the default and the override path: two distinct\n * addresses (token paths / rule-sets) that resolve to the same output name throw a path-labelled error,\n * so a silent merge — e.g. palettes `\"brand accent\"` and `\"brand-accent\"` both sanitizing to\n * `--dt-colors-brand-accent` — fails loud instead. The SAME address re-resolving to the same name is\n * fine (definitions + usages call repeatedly). With no overrides the namer returns the built-in name\n * verbatim (byte-identical); the bookkeeping is checked but never rewrites the name.\n * The container-context class keeps its own `<classToken>-cq-<name>` default, distinct from the recipe formula.\n */\nexport const createNamer = (naming: AdapterNaming, overrides?: NamingOverrides): AdapterNamer => {\n  const varSeen = new Map<string, string>(); // output var name → source path\n  const classSeen = new Map<string, string>(); // output class name → source address key\n  const hasVarOverride = !!overrides?.variableName;\n  const hasClassOverride = !!overrides?.className;\n\n  const trackVar = (name: string, path: string): void => {\n    const prev = varSeen.get(name);\n    if (prev !== undefined && prev !== path) {\n      throw new RefractError(\n        \"REFRACT_E_NAMING\",\n        hasVarOverride\n          ? `naming override: variable name \"${name}\" is produced by both \"${prev}\" and \"${path}\" — ` +\n              `variableName must map distinct token paths to distinct names`\n          : `naming collision: token paths \"${prev}\" and \"${path}\" both produce the variable name ` +\n              `\"${name}\" — segment sanitization collapses spaces / punctuation to \"-\", so rename one ` +\n              `so their sanitized names differ`,\n      );\n    }\n    varSeen.set(name, path);\n  };\n\n  const trackClass = (name: string, key: string): void => {\n    const prev = classSeen.get(name);\n    if (prev !== undefined && prev !== key) {\n      throw new RefractError(\n        \"REFRACT_E_NAMING\",\n        hasClassOverride\n          ? `naming override: class name \"${name}\" is produced by both \"${prev}\" and \"${key}\" — ` +\n              `className must map distinct rule-sets to distinct names`\n          : `naming collision: rule-sets \"${prev}\" and \"${key}\" both produce the class name \"${name}\" — ` +\n              `segment sanitization collapses spaces / punctuation to \"-\", so rename one so they differ`,\n      );\n    }\n    classSeen.set(name, key);\n  };\n\n  return {\n    naming,\n    variableName: (path) => {\n      const def = varNameFromPath(naming.varToken, path);\n      if (!overrides?.variableName) {\n        trackVar(def, path);\n        return def;\n      }\n      const raw = overrides.variableName(\n        { path, segments: path.split(\".\") },\n        { varToken: naming.varToken, name: def },\n      );\n      const name = sanitizeVarName(raw);\n      trackVar(name, path);\n      return name;\n    },\n    className: (kind, subsystem, group, variant) => {\n      const def =\n        kind === \"container\"\n          ? `${naming.classToken}-cq-${sanitizeSegment(variant)}`\n          : recipeClassName(naming, subsystem, group, variant);\n      const key = `${kind}:${subsystem}.${group}.${variant}`;\n      if (!overrides?.className) {\n        trackClass(def, key);\n        return def;\n      }\n      const raw = overrides.className(\n        { kind, subsystem, group, variant },\n        { classToken: naming.classToken, name: def },\n      );\n      const name = sanitizeSegment(raw);\n      if (!name) {\n        throw new RefractError(\n          \"REFRACT_E_NAMING\",\n          `naming override: className returned an empty/invalid name for ` +\n            `\"${kind}:${subsystem}.${group}.${variant}\"`,\n        );\n      }\n      trackClass(name, key);\n      return name;\n    },\n  };\n};\n"],"names":["sanitizeSegment","segment","trim","replace","toLowerCase","resolveNaming","options","varToken","_a","prefix","classToken","_c","_b","classPrefix","varNameFromPath","path","split","map","filter","Boolean","join","recipeClassName","naming","subsystem","group","variant","createNamer","overrides","varSeen","Map","classSeen","hasVarOverride","variableName","hasClassOverride","className","trackVar","name","prev","get","undefined","RefractError","set","trackClass","key","def","body","sanitizeVarName","segments","kind","raw"],"mappings":"oDAcaA,EAAmBC,GAC9BA,EACGC,OACAC,QAAQ,OAAQ,KAChBA,QAAQ,kBAAmB,KAC3BA,QAAQ,MAAO,KACfA,QAAQ,MAAO,IACfA,QAAQ,MAAO,IACfC,cAWQC,EAAiBC,cAG5B,MAAO,CAAEC,SAFQP,EAAkC,QAAlBQ,EAAAF,EAAQG,cAAU,IAAAD,EAAAA,EAAA,OAAS,KAEzCE,WADAV,EAAqD,QAArCW,EAAuB,QAAvBC,EAAAN,EAAQO,mBAAe,IAAAD,EAAAA,EAAAN,EAAQG,cAAM,IAAAE,EAAAA,EAAI,OAAS,OAK1EG,EAAkB,CAACP,EAAkBQ,IAChD,KAAKR,KAAYQ,EAAKC,MAAM,KAAKC,IAAIjB,GAAiBkB,OAAOC,SAASC,KAAK,OAGhEC,EAAkB,CAC7BC,EACAC,EACAC,EACAC,IAEA,CAACH,EAAOZ,WAAYa,EAAWC,EAAOC,GAASR,IAAIjB,GAAiBkB,OAAOC,SAASC,KAAK,KAwE9EM,EAAc,CAACJ,EAAuBK,KACjD,MAAMC,EAAU,IAAIC,IACdC,EAAY,IAAID,IAChBE,KAAmBJ,aAAA,EAAAA,EAAWK,cAC9BC,KAAqBN,aAAA,EAAAA,EAAWO,WAEhCC,EAAW,CAACC,EAAcrB,KAC9B,MAAMsB,EAAOT,EAAQU,IAAIF,GACzB,QAAaG,IAATF,GAAsBA,IAAStB,EACjC,MAAM,IAAIyB,EACR,mBACAT,EACI,mCAAmCK,2BAA8BC,WAActB,oEAE/E,kCAAkCsB,WAActB,sCAC1CqB,kHAIdR,EAAQa,IAAIL,EAAMrB,IAGd2B,EAAa,CAACN,EAAcO,KAChC,MAAMN,EAAOP,EAAUQ,IAAIF,GAC3B,QAAaG,IAATF,GAAsBA,IAASM,EACjC,MAAM,IAAIH,EACR,mBACAP,EACI,gCAAgCG,2BAA8BC,WAAcM,+DAE5E,gCAAgCN,WAAcM,mCAAqCP,iGAI3FN,EAAUW,IAAIL,EAAMO,IAGtB,MAAO,CACLrB,SACAU,aAAejB,IACb,MAAM6B,EAAM9B,EAAgBQ,EAAOf,SAAUQ,GAC7C,KAAKY,aAAA,EAAAA,EAAWK,cAEd,OADAG,EAASS,EAAK7B,GACP6B,EAET,MAIMR,EA/EY,CAACA,IACvB,MAAMS,EAAO7C,EAAgBoC,EAAKjC,QAAQ,MAAO,KACjD,IAAK0C,EAAM,MAAM,IAAIL,EAAa,mBAAoB,kEAAkEJ,OACxH,MAAO,KAAKS,KA4EKC,CAJDnB,EAAUK,aACpB,CAAEjB,OAAMgC,SAAUhC,EAAKC,MAAM,MAC7B,CAAET,SAAUe,EAAOf,SAAU6B,KAAMQ,KAIrC,OADAT,EAASC,EAAMrB,GACRqB,GAETF,UAAW,CAACc,EAAMzB,EAAWC,EAAOC,KAClC,MAAMmB,EACK,cAATI,EACI,GAAG1B,EAAOZ,iBAAiBV,EAAgByB,KAC3CJ,EAAgBC,EAAQC,EAAWC,EAAOC,GAC1CkB,EAAM,GAAGK,KAAQzB,KAAaC,KAASC,IAC7C,KAAKE,aAAA,EAAAA,EAAWO,WAEd,OADAQ,EAAWE,EAAKD,GACTC,EAET,MAAMK,EAAMtB,EAAUO,UACpB,CAAEc,OAAMzB,YAAWC,QAAOC,WAC1B,CAAEf,WAAYY,EAAOZ,WAAY0B,KAAMQ,IAEnCR,EAAOpC,EAAgBiD,GAC7B,IAAKb,EACH,MAAM,IAAII,EACR,mBAEE,kEAAIQ,KAAQzB,KAAaC,KAASC,MAIxC,OADAiB,EAAWN,EAAMO,GACVP"}

package/dist/build/auditCommand.d.ts

@@ -0,0 +1,19 @@
+import { type AuditResult, type WcagLevel } from "../subsystems/colors/audit";
+export interface AuditCommandOptions {
+    readonly cwd?: string;
+    /** `--config` override — a path to the config file. */
+    readonly configPath?: string;
+    /** `--strict` — throw (non-zero exit) when any pairing fails. */
+    readonly strict?: boolean;
+    /** `--min-wcag` — pass bar (`"AA"` default). */
+    readonly minWcag?: WcagLevel;
+    /** `--large` — score against large-text thresholds. */
+    readonly largeText?: boolean;
+}
+export interface AuditCommandResult {
+    /** Absolute path the config was loaded from. */
+    readonly configPath: string;
+    readonly result: AuditResult;
+}
+/** Load the config, build the theme (adapter-free), and audit its colour pairings. */
+export declare function runAudit(options?: AuditCommandOptions): Promise<AuditCommandResult>;

package/dist/build/buildCommand.d.ts

@@ -0,0 +1,23 @@
+export interface BuildOptions {
+    readonly cwd?: string;
+    /** `--config` override — a path to the config file. */
+    readonly configPath?: string;
+    /** `--target` override — a target name, numeric index, or outDir to build in isolation. */
+    readonly target?: string;
+    /** `--out` override — replaces the selected target's outDir. */
+    readonly out?: string;
+}
+export interface BuildTargetSummary {
+    readonly name?: string;
+    readonly adapter: string;
+    /** Absolute outDir the target was written to. */
+    readonly outDir: string;
+    /** Absolute paths of every file written for this target. */
+    readonly files: string[];
+}
+export interface BuildResult {
+    readonly configPath: string;
+    readonly targets: BuildTargetSummary[];
+}
+/** Load the config and emit every (selected) target to disk. */
+export declare function runBuild(options?: BuildOptions): Promise<BuildResult>;

package/dist/build/cli.d.ts

@@ -0,0 +1,2 @@
+/** Dispatch a parsed argv (without the node/script prefix). Returns a process exit code. */
+export declare function main(argv: string[]): Promise<number>;

package/dist/build/config.d.ts

@@ -0,0 +1,58 @@
+import type { ThemeAdapter, Emit } from "../core/ThemeAdapter";
+import type { RawTheme } from "../core/rawTheme";
+import type { MediaConfig } from "../core/media";
+import type { UnitsConfig } from "../core/units";
+import type { GuideConfig } from "./emitTheme";
+/** One emit target: an adapter + where to write it, plus which shared vendored helpers it wants. */
+export interface EmitTarget {
+    readonly adapter: ThemeAdapter;
+    readonly outDir: string;
+    readonly helpers?: readonly string[];
+    /** Optional label — lets `refract build --target <name>` select this target (else index/outDir). */
+    readonly name?: string;
+    /** Optional output-shape directive (§9): single / split / subsystem / components. Default = single. */
+    readonly emit?: Emit;
+    /**
+     * §C — emit a self-documenting `llms.txt` + `manifest.json` into this target's `outDir`, so a
+     * published/zipped theme carries its own AI consumption guide (real class names / token paths) for
+     * a downstream dev who has neither refract nor its skills. `true` uses defaults; an object tunes the
+     * file names or adds a `packageName` for a by-specifier import overlay. Off by default.
+     */
+    readonly guide?: boolean | GuideConfig;
+}
+/** The `theme.config` shape: the raw theme + one or more emit targets. */
+export interface ThemeConfig {
+    readonly raw: RawTheme;
+    readonly targets: readonly EmitTarget[];
+    /**
+     * Media-query output config (§10.5) — `{ unit: "px" | "em" | "rem"; baseFontSize }`. Applies to
+     * both the viewport `@media` and container `@container` widths (breakpoints/container thresholds are
+     * authored as px numbers; `unit` controls the emitted unit). Defaults to px.
+     */
+    readonly media?: MediaConfig;
+    /**
+     * Declaration-value length units (§21) — a token-path role map (`units.default`, `units["<subsystem>"]`,
+     * `units["<subsystem>.<property>"]`), most-specific wins over the built-in seed. Resolved once, format-
+     * neutrally, so every target emits the same unit. The build-time twin of `createTheme`'s `units` option.
+     */
+    readonly units?: UnitsConfig;
+    /** Divisor when a deferred length resolves to `rem` (§21). Defaults to 16. */
+    readonly baseFontSize?: number;
+}
+/** Identity fn — types the config authored in `theme.config.(ts|js|mjs)`. */
+export declare const defineConfig: (config: ThemeConfig) => ThemeConfig;
+/** Find `theme.config.{ts,mjs,js}` in `fromDir`, honoring the ts→mjs→js resolution order. */
+export declare const findConfigFile: (fromDir?: string) => string | undefined;
+export interface LoadedConfig {
+    readonly config: ThemeConfig;
+    /** Absolute path the config was loaded from. */
+    readonly path: string;
+}
+/**
+ * Resolve + load a `theme.config`. `configPath` (a CLI `--config` override) wins; otherwise the
+ * ts→mjs→js search in `cwd`. Returns the `defineConfig(...)` object (default or named `config` export).
+ */
+export declare function loadConfig(options?: {
+    cwd?: string;
+    configPath?: string;
+}): Promise<LoadedConfig>;

package/dist/build/diff.d.ts

@@ -0,0 +1,56 @@
+/**
+ * `diffThemes` — the blast radius of a candidate theme edit, computed against a base (§5 agent-native).
+ *
+ * refract stores every synthesized rung/variant as a `{ ref, fn, arg }` graph, not a frozen literal, so
+ * a candidate theme can be *built and compared* before it's applied — the claim no token file can make:
+ * see what a change does before you make it. This is the shared engine behind `refract diff <candidate>`
+ * (a human CLI + a CI gate) and the MCP `diffTheme` tool (an agent's plan-then-apply guardrail).
+ *
+ * Three axes, each adapter-independent except `classes`:
+ *   - `tokens`   — which resolved token values moved (added / removed / changed).
+ *   - `classes`  — which emitted recipe classes changed CSS (only when the themes emit classes, e.g. the
+ *                  CSS adapter — read via the duck-typed `renderRecipe` / `getClass`).
+ *   - `contrast` — which WCAG pairings crossed a pass/level threshold (via {@link audit}).
+ */
+import type { Theme } from "../core";
+export type ChangeKind = "added" | "removed" | "changed";
+export interface TokenChange {
+    path: string;
+    before: string | null;
+    after: string | null;
+    kind: ChangeKind;
+}
+export interface ClassChange {
+    /** The emitted class name (or the `subsystem.group.variant` id when no adapter names it). */
+    name: string;
+    kind: ChangeKind;
+}
+export interface ContrastScore {
+    ratio?: number;
+    level?: string;
+    pass?: boolean;
+}
+export interface ContrastChange {
+    label: string;
+    before: ContrastScore | null;
+    after: ContrastScore | null;
+    /** True when the pass verdict or the WCAG level changed — the threshold-crossing an agent cares about. */
+    crossed: boolean;
+}
+export interface ThemeDiff {
+    tokens: TokenChange[];
+    classes: ClassChange[];
+    contrast: ContrastChange[];
+    summary: {
+        tokensChanged: number;
+        classesChanged: number;
+        /** Pairings whose pass verdict or level crossed a threshold. */
+        pairingsCrossed: number;
+    };
+}
+/**
+ * Diff a candidate theme against a base. Both should be built with the same adapter; pass a
+ * class-emitting adapter (e.g. CSS) on both sides to populate `classes`, or any adapter for the
+ * adapter-independent `tokens` / `contrast` axes.
+ */
+export declare function diffThemes(base: Theme, candidate: Theme): ThemeDiff;

package/dist/build/diffCommand.d.ts

@@ -0,0 +1,29 @@
+import { type ThemeDiff } from "./diff";
+export interface DiffCommandOptions {
+    cwd?: string;
+    configPath?: string;
+    /** Path to the candidate theme (`.ts` / `.mjs` / `.js` default-export, or `.json`). */
+    candidatePath: string;
+    /** CI gate: fail if more than this many classes changed. */
+    maxClassChanges?: number;
+    /** CI gate: fail if more than this many tokens changed. */
+    maxTokenChanges?: number;
+    /** CI gate: fail if any pairing's `after` level drops below this WCAG bar. */
+    failBelow?: string;
+}
+export interface TargetStatus {
+    name: string;
+    ok: boolean;
+    errors: string[];
+}
+export interface DiffCommandResult {
+    configPath: string;
+    candidatePath: string;
+    diff: ThemeDiff;
+    /** Per configured target: does the candidate still build? */
+    targets: TargetStatus[];
+    /** CI-gate verdict: false when any threshold was breached (or a target stopped building). */
+    ok: boolean;
+    violations: string[];
+}
+export declare function runDiff(options: DiffCommandOptions): Promise<DiffCommandResult>;

package/dist/build/emit.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `resolveEmitPlan` — normalize the authored `Emit` directive into a discriminated `NormalizedEmit`
+ * with every default filled (§9, 9a). This is the build layer's light normalization; the *vocabulary*
+ * (`Emit`/`NormalizedEmit`) lives in core (`src/core/ThemeAdapter.ts`), and each adapter decides which
+ * modes it actually honors — `resolveEmitPlan` never renders anything.
+ *
+ * Discriminator inference (only `single`/`split` may omit `type`):
+ *  - `undefined` / `{}` / `{ file }`        → `single`   (`file` renames the one file; default theme.css)
+ *  - the `variables` key present            → `split`    (that key is what tips `{ file, variables }` in)
+ *  - `subsystem` / `components`             → require an explicit `type` (or the string shorthand)
+ *
+ * Per-type filename/name defaults:
+ *  - single    → `theme.css`
+ *  - split     → `styles.css` + `variables.css`
+ *  - subsystem → `<sub>.css` / `<sub>.variables.css`
+ *  - components→ `${group}-${variant}.css`, `inline: true`, `variables` on (a filename)
+ */
+import type { Emit, NormalizedEmit } from "../core/ThemeAdapter";
+/** Normalize an authored {@link Emit} directive into a fully-defaulted {@link NormalizedEmit}. */
+export declare function resolveEmitPlan(emit: Emit): NormalizedEmit;

package/dist/build/emitTheme.d.ts

@@ -0,0 +1,39 @@
+import type { ThemeAdapter, Emit } from "../core/ThemeAdapter";
+import type { RawTheme } from "../core/rawTheme";
+import type { MediaConfig } from "../core/media";
+import type { UnitsConfig } from "../core/units";
+/** Opt-in self-documenting output config (§C). `true` uses defaults; the object tunes names/overlay. */
+export type GuideConfig = {
+    /** Published package specifier — adds a by-specifier import overlay to the guide (else relative-only). */
+    readonly packageName?: string;
+    /** Narrative guide filename (default `"llms.txt"`). */
+    readonly llmsFile?: string;
+    /** Machine index filename (default `"manifest.json"`); `false` suppresses it. */
+    readonly manifestFile?: string | false;
+};
+export interface EmitThemeOptions {
+    /** The raw theme config (same shape `createTheme` consumes). */
+    readonly raw: RawTheme;
+    /** The fully-constructed adapter object (`createCssAdapter(...)`, an SC adapter, …). */
+    readonly adapter: ThemeAdapter;
+    /** Directory to write the emitted files into (created recursively). */
+    readonly outDir: string;
+    /** Shared vendorable helper ids to materialize from `VENDOR_HELPERS` (e.g. `["color-math"]`). */
+    readonly helpers?: readonly string[];
+    /** Output-shape directive (§9); normalized to a plan and passed to the adapter's `emit(plan)`. */
+    readonly emit?: Emit;
+    /** Media unit config (§10.5) — threaded into `createTheme` + the emit rebind so em/rem reaches disk. */
+    readonly media?: MediaConfig;
+    /** Declaration-value length units (§21) — threaded into `createTheme` so built output honors the role map. */
+    readonly units?: UnitsConfig;
+    /** Divisor when a deferred length resolves to `rem` (§21). Defaults to 16. */
+    readonly baseFontSize?: number;
+    /** §C — emit a self-documenting `llms.txt` + `manifest.json` into `outDir`. Off by default. */
+    readonly guide?: boolean | GuideConfig;
+}
+export interface EmitThemeResult {
+    readonly outDir: string;
+    /** Absolute paths of every file written, in write order. */
+    readonly files: string[];
+}
+export declare function emitTheme(options: EmitThemeOptions): Promise<EmitThemeResult>;

package/dist/build/guide.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Self-documenting theme output (Node-only) — render an `llms.txt` consumption guide + a
+ * `manifest.json` index from an adapter's {@link UsageDescriptor} and a DTCG token export.
+ *
+ * The point: a theme built by refract is often shipped onward as a published package, a zip / CI
+ * artifact, or a vendored folder to developers who have **neither refract nor its skills** (and may
+ * not know refract exists). These two files travel *inside* `outDir`, so they accompany any
+ * distribution form, and they name the theme's REAL class names / export ids / token paths — a
+ * downstream agent consumes the theme from the folder alone, never guessing an identifier.
+ *
+ * Distribution-agnostic by construction: references are **relative** by default (`./theme.css`); the
+ * `@scope/name` import form is added only as an overlay when a package name is configured (a zip has
+ * no package specifier, so it must not be assumed).
+ */
+import type { UsageDescriptor } from "../core/ThemeAdapter";
+export interface GuideOptions {
+    /** The static file names emitted for this target (relative), so the guide points at real artifacts. */
+    readonly files: readonly string[];
+    /** The published package specifier, if any — adds an import-by-specifier overlay to the prose. */
+    readonly packageName?: string;
+    /** Output name for the narrative guide (default `"llms.txt"`). */
+    readonly llmsFile?: string;
+    /** Output name for the machine index (default `"manifest.json"`); `false` suppresses it. */
+    readonly manifestFile?: string | false;
+}
+export interface GuideOutput {
+    /** filename → contents, ready for the build layer to write into `outDir`. */
+    readonly files: Record<string, string>;
+}
+/**
+ * Build the guide artifacts. `tokens` is a DTCG document (from `toDTCG`) embedded verbatim into the
+ * manifest so the machine index carries every token path + value beside the recipe identities.
+ */
+export declare function buildGuide(descriptor: UsageDescriptor, tokens: unknown, options: GuideOptions): GuideOutput;

package/dist/build/importCommand.d.ts

@@ -0,0 +1,42 @@
+export interface ImportOptions {
+    /** Project dir to scaffold into (default `process.cwd()`). */
+    readonly cwd?: string;
+    /** Path to the DTCG `tokens.json` to import (relative to cwd or absolute). Required. */
+    readonly input: string;
+    /** `--out` — the raw-theme file to write (default `theme.raw.ts`, resolved against cwd). */
+    readonly out?: string;
+    /** `--raw-only` — write only `theme.raw.ts`, skip the companion `theme.config.ts` (default false). */
+    readonly rawOnly?: boolean;
+    /** `--force` — overwrite existing files instead of refusing (default false). */
+    readonly force?: boolean;
+    /** `--breakpoint-group` — DTCG group whose dimension tokens seed the breakpoints. */
+    readonly breakpointGroup?: string;
+    /** `--breakpoints` — explicit `{ name: px }` fallback when the doc carries no breakpoint group. */
+    readonly breakpoints?: Record<string, number>;
+    /** Package name the generated files import from (default: this package's own `name`). */
+    readonly packageName?: string;
+}
+export interface ImportResult {
+    /** Absolute path of the DTCG document read. */
+    readonly inputFile: string;
+    /** Absolute path of the written `theme.raw.ts`. */
+    readonly rawFile: string;
+    /** Absolute path of the written `theme.config.ts`, or `undefined` when `--raw-only`. */
+    readonly configFile?: string;
+    /** Top-level raw keys produced (e.g. `["breakpoints", "colors", "typography"]`). */
+    readonly sections: readonly string[];
+    /** Per-subsystem property count seeded from the document (excludes `breakpoints`). */
+    readonly counts: Readonly<Record<string, number>>;
+}
+/** Parse a `--breakpoints "sm:576,md:768"` flag into `{ sm: 576, md: 768 }`. Ignores malformed pairs. */
+export declare function parseBreakpointsFlag(spec: string): Record<string, number>;
+/** The generated `theme.raw.ts` body — a typed `RawTheme` the user then owns and extends. */
+export declare function scaffoldRaw(packageName: string, raw: unknown, sourceLabel: string): string;
+/** The generated companion `theme.config.ts` — a runnable build config importing the seeded raw. */
+export declare function scaffoldImportConfig(packageName: string, rawImportSpec: string): string;
+/**
+ * Read the DTCG document at `input`, convert it via `fromDTCG`, and write a `theme.raw.ts` (plus, unless
+ * `rawOnly`, a companion `theme.config.ts`) into `cwd`. Returns a summary of what was seeded. Throws on a
+ * missing/unparseable input or when an output file exists and `force` is not set (never clobbers).
+ */
+export declare function runImport(options: ImportOptions): ImportResult;

package/dist/build/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Build-time layer barrel (Node-only) — `emitTheme` + config plumbing + the vendor registry.
+ *
+ * Deliberately NOT re-exported from the runtime `.` barrel (`src/index.ts`): it imports `node:fs`
+ * + `typescript` and belongs to the build/CLI surface (surfaced via a `./build` subpath + `bin` in
+ * Step 10e). Nothing here is on the runtime graph.
+ */
+export * from "./vendor";
+export * from "./paths";
+export * from "./guide";
+export * from "./emitTheme";
+export * from "./emit";
+export * from "./config";
+export * from "./init";
+export * from "./importCommand";
+export * from "./buildCommand";
+export * from "./tokensCommand";
+export * from "./auditCommand";
+export * from "./diff";
+export * from "./diffCommand";
+export * from "./skillsCommand";
+/** The `refract` bin's `main(argv)` dispatch — exposed so the CLI is testable without spawning a process
+ *  (the module's entry-guard means importing it here never triggers a run). */
+export { main } from "./cli";
+/**
+ * Re-export the authoring types (§8c) so a config author gets `defineConfig` + `RawTheme` from ONE
+ * `/build` import — `import { defineConfig, type RawTheme } from "…/build"` — to type a separate
+ * `theme.raw.ts` the graph loader now compiles (§8b). Type-only: no runtime edge, boundary-safe.
+ */
+export type { RawTheme } from "../core";
+/** The output-shape vocabulary (§9) — config authors use it in `defineConfig` target `emit` fields. */
+export type { Emit } from "../core";
+export type { ColorsRaw, TypographyRaw, EffectsRaw, LayoutRaw, ComponentsRaw, } from "../subsystems";

package/dist/build/init.d.ts

@@ -0,0 +1,32 @@
+export type ConfigVariant = "ts" | "js" | "mjs";
+/**
+ * The sibling package the CSS adapter ships from post monorepo split. `defineConfig`/`RawTheme` still
+ * come from core (`${packageName}/build`); only the adapter itself moved to its own package.
+ */
+export declare const CSS_ADAPTER_PACKAGE = "@theme-registry/refract-css";
+export interface InitOptions {
+    /** Project dir to scaffold into (default `process.cwd()`). */
+    readonly cwd?: string;
+    /** Which config flavor to write (default `"ts"`). */
+    readonly variant?: ConfigVariant;
+    /** Overwrite an existing config instead of refusing (default `false`). */
+    readonly force?: boolean;
+    /** Package name to import from in the scaffold (default: this package's own `name`). */
+    readonly packageName?: string;
+}
+export interface InitResult {
+    /** Absolute path of the written config. */
+    readonly path: string;
+    readonly variant: ConfigVariant;
+    /** The package name the scaffold imports from. */
+    readonly packageName: string;
+}
+/** Read this package's own `name` (so the scaffold imports the currently-installed package name). */
+export declare function readOwnPackageName(): string;
+/** The scaffolded config body — one shared ESM template across ts/js/mjs. */
+export declare function scaffoldConfig(packageName: string): string;
+/**
+ * Scaffold `theme.config.<variant>` into `cwd`. Throws if the file exists and `force` is not set
+ * (never silently clobbers a user's config).
+ */
+export declare function runInit(options?: InitOptions): InitResult;