YZF Sudoku 使用手册 / User Manual

YZF Sudoku is a Web/WASM Sudoku tool focused on advanced solving logic. It supports puzzle-string import, Sudoku Coach formats, local image OCR, auto solving, all-step search, candidate editing, explanation paths, and highlighting.

The goal is not only to produce the final answer, but to show the logical path behind each step, especially for advanced techniques such as AIC, ALS, UR, Oddagon, and Force Chain.

Regular Web Build

The regular build is usually opened through a local or hosted HTTP server. For development:

cd web-app
python -m http.server 8000

Then open http://127.0.0.1:8000/index.html.

Standalone Build

The standalone build is intended to work by double-clicking the HTML file without starting a server. OCR models and runtime files should be bundled into the single HTML file.

• Board: shows the 9×9 grid, givens, solved digits, and candidates.
• Input panel: accepts puzzle strings, Coach/Library formats, and image OCR.
• Technique panel: selects techniques, finds the next step, or searches all steps.
• Result panel: displays eliminations, paths, explanations, ratings, and status messages.
• Export area: exports the current board, candidates, and shareable strings.

The project supports several import formats:

• 81-character string: digits 1-9 are givens, while 0 or . means empty.
• Library colon format: for example :0000:x:<board>:<eliminations>::, preserving candidate eliminations.
• Sudoku Coach JSON: includes fields such as givenDigits, userDigits, and userCellCandidates.
• SCv7_32 Coach compressed string: decompressed by the frontend into Coach JSON before import.

Regular imports are checked for validity and uniqueness. OCR imports are allowed to land as editable drafts so the user can correct recognition mistakes.

userCellCandidates contains 81 masks separated by -. Digit d corresponds to 1 << d. For candidates 2,3,6, the mask is 4 + 8 + 64 = 76.

Image recognition runs locally in the browser. Images are not uploaded and no online fallback is used. The recognized result is imported directly as an editable draft board.

The buttons are normally placed in the “Puzzle Input / Export & Rating” panel:

• Select Image: choose an image from files or photo library.
• Take Photo: open the camera on mobile devices.
• Read Clipboard: read a screenshot from the desktop clipboard.
• Ctrl+V: desktop users can paste screenshots directly.

• Black large digits: imported as givens, givenDigits.
• Blue or other colored large digits: imported as solved/user digits, userDigits.
• Pencil marks: imported as userCellCandidates.
• Non-unique result: not rejected; it is shown as a draft so the user can correct it.

After OCR import, the black givens are checked for uniqueness. If the check fails, the draft still remains editable on the board.

After selecting a cell, you can enter a digit or toggle candidates. In OCR draft mode, edits are applied directly to the frontend draft board, so the engine will not reject the board simply because the givens are not yet unique.

• Enter a large digit: set the solved/user digit for the cell.
• Toggle candidates: add or remove pencil marks in an empty cell.
• Undo/Redo: revert or restore recent board operations.
• After correction, you may re-import or start technique search.

Auto Solve starts from the current board and searches for logical steps according to the enabled techniques and priority order, until the puzzle is solved or no next step is found.

• Auto Solve: repeatedly applies available logical steps.
• Background solving: long searches may display background status messages.
• Status messages: show results such as solved, NoResult, or Invalid.

If an advanced technique is not found, make sure it is enabled in the technique panel and that the current wasm/standalone file has been rebuilt or regenerated.

“All Steps” collects multiple available steps from the current board, making it easier to compare different techniques, eliminations, and paths.

• Filter by technique type.
• Inspect eliminations, paths, explanations, and highlights.
• Complex chains and Force Chains may require noticeably more time.

The project supports a wide range of techniques from basic to advanced. Advanced chain techniques display paths, strong/weak links, common eliminations, and special patterns.

Full technique guide: open techniques.html for player-facing explanations of implemented techniques, conclusions, and highlight reading tips.

Recently supported advanced areas include:

• AIC / X-Chain / XY-Chain
• ALS / AHS / XZ-style techniques
• UR Guardian Force Chain
• Triplet Oddagon / Tridagon Guardian Force Chain
• MSLS, JE, Dynamic Chain, and other migrated advanced techniques

Highlights usually include chain paths, starts, ends, eliminations, structure cells, and guardian candidates.

The general logic of Guardian Force Chain is: not all guardians of a dead pattern can be false, so at least one guardian must be true. If every true guardian leads to the same elimination, that elimination is valid.

UR Guardian FC and Triplet Oddagon Guardian FC share the same search logic; only the dead-pattern structure differs.

The project supports a built-in superhard puzzle bank. When generating a superhard puzzle, one entry is randomly selected from the compressed bank, decoded, and imported into the current board.

The lightweight design uses a compressed bank, much smaller than storing raw 81-character strings. The packing tool can convert a list of puzzles into a C++ data segment.

• Raw puzzle strings: about 81 bytes per puzzle.
• Puzzle19 raw: about 19 bytes per puzzle.
• Compressed bank: observed around 14.4 bytes per puzzle, depending on the bank.

You can export the current board for sharing, reproduction, or debugging. Common export contents include:

• Plain 81-character puzzle string.
• Library colon format with candidate eliminations.
• Coach JSON or SCv7_32 compressed string.
• Current rating, step paths, and highlight information.

After OCR import, correct the board first, then use the existing export feature to save the corrected position.

• Mobile devices do not have a Ctrl + V shortcut, so use “Select Image” or “Take Photo”.
• If Chrome cannot open the camera, check whether camera permission is disabled in Chrome settings.
• Some browsers show a “camera/gallery” chooser instead of opening the camera directly. This is browser behavior, not necessarily a project bug.
• After recognition, edit large digits and candidates directly on the board.

Refreshing Chrome on Android

There is no exact mobile equivalent of desktop Ctrl + F5. During development, use versioned URLs or clear the site cache in Chrome settings.

The standalone build is meant for offline use without a local server. To support image recognition, the build script must inline or bundle the OCR JS, ORT runtime, WASM, and model files into the single HTML file.

If OCR works in the regular Web build but fails in standalone, check:

• whether ort.min.js is correctly bundled.
• whether the .wasm runtime is available.
• whether puzzle_localizer.ort and puzzle_classifier.ort are bundled.
• whether the OCR module still uses dynamic import() or fetch() for local files.

The Sudoku image recognition feature uses a local model trained by Alex Kubiesa / Sudoku OCR. Recognition is performed locally in the browser. Images are not uploaded and no online fallback is used.

Recommended attribution text for About, Help, or the OCR panel:

Sudoku image recognition uses a local model trained by Alex Kubiesa / Sudoku OCR. No online fallback is used.