three-rs 0.3.0

A port of three.js core and its WebGPURenderer to Rust on wgpu, graded against three.js's own end-to-end pixel comparison.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
# API design note

The decisions issue #14 asked for, settled 2026-09-13 after the first outside
consumer (a native app drawing dendrograms on two planes) built three rungs
against the published 0.1.0. Each decision records its reason so it is not
reopened per pull request. Breaking changes ship together in 0.2.0.

## 1. The scene stays single-threaded, by design

Nothing in the scene graph is `Send` or `Sync`, and that is the design rather
than a 0.x limitation. three.js's graph is single-threaded and
`WebGPURenderer` never touches an `Object3D` off the main thread; the port
inherits that shape, and it is the shape of every renderer built on the same
model. Renderers that work across threads fall into two camps: flat entity
stores with a scheduler (Bevy, Unity DOTS), or one owner thread with a copy of
the scene handed to the renderer (Unreal's proxies, Godot's servers, Filament,
rend3). Sharing a pointer tree behind locks is the third option, and
OpenSceneGraph is the cautionary tale; its successor VulkanSceneGraph went
back to a single owner. three-rs is in the second camp.

Parallelism belongs beside the scene, not inside it: asset decoding, layout,
the SDF rasteriser, and a git or filesystem scan all run on other threads and
hand finished data to the scene thread. `wgpu` itself is thread-safe. A
compositor drives the scene from one thread and feeds it messages.

`Rc`, not `Arc`; `RefCell`, not `Mutex`. The compiler refuses to let a `ObjectRef`
cross a thread, which is the guarantee wanted.

## 2. A scene object is an `ObjectRef`, a newtype over `Rc<RefCell<Object3D>>`

0.1.0 spells the handle out as a type alias, `pub type Node =
Rc<RefCell<Object3D>>`, with the tree operations on an `Object3DNode` trait.
Two costs showed up in the first consumer and in six of the fourteen examples:
every user has to discover `use three_rs::core::Object3DNode` before
`light.add(&mesh)` compiles, and rustdoc prints the plumbing in every
signature instead of a type called `Node`.

0.2.0 makes `Node` a newtype with the trait's methods inherent, and
`Deref<Target = RefCell<Object3D>>` so `borrow()` and `borrow_mut()` keep
working. Every call site stays the same text, so the examples, the QUnit
ports in `tests/`, and the line-for-line correspondence with three.js that
the pixel grader depends on are untouched. `WeakNode` gets the same
treatment; `Rc::ptr_eq` becomes `Node::ptr_eq`.

Rejected: an arena of indices, the shape a Rust reviewer expects and what the
d3-hierarchy port uses. `docs/scene-graph.md` gives the reasons and they
still hold: every three.js method would gain an arena argument, objects live
outside any scene (cameras, the instance-mesh dummy, loaded glTF trees before
they are added), `attach()` across parents stops being expressible, and the
QUnit ports have no arena to pass. The arena earns its cost only under
decision 1's first camp, which this crate is not in.

0.3.0 renames the handle `ObjectRef` (#250). `Node` had been three.js'
word for the shader-graph node (`nodes::Node`, behind `NodeRef`) as well,
and `ARCHITECTURE.md` spent a paragraph on which one a sentence meant.
Every other `Rc` handle in the crate is already named `<Thing>Ref` after
the struct it points at: `NodeRef`, `SceneRef`, `CameraRef`, `SkeletonRef`,
`CurveRef`. `ObjectRef` over `Object3D` is that pattern; `core::Object`
beside `Object3D` would have read as two things that are one, and
`Object3DRef` buys nothing over the short form. `WeakNode` is
`WeakObjectRef`. The shader-graph `Node` keeps its name: three.js calls it
that, and so does all of `docs/nodes.md`. Call sites are unchanged apart
from the type name; most never spell it.

Users hold `ObjectRef` clones across frames; that is what every consumer does. The
parent link is `Weak`, the one place the port's ownership differs from
three.js: a child does not keep its parent alive, so a subtree removed and
not held is freed.

## 3. Keep three.js's shape wherever there is no real trade-off

- **Field access, not accessor layers.** `mesh.borrow_mut().position.y = -1.0`
  is the JavaScript with one extra call. A full getter and setter layer over
  `Object3D`'s public fields would hide the cell behind `update(|o| ..)`,
  which is `borrow_mut()` under another name, and would cost the ports their
  shape. Convenience setters are added one at a time where they clearly pay
  (`set_position`, light-specific passthroughs that avoid
  `light_mut().unwrap()`).
- **`Mesh::new(geometry, material)`** takes the material, as `new Mesh(
  geometry, material )` does. 0.1.0's `Mesh::new(geometry)` followed by
  `mesh.borrow_mut().mesh_mut().unwrap().material = Some(m)` is the ugliest
  line in every example and appears 22 times; `Line::new` and
  `LineSegments::new` already take the material. Breaking, 0.2.0.
- **Materials keep public fields and named constructors; no builders.**
  `MeshBasicNodeMaterial` has some 40 public fields and three.js's docs name
  them. Struct-update syntax already gives builder ergonomics:
  `MeshPhongNodeMaterial { shininess: 80.0, ..MeshPhongNodeMaterial::phong(c) }`.
  The named constructors (`phong`, `standard`, `line`, `sprite`) carry the
  per-kind defaults, which is where three.js's subclasses live.
- **Options structs are `#[non_exhaustive]`, built from `Default` or a
  constructor.** A struct that stands for one of three.js's options objects
  carries only the keys the ported pages read, so it gains a field whenever a
  rung needs one more, and with struct literals each of those was a break for
  every caller. That covers `PassOptions`, `RenderTargetOptions`,
  `RendererParameters` (one field today; `new WebGPURenderer()` takes a dozen),
  the blur `*Options`, `Billboarding`, `ExtrudeGeometryOptions`,
  `TextGeometryOptions`, `ReflectorParameters`, `OverrideNodes`, `Ktx2Support`,
  `RaycasterParams`, and sdf-text's `LayoutParams` and `BatchedTextOptions`.
  The fields stay public and `Default` holds three's defaults, so a caller
  writes `let mut options = PassOptions::default(); options.auto_clear_depth
  = false;`, the JavaScript object with its keys set one per line. That is the
  one form `#[non_exhaustive]` leaves open outside the crate: it forbids the
  literal and the `..Default::default()` update alike. A constructor is added
  only where a field has no default: `ComputeFlow::new( statements, count )`
  is three's `.compute( count )`, and `MaterialFlow::new( output, position )`
  the two nodes a hand-built flow must name. Structs callers only read — `Info`
  and its four count blocks, sdf-text's `TextRenderInfo` — are
  `#[non_exhaustive]` and nothing more. Materials keep the literal anyway.
  They are the construction surface of every example, where
  `..MeshPhongNodeMaterial::phong( c )` reads as the JavaScript does, and a
  field added to one is a breaking change taken at a minor release; that is
  the trade the bullet above made. Input events (`PointerEvent`, `WheelEvent`,
  `KeyEvent`) are DOM values rather than options and are left as literals too.
- **Lights, cameras and textures** take three.js's positional constructor
  arguments and expose the rest as fields or one-line setters, for the same
  reason.
  `LightProbe::new( sh, intensity )` returns a `ObjectRef`, as every other light
  does, and keeps its coefficients in the light's `sh` field. The addons that
  three.js writes as classes with static methods (`LightProbeGenerator`) are
  unit structs with associated functions, so the call reads
  `LightProbeGenerator::from_cube_texture( &cube )`. `CubeCamera` follows the
  cameras: it owns a `node` and its `render_target`, and its `update()` takes
  the renderer and the scene, as three's `update( renderer, scene )` does.
- **Rust names throughout**, with the three.js name in the doc comment. This
  is already how the crate is written (`set_rotation`,
  `matrix_world_needs_update`, `is_mesh()`); recorded so it is not reopened.
  It covers casing too (C-CASE): an acronym in a type, variant or trait name
  is one word, so three.js' `GLTFLoader`, `SRGBColorSpace` and
  `WebGPUCoordinateSystem` are `GltfLoader`, `ColorSpace::Srgb` and
  `CoordinateSystem::WebGpu`, as `HdrLoader`, `PmremGenerator`, `Ktx2Loader`,
  `MrtNode` and `FxaaNode` already were. Three kinds of name are not acronyms
  and keep their capitals: a dimension suffix (`Data3DTexture`,
  `TextureSource::Texture2D`), which a digit already splits and which would
  only get harder to read; an axis order (`EulerOrder::XYZ`), which is three
  one-letter axis names, as in glam's `EulerRot::XYZ`; and the glam-style
  vector types (`Type::UVec2`, `BVec3`), which are WGSL's `vec2<u32>` in the
  spelling Rust graphics code already uses. Error strings that quote
  three.js (`THREE.GLTFLoader: ...`) keep three's spelling.
- **One `ColorSpace`.** three.js' colour spaces are string constants shared by
  `ColorManagement`, `Color`, `Texture.colorSpace` and
  `renderer.outputColorSpace`, so the port has one enum for all four:
  `math::ColorSpace`, next to `ColorManagement`, re-exported at the crate root.
  `NoColorSpace` is a variant, as `''` is a constant, rather than `None` in an
  `Option`.
- **One `BufferAttribute`, typed by its array.** three's typed subclasses are
  constructors on one struct: `BufferAttribute::new( vec, item_size )` is the
  `Float32BufferAttribute` default, and `int8` / `uint8` / `uint8_clamped` /
  `int16` / `uint16` / `int32` / `uint32` / `float16( vec, item_size,
  normalized )` and `from_typed( TypedArray, … )` cover the rest, with
  `new_instanced` / `from_typed_instanced` for `InstancedBufferAttribute`.
  `array()` is the `Float32Array` as a `Ref<Vec<f32>>` and panics on any other
  kind, because nearly every caller wants floats and should not unwrap an
  enum to get them; `data()` is the `TypedArray` whatever its kind, and the
  `get_x` … `set_xyzw` accessors read and write `f64` through `normalized`
  and the typed array's store conversion, as three's do. An interleaved
  attribute is `BufferAttribute::interleaved( Rc<InterleavedBuffer>,
  item_size, offset, normalized )`, a view into a buffer that several views
  share and the renderer uploads once; `data_buffer()` reaches the buffer.
  `StorageBufferAttribute` is a handle a compute kernel writes through
  `storage( &attribute, ty, count )` and a geometry draws from after
  `.into()`, both on the same GPU buffer. The vertex input is declared in the
  attribute's own type over three's vertex format, so a normalized `Uint8`
  colour is `unorm8x4` into a `vec4<f32>` and a `Uint32` index a `vec4<u32>`;
  the table and the reasons are the module note on `core::buffer_attribute`.
- **`Scene` and the cameras own a `node` field** and are not `ObjectRef`s
  themselves. `Scene` adds `background`, `fog_node` and `override_material`;
  a camera adds its projection state. Both forward `add()`, `children()` and
  `update_matrix_world()` to their node, so both can sit inside the tree.

## 4. Surface hygiene

- `three_rs::testing` is `#[doc(hidden)]`. It holds the harness helpers
  (`write_png`, `three_js_dir`) that the examples, the viewer, the e2e tests
  and consumers' own graders use, so it stays public but out of the docs.
  Decision 11 is the audit of everything else that was public.
- Only things that touch the filesystem or the GPU return `Result`: the
  loaders, `Renderer::new`, `render()`. Constructors, geometry builders and
  the scene-graph methods stay infallible, as they are in three.js. Issue #9
  did the work of replacing the remaining panics under this rule; the shape
  it settled on is decision 5.

## 5. Errors: one enum per crate, panics only on invariants

Decision 4's rule needed a shape to land in; issue #9 gave it one.

- **One error enum per crate**, `three_rs::Error` and `sdf_text::Error`, both
  `#[non_exhaustive]` and both implementing `std::error::Error`. A caller who
  wants to know what failed matches on variants that name it (`NoAdapter`,
  `UnsupportedTrackType`, `Image { path, reason }`); a caller who does not can
  `?` the lot into `Box<dyn Error>` or `anyhow`. Rejected: a per-module error
  type, which makes every loader call site declare a `From`, and a single
  `Error(String)`, which is a panic with extra steps. glTF is the one nested
  enum (`Error::Gltf(GltfError)`), because fifteen distinct failures inside
  one file format would otherwise crowd out the rest of the crate.
- **Fallible means reachable from a caller's mistake or from the machine.**
  Anything that reads a file, decodes an image, parses JSON or a track name,
  asks for an adapter or a device, or takes a texture type that may have no
  format, returns `Result`. That is the loaders, `Renderer::new` /
  `with_instance` / `read_canvas_pixels`, `RenderTarget::new_with_options`,
  `DepthTexture::set_type`, `AnimationClip` and `KeyframeTrack` parsing, and
  `VectorFont::parse`.
- **Panics are invariants, and say which one.** Every remaining panic in
  library code is a statement about the crate's own state — "the light list
  only holds lights", "prepare_canvas() has just created the canvas" — and its
  message starts `three-rs:` (or `sdf-text:`) and names it. If one of these
  fires it is a bug in the crate, never in the call. A caller can therefore
  read the rule as: handle the `Result`s, and do not write a `catch_unwind`.
- **Infallible stays infallible.** Constructors, geometry builders and the
  scene-graph methods do not return `Result`, as decision 3 says; where a
  value must be checked, the check is on the setter that takes it
  (`DepthTexture::set_type`) rather than on the accessor that would have
  panicked later, so the failure surfaces at the call that caused it.
- **`Error` is not the renderer's return channel for wrong pixels.** Nothing
  in this crate reports a rendering difference as an error; the grader does
  that. `Error` is for what did not happen at all.

## 6. The renderer can be embedded in a host that owns the GPU

Settled 2026-09-14, after the second outside consumer: a Smithay/wgpu Wayland
compositor that imports client dmabufs as `wgpu::Texture`s, draws its scene
with three-rs and scans out to DRM. Three additions, all at the boundary
between the renderer and a host that already has a device and already has
textures.

- **`Renderer::with_device( parameters, adapter, device, queue )`.** The host's
  device, adopted. `Renderer::new` and `with_instance` now end in it, so there
  is one construction path. A `wgpu::Texture` belongs to the device it was
  created on, so a renderer that always made its own device could never sample
  an imported buffer — the alternative, handing the renderer an `Instance` and
  letting it pick, is `with_instance`, and it does not solve this. `Device` and
  `Queue` are refcounted handles, so the host keeps its own clones and goes on
  using them.

  The one capability question this raises is `FLOAT32_FILTERABLE`, which
  sdf-text's `r32float` atlas needs. With an adopted device the adapter's
  feature set says nothing about what was actually enabled, so the renderer
  reads `device.features()` and asserts at the point of use; the doc comment
  tells a host that wants sdf-text to request it.

- **`Texture::external( gpu, color_space )`** — three.js's `ExternalTexture`.
  Size and format come off the `wgpu::Texture` so they cannot drift from it;
  `own_gpu = false`, so the renderer samples the handle and never re-uploads,
  re-creates or destroys it. The machinery already existed for render targets
  (`Texture::render_target` + `set_gpu`, and `ensure_texture_2d`'s `own_gpu`
  short-circuit); what was missing was a constructor that ties the four facts
  together, since `set_gpu` alone leaves size, format and colour space to be
  set by hand and silently wrong if they are not. The colour space must agree
  with the format's transfer function and that is asserted, because the GPU
  applies the transfer on sample and a mismatch is a wrong-looking frame rather
  than an error.

- **`Texture::set_data( data )` / `set_needs_update()` / `version()`** —
  `texture.needsUpdate = true`. A texture whose pixels change every frame at
  the same size and format (a screencast frame, an shm client buffer) had no
  path but clearing the GPU handle, which threw away the allocation, the mip
  chain and every bind group built from it. The renderer's texture cache is now
  keyed on `( id, version )`, exactly as the program cache is keyed on
  `( material.id, material.version )`, and a bumped version writes the new
  bytes into the texture that is already there.

  `set_data` bumps the version itself rather than waiting for a separate
  `set_needs_update()`. three.js needs the flag because its data array is
  mutated in place behind the texture's back; here the setter *is* the
  mutation, so requiring a second call would only add a silent-stale-frame
  footgun. `set_needs_update()` stays for forcing a re-upload, and the name
  keeps the three.js correspondence. `set_data` panics on the wrong byte count
  and on a texture the renderer does not own.

- **`InstancedBufferAttribute::array()` / `array_mut()` / `set_needs_update()`
  / `version()`** — `attribute.needsUpdate = true`, for `instanceMatrix` and
  `instanceColor` (#89). The renderer keeps one GPU buffer per attribute and
  writes it only when the version moves, so the array is no longer a public
  field: a write that bypassed the version would be a stale frame. The same
  reasoning as `set_data` puts the bump in the writers: `array_mut()` always
  bumps, and `set_matrix_at` / `set_color_at` bump when the value they write
  differs from the one there, so an animation loop that re-sets unchanged
  matrices uploads nothing. three.js' `setMatrixAt` needs the flag;
  here it does not.

## 7. A material field the port does not read says so

`MeshBasicNodeMaterial` is one struct for every kind (decision 3), so a field
can be set on a kind whose flow never looks at it. Issue #171 audited every
public field against what `materials::setup()` and the pipeline read, and
settled each one that was silently ignored: either it is implemented, or it is
loud. Loud means the renderer prints `three-rs: material <id> (<kind>): <field>
is set but not supported, and is ignored` once per material when it builds
the program, and `MeshBasicNodeMaterial::check_supported()` returns
`Err(Error::Unsupported { field, kind })` for an application that would rather
fail before its first frame. `unsupported_fields()` lists them all.

The single source for what each kind reads is `MaterialKind::table()` in
`src/materials/fields.rs`: an exhaustive `match` that gives every kind its
fragment flow, the fields that flow reads, the fields it is loud about, and
the rules only a draw can judge. `materials::setup()` picks the flow and gates
the Basic environment map and the Physical extensions on it;
`unsupported_fields()` is the loud list filtered by what the material sets;
the renderer's warning adds the draw rules and the accessor-only maps under
one registry. A no-GPU test in the same file builds every kind with each field
set and checks that the program shows the field exactly when the table says
the kind reads it. The tables below summarise it; where they disagree, the
code wins. Before the table the flow was an `if`/`else` chain whose last arm
caught every kind it did not name, so Sprite, Points and Line2 were warned
that they ignore `env_map` and then sampled it (#253).

Implemented by the audit:

| Field | What reads it now |
|---|---|
| `depth_func` (new) | `RenderState` → `depthCompare`, as `_getDepthCompare()` maps `Material.depthFunc`. |
| `alpha_to_coverage` | the pipeline's `alphaToCoverageEnabled`, `&& sampleCount > 1` as in three. It used to be hard-wired off. |
| `emissive_node` on Phong, Lambert, Standard, Physical | `setupLighting()`'s `vec3( emissiveNode ?? materialEmissive )`. Only the Basic flow read it before. |
| `emissive_map` on Phong, Lambert | `MaterialNode.EMISSIVE`'s map multiply, as on Standard. |
| `clearcoat_map`, `clearcoat_roughness_map` (new) | `MaterialNode.CLEARCOAT` (× `.r`) and `.CLEARCOAT_ROUGHNESS` (× `.g`); `GLTFLoader` fills them from `clearcoatTexture` / `clearcoatRoughnessTexture`. |
| `clearcoat`, `clearcoat_roughness`, `clearcoat_normal_map` under a direct light | the direct clearcoat lobe in `PhysicalLightingModel.direct()`. The indirect lobe was already there; with a light in the scene the coat had no highlight. |
| `clearcoat_normal_scale` on a glTF primitive with no tangents | the derivative-tangent `.y` flip three applies to it as well as to `normalScale`. |
| `backdrop_node`, `backdrop_alpha_node` (new, #169) | `LightsNode.setup()`'s blend into `totalDiffuse` on Basic, Phong, Lambert, Toon, Standard, Physical and a custom `lighting_model`, and `setupLighting()`'s backdrop arm on an unlit material. A backdrop also puts the material in the transparent list. |

Loud:

| Field | On | Why |
|---|---|---|
| `env_map` | anything but Basic | The Basic flow's `BasicEnvironmentNode` is the only reader. Phong and Lambert wrap the same node in their own lighting model, which is not ported; a PBR material takes a PMREM through `pmrem_env` (or `scene.environment`) rather than a raw cube. |
| `pmrem_env` | anything but Standard / Physical | Only `PhysicalLightingModel` reads a PMREM. |
| `backdrop_node` | Normal | `MeshNormalNodeMaterial`'s flow packs the normal straight into the output, with no lighting step for the blend to sit in. |
| `anisotropy` | Physical, lit by a point, spot or directional light (a draw rule) | The anisotropic `BRDF_GGX` (`V_GGX_SmithCorrelated_Anisotropic`, `D_GGX_Anisotropic`) is not ported, so the direct highlight would be the isotropic one. The indirect bent normal is ported, which is why an unlit anisotropic page such as `webgpu_loader_gltf_anisotropy` is quiet. |
| `size_attenuation`, `size` without `size_node` | Points, drawn on a `Sprite` (a draw rule) | `PointsNodeMaterial.setupVertexSprite()` is ported for a `sizeNode` without size attenuation only. |

`light_map` and Phong's `specular_map` are read only by an accessor
(`material_light_map`, `material_specular_strength`) in a node the
application builds, not by any kind's own flow. The renderer says so once per
material; `check_supported()` passes them.

The table also records one known gap the other way. Three's
`MeshBasicNodeMaterial.setupNormal()` returns the geometry normal, so a Basic
material's normal and bump maps and `normal_node` never reach its env-map
reflect vector; the port's Basic flow reads the material normal there, so
they do. Basic's row declares them, with the deviation noted beside it.

Not fields, so nothing to be loud about: three.js properties the struct does
not have at all — `clippingPlanes` (`WebGLRenderer`-only in three; planes
come from a `ClippingGroup`), `sheenColorMap` / `sheenRoughnessMap`, `polygonOffset*`,
`dithering`. (`wireframe` and the scalar `alpha_test` are fields and are
honoured; `alpha_test_node` is the node form of the latter.)
Setting one is a compile error, which is louder than a log line. A field
three's own class for that kind lacks — `clearcoat` on a Standard material,
`shininess` on a Physical one — is ignored by three too and is not listed.
`scene.environment` is not applied to Phong or Lambert either, which is
three's behaviour: `NodeMaterial.setupEnvironment()`, which those kinds
inherit, reads only `material.envNode` / `material.envMap`.

## 8. Render-pipeline hooks take the renderer and nothing else

`RenderPipeline::on_before_render` and `on_after_render` take a
`Box<dyn FnMut(&mut Renderer)>`. A hook that has to move a camera captures
the camera itself, through `RenderCamera::set_view_offset` (issue #164). The
hook signature does not pass one in, because three's callbacks take no
arguments either. `docs/nodes.md` §37 has the ordering.

### TRAA's jitter is attached by the caller

Three's `TRAANode.setup()` reaches the pipeline through
`builder.context.renderPipeline`. It registers its jitter hooks there,
guarded by `renderPipelineState.viewOffsetOwner`. The port's nodes have no
pipeline handle while they build, and adding one to every node build would
put a `&mut RenderPipeline` in a path that only TRAA needs. So
`TraaNode::attach( &mut RenderPipeline )` installs the two hooks, and
`RenderPipeline::claim_view_offset()` is `viewOffsetOwner`. It returns true
once per pipeline, so a second TRAA node does not jitter again. Forgetting
`attach` costs anti-aliasing, not correctness: the output is the resolved
scene without jitter.

### Velocity's projection override is on the renderer

Three calls `velocity.setProjectionMatrix( m )` on the `VelocityNode`
singleton. Here the velocity history belongs to the renderer's
`NodeFrameState` (#154, decision 1), and `velocity()` builds a fresh node
each call. So the setter is `Renderer::set_velocity_projection_matrix(
Option<Matrix4> )`, where `None` is three's `null`. `docs/nodes.md` §62 has
the store.

## 9. The node enum opens through `Node::Custom`

`nodes::Node` is a closed enum, and an exhaustive `match` over it in the
builder is what tells a rung it has added something the generator cannot
emit. Issue #155 settled how user code gets node types of its own anyway:
one more variant, `Node::Custom(Rc<dyn CustomNode>)`, rather than trait
objects everywhere or a registry of kinds. A `CustomNode` has a
`type_name`, a `node_type`, an `is_cacheable` flag and a `setup(
&NodeBuilder ) -> NodeRef` that **composes existing variants and never emits WGSL of its
own**; a node that needs a new statement shape becomes a variant in the
crate, where the dump gates see it. `tsl::custom( node )` wraps one.
`tsl::context( node, ContextValue )` and `tsl::isolate( node )` (and the
`.context()` / `.isolate()` methods) are three's `ContextNode` and
`IsolateNode`; `ContextValue` holds string-keyed node values, the addon half
of `BuildContext` (#155 decision 6). `NodeBuilder::context( key )` is how a
`setup` reads them. `docs/nodes.md` §45 has the semantics.

All of this shipped in 0.1.x (#155 decision 3). Strictly, three new variants
on a public enum break a caller that matches on `Node` exhaustively; no
published consumer does, since they build graphs and hand them to the
builder, so the change was taken as additive. 0.2.0 marks `Node`
`#[non_exhaustive]` (decision 11), so that later variants are additive by the
rules and not only in practice. The pre-`context` spellings stay:
`range_fog_factor_with_view_z` and `density_fog_factor_with_view_z` build the
same WGSL as the `.context( { getViewZ } )` form.

## 10. Passes render themselves; their explicit `render()` is removed

`PassNode::render`, `RttNode::render` and `BloomNode::render` were
`#[deprecated(since = "0.1.3")]` and are removed in 0.2.0. The renderer runs
a pass from `updateBefore()`, the first time in a frame a draw samples the
pass's texture, as three does (`docs/nodes.md` §57). A pass holds its scene
and camera through `pass( scene, camera )` or `set_scene` instead of
borrowing them per call. The three methods stayed for one release, forwarding
to that path while they were 0.1.x public API and callers used them: each one
marked the pass done for the frame and rendered it, so an unconverted caller
got the frame it got before, rendered once. Every caller in this tree is
converted; `mark_update_before` and the `NodeFrameState::mark` it used, which
existed only for the forward, went with them.

The pass types became `Rc` handles to make this work, and their setters
take `&self`. Code that held them by value still compiles, because a handle
derefs to its state. `controls_and_camera` hosts take the camera as
`cameras::CameraMut`, because an example that shares its camera with a pass
can lend it only as a `RefMut`.

## 11. Public means three.js public, or documented here

Settled for 0.2.0 by the audit #14 asked for, which walked every reachable
public item in `three-rs`, `sdf-text` and `three-rs-controls` against three.js
(or troika, for `sdf-text`) and against who outside the crate uses it. Each
item landed in one of three places, by one rule each:

- **Public**: a three.js class, its non-underscore methods and properties, an
  exported TSL function or constant, or something a decision in this file
  designs. This is kept even where nothing calls it yet, because the port
  mirrors three.js' public API on purpose and the next rung will want it.
- **`#[doc(hidden)]`**: not API, but the examples, the tests, the viewer, the
  web shell or `dump_wgsl` genuinely reach it. These are three's private
  members that the WGSL and pixel gates inspect (`quad_material`,
  `NodeProgram::vertex_buffers`, `materials::setup` and its contexts), the
  readbacks and cache counters the grader asserts on (`read_target_pixels`,
  `material_cache_len`), and the oracle hooks the decoder tests compare with
  three's own output (`GltfLoader::accessors`, `loaders::meshopt`,
  `loaders::draco`). Like `testing` (decision 4) they carry no compatibility
  promise.
- **`pub(crate)`**: everything else. Setup-context plumbing, per-light uniform
  helpers keyed on the renderer's light index, render-list and render-state
  internals, texture GPU handles, three's `_`-prefixed members, module-local
  helpers three.js does not export. Items that turned out to be unused
  anywhere were deleted rather than hidden.

A `pub mod` whose every item is re-exported from its parent is private now
(`animation::animation_action`, `extras::curve`, `math::interpolant`,
`three_rs::error` and the like), so each type has one path. The long paths
were only ever used by the QUnit ports, which now import the short ones.
Modules that are namespaces in three.js (`extras::shape_utils`,
`math::math_utils`) or that hold items not re-exported stay public.

`#[non_exhaustive]` goes on the enums that mirror an open-ended three.js
concept of which the port has only part: `nodes::Node` (decision 9) and its
`Builtin`, `UniformSource`, `TextureSource` and `BufferSource`; `MaterialKind`,
`Payload`, `LightKind`, `Background`, `ToneMapping`; the texture `TextureType`,
`Mapping`, `ColorSpace` and `DataTextureData`; KTX2's
`EngineFormat`; `TrackInterpolant`, which has no Bézier arm yet; and
`sdf_text::TextAlign`, which has no `justify`. Each one gains variants as rungs
land, and a variant is additive only if callers were made to write the `_`
arm first. Enums whose three.js set is closed and fully ported (`Blending`,
`Side`, `Wrapping`, `ShadowMapType`, `EulerOrder`) stay exhaustive, because a
caller matching them exhaustively is right to. The same reasoning puts the
attribute on the structs that stand for a partly ported options object or
counts block; decision 3 says how those are built.

The Rust API Guidelines checklist (#37, folded into #14) was the rubric, and
only the items that cannot be fixed later without a break were acted on; the
rest are follow-up issues. One more was: `CurveVector` (and so `BezierVector`
and `LineVector`) is sealed (C-SEALED). It is the bound the generic curves put
on their point type, implemented for `Vector2` and `Vector3` as three.js'
curves are, and sealing it is what lets it gain a method later. `RenderCamera`
is sealed the same way, for the same reason: it is the render path's slice of
`Camera`, implemented for `ArrayCamera`, `OrthographicCamera` and
`PerspectiveCamera` only, and the trait gains a method as the render path
needs one rather than growing a new one beside it. The traits
users are meant to implement (`Curve`, `CustomNode`, `LightingModel`,
`NodeUpdate`, `UvGenerator`, `BindingTarget`, `TargetResolver`) stay open. The `get_` prefixes (`get_world_position`,
`get_size`) stay: they are three.js' `getX( target )` methods, which compute
rather than return a field, so C-GETTER does not apply and decision 3's
correspondence does. Handles and ids into a crate-owned table
(`NodeRef`, `RootId`, `ActionHandle`, `GeometryId`, `MaterialId`, ...) are
opaque: their fields are private, so the only way to get one is the
constructor or accessor the owning type hands out, and a caller can never
forge one that names a slot the table never allocated.

## 12. Events are typed enums, render callbacks are closure fields, and `Drop` is `dispose()`

three.js has one event mechanism, `EventDispatcher`: string-keyed listener
arrays on objects, materials, geometries, textures, render targets, the
animation mixer and the controls, with an untyped event object. The port has
no such trait (issue #153, option C). Each thing three dispatches on gets the
shape its events need:

- **The scene graph** dispatches a `SceneEvent`: `Added`, `Removed`,
  `ChildAdded(child)` and `ChildRemoved(child)`, the four events
  `Object3D` dispatches, which are the whole set. `ObjectRef::add_event_listener(
  SceneEventType, listener)` returns an opaque `ListenerHandle`, which stands
  for the listener in `remove_event_listener` and `has_event_listener`
  because a closure has no identity to compare. `ObjectRef::dispatch_event` copies
  the listener list before calling it, as three's `listenerArray.slice( 0 )`
  does, and holds no borrow during the calls: a listener may remove itself or
  any other listener, borrow its node, or change the tree, which dispatches
  again. A listener is `Fn(&SceneEvent, &ObjectRef)`, the second argument being
  three's `event.target`; `Fn` because of that re-entrancy, and the target is
  passed in so a listener need not capture, and so keep alive, its own node.
  `add()` and `attach()` dispatch `Added` on the child and then `ChildAdded`
  on the parent, once the link is made (and, for `attach()`, after the world
  matrix update); `remove()`, and so `clear()` and `remove_from_parent()`,
  dispatch `Removed` and then `ChildRemoved` once it is broken. The listeners
  are a public field of opaque type, `Object3D::listeners`, so `Object3D {
  .., ..Default::default() }` still builds outside the crate; `Clone` does
  not copy them, as three's `copy()` does not.
- **The animation mixer** queues a `MixerEvent`: `Loop { action,
  loop_delta }` and `Finished { action, direction }`, the two events
  `AnimationAction._updateTime` dispatches on the mixer, with three's
  `action` as the `ActionHandle` and `loopDelta` / `direction` as the `f64`s
  three computes. `AnimationMixer::update()` clears the queue and refills it
  in three's dispatch order; the caller drains it with `take_events()` on the
  next line, so `mixer.addEventListener( 'finished', ... )` becomes a loop
  over `take_events()` after each `update()`. A queue rather than listeners
  because the caller already polls `update()` once a frame, because the
  mixer is borrowed mutably throughout `update()` so a listener could not
  reach it to `play()` or `fadeIn()` the next action (what three's listeners
  usually do), and because it needs no `ListenerHandle`. The cost is timing:
  three's listener runs inside `update()`, here the response runs after it,
  so a change it makes is first seen by the next `update()`. Clearing on
  `update()` keeps a caller that never drains from growing the queue, and
  matches three, where an event with no listener at dispatch time is gone.
- **`dispose`** is `Drop`. A texture, render target or geometry is an `Rc`
  handle and the renderer frees what it made for it once the last handle is
  gone (`docs/scene-graph.md`, "Identity and eviction"); a material ages out.
  `dispose(self)` on `Texture`, `CubeTexture`, `DataTexture`,
  `Data3DTexture`, `DataArrayTexture`, `DepthTexture`, `CubeDepthTexture`,
  `RenderTarget`, `CubeRenderTarget` and `MeshBasicNodeMaterial`, and
  `dispose(self: Rc<Self>)` on `BufferGeometry`, are documented no-ops that
  consume the handle, so three.js code ports line for line.

Why not a string-keyed `EventDispatcher` trait: the event sets are closed and
small, the data each event carries differs, and the one place three's
dispatch does real work — the renderer releasing GPU memory on `dispose` —
is already done by `Rc` counts with no call to forget. A string dispatcher
would trade a compile error on a misspelt event or a wrong payload for a
listener that silently never fires, and give every listener a `dyn Any` to
downcast. A typed enum keeps three's names, one variant per event, and
gains a variant if three's set grows.

**Render callbacks** are `Option<Box<dyn ...>>` fields, set by assignment
or by a `set_on_before_render` / `set_on_after_render` that spares writing
the closure's argument types.

- `Object3D::on_before_render` / `on_after_render` are an
  `ObjectRenderHook`: `FnMut(&ObjectRef, &Renderer, &Scene, &dyn RenderCamera,
  Option<&Group>)`. three passes `( renderer, scene, camera, geometry,
  material, group )` with the object as `this`. The object comes first, as
  its unborrowed `ObjectRef`: the renderer takes the hook out of the object for
  the call, so the hook can borrow its own node or any other, and puts it back
  unless the hook installed a replacement. The geometry and material are on
  that node's payload. The renderer is `&Renderer`, not `&mut`: the hook runs
  inside a render, and the port records a pass's draws only after every
  before-hook of the pass has run, so a hook cannot draw or start a render.
- `Scene::on_before_render` / `on_after_render` are a `SceneRenderHook`:
  `Fn(&Renderer, &Scene, &dyn RenderCamera, Option<&RenderTarget>)`, three's
  `( renderer, scene, camera, renderTarget )`. The target is the one the
  scene is drawn into: the internal framebuffer target when one is used, else
  the renderer's render target, so `None` is the canvas. `Fn`, not `FnMut`,
  because the renderer holds the scene shared: a pass or a reflector renders
  it again from inside its own render. The scene root's `Object3D` hooks are
  never called; three calls an object's hook per draw, and the root is not
  drawn.

The renderer calls them in `Renderer._renderScene()`'s order, on every scene
render, including those passes and reflectors make: the scene's before-hook
after the scene's and camera's matrix updates and before the projection; each
drawn object's before-hook once per render item, after the cull and the
render-object filters (OIT, the outline selection) and once for both halves
of a split `DoubleSide` draw; the draws, and the output pass if any; each
object's after-hook; the scene's after-hook. Two differences from three
follow from recording the pass afterwards. Every before-hook runs before any
draw, where three interleaves them with the draws. A change a hook makes to
the transform is seen next frame, as in three, because the draw uses the
world matrix computed before it; a change to the material is seen this frame.
The shadow passes draw from their own list and call no hooks, where three's
`renderer.render()` of the shadow camera would.

## 13. The renderer forgets what it has not drawn for four frames

The contract, for a consumer: **anything the renderer has not drawn for four
frames is forgotten, and the next render that draws it builds it again from
scratch.** Draw a thing at least every fourth frame and it stays warm; draw it
less often and each of its renders pays for a cold build.

"Frame" is the renderer's frame clock, three's `NodeFrame.frameId`
(`Renderer::node_frame()`), not the number of `render()` calls. A frame closes
on a render to the screen, and every render into a render target before that
(a pass's scene render, SSAA's eight samples) belongs to it. The window is
`CACHE_GRACE_FRAMES` in `src/renderer/mod.rs`.

What is forgotten is everything the renderer caches under the id of a value it
does not own, and so cannot ask whether that value is still alive: a
material's built node programs (`node_builder_states`), node-owned buffers
such as a `range()` fill (`buffers`), each draw's uniform, bone and morph
buffers (`slot_buffers`), texture views (`views`) and bind groups
(`bind_group_cache`). Once no surviving material state names a compiled
program for the same window, the program and its pipelines go too. What is
*not* forgotten is what the renderer can watch die: geometries and textures
are evicted by a `Weak` strong count when the consumer drops them, however
long they sit unused (`docs/scene-graph.md`, "Identity and eviction").

Who notices: a thumbnail rendered once and then again later, a preview
refreshed on demand, a secondary view updated on a timer, a second scene
drawn every fifth frame. Each of those renders rebuilds its programs,
buffers and bind groups. `steady_frame_builds_nothing` cannot see it,
because it renders every frame; `renderer.info().build` can, by counting
what the render built.

Why not zero: a consumer that renders two scenes, or one scene from two
cameras, in alternating frames would evict each one's materials on the
other's frame and rebuild them every time. Why four: it tolerates a handful
of interleaved scenes and passes while bounding the maps at a few frames'
worth of churn. A steady frame touches every entry, so it evicts nothing and
builds nothing, whatever the window.

Issue #249 offered two other answers, and both stay open if a consumer's
cadence makes this contract hurt. One is a configurable window
(`Renderer::set_cache_grace_frames`, or a builder option): cheap, but still
frame-based, so the consumer has to know their own cadence. The other keys
eviction on liveness instead of age, as `geometries` and the texture maps
already do: a material state holding a `Weak` on its material would go when
the consumer drops the material, not when it pauses, which removes the
contract altogether at the cost of giving materials a liveness signal.
Either can keep four frames as the default, so neither need break a
consumer that relies on this one.

## Where each decision came from

Decision 13 is issue #249's option 1: the window the renderer already had,
written down as a contract.

Decision 12 is issue #153's option C and its maintainer decisions, built in
#159; the mixer's event queue was built in #326.

Decision 11 is the last of issue #14 (with #37).

Decision 10 is issue #162.


Decision 8 is #155's design note and its decisions 1, 2, 3 and 6, built in
#161.

Decision 6 came out of the compositor consumer and issue #62; the gaps it
closes were found by trying to build the compositor's scene against 0.1.2.

Decisions 1 and 2 came out of the plane-dendro consumer test and a
conversation about which renderers are multi-threaded and how. Decision 3 is
the port's founding discipline restated for the public API. The consumer
gaps that test produced (undocumented windowed path, silent frustum culling
of text, per-frame program rebuild) are filed as their own issues; they are
about missing pieces and performance, not about the shape above.