Saboteur ▪ Reversed Tetris — Game Design Spec

1. Background and Goals

Concept. Saboteur is a reversed Tetris: the player is the dealer, choosing which tetromino falls next, while an AI opponent — the Stacker — plays NES-style Tetris in real time. The player wins by forcing the Stacker to top out, as fast as possible. Where the original asks "survive as long as you can," the reversal asks "kill as fast as you can."

Design lineage. Candidate selection for the series applied four filters, which this design passes: (1) the player's core verb is one causal step from the outcome (a dealt piece immediately becomes the Stacker's problem); (2) outcomes are attributable to player decisions (visible fumbles, pressure-scaled mistakes); (3) no dominant strategy exists (free dealing is provably solved — alternating S/Z forces a loss against any opponent — so dealing is constrained by cooldowns); (4) the opponent is a local heuristic, no network, no remote AI.

Goals (observable outcomes).

• A new player understands the inversion within seconds: "I pick the pieces; he suffers them."
• A new player can eventually clear level 1 with practice; an expert climbs a 29-level ladder over many sessions.
• Every loss of momentum is traceable to the player's own deals or hesitations — never to unreadable AI randomness.
• The game runs entirely offline as one HTML file, sibling in structure and fidelity to minelayer and ghost-squad.

2. Product Contract

3. Scope

P0 — required for the complete game P0

• NES-faithful well, pieces, colors, and panel layout (FR-01)
• 29-level ladder with sequential unlock and per-level best kill score (FR-02)
• Match loop on the deal-ahead pipeline: pick the next piece while the current one falls (FR-03)
• Dealing controls with per-piece cooldowns counted in beats (FR-04)
• Timeout punishment: Stacker's Choice (FR-05)
• The Stacker bot: heuristic placement, visible human-like manipulation, pressure-scaled fumbles (FR-06)
• Scoring and end-of-level attribution stats (FR-08)
• Synthesized NES-style audio with persistent mute (FR-09)

P1 — valuable, not blocking P1

• Kill replay (watch the final collapse)
• Practice mode: replay any unlocked level with a visible fumble-probability readout
• Touch controls for tablets

Explicitly excluded OUT

• Hold slot and hard drop for the Stacker (a hold makes the bot nearly unstarvable and kills cooldown-denial strategy)
• Any invented win/lose resource — see the rejected design below
• Online features of any kind; multiplayer
• Procedural piece generation beyond the dealing rules (no 7-bag: the player is the generator)

4. Game Model

4.1 Objects

4.2 Match state machine (canonical)

There is no LOSS state by design (§2). The only terminal states of PLAY are CLEARED and player-initiated quit.

5. Functional Requirements

FR-01NES-faithful presentation

• Layout: replicate the NES Tetris screen composition: well center-left; right panel showing NEXT, SCORE (player's kill score), BEST, LEVEL, and the dealer's piece bar (FR-04) in place of the original's statistics column. Series convention applies: strict fidelity to the reference; no invented decorative elements, backgrounds, or effects. On narrow viewports (≤720px) the composition reflows rather than zooms: the well moves to the top and the panel sits full-width beneath it (see FR-04 · Responsive).
• Pieces: classic shapes and colors (I cyan, O yellow, T purple, S green, Z red, J blue, L orange).
• Motion: gravity per the level configuration (SR-3); pieces spawn, fall, and lock per NES timing conventions.
• Exceptions: viewport smaller than the playfield → proportional scaling, never cropping; aspect ratio preserved.

FR-02Level ladder and progression

• Structure: 29 levels, each a complete fixed-speed match. Level 1 unlocked at first launch; clearing level N unlocks N+1. All unlocked levels are freely replayable from LEVEL SELECT.
• Why 29 (product judgment): a deliberate callback to the NES kill screen — level 29, the original's legendary terminal level where gravity outruns human hands. The symmetry is the series signature: in the original, level 29 is where the player dies; here, level 29 is where the Stacker must die. Twenty-nine hand-meaningful rungs also beat ninety-nine curve-generated ones: every level is a distinct beat, not filler.
• Why a ladder (product judgment): difficulty must advance only after success. In the original's endless ramp, speed rises while a struggling player is still failing — punishing them further — and past kill-screen speed the bot dies regardless of deals, rewarding passivity. Fixed-speed levels invert neither curve: progression is gated by skill, not patience.
• Display: LEVEL SELECT shows the 1–29 ladder, lock state, and per-level best kill score. Current level shown on the HUD during play.
• Persistence: unlocked levels and per-level bests in localStorage; blocked storage → session-only, silently.

FR-03Match loop (deal-ahead pipeline)

FR-04Dealing controls and cooldowns

Purpose. One verb, one resource: pick pieces, manage cooldowns. Cooldowns exist because free dealing is mathematically solved — alternating S/Z forces a top-out against any possible opponent — so S and Z carry the longest cooldowns.

• Input: click a piece card in the dealer bar, tap it on a touchscreen, or press 1–7 (order I O T S Z J L). Only off-cooldown pieces are pickable. The dealer bar is laid out as a 3×3 numpad grid (7 8 9 / 4 5 6 / 1 2 3): each piece sits at the cell matching its key, so on-screen position equals physical numpad position (keys 8 and 9 are inert placeholders). Mobile taps use touch-action: manipulation plus a touchend fast path for zero-delay selection.
• Cooldown rule: canonical in SR-2. Dealt piece goes on cooldown; all cooldowns tick down one per beat.
• Feedback: piece cards show shape, name, key, and cooldown countdown; on-cooldown cards are dimmed and unclickable; the dealt card flashes white; a Stacker's Choice card flashes red with a "STACKER'S CHOICE" banner (see demo below).
• Changing a pick: re-picking within the same window replaces the pending deal; the replaced piece's cooldown is refunded (implemented: cooldowns apply only when the deal finalizes at lock, so re-picking is inherently free — favors experimentation).
• Exceptions: input on a cooling piece is ignored (no queue); input after the window closes applies to the next window.
• Responsive & touch (mobile): two layouts, chosen by matchMedia('(max-width:720px)'). Desktop keeps the fixed 500×512 NES landscape stage, uniformly scaled via transform: scale(); only screens narrower than 300px or shorter than 380px are rejected. Mobile reflows instead (scaling is zoom, not layout — it would shrink the side panel into an unusable sliver): the stage becomes a vertical column with the well canvas on top and the panel full-width beneath it, secondary chrome is compacted, the deal bar keeps its 3×3 numpad order with ≥46px tap targets, and the level grid becomes auto-fill. The well's height is computed in JS to fit the space above the panel, so nothing is clipped. Touch devices (detected via ontouchstart / maxTouchPoints) get an html.is-touch class that swaps all instruction copy from keyboard to touch and reveals on-screen controls: a ⏸ pause button during play, and RESUME/QUIT buttons on the pause overlay and NEXT/RETRY/LEVEL SELECT buttons on the summary overlay. The title overlay is tappable to advance.

Interactive demo — FR-04 deal bar / FR-05 timeout

The bar auto-advances one beat every few seconds. Click a piece (or press 1–7) to deal it; watch S and Z carry long cooldowns. Let a beat expire and the Stacker serves himself. Demo values are shortened; game values are SR-2/SR-3 tuning.

FR-05Timeout punishment — Stacker's Choice

• Rule: when the deal window closes with no pick, the Stacker's Choice is dealt. The choice quality is level-scaled (SR-3): at low levels it is mostly random (the bot can get a bad piece on timeout — forgiving for beginners), at high levels it converges to the heuristic's favorite (the bot reliably gets its best piece — timeout is punishing, the player MUST deal actively).
• Why level-scaled (design update): the original design required the Stacker's Choice to always be the heuristic's favorite, arguing random is worse than the player's worst pick. In practice this made auto-mode immortal at every level (the bot always got its best piece) and the timeout too punishing at L1 (missing one beat gives the bot a perfect piece). The level-scaled model preserves the "timeout is worse than dealing" property at high levels (where choiceQuality ≥ 0.90) while making L1 forgiving (choiceQuality = 0.15 — the bot gets a random piece 85% of the time on timeout).
• Feedback: "STACKER'S CHOICE" banner on the dealt card and beside NEXT; counted in the end-of-level stats (FR-08).
• Dramatic property: at high levels, the punishment hurts most exactly when the Stacker is in trouble — hesitating while winning produces genuine comeback swings. At low levels, the timeout is a gentle nudge, not a free good piece for the bot.

FR-06The Stacker bot

Purpose. A convincing, fallible, fully local opponent. This component carries the design's concentrated risk (§8, R-1): the match is only fun if its mistakes read as caused.

• Placement heuristic (behavior contract): evaluates legal placements with classic board features — aggregate height, holes, bumpiness, well depth — with one-piece lookahead using the NEXT preview. Deterministic scoring; strength differences come from execution, not from dumber evaluation.
• Visible hands: the Stacker does not teleport pieces. It shifts and rotates in discrete steps at a level-scaled rate (SR-3), so manipulation is bounded per beat exactly like a human's. At high levels, gravity outruns physically possible manipulation and forced misdrops occur naturally — the kill-screen flavor of the top ladder.
• Fumbles (injected mistakes): with a context-scaled probability (SR-4) the Stacker locks a clearly suboptimal placement, telegraphed by a brief wobble animation before lock. The wobble is the attribution device: "my deal forced that."
• Line clears: clears are the Stacker healing itself — damage undone, visibly. No meter is needed; the board is the meter.
• Believability limits: acts only on spawn and during its own fall; no reactions to events outside its piece; never exceeds its level's manipulation rate.
• Exceptions: if all placements top out, it locks the least-bad and the match ends — the bot never stalls, freezes, or oscillates.

FR-07Per-level configuration

• Rule: each level fixes gravity and Stacker hand speed per the SR-3 table; both rise together, tuned so the Stacker remains equally competent and the shrinking deal window is the intended difficulty source.
• Display: level number on LEVEL SELECT and HUD; no other per-level UI — like the original, the game doesn't change, your time does.

FR-08Scoring and attribution stats

• Kill score: pieces dealt until top-out (including Stacker's Choice beats); lower is better — golf scoring, mirroring the original's survival score. Best-per-level stored locally; ties broken by shorter wall-clock time (implemented).
• SUMMARY stats (the attribution aids): pieces dealt · forced fumbles · Stacker's Choices gifted · lines the Stacker cleared · time. Every level teaches what your dealing did.
• HUD: current deal count, level, best for level.

FR-09Audio

• Rules: all audio synthesized locally (Web Audio API), NES-flavored: fall tick, deal confirm, cooldown-ready blip, Stacker's Choice sting, fumble wobble cue, line-clear arpeggio (an ominous sound here — inversion of the original's reward), top-out collapse, level-clear jingle. No audio files.
• Control: M mutes; persisted. Engine starts on first user gesture per autoplay policy; fully playable silent.

FR-10Result sharing (community layer)

• Share card: the top-out overlay carries an always-visible SHARE RESULT button (visible on desktop too — sharing is not touch-only). It assembles a plain-text result card: brand line (title_brand + " — " + title_suffix, both localized per language), a hook line with the level and piece count ("topped out the Level N Stacker in N pieces"), the deal history rendered as a row of colored squares matching each piece's NES color (I🟦 O🟨 T🟪 S🟩 Z🟥 J🟫 L🟧, Stacker's Choice beats prefixed with 🔴, capped at 12 symbols with …), and a call-to-action line with the page URL.
• Delivery: shared engine public/shared/share.js. Clicking SHARE RESULT always opens a retro CRT preview modal first — the player sees the exact card before anything leaves the device. From the modal: COPY (clipboard + execCommand legacy fallback + retro toast), native SHARE via the Web Share API sheet where available (a dismissed sheet is not an error), CLOSE. Modal button labels are localized in all 8 languages by the engine's own dictionary. Purely additive: no server, no account, no change to the match loop.
• i18n + tests: share_btn, share_copied, share_hook, share_cta dictionary keys in all 8 languages; card assembly (buildShareCard) is a pure function pinned byte-for-byte by the 05-share test suite.

6. Shared Rules

SR-1 · Beat and timing model (canonical)

A beat = the lifespan of one piece, spawn → lock. The deal window for piece k+1 opens when piece k spawns and closes when it locks. Cooldowns tick per beat, not per second — the whole economy compresses uniformly as levels speed up. Pause freezes beats entirely.

SR-2 · Cooldown rule (canonical)

Each piece type has a cooldown length in beats: S = 6, Z = 6, others = 3 (implemented). Dealing starts that piece's cooldown when the deal finalizes (at the lock that closes the window); every locked piece ticks all cooldowns down by 1. Values are tuning targets, chosen so S/Z denial is a meaningful but not dominant strategy.

Evidence base: cooldowns are anti-degeneracy guardrails, not a piece-value encoding. Brzustowski (1992, Can You Win at Tetris?, UBC) proved single-piece winning strategies exist for all seven tetrominoes — no repeated single piece is ever lethal, so spam alone cannot justify differentiating cooldowns. The only statically-proven lethal pattern is S/Z alternation (Burgiel 1997, How to Lose at Tetris, Mathematical Gazette 81: a hole is forced within 240 pieces against any play). Beyond S/Z, adversarial dealing is rich but unranked (Demaine, Hohenberger, Liben-Nowell 2003, Tetris is Hard, Even to Approximate), and empirical piece-set experiments (Zhang, U. Twente: L+J-only games outscore the full 7-piece game while S/Z-only games collapse immediately) support a binary {S,Z}-vs-rest split with no gradient inside the five. Adversarial-dealer implementations (Bastet, HATETRIS) likewise show piece badness beyond S/Z is board-dependent, not intrinsic. Uniform short cooldowns on the other five are therefore deliberate: reading which piece is worst in context is the player's skill, not a static tax. Sole candidate for a medium tier is O (nasty on ragged boards, harmless on flat ones) — resolved in tuning [TBD].

SR-3 · Level configuration (canonical)

Implemented: gravity is the NES frames-per-row table with level L mapped to NES index L−1 (L29 = 1 f/row); hand speed = clamp(round(50/fpr), 3, 24) actions/s. Once aligned the Stacker soft-drops at ~3× gravity (floor(fpr/3) f/row), keeping L1's deal window ≈ 5 s/beat. All per-level tuning values are smooth breakpoint curves (linear interpolation — no per-band restarts, every level's config is distinct, verified 29/29). Four difficulty levers beyond gravity speed: (1) level-scaled lookahead — 0.0 at L1–5 (bot is purely reactive), 0.75 from L10, ramping to 0.90 across L21–28, reverting to 0.75 at L29 so the kill screen stays physics-lethal; (2) level-scaled choice quality — the Stacker's Choice is mostly random at L1 (0.15), rising to 0.95; deliberately never 1.0 (see below); (3) fumble base — 0.35 at L1 tapering smoothly to 0.015 at L28, 0 at L29; (4) clear-miss + danger feedback (see SR-4), implicitly curved through the fumble base. Why choice quality caps at 0.95: at L29 the ⅓ s deal windows mean a human cannot deal at all — the level is auto-mode for a human player, so the 5% random timeout pieces are the margin by which kill-screen physics still kills the bot; benchmark-verified that 1.0 lets it survive 500+ pieces, making L29 unbeatable. Measured lower bound (5-seed avg): auto-mode survives ~137 at L1, 446 at L5, 500+ at L8–L28, ~51 at L29. Measured upper bound: optimal dealer kills L1 in ~44, L10 in ~60, L20 in ~104, L22 in ~126, L28 in ~135, L29 in ~22; 50% optimal kills L1 in ~46, L10 in ~127, wall at L16+; random kills L1 in ~91, wall at L10+. Strategy (withhold I, deal S/Z/J) is rewarded at every level.

SR-4 · Fumble and clear-miss model (canonical)

The bot has two independent fallibility mechanisms, both gated by board danger (danger = stackDanger(board), ranging 0 on an empty board to 1 at the top):

1. Clear-miss (attacks the bot's line-clear healing): when danger ≥ 0.3 and the best placement clears lines, the bot has a clearMissP = fumbleBase × 0.5 × danger (capped at 0.20) chance to instead pick the best non-clearing placement (within 20 points of best). This specifically prevents the bot from healing via line clears when under pressure, creating a death spiral: bad pieces → stack grows → clear-miss → no heal → stack grows more → death. On an empty board (danger ≈ 0), clear-miss never triggers, so auto-mode (good pieces, low stack) is unaffected.

2. Fumble (suboptimal placement): p = fumbleBase × (0.7 + 0.8 × danger), capped at 0.40. A fumble locks a placement chosen uniformly (seeded) among those scoring 10–50 points below the heuristic's best — clearly suboptimal but never braindead. Always preceded by a 16-frame wobble cue.

Comeback cap: the Stacker never fumbles or clear-misses away a saving line clear (clears > 0 and danger ≥ 0.7) more than once per match — comebacks are earned, not gifted.

Why two mechanisms: the flat fumble alone could not overcome the bot's line-clear healing (199 lines cleared in 500 auto-mode pieces). The clear-miss specifically targets the healing, creating the death-spiral feedback loop that makes the player's bad deals stick. The fumble adds visible, telegraphed mistakes on top. Together they create a bot that is competent with good pieces (auto-mode survives) but vulnerable to bad dealing (player kills in ~35 pieces at L1).

SR-5 · Pause and focus

Esc toggles PAUSED; beats, gravity, cooldowns, and the Stacker freeze. Window blur or tab hidden forces PAUSED. PAUSED dims the well and shows controls; no state is lost.

SR-6 · Persistence

Stored in localStorage: unlocked level count, per-level best kill score, mute preference, last played level. Storage unavailable → session-only, no error surfaced.

7. Exceptions and Boundaries

8. Open Questions and Risks

• R-1 · The concentrated risk (bot legibility): the entire design rides on the Stacker's manipulation and fumbles reading as human. Implemented as: Dellacherie-feature heuristic (landing height, eroded cells, row/column transitions, holes, wells) with one-piece lookahead weighted 0.75 (averaged over all 7 pieces when NEXT is not yet dealt — the bot plans at spawn, seeing the preview exactly as a human would); one discrete rotate/shift action per hand tick; wobble-telegraphed fumbles. Validated by headless scenario tests and browser E2E (see §9); human watch-test still recommended during tuning.
• R-2 · I-starvation may be a dominant strategy: adversarial-dealer precedents (Bastet, HATETRIS) show that withholding the I piece — not merely dealing S/Z — is a top weapon, and under SR-2 the player can simply never deal I at zero cost. If playtesting confirms I-drought dominates, add a drought-breaker rule [TBD candidate: after K beats with no I dealt, the Stacker receives a free I — "the well provides"], accepting one small invented rule to protect the dealing game. Not implemented — pending playtest evidence.
• Rotation system (resolved): NES rotation states, no wall kicks, CW-only bot rotation — replicated per §4.1.
• Cooldown lengths (SR-2), gravity/hand-speed curves (SR-3), fumble formula (SR-4) — values implemented as documented above; tuning validated by the upper/lower-bound benchmarks in §9.4.
• [TBD] Final title: "Saboteur" is the working title; alternatives that evoke dealing/tetrominoes welcome.

9. Testing and Difficulty Verification

The game ships with three test layers: headless unit tests (33 scenarios), a browser-level E2E sweep (11 scenarios), and a difficulty-benchmarking methodology used during tuning. All tests load the real index.html in-memory — the game file on disk is never modified.

9.1 Test harness infra

• Headless harness (tests/saboteur/harness.js): reads the real index.html, stubs browser APIs (DOM, canvas 2D, Web Audio, rAF), injects a window.__S hook that exposes game internals (state, board, cur, cooldowns, stats, save, bot target, fumble flag) plus control functions (pick, setBoard, setCell, forceTarget, pieceScores, choiceFor, etc.) for deterministic scenario construction. The hook is shared with the E2E driver so the two test layers never drift.
• Runner (tests/saboteur/run.js): tiny per-file-isolation runner. Each test file gets a fresh module registry so the game's global state reloads cleanly. Run: node tests/saboteur/run.js.
• E2E driver (tests/saboteur/e2e.js): launches the system's headless Edge/Chrome via the DevTools protocol directly (zero npm dependencies — uses Node ≥ 22's built-in fetch/WebSocket). Serves index.html through a local HTTP server that injects the same __S hook in memory at serve time. Drives real OS-level keyboard events (Input.dispatchKeyEvent), asserts on real rendered canvas pixels (getImageData), real localStorage, and real rAF timing. Run: node tests/saboteur/e2e.js (requires unsandboxed execution — launches a real browser process).

9.2 Headless unit tests (33 scenarios) P0

9.3 Browser-level E2E sweep (11 scenarios) P0

End-to-end coverage of the full player journey in a real headless Chromium browser over the DevTools protocol. Each scenario drives real keyboard events and asserts on real rendered pixels, real localStorage, and real rAF timing. Screenshots saved to tests/saboteur/e2e-shots/ on each run.

9.4 Difficulty-verification methodology

Two complementary benchmarks establish the lower bound and upper bound of each level's difficulty. Both were used during tuning to validate the fumble model (SR-4) and level curve (SR-3). The benchmarks are not shipped as test files — they are throwaway scripts run during tuning — but the methodology is canonical and should be re-run whenever difficulty parameters change.

Lower bound: auto-mode survival (can the Stacker hold its own?)

Motivation (analogous to Ghost Squad's auto-mode test): in auto mode the player never deals, so every piece is the Stacker's Choice. The choice quality is level-scaled (SR-3): at L1 only 15% of timeout pieces are the heuristic's favorite, so the bot gets mostly random pieces — it is competent but not immortal. If the bot dies too quickly even with good pieces, it is too weak to be fun. If it survives forever at every level, the timeout is too rewarding.

Method: boot a match, never call pick(), step every frame until state === 'summary' or a piece cap (500) is reached. Record survival length, lines cleared, and fumble count.

Acceptance criterion: the Stacker survives ≥ 500 pieces at L8+ (high choice quality — bot gets near-optimal pieces). At L1–5, auto-mode survival is expected to be shorter (137–446) because the bot gets mostly random pieces — this is by design, not a bug. If auto-mode kills the bot at L8+, the fumble model is too aggressive. If auto-mode survives 500+ at L1, the choice quality is too high. This test caught: (1) v1 flat model with 0.28 base → 41% auto-mode fumble rate, bot died in 68 pieces; (2) v2 piece-quality-aware model → auto-mode immortal at every level, optimal couldn't kill; (3) the Stacker's Choice always being the best piece → auto-mode immortal regardless of fumble model. The v3 model (level-scaled choice quality + flat fumble + clear-miss + level-scaled lookahead) is the first to satisfy both bounds.

Upper bound: adversarial-dealer pieces-to-kill (can the player win, and does skill matter?)

Motivation: if even optimal play can't kill the bot, the level is too hard. If random dealing wins as easily as optimal, skill doesn't matter. The gap between optimal and random is the "skill ladder" — the space where the player's choices matter.

Method: boot a match, each beat deal the piece the heuristic scores worst (for optimal) or a mix of worst/random (for skill-mixed), step one beat, repeat until top-out or cap. Run 3–5 seeds per level.

Acceptance criterion: optimal dealing kills the bot at every level (including L29, which is physics-bound at ~20 pieces). At L1, optimal kills in ~35, 50%-optimal in ~41, even random in ~68 — the level is beatable by casual players. At L10+, only skilled (70%+) dealing wins. If optimal can't kill, either the fumble rate is too low, the clear-miss is too weak, or the lookahead is too strong for that level.

Measured values (current tuning, 3-seed avg): auto-mode survives 500+ at every level except L29 (~20). Optimal dealer: L1 ≈ 35, L5 ≈ 40, L10 ≈ 35, L20 ≈ 81, L29 ≈ 20. 50%-optimal: L1 ≈ 41, L5 ≈ 64, L10 ≈ 126, L20 ≈ 200+ (can't beat). Random: L1 ≈ 68, L5 ≈ 190, L10+ can't beat. The skill gap at L1 is 35 (optimal) vs 68 (random) — a 2× speed advantage for skilled play. Re-run both benchmarks whenever fumbleBase, lookahead, the clear-miss formula, or the fumble-severity band (10–50 below best) changes.

9.5 Tuning changes from initial implementation

10. Internationalization

Scope. The game UI is localized through the series' shared engine public/shared/i18n.js (loaded as an external, offline-safe script) plus a per-page dictionary public/shared/lang/saboteur.js. No network, no runtime dependencies.

Supported languages (8). en (English), zh (中文), es (Español), de (Deutsch), fr (Français), ru (Русский), ja (日本語), ko (한국어). English is stored in the dictionary like any other language (the en block, first in the file) and doubles as the default.

Detection order. On boot, RG_I18N.init('saboteur') resolves the language as: (1) the localStorage key rg.lang (a user override, written by the switcher); (2) the browser languages — navigator.languages, then navigator.language, matched by exact id or 2-letter prefix (e.g. zh-CN → zh); (3) en. A fixed top-right <select> switcher (injected by the engine) lets the player change language at any time; the choice persists in rg.lang.

Two-string pattern. Static markup carries data-i18n="saboteur.<key>"; the engine swaps in the active translation — English included, from the dictionary's en block — and captures the element's original innerHTML once as a last-resort fallback (inline <kbd>/<br>/entities are preserved). Dynamic, JS-built strings use the page-local helper T('saboteur.<key>', 'English default'), which the engine resolves against the saboteur dictionary namespace. On a language change the page re-renders its JS-built DOM (the deal-bar cards, the level-select grid, and the canvas NEXT "?" glyph) via an RG_I18N.onChange(...) listener. Numeric HUD cells (#vLevel, #vScore, #sDealt, …) are never localized — only their surrounding labels are. The game title is a standalone field: title_brand is the first key of every language block (it is the title-screen wordmark), and the document <title> (doc_title) is derived from it as title_brand + " — " + descriptor in the dictionary's GAME TITLE section, so renaming the game in one place follows into the browser tab.

Harness safety. The deterministic headless harness (tests/saboteur/harness.js) extracts and evals only the single bare inline <script> block; the engine and dictionary are loaded as external <script src> tags and are therefore invisible to it. Inside that block window.RG_I18N is undefined, so the guarded boot is skipped and T() returns its English default — the game (and all value assertions) behave exactly as before localization.