Translate the reference mockup into an implementation spec

[yoelthewhale]

Related issue

Part of #98. Documentation only — no implementation, per the review-first instruction.

What changed

Adds docs/VISUAL_TARGET_SPEC.md, the blueprint for getting from the current UI to the approved 2026-08-21 reference without breaking the progression system underneath it. VISUAL_DIRECTION.md gains one pointer to it.

Two findings drove most of the plan:

Solo has no timer. endsAt is nil for Solo and timeLeft is always 0. The reference's TIME 1:28 widget is a mockup artifact, not a feature to build. The only Solo loss condition is having no legal move. Recorded explicitly so nobody implements UI against a system that does not exist.

The results breakdown mostly already has its data. resultSummary carries score, best, previous best, coins, XP, lines cleared, highest combo, and next-unlock text — so most of the reference's panel can ship immediately. "Stage reached" needs one server line. "Base score" and "combo bonus" need real score attribution on the server (score is one running total today), and "time bonus" needs a timer that doesn't exist. Those are called out as new systems rather than quietly built.

Notable decisions in the spec

• Phasing is reordered. The HUD must be extracted out of BlockBlastClient.client.luau before any large HUD code lands — it sits at 198/200 locals and that is exactly how [Critical] GameServer.server.luau exceeds Luau's 200-local-register limit and fails to compile #96 happened. That extraction is flagged as the highest-risk step and wants its own behaviour-neutral PR.
• The identity/flavor/energy model is restated repeatedly, because the reference shows one flavor at low energy and is easy to misread as "make the game permanently pink." Tokens carrying meaning (ink, danger, success, disabled, rank metals) stay stable; tokens carrying mood move with flavor and energy.
• Twelve PNG assets requested, deliberately excluding anything containing text, numbers, or layout — nothing that must recolour per flavor or reflow on a phone gets baked into an image.
• Gameplay findings are analysis only, split into facts verified in code and hypotheses needing playtesting. Notably: sudden death and garbage are Battle-only, so they are ruled out as Solo death causes.

How I tested it

• Tested in Roblox Studio — not applicable, docs only; and no Studio exists in this environment.
• Ran the validation commands below

Validation

• stylua src — unaffected, no src/ changes
• selene src, lune run scripts/run-tests.luau, rojo build — no src/ change, CI covers them

Risks or notes for the reviewer

None to the code — this touches no src/ file.

Three decisions in §13 genuinely need you, and the plan branches on them:

1. The timer. Drop it from the design (recommended), add a timed mode, or show elapsed time instead?
2. Results breakdown. Is score attribution on the server worth it, or ship the simpler modal from existing data?
3. Chrome and energy. Should the chassis heat up on a hot streak, or stay stable as it is now?

Also worth flagging: nothing in the current visual work has been seen rendered. Every phase in this plan assumes a Studio pass before the next builds on it.

---

Generated by Claude Code