Skip to content

ritmo-devtools layout: audit a game's page for broken layout at each screen size - #235

Open
SandroMaglione wants to merge 6 commits into
mainfrom
claude/project-thread-misyri
Open

SandroMaglione wants to merge 6 commits into
mainfrom
claude/project-thread-misyri

Conversation

@SandroMaglione

Copy link
Copy Markdown
Member

Requested by Sandro · project thread

What

ritmo-devtools layout is a sibling of ritmo-devtools keyboard. It uses the same route file and the same Chromium. It opens each screen at several screen sizes and reports what is broken in the layout the player sees. It measures the laid-out page (text line rects, hit tests, CDP safe-area insets, Chromium layout-shift entries), not pictures.

Errors (exit 1):

  • overlap
  • cut-text
  • off-screen
  • safe-area
  • small-target
  • layout-shift
  • never-settled

Warnings (never fail):

  • truncated-text (an ellipsis or line clamp says the cut is meant)
  • scroll-edge (a control half hidden at a scroller's edge)
  • everything that breaks only in the longer-text pass (every text about 40% longer)

A route can allow a finding by check and selector, on the route or on one screen. The summary counts what it allowed. --screenshots <dir> saves each screen with numbered boxes, red for errors and amber for warnings. --json prints the report.

Default viewports (a route can list its own):

Viewport Size Notes
Small phone, landscape 667x375
iPhone, landscape 844x390 with insets
iPhone, portrait 390x844 with insets
Desktop 1280x800

Other changes:

  • Touch.actions (ritmo-browser) now leaves a reader on its target, under Symbol.for("@typeonce/ritmo-browser/Touch.layout"). The audit uses it to check canvas-drawn touch buttons: overlap with the page, between buttons, safe area, size.
  • The route and the page opening are shared between the two walks (internal/route.ts, internal/pageOpen.ts).
  • A route can now use a type step, and a click looks in an open menu first.

Rules added to avoid false alarms

These came from the Phase 1 prototype and from the runs below:

  • A control that draws nothing, such as a transparent touch area over the stage, is not an overlap or a cut.
  • A layer that covers the lower thing is not an overlap: something behind a scrim, or a badge inside its card.
  • A control under the whole of another is a backdrop, not an overlap: "tap anywhere", a clickable panel.
  • A control that covers the whole safe area is not judged for safe-area; its text still is.
  • A target whose centre another layer takes is behind that layer, not small.
  • A Touch layout with no button that takes a tap (a menu is over the game) is skipped. Its buttons are judged by their circles.
  • Measurements use the configured screen size, not innerWidth, which widens on mobile when content overflows.
  • Body overflow propagated to the viewport is handled, and so is overflow clipping along the containing-block chain.

Run on reference games

spirit-call, 12 screens × 3 landscape viewports, minTarget: 42: 55 errors and 31 warnings, all real by measurement.

Area Finding
Round buttons (Close, Settings, Change party) 40×50 px, under 42
Chests 29–36 px wide
Quest rows and rank tabs 39–40 px tall
Lineup name button 22 px tall
Touch "ultimate" 41 px on the small phone
Touch "dash" 4 px into the home bar
Warnings Practice card names cut by an ellipsis; "Rank 3" and the roster half hidden at scroll edges; home's right column goes off screen or into the notch with 40% longer text

The prototype's false alarms no longer appear: the invisible rotate-stage control, the control under the pause scrim, and the scaled 44-unit targets.

website town demo (/play/town/): 2 errors, both real.

  • The D-pad's left button reaches 25 px into the notch on a sideways iPhone.
  • Its down button reaches 4 px into the home bar when upright.

One false alarm on the full-page "Play" start button is fixed by the backdrop rules above, with a fixture.

Verify

  • pnpm typecheck, pnpm lint, pnpm test-types, pnpm check-examples, and pnpm test (172 files, 2015 tests) all pass.
  • pnpm pack:check passes.
  • pnpm --dir website build passes.
  • 13 layout tests with a fixture for each check, 4 route tests, and a Touch reader test.
  • Changesets:
    • devtools: minor
    • browser: patch, for the Touch reader
    • ritmo: patch, for the UI playbook's check line

Generated by Claude Code

The layout audit reads the same route file as the keyboard walk and reaches
screens the same way, so the route parser and the code that opens a screen
move out of keyboardWalk.ts. The route gains a type step (to fill a name
field on the way to a screen) and the layout audit's fields (viewports,
minTarget, allow), which the keyboard walk ignores.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HendNejwwEtfv3nfMtbBwn
The Touch buttons are drawn on the canvas, so a page audit cannot see them.
While attached, the target carries a function returning the layout at its
current size (under a Symbol.for key), and dispose() removes it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HendNejwwEtfv3nfMtbBwn
Opens each screen of the route in Chromium at each viewport (phones held
both ways, with an iPhone's notch and home bar, and a desktop by default)
and reports what is broken in the layout the player sees. Errors fail the
run: overlap, cut-text, off-screen, safe-area, small-target, layout-shift,
never-settled. Warnings never fail, because a game may mean them:
truncated-text (an ellipsis or clamp), scroll-edge, and what breaks only
with every text 40% longer. A route's allow leaves out what the game means.

The rules come from a prototype run on spirit-call: a control that draws
nothing (a touch area over the stage) is not an overlap, something behind a
scrim is not under the scrim's text, a box that spans the screen cuts at the
screen's edge, items in a scrolling area are judged by it, and a tap area
is measured by hit tests so a ::after extension counts. Touch buttons are
read from the target Touch.actions marks.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HendNejwwEtfv3nfMtbBwn
…vered layouts; docs and changesets

A Touch layout under a menu takes no tap, so its buttons are not in play
and are left out rather than reported as covered. Route clicks look in an
open menu first, as a player would.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HendNejwwEtfv3nfMtbBwn
The website's town demo starts from a "Play" button that covers the
whole page: it reached into the notch and lay under the other controls,
which is what it is for. A control over the whole safe area is not
judged by safe-area, and one under the whole of another is its backdrop.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HendNejwwEtfv3nfMtbBwn

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants