docs: analyze legacy lines 2001-2500

README.md

@@ -6,7 +6,7 @@ This branch is an analysis-only bootstrap for a Mainline-first modernization of
 
 The preserved 8,401-line Mainline source must be analyzed sequentially, in evidence-backed batches, before runtime work begins. All behavior-critical shortened symbols must be resolved and all batches must be complete before any public Lua API, runtime module, modern TOC, packaging, or release work is added.
 
-Batches 01–04 (lines 1–2,000) are documented. The remaining batches are scheduled but not analyzed.
+Batches 01–05 (lines 1–2,500) are documented. The remaining batches are scheduled but not analyzed.
 
 ## Goal
 

docs/analysis/batch-schedule.md

@@ -8,7 +8,7 @@ The immutable analysis source is `Legacy/Bejeweled_Mainline.lua` from commit `6f
 | 02 | 0501–1000 | 500 | `lines-0501-1000.md` | complete |
 | 03 | 1001–1500 | 500 | `lines-1001-1500.md` | complete |
 | 04 | 1501–2000 | 500 | `lines-1501-2000.md` | complete |
-| 05 | 2001–2500 | 500 | `lines-2001-2500.md` | pending |
+| 05 | 2001–2500 | 500 | `lines-2001-2500.md` | complete |
 | 06 | 2501–3000 | 500 | `lines-2501-3000.md` | pending |
 | 07 | 3001–3500 | 500 | `lines-3001-3500.md` | pending |
 | 08 | 3501–4000 | 500 | `lines-3501-4000.md` | pending |

docs/analysis/identifier-ledger.md

@@ -396,12 +396,57 @@ The completed `M`, flight loader, rotation helper, and pause helper are resolved
 | `e`,`n`,`o` / `Q` parameters | 1952 | Gem, column, row; coordinates/keys assigned after cleanup (1965–1979). | `gem`, `column`, `row` | resolved | High. | 04–04 | UI/GemPool | None. |
 | `t` / `Q` local | 1953 | Receives each value's type and gates removal of numeric-valued keys (1954–1958). | `valueType` | resolved | High. | 04–04 | UI/GemPool | None. |
 | `n`,`o` / `Q` generic loop | 1954 | Shadow parameters inside loop as key/value; removes numeric values (1955–1958). | `key`, `value` | resolved | High. | 04–04 | UI/GemPool | None. |
-| `Ke` / chunk function | 1984 | Begins board-wide gem transition; continues after 2000. | `startGameOverGemAnimation` | working | Medium: prefix only. | 04–04 | UI/Animations | Complete in batch 05. |
+| `Ke` / chunk function | 1984 | Applies game-over movement/effects and queues every gem (1985–2002). | `startGameOverGemAnimation` | resolved | High: complete body. | 04–05 | UI/Animations | Dispatcher remains ahead. |
 | `n` / `Ke` duplicate preliminary bindings 1–2 | 1985 | Hidden by animator local at 1986. | — | dead | High. | 04–04 | Unassigned | Minifier artifact. |
-| `t` / `Ke` local | 1985 | Receives each gem and mutates animation fields (1989–1999). | `gem` | working | High for prefix. | 04–04 | UI/Animations | Continuation pending. |
-| `n` / `Ke` animator local | 1986 | Aliases animator and receives every gem via `Add` (1999). | `animator` | working | High for prefix. | 04–04 | UI/Animations | Continuation pending. |
+| `t` / `Ke` local | 1985 | Receives/mutates each gem before queueing (1989–2000). | `gem` | resolved | High. | 04–05 | UI/Animations | None. |
+| `n` / `Ke` animator local | 1986 | Receives every grid gem (1999–2002). | `animator` | resolved | High. | 04–05 | UI/Animations | None. |
 | `i`,`e` / `Ke` grid loops | 1987, 1988 | Iterate grid rows/columns and index gem grid (1989). | `row`, `column` | resolved | High. | 04–04 | Engine/Grid | None. |
 
 ## Batch 04 resolution policy
 
 Completed event callbacks and helpers are resolved by full local data flow. Legacy positional API fields remain `working` where modern contracts are unverified. Duplicate declarations and proven-unused callback parameters are `dead`; accidental global writes remain explicit `working`/`unresolved` evidence. `Ke` and its transition-state constants stay working across the batch boundary.
+
+## Batch 05 declarations and scopes
+
+| Legacy identifier / lexical scope | Decl. | Observed interactions | Proposed name | Status | Confidence/evidence | First–last | Target | Open question |
+| --- | ---: | --- | --- | --- | --- | --- | --- | --- |
+| `de` / chunk function | 2004 | Randomly assigns color and optionally avoids initial matches (2005–2057). | `assignRandomGem` | resolved | High: complete body. | 05–05 | Engine/Grid | None. |
+| `t`,`n`,`f`,`i` / `de` parameters | 2004 | Column, row, avoidance flag, skip-reset flag. | `column`,`row`,`avoidMatches`,`skipReset` | resolved | High. | 05–05 | Engine/Grid | None. |
+| `p` / `de` duplicate locals 1–5 | 2005 | Hidden by later bindings or unread. | — | dead | High. | 05–05 | Unassigned | Minifier artifact. |
+| `s`,`c`,`d`,`S`,`e` / `de` locals | 2005 | Match count, safe flag, two scan steps, chosen color (2006–2049). | `matchCount`,`safe`,`xStep`,`yStep`,`color` | resolved | High. | 05–05 | Engine/Grid | None. |
+| `i`,`l` / `de` loops | 2012, 2014, 2020, 2025 | Attempts, pattern, row offset, column offset. | `attempt/pattern`,`rowOffset`,`columnOffset` | resolved | High. | 05–05 | Engine/Grid | None. |
+| `t` / `de` gem local | 2049 | Shadows column after indexing and receives rendered gem. | `gem` | resolved | High. | 05–05 | UI/GemPool | None. |
+| `R` / chunk renderer | 2059 | Shadows type alias; renders normal/hyper/empty gem (2060–2075). | `renderGem` | resolved | High. | 05–05 | UI/GemPool | Earlier reset closure retains old alias. |
+| `t` / renderer parameter | 2059 | Gem/content receiver. | `gem` | resolved | High. | 05–05 | UI/GemPool | None. |
+| `j` / chunk game function | 2077 | Shadows leaderboard merger; initializes/restores game (2078–2245). | `startGame` | resolved | High. | 05–05 | Engine/Grid | Attachment pending. |
+| `l`,`s`,`r` / game parameters | 2077 | Mode, duration, resume flag. | `mode`,`duration`,`resume` | resolved | High. | 05–05 | Engine/Grid | None. |
+| `d`,`i`,`t` / game locals | 2078–2079 | Player name (after dead duplicate), object temporary, game-state alias. | `playerName`,`object`,`gameState` | resolved | High. | 05–05 | Engine/Grid | None. |
+| `t`,`e` / game loops | 2099, 2129–2130, 2184–2192, 2202–2203 | Animation/grid indices. | `index/row/column` | resolved | High. | 05–05 | Engine/Grid, UI/Animations | None. |
+| `n`,`l`,`r` / resume locals | 2199–2201 | Saved state, encoded gem, animator. | `savedState`,`encodedGem`,`animator` | resolved | High. | 05–05 | Core/SavedVariables | None. |
+| `ee` / chunk function | 2247 | Creates power gem/big star and achievement (2248–2264). | `createPowerGem` | resolved | High. | 05–05 | Engine/Matches | None. |
+| `Z` / chunk function | 2266 | Creates hyper gem and achievement (2267–2283). | `createHyperGem` | resolved | High. | 05–05 | Engine/Matches | None. |
+| `t`,`i`,`o` / `ee` and `Z` bindings | 2247–2267 | Gem, forced flag, created result in each helper. | `gem`,`forced`,`created` | resolved | High. | 05–05 | Engine/Matches | None. |
+| `Le` / chunk function | 2285 | Marks directional clear/explosion and queues animation (2286–2300). | `markGemForClear` | resolved | High. | 05–05 | Engine/Matches | Direction enum pending. |
+| `t`,`o` / `Le` parameters | 2285 | Gem and direction; `Ne` selects X. | `gem`,`direction` | resolved | High. | 05–05 | Engine/Matches | None. |
+| `Q` / chunk move finder | 2302 | Shadows reset helper; transactional swaps detect legal match (2303–2347). | `findLegalMove` | resolved | High. | 05–05 | Engine/Matches | Returns one candidate gem. |
+| `e`,`t`,`p` / move loops | 2304–2306 | Row, column, cardinal direction. | `row`,`column`,`direction` | resolved | High. | 05–05 | Engine/Matches | None. |
+| `n`,`i`,`c`,`f`,`d`,`s`,`S`,`l` / move locals | 2303 | Neighbor row/column, swapped gem, validity and four run bounds. | `neighborRow`,`neighborColumn`,`gem`,`valid`,`left`,`right`,`top`,`bottom` | resolved | High. | 05–05 | Engine/Matches | Preliminary duplicate `e` bindings dead. |
+| `e` / `TotalTime` local | 2350 | Accumulates duration text. | `text` | resolved | High. | 05–05 | UI/HUD | None. |
+| `Se` / chunk function | 2384 | Clears current/next selection and selector UI (2385–2401). | `clearSelection` | resolved | High. | 05–05 | Engine/Grid | None. |
+| `t`,`e` / `Se` bindings | 2384–2385 | Next flag and selected gem. | `next`,`gem` | resolved | High. | 05–05 | Engine/Grid | None. |
+| `Me` / chunk function | 2403 | Finalizes game and starts board wipe (2404–2456). | `endGame` | resolved | High. | 05–05 | Engine/Scoring | Summary follows later. |
+| `o`,`t` / `Me` locals | 2404–2405 | Animator and status text. | `animator`,`statusText` | resolved | High. | 05–05 | UI/HUD | None. |
+| `e` / `Me` duplicate/loop bindings | 2423–2429 | Dead duplicate locals; live loops clear saved state. | `column/index` | resolved | High. | 05–05 | Core/SavedVariables | None. |
+| `At` / chunk function | 2458 | Creates positioned layered BackdropTemplate frame (2459–2482). | `createImageFrame` | resolved | High. | 05–05 | UI/GemPool | First parameter unused. |
+| `a`,`o`,`i`,`n`,`t`,`e`,`l` / `At` parameters | 2458 | Unused, X, Y, width, height, parent, overlay flag. | —,`x`,`y`,`width`,`height`,`parent`,`overlay` | working | High except unused first. | 05–05 | UI/GemPool | Identify first argument. |
+| `e` / `At` frame local | 2459 | Shadows parent after initializer; returned frame. | `frame` | resolved | High. | 05–05 | UI/GemPool | None. |
+| `tt` / chunk function | 2484 | Begins gem-frame creation; continues after 2500. | `createGemFrame` | working | High for prefix. | 05–05 | UI/GemPool | Complete in batch 06. |
+| `n`,`i`,`o`,`t`,`e` / `tt` bindings | 2484–2485 | X, Y, parent, color, created frame. | `x`,`y`,`parent`,`color`,`gem` | working | High for prefix. | 05–05 | UI/GemPool | Continue in batch 06. |
+| `t` / `TotalTime` parameter | 2349 | Floored and reduced by day/hour/minute moduli (2351–2375). | `seconds` | resolved | High. | 05–05 | UI/HUD | None. |
+| `o`,`n`,`e`,`t` / `Print` parameters | 2380 | Passed directly to chat-frame message plus RGB values (2381). | `message`,`red`,`green`,`blue` | resolved | High. | 05–05 | UI/HUD | None. |
+| `t`,`e` / `Me` saved-grid loops | 2424–2425 | Row/column indices clearing saved grid. | `row`,`column` | resolved | High. | 05–05 | Core/SavedVariables | None. |
+| `e` / `Me` metadata loop | 2429 | Index clearing saved metadata row. | `index` | resolved | High. | 05–05 | Core/SavedVariables | None. |
+
+## Batch 05 resolution policy
+
+Complete helpers are resolved from full bodies. Same-spelling functions are separate entries because earlier closures retain prior bindings. `tt` and dispatcher-dependent constants remain working.

docs/analysis/lines-2001-2500.md

@@ -0,0 +1,91 @@
+# Batch 05: lines 2001–2500
+
+Source: `Legacy/Bejeweled_Mainline.lua` at Git commit `6faec1c`  
+Physical coverage: lines 2001–2500 inclusive (500 lines)  
+Blank lines: 2003, 2058, 2076, 2246, 2265, 2284, 2301, 2348, 2379, 2383, 2402, 2457, and 2483  
+Status: complete; `Ke` closes at 2002 and `tt` continues into batch 06
+
+## Line-indexed coverage audit
+
+| Lines | Evidence represented |
+| ---: | --- |
+| 2001–2002 | Closes `Ke`: every grid gem was added to the animator. |
+| 2003 | Blank separator. |
+| 2004–2010 | `de(column,row,avoidMatches,skipReset)` chooses random gem type 1–7 and optionally resets/empties target gem. Five duplicate `p` locals are dead. |
+| 2011–2048 | When avoiding matches, tries up to seven colors; scans six offset patterns from `r`, counts matching neighbors within bounds, cycles color when count exceeds one, and stops on a safe color. Nested `i` loop bindings intentionally shadow each other. |
+| 2049–2057 | Assigns chosen contents and gem/shine textures; normal (non-avoidance) calls increment total matched-gem statistic. |
+| 2058 | Blank separator. |
+| 2059–2075 | New chunk function `R(gem)` shadows the earlier `type` alias for later declarations. It renders normal colors, creates hyper gem for contents 9, or hides empty/other texture/glow coordinates. Earlier `Q(resetGem)` retains old `R=type`. |
+| 2076 | Blank separator. |
+| 2077–2098 | New chunk function `j(mode,duration,resume)` shadows leaderboard merger and initializes current-game state/counters, level threshold, mode, splash, and player name. Earlier inbound-sync helper retains old `j`. |
+| 2099–2128 | Drains animator stack from index 1, returning known effect types to big-star, explosion, floating-text, shard, lightwave, or lightning pools; clears parent links/visibility and animation flag. |
+| 2129–2140 | Resets every 8×8 gem via captured old `Q`, clears hyper marker, and updates optional FuBar/Titan current mode. |
+| 2141–2166 | Selects classic/timed stats, initializes maxima/flags/HUD mode/countdown, and handles timed timer stop versus flight-learning immediate state. |
+| 2167–2183 | Hides status/summary/about/skill/options controls, configures Return-to-Game button, sets spawn animation state, resets hint, and reseeds RNG from random plus `GetTime`. |
+| 2184–2195 | Populates board diagonally/triangularly with `de(...,true)` while temporarily clearing each generated contents, ensuring initial colors avoid matches before spawn. |
+| 2196–2218 | Resume branch disables spawning, reads saved grid, restores normal gems, hyper gems, or big-star gems from `<9`, `==9`, or `>9` encodings, renders each via `R`. |
+| 2219–2238 | Restores metadata row, validates signed score, decodes it or uses zero, restores timer/multiplier/bar/text, and updates HUD. |
+| 2239–2245 | Sets `we` according to restored level and unpauses via `T(false)`; closes new-game helper. |
+| 2246 | Blank separator. |
+| 2247–2264 | `ee(gem,forced)` creates hidden queued big star for selected/swapped/forced gem unless exploding, increments power-gem total, checks 100-power achievement, and returns truthy creation marker. |
+| 2265 | Blank separator. |
+| 2266–2283 | `Z(gem,forced)` marks hyper-gem spawn/effect, queues gem, increments hyper total, reports match-5 through `M`, checks 50-hyper achievement, and returns creation marker. |
+| 2284 | Blank separator. |
+| 2285–2300 | `Le(gem,direction)` marks X when direction equals `Ne`, otherwise Y; big-star gems increment explosions; sets animation effect/frame/highlight and returns explosion count. |
+| 2301 | Blank separator. |
+| 2302–2347 | New chunk function `Q()` shadows reset helper and searches for any legal move. It tries each gem against four cardinal neighbors, temporarily swaps nonempty neighbor, expands horizontal/vertical equal-color runs, restores swap, and returns the candidate gem when run length reaches three. Contents 9 is automatically considered viable. |
+| 2348 | Blank separator. |
+| 2349–2378 | `TotalTime(seconds)` formats floored duration into days, hours, minutes, seconds with spaces; zero becomes `0 s`. |
+| 2379 | Blank separator. |
+| 2380–2382 | `Print` delegates four arguments to `DEFAULT_CHAT_FRAME:AddMessage`. |
+| 2383 | Blank separator. |
+| 2384–2401 | `Se(next)` clears current or next selected gem, ends non-hyper effect, hides selector, clears mouse coordinates. |
+| 2402 | Blank separator. |
+| 2403–2419 | `Me` begins game-over: hides/reset hint, marks state, stores last mode, updates optional integrations, and stops timer. |
+| 2420–2436 | Classic path shows/plays no-more-moves and zeroes all saved-state cells/metadata; nonclassic shows/plays time-up. |
+| 2437–2456 | Increments total games, checks 100/1000-game achievements, shows status, deselects both gems, sets game-over animation, calls `Ke`, plays board-wipe, and closes `Me`. |
+| 2457 | Blank separator. |
+| 2458–2482 | `At(unused,x,y,width,height,parent,overlay)` creates `BackdropTemplate` frame, texture/highlight layers, stores position, and returns it. Local frame `e` shadows parent parameter after initializer. |
+| 2483 | Blank separator. |
+| 2484–2500 | `tt(x,y,parent,color)` begins gem-frame creation via animator image, assigns color textures, selector and glow geometry. Function continues in batch 06. |
+
+## Control/data flow and shapes
+
+- Board creation deliberately chooses colors that avoid pre-existing three-in-a-row patterns, then uses the spawn animator to reveal them.
+- New-game initialization drains pooled animation objects by effect type, resets grid/state/HUD, and optionally restores the nine-row signed SavedVariables snapshot documented in batch 04.
+- Lua lexical capture remains critical: renderer `R`, new-game `j`, and move finder `Q` shadow earlier helpers, while previously declared closures retain the old bindings.
+- Legal-move detection is transactional: swap, scan both axes, restore, return candidate. Hyper contents 9 short-circuits viability.
+- Game over clears classic resumable state, updates lifetime game achievements, deselects input, and starts a board-wide wipe.
+- `At` correctly uses `BackdropTemplate`; `tt` constructs layered gem visuals and remains open.
+
+| Object | Proven shape/invariant |
+| --- | --- |
+| Gem contents | 1–7 normal colors, 9 hyper, >9 saved big-star encoding, 0 empty. |
+| Effect pools | Animator owns queues for big stars, explosions, text, shards, lightwaves, and lightning. |
+| Initial grid | 8×8; colors 1–7; avoidance scan uses six patterns from `r`. |
+| Legal move | Candidate swap must yield horizontal or vertical span difference ≥2 (three gems). |
+| Restored metadata | Saved row 9 maps score, threshold, level, moves, maxima, elapsed, multiplier, signed score. |
+
+## WoW API contracts
+
+- `GetTime` contributes to RNG reseeding (2181–2183); deterministic future engine state must not inherit this global randomness without an explicit compatibility decision.
+- Frame/texture calls include `SetTexture`, `SetTexCoord`, pooling visibility, alpha, anchoring, and `CreateFrame(...,"BackdropTemplate")`.
+- `DEFAULT_CHAT_FRAME:AddMessage` is the legacy print target (2380–2382).
+- No `C_Timer`, metadata, animation-group, or compartment API appears.
+
+## Symbol resolutions and forward dependencies
+
+- `de` resolves as random gem assignment, new `R` as gem renderer, new `j` as game initializer/restorer, `ee` as power-gem creator, `Z` as hyper-gem creator, `Le` as clear marker, new `Q` as legal-move finder, `Se` as deselector, and `Me` as game-over transition.
+- `Ke` resolves as board-wipe starter; effect constants remain tied to dispatcher evidence still ahead.
+- Batch 06 must finish `tt`, identify created gem-frame fields, and continue animation/grid ownership.
+- `I` is used as the restored authenticated-score field on current game state, but its concrete later purpose still needs assignment evidence.
+
+## Architecture mapping
+
+- `Engine/Grid.lua`: generation, reset, restore, legal-move search, selection state.
+- `Engine/Matches.lua`: power/hyper creation and directional clear marking.
+- `Engine/Scoring.lua`: new-game counters, restored scoring, lifetime achievements, game over.
+- `Core/SavedVariables.lua`: signed saved-state validation/decoding.
+- `UI/GemPool.lua`: gem rendering and frame construction.
+- `UI/Animations.lua`: pool draining, spawn/wipe effects, floating skill/rank messages.
+- `UI/HUD.lua`: mode setup, status, timers, summaries, duration/chat presentation.

tools/verify-bootstrap.ps1

@@ -133,9 +133,10 @@ Assert-ReportCoverage 'docs/analysis/lines-0001-0500.md' 1 500
 Assert-ReportCoverage 'docs/analysis/lines-0501-1000.md' 501 1000
 Assert-ReportCoverage 'docs/analysis/lines-1001-1500.md' 1001 1500
 Assert-ReportCoverage 'docs/analysis/lines-1501-2000.md' 1501 2000
+Assert-ReportCoverage 'docs/analysis/lines-2001-2500.md' 2001 2500
 
 $lineCount = (Get-Content -LiteralPath 'Legacy/Bejeweled_Mainline.lua').Count
 Assert-True ($lineCount -eq 8401) "Legacy source has $lineCount lines, expected 8401"
 
 Write-Output "Verified: forbidden files absent; legacy and $($assetPaths.Count) asset hashes match $SourceCommit."
-Write-Output "Verified: strict UTF-8 text, exact 8,401-line schedule, and complete batch-01/02/03/04 line coverage."
+Write-Output "Verified: strict UTF-8 text, exact 8,401-line schedule, and complete batch-01/02/03/04/05 line coverage."