feat: start the course from zero — control flow, a step-by-step loop viewer, and the foundations

- engine: if/elif/else, for, while, break/continue, and range(); string
  literals become heap objects so every str operation is canvas-visible
- engine: record each statement and loop iteration into state.trace so a
  run can be replayed (ADR 003)
- board: a transport bar (first/prev/step/last) scrubs the recorded run,
  so a for/while loop can be watched iteration by iteration
- levels: three new pure-Python series — First Steps, Decisions, Repeating
  (23 levels) — and a reordered catalog: basics -> flow -> loops ->
  functions, then the memory model, then the libraries (78 levels / 16
  series); prerequisites are respected (def before its users, .append
  before the aliasing and copy series)
- onboarding: welcome copy leads from zero; the levels map shows
  difficulty dots and a start-here marker
- docs: CURRICULUM catalog + record-replay section, README subset update,
  ADR 003; fix the raw-string 'in' fallback that tsc caught

Author: alisadeghiaghili

README.md

@@ -41,7 +41,7 @@ Type Python-subset statements. Meta-commands:
 | Command | Effect |
 |---------|--------|
 | `help` | subset + meta overview |
-| `levels` | list the 40 levels / 10 series |
+| `levels` | list the 78 levels / 16 series |
 | `level <id>` | load a level (e.g. `level first-name`) |
 | `lesson` | open the current level's lesson text |
 | `goal` / `guide` | focus the right-hand guide panel |
@@ -60,17 +60,20 @@ A deliberately small, pedagogically sharp subset — not CPython:
 
 - **Literals & types:** `int`, `float`, `str`, `bool`, `None`; `list`, `dict`, `tuple`, `set`
 - **Names:** assignment, rebinding, augmented assign, indexing, slicing
+- **Control flow:** `if` / `elif` / `else`, `for x in …`, `while …`, `break`, `continue`; `range(n)` / `range(a, b)` / `range(a, b, step)`
 - **Methods:** `.append` `.insert` `.extend` `.pop` `.remove` `.copy` `.get` `.update` `.keys` `.clear`
 - **Functions:** `def` / call / `return`, local frames, nested calls
 - **Builtins:** `print` `len` `type` `id` `str` `int` `bool` `list` `dict` `set`
-- **Modules:** `import copy as cp` — `cp.copy` (shallow) and `cp.deepcopy`; `import collections as c` — `c.defaultdict`; `import functools as f` — `f.reduce`; `import numpy as np` — `np.array`, `.copy()`, slicing (views), `+`, `.sum()`
+- **Modules:** `import copy as cp` — `cp.copy` (shallow) and `cp.deepcopy`; `import collections as c` — `c.defaultdict`; `import functools as f` — `f.reduce`; `import numpy as np` — `np.array`, `.copy()`, slicing (views), `+`, `.sum()`; `import pandas as pd` — `pd.DataFrame`, `pd.Series`, `pd.read_csv`; `import asyncio as a`, `import threading as t`
 - **Iterators:** `iter(x)` and `next(it)` — a stateful iterator object you advance by hand
 - **Functional:** `map(fn, it)` / `filter(pred, it)` — lazy iterator objects; `f.reduce(fn, it)` — an eager fold
 - **NumPy:** `np.array` → an ndarray *window* over a separate **buffer** box; `.copy()` mints a new buffer; a slice is a *view* sharing the same buffer; `a + 1` vectorizes into a new buffer; `a.sum()` folds to a scalar
 - **Plotting:** `scatter(xs, ys, "title")` `line(xs, ys, "title")`
-- **Operators:** arithmetic, comparisons, `is`, `==`
+- **Operators:** arithmetic, comparisons, `is`, `==`, `and` / `or` / `not`, `in` / `not in`
 
-Not in v0: classes, real module imports (only the simulated `copy`, `collections`, `functools`, `numpy`), control flow (`if`/`for`/`while`), exceptions (beyond clean parse/runtime errors), comprehensions, I/O, async, `range`/`sorted`/`min`/`max`, full CPython semantics.
+**Watch it run:** every run records a step trace; the transport bar under the board tabs (⏮ ◀ ▶ ⏭) scrubs it, so a `for`/`while` loop can be watched iteration by iteration on the canvas.
+
+Not in v0: classes, real module imports (only the simulated `copy`, `collections`, `functools`, `numpy`, `pandas`, `asyncio`, `threading`), exceptions (beyond clean parse/runtime errors), comprehensions, real I/O, full CPython semantics.
 
 A planned curriculum extends this with pandas, re, datetime and more — all drawn on the same memory canvas. See `docs/ENGINE-EXTENSION.md` and `docs/adr/002-library-modules.md`.
 
@@ -79,7 +82,7 @@ A planned curriculum extends this with pandas, re, datetime and more — all dra
 ```
 src/engine/    simulated runtime (tokenizer, parser, evaluator, memory, session)
                + goal checks (checks.ts) — the "TreeCompare" analogue
-src/levels/    10-series / 40-level catalog + per-level goals, par, solutions
+src/levels/    16-series / 78-level catalog + per-level goals, par, solutions
 src/ui/        app shell, memory canvas, plot board, REPL, dialog, script editor
 src/style.css  design tokens + layout
 tests/         vitest unit + level-solution tests
@@ -91,7 +94,23 @@ The engine is intentionally a **teaching subset**, not CPython. Every state tran
 
 ## Levels
 
-Ten series — Names & Bindings, Aliasing & Copy, Containers in Memory, **Copy Semantics** (shallow vs deep), **Iterators & Iterables**, **Defaults & Functional** (defaultdict, map, filter), **NumPy: Buffers & Views** (ndarray, buffer, `.copy()`, slice-as-view), Mutation & Methods, Functions & Frames, Plotting & Capstone. Each of the 40 levels has a brief, optional hint, a goal (predicate or target snapshot), a statement-par for golf, and a worked solution.
+Sixteen series, 78 levels. The course now starts **from zero**: a pure-Python
+spine — **First Steps** (print, values, names, math, strings), **Decisions**
+(`if`/`elif`/`else`, booleans, comparisons), **Repeating** (`for`/`range`,
+`while`, building data, and a "watch the loop run" level), and **Functions &
+Frames** — reached before any memory-model vocabulary. Only then does the
+memory model arrive: **Names & Bindings**, **Containers in Memory**, **Mutation
+& Methods**, **Aliasing & Copy**, **Copy Semantics** (shallow vs deep),
+**Iterators & Iterables**, **Defaults & Functional** (defaultdict, map, filter).
+Then the data libraries — **NumPy: Buffers & Views**, **Pandas: Tables as
+windows over a buffer** — and concurrency — **Asyncio** (coroutines, tasks, the
+event loop) and **Threading** (threads, shared state, the data race) — closing
+with **Plotting & Capstone**.
+
+Each level has a brief, optional hint, a goal (predicate or target snapshot), a
+statement-par for golf, and a worked solution. Every level's own solution is
+verified to solve its goal within `par + 2` statements, so the whole catalog is
+proven runnable, not just compilable.
 
 ## Tech
 

docs/CURRICULUM.md

@@ -118,8 +118,9 @@ what is simulated:
 
 - `pd.read_csv(name, data)` builds a real DataFrame; the *content* is supplied
   (there is no disk), the *structure* is the lesson.
-- A view mutation is real in-model (it writes the shared buffer); a real
-  `for`-loop is out of the subset (consumption is `next()`-driven and visible).
+- A view mutation is real in-model (it writes the shared buffer). A real
+  `for`/`while` loop *is* in the subset now, and each of its iterations is
+  recorded so the learner can watch it step by step on the canvas (§2.8).
 - Every deep lesson names where the model stops and CPython takes over.
 
 This is a feature, not a defect: it forces the learner to see the object graph,
@@ -196,30 +197,122 @@ Every series ships the same way: **engine → canvas → predicates → tests 
 with `npx tsc --noEmit` + `npm test` (and the browser) green at the end of each
 step. The numpy and pandas series are the two worked references.
 
+### 2.8 The step-recording hook (watch it run)
+
+The canvas is the signature feature, and the one thing a static end-state can't
+teach well is a **loop**. Rather than build a full program-counter interpreter,
+the evaluator records a *trace*: when trace capture is on, after every top-level
+statement and after every loop iteration it appends a `cloneState(state)` snapshot
+to `state.trace` (capped at `TRACE_CAP = 60` frames so a runaway `while` can't
+explode memory; the growing array is stripped out of each clone so frames never
+nest).
+
+- `setTraceEnabled(on)` / `isTraceEnabled()` in `evaluator.ts` toggle capture;
+  the UI turns it on once at startup, so every run is scrubbable.
+- `MemoryState.trace?: MemoryState[]` holds the frames. Frame 0 is the state
+  *before* the run; frame N is after the Nth recorded step.
+- `snapshot()`, goals, and predicates never read `trace` — it is a pure replay
+  aid. `recordStep` is a no-op when capture is off, so tests and the solvability
+  gate are unaffected.
+
+The **stepper** (the transport bar ⏮ ◀ ▶ ⏭ under the board tabs, `src/ui/board.ts`)
+shows up after a run with two or more frames and lets the learner scrub; App paints
+the selected frame through the existing `renderMemory`/`renderRam`. This is what
+makes the `watch-the-loop` level real: the same code runs, and the learner steps
+through it to *see* each iteration change the canvas.
+
 ---
 
 ## 3. The catalog (current)
 
-**55 levels across 13 series.** Series are in teaching order. `band` is the
+**78 levels across 16 series.** Series are in teaching order. `band` is the
 level's ELI band.
 
+The course now opens with **pure Python from zero** — `print`, values, names,
+math, strings, decisions (`if`/`elif`/`else`), and loops (`for`/`range`/
+`while`) — before any memory-model vocabulary. The memory model (names,
+containers, aliasing, copy) is the *second* layer, reached only after the learner
+has felt real control flow. Prerequisites are respected: `functions` (`def`)
+precedes every series that calls a function, and `mutation` (`.append`) precedes
+the aliasing and copy series that mutate lists.
+
 | Series | Title | Levels |
 |--------|-------|--------|
+| `basics` | First Steps | 8 |
+| `flow` | Decisions | 8 |
+| `loops` | Repeating | 7 |
+| `functions` | Functions & Frames | 4 |
 | `names` | Names & Bindings | 5 |
-| `aliasing` | Aliasing & Copy | 4 |
 | `containers` | Containers in Memory | 4 |
+| `mutation` | Mutation & Methods | 4 |
+| `aliasing` | Aliasing & Copy | 4 |
 | `copy-semantics` | Copy Semantics | 3 |
 | `iterators` | Iterators & Iterables | 4 |
 | `functional` | Defaults & Functional | 4 |
 | `numpy` | NumPy: Buffers & Views | 5 |
 | `pandas` | Pandas: Tables as windows over a buffer | 5 |
 | `asyncio` | Asyncio: Coroutines, Tasks & the Event Loop | 5 |
 | `threading` | Threading: Threads, Shared State & the Data Race | 5 |
-| `mutation` | Mutation & Methods | 4 |
-| `functions` | Functions & Frames | 4 |
 | `plotting` | Plotting & Capstone | 3 |
 
-### Core Python
+### Foundations (from zero)
+
+These three series are pure Python with no memory-model vocabulary: the learner
+writes `print`, names values, does math, and builds strings, then makes decisions
+and repeats. The canvas is present but the story is the code, not the graph.
+
+**`basics` — First Steps**
+
+| id | band | name |
+|----|------|------|
+| `hello-world` | eli5 | Hello, world |
+| `first-variable` | eli5 | Save a value |
+| `change-a-value` | eli5 | Change a value |
+| `do-math` | eli10 | Do some math |
+| `build-up` | eli10 | Build a value up |
+| `your-name` | eli5 | A word in a box |
+| `combine-words` | eli10 | Join two words |
+| `how-long` | eli10 | How long is it? |
+
+**`flow` — Decisions**
+
+| id | band | name |
+|----|------|------|
+| `true-or-false` | eli10 | True or False |
+| `is-equal` | eli10 | Ask if equal |
+| `is-bigger` | eli10 | Bigger or smaller |
+| `first-if` | eli10 | Your first if |
+| `if-else` | eli10 | If … else |
+| `elif-ladder` | eli15 | Picking with elif |
+| `and-or` | eli15 | And, or, not |
+| `membership` | eli15 | Is it in there? |
+
+**`loops` — Repeating**
+
+| id | band | name |
+|----|------|------|
+| `count-with-range` | eli10 | Count with a loop |
+| `range-start-stop` | eli10 | A range with a start |
+| `loop-a-string` | eli10 | Loop over a word |
+| `while-loop` | eli15 | Loop until done |
+| `loop-with-if` | eli15 | Loop plus a decision |
+| `break-out` | eli15 | Stop early with break |
+| `watch-the-loop` | eli15 | Watch the loop run |
+
+`watch-the-loop` leans on the **step-recording hook** (§2.8): after a run the
+learner scrubs the recorded frames with the board's transport controls (⏮ ◀ ▶
+⏭) and watches each loop iteration paint onto the canvas.
+
+### Core Python (the memory model)
+
+**`functions` — Functions & Frames**
+
+| id | band | name |
+|----|------|------|
+| `print-is-not-magic` | eli5 | `print` is not magic |
+| `define-function` | eli10 | Define a function |
+| `call-and-bind` | eli10 | Call and bind |
+| `rebind-in-fn-is-local` | eli20 | Rebind inside a function |
 
 **`names` — Names & Bindings**
 
@@ -231,15 +324,6 @@ level's ELI band.
 | `values-vs-refs` | eli10 | Values vs references |
 | `shared-value` | eli10 | Two names, one value |
 
-**`aliasing` — Aliasing & Copy**
-
-| id | band | name |
-|----|------|------|
-| `two-names-one-list` | eli10 | Two names, one list |
-| `copy-dont-alias` | eli10 | Copy, do not alias |
-| `rebind-vs-mutate` | eli15 | Rebind vs mutate |
-| `identity-is` | eli15 | Identity: `is` |
-
 **`containers` — Containers in Memory**
 
 | id | band | name |
@@ -249,6 +333,24 @@ level's ELI band.
 | `tuple-identity` | eli10 | Tuple identity |
 | `set-semantics` | eli15 | Set semantics |
 
+**`mutation` — Mutation & Methods**
+
+| id | band | name |
+|----|------|------|
+| `grow-with-append` | eli10 | Grow with `append` |
+| `pop-returns` | eli15 | `pop` returns |
+| `dict-get-safe` | eli15 | Safe `dict.get` |
+| `dict-update-merge` | eli15 | `dict` update / merge |
+
+**`aliasing` — Aliasing & Copy**
+
+| id | band | name |
+|----|------|------|
+| `two-names-one-list` | eli10 | Two names, one list |
+| `copy-dont-alias` | eli10 | Copy, do not alias |
+| `rebind-vs-mutate` | eli15 | Rebind vs mutate |
+| `identity-is` | eli15 | Identity: `is` |
+
 **`copy-semantics` — Copy Semantics**
 
 | id | band | name |
@@ -275,24 +377,6 @@ level's ELI band.
 | `map-lazy` | eli15 | `map`: a lazy transform |
 | `filter-truthy` | eli15 | `filter`: keep what is truthy |
 
-**`mutation` — Mutation & Methods**
-
-| id | band | name |
-|----|------|------|
-| `grow-with-append` | eli10 | Grow with `append` |
-| `pop-returns` | eli15 | `pop` returns |
-| `dict-get-safe` | eli15 | Safe `dict.get` |
-| `dict-update-merge` | eli15 | `dict` update / merge |
-
-**`functions` — Functions & Frames**
-
-| id | band | name |
-|----|------|------|
-| `print-is-not-magic` | eli5 | `print` is not magic |
-| `define-function` | eli10 | Define a function |
-| `call-and-bind` | eli10 | Call and bind |
-| `rebind-in-fn-is-local` | eli20 | Rebind inside a function |
-
 **`plotting` — Plotting & Capstone**
 
 | id | band | name |

docs/adr/002-library-modules.md

@@ -53,8 +53,7 @@ Extend the subset, not the runtime philosophy:
 - **Fidelity boundary is explicit and fixed:** the sandbox cannot read/write real files. I/O levels
   (`read_csv`, `to_excel`, `to_pickle`, h5py) model the *result object* and the *serialization
   meaning* (e.g. pickle = freezing the whole object graph to bytes, preserving aliasing), not real
-  disk access. `for` is not in the subset, so iterator consumption is taught with explicit `next()` —
-  which is *deliberately better* for this tool: each step is visible on the canvas, whereas `for`
-  would hide consumption inside the loop.
+  disk access. (Control flow `if`/`for`/`while` and `range` were added to the subset later — see
+  ADR 003; the `iter`/`next` protocol is still taught explicitly so the iterator object is visible.)
 - Scope is capped per library to the 5-ladder "0→90" (mental model → daily API → real patterns →
   depth/gotchas → capstone project). See `ENGINE-EXTENSION.md` for the contract and phase plan.

docs/adr/003-control-flow-and-record-replay.md

@@ -0,0 +1,73 @@
+# learn-python — ADR 003: Add control flow, and teach it by recording then replaying
+
+## Status
+
+Accepted
+
+## Context
+
+The course is an interactive Python **memory model** visualizer, but the subset had no control
+flow: no `if`/`for`/`while`, no `range`. Two problems followed from that.
+
+1. **The course started from the middle.** The simplest concepts — printing, naming a value, a
+   decision, a loop — are what a learner with zero Python actually needs first. But they were the
+   *last* things taught (or absent), while aliasing, numpy, and threading came early. A brand-new
+   learner landing on level 1 was shown `stack frame` / `heap` vocabulary before they had written a
+   single line that did anything.
+2. **Loops were the one thing the canvas could not show.** The signature feature is watching state
+   change. But the interpreter ran a whole submission in one tick and drew only the *final* state.
+   A `for` loop is fundamentally a *sequence* of states, and the final state alone loses the lesson
+   ("the same line runs again and again").
+
+The fix had to be real: to start "from zero," the engine genuinely needed `if`/`for`/`while`/
+`range`, and to make loops visible it needed to be able to *show the intermediate states*.
+
+## Decision
+
+Two additive, orthogonal changes.
+
+**1. Control flow in the subset.** The tokenizer already emitted the keywords and
+`INDENT`/`DEDENT` (the `def` block parsing relied on them), so adding control flow touched only the
+parser and evaluator:
+
+- `parser.ts`: a `parseSuite()` helper (the indented-block loop `def` already used) is shared by
+  `parseIf` / `parseFor` / `parseWhile`, so nested blocks recurse for free.
+- `evaluator.ts`: `case 'If'` / `case 'For'` / `case 'While'` / `case 'Break'` / `case 'Continue'`
+  in `execStatement`, plus `range(n[, stop[, step]])` as a builtin. `break`/`continue` are
+  marker exceptions caught by the enclosing loop. A `while` guard caps iterations so a
+  beginner's `while True` cannot hang the browser.
+- **Strings become heap objects.** String *literals* now allocate a heap `str` object (the rest of
+  the subset already did for lists/dicts). This keeps every `str` code path — concatenation,
+  `.upper()`, indexing, `in`, looping over a word — uniform and, crucially, *visible on the canvas*,
+  consistent with the "make identity visible" thesis.
+
+**2. Record, then replay.** Rather than build a program-counter interpreter with pause/resume, the
+evaluator *records*: when capture is on, after every top-level statement and after every loop
+iteration it appends a deep `cloneState(state)` to `state.trace` (capped at 60 frames; the growing
+array is stripped from each clone so frames never nest). The UI then *replays*: a transport bar
+(⏮ ◀ ▶ ⏭) under the board tabs scrubs the recorded frames, painting each through the existing
+`renderMemory`/`renderRam`.
+
+Record-replay was chosen over a live PC-based stepper on purpose: "watch the loop" only needs the
+*history*, and cloning already-built state is far less machinery than pausing mid-execution. If
+interactive stop-and-resume is ever needed, the trace is the right foundation to build on.
+
+`MemoryState.trace` is a pure replay aid — `snapshot()`, goals, and predicates never read it, and
+`recordStep` is a no-op when capture is off — so the solvability gate and existing tests are
+unaffected.
+
+## Consequences
+
+- **The course opens from zero.** New pure-Python series — `basics` (print, values, names, math,
+  strings), `flow` (booleans, comparisons, `if`/`elif`/`else`), `loops` (`for`/`range`, `while`,
+  building data, and the "watch the loop run" level) — come first, with no memory-model vocabulary.
+  The memory model (`names` → `containers` → `mutation` → `aliasing` → `copy-semantics`) is the
+  second layer. `functions` (which introduces `def`) is moved before the library and concurrency
+  series that call functions, and `mutation` (`.append`) before the series that mutate lists.
+- **Every run is scrubbable.** Trace capture is on by default in the UI, so the learner can step
+  through any run; the `loops` series has a level built on it.
+- **The subset is now a real (small) Python.** `if`/`for`/`while`/`range` and string identity on the
+  canvas are honest features, documented in the README and `docs/CURRICULUM.md`. The fidelity
+  boundary (no real I/O, simulated libraries) is unchanged.
+- **Cost:** one `cloneState` per step, bounded by the 60-frame cap. `cloneState` is a JSON deep
+  clone; at this size it is invisible in the browser.