core2026/docs/frontend-legacy-parity.md

Frontend legacy parity

This document records the reusable browser fixture and the visual contracts that are enforced while the PHP frontend is moved to the Vue applications. The workspace-level docs/ref-core2026-mapping.md remains the source of truth for the end-to-end PHP-to-core2026 mapping.

Canonical browser fixture

tools/frontend-legacy-parity/fixtures/canonical.ts contains deterministic, non-secret gateway, session, map, and hall-of-fame data. The fixture uses a synthetic ga_ game access token so the game router guard follows the same authenticated path as a real session without contacting a live database.

The test suite intercepts only the tRPC operations required by each screen and fails on unknown operations. It also serves the checked-out reference image tree instead of replacing images with layout-neutral placeholders. public-gaps.spec.ts adds bounded fixtures for nation betting and the public NPC list, including mutations and recoverable API failures. tournament-betting.spec.ts covers the separate tournament and tournament betting routes, including a recoverable failed bet. reference-rankings.mjs records the authenticated PHP 명장일람 and public 명예의 전당 computed DOM without embedding the reference password. battleSimulator.spec.ts covers the authenticated simulator with and without an owned general. battleSimulatorRef.spec.ts can additionally exercise the live reference page when its URL, user, and ignored password file are supplied.

Run the suite from the core2026 repository root:

pnpm test:e2e:frontend-legacy

When another worktree occupies the default ports, set FRONTEND_PARITY_GATEWAY_PORT, FRONTEND_PARITY_GAME_PORT, and FRONTEND_PARITY_GAME_URL. FRONTEND_PARITY_ARTIFACT_DIR retains the tournament and betting screenshots.

Run the focused simulator fixture with:

pnpm --filter game-frontend test:e2e:battle-simulator

The optional reference check uses REF_BATTLE_SIM_URL, REF_USER_ID, and REF_USER_PASSWORD_FILE. The password is read inside the test and is never written to screenshots or reports.

The suite starts both applications at their public prefixes:

• gateway: http://127.0.0.1:15100/gateway/
• game: http://127.0.0.1:15102/che/

Chromium uses the same locale, timezone, device scale factor, and color scheme for desktop and mobile checks. Tests assert geometry, computed typography and texture URLs before checking hover, focus, menu, login mutation, session storage, route guards, and image loading.

Enforced contracts

Screen	Ref entry point	Current automated contract
gateway login/status	index.php	450/700px desktop widths, mobile collapse, Pretendard title, real login mutation/session storage, actual seasonal map asset
gateway account	i_entrance/user_info.php	550px × minimum 575px panel, 14px Pretendard, three legacy textures, success and API-error password flows
gateway OAuth join	oauth_kakao/join.php	700px centered registration card, Kakao exchange/register success, retained-input API error, hover/focus
game login hand-off	unauthenticated hwe/index.php redirect	/che/login delegates to /gateway/
troop	hwe/v_troop.php	existing app/game-frontend/e2e/troop.spec.ts desktop/mobile geometry and interaction suite
current city	hwe/b_currentCity.php	ref-specific 16px Times New Roman, 1000px summary/1024px general tables, 400px selector, 64px icon, nation title color, force summary, actor/spy/admin redaction, and map-click query navigation
best general	hwe/a_bestGeneral.php	authenticated 500/1000px ranking and unique-item grids, user/NPC switch, 100/64px cell/image geometry, title/button computed styles, retained-data API error
hall of fame	hwe/a_hallOfFame.php	public 500/1000px container, 100px ranking cells, 64px natural image, title/button/select computed styles, scenario switch and retained-data API error
yearbook	hwe/v_history.php	1000px 700+300 desktop grid, 500px stacked grid, month navigation, legacy textures, success and API-error flows
inheritance	hwe/v_inheritPoint.php	1000px 3-column desktop and 500px stacked layout, walnut/green textures, Pretendard 14px, scenario unique selector, buff purchase success and retained-input API error
nation betting	hwe/v_nationBetting.php	1000px/6-column desktop and 500px/3-column mobile grids, picked card style, payout table, success and retained-form error
public NPC list	hwe/a_npcList.php	1000px 12-column table with Chromium-expanded legacy widths, NPC color, eight sorts, retained table/sort after API error
survey	hwe/v_vote.php, hwe/ts/PageVote.vue	1000/500px fixed container, blue title/green table textures, list/detail/results/comments, selection/focus/hover, submit and retained-selection API error
nation personnel	hwe/b_myBossInfo.php	fixed 1000px document at both viewports, chief icon columns, officer/permission/city/kick controls, role redaction
nation finance	hwe/v_nationStratFinan.php	1000/500px at the legacy 940px breakpoint, exact diplomacy grid, policy controls, role gating and failed-mutation rollback
battle simulator	hwe/battle_simulator.php	centered 1000px desktop document, 500px responsive stacking, independent/current presets, owned-general import gating, fixed-seed result/logs, retained input after API error
NPC policy	hwe/v_NPCControl.php	1000/500px form and priority-list geometry, walnut/green textures, dynamic zero hints, drag/focus/tooltip, successful save and permission failures
tournament	hwe/b_tournament.php	fixed 2000px canvas, 16×125px bracket, eight 250px group tables, walnut texture, 1024px overflow, hover/focus
tournament betting	hwe/b_betting.php	fixed 1120px canvas, 16×70px candidates, four 280px rank tables, exact title/button geometry, retained selection on error

The global game baseline is black, white, Pretendard 14px. Legacy texture helpers intentionally follow common.orig.css: bg0 is walnut, bg1 is green, and bg2 is blue. Shared PanelCard uses the same walnut body and green header so screens that still use the common component no longer inherit the discarded Galmuri/parchment visual system.

The survey fixture covers both the poll list and an open detail. Its result rows are visible before the current general votes when the poll uses the legacy-compatible after_vote mode. The mutation fixture covers voting and comment submission, while the error fixture confirms that a failed vote keeps the selected radio option so the user can retry.

Route coverage rule

Adding or changing a frontend route requires:

1. a verified ref entry-point mapping in the workspace mapping document;
2. deterministic tRPC fixture data for the visible state;
3. desktop and 500px/mobile geometry and computed-style assertions;
4. actual Chromium interaction checks for every visible interactive state;
5. natural image dimensions and object-fit checks where images affect layout.

Pixel snapshots may be added after these structural assertions pass. Dynamic regions must not be hidden merely to make a pixel threshold pass.

To refresh the PHP ranking evidence after building the ignored reference webpack assets, run:

REF_RANKING_URL=http://127.0.0.1:3400/sam/ \
REF_RANKING_PASSWORD_FILE=/path/to/ignored/user1_password \
REF_RANKING_ARTIFACT_DIR=/path/to/ignored/artifacts \
node tools/frontend-legacy-parity/reference-rankings.mjs

The nation office suite can be run independently:

pnpm --filter @sammo-ts/game-frontend test:e2e:nation-offices

Set PLAYWRIGHT_FRONTEND_PORT when the default 15120 port is occupied. For reference collection, tools/frontend-legacy-parity/reference-nation-offices.mjs records desktop/500px computed DOM and screenshots from the PHP service without changing its product code.

The NPC policy suite and its reference collector can be run independently:

PLAYWRIGHT_FRONTEND_PORT=15126 \
  pnpm --filter @sammo-ts/game-frontend test:e2e:npc-policy

REF_PARITY_USER=refuser1 \
REF_PARITY_PASSWORD_FILE=/path/to/password-file \
REF_PARITY_BASE_URL=http://127.0.0.1:3400/sam/ \
  node tools/frontend-legacy-parity/reference-npc-policy.mjs

The collector writes desktop and 500px screenshots plus computed DOM JSON only when REF_PARITY_ARTIFACT_DIR is set. It requires an existing reference general owned by the supplied account and never accepts a password on the command line.

The current-city reference can be collected independently with tools/frontend-legacy-parity/reference-current-city.mjs. It requires REF_PARITY_PASSWORD_FILE and accepts REF_PARITY_URL, REF_PARITY_USER, and REF_PARITY_ARTIFACT_DIR; the password is read from the ignored secret file and is never written to the artifact. The matching core fixture is app/game-frontend/e2e/inGameInfo.spec.ts, which writes its computed DOM and screenshot only when CITY_PARITY_ARTIFACT_DIR is set.

For a review run that also writes full-page screenshots, create an ignored artifact directory and set FRONTEND_PARITY_ARTIFACT_DIR before invoking the suite. The ordinary CI run does not write screenshots after successful tests.