Shader for Interfaces

Implementation constraints

• Reuse the host application's renderer. Once Three.js is justified, default to WebGLRenderer with ShaderMaterial for custom GLSL. Do not add vgpu beside an existing Three.js or R3F renderer for one effect unless the product explicitly needs a separate WebGPU surface and accepts the extra device, bundle, lifecycle, and fallback cost.
• Choose vgpu for a contained WebGPU/WGSL effect when the project already uses it or when WebGPU, WGSL modules, or browser-and-Node pixel validation provides a concrete benefit. vgpu does not supply an automatic WebGL fallback; keep a designed non-WebGPU state.
• Give a contained vgpu surface one Gpu owner. Create its surface, effect, and resource objects once. After the first set(), keep each binding in the same ownership category: continue sending plain values to value-backed bindings, and keep user-owned textures, buffers, and samplers resource-backed. Stop the frame loop, unsubscribe resize callbacks, and call gpu.dispose() during teardown.
• Use the installed vgpu documentation or companion skill to resolve current API details. Load only the concept, guide, or symbol needed for the next decision; do not vendor the upstream manual or assume the latest online API matches the lockfile.
• Check the installed Three.js and R3F versions before using version-specific shader chunks, color APIs, renderer compilation hooks, or frame-loop behavior. Translate older APIs deliberately rather than presenting current syntax as version-agnostic.
• Use RawShaderMaterial only when full shader declarations are intentional. Then own precision, attributes, uniforms, GLSL version, fragment output, and output color conversion explicitly.
• Keep an existing React Three Fiber setup. Do not add R3F to a vanilla Three.js project for one effect.
• Keep DOM or application state authoritative. Feed shaders bounded visual derivatives of hover, focus, press, selection, disabled, loading, error, and progress states instead of making the GPU the component state machine.
• Name the owner of the renderer, scene, camera, geometry, material, uniforms, animation loop, resize logic, and cleanup.
• Mutate stable uniforms in the frame loop. Do not recreate materials, geometry, typed arrays, or React state each frame.
• Normalize pointer input within the canvas container unless the interaction is intentionally global.
• Use ResizeObserver for component-sized canvases. Distinguish CSS size, drawing-buffer size, and shader resolution.
• Avoid unbounded renderer, context, device, loop, and observer counts across repeated components. Use ui-integration.md to choose isolated, shared, or demand-driven surfaces. Carry focus, disabled/loading suppression, interruption, readiness, and fallback behavior into the chosen repeated-surface approach.
• Cap DPR. Start at Math.min(devicePixelRatio, 2) and lower it for fragment-heavy surfaces.
• Test color space, alpha, and transparent edges over the real interface background.
• Require a product, brand, reference, material, or data reason for dominant hues. Do not default to purple-cyan gradients, neon-on-dark glow, glass surfaces, or any replacement canned palette.
• Keep essential text, controls, status, and the only representation of data out of the canvas.
• Adapt shader source, textures, models, fonts, and data only when the user owns them or the applicable license permits the use. Preserve required attribution in the target project.

Browser gate

Before claiming completion:

1. Run the real app and check JavaScript, shader compilation, selected GPU backend, and asset errors.
2. Inspect desktop, mobile, and one unusual aspect ratio. When the effect repeats, test a representative grid or list rather than one isolated instance. Record layout stability, primary interaction latency, loading, and the first stable effect frame in addition to GPU timing.
3. Freeze time or use a fixed seed to judge the still composition.
4. Watch several seconds of motion for seams, hard bands, popping, unstable transparency, and discontinuities.
5. Test applicable default, hover, focus-visible, pressed, selected, disabled, loading, error, and progress states; input at the surface edges; resize; pointer cancellation; touch-scroll takeover; route interruption; and rapid re-entry.
6. Test reduced motion, initialization or context/device failure, unavailable selected GPU backend, and the static fallback.
7. Check the readability of the actual UI and inspect canvas accessibility semantics: decorative surfaces stay hidden and unfocusable, while meaningful or interactive surfaces have an accessible DOM equivalent or a complete name, description, and keyboard model.
8. Run the acceptance checklist in color-direction.md, including light/dark and runtime theme changes, supported forced-colors/high-contrast modes, grayscale, worst-frame contrast, non-color cues, and the generic-palette test.
9. Record browser, viewport, DPR, quality setting, and remaining gaps.

When output looks wrong, inspect UVs, normals, depth, field value, particle age, data value, alpha, and overdraw before tuning the final color.

Handoff

Match the handoff to the task:

• Recommend: report the renderer decision, rationale, constraints, fallback, and next validation step.
• Diagnose: report the cause, affected files or shader stages, reproduction evidence, scoped fix, and anything still inferred or unverified.
• Build or change: return the runnable integration and report changed files, public controls, input or data paths, browser checks, fallback behavior, and unverified states.