Patch release - fixes broken N8AO output after a pixel ratio change (#280).

Fixed

• EffectComposer: changing only the pixel ratio (setDpr, <AdaptiveDpr>, dpr prop) didn't resize the composer and its passes. They now follow the drawing buffer size.

What's Changed

• fix(EffectComposer): resize the composer when the pixel ratio changes by @tonyblu331 in #381

New Contributors

• @tonyblu331 made their first contribution in #381

Full Changelog: v3.1.2...v3.1.3

Patch release - fixes a crash in mergeMode: "auto" when combining a UV-transforming effect (e.g. Glitch) with a convolution effect (e.g. ChromaticAberration).

Fixed

• EffectComposer: mergeMode: "auto" could merge a mainUv effect into the same pass as a convolution effect, which postprocessing itself doesn't allow - EffectPass throws at render time either way. 'auto' now keeps them apart the same way it already keeps two convolution effects apart.

What's Changed

• docs: add example links for ASCII and N8AO by @kvvasuu in #379
• fix: keep mainUv effects out of the same auto-merged pass as convolution effects by @kvvasuu in #380

Full Changelog: v3.1.1...v3.1.2

Patch release focused purely on compatibility - no behavior changes.
It loosens peerDependencies that were accidentally over-constrained in 3.1.0.

What's Changed

• fix: loosen peerDependencies for react and three by @kvvasuu in #378
• Build the docs with pmndrs/docs@v4 by @abernier in #375

Full Changelog: v3.1.0...v3.1.1

This release is an internal rewrite of how effects apply prop changes - most of it is invisible unless you hit one of the bugs it fixes, but it puts every effect on the same reliable, live-updating foundation instead of each one reconstructing itself in ad hoc ways.

Added

• EffectGroup: new component that groups effects into a single EffectPass with its own cheap enabled toggle, backed by a shared trailing CopyPass so disabling the last pass in a chain doesn't blank the canvas.
• DepthPicking, useDepthPicking: new component + hook for reading world-space positions off the depth buffer, extracted from <Autofocus> into a reusable, standalone primitive. <DepthPicking> just mounts the vanilla DepthPickingPass and exposes readDepth via ref - renders nothing, updates nothing automatically. useDepthPicking turns a screen position into a world-space point on demand, auto-detecting the composer's own camera when used inside its <EffectComposer>, with an explicit camera override for calling it from outside that tree. <Autofocus> is now built on both internally, same external behavior.
• EffectComposer: new autoRenderToScreen?: boolean prop (default true) - construction-time option, same treatment as depthBuffer/multisampling.
• EffectComposer: new renderPass?: (scene, camera) => Pass prop - lets consumers supply their own scene/camera render pass
• EffectComposer: new mergeMode?: 'auto' | 'all' | 'none' prop (default 'auto'). 'auto' merges effects into as few EffectPasses as possible while keeping at most one convolution effect per pass - matching what postprocessing itself actually allows. This is strictly better than the old unconditional "any convolution effect gets fully isolated" behavior. 'all' drops that safety limit entirely. 'none' gives every effect its own pass.
• createEffectComponent: the internal effect-wrapping factory is now part of the public API, for wrapping your own zero-arg-constructible postprocessing effect classes the same way this library's own simple effects do.
• N8AO: new enabled prop, wired into the same shared trailing-CopyPass safety net as EffectGroup (N8AO isn't a mergeable postprocessing Effect, so it needed its own toggle rather than going through EffectGroup directly).
• Grid, Glitch: opacity now works - these never went through wrapEffect (the only place that handled it) before, so it was silently inert regardless of what the (missing) types suggested.
• Outline, GodRays: warn in the console when mounted without <EffectComposer autoClear={false}> - both render an internal extra pass that silently produces wrong output (outlines don't render at all; GodRays occlusion looks wrong) without it.
• Outline: visibleEdgeColor/hiddenEdgeColor now typed as ColorRepresentation (number | string | Color) instead of just number - the runtime already wrapped values in new Color(value), so string colors ("red", "#ff0000", etc.) always worked, the type just didn't say so.
• LensFlare, ShockWave: lensPosition/position now accept ReactThreeFiber.Vector3 (a tuple or a single number, not just a Vector3 instance), matching how position props work everywhere else in the r3f ecosystem.

Changed

• Effects whose postprocessing class can be constructed with zero arguments are now built on createEffectComponent: live props update the existing effect instance in place instead of reconstructing it on every change, and a ref now points to one stable instance across prop updates instead of a new one every render.
• Effects that need real constructor args and can't use createEffectComponent similarly apply live props through useLiveDefaults instead of reconstructing the whole effect on every change.
• EffectComposer: pass rebuild lifecycle rewritten - passes are now only rebuilt when the resolved effect/pass list actually changed, not on every unrelated React render.
• SSAO: resolutionScale now falls back to the parent <EffectComposer>'s own resolutionScale prop when not set directly on <SSAO>, instead of always defaulting straight to 1.
• Build: dist is no longer minified - the consumer's own bundler minifies anyway in a real production build, and this keeps stack traces/devtools readable when debugging into the library.

Fixed

• SSAO: almost none of its props updated live on change - useMemo only depended on [camera, downSamplingPass, normalPass, resolutionScale], and props were never re-applied to the effect any other way. Changing color, intensity, radius, samples, worldProximityThreshold/worldProximityFalloff, or anything else did nothing until one of those four values happened to change too. Now applies live via useLiveDefaults.
• DepthOfField: changing depthTexture reconstructed the whole effect - render targets and passes included - despite DepthOfFieldEffect.setDepthTexture() existing specifically to update an existing instance in place. Now applied live.
• N8AO: config/quality changes mutate effect.configuration directly (a plain object outside r3f's reconciler) without ever calling invalidate(), so changes didn't repaint under <Canvas frameloop="demand">.
• EffectComposer: sized itself off r3f's size, which drei's <View> overrides per-portal only on View's own re-renders - not kept live - so a composer nested in a <View> could go arbitrarily long without picking up a resize (in practice: staying offset/wrong-sized indefinitely). Now reads gl.getSize() directly instead, which isn't portal-scoped and can't be missed regardless of whether the component itself ever re-renders.

Removed

• Pixelation, ShockWave: blendFunction/opacity props removed entirely. Both are mainUv-only shaders (no mainImage, verified against postprocessing's own pass-composition logic) - there's no color output to blend, so the props never did anything; they're gone rather than wired up. If you were passing either to <Pixelation>/<ShockWave>, remove them - they were already silent no-ops.

What's Changed

• Add createEffectComponent, a thin r3f-native effect factory by @kvvasuu in #363
• Rewrite EffectComposer's pass lifecycle for correctness and cost by @kvvasuu in #364
• Migrate simple effects to createEffectComponent by @kvvasuu in #366
• Migrate hand-rolled effects to useLiveDefaults by @kvvasuu in #367
• Simplify Autofocus's dispose handling, drop idempotency guard by @kvvasuu in #368
• docs: Update Custom Effects docs for React 19 by @MaximeHeckel in #337
• Fix/docs workflow v3 by @kvvasuu in #370
• docs(examples): migrate examples to @pmndrs/examples by @kvvasuu in #371
• feat: add DepthPicking component and useDepthPicking hook by @kvvasuu in #372
• chore: switch from yarn to pnpm by @kvvasuu in #373
• docs: add missing effect pages by @kvvasuu in #374
• docs: link effect examples to pmndrs/examples by @kvvasuu in #376

New Contributors

• @MaximeHeckel made their first contribution in #337

Full Changelog: v3.0.5...v3.1.0

Fixed

• EffectComposer: the composer was created in useMemo, which React may discard without running cleanup. Creation moved into a proper effect lifecycle instead. (#353) by @kvvasuu
• EffectComposer: renderer.autoClear and renderer.toneMapping were force-set and never restored. They're now restored on unmount. (#358) by @kvvasuu
• ChromaticAberration: moved off the generic wrapEffect onto a manual construct/dispose pattern so the tuple offset prop is correctly coerced. (#355) by @kvvasuu
• Selection: fixed an infinite update loop caused by Select's effect depending on its own write; it now diffs newly-claimed/released objects against what it previously claimed instead of clearing and re-adding unconditionally. (#359) by @kvvasuu
• Selection: object detection now covers Mesh/Line/Points subclasses (isMesh/isLine/isPoints), not just an exact type === 'Mesh' check - custom mesh subclasses are now selectable. (#359) by @kvvasuu
• SelectiveBloom: light refs that haven't attached yet are now resolved and filtered instead of crashing addLight/removeLight on a null object. (#360) by @kvvasuu
• Outline, SelectiveBloom: selection sync unified behind a shared useSelectionSync hook, which also stops the selection effect from re-running on every render (it previously depended on an unstable spread props object). (#360) by @kvvasuu
• Outline: patternScale, multisampling, resolutionScale, resolutionX, resolutionY are now wired up as live constructor options. (#360) by @kvvasuu
• SelectiveBloom: radius, levels, resolutionScale, resolutionX, resolutionY are now wired up as live constructor options. (#360) by @kvvasuu
• All <primitive>-based effects now dispose themselves (new useDispose hook). (#355) by @kvvasuu
• Corrected npm package metadata (added bugs/homepage fields). (#347) by @2lll5

Changed

• wrapEffect split out of util.tsx into its own module; Effect components dropped forwardRef in favor of ref as a plain, optional prop. (#352) by @kvvasuu
• @react-three/fiber peer floor raised to >=9.7.0. (#353) by @kvvasuu
• postprocessing moved from a pinned dependencies entry to a peerDependencies range (^6.36.0); three peer floor raised to >= 0.182.0. (#351) by @kvvasuu
• Migrated ESLint config to flat config; updated dependencies. (#351) by @kvvasuu
• Updated tone mapping docs (examples and props table). (#345) by @vis-prime

Added

• Smoke test coverage for every effect component, plus new regression tests for Selection, Outline, SelectiveBloom, ChromaticAberration, EffectComposer, and wrapEffect. (#355, #356, #359, #360) by @kvvasuu
• GitHub Action for publishing releases to npm from master, by @krispya

New Contributors

• @2lll5 made their first contribution in #347
• @vis-prime made their first contribution in #345

Full Changelog: v3.0.4...v3.0.5

What's Changed

• fix(types): emit types in build by @CodyJasonBennett in #327

Full Changelog: v3.0.3...v3.0.4

Manual re-release of v3.0.2.

Full Changelog: v3.0.2...v3.0.3

3.0.2 (2025-02-19)

Bug Fixes

• include dist folder in package files (#326) (dc9e2e6)

3.0.1 (2025-02-19)

Bug Fixes

• include dist folder in release artifacts (#325) (1d9526c)

3.0.0 (2025-02-19)

• BREAKING CHANGE: React 19 support (#318) (9bbc98c), closes #318

BREAKING CHANGES

• React 19 support