react-native-webrtc-kaleidoscope 2.0.0 → 2.1.0

package/src/kaleidoscope/controls.ts

@@ -0,0 +1,127 @@
+// The three-verb controls: shared composite-state machine, platform-agnostic.
+//
+// Holds the art effect (one composite) and the transform op list, reconciles
+// them into an ordered EffectSpec array (art FIRST so segmentation sees the
+// upright frame, transform LAST so it reorients the finished composite), and
+// applies them through an injected platform `reconcile`. Web rebuilds the
+// pipeline and yields a new track (disposing the prior one); native mutates in
+// place. `mask` writes the segmentation edge through an injected `setMask`; the
+// running composite reads it per frame, so it needs no rebuild.
+//
+// The art verb is rebuild-aware: switching to a different preset rebuilds, but
+// patching the currently-active preset routes through an injected live
+// layer-uniform channel (`setLayerUniforms`, keyed by layer id) so a slider drag
+// updates the running composite without a rebuild.
+
+import type { KaleidoscopePreset, KaleidoscopePresetBook } from '../kaleidoscope.preset-book.types';
+import type { EffectSpec, TransformName } from './effect.types';
+import { compositeToEffectSpec } from './shader-to-spec';
+import type { KaleidoscopeBinding, KaleidoscopeBindOptions, TransformInput } from './types';
+
+/** Apply the ordered specs to the base track and return the output. */
+export type Reconcile = {
+  apply: (specs: ReadonlyArray<EffectSpec>) => MediaStreamTrack;
+  dispose: () => void;
+};
+
+/** Write the segmentation mask edge (platform tuning channel). */
+export type SetMask = (hardness: number, threshold: number) => void;
+
+/**
+ * Write a live per-layer uniform override (platform tuning channel), keyed by
+ * layer id. The running composite merges these over the layer's baked uniforms
+ * each frame, with no rebuild. Mirrors `setMask`.
+ */
+export type SetLayerUniforms = (
+  id: string,
+  uniforms: Readonly<Record<string, number | readonly number[]>>,
+) => void;
+
+/**
+ * Drop every live per-layer override (platform tuning channel). A preset switch
+ * calls this so a reused layer id reverts to the new preset's baked uniforms
+ * rather than inheriting a stale override from the prior preset.
+ */
+export type ResetLayerUniforms = () => void;
+
+// Decompose an absolute transform into the discrete ops the pipeline already
+// runs (reused on web and native). Flips first, then rotation; rotation snaps to
+// the nearest 90°. 180° is two CW steps; 270° is one CCW step.
+const decomposeTransform = (t?: TransformInput): EffectSpec[] => {
+  if (!t) return [];
+  const names: TransformName[] = [];
+  if (t.flip?.x) names.push('flip-x');
+  if (t.flip?.y) names.push('flip-y');
+  const deg = (((Math.round((t.rotate ?? 0) / 90) * 90) % 360) + 360) % 360;
+  if (deg === 90) names.push('rotate-cw');
+  else if (deg === 180) names.push('rotate-cw', 'rotate-cw');
+  else if (deg === 270) names.push('rotate-ccw');
+  return names.map((name) => ({ name }));
+};
+
+export const createControls = <P extends KaleidoscopePresetBook>(
+  baseTrack: MediaStreamTrack,
+  { presets, onTrack }: KaleidoscopeBindOptions<P>,
+  reconcile: Reconcile,
+  setMask: SetMask,
+  setLayerUniforms: SetLayerUniforms,
+  resetLayerUniforms: ResetLayerUniforms,
+): KaleidoscopeBinding<P> => {
+  let art: EffectSpec | null = null;
+  let transformOps: EffectSpec[] = [];
+  let current = baseTrack;
+  // The id of the active preset (null when cleared). A patch of THIS id routes
+  // through the live channel; any other cmd rebuilds.
+  let activeId: keyof P | null = null;
+
+  const apply = (): void => {
+    const specs: EffectSpec[] = [];
+    if (art) specs.push(art);
+    specs.push(...transformOps);
+    current = reconcile.apply(specs);
+    onTrack?.(current);
+  };
+
+  return {
+    kaleidoscope: (
+      cmd: keyof P | null,
+      patches?: ReadonlyArray<{
+        readonly id: string;
+        readonly uniforms: Readonly<Record<string, number | readonly number[]>>;
+      }>,
+    ) => {
+      // Patch the currently-active preset: route through the live no-rebuild
+      // channel, keyed by layer id. The `shader` field on a patch is only for
+      // narrowing; the channel resolves by `id`.
+      if (cmd != null && cmd === activeId && patches && patches.length > 0) {
+        for (const patch of patches) {
+          setLayerUniforms(patch.id, patch.uniforms);
+        }
+        return;
+      }
+      // Switch the preset (or clear): rebuild. Drop every live override first so
+      // a reused layer id (e.g. 'blur', shared by the low/medium/high blur
+      // presets) takes the new preset's baked uniforms instead of carrying a
+      // stale slider override across. A transform rebuild does NOT pass through
+      // here, so slider tweaks survive flips/rotations of the active preset.
+      activeId = cmd;
+      art = cmd == null ? null : compositeToEffectSpec(presets[cmd] as KaleidoscopePreset);
+      resetLayerUniforms();
+      apply();
+    },
+    transform: (t) => {
+      transformOps = decomposeTransform(t);
+      apply();
+    },
+    mask: (m) => {
+      // Updates the edge the per-frame composite reads; no pipeline rebuild.
+      setMask(m.hardness, m.threshold);
+    },
+    get track() {
+      return current;
+    },
+    dispose: () => {
+      reconcile.dispose();
+    },
+  };
+};

package/src/kaleidoscope/effect.ts

@@ -0,0 +1,5 @@
+import type { EffectInput, EffectSpec } from './effect.types';
+
+/** Normalize an `EffectInput` (bare name or spec) into an `EffectSpec`. */
+export const toEffectSpec = (input: EffectInput): EffectSpec =>
+  typeof input === 'string' ? ({ name: input } as EffectSpec) : input;

package/src/kaleidoscope/effect.types.ts

@@ -0,0 +1,63 @@
+// The runtime effect contract: the lower-level spec the drivers consume.
+//
+// A consumer never writes these; they sit below the preset-book vocabulary. A
+// `KaleidoscopePreset` projects into a `CompositeSpec` (see shader-to-spec), the
+// transform verb produces `TransformSpec`s, and `applyVideoEffects` takes the
+// union. Each driver (android / ios / web-driver) renders this same spec.
+
+import type { KaleidoscopeLayer } from '../kaleidoscope.preset-book.types';
+
+/**
+ * Geometric reorientation of the frame: an axis flip or a 90-degree rotation.
+ * The operation IS the effect name (parameterless), compatible with the
+ * bare-string input form and the flat-string native registry. On web these run
+ * in display space; native pipelines correct for the camera buffer's rotation.
+ */
+export type TransformName = 'flip-x' | 'flip-y' | 'rotate-cw' | 'rotate-ccw';
+
+export type TransformSpec = {
+  readonly name: TransformName;
+};
+
+/**
+ * A composed effect: an ordered painter's stack of layers, run by the one
+ * compositor as a single stage. Layer 0 is the base; later layers blend over it.
+ * Every former singleton (blur, image, generative shader) is a layer inside it.
+ */
+export type CompositeSpec = {
+  readonly name: 'composite';
+  readonly layers: ReadonlyArray<KaleidoscopeLayer>;
+};
+
+export type EffectSpec = CompositeSpec | TransformSpec;
+
+/**
+ * The discriminant. Useful for typed switch statements and the bare-string call
+ * shape for the parameterless transforms (`applyVideoEffects(track, ['flip-x'])`).
+ */
+export type EffectName = EffectSpec['name'];
+
+/**
+ * `applyVideoEffects` accepts either a bare transform name (the parameterless
+ * transforms) or a full `EffectSpec` object (a composite or a transform). The
+ * bare-string form is `TransformName`, NOT `EffectName`: a bare `'composite'`
+ * would normalize to a layerless spec and crash the compositor, so the type
+ * rejects it. A composite must always arrive as a full `CompositeSpec`.
+ */
+export type EffectInput = EffectSpec | TransformName;
+
+/**
+ * Apply zero or more effects to a local `MediaStreamTrack`.
+ *
+ * - Native: thin facade over `track._setVideoEffects(names)` from
+ *   `react-native-webrtc`. Returns the same track reference; mutation is in place.
+ * - Web: builds an Insertable-Streams pipeline and returns a NEW track carrying
+ *   the transformed frames.
+ *
+ * Throws on remote tracks, unknown effect names, missing platform capabilities,
+ * or non-video tracks.
+ */
+export type ApplyVideoEffects = (
+  track: MediaStreamTrack,
+  effects: ReadonlyArray<EffectInput>,
+) => MediaStreamTrack;

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

@@ -0,0 +1,16 @@
+// Translate a book composite into the lower-level EffectSpec the primitive
+// `applyVideoEffects` consumes. This is the seam between the book vocabulary the
+// consumer sees and the effect the pipeline runs; the controls own the active
+// composite and reconcile through here.
+//
+// Every book entry is a composite (an ordered layer stack), so this is a thin
+// 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 { EffectSpec } from './effect.types';
+
+export const compositeToEffectSpec = (composite: KaleidoscopePreset): EffectSpec => ({
+  name: 'composite',
+  layers: composite.layers,
+});

package/src/kaleidoscope/types.ts

@@ -0,0 +1,101 @@
+// The three-verb surface: types.
+//
+// Bind a track and a preset book once; get three typed verbs back:
+//   - kaleidoscope(cmd, patches?)  the art axis: which composite (layer stack)
+//     fills the frame. cmd is a preset id from the book (narrowed), or null to
+//     clear. patches optionally merge per-layer uniform overrides (addressed by
+//     layer id); patching the currently-active preset routes through the live
+//     no-rebuild channel, so sliders stay smooth.
+//   - transform(t?)             the geometry axis: absolute flips + 90° rotation.
+//   - mask(m)                   the segmentation edge shared by every art effect.
+//
+// Shaders live in the library; consumers add presets (composites) over them,
+// never new shaders. Per shader-world convention, numeric uniforms are
+// normalized 0..1 where practical; ranges are documented in JSDoc as hints for
+// IntelliSense and tooling, not enforced at runtime (validation is userland).
+
+import type { PatchableShaderName, ShaderUniformsMap } from '../../catalog/shaders';
+import type { KaleidoscopePresetBook } from '../kaleidoscope.preset-book.types';
+
+/**
+ * A live per-layer uniform override for ONE layer, derived from the layer's own
+ * type: `id` is the layer's id, `uniforms` is `Partial` of the shader's uniform
+ * type (re-indexed from `ShaderUniformsMap` by the layer's literal `shader`).
+ * Non-tunable layers (`image`, `direct`) distribute to `never`, so they cannot be
+ * patched. The runtime resolves by `id`; the shader is never sent on the wire.
+ */
+export type PatchFor<L> = L extends {
+  readonly id: infer I extends string;
+  readonly shader: infer S extends PatchableShaderName;
+}
+  ? { readonly id: I; readonly uniforms: Partial<ShaderUniformsMap[S]> }
+  : never;
+
+/**
+ * The patches `kaleidoscope` accepts for preset `K` in book `P`: per-layer
+ * overrides, each addressed by one of that preset's tunable layer ids and typed
+ * by that layer's shader. At a literal `cmd` call site this narrows to the
+ * preset's ids/uniforms; with a variable `cmd` it widens to the book-wide union
+ * and is runtime-checked by id.
+ */
+export type PatchesFor<P extends KaleidoscopePresetBook, K extends keyof P> = ReadonlyArray<
+  PatchFor<P[K]['layers'][number]>
+>;
+
+/**
+ * Absolute, stateless geometric transform. Every call is the full desired state
+ * from the identity orientation: re-passing is the caller's responsibility, and
+ * `transform()` (or `transform({})`) resets to identity. Rotation snaps to the
+ * nearest 90°; arbitrary angles and offset are a later step.
+ */
+export type TransformInput = {
+  /** Mirror flips about each axis. */
+  readonly flip?: { readonly x?: boolean; readonly y?: boolean };
+  /** Clockwise rotation in degrees; snapped to the nearest 90 (0/90/180/270). */
+  readonly rotate?: number;
+};
+
+/** The segmentation mask edge, shared by every art effect (not transforms). */
+export type MaskInput = {
+  /** Edge hardness, 0..1. 0 = soft halo, 1 = near-step. */
+  readonly hardness: number;
+  /** Edge threshold, 0..1. Higher rejects low-confidence (chair-edge) pixels. */
+  readonly threshold: number;
+};
+
+export type KaleidoscopeBindOptions<P extends KaleidoscopePresetBook> = {
+  /** The consumer's preset book. Declare it `as const satisfies KaleidoscopePresetBook`. */
+  readonly presets: P;
+  /**
+   * Called with the live output track after every art/transform command. On web
+   * each command yields a NEW MediaStreamTrack (the pipeline is rebuilt); on
+   * native the same track is mutated in place and passed back.
+   */
+  readonly onTrack?: (track: MediaStreamTrack) => void;
+};
+
+/**
+ * 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.
+ */
+type KaleidoscopeCommand<P extends KaleidoscopePresetBook> = <K extends keyof P>(
+  cmd: K | null,
+  patches?: PatchesFor<P, K>,
+) => void;
+
+/**
+ * The three verbs for one bound track and book, plus the live track and a
+ * teardown. `kaleidoscope` (preset switch) and `transform` rebuild the composite
+ * (web yields a new track via onTrack); a `kaleidoscope` patch of the active
+ * preset and `mask` both update what the running composite reads each frame, so
+ * they need no rebuild.
+ */
+export interface KaleidoscopeBinding<P extends KaleidoscopePresetBook> {
+  readonly kaleidoscope: KaleidoscopeCommand<P>;
+  readonly transform: (t?: TransformInput) => void;
+  readonly mask: (m: MaskInput) => void;
+  readonly track: MediaStreamTrack;
+  readonly dispose: () => void;
+}

package/src/kaleidoscope.preset-book.types.ts

@@ -0,0 +1,105 @@
+// Point of entry #1: the preset-book vocabulary. The base of the pyramid.
+//
+// The complete, declarative lexicon a consumer writes in their
+// `kaleidoscope.preset-book.ts`, and the single source of truth for it: any file
+// that needs one of these types imports it from here. A preset book is a record
+// of named presets; a preset is a name + taxonomy + (optional) thumbnail +
+// (optional) controls + an ordered stack of layers; a layer names a `shader` from
+// the catalog and carries that shader's options.
+//
+// What is NOT here: the runtime effect contract (`CompositeSpec` etc. live in
+// `kaleidoscope/effect.types`; the consumer never writes those), the shader
+// option catalog (`LayerShaderOptions` lives with the shaders it describes), and
+// generic primitives (`RGB` in `lib/primitives.types`).
+
+import type { ComponentType } from 'react';
+import type { LayerShaderName, LayerShaderOptions } from '../catalog/shaders';
+
+/**
+ * A preset's place in the picker: an ordered path of group names, deepest last.
+ * One level (`['Backgrounds']`) is a flat group; two (`['Worlds', 'Wizard Tower']`)
+ * is group then subgroup. The list IS the depth, so a group can't be set without
+ * its parent. Extend to three levels by adding a member here when needed.
+ */
+export type KaleidoscopeTaxonomy = readonly [string] | readonly [string, string];
+
+/**
+ * What the Tuner passes a preset's `controls` component: the per-layer baked
+ * uniforms keyed by layer id, and the single shared `onPatch` every layer's
+ * `ControlForm` emits through (the `id` discriminates). Intentionally loose at
+ * this boundary (heterogeneous layers); per-shader typing is recovered inside
+ * each `<Shader>Controls` via `makeControls<U>()`.
+ */
+export type KaleidoscopeControls = {
+  readonly uniforms: Readonly<Record<string, Readonly<Record<string, number | readonly number[]>>>>;
+  readonly onPatch: (patch: {
+    readonly id: string;
+    readonly uniforms: Record<string, number | readonly number[]>;
+  }) => void;
+  readonly disabled?: boolean;
+};
+
+/** How a layer blends over the layers beneath it (painter's order). */
+export type KaleidoscopeBlendMode = 'normal' | 'additive';
+
+/**
+ * Which part of the frame a layer applies to. Omit for `'background'` (the
+ * accumulated stack so far); `'subject'` stencils the layer to the segmented
+ * person. The same shader can run on either target.
+ */
+export type KaleidoscopeLayerTarget = 'background' | 'subject';
+
+/**
+ * One layer in a preset: a `shader` (from the catalog) applied to a `target`,
+ * with optional `blend`. The `shader` is the discriminant and carries that
+ * shader's required fields (a discriminated union over the catalog's
+ * `LayerShaderOptions`). `id` is required and unique within one preset; it is the
+ * address a patch resolves against, and for an `image` layer it doubles as the
+ * bundled-WebP basename the native facade sends as the image `source`.
+ */
+export type KaleidoscopeLayer = {
+  readonly [S in LayerShaderName]: {
+    readonly id: string;
+    readonly shader: S;
+    readonly target?: KaleidoscopeLayerTarget;
+    readonly blend?: KaleidoscopeBlendMode;
+  } & LayerShaderOptions[S];
+}[LayerShaderName];
+
+/**
+ * One preset: an ordered painter's stack of layers under one book name, plus
+ * display metadata. `kaleidoscope(id)` runs the whole stack as one composite
+ * through the one compositor.
+ */
+export type KaleidoscopePreset = {
+  /** Human-readable label for the picker. */
+  readonly name: string;
+  /** Grouping path for the picker, root first (e.g. `['Worlds', 'Wizard Tower']`). */
+  readonly taxonomy: KaleidoscopeTaxonomy;
+  /**
+   * Optional thumbnail for the picker rail.
+   * - `string`: a resolved URL (web) or native preset name routed through the
+   *   image resolver.
+   * - `number`: a Metro asset module id (`require('./foo.webp')`), consumed
+   *   directly by `<Image source={number}>`.
+   */
+  readonly thumbnail?: string | number;
+  /** The painter's stack, back to front. Each layer's `id` is unique here. */
+  readonly layers: ReadonlyArray<KaleidoscopeLayer>;
+  /**
+   * Optional tuning component the Tuner renders, mounting a `ControlForm` +
+   * `ControlSection` per tunable layer. `undefined` renders nothing. The
+   * `import type` keeps presets runtime-React-free.
+   */
+  readonly controls?: ComponentType<KaleidoscopeControls>;
+};
+
+/** The consumer's book: a flat record of presets keyed by id. */
+export type KaleidoscopePresetBook = Readonly<Record<string, KaleidoscopePreset>>;
+
+/**
+ * A materialized book entry: a `KaleidoscopePreset` plus the `id` it was keyed
+ * by. What the picker and tuner iterate (the book is keyed; this carries the key
+ * inline so a flattened list keeps its identity).
+ */
+export type KaleidoscopePresetEntry = { readonly id: string } & KaleidoscopePreset;

package/src/lib/primitives.types.ts

@@ -0,0 +1,5 @@
+// Generic, cross-everything primitives. No domain or platform coupling, so they
+// are safe in any flow (runtime, prebuild, components).
+
+/** RGB color, each channel in [0, 1]. */
+export type RGB = readonly [number, number, number];

package/src/lib/test-id.ts

@@ -0,0 +1,81 @@
+// The test-id grammar: pure builders for the deterministic, semantic
+// `accessibilityIdentifier`s every interactive kit leaf carries. One source of
+// truth so a Maestro flow can address a control by a stable id instead of its
+// brittle visible text. No React/RN import; this is plain data.
+//
+// Shape (dot-delimited, rooted at `kld`):
+//   control field   kld.<preset>.<layer>.<uniform>      (+ .r/.g/.b per channel)
+//   transform       kld.transform.rotate-90 | flip-x
+//   mask            kld.mask.hardness
+//   family tab      kld.family.<slug>
+//   category item   kld.category.<slug-family>.<slug-category>
+//   preset tile     kld.preset.<id>
+//
+// preset/layer/uniform ids and book keys are already stable tokens and are used
+// verbatim; only display strings (family, category) are slugged.
+
+export const TESTID_ROOT = 'kld';
+
+/** Default static prefixes for the two control families that have no preset scope. */
+export const TRANSFORM_TESTID_PREFIX = `${TESTID_ROOT}.transform`;
+export const MASK_TESTID_PREFIX = `${TESTID_ROOT}.mask`;
+
+/**
+ * Normalize a display string to a stable id segment: lowercase, spaces and
+ * underscores to `-`, drop anything outside `[a-z0-9-]`, collapse repeats, trim.
+ */
+export function slug(s: string): string {
+  return (
+    s
+      .trim()
+      .toLowerCase()
+      .replace(/[\s_]+/g, '-')
+      .replace(/[^a-z0-9-]+/g, '')
+      .replace(/-+/g, '-')
+      // Runs are collapsed to a single '-' above, so each edge has at most one
+      // hyphen; trim one char (no quantifier) instead of '-+$', whose backtracking
+      // is polynomial on a long hyphen run (ReDoS, code-scanning alert #9).
+      .replace(/^-|-$/g, '')
+  );
+}
+
+/**
+ * The scope a ControlForm's fields hang off: `kld.<preset>.<layer>`, or
+ * `kld.<layer>` when rendered standalone (no Tuner provides a preset).
+ */
+export function controlScope(presetId: string | null, layerId: string): string {
+  return presetId ? `${TESTID_ROOT}.${presetId}.${layerId}` : `${TESTID_ROOT}.${layerId}`;
+}
+
+/** One field's id within its form scope: `<scope>.<uniform>`. */
+export function fieldTestId(scope: string, uniform: string): string {
+  return `${scope}.${uniform}`;
+}
+
+/** A rotation button: `<prefix>.rotate-<deg>`. */
+export function rotateTestId(prefix: string, deg: number): string {
+  return `${prefix}.rotate-${deg}`;
+}
+
+/** A flip toggle: `<prefix>.flip-<axis>`. */
+export function flipTestId(prefix: string, axis: 'x' | 'y'): string {
+  return `${prefix}.flip-${axis}`;
+}
+
+/** A family tab: `kld.family.<slug>`. */
+export function familyTestId(family: string): string {
+  return `${TESTID_ROOT}.family.${slug(family)}`;
+}
+
+/**
+ * A category menu item, qualified by its family so the same label under two
+ * families does not collide: `kld.category.<slug-family>.<slug-category>`.
+ */
+export function categoryTestId(family: string, category: string): string {
+  return `${TESTID_ROOT}.category.${slug(family)}.${slug(category)}`;
+}
+
+/** A preset tile: `kld.preset.<id>` (id is the book key, already a stable token). */
+export function presetTileTestId(id: string): string {
+  return `${TESTID_ROOT}.preset.${id}`;
+}

package/src/livekit.ts

@@ -8,7 +8,9 @@
 // instead. This adapter is that bridge:
 //
 //   import { KaleidoscopeProcessor } from 'react-native-webrtc-kaleidoscope/livekit';
-//   await localVideoTrack.setProcessor(new KaleidoscopeProcessor(['blur']));
+//   await localVideoTrack.setProcessor(
+//     new KaleidoscopeProcessor([{ name: 'composite', layers: [{ id: 'you', shader: 'direct', target: 'subject' }] }]),
+//   );
 //
 // `livekit-client` is an OPTIONAL peer dependency: the import below is type-only
 // (erased at build), so the published JS has no runtime dependency on LiveKit
@@ -22,13 +24,13 @@
 
 import type { ProcessorOptions, Track, TrackProcessor } from 'livekit-client';
 import { applyVideoEffectsDisposable } from './index.web';
-import type { EffectInput } from './types';
+import type { EffectInput } from './kaleidoscope/effect.types';
 
 /**
  * A LiveKit `TrackProcessor` that applies Kaleidoscope video effects to a local
  * camera track. Construct it with the same effect inputs `applyVideoEffects`
- * accepts (bare names like `'blur'` or full `EffectSpec` objects), then pass it
- * to `localTrack.setProcessor(processor)`.
+ * accepts (bare transform names like `'flip-x'`, or full `EffectSpec` composite
+ * objects), then pass it to `localTrack.setProcessor(processor)`.
  *
  * `restart` (camera flip / source change) and `destroy` (unpublish) tear down
  * the prior Insertable-Streams pipeline, so repeated flips do not leak

package/src/nativewind.ts

@@ -0,0 +1,41 @@
+// Opt-in NativeWind integration for the picker components (subpath
+// `./nativewind`). Import and call this once from your NativeWind interop setup
+// (the file where you register third-party components for `className`):
+//
+//   import { registerKaleidoscopeNativeWind } from 'react-native-webrtc-kaleidoscope/nativewind';
+//   registerKaleidoscopeNativeWind();
+//
+// This is the only module that imports `nativewind` (an optional peer); the
+// core `./ui` components stay style-agnostic. Without this call the components
+// still work via their defaults and the `style` prop; `className` is simply
+// inert. `cssInterop` maps each component's `className` onto its `style` target,
+// so the class string the consumer passes is resolved by their NativeWind setup.
+
+import { cssInterop } from 'nativewind';
+import { PresetBookMenu } from './components/preset-book-menu';
+import { PresetBookMenuLayout } from './components/preset-book-menu/layout';
+import { PresetGrid } from './components/preset-book-menu/preset-grid';
+import { PresetTile } from './components/preset-tile';
+import { Button } from './components/ui/button';
+import { ColorPicker } from './components/ui/color-picker';
+import { Label } from './components/ui/label';
+import { Readout } from './components/ui/readout';
+import { Slider } from './components/ui/slider';
+
+/**
+ * Register the picker and control primitives with NativeWind so they accept
+ * `className`. Idempotent; call once at app/interop setup. Requires the optional
+ * `nativewind` peer dependency.
+ */
+export function registerKaleidoscopeNativeWind(): void {
+  const mapping = { className: 'style' } as const;
+  cssInterop(PresetBookMenu, mapping);
+  cssInterop(PresetBookMenuLayout, mapping);
+  cssInterop(PresetGrid, mapping);
+  cssInterop(PresetTile, mapping);
+  cssInterop(Label, mapping);
+  cssInterop(Readout, mapping);
+  cssInterop(Slider, mapping);
+  cssInterop(ColorPicker, mapping);
+  cssInterop(Button, mapping);
+}