@vibes.diy/prompts 14.3.83 → 14.3.85

package/llms/worlds.md

@@ -0,0 +1,826 @@
+# Generative worlds — living simulations on a canvas
+
+When someone asks for an ecosystem, a terrarium, an ant farm, a meadow with
+rabbits and foxes, Conway's Game of Life, a cellular automaton, falling sand,
+a forest fire, a flock of boids, a petri dish, weather drifting over a map, or
+any screen where a small world runs by its own rules and the fun is watching
+it go, this is the recipe. The browser's own canvas is the whole engine: a
+grid of cells in a typed array, two functions that seed and step it, a seeded
+random generator so the same world grows on every device, a loop on its own
+clock, and the grid painted as pixels. Fireproof keeps a world as its recipe
+(seed, dials, tick, and any taps a person made), so a saved world is a few
+bytes and a card in a gallery is that world, alive, at the moment it was kept.
+
+The sibling boundary: a sketch that draws (flow fields, kaleidoscopes, a
+drawing toy) is `p5`; bodies with mass that collide are `physics`; a block
+world with depth is `voxel`. Worlds is the right call when the fun is a
+population of simple things following simple rules over time.
+
+The worked examples below were built and measured for this doc (Chromium,
+2026-10-07): a meadow whose dials a person turns and whose moments they keep,
+and a falling-sand box whose brush strokes replay.
+
+## Project shape
+
+```
+App.jsx          the interface: the stage, play / pause / step / speed, dials, keep, a gallery
+lib/world.js     the engine: seeded random, double-buffered grid, pixel paint, the tick loop, recipes
+lib/rules.js     the world's rules: seed(world) and step(world, from, to), plus a census
+access.js        who may keep a world in the shared gallery
+```
+
+The engine is the same for every world; the rules are the part a request
+changes. A second kind of world (sand, life, fire) is a second rules module
+imported into the same `createWorld`.
+
+## The engine — `lib/world.js`
+
+### `lib/world.js`
+```js app=meadow
+// lib/world.js — a seeded, fixed-tick grid world painted as pixels.
+// Every random number comes from one seeded generator, the tick counter has one owner, the grid
+// is double-buffered and painted through ImageData onto a small offscreen canvas that is drawn
+// scaled (no smoothing) onto the visible one, and the loop runs on its own clock.
+
+/** A tiny seeded PRNG (mulberry32): the same seed gives the same sequence on every device. */
+export function seededRandom(seed) {
+  let a = seed >>> 0;
+  return function random() {
+    a = (a + 0x6d2b79f5) >>> 0;
+    let t = a;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/** Resolve an injected theme token to a concrete colour once per mount (the p5 doc's probe). */
+export function cssColor(host, token, fallback) {
+  const probe = document.createElement("span");
+  probe.style.display = "none";
+  probe.style.color = `var(${token}, ${fallback})`;
+  host.appendChild(probe);
+  const value = getComputedStyle(probe).color;
+  probe.remove();
+  return value;
+}
+
+/**
+ * Any CSS colour → [r, g, b] for ImageData. A canvas fill does the conversion, so a token that
+ * computes to `oklch(…)`, `color-mix(…)` or `rgb(50% …)` (measured: a computed style reports an
+ * oklch token verbatim) lands as bytes rather than being read as three numbers.
+ */
+export function rgb(color) {
+  const probe = document.createElement("canvas").getContext("2d");
+  probe.fillStyle = color;
+  probe.fillRect(0, 0, 1, 1);
+  const [r, g, b] = probe.getImageData(0, 0, 1, 1).data;
+  return [r, g, b];
+}
+
+/**
+ * createWorld(canvas, { cols, rows, seed, rules, palette, ticksPerSecond })
+ *
+ * `rules` is { seed(world) , step(world, from, to) }: `seed` fills `world.cells` once from the
+ * seeded generator; `step` reads `from` and writes `to` (the two buffers swap each tick). Both use
+ * `world.random()` for every random number. `palette` maps a cell value to [r, g, b].
+ */
+export function createWorld(canvas, { cols, rows, seed = 1, rules, palette, ticksPerSecond = 30 }) {
+  const dpr = Math.min(window.devicePixelRatio || 1, 2);
+  const ctx = canvas.getContext("2d");
+  const offscreen = document.createElement("canvas");
+  offscreen.width = cols;
+  offscreen.height = rows;
+  const octx = offscreen.getContext("2d");
+  const image = octx.createImageData(cols, rows);
+
+  const world = {
+    cols,
+    rows,
+    seed,
+    tick: 0,
+    cells: new Uint8Array(cols * rows),
+    next: new Uint8Array(cols * rows),
+    random: seededRandom(seed),
+    ticksPerSecond,
+    running: false,
+    events: [],
+    applied: 0, // how many of `events` have landed on the grid (live or replayed)
+    raf: 0,
+    owed: 0,
+    last: 0,
+    listeners: new Set(),
+  };
+
+  function resize() {
+    const w = canvas.clientWidth || cols;
+    const h = canvas.clientHeight || rows;
+    canvas.width = Math.round(w * dpr);
+    canvas.height = Math.round(h * dpr);
+  }
+
+  world.paint = () => {
+    const data = image.data;
+    const cells = world.cells;
+    for (let i = 0, p = 0; i < cells.length; i += 1, p += 4) {
+      const c = palette[cells[i]] || palette[0];
+      data[p] = c[0];
+      data[p + 1] = c[1];
+      data[p + 2] = c[2];
+      data[p + 3] = 255;
+    }
+    octx.putImageData(image, 0, 0);
+    ctx.imageSmoothingEnabled = false;
+    ctx.drawImage(offscreen, 0, 0, canvas.width, canvas.height);
+  };
+
+  /** Land every recorded event up to the current tick that has not landed yet (a replay's). */
+  function applyDue() {
+    while (world.applied < world.events.length && world.events[world.applied].tick <= world.tick) {
+      rules.apply?.(world, world.events[world.applied]);
+      world.applied += 1;
+    }
+  }
+
+  /** The one place the tick advances: land this tick's events that are still due, then the rules. */
+  world.step = () => {
+    applyDue();
+    rules.step(world, world.cells, world.next);
+    const swap = world.cells;
+    world.cells = world.next;
+    world.next = swap;
+    world.tick += 1;
+    for (const fn of world.listeners) fn(world);
+  };
+
+  /** Record an input against the current tick and land it now; the cursor keeps step() from landing it twice. */
+  world.record = (event) => {
+    const stamped = { ...event, tick: world.tick };
+    world.events.push(stamped);
+    rules.apply?.(world, stamped);
+    world.applied = world.events.length;
+    world.paint();
+  };
+
+  world.frame = () => {
+    if (!world.running) return;
+    // performance.now(), not the frame's timestamp: the two clocks can disagree by whole seconds
+    // in some browsers, and a negative delta would stall the loop.
+    const now = performance.now();
+    const tickMs = 1000 / world.ticksPerSecond;
+    world.owed += Math.max(0, Math.min(now - world.last, 4 * tickMs));
+    world.last = now;
+    let stepped = false;
+    while (world.owed >= tickMs) {
+      world.step();
+      world.owed -= tickMs;
+      stepped = true;
+    }
+    if (stepped) world.paint();
+    world.raf = requestAnimationFrame(world.frame);
+  };
+
+  world.start = () => {
+    if (world.running) return;
+    world.running = true;
+    world.last = performance.now();
+    world.owed = 0;
+    world.raf = requestAnimationFrame(world.frame);
+  };
+  world.stop = () => {
+    world.running = false;
+    cancelAnimationFrame(world.raf);
+  };
+  world.stepOnce = () => {
+    world.step();
+    world.paint();
+  };
+  world.setSpeed = (tps) => {
+    world.ticksPerSecond = tps;
+  };
+  world.onTick = (fn) => {
+    world.listeners.add(fn);
+    return () => world.listeners.delete(fn);
+  };
+
+  /** Back to tick 0 with the same seed (or a new one): the next run replays exactly. */
+  world.reset = (nextSeed = world.seed, events = []) => {
+    world.seed = nextSeed;
+    world.random = seededRandom(nextSeed);
+    world.tick = 0;
+    world.cells.fill(0);
+    world.next.fill(0);
+    world.events = events.slice();
+    world.applied = 0;
+    rules.seed(world);
+    world.paint();
+  };
+
+  /** Run from a recipe to a tick without drawing in between; the paint at the end is the card. */
+  world.replay = ({ seed: s, tick, events = [] }) => {
+    world.reset(s, events);
+    while (world.tick < tick) world.step();
+    applyDue(); // inputs recorded at the kept tick itself, after its last step
+    world.paint();
+  };
+
+  world.recipe = () => ({ seed: world.seed, tick: world.tick, events: world.events.slice() });
+
+  world.dispose = () => {
+    world.stop();
+    world.listeners.clear();
+  };
+
+  resize();
+  world.reset(seed);
+  return world;
+}
+
+/** Cell index helpers with wrap-around edges. */
+export function at(world, x, y) {
+  const { cols, rows } = world;
+  return (((y % rows) + rows) % rows) * cols + (((x % cols) + cols) % cols);
+}
+```
+
+## Rules are two functions — `lib/rules.js`
+
+A world's rules are `seed(world)`, which fills the first grid, and
+`step(world, from, to)`, which reads one buffer and writes the other. The
+engine swaps the buffers and counts the tick. Writing into `to` while reading
+`from` is what makes a step order-independent: every cell sees the same
+previous world. (The meadow below reads `to` for neighbours on purpose, so a
+cell a rabbit already moved into this tick counts as taken; that is the
+rule's choice, and the seed makes it reproducible either way.)
+
+### `lib/rules.js`
+```js app=meadow
+// lib/rules.js — a meadow: grass grows back, rabbits graze and breed, foxes hunt and starve.
+// Rules are two functions over the grid. Every random number comes from `world.random()`, so the
+// same seed grows the same meadow on every device and a saved tick replays exactly.
+import { at } from "./world.js";
+
+export const EMPTY = 0;
+export const GRASS = 1;
+export const RABBIT = 2;
+export const FOX = 3;
+
+/** The dials a person can turn; each is a probability per cell per tick. */
+export const DEFAULT_PARAMS = { regrow: 0.03, rabbitBreed: 0.15, rabbitDie: 0.03, foxBreed: 0.6, foxStarve: 0.01 };
+
+export function meadowRules(params = DEFAULT_PARAMS) {
+  const P = { ...DEFAULT_PARAMS, ...params };
+  return {
+    /** The first tick's world: half grass, a few rabbits, fewer foxes. */
+    seed(world) {
+      const cells = world.cells;
+      for (let i = 0; i < cells.length; i += 1) {
+        const r = world.random();
+        cells[i] = r < 0.5 ? GRASS : r < 0.56 ? RABBIT : r < 0.58 ? FOX : EMPTY;
+      }
+    },
+    /** Read `from`, write `to`; the engine swaps them after. */
+    step(world, from, to) {
+      to.set(from);
+      for (let y = 0; y < world.rows; y += 1) {
+        for (let x = 0; x < world.cols; x += 1) {
+          const i = y * world.cols + x;
+          const c = from[i];
+          if (c === EMPTY) {
+            if (world.random() < P.regrow) to[i] = GRASS;
+            continue;
+          }
+          if (c === GRASS) continue;
+          const dx = Math.floor(world.random() * 3) - 1;
+          const dy = Math.floor(world.random() * 3) - 1;
+          const j = at(world, x + dx, y + dy);
+          const n = to[j];
+          if (c === RABBIT) {
+            if (n === GRASS) {
+              to[j] = RABBIT;
+              to[i] = world.random() < P.rabbitBreed ? RABBIT : EMPTY;
+            } else if (n === EMPTY) {
+              to[j] = RABBIT;
+              to[i] = EMPTY;
+            }
+            if (world.random() < P.rabbitDie) to[i] = EMPTY;
+          } else if (c === FOX) {
+            if (n === RABBIT) {
+              to[j] = FOX;
+              to[i] = world.random() < P.foxBreed ? FOX : EMPTY;
+            } else if (n === EMPTY || n === GRASS) {
+              to[j] = FOX;
+              to[i] = n;
+              if (world.random() < P.foxStarve) to[j] = n;
+            }
+          }
+        }
+      }
+    },
+  };
+}
+
+/** How many of each kind are alive — read on a slow clock, every few ticks. */
+export function census(world) {
+  const counts = [0, 0, 0, 0];
+  for (const c of world.cells) counts[c] += 1;
+  return { grass: counts[GRASS], rabbits: counts[RABBIT], foxes: counts[FOX] };
+}
+```
+
+Measured with these dials (160 × 100 cells, seed 11): grass, rabbits and
+foxes all alive at tick 2000, with foxes between about 300 and 500 the whole
+way. Dials that let one species win in the first few hundred ticks are the
+common first draft; the fix is a lower breed rate for the prey and a lower
+starve rate for the predator, then watch the census for a thousand ticks.
+
+## The interface — a meadow with dials, a keep button and a living gallery
+
+### `App.jsx`
+```jsx app=meadow
+import React, { useEffect, useMemo, useRef, useState } from "react";
+import { useFireproof } from "use-fireproof";
+import { useVibe, useViewer } from "use-vibes";
+import { Badge, Button, Card, Field, Heading, Input, Row, Skeleton, Spacer, Stack, Text } from "@vibes.diy/pouf";
+import { Slider } from "@vibes.diy/pouf/interactive";
+import { createWorld, cssColor, rgb } from "./lib/world.js";
+import { DEFAULT_PARAMS, census, meadowRules } from "./lib/rules.js";
+
+const COLS = 160;
+const ROWS = 90;
+
+/** One palette per mount, from the app's theme tokens: the owner's restyle reaches the meadow. */
+function makePalette(host) {
+  return [
+    rgb(cssColor(host, "--background", "#141618")),
+    rgb(cssColor(host, "--primary", "#3c8c46")),
+    rgb(cssColor(host, "--foreground", "#e6dcc8")),
+    rgb(cssColor(host, "--accent", "#dc6e32")),
+  ];
+}
+
+/** A gallery card: a tiny canvas that replays the kept world to its tick, once. */
+function WorldCard({ doc, onOpen }) {
+  const ref = useRef(null);
+  useEffect(() => {
+    const canvas = ref.current;
+    const world = createWorld(canvas, { cols: COLS, rows: ROWS, seed: doc.seed, rules: meadowRules(doc.params), palette: makePalette(canvas) });
+    world.replay({ seed: doc.seed, tick: doc.tick });
+    return () => world.dispose();
+  }, [doc.seed, doc.tick, doc.params]);
+  return (
+    <Card variant="tight">
+      <Stack gap={2}>
+        <canvas ref={ref} className="block w-full aspect-video rounded" />
+        <Row gap={2} align="center" wrap>
+          <Text size="sm">{doc.name}</Text>
+          <Spacer />
+          <Button size="sm" variant="quiet" onClick={() => onOpen(doc)}>Open</Button>
+        </Row>
+      </Stack>
+    </Card>
+  );
+}
+
+export default function App() {
+  const { database, useLiveQuery } = useFireproof("meadows");
+  const { me, can, ready } = useVibe("meadows");
+  const { requestLogin, ViewerTag } = useViewer();
+  const { docs } = useLiveQuery("type", { key: "world" });
+  const kept = useMemo(() => [...docs].sort((a, b) => (b.createdAt ?? 0) - (a.createdAt ?? 0)), [docs]);
+
+  const [seed, setSeed] = useState(11);
+  const [params, setParams] = useState(DEFAULT_PARAMS);
+  const [running, setRunning] = useState(true);
+  const [speed, setSpeed] = useState(30);
+  const [counts, setCounts] = useState({ grass: 0, rabbits: 0, foxes: 0 });
+  const [tick, setTick] = useState(0);
+  const [name, setName] = useState("");
+
+  const canvasRef = useRef(null);
+  const worldRef = useRef(null);
+  const openRef = useRef(null); // a kept moment to replay once the next world exists
+  const [opened, setOpened] = useState(0); // bumps on every Open, so the effect runs even when seed and dials match
+
+  // The world lives in a ref: created once per seed and dials, stopped in the effect's cleanup.
+  useEffect(() => {
+    const canvas = canvasRef.current;
+    const world = createWorld(canvas, { cols: COLS, rows: ROWS, seed, rules: meadowRules(params), palette: makePalette(canvas), ticksPerSecond: speed });
+    worldRef.current = world;
+    if (openRef.current) {
+      world.replay(openRef.current);
+      openRef.current = null;
+    }
+    // One reading right away, so a paused or replayed world shows its own numbers.
+    setCounts(census(world));
+    setTick(world.tick);
+    // React state updates happen on a slow clock: a census every 15 ticks, not every tick.
+    const off = world.onTick((w) => {
+      if (w.tick % 15 === 0) {
+        setCounts(census(w));
+        setTick(w.tick);
+      }
+    });
+    if (running) world.start();
+    return () => {
+      off();
+      world.dispose();
+      worldRef.current = null;
+    };
+  }, [seed, params, opened]);
+
+  useEffect(() => {
+    const world = worldRef.current;
+    if (!world) return;
+    world.setSpeed(speed);
+    if (running) world.start();
+    else world.stop();
+  }, [running, speed]);
+
+  function open(doc) {
+    openRef.current = { seed: doc.seed, tick: doc.tick };
+    setParams(doc.params);
+    setSeed(doc.seed);
+    setRunning(false);
+    setOpened((n) => n + 1);
+  }
+
+  const draft = { type: "world", name: name || "a meadow", seed, params, tick, creatorHandle: me?.userHandle };
+  const canKeep = Boolean(ready && me && can.create(draft).ok);
+
+  async function keep() {
+    const world = worldRef.current;
+    if (!world || !canKeep) return;
+    await database.put({ ...draft, _id: crypto.randomUUID(), tick: world.tick, createdAt: Date.now() });
+    setName("");
+  }
+
+  const dial = (key, label, max) => (
+    <Stack key={key} gap={1}>
+      <Text size="sm">{label}</Text>
+      <Slider label={label} min={0} max={max} step={max / 100} value={[params[key]]} onChange={([v]) => setParams({ ...params, [key]: v })} />
+    </Stack>
+  );
+
+  return (
+    <main className="min-h-screen bg-background text-foreground p-4 md:p-8">
+      <Stack gap={4}>
+        <Row gap={2} align="center" wrap>
+          <Heading level={1}>Meadow</Heading>
+          <Spacer />
+          <Badge tone="up">{counts.rabbits} rabbits</Badge>
+          <Badge tone="info">{counts.foxes} foxes</Badge>
+          <Badge>tick {tick}</Badge>
+        </Row>
+
+        <Card variant="flush">
+          <canvas ref={canvasRef} className="block w-full aspect-video touch-none" />
+        </Card>
+
+        <Row gap={2} align="center" wrap>
+          <Button onClick={() => setRunning((r) => !r)}>{running ? "Pause" : "Play"}</Button>
+          <Button variant="quiet" onClick={() => { setRunning(false); worldRef.current?.stepOnce(); }}>Step</Button>
+          <Button variant="quiet" onClick={() => setSeed(Math.floor(Math.random() * 1e9))}>New meadow</Button>
+          <Stack gap={1}>
+            <Text size="sm">Speed</Text>
+            <Slider label="Ticks per second" min={1} max={120} value={[speed]} onChange={([v]) => setSpeed(v)} />
+          </Stack>
+        </Row>
+
+        <Card variant="tight">
+          <Stack gap={2}>
+            <Heading level={2}>Dials</Heading>
+            <Text size="sm" muted>Each dial is a chance per cell per tick. Turning one restarts the meadow from the same seed.</Text>
+            <Row gap={3} wrap>
+              {dial("regrow", "Grass regrows", 0.2)}
+              {dial("rabbitBreed", "Rabbits breed", 1)}
+              {dial("rabbitDie", "Rabbits rest", 0.2)}
+              {dial("foxBreed", "Foxes breed", 1)}
+              {dial("foxStarve", "Foxes wander off", 0.1)}
+            </Row>
+          </Stack>
+        </Card>
+
+        <Card variant="tight">
+          <Stack gap={3}>
+            <Heading level={2}>Kept meadows</Heading>
+            {!ready && <div aria-busy="true"><Skeleton variant="row" /></div>}
+            {ready && !me && <Row gap={2} align="center" wrap><Text muted>Sign in and your meadows stay with you.</Text><Button size="sm" variant="quiet" onClick={requestLogin}>Sign in to keep meadows</Button></Row>}
+            {canKeep && (
+              <Row gap={2} align="top" wrap>
+                <Field label="Name this moment">{(id, d) => <Input id={id} describedBy={d} value={name} onChange={setName} placeholder="the fox spring" />}</Field>
+                <Button size="sm" onClick={keep}>Keep</Button>
+              </Row>
+            )}
+            <div className="grid grid-cols-2 md:grid-cols-3 gap-3">
+              {kept.map((doc) => (
+                <Stack key={doc._id} gap={1}>
+                  <WorldCard doc={doc} onOpen={open} />
+                  <Row gap={2} align="center" wrap>
+                    {doc.creatorHandle && <ViewerTag userHandle={doc.creatorHandle} />}
+                    <Spacer />
+                    {can.delete(doc).ok && <Button size="sm" variant="quiet" tone="down" onClick={() => database.del(doc._id)}>Remove</Button>}
+                  </Row>
+                </Stack>
+              ))}
+            </div>
+          </Stack>
+        </Card>
+      </Stack>
+    </main>
+  );
+}
+```
+
+### `access.js`
+```js app=meadow
+// world: a kept meadow. Its keeper edits and removes it; everyone can open and watch it.
+export function meadows(doc, oldDoc, user, ctx) {
+  if (!user) throw { forbidden: "sign in to keep meadows" };
+  if (doc.type === "world" || (doc._deleted && oldDoc && oldDoc.type === "world")) {
+    const keeper = oldDoc ? oldDoc.creatorHandle : doc.creatorHandle;
+    if (keeper !== user.userHandle) throw { forbidden: "meadows are kept as yourself" };
+    if (oldDoc && !doc._deleted && doc.creatorHandle !== oldDoc.creatorHandle) throw { forbidden: "a meadow keeps its keeper" };
+    return { channels: ["worlds"], grant: { public: ["worlds"] } };
+  }
+  throw { forbidden: "unknown document type" };
+}
+```
+
+## One seeded generator
+
+**Every random number the world uses comes from one seeded generator,
+`world.random()`, so the same seed grows the same world on every device.**
+`seededRandom(seed)` is twenty lines (mulberry32) and the engine owns the one
+instance; the rules call `world.random()` for a neighbour, a coin flip, a
+regrowth roll. Measured: two worlds from seed 7 stepped 500 times hold
+identical cells, and a third world fed the first one's recipe lands on the
+same grid. The interface picks a fresh seed with the browser's own random
+(`Math.floor(Math.random() * 1e9)`) because that number is about to be saved;
+inside the rules, the seeded one is the only source.
+
+## The tick counter has one owner, and ticks run on their own clock
+
+**`world.step()` is the only place `tick` advances, and the frame loop pays
+out whole ticks from the time that has passed, so a world runs at the same
+speed on a 60 Hz laptop and a 120 Hz phone.** The accumulator owes
+`1000 / ticksPerSecond` ms per tick, steps as many times as it owes, caps a
+long absence at four ticks (a background tab resumes rather than fast-forwards),
+and paints once per frame however many ticks ran. Measured: 29 ticks in a
+second at 30, 119 at 120, with the frame rate unchanged. The speed slider
+changes `ticksPerSecond` and nothing else; Step pauses and runs one tick;
+Pause stops the loop and leaves the grid on screen.
+
+The loop reads `performance.now()` rather than the frame's own timestamp:
+the two clocks can disagree by whole seconds in some browsers, and a negative
+delta would stall the loop (measured: the timestamp version ran zero ticks in
+headless Chromium; the `performance.now()` version ran 29).
+
+## Paint the grid as pixels
+
+**Paint the grid as pixels: one `ImageData` the size of the grid, filled from
+the palette, put on a grid-sized offscreen canvas, and drawn scaled onto the
+visible canvas with `imageSmoothingEnabled = false`.** That is one
+`putImageData` and one `drawImage` per frame whatever the grid's size;
+measured, 60 paints of a 160 × 100 grid cost 42 ms in total, and a 240 × 160
+meadow steps in about 2.6 ms. A `fillRect` per cell is tens of thousands of
+calls a frame and is where a world turns into a slideshow. The palette is
+built once per mount from the theme tokens (`cssColor` then `rgb`), so cell
+colours follow the app's theme. For a world drawn as sprites rather than
+cells (boids, ants with heading), paint the agents on top after the grid.
+
+## A saved world is its seed, its parameters and its tick
+
+**A saved world is its seed, its parameters and its tick, and when a person
+tapped the world, the taps as events on the tick line.** The meadow keeps
+`{ type: "world", seed, params, tick, name, creatorHandle }`; a gallery card
+makes a world from the seed and dials and calls `replay({ seed, tick })`,
+which steps to the tick without painting and paints once. The card is the
+kept moment itself, alive, and Open puts the person in it. The sand box below
+keeps `events: [{ tick, x, y, kind }]` as well, so a replay lands the brush at
+the tick it landed. Measured: 31 recorded dabs over 300 ticks replay to an
+identical grid from a different starting seed. A pixel snapshot is the one
+thing a recipe cannot hold; an app that wants the literal image (an export
+button) takes one with `canvas.toBlob` beside the recipe.
+
+## React stays on the slow clock
+
+**React state updates happen on a slow clock: the loop paints the canvas
+itself, and the interface reads a census every fifteen ticks or on demand.**
+A `setState` per tick at 30 ticks a second re-renders the whole page thirty
+times a second for numbers nobody can read that fast. The engine's `onTick`
+listener is where the interface samples the world; the handlers for Play,
+Step and the dials call into the world through the ref; and the dials restart
+the world through the effect's dependency list so a turned dial is a fresh
+run from the same seed.
+
+## Inputs are events on the tick line — a sand box
+
+A world a person can touch keeps what they did as events keyed to the tick,
+and `world.record(event)` lands the input now and remembers it for replay.
+The rules' `apply(world, event)` is the one place an input touches the grid,
+so the live tap and the replayed tap do the same thing, and the engine's
+`applied` cursor is what keeps a tap from landing twice: `record` lands it
+and moves the cursor past it, `step` lands only the events the cursor has
+not reached (a replay's), and `replay` lands the events recorded at the kept
+tick itself before its final paint. Measured with a toggle (an `apply` that
+flips a cell, so a second landing would undo it): the live grid and the
+replayed grid match.
+
+### `lib/sand.js`
+```js app=sand
+// lib/sand.js — falling sand: sand piles, water flows, walls stay. Brush strokes are recorded
+// events on the tick line, so a saved world replays the hand that drew it.
+import { at } from "./world.js";
+
+export const EMPTY = 0;
+export const SAND = 1;
+export const WALL = 2;
+export const WATER = 3;
+
+export const sandRules = {
+  seed() {},
+  /** A recorded brush dab: a 5×5 square of one material at the tick it happened. */
+  apply(world, event) {
+    for (let dy = -2; dy <= 2; dy += 1) {
+      for (let dx = -2; dx <= 2; dx += 1) world.cells[at(world, event.x + dx, event.y + dy)] = event.kind;
+    }
+  },
+  step(world, from, to) {
+    to.set(from);
+    for (let y = world.rows - 2; y >= 0; y -= 1) {
+      for (let x = 0; x < world.cols; x += 1) {
+        const i = y * world.cols + x;
+        const c = from[i];
+        if (c !== SAND && c !== WATER) continue;
+        const below = (y + 1) * world.cols + x;
+        if (to[below] === EMPTY) {
+          to[below] = c;
+          to[i] = EMPTY;
+          continue;
+        }
+        const side = world.random() < 0.5 ? -1 : 1;
+        const diagonal = at(world, x + side, y + 1);
+        if (to[diagonal] === EMPTY) {
+          to[diagonal] = c;
+          to[i] = EMPTY;
+          continue;
+        }
+        if (c === WATER) {
+          const beside = at(world, x + side, y);
+          if (to[beside] === EMPTY) {
+            to[beside] = c;
+            to[i] = EMPTY;
+          }
+        }
+      }
+    }
+  },
+};
+```
+
+### `App.jsx`
+```jsx app=sand
+import React, { useEffect, useRef, useState } from "react";
+import { useFireproof } from "use-fireproof";
+import { useVibe } from "use-vibes";
+import { Button, Card, Heading, Row, Segmented, Spacer, Stack, Text } from "@vibes.diy/pouf";
+import { createWorld, cssColor, rgb } from "./lib/world.js";
+import { SAND, WALL, WATER, sandRules } from "./lib/sand.js";
+
+const COLS = 128;
+const ROWS = 72;
+const MATERIALS = [
+  { value: "sand", label: "Sand" },
+  { value: "water", label: "Water" },
+  { value: "wall", label: "Wall" },
+];
+const KIND = { sand: SAND, water: WATER, wall: WALL };
+
+export default function App() {
+  const { database } = useFireproof("sandbox");
+  const { me, can, ready } = useVibe("sandbox");
+  const canvasRef = useRef(null);
+  const worldRef = useRef(null);
+  const [material, setMaterial] = useState("sand");
+  const [painting, setPainting] = useState(false);
+
+  useEffect(() => {
+    const canvas = canvasRef.current;
+    const palette = [
+      rgb(cssColor(canvas, "--background", "#141618")),
+      rgb(cssColor(canvas, "--accent", "#dcbe78")),
+      rgb(cssColor(canvas, "--muted-foreground", "#5a5a64")),
+      rgb(cssColor(canvas, "--primary", "#4682dc")),
+    ];
+    const world = createWorld(canvas, { cols: COLS, rows: ROWS, seed: 3, rules: sandRules, palette, ticksPerSecond: 60 });
+    worldRef.current = world;
+    world.start();
+    return () => {
+      world.dispose();
+      worldRef.current = null;
+    };
+  }, []);
+
+  // A pointer position in CSS pixels → a cell; the event is recorded against the current tick.
+  function dab(event) {
+    const world = worldRef.current;
+    const canvas = canvasRef.current;
+    if (!world || !canvas) return;
+    const rect = canvas.getBoundingClientRect();
+    const x = Math.floor(((event.clientX - rect.left) / rect.width) * COLS);
+    const y = Math.floor(((event.clientY - rect.top) / rect.height) * ROWS);
+    world.record({ kind: KIND[material], x, y });
+  }
+
+  const draft = { type: "world", seed: 3, creatorHandle: me?.userHandle };
+  const canKeep = Boolean(ready && me && can.create(draft).ok);
+
+  async function keep() {
+    const world = worldRef.current;
+    if (!world || !canKeep) return;
+    const recipe = world.recipe();
+    await database.put({ ...draft, _id: crypto.randomUUID(), tick: recipe.tick, events: recipe.events, createdAt: Date.now() });
+  }
+
+  return (
+    <main className="min-h-screen bg-background text-foreground p-4 md:p-8">
+      <Stack gap={4}>
+        <Row gap={2} align="center" wrap>
+          <Heading level={1}>Sand box</Heading>
+          <Spacer />
+          <Segmented label="Material" value={material} onChange={setMaterial} options={MATERIALS} />
+        </Row>
+        <Text size="sm" muted>Draw on the box. Sand piles, water flows, walls hold.</Text>
+        <Card variant="flush">
+          <canvas
+            ref={canvasRef}
+            className="block w-full aspect-video touch-none"
+            onPointerDown={(e) => { setPainting(true); dab(e); }}
+            onPointerMove={(e) => painting && dab(e)}
+            onPointerUp={() => setPainting(false)}
+            onPointerLeave={() => setPainting(false)}
+          />
+        </Card>
+        <Row gap={2} align="center" wrap>
+          <Button variant="quiet" onClick={() => worldRef.current?.reset()}>Clear</Button>
+          {canKeep && <Button onClick={keep}>Keep this drawing</Button>}
+        </Row>
+      </Stack>
+    </main>
+  );
+}
+```
+
+## Mobile
+
+The stage is the full width of the screen (`w-full` with an aspect ratio),
+`touch-none` keeps a dab from scrolling the page, and the grid is sized by
+cell count rather than by pixels, so a phone paints the same 160 × 90 world
+a laptop does and the cost is the same. Pointer events cover mouse and
+touch together. Play, Pause and Step sit under the stage as large buttons; the
+dials live below, each a labelled slider. Keep `dpr` capped at 2. A world of
+about 20,000 cells at 30 ticks a second is comfortable on a phone; a bigger
+grid earns a lower tick rate rather than a smaller canvas.
+
+## Shapes a world takes
+
+- **An ecosystem or terrarium** — grass, grazers and hunters as cell kinds,
+  dials for the rates, a census, kept moments in a gallery. The starter.
+- **Game of Life and other automata** — `step` counts neighbours in `from`
+  and writes `to`; the seed is a random fill or a named pattern. Add a tap to
+  toggle cells as a recorded event, and a rule picker (B3/S23, HighLife).
+- **Falling sand** — materials as cell kinds, a bottom-up scan, brush dabs as
+  events. The second example.
+- **Forest fire** — trees grow with a small chance, lightning strikes with a
+  smaller one, fire spreads to neighbouring trees and burns out: three kinds
+  and two dials make a world that keeps changing.
+- **Langton's ant and turmites** — one agent with a position and a heading
+  walking a grid that it recolours; the agent's state lives beside the grid on
+  the world object and the step moves it once.
+- **Boids, ants with pheromone trails** — agents on a continuous field in
+  typed arrays (`x`, `y`, `vx`, `vy`), a grid underneath for the trail or the
+  food, painted as the grid then the agents on top. Keep the agent count in
+  the hundreds and the step cheap.
+- **Weather over a map** — a grid of pressure or moisture diffusing each
+  tick, painted through a palette ramp; a map image drawn underneath.
+
+## Gotchas
+
+- **The world runs at a different speed on another device** — the loop
+  steps once per frame. Pay out whole ticks from elapsed time with the
+  accumulator, as `frame` does.
+- **A kept world opens looking different** — a `Math.random()` inside the
+  rules, or a tick counted twice. One generator, one owner.
+- **The loop stalls on some browsers** — the frame's timestamp was read as
+  the clock. Read `performance.now()`.
+- **The page re-renders thirty times a second** — a state setter inside
+  `onTick` with no sampling. Sample every N ticks, or on demand.
+- **A big grid turns into a slideshow** — a `fillRect` per cell. One
+  `ImageData`, one `drawImage`.
+- **Two worlds run after a hot reload or a dial change** — the effect's
+  cleanup is missing `dispose()`. Stop the loop in the effect's cleanup.
+- **A tap lands in the wrong cell** — pointer coordinates were divided by the
+  canvas's pixel size rather than its CSS size. Use the bounding rect.
+- **Cells smear at the edges** — a scaled `drawImage` with smoothing on. Set
+  `imageSmoothingEnabled = false` after every resize (a resize resets it).