@solidrt/3d 0.0.64 → 0.0.65

package/AGENTS.md

@@ -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 `srt test`, on the bare flux
+binary, so a gui or `srt:` 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 srt 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,7 +1664,7 @@ 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 srt tool 3d/environment sky.hdr -o assets/sky.srte`
 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
@@ -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
@@ -2321,14 +2326,118 @@ 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
+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
+
+`srt tool 3d/model <in> -o assets/<name>.srtm` 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
@@ -2587,9 +2696,9 @@ 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`.
+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 `srt tool 3d/model`.
 
 ## Splats
 

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 srt 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
@@ -58,7 +58,7 @@ depends on `@solidrt/3d` (or in-repo from the package directory).
   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`
+  `bun run srt tool 3d/environment <panorama>.hdr -o assets/environment.srte`
   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 srt tool 3d/model examples/model.glb -o assets/model.srtm`.

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 { 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/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 srt tool 3d/model examples/model.glb -o assets/model.srtm
 //
 // (loadGltf("assets/model.glb") has the exact same async shape; the bake
 // just removes the runtime parse.)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/3d",
-  "version": "0.0.64",
+  "version": "0.0.65",
   "license": "MIT",
   "funding": "https://github.com/sponsors/wellawaretech",
   "author": "Antoine van Wel",
@@ -19,8 +19,11 @@
     "examples/",
     "AGENTS.md"
   ],
+  "devDependencies": {
+    "@solidrt/test": "0.0.65"
+  },
   "peerDependencies": {
-    "@solidjs/signals": "2.0.0-rc.9",
-    "@solidrt/core": "0.0.64"
+    "@solidjs/signals": "2.0.0-rc.13",
+    "@solidrt/core": "0.0.65"
   }
 }

package/src/geometry.ts

@@ -37,7 +37,7 @@
 // format's codec.
 //
 // Pure module by design - geometry is data, and every function here is
-// array math (the check rig checks/geometry-check.ts runs it headless on
+// array math (tests/geometry.test.ts runs it headless on
 // flux). The GPU buffer step lives in geometry-gpu.ts.
 
 import type { Topology, VertexAttribute, VertexFormat } from "@solidrt/core/gpu"

package/src/glsl.ts

@@ -19,7 +19,7 @@
 import type { CullMode, VertexAttribute } from "@solidrt/core/gpu"
 
 // core/gpu's glsl tag, aliased locally (it is String.raw) so this module
-// stays runtime-pure: no flux:gpu import, so the checks/ rigs and any
+// stays runtime-pure: no flux:gpu import, so the tests and any
 // bake-time tool can run it headless on bare flux.
 let glsl = String.raw
 

package/src/gltf.ts

@@ -16,10 +16,13 @@
 // data: buffers and images, and single-file .glb.
 //
 // Pure module by design - a parse is JSON plus typed-array views plus one
-// interleave loop per primitive, so it runs the same under bun (the bake
-// tool in tools/model.ts, the check rig) and on flux (loadGltf in
+// interleave loop per primitive, so it runs the same under bun (an app's
+// bake script, the check rig) and on flux (loadGltf in
 // model.ts). It never decodes images: material.map indexes the encoded
-// bytes in `images`, and uploading is the engine side's job.
+// files in `images`, and uploading is the engine side's job. An image is
+// a PNG or JPEG, or a KTX2 compressed texture (KHR_texture_basisu, whose
+// source a texture prefers over its plain one), kept with what its
+// source calls it.
 //
 // Outside the subset: Draco/meshopt-compressed meshes and any other
 // required extension throw naming it; tangents (the base channel and
@@ -44,6 +47,8 @@
 // the way Three fills userData, so app data authored as custom
 // properties arrives with the model.
 
+import type { TextureKind } from "@solidrt/core/textures"
+
 import { compose, decompose, det3, mat4, multiply, quatNormalize } from "./math.ts"
 import { linearToSrgb } from "./color.ts"
 import type { Mat4, Quat, Vec3 } from "./math.ts"
@@ -229,8 +234,13 @@ export type ModelData = {
   /** The file's animations (empty when it has none). */
   clips: ModelClip[]
   materials: ModelMaterial[]
-  /** Encoded image files (PNG/JPEG bytes) the materials' `map` index. */
-  images: Uint8Array[]
+  /** The images the materials' maps index. */
+  images: ModelImage[]
+  /** The KTX2 images transcoded for this device, by image index (the
+   * others absent): what `transcodeModelImages` adds and `createModel`
+   * uploads in place of the file. Never in a file; a parse and
+   * `decodeModel` leave it out. */
+  textures?: (ModelTexture | undefined)[]
   /** World-space rest-pose [minX, minY, minZ, maxX, maxY, maxZ] over every
    * part - each part's local box through its node's composed transform, and
    * a skinned part's per-joint boxes through the joints' rest transforms
@@ -355,6 +365,68 @@ const DEFAULT_MATERIAL: ModelMaterial = {
 }
 
 /** True when the bytes are a .glb container (the "glTF" magic). */
+/** One image of a model: its file as it is, and what its source calls
+ * it. */
+export type ModelImage = {
+  /** The encoded image file: PNG, JPEG or KTX2 bytes. */
+  bytes: Uint8Array
+  /** Its name in the document; without one the uri of its file, and
+   * "image<i>" (its index in the document) for a nameless image embedded
+   * there. Labels its texture, and is how an image embedded in a model
+   * is told from the others (`solidrt.textures`). */
+  name: string
+  /** The file a parse read it from, as the document names it (still
+   * percent-encoded), when it is a file of its own. Absent for an image
+   * embedded in its document, and on everything read from the container,
+   * which embeds its images. */
+  uri?: string
+}
+
+/** How a model samples one of its images: what decides its color space
+ * at upload and how it is compressed at bake. */
+export type ModelImageUse = {
+  /** A material samples it as color (base color, emissive): its texels
+   * are sRGB-encoded, as glTF stores those. Every other map is linear. */
+  srgb: boolean
+  /** What its errors cost, which picks its codec at bake time (the kinds
+   * of `solidrt.textures`): "normal" when any material samples it as a
+   * normal map, else "color" when it is a color map, else "data". An
+   * image several slots share takes the most demanding of them, and
+   * stays sRGB if one of them is a color slot. */
+  kind: TextureKind
+}
+
+/**
+ * How the model's materials sample each of its images, by image index.
+ * The one rule behind createModel's uploads and the bake's encodes, so a
+ * baked image is sampled as the same image unbaked.
+ */
+export function modelImageUses(data: Pick<ModelData, "images" | "materials">): ModelImageUse[] {
+  let uses: ModelImageUse[] = data.images.map(() => ({ srgb: false, kind: "data" }))
+  let at = (index: number | null): ModelImageUse | undefined => (index === null ? undefined : uses[index])
+  for (let m of data.materials) {
+    for (let color of [at(m.map), at(m.emissiveMap)]) {
+      if (color === undefined) continue
+      color.srgb = true
+      if (color.kind === "data") color.kind = "color"
+    }
+    let normal = at(m.normalMap)
+    if (normal !== undefined) normal.kind = "normal"
+  }
+  return uses
+}
+
+/** A compressed texture ready to upload: the payload `createTexture`
+ * takes at `format`, with the full mip chain when `mipmap`. The shape
+ * `transcodeTexture` returns. */
+export type ModelTexture = {
+  data: Uint8Array
+  width: number
+  height: number
+  format: "etc2-rgba8" | "etc2-rgba8-srgb" | "bc7-rgba8" | "bc7-rgba8-srgb" | "rgba8" | "rgba8-srgb"
+  mipmap: boolean
+}
+
 export function isGlb(bytes: Uint8Array): boolean {
   return bytes.length >= 12 && new DataView(bytes.buffer, bytes.byteOffset, 12).getUint32(0, true) === GLB_MAGIC
 }
@@ -363,7 +435,7 @@ export function isGlb(bytes: Uint8Array): boolean {
 // samples, and so the only images the parser ever opens: the prefetch
 // list (gltfExternalUris) and the parser's demand set are both derived
 // from this one table, so a channel added to the map is added here too or
-// checks/gltf-check.ts fails on its all-channels fixture.
+// tests/gltf.test.ts fails on its all-channels fixture.
 const SAMPLED_TEXTURES: ((material: any) => any)[] = [
   (m) => m.pbrMetallicRoughness?.baseColorTexture,
   (m) => m.normalTexture,
@@ -371,14 +443,21 @@ const SAMPLED_TEXTURES: ((material: any) => any)[] = [
   (m) => m.pbrMetallicRoughness?.metallicRoughnessTexture,
 ]
 
+// The image a texture samples: the KTX2 one where the file carries it
+// (KHR_texture_basisu), ahead of the plain source a file may keep beside
+// it as a fallback for loaders without the extension.
+function textureSource(texture: any): number | undefined {
+  return texture?.extensions?.KHR_texture_basisu?.source ?? texture?.source
+}
+
 // The image indices a document's materials sample (SAMPLED_TEXTURES
-// through textures[].source), the demand set imageSlot will meet.
+// through textureSource), the demand set imageSlot will meet.
 function sampledImages(gltf: any): Set<number> {
   let images = new Set<number>()
   for (let m of gltf.materials ?? []) {
     for (let channel of SAMPLED_TEXTURES) {
       let ref = channel(m)
-      let source = ref === undefined ? undefined : gltf.textures?.[ref.index]?.source
+      let source = ref === undefined ? undefined : textureSource(gltf.textures?.[ref.index])
       if (source !== undefined) images.add(source)
     }
   }
@@ -429,9 +508,9 @@ export function parseGltf(bytes: Uint8Array, resolve?: UriResolver): ModelData {
     }
     // Quantized attributes read through the normalized-integer path,
     // emissive strength is the emissive intensity, GPU instancing is
-    // read as placements; every other required extension changes what
-    // the file means.
-    if (ext !== "KHR_mesh_quantization" && ext !== "KHR_materials_emissive_strength" && ext !== "EXT_mesh_gpu_instancing") {
+    // read as placements, a KTX2 image is an image like another; every
+    // other required extension changes what the file means.
+    if (ext !== "KHR_mesh_quantization" && ext !== "KHR_materials_emissive_strength" && ext !== "EXT_mesh_gpu_instancing" && ext !== "KHR_texture_basisu") {
       throw new Error("parseGltf: the file requires the " + ext + " extension, which is not supported")
     }
   }
@@ -462,7 +541,7 @@ export function parseGltf(bytes: Uint8Array, resolve?: UriResolver): ModelData {
 
   // Images are pulled in only when a material samples them, in first-use
   // order, so `map` indexes a compact list.
-  let images: Uint8Array[] = []
+  let images: ModelImage[] = []
   let imageSlots = new Map<number, number>()
   let imageSlot = (index: number): number => {
     let slot = imageSlots.get(index)
@@ -470,8 +549,12 @@ export function parseGltf(bytes: Uint8Array, resolve?: UriResolver): ModelData {
       let image = gltf.images?.[index]
       if (image === undefined) throw new Error("parseGltf: texture names a missing image " + index)
       let bytes = image.uri !== undefined ? external(image.uri, "image " + index) : bufferViewBytes(image.bufferView)
+      // A data: uri is the image embedded in the document, not a file.
+      let file: string | undefined = image.uri !== undefined && !image.uri.startsWith("data:") ? image.uri : undefined
+      let entry: ModelImage = { bytes, name: image.name ?? file ?? "image" + index }
+      if (file !== undefined) entry.uri = file
       slot = images.length
-      images.push(bytes)
+      images.push(entry)
       imageSlots.set(index, slot)
     }
     return slot
@@ -484,8 +567,8 @@ export function parseGltf(bytes: Uint8Array, resolve?: UriResolver): ModelData {
   // (the prefetch list): a new channel goes in the table first.
   let textureSlot = (ref: any): number | null => {
     if (ref === undefined) return null
-    let texture = gltf.textures?.[ref.index]
-    return texture?.source !== undefined ? imageSlot(texture.source) : null
+    let source = textureSource(gltf.textures?.[ref.index])
+    return source !== undefined ? imageSlot(source) : null
   }
   let materials: ModelMaterial[] = (gltf.materials ?? []).map((m: any, i: number): ModelMaterial => {
     let pbr = m.pbrMetallicRoughness ?? {}

package/src/index.ts

@@ -77,10 +77,10 @@ export type {
   ShotProps,
   ShotsProps,
 } from "./components/index.ts"
-export { gltfExternalUris, isGlb, parseGltf } from "./gltf.ts"
-export type { ModelChannel, ModelClip, ModelData, ModelExtras, ModelMaterial, ModelNode, ModelPart, ModelSkin, UriResolver } from "./gltf.ts"
+export { gltfExternalUris, isGlb, modelImageUses, parseGltf } from "./gltf.ts"
+export type { ModelChannel, ModelClip, ModelData, ModelExtras, ModelImage, ModelImageUse, ModelMaterial, ModelNode, ModelPart, ModelSkin, ModelTexture, UriResolver } from "./gltf.ts"
 export { decodeModel, encodeModel } from "./model-file.ts"
-export { createModel, loadGltf, loadModel } from "./model.ts"
+export { createModel, loadGltf, loadModel, transcodeModelImages } from "./model.ts"
 export type { Model, ModelMaps, ModelOptions } from "./model.ts"
 export { decodeSplat, encodeSplat, parseSplat, SPLAT_ATTRIBUTES, SPLAT_RECORD_BYTES, SPLAT_RECORD_TEXELS, SPLAT_SH_TEXELS, SPLAT_TEXEL_BYTES } from "./splat-data.ts"
 export type { ParseSplatOptions, SplatData, SplatFormat } from "./splat-data.ts"

package/src/model-data.ts

@@ -2,19 +2,21 @@
 // runtime: the glTF parser, the .srtm container and the pure geometry kit,
 // for a script that bakes an app's own geometry under bun (or any host
 // with no flux). The package root imports `flux:*` and so loads only on
-// the runtime; this entry imports nothing that does. tools/model.ts (the
-// glTF bake) runs on exactly this surface, so an app's bake script and
-// the tool share one path:
+// the runtime; this entry imports nothing that does. tools/model.flux.ts
+// (the glTF bake) takes its model side from exactly this surface, so an
+// app's bake script and the tool share one path:
 //
 //   import { box, encodeModel, transformGeometry } from "@solidrt/3d/model"
 //   writeFileSync("assets/terrain.srtm", encodeModel({ nodes, parts, ... }))
 //
 // createModel / loadModel on the runtime read what it writes. Keep this
-// entry pure: tests/model-data.test.ts imports it under bun and fails the
-// moment a runtime import creeps into the chain.
+// entry pure. tests/model-data.test.ts imports it on the bare flux binary
+// and fails the moment a gui or srt: import creeps into the chain; a
+// headless flux: import it would not notice, and a bake script under bun
+// would.
 
-export { gltfExternalUris, isGlb, parseGltf } from "./gltf.ts"
-export type { ModelChannel, ModelClip, ModelData, ModelExtras, ModelMaterial, ModelNode, ModelPart, ModelSkin, UriResolver } from "./gltf.ts"
+export { gltfExternalUris, isGlb, modelImageUses, parseGltf } from "./gltf.ts"
+export type { ModelChannel, ModelClip, ModelData, ModelExtras, ModelImage, ModelImageUse, ModelMaterial, ModelNode, ModelPart, ModelSkin, ModelTexture, UriResolver } from "./gltf.ts"
 export { decodeModel, encodeModel } from "./model-file.ts"
 export { arrowHelper, axesHelper, box, box3Helper, capsule, capsuleHelper, circle, cone, cylinder, dodecahedron, fillAttribute, fillColors, edgesGeometry, mergeVertices, normalsHelper, toNonIndexed, withNormals, geometryBounds, geometryTopology, gridHelper, icosahedron, attributeAccess, geometryAttribute, geometryKey, geometryLayouts, geometrySlot, geometryStreams, geometryVertexCount, isFloatFormat, isFloatLayout, layoutAttributes, layoutKey, layoutSlot, layoutStride, mergeGeometries, octahedron, packGeometry, packMorphTargets, plane, planeHelper, polyhedron, ring, sphere, tetrahedron, torus, torusKnot, transformGeometry, validateGeometry, wireframeGeometry, vertexBytes, vertexCount, vertexView, withAttribute, withColors, withMorphTargets, MORPH_ENTRY_TEXELS, MORPH_TEXEL_FLOATS, BASE_FLOATS, VERTEX_FORMATS, VERTEX_LAYOUTS } from "./geometry.ts"
 export type { ArrowHelperOptions, AttributeAccess, AttributeFill, VertexStream, WithAttributeOptions, AxesHelperOptions, BoxOptions, CapsuleHelperOptions, CapsuleOptions, CircleOptions, ColorFill, ConeOptions, CylinderOptions, FormatCodec, Geometry, GeometryOptions, GridHelperOptions, MorphTarget, MorphTargets, NormalsHelperOptions, PlaneHelperOptions, PlaneOptions, PolyhedronOptions, RingOptions, SphereOptions, TorusKnotOptions, TorusOptions, VertexLayout } from "./geometry.ts"

package/src/model-file.ts

@@ -1,7 +1,9 @@
 // The baked model container (.srtm): ModelData as one file whose payload IS
 // the GPU layout, so loading it is a header parse plus typed-array views -
-// no per-vertex work. Written by tools/model.ts under bun (from parseGltf),
-// read by loadModel on flux; both ends are this pure module.
+// no per-vertex work. Written by tools/model.flux.ts (from parseGltf),
+// read by loadModel on flux; both ends are this pure module. An image
+// block carries the image file as it is, a PNG, a JPEG or a KTX2, under
+// the image's name.
 //
 // Layout, all little-endian:
 //   "SRTM" u32 | version u32 | jsonLength u32 | json (padded to 4) | payload
@@ -16,7 +18,7 @@
 // flipped index order) share the vertex block - decodeModel restores the
 // same identities, so the runtime uploads shared bytes once.
 
-import type { ModelChannel, ModelData, ModelExtras, ModelMaterial, ModelNode, ModelSkin } from "./gltf.ts"
+import type { ModelChannel, ModelData, ModelExtras, ModelImage, ModelMaterial, ModelNode, ModelSkin } from "./gltf.ts"
 import { layoutStride, vertexView, VERTEX_FORMATS } from "./geometry.ts"
 import type { VertexAttribute } from "@solidrt/core/gpu"
 import type { Geometry, VertexLayout } from "./geometry.ts"
@@ -54,7 +56,10 @@ const MAGIC = 0x4d545253
 // every earlier version rather than read as a file without them, so a
 // stale bake never silently drops the data an app relies on. Re-bake
 // with `srt tool 3d/model`.
-const VERSION = 10
+// Version 11 names the images: an image record is its block and the
+// image's name (ModelImage.name), which labels its texture. A
+// version-10 file has blocks alone and is rejected the same way.
+const VERSION = 11
 
 // The named layouts the container writes by name; a custom attribute-list
 // layout (a skinned primitive with COLOR_0, a withAttribute channel) is
@@ -76,6 +81,10 @@ function decodeLayout(layout: string | VertexAttribute[], name: string): VertexL
 
 type Block = { offset: number; bytes: number }
 
+/** One image: the block holding its file, and its name. The uri a parse
+ * read it from is not written: the container embeds the image. */
+type ImageHeader = Block & { name: string }
+
 /** One geometry of the table: its interleaved vertex block, index block
  * and packed morph targets. Blocks may be shared between entries. */
 type GeometryHeader = {
@@ -116,7 +125,7 @@ type ClipHeader = { name: string; duration: number; channels: ChannelHeader[] }
 type Header = {
   nodes: ModelNode[]
   materials: ModelMaterial[]
-  images: Block[]
+  images: ImageHeader[]
   geometries: GeometryHeader[]
   parts: PartHeader[]
   skins: SkinHeader[]
@@ -190,7 +199,7 @@ export function encodeModel(data: ModelData): Uint8Array {
     if (part.extras !== undefined) header.extras = part.extras
     return header
   })
-  let images = data.images.map((image) => push(image))
+  let images: ImageHeader[] = data.images.map((image) => ({ ...push(image.bytes), name: image.name }))
   let floats = (f: Float32Array): Block => push(new Uint8Array(f.buffer, f.byteOffset, f.byteLength))
   let skins: SkinHeader[] = data.skins.map((skin) => ({ joints: skin.joints, inverseBind: floats(skin.inverseBind), jointBounds: floats(skin.jointBounds) }))
   let clips: ClipHeader[] = data.clips.map((clip) => ({
@@ -277,7 +286,7 @@ export function decodeModel(bytes: Uint8Array): ModelData {
     if (part.extras !== undefined) out.extras = part.extras
     return out
   })
-  let images = header.images.map((block) => new Uint8Array(buffer, payload + block.offset, block.bytes))
+  let images: ModelImage[] = header.images.map((image) => ({ bytes: new Uint8Array(buffer, payload + image.offset, image.bytes), name: image.name }))
   let floats = (block: Block): Float32Array => new Float32Array(buffer, payload + block.offset, block.bytes / 4)
   let skins: ModelSkin[] = header.skins.map((skin) => ({ joints: skin.joints, inverseBind: floats(skin.inverseBind), jointBounds: floats(skin.jointBounds) }))
   let clips = header.clips.map((clip) => ({

package/src/model.ts

@@ -13,15 +13,17 @@
 // them and detaches the group. loadGltf / loadModel are the
 // read-then-create conveniences over flux:fs; parseGltf / decodeModel +
 // createModel are the primitives under them, for bytes obtained any other
-// way (a binary import, a fetch).
+// way (a binary import, a fetch). Compressed images (KTX2, what `srt tool
+// 3d/model` bakes) are turned into this device's block format by
+// transcodeModelImages, the one asynchronous step between the two.
 
 import { file } from "flux:fs"
 import * as spatial from "flux:spatial"
-import { decodeImage, getOwner, isDisposed, onCleanup, runWithOwner } from "@solidrt/core"
+import { decodeImage, getOwner, isDisposed, isKtx2, onCleanup, runWithOwner, transcodeTexture } from "@solidrt/core"
 import type { Owner } from "@solidrt/core"
 import { createMutableTexture, createTexture, destroyTexture } from "@solidrt/core/gpu"
 import type { TextureId } from "@solidrt/core/gpu"
-import { gltfExternalUris, parseGltf } from "./gltf.ts"
+import { gltfExternalUris, modelImageUses, parseGltf } from "./gltf.ts"
 import type { ModelClip, ModelData, ModelExtras, ModelMaterial } from "./gltf.ts"
 import { decodeModel } from "./model-file.ts"
 import { disposeGeometry } from "./geometry-gpu.ts"
@@ -144,6 +146,20 @@ export type ModelSkinNodes = {
   jointBounds: Float32Array
 }
 
+/**
+ * Transcode the model's compressed images (KTX2) into this device's block
+ * format, off the JS thread (all are started at once; the runtime runs a
+ * few at a time), and return the data with them as `textures`; the images that are PNG or JPEG are left for
+ * createModel to decode. The step between a parse (or decodeModel) and
+ * createModel for data that may hold KTX2 images; loadModel and loadGltf
+ * run it. Data with no KTX2 image comes back as it is.
+ */
+export async function transcodeModelImages(data: ModelData): Promise<ModelData> {
+  if (!data.images.some((image) => isKtx2(image.bytes))) return data
+  let textures = await Promise.all(data.images.map((image) => (isKtx2(image.bytes) ? transcodeTexture(image.bytes) : undefined)))
+  return { ...data, textures }
+}
+
 /**
  * Build the scene object for parsed model data: upload its images (repeat
  * wrap, mipmapped, MODEL_ANISOTROPY; the base color and emissive images
@@ -151,24 +167,26 @@ export type ModelSkinNodes = {
  * rgba8), make a material per glTF material, the file's node hierarchy as
  * nested Groups, and a mesh per part under its node. Synchronous - the
  * data is already in memory.
+ *
+ * A compressed image uploads as transcodeModelImages left it: at the
+ * format and color space its file names, with the mip chain the file
+ * carries (none can be generated for compressed storage). Data holding a
+ * KTX2 image that was not transcoded throws.
  */
 export function createModel(data: ModelData, opts: ModelOptions = {}): Model {
   let label = opts.label
-  let colorImages = new Set<number>()
-  for (let m of data.materials) {
-    if (m.map !== null) colorImages.add(m.map)
-    if (m.emissiveMap !== null) colorImages.add(m.emissiveMap)
-  }
-  let textures: TextureId[] = data.images.map((bytes, i) => {
-    let image = decodeImage(bytes)
-    return createTexture(image.data, image.width, image.height, {
-      format: colorImages.has(i) ? "rgba8-srgb" : "rgba8",
-      wrap: "repeat",
-      mipmap: true,
-      anisotropy: MODEL_ANISOTROPY,
-      autoFree: false,
-      label: label ? label + "-image" + i : undefined,
-    })
+  let uses = modelImageUses(data)
+  let textures: TextureId[] = data.images.map((image, i) => {
+    let sampling = { wrap: "repeat" as const, anisotropy: MODEL_ANISOTROPY, autoFree: false, label: label ? label + "-" + image.name : image.name }
+    let ready = data.textures?.[i]
+    if (ready !== undefined) {
+      return createTexture(ready.data, ready.width, ready.height, { ...sampling, format: ready.format, mipmap: ready.mipmap })
+    }
+    if (isKtx2(image.bytes)) {
+      throw new Error("createModel: image '" + image.name + "' is a KTX2 compressed texture, which is transcoded before the model is created: await transcodeModelImages(data) first (loadModel and loadGltf do)")
+    }
+    let decoded = decodeImage(image.bytes)
+    return createTexture(decoded.data, decoded.width, decoded.height, { ...sampling, format: uses[i]!.srgb ? "rgba8-srgb" : "rgba8", mipmap: true })
   })
   let make = opts.material ?? ((m: ModelMaterial, maps: ModelMaps, skinned: boolean, vertexColors: boolean, morphed: boolean, instanced: boolean): Material => {
     // An emissive factor of zero is emission OFF (the glTF product rule:
@@ -434,7 +452,8 @@ export async function loadGltf(path: string, opts?: ModelOptions): Promise<Model
   for (let uri of gltfExternalUris(bytes)) {
     if (!files.has(uri)) files.set(uri, await file(dir + decodeURIComponent(uri)).bytes())
   }
-  return buildOwned(owner, opts, () => createModel(parseGltf(bytes, (uri) => files.get(uri)!), opts))
+  let data = await transcodeModelImages(parseGltf(bytes, (uri) => files.get(uri)!))
+  return buildOwned(owner, opts, () => createModel(data, opts))
 }
 
 /** Read a baked .srtm model (`srt tool 3d/model`) and build it: no parsing,
@@ -442,5 +461,6 @@ export async function loadGltf(path: string, opts?: ModelOptions): Promise<Model
 export async function loadModel(path: string, opts?: ModelOptions): Promise<Model> {
   let owner = getOwner()
   let bytes = await file(path).bytes()
-  return buildOwned(owner, opts, () => createModel(decodeModel(bytes), opts))
+  let data = await transcodeModelImages(decodeModel(bytes))
+  return buildOwned(owner, opts, () => createModel(data, opts))
 }

package/src/node.ts

@@ -273,6 +273,11 @@ export type SceneEventBase = {
    * (a view's own pixels under a view leaf). */
   x: number
   y: number
+  /** When the event happened, ms: the element event's `timeStamp`. */
+  timeStamp: number
+  /** The element event's `predicted`: a move the pointer was never
+   * reported at. Draw with it, do not measure with it. */
+  predicted: boolean
   pointerId: number
   pointerType: string
   button?: number

package/src/scene-pointer.ts

@@ -19,7 +19,7 @@
 // dispatch.ts is the same model one dimension down.
 //
 // Pure BY DESIGN (types only, nothing with GPU imports) so
-// checks/dispatch-check.ts drives it headless with a fake pick.
+// tests/dispatch.test.ts drives it headless with a fake pick.
 
 import type { PointerEvent as ElementPointerEvent, PointerFeed } from "@solidrt/core"
 import type { NodePointerEvent, SceneNode, ScenePointerListener } from "./node.ts"
@@ -58,6 +58,8 @@ type InternalEvent = {
   distance: number | null
   x: number
   y: number
+  timeStamp: number
+  predicted: boolean
   pointerId: number
   pointerType: string
   button?: number
@@ -95,8 +97,6 @@ export type PointerInputDeps = {
   root: Scene | ViewHandle
   /** The root's listeners, in registration order. */
   listeners: Set<ScenePointerListener>
-  /** The clock for tap repeats (default performance.now; checks inject). */
-  now?: () => number
 }
 
 export type PointerInput = {
@@ -108,7 +108,6 @@ export type PointerInput = {
 }
 
 export function makePointerInput(deps: PointerInputDeps): PointerInput {
-  let now = deps.now ?? (() => performance.now())
   let presses = new Map<number, Press>()
   let hover = new Map<number, Target>()
   let lastTap: { time: number; cx: number; cy: number; target: Target | null; count: number } | null = null
@@ -170,6 +169,8 @@ export function makePointerInput(deps: PointerInputDeps): PointerInput {
         distance: hit === null ? null : hit.distance,
         x,
         y,
+        timeStamp: e.timeStamp,
+        predicted: e.predicted,
         pointerId: e.pointerId,
         pointerType: e.pointerType,
         button: e.button,
@@ -245,7 +246,7 @@ export function makePointerInput(deps: PointerInputDeps): PointerInput {
         if (press.moved || !press.alone) return
         let release = nearest(x, y)
         if (press.target === null ? release !== null : release === null || !sameHit(release, press.target)) return
-        let time = now()
+        let time = e.timeStamp
         let repeat = lastTap !== null && time - lastTap.time <= TAP_INTERVAL_MS && sameTarget(lastTap.target, press.target) && Math.hypot(e.clientX - lastTap.cx, e.clientY - lastTap.cy) <= TAP_REPEAT_SLOP
         let count = repeat ? lastTap!.count + 1 : 1
         lastTap = { time, cx: e.clientX, cy: e.clientY, target: press.target, count }

package/src/splat-data.ts

@@ -3,8 +3,8 @@
 // covariance bake and the .srts container, for `srt tool 3d/splat` and any
 // app bake script under bun. The package root imports `flux:*` and so
 // loads only on the runtime; this entry imports nothing that does (the
-// model-data rule; tests/splat-data.test.ts imports it under bun and fails
-// the moment a runtime import creeps into the chain).
+// model-data rule; tests/splat-data.test.ts imports it on the bare flux
+// binary and fails the moment a gui or srt: import creeps into the chain).
 //
 //   import { encodeSplat, parseSplat } from "@solidrt/3d/splat"
 //   writeFileSync("assets/scan.srts", encodeSplat(parseSplat(bytes)))

package/tools/model.flux.ts

@@ -0,0 +1,206 @@
+// srt tool 3d/model: bake a glTF into a .srtm model file - the parse
+// (src/gltf.ts) run once here, the result written in the exact layout
+// loadModel views without any per-vertex work at runtime. Same parser,
+// same subset, same result as loadGltf; this only moves the cost to build
+// time. Put the output under assets/ so it ships with the app.
+//
+// The images are baked too: each PNG or JPEG becomes a KTX2 compressed
+// texture with its mip chain, which the device turns into its own block
+// format at load (a quarter of the GPU memory of the decoded image). One
+// file for every platform, so the tool takes no platform. How each image
+// is compressed, and whether, is the app's: the `textures` group of the
+// `solidrt` key in the package.json of the project the tool runs in, over
+// the defaults (@solidrt/core/textures) - per kind of map (color, normal,
+// data) and per file, an image named by its path from the project root
+// and an embedded one by `<model path>#<its name>`. --compress and
+// --no-compress stand in for the app's own `compress` for one run.
+//
+// A flux tool (the file name says so): the texture encoder is the
+// runtime's, flux:image. The model side comes from the runtime-free
+// `@solidrt/3d/model` entry (src/model-data.ts), the same surface an
+// app's own bake script uses under bun.
+//
+//   srt tool 3d/model <in.gltf|in.glb> [-o <out.srtm>] [--compress|--no-compress]
+
+import { file, glob } from "flux:fs"
+import { decodeImage, encodeTexture } from "flux:image"
+import { basename, dirname, extname, join, matchesGlob, relative } from "flux:path"
+import { argv, exit } from "flux:process"
+import { isKtx2, textureSettingFor, textureSettings, unmatchedTextureFiles, unmatchedTextureNames } from "@solidrt/core/textures"
+import type { TextureKind, TextureSetting, TextureSettings, TextureSource } from "@solidrt/core/textures"
+import { encodeModel, gltfExternalUris, layoutStride, modelImageUses, parseGltf } from "../src/model-data.ts"
+import type { ModelData, ModelImage } from "../src/model-data.ts"
+
+// The project's package.json, where the texture settings live.
+const PROJECT_CONFIG = "package.json"
+
+// How many images are decoded and encoded at once: what the runtime
+// encodes at a time. More would only queue, each with its decoded pixels.
+const IMAGES_IN_FLIGHT = 4
+
+// The project the tool runs in: its root is the cwd, which the patterns
+// of the texture settings are written from.
+const PROJECT_ROOT = "."
+
+const USAGE = "Usage: srt tool 3d/model <in.gltf|in.glb> [-o <out.srtm>] [--compress|--no-compress]"
+
+function usage(error?: string): never {
+  if (error) console.error(error)
+  console.log(USAGE)
+  exit(error ? 1 : 0)
+}
+
+function kib(bytes: number): string {
+  return (bytes / 1024).toFixed(0) + " KiB"
+}
+
+function images(count: number): string {
+  return count === 1 ? "1 image" : count + " images"
+}
+
+// The texture settings of the project the tool runs in; the defaults where
+// it has no package.json. `compress` is the run's own word, when it has
+// one.
+async function projectTextureSettings(compress: boolean | undefined): Promise<TextureSettings> {
+  let config = file(PROJECT_CONFIG)
+  return textureSettings((await config.exists()) ? await config.json() : undefined, { compress })
+}
+
+// What an image is to the texture settings: its file as the path from the
+// project root, or for an embedded image the model's file and its name.
+function imageSource(image: ModelImage, model: string): TextureSource {
+  if (image.uri === undefined) return { file: relative(PROJECT_ROOT, model), name: image.name }
+  return { file: relative(PROJECT_ROOT, join(dirname(model), decodeURIComponent(image.uri))) }
+}
+
+// The entries of the settings that name nothing, which is a misspelled
+// pattern: a file the project does not have, a name the model does not.
+async function unmatchedPatterns(data: ModelData, model: string, settings: TextureSettings): Promise<string[]> {
+  let files = await unmatchedTextureFiles(settings, (pattern) => glob(pattern, { cwd: PROJECT_ROOT }))
+  let embedded = data.images.filter((image) => image.uri === undefined).map((image) => image.name)
+  return [...files, ...unmatchedTextureNames(settings, relative(PROJECT_ROOT, model), embedded, matchesGlob)]
+}
+
+// The images of one kind compressed the same way, and the ones kept.
+type Group = { kind: TextureKind; setting: TextureSetting; images: number; from: number; to: number }
+type Baked = { groups: Group[]; kept: { images: number; bytes: number } }
+
+// The images as KTX2, in place, each as the settings say for it and in
+// the color space createModel samples it in (modelImageUses, the rule the
+// two share), mipmapped for repeat wrap. IMAGES_IN_FLIGHT at a time, each
+// decoded when its turn comes. An image the settings leave alone is kept,
+// and so is one that is a KTX2 already.
+async function bakeImages(data: ModelData, model: string, settings: TextureSettings): Promise<Baked> {
+  let baked: Baked = { groups: [], kept: { images: 0, bytes: 0 } }
+  let groupOf = (kind: TextureKind, setting: TextureSetting): Group => {
+    let group = baked.groups.find((g) => g.kind === kind && g.setting.codec === setting.codec && g.setting.quality === setting.quality)
+    if (group === undefined) {
+      group = { kind, setting, images: 0, from: 0, to: 0 }
+      baked.groups.push(group)
+    }
+    return group
+  }
+  let uses = modelImageUses(data)
+  let next = 0
+  let lane = async () => {
+    while (next < data.images.length) {
+      let i = next++
+      let image = data.images[i]!
+      let source = image.bytes
+      let { kind, srgb } = uses[i]!
+      let setting = textureSettingFor(settings, kind, imageSource(image, model), matchesGlob)
+      if (!setting.compress || isKtx2(source)) {
+        baked.kept.images++
+        baked.kept.bytes += source.byteLength
+        continue
+      }
+      image.bytes = await encodeTexture(decodeImage(source), {
+        codec: setting.codec,
+        quality: setting.quality,
+        srgb,
+        mipmap: true,
+        wrap: "repeat",
+      })
+      let group = groupOf(kind, setting)
+      group.images++
+      group.from += source.byteLength
+      group.to += image.bytes.byteLength
+    }
+  }
+  await Promise.all(Array.from({ length: IMAGES_IN_FLIGHT }, lane))
+  let order: TextureKind[] = ["color", "normal", "data"]
+  baked.groups.sort((a, b) => order.indexOf(a.kind) - order.indexOf(b.kind))
+  return baked
+}
+
+let input: string | undefined
+let output: string | undefined
+let compress: boolean | undefined
+for (let i = 0; i < argv.length; i++) {
+  let arg = argv[i]!
+  if (arg === "--help" || arg === "-h") usage()
+  else if (arg === "-o" || arg === "--output") {
+    output = argv[++i]
+    if (output === undefined) usage("Missing value for " + arg)
+  } else if (arg === "--compress") compress = true
+  else if (arg === "--no-compress") compress = false
+  else if (arg.startsWith("-")) usage("Unknown option " + arg)
+  else if (input === undefined) input = arg
+  else usage("Unexpected argument " + arg)
+}
+if (input === undefined) usage("Missing input file")
+if (output === undefined) output = basename(input, extname(input)) + ".srtm"
+
+// The parse is synchronous, so the external files it will open are read
+// ahead of it (the same prefetch loadGltf does).
+let dir = dirname(input)
+let bytes = await file(input).bytes()
+let files = new Map<string, Uint8Array>()
+for (let uri of gltfExternalUris(bytes)) {
+  if (!files.has(uri)) files.set(uri, await file(join(dir, decodeURIComponent(uri))).bytes())
+}
+
+let started = performance.now()
+let data = parseGltf(bytes, (uri) => files.get(uri)!)
+let parsed = performance.now() - started
+
+// Read and checked before the encode, so a mistake in the settings costs
+// no bake.
+let settings: TextureSettings
+let unmatched: string[]
+try {
+  settings = await projectTextureSettings(compress)
+  unmatched = await unmatchedPatterns(data, input, settings)
+} catch (e) {
+  console.error(`The texture settings in ${PROJECT_CONFIG} cannot be used: ${e instanceof Error ? e.message : String(e)}`)
+  exit(1)
+}
+if (unmatched.length > 0) {
+  console.error(`The texture settings in ${PROJECT_CONFIG} (solidrt.textures.files) name nothing with:`)
+  for (let pattern of unmatched) console.error(`  ${pattern}`)
+  console.error("A pattern is a path from the project root; after a model's path, #name picks an image embedded in it.")
+  exit(1)
+}
+started = performance.now()
+let baked = await bakeImages(data, input, settings)
+let bakeMs = performance.now() - started
+
+let encoded = encodeModel(data)
+await file(output).write(encoded)
+
+let triangles = data.parts.reduce((n, p) => n + p.geometry.indices.length / 3, 0)
+let vertices = data.parts.reduce((n, p) => n + p.geometry.vertices.byteLength / layoutStride(p.geometry.layout), 0)
+let targets = data.parts.reduce((n, p) => n + (p.geometry.morphs?.names.length ?? 0), 0)
+console.log(
+  `${output}: ${data.nodes.length} nodes, ${data.parts.length} parts, ${vertices} vertices, ${triangles} triangles, ` +
+    (targets > 0 ? `${targets} morph targets, ` : "") +
+    `${data.clips.length} clips, ${data.materials.length} materials, ${data.images.length} images, ${kib(encoded.byteLength)} ` +
+    `(parsed in ${parsed.toFixed(0)} ms)`,
+)
+if (baked.groups.length > 0) {
+  console.log(`Images as KTX2 (encoded in ${(bakeMs / 1000).toFixed(1)} s):`)
+  for (let group of baked.groups) {
+    console.log(`  ${group.kind}: ${images(group.images)}, ${group.setting.codec} at quality ${group.setting.quality}, ${kib(group.from)} to ${kib(group.to)}`)
+  }
+}
+if (baked.kept.images > 0) console.log(`Kept as they are: ${images(baked.kept.images)}, ${kib(baked.kept.bytes)}`)

package/tools/model.ts

@@ -1,56 +0,0 @@
-#!/usr/bin/env bun
-/// <reference path="./node-env.d.ts" />
-
-// srt tool 3d/model: bake a glTF into a .srtm model file - the parse
-// (src/gltf.ts) run once here under bun, the result written in the exact
-// layout loadModel views without any per-vertex work at runtime. Same
-// parser, same subset, same result as loadGltf; this only moves the cost
-// to build time. Put the output under assets/ so it ships with the app.
-// Everything here comes from the runtime-free `@solidrt/3d/model` entry
-// (src/model-data.ts), the same surface an app's own bake script uses.
-//
-//   srt tool 3d/model <in.gltf|in.glb> [-o <out.srtm>]
-
-import { readFileSync, writeFileSync } from "node:fs"
-import { basename, dirname, extname, join } from "node:path"
-import { encodeModel, layoutStride, parseGltf } from "../src/model-data.ts"
-
-function usage(error?: string): never {
-  if (error) console.error(error)
-  console.log("Usage: srt tool 3d/model <in.gltf|in.glb> [-o <out.srtm>]")
-  process.exit(error ? 1 : 0)
-}
-
-let input: string | undefined
-let output: string | undefined
-let args = process.argv.slice(2)
-for (let i = 0; i < args.length; i++) {
-  let arg = args[i]!
-  if (arg === "--help" || arg === "-h") usage()
-  else if (arg === "-o" || arg === "--output") {
-    output = args[++i]
-    if (output === undefined) usage("Missing value for " + arg)
-  } else if (arg.startsWith("-")) usage("Unknown option " + arg)
-  else if (input === undefined) input = arg
-  else usage("Unexpected argument " + arg)
-}
-if (input === undefined) usage("Missing input file")
-if (output === undefined) output = basename(input, extname(input)) + ".srtm"
-
-let dir = dirname(input)
-let bytes = new Uint8Array(readFileSync(input))
-let started = performance.now()
-let data = parseGltf(bytes, (uri) => new Uint8Array(readFileSync(join(dir, decodeURIComponent(uri)))))
-let parsed = performance.now() - started
-let encoded = encodeModel(data)
-writeFileSync(output, encoded)
-
-let triangles = data.parts.reduce((n, p) => n + p.geometry.indices.length / 3, 0)
-let vertices = data.parts.reduce((n, p) => n + p.geometry.vertices.byteLength / layoutStride(p.geometry.layout), 0)
-let targets = data.parts.reduce((n, p) => n + (p.geometry.morphs?.names.length ?? 0), 0)
-console.log(
-  `${output}: ${data.nodes.length} nodes, ${data.parts.length} parts, ${vertices} vertices, ${triangles} triangles, ` +
-    (targets > 0 ? `${targets} morph targets, ` : "") +
-    `${data.clips.length} clips, ${data.materials.length} materials, ${data.images.length} images, ${(encoded.byteLength / 1024).toFixed(0)} KiB ` +
-    `(parsed in ${parsed.toFixed(0)} ms)`,
-)