@astryxdesign/core 0.1.4 → 0.1.5-canary.76e6697

package/dist/theme/Theme.js

@@ -48,7 +48,7 @@ import { ThemeContext } from "./useTheme.js";
 /**
  * Theme provider props
  */
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsxDEV as _jsxDEV } from "react/jsx-dev-runtime";
 /**
  * Styles for the theme wrapper
  */
@@ -238,17 +238,17 @@ export function Theme({
     theme,
     mode
   }), [theme, mode]);
-  return /*#__PURE__*/_jsx(ThemeContext, {
+  return /*#__PURE__*/_jsxDEV(ThemeContext, {
     value: ctxValue,
-    children: /*#__PURE__*/_jsx(ThemeNestingContext, {
+    children: /*#__PURE__*/_jsxDEV(ThemeNestingContext, {
       value: true,
-      children: /*#__PURE__*/_jsx("div", {
+      children: /*#__PURE__*/_jsxDEV("div", {
         ...stylex.props(wrapperStyles.base, colorSchemeStyle),
         "data-astryx-theme": theme.name,
         "data-theme": mode === 'system' ? undefined : mode,
         children: children
-      })
-    })
-  });
+      }, void 0, false)
+    }, void 0, false)
+  }, void 0, false);
 }
 Theme.displayName = 'Theme';

package/dist/theme/defineTheme.d.ts

@@ -228,7 +228,7 @@ export interface DefineThemeInput {
     /**
      * Default syntax highlighting theme for code components.
      * Sets --color-syntax-* tokens at the theme root. Can be overridden
-     * per-region via SyntaxTheme or per-instance via syntaxTheme prop.
+     * per-region (or per-instance) by wrapping in SyntaxTheme.
      *
      * @example
      * ```tsx

package/dist/theme/defineTheme.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"defineTheme.d.ts","sourceRoot":"","sources":["../../src/theme/defineTheme.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,4BAA4B,CAAC;AAC7D,OAAO,KAAK,EAAC,gBAAgB,EAAa,MAAM,SAAS,CAAC;AAC1D,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACrB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,aAAa,EACb,eAAe,EACf,YAAY,EACZ,cAAc,EACd,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EAClB,MAAM,iBAAiB,CAAC;AAMzB,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAmB,KAAK,gBAAgB,EAAC,MAAM,oBAAoB,CAAC;AAE3E,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,gBAAgB,CAAC;AAEpD,OAAO,KAAK,EAAC,qBAAqB,EAAC,MAAM,UAAU,CAAC;AAMpD,wCAAwC;AACxC,MAAM,MAAM,aAAa,GACrB,MAAM,OAAO,aAAa,GAC1B,MAAM,OAAO,eAAe,GAC5B,MAAM,OAAO,YAAY,GACzB,MAAM,OAAO,cAAc,GAC3B,MAAM,OAAO,cAAc,GAC3B,MAAM,OAAO,gBAAgB,GAC7B,MAAM,OAAO,YAAY,GACzB,MAAM,OAAO,kBAAkB,GAC/B,MAAM,OAAO,kBAAkB,GAC/B,MAAM,OAAO,gBAAgB,GAC7B,MAAM,OAAO,kBAAkB,GAC/B,MAAM,OAAO,iBAAiB,CAAC;AAEnC,0DAA0D;AAC1D,MAAM,MAAM,SAAS,GAAG,aAAa,GAAG,eAAe,CAAC;AAExD;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;AAEhE;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;AAE7E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,CACpC,MAAM,EACN,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAC/B,CAAC;AAEF,2BAA2B;AAC3B,MAAM,WAAW,gBAAgB;IAC/B,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB;;;;;;;;;;;;;;;;;;OAkBG;IACH,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB;;4EAEwE;IACxE,MAAM,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC,CAAC;IAChD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAC/B,8DAA8D;IAC9D,KAAK,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;IAC9B;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE,qBAAqB,CAAC;IAC/B;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B;;;OAGG;IACH,OAAO,CAAC,EAAE,gBAAgB,CAAC;CAC5B;AAED,iDAAiD;AACjD,MAAM,WAAW,YAAY;IAC3B,iBAAiB;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,gCAAgC;IAChC,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAC/B,oBAAoB;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;IAC9B,kEAAkE;IAClE,OAAO,CAAC,EAAE,IAAI,CAAC;IACf;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC;IACpD;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B;;;OAGG;IACH,SAAS,CAAC,EAAE,eAAe,CAAC;CAC7B;AAMD,qFAAqF;AACrF,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAchD,CAAC;AA6FF;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,YAAY,CA8JjE;AAMD,OAAO,EACL,kBAAkB,EAClB,uBAAuB,EACvB,kBAAkB,EAClB,gBAAgB,EAChB,oBAAoB,EACpB,KAAK,eAAe,EACpB,KAAK,cAAc,GACpB,MAAM,sBAAsB,CAAC;AAM9B,2DAA2D;AAC3D,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAQpE"}
+{"version":3,"file":"defineTheme.d.ts","sourceRoot":"","sources":["../../src/theme/defineTheme.ts"],"names":[],"mappings":"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"}

package/dist/theme/expandColorScale.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"expandColorScale.d.ts","sourceRoot":"","sources":["../../src/theme/expandColorScale.ts"],"names":[],"mappings":"AAuBA;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,gBAAgB;IAC/B,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC;IAEf;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAE3C;;;OAGG;IACH,QAAQ,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC;CAChC;AAED,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AA0BtD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,gBAAgB,GACvB,gBAAgB,CAiFlB"}
+{"version":3,"file":"expandColorScale.d.ts","sourceRoot":"","sources":["../../src/theme/expandColorScale.ts"],"names":[],"mappings":"AAuBA;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,gBAAgB;IAC/B,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC;IAEf;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAE3C;;;OAGG;IACH,QAAQ,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC;CAChC;AAED,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AA8BtD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,gBAAgB,GACvB,gBAAgB,CAkFlB"}

package/dist/theme/expandColorScale.js

@@ -56,6 +56,9 @@ const NEUTRAL_VARIANT_CHROMA = {
 function ld(light, dark) {
   return `light-dark(${light}, ${dark})`;
 }
+function accentWithAlpha(alpha) {
+  return `color-mix(in srgb, var(--color-accent) ${alpha * 100}%, transparent)`;
+}
 
 /**
  * Expand a color scale config into Astryx color token overrides.
@@ -93,7 +96,11 @@ export function expandColorScale(config) {
   return {
     // Core semantic
     '--color-accent': ld(P[40], P[80]),
-    '--color-accent-muted': ld(hexWithAlpha(P[40], 0.2), hexWithAlpha(P[80], 0.25)),
+    // Derived accent tokens reference --color-accent instead of baking its
+    // resolved hex, so a scoped override of the base token re-accents the
+    // whole subtree at runtime. --color-on-accent stays baked: it is a
+    // contrast computation against the accent, which CSS cannot express.
+    '--color-accent-muted': ld(accentWithAlpha(0.2), accentWithAlpha(0.25)),
     '--color-on-accent': ld(P[100], P[20]),
     '--color-neutral': ld(hexWithAlpha(N[10], 0.1), hexWithAlpha(N[90], 0.2)),
     '--color-background-surface': ld(N[99], N[10]),
@@ -106,9 +113,9 @@ export function expandColorScale(config) {
     '--color-text-primary': ld(N[textPrimaryLightTone], N[textPrimaryDarkTone]),
     '--color-text-secondary': ld(NV[textSecondaryLightTone], NV[textSecondaryDarkTone]),
     '--color-text-disabled': ld(NV[60], NV[40]),
-    '--color-text-accent': ld(P[30], P[80]),
+    '--color-text-accent': 'var(--color-accent)',
     // Icon
-    '--color-icon-accent': ld(P[40], P[80]),
+    '--color-icon-accent': 'var(--color-accent)',
     '--color-icon-primary': ld(N[textPrimaryLightTone], N[textPrimaryDarkTone]),
     '--color-icon-secondary': ld(NV[textSecondaryLightTone], NV[textSecondaryDarkTone]),
     '--color-icon-disabled': ld(NV[60], NV[40]),

package/dist/theme/hct.d.ts

@@ -1,18 +1,3 @@
-/**
- * @file hct.ts
- * @input Hex color string (#RRGGBB)
- * @output HCT color representation (Hue, Chroma, Tone)
- * @position Theme utility; consumed by expandColorScale.ts
- *
- * Minimal HCT (Hue, Chroma, Tone) color space implementation.
- * Ported from Google's material-color-utilities (Apache-2.0).
- * Zero runtime dependencies — all math is self-contained.
- *
- * HCT combines:
- * - Hue from CIELab (perceptually uniform hue)
- * - Chroma approximated via CIELab C*ab (colorfulness)
- * - Tone from L* (CIE Lightness, 0=black, 100=white)
- */
 export interface HCT {
     hue: number;
     chroma: number;

package/dist/theme/hct.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hct.d.ts","sourceRoot":"","sources":["../../src/theme/hct.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AAMH,MAAM,WAAW,GAAG;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAoFD,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEzC;AA4BD;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAkBzC;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CA8BzC;AAkDD;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,GACb,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMxB;AAMD;;GAEG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAM/D"}
+{"version":3,"file":"hct.d.ts","sourceRoot":"","sources":["../../src/theme/hct.ts"],"names":[],"mappings":"AAwBA,MAAM,WAAW,GAAG;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAoFD,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEzC;AAkBD;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAkBzC;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CA8BzC;AAkDD;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,GACb,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMxB;AAMD;;GAEG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAM/D"}

package/dist/theme/hct.js

@@ -16,6 +16,8 @@
  * - Tone from L* (CIE Lightness, 0=black, 100=white)
  */
 
+import { parseHex, formatHex } from "../utils/color.js";
+
 // =============================================================================
 // Types
 // =============================================================================
@@ -86,13 +88,11 @@ export function yToTone(y) {
 // =============================================================================
 
 function hexToRgb(hex) {
-  const h = hex.replace('#', '');
-  const full = h.length === 3 ? h[0] + h[0] + h[1] + h[1] + h[2] + h[2] : h.slice(0, 6);
-  const n = parseInt(full, 16);
-  return [n >> 16 & 0xff, n >> 8 & 0xff, n & 0xff];
-}
-function rgbToHex(r, g, b) {
-  return '#' + [r, g, b].map(c => c.toString(16).padStart(2, '0')).join('').toUpperCase();
+  const parsed = parseHex(hex);
+  if (parsed === null) {
+    return [0, 0, 0];
+  }
+  return [parsed.r, parsed.g, parsed.b];
 }
 
 // =============================================================================
@@ -142,7 +142,7 @@ export function hctToHex(hct) {
   }
   if (chroma < 0.5) {
     const gray = toneToGray(tone);
-    return rgbToHex(gray, gray, gray);
+    return formatHex(gray, gray, gray);
   }
   let lo = 0;
   let hi = chroma;
@@ -183,7 +183,7 @@ function hctComponentToHex(hue, chroma, tone) {
   if (r < 0 || r > 255 || g < 0 || g > 255 || bVal < 0 || bVal > 255) {
     return null;
   }
-  return rgbToHex(r, g, bVal);
+  return formatHex(r, g, bVal);
 }
 
 // =============================================================================

package/dist/theme/syntax/SyntaxTheme.js

@@ -19,7 +19,7 @@ import { useMediaQuery } from "../../hooks/useMediaQuery.js";
 // =============================================================================
 
 /** @internal */
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsxDEV as _jsxDEV } from "react/jsx-dev-runtime";
 const SyntaxThemeContext = /*#__PURE__*/createContext(null);
 SyntaxThemeContext.displayName = 'SyntaxThemeContext';
 
@@ -85,13 +85,13 @@ export function SyntaxTheme({
   const value = useMemo(() => ({
     theme
   }), [theme]);
-  return /*#__PURE__*/_jsx(SyntaxThemeContext, {
+  return /*#__PURE__*/_jsxDEV(SyntaxThemeContext, {
     value: value,
-    children: /*#__PURE__*/_jsx("div", {
+    children: /*#__PURE__*/_jsxDEV("div", {
       style: style,
       "data-astryx-syntax-theme": theme.name,
       children: children
-    })
-  });
+    }, void 0, false)
+  }, void 0, false);
 }
 SyntaxTheme.displayName = 'SyntaxTheme';

package/dist/theme/tokens.d.ts

@@ -8,6 +8,11 @@
  * build-time theme adapters, chart configuration, canvas/SVG rendering, tests,
  * or plain JS theme objects for other styling libraries.
  *
+ * Derived tokens can reference other tokens (`var(--color-accent)`) and use CSS
+ * color functions (`color-mix`). The resolver follows those references through
+ * the theme iteratively and evaluates the supported color functions so callers
+ * receive concrete raw values, not CSS expressions.
+ *
  * SYNC: When modified, update:
  * - /packages/core/src/theme/useTheme.ts
  * - /packages/core/src/theme/index.ts
@@ -51,8 +56,11 @@ export declare const tokenVars: Record<TokenName, string>;
  * The result starts with `tokenDefaults`, applies `theme.tokens`, then
  * reapplies `theme.__inputTokens` when available so explicit tuple overrides
  * retain their original light/dark sides instead of relying on CSS parsing.
- * This mirrors the token resolution used by `useTheme()` but does not need
- * React context or media queries.
+ * A final pass resolves any `var()` references between tokens and evaluates
+ * the CSS color functions the theme generator emits (e.g. `color-mix`), so
+ * derived tokens like `--color-text-accent` return concrete values rather than
+ * `var(--color-accent)`. This mirrors the token resolution used by
+ * `useTheme()` but does not need React context or media queries.
  *
  * Pass `theme` as null/undefined to resolve defaults only.
  */

package/dist/theme/tokens.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../src/theme/tokens.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,SAAS,EAEf,MAAM,eAAe,CAAC;AAEvB,kFAAkF;AAClF,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,MAAM,CAAC;AAEjD,4DAA4D;AAC5D,MAAM,WAAW,yBAAyB;IACxC,kGAAkG;IAClG,IAAI,EAAE,iBAAiB,CAAC;CACzB;AAED,2DAA2D;AAC3D,MAAM,WAAW,wBAAyB,SAAQ,yBAAyB;IACzE,mFAAmF;IACnF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,GAAG,MAAM,CAEhE;AAED,sFAAsF;AACtF,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAElB,CAAC;AAmF/B;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,YAAY,GAAG,IAAI,GAAG,SAAS,EACtC,OAAO,EAAE,yBAAyB,GACjC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAyBxB;AAED,2EAA2E;AAC3E,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,YAAY,GAAG,IAAI,GAAG,SAAS,EACtC,IAAI,EAAE,SAAS,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,EAC/B,OAAO,EAAE,wBAAwB,GAChC,MAAM,CAGR"}
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../src/theme/tokens.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,SAAS,EAEf,MAAM,eAAe,CAAC;AAGvB,kFAAkF;AAClF,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,MAAM,CAAC;AAEjD,4DAA4D;AAC5D,MAAM,WAAW,yBAAyB;IACxC,kGAAkG;IAClG,IAAI,EAAE,iBAAiB,CAAC;CACzB;AAED,2DAA2D;AAC3D,MAAM,WAAW,wBAAyB,SAAQ,yBAAyB;IACzE,mFAAmF;IACnF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,GAAG,MAAM,CAEhE;AAED,sFAAsF;AACtF,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAElB,CAAC;AAqT/B;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,YAAY,GAAG,IAAI,GAAG,SAAS,EACtC,OAAO,EAAE,yBAAyB,GACjC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAyBxB;AAED,2EAA2E;AAC3E,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,YAAY,GAAG,IAAI,GAAG,SAAS,EACtC,IAAI,EAAE,SAAS,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,EAC/B,OAAO,EAAE,wBAAwB,GAChC,MAAM,CAGR"}

package/dist/theme/tokens.js

@@ -10,12 +10,18 @@
  * build-time theme adapters, chart configuration, canvas/SVG rendering, tests,
  * or plain JS theme objects for other styling libraries.
  *
+ * Derived tokens can reference other tokens (`var(--color-accent)`) and use CSS
+ * color functions (`color-mix`). The resolver follows those references through
+ * the theme iteratively and evaluates the supported color functions so callers
+ * receive concrete raw values, not CSS expressions.
+ *
  * SYNC: When modified, update:
  * - /packages/core/src/theme/useTheme.ts
  * - /packages/core/src/theme/index.ts
  */
 
 import { tokenDefaults } from "./defineTheme.js";
+import { parseColor, formatColor } from "../utils/color.js";
 
 /** Resolved color mode used when choosing the side of light/dark token values. */
 
@@ -115,14 +121,224 @@ function resolveXDSTokenValue(value, mode) {
   return value;
 }
 
+// =============================================================================
+// Reference resolution — turn token expressions into concrete raw values
+// =============================================================================
+//
+// Generated themes emit derived tokens as references to other tokens rather
+// than baked-in values, so a scoped CSS override of a base token re-themes the
+// subtree that references it. The CSS cascade resolves those references, but
+// non-CSS consumers (canvas, SVG, data-viz) need the concrete value. These
+// helpers replay the same resolution in JS: follow `var()` references through
+// the resolved token map (iteratively, guarding against cycles) and evaluate
+// the CSS color functions used by the theme generator against those values.
+
+/** Index of the `)` matching the `(` at `openIndex`, or -1 when unbalanced. */
+function findMatchingParen(input, openIndex) {
+  let depth = 0;
+  for (let i = openIndex; i < input.length; i++) {
+    const char = input[i];
+    if (char === '(') {
+      depth++;
+    } else if (char === ')') {
+      depth--;
+      if (depth === 0) {
+        return i;
+      }
+    }
+  }
+  return -1;
+}
+
+/** Split a color-mix component into its color and optional percentage. */
+function parseMixComponent(part) {
+  const trimmed = part.trim();
+  const match = trimmed.match(/\s+([\d.]+)%$/);
+  if (match) {
+    return {
+      color: trimmed.slice(0, match.index).trim(),
+      percentage: parseFloat(match[1])
+    };
+  }
+  return {
+    color: trimmed,
+    percentage: null
+  };
+}
+
+/**
+ * Evaluate `color-mix(in <space>, c1 [p1], c2 [p2])` to a concrete color.
+ *
+ * Supports the `srgb` color space (the one the theme generator emits) using
+ * the CSS Color 5 algorithm: normalize the percentages, interpolate the
+ * premultiplied channels, then apply the alpha multiplier when the mix weights
+ * sum to less than 100%. Returns null for anything it can't evaluate so the
+ * original expression is preserved rather than guessed.
+ */
+function evaluateColorMix(body) {
+  const spaceMatch = body.match(/^in\s+([\w-]+)\s*,\s*(.+)$/s);
+  if (!spaceMatch) {
+    return null;
+  }
+  const [, colorSpace, rest] = spaceMatch;
+  if (colorSpace.toLowerCase() !== 'srgb') {
+    return null;
+  }
+  const split = splitTopLevelComma(rest);
+  if (split === null) {
+    return null;
+  }
+  const first = parseMixComponent(split[0]);
+  const second = parseMixComponent(split[1]);
+  if (first === null || second === null) {
+    return null;
+  }
+  const c1 = parseColor(first.color);
+  const c2 = parseColor(second.color);
+  if (c1 === null || c2 === null) {
+    return null;
+  }
+
+  // Fill in omitted percentages, then normalize so they sum to 100%.
+  let p1;
+  let p2;
+  if (first.percentage !== null && second.percentage !== null) {
+    p1 = first.percentage;
+    p2 = second.percentage;
+  } else if (first.percentage !== null) {
+    p1 = first.percentage;
+    p2 = 100 - p1;
+  } else if (second.percentage !== null) {
+    p2 = second.percentage;
+    p1 = 100 - p2;
+  } else {
+    p1 = 50;
+    p2 = 50;
+  }
+  const sum = p1 + p2;
+  if (sum <= 0) {
+    return null;
+  }
+  const w1 = p1 / sum;
+  const w2 = p2 / sum;
+  const alphaMultiplier = sum < 100 ? sum / 100 : 1;
+
+  // Interpolate in premultiplied sRGB, then un-premultiply.
+  const mixedA = w1 * c1.a + w2 * c2.a;
+  const premix = (k1, k2) => w1 * k1 * c1.a + w2 * k2 * c2.a;
+  const rp = premix(c1.r, c2.r);
+  const gp = premix(c1.g, c2.g);
+  const bp = premix(c1.b, c2.b);
+  const rgb = mixedA === 0 ? {
+    r: 0,
+    g: 0,
+    b: 0
+  } : {
+    r: rp / mixedA,
+    g: gp / mixedA,
+    b: bp / mixedA
+  };
+  return formatColor({
+    ...rgb,
+    a: mixedA * alphaMultiplier
+  });
+}
+
+/** Evaluate every supported color function in an expression, innermost first. */
+function evaluateColorFunctions(expr) {
+  const idx = expr.indexOf('color-mix(');
+  if (idx === -1) {
+    return expr;
+  }
+  const openIndex = idx + 'color-mix'.length;
+  const closeIndex = findMatchingParen(expr, openIndex);
+  if (closeIndex === -1) {
+    return expr;
+  }
+  const body = evaluateColorFunctions(expr.slice(openIndex + 1, closeIndex));
+  const evaluated = evaluateColorMix(body);
+  const replacement = evaluated ?? `color-mix(${body})`;
+  return expr.slice(0, idx) + replacement + evaluateColorFunctions(expr.slice(closeIndex + 1));
+}
+
+/**
+ * Substitute `var(--name[, fallback])` references with their resolved values.
+ * `seen` tracks the reference chain so cycles resolve to the literal reference
+ * instead of recursing forever.
+ */
+function substituteVars(expr, raw, cache, seen) {
+  const start = expr.indexOf('var(');
+  if (start === -1) {
+    return expr;
+  }
+  const openIndex = start + 'var'.length;
+  const closeIndex = findMatchingParen(expr, openIndex);
+  if (closeIndex === -1) {
+    return expr;
+  }
+  const inner = expr.slice(openIndex + 1, closeIndex);
+  const commaSplit = splitTopLevelComma(inner);
+  const name = (commaSplit ? commaSplit[0] : inner).trim();
+  const fallback = commaSplit ? commaSplit[1] : null;
+  let replacement;
+  if (seen.has(name)) {
+    replacement = expr.slice(start, closeIndex + 1);
+  } else if (name in raw) {
+    seen.add(name);
+    replacement = resolveReference(name, raw, cache, seen);
+    seen.delete(name);
+  } else if (fallback !== null) {
+    replacement = substituteVars(fallback.trim(), raw, cache, seen);
+  } else {
+    replacement = expr.slice(start, closeIndex + 1);
+  }
+  const rest = substituteVars(expr.slice(closeIndex + 1), raw, cache, seen);
+  return expr.slice(0, start) + replacement + rest;
+}
+
+/** Fully resolve a single expression: substitute references, then evaluate colors. */
+function resolveExpression(expr, raw, cache, seen) {
+  if (!expr.includes('var(') && !expr.includes('color-mix(')) {
+    return expr;
+  }
+  const substituted = substituteVars(expr, raw, cache, seen);
+  return evaluateColorFunctions(substituted);
+}
+
+/** Resolve one token by name, memoizing the result in `cache`. */
+function resolveReference(name, raw, cache, seen) {
+  if (name in cache) {
+    return cache[name];
+  }
+  const value = raw[name];
+  if (value === undefined) {
+    return '';
+  }
+  const resolved = resolveExpression(value, raw, cache, seen);
+  cache[name] = resolved;
+  return resolved;
+}
+
+/** Resolve every reference/color function in a raw token map to concrete values. */
+function resolveReferences(raw) {
+  const cache = {};
+  for (const name of Object.keys(raw)) {
+    resolveReference(name, raw, cache, new Set());
+  }
+  return cache;
+}
+
 /**
  * Resolve all Astryx token values for a theme and effective color mode.
  *
  * The result starts with `tokenDefaults`, applies `theme.tokens`, then
  * reapplies `theme.__inputTokens` when available so explicit tuple overrides
  * retain their original light/dark sides instead of relying on CSS parsing.
- * This mirrors the token resolution used by `useTheme()` but does not need
- * React context or media queries.
+ * A final pass resolves any `var()` references between tokens and evaluates
+ * the CSS color functions the theme generator emits (e.g. `color-mix`), so
+ * derived tokens like `--color-text-accent` return concrete values rather than
+ * `var(--color-accent)`. This mirrors the token resolution used by
+ * `useTheme()` but does not need React context or media queries.
  *
  * Pass `theme` as null/undefined to resolve defaults only.
  */
@@ -135,7 +351,7 @@ export function resolveThemeTokens(theme, options) {
     resolved[key] = resolveXDSTokenValue(value, mode);
   }
   if (theme == null) {
-    return resolved;
+    return resolveReferences(resolved);
   }
   for (const [key, value] of Object.entries(theme.tokens)) {
     resolved[key] = resolveXDSTokenValue(value, mode);
@@ -147,7 +363,7 @@ export function resolveThemeTokens(theme, options) {
       }
     }
   }
-  return resolved;
+  return resolveReferences(resolved);
 }
 
 /** Resolve one Astryx token value for a theme and effective color mode. */

package/dist/theme/useTheme.d.ts

@@ -57,8 +57,9 @@ export interface UseThemeReturn {
  * (e.g. Vega, D3, Chart.js) that need concrete values rather than
  * CSS custom property references.
  *
- * When called outside an <Theme> provider, returns the default theme
- * tokens resolved against the current system color mode.
+ * When called outside a <Theme> provider, resolves mode from the root
+ * Theme's `<html data-theme>` when one is present, falling back to the
+ * current system color mode otherwise.
  *
  * @example
  * ```

package/dist/theme/useTheme.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useTheme.d.ts","sourceRoot":"","sources":["../../src/theme/useTheme.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,SAAS,CAAC;AACvC,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,eAAe,CAAC;AAQhD;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,+BAA+B;IAC/B,KAAK,EAAE,YAAY,CAAC;IACpB,0CAA0C;IAC1C,IAAI,EAAE,SAAS,CAAC;CACjB;AAED;;;;GAIG;AACH,eAAO,MAAM,YAAY,mDAAgD,CAAC;AAO1E;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,iBAAiB;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,IAAI,EAAE,OAAO,GAAG,MAAM,CAAC;IACvB;;;;;;;;;;;;;OAaG;IACH,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IAChC;;;;;;;OAOG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAMD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,QAAQ,IAAI,cAAc,CA4BzC"}
+{"version":3,"file":"useTheme.d.ts","sourceRoot":"","sources":["../../src/theme/useTheme.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,SAAS,CAAC;AACvC,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,eAAe,CAAC;AAQhD;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,+BAA+B;IAC/B,KAAK,EAAE,YAAY,CAAC;IACpB,0CAA0C;IAC1C,IAAI,EAAE,SAAS,CAAC;CACjB;AAED;;;;GAIG;AACH,eAAO,MAAM,YAAY,mDAAgD,CAAC;AAO1E;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,iBAAiB;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,IAAI,EAAE,OAAO,GAAG,MAAM,CAAC;IACvB;;;;;;;;;;;;;OAaG;IACH,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IAChC;;;;;;;OAOG;IACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AA4ED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,QAAQ,IAAI,cAAc,CAiCzC"}

package/dist/theme/useTheme.js

@@ -9,13 +9,18 @@
  * @position Theme hook; used by data viz, canvas, and non-CSS consumers
  *
  * Provides synchronous access to theme token values resolved for the
- * current color mode — no DOM reads, no double render. Token resolution
- * is shared with the server-safe helpers in ./tokens.ts.
+ * current color mode — no DOM reads on the provider path, no double render.
+ * Without a reachable ThemeContext it consults `<html data-theme>` (kept in
+ * sync by Theme) via a single shared, refcounted MutationObserver before
+ * assuming OS preference; provider-path consumers subscribe to a no-op
+ * store instead (the same args-switch technique useMediaQuery uses), so
+ * mounting under a Theme never creates an observer. Token resolution is
+ * shared with the server-safe helpers in ./tokens.ts.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/theme/index.ts
  */
-import { createContext, use, useMemo } from 'react';
+import { createContext, use, useMemo, useSyncExternalStore } from 'react';
 import { resolveThemeTokens } from "./tokens.js";
 import { useMediaQuery } from "../hooks/useMediaQuery.js";
 
@@ -48,6 +53,62 @@ ThemeContext.displayName = 'ThemeContext';
 // Hook
 // =============================================================================
 
+function getRootThemeAttrSnapshot() {
+  if (typeof document === 'undefined') {
+    return null;
+  }
+  const attr = document.documentElement.getAttribute('data-theme');
+  return attr === 'light' || attr === 'dark' ? attr : null;
+}
+function getRootThemeAttrServerSnapshot() {
+  return null;
+}
+function getNullThemeMode() {
+  return null;
+}
+
+// Every no-context consumer wants the same <html data-theme> attribute, so
+// one MutationObserver — refcounted via this listener set — serves all of
+// them instead of one per consumer.
+const rootThemeAttrListeners = new Set();
+let rootThemeAttrObserver = null;
+function notifyRootThemeAttrListeners() {
+  for (const listener of rootThemeAttrListeners) {
+    listener();
+  }
+}
+function subscribeRootThemeAttr(onStoreChange) {
+  rootThemeAttrListeners.add(onStoreChange);
+  if (rootThemeAttrListeners.size === 1 && typeof MutationObserver !== 'undefined') {
+    rootThemeAttrObserver = new MutationObserver(notifyRootThemeAttrListeners);
+    rootThemeAttrObserver.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: ['data-theme']
+    });
+  }
+  return () => {
+    rootThemeAttrListeners.delete(onStoreChange);
+    if (rootThemeAttrListeners.size === 0 && rootThemeAttrObserver) {
+      rootThemeAttrObserver.disconnect();
+      rootThemeAttrObserver = null;
+    }
+  };
+}
+function subscribeNoop() {
+  return () => {};
+}
+
+/**
+ * Reads the root Theme's mode off `<html data-theme>`, live via the shared
+ * MutationObserver. Null means no root Theme has synced it (none present,
+ * or mode is 'system'). `hasCtx` switches which store this subscribes to —
+ * a no-op store when a ThemeContext exists — instead of skipping the hook
+ * call, so provider-path consumers never touch the DOM or the observer.
+ */
+function useRootThemeModeAttr(hasCtx) {
+  return useSyncExternalStore(hasCtx ? subscribeNoop : subscribeRootThemeAttr, hasCtx ? getNullThemeMode : getRootThemeAttrSnapshot, getRootThemeAttrServerSnapshot);
+}
+
 /**
  * Access the current Astryx theme's token values, resolved for the active color mode.
  *
@@ -56,8 +117,9 @@ ThemeContext.displayName = 'ThemeContext';
  * (e.g. Vega, D3, Chart.js) that need concrete values rather than
  * CSS custom property references.
  *
- * When called outside an <Theme> provider, returns the default theme
- * tokens resolved against the current system color mode.
+ * When called outside a <Theme> provider, resolves mode from the root
+ * Theme's `<html data-theme>` when one is present, falling back to the
+ * current system color mode otherwise.
  *
  * @example
  * ```
@@ -75,9 +137,14 @@ ThemeContext.displayName = 'ThemeContext';
 export function useTheme() {
   const ctx = use(ThemeContext);
 
+  // Falls back to the root Theme's mode via <html data-theme> when there's
+  // no ThemeContext ancestor (e.g. useToast's detached fallback viewport).
+  // Resolves to null when `ctx` is present, so it has no effect there.
+  const rootAttrMode = useRootThemeModeAttr(ctx != null);
+
   // Resolve 'system' to 'light' | 'dark' using the OS preference
   const prefersDark = useMediaQuery('(prefers-color-scheme: dark)');
-  const mode = ctx?.mode ?? 'system';
+  const mode = ctx?.mode ?? rootAttrMode ?? 'system';
   const theme = ctx?.theme ?? null;
   const effectiveMode = mode === 'system' ? prefersDark ? 'dark' : 'light' : mode;