mapwright 0.12.0__tar.gz → 0.17.0__tar.gz

{mapwright-0.12.0 → mapwright-0.17.0}/.gitignore

@@ -28,3 +28,4 @@ htmlcov/
 
 # Local working notes (roadmap, scratch)
 *.local.md
+memory/

{mapwright-0.12.0 → mapwright-0.17.0}/CHANGELOG.md

@@ -8,6 +8,81 @@ All notable changes to mapwright are documented here. The format follows
 `tests/test_api_contract.py`). While the version is `0.x`, minor versions may
 make breaking changes; these will always be noted here.
 
+## [0.17.0] — 2026-06-02
+
+### Added
+- **Render themes — `Theme` + `THEMES`.** `RegionalSVGRenderer` now takes a
+  `theme=` (a name or a `Theme`): a palette plus an optional biome *vocabulary*
+  that re-skins the same neutral terrain without regenerating anything. The
+  `Biome` enum is unchanged — a theme only decides how each biome looks and is
+  named — so this is purely additive and the contract is stable. Built-ins:
+  `parchment` (default, **byte-identical** to the previous output), `neon`
+  (Tron / digital-grid), `dune` (Tatooine / sand medium), and `blueprint`.
+  `Theme` is plain hex-string data (JSON-friendly), so a host or image service
+  can author new ones; `Theme.biome_label()` exposes the vocabulary (e.g.
+  `OCEAN` → "Void"). This is the first slice of the "Dominant Medium" /
+  render-theme direction — pair a theme with a matching `ArtPack` for a full
+  restyle. Gallery gains a same-continent neon/dune/blueprint showcase.
+
+## [0.16.0] — 2026-06-02
+
+### Added
+- **`AtlasRenderer` + `ArtPack` — hand-drawn / themed atlas rendering.** A new
+  optional renderer that stamps symbol images from an external *art pack* onto a
+  `TerrainResult` to produce a hand-drawn (or any-style) fantasy-map look:
+  mountains (young/mid/old by `land_age`), hills, forests (pine/deciduous/cactus
+  by climate), dunes, settlements (by marker kind), and sea decorations + a
+  compass rose. mapwright ships **no art** — an art pack is a directory of PNG
+  symbols plus an optional `manifest.json` that maps mapwright's neutral concepts
+  (`Biome`, `land_age`, settlement size) onto art "slots"; a host (e.g. an
+  image-generation service) produces packs in any style and this renderer just
+  places them. `ArtPack.from_directory()` reads a manifest, or auto-discovers
+  slots from a conventional (Nortantis-style) folder layout. Missing fine-grained
+  slots fall back to a coarser sibling, so partial packs still work. Requires
+  Pillow — install the optional extra: `pip install "mapwright[atlas]"`. The
+  core library stays numpy-only; without Pillow, `import mapwright` is unaffected
+  and only `AtlasRenderer` rendering raises a clear install hint.
+
+## [0.15.0] — 2026-06-02
+
+### Added
+- **`land_age` — geological age of the terrain** (a mapwright-original idea). A new
+  `WorldMapConfig` knob: 0 = *young* (jagged, tall, snow-capped peaks — think the
+  Rockies), 1 = *old* (worn down to rounded hills and lowlands — the Appalachians).
+  It shapes the hypsometric curve (a gamma on land elevation → more/fewer mountains)
+  and, for old land, applies weathering passes that smooth the relief. The default
+  (0.5) is neutral — terrain is byte-identical to before, so the feature is purely
+  opt-in. First slice of a broader age/era/wealth axis (forests, settlements next).
+
+## [0.14.0] — 2026-06-02
+
+### Added
+- **Heightmap templates** — an optional, controllable alternative to the default
+  tectonic auto-generation. `RegionalTerrainGenerator.generate(..., template=…)`
+  builds the heightmap from composable elevation ops (hill, pit, range, trough,
+  strait) spread over the cell graph, and `TERRAIN_TEMPLATES` provides named
+  continent archetypes: `continents`, `archipelago`, `peninsula`, `isthmus`,
+  `volcano`, `atoll`. A template sets the *pattern* of high/low ground; `config`
+  still drives sea level (percentile), climate, and rivers on top. Clean-room from
+  the documented idea in Azgaar's Fantasy-Map-Generator (see NOTICE). The default
+  (no template) tectonic terrain is byte-identical — this is purely additive.
+
+## [0.13.0] — 2026-06-02
+
+### Changed
+- **Tectonic-plate terrain.** The heightmap is now built from a simple plate
+  simulation instead of a radial/noise field: the map is tiled into continental
+  and oceanic plates (Voronoi over plate seeds) that drift, and **convergent plate
+  boundaries raise mountain ranges** — so continents get organic coastlines *and*
+  believable linear mountain belts, with no centre bias. The `continents` knob is
+  the number of continental plates; oceanic plates interleave between them, so
+  multi-continent worlds (`archipelago`, `islands`) fragment into scattered islands
+  around an inner sea rather than one blob. Sea level is now **percentile-based**
+  (`sea_level` maps directly to the water fraction). Rivers form reliably across
+  all presets (a flux-quantile source threshold). Clean-room from the documented
+  ideas of Nortantis (tectonics) and the Fractal Worldmap Generator (percentile
+  sea level); see NOTICE. Regenerated the terrain/roads/regions gallery.
+
 ## [0.12.0] — 2026-06-02
 
 ### Changed
@@ -198,7 +273,10 @@ Initial release. Domain-neutral procedural fantasy map & world generation.
   polygons, coastline, rivers, labelled markers. `compute_cell_polygons` rebuilds
   convex Voronoi polygons via half-plane clipping.
 
-[Unreleased]: https://github.com/sligara7/mapwright/compare/v0.12.0...HEAD
+[Unreleased]: https://github.com/sligara7/mapwright/compare/v0.15.0...HEAD
+[0.15.0]: https://github.com/sligara7/mapwright/compare/v0.14.0...v0.15.0
+[0.14.0]: https://github.com/sligara7/mapwright/compare/v0.13.0...v0.14.0
+[0.13.0]: https://github.com/sligara7/mapwright/compare/v0.12.0...v0.13.0
 [0.12.0]: https://github.com/sligara7/mapwright/compare/v0.11.0...v0.12.0
 [0.11.0]: https://github.com/sligara7/mapwright/compare/v0.10.0...v0.11.0
 [0.10.0]: https://github.com/sligara7/mapwright/compare/v0.9.0...v0.10.0

{mapwright-0.12.0 → mapwright-0.17.0}/NOTICE

@@ -14,7 +14,9 @@ copied from them; this NOTICE credits the lineage of the techniques.
     https://github.com/Azgaar/Fantasy-Map-Generator
     Ideas: jittered-grid Voronoi with Lloyd relaxation, flux-accumulation
     rivers, temperature x precipitation -> biome matrix, Markov per-culture
-    name generation, single-seed determinism, SVG cartographic rendering.
+    name generation, single-seed determinism, SVG cartographic rendering,
+    composable heightmap templates (hill/range/pit/trough/strait ops combined
+    into named continent archetypes).
 
 * "Generating fantasy maps" by Martin O'Leary (mewo2), and its C++ implementation
   FantasyMapGenerator by Ryan L. Guy (rlguy) (Zlib License)
@@ -31,5 +33,22 @@ copied from them; this NOTICE credits the lineage of the techniques.
     subdivided into Voronoi wards. mapwright's settlement code is an independent
     clean-room implementation built on its own geometry primitives.
 
+* Nortantis by Joseph Heydorn (AGPLv3)
+    https://github.com/jeheydorn/nortantis
+    Concept only (NO code derived — AGPLv3 is incompatible with this MIT
+    project): the idea of shaping land with a simple tectonic-plate simulation
+    (continental/oceanic plates whose convergent boundaries raise mountain
+    ranges), and the general approach of compositing a map from stamped symbol
+    images. mapwright's plate model and AtlasRenderer are independent clean-room
+    implementations; AtlasRenderer's optional art-pack auto-discovery merely
+    recognises a Nortantis-like folder naming convention (mountains/, hills/,
+    trees/, …) as a data layout — no Nortantis code or art is used or bundled.
+
+* "Fractal Worldmap Generator" by John Olsson / Torben Æ. Mogensen
+    https://www.lysator.liu.se/~johol/fwmg/fwmg.html
+    Ideas (clean-room): a percentile/histogram sea level so a target water
+    fraction is met, and elevation built from many random "faults" rather than a
+    centred radial field.
+
 The name lists ("namebases") bundled with mapwright are original, hand-authored
 data, not derived from any third-party generator.

{mapwright-0.12.0 → mapwright-0.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mapwright
-Version: 0.12.0
+Version: 0.17.0
 Summary: Domain-neutral procedural fantasy map & world generation: Voronoi terrain, hydraulic erosion, biomes, rivers, Markov place-names, and shaded-relief SVG.
 Project-URL: Homepage, https://github.com/sligara7/mapwright
 Project-URL: Repository, https://github.com/sligara7/mapwright
@@ -16,8 +16,11 @@ Classifier: Topic :: Games/Entertainment :: Role-Playing
 Classifier: Topic :: Multimedia :: Graphics
 Requires-Python: >=3.10
 Requires-Dist: numpy>=1.26
+Provides-Extra: atlas
+Requires-Dist: pillow>=10; extra == 'atlas'
 Provides-Extra: dev
 Requires-Dist: hypothesis>=6; extra == 'dev'
+Requires-Dist: pillow>=10; extra == 'dev'
 Requires-Dist: pytest>=7.4; extra == 'dev'
 Requires-Dist: ruff>=0.1; extra == 'dev'
 Description-Content-Type: text/markdown
@@ -38,7 +41,27 @@ own tiles/entities however you like.
 
 ## Gallery
 
-Every image below is a deterministic render of a built-in preset (or a dungeon),
+**`AtlasRenderer`** — the same neutral terrain, skinned with a hand-drawn *art pack*.
+The art here is original, generated through mapwright's companion image service and
+stamped where the physics put it (mountains on the ranges, forests by climate, sea
+serpents offshore). mapwright itself ships no art — the pack is the skin:
+
+<p align="center">
+<img width="640" src="https://raw.githubusercontent.com/sligara7/mapwright/main/docs/gallery/atlas.png" alt="hand-drawn atlas rendered from a sample art pack">
+</p>
+
+**Render themes** — the *same* continent (same cells, rivers, roads, settlements),
+re-skinned by swapping a `Theme` (palette + biome vocabulary). No regeneration:
+
+<table>
+<tr>
+<td align="center"><img width="240" src="https://raw.githubusercontent.com/sligara7/mapwright/main/docs/gallery/theme-neon.png" alt="neon (Tron) theme"><br><sub><code>theme="neon"</code></sub></td>
+<td align="center"><img width="240" src="https://raw.githubusercontent.com/sligara7/mapwright/main/docs/gallery/theme-dune.png" alt="dune (sand) theme"><br><sub><code>theme="dune"</code></sub></td>
+<td align="center"><img width="240" src="https://raw.githubusercontent.com/sligara7/mapwright/main/docs/gallery/theme-blueprint.png" alt="blueprint theme"><br><sub><code>theme="blueprint"</code></sub></td>
+</tr>
+</table>
+
+Below: deterministic shaded-relief renders of each built-in preset (or a dungeon),
 produced by [`examples/gallery.py`](examples/gallery.py):
 
 <table>
@@ -65,10 +88,19 @@ produced by [`examples/gallery.py`](examples/gallery.py):
 <tr>
 <td align="center"><img width="240" src="https://raw.githubusercontent.com/sligara7/mapwright/main/docs/gallery/roads.png" alt="settlements linked by terrain-routed roads"><br><sub><code>RegionalRoadGenerator</code></sub></td>
 <td align="center"><img width="240" src="https://raw.githubusercontent.com/sligara7/mapwright/main/docs/gallery/regions.png" alt="land partitioned into named territories"><br><sub><code>RegionGenerator</code></sub></td>
-<td></td>
+<td align="center"><img width="240" src="https://raw.githubusercontent.com/sligara7/mapwright/main/docs/gallery/template-isthmus.png" alt="isthmus heightmap template"><br><sub><code>template="isthmus"</code></sub></td>
+</tr>
+<tr>
+<td align="center"><img width="240" src="https://raw.githubusercontent.com/sligara7/mapwright/main/docs/gallery/template-atoll.png" alt="atoll heightmap template"><br><sub><code>template="atoll"</code></sub></td>
+<td align="center"><img width="240" src="https://raw.githubusercontent.com/sligara7/mapwright/main/docs/gallery/age-young.png" alt="young jagged terrain"><br><sub><code>land_age=0</code> (young)</sub></td>
+<td align="center"><img width="240" src="https://raw.githubusercontent.com/sligara7/mapwright/main/docs/gallery/age-old.png" alt="old worn terrain"><br><sub><code>land_age=1</code> (old)</sub></td>
 </tr>
 </table>
 
+The two right-hand maps above are the **same continent** at `land_age=0` (young, jagged,
+snow-capped peaks) vs `land_age=1` (old, worn down to rounded hills) — a mapwright-original
+"geological age" knob.
+
 Regenerate them with `python examples/gallery.py` (SVGs always; PNGs when
 `cairosvg` is installed).
 
@@ -76,6 +108,8 @@ Regenerate them with `python examples/gallery.py` (SVGs always; PNGs when
 
 ```bash
 pip install mapwright
+# hand-drawn / themed atlas rendering (adds Pillow):
+pip install "mapwright[atlas]"
 # latest from git:
 pip install git+https://github.com/sligara7/mapwright.git
 # or, for local development:
@@ -112,6 +146,18 @@ WorldMapConfig.from_dict({"temperature": 5, "continents": -3})  # -> safe, clamp
 Presets: `continent`, `pangaea`, `archipelago`, `islands`, `highlands`, `desert`,
 `arctic`, `tropical`.
 
+Terrain defaults to a **tectonic-plate** simulation (organic coasts + mountain ranges).
+For a controllable continent *archetype*, pass a `template` (Azgaar-style composed
+heightmap ops) — `config` still drives sea level, climate, and rivers on top of it:
+
+```python
+from mapwright import RegionalTerrainGenerator, SeededRNG, WorldMapConfig, TERRAIN_TEMPLATES
+
+print(list(TERRAIN_TEMPLATES))   # archipelago, volcano, peninsula, isthmus, atoll, continents
+world = RegionalTerrainGenerator(SeededRNG(5)).generate(
+    80, 58, WorldMapConfig(sea_level=0.55), template="archipelago")
+```
+
 Save and reload worlds (and dungeons) — JSON round-trips losslessly, so a reloaded
 world renders byte-identically:
 
@@ -169,9 +215,11 @@ Settlement presets: `hamlet`, `village`, `town`, `city`, `port`, `citadel`.
 |-----------|--------------|
 | `SeededRNG` | One seed drives everything; `.derive(label)` yields independent, reproducible sub-streams (unifies stdlib + numpy). |
 | `NameGenerator` | Order-k character Markov names over hand-authored culture namebases; reproducible across processes. |
-| `RegionalTerrainGenerator` | Voronoi cells (Lloyd-relaxed) → noise-shaped **organic** land/sea mask + distance-to-coast elevation → Planchon–Darboux depression fill → flux + hydraulic/creep erosion → rivers + inland lakes → latitude/elevation climate with **rain-shadow** → Whittaker biomes. |
+| `RegionalTerrainGenerator` | Voronoi cells (Lloyd-relaxed) → **tectonic-plate** heightmap (organic coasts + mountain ranges at plate collisions; percentile sea level) → Planchon–Darboux depression fill → flux + hydraulic/creep erosion → rivers + inland lakes → latitude/elevation climate with **rain-shadow** → Whittaker biomes. |
 | `compute_cell_polygons` | Reconstructs convex Voronoi polygons (half-plane clipping) for vector rendering. |
-| `RegionalSVGRenderer` | Shaded-relief (hillshade) SVG: biome polygons, coastline, rivers, roads, labelled markers. |
+| `RegionalSVGRenderer` | Shaded-relief (hillshade) SVG: biome polygons, coastline, rivers, roads, labelled markers. Takes a `theme=`. |
+| `Theme` / `THEMES` | A render palette + biome vocabulary; re-skins the same terrain (parchment / neon / dune / blueprint, or your own). The "Dominant Medium" layer. |
+| `AtlasRenderer` / `ArtPack` | Hand-drawn / themed PNG: stamps symbols from an external *art pack* (mountains, forests, hills, settlements, sea decorations) onto the terrain. mapwright ships no art — a pack is a skin. Needs `pip install "mapwright[atlas]"`. |
 | `RegionalRoadGenerator` | Connects settlement sites with trade routes — an MST whose edges are A*-routed over the terrain (avoids sea, climbs/crosses rivers at a cost). |
 | `RegionGenerator` | Partitions land into named factions/territories: spread capitals seed a flood fill over the land graph (sea divides them); each `Region` is Markov-named. |
 | `DungeonGenerator` | BSP-partitioned rooms + minimum-spanning-tree corridors → rooms, corridor cells, and a walkable grid (with `Dungeon.ascii()`). |
@@ -182,6 +230,77 @@ Settlement presets: `hamlet`, `village`, `town`, `city`, `port`, `citadel`.
 Everything is neutral: `RegionalTerrainGenerator` returns a `TerrainResult` of `TerrainCell`s
 (each with a `Biome`), and you decide how a `Biome` maps to your world.
 
+## Atlas rendering & art packs
+
+`RegionalSVGRenderer` draws a clean shaded-relief map. For a **hand-drawn** (or neon, or
+scrap-metal, or any) look, `AtlasRenderer` stamps little symbol images — mountains, trees,
+hills, towns, sea monsters, a compass — placed exactly where the physics put them.
+
+mapwright bundles **no art**. The renderer is the *engine*; the art is a separate **art pack**
+you point it at, so the same world can wear any style without re-generating anything:
+
+```python
+from mapwright import SeededRNG, RegionalTerrainGenerator, ArtPack, AtlasRenderer, Marker
+
+terrain = RegionalTerrainGenerator(SeededRNG(7)).generate(80, 56)
+markers = [Marker("Eldmoor", 40, 28, kind="settlement_castle")]
+
+pack = ArtPack.from_directory("path/to/my-art-pack")   # needs mapwright[atlas]
+png = AtlasRenderer(pack, scale=12, seed=7).render(terrain, markers, land_age=0.3)
+open("atlas.png", "wb").write(png)
+```
+
+An **art pack** is just a directory of transparent PNG symbols plus an optional
+`manifest.json` that maps mapwright's neutral concepts onto art **slots**:
+
+```jsonc
+{
+  "name": "my-pack",
+  "colors": {"parchment": "#ecdfbf", "water": "#b5cad1",
+             "coast": "#463c2c", "label": "#2b2218"},
+  "slots": {
+    "mountain.young": {"files": ["mountains/sharp/*.png"], "width": 2.0, "anchor": "bottom"},
+    "mountain.old":   {"files": ["mountains/eroded/*.png"]},
+    "hill":           {"files": ["hills/*.png"]},
+    "tree.pine":      {"files": ["trees/pine/*.png"]},
+    "tree.deciduous": {"files": ["trees/leafy/*.png"]},
+    "city.castle":    {"files": ["cities/castle*.png"]},
+    "decoration.compass": {"files": ["compass/*.png"], "anchor": "center"}
+  }
+}
+```
+
+Slots the renderer asks for: terrain relief — `mountain.young` / `mountain.mid` /
+`mountain.old` (chosen by `land_age`), `hill`, `tree.pine` / `tree.deciduous` /
+`tree.cactus` (by climate), `dune`; settlements — `city.castle` / `city.large` /
+`city.town` / `city.village` (by marker `kind`); decorations — `decoration.creature`
+/ `decoration.ship` / `decoration.compass`. A missing fine slot falls back to a coarser
+sibling (`mountain.mid` → any `mountain.*`), so partial packs still render. With **no**
+`manifest.json`, `ArtPack.from_directory()` auto-discovers slots from a conventional
+folder layout. Because packs are pure data, a host like an image-generation service can
+**produce them on demand** in any style — the generation stays the same; the pack is the skin.
+
+### Render themes
+
+The vector `RegionalSVGRenderer` takes a **`Theme`** — a palette plus an optional biome
+*vocabulary* — so the same neutral terrain re-skins into wildly different worlds without
+regenerating anything. The neutral `Biome` enum never changes; a theme just decides how
+each biome looks and is named:
+
+```python
+from mapwright import RegionalSVGRenderer, THEMES
+
+svg = RegionalSVGRenderer(theme="neon").render(terrain, markers, roads=roads)
+# built-ins: "parchment" (default), "neon" (Tron/digital-grid), "dune" (sand), "blueprint"
+THEMES["neon"].biome_label(Biome.OCEAN)   # -> "Void"  (the vocabulary layer)
+```
+
+A `Theme` is plain hex-string data (JSON-friendly), so a host — or the same image service
+that makes art packs — can author new ones. This is the "Dominant Medium" idea from
+mapwright's longer-term vision: a sand planet, a digital grid, and an irradiated waste are
+the *same map* wearing different skins. Pair a theme with a matching `ArtPack` for a full
+restyle of both the vector and hand-drawn renders.
+
 ## Determinism
 
 Every generator draws from a `SeededRNG`. The same seed (and parameters) reproduces an

{mapwright-0.12.0 → mapwright-0.17.0}/README.md

@@ -14,7 +14,27 @@ own tiles/entities however you like.
 
 ## Gallery
 
-Every image below is a deterministic render of a built-in preset (or a dungeon),
+**`AtlasRenderer`** — the same neutral terrain, skinned with a hand-drawn *art pack*.
+The art here is original, generated through mapwright's companion image service and
+stamped where the physics put it (mountains on the ranges, forests by climate, sea
+serpents offshore). mapwright itself ships no art — the pack is the skin:
+
+<p align="center">
+<img width="640" src="https://raw.githubusercontent.com/sligara7/mapwright/main/docs/gallery/atlas.png" alt="hand-drawn atlas rendered from a sample art pack">
+</p>
+
+**Render themes** — the *same* continent (same cells, rivers, roads, settlements),
+re-skinned by swapping a `Theme` (palette + biome vocabulary). No regeneration:
+
+<table>
+<tr>
+<td align="center"><img width="240" src="https://raw.githubusercontent.com/sligara7/mapwright/main/docs/gallery/theme-neon.png" alt="neon (Tron) theme"><br><sub><code>theme="neon"</code></sub></td>
+<td align="center"><img width="240" src="https://raw.githubusercontent.com/sligara7/mapwright/main/docs/gallery/theme-dune.png" alt="dune (sand) theme"><br><sub><code>theme="dune"</code></sub></td>
+<td align="center"><img width="240" src="https://raw.githubusercontent.com/sligara7/mapwright/main/docs/gallery/theme-blueprint.png" alt="blueprint theme"><br><sub><code>theme="blueprint"</code></sub></td>
+</tr>
+</table>
+
+Below: deterministic shaded-relief renders of each built-in preset (or a dungeon),
 produced by [`examples/gallery.py`](examples/gallery.py):
 
 <table>
@@ -41,10 +61,19 @@ produced by [`examples/gallery.py`](examples/gallery.py):
 <tr>
 <td align="center"><img width="240" src="https://raw.githubusercontent.com/sligara7/mapwright/main/docs/gallery/roads.png" alt="settlements linked by terrain-routed roads"><br><sub><code>RegionalRoadGenerator</code></sub></td>
 <td align="center"><img width="240" src="https://raw.githubusercontent.com/sligara7/mapwright/main/docs/gallery/regions.png" alt="land partitioned into named territories"><br><sub><code>RegionGenerator</code></sub></td>
-<td></td>
+<td align="center"><img width="240" src="https://raw.githubusercontent.com/sligara7/mapwright/main/docs/gallery/template-isthmus.png" alt="isthmus heightmap template"><br><sub><code>template="isthmus"</code></sub></td>
+</tr>
+<tr>
+<td align="center"><img width="240" src="https://raw.githubusercontent.com/sligara7/mapwright/main/docs/gallery/template-atoll.png" alt="atoll heightmap template"><br><sub><code>template="atoll"</code></sub></td>
+<td align="center"><img width="240" src="https://raw.githubusercontent.com/sligara7/mapwright/main/docs/gallery/age-young.png" alt="young jagged terrain"><br><sub><code>land_age=0</code> (young)</sub></td>
+<td align="center"><img width="240" src="https://raw.githubusercontent.com/sligara7/mapwright/main/docs/gallery/age-old.png" alt="old worn terrain"><br><sub><code>land_age=1</code> (old)</sub></td>
 </tr>
 </table>
 
+The two right-hand maps above are the **same continent** at `land_age=0` (young, jagged,
+snow-capped peaks) vs `land_age=1` (old, worn down to rounded hills) — a mapwright-original
+"geological age" knob.
+
 Regenerate them with `python examples/gallery.py` (SVGs always; PNGs when
 `cairosvg` is installed).
 
@@ -52,6 +81,8 @@ Regenerate them with `python examples/gallery.py` (SVGs always; PNGs when
 
 ```bash
 pip install mapwright
+# hand-drawn / themed atlas rendering (adds Pillow):
+pip install "mapwright[atlas]"
 # latest from git:
 pip install git+https://github.com/sligara7/mapwright.git
 # or, for local development:
@@ -88,6 +119,18 @@ WorldMapConfig.from_dict({"temperature": 5, "continents": -3})  # -> safe, clamp
 Presets: `continent`, `pangaea`, `archipelago`, `islands`, `highlands`, `desert`,
 `arctic`, `tropical`.
 
+Terrain defaults to a **tectonic-plate** simulation (organic coasts + mountain ranges).
+For a controllable continent *archetype*, pass a `template` (Azgaar-style composed
+heightmap ops) — `config` still drives sea level, climate, and rivers on top of it:
+
+```python
+from mapwright import RegionalTerrainGenerator, SeededRNG, WorldMapConfig, TERRAIN_TEMPLATES
+
+print(list(TERRAIN_TEMPLATES))   # archipelago, volcano, peninsula, isthmus, atoll, continents
+world = RegionalTerrainGenerator(SeededRNG(5)).generate(
+    80, 58, WorldMapConfig(sea_level=0.55), template="archipelago")
+```
+
 Save and reload worlds (and dungeons) — JSON round-trips losslessly, so a reloaded
 world renders byte-identically:
 
@@ -145,9 +188,11 @@ Settlement presets: `hamlet`, `village`, `town`, `city`, `port`, `citadel`.
 |-----------|--------------|
 | `SeededRNG` | One seed drives everything; `.derive(label)` yields independent, reproducible sub-streams (unifies stdlib + numpy). |
 | `NameGenerator` | Order-k character Markov names over hand-authored culture namebases; reproducible across processes. |
-| `RegionalTerrainGenerator` | Voronoi cells (Lloyd-relaxed) → noise-shaped **organic** land/sea mask + distance-to-coast elevation → Planchon–Darboux depression fill → flux + hydraulic/creep erosion → rivers + inland lakes → latitude/elevation climate with **rain-shadow** → Whittaker biomes. |
+| `RegionalTerrainGenerator` | Voronoi cells (Lloyd-relaxed) → **tectonic-plate** heightmap (organic coasts + mountain ranges at plate collisions; percentile sea level) → Planchon–Darboux depression fill → flux + hydraulic/creep erosion → rivers + inland lakes → latitude/elevation climate with **rain-shadow** → Whittaker biomes. |
 | `compute_cell_polygons` | Reconstructs convex Voronoi polygons (half-plane clipping) for vector rendering. |
-| `RegionalSVGRenderer` | Shaded-relief (hillshade) SVG: biome polygons, coastline, rivers, roads, labelled markers. |
+| `RegionalSVGRenderer` | Shaded-relief (hillshade) SVG: biome polygons, coastline, rivers, roads, labelled markers. Takes a `theme=`. |
+| `Theme` / `THEMES` | A render palette + biome vocabulary; re-skins the same terrain (parchment / neon / dune / blueprint, or your own). The "Dominant Medium" layer. |
+| `AtlasRenderer` / `ArtPack` | Hand-drawn / themed PNG: stamps symbols from an external *art pack* (mountains, forests, hills, settlements, sea decorations) onto the terrain. mapwright ships no art — a pack is a skin. Needs `pip install "mapwright[atlas]"`. |
 | `RegionalRoadGenerator` | Connects settlement sites with trade routes — an MST whose edges are A*-routed over the terrain (avoids sea, climbs/crosses rivers at a cost). |
 | `RegionGenerator` | Partitions land into named factions/territories: spread capitals seed a flood fill over the land graph (sea divides them); each `Region` is Markov-named. |
 | `DungeonGenerator` | BSP-partitioned rooms + minimum-spanning-tree corridors → rooms, corridor cells, and a walkable grid (with `Dungeon.ascii()`). |
@@ -158,6 +203,77 @@ Settlement presets: `hamlet`, `village`, `town`, `city`, `port`, `citadel`.
 Everything is neutral: `RegionalTerrainGenerator` returns a `TerrainResult` of `TerrainCell`s
 (each with a `Biome`), and you decide how a `Biome` maps to your world.
 
+## Atlas rendering & art packs
+
+`RegionalSVGRenderer` draws a clean shaded-relief map. For a **hand-drawn** (or neon, or
+scrap-metal, or any) look, `AtlasRenderer` stamps little symbol images — mountains, trees,
+hills, towns, sea monsters, a compass — placed exactly where the physics put them.
+
+mapwright bundles **no art**. The renderer is the *engine*; the art is a separate **art pack**
+you point it at, so the same world can wear any style without re-generating anything:
+
+```python
+from mapwright import SeededRNG, RegionalTerrainGenerator, ArtPack, AtlasRenderer, Marker
+
+terrain = RegionalTerrainGenerator(SeededRNG(7)).generate(80, 56)
+markers = [Marker("Eldmoor", 40, 28, kind="settlement_castle")]
+
+pack = ArtPack.from_directory("path/to/my-art-pack")   # needs mapwright[atlas]
+png = AtlasRenderer(pack, scale=12, seed=7).render(terrain, markers, land_age=0.3)
+open("atlas.png", "wb").write(png)
+```
+
+An **art pack** is just a directory of transparent PNG symbols plus an optional
+`manifest.json` that maps mapwright's neutral concepts onto art **slots**:
+
+```jsonc
+{
+  "name": "my-pack",
+  "colors": {"parchment": "#ecdfbf", "water": "#b5cad1",
+             "coast": "#463c2c", "label": "#2b2218"},
+  "slots": {
+    "mountain.young": {"files": ["mountains/sharp/*.png"], "width": 2.0, "anchor": "bottom"},
+    "mountain.old":   {"files": ["mountains/eroded/*.png"]},
+    "hill":           {"files": ["hills/*.png"]},
+    "tree.pine":      {"files": ["trees/pine/*.png"]},
+    "tree.deciduous": {"files": ["trees/leafy/*.png"]},
+    "city.castle":    {"files": ["cities/castle*.png"]},
+    "decoration.compass": {"files": ["compass/*.png"], "anchor": "center"}
+  }
+}
+```
+
+Slots the renderer asks for: terrain relief — `mountain.young` / `mountain.mid` /
+`mountain.old` (chosen by `land_age`), `hill`, `tree.pine` / `tree.deciduous` /
+`tree.cactus` (by climate), `dune`; settlements — `city.castle` / `city.large` /
+`city.town` / `city.village` (by marker `kind`); decorations — `decoration.creature`
+/ `decoration.ship` / `decoration.compass`. A missing fine slot falls back to a coarser
+sibling (`mountain.mid` → any `mountain.*`), so partial packs still render. With **no**
+`manifest.json`, `ArtPack.from_directory()` auto-discovers slots from a conventional
+folder layout. Because packs are pure data, a host like an image-generation service can
+**produce them on demand** in any style — the generation stays the same; the pack is the skin.
+
+### Render themes
+
+The vector `RegionalSVGRenderer` takes a **`Theme`** — a palette plus an optional biome
+*vocabulary* — so the same neutral terrain re-skins into wildly different worlds without
+regenerating anything. The neutral `Biome` enum never changes; a theme just decides how
+each biome looks and is named:
+
+```python
+from mapwright import RegionalSVGRenderer, THEMES
+
+svg = RegionalSVGRenderer(theme="neon").render(terrain, markers, roads=roads)
+# built-ins: "parchment" (default), "neon" (Tron/digital-grid), "dune" (sand), "blueprint"
+THEMES["neon"].biome_label(Biome.OCEAN)   # -> "Void"  (the vocabulary layer)
+```
+
+A `Theme` is plain hex-string data (JSON-friendly), so a host — or the same image service
+that makes art packs — can author new ones. This is the "Dominant Medium" idea from
+mapwright's longer-term vision: a sand planet, a digital grid, and an irradiated waste are
+the *same map* wearing different skins. Pair a theme with a matching `ArtPack` for a full
+restyle of both the vector and hand-drawn renders.
+
 ## Determinism
 
 Every generator draws from a `SeededRNG`. The same seed (and parameters) reproduces an