react-native-webrtc-kaleidoscope 2.0.0 → 2.1.0

package/plugin/build/lib/preset-book.js

@@ -0,0 +1,215 @@
+// @generated by `bun run build:plugin`; DO NOT EDIT THIS FILE.
+// Source of truth: plugin/src/. Edit the TypeScript there, then run
+// `bun run build:plugin` to regenerate this committed output.
+// Committed (not in dist/) because Expo loads the config plugin via
+// app.plugin.js -> ./plugin/build at prebuild time, including on EAS workers
+// where the library's dist/ and node_modules are absent.
+
+'use strict';
+// Static analysis of the consumer's preset book (prebuild-only).
+//
+// The book is read as TEXT, never executed: a layer's `source` is per-platform
+// (a URL on web, an image id on native), so it is not a static specifier;
+// instead we read the book's imports and its `image` layers to learn which asset
+// each preset references. The runtime never does this; it receives the book as a
+// real object. So this lives in the plugin, not the runtime.
+//
+// Static-analyzability is the consumer's contract (documented in the README):
+// each `image` layer is `{ id, shader: 'image', source: <ref> }`, where <ref> is
+// a `require('./x.webp')` literal, a single named import from an
+// `.../images/<category>/<leaf>` specifier, or a `const X = ...require('./x.webp')...`
+// binding. Anything that can't be parsed or resolved warns (never throws),
+// matching the plugin's non-fatal contract.
+var __importDefault =
+  (this && this.__importDefault) ||
+  function (mod) {
+    return mod && mod.__esModule ? mod : { default: mod };
+  };
+Object.defineProperty(exports, '__esModule', { value: true });
+exports.PRESET_BOOK_FILENAME = void 0;
+exports.collectReferencedAssets = collectReferencedAssets;
+const node_fs_1 = __importDefault(require('node:fs'));
+const node_path_1 = __importDefault(require('node:path'));
+const file_manipulation_1 = require('./file-manipulation');
+/** The file a consumer declares at their project root. */
+exports.PRESET_BOOK_FILENAME = 'kaleidoscope.preset-book.ts';
+/**
+ * Local binding -> import specifier, for single named imports (`{ X }` and
+ * `{ X as Y }`; the LOCAL name is what a layer's `source` references) plus
+ * `const X = ...require('spec')...` bindings (the idiomatic Expo
+ * `Asset.fromModule(require('./x.webp')).uri`). Imports win on a name clash.
+ */
+function parseImports(source) {
+  const imports = {};
+  const re =
+    /import\s*\{\s*([A-Za-z0-9_$]+)(?:\s+as\s+([A-Za-z0-9_$]+))?\s*\}\s*from\s*['"]([^'"]+)['"]/g;
+  for (const m of source.matchAll(re)) {
+    const local = m[2] ?? m[1];
+    const specifier = m[3];
+    if (local && specifier) imports[local] = specifier;
+  }
+  const requireBindingRe =
+    /(?:const|let|var)\s+([A-Za-z0-9_$]+)\s*=\s*[^;\n]*\brequire\(\s*['"]([^'"]+)['"]\s*\)/g;
+  for (const m of source.matchAll(requireBindingRe)) {
+    const local = m[1];
+    const specifier = m[2];
+    if (local && specifier && !(local in imports)) imports[local] = specifier;
+  }
+  return imports;
+}
+/**
+ * Derive an image id from its source specifier: the basename without extension
+ * (`'./assets/wolf-cave.webp'` -> `'wolf-cave'`). The fallback id when an image
+ * layer omits an explicit `id`; matches the basename==id convention the runtime
+ * sends as the native `source` (native resolves `assets/images/<id>.webp`).
+ */
+function imageIdFromSpecifier(specifier) {
+  const segment = specifier.substring(specifier.lastIndexOf('/') + 1);
+  return segment.replace(/\.[^.]+$/, '');
+}
+/**
+ * Every `image` layer's id + asset specifier in a source file (the book OR an
+ * imported composite). The id is the layer's `id` (the basename native resolves
+ * by); the specifier resolves to the `.webp`.
+ */
+function parseImageRefs(source) {
+  const imports = parseImports(source);
+  const refs = [];
+  const seen = new Set();
+  // Each image-layer object is a flat brace group containing `shader: 'image'`.
+  const layerRe = /\{([^{}]*shader\s*:\s*['"]image['"][^{}]*)\}/g;
+  for (const m of source.matchAll(layerRe)) {
+    const body = m[1];
+    if (!body) continue;
+    const sourceM = body.match(/source\s*:\s*(require\(\s*['"][^'"]+['"]\s*\)|[A-Za-z0-9_$]+)/);
+    const expr = sourceM?.[1];
+    if (!expr) continue;
+    const requireLiteral = expr.match(/require\(\s*['"]([^'"]+)['"]\s*\)/);
+    const specifier = requireLiteral ? requireLiteral[1] : (imports[expr] ?? null);
+    if (!specifier) continue;
+    const idM = body.match(/\bid\s*:\s*['"]([\w-]+)['"]/);
+    const id = idM?.[1] ?? imageIdFromSpecifier(specifier);
+    if (seen.has(id)) continue;
+    seen.add(id);
+    refs.push({ id, specifier });
+  }
+  return refs;
+}
+/**
+ * Resolve an imported-composite specifier (`<pkg>/composites/<name>`) to its
+ * source `.ts` on disk. Returns null for a non-composite specifier or an
+ * unresolvable package.
+ */
+function resolveCompositeSource(specifier, projectRoot) {
+  if (!/(^|\/)composites\/[\w-]+$/.test(specifier)) return null;
+  const name = specifier.substring(specifier.lastIndexOf('/') + 1);
+  try {
+    const pkgJson = require.resolve('react-native-webrtc-kaleidoscope/package.json', {
+      paths: [projectRoot],
+    });
+    const ts = node_path_1.default.join(
+      node_path_1.default.dirname(pkgJson),
+      'catalog',
+      'composites',
+      name,
+      `${name}.ts`,
+    );
+    return node_fs_1.default.existsSync(ts) ? ts : null;
+  } catch {
+    return null;
+  }
+}
+/** Resolve an `image` layer's `source` specifier to an on-disk WebP path. */
+function resolveAssetPath(specifier, baseDir, projectRoot) {
+  if (specifier.startsWith('.') || node_path_1.default.isAbsolute(specifier)) {
+    const abs = node_path_1.default.resolve(baseDir, specifier);
+    for (const candidate of [`${abs}.webp`, abs]) {
+      if (node_fs_1.default.existsSync(candidate)) return candidate;
+    }
+    return null;
+  }
+  try {
+    return require.resolve(`${specifier}.webp`, { paths: [projectRoot] });
+  } catch {
+    try {
+      return require.resolve(specifier, { paths: [projectRoot] });
+    } catch {
+      return null;
+    }
+  }
+}
+// Walk a book's own source plus every imported-composite source, yielding each
+// with the base dir its relative specifiers resolve against. Shared by both
+// collectors so neither drifts from the other.
+function walkBookSources(bookSource, projectRoot) {
+  const sources = [{ source: bookSource, baseDir: projectRoot }];
+  for (const specifier of Object.values(parseImports(bookSource))) {
+    const compositePath = resolveCompositeSource(specifier, projectRoot);
+    if (!compositePath) continue;
+    const compositeSource = (0, file_manipulation_1.readTextOrNull)(compositePath);
+    // Non-fatal: a composite we cannot read contributes nothing.
+    if (compositeSource !== null) {
+      sources.push({
+        source: compositeSource,
+        baseDir: node_path_1.default.dirname(compositePath),
+      });
+    }
+  }
+  return sources;
+}
+/**
+ * Every image a preset book needs: the image layers declared inline in the book
+ * PLUS the image layers inside every packaged composite it imports.
+ */
+function collectImageRefs(bookSource, projectRoot) {
+  const refs = [];
+  const seen = new Set();
+  for (const { source, baseDir } of walkBookSources(bookSource, projectRoot)) {
+    for (const { id, specifier } of parseImageRefs(source)) {
+      if (seen.has(id)) continue;
+      seen.add(id);
+      refs.push({ id, specifier, srcPath: resolveAssetPath(specifier, baseDir, projectRoot) });
+    }
+  }
+  return refs;
+}
+/**
+ * Every packaged composite's `<name>.thumb.webp`, keyed by `<name>-thumb` (the
+ * suffix disambiguates from a same-named image). Mirrors collectImageRefs but for
+ * the picker-tile thumbnails (a different asset family).
+ */
+function collectCompositeThumbRefs(bookSource, projectRoot) {
+  const refs = [];
+  const seen = new Set();
+  for (const specifier of Object.values(parseImports(bookSource))) {
+    const compositeTs = resolveCompositeSource(specifier, projectRoot);
+    if (!compositeTs) continue;
+    const name = specifier.substring(specifier.lastIndexOf('/') + 1);
+    if (seen.has(name)) continue;
+    const thumbPath = node_path_1.default.join(
+      node_path_1.default.dirname(compositeTs),
+      `${name}.thumb.webp`,
+    );
+    if (!node_fs_1.default.existsSync(thumbPath)) continue;
+    seen.add(name);
+    refs.push({ id: `${name}-thumb`, srcPath: thumbPath });
+  }
+  return refs;
+}
+/**
+ * Read the consumer's preset book at the project root and collect every asset it
+ * references: image-layer images plus packaged-composite thumbnails. Returns null
+ * when there is no book (a consumer that declares no assets), which both
+ * platforms treat as "nothing to bundle, stay quiet". The ONE place the book is
+ * read from disk; the platform asset modules consume the result.
+ */
+function collectReferencedAssets(projectRoot) {
+  const source = (0, file_manipulation_1.readTextOrNull)(
+    node_path_1.default.join(projectRoot, exports.PRESET_BOOK_FILENAME),
+  );
+  if (source === null) return null;
+  return {
+    images: collectImageRefs(source, projectRoot),
+    thumbs: collectCompositeThumbRefs(source, projectRoot),
+  };
+}

package/plugin/build/lib/types.js

@@ -0,0 +1,16 @@
+// @generated by `bun run build:plugin`; DO NOT EDIT THIS FILE.
+// Source of truth: plugin/src/. Edit the TypeScript there, then run
+// `bun run build:plugin` to regenerate this committed output.
+// Committed (not in dist/) because Expo loads the config plugin via
+// app.plugin.js -> ./plugin/build at prebuild time, including on EAS workers
+// where the library's dist/ and node_modules are absent.
+
+'use strict';
+// Minimal structural shapes for the slice of the Expo prebuild config + ModConfig
+// this plugin touches. We deliberately DON'T import these from
+// @expo/config-plugins: the compiled plugin must LOAD on an EAS worker where
+// @expo/config-plugins is not installed at app.plugin.js's realpath (see
+// index.ts). A structural subset is enough for compile-time safety and keeps the
+// load-time dependency surface at zero. @expo/config-plugins is still resolved at
+// RUNTIME, lazily, from the consumer (ios-assets.ts) where it is installed.
+Object.defineProperty(exports, '__esModule', { value: true });

package/src/components/form/control-form.tsx

@@ -0,0 +1,112 @@
+// ControlForm: the per-layer micro-provider that owns one form's view model.
+//
+// It holds the synchronous local values fields read (so a slider tracks the drag
+// without a host round-trip) and emits the debounced, trailing-flushed
+// `onPatch({ id, uniforms })` the host routes into `kaleidoscope(activeId, [...])`.
+//
+// Reset is by REMOUNT, never by effect: the Tuner renders the active controls
+// component keyed by preset id, so a preset switch unmounts this and a fresh
+// ControlForm re-seeds from `uniforms`. There is no effect syncing state to props.
+
+import type { ReactNode } from 'react';
+import { createContext, useContext, useEffect, useReducer, useRef } from 'react';
+import type { UniformControl } from '../../../catalog/shaders';
+import { controlScope } from '../../lib/test-id';
+import { ControlScopeContext } from './scope';
+
+/** One field's value: a scalar uniform or a vecN (e.g. an RGB triple). */
+export type FieldValue = number | readonly number[];
+
+type FormValues = Readonly<Record<string, FieldValue>>;
+
+/** The live form state a field reads/writes via `useField`. */
+export type ControlFormContextValue = {
+  readonly values: FormValues;
+  readonly setField: (key: string, value: FieldValue) => void;
+  readonly disabled: boolean;
+  /** The form's test-id scope (`kld.<preset>.<layer>`); fields append their uniform. */
+  readonly path: string;
+  /** The control descriptors, so `<Control uniform>` can resolve one by name. */
+  readonly controls?: readonly UniformControl[];
+};
+
+export const ControlFormContext = createContext<ControlFormContextValue | null>(null);
+
+type Action = { readonly key: string; readonly value: FieldValue };
+
+function reducer(state: FormValues, action: Action): FormValues {
+  return { ...state, [action.key]: action.value };
+}
+
+export type ControlFormProps = {
+  /** The layer id this form patches; the discriminator in the emitted patch. */
+  readonly id: string;
+  /** The layer's baked uniforms; the form seeds from these at mount. */
+  readonly uniforms: FormValues;
+  /** Emitted (debounced) with the layer id and the current edited uniforms. */
+  readonly onPatch: (patch: { id: string; uniforms: Record<string, FieldValue> }) => void;
+  /** Disables every field in the form (read by `useField`). */
+  readonly disabled?: boolean;
+  /** Trailing-edge debounce for the emit, in ms. 0 (default) emits per change. */
+  readonly debounceMs?: number;
+  /** The shader's control descriptors; lets children use `<Control uniform>`. */
+  readonly controls?: readonly UniformControl[];
+  readonly children: ReactNode;
+};
+
+export function ControlForm({
+  id,
+  uniforms,
+  onPatch,
+  disabled = false,
+  debounceMs = 0,
+  controls,
+  children,
+}: ControlFormProps) {
+  const [values, dispatch] = useReducer(reducer, uniforms);
+
+  // Latest onPatch in a ref so the emit effect doesn't re-arm when the parent
+  // passes a fresh callback each render.
+  const onPatchRef = useRef(onPatch);
+  onPatchRef.current = onPatch;
+
+  // The latest not-yet-emitted edit, held so it can be flushed on unmount (a
+  // preset switch remounts this form mid-debounce; the trailing value must not be
+  // lost). Cleared when it fires.
+  const pending = useRef<(() => void) | null>(null);
+
+  // Skip the emit for the initial seed; only edits should patch.
+  const seeded = useRef(false);
+  useEffect(() => {
+    if (!seeded.current) {
+      seeded.current = true;
+      return;
+    }
+    const fire = () => {
+      pending.current = null;
+      onPatchRef.current({ id, uniforms: { ...values } });
+    };
+    if (debounceMs <= 0) {
+      fire();
+      return;
+    }
+    pending.current = fire;
+    const t = setTimeout(fire, debounceMs);
+    return () => clearTimeout(t);
+  }, [values, id, debounceMs]);
+
+  // Flush a pending debounced edit on unmount so the trailing value survives a
+  // remount/preset switch.
+  useEffect(() => () => pending.current?.(), []);
+
+  const presetId = useContext(ControlScopeContext);
+  const ctx: ControlFormContextValue = {
+    values,
+    setField: (key, value) => dispatch({ key, value }),
+    disabled,
+    path: controlScope(presetId, id),
+    controls,
+  };
+
+  return <ControlFormContext.Provider value={ctx}>{children}</ControlFormContext.Provider>;
+}

package/src/components/form/make-controls.ts

@@ -0,0 +1,33 @@
+// makeControls<U>(): the typed-factory escape from React context invariance.
+// Returns the field primitives with their `uniform` prop narrowed to the keys of
+// the shader's uniform type whose value matches the widget (numeric keys for the
+// Slider, RGB-tuple keys for the ColorPicker). A shader fragment authors
+// `const { Slider, ColorPicker } = makeControls<CloudsUniforms>()`, after which a
+// typo'd or wrong-typed `uniform` is a compile error. The components still
+// self-wire through the nearest ControlForm at runtime.
+
+import type { ReactElement } from 'react';
+import type { RGB } from '../../lib/primitives.types';
+import { ColorPicker, type ColorPickerProps } from '../ui/color-picker';
+import { Slider, type SliderProps } from '../ui/slider';
+
+type NumericKeys<U> = { [K in keyof U]: U[K] extends number ? K : never }[keyof U];
+type RgbKeys<U> = { [K in keyof U]: U[K] extends RGB ? K : never }[keyof U];
+
+type TypedSlider<U> = (
+  props: Omit<SliderProps, 'uniform'> & { readonly uniform: NumericKeys<U> & string },
+) => ReactElement;
+
+type TypedColorPicker<U> = (
+  props: Omit<ColorPickerProps, 'uniform'> & { readonly uniform: RgbKeys<U> & string },
+) => ReactElement;
+
+export function makeControls<U>(): {
+  readonly Slider: TypedSlider<U>;
+  readonly ColorPicker: TypedColorPicker<U>;
+} {
+  return {
+    Slider: Slider as TypedSlider<U>,
+    ColorPicker: ColorPicker as TypedColorPicker<U>,
+  };
+}

package/src/components/form/scope.ts

@@ -0,0 +1,9 @@
+// ControlScopeContext: the active preset id, provided by PresetControlPanel above
+// the controls component so each ControlForm can compose its test-id scope
+// (`kld.<preset>.<layer>`) without the per-composite forms having to thread it.
+// Null when a ControlForm is rendered standalone (no Tuner); the scope then
+// drops the preset segment.
+
+import { createContext } from 'react';
+
+export const ControlScopeContext = createContext<string | null>(null);

package/src/components/form/use-field.ts

@@ -0,0 +1,35 @@
+// useField: a control primitive's hook into its ControlForm. Reads the field's
+// current value (synchronously, so display tracks input) and returns an onChange
+// that writes back. Throws without a ControlForm ancestor, which is the contract
+// that keeps shader fragments from being rendered standalone.
+//
+// This is the raw, loosely-typed hook; `makeControls<U>()` wraps it to constrain
+// the key and value types to a shader's uniform type.
+
+import { useContext } from 'react';
+import { fieldTestId } from '../../lib/test-id';
+import { ControlFormContext, type FieldValue } from './control-form';
+
+export type Field = {
+  readonly value: FieldValue | undefined;
+  readonly onChange: (value: FieldValue) => void;
+  readonly disabled: boolean;
+  /** Deterministic `accessibilityIdentifier` for this field: `<form path>.<key>`. */
+  readonly testID: string;
+};
+
+export function useField(key: string): Field {
+  const ctx = useContext(ControlFormContext);
+  if (ctx === null) {
+    throw new Error(
+      `useField("${key}") must be rendered inside a <ControlForm>. A shader control ` +
+        'fragment is mounted by its composite form, not standalone.',
+    );
+  }
+  return {
+    value: ctx.values[key],
+    onChange: (value) => ctx.setField(key, value),
+    disabled: ctx.disabled,
+    testID: fieldTestId(ctx.path, key),
+  };
+}