# Magic Hex Swap — prototype rules

This is a playable adaptation, not a declaration of canonical rules. The original source is preserved unchanged at `docs/archaeology/games/magic-hex-swap/sources/Magic Hex Swap Game Design Doc.pdf` (two pages), with its text companion and provenance profile in the same archaeology directory. Both PDF pages and the full action list were read and visually checked for this implementation on 2026-10-08.

## Authority and provisional choices

Owner rulings relayed in the October 8 task, dated October 7: the 19 hexes are an opening arrangement, not a board boundary; colors may be created freely during play. The initial bag of 30 (six of each color) applies only to the opening. This engine has neither a play-time board boundary nor a per-color inventory cap.

The [live Magic Hex Swap Game Design Doc](https://docs.google.com/document/d/11MlxzL8XXc-Jz0OpHHT1whtw4JdCNeDK72TmgFvFQH8/edit) was supplied in the task follow-up and independently reread in full through the authorized Google Drive connection on 2026-10-08. The archived profile at master `47a8205` omits this URL; the frozen archive remains unchanged. Earlier research read both sources on October 7, as relayed in the follow-up.

The verified Green 3 discrepancy is PDF “Add up to 4 green nodes to spaces adjacent to a single green cluster” versus Doc “Add up to 4 green nodes to green-adjacent spaces.” The remaining action wording agrees. Neither source's date establishes precedence, and neither variant is selected as owner canon. The Doc metadata reports creation on 2024-08-06 and modification on 2024-08-09; these dates are provenance, not a rules-priority decision. The PDF supplies the prototype's default baseline, while both Green 3 modes and their timing details remain explicitly provisional.

Prototype interpretations (not owner rulings):

- Tier numbers cost exactly that many matching-color or wild dice; one action per turn. Choose which dice to spend. Save any unspent dice; reroll all others.
- Hex distance is geometric axial distance, independent of occupied cells. Blue destinations must be empty; nodes may move across gaps without a path requirement.
- Chains are ordered, distinct, adjacent target positions. Each next node must touch the previous target, including the former position of a removed node.
- Compound actions evaluate sequentially against the intermediate board but commit atomically. A third node in White 3 is distinct from both first-swap nodes. Blue 3's second node is distinct from the first moved node. Eligibility is rechecked after the first operation. No extra distance limit is imposed on the second White 3 swap or Blue 3 move because the source does not specify one.
- Default **PDF cluster mode**: Green 3 adds 1–4 greens, all adjacent to one common green component as it existed before the action. Earlier additions do not extend that reference component. This timing detail is provisional, even in PDF mode. If the first target touches multiple components, any common component satisfying every target is sufficient.
- Alternate **Doc adjacency mode**: Green 3 adds 1–4 greens, each adjacent to any green at that step, including newly added greens. This is a provisional interpretation of the verified Doc wording; the Doc does not settle whether earlier additions extend adjacency during the action. Select the mode when starting a game; it is stored with the save.
- Green's non-green creations may be any non-green color independently, with unlimited supply. “Up to 4” means at least one; a zero-effect selection is not an action.
- A pass costs one turn and permits saving/rerolling. This escape hatch is not in the PDF; it prevents an unusable roll from trapping play after a color disappears. It is available explicitly, never automatic.
- A turn is scored when its action/pass completes, including the winning action. Undo restores the complete prior checkpoint and deterministic roll sequence; last 50 checkpoints are retained.
- If a shuffled initial bag cannot legally fill a position even after checking all deferred nodes, deterministically reshuffle and redeal. This rare setup fallback is provisional. Otherwise deferred colors are tried oldest first before drawing from the bag, exactly as described.

## Full action coverage

All five colors and all 15 tiers are implemented; alternative branches have their own menu items.

| Color | 1 die | 2 dice | 3 dice |
|---|---|---|---|
| White / swap | White with adjacent node | White with a node exactly 2 away OR white-adjacent with adjacent node | White/white-adjacent with a node 1–2 away; then another eligible node with either first-swap position |
| Black / blacken | Non-black with at least 2 black neighbors | Black-adjacent non-black | Chain-blacken 2 non-black nodes, starting black-adjacent |
| Red / remove | Non-red with at least 2 red neighbors | Red-adjacent non-red | Chain-remove 2 non-red nodes, starting red-adjacent |
| Blue / move | Blue 1–2 spaces | Blue 3–4 OR blue-adjacent 1–2 | Blue/blue-adjacent 1–4; then another eligible node into the first vacancy |
| Green / add | Chain 1–2 greens from green adjacency | Chain 3–4 greens OR one non-green at green adjacency | 1–4 greens with selected cluster interpretation OR chain 2 non-greens from green adjacency |

## Setup, win and score

Nineteen nodes are dealt row by row, left to right, in 3/4/5/4/3 rows from a shuffled six-of-each-color bag. A node never starts next to its own color. Rejected draws are set aside and checked oldest first for subsequent positions. Three dice each have white, black, red, blue, green and wild faces. Seeds reproduce the opening and each turn's roll.

Win when every present color has exactly one connected component containing at least two nodes. Absent colors are allowed; different-color groups do not need to touch. Singletons and split groups do not win. Lower completed-turn scores are better. Original ratings: 10+ beginner; 8–9 improving; 7 good; 6 great; 5 or fewer expert and/or lucky.

## Play and run locally

Requires Node.js 20+; no install, external assets, network service, paid API or runtime model call.

```sh
cd magic-hex-swap
node serve.mjs
# Open http://127.0.0.1:8954
node --test tests/engine.test.mjs
node build.mjs
# Optional: serve the static build with node serve.mjs --dist
```

Select matching/wild dice, choose an action, then tap outlined targets in order. Choose a color before each non-green creation. The board previews intermediate effects; Apply action commits the complete sequence. Color groups shows the group and node counts for each color, whether it still needs joining or a partner, and which absent colors are already allowed. Tap a present color in Color groups to number its connected groups on the board. Nodes with the same letter and number are connected; different numbers need joining. Tap again to clear. This view does not spend dice or change the puzzle, and follows the current draft. During target selection this readout is explicitly a draft preview; only Apply action commits it. Cancel clears targets without consuming dice. Afterward select unspent dice to save and roll the rest. Drag to pan, use +/− to zoom, and Fit to include legal targets. The board grows without a game boundary. Reload restores committed progress and a valid action draft. Restart can use the same seed or a new one; Undo can recover the previous game.

## Scope and limitations

Phone-friendly solo prototype. The shared Deev Games release stages it at `/magic-hex-swap/`, visibly labeled as a prototype; publication does not finalize any provisional interpretation. No multiplayer, AI, solver, solvability proof, balance claim, official-rule claim, or change to older games. Seeded legality is verified, not a guarantee every opening is solvable within a target score. Large boards remain legal but rendering/target enumeration has not been load-tested. Storage is browser-local and browser clearing removes it. Keyboard target selection is supported; a full accessibility audit and native-device Safari pass are still pending. See `VERIFICATION.md` for executed checks and capacity evidence.

## Three quick finishers

Blue bridge, Two homes and Remove the splinter are authored practice positions,
with fixed dice and at least one engine-verified one-turn solution each. They use
the same prototype actions and victory test, with the PDF Green 3 mode. These
small boards are explicitly separate from the ordinary 19-node deal, not a new
opening rule or a claim that normal random openings have one-turn solutions.

Each practice puzzle keeps its own browser save, draft and Undo history. Reload
resumes it; Restart this puzzle resets its fixed position and can itself be
undone. Return to main puzzle restores the ordinary game without changing it.
Hints are optional. Pass, further turns and ordinary actions remain available.