React Three Fiber WebGL…

适用于基于 @react-three/postprocessing 的 EffectComposer 实现屏幕空间后处理（Bloom、SelectiveBloom、SSAO、DepthOfField 等），而不是写 mesh 材质 shader。

适用场景

解决思路

1. 先检查实际 renderer 和 package peer dependencies；示例目标为 Fiber 9.7 / React 19、`@react-three/postprocessing` 3.1、`postprocessing` 6.39、WebGL；不要组合任意最新包版本，也不要静默升级项目。
2. 选择管线：这里的 React postprocessing composer 用于 WebGL；Three.js WebGPURenderer 在 r183+ 使用 node effects 和 `RenderPipeline`，需单独验证该后端。
3. 只让一个 owner 渲染最终场景；`EffectComposer` 使用正数 frame priority，额外手动 `gl.render` 会覆盖或重复其输出。
4. 普通 Bloom 可通过 HDR 阈值分离亮表面；只有确实需要对象选择时才用 `SelectiveBloom`，它会增加开销。
5. 实际选中对象 bloom 时，在 Canvas 下挂载 `Selection`，点击左侧 box 切换 selected；两个 box 都亮，但只有选中对象参与该 bloom pass。
6. 按示例结构：用 `<Selection>` 包裹 `<directionalLight ref={light} position={[0, 3, 5]} intensity={2} />`、被 `<Select enabled={selected}>` 包裹的 mesh、另一个对照 mesh，以及 `<EffectComposer multisampling={0}>`。
7. 在 `EffectComposer` 内放置 `<SelectiveBloom lights={lights} luminanceThreshold={0} intensity={2} mipmapBlur />` 和 `<ToneMapping mode={ToneMappingMode.ACES_FILMIC} />`；用 `useMemo(() => [light], [])` 收集 lights，用 `useState` 切换 selected。
8. `Selection`/`Select` 为支持选择的效果提供选择信息，例如 Outline 和 SelectiveBloom；把普通 Bloom 包在 `Selection` 中不会让 Bloom 尊重选中对象。
9. 为 `SelectiveBloom` 提供相关 lights，并让 selection layers 与其他 layer 用法协调；测试一个同样亮但未选中的对象，而不只是暗背景。
10. Bloom 在最终 tone mapping 之前基于亮度工作；使用 emissive/HDR 值和有意义的阈值；不要为了强制发光而压平整个场景。
11. 这个 composer 会禁用 renderer tone mapping；用 ToneMapping effect 达到预期最终外观；把 bloom/HDR effects 放在 tone mapping 之前，并避免重复输出转换。
12. `ref.current` 变为非 null 不会触发 React 重新渲染；不要仅依赖 ref 赋值来控制 effect 初始挂载；在需要响应式对象时使用支持的 refs 或 callback-ref state。
13. SSAO 在这个 wrapper 中需要 `<EffectComposer enableNormalPass>`；只为需要额外 buffer 的 effects 启用它们；当文档和行为不一致时检查已安装 effect 的源码/类型。
14. `DepthOfField` 的 `target` 是世界位置（vector/tuple），不是 mesh ref；`focusDistance={0}` 不是通用自动对焦开关；使用支持的 target 或 Autofocus helper。
15. 某些 effect props 接受 Three.js `Vector2`/`Vector3` 实例而不是 tuple；按已安装 wrapper 做类型检查；不要把 JSX coercion 假设转移到任意 React 组件。
16. Alpha 混合表面、深度、selection 和 multisampling 会相互影响；测试实际透明/透射场景，而不是依赖不透明 box 截图。
17. 性能上从少量 effects 和适中的 DPR/resolution 开始；有意选择 anti-aliasing 策略；避免盲目叠加 MSAA、SMAA 和 FXAA。
18. Effect 数量不等于 pass 数量：兼容 effects 可以合并；convolution/depth effects 和 auxiliary buffers 仍可能昂贵；测量 GPU 成本。
19. 优先使用支持的 wrapper 组件；对于自定义 postprocessing Effect，遵循 `mainImage`/`mainUv`、uniforms、input-buffer 和 effect-attribute 约定；改变 UV 的 effect 需要适当的 convolution declaration。
20. 为自定义 Effect 实例明确 cleanup ownership；不要在没有 owner 时使用 `dispose={null}`，也不要从一个 consumer dispose 共享 effect。
21. 更新后检查动态 prop 支持：仅在构造时生效的设置可能会重新创建 effect；不要为了动画 uniform 每帧重建 composer。
22. 验证时渲染完整 pipeline，切换 effects/selection，调整大小，并在 Strict Mode 下 unmount/remount；确认 selected-only 行为和最终颜色输出；TypeScript 无法证明这两者。

适用边界 · 注意事项

• 不适用于直接编写 mesh material shader / 材质内自定义 shader；本技能针对 composer pipeline 和屏幕空间效果。
• 不适用于未单独验证的 Three.js WebGPURenderer 后端；这里的 React postprocessing composer 面向 WebGL，WebGPU 应使用 node effects 和 `RenderPipeline`。
• 不适用于未核对实际 renderer 与 package peer dependencies、随意组合最新版本或静默升级的项目。