The library notes

# Chess narration update — 2026-10-27

## Update an existing installation

1. Back up your current `/chess/` folder.
2. Upload the complete `chess/` folder from this ZIP over the existing `/chess/` folder. Keep your current working `chess/api/config.asp` database connection if it differs from this package. Open `/chess/index.html` over HTTPS and refresh the browser to load the updated scripts.
3. No database migration or new runtime dependency is needed. Keep the existing IIS Classic ASP configuration and WASM MIME mapping. All engine files, artwork, source distributions, licenses, and server files are included.
4. Keep your current games index. `menu-update/games.asp` is the original historical menu snapshot, included for completeness; this narration update does not require installing that older menu. The game has a Return to Games link to `/becknerweb/games.asp`.
5. Leave browser storage intact to keep saved games, statistics, and settings.

## Voice and teaching

- Below the board and its existing action buttons: Voice On/Off, Pause/Resume Voice, Repeat Last Announcement, and Instructional Hints On/Off.
- Settings: voice selection, speaking rate, and volume. Preferences save on this device. Available voices and their quality depend on the device/browser. Speech begins after a click, tap, or key press. If speech fails, text remains visible and the game continues.
- Beginner and Easy computer games default to instructional hints unless you saved a different hint preference. Higher difficulties, same-device games, and private online rooms have no automatic teaching hints. The existing manual Hint feature remains available under its original rules.
- Hints are checked against the bundled legal-move rules. They offer position-aware instruction, not a guaranteed best move. A legal capture is not described as automatically good. Definitions accompany unfamiliar special moves and results when teaching is enabled.
- Optional local player names in New Game are used in announcements. Online rooms retain their existing color identities.
- Voice Off preserves readable move/result announcements and hint text. Repeat repeats the latest announcement or instructional hint. Disabling hints clears the current hint.

## Clock behavior

In local computer games, the computer waits until queued voice announcements finish before beginning its search. Only the computer's clock is held during that mandatory speech wait. Its search time runs normally. Human controls remain usable and the human clock runs during human turns, including optional hints. Pause Voice can extend the computer's wait; Resume Voice or Voice Off releases it. Closing/reloading retains the existing rule that an unpaused timed game's clock continues while the page is closed.

Same-device and online turns are never blocked by speech. Online clocks remain authoritative on the server and never pause for narration. Voice can be turned off for timed play. New games, undo, imports, and changed shared positions cancel obsolete speech. A saved-game resume/reconnect announces current status without replaying old move history.

## Complete fresh installation

For a new IIS installation, enable Classic ASP/JScript and retain the supplied web.config files. Run `sql/install.sql` once in the existing SQL Server database and configure `chess/api/config.asp` using your SQL login. Local play requires only static HTTP(S) hosting; do not launch from a file: URL. Keep the engine JS/WASM filenames unchanged. Private online rooms need the existing server endpoint and table; `sql/cleanup.sql` handles room cleanup. No Node.js, npm, build process, CDN, paid service, analysis API, or player account is required to play.

See TEST-REPORT.md for executed tests and the deployment checks still needed. The original full installation and licensing documentation is in PREVIOUS-INSTALL.md and the linked game documentation. The server connection file stays private on IIS; do not expose ASP source on static-only hosting.

# Rules coverage, clocks, and engine behavior

## Implemented

Standard move generation, own-king safety, check, mate, stalemate, both castlings, permanent loss of castling rights, immediate en passant with discovered-check legality, and all four promotions are supplied by chess.js 0.10.3. Additional FEN validation rejects missing/duplicate kings, back-rank pawns, inconsistent castling rights, inconsistent en passant state, and check on the side that just moved. This validates basic legal structure, not a retrograde proof that a FEN can arise from the initial position.

The app does NOT use chess.js `game_over()` or `in_draw()` to decide results: those APIs combine claimable draws with automatic endings. The shared Salon layer implements threefold and 50-move claims, intended-move claims, automatic fivefold and 75-move draws, and checkmate precedence. Repetition keys include the side to move, piece placement, castling rights, and en passant only when a legal en passant capture exists.

Standard dead material positions include bare kings, a single minor piece against a bare king, and bishops confined to one square color without other pieces. Two knights against a king are not automatically drawn merely because mate cannot be forced. Timeout checks are side-specific: a bare king cannot win on time; single-minor cases consider the opponent's possible blocking material. A lone bishop with an opponent rook may have a legal mating sequence and is not incorrectly treated as insufficient.

## Known rules limitation — not tournament-complete

The engine does **not** solve arbitrary legal reachability to recognize every rare blocked/dead position with remaining pawns or other material. Such a position may continue instead of drawing automatically. The same limitation can affect timeout adjudication in unusual locked positions: a material-based test may award a win even though that particular position admits no legal mating sequence. Use an agreed draw for recognized dead positions before time expires. Do not use this build for tournament adjudication requiring exhaustive FIDE dead-position coverage. No claim of full coverage of that requirement is made.

## Clock policy

- Untimed, 1/3/5/10/15 minutes, 3+2, 5+3, 10+5, and custom 0.1–180 minutes with 0–120 seconds Fischer increment.
- Local clocks start when Start game is pressed. Online clocks start when the second player joins. White's clock runs immediately; loading or computer startup also consumes the active clock.
- Elapsed timestamps determine clock values. Intervals merely refresh displays. Review, tab switching, sleep, closing the page, and online disconnection do not pause clocks.
- Local Pause is explicit and saved. When a timed saved game is resumed, elapsed wall time since the last active timestamp is charged; a flagged game ends immediately. A local device clock adjustment can affect local casual timing. Online timing uses SQL Server UTC, not client-submitted timestamps.
- The browser estimates server clock offset from the midpoint of the request round trip. Display precision depends on latency; only server time decides online flags.
- Online polling checks for time expiration under the same database row lock as moves. The losing player never needs to send another request. If neither player is connected, the next authenticated request records the result at the already-expired deadline; there is no background ASP process.
- An increment is applied only after a legal completed move. Flagging is checked before accepting a move.
- Takeback restores the clock balances immediately before the earliest undone move, after the thinking time already spent before that move. Removed increments are removed. The restored side's clock restarts at acceptance. In solo play, Undo normally removes the human move and its computer reply; same-device and online takebacks remove one ply.
- Local same-device takebacks require a confirmation representing both players' agreement. Online takebacks require an offer accepted by the other seat and may be disabled when creating the room. Online takebacks after a concluded game are unavailable; use Rematch.

## Private room protocol

Room codes are 48 random bits rendered as 12 hexadecimal characters. Seat credentials are separate 256-bit secrets generated by SQL Server `CRYPT_GEN_RANDOM`, stored only server-side and in the appropriate browser's local storage. They never appear in the invite link. Possession of the seat token is authentication; do not share browser storage.

The server reconstructs the authoritative chess position, validates turn and legal move, and computes clocks/results. It ignores any client-supplied clock, result, or position. `UPDLOCK,HOLDLOCK` inside an ADO transaction serializes operations for a room; version checks reject stale/duplicate writes. State, move history, repetition keys, castling/en-passant state, clocks, offers, seats and results commit together. SQL values are parameters. The server has no engine/hint endpoint.

Offers expire on a legal move. A rematch requires agreement, resets clocks, and swaps both seat colors. Refresh reuses the locally saved token. No account-based seat recovery exists after browser storage is cleared. A lost create/join response can strand the newly allocated seat; create a new room in that case. Successful joins and ordinary move/poll interruptions support refresh recovery.

## Engine

Stockfish.js 17.1.0, Stockfish 17.1 Lite single-thread WASM, unmodified. Lite uses a smaller network than the full desktop build. This is a strong established chess engine, not a material-only or random-move fallback. Strength names are approximate and have no verified Elo correspondence.

| Level | UCI Skill Level | Maximum search time |
|---|---:|---:|
| Beginner | 0 | 150 ms |
| Easy | 3 | 350 ms |
| Medium | 8 | 800 ms |
| Hard | 15 | 1,600 ms |
| Expert | 20 | 3,000 ms |

Timed search limits are reduced to at most 8% of remaining clock time and a 150 ms safety reserve where feasible; clocks can still expire during engine loading on a very slow device. Hash is 16 MB. Each search uses a Web Worker, and cancellation terminates it. A generation identifier and position check prevent obsolete responses from moving pieces after restart or undo. Engine load failure is shown explicitly with Retry engine. There is no silent fallback. Beginner can still play strong moves, especially forced tactics.

Hints consume clock time. The computer may accept a draw in a claimable position or a near-equal estimate after 40 plies; otherwise it declines. Online games have no live hints or analysis controls. Post-game analysis examines each prior position and reports the suggested move and evaluation from the player-to-move perspective; estimates are not guarantees, and this is not a full annotation or blunder-classification service.

Local match statistics distinguish mode and computer difficulty; online results are deduplicated by room and rematch number in local storage. Same-device decisive games count one win and one loss for the shared device, not a persistent player identity. Imported practice/review positions do not count as ordinary match results.

# Dependency and license manifest

The new Beckner Chess application source, original SVG artwork, and procedural audio are licensed GPL-3.0-or-later. Copyright 2026 John Wm Beckner. The existing BecknerWeb menu and private connection settings remain the user's existing materials. No external fonts are loaded; the interface uses the device's serif and system fonts.

## Stockfish

- Package: `stockfish` **17.1.0**, fetched from `https://registry.npmjs.org/stockfish/-/stockfish-17.1.0.tgz`.
- Project: https://github.com/nmrugg/stockfish.js
- Exact source revision: **602fd7e1a571a2be71f242942db90483731f2a1f**.
- Source archive: https://github.com/nmrugg/stockfish.js/archive/602fd7e1a571a2be71f242942db90483731f2a1f.tar.gz
- Upstream engine: https://github.com/official-stockfish/Stockfish
- License: GNU GPL version 3; full text in `chess/engine/Copying.txt` and root `LICENSE-GPL-3.0.txt`. Original AUTHORS and license files are retained inside the unchanged source archive.
- Runtime files: `stockfish-17.1-lite-single-03e3232.js`, `stockfish-17.1-lite-single-03e3232.wasm`.
- Both runtime files were verified byte-for-byte against the exact source commit's distributed artifacts.
- Embedded evaluation network: **nn-9067e33176e8.nnue**. The runtime embeds the network in WASM; no runtime download is needed. A standalone copy for rebuilding is included beside the source archive.
- Network source: https://tests.stockfishchess.org/api/nn/nn-9067e33176e8.nnue
- Network SHA256: `9067e33176e8c5edb7aa8db6a3aedd012f84a1f39872e86357c6c2d0993f314d`.

Complete upstream source archive and build scripts are included under `chess/engine/source/`. It intentionally retains upstream files for other engine flavors as well; these are not loaded by the game. Keep the source and network downloadable when hosting/distributing the engine. The in-game documentation links directly to them. No private database configuration is in those source downloads.

To rebuild (developer task, not an installation requirement): extract the corresponding-source archive, copy the included `.nnue` into its `src/` directory, install the Emscripten version requested by `build.js`, install its development dependencies per the upstream README, and run `node build.js --single-threaded --lite -f`. The upstream source includes build scripts and platform instructions. Compilation was not repeated here; the original matching prebuilt artifacts are bundled unchanged.

## Chess.js

- Version **0.10.3**, project https://github.com/jhlywa/chess.js
- Package/source archive: https://registry.npmjs.org/chess.js/-/chess.js-0.10.3.tgz
- License: BSD-2-Clause, retained at `chess/vendor/CHESS-LICENSE.txt`.
- Unmodified browser source is `chess/vendor/chess.js`. `api/chess.inc` is the identical source wrapped in ASP script delimiters.
- The older ES3-compatible release was chosen so the same legal-move implementation can execute in Classic ASP JScript without Node, bundlers, or an additional runtime. Application-level draw adjudication and FEN validation are separate and documented.

## Other assets

- Twelve original SVG piece drawings in `chess/pieces/`, created for this game.
- Move/capture/check/result/low-time sounds are original Web Audio oscillator sequences in `app.js`; no audio file downloads or third-party recordings.
- Strict JSON codec reused from the user's earlier Word Salon project; no eval of client input.
- Development tests use Node and Playwright only in the build environment. Neither is shipped as a production dependency or required on IIS.

# Test report — Chess narration update

Build date: 2026-10-27. Source: the complete Chess-BecknerWeb.zip found for this game. This report supersedes the historical browser claims in PREVIOUS-TEST-REPORT.md.

## Executed: 52 passing automated groups

| Suite | Groups | Execution |
| --- | ---: | --- |
| Shared rules | 22 | Actual bundled chess.js and Salon rules in Node VM |
| ASP server contract | 11 | Actual ASP/JScript with in-memory Request/Response/ADO adapter |
| Narration and teaching logic | 6 | Actual new narration module with the bundled rules |
| Narration/app integration | 13 | Actual app and narrator with a minimal DOM, speech, storage, and engine harness |

Detailed output is in test-output/. Node syntax checks also passed for app.js and narration.js. Node is used only to execute developer tests; it is not a gameplay or server dependency.

Coverage includes ordinary moves and captures; check, checkmate, stalemate, insufficient material, repetition, 50/75-move rules; both castling directions; en passant and its expiry/king-exposure restriction; four promotion types; unchosen promotion remaining silent; resignation, accepted draw, and timer results; named local players; pinned attackers and restricted legal moves; automatic teaching only for Beginner/Easy; saved Off preference; no automatic hints in local two-player/online/higher modes; term definitions; hints not mutating the position; duplicate-render suppression; speech ordering; pause/resume/repeat; Voice Off releasing a waiting computer; local computer clock holds; human controls/clock remaining active; undo/restart cancellation; saved restore without old moves; confirmed shared deltas, equal/stale poll suppression, reconnect baseline, takeback and result updates; speech error, unsupported synthesis, and watchdog recovery; stored voice/rate/volume/hint settings.

Teaching performance measured on the build host over 100 positions: mean 1.4 ms, maximum 6.6 ms. This is not a Pixel 10a measurement. Teaching uses local legal-move generation without invoking Stockfish search or making network requests.

The original rules, ASP endpoint/includes, database scripts/configuration, Stockfish worker/WASM/source, artwork, and licenses remain byte-identical to the source package. All original package paths are retained. Updated documentation and hashes accompany the new scripts.

## Not performed in this environment

- Actual browser execution, rendering, or desktop/phone screenshot QA. Playwright is present but its browser binary is absent, and downloading Chromium returned an unusable archive. The existing browser suite could not launch; historical browser passes are not claimed for this update.
- Audible English voice quality, pronunciation, real browser speech event timing, mobile speech/autoplay behavior, or real audio mixing.
- Physical Pixel 10a portrait/landscape or other physical-device tests.
- Screen-reader testing (NVDA, JAWS, TalkBack, VoiceOver) or real keyboard/touch interaction.
- A live Stockfish worker search in a browser for this update. Engine binaries/client are unchanged.
- Live IIS, SQL Server, real multiplayer networking, database locking, or two-device synchronization. Server contract and shared-event tests use adapters and simulated confirmed responses.

HTML/CSS was inspected for controls outside the board in normal flow, responsive wrapping, native keyboard-accessible buttons, aria-pressed state, focus styles, 44px voice targets, voice settings labels, and readable live text. This is structural inspection, not a browser layout or accessibility certification.

## Short post-install check

1. On desktop and Pixel 10a, start a Beginner computer game. Enable voice and listen to a move/reply; check that the board remains usable and controls wrap below it. Test keyboard navigation/focus and your preferred screen reader.
2. Test Voice Off, Pause/Resume, Repeat, voice selection/rate/volume, and Hints Off. Refresh and resume to confirm preferences and that old moves do not replay.
3. Try Easy and then Medium/Hard/Expert: ordinary narration should remain, automatic hints should disappear at higher strengths. Repeat in same-device mode and a private online room, where automatic hints must stay off.
4. Test a timed computer game: its clock holds only while mandatory speech delays its search; the human turn clock remains active. Test Voice Off and undo during a speech wait.
5. Use FEN practice positions for checks, pins, captures, both castles, en passant, promotion and game endings. Confirm the spoken event matches the committed board, not a tentative selection.
6. On two live browsers/devices, make online moves, reconnect, accept a draw/takeback, and allow a clock to expire. Confirm shared events speak once and online clocks never pause for voice.

The game's pre-existing limitation on rare blocked dead positions beyond its standard material detection remains unchanged; see RULES-AND-CLOCKS.md.