Vector — a Go trainer

Levels L0 through L5 are not a difficulty dial inside one template — they are distinct modes of interaction, each with its own component:

• L0 — the lab. An editable example from the lesson, a Run button, an Experiments panel (a list of “what if…” prompts delivered with the exercise in an experiments field), and a box for explaining the code in your own words. Credit is granted by an explicit “mark done and continue” button.
• L1 — predict the output. The code is read-only; the learner first writes down what will be printed and only then runs it. A correct prediction fires its own toast, because the value of the exercise lies in the prediction, not in the act of running.
• L3 — assemble from blocks. A purpose-built ParsonsBuilder: the program is reassembled from shuffled lines, so syntax errors stop getting in the way of testing whether the learner understands the order of operations.
• L4 / L5 — full tasks. Tracked separately in the achievement system: clean-l4 for passing on the first submission, boss-l5 for closing a stage’s final task.

Hints are handed out in portions and counted — the exercise UI shows Hint 1/3. That counter is not decoration: the number of hints taken is what separates “solved it” from “peeked”.

The easiest way to quietly ruin a learning product is to award progress for scrolling past a screen. So after an audit, every call site of markLectureRead and completeExercise was reviewed one by one, and each turned out to hang off a button press: “read it — mark done” on a lesson node, “mark done and continue” in L0, the check button in L1 and L3.

Not a single call from onBack, from unmount, or from an effect. The rule is written as an invariant comment in the two places where the temptation is highest, so that the next edit cannot break it silently.

The same reasoning drove the button relabelling: “got it, next” became “mark done and continue”; “read — next” became “read it — mark done”. A label should name the consequence of the press, not the emotion.

The exam is the data source for spaced repetition. An answer the judge has broken down becomes a card (“written to memory” in the UI), and misses are logged from the verdict rather than from self-rating. Scheduling uses the FSRS interval algorithm on the backend; the frontend holds session marks (lib/reviewmarks.ts) and a local progress cache (lib/progressstore.ts).

Readiness for a review goal is computed with a deliberately blunt formula: half the weight for the share of mature cards, half for the share of completed practice items. The formula is crude, but it can be read aloud, and it explains why a ring shows exactly 17%. In a learning product, an elegant opaque metric does more harm than a coarse legible one.

The exam summary reports four quantities: rubric coverage, factual errors, skipped questions and time overruns. The final verdict is phrased in interview terms — “would not have passed” — rather than as a percentage, because a percentage is easy to forgive yourself.

Revision has a different usage pattern. The main application is a half-hour session at a desk: lesson, editor, run, breakdown. Revision is ten minutes on a phone at an arbitrary point in the day. Merging them into one shell would force the phone to carry the whole course just to reach a queue of cards.

So review.html is a second entry point with its own ReviewApp shell, its own nginx container and its own address on the local network. The consequences that matter:

• The heavy parts are shared. The session engine (TrainScreen, ReviewScreen, ExamScreen), the design system and motion land in shared chunks of a single Vite build. Two applications, one codebase, one npm run build.
• CORS never arises. nginx proxies /api/ to the backend over the internal Docker network, so the phone’s browser only ever talks to one origin. No preflight requests, no Access-Control-* headers, and no time spent debugging either.
• Delivery differs by target. The main application is compiled into the Go binary via embed; the revision application is served as static files from nginx with gzip and a thirty-day immutable cache on Vite’s hashed assets.

The editor is CodeMirror 6 with the Go grammar (@codemirror/lang-go on top of Lezer) and a custom theme in components/codetheme.ts: highlighting is built from the application’s own design tokens rather than the default one-dark, otherwise every code block would look pasted in from another product.

The standalone playground appeared after a direct request: give me somewhere to poke at code without being graded. What made it work:

• An entrance from everywhere. A compact pill button that opens the playground sits in the lower-right corner of every code block — including the read-only prediction code in L1, which previously could not be touched by design.
• Fragments are wrapped automatically. A snippet without package main goes through wrapInMain and becomes a compilable program. Without that, half the buttons would lead straight to a compile error.
• An empty file is a bad start. Entering with no saved draft yields a starter template carrying three micro-steps in comments: run it, change the text, add a Println. The draft lives in localStorage, and “start over” restores the template rather than blanking the buffer.
• The “try this” panel. If the exercise ships its own experiments, those are shown; if not, five universal challenges appear (predict then run; break it deliberately and read the error aloud; insert fmt.Println in the middle and trace the ordering; wrap it in a loop; trigger a panic on purpose and read the stack trace).

Waiting on the backend just to look at a screen costs hours. So the client carries a parallel mock layer: with VITE_MOCK=1 (or when the backend is unreachable) api/client.ts switches to api/mock.ts, which has its own seeds, pure computation functions (computeMilestone, buildWeek) and an emulated code run.

Two principles keep a mock from rotting. First: one set of arrays. The stats sheet and the weekly sparkline read the same source, so yesterday’s figure agrees across both screens and a discrepancy in the mock surfaces as a real bug. Second: honest labelling. In mock mode a sticky banner sits above the interface, stating that the data is generated locally and no backend is attached. A demo should never look more convincing than it is.

One detail shows what realism costs: the run emulator originally detected an HTTP server by matching the greeting text, so a plain Println in the playground falsely printed server output. It now matches on the ListenAndServe call instead.

A trainer is a keyboard-driven application used at speed. That produced a set of decisions nobody notices while they are working:

• Double submit from mouse plus key. The inFlight lock is a useRef set synchronously, before the await, not in state. State updates a render later, and the second event arrives sooner than that.
• Hotkey collisions between phases. A 260 ms debounce on session phase changes stopped a fast double keypress from skipping a step.
• Re-entering a checkpoint. The training screen’s key is derived from the set of cardIds, so the session genuinely restarts instead of resuming with state belonging to a different card set.
• Screen transitions. View Transitions with named groups: only the screen group animates, while the tab bar and the demo banner stay put. The default root cross-fade produced double exposure — the learner described it as sloppy.
• Accessibility. Focus trapping in modal sheets (remember the trigger, cycle Tab, restore focus on close), hit targets of at least 44×44 px, content-visibility: auto on long lists, and prefers-reduced-motion respected — confetti included.