Bring the tutorial up to the interface that exists, and check its code in CI

[kaidesu]

docs/tutorial.html had spent two rebuilds describing an interface the repository no longer had. It carried a notice saying so, which is better than lying quietly but is not a fix.

The teaching change

The old Part 04 taught a bevel — a light line on the top and left, a dark one on the bottom and right, swapped to make the same box read as a hole — and called it "the entire 3D vocabulary of this interface".

It is the obvious way to build a retro interface and it is not what Aseprite does. A button there is a flat fill with one pixel off each corner and no border of any kind; only windows are outlined. So the chapter now teaches chamfered, surface, and a tone ramp — and says plainly that the earlier version was wrong, since a reader who saw the old one deserves to know which way round it went.

The Button chapter follows: pressed is no longer a bevel inversion but a step down the ramp, which imposes a rule the bevelled version could ignore — a control is read entirely by its tone against its ground, so there must always be a step between them. Get that wrong and the control does not look flat, it looks absent.

Everything else that had rotted

• Theme — Catppuccin by named lookup rather than hex literals, with a note on why the palette had to be identified rather than measured (the references were lossy enough that measurement was impossible, but five values survive at distance 0.0, which is enough to name it).
• Part 00 now teaches the framebuffer, since it is the decision everything else rests on and a 12px menu bar means nothing without it. logical-size.gs is introduced before the entry file that uses it.
• The page's own mockup of the workspace is flat Catppuccin now, with no inset highlight anywhere in it.
• Old theme name, old hex values, and the bevel.dark grid colour all corrected. Zero stale references remain outside the page's own CSS.

New Part 09: the playground

Eight parts in, the old order had the reader build widgets and not look at one until Studio arrived at Part 10. That is backwards. Every serious fault in this project was found by rendering something and measuring pixels, never by reasoning about code.

The new part builds playground.gs and the headless --shot flag, and lists three faults that were invisible until a gallery existed to show them — heading text that vanished on toolbar grey, buttons that disappeared when their outlines were removed, and a one-pixel colour fringe caused by line primitives and rectangles disagreeing about pixel snapping.

Parts 09–16 shift to 10–17; ids, labels and every table-of-contents link were renumbered and verified.

A papercut worse than the one beside it

The log gains the one this rebuild found. The existing entry covers a method name shadowing an import. This one is nastier:

class Probe {
  gap() { return 7 }
  first() { gap = 99; return gap }
  second() { return this.gap() }
}
p = new Probe(); p.second(); p.first(); p.second()

prints 7, then raises. A local does not shadow a method for a call — it destroys that method on the object permanently, from any other method. It is time-dependent, so whether a test catches it depends on call order. It shipped twice: the second time after a linter had been written for it, because the first version of that check only looked in the same method as the local.

The code is checked now

tools/check-tutorial.py extracts every whole-file code block and parses it; CI runs it on every commit.

A tutorial whose premise is "type this" fails worst when the code has quietly stopped working, because the reader cannot tell whether they mistyped it or the page is wrong. Prose going stale is hard to catch automatically; code going stale is not, and this catches that half. All 38 whole-file blocks parse, verified against a deliberately broken one. Blocks marked edit are skipped — they are fragments and cannot parse alone.

Note on the branch

PR #2 was squash-merged, so its four commits are not ancestors of main even though their content is (git diff between them is empty). Rather than force-push over that, this branch merges the old head — bringing the history forward without changing a single file — so the push fast-forwards.

Checks

132 assertions, a clean linter, 38 tutorial blocks parsing, all eight Picotron pixel tiles matching.

🤖 Generated with Claude Code

https://claude.ai/code/session_019QF46RxyogNPLNX7DajyKM

---

Generated by Claude Code