react-native-webrtc-kaleidoscope 2.0.0 → 2.1.1

package/src/components/preset-control-panel/control-section.tsx

@@ -0,0 +1,84 @@
+// ControlSection: the shared chrome every control group wears (a title + a
+// controls slot + a web-only copy button). Rendered INSIDE a ControlForm so the
+// copy button can read that form's live view model and serialize it.
+//
+// Copy is a desktop tweak-then-paste-into-a-preset workflow: the button renders
+// only on web (Platform.OS), writes via navigator.clipboard, and depends on no
+// clipboard module. Native intentionally has no copy button.
+
+import type { ReactNode } from 'react';
+import { useContext } from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+import { Platform, StyleSheet, Text, View } from 'react-native';
+import { ControlFormContext, type FieldValue } from '../form/control-form';
+import { useThemeSlot } from '../theme/provider';
+import { Button } from '../ui/button';
+
+type Values = Readonly<Record<string, FieldValue>>;
+
+// Round off float noise (drag jitter, the slider epsilon) and snap near-zero to
+// a true 0 so the pasted JSON reads as intended.
+const round = (n: number): number => {
+  const r = Math.round(n * 1e4) / 1e4;
+  return Math.abs(r) < 1e-4 ? 0 : r;
+};
+
+const roundForCopy = (values: Values): Record<string, FieldValue> => {
+  const out: Record<string, FieldValue> = {};
+  for (const [k, v] of Object.entries(values)) {
+    out[k] = Array.isArray(v) ? v.map(round) : round(v as number);
+  }
+  return out;
+};
+
+// Web-only clipboard write, typed off globalThis so it needs no DOM lib and is a
+// no-op anywhere `navigator.clipboard` is absent.
+const writeClipboard = (text: string): void => {
+  const nav = (globalThis as { navigator?: { clipboard?: { writeText?: (t: string) => unknown } } })
+    .navigator;
+  nav?.clipboard?.writeText?.(text);
+};
+
+export type ControlSectionProps = {
+  readonly title: string;
+  readonly children: ReactNode;
+  readonly style?: StyleProp<ViewStyle>;
+};
+
+export function ControlSection({ title, children, style }: ControlSectionProps) {
+  const form = useContext(ControlFormContext);
+  const { style: themeStyle } = useThemeSlot('section');
+  const canCopy = Platform.OS === 'web' && form !== null;
+  return (
+    <View style={[styles.section, themeStyle as StyleProp<ViewStyle>, style]}>
+      <View style={styles.header}>
+        <Text accessibilityRole="header" style={styles.title}>
+          {title}
+        </Text>
+        {canCopy && form ? (
+          <Button
+            testID={`${form.path}.copy`}
+            onPress={() =>
+              writeClipboard(`${title}: ${JSON.stringify(roundForCopy(form.values), null, 2)}`)
+            }
+          >
+            copy
+          </Button>
+        ) : null}
+      </View>
+      <View>{children}</View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  section: { gap: 6 },
+  header: { flexDirection: 'row', justifyContent: 'space-between', alignItems: 'center' },
+  title: {
+    color: '#aaa',
+    fontSize: 12,
+    fontWeight: '600',
+    textTransform: 'uppercase',
+    letterSpacing: 1,
+  },
+});

package/src/components/preset-control-panel/control.tsx

@@ -0,0 +1,50 @@
+// Control: place one control by uniform id inside a per-shader form. It takes
+// ONLY the uniform name, resolves that uniform's descriptor from the enclosing
+// ControlForm, and renders the kind's self-wiring primitive with the descriptor's
+// props. Taking only the name is the invariant: a layout form can ARRANGE controls
+// (wrap them in Views, group them) but cannot redefine a control's behavior.
+//
+// `dispatchControl` is the shared kind -> primitive map, reused by the auto-form
+// (CompositeLayerControlPanel renders every descriptor) and by <Control> (renders
+// one looked-up descriptor).
+
+import type { ReactNode } from 'react';
+import { useContext } from 'react';
+import type { UniformControl } from '../../../catalog/shaders';
+import { ControlFormContext } from '../form/control-form';
+import { ColorPicker } from '../ui/color-picker';
+import { PolygonField } from '../ui/polygon-field';
+import { Slider } from '../ui/slider';
+import { Switch } from '../ui/switch';
+
+/** Render one control descriptor as its kind's self-wiring primitive. */
+export function dispatchControl(c: UniformControl): ReactNode {
+  const label = c.label ?? c.name;
+  switch (c.kind) {
+    case 'color':
+      return <ColorPicker uniform={c.name} label={label} />;
+    case 'float':
+      return <Slider uniform={c.name} min={c.min} max={c.max} step={c.step} label={label} />;
+    case 'switch':
+      return <Switch uniform={c.name} label={label} />;
+    case 'polygon':
+      return <PolygonField uniform={c.name} points={c.points} label={label} />;
+  }
+}
+
+export type ControlProps = {
+  /** The uniform id to place; its descriptor is resolved from the ControlForm. */
+  readonly uniform: string;
+};
+
+export function Control({ uniform }: ControlProps) {
+  const ctx = useContext(ControlFormContext);
+  const descriptor = ctx?.controls?.find((c) => c.name === uniform);
+  if (!descriptor) {
+    throw new Error(
+      `<Control uniform="${uniform}"/>: no descriptor found. Pass controls={X_CONTROLS} ` +
+        'to the enclosing <ControlForm>.',
+    );
+  }
+  return dispatchControl(descriptor);
+}

package/src/components/preset-control-panel/index.ts

@@ -0,0 +1,31 @@
+// Public entry for the opt-in controls composition kit (subpath `./controls`).
+//
+// A per-form `ControlForm` micro-provider with `useField`/`makeControls`, the
+// self-theming field primitives, the `ControlSection` chrome, and the
+// `PresetControlPanel`, all themed via `KaleidoscopeThemeProvider`. This barrel
+// grows commit by commit; the theme surface lands first so later primitives can
+// register against a real exported entry.
+
+export type { KaleidoscopeControls } from '../../kaleidoscope.preset-book.types';
+export { ControlForm, type ControlFormProps, type FieldValue } from '../form/control-form';
+export { makeControls } from '../form/make-controls';
+export { type Field, useField } from '../form/use-field';
+export { KaleidoscopeThemeProvider, useKaleidoscopeTheme, useThemeSlot } from '../theme/provider';
+export type { KaleidoscopeThemeSlots, SlotStyle, ThemeSlot } from '../theme/slots';
+export * from '../ui';
+export {
+  CompositeLayerControlPanel,
+  type CompositeLayerControlPanelProps,
+  type ControlOverride,
+} from './composite-layer-control-panel';
+export { Control, type ControlProps, dispatchControl } from './control';
+export { ControlSection, type ControlSectionProps } from './control-section';
+export {
+  MaskControlPanel,
+  type MaskControlPanelProps,
+} from './mask-control-panel';
+export { PresetControlPanel, type PresetControlPanelProps } from './preset-control-panel';
+export {
+  TransformControlPanel,
+  type TransformControlPanelProps,
+} from './transform-control-panel';

package/src/components/preset-control-panel/mask-control-panel.tsx

@@ -0,0 +1,93 @@
+// MaskControlPanel: the segmentation-edge panel, themed and controlled.
+// Either slider emits the full MaskInput (the mask verb is absolute). Not a
+// layer form, so it has no ControlForm (and thus no copy button) and uses the
+// raw slider directly with the themed Label/Readout primitives.
+
+import RNSlider from '@react-native-community/slider';
+import { StyleSheet, View } from 'react-native';
+import type { MaskInput } from '../../kaleidoscope/types';
+import { MASK_TESTID_PREFIX } from '../../lib/test-id';
+import { Label } from '../ui/label';
+import { Readout } from '../ui/readout';
+import { SLIDER_TINTS } from '../ui/slider-value';
+import { ControlSection } from './control-section';
+
+export type MaskControlPanelProps = {
+  readonly hardness: number;
+  readonly threshold: number;
+  readonly onChange: (mask: MaskInput) => void;
+  readonly disabled?: boolean;
+  /** Root for this instance's test ids; override when a screen mounts two. */
+  readonly testIDPrefix?: string;
+};
+
+function MaskRow({
+  label,
+  value,
+  disabled,
+  onChange,
+  testID,
+}: {
+  readonly label: string;
+  readonly value: number;
+  readonly disabled: boolean;
+  readonly onChange: (v: number) => void;
+  readonly testID: string;
+}) {
+  return (
+    <View style={styles.row}>
+      <View style={styles.line}>
+        <Label>{label}</Label>
+        <Readout>{value.toFixed(2)}</Readout>
+      </View>
+      <RNSlider
+        style={styles.slider}
+        testID={testID}
+        accessibilityLabel={label}
+        // Floor at 0.01: at exactly 0 the mask smoothstep range collapses
+        // (lo === hi) and the edge breaks. 0.01 keeps it well-defined. This is a
+        // shader-math floor, distinct from the field slider's web-crash epsilon.
+        minimumValue={0.01}
+        maximumValue={1}
+        step={0.01}
+        value={value}
+        disabled={disabled}
+        onValueChange={onChange}
+        {...SLIDER_TINTS}
+      />
+    </View>
+  );
+}
+
+export function MaskControlPanel({
+  hardness,
+  threshold,
+  onChange,
+  disabled = false,
+  testIDPrefix = MASK_TESTID_PREFIX,
+}: MaskControlPanelProps) {
+  return (
+    <ControlSection title="mask">
+      <MaskRow
+        label="hardness"
+        value={hardness}
+        disabled={disabled}
+        onChange={(v) => onChange({ hardness: v, threshold })}
+        testID={`${testIDPrefix}.hardness`}
+      />
+      <MaskRow
+        label="threshold"
+        value={threshold}
+        disabled={disabled}
+        onChange={(v) => onChange({ hardness, threshold: v })}
+        testID={`${testIDPrefix}.threshold`}
+      />
+    </ControlSection>
+  );
+}
+
+const styles = StyleSheet.create({
+  row: { gap: 2 },
+  line: { flexDirection: 'row', justifyContent: 'space-between', alignItems: 'center' },
+  slider: { width: '100%', height: 32 },
+});

package/src/components/preset-control-panel/preset-control-panel.tsx

@@ -0,0 +1,48 @@
+// PresetControlPanel: the thin, controlled editor. For the active preset it
+// renders that preset's `controls` component (keyed by preset id, so a switch
+// remounts and the ControlForms re-seed), handing it the per-layer baked
+// uniforms and a single shared onPatch. It never calls `kaleidoscope` itself;
+// the host routes onPatch into `kaleidoscope(activeId, [patch])`.
+
+import type { ReactElement } from 'react';
+import type {
+  KaleidoscopeControls,
+  KaleidoscopePresetBook,
+} from '../../kaleidoscope.preset-book.types';
+import { ControlScopeContext } from '../form/scope';
+
+export type PresetControlPanelProps<P extends KaleidoscopePresetBook> = {
+  readonly presets: P;
+  /** The active preset id, or null when nothing is selected. */
+  readonly value: (keyof P & string) | null;
+  /** Routed to the host, which applies it via `kaleidoscope(value, [patch])`. */
+  readonly onPatch: KaleidoscopeControls['onPatch'];
+  readonly disabled?: boolean;
+};
+
+export function PresetControlPanel<P extends KaleidoscopePresetBook>({
+  presets,
+  value,
+  onPatch,
+  disabled = false,
+}: PresetControlPanelProps<P>): ReactElement | null {
+  if (value === null) return null;
+  const preset = presets[value];
+  const Controls = preset?.controls;
+  if (!Controls) return null;
+
+  // Per-layer baked uniforms keyed by id, for the controls component to seed each
+  // layer's ControlForm. Only tunable layers carry uniforms.
+  const uniforms: Record<string, Record<string, number | readonly number[]>> = {};
+  for (const layer of preset.layers) {
+    if ('uniforms' in layer) {
+      uniforms[layer.id] = { ...layer.uniforms } as Record<string, number | readonly number[]>;
+    }
+  }
+
+  return (
+    <ControlScopeContext.Provider value={value}>
+      <Controls key={value} uniforms={uniforms} onPatch={onPatch} disabled={disabled} />
+    </ControlScopeContext.Provider>
+  );
+}

package/src/components/preset-control-panel/transform-control-panel.tsx

@@ -0,0 +1,146 @@
+// TransformControlPanel: absolute flip + 90-degree rotation, themed and
+// controlled. Every change emits the full TransformInput (the transform verb is
+// absolute). Toggles read the `active` theme slot for their on state.
+
+import type { StyleProp, ViewStyle } from 'react-native';
+import { Pressable, StyleSheet, Text, View } from 'react-native';
+import type { TransformInput } from '../../kaleidoscope/types';
+import { flipTestId, rotateTestId, TRANSFORM_TESTID_PREFIX } from '../../lib/test-id';
+import { useThemeSlot } from '../theme/provider';
+import { ControlSection } from './control-section';
+
+const ROTATIONS = [0, 90, 180, 270] as const;
+
+export type TransformControlPanelProps = {
+  readonly flip?: { readonly x?: boolean; readonly y?: boolean };
+  readonly rotate?: number;
+  readonly onChange: (transform: TransformInput) => void;
+  readonly disabled?: boolean;
+  /** Root for this instance's test ids; override when a screen mounts two. */
+  readonly testIDPrefix?: string;
+};
+
+function FlipToggle({
+  label,
+  icon,
+  on,
+  disabled,
+  onPress,
+  testID,
+  accessibilityLabel,
+}: {
+  readonly label: string;
+  readonly icon: string;
+  readonly on: boolean;
+  readonly disabled: boolean;
+  readonly onPress: () => void;
+  readonly testID: string;
+  readonly accessibilityLabel: string;
+}) {
+  const { style: activeStyle } = useThemeSlot('active');
+  return (
+    <Pressable
+      accessibilityRole="switch"
+      accessibilityLabel={accessibilityLabel}
+      accessibilityState={{ checked: on, disabled }}
+      testID={testID}
+      disabled={disabled}
+      onPress={onPress}
+      style={[
+        styles.flip,
+        on && styles.on,
+        on && (activeStyle as StyleProp<ViewStyle>),
+        disabled && styles.disabled,
+      ]}
+    >
+      <Text style={styles.flipIcon}>{icon}</Text>
+      <Text style={styles.flipLabel}>{label}</Text>
+    </Pressable>
+  );
+}
+
+export function TransformControlPanel({
+  flip,
+  rotate = 0,
+  onChange,
+  disabled = false,
+  testIDPrefix = TRANSFORM_TESTID_PREFIX,
+}: TransformControlPanelProps) {
+  const x = flip?.x ?? false;
+  const y = flip?.y ?? false;
+  const { style: activeStyle } = useThemeSlot('active');
+  return (
+    <ControlSection title="transform">
+      <View style={styles.flipRow}>
+        <FlipToggle
+          label="X"
+          icon="↔"
+          on={x}
+          disabled={disabled}
+          onPress={() => onChange({ flip: { x: !x, y }, rotate })}
+          testID={flipTestId(testIDPrefix, 'x')}
+          accessibilityLabel="Flip horizontal"
+        />
+        <FlipToggle
+          label="Y"
+          icon="↕"
+          on={y}
+          disabled={disabled}
+          onPress={() => onChange({ flip: { x, y: !y }, rotate })}
+          testID={flipTestId(testIDPrefix, 'y')}
+          accessibilityLabel="Flip vertical"
+        />
+      </View>
+      <View style={styles.rotRow}>
+        {ROTATIONS.map((deg) => {
+          const on = rotate === deg;
+          return (
+            <Pressable
+              key={deg}
+              accessibilityRole="radio"
+              accessibilityLabel={deg === 0 ? 'No rotation' : `Rotate ${deg} degrees`}
+              accessibilityState={{ selected: on, disabled }}
+              testID={rotateTestId(testIDPrefix, deg)}
+              disabled={disabled}
+              onPress={() => onChange({ flip: { x, y }, rotate: deg })}
+              style={[
+                styles.rot,
+                on && styles.on,
+                on && (activeStyle as StyleProp<ViewStyle>),
+                disabled && styles.disabled,
+              ]}
+            >
+              <Text style={styles.rotText}>{deg}°</Text>
+            </Pressable>
+          );
+        })}
+      </View>
+    </ControlSection>
+  );
+}
+
+const styles = StyleSheet.create({
+  flipRow: { flexDirection: 'row', gap: 8 },
+  rotRow: { flexDirection: 'row', flexWrap: 'wrap', gap: 8 },
+  flip: {
+    flex: 1,
+    paddingVertical: 12,
+    backgroundColor: '#2a2a2a',
+    borderRadius: 6,
+    alignItems: 'center',
+    gap: 2,
+  },
+  rot: {
+    flexGrow: 1,
+    minWidth: 56,
+    paddingVertical: 10,
+    backgroundColor: '#2a2a2a',
+    borderRadius: 6,
+    alignItems: 'center',
+  },
+  on: { backgroundColor: '#4a8f3f' },
+  disabled: { opacity: 0.5 },
+  flipIcon: { color: '#fff', fontSize: 22, lineHeight: 26 },
+  flipLabel: { color: '#fff', fontWeight: '500', fontSize: 13 },
+  rotText: { color: '#fff', fontWeight: '600', fontSize: 13 },
+});

package/src/components/preset-tile/index.tsx

@@ -0,0 +1,160 @@
+// Leaf: one preset tile. The single item shape for every family; it prints the
+// label and, if the preset has a resolved thumbnail, paints it as a wallpaper
+// behind the label; with no thumbnail it is a recessed pressable button of the
+// SAME footprint, so a thumbnail-less preset never breaks the grid's flow. The
+// variant is chosen per preset by `uri` presence, not by family. Hover/press
+// "light up" via an overlay sheet (web hover is inert on native, where
+// `hovered` is simply undefined).
+//
+// The tile is a fixed 16:9 box (`aspectRatio`), matching the 1280x720 images and
+// 320x180 thumbnails, so cover-fit shows the whole image and every tile is the
+// same shape regardless of how wide a column resolves to. Width comes from the
+// flex row (`flexBasis`/`maxWidth`); `aspectRatio` derives the height from it.
+// (Historical note: an earlier attempt rendered thin strips when Yoga failed to
+// derive height from a percentage `flexBasis` + `aspectRatio`; if that recurs on
+// a target, restore an explicit `height` floor here.)
+//
+// Styling is headless: defaults + `style` (wins) + `className` (consumed by the
+// `./nativewind` interop, inert without it).
+
+import {
+  Image,
+  Pressable,
+  type StyleProp,
+  StyleSheet,
+  Text,
+  View,
+  type ViewStyle,
+} from 'react-native';
+
+interface PresetTileProps {
+  readonly label: string;
+  /**
+   * Resolved thumbnail source. A `string` is a URL (web) or file:// URI (native
+   * preset-name lookup); a `number` is a Metro asset module id consumed directly
+   * by `<Image source={number}>`. Undefined renders the recessed button.
+   */
+  readonly uri: string | number | undefined;
+  readonly selected: boolean;
+  readonly disabled?: boolean | undefined;
+  readonly onPress: () => void;
+  /** Optional corner badge, e.g. "demo-owned". */
+  readonly badge?: string | undefined;
+  /** NativeWind class; resolved via the `./nativewind` interop registration. */
+  readonly className?: string | undefined;
+  /** RN style override; applied after the defaults. */
+  readonly style?: StyleProp<ViewStyle> | undefined;
+  /** Deterministic `accessibilityIdentifier` (`kld.preset.<id>`). */
+  readonly testID?: string | undefined;
+}
+
+export function PresetTile(props: PresetTileProps) {
+  const { label, uri, selected, disabled = false, onPress, badge, style, testID } = props;
+  const hasWallpaper = !!uri;
+  return (
+    <Pressable
+      accessibilityRole="radio"
+      accessibilityState={{ checked: selected, disabled }}
+      testID={testID}
+      disabled={disabled}
+      onPress={onPress}
+      style={[
+        styles.tile,
+        hasWallpaper ? styles.wallpaper : styles.recessed,
+        selected && styles.selected,
+        disabled && styles.disabled,
+        style,
+      ]}
+    >
+      {({ pressed, hovered = false }: { pressed: boolean; hovered?: boolean }) => (
+        <>
+          {hasWallpaper ? (
+            <Image
+              source={typeof uri === 'number' ? uri : { uri }}
+              style={styles.thumb}
+              resizeMode="cover"
+            />
+          ) : null}
+          {hasWallpaper ? <View style={styles.scrim} /> : null}
+          {badge ? (
+            <View style={styles.badge}>
+              <Text style={styles.badgeText}>{badge}</Text>
+            </View>
+          ) : null}
+          <View style={styles.labelWrap}>
+            <Text numberOfLines={2} style={styles.label}>
+              {label}
+            </Text>
+          </View>
+          {hovered || pressed ? (
+            <View pointerEvents="none" style={[styles.glow, pressed && styles.glowPressed]} />
+          ) : null}
+        </>
+      )}
+    </Pressable>
+  );
+}
+
+const styles = StyleSheet.create({
+  tile: {
+    aspectRatio: 16 / 9,
+    minWidth: 96,
+    // GENERAL React Native gotcha worth naming, because it bites LLM-generated
+    // layouts in particular: Yoga (RN's flex engine) will silently collapse a
+    // view to zero height when the layout describes height purely by derivation
+    // (a percentage `flexBasis` plus an `aspectRatio`, or content that has not
+    // measured yet) without an explicit floor. It smashes shut like an
+    // unbroken IE6 `<div>`. If a row of tiles ever renders as thin strips, the
+    // first thing to check is whether each tile has a `height` or `minHeight`
+    // anywhere in its chain.
+    //
+    // THIS SITE: declared `flexBasis: '30%'` + `aspectRatio: 16/9` and no
+    // height floor; each tile resolved to 118 x 4 px on iOS (Maestro hierarchy
+    // bounds), turning every wallpaper tile into a thin gray strip. The
+    // recessed variant survived only because its visible 2px border made the
+    // 4px collapse read as a deliberate divider. 54 = 96 * 9 / 16 (the
+    // minWidth's aspect-derived height), so a tile whose width grows past the
+    // floor still tracks the 16:9 ratio via `aspectRatio`.
+    minHeight: 54,
+    flexGrow: 1,
+    flexBasis: '30%',
+    maxWidth: '32%',
+    borderRadius: 6,
+    overflow: 'hidden',
+    borderWidth: 2,
+    borderColor: 'transparent',
+  },
+  // Wallpaper variant: the thumbnail fills the tile, label over a legibility scrim.
+  wallpaper: { backgroundColor: '#1a1a1a' },
+  // Recessed variant (no thumbnail): a pressable inset area, same footprint.
+  recessed: { backgroundColor: '#242424', borderColor: '#333' },
+  selected: { borderColor: '#4a8f3f' },
+  disabled: { opacity: 0.5 },
+  thumb: { ...StyleSheet.absoluteFillObject },
+  scrim: { ...StyleSheet.absoluteFillObject, backgroundColor: 'rgba(0, 0, 0, 0.35)' },
+  badge: {
+    position: 'absolute',
+    top: 4,
+    left: 4,
+    backgroundColor: 'rgba(217, 119, 6, 0.92)',
+    borderRadius: 4,
+    paddingHorizontal: 5,
+    paddingVertical: 2,
+  },
+  badgeText: { color: '#fff', fontSize: 9, fontWeight: '700' },
+  labelWrap: {
+    ...StyleSheet.absoluteFillObject,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  label: {
+    color: '#fff',
+    fontSize: 12,
+    fontWeight: '700',
+    textAlign: 'center',
+    paddingHorizontal: 6,
+  },
+  // Hover/press "lights up": a translucent sheet over the whole tile.
+  glow: { ...StyleSheet.absoluteFillObject, backgroundColor: 'rgba(255, 255, 255, 0.12)' },
+  glowPressed: { backgroundColor: 'rgba(255, 255, 255, 0.04)' },
+});

package/src/components/theme/provider.tsx

@@ -0,0 +1,50 @@
+// The theme provider: one context holding the flat slot bank that every control
+// primitive reads to self-decorate. Mirrors the React Native Reusables
+// `TextClassContext` idea, generalized to a slot map.
+//
+// Pass a STABLE `value` (React Compiler memoizes it on the consumer side;
+// otherwise memoize it by hand): a fresh object each render re-renders every
+// themed primitive.
+//
+// Leaf module: imports only `react` and the slot types. It must never import from
+// sibling component modules or from `ui/`, so `ui/` can depend on it (the one
+// allowed `ui/` -> `theme/` edge) without a cycle.
+
+import type { ReactNode } from 'react';
+import { createContext, useContext } from 'react';
+import type { KaleidoscopeThemeSlots, SlotStyle, ThemeSlot } from './slots';
+
+const EMPTY: KaleidoscopeThemeSlots = {};
+
+const ThemeContext = createContext<KaleidoscopeThemeSlots>(EMPTY);
+
+/**
+ * Wrap the controls UI to theme every primitive at once. `value` is the slot
+ * bank (`labelClassName`, `sliderStyle`, ...); memoize it at the call site.
+ */
+export function KaleidoscopeThemeProvider({
+  value,
+  children,
+}: {
+  readonly value?: KaleidoscopeThemeSlots;
+  readonly children: ReactNode;
+}) {
+  return <ThemeContext.Provider value={value ?? EMPTY}>{children}</ThemeContext.Provider>;
+}
+
+/** The full slot bank from context (empty when no provider is mounted). */
+export function useKaleidoscopeTheme(): KaleidoscopeThemeSlots {
+  return useContext(ThemeContext);
+}
+
+/** The `{ className, style }` pair for one slot, for a primitive to merge last. */
+export function useThemeSlot(slot: ThemeSlot): {
+  readonly className?: string;
+  readonly style?: SlotStyle;
+} {
+  const slots = useContext(ThemeContext);
+  return {
+    className: slots[`${slot}ClassName`],
+    style: slots[`${slot}Style`],
+  };
+}