User Guide

Shannon Bench is a workbench for information itself: what it is, how small it can be squeezed, and how it survives a noisy wire. You type a message and watch an entropy needle price it live; you grow a Huffman tree that compresses it as far as the law allows; then you send it through real, seeded noise and watch encoder chips fight for it — up to the wall no code can pass. Everything happens in your browser; nothing is uploaded.

If Boole Bench showed you how machines are built, and Turing Bench what they can do, Shannon Bench shows what they are all working on — and the one wall even a perfect code cannot pass.

Two colors carry meaning everywhere: amber is your payload, blue is the code machinery riding along to protect it.

0. First visit: the welcome and the hints

On your very first visit the bench introduces itself — the two rooms, the amber/blue rule, and two ways to start: Start with Lesson 1 (opens the Learn layer) or Just let me play.

Hints are the plain-language layer: with the toolbar's Hints toggle on, small blue ? dots appear next to the instruments that need explaining — the gauge, the rack, the prediction readings, the BER counters, the capacity box. Hover one for a short card. They are hovercards, not a tour: nothing moves, nothing is gated.

1. The bench at a glance

The toolbar runs along the top:

Both rooms have the same anatomy: a library rail on the left (what you can load), the canvas in the middle (where things happen), and an instrument rail on the right (what the numbers say).

2. The source room: the message deck

The deck is the single source of truth — every instrument derives from whatever is on it. Click it (it autofocuses) and type.

• Input rule: A–Z, digits, space; everything else is dropped silently. Uppercase is forced.
• The deck caps at 64 symbols — enough for every instrument to stay readable, and an honest limit the Prediction section will remind you of (§3).
• Typing switches the source chip to Scratchpad, but the gauge keeps the last preset's reference mark — comparing your typing against the chosen source is the point.
• Edits append/delete at the end, terminal-style.

The compressor controls sit under the deck:

3. The instrument rail: gauge, rack, prediction

Entropy gauge. The amber needle is H of the deck message in bits/symbol, measured live on every keystroke. The cool mark is the loaded source's designed entropy (its REF). Short samples read low — the gap between needle and mark is a lesson, not an error. The MEASURED / SOURCE REF counters repeat both numbers digitally.

Symbol rack. Every distinct symbol with its count and price on arrival: −log₂ p bits. Rare symbols cost more, and their lamps burn brighter — unless all counts are equal, in which case no lamp lights (a lamp that always burns says nothing).

Counters. Symbols and distinct symbols on the deck.

Prediction. The memory-and-models section (it appears once the deck is non-empty):

• CONTEXT — H(next | prev), estimated from the message's sliding letter pairs. When the message is too short to fill its own pair table (fewer than 3·alphabet² pairs), the reading dims and the caption says THIN: the number memorizes the sample instead of measuring the source, and the instrument says so instead of pretending.
• MODEL H× — the bill a fixed letter-frequency model pays for your message, in bits/symbol. The model reads "the book" — the same corpus the Approximations tab cranks. It can never beat the needle (Gibbs' inequality); the gap is the model's ignorance. If you type a symbol the book never says (any digit), the bill honestly reads ∞.
• PERPLEXITY — 2^(MODEL H×): how many equally likely symbols the model is effectively choosing among.

Compression. Once the deck is non-empty: the same message billed four ways — ASCII (8 bits/symbol), FIXED (⌈log₂ distinct⌉), HUFFMAN (the tree's total), and the average bits/symbol. When Huffman cannot beat fixed, the rail says "compression honestly refuses".

4. The canvas tabs: the tree and the experiments

• Huffman Tree — the compressor grows on the canvas: merge the two lightest nodes until one root holds everything; each symbol's codeword is its branch path. Press ENCODE and the hot path walks each symbol's branch live.
• Beat Huffman — build your own tree by clicking two roots to merge. Any full binary tree is billed honestly (every merge is a prefix code by construction); try to beat the compressor's total. Ties are possible; wins are not.
• Code Forge — no tree, no help: a bare symbol → codeword table you fill in by hand. The forge judges every keystroke live — colliding rows flash as a pair, the Kraft budget bar (Σ 2^−length of 1.00) fills and overdraws into hot, and three meters race your average length L against the needle's H. On THE FOUNDRY (dyadic) the optimal table lands on H exactly; anywhere else the wall stands within one bit. CLEAR TABLE starts over; deck edits keep the words of surviving symbols.
• Bit Log — the encoded stream, symbol by symbol, with each codeword. The decode is separator-free — that is the prefix property at work.
• Guessing Game — Shannon 1951: guess the next letter of a hidden passage until you get it. Your tally of guess counts converts into live lower/upper bounds on the entropy of the language in your head. You are the instrument. Use Test a Friend to paste a hidden passage and hand the keyboard over.
• Approximations — Shannon 1948 §3: crank out text at rising order (uniform letters → letter frequencies → digrams → trigrams) from an editable corpus, and watch gibberish discover spelling. The F-series counters (F₀…F₃) show how memory lowers the rate; TO DECK sends the output to the deck to be measured.
• Mind Reader — be a fair coin; the machine bets first. It predicts your next press from your last two choices, deterministically (inspectable in the engine). Against a true coin it breaks even; against a human it usually wins.

Experiments stay mounted — a game in progress survives tab hops.

5. The channel room: chips, noise, and the wire

The left rail is the code library:

Below the chips, four noise presets (Clean 0.00 · Whisper 0.05 · Noisy 0.10 · Storm 0.30) and the fader for anything in between (up to 0.5). The source panel at the bottom shows what the source room will be sending.

Controls under the wire:

The signal path shows the selected transmission: payload bits in amber, check bits in blue, and ⚡ strikes where the noise hit. When a send is selected you can click a wire bit to sabotage it by hand — the log then tags the row hand-flipped and keeps the record honest.

Determinism. Sends are seeded (seed 0x5EED + send id): the same clicks produce the same flips, RESET truly rewinds, and the trace scrubber replays records instead of re-rolling them. Claims you can re-run are the only claims an instrument should make.

The Arena (image payload)

The center column's second tab swaps the nibble payload for a 32×32 one-bit image — 1024 pixels, 256 blocks of four, through the same seeded channel with whatever chip is armed:

• SENT is a sketchpad: three motifs (Sigma, Smiley, Checker) plus draw-by-drag with the pointer.
• The wire shows one spark per real flip — nothing decorative.
• RECEIVED marks wrong pixels hot; blocks a detecting code flagged but could not fix glow blue (PARITY's honesty).
• The noise fader works live — the fight replays instantly as you drag. RE-DEAL draws a fresh noise realization at the same settings.
• Per lane, two meters: OVERHEAD (wire bits per pixel — the price) and WRONG PIXELS (what survived the decoder — the product).
• DUEL arms a second lane over the same master seed: same image, same dealer, your armed chip against an opponent from the library. Two verdicts side by side; the design wins or loses, not the dice.

6. Reading the verdicts

The transmission log gives every block one of four verdicts, and the words are precise:

• clean — no flips.
• healed — flips happened, payload arrived intact (including flips the machinery absorbed on its own check bits).
• flagged — the decoder detected an error it could not fix (parity's specialty): a fire alarm that can't find the fire.
• lost — wrong payload delivered, and the decoder never knew: repeat's outvoted votes, Hamming's two-flip miscorrections, or a naked channel's everything.

Decoder panel. Click a row: repeat shows each triple's election, parity shows the check, Hamming shows C1/C2/C3 recomputed from the received bits, mismatches highlighted, the address assembled. The panel knows the ground truth from the record and will tag "healed the wrong bit"; the chip's own lamps only ever see the received bits. Both views are shown side by side on purpose.

Syndrome instrument (Hamming): the three check lamps and the assembled address S₃S₂S₁ — the checks spell the crime scene.

BER instruments. BER RAW counts flips on the wire (it tracks the fader; no code changes it). BER OUT counts payload bits still wrong after decoding. A code earns its keep exactly in the gap. STRUCK / HEALED / FLAGGED / LOST count blocks by verdict.

Rate vs Capacity. RATE R is the armed chip's payload share; CAPACITY C = 1 − H₂(p) is the wall. The box judges the armed code against the current noise — when R > C it pulses ABOVE CAPACITY: "no code — present or future — can make this reliable. That is not a warning, it is a theorem." The same C, read as mutual information, is how many bits of source survive each wire bit — the lesson "The Bridge" makes that connection.

Trace. The scrubber rewinds to any past send; records replay exactly. LIVE — drag to rewind.

7. The library: presets and import/export

Every preset is referenced by at least one lesson, and every lesson binds at least one preset (family rule):

Export downloads the bench state as shannon-bench.json: message, preset, armed code, noise level. Import loads one back — it replaces the current state without asking (you chose the file). Unknown presets land on Scratchpad, noise clamps to [0, 0.5], unknown codes are rejected loudly. Your Chip's custom wiring is not persisted in export v1.

8. The Learn layer

Learn opens the 16-lesson course in a right-hand panel; the bench stays live and the canvas stays the hero.

• Lessons live in a room and the bench follows them there; the mode switch stays free — never gated.
• Each lesson, in reading order: a hook, a Watch (points at the live bench, never at a picture), a Predict — multiple choice, instant feedback, never gated — then a Read, an Experiment, sometimes The Fine Print (an honest footnote where the bench simplifies), and a one-breath Recap that hands you to the next lesson. The predict comes before the explanation on purpose: it asks you to apply what the watch showed, and everything that could spoil the answer sits below it. Wrong answers invite you to try it on the bench and answer again; nothing locks.
• The course runs source room (The Bit → The Incompressible, with The Guessing Game and The Code Forge before The Compressor) → channel room (Noise → The Limit, with the Arena arc — The Arena, The Armor, The Duel — after The Healer and The Bridge before The Limit) → and one epilogue back in the source room: The Model, which ends at The Circle Closes — the hand-off to Boole Bench, where a 1937 master's thesis by one Claude Shannon put Boole's algebra into relays.
• Progress (the dot strip) is a souvenir, not a gate. It lives in your browser's localStorage and survives visits.

9. Tips & troubleshooting

• The needle won't move. Click the deck first — it captures keystrokes once focused (it autofocuses on load).
• The needle reads lower than the REF mark on English Text. Correct: a 23-symbol sample cannot show English's true letter statistics. Short samples read low — type more and watch it climb.
• CONTEXT is grey and says THIN. The message is too short for a stable pair table (needs ≥ 3·alphabet² pairs). That is the instrument refusing to lie, not failing. Load WEATHER CHAIN (2-symbol alphabet) to see a stable reading.
• MODEL H× reads ∞. Your message contains a symbol the book never says — any digit does it. A zero-probability event has no finite price; delete the symbol and the bill returns.
• Huffman equals Fixed and won't improve. Your message is (near) uniform — compression honestly refuses. That is Chapter 6 of the workbook, not a bug.
• The capacity box pulses with no code armed. NONE is rate 1.0; any noise puts that above C = 1 − H₂(p). The pulse is the theorem doing its job.
• Same sends, same flips? Yes — seeded noise (see §5). RESET and repeat any experiment; records replay exactly.
• Import failed. The file is validated: unknown code ids and malformed JSON are rejected loudly; fix the file or re-export.

The companion Workbook (one chapter per lesson, exercises with solutions) lives next to this guide — both build to print with python3 docs/docbuild.py.