mapwright 0.2.0__py3-none-any.whl

mapwright/names.py

@@ -0,0 +1,261 @@
+"""Procedural name generation via character-level Markov chains.
+
+Ported (clean-room) from the technique in Azgaar's Fantasy-Map-Generator (MIT):
+train a Markov chain on a small list of example names that share a linguistic
+"feel", then walk the chain to emit *new* names in the same style. This is
+cheap, fully offline (no LLM call), deterministic given a :class:`SeededRNG`,
+and language-agnostic — swap the training list to change the culture.
+
+Why a Markov chain rather than just sampling syllables: an order-k chain
+captures local letter-transition statistics (which clusters are plausible in a
+given language) without needing a phonotactic grammar. Order 3 over the seed
+lists below gives names that read as "Nordic" or "Elvish" without ever copying
+a training word verbatim (we reject exact training-set hits).
+
+The seed namebases here are intentionally compact, hand-authored word lists —
+*not* copied from any GPL/unlicensed generator — so the output and this module
+are clean for reuse. They're large enough for an order-3 chain; extend them
+freely (more examples → richer output).
+
+Usage::
+
+    rng = SeededRNG(seed)
+    namer = NameGenerator(rng)
+    namer.place("nordic")          # -> "Skjoldur"
+    namer.settlement("generic")    # -> "Eldmoor"  (base name + culture suffix)
+    namer.person("elvish")         # -> "Aelirien"
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import Optional
+
+from .rng import SeededRNG
+
+# Sentinel marking a word boundary in the Markov context/emission alphabet.
+_BOUNDARY = "\x00"
+
+# ---------------------------------------------------------------------------
+# Seed namebases — hand-authored, license-clean training lists, one per culture.
+# Order-3 chains need only a couple dozen examples to produce varied output.
+# ---------------------------------------------------------------------------
+
+NAMEBASES: dict[str, list[str]] = {
+    "generic": [
+        "Aldwin", "Brennan", "Caldor", "Dunmere", "Eldric", "Faron",
+        "Garrick", "Hadwin", "Ironholt", "Kelmoor", "Lannet", "Marden",
+        "Norwick", "Oakheart", "Pelmont", "Ravenwood", "Stonefel", "Thornby",
+        "Ulmar", "Vendry", "Westmere", "Wyndham", "Yardley", "Ashford",
+        "Briarcliff", "Greymoor", "Holloway", "Redwyn", "Tarnwick",
+    ],
+    "nordic": [
+        "Bjorn", "Sigurd", "Ragnar", "Eirik", "Halldor", "Gunnar", "Ivar",
+        "Knut", "Leif", "Olaf", "Sten", "Torvald", "Ulf", "Vidar", "Asgeir",
+        "Skuli", "Hakon", "Brandr", "Geirmund", "Snorri", "Thorgil",
+        "Frosta", "Helga", "Ingrid", "Sigrun", "Yngvar", "Skjold", "Dagny",
+    ],
+    "latin": [
+        "Marcus", "Valeria", "Cassius", "Aurelia", "Decimus", "Octavia",
+        "Tiberius", "Lucilla", "Quintus", "Flavia", "Septimus", "Antonia",
+        "Cornelius", "Drusilla", "Gaius", "Livia", "Maximus", "Vipsania",
+        "Aelius", "Camilla", "Tarquin", "Sabina", "Verus", "Junia",
+    ],
+    "elvish": [
+        "Aelar", "Caelynn", "Eluvian", "Faelar", "Galadriel", "Ithilien",
+        "Laeroth", "Mirelle", "Naerith", "Oromis", "Saelihn", "Thalion",
+        "Aerendyl", "Cithreth", "Elarian", "Faewyn", "Illianor", "Lithriel",
+        "Nimriel", "Sylvaris", "Vaelynn", "Aelirien", "Maeglin", "Tinuviel",
+    ],
+    "dwarvish": [
+        "Borin", "Durgan", "Thrain", "Balgrim", "Kragdor", "Norund",
+        "Gimrek", "Brundal", "Khazek", "Morgrum", "Thoradin", "Brokkur",
+        "Dvalin", "Grundvik", "Hrothgar", "Kazrik", "Orin", "Throndur",
+        "Belmund", "Garrundr", "Korvald", "Stonebeard", "Ironfist", "Deepdelve",
+    ],
+    "eastern": [
+        "Akihiro", "Renjiro", "Haruki", "Kenshin", "Daichi", "Sora",
+        "Takeo", "Yorimoto", "Ryusei", "Kaede", "Michiyo", "Tamaki",
+        "Hideaki", "Naoki", "Shinobu", "Yukihiro", "Asuka", "Reiko",
+        "Toshiro", "Mizuki", "Hayato", "Sayuri", "Kojiro", "Emiko",
+    ],
+    "desert": [
+        "Aziz", "Farran", "Jamil", "Karim", "Nasir", "Rashid", "Tariq",
+        "Yusuf", "Zahir", "Amina", "Layla", "Nadira", "Samira", "Zaida",
+        "Hakim", "Ibrahim", "Khalil", "Mansur", "Rafiq", "Saladin",
+        "Bahram", "Cyrus", "Darius", "Faridun",
+    ],
+    "dark": [
+        "Malketh", "Vornak", "Drathys", "Skorvath", "Nyxara", "Vexmoor",
+        "Gorthak", "Zultharn", "Morvath", "Skarn", "Velkith", "Drusk",
+        "Azgoth", "Korrath", "Nethyr", "Sablethorn", "Grimwald", "Vauldrek",
+        "Mortessa", "Shaelgar", "Thessaroth", "Ulvyn", "Xathorne", "Zerith",
+    ],
+}
+
+# Optional culture-flavoured settlement suffixes, appended to a base name to
+# form place names ("Eld" + "moor" -> "Eldmoor"). Mirrors how Azgaar composes
+# burg names from a root plus a geographic suffix.
+SETTLEMENT_SUFFIXES: dict[str, list[str]] = {
+    "generic": ["ton", "ford", "moor", "wick", "bury", "hill", "dale", "field",
+                "gate", "haven", "crest", "hollow", "march", "watch"],
+    "nordic": ["heim", "vik", "fjord", "gard", "stad", "ness", "fell", "by"],
+    "latin": ["um", "ium", "polis", "ara", "ena", "ica", "anum"],
+    "elvish": ["wood", "lond", "thil", "mar", "vale", "shire", "loth", "wen"],
+    "dwarvish": ["delve", "hold", "forge", "deep", "barrow", "mount", "karak"],
+    "eastern": ["mura", "gawa", "yama", "shiro", "do", "ji", "saki"],
+    "desert": ["abad", "stan", "kar", "oasis", "dune", "mir", "sah"],
+    "dark": ["spire", "gloom", "barrow", "throne", "mire", "fang", "shroud"],
+}
+
+# A reasonable default when a caller asks for an unknown culture.
+_FALLBACK_CULTURE = "generic"
+
+
+class MarkovNameGenerator:
+    """An order-``k`` character-level Markov chain trained on one word list."""
+
+    def __init__(self, words: list[str], order: int = 3):
+        self.order = order
+        # Keep a clean, lowercased copy of the training words so we can reject
+        # exact reproductions and know plausible length bounds.
+        self._training = {w.lower() for w in words if w and w.isalpha()}
+        self._min_len, self._max_len = self._length_bounds(self._training)
+        self._chain: dict[str, list[str]] = self._build_chain(self._training)
+
+    @staticmethod
+    def _length_bounds(words: set[str]) -> tuple[int, int]:
+        if not words:
+            return 4, 10
+        lengths = [len(w) for w in words]
+        return max(3, min(lengths)), max(lengths) + 2
+
+    def _build_chain(self, words: set[str]) -> dict[str, list[str]]:
+        """Map each k-char context to the list of characters that follow it.
+
+        We store the raw (multiset) list rather than a Counter so that picking a
+        next char with ``rng.choice`` is automatically frequency-weighted.
+        Words are padded with ``order`` boundary sentinels on each side.
+
+        ``words`` is iterated in **sorted** order, not set order: the follower
+        lists are positional, so set iteration (salted by ``PYTHONHASHSEED``)
+        would make ``rng.choice`` pick differently across processes and break
+        the library's seed-reproducibility guarantee.
+        """
+        chain: dict[str, list[str]] = defaultdict(list)
+        pad = _BOUNDARY * self.order
+        for word in sorted(words):
+            padded = pad + word + _BOUNDARY
+            for i in range(len(padded) - self.order):
+                context = padded[i : i + self.order]
+                nxt = padded[i + self.order]
+                chain[context].append(nxt)
+        return dict(chain)
+
+    def generate(
+        self,
+        rng: SeededRNG,
+        min_len: Optional[int] = None,
+        max_len: Optional[int] = None,
+        max_attempts: int = 40,
+    ) -> str:
+        """Walk the chain to produce a single capitalised name.
+
+        Retries up to ``max_attempts`` times to satisfy the length bounds and
+        avoid echoing a training word; falls back to the best candidate seen.
+        """
+        if not self._chain:
+            return ""
+        lo = min_len if min_len is not None else self._min_len
+        hi = max_len if max_len is not None else self._max_len
+        pad = _BOUNDARY * self.order
+
+        best = ""
+        for _ in range(max_attempts):
+            context = pad
+            out: list[str] = []
+            while True:
+                followers = self._chain.get(context)
+                if not followers:
+                    break
+                nxt = rng.choice(followers)
+                if nxt == _BOUNDARY:
+                    break
+                out.append(nxt)
+                if len(out) >= hi:  # hard stop on runaway chains
+                    break
+                context = (context + nxt)[-self.order :]
+            word = "".join(out)
+            if len(word) > len(best):
+                best = word
+            if lo <= len(word) <= hi and word not in self._training:
+                return word.capitalize()
+        return best.capitalize() if best else ""
+
+
+class NameGenerator:
+    """High-level, culture-aware naming facade over per-culture Markov chains.
+
+    Holds a :class:`SeededRNG` and lazily builds (and caches) one
+    :class:`MarkovNameGenerator` per culture. All draws go through a derived
+    ``"names"`` sub-stream so naming stays decoupled from terrain generation —
+    adding a name call never shifts the terrain RNG.
+    """
+
+    def __init__(self, rng: SeededRNG, order: int = 3):
+        self._rng = rng.derive("names")
+        self._order = order
+        self._chains: dict[str, MarkovNameGenerator] = {}
+
+    @staticmethod
+    def cultures() -> list[str]:
+        """The set of built-in culture keys available for naming."""
+        return sorted(NAMEBASES.keys())
+
+    def _chain_for(self, culture: str) -> MarkovNameGenerator:
+        key = culture if culture in NAMEBASES else _FALLBACK_CULTURE
+        if key not in self._chains:
+            self._chains[key] = MarkovNameGenerator(NAMEBASES[key], self._order)
+        return self._chains[key]
+
+    # -- public naming API ----------------------------------------------
+
+    def place(self, culture: str = "generic") -> str:
+        """A bare place/region name in the given culture's style."""
+        return self._chain_for(culture).generate(self._rng)
+
+    def person(self, culture: str = "generic") -> str:
+        """A personal name in the given culture's style."""
+        return self._chain_for(culture).generate(self._rng)
+
+    def settlement(self, culture: str = "generic", suffix_chance: float = 0.65) -> str:
+        """A settlement name: a root name, often plus a geographic suffix.
+
+        e.g. ``"Eld" + "moor" -> "Eldmoor"``. With probability
+        ``1 - suffix_chance`` the bare root is returned instead, for variety.
+        """
+        root = self.place(culture)
+        if not root:
+            return root
+        suffixes = SETTLEMENT_SUFFIXES.get(culture) or SETTLEMENT_SUFFIXES[_FALLBACK_CULTURE]
+        if suffixes and self._rng.chance(suffix_chance):
+            # Drop a trailing vowel before a vowel-initial suffix to avoid
+            # awkward clusters ("Elda" + "moor" -> "Eldmoor").
+            suffix = self._rng.choice(suffixes)
+            if root[-1].lower() in "aeiou" and suffix[0].lower() not in "aeiou":
+                root = root[:-1]
+            return (root + suffix).capitalize()
+        return root
+
+    def region(self, culture: str = "generic") -> str:
+        """A region/territory name, e.g. "The Tarnwick Reach"."""
+        forms = [
+            "{name}",
+            "The {name} Reach",
+            "{name} March",
+            "{name}land",
+            "Vale of {name}",
+            "The {name} Wastes",
+        ]
+        name = self.place(culture)
+        return self._rng.choice(forms).format(name=name) if name else name

mapwright/rng.py

@@ -0,0 +1,163 @@
+"""Unified seeded random-number generator for procedural map generation.
+
+Ported from the discipline used by Azgaar's Fantasy-Map-Generator (MIT) and
+Watabou's generators: a *single* seed drives *every* stage of generation, so
+the same seed always reproduces the same world. The key idea that the previous
+``random.seed(seed)`` / ``np.random.seed(seed)`` pattern lacked:
+
+  * It mutated Python's **global** ``random`` module state, so any other code
+    that drew from ``random`` (or any reordering of draws) silently changed the
+    output. Here the stream is **instance-local** — nothing leaks in or out.
+  * It kept two *uncoordinated* streams (stdlib ``random`` and ``numpy``). Here
+    both are derived from one seed, so a single integer reproduces terrain
+    *and* noise.
+  * Adding a draw anywhere shifted everything downstream. :meth:`derive` gives
+    each generation stage (terrain, naming, settlements, …) its own independent
+    sub-stream keyed by a label, so stages can evolve without desyncing.
+
+Example::
+
+    rng = SeededRNG(request.seed)          # rng.seed is the resolved int seed
+    terrain_rng = rng.derive("terrain")    # independent, reproducible sub-stream
+    name_rng = rng.derive("names")         # adding/removing draws here cannot
+                                           # shift terrain_rng's output
+"""
+
+from __future__ import annotations
+
+import hashlib
+import random
+from typing import Optional, Sequence, TypeVar
+
+import numpy as np
+
+T = TypeVar("T")
+
+# Seeds are kept inside the signed 31-bit range so they round-trip cleanly
+# through JSON, the ``generation_seed`` column, and numpy's seed API.
+_SEED_MODULUS = 2**31
+
+
+def _coerce_seed(seed: Optional[int]) -> int:
+    """Resolve an optional seed to a concrete, reproducible 31-bit integer.
+
+    When ``seed`` is ``None`` we draw a fresh one from the OS entropy pool and
+    *return it* so callers can persist it and replay the exact same map later.
+    """
+    if seed is None:
+        # SystemRandom is process-state-free, so picking the auto-seed never
+        # perturbs any SeededRNG stream.
+        return random.SystemRandom().randrange(_SEED_MODULUS)
+    return int(seed) % _SEED_MODULUS
+
+
+def _derive_seed(parent_seed: int, label: str) -> int:
+    """Deterministically mix ``parent_seed`` with ``label`` into a child seed.
+
+    Uses BLAKE2b rather than the builtin ``hash()`` because ``hash()`` of a
+    string is salted per-process (``PYTHONHASHSEED``) and would make derived
+    streams non-reproducible across runs.
+    """
+    digest = hashlib.blake2b(
+        f"{parent_seed}:{label}".encode("utf-8"), digest_size=8
+    ).digest()
+    return int.from_bytes(digest, "big") % _SEED_MODULUS
+
+
+class SeededRNG:
+    """A reproducible, instance-local random stream with derivable sub-streams.
+
+    Wraps a private :class:`random.Random` and a private
+    :class:`numpy.random.Generator`, both seeded from the same integer. None of
+    the methods touch global RNG state.
+    """
+
+    __slots__ = ("seed", "_rng", "_np")
+
+    def __init__(self, seed: Optional[int] = None):
+        self.seed: int = _coerce_seed(seed)
+        self._rng = random.Random(self.seed)
+        self._np: Optional[np.random.Generator] = None  # lazily constructed
+
+    # -- sub-streams -----------------------------------------------------
+
+    def derive(self, label: str) -> "SeededRNG":
+        """Return an independent child stream keyed by ``label``.
+
+        Same parent seed + same label always yields the same child, but the
+        child's draws are statistically independent of the parent's and of
+        sibling labels. This is how generation stages stay decoupled.
+        """
+        return SeededRNG(_derive_seed(self.seed, label))
+
+    @property
+    def numpy(self) -> np.random.Generator:
+        """A numpy ``Generator`` seeded from the same seed (for vectorised noise)."""
+        if self._np is None:
+            self._np = np.random.default_rng(self.seed)
+        return self._np
+
+    # -- scalar draws ----------------------------------------------------
+
+    def random(self) -> float:
+        """Float in ``[0.0, 1.0)``."""
+        return self._rng.random()
+
+    def uniform(self, low: float, high: float) -> float:
+        """Float in ``[low, high)``."""
+        return self._rng.uniform(low, high)
+
+    def randint(self, low: int, high: int) -> int:
+        """Integer in ``[low, high]`` (inclusive on both ends, like stdlib)."""
+        return self._rng.randint(low, high)
+
+    def chance(self, probability: float) -> bool:
+        """``True`` with the given probability (Watabou's ``Random.bool``)."""
+        return self._rng.random() < probability
+
+    def gauss(self, mu: float = 0.0, sigma: float = 1.0) -> float:
+        """A normally-distributed float."""
+        return self._rng.gauss(mu, sigma)
+
+    def fuzzy(self, value: float, spread: float) -> float:
+        """Jitter ``value`` by ``±spread`` uniformly.
+
+        Watabou uses this constantly to break up grid regularity (e.g. nudging
+        polygon vertices). ``rng.fuzzy(10, 2)`` returns a float in ``[8, 12)``.
+        """
+        return value + self._rng.uniform(-spread, spread)
+
+    # -- sequence draws --------------------------------------------------
+
+    def choice(self, seq: Sequence[T]) -> T:
+        """Uniformly pick one element."""
+        return self._rng.choice(seq)
+
+    def choices(
+        self,
+        population: Sequence[T],
+        weights: Optional[Sequence[float]] = None,
+        k: int = 1,
+    ) -> list[T]:
+        """Weighted sampling with replacement (stdlib semantics)."""
+        return self._rng.choices(population, weights=weights, k=k)
+
+    def weighted(self, options: dict[T, float]) -> T:
+        """Pick one key from a ``{value: weight}`` mapping, proportional to weight.
+
+        The bread-and-butter of Azgaar's culture/state/biome selection.
+        """
+        keys = list(options.keys())
+        weights = list(options.values())
+        return self._rng.choices(keys, weights=weights, k=1)[0]
+
+    def shuffle(self, seq: list) -> None:
+        """In-place shuffle."""
+        self._rng.shuffle(seq)
+
+    def sample(self, population: Sequence[T], k: int) -> list[T]:
+        """Sample ``k`` distinct elements (without replacement)."""
+        return self._rng.sample(list(population), k)
+
+    def __repr__(self) -> str:  # pragma: no cover - debugging aid
+        return f"SeededRNG(seed={self.seed})"

mapwright/svg_renderer.py

@@ -0,0 +1,249 @@
+"""Vector (SVG) renderer for regional terrain, with shaded relief.
+
+Renders a :class:`~src.mapwright.terrain.TerrainResult` as a scalable SVG map:
+organic Voronoi biome polygons, slope-based **shaded relief** (the hillshade
+technique from rlguy/Mewo2's FantasyMapGenerator — per-cell surface normals lit
+by a fixed light direction), a coastline stroke, rivers whose width tracks
+discharge, and labelled settlement markers.
+
+Why SVG for this tier (vs the PNG tile compositor used for tactical maps):
+world/regional maps want to zoom, restyle, and carry crisp labels — all of which
+vector handles for free, and it sidesteps the "fog/grid baked into the PNG"
+tech-debt. Everything here is pure string-building (no new dependencies).
+"""
+
+from __future__ import annotations
+
+import math
+import xml.sax.saxutils as su
+from dataclasses import dataclass
+from typing import Optional, Sequence
+
+from .terrain import Biome, TerrainCell, TerrainResult, compute_cell_polygons
+
+
+@dataclass
+class Marker:
+    """A neutral point-of-interest to label on the map (e.g. a settlement).
+
+    Domain-neutral on purpose: a host app maps its own feature objects onto this
+    rather than the renderer depending on the host's models. ``kind`` selects the
+    marker size (see ``_SETTLEMENT_RADIUS``) and a substring of it (e.g. "city")
+    bumps the label font.
+    """
+
+    name: str
+    x: float
+    y: float
+    kind: str = ""
+
+# Base biome fill colours (before relief shading), tuned for a parchment-ish
+# fantasy palette rather than the dungeon tile colours.
+_BIOME_RGB: dict[Biome, tuple[int, int, int]] = {
+    Biome.OCEAN: (31, 78, 107),
+    Biome.COAST: (61, 126, 166),
+    Biome.BEACH: (217, 199, 155),
+    Biome.DESERT: (214, 196, 130),
+    Biome.PLAINS: (169, 196, 127),
+    Biome.FOREST: (79, 130, 74),
+    Biome.SWAMP: (107, 123, 74),
+    Biome.HILLS: (160, 154, 100),
+    Biome.MOUNTAIN: (140, 132, 122),
+    Biome.TUNDRA: (188, 196, 180),
+    Biome.SNOW: (240, 244, 248),
+    Biome.RIVER: (127, 168, 106),  # riverbank green; the river line draws on top
+}
+
+_OCEAN_BG = (24, 62, 86)
+_COASTLINE = (40, 54, 64)
+_RIVER_COLOR = (74, 130, 175)
+
+_SETTLEMENT_RADIUS = {
+    "settlement_city": 5.5,
+    "settlement_town": 4.0,
+    "settlement_village": 3.0,
+    "settlement_castle": 4.5,
+}
+
+
+def _shade(base: tuple[int, int, int], brightness: float) -> str:
+    """Apply a relief brightness multiplier to a colour → ``#rrggbb``."""
+    return "#%02x%02x%02x" % tuple(
+        max(0, min(255, int(round(ch * brightness)))) for ch in base
+    )
+
+
+def _rgb(c: tuple[int, int, int]) -> str:
+    return "#%02x%02x%02x" % c
+
+
+class RegionalSVGRenderer:
+    """Renders a :class:`TerrainResult` to an SVG document string."""
+
+    def __init__(self, scale: float = 16.0, relief_strength: float = 60.0):
+        # scale = pixels per tile-unit; relief_strength exaggerates slope so the
+        # hillshade reads on gentle terrain (height diffs between cells are tiny,
+        # so this needs to be large).
+        self.scale = scale
+        self.relief_strength = relief_strength
+        # Light from the upper-left (classic cartographic convention).
+        lx, ly, lz = -1.0, -1.0, 1.4
+        norm = math.sqrt(lx * lx + ly * ly + lz * lz)
+        self._light = (lx / norm, ly / norm, lz / norm)
+
+    def render(
+        self,
+        terrain: TerrainResult,
+        markers: Optional[Sequence[Marker]] = None,
+        *,
+        show_relief: bool = True,
+        show_labels: bool = True,
+    ) -> str:
+        s = self.scale
+        w_px, h_px = terrain.width * s, terrain.height * s
+        polys = compute_cell_polygons(terrain.cells, terrain.width, terrain.height)
+        brightness = self._relief(terrain.cells) if show_relief else {}
+
+        parts: list[str] = [
+            f'<svg xmlns="http://www.w3.org/2000/svg" width="{w_px:.0f}" '
+            f'height="{h_px:.0f}" viewBox="0 0 {w_px:.0f} {h_px:.0f}">',
+            f'<rect width="{w_px:.0f}" height="{h_px:.0f}" fill="{_rgb(_OCEAN_BG)}"/>',
+        ]
+
+        # 1. Biome polygons with relief shading.
+        parts.append('<g stroke-linejoin="round">')
+        for cell in terrain.cells:
+            poly = polys.get(cell.id)
+            if not poly or len(poly) < 3:
+                continue
+            fill = _shade(_BIOME_RGB[cell.biome], brightness.get(cell.id, 1.0))
+            pts = " ".join(f"{x * s:.1f},{y * s:.1f}" for x, y in poly)
+            # A hairline stroke in the fill colour hides seams between cells.
+            parts.append(f'<polygon points="{pts}" fill="{fill}" stroke="{fill}" '
+                         f'stroke-width="0.5"/>')
+        parts.append("</g>")
+
+        # 2. Coastline — edges of land cells that border the sea.
+        parts.append(self._coastline_svg(terrain, polys))
+
+        # 3. Rivers — downhill polylines, width by discharge.
+        parts.append(self._rivers_svg(terrain))
+
+        # 4. Settlements.
+        if markers:
+            parts.append(self._settlements_svg(markers, show_labels))
+
+        parts.append("</svg>")
+        return "".join(parts)
+
+    # -- relief ----------------------------------------------------------
+
+    def _relief(self, cells: list[TerrainCell]) -> dict[int, float]:
+        """Per-cell brightness from a slope normal lit by the fixed light."""
+        out: dict[int, float] = {}
+        lx, ly, lz = self._light
+        for c in cells:
+            if c.is_water:
+                out[c.id] = 1.0
+                continue
+            gx = gy = 0.0
+            count = 0
+            for nid in c.neighbors:
+                n = cells[nid]
+                dx, dy = n.cx - c.cx, n.cy - c.cy
+                d2 = dx * dx + dy * dy
+                if d2 <= 0:
+                    continue
+                dh = (n.height - c.height) * self.relief_strength
+                gx += dh * dx / d2
+                gy += dh * dy / d2
+                count += 1
+            if count:
+                gx /= count
+                gy /= count
+            # Surface normal of the local plane z = -gx*x - gy*y, lit by the
+            # light direction. Steeper slopes facing the light brighten; those
+            # facing away darken — classic hillshade.
+            nx, ny, nz = -gx, -gy, 1.0
+            nlen = math.sqrt(nx * nx + ny * ny + nz * nz) or 1.0
+            shade = (nx * lx + ny * ly + nz * lz) / nlen  # ~0..1, ~0.7 when flat
+            # Re-centre around the flat-ground value (lz) so flat terrain stays
+            # neutral and aspect drives the contrast.
+            out[c.id] = max(0.66, min(1.28, 1.0 + 1.1 * (shade - lz)))
+        return out
+
+    # -- coastline -------------------------------------------------------
+
+    def _coastline_svg(self, terrain: TerrainResult, polys) -> str:
+        s = self.scale
+        cells = terrain.cells
+        segs: list[str] = []
+        eps = 1e-6
+        w, h = terrain.width, terrain.height
+        for c in cells:
+            if c.is_water:
+                continue
+            poly = polys.get(c.id)
+            if not poly or len(poly) < 3:
+                continue
+            n = len(poly)
+            for i in range(n):
+                a, b = poly[i], poly[(i + 1) % n]
+                mx, my = (a[0] + b[0]) / 2, (a[1] + b[1]) / 2
+                # Skip edges lying on the map border (not a real coastline).
+                if mx < eps or my < eps or mx > w - eps or my > h - eps:
+                    continue
+                # The neighbour across this edge is the nearest cell-site to the
+                # edge midpoint (the edge lies on their shared bisector).
+                nb = min(c.neighbors,
+                         key=lambda k: (cells[k].cx - mx) ** 2 + (cells[k].cy - my) ** 2,
+                         default=None)
+                if nb is not None and cells[nb].is_water:
+                    segs.append(f'M{a[0] * s:.1f},{a[1] * s:.1f} '
+                                f'L{b[0] * s:.1f},{b[1] * s:.1f}')
+        if not segs:
+            return ""
+        return (f'<path d="{" ".join(segs)}" fill="none" stroke="{_rgb(_COASTLINE)}" '
+                f'stroke-width="2.0" stroke-linecap="round"/>')
+
+    # -- rivers ----------------------------------------------------------
+
+    def _rivers_svg(self, terrain: TerrainResult) -> str:
+        s = self.scale
+        cells = terrain.cells
+        paths: list[str] = []
+        for river in terrain.rivers:
+            if len(river.cells) < 2:
+                continue
+            pts = [(cells[i].cx * s, cells[i].cy * s) for i in river.cells]
+            d = "M" + " L".join(f"{x:.1f},{y:.1f}" for x, y in pts)
+            width = max(0.8, min(4.0, 0.4 * river.width))
+            paths.append(f'<path d="{d}" fill="none" stroke="{_rgb(_RIVER_COLOR)}" '
+                         f'stroke-width="{width:.1f}" stroke-linecap="round" '
+                         f'stroke-linejoin="round"/>')
+        if not paths:
+            return ""
+        return '<g opacity="0.9">' + "".join(paths) + "</g>"
+
+    # -- settlements -----------------------------------------------------
+
+    def _settlements_svg(self, markers: Sequence[Marker], labels: bool) -> str:
+        s = self.scale
+        out: list[str] = ['<g font-family="Georgia, serif">']
+        for m in markers:
+            r = _SETTLEMENT_RADIUS.get(m.kind, 3.0)
+            cx, cy = m.x * s, m.y * s
+            out.append(f'<circle cx="{cx:.1f}" cy="{cy:.1f}" r="{r:.1f}" '
+                       f'fill="#f4ead8" stroke="#2b2b2b" stroke-width="1.2"/>')
+            if labels and m.name:
+                name = su.escape(m.name)
+                tx, ty = cx + r + 2, cy + 3
+                fs = 11 if "city" in m.kind else 9
+                # White halo behind the label for legibility over any biome.
+                out.append(
+                    f'<text x="{tx:.1f}" y="{ty:.1f}" font-size="{fs}" '
+                    f'stroke="#f7f3ea" stroke-width="3" paint-order="stroke" '
+                    f'fill="#23211c">{name}</text>'
+                )
+        out.append("</g>")
+        return "".join(out)