react-native-webrtc-kaleidoscope 1.0.0 → 1.1.0

package/README.md

@@ -14,7 +14,7 @@
 
 ## Status
 
-**Active development; not yet production-ready.** Published to npm as `0.1.0-alpha.x` for name reservation and integration testing. The npm presentation, marketing, and release-quality polish will come in a later pass; right now the README's job is to tell the truth about what works.
+**Active development; not yet production-ready.** Published to npm at `1.0.0` (semantic-release cut the first tag at 1.0.0; the number reflects release automation, not a maturity claim). The npm presentation, marketing, and release-quality polish will come in a later pass; right now the README's job is to tell the truth about what works.
 
 ### What works today
 
@@ -27,12 +27,11 @@
 |---|---|---|---|---|
 | Web (Chrome / Edge) | ✓ | ✓ | ✓ | MediaStreamTrackProcessor + MediaPipe Selfie Segmentation (WASM, CDN) |
 | Android (API 24+) | ✓ | ✓ | ✓ | OpenGL ES 3.0 + MLKit Selfie Segmentation |
-| iOS (≥ 15) | — | — | — | Coming soon; transpilation pipeline in place, host implementation pending |
+| iOS (≥ 15) | ✓ | ✓ | ✓ | Metal + Vision (person segmentation), verified on device. Older A11 devices (iPhone X) run at a lower frame rate |
 | Safari / Firefox | — | — | — | No Insertable Streams; `applyVideoEffects` throws a typed error |
 
 ### Coming soon
 
-- **iOS support**, via the canonical GLSL transpiled to Metal Shading Language (`glslangValidator` → `spirv-cross --msl`). The pipeline is in the repo at `scripts/transpile-shaders.ts` and the GLSL canonical source lives in `shaders/`. The Swift host code that loads the metallib and runs the Metal pipeline is the next chunk of work.
 - **Procedural backgrounds** (animated shaders behind the person, not just still images). Same composite path; the only new piece is each effect's background producer.
 - A careful pass over the npm presentation, install docs, and demo polish before any "we recommend you use this" framing.
 
@@ -54,6 +53,24 @@ bun add @livekit/react-native @livekit/react-native-webrtc react-native-webrtc-k
 
 Pick one fork. Installing both upstream `react-native-webrtc` and `@livekit/react-native-webrtc` in the same app will cause native class collisions; that's the consumer's problem to resolve.
 
+**Native wiring.** `@livekit/react-native` hands you a `LocalVideoTrack`; apply effects to its underlying `MediaStreamTrack`:
+
+```ts
+import { applyVideoEffects } from 'react-native-webrtc-kaleidoscope';
+
+applyVideoEffects(localCameraTrack.mediaStreamTrack, ['blur']);
+```
+
+**Web wiring.** On web, LiveKit owns the `RTCRtpSender`, so you cannot swap the track yourself; go through LiveKit's processor API instead. The opt-in `/livekit` subpath ships a ready-made processor (it needs `livekit-client`, which a LiveKit app already has):
+
+```ts
+import { KaleidoscopeProcessor } from 'react-native-webrtc-kaleidoscope/livekit';
+
+await localVideoTrack.setProcessor(new KaleidoscopeProcessor(['blur']), true);
+```
+
+The second argument shows the processed stream in your local preview. The processor tears down its Insertable-Streams pipeline on camera flip (`restart`) and unpublish (`destroy`), so repeated flips do not leak generators.
+
 ## Configure
 
 Add the config plugin to `app.config.ts`:
@@ -110,6 +127,16 @@ Effects chain in array order.
 
 The library ships neutral defaults (8, 0.5, 0.5) and consumers tune at runtime via the API above; whether to ship the dialed-in values as platform-specific defaults is an open question waiting on iOS data.
 
+## Web and native differences
+
+The API surface is the same across platforms, but the runtimes differ in ways worth knowing before you wire effects in:
+
+- **Effect parameters.** Web reads tuning from the global setters (`setBlurSigma`, `setMaskHardness`, `setMaskThreshold`) on the next frame. Native currently ignores per-call `EffectSpec` parameters such as `{ name: 'blur', sigma: 12 }`; tuning is global through the same setters. Per-call uniforms through the native registry are a follow-up.
+- **Background source.** `background-image.source` is a bundled preset name on native (the upstream `_setVideoEffects` registry is keyed by flat strings, not URIs), but on web it accepts either a preset name or an arbitrary image URL or data URI.
+- **Background presets ship as tree-shakeable files.** Two example backgrounds (`office-1`, `office-2`) are importable per preset: `import { office1 } from 'react-native-webrtc-kaleidoscope/backgrounds/office-1'`. Each preset is its own file behind its own subpath export, and the package sets `sideEffects: false`, so an unused preset is dropped by web bundlers — and, since Metro doesn't tree-shake, simply never imported on native. Web resolves the bundled WebP to a URL; native loads its own bundled copy by name. Web also still accepts an arbitrary image URL or data URI. See [`src/backgrounds/README.md`](./src/backgrounds/README.md).
+- **Segmentation model on web.** The web blur and background-image effects load MediaPipe Selfie Segmentation from the jsdelivr CDN (`cdn.jsdelivr.net/npm/@mediapipe/selfie_segmentation`) on first use. A strict Content-Security-Policy must allow that origin for `script-src`, `connect-src`, and the WASM fetch, and the effects do not work offline. Mirror needs no model.
+- **Browser support on web.** Effects use Insertable Streams (`MediaStreamTrackProcessor` and `MediaStreamTrackGenerator`), which ship in Chromium-based browsers; Safari and Firefox throw a typed capability error.
+
 ## What this isn't
 
 - **Not a fork of `react-native-webrtc`.** A thin layer over its undocumented `_setVideoEffects` registry on native, and `MediaStreamTrackProcessor` on web. Install alongside `react-native-webrtc`.
@@ -124,7 +151,7 @@ The codebase lives across four surfaces:
 - `src/` — JS facade and shared types. `applyVideoEffects(track, effects)` plus runtime tuning setters.
 - `src/web/` — WebGL2 pipeline. MediaPipe segmentation + GLSL composite. One shader file per stage in `src/web/shaders.ts`.
 - `android/` — OpenGL ES 3.0 pipeline. MLKit segmentation (async, worker-thread, last-known-mask cache) + GLSL composite. Shaders inline in `gpu/Shaders.kt` as `const val` strings.
-- `ios/` — Scaffold only; the canonical GLSL in `shaders/` will transpile to Metal Shading Language for the iOS path.
+- `ios/` — Metal pipeline (Swift) with Vision person segmentation. The canonical GLSL in `shaders/` transpiles to Metal Shading Language via `scripts/build-shaders.ts`. Implemented and verified on device.
 
 The composite shader (`shaders/composite.frag`) is the same GLSL source for every effect category (blur, background-image, future procedural backgrounds). Per-effect difference is upstream of the composite: how the `uBackground` texture gets produced.
 

package/android/build.gradle

@@ -4,7 +4,9 @@ apply plugin: 'com.android.library'
 apply plugin: 'kotlin-android'
 
 group = 'com.simiancraft.kaleidoscope'
-version = '0.1.0-alpha.1'
+// Single source of truth for the version is package.json (the iOS podspec reads
+// it the same way), so the three platforms cannot drift apart.
+version = new groovy.json.JsonSlurper().parseText(file("../package.json").text).version
 
 def expoModulesCorePlugin = new File(project(":expo-modules-core").projectDir.absolutePath, "ExpoModulesCorePlugin.gradle")
 if (expoModulesCorePlugin.exists()) {

package/android/src/main/java/com/simiancraft/kaleidoscope/Registration.kt

@@ -32,8 +32,8 @@ object Registration {
       BackgroundImageFactory(context, "office-2"),
     )
 
-    // Architecture-proof hook from PLAN.md Commit 3. Removed in the cleanup
-    // pass before v0.1 ships.
+    // Temporary architecture-proof passthrough hook from the GPU bring-up.
+    // Removed in the cleanup pass before v0.1 ships.
     ProcessorProvider.addProcessor("gpu-passthrough", GpuEffectFactory())
   }
 }

package/android/src/main/java/com/simiancraft/kaleidoscope/gpu/GpuEffectProcessor.kt

@@ -2,7 +2,7 @@
 // invokes process() per frame on the SurfaceTextureHelper's GL thread, so
 // every GL call is implicitly on the correct context.
 //
-// Commit 3 of PLAN.md: this version is a passthrough — sample the OES
+// Initial GPU bring-up: this version is a passthrough — sample the OES
 // camera texture and emit it as a 2D-backed VideoFrame, no other math.
 // Architecture proof for the OES -> shader -> TextureBufferImpl -> renderer
 // round-trip. Effect-specific math (blur, composite, image background) lands

package/android/src/main/java/com/simiancraft/kaleidoscope/gpu/Shaders.kt

@@ -15,15 +15,10 @@ internal object Shaders {
   //   1 -> (2,0) -> ( 1,-1), uv (1,0)
   //   2 -> (0,2) -> (-1, 1), uv (0,1)
   //   3 -> (2,2) -> ( 1, 1), uv (1,1)
-  const val PASSTHROUGH_VERT = """#version 300 es
-precision highp float;
-out vec2 vUv;
-void main() {
-  vec2 p = vec2(float((gl_VertexID & 1) << 1), float(gl_VertexID & 2));
-  vUv = p * 0.5;
-  gl_Position = vec4(p - 1.0, 0.0, 1.0);
-}
-"""
+  // Canonical source: shaders/passthrough.vert. Generated into
+  // ShadersGenerated by `bun run build:shaders`; delegated here so call sites
+  // keep using Shaders.PASSTHROUGH_VERT.
+  val PASSTHROUGH_VERT = ShadersGenerated.PASSTHROUGH_VERT
 
   // Sample the OES external camera texture and emit as 2D RGBA. The first
   // pass of every effect runs this so subsequent passes can use sampler2D.
@@ -56,24 +51,10 @@ void main() {
   // uAxis is (1/width, 0) for the horizontal pass and (0, 1/height) for the
   // vertical pass. uOffsets[0] is the center tap (zero); offsets are in
   // pixel units, so the shader multiplies by uAxis to convert to UV space.
-  const val BLUR_FRAG = """#version 300 es
-precision mediump float;
-uniform sampler2D uTex;
-uniform vec2 uAxis;
-uniform float uWeights[9];
-uniform float uOffsets[9];
-in highp vec2 vUv;
-out vec4 oColor;
-void main() {
-  vec4 color = texture(uTex, vUv) * uWeights[0];
-  for (int i = 1; i < 9; i++) {
-    vec2 off = uAxis * uOffsets[i];
-    color += texture(uTex, vUv + off) * uWeights[i];
-    color += texture(uTex, vUv - off) * uWeights[i];
-  }
-  oColor = color;
-}
-"""
+  // Canonical source: shaders/blur.frag. Generated into ShadersGenerated by
+  // `bun run build:shaders`; delegated here. BlurFactory computes the 9 weights
+  // and offsets from sigma on the CPU and uploads the arrays each program use.
+  val BLUR_FRAG = ShadersGenerated.BLUR_FRAG
 
   // Composite: mix(background, original, mask). One shader, byte-identical
   // to src/web/shaders.ts's COMPOSITE_FRAG_SRC.
@@ -102,28 +83,9 @@ void main() {
   // blurred copy. For background-image, the caller computes them to perform
   // a cover-fit center crop so an arbitrarily-shaped image fills the output
   // without distortion.
-  const val COMPOSITE_FRAG = """#version 300 es
-precision mediump float;
-uniform sampler2D uOriginal;
-uniform sampler2D uBackground;
-uniform sampler2D uMask;
-uniform vec2 uBgUvScale;
-uniform vec2 uBgUvOffset;
-uniform vec2 uMaskUvScale;
-uniform vec2 uMaskUvOffset;
-uniform float uMaskLo;
-uniform float uMaskHi;
-in highp vec2 vUv;
-out vec4 oColor;
-void main() {
-  vec2 maskUv = vUv * uMaskUvScale + uMaskUvOffset;
-  float raw = texture(uMask, maskUv).r;
-  float safeHi = max(uMaskHi, uMaskLo + 0.001);
-  float m = smoothstep(uMaskLo, safeHi, raw);
-  vec3 orig = texture(uOriginal, vUv).rgb;
-  vec2 bgUv = clamp(vUv * uBgUvScale + uBgUvOffset, 0.0, 1.0);
-  vec3 bg = texture(uBackground, bgUv).rgb;
-  oColor = vec4(mix(bg, orig, m), 1.0);
-}
-"""
+  // Canonical source: shaders/composite.frag. Generated into ShadersGenerated
+  // by `bun run build:shaders`; delegated here. The per-platform mask/bg
+  // orientation differences live in the uniforms the host sets (see above),
+  // not in the shader, so the same generated body serves every runtime.
+  val COMPOSITE_FRAG = ShadersGenerated.COMPOSITE_FRAG
 }

package/android/src/main/java/com/simiancraft/kaleidoscope/gpu/ShadersGenerated.kt

@@ -0,0 +1,64 @@
+// @generated by scripts/build-shaders.ts from shaders/. DO NOT EDIT.
+// Run `bun run build:shaders` to regenerate.
+//
+// Cross-runtime shared shaders. Platform-local shaders (OES external texture,
+// 2D passthrough) stay hand-written in Shaders.kt, which delegates the consts
+// below.
+
+package com.simiancraft.kaleidoscope.gpu
+
+internal object ShadersGenerated {
+  const val PASSTHROUGH_VERT = """#version 300 es
+precision highp float;
+out highp vec2 vUv;
+void main() {
+  vec2 p = vec2(float((gl_VertexID & 1) << 1), float(gl_VertexID & 2));
+  vUv = p * 0.5;
+  gl_Position = vec4(p - 1.0, 0.0, 1.0);
+}
+"""
+
+  const val COMPOSITE_FRAG = """#version 300 es
+precision mediump float;
+uniform sampler2D uOriginal;
+uniform sampler2D uBackground;
+uniform sampler2D uMask;
+uniform vec2 uBgUvScale;
+uniform vec2 uBgUvOffset;
+uniform vec2 uMaskUvScale;
+uniform vec2 uMaskUvOffset;
+uniform float uMaskLo;
+uniform float uMaskHi;
+in highp vec2 vUv;
+out vec4 oColor;
+void main() {
+  vec2 maskUv = vUv * uMaskUvScale + uMaskUvOffset;
+  float raw = texture(uMask, maskUv).r;
+  float safeHi = max(uMaskHi, uMaskLo + 0.001);
+  float m = smoothstep(uMaskLo, safeHi, raw);
+  vec3 orig = texture(uOriginal, vUv).rgb;
+  vec2 bgUv = clamp(vUv * uBgUvScale + uBgUvOffset, 0.0, 1.0);
+  vec3 bg = texture(uBackground, bgUv).rgb;
+  oColor = vec4(mix(bg, orig, m), 1.0);
+}
+"""
+
+  const val BLUR_FRAG = """#version 300 es
+precision mediump float;
+uniform sampler2D uTex;
+uniform vec2 uAxis;
+uniform float uWeights[9];
+uniform float uOffsets[9];
+in highp vec2 vUv;
+out vec4 oColor;
+void main() {
+  vec4 color = texture(uTex, vUv) * uWeights[0];
+  for (int i = 1; i < 9; i++) {
+    vec2 off = uAxis * uOffsets[i];
+    color += texture(uTex, vUv + off) * uWeights[i];
+    color += texture(uTex, vUv - off) * uWeights[i];
+  }
+  oColor = color;
+}
+"""
+}

package/app.plugin.js

@@ -1,5 +1,255 @@
-// Expo config plugin entry. Compiled output lives in plugin/build/.
-// See plugin/src/withKaleidoscope.ts for the plugin implementation.
-import withKaleidoscope from './plugin/build/withKaleidoscope.js';
+// Expo config plugin. Native registration happens via the Expo Module's
+// OnCreate hook (see android/.../KaleidoscopeModule.kt and
+// ios/.../KaleidoscopeModule.swift), not through a plugin-time mod.
+//
+// This plugin's job is narrowly scoped: patch the consumer's iOS build to
+// satisfy this library's hard requirements that cannot be expressed in the
+// Expo Module manifest or the podspec alone. Today that means two patches,
+// both installed by a single iOS `dangerous` mod:
+//
+//   1. Declare `pod 'react-native-webrtc', :modular_headers => true` in the
+//      generated Podfile so Swift sources can `import react_native_webrtc`
+//      (see modular-headers detail below).
+//   2. Raise `ios.deploymentTarget` in `Podfile.properties.json` to the value
+//      required by `ios/Kaleidoscope.podspec`. The default Expo Podfile
+//      platform (iOS 13.4) is lower than this library's minimum (iOS 15.0
+//      for Apple Vision person segmentation), and `expo-modules-autolinking`
+//      silently drops pods whose declared minimum exceeds the Podfile
+//      platform — the library would build, install, and then be absent from
+//      the generated `ExpoModulesProvider.swift` at runtime.
+//
+// Bounding invariant for future patches in this mod:
+//   Every patch this mod installs must be (a) idempotent across re-prebuilds,
+//   (b) non-downgrading (never reduce a value the consumer or another plugin
+//   set higher), and (c) recoverable via a logged manual instruction on I/O
+//   failure (no throwing — prebuild must keep going).
+//
+// Ordering note: this mod must run AFTER any consumer plugin that writes the
+// same files (notably `expo-build-properties`). Expo executes plugins in
+// declaration order from `plugins[]`, so consumers must list this plugin
+// AFTER `expo-build-properties` in their `app.config.js`. The demo's
+// `app.config.js` already does so.
+//
+// Modular-headers detail: our Swift sources do `import react_native_webrtc`
+// to reach the Obj-C `ProcessorProvider` class and `VideoFrameProcessorDelegate`
+// protocol that live inside the react-native-webrtc pod. For a Swift target to
+// `import` an Objective-C CocoaPod as a Clang module, that pod must be built with
+// modular headers. react-native-webrtc is NOT built with modular headers by
+// default in a React Native / Expo app, so a default prebuild produces Swift
+// that fails to compile with "no such module 'react_native_webrtc'".
+//
+// We deliberately do NOT emit a global `use_modular_headers!`: that flips every
+// pod to build as a Clang module, which regularly breaks React Native core
+// pods that ship non-modular umbrella headers. A single per-pod opt-in is the
+// narrow, supported fix that react-native-webrtc's own docs recommend.
+//
+// WHY this file requires nothing but Node builtins (no @expo/config-plugins):
+// Expo's plugin resolver hardcodes the entry filename to `app.plugin.js` and
+// loads it with `require()` from the file's REAL path. In the demo we consume
+// this library via `file:..`, so on EAS the realpath is the repo root, where
+// there is no node_modules (EAS only installs the demo subdirectory). A
+// top-level `require('@expo/config-plugins')` therefore throws
+// "Cannot find module '@expo/config-plugins'" on the EAS worker. Registering
+// the dangerous mod by mutating `config.mods.ios.dangerous` directly removes
+// that dependency, so the plugin loads identically from the symlinked demo, a
+// normally-installed external consumer, and the EAS worker. The mod contract is
+// the one @expo/config-plugins' own dangerous base provider calls: it invokes
+// our mod as `nextMod({ ...config, modResults, modRequest })` and only requires
+// the returned value to be the config object (it asserts `.mods` exists).
+//
+// This file is CommonJS, and the package is deliberately `type: commonjs`:
+// Expo's plugin resolver loads app.plugin.js with `require()`, and a CommonJS
+// entry sidesteps ESM-interop variance across the Node versions EAS workers run
+// (older SDK images run Node 18, which cannot `require()` an ESM module at all;
+// newer images run Node 20/22). The ESM-authored library source lives in `src/`
+// and is consumed by Metro via the `react-native` export condition, never
+// loaded by Node.
 
-export default withKaleidoscope;
+const fs = require('node:fs');
+const path = require('node:path');
+
+// A sentinel comment lets us find our own injection on re-prebuilds and stay
+// idempotent regardless of how Expo regenerates the surrounding Podfile.
+const SENTINEL = '# react-native-webrtc-kaleidoscope: modular headers (managed)';
+
+// Mirrors ios/Kaleidoscope.podspec :ios => '15.0'. Bumping the podspec
+// requires bumping this constant; the drift cost is a silent pod-install
+// drop (the bug this plan fixes).
+const IOS_DEPLOYMENT_TARGET = '15.0';
+
+// Compare two dotted version strings element-wise. Returns true iff `existing`
+// is strictly less than `target`. Missing/empty existing counts as "less than".
+// We avoid `semver` so this file stays dependency-free for EAS workers that
+// don't install the library's node_modules. The library's iOS deployment
+// target is a plain three-part version like '15.0' (or '15.0.1' if Apple ever
+// requires it); pre-release/build metadata is not part of the contract.
+function isVersionLessThan(existing, target) {
+  if (typeof existing !== 'string' || existing.length === 0) {
+    return true;
+  }
+  const toParts = (s) => s.split('.').map((part) => Number(part) || 0);
+  const a = toParts(existing);
+  const b = toParts(target);
+  const max = Math.max(a.length, b.length);
+  for (let i = 0; i < max; i += 1) {
+    const av = a[i] || 0;
+    const bv = b[i] || 0;
+    if (av < bv) return true;
+    if (av > bv) return false;
+  }
+  return false; // equal
+}
+
+// Resolve which react-native-webrtc fork the consumer installed, and return its
+// CocoaPods pod name + npm package directory (used to build the `:path` for
+// the Podfile declaration). Two forks ship the same JS/native surface under
+// different names (mirrors the dual probe in android/build.gradle):
+//   - @livekit/react-native-webrtc -> pod `livekit-react-native-webrtc`
+//   - react-native-webrtc          -> pod `react-native-webrtc`
+// We prefer the fork when both are present, matching the Swift import order
+// (`#if canImport(livekit_react_native_webrtc)` first). Declaring a pod for a
+// package that is not installed would break `pod install`, so we return null
+// (and skip patching) when neither is found.
+function resolveWebrtcPod(projectRoot) {
+  if (!projectRoot) {
+    return { podName: 'react-native-webrtc', packageDir: 'react-native-webrtc' };
+  }
+  const fork = path.join(projectRoot, 'node_modules', '@livekit', 'react-native-webrtc');
+  const upstream = path.join(projectRoot, 'node_modules', 'react-native-webrtc');
+  if (fs.existsSync(fork)) {
+    return { podName: 'livekit-react-native-webrtc', packageDir: '@livekit/react-native-webrtc' };
+  }
+  if (fs.existsSync(upstream)) {
+    return { podName: 'react-native-webrtc', packageDir: 'react-native-webrtc' };
+  }
+  return null;
+}
+
+// Ensure the Podfile builds the resolved react-native-webrtc pod with modular
+// headers so our Swift can `import` it as a Clang module. Declare with an
+// explicit `:path` (instead of a bare `pod 'name'`) so the build works even
+// when RN autolinking does not register the pod for us — e.g. react-native-webrtc's
+// own `react-native.config.js` only sets `module.exports` under
+// `--use-react-native-macos`, and on EAS workers `use_native_modules!` has been
+// observed to skip the pod entirely as a result. With `:path` provided here,
+// CocoaPods resolves the local podspec directly; when autolinking also picks
+// it up, the two identical-path declarations are merged and modular_headers
+// is applied. Idempotent: running prebuild twice neither duplicates the line
+// nor corrupts the Podfile.
+function patchPodfile(contents, pod) {
+  if (contents.includes(SENTINEL)) {
+    return contents;
+  }
+
+  const block = `${SENTINEL}\n  pod '${pod.podName}', :path => '../node_modules/${pod.packageDir}', :modular_headers => true`;
+  const lines = contents.split('\n');
+
+  // Insert just inside the first `target ... do` block so the per-pod
+  // declaration sits in the same scope as the autolinked React Native pods.
+  const targetIndex = lines.findIndex((line) => /^\s*target\s+['"].*['"]\s+do\b/.test(line));
+  if (targetIndex !== -1) {
+    lines.splice(targetIndex + 1, 0, block);
+    return lines.join('\n');
+  }
+
+  // No `target` block found (unexpected for an Expo-generated Podfile); append
+  // the declaration so the build requirement is at least present.
+  return `${contents.trimEnd()}\n${block}\n`;
+}
+
+const withKaleidoscope = (config) => {
+  if (!config.mods) {
+    config.mods = {};
+  }
+  if (!config.mods.ios) {
+    config.mods.ios = {};
+  }
+
+  // Chain any previously registered iOS dangerous mod so we cooperate with
+  // other plugins instead of clobbering them.
+  const previousMod = config.mods.ios.dangerous;
+
+  config.mods.ios.dangerous = async (modConfig) => {
+    const result = typeof previousMod === 'function' ? await previousMod(modConfig) : modConfig;
+    const modRequest = result.modRequest || {};
+    const platformProjectRoot = modRequest.platformProjectRoot;
+    const pod = resolveWebrtcPod(modRequest.projectRoot);
+    if (platformProjectRoot && pod) {
+      const podfilePath = path.join(platformProjectRoot, 'Podfile');
+      try {
+        const original = fs.readFileSync(podfilePath, 'utf8');
+        const patched = patchPodfile(original, pod);
+        if (patched !== original) {
+          fs.writeFileSync(podfilePath, patched);
+        }
+      } catch (error) {
+        // Non-fatal: surface a clear instruction rather than failing prebuild.
+        const manualLine = `pod '${pod.podName}', :path => '../node_modules/${pod.packageDir}', :modular_headers => true`;
+        console.warn(
+          `[react-native-webrtc-kaleidoscope] Could not patch the Podfile to build ${pod.podName} with modular headers; add "${manualLine}" inside your app target manually. ${String(error)}`,
+        );
+      }
+    }
+    if (platformProjectRoot) {
+      // Raise the consumer's iOS deployment target via Podfile.properties.json.
+      // The generated Podfile reads `podfile_properties['ios.deploymentTarget']`
+      // at the top, so this is the canonical, no-Podfile-edit override seam.
+      // `expo-modules-autolinking`'s package-filter silently drops any pod
+      // whose declared minimum platform exceeds the Podfile platform; without
+      // this bump the Kaleidoscope pod is dropped and the runtime module
+      // lookup throws.
+      const propsPath = path.join(platformProjectRoot, 'Podfile.properties.json');
+      try {
+        let parsed = {};
+        try {
+          const raw = fs.readFileSync(propsPath, 'utf8');
+          try {
+            const candidate = JSON.parse(raw);
+            if (candidate && typeof candidate === 'object' && !Array.isArray(candidate)) {
+              parsed = candidate;
+            }
+          } catch (jsonError) {
+            // Corrupt JSON: warn but proceed with `{}` so the build still gets
+            // the bump it needs. The next prebuild will fully regenerate the
+            // file anyway.
+            console.warn(
+              `[react-native-webrtc-kaleidoscope] Could not parse ${propsPath}; rewriting with defaults. ${String(jsonError)}`,
+            );
+            parsed = {};
+          }
+        } catch (readError) {
+          if (readError && readError.code === 'ENOENT') {
+            parsed = {};
+          } else {
+            // Transient I/O failure (EACCES, EMFILE, ...). Don't clobber the
+            // file when we couldn't actually read it; warn and bail.
+            console.warn(
+              `[react-native-webrtc-kaleidoscope] Could not read ${propsPath}; skipping iOS deployment-target bump. ${String(readError)}`,
+            );
+            return result;
+          }
+        }
+        // Explicit own-key copy into a fresh object to foreclose
+        // `__proto__`-as-literal-key surprises from JSON.parse.
+        const next = {};
+        for (const key of Object.keys(parsed)) {
+          next[key] = parsed[key];
+        }
+        const existing = next['ios.deploymentTarget'];
+        if (isVersionLessThan(existing, IOS_DEPLOYMENT_TARGET)) {
+          next['ios.deploymentTarget'] = IOS_DEPLOYMENT_TARGET;
+        }
+        fs.writeFileSync(propsPath, `${JSON.stringify(next, null, 2)}\n`);
+      } catch (error) {
+        console.warn(
+          `[react-native-webrtc-kaleidoscope] Could not patch ${propsPath} to raise iOS deployment target; add "ios.deploymentTarget": "${IOS_DEPLOYMENT_TARGET}" to Podfile.properties.json under your demo/ios directory manually. ${String(error)}`,
+        );
+      }
+    }
+    return result;
+  };
+
+  return config;
+};
+
+module.exports = withKaleidoscope;

package/dist/backgrounds/index.d.ts

@@ -0,0 +1,3 @@
+export type { BackgroundPresetName } from './presets';
+export { BACKGROUND_PRESETS } from './presets';
+//# sourceMappingURL=index.d.ts.map

package/dist/backgrounds/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/backgrounds/index.ts"],"names":[],"mappings":"AAKA,YAAY,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC","sourcesContent":["// Barrel for the backgrounds feature: the platform-agnostic preset catalog.\n// Preset *sources* are not re-exported here; import them per preset so each\n// pulls only its own WebP, e.g.\n// `import { office1 } from 'react-native-webrtc-kaleidoscope/backgrounds/office-1'`.\n\nexport type { BackgroundPresetName } from './presets';\nexport { BACKGROUND_PRESETS } from './presets';\n"]}

package/dist/backgrounds/index.js

@@ -0,0 +1,6 @@
+// Barrel for the backgrounds feature: the platform-agnostic preset catalog.
+// Preset *sources* are not re-exported here; import them per preset so each
+// pulls only its own WebP, e.g.
+// `import { office1 } from 'react-native-webrtc-kaleidoscope/backgrounds/office-1'`.
+export { BACKGROUND_PRESETS } from './presets';
+//# sourceMappingURL=index.js.map

package/dist/backgrounds/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/backgrounds/index.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,4EAA4E;AAC5E,gCAAgC;AAChC,qFAAqF;AAGrF,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC","sourcesContent":["// Barrel for the backgrounds feature: the platform-agnostic preset catalog.\n// Preset *sources* are not re-exported here; import them per preset so each\n// pulls only its own WebP, e.g.\n// `import { office1 } from 'react-native-webrtc-kaleidoscope/backgrounds/office-1'`.\n\nexport type { BackgroundPresetName } from './presets';\nexport { BACKGROUND_PRESETS } from './presets';\n"]}

package/dist/backgrounds/office-1.d.ts

@@ -0,0 +1,3 @@
+import type { PresetSource } from './preset-source.types';
+export declare const office1: PresetSource;
+//# sourceMappingURL=office-1.d.ts.map

package/dist/backgrounds/office-1.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"office-1.d.ts","sourceRoot":"","sources":["../../src/backgrounds/office-1.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAK1D,eAAO,MAAM,OAAO,EAAE,YAAyB,CAAC","sourcesContent":["import type { PresetSource } from './preset-source.types';\n\n// Native variant. The native module loads its own bundled resource by name, so\n// the source is just the preset name; no WebP import, no expo-asset on native.\n// Web is handled by office-1.web.ts.\nexport const office1: PresetSource = 'office-1';\n"]}

package/dist/backgrounds/office-1.js

@@ -0,0 +1,5 @@
+// Native variant. The native module loads its own bundled resource by name, so
+// the source is just the preset name; no WebP import, no expo-asset on native.
+// Web is handled by office-1.web.ts.
+export const office1 = 'office-1';
+//# sourceMappingURL=office-1.js.map

package/dist/backgrounds/office-1.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"office-1.js","sourceRoot":"","sources":["../../src/backgrounds/office-1.ts"],"names":[],"mappings":"AAEA,+EAA+E;AAC/E,+EAA+E;AAC/E,qCAAqC;AACrC,MAAM,CAAC,MAAM,OAAO,GAAiB,UAAU,CAAC","sourcesContent":["import type { PresetSource } from './preset-source.types';\n\n// Native variant. The native module loads its own bundled resource by name, so\n// the source is just the preset name; no WebP import, no expo-asset on native.\n// Web is handled by office-1.web.ts.\nexport const office1: PresetSource = 'office-1';\n"]}

package/dist/backgrounds/office-1.web.d.ts

@@ -0,0 +1,3 @@
+import type { PresetSource } from './preset-source.types';
+export declare const office1: PresetSource;
+//# sourceMappingURL=office-1.web.d.ts.map

package/dist/backgrounds/office-1.web.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"office-1.web.d.ts","sourceRoot":"","sources":["../../src/backgrounds/office-1.web.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAK1D,eAAO,MAAM,OAAO,EAAE,YAAiD,CAAC","sourcesContent":["/// <reference path=\"./assets.d.ts\" />\nimport { Asset } from 'expo-asset';\nimport office1Asset from './office-1.webp';\nimport type { PresetSource } from './preset-source.types';\n\n// Web variant. The bundled WebP's URL, which the background-image effect\n// fetches. Resolved with expo-asset because react-native-web has no\n// Image.resolveAssetSource; `.uri` is set synchronously by fromModule.\nexport const office1: PresetSource = Asset.fromModule(office1Asset).uri;\n"]}

package/dist/backgrounds/office-1.web.js

@@ -0,0 +1,8 @@
+/// <reference path="./assets.d.ts" />
+import { Asset } from 'expo-asset';
+import office1Asset from './office-1.webp';
+// Web variant. The bundled WebP's URL, which the background-image effect
+// fetches. Resolved with expo-asset because react-native-web has no
+// Image.resolveAssetSource; `.uri` is set synchronously by fromModule.
+export const office1 = Asset.fromModule(office1Asset).uri;
+//# sourceMappingURL=office-1.web.js.map

package/dist/backgrounds/office-1.web.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"office-1.web.js","sourceRoot":"","sources":["../../src/backgrounds/office-1.web.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,YAAY,MAAM,iBAAiB,CAAC;AAG3C,yEAAyE;AACzE,oEAAoE;AACpE,uEAAuE;AACvE,MAAM,CAAC,MAAM,OAAO,GAAiB,KAAK,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC,GAAG,CAAC","sourcesContent":["/// <reference path=\"./assets.d.ts\" />\nimport { Asset } from 'expo-asset';\nimport office1Asset from './office-1.webp';\nimport type { PresetSource } from './preset-source.types';\n\n// Web variant. The bundled WebP's URL, which the background-image effect\n// fetches. Resolved with expo-asset because react-native-web has no\n// Image.resolveAssetSource; `.uri` is set synchronously by fromModule.\nexport const office1: PresetSource = Asset.fromModule(office1Asset).uri;\n"]}

package/dist/backgrounds/office-2.d.ts

@@ -0,0 +1,3 @@
+import type { PresetSource } from './preset-source.types';
+export declare const office2: PresetSource;
+//# sourceMappingURL=office-2.d.ts.map

package/dist/backgrounds/office-2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"office-2.d.ts","sourceRoot":"","sources":["../../src/backgrounds/office-2.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAK1D,eAAO,MAAM,OAAO,EAAE,YAAyB,CAAC","sourcesContent":["import type { PresetSource } from './preset-source.types';\n\n// Native variant. The native module loads its own bundled resource by name, so\n// the source is just the preset name; no WebP import, no expo-asset on native.\n// Web is handled by office-2.web.ts.\nexport const office2: PresetSource = 'office-2';\n"]}

package/dist/backgrounds/office-2.js

@@ -0,0 +1,5 @@
+// Native variant. The native module loads its own bundled resource by name, so
+// the source is just the preset name; no WebP import, no expo-asset on native.
+// Web is handled by office-2.web.ts.
+export const office2 = 'office-2';
+//# sourceMappingURL=office-2.js.map

package/dist/backgrounds/office-2.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"office-2.js","sourceRoot":"","sources":["../../src/backgrounds/office-2.ts"],"names":[],"mappings":"AAEA,+EAA+E;AAC/E,+EAA+E;AAC/E,qCAAqC;AACrC,MAAM,CAAC,MAAM,OAAO,GAAiB,UAAU,CAAC","sourcesContent":["import type { PresetSource } from './preset-source.types';\n\n// Native variant. The native module loads its own bundled resource by name, so\n// the source is just the preset name; no WebP import, no expo-asset on native.\n// Web is handled by office-2.web.ts.\nexport const office2: PresetSource = 'office-2';\n"]}

package/dist/backgrounds/office-2.web.d.ts

@@ -0,0 +1,3 @@
+import type { PresetSource } from './preset-source.types';
+export declare const office2: PresetSource;
+//# sourceMappingURL=office-2.web.d.ts.map

package/dist/backgrounds/office-2.web.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"office-2.web.d.ts","sourceRoot":"","sources":["../../src/backgrounds/office-2.web.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAK1D,eAAO,MAAM,OAAO,EAAE,YAAiD,CAAC","sourcesContent":["/// <reference path=\"./assets.d.ts\" />\nimport { Asset } from 'expo-asset';\nimport office2Asset from './office-2.webp';\nimport type { PresetSource } from './preset-source.types';\n\n// Web variant. The bundled WebP's URL, which the background-image effect\n// fetches. Resolved with expo-asset because react-native-web has no\n// Image.resolveAssetSource; `.uri` is set synchronously by fromModule.\nexport const office2: PresetSource = Asset.fromModule(office2Asset).uri;\n"]}

package/dist/backgrounds/office-2.web.js

@@ -0,0 +1,8 @@
+/// <reference path="./assets.d.ts" />
+import { Asset } from 'expo-asset';
+import office2Asset from './office-2.webp';
+// Web variant. The bundled WebP's URL, which the background-image effect
+// fetches. Resolved with expo-asset because react-native-web has no
+// Image.resolveAssetSource; `.uri` is set synchronously by fromModule.
+export const office2 = Asset.fromModule(office2Asset).uri;
+//# sourceMappingURL=office-2.web.js.map

package/dist/backgrounds/office-2.web.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"office-2.web.js","sourceRoot":"","sources":["../../src/backgrounds/office-2.web.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,YAAY,MAAM,iBAAiB,CAAC;AAG3C,yEAAyE;AACzE,oEAAoE;AACpE,uEAAuE;AACvE,MAAM,CAAC,MAAM,OAAO,GAAiB,KAAK,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC,GAAG,CAAC","sourcesContent":["/// <reference path=\"./assets.d.ts\" />\nimport { Asset } from 'expo-asset';\nimport office2Asset from './office-2.webp';\nimport type { PresetSource } from './preset-source.types';\n\n// Web variant. The bundled WebP's URL, which the background-image effect\n// fetches. Resolved with expo-asset because react-native-web has no\n// Image.resolveAssetSource; `.uri` is set synchronously by fromModule.\nexport const office2: PresetSource = Asset.fromModule(office2Asset).uri;\n"]}