@oxyhq/bloom 0.6.15 → 0.6.17

package/lib/typescript/module/theme/color-presets.d.ts

@@ -21,6 +21,8 @@ export interface AppColorPreset {
     dark: PresetTokens;
 }
 export declare const APP_COLOR_NAMES: readonly AppColorName[];
+/** Premium-exclusive presets, hidden from the standard color picker. */
+export declare const PREMIUM_COLOR_NAMES: readonly AppColorName[];
 export declare const HEX_TO_APP_COLOR: Record<string, AppColorName>;
 export declare function hexToAppColorName(hex: string): AppColorName;
 export declare const APP_COLOR_PRESETS: Record<AppColorName, AppColorPreset>;

package/lib/typescript/module/theme/color-presets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"color-presets.d.ts","sourceRoot":"","sources":["../../../../src/theme/color-presets.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,GAAG,UAAU,CAAC;AAEvJ;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAElD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,YAAY,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,YAAY,CAAC;IACpB,IAAI,EAAE,YAAY,CAAC;CACpB;AAED,eAAO,MAAM,eAAe,EAAE,SAAS,YAAY,EAAsH,CAAC;AAE1K,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAczD,CAAC;AAEF,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,CAE3D;AAED,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,YAAY,EAAE,cAAc,CAkmBlE,CAAC"}
+{"version":3,"file":"color-presets.d.ts","sourceRoot":"","sources":["../../../../src/theme/color-presets.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,GAAG,UAAU,CAAC;AAEvJ;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAElD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,YAAY,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,YAAY,CAAC;IACpB,IAAI,EAAE,YAAY,CAAC;CACpB;AAED,eAAO,MAAM,eAAe,EAAE,SAAS,YAAY,EAAsH,CAAC;AAE1K,wEAAwE;AACxE,eAAO,MAAM,mBAAmB,EAAE,SAAS,YAAY,EAAwB,CAAC;AAEhF,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAczD,CAAC;AAEF,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,YAAY,CAE3D;AAED,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,YAAY,EAAE,cAAc,CAkmBlE,CAAC"}

package/lib/typescript/module/theme/color-scope/index.d.ts

@@ -0,0 +1,23 @@
+import React from 'react';
+import { type StyleProp, type ViewStyle } from 'react-native';
+import type { AppColorName } from '../color-presets';
+export interface BloomColorScopeProps {
+    /** Preset to apply within this subtree. */
+    colorPreset: AppColorName;
+    /**
+     * When `true`, do not render a wrapping `<View>`. The caller owns the
+     * element that receives the CSS vars (via `useColorScopeStyle`).
+     */
+    asChild?: boolean;
+    /** Additional style applied to the wrapping `<View>`. Ignored with `asChild`. */
+    style?: StyleProp<ViewStyle>;
+    children: React.ReactNode;
+}
+export declare function BloomColorScope({ colorPreset, asChild, style, children, }: BloomColorScopeProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Escape hatch for advanced cases where the wrapping element is owned by the
+ * caller. Returns a stable native style object carrying the preset's CSS vars.
+ * Returns `undefined` when nativewind is not installed.
+ */
+export declare function useColorScopeStyle(colorPreset: AppColorName): StyleProp<ViewStyle>;
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/module/theme/color-scope/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/theme/color-scope/index.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA8B,MAAM,OAAO,CAAC;AACnD,OAAO,EAAQ,KAAK,SAAS,EAAE,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AAIpE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAgBrD,MAAM,WAAW,oBAAoB;IACnC,2CAA2C;IAC3C,WAAW,EAAE,YAAY,CAAC;IAC1B;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,iFAAiF;IACjF,KAAK,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IAC7B,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAED,wBAAgB,eAAe,CAAC,EAC9B,WAAW,EACX,OAAe,EACf,KAAK,EACL,QAAQ,GACT,EAAE,oBAAoB,2CAuBtB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,YAAY,GAAG,SAAS,CAAC,SAAS,CAAC,CAUlF"}

package/lib/typescript/module/theme/color-scope/index.web.d.ts

@@ -0,0 +1,22 @@
+import React from 'react';
+import type { AppColorName } from '../color-presets';
+export interface BloomColorScopeProps {
+    /** Preset to apply within this subtree. */
+    colorPreset: AppColorName;
+    /**
+     * When `true`, do not render a wrapping element. The caller is responsible
+     * for placing the returned context provider over a DOM node that owns the
+     * CSS vars (via `useColorScopeStyle`).
+     */
+    asChild?: boolean;
+    children: React.ReactNode;
+}
+export declare function BloomColorScope({ colorPreset, asChild, children }: BloomColorScopeProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Escape hatch for advanced cases where the wrapping element is owned by the
+ * caller (e.g. a Pressable, a NativeWind-styled View that already has a style
+ * prop). Returns a stable React `style` object carrying every CSS custom
+ * property of the preset.
+ */
+export declare function useColorScopeStyle(colorPreset: AppColorName): React.CSSProperties;
+//# sourceMappingURL=index.web.d.ts.map

package/lib/typescript/module/theme/color-scope/index.web.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.web.d.ts","sourceRoot":"","sources":["../../../../../src/theme/color-scope/index.web.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA8B,MAAM,OAAO,CAAC;AAInD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAIrD,MAAM,WAAW,oBAAoB;IACnC,2CAA2C;IAC3C,WAAW,EAAE,YAAY,CAAC;IAC1B;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAED,wBAAgB,eAAe,CAAC,EAAE,WAAW,EAAE,OAAe,EAAE,QAAQ,EAAE,EAAE,oBAAoB,2CAuB/F;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,YAAY,GAAG,KAAK,CAAC,aAAa,CAUjF"}

package/lib/typescript/module/theme/color-scope/style-builder.d.ts

@@ -0,0 +1,8 @@
+import type { AppColorName } from '../color-presets';
+/**
+ * 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.
+ */
+export declare function buildScopeVars(colorPreset: AppColorName, mode: 'light' | 'dark'): Record<string, string>;
+//# sourceMappingURL=style-builder.d.ts.map

package/lib/typescript/module/theme/color-scope/style-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"style-builder.d.ts","sourceRoot":"","sources":["../../../../../src/theme/color-scope/style-builder.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,WAAW,EAAE,YAAY,EACzB,IAAI,EAAE,OAAO,GAAG,MAAM,GACrB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAExB"}

package/lib/typescript/module/theme/index.d.ts

@@ -1,10 +1,14 @@
-export { BloomThemeProvider, BloomColorScope } from './BloomThemeProvider';
-export type { BloomThemeProviderProps, BloomThemeContextValue, BloomColorScopeProps, } from './BloomThemeProvider';
+export { BloomThemeProvider } from './BloomThemeProvider';
+export type { BloomThemeProviderProps, BloomThemeContextValue, } from './BloomThemeProvider';
+export { BloomColorScope, useColorScopeStyle } from './color-scope';
+export type { BloomColorScopeProps } from './color-scope';
 export { buildTheme, STATUS_COLORS } from './build-theme';
 export { useTheme, useThemeColor, useBloomTheme } from './use-theme';
 export type { Theme, ThemeColors, ThemeMode } from './types';
 export type { AppColorName, AppColorPreset, PresetTokens } from './color-presets';
-export { APP_COLOR_NAMES, APP_COLOR_PRESETS, HEX_TO_APP_COLOR, hexToAppColorName, } from './color-presets';
+export { APP_COLOR_NAMES, PREMIUM_COLOR_NAMES, APP_COLOR_PRESETS, HEX_TO_APP_COLOR, hexToAppColorName, } from './color-presets';
+export { getPresetVars, applyPresetVarsToDocument, } from './preset-vars';
+export type { PresetVarsOptions } from './preset-vars';
 export { applyDarkClass } from './apply-dark-class';
 export { setColorSchemeSafe } from './set-color-scheme-safe';
 export { initCssInteropDarkMode } from './init-css-interop';

package/lib/typescript/module/theme/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/theme/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC3E,YAAY,EACV,uBAAuB,EACvB,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACrE,YAAY,EAAE,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAC7D,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAClF,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,YAAY,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAC5E,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/theme/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,YAAY,EACV,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACpE,YAAY,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACrE,YAAY,EAAE,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAC7D,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAClF,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,aAAa,EACb,yBAAyB,GAC1B,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,YAAY,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAC5E,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC"}

package/lib/typescript/module/theme/preset-vars.d.ts

@@ -0,0 +1,28 @@
+import { type AppColorName, type PresetTokens } from './color-presets';
+export interface PresetVarsOptions {
+    /**
+     * Also emit Tailwind v4 resolved `--color-*` vars (wrapped in `hsl(...)`)
+     * alongside the raw HSL triples. Needed when scoping a subtree where
+     * Tailwind's `@theme` block has already precomputed `--color-*` at `:root`,
+     * so overriding `--background` alone wouldn't cascade to `bg-background`.
+     * Default `false`.
+     */
+    includeResolvedColorVars?: boolean;
+}
+/**
+ * Bloom's base preset tokens extended with the surface/card/chart/sidebar
+ * tokens that apps layer on top of the core shadcn palette. Synthesized from
+ * the preset's primary hue so every preset stays in sync automatically.
+ *
+ * This is the single source of truth for extended theming vars — consumer apps
+ * must not redefine these per-app.
+ */
+export declare function getPresetVars(colorName: AppColorName, mode: 'light' | 'dark', options?: PresetVarsOptions): PresetTokens;
+/**
+ * Apply a preset's extended vars to `document.documentElement`. Web-only no-op
+ * 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.
+ */
+export declare function applyPresetVarsToDocument(colorName: AppColorName, mode: 'light' | 'dark', options?: PresetVarsOptions): void;
+//# sourceMappingURL=preset-vars.d.ts.map

package/lib/typescript/module/theme/preset-vars.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preset-vars.d.ts","sourceRoot":"","sources":["../../../../src/theme/preset-vars.ts"],"names":[],"mappings":"AACA,OAAO,EAAqB,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAiC1F,MAAM,WAAW,iBAAiB;IAChC;;;;;;OAMG;IACH,wBAAwB,CAAC,EAAE,OAAO,CAAC;CACpC;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,YAAY,EACvB,IAAI,EAAE,OAAO,GAAG,MAAM,EACtB,OAAO,GAAE,iBAAsB,GAC9B,YAAY,CAqCd;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,YAAY,EACvB,IAAI,EAAE,OAAO,GAAG,MAAM,EACtB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,IAAI,CAQN"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/bloom",
-  "version": "0.6.15",
+  "version": "0.6.17",
   "description": "Bloom UI — Oxy ecosystem component library for React Native + Expo + Web",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",

package/src/__tests__/BloomColorScope.test.tsx

@@ -0,0 +1,53 @@
+import React from 'react';
+import { Text } from 'react-native';
+import { render } from '@testing-library/react-native';
+
+import { BloomThemeProvider } from '../theme/BloomThemeProvider';
+import { BloomColorScope } from '../theme/color-scope';
+import { useBloomTheme } from '../theme/use-theme';
+
+function CurrentPreset() {
+  const { colorPreset } = useBloomTheme();
+  return <Text testID="preset">{colorPreset}</Text>;
+}
+
+describe('BloomColorScope', () => {
+  it('overrides the colorPreset of its subtree without affecting the parent', () => {
+    const { getAllByTestId } = render(
+      <BloomThemeProvider defaultColorPreset="blue" fonts={false}>
+        <CurrentPreset />
+        <BloomColorScope colorPreset="green">
+          <CurrentPreset />
+        </BloomColorScope>
+      </BloomThemeProvider>,
+    );
+
+    const presets = getAllByTestId('preset').map((node) => node.props.children);
+    expect(presets[0]).toBe('blue');
+    expect(presets[1]).toBe('green');
+  });
+
+  it('renders children directly with asChild (no wrapper element)', () => {
+    const { getByTestId } = render(
+      <BloomThemeProvider defaultColorPreset="blue" fonts={false}>
+        <BloomColorScope colorPreset="purple" asChild>
+          <CurrentPreset />
+        </BloomColorScope>
+      </BloomThemeProvider>,
+    );
+
+    expect(getByTestId('preset').props.children).toBe('purple');
+  });
+
+  it('throws when used outside BloomThemeProvider', () => {
+    const consoleError = jest.spyOn(console, 'error').mockImplementation(() => {});
+    expect(() =>
+      render(
+        <BloomColorScope colorPreset="red">
+          <CurrentPreset />
+        </BloomColorScope>,
+      ),
+    ).toThrow('BloomColorScope must be used within a <BloomThemeProvider>');
+    consoleError.mockRestore();
+  });
+});

package/src/__tests__/preset-vars.test.ts

@@ -0,0 +1,58 @@
+import { APP_COLOR_NAMES, APP_COLOR_PRESETS } from '../theme/color-presets';
+import { getPresetVars } from '../theme/preset-vars';
+
+const EXTENDED_KEYS = [
+  '--card',
+  '--card-foreground',
+  '--chart-1',
+  '--chart-2',
+  '--chart-3',
+  '--chart-4',
+  '--chart-5',
+  '--content-area',
+  '--sidebar-foreground',
+  '--sidebar-primary',
+  '--sidebar-primary-foreground',
+  '--sidebar-accent',
+  '--sidebar-accent-foreground',
+  '--sidebar-border',
+  '--sidebar-ring',
+] as const;
+
+describe('getPresetVars', () => {
+  it('includes every base preset token plus extended tokens for all presets and modes', () => {
+    for (const name of APP_COLOR_NAMES) {
+      for (const mode of ['light', 'dark'] as const) {
+        const vars = getPresetVars(name, mode);
+        const base = mode === 'light' ? APP_COLOR_PRESETS[name].light : APP_COLOR_PRESETS[name].dark;
+
+        for (const key of Object.keys(base)) {
+          expect(vars[key]).toBe(base[key]);
+        }
+        for (const key of EXTENDED_KEYS) {
+          expect(vars[key]).toBeDefined();
+        }
+      }
+    }
+  });
+
+  it('derives chart/sidebar hue from the preset primary', () => {
+    const vars = getPresetVars('blue', 'light');
+    const primary = APP_COLOR_PRESETS.blue.light['--primary'] ?? '';
+    const primaryHue = primary.split(' ')[0] ?? '';
+    const chart1 = vars['--chart-1'] ?? '';
+    expect(chart1.startsWith(`${primaryHue} `)).toBe(true);
+    expect(vars['--sidebar-primary']).toBe(primary);
+  });
+
+  it('does not emit resolved --color-* vars by default', () => {
+    const vars = getPresetVars('green', 'dark');
+    expect(vars['--color-primary']).toBeUndefined();
+  });
+
+  it('emits resolved --color-* vars wrapped in hsl() when requested', () => {
+    const vars = getPresetVars('green', 'dark', { includeResolvedColorVars: true });
+    expect(vars['--color-primary']).toBe(`hsl(${APP_COLOR_PRESETS.green.dark['--primary']})`);
+    expect(vars['--color-card']).toBe(`hsl(${vars['--card']})`);
+  });
+});

package/src/theme/BloomThemeProvider.tsx

@@ -304,27 +304,4 @@ export function BloomThemeProvider({
   );
 }
 
-/**
- * Scoped color override for a subtree. Inherits the resolved mode from the
- * parent `BloomThemeProvider` but renders descendants with a different preset.
- */
-export interface BloomColorScopeProps {
-  colorPreset: AppColorName;
-  children: React.ReactNode;
-}
-
-export function BloomColorScope({ colorPreset, children }: BloomColorScopeProps) {
-  const parent = useContext(BloomThemeContext);
-  if (!parent) {
-    throw new Error('BloomColorScope must be used within a <BloomThemeProvider>');
-  }
 
-  const contextValue = useMemo<BloomThemeContextValue>(() => {
-    const theme = buildTheme(colorPreset, parent.theme.mode);
-    return { ...parent, theme, colorPreset };
-  }, [colorPreset, parent]);
-
-  return (
-    <BloomThemeContext.Provider value={contextValue}>{children}</BloomThemeContext.Provider>
-  );
-}

package/src/theme/color-presets.ts

@@ -25,6 +25,9 @@ export interface AppColorPreset {
 
 export const APP_COLOR_NAMES: readonly AppColorName[] = ['teal', 'blue', 'green', 'amber', 'yellow', 'red', 'purple', 'pink', 'sky', 'orange', 'mint', 'oxy', 'faircoin'];
 
+/** Premium-exclusive presets, hidden from the standard color picker. */
+export const PREMIUM_COLOR_NAMES: readonly AppColorName[] = ['oxy', 'faircoin'];
+
 export const HEX_TO_APP_COLOR: Record<string, AppColorName> = {
   '#005c67': 'teal',
   '#1d9bf0': 'blue',

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

@@ -0,0 +1,80 @@
+import React, { useContext, useMemo } from 'react';
+import { View, type StyleProp, type ViewStyle } from 'react-native';
+
+import { BloomThemeContext, type BloomThemeContextValue } from '../BloomThemeProvider';
+import { buildTheme } from '../build-theme';
+import type { AppColorName } from '../color-presets';
+import { lazyRequire } from '../../utils/lazy-require';
+import { buildScopeVars } from './style-builder';
+
+interface NativeWindVarsModule {
+  vars: (record: Record<string, string>) => StyleProp<ViewStyle>;
+}
+
+const getNativeWindVars = lazyRequire<NativeWindVarsModule>('nativewind');
+
+function presetStyle(colorPreset: AppColorName, mode: 'light' | 'dark'): StyleProp<ViewStyle> {
+  const module = getNativeWindVars();
+  if (!module || typeof module.vars !== 'function') return undefined;
+  return module.vars(buildScopeVars(colorPreset, mode));
+}
+
+export interface BloomColorScopeProps {
+  /** Preset to apply within this subtree. */
+  colorPreset: AppColorName;
+  /**
+   * When `true`, do not render a wrapping `<View>`. The caller owns the
+   * element that receives the CSS vars (via `useColorScopeStyle`).
+   */
+  asChild?: boolean;
+  /** Additional style applied to the wrapping `<View>`. Ignored with `asChild`. */
+  style?: StyleProp<ViewStyle>;
+  children: React.ReactNode;
+}
+
+export function BloomColorScope({
+  colorPreset,
+  asChild = false,
+  style,
+  children,
+}: BloomColorScopeProps) {
+  const parent = useContext(BloomThemeContext);
+  if (!parent) {
+    throw new Error('BloomColorScope must be used within a <BloomThemeProvider>');
+  }
+
+  const resolvedMode = parent.theme.mode;
+
+  const contextValue = useMemo<BloomThemeContextValue>(() => {
+    const theme = buildTheme(colorPreset, resolvedMode);
+    return { ...parent, theme, colorPreset };
+  }, [colorPreset, resolvedMode, parent]);
+
+  const varsStyle = useMemo(
+    () => presetStyle(colorPreset, resolvedMode),
+    [colorPreset, resolvedMode],
+  );
+
+  return (
+    <BloomThemeContext.Provider value={contextValue}>
+      {asChild ? children : <View style={[{ flex: 1 }, varsStyle, style]}>{children}</View>}
+    </BloomThemeContext.Provider>
+  );
+}
+
+/**
+ * Escape hatch for advanced cases where the wrapping element is owned by the
+ * caller. Returns a stable native style object carrying the preset's CSS vars.
+ * Returns `undefined` when nativewind is not installed.
+ */
+export function useColorScopeStyle(colorPreset: AppColorName): StyleProp<ViewStyle> {
+  const parent = useContext(BloomThemeContext);
+  if (!parent) {
+    throw new Error('useColorScopeStyle must be used within a <BloomThemeProvider>');
+  }
+  const resolvedMode = parent.theme.mode;
+  return useMemo(
+    () => presetStyle(colorPreset, resolvedMode),
+    [colorPreset, resolvedMode],
+  );
+}

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

@@ -0,0 +1,62 @@
+import React, { useContext, useMemo } from 'react';
+
+import { BloomThemeContext } from '../BloomThemeProvider';
+import { buildTheme } from '../build-theme';
+import type { AppColorName } from '../color-presets';
+import { BloomThemeContextValue } from '../BloomThemeProvider';
+import { buildScopeVars } from './style-builder';
+
+export interface BloomColorScopeProps {
+  /** Preset to apply within this subtree. */
+  colorPreset: AppColorName;
+  /**
+   * When `true`, do not render a wrapping element. The caller is responsible
+   * for placing the returned context provider over a DOM node that owns the
+   * CSS vars (via `useColorScopeStyle`).
+   */
+  asChild?: boolean;
+  children: React.ReactNode;
+}
+
+export function BloomColorScope({ colorPreset, asChild = false, children }: BloomColorScopeProps) {
+  const parent = useContext(BloomThemeContext);
+  if (!parent) {
+    throw new Error('BloomColorScope must be used within a <BloomThemeProvider>');
+  }
+
+  const resolvedMode = parent.theme.mode;
+
+  const contextValue = useMemo<BloomThemeContextValue>(() => {
+    const theme = buildTheme(colorPreset, resolvedMode);
+    return { ...parent, theme, colorPreset };
+  }, [colorPreset, resolvedMode, parent]);
+
+  const style = useMemo(
+    () => buildScopeVars(colorPreset, resolvedMode) as React.CSSProperties,
+    [colorPreset, resolvedMode],
+  );
+
+  return (
+    <BloomThemeContext.Provider value={contextValue}>
+      {asChild ? children : <div style={style}>{children}</div>}
+    </BloomThemeContext.Provider>
+  );
+}
+
+/**
+ * Escape hatch for advanced cases where the wrapping element is owned by the
+ * caller (e.g. a Pressable, a NativeWind-styled View that already has a style
+ * prop). Returns a stable React `style` object carrying every CSS custom
+ * property of the preset.
+ */
+export function useColorScopeStyle(colorPreset: AppColorName): React.CSSProperties {
+  const parent = useContext(BloomThemeContext);
+  if (!parent) {
+    throw new Error('useColorScopeStyle must be used within a <BloomThemeProvider>');
+  }
+  const resolvedMode = parent.theme.mode;
+  return useMemo(
+    () => buildScopeVars(colorPreset, resolvedMode) as React.CSSProperties,
+    [colorPreset, resolvedMode],
+  );
+}

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

@@ -0,0 +1,14 @@
+import { getPresetVars } from '../preset-vars';
+import type { AppColorName } from '../color-presets';
+
+/**
+ * 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.
+ */
+export function buildScopeVars(
+  colorPreset: AppColorName,
+  mode: 'light' | 'dark',
+): Record<string, string> {
+  return getPresetVars(colorPreset, mode, { includeResolvedColorVars: true });
+}

package/src/theme/index.ts

@@ -1,19 +1,26 @@
-export { BloomThemeProvider, BloomColorScope } from './BloomThemeProvider';
+export { BloomThemeProvider } from './BloomThemeProvider';
 export type {
   BloomThemeProviderProps,
   BloomThemeContextValue,
-  BloomColorScopeProps,
 } from './BloomThemeProvider';
+export { BloomColorScope, useColorScopeStyle } from './color-scope';
+export type { BloomColorScopeProps } from './color-scope';
 export { buildTheme, STATUS_COLORS } from './build-theme';
 export { useTheme, useThemeColor, useBloomTheme } from './use-theme';
 export type { Theme, ThemeColors, ThemeMode } from './types';
 export type { AppColorName, AppColorPreset, PresetTokens } from './color-presets';
 export {
   APP_COLOR_NAMES,
+  PREMIUM_COLOR_NAMES,
   APP_COLOR_PRESETS,
   HEX_TO_APP_COLOR,
   hexToAppColorName,
 } from './color-presets';
+export {
+  getPresetVars,
+  applyPresetVarsToDocument,
+} from './preset-vars';
+export type { PresetVarsOptions } 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/preset-vars.ts

@@ -0,0 +1,115 @@
+import { Platform } from 'react-native';
+import { APP_COLOR_PRESETS, type AppColorName, type PresetTokens } from './color-presets';
+
+function extractHue(hslVar: string): number {
+  return parseInt(hslVar.split(' ')[0] ?? '0', 10);
+}
+
+function extractSat(hslVar: string): number {
+  return parseInt(hslVar.split(' ')[1] ?? '0', 10);
+}
+
+const RESOLVED_COLOR_MAP: Record<string, string> = {
+  '--background': '--color-background',
+  '--foreground': '--color-foreground',
+  '--primary': '--color-primary',
+  '--primary-foreground': '--color-primary-foreground',
+  '--secondary': '--color-secondary',
+  '--secondary-foreground': '--color-secondary-foreground',
+  '--muted': '--color-muted',
+  '--muted-foreground': '--color-muted-foreground',
+  '--accent': '--color-accent',
+  '--accent-foreground': '--color-accent-foreground',
+  '--destructive': '--color-destructive',
+  '--border': '--color-border',
+  '--input': '--color-input',
+  '--ring': '--color-ring',
+  '--popover': '--color-popover',
+  '--popover-foreground': '--color-popover-foreground',
+  '--surface': '--color-surface',
+  '--surface-foreground': '--color-surface-foreground',
+  '--card': '--color-card',
+  '--card-foreground': '--color-card-foreground',
+};
+
+export interface PresetVarsOptions {
+  /**
+   * Also emit Tailwind v4 resolved `--color-*` vars (wrapped in `hsl(...)`)
+   * alongside the raw HSL triples. Needed when scoping a subtree where
+   * Tailwind's `@theme` block has already precomputed `--color-*` at `:root`,
+   * so overriding `--background` alone wouldn't cascade to `bg-background`.
+   * Default `false`.
+   */
+  includeResolvedColorVars?: boolean;
+}
+
+/**
+ * Bloom's base preset tokens extended with the surface/card/chart/sidebar
+ * tokens that apps layer on top of the core shadcn palette. Synthesized from
+ * the preset's primary hue so every preset stays in sync automatically.
+ *
+ * This is the single source of truth for extended theming vars — consumer apps
+ * must not redefine these per-app.
+ */
+export function getPresetVars(
+  colorName: AppColorName,
+  mode: 'light' | 'dark',
+  options: PresetVarsOptions = {},
+): PresetTokens {
+  const preset = APP_COLOR_PRESETS[colorName];
+  const base = mode === 'light' ? preset.light : preset.dark;
+  const get = (key: string): string => base[key] ?? '0 0% 0%';
+  const primary = get('--primary');
+  const foreground = get('--foreground');
+  const hue = extractHue(primary);
+  const sat = Math.min(extractSat(primary), 80);
+  const isDark = mode === 'dark';
+
+  const extended: PresetTokens = {
+    ...base,
+    '--card': isDark ? `${hue} 30% 10%` : '0 0% 100%',
+    '--card-foreground': foreground,
+    '--chart-1': `${hue} ${sat}% 85%`,
+    '--chart-2': `${hue} ${sat}% 75%`,
+    '--chart-3': `${hue} ${sat}% 65%`,
+    '--chart-4': `${hue} ${sat}% ${isDark ? 55 : 75}%`,
+    '--chart-5': `${hue} ${sat}% ${isDark ? 45 : 65}%`,
+    '--content-area': isDark ? `${hue} 30% 8%` : get('--surface'),
+    '--sidebar-foreground': foreground,
+    '--sidebar-primary': primary,
+    '--sidebar-primary-foreground': get('--primary-foreground'),
+    '--sidebar-accent': isDark ? get('--sidebar') : get('--accent'),
+    '--sidebar-accent-foreground': isDark ? foreground : get('--accent-foreground'),
+    '--sidebar-border': get('--border'),
+    '--sidebar-ring': get('--ring'),
+  };
+
+  if (!options.includeResolvedColorVars) return extended;
+
+  const resolved: PresetTokens = { ...extended };
+  for (const [rawKey, colorKey] of Object.entries(RESOLVED_COLOR_MAP)) {
+    const value = extended[rawKey];
+    if (value) resolved[colorKey] = `hsl(${value})`;
+  }
+  return resolved;
+}
+
+/**
+ * Apply a preset's extended vars to `document.documentElement`. Web-only no-op
+ * 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.
+ */
+export function applyPresetVarsToDocument(
+  colorName: AppColorName,
+  mode: 'light' | 'dark',
+  options?: PresetVarsOptions,
+): void {
+  if (Platform.OS !== 'web' || typeof document === 'undefined') return;
+
+  const vars = getPresetVars(colorName, mode, options);
+  const root = document.documentElement.style;
+  for (const [key, value] of Object.entries(vars)) {
+    root.setProperty(key, value);
+  }
+}