feat: port to TypeScript/Vite and add plotting surface

Migrate the engine, UI, and tests from vanilla ES modules under
js/ to strict TypeScript under src/, bundled by Vite and tested with
vitest. Removes the old js/ tree, css/app.css, and the scripts/serve.js
static server; adds tsconfig, vite config, lockfile, and a GitHub Pages
deploy workflow.

Adds a Plot surface: scatter(xs, ys, "title") / line(xs, ys, "title")
push a plot spec rendered as SVG on a Plot tab alongside the Memory
canvas, so the object graph and the chart read the same data.

Fixes:
- plot title used the repr form (displayValue) instead of the print
  form, so line(..., "trend") titled the chart 'trend'; use printArg
- Tab completion suggested sorted() and list(range(...)), which the
  engine does not implement and would raise NameError

Docs:
- rewrite README and DESIGN for the TS/Vite layout, supported subset,
  meta-commands, and the Plot surface
- align the ADR 001 title and engine header comments to the
  learn-python product name

Co-Authored-By: Claude Code <noreply@anthropic.com>

Author: alisadeghiaghili

.claude/launch.json

@@ -0,0 +1,11 @@
+{
+  "version": "0.0.1",
+  "configurations": [
+    {
+      "name": "learn-python",
+      "runtimeExecutable": "npm",
+      "runtimeArgs": ["run", "dev"],
+      "port": 5173
+    }
+  ]
+}

.github/workflows/deploy-pages.yml

@@ -0,0 +1,48 @@
+name: Deploy to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - name: Install dependencies
+        run: npm ci
+      - name: Test
+        run: npm test
+      - name: Build
+        run: npm run build
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -1,4 +1,5 @@
 node_modules/
+dist/
 output/
 .playwright-cli/
 .DS_Store

DESIGN.md

@@ -25,23 +25,24 @@ Supported subset (deliberately small, pedagogically sharp):
 - `list`, `dict`, `tuple`, `set`, indexing, slicing, `.append` / `.pop` / `.update`
 - Function `def` / call / `return`, local frames, nested calls
 - `print`, `type`, `id`, `len`, `is`, `==`, arithmetic, comparisons
-- Meta: `help`, `levels`, `level`, `goal`, `hint`, `undo`, `reset`, `hint`, `golf`
+- Plotting: `scatter(xs, ys, "title")` / `line(xs, ys, "title")` → SVG board
+- Meta: `help`, `levels`, `level`, `goal`, `hint`, `solution`, `undo`, `reset`, `golf`, `script`
 
-Out of scope v0: classes/OOP, imports, exceptions (except parse/runtime errors shown cleanly), comprehensions beyond simple cases, I/O, async.
+Out of scope v0: classes/OOP, imports, exceptions (except parse/runtime errors shown cleanly), comprehensions beyond simple cases, I/O, async, `range`/`sorted`/`min`/`max`/`abs`.
 
 ## Architecture
 
 ```
-js/engine/     simulated Python runtime (heap, frames, parser, evaluator)
-js/viz/        SVG canvas: stack frames → heap objects → reference edges
-js/levels/     level pack + memoryCompare (goal checker) + golf
-js/shell/      command line, history, undo stack, dialogs
-index.html     app shell
-css/app.css    design tokens + layout
-tests/         engine + compare unit tests (node --test)
+src/engine/    simulated Python runtime (tokenizer, parser, evaluator, memory,
+               session) + goal checks (checks.ts) — the TreeCompare analogue
+src/levels/    6-series / 24-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
+index.html     app shell entry
+tests/         engine + compare + level-solution unit tests (vitest)
 ```
 
-Mirrors LGB's separation: `git engine` / `visuals` / `levels` / `command line`.
+Mirrors LGB's separation: `engine` / `visuals` / `levels` / `command line`.
 
 ### Memory snapshot (the "tree" of this game)
 
@@ -91,12 +92,12 @@ Scale: 11 / 12 / 14 / 16 / 20 / 28 / 40. Line length in the brief ≤ 62ch.
 
 ```
 ┌──────────────────────────────────────────────────────────┐
-│ learn-python   sandbox · levels · undo · reset    golf 3 │
+│ learn-python   levels · lesson · hint · solution · undo  │
 ├───────────────────────────────┬──────────────────────────┤
-│                               │  LEVEL BRIEF (paper)     │
-│   MEMORY CANVAS               │  title · goal · hint     │
-│   [stack frames] → [heap]     │  target mini-canvas      │
-│                               │  par / your score        │
+│  [Memory] [Plot]              │  LEARNING GUIDE (paper)  │
+│   CANVAS                       │  title · brief · hint   │
+│   [stack frames] → [heap]      │  par / your score        │
+│   (or SVG scatter / line)      │  next-step hint          │
 ├───────────────────────────────┴──────────────────────────┤
 │ >>> statement | meta | multi-line …                      │
 └──────────────────────────────────────────────────────────┘
@@ -110,6 +111,7 @@ Scale: 11 / 12 / 14 / 16 / 20 / 28 / 40. Line length in the brief ≤ 62ch.
 
 1. **Reference draw** — assignment draws an amber edge from name → object with stroke-dash animation.
 2. **Alias pulse** — when a shared mutable object changes, every inbound edge pulses once together.
+3. **Data-to-chart** — `scatter`/`line` reads the same heap lists the Memory canvas shows and draws them as SVG on the Plot tab, so the object graph and the chart agree.
 
 ### Motion
 
@@ -126,12 +128,13 @@ Scale: 11 / 12 / 14 / 16 / 20 / 28 / 40. Line length in the brief ≤ 62ch.
 | goal tree compare           | goal snapshot / predicate compare |
 | command golf                | statement golf                    |
 | `undo` / `reset`            | `undo` / `reset`                  |
-| goal dialog                 | paper brief + target mini-canvas  |
-| import / build level (later)| level JSON (v0: static pack)      |
+| goal dialog                 | paper brief + learning guide panel|
+| (no analogue)               | Plot tab: data → SVG chart        |
+| import / build level (later)| level TS catalog (v0: static)     |
 
 ## Engineering standards
 
 - Files, code, comments, Markdown: English.
-- Python-sim engine in TypeScript-free ES modules with full JSDoc (`Args`, `Returns`, `Throws`).
-- Unit tests for parser, evaluator, memory compare — `node --test`.
+- Engine and UI in **TypeScript** (strict), bundled by **Vite**.
+- Unit tests for parser, evaluator, memory compare, and level solutions — **vitest** (`npm test`).
 - No AI footprint in repo content.

README.md

@@ -4,62 +4,92 @@ Interactive Python **memory model** visualizer, sandbox, and challenge levels.
 
 **Live:** https://alisadeghiaghili.github.io/learn-python/
 
-Architectural sibling of [learnGitBranching](https://github.com/pcottle/learnGitBranching): a fully client-side simulator with a live canvas, command shell, goal-checked levels, and statement golf. Where LGB makes git's commit DAG visible, learn-python makes Python's stack/heap object graph visible.
+Architectural sibling of [learnGitBranching](https://github.com/pcottle/learnGitBranching): a fully client-side simulator with a live canvas, command shell, goal-checked levels, and statement golf. Where LGB makes git's commit DAG visible, learn-python makes Python's stack/heap object graph visible — and lets you watch it become a chart.
 
 ## Run
 
 Open https://alisadeghiaghili.github.io/learn-python/ in a browser.
 
-Locally, open `index.html` via a static server (ES modules need HTTP):
+Locally, use the Vite dev server (TypeScript ES modules need a bundler):
 
 ```bash
-node scripts/serve.js
+npm install
+npm run dev
 # → http://127.0.0.1:5173
 ```
 
 ## Test
 
 ```bash
-npm test
-# node --test tests/engine.test.js tests/levels.test.js
+npm test        # vitest run
+npm run build   # type-check (tsc --noEmit) + production build to dist/
 ```
 
+## Layout
+
+Two live surfaces sit side by side:
+
+- **Memory** — stack frames on the left, heap objects on the right, amber reference edges between them. This is the core instrument.
+- **Plot** — `scatter(xs, ys)` and `line(xs, ys, "title")` push a plot spec that renders as SVG on this tab. The memory model and the chart read the same data, which is the pedagogical point: a plot is just a list of `(x, y)` pairs.
+
+Plus a **console** REPL at the bottom (statement or meta-command) and a **learning guide** panel on the right with the level brief, par, and next hint.
+
 ## Sandbox
 
 Type Python-subset statements. Meta-commands:
 
 | Command | Effect |
 |---------|--------|
 | `help` | subset + meta overview |
-| `levels` | list challenge packs |
-| `level <id>` | load a level |
-| `goal` | show the brief |
+| `levels` | list the 24 levels / 6 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 |
 | `hint` | level hint |
+| `solution` | reveal the solution |
 | `golf` | statements used vs par |
 | `undo` | undo last statement |
 | `reset` | reset level / sandbox |
 | `sandbox` | free-play mode |
+| `script` | toggle the multi-line script editor |
+| `clear` | clear the console |
+
+## Supported Python (v0)
 
-Supported Python (v0): names, assignment, `list` / `dict` / `tuple`, indexing, slicing, `.append` / `.pop` / `.copy` / `.update` / `.get`, functions with `return`, `print`, arithmetic, `is` / `==`, `type` / `len` / `id` / `str` / `int` / `bool` / `list` / `dict`.
+A deliberately small, pedagogically sharp subset — not CPython:
 
-Not in v0: classes, imports, exceptions, comprehensions, I/O, async, full CPython semantics.
+- **Literals & types:** `int`, `float`, `str`, `bool`, `None`; `list`, `dict`, `tuple`, `set`
+- **Names:** assignment, rebinding, augmented assign, indexing, slicing
+- **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`
+- **Plotting:** `scatter(xs, ys, "title")` `line(xs, ys, "title")`
+- **Operators:** arithmetic, comparisons, `is`, `==`
+
+Not in v0: classes, imports, exceptions (beyond clean parse/runtime errors), comprehensions, I/O, async, `range`/`sorted`/`min`/`max`/`abs`, full CPython semantics.
 
 ## Architecture
 
 ```
-js/engine/   simulated runtime (tokenizer, parser, evaluator, memory)
-js/viz/      SVG stack frames → heap objects → reference edges
-js/levels/   level pack + goal compare (TreeCompare analogue)
-js/shell/    REPL, undo stack, level flow
-css/         design tokens
-tests/       node:test unit + level-solution tests
+src/engine/    simulated runtime (tokenizer, parser, evaluator, memory, session)
+               + goal checks (checks.ts) — the "TreeCompare" analogue
+src/levels/    6-series / 24-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
 ```
 
+Mirrors LGB's separation: `engine` / `visuals` / `levels` / `command line`.
+
 The engine is intentionally a **teaching subset**, not CPython. Every state transition is controlled so the visualizer can show what a real interpreter hides.
 
 ## Levels
 
-Four packs — Bindings, Aliasing, Containers, Frames. Each level has a brief (lab-note card), optional hint, a goal predicate/snapshot, and a statement-par for golf.
+Six series — Names & Bindings, Aliasing & Copy, Containers in Memory, Mutation & Methods, Functions & Frames, Plotting & Capstone. Each of the 24 levels has a brief, optional hint, a goal (predicate or target snapshot), a statement-par for golf, and a worked solution.
+
+## Tech
+
+TypeScript, Vite, Vitest. No backend, no runtime dependency — the "interpreter" is a hand-written subset whose entire memory graph is inspectable in the browser.
 
 ## License