Sandpile - Self-Organized Criticality

The task details say: "Wake up and do as you please." So this is an open-ended task. Based on my purpose, I should create cool Three.js demos in my space under /space/demos/. The last execution created demo 037-epicycle. So I should create a new demo, e.g., 038-something.

Let me first look at the existing demos to understand the structure and conventions, then create a new advanced demo.

Let me install shell tools and explore the demos folder.

Let me explore the demos folder to see what exists.

I see the demos structure. The previous demo was 037-epicycle. So the new demo should be 038-something. Let me look at a recent demo to understand conventions (e.g., 037-epicycle or 036-wavefunction).

Let me check the structure of the epicycle demo to see the conventions used (import maps, quality tiers, UI, etc.).

Now let me look at the script section of the epicycle demo to see conventions for the import map, quality tiers, and other patterns.

I understand the conventions. Now let me see the tail of the file to understand the structure at the end (quality tiers, resize, etc.).

I understand the conventions well now. Let me check the list of existing demos to avoid duplicating a concept:

1. 001-spinning-cube
2. 002-nebula-galaxy
3. 003-mandelbulb-explorer
4. 004-fluid-dynamics
5. 005-gravity-sandbox
6. 006-event-horizon
7. 007-sonic-reactor
8. 008-void-runner
9. 009-azure-odyssey
10. 010-abyssal-bloom
11. 011-physarum-garden
12. 012-powder-alchemy
13. 013-clockwork-nebula
14. 014-neon-rain
15. 015-aurora-borealis
16. 016-skitter
17. 017-coral-resonance
18. 018-threshold
19. 019-attractorium
20. 020-murmuration
21. 021-terraforge
22. 022-cloudsea
23. 023-frostline
24. 024-koi-pond
25. 025-ferrofluid
26. 026-synchrony
27. 027-cymatics
28. 028-teslasphere
29. 029-pyrosymphony
30. 030-morphogenesis
31. 031-galton-cascade
32. 032-wavefront
33. 033-gossamer
34. 034-magnetosphere
35. 035-cloud-chamber
36. 036-wavefunction
37. 037-epicycle

Let me quickly glance at the demo names/descriptions in the index to avoid overlapping concepts. Let me grab the titles and short descriptions.

Now I need to pick a fresh concept for demo 038. Existing concepts span: fluid, gravity, black hole, audio, runner game, flight, jellyfish/bloom, physarum, powder sim, clockwork, rain, aurora, insects (skitter), coral, threshold (?), attractors, murmuration (flocking), terrain forge, clouds, frost, koi pond, ferrofluid, synchrony (Kuramoto), cymatics, tesla sphere, fire, morphogenesis (reaction-diffusion), galton board, wavefront, gossamer (spider web?), magnetosphere, cloud chamber, wavefunction (quantum), epicycle (Fourier).

Brainstorming fresh ideas:

1. Sandpile / Abelian sandpile (Bak–Tang–Wiesenfeld) — toppling avalanches, fractal identity patterns, beautiful colors. Could be done in 3D with instanced boxes, avalanche dynamics, and sound. This is a cellular automaton producing gorgeous fractal patterns (the identity element of the sandpile group is stunning). GPU or CPU compute on a grid, rendered as stacked cubes or a heightmap with custom shader. "Abelian" — a sandpile cathedral.

2. Reaction–diffusion already done (030-morphogenesis). Skip.

3. N-body choreographies — maybe overlaps with gravity sandbox.

4. Knot theory / torus knots with tubes, Frenet frames — nice but maybe less "wow".

5. Chladni — overlaps with cymatics.

6. L-systems / procedural trees — could be gorgeous: 3D L-system forest, wind, seasons.

7. Voronoi / Delaunay — fracture sim? "Shatter" physics.

8. Game of Life in 3D — cellular automata... maybe overlaps.

9. Percolation / forest fire model — nice stat-mech visualization.

10. Ray-traced/ray-marched fractal — mandelbulb already exists.

11. Origami / paper folding — complex.

12. Spirograph/harmonograph — epicycle just did Fourier drawing; harmonograph overlaps slightly.

13. Double pendulum / chaos gallery — attractors exist.

14. Turing patterns — done.

15. Mandelbrot set deep zoom in 3D — mandelbulb exists but 2D zoom different... skip.

16. Abelian sandpile — I really like this. The identity element of the sandpile group on a large grid produces breathtaking fractal patterns (self-similar patches). Rendering: a heightfield where each cell's grain count (0-3) maps to color; toppling avalanches propagate as glowing waves. Interactions: click to drop sand, drag to draw sand lines, choose between "random pile", "identity element (recursive fractal)", "infinite pile", avalanches stats, power-law histogram of avalanche sizes (self-organized criticality!). 3D view: instanced cubes stacked? Better: a shader-based heightmap plane with vertex displacement, colored by grain count, with avalanche glow. Add sound: clicks/pings on topple waves. Add power-law plot: avalanche size distribution histogram on log-log scale showing 1/f. This is a fantastic demo of self-organized criticality. Name: "Sandpile Cathedral" or "Critical State" or "Abelian".

17. Solar system / orrery with real planets — clockwork nebula was space-y. Skip.

18. Cloth/flag simulation — could be nice but simpler.

19. Boids — murmuration done.

20. Tensegrity / soft-body physics — interesting but tricky.

21. Hyperbolic tiling / Escher — Poincaré disk with animated geodesics. Beautiful and mathy. "Hyperbolic".

22. Maze generation + solver — less wow.

23. Light caustics / optics bench — refractive glass shapes, prisms splitting light into spectrum. "Prism" — a gorgeous optics bench with ray tracing through lenses/prisms, chromatic dispersion, spectral colors. That's visually stunning and interactive: drag lenses/prisms, emit white light beams that split into rainbows. 2D optics in 3D presentation with bloom. This is very appealing! "Optics" or "Chroma" or "Refraction".

24. Ant colony / pheromone sim — physarum covers similar.

25. Tidal locking / three-body — gravity sandbox covers.

26. Ising model (ferromagnetism) — stat-mech: temperature slider, domain formation, critical temperature ~2.269, magnetization curve, heat map, flips with Metropolis algorithm on GPU. Visually could be very nice with glowing domains, but maybe less dynamic.

27. Excitable media / spiral waves (Belousov-Zhabotinsky) — different from reaction-diffusion? It's related but distinct: FitzHugh-Nagumo spiral waves. Morphogenesis was probably Turing patterns (spots/stripes). Spiral waves are a different look (rotating spirals, heart tissue, BZ reaction). Could overlap though.

28. Origami crane / paper — skip.

29. Penrose tiling — quasiperiodic tiling animated, with inflation/deflation. Visually striking (kites and darts), hypnotic morphing. Could add 3D extrusion. "Penrose" — nice math-art. Interactive: inflate/deflate animation, color by tile type, music notes on tile events. Hmm, decent but maybe static-ish.

30. Sandpile remains my favorite for SOC + fractal identity patterns + avalanches + power law. Let me think about how to make it jaw-dropping:

Demo 038: "Sandpile" — self-organized criticality cathedral.

Core: Abelian sandpile model on a 256×256 or 512×512 grid. Each cell holds 0-3 grains (stable). Adding a grain to a cell with 4 grains topples: it gives 1 grain to each of 4 neighbors, which may cascade. Avalanches propagate.

Two spectacular modes:

1. Identity mode: compute the identity element of the sandpile group: I = (2c − (2c)°)° where c is the max-stable config (3 everywhere), x° means stabilize. On a 512×512 grid this produces a stunning fractal pattern. Computing this is heavy: needs ~N topplings... Actually the identity computation requires stabilizing 2*(max) twice; it's doable with an efficient queue-based toppling algorithm. For 512×512 = 262144 cells, the identity computation involves on the order of ~1e8-1e9 topplings in naive form — too slow in JS in real time. Hmm. But there's a faster way: burning algorithm? The burning algorithm tests recurrence but doesn't directly give identity. Computing the identity: e = 2c* − (2c*)° where c* = 2 (the config with 2 grains everywhere)? The known formula: the identity is (2c − (2c)°)°, where c is the maximal stable configuration (3 grains each). Actually known: e = (2c_max − (2c_max)°)° where c_max = 3 everywhere. (2c_max)° = stabilize(6 everywhere). Stabilizing 6/everywhere on 512² needs each cell to topple... The total number of grains is 6·262144 ≈ 1.57M; grains lost at boundary per stabilization... The identity computation at 512×512 typically takes billions of topplings — too slow for real-time JS. At 192×192 or 256×256 it might be feasible over ~seconds-minutes with a good typed-array implementation and chunking. Hmm.

Alternative gorgeous mode: drop grains in the center continuously — the pile grows into a circular-ish pattern with fractal avalanche trails; colors 0-3 produce beautiful patterns as the pile evolves (this is the classic BTW evolution and it is beautiful — concentric rings with intricate triangular/diamond patterns emerging). At ~millions of grains dropped, the classic "sandpile identity-like" patterns emerge. With typed arrays and a topple queue, JS can do maybe 5-20M topplings/sec. Center-drop to build a 256×256 pile to the interesting stage needs ~2-4M grains → topplings maybe tens of millions — can run at interactive rates with "speed" slider controlling grains-per-frame.

Actually, the prettiest known pattern is dropping a huge amount of sand at the center of an initially empty grid: you get the famous "sandpile fractal" (a square-ish mandala with triangular motifs, Sierpinski-like). Yes! N grains at center of empty grid, stabilize — produces the famous pattern (like the identity but centered). This is computed incrementally: each frame add K grains at center, process topplings with a queue. The pattern grows outward in a circle of fractal patches. That's the demo. Also clicking adds sand anywhere; drawing adds lines.

Avalanches: when a topple wave propagates, render it as a glowing wave. Track avalanche size (total topplings per drop) and duration → log-log histogram → power law → self-organized criticality. That's the science hook.

Rendering in 3D: represent pile as a plane with per-cell displacement = height (grains), color by height: 0 black, 1 cyan, 2 violet, 3 amber, 4+ glowing white (toppling). Use a 256×256 (or larger) instanced mesh of boxes? 512×512 = 262144 instances — InstancedMesh with box geometry can handle 262k instances OK-ish but heavy. Better: use a custom BufferGeometry grid plane 256×256 segments with vertex displacement + color in shader; or point sprites. A displaced heightfield with sharp per-cell colors requires either per-cell quads (flat shading) — use a plane geometry and compute cell color from data texture in fragment shader, displacing vertices per cell too. Simplest robust approach:

• DataTexture (256×256, R channel = height/4) updated from typed array.
• Ground plane geometry 256×256 segments, displaced in vertex shader by texture sample (with flat per-cell look via nearest filtering), fragment shader colors by height + glow for toppling cells + edge lighting.
• Plus avalanche "sparks": when cells topple, spawn glowing particles along the wave front for drama (capped).

Actually for crisp look, per-cell cubes: 256×256 = 65,536 instances. InstancedMesh of a small box with per-instance color and scale-y = height. 65k instances fine. 512×512 = 262k boxes also possible on decent GPU but heavy with bloom at high pixel ratio; adaptive quality handles it. Cubes give great 3D depth, shadows-ish, and "cathedral" look. I could do 256 with boxes... but updating 65k instance matrices per frame is CPU heavy (~65k × matrix compose) — but we only need to update cells that changed (toppled). Use per-instance attribute updates on a dirty-list basis. Box scale Y changes + color changes only on changed cells. Dirty list per frame typically thousands — fine.

Hmm, but actually a slicker approach used by many: render the pile as a heightfield plane with a texture, plus a separate "peak cubes"... Let me keep it simpler: InstancedMesh cubes, grid 256×256 centered at origin, each cube unit size ~1, pile spans 256 units; camera looks at it at an angle; OrbitControls. When grains topple, instance scale/color updated. Toppling cells flash bright (emissive-ish via brighter color + bloom).

Sound: WebAudio — avalanche sonification: map avalanche wave-front propagation to arpeggiated pings (pentatonic), bigger avalanches → deeper rumble. Add ambient drone.

UI:

• Sliders: DROP RATE (grains per frame at center), GRID SIZE? (requires rebuild; maybe presets instead), BRUSH SIZE, SIM SPEED (topples per frame batch).
• Modes: Center drop / Rain (random drops) / Draw (brush) / Identity (precompute?) — maybe skip identity; instead "seed patterns": Empty, Centered pile, Ring, Checker of 3s (max stable) then drop → different aesthetics.
• Buttons: presets: "Center Drop", "Rain", "Max Stable + drop", "Twin Peaks" (two drop points interfere), "Circle of sand".
• Stats: total grains, total topplings, avalanche count, last avalanche size, mean; log-log histogram canvas of avalanche size distribution with fitted slope τ≈1.0-1.5.
• Toggles: sound, auto-rotate, height exaggeration (2D flat vs 3D towers), avalanche glow.
• Keys, help overlay, PNG snapshot, adaptive quality tiers, bloom + vignette/grain grade — follow the house style.

Physics details: grid G×G Int32 (heights), toppling via queue (Int32Array stack). Rules: if h≥4: h-=4; each neighbor +1 (if inside; else grain lost at edge). Avalanche = sequence triggered by one added grain; count topplings and area (unique cells) and duration (wave "radius" steps via BFS layering... simpler: measure time from start to end of cascade in sim steps... with batched processing per frame it's fine to compute per-avalanche stats by fully processing each drop's cascade synchronously? For big avalanches (100k+ topplings) that would block a frame; but 100k topplings is ~a few ms — acceptable. Drop rate low (e.g., up to 50/frame) each processed fully → up to few hundred k topplings per frame worst case ~10-20ms — borderline. Use a cap: process up to B topples per frame, remaining cascade continues next frame (avalanche spans multiple frames — actually nicer visually: waves propagate visibly!). So implement a global topple queue processed in batches per frame; avalanche stat accumulates until queue empties. Visual wave propagation emerges naturally since we process B topples/frame and the wave front glows.

Wave-front glow: keep a "heat" Float32Array that gets set to 1 when a cell topples, decays ×0.92/frame; color = base + heat glow. Instance color update: per frame, for cells in dirty set (toppled this frame + decaying set?) — updating colors of all hot cells each frame could be many; instead: heat captured in instanceColor only at topple moment (set bright), then decay handled by re-tinting recently-changed cells over ~30 frames via a small list of "cooling" cells. Manageable: keep list of {index, heat} — each frame iterate cooling list (usually few thousand), lerp color toward base, remove when close. Instance attribute needsUpdate uploads whole buffer (65k×3 floats = 786KB — per frame upload is heavy but OK-ish? Actually needsUpdate re-uploads entire buffer). Alternative: use partial updates via updateRanges (three r170 supports addUpdateRange on BufferAttribute). Use attribute.addUpdateRange(start, count)? In r170, updateRanges array supported: attr.clearUpdateRanges(); attr.addUpdateRange(...). Hmm, per-cell scattered updates → many ranges; three supports multiple ranges? addUpdateRange pushes ranges; yes multiple ranges allowed. Cap ranges count. Simpler: just set needsUpdate=true on instanceColor when dirty count exceeds threshold... 786KB/frame upload at 60fps = 47MB/s — GPUs handle fine honestly. Similarly instanceMatrix full re-upload 65k×64B = 4MB — too heavy per frame. So: keep heights in instanceMatrix but avoid rewriting matrices every frame. Alternative: use per-instance custom attribute for height and color, and do scaling in vertex shader via instanced attribute (MeshBasicMaterial/ShaderMaterial with instance attributes). Then only two float attributes to update (h, heat) — 65k floats each = 262KB — fine to upload fully per frame; or use update ranges.

Plan: custom ShaderMaterial for instanced boxes:

• attributes: instanceHeight (float), instanceHeat (float) — instanced BufferAttributes.
• vertex: scale unit box Y by max(h, 0.02)*heightScale; translate to grid position (computed from gl_InstanceID? WebGL2 has gl_InstanceID — three r170 uses WebGL2, so yes). Grid coords from instanceID: x = id % G, z = floor(id / G).
• fragment: color = palette(h) + heat glow; simple lambert-ish lighting via normal; slight AO fake by height.

This avoids instanceMatrix entirely — efficient and slick. Picking/interaction: raycast onto invisible ground plane, convert to cell coords, add grains via brush.

Palette: 0: deep navy; 1: cyan; 2: violet; 3: amber; ≥4 (toppling): white-hot flash. Actually heights stay ≤3 except momentarily during topple; heat handles flash.

Stats/histogram: log-log avalanche-size histogram in a 2D canvas: bin sizes logarithmically, plot count vs size as points, draw reference slope τ≈1.2. Updates live.

Extra drama: "quake" events — big avalanches (size > threshold) trigger a camera shake + deep boom + log entry. Nice touch.

Presets:

1. Center Drop — empty grid, drop stream at center → classic fractal mandala grows.
2. Rain — random positions, uniform → SOC steady state, constant avalanches, power law.
3. Peak & Peak — two drop points; interference patterns.
4. Full House — start all cells at 3 (max stable), then rain → massive early cascades, then SOC.
5. Ring — drop on a circle ring. Maybe also "Draw" brush always available with brush size slider.

Height exaggeration slider: 0 (flat mosaic) → 1 (towers). Default ~0.5.

Speed: topples per frame batch: 2k–200k slider (log). Drop rate slider 0–200/frame.

Sound engine: ambient drone + per-frame: if avalanche active, ping notes proportional to wave front size; pentatonic scale mapped from log(topples this frame); quake boom for large avalanches; grain drop click. Follow house style (WebAudio, master gain, toggle A).

Post: UnrealBloom + custom grade (vignette/grain/chromatic) + OutputPass, like the others.

Backdrop: starfield + dust? Maybe a subtle gradient + floating dust motes + fog. Keep consistent with house style: stars, dust, grid floor under the pile? A dark reflective-ish base plane with polar grid? Simpler: faint grid base plane slightly below, plus stars.

Name ideas: "Sandpile" / "Critical Mass" / "Avalanche" / "SOC" / "Sandmandala" / "Abelian". I like 038-sandpile with title "Sandpile — self-organized criticality". Maybe "SANDPILE · the self-organized criticality cathedral". Folder: /space/demos/038-sandpile/.

Let me also double check how index.html cards are inserted (""). I'll insert a new card right after that comment, matching formatting style of 037 card (indented). I'll craft a rich description paragraph in the same verbose style.

Let me look at more of the epicycle code for audio engine and grade shader patterns to reuse conventions (not copy whole, but match style).

***************************************************************************************************************************************************************************ns.

I now have all the conventions. Time to create demo 038. My choice: Sandpile — self-organized criticality cathedral (Abelian/BTW sandpile model).

Let me check the exact index.html insertion point formatting once more, then write the demo.

The plan for /space/demos/038-sandpile/index.html:

Core model

• Grid G×G (default 256; presets allow 192/256/320?). Actually let me keep a fixed G=256 for simplicity and performance, maybe allow size switching via a small select (192/256/384). Instanced boxes: 384² = 147k instances — OK for shader-instanced boxes. Let me support grid size presets: 160, 256, 384. Changing rebuilds.
• heights: Int32Array(G*G), heat: Float32Array (per-instance attr), heights also as instanced float attr (updated when changed).
• Topple queue: Int32Array(G*G) ring buffer. inQueue? Not necessary — duplicates fine but could blow queue; standard approach: when a cell reaches ≥4 and not already flagged, push. Use a Uint8Array flag to avoid duplicates: flag set on push, cleared on pop.
• Process per frame: budget B (slider 2k..120k, log scale) topples per frame.
• Drop grains: each "drop" adds +1 at cell; if becomes ≥4 → push. Avalanche bookkeeping: an avalanche is "active" while queue non-empty. When queue transitions empty→nonempty, avalanche id++; when it drains, record size/duration/area into histogram stats.

Stats:

• avalanche size s = total topples; area = unique cells toppled (Uint8 mark per avalanche id — use Int32Array lastAvalId per cell); duration = frames (approx "time steps" — with batched processing, count process-batches; better: count queue-empties... use frames active).
• Log-log histogram: sizes from 1..1e6+, bins log-spaced (e.g., 40 bins between 1 and 4e6). Draw as scatter on 2D canvas with log axes + reference line slope -1.2. Nice.
• Totals: grains added, topples, avalanches, grains lost at boundary.

Visuals

• Instanced boxes with custom ShaderMaterial:
  • instanced attributes: aH (height 0..3+), aHeat (0..1).
  • grid coords from gl_InstanceID: int ix = gl_InstanceID % G; int iz = gl_InstanceID / G; — need uniform uG. WebGL2 guaranteed (three r170 requires WebGL2).
  • vertex: pos = position (unit box centered at origin, size ~0.86 for gaps); y-scale by (0.12 + h*uHeight) — h can exceed 3 briefly? h after stabilize ≤3 but during frame we may snapshot h mid-avalanche with h up to ~7 — clamp display h to 3.x. Actually since we sync attributes after each frame's batch, heights can transiently be ≥4; clamp visually.
  • lighting: simple: normal-based lambert with two directional lights + hemisphere ambient; plus fresnel rim. Color palette by h: h0: #0d1420 dark navy; h1: cyan #37b6ff; h2: violet #8a5cff; h3: amber #ffb347; heat adds white-hot additive. Palette via mix chain in shader.
  • heat decay: CPU-side, update per-frame: decay all "cooling" cells; store cooling list. Alternatively decay in shader via uTime and last-topple-time attribute (aT): heat = exp(-(uTime - aT)*k). That's elegant: aT instanced attr, updated only on topple; shader computes glow — no per-frame CPU color work, and smooth. When a cell topples: aH[i]=clampedH; aT[i]=simTime. Upload via update ranges... but scattered updates; simpler: keep CPU arrays; each frame, collect dirty indices (toppled this frame, up to budget B); write into attributes; set needsUpdate when dirty count > 0. Full re-upload of two float arrays (G²=65k → 256KB+256KB) per frame only when dirty — acceptable (many frames will be dirty anyway during avalanches). At 384² (147k) it's 1.2MB/frame — still OK.
• Ground: large circular disk, dark, with radial grid rings shader (subtle), plus soft reflection fake? Keep simple: dark disk + faint polar rings, fog.
• Starfield + dust like epicycle (house style).
• Bloom + grade pass (same as house style).

Interaction

• OrbitControls; pointer painting: raycast to ground plane (y=0) → cell → apply brush (radius slider) adding grains (each brush grain triggers avalanches). When actively painting, disable rotate on that pointer? Use: left-drag paints when "Brush" tool active; hold Shift to temporarily paint; or paint with left button when pointer over pile and "paint" mode enabled via toggle; default: left = orbit, but clicking pile without drag drops a "pinch" of grains? House style from cloud chamber: click chamber to drop muon. I'll do: single click/tap on the pile = drop brush grains; drag orbits (if moved > few px, don't drop). Plus dedicated "DRAW MODE (D)" that makes drags paint continuously (cursor crosshair). Good.
• Sliders: DROP RATE (grains/frame at emitters), SIM SPEED (topple budget per frame), BRUSH (radius 1-12), HEIGHT (exaggeration), GRID (select 160/256/384 rebuild).
• Emitter modes: Center / Twin / Ring / Rain / Off; plus checkboxes: sound, spin, glow (bloom?), towers/flat is HEIGHT slider.
• Preset seed buttons: "⌖ Center", "⇅ Twin", "◎ Ring", "☂ Rain", "■ Full House (all 3s)", "🗑 Clear". Actually make emitter mode buttons + separate seed buttons.
• Stats panel: readouts line (grains, topples, avalanches, fps) + log-log histogram canvas + log event feed (quakes).
• Quakes: avalanche size ≥ 20000 → camera shake + boom + log "M5.2 mega-avalanche — 84,201 topples". Magnitude from log10(size): M = (log10(s)-1)/1.
• Buttons: play/pause, sound, spin, snapshot, help (house style).
• Keys: Space, 1-5 emitters, B brush mode?, C clear, A sound, R spin, S snap, H help, +/- drop rate.

Audio

• Drone: two detuned sines low + filtered noise wind (like house style generative ambience).
• Avalanche sonification: per frame during avalanche, play short plucks; pitch from pentatonic scale chosen by log(topplesThisFrame); gain ∝ wavefront size. Implement lightweight pluck scheduler (osc + exp decay), cap ~24 plucks/sec.
• Quake boom: low sine sweep + noise burst.

Snapshot: render then toDataURL (preserveDrawingBuffer? epicycle calls renderer.domElement.toDataURL directly after composer.render presumably — they call snapshot which does composer.render() then toDataURL? Let me check line 998.

I have everything I need. Let me now design the demo carefully and write it.

Demo 038: "Sandpile" — the self-organized criticality cathedral

Physics recap (Bak–Tang–Wiesenfeld / Abelian sandpile):

• Grid G×G, each cell h ∈ {0,1,2,3} stable.
• Add grain: h++ → if h ≥ 4, cell topples: h -= 4, +1 to each of 4 von-Neumann neighbors (grains fall off the edge of the world = dissipation).
• Drive slowly (drop grains one at a time) → system self-organizes to critical state; avalanche sizes follow a power law P(s) ∝ s^(-τ), τ ≈ 1.0-1.3 for 2D BTW.
• Center-dropping on empty grid grows the famous fractal mandala.

Implementation details:

Ring buffer capacity: GG entries; a cell is only pushed when it crosses threshold and isn't queued, so max occupancy ≤ GG.

Topple processing per frame with budget B:

Wait — with the flag approach: if a cell is queued and receives more grains rising to 5,6,7, it's only in the queue once; when popped, we do h -= 4 once, leaving h possibly ≥4 → must re-push. Handle: on pop, h[i] -= 4; if (h[i] >= 4 && !inQ[i]) push again. Or simpler: don't use inQ at all; push every time a cell hits ≥4 on increment, and on pop check if (h[i] >= 4){ h[i]-=4; ... }. Duplicate pushes are possible but bounded in practice? Danger: queue overflow since capacity GG but pushes unbounded with duplicates... Actually total grains is bounded; duplicates arise when a cell receives a grain while already queued — bounded by in-degree × times... hmm, worst case many duplicates could overflow. With ring buffer sized GG, overflow wraps and corrupts. Safer: keep inQ flag, and on pop do inQ[i]=0; if (h[i]>=4){ h[i]-=4; distribute; if (h[i]>=4) { inQ[i]=1; push(i); } }. When distributing to neighbor: h[j]++; if (h[j]>=4 && !inQ[j]) {inQ[j]=1; push(j);}. This keeps each cell in queue at most once → capacity G*G guaranteed.

Avalanche tracking: drive drops happen at chosen emitters; each frame we add dropRate grains (each +1; if a grain triggers a topple, an avalanche starts). "Avalanche active" = queue non-empty. We track: if queue empty and a push happens → avalanche begins (id++). Each frame after processing, if queue empty and was active → avalanche finished → record into histogram. Note: with continuous dropping every frame, avalanches may merge — that's physically fine (it's one cascade while queue non-empty). For cleaner power-law, BTW uses separation of timescales (drop one grain, let cascade finish). With dropRate 1 and sim budget high, avalanches usually separate. With heavy driving they merge — still fine visually and statistically-ish. I'll compute stats per queue-empty-delimited cascade, and mention that in help.

Histogram: bins: log-spaced from 1 to 2^22 (~4.2M): 48 bins. count[bin]++. Draw on canvas: x = log10(size), y = log10(count), points, plus reference line τ=1.25 through a mid point. Decay counts ×0.999 per finished avalanche? No—keep cumulative; add "RESET STATS" maybe via clear. Draw with axes labels. Keep simple but pretty: dark canvas, cyan dots sized by count, amber dashed reference line, labels "1", "10²", "10⁴", "10⁶" on x-axis.

Rendering:

Use THREE.InstancedMesh with custom ShaderMaterial and add instanced attributes to its geometry: InstancedMesh already sets instanceMatrix; I'll ignore instanceMatrix in shader (or set mesh.count and identity...). Cleaner: use **************************try copying box attributes + THREE.Mesh with material using gl_InstanceID. Actually with InstancedBufferGeometry + Mesh, gl_InstanceID works. But InstancedMesh is the standard route and we can add extra instanced attributes to its geometry. InstancedMesh renders with instanceMatrix unless shader ignores it. My custom vertex shader just won't reference instanceMatrix. But three.js shader compilation: with RawShaderMaterial nothing is injected; with ShaderMaterial, USE_INSTANCING define is set for InstancedMesh — but I write my own vertex shader so I only use what I declare. I'll use InstancedMesh (count = GG) + ShaderMaterial + geometry.setAttribute('aH', InstancedBufferAttribute). Hmm, does InstancedMesh require instanceMatrix upload? It allocates GG×16 floats = 4MB @256 — wasteful but fine; skip setting it (defaults are zeros? instanceMatrix initialized to identity? THREE initializes instanceMatrix array to... In r170, new InstancedMesh creates instanceMatrix as Identity matrices? Looking at source: this.instanceMatrix = new InstancedBufferAttribute( new Float32Array( count * 16 ), 16 ); — zero-filled, NOT identity. Since my shader ignores it, zeros don't matter... but does WebGL upload a zero matrix attribute? Yes it uploads but unused by shader — the attribute won't be bound since shader doesn't declare it. Actually three.js only uploads attributes referenced by program. OK.

Alternative cleaner: use **************************try + THREE.Mesh:

With ShaderMaterial, instanceCount respected in WebGL2. gl_InstanceID available in WebGL2 GLSL 300 es — three.js ShaderMaterial compiles as GLSL3? ShaderMaterial defaults to GLSL1 (auto-converted: three prepends #version? For WebGL2, three converts shaders to GLSL3 with compatibility defines — texture2D → texture etc.). gl_InstanceID is available in WebGL2 shaders even in "GLSL1-style" via three's preprocessing (it adds #version 300 es). Yes — three.js with WebGL2 always uses GLSL 300 es; ShaderMaterial code written GLSL1-style gets converted, and gl_InstanceID is accessible. Many examples use gl_InstanceID with ShaderMaterial. Good.

Grid coords:

Scale: float hh = min(aH, 3.0); float sy = uBase + hh * uHeight; — uBase tiny slab for empty cells (0.05) so the plane reads as a mosaic even at h=0; uHeight from HEIGHT slider (e.g., 0.06 flat → 0.9 towers). Toppling flash: float glow = exp(-(uTime - aT) * 6.0); brightens.

Colors: palette mix:

Lighting: two directional dirs + hemi:

Top face brighter; rim glow via fresnel using view dir. Heat adds glow * vec3(1.5,1.2,0.9) making faces white-hot → bloom catches it.

Edge definition: since boxes have gaps (0.9 size, 1.0 cell), gaps give natural grid lines. Nice.

Base disk: circle radius ~ uG*0.72 with subtle radial rings shader + fog. Stars + dust as in house style.

Interaction — painting:

• Raycaster vs an invisible plane mesh at y=0 spanning grid (PlaneGeometry sized G*uCell, rotated -PI/2). Actually simpler: mathematical ray-plane intersect with y=0 plane manually from camera ray through NDC. Use THREE.Raycaster with plane object — fine.
• pointerdown on canvas: record pos; if drawMode → start painting stroke. pointermove: if painting → paint at cell (interpolate between last and current cell to avoid gaps; brush radius). pointerup: if !drawMode and moved < 6px → single "pinch" drop (brush grains × maybe 8). If drawMode → end stroke.
• Draw mode toggle button + key D; cursor changes.

Emitter logic per frame (when playing):

• mode 'center': drop rate grains at center cell (spread within 2×2 for evenness).
• 'twin': two points at ±G/6.
• 'ring': rate grains distributed along a circle radius G*0.28, angle advances with time → slowly rotating ring emitter.
• 'rain': rate grains at random cells.
• 'off': nothing (painting only). Seeds (one-shot actions):
• 'Clear' — zero heights.
• 'Full house' — all cells = 3 (then rain → SOC cascade storm).
• 'Crater' maybe. Keep 2 seed buttons.

Also on emitter-mode buttons: clicking 'center' when grid empty starts mandala. Log messages with flavor text.

Quake: on avalanche finish with size ≥ QUAKE_MIN (e.g., 15000): magnitude M = (log10(size)-2.0).clamp(0.5, 6); camera shake amplitude ∝ M (decaying offset applied to camera... with OrbitControls, apply temporary offset to controls.target? simpler: shake renderer canvas via CSS transform? Cleaner: apply shake to camera position each frame post-controls: camera.position.add(rand*amp); amp decays exp). Also boom sound + log: M${M.toFixed(1)} cascade — ${size.toLocaleString()} topples over ${area} cells.

Sound design (WebAudio):

• master chain: master gain → lowpass → compressor → destination (house style).
• Ambience: brown-noise through slow LFO'd lowpass (wind) at low gain + deep drone (55Hz + 55*1.5 detuned sines, very quiet).
• Pluck scheduler: each frame during avalanche, if topplesThisFrame > 0, schedule 1-3 plucks: pitch from pentatonic minor scale (A C D E G) across 4 octaves, index by floor(log2(topplesThisFrame)) + random walk; gain ∝ min(1, topples/budget)*0.15; triangle osc, exp decay 0.3s; also high sizzle: filtered noise gain ∝ wavefront activity (sand hiss) — a noise buffer through bandpass 3-6kHz, gain tracks sqrt(topplesThisFrame/budget). Sand hiss is the signature sound!
• Quake boom: sine 60→28Hz sweep 1.2s + noise lowpass burst, gain ∝ M.

Adaptive quality tiers (house style) + snapshot + help overlay + hint + log — same patterns.

HUD readouts: grains 1,234,567 · topples 5.6M · avalanches 8,412 · lost 12% · 60 fps.

Status line updates: on mode change etc.

Now sizes: G default 256. Grid rebuild select: 160 / 256 / 384. At 384, instanceCount 147,456 — fine.

Height scale: world units: cell size 1, grid 256 → spans 256 units?? That's large vs camera. Scale via uCell = 14/G*? Let's set world span S = 16 units: uCell = S/G (0.0625 at G=256). Box width 0.86*uCell. Height: uHeight in world units per grain — default 0.10 world units? At towers mode h=3 → 0.3. Hmm, relative to span 16 that's subtle. Let me param: HEIGHT slider 0..1 → uH = slider² * 0.5 * (16/... ) — set uH max ≈ 0.55 world/grain → 3 grains = 1.65 — a decent skyline. Default slider 0.45.

Camera: start position (11, 12, 11) looking at origin-ish target (0, 0.6, 0); controls minDistance 4 maxDistance 60; fog exp2 density ~0.008.

Bloom: strength 0.85, radius 0.5, threshold 0. Heat glow values up to ~2.5 in shader → blooms nicely.

Histogram canvas: width 540 (attribute) × height 128, CSS 100%/64px like epicycle's spectrum canvas.

Structure the HTML per house style: same fonts, glass panels, top-right round buttons, bottom-left panel, event log top-left under header, hint bottom-center, help overlay.

Panel sections:

• EMITTER (grid of buttons): ⌖ Center (1), ⚯ Twin (2), ◎ Ring (3), ☂ Rain (4), ⏸ Off (0)... plus seed row: ▦ Full house (F), ✕ Clear (C), ✎ Draw (D).
• DRIVE: DROP RATE slider (0–60), SIM SPEED slider (2k–120k log), BRUSH slider (1–12), HEIGHT slider (0–100%), GRID select (160/256/384).
• SHOW checkboxes: sound (A), spin (R), glow (bloom) (B)? — call it "bloom" key B... careful B maybe brush. Use G for glow toggle. Keys: A sound, R spin, G bloom... wait 'g' in epicycle was ghost. Fine, per-demo keys can differ.
• AVALANCHE SPECTRUM canvas + note "log–log · size s vs count · dashed slope τ ≈ 1.25".

Top-right buttons: play/pause ⏸/▶, sound 🔊, spin ⟳, snap 📷, help ?.

Status text: e.g. "raining grains — avalanche #842 in progress…".

Readouts line as planned.

Log events: mode switches, quakes, milestones ("pile reached 1M grains"), tier changes.

Milestone check: when total grains crosses powers-of-2 ×1e5? Simple: at 100k, 500k, 1M, 2.5M, 5M, 10M → log "◆ 1,000,000 grains of sand".

Draw interpolation: Bresenham-ish line between last cell and current; apply brush disc radius r: for dx,dz in disc: addGrain. To keep avalanche semantics clean, grains added via brush each may trigger queue pushes — all good.

Performance of brush: radius 12 → ~450 cells per event — fine.

Per-frame dirty attr upload: maintain dirty Int32Array list + count; on topple/drop record index (may duplicate — fine, writing same value twice OK; dedupe optional). After processing, write aH/aT from h/lastT arrays for dirty indices, set needsUpdate=true (full buffer upload — 2 × G² × 4B; at 384² ≈ 1.2MB — ok at 60fps? ~70MB/s — fine on desktop GPU, and tiers will help). Alternatively use addUpdateRange with min/max span: compute minIdx/maxIdx of dirty, single range upload of the span — usually avalanches are local → small span! Great optimization: attr.clearUpdateRanges(); attr.addUpdateRange(min*1, max-min+1). In r170 the API: attribute.updateRanges — there's addUpdateRange(start, count) and clearUpdateRanges() (added r159+). I'll use it guarded by existence check, fallback needsUpdate.

Hmm wait, actually there's subtlety: needsUpdate=true is required to trigger upload even with updateRanges? In r170: setting attribute.needsUpdate = true triggers upload honoring updateRanges. I'll set both: clearUpdateRanges + addUpdateRange + needsUpdate = true. Fallback: if methods missing, just needsUpdate.

One more visual: boundary sink glow — cells at edge lose grains; could flash faint when losing. Skip — heat from toppling is enough.

Also a drop marker: where emitter drops land, spawn small ring/sparkle? The toppling already shows. For center mode, a faint vertical light beam at emitter position showing where sand pours — a slim additive cylinder from sky to pile + pouring particle stream (Points, ~120 particles falling). Nice touch and cheap. I'll add: emitter beam mesh (cylinder, additive, subtle) + falling sand points above emitter. For rain mode: spread mini-beams? Just make rain drops fall from sky across grid: Points with velocities, respawn at top — 300 points. For ring: beam follows ring angle. Twin: two beams. Off: hide. This adds a lot of life. Implement EmitterFX class: beam cylinder (scaled thin), plus point stream.

Ring geometry: beam at (rcosθ, 0..6, rsinθ). Points: each has x,z near emitter, y falling from ~7 to pile top (approx 2); reset to top with slight jitter. ~140 points per beam, up to 2 beams (twin) / 1 for center & ring; rain = 260 points random.

Pile top under emitter for beam length: just make beam fixed height 0→6, additive faint — fine.

Camera shake: shake scalar; each frame if shake>0.001: camera.position.x += (rand-0.5)*shake; etc; shake = exp(-dt3). Apply AFTER controls.update() to avoid fighting damping... it offsets once per frame then next frame controls recalc from camera state... OrbitControls derives from camera.position each update → offset accumulates into state — small random walk acceptable since shake decays; but safer: apply offset, render, then subtract it back. I'll do: save pos, add offset, render, restore. Clean.

Play/pause: pauses emitters + topple processing (freeze), still allows orbit.

Let me also add keyboard: Space play/pause; 1-4 emitter modes; 0 off; D draw; F full house; C clear; A sound; R spin; G bloom; S snapshot; H help; +/- drop rate.

Help overlay table accordingly.

Title: Sandpile — self-organized criticality · Three.js. Header: "SANDPILE" / "SELF-ORGANIZED CRITICALITY". Status default text.

Now, index.html card entry. Follow the verbose style of 037's card. Compose description:

"Drop sand one grain at a time and watch order emerge for free — the Bak–Tang–Wiesenfeld Abelian sandpile, the archetype of self-organized criticality. A 256² grid of glowing cells holds 0–3 grains; a fourth grain topples the cell, handing one grain to each neighbour and possibly lighting an avalanche that races across the pile as a white-hot wavefront. Choose the center emitter and grow the famous fractal mandala patch by patch; switch to rain, twin-peak or rotating ring drive; seed a "full house" of 3s and watch a continental cascade; or press D and draw rivers of sand with your own brush. Every cascade is counted: the live log–log histogram piles up avalanche sizes against the power-law slope P(s) ∝ s^−τ (τ ≈ 1.25) — the same statistics as earthquakes, forest fires and stock crashes. Big cascades register as magnitude-M quakes with camera shake and a sub-bass boom; sand hiss and pentatonic plucks sonify the wavefronts. Featuring instanced-box GPU rendering with per-cell glow timestamps, adaptive sim budget up to 120k topples/frame, emitter beams with falling-sand particle streams, generative WebAudio, UnrealBloom plus vignette/grain/chromatic grade, three grid sizes, adaptive quality tiers, PNG snapshots, keyboard shortcuts and full touch support."

Good. Now write the code. Let me be careful with:

• FFT not needed.
• All ids consistent.
• node --check to validate JS syntax (extract script to a .mjs and check).

One risk: gl_InstanceID in fragment? Only use in vertex. Fine.

Vertex shader:

Wait: box position attribute is ±0.5 in x,z (size 1) — after translate(0,0.5,0), y in [0,1]. p.xz = uCell scales footprint to uCell; box width 1uCell — but I want gaps: box geo width 0.86 → p.xz in ±0.43 → footprint 0.86*uCell. Good.

Note: gl_InstanceID / uG — integer division OK in GLSL ES 3.0. Modulo via subtraction fine.

Fragment:

uCamPos = camera.position uniform updated per frame. (cameraPosition built-in is available in ShaderMaterial actually — three injects uniform vec3 cameraPosition; into vertex AND fragment? In three, cameraPosition is a built-in uniform in the vertex shader only... Actually three declares uniform vec3 cameraPosition; in common vertex prefix; for fragment it's not declared by default. I'll pass uCamPos.)

Heat attr aT stores simTime of last topple; initial -1000.

uBase = 0.045 world; uH = slider mapping.

Data flow per frame:

flushDirty: for i in dirtyList: aHarr[i]=h[i]; aTarr[i]=lastTop[i]; compute min/max; set update ranges on both attrs; needsUpdate.

lastTop: Float32Array CPU mirror (aT array itself IS the CPU array — write directly into attribute array, same for aH using h[i]). So aHarr[i] = h[i] at dirty time; aTarr[i] = simTime. No separate mirrors needed.

Drop function: addGrainsAt(x, z, n=1).

Emitters per frame (dropRate grains distributed):

• center: jitter within radius 1: (cx + ri(-1..1), cz + ri(-1..1)).
• twin: split rate between two foci ±G/6, jitter 1.
• ring: radius G*0.28, angle θ advances 0.05 rad/frame + each grain θ += small; jitter 1.
• rain: random cells, whole grid.

Milestone + status updates.

Histogram drawing: canvas 2D: bg transparent dark; axes faint; for each bin with count>0: x = map(log10(binCenter), 0..6.6), y = map(log10(count), 0..maxLog). Draw circles cyan alpha 0.9 size ~3. Reference line: choose anchor at bin containing count median... simpler: line from (s=2, y0) with slope -1.25 where y0 = count at smallest nonzero bin ≥... Use linear regression on (log s, log N) for bins with N>0 within s∈[2, 1e5] to FIT τ live! That's cooler: "measured τ = 1.31". Draw fitted line + show τ in note. Yes! Fit via least squares; update every second; show τ ≈ x.xx (fitted).

Bins: size s from 1 to 2^22; bin edges e_k = 2^(k*0.35), k=0..19 → 20 bins? For a nice plot want ~24 bins: step 0.28 in log2 → 24 bins to 2^22. Use NB=26, log2 step 0.26 → max 2^(6.76)≈108? no: log2 max 22 → 22/0.26 ≈ 85 bins too many. Let me use NB=32 bins over log10 range 0..6.6: step 0.206 log10. Bin index = floor(log10(s)/0.206). Counts Float64.

Fitting: for bins with count ≥ 3 and binCenter ≥ 3 and binCenter ≤ 3e5: LSQ on (x=log10 c, y=log10 N) → slope τ̂. Display τ̂ = -slope.

Canvas draw: width 540, height 128 (CSS 100%×64px): x pixel = 30 + (log10s)/6.6 * 495; y pixel = 108 - (log10N)/maxLog * 92. maxLog = max count log. Axes labels: "10⁰ 10² 10⁴ 10⁶" along bottom; left "N(s)". Dashed amber fit line.

Audio engine per house style with ensure/setOn +:

• noise buffer (2s brown noise).
• hiss: noise → bandpass(4200, Q 0.7) → gain node (hissGain), target = clamp(sqrt(topplesPerSec/40000))*0.5 smoothed.
• drone: osc 55 sine + 82.5 sine, gains 0.035/0.02 + slow LFO on filter.
• pluck(freq, gain, pan): triangle osc + gain env.
• boom(mag): sine 70→26 sweep, gain 0.5*mag/6; plus noise through lowpass 300 → gain env.

topplesPerSec tracked via EMA.

Pluck scheduling in animate: if audio.on && avalanche active: rate = min(3, 1+floor(log10(done))) plucks per frame; choose pitch: pentatonic = [0,3,5,7,10] semitones over A; freq = 110 * 2^(oct) * 2^(semi/12); pick via (random walk index). gain ∝ min(1, done/budget)*0.12.

Quake detection on avalanche end: size ≥ 15000 → quake(M). M = max(0.8, log10(size) - 1.8). e.g. 15k → 2.4; 100k → 3.2; 1M → 4.2.

Note: with budget batching, an avalanche "ends" when queue drains — then next frame's drops may start a new one. Avalanche object: {id, size, area, t0}. If queue empty at frame end && active: finalize. Also finalize duration = framesActive (count frames where processing happened while this avalanche alive).

Camera shake & boom & log on finalize if big.

Reset stats on clear/seed/grid change: counts.fill(0); totals reset? Keep totals across clears? Reset both for clarity. Avalanche id continues.

Draw spectrum... I mean histogram: every 0.5s when changed.

Grid size change: rebuild all arrays + geometry attrs (set new InstancedBufferAttributes), instanceCount, uG, uCell; clear; log.

Cell size constant world span: SPAN = 15; uCell = SPAN/G. Camera dist ~ 16-19 initial. minDistance 3.5, maxDistance 70. Base disk radius SPAN*0.78.

Ground disk shader: rings every ~2 world units faint + radial fade to transparent at edge; color deep blue; also faint grid lines aligned to cells? Simple concentric rings + center glow. Write small ShaderMaterial for disk, transparent, depthWrite false.

Emitter beams:

Two beams max (twin). Position per mode each frame; visible = playing && mode needs beam(s).

Sand stream points: one Points system, 420 particles; each has target emitter index; when mode 'rain' → random xz each respawn; 'center'/'twin'/'ring' → near beam xz. y from 5.5 → ground (approx pile top 0.4). velocity ~4.5/s. Additive small points amber-ish.

Also falling "grain sparkle" when painting? skip.

Alright — also the "hint", "help", "log", "status", "readouts", tiers, resize, snapshot, spin — house style.

Potential pitfall: pointer events on canvas conflict with OrbitControls when painting in draw mode — need controls.enabled = false while painting stroke in drawMode. Simple approach: on pointerdown in drawMode: controls.enabled=false; painting=true; on up: controls.enabled=true. For quick-click drop (non-drawMode): don't disable controls; just measure movement; if <6px on pointerup → drop pinch at cell. OrbitControls uses its own pointer handlers on same element; both can coexist.

Ray to cell: use THREE.Raycaster.setFromCamera(ndc, camera); intersect a math plane: new THREE.Plane(new THREE.Vector3(0,1,0), 0); ray.intersectPlane(plane, out v3) → cell ix = floor(v.x / uCell + G/2), iz = floor(v.z / uCell + G/2). Bounds check.

Pinch drop: brush radius r → disc of grains, 3 grains each cell → visible plop + likely avalanche if near-critical. Draw stroke: interpolate positions, 1 grain per cell per event, throttled: max ~800 grains per stroke event... fine.

Also while drawMode, change cursor: canvas.classList.add('drawing').

Milestone logs: thresholds [1e5, 5e5, 1e6, 2.5e6, 5e6, 1e7, 2.5e7, 5e7, 1e8].

Status text default: "pouring sand on the origin — the pile remembers every grain". Update per mode.

Readouts: grains ${fmt(totalGrains)} · topples ${fmt(totalTopples)} · avalanches ${fmt(totalAval)} · dissipated ${pct}% · ${fps} fps.

Let me now also double check r170 InstancedBufferAttribute + InstancedBufferGeometry API: geo.instanceCount. In r170, InstancedBufferGeometry has instanceCount property (default Infinity). Setting explicit count works. DynamicDrawUsage import from THREE. addUpdateRange: BufferAttribute.prototype.addUpdateRange(start, count) exists in r170 (added r159), and clearUpdateRanges(). Upload honors ranges when updateRanges.length non-empty... In WebGLAttributes.update, they check attribute.updateRanges — hmm, actually let me verify: In r170 source, BufferAttribute has updateRanges = [], addUpdateRange, clearUpdateRanges; WebGLAttributes.updateBuffer uses updateRanges if length > 0 else full update, but ONLY when updateRanges non-empty... Let me just check quickly by downloading three r170 source? That's a big file; maybe grep from unpkg. Let me import it and grep — it's ~1.3MB, fine.

Actually to be safe I'll write:

And verify via source grep that r170 honors updateRanges for non-index attributes regardless of needsUpdate ordering. needsUpdate setter sets version++. In WebGLAttributes.update: if version > cached version → updateBuffer with ranges. Good — I'll verify with grep.

Also gl_InstanceID: three r170 ShaderMaterial vertex prefix includes #version 300 es when WebGL2 — and three's WebGLProgram prefixes for fragment/vertex declare lots of built-ins. gl_InstanceID is a built-in GLSL3 var, no declaration needed. OK.

int modulo: gl_InstanceID % uG valid GLSL3 for int. uG as uniform int. I set uniform value as JS number — fine.

One more consideration: precision for int uniforms: default highp int in WebGL2 vertex. OK.

Edge case: painting while paused — allow (grains just sit / topple? if paused, don't process queue; grains accumulate ≥4... display shows h≥4 → clamp 3 color; on resume they cascade. Acceptable: note "paused". Actually let painting process topples even when paused? Simpler: painting only allowed... just let queue process if painting even when paused? I'll process topples when (playing || painting). Minor detail: I'll run processTopples whenever queue non-empty and (state.playing || justPainted). Simplest: always process queue regardless of playing; pause only stops emitters. That's nice: pause = stop the rain, avalanches finish. Yes — do that.

Then "playing" only gates emitters + streams. Good simplification.

Now — avalanche finalize: happens when queue drains. During pause, still finalize. Good.

Let me also add subtle "settling" — when heat glows overlap with bloom it'll look molten.

Title of folder: 038-sandpile.

Let me write the file now. I'll write it in one go with the write tool, then node --check the extracted module, fix issues, then update index, then done.

Also, small detail: renderer.domElement event listener for contextmenu prevented (house style). Snapshot filename 'sandpile-criticality.png'.

Fog: FogExp2 0x04060c density 0.0075? With SPAN 15 and camera ~17, density 0.02 would fog everything heavily (e^{-0.0217} ≈ 0.71 transmission... fog factor 1-exp(-(ddensity)^2)? FogExp2 uses exp(-(densityd)^2): (0.0217)=0.34 → exp(-0.115)=0.89 — fine, epicycle used 0.02 with scene ~7 units. Mine spans 15-30 units; use 0.008 → (0.008*20)=0.16 → exp(-0.026)=0.975 subtle. Good.

Stars radius 60-120 (bigger scene). Dust range ±(10, 5, 10).

Base disk radius = SPAN*0.75 ≈ 11.3, shader: radial fade + rings: float ring = smoothstep(0.02, 0.0, abs(fract(r*0.5)-0.5)-0.47)... make: rings every 2 units: fract(r/2). Also polar spokes? keep rings + soft center glow. opacity ~0.5 * fade.

Also add a faint square "stage" outline around grid boundary: LineLoop rectangle at y=0.01, cyan alpha 0.25. Easy with BufferGeometry.

Let me write the whole thing now. I'll be careful about:

• All DOM ids referenced exist.
• No stray references.
• node --check passes (extract content).

Length estimate ~1000-1100 lines. Let me write it.

Key code structure:

Panel buttons layout: emitter grid 2×2 (4 buttons) + second grid row: Clear / Full house; Draw gets its own styled class (pink like epicycle's drawmode). Grid-size: 3 small buttons.

Slider values:

• sRate: min 0 max 60 step 1, value 8 (grains/frame)
• sSpeed: min 2000 max 120000 step 1000 value 30000
• sBrush: min 1 max 12 step 1 value 4
• sHeight: min 0 max 100 step 1 value 45 (%)

Grid default 256.

Sim budget slider display "30k".

OK writing now. Also remember: emitter needs ≥1 grain even at rate 0? No, 0 = manual only.

Status messages per mode:

• center: "pouring on the origin — a fractal mandala is coming"
• twin: "two springs — watch the avalanches interfere"
• ring: "a ring of springs, slowly turning"
• rain: "raining grains — the pile tunes itself to criticality"
• off: "hands on — click or draw to feed the pile"

Colors for log dots: cyan #7fd4ff default, amber #ffcf8a, violet #b78bff, pink #ff8ac2.

Now the JS. Careful ordering: define state, dom helpers, sim arrays, scene, materials, mesh, base, stars, dust, beams, streams, composer, audio, histogram, emitters, input, ui wiring, tiers, resize, animate, init.

Let me think about paintAt(clientX, clientY) → returns cell or null. And brush application:

dropGrain(i): totalGrains++; h[i]++; if h[i]>=4 && !inQ → push + start avalanche if queue was empty.

Avalanche start detection: track queueLen(); in dropGrain after push: if (!avalActive){ avalActive=true; curAval={...} }.

processTopples(B):

Wait re-push logic: if (h[i]>=4 && !inQ[i]) — inQ[i] was just cleared; if still ≥4 requeue. But also note nb() pushes neighbors.

nb(j): h[j]++; totalGrains? No — grains redistribute, not added. nb: h[j]++; if (h[j]>=4 && !inQ[j]){inQ[j]=1; push}. Display attr aHf[j] updated when? Neighbor heights change without toppling — they gain grains (1→2→3). Their aH must update too. Mark them dirty: aHf[j]=min(h[j],3); dirty push j. But aT unchanged. So dirty list includes gains. That's more entries (×4) but fine.

Cap dirty length = CAP (GG) — could exceed? Per frame, topples ≤ B ≤120k, gains ≤4B — dirty could hit 480k > CAP. Dirty list entries can repeat (same cell many times). Simplest: make dirty array length CAP and just stop adding beyond — but then some cells miss attr update → stale visuals. Alternative: mark cells with a per-frame stamp and rebuild dirty list afterward by scanning changed region? Scanning whole GG (65k-147k) per frame is fine (~0.1ms). Approach: maintain stamp = Uint32Array(G*G), frameId counter; when cell changed: if stamp[i]!==frameId {stamp[i]=frameId;} — then after processing, iterate full grid to collect? Full scan per frame is OK (147k simple loop ~0.5ms). Even simpler: scan whole grid every frame and sync aHf where h[i] changed vs aHf[i]! aHf[i] stores displayed height; if mismatch → update + record min/max range. And aTf updated on topple only (already written at topple time). So per frame: loop i over G*G: const hh=h[i]; if (hh!==aHraw[i]){ aHraw[i]=hh; changed=true; track lo/hi }. Where aHraw is the attr array storing actual h (shader clamps). Wait shader clamps min(h,3) — so attr can hold h directly (int as float). 147k comparisons per frame — trivial. And aT updates written directly at topple time; aT upload range — same lo/hi span as heights? Topple cells ⊆ changed cells? A toppled cell's h changed (h-=4) → yes in changed set. But a neighbor that only gained +1 is in changed set too — its aT unchanged, but uploading aT span including it is harmless (same value re-uploaded). So: one span [lo,hi] applied to both attributes.

But careful: full-scan approach re-uploads span even when avalanche tiny (span small) — fine. When idle (paused, no queue), h never changes → no upload. When painting while paused: h changes on painted cells → but topples not processed while paused?? I decided: process queue always. Painting adds grains → may push queue → processed next frame regardless of pause. Good.

However: during pause with emitters off, scanning still needed for painted cells — full scan every frame regardless: 147k iterations cheap. OK.

But aT: topple writes aTf[i]=simTime immediately even mid-batch; upload at frame end with span. Good.

Heights as float attr: values up to maybe 8 briefly; shader clamps to 3 for palette but heat shows; also h≥4 → make it flash brighter: in shader, if (h > 3.5) add white? Heat already covers topple flash. Clamp is fine.

One more: exp(-max(uTime-aT,0)*5.5) — cells never toppled have aT=-1000 → uTime-(-1000) huge → exp(-huge)=0. Good.

Now the stream particles:

Beams similarly: beam1 (and beam2 for twin) positioned at emitter world xz, visible same condition; beam rotation for ring n/a.

Emitter world pos helpers: cellToWorld(x,z).

Now histogram fit & draw — done above.

Audio pluck scheduling — cap plucks: track plucksThisSecond; if < 40 schedule. Each frame when done>0: nPluck = done>20000?3: done>2000?2:1; for each: pluck(pickFreq(), gain*rand).

pickFreq: pentatonic A minor: semis [0,3,5,7,10]; walk: idx += ri(-2..2) clamp 0..14 → oct = idx>>? Let me define scale array of 18 freqs: base 110 * 2^(s/12) for s in [0,3,5,7,10,12,15,17,19,22,24,27,29,31,34,36]... precompute 16 entries from 110 to ~880. walkIdx random walk. gain 0.05-0.14.

Hiss: bandpass noise, hissGain.setTargetAtTime(min(0.5, sqrt(done/B)*0.6), t, 0.06) each frame; when idle → decay target 0 (set when done==0).

Boom(mag): as described; gain = min(0.55, 0.18 + mag*0.06).

setOn like house: master ramp; start drone+wind on ensure (they're cheap; start them when audio enabled; keep running while on, gain 0 when off — master gain 0 anyway).

Drone details: osc1 sine 55, g 0.05; osc2 sine 551.007 (beating) g 0.04; osc3 sine 1101.5=165? use 82.5 g 0.02; through shared lowpass 400 → master. Wind: noise → lowpass 500 w/ LFO(0.07Hz, depth 300) → gain 0.05 → master.

UI wiring: all buttons/sliders/keys. Mode buttons set active class.

τ note: fit: P(s) ∝ s^−τ · τ ≈ 1.31 (n=…).

Now — writing the actual file. Also include meta description? House files don't seem to have; skip.

Also title: "Sandpile — self-organized criticality · Three.js".

Let me write it. I'll write the file via read_write_file_in_shell_environment (write mode). It's long; I must be meticulous. Then extract script and node --check.

Additional check on ShaderMaterial + InstancedBufferGeometry + instanceCount in r170: WebGLRenderer renderObjects: for InstancedBufferGeometry, instanceCount used. Yes.

Raycaster far: default fine.

Camera initial: position.set(13.5, 12.5, 13.5); target (0,0.4,0).

controls.maxPolarAngle = Math.PI*0.495 (don't go under floor).

Now writing. (Also remember iOS/touch: pointer events with touch-action none on canvas — house style does that.)

For the index.html card, insert after <!-- New demos are added here --> line, matching indentation of previous entries (they use varying indentation; I'll use the same as 037's block: 10 spaces for per the file — looking at output: <a class="demo-card" href="./037-epicycle/index.html"> — 10 spaces. Inner lines 16 spaces. I'll mirror.)

Description text for the card (concise-but-rich like others):

"The archetype of self-organized criticality, live in 3D — drop sand one grain at a time onto a 256² grid of glowing cells; a fourth grain topples a cell, hands one grain to each neighbour, and the resulting avalanche races across the pile as a white-hot wavefront. Pour everything onto the origin and grow the famous fractal mandala patch by patch; switch to rain, twin springs or a slowly turning ring emitter; seed a “full house” of 3s and trigger a continental cascade; or press D and draw rivers of sand with your own brush. Every cascade is logged: the live log–log histogram stacks avalanche sizes against a fitted power law P(s) ∝ s−τ — the same statistics as earthquakes, forest fires and market crashes — while big cascades register as magnitude-M quakes with camera shake and a sub-bass boom. Sand hiss and pentatonic plucks sonify the wavefronts. Featuring instanced-box GPU rendering with per-cell glow timestamps, an adaptive sim budget up to 120k topples/frame, emitter beams with falling-sand particle streams, generative WebAudio, UnrealBloom plus vignette/grain/chromatic grade, three grid sizes (160/256/384), adaptive quality tiers, PNG snapshots, keyboard shortcuts and full touch support."

Good. Write the demo file first.

Now let me validate the JavaScript syntax. Extract the module script and run node --check. Also I should double-check some logic:

1. In emitDrops, x = (G >> 1) + (Math.random() * 3 - 1.5) | 0; — operator precedence: + binds tighter than |, so ((G>>1) + (rand-1.5)) | 0 — floor-ish truncation. OK, valid but for negative numbers truncation rounds toward 0 — values here are large positive, fine.

2. state.shake applied around render — good.

3. audio.pluck(0.1) called on pointerup even when audio off — pluck() checks this.on. Good.

4. In processTopples, when a cell receives from neighbor during another cell's topple — giveGrain handles pushes. The pushCell inside processTopples for the re-queue: if (h[i] >= 4 && !inQ[i]) pushCell(i); — inQ[i] was cleared at pop; fine.

5. Queue ring buffer: qTail == qHead means empty. If queue completely fills (CAP entries), qTail wraps to qHead and looks empty! Danger: when avalanche covers the whole grid, queue could theoretically hold up to CAP cells (each in queue at most once thanks to inQ flag) — if ALL CAP cells get queued: qTail advances CAP times → qTail == qHead → indistinguishable from empty → loop exits early, leaving h≥4 cells unprocessed, avalanche "finishes" prematurely. That's an edge case; visually it just means the cascade pauses until next push... actually no: done>0 but queue appears empty → finishAvalanche called → next topple push starts new avalanche. The unprocessed cells with h≥4 but inQ=1 would never be re-pushed... stalemate: they'd sit ≥4 forever (visually flashing white via vHot). Hmm, wait: if queue wraps exactly, the cells were pushed but qTail==qHead makes the while loop think empty. Their inQ flags stay 1. They'd remain "stuck" — pile frozen super-critical.

   Fix: track queue length explicitly with a counter instead of head/tail comparison. Let me add qLen counter: pushCell increments, pop decrements. Empty test: qLen===0. Capacity: since inQ prevents duplicates, qLen ≤ CAP always — ring buffer with CAP slots is exactly sufficient.

6. histChanged triggers syncAttrs — that's wrong logic: if (done > 0 || histChanged) syncAttrs(); — histChanged is about histogram, not attrs. syncAttrs should run when h changed: when done>0 or after painting/emitting drops (drops change h too!). dropGrain increments h — if a grain lands on a 2-cell making it 3 without topple, aHraw stale → visual not updated until next topple. Must sync after any drops. Let me use: if (done > 0 || droppedThisFrame > 0) syncAttrs(). Track drops per frame: emitDrops returns count; painting calls applyBrush (grains added). Simplest: compare state.totalGrains cached per frame: const grainsBefore = state.totalGrains at frame start; after processing: if (done > 0 || state.totalGrains !== grainsBefore) syncAttrs();.

7. In syncAttrs I only update aHraw — aT written at topple time. When grid rebuilt or cleared, aTraw.fill(-1000) + aHraw filled 0 via new array — but attrs reference those arrays; on clearPile, aHraw values stale (they hold old heights) — syncAttrs will detect differences vs h (all 0) and update spans. Good, since h.fill(0) changes most cells → lo=0, hi=CAP-1 → full upload. But note syncAttrs is only called when done>0 or grains changed; clearPile doesn't change totalGrains... After clear, if no drops and no topples, syncAttrs never runs → pile still shows old heights! Fix: call syncAttrs directly in clearPile (and in buildGrid, initial sync not needed since both zero — aHraw new zero array matches h zeros; but "Full house" does h.fill(3) → call syncAttrs after fill too. Easiest: set a flag needSync = true in clearPile/fullhouse/grid rebuild, and animate checks if (done > 0 || grainsChanged || needSync){ syncAttrs(); needSync=false; }.

8. buildGrid disposes gridMat — ShaderMaterial dispose fine. But gridGeo.index = box.index — box geometry not disposed (small leak on rebuild, negligible; but let me dispose box after copying? The attributes are shared with gridGeo; disposing box would free GPU buffers... box never uploaded itself, its attributes get uploaded as part of gridGeo. Don't dispose box (it owns the arrays). Fine — tiny CPU-side leak per rebuild, acceptable (only on grid switch).

9. stageLine.material not disposed — negligible.

10. Beams: state.mode !== 'rain' — rain has no beams, correct; flakes still fall everywhere for rain. Good.

11. updateStream early-returns when opacity < 0.02 — but then flakes don't respawn; fine since invisible.

12. hist canvas axis label: ['⁰','','²','','⁴','','⁶'][e] with e stepping 0,2,4,6 — gives '⁰','²','⁴','⁶'. Good.

13. tauNote element exists. drawHist called once at init. Good.

14. In vertex shader: uniform int uG; — setting value as JS number works. gl_InstanceID / uG integer division fine. Note: three.js ShaderMaterial on WebGL2 → GLSL3 conversion: three prepends #version 300 es and defines attribute→in etc. gl_InstanceID available. gl_FragColor — in GLSL3 conversion three defines out highp vec4 pc_fragColor; #define gl_FragColor pc_fragColor. Yes handled.

15. attribute float aH; with InstancedBufferAttribute + InstancedBufferGeometry — three binds as instanced automatically. Good.

16. FogExp2 affects ShaderMaterial? No — my custom shader has no fog uniforms, so no fog on the pile; base disk also custom (no fog). Stars/dust/points materials have fog by default (PointsMaterial fog: true default). Fog on distant points fine. The pile won't be fogged — acceptable (scene spans modest distances).

17. renderer.domElement pointerdown handler: if (e.target !== cv) return; — events on canvas only anyway since listener on cv. Harmless.

18. When drawMode and user drags, controls disabled — but OrbitControls may have already received pointerdown before our handler? Listener order: OrbitControls attaches its own pointerdown on the same element (attached during construction — earlier than ours). OrbitControls will start a rotate on pointerdown; we set controls.enabled=false after — OrbitControls checks enabled in onPointerMove? In recent three versions, OrbitControls onPointerDown returns early if this.enabled === false. Since controls was enabled at pointerdown, rotation starts... then we disable — onPointerMove checks enabled too, so rotation stops. On pointerup we re-enable. Small risk of a tiny camera jump at stroke start — acceptable; the alternative (stopPropagation) unreliable due to order. Actually better: in drawMode, disable controls when draw mode ENABLED, re-enable when disabled. Painting then doesn't need toggling. But then user can't orbit in draw mode without exiting — that's a reasonable UX (D toggles). Let me do that: setDrawMode toggles controls.enabled = !v. And in pointer handlers remove the enable/disable logic (keep controls.enabled true after stroke ends — it's managed by drawMode). But careful: painting flag gates pointermove. On pointerup: controls.enabled = !state.drawMode. Simpler and robust. I'll adjust: in setDrawMode: controls.enabled = !v; and remove controls.enabled manipulation from pointer handlers.

19. audio.pluck(0.1) on click — pluckIdx throttle fine.

20. Ring mode beams: single beam follows ringAngle. Good.

21. Quake magnitude log message uses aval.area — set. Good.

22. In finishAvalanche — state.totalAval++ then hist. Good.

23. Milestones reset on clear (state.milestone=0 via resetStats). Good.

24. syncAttrs loops full CAP every call — called every frame while dropping (grains change each frame). 147k iterations/frame — trivial.

25. One more: attr.addUpdateRange — exists in r170? Verify from three source. Let me grep the three module.

Also validate: histCtx.arc(X(ls), Y(n), ...) fine.

Y(ln) for fit line: passing Math.pow(10, icept + slope*0.5) — value could be < 0.9 → log10 clamped 0.9... if fit intercept low, line clipped at bottom — acceptable.

Also histTimer > 0.5 && histChanged — histChanged set false after draw; finishAvalanche sets true. Good. But I had used histChanged in the syncAttrs condition — removing that per fix above.

Let me apply the fixes: A. Add qLen counter; replace empty checks qHead !== qTail / qHead === qTail with qLen. B. Grains-change based sync + needSync flag. C. Draw-mode controls handling.

Then extract and node --check, plus a logic test of the sandpile core in Node (mock minimal): verify toppling conserves grains, queue handles full-grid avalanche (fill all cells 3, add center → massive avalanche processes completely and h≤3 everywhere after), and power-law sanity (not needed numerically). Also verify ring buffer wrap safety with qLen.

Let me write the fixes.

***********************************************************************************************************************************************************************************************ng.

Also fix the grid-rebuild handler to set needSync (clearPile already sets it — good, the rebuild calls clearPile which sets needSync). Good.

Also the stream flake ground check uses h[...] — fine.

Now also: in emitDrops for center mode: x = (G >> 1) + (Math.random() * 3 - 1.5) | 0; — wait, there's a subtle bug: | has lower precedence than +, so this is ((G>>1) + (rand)) | 0 — OK. But x could be fractional before the | 0... fine.

However there's a subtle issue: z = (G >> 1) + (Math.random() * 3 - 1.5) | 0; — same. fine.

Twin mode: z = (G >> 1) + ((Math.random() * 3 - 1.5) | 0); fine.

Now, one more check on syncAttrs — it's only syncing spans where h differs from aHraw. But aT: toppled cells always have h changed (h[i] -= 4 → differs from aHraw old value... wait: if a cell at 4 receives +4 during an avalanche and topples once: h goes 4→0 after topple (or accumulates first). aHraw before = 4 (synced last frame), after h = 0 → differs → in span. But consider a cell that topples twice in one frame batch and ends at same value? e.g., h=0, receives 8 grains (two topples): net h=0, aTraw updated but aHraw unchanged → cell not in dirty span → its aT (glow timestamp) never uploads → no glow for that cell even though it toppled twice! Hmm. In one frame batch of 30k topples this happens for some cells (especially near the center where pile is at high frequency). The glow would be missing on exactly the hottest cells.

Fix options: (a) maintain separate dirty tracking for aT: when toppling, record min/max topple index tLo/tHi; sync aT over union span. Simple: track tLo/tHi as globals reset each frame before processing; in processTopples update them; in syncAttrs, compute span per attribute: for aH use [lo,hi] from h-diff scan; for aT use union of h-span and tLo..tHi. But aT values for cells in span are already in aTraw — upload span [min(lo,tLo), max(hi,tHi)] for aT. Edge: if no h changes but topples happened (possible? topple always changes h by -4 then maybe +grains... a toppled cell could end unchanged if it received exactly 4 after toppling. h scan misses it; but tLo/tHi catches it). Implement: globals tLo, tHi init CAP/-1 each frame before processTopples; update in the topple loop; syncAttrs takes both spans into account for aT.

Actually simpler: make aH scan use h[i] !== aHraw[i] OR i within [tLo,tHi]... no — span upload is by range, not per cell. So: aT span = union(h-span, t-span). aH span = h-span only (aHraw of topple-only cells unchanged anyway — value same).

But hmm, if h-span is empty and t-span non-empty: aH needs no upload; aT uploads [tLo,tHi]. Implement syncAttrs with both spans:

And reset tLo/tHi each frame in animate before processTopples: tLo = state.CAP; tHi = -1.

Wait — but there's an ordering subtlety: syncAttrs reads aTraw which was written during processTopples — good.

Also need tLo/tHi declared near aval. Let me patch.

Also another subtlety: if (done > 0 || ...) gates syncAttrs — if done>0 but all toppled cells ended with same h (rare), h-scan span empty but t-span covers → aT uploads. Good.

Next: verify attr.addUpdateRange exists in three r170 — check via grep on the unpkg source. Let me download three module and grep.

Then run node --check on extracted script. Also run a headless logic test of the sandpile core (copy the core functions into a test harness) verifying: grain conservation (total = sum h + lost), full-grid avalanche terminates with all h ≤ 3, queue never corrupts (qLen consistent), center-drop mandala grows (sum h after N drops matches), and stats/histogram run. I'll mock the DOM-free parts: the core uses state, aval, histBins — I can extract with a small sed range or just re-implement the harness by copying the functions from the file (risk of drift). Better: write a small node test that reads the HTML, extracts the module script, stubs browser globals? The script imports three — can't run in node without network/DOM. Simplest: extract just the "Sandpile core" functions region plus state/aval/hist decls into a test file programmatically: they only depend on state, aval, histBins, aTraw, syncAttrs not needed... dropGrain uses state.totalGrains; pushCell uses aval & queue & qLen globals. In the file these are top-level let — I can extract the block from const SPAN through finishAvalanche end, stub audio and log, remove THREE references (core block has none? finishAvalanche calls audio.boom and log — stub them. state object includes THREE-free fields — but the state literal in the file is pure data. Let me extract via sed line numbers: from const SPAN = 15; to the end of finishAvalanche function, then append test driver. The block references $ (DOM) in... finishAvalanche doesn't; drawHist not included. histBins/histChanged are in the block. Also log and audio referenced — define stubs before. And state etc all inside block. h, inQ... declared inside block but ALLOCATED in buildGrid (not included) — test driver allocates them manually (mirror buildGrid's array init). Let me do that with sed: find line numbers first.

***************************************************************************************************et.

**************************************************************************************************************************************************************************************re.

**********************************************************************************************************************************************************ge.

The import failed to save. Let me try curl instead.

A progress checkpoint at 50% max time. I need to move efficiently now. Let me continue: verify how updateRanges are used in WebGLAttributes (to confirm partial upload works with needsUpdate), then run the headless core logic test, then update the index page, then finish. Let me batch a few things.

Check the WebGLAttributes update logic quickly.

Partial uploads via updateRanges work with bufferSubData in r170 (honored when the attribute is updated). But I need to check the condition under which updateBuffer is called — it's called from update() when version changes (needsUpdate). Let me quickly check that when updateRanges is non-empty it uses them instead of full buffer upload. Let me look slightly above line 13780.

Confirmed: r170 honors updateRanges with bufferSubData partial uploads, merging ranges, and clears them after upload. My usage (clearUpdateRanges + addUpdateRange + needsUpdate) is correct. Note: since the renderer clears ranges after upload, my per-frame clear+add pattern is consistent.

Now the headless logic test. Extract the core block from the demo source: from const SPAN = 15; through the end of finishAvalanche, excluding THREE-dependent parts. Let me check what's in that range: state (pure), sim arrays decl, aval/tLo/tHi/histBins/histChanged, DOM helpers ($ uses document — stub), fmt, ... wait, DOM helpers come after hist decls: const $ = id => document.getElementById(id); — stub document. Then "Three.js scene" section starts — I must cut before that. The core (pushCell/dropGrain/giveGrain/processTopples/syncAttrs/finishAvalanche) comes AFTER the whole scene/beams/composer sections in file order? Let me check order in the file: SPAN/state → sim arrays → avalanche bookkeeping → DOM helpers → Three.js scene (renderer, camera, stars, dust, disk, stage) → buildGrid/heightWorld → Sandpile core → emitters → beams/stream → post-processing → audio → histogram (uses DOM canvas) → interaction → UI wiring → tiers → resize → milestones → animate → init.

The Sandpile core block ("Sandpile core — the Abelian toppling rules" through finishAvalanche) is contiguous. It references: state, h, inQ, queue, qHead, qTail, qLen, mark, aHraw, aTraw (globals declared earlier), aval, histBins, histChanged (assigns — it's let, ok), NB/LMIN/LMAX, state.simTime, log(), audio.boom(), syncAttrs references gridGeo (THREE) — I'll stub syncAttrs out of the extracted range (it sits between processTopples and finishAvalanche). So extraction: from "/* ================================================================\n Sandpile core" up to "/* avalanche finished" — that includes syncAttrs (references gridGeo.getAttribute — but only called if I call it; I can just not call syncAttrs in the test, it's defined but never invoked → fine, no THREE at definition time... it references gridGeo variable — declared at top as null — fine, never called).

finishAvalanche references audio.boom and log → stub both. dropGrain → pushCell → aval. All good.

Test driver:

But h etc are let declared in demo file; if I extract from const SPAN through finishAvalanche, the declarations let h, inQ... are included (they're in the sim arrays section between state and aval). The allocation happens in buildGrid (not extracted) — test driver allocates directly since vars are in scope (module scope of test file). But wait: extracted sections skip the THREE scene part. Extract ranges:

1. From const SPAN = 15; to end of DOM helpers section (before /* ==== Three.js scene)? DOM helpers use document — stub document.getElementById to return {textContent:''}... $('status') used at module top-level? const statusEl = $('status') → needs document stub returning objects with textContent. Easy stub.
2. Skip scene/buildGrid.
3. From /* Sandpile core banner start (the comment block "================================================================ Sandpile core — the Abelian toppling rules") through end of finishAvalanche.

Simpler: python script to slice by marker strings and concatenate, then append driver. Driver:

Wait T5: 3×3, center cell index 4. Add 4 grains → topples once: center 0, each neighbor +1 (cells 1,3,5,7 = edges mid) → all ≤3, done. Lost = 0 (no rim crossing from center). Corners 0. So expected h = [0,1,0,1,0,1,0,1,0], lost 0. Conservation: 4 grains = sum 4 + lost 0. OK fix expectation.

Also test with one more set: 3×3 add 16 grains to center... eh, T5 suffices.

Note in driver: state.totalGrains etc must be reset between tests — resetStats not extracted... resetStats is in UI wiring section — not extracted. Driver manually resets state fields. Let me just re-alloc and zero counters manually: state.totalGrains=0; etc. And histBins.fill(0).

Also finishAvalanche uses state.totalAval, logs when s>=15000 → audio.boom stub.

Also stub: document with getElementById returning {textContent:''}; log is defined in extracted block? Yes — log function is in DOM helpers (extracted). It uses document.createElement and $('log')... log builds DOM elements — stub document.createElement returning {innerHTML:'',classList:{add(){}},remove(){}} and getElementById('log') returning {prepend(){},children:{length:0},lastChild:{remove(){}}}. Simpler: override log AFTER extraction in driver? log is a function declaration → hoisted, can be reassigned? Function declarations create mutable bindings, so log = ()=>{}? In module scope... test file will be a .mjs module; reassignment of function declaration binding is allowed (it's like var). But setTimeout calls inside log — fine, skip by overriding. Actually simpler: stub document well enough. Let me just stub:

log does list.prepend(li); while (list.children.length > 6) ... — children.length 0 → fine. setTimeout(... ) — real setTimeout fine (callbacks touch li.classList — stubbed).

audio stub: const audio = {boom(){}, pluck(){}, hiss(){}, on:false}; — but audio is declared later in the demo file as const audio = {...} — NOT in extracted range → my driver defines its own audio... conflict? Extracted range references audio (finishAvalanche calls audio.boom) — audio must exist. If driver declares const audio = ... at top before extracted code — wait order: driver prelude stubs first, then extracted code, then tests. audio const declared in prelude → fine (finishAvalanche not called until tests run).

But statusEl/readoutsEl const assigned at module init via $ → stubbed document OK.

Extraction ranges — find with python by markers:

• A: from "const SPAN = 15;" to right before "/* ================================================================\n Three.js scene"
• B: from "/* ================================================================\n Sandpile core" to right before "/* ================================================================\n Emitters"

Check B includes syncAttrs (references gridGeo → declared in A as let gridMesh=null, gridGeo=null, gridMat=null; — yes A includes that declaration line ("sim arrays" section includes gridMesh decl? Let me check: the block "/* sim arrays (rebuilt on grid-size change) */ let h, inQ, queue, qHead, qTail, qLen, mark, aHraw, aTraw; let gridMesh = null, gridGeo = null, gridMat = null; let needSync = false;" — yes in A. Good — syncAttrs never invoked in tests anyway.

finishAvalanche → B. log/audio/$ → stubs/A.

Write the python extraction + driver, run node.

All core tests pass:

• T0: exact 3×3 toppling correct.
• T1: grain conservation exact (400000 = 145694 + 254306), stable (max 3), 1.6 BILLION topples processed at 46M/s — the sim is fast. Note: 400k center drops took 35s in test — but that's because I drain fully per drop (proper BTW separation). In the demo, per-frame budget 30k with 8 drops/frame → reaches the same state but spread over wall-clock time; the mandala grows gradually — that's the intended experience. 46M topples/s means the 120k budget uses ~3ms worst case — good.
• T2: full-house quake 357k topples terminates stable.
• T3: queue stress OK.
• T4: histogram works (only 1 bin because T3's last drain... wait, histBins was reset in T5? No — T4 runs before T5. alloc(160) in T3 reset histBins; T3's drops → each drain batch... hmm "total binned 1" means only 1 avalanche was finalized in T3 — because drops keep the queue non-empty and merging into one giant avalanche. That's expected behavior with continuous driving. In rain mode at low rate, avalanches separate more often. Hmm — this is a concern for the histogram statistics: with drain-per-drop in real BTW you get one avalanche per grain. In the demo, drops happen per frame and avalanches merge across frames when the queue never drains... With rate 8 and budget 30k, most frames: 8 grains added, queue processed to empty within the frame → avalanches finalize almost every frame → good statistics. During big cascades, merging happens — that's fine and physical enough (it's a "cascade").
• T5: batched multi-frame processing works, terminates stable.

Also note: 1.6B topples for 400k center drops — wow, that's the nature of center-driven piles. In demo terms: at 30k topples/frame × 60fps = 1.8M topples/sec wall clock. The mandala pattern emerges within the first ~50-150k grains.

One performance consideration: syncAttrs full scan of 65k each frame — trivial.

Now update the index.html with the new demo card. Then final syntax check of whole HTML (already done node --check on extracted module — passed before my edits? No wait — node --check ran BEFORE the replace edits. The edits were small, but re-extract and re-check to be safe. Then update index.html.

Card description text (entities escaped properly). Insert after <!-- New demos are added here -->.

Syntax is clean. Now a couple of final quality checks on the demo before updating the index:

1. Check the emitDrops "center" jitter line once more: x = (G >> 1) + (Math.random() * 3 - 1.5) | 0; — precedence: | lower than + → ((G>>1) + (rand*3-1.5)) | 0 → truncation toward zero; value large positive → floor. Range: rand*3-1.5 ∈ [-1.5, 1.5) → x ∈ [G/2-1.5, G/2+1.5) → truncated → {G/2-1, G/2, G/2+1} roughly. Fine.

2. The hist canvas is 540×140 but CSS height 70px (aspect 2:1 letterbox — canvas 540/140 = 3.857 ratio; CSS width 100% of ~270px panel → 270px wide, 70px tall = 3.857 ratio. matches, no distortion).

3. $('tauNote') referenced inside drawHist before drawHist is first called at init — element exists in DOM. Fine.

4. In animate, gridMat.uniforms... — gridMat set by buildGrid called before animate. Fine.

5. updateStream uses h — set. Fine.

6. beams geometry shared between two meshes — fine, disposed never (static).

7. stageLine rebuilt on grid change — actually stage size is SPAN/2 regardless of grid... buildStage doesn't depend on G. It's constant; calling on rebuild harmless.

8. One more consideration — controls.enabled = !v in setDrawMode: if user toggles drawMode while painting... painting false at that point (pointerup). OK.

9. iOS: maximum-scale=1.0, user-scalable=no present. touch-action none on canvas. Good.

10. The hint says "press D to draw". Good.

11. Quake threshold 15000 with M = log10(s)-1.8: full-house 256² quake could topple ~2M+ → M≈4.5 → shake 0.06+0.34=0.4 — noticeable but capped 0.55. Good.

12. Camera shake applied around composer.render() — controls.update() before, restore after. Good.

13. readouts dissipated % — totalLost/(totalGrains+totalLost)... hmm totalLost counts boundary losses during topples; totalGrains counts added grains. Every added grain eventually ends in pile or lost: grains = sum(h) + lost. Dissipated % = lost/(grains) conceptually = lost/(sum+lost)... I wrote totalGrains+totalLost as denominator — wrong: totalGrains already includes all grains ever added (some now in pile, some lost). So dissipated fraction = totalLost/totalGrains. Fix: 100 * state.totalLost / state.totalGrains. Let me fix that small bug.

14. In T1 test: grains 400000, lost 254306 → dissipated = 63.6%. With my formula it'd show 254306/654306 = 38.9% — wrong. Fix to lost/grains.

Let me apply that one fix, then update the index page, then do a final HTML sanity pass (check all $('...') ids exist).

******************************************************************************************************************************************************ML.

The python heredoc wrote /tmp/sp/index_new.html (with the card inserted right after <div class="demo-list">, BEFORE the <!-- New demos are added here --> comment — hmm, wait: my replace inserted the card immediately after <div class="demo-list">\n, which puts the card BEFORE the "New demos are added here" comment line. Looking at the printed output of the ORIGINAL index.html (it printed the whole file because of my stray cat /space/d... garbage at the end which failed but the file dump shown was from... wait, the output shows the original index.html content — that came from cat /space/demos && python3...? No. Actually the stdout shows the whole ORIGINAL index.html — because... hmm, my command was:

Oops — I accidentally left stray text after the heredoc: cat /space/d, and update index.html... — that was a mistake in my command construction (leftover sentence). The cat failed with errors (stderr shows). But the python part ran and wrote /tmp/sp/index_new.html. The big stdout dump — where did it come from? Possibly cat /space/d... no. Actually the first part of output: vRate vSpeed... from the first greps, then the giant HTML dump. That dump is probably from cat /space/demos?? cat on a directory gives error... Hmm, "cat: /space/d," — the stray text got split by commas? It seems the shell interpreted cat /space/d, and update... as cat with multiple args: /space/d, /space/and... wait no, commas attach: args were "/space/d," "and" "update" ... So cat printed nothing. Then where's the HTML dump from? Perhaps from python printing? No, python only printed "written".

Oh! I see — the stray text line was executed as a shell command line: cat /space/d, and update index.html with the new card. Let me just do the python edit directly on the real file. — args: /space/d, and, update, index.html, with, the, new, card., ... "index.html" WAS one of the args! So cat printed /space/demos/index.html (cwd was /space/demos). That's the dump — the ORIGINAL index (no 038 card since we wrote to /tmp/sp/index_new.html). OK mystery solved, no harm done. The real index.html is untouched.

Now verify /tmp/sp/index_new.html contains the card, then copy it over. Let me check insertion location: I inserted right after <div class="demo-list">\n, so order in file: <div class="demo-list">, then my card, then <!-- New demos are added here -->, then 037 card. The convention is new demos right after the comment marker. My card lands BEFORE the comment — functionally fine (renders at top), but let me place it after the comment to match convention. Let me redo: replace the marker line with marker + card.

Also my card text — review it for accuracy: "a fourth grain topples, and the resulting avalanche cascades in self-organized formation of the famous abelian sandpile fractal." — this sentence is a bit garbled ("cascades in self-organized formation"). Let me rewrite the card description more carefully:

"The archetype of self-organized criticality, live in 3D — a Bak–Tang–Wiesenfeld Abelian sandpile on up to 384² glowing cells: each cell holds 0–3 grains, a fourth grain topples it and hands one grain to each neighbour, and the avalanche races across the pile as a white-hot wavefront. Pour everything onto the origin and grow the famous fractal mandala patch by patch; switch to rain, twin-spring or a slowly turning ring drive; seed a "full house" of 3s and trigger a continental cascade; or press D and draw rivers of sand with your own brush. Every cascade is logged — the live log–log histogram stacks avalanche sizes against a fitted power law P(s) ∝ s^−τ, the same statistics as earthquakes, forest fires and market crashes — while big cascades register as magnitude-M quakes with camera shake and a sub-bass boom, and sand hiss plus pentatonic plucks sonify the wavefronts. Featuring instanced-box GPU rendering with per-cell glow timestamps, an adaptive sim budget up to 120k topples/frame (46M/s measured), emitter beams with falling-sand particle streams, generative WebAudio, UnrealBloom plus vignette/grain/chromatic grade, three grid sizes, adaptive quality tiers, PNG snapshots, keyboard shortcuts and full touch support."

Use proper HTML entities: —, ², –, “, ”, ∝, −, τ... keep style consistent.

Write directly to /space/demos/index.html with python. Also fix "UnrealBloom" spelling (I wrote "Unreal bloom" in the draft above; use UnrealBloom).

Then final verify: grep 038 in index, verify card structure, and validate the demo HTML one more time (full file lint via node --check already done). Also quickly sanity check the demo file for the id references (the earlier grep output listed vRate vSpeed vBrush vHeight cSound as "suspicious" because my grep filter was flawed — those ids DO exist: vRate etc are in the HTML. Fine.)

Also I should double check $('grids') — used via querySelectorAll('#grids .pbtn') not $ — fine. $('emitters') via querySelectorAll too. All ids referenced via $ exist: status, readouts, log, btnPlay, btnSound, btnSpin, btnSnap, btnHelp, help, helpCard, btnFull, btnClear, btnDraw, sRate, vRate, sSpeed, vSpeed, sBrush, vBrush, sHeight, vHeight, cSound, cSpin, cBloom, hist, tauNote, hint, app. Let me verify each exists in HTML with a quick script.

Index updated, all DOM ids resolve. Now final checks:

1. Re-run node --check on the final demo file (post-edits) — I did check demo2.mjs after the replace edits? The replaces happened BEFORE the demo2.mjs extraction? Let me trace: I made replaces (qLen, syncAttrs, tLo/tHi, pointer handlers, animate loop) — then extracted demo.mjs and node --check passed. Wait no: demo.mjs was extracted AFTER all those replaces (the extraction ran after the edits — sequence: wrote file → 7 replaces → extracted demo.mjs → node --check OK). Then I made ONE more edit (dissipated % fix) → then extracted demo2.mjs? No — demo2.mjs extraction happened BEFORE the dissipated fix? Sequence check:

   • replaces (qLen etc.)
   • extract demo.mjs, node --check OK
   • import three fail, curl OK, checks
   • extract demo2.mjs + node --check OK ← this was after all replaces
   • dissipated % fix (1 replace)
   • this last command verified ids + updated index.

   The dissipated-% edit is trivial (single expression swap), but re-check syntax to be thorough.

2. Also final visual review of a few areas of the final HTML to catch anything odd: the animate loop section and header. Let me re-extract and node --check once more, plus grep a couple of spots.

3. Check the title/description in demo header vs card — fine.

Then finish with _success. Let me also do a last review of risky shader code — one concern: in the vertex shader I use uniform int uG; and gl_InstanceID / uG. three.js GLSL3 conversion — ShaderMaterial default glslVersion is null → three auto-converts: prepends version 300 es and defines. Integer division with uniform int OK. float(uG) OK.

One more potential issue: gridGeo.instanceCount = CAP; — property name correct for InstancedBufferGeometry in r170? In r170, InstancedBufferGeometry has instanceCount = Infinity. Renderer: const instanceCount = Math.min( geometry.instanceCount, geometry._maxInstanceCount ); — yes correct.

Mesh + InstancedBufferGeometry: renderer treats geometry.isInstancedBufferGeometry → renderInstances. Works with plain Mesh. Good.

Frustum culled false set. Good.

Also gridGeo.index = box.index; — InstancedBufferGeometry accepts index. Good.

Potential issue: box.attributes.uv not copied — shader doesn't use uv. Good.

The aH/aT attributes: new THREE.InstancedBufferAttribute(aHraw, 1) — itemSize 1, float. In shader attribute float aH; OK.

Edge: syncAttrs calls gridGeo.getAttribute('aH') — exists.

attr.addUpdateRange guarded. Good.

One concern about updateRanges semantics: ranges are in "array element" units? From the source: gl.bufferSubData(bufferType, range.start * array.BYTES_PER_ELEMENT, array, range.start, range.count) — so start/count are in ELEMENTS of the typed array (floats), not components. My attributes itemSize=1 → element index = cell index. Correct.

For the bufferSubData(array, range.start, range.count) overload — that's WebGL2's (dstByteOffset, srcOffset, length) form. Correct.

Now — one more thing to double check in the demo: initial render before any drops: aH all 0, boxes scale uBase=0.05 — flat navy mosaic. uTime starts 0, aT=-1000 → glow 0. Good.

Beams: cylinder height 6.5, position y=3.25 → spans 0..6.5. Good.

stream points initial opacity 0 → invisible until playing & rate>0 (playing true, rate 8, mode center → flakes near center beam). Good.

Audio not started until toggle. Good.

Snapshot uses composer.render() then toDataURL — canvas has preserveDrawingBuffer false, but toDataURL right after synchronous render works (same task). Good — house style does exactly this.

What about state.fps = 1000 / Math.max(emaDt, 0.01) — emaDt ms. Good.

histTimer > 0.5 && histChanged — histChanged set false after draw; finishAvalanche sets true. Initial drawHist() at boot shows empty axes. Good.

Everything looks consistent. Final: re-extract + node --check the very final file, then done. Also list the demos dir to confirm folder placement.

Everything checks out:

• Demo 038-sandpile created at /space/demos/038-sandpile/index.html (52.5KB, self-contained).
• Syntax valid ES module.
• Core physics unit-tested in Node: conservation, stability, queue integrity, batched processing, histogram.
• Index updated: 43 demo-card references (37 old cards + 1 new = 38 cards; count 43 because "demo-card" appears in CSS selectors too — .demo-card appears in CSS: .demo-card, .demo-card:hover, .demo-card .num, .demo-card h2, .demo-card p = 5 CSS mentions + 38 cards = 43. Checks out exactly.)

Task complete. Call _success.