@oxyhq/bloom 0.39.0 → 0.40.0

package/lib/module/theme/seed-scope/index.web.js

@@ -0,0 +1,81 @@
+"use strict";
+
+import React, { Children, cloneElement, isValidElement, useContext, useMemo } from 'react';
+import { BloomThemeContext } from "../BloomThemeProvider.js";
+import { buildSeedScopeVars } from "../color-scope/seed-scope.js";
+import { buildThemeFromSeed } from "../build-theme-from-seed.js";
+
+/**
+ * On web the single `asChild` child is frequently a react-native-web component
+ * whose `style` prop is a style ARRAY (or a numeric registered-style id), not a
+ * plain object. Spreading such an array into an object literal would copy its
+ * numeric indices as keys and crash RNW; merge as an array instead.
+ */
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Web `<BloomSeedScope>`: scopes a subtree to an ARBITRARY seed colour's palette
+ * (the dynamic counterpart of `<BloomColorScope>`). It (1) writes every canonical
+ * `--x` token plus the Tailwind v4 `--color-x` aliases (already resolved to
+ * `rgb(...)`) onto the wrapping element's inline `style`, so NativeWind classes
+ * inside resolve against the seed palette instead of the document root, and
+ * (2) publishes a matching JS `theme` on `BloomThemeContext` so
+ * `useTheme()`/`useBloomTheme()` consumers inside the subtree re-theme too. The
+ * `colorPreset` field is left as the parent's (a seed is not a named preset).
+ */
+export function BloomSeedScope({
+  seed,
+  variant,
+  contrastLevel,
+  asChild = false,
+  style,
+  children
+}) {
+  const parent = useContext(BloomThemeContext);
+  const resolvedMode = parent?.theme.mode ?? 'light';
+  const varsStyle = useMemo(() => seed ? buildSeedScopeVars({
+    seed,
+    mode: resolvedMode,
+    variant,
+    contrastLevel
+  }) : null, [seed, resolvedMode, variant, contrastLevel]);
+  const contextValue = useMemo(() => {
+    if (!parent || !seed) return null;
+    const theme = buildThemeFromSeed(seed, resolvedMode, variant, contrastLevel);
+    return {
+      ...parent,
+      theme
+    };
+  }, [parent, seed, resolvedMode, variant, contrastLevel]);
+  if (!parent) {
+    throw new Error('BloomSeedScope must be used within a <BloomThemeProvider>');
+  }
+  if (!varsStyle || !contextValue) return /*#__PURE__*/_jsx(_Fragment, {
+    children: children
+  });
+  let content;
+  if (asChild) {
+    const child = Children.only(children);
+    if (! /*#__PURE__*/isValidElement(child)) {
+      throw new Error('BloomSeedScope with `asChild` requires a single React element child that accepts a `style` prop.');
+    }
+    const childStyle = child.props.style;
+    const mergedStyle = [varsStyle, style, childStyle];
+    content = /*#__PURE__*/cloneElement(child, {
+      style: mergedStyle
+    });
+  } else {
+    const mergedStyle = {
+      ...varsStyle,
+      ...style
+    };
+    content = /*#__PURE__*/_jsx("div", {
+      style: mergedStyle,
+      children: children
+    });
+  }
+  return /*#__PURE__*/_jsx(BloomThemeContext.Provider, {
+    value: contextValue,
+    children: content
+  });
+}
+//# sourceMappingURL=index.web.js.map

package/lib/module/theme/seed-scope/index.web.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["React","Children","cloneElement","isValidElement","useContext","useMemo","BloomThemeContext","buildSeedScopeVars","buildThemeFromSeed","Fragment","_Fragment","jsx","_jsx","BloomSeedScope","seed","variant","contrastLevel","asChild","style","children","parent","resolvedMode","theme","mode","varsStyle","contextValue","Error","content","child","only","childStyle","props","mergedStyle","Provider","value"],"sourceRoot":"../../../../src","sources":["theme/seed-scope/index.web.tsx"],"mappings":";;AAAA,OAAOA,KAAK,IAAIC,QAAQ,EAAEC,YAAY,EAAEC,cAAc,EAAEC,UAAU,EAAEC,OAAO,QAAQ,OAAO;AAE1F,SAASC,iBAAiB,QAAqC,0BAAuB;AACtF,SAASC,kBAAkB,QAAQ,8BAA2B;AAC9D,SAASC,kBAAkB,QAAQ,6BAA0B;;AAyB7D;AACA;AACA;AACA;AACA;AACA;AALA,SAAAC,QAAA,IAAAC,SAAA,EAAAC,GAAA,IAAAC,IAAA;AAkBA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,cAAcA,CAAC;EAC7BC,IAAI;EACJC,OAAO;EACPC,aAAa;EACbC,OAAO,GAAG,KAAK;EACfC,KAAK;EACLC;AACmB,CAAC,EAAE;EACtB,MAAMC,MAAM,GAAGhB,UAAU,CAACE,iBAAiB,CAAC;EAC5C,MAAMe,YAAY,GAAGD,MAAM,EAAEE,KAAK,CAACC,IAAI,IAAI,OAAO;EAElD,MAAMC,SAAS,GAAGnB,OAAO,CACvB,MACES,IAAI,GACCP,kBAAkB,CAAC;IAClBO,IAAI;IACJS,IAAI,EAAEF,YAAY;IAClBN,OAAO;IACPC;EACF,CAAC,CAAC,GACF,IAAI,EACV,CAACF,IAAI,EAAEO,YAAY,EAAEN,OAAO,EAAEC,aAAa,CAC7C,CAAC;EAED,MAAMS,YAAY,GAAGpB,OAAO,CAAgC,MAAM;IAChE,IAAI,CAACe,MAAM,IAAI,CAACN,IAAI,EAAE,OAAO,IAAI;IACjC,MAAMQ,KAAK,GAAGd,kBAAkB,CAACM,IAAI,EAAEO,YAAY,EAAEN,OAAO,EAAEC,aAAa,CAAC;IAC5E,OAAO;MAAE,GAAGI,MAAM;MAAEE;IAAM,CAAC;EAC7B,CAAC,EAAE,CAACF,MAAM,EAAEN,IAAI,EAAEO,YAAY,EAAEN,OAAO,EAAEC,aAAa,CAAC,CAAC;EAExD,IAAI,CAACI,MAAM,EAAE;IACX,MAAM,IAAIM,KAAK,CAAC,2DAA2D,CAAC;EAC9E;EACA,IAAI,CAACF,SAAS,IAAI,CAACC,YAAY,EAAE,oBAAOb,IAAA,CAAAF,SAAA;IAAAS,QAAA,EAAGA;EAAQ,CAAG,CAAC;EAEvD,IAAIQ,OAAwB;EAC5B,IAAIV,OAAO,EAAE;IACX,MAAMW,KAAK,GAAG3B,QAAQ,CAAC4B,IAAI,CAACV,QAAQ,CAAC;IACrC,IAAI,eAAChB,cAAc,CAAiByB,KAAK,CAAC,EAAE;MAC1C,MAAM,IAAIF,KAAK,CACb,kGACF,CAAC;IACH;IACA,MAAMI,UAAU,GAAGF,KAAK,CAACG,KAAK,CAACb,KAAK;IACpC,MAAMc,WAAqB,GAAG,CAACR,SAAS,EAAEN,KAAK,EAAEY,UAAU,CAAC;IAC5DH,OAAO,gBAAGzB,YAAY,CAAC0B,KAAK,EAAE;MAAEV,KAAK,EAAEc;IAAY,CAAC,CAAC;EACvD,CAAC,MAAM;IACL,MAAMA,WAAgC,GAAG;MAAE,GAAGR,SAAS;MAAE,GAAGN;IAAM,CAAC;IACnES,OAAO,gBAAGf,IAAA;MAAKM,KAAK,EAAEc,WAAY;MAAAb,QAAA,EAAEA;IAAQ,CAAM,CAAC;EACrD;EAEA,oBAAOP,IAAA,CAACN,iBAAiB,CAAC2B,QAAQ;IAACC,KAAK,EAAET,YAAa;IAAAN,QAAA,EAAEQ;EAAO,CAA6B,CAAC;AAChG","ignoreList":[]}

package/lib/typescript/commonjs/theme/build-theme-from-seed.d.ts

@@ -0,0 +1,23 @@
+import { type SchemeVariant } from './color-engine';
+import type { Theme, ThemeColors } from './types';
+/**
+ * Build the JS `theme.colors` object from an ARBITRARY seed colour — the dynamic
+ * counterpart of `buildTheme(preset, …)`.
+ *
+ * This mirrors `buildColorsFromPreset` (`build-theme.ts`) field-for-field, but
+ * sources its tokens from `buildSeedScopeVars({ seed })` instead of a named
+ * preset, so a preset's seed reproduces that preset's JS theme exactly. Keeping
+ * the two in lockstep is enforced by `__tests__/build-theme-from-seed-parity.test.ts`.
+ *
+ * Token-backed fields read the resolved `rgb(...)` token map; the brand-tint
+ * family (primarySubtle / negative / …) reads the engine's container/error roles
+ * directly — identical to the preset path.
+ */
+export declare function buildColorsFromSeed(seed: string, resolved: 'light' | 'dark', variant?: SchemeVariant, contrastLevel?: number): ThemeColors;
+/**
+ * Build a full `Theme` from a seed colour and a resolved light/dark mode. Unlike
+ * `buildTheme`, there is no adaptive (Material You / iOS dynamic) override — a
+ * seed IS the dynamic source here.
+ */
+export declare function buildThemeFromSeed(seed: string, resolved: 'light' | 'dark', variant?: SchemeVariant, contrastLevel?: number): Theme;
+//# sourceMappingURL=build-theme-from-seed.d.ts.map

package/lib/typescript/commonjs/theme/build-theme-from-seed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-theme-from-seed.d.ts","sourceRoot":"","sources":["../../../../src/theme/build-theme-from-seed.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuC,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAIzF,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAElD;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,OAAO,GAAG,MAAM,EAC1B,OAAO,CAAC,EAAE,aAAa,EACvB,aAAa,CAAC,EAAE,MAAM,GACrB,WAAW,CAsDb;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,OAAO,GAAG,MAAM,EAC1B,OAAO,CAAC,EAAE,aAAa,EACvB,aAAa,CAAC,EAAE,MAAM,GACrB,KAAK,CAQP"}

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

@@ -2,7 +2,14 @@ export { BloomThemeProvider } from './BloomThemeProvider';
 export type { BloomThemeProviderProps, BloomThemeContextValue, } from './BloomThemeProvider';
 export { BloomColorScope, useColorScopeStyle } from './color-scope';
 export type { BloomColorScopeProps } from './color-scope';
+export { BloomSeedScope } from './seed-scope';
+export type { BloomSeedScopeProps } from './seed-scope';
+export { buildSeedScopeVars, roleColorsToPresetTokens } from './color-scope/seed-scope';
+export type { SeedScopeOptions } from './color-scope/seed-scope';
+export { generateRoleColors, seedHexFromImagePixels, seedsFromImagePixels, quantizeImage, argbFromHex, hexFromArgb, argbFromRgb, redFromArgb, greenFromArgb, blueFromArgb, } from './color-engine';
+export type { RoleColors, GenerateOptions, RoleName, SchemeVariant } from './color-engine';
 export { buildTheme, STATUS_COLORS } from './build-theme';
+export { buildThemeFromSeed, buildColorsFromSeed } from './build-theme-from-seed';
 export { THEME_GRADIENTS } from './gradients';
 export { useTheme, useThemeColor, useBloomTheme } from './use-theme';
 export { useNavigationTheme } from './use-navigation-theme';

package/lib/typescript/commonjs/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,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,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,YAAY,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AACnF,YAAY,EAAE,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAC5F,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,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AACpD,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AACzE,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,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,YAAY,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACxF,YAAY,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAIjE,OAAO,EACL,kBAAkB,EAClB,sBAAsB,EACtB,oBAAoB,EACpB,aAAa,EACb,WAAW,EACX,WAAW,EACX,WAAW,EACX,WAAW,EACX,aAAa,EACb,YAAY,GACb,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC3F,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAClF,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,YAAY,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AACnF,YAAY,EAAE,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAC5F,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,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AACpD,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AACzE,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/commonjs/theme/seed-scope/index.d.ts

@@ -0,0 +1,37 @@
+import React from 'react';
+import { type StyleProp, type ViewStyle } from 'react-native';
+import type { SchemeVariant } from '../color-engine';
+export interface BloomSeedScopeProps {
+    /**
+     * The seed colour (`#rrggbb`) to derive this subtree's palette from. When
+     * `undefined`, the scope is a no-op and children inherit the parent scope
+     * unchanged — pass `undefined` to fall back to the app preset (e.g. on
+     * mouse-leave/blur when restoring the default theme).
+     */
+    seed: string | undefined;
+    /** Tonal scheme variant. Defaults to `'vibrant'` (matches Bloom presets). */
+    variant?: SchemeVariant;
+    /** −1 (low) … 0 (normal) … 1 (high). Defaults to 0. */
+    contrastLevel?: number;
+    /**
+     * When `true`, do not render a wrapping `<View>`. The single child is cloned
+     * with the caller's `style` merged into its `style` prop (Radix-style).
+     */
+    asChild?: boolean;
+    /** Additional style applied to the wrapping `<View>` (or merged into the cloned child with `asChild`). */
+    style?: StyleProp<ViewStyle>;
+    children: React.ReactNode;
+}
+/**
+ * Native `<BloomSeedScope>`: scopes a subtree to an ARBITRARY seed colour's
+ * palette (the dynamic counterpart of `<BloomColorScope>`, which takes a named
+ * preset). Feeds the seed through the colour engine and (1) provides the
+ * resulting canonical CSS vars to descendants via react-native-css's
+ * `VariableContext` — so `bg-background` / `bg-card` / `var(--primary)` resolve
+ * against the seed inside this subtree — and (2) publishes a matching JS `theme`
+ * on `BloomThemeContext`, so `useTheme()`/`useBloomTheme()` consumers inside the
+ * subtree also re-theme. The `colorPreset` field is left as the parent's (a seed
+ * is not a named preset).
+ */
+export declare function BloomSeedScope({ seed, variant, contrastLevel, asChild, style, children, }: BloomSeedScopeProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/commonjs/theme/seed-scope/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/theme/seed-scope/index.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAsE,MAAM,OAAO,CAAC;AAC3F,OAAO,EAAQ,KAAK,SAAS,EAAE,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AAMpE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErD,MAAM,WAAW,mBAAmB;IAClC;;;;;OAKG;IACH,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,6EAA6E;IAC7E,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,uDAAuD;IACvD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,0GAA0G;IAC1G,KAAK,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IAC7B,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,EAC7B,IAAI,EACJ,OAAO,EACP,aAAa,EACb,OAAe,EACf,KAAK,EACL,QAAQ,GACT,EAAE,mBAAmB,2CA8CrB"}

package/lib/typescript/commonjs/theme/seed-scope/index.web.d.ts

@@ -0,0 +1,35 @@
+import React from 'react';
+import type { SchemeVariant } from '../color-engine';
+export interface BloomSeedScopeProps {
+    /**
+     * The seed colour (`#rrggbb`) to derive this subtree's palette from. When
+     * `undefined`, the scope is a no-op and children inherit the parent scope
+     * unchanged — pass `undefined` to fall back to the app preset (e.g. on
+     * mouse-leave/blur when restoring the default theme).
+     */
+    seed: string | undefined;
+    /** Tonal scheme variant. Defaults to `'vibrant'` (matches Bloom presets). */
+    variant?: SchemeVariant;
+    /** −1 (low) … 0 (normal) … 1 (high). Defaults to 0. */
+    contrastLevel?: number;
+    /**
+     * When `true`, do not render a wrapping `<div>`. The single child is cloned
+     * with the scope's CSS vars merged into its `style` prop (Radix-style).
+     */
+    asChild?: boolean;
+    /** Additional style applied to the wrapping `<div>` (or merged into the cloned child with `asChild`). */
+    style?: React.CSSProperties;
+    children: React.ReactNode;
+}
+/**
+ * Web `<BloomSeedScope>`: scopes a subtree to an ARBITRARY seed colour's palette
+ * (the dynamic counterpart of `<BloomColorScope>`). It (1) writes every canonical
+ * `--x` token plus the Tailwind v4 `--color-x` aliases (already resolved to
+ * `rgb(...)`) onto the wrapping element's inline `style`, so NativeWind classes
+ * inside resolve against the seed palette instead of the document root, and
+ * (2) publishes a matching JS `theme` on `BloomThemeContext` so
+ * `useTheme()`/`useBloomTheme()` consumers inside the subtree re-theme too. The
+ * `colorPreset` field is left as the parent's (a seed is not a named preset).
+ */
+export declare function BloomSeedScope({ seed, variant, contrastLevel, asChild, style, children, }: BloomSeedScopeProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=index.web.d.ts.map

package/lib/typescript/commonjs/theme/seed-scope/index.web.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.web.d.ts","sourceRoot":"","sources":["../../../../../src/theme/seed-scope/index.web.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAsE,MAAM,OAAO,CAAC;AAK3F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErD,MAAM,WAAW,mBAAmB;IAClC;;;;;OAKG;IACH,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,6EAA6E;IAC7E,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,uDAAuD;IACvD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,yGAAyG;IACzG,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;IAC5B,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAoBD;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,EAC7B,IAAI,EACJ,OAAO,EACP,aAAa,EACb,OAAe,EACf,KAAK,EACL,QAAQ,GACT,EAAE,mBAAmB,2CA6CrB"}

package/lib/typescript/module/theme/build-theme-from-seed.d.ts

@@ -0,0 +1,23 @@
+import { type SchemeVariant } from './color-engine';
+import type { Theme, ThemeColors } from './types';
+/**
+ * Build the JS `theme.colors` object from an ARBITRARY seed colour — the dynamic
+ * counterpart of `buildTheme(preset, …)`.
+ *
+ * This mirrors `buildColorsFromPreset` (`build-theme.ts`) field-for-field, but
+ * sources its tokens from `buildSeedScopeVars({ seed })` instead of a named
+ * preset, so a preset's seed reproduces that preset's JS theme exactly. Keeping
+ * the two in lockstep is enforced by `__tests__/build-theme-from-seed-parity.test.ts`.
+ *
+ * Token-backed fields read the resolved `rgb(...)` token map; the brand-tint
+ * family (primarySubtle / negative / …) reads the engine's container/error roles
+ * directly — identical to the preset path.
+ */
+export declare function buildColorsFromSeed(seed: string, resolved: 'light' | 'dark', variant?: SchemeVariant, contrastLevel?: number): ThemeColors;
+/**
+ * Build a full `Theme` from a seed colour and a resolved light/dark mode. Unlike
+ * `buildTheme`, there is no adaptive (Material You / iOS dynamic) override — a
+ * seed IS the dynamic source here.
+ */
+export declare function buildThemeFromSeed(seed: string, resolved: 'light' | 'dark', variant?: SchemeVariant, contrastLevel?: number): Theme;
+//# sourceMappingURL=build-theme-from-seed.d.ts.map

package/lib/typescript/module/theme/build-theme-from-seed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-theme-from-seed.d.ts","sourceRoot":"","sources":["../../../../src/theme/build-theme-from-seed.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuC,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAIzF,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAElD;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,OAAO,GAAG,MAAM,EAC1B,OAAO,CAAC,EAAE,aAAa,EACvB,aAAa,CAAC,EAAE,MAAM,GACrB,WAAW,CAsDb;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,OAAO,GAAG,MAAM,EAC1B,OAAO,CAAC,EAAE,aAAa,EACvB,aAAa,CAAC,EAAE,MAAM,GACrB,KAAK,CAQP"}

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

@@ -2,7 +2,14 @@ export { BloomThemeProvider } from './BloomThemeProvider';
 export type { BloomThemeProviderProps, BloomThemeContextValue, } from './BloomThemeProvider';
 export { BloomColorScope, useColorScopeStyle } from './color-scope';
 export type { BloomColorScopeProps } from './color-scope';
+export { BloomSeedScope } from './seed-scope';
+export type { BloomSeedScopeProps } from './seed-scope';
+export { buildSeedScopeVars, roleColorsToPresetTokens } from './color-scope/seed-scope';
+export type { SeedScopeOptions } from './color-scope/seed-scope';
+export { generateRoleColors, seedHexFromImagePixels, seedsFromImagePixels, quantizeImage, argbFromHex, hexFromArgb, argbFromRgb, redFromArgb, greenFromArgb, blueFromArgb, } from './color-engine';
+export type { RoleColors, GenerateOptions, RoleName, SchemeVariant } from './color-engine';
 export { buildTheme, STATUS_COLORS } from './build-theme';
+export { buildThemeFromSeed, buildColorsFromSeed } from './build-theme-from-seed';
 export { THEME_GRADIENTS } from './gradients';
 export { useTheme, useThemeColor, useBloomTheme } from './use-theme';
 export { useNavigationTheme } from './use-navigation-theme';

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,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,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,YAAY,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AACnF,YAAY,EAAE,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAC5F,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,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AACpD,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AACzE,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,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,YAAY,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACxF,YAAY,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAIjE,OAAO,EACL,kBAAkB,EAClB,sBAAsB,EACtB,oBAAoB,EACpB,aAAa,EACb,WAAW,EACX,WAAW,EACX,WAAW,EACX,WAAW,EACX,aAAa,EACb,YAAY,GACb,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC3F,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAClF,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,YAAY,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AACnF,YAAY,EAAE,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAC5F,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,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AACpD,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC;AACzE,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/seed-scope/index.d.ts

@@ -0,0 +1,37 @@
+import React from 'react';
+import { type StyleProp, type ViewStyle } from 'react-native';
+import type { SchemeVariant } from '../color-engine';
+export interface BloomSeedScopeProps {
+    /**
+     * The seed colour (`#rrggbb`) to derive this subtree's palette from. When
+     * `undefined`, the scope is a no-op and children inherit the parent scope
+     * unchanged — pass `undefined` to fall back to the app preset (e.g. on
+     * mouse-leave/blur when restoring the default theme).
+     */
+    seed: string | undefined;
+    /** Tonal scheme variant. Defaults to `'vibrant'` (matches Bloom presets). */
+    variant?: SchemeVariant;
+    /** −1 (low) … 0 (normal) … 1 (high). Defaults to 0. */
+    contrastLevel?: number;
+    /**
+     * When `true`, do not render a wrapping `<View>`. The single child is cloned
+     * with the caller's `style` merged into its `style` prop (Radix-style).
+     */
+    asChild?: boolean;
+    /** Additional style applied to the wrapping `<View>` (or merged into the cloned child with `asChild`). */
+    style?: StyleProp<ViewStyle>;
+    children: React.ReactNode;
+}
+/**
+ * Native `<BloomSeedScope>`: scopes a subtree to an ARBITRARY seed colour's
+ * palette (the dynamic counterpart of `<BloomColorScope>`, which takes a named
+ * preset). Feeds the seed through the colour engine and (1) provides the
+ * resulting canonical CSS vars to descendants via react-native-css's
+ * `VariableContext` — so `bg-background` / `bg-card` / `var(--primary)` resolve
+ * against the seed inside this subtree — and (2) publishes a matching JS `theme`
+ * on `BloomThemeContext`, so `useTheme()`/`useBloomTheme()` consumers inside the
+ * subtree also re-theme. The `colorPreset` field is left as the parent's (a seed
+ * is not a named preset).
+ */
+export declare function BloomSeedScope({ seed, variant, contrastLevel, asChild, style, children, }: BloomSeedScopeProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/theme/seed-scope/index.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAsE,MAAM,OAAO,CAAC;AAC3F,OAAO,EAAQ,KAAK,SAAS,EAAE,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AAMpE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErD,MAAM,WAAW,mBAAmB;IAClC;;;;;OAKG;IACH,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,6EAA6E;IAC7E,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,uDAAuD;IACvD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,0GAA0G;IAC1G,KAAK,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IAC7B,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,EAC7B,IAAI,EACJ,OAAO,EACP,aAAa,EACb,OAAe,EACf,KAAK,EACL,QAAQ,GACT,EAAE,mBAAmB,2CA8CrB"}

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

@@ -0,0 +1,35 @@
+import React from 'react';
+import type { SchemeVariant } from '../color-engine';
+export interface BloomSeedScopeProps {
+    /**
+     * The seed colour (`#rrggbb`) to derive this subtree's palette from. When
+     * `undefined`, the scope is a no-op and children inherit the parent scope
+     * unchanged — pass `undefined` to fall back to the app preset (e.g. on
+     * mouse-leave/blur when restoring the default theme).
+     */
+    seed: string | undefined;
+    /** Tonal scheme variant. Defaults to `'vibrant'` (matches Bloom presets). */
+    variant?: SchemeVariant;
+    /** −1 (low) … 0 (normal) … 1 (high). Defaults to 0. */
+    contrastLevel?: number;
+    /**
+     * When `true`, do not render a wrapping `<div>`. The single child is cloned
+     * with the scope's CSS vars merged into its `style` prop (Radix-style).
+     */
+    asChild?: boolean;
+    /** Additional style applied to the wrapping `<div>` (or merged into the cloned child with `asChild`). */
+    style?: React.CSSProperties;
+    children: React.ReactNode;
+}
+/**
+ * Web `<BloomSeedScope>`: scopes a subtree to an ARBITRARY seed colour's palette
+ * (the dynamic counterpart of `<BloomColorScope>`). It (1) writes every canonical
+ * `--x` token plus the Tailwind v4 `--color-x` aliases (already resolved to
+ * `rgb(...)`) onto the wrapping element's inline `style`, so NativeWind classes
+ * inside resolve against the seed palette instead of the document root, and
+ * (2) publishes a matching JS `theme` on `BloomThemeContext` so
+ * `useTheme()`/`useBloomTheme()` consumers inside the subtree re-theme too. The
+ * `colorPreset` field is left as the parent's (a seed is not a named preset).
+ */
+export declare function BloomSeedScope({ seed, variant, contrastLevel, asChild, style, children, }: BloomSeedScopeProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=index.web.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.web.d.ts","sourceRoot":"","sources":["../../../../../src/theme/seed-scope/index.web.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAsE,MAAM,OAAO,CAAC;AAK3F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErD,MAAM,WAAW,mBAAmB;IAClC;;;;;OAKG;IACH,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,6EAA6E;IAC7E,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,uDAAuD;IACvD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,yGAAyG;IACzG,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;IAC5B,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAoBD;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,EAC7B,IAAI,EACJ,OAAO,EACP,aAAa,EACb,OAAe,EACf,KAAK,EACL,QAAQ,GACT,EAAE,mBAAmB,2CA6CrB"}

package/package.json

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

package/src/theme/__tests__/build-theme-from-seed-parity.test.ts

@@ -0,0 +1,33 @@
+/**
+ * Parity guard for the dynamic JS-theme seed path.
+ *
+ * A named preset is just a fixed seed, so `buildThemeFromSeed(preset.hex, mode)`
+ * MUST produce the identical `theme.colors` as the preset path
+ * `buildTheme(name, mode)`. If `buildColorsFromSeed` ever drifts from
+ * `buildColorsFromPreset`, this fails.
+ *
+ * NOTE: `buildTheme` can apply an adaptive (Material You) override on native, but
+ * this test runs under jsdom/node where `Platform.OS !== 'web'` is false and
+ * `isAdaptive` defaults to false, so the comparison is against the preset-derived
+ * palette (not adaptive), which is exactly what the seed path reproduces.
+ */
+import { APP_COLOR_NAMES, APP_COLOR_PRESETS, type AppColorName } from '../color-presets';
+import { buildTheme } from '../build-theme';
+import { buildThemeFromSeed } from '../build-theme-from-seed';
+
+describe('buildThemeFromSeed parity with buildTheme (preset)', () => {
+  const modes: Array<'light' | 'dark'> = ['light', 'dark'];
+
+  for (const name of APP_COLOR_NAMES as readonly AppColorName[]) {
+    for (const mode of modes) {
+      it(`matches preset "${name}" colours in ${mode} mode`, () => {
+        const preset = APP_COLOR_PRESETS[name];
+        const fromPreset = buildTheme(name, mode);
+        const fromSeed = buildThemeFromSeed(preset.hex, mode, preset.variant);
+        expect(fromSeed.colors).toEqual(fromPreset.colors);
+        expect(fromSeed.mode).toBe(fromPreset.mode);
+        expect(fromSeed.isDark).toBe(fromPreset.isDark);
+      });
+    }
+  }
+});

package/src/theme/build-theme-from-seed.ts

@@ -0,0 +1,99 @@
+import { generateRoleColors, type RoleColors, type SchemeVariant } from './color-engine';
+import { buildSeedScopeVars } from './color-scope/seed-scope';
+import { STATUS_COLORS } from './build-theme';
+import { THEME_GRADIENTS } from './gradients';
+import type { Theme, ThemeColors } from './types';
+
+/**
+ * Build the JS `theme.colors` object from an ARBITRARY seed colour — the dynamic
+ * counterpart of `buildTheme(preset, …)`.
+ *
+ * This mirrors `buildColorsFromPreset` (`build-theme.ts`) field-for-field, but
+ * sources its tokens from `buildSeedScopeVars({ seed })` instead of a named
+ * preset, so a preset's seed reproduces that preset's JS theme exactly. Keeping
+ * the two in lockstep is enforced by `__tests__/build-theme-from-seed-parity.test.ts`.
+ *
+ * Token-backed fields read the resolved `rgb(...)` token map; the brand-tint
+ * family (primarySubtle / negative / …) reads the engine's container/error roles
+ * directly — identical to the preset path.
+ */
+export function buildColorsFromSeed(
+  seed: string,
+  resolved: 'light' | 'dark',
+  variant?: SchemeVariant,
+  contrastLevel?: number,
+): ThemeColors {
+  const t = buildSeedScopeVars({ seed, mode: resolved, variant, contrastLevel });
+  const isDark = resolved === 'dark';
+
+  // Read a resolved `rgb(...)` token by its bare name (no leading `--`).
+  const g = (k: string): string => t[`--${k}`] ?? 'rgb(0 0 0)';
+
+  const r: RoleColors = generateRoleColors({
+    seed,
+    variant,
+    isDark,
+    contrastLevel,
+  });
+
+  return {
+    background: g('background'),
+    backgroundSecondary: g('surface'),
+    backgroundTertiary: g('popover'),
+
+    text: g('foreground'),
+    textSecondary: g('muted-foreground'),
+    textTertiary: r.outline,
+
+    border: g('border'),
+    borderLight: g('input'),
+
+    primary: g('primary'),
+    primaryForeground: g('primary-foreground'),
+    primaryLight: g('surface'),
+    primaryDark: g('background'),
+
+    secondary: g('secondary'),
+    secondaryForeground: g('secondary-foreground'),
+    tertiary: g('tertiary'),
+    tertiaryForeground: g('tertiary-foreground'),
+
+    tint: g('primary'),
+    icon: g('muted-foreground'),
+    iconActive: g('primary'),
+
+    ...STATUS_COLORS,
+
+    primarySubtle: r.primaryContainer,
+    primarySubtleForeground: r.onPrimaryContainer,
+    negative: r.error,
+    negativeForeground: r.onError,
+    negativeSubtle: r.errorContainer,
+    negativeSubtleForeground: r.onErrorContainer,
+    contrast50: g('muted'),
+
+    card: g('card'),
+    shadow: isDark ? 'rgba(0, 0, 0, 0.3)' : 'rgba(0, 0, 0, 0.1)',
+    overlay: 'rgba(0, 0, 0, 0.5)',
+  };
+}
+
+/**
+ * Build a full `Theme` from a seed colour and a resolved light/dark mode. Unlike
+ * `buildTheme`, there is no adaptive (Material You / iOS dynamic) override — a
+ * seed IS the dynamic source here.
+ */
+export function buildThemeFromSeed(
+  seed: string,
+  resolved: 'light' | 'dark',
+  variant?: SchemeVariant,
+  contrastLevel?: number,
+): Theme {
+  return {
+    mode: resolved,
+    colors: buildColorsFromSeed(seed, resolved, variant, contrastLevel),
+    gradients: THEME_GRADIENTS,
+    isDark: resolved === 'dark',
+    isLight: resolved === 'light',
+  };
+}

package/src/theme/index.ts

@@ -5,7 +5,28 @@ export type {
 } from './BloomThemeProvider';
 export { BloomColorScope, useColorScopeStyle } from './color-scope';
 export type { BloomColorScopeProps } from './color-scope';
+export { BloomSeedScope } from './seed-scope';
+export type { BloomSeedScopeProps } from './seed-scope';
+export { buildSeedScopeVars, roleColorsToPresetTokens } from './color-scope/seed-scope';
+export type { SeedScopeOptions } from './color-scope/seed-scope';
+// Colour engine — the dependency-free tonal system that turns ANY seed colour
+// into a full role set. Surfaced here so consumers can derive dynamic themes
+// (e.g. from artwork) without reaching into the internal color-engine path.
+export {
+  generateRoleColors,
+  seedHexFromImagePixels,
+  seedsFromImagePixels,
+  quantizeImage,
+  argbFromHex,
+  hexFromArgb,
+  argbFromRgb,
+  redFromArgb,
+  greenFromArgb,
+  blueFromArgb,
+} from './color-engine';
+export type { RoleColors, GenerateOptions, RoleName, SchemeVariant } from './color-engine';
 export { buildTheme, STATUS_COLORS } from './build-theme';
+export { buildThemeFromSeed, buildColorsFromSeed } from './build-theme-from-seed';
 export { THEME_GRADIENTS } from './gradients';
 export { useTheme, useThemeColor, useBloomTheme } from './use-theme';
 export { useNavigationTheme } from './use-navigation-theme';

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

@@ -0,0 +1,100 @@
+import React, { Children, cloneElement, isValidElement, useContext, useMemo } from 'react';
+import { View, type StyleProp, type ViewStyle } from 'react-native';
+
+import { BloomThemeContext, type BloomThemeContextValue } from '../BloomThemeProvider';
+import { buildSeedScopeVars } from '../color-scope/seed-scope';
+import { getVariableContextProvider } from '../color-scope/style-builder';
+import { buildThemeFromSeed } from '../build-theme-from-seed';
+import type { SchemeVariant } from '../color-engine';
+
+export interface BloomSeedScopeProps {
+  /**
+   * The seed colour (`#rrggbb`) to derive this subtree's palette from. When
+   * `undefined`, the scope is a no-op and children inherit the parent scope
+   * unchanged — pass `undefined` to fall back to the app preset (e.g. on
+   * mouse-leave/blur when restoring the default theme).
+   */
+  seed: string | undefined;
+  /** Tonal scheme variant. Defaults to `'vibrant'` (matches Bloom presets). */
+  variant?: SchemeVariant;
+  /** −1 (low) … 0 (normal) … 1 (high). Defaults to 0. */
+  contrastLevel?: number;
+  /**
+   * When `true`, do not render a wrapping `<View>`. The single child is cloned
+   * with the caller's `style` merged into its `style` prop (Radix-style).
+   */
+  asChild?: boolean;
+  /** Additional style applied to the wrapping `<View>` (or merged into the cloned child with `asChild`). */
+  style?: StyleProp<ViewStyle>;
+  children: React.ReactNode;
+}
+
+interface StyleableProps {
+  style?: StyleProp<ViewStyle>;
+}
+
+/**
+ * Native `<BloomSeedScope>`: scopes a subtree to an ARBITRARY seed colour's
+ * palette (the dynamic counterpart of `<BloomColorScope>`, which takes a named
+ * preset). Feeds the seed through the colour engine and (1) provides the
+ * resulting canonical CSS vars to descendants via react-native-css's
+ * `VariableContext` — so `bg-background` / `bg-card` / `var(--primary)` resolve
+ * against the seed inside this subtree — and (2) publishes a matching JS `theme`
+ * on `BloomThemeContext`, so `useTheme()`/`useBloomTheme()` consumers inside the
+ * subtree also re-theme. The `colorPreset` field is left as the parent's (a seed
+ * is not a named preset).
+ */
+export function BloomSeedScope({
+  seed,
+  variant,
+  contrastLevel,
+  asChild = false,
+  style,
+  children,
+}: BloomSeedScopeProps) {
+  // Hooks run unconditionally; conditional no-op/throw is applied afterwards.
+  const parent = useContext(BloomThemeContext);
+  const resolvedMode = parent?.theme.mode ?? 'light';
+
+  const nativeVars = useMemo<Record<string, string> | null>(
+    () => (seed ? buildSeedScopeVars({ seed, mode: resolvedMode, variant, contrastLevel }) : null),
+    [seed, resolvedMode, variant, contrastLevel],
+  );
+
+  const contextValue = useMemo<BloomThemeContextValue | null>(() => {
+    if (!parent || !seed) return null;
+    const theme = buildThemeFromSeed(seed, resolvedMode, variant, contrastLevel);
+    return { ...parent, theme };
+  }, [parent, seed, resolvedMode, variant, contrastLevel]);
+
+  if (!parent) {
+    throw new Error('BloomSeedScope must be used within a <BloomThemeProvider>');
+  }
+  // `seed` undefined => no-op; children inherit the parent scope.
+  if (!nativeVars || !contextValue) return <>{children}</>;
+
+  const VariableProvider = getVariableContextProvider();
+
+  let content: React.ReactNode;
+  if (asChild) {
+    const child = Children.only(children);
+    if (!isValidElement<StyleableProps>(child)) {
+      throw new Error(
+        'BloomSeedScope with `asChild` requires a single React element child that accepts a `style` prop.',
+      );
+    }
+    const childStyle = child.props.style;
+    const mergedStyle: StyleProp<ViewStyle> = [style, childStyle];
+    content = cloneElement(child, { style: mergedStyle });
+  } else {
+    content = <View style={[{ flex: 1 }, style]}>{children}</View>;
+  }
+
+  const scoped = VariableProvider ? (
+    <VariableProvider value={nativeVars}>{content}</VariableProvider>
+  ) : (
+    content
+  );
+
+  return <BloomThemeContext.Provider value={contextValue}>{scoped}</BloomThemeContext.Provider>;
+}