Renovating Sudoku

After reading sudokuSPARK.html, sudokuSPARKStyles.css, and the Bingo reference files, here is the analysis before touching anything:

What to preserve entirely:

• All JavaScript logic — loadDemo(), enterValue(), selectValue(), checkCurrentPlacement(), makeBlankBoard(), updateFrequencies(), and all supporting helpers. This code is mature, multi-stage, and tested.
• The 9×9 board HTML structure — the table with its r1–r9 / c1–c9 class system, rightSolid / bottomSolid separators, and faint alternating-group shading. The JS depends on all of these class names for coordinate detection and board rendering.
• The entries table (digit palette: 1–9, E, C, M) — selectValue() targets its cells directly.
• The demo selector form — loadDemo() reads demoMenu by ID.

What to change:

• Replace the legacy <header id="masthead"> (hand-coded float-based nav) with the TNT dark #mainNav Bootstrap navbar pattern
• Add Bootstrap 5.3.3, Font Awesome 6.5, Boogaloo + Inter
• Add tnt-base-styles.css; rewrite sudokuSPARKStyles.css (old file was only masthead/nav rules — dead selectors after the header is replaced)
• Remove the legacy #introFigure (Batman image, float:left, 400px) — it was a decorative sidebar that has no functional role
• Replace div#sudokuPanel (float:left, 400px) with a centered Bootstrap container
• Add a hero section with the einsteinSudoku.jpg background image from the app’s own images/ folder
• Add dark footer, SEO meta block, linkGuard.js
• Add init() function for copyright/date/validateLink wiring (the legacy app had none)
• Create sudokuChatlog.html with the S.P.A.R.K. development log pattern

Three factors distinguish the Sudoku hero palette from Bingo’s:

• Bingo is social and kinetic. It is played in groups, with a caller, under time pressure, in a festive atmosphere. The dark navy→red gradient matched that energy. Sudoku is solitary and cognitive. The player sits down, focuses, and thinks. The atmosphere should signal concentration, not excitement.
• The board’s own palette is green-on-light. The 9×9 grid uses forest green borders (#2e7d32), green-tinted cell backgrounds (#e8f5e9), and off-white alternating groups. The hero gradient ends in forest green so the page reads as one continuous visual environment from top to bottom, not two separate sections.
• Einstein is the right reference. The einsteinSudoku.jpg image in the app’s own images/ folder was chosen by the original developer as a personality reference for the puzzle. Using it as the hero background honors that intent while integrating it into the renovated structure. The dark overlay ensures the white hero text remains readable while keeping the image subtly present.

The gradient chosen: rgba(10, 14, 50, 0.72) → rgba(20, 80, 30, 0.58) — deep navy-to-forest-green, matching the board’s border color exactly.

Complete change inventory for sudokuSPARK.html:

Head section:

• Added Bootstrap 5.3.3, Font Awesome 6.5, Boogaloo + Inter. These were entirely absent from the legacy file, which used only Google Fonts (Lobster + Roboto Condensed) and the local stylesheet.
• Replaced link href="styles/sudokuSPARKStyles.css" with tnt-base-styles.css + sudokuSPARKStyles.css (in that order). The base styles define CSS custom properties that the app styles reference.
• Changed favicon path from images/favicon-32x32.png (local) to ../images/favicon-32x32.png (site level). The local copy was a duplicate; the site-level copy is canonical.
• Updated <title> to use the TNT brand pattern and en-dash entity.
• Added full SEO meta block.
• Added lastUpdate / currentYear script variables.

Legacy header removed:

• The <header id="masthead"> element (float-based, green border-bottom, local nav with Stage 1/2/3 links) was replaced entirely with the TNT dark #mainNav Bootstrap navbar. The stage links in the old nav pointed to files that do not exist in the workspace (sudoku-stg1.html) — the TNT site-wide links are the correct replacement.

Layout restructure:

• Removed div#introFigure (Batman image, float:left). See Design Decision above.
• Removed float:left and fixed 400×400px from #sudokuPanel. The panel is now a fixed 360px block (matching the board width) centered via Bootstrap’s d-flex justify-content-center on the container.
• Added <section id="hero"> with the Einstein background and dark blue-green gradient overlay.
• Added <section id="appSection"> wrapping the centered puzzle.

Board table:

• Reduced board from 400×400px to 360×360px (inline style). At 360px, nine cells at ~40px each fit cleanly with no rounding artifacts. The font-size was adjusted from 2em to 1.8em proportionally.
• Updated green colors from the legacy CSS-named green keyword to the explicit #2e7d32 (forest green). CSS green is actually #008000 — a flat mid-green. #2e7d32 is richer and more legible.
• Updated td.frozen:hover from pink to #fce4ec (a soft rose consistent with the Bootstrap red error vocabulary).
• Updated td.active from lightgreen to #c8e6c9 (the same green-mid token used in the header style).
• Updated td.mark from CSS blue to #1565c0 (a deep material blue that is accessible on the light cell backgrounds).

Entries table and demo form:

• Width updated to 360px (matching the board). Previously 400px.
• Load button styled with var(--tnt-amber) background instead of the unstyled gray default.
• Demo option labels made descriptive: “Demo 1 — Classic” instead of just “Demo 1”. The player now knows what they are loading before they load it.
• Added aria-label to the entries table for screen readers.

JavaScript:

• All game logic is unchanged. Added one new function: init(), called via onload. It sets copyright, last-updated date, and the validate-link localhost detection — the same three tasks every TNT SPARK page needs on load.
• The legacy app had no init() and no onload handler. This meant the copyright span and update span were never populated. Those spans now exist in the footer and are wired correctly.

Footer:

• The legacy app had no footer at all. Added the full TNT dark footer pattern with the same icon set used in Bingo and other SPARK apps.
• Added the Copilot + VS Code credits in the footer paragraph.
• Added validateLink with localhost detection.
• Added linkGuard.js.

Three CSS layers are involved in the Sudoku SPARK edition:

• ../styles/tnt-base-styles.css — shared across all TNT pages. CSS custom properties, #mainNav, #hero structural rules, and the dark footer. Never edited for app-specific changes.
• styles/sudokuSPARKStyles.css — new SPARK app file. Defines the hero background and gradient, the off-white app section background, and the #sudokuPanel fixed-width container. This is the file to edit when the Sudoku app needs visual changes beyond the game table itself.
• Inline <style> in sudokuSPARK.html — intentionally retained. Contains the board table rules, the entries palette styling, and the demo form. These are game-specific; they interact with the JavaScript class system (frozen, active, error, mark). Moving them to an external file is a future clean-up task, not a preliminary change.

The legacy sudokuSPARKStyles.css was overwritten (not preserved) because its contents — the masthead and float-nav rules — matched no elements in the renovated page. There was no reason to keep dead CSS. This is different from the Bingo renovation, where the legacy bingo-styles.css was preserved as a reference because it contained game-relevant rules that had not yet been migrated.

The centering strategy: Bootstrap’s d-flex justify-content-center on the .container, with #sudokuPanel as the single flex child at a fixed 360px width.

Why this approach over alternatives:

• Not mx-auto + text-align: center: The board, entries table, and demo form are all block elements at different natural widths. Text-centering would align inline content but not block children. mx-auto on the panel works but requires an explicit display:block and margin:auto, which is slightly more fragile than flexbox centering.
• Not Bootstrap grid columns: A grid column like col-md-6 offset-md-3 would work at medium widths but produce a wide panel on small screens. The puzzle has a fixed 360px width — it does not need to expand on larger screens. The flex approach centers a fixed-width child regardless of viewport.
• Flexbox on the container, fixed width on the panel: The container centers its flex children horizontally. The panel specifies its own width (360px, matching the board). The board, entries table, and demo form are all block children of the panel — they inherit its 360px width without needing their own width declarations.

The key architectural decision before writing any code: pre-compute all steps, then replay. Two approaches were considered:

• Real-time solving: run the algorithm asynchronously, pausing at each step with await. Pause/Resume requires suspending a running generator; Step requires advancing it one yield at a time. Complex to implement correctly.
• Pre-compute then replay: run the solver instantly on a board copy, collecting all steps into an array. Then animate the step array at a user-controlled speed. Pause/Resume is clearTimeout / setTimeout. Step is stepIndex++. Reset is stepIndex = 0. Each control is two lines of code.

The pre-compute approach was chosen. The student sees identical behavior either way; the implementation is dramatically simpler, and the log panel can show the complete reasoning before the animation even starts.

Three strategies, applied in priority order:

1. Naked Single — a cell with exactly one legal candidate digit. The log entry shows which constraint (row / col / box) eliminates each of the other eight digits, so the deduction is fully transparent.
2. Hidden Single — a digit that can go in only one cell within a row, column, or box. The cell may have multiple candidates; the constraint is on the digit’s placement within the group, not on the cell’s options.
3. Backtracking (MRV heuristic) — when logic is exhausted, the solver picks the empty cell with the fewest candidates (Minimum Remaining Values), tries each one recursively, and records both the trial and any backtrack as distinct steps.

Three board colors were designed, aligned with the strategies the solver actually implements:

• Blue (#bbdefb) — Naked Single. Certain, logical, direct. The digit was forced by elimination.
• Purple (#d8b4fe) — Hidden Single. More sophisticated: the cell had multiple candidates, but within its group only one cell could hold this digit.
• Amber (#fff8e1) — Backtrack trial. Tentative. May be erased if the branch fails.

Each step object carries a sub property ('naked' or 'hidden') so applyStep() can decide which class to add to the cell, and the log panel can color-code each entry to match the board.

Bug 1: CSS replacement failure. The previous session had replaced the ai-placed CSS rule with ai-naked and ai-hidden using replace_string_in_file. The oldString included the comment block that uses box-drawing characters (─ U+2500) as decorative horizontal lines. The exact bytes in the file did not match the characters in the replacement call — the tool reported success for the file (because other replacements in the same call succeeded), but this particular replacement silently did nothing.

Result: ai-placed CSS still existed. ai-naked and ai-hidden CSS rules had never been added. The JavaScript was correctly calling classList.add('ai-naked') and classList.add('ai-hidden') on cells, but those classes had no CSS rules — so no color appeared.

Fix: read the actual file content to get the exact characters, then add the two missing rules directly.

Bug 2: The property that was designed but never written. After CSS Bug 1 was fixed, the applyStep() function correctly chose between ai-naked and ai-hidden based on step.sub === 'hidden'. The nakedSingle() function now correctly set sub: 'naked' on each step it pushed. But the hiddenSingle() function had three separate push calls — one for row singles, one for column singles, one for box singles — and none of the three included sub: 'hidden'.

This meant step.sub was undefined for every hidden single step. The condition step.sub === 'hidden' evaluated to false, so classList.add('ai-naked') was called for hidden singles — giving them blue instead of purple. The stats chips correctly showed 25 hidden singles (because stats.hidden++ was correctly incremented), but the visual classification was wrong for all of them.

The diagnosis only became possible by actually reading the hiddenSingle() function from disk and observing the three push calls directly. Assuming the property was there because it was designed to be there was the wrong assumption.

Generation requires two independent recursive algorithms — each with a different purpose, but the same structural pattern:

• Phase 1: fillGrid(b, out, depth) — builds a complete valid 9×9 grid. Uses randomized backtracking: for each empty cell, tries digits in a freshly shuffled order. Places a digit, recurses for the next cell. If the recursion returns false (dead end), clears the digit and tries the next. The depth parameter tracks the call stack level and is shown in the log so students can watch recursion depth rise and fall.
• Phase 2: removeCells() + countSolutions(b, limit) — removes cells to reach the difficulty target. For each removed cell, countSolutions(b, 2) verifies the puzzle still has exactly one solution. It uses the same recursive backtracking structure as the solver, but returns a count (not a boolean) and stops as soon as the count reaches limit (early exit). If the count is not 1, the cell is restored.

Difficulty is controlled by how many given clues remain: Easy = 45, Medium = 35, Difficult = 28.

Every recursive function has exactly two kinds of cases:

• Base cases — conditions that return without making a recursive call. In fillGrid there are two:
  • Base case 1: No empty cells found → return true. The board is complete. Success propagates up the call stack.
  • Base case 2: No valid digit for the current cell → return false. Dead end. Forces the caller to try its next digit.
• Recursive case — the function makes progress (places one digit), then calls itself on the resulting board. If that call returns false, it undoes its progress (clears the digit) and tries the next option.

The pattern in pseudocode:

function fillGrid(board):   find first empty cell (r, c)   if no empty cell: return TRUE    // Base case 1   for each digit in shuffle([1..9]):     if digit is valid at (r,c):       board[r][c] = digit       if fillGrid(board) = TRUE: // RECURSIVE CALL         return TRUE       board[r][c] = 0            // backtrack   return FALSE                  // Base case 2

Why it terminates: Each recursive call works on a board with one more cell filled than the previous call. The board has 81 cells. After at most 81 successful placements, the first base case triggers and the entire recursion resolves. Backtracking does not reset the depth counter — it rewinds to a previous call frame on the existing stack. The maximum call stack depth is 81.

Why randomization produces variety: Without shuffling, fillGrid would always produce the same complete grid (digits tried in order 1, 2, 3… would always make the same choices). Shuffling the digit order before each cell means every run explores a different path through the solution space.

The call stack visualized: In the Phase 1 animation, each teal cell added to the board represents one recursive call being pushed onto the stack. Each red flash and clearing represents a stack frame being popped. The depth number in each log entry is the actual JavaScript call stack level at that moment.

Root cause: the CSS file was placed in the wrong directory.

create_file placed aiCreateSudokuStyles.css at the project root (SudokuSPARK2026-07-15/aiCreateSudokuStyles.css), but the HTML links to styles/aiCreateSudokuStyles.css — the styles/ subfolder that every other TNT Sudoku stylesheet lives in. The browser silently received a 404 for the stylesheet and rendered the page unstyled.

Two fixes were required:

1. Create the file at the correct path: styles/aiCreateSudokuStyles.css
2. Update the url() in the #hero background rule from url('images/einsteinSudoku.jpg') to url('../images/einsteinSudoku.jpg'). When the CSS is inside the styles/ subfolder, image paths must go up one level (../) to reach the images/ folder — the same pattern used by every other stylesheet in the project.

The end-to-end workflow is now confirmed working:

1. Open aiCreateSudoku.html, select Easy (45 given)
2. Click Generate — Phase 1 fills 81 cells in teal, with red backtracks visible; Phase 2 removes 36 cells and restores a few with amber flashes
3. Generation completes; the board shows bold given cells and empty puzzle gaps
4. The Save Puzzle panel appears with a JavaScript object literal ready to copy
5. Click Copy — the code is in the clipboard
6. Paste inside the array in sudokuCustomPuzzles.js

The first saved puzzle (id: easy-1784168082196, created 07/15/2026) is now in sudokuCustomPuzzles.js. It has 45 given clues and a guaranteed unique solution, verified by countSolutions(b, 2) during the removal phase.

The 13-digit number is the output of Date.now() — one line in aiCreateSudokuScript.js:

var id = diff + ‘-’ + Date.now(); // → e.g. ‘easy-1784168082196’

Date.now() returns the number of milliseconds elapsed since January 1, 1970, 00:00:00 UTC — the “Unix epoch.”

As of mid-2026 we are roughly 1.784 trillion milliseconds into history — a 13-digit number. The ID serves two purposes simultaneously:

• Uniqueness: two puzzles generated even 1 ms apart get different IDs. No UUID library, no database, no counter.
• Traceability: the number is a decodable timestamp. 1784168082196 ms ÷ 1000 = 1784168082 s since epoch — paste into any Unix timestamp converter to see the exact creation date and time.

Quick sanity check: easy-1784168082196 decodes to July 15, 2026 — the day this session ran.

The custom puzzle ecosystem requires four new files and updates to two existing ones:

• playCustomSudokuPuzzle.html — interactive player; reads localStorage, shows puzzle info bar, digit palette, Reset / Generate New / Watch AI Solve buttons
• playCustomSudokuScript.js — reads tntCustomPuzzle from localStorage, populates board with frozen/clickable cells, exposes window.enterValue() and window.selectValue() for onclick handlers
• solveCustomSudoku.html — AI solver page; same solve controls as aiSolveSudokuSPARK.html but no demo dropdown; puzzle info bar instead; hero is Einstein with navy→purple gradient
• solveCustomSudokuScript.js — loader module: reads localStorage, sets window.brd, populates board, then calls window.aiSolverInit()

The Solve with AI button was added to the generator save section alongside Copy and Play This Puzzle. The Watch AI Solve button was added to the play page controls. This completes a three-page flow: Generate → Play → AI Solve.

solveCustomSudokuScript.js has exactly one responsibility: bridge the localStorage data into the form that aiSolveSudoku.js expects. That bridge has three steps:

1. Read: localStorage.getItem('tntCustomPuzzle') → parse JSON → validate puzzle.board exists
2. Write: set window.brd = puzzle.board.map(…) — the same global variable that aiSolveSudoku.js reads via typeof brd !== 'undefined'
3. Populate: iterate all 81 cells, add frozen class for given digits, clickable for empty — identical to loadDemo() in the player pages

After those three steps, window.aiSolverInit() is called and aiSolveSudoku.js takes over entirely. It finds the frozen cells via hasPuzzle(), reads brd, and the Solve / Step / Pause / Reset controls work identically to the demo solver page.

Script load order in the HTML is critical: solveCustomSudokuScript.js must load before aiSolveSudoku.js so that window.solveCustomInit exists when the page’s init() calls it.

Root cause: in syncUI(), the Step button was disabled whenever isRunning was true:

if (elStep) elStep.disabled = isRunning;

But in step mode, both isRunning and isPaused are true simultaneously. isRunning means “a solve sequence is active”; isPaused means “it is waiting for the user to advance it.” Disabling Step whenever isRunning is true disables it in exactly the state where the user needs it most.

Fix: Step should be disabled only when the animation is actively playing — i.e., when isRunning && !isPaused.

if (elStep) elStep.disabled = (isRunning && !isPaused);

Root cause of “Solved with no steps”: after a completed auto-solve, endRun() sets isRunning = false, which re-enabled Solve immediately. Clicking Solve again ran prepareRun(), which snapshots the already-solved brd into originalBrd. Then clearAICells() restored all AI-colored cells to their values from that solved snapshot — keeping brd fully filled. collectSteps(brd) then found no empty cells and produced a single “Puzzle solved! 0 naked singles” step.

The same race applied to Step after auto-solve.

Fix: Solve and Step are disabled not only while isRunning is true, but also whenever steps.length > 0 (a run completed but has not been reset). resetSolver() already sets steps = [], so Reset re-enables both buttons automatically.

// Before:
elSolve.disabled = isRunning;
elStep.disabled  = (isRunning && !isPaused);

// After:
elSolve.disabled = isRunning || steps.length > 0;
elStep.disabled  = (isRunning && !isPaused) || (!isRunning && steps.length > 0);

The legacy sudokuIndex.html contained: no Bootstrap, Lobster + Roboto Condensed fonts, a non-TNT masthead nav, lorem ipsum body text, an Einstein image in a figure, and no links to any of the seven active pages. It was a 2022-era placeholder that was never updated as the ecosystem grew around it.

What the renovation replaced it with:

• Bootstrap 5.3.3, Font Awesome 6.5, Boogaloo + Inter — matching every other Sudoku Saga page.
• TNT dark navbar (#mainNav pattern) and dark footer with validate link and Copilot/VS Code credits.
• Hero using images/sumoSudokuCartoon.jpeg with a dark green gradient overlay; 200 px height — the compact hero used for reference and navigation pages, not the taller hero used for active apps.
• Four primary feature cards in a responsive grid (col-sm-6 col-xl-3): Play Sudoku, AI Puzzle Generator, AI Solver, Rules & Strategies. Each has a colored accent top border, a Font Awesome icon, a description, and a CTA arrow link.
• Three secondary cards below: Play Custom Puzzle, Solve Custom Puzzle, S.P.A.R.K. Chat Log — smaller layout, visually subordinate to the four primary cards.
• SEO meta block, linkGuard.js, validate-link localhost detection, and copyright/update spans via the standard init() pattern.

What was discarded: the old masthead, old nav links to sudoku-stg1.html, Stage 2, Stage 3 (none of these exist in the current build), the Einstein figure, the lorem ipsum article, Lobster/Roboto Condensed fonts, and the old styles/sudokuStyles.css link.

Three changes were required in sudokuSPARK.html:

1. Script tag — load order matters:

<script src="sudokuCustomPuzzles.js"></script> was added immediately before the inline <script> block. This order is non-negotiable: the inline script’s init() reads sudokuCustomPuzzles by name on page load. If the inline block parses before sudokuCustomPuzzles.js loads, the variable is undefined at the exact moment it is needed.

2. Dynamic dropdown population in init():

After the existing validateLink block, a loop over sudokuCustomPuzzles builds an <optgroup label="Live Puzzles"> and appends one <option> per puzzle. Each option’s value is the puzzle’s id (the timestamp); its visible text is the label plus a running counter — so two puzzles both labeled Live-Medium become Live-Medium 1 and Live-Medium 2 automatically. The entire block is guarded by typeof sudokuCustomPuzzles !== 'undefined' so the page functions correctly even if the data file is absent or empty.

3. Custom puzzle lookup in loadDemo():

The existing else brd = b1 fallback was replaced with a search loop: if the selected dropdown value matches a puzzle id in sudokuCustomPuzzles, that puzzle’s board is loaded with a deep copy (.map(row => row.slice())). The deep copy is required: brd is mutated during play and by the AI solver. Without copying, entering a digit would permanently alter the stored puzzle data in sudokuCustomPuzzles, making it unreloadable mid-session. If no match is found — which should not happen in normal use — b1 remains the fallback.

The same three changes applied to sudokuSPARK.html were applied to aiSolveSudokuSPARK.html:

1. <script src="sudokuCustomPuzzles.js"></script> added before the inline script block
2. Dynamic dropdown population loop added to init(), inserted before the existing if (window.aiSolverInit) window.aiSolverInit(); call
3. Custom puzzle search loop replacing else brd = b1 in loadDemo()

The only structural difference from the player: the solver’s init() ends with a call to window.aiSolverInit() that the player does not have. The dropdown population was inserted before that call so the DOM element exists when aiSolverInit() wires its event listeners. The result is identical behavior in both dropdowns: the “Live Puzzles” optgroup appears beneath the built-in demos, and selecting a custom puzzle loads it via the same deep-copy lookup.

Two changes per page, applied to all five puzzle pages:

CSS (added to each page’s inline <style> block):

• .sudoku-mobile-warning — hidden by default; centered, red, bold, generous padding.
• @media (max-width: 389px) — shows the warning and hides #appSection with !important. For playCustomSudokuPuzzle.html and solveCustomSudoku.html, #puzzleInfoBar is also hidden, because it sits between the hero and the app section on those two pages and would otherwise remain visible on narrow screens.

HTML (inserted between hero and app section in each page):

• A <p class="sudoku-mobile-warning"> with a Font Awesome rotate icon and the message: “Sudoku requires a larger screen or landscape orientation. Please rotate your device or switch to a tablet or desktop.”

The class name sudoku-mobile-warning is consistent across all five pages. The warning element is placed between the hero section and the first content section, matching the Bingo pattern exactly.

The two problems required changes to playCustomSudokuScript.js and playCustomSudokuPuzzle.html:

Problem 1 — Game progress is lost on navigation.

Solution: localStorage autosave. After every digit placement or erasure, autosave() writes the current board state and puzzle ID to localStorage('tntCustomPuzzleProgress'). On the next load, restoreProgress() checks whether a matching save exists (puzzle IDs must match) and restores the player’s digit entries into all non-given cells. The Reset Puzzle button calls clearProgress() before restoring given cells, so a deliberate reset also clears the autosave — future resumptions start fresh.

Problem 2 — “No puzzle” is a static div, not a blocking message.

showNoData() was updated to trigger a Bootstrap modal (#noPuzzleModal) with data-bs-backdrop="static" and data-bs-keyboard="false". The modal is non-dismissible: the user cannot close it by clicking the backdrop or pressing Escape. Two action buttons: Generate a Puzzle (navigates to the generator) and Sudoku Home (navigates to the index). The existing #noDataMessage div is retained as a fallback for environments where Bootstrap’s modal JS is unavailable.

What was not implemented for this session: autosave for the built-in demo games in sudokuSPARK.html. Demo game autosave would require storing the selected demo value alongside the board state, and is straightforward to add using the same pattern — it is a flagged next step.