clone

a browser grid puzzle game where you push words around to rewrite the rules of each level

main
miau-is-true / openspec / changes / add-proof-title-fitting / design.md
design.md 3.3K source

Context

The design review recorded in docs/design-inbox.md and the current "Proof titles never truncate" section of docs/design.md require authored words to remain visible. The title is currently rendered inside a fixed HUD region, so a long title can collide with the step counter or clip at the mobile edge.

Decisions

Use measured owning regions

Each scene computes the title region from its actual geometry. In the Proof HUD, the region begins after the [NN] number tile and ends before the step counter, with a 16px inset on both sides. INDEX and Win derive equivalent regions from their own settled layout. Text measurement uses the existing font/Pretext-compatible measurement path and never changes cell size or grid coordinates.

Shrink, then wrap, never ellipsize

Start at 22px for the Proof HUD and reduce one pixel at a time to a 16px floor while testing the full title on one line. If the title still exceeds the measured width, wrap only at word boundaries into at most two lines. The renderer must retain the authored words and must not add …, silently drop a word, or split a word to force a fit.

On a narrow viewport, a two-line overflow is an exceptional layout path. The title receives the full band from the title's left inset to the right inset and is fitted at 16px into up to three lines. The compact step counter moves into the subline row: PROOF NN OF NN is left aligned and STEPS 02 is right aligned on that same row. The 40px HUD-to-board clearance remains mandatory. The loader rejects titles over 64 characters with Titles can be at most 64 characters so they fit on phones, so authored titles cannot exceed this mobile layout contract. The W11 note for titles over 32 characters remains a nonblocking authoring recommendation.

Preserve the HUD-to-board contract

When the Proof title takes two or three lines, the PROOF NN OF NN subline and board origin move down as one measured group. In the exceptional narrow layout, the compact STEPS 02 counter shares the subline row. The board retains at least 40px of clear space below the HUD. The board cell size and authored coordinates remain unchanged; only the available vertical presentation region is recomputed.

Keep motion and reduced motion deterministic

Title fitting is settled geometry. Existing title type/drop, INDEX banner type, Win stamp, slow-motion clock, and reduced-motion behavior continue to consume the fitted lines. Reduced motion shows both final lines immediately. No fitting decision may delay input or alter pointer hit rectangles.

Risks and mitigations

  • A narrow title region can create an unexpected two- or three-line title. Test the exact desktop and 390x844 mobile widths and return measured line geometry.
  • A board shift can collide with the footer or ledger. Add layout assertions for the 40px gap and bottom safe region.
  • Different scenes may drift into different wrapping behavior. Share a pure fit helper and test its output directly before wiring each renderer.

Non-goals

  • Changing title copy, sentence case, level IDs, or authoring data.
  • Changing the >32-character W11 guidance semantics; the 64-character loader ceiling is part of this presentation contract.
  • Changing Pretext's grid placement or simulation coordinates.
  • Changing navigation, pointer hit testing, or scene transition timing.