mapwright 0.2.0__tar.gz → 0.10.0__tar.gz

{mapwright-0.2.0 → mapwright-0.10.0}/.github/workflows/ci.yml

@@ -13,8 +13,8 @@ jobs:
       matrix:
         python-version: ["3.10", "3.11", "3.12", "3.13"]
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install

{mapwright-0.2.0 → mapwright-0.10.0}/.github/workflows/publish.yml

@@ -14,15 +14,15 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.12"
       - name: Build sdist + wheel
         run: |
           python -m pip install --upgrade build
           python -m build
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v7
         with:
           name: dist
           path: dist/
@@ -35,7 +35,7 @@ jobs:
       id-token: write          # REQUIRED for Trusted Publishing (OIDC)
       contents: read
     steps:
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@v8
         with:
           name: dist
           path: dist/

{mapwright-0.2.0 → mapwright-0.10.0}/.gitignore

@@ -25,3 +25,6 @@ htmlcov/
 # Generated preview artifacts
 *.preview.svg
 *.preview.png
+
+# Local working notes (roadmap, scratch)
+*.local.md

mapwright-0.10.0/CHANGELOG.md

@@ -0,0 +1,190 @@
+# Changelog
+
+All notable changes to mapwright are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/), and the project aims to follow
+[Semantic Versioning](https://semver.org/).
+
+**Public API** = the names exported in `mapwright.__all__` (pinned by
+`tests/test_api_contract.py`). While the version is `0.x`, minor versions may
+make breaking changes; these will always be noted here.
+
+## [Unreleased]
+
+### Added
+- Property-based tests (Hypothesis, a new dev dependency) over config clamping,
+  the geometry/graph primitives, and generation round-trips. Test-only — no
+  change to the public API.
+- `examples/benchmark.py` — micro-benchmarks for the generators, and a
+  **Performance** section in the README documenting the 1500-cell terrain cap,
+  the per-pixel rasterisation cost on large maps, and the dungeon MST scaling.
+
+## [0.10.0] — 2026-06-02
+
+### Added
+- **Region / faction assignment** — `RegionGenerator.generate(terrain, count=…)`
+  partitions the land into named territories: well-spread capital cells
+  (farthest-point sampling) seed a multi-source flood fill over the land-cell
+  graph, so each reachable land cell joins its nearest capital's region (the sea
+  divides them). Returns `Region` objects (name, capital cell, member cells);
+  region names come from the Markov `NameGenerator`. `RegionalSVGRenderer.render(
+  ..., regions=…)` draws political borders and italic region labels.
+
+## [0.9.0] — 2026-06-02
+
+### Added
+- **Regional roads / trade routes** — `RegionalRoadGenerator.generate(terrain, sites)`
+  connects settlement sites with a road network: a minimum spanning tree over the
+  sites whose edges are A*-routed over the terrain cell graph, preferring flat land
+  and paying penalties for sea, lakes, rivers (bridges), and uphill slope. Returns
+  `Road` objects (lists of cell ids); `RegionalSVGRenderer.render(..., roads=…)`
+  draws them as dashed routes with a pale casing.
+- **Generic A* (`_graph.astar`)** — an internal shortest-path primitive over an
+  arbitrary graph (neighbour + cost + heuristic callbacks), alongside `prim_mst`.
+
+## [0.8.0] — 2026-06-01
+
+### Added
+- **Inland lakes** — `RegionalTerrainGenerator` now flags interior hollows (land
+  cells lower than most neighbours that collect real flux) as lakes: a new
+  `Biome.LAKE`, an `is_lake` flag on `TerrainCell`, and a bounded
+  `WorldMapConfig.lake_density` knob. Lakes seed the moisture model and rivers
+  terminate into them; `RegionalSVGRenderer` draws them as flat freshwater.
+- **Rain-shadow climate** — moisture is now attenuated on the lee of high terrain.
+  A prevailing wind is swept upwind→downwind over the cell graph; air rising over
+  mountains precipitates (wet windward slopes) and arrives dry on the far side, so
+  windward/leeward biome contrast emerges naturally.
+
+### Changed
+- `TerrainCell` gains an `is_lake` field and `TerrainResult` serialisation bumps to
+  `mapwright/terrain@2`; older `@1` payloads still load (`is_lake` defaults False).
+  `WorldMapConfig` gains `lake_density` (old payloads use its default). `Biome` adds
+  `LAKE = 12`. The `desert` preset sets a low `lake_density` for aridity.
+
+## [0.7.0] — 2026-06-01
+
+### Added
+- **Settlement walls** — a defensive wall when `walled=True`, completing the
+  settlement tier. `Wall` (ring, closed, gates) is added to the public surface
+  and `Settlement.wall` holds it. The wall follows the footprint perimeter with a
+  tower at each corner and gate gaps where the main roads exit; on a coastal town
+  the ring is opened along the coast (a harbour, no wall over water).
+  `SettlementSVGRenderer` draws the wall, round corner towers, and square
+  gatehouses at the gates (replacing the previous heavier-boundary placeholder).
+  Added a walled `citadel` to the gallery.
+
+### Changed
+- `Settlement` serialisation tag bumped to `mapwright/settlement@4` (adds
+  `wall`); older payloads without it still load (`wall` defaults to `None`).
+
+## [0.6.0] — 2026-06-01
+
+### Added
+- **Settlement streets** — a road network over the wards. `Street` (path, kind)
+  is added to the public surface; `Settlement` gains `streets` and `gates`.
+  Wards are connected by a minimum-spanning-tree (the shared `prim_mst`) over
+  ward adjacency — detected from shared polygon edges — plus a few loop roads;
+  each minor street runs through the two ward centres via their shared-edge
+  midpoint. A few gates are placed around the footprint (plus a harbour gate on
+  the coast when `coastal=True`), and `"main"` roads connect each gate to the
+  market. `SettlementSVGRenderer` overlays the network (casing + pale surface,
+  main roads wider) with a `show_streets` toggle.
+
+### Changed
+- `Settlement` serialisation tag bumped to `mapwright/settlement@3` (adds
+  `streets` and `gates`); older payloads without those keys still load (they
+  default to empty).
+
+## [0.5.0] — 2026-06-01
+
+### Added
+- **Settlement lots** — wards are now subdivided into building plots. `Lot`
+  (id, polygon, ward) is added to the public surface and `Settlement.lots` lists
+  them; `SettlementSVGRenderer` draws the building footprints (toggle with
+  `show_lots`). Each buildable ward is recursively bisected across its longest
+  axis down to a target plot area — a new bounded `SettlementConfig.lot_size`
+  knob — with per-kind sizing (noble = large estates, slums = cramped, market =
+  an open square with no buildings); each plot is inset so gaps read as alleys.
+  New shared geometry primitives: `polygon_area`, `inset_convex`.
+
+### Changed
+- `Settlement` serialisation tag bumped to `mapwright/settlement@2` (adds
+  `lots`); older `@1` payloads without a `lots` key still load (lots default to
+  empty), and `SettlementConfig` gains `lot_size` (old payloads use its default).
+
+## [0.4.0] — 2026-06-01
+
+### Added
+- **Settlement tier (wards)** — `SettlementGenerator` → `Settlement` (+ `SettlementConfig`,
+  `Ward`, `SETTLEMENT_PRESETS`, and `SettlementSVGRenderer`). Self-contained town
+  *layout*: an organic convex footprint divided into named Voronoi wards (a central
+  market, residential/craftsmen/temple/noble/garrison/slums mix, plus a dockside ward
+  and synthetic coastline when `coastal=True`); `walled` is recorded for the upcoming
+  wall layer. Config follows the `WorldMapConfig` discipline (bounded knobs + boolean
+  flags, `from_dict` clamping, `json_schema()`, presets) and the result round-trips
+  via `to_dict`/`from_dict`/`to_json`/`from_json`. Clean-room from the *ideas* of
+  Watabou's TownGeneratorOS (GPLv3) — concept only, no code; see NOTICE.
+  _This is the first slice of the tier; lots, streets, and walls follow in later
+  versions, and the `Settlement`/`Ward` shapes will grow accordingly._
+
+### Changed
+- Internal refactor: extracted the shared Voronoi/Lloyd, half-plane polygon
+  clipping, and Prim-MST primitives into `_geometry.py` / `_graph.py`; the terrain
+  and dungeon tiers now delegate to them (no behaviour change — same seeds produce
+  byte-identical output). New tiers build on these instead of re-implementing them.
+
+## [0.3.0] — 2026-06-01
+
+### Added
+- **Dungeon SVG renderer** — `DungeonSVGRenderer.render(dungeon, …)` turns a
+  `Dungeon` into a scalable SVG (dark walls, carved floor from the walkable grid,
+  room outlines, optional faint tile grid via `show_grid`, optional per-room
+  labels via `labels=True`/a sequence). Mirrors `RegionalSVGRenderer`: pure
+  string-building, no new dependency. Closes the previously ascii-only gap for
+  dungeons.
+- **Serialisation / JSON round-trip** — `to_dict`/`from_dict` and
+  `to_json`/`from_json` on `TerrainResult`, `Dungeon`, and `Marker` (plus
+  `to_dict`/`from_dict` on the nested `TerrainCell`, `River`, and `Rect`). A saved
+  world or dungeon reloads bit-identically — numpy rasters (`cell_of`, dungeon
+  `grid`) and full-precision floats are preserved, so a reloaded world renders to
+  byte-identical SVG. Payloads carry a `schema` tag and ignore unknown keys on
+  load (forward-compatible). No new dependency; pure-JSON builtins only.
+
+## [0.2.0] — 2026-06-01
+
+### Added
+- **Dungeon generation** — `DungeonGenerator` → `Dungeon` (+ `DungeonConfig`, `Rect`):
+  BSP space-partitioning rooms (no overlap) connected by a Prim minimum-spanning-tree
+  of L-corridors, plus optional loop corridors. Returns rooms, carved corridor cells,
+  and a boolean walkable grid; `Dungeon.ascii()` for quick previews. Clean-room from
+  Dungeon-Generator (MIT, BSP) and donjuan (CC0, MST connectivity).
+
+## [0.1.0] — 2026-06-01
+
+Initial release. Domain-neutral procedural fantasy map & world generation.
+
+### Added
+- `SeededRNG` — one-seed determinism with `.derive(label)` sub-streams; unifies
+  the stdlib and numpy generators. Reproducible across processes.
+- `NameGenerator` / `MarkovNameGenerator` — order-k Markov place/person names
+  over hand-authored culture namebases (`NAMEBASES`); hash-seed independent.
+- `RegionalTerrainGenerator` → `TerrainResult` — Voronoi cells (Lloyd-relaxed),
+  Planchon–Darboux depression fill, hydraulic + creep erosion, river tracing,
+  latitude/elevation climate, and a Whittaker `Biome` matrix.
+- `WorldMapConfig` — bounded, documented world parameters (sea level, continents,
+  climate, mountains, rivers) with `from_dict` clamping, named `PRESETS`, and a
+  `json_schema()` contract for host/LLM population.
+- `RegionalSVGRenderer` + `Marker` — shaded-relief (hillshade) SVG: biome
+  polygons, coastline, rivers, labelled markers. `compute_cell_polygons` rebuilds
+  convex Voronoi polygons via half-plane clipping.
+
+[Unreleased]: https://github.com/sligara7/mapwright/compare/v0.10.0...HEAD
+[0.10.0]: https://github.com/sligara7/mapwright/compare/v0.9.0...v0.10.0
+[0.9.0]: https://github.com/sligara7/mapwright/compare/v0.8.0...v0.9.0
+[0.8.0]: https://github.com/sligara7/mapwright/compare/v0.7.0...v0.8.0
+[0.7.0]: https://github.com/sligara7/mapwright/compare/v0.6.0...v0.7.0
+[0.6.0]: https://github.com/sligara7/mapwright/compare/v0.5.0...v0.6.0
+[0.5.0]: https://github.com/sligara7/mapwright/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/sligara7/mapwright/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/sligara7/mapwright/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/sligara7/mapwright/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/sligara7/mapwright/releases/tag/v0.1.0

{mapwright-0.2.0 → mapwright-0.10.0}/NOTICE

@@ -24,5 +24,12 @@ copied from them; this NOTICE credits the lineage of the techniques.
     slope^2), Planchon-Darboux depression filling for guaranteed drainage,
     slope-normal hillshade ("shaded relief") rendering.
 
+* Watabou's TownGeneratorOS (GPLv3)
+    https://github.com/watabou/TownGeneratorOS
+    Concept only (NO code derived — GPLv3 is incompatible with this MIT
+    project): the high-level idea of generating a town as an organic footprint
+    subdivided into Voronoi wards. mapwright's settlement code is an independent
+    clean-room implementation built on its own geometry primitives.
+
 The name lists ("namebases") bundled with mapwright are original, hand-authored
 data, not derived from any third-party generator.

mapwright-0.10.0/PKG-INFO

@@ -0,0 +1,242 @@
+Metadata-Version: 2.4
+Name: mapwright
+Version: 0.10.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
+Author: Anthony Sligar
+License: MIT
+License-File: LICENSE
+License-File: NOTICE
+Keywords: biomes,erosion,fantasy-map,procedural-generation,svg,terrain,ttrpg,voronoi,worldgen
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Games/Entertainment :: Role-Playing
+Classifier: Topic :: Multimedia :: Graphics
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.26
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# mapwright
+
+> ⚠️ **Early development (v0.x, alpha).** The API is still moving and may change without
+> notice between versions. Extracted from a working application; usable today, but pin a
+> commit if you depend on it.
+
+**Domain-neutral procedural fantasy map & world generation** — Voronoi terrain with
+hydraulic erosion, climate-driven biomes, rivers, Markov place-names, and shaded-relief
+SVG rendering. Pure Python, `numpy`-only, fully seed-deterministic.
+
+mapwright produces *neutral data* (cells, biomes, rivers, polygons) and a self-contained
+SVG renderer. It has no opinion about your application's models — map its output onto your
+own tiles/entities however you like.
+
+## Gallery
+
+Every image below is a deterministic render of a built-in preset (or a dungeon),
+produced by [`examples/gallery.py`](examples/gallery.py):
+
+<table>
+<tr>
+<td align="center"><img width="240" src="https://raw.githubusercontent.com/sligara7/mapwright/main/docs/gallery/continent.png" alt="continent preset"><br><sub><code>continent</code></sub></td>
+<td align="center"><img width="240" src="https://raw.githubusercontent.com/sligara7/mapwright/main/docs/gallery/archipelago.png" alt="archipelago preset"><br><sub><code>archipelago</code></sub></td>
+<td align="center"><img width="240" src="https://raw.githubusercontent.com/sligara7/mapwright/main/docs/gallery/islands.png" alt="islands preset"><br><sub><code>islands</code></sub></td>
+</tr>
+<tr>
+<td align="center"><img width="240" src="https://raw.githubusercontent.com/sligara7/mapwright/main/docs/gallery/highlands.png" alt="highlands preset"><br><sub><code>highlands</code></sub></td>
+<td align="center"><img width="240" src="https://raw.githubusercontent.com/sligara7/mapwright/main/docs/gallery/desert.png" alt="desert preset"><br><sub><code>desert</code></sub></td>
+<td align="center"><img width="240" src="https://raw.githubusercontent.com/sligara7/mapwright/main/docs/gallery/arctic.png" alt="arctic preset"><br><sub><code>arctic</code></sub></td>
+</tr>
+<tr>
+<td align="center"><img width="240" src="https://raw.githubusercontent.com/sligara7/mapwright/main/docs/gallery/pangaea.png" alt="pangaea preset"><br><sub><code>pangaea</code></sub></td>
+<td align="center"><img width="240" src="https://raw.githubusercontent.com/sligara7/mapwright/main/docs/gallery/tropical.png" alt="tropical preset"><br><sub><code>tropical</code></sub></td>
+<td align="center"><img width="240" src="https://raw.githubusercontent.com/sligara7/mapwright/main/docs/gallery/dungeon.png" alt="generated dungeon"><br><sub><code>DungeonGenerator</code></sub></td>
+</tr>
+<tr>
+<td align="center"><img width="240" src="https://raw.githubusercontent.com/sligara7/mapwright/main/docs/gallery/town.png" alt="generated town"><br><sub><code>SettlementGenerator</code></sub></td>
+<td align="center"><img width="240" src="https://raw.githubusercontent.com/sligara7/mapwright/main/docs/gallery/port.png" alt="generated coastal port"><br><sub><code>Settlement (port)</code></sub></td>
+<td align="center"><img width="240" src="https://raw.githubusercontent.com/sligara7/mapwright/main/docs/gallery/citadel.png" alt="generated walled citadel"><br><sub><code>Settlement (citadel)</code></sub></td>
+</tr>
+<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>
+</tr>
+</table>
+
+Regenerate them with `python examples/gallery.py` (SVGs always; PNGs when
+`cairosvg` is installed).
+
+## Install
+
+```bash
+pip install git+https://github.com/sligara7/mapwright.git
+# or, for local development:
+pip install -e ".[dev]"
+```
+
+## Quickstart
+
+```python
+from mapwright import SeededRNG, RegionalTerrainGenerator, RegionalSVGRenderer, Marker
+
+# Same seed -> same world, every time.
+terrain = RegionalTerrainGenerator(SeededRNG(7)).generate(width=60, height=40)
+
+markers = [Marker(name="Eldmoor", x=30, y=18, kind="settlement_city")]
+svg = RegionalSVGRenderer().render(terrain, markers)
+open("world.svg", "w").write(svg)
+```
+
+Shape the world with `WorldMapConfig` — or describe it and let an LLM fill the config:
+
+```python
+from mapwright import WorldMapConfig, RegionalTerrainGenerator, SeededRNG
+
+desert = WorldMapConfig.preset("desert")          # ready-made worlds...
+custom = WorldMapConfig(continents=7, sea_level=0.55, temperature=-0.8)  # ...or tune
+world  = RegionalTerrainGenerator(SeededRNG(1)).generate(60, 40, config=desert)
+
+# Every field is a bounded scalar with a clear meaning, so it doubles as a schema
+# a host app (or an LLM) can populate. from_dict clamps junk to valid ranges:
+WorldMapConfig.from_dict({"temperature": 5, "continents": -3})  # -> safe, clamped
+```
+
+Presets: `continent`, `pangaea`, `archipelago`, `islands`, `highlands`, `desert`,
+`arctic`, `tropical`.
+
+Save and reload worlds (and dungeons) — JSON round-trips losslessly, so a reloaded
+world renders byte-identically:
+
+```python
+from mapwright import RegionalTerrainGenerator, SeededRNG, TerrainResult
+
+terrain = RegionalTerrainGenerator(SeededRNG(7)).generate(60, 40)
+open("world.json", "w").write(terrain.to_json())          # ...later...
+same = TerrainResult.from_json(open("world.json").read())  # bit-identical
+```
+
+`to_dict`/`from_dict` (and `to_json`/`from_json`) are available on `TerrainResult`,
+`Dungeon`, and `Marker`. Numpy rasters and full-precision floats are preserved.
+
+Procedural place-names in several culture styles:
+
+```python
+from mapwright import SeededRNG, NameGenerator
+
+namer = NameGenerator(SeededRNG(7))
+namer.settlement("nordic")    # -> 'Eirmundheim'
+namer.settlement("elvish")    # -> 'Faelynnwood'
+namer.region("dwarvish")      # -> 'The Korvald Reach'
+```
+
+Generate a dungeon and render it:
+
+```python
+from mapwright import SeededRNG, DungeonGenerator, DungeonSVGRenderer
+
+dungeon = DungeonGenerator(SeededRNG(3)).generate(48, 32)
+svg = DungeonSVGRenderer().render(dungeon, labels=True)  # number the rooms
+open("dungeon.svg", "w").write(svg)
+print(dungeon.ascii())  # or eyeball it as text
+```
+
+Generate a town — an organic footprint split into named wards, each subdivided
+into building lots, threaded with streets, and optionally walled (try the
+`port` and `citadel` presets):
+
+```python
+from mapwright import SeededRNG, SettlementGenerator, SettlementConfig, SettlementSVGRenderer
+
+town    = SettlementGenerator(SeededRNG(7)).generate(90, 90)
+port    = SettlementGenerator(SeededRNG(5)).generate(90, 90, SettlementConfig.preset("port"))
+citadel = SettlementGenerator(SeededRNG(3)).generate(90, 90, SettlementConfig.preset("citadel"))
+open("town.svg", "w").write(SettlementSVGRenderer().render(town))
+```
+
+Settlement presets: `hamlet`, `village`, `town`, `city`, `port`, `citadel`.
+
+## What's inside
+
+| Component | What it does |
+|-----------|--------------|
+| `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) → heightmap → 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. |
+| `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()`). |
+| `DungeonSVGRenderer` | Renders a `Dungeon` to SVG: walls, carved floor, room outlines, optional tile grid and per-room labels. |
+| `SettlementGenerator` | Self-contained town layout: an organic footprint divided into named Voronoi **wards** (market, docks, …), each subdivided into building **lots**, a **street** network (MST over ward adjacency + main roads from gates to the market), an optional defensive **wall** (towers + gate gaps, opened at the harbour when coastal), and optional coastline. |
+| `SettlementSVGRenderer` | Renders a `Settlement` to SVG: sea, footprint, kind-coloured wards, building lots, streets, wall with towers/gatehouses, labels. |
+
+Everything is neutral: `RegionalTerrainGenerator` returns a `TerrainResult` of `TerrainCell`s
+(each with a `Biome`), and you decide how a `Biome` maps to your world.
+
+## Determinism
+
+Every generator draws from a `SeededRNG`. The same seed (and parameters) reproduces an
+identical world — terrain, names, rivers, and SVG — across runs *and across processes*
+(the Markov chains are built in sorted order, so output never depends on `PYTHONHASHSEED`).
+
+## Performance
+
+Pure Python + numpy, single-threaded. Typical map/town sizes generate in well under a
+second; `examples/benchmark.py` prints a table for your machine. Rough figures (numbers
+are machine-dependent):
+
+| Generator | Size | Time |
+|-----------|------|------|
+| Terrain | 64×44 (≈470 cells) | ~150 ms |
+| Terrain | 120×90 (1500 cells, capped) | ~1.8 s |
+| Dungeon | 80×60 (≈50 rooms) | ~9 ms |
+| Settlement | pop 9000 (50 wards, ~1100 lots) | ~65 ms |
+| Roads / regions | on a 120×90 map | a few ms |
+
+Two things worth knowing:
+
+- **Terrain cell count is capped at 1500** (`cell_area` clamp in `generate`), which bounds
+  the hydrology/climate/graph work — but the initial Voronoi *rasterisation* is per-pixel,
+  so total time still grows roughly linearly with `width × height` on large maps. Raise
+  `cell_area` (fewer, coarser cells) to trade detail for speed, e.g.
+  `generate(w, h, cell_area=12)`.
+- **Dungeon corridor connection is a dense MST (~O(rooms³))**, so dungeons with hundreds of
+  rooms get slow — keep them modest or raise `DungeonConfig.min_leaf` for fewer, larger rooms.
+
+## API stability & contract
+
+The **public API is exactly the names exported in `mapwright.__all__`** — that's
+the contract. It's pinned by `tests/test_api_contract.py` (public surface, key
+signatures), so an accidental breaking change fails CI.
+
+For the world parameters specifically, `WorldMapConfig.json_schema()` returns a
+JSON Schema (draft 2020-12) — the machine-readable contract a host app or LLM can
+validate/generate against, then feed through `WorldMapConfig.from_dict()` (which
+clamps to valid ranges). Schema and runtime clamping are generated from the same
+field spec, so they can't drift.
+
+Versioning follows [SemVer](https://semver.org/). While at `0.x` the API may still
+change between minor versions; every change is recorded in `CHANGELOG.md`. Pin a
+tag or commit if you depend on it.
+
+## Development
+
+```bash
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## Credits & license
+
+MIT licensed (see `LICENSE`). Algorithms were implemented clean-room from the publicly
+described techniques of **Azgaar's Fantasy-Map-Generator** (MIT) and **Martin O'Leary /
+Ryan L. Guy's FantasyMapGenerator** (Zlib); see `NOTICE` for details. The bundled name
+lists are original.