@oxyhq/bloom 0.7.7 → 0.8.0

package/src/theme/__tests__/color-space.test.ts

@@ -0,0 +1,28 @@
+import { oklchToSrgb, srgbToRgbString, parseRgbString, deltaE } from '../color-space';
+
+describe('color-space', () => {
+  it('converts oklch white/black correctly', () => {
+    expect(oklchToSrgb({ l: 1, c: 0, h: 0 })).toEqual({ r: 255, g: 255, b: 255 });
+    expect(oklchToSrgb({ l: 0, c: 0, h: 0 })).toEqual({ r: 0, g: 0, b: 0 });
+  });
+  it('round-trips a known oxy purple within ΔE 1', () => {
+    // hsl(277 66% 56%) === rgb(160 69 217) (current oracle)
+    const rgb = oklchToSrgb({ l: 0.5783, c: 0.22, h: 309.31 });
+    expect(deltaE(rgb, { r: 160, g: 69, b: 217 })).toBeLessThanOrEqual(1.0);
+  });
+  it('formats rgb as space-separated modern syntax', () => {
+    expect(srgbToRgbString({ r: 31, g: 153, b: 239 })).toBe('rgb(31 153 239)');
+    expect(srgbToRgbString({ r: 31, g: 153, b: 239 }, 0.1)).toBe('rgb(31 153 239 / 0.1)');
+  });
+  it('parses modern + legacy rgb strings', () => {
+    expect(parseRgbString('rgb(31 153 239)')).toEqual({ r: 31, g: 153, b: 239 });
+    expect(parseRgbString('rgb(31, 153, 239)')).toEqual({ r: 31, g: 153, b: 239 });
+  });
+  it('throws loudly on non-rgb input instead of silently returning black', () => {
+    expect(() => parseRgbString('277 50% 5%')).toThrow(
+      'parseRgbString: expected an rgb() string, got: 277 50% 5%',
+    );
+    expect(() => parseRgbString('hsl(277 50% 5%)')).toThrow(/expected an rgb\(\) string/);
+    expect(() => parseRgbString('')).toThrow(/expected an rgb\(\) string/);
+  });
+});

package/src/theme/__tests__/golden-tokens.test.ts

@@ -0,0 +1,33 @@
+import goldenResolvedTokens from './__fixtures__/golden-resolved-tokens.json';
+import { APP_COLOR_NAMES } from '../color-presets';
+import { getResolvedTokens } from '../token-registry';
+
+// `golden-resolved-tokens.json` is the FROZEN parity oracle: the exact resolved
+// rgb for every preset×mode×token that the legacy resolved-color pipeline
+// produced (captured once, each resolved-color key remapped to its base `--X`).
+// It is IMMUTABLE — never regenerate it to chase new output. These tests prove
+// the canonical `getResolvedTokens` pipeline reproduces that palette EXACTLY
+// (byte-for-byte rgb), so the refactor to a single rgb token pipeline does not
+// shift a single color.
+const fixture = goldenResolvedTokens as Record<string, Record<string, string>>;
+
+describe('golden token parity (frozen oracle)', () => {
+  for (const name of APP_COLOR_NAMES) {
+    for (const mode of ['light', 'dark'] as const) {
+      it(`${name}/${mode} resolves to the frozen rgb palette exactly`, () => {
+        const expected = fixture[`${name}/${mode}`];
+        expect(expected).toBeDefined();
+
+        const resolved = getResolvedTokens(name, mode);
+        // For every token the oracle ever resolved, the canonical pipeline must
+        // produce the identical rgb string. (The fixture covers exactly the keys
+        // that had a resolved-color companion; extended-only tokens —
+        // chart-*/sidebar-*/content-area — were never in the rgb oracle and are
+        // covered by the canonical-token coverage test instead.)
+        const actual: Record<string, string | undefined> = {};
+        for (const key of Object.keys(expected ?? {})) actual[key] = resolved[key];
+        expect(actual).toEqual(expected);
+      });
+    }
+  }
+});

package/src/theme/__tests__/runtime-contract.test.ts

@@ -0,0 +1,49 @@
+/**
+ * @jest-environment jsdom
+ */
+
+import normalizeColor from '@react-native/normalize-colors';
+import { Platform } from 'react-native';
+
+import { buildTheme } from '../build-theme';
+import { applyColorPresetVars } from '../apply-dark-class';
+
+// `@react-native/normalize-colors` is the exact parser React Native (native) and
+// react-native-web use behind `StyleSheet`/`processColor`. If it returns `null`
+// for a value, that color is UNPARSEABLE and the element renders nothing. These
+// tests pin the runtime contract for the canonical rgb token pipeline: every
+// JS `theme.colors` value must parse, the web document vars must be full colors
+// (not bare HSL triples), and the historically mislabeled aliases must be fixed.
+
+it('every theme.colors value parses via normalize-colors (native/RNW StyleSheet)', () => {
+  const { colors } = buildTheme('oxy', 'dark');
+  for (const v of Object.values(colors)) {
+    expect(normalizeColor(v)).not.toBeNull(); // null = unparseable -> renders nothing
+  }
+});
+
+describe('web var(--primary) resolves to a real color (not a bare triple)', () => {
+  const originalOS = Platform.OS;
+
+  beforeEach(() => {
+    Platform.OS = 'web';
+    document.documentElement.removeAttribute('style');
+  });
+
+  afterEach(() => {
+    Platform.OS = originalOS;
+    document.documentElement.removeAttribute('style');
+  });
+
+  it('writes --primary as a resolved rgb() color', () => {
+    applyColorPresetVars('oxy', 'dark');
+    const v = document.documentElement.style.getPropertyValue('--primary').trim();
+    expect(v).toMatch(/^rgb\(/);
+    expect(normalizeColor(v)).not.toBeNull();
+  });
+});
+
+it('mislabeled aliases are fixed: secondary !== primary', () => {
+  const { colors } = buildTheme('oxy', 'light');
+  expect(colors.secondary).not.toBe(colors.primary);
+});

package/src/theme/__tests__/token-registry.test.ts

@@ -0,0 +1,30 @@
+import goldenResolvedTokens from './__fixtures__/golden-resolved-tokens.json';
+import { CANONICAL_TOKENS, getResolvedTokens } from '../token-registry';
+import { APP_COLOR_NAMES } from '../color-presets';
+import { getPresetVars } from '../preset-vars';
+
+const fixture = goldenResolvedTokens as Record<string, Record<string, string>>;
+
+it('canonical token list covers every base+extended preset var', () => {
+  const fromPreset = Object.keys(getPresetVars('oxy', 'light'));
+  for (const k of fromPreset) expect(CANONICAL_TOKENS).toContain(k.replace(/^--/, ''));
+});
+
+describe('getResolvedTokens parity vs frozen oracle (exact rgb)', () => {
+  for (const name of APP_COLOR_NAMES) {
+    for (const mode of ['light', 'dark'] as const) {
+      it(`${name}/${mode}`, () => {
+        const oracle = fixture[`${name}/${mode}`];
+        expect(oracle).toBeDefined();
+
+        const resolved = getResolvedTokens(name, mode); // Record<'--x','rgb(...)'>
+        for (const [base, oracleRgb] of Object.entries(oracle ?? {})) {
+          expect(resolved[base]).toBeDefined();
+          // Exact match — the canonical pipeline reproduces the legacy
+          // resolved-color rgb byte-for-byte, so there is no palette drift.
+          expect(resolved[base]).toBe(oracleRgb);
+        }
+      });
+    }
+  }
+});

package/src/theme/__tests__/visual-gallery.test.tsx

@@ -0,0 +1,10 @@
+import { buildTheme } from '../build-theme';
+import { APP_COLOR_NAMES } from '../color-presets';
+
+it('theme.colors snapshot for all presets (catches unintended palette shifts)', () => {
+  const all = Object.fromEntries(
+    APP_COLOR_NAMES.flatMap((n) => (['light', 'dark'] as const).map(
+      (m) => [`${n}/${m}`, buildTheme(n, m).colors] as const)),
+  );
+  expect(all).toMatchSnapshot();
+});

package/src/theme/apply-dark-class.ts

@@ -1,11 +1,6 @@
 import { Platform } from 'react-native';
 import { APP_COLOR_PRESETS, type AppColorName } from './color-presets';
-import { getPresetVars, toWebColorValue } from './preset-vars';
-
-// Re-exported so the web var-contract helper is reachable from this file (the
-// home of the web write path). Defined in `preset-vars.ts` next to the related
-// HSL parsing so native (which never imports this module) doesn't pull it in.
-export { toWebColorValue } from './preset-vars';
+import { getResolvedTokens } from './token-registry';
 
 export function applyDarkClass(resolved: 'light' | 'dark') {
   if (Platform.OS === 'web' && typeof document !== 'undefined') {
@@ -21,16 +16,12 @@ export function applyDarkClass(resolved: 'light' | 'dark') {
  * -------------------------------------------------------------------
  * The shadcn/Tailwind-v4 web apps compile their color utilities to reference the
  * BASE token directly (`.bg-background { background-color: var(--background) }`),
- * so on web the base `--x` tokens MUST be FULL CSS colors. We therefore write
- * them as `hsl(...)` (e.g. `--primary: hsl(185 100% 20%)`) — `var(--primary)`
- * then resolves to a valid color. The resolved `--color-*` vars are written
- * verbatim as `rgb(...)` (already full colors, used by native `color-mix` alpha
- * utilities; harmless on web). Non-color tokens (`--radius`, etc.) pass through
- * unchanged. See `toWebColorValue`.
+ * so on web the base `--x` tokens MUST be FULL CSS colors. `getResolvedTokens`
+ * returns every canonical token already resolved to an sRGB `rgb(...)` string,
+ * so `var(--x)` resolves to a valid color directly — no per-value wrapping. The
+ * same rgb values feed native (`color-mix` alpha utilities resolve on sRGB), so
+ * web and native share one canonical token pipeline.
  *
- * NATIVE writes the SAME tokens as RAW HSL triples (no `hsl()` wrapper) via
- * `rootVariables` (`native-root-vars.native.ts`), consumed through bloom's
- * native `global.css` `hsl(var(--x))` indirection — that path is untouched here.
  * Includes extended tokens (card, chart-*, content-area, sidebar-*) so consumer
  * apps don't need to synthesize them.
  */
@@ -38,10 +29,10 @@ export function applyColorPresetVars(preset: AppColorName, resolved: 'light' | '
   if (Platform.OS !== 'web' || typeof document === 'undefined') return;
   if (!APP_COLOR_PRESETS[preset]) return;
 
-  const vars = getPresetVars(preset, resolved, { includeResolvedColorVars: true });
+  const vars = getResolvedTokens(preset, resolved);
   const root = document.documentElement.style;
 
   for (const [key, value] of Object.entries(vars)) {
-    root.setProperty(key, toWebColorValue(key, value));
+    root.setProperty(key, value);
   }
 }

package/src/theme/build-theme.ts

@@ -1,6 +1,8 @@
 import { Platform } from 'react-native';
-import { APP_COLOR_PRESETS, type AppColorName, type PresetTokens } from './color-presets';
+import type { AppColorName } from './color-presets';
 import { getAdaptiveColors } from './adaptive-colors';
+import { getResolvedTokens } from './token-registry';
+import { parseRgbString, srgbToRgbString } from './color-space';
 import type { Theme, ThemeColors } from './types';
 
 /**
@@ -15,91 +17,61 @@ export const STATUS_COLORS = {
 } as const;
 
 /**
- * Convert a shadcn-style HSL CSS variable (`'H S% L%'` or `'H S% L% / A'`)
- * into a fully-resolved `hsl()` / `hsla()` color string consumable by both
- * web `style` and React Native.
+ * Build the JS `theme.colors` object from the SAME canonical rgb token source
+ * the web/native CSS-var writes use (`getResolvedTokens`). JS styles and the
+ * `var(--x)` document tokens therefore share one rgb pipeline — no second,
+ * drift-prone HSL conversion lives here. Subtle/alpha mixes derive from the
+ * resolved rgb via `parseRgbString` + `srgbToRgbString`.
  */
-function hslVarToColor(hslVar: string): string {
-  const parts = hslVar.split('/').map((p) => p.trim());
-  const triple = parts[0] ?? '0 0% 0%';
-  const components = triple.replace(/\s+/g, ', ');
-
-  if (parts.length === 2) {
-    const alpha = parseFloat(parts[1] ?? '100') / 100;
-    return `hsla(${components}, ${alpha})`;
-  }
-  return `hsl(${components})`;
-}
-
-function extractHue(hslVar: string): number {
-  const first = hslVar.split(/\s+/)[0] ?? '0';
-  const hue = parseInt(first, 10);
-  return Number.isFinite(hue) ? hue : 0;
-}
-
-function hsl(h: number, s: number, l: number): string {
-  return `hsl(${h}, ${s}%, ${l}%)`;
-}
-
-function readToken(tokens: PresetTokens, key: string, fallback = '0 0% 0%'): string {
-  return hslVarToColor(tokens[key] ?? fallback);
-}
-
 function buildColorsFromPreset(
   preset: AppColorName,
   resolved: 'light' | 'dark',
 ): ThemeColors {
-  const config = APP_COLOR_PRESETS[preset];
-  const tokens = resolved === 'dark' ? config.dark : config.light;
+  const t = getResolvedTokens(preset, resolved);
   const isDark = resolved === 'dark';
 
-  const primaryHue = extractHue(tokens['--primary'] ?? '0 0% 50%');
-  const destructiveHue = extractHue(tokens['--destructive'] ?? '0 0% 0%');
-
-  const background = readToken(tokens, '--background');
-  const surface = readToken(tokens, '--surface');
-  const mutedForeground = readToken(tokens, '--muted-foreground', '0 0% 50%');
-  const primaryColor = readToken(tokens, '--primary', '0 0% 50%');
-  const primaryForeground = readToken(tokens, '--primary-foreground', '0 0% 100%');
+  // Read a resolved `rgb(...)` token by its bare name (no leading `--`).
+  const g = (k: string): string => t[`--${k}`] ?? 'rgb(0 0 0)';
+  // Re-emit a resolved token at a given alpha (sRGB rgb-with-alpha).
+  const mix = (k: string, a: number): string => srgbToRgbString(parseRgbString(g(k)), a);
 
   return {
-    background,
-    backgroundSecondary: surface,
-    backgroundTertiary: readToken(tokens, '--muted'),
+    background: g('background'),
+    backgroundSecondary: g('surface'),
+    backgroundTertiary: g('muted'),
 
-    text: readToken(tokens, '--foreground', '0 0% 100%'),
-    textSecondary: mutedForeground,
-    textTertiary: mutedForeground,
+    text: g('foreground'),
+    textSecondary: g('muted-foreground'),
+    textTertiary: g('muted-foreground'),
 
-    border: readToken(tokens, '--border', '0 0% 20%'),
-    borderLight: readToken(tokens, '--input', '0 0% 20%'),
+    border: g('border'),
+    borderLight: g('input'),
 
-    primary: primaryColor,
-    primaryForeground,
-    // Legacy aliases retained for backwards compatibility with downstream
-    // consumers. `primaryLight` should be a brand tint, not the surface, but
-    // changing this is a breaking change handled in a separate major.
-    primaryLight: surface,
-    primaryDark: background,
+    primary: g('primary'),
+    primaryForeground: g('primary-foreground'),
+    // Corrected aliases (see types.ts): `primaryLight` is the preset accent
+    // tint, `primaryDark` is the focus-ring shade — NOT the surface/background.
+    primaryLight: g('accent'),
+    primaryDark: g('ring'),
 
-    // `secondary` historically mirrored `primary`. Retained for compatibility.
-    secondary: primaryColor,
+    // Corrected: `secondary` is the preset's secondary surface, NOT a primary mirror.
+    secondary: g('secondary'),
 
-    tint: primaryColor,
-    icon: mutedForeground,
-    iconActive: primaryColor,
+    tint: g('primary'),
+    icon: g('muted-foreground'),
+    iconActive: g('primary'),
 
     ...STATUS_COLORS,
 
-    primarySubtle: isDark ? hsl(primaryHue, 50, 10) : hsl(primaryHue, 70, 93),
-    primarySubtleForeground: isDark ? hsl(primaryHue, 70, 65) : hsl(primaryHue, 90, 25),
-    negative: hsl(destructiveHue, 84, 45),
+    primarySubtle: mix('primary', isDark ? 0.16 : 0.12),
+    primarySubtleForeground: g('primary'),
+    negative: g('destructive'),
     negativeForeground: '#FFFFFF',
-    negativeSubtle: isDark ? hsl(destructiveHue, 50, 10) : hsl(destructiveHue, 90, 95),
-    negativeSubtleForeground: isDark ? hsl(destructiveHue, 70, 65) : hsl(destructiveHue, 80, 40),
-    contrast50: isDark ? hsl(primaryHue, 15, 12) : hsl(primaryHue, 10, 93),
+    negativeSubtle: mix('destructive', isDark ? 0.16 : 0.12),
+    negativeSubtleForeground: g('destructive'),
+    contrast50: mix('foreground', 0.5),
 
-    card: surface,
+    card: g('card'),
     shadow: isDark ? 'rgba(0, 0, 0, 0.3)' : 'rgba(0, 0, 0, 0.1)',
     overlay: 'rgba(0, 0, 0, 0.5)',
   };

package/src/theme/color-presets.ts

@@ -6,17 +6,17 @@ export type AppColorName = 'teal' | 'blue' | 'green' | 'amber' | 'yellow' | 'red
  * Keys carry a leading `--` for historical reasons (shadcn-style CSS variable
  * names) — keep in mind the values are platform-agnostic **raw HSL triples**
  * (e.g. `'185 100% 20%'` or `'185 100% 20% / 0.5'`), not CSS-resolved colors.
- * The same map drives both:
- *   - the web layer: the base `--x` tokens are wrapped to full `hsl(...)` colors
- *     (via `toWebColorValue`) before being written to `document.documentElement`
- *     / a `BloomColorScope` element, so `var(--x)` — the form Tailwind v4
- *     `@theme inline` compiles its color utilities to — resolves to a valid
- *     color directly; the resolved `--color-*` companions are written as
- *     `rgb(...)`, and
+ * The single canonical resolver `getResolvedTokens` (in `token-registry.ts`)
+ * converts this raw map to sRGB `rgb(...)` for every runtime write — the same
+ * values drive BOTH layers:
+ *   - the web layer: `getResolvedTokens`'s `rgb(...)` strings are written to
+ *     `document.documentElement` / a `BloomColorScope` element, so `var(--x)` —
+ *     the form Tailwind v4 `@theme inline` compiles its color utilities to —
+ *     resolves to a valid color directly, and
  *   - the native layer (`buildTheme` resolves the raw triples into `hsl(...)`
  *     strings consumable by React Native styles; `native-root-vars.native.ts`
- *     writes the raw triples through bloom's `hsl(var(--x))` `global.css`
- *     indirection).
+ *     writes the same canonical `rgb(...)` values into react-native-css's
+ *     `rootVariables` family).
  *
  * The `--` prefix is an implementation detail we will drop in a future major.
  */

package/src/theme/color-scope/index.web.tsx

@@ -3,27 +3,20 @@ import React, { Children, cloneElement, isValidElement, useContext, useMemo } fr
 import { BloomThemeContext, type BloomThemeContextValue } from '../BloomThemeProvider';
 import { buildTheme } from '../build-theme';
 import type { AppColorName } from '../color-presets';
-import { toWebColorValue } from '../preset-vars';
-import { buildScopeVars } from './style-builder';
+import { getResolvedTokens } from '../token-registry';
 
 /**
- * `buildScopeVars` returns the preset's tokens as platform-agnostic raw HSL
- * triples (shared with the native write path). On web they are scoped onto an
- * element's inline `style`, where Tailwind v4's compiled utilities read them as
- * `var(--x)` directly — so the base tokens MUST be full CSS colors. Wrap each
- * raw triple in `hsl(...)` via `toWebColorValue`; `--color-*` rgb vars and
- * non-color tokens pass through. See `toWebColorValue` in `../preset-vars`.
+ * `getResolvedTokens` returns every canonical token already resolved to an sRGB
+ * `rgb(...)` string — the SAME pipeline the document-root web writer and the
+ * native writer use. Scoped onto an element's inline `style`, Tailwind v4's
+ * compiled utilities read these as `var(--x)` directly, so each base token is a
+ * full CSS color with no per-value wrapping needed.
  */
 function buildWebScopeVars(
   colorPreset: AppColorName,
   mode: 'light' | 'dark',
 ): React.CSSProperties {
-  const raw = buildScopeVars(colorPreset, mode);
-  const out: Record<string, string> = {};
-  for (const [key, value] of Object.entries(raw)) {
-    out[key] = toWebColorValue(key, value);
-  }
-  return out as React.CSSProperties;
+  return getResolvedTokens(colorPreset, mode) as React.CSSProperties;
 }
 
 export interface BloomColorScopeProps {

package/src/theme/color-scope/style-builder.ts

@@ -1,7 +1,7 @@
 import type React from 'react';
 import { Platform, type StyleProp, type ViewStyle } from 'react-native';
 
-import { getPresetVars } from '../preset-vars';
+import { getResolvedTokens } from '../token-registry';
 import type { AppColorName } from '../color-presets';
 import { lazyRequire } from '../../utils/lazy-require';
 
@@ -25,14 +25,17 @@ const getNativeWindVars = lazyRequire<NativeWindVarsModule>('nativewind');
 
 /**
  * Build the CSS custom-property map for a preset, ready to be applied to a
- * subtree. Always includes the resolved `--color-*` vars so Tailwind v4
- * `@theme` utilities (e.g. `bg-background`) honour the scope.
+ * subtree. Every token is resolved to an sRGB `rgb(...)` string via
+ * `getResolvedTokens` — the single canonical token pipeline shared by web and
+ * native — so Tailwind v4 `@theme` utilities (e.g. `bg-background`) and
+ * `color-mix`-based alpha utilities (`bg-primary/10`) both resolve against the
+ * same color values. Keys retain the leading `--`.
  */
 export function buildScopeVars(
   colorPreset: AppColorName,
   mode: 'light' | 'dark',
 ): Record<string, string> {
-  return getPresetVars(colorPreset, mode, { includeResolvedColorVars: true });
+  return getResolvedTokens(colorPreset, mode);
 }
 
 /**

package/src/theme/color-space.ts

@@ -0,0 +1,56 @@
+export interface Oklch { l: number; c: number; h: number } // l 0..1, c 0..~0.4, h deg
+export interface Rgb { r: number; g: number; b: number }   // 0..255 integers
+
+const clamp = (n: number, lo: number, hi: number) => Math.min(hi, Math.max(lo, n));
+const srgbGamma = (x: number) =>
+  x <= 0.0031308 ? 12.92 * x : 1.055 * Math.pow(x, 1 / 2.4) - 0.055;
+
+/** OKLCH → linear OKLab → linear sRGB → gamma sRGB → 0..255. Pure. */
+export function oklchToSrgb({ l, c, h }: Oklch): Rgb {
+  const hr = (h * Math.PI) / 180;
+  const a = c * Math.cos(hr);
+  const b2 = c * Math.sin(hr);
+  const l_ = l + 0.3963377774 * a + 0.2158037573 * b2;
+  const m_ = l - 0.1055613458 * a - 0.0638541728 * b2;
+  const s_ = l - 0.0894841775 * a - 1.291485548 * b2;
+  const lc = l_ ** 3, mc = m_ ** 3, sc = s_ ** 3;
+  const lr = +4.0767416621 * lc - 3.3077115913 * mc + 0.2309699292 * sc;
+  const lg = -1.2684380046 * lc + 2.6097574011 * mc - 0.3413193965 * sc;
+  const lb = -0.0041960863 * lc - 0.7034186147 * mc + 1.707614701 * sc;
+  return {
+    r: Math.round(clamp(srgbGamma(lr), 0, 1) * 255),
+    g: Math.round(clamp(srgbGamma(lg), 0, 1) * 255),
+    b: Math.round(clamp(srgbGamma(lb), 0, 1) * 255),
+  };
+}
+
+export function srgbToRgbString({ r, g, b }: Rgb, alpha?: number): string {
+  return alpha === undefined || alpha >= 1
+    ? `rgb(${r} ${g} ${b})`
+    : `rgb(${r} ${g} ${b} / ${alpha})`;
+}
+
+/**
+ * Parse an `rgb(...)` / `rgba(...)` string into an {@link Rgb}.
+ *
+ * Contract: input MUST be an `rgb(...)` / `rgba(...)` string (e.g. a resolved
+ * token from `getResolvedTokens`). Both modern (`rgb(r g b)`) and legacy
+ * (`rgb(r, g, b)`) syntaxes are accepted. Anything else throws — this is a
+ * canonical-pipeline primitive and a non-rgb input signals a real bug at the
+ * call site, never a value to silently coerce to black.
+ *
+ * @throws {Error} if `s` is not an `rgb()` / `rgba()` string.
+ */
+export function parseRgbString(s: string): Rgb {
+  const inner = s.match(/rgba?\(([^)]+)\)/i)?.[1];
+  if (inner === undefined) {
+    throw new Error(`parseRgbString: expected an rgb() string, got: ${s}`);
+  }
+  const [r, g, b] = inner.split(/[ ,/]+/).map((n) => parseInt(n, 10));
+  return { r: r ?? 0, g: g ?? 0, b: b ?? 0 };
+}
+
+/** Cheap perceptual-ish distance in sRGB (sufficient for a ≤1 rounding gate). */
+export function deltaE(a: Rgb, b: Rgb): number {
+  return Math.sqrt((a.r - b.r) ** 2 + (a.g - b.g) ** 2 + (a.b - b.b) ** 2) / Math.sqrt(3);
+}

package/src/theme/index.ts

@@ -16,12 +16,7 @@ export {
   HEX_TO_APP_COLOR,
   hexToAppColorName,
 } from './color-presets';
-export {
-  getPresetVars,
-  applyPresetVarsToDocument,
-  toWebColorValue,
-} from './preset-vars';
-export type { PresetVarsOptions } from './preset-vars';
+export { getPresetVars, applyPresetVarsToDocument } from './preset-vars';
 export { applyDarkClass } from './apply-dark-class';
 export { setColorSchemeSafe } from './set-color-scheme-safe';
 export { initCssInteropDarkMode } from './init-css-interop';

package/src/theme/native-root-vars.native.ts

@@ -16,8 +16,8 @@
 // directive ships raw in `src/` (Bloom publishes `files: ["src", "lib"]`).
 import { rootVariables } from 'react-native-css/native-internal';
 
-import { buildScopeVars } from './color-scope/style-builder';
 import { type AppColorName } from './color-presets';
+import { getResolvedTokens } from './token-registry';
 
 /**
  * Publish the active color preset's CSS custom properties into react-native-css's
@@ -41,18 +41,28 @@ import { type AppColorName } from './color-presets';
  * `BloomThemeProvider`'s `VariableContextProvider` only feeds path #1, so the navigator
  * host and every portal/modal — which render outside that subtree — never see the
  * preset vars and fall through to `rootVariables`/`universalVariables`. By default those
- * families hold only react-native-css's own `__rn-css-rem`/`__rn-css-color` entries
- * (Bloom's `global.css` defines the `hsl(var(--primary))` indirection but not the HSL
- * triples themselves — those are injected at runtime), so the whole tree below the
- * navigator renders monochrome. Writing the vars into `rootVariables` here is the
- * exact same mechanism react-native-css uses for compiled `:root {}` / `@theme` vars
- * (`StyleCollection.inject` does `rootVariables(name).set(valueArray)`), so portaled
- * content resolves the palette identically regardless of React-tree position.
+ * families hold only react-native-css's own `__rn-css-rem`/`__rn-css-color` entries, so
+ * the whole tree below the navigator renders monochrome until the palette is injected at
+ * runtime. Writing the vars into `rootVariables` here is the exact same mechanism
+ * react-native-css uses for compiled `:root {}` / `@theme` vars (`StyleCollection.inject`
+ * does `rootVariables(name).set(valueArray)`), so portaled content resolves the palette
+ * identically regardless of React-tree position.
  *
- * The raw tokens are written as HSL triples (`primary: '205 87% 53%'`) and the
- * resolved Tailwind v4 `--color-*` vars as sRGB `rgb(...)` (`color-primary:
- * 'rgb(31 153 239)'`) — the latter so `color-mix`-based alpha utilities resolve
- * on native (see `getPresetVars` / `hslTripletToRgb`).
+ * Consumer contract (CRITICAL — single canonical color pipeline)
+ * -------------------------------------------------------------
+ * Each base `--x` token is now written as a FULL `rgb(...)` color (not a raw HSL
+ * triple). A consuming app's Tailwind `@theme` must therefore reference these
+ * base tokens DIRECTLY (its Tailwind color var equals `var(--x)`) and must NOT
+ * wrap them in `hsl(...)`. The legacy `hsl(var(--x))` indirection (which assumed
+ * a raw triple) would produce the invalid `hsl(rgb(...))` and must be removed in
+ * every consumer. Web and native now share this one contract.
+ *
+ * Every token is written as an sRGB `rgb(...)` string from the single canonical
+ * token pipeline (`getResolvedTokens`) — `primary: 'rgb(31 153 239)'` — the SAME
+ * values web writes to `document.documentElement`. sRGB is the space
+ * react-native-css's `color-mix` resolver registers, so `color-mix`-based alpha
+ * utilities (`bg-primary/10`) resolve on native; full (non-alpha) utilities
+ * resolve directly through bloom's `global.css` `var(--x)` indirection.
  *
  * Why a STATIC `import`, not a runtime `require` (critical)
  * ---------------------------------------------------------
@@ -82,15 +92,15 @@ import { type AppColorName } from './color-presets';
  * `shared.rootVariables[name]`, and `@property --x` goes through
  * `name.startsWith("--") ? name.slice(2) : name`. The lookup side matches: a `var(--x)`
  * reference compiles to `[{}, "var", ident.slice(2)]`, so `varResolver` looks up the
- * bare name. `buildScopeVars` returns keys WITH the `--` prefix, so we strip it before
- * writing each entry.
+ * bare name. `getResolvedTokens` returns keys WITH the `--` prefix, so we strip it
+ * before writing each entry.
  *
  * Value shape
  * -----------
  * Each entry is a `VariableValue[]` — an array of `[value, mediaCondition?]` tuples.
  * Bloom's preset vars are unconditional, so each is a single-element `[[value]]`, e.g.
- * `rootVariables('primary').set([['205 87% 53%']])`. This is the same shape the compiler
- * emits for unconditional `:root` vars.
+ * `rootVariables('primary').set([['rgb(31 153 239)']])`. This is the same shape the
+ * compiler emits for unconditional `:root` vars.
  *
  * This is native-only and additive: the `VariableContextProvider` wrapper stays (it is
  * the correct, scoped mechanism for `BloomColorScope` subtree overrides and harmlessly
@@ -114,9 +124,9 @@ import { type AppColorName } from './color-presets';
 export function applyNativeRootVars(colorPreset: AppColorName, mode: 'light' | 'dark'): void {
   if (typeof rootVariables !== 'function') return;
 
-  const vars = buildScopeVars(colorPreset, mode);
+  const vars = getResolvedTokens(colorPreset, mode);
   for (const [key, value] of Object.entries(vars)) {
-    // The family is keyed by the bare name; `buildScopeVars` keys include `--`.
+    // The family is keyed by the bare name; `getResolvedTokens` keys include `--`.
     const name = key.startsWith('--') ? key.slice(2) : key;
     rootVariables(name).set([[value]]);
   }