react-native-webrtc-kaleidoscope 2.0.0 → 2.1.1

package/src/components/preset-book-menu/index.tsx

@@ -0,0 +1,286 @@
+// The drop-in composite picker (#28): tabs over the consumer's preset families,
+// a left-hand category menu under the tabs, and a uniform tile grid filtered by
+// the active family and category. Controlled selection; emit the chosen id, the
+// host applies it. `usePresetBookMenu` is the orchestration (group the book by
+// family/category, own the active tab and category) and is exported for BYO
+// layouts.
+
+import { useState } from 'react';
+import { Pressable, StyleSheet, Text } from 'react-native';
+import type { KaleidoscopePresetBook } from '../../kaleidoscope.preset-book.types';
+import { categoryTestId, familyTestId } from '../../lib/test-id';
+import { PresetBookMenuLayout } from './layout';
+import type { Category, Family, PresetBookMenuProps, PresetView } from './preset-book-menu.types';
+import { PresetGrid } from './preset-grid';
+
+/** The grouping usePresetBookMenu returns; named so BYO-layout consumers can type it. */
+export interface PresetBookMenuModel {
+  /** Distinct families present in the book, in first-appearance order. */
+  readonly families: ReadonlyArray<Family>;
+  /** The reconciled active family (survives a changed book; falls back to the first). */
+  readonly activeTab: Family | undefined;
+  /** Set the active family tab. */
+  readonly setActiveTab: (family: Family) => void;
+  /**
+   * Categories (taxonomy[1]) within the active family, first-appearance order.
+   * Empty when the family is flat (every preset is depth-1).
+   */
+  readonly categories: ReadonlyArray<Category>;
+  /** The reconciled active category, or undefined when the family is flat. */
+  readonly activeCategory: Category | undefined;
+  /** Set the active category. */
+  readonly setActiveCategory: (category: Category) => void;
+  /**
+   * Presets to display: the active family narrowed to the active category, or
+   * every preset in the family when it is flat.
+   */
+  readonly views: ReadonlyArray<PresetView>;
+}
+
+/**
+ * Tabbed, preset-book-driven picker. Controlled selection; emits the chosen id
+ * and the host applies it.
+ *
+ * @example
+ * <PresetBookMenu
+ *   presets={presets}
+ *   value={art}
+ *   onSelect={setArt}
+ * />
+ */
+export function PresetBookMenu<P extends KaleidoscopePresetBook>(props: PresetBookMenuProps<P>) {
+  // `className` (declared on PresetBookMenuProps) is intentionally not destructured: the
+  // ./nativewind cssInterop registration consumes it at the JSX boundary and
+  // merges the resolved classes into `style` before this body runs.
+  const {
+    presets,
+    value,
+    onSelect,
+    disabled = false,
+    renderTile,
+    labelFor,
+    tabLabelFor,
+    categoryLabelFor,
+    style,
+  } = props;
+  const {
+    families,
+    activeTab,
+    setActiveTab,
+    categories,
+    activeCategory,
+    setActiveCategory,
+    views,
+  } = usePresetBookMenu(presets, labelFor);
+
+  if (!activeTab) return null;
+  // The renderers speak string ids (PresetView.id); the public onSelect is
+  // narrowed to keyof P. Adapt once here so consumers need no cast (every id
+  // came from Object.keys(presets), so it is a real key).
+  const handleSelect = (id: string | null) => onSelect(id as (keyof P & string) | null);
+
+  return (
+    <PresetBookMenuLayout
+      style={style}
+      tabsZone={families.map((family) => (
+        <Tab
+          key={family}
+          label={tabLabelFor?.(family) ?? titleCase(family)}
+          active={family === activeTab}
+          disabled={disabled}
+          onPress={() => setActiveTab(family)}
+          testID={familyTestId(family)}
+        />
+      ))}
+      sidebarZone={
+        categories.length > 0
+          ? categories.map((category) => (
+              <CategoryItem
+                key={category}
+                label={categoryLabelFor?.(category) ?? category}
+                active={category === activeCategory}
+                disabled={disabled}
+                onPress={() => setActiveCategory(category)}
+                testID={categoryTestId(activeTab, category)}
+              />
+            ))
+          : undefined
+      }
+      bodyZone={
+        <PresetGrid
+          presets={views}
+          value={value}
+          onSelect={handleSelect}
+          disabled={disabled}
+          renderTile={renderTile}
+        />
+      }
+    />
+  );
+}
+
+/**
+ * Group a preset book by family and category, and own the active tab and
+ * category. The grouping is plain; no hand-rolled memo: React Compiler memoizes
+ * it when the library is compiled, and it is cheap to recompute otherwise. The
+ * active tab and category are reconciled every render: each survives as long as
+ * it is still in the book, else it falls back to the first; so swapping
+ * `presets`, or switching to a family that lacks the prior category, can't strand
+ * a dead selection.
+ */
+export function usePresetBookMenu<P extends KaleidoscopePresetBook>(
+  presets: P,
+  labelFor?: (id: keyof P & string) => string,
+): PresetBookMenuModel {
+  const families: Family[] = [];
+  const viewsByFamily = new Map<Family, PresetView[]>();
+  const categoriesByFamily = new Map<Family, Category[]>();
+  const viewsByFamilyCategory = new Map<Family, Map<Category, PresetView[]>>();
+  for (const id of Object.keys(presets)) {
+    const preset = presets[id];
+    if (!preset) continue;
+    // taxonomy[0] is the family (tab); taxonomy[1], when present, is the
+    // category (left-hand menu). A depth-1 preset has no category.
+    const family = preset.taxonomy[0];
+    const category = preset.taxonomy[1];
+    const view: PresetView = {
+      id,
+      label: labelFor?.(id as keyof P & string) ?? preset.name,
+      family,
+      category,
+      source:
+        typeof preset.thumbnail === 'string' || typeof preset.thumbnail === 'number'
+          ? preset.thumbnail
+          : undefined,
+    };
+    if (!viewsByFamily.has(family)) {
+      families.push(family);
+      viewsByFamily.set(family, []);
+      categoriesByFamily.set(family, []);
+      viewsByFamilyCategory.set(family, new Map());
+    }
+    viewsByFamily.get(family)?.push(view);
+    if (category !== undefined) {
+      const cats = categoriesByFamily.get(family);
+      const catViews = viewsByFamilyCategory.get(family);
+      if (cats && catViews && !catViews.has(category)) {
+        cats.push(category);
+        catViews.set(category, []);
+      }
+      catViews?.get(category)?.push(view);
+    }
+  }
+
+  const [activeTab, setActiveTab] = useState<Family | undefined>(undefined);
+  const family = activeTab && families.includes(activeTab) ? activeTab : families[0];
+  const categories = (family && categoriesByFamily.get(family)) || [];
+
+  const [activeCategory, setActiveCategory] = useState<Category | undefined>(undefined);
+  const category =
+    activeCategory && categories.includes(activeCategory) ? activeCategory : categories[0];
+
+  const views = category
+    ? (family && viewsByFamilyCategory.get(family)?.get(category)) || []
+    : (family && viewsByFamily.get(family)) || [];
+
+  return {
+    families,
+    activeTab: family,
+    setActiveTab,
+    categories,
+    activeCategory: category,
+    setActiveCategory,
+    views,
+  };
+}
+
+interface TabProps {
+  readonly label: string;
+  readonly active: boolean;
+  readonly disabled: boolean;
+  readonly onPress: () => void;
+  readonly testID: string;
+}
+
+function Tab({ label, active, disabled, onPress, testID }: TabProps) {
+  return (
+    <Pressable
+      accessibilityRole="tab"
+      accessibilityState={{ selected: active, disabled }}
+      testID={testID}
+      disabled={disabled}
+      onPress={onPress}
+      style={[styles.tab, active && styles.tabActive, disabled && styles.tabDisabled]}
+    >
+      <Text style={[styles.tabLabel, active && styles.tabLabelActive]}>{label}</Text>
+    </Pressable>
+  );
+}
+
+interface CategoryItemProps {
+  readonly label: string;
+  readonly active: boolean;
+  readonly disabled: boolean;
+  readonly onPress: () => void;
+  readonly testID: string;
+}
+
+function CategoryItem({ label, active, disabled, onPress, testID }: CategoryItemProps) {
+  return (
+    <Pressable
+      accessibilityRole="menuitem"
+      accessibilityState={{ selected: active, disabled }}
+      testID={testID}
+      disabled={disabled}
+      onPress={onPress}
+      style={[
+        styles.category,
+        active && styles.categoryActive,
+        disabled && styles.categoryDisabled,
+      ]}
+    >
+      <Text style={[styles.categoryLabel, active && styles.categoryLabelActive]}>{label}</Text>
+    </Pressable>
+  );
+}
+
+function titleCase(s: string): string {
+  return s
+    .split('-')
+    .map((w) => (w ? w.charAt(0).toUpperCase() + w.slice(1) : w))
+    .join(' ');
+}
+
+const styles = StyleSheet.create({
+  tab: { paddingVertical: 6, paddingHorizontal: 12, borderRadius: 999, backgroundColor: '#1f1f1f' },
+  tabActive: { backgroundColor: '#333' },
+  tabDisabled: { opacity: 0.5 },
+  tabLabel: { color: '#999', fontSize: 12, fontWeight: '600' },
+  tabLabelActive: { color: '#fff' },
+  category: {
+    paddingVertical: 6,
+    paddingHorizontal: 10,
+    borderRadius: 8,
+    backgroundColor: '#1a1a1a',
+  },
+  categoryActive: { backgroundColor: '#2c2c2c' },
+  categoryDisabled: { opacity: 0.5 },
+  categoryLabel: { color: '#9a9a9a', fontSize: 12, fontWeight: '500' },
+  categoryLabelActive: { color: '#fff' },
+});
+
+export { PresetTile } from '../preset-tile';
+// The `./picker` subpath barrel: the chassis above plus the composable parts and
+// types a consumer can use to build a BYO layout.
+export { PresetBookMenuLayout } from './layout';
+export type {
+  Category,
+  Family,
+  PresetBookMenuProps,
+  PresetBookMenuSelection,
+  PresetBookMenuStyleProps,
+  PresetItemState,
+  PresetView,
+  RenderTile,
+} from './preset-book-menu.types';
+export { PresetGrid } from './preset-grid';

package/src/components/preset-book-menu/layout.tsx

@@ -0,0 +1,63 @@
+// Zone container for the composite picker: a tab bar above, then (when the
+// active family has categories) a left-hand category menu beside the body.
+// Presentational only; the composite fills the zones.
+
+import type { ReactNode } from 'react';
+import { type StyleProp, StyleSheet, View, type ViewStyle } from 'react-native';
+
+interface PresetBookMenuLayoutProps {
+  /**
+   * The family tab bar; conventionally a row of tab buttons, one per family.
+   * The layout already wraps this in a `tablist`-role row with flex/gap, so the
+   * filler should be the bare tab elements (don't add another row wrapper).
+   */
+  readonly tabsZone: ReactNode;
+  /**
+   * The category menu for the active family (a column of buttons, one per
+   * category). Omit (or pass nothing) for a flat family: the body then spans
+   * full width with no left column. The layout wraps this in the left column;
+   * the filler should be the bare item elements.
+   */
+  readonly sidebarZone?: ReactNode;
+  /** The active family's renderer (a PresetGrid); fills the body column. */
+  readonly bodyZone: ReactNode;
+  /** NativeWind class for the container; resolved via the `./nativewind` interop. */
+  readonly className?: string | undefined;
+  readonly style?: StyleProp<ViewStyle> | undefined;
+}
+
+// `className` is consumed by the ./nativewind cssInterop at the boundary and
+// arrives merged into `style`, so it is not destructured/read here.
+export function PresetBookMenuLayout({
+  tabsZone,
+  sidebarZone,
+  bodyZone,
+  style,
+}: PresetBookMenuLayoutProps) {
+  return (
+    <View style={[styles.container, style]}>
+      <View accessibilityRole="tablist" accessibilityLabel="Effect families" style={styles.tabs}>
+        {tabsZone}
+      </View>
+      {sidebarZone ? (
+        <View style={styles.split}>
+          <View accessibilityRole="menu" accessibilityLabel="Categories" style={styles.sidebar}>
+            {sidebarZone}
+          </View>
+          <View style={styles.bodyFlex}>{bodyZone}</View>
+        </View>
+      ) : (
+        <View style={styles.body}>{bodyZone}</View>
+      )}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: { gap: 8, width: '100%' },
+  tabs: { flexDirection: 'row', flexWrap: 'wrap', gap: 6 },
+  split: { flexDirection: 'row', gap: 12, width: '100%', alignItems: 'flex-start' },
+  sidebar: { flexShrink: 0, gap: 4, minWidth: 96 },
+  bodyFlex: { flex: 1 },
+  body: { width: '100%' },
+});

package/src/components/preset-book-menu/preset-book-menu.types.ts

@@ -0,0 +1,112 @@
+// Shared contract for the drop-in picker components (#28).
+//
+// These types are the seam between the composite picker, its family renderers,
+// and the per-item leaves. The composite reads the consumer's preset book,
+// flattens each preset to a `PresetView`, groups by `family` (the book entry's
+// taxonomy root), and dispatches to a family-appropriate control. Selection is
+// controlled: the
+// component emits the chosen preset id; the host applies it via `kaleidoscope`.
+//
+// No runtime imports from platform-specific packages live here (it is the
+// shared `.types.ts` for the platform-split resolver too); only `react` types.
+
+import type { ReactNode } from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+import type { KaleidoscopePresetBook } from '../../kaleidoscope.preset-book.types';
+
+/**
+ * A composite's family; the grouping (tab) axis. This is the book entry's
+ * taxonomy root (`taxonomy[0]`, e.g. 'Worlds', 'Backgrounds').
+ */
+export type Family = string;
+
+/**
+ * A composite's category; the second grouping axis under a family (the
+ * left-hand menu). This is the book entry's `taxonomy[1]` (e.g. 'Wizard Tower'
+ * under 'Worlds', 'Office' under 'Backgrounds'). Absent for a depth-1 preset.
+ */
+export type Category = string;
+
+/**
+ * A preset flattened for display. `id` is the book key the picker emits and the
+ * effect dispatches by; `source` is a thumbnail source (the composite's
+ * `thumbnail`) when present, feeding the thumbnail tile/resolver.
+ */
+export interface PresetView {
+  readonly id: string;
+  readonly label: string;
+  readonly family: Family;
+  /** The preset's category (`taxonomy[1]`); undefined for a depth-1 preset. */
+  readonly category?: Category | undefined;
+  /**
+   * Thumbnail source (web URL or native preset name as `string`, or a Metro
+   * asset module id as `number`); present when the book entry has one.
+   */
+  readonly source?: string | number | undefined;
+}
+
+/**
+ * The item's own interaction state, passed to a render-prop so a BYO tile/button
+ * can reflect it. This is the leaf's interaction surface (its own selected/press
+ * lifecycle), not a relayed parent-state flag.
+ */
+export interface PresetItemState {
+  readonly selected: boolean;
+  readonly disabled: boolean;
+  readonly onPress: () => void;
+}
+
+/**
+ * Render-prop for one preset tile. `uri` is the resolved thumbnail source
+ * (undefined renders the recessed variant); `testID` is the tile's deterministic
+ * `accessibilityIdentifier` (`kld.preset.<id>`), which a BYO tile should apply to
+ * its pressable root so Maestro can address it.
+ */
+export type RenderTile = (
+  preset: PresetView,
+  state: PresetItemState & {
+    readonly uri: string | number | undefined;
+    readonly testID: string;
+  },
+) => ReactNode;
+
+/**
+ * Controlled single-selection contract shared by every picker surface. `K` is
+ * the id type: the composite narrows it to `keyof P` so `value`/`onSelect` speak
+ * the book's keys (no cast at the call site), matching how `kaleidoscope(cmd)`
+ * narrows. Standalone primitives default `K` to `string`.
+ */
+export interface PresetBookMenuSelection<K extends string = string> {
+  /** The selected preset id, or null when nothing is selected. */
+  readonly value: K | null;
+  /**
+   * Emitted with the chosen id, or null when the selection is toggled off
+   * (clicking the selected item clears it, mapping to `kaleidoscope(null)`).
+   */
+  readonly onSelect: (id: K | null) => void;
+}
+
+/** Props common to the picker surfaces; styling and templating hooks. */
+export interface PresetBookMenuStyleProps {
+  readonly disabled?: boolean | undefined;
+  /** Container class; resolved by NativeWind via the `./nativewind` interop. */
+  readonly className?: string | undefined;
+  /** Override the per-preset tile rendering (BYO tile). */
+  readonly renderTile?: RenderTile | undefined;
+}
+
+/** Props for the drop-in composite picker (the tabbed kitchen sink). */
+export interface PresetBookMenuProps<P extends KaleidoscopePresetBook = KaleidoscopePresetBook>
+  extends PresetBookMenuSelection<keyof P & string>,
+    PresetBookMenuStyleProps {
+  /** The consumer's preset book. */
+  readonly presets: P;
+  /** RN style override for the container; applied after the defaults. */
+  readonly style?: StyleProp<ViewStyle> | undefined;
+  /** Map a preset id to a display label; defaults to a title-cased id. */
+  readonly labelFor?: ((id: keyof P & string) => string) | undefined;
+  /** Label a family tab; defaults to a title-cased family name. */
+  readonly tabLabelFor?: ((family: Family) => string) | undefined;
+  /** Label a category menu item; defaults to the raw category string. */
+  readonly categoryLabelFor?: ((category: Category) => string) | undefined;
+}

package/src/components/preset-book-menu/preset-grid.tsx

@@ -0,0 +1,80 @@
+// Family renderer: one family's presets as a uniform tile grid. Every family
+// renders through this; the per-preset tile decides wallpaper-vs-recessed by
+// whether it has a resolved thumbnail, so a family with no thumbnails just
+// renders recessed buttons of the same footprint. The tile renderer is the
+// `renderTile` slot or the default.
+//
+// The thumbnail URI comes from the platform-split `resolveImageUri`: the
+// source URL on web, the in-bundle file:// URI on native; undefined for a preset
+// with no thumbnail (the tile then renders its recessed variant).
+
+import { Fragment } from 'react';
+import { type StyleProp, StyleSheet, View, type ViewStyle } from 'react-native';
+import { presetTileTestId } from '../../lib/test-id';
+import { PresetTile } from '../preset-tile';
+import type { PresetView, RenderTile } from './preset-book-menu.types';
+import { resolveImageUri } from './resolve-image-uri';
+
+interface PresetGridProps {
+  readonly presets: ReadonlyArray<PresetView>;
+  readonly value: string | null;
+  readonly onSelect: (id: string | null) => void;
+  readonly disabled?: boolean | undefined;
+  /** Override the tile rendering (BYO tile, e.g. to add a badge). */
+  readonly renderTile?: RenderTile | undefined;
+  /** NativeWind class for the grid container; resolved via the `./nativewind` interop. */
+  readonly className?: string | undefined;
+  readonly style?: StyleProp<ViewStyle> | undefined;
+}
+
+const defaultRenderTile: RenderTile = (preset, state) => (
+  <PresetTile
+    label={preset.label}
+    uri={state.uri}
+    selected={state.selected}
+    disabled={state.disabled}
+    onPress={state.onPress}
+    testID={state.testID}
+  />
+);
+
+export function PresetGrid(props: PresetGridProps) {
+  const { presets, value, onSelect, disabled = false, renderTile, style } = props;
+  const renderItem = renderTile ?? defaultRenderTile;
+  // Resolve each preset's thumbnail URI; pure in (id, source), so React Compiler
+  // memoizes the map by `presets` when the library is compiled.
+  // The native resolver looks the thumbnail up by id in Bundle.main. For image
+  // presets the preset id and the thumbnail's bundle filename coincide (a
+  // background's image id IS its preset id); for composites they differ (the
+  // composite's thumb is bundled as `<composite-id>-thumb.webp`), so pass the
+  // source as the lookup key when it is a string and falls back to the preset
+  // id otherwise.
+  const uriById = new Map(
+    presets.map((p) => {
+      const lookupId = typeof p.source === 'string' ? p.source : p.id;
+      return [p.id, resolveImageUri(lookupId, p.source)] as const;
+    }),
+  );
+  return (
+    <View accessibilityRole="radiogroup" accessibilityLabel="Presets" style={[styles.grid, style]}>
+      {presets.map((preset) => {
+        const selected = value === preset.id;
+        return (
+          <Fragment key={preset.id}>
+            {renderItem(preset, {
+              selected,
+              disabled,
+              uri: uriById.get(preset.id),
+              onPress: () => onSelect(selected ? null : preset.id),
+              testID: presetTileTestId(preset.id),
+            })}
+          </Fragment>
+        );
+      })}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  grid: { flexDirection: 'row', flexWrap: 'wrap', gap: 8, width: '100%' },
+});

package/src/components/preset-book-menu/resolve-image-uri.ts

@@ -0,0 +1,31 @@
+// Native variant: the prebuild copied the curated WebP to a conventional
+// in-bundle location; the native module returns a displayable URI for it
+// (Android `asset:///...` so Fresco's asset fetcher loads it, iOS the
+// `Bundle.main` file URL). No second copy of the image.
+//
+// The `resolveImageUri` Expo function is optional here: a native build
+// predating it (or a non-background effect build) simply lacks it, so guard with
+// `?.` and fall back to the source (the preset name), which renders no thumbnail
+// rather than crashing.
+
+import { requireNativeModule } from 'expo-modules-core';
+import type { ResolveImageUri } from './resolve-image-uri.types';
+
+interface ImageUriModule {
+  readonly resolveImageUri?: (id: string) => string | null;
+}
+
+// Resolve the module once, lazily; it is registered at the Expo module's
+// OnCreate, before any picker renders. Hoisted out of the per-call path so a
+// grid of N tiles does not perform N module lookups per render.
+let cachedModule: ImageUriModule | undefined;
+const nativeModule = (): ImageUriModule =>
+  (cachedModule ??= requireNativeModule<ImageUriModule>('RnWebrtcKaleidoscope'));
+
+export const resolveImageUri: ResolveImageUri = (id, source) => {
+  // A numeric source is a Metro asset module id (from `require('./foo.webp')`)
+  // and is consumable directly by `<Image source={number}>`; the native module
+  // resolves only string preset names, so pass numbers straight through.
+  if (typeof source === 'number') return source;
+  return nativeModule().resolveImageUri?.(id) ?? source;
+};

package/src/components/preset-book-menu/resolve-image-uri.types.ts

@@ -0,0 +1,18 @@
+// Shared contract for the platform-split thumbnail resolver. No runtime imports
+// from platform-specific packages (web and native variants both import this).
+
+/**
+ * Resolve a displayable thumbnail source for a preset.
+ * - Web: the preset `source` is already a usable image URL; returned as-is.
+ * - Native: the bundled WebP lives at a conventional in-bundle location; the
+ *   native module returns a `file://` URI for it (no second copy of the image).
+ *   When `source` is a `number` (a Metro asset module id), it bypasses the
+ *   native module and is returned as-is so `<Image source={number}>` can load
+ *   it directly through Metro's asset pipeline.
+ * Returns `undefined` when no thumbnail can be resolved (the tile shows just its
+ * label).
+ */
+export type ResolveImageUri = (
+  id: string,
+  source: string | number | undefined,
+) => string | number | undefined;

package/src/components/preset-book-menu/resolve-image-uri.web.ts

@@ -0,0 +1,15 @@
+// Web variant: the preset source is already a bundled image URL, so the
+// thumbnail URI is the source itself.
+//
+// How this file gets picked over the native sibling: Metro resolves the bare
+// `../resolve-image-uri` import to `.web.ts` via platform extensions; for
+// non-Metro dist consumers it is selected by the top-level `browser` FIELD remap
+// in package.json (dist/.../resolve-image-uri.js -> .web.js). That is a
+// different mechanism than the `backgrounds/*` subpath `exports` browser
+// CONDITIONS, because this file is reached by an internal relative import, not a
+// subpath export. Adding another platform-split file under src/ui consumed via a
+// bare import means extending that `browser` field, not adding an exports entry.
+
+import type { ResolveImageUri } from './resolve-image-uri.types';
+
+export const resolveImageUri: ResolveImageUri = (_id, source) => source;

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

@@ -0,0 +1,56 @@
+// CompositeLayerControlPanel: render a shader's `*_CONTROLS` descriptor list as
+// fields, in order, data-driven. This is the AUTO-FORM (the default when a shader
+// ships no custom layout form): `<CompositeLayerControlPanel controls={CLOUDS_CONTROLS} />`.
+// It maps every descriptor through the shared `dispatchControl`, so it handles
+// every kind (color, float, switch, polygon) the same way `<Control>` does.
+//
+// KaleidoscopePreset-level customization is props: pass a filtered `controls`
+// array to hide knobs, or `overrides` to narrow a control's range/label for this
+// composite. For real layout (grouping, split, per-beam lists), a shader exports
+// a custom form of `<Control uniform>`s instead of using this panel.
+
+import { Fragment } from 'react';
+import type { UniformControl } from '../../../catalog/shaders';
+import { dispatchControl } from './control';
+
+/** Per-uniform range/label override, keyed by uniform name. */
+export type ControlOverride = {
+  readonly min?: number;
+  readonly max?: number;
+  readonly step?: number;
+  readonly label?: string;
+};
+
+export type CompositeLayerControlPanelProps = {
+  readonly controls: readonly UniformControl[];
+  readonly overrides?: Readonly<Record<string, ControlOverride>>;
+};
+
+// Merge a preset override onto a descriptor. min/max/step only apply to float;
+// label applies to any kind.
+function withOverride(c: UniformControl, o?: ControlOverride): UniformControl {
+  if (!o) return c;
+  if (c.kind === 'float') {
+    return {
+      ...c,
+      min: o.min ?? c.min,
+      max: o.max ?? c.max,
+      step: o.step ?? c.step,
+      label: o.label ?? c.label,
+    };
+  }
+  return o.label ? { ...c, label: o.label } : c;
+}
+
+export function CompositeLayerControlPanel({
+  controls,
+  overrides,
+}: CompositeLayerControlPanelProps) {
+  return (
+    <>
+      {controls.map((c) => (
+        <Fragment key={c.name}>{dispatchControl(withOverride(c, overrides?.[c.name]))}</Fragment>
+      ))}
+    </>
+  );
+}