# Mesh Physical Materials Spec — glass, metal and iridescence on Luxar meshes

**Status:** Phases 1–4 are **implemented** (Phase 3 opt-in per mesh, with the data
in front of the glass partitioned out and drawn crisp). Written after the `esm3_protein_stories` demo wanted translucent marker
shells around clusters and got them from the existing light-free mesh model (see
§2); this document is the plan for the materials that model cannot express, and —
for the delivered phases — the record of what shipped and where it deviates from
the sketch (the implementation notes in §3.1, §3.2, §3.3, §3.5 and §3.6).

## 1. Motivation

Luxar's four geometry types are emissive by design: points, lines and splats
have no lighting at all, and the mesh (`MESH_NODE_SPEC.md` §6.2) shades with a
light-free, view-anchored key so a surface reads without any light object in the
scene. That is the right default for scientific data. It is also a ceiling: a
mesh cannot look like glass, brushed metal, a soap bubble or a lens, because all
of those are statements about how a surface reflects and transmits an
*environment*, and Luxar has no environment.

three.js has all of it in `MeshPhysicalMaterial` (`transmission`, `ior`,
`thickness`, `attenuationColor`, `dispersion`, `clearcoat`, `iridescence`,
`sheen`, `roughness`, `metalness`) and in its node twin
`MeshPhysicalNodeMaterial`, on both backends Luxar ships. The question is not
whether the shading exists but how it enters a light-free, additively blended,
post-processed, dual-backend viewer without breaking the contracts the four
types share. This spec answers that in phases.

## 2. What the current model already gives (baseline, shipped)

Before adding a material system, note what the existing knobs do, because a
surprising amount of "translucent marker" is already there:

- Per-vertex **RGBA** colours: alpha is per-vertex opacity, consumed by every
  blending mode.
- `blending_mode` ∈ `opaque | normal | additive | luminous | max` (no
  `volumetric` on meshes).
- `shading` ∈ `smooth | flat | none`, with the wrapped diffuse term
  `mix(ambient, 1, pow(dot(N, L)·0.5 + 0.5, shade_exponent))` under a fixed
  view-space key `L`, plus an additive Blinn–Phong highlight
  (`specular`, `shininess`). `ambient = 0` removes the floor so only the lit
  side of a shell shows; `shininess` shapes the highlight.
- `double_sided`, `layer_order` bands, and the nD vertex array (a marker can be
  pinned to a hidden-dimension slot like any other node).

The stories demo's marker spheres are exactly this: an icosphere per cluster,
story colour at alpha 0.10, `additive`, `ambient = 0`, `shade_exponent = 2`,
`specular = 0.35`, in a depth band between backdrop and highlight. What this
cannot do: Fresnel rim falloff (the key is fixed, not view-relative), refraction
of what lies behind, reflections, dispersion.

## 3. Design

### 3.1 Authoring: an opt-in `material` on `add_mesh`

```python
scene.add_mesh(
    "lens", vertices, faces, normals=normals, normal_dims=[0, 1, 2],
    colors=rgb,                       # base colour (vertex colours), as today
    material="physical",              # opt-in; default stays the house shader
    roughness=0.05, metalness=0.0,
    transmission=1.0, ior=1.5, thickness=0.4,
    attenuation_color="#f6d148", attenuation_distance=0.3,
    dispersion=0.5,
    clearcoat=0.0, iridescence=0.0,
)
```

`material` is a node attr with two values, `"luxar"` (default, today's shader)
and `"physical"`. The physical parameters are plain snake_case attrs validated
in `add_mesh` (ranges per three's documentation: `roughness`/`metalness`/
`transmission`/`clearcoat`/`iridescence` in [0, 1], `ior` in [1, 2.333],
`thickness` ≥ 0, `dispersion` ≥ 0, `attenuation_distance` > 0 or absent) and
written only when set. Unknown material attrs are refused, as `Waypoint.rendering`
refuses unknown keys: an audience is the wrong place to discover a typo.

A physical mesh keeps everything else a mesh has: nD vertices and the §5
slab cull, `layer_order`, `opacity`, labels/picking, partition and LOD groups,
`double_sided`. It drops the house-shader-only knobs (`shading`, `ambient`,
`shade_exponent`, `specular`, `shininess`, `blending_mode`, colormaps): those
are refused when `material="physical"`, not silently ignored.

**Phase 1 implementation notes** (what shipped; the contract where it differs
from the sketch above):

- The Phase 1 knob set is `roughness`, `metalness`, `clearcoat`,
  `clearcoat_roughness`, `iridescence`, `sheen` — each a finite float in
  `[0, 1]` — plus **`sheen_color`** (`"#rrggbb"`), which the sketch omitted:
  three's default sheen colour is black, so `sheen` alone renders nothing, and a
  knob that can never render anything is exactly the trap this validation exists
  to refuse. The viewer defaults `sheenColor` to white when unset for the same
  reason.
- **Phase 2 (delivered)** adds the glass family: `transmission` (`[0, 1]`), `ior`
  (`[1, 2.333]`), `thickness` (`>= 0`), `attenuation_color` (`"#rrggbb"`),
  `attenuation_distance` (`> 0`; absent = none) and `dispersion` (`>= 0`). One
  more pairing rule: `thickness`, `attenuation_*` and `dispersion` are refused
  without a `transmission` above zero, because three compiles them only inside
  its `USE_TRANSMISSION` block — written, they would be silently ignored. `ior`
  stands alone (it also sets an opaque surface's specular reflectance).
- **Phase 3 (delivered)** adds one boolean, `refract_data`: the glass draws AFTER
  the emissive data and refracts it (§3.4). Absent = false, so every Phase 2 scene
  keeps its glass-first behaviour. It joins the pairing rule — refused without a
  `transmission` above zero, since a surface that transmits nothing has nothing to
  refract — and is refused as a number (`refract_data=1` reads like a slider value).
- **`shading` is kept, not refused**, except for `"none"`. Flat-versus-smooth
  normals is a property of any lit surface, not of the house key; it maps onto
  three's `flatShading`. Only the unlit `"none"` is meaningless on an
  environment-lit surface.
- **`alpha_cutoff` is mapped, not refused**: it becomes three's `alphaTest`, and
  on an RGBA mesh its presence selects the opaque cutout path over
  translucency — the meaning the house `opaque` mode gives the same pair.
- Refused under `material="physical"` (a `ValueError` naming the knob and why,
  from the mesh adder next to the volumetric refusal): `ambient`,
  `shade_exponent`, `specular`, `shininess`, `blending_mode`, `colormap`, a
  `texture`, `shading="none"`. A physical knob without `material="physical"` is
  refused too, as is an unknown `material` value. `material="luxar"` is accepted
  and written as given; an absent attr means the house shader.
- The vocabulary lives in `luxar.validation.types` (`MESH_MATERIALS`,
  `PHYSICAL_MATERIAL_ATTRS`, `HOUSE_SHADER_ONLY_ATTRS`) and every key is also in
  `MESH_ONLY_APPEARANCE_ATTRS`, so points, lines, splats and groups refuse it.
  (`Waypoint.rendering`, cited above as the style precedent, is not on `main`;
  the shipped refusals follow `validate_render_attrs`'s.)

### 3.2 Viewer: a third material family, not a variant

`createMeshNode` reads `attrs.material`. For `"physical"` it constructs three's
own material — `MeshPhysicalMaterial` on WebGL, `MeshPhysicalNodeMaterial` on
WebGPU — with `vertexColors = true`, `transparent = transmission > 0 || opacity < 1`,
`side` from `double_sided`, and the attrs mapped one to one. It is registered
in `material-manager/factories.ts` as its own entry (`meshPhysical`) rather than a
variant of `MeshMaterial`, because none of the house contracts apply to it:

- **No codegen snapshots.** The snapshot harness pins TSL Luxar writes. Three's
  own materials are three's to pin.
- **Picking** still uses the house `mesh-pick` material: picking renders
  geometry, not appearance, so a physical mesh picks exactly like a house mesh.
- **Depth sorting.** A physical mesh is not registered with the triangle sorter
  (`normal` mode's per-triangle sort is a house-shader feature). Three handles
  transmissive objects in its own render list order (§3.4).
- **Layer bands.** `renderOrder` from `layer_order` applies unchanged; three
  sorts within each of its lists by `renderOrder` first.

**Phase 1 implementation notes.** Three's material is wrapped, not used bare:
`PhysicalMeshMaterial extends MeshPhysicalMaterial` and
`PhysicalMeshTSLMaterial extends MeshPhysicalNodeMaterial`
(`rendering/materials/mesh-physical/`), sharing ONE attr→property mapping. The
wrapper exists because the viewer's generic paths assume a leaf-material surface:
`MaterialManager` broadcasts camera params, the Layers panel / exposure / LOD
cross-fade gate on `updateIntensity` + `updateGamma`, and a layer reset calls
`applyBlendingMode` (falling back to writing the HOUSE blend state when the
method is missing). So the wrapper implements exactly that surface with physical
meanings — `intensity` → a scalar base-colour gain, `offset` → emissive,
`gamma` recorded only, `applyBlendingMode` a no-op — and nothing more. It has
no camera surface (the near fade is a house-shader feature) and stamps
`userData.blendingMode = 'opaque'` only when opaque, so the depth-sort
coordinator releases it in every case while the `layer_order` band rank still
applies. Translucency is read off the data (`opacity < 1`, `transmission > 0`,
or per-vertex alpha without an `alpha_cutoff`); translucent surfaces do not
write depth. Vertex alpha is learned at the first commit
(`applyMeshVertexAlpha`), since the attrs record `has_colors` but not the
component count.

**Phase 2 implementation notes.** The knobs are ONE table
(`PHYSICAL_MESH_KNOBS` in `config.ts`: attr, three property, domain, default,
slider presentation, program-affecting flag) that the construction mapping, the
live Layers-panel sliders and the tests all read. `setPhysicalKnob` is the single
write path and flags `needsUpdate` when a program-affecting knob crosses zero:
three's WebGL setters version-bump on that crossing already, but
`MeshPhysicalNodeMaterial` stores plain properties and bakes `useTransmission`
into its lighting model at setup, so the rule lives in the shared helper for
both twins. Glass composites as translucent — the §3.4 contract made concrete: a
depth-writing shell would HIDE the cluster inside it, the worse failure for the
marker case — and stamps `userData.drawBeforeEmissive`, which the depth-sort
coordinator turns into "first within its `layer_order` band" (renderOrder −1
when unranked); see §3.4 for why that is needed on WebGPU.

### 3.3 Lighting: a scene environment, not scene lights

Physical materials render black without light. Luxar stays light-free in the
sense that matters (no light objects in the graph, nothing per-node), and gains
one scene-level input: `scene.environment`.

- **Default:** three's procedural `RoomEnvironment` through `PMREMGenerator`,
  built lazily the first time a physical mesh is created and cached by the active
  viewer host (`SceneManager` or `LuxarLayer`). Layer mode preserves a host-supplied
  `scene.environment`; otherwise its environment also lights the host's own
  lighting-model materials until the layer is disposed. It needs no asset, gives
  believable reflections and a neutral key, and is what three's own examples use.
- **Authored (Phase 4):** `viewer_config.environment = {"source": "room" |
  "scene" | "hdri", "probe": "auto" | [x, y, z] | "node:<path>", "resolution":
  128, "intensity": 1.0, "url": ...}`. `"room"` is today's default. `"hdri"`
  loads an equirectangular image from the store (the loader already fetches
  opaque files for overlays and textures). `"scene"` is the interesting one and
  is described next.
- `environmentIntensity` rides `viewer_config.environment.intensity`.

**Scene-derived environments (`"source": "scene"`).** Luxar's data is emissive,
so a capture of the scene *is* a radiance map of the data: a chrome sphere or a
glass shell reflects the cloud it sits in, and the light-free principle holds —
the data is the light, nothing is added to the graph. The capture is EXACT and
reuses the real shaders: a `CubeCamera` renders the scene from the probe point
into a cube render target, `PMREMGenerator.fromCubemap` prefilters it, and the
result goes onto `scene.environment` through the same lazy
`SceneEnvironment.ensure()` seam the room uses. An approximate alternative
(projecting the resident emitters into a small equirect on the CPU, no render)
was considered and **rejected**: it would re-implement the appearance pipeline
(colormaps, intensity, opacity, gamma, textures, LOD energy compensation) a
second time and keep it in step with the shaders forever — the two-copies drift
this codebase is organised to make impossible — for a saving that is only real
per frame, and the capture is never per frame.

Four details make the exact capture cheap and correct:

- **Trigger, not cadence.** Capture on camera settle and on data commit (and on
  slice change), at 64–128 pixel faces. Six low-resolution draws a few times a
  minute; never per frame unless the probe moves.
- **Sprite sizes.** Point and line footprints come from the camera params the
  material manager broadcasts (fov, resolution). The capture pushes the cube
  camera's params before the six renders and restores them after.
- **No self-reflection.** Physical meshes are masked out of their own capture
  with the cube camera's `layers` bit (a mesh that reflects a stale copy of
  itself is the failure mode). Blending the room in is just the room's boxes
  added to the capture scene.
- **Parallax.** A cube map is exact only at its probe. `"auto"` is the scene
  centre (the showcase case); `"node:<path>"` captures from a node's bounding-box
  centre, which is what a marker shell around a cluster wants. Depth-sorted
  `normal` / `volumetric` layers are ordered for the main camera, so their
  reflection is slightly mis-ordered — invisible under any real roughness.

**Baking at compile time: `luxar env bake`.** The same capture, driven headlessly,
moves the cost off the viewer entirely for a published scene:

```bash
luxar env bake scene.luxar.zarr                       # probe auto, 128 px faces
luxar env bake scene.luxar.zarr --probe node:clusters/shell_3
```

It drives the viewer through Playwright the way the gallery capture does (so it
runs unattended on a GPU box), using a `?bakeEnv&probe=...` URL parameter that
makes the viewer capture on load settle, read the six faces back as FLOATS
(`readRenderTargetPixels` — a PNG would clip everything above 1.0 and destroy the
highlights that make metals read) and download one binary blob with a JSON header
(probe, resolution, scene `content_hash`, appearance state). `luxar env attach
scene.luxar.zarr faces.bin` is the manual half of the same loop: it writes the
faces as an `environment/faces` zarr array of shape `(6, H, W, 3)` (float16) with
the header as attrs. At load the viewer builds a `CubeTexture` from it and runs
`PMREMGenerator.fromCubemap` — milliseconds — so what is stored is the raw
capture and the prefilter math stays three's. Idempotent (an unchanged scene
rewrites nothing) and honest about staleness: the viewer ignores a baked map
whose `content_hash` does not match the scene, says so in the console, and falls
back to the live capture or the room. What baking freezes: one appearance (a
Layers-panel colormap change does not reach the reflections until re-baked) and
one slice — a scene sliced on a hidden dimension gets one map for the slice it
was baked at, or one per slice under `environment/<slice>/`. Fine for a published
demo, which is where baking pays; for authoring sessions the live capture is the
default.

House-shaded meshes, points, lines and splats ignore `scene.environment`
entirely (their shaders never read it), so enabling it changes nothing about
existing scenes.

**Phase 4 implementation notes** (what shipped; where it differs from the text
above):

- **No explicit `PMREMGenerator.fromCubemap` call.** Both backends re-prefilter a
  cube texture assigned to `scene.environment` whenever its `pmremVersion` moves,
  and `CubeCamera.update` bumps it — so the live capture is "render six faces,
  assign the target's texture", and a baked map is "build a half-float
  `CubeTexture`, assign it". The room still goes through `fromScene` once.
- **Visibility, not a `layers` bit, hides physical meshes during the capture.**
  A persistent bit would need the pick camera and the main camera to agree on it;
  each mesh's PREVIOUS `visible` is restored, so a user- or LOD-hidden mesh stays
  hidden. (The one `layers` use in the viewer, Phase 3's refraction split, is
  transient inside a single render call and restored before this capture can run.)
- **Camera settle is NOT a trigger.** A cube map from a fixed probe is
  view-independent; the only camera-driven change — LOD residency — arrives as a
  geometry commit. Triggers are: geometry commit (`eventBus 'geometry-committed'`),
  slice change, appearance change; a 250 ms debounce; and the loader's settled
  predicate. The first light is an immediate capture of whatever is resident.
- **The capture pushes its own camera params** to the material manager directly
  (90° fov, a square drawing buffer, pixel ratio 1) and restores the main camera's
  through the ordinary path, because the shared helper reads the canvas size.
- **The store contract.** `environment/` is a root-level group with no `type` and
  no `kind` (the viewer skips such groups as sidecars; `RESERVED_ROOT_GROUPS` makes
  every general Python walker that enumerates root children as nodes do the same,
  and the compiler refuses a user node by that name). The faces array is
  `environment/faces-<xxh64[:8]>`, shape `(6, H, W, 4)`,
  zarr dtype **`uint16` holding IEEE half-float bits** rather than `float16`:
  zarrita throws on `<f2` without a `Float16Array`, while the GPU readback and
  three's `HalfFloatType` cube texture already speak half bits, so `uint16` needs
  no conversion at either end. RGBA rather than RGB because the readback is RGBA.
  The digest suffix makes a re-bake a NEW path (a caching viewer cannot serve stale
  faces); the group's `faces` attr names the live array.
- **The environment group is EXCLUDED from the scene `content_hash`** (both
  hashing walks). That is what makes the header's `scene_content_hash` an exact
  guard the viewer can evaluate, keeps `luxar env attach` from invalidating every
  visitor's warm cache, and makes attaching idempotent. The group carries its own
  digest for tooling.
- **`luxar env bake`** serves the store and the built viewer from one process
  (a stoppable `served_store`), drives a headless browser to
  `?bakeEnv&probe=…&envResolution=…` through the viewer's Playwright
  (`scripts/bake-env.mjs`, Node — Playwright is a devDependency of the viewer, not
  a Python dependency, so the command needs a development checkout), pulls the
  `LXENV001` container back through `page.evaluate` as base64 rather than a
  download event, and attaches it. `luxar env attach` is the manual half. A
  bake ignores any previously attached map (it captures the SCENE), and a
  stale bake is refused unless `--force`.
- Precedence at load: a valid baked map > `viewer_config.environment.source` > the
  room. `viewer_config.environment` round-trips through the Python
  `EnvironmentConfig` dataclass and the Ctrl+Shift+S export.

### 3.4 Transmission and what it can see

This is the load-bearing limitation and must be stated before anyone authors a
"glass sphere around a point cloud".

Three renders transmission by drawing the scene into a transmission render
target and sampling it, blurred by roughness, behind the transmissive surface.
Both backends do this natively (WebGL `renderTransmissionPass`, WebGPU
`Renderer` with `viewportSharedTexture`). The target is filled from the
**opaque and transmissive** render lists. **Transparent objects are excluded.**
Every Luxar point, line and splat material is `transparent: true` (additive,
luminous, normal, max). Therefore:

> A physical mesh with `transmission > 0` refracts the background, opaque
> meshes and other physical meshes. It does **not** refract points, lines or
> splats — they are drawn afterwards, on top, unrefracted — **unless it is
> authored with `refract_data=True`** (Phase 3, below), in which case it draws
> after them and refracts what is behind it, while what is in front of it is
> drawn crisp on top (the depth partition, below).

For the stories demo's "glass around a cluster", the cluster's points would sit
crisply *on* the glass rather than *inside* it. Whether that reads well is a
design question, not a bug; it is also why the additive rim shell (§2) is the
right marker for the kiosk.

**Phase 2 (delivered) — what makes that statement true on BOTH backends.** On
WebGL it is free: the transmissive list draws before the transparent list, a
glass fragment lands with alpha 1 (`transmissionAlpha` is 1 because the
transmission target is cleared at alpha 1), and the glass writes no depth, so the
emissive draws that follow land on top. On WebGPU a transmissive mesh joins the
SAME transparent list as every point, line and splat layer, sorted back-to-front
by object depth — so a cluster whose centre sorts farther than the sphere would be
drawn first and then painted over by the alpha-1 glass. The physical material
therefore stamps `userData.drawBeforeEmissive` while `transmission > 0`, and the
depth-sort coordinator's cross-node pass orders such a mesh first within its
`layer_order` band (renderOrder −1 when unranked, since unranked emissive layers
sit at three's default 0). One more asymmetry worth recording: WebGL exposes
`renderer.transmissionResolutionScale` (left at three's 1.0; the 0.5 default
belongs to Phase 3's cost work), WebGPU has no equivalent and always mip-chains a
full-resolution framebuffer copy, so its transmission cost is not tunable.

**Phase 3 (delivered) — data through glass, opt-in.** `refract_data=True` flips
the ordering stamp to `userData.drawAfterEmissive`. The spike
(`spike/glass-refracts-data`) settled the mechanism and its cost before this was
built; the owner's review of the first delivery then removed the one limit the
spike had accepted (data in front of the glass painted over), with the partition
described last below.

- **Rank last.** The depth-sort coordinator gives a refracting glass a rank even
  when nothing else would (the unranked emissive layers sit at renderOrder 0) and a
  `last` flag that mirrors Phase 2's `first`: after everything else in its
  `layer_order` band, before any higher band. The containment hoist (§6.3 of the
  mesh spec) skips edges that touch a glass-last group — a lens enclosing a cluster
  is exactly "container contains content", and hoisting the lens first would paint
  the cluster crisp on top instead of refracting it.
- **The split.** `PostProcessingManager` owns a `DataRefractionSplit` that runs on
  BOTH backends when a visible glass asks to refract (`collectRefractingGlass`, read
  off the coordinator's node registry, not a scene traversal). Pass G renders the
  refracting glass's FRONT faces, depth only, through depth-only proxies into a
  target wrapping the one shared depth texture (`materials/_shared/glass-partition.ts`;
  cleared depth 1.0 = "no glass here"). Pass A renders everything but the refracting
  glass into the HDR target with the data in partition mode 1. On WebGL — whose
  `renderTransmissionPass` draws only the *opaque* list into a mip-mapped half-float
  target — the colour is blitted into a copy target, and pass B renders the glass
  plus one OPAQUE screen-space quad textured with that copy, so three draws the quad
  into the transmission texture and the glass refracts the data; on WebGPU three
  samples the live framebuffer and pass B is the glass alone. Pass C renders the data
  again in partition mode 2. Pass A's depth survives, so an opaque mesh in front
  still occludes the glass. The refracting glass sits on `Object3D.layers` bit 1 and
  the meshes three's own materials draw (Phase 2 glass, opaque physical surfaces —
  they carry no Luxar shader and cannot classify themselves) on bit 2 for the
  duration (`rendering/render-layers.ts`), drawn in pass A and left out of pass C;
  everything borrowed — the partition mode first, the layer masks, the camera mask,
  `autoClear`, the scene background, the transmission scale, the quads' scene
  membership — goes back in a `finally`, so nothing outside that one render call
  can observe any of it: picking, the environment capture, the blend warm-up and
  scene disposal are untouched. The raw-HDR capture path shares the same stage, so
  an EXR refracts too.
- **The depth partition — how data in front of the glass stays crisp.** Emissive
  layers write no depth (additive mode has the depth test off altogether), so
  nothing in the hardware can tell a lattice row in front of the lens from one
  behind it. Every Luxar data fragment shader (points, quad and capsule lines,
  splats, the house mesh; GLSL and TSL) therefore classifies ITSELF against the
  pass-G texture, first thing in its fragment stage:
  `inFront = glassDepth < 1.0 && fragmentDepth < glassDepth`. Mode 1 discards the
  fragments in front; mode 2 discards the rest. The two modes are complements of one
  predicate, so every data fragment is drawn exactly once across passes A and C, and
  the glass paints over nothing nearer than itself. The mode is a runtime uniform
  (`uGlassPartition`, flipped several times per frame, never a define), the sampler
  `uGlassDepth` binds ONE module-level `DepthTexture` that the pass-G target is
  created with, so no material is ever rebound; the pick materials deliberately
  carry neither — picking must see all the data, and it runs while the mode is 0.
  GLSL reads its own window depth from `gl_FragCoord.z` and the texture with an
  exact `texelFetch` at its pixel; TSL carries the clip `zw` as a varying (the data
  graphs replace three's vertex stage, so three's depth nodes would read a
  quad-corner attribute) remapped to window depth per coordinate system at
  build time, and samples at `screenUV` exactly as three's `viewportDepthTexture`
  does, so the depth texture's Y flip on the GLSL builder is applied for free.
  The depth map stores only the nearest refracting front face, so overlapping
  refracting glasses can paint over data in front of the farther glass. Viewed from
  inside a double-sided refracting glass, the front-face proxy writes no depth and the
  shell can paint over enclosed data.
- **Two things three does that the split must undo.** (1) Both renderers FORCE a
  clear at the start of every `render()` whose scene has a colour background,
  whatever `autoClear` says — passes B and C run with `scene.background` taken away
  (found by bisecting a black frame: the original two-pass split only survived
  because the WebGL quad repainted the frame after that clear). (2) Under MSAA the
  WebGL renderer resolves a multisampled target's colour to its texture at the end of
  every `render()` and INVALIDATES the multisampled colour attachment (depth is
  resolved and kept), so passes B and C each draw onto undefined colour until a
  full-screen quad repaints it from a copy; the pass-B quad and a second blit +
  restore quad before pass C do that, which is why the quads' `depthTest:false`,
  `depthWrite:false`, `transparent:false` and `frustumCulled:false` are pinned by
  test. `WebGPURenderer`'s WebGL2 fallback (`?webgpuForceWebgl`) invalidates too
  and cannot take the GLSL quads, so that one combination with MSAA on falls back to
  a single pass with a warning.
- **`transmissionResolutionScale` 0.5, pass B only** (config
  `renderingControls.refraction`, validated in `(0, 1]`). Three reads it per
  transmission pass, so Phase 2 glass in pass A keeps three's default and its
  pixels are untouched; WebGPU has no equivalent knob. SSAA is plain supersampling
  here (there is no camera jitter), so all passes render at the same size.

**The alpha finding — the one thing the spike changed about this design.** Luxar's
`additive`, `luminous` and `normal` point and line shaders are alpha-weighted (RGB
unweighted, alpha = intensity·opacity, blended SrcAlpha/One with One/One on the
alpha channel), so the HDR framebuffer alpha behind a point cloud is an overdraw
count — 8 to 18 was measured, `Infinity` on dense scenes. The house already treats
that channel as undefined: the mega shader reads RGB only and the EXR capture forces
alpha to 1 before export. Three's transmission, meant for transparent canvases,
copies the sampled alpha into the glass fragment alpha (`transmission_fragment`'s
`transmissionAlpha` on WebGL, `PhysicalLightingModel.start`'s `diffuseColor.a`
multiply on WebGPU), an UNCLAMPED blend factor on a half-float target: a glass drawn
after the data came out thousands of times too bright, or negative, on both
backends. **Decision: the physical family refuses that channel too.** The WebGL
wrapper's `onBeforeCompile` expands the `transmission_fragment` include with the one
mix line pinned to `1.0` (a unit test on three's real chunk turns a future drift
into a red build; a fixed `customProgramCacheKey` keeps the warm-up fingerprint
stable); the WebGPU wrapper's lighting model saves `diffuseColor.a` into a property
node before three's `start` and restores it after (a `toVar` would be declared
after the multiply). Always on, and a pixel no-op for the glass-first path, whose
transmission target only ever holds the alpha-1 clear and opaque meshes; an
`opaque`-mode house layer or a cutout mesh seen through glass now follows the same
rule. Redefining HDR alpha as coverage was considered and rejected: it needs
premultiplied output plus separate alpha blend factors on every emissive mode on
both backends (the gsplat code records that separate alpha-channel blend state trips
the WebGPU renderer's WebGL2 bridge), and with the clear alpha at 1 it would yield
the same pixels.

**Cost.** Paid only in frames where a refracting glass is visible; every other
scene keeps today's single pass. Measured on `mesh_glass_lens_example` (three
spheres, 675 points) at 1280×720, dpr 1, Apple M4 Max, median of 7 trials × 20
`PostProcessingManager.render()` calls behind a GPU barrier (a one-pixel
`readPixels` on WebGL — `gl.finish()` returns in 0 ms on ANGLE/Metal and is not a
barrier — and `queue.onSubmittedWorkDone()` on WebGPU):

| | refracting glass hidden (one pass) | the partitioned split | the earlier two-pass split (partition off, in-page) |
| --- | --- | --- | --- |
| WebGL | 1.7 ms | 4.2 ms | 5.2 ms |
| native WebGPU | 0.8 ms | 1.5 ms | 1.5 ms |

Switching the passes off one at a time attributes the whole difference to pass B —
the glass draw with three's transmission render — on both backends; the depth
pre-pass, the partition compare (one texel fetch per data fragment under a uniform
branch) and pass C add nothing measurable on this scene. What pass C does add in
general is the data's vertex work a second time, most of whose fragments discard at
once: on a multi-million-point cloud that is a share of the data draw in exactly
the frames where a refracting glass is visible, and the adaptive DPR manager
regulates frame time in any case. (The spike had measured the two-pass split at
0.68 ms on a one-sphere scene; the 3.5 ms pass B here is pre-existing and a
follow-up, not part of the partition.)

**What the depth table now means.** Which emissive layers write depth decides what
a glass surface drawn after them is occluded by in pass B
(`rendering/blending-state.ts`):

| Mode | depthTest | depthWrite |
| --- | --- | --- |
| `additive` | off | off |
| `luminous` | on | off |
| `max` | on | off |
| `volumetric` | on | off |
| `normal` | on | only at opacity ≥ 0.99 (points, gsplats; lines never) |
| `opaque` | on | on |

Before the partition this table was the limit: data in `additive`, `luminous`,
`max` and `volumetric` layers in front of a refracting glass was painted over by
it. The partition removes that dependency — the in-front fragments are held back
from pass A and drawn in pass C whatever their mode — so the table only says which
layers ALSO occlude the glass through the hardware depth test (`opaque`, and
`normal` at near-full opacity). Depth-sorted layers are ordered for the main
camera, so through a clear lens their order is slightly off (invisible under
roughness). The flag stays opt-in per mesh because refraction is a look, not a
default: a lens of saturated data is a white disk — additive data above 1.0 clips
under tone mapping — so a showcase needs faint, non-overlapping points, and the
frame pays pass B.

### 3.5 Colour pipeline

The viewer renders linear and tone-maps in post (ACES by default). Three's
physical materials output linear radiance and read `renderer.toneMapping`, which
Luxar leaves at `NoToneMapping` for the scene pass, so a physical mesh flows
through bloom and the tone-mapping pass like any emissive node. Two consequences
to test, not assume: the bloom threshold treats a bright specular highlight as a
light source (usually desirable on glass, possibly not on metal), and `AgX`/
`Neutral` tone mapping shifts the saturated `attenuationColor` of thick glass.

**Phase 1 measurement** (the demo scene, `ab-webgpu-vs-webgl.mjs --bloom`,
1280×720, `dpr=1`, ACES, default bloom threshold 0.01). With bloom OFF (the
default) the physical spheres' specular highlights occupy ~1.5% of the frame as
near-white pixels against ~0.04% for a house-shaded fixture: the highlights ARE
bright, as expected of a polished metal under a room environment. With bloom ON
they bloom heavily — near-white rises to ~4.8% on WebGL — but so does everything
else at that threshold (the house fixture's own lit surfaces go to ~8.5%), so
the default threshold, not the material, decides. A metal that reads too hot
under bloom is a `bloom_threshold` matter for the scene author. Separately, the
bloom pass itself diverges between backends (WebGL blooms noticeably more than
WebGPU on the SAME scene, including a house-only one: SSIM 0.87–0.91 with
bloom on vs 0.99–1.00 with it off); that is a pre-existing post-pipeline
difference, not a physical-material one, and is tracked as #2563 rather than fixed here.

### 3.6 Dual-backend parity

`MeshPhysicalMaterial` and `MeshPhysicalNodeMaterial` are three's own and are
close but not pixel-identical (transmission blur and dispersion differ in
sampling). The acceptance test is a real-WebGPU A/B on the stories scene with a
structural-similarity floor, not pixel equality; the mesh spec's §11 row 6 A/B
harness is the tool.

**Phase 1 result.** The §11 row 6 run was manual, so the tool now exists as a
script: `packages/luxar-viewer/scripts/ab-webgpu-vs-webgl.mjs` launches the
system Chrome (the only headless browser with a WebGPU adapter), captures the
same scene on WebGL and on real WebGPU — verifying the WebGPU arm actually got a
WebGPU backend — and reports SSIM, normalised cross-correlation and lit-pixel
counts on a 256² greyscale downscale. On `mesh_physical_materials_example` (then six
spheres: house shader, dark clearcoat shell around an emissive cluster, gold,
steel, pearl, velvet) the two backends score **SSIM 0.986, NCC 0.998**, both
with the environment built and 7,680 triangles committed; the Fresnel rim on the
dark shell is visible on both. The stories scene is not on `main` yet, so the
demo carries the A/B until it is.

**Phase 2 result.** The same run on the nine-sphere demo (three glass spheres in
front of a house-shaded checkerboard, an emissive cluster inside the clear
one; 11,808 triangles, environment built on both arms, real WebGPU verified):
**SSIM 0.988, NCC 0.998**, lit-pixel share 15.6% (WebGL) vs 18.4% (WebGPU). Both
arms refract the checkerboard through all three glass spheres, the amber
sphere's volume attenuation reads on both, and the cluster inside the clear
glass is drawn crisp and unrefracted on both — the draw-before-emissive rule
doing its job on WebGPU. Where the arms differ most is the dispersive crystal
(`ior=2.0`, `dispersion=0.6`): WebGPU's transmission sample comes off a coarser
level of its framebuffer mip chain there and shows the checkerboard's tiles
through the sphere where WebGL shows a smoother frosted refraction. That is the
sampling difference this section predicts, not a defect in either mapping, and
it is why the acceptance floor is structural similarity rather than pixels.

**Phase 4 result** (`mesh_reflections_example`: a 60k-point emissive swirl with a
chrome and a glass sphere, `environment.source = "scene"`, 1280×720, dpr 1,
bloom off). Live capture: **SSIM 0.986, NCC 0.9995** WebGL vs real WebGPU, the
environment built on both arms — the chrome reflects the swirl on both. Then a
real headless bake through `scripts/bake-env.mjs` against the dev viewer (a 64 px
cube, 197 KB container), attached with `luxar env attach`, and the same frames
captured again with the viewer reporting `kind = baked`: baked-vs-live agreement
is **SSIM 0.9985 (WebGL) / 0.9989 (WebGPU)** on the same backend (an
unrelated-scene control scores 0.23), so the stored faces rebuild the texture the
capture produced — orientation included — and with the baked map the two
backends render identically (**SSIM 1.000**), since neither captures anything.
`LuxarScene.nodes` and `luxar info` list no `environment` node, the root
`content_hash` is unchanged by the attach, and a second attach is a no-op.

**Phase 3 result** (spike, `spike/glass-refracts-data`, on a faint point lattice
with a refracting glass sphere, 1280×720, dpr 1). With the flag off the two
backends agree at **SSIM 0.999** inside the glass; with it on, **0.888–0.917**
(the lens is a magnified, inverted image of soft point sprites, and the two
transmission samplers blur it differently). On the saturated reflections swirl
the lens is a white disk on both and they agree at 0.994–0.998. Before the alpha
pin the same crops scored 0.25–0.58 and the HDR pixels inside the glass read
`[-15504, -21808, -22336, 65504]`. The verification run of the delivered code on
`mesh_glass_lens_example` is recorded in the Phase 3 PR. **With the depth
partition** (WebGL vs native WebGPU on the lens example, whole frame): **SSIM
0.991, NCC 0.997**. The partition itself, from behind the spheres with the lattice
between the camera and the lens: of the 22 lattice points projecting inside the
lens disk, sampled with the lens shown and hidden, the mean per-channel difference
is 7/255 with one point over 24 (the glass brightening under a point where it
refracts the neighbouring sphere) on both backends; with the partition switched
off in-page the same points differ by 51 on average, nine of them over 24, up to
207 — the glass's refracted image of the lattice painted over them. Those are the
thresholds `glass-refraction-partition.spec.ts` sits between.

## 4. Phases

| Phase | Scope | Unlocks | Cost |
| --- | --- | --- | --- |
| 1 — **delivered** | `material="physical"`, `roughness`, `metalness`, `clearcoat`, `clearcoat_roughness`, `iridescence`, `sheen`, `sheen_color`; default `RoomEnvironment` built lazily; Python validation; Layers-panel shows the physical knobs read-only; `mesh_physical_materials_example`; the A/B script | Metals, lacquer, pearlescent shells; a true Fresnel rim via `clearcoat` on a dark base | Small: one factory entry, one env builder, attrs plumbing |
| 2 — **delivered** | `transmission`, `ior`, `thickness`, `attenuation_*`, `dispersion` with three's stock pass; glass ordered first in its band on both backends; the physical knobs as LIVE Layers-panel sliders (§6 item 2); three glass spheres and a checkerboard backdrop in the demo | Glass and lenses that refract the background and other meshes; tuning a material without a rebuild | Small; the §3.4 caveat is in the Layers panel tooltip |
| 3 — **delivered** (opt-in) | `refract_data`: glass ranked LAST in its band, the `DataRefractionSplit` on both backends (glass depth pre-pass, data behind, glass — with a screen quad on WebGL — data in front), the per-fragment depth partition in every data shader (`uGlassPartition` / `uGlassDepth`, GLSL and TSL), `transmissionResolutionScale` 0.5 in pass B only, the transmitted alpha pinned to 1 on both backends (§3.4); a live Layers-panel switch; `mesh_glass_lens_example`; the `glass-refraction-partition` E2E spec | Glass that refracts the data behind it while the data in front of it stays crisp | Medium: one split module owned by `PostProcessingManager`, one `last` flag + two queries in the coordinator, a guard in ten fragment shaders, two shader hooks |
| 4 — **delivered** | `viewer_config.environment.source = room \| scene \| hdri` with `probe`, `resolution`, `intensity`, `url`; live exact cube capture on commit / slice / appearance change once settled; `luxar env bake` / `?bakeEnv` / `luxar env attach` storing `environment/faces-<digest>` (uint16 half bits) with an exact `scene_content_hash` guard, the group excluded from the scene digest (§3.3 Phase 4 notes); `mesh_reflections_example` | Metals and glass that reflect the data they sit in; zero-cost baked environments for published scenes | Small: one more builder behind `SceneEnvironment.ensure()`, one CLI pair, one Playwright driver |

## 5. Explicitly out of scope

- Physical materials on points, lines or splats. They are emissive primitives;
  the mesh is the only surface.
- Scene lights (`DirectionalLight` etc.). The environment is the light.
- Shadows.
- Replacing the house mesh shader. It stays the default: it is faster, has no
  environment dependency, and is what every existing scene renders with.
- Approximate environments computed from the resident arrays instead of rendered
  (emitter projection to an equirect, spherical harmonics from the data).
  Rejected in §3.3: they duplicate the appearance pipeline for a saving the
  exact capture does not need, since it is triggered rather than per frame.
- Depth writes for emissive point, line and splat layers so that glass can be
  occluded by data in front of it. It would break the additive sum those modes
  are (§3.4); the refraction split partitions the data by depth against the glass
  in the data shaders instead, which writes no depth.

## 6. Open questions

1. Should `material="physical"` force `opacity`-based transparency through
   three's `transparent` flag, or map Luxar `opacity` onto `transmission`? The
   former is literal and predictable; the latter is what "translucent glass"
   usually means. Proposal: literal, with `transmission` explicit.
   **Phase 1: literal.** `opacity < 1` (or per-vertex alpha without a cutoff)
   sets `transparent`; `transmission` stays a Phase 2 knob.
2. Does the Layers panel expose the physical knobs as live sliders (they map
   cleanly to `setLayer` patches) or read-only? Proposal: sliders in Phase 2
   once two demos exist to tune against. **Phase 1: read-only**, in place of
   the house shading sliders; Gamma and Blend hide too, since neither has a
   meaning on this material. Opacity stays live. **Phase 2: live sliders**, one
   per numeric knob from the shared knob table (ranges, steps and a log track
   for `attenuation_distance` whose top stop means "none"); the two colour knobs
   stay read-only rows; Reset restores the authored values. **Phase 3: a live
   "Refract data" switch** after the sliders, inert (with the reason) until
   Transmission is above 0; the per-row Reset restores the physical knobs and the
   switch (it had only ever reset the readouts).
3. Which demo carries Phase 1? Candidate: a bubble/lens marker variant of
   `esm3_protein_stories`, which already has the story dimension to switch
   marker styles on. **Phase 1: `mesh_physical_materials_example`** (a demo until
   Phase 3 moved the physical scenes to `packages/luxar/examples/`), a numpy-only
   row of icospheres (house shader, dark clearcoat shell around an emissive
   point cluster, gold, steel, pearl, velvet), because the stories demo was not
   on `main`. Switching one stories shell to `material="physical"` is a
   one-line change once it lands; the shared `luxar.mesh.primitives.icosphere`
   exists for it.
4. Should a scene-derived environment be computed from the arrays (compile time,
   approximate) or rendered (exact)? **Decided: rendered, exact**, on both the
   live path and the baked one (§3.3). An approximation buys nothing once the
   exact capture is triggered rather than per frame, and costs a second copy of
   the appearance pipeline. Compile-time baking exists only as
   `luxar env bake`, which drives the same exact capture headlessly.
5. Where do probes live — on the scene manager or on the node? **Decided: the
   probe is a knob of the environment config** (`"auto"` = scene centre,
   `[x, y, z]`, or `"node:<path>"`), so one implementation serves the showcase
   case and the marker-shell case; a per-node probe is a second capture, not a
   second mechanism. Whether several probes can be active at once (one physical
   mesh per probe) is left to Phase 4's first demo. **Phase 4: one probe per
   scene.** `mesh_reflections_example` puts the chrome sphere AT the probe (the
   scene centre) and the glass sphere beside it, which is exact where it matters
   and a small parallax error where it does not; a per-mesh probe stays a
   possible follow-up, not a need any demo has shown.
6. Is Phase 3 worth its intrusion? **Decided: as re-formulated in §3.4 it is not
   intrusive** (a renderOrder rule on WebGPU, a two-render split with a quad on
   WebGL, isolated in `pipeline.ts`), and its cost is paid only when a
   transmissive mesh is visible. What defers it is the correctness limit that
   emissive layers do not write depth, so data in front of a glass surface is
   painted over. **Phase 3: built, opt-in per mesh (`refract_data`)**, after a
   spike measured the cost (none) and the limit (real, visible) and found the
   alpha defect below. **The limit itself was then removed** (owner review of the
   first delivery: "when 'refract data' is on, it refracts even data in front of
   it?!"): the per-fragment depth partition in §3.4 draws the data in front of the
   glass crisp on top, on both backends. `mesh_glass_lens_example` is the lens.
7. What does the HDR framebuffer's alpha channel MEAN? **Decided: nothing — it is
   an overdraw count, and consumers must not read it.** The mega shader and the
   EXR capture already followed that rule; Phase 3 makes the physical glass follow
   it too (§3.4, the alpha finding). Redefining it as coverage is a possible future
   refactor of every emissive blend mode, not a Phase 3 prerequisite: with the
   clear alpha at 1 it would change no pixel the glass produces.