functional-programming-snake/docs/superpowers/specs/2026-11-11-course-extensions.md

Course extensions — spec (2026-11-11)

Status: all twelve items built and verified on 2026-11-11. Where the build differed from the first draft, the text below was corrected in place. The rules as they now stand are in docs/contract.md; results and decisions are in docs/superpowers/notes/2026-10-29-build-log.md. Known leftovers in the wording: Item 9's command is tsc -p js/jsconfig.json (not -p js); Item 11's scripts/play.mjs was built and then replaced by Item 12; Item 9's event type is called Input in JS.

Eleven additions to the Pure Snake course, approved by the owner on 2026-11-11. This document is the contract for the builders. Where it says "builder's call", decide, and list the decision in your report.

Read first: README.md ("For maintainers"), docs/superpowers/notes/2026-10-29-build-log.md (both sections), one finished module end to end (course/10-extensions.md) and its code in all places (js/src, js/solutions, js/test, fixtures).

Rules for every builder

• Layout. Student stubs in <track>/src, finished reference in <track>/solutions, same file names. A stub compiles, carries the doc comment that specifies behaviour, and fails per test (todo('mNN'), ???, failwith "TODO mNN"; in F# use unit functions where a module-level value would fail at load). Tests in js/test/mNN-*.test.js, scala/test/MNN*.test.scala, fsharp/tests/MNN*.fs (+ fsproj entries; src/Snake.fsproj and solutions/Snake.fsproj stay identical).
• Fixtures. Pure-logic cases live in fixtures/mNN-<function>.json as {function, cases:[{name, args, expected}]}, generated from the JS solution with a throwaway script and then read by hand. All three tracks read the same file. Case names are kebab-case sentences.
• Purity. Outside the runtime/browser files: no let/var/mutation/loops with counters/Math.random/clock/DOM (the purity tests of each track enforce it). Recursion and folds instead.
• JS is the reference track. A JS builder writes JS stubs, solutions, tests, fixtures and the course text. Port builders port to Scala or F# and touch only their track's directory.
• Course text (course/*.md): explain why before how; assume general programming experience and no FP or Scala background; never explain by reference to Scala; connect ideas to everyday programming in blockquotes starting > **From everyday programming:**. Signatures in all three languages. Every coding exercise gets three folded hints (nudge, stronger hint, near-solution skeleton with ___ holes — never the full solution), a "Tests"/"Proved by" list naming the JS test titles and fixture cases, and "Check your understanding" questions. Plain, direct prose; British spelling as in the existing text. Update course/reference.md, the README module map/checkpoint table, course/00-setup.md tables and scripts/check-progression.sh (files_for) when files or modules are added. External links must resolve (node scripts/check-links.mjs).
• Signature conventions. JS: data first, plain objects with tag. Scala: methods/objects in package snake, Option, List, Long for seeds and time. F#: data last, bind/choose, PascalCase fields, uint32 seeds, int64 time.
• Verification before you report (from the repo root): scripts/verify.sh <track>, scripts/check-stubs.sh <track>, scripts/check-progression.sh <track> for every track you touched; node scripts/check-links.mjs --offline (and online if you added links) if you touched text. For browser-facing changes: copy the repo to a temp dir, replace src with solutions, run build-web.sh (Scala/F#), serve with node scripts/serve.mjs and run node scripts/smoke.mjs <url> for each page.
• Do not commit, stash, reset or checkout. Do not edit files outside your stated scope; other builders are working in the tree at the same time. Do not weaken or delete an existing test to make something pass; if an existing test contradicts this spec, change it deliberately and report it.
• Report: files created/changed, final script results with test counts, every decision you made that this spec left open, and anything in the spec you found wrong or ambiguous.

---

Item 1 — Turn queue (Module 10, new Exercise 10.6)

Why. Module 3 admits that Up-then-Left within one step loses the second key. Fix it as an extension, without changing the Module 3 rules.

Model. GameState gets one more field, dormant until Module 10 like frame: queued — JS Direction | null, Scala Option[Direction], F# Direction option (Queued). initialState sets it to none. Add "queued": null to every game state in every existing fixture with a script; existing expectations otherwise stay as they are unless they contradict the semantics below (report each such case).

Semantics (in the game module, used by update; turn, advance, tick of Modules 3–4 are unchanged and ignore queued):

• steer(state, dir) — what update does for Turn(dir) from Module 10 on:
  • not Playing → unchanged;
  • no turn pending (nextDir == dir) → turn(state, dir) (the Module 3 rule);
  • a turn is pending (nextDir != dir) → if dir is neither nextDir nor its opposite, the state with queued = dir (a later key replaces an earlier queued one); otherwise unchanged.
• After every game step taken by update (the Tick case and the stepping branch of Frame): if the result is Playing and queued is set, then nextDir = queued and queued = none. If the result is not Playing, queued is left as it is. Restart gives a state with nothing queued.
• Result: Up then Left within one step makes the snake go Up on the next step and Left on the one after.

Tests. New m10-update.json cases covering each branch above, plus a non-fixture test that plays "Turn Up, Turn Left, step, step" and checks the head's path. Module 5's "every other action unchanged"/Turn cases must still pass with the finished update.

Module 12. Add invariant queued-not-reversed (queued is none, or differs from the opposite of nextDir) after turn-not-reversed; extend m12-violations.json; genActions unchanged.

Text. Module 2 (field list, "ten fields" → eleven, canonical model, fixtures note), Module 3 (the question about the queue now points to Exercise 10.6), Module 10 (new section + exercise + hints + questions), reference.

Item 7 — Random states and a model-based test (Module 12, Exercises 12.6–12.7)

Why. Module 12 says invariants cannot see the wrong collision check of Puzzle 1. Close that.

• genSnake(width, height, maxLen) : Random of a snake (head first): a random start cell, then up to maxLen - 1 further cells, each chosen with elementOf among the in-bounds neighbours of the last cell that are not yet in the snake; stop early when there is none. (Exact draw order is part of the contract so that tracks agree; write it in the stub doc.)
• genState(width, height) (given, built from genSnake): a sane Playing state: snake from genSnake, dir consistent with the first two cells (any fixed choice for a one-cell snake), nextDir = dir or a perpendicular direction, apple = none or a free cell, queued none.
• advanceSpec(state) : the step written straight from the rules, in a different style from Module 3's advance: build the snake the step would produce (new head in front; drop the last cell unless eating), then ask violations whether that snake is on the board and free of overlap; if not, game over as Module 3 specifies. It must agree with advance on every state.
• Tests: fixture or seed-pinned tests for genSnake; every generated state has no violations; advance and advanceSpec agree on 500 generated states of a 5×5 board; a mutant advance with Puzzle 1's wrong check ("new head must not be on the old snake") is caught by that comparison.
• Text: new sections in Module 12 ("generating states", "a second implementation as an oracle"), rewrite the bullet that says invariants cannot see Puzzle 1, question 6 now refers to the exercise.

Item 6 — Random is State (Module 4, optional Exercise 4.7)

New file state.js / State.scala / State.fs: State<S, A> = S -> (A, S) with pure, map, flatMap (bind), get, put, modify, run. Tests (m04-state): the laws on small examples; a counter example; and "Random is State with the seed as S": the dice of Module 4 written with State give the same values and seeds as with Random. Nothing in the game changes to use it. Text: a "Going further" section in Module 4 after "A pattern with a name", exercise 4.7 marked optional, hints, two questions (one asks the reader to express a label counter or the Pong serve with State). Progression mapping: with Module 4's files.

Item 4 — Stack-safe IO (optional Module 7b)

New text course/07b-stack-safe-io.md and new file safeio.js / SafeIO.scala / SafeIO.fs, independent of the game and of io: an IO with three constructors (Pure, Effect(op, k), FlatMap(io, f)), where flatMap only builds a FlatMap node, and an interpreter written as a loop (in the purity-audited file a loop is not allowed: write it as a tail-recursive function in Scala/F#; in JS put the interpreter where a while is permitted or — builder's call — express it with a trampoline; say which). Provide pure, effect, map, flatMap, sequence, a pure trace-like interpreter that does not grow the stack, and the re-association step explained in the text. Tests (m07b-*, module tag M07b; make test.sh M07b, check-stubs and check-progression understand it — builder's call how, e.g. number it so the scripts' loops find it): the three monad laws observationally; 100 000 left-nested flatMaps and 100 000 right-nested ones both run; traces equal those of Module 7's IO on the same programs. Text: why left nesting is quadratic and deep for the simple IO, the trampoline idea, the re-association rule as a picture, what production libraries add. Link from Module 7 section 12 and the README map (marked optional).

Item 8 — Mutation analysis as a maintainer script

scripts/mutate.mjs [file...]: single-token mutants of js/solutions files run against the JS suite in a temp copy; prints killed/survived and each survivor with file, line, original and mutated text; exits 1 when there are survivors not listed in an allow-list file of known equivalent mutants (scripts/mutate-allow.txt, with a reason per line). Start from the prototype at /tmp/claude-1000/-home-user-functional-programming-course/9bf00381-a84f-4bd0-87b0-ffcbdbf94782/scratchpad/mutate.mjs. Add a row to the README maintainer table and CLAUDE.md's list of checks is left alone.

Item 2 — A persisted high score (Module 10, Exercise 10.7, replaces the thought exercise)

Effects. Two new Ops: LoadBest (answer: a number) and SaveBest(score) (answer: unit). Scala/F#: OpResult gets Best(value: Int). io: loadBest (a value; F# loadBest ()), saveBest(n). trace must answer LoadBest: JS trace(io, seed, best = 0), Scala a default argument, F# traceWith seed best io with trace seed = traceWith seed 0. Platform gets loadBest() and saveBest(n); the browser implementations use localStorage key pure-snake-best, treat anything unreadable as 0 and never throw; runIO performs them; the fake platforms in the tests record them.

State. GameState, update and view are not changed. A new value wraps the game: Session = {game, best, improved}. sessionUpdate(session, action): game' = update(game, action), best' = max(best, game'.score), improved = best' > best. sessions(seed, best, actions) = startWith(scan(actions, sessionUpdate, s0), s0) with s0 = {game: newGame(seed), best, improved: false}.

Output. sessionView(session) = view(game) followed by one text shape Best: <n> (right-aligned at the top right; exact numbers builder's call, fixed by a fixture). renderSession(session) = drawScene(sessionView(session)), followed by saveBest(best) when improved. main = ask for the seed, then load the best, then the clamped stream of renderSession over sessions(seed, best, speedActions).

Tests. Module 7/9/10 tests that pin main's ops change from [RandomSeed] to [RandomSeed, LoadBest]: update them deliberately. classicMain in the test helpers stays the Module 9 program without the session. New tests: the interpreters handle the new ops; a traced renderSession contains SaveBest exactly when improved; a scripted run that beats the record saves once per improvement; the runtime with a fake platform loads once at start.

Text. Section 7 of Module 10 becomes a built feature: keep the six design questions as the lead-in, then the canonical design above, exercise, hints, questions. Module 7's "adding an effect is adding an Op" now points to it.

Item 5 — The whole program in one equality (Module 9, Exercise 9.5)

A pure helper in the app module: play(main, seed, events) (after Item 2: also the stored best; JS default 0, Scala default argument, F# explicit) returns, for each drawing the program emits while fed events, the list of ops it performs (trace of main, run of the stream, trace of each emitted IO). Tests: play on classicMain equals the scenes of the expected states for a short scripted game; a golden fixture m10-golden.json (built under that name because the final main only exists after Module 10) holds a seed, a list of events and the expected final scene, for main. Text: a short section in Module 9 ("testing the program end to end without a browser"), exercise, hints.

Item 3 — A replay viewer (Module 10, Exercise 10.8)

Why. Module 5 promises replays and nothing shows one.

• A recording is {seed, actions}. fixtures/replay-sample.json holds one worth watching (the snake eats several apples and then dies; produce it with a small bot script and keep it under ~400 actions; Tick/Turn only).
• Pure viewer module (replay.js / Replay.scala / Replay.fs): frames(recording) = history(newGame(seed), actions); viewer state = index into the frames; keys: ArrowRight/d next, ArrowLeft/a previous, Home first, End last, Space toggles autoplay (advance one frame every 100 ms from interval while on; stops at the end); viewerUpdate(viewerState, viewerAction) is total and clamps at both ends; viewerView = the game's view of the current frame plus a step i / n text and a hint line; replayMain(recording) : IO<Stream<IO<unit>>> (no seed needed, so it starts with pure).
• Pages: js/replay.html (+ src/replay-main.js, given), scala/replay.html, fsharp/replay.html with given browser glue and build-script changes; the given glue of all three tracks loads the sample recording with fetch("../fixtures/replay-sample.json") (as built; an earlier draft had Scala/F# embed a generated value).
• Tests m10-replay: viewerUpdate fixture; autoplay via run on scripted events; replayMain traced; stepping back shows exactly the earlier scene.
• Text: Module 10 section + exercise + hints; Module 5's "Replays" bullet points forward to it. README quick start mentions the page.

Item 10 — Second capstone: Conway's Life with the mouse (Module 13)

Why. Pong is close to Snake. Life forces a new kind of input.

• New event: Click(x, y) in canvas pixels. Stream source clicks. Platform.onClick(cb); runtime feeds it; browser glue listens for click on the canvas and converts to canvas coordinates. Existing sources ignore it. This touches stream, runtime, browser in all tracks: keep every existing test green.
• Game in life/ (Life/ in F#): board 40×30 cells of 16 px; state {cells (set of live points, kept as a sorted list, row-major, no duplicates), running, seed, generation}; actions Frame (when running: next generation every 150 ms), Toggle(cell) from a click (as built: always, running or paused; a click that is silently ignored looks broken), TogglePause (Space), Step (n, one generation while paused), Clear (c), Randomize (r: each cell alive with probability about 1/4 drawn from the seed; seed advances). Classic rules B3/S23, edges are dead (no wrap). lifeView, lifeKey, lifeActions, lifeStates, lifeMain (clamped like the others).
• Fixtures m13-life-step.json (blinker, block, glider, edge cases, empty), m13-life-update.json, m13-life-view.json, m13-life-key.json; tests M13. Pages life.html per track with given glue.
• Text course/13-capstone-life.md: the stateful sketch to convert, the rules precisely, the method step by step with questions first and the canonical choice after (as Module 11 does), lighter hints (nudge + stronger hint only), a section on why the next generation is a pure function of the whole board and what goes wrong when the usual in-place loop updates cells one by one. README, setup, reference, progression script, method.md's "next projects" list.

Item 9 — Type checking for the JavaScript track, with no install

js/jsconfig.json with checkJs, strict null checks, ES modules; shared types in js/src/types.d.ts (Point, Direction, Status, Action, GameState, Shape, Op, IO, Event, Stream, Random, Platform, Session, Pong and Life types); JSDoc on exported functions in stubs and solutions referring to them. Goal: an editor with TypeScript support (VS Code out of the box) shows errors, including a non-exhaustive switch over Action (use the never trick in the text, not in the given stubs). No dependency is added to the course: the optional command is npx -y -p typescript tsc -p js --noEmit. scripts/typecheck-js.sh runs it against a temp copy with solutions as src and must pass; if npx has no network, it exits 2 with a clear message. Text: a short optional section in Module 0 ("if your editor understands types") and a paragraph in Module 2 where exhaustiveness is discussed, replacing "in JS you are the type checker" with the more precise statement. The purity test must ignore .d.ts.

Item 11 — An automated play session

scripts/play.mjs <base-url> (Chrome DevTools protocol, zero dependencies, same style as smoke.mjs): for each track's Snake page: load, check the first paint, press keys and check that the picture changes, press Space and check that it stops changing, press R; simulate a hidden tab if CDP allows (Emulation.setCPUThrottlingRate or Page.setWebLifecycleState; otherwise skip and say so) and check that the game is still alive afterwards; for Pong, Life and the replay viewer: load, interact once, check a change. Prints one line per check; exit 1 on any failure. README maintainer row. This does not replace a person playing; the report must say what it could not check.

---

Order of work

Wave 1 (parallel, disjoint files): A = Items 1 + 7 (JS, fixtures, text) · B = Items 6 + 8 · C = Item 4. Wave 2: D = Items 2 + 5 (JS, fixtures, text). Ports 1: Scala and F# builders port Items 1, 7, 6, 4, 2, 5. Wave 3: E = Items 3 + 10 (JS, fixtures, text), then ports 2 (Scala, F#). Wave 4: F = Items 9 + 11.

---

Item 12 — End-to-end tests with Playwright (replaces scripts/play.mjs)

Suggested by the owner after Item 11. Maintainer tooling only: the three course tracks stay free of dependencies.

Layout. e2e/ at the repo root: package.json (private; one dev dependency, @playwright/test, pinned to the exact version installed here), playwright.config.mjs, tests/*.spec.mjs, lib/ helpers. e2e/node_modules, reports and traces are git-ignored. scripts/e2e.sh [--tracks js,scala,fsharp] [-- <playwright args>] builds a temp copy with solutions as src (running build-web.sh for Scala/F# when those tracks are selected), serves it with scripts/serve.mjs on a free port, runs the tests against it and cleans up; exit code is Playwright's. Projects: Chromium and WebKit (Firefox too if a build is installed; never download browsers implicitly — if a browser is missing, skip that project with a clear message).

Three techniques every test builds on (put them in e2e/lib, each proven by its own small test):

1. Fixed seed. An init script replaces crypto.getRandomValues so the page's seed is a known number.
2. Fake clock. page.clock drives requestAnimationFrame, so time advances only when the test says so. Confirm on all three tracks' glue that the timestamp the page receives really is the fake one.
3. Recorded drawing. An init script wraps the canvas 2D context's fillRect and fillText and records each call with the fill style, font and alignment in force, marking where each frame starts. A test can then read the last complete frame as a list of shapes.

The oracle. The tests import the pure JS solutions (js/solutions/*.js) in Node and compute what the page must draw: the last recorded frame must equal the model's scene (sessionView, pongView, viewerView, lifeView) for the same seed and the same events. This is a differential test of each track's browser build against the pure model; it is what replaces pixel-guessing.

Checks, for each track and each browser:

• Snake: first frame equals the new session's scene; one step every 200 ms of fake time at score 0; a scripted game (keys at chosen fake times, enough to eat at least three apples with the fixed seed) matches the model after every key and at the end, including the faster step after the third apple; Up then Left inside one step gives Up then Left (turn queue); Space shows Paused and freezes the scene, Space resumes; a crash shows Game Over, R restarts; a 10 s jump of the fake clock in one frame advances the game by 250 ms only; the best score is saved on improvement, shown after reload, and a page whose localStorage throws or holds garbage still runs and shows Best: 0.
• Pong: holding and releasing keys moves the paddle as the model says; a whole match on the fake clock ends with the model's score and the right winner text; R restarts and keeps a held key.
• Replay: Right/Left/Home/End match the model's frames; autoplay advances one frame per 100 ms of fake time and stops on the last frame.
• Life: clicks on a CSS-scaled canvas with a border toggle the cells the model says (click at cell centres and near cell edges); N, Space (one generation per 150 ms), C and R (with the fixed seed: exactly the model's cells) match the model.
• No page errors or console errors anywhere.

Retire scripts/play.mjs (delete it; scripts/smoke.mjs stays as the dependency-free quick check) and update the README maintainer table, CLAUDE.md is left alone.

Report what the suite still cannot check and what a person still has to try.