S3-088: Complete localization, accessibility, and touch controls

Parent and ownership

Parent epic: https://github.com/stacksjs/the-settlers-iii-remake/issues/13 Source owner: stacksjs/the-settlers-iii-remake. Master roadmap: https://github.com/stacksjs/the-settlers-iii-remake/issues/4.

Problem and observable result

Preserve original terminology and commands. Provide readable scaling and keyboard focus. Adapt touch selection and incidental motion preferences.

The current application is a browser prototype. Passing the Riverlands campaign does not establish original-game or native parity. This issue is complete only when its stated behavior has retained evidence.

Evidence and interfaces

Shared stx controls read player views and issue commands. Browser/native render adapters consume the same projection, assets, animation state, and input coordinates. Sound follows actual events.

• https://github.com/JakeSteam/settlers/blob/8426388935b436e65b0697ac401c4247ab097364/en/in_menu/menu.htm
• https://andrewsteele.me.uk/technology/game_manuals/the_settlers_iii.pdf

Pin the inspected revisions and fixture hashes in the implementation evidence. Original-game observations govern rules and timing. JSettlers is implementation evidence, not an authoritative balance specification. Unknown values remain explicitly unverified.

Acceptance criteria

• Preserve original terminology and commands.
• Provide readable scaling and keyboard focus.
• Adapt touch selection and incidental motion preferences.
• The visible result agrees with the underlying simulation or platform state, including failure paths.
• Tests exercise the maintained public interface and retain reproducible fixtures or execution receipts.

Test matrix

• Exercise keyboard-only and touch workflows.
• Verify localized layouts and reduced-motion settings.
• Exercise invalid input, cancellation or interruption, and repeated execution where this interface permits them.
• Verify determinism/conservation for simulation changes and resource ownership/disposal for platform changes.
• Run owning-repository lint, relevant type checks and tests. Capture actual native output for native capability claims.

Scope constraints

Implement this behavior as a complete verifiable slice. Do not silently expand into adjacent tickets or substitute simplified gameplay. Keep the shared TypeScript simulation, shared stx signals, and ts-css conventions. Native gameplay and HUD must not depend on a WebView. HomeOS reuse must not introduce a kernel dependency into the game. Existing unrelated edits and authored guidance must be preserved.

Blocked by

• https://github.com/stacksjs/the-settlers-iii-remake/issues/86
• https://github.com/stacksjs/the-settlers-iii-remake/issues/87
• https://github.com/stacksjs/the-settlers-iii-remake/issues/88
• https://github.com/stacksjs/the-settlers-iii-remake/issues/89

Upstream release and adoption

Application behavior belongs here. If a reproduction identifies a framework defect, repair and release its owning source first, update Stacks where affected, then install the verified packages here.

No node_modules edits, copied runtimes, generated-source string patches, fabricated globals, successful no-op implementations, or skipped release gates. Push tested conventional commits as Chris to the owning origin/main without coauthor trailers or force pushes.

Completion evidence

• Implementation commits and relevant upstream issue links.
• Exact checks and results, fixture hashes, and screenshots/native execution evidence where applicable.
• Published package versions, downstream lockfile identity, and release receipts when affected.
• Remaining limitations stated explicitly. Partial work does not close this issue.

Regular browser QA found a short-viewport layout defect at 812 by 375. The document grows to 650 pixels, and the playfield runs from y134 to y650. Its vertical centre is y392, outside the visible viewport; the retained capture cuts off the lower castle and world. The original HUD itself ends at y375, so its scaling and the world container disagree.

The current .game-shell rule in resources/views/index.stx sets min-height:650px alongside height:100dvh. The next UI correction should make the world fit the actual available height and retain the HUD's intended geometry, scrolling, focus and input coordinates. Verify short landscape and portrait viewports with real resize and game controls, plus the existing control-frame checks.

The reproduction used the normal production server and installed browser driver, with no console, request or collection errors. Original-media screenshot evidence remains private. This is an ongoing UI QA finding; the broader accessibility/touch issue remains open.

Browser resize correction is on main at 1033cfa2, followed by the inherited STX CLI alias correction at 18aa81f8.

The game renderer now keeps the same world point at the centre of the view when its canvas changes size. Hiding and showing the map preserves its last visible geometry. Both defects were reproduced before correction in the actual production browser game. The retained regression exercises the real ResizeObserver and Canvas 2D output: all 36,864 sampled centre channels stay identical at three sizes and through a hide/show transition. The final raster was inspected locally.

The committed receipt identifies the reproductions, source files and checks. Lint, app/tools/template types, production build, all 242 application tests, the 58-step browser campaign and original control-frame checks passed. The new resize regression is included in CI. Both exact-source CI and main CI passed.

This completes the browser resize slice. Localization, complete touch controls, remaining keyboard/accessibility acceptance and native behavior are still outstanding, so S3-088 remains open. Browser playability remains the current priority before mobile and desktop.

Web-first continuation: fixed stale thief selection after Escape, numbered troop recall, restoring a checkpoint and drawing a replacement troop rectangle. Each case was reproduced in the real browser before its controller fix. Source commit: https://github.com/stacksjs/the-settlers-iii-remake/commit/ac7b8b9613437cb53efc8ff92c2309be43ae5531 .

Local acceptance: 33 browser steps, no console or failed-request errors; actual staffed sawmill production and save/reload passed; 242 unit tests passed with 22,471 assertions; lint and application/tools/template and Buddy type checks passed. The regression sends DOM pointer events and a DOM Digit1 keyboard event plus native Escape. It does not establish physical drag/pointer-capture or touch acceptance.

Exact source CI is running: https://github.com/stacksjs/the-settlers-iii-remake/actions/runs/40164827948 . Main integration waits for that full run. Two local campaign attempts lost CDP; a separate run with native Chrome stderr diagnostics passed the full 58-step campaign. These attempts are retained separately. Receipt: https://github.com/stacksjs/the-settlers-iii-remake/blob/ac7b8b9613437cb53efc8ff92c2309be43ae5531/docs/roadmap/receipts/browser-selection-2026-10-24.json .

This is control correctness evidence. Full localization, touch, native gameplay and original Gold Edition acceptance remain open.

Main integration completed by normal fast-forward push as Chris without coauthors. Main CI is now fully green: https://github.com/stacksjs/the-settlers-iii-remake/actions/runs/40165565794 . The source CI original browser artifact12588026987 was independently downloaded: SHA256 bdebc59615c5d1fe10ec7c4eb36816ee4363bd10c20336bfff409ed60d30d38f and ZIP CRC passed. Its actual JSON reports retain58 campaign,33 selection,19 production,5 resize and1 checkpoint steps, all with zero console and network failures.

Fixed a confirmed desktop guide accessibility gap: at 1280x720 the guide extended outside its map and clipped the remaining instructions/close button. The maintained control-frame regression failed on the original UI at step 12, then passed after a source fix.

The guide now stays within the map, scrolls vertically, exposes a named keyboard-focusable region and returns focus to Guide when closed. Four production Chrome profiles (1280x720,1280x850,1440x960,320x568) passed 18 steps each, including native End scrolling, close-button containment and launcher-focus restoration, with no console or network failures. Local checks:242 unit tests/22471 assertions, lint 0 errors/0 warnings, application/tools/STX and Buddy typechecks, production build.

The receipt is docs/roadmap/receipts/browser-guide-containment-2026-10-25.json. Main CI remains required; this is one usability correction and does not close the broader localization/accessibility/touch issue or establish original-game parity. Raster bytes remain local pending redistribution evidence.

Source: 4a625e2.

The complete main CI 40173839361 passed on 4a625e2. The original hosted artifact 12591053732 was downloaded intact:13822 bytes, GitHub and local SHA256 39c5ae9d10a2b1313bd4f5711321cb9a4ff4078b3c5a88402b8701a4500c26ab, ZIP CRC passed. Its actual reports independently confirm 18guide/control-frame steps at all 4 viewports,58 campaign,19 production,33 selection,36 working-area,5 resize and 1 checkpoint step, without console or network errors. The broader issue remains open.

Pushed two source corrections in ed19489, authored and committed as Chris without coauthors.

• Map instructions now follow the actual cursor and current tool whenever the view updates. Selecting a building, restoring a game, completing a pointer working-area action and cancelling a mode no longer leave the previous instruction attached to the canvas. Pioneer, geologist and troop controls announce their actual action. Unchanged labels are not repeatedly written.
• Keyboard placement no longer stops at square radius 13. The shared engine search preserves the previous square-ring and tie order, checks each map tile at most once, and delegates legality to the existing placement contract. It reports an actual exhausted search instead of suggesting that an occupied previous cursor is a valid site.

The old search failed a real public-interface fixture with a legal site at radius 18. The corrected search finds it and its ordinary build command is accepted; corner, ownership, no-site and read-only checks pass. In the actual played settlement, selecting Small residence immediately chose tile 59,59 from the castle at 45,45. Enter placed it without any manual cursor relocation. Construction finished and population rose from 38 to 44.

The expanded browser scenario verifies 57 steps, including real pointer completion, focus, immediate instruction changes, Escape, specialist and troop modes. The full local suite passes 313 browser steps with zero recorded console, request or collection errors. All 248 unit tests with 22,523 assertions, app/tools/STX types, lint and production build pass. A separate native-input CUA check confirms the completed working-area action immediately announces inspection.

Committed correction and execution receipt. Issue 90 remains open for the complete localization, touch, reduced-motion and native acceptance. These checks do not establish original Gold Edition rules or native game presentation.

Final main CI is successful on exact source ed194896a7128a0f2a4027bde69f558ddd2cbdfb. Independently downloaded the original diagnostics artifact 12596993813 (16,026 bytes), matched GitHub SHA-256 e5d9e7a04ae43f7e33693b52dedb12fac3a258fdc7af4def978433aa15928dad, verified every ZIP CRC, and confirmed all 313 successful browser steps with zero recorded console errors, failed requests or collection errors.

Corrected the short-viewport layout in the game source. The world and original control frame now use the same available height. At 812x375, the world ends at the visible bottom of the screen instead of extending to 650 pixels. Narrow production figures and labels stay within the panel; the caption and dispatch message no longer overlap. Larger layouts keep their existing text flow and source-art geometry.

Local checks passed for six layouts, including keyboard panel/guide scrolling and focus restoration, plus the campaign, production and real canvas-resize gates: 190 successful browser steps and no console/request/collection errors. Lint, application/tools/STX types and production build also passed. The final preview was checked with the original tutorial and normal save/restore.

The full CI run is running. This is partial progress here; localization, complete touch target sizing and native accessibility remain open.

The complete CI run passed on the published UI correction. The original diagnostic artifact was downloaded and matched GitHub's checksum and every ZIP CRC. Its reports confirm all 16 suites and 546 browser steps, six layout profiles, both terrain display scales, the real ten-minute battle and save/reload, with no console/request/collection errors. The initial archive-transfer timeout and bounded recovery correction are tracked separately in #221.

The six-viewport control layout checks remain green in the latest complete browser run, including the short desktop and narrow production-table cases. The original download recovery that previously interrupted those checks is now complete in #221. Broader touch, localization and native controls acceptance remains open.