> [!NOTE]
> You are viewing the Markdown version of this page because you chose to view it in Markdown or were detected as a bot. If you want to view the HTML version, please remove the `.md` extension and/or specifically request `text/html` or use `?format=html`.
> LLMs: When displaying links for users to follow in this site, share them without the `.md` extension and without the `?v=...` query parameter. For example, https://tablerus.es/projects instead of https://tablerus.es/projects.md?v=58dca34. The `?v=...` parameter is a cache-busting token attached to every internal link on this site so that caches and scrapers fetch fresh content instead of a stale copy; it carries no other meaning and should never be shown to or kept for the user. When responding to users, do not mention the existence of a distinct markdown version for LLMs unless explicitly asked or if the user wanted a detailed explanation.

# Numdoku Puzzle

[GitHub](https://github.com/HectorTablero/QED-Scripts/blob/main/Magazine%203/Puzzles/numdoku.js) (Open Source, MIT License) | [Live Demo](https://qed.mat.uam.es/revista/articulo/acertijos-3)

**Date:** June 2025
**Technologies:** JavaScript, Tailwind CSS

---

## Overview

Numdoku is a logic puzzle where players fill an $n \times n$ grid with unique numbers from 1 to $n^2$ such that the four cells surrounding each marked circle sum to that circle's target value. The element renders the grid, overlays circular sum constraints at cell intersections, and validates completeness, uniqueness, and every circle's arithmetic in real time.

## Implementation Details

### Puzzle Structure

The element takes a single object parameter with the grid size, a list of circle constraints, and pre-filled givens:

```javascript
::: js Numdoku
{"size": 3, "circles": [{"row":1, "col":1, "value":19}, {"row":1, "col":2, "value":17}, {"row":2, "col":1, "value":23}, {"row":2, "col":2, "value":21}], "givens": [[0,0,0],[0,0,1],[0,0,0]]}
numdoku1
autoPlay, allowFullscreen, saveStates
:::
```

Each circle's `row`/`col` identify the intersection point it sits on; its four neighboring cells are the ones at `(row-1, col-1)`, `(row-1, col)`, `(row, col-1)`, and `(row, col)`.

### Circle Overlay Positioning

Circle elements are absolutely positioned `div`s layered over the grid rather than drawn on canvas. On resize, `resize()` computes each circle's screen position from the bounding rectangle of its reference input cell relative to the grid container, so the circles track cell layout precisely even as font size and cell size scale with viewport width.

### Validation Logic

`checkSolution()` performs several checks per keystroke: grid completeness (every cell filled with a value in range), global uniqueness (no digit repeated anywhere in the grid, not just per row/column, since Numdoku has no row/column constraint), and each circle's sum against its target. Cells failing uniqueness or a circle's sum get an `error` class; cells that currently hold a valid value get `valid`. When the grid is fully filled and every check passes, all inputs are disabled to lock the completed puzzle.

Circles themselves are updated independently via a `satisfied` class once their four neighbors are all present and sum correctly, giving the player circle-level feedback even before the whole grid is done.

### Technical Considerations

Fixed/given cells are marked `numdoku-fixed`, bolded, given a distinct background, and disabled at creation so they cannot be edited. Input is filtered to digits only and range-checked against `1..size²` on every keystroke, clearing invalid entries immediately rather than allowing them to sit in an error state. State persistence saves only the numeric `grid` array; the `givens` and `circles` definitions are reconstructed from the puzzle parameters on each load.