Development

Stack

• Frontend — Next.js 16 (App Router, Turbopack), React 19, TypeScript 5, Tailwind v4, Phosphor Icons.
• Simulation runtime — Web Worker tick loop posting world frames as transferable buffers. Pixi.js v8 WebGL field renderer. react-force-graph-3d (Three.js) for the network view. Zustand for state.
• Data — Prisma with SQLite locally; PostgreSQL once accounts land.
• Observers — Mistral API (mistral-small). One call per significant event, dispatched from the browser via app/api/observe.
• Infrastructure — Hetzner VPS (Falkenstein) running Dokploy.

Quick start

Install dependencies (this also runs prisma generate):

Copy the env file. DATABASE_URL is preset; add MISTRAL_API_KEY if you want the observers to narrate:

Create the local SQLite database at prisma/dev.db, then start the dev server:

npm run db:push
npm run dev

.env (not .env.local) is used so the Prisma CLI and Next.js read the same file.

Open http://localhost:3000.

If styles look stale after a config change, clear Turbopack's cache:

Scripts

Architecture

The runtime splits across three layers.

Browser — the engine and the entire UI live here.

• Web Worker runs engine.tick() on an interval driven by the user's speed setting. Each tick produces a WorldFrame posted to the main thread as a set of transferable ArrayBuffers (no structured-clone overhead).
• Main thread rehydrates frames into a WorldView, holds the Zustand store, renders the Pixi WebGL field and the 3D NetworkView, runs the significant-event detector, and shows the inspector and floating windows.

Server — Next.js route handlers.

• /api/observe accepts an event + theorist payload from the browser, builds the per-theorist system + user prompt, calls Mistral, and streams the reading back into the chronicle. It is the only endpoint that costs money per call, so it is rate limited (lib/rate-limit.ts, policy in lib/observe-rate-limit.ts): a per-minute burst rule under a per-hour volume rule, per caller — by user id when signed in, otherwise by IP — plus a deployment-wide hourly ceiling. Over the limit it answers 429 with Retry-After, and the narrator honours it by pausing narration rather than retrying. Limits are env-tunable (OBSERVE_LIMIT_*, see .env.example). Buckets are in-process, so a multi-instance deployment enforces them per instance.

External — Mistral API (mistral-small). One LLM call per significant event, not per tick. Without MISTRAL_API_KEY the simulation still runs; observers stay silent.

The flow on a single significant event:

Web Worker  ─[frames]─▶  Main thread  ─[POST]─▶  /api/observe  ─[prompt]─▶  Mistral
                                                                                │
                          chronicle  ◀──────────────────[reading]───────────────┘

• The engine (lib/engine.ts) is a pure TypeScript class — no React, no DOM. It runs in a Web Worker (app/worker.ts). Every tick it produces a serialisable WorldFrame.
• The worker posts each frame as transferable ArrayBuffers to the main thread, where they're rehydrated into a WorldView (lib/world.ts).
• The store (lib/store.ts, Zustand) holds the latest snapshot, the configuration, the chronicle, the open-window state.
• The Pixi canvas (components/simulation-canvas.tsx) reads the latest WorldView from activeWorldRef (an unsubscribed mutable ref the worker keeps current) and paints at 60fps.
• The observer narrator (components/observer-narrator.tsx) reads snapshots from the store, runs detectEvent against rolling history, routes events via pickObserver, and POSTs to /api/observe.

Where things live

The bench

scripts/bench.ts runs the engine headlessly (no React, no Pixi, no LLM) and prints sampled state for village, town, and city. Use it whenever you change a rate constant or a rule, to see how the dynamics shift without firing up the dev server.

Output is one row per sampleEvery turns per scale, with columns:

turn alive gini coerce shame ties isol% tokens issuers land price vol tVol mat sym norm pow

Read the columns to spot regimes — Gini climbing without bound, tokens not circulating, monoculture lock-in. Runs are deterministic from seed, so before-and-after constant changes are directly comparable.

Calibration knobs

Most useful constants in lib/engine.ts:

In lib/events.ts:

In components/observer-narrator.tsx:

Adding a new observer

See observers.md.

Adding a new event kind

See observers.md.

Adding a new agent rule

Most rules live in lib/engine.ts. The pattern:

1. Read traits, not motivation. The whole point of the trait refactor is that behaviour is f(traits). If your new rule starts with if (a.motivation === ...), you're regressing.
2. Use the rate-constant pattern. Put any tunable number as a const X = ... near the top of the function (or in the constants block near the file top) so it's easy to find and tune via the bench.
3. If it involves memory, decay it and scrub it on death. New per-agent or per-pair state should decay each tick (via decayReputations or the tie decay) and be wiped in scrubReputations / scrubTies when the agent dies. Otherwise long runs leak state and dead-agent references corrupt reputation reads.
4. Add the symptom to the snapshot. If the rule produces a per-tick number you want to read or observe, add it to EngineSnapshot, to getSnapshot(), and to the bench output.
5. Re-run the bench to confirm the new rule doesn't break existing dynamics (Gini, alive trajectory, tokens circulating).

Notes on the rendering

The Pixi renderer (components/simulation-canvas.tsx) is one file but does five things:

• Bootstraps a Pixi Application and appends its canvas to a host div sized like a Canvas2D canvas.
• Pre-builds four motivation textures (square / circle / triangle / diamond) once via app.renderer.generateTexture.
• Renders every alive agent as a Sprite with interpolated position between prevX/prevY and x/y. Wealth-modulated alpha makes inequality visible.
• Renders the resource grid as a single Sprite whose texture is an off-screen Canvas2D, sized at framebuffer resolution and repainted only when world.turn changes.
• Renders selection (vision lines to neighbours, pulsing ring) as a Graphics layer above the agents.

Pixi v8's Texture.from(canvas) caches by source identifier and can return stale entries on canvas resize. The code constructs textures via new Texture({ source: new CanvasSource({ resource: canvas }) }) to bypass that cache for the resource layer. If you see "stretched 1-pixel blur" instead of resources, that is usually the failure mode.

Notes on the worker boundary

The engine class is single-threaded. The worker (app/worker.ts) instantiates one engine, runs tick() on the configured interval, and posts each frame back to the main thread.

Frames are packed in lib/world.ts:serializeWorld into a fixed-stride Float32 buffer (per-agent fields), plus the resource grids and tie array. All payloads are transferable ArrayBuffers — no structured-clone overhead.

The store updates from worker messages. The Pixi renderer reads from activeWorldRef.current (set by the worker bridge in lib/active-world.ts), not the store — this avoids re-renders on every frame.

Pre-deploy checklist

Run lint and a real production build (dev catches less than build does):

npm run lint
npm run build

The /signin page has a pre-existing Next 16 prerender warning about useSearchParams — unrelated and doesn't block.