[WIP] #E — Asteroid TUI demo (interactive polish in progress)

[jowch]

#E — Tachikoma ASCII Asteroid Blaster (examples/asteroid_tui/)

The wave-2 headline demo: measure-once, layout-many in terminal space. Prose is shape-packed into procedural asteroid silhouettes, fractured on word boundaries when hit, and reflowed live as asteroids rotate.

Architecture

Renderer-agnostic CellBuffer (Matrix{Char} + 256-color + bold). Pure tick!(state, input) + draw!(buf, state) — no terminal I/O in the core. The interactive Tachikoma renderer drains the CellBuffer to screen; the CI test drains it to a checksum.

Consumes all four wave-1 deps:

• subprep (#A) — word-boundary fracture without re-measuring
• FigletBackend (#B) — cell-level display type
• shape_pack/raster_chord_fn (#C) — pack words into a cell-grid silhouette
• asteroid_polygon/voronoi_shatter/rasterize (#D) — shapes, fracture, raster

A tiny internal CellBackend (1 cell/grapheme, metrics (1,0,1)) makes shape_pack land on integer cell coords.

Tests — 89 pass, headless

• Golden frame: seeded 60-tick scripted scenario (forces a hit→fracture) → CellBuffer checksummed via SHA-256 over a canonical byte encoding (version-stable, not Base.hash), committed at test/golden/frame60.sha256. Human-readable snapshot at test/golden/frame60.txt.
• Glyph preservation (order-exact): test/test_fracture.jl asserts vcat(shard words…) == original — every glyph survives once, in order. Also a short-prose/high-shard-count case guarding _word_boundary_splits against rounding collisions and voronoi_shatter returning fewer polys than requested (1:1 pairing asserted, no silent zip truncation).
• Integer-cell adjacency, FIGlet-ext activation, physics/charge/respawn/invuln, draw determinism.

⚠️ Tier-2/3 (human) check required — NOT unit-testable

The interactive Done-whens live in src/render_tachikoma.jl + run.jl and need a human at a real terminal:

• ≥30fps in a 120×40 terminal with ~5 asteroids
• respawn flash + ~3Hz invulnerability blink
• ? debug overlay live toggle
• beam length scaling on screen

The Tachikoma input/present shims (_poll_input/_present) are isolated stubs to be wired against the live event API during interactive bring-up; the game core and golden test do not depend on them.

Conventions

• Manifest.toml gitignored (Project.toml only)
• [extras] Test + [targets] test — Pkg.test() works
• SPDX MIT header on every .jl
• julia = "1.12" (Tachikoma floor), independent of TextMeasure's 1.11
• Did NOT invoke finishing-a-development-branch (orchestrator integrates)

Plan: docs/superpowers/plans/2026-05-28-E-asteroid-tui.md

🤖 Generated with Claude Code

[jowch]

Review — round 1

Re-review of the #E Asteroid TUI demo, verifying the 3 MAJOR + 3 minor plan-gate findings and the core demo invariants. I dispatched the project's textmeasure-reviewer agent over the full tree and independently spot-checked the highest-risk claims (grouping logic traced by hand, checksum, wall-clock, Manifest tracking, runtests structure). All prior findings are resolved with real, non-vacuous fixes, and every listed invariant holds. No blocking issues. One dead-constant nit below.

Resolved since plan gate

• MAJOR #1 — runtests structure: test/runtests.jl:2-3 keeps top-level using AsteroidTUI / using Test; :8-10 retains the dependency surface testset asserting AsteroidTUI._ext_loaded() (real Base.get_extension(...) !== nothing check) alongside the include loop (:12-15). ✅
• MAJOR #2 — order-exact glyph preservation: test/test_fracture.jl:21-23 asserts rebuilt == original (vcat of shard words == original word list), guarded by @test length(g.shards) >= 2 (:19) so it exercises a real multi-shard fracture — order-exact, not membership. The golden test's weak membership check is removed and replaced by an explanatory comment (test/test_golden.jl:54-59) pointing at test_fracture.jl. ✅
• MAJOR #3 — _word_boundary_splits rewrite: src/game.jl:131-154 groups by word ordinal (div((i-1)*nw,n)+1), strictly-increasing starts ⇒ no empty/duplicate leading range; @assert length(ranges)==length(polys) at :179 precedes the zip at :182; wordless extra polys dropped at :176-178. Test test/test_fracture.jl:28-53 drives 3 words over n in 1:6 proving no empty range / contiguous tiling / lossless in-order rebuild, plus a full short-prose fracture. Traced n=3 by hand: starts=[1,3,5] → ranges [1:2,3:4,5:5], tiles 1:5 with no gaps. Non-vacuous. ✅
• Minor #4 — length(graphemes(text)) without collect: src/cellbackend.jl:17-18. ✅
• Minor #5 — integer-cell adjacency: test/test_cellbackend.jl:30 ys[2]-ys[1] == 1.0, guarded by a 2-line check at :28. ✅
• Minor #6 — golden-drift rng hoisted + deterministic fracture: test/test_golden.jl:17 hoists drift_rng = Xoshiro(99) out of the loop; _run_golden parks/zeroes asteroid 1 so the beam deterministically fractures it (:43 asserts length(g.shards) >= 2). ✅

Core invariants — all PASS

• CellBackend (src/cellbackend.jl:13,17-20) subtypes TextMeasure.AbstractMeasurementBackend; measure = grapheme count (no byte/char, no kerning); font_metrics = FontMetrics(1.0,0.0,1.0); methods qualified as TextMeasure.measure/font_metrics; internal to the demo.
• Checksum (src/cellbuffer.jl:47-56) is bytes2hex(sha256(_canonical_bytes(...))) over a canonical encoding (dims as UInt32, UTF-8 codeunits w/ 0x00 separators, fg, bold) — no Base.hash, version-stable.
• tick!/draw! pure/deterministic: no time()/now()/Dates in src/game.jl or src/draw.jl; randomness threads g.rng. The only sleep(1/60) is in the interactive src/render_tachikoma.jl:45, not in logic.
• Interactive Done-whens (≥30fps, respawn flash, ~3Hz invuln blink, ? overlay) isolated to render_tachikoma.jl/run.jl and flagged as human tier-2/3 (render_tachikoma.jl:3-6, README); no test asserts on them. The pure blink/respawn counters are unit-tested (correct split).
• Test assertions are on CellBuffer/checksum/computed structs — no test greps terminal escapes.
• Heavy deps isolated to examples/asteroid_tui/Project.toml; root Project.toml untouched.
• Manifest.toml not tracked (git ls-files empty; matched by .gitignore).
• SPDX header on all 20 .jl files; Project.toml declares julia = "1.12".
• Test count: independent trace ≈ 88 (60 static + loop expansion in test_fracture's for n in 1:6 block), within off-by-one of the claimed 89 (testset-as-result ambiguity). Plausible.

Nits

• src/game.jl:24 — const RERASTER_EVERY = 5 is declared but never referenced. Drop it or wire it up; harmless either way.

[jowch]

Review — round 2

Scoped re-review of the showcase redesign (head 537c62f): new draw.jl rendering code, shard-scatter change in game.jl, and the golden relocated to a static composed hero scene. I read the bytes from disk (write primitives, every draw layer, both golden fixtures, all touched tests) rather than trusting prose. Code correctness is clean — one blocking doc defect and two nits below. The round-1 nit (RERASTER_EVERY) is fixed (ee56b8a).

Blocking

1. examples/asteroid_tui/README.md:58-61 — the scene description is factually wrong about the committed artifact. It says "a 120×40 showcase scene" with "a four-shard explosion from a beam hit," but the pinned golden (test/test_golden.jl:33-37) is 116×36 with two INTACT asteroids and no shards/explosion (dominant text-mass + smaller intact asteroid + hunting ship). The same README also says 116×36 at line 49, so the file self-contradicts. Fix: rewrite 58-61 to describe the actual static scene; note that fracture/shard mechanics are exercised by the runtime + test_fracture.jl, not by this frame.

Nits

• src/draw.jl:116-130 — _callout_cells is dead code (no call sites), and its comments at :94-95 and :115 reference an "overprint scorer" that does not exist in this PR. Either wire it into a real overprint test or delete it + the scorer comments.
• The "overprint-free by construction" framing overstates the guarantee. Asteroid/shard prose (_blit_packed!, draw.jl:159), callout box rules (:144-146), ship hull (:186-189), and border/footer (:29-43) write unconditionally (put_char!/put_string!); only trails/leader/plume/beam use the _put_if_empty! guard. The frame is overprint-free by z-order + hand placement in the seed-38 scene, not by an empty-cell guard on every layer. (The draw! docstring at :214-217 is itself accurate — it only claims trails/leader/plume are empty-only — so this is about the broader claim, not that comment.)

Verified PASS — overprint, fracture, scope, assertions

• 0 border-overprint: _draw_border! is drawn LAST and unconditionally (draw.jl:236, 26-45), so the border is always intact in the final frame; stray edge glyphs are clipped (deliberate).
• 0 cross-entity overprint in the committed frame: entities are hand-placed apart (a1 x=32, a2 x=93, ship x=58/y=31 in clear space); no collision; the SHA-256 checksum anchors that exact frame. (True for this scene, per above — not a universal structural guarantee.)
• No out-of-bounds writes possible: every write clips via inbounds (cellbuffer.jl:30).
• Glyph-preservation on fracture intact: the scatter change (game.jl:181-198) only alters shard spawn position/velocity; the tiling path (_word_boundary_splits + @assert length(ranges)==length(polys) + subprep) is unchanged, and test_fracture.jl's order-exact rebuilt == original still asserts it.
• Scope call — no coverage LOST in the golden relocation: tick-loop determinism is genuinely tested in test_draw.jl:18-21 (two draw! of the same evolved state → equal chars+fg, after a real 10-tick loop) plus multi-tick state evolution in test_game.jl; fracture glyph-preservation stays in test_fracture.jl; the new static golden is deterministic (seed 38, no wall-clock), SHA-256 over the canonical encoding, and read+compared against frame60.sha256. Sound regression anchor.
• +3 scene assertions non-tautological (test_golden.jl:46-48): length(g.asteroids)==2, ship_visible(g), and count(!=(' '), buf.chars) > 200 are all real computed properties of the composed buffer; the >200 is a meaningful regression floor against the 4176-cell frame (a packer regression that emptied the blobs drops below it).

Resolved since last round

• RERASTER_EVERY dead constant removed (ee56b8a).

[jowch]

Review — round 3

Re-review of head 3123c29 (README.md + draw.jl only; no behavior change). All three round-2 items are properly resolved, the golden frame + checksum are untouched, and I ran the suite to a real green. Approved.

Resolved since last round

• (was Blocking) README.md stale scene — fixed. 0 matches for 120×40 / four-shard / explosion / beam hit; the snapshot paragraph (README.md:58-63) now accurately describes the pinned hero (116×36: dominant shape-packed text-mass + smaller intact receding drifter upper-right + hunting ship, closed ┌─ d:… v:… ─┐ callouts with connector leaders, motion trails, thrust plume). No longer self-contradicts the 116×36 line at :49.
• (was Nit 1) dead _callout_cells + "overprint scorer" comments — deleted; 0 remaining refs to _callout_cells / scorer. The now-unused buf_h param was dropped from _callout_layout (draw.jl:98) and its sole caller updated (:118). draw.jl parses clean.
• (was Nit 2) overstated non-overlap claim — reworded honestly in both the helper comment (draw.jl:47-51) and the draw! docstring (:200-204): non-overlap is "z-order + scene composition," with decorations (trails/leader/plume/beam) empty-guarded and prose/callout/hull/border drawn unconditionally in deliberate layer order.

Verified

• Golden untouched since 537c62f; checksum b934327… unchanged.
• Full suite green: AsteroidTUI | 91 91 (35.2s) — ran Pkg.test() myself from the demo env, not a log read.

[jowch]

Review — round 4

Re-review of head 1592047 (game-loop refactor + headless smoke test). I ran the suite from disk myself (not a log read). The suite is RED — 104 passed, 1 errored — and the new smoke test correctly caught a real bug: run_game crashes against the installed Tachikoma 2.1.0, so julia run.jl does not actually run. Blocking. The refactor and the rest of the test are excellent; details below.

Blocking

1. examples/asteroid_tui/src/render_tachikoma.jl:79 — run_game errors at Terminal construction. It calls TK.Terminal(; size = TK.Rect(0, 0, width, height)), but Tachikoma 2.1.0's keyword constructor (~/.julia/packages/Tachikoma/vrBon/src/terminal.jl:74-76) does:

   sz = something(size, terminal_size())
   rect = Rect(1, 1, sz.cols, sz.rows)   # expects .cols/.rows

   A Rect has fields x,y,width,height (no .cols/.rows), so this throws FieldError: type Tachikoma.Rect has no field 'cols'. The size kwarg expects the (; cols, rows) NamedTuple shape that terminal_size() returns, not a Rect. Result: the "run_game itself runs headless" test (test/test_gameloop.jl:111-118) errors, and julia run.jl throws immediately at boot — the game never enters the loop.
   Fix: term = TK.Terminal(; size = (cols = width, rows = height)) (and verify the TK.Buffer(TK.Rect(0,0,width,height)) call at :82 is correct for 2.1.0 — Buffer(::Rect) exists, so that one is fine). Then the suite goes green at 105/105.

   This test did its job — it's the first thing to ever actually execute run_game, and it found that the interactive entry point was never runnable. Good catch by the test; it just can't be reported as passing until the fix lands.

Non-blocking note (after the fix)

• Even once the Terminal constructs, _poll_input/_present are still no-op stubs (render_tachikoma.jl:94-104, returning Input()/nothing), and run.jl calls run_game() with no max_frames. So interactive julia run.jl will be an infinite loop that reads no keys and renders nothing visible — by design, this is the documented TTY/bring-up residue. Worth stating precisely so the milestone claim is "the loop machinery + sim + buffer-drain run headlessly, and run_game loops bounded without crashing (once the Rect fix lands)," not "the interactive game is playable."

Verified PASS

• Refactor preserves behavior, single-sourced loop: run_game builds TTY-backed poll/present/pace and drives the SAME game_loop! (render_tachikoma.jl:51-63, 76-89) — not a parallel copy. step_frame! = tick!+draw!. Confirmed.
• The 6 headless sub-tests are non-tautological and would fail on a loop crash (one did): scripted full-vocabulary 120-frame run validates the CellBuffer every frame via the present callback + asserts frames==120, tick_count==120, in-bounds invariants (test_gameloop.jl:29-59); no-input idle 90 (:61-73); quit-path early-stop frames==10 not max (:75-85); entity-evolution-under-motion (:87-99); real Tachikoma drain_to_tachikoma! (:101-109). These exercise input dispatch / tick / draw / drain / collision-detection under motion; a mid-run crash or OOB fails immediately. (They don't assert a fracture/respawn fires — that's a smoke test by design; order-exact fracture preservation stays in test_fracture.jl.)
• TTY-only residue correctly scoped & documented: raw-mode keypress (_poll_input), escape write (_present), wall-clock pacing, visible blink/overlay — documented at render_tachikoma.jl:11-15, 91-93.
• Golden unchanged: frame60.txt byte-identical since 3123c29; git hash-object = d6acd634d0cd658840055878802e7506ce040bfc; checksum b934327a…. The refactor did not shift the static render.
• Note: the diff since round 3 also pulled a main merge (C2 shape_pack, house-style doc) — already merged via #25, outside #E's review scope.

[jowch]

Review — round 5

Re-review of head 4b765e3 (impl-asteroid's real playable #E). I ran the suite from disk (real exit code), read the full delta, and verified the Tachikoma 2.1.0 API assumptions — including the TTY-only key path the tests can't reach. Everything checks out. Approved. The round-4 blocker is fixed and the headless test is genuine, not weakened.

Resolved since round 4

• (was Blocking) run_game crash + RED suite — fixed. The interactive branch now constructs TK.Terminal(; size = (cols = width, rows = height)) (NamedTuple, render_tachikoma.jl:107), so the FieldError: Rect has no field cols is gone. Bonus: drain_to_tachikoma! now guards every write with TK.in_bounds (:30), fixing a separate set_char! BoundsError render crash (commit 2d2612a).
• Suite genuinely green: AsteroidTUI | 107 107, Pkg.test() EXIT=0 (38.8s, ran it myself — not a log read).

Verified

1. Test is NOT weakened (the crux): the run_game itself runs headless subtest (test_gameloop.jl:111-124) calls the REAL entry point run_game(; width=W, height=H, seed=3, max_frames=60, io=io) — no bypass helper — and asserts g.tick_count == 60 AND position(io) > 0 (real bytes flushed → the genuine boot→loop→_present→draw!→drain→flush path ran headless). The other 6 sub-tests remain non-tautological (full-vocab 120-frame buffer-validated-every-frame, idle-90, quit early-stop frames==10, entity-evolution, real drain).
2. run_game two-mode design is sound (render_tachikoma.jl:97-124): interactive → enter_tui! → poll real keys → ~30fps (sleep(1/30)) → leave_tui! in a finally (terminal restored on quit OR crash); headless → Terminal(; io, size) over an IOBuffer, Input() per frame, no pacing, real _present. Both modes share _run_loop! → game_loop! (single-sourced; present is the real path in both).
3. _poll_input/_present are genuinely implemented, not stubs. _poll_input (:152-180) drains TK.poll_event(0.0005) events, folds KeyEvents into one Input, ignores key_release. I verified against installed Tachikoma 2.1.0: KeyEvent fields are (:key::Symbol, :char::Char, :action::KeyAction), and Tachikoma emits :up/:left/:right/:escape/:ctrl_c (events.jl:162,359-361) + :char/evt.char — so every mapping in _poll_input is correct (keys will actually work at the play-test). _present (:190-196) does the real TK.draw!→reset!→drain→flush on both TTY and IOBuffer.
4. run.jl refuses to start headless: !(stdout isa Base.TTY) → message + exit(1). Verified directly: julia --project run.jl </dev/null → exit 1 (no infinite-loop hang — protects #J CI).
5. Golden unchanged: checksum b934327a…, frame blob git hash-object = d6acd634… — both identical to prior rounds.

Honest scope — what stays TTY-only / human tier-2/3 (NOT headless-green)

Genuinely covered headless: boot, loop, input dispatch, tick!, draw!, drain, _present byte emission, terminal restore-by-construction. Remaining human play-test items: (a) real keystroke→action via raw mode (_poll_input's capture; API verified, but live keys are human-checked), (b) on-screen render appearance on a real terminal, (c) real-time ~30fps feel (sleep(1/30) not exercised headless), (d) visible respawn flash / invuln blink / ? overlay. These are correctly isolated and the appropriate tier.

Nits (non-blocking)

• test_gameloop.jl:3-9 and render_tachikoma.jl:12-15 still describe _present as "no-op present" / "TTY-only, not unit-testable" — stale now that _present runs (and is asserted) headless over an IOBuffer. The per-test comment at :111-118 and the _present docstring (:182-188) are accurate; just reconcile the two file headers so the "what's TTY-only" list doesn't overclaim.