mapspinner 0.1.1

package/AGENTS.md

@@ -0,0 +1,265 @@
+# mapspinner — agent working rules
+
+## SDK Validation Policy
+
+SDK changes must be validated against the test suite and verified in both the dev demo (planet.html) and external consumer examples. No changes ship without passing tests.
+
+## Architecture (GPU one-fractal)
+- Height pool: **R16F**, **1024 layers**, **4 mip levels**, 130-texel tiles. The ONLY runtime branch is a
+  FORMAT capability probe (`_useR16F` = half-float color+storage+linear) that falls back to the
+  numerically-equivalent R32F when the GPU lacks half-float — correctness, not a quality tier.
+  (`THC_CACHE_LAYERS` clamps to `MAX_ARRAY_TEXTURE_LAYERS`; 1024 was tuned from a live eviction
+  measurement — 512 evicted ~3155/s at the deck where ~594 leaves are visible, 1024 → 0/s. ~35MB vs
+  the old 138MB R32F/2048 = ~90% VRAM cut.)
+- Shader precision: **global `mediump float`** with explicit **highp islands** on every planet-scale
+  quantity (`vRel`/`vWorld`/`vH`, `defRadius`/`defViewProj*`/`defCam*`, all noise lattices + their args,
+  `broadShapeM`/`broadShapeLowM`/`faceWarp`/`vtxDisplace` metre accumulators, coordinate-snapped noise
+  anchors `rockO`/`wOrigin`). Validated SAFE live: `d.assertElevLinear()` pass, `d.pxPerPoly()` ~238k
+  tris rasterized. fp16 leaking onto a planet-scale value collapses the geometry — keep the islands.
+- Reduced octaves: `broadShapeM` 14→12, `vtxDisplace` 9→6, single-octave rock detail; tanh ceiling
+  `tanh(x/8000)` gives pointed peaks (CLI `shapeReport allGatesPass`). Distance-gated cheap FS far path.
+  Tightened LOD (`planet-orchestrator` splitFactor + near-radius). Dead atlas apparatus deleted.
+- The two new FS/VS uniforms `uHeightPoolTexSize` (=tile res) and `uFloatLinearOK` (=half-float-linear
+  probe) MUST be set on the main render program (`gl-render.js`) or the height-pool UV math goes to
+  `vec2(0)` → NaN displacement.
+
+WITNESS HEADLESS WITHOUT A FRAMED SCREENSHOT: don't judge "flat render" from a close-zoom shot whose
+camera you can't aim. Use the DATA diagnostics — `__diag.pxPerPoly()` (on-screen quads/tris rasterized),
+`__diag.assertElevLinear()`, `__diag.landWitness()`, and `window.__terrainConfig`/`__tcEvictRate`. Start
+`node server.js` (port 8080) yourself if it's down, then drive a fresh headless session to it.
+
+---
+
+## The terrain pipeline in one page (read this before touching terrain)
+
+Earth-scale terrain SDK, WebGL2, served at `http://localhost:8080/` (entry `planet.html`, `server.js`).
+GPU one-fractal: no Proland tile producer, no cascade. A finer
+LOD is a denser sample of the SAME field. The procedural broadShapeM fractal is the LIVE render
+path (hasAtlas==0, the default). The baked atlas is opt-in (planet-orchestrator.js opts.atlas===true;
+live `window.__toggleAtlas(on)` / `__forceAtlas`); its bake is CLI-validated faithful (atlas-bake.mjs
+`interiorExact` gate) and `broadShapeMD` central-differences `atlasHeight` so atlas-on land shades with
+relief. Do NOT delete the procedural path while the atlas is opt-in. Recall
+"tv8-atlas-flat-is-flat-normals-root-2026-06-07" + "tv8-reliable-visual-witness-method-2026-06-03".
+
+THE SPOOL `browser` VERB IS A FULL BROWSER, NOT HEADLESS (user correction 2026-06-11): it drives a
+locally-profiled Chromium with the REAL GPU + real ANGLE backend (witnessed: ANGLE AMD D3D11 -- the
+user's exact stack). The 9222 headless chrome that scripts/verify.mjs targets runs a DIFFERENT
+backend, so a look defect can pass every verify.mjs witness and still be broken on the user's
+screen; any look/material/normal judgment MUST be confirmed on the spool browser verb (or the
+user's warm tab via /cmd). Never write a note calling the spool browser tool headless.
+
+LIVE WITNESS VIA SERVER: the cold shader compile (~110s on source change, ~150s on d3d11/FXC)
+makes fresh sessions slow, so witness the warm tab through the server when possible. `server.js`
+hosts `POST /diag` (per-frame
+render state, ringed) read via `GET /diag/tail`, and a `POST /cmd {js}` command channel the page polls
+and runs live (result to `/diag`, kind:`cmd-result`). Drive `window.__toggleAtlas`, `window.__diag`
+probes, and `window.__diag.reloadShaders()` hot-reload through `/cmd` — no page reload. Recall
+"tv8-diag-sink-rehosted-2026-06-07".
+
+Data flow, each stage names its one file:
+1. QUADTREE picks which cube-sphere patches to draw per camera altitude — `src/quadtree.js`
+   (cube-sphere quadtree in JS, ported from the deleted Proland C++), driven per frame by
+   `src/planet-orchestrator.js`.
+2. MESH per patch is a GRID+2 grid (`src/gl-render.js`) whose outer ring is a SKIRT (terrain.glsl
+   drops `vertex.z>0.5` verts radially below the surface) hiding LOD T-junction cracks. The outer
+   ring is LOAD-BEARING — do not "just not draw it".
+3. HEIGHT assembled per-vertex in the VS (`src/shaders/terrain.glsl`): `h = cbias + bShape +
+   vDisp(land) + lake/river/canyon carves`. `bShape = broadShapeM(worldDir,reliefMul,ridgeMul)` =
+   THE shape (one continuous 14-oct world-dir fBm, LOD-invariant by construction). `cbias` = anchor
+   continental swell (`src/anchor-field.js`); `vDisp` = LOD-invariant micro-relief; carves via
+   `inciseRidgeField`. Collision = a GPU `_PROBE_` variant of the SAME shader (1px readback,
+   `gl-render.sampleGroundM`), no CPU mirror. — full design: recall "TV8 GPU-TERRAIN ARCHITECTURE
+   DECISION" in rs-learn.
+4. DEFORM: direct per-vertex sphere projection — `vWorld = dir0 * (R + h)` (replaced the Proland
+   corner-blend deform; round at any tessellation, no flat patches at high GRID).
+5. FS shades from height+slope+climate (`terrainAlbedoClimate`) + per-vertex seamless normal +
+   ocean/lake/river. No FS detail TEXTURE (a tiled image would moire + UV-scroll); closeup MACRO
+   relief comes from the mesh subdividing into a denser sample of the one VS fractal. The FS DOES
+   carry a procedural cliff DETAIL-NORMAL (biplanar + 2-scale RNM rock bump, world-anchored so it
+   never reseeds on camera move) on steep faces only, plus object-space slope/gorge AO and inline
+   analytic single-scatter AERIAL PERSPECTIVE (distance-gated space->ground depth cue). Unified
+   FS shading model: recall "tv8-fs-shading-bundle-shipped-2026-06-05" + "tv8-shading-unification-decision-2026-06-05".
+   CLOSE-UP ROCK ENGAGEMENT (2026-06-05b, workflow w5gywvug1): all rock/cliff/strata/detail-normal
+   gates now key off `rockSlope` = clamp(1-dot(ngGeo,uz), slope, 1) where ngGeo = the RAW geometric
+   normal cross(dFdx,dFdy) hoisted BEFORE the lit-normal compression (the macro `slope` caps ~0.6 on
+   vertical faces -> rock gates never fired at the deck = lit clay). The biplanar bump is promoted to a
+   material+AO signal (microSlope/microCurv from existing taps), all pxWorld/nearFade-faded so orbit is
+   identical. ZERO VS octaves added (VS is 96%-bound; the VS derivative-fBm was rejected). recall
+   "tv8-closeup-rock-engagement-2026-06-05". The deck VISUAL is the user's-eye gate (driven browser
+   can't render the deck: low-alt tile-fetch returns black).
+
+DETAIL-ON-APPROACH: relief must grow (or hold), never drop, as you descend — guaranteed by
+construction (finer LOD = denser sample of the one field). The lit-luma metric is near-blind to
+relief at nadir; judge closeup BY EYE (screenshot) at an oblique pose.
+
+RUNTIME FPS is VERTEX-SHADER-bound (96% VS+raster at the deck, FS is a dead lever): measure with the
+headed-browser `window.__diag.gpuTimer` (EXT_disjoint_timer_query_webgl2 + a `uFsCheap` FS short-circuit).
+Levers shipped: `broadShapeFD` reduced-octave FD, GRID 24->16, and the low-alt `altSplitMul` PEAK 2.0->1.4
+(removes a sub-pixel over-tessellation tail; 1.68x at 6km). BEFORE trusting gpuTimer, read `__pageErr` and
+confirm `dbg.quads()>0` — a frozen `__altM`+0-quads+overlay-up is a CRASHED render loop, not a slow one.
+Full numbers, the live `__splitFactor` sweep method, the crash class, and gotchas in recall
+"tv8-fps-splitfactor-peak-cut-2026-06-04b". Workflow `.claude/workflows/fps-perf.js`.
+
+## Headless shader verification (USE scripts/verify.mjs)
+
+The render/lint/watch CLI toolchain and src/lab (terrain-lab mirrors, glslang lint) were DELETED
+2026-06-12 (user: "get rid of the lab and glslang"). The single headless verification surface is
+`node scripts/verify.mjs [probeName|expr]` (raw CDP against the live planet.html -- see the
+PERMANENT VERIFY POLICY at the top): shader compile errors surface as orch 'error'/ready-timeout
+on the real two-stage compile, and the in-page `__diag` probes assert behavior. The lab's LOD
+knot solver pattern (node bisection over the real quadtree) lives in recall
+"tv8-separate-water-surface-2026-06-11" if a re-solve is ever needed -- rebuild it inline, do not
+resurrect the lab mirror (byte-sync drift was a recurring failure class). NO node-WebGL2 binding
+exists on win32 (headless-gl/@kmamal are WebGL1).
+
+## The efficient terrain-debug loop (USE THIS, never restart-and-eyeball)
+
+Debug LIVE in the browser through `window.__diag` / `window.__dbg`, NOT by restarting the server
+and guessing from screenshots. One `page.evaluate` dispatch reads the actual runtime state.
+
+1. Serve: `PORT=8081 node server.js`. Drive the page with the spool `browser` verb (Playwriter
+   script in `.gm/exec-spool/in/browser/N.txt`; raw JS, `page` global). Reuse ONE persistent
+   session — do NOT re-navigate per probe (~10 navs crashes chrome).
+2. Gate: a shader compile fail leaves `window.__diag` undefined / `window.__pageErr` set and the
+   page LOOKS like a slow load. Check `hasDiag` + `pageErr` in one dispatch before measuring.
+3. Park: `await __diag.parkOblique(altKm, aimFrac)` / `parkAt(rung)` — deterministic, reproducible
+   viewpoints (eyeballed positions made comparisons noisy).
+4. Measure: numeric probes return a metric + pass/coverage: `_read()` (pixel buffer), relief/
+   albedo SD, `limbScan`, `seamProbe`, `speckleProbe`, the `__lastGLQuads` leaf set + quad counts,
+   `glError`. Keep probes light — many frames + several parkOblique in one dispatch can exceed the
+   ~14s browser timeout; split into multiple dispatches.
+   **LIVE-TAB CAMERA CONTENTION (load-bearing):** the witness browser is CDP-attached to the USER's
+   live tab whose rAF loop overwrites `__planet.cam.pos`, so scripted poses are reverted — `__lastGLQuads`/
+   center-pixel/`page.screenshot()` read the user's contested camera, NOT yours. Pose-independent (reliable):
+   `reloadShaders`, `pageErr`-null-after-load (compile witness), `seamProbe`, `sampleGroundM`/`hpf.sampleDir`
+   scans, split-math trace. **LOD/SHAPE validation = the HEADLESS LAB** (`cd src/lab && node terrain-lab.mjs`;
+   mirror is STALE-prone, sync on shader massif/peak/ceiling edits). If the `browser` verb returns "could
+   not allocate free port" mid-session (resource accumulation), the fix is a FULL plugkit node-tree
+   kill+reboot (kill every `*plugkit*`/`*supervisor*`/`*relay*` node proc — spare server.js + the user's
+   Chrome/other projects — then `bun x gm-plugkit@latest spool &`); killing only the relay/duplicates does
+   NOT recover it. — recall "TV8 witness contention lod traces correct" + "TV8 wasm renamed to src and
+   spooler restart recovery 2026-06-02".
+5. Tune live, NO rebuild: `window.__gen` shader globals; `window.__displayMode` debug views —
+   recall "TV8 live-debug display modes" in rs-learn for the full mode list.
+6. Re-measure. Repeat. The whole loop is browser-side; the server stays up.
+
+GEN-CONTROLS OVERRIDE + JS CACHE TRAP (cost many turns of invisible edits): the LIVE biome material
+values (bcRock, slopeRock, bandEdgesHi/Lo, snowEdges...) come from `window.__gen.state.biome` in
+`src/terrain-gen-controls.js` (~L35-41), which OVERRIDES the gl-render.js defaults — edit the
+gen-controls state, not the gl-render default. AND the browser HTTP-caches JS modules, so reloads
+serve stale code; force fresh via a CDP `Network.setCacheDisabled` before `page.goto`, and VERIFY any
+change took with `gl.getUniform(orch.render.prog, name)` — never trust an edit is live. Recall "TV8
+gen-controls overrides gl-render defaults CRITICAL 2026-06-03".
+
+CLIENT-EDIT WITNESS: any edit to `terrain.glsl` / `*.js` / `planet.html` must be witnessed in the
+SAME turn via a `browser` dispatch asserting the invariant (compile clean + glError 0 + the metric
+the edit targets). Port-exhausted browser → contention-free headless fallbacks (lab for LOD/shape;
+NODE MODULE PROFILE for JS hot loops, how bakeHpf 4027ms→1137ms was found) — recall "TV8 node module
+profile bakehpf bottleneck 2026-06-02" + "TV8 patches view loadtime distribution 2026-06-02c".
+
+## RECURRING CLASS: "rocks everywhere + normals gone + height-keyed shading" -- THE SOLUTION (user order 2026-06-12)
+
+PRIMARY ROOT = ANGLE D3D11/FXC MIS-TRANSLATION OF THE UNROLLED FRACTAL (default Chrome on Windows
+= d3d11 backend = FXC). Proven by backend split on the SAME AMD GPU: vulkan renders correctly,
+d3d11 renders the triad (blotchy rocks on flat ground + relief normals gone + shading reads as
+height); the GPU/driver is innocent. FXC fully unrolls constant-bound loops and reorders math
+across the unrolled 12-octave broadShapeM body. THE FIX (THE SOLUTION, do not regress it):
+broadShapeM's octave loop is RUNTIME-BOUNDED -- `uniform int uOctMax` (set 12 by
+gl-render setComposeHeightUniforms; shader guards <=0 -> 12) so FXC CANNOT unroll. Side proof the
+de-unroll engages: d3d11 cold shaderCompileMs 152379 -> 63259. If this triad ever returns on
+default Chrome/AMD: check the loop is still runtime-bounded FIRST. Never reintroduce a constant
+12 bound; if a new VS fractal loop is added, give it the same runtime bound.
+
+SECONDARY (real but transient/exotic) modes with the same look, check in this order via /diag tail:
+(a) `swgl`/`ctxLostAt` non-null = software-WebGL after a GPU-process crash -> restart the BROWSER;
+(b) `bakePending` non-zero = unbaked/zero-HPF window (keep whole-planet bake <1s, ee7d72e).
+Rock gates themselves are SLOPE-ONLY by design (terrain.glsl macro ~1093-1100, splat ~1574;
+height-band rock REMOVED 2026-06-03) -- rock on flat ground means broken INPUTS, never the gates.
+
+## FXC (ANGLE d3d11 / default Chrome on Windows) -- THE SOLUTION RECORD (user order, 2026-06-12)
+
+The recurring "rocks everywhere + normals gone + dark daylit ground, AMD/default-Chrome only" class
+is FXC SHADER MIS-TRANSLATION, never the GPU/driver (vulkan on the same AMD silicon renders
+correctly). Two proven mechanisms + their fixes (commits f062365 + d56a202):
+1. CONSTANT-BOUND LOOPS get fully unrolled + cross-iteration reordered -> `uniform int uOctMax`
+   runtime-bounds the broadShapeM octave loop (side effect: cold compile 152s -> 63s).
+2. PER-CALLSITE INLINING: composeHeight inlined at separate call sites gets optimized DIFFERENTLY
+   per copy -- the lit-normal FD taps then disagree by tens of metres on FLAT ground (fake slope ->
+   rock material + slope-AO dark + dead normals, in patches). Fix: ALL FD taps evaluate through ONE
+   runtime-bounded loop (fdIters keyed on uNrmStepM) = a single instance, errors cancel exactly.
+RULES: never reintroduce a constant bound on a VS fractal loop; never difference composeHeight (or
+any big field fn) across separate call sites -- route every tap through the single-instance loop.
+DIAGNOSIS ORDER for the symptom triad: (1) loop-bound/call-site regression, (2) HUD/diag `SWGL!`/
+`CTXLOST!` (software fallback after a GPU crash -- restart the BROWSER), (3) `bake:` pending
+(zero-HPF window). COMPILE COST CORRECTED (2026-06-12, user caught it): the earlier ">40min cold
+compile" reading was machine-HIBERNATION wall-clock contamination; a clean-profile awake measure
+(shader disk cache disabled, real AMD d3d11) shows shaderCompileMs 31455 -- the single-instance-loop
+shape compiles ~31s cold, 5x FASTER than the original 152s unrolled shape, cached ~250ms after.
+No cheapening needed. Timing rule: never trust wall-clock perf numbers across a sleep/hibernate;
+re-measure awake with the in-page shaderCompileMs.
+Memory keys: tv8-fxc-percallsite-divergence-TRUE-ROOT-2026-06-12, tv8-fxc-unroll-amd-root-SOLUTION-2026-06-12.
+
+## DEBUGGING PLAYBOOK (2026-06-12, distilled from the day the FXC hunt cost)
+
+- BACKEND SPLIT FIRST for any "looks wrong on X's machine" report: `node scripts/backend-ab.mjs`
+  launches d3d11 + vulkan side-by-side at the same pose and prints a divergence verdict.
+- USER-FLOWN EVIDENCE: open a CDP-driven window (`.gm/drive.mjs` pattern), let the USER fly it to
+  the defect, then dissect THAT frame -- their eyes pick the evidence, probes name the term.
+- ONE-CALL CARRIER FINDER: `__diag.bisect()` A/Bs splat/texNormals/warp/litNormal/slopeRock at the
+  current pose and returns per-toggle pixel-diff fractions; `__diag.groundTruth()` gives probe
+  h+slope under the camera. WIREFRAME checkbox = the geometry-truth tiebreaker (flat mesh under a
+  "rocky" render = the shading path is the liar).
+- CLOSE EVERY OTHER PLANET WINDOW before judging look/fps on the iGPU: leaked pages render at full
+  rAF, crush the GPU, steal /cmd commands, and pollute every measurement (witnessed repeatedly).
+- HUD tail now shows `vendor/backend`, `SWGL!`, `CTXLOST!`, `bake:N`, and `DBGVIEW <state>` when a
+  debug displayMode is requested but its program is still compiling or failed -- a debug view can
+  no longer silently fall back to the lit render.
+- BACKGROUNDED TABS throttle rAF to ~1/min: the compile poll now falls back to setTimeout when
+  `document.hidden`, but remember the mechanism -- a hidden tab that seems "stuck at init" may just
+  be starved, foreground it.
+
+## Hard-won invariants
+
+ONE FRACTAL PER CARVE (user hard rule): every carve = ONE world-dir field fn called in BOTH the VS
+geometry carve AND any FS mask at `normalize(worldPos)`; never a divergent FS inline loop — recall
+"TV8 one fractal per carve invariant 2026-06-02".
+
+FP32 PRECISION + GRAZING-AA + per-pixel-moire + SHARED-PREAMBLE (snoise3/carves/broadShapeM must be
+outside `#ifdef _VERTEX_` so the FS + `_PROBE_` program link) — recall "TV8 glsl fp32 grazing moire
+invariants 2026-06-02".
+
+LOD must INCREASE detail monotonically on descent + the LOD CENTER tracks the camera (worldToFaceLocal
+applies the atan inverse of faceWarp; witness with `window.__diag.lodCenterProbe()` -> tracksCamera
+<0.5deg). Far-LOD falloff coarsens only beyond the horizon; cull ON by default (screen-AABB). Debug
+displayModes 0-12 (6 elevation, 10 canyon, 11 cliffs, 12 patches/LOD) — recall "TV8 lod monotone
+descent cull debugviews 2026-06-02".
+
+CLIFFS/CANYONS/STRATA/CLIFF-LIGHTING (terrain.glsl mesa cliffTerraceM coherent-rim redesign + FS
+strata + RNB normal + slope-AO; levers `__canyonDepth __cliffAmt __strataM __cliffStrata __aoAmt
+__macroNrm __biomeBandBias`; realism WIP, user visual is the gate) — recall "TV8 cliffs canyons
+strata levers 2026-06-02".
+
+LIGHTING / "FLAT GREEN" ROOT (recurring complaint): the "terrain reads flat green / normals not
+affecting lit" was NOT the normal pipeline (A/B fsNormal proven, normalDiff 36-38 on gentle AND steep
+land). It was the DEFAULT SUN sitting high (near-overhead) -> minimal slope self-shading on gentle
+rolling terrain (correct for noon, but reads flat). FIX (planet.html cam.sunLatBase 0.6->0.35, commit
+333f3ba): a lower default sun = longer shadows -> even gentle hills self-shade -> default view reads
+3D. When judging relief, use an OBLIQUE sun + frame ACTUAL LAND (a sea-level dir at 45deg oblique from
++5km frames mostly ocean — verify the screenshot is land, not water). fsNormal default stays 0 (gated
+to steep faces, no-op on gentle land; gentle relief is carried by pvNormal, default on).
+
+VERTICAL ROCKFACE MATERIAL (user hard rule; distinct dark cool-grey cliffRock gated on verticality,
+slope gates calibrated to the 0.3-0.6 SMOOTHED-normal band not ~1.0, witness by image, warm-cast caveat) —
+recall "tv8-vertical-rockface-material-calibration".
+
+ROCK DETAIL-NORMAL = JUMP-FREE (biplanar pow-softmax weight, never a dominant-plane pick or fwidth fade
+= both JUMP on move; keep FS snoise3 taps down; cold-compile fix is CACHE PERSISTENCE not source-trim,
+181s one-time/machine) — recall "tv8-rock-detail-normal-triplanar-jumpfree" + "tv8-closeup-rock-engagement-2026-06-05".
+Workflow `/startup-perf`.
+
+## HPF adaptive quadtree (anchor-field.js)
+
+Per-band adaptive quadtrees (additive detail-hat overlay) + the BAKED-vs-FULL-BAND elevAmp gotcha —
+recall "TV8 hpf adaptive quadtree anchor field 2026-06-02".
+
+@.gm/next-step.md

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+## 2026-06-08
+
+- **Single comprehensive mobile-first terrain version** (`ab68667`) — rearchitected to run performantly on phones with drastically fewer GPU resources, one version only (no device tiers, no desktop/procedural/clipmap fallbacks). Driven by two subagent workflows (an 8-dimension analysis fan-out, then a 13-item per-file fixing-run fan-out), each step lint-witnessed.
+  - `gl-render.js`: height pool **R32F→R16F**, **2048→1024 layers** (tuned from a live eviction measurement: 512 evicted ~3155/s at the deck → 1024 gives 0/s), **8→4 mip levels**, with a format-only capability probe (`_useR16F`) that falls back to R32F when half-float is unavailable. **~90% VRAM cut** (138MB → ~35MB). Set the previously-missing `uHeightPoolTexSize` + `uFloatLinearOK` uniforms (were `vec2(0)` → NaN displacement). Added a `__tcEvictRate` counter + `window.__terrainConfig` diagnostics readout.
+  - `terrain.glsl` + `atmosphere.glsl`: global **`mediump float`** with explicit **highp islands** on all planet-scale quantities (validated safe — `assertElevLinear` pass, ~238k tris rasterized). Octave cuts (`broadShapeM` 14→12, `vtxDisplace` 9→6, single-octave rock), `aw*aw*aw*aw` for `pow(aw,4)`, distance-gated cheap FS far path, tanh ceiling `x/8000` (pointed peaks, no flat clipped tops). Overflow leaves shade with the geometric macro normal (no pale/colored flash) + macro-slope rock gate.
+  - `planet-orchestrator.js`: tightened LOD (splitFactor + near-radius) so peak visible leaves drop under the smaller cap; HPF continental field packed to RG16F+RG8.
+  - `quadtree.js`, `terrain-lab.mjs`: matched LOD + lab-mirror updates. Dead atlas apparatus deleted across files. 6-stage GLSL lint + `node --check` clean; CLI `shapeReport allGatesPass`; live glError 0 (R16F active, `bakeErr null`).
+
+## 2026-06-07
+
+- `terrain.glsl` + `gl-render.js` (`7ee7cb0`): unified lit-normal slope gain (`uNrmGain`) so the normal is the true gradient of the rendered height; camera moveStep + collision both use the GPU-exact `sampleGroundM` height — fixes the camera hitting zero speed before the surface.
+- `planet-orchestrator.js` + `terrain-lab.mjs` (`69c2a86`): LOD `distFactor` `sf*3.6 -> sf*8.0` — the detail seen at 5.5km now displays at ~12km (each LOD pop ~2.2x farther in altitude).
+- `terrain.glsl` (`06a9bd9`): rockface/canyon detail texture ~10x larger (FS noise freq `1800->180`, `1200->120`).
+- `terrain.glsl` (`db4dae0`): four normal-slope defects — full fine band restored, cbias continental-swell gradient added to the normal, peak-lift smoothstep chain rule, normalized pole tangent frame.
+- `terrain.glsl` + `lint-shader.mjs` (`7cb6eac`): guard the VS-only fractal + debug-only functions out of the render FS to shrink the ANGLE cold compile; lint now covers the PROBE and DEBUG-FS programs.
+- `terrain.glsl` + `planet-orchestrator.js` + `atlas-bake.mjs` (`b73465e`, `89f381e`): the baked atlas shades with relief — `broadShapeMD` central-differences `atlasHeight` so atlas-on land is no longer flat-shaded; `interiorExact` bake-validation gate added. Atlas default-off, live A/B via `window.__toggleAtlas`/`__forceAtlas`.
+- `server.js` + `planet.html` (`61135c6`, `4b116ad`): re-host the `/diag` sink and add a `/cmd` command channel — a headless agent reads the warm tab's live render state and drives it (toggle atlas, hot-reload shaders, probe GPU state) with no page reload, routing around the cold-compile browser-tool block.
+- `atlas.js` (`a2b2ce0`): `PLANET_R` default `6371000 -> 6360000` to match the system radius; closes the coordinate-system audit sweep (face-UV convention, vH<->normal term parity, tangent-frame guards, fp32 coord-scale, quadtree R, camera-height AGL — all pass).
+- `terrain.glsl` (`e3e4572`): bounded quantization — break the `vtxDisplace` octave loop below the Nyquist fade floor; ~2-4 fewer noise taps/vertex at deep LOD, geometry pixel-identical.
+- `quadtree.js` (`6bbf6e1`): flatten the near-far detail gradient as altitude rises above fps height (gradient 8 at the deck -> 2 at 300km).
+- `planet-orchestrator.js` + `terrain.glsl` + `gl-render.js` (`7b7dcd6`): matched HPF bake+shader seam-inset (`window.__hpfInset`) collapses the 985m cube-face seam to 0m; gated off by default.
+
+## 2026-05-23
+
+- `terrain-phase2.js` (commit `d87c51b`): Add `allocateTileSlot`, `computePipelines`, `computeBindGroups` to `ProlandProducer` — stopped TypeError crash every render frame when `terrain-phase3-integration.js` called these missing methods.
+- `shader-loader.js` (commit `1e61b7b` session): Fix `#if` numeric literal handling — `#if 1` was treated as a flag lookup (always false), stripping always-true blocks and causing GPU validation errors and black canvas.
+- `terrain-phase1.js`: Change `normTexArray` format from `rg32float` to `rgba8unorm` to match `normal_producer.wgsl` storageTexture output.
+- `terrain-phase2.js`: Remove unused bind group entries for upsample (b5), normal producer (b0), ortho producer (b0,b1,b2,b6) — WebGPU `layout:'auto'` strips unreachable bindings, causing validation errors when they were supplied.
+- `.gitignore`: Add `--session-id` stale runtime artifact.

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/README.md

@@ -0,0 +1,82 @@
+# mapspinner — WebGL2 Earth-scale Terrain SDK
+
+A performant, production-ready WebGL2 rendering SDK for interactive Earth-scale globe applications. Designed as a composable rendering layer that integrates seamlessly into projects like spoint.
+
+## Quick Start
+
+```bash
+npm install mapspinner
+```
+
+```javascript
+import { createPlanet } from 'mapspinner';
+
+// In your WebGL2 application
+const planet = await createPlanet(gl, {
+  radius: 6360000,      // Earth radius in meters
+  gridMeshSize: 16      // Mesh subdivision level
+});
+
+// Per-frame render
+planet.frame();
+```
+
+## Integration Example
+
+For integration into external projects (e.g., spoint), see `examples/basic-sdk-usage.js` for a complete setup including peer dependencies, camera control, and WebGL context initialization.
+
+## Development
+
+```bash
+PORT=8080 npm run dev
+# open http://localhost:8080/ in any WebGL2 browser
+```
+
+## Controls
+
+- **WASD** / mouse drag — yaw + pitch
+- **Q / E** / mouse wheel — zoom in / out
+- **R** — reset camera
+
+The camera flies continuously from orbit to first-person on the surface; the terrain LOD
+refines as you descend.
+
+## Architecture
+
+The terrain is a single continuous world-direction fractal evaluated per-vertex on the GPU — a lean, portable design with no procedural tile generation or offline preprocessing.
+
+- **`src/shaders/terrain.glsl`** — the core fractal. Height per vertex =
+  `cbias` (continental elevation bias) + `broadShapeM` (silhouette + relief) + `vtxDisplace` (micro-relief) + carves. The fragment stage shades via biome ramp + seamless normal + ocean/lake/river.
+- **`src/quadtree.js`** — cube-sphere quadtree LOD in JS. Selects visible patches based on camera altitude.
+- **`src/planet-orchestrator.js`** — per-frame quadtree drive, mesh generation, and render dispatch.
+- **`src/anchor-field.js`** — world-direction climate/elevation modulation (biome, temperature).
+- **`src/gl-render.js`** — WebGL2 program compile, mesh generation, per-quad draw.
+- **`src/index.js`** — SDK entry point for external consumers.
+
+## Layout
+
+```
+planet.html                  dev demo entry + __diag witness harness
+server.js                    dev static server (COOP/COEP, no-cache)
+src/shaders/terrain.glsl     terrain fractal (VS + FS)
+src/shaders/atmosphere.glsl  analytic sky/limb shading
+src/quadtree.js              cube-sphere quadtree LOD
+src/planet-orchestrator.js   per-frame drive + render dispatch
+src/anchor-field.js          elevation anchor field
+src/gl-render.js             WebGL2 render layer
+src/index.js                 SDK entry point
+examples/                    integration examples
+tests/                       SDK validation tests
+```
+
+## Testing
+
+```bash
+npm test
+```
+
+Tests validate SDK geometry output, shader compilation, and rendering invariants.
+
+## License
+
+MIT

package/examples/basic-sdk-usage.html

@@ -0,0 +1,114 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <title>mapspinner SDK Integration Example</title>
+  <style>
+    body { margin: 0; overflow: hidden; font-family: sans-serif; }
+    canvas { display: block; }
+    #hud {
+      position: absolute;
+      top: 10px;
+      left: 10px;
+      background: rgba(0,0,0,0.7);
+      color: #0f0;
+      padding: 10px;
+      font-family: monospace;
+      font-size: 12px;
+      z-index: 10;
+      white-space: pre;
+    }
+  </style>
+</head>
+<body>
+  <canvas id="canvas"></canvas>
+  <div id="hud">
+    mapspinner SDK example
+    Controls: WASD fly, QE zoom, R reset, mouse drag rotate
+  </div>
+
+  <script type="module">
+    // mapspinner SDK integration example for external consumers (e.g., spoint)
+    
+    import { createPlanet } from '../src/index.js';
+
+    const canvas = document.getElementById('canvas');
+    const hud = document.getElementById('hud');
+    
+    canvas.width = window.innerWidth;
+    canvas.height = window.innerHeight;
+
+    const gl = canvas.getContext('webgl2', { antialias: false, preserveDrawingBuffer: false });
+    if (!gl) {
+      alert('WebGL2 not supported');
+      throw new Error('No WebGL2 context');
+    }
+
+    // Enable required extensions
+    gl.getExtension('OES_texture_float');
+    gl.getExtension('OES_texture_float_linear');
+    gl.getExtension('EXT_color_buffer_float');
+    gl.getExtension('KHR_parallel_shader_compile');
+
+    let planet = null;
+    let frameCount = 0;
+    let lastTime = Date.now();
+
+    // Initialize mapspinner SDK
+    async function init() {
+      try {
+        planet = await createPlanet(gl, {
+          radius: 6360000,      // Earth radius (meters)
+          gridMeshSize: 16      // Mesh subdivision
+        });
+        console.log('mapspinner SDK initialized');
+        render();
+      } catch (e) {
+        hud.textContent = `Initialization error: ${e.message}`;
+        console.error(e);
+      }
+    }
+
+    function render() {
+      requestAnimationFrame(render);
+
+      if (!planet) return;
+
+      // Update camera and render one frame
+      try {
+        const frameResult = planet.frame();
+        frameCount++;
+        
+        // Update HUD
+        const now = Date.now();
+        const elapsed = now - lastTime;
+        if (elapsed > 500) {
+          const fps = (frameCount / elapsed * 1000).toFixed(1);
+          hud.textContent = 
+            `mapspinner SDK example\n` +
+            `FPS: ${fps}\n` +
+            `Quads: ${frameResult.quadCount || 0}\n` +
+            `Controls: WASD fly, QE zoom, R reset`;
+          frameCount = 0;
+          lastTime = now;
+        }
+      } catch (e) {
+        hud.textContent = `Render error: ${e.message}`;
+        console.error(e);
+      }
+    }
+
+    // Handle window resize
+    window.addEventListener('resize', () => {
+      canvas.width = window.innerWidth;
+      canvas.height = window.innerHeight;
+      if (planet && planet.render && planet.render.cullMatrix) {
+        // Notify render layer of viewport change if needed
+      }
+    });
+
+    // Start initialization
+    init();
+  </script>
+</body>
+</html>

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "mapspinner",
+  "version": "0.1.1",
+  "description": "WebGL2 Earth-scale terrain rendering SDK for interactive globe applications",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "type": "module",
+  "scripts": {
+    "test": "node tests/run.js",
+    "dev": "PORT=8080 node server.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AnEntrypoint/mapspinner.git"
+  },
+  "keywords": [
+    "WebGL2",
+    "terrain",
+    "rendering",
+    "SDK",
+    "globe",
+    "3D"
+  ],
+  "author": "",
+  "license": "MIT"
+}