ether-shaders

Technique reference for the shader + postprocessing + extruded-text stack in the ether engine. Invoke before writing any shader, postprocessing change, or text-as-form work on a site built on it.

When to use

Any of:

• Writing a new ShaderMaterial, vertex shader, or fragment shader.
• Modifying postprocessing (bloom, dither, color grading, new effects).
• Adding or tuning extruded text — hero treatments, chapter heads.
• Diagnosing a banding / glow / type-ghosting / displacement-blur issue.

Invoke alongside ether-threejs (the general slop checklist) — this skill specializes, the other generalizes.

Read first

1. The ether-threejs SKILL.md — the general "no AI-slop three.js" checklist applies first.
2. recipes.md in this directory — nine numbered recipes.
3. Your studio's taste doc, if the repo has one — what lands vs. what doesn't.

The engine / site boundary

• Engine owns (ether src/):
  • postfx/composer.ts — createComposer, the one composer shape: render → your effects → (ACES when hdr) → dither, fused into a single EffectPass.
  • postfx/heroComposer.ts — three tunings of it: createHeroComposer (restrained LDR bloom for a dark scene with one bright accent), createNightComposer (hotter bloom for scenes whose light IS emissive geometry; exposes the optional hdr flag), createLightComposer (dither only — bloom on a pale ground just lifts the ground).
  • postfx/DitherEffect.ts — per-pixel hash grain applied through the sRGB transfer. Separately, shaders/dither.glsl is a standalone 8×8 Bayer chunk for your own materials; the effect does not use it.
  • primitives/ShaderQuad — backdrop plane with auto-wired uTime / uAspect.
  • text/extrudedWord — opentype → SVGLoader → ExtrudeGeometry pipeline (type as form).
  • text/msdf — msdfText, a troika-backed MSDF mesh (type as text), on its own entry so the optional peer stays optional.
• Your site owns (src/shaders/<scene>/):
  • The hero material shaders — your identity. Site-specific until a second consumer needs them.
  • Backdrop shaders (caustics, gradients, generative fields).

The engine is brand-free by construction: it ships wiring and takes the palette as uniforms, so the site injects its own colors. Don't promote site shaders to the engine without a generalization pass (uniform-driven palettes, no hardcoded brand-token vec3s).

Hard rules

• Follow the project's configured shader import convention — vite-plugin-glsl, ?raw (import frag from './x.frag.glsl?raw'), or inline strings. When adding a shader, use what the codebase already does; don't mix strategies without a reason.
• optimizeDeps.exclude: ['ether'] is mandatory in your astro.config.ts (or Vite config) for a git / file: install, which ships raw .ts. esbuild's dep-scan can't parse the engine's Vite-only ?raw GLSL imports; excluding it routes those files through Vite's full plugin pipeline instead.
• Never set preserveSymlinks: true for a file: layout — it pins the engine at its node_modules path, which Vite ignores for file-watching, so engine edits never hot-reload and it gets served as a stale cached external dep. Its one job (resolving the engine's bare three / postprocessing imports into the site's node_modules) is done correctly by resolve.dedupe: ['three', 'postprocessing', …] — set that instead. Both rules live together in astro.config.ts.
• Three composer presets exist — pick one, don't mutate one into the other. All three are thin tunings over createComposer; if none fits, write a fourth on createComposer rather than parameterising an existing one. createHeroComposer takes PresetOptions and is LDR by design — it never passes hdr, so values clip at 1.0 deliberately as bloom containment. Only createNightComposer re-exposes hdr (NightComposerOptions), which switches on HalfFloatType buffers + an ACES ToneMappingEffect and makes toneMappingExposure live. createLightComposer is dither-only.
• Edge AA comes from the composer's multisampling, never the context antialias flag. Post-processing renders into textures that bypass the canvas framebuffer, so context MSAA is visually dead the moment a composer runs (the quality profile sets antialias: false and carries msaaSamples instead — wire via createHeroComposer(renderer, scene, camera, { multisampling: quality.msaaSamples })).
• Dither runs on every tier. The quality profile ships enablePostFX: true and enableDither: true on LOW, MID and HIGH alike — tiers differ only in msaaSamples (HIGH 4 / MID 2 / LOW 0). It merges into the SAME fullscreen pass as bloom (a few ALU ops — effectively free) and kills the dark-gradient banding that reads as posterized color on mobile OLED. Never gate it on tier at a call site.
• Bloom intensity 0.06 is the hero-preset ceiling. Higher = glow-spam. Raise luminanceThreshold to gate harder if you need more visible bloom. The night preset ships 0.38 by design — its own ceiling, not a license to raise the hero's.
• Custom ShaderMaterial only on hero elements. No MeshBasicMaterial / MeshStandardMaterial for hero content. See ether-threejs.
• Brand tokens through uniforms. Pull colors from your site's constants module — the engine never names a color. If tokens are mirrored in CSS, update both when a color changes.
• Wire uTime through the scene tick. Material uniforms updated from tick() or via a wrapper's tickUniforms. Never via setInterval.
• Add precision highp float; at the top of fragment shaders explicitly — three.js prepends it by default, but stating it inline keeps the intent durable across pipeline changes.

Slop indicators (do not ship)

• Default materials (MeshBasicMaterial, MeshStandardMaterial) on hero elements.
• Bloom intensity > 0.1 on the hero preset, or luminanceThreshold < 0.5 (the night preset ships 0.38 by design).
• Hardcoded vec3(...) colors in shaders.
• Ambient particle fields with no narrative function (see ether-threejs).
• ShaderMaterial without uTime wired through the engine's tick.
• dat.gui left in production builds.
• console.log inside shader hot paths.
• ExtrudedWord with curveSegments < 6 on hero treatments.
• Single-color iridescent rim (must be a dual-color mix by normal direction).
• Promoting a site shader to the engine without uniformising the color palette.
• Vertex displacement strong enough to blur bevels on letter-extrusion geometry.

Procedure for a new ShaderMaterial

1. Confirm against the ether-threejs slop checklist first — general rules apply before specifics.
2. Decide ownership — is the shader reusable across sites (engine) or brand-specific (site)? Default: site, until a second consumer exists.
3. Place files — src/shaders/<scene>/<name>.{vert,frag}.glsl. Import them by the project's existing convention.
4. Wire uniforms through your constants module — brand colors, displacement amplitudes, fresnel exponents.
5. Tick uniforms from the scene's tick() (or a wrapping class's tickUniforms).
6. Add precision highp float; to fragment shaders.
7. Test against the hero composer. If your material needs HDR values, the LDR composer clips them — rework to 0..1 (preferred) or use the night preset.
8. Run premium-review before reporting complete.

After the skill

• Run the premium-review subagent on any shader work before reporting complete.
• If the shader is scroll-bound, also invoke ether-scroll for the bridge pattern.
• If creating a new dimensional-type treatment, cite the extrudedWord options you chose in the commit message — future grep will find the lineage.

Files

• SKILL.md — this file (the script).
• recipes.md — nine numbered technique recipes, each ending in a file + symbol citation index.
• evals/triggers.json — should/shouldn't-trigger regression set for the description.