tosijs-3d 0.8.3 → 0.8.5

package/CHANGELOG.md

@@ -6,6 +6,610 @@ All notable changes to **tosijs-3d**. This project is pre-1.0 (`0.x`), so minor
 versions may carry breaking peer-dependency changes — each is called out in a
 **⚠️ Breaking** block in its version section below, with what a consumer must do.
 
+## 0.8.5
+
+**Weather you can watch.** Storms that darken the day and strike: lightning
+that lights the cloud from below, inside and above, lights the landscape and
+throws shadows, with thunder at the speed of sound. Shafts of sun through a
+broken sky, and the sky and sun seen through the water from below, with rays
+fanning down from them. Rain and snow from the weather, the wind carrying
+aircraft and buffeting them in a storm. And two long-hidden bugs: the cloud
+deck's local weather was mirrored north-south, and on the doc site no shadow
+map had rendered at all.
+
+Size: barrel (min, packages external) 883.2 KB raw / 295.6 KB gz (+5.7% gz),
+for lightning, light shafts, weather cells, trails and caustics.
+
+### Fixed
+
+- **Lightning lit the land through cloud-shaped shadows** (Tonio: "the
+  directional light seems to be coming from above the cloud layer ... the
+  shadows are mostly cloud"). The projected cloud shadow multiplied the
+  whole lit colour, flash included; a flash starts BELOW the cloud, so the
+  cloud shadow now fades while the deck is flashing (`strengthSource`, read
+  at draw time).
+- **Moonlight made shafts as bright as noon.** The shafts' colour was
+  normalised and never scaled by the light's intensity; the skybox puts the
+  moon in the same light at night. They now scale with it (moon shafts are
+  real, and faint).
+- **Shafts are SMALL where they leave the deck or the surface** (Tonio: the
+  wider they are, the more obvious any mismatch with the gap): sky `width`
+  200 -> 40 m (4 m near closed cover), underwater rays 0.2-0.8 m.
+
+- **No shadow map rendered on the doc site, the sun's included.** Babylon's
+  shadow generators lazy-load their shaders from code-split chunks, and each
+  chunk loaded a second copy of the site bundle (tosijs-ui#191), which threw,
+  so the shaders never loaded and every `isReady()` stayed false. The site
+  entry now imports the shadow shaders statically and tells the generators
+  they are loaded (site-only workaround; the library is unaffected).
+
+- **Thunder kept playing after leaving the page** (Tonio). Thunder is
+  scheduled ahead on the audio clock (a storm 2 km off rumbles 6 s after its
+  flash, for 4 s), and disposing `<tosi-b3d-lightning>` neither stopped it
+  nor closed the context. It now closes its AudioContext, silencing
+  anything queued at once and no longer leaking a context per visit.
+
+- **The cloud deck's local-weather texture was MIRRORED north-south.**
+  Babylon's ground rows run from +Z to -Z; the texture's rows the other way.
+  Everything reading the texture (local coverage, storm gloom, the cloud
+  shadow) put storms and orographic cloud at the mirror image of where they
+  were, invisible when a storm sat near the deck's centre. The lightning
+  demo's storm, 1.3 km off-centre, was drawn 1.3 km the other way, so every
+  strike lit empty sky. Pure `packWeatherTexture` flips the rows, tested.
+- **A storm's sky only closed at its very core**, so from below you looked
+  up through gaps at the inside of the tower, which read as the deck's
+  BOTTOM bowing upward (Tonio). A storm now counts in full in the coverage
+  (its share is taken out of the ramped field and added back whole): a cell
+  of 1.8 closes the sky over the inner half of its radius, the base stays
+  flat, and only the top skin rises into the tower. From above the ceiling
+  bulges up; from below it is a flat, solid underside.
+- **A strike lit the cloud one frame late** (the deck pushed its flash before
+  lightning set it); the flash is now written at draw time. It also lights
+  the TOP skin, so a tower seen from the side glows, and the ground light
+  sits halfway between the cloud base and the terrain under the strike.
+
+- **The launcher demo's left stick did nothing** (board #2434). Since the
+  GTA-style remap the biped mapping sends A/D and left-stick X to `strafe`
+  and only the right stick to `turn`; three doc demos (launcher, warhead,
+  the controller's rover) still steered on `turn` alone, so the glass
+  pad's stick and A/D were dead. They now steer on either.
+
+- **Orographic cloud filled the whole sky over land** (Tonio: "orographic is
+  the problem. It fills the transparent areas without changing apparent
+  cloud coverage"). The lift was measured from ABSOLUTE height, so with Land
+  and Sky's sea at 147 m every bit of land counted as mountain and added
+  +0.5 to +0.75 coverage: a 0.3 sky rendered as a solid grey sheet. It is
+  now measured from the SEA (the scene's water surface) and weighted to
+  RIDGES (ground above its surroundings); a high flat plateau keeps 35% of
+  it. Pure: `cloud-field`'s `orographicLift`, tested. `orographicPeak` is now
+  the height above the sea.
+
+### Added
+
+- **Lightning casts shadows** (Tonio: "spin up a shadow map and retain it
+  between strokes and just use it for the brightest strike"). ONE shadow map,
+  kept; re-rendered once per new brightest ground strike, never per frame.
+  The strike's light is a POINT light by default (`flashLight`), from the
+  middle of the channel, so shadows radiate from the bolt (a cube map: six
+  renders per strike); `'directional'` is the one-render option for low-end
+  devices. Casters within `shadowRange` of you (and of the strike, for a
+  point light); `shadows`, `shadowSize`. It replaces the old point light, so
+  the scene stays within a material's 4-light budget. The lightning demo now
+  has hills, trees and a hamlet under the storm.
+- **A storm darkens the day around it** (Tonio: "cut ambient and even sun
+  brightness somewhat when lightning is flashing ... by half"): new
+  `darken` on `<tosi-b3d-lightning>` (0.5) takes the sun and the ambient
+  fill down by half at full storm, easing with distance and strength,
+  through the cloud deck's own light handling (`deck.stormDim`) so the two
+  cannot compound. The deck's gloom no longer dims lightning's own lights
+  (it was cutting the landscape flash by up to 90% under cover).
+- **Land and Sky: a "lightning storm" toggle** beside the volcano: the storm
+  gathers in front of you over 20 s, strikes, rains and throws strike
+  shadows, then drifts away east.
+- **Lightning is dramatic** (Tonio: "having the lightning be dramatically
+  bright"): each strike lights the WHOLE landscape from above (falling off
+  with the storm's distance), the tower from inside, harder, and the bolt
+  carries an additive halo. New `brightness` (the drama) and `rate` (how
+  often, a multiple of the natural rate; pure `strikesBetween` takes it,
+  tested) on `<tosi-b3d-lightning>`; `groundLight` default 2.5 -> 6. Storm
+  lightning also brightens the WHITEOUT when you are inside the cloud. The
+  landscape flash is strong enough for a dark ground to read as lit (peak
+  3.5, halving at 6 km; the ground light reaches 6 km). The
+  demo has a scene panel: storm size,
+  how often, cloud cover, brightness, time of day. A storm is no longer a
+  TOWER by default (Tonio: "it basically looks terrible"): the deck's
+  `stormRise` defaults to 0 (opt-in, domed when on), so a storm is more
+  cover and lightning. From below the flash lights the underside and the
+  ground, inside it the whiteout, above it the top.
+- **Weather reaches the airframe** (board #1125). `<tosi-b3d-aircraft>` asks
+  the scene for the weather where it is: the WIND carries it (it chases an
+  air-relative velocity, so a crosswind crabs it downwind), and a STORM
+  buffets it — seeded disturbance on pitch, roll and climb that the attitude
+  controller fights back toward the stick. Strong wind alone adds a little.
+  New attributes **`turbulence`** (`'on'`/`'off'`, default on) and
+  **`turbulenceScale`** (default `1`), and a read-only **`turbulenceLevel`**
+  (0–1) for a HUD or a debug readout. The disturbance is the pure, seeded
+  **`turbulence(t, seed, level)`** in `fly-by-wire`. Nothing happens on the
+  ground or in an owner without the weather service.
+- **Light shafts** (WEATHER-DESIGN stage 4, board #1084), to Tonio's model
+  (pure half: **`light-rays`**): **`<tosi-b3d-light-shafts>`** hangs shafts
+  from the gaps in the cloud deck, BELOW it, running along the sun and
+  widening slightly (`spread`), and as broad as the gaps: `width` at the
+  0.5 threshold down to slits as the cover closes toward 1. An additive,
+  flat fill of the sun's colour — `strength` 0.35 at the cloud, linear to 0 — most prominent looking toward
+  the sun (a forward-scatter phase, per pixel), and only where the local
+  cover is broken: 0.5 up to (not including) 1. Placement searches a fine
+  grid near you as well as a coarse one far out, keeps one shaft per gap,
+  and only refuses a shaft that would pass through you, so a deck just
+  above your head (Land and Sky) gets shafts too. The same model runs UNDER
+  THE WATER: shafts from the surface, bent by Snell's law, sunlight tinted
+  by the water's fog, shimmering as cells come and go (`underwater`,
+  `underwaterCount`). SURFACE TURBULENCE drives them (the wind over the
+  water, its `waveHeight` and `bumpHeight`): calm water gives a few broad,
+  slow rays, choppy water many narrow ones that flicker (`waterRoughness`,
+  `waterRayShape`; `waterRoughness` on the element reads it back). The doc
+  page has an underwater demo. Shafts are RECTANGULAR (`spread` 0), so
+  perspective alone makes them radiate from the sun; sky placement is
+  weighted hard toward the sun's position in view, and underwater rays are
+  biased toward the viewer so the middle of the view is not empty. Rain adds
+  to the strength.
+- **The weather-cell demo has a frame of reference** (Tonio: "it has no
+  frame of reference so it just looks like leaves blowing around"): a row of
+  flagpoles you fly past, each flag showing the wind WHERE IT STANDS
+  (streaming downwind, limp in the lee), and the lee's edge drawn as a ring
+  on the water.
+- **The sky through the water, from below** (`b3d-water` `undersideSky`,
+  default 1; Tonio: "we want to see the sky and sun through and distorted by
+  the water surface"). The window no longer shows a flat colour: a small
+  reflection probe photographs the sky with its fog and veil OFF, and the
+  underside refracts it through the water's own ripples, so the sky and the
+  sun arrive bent and moving. Clearest in the shallows, fading with depth,
+  giving way to the dark mirror at grazing angles. The probe is HALF-FLOAT
+  and captures the sun as HDR (a new skybox uniform, `b3dSunHdr`, 0 in
+  normal rendering), so the sun still punches through the partial
+  transmission of the surface (Tonio: "our skybox isn't HDR so its glare
+  doesn't punch through"). (It replaces a glare sprite that looked fake.) Underwater rays are fewer (`underwaterCount`
+  12, lower presence).
+- **Rain and snow from the weather** (WEATHER-DESIGN stage 5, board #1124).
+  `b3d-ambient` gains `weather: 'rain' | 'snow'`: emission follows the
+  PRECIPITATION where the viewer is, so a storm brings its own rain and it
+  eases in and out as the storm passes; the local temperature splits rain
+  from snow (sleet between). Rain now draws as STREAKS stretched along its
+  velocity, so the wind visibly slants it. Land and Sky's storm rains.
+- **Lightning and thunder** (WEATHER-DESIGN stage 3, board #1123):
+  **`<tosi-b3d-lightning>`** strikes under every weather cell with
+  `storminess`, seeded (same seed, same storm; frame rate cannot change it).
+  Cloud-to-ground strikes draw a jagged, branching bolt that flickers through
+  its re-strokes and light the ground; every strike lights the cloud deck from
+  INSIDE around it (`deck.flash()`, a new hook: why storms want coverage past
+  1); thunder is procedural and arrives at the speed of sound, so you can
+  count the distance; and over strong storms, rarely, **sprites**: brief
+  red-pink crowns with purple tendrils high above the tower. Each strike
+  dispatches `strike` with `{ kind, x, z, t, distance }`. The pure model is
+  `lightning.ts` (`strikesBetween`, `boltPath`, `flashAt`, `thunderDelay`).
+  Land and Sky's storm now brings lightning.
+- **Weather, stage 2: a storm you can see** (board #1122). A
+  `<tosi-b3d-weather-cell>` with `coverage` joins the cloud deck's local
+  weather field: denser cloud over it, a greyer, heavier underside (its own
+  "gloom" channel, so orographic cloud still never repaints fair weather as
+  foul), the storm's shadow on the ground beneath (the shadow reads the same
+  field), and full strength even when the global dial says clear. A drifting
+  cell re-bakes about once per 10 m of travel.
+  Land and Sky has a **storm** toggle in its Weather group: a storm drifting
+  with the wind (the scene's wind now matches the deck's) that passes over
+  you and recedes into view.
+  Cells gain **`grow`** (seconds to gather from nothing to full), so a storm
+  builds rather than appearing; the deck re-bakes in 1% strength steps as it
+  does. Across SPACE a cell was already gradual: a smoothstep over its whole
+  radius, smoothed again by the deck.
+  **Storm towers:** cell coverage now runs to 2, and past 1 is THICKNESS,
+  as on the deck's own dial: the deck lifts its top skin there by up to
+  `stormRise` (1,500 m), whatever the global dial says, so a storm is a dark
+  heavy base from below and a bright tower from above, and the thing
+  lightning will light from inside. The cell channels get one smoothing pass,
+  not the orographic field's four (which flattened a storm's excess from 0.7
+  to 0.18). Land and Sky's storm is coverage 1.7.
+- **Weather, stage 1: the weather where you are** (WEATHER-DESIGN.md, board
+  #255). `b3d.weatherAt(x, z)` (and `weatherHere()`) answers what every
+  weather consumer asks: the scene's base wind plus every
+  **`<tosi-b3d-weather-cell>`** that reaches the point, composed per quantity
+  (wind and temperature sum, coverage sums clamped, precipitation and
+  storminess take the max). Clouds, water and ambient now read the wind AT
+  THE VIEWER rather than one scene-wide value, so a lee is calm and a squall
+  is local. A cell with `drift="wind"` travels with the wind (a weather
+  system), and `lifetime` grows, holds and ends it. The pure model is
+  `weather.ts`. Measured on the new page: leaves' wind 12 → 0.96 m/s crossing
+  a lee's centre.
+- **Caustics** (board #198, tosijs-3d#16): light through the moving surface,
+  dancing on whatever is beneath a `twoSided` `b3d-water` (`caustics`,
+  `'auto'` = on whenever `twoSided`; `causticsStrength`, `causticsScale`).
+  Projected by world position through a material plugin (the cloud-shadow
+  technique), so terrain, hulls and the player all get it with no per-mesh
+  setup; slants with the sun, shimmers (two moving layers, combined with
+  `min`), fades with depth and fog, and goes with the sun. The pattern is a
+  seeded, tiling cellular web (`causticPattern`), with no file to fetch.
+- **One lattice per world, enforced where code can** (board #257,
+  tosijs-3d#75): every `extractChunk` result carries its `lattice` identity
+  (`latticeIdentity(cfg)`), and `assertLatticesWeld(chunks)` throws on a
+  mismatch instead of leaving a crack. TUNNEL-DESIGN.md records the decision
+  that carves are world-level objects provinces declare but don't own, so a
+  tunnel between provinces is just a carve in the field.
+- **Snell's window: the water's underside** (board #197, tosijs-3d#15). Looking
+  up from under a `twoSided` `b3d-water` used to show flat dark blue. Now
+  (`underside`, `'auto'` = on whenever `twoSided`) it is a bright window onto
+  the sky overhead, darkening to a mirror of the depths toward grazing angles,
+  rippling with the same normal map as the surface, and fading in with the
+  underwater fog's own band weight. One plane, one draw call, only while
+  submerged. `undersideColor` / `undersideDepthColor` tune the two ends. It
+  stays OPAQUE and the sky stays fogged, unlike the prototype, so a level look
+  under water still sees murk rather than sky.
+- **`b3d.debugFogColor`** (`'#ff00ff'`) paints the composited fog a colour
+  nothing else is, to tell fog from surface from sky; also a toggle on the
+  Perf Stats panel's new Fog row (with density, end and veil), for a headset.
+- **`<tosi-b3d-trail>`** — a ribbon behind anything that moves (contrails,
+  missile smoke, a fast enemy's wake), lifted from manta-recon's engine
+  contrails (tosijs-3d#4, board #186). Nest it in the mover, give it a local
+  offset; it measures speed at its own emitter (so it works on anything),
+  fades below `minSpeed`, takes `underwaterColor` below a `<tosi-b3d-water>`,
+  re-attaches when the host's mesh is replaced (respawn, async load), and
+  resets on a floating-origin shift. **`attachTrail(node, scene, options)`**
+  is the same for a node you hold, such as a spawned missile.
+  Missiles get it for free: `<tosi-b3d-launcher missile-trail="on">`, or
+  `trail` on `spawnProjectile`/`spawnMissile` for your own rounds.
+- **Frame panels are usable as menus** (board #768, tosijs-3d#92, from
+  manta-recon moving its outer game to viewer-relative panels):
+  - **They route pointers.** A `panel3d` on a frame panel now takes presses,
+    drags and hover from mouse, touch and XR rays (the same routing
+    `b3d-svg-plane` has), and repaints immediately on press and release rather
+    than on the texture's 400 ms timer. Before, the buttons drew and ignored
+    every click, with no error.
+  - `attachFramePanel` returns its **`mesh`**.
+  - **`resolution`** on `FramePanelSpec` (and `<tosi-b3d-panel resolution>`):
+    384 suits a reticle, not a menu of text.
+  - **`flatFrame` applies to any panel**, not only hand panels, so
+    `flatFrame: 'face'` measures a flat panel's elevation from the VIEW rather
+    than the off-screen horizon of a pitched camera.
+- **Flying under water feels like water** (board #185, manta's #3). A
+  `submersible` aircraft now meets a thicker MEDIUM below the surface:
+  `waterDrag` (×10 by default, the 2010 Manta's air:water ratio) multiplies
+  drag, blended over `waterTransition` metres. The controls are unchanged; full
+  throttle settles at ~32% of `maxSpeed`. **`surface-crossed`** fires on each
+  crossing with `{ entering, point, speed, aircraft }` for splash, wake and
+  audio cues, and **`submerged`** (0–1) is readable. In the pure model:
+  `FlyByWireConfig.mediumDrag`, and drag now clamps at rest instead of
+  overshooting into reverse on a long frame.
+
+### Fixed
+
+- **Replacing the player left input focus on the removed one** (board #2421,
+  from manta-recon's respawn): the new craft got no input and its crash was
+  ignored by `b3d-death`. A controllable now releases focus when it is
+  disposed, and `adoptIfVacant` treats a disconnected focused entity as a
+  vacant seat. No more `releaseFocus()` before the swap.
+- **Ambient wind accumulated every frame and flung particles away**: the
+  preset's direction vectors were assigned by reference, and the per-frame
+  `direction.set(preset + wind)` wrote into the preset, so the wind grew frame
+  on frame (drops at kilometres a second, never seen). Cloned now, and the
+  particles take the INHERITED wind (scene and weather cells), not only the
+  element's own `windX`/`windZ`.
+- **Flat eye-anchored panels trailed a moving camera by one frame** (board
+  #767, found by manta-recon at 2.15 m per frame behind b3d-aircraft's follow
+  camera). The flat frames are now posed on `onBeforeCameraRenderObservable`,
+  after anything that moves the camera during the render. Measured: 0.000 m
+  gap over 64 frames of a camera moving 2 m per frame.
+- **Every scene with a glass gamepad logged a type warning** (`gamepad is
+  declared boolean … but was written string`). `gamepad` is genuinely
+  `boolean | string` (`true` = the default layout, a string = a layout), so
+  it is now a plain property read once at setup rather than a typed attribute.
+  Markup (`gamepad`, `gamepad="…"`) and `b3d({ gamepad })` are unchanged.
+- **`b3d-terrain.recenter()` threw away an authored `worldU`/`worldV`** (board
+  #458), resetting them to the defaults. It now clears the travel (the
+  floating-origin offset) and leaves the placement alone.
+
+## 0.8.4
+
+**A sky you can actually see the stars in, and a world with things growing on
+it.** The encoded sky is decoded exactly (sharp points, not smeared blobs),
+twinkles, and is rebaked from the new voxel galaxy — one galaxy implementation
+now, with stable star addresses and a biased "interesting stars" population.
+Worlds get their own air and dust (a black noon on the Moon, a butterscotch
+Mars), cosmetic extra moons whose phase follows the sun, and render resolution
+follows the display by device tier. `<tosi-b3d-decorator>` scatters rocks and
+trees by budget and biome, with near-only shadows and colliders. Plus a
+batch of adopter fixes (ensemble's #76–#91, touch-orbit #52) and review
+follow-ups, and the first release through the OIDC + staged publish flow.
+
+Size: barrel 837.8 KB min (+5.6%) · **279.6 KB gz (+6.3%)**; dist total 1.30 MB gz (+4.3%).
+
+> **Visible, not breaking:** every `PRNG`-seeded output re-rolls (xoshiro128\*\*
+> replaces the Mersenne Twister), so a given seed produces a different galaxy,
+> star system, cloud field, crowd and spawn sequence from 0.8.3 — "same seed,
+> same battles" holds within 0.8.4, not across the upgrade. The shipped sky is
+> rebaked (and now served from a versioned URL). Deprecated names still work
+> and warn once: `generateGalaxy` (use `voxelGalaxy`), `onEnter`/`onExit` on
+> the trigger, `handleChange`/`handleCommit` on the manipulator
+> (`whenChange`/`whenCommit`). `registerIcons` now refuses markup that can run.
+
+### Fixed
+
+- **Dropdowns in a panel with a pinned header opened over their own
+  control** — body popups were anchored as if there were no header, too high
+  by its height. The in-VR scene panel has one (the transport bar), so this was
+  every select in the headset. Header widgets also get a host now, so a
+  `select3d` pinned in a header can open at all.
+- **`FrameInfo` keeps wall-clock time while paused**, as documented:
+  `realDt`, `realElapsed` and `frame` advance on a paused (still rendering)
+  frame; `dt` and `elapsed` stay stopped. They used to freeze too, which broke
+  the one case they exist for — a spinner on the pause panel.
+- **Floating origin reaches the placeables.** `b3d-prop`, a standalone
+  `b3d-beacon` and a place-anchored `b3d-spawner` drifted on a terrain rebase;
+  they now shift with it. The shared piece is `AbstractMesh.followOrigin()`,
+  which `b3d-destroyable` now uses too.
+- **`b3d-trigger` no longer calls BOTH `whenEnter` and `onEnter`** — the new
+  name wins and the old one warns once, like every other deprecated callback.
+  `themeEditor` reads `handleChange`/`onChange` the same way (it never warned).
+- **A table's row-button menu opened low** by the COLUMN gap; it is now
+  anchored at the row.
+- **A log slider with `zeroStop` ignored `step`**; it quantises in decades
+  like one without.
+- **`registerIcons` refuses markup that can run** (`<script>`, `on*=`
+  handlers, `<foreignObject>`, `javascript:` URLs) with a warning; the trust
+  boundary is now documented.
+- Clouds, ambient and water share one wind-inheritance rule
+  (`inheritedWind`); `vector3d`/`footprint3d`/`curve3d` import `handlerOf`
+  from its own module rather than dragging in `widgets3d`.
+- **Stars were smeared into soft plus-shaped blobs.** The sky's star decoder
+  placed each star relative to whichever tap fetched its texel, so it moved
+  as the fragment moved and was drawn across the whole texel (sometimes twice,
+  when two rotated taps hit one texel). It now walks the 3×3 neighbourhood in
+  texel space and rebuilds every star from its own texel and sub-texel offset,
+  through an exact GLSL mirror of the codec's cube convention. Also, **the
+  data cube had mipmaps**, despite a comment saying otherwise: a mip of packed
+  fields is data nobody encoded. They are off now.
+- **Airless sun and moon vanished** (the moon kept only its glow). The sky
+  model draws both through scattering, so without air there was nothing left.
+  Real half-degree discs now fade in as the air goes, and the glow fades with
+  it: a hard white sun and moon on a black sky. The airless moon is as bright
+  as the moon seen through air.
+- **The voxel galaxy's disc was built of slabs** (seen by Tonio as
+  "ellipsoid columns" at 1M stars). Voxel layers (0.03 at `nz` 20) were as
+  thick as the disc, so stars sat in flat slabs with hard edges. `nz` now
+  defaults to 60. Every voxel address changes (0.8.4 already rerolls the
+  galaxy), and the shipped sky is rebaked with a slightly crisper band.
+- **Big objects in the star sky were clipped square**, and **packed stars sat
+  on a lattice.** Objects wider than the decoder's 3×3 reach (distant galaxies
+  run to 3.5 texels) were cut at texel edges. Everything now tapers to nothing
+  within a texel. Packed stars in the dense core, known only to a quarter
+  texel, were drawn at their cells' centres, which formed a lattice the cube
+  projection bends into curves. They now get a deterministic jitter within the
+  cell (error diffusion for position).
+- **`atmosphere` just below 1 made the clouds vanish.** 5% vacuum pushed a
+  1–4 km fog out past 50 km, and the haze that hides the cloud deck's rim went
+  with it. The world's air is now steep, nearly binary (vacuum is
+  `(1 − atmosphere)⁴`): 0.95 is Earth, and only the last stretch thins the sky.
+- **Touch on the orbit camera: two fingers pan, a pinch zooms** (tosijs-3d#52).
+  Babylon's default does both on every two-finger move, with zoom from the
+  change in SQUARED spacing, so a drag read as "a weird zoom"; its alternative
+  mode turns a slow pinch into a pan for good. New **`touchOrbit(camera)`**
+  (wired into `<tosi-b3d>`'s default camera and `orbitCam`) decides once per
+  gesture from NET spread vs NET centroid travel, then locks. Pan follows the
+  fingers (pixels → world units at the target's depth), and zoom is natural.
+  Pure decision model in **`touch-gesture`**, unit-tested; measured in
+  headless Chrome with emulated touch: a 150 px two-finger drag now moves the
+  target 2.35 m with the radius unchanged, where before it moved 0.76 m and
+  zoomed 8 → 8.68.
+- **Vacuum hid the stars it was supposed to reveal.** The space band's fog
+  layer defaulted its sky veil to its weight, so leaving the atmosphere
+  painted the sky black OVER the starfield. Vacuum is the absence of a
+  medium; it now thins the haze without veiling the sky. Found building
+  `atmosphere: 0`, and it applies to the rocket climb too.
+- **A field outside an attached `fieldGroup` swallowed keystrokes silently**
+  (tosijs-3d#82). Attaching any group stood the global key listener down for
+  EVERY field, so a tapped field outside it showed a caret while its keys went
+  to the group's active field or nowhere. Now the listener stands down only
+  for fields an attached group owns, and a field outside every group that
+  takes focus makes those groups let go. `fieldGroup` gains **`add(field)`**,
+  so a field created after the group can join it rather than depending on
+  construction order.
+- **A page that mounted and removed scenes hit Chrome's WebGL context cap**
+  (tosijs-3d#79). Babylon's `engine.dispose()` keeps the context alive unless
+  `loseContextOnDispose` is set, so every removed scene held one until GC, and
+  Chrome force-loses the OLDEST live context past its cap — the scene you are
+  looking at goes black. Teardown now releases the context, and an element
+  re-added after a removal gets a fresh canvas (a lost context is permanent
+  for its canvas). A genuine re-add no longer warns "an engine already
+  exists". `bun bin/context-cap.ts` checks it in headless Chrome: 50 trips
+  with the removed elements retained; the live scene rendered nothing before
+  the fix and renders now.
+- **Starfield attributes were construction-time only** (tosijs-3d#88). Setting
+  `starfieldData`, `starfieldCube`, `starfieldTilt`, `nebulae`, … on an
+  existing sky did nothing — no request, no stars, no error. They rebuild the
+  starfield now; the dome is untouched. A dispose also releases the cube
+  textures (a moved sky used to leave them behind).
+- **A sky given `starfieldData` alone drew no stars.** The build returned
+  early unless `starfield` or `starfieldCube` was set, although the data cube
+  stands on its own.
+- **`slider3d`, `toggle3d` and `select3d` rejected the reactive boxes they
+  are designed to bind** (tosijs-3d#76) — 24 false type errors in one
+  consumer panel. `value` is `Bindable<T>` now (exported): a `T` or anything
+  with `.value` and `.observe`.
+- **`spaceStart`, `spaceFull` and `starDistance` said `unit` where every other
+  schema field says `x-unit`** (tosijs-3d#85). A test now rejects a bare `unit`.
+- **`azimuth` is out of `skyboxSchema()`** (tosijs-3d#86). It has been a no-op
+  since the sky material fork (the sun is placed by `latitude` and
+  `timeOfDay`), and the schema offered it as a 0–360° slider while the docs
+  called it a 0–1 fraction. Still accepted in markup; documented as ignored.
+- **A cloud deck forgot its local weather on a re-parent.** Its bake memo
+  survived `sceneDispose`, so the fresh mesh stayed unbaked — orographic cloud
+  gone — until some input moved. A deck moved into another `<tosi-b3d>` also
+  kept sampling the OLD scene's terrain (a narrow regression from 0.8.3's
+  cached lookup). Both reset on dispose now.
+- **The deck did per-frame work it did not need.** With no field in force
+  (orographic 0, no `weather`) it re-baked zeros on every grid snap and every
+  terrain rebuild; and the fly-into-cloud whiteout rebuilt the whole weather
+  field — a fresh terrain height sampler — every frame to sample one point.
+  The first bakes once; the second samples the field the bake already built.
+
+### Added
+
+- **Undo for the two page-global mutations.** `themeEditor()`'s element has
+  `restore()` — the palette as it was when the editor was built, then
+  `handleChange` so you rebuild. `registerIcons()` now RETURNS an undo that
+  removes the names it added and brings back any icon it replaced.
+- **`<tosi-b3d-moon>`** — cosmetic extra moons (tosijs-3d#89). Put up to
+  four inside a `<tosi-b3d-skybox>`: `azimuth`/`elevation` on the star
+  sphere (they ride with the stars), `size` (angular diameter, degrees),
+  `color`, `brightness`. The PHASE is automatic: each disc is shaded as a
+  sphere lit by the real sun, so a moon near the sun is a crescent and one
+  opposite it is full. A moon hides the stars behind it; it casts no light.
+- **`voxel-galaxy`** (`tosijs-3d/voxel-galaxy`) — the first step of
+  `GALAXY-DESIGN.md`: a galaxy as voxels, each with a derived bright and dim
+  seed. `brightStars()` is the global pass; `dimStarsNear(point, radius)` is
+  the local one the skybox baker will use. Density is sampled from
+  `generateGalaxy` and propagated so no voxel is empty; stars are addressed
+  `population:voxel:n` (no shared-seed clones). `galaxy-data` exports `starDetailFor`, `SPECTRAL_CLASSES`
+  and `SPECTRAL_WEIGHTS`, split out so both generators share one definition.
+- **The baker reads the voxel galaxy** (`GALAXY-DESIGN.md` step 2):
+  `starsFromVoxelGalaxy(galaxy, shell, eye, { dimReach, floor })` gives every
+  bright star (today's rule — intrinsic brightness), the dim stars near the
+  eye falling off with distance (the gather radius computed from the floor,
+  not guessed), and the distant shell. `bakeSkyPair` takes precomputed
+  `objects`; `bin/bake-stars.ts` rebakes `static/sky/stars_*` without a
+  browser in ~1 s for the tuning loop; `SHIPPED_SKY.voxel` holds the dials.
+
+### Changed
+
+- **`b3d-manipulator` callbacks are `whenChange` / `whenCommit`** — the
+  component convention. `handleChange`/`handleCommit` still work, warn once,
+  and are removed in 0.9.
+- `AbstractMesh.applyUniformScale()` replaces the identical private copies in
+  `b3d-prop` and `b3d-destroyable`.
+- **ONE galaxy implementation** (GALAXY-DESIGN.md → "Reconciliation").
+  The voxel galaxy is the galaxy now. `b3d-galaxy`, `b3d-star-system`, the
+  skybox baker and `bin/bake-stars` all read it. Its nebulae and distant shell
+  have their own derived seeds, so they no longer depend on the star count.
+  - **Visible:** a given seed now produces a **different galaxy** from 0.8.3
+    (same shape and distributions, different stars), and `starCount` is the
+    galaxy's **bright budget** (±noise), not an exact count.
+  - **`generateGalaxy` is deprecated** (removed in 0.9). It is now an adapter
+    returning `voxelGalaxy({ seed, brightBudget }).view()`. The spiral model it
+    was built on survives as **`sampleSpiral`**, which the density is sampled
+    from.
+  - **Stars have an address:** `id` is `seed:population:voxel:n`, with a
+    sequence number rather than the derived seed. `galaxy.star(id)`,
+    `b3d-galaxy.getStar(id)` and `b3d-star-system`'s new `star` attribute
+    resolve it. Star _n_ never depends on the budget, so an address resolves
+    even in a galaxy computed with a smaller one.
+  - **New:** `voxelGalaxy().view()`, `.star(id)`, `.nebulae()`, `.shell()`;
+    `b3d-galaxy`'s `dimBudget`; `starAddress` / `parseStarAddress`,
+    `starNameFor`, `sampleSpiral` and `starsFromVoxelGalaxy` in the barrel.
+  - **Interesting stars.** The dim population splits in two. **Interesting**
+    stars have a planet with HI ≤ 2 (breathable or filterable air, under 2 g,
+    not extreme); they are generated globally, so the galaxy demo's HI filter
+    sees every habitable system with its HI already known. **Boring** stars
+    are generated only locally, as sky texture. Both are exact: candidates are
+    drawn from a spectral mix biased by measured pass rates, then verified with
+    the real HI rules. The rates come from a harness, **`bin/tune-populations.ts`**,
+    which writes `population-table.ts`. A fingerprint test fails when HI
+    changes, and the fix is to rerun it. HI 3 is deliberately not
+    "interesting": it has no air requirement, so the Moon and Mars are HI 3.
+    `generateGalaxy` (deprecated) keeps meaning bright stars only.
+  - **`PRNG` runs on xoshiro128\*\*** (new **`Xoshiro128`**, exported). MT
+    carried 624 words of state and regenerated them before its first draw,
+    so just constructing one cost ~13 µs, and a star system builds one per
+    planet. xoshiro has 4 words: 30–75× faster to construct and draw, and it
+    passes BigCrush and PractRand, which MT fails. A star system now costs
+    6.5 µs, down from 70. It is checked against an independent BigInt
+    transcription of the reference C. **Every `PRNG`-seeded output
+    re-rolls:** planets, the spiral samples, nebulae, the shell and the
+    skybox's point starfield. That is folded into this release, which already
+    changes every galaxy. `b3d-clouds`, `b3d-crowd` and `b3d-spawner` moved
+    too, so their seeded layouts (cloud blobs, crowd placement, spawn rings)
+    reroll once as well. `MersenneTwister` stays exported.
+  - **The shipped sky's nebula half is rebaked** with the new nebulae.
+    **`bin/bake-nebula.ts`** bakes it in headless Chrome and checks that the
+    point half on disk came from the same galaxy.
+- **Noted late, from 0.8.3: `slider3d`'s `peek` readout appears BESIDE the
+  caption rather than replacing it** (tosijs-3d#84). Deliberate — a label that
+  vanishes the moment you touch the control loses the name of what you are
+  adjusting — but it went unannounced, and a consumer test pinned the old
+  behaviour. Press and drag over the caption also work (the stacked layout made
+  the whole width the track); now pinned by a test.
+- **The shipped sky's stars are rebaked from the voxel galaxy** — 100k bright
+  stars plus the dim stars around the bake point (~119k objects, against 100k
+  before). Far more stars at night, and a dense local sprinkle across the
+  whole sky rather than only along the band. The band itself is a little
+  broader. `bun bin/bake-stars.ts` with no flags reproduces it byte-for-byte;
+  the smooth `nebula_*` half is unchanged.
+- **The shipped sky has pinned, versioned URLs** (tosijs-3d#90):
+  `/sky/0.8.3/…` (the previous sky) and `/sky/0.8.4/…` (this one), each with a
+  `manifest.json` holding the decode parameters and the recipe.
+  `/sky/stars` stays "latest" for the demos; a document should pin a version.
+  `shipped-sky.test.ts` fails if latest drifts from the newest version.
+- **A world's own air, and its sky colour** (tosijs-3d#89). `b3d-skybox`
+  gains **`atmosphere`** (1 Earth … 0 the Moon: black noon, stars out, no
+  haze, a hard sun), which multiplies with the space band, and
+  **`zenithTint` / `horizonTint` / `tintStrength`**, which colourize the
+  scattered light only, keeping its brightness (a butterscotch Mars, a green
+  alien sky). Stars and moon are behind the air and stay untinted. Land and
+  Sky gains an **Atmosphere** group: a world preset (Earth / Mars / Alien /
+  Airless) plus live air, tint, turbidity, rayleigh, mie and luminance.
+- **Viewer-relative panels in the flat view** (tosijs-3d#81).
+  `<tosi-b3d-panel presence="both">` appears on a monitor as well as in a
+  headset, placed with the same frame vocabulary (eye / body / neck / face,
+  azimuth-elevation-distance, presets, gaze reveal). **`XrFrames.flat(scene,
+camera)`** derives the frames from any flat camera's world pose (the eye
+  frame takes the view's yaw, not its pitch). Hands have no flat analogue, so
+  a hand panel declares **`flatFrame`**; without one it stays VR-only and
+  warns once. `presence` defaults to `'xr'`, so existing panels are unchanged.
+- **`<tosi-b3d-decorator>` — rocks and trees on the terrain, by budget and
+  by climate.** The pure **`scatterPlacements`** model places a fixed NUMBER of things.
+  Its rules use the biome shader's own axes (temperature, moisture, altitude
+  above sea, slope), so pines grow in the cold, palms on warm shores, cacti in
+  hot dry country, and boulders on the steep. Candidates are world-anchored
+  and deterministic, and an acceptance threshold is solved to hit the budget.
+  Provinces suppress by kind (no plants on a lava field; rocks still). Models
+  come from Kenney's Nature Kit, drawn as thin instances: one draw call per
+  model part, whatever the budget. A small collider pool follows the camera:
+  trunks as posts, boulders as boxes. `measureCost()` steps through budgets
+  and reports frame time, GPU time (where exposed), draw calls and indices.
+  Land and Sky has a Vegetation group (budget 0–20k, reach).
+- **Render resolution follows the display, by device tier.** Scenes rendered
+  at CSS resolution, so a 1.25× or 2× display upscaled everything (soft edges,
+  soft stars). The render now uses the display's pixel ratio capped by tier:
+  high up to 2×, medium up to 1.5×, low at CSS resolution. The new
+  `PerfBudgets.pixelRatioCap` sets the cap, and **`<tosi-b3d pixel-ratio>`**
+  overrides it with an explicit value (`1` = CSS resolution, `2` = full
+  Retina, `0.75` = below CSS for speed). It follows a window moved to another
+  monitor, and XR is unaffected. The rule is `renderScalingLevel` in
+  `b3d-quality`, tested.
+- **Twinkle** (`starfieldTwinkle`, default 0.35): scintillation, which is
+  the air, so it scales with the gas (none on an airless world), is strongest
+  at the horizon, and each star flickers on its own pattern. Land and Sky has
+  a twinkle slider.
+- **`dust` on `b3d-skybox`** separates dust from gas. Gas (`atmosphere`)
+  scatters blue; dust scatters a bright grey haze that the tint colours. So
+  Mars is almost no air, lots of dust and a butterscotch sky (Land and Sky's
+  preset: air 0.03, dust 0.85), and the Moon is neither. The previous Mars
+  needed full air to be bright at all.
+- **Star look dials on `b3d-skybox`:** **`starfieldGain`** (brightness) and
+  **`starfieldFloor`** (the faint mass) join `starfieldSharpness` (size) and
+  `starfieldSizeScale`. All four are live uniforms, so a slider does not reload
+  the cube. With exact points the defaults moved to gain 0.9 and floor 0.4.
+  Land and Sky has a Stars group (size, brightness, faint stars).
+- **`slider3d({ useful: [lo, hi] })`** (tosijs-3d#83) — a soft band on the
+  track where the values anybody wants live; the handle still reaches `min`
+  and `max`. It is where a schema's `x-useful` lands.
+- **`cloudDeckSchema()`** in `sceneSchemas` (tosijs-3d#87) — the deck was the
+  one scene primitive a schema-driven consumer had to describe by hand.
+- **Fetched strings are marked in the scene schemas** (tosijs-3d#91):
+  `format: 'uri-reference'` on `starfieldData`, `starfieldCube`,
+  `nebulaTexture`, `water.normalMap`, `clouds.model` and `ground.texture`
+  (which also lists its keywords in `x-keywords`). A test fails on any new
+  plain string that is not a colour, enum, URL or deliberately listed.
+- **`bun run sizes`** — the barrel as a consumer bundles it, and the shipped
+  `dist/*.js`, against a committed `dist-sizes.json` (0.8.3: 263.1 KB gz).
+
 ## 0.8.3
 
 **A galaxy that costs nothing per frame, a sky that keeps the right time, and