@oxyhq/bloom 0.7.5 → 0.7.7

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

@@ -1,6 +1,11 @@
 import { Platform } from 'react-native';
 import { APP_COLOR_PRESETS, type AppColorName } from './color-presets';
-import { getPresetVars } from './preset-vars';
+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';
 
 export function applyDarkClass(resolved: 'light' | 'dark') {
   if (Platform.OS === 'web' && typeof document !== 'undefined') {
@@ -10,16 +15,24 @@ export function applyDarkClass(resolved: 'light' | 'dark') {
 
 /**
  * Apply a color preset's CSS custom properties to the document root.
- * No-op on native — only affects web.
+ * No-op on native — only affects web (early-returns on `Platform.OS !== 'web'`).
+ *
+ * Web var contract (the form Tailwind v4 `@theme inline` compiles to)
+ * -------------------------------------------------------------------
+ * 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`.
  *
- * Writes both the raw HSL triples (e.g. `--primary: 185 100% 20%`) and the
- * resolved `--color-*` vars (`--color-primary: rgb(0 94 102)`) so both
- * shadcn-style `hsl(var(--primary))` plumbing and Tailwind v4 `@theme`
- * utilities resolve consistently. The resolved vars are emitted as `rgb(...)`
- * (not `hsl(...)`) so the alpha utilities (`bg-primary/10`) resolve on native —
- * see `getPresetVars` / `hslTripletToRgb`. Includes extended tokens (card,
- * chart-*, content-area, sidebar-*) so consumer apps don't need to synthesize
- * them.
+ * 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.
  */
 export function applyColorPresetVars(preset: AppColorName, resolved: 'light' | 'dark') {
   if (Platform.OS !== 'web' || typeof document === 'undefined') return;
@@ -29,6 +42,6 @@ export function applyColorPresetVars(preset: AppColorName, resolved: 'light' | '
   const root = document.documentElement.style;
 
   for (const [key, value] of Object.entries(vars)) {
-    root.setProperty(key, value);
+    root.setProperty(key, toWebColorValue(key, value));
   }
 }

package/src/theme/color-presets.ts

@@ -7,10 +7,16 @@ export type AppColorName = 'teal' | 'blue' | 'green' | 'amber' | 'yellow' | 'red
  * 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 (written verbatim into `document.documentElement.style`
- *     so Tailwind's `hsl(var(--primary))` plumbing picks them up), and
- *   - the native layer (`buildTheme` resolves them into `hsl(...)` strings
- *     consumable by React Native styles).
+ *   - 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 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).
  *
  * The `--` prefix is an implementation detail we will drop in a future major.
  */

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

@@ -3,8 +3,29 @@ 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';
 
+/**
+ * `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`.
+ */
+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;
+}
+
 export interface BloomColorScopeProps {
   /**
    * Preset to apply within this subtree. When `undefined`, the scope is a
@@ -63,7 +84,7 @@ export function BloomColorScope({
   }, [colorPreset, resolvedMode, parent]);
 
   const varsStyle = useMemo(
-    () => buildScopeVars(colorPreset, resolvedMode) as React.CSSProperties,
+    () => buildWebScopeVars(colorPreset, resolvedMode),
     [colorPreset, resolvedMode],
   );
 
@@ -104,7 +125,7 @@ export function useColorScopeStyle(colorPreset: AppColorName): React.CSSProperti
   }
   const resolvedMode = parent.theme.mode;
   return useMemo(
-    () => buildScopeVars(colorPreset, resolvedMode) as React.CSSProperties,
+    () => buildWebScopeVars(colorPreset, resolvedMode),
     [colorPreset, resolvedMode],
   );
 }

package/src/theme/index.ts

@@ -19,6 +19,7 @@ export {
 export {
   getPresetVars,
   applyPresetVarsToDocument,
+  toWebColorValue,
 } from './preset-vars';
 export type { PresetVarsOptions } from './preset-vars';
 export { applyDarkClass } from './apply-dark-class';

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

@@ -0,0 +1,123 @@
+/// <reference path="../react-native-css.d.ts" />
+// The triple-slash reference above pins Bloom's ambient declaration for
+// `react-native-css/native-internal` (`src/react-native-css.d.ts`) into the
+// compilation graph of EVERY program that compiles THIS file — including
+// downstream consumers that resolve Bloom's `"react-native"` source export
+// condition (`./src/theme/index.ts` → `BloomThemeProvider` → this file). Without
+// it the ambient decl is only auto-loaded inside Bloom's own tsconfig
+// (`include: ["src"]`); a consumer's tsconfig never includes
+// `node_modules/@oxyhq/bloom/src/**`, and TypeScript does NOT auto-pick-up
+// ambient `.d.ts` files that live under `node_modules`, so
+// `react-native-css/native-internal` is unresolved (TS2307) unless the reference
+// travels with the source. react-native-css is intentionally NOT a Bloom
+// dependency — it arrives transitively via a host's NativeWind 5 install, or is
+// absent entirely for NativeWind 4 consumers — so the ambient declaration is the
+// only thing that can type this import, and it MUST reach the consumer. The
+// 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';
+
+/**
+ * Publish the active color preset's CSS custom properties into react-native-css's
+ * GLOBAL root-variable family so they reach the ENTIRE native app tree — including
+ * content rendered outside the React subtree of `BloomThemeProvider`: expo-router
+ * navigator screens, `Portal`s, `Dialog`/`BottomSheet` overlays, and any other host
+ * that paints through a separate React root.
+ *
+ * Why a global write is required (native only)
+ * --------------------------------------------
+ * react-native-css resolves a `var(--x)` reference (its `varResolver`) in this order:
+ *   1. `name in inheritedVariables`  — the React-context-inherited vars. This is what
+ *      `VariableContextProvider` populates, but it is React-context-scoped, so it only
+ *      reaches *direct descendants* of the provider in the React tree.
+ *   2. `inlineVariables[name]`        — same-component inline vars.
+ *   3. `variables[name]`             — resolved inherited vars.
+ *   4. `universalVariables(name)`    — a GLOBAL observable family.
+ *   5. `rootVariables(name)`         — a GLOBAL observable family.
+ *   6. the declared fallback.
+ *
+ * `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.
+ *
+ * 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`).
+ *
+ * Why a STATIC `import`, not a runtime `require` (critical)
+ * ---------------------------------------------------------
+ * react-native-css@3.0.7 ships both a `dist/commonjs` and a `dist/module` build, and
+ * Metro bundles BOTH. In `native-internal/root.js` the variable families are plain
+ * module-local consts — NOT `globalThis`-guarded the way `StyleCollection` is — so the
+ * commonjs `root.js` and the module `root.js` each instantiate their OWN separate
+ * `rootVariables` family. The react-native-css renderer (`react-native-css/src/components/View.tsx`
+ * → `varResolver`) imports its `root.js` via ESM `import`, i.e. the MODULE build. A
+ * runtime `require('react-native-css/native-internal')` resolves the package's `require`
+ * export condition → the COMMONJS build → a DIFFERENT family the renderer never
+ * subscribes to, so the writes are a silent no-op on device. A static top-level
+ * `import` resolves the `import` condition → the MODULE build → the renderer's instance.
+ *
+ * This plain file is the NATIVE/default variant (Metro selects it on iOS/Android,
+ * which have no `.native` override here); the web variant lives in the sibling
+ * `native-root-vars.web.ts` no-op, which web bundlers pick over this one. So the
+ * static `react-native-css/native-internal` import below is never pulled into a web
+ * bundle — only into native. This mirrors Bloom's existing platform-split convention
+ * (`color-scope/index.tsx` + `color-scope/index.web.tsx`, `FontLoader.native.tsx`).
+ *
+ * Keying contract (verified against react-native-css@3.0.7)
+ * ---------------------------------------------------------
+ * The `rootVariables` family is keyed by the BARE variable name, WITHOUT the leading
+ * `--`. The compiler strips it uniformly: a `:root { --primary: ... }` declaration is
+ * stored via `rule.v.push([property.slice(2), value])` then routed into
+ * `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.
+ *
+ * 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.
+ *
+ * This is native-only and additive: the `VariableContextProvider` wrapper stays (it is
+ * the correct, scoped mechanism for `BloomColorScope` subtree overrides and harmlessly
+ * covers direct descendants). The web fork (`native-root-vars.web.ts`) no-ops — web
+ * writes the same vars to `document.documentElement` via `applyColorPresetVars`.
+ */
+
+/**
+ * Write the preset's CSS vars to react-native-css's global `rootVariables` family
+ * so the whole native tree (navigator screens + portals/modals/bottom-sheets)
+ * resolves the active palette.
+ *
+ * Each `.set` notifies its own observers synchronously (react-native-css only
+ * batches notifications inside its own `StyleCollection.inject`; outside it,
+ * `observableBatch.current` is unset so every `.set` runs observers immediately),
+ * so sequential writes correctly trigger a re-render when the preset/mode changes.
+ *
+ * Defensive guard: if a host ships a react-native-css build that doesn't expose
+ * `rootVariables` as a callable (it always does on @3), we bail rather than throw.
+ */
+export function applyNativeRootVars(colorPreset: AppColorName, mode: 'light' | 'dark'): void {
+  if (typeof rootVariables !== 'function') return;
+
+  const vars = buildScopeVars(colorPreset, mode);
+  for (const [key, value] of Object.entries(vars)) {
+    // The family is keyed by the bare name; `buildScopeVars` keys include `--`.
+    const name = key.startsWith('--') ? key.slice(2) : key;
+    rootVariables(name).set([[value]]);
+  }
+}

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

@@ -1,123 +1,37 @@
-/// <reference path="../react-native-css.d.ts" />
-// The triple-slash reference above pins Bloom's ambient declaration for
-// `react-native-css/native-internal` (`src/react-native-css.d.ts`) into the
-// compilation graph of EVERY program that compiles THIS file — including
-// downstream consumers that resolve Bloom's `"react-native"` source export
-// condition (`./src/theme/index.ts` → `BloomThemeProvider` → this file). Without
-// it the ambient decl is only auto-loaded inside Bloom's own tsconfig
-// (`include: ["src"]`); a consumer's tsconfig never includes
-// `node_modules/@oxyhq/bloom/src/**`, and TypeScript does NOT auto-pick-up
-// ambient `.d.ts` files that live under `node_modules`, so
-// `react-native-css/native-internal` is unresolved (TS2307) unless the reference
-// travels with the source. react-native-css is intentionally NOT a Bloom
-// dependency — it arrives transitively via a host's NativeWind 5 install, or is
-// absent entirely for NativeWind 4 consumers — so the ambient declaration is the
-// only thing that can type this import, and it MUST reach the consumer. The
-// 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';
 
 /**
- * Publish the active color preset's CSS custom properties into react-native-css's
- * GLOBAL root-variable family so they reach the ENTIRE native app tree — including
- * content rendered outside the React subtree of `BloomThemeProvider`: expo-router
- * navigator screens, `Portal`s, `Dialog`/`BottomSheet` overlays, and any other host
- * that paints through a separate React root.
- *
- * Why a global write is required (native only)
- * --------------------------------------------
- * react-native-css resolves a `var(--x)` reference (its `varResolver`) in this order:
- *   1. `name in inheritedVariables`  — the React-context-inherited vars. This is what
- *      `VariableContextProvider` populates, but it is React-context-scoped, so it only
- *      reaches *direct descendants* of the provider in the React tree.
- *   2. `inlineVariables[name]`        — same-component inline vars.
- *   3. `variables[name]`             — resolved inherited vars.
- *   4. `universalVariables(name)`    — a GLOBAL observable family.
- *   5. `rootVariables(name)`         — a GLOBAL observable family.
- *   6. the declared fallback.
- *
- * `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.
- *
- * 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`).
- *
- * Why a STATIC `import`, not a runtime `require` (critical)
- * ---------------------------------------------------------
- * react-native-css@3.0.7 ships both a `dist/commonjs` and a `dist/module` build, and
- * Metro bundles BOTH. In `native-internal/root.js` the variable families are plain
- * module-local consts — NOT `globalThis`-guarded the way `StyleCollection` is — so the
- * commonjs `root.js` and the module `root.js` each instantiate their OWN separate
- * `rootVariables` family. The react-native-css renderer (`react-native-css/src/components/View.tsx`
- * → `varResolver`) imports its `root.js` via ESM `import`, i.e. the MODULE build. A
- * runtime `require('react-native-css/native-internal')` resolves the package's `require`
- * export condition → the COMMONJS build → a DIFFERENT family the renderer never
- * subscribes to, so the writes are a silent no-op on device. A static top-level
- * `import` resolves the `import` condition → the MODULE build → the renderer's instance.
- *
- * This plain file is the NATIVE/default variant (Metro selects it on iOS/Android,
- * which have no `.native` override here); the web variant lives in the sibling
- * `native-root-vars.web.ts` no-op, which web bundlers pick over this one. So the
- * static `react-native-css/native-internal` import below is never pulled into a web
- * bundle — only into native. This mirrors Bloom's existing platform-split convention
- * (`color-scope/index.tsx` + `color-scope/index.web.tsx`, `FontLoader.native.tsx`).
- *
- * Keying contract (verified against react-native-css@3.0.7)
- * ---------------------------------------------------------
- * The `rootVariables` family is keyed by the BARE variable name, WITHOUT the leading
- * `--`. The compiler strips it uniformly: a `:root { --primary: ... }` declaration is
- * stored via `rule.v.push([property.slice(2), value])` then routed into
- * `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.
- *
- * 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.
- *
- * This is native-only and additive: the `VariableContextProvider` wrapper stays (it is
- * the correct, scoped mechanism for `BloomColorScope` subtree overrides and harmlessly
- * covers direct descendants). The web fork (`native-root-vars.web.ts`) no-ops — web
- * writes the same vars to `document.documentElement` via `applyColorPresetVars`.
+ * Platform-neutral DEFAULT variant of `applyNativeRootVars` — a no-op.
+ *
+ * This is the file resolved by every bundler / type-checker that does NOT do
+ * React Native's platform-extension resolution:
+ *   - a consumer's `tsc` (resolving Bloom's `"react-native"` -> `./src/...` source
+ *     export condition: `theme/index.ts` -> `BloomThemeProvider` -> this import);
+ *   - non-Metro web bundlers (Vite/Rolldown, webpack) resolving the package
+ *     `exports` `import`/`require` conditions to `lib/.../native-root-vars.js`.
+ *
+ * It deliberately does NOT import `react-native-css/native-internal`. That subpath
+ * is native-only: it has no web build, and react-native-css is not even a Bloom
+ * dependency. Statically importing it from a file a web bundler resolves breaks
+ * module resolution outright (the original report: `Rolldown failed to resolve
+ * import "react-native-css/native-internal" from .../native-root-vars.js`).
+ * Importing it from a file a consumer's `tsc` resolves breaks type-check (TS2307).
+ *
+ * Confining the real implementation (and that import) to the `.native` sibling —
+ * `native-root-vars.native.ts`, which ONLY Metro selects — keeps both web bundling
+ * AND downstream `tsc` green, while native still publishes the preset vars into
+ * react-native-css's GLOBAL `rootVariables` family so the whole native tree
+ * (navigator screens + portals/modals) resolves the palette.
+ *
+ * The other variants:
+ *   - `native-root-vars.native.ts` — iOS/Android (Metro), the real implementation;
+ *   - `native-root-vars.web.ts` — web, also a no-op (web writes the same vars to
+ *     `document.documentElement` via `applyColorPresetVars` instead).
+ *
+ * The signature is intentionally identical to those variants so the import site in
+ * `BloomThemeProvider` is platform-agnostic.
  */
-
-/**
- * Write the preset's CSS vars to react-native-css's global `rootVariables` family
- * so the whole native tree (navigator screens + portals/modals/bottom-sheets)
- * resolves the active palette.
- *
- * Each `.set` notifies its own observers synchronously (react-native-css only
- * batches notifications inside its own `StyleCollection.inject`; outside it,
- * `observableBatch.current` is unset so every `.set` runs observers immediately),
- * so sequential writes correctly trigger a re-render when the preset/mode changes.
- *
- * Defensive guard: if a host ships a react-native-css build that doesn't expose
- * `rootVariables` as a callable (it always does on @3), we bail rather than throw.
- */
-export function applyNativeRootVars(colorPreset: AppColorName, mode: 'light' | 'dark'): void {
-  if (typeof rootVariables !== 'function') return;
-
-  const vars = buildScopeVars(colorPreset, mode);
-  for (const [key, value] of Object.entries(vars)) {
-    // The family is keyed by the bare name; `buildScopeVars` keys include `--`.
-    const name = key.startsWith('--') ? key.slice(2) : key;
-    rootVariables(name).set([[value]]);
-  }
+export function applyNativeRootVars(_colorPreset: AppColorName, _mode: 'light' | 'dark'): void {
+  // Intentionally empty — the native variant (`native-root-vars.native.ts`) does
+  // the real work; this neutral default and the web fork are inert.
 }

package/src/theme/preset-vars.ts

@@ -83,6 +83,53 @@ export function hslTripletToRgb(triplet: string): string {
   return `rgb(${red} ${green} ${blue})`;
 }
 
+/**
+ * Prefix that marks a Tailwind v4 resolved color var (`--color-primary`). These
+ * are already emitted as full `rgb(...)` colors by `getPresetVars` and must be
+ * written to web verbatim — wrapping them would corrupt the value.
+ */
+const RESOLVED_COLOR_VAR_PREFIX = '--color-';
+
+/**
+ * Matches a shadcn-style raw HSL triple — `H S% L%`, optionally with an alpha
+ * tail `H S% L% / A`. The value starts with a digit (or a leading `-`) and
+ * carries at least one `%` (the saturation/lightness units), which together
+ * distinguish a bare triple from an already-resolved CSS color (`rgb(...)`,
+ * `hsl(...)`, `#fff`, named colors) or a unitless/length token (`--radius`).
+ * Mirrors the triple shape parsed by `hslTripletToRgb`.
+ */
+const RAW_HSL_TRIPLE = /^-?\d[\d.]*\s+[\d.]+%/;
+
+/**
+ * Transform a single preset var into the value to write to a WEB element
+ * (`document.documentElement` or a `BloomColorScope` subtree element).
+ *
+ * The web apps (Vite + Tailwind v4 + shadcn) compile their `@theme inline`
+ * block so the color utilities reference the BASE token directly — e.g.
+ * `.bg-background { background-color: var(--background) }`. So on web the base
+ * `--x` tokens MUST resolve to a COMPLETE CSS color; a bare HSL triple
+ * (`185 50% 5%`) is invalid as a `background-color` value and renders
+ * transparent (the production incident this fixes). We therefore wrap raw
+ * triples in `hsl(...)`, preserving the exact preset color math (and any `/ A`
+ * alpha tail, valid in modern `hsl(H S% L% / A)` syntax) with zero rounding
+ * drift.
+ *
+ * Values that are already full colors pass through unchanged:
+ *   - `--color-*` resolved vars (already `rgb(...)` from `getPresetVars`),
+ *   - any value not shaped like a raw HSL triple (`--radius: 0.5rem`,
+ *     pre-resolved `rgb(...)`/`hsl(...)`, etc.).
+ *
+ * NATIVE never calls this — `getPresetVars` returns raw triples verbatim and
+ * `native-root-vars.native.ts` writes them through bloom's `hsl(var(--x))`
+ * native `global.css` indirection. Pure function — no side effects — so it is
+ * unit-testable in isolation.
+ */
+export function toWebColorValue(key: string, value: string): string {
+  if (key.startsWith(RESOLVED_COLOR_VAR_PREFIX)) return value;
+  if (!RAW_HSL_TRIPLE.test(value)) return value;
+  return `hsl(${value})`;
+}
+
 const RESOLVED_COLOR_MAP: Record<string, string> = {
   '--background': '--color-background',
   '--foreground': '--color-foreground',
@@ -183,6 +230,11 @@ export function getPresetVars(
  * on native. `BloomThemeProvider` already writes the base preset vars on web;
  * call this only when an app needs the extended (card/chart/sidebar) tokens on
  * the document root.
+ *
+ * The base raw-HSL-triple tokens are wrapped to full `hsl(...)` colors via
+ * `toWebColorValue` so `var(--x)` (the form Tailwind v4 `@theme inline`
+ * compiles to) resolves directly on web; `--color-*` rgb vars pass through. See
+ * `toWebColorValue` for the web var contract.
  */
 export function applyPresetVarsToDocument(
   colorName: AppColorName,
@@ -194,6 +246,6 @@ export function applyPresetVarsToDocument(
   const vars = getPresetVars(colorName, mode, options);
   const root = document.documentElement.style;
   for (const [key, value] of Object.entries(vars)) {
-    root.setProperty(key, value);
+    root.setProperty(key, toWebColorValue(key, value));
   }
 }