@oxyhq/bloom 0.44.1 → 0.45.0

package/lib/typescript/commonjs/theme/BloomThemeProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BloomThemeProvider.d.ts","sourceRoot":"","sources":["../../../../src/theme/BloomThemeProvider.tsx"],"names":[],"mappings":"AAIA,OAAO,oBAAoB,CAAC;AAE5B,OAAO,KAQN,MAAM,OAAO,CAAC;AACf,OAAO,EAIL,KAAK,SAAS,EACd,KAAK,SAAS,EACf,MAAM,cAAc,CAAC;AAStB,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAGpD,OAAO,EAKL,KAAK,iBAAiB,EAEvB,MAAM,eAAe,CAAC;AAIvB,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAKhD,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,KAAK,CAAC;IACb,IAAI,EAAE,SAAS,CAAC;IAChB,WAAW,EAAE,YAAY,CAAC;IAC1B,OAAO,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAC;IACnC,cAAc,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;IAC/C;;;;OAIG;IACH,UAAU,EAAE,MAAM,IAAI,CAAC;CACxB;AAED,OAAO,CAAC,MAAM,CAAC;IAEb,IAAI,6BAA6B,EAC7B,KAAK,CAAC,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC,GAC5C,SAAS,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,iBAAiB,EAAE,KAAK,CAAC,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAEpB,CAAC;AAExD,MAAM,WAAW,uBAAuB;IACtC,uFAAuF;IACvF,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,mEAAmE;IACnE,WAAW,CAAC,EAAE,YAAY,CAAC;IAC3B,mEAAmE;IACnE,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB,2EAA2E;IAC3E,kBAAkB,CAAC,EAAE,YAAY,CAAC;IAElC,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAC;IACzC,mBAAmB,CAAC,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;IAErD;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,OAAO,CAAC,EAAE,iBAAiB,CAAC;IAC5B;;;;;OAKG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,iDAAiD;IACjD,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAE9B,2DAA2D;IAC3D,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,wDAAwD;IACxD,cAAc,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAEjC;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IAE1C;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAkJD,wBAAgB,kBAAkB,CAAC,EACjC,IAAI,EAAE,cAAc,EACpB,WAAW,EAAE,gBAAgB,EAC7B,WAA0B,EAC1B,kBAAmC,EACnC,YAAY,EACZ,mBAAmB,EACnB,UAAU,EACV,OAAO,EACP,cAAc,EACd,WAAW,EACX,KAAY,EACZ,cAAc,EACd,kBAAkB,EAClB,cAAc,EACd,aAAa,EACb,IAAI,EACJ,QAAQ,GACT,EAAE,uBAAuB,2CA0HzB"}
+{"version":3,"file":"BloomThemeProvider.d.ts","sourceRoot":"","sources":["../../../../src/theme/BloomThemeProvider.tsx"],"names":[],"mappings":"AAIA,OAAO,oBAAoB,CAAC;AAE5B,OAAO,KAQN,MAAM,OAAO,CAAC;AACf,OAAO,EAIL,KAAK,SAAS,EACd,KAAK,SAAS,EACf,MAAM,cAAc,CAAC;AAWtB,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAGpD,OAAO,EAKL,KAAK,iBAAiB,EAEvB,MAAM,eAAe,CAAC;AAIvB,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAKhD,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,KAAK,CAAC;IACb,IAAI,EAAE,SAAS,CAAC;IAChB,WAAW,EAAE,YAAY,CAAC;IAC1B,OAAO,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAC;IACnC,cAAc,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;IAC/C;;;;OAIG;IACH,UAAU,EAAE,MAAM,IAAI,CAAC;CACxB;AAED,OAAO,CAAC,MAAM,CAAC;IAEb,IAAI,6BAA6B,EAC7B,KAAK,CAAC,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC,GAC5C,SAAS,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,iBAAiB,EAAE,KAAK,CAAC,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAEpB,CAAC;AAExD,MAAM,WAAW,uBAAuB;IACtC,uFAAuF;IACvF,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,mEAAmE;IACnE,WAAW,CAAC,EAAE,YAAY,CAAC;IAC3B,mEAAmE;IACnE,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB,2EAA2E;IAC3E,kBAAkB,CAAC,EAAE,YAAY,CAAC;IAElC,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAC;IACzC,mBAAmB,CAAC,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;IAErD;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,OAAO,CAAC,EAAE,iBAAiB,CAAC;IAC5B;;;;;OAKG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,iDAAiD;IACjD,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAE9B,2DAA2D;IAC3D,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,wDAAwD;IACxD,cAAc,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAEjC;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IAE1C;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAkJD,wBAAgB,kBAAkB,CAAC,EACjC,IAAI,EAAE,cAAc,EACpB,WAAW,EAAE,gBAAgB,EAC7B,WAA0B,EAC1B,kBAAmC,EACnC,YAAY,EACZ,mBAAmB,EACnB,UAAU,EACV,OAAO,EACP,cAAc,EACd,WAAW,EACX,KAAY,EACZ,cAAc,EACd,kBAAkB,EAClB,cAAc,EACd,aAAa,EACb,IAAI,EACJ,QAAQ,GACT,EAAE,uBAAuB,2CA+JzB"}

package/lib/typescript/commonjs/theme/ambient-store.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The current ambient theme override. When `seed` is non-null the whole app is
+ * themed from this dynamic seed (same colour engine the `seed` prop uses),
+ * overriding the active preset / static `seed` prop. `secondary`/`tertiary` pin
+ * this seed's accent families (e.g. the 2nd/3rd colours extracted from artwork).
+ */
+export interface AmbientThemeState {
+    readonly seed: string | null;
+    readonly secondary: string | null;
+    readonly tertiary: string | null;
+}
+export interface AmbientAccents {
+    secondary?: string | null;
+    tertiary?: string | null;
+}
+export interface AmbientThemeApi {
+    /**
+     * Set the ambient seed (and optional accents). Coalesced through an internal
+     * debounce so rapid hover/scroll doesn't thrash the theme. The debounce lives
+     * HERE — apps never own one.
+     */
+    setAmbient: (seed: string, accents?: AmbientAccents) => void;
+    /** Clear the ambient override, restoring the preset (or the static `seed` prop). */
+    clearAmbient: () => void;
+}
+/** Options for {@link useAmbientTheme}. */
+export interface UseAmbientThemeOptions {
+    /**
+     * Debounce, in ms, applied to `setAmbient`/`clearAmbient` before the store
+     * commits. Default `120`. Pass `0` to apply synchronously.
+     */
+    debounceMs?: number;
+}
+/**
+ * Read + drive the app-wide ambient theme. Reading returns the current override
+ * (via `useSyncExternalStore` — stable snapshot ref while unchanged); the
+ * returned `setAmbient`/`clearAmbient` are debounced imperative controls.
+ *
+ * `BloomThemeProvider` consumes the SAME store internally, so calling
+ * `setAmbient(...)` from anywhere themes the whole app through the provider's
+ * single apply path — no `seed` prop threading, no app-owned theming store.
+ */
+export declare function useAmbientTheme(options?: UseAmbientThemeOptions): AmbientThemeState & AmbientThemeApi;
+/**
+ * Provider-side subscription. Returns the current ambient state with a stable
+ * ref while unchanged. Uses the same store, so it stays in lockstep with any
+ * `useAmbientTheme()` caller.
+ */
+export declare function useAmbientThemeState(): AmbientThemeState;
+/**
+ * Non-hook imperative escape hatch (e.g. gesture handlers / worklets bridges /
+ * non-React callers). Same debounced store as {@link useAmbientTheme}.
+ */
+export declare const ambientTheme: AmbientThemeApi & {
+    getState: () => AmbientThemeState;
+};
+/** Test-only: flush any pending debounced commit synchronously. */
+export declare function __flushAmbientForTests(): void;
+/** Test-only: reset the store to the empty state without notifying via debounce. */
+export declare function __resetAmbientForTests(): void;
+//# sourceMappingURL=ambient-store.d.ts.map

package/lib/typescript/commonjs/theme/ambient-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ambient-store.d.ts","sourceRoot":"","sources":["../../../../src/theme/ambient-store.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,KAAK,IAAI,CAAC;IAC7D,oFAAoF;IACpF,YAAY,EAAE,MAAM,IAAI,CAAC;CAC1B;AAED,2CAA2C;AAC3C,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAqFD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,OAAO,CAAC,EAAE,sBAAsB,GAC/B,iBAAiB,GAAG,eAAe,CAUrC;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,iBAAiB,CAExD;AAED;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAE,eAAe,GAAG;IAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;CAI/E,CAAC;AAEF,mEAAmE;AACnE,wBAAgB,sBAAsB,IAAI,IAAI,CAU7C;AAED,oFAAoF;AACpF,wBAAgB,sBAAsB,IAAI,IAAI,CAO7C"}

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

@@ -13,6 +13,8 @@ export { buildThemeFromSeed, buildColorsFromSeed } from './build-theme-from-seed
 export type { SeedAccents } from './build-theme-from-seed';
 export { THEME_GRADIENTS } from './gradients';
 export { useTheme, useThemeColor, useBloomTheme } from './use-theme';
+export { useAmbientTheme, ambientTheme } from './ambient-store';
+export type { AmbientThemeState, AmbientThemeApi, AmbientAccents, UseAmbientThemeOptions, } from './ambient-store';
 export { useNavigationTheme } from './use-navigation-theme';
 export type { NavigationTheme, NavigationThemeFont } from './use-navigation-theme';
 export type { Theme, ThemeColors, ThemeMode, ThemeGradient, ThemeGradients } from './types';

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,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,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC1G,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAClF,YAAY,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,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,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,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,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC1G,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAClF,YAAY,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAChE,YAAY,EACV,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,sBAAsB,GACvB,MAAM,iBAAiB,CAAC;AACzB,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,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,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/BloomThemeProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BloomThemeProvider.d.ts","sourceRoot":"","sources":["../../../../src/theme/BloomThemeProvider.tsx"],"names":[],"mappings":"AAIA,OAAO,oBAAoB,CAAC;AAE5B,OAAO,KAQN,MAAM,OAAO,CAAC;AACf,OAAO,EAIL,KAAK,SAAS,EACd,KAAK,SAAS,EACf,MAAM,cAAc,CAAC;AAStB,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAGpD,OAAO,EAKL,KAAK,iBAAiB,EAEvB,MAAM,eAAe,CAAC;AAIvB,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAKhD,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,KAAK,CAAC;IACb,IAAI,EAAE,SAAS,CAAC;IAChB,WAAW,EAAE,YAAY,CAAC;IAC1B,OAAO,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAC;IACnC,cAAc,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;IAC/C;;;;OAIG;IACH,UAAU,EAAE,MAAM,IAAI,CAAC;CACxB;AAED,OAAO,CAAC,MAAM,CAAC;IAEb,IAAI,6BAA6B,EAC7B,KAAK,CAAC,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC,GAC5C,SAAS,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,iBAAiB,EAAE,KAAK,CAAC,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAEpB,CAAC;AAExD,MAAM,WAAW,uBAAuB;IACtC,uFAAuF;IACvF,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,mEAAmE;IACnE,WAAW,CAAC,EAAE,YAAY,CAAC;IAC3B,mEAAmE;IACnE,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB,2EAA2E;IAC3E,kBAAkB,CAAC,EAAE,YAAY,CAAC;IAElC,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAC;IACzC,mBAAmB,CAAC,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;IAErD;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,OAAO,CAAC,EAAE,iBAAiB,CAAC;IAC5B;;;;;OAKG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,iDAAiD;IACjD,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAE9B,2DAA2D;IAC3D,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,wDAAwD;IACxD,cAAc,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAEjC;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IAE1C;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAkJD,wBAAgB,kBAAkB,CAAC,EACjC,IAAI,EAAE,cAAc,EACpB,WAAW,EAAE,gBAAgB,EAC7B,WAA0B,EAC1B,kBAAmC,EACnC,YAAY,EACZ,mBAAmB,EACnB,UAAU,EACV,OAAO,EACP,cAAc,EACd,WAAW,EACX,KAAY,EACZ,cAAc,EACd,kBAAkB,EAClB,cAAc,EACd,aAAa,EACb,IAAI,EACJ,QAAQ,GACT,EAAE,uBAAuB,2CA0HzB"}
+{"version":3,"file":"BloomThemeProvider.d.ts","sourceRoot":"","sources":["../../../../src/theme/BloomThemeProvider.tsx"],"names":[],"mappings":"AAIA,OAAO,oBAAoB,CAAC;AAE5B,OAAO,KAQN,MAAM,OAAO,CAAC;AACf,OAAO,EAIL,KAAK,SAAS,EACd,KAAK,SAAS,EACf,MAAM,cAAc,CAAC;AAWtB,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAGpD,OAAO,EAKL,KAAK,iBAAiB,EAEvB,MAAM,eAAe,CAAC;AAIvB,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAKhD,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,KAAK,CAAC;IACb,IAAI,EAAE,SAAS,CAAC;IAChB,WAAW,EAAE,YAAY,CAAC;IAC1B,OAAO,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAC;IACnC,cAAc,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;IAC/C;;;;OAIG;IACH,UAAU,EAAE,MAAM,IAAI,CAAC;CACxB;AAED,OAAO,CAAC,MAAM,CAAC;IAEb,IAAI,6BAA6B,EAC7B,KAAK,CAAC,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC,GAC5C,SAAS,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,iBAAiB,EAAE,KAAK,CAAC,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAEpB,CAAC;AAExD,MAAM,WAAW,uBAAuB;IACtC,uFAAuF;IACvF,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,mEAAmE;IACnE,WAAW,CAAC,EAAE,YAAY,CAAC;IAC3B,mEAAmE;IACnE,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB,2EAA2E;IAC3E,kBAAkB,CAAC,EAAE,YAAY,CAAC;IAElC,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAC;IACzC,mBAAmB,CAAC,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;IAErD;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,OAAO,CAAC,EAAE,iBAAiB,CAAC;IAC5B;;;;;OAKG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,iDAAiD;IACjD,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAE9B,2DAA2D;IAC3D,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,wDAAwD;IACxD,cAAc,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAEjC;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IAE1C;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAkJD,wBAAgB,kBAAkB,CAAC,EACjC,IAAI,EAAE,cAAc,EACpB,WAAW,EAAE,gBAAgB,EAC7B,WAA0B,EAC1B,kBAAmC,EACnC,YAAY,EACZ,mBAAmB,EACnB,UAAU,EACV,OAAO,EACP,cAAc,EACd,WAAW,EACX,KAAY,EACZ,cAAc,EACd,kBAAkB,EAClB,cAAc,EACd,aAAa,EACb,IAAI,EACJ,QAAQ,GACT,EAAE,uBAAuB,2CA+JzB"}

package/lib/typescript/module/theme/ambient-store.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The current ambient theme override. When `seed` is non-null the whole app is
+ * themed from this dynamic seed (same colour engine the `seed` prop uses),
+ * overriding the active preset / static `seed` prop. `secondary`/`tertiary` pin
+ * this seed's accent families (e.g. the 2nd/3rd colours extracted from artwork).
+ */
+export interface AmbientThemeState {
+    readonly seed: string | null;
+    readonly secondary: string | null;
+    readonly tertiary: string | null;
+}
+export interface AmbientAccents {
+    secondary?: string | null;
+    tertiary?: string | null;
+}
+export interface AmbientThemeApi {
+    /**
+     * Set the ambient seed (and optional accents). Coalesced through an internal
+     * debounce so rapid hover/scroll doesn't thrash the theme. The debounce lives
+     * HERE — apps never own one.
+     */
+    setAmbient: (seed: string, accents?: AmbientAccents) => void;
+    /** Clear the ambient override, restoring the preset (or the static `seed` prop). */
+    clearAmbient: () => void;
+}
+/** Options for {@link useAmbientTheme}. */
+export interface UseAmbientThemeOptions {
+    /**
+     * Debounce, in ms, applied to `setAmbient`/`clearAmbient` before the store
+     * commits. Default `120`. Pass `0` to apply synchronously.
+     */
+    debounceMs?: number;
+}
+/**
+ * Read + drive the app-wide ambient theme. Reading returns the current override
+ * (via `useSyncExternalStore` — stable snapshot ref while unchanged); the
+ * returned `setAmbient`/`clearAmbient` are debounced imperative controls.
+ *
+ * `BloomThemeProvider` consumes the SAME store internally, so calling
+ * `setAmbient(...)` from anywhere themes the whole app through the provider's
+ * single apply path — no `seed` prop threading, no app-owned theming store.
+ */
+export declare function useAmbientTheme(options?: UseAmbientThemeOptions): AmbientThemeState & AmbientThemeApi;
+/**
+ * Provider-side subscription. Returns the current ambient state with a stable
+ * ref while unchanged. Uses the same store, so it stays in lockstep with any
+ * `useAmbientTheme()` caller.
+ */
+export declare function useAmbientThemeState(): AmbientThemeState;
+/**
+ * Non-hook imperative escape hatch (e.g. gesture handlers / worklets bridges /
+ * non-React callers). Same debounced store as {@link useAmbientTheme}.
+ */
+export declare const ambientTheme: AmbientThemeApi & {
+    getState: () => AmbientThemeState;
+};
+/** Test-only: flush any pending debounced commit synchronously. */
+export declare function __flushAmbientForTests(): void;
+/** Test-only: reset the store to the empty state without notifying via debounce. */
+export declare function __resetAmbientForTests(): void;
+//# sourceMappingURL=ambient-store.d.ts.map

package/lib/typescript/module/theme/ambient-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ambient-store.d.ts","sourceRoot":"","sources":["../../../../src/theme/ambient-store.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,KAAK,IAAI,CAAC;IAC7D,oFAAoF;IACpF,YAAY,EAAE,MAAM,IAAI,CAAC;CAC1B;AAED,2CAA2C;AAC3C,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAqFD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,OAAO,CAAC,EAAE,sBAAsB,GAC/B,iBAAiB,GAAG,eAAe,CAUrC;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,iBAAiB,CAExD;AAED;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAE,eAAe,GAAG;IAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;CAI/E,CAAC;AAEF,mEAAmE;AACnE,wBAAgB,sBAAsB,IAAI,IAAI,CAU7C;AAED,oFAAoF;AACpF,wBAAgB,sBAAsB,IAAI,IAAI,CAO7C"}

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

@@ -13,6 +13,8 @@ export { buildThemeFromSeed, buildColorsFromSeed } from './build-theme-from-seed
 export type { SeedAccents } from './build-theme-from-seed';
 export { THEME_GRADIENTS } from './gradients';
 export { useTheme, useThemeColor, useBloomTheme } from './use-theme';
+export { useAmbientTheme, ambientTheme } from './ambient-store';
+export type { AmbientThemeState, AmbientThemeApi, AmbientAccents, UseAmbientThemeOptions, } from './ambient-store';
 export { useNavigationTheme } from './use-navigation-theme';
 export type { NavigationTheme, NavigationThemeFont } from './use-navigation-theme';
 export type { Theme, ThemeColors, ThemeMode, ThemeGradient, ThemeGradients } from './types';

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,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,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC1G,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAClF,YAAY,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,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,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,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,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC1G,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAClF,YAAY,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAChE,YAAY,EACV,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,sBAAsB,GACvB,MAAM,iBAAiB,CAAC;AACzB,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,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/bloom",
-  "version": "0.44.1",
+  "version": "0.45.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/__tests__/ambient-theme.test.tsx

@@ -0,0 +1,136 @@
+import React from 'react';
+import { Text, Pressable } from 'react-native';
+import { act, render, fireEvent } from '@testing-library/react-native';
+
+import { BloomThemeProvider } from '../theme/BloomThemeProvider';
+import { useTheme } from '../theme/use-theme';
+import {
+  useAmbientTheme,
+  ambientTheme,
+  __flushAmbientForTests,
+  __resetAmbientForTests,
+} from '../theme/ambient-store';
+import { buildThemeFromSeed } from '../theme/build-theme-from-seed';
+import { buildTheme } from '../theme/build-theme';
+
+const OXY_PRESET_PRIMARY = buildTheme('oxy', 'light', false).colors.primary;
+const RED_SEED = '#ff0000';
+const RED_SEED_PRIMARY = buildThemeFromSeed(RED_SEED, 'light').colors.primary;
+
+function PrimaryProbe() {
+  const theme = useTheme();
+  return <Text testID="primary">{theme.colors.primary}</Text>;
+}
+
+function AmbientDriver({ debounceMs }: { debounceMs?: number }) {
+  const { seed, setAmbient, clearAmbient } = useAmbientTheme({ debounceMs });
+  return (
+    <>
+      <Text testID="ambient-seed">{seed ?? 'null'}</Text>
+      <Pressable testID="set" onPress={() => setAmbient(RED_SEED)} />
+      <Pressable testID="clear" onPress={() => clearAmbient()} />
+    </>
+  );
+}
+
+describe('ambient theme store', () => {
+  beforeEach(() => {
+    __resetAmbientForTests();
+  });
+  afterEach(() => {
+    __resetAmbientForTests();
+  });
+
+  it('starts empty and returns a stable snapshot ref while unchanged', () => {
+    const { getByTestId } = render(
+      <BloomThemeProvider>
+        <AmbientDriver debounceMs={0} />
+      </BloomThemeProvider>,
+    );
+    expect(getByTestId('ambient-seed').props.children).toBe('null');
+  });
+
+  it('debounces setAmbient and coalesces rapid calls', () => {
+    ambientTheme.setAmbient('#111111');
+    ambientTheme.setAmbient('#222222');
+    ambientTheme.setAmbient(RED_SEED);
+    // Nothing committed yet — still debouncing.
+    expect(ambientTheme.getState().seed).toBeNull();
+    act(() => {
+      __flushAmbientForTests();
+    });
+    // Only the LAST call wins.
+    expect(ambientTheme.getState().seed).toBe(RED_SEED);
+  });
+
+  it('applies debounceMs: 0 synchronously', () => {
+    const { getByTestId } = render(
+      <BloomThemeProvider>
+        <AmbientDriver debounceMs={0} />
+      </BloomThemeProvider>,
+    );
+    act(() => {
+      fireEvent.press(getByTestId('set'));
+    });
+    expect(getByTestId('ambient-seed').props.children).toBe(RED_SEED);
+  });
+});
+
+describe('BloomThemeProvider ambient override / restore', () => {
+  beforeEach(() => {
+    __resetAmbientForTests();
+  });
+  afterEach(() => {
+    __resetAmbientForTests();
+  });
+
+  it('overrides the preset while ambient is set and restores it on clear', () => {
+    const { getByTestId } = render(
+      <BloomThemeProvider>
+        <PrimaryProbe />
+        <AmbientDriver debounceMs={0} />
+      </BloomThemeProvider>,
+    );
+    // Baseline: the oxy preset.
+    expect(getByTestId('primary').props.children).toBe(OXY_PRESET_PRIMARY);
+
+    act(() => {
+      fireEvent.press(getByTestId('set'));
+    });
+    // Ambient seed themes the whole app from the red seed.
+    expect(getByTestId('primary').props.children).toBe(RED_SEED_PRIMARY);
+    expect(RED_SEED_PRIMARY).not.toBe(OXY_PRESET_PRIMARY);
+
+    act(() => {
+      fireEvent.press(getByTestId('clear'));
+    });
+    // Cleared → back to the preset.
+    expect(getByTestId('primary').props.children).toBe(OXY_PRESET_PRIMARY);
+  });
+
+  it('ambient overrides even a static seed prop, then restores it on clear', () => {
+    const staticSeed = '#00ff00';
+    const staticPrimary = buildThemeFromSeed(staticSeed, 'light').colors.primary;
+
+    const { getByTestId } = render(
+      <BloomThemeProvider seed={staticSeed}>
+        <PrimaryProbe />
+        <AmbientDriver debounceMs={0} />
+      </BloomThemeProvider>,
+    );
+    // Static seed prop is active.
+    expect(getByTestId('primary').props.children).toBe(staticPrimary);
+
+    act(() => {
+      fireEvent.press(getByTestId('set'));
+    });
+    // Ambient wins over the static seed prop.
+    expect(getByTestId('primary').props.children).toBe(RED_SEED_PRIMARY);
+
+    act(() => {
+      fireEvent.press(getByTestId('clear'));
+    });
+    // Restored to the static seed prop, NOT the preset.
+    expect(getByTestId('primary').props.children).toBe(staticPrimary);
+  });
+});

package/src/theme/BloomThemeProvider.tsx

@@ -24,6 +24,8 @@ import {
 import { useControllableState } from '../hooks/useControllableState';
 import { FontLoader } from '../fonts/FontLoader';
 
+import { useAmbientThemeState } from './ambient-store';
+
 import { applyDarkClass, applyVarsToDocument } from './apply-dark-class';
 import { buildTheme } from './build-theme';
 import { buildThemeFromSeed } from './build-theme-from-seed';
@@ -332,16 +334,40 @@ export function BloomThemeProvider({
 }: BloomThemeProviderProps) {
   const rnScheme = useRNColorScheme();
 
+  // The app-wide ambient override, driven imperatively via `useAmbientTheme()`
+  // from anywhere in the app. Subscribed through the module-level store's
+  // `useSyncExternalStore` (stable snapshot ref while unchanged → React-Compiler
+  // safe). When an ambient seed is set it OVERRIDES the static `seed` prop and
+  // the active preset; clearing it restores them.
+  const ambient = useAmbientThemeState();
+
+  // The EFFECTIVE dynamic seed + accents for this render: ambient wins over the
+  // static props. `null` ambient seed means "no override" → fall back to the
+  // `seed` prop (which itself may be undefined → preset path). When ambient is
+  // active, ambient accents replace the static accent props entirely (a null
+  // ambient accent = "no pin for this artwork colour").
+  const ambientActive = ambient.seed !== null;
+  const effectiveSeed: string | undefined = ambientActive
+    ? ambient.seed ?? undefined
+    : seed;
+  const effectiveSecondary: string | undefined = ambientActive
+    ? ambient.secondary ?? undefined
+    : secondaryColor;
+  const effectiveTertiary: string | undefined = ambientActive
+    ? ambient.tertiary ?? undefined
+    : tertiaryColor;
+
   // The app-wide pinned accents, if any. Memoized so its identity only changes
-  // when a prop changes (keeps the effect/memo deps below stable). Left
+  // when an accent changes (keeps the effect/memo deps below stable). Left
   // `undefined` when neither is set so every downstream call is byte-identical
-  // to the no-accent path.
+  // to the no-accent path. Uses the EFFECTIVE accents so ambient accents apply
+  // to the preset path too when no ambient seed is present.
   const explicitAccents = useMemo<ExplicitAccents | undefined>(
     () =>
-      secondaryColor === undefined && tertiaryColor === undefined
+      effectiveSecondary === undefined && effectiveTertiary === undefined
         ? undefined
-        : { secondaryHex: secondaryColor, tertiaryHex: tertiaryColor },
-    [secondaryColor, tertiaryColor],
+        : { secondaryHex: effectiveSecondary, tertiaryHex: effectiveTertiary },
+    [effectiveSecondary, effectiveTertiary],
   );
 
   const { mode, colorPreset, setMode, setColorPreset, resetTheme, hydrated } = useThemeState({
@@ -371,20 +397,33 @@ export function BloomThemeProvider({
   // colour engine, so there is one code path — no seed/preset duplication.
   const themeVars = useMemo(
     () =>
-      seed
-        ? buildSeedScopeVars({ seed, mode: resolved, secondarySeed: secondaryColor, tertiarySeed: tertiaryColor })
+      effectiveSeed
+        ? buildSeedScopeVars({
+            seed: effectiveSeed,
+            mode: resolved,
+            secondarySeed: effectiveSecondary,
+            tertiarySeed: effectiveTertiary,
+          })
         : buildScopeVars(colorPreset, resolved, explicitAccents),
-    [seed, secondaryColor, tertiaryColor, colorPreset, resolved, explicitAccents],
+    [effectiveSeed, effectiveSecondary, effectiveTertiary, colorPreset, resolved, explicitAccents],
   );
   const themeColors = useMemo(
     () =>
-      seed
-        ? buildThemeFromSeed(seed, resolved, undefined, undefined, {
-            secondarySeed: secondaryColor,
-            tertiarySeed: tertiaryColor,
+      effectiveSeed
+        ? buildThemeFromSeed(effectiveSeed, resolved, undefined, undefined, {
+            secondarySeed: effectiveSecondary,
+            tertiarySeed: effectiveTertiary,
           })
         : buildTheme(colorPreset, resolved, isAdaptive, explicitAccents),
-    [seed, secondaryColor, tertiaryColor, colorPreset, resolved, isAdaptive, explicitAccents],
+    [
+      effectiveSeed,
+      effectiveSecondary,
+      effectiveTertiary,
+      colorPreset,
+      resolved,
+      isAdaptive,
+      explicitAccents,
+    ],
   );
 
   useIsomorphicLayoutEffect(() => {

package/src/theme/ambient-store.ts

@@ -0,0 +1,186 @@
+import { useSyncExternalStore } from 'react';
+
+/**
+ * The current ambient theme override. When `seed` is non-null the whole app is
+ * themed from this dynamic seed (same colour engine the `seed` prop uses),
+ * overriding the active preset / static `seed` prop. `secondary`/`tertiary` pin
+ * this seed's accent families (e.g. the 2nd/3rd colours extracted from artwork).
+ */
+export interface AmbientThemeState {
+  readonly seed: string | null;
+  readonly secondary: string | null;
+  readonly tertiary: string | null;
+}
+
+export interface AmbientAccents {
+  secondary?: string | null;
+  tertiary?: string | null;
+}
+
+export interface AmbientThemeApi {
+  /**
+   * Set the ambient seed (and optional accents). Coalesced through an internal
+   * debounce so rapid hover/scroll doesn't thrash the theme. The debounce lives
+   * HERE — apps never own one.
+   */
+  setAmbient: (seed: string, accents?: AmbientAccents) => void;
+  /** Clear the ambient override, restoring the preset (or the static `seed` prop). */
+  clearAmbient: () => void;
+}
+
+/** Options for {@link useAmbientTheme}. */
+export interface UseAmbientThemeOptions {
+  /**
+   * Debounce, in ms, applied to `setAmbient`/`clearAmbient` before the store
+   * commits. Default `120`. Pass `0` to apply synchronously.
+   */
+  debounceMs?: number;
+}
+
+const DEFAULT_DEBOUNCE_MS = 120;
+
+// A single frozen "no override" snapshot. `getSnapshot` returns this EXACT
+// reference whenever nothing is set, so `useSyncExternalStore` sees a stable
+// identity across renders (React-Compiler-safe: the memoized value never
+// silently goes stale because the snapshot ref only changes on a real commit).
+const EMPTY_STATE: AmbientThemeState = Object.freeze({
+  seed: null,
+  secondary: null,
+  tertiary: null,
+});
+
+let state: AmbientThemeState = EMPTY_STATE;
+const listeners = new Set<() => void>();
+
+// Pending debounced commit. `null` operation means "clear".
+let pendingTimer: ReturnType<typeof setTimeout> | null = null;
+let pendingCommit: (() => void) | null = null;
+
+function emit(): void {
+  for (const listener of listeners) listener();
+}
+
+function commit(next: AmbientThemeState): void {
+  // Skip a no-op commit so subscribers don't re-render for an identical value.
+  if (
+    next.seed === state.seed &&
+    next.secondary === state.secondary &&
+    next.tertiary === state.tertiary
+  ) {
+    return;
+  }
+  state = next;
+  emit();
+}
+
+function schedule(next: AmbientThemeState, debounceMs: number): void {
+  if (pendingTimer !== null) {
+    clearTimeout(pendingTimer);
+    pendingTimer = null;
+  }
+  const run = () => {
+    pendingTimer = null;
+    pendingCommit = null;
+    commit(next);
+  };
+  if (debounceMs <= 0) {
+    run();
+    return;
+  }
+  pendingCommit = run;
+  pendingTimer = setTimeout(run, debounceMs);
+  pendingTimer.unref?.();
+}
+
+function subscribe(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+function getSnapshot(): AmbientThemeState {
+  return state;
+}
+
+/** Internal setter used by the debounced hook API. */
+function setAmbientInternal(seed: string, accents: AmbientAccents | undefined, debounceMs: number): void {
+  schedule(
+    {
+      seed,
+      secondary: accents?.secondary ?? null,
+      tertiary: accents?.tertiary ?? null,
+    },
+    debounceMs,
+  );
+}
+
+/** Internal clear used by the debounced hook API. */
+function clearAmbientInternal(debounceMs: number): void {
+  schedule(EMPTY_STATE, debounceMs);
+}
+
+/**
+ * Read + drive the app-wide ambient theme. Reading returns the current override
+ * (via `useSyncExternalStore` — stable snapshot ref while unchanged); the
+ * returned `setAmbient`/`clearAmbient` are debounced imperative controls.
+ *
+ * `BloomThemeProvider` consumes the SAME store internally, so calling
+ * `setAmbient(...)` from anywhere themes the whole app through the provider's
+ * single apply path — no `seed` prop threading, no app-owned theming store.
+ */
+export function useAmbientTheme(
+  options?: UseAmbientThemeOptions,
+): AmbientThemeState & AmbientThemeApi {
+  const debounceMs = options?.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+  const current = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+  return {
+    seed: current.seed,
+    secondary: current.secondary,
+    tertiary: current.tertiary,
+    setAmbient: (seed, accents) => setAmbientInternal(seed, accents, debounceMs),
+    clearAmbient: () => clearAmbientInternal(debounceMs),
+  };
+}
+
+/**
+ * Provider-side subscription. Returns the current ambient state with a stable
+ * ref while unchanged. Uses the same store, so it stays in lockstep with any
+ * `useAmbientTheme()` caller.
+ */
+export function useAmbientThemeState(): AmbientThemeState {
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+
+/**
+ * Non-hook imperative escape hatch (e.g. gesture handlers / worklets bridges /
+ * non-React callers). Same debounced store as {@link useAmbientTheme}.
+ */
+export const ambientTheme: AmbientThemeApi & { getState: () => AmbientThemeState } = {
+  setAmbient: (seed, accents) => setAmbientInternal(seed, accents, DEFAULT_DEBOUNCE_MS),
+  clearAmbient: () => clearAmbientInternal(DEFAULT_DEBOUNCE_MS),
+  getState: getSnapshot,
+};
+
+/** Test-only: flush any pending debounced commit synchronously. */
+export function __flushAmbientForTests(): void {
+  if (pendingCommit) {
+    if (pendingTimer !== null) {
+      clearTimeout(pendingTimer);
+      pendingTimer = null;
+    }
+    const run = pendingCommit;
+    pendingCommit = null;
+    run();
+  }
+}
+
+/** Test-only: reset the store to the empty state without notifying via debounce. */
+export function __resetAmbientForTests(): void {
+  if (pendingTimer !== null) {
+    clearTimeout(pendingTimer);
+    pendingTimer = null;
+  }
+  pendingCommit = null;
+  commit(EMPTY_STATE);
+}

package/src/theme/index.ts

@@ -30,6 +30,13 @@ export { buildThemeFromSeed, buildColorsFromSeed } from './build-theme-from-seed
 export type { SeedAccents } from './build-theme-from-seed';
 export { THEME_GRADIENTS } from './gradients';
 export { useTheme, useThemeColor, useBloomTheme } from './use-theme';
+export { useAmbientTheme, ambientTheme } from './ambient-store';
+export type {
+  AmbientThemeState,
+  AmbientThemeApi,
+  AmbientAccents,
+  UseAmbientThemeOptions,
+} from './ambient-store';
 export { useNavigationTheme } from './use-navigation-theme';
 export type { NavigationTheme, NavigationThemeFont } from './use-navigation-theme';
 export type { Theme, ThemeColors, ThemeMode, ThemeGradient, ThemeGradients } from './types';