wordsearch prototype

Author: acharneski

experiments/wordsearch/README.md

@@ -22,7 +22,7 @@ This project flips that around. The filler is generated to **mimic the
 statistical texture of natural language** along all eight reading directions.
 When the noise itself looks word-like, the target words blend in, and the
 puzzle becomes meaningfully harder — not because of grid size, but because of
-*camouflage*.
+_camouflage_.
 
 ---
 
@@ -49,7 +49,7 @@ largely determined by how well the filler hides the targets.
 ### Markov Models
 
 A **Markov model** predicts the next item in a sequence based on the recent
-history. For text, we model it at the *character* level: given the previous
+history. For text, we model it at the _character_ level: given the previous
 few characters, what is the probability distribution over the next character?
 
 Training is simply counting. We slide a window over a reference text and
@@ -117,10 +117,10 @@ while empty cells remain:
 
 The key insight is the **combination step**. A single cell is read as part of
 potentially several different lines (one per direction), so its letter should
-be plausible for *all* of them at once. We support several combiners:
+be plausible for _all_ of them at once. We support several combiners:
 
 | Combiner  | Behaviour                                                                        |
-|-----------|----------------------------------------------------------------------------------|
+| --------- | -------------------------------------------------------------------------------- |
 | `product` | Multiply probabilities — AND-like; favours letters that all directions agree on. |
 | `sum`     | Average the distributions — OR-like; more permissive.                            |
 | `max`     | Take the single strongest directional vote.                                      |
@@ -140,11 +140,11 @@ them:
 ### vs. Random / Frequency-Weighted Filler
 
 The overwhelmingly common approach is to fill empty cells with **uniformly
-random** letters, or occasionally letters drawn from a language's *unigram*
+random** letters, or occasionally letters drawn from a language's _unigram_
 frequency table (so `E` and `T` appear more than `Q` and `Z`). Both ignore
-*sequence* structure entirely. We model the **conditional** distribution
-(order-N), so the filler exhibits realistic letter *transitions*, not just
-realistic letter *counts*.
+_sequence_ structure entirely. We model the **conditional** distribution
+(order-N), so the filler exhibits realistic letter _transitions_, not just
+realistic letter _counts_.
 
 ### vs. Single-Direction Text Generation
 
@@ -153,13 +153,13 @@ generated in **one** direction (left to right). A wordsearch is read in
 **eight**. A naive Markov fill that only respects, say, the horizontal
 direction would still produce nonsense vertically and diagonally. Our
 **multi-directional combination** is the core difference: each cell is
-optimised to be plausible across *all* the lines it participates in
+optimised to be plausible across _all_ the lines it participates in
 simultaneously.
 
 ### vs. Dictionary / Constraint-Solver Filler
 
 Some sophisticated generators (closer to crossword construction) try to make
-the filler spell *real* words in multiple directions using dictionaries and
+the filler spell _real_ words in multiple directions using dictionaries and
 constraint solvers. That is computationally expensive, often infeasible for
 dense grids, and produces a different feel (it leaks real words, which can be
 distracting). We deliberately aim for **plausible-but-not-real** texture:
@@ -172,12 +172,12 @@ Many generators make puzzles "harder" simply by enlarging the grid or adding
 more words. Our difficulty lever is **statistical camouflage**: by matching
 the noise to the language model, target words blend into their surroundings
 regardless of grid size. The Markov order and combiner give fine-grained,
-*qualitative* control over difficulty.
+_qualitative_ control over difficulty.
 
 ### Summary
 
 | Approach                       | Sequence-aware | Multi-directional | Produces real words |    Cost    |
-|--------------------------------|:--------------:|:-----------------:|:-------------------:|:----------:|
+| ------------------------------ | :------------: | :---------------: | :-----------------: | :--------: |
 | Uniform random filler          |       ✗        |         ✗         |          ✗          |    Low     |
 | Unigram-frequency filler       |       ✗        |         ✗         |          ✗          |    Low     |
 | Single-direction Markov        |       ✓        |         ✗         |          ✗          |    Low     |
@@ -189,7 +189,7 @@ regardless of grid size. The Markov order and combiner give fine-grained,
 ## Configuration
 
 | Option    | Default    | Notes                                          |
-|-----------|------------|------------------------------------------------|
+| --------- | ---------- | ---------------------------------------------- |
 | grid size | 15 × 15    | Width × height of the lattice.                 |
 | order (N) | 3          | Markov context length.                         |
 | combiner  | `product`  | How directional predictions are merged.        |
@@ -244,4 +244,4 @@ This is an experiment under active design. Milestones:
 
 - Per-direction weighting of contributions.
 - Difficulty estimation heuristics.
-- Shareable puzzle URLs (encode grid + word list).
+- Shareable puzzle URLs (encode grid + word list).

experiments/wordsearch/idea.md

@@ -12,6 +12,7 @@ backwards), making the hidden target words harder to spot.
 ## 2. Goals & Non-Goals
 
 ### Goals
+
 - Train an order-N Markov model from arbitrary reference text.
 - Place a user-supplied set of target words on the lattice.
 - Fill remaining cells using directional Markov predictions combined
@@ -20,14 +21,15 @@ backwards), making the hidden target words harder to spot.
   required).
 
 ### Non-Goals
+
 - Server-side processing (everything runs client-side).
 - Solving / auto-finding words (generation only, for now).
 - Multi-language morphology (we operate on raw character sequences).
 
 ## 3. Definitions
 
 | Term            | Meaning                                                        |
-|-----------------|----------------------------------------------------------------|
+| --------------- | -------------------------------------------------------------- |
 | Lattice / Grid  | 2D array of cells, each holding a single character.            |
 | Direction       | One of 8 unit vectors: N, S, E, W, NE, NW, SE, SW.             |
 | Order (N)       | Number of preceding characters used as Markov context.         |
@@ -64,6 +66,7 @@ manifest.webmanifest
 ## 5. Component Specifications
 
 ### 5.1 MarkovModel
+
 - `train(text, order)`: builds nested frequency maps
   `context -> { char -> count }`.
 - `predict(context)`: returns a normalised `Map<char, prob>`.
@@ -72,43 +75,49 @@ manifest.webmanifest
 - Serialisable to/from JSON for caching.
 
 ### 5.2 Grid & Directions
+
 - `Grid(width, height)` stores cells; `get/set(x, y)`, `inBounds(x, y)`.
 - `directions.js` exports the 8 vectors and a helper to read the
   context string of length ≤ N preceding a cell along a direction.
 
 ### 5.3 Placement
+
 - Randomly position each target word along a random direction,
   rejecting placements that conflict with already-placed letters
   (unless overlapping letters match).
 - Mark placed cells as **locked** (never overwritten by the filler).
 
 ### 5.4 Fill Order (Adjacency)
+
 - Maintain a priority queue of empty cells keyed by adjacency score.
 - Cells with more filled neighbours are filled first; ties broken
   randomly. Re-score neighbours after each fill.
 
 ### 5.5 Prediction Combination
+
 For a target empty cell, for each of the 8 directions that has a
 defined (non-empty) preceding context, request a prediction. Then
 combine the resulting distributions using a configurable method:
 
-| Combiner   | Description                                             |
-|------------|---------------------------------------------------------|
-| `product`  | Multiply probabilities (logarithmic, AND-like).         |
-| `sum`      | Average / weighted sum (OR-like).                       |
-| `max`      | Take the strongest single directional vote.             |
-| `vote`     | Each direction votes for its argmax; majority wins.     |
+| Combiner  | Description                                         |
+| --------- | --------------------------------------------------- |
+| `product` | Multiply probabilities (logarithmic, AND-like).     |
+| `sum`     | Average / weighted sum (OR-like).                   |
+| `max`     | Take the strongest single directional vote.         |
+| `vote`    | Each direction votes for its argmax; majority wins. |
 
 The combined distribution is sampled (or argmax-selected per config)
 to choose the cell's letter.
 
 ### 5.6 UI
+
 - Controls: grid size, Markov order, combiner method, sampling mode,
   reference text input/upload, target word list.
 - Render grid (highlight locked target letters in debug mode).
 - Regenerate / export (text, PNG) actions.
 
 ### 5.7 PWA
+
 - `manifest.webmanifest` + service worker caching app shell for
   offline use. Installable on desktop/mobile.
 
@@ -131,13 +140,13 @@ while empty cells remain:
 
 ## 7. Configuration Defaults
 
-| Option       | Default     |
-|--------------|-------------|
-| grid size    | 15 × 15     |
-| order (N)    | 3           |
-| combiner     | `product`   |
-| sampling     | `weighted`  |
-| back-off     | enabled     |
+| Option    | Default    |
+| --------- | ---------- |
+| grid size | 15 × 15    |
+| order (N) | 3          |
+| combiner  | `product`  |
+| sampling  | `weighted` |
+| back-off  | enabled    |
 
 ## 8. Implementation Plan (Milestones)
 
@@ -151,11 +160,13 @@ while empty cells remain:
 7. **M7 — Polish**: presets, sample reference texts, accessibility.
 
 ## 9. Testing Strategy
+
 - Unit tests for model back-off, combiner math, placement conflicts.
 - Property test: every locked target word is readable post-fill.
 - Visual/manual QA for generated grid plausibility.
 
 ## 10. Stretch Goals
+
 - Per-direction weighting of contributions.
 - Difficulty estimation heuristics.
-- Shareable puzzle URLs (encode grid + word list).
+- Shareable puzzle URLs (encode grid + word list).