settlemaker 3.0.0 → 3.0.1

package/docs/scene-schema.md

@@ -0,0 +1,160 @@
+# City scene and rendering contract
+
+`Scene` version **2** is the semantic rendering representation of the **city**
+planner. Villages use `VillageModel` and `renderVillage`; they do not pass through
+`buildScene`. Use [GeoJSON](geojson.md) for exported feature data from both planners,
+and [skins](skins.md) for portable artwork that works in both.
+
+```text
+City:     Model → buildScene → Scene v2 → assembleSvg → SVG
+Village:  VillageModel → renderVillage → SVG
+```
+
+The scene stores geometry, semantic kinds, saved glyph selections and material
+variant indices. It does not contain SVG fragment bodies or a complete theme.
+`assembleSvg` supplies the artwork and appearance. The complete declarations live
+in [src/scene/scene.ts](../src/scene/scene.ts).
+
+## Render an existing city model
+
+This complete example uses the high-level city generator to retain its coastal
+shift and degradation behaviour, then renders the saved model in another palette:
+
+```js
+import { generateFromBurg, buildScene, assembleSvg, PALETTES } from 'settlemaker';
+
+const burg = {
+  name: 'Thornwall', population: 5000, biome: 'temperate',
+  port: false, citadel: true, walls: true, plaza: true,
+  temple: true, shanty: false, capital: false,
+  roadBearings: [20, 145, 270],
+};
+const result = generateFromBurg(burg, { seed: 42 });
+const scene = buildScene(result.model, { shift: result.originShift, padding: 20 });
+const svg = assembleSvg(scene, { palette: PALETTES.night });
+console.log(scene.version, svg.length);
+```
+
+`generateSvg(model, options)` is a convenience wrapper around those two stages.
+When rerendering a model from `generateFromBurg`, pass its `originShift` if you
+want the same output coordinate frame. When generating SVG and GeoJSON separately,
+use the same shift and padding for both.
+
+For direct control over city generation:
+
+```js
+import { mapToGenerationParams, Model, generateSvg, generateGeoJson } from 'settlemaker';
+
+// burg is the complete object from the preceding example.
+const params = mapToGenerationParams(burg, 42);
+const model = new Model(params).generate();
+const svg = generateSvg(model);
+const geojson = generateGeoJson(model);
+```
+
+`GenerationParams` is a TypeScript interface. It cannot be called with `new`.
+This direct path does not reproduce the two-pass coastal output translation
+performed by `generateFromBurg`; use that high-level function when you want it.
+
+## Scene fields
+
+| Field | Meaning |
+| --- | --- |
+| `version` | Literal 2. |
+| `seed`, `population`, optional `name`, `biome` | Generating context. |
+| `bounds` | Local output bounds. |
+| `metersPerUnit` | Optional city scale estimate for rendering, not a survey. |
+| `buildingCapacity` | Optional ordinary-building budget accounting. |
+| `layers` | The geometry and instance arrays described below. |
+
+| Layer | Contents |
+| --- | --- |
+| `water` | `{rings, synthetic}`; even-odd output rings retain islands. |
+| `fields` | Polygon `ring`, `angleDeg`, optional native `glyph` and `hatch`. Pattern pitch is independent of parcel size. |
+| `furrows` | Deprecated array; current scenes leave it empty and use field direction instead. |
+| `greens` | Polygon rings with optional planned paths and path width. |
+| `vegetation` | Position, glyph/legacy `kind`, scale and rotation. |
+| `symbols` | Glyph `id`, position, scale, optional `scaleY`, `buildingId`, `materialVariant`, rotation, and `zBand`. |
+| `roads` | Paths with `kind: 'artery' | 'road' | 'alley'` and optional width. |
+| `buildings` | Polygon, semantic ward `kind`, `landmark`, optional `id` and `glyphBacked`. |
+| `piers` | Polygon rings. |
+| `walls` | Polylines, towers, gates and `large`; optional curtain/rubble/palisade material. Gates retain route IDs. |
+| `bridges` | Optional on v2 scenes; bank-to-bank path, width and ID. |
+
+An instance's scale gives its art-box size in scene units; artwork coordinates
+come from the selected glyph's view box and anchor. Preserve non-square boxes and
+`scaleY`. Native field tiles may have a 32-unit box, structure slots commonly 64,
+and downloadable authoring assets can use other dimensions. There is no universal
+2×2 authoring rule for current glyphs.
+
+## Appearance and artwork
+
+`assembleSvg(scene, options)` accepts `palette`, partial `theme`, `skin`,
+`skinBiome`, `assetSet`, `symbols` and `clipId`. `generateSvg` also accepts scene
+`padding` and `shift`.
+
+The default asset set is **`SETTLEMENT_SET`**, containing the current native biome
+artwork. `REFINED_SET` and `SCHEMATIC_SET` remain explicit lower-level alternatives.
+`assetSetFor` returns the current default. `paletteForBiome` currently supplies
+its palette fallback; the artwork and material selection provide much of the
+visible biome variation. Do not assume each biome corresponds to a different
+named city palette.
+
+For an artist-facing integration, prefer `createSkin` and the [skin contract](skins.md).
+It validates portable JSON, allowed SVG fragments and exact slot names without
+requiring changes to the asset lookup code. An explicit city `assetSet` overrides
+a skin's artwork. Skin colours/biomes and renderer overrides follow the precedence
+in the skin guide.
+
+`AssetSet` remains a lower-level API for trusted code. It has a name, legacy
+semantic `symbols`, optional `patterns`, `glyphs`, placement `manifest` and
+`refined` styling flag. Its legacy symbols use a unit box, while `glyphs` carry
+explicit view boxes and anchors. Do not apply the legacy unit-box convention to
+portable skin glyphs.
+
+## SVG styling and geometry
+
+Current SVGs combine group CSS, material custom properties and presentation
+attributes inside native or procedural artwork. They are not wholly styled by
+one CSS block, and changing a group fill does not recolour every roof or tree.
+Use documented theme/token controls instead of rewriting arbitrary SVG attributes.
+
+City groups include fields, greens, water, roads, buildings, landmarks, shadows,
+placed symbols/marks, vegetation and walls. Some groups are omitted when empty;
+procedural artwork can add nested groups, masks and patterns. These group names
+are not the village renderer's DOM contract. For city building identity, emitted
+`data-building-id` attributes connect applicable polygons/symbols to GeoJSON IDs.
+Use GeoJSON for semantic feature queries rather than inferring a feature solely
+from its colour or DOM position.
+
+`symbols: false` hides placed city symbols and overlay marks. It leaves vegetation
+and actual building polygons available. It is not a universal switch to remove
+all embedded artwork.
+
+## Embedding SVG
+
+The `data-bg="paper"` rectangle is used by the tile cropper. Preserve it when
+post-processing. Village roots also declare `data-px-per-metre`; use it to retain
+their physical scale through tiling.
+
+Generated SVG IDs are scoped to a document. When displaying several maps, prefer
+separate `<img>` documents (including SVG Blob URLs), `<object>` elements or
+iframes. A unique city `clipId` only changes selected clipping/pattern IDs; it
+does not namespace every glyph, CSS selector or village ID. It is insufficient
+by itself to make multiple inline maps independent. A custom inline compositor
+must consistently namespace IDs, references and applicable styles.
+
+SVG output is self-contained for artwork. A browser host is responsible for
+responsive sizing, pan/zoom, downloads and visible errors. Those behaviours are
+not implemented by importing the generator alone.
+
+## Evolution and saved scenes
+
+Optional fields such as `layers.bridges`, field `glyph`, wall `material` and symbol
+`materialVariant` extend Scene v2. Consumers should handle their absence in older
+saved scenes. Breaking changes to existing field meaning or structure require a
+scene version change.
+
+A saved scene is not a complete reproduction package: retain the generator
+version, skin definition and renderer options too. A `SettlementSkin` runtime
+handle must be recreated from JSON in the module instance doing the rendering.

package/docs/schema-v3.md

@@ -0,0 +1,38 @@
+# Historical GeoJSON schema v3
+
+This page records the city-output transition introduced in release 0.4.0.
+**Current output uses schema 4.** Use the [current GeoJSON reference](geojson.md)
+for new integrations, including village coordinates, road widths and diagnostics.
+Do not gate current output on `schema_version === 3`.
+
+## What changed in v3
+
+City output gained POI Point features, building and street IDs, ID-prefix
+metadata, and the hamlet/town POI density marker. Existing city properties such
+as `wardType` and `streetType` retained camelCase; additions such as `building_id`
+and `poi_id` used snake_case. That mixture remains deliberate in current output.
+
+Later city releases added symbol-backed floating wells, markets and mills, then
+capacity accounting and other optional schema-4 fields. Later village releases
+introduced a different planner and its own feature properties. The historic
+city-only POI and flat-street descriptions must not be applied to every village.
+
+## Stable-ID contract
+
+IDs are deterministic for identical inputs and a fixed generator version.
+They are opaque and are not guaranteed stable across upgrades. See
+[current identity and persistence](geojson.md#ids-and-persistence).
+
+## Village road cross-sections
+
+The documentation formerly appended here now lives in the
+[current village road section](geojson.md#village-road-cross-sections), including
+corridor widths, painted widths, setbacks, bridge decks and route provenance.
+
+## Migration for consumers
+
+For 3.0.x, check schema **4**, inspect `properties.layer` and geometry types,
+and accept optional fields your application does not need. Branch for the
+[village/city differences](geojson.md), especially POIs, greens, gate features,
+coordinates and IDs. The package version, scene version and URL envelope version
+are separate discriminators; see the [documentation index](README.md#contract-versions).

package/docs/skins.md

@@ -1,5 +1,9 @@
 # Authoring settlement skins
 
+This is the portable **skin format 1** contract for SettleMaker 3.0.x. Start here
+to create a personalised setting; the older `AssetSet` API is for trusted city
+rendering code and is not required to distribute a skin.
+
 A skin is a versioned JSON document containing SVG artwork, material colours,
 and optional named biomes. The same skin works with villages and cities in Node
 and the browser. Load it once with `createSkin`, then pass it per request:
@@ -7,6 +11,13 @@ and the browser. Load it once with `createSkin`, then pass it per request:
 ```ts
 import { createSkin, generateSettlement } from 'settlemaker';
 
+const burg = {
+  name: 'Moonfall', population: 300,
+  port: false, citadel: false, walls: false, plaza: true,
+  temple: true, shanty: false, capital: false,
+  roadBearings: [18, 142, 267],
+};
+
 // Browser example. Applications choose where to store/host their skin files.
 const response = await fetch('/skins/moon-glass.skin.json');
 if (!response.ok) throw new Error('Could not load skin');
@@ -22,6 +33,9 @@ In Node, pass `JSON.parse(await readFile(path, 'utf8'))` to `createSkin`.
 There is no global registry, automatic network access, or executable plugin code.
 Keep the original JSON to save or distribute the skin; the returned skin is an
 immutable runtime handle. Invalid definitions throw an error naming the property.
+Create the handle in the same module instance that generates or renders the map.
+For a worker, another independently loaded bundle, or saved data, transfer the
+definition JSON and call `createSkin` there. There is no runtime-handle wire format.
 
 Start with [Moon Glass](examples/moon-glass.skin.json), a small working example
 that replaces snowy dwellings with crystal homes and colours their surroundings.
@@ -157,3 +171,41 @@ Skins are currently a library API. A hosting application can add a picker or loa
 its own curated files; the URL codec does not serialize skin artwork or fetch skin
 URLs. Distribute your original artwork with your chosen licence information. For
 artwork derived from the bundled symbols, consult [symbols/LICENSE](../symbols/LICENSE).
+
+## Build and review your own skin
+
+1. Choose a base biome whose terrain behaviour fits the setting. Begin with a
+   partial skin so you can evaluate the style before drawing a complete set.
+2. Inspect `SKIN_SLOTS` and the current source SVG for each replacement. Retain the
+   slot's view box, orientation and painted extents. Export the inner shapes and,
+   for structures, a matching silhouette.
+3. Put replacements under their exact IDs. Biome variants are separate entries:
+   a generic house replacement does not automatically replace every snowy or
+   desert house. Cover each category that appears in your target biomes.
+4. Add tokens and the separate `village`/`city` theme overrides. Render both engines
+   with the same loaded skin and try more than one seed and population.
+5. Validate using `createSkin`, then inspect SVG and raster output for seams,
+   clipping, shadows and overlap. Schema validation alone cannot establish visual
+   compatibility with a placement footprint.
+6. Distribute the JSON with a README, preview images and your artwork's license and
+   credits in adjacent files. Do not add unsupported executable hooks or invent
+   top-level schema fields for license text. Record the generator version used for
+   testing and the biomes/categories you intentionally cover.
+
+The [gallery](gallery.md) demonstrates real library output. Its
+[generator script](../scripts/generate-examples.mjs) shows complete inputs for both
+planners. For original alternative artwork and regeneration commands, inspect
+[Copperline](../symbols/copperline/README.md). Its GPL-3.0-only terms are separate
+from the default collections' rendered-output exception.
+
+## Common mistakes
+
+| Symptom | Check |
+| --- | --- |
+| Some default buildings remain | Replacement IDs must match exact runtime slots, including biome variants. Partial skins deliberately inherit omissions. |
+| A named biome renders as temperate | Pass the loaded skin on that generation request and use a defined key/alias. Unknown names retain the normal fallback. |
+| A replacement overlaps its neighbour | Check painted extents, not just whether the drawing fits inside the SVG view box. Placement footprints cannot be changed by skin format 1. |
+| The old shadow remains or the replacement has none | Supply a matching `sil`; an omitted silhouette means no shadow for that replaced glyph. |
+| A worker rejects a skin handle | Send the original JSON and recreate the handle inside that worker's module instance. |
+| A road or bridge ignores an SVG replacement | Some features are procedural geometry, outside the slot catalogue. Use the exposed renderer controls where available. |
+| An iframe ignores a skin URL | The URL codec has no skin parameter. Load skins through your application's library integration. |

package/docs/test-urls.md

@@ -0,0 +1,39 @@
+# Reproducible example URLs
+
+The [current gallery](gallery.md) is the public example set for 3.0.x. Its images
+are generated with `generateSettlement`, so population ≤1,000 uses the village
+planner instead of forcing small inputs through the city generator.
+
+Each entry includes its population, seed, full SVG and (where supported) a hosted
+preview URL. [fixtures.json](examples/gallery/fixtures.json) records the complete
+burg inputs, generator version and skin choice. Use those inputs with your pinned
+npm package for exact local reproduction; a hosted URL uses the website's deployed
+build and can change appearance when that site updates.
+
+## Generate links
+
+Use the public `encodeBurgParam` helper described in the [URL contract](url-api.md).
+Supply the complete input and an explicit seed. Route IDs and measured water
+require the compressed input tier; the flat tier cannot preserve them.
+
+Copperline examples are direct library calls. The URL protocol does not transport
+skins, so the gallery links those examples to their generated SVG and skin JSON
+instead of presenting a URL that would silently show default artwork.
+
+## Regenerate and review
+
+```sh
+npm ci
+npm run docs:images
+npm run docs:check
+```
+
+The image command regenerates PNG and SVG files together and rewrites the gallery
+and fixture manifest. Review the actual maps before committing them. PNGs use the
+SVG's supplied CSS-variable fallbacks for rasterizer compatibility.
+
+The generator script is [scripts/generate-examples.mjs](../scripts/generate-examples.mjs).
+Older development review fixtures in `scripts/generate-test-urls.ts` and previous
+image files are historical aids, not the current documentation contract or a list
+of unresolved defects. Current behaviour and limits are documented in the
+[API](api.md), [GeoJSON reference](geojson.md) and [water contract](water-context-v1.md).

package/docs/url-api.md

@@ -0,0 +1,252 @@
+# URL adapter contract
+
+This guide describes the **3.0.x library's URL codec** and the hosting contract
+for a renderer at `https://settlemaker.com/fmg`. The URL envelope version remains
+**1**. The npm library and hosted website have separate release cycles; a package
+publication alone does not establish which generator a website is running.
+
+Use the [library API](api.md) when your application generates maps itself. Use a
+URL adapter when a host such as Azgaar's Fantasy Map Generator embeds a separately
+deployed renderer. There is no HTTP JSON generation endpoint or iframe result
+message protocol in this contract.
+
+## Endpoints and responsibility
+
+| Path | Role |
+| --- | --- |
+| `/fmg` | Embedded renderer receiving a burg URL. |
+| `/` | Human-facing application; do not use it as the burg-rendering endpoint. |
+| `/symbols` | Artwork browsing, outside the input protocol. |
+
+The host supplies the URL and owns its surrounding UI. The renderer parses it,
+generates SVG and displays success, warnings or a visible error. Hosts cannot
+read a cross-origin iframe's model, GeoJSON or JavaScript result. Direct library
+consumers can read those results without an iframe.
+
+## Build a complete link
+
+```js
+import { encodeBurgParam } from 'settlemaker';
+
+const burg = {
+  name: 'Ashford', population: 300, biome: 'temperate',
+  port: false, citadel: false, walls: false, plaza: true,
+  temple: true, shanty: false, capital: false,
+  roadBearings: [
+    { bearing_deg: 36, kind: 'main', route_id: 'r17', through: true },
+    { bearing_deg: 209, kind: 'main', route_id: 'r17', through: true },
+    { bearing_deg: 117, kind: 'town', route_id: 'r23' },
+  ],
+};
+const url = new URL('https://settlemaker.com/fmg');
+url.searchParams.set('i', await encodeBurgParam(burg, 42));
+console.log(url.href); // use as the iframe src or external-open link
+```
+
+The codec uses Web Platform globals, including
+`CompressionStream('deflate-raw')` and `DecompressionStream('deflate-raw')`.
+Verify support in the host environment. The library provides no compression
+polyfill. The full [input reference](api.md#burg-input) is shared with direct
+library calls; always supply all required flags explicitly.
+
+## Compressed payload
+
+`i=` contains this envelope:
+
+```json
+{
+  "v": 1,
+  "burg": {
+    "name": "Ashford",
+    "population": 300,
+    "port": false,
+    "citadel": false,
+    "walls": false,
+    "plaza": true,
+    "temple": true,
+    "shanty": false,
+    "capital": false
+  },
+  "seed": 42
+}
+```
+
+Encoding is JSON → UTF-8 → raw DEFLATE → unpadded base64url. Raw DEFLATE has no
+zlib/gzip header. `encodeBurgParam` and `decodeBurgParam` implement this envelope;
+`encodeJsonParam` and `decodeJsonParam` provide the generic JSON codec used by
+presentation overrides.
+
+`v` must equal 1. `seed` is optional; otherwise generation derives it from the
+burg name. The decoder checks the envelope, a plausible name/population and any
+water context. It is not complete validation of every burg field. Validate
+untrusted integration data before calling generation.
+
+`i=` takes precedence over **all flat data fields**, including a flat `seed`.
+A malformed `i=` is an error, not permission to retry with flat fields.
+Presentation parameters remain separate and apply after input decoding.
+
+## Roads
+
+Send one record per **actual land approach**, with its independently measured
+clockwise bearing from north. Keep both sides of a continuing route even when
+they are not 180 degrees apart; use the same `route_id` for those two records.
+`through: true` is a hint and never creates an exit.
+
+| Source meaning | `group` | `kind` |
+| --- | --- | --- |
+| Known land-road class | `roads` | `royal`, `main`, `market`, `town`, `local` |
+| Known trail class | `trails` | `trail`, `footpath` |
+| Road group without a class | `roads` | `road` |
+| Trail group without a class | `trails` | `foot` |
+| Sea, air or trade-only network without a land approach | — | Exclude from land approaches. |
+
+Do not transmit UI labels such as `"roads / royal"` as a kind. `local` is accepted,
+but an adapter should not invent it for missing source classes. `relief` and
+`followsRiver` carry optional city growth hints. See [road inputs](api.md#roads).
+
+Village approaches preserve source provenance as they join shared internal
+streets. Drawn village street classes can change to `town`, `local` or `footpath`;
+a small roadside hamlet can retain a major through road. City outputs use their
+legacy road/foot categories and gate matching. Do not assume identical feature
+counts or names in both engines.
+
+An explicit `roadBearings: []` means no external approaches. Omitted approaches
+also produce none in villages; the city planner retains its legacy random-gate
+fallback when the field is absent.
+
+## Water and physical units
+
+The full [water-context v1 specification](water-context-v1.md) remains the
+normative contract for measured **villages, population 1–1,000**. A city input with
+`waterContext` is rejected with `water-context-unsupported-engine`; the host must
+not strip the object and silently reinterpret its metre geometry as city units.
+
+| Input | Village | City |
+| --- | --- | --- |
+| `coastlineGeometry` | Filled polygons in burg-local metres | Filled polygons in city-local mesh units |
+| `rivers` | Centreline, positive `widthM`, optional `meander: false` | Not consumed by city generation |
+| `oceanBearing` | Generated coast when explicit/measured inputs do not supersede it | Legacy generated coast fallback |
+| `waterContext` | Validated survey/unknown-unit mode | Rejected |
+
+Positive x points east and positive y south. Do not send geographic coordinates
+or assume city-local units are metres. `port` controls infrastructure, not water
+visibility. A `coastal` biome chooses artwork but does not itself add an ocean.
+
+A nonempty `coastlineGeometry` array represents **filled areas**, not bank lines.
+Include all relevant water polygons and preserve narrow channels and bends. For
+village rivers, supply a centreline with width or a filled polygon, not duplicate
+representations. `followsRiver` alone creates no water.
+
+For measured water, carry summaries, polygon associations, declared geometry
+error and survey coverage together. An empty measured survey suppresses the
+legacy coast; unknown units remain a diagnostic state. URL compression/length
+problems must not fall back to a flat URL that loses measured-water semantics.
+Simplify only within the declared physical error budget, or show an encoding error.
+There is no automatic iframe resurvey protocol.
+
+## Flat parameters
+
+The flat tier is convenient for manual examples:
+
+```text
+https://settlemaker.com/fmg?name=Ashford&pop=300&seed=2&biome=temperate&plaza=1&temple=1&roads=18:main,142:town,267:local
+```
+
+| Parameter | Parsed meaning |
+| --- | --- |
+| `name` | Name; default derived from seed/population if omitted. |
+| `pop` | Finite population; defaults to 300. |
+| `seed` | Optional numeric seed. |
+| `port`, `citadel`, `walls`, `plaza`, `temple`, `shanty`, `capital`, `trade` | True for `1` or `true`; otherwise false. |
+| `biome` | Input biome name. |
+| `urbanDensity`, `coreCapacity` | Optional positive numbers. |
+| `oceanBearing` | Optional finite compass bearing. |
+| `harbourSize` | `large` or `small`. |
+| `roads` | Comma-separated `bearing[:class[:through]]` records. |
+
+`roads=36:main:through,209:main:through,117:town` supplies all three approaches.
+Bearings wrap into `[0, 360)`; default class is `main`. Valid flat classes are the
+seven land classes in `ROUTE_CLASS_ORDER`; legacy/group aliases are not accepted
+by this flat syntax. Invalid classes or continuation tokens throw a `roads` error.
+Flat records cannot carry route IDs, relief, river following or measured water.
+
+With no data fields, `parseSettlementUrl` chooses a demo input and seed. That
+includes a URL containing only presentation fields. A URL with explicit input and
+a resolved seed is reproducible within the same deployed generator version; the
+bare demo URL intentionally is not.
+
+## Presentation
+
+| Parameter | Used by | Meaning |
+| --- | --- | --- |
+| `theme` | City | Named palette. |
+| `style` | City | Compressed JSON with partial `RenderTheme` overrides. |
+| `villageTheme` | Village | One of `temperate`, `desert`, `tundra`, `tropical`, `coastal`. |
+
+City palette keys are `default`, `classic`, `parchment`, `blueprint`, `bw`, `ink`,
+`night`, `ancient`, `colour`, `simple`. `default` aliases `parchment`; `classic` selects the
+original classic palette. The parser returns the name; a renderer must validate it against
+`PALETTES` and display an unknown-palette error itself.
+
+`style` accepts hex colour fields, nullable water colours, finite theme numbers
+and a finite `{dx, dy}` shadow offset. Unknown fields/wrong value shapes are dropped
+by `sanitizeThemeOverrides`. Accepted material keys include `smInk`, `smStone`,
+`smTimber`, `smVoid`, `smCanopy1`, `smCanopy2`, alongside the geometry style fields in
+[RenderTheme](../src/output/render-theme.ts). This is not arbitrary CSS.
+
+`villageTheme` changes ground, water, shadows and material tokens without changing
+the input biome's dwelling/landscape selection. An invalid name is a
+`UrlCodecError` with reason `villageTheme`, even when the city engine would run.
+The city presentation fields have no effect on the village renderer, and vice versa.
+
+**Skins are a direct library feature.** There is no `skin=` URL option, remote skin
+fetch, or embedded skin definition in this protocol. A host that offers a skin
+picker must explicitly load a definition and pass the resulting handle to the
+library API. There is also no `symbols=` or `fit=` URL option in this parser.
+
+## Implementing a renderer
+
+```js
+import {
+  parseSettlementUrl, generateSettlement, PALETTES, villageThemeFor,
+} from 'settlemaker';
+
+// In a browser page:
+const parsed = await parseSettlementUrl(new URLSearchParams(location.search));
+const palette = parsed.paletteName === undefined ? undefined : PALETTES[parsed.paletteName];
+if (parsed.paletteName !== undefined && !Object.hasOwn(PALETTES, parsed.paletteName)) {
+  throw new Error(`Unknown palette: ${parsed.paletteName}`);
+}
+const result = generateSettlement(parsed.burg, {
+  seed: parsed.seedOverride,
+  svg: { palette, theme: parsed.themeOverrides },
+  village: parsed.villageThemeName
+    ? { theme: villageThemeFor(parsed.villageThemeName) }
+    : undefined,
+});
+// Display result.svg and any result.waterContextResult diagnostics.
+```
+
+Wrap parsing/generation in your page's error handler. `UrlCodecError.reason` can
+be `base64`, `inflate`, `json`, `version`, `shape`, `villageTheme` or `roads`.
+Fatal water errors use `WaterContextError.waterContextResult`; successful measured
+results can still contain warnings. Keep errors and warnings visible without
+hover or interaction, including inside pointer-disabled previews.
+
+The library does not render diagnostic cards for you. An iframe host must provide
+those in its page, and must not assume a source-map popup or console error is a
+usable explanation for an embedded user. See [embedding and zoom](fmg-embed-zoom.md).
+
+## Deployment and compatibility
+
+Pin the renderer to a tested library release, deploy its diagnostics alongside it,
+then enable corresponding measured-water inputs in the sending application.
+Validate preview and external-open links together. Do not infer website support
+from the npm `latest` tag.
+
+Payload v1 evolves through optional additions. Breaking changes to the envelope
+require a new version; decoders reject an unsupported version. Geometry changes
+can occur without a URL or GeoJSON version bump, so save the package/build version
+with any cached preview or generated IDs.
+
+[Current generated fixtures and preview links](gallery.md) · [Input API](api.md)