@solidrt/3d 0.0.64 → 0.0.66

package/AGENTS.md

@@ -217,7 +217,7 @@ displacement - and `cullMargin` (world units, Godot's
 `extra_cull_margin`) for bounded displacement such as wind. Sprites
 cull by their quad's reach at any facing. A SKINNED part is culled by
 the union of its joints' boxes (the bake computes each joint's
-influence box in joint space, `ModelSkin.jointBounds`, .srtm VERSION
+influence box in joint space, `ModelSkin.jointBounds`, .sol3m VERSION
 5; the joint nodes carry them as culling-only bounds, outside the
 picking index), so the box follows the pose with no per-frame JS -
 Unity's bone bounds, Godot's per-bone AABBs; no `updateWhenOffscreen`
@@ -409,7 +409,7 @@ that pop in and shrink away on tap, the shelf cascading out and back
 through `<Show>`. Each natural settle calls the node's `onTransitionEnd`
 (plain field like the pointer handlers) with `{ component }` - never on
 a cancel, snap, leave or exit; the raw "spatialTransitionEnd" engine
-event (srt:events, carrying the CORE node id `_node`) stays for
+event (sol:events, carrying the CORE node id `_node`) stays for
 flux:spatial consumers.
 
 ### Geometry layout, indices and topology
@@ -495,7 +495,7 @@ so the mesh picks and culls where it is now drawn (the box follows at
 the next flush, the triangle index is rebuilt by the next query - a
 deforming mesh needs no re-attach). transformGeometry and
 the edge builders share extra streams with their source; merge
-concatenates every stream; the `.srtm` container refuses streams (run
+concatenates every stream; the `.sol3m` container refuses streams (run
 time data). `setDrawRange(mesh, first, count?)` draws indices `[first,
 first + count)` of the mesh's geometry (Three's `setDrawRange`, on the
 mesh because the scene owns the entries), applied to every entry of the
@@ -550,25 +550,25 @@ are Solid-free and
 GPU-free BY DESIGN so they can be checked headless and run under bun:
 `src/model-data.ts` re-exports exactly this set as the published
 `@solidrt/3d/model` entry (the bake tool and app bake scripts), and
-`tests/model-data.test.ts` imports it under `bun test`, so a runtime
-import creeping into any of them fails there; keep them that way.
+`tests/model-data.test.ts` imports it under `sol test`, on the bare flux
+binary, so a gui or `sol:` import creeping into any of them fails there
+(a headless `flux:` import would not); keep them that way.
 `src/splat-data.ts` is its own published entry the same way
 (`@solidrt/3d/splat`, guarded by `tests/splat-data.test.ts`).
-The rigs under `checks/`
-(`geometry-check`, `sweep-check`, `pick-check`, `dispatch-check`,
-`gltf-check`) run on
-flux from the repo root: `bunx srt bundle -f --stdout
-packages/3d/checks/<name>.ts | target/release/flux -`. Run the ones
-touching what you changed. `raycast-check.tsx` and
-`collision-check.tsx` are the exceptions: they assert the documented
-picking contract (triangle accuracy, the box tier, pick/raycast
-parity, layer masks, the `{ meshes }` filter) and collision contract
-(exact sweep times, the surface rule, the slide filter, layers and
-meshes on overlap/sweep, moveAndSlide's landing) against a real scene,
-so they run on the playback client instead:
-`bunx srt render packages/3d/checks/<name>.tsx --project --duration 3
---size 128x128`. Run them whenever a doc edit touches picking or
-collision claims - two copies of this contract have drifted before.
+The tests under `tests/` run with `bun run sol test packages/3d` from the
+repo root, or one file, or `--filter <text>` for the tests whose name
+contains it: the pure modules on the bare flux binary, and the files
+that need a GPU (`.test.tsx`, importing `@solidrt/test`) on the
+headless dev client. Run them after a change. `raycast.test.tsx` and
+`collision.test.tsx` assert the documented picking contract (triangle
+accuracy, the box tier, pick/raycast parity, layer masks, the
+`{ meshes }` filter) and collision contract (exact sweep times, the
+surface rule, the slide filter, layers and meshes on overlap/sweep,
+moveAndSlide's landing) against a real scene; run them whenever a doc
+edit touches picking or collision claims - two copies of this contract
+have drifted before. `fog.test.tsx` reads the fog example's pixels
+through its debug commands, and `camera-components.test.tsx` drives
+`<OrbitCamera>` and `<FirstPersonCamera>` with a real drag and key.
 
 ## Components
 
@@ -810,7 +810,7 @@ driving - the predicate every camera control shares) are reactive
 (HUD-safe); the pose is plain state via `pose()`/`set()` (also the
 debug-command shape). It drives position and target only; fov/near/far
 stay on scene.setCamera (or the Scene `camera` prop). The auto-orbit
-pauses while a gesture is open. checks/orbit-check.ts pins every stage
+pauses while a gesture is open. tests/orbit.test.ts pins every stage
 headless.
 
 In a component tree, skip the wiring: `<OrbitCamera input={input}
@@ -868,7 +868,7 @@ the shot's recording target, so an `<OrbitCamera>` or
 it, the container runs the blend on frames while one is in flight. A
 shot's picks and raycasts (`anchor`, `occlusion`) go through the
 owner's actual camera, which is the shot's own only while it is live
-and at rest. Pinned in checks/orbit-check.ts; probes/shots-3d-probe.tsx
+and at rest. Pinned in tests/orbit.test.ts; probes/shots-3d-probe.tsx
 is the live guard.
 
 ### First-person camera
@@ -931,8 +931,8 @@ swap with it), `moveSpeed`/`lookSpeed` follow their props, and a pitch
 clamp change re-clamps at once. Like the orbit control it drives
 position and yaw/pitch only: fov/near/far stay on scene.setCamera (or
 the Scene `camera` prop), so a walker in a scene bigger than the default
-`far` of 100 sets one there. checks/orbit-check.ts and
-checks/first-person-check.ts pin both controls headless (they import
+`far` of 100 sets one there. tests/orbit.test.ts and
+tests/first-person.test.ts pin both controls headless (they import
 `@solidrt/core/input` only).
 
 ### Overlay projection
@@ -1084,7 +1084,9 @@ repeats within 300 ms and 20 px on the same target (a double tap is
 tap. Wheel walks like a move with `deltaX/deltaY` (a node stopping it
 keeps the zoom out). Every event carries `native`, the leaf's element
 event, for core's recognizers, and the element fields (pointerId,
-pointerType, button, modifiers) plus `x`/`y` in scene pixels
+pointerType, button, modifiers, `timeStamp`, and `predicted`: a move to
+draw with, not to measure with - core's AGENTS.md has both) plus `x`/`y`
+in scene pixels
 (screenRay's input - a drag plane is one intersection away). Root
 listeners all run, in registration order (the root is the last stop,
 nothing is left to claim). Wiring: the built-in `<Scene>` leaf carries
@@ -1098,7 +1100,7 @@ natural size, under any ancestor transforms or design-size fits (the hit
 test undoes them; localX/localY arrive in the leaf's layout frame). A
 leaf laid out at a different size (the supersampling pattern) uses
 `scene.handlersFor(() => ({ width, height }))` with its layout size.
-checks/dispatch-check.ts pins the walk, claiming, capture, hover, wheel
+tests/dispatch.test.ts pins the walk, claiming, capture, hover, wheel
 and tap rules headless; examples/pick.tsx is the live guard.
 
 ### Geometry generators
@@ -1662,10 +1664,10 @@ specular, `envIrradiance` - the fully rough sample along the normal, as
 Three's getIBLIrradiance and Godot read it - added to the hemisphere
 for the diffuse) and every `phong({ reflectivity })` material mirrors,
 typically the skybox's own cube turned with it. The cube to use is a
-BAKED one: `bunx srt tool 3d/environment sky.hdr -o assets/sky.srte`
+BAKED one: `bun run sol tool 3d/environment sky.hdr -o assets/sky.sol3e`
 turns an equirectangular Radiance .hdr (Poly Haven's are CC0) into the
 six faces plus the GGX-prefiltered mip chain in linear float, and
-`await loadEnvironment("assets/sky.srte")` uploads it as an explicit
+`await loadEnvironment("assets/sky.sol3e")` uploads it as an explicit
 "rgba16f" chain (createCubeTexture's array-of-levels form: no generated
 mipmaps, so no half-float render support needed - it works on every
 device; created after an await, so not auto-freed). Unity convolves at
@@ -1680,7 +1682,7 @@ is a coarse average - fine for a sky gradient, wrong for a photograph.
 A 128 environment (2 MiB, the default) lights any surface; for a
 mirror-finish showpiece bake at 256, and for a crisp backdrop pair it
 with a separate hi-res LDR skybox (a 2k panorama through equirectToCube)
-as `background` while the .srte stays the `environment`. Scene-level like Three's
+as `background` while the .sol3e stays the `environment`. Scene-level like Three's
 `scene.environment`, Unity's environment reflections and Godot's
 sky-lit reflections: ONE `uEnv` samplerCube bound on every target the
 scene draws into (a 1x1 black placeholder while unset) and one
@@ -1748,7 +1750,7 @@ one), then the PREFILTER: the faces convolved on the GPU into a second,
 `mipmap: true` cube target level by level (`renderTarget(chain, face,
 level)`, one small pass each - 48 at 128 - the bake tool's GGX
 importance sampling as a fragment, `createPrefilter` in environment.ts,
-with the same roughness-to-level rule as a .srte chain), so `standard`
+with the same roughness-to-level rule as a .sol3e chain), so `standard`
 blurs a probe by roughness exactly like a baked environment; `prefilter:
 false` skips it and hands out the sharp faces (Three's CubeCamera: a
 mirror at every roughness). COST: the chain's passes are tiny, but a
@@ -1806,7 +1808,7 @@ clamp (`repeat` also wraps vertically and bleeds the poles). An HDR
 panorama uploaded as rgba16f converts into a half-float cube (sharp:
 a skybox, or `mipmap: true` for the box chain); its PREFILTERED form is
 the bake tool above, whose CPU pipeline (`src/environment-bake.ts`:
-decodeHdr, panoramaToCube, prefilterCube, the .srte encode/decode) is
+decodeHdr, panoramaToCube, prefilterCube, the .sol3e encode/decode) is
 pure TypeScript and bun-tested - there is no runtime .hdr decoder.
 
 ### Fog
@@ -2225,7 +2227,9 @@ index into `images`, `doubleSided`, `transparent` = alphaMode BLEND,
 `alphaMode` as written and `alphaCutoff`, spec default 0.5, the
 normal and emissive slots, `metalness`/`roughness` factors and the
 packed `metalnessRoughnessMap` - standard's inputs), `images`
-(the encoded PNG/JPEG bytes, undecoded) and `bounds` (world-space rest
+(each `{ bytes, name, uri? }`: the encoded PNG, JPEG or KTX2 file,
+undecoded; its name in the document, else the uri of its file, else
+"image<i>"; the `uri` when it is a file of its own) and `bounds` (world-space rest
 pose: a part's box through its node, a skinned part's per-joint boxes
 through the joints' rest transforms - where the skin places it, armature
 scale included; conservative under rotation). External
@@ -2273,7 +2277,8 @@ its true roots; a hierarchy reaching a node twice (a cycle) throws.
 #### createModel
 
 `createModel(data, { material?, label?, autoFree? })` - uploads the images (repeat
-wrap, mipmapped, 4x anisotropic), makes one material per glTF material (default `standard`
+wrap, mipmapped, 4x anisotropic; each texture is labeled `<label>-<image name>`, so the
+`/gpu` inventory names the image), makes one material per glTF material (default `standard`
 with the file's color, maps, normal scale, metalness/roughness and
 packed map, emissive and transparency - the glTF material model, so a
 scene showing a model wants an `environment` (a glTF metal in a scene
@@ -2319,16 +2324,120 @@ for the loaders that scope is the caller's at the call, captured before
 the await, so a model loaded inside a memo goes with the memo's rerun
 and one loaded in a component with its unmount. A load that settles
 after its scope is gone (unmounted mid-load) is freed on arrival and
-resolves already disposed - nothing owns it any more. `loadModel` reads the baked `.srtm` written by `srt tool
-3d/model <in.gltf|glb> -o assets/<name>.srtm`: the same parse run once
-under bun, stored in the GPU layout, so loading is views onto the file's
-bytes plus the image decodes. Numbers from a 32k-vertex, 6-texture model
+resolves already disposed - nothing owns it any more. `loadModel` reads the baked `.sol3m` written by `sol tool
+3d/model <in.gltf|glb> -o assets/<name>.sol3m`: the same parse run once
+at build time, stored in the GPU layout, so loading is views onto the
+file's bytes plus the image decodes. Numbers from a 32k-vertex, 6-texture model
 on a release client: `parseGltf` 124 ms on flux (22 ms under bun) against
 40 ms for the whole baked load - the runtime parse is fine for small
 models and a binary import (`import bytes from "./x.glb" with { type:
 "binary" }` then `createModel(parseGltf(bytes))`, see
 `examples/model.tsx`); bake anything big.
 
+#### Compressed textures
+
+`sol tool 3d/model <in> -o assets/<name>.sol3m` bakes the images
+too: each becomes a KTX2 compressed texture with its mip chain. The file is the
+same for every platform; at load each device turns the images into the
+block format its GPU samples (BC7 on desktops, ETC2 elsewhere), which
+holds them in a quarter of the memory of the decoded image. Measured on
+the Khronos Sponza sample (69 images): 363 MB of textures as PNG/JPEG,
+91 MB compressed. The encode is slow (a minute for that
+model) and runs once, at bake time. Block compression is lossy: judge
+the result on your own textures. What it saves is GPU memory; the file
+shrinks for color maps and can grow for data maps.
+
+How the images are compressed, and whether, is the app's to say, in the
+`textures` group of the `solidrt` key in its package.json (the project
+the tool runs in, whose root is where the tool is run). These are the
+defaults; name only what differs:
+
+```json
+"solidrt": {
+  "textures": {
+    "compress": true,
+    "color": { "codec": "etc1s", "quality": 0.75 },
+    "normal": { "codec": "uastc", "quality": 0.9 },
+    "data": { "codec": "uastc", "quality": 0.9 },
+    "files": []
+  }
+}
+```
+
+Three levels, the narrower one winning: the app (`compress`), a kind
+of map (`compress`, `codec`, `quality`), and single files:
+
+```json
+"files": [
+  { "match": "assets/sponza/textures/lion_*.png", "codec": "uastc", "quality": 0.95 },
+  { "match": ["assets/ui/**", "assets/hero.glb#lut*"], "compress": false }
+]
+```
+
+- `match` is a glob pattern, or a list of them, against the image's
+  path FROM THE PROJECT ROOT, written with "/": `*` inside a segment,
+  `**` across segments, `?`, `[a-z]`, `[!a-z]` (`matchesGlob` of
+  flux:path; no `{a,b}`, list the patterns). Not the uri the glTF
+  writes: two models with a `textures/base.png` each are two files.
+- An image embedded in the model (a .glb) has no file of its own: the
+  model's path names every image in it, and `#name` after it picks
+  the ones of that name (the glTF image's `name`, "image<i>" without
+  one).
+- An entry sets `compress`, `codec`, `quality` or several, over what
+  the image's kind says. Where several entries name one image, a
+  later entry wins, field by field.
+- `"compress": false` keeps the image as its PNG or JPEG. That is for
+  what must come back exact (a lookup table, a distance field) and
+  for sharp art and text, which block compression damages.
+- A pattern that names nothing FAILS the bake, before anything is
+  encoded: no file of the project matches it, or the baked model has
+  no embedded image of that name. A misspelled pattern would
+  otherwise do nothing and say nothing.
+
+`--compress` and `--no-compress` stand in for the app's `compress` for
+one run (a quick bake while the model is still changing); what a kind
+or an entry says about itself still holds.
+
+The kinds are core's and say what the texels are (`@solidrt/core/textures`).
+This package maps a material's slots onto them: base color and emissive
+maps are `color`, normal maps are `normal`, metallic-roughness maps
+(occlusion rides in the same image) are `data`.
+An image several slots share takes the most demanding kind, normal over
+color over data, and stays sRGB when one of them is a color slot;
+`modelImageUses(data)` returns that per image, the rule the loader and
+the bake both follow, for a bake script of your own.
+`codec` and `quality` are `encodeTexture`'s: "etc1s" is small (a
+quarter of a JPEG), "uastc" is accurate and large (often larger than
+the JPEG it replaces), `quality` is 0..1. A normal map steers the
+lighting and shows its errors, and a metallic-roughness map packs
+unrelated values into its channels, which the small codec handles
+badly, so both take the accurate one (what the Khronos KTX guide
+recommends). Set `data` to "etc1s" when the download matters more than
+roughness detail: on the Khronos Sponza sample that is 9 MB less for
+about 2 dB in the views that glossy surfaces fill. An unknown key, codec or field fails the bake naming the key,
+before anything is encoded, and the bake prints how many images it
+compressed with which codec and quality, and how many it kept. The color space (sRGB for `color`), the mip chain and the
+wrap are not settings: they follow how `createModel` samples. The
+settings are the app's, not this package's: an app's own bake script,
+or another extension's, reads the same group with
+`textureSettings(packageJson)` from `@solidrt/core/textures` and asks
+`textureSettingFor(settings, kind, { file, name }, matchesGlob)` per
+texture (core's AGENTS.md has the rest).
+
+`loadModel` and `loadGltf` handle such a model as they are, and
+`loadGltf` reads a glTF that carries KTX2 images itself
+(`KHR_texture_basisu`). Only the primitives show the step: transcoding
+is asynchronous and `createModel` is not, so bytes obtained another way
+go through `transcodeModelImages` between the two:
+
+```ts
+let data = await transcodeModelImages(decodeModel(bytes))
+let model = createModel(data)
+```
+
+`createModel` on data whose KTX2 images were not transcoded throws and
+names the function. Data without KTX2 images needs no such step.
+
 #### Baking your own geometry
 
 Geometry an app GENERATES (a terrain, a city block, a hundred thousand
@@ -2347,12 +2456,12 @@ import type { ModelData } from "@solidrt/3d/model"
 // takes `placements`), materials as glTF-shaped records, app data in
 // `extras` (JSON) and `blobs` (named bytes, each an aligned block).
 let data: ModelData = { nodes, parts, skins: [], clips: [], materials, images: [], bounds, extras: { spawn }, blobs: { grid } }
-await Bun.write("assets/level.srtm", encodeModel(data))
+await Bun.write("assets/level.sol3m", encodeModel(data))
 ```
 
-`loadModel("assets/level.srtm")` then builds it like any authored model;
+`loadModel("assets/level.sol3m")` then builds it like any authored model;
 `model.extras` and `model.blobs` hand the app data back (blobs are views
-onto the loaded bytes). `srt tool 3d/model` is the same entry applied
+onto the loaded bytes). `sol tool 3d/model` is the same entry applied
 to a glTF, so the two bakes share one code path.
 
 ### Async loading
@@ -2370,7 +2479,7 @@ PENDING_ASYNC_UNTRACKED_READ, and any element the component builds before
 the suspending read is orphaned on the boundary's retry and never freed
 (the dev leak sentinel reports it) - so the suspending component creates
 no elements of its own. Async here means the file read: the parse and
-createModel run synchronously on main. Bake anything big to .srtm; when
+createModel run synchronously on main. Bake anything big to .sol3m; when
 a source glTF must be parsed at runtime, do the parse in an isolate
 (parseGltf's result is plain data and copies across) and keep
 createModel on main.
@@ -2443,10 +2552,10 @@ rigged one; linear and premultiplied as glTF stores it) and the default
 material takes `vertexColors: true` for such parts - the callback's
 fourth argument says so, and a material shared by painted and unpainted
 parts is made once per variant, like the skinned split.
-A `.srtm` baked before the material records carried the PBR fields
+A `.sol3m` baked before the material records carried the PBR fields
 (file version 3), or before the vertex formats took the WebGPU spelling
 and byte counts (file version 5), is rejected by loadModel - re-bake
-with `srt tool 3d/model`. A baked part keeps a quantized export's
+with `sol tool 3d/model`. A baked part keeps a quantized export's
 bytes: u8 colors, u8/u16 joints and normalized weights, u16 uvs land in
 their own formats, positions and normals as floats.
 
@@ -2586,10 +2695,10 @@ mesh (JS-written records, no nodes) cannot morph: rejected at add().
 
 Not in the subset, dropped: tangents and further UV sets; samplers are
 ignored (every texture repeats); additive blending draws as base color.
-The follow-ups are filed in okf/backlog/3d-model-loader.md. The `.srtm`
-container is VERSION 8 (node table in the header, node-local vertices,
-skins, clips, packed morph targets); older bakes are rejected - re-bake
-with `srt tool 3d/model`.
+The follow-ups are filed in okf/backlog/3d-model-loader.md. The `.sol3m`
+container is VERSION 11 (node table in the header, node-local vertices,
+skins, clips, packed morph targets, app data, images under their
+names); older bakes are rejected - re-bake with `sol tool 3d/model`.
 
 ## Splats
 
@@ -2606,12 +2715,12 @@ successors) as ordinary content, the model-loading split repeated:
   times opacity, so the first n are the scene at n), y-down captures
   (.ply, .splat) stood up to y-up (positions and covariances rotated
   together; `keepOrientation` opts out, `.spz` is y-up already), bounds
-  measured. `encodeSplat`/`decodeSplat` round-trip the `.srts` container
+  measured. `encodeSplat`/`decodeSplat` round-trip the `.sol3s` container
   (the record and SH blocks, next bullet); decode is a header parse
-  plus byte VIEWS, nothing per-splat. `srt tool 3d/splat <in> [-o
-  out.srts] [--sh 0..3] [--keep-orientation]` is the parse and bake
+  plus byte VIEWS, nothing per-splat. `sol tool 3d/splat <in> [-o
+  out.sol3s] [--sh 0..3] [--keep-orientation]` is the parse and bake
   under bun (tools/splat.ts); an app bake script uses the same entry.
-- The `.srts` record (version 2) is 32 bytes = two rgba32ui texels:
+- The `.sol3s` record (version 2) is 32 bytes = two rgba32ui texels:
   center float32x3 + sRGB color and opacity unorm8x4, then the
   covariance upper triangle as six float16 + a spare word
   (SPLAT_ATTRIBUTES as a byte layout, SPLAT_RECORD_TEXELS). `--sh 1..3`
@@ -2622,7 +2731,7 @@ successors) as ordinary content, the model-loading split repeated:
   rgb interleaved), 32/48/96 bytes per splat of texture, so the
   default is 0 and a bake opts in. The y-up flip negates the
   coefficients whose basis is odd in (y, z).
-- On the runtime, `loadSplat(path)` reads a `.srts` (fetch + decode,
+- On the runtime, `loadSplat(path)` reads a `.sol3s` (fetch + decode,
   the loadModel shape) and `createSplatMesh(data, { count?, material?,
   label? })` / `<SplatMesh>` shows it: a RecordMesh in the INDEXED form
   (see "Instance order") - the records handed to the engine as the
@@ -2719,7 +2828,7 @@ successors) as ordinary content, the model-loading split repeated:
   ambient probe, this does not). glTF's default metallic factor is 1,
   so an untextured asset is all metal, and createModel's default is
   `standard`: give a model scene an `environment` (loadEnvironment's
-  baked .srte, or the skybox's cube), or pass `phong` as the material.
+  baked .sol3e, or the skybox's cube), or pass `phong` as the material.
 - Light intensities are the same numbers for `phong` and `standard`: 1
   lights a white matte surface to 1 face-on. A Three scene's intensities
   are a factor pi larger for the same look; divide when porting.
@@ -2792,7 +2901,7 @@ successors) as ordinary content, the model-loading split repeated:
 - A generated cube chain (`mipmap: true` from six faces) is a box
   filter, not the GGX convolution the roughness-to-level rule assumes:
   rough reflections read too sharp and the diffuse `envIrradiance` is a
-  4x4 average. Bake with `srt tool 3d/environment` for anything
+  4x4 average. Bake with `sol tool 3d/environment` for anything
   photographed; the JS sky gradients in the examples get away with it.
 - The background covers the whole target with depth off, drawn first: it
   REPLACES the clearColor visually (the clear still runs; you just never

package/examples/README.md

@@ -1,6 +1,6 @@
 # @solidrt/3d examples
 
-One concept per file; run with `bunx srt run <file>` from an app that
+One concept per file; run with `bun run sol run <file>` from an app that
 depends on `@solidrt/3d` (or in-repo from the package directory).
 
 - `scene-basic.tsx` - the whole v1 surface: a `<Scene>` composited as a
@@ -57,8 +57,8 @@ depends on `@solidrt/3d` (or in-repo from the package directory).
   the environment as tinted reflections, the dielectric row the same
   sky as a faint face-on gloss. Drag to look around.
 - `environment.tsx` - a baked HDR environment lighting the scene ALONE
-  (no lights, no hemisphere): `loadEnvironment` reads the .srte that
-  `bunx srt tool 3d/environment <panorama>.hdr -o assets/environment.srte`
+  (no lights, no hemisphere): `loadEnvironment` reads the .sol3e that
+  `bun run sol tool 3d/environment <panorama>.hdr -o assets/environment.sol3e`
   bakes from any equirectangular .hdr (Poly Haven's are CC0; the asset
   is not committed, bake one first), used as background and environment
   with ACES tone mapping. A metal row and a red dielectric row, roughness
@@ -200,4 +200,4 @@ depends on `@solidrt/3d` (or in-repo from the package directory).
   stays above the boundary - the two rules that avoid
   PENDING_ASYNC_UNTRACKED_READ and the suspend-retry element leak. Needs
   the asset baked into the running app:
-  `bunx srt tool 3d/model examples/model.glb -o assets/model.srtm`.
+  `bun run sol tool 3d/model examples/model.glb -o assets/model.sol3m`.

package/examples/cascades.tsx

@@ -22,7 +22,7 @@
 // plane, so the far pillars sink into the horizon instead of clipping
 // (`examples/fog.tsx` is the fog tour).
 import { createSignal, flush, onFrame, pct, render } from "@solidrt/core"
-import { registerDebug } from "srt:dev"
+import { registerDebug } from "sol:dev"
 import { box, DirectionalLight, HemisphereLight, phong, Mesh, PerspectiveCamera, plane, Scene, sphere } from "@solidrt/3d"
 import type { Geometry, Vec3 } from "@solidrt/3d"
 

package/examples/collision.tsx

@@ -30,7 +30,7 @@ import {
   sphere,
 } from "@solidrt/3d"
 import type { FirstPersonCameraHandle, MeshNode, MoveResult, SceneHandle, Vec3, Volume } from "@solidrt/3d"
-import { registerDebug } from "srt:dev"
+import { registerDebug } from "sol:dev"
 
 // Layer bit the level geometry adds to its drawn layer: what every
 // collision query selects, so pickups (drawn only) never block the walker.

package/examples/exits.tsx

@@ -14,7 +14,7 @@
 import { createSignal, For, pct, render, Show } from "@solidrt/core"
 import { box, Group, Mesh, PerspectiveCamera, plane, Scene, unlit } from "@solidrt/3d"
 import type { NodeTransition, SceneHandle, SceneTapEvent, Vec3 } from "@solidrt/3d"
-import { registerDebug } from "srt:dev"
+import { registerDebug } from "sol:dev"
 
 const COUNT = 5
 // Crate spacing along x, and the pause before a tapped-away crate is

package/examples/first-person.tsx

@@ -13,7 +13,7 @@ import { createInputMap, createPointerFeed, createSignal, gamepad, keyboard, loc
 import type { PointerEvent } from "@solidrt/core"
 import { box, cylinder, DirectionalLight, FirstPersonCamera, firstPersonActions, firstPersonBindings, HemisphereLight, phong, Mesh, PerspectiveCamera, plane, Scene } from "@solidrt/3d"
 import type { FirstPersonCameraHandle, Vec3 } from "@solidrt/3d"
-import { registerDebug } from "srt:dev"
+import { registerDebug } from "sol:dev"
 
 // Half extent of the walkable courtyard in world units; the walls stand
 // just outside it.

package/examples/fleet.tsx

@@ -18,7 +18,7 @@
 import { createInputMap, createPointerFeed, createSignal, flush, For, gamepad, pct, render } from "@solidrt/core"
 import { box, DirectionalLight, HemisphereLight, Instance, InstancedMesh, phong, Mesh, OrbitCamera, orbitActions, orbitBindings, plane, Scene, worldPosition } from "@solidrt/3d"
 import type { InstanceNode, NodeTransition, SceneHandle, Vec3 } from "@solidrt/3d"
-import { registerDebug } from "srt:dev"
+import { registerDebug } from "sol:dev"
 
 type Tint = [number, number, number, number]
 

package/examples/fog.tsx

@@ -16,11 +16,12 @@
 // command sets the mode and its knobs (`{ mode: "linear" | "exp2" |
 // "height" | "off", near, far, density, height, falloff }`) and returns
 // the state; `pan` parks the camera (`{ t: seconds }`), so a capture
-// repeats.
+// repeats; `suns` is the two suns' world positions and `project`
+// (`{ point }`) is where a world point is on screen, for a pixel probe.
 import { createSignal, flush, onFrame, pct, render } from "@solidrt/core"
-import { registerDebug } from "srt:dev"
+import { registerDebug } from "sol:dev"
 import { cone, cylinder, DirectionalLight, HemisphereLight, phong, Mesh, PerspectiveCamera, plane, Scene, sphere, unlit } from "@solidrt/3d"
-import type { FogOptions, Vec3 } from "@solidrt/3d"
+import type { FogOptions, SceneHandle, Vec3 } from "@solidrt/3d"
 
 const FAR = 400
 // The sky, shared by the clear and the fog so the horizon has no band.
@@ -36,6 +37,10 @@ const LINEAR_FAR = FAR
 const DENSITY = 0.006
 const HEIGHT = 10
 const HEIGHT_FALLOFF = 0.12
+// The two suns, side by side on the far ridge: the left one opts out of
+// the fog, the right one fogs like everything else.
+const SUN_LIT: Vec3 = [-30, 100, -220]
+const SUN_FOGGED: Vec3 = [30, 100, -220]
 
 type Mode = "linear" | "exp2" | "height" | "off"
 const MODES: Mode[] = ["linear", "exp2", "height", "off"]
@@ -48,6 +53,7 @@ let [height, setHeight] = createSignal(HEIGHT)
 let [falloff, setFalloff] = createSignal(HEIGHT_FALLOFF)
 let [time, setTime] = createSignal(0)
 let parked: number | null = null
+let scene: SceneHandle | null = null
 
 let num = (v: unknown, set: (n: number) => void) => {
   if (typeof v === "number") set(v)
@@ -73,6 +79,13 @@ registerDebug("pan", (args?: Record<string, unknown>) => {
   flush()
   return { t: time(), parked: parked !== null }
 })
+registerDebug("suns", () => ({ lit: SUN_LIT, fogged: SUN_FOGGED }))
+registerDebug("project", (args?: Record<string, unknown>) => {
+  if (scene === null) throw new Error("project: the scene is not mounted")
+  let point = args?.point
+  if (!Array.isArray(point) || point.length !== 3 || !point.every(v => typeof v === "number")) throw new Error("project: pass { point: [x, y, z] }")
+  return scene.project(point as Vec3)
+})
 
 function fog(): FogOptions | undefined {
   switch (mode()) {
@@ -148,7 +161,7 @@ function App() {
   return (
     <window>
       <view width={pct(100)} height={pct(100)} onPointerDown={() => setMode(m => MODES[(MODES.indexOf(m) + 1) % MODES.length] ?? "linear")}>
-        <Scene clearColor={[SKY[0], SKY[1], SKY[2], 1]} fog={fog()} samples={4} label="fog">
+        <Scene ref={s => (scene = s)} clearColor={[SKY[0], SKY[1], SKY[2], 1]} fog={fog()} samples={4} label="fog">
           <PerspectiveCamera fov={55} near={0.5} far={FAR} position={EYE} lookAt={lookAt()} />
           <HemisphereLight sky={[0.55, 0.62, 0.75]} ground={[0.28, 0.24, 0.2]} />
           <DirectionalLight color={[0.9, 0.85, 0.75]} rotation={[-0.9, 0.6, 0]} />
@@ -162,8 +175,8 @@ function App() {
               <Mesh geometry={crown} material={needles} position={[p.position[0], p.position[1] + p.size * 0.3 + p.size * 0.5, p.position[2]]} scale={[p.size * 0.9, p.size, p.size * 0.9]} />
             </>
           ))}
-          <Mesh geometry={sun} material={sunLit} position={[-30, 100, -220]} />
-          <Mesh geometry={sun} material={sunFogged} position={[30, 100, -220]} />
+          <Mesh geometry={sun} material={sunLit} position={SUN_LIT} />
+          <Mesh geometry={sun} material={sunFogged} position={SUN_FOGGED} />
         </Scene>
       </view>
     </window>

package/examples/lod.tsx

@@ -21,7 +21,7 @@
 import { onFrame, pct, render } from "@solidrt/core"
 import { addInstance, cone, cylinder, DirectionalLight, HemisphereLight, icosahedron, InstancedLod, phong, Lod, Mesh, mergeGeometries, plane, Scene, transformGeometry, useScene } from "@solidrt/3d"
 import type { InstancedMeshNode } from "@solidrt/3d"
-import { registerDebug } from "srt:dev"
+import { registerDebug } from "sol:dev"
 
 const TREES = 1000
 // Half the side of the square field the trees scatter over.

package/examples/model-load.tsx

@@ -3,7 +3,7 @@
 // bundle - the shape every app with real content ends up needing. Bake
 // the asset once and drop it in your app's assets tree:
 //
-//   bunx srt tool 3d/model examples/model.glb -o assets/model.srtm
+//   bun run sol tool 3d/model examples/model.glb -o assets/model.sol3m
 //
 // (loadGltf("assets/model.glb") has the exact same async shape; the bake
 // just removes the runtime parse.)
@@ -51,7 +51,7 @@ function Rover(props: { turn: () => number }) {
   // The async value: a memo returning a Promise. Its read below suspends
   // until the file is read and the model built, then resumes under the
   // <Loading> boundary in App.
-  let loaded = createMemo(() => loadModel("assets/model.srtm", { label: "rover" }))
+  let loaded = createMemo(() => loadModel("assets/model.sol3m", { label: "rover" }))
 
   // Everything derived from the model - framing, mounting - happens in
   // this memo, AFTER the suspending read, so nothing here runs or builds

package/examples/model.tsx

@@ -4,7 +4,7 @@
 // with parseGltf and turned into a Group of meshes by createModel. The
 // glb rides in the bundle as a binary import; a model under assets/ goes
 // through loadGltf (same parser, read with flux:fs) or, baked once with
-// `srt tool 3d/model`, through loadModel (no parsing at all). Every part
+// `sol tool 3d/model`, through loadModel (no parsing at all). Every part
 // keeps its node name and is an ordinary mesh: pointer events, transforms
 // and materials work per part. The materials are createModel's default
 // `standard` from the file's PBR factors, so the scene carries an

package/examples/morph.tsx

@@ -20,7 +20,7 @@
 // shadows morph too.
 
 import { createSignal, onCleanup, onFrame, pct, render } from "@solidrt/core"
-import { registerDebug } from "srt:dev"
+import { registerDebug } from "sol:dev"
 import { DirectionalLight, geometryAttribute, geometryVertexCount, getMorphNames, getMorphWeights, HemisphereLight, Instance, InstancedMesh, phong, Mesh, PerspectiveCamera, plane, Scene, setMorphWeights, sphere, withMorphTargets } from "@solidrt/3d"
 import type { InstanceNode, MeshNode } from "@solidrt/3d"
 

package/examples/normals.tsx

@@ -17,7 +17,7 @@
 // `helpers` debug command ({ on?: boolean }) toggles them.
 
 import { createSignal, onFrame, pct, render } from "@solidrt/core"
-import { registerDebug } from "srt:dev"
+import { registerDebug } from "sol:dev"
 import { computeVertexNormals, cylinder, DirectionalLight, fillAttribute, geometryAttribute, geometryVertexCount, Group, HemisphereLight, phong, Mesh, normalsHelper, PerspectiveCamera, Scene, sphere, toNonIndexed, unlit, updateVertices, withNormals } from "@solidrt/3d"
 
 // The crease angles in degrees: flat, the default, everything smoothed.

package/examples/pick.tsx

@@ -24,7 +24,7 @@
 import { createInputMap, createPointerFeed, createSignal, displayScale, pct, render } from "@solidrt/core"
 import { box, cone, getRotation, Group, Mesh, OrbitCamera, orbitActions, orbitBindings, PerspectiveCamera, plane, Scene, setMeshParams, setTransform, sphere, torus, unlit, useScene } from "@solidrt/3d"
 import type { Geometry, MeshNode, NodePointerEvent, NodeTapEvent, NodeWheelEvent, OrbitCameraHandle, SceneHandle, Vec3 } from "@solidrt/3d"
-import { registerDebug } from "srt:dev"
+import { registerDebug } from "sol:dev"
 
 type Color = [number, number, number]
 

package/examples/wireframe.tsx

@@ -18,7 +18,7 @@
 import { createSignal, onFrame, pct, render } from "@solidrt/core"
 import { createTexture } from "@solidrt/core/gpu"
 import type { TextureId } from "@solidrt/core/gpu"
-import { registerDebug } from "srt:dev"
+import { registerDebug } from "sol:dev"
 import { add, axesHelper, box3Helper, createModel, DirectionalLight, edgesGeometry, equirectToCube, gridHelper, Group, Mesh, parseGltf, PerspectiveCamera, Scene, setGeometry, setMaterial, unlit, wireframeGeometry } from "@solidrt/3d"
 import type { SceneNode } from "@solidrt/3d"
 import modelBytes from "./model.glb" with { type: "binary" }