# Test screens, aspect ratios and active states

The app owns its layout. Hackemist provides viewport information, preview tools and measurements; it cannot safely rearrange arbitrary uploaded controls. A CSS viewport is measured in logical pixels. A phone with a 1080 × 2400 physical panel may expose approximately 360 × 800 CSS pixels at device pixel ratio 3. Test CSS size and DPR separately; declaring a 1920-pixel canvas is not responsive layout.

## Manual Studio workflow

Save the draft, choose **Run draft**, then open **Local performance tools** in the player. The **Screen and performance tools** panel offers phone 16:9, 20:9 and 21:9 in both orientations, short landscape, tablets, 1920 × 1080, 2048 × 1080 cinema 2K, 2560 × 1440 QHD, 2520 × 1080 ultrawide, and 3840 × 2160 UHD 4K. Custom Width/Height and Rotate preserve the running frame and app state. Reset returns to the normal player size. Closing the tools keeps the selected preview so the panel does not consume the working area.

The iframe receives the selected **CSS layout size** and is scaled only for viewing inside the creator's display. This does not emulate phone hardware, browser chrome, safe-area hardware, touch capabilities or a different DPR. Use player zoom to inspect details. Use a real phone, browser device tools, or the local matrix helper for mobile/touch/DPR emulation. SDK `hackemist:resize` reports the logical width/height, available width/height, display scale, orientation, fullscreen and `preview` state. Use logical dimensions for CSS/canvas layout, not the outer monitor's physical resolution.

Open each meaningful menu, gameplay state, pause screen, result, dialog, active edit and expanded control panel. Choose **Inspect current screen**. The local report identifies overflow, covered or overlapping DOM controls, controls below 24 CSS pixels, and collisions inside one declared `data-hackemist-required-ui` HUD/action bar. Aim for about 44 CSS pixels for primary touch actions, with `flex-shrink: 0`, reserved layout space and wrapping/reflow where needed. Inspect intentional overlays yourself. Canvas-drawn buttons, text contrast and multi-finger input need their own tests; DOM geometry cannot identify their semantic hit areas. A limited scan is reported explicitly.

`await Hackemist.diagnostics.layout()` offers the same on-demand measurement in supported connected browser sessions. It returns bounded geometry/counts, not field values, text, account contents or resource URLs. Nothing is automatically uploaded. The helper is fetched only when requested; ordinary play gains no measurement loop.

## MCP workflow and the local helper

Run these checks in the coding agent's local execution environment, without GitHub Actions. Follow the [required local release checks](/docs/agent-authentication.md#required-checks-before-publishing); do not create workflows, dispatch jobs or push code to trigger this matrix.

1. Read `hosting_info.layout_testing`, `hackemist://docs/app-layout` and this resource (`hackemist://docs/layout-testing`). Call **`project_layout_plan`** with the owned project ID and current draft version. Optional `target_ids` selects catalog presets. The response is `client_layout_required`, `accepted:false`, `tested:false`; it starts no browser, upload, launch, save, version or server job.
2. Save only `layout_plan` as `layout-plan.json`. Download every `local_tools.helper_files` entry into one tools folder. This extends the existing local capture kit with `creator_layout.mjs`, `layout_targets.js`, `layout_targets.json` and `layout-measure.mjs`. Keep the kit together. Node 22+ and Playwright are required; layout-only checks do **not** run FFmpeg or encode media.
3. Replace the default Startup-only scenario with actions/assertions for real implemented states. Add custom viewports if needed, within the returned configurable local budgets. Use synthetic test text. Never put credentials, private saves or production account tokens into a plan.
4. Run the helper against the finished static build, using a **new** output directory outside that build. Include the returned `helper_arguments` (especially the current plan-byte allowance):

```sh
node creator_layout.mjs --build /path/to/dist --plan /path/to/layout-plan.json --output /path/to/new-report --max-plan-bytes 1048576 --browser /absolute/path/to/chrome
```

5. Inspect `layout-report.html`, its JSON and any requested screenshots. Each scenario starts in a fresh synthetic local session for each mobile/touch/DPR profile, then resizes the same running state through its targets. Phone/tablet catalog presets enable mobile layout and touch capabilities; custom targets can specify `is_mobile` and `has_touch`. The report records actual touch availability and the coarse-pointer media query. `wait_for:"playable"` waits for `Hackemist.markReady()`. Deliberately selecting `"document"` provides weaker document-load evidence and is recorded. A clamped or mismatched actual viewport/DPR never receives a passing result. Incomplete execution writes `layout-incomplete.json`, not a completed passing report.
6. Fix failures and confirmed defects in the source, rerun affected checks into a new folder against the exact release build, and review the new report and screenshots. Repeat until the required checks pass; stop before publishing when they fail, cannot run, are incomplete or remain unreviewed. Real safe areas, touch/keyboard behavior, Safari/Android performance, authenticated save/reload, external backends and real peers remain separate checks. Keep honest device/orientation metadata. Local evidence does not replace the normal release checklist or independently trusted publication checks.

The browser uses checked local build files and ephemeral SDK state. There is no HTTP listener, existing browser profile, external HTTP/WebSocket connection or live WebRTC/WebTransport. Source files, accounts and existing outputs are not changed. The helper shares the recorder's path/network sandbox and the publication checker's DOM measurement. Large matrices stay on the creator's machine; the server stores no per-frame data.

Set up the tools folder as an ES module package (`npm init -y`, then `npm pkg set type=module`) and install Playwright there (`npm install --save-dev playwright@1.62.0`), or use your existing compatible module workspace. Use `--browser` for an existing Chrome executable; otherwise install the matching browser with `npx playwright install chromium`. Keep this tools folder outside the app build. The helper kit is tested from an independent folder as well as from this repository.

## Example state plan

Keep the project/version, limits and other fields returned by the tool. A scenario may contain safe CSS-selector actions (`click`, `fill`, `select`, `wait_for`), keyboard actions (`key`, `key_down`, `key_up`) and bounded `wait` milliseconds. Arbitrary scripts, network URLs and host commands are not actions. Assertions check visibility, an input value or contained text without recording their values in the result:

```json
{
  "name": "An edit survives rotation and wide-screen resizing",
  "actions": [{"type":"click","selector":"#edit"},{"type":"fill","selector":"#title","value":"Keep my edit"}],
  "assertions": [{"selector":"#title","visible":true,"value":"Keep my edit"}]
}
```

Set `screenshots:true` for actual PNG evidence. Default plans test a matrix of sizes, not every hidden feature. A passing geometry count does not prove that a game was played or a multiplayer match synchronized.

## Efficiency, limits and release checks

Admin → **Limits and capacity** exposes preview dimension/pixel budgets, controls inspected, matrix target/action counts, plan bytes and local browser timeout. These are saved operator settings with no additional product ceilings; browser/Node numeric, timer, viewport and hardware limits still apply. The native browser millisecond timer uses a signed 32-bit representation, shown in the catalog. New plans include the current values and helper arguments. Recreate a plan after changing them. Larger local budgets consume the creator's device resources, not additional Suite gameplay workers. Manual presets are choices, not an aspect-ratio allowlist.

Desktop publication includes both 1440 × 900 and **1920 × 1080**. Required phones/tablets and TV retain their bounded shared server checks. Current strict checks reject positively overlapping actions in the same declared HUD/action bar, alongside existing overflow/clipping/navigation failures. Other covered, small or overlapping controls produce a contextual review warning, avoiding a false guarantee about intentional overlays. The broader QHD/4K/aspect-ratio/DPR/state matrix is explicit local QA, keeping the server's normal maximum of eight startup/layout loads unchanged.

Newly requested default media plans can use 1080p for one of their desktop scenes. The mixed-device plan still has eight screenshots; existing stored media is preserved and is not regenerated automatically.

For graphics, size the renderer to its **content container**, reserve HUD/control space, update projection and hit coordinates after resizing, and choose an explicit on-device resolution/quality policy. A 4K screen does not require reflowing text in physical framebuffer pixels or always allocating the largest DPR buffer. Preserve active edits, focus and game state through rotation and layout transitions.