react-native-webrtc-kaleidoscope 2.2.1 → 2.3.0

package/src/kaleidoscope/shader-to-spec.ts

@@ -7,10 +7,37 @@
 // projection: the layers already carry their own ids, sources, uniforms, and
 // blend. Transforms are not book entries; the transform verb handles them.
 
-import type { KaleidoscopePreset } from '../kaleidoscope.preset-book.types';
+import type { KaleidoscopeLayer, KaleidoscopePreset } from '../kaleidoscope.preset-book.types';
 import type { EffectSpec } from './effect.types';
 
-export const compositeToEffectSpec = (composite: KaleidoscopePreset): EffectSpec => ({
-  name: 'composite',
-  layers: composite.layers,
-});
+/** The patch wire shape (layer id + partial uniforms), as the verb receives it. */
+type LayerPatchInput = {
+  readonly id: string;
+  readonly uniforms: Readonly<Record<string, number | readonly number[]>>;
+};
+
+/**
+ * Project a composite into the spec, optionally merging per-layer uniform
+ * patches over the baked values (a switch-with-patches, e.g. restoring a
+ * persisted selection). Merging here, at the seam, is what carries the patches
+ * to EVERY platform: web rebuilds from these layers, and native re-sends them
+ * over setCompositeLayers. A patch addressing a non-tunable or unknown layer id
+ * is ignored.
+ */
+export const compositeToEffectSpec = (
+  composite: KaleidoscopePreset,
+  patches?: ReadonlyArray<LayerPatchInput>,
+): EffectSpec => {
+  if (!patches || patches.length === 0) {
+    return { name: 'composite', layers: composite.layers };
+  }
+  const byId = new Map(patches.map((patch) => [patch.id, patch.uniforms]));
+  return {
+    name: 'composite',
+    layers: composite.layers.map((layer) => {
+      const override = byId.get(layer.id);
+      if (!override || !('uniforms' in layer)) return layer;
+      return { ...layer, uniforms: { ...layer.uniforms, ...override } } as KaleidoscopeLayer;
+    }),
+  };
+};

package/src/kaleidoscope/types.ts

@@ -78,7 +78,9 @@ export type KaleidoscopeBindOptions<P extends KaleidoscopePresetBook> = {
  * The art verb: select a composite by id (rebuilding the pipeline), or clear it
  * with `null`. When `cmd` is the currently-active preset id and `patches` is
  * given, the patches merge through the live no-rebuild uniform channel (keyed by
- * layer id) instead of rebuilding, so a slider drag stays smooth.
+ * layer id) instead of rebuilding, so a slider drag stays smooth. On a preset
+ * SWITCH, patches merge into the rebuilt layer stack itself, so a restored
+ * selection lands tuned on every platform, native included.
  */
 type KaleidoscopeCommand<P extends KaleidoscopePresetBook> = <K extends keyof P>(
   cmd: K | null,

package/src/persistence/async-storage-store.ts

@@ -0,0 +1,33 @@
+// The default backing store: AsyncStorage under the canonical key. Works on
+// every platform (the web build is localStorage-backed).
+//
+// `@react-native-async-storage/async-storage` is an OPTIONAL peer dependency of
+// the package: only the `/persistence` subpath touches it, and Metro resolves
+// it at bundle time for any app that imports this subpath (even with a custom
+// `store`; bundlers do not tree-shake the default away).
+
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import {
+  KALEIDOSCOPE_STATE_KEY,
+  type KaleidoscopeStateStore,
+  parseStoredKaleidoscopeState,
+  type StoredKaleidoscopeState,
+  serializeKaleidoscopeState,
+} from './state';
+
+export const kaleidoscopeAsyncStorageStore: KaleidoscopeStateStore = {
+  load(): Promise<StoredKaleidoscopeState | null> {
+    return AsyncStorage.getItem(KALEIDOSCOPE_STATE_KEY).then(
+      parseStoredKaleidoscopeState,
+      () => null,
+    );
+  },
+  save(state: StoredKaleidoscopeState): Promise<void> {
+    return AsyncStorage.setItem(KALEIDOSCOPE_STATE_KEY, serializeKaleidoscopeState(state)).then(
+      () => undefined,
+      (error) => {
+        console.warn('kaleidoscope: preset persistence save failed', error);
+      },
+    );
+  },
+};

package/src/persistence/index.ts

@@ -0,0 +1,28 @@
+// Subpath entry: react-native-webrtc-kaleidoscope/persistence
+//
+// The persisted-selection convenience: a provider + hook that keep the last
+// applied preset, its control-panel patches, and the mask across launches.
+// Storage-agnostic via `KaleidoscopeStateStore`; defaults to AsyncStorage
+// (`@react-native-async-storage/async-storage`, an optional peer dependency
+// required only by apps that use the default store).
+
+export { kaleidoscopeAsyncStorageStore } from './async-storage-store';
+export {
+  KaleidoscopeStateProvider,
+  type KaleidoscopeStateProviderProps,
+  type KaleidoscopeStateValue,
+  useKaleidoscopeState,
+} from './provider';
+export {
+  DEFAULT_MASK,
+  KALEIDOSCOPE_STATE_KEY,
+  type KaleidoscopeStateStore,
+  parseStoredKaleidoscopeState,
+  pruneStoredState,
+  type StoredKaleidoscopeState,
+  type StoredLayerUniforms,
+  type StoredPatch,
+  type StoredPatches,
+  type StoredPatchMap,
+  serializeKaleidoscopeState,
+} from './state';

package/src/persistence/provider.tsx

@@ -0,0 +1,165 @@
+// Persistence: the React surface. `KaleidoscopeStateProvider` hydrates the
+// stored selection once at mount and writes through on every change;
+// `useKaleidoscopeState` hands the host the hydrated values plus the setters.
+//
+// The provider owns STORAGE state only; it never binds a track or calls the
+// verbs. The host applies the restored selection itself (gated on `hydrated`,
+// so a stored preset is not flashed over by the default):
+//
+//   const { hydrated, presetId, patchesFor, mask, ... } = useKaleidoscopeState<typeof presets>();
+//   useEffect(() => {
+//     if (!hydrated || !controls) return;
+//     if (presetId) controls.kaleidoscope(presetId, patchesFor(presetId));
+//     else controls.kaleidoscope(null);
+//   }, [hydrated, controls, presetId]);
+//
+// The backing store defaults to AsyncStorage; pass any `KaleidoscopeStateStore`
+// to swap it. Importing this subpath is what brings the optional
+// `@react-native-async-storage/async-storage` peer onto your bundle path
+// (Metro resolves it at bundle time either way, so there is no lazy escape).
+
+import {
+  createContext,
+  type ReactElement,
+  type ReactNode,
+  useContext,
+  useEffect,
+  useRef,
+  useState,
+} from 'react';
+import type { MaskInput, PatchesFor } from '../kaleidoscope/types';
+import type { KaleidoscopePresetBook } from '../kaleidoscope.preset-book.types';
+import { kaleidoscopeAsyncStorageStore } from './async-storage-store';
+import {
+  DEFAULT_MASK,
+  type KaleidoscopeStateStore,
+  mergePatch,
+  patchListFor,
+  pruneStoredState,
+  type StoredPatch,
+  type StoredPatches,
+} from './state';
+
+export type KaleidoscopeStateValue<P extends KaleidoscopePresetBook = KaleidoscopePresetBook> = {
+  /** False until the persisted selection has been read; apply no effects before then. */
+  readonly hydrated: boolean;
+  /** The selected preset id, or null when nothing is selected. */
+  readonly presetId: (keyof P & string) | null;
+  /** The shared segmentation edge. */
+  readonly mask: MaskInput;
+  /** Every preset's stored per-layer overrides (keyed by preset id, then layer id). */
+  readonly patches: StoredPatches;
+  readonly setPreset: (presetId: (keyof P & string) | null) => void;
+  readonly setMask: (mask: MaskInput) => void;
+  /** Record one control-panel patch against a preset (and persist it). */
+  readonly setPatch: (presetId: keyof P & string, patch: StoredPatch) => void;
+  /** A preset's stored overrides in the array shape `kaleidoscope(id, patches)` takes. */
+  readonly patchesFor: <K extends keyof P & string>(presetId: K) => PatchesFor<P, K>;
+  /** Clear the stored selection back to defaults (and persist the cleared state). */
+  readonly reset: () => void;
+};
+
+const KaleidoscopeStateContext = createContext<KaleidoscopeStateValue | null>(null);
+
+export type KaleidoscopeStateProviderProps<P extends KaleidoscopePresetBook> = {
+  /** The consumer's preset book; stored state is pruned against it at hydrate. */
+  readonly presets: P;
+  /** The backing store. Defaults to the AsyncStorage store (lazily loaded). */
+  readonly store?: KaleidoscopeStateStore;
+  /** The mask used before hydration and after `reset`. Defaults to 0.5/0.5. */
+  readonly defaultMask?: MaskInput;
+  readonly children: ReactNode;
+};
+
+type Selection = {
+  readonly presetId: string | null;
+  readonly mask: MaskInput;
+  readonly patches: StoredPatches;
+};
+
+export function KaleidoscopeStateProvider<P extends KaleidoscopePresetBook>({
+  presets,
+  store,
+  defaultMask = DEFAULT_MASK,
+  children,
+}: KaleidoscopeStateProviderProps<P>): ReactElement {
+  const [hydrated, setHydrated] = useState(false);
+  const [selection, setSelection] = useState<Selection>({
+    presetId: null,
+    mask: defaultMask,
+    patches: {},
+  });
+  // A write before hydration wins over the stored value (the person acted; do
+  // not clobber their fresh choice with yesterday's).
+  const dirty = useRef(false);
+  // Pinned for the provider's lifetime: hydrate and every write-through go to
+  // the same store the first render saw.
+  const storeRef = useRef(store ?? kaleidoscopeAsyncStorageStore);
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: hydrate exactly once; the book and store are bind-time constants.
+  useEffect(() => {
+    let cancelled = false;
+    storeRef.current.load().then(
+      (stored) => {
+        if (cancelled) return;
+        if (stored && !dirty.current) {
+          const pruned = pruneStoredState(stored, presets);
+          setSelection({ presetId: pruned.presetId, mask: pruned.mask, patches: pruned.patches });
+        }
+        setHydrated(true);
+      },
+      () => {
+        if (!cancelled) setHydrated(true);
+      },
+    );
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  const commit = (next: Selection): void => {
+    dirty.current = true;
+    setSelection(next);
+    void storeRef.current.save({ version: 1, ...next });
+  };
+
+  const value: KaleidoscopeStateValue = {
+    hydrated,
+    presetId: selection.presetId,
+    mask: selection.mask,
+    patches: selection.patches,
+    setPreset: (presetId) => commit({ ...selection, presetId }),
+    setMask: (mask) => commit({ ...selection, mask }),
+    setPatch: (presetId, patch) =>
+      commit({ ...selection, patches: mergePatch(selection.patches, presetId, patch) }),
+    // The stored wire shape is book-agnostic; the typed view is recovered at the
+    // hook (`useKaleidoscopeState<typeof presets>()`), so the cast is the seam.
+    patchesFor: ((presetId: string) =>
+      patchListFor(selection.patches, presetId)) as KaleidoscopeStateValue['patchesFor'],
+    reset: () => commit({ presetId: null, mask: defaultMask, patches: {} }),
+  };
+
+  return (
+    <KaleidoscopeStateContext.Provider value={value}>{children}</KaleidoscopeStateContext.Provider>
+  );
+}
+
+/**
+ * The persisted selection plus its setters. Typed by the consumer's book:
+ * `useKaleidoscopeState<typeof presets>()`. Throws outside the provider.
+ */
+export function useKaleidoscopeState<
+  P extends KaleidoscopePresetBook = KaleidoscopePresetBook,
+>(): KaleidoscopeStateValue<P> {
+  const value = useContext(KaleidoscopeStateContext);
+  if (value === null) {
+    throw new Error(
+      'useKaleidoscopeState: no <KaleidoscopeStateProvider> above this component. ' +
+        'Wrap your app (or the screen using the picker) in the provider from ' +
+        "'react-native-webrtc-kaleidoscope/persistence'.",
+    );
+  }
+  // Safe by construction: the provider pruned ids against the same book the
+  // consumer parameterizes with; the runtime shapes are identical.
+  return value as unknown as KaleidoscopeStateValue<P>;
+}

package/src/persistence/state.ts

@@ -0,0 +1,167 @@
+// Persistence: the pure state module. The stored shape, its key, the tolerant
+// parse, and the pure helpers the provider uses to prune, merge, and project
+// stored state. No React, no storage; the store interface is the only boundary
+// (a consumer may back it with AsyncStorage, localStorage, MMKV, anything
+// promise-shaped). Everything here is unit-testable in plain Node.
+//
+// What persists is the person's selection: the preset id they last applied, the
+// per-layer uniform patches they dialed in through the control panels (keyed by
+// preset, so tweaks to several presets all survive), and the shared mask edge.
+
+import type { MaskInput } from '../kaleidoscope/types';
+import type { KaleidoscopePresetBook } from '../kaleidoscope.preset-book.types';
+
+/** One layer's stored uniform overrides (the wire shape `onPatch` emits). */
+export type StoredLayerUniforms = Readonly<Record<string, number | readonly number[]>>;
+
+/** A preset's stored overrides, keyed by layer id. */
+export type StoredPatchMap = Readonly<Record<string, StoredLayerUniforms>>;
+
+/** Every preset's stored overrides, keyed by preset id. */
+export type StoredPatches = Readonly<Record<string, StoredPatchMap>>;
+
+/** The single live-patch shape, identical to `KaleidoscopeControls['onPatch']`'s argument. */
+export type StoredPatch = {
+  readonly id: string;
+  readonly uniforms: StoredLayerUniforms;
+};
+
+export type StoredKaleidoscopeState = {
+  readonly version: 1;
+  /** The last-applied preset id, or null when nothing was selected. */
+  readonly presetId: string | null;
+  /** The shared segmentation edge. */
+  readonly mask: MaskInput;
+  /** Per-preset, per-layer uniform overrides from the control panels. */
+  readonly patches: StoredPatches;
+};
+
+/**
+ * The backing store. `load` resolves null when nothing (or nothing readable) is
+ * stored; `save` swallows its own failures (persistence is a convenience, never
+ * a crash).
+ */
+export interface KaleidoscopeStateStore {
+  load(): Promise<StoredKaleidoscopeState | null>;
+  save(state: StoredKaleidoscopeState): Promise<void>;
+}
+
+export const KALEIDOSCOPE_STATE_KEY = 'kaleidoscope.state.v1';
+
+export const DEFAULT_MASK: MaskInput = { hardness: 0.5, threshold: 0.5 };
+
+export const serializeKaleidoscopeState = (state: StoredKaleidoscopeState): string =>
+  JSON.stringify(state);
+
+const clamp01 = (value: number): number => Math.min(1, Math.max(0, value));
+
+const isUniformValue = (value: unknown): value is number | readonly number[] =>
+  typeof value === 'number' ||
+  (Array.isArray(value) && value.every((entry) => typeof entry === 'number'));
+
+// A patch map (layer id -> uniforms) with every malformed entry dropped.
+const parsePatchMap = (raw: unknown): StoredPatchMap | null => {
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) return null;
+  const out: Record<string, StoredLayerUniforms> = {};
+  for (const [layerId, uniforms] of Object.entries(raw)) {
+    if (typeof uniforms !== 'object' || uniforms === null || Array.isArray(uniforms)) continue;
+    const kept: Record<string, number | readonly number[]> = {};
+    for (const [key, value] of Object.entries(uniforms)) {
+      if (isUniformValue(value)) kept[key] = value;
+    }
+    if (Object.keys(kept).length > 0) out[layerId] = kept;
+  }
+  return out;
+};
+
+/**
+ * Tolerant parse: any malformed or wrong-version payload reads as null, and a
+ * malformed `patches` subtree degrades to the valid subset rather than killing
+ * the whole state. Mask values clamp to 0..1 (the verbs' documented range).
+ */
+export const parseStoredKaleidoscopeState = (
+  raw: string | null,
+): StoredKaleidoscopeState | null => {
+  if (!raw) return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== 'object' || parsed === null) return null;
+  const candidate = parsed as Record<string, unknown>;
+  if (candidate.version !== 1) return null;
+  if (candidate.presetId !== null && typeof candidate.presetId !== 'string') return null;
+  const mask = candidate.mask as Record<string, unknown> | null | undefined;
+  if (!mask || typeof mask.hardness !== 'number' || typeof mask.threshold !== 'number') {
+    return null;
+  }
+  const patches: Record<string, StoredPatchMap> = {};
+  if (typeof candidate.patches === 'object' && candidate.patches !== null) {
+    for (const [presetId, rawMap] of Object.entries(candidate.patches)) {
+      const map = parsePatchMap(rawMap);
+      if (map && Object.keys(map).length > 0) patches[presetId] = map;
+    }
+  }
+  return {
+    version: 1,
+    presetId: candidate.presetId as string | null,
+    mask: { hardness: clamp01(mask.hardness), threshold: clamp01(mask.threshold) },
+    patches,
+  };
+};
+
+// The layer ids a preset can be patched on: the layers that carry uniforms
+// (`image` and `direct` layers have none and cannot be patched).
+const tunableLayerIds = (book: KaleidoscopePresetBook, presetId: string): ReadonlySet<string> => {
+  const preset = book[presetId];
+  if (!preset) return new Set();
+  return new Set(preset.layers.filter((layer) => 'uniforms' in layer).map((layer) => layer.id));
+};
+
+/**
+ * Reconcile stored state against the consumer's current book: a preset that no
+ * longer exists reads as "none", a patch for a vanished preset or layer is
+ * dropped. Stale state degrades silently; it never crashes the picker.
+ */
+export const pruneStoredState = (
+  state: StoredKaleidoscopeState,
+  book: KaleidoscopePresetBook,
+): StoredKaleidoscopeState => {
+  const presetId = state.presetId !== null && state.presetId in book ? state.presetId : null;
+  const patches: Record<string, StoredPatchMap> = {};
+  for (const [id, map] of Object.entries(state.patches)) {
+    if (!(id in book)) continue;
+    const tunable = tunableLayerIds(book, id);
+    const kept: Record<string, StoredLayerUniforms> = {};
+    for (const [layerId, uniforms] of Object.entries(map)) {
+      if (tunable.has(layerId)) kept[layerId] = uniforms;
+    }
+    if (Object.keys(kept).length > 0) patches[id] = kept;
+  }
+  return { version: 1, presetId, mask: state.mask, patches };
+};
+
+/** Merge one live patch into a preset's stored overrides (immutably). */
+export const mergePatch = (
+  patches: StoredPatches,
+  presetId: string,
+  patch: StoredPatch,
+): StoredPatches => ({
+  ...patches,
+  [presetId]: {
+    ...patches[presetId],
+    [patch.id]: { ...patches[presetId]?.[patch.id], ...patch.uniforms },
+  },
+});
+
+/**
+ * Project a preset's stored overrides into the array shape the `kaleidoscope`
+ * verb takes as `patches`.
+ */
+export const patchListFor = (
+  patches: StoredPatches,
+  presetId: string,
+): ReadonlyArray<StoredPatch> =>
+  Object.entries(patches[presetId] ?? {}).map(([id, uniforms]) => ({ id, uniforms }));