@oxyhq/bloom 0.44.1 → 0.46.0

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';