Render square Wang solutions as diagnostic PNGs

renderer/README.md

@@ -6,6 +6,10 @@ A command-line pixel art renderer that composites a scene from a tile-based back
 
 **Status**: feature-complete. The code works and is tested; any future changes will be refactoring, cleanup, or optimization.
 
+Tiling Foundry also supplies a separate presentation-only Wang square backend.
+It consumes the versioned JSON boundary without importing the solver or
+changing this legacy pixel-art pipeline.
+
 ## Output
 
 ![example render](output/example.png)
@@ -33,6 +37,29 @@ python main.py <palette.json> <scene.json> <tiles.bin> <sprites.bin> <output.png
 | `sprites.bin` | packed binary sprite sheet (32768 bytes) |
 | `output.png` | rendered output |
 
+### Wang square diagnostic rendering
+
+From this directory, render a `wang-solution-v1` square document with:
+
+```bash
+uv run --locked python wang_square.py \
+  ../tests/fixtures/wang_solution_v1_square_sat.json \
+  output/wang-square.png
+```
+
+Optional `--pixels-per-cell N` and `--margin N` arguments control the dynamic
+canvas. Inclusive coordinate offsets, including negative origins, do not alter
+dense row-major placement. Holes use a neutral checkerboard. Each logical edge
+color receives a deterministic, distinct RGB value, so the backend does not
+collapse the contract's unbounded color IDs into the legacy 16-color palette.
+
+The backend renders every active cell from its named `N`, `E`, `S`, and `W`
+edge colors and writes the PNG with an atomic same-directory replace. It does
+not use `boundary` or `metadata` to select pixels, check edge matching, validate
+SAT correctness, or load `libwang.so`/Z3. A successful PNG is presentation,
+not a proof; correctness remains the responsibility of the independent Tiling
+Foundry verifier before export.
+
 ## Input Format
 
 ### palette.json
@@ -177,9 +204,12 @@ Raises `RenderingException` on pipeline errors.
 ├── main.py               # CLI entry point
 ├── classes.py            # Palette, VirtualVRAM, SceneParser, Blitter, RenderingPipeline
 ├── tests.py              # Test suite (144 tests, all passing)
+├── wang_square.py         # Separate wang-solution-v1 square backend and CLI
+├── test_wang_square.py    # Wang loader, raster, isolation, CLI, and failure tests
 ├── input/                # Example input files (palette, scene, tiles, sprites)
 ├── output/               # Rendered PNG output goes here
 ├── test_data/
+│   ├── wang_solution_v1_square_sat.png # Decoded-pixel golden for the Wang fixture
 │   ├── palette_ok.json             # Valid 16-color palette
 │   ├── palette_wrong_count.json    # Only 3 colors (invalid)
 │   ├── palette_wrong_value.json    # Component > 255 (invalid)
@@ -192,10 +222,17 @@ Raises `RenderingException` on pipeline errors.
 ## Tests
 
 ```bash
-uv run pytest tests.py -v
+uv run --locked pytest -q
+```
+
+The complete isolated suite has 189 tests: the 144 preserved legacy tests
+below and 45 Wang square tests. To run only the original upstream suite:
+
+```bash
+uv run --locked pytest tests.py -v
 ```
 
-144 tests covering all classes:
+The 144 legacy tests cover all original classes:
 
 **Palette (18 tests)**
 - Happy path: load, `__getitem__` first/last, boundary values (0 and 255)

renderer/UPSTREAM.md

@@ -13,14 +13,21 @@ not contain a nested Git repository.
 - License: MIT; the upstream license is preserved in `LICENSE`
 - Import date: 2026-08-25
 
-All files tracked by that commit are present. Production code, tests, assets,
-lockfile, project metadata, and license are byte-for-byte unchanged. The sole
-documentary correction to the imported snapshot is in `README.md`: its stale
-test totals said 135, while collection at the pinned commit yields 144 tests.
-The overall and affected section totals now say 144, 18 Palette, 33
+All files tracked by that commit are present. The imported production code,
+tests, assets, lockfile, project metadata, and license remain byte-for-byte
+unchanged. At import, the sole documentary correction was in `README.md`: its
+stale test totals said 135, while collection at the pinned commit yields 144
+tests. The overall and affected section totals now say 144, 18 Palette, 33
 SceneParser, and 49 Blitter tests. This `UPSTREAM.md` file is local provenance,
 not an upstream file.
 
+Tiling Foundry later added `wang_square.py`, `test_wang_square.py`, and the
+decoded-pixel golden `test_data/wang_solution_v1_square_sat.png`, plus clearly
+separated usage notes in `README.md`. These additions consume
+`wang-solution-v1` as presentation data and do not modify or import the legacy
+PAP modules. They also leave `pyproject.toml`, `uv.lock`, and the pinned
+dependencies unchanged.
+
 ## Verification
 
 The isolated upstream project requires Python 3.14 or newer. Its committed
@@ -35,9 +42,10 @@ uv run --locked pytest --collect-only -q
 uv run --locked pytest -q
 ```
 
-The import baseline is 144 collected tests and 144 passing tests. Keep the
-renderer environment under `renderer/.venv`; its local `.gitignore` excludes
-that environment and generated Python/build files.
+The import baseline remains 144 collected tests and 144 passing tests. The
+combined local suite is 189 tests: 144 preserved legacy tests and 45 Wang
+square tests. Keep the renderer environment under `renderer/.venv`; its local
+`.gitignore` excludes that environment and generated Python/build files.
 
 The preserved `renderer/.github/workflows/ci.yml` is nested upstream evidence;
 GitHub does not run it as a workflow of the containing repository. The
@@ -53,7 +61,8 @@ Treat an update as a separate reviewed change:
    instructions, tracked files, and collected test count.
 3. Run its locked suite in a temporary clone before changing this directory.
 4. Replace the snapshot from `git archive` so no upstream `.git` directory is
-   copied. Preserve this provenance file and document every local difference.
+   copied. Preserve this provenance file and reapply or consciously revise the
+   separately identified Wang files and README sections.
 5. Re-run the renderer suite and the Tiling Foundry repository gates, then
    inspect the complete diff, secrets, and generated artifacts.