@opsydyn/effect-three 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+## 0.1.0 (2026-10-18)
+
+### Features
+
+- **effect-three-foldkit:** Foldkit adapter with WebGL renderer and browser tests ([5e2816d](https://github.com/opsydyn/fold-kit-experiments/commit/5e2816d4a46138777db0cb656a9c3436328c8be4))
+- **effect-three:** a rigid body per instance ([cc39435](https://github.com/opsydyn/fold-kit-experiments/commit/cc39435b878c781c7bf35e00e4b50ddc6d92b035))
+- **effect-three:** a WebGPU renderer ([94a0964](https://github.com/opsydyn/fold-kit-experiments/commit/94a0964c723c9c8bea555a0054d52c2224fcc00c))
+- **effect-three:** after R5 — WebGPU, render kits, glide, physics groups, XR spaces ([e5bde71](https://github.com/opsydyn/fold-kit-experiments/commit/e5bde71212353879d74aa32567c3eb9cbbeb38ac))
+- **effect-three:** animation clips on borrowed objects ([719e73e](https://github.com/opsydyn/fold-kit-experiments/commit/719e73ed8053ba60ff1ecf7902d89735c1d74e31))
+- **effect-three:** basic, lambert, phong, standard, physical and normal materials ([5baa690](https://github.com/opsydyn/fold-kit-experiments/commit/5baa690ef51dce7c1ae9ea53cfc0b6c70b9565c3))
+- **effect-three:** benchmarks, API reports, package checks and CI browser tests ([5640b2d](https://github.com/opsydyn/fold-kit-experiments/commit/5640b2dc2a078642f15f157fa77b491e1443305d))
+- **effect-three:** bodies on groups and loaded models ([b06179c](https://github.com/opsydyn/fold-kit-experiments/commit/b06179c4baa878fb65dc2f15a43a3e275b7bf682))
+- **effect-three:** borrowed objects and lent textures ([6e4c010](https://github.com/opsydyn/fold-kit-experiments/commit/6e4c010bc21da24aadea61bee76b3a39963cda4a))
+- **effect-three:** camera auto-rotate, and damping for view cameras ([c563b69](https://github.com/opsydyn/fold-kit-experiments/commit/c563b697753d8d2c0eed05ecfc935ad0d48f693a))
+- **effect-three:** close the parity gaps and prepare the packages for npm ([994fe5d](https://github.com/opsydyn/fold-kit-experiments/commit/994fe5dd640583c787746a95e8465d8f051d78df))
+- **effect-three:** colliders of a body's own, motors, contact forces and debug lines ([2a16c9e](https://github.com/opsydyn/fold-kit-experiments/commit/2a16c9e0f8432872e008bbd747eede1472c6ba44))
+- **effect-three:** collision groups and colliders named in collisions ([9531a01](https://github.com/opsydyn/fold-kit-experiments/commit/9531a01f54e9e19b8ccc301152167d0ac52c3229))
+- **effect-three:** declarative, diffed instancing ([26f70b3](https://github.com/opsydyn/fold-kit-experiments/commit/26f70b3ea5f20d5d4c33e36d3056bb15d2053334))
+- **effect-three:** demo app, package builds and visual tests ([1649d49](https://github.com/opsydyn/fold-kit-experiments/commit/1649d496c3387eb63233665da4ccc6e1def2aa64))
+- **effect-three:** Drei's shader grid, centring and environment presets ([a9467c7](https://github.com/opsydyn/fold-kit-experiments/commit/a9467c7580e24c0e93ee6742bb71ebd1da08a5e5))
+- **effect-three:** eased transitions and sphere, plane and cylinder geometry ([26187f1](https://github.com/opsydyn/fold-kit-experiments/commit/26187f12e8ffed91993802c0128e2be03ea3ba41))
+- **effect-three:** Effect runtime with scoped scenes, frame source and pointer events ([e7dec61](https://github.com/opsydyn/fold-kit-experiments/commit/e7dec61ce9fa57594fe606f9453a3115566a4cf8))
+- **effect-three:** environment lighting and a shadow catcher ([023d2de](https://github.com/opsydyn/fold-kit-experiments/commit/023d2dedc8ab7b6a46a6ef23a1dc0f364af80816))
+- **effect-three:** event bubbling paths, interactive groups and drag capture ([546a946](https://github.com/opsydyn/fold-kit-experiments/commit/546a94631923532bf5c11ff5b4ad7b19be64195e))
+- **effect-three:** every hit carries the pointer's world-space ray ([a7b3a46](https://github.com/opsydyn/fold-kit-experiments/commit/a7b3a46aa09eecaa04d7c73158b5fbf388a12cb6))
+- **effect-three:** frame-rate monitoring and render resolution ([64f9027](https://github.com/opsydyn/fold-kit-experiments/commit/64f902794d58bc5ef7bfbb19c0e2cbfa753e6f8b))
+- **effect-three:** full pointer event set with R3F semantics ([d9c6366](https://github.com/opsydyn/fold-kit-experiments/commit/d9c6366931c5e6c7414ce3a4a04bd1ef8da6b019))
+- **effect-three:** headless core kernel with property-tested keyed reconciliation ([a579695](https://github.com/opsydyn/fold-kit-experiments/commit/a5796951fc9545236a360ad62dc50c523c017b8c))
+- **effect-three:** HTML overlays at points in the scene ([d0d016f](https://github.com/opsydyn/fold-kit-experiments/commit/d0d016f1896eb05927f154b0941662b7afc6112e))
+- **effect-three:** immersive sessions (WebXR) ([9e003d1](https://github.com/opsydyn/fold-kit-experiments/commit/9e003d125813e2ce72477fd544242bc5b03cac73))
+- **effect-three:** joints, and bodies no longer remade by rounding ([66ebf4d](https://github.com/opsydyn/fold-kit-experiments/commit/66ebf4d0a4bcd580699e9a7f371919397e95585c))
+- **effect-three:** label colour ranges, curves, materials and layout ([ad9942e](https://github.com/opsydyn/fold-kit-experiments/commit/ad9942e49a540ab346a62fa00481c8c4d40ede11))
+- **effect-three:** lent geometries and XR detected meshes ([832388b](https://github.com/opsydyn/fold-kit-experiments/commit/832388bbe6833d248d1d437f01c6e1a31aba08ce))
+- **effect-three:** multiple views into one canvas ([b732a7c](https://github.com/opsydyn/fold-kit-experiments/commit/b732a7c4b6ddb50f846f71d4fa4401786a76d2a3))
+- **effect-three:** orbit controls as data ([067af99](https://github.com/opsydyn/fold-kit-experiments/commit/067af99a443c1c3000bfb3e424ae43e5995366d0))
+- **effect-three:** orthographic camera ([ac05a7e](https://github.com/opsydyn/fold-kit-experiments/commit/ac05a7e60307150e7707533b9ee14457ec5110ab))
+- **effect-three:** physics as data, simulated by Rapier ([dd99e1c](https://github.com/opsydyn/fold-kit-experiments/commit/dd99e1cbde789e5b578ec6b28278893e5725b326))
+- **effect-three:** post-processing effects ([1e2aa60](https://github.com/opsydyn/fold-kit-experiments/commit/1e2aa60533696b4db9158fd3de5d978bc601a063))
+- **effect-three:** registered behaviours as data ([68eef53](https://github.com/opsydyn/fold-kit-experiments/commit/68eef530b7f43cb59ac45822064b0d1518887cc4))
+- **effect-three:** render frames on demand ([9df4a06](https://github.com/opsydyn/fold-kit-experiments/commit/9df4a06adc9493a64fd0ef183e562c06568285fd))
+- **effect-three:** render textures as data ([cbc5f3d](https://github.com/opsydyn/fold-kit-experiments/commit/cbc5f3d54a844ea623c28b9223a0561586771737))
+- **effect-three:** scaffold Effect-native Three.js packages with Phase 0 ADRs ([02fa947](https://github.com/opsydyn/fold-kit-experiments/commit/02fa9476801e8609e311174023016b262e108427))
+- **effect-three:** shadows and scene render settings ([4140595](https://github.com/opsydyn/fold-kit-experiments/commit/41405952fbe709ab6453f51b9cfd53b7e1adb40e))
+- **effect-three:** sky and grid staging ([03e9f4f](https://github.com/opsydyn/fold-kit-experiments/commit/03e9f4f5c81a6dbe2a0e29720f768380ff86e737))
+- **effect-three:** stage lighting as scene parts ([8686f13](https://github.com/opsydyn/fold-kit-experiments/commit/8686f13da31425c49e8d9f73e0baf78b0ce82eb2))
+- **effect-three:** text geometry from lent typeface fonts ([c573453](https://github.com/opsydyn/fold-kit-experiments/commit/c573453ae3acef5356a184eb3030495ed08389af))
+- **effect-three:** torus, cone, capsule, ring and circle; point, spot and hemisphere lights ([3d695fe](https://github.com/opsydyn/fold-kit-experiments/commit/3d695fe6f9d85ffd70e3762dcdf586ce7cbb94de))
+- **effect-three:** update telemetry, shared samples package and apps/web samples ([f7cd64d](https://github.com/opsydyn/fold-kit-experiments/commit/f7cd64da19496e6137d8daa669ada99cae01d546))
+- **effect-three:** XR controllers, and VR in the toybox ([861f008](https://github.com/opsydyn/fold-kit-experiments/commit/861f0082819ad3b1898be9e86dd9c537de637cee))
+- **effect-three:** XR hover and drag, hands, sticks, AR surfaces ([35597b9](https://github.com/opsydyn/fold-kit-experiments/commit/35597b937b2721b823040b2c67468d6ab9224fd0))
+- **effect-three:** XR spaces, anchors, planes and DOM overlay ([0041c7c](https://github.com/opsydyn/fold-kit-experiments/commit/0041c7c9ebbe066f2c2300ae23283dfa68cc7451))
+- **effect-three:** zoom to cursor, arrow keys and camera fitting ([e14224b](https://github.com/opsydyn/fold-kit-experiments/commit/e14224b5dc11ac1d371ce1061ad41ca73879fc6f))
+
+### Performance Improvements
+
+- **effect-three:** reconcile 1,000 unchanged meshes in about 95 µs ([1069d8a](https://github.com/opsydyn/fold-kit-experiments/commit/1069d8a1a9cbd344eb6d59fd6dc290d5c436f121))

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alan P Currie
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,192 @@
-# Temporary Holding Version
+# @opsydyn/effect-three
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Declarative Three.js scenes with Effect owning every lifetime: GPU resources, renderers, frame subscriptions and event queues are acquired in a `Scope` and released when it closes. Scenes are plain data, so they can be derived from an application model, diffed and tested without a browser.
+
+The core is independent of any UI framework and of the DOM. For Foldkit, use [`@opsydyn/effect-three-foldkit`](../effect-three-foldkit/README.md).
+
+> Status: `0.x` (see [Stability](#stability)). The API is documented in [`etc/effect-three.api.md`](etc/effect-three.api.md).
+
+```sh
+npm install @opsydyn/effect-three effect three
+```
+
+## Describe a scene
+
+```ts
+import {
+  ambientLight,
+  box,
+  directionalLight,
+  mesh,
+  scene,
+  sharedGeometry,
+  sharedMaterial,
+  spin,
+  standard,
+} from '@opsydyn/effect-three';
+
+const description = scene({
+  resources: {
+    geometries: [{ id: 'cube', geometry: box() }],
+    materials: [{ id: 'paint', material: standard({ color: 0x14b8a6 }) }],
+  },
+  children: [
+    ambientLight({ key: 'ambient', intensity: 0.4 }),
+    directionalLight({ key: 'sun', position: [3, 4, 5] }),
+    mesh({
+      key: 'cube',
+      geometry: sharedGeometry('cube'),
+      material: sharedMaterial('paint'),
+      rotation: spin({ axis: 'y', radiansPerSecond: 1 }),
+      interactive: true,
+    }),
+  ],
+});
+```
+
+- **Keys are unique across the whole scene.** A node keeps its three.js object while its key and kind stay the same, including when it moves to another group. A different kind under the same key replaces the object in place.
+- **Descriptions are fully specified data.** The constructors fill in defaults, and nothing in a description is a closure or a three.js object.
+- **Shapes:** `box`, `sphere`, `plane`, `cylinder`, `torus`, `cone`, `capsule`, `ring` and `circle`, owned by one mesh or shared through `resources`. Parameter names and defaults are three.js's own.
+- **Materials:** `basic`, `lambert`, `phong`, `standard`, `physical` and `normalMaterial`, each with opacity, transparency, `side`, wireframe and (lit kinds) flat shading and emission. Defaults are three.js's own. Changing a material within its kind updates it in place; changing its kind replaces it.
+- **Shadows and render settings:** `scene({ render: renderSettings({ shadows: 'soft', toneMapping: 'aces' }) })`, then `castShadow`/`receiveShadow` on meshes and `castShadow` on directional, point and spot lights. Tone mapping defaults to `none` (React Three Fiber defaults to ACES) so colours render exactly as given.
+- **Instancing:** `instances({ key, geometry, material, instances: [instance({ key, position, color })] })` draws many copies in one call. Updates rewrite only the instances that changed, and hits name the instance (`instance` on the event).
+- **Views:** `scene({ views: [view({ key: 'front', camera, rect: { width: 0.5 } }), ...] })` draws several cameras into parts of one canvas; picks use the view under the pointer and report it as `view`.
+- **Post-processing:** `renderSettings({ effects: [bloom({ strength: 1.5 }), vignette()] })` applies three.js's composer passes in order (`bloom`, `vignette`, `film`); with no effects the scene renders straight to the screen.
+- **Render textures:** `scene({ renderTextures: [renderTexture({ id: 'screen', camera, children })] })` draws a little scene of its own into a texture that any material uses with `map: 'screen'`; it redraws only when its scene changes.
+- **Orbit controls:** `scene({ gestures: 'scene', camera: model.camera })` claims drags, wheel and pinches from the page and reports each as a `Gesture`; `orbit(model.camera, gesture)` returns the next camera, as three.js's `OrbitControls` would move it. A camera's `damping` eases the rendered camera there (a view's too), and `autoRotate` turns it round its target until a gesture, which an `AutoRotated` event precedes: keep it with `autoRotated(model.camera, detail)`. See [ADR-006](../../docs/effect-three/adr/006-controls-as-data.md).
+- **Fitting:** `scene({ measure: ['model'] })` reports the node's world box as a `Measured` event whenever it changes; `fitCamera(camera, box, area)` frames it as Drei's `Bounds` does, and `orbitKey` moves the camera for arrow keys.
+- **HTML overlays:** `overlay({ key: 'tag', node: 'cone', position: [0, 1, 0], center: true })` is a point the scene places after every drawn frame, as Drei's `Html`; the Foldkit view's `overlays: [{ overlay, content }]` moves Model-rendered HTML there.
+- **Text:** `text({ text: 'Hello', font: 'inter', depth: 0.2 })` is extruded (or, at depth 0, flat) text from a typeface JSON font lent with `store.lendFont` (`assets.loadFont` in Foldkit), as Drei's `Text3D`, with `letterSpacing`, `lineHeight` and `align` applied (three ignores them).
+- **Labels:** `label({ key: 'title', text: 'Hello', font: '/inter.woff', fontSize: 0.5 })` is crisp distance-field text at any size, as Drei's `Text`: wrapping (`maxWidth`), anchors, alignment, spacing, outlines, coloured runs (`colorRanges`), curving (`curveRadius`) and a scene `material` to light it; measured (`scene({ measure })`), it reports its laid-out size as `LabelMeasured`. Pass an engine (`troikaLabels()` from `@opsydyn/effect-three-troika`); fonts are TTF, OTF or WOFF (troika 0.52 cannot read WOFF2).
+- **Staging:** `scene({ environment: environment(), sky: sky() })` adds image-based lighting (three's `RoomEnvironment`, or a lent panorama with `map`) and a daylight sky, as Drei's `Environment` and `Sky`; `grid({ key })` draws three's `GridHelper`, `contactShadows()` draws Drei's soft ground shadows, and `shadowMaterial()` shows only the shadows cast onto it.
+- **Stage:** `const { lights, contactShadows, environment } = stage({ radius: 1.2, height: 2 })` is Drei's `Stage` lighting (presets `rembrandt`, `portrait`, `upfront`, `soft`) for content centred on the origin; spread the parts into `scene`. Measure the content (`scene({ measure })`), place it at `centerOffset(box)` (Drei's `Center`), light it with `stage(stageBounds(box))` and frame it with `fitCamera`.
+- **Grids and presets:** `shaderGrid({ key, infinite: true })` is Drei's fading shader `Grid`; `environmentPresetUrl('sunset')` is one of Drei's ten environment HDRs, for `assets.loadEnvironment`.
+- **Physics:** `mesh({ body: body({ collider: 'ball', restitution: 0.6 }) })` under `scene({ physics: physics() })` makes a rigid body the simulation moves; kicks are `impulse: { id, impulse }`, applied once per id, and collisions arrive as `Collision` events. Bodies sit on groups, models and instances too, take colliders of their own (`colliders: [capsuleCollider(…)]`) and report `ContactForce` over a threshold; joints (with motors) go in `physics({ joints })`, and `physics({ debug: true })` draws the colliders. Pass an engine (`loadRapier()` from `@opsydyn/effect-three-rapier`) to the scene graph or the Foldkit environment. See [ADR-007](../../docs/effect-three/adr/007-physics-as-a-pose-source.md).
+- **XR:** `scene({ xr: xr({ origin: [0, 0, 4] }) })` lets a scene be presented in a WebXR session; in Foldkit, run `environment.xr.enter('immersive-vr')` from a click's Command. The session drives frames, the player stands at `origin`, and controllers and hands hover, click and drag along their rays. Thumbsticks arrive as `XrStick` events (`locomote(model.xr, stick)` snap-turns and steps), buttons as `XrButton`, and in AR with `xr({ hitTest: true })` a select reports the real surface it met (`XrSurface`). `xr({ glide })` glides with the sticks and reports `XrMoved`. `group({ follow: jointSpace('right', 'index-finger-tip') })` rides a tracked space (also `headSpace()`, `controllerSpace(hand)`, `anchorSpace(id)`, `planeSpace(id)`), hidden while it is not tracked; `xr({ anchors: [xrAnchor({ id, position })] })` anchors places in the room, `xr({ planes: true })` reports detected planes as `XrPlanes`, `xr({ meshes: true })` detected meshes as `XrMeshes` (draw one with `mesh({ geometry: xrMesh(id) })` in a group following `meshSpace(id)`), and `xr({ domOverlay: true })` overlays the scene's element. See [ADR-008](../../docs/effect-three/adr/008-immersive-sessions.md).
+- **Cameras:** `perspectiveCamera({ fov })` or `orthographicCamera({ zoom })`. As in React Three Fiber, an orthographic frustum follows the viewport in CSS pixels, with `zoom` in pixels per world unit.
+- **Lights:** `ambientLight`, `directionalLight`, `pointLight`, `spotLight` (aimed at a world-space `target`) and `hemisphereLight`, with three.js defaults.
+
+## Run it
+
+```ts
+import { Effect, Layer } from 'effect';
+import { FrameSource, ResourceRegistry, SceneRuntime } from '@opsydyn/effect-three';
+
+const program = Effect.gen(function* () {
+  const handle = yield* SceneRuntime.make({ scene: description, renderer, viewport });
+  yield* handle.update(nextDescription); // diff and apply; equal scenes cost no host changes
+  handle.pointer({ _tag: 'PointerDown', x: 0, y: 0, button: 0 }); // normalised device coords
+  // handle.events: Stream of PointerEnter | PointerMove | PointerLeave | PointerDown | PointerUp
+  //   | Click | DoubleClick | ContextMenu | Wheel | PointerMissed | Drag | DragEnd | Gesture
+}).pipe(Effect.scoped);
+
+const environment = Layer.mergeAll(ResourceRegistry.layer, FrameSource.layer(scheduler));
+```
+
+- `renderer` is a `RendererFactory`: a plain object whose `create()` returns a renderer bound to one drawing surface. The WebGL2 implementation lives in the browser adapter. A WebGPU one can be added without touching the core.
+- `FrameSource.layer(scheduler)` takes any `FrameScheduler`: `requestAnimationFrame`, three's `setAnimationLoop`, or `createManualFrames()` in tests.
+- Pointer events follow React Three Fiber's semantics: click, double-click and context menu go only to the mesh that was pressed; a click that hits nothing and moves at most 2 CSS pixels is a `PointerMissed`. Hits carry the key, world-space point, distance, face normal and uv.
+- `make` is atomic. If the description is invalid (`InvalidScene`), the renderer can't be created (`RendererUnavailable`), or startup is interrupted, everything already acquired is released before it returns.
+
+## Resource ownership
+
+| Mode   | Declared as                                                              | Lifetime                                                                                                                                                                                                                                                                    |
+| ------ | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Owned  | `geometry: box(...)`, `material: standard(...)`                          | Created for one mesh, disposed with it. Owned material changes are applied in place.                                                                                                                                                                                        |
+| Shared | `sharedGeometry(id)`, `sharedMaterial(id)` plus a `resources` definition | Created on first use, reference-counted across every scene using the same `ResourceRegistry`, disposed when the last user releases it. Changing a shared material updates it in place; changing a shared geometry swaps a new one onto every user and disposes the old one. |
+
+Borrowed objects, textures and geometries are the application's own: lend them to the store and the library shows them but never disposes them.
+
+```ts
+const withdraw = store.lend('car', gltf.scene); // then: borrowed({ key: 'car', id: 'car' })
+store.lendTexture('bricks', texture); // then: standard({ map: 'bricks' })
+store.lendGeometry('terrain', geometry); // then: mesh({ geometry: lentGeometry('terrain'), ... })
+```
+
+A `borrowed` node may name an id before it is lent, so a description can refer to a model that is still loading; it appears when lent and disappears when withdrawn. Hits inside a borrowed object carry the `part` name of the mesh hit.
+
+## Animation
+
+Behaviours own animated properties: a mesh's rotation is either model-owned (`fixed`) or behaviour-owned (`spin`), never both. A behaviour's output is a pure function of scene time, so frames are deterministic and frame-rate independent.
+
+Behaviours replace React Three Fiber's `useFrame` with data: a node names one, `behaviour: behave('float', { speed: 2 })`, and the behaviour (a pure function of scene time registered with the scene) adds a position offset, a rotation and a scale factor on top of the node's transform each frame. `float` (Drei's `Float`) is built in; register your own through `SceneRuntime.make({ behaviours })` or `makeEnvironment(window, { behaviours })`:
+
+```ts
+const orbit: Behaviour = (pose, seconds, params) =>
+  pose.offset.set(Math.cos(seconds) * (params['radius'] ?? 1), 0, Math.sin(seconds));
+```
+
+Transitions decide how `position` and `scale` reach new values. The Model always owns the target; a transition only shapes the journey:
+
+```ts
+mesh({
+  key: 'cube',
+  position: [model.column, 0, 0],
+  transition: ease({ seconds: 0.35, easing: 'easeOutBack' }), // default: instant()
+  geometry: box(),
+  material: standard({ color: 0x14b8a6 }),
+});
+```
+
+- A new target mid-flight restarts from the pose on screen, so nothing jumps. A node moving to another group keeps its world position and travels to its new place.
+- Easings: `linear`, `easeInOutCubic` (default), `easeOutCubic`, `easeOutBack`. Tweens run in the frame loop without allocating and never reach `update`.
+
+Frames render on demand by default: a scene draws after any change and while anything animates, then stops requesting frames until the next change, so nothing ever calls `invalidate`. `render: renderSettings({ frames: 'always' })` draws every display frame, as React Three Fiber's default does; `frames: 'never'` draws only on `handle.advance`.
+
+When frames run persistently slow, the scene emits `PerformanceChanged { fps, factor }` (Drei's `PerformanceMonitor` algorithm). Store the factor in the Model and pass it back as `renderSettings({ resolution })` to lower the pixel ratio until frames recover.
+
+`handle.setAnimating(false)` freezes scene time (for `prefers-reduced-motion`) while frames keep rendering; transitions then land at once, including any in flight.
+
+## Testing
+
+Everything needed for deterministic headless tests ships with the package:
+
+- `recordingRendererFactory()`: counts renders and records viewport and disposal.
+- `createManualFrames()`: frames run when you call `step()`.
+- Effect's `TestClock`: scene time comes from the `Clock` service's monotonic reading.
+- **Renderers:** `webglRendererFactory` (the default) or `webgpuRendererFactory` (three's `WebGPURenderer`: WebGPU where available, its WebGL 2 backend otherwise), each carrying its render kit (`@opsydyn/effect-three/webgl` or `/webgpu`). Labels need WebGL. See [ADR-010](../../docs/effect-three/adr/010-webgpu-renderer.md).
+- `createSceneGraph()`: the synchronous kernel on its own, with `object(key)` and resource `stats()` for assertions. Pass `kit: webglKit` (from `@opsydyn/effect-three/webgl`) to draw skies, shader grids and contact shadows; `webglRendererFactory` carries it for you.
+
+## Stability
+
+`0.x`. The four packages (`@opsydyn/effect-three`, `-foldkit`, `-rapier`, `-troika`) are
+released together at one version, and each adapter needs the core at exactly its own
+version. The public surface is what the API reports in `etc/` record, checked in CI: a
+change that breaks it bumps the minor version (0.1 to 0.2); additions and fixes bump the
+patch.
+
+## Limits
+
+- **WebXR on `WebGPURenderer`** is wired but untested: the headset emulator the tests use
+  (IWER) cannot render into it. WebXR on the WebGL renderer is tested.
+- **Labels are not drawn under WebGPU**: troika builds WebGL shaders and has no WebGPU
+  path. A scene with labels draws everything else.
+- **DOM overlay** (`xr({ domOverlay: true })`) is checked only in the session request; the
+  emulator has no overlay.
+
+## Architecture
+
+- `src/kernel`: plain TypeScript (descriptions, keyed diff, applier, resource store, behaviours, pointer hit testing). It must not import `effect` ([ADR-003](../../docs/effect-three/adr/003-kernel-runtime-layering.md)).
+- `src/runtime`: Effect services, scopes and typed errors.
+
+Decisions and their evidence are in [`docs/effect-three`](../../docs/effect-three/).
+
+## Development
+
+```sh
+bun run test         # unit and property tests (effect/Arbitrary)
+bun run check        # strict lint, layering and single-effect checks
+bun run typecheck    # TypeScript 7
+bun run bench:check  # benchmarks against the plan's budgets
+bun run build        # dist JS (bun build) and declarations (tsc)
+bun run api:check    # fail if the public API changed without updating etc/
+```
+
+Current benchmark results (Apple Silicon, 1,000 meshes):
+
+| Case                         | Median                 | Budget |
+| ---------------------------- | ---------------------- | ------ |
+| No-op reconcile              | ~95 µs                 | 200 µs |
+| One changed property         | ~95 µs, 1 op           | 500 µs |
+| Runtime mount + unmount      | ~22 µs                 | 1 ms   |
+| Frame with one animated mesh | ~55 ns, no heap growth | 50 µs  |

package/dist/index-4045wme0.js

@@ -0,0 +1,129 @@
+// src/kernel/contactShadowPasses.ts
+import {
+  Color,
+  Mesh,
+  MeshBasicMaterial,
+  OrthographicCamera,
+  PlaneGeometry,
+  Scene,
+  Vector3
+} from "three";
+var up = new Vector3(0, 1, 0);
+var aim = new Vector3;
+var groundGeometry = (width, depth, flipped) => {
+  const geometry = new PlaneGeometry(width, depth).rotateX(-Math.PI / 2);
+  if (flipped)
+    return geometry;
+  const uv = geometry.getAttribute("uv");
+  for (let i = 0;i < uv.count; i++)
+    uv.setY(i, 1 - uv.getY(i));
+  return geometry;
+};
+var reshaped = (a, b) => a.resolution !== b.resolution || a.size[0] !== b.size[0] || a.size[1] !== b.size[1];
+var createContactShadowPasses = (graph, renderer, materials) => {
+  let shown;
+  const release = () => {
+    if (shown === undefined)
+      return;
+    shown.plane.removeFromParent();
+    shown.plane.geometry.dispose();
+    shown.plane.material.dispose();
+    shown.target.dispose();
+    shown.blurTarget.dispose();
+    shown.depthMaterial.dispose();
+    shown.horizontal.material.dispose();
+    shown.vertical.material.dispose();
+    shown.quad.geometry.dispose();
+    shown = undefined;
+  };
+  const build = (description) => {
+    const [width, depth] = description.size;
+    const target = renderer.createTarget(description.resolution, description.resolution);
+    const blurTarget = renderer.createTarget(description.resolution, description.resolution);
+    const material = new MeshBasicMaterial({
+      map: target.texture,
+      transparent: true,
+      depthWrite: false
+    });
+    const plane = new Mesh(groundGeometry(width, depth, materials.flippedTargets), material);
+    plane.raycast = () => {
+      return;
+    };
+    graph.scene.add(plane);
+    const color = new Color;
+    const quad = new Mesh(new PlaneGeometry(2, 2));
+    quad.position.z = -0.5;
+    const quadScene = new Scene;
+    quadScene.add(quad);
+    return {
+      description,
+      plane,
+      camera: new OrthographicCamera(-width / 2, width / 2, depth / 2, -depth / 2, 0, 1),
+      target,
+      blurTarget,
+      color,
+      depthMaterial: materials.depth(color),
+      horizontal: materials.blur("horizontal"),
+      vertical: materials.blur("vertical"),
+      quad,
+      quadScene,
+      quadCamera: new OrthographicCamera(-1, 1, 1, -1, 0, 1)
+    };
+  };
+  const update = (current, description) => {
+    current.plane.position.fromArray(description.position);
+    current.plane.material.opacity = description.opacity;
+    current.color.setHex(description.color);
+    current.camera.position.fromArray(description.position);
+    current.camera.up.set(0, 0, 1);
+    current.camera.lookAt(aim.copy(current.camera.position).add(up));
+    current.camera.near = description.near;
+    current.camera.far = description.far;
+    current.camera.updateProjectionMatrix();
+    current.camera.updateMatrixWorld();
+    return { ...current, description };
+  };
+  const blurPass = (current, amount) => {
+    const { horizontal, vertical, quad, quadScene, quadCamera } = current;
+    quad.material = horizontal.material;
+    horizontal.set(current.target.texture, amount / 256);
+    renderer.render(quadScene, quadCamera, undefined, current.blurTarget);
+    quad.material = vertical.material;
+    vertical.set(current.blurTarget.texture, amount / 256);
+    renderer.render(quadScene, quadCamera, undefined, current.target);
+  };
+  const render = (current) => {
+    const { scene } = graph;
+    const background = scene.background;
+    const override = scene.overrideMaterial;
+    current.plane.visible = false;
+    scene.background = null;
+    scene.overrideMaterial = current.depthMaterial;
+    renderer.render(scene, current.camera, undefined, current.target);
+    scene.overrideMaterial = override;
+    scene.background = background;
+    current.plane.visible = true;
+    blurPass(current, current.description.blur);
+    if (current.description.smooth)
+      blurPass(current, current.description.blur * 0.4);
+  };
+  return {
+    draw: () => {
+      const description = graph.contactShadows();
+      if (description === null) {
+        release();
+        return;
+      }
+      if (shown !== undefined && reshaped(shown.description, description))
+        release();
+      shown = update(shown ?? build(description), description);
+      render(shown);
+    },
+    dispose: release
+  };
+};
+
+export { createContactShadowPasses };
+
+//# debugId=AFE8D134F596683564756E2164756E21
+//# sourceMappingURL=index-4045wme0.js.map

package/dist/index-4045wme0.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/kernel/contactShadowPasses.ts"],
+  "sourcesContent": [
+    "/**\n * Contact shadows, drawn by the frame loop with the scene's renderer: the passes, shared\n * by every render kit, which supplies the materials (`ShadowMaterials`).\n *\n * Behavioural reference: Drei `src/core/ContactShadows.tsx` at `bf6f4ad`, itself after\n * three.js's `webgl_shadow_contact` example by mrdoob (both MIT). As there, every drawn\n * frame:\n *\n * 1. renders the scene from below with an orthographic camera into a texture, through a\n *    depth material that turns nearness to the ground into shadow (alpha `1 − depth`,\n *    colour `color · depth · 2`), with the background off and the shadow plane hidden;\n * 2. blurs it horizontally and vertically (`blur / 256`), twice with `smooth` (the second\n *    at 0.4 of the blur);\n * 3. shows it on a transparent plane facing up.\n *\n * One difference: the blur passes draw a quad with their own camera, so they fill the\n * texture wherever the shadows are placed. (Drei draws its quad at the world origin with\n * the shadow camera, which leaves the blur empty when the shadows sit above `y = 0`.)\n *\n * @module\n */\nimport {\n  Color,\n  type Material,\n  Mesh,\n  MeshBasicMaterial,\n  OrthographicCamera,\n  PlaneGeometry,\n  Scene,\n  type Texture,\n  Vector3,\n} from 'three';\n\nimport type { ContactShadows } from './description.ts';\nimport type { RenderTarget, SceneRenderer } from './renderer.ts';\nimport type { ContactShadowPasses, ShadowedScene } from './renderKit.ts';\n\n/** One blur direction's material, and how to point it at a texture by an amount. */\nexport type BlurPass = {\n  readonly material: Material;\n  /** Reads `source`, blurring by `amount` of the texture's width (or height). */\n  readonly set: (source: Texture, amount: number) => void;\n};\n\n/** What a render kit draws contact shadows with. */\nexport type ShadowMaterials = {\n  /**\n   * The material the scene is drawn through from below: colour `color · depth · 2`, alpha\n   * `1 − depth`, no depth test or write.\n   */\n  readonly depth: (color: Color) => Material;\n  readonly blur: (direction: 'horizontal' | 'vertical') => BlurPass;\n  /**\n   * Whether the renderer reads a target's texture with v running the other way from\n   * WebGL's: three's WebGPU renderer does, on either backend.\n   */\n  readonly flippedTargets: boolean;\n};\n\n/** Everything one set of contact shadows holds while shown. */\ntype Shown = {\n  readonly description: ContactShadows;\n  readonly plane: Mesh<PlaneGeometry, MeshBasicMaterial>;\n  readonly camera: OrthographicCamera;\n  readonly target: RenderTarget;\n  readonly blurTarget: RenderTarget;\n  readonly color: Color;\n  readonly depthMaterial: Material;\n  readonly horizontal: BlurPass;\n  readonly vertical: BlurPass;\n  readonly quad: Mesh<PlaneGeometry, Material>;\n  readonly quadScene: Scene;\n  readonly quadCamera: OrthographicCamera;\n};\n\nconst up = new Vector3(0, 1, 0);\nconst aim = new Vector3();\n\n/**\n * The plane's geometry: flat, facing up, its texture's v running towards +z as the shadow\n * camera's image does (already so where the renderer reads targets flipped).\n */\nconst groundGeometry = (width: number, depth: number, flipped: boolean): PlaneGeometry => {\n  const geometry = new PlaneGeometry(width, depth).rotateX(-Math.PI / 2);\n  if (flipped) return geometry;\n  const uv = geometry.getAttribute('uv');\n  for (let i = 0; i < uv.count; i++) uv.setY(i, 1 - uv.getY(i));\n  return geometry;\n};\n\n/** Whether a change needs new targets, geometry or camera rather than an update. */\nconst reshaped = (a: ContactShadows, b: ContactShadows): boolean =>\n  a.resolution !== b.resolution || a.size[0] !== b.size[0] || a.size[1] !== b.size[1];\n\n/** Creates the contact shadow passes for one scene graph and renderer, with `materials`. */\nexport const createContactShadowPasses = (\n  graph: ShadowedScene,\n  renderer: SceneRenderer,\n  materials: ShadowMaterials,\n): ContactShadowPasses => {\n  let shown: Shown | undefined;\n\n  const release = (): void => {\n    if (shown === undefined) return;\n    shown.plane.removeFromParent();\n    shown.plane.geometry.dispose();\n    shown.plane.material.dispose();\n    shown.target.dispose();\n    shown.blurTarget.dispose();\n    shown.depthMaterial.dispose();\n    shown.horizontal.material.dispose();\n    shown.vertical.material.dispose();\n    shown.quad.geometry.dispose();\n    shown = undefined;\n  };\n\n  const build = (description: ContactShadows): Shown => {\n    const [width, depth] = description.size;\n    const target = renderer.createTarget(description.resolution, description.resolution);\n    const blurTarget = renderer.createTarget(description.resolution, description.resolution);\n    const material = new MeshBasicMaterial({\n      map: target.texture,\n      transparent: true,\n      depthWrite: false,\n    });\n    const plane = new Mesh(groundGeometry(width, depth, materials.flippedTargets), material);\n    // Shadows are scenery: never picked, never in the way of an overlay.\n    plane.raycast = () => undefined;\n    graph.scene.add(plane);\n    const color = new Color();\n    const quad = new Mesh<PlaneGeometry, Material>(new PlaneGeometry(2, 2));\n    // In front of the quad camera, between its near and far planes.\n    quad.position.z = -0.5;\n    const quadScene = new Scene();\n    quadScene.add(quad);\n    return {\n      description,\n      plane,\n      camera: new OrthographicCamera(-width / 2, width / 2, depth / 2, -depth / 2, 0, 1),\n      target,\n      blurTarget,\n      color,\n      depthMaterial: materials.depth(color),\n      horizontal: materials.blur('horizontal'),\n      vertical: materials.blur('vertical'),\n      quad,\n      quadScene,\n      quadCamera: new OrthographicCamera(-1, 1, 1, -1, 0, 1),\n    };\n  };\n\n  /** Applies the fields that change in place: placement, reach, colour and opacity. */\n  const update = (current: Shown, description: ContactShadows): Shown => {\n    current.plane.position.fromArray(description.position);\n    current.plane.material.opacity = description.opacity;\n    current.color.setHex(description.color);\n    current.camera.position.fromArray(description.position);\n    // Looking straight up, with +z as the image's up: its v runs towards +z, as the plane's.\n    current.camera.up.set(0, 0, 1);\n    current.camera.lookAt(aim.copy(current.camera.position).add(up));\n    current.camera.near = description.near;\n    current.camera.far = description.far;\n    current.camera.updateProjectionMatrix();\n    current.camera.updateMatrixWorld();\n    return { ...current, description };\n  };\n\n  /** One blur: horizontally into the spare target, then vertically back. */\n  const blurPass = (current: Shown, amount: number): void => {\n    const { horizontal, vertical, quad, quadScene, quadCamera } = current;\n    quad.material = horizontal.material;\n    horizontal.set(current.target.texture, amount / 256);\n    renderer.render(quadScene, quadCamera, undefined, current.blurTarget);\n    quad.material = vertical.material;\n    vertical.set(current.blurTarget.texture, amount / 256);\n    renderer.render(quadScene, quadCamera, undefined, current.target);\n  };\n\n  const render = (current: Shown): void => {\n    const { scene } = graph;\n    const background = scene.background;\n    const override = scene.overrideMaterial;\n    current.plane.visible = false;\n    scene.background = null;\n    scene.overrideMaterial = current.depthMaterial;\n    renderer.render(scene, current.camera, undefined, current.target);\n    scene.overrideMaterial = override;\n    scene.background = background;\n    current.plane.visible = true;\n    blurPass(current, current.description.blur);\n    if (current.description.smooth) blurPass(current, current.description.blur * 0.4);\n  };\n\n  return {\n    draw: () => {\n      const description = graph.contactShadows();\n      if (description === null) {\n        release();\n        return;\n      }\n      if (shown !== undefined && reshaped(shown.description, description)) release();\n      shown = update(shown ?? build(description), description);\n      render(shown);\n    },\n    dispose: release,\n  };\n};\n"
+  ],
+  "mappings": "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",
+  "debugId": "AFE8D134F596683564756E2164756E21",
+  "names": []
+}