Zero build in the browser, one pass on disk

Adding a collection requires only a folder with a collection.js descriptor and chapter modules exporting statement, idea, deps, and viz(v). On build, scripts/build.mjs verifies that all 11,541 dependency edges form a cycle-free DAG, computes each item’s transitive ancestor and descendant closures, packs chapters into 88 shelf rows using eight forward-and-backward barycentre sweeps, and derives light and dark collection hues in perceptual OKLCH space.

6,684 ideas in one dependency graph

Because deps cross chapter, book, and discipline boundaries, a single click traces how foundational definitions propagate across the entire graph: an order on a set (pma-1.5) sits at depth 0 with 3,286 downstream descendants; uniform continuity on compact sets (pma-4.19) bridges metric topology into integration and Fourier analysis; the real spectral theorem (ladr-7.29) feeds 664 results across mechanics, quantum theory, and statistics; the 1,989 cross-field links carry mathematical structure into physics (446), engineering (116), statistics (110), computer science (104), and economics (93); and the 77-step longest chain runs unbroken from pma-1.5 through complex and functional analysis, wave mechanics, and quantum gates to Grover’s search algorithm (cplx-13.9).

Thirteen fields, one canvas runtime

Every simulation in the repository is written against the same 3,531-line runtime (core.js + math.js) and 17 domain kits. Instead of static diagrams, each viz(v) exposes the quantity the proof or mechanism controls: you can break compactness on (0, 1] in pma-4.19 and watch the greatest admissible δ(p) collapse to zero near the missing endpoint, drag the launch velocity in mech-8.22 as Keplerian velocities trace an exact circle in hodograph space, drag Greenland to the equator in geog-4.4 to shed its 14× sec²φ Mercator inflation, reconstruct a CT phantom from its Radon sinogram in imaging-3.3, tip an integrated city into segregation in soc-1.2, or snap one tooth off the Antikythera b1 gear in tech-2.9 and watch the Metonic pointer drift.

One mathematical spine, many disguises

The same mathematical skeleton repeatedly reappears under different physical or social names. Following the spectral theorem bridge walks from self-adjoint matrices (ladr-7.29) and SVD (ladr-7.70) to coupled normal modes (mech-11.4) and standing waves on a string (music-2.3); the entropy bridge links Boltzmann microstates (thermo-5.6) to Shannon information (info-1.2) and Landauer’s k_BT ln 2 erasure bound (thermo-5.17); the fixed-point bridge connects Banach contraction (pma-9.23) to Nash equilibria (game-2.3) and PageRank (stoch-4.15); and switching to the 450 landmark papers plots each primary source on the field timeline alongside the graph nodes it introduced.

Auditing 6,621 canvases without eyes

Keeping 6,621 interactive canvases honest requires automated checks at two levels. In headless Chromium, scripts/check.mjs --modes mounts every item in tools/harness.html, clicks through every segmented control and toggle, verifies that every visible canvas paints non-transparent pixels, and flags raw-string TeX backslash escapes or missing live readouts. In Node, 161 primary-source verification suites test the underlying solvers against independent quadrature and published datasets—catching discarded negative-k_x imaginary residuals and sub-Nyquist detector aliasing in Fourier CT (imaging-3.4), separating exact discrete log-odds selection ln(1 + s) from the weak-selection s approximation (popgen-4.2), and auditing every control mode and primitive family across the 85 collections.

A film is a package

Rendering a sixty-minute film in parallel exposes two bottlenecks in stock Manim: concurrent scene processes race on shared LaTeX files, and frame-by-frame numeric readouts fill SVG_HASH_TO_MOB_MAP past 6 GB of RAM. tools/build.py gives every scene worker its own TeX directory, orders jobs longest-first so a short scene never waits behind a long tail, and replaces Manim’s unbounded SVG dictionary with a 400-entry LRU cache.

Twenty-four films, frame by frame

Each barcode strip compresses a full render into 300 vertical slices against the #0E1117 background, making a film’s structure visible before pressing play. You can spot the Kármán vortex street in Navier–Stokes where blue velocity gives way to orange vorticity, the rainbow phase portrait of ζ(s) in The Riemann Hypothesis, the orange attention matrices and purple MLP blocks in How LLMs Work, and the domain-colored complex discs opening Analysis, Built Part 7.

The voice is the clock

Scenes never hard-code pause durations. Instead, narration strings carry inline <bookmark mark='...'/> tags that VoiceoverScene strips before synthesis and maps to the exact start timestamp of the following word:

with self.voiceover(
    "<bookmark mark='a'/> To solve cosine of x equals x, just iterate ... "
    "<bookmark mark='b'/> On the graph, bounce between the curve and the diagonal ..."
) as vo:
    self.play(FadeIn(head[0]), Create(ax), Create(dg), FadeIn(dl))
    vo.wait_until("a")
    self.play(Create(cg), FadeIn(cl))
    vo.wait_until("b")
    self.play(Create(web), run_time=4.0, rate_func=linear)

Because self.play() durations are fixed while vo.wait_until() absorbs the difference in speech cadence, translating a film requires zero timeline editing. Switching from the English cobweb to the Chinese render, jumping to the shrinking Cauchy discs in Rudin 9.23, or zooming ×127 into the √2 ∉ ℚ hole runs the exact same 82 Manim segments in lockstep with each voice.

One color per concept, one IPA rule per term

Across all 705 scene files, mobjects never pass raw hex strings; they import semantic roles from explainer/style.py—tolerance bands in gold (C.EPS) and holes in coral (C.HOLE) across Analysis, Built, or queries, keys, values, and attention across the ML films. On the audio side, a 513-rule pronunciation lexicon injects inline IPA into Kokoro’s G2P front-end so Poisson is never read as “poison”, the differential dy never becomes “die”, and F = m a stays two letters instead of “Emma”.

Hunting dead air

Watching twenty hours of 4K renders at real-time speed to check whether an equation appeared on time does not scale. tools/dead_air.py streams a render through ffmpeg at 320×180 and measures the fraction of pixels brighter than the #0E1117 background, flagging any stretch of 1.5 seconds or longer below 0.30% (a lone header or bare axes). Running it across the series caught places where a vo.wait_until() call sat before self.play()—leaving 12.4 seconds of bare title before the router load replay, 14.5 seconds before the μP scaling card, or 8.0 seconds before the chain-of-thought faithfulness schematic—and cut sparse stretches across the eleven series films by 91%.

Four processes

Splitting a self-hosted workspace across four processes and three Python virtual environments was a truce with dependency management. TradingAgents pulls in the LangChain and LangGraph stack, while the quantitative backtesting engine relies on vectorbt and numba—and both pin transitive packages that clash directly with the FastAPI backend’s own dependencies.

Rather than forcing three incompatible dependency trees into a single environment, the backend isolates both runtimes behind newline-delimited JSON (JSONL) pipes over standard input and output. Each desk run spawns a fresh agents-runtime subprocess and relays its stdout lines to the browser as server-sent events; because each LangGraph process claims a few hundred megabytes of memory, a semaphore caps concurrent runs at five and queues the rest. The quant-runtime takes the opposite lifecycle: importing numba and vectorbt is slow, so the backend starts one worker at boot, keeps it warm across requests, and respawns it automatically if a calculation stalls.

The desk

Convening the trading desk used to be a tool the chat copilot could invoke on its own, which meant a casual question could accidentally launch a multi-minute, twelve-node LangGraph debate. Now a desk run is always deliberate: typing @TradingAgents NVDA in chat starts the graph directly and streams every analyst report, bull-versus-bear rebuttal, and risk-committee turn into the thread without a model middleman deciding whether to.

Ten of the 22 recorded runs reached a final portfolio verdict (3 BUY, 5 SELL, 2 HOLD), and the runner’s parse_action extracts the exact same call from all ten. Replaying those transcripts surfaced two bugs that only appear when real model routers and LangGraph state dictionaries meet. In one NVDA run and one MU run, a free upstream model router intercepted the Bull Researcher’s turn and returned a bare content-safety classifier label (safety: safe) instead of a bull case; with nobody arguing for the stock, both desks marched straight to SELL. Since September, the runner checks every turn against a classifier pattern and redraws the reply up to three times before any downstream agent reads it:

_CLASSIFIER_REPLY = re.compile(
    r"^\s*(?:(?:user|response|prompt|agent)\s+)?safety\s*:\s*(?:un)?safe\b", re.IGNORECASE
)

A quieter bug hid in the risk committee at the end of the graph. Every finished run in the snapshot streamed only the Neutral risk analyst’s turn. All three risk voices had actually run, but the runner looked up risky and safe in the state dictionary where TradingAgents 0.6.0 writes aggressive and conservative—silently dropping two of the three risk perspectives until a contract test pinned the state keys.

What a turn carries

Because an LLM API call pays for every tool schema on every round, shipping the full registry of 138 tools on every turn would burn tens of thousands of prompt characters before the user asked a question. Instead, tools_for_request routes a slice of the catalogue per turn: the 21 core tools are always included, the current page adds its own domain group, and keywords in the user’s question trip any matching intent groups.

To keep schema bloat from creeping back in, a test pins a strict character ceiling for a plain question on each route and requires a written note in the test file whenever a ceiling is raised. The /dashboards page already sits at 28,923 characters against a 28,950 ceiling before any question keywords fire, and asking a question about the book ("how is my book doing?") pulls in enough portfolio and risk tools to push almost every page past its baseline cap.

Ordered by how often it changes

Routing fewer tools shrinks each request; ordering the prompt blocks keeps the provider’s prefix cache warm across turns. On every turn, the loop sends up to five system messages arranged strictly by how often each one changes: the base system prompt (4,998 chars), the listing of 150 slash commands (15,962 chars), and the mode policy (1,073 chars) sit at the very top, followed by the growing conversation history.

The page context block (687 chars) carries a wall-clock timestamp that changes every minute, so it is placed last, immediately before the newest user question. It used to sit before the history—which meant that every time the clock ticked over a minute, that single changing line invalidated the provider’s prefix cache for the entire conversation history behind it.

Building an agent

When a question needs several rounds of data gathering, the copilot can delegate a sub-question to a specialist: a smaller child loop with its own instructions and a narrower slice of the tool catalogue, which runs the lookups in isolation and returns one synthesized paragraph. Five specialists ship with the app (general, market, filings, web, and portfolio), and a user can declare up to eight custom specialists in settings—each with a @name handle, up to 4,000 characters of instructions, a tool allowlist, a model choice, and a cap of eight rounds.

What a custom declaration cannot override is fixed in the loop itself: every child runs in ask mode with mutating actions disabled, its tool list can only ever narrow the parent’s read-only tools, and a specialist cannot delegate again. Because the general specialist declares no tool filter of its own, plan_tools hands it the full read-only slice routed by the question—research_subagent included—and the loop refuses the call at depth one if it tries to recurse.

One fire per slot

A single scheduler drives the backend’s ten recurring system jobs—market snapshots, nightly syncs, thesis scans, and morning or evening briefs—stepping once a minute. Each job is keyed to a slot (a local calendar date or an hour bucket) and may succeed at most once per slot; during an upstream outage, a failing pass retries up to three times in that slot, one minute apart, before waiting for the next window.

Because a self-hosted box can reboot or sleep at any hour, a restart treats any pass left marked running in SQLite as failed and re-fires it immediately, while skipping any morning brief whose catch-up window has already closed rather than delivering a pre-market summary at noon.

Evals without a key

Half of the core evaluation suite (17 of 34 scenarios, 144 checks in all) runs in five seconds without an API key and with outbound network connections blocked, because what it guards is the loop rather than the model. A scripted fake model replays predetermined tool calls and failure modes against the real CopilotLoop, tool registry, and permission checks: verifying that an action attempted in ask mode is stopped before touching disk, that a tool call written as prose is handed back for a retry rather than shown to the user, and that the sixteen-lookup turn compacts older tool results out of its context window as it works and still answers using the very first lookup.

What runs where

Keeping an open-world game smooth in a browser means keeping the 900 MB map off the thread that draws frames. On the main thread, the simulation steps at a fixed 60 Hz—updating CJ, ambient traffic, pedestrians, police, and the mission script interpreter—alongside Rapier physics in WebAssembly and a three.js renderer capped at 30 fps. Everything that touches storage or network lives in background workers: a chunk fetcher downloads, verifies, caches, and inflates raw world archives across 1,943 hash-addressed chunks, while a world streamer unpacks building placements, geometry, and collision meshes for the active region.

Gameplay systems are ported from gta-reversed, the community’s C++ reconstruction of the PC game; wherever gta-reversed has only a stub, the port cross-references the disassembled iOS executable to recover the missing logic.

Streaming a state

The world arrives in 180-unit high-detail windows surrounded by low-detail LODs out to 1,000 units. A small state machine, the region follower, tracks a look-ahead point in front of the car: once that point drifts 30% of a radius from the current window’s center, it asks the worker for the next window; if the car travels 85% of the way to the edge before the new window arrives, the game pauses on a streaming hold rather than letting CJ drive off the end of the collision mesh.

On the synthetic straight road above, at 70 m/s, 2-second windows land just in time and never stop the car. At 2.1 seconds, that extra tenth of a second pushes the car past the 85% threshold and triggers repeated holds.

That exact cliff showed up in the real game. When players reported freezes on fast highways, a scripted route probe drove a 90-second diagonal across the map at 70 m/s and logged 53 streaming holds totaling 28.6 seconds—and along the way uncovered a Rapier physics body leak that no unit test had caught. The streaming worker had been decoding every model in each new window before discarding the ones already resident in memory. Skipping already-loaded models before decoding and caching collision data cut window load times from 1.3–1.9 seconds down to 60–350 ms, reducing the same 90-second drive to a single 1.4-second hold at the start.

Running the original scripts

San Andreas’s story, side jobs, cutscene timing, and ambient triggers are all compiled into Rockstar’s SCM bytecode (main.scm plus roughly two hundred streamed mission scripts), and web-gta executes that original bytecode directly. Each cooperative script thread steps through instructions—a two-byte opcode followed by type-tagged arguments—until it reaches a WAIT, then sleeps until the game clock catches up. (Set the wait to a full second and the thread spends almost all its time asleep, which is what most of the game’s background threads are doing at any moment.)

Writing the bytecode interpreter is the small part; the real work is the opcode catalogue behind it. The original scripts call 1,570 distinct commands across 416,669 places in the bytecode, and each one needs an engine subsystem behind it to spawn a car, assign a pedestrian task, or start a phone call. When a thread hits one of the 127 commands that aren’t ported yet, the interpreter logs the skip, reports “nothing found” for its outputs, and lets the mission carry on rather than crashing the script.

Traffic from the original arithmetic

Ambient traffic runs a direct port of CCarCtrl::SlowCarDownForOtherCar. When another vehicle enters the scan zone ahead, the follower caps its target speed at roughly 62% of cruise and slows down in proportion to the closing gap.

Right behind a bumper, however, three consecutive branches in the original formula produce a quirk you can watch live above. Stopped 8.5 units behind the lead car, the follower stays put in the outer stop zone. Place it one unit closer and it lands in a middle branch that commands a crawl speed of 1, creeping forward until it hits the inner stop zone at 5.9 units—closer than the spot where it was already stopped, it starts moving again. Both zones come straight out of the branching arithmetic ported from reVC.

Fitting on a phone

Running a desktop open-world game inside a mobile browser hits three bottlenecks at once: fill-rate limits, thermal throttling, and tight memory ceilings. To protect frame rate, the adaptive-resolution controller watches the median frame time over a three-second window and drops a step down the resolution ladder (100% → 85% → 72% → 60%) whenever rendering stays slower than 26 fps. On a GPU-bound phone, stepping down to 85% immediately restores smooth frames; on a CPU-bound phone, fewer pixels make no difference, so the controller undoes the step after a single window and backs off—waiting twice as long before each retry—rather than blurring the screen for nothing.

Because few mobile GPUs can sample the PC release’s DXT-compressed textures directly, the port decodes them on the CPU as chunks stream in. Decoding DXT1 blocks into 16-bit colour (RGB565, or RGB5A1 when a block uses DXT1’s transparency mode—swap the two endpoints to see c0 <= c1 turn index 3 clear) instead of 32-bit RGBA cut texture memory around Grove Street in half, from 93 MB to 46 MB.

Finally, because a thumb on glass has no physical resistance, the touch thumbstick uses the iOS port’s non-linear steering curve: the first third of the stick’s travel turns the wheels only a fifth of the way so you can make fine lane corrections at speed, while the outer range opens up to full lock.

A simulation with no screen

One architectural rule governs the entire 66,000-line codebase: GameModel may never import Phaser, a scene class, or a single byte of rendering data. Fifty-three files in the repository touch Phaser, and none of them is reachable from the simulation. During a live battle, the Phaser scene steps GameModel twenty times a second (step(0.05)) and interpolates unit positions between ticks so movement looks smooth at any display refresh rate without the model knowing frames exist. Because the simulation is pure TypeScript, the exact same class runs live raids in the browser, verifies deterministic replays in CI, and generated every figure on this page from a Node script.

Where you attack from

Once deployed outside the shaded exclusion zone, every unit follows a greedy target rule: Barbarians and Archers march toward the nearest building of any kind, while Giants ignore resource huts and head straight for the nearest defense. That makes your landing point decisive, because it determines which defenses your Giants engage first and how long your damage dealers survive behind them.

Deploy the exact same 42-troop army (6 Giants, 4 Wall Breakers, 16 Barbarians, 16 Archers) from twelve points around Ember Keep and the outcomes split completely. From the northeast, the army strings out into the village’s defenses one at a time and dies at 37% destruction with zero stars. From lower down the same side, four of the six Giants survive into the core and the raid clears the village for all three stars in 42 seconds:

b.stars = Number(b.destruction >= 50)
  + Number(townHallDead)
  + Number(b.destruction === 100);

Routes through walls

Every ground unit finds its way across the 48×48 tile grid with four-directional A*. Buildings are solid obstacles, while walls are passable at a price: stepping onto open grass costs 1, and stepping through a wall tile costs 7. A troop will detour up to six extra tiles around a wall before deciding to stop and batter through it, recomputing its path whenever a building or wall segment falls.

Because Giants only target defenses—and Ember Keep’s defenses sit inside stone compartments—20 of the 64 perimeter starting points send them straight through a wall. Barbarians settle for the closest building of any kind, which from the perimeter is always an outside building, so their initial paths never break a wall at all.

One army, twelve villages

Because GameModel runs without a screen, balancing the twelve-stage single-player campaign means sweeping test armies across every village in Node. Deployed from the west, the small starter army fades after the fourth village, while the medium ground force holds three stars through village eight. Air (Balloons and Dragons) flies over every wall to clear the first eight villages just as easily as the ground army, then falls off sharply on the Expert stages as soon as villages gain a second Air Defense.

Every step, recorded

Crown & Clan does not record a battle as video or as a stream of unit positions. A replay saves only the initial setup and your timestamped taps, then simulates the battle again from scratch—45 actions and 317 step sizes for the 16-second raid above, under 10 KB in all.

That only works if simulating the raid a second time produces the exact same battle to the bit. Combat uses no ambient random number generator, hashing a fixed battle seed with a counter whenever a rule needs chance. Distances are computed with explicit arithmetic because browser implementations of Math.hypot can disagree by a few least-significant bits—enough for a projectile in Safari to arrive one tick later than in Chrome and fork the rest of the raid. And because a different tick rate produces a different battle—as the two boards above show halfway through the raid—the recording logs every step size alongside every tap.

The rules

Even if you play Western chess every day, four xiangqi rules will catch you off guard: a horse’s leg can be blocked on the orthogonal step before its diagonal turn; an elephant’s eye too at the midpoint of its two-point diagonal jump (and elephants may never cross the river); a cannon captures over exactly one screen while sliding like a rook when moving to an empty point; and the generals may never face each other along an open file with no piece between them.

Before the UI ever sends a position to the engine, its own TypeScript move generator has to agree with Pikafish on every legal move. A perft test suite pins the two together to the leaf: 44 moves from the starting board, 1,920 two-move sequences, and 79,666 three-move sequences.

Writing a move down

Xiangqi notation reads like a four-character sentence rather than an algebraic square, with files numbered 1 to 9 from each player’s own right-hand side. In the classic central-cannon opening 炮二平五 (C2=5 in World Xiangqi Federation letters), Red takes the cannon (炮) on file two (二) and slides it horizontally (平) to the fifth file (五). When a piece advances (進, +) or retreats (退, −), the final character changes role depending on the piece: for pieces that travel straight along a file, it counts the steps taken; for diagonal pieces like horses, elephants, and advisors, it names the file they land on.

You can play 炮二平五 on the board above, or switch the pieces to letters if you are still learning the characters (Red and Black even use different characters for their own counterparts, such as 仕 and 士 for advisors). To parse a move a user types—whether in Chinese, WXF letters, or UCI coordinates—the app simply renders every legal move in the current position across all three notations and keeps the one that matches.

Compiling Pikafish

Pikafish is written as a command-line program that blocks on stdin waiting for UCI strings. A browser worker has no stdin to block on, so the heart of the 340-line patch turns main() into initialization and exposes a single C function that dispatches one command at a time:

extern "C" void command(const char* cmd) {
    uciP->process_command(cmd);
}

The rest of the patch stubs out native threads for the single-threaded builds and removes NUMA node binding, producing four compact WASM binaries (~700 KB each) that the loader chooses between at startup. The compiler itself had to be pinned as tightly as the C++ source: Emscripten 6.0.2 quietly dropped a flag that told pthread workers where the engine’s script lived, turning every spawned thread into new Worker(undefined) so the engine answered uci and then hung forever before readyok.

Beside the 700 KB core sits pikafish.nnue, a 53.7 MB weight file that accounts for 97.6% of a first visit’s download (and is already Zstandard-compressed, so gzipping it on the server actually makes it 8.8 KB larger). Because browsers refuse to store a 53 MB response in the standard HTTP cache, the app’s service worker stores the network in Cache Storage itself—and attaches the two cross-origin isolation headers that GitHub Pages cannot send, taking an eight-thread search from 414,000 nodes a second to 3.7 million.

The halfmove clock

Every FEN string ends with a halfmove clock counting plies since the last capture. Where chess draws after 50 moves (100 plies), xiangqi enforces a 60-move rule (120 plies), and Pikafish reads that counter directly from the FEN when searching.

In the horse-and-advisor endgame above, forcing mate in three requires five plies. That means the forced mate is still there at a clock of 115 (115 + 5 = 120, delivering mate on the final legal ply) and vanishes into a 0.00 draw at 116. Early versions of web-xiangqi wrote a hardcoded 0 into the clock field of every FEN and ignored the clock on pasted positions—which caused endgames pasted near the 60-move limit to promise forced mates in positions the engine itself would have declared drawn.

Repetition

Repetition is where xiangqi breaks hardest from Western chess. Repeating a board position three times is not an automatic draw; the outcome depends on who is forcing the loop. A player who checks on every move of a cycle loses unless they deviate, and so does a player who perpetually chases an unprotected piece.

The app’s own TypeScript detector catches perpetual check as soon as the cycle forms, since every recorded move already carries a check flag. It deliberately does not guess at perpetual chase: deciding whether a move legally “chases” requires knowing which piece became newly attacked, whether it is defended, and a tangle of exceptions for pinned pieces, generals, and soldiers. As the source comments put it, guessing at that would be worse than saying nothing—so the UI flags an unverified loop as a draw unless a chase is involved, while the WASM patch exposes Pikafish’s internal rulejudge command, which adjudicates both lines above.

Reviewing a game

The review pipeline scores every position at depth 16, maps centipawns onto a win-probability curve, and grades each move by the milder of its centipawn and winning-chance losses. In the game above, play stays roughly level through a pair of mutual stumbles around move 32 until Red steps its general off the back rank with 45.帥五進一, dropping from 43% winning chances to 17% and walking into mate eleven plies later.

That showcase game was played between two of the app’s own AI levels (Easy and Medium) rather than lifted from a book, and for good reason. web-xiangqi once shipped ten “classic grandmaster games” complete with player names, tournament titles, and dates. None of them were real: seven shared the exact same eight-move opening block, and two contained illegal moves that had been loading silently truncated. What gave the fabrication away was pointing the app’s own review engine at them—the supposed grandmasters scored 20% to 28% accuracy with seven to ten blunders apiece, barely ahead of the 7% scored by random legal moves.

Three engines in one tab

Instead of multiplexing a single Stockfish instance across every task, web-chess keeps separate engines in separate Web Workers. Live analysis wants MultiPV and win-draw-loss statistics; the AI opponent wants UCI_LimitStrength and an Elo cap; and re-sending UCI options like Hash between turns silently flushes the engine’s transposition table even when the hash size hasn’t changed. When you ask for a full game review, the app spins up a temporary pool of two to four workers and hands each one a contiguous slice of the game so its hash table stays warm from move to move. (An earlier experiment tried to speed reviews up further and clocked a 37% win on a single run—until a five-run benchmark showed it was actually slower.)

How many workers and threads the app spawns depends on what the browser reports. A phone gets one small, single-threaded engine, a 16 MB hash table, and a single principal variation, since a second line costs two to four times the search effort. An 18-core desktop spins up four review engines with two threads each. Without cross-origin isolation—which GitHub Pages cannot grant unless the app’s service worker intercepts the page—shared memory disappears and each engine drops to one thread, but the four-worker review pool still runs at full width because separate workers share no memory. For a long time, a missing bootstrap wrapper meant the multithreaded build died at startup and silently fell back to single-threaded WASM; fixing that one silent fallback took a depth-16 search from 443,000 to 3.5 million nodes a second.

From a score to a verdict

Stockfish measures positions in centipawns (hundredths of a pawn), which is the right unit for searching a tree and the wrong unit for judging a person. Losing a pawn in a level endgame can cost the game; losing a pawn when you are already a rook ahead changes nothing.

To judge moves in context, web-chess converts centipawn evaluations into winning chances using Lichess’s logistic curve, grades every move on both centipawns lost and winning chances lost, and reports the milder of the two verdicts. Three pawns from a level position cuts your winning chances from 50% to 25% and registers as a Blunder on both ladders; the same three pawns at +10 nudges your winning chances from 97% to 93% and is graded Good. Even walking into mate when already lost (15…Nxd7 in the Opera Game) comes out Good: Stockfish encodes forced mate with a 100-pawn sentinel, which looks like a 90-pawn catastrophe on the raw scale—and once inflated the Opera Game’s average centipawn loss to 316 beside zero mistakes—whereas the winning-chance curve simply sees a lost position ending a move sooner.

One number for a game

Turning forty per-move scores into a single game accuracy looks like a job for a plain average, and for its first seven months web-chess used one. The trouble is that one blunder in forty moves barely dents an arithmetic mean: thirty-nine solid moves at 95 and a single game-throwing blunder at 9.5 still average 93, which reads like a near-flawless game.

Following Lichess, web-chess now averages two different summaries instead. The first weights each move by how volatile the game was around it—the standard deviation of winning chances over a local window—so moves played while the balance is swinging count far more than routine moves in a dead ending. The second is the harmonic mean, which is dominated by the worst move on the board. Averaging the two pulls that one-blunder game down from 93 to 85, while dragging the blunder bar back up shows the penalty disappearing as soon as the mistake is no longer fatal.

Reviewing a game

Putting the worker pool, the dual grading ladders, and the opening book together produces the full review above, searched at depth 16. The default game was played between two of web-chess’s own levels, Club as White and Intermediate as Black. Black was winning for most of the afternoon until White played 19.Nxf6+; instead of taking the knight back, Black stepped away with 19…Kf8, surrendering 8.6 pawns and 66 points of winning chances in a single move—the only Blunder in either game. Switch to the Opera Game and Black’s worst slips (6…Nf6 and 10…cxb5) are only Inaccuracies: after 10…cxb5 the position is already four pawns down in the engine’s eyes, so none of the famous fireworks that follow cost Black many winning chances it still had.

Playing badly on purpose

Stockfish’s built-in UCI_LimitStrength option only goes down to 1,320 Elo, which is still strong enough to overwhelm a casual player. To soften the two weakest levels (Beginner and Novice), web-chess originally injected variety by picking a uniformly random legal move 38% and 20% of the time.

No human beginner plays chess by rolling a die across every legal move on the board. After 4…Bxf3 in the Opera Game, White has to recapture the bishop; 33 of White’s 35 legal moves leave the piece hanging and immediately lose three pawns or more. Under the old rule, Beginner wandered into one of those unforced blunders more than a third of the time. Now the opponent asks Stockfish for its top four candidate lines and only varies among moves that stay within 1.8 pawns of its first choice (0.9 for Novice)—which here means choosing between the two sensible recaptures, Qxf3 and gxf3. Across all 90 positions in both games, Beginner went from throwing away three or more pawns on one move in six to never doing so at all.

Piece artwork: Colin M.L. Burnett's set, as drawn by react-chessboard in the app.

Main thread and worker

The most important architectural line in the codebase separates the UI from the engine. A 200-visit search can take a couple of seconds; if tensor allocations or tree walks happened on the main thread, stones would stutter under your cursor. Instead, the main thread owns only what you see and touch—the React views and a single Zustand store holding the game tree—while a dedicated Web Worker owns model parsing, feature encoding, neural network inference, and tree search.

Keeping that boundary clean comes down to the analysis queue in the middle. When you scrub rapidly through a game, you do not want forty stale board positions piling up in the worker. The queue orders every request by priority—the position currently on screen comes first, then the AI opponent’s next reply, and finally any background full-game review. As soon as you step to a new move, in-flight requests for the old position are cancelled, and completed evaluations are cached directly on their GameNode in the tree so revisiting a branch is instant.

Which backend

A browser cannot execute KataGo’s native binary directly, so web-katrain reads KataGo’s raw .bin weight files (format versions 8 through 16), reconstructs the residual network out of TensorFlow.js operations, and feeds it the exact same inputs: 22 spatial planes over the board (stones, liberties, ko bans, ladders, and the last five moves) plus 19 global scalars for komi and rules.

At startup, the app probes your browser to pick the fastest execution path: WebGPU first, then WebAssembly, and finally plain JavaScript on the CPU. Every fallback exists because browsers fail in quiet, specific ways. Multithreaded WASM requires SharedArrayBuffer, which browsers only expose when a host sends cross-origin isolation headers—headers that GitHub Pages cannot attach on its own, forcing WASM onto a single thread there. WebGPU needs no special headers and handles most modern desktops, but its shader warm-up can still fail on quirky drivers, and browser storage throws in private windows. Each failure degrades to a slower path rather than breaking the app.

Checking against KataGo

The bugs to fear in a neural-network port never crash the page. A transposed feature plane, a flipped sign on komi, or an off-by-one liberty count simply makes the engine play slightly worse Go while every number on screen still looks plausible.

To catch silent drift, web-katrain tests itself against KataGo’s own golden fixture, which records what the native C++ binary outputs on a 5×5 position using g170-b6c96, the compact 3.6 MB network bundled with the app. Pushing that exact position through web-katrain’s binary parser, feature encoder, TensorFlow.js graph, and post-processing produces an almost identical reading: across the board, only four ownership values differ, each by a single permille (0.001), while the policy priors match to the printed digit.

Because a single fixture only pins down one board, a companion test suite checks invariants that must hold on any position: swapping Black and White stones while negating komi must yield a bit-identical input tensor; raising komi must monotonically lower Black’s lead; and under area scoring, summing the ownership map across all intersections must reconcile with the value head’s reported score lead. Even board symmetry needed care: KataGo normally evaluates random rotations and reflections to decorrelate errors deep in the search tree, but at the root node that randomness caused the territory overlay to flicker by up to a quarter point from run to run, so root evaluations now lock to a canonical orientation.

Where the next playout goes

const explore = (scaling * prior) / (1.0 + childWeight);
const score = explore + sign * childUtility; // the best score gets the playout

A single network evaluation gives only a first impression: a policy prior (where a strong player would look first) and a value estimate (who appears to be ahead). Search turns that intuition into calculation by spending playouts, walking down the tree one evaluation at a time. At every node, KataGo’s PUCT formula adds an exploration bonus—scaled by the network’s prior and divided by the weight already spent on that child—to the move’s observed utility.

You can watch that balance shift after move 20 of the self-play game below. At the default constant, the network’s initial favourite, F6, gets the first playout, comes back worse than its prior promised, and quickly cedes the search to H4, which takes 89 of the first 100 playouts. With less exploration, the search locks onto the early leader even harder; with more, the prior keeps pulling visits back toward F6, which climbs to 26. Around this core rule, the port brings over the rest of KataGo’s search details: first-play urgency for unvisited moves, lower-confidence-bound move selection, root symmetry deduplication, subtree value-bias correction, and uncertainty-weighted visits.

Reviewing a game

Once every position in a game has been searched, each move is graded by the points of score lead it gave up, following KaTrain’s six classes from blunder (12 or more points lost) down to best (under 0.5). To give the review above genuine mistakes to catch, the self-play generator occasionally planted a lower-ranked candidate instead of the search’s top choice; the figure labels those slips on the graph.

A candidate table can tell you that a move lost fourteen points, but not where on the board those points went. That is what the swing overlay solves. Because the network predicts ownership for every intersection, subtracting the ownership map before a move from the map after it highlights the exact territory that changed hands. On Move 37, Black’s planted slip at J3 drops 14 points: the swing map immediately shows 15 points in the top right passing to White while 12 points on the left solidify for Black.

Two small constraints make that overlay readable. Subtracting two whole-board estimates leaves a faint haze of tiny deltas across three-quarters of the board, so only intersections that shifted by at least a quarter point (0.25) are painted. And the overlay deliberately prints no point total of its own: ownership and score lead come from different heads of the network, and on this small bundled net their changes disagree by 8 to 25 points. The score readout tells you how much a move cost; the swing map shows you where.