@react-three/postprocessing 3.0.5 → 3.1.0

package/src/tests/createEffectComponent.test.tsx

@@ -0,0 +1,286 @@
+import { Effect, EffectComposer as EffectComposerImpl } from 'postprocessing'
+import * as React from 'react'
+import { Uniform } from 'three'
+import { describe, expect, it, vi } from 'vitest'
+import { createEffectComponent } from '../createEffectComponent'
+import { EffectComposer } from '../EffectComposer'
+import { flush, root } from './test-utils'
+
+// Zero-arity, real accessor - the class of effect createEffectComponent
+// targets. Matches BloomEffect's shape: `constructor({...} = {})`.
+class FakeEffect extends Effect {
+  private _value: number
+  constructor({ value = 0 }: { value?: number } = {}) {
+    super('FakeEffect', 'mainImage() {}')
+    this._value = value
+  }
+  get value() {
+    return this._value
+  }
+  set value(v: number) {
+    this._value = v
+  }
+}
+
+const FakeEffectComponent = /* @__PURE__ */ createEffectComponent<typeof FakeEffect, { value?: number }>(FakeEffect)
+
+// Options stored only in `uniforms` (mirrors WaterEffectImpl/RampEffect
+// before this branch gave them real accessors) - `factor` here HAS a real
+// accessor, proving that's what makes a plain JSX prop actually reach it.
+class UniformFixtureEffect extends Effect {
+  constructor({ factor = 0 }: { factor?: number } = {}) {
+    super('UniformFixtureEffect', 'mainImage() {}', { uniforms: new Map([['factor', new Uniform(factor)]]) })
+  }
+  get factor(): number {
+    return this.uniforms.get('factor')!.value
+  }
+  set factor(v: number) {
+    this.uniforms.get('factor')!.value = v
+  }
+}
+
+const UniformFixtureComponent = /* @__PURE__ */ createEffectComponent<typeof UniformFixtureEffect, { factor?: number }>(
+  UniformFixtureEffect
+)
+
+describe('createEffectComponent', () => {
+  it('constructs the effect and passes props through to the instance', async () => {
+    const composerRef = React.createRef<EffectComposerImpl>()
+
+    await React.act(async () =>
+      root.render(
+        <EffectComposer ref={composerRef}>
+          <FakeEffectComponent value={42} />
+        </EffectComposer>
+      )
+    )
+
+    await flush()
+
+    // @ts-expect-error - `effects` isn't part of the public Pass typing
+    const effect = composerRef.current!.passes[1].effects[0]
+
+    expect(effect).toBeInstanceOf(FakeEffect)
+    expect(effect.value).toBe(42)
+
+    await React.act(async () => root.render(null))
+  })
+
+  it('applies a live prop without reconstructing the instance (r3f-native, no args change)', async () => {
+    const composerRef = React.createRef<EffectComposerImpl>()
+    const ref = React.createRef<FakeEffect>()
+
+    const render = (value: number) =>
+      root.render(
+        <EffectComposer ref={composerRef}>
+          <FakeEffectComponent ref={ref} value={value} />
+        </EffectComposer>
+      )
+
+    await React.act(async () => render(1))
+    await flush()
+    const first = ref.current
+    expect(first!.value).toBe(1)
+
+    await React.act(async () => render(2))
+    await flush()
+
+    expect(ref.current).toBe(first)
+    expect(ref.current!.value).toBe(2)
+
+    await React.act(async () => root.render(null))
+  })
+
+  it('resets a live prop to its constructor default when removed (r3f-native diffProps)', async () => {
+    const composerRef = React.createRef<EffectComposerImpl>()
+    const ref = React.createRef<FakeEffect>()
+
+    await React.act(async () =>
+      root.render(
+        <EffectComposer ref={composerRef}>
+          <FakeEffectComponent ref={ref} value={5} />
+        </EffectComposer>
+      )
+    )
+    await flush()
+    expect(ref.current!.value).toBe(5)
+
+    await React.act(async () =>
+      root.render(
+        <EffectComposer ref={composerRef}>
+          <FakeEffectComponent ref={ref} />
+        </EffectComposer>
+      )
+    )
+    await flush()
+
+    expect(ref.current!.value).toBe(0)
+
+    await React.act(async () => root.render(null))
+  })
+
+  it('reconstructs when an explicit args prop changes, same as any other r3f element', async () => {
+    const composerRef = React.createRef<EffectComposerImpl>()
+    const ref = React.createRef<FakeEffect>()
+
+    const render = (value: number) =>
+      root.render(
+        <EffectComposer ref={composerRef}>
+          <FakeEffectComponent ref={ref} args={[{ value }]} />
+        </EffectComposer>
+      )
+
+    await React.act(async () => render(1))
+    await flush()
+    const first = ref.current
+    expect(first!.value).toBe(1)
+
+    await React.act(async () => render(2))
+    await flush()
+
+    expect(ref.current).not.toBe(first)
+    expect(ref.current!.value).toBe(2)
+
+    await React.act(async () => root.render(null))
+  })
+
+  it('applies blendFunction/opacity through blendMode, not as a stray top-level property', async () => {
+    const composerRef = React.createRef<EffectComposerImpl>()
+    const ref = React.createRef<FakeEffect>()
+
+    await React.act(async () =>
+      root.render(
+        <EffectComposer ref={composerRef}>
+          <FakeEffectComponent ref={ref} blendFunction={7 as never} opacity={0.5} />
+        </EffectComposer>
+      )
+    )
+    await flush()
+
+    expect(ref.current!.blendMode.blendFunction).toBe(7)
+    expect(ref.current!.blendMode.opacity.value).toBe(0.5)
+    expect((ref.current as unknown as { blendFunction?: unknown }).blendFunction).toBeUndefined()
+
+    await React.act(async () => root.render(null))
+  })
+
+  it('resets blendFunction/opacity to blendMode\'s own defaults when the props are removed', async () => {
+    const composerRef = React.createRef<EffectComposerImpl>()
+    const ref = React.createRef<FakeEffect>()
+
+    await React.act(async () =>
+      root.render(
+        <EffectComposer ref={composerRef}>
+          <FakeEffectComponent ref={ref} />
+        </EffectComposer>
+      )
+    )
+    await flush()
+    const defaultBlendFunction = ref.current!.blendMode.blendFunction
+    const defaultOpacity = ref.current!.blendMode.opacity.value
+
+    await React.act(async () =>
+      root.render(
+        <EffectComposer ref={composerRef}>
+          <FakeEffectComponent ref={ref} blendFunction={7 as never} opacity={0.5} />
+        </EffectComposer>
+      )
+    )
+    await flush()
+    expect(ref.current!.blendMode.blendFunction).toBe(7)
+    expect(ref.current!.blendMode.opacity.value).toBe(0.5)
+
+    await React.act(async () =>
+      root.render(
+        <EffectComposer ref={composerRef}>
+          <FakeEffectComponent ref={ref} />
+        </EffectComposer>
+      )
+    )
+    await flush()
+
+    expect(ref.current!.blendMode.blendFunction).toBe(defaultBlendFunction)
+    expect(ref.current!.blendMode.opacity.value).toBe(defaultOpacity)
+
+    await React.act(async () => root.render(null))
+  })
+
+  it('updates a uniforms-Map-backed prop live via its accessor, without reconstructing', async () => {
+    const composerRef = React.createRef<EffectComposerImpl>()
+    const ref = React.createRef<UniformFixtureEffect>()
+
+    const render = (factor: number) =>
+      root.render(
+        <EffectComposer ref={composerRef}>
+          <UniformFixtureComponent ref={ref} factor={factor} />
+        </EffectComposer>
+      )
+
+    await React.act(async () => render(1))
+    await flush()
+    const first = ref.current
+    expect(first!.uniforms.get('factor')!.value).toBe(1)
+
+    await React.act(async () => render(2))
+    await flush()
+
+    expect(ref.current).toBe(first)
+    expect(ref.current!.uniforms.get('factor')!.value).toBe(2)
+
+    await React.act(async () => root.render(null))
+  })
+
+  it('disposes the instance on unmount', async () => {
+    const disposeSpy = vi.spyOn(FakeEffect.prototype, 'dispose')
+    const composerRef = React.createRef<EffectComposerImpl>()
+
+    try {
+      await React.act(async () =>
+        root.render(
+          <EffectComposer ref={composerRef}>
+            <FakeEffectComponent value={1} />
+          </EffectComposer>
+        )
+      )
+      await flush()
+
+      await React.act(async () => root.render(null))
+
+      expect(disposeSpy).toHaveBeenCalledTimes(1)
+    } finally {
+      disposeSpy.mockRestore()
+    }
+  })
+
+  it('forwards a callback ref\'s own returned cleanup (React 19 ref cleanup), instead of dropping it', async () => {
+    const composerRef = React.createRef<EffectComposerImpl>()
+    const events: string[] = []
+    const cleanup = vi.fn(() => {
+      events.push('cleanup')
+    })
+    const callbackRef = vi.fn((instance: FakeEffect | null) => {
+      events.push(instance ? 'attach' : 'attach-null')
+      if (instance) return cleanup
+    })
+
+    await React.act(async () =>
+      root.render(
+        <EffectComposer ref={composerRef}>
+          <FakeEffectComponent ref={callbackRef} value={1} />
+        </EffectComposer>
+      )
+    )
+    await flush()
+
+    expect(callbackRef).toHaveBeenCalledTimes(1)
+    expect(cleanup).not.toHaveBeenCalled()
+
+    await React.act(async () => root.render(null))
+
+    // React 19 ref-cleanup semantics: once a cleanup is returned, it's
+    // called directly - the callback itself is never re-invoked with null.
+    expect(cleanup).toHaveBeenCalledTimes(1)
+    expect(callbackRef).toHaveBeenCalledTimes(1)
+    expect(events).toEqual(['attach', 'cleanup'])
+  })
+})

package/src/tests/effects.smoke.test.tsx

@@ -10,8 +10,8 @@
 // effects still need manual/visual verification before release.
 //
 // Coverage is enforced by the last test in this file: every *.tsx file in
-// src/effects must appear either in SMOKE_CASES or EXCLUDED below. Adding a
-// new effect file without touching either list fails CI.
+// src/effects or src/passes must appear either in SMOKE_CASES or EXCLUDED
+// below. Adding a new effect/pass file without touching either list fails CI.
 //
 // This file is excluded from `tsc -p tsconfig.json` (it matches
 // src/**/*.test.*), so editors fall back to a detached/inferred compilation
@@ -23,7 +23,7 @@
 import fs from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { CopyPass, DepthPickingPass, EffectComposer as EffectComposerImpl } from 'postprocessing'
+import { DepthPickingPass as DepthPickingPassImpl, EffectComposer as EffectComposerImpl } from 'postprocessing'
 import * as React from 'react'
 import * as THREE from 'three'
 import { describe, expect, it, vi } from 'vitest'
@@ -44,7 +44,6 @@ import { Grid } from '../effects/Grid'
 import { HueSaturation } from '../effects/HueSaturation'
 import { LensFlare } from '../effects/LensFlare'
 import { LUT } from '../effects/LUT'
-import { N8AO } from '../effects/N8AO'
 import { Noise } from '../effects/Noise'
 import { Outline } from '../effects/Outline'
 import { Pixelation } from '../effects/Pixelation'
@@ -60,16 +59,18 @@ import { TiltShift2 } from '../effects/TiltShift2'
 import { ToneMapping } from '../effects/ToneMapping'
 import { Vignette } from '../effects/Vignette'
 import { WaterEffect } from '../effects/Water'
+import { DepthPicking } from '../passes/DepthPicking'
+import { N8AO } from '../passes/N8AO'
 import { flush, root } from './test-utils'
 
 type SmokeCase = {
-  /** Filename under src/effects this case covers — drives the coverage check below. */
+  /** Filename under src/effects or src/passes this case covers — drives the coverage check below. */
   file: string
   label: string
   composerProps?: Record<string, unknown>
   /** Extra scene content the effect needs (e.g. a sun mesh for GodRays). */
   extras?: React.ReactNode
-  /** Renders the effect element. `ref` may be ignored by effects that don't forward one (e.g. LensFlare). */
+  /** Renders the effect element. */
   effect: (ref: React.Ref<any>) => React.ReactElement
 }
 
@@ -85,6 +86,7 @@ const SMOKE_CASES: SmokeCase[] = [
   { file: 'ColorDepth.tsx', label: 'ColorDepth', effect: (ref) => <ColorDepth ref={ref} /> },
   { file: 'Depth.tsx', label: 'Depth', effect: (ref) => <Depth ref={ref} /> },
   { file: 'DepthOfField.tsx', label: 'DepthOfField', effect: (ref) => <DepthOfField ref={ref} /> },
+  { file: 'DepthPicking.tsx', label: 'DepthPicking', effect: (ref) => <DepthPicking ref={ref} /> },
   { file: 'DotScreen.tsx', label: 'DotScreen', effect: (ref) => <DotScreen ref={ref} /> },
   { file: 'FXAA.tsx', label: 'FXAA', effect: (ref) => <FXAA ref={ref} /> },
   { file: 'Glitch.tsx', label: 'Glitch', effect: (ref) => <Glitch ref={ref} /> },
@@ -96,8 +98,7 @@ const SMOKE_CASES: SmokeCase[] = [
   },
   { file: 'Grid.tsx', label: 'Grid', effect: (ref) => <Grid ref={ref} /> },
   { file: 'HueSaturation.tsx', label: 'HueSaturation', effect: (ref) => <HueSaturation ref={ref} /> },
-  // LensFlare manages its own internal ref and doesn't accept one as a prop.
-  { file: 'LensFlare.tsx', label: 'LensFlare', effect: () => <LensFlare /> },
+  { file: 'LensFlare.tsx', label: 'LensFlare', effect: (ref) => <LensFlare ref={ref} /> },
   { file: 'LUT.tsx', label: 'LUT', effect: (ref) => <LUT ref={ref} lut={lutTexture} /> },
   { file: 'N8AO.tsx', label: 'N8AO', effect: (ref) => <N8AO ref={ref} /> },
   { file: 'Noise.tsx', label: 'Noise', effect: (ref) => <Noise ref={ref} /> },
@@ -165,32 +166,12 @@ describe('effect smoke tests', () => {
     }
   })
 
-  // Tracks dispose() calls per instance rather than per class — EffectComposerImpl
-  // constructs its own internal CopyPass (this.copyPass, for compositing) and
-  // disposes it as part of its own teardown, unrelated to any CopyPass an effect
-  // constructs. A class-wide spy would conflate the two into a false "double
-  // dispose"; this only flags it if the *same* instance is disposed twice.
-  function trackDisposePerInstance(Ctor: { prototype: { dispose: (...args: unknown[]) => unknown } }) {
-    const counts = new Map<object, number>()
-    const original = Ctor.prototype.dispose
-    const spy = vi.spyOn(Ctor.prototype, 'dispose').mockImplementation(function (this: object, ...args: unknown[]) {
-      counts.set(this, (counts.get(this) ?? 0) + 1)
-      return original.apply(this, args)
-    })
-    return {
-      restore: () => spy.mockRestore(),
-      maxCallsForAnySingleInstance: () => Math.max(0, ...counts.values()),
-    }
-  }
-
-  // Autofocus's ref resolves to { dofRef, hitpoint, update } (its own
-  // imperative API), not an effect instance — the generic dispose check
-  // above silently no-ops for it. It actually owns three disposables
-  // (depthPickingPass, copyPass, and the DepthOfField effect it renders
-  // internally), verified explicitly here instead.
-  it('Autofocus disposes depthPickingPass, copyPass, and the nested DepthOfField effect exactly once each', async () => {
-    const depthPickingTracker = trackDisposePerInstance(DepthPickingPass)
-    const copyPassTracker = trackDisposePerInstance(CopyPass)
+  // Autofocus's ref resolves to { dofRef, hitpoint, update }, not an effect
+  // instance - the generic dispose check above no-ops for it. It owns two
+  // disposables (the nested DepthPicking component's pass, and the
+  // nested DepthOfField effect), verified here.
+  it('Autofocus disposes the nested DepthPicking and DepthOfField effect', async () => {
+    const depthPickingDisposeSpy = vi.spyOn(DepthPickingPassImpl.prototype, 'dispose')
     // AutofocusProps' `ref` type is broken (ComponentProps<typeof DepthOfField>
     // drags in DepthOfField's own `ref: Ref<DepthOfFieldEffect>`, which then
     // intersects with `Ref<AutofocusApi>` — separate pre-existing issue,
@@ -214,17 +195,40 @@ describe('effect smoke tests', () => {
     await React.act(async () => root.render(null))
     await flush()
 
-    expect(depthPickingTracker.maxCallsForAnySingleInstance()).toBeLessThanOrEqual(1)
-    expect(copyPassTracker.maxCallsForAnySingleInstance()).toBeLessThanOrEqual(1)
-    expect(dofDisposeSpy).toHaveBeenCalledTimes(1)
+    expect(depthPickingDisposeSpy).toHaveBeenCalled()
+    expect(dofDisposeSpy).toHaveBeenCalled()
+
+    depthPickingDisposeSpy.mockRestore()
+  })
+
+  it('DepthPicking disposes its pass on unmount', async () => {
+    const disposeSpy = vi.spyOn(DepthPickingPassImpl.prototype, 'dispose')
+    const ref = React.createRef<import('../passes/DepthPicking').DepthPickingApi>()
+
+    await React.act(async () =>
+      root.render(
+        <EffectComposer>
+          <DepthPicking ref={ref} />
+        </EffectComposer>
+      )
+    )
+
+    await flush()
+    expect(ref.current).toBeTruthy()
+
+    await React.act(async () => root.render(null))
+    await flush()
+
+    expect(disposeSpy).toHaveBeenCalled()
 
-    depthPickingTracker.restore()
-    copyPassTracker.restore()
+    disposeSpy.mockRestore()
   })
 
-  it('covers every file in src/effects (or documents why it is excluded)', () => {
-    const effectsDir = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'effects')
-    const files = fs.readdirSync(effectsDir).filter((f) => f.endsWith('.tsx'))
+  it('covers every file in src/effects and src/passes (or documents why it is excluded)', () => {
+    const srcDir = path.join(path.dirname(fileURLToPath(import.meta.url)), '..')
+    const files = ['effects', 'passes'].flatMap((dir) =>
+      fs.readdirSync(path.join(srcDir, dir)).filter((f) => f.endsWith('.tsx'))
+    )
 
     const covered = new Set(SMOKE_CASES.map((c) => c.file))
     const missing = files.filter((f) => !covered.has(f) && !(f in EXCLUDED))

package/src/util.tsx

@@ -1,7 +1,7 @@
-import { useThree, type ReactThreeFiber } from '@react-three/fiber'
+import { useThree, type Instance, type ReactThreeFiber } from '@react-three/fiber'
 import type { Selection as PPSelection } from 'postprocessing'
-import { use, useEffect, useMemo, useRef, type RefObject } from 'react'
-import { Object3D, Vector2, type Vector2Tuple } from 'three'
+import { use, useCallback, useEffect, useLayoutEffect, useMemo, useRef, type Ref, type RefObject } from 'react'
+import { Group, Object3D, Vector2, Vector3, type Vector2Tuple, type Vector3Tuple } from 'three'
 import { selectionContext } from './Selection'
 
 // Stable reference for array-typed props defaulting to "nothing" - `= []`
@@ -12,13 +12,49 @@ export const EMPTY_ARRAY: never[] = []
 export const resolveRef = <T,>(ref: T | RefObject<T>) =>
   typeof ref === 'object' && ref != null && 'current' in ref ? ref.current : ref
 
-/**
- * Keeps a postprocessing effect's `selection` (and its render layer) in
- * sync with either mode effects support: the manual
- * `selection` prop (used only when there's no enclosing <Selection>), or
- * the declarative Selection/Select API. The two are mutually exclusive -
- * context wins when both are present.
- */
+// Merges a local ref with a caller-supplied ref (object or callback form).
+// Clears localRef inside the callback ref's own returned cleanup, since
+// React 19 never re-invokes it with null once it returns one.
+export function useMergeRefs<T>(
+  localRef: RefObject<T | null>,
+  outerRef: Ref<T> | undefined
+): (instance: T | null) => void | (() => void) {
+  return useCallback(
+    (instance: T | null) => {
+      localRef.current = instance
+      if (typeof outerRef !== 'function') {
+        if (outerRef) outerRef.current = instance
+        return
+      }
+      const cleanup = outerRef(instance)
+      if (typeof cleanup !== 'function') return
+      return () => {
+        localRef.current = null
+        cleanup()
+      }
+    },
+    [localRef, outerRef]
+  )
+}
+
+// Reads a <group>'s direct r3f children, filtered by type - transparent to
+// non-host wrapper components, since r3f's instance tree already is.
+export function readGroupChildren<T>(group: Group, filter: (object: unknown) => object is T): T[] {
+  const groupInstance = (group as Group & { __r3f: Instance<Group> }).__r3f
+  return groupInstance ? groupInstance.children.map((child) => child.object).filter(filter) : []
+}
+
+// Diffs `next` against what's stored in `ref`, updating it only when the
+// contents actually changed. Returns whether it changed.
+export function updateIfChanged<T>(ref: RefObject<T[]>, next: T[]): boolean {
+  const previous = ref.current
+  if (next.length === previous.length && next.every((item, i) => item === previous[i])) return false
+  ref.current = next
+  return true
+}
+
+// Keeps `selection` synced with whichever mode is active: the manual
+// `selection` prop, or the declarative Selection/Select API (context wins).
 export function useSelectionSync(
   effect: { selection: PPSelection },
   selection: Object3D | Object3D[] | RefObject<Object3D | null> | RefObject<Object3D | null>[],
@@ -59,26 +95,91 @@ export function useSelectionSync(
   }, [api, effect.selection, invalidate])
 }
 
-/**
- * r3f never disposes <primitive> objects (their state may be owned outside
- * React), so effects rendered that way must dispose themselves. Guards
- * against double-dispose across StrictMode's dev-only mount/cleanup/mount
- * cycle, where the cleanup closure re-runs against the same instance.
- */
+// r3f never disposes <primitive> objects, so they must dispose themselves.
 export const useDispose = <T extends { dispose?: () => void }>(instance: T): void => {
-  const disposedRef = useRef<WeakSet<object>>(new WeakSet())
-
   useEffect(() => {
-    const disposed = disposedRef.current
     return () => {
-      if (instance && typeof instance === 'object' && !disposed.has(instance)) {
-        disposed.add(instance)
-        instance.dispose?.()
-      }
+      instance?.dispose?.()
     }
   }, [instance])
 }
 
+// Reads a plain or r3f-pierced ("a-b-c") key off an object, matching what
+// applyProps below can write - a single reader that works for both shapes.
+export function readPierced(instance: object, key: string): unknown {
+  let target: unknown = instance
+  for (const part of key.split('-')) {
+    if (target == null) return undefined
+    target = (target as Record<string, unknown>)[part]
+  }
+  return target
+}
+
+// Writes a plain or r3f-pierced ("a-b-c") key, mirroring readPierced.
+// Deliberately a plain assignment, not r3f's applyProps: these instances
+// are built with `new`, not r3f's reconciler, so applyProps' Color/Vector
+// coercion never applies to them. Callers wrap values that need coercion.
+export function applyPierced(instance: object, key: string, value: unknown): void {
+  const parts = key.split('-')
+  let target: unknown = instance
+  for (let idx = 0; idx < parts.length - 1; idx++) {
+    if (target == null) return
+    target = (target as Record<string, unknown>)[parts[idx]]
+  }
+  if (target == null) return
+  ;(target as Record<string, unknown>)[parts[parts.length - 1]] = value
+}
+
+// Applies live-mutable properties onto an instance built via `new` (not
+// r3f's reconciler, so r3f's own prop diffing/reset never runs on it).
+// Falls back to the constructor-time default when a value is `undefined`.
+// Only calls `set` when the resolved value actually changed since the last
+// apply - some setters have side effects beyond storing the value (e.g.
+// OutlineEffect's `multisampling` disposes its render target on every set).
+export function useLiveDefaults<T extends object>(
+  instance: T | RefObject<T | null> | null,
+  values: Record<string, unknown>,
+  keys: Iterable<string>,
+  get: (instance: T, key: string) => unknown = readPierced,
+  set: (instance: T, key: string, value: unknown) => void = applyPierced
+): void {
+  const snapshotRef = useRef<{ instance: T; defaults: Map<string, unknown>; applied: Map<string, unknown> } | null>(
+    null
+  )
+  const invalidate = useThree((state) => state.invalidate)
+
+  useLayoutEffect(() => {
+    const resolved = resolveRef(instance)
+    if (!resolved) return
+    if (snapshotRef.current?.instance !== resolved) {
+      snapshotRef.current = { instance: resolved, defaults: new Map(), applied: new Map() }
+    }
+    const { defaults, applied } = snapshotRef.current
+    let changed = false
+
+    for (const key of keys) {
+      if (!defaults.has(key)) {
+        // Seed `applied` too, not just `defaults`, so an unchanged key
+        // skips `set` even on this first pass (avoids re-triggering
+        // setters with side effects, e.g. multisampling's dispose).
+        const current = get(resolved, key)
+        defaults.set(key, current)
+        applied.set(key, current)
+      }
+      const next = values[key] !== undefined ? values[key] : defaults.get(key)
+      if (Object.is(applied.get(key), next)) continue
+      set(resolved, key, next)
+      applied.set(key, next)
+      changed = true
+    }
+
+    // These instances are mutated directly (not via r3f's reconciler), so
+    // r3f never sees the change - without this, frameloop="demand" would
+    // never repaint after a live prop update.
+    if (changed) invalidate()
+  })
+}
+
 export const useVector2 = (props: Record<string, unknown>, key: string): Vector2 => {
   const value = props[key] as ReactThreeFiber.Vector2 | undefined
 
@@ -87,6 +188,10 @@ export const useVector2 = (props: Record<string, unknown>, key: string): Vector2
       return new Vector2(value, value)
     }
 
+    if (value instanceof Vector2) {
+      return value
+    }
+
     if (value) {
       return new Vector2(...(value as Vector2Tuple))
     }
@@ -94,3 +199,23 @@ export const useVector2 = (props: Record<string, unknown>, key: string): Vector2
     return new Vector2()
   }, [value])
 }
+
+export const useVector3 = (props: Record<string, unknown>, key: string): Vector3 => {
+  const value = props[key] as ReactThreeFiber.Vector3 | undefined
+
+  return useMemo(() => {
+    if (typeof value === 'number') {
+      return new Vector3(value, value, value)
+    }
+
+    if (value instanceof Vector3) {
+      return value
+    }
+
+    if (value) {
+      return new Vector3(...(value as Vector3Tuple))
+    }
+
+    return new Vector3()
+  }, [value])
+}

package/src/wrapEffect.tsx

@@ -1,8 +1,9 @@
 import { extend, useThree } from '@react-three/fiber'
-import type { BlendFunction, Effect, Pass } from 'postprocessing'
+import type { BlendFunction } from 'postprocessing'
 import { useMemo, type ExoticComponent, type JSX, type Ref } from 'react'
+import type { EffectConstructor } from './createEffectComponent'
 
-export type EffectConstructor = new (...args: any[]) => Effect | Pass
+export type { EffectConstructor }
 
 // Handles three ConstructorParameters<T> shapes: required first param
 // (P), optional first param (Partial<P> — some effects in postprocessing

package/dist/tests/test-utils.d.ts

@@ -1,12 +0,0 @@
-import { EffectComposer as EffectComposerImpl } from 'postprocessing';
-import * as React from 'react';
-declare global {
-    var IS_REACT_ACT_ENVIRONMENT: boolean;
-}
-export declare const root: import("@react-three/fiber").ReconcilerRoot<HTMLCanvasElement>;
-export declare const EFFECT_SHADER = "\nvoid mainImage(const in vec4 inputColor, const in vec2 uv, out vec4 outputColor) {\n  outputColor = inputColor;\n}\n";
-export declare const flush: () => Promise<void>;
-export declare const strict: (children: React.ReactNode) => React.JSX.Element;
-export declare const waitForComposer: (ref: React.RefObject<EffectComposerImpl | null>) => Promise<EffectComposerImpl>;
-export declare const waitForNewComposer: (ref: React.RefObject<EffectComposerImpl | null>, previous: EffectComposerImpl) => Promise<EffectComposerImpl>;
-export declare const waitForEffects: (ref: React.RefObject<EffectComposerImpl | null>, count: number) => Promise<import("postprocessing").Effect[]>;