react-native-effects 0.1.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-effects",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "WebGPU-powered visual effects running on a background thread in React Native",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",
@@ -65,45 +65,46 @@
     "registry": "https://registry.npmjs.org/"
   },
   "devDependencies": {
-    "@commitlint/config-conventional": "^19.8.1",
-    "@eslint/compat": "^1.3.2",
-    "@eslint/eslintrc": "^3.3.1",
-    "@eslint/js": "^9.35.0",
-    "@react-native/babel-preset": "0.83.1",
-    "@react-native/eslint-config": "0.83.1",
-    "@release-it/conventional-changelog": "^10.0.1",
+    "@commitlint/config-conventional": "^21.0.2",
+    "@eslint/compat": "^2.1.0",
+    "@eslint/eslintrc": "^3.3.5",
+    "@eslint/js": "^9.39.4",
+    "@react-native/babel-preset": "0.85.3",
+    "@react-native/eslint-config": "0.85.3",
+    "@react-native/jest-preset": "0.85.3",
+    "@release-it/conventional-changelog": "^11.0.1",
     "@types/jest": "^29.5.14",
-    "@types/react": "^19.1.12",
-    "@webgpu/types": "0.1.69",
-    "commitlint": "^19.8.1",
-    "del-cli": "^6.0.0",
-    "eslint": "^9.35.0",
+    "@types/react": "^19.2.17",
+    "@webgpu/types": "0.1.70",
+    "commitlint": "^21.0.2",
+    "del-cli": "^7.0.0",
+    "eslint": "^9.39.4",
     "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-prettier": "^5.5.4",
+    "eslint-plugin-prettier": "^5.5.6",
     "jest": "^29.7.0",
-    "lefthook": "^2.0.3",
-    "prettier": "^2.8.8",
-    "react": "19.2.0",
-    "react-native": "0.83.1",
-    "react-native-builder-bob": "^0.40.18",
-    "react-native-gesture-handler": "2.30.0",
-    "react-native-reanimated": "4.3.0-rc.0",
-    "react-native-wgpu": "0.5.6",
-    "react-native-worklets": "0.8.0-rc.0",
-    "release-it": "^19.0.4",
-    "turbo": "^2.5.6",
-    "typescript": "^5.9.2"
+    "lefthook": "^2.1.9",
+    "prettier": "^3.8.3",
+    "react": "19.2.3",
+    "react-native": "0.85.3",
+    "react-native-builder-bob": "^0.41.0",
+    "react-native-gesture-handler": "2.31.1",
+    "react-native-reanimated": "4.3.1",
+    "react-native-webgpu": "0.5.15",
+    "react-native-worklets": "0.8.3",
+    "release-it": "^20.2.0",
+    "turbo": "^2.9.16",
+    "typescript": "^6.0.3"
   },
   "peerDependencies": {
     "react": "*",
     "react-native": "*",
     "react-native-gesture-handler": ">=2.0.0",
-    "react-native-wgpu": ">=0.5.0",
+    "react-native-webgpu": ">=0.5.0",
     "react-native-worklets": ">=0.8.0"
   },
   "resolutions": {
-    "metro": "patch:metro@npm%3A0.83.3#./.yarn/patches/metro-npm-0.83.3-d09f48ca84.patch",
-    "metro-runtime": "patch:metro-runtime@npm%3A0.83.3#./.yarn/patches/metro-runtime-npm-0.83.3-c614bbd3b9.patch"
+    "metro": "patch:metro@npm%3A0.84.4#./.yarn/patches/metro-npm-0.84.4.patch",
+    "metro-runtime": "patch:metro-runtime@npm%3A0.84.4#./.yarn/patches/metro-runtime-npm-0.84.4.patch"
   },
   "workspaces": [
     "example"
@@ -135,7 +136,7 @@
     "useTabs": false
   },
   "jest": {
-    "preset": "react-native",
+    "preset": "@react-native/jest-preset",
     "modulePathIgnorePatterns": [
       "<rootDir>/example/node_modules",
       "<rootDir>/lib/"

package/src/components/ShaderView/index.tsx

@@ -1,6 +1,6 @@
-import { PixelRatio, StyleSheet } from 'react-native';
-import { Canvas } from 'react-native-wgpu';
-import { useEffect, useRef } from 'react';
+import { AppState, PixelRatio, StyleSheet } from 'react-native';
+import { Canvas, installWebGPU } from 'react-native-webgpu';
+import { useEffect, useRef, useState } from 'react';
 import { createSynchronizable, scheduleOnRuntime } from 'react-native-worklets';
 import { colorToVec4 } from '../../utils/colors';
 import { useWGPUSetup } from '../../hooks/useWGPUSetup';
@@ -24,10 +24,27 @@ export default function ShaderView({
   speed = 1.0,
   params = [],
   isStatic = false,
+  transparent = false,
+  paramsSynchronizable,
   style,
   ...viewProps
 }: ShaderViewProps) {
-  const { canvasRef, runtime, resources } = useWGPUSetup();
+  const { canvasRef, runtime, resources, onCanvasLayout } = useWGPUSetup();
+
+  // Pause the render loop while the app is backgrounded. The rAF loop otherwise
+  // keeps churning frames against a surface that's offscreen (and often
+  // transiently invalid), wasting battery/GPU. We only pause on a true
+  // 'background' transition — iOS 'inactive' (app switcher peek, notification
+  // pulldown) is left running to avoid flicker on brief, foreground interruptions.
+  const [appActive, setAppActive] = useState(
+    () => (AppState.currentState ?? 'active') !== 'background'
+  );
+  useEffect(() => {
+    const subscription = AppState.addEventListener('change', (state) => {
+      setAppActive(state !== 'background');
+    });
+    return () => subscription.remove();
+  }, []);
 
   const propsSync = useRef(
     createSynchronizable<Float64Array>(new Float64Array(SYNC_SIZE))
@@ -79,18 +96,33 @@ export default function ShaderView({
     };
   }, [propsSync]);
 
-  // Start render loop when GPU resources are ready
+  // Start render loop when GPU resources are ready and the app is foregrounded.
+  // When the app backgrounds, `appActive` flips false and this effect's cleanup
+  // tears the loop down (via the `cancelled` token below); on return to the
+  // foreground it re-runs and starts a fresh loop.
   useEffect(() => {
-    if (!resources) {
+    if (!resources || !appActive) {
       return;
     }
 
     const { device, context, presentationFormat } = resources;
     const dpr = PixelRatio.get();
 
+    // Per-run cancellation token. On Fast Refresh / dep change / unmount, React
+    // runs this effect's cleanup, which flips the flag and stops *this* loop —
+    // otherwise the old worklet RAF loop keeps running forever alongside the new
+    // one, stacking a duplicate render loop on every Metro reload.
+    const cancelled = createSynchronizable<Float64Array>(new Float64Array(1));
+
     scheduleOnRuntime(runtime, () => {
       'worklet';
 
+      // Worklet runtimes start without the WebGPU flag constants
+      // (GPUBufferUsage, GPUTextureUsage, ...). installWebGPU() captures them
+      // into this runtime so they're available below. Idempotent / safe no-op
+      // if already installed.
+      installWebGPU();
+
       // Create pipeline once
       const pipeline = device.createRenderPipeline({
         layout: 'auto',
@@ -120,10 +152,38 @@ export default function ShaderView({
       const uniformData = new Float32Array(UNIFORM_FLOAT_COUNT);
       let accumulatedTime = 0;
       let lastTimestamp = 0;
+      let warned = false;
+      let bufferDestroyed = false;
+
+      // Free this loop's uniform buffer when the loop ends (alive=0 / superseded
+      // by Fast Refresh / unmount). On a fragmentShader change the effect
+      // re-runs and schedules a fresh loop with a new buffer while the device
+      // persists, so without this the old buffer leaks every shader swap.
+      function destroyBuffer() {
+        if (bufferDestroyed) {
+          return;
+        }
+        bufferDestroyed = true;
+        try {
+          uniformBuffer.destroy();
+        } catch {
+          // The device may already have been destroyed on unmount — the buffer
+          // is gone either way, so there's nothing to recover.
+          return;
+        }
+      }
 
       function render(timestamp: number) {
         const props = propsSync.getDirty();
         if (props[IDX_ALIVE] === 0) {
+          destroyBuffer();
+          return;
+        }
+
+        // This loop was superseded (Fast Refresh / unmount) — bail without
+        // scheduling another frame so it can be garbage-collected.
+        if (cancelled.getDirty()[0] === 1) {
+          destroyBuffer();
           return;
         }
 
@@ -144,7 +204,7 @@ export default function ShaderView({
         const height = canvas.height || 1;
         const aspect = width / height;
 
-        // Fill uniform data (6 × vec4 = 24 floats)
+        // Fill uniform data (7 × vec4 = 28 floats)
         // resolution: vec4<f32>
         uniformData[0] = width;
         uniformData[1] = height;
@@ -175,35 +235,61 @@ export default function ShaderView({
         uniformData[18] = props[IDX_PARAMS + 2]!;
         uniformData[19] = props[IDX_PARAMS + 3]!;
 
-        // params1: vec4<f32>
+        // params1: vec4<f32> — static params[4..7]
         uniformData[20] = props[IDX_PARAMS + 4]!;
         uniformData[21] = props[IDX_PARAMS + 5]!;
         uniformData[22] = props[IDX_PARAMS + 6]!;
         uniformData[23] = props[IDX_PARAMS + 7]!;
 
-        device.queue.writeBuffer(uniformBuffer, 0, uniformData);
-
-        const commandEncoder = device.createCommandEncoder();
-        const textureView = context.getCurrentTexture().createView();
-        const passEncoder = commandEncoder.beginRenderPass({
-          colorAttachments: [
-            {
-              view: textureView,
-              clearValue: [0, 0, 0, 1],
-              loadOp: 'clear',
-              storeOp: 'store',
-            },
-          ],
-        });
-
-        passEncoder.setPipeline(pipeline);
-        passEncoder.setBindGroup(0, bindGroup);
-        passEncoder.draw(3);
-        passEncoder.end();
-
-        device.queue.submit([commandEncoder.finish()]);
-        context.present();
+        // live: vec4<f32> — off-thread input (touch/scroll/audio) from
+        // paramsSynchronizable, written into its own slot so it never collides
+        // with the static params. Stays (0,0,0,0) when no channel is attached.
+        if (paramsSynchronizable) {
+          const live = paramsSynchronizable.getDirty();
+          uniformData[24] = live[0]!;
+          uniformData[25] = live[1]!;
+          uniformData[26] = live[2]!;
+          uniformData[27] = live[3]!;
+        }
 
+        // GPU work can throw when the surface is transiently invalid — the app
+        // backgrounded, the view detached, or the device was lost. Swallow the
+        // failed frame so the loop survives and recovers when the surface comes
+        // back (rather than the worklet crashing or the loop dying silently).
+        try {
+          device.queue.writeBuffer(uniformBuffer, 0, uniformData);
+
+          const commandEncoder = device.createCommandEncoder();
+          const textureView = context.getCurrentTexture().createView();
+          const passEncoder = commandEncoder.beginRenderPass({
+            colorAttachments: [
+              {
+                view: textureView,
+                clearValue: transparent ? [0, 0, 0, 0] : [0, 0, 0, 1],
+                loadOp: 'clear',
+                storeOp: 'store',
+              },
+            ],
+          });
+
+          passEncoder.setPipeline(pipeline);
+          passEncoder.setBindGroup(0, bindGroup);
+          passEncoder.draw(3);
+          passEncoder.end();
+
+          device.queue.submit([commandEncoder.finish()]);
+          context.present();
+        } catch (e) {
+          // Warn once to avoid spamming the console every frame on a persistent
+          // failure (e.g. a lost device).
+          if (!warned) {
+            warned = true;
+            console.warn('[react-native-effects] render frame failed:', e);
+          }
+        }
+
+        // Always reschedule animated loops, even after a caught failure, so the
+        // effect self-heals once the surface is valid again.
         if (!isStatic) {
           requestAnimationFrame(render);
         }
@@ -211,10 +297,32 @@ export default function ShaderView({
 
       requestAnimationFrame(render);
     });
-  }, [resources, runtime, propsSync, fragmentShader, isStatic]);
+
+    return () => {
+      cancelled.setBlocking(() => Float64Array.of(1));
+    };
+  }, [
+    resources,
+    appActive,
+    runtime,
+    propsSync,
+    paramsSynchronizable,
+    fragmentShader,
+    isStatic,
+    transparent,
+  ]);
 
   return (
-    <Canvas ref={canvasRef} style={[styles.canvas, style]} {...viewProps} />
+    <Canvas
+      ref={canvasRef}
+      transparent={transparent}
+      style={[styles.canvas, style]}
+      {...viewProps}
+      onLayout={(event) => {
+        onCanvasLayout(event);
+        viewProps.onLayout?.(event);
+      }}
+    />
   );
 }
 

package/src/components/ShaderView/types.ts

@@ -1,6 +1,19 @@
 import type { ViewProps } from 'react-native';
+import type { Synchronizable } from 'react-native-worklets';
 import type { ColorInput } from '../../utils/colors';
 
+/**
+ * A 4-float synchronizable whose values are written into the dedicated `u.live`
+ * uniform slot every frame. It has its own slot, so it never collides with the
+ * 8 static `params` (`u.params0`/`u.params1`).
+ *
+ * This is the bridge for live, per-frame input (touch position, scroll
+ * progress, velocity) coming from the JS thread into the off-thread render
+ * loop. Create one with `useParamsSynchronizable` and update it from
+ * gesture/scroll handlers. See `ShaderViewWithPanGesture`.
+ */
+export type ParamsSynchronizable = Synchronizable<Float64Array>;
+
 export type ShaderViewProps = ViewProps & {
   /** WGSL fragment shader source (must declare the Uniforms struct) */
   fragmentShader: string;
@@ -12,4 +25,12 @@ export type ShaderViewProps = ViewProps & {
   params?: number[];
   /** Render once then stop the RAF loop. Default: false */
   isStatic?: boolean;
+  /** Use transparent background (clear to alpha 0). Default: false */
+  transparent?: boolean;
+  /**
+   * Optional live input. Its 4 floats are written into the dedicated `u.live`
+   * slot every frame — independent of the static `params`. Use for
+   * touch/scroll/audio. Create it with `useParamsSynchronizable`.
+   */
+  paramsSynchronizable?: ParamsSynchronizable;
 };

package/src/components/ShaderViewWithPanGesture/index.tsx

@@ -0,0 +1,225 @@
+import { useCallback, useRef } from 'react';
+import { StyleSheet, View, type LayoutChangeEvent } from 'react-native';
+import { Gesture, GestureDetector } from 'react-native-gesture-handler';
+import {
+  createSynchronizable,
+  type Synchronizable,
+} from 'react-native-worklets';
+import ShaderView from '../ShaderView';
+import { useParamsSynchronizable } from '../../hooks/useParamsSynchronizable';
+import type { ShaderViewProps } from '../ShaderView/types';
+
+/**
+ * A {@link ShaderView} that feeds touch input into the shader's `u.live`:
+ *
+ *   - `live.x` → pointer X, normalized 0..1 (left → right)
+ *   - `live.y` → pointer Y, normalized 0..1 (bottom → top, matching UV space)
+ *   - `live.z` → 1.0 while touching, 0.0 when released
+ *   - `live.w` → 0.0 (reserved)
+ *
+ * Dragging moves the pointer **relatively** — it pushes from where the pointer
+ * already is rather than jumping under the finger — and a fling lets it glide to
+ * a stop. The position is **remembered**: it stays wherever it ended and is
+ * never reset; only the "touched" flag (`live.z`) toggles on release. A
+ * shader can read `live.xy` as a stable resting position and use `live.z`
+ * purely for touch-driven emphasis, so the effect never snaps back.
+ *
+ * The resting value before the first touch is `[0, 0, 0, 0]` by default; pass
+ * `initialParamsSynchronizable` to seed it — e.g. `[0.5, 0.5, 0, 0]` to start a
+ * pointer at screen center.
+ *
+ * The drag runs as a **worklet on the UI thread** and writes the synchronizable
+ * directly, so pointer updates never hop to the JS thread — matching the rest of
+ * the library, which renders off the JS thread. The render runtime reads the
+ * same synchronizable each frame.
+ */
+export type ShaderViewWithPanGestureProps = Omit<
+  ShaderViewProps,
+  'paramsSynchronizable'
+> & {
+  /**
+   * Initial value for the gesture channel (`u.live`) before the first touch.
+   * Defaults to `[0, 0, 0, 0]`. Use e.g. `[0.5, 0.5, 0, 0]` to rest a pointer at
+   * screen center.
+   */
+  initialParamsSynchronizable?: readonly [number, number, number, number];
+};
+
+export default function ShaderViewWithPanGesture({
+  style,
+  initialParamsSynchronizable = [0, 0, 0, 0],
+  ...props
+}: ShaderViewWithPanGestureProps) {
+  const { paramsSynchronizable } = useParamsSynchronizable(
+    initialParamsSynchronizable
+  );
+
+  // View size, read inside the gesture worklets to normalize pointer coords.
+  const sizeRef = useRef<Synchronizable<Float64Array> | null>(null);
+  if (sizeRef.current === null) {
+    sizeRef.current = createSynchronizable<Float64Array>(Float64Array.of(1, 1));
+  }
+  const sizeSynchronizable = sizeRef.current;
+
+  // Generation of the current post-release glide; bumped to cancel an old one.
+  const momentumRef = useRef<Synchronizable<Float64Array> | null>(null);
+  if (momentumRef.current === null) {
+    momentumRef.current = createSynchronizable<Float64Array>(
+      Float64Array.of(0)
+    );
+  }
+  const momentumSynchronizable = momentumRef.current;
+
+  // Pointer position when the current drag began — the pan moves the pointer
+  // relative to this, so a drag pushes from where it was rather than jumping.
+  const panStartRef = useRef<Synchronizable<Float64Array> | null>(null);
+  if (panStartRef.current === null) {
+    panStartRef.current = createSynchronizable<Float64Array>(
+      Float64Array.of(0, 0)
+    );
+  }
+  const panStartSynchronizable = panStartRef.current;
+
+  const onLayout = useCallback(
+    (e: LayoutChangeEvent) => {
+      const { width, height } = e.nativeEvent.layout;
+      sizeSynchronizable.setBlocking(() =>
+        Float64Array.of(width || 1, height || 1)
+      );
+    },
+    [sizeSynchronizable]
+  );
+
+  // Worklet: runs on the UI thread and writes the normalized pointer straight
+  // into the synchronizable the render runtime reads, so a pointer move never
+  // touches the JS thread.
+  const writePointer = (nx: number, ny: number, active: number) => {
+    'worklet';
+    const x = Math.min(1, Math.max(0, nx));
+    const y = Math.min(1, Math.max(0, ny));
+    paramsSynchronizable.setBlocking(() => Float64Array.of(x, y, active, 0));
+  };
+
+  const stopMomentum = () => {
+    'worklet';
+    const next = (momentumSynchronizable.getDirty()[0] || 0) + 1;
+    momentumSynchronizable.setBlocking(() => Float64Array.of(next));
+  };
+
+  // Drop the touched flag in place — safety net for a gesture cancelled with no
+  // onEnd, so the flag never sticks.
+  const releaseFlag = () => {
+    'worklet';
+    const p = paramsSynchronizable.getDirty();
+    const x = p[0] || 0;
+    const y = p[1] || 0;
+    paramsSynchronizable.setBlocking(() => Float64Array.of(x, y, 0, 0));
+  };
+
+  // After release, drift from the last position along the fling velocity and
+  // decay to a stop — a little inertia. Runs on the UI thread via rAF, like the
+  // render loop, writing each frame into the same synchronizable.
+  const startMomentum = (velX: number, velY: number) => {
+    'worklet';
+    const s = sizeSynchronizable.getDirty();
+    const w = s[0] || 1;
+    const h = s[1] || 1;
+
+    // Flick speed in normalized units/sec, scaled to a subtle glide (Y flipped).
+    const SCALE = 0.12;
+    let vx = (velX / w) * SCALE;
+    let vy = (-velY / h) * SCALE;
+
+    const p = paramsSynchronizable.getDirty();
+    let x = p[0] || 0;
+    let y = p[1] || 0;
+
+    // Claim this glide; a newer one bumps the generation and this loop bails.
+    const gen = (momentumSynchronizable.getDirty()[0] || 0) + 1;
+    momentumSynchronizable.setBlocking(() => Float64Array.of(gen));
+
+    const FRICTION = 2; // 1/s — higher stops sooner
+    let last = -1;
+
+    // Plain closure (no 'worklet') so its accumulators and self-reference
+    // survive across frames; a serialized worklet would snapshot them by value.
+    const step = (now: number) => {
+      if ((momentumSynchronizable.getDirty()[0] || 0) !== gen) {
+        return;
+      }
+      const dt = last < 0 ? 0 : (now - last) / 1000;
+      last = now;
+
+      x = Math.min(1, Math.max(0, x + vx * dt));
+      y = Math.min(1, Math.max(0, y + vy * dt));
+      const decay = Math.exp(-FRICTION * dt);
+      vx = vx * decay;
+      vy = vy * decay;
+
+      paramsSynchronizable.setBlocking(() => Float64Array.of(x, y, 0, 0));
+
+      if (Math.abs(vx) + Math.abs(vy) > 0.0008) {
+        requestAnimationFrame(step);
+      }
+    };
+    requestAnimationFrame(step);
+  };
+
+  // Drag moves the pointer *relatively*: grab anywhere and push it from where it
+  // is, rather than snapping it under the finger. A plain tap leaves it put.
+  const pan = Gesture.Pan()
+    .onBegin(() => {
+      'worklet';
+      stopMomentum();
+      const p = paramsSynchronizable.getDirty();
+      const sx = p[0] || 0;
+      const sy = p[1] || 0;
+      panStartSynchronizable.setBlocking(() => Float64Array.of(sx, sy));
+      writePointer(sx, sy, 1);
+    })
+    .onUpdate((e) => {
+      'worklet';
+      const s = sizeSynchronizable.getDirty();
+      const w = s[0] || 1;
+      const h = s[1] || 1;
+      const start = panStartSynchronizable.getDirty();
+      // Add the drag delta; Y is flipped to match the shader's UV space.
+      writePointer(
+        (start[0] || 0) + e.translationX / w,
+        (start[1] || 0) - e.translationY / h,
+        1
+      );
+    })
+    .onEnd((e) => {
+      'worklet';
+      const p = paramsSynchronizable.getDirty();
+      writePointer(p[0] || 0, p[1] || 0, 0);
+      startMomentum(e.velocityX, e.velocityY);
+    })
+    .onFinalize(() => {
+      'worklet';
+      releaseFlag();
+    });
+
+  return (
+    <GestureDetector gesture={pan}>
+      <View
+        style={[styles.fill, style]}
+        onLayout={onLayout}
+        collapsable={false}
+      >
+        <ShaderView
+          {...props}
+          paramsSynchronizable={paramsSynchronizable}
+          style={StyleSheet.absoluteFill}
+        />
+      </View>
+    </GestureDetector>
+  );
+}
+
+const styles = StyleSheet.create({
+  fill: {
+    flex: 1,
+  },
+});

package/src/hooks/useParamsSynchronizable.ts

@@ -0,0 +1,52 @@
+import { useCallback, useRef } from 'react';
+import { createSynchronizable } from 'react-native-worklets';
+import type { ParamsSynchronizable } from '../components/ShaderView/types';
+
+/**
+ * Creates a {@link ParamsSynchronizable} — a 4-float channel written into the
+ * dedicated `u.live` slot of a {@link ShaderView} every frame. It has its own
+ * uniform slot, so it leaves all 8 static `params` untouched.
+ *
+ * The returned `setParamsSynchronizable` runs on the JS thread (call it from gesture or scroll
+ * handlers); the values are read by the off-thread render loop. By convention
+ * the four floats carry `(x, y, active, extra)` for pointer input, or
+ * `(progress, ...)` for scroll-driven effects — but the meaning is up to the
+ * shader consuming `u.live`.
+ *
+ * Pass `initial` to seed the channel's starting value (read once on first
+ * render), so the shader has a sane resting state before the first update —
+ * e.g. `[0.5, 0.5, 0, 0]` to start a pointer at screen center. Defaults to all
+ * zeros.
+ */
+export function useParamsSynchronizable(
+  initial: readonly [number, number, number, number] = [0, 0, 0, 0]
+): {
+  paramsSynchronizable: ParamsSynchronizable;
+  setParamsSynchronizable: (
+    x: number,
+    y: number,
+    active: number,
+    extra: number
+  ) => void;
+} {
+  // Lazily create once; `initial` is only a seed, so it is read on first render
+  // and ignored thereafter.
+  const ref = useRef<ParamsSynchronizable | null>(null);
+  if (ref.current === null) {
+    ref.current = createSynchronizable<Float64Array>(
+      Float64Array.of(initial[0], initial[1], initial[2], initial[3])
+    );
+  }
+  const paramsSynchronizable = ref.current;
+
+  const setParamsSynchronizable = useCallback(
+    (x: number, y: number, active: number, extra: number) => {
+      paramsSynchronizable.setBlocking(() =>
+        Float64Array.of(x, y, active, extra)
+      );
+    },
+    [paramsSynchronizable]
+  );
+
+  return { paramsSynchronizable, setParamsSynchronizable };
+}