@opsydyn/effect-three 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [0.4.0](https://github.com/opsydyn/fold-kit-experiments/compare/effect-three-v0.3.0...effect-three-v0.4.0) (2026-10-20)
+
+### Features
+
+- **effect-three:** a HUD, and the viewport gizmo in it ([a1d99d4](https://github.com/opsydyn/fold-kit-experiments/commit/a1d99d477d80744652237c0718fe0f2418490ea8))
+- **effect-three:** a measuring tape, the last widget of Beyond parity 5 ([0a05ae0](https://github.com/opsydyn/fold-kit-experiments/commit/0a05ae04b0ccfd616f945f26429b27acbe79f108))
+- **effect-three:** a scene vocabulary for assistants ([a138ccb](https://github.com/opsydyn/fold-kit-experiments/commit/a138ccb3c38226149b44d7b56ce488be8ebbcd89))
+- **effect-three:** a transform gizmo as data, and as a Foldkit submodel ([3b1e585](https://github.com/opsydyn/fold-kit-experiments/commit/3b1e58535b35669917c3325214199f9264fb314c))
+- **effect-three:** an inspector generated from schemas ([64d1d3b](https://github.com/opsydyn/fold-kit-experiments/commit/64d1d3b8bf9991c57c1cf56b94a8b3f1c773b17d))
+- **effect-three:** box select as data, and as a Foldkit submodel ([498a2ec](https://github.com/opsydyn/fold-kit-experiments/commit/498a2ecd7763208c17b54b85f5cc8af294c7ce9b))
+- **effect-three:** edges, trails, points, sparkles and stars ([f976907](https://github.com/opsydyn/fold-kit-experiments/commit/f9769078724c7ef405728581574d50001f338e81))
+- **effect-three:** lockstep, and the editor edited together across tabs ([b416557](https://github.com/opsydyn/fold-kit-experiments/commit/b416557da1e5b5c0d2669891c41e365f48ca818c))
+- **effect-three:** pivot controls as data, and as a Foldkit submodel ([4284921](https://github.com/opsydyn/fold-kit-experiments/commit/42849211eed2b745c4a43ad42682e2508829901b))
+- **effect-three:** scene files, branching history and review diffs ([ce2c54e](https://github.com/opsydyn/fold-kit-experiments/commit/ce2c54ef7cefa77ab07ee7126782b9abccb15adc))
+
 ## [0.3.0](https://github.com/opsydyn/fold-kit-experiments/compare/effect-three-v0.2.0...effect-three-v0.3.0) (2026-10-19)
 
 ### Features

package/README.md

@@ -47,12 +47,24 @@ const description = scene({
 - **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. `roundedBox` and `backdrop` are Drei's `RoundedBox` and `Backdrop`, with Drei's defaults.
+- **Lines:** `line({ key, points, width: 3, dashed: true })` is Drei's `Line` (three's fat lines, drawn by the render kit): pixels wide, or scene units with `worldUnits`; one colour or `vertexColors`; `segments: true` for pairs of points (Drei's `Segments`). `catmullRomPoints`, `cubicBezierPoints` and `quadraticBezierPoints` give the points of Drei's curve lines. `mesh({ edges: edges() })` outlines a mesh's hard edges (Drei's `Edges`), and `trail()` on a group or mesh leaves a ribbon behind it (Drei's `Trail`).
+- **Points:** `points({ key, positions, size: 6 })` draws round dots (Drei's `Points` and `PointMaterial`), with a colour and size factor a point if you like; `sparkles()` and `stars()` are Drei's `Sparkles` and `Stars`, seeded so they are the same on every load, moving in scene time. The render kit draws them.
+- **Transform gizmo:** `gizmoNodes(key, gizmo, placement, camera)` draws three's `TransformControls` handles (move, turn, scale; world or local; snaps) as scene nodes, and `pressGizmo` and `dragGizmo` turn the press and drag rays into the next placement, as three's controls would; the Foldkit adapter's `TransformGizmo` is it as a submodel. `basic({ depthTest: false })` draws over everything. `movedAlike(from, to, other)` moves the rest of a selection as the gizmo moved the first. `pivotNodes`, `pressPivot` and `dragPivot` are Drei's `PivotControls` the same way (every handle at once, sized in scene units); the adapter's `PivotControls` is the submodel.
+- **Measuring tape:** `placeTapeEnd(tape(), point)` places a tape's ends where clicks hit the scene, `pointTape` runs it to the pointer while the second is placed, `tapeLength` measures it and `tapeNodes` draws it; the Foldkit adapter's `MeasuringTape` is it as a submodel, its length an overlay at the middle.
+- **Lockstep:** `Lockstep.make`, `submit`, `send`, `receive` and `advance` keep peers that run the same `update` in step: each sends one packet a turn, a turn applies when all are in, inputs in peer order; `admit`, `welcomeDue`, `leave` and `remove` change who is in. The transport is yours (a `BroadcastChannel`, a socket); `SceneSchema.Lockstep(schema)` puts a session in a Model. The editor sample edits together across tabs with it (ADR-013).
+- **Scene files:** `SceneFile.save(scene)` writes a description as indented JSON in a versioned envelope; `SceneFile.read(text)` reads one back as a `Result`, failing with `UnreadableScene` and where. Fields added since a file was written read at their defaults.
+- **History:** `History.make(value)`, `History.record(history, next, label)`, `undo`, `redo`, `branches`, `chooseBranch` and `jumpTo` keep every Model value as a tree, so a change after an undo starts a branch instead of losing the old future; `SceneSchema.History(schema)` puts one in a Model.
+- **Describing and staging, for assistants:** `describeScene(scene)` lists what a scene contains (camera, things with kind, size, colour and place, lights, bounds, staging) and `formatSummary` writes it as a few lines to read before acting; `shotCamera(camera, box, 'three-quarter')` frames a box from a named angle, and `moodStaging('sunset')` gives a mood's lights, environment and sky.
+- **Inspector:** `Inspector.fields(schema, value)` lists any value's fields from its schema (numbers, text, switches, choices, colours, vectors; kinds and lists read-only), and `Inspector.edit(schema, value, path, next)` sets one and checks the result with the schema, as a `Result`. The Foldkit adapter's `inspectorView` draws them as a form.
+- **Review diffs:** `sceneChanges(before, after)` lists what changed (the kernel's own operations, the scene's settings, its HUD and render textures) and `formatChanges` writes a line for each; `bun run scene:diff a.json b.json` prints them for two scene files.
+- **Box select:** `boxSelect(camera, size, from, to, selectable)` returns the keys whose points fall in a box on the canvas, as three's `SelectionBox` (which Drei's `Select` wraps) would select them; the `GestureEnd` event ends a drag that began on nothing. The Foldkit adapter's `BoxSelect` is it as a submodel.
 - **Facing, detail and shake:** `rotation: billboard()` turns a node to face the camera every frame (Drei's `Billboard`, with `lockX`/`lockY`/`lockZ`); `group({ detail: detailed({ distances: [0, 10, 20] }) })` shows one child at a time by the camera's distance (Drei's `Detailed`); and a camera's `shake: cameraShake({ decay: true })` shakes it (Drei's `CameraShake`), a pure function of scene time that reduced motion holds still. A `borrowed` model shown under several keys is cloned, skinned models included (Drei's `Clone`).
 - **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.
+- **HUD:** `scene({ hud: hud({ alignment: 'bottom-right', margin: [80, 80], children }) })` draws nodes over the scene (Drei's `Hud`), through a camera measured in CSS pixels whose origin sits `margin` in from the aligned edges; its interactive meshes are picked before the scene. `viewportGizmoNodes(key, camera)` is Drei's `GizmoViewport` for it, and `cameraAlong(camera, axis)` turns a camera to look from an axis; the Foldkit adapter's `ViewportGizmo` is both as a submodel.
 - **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.