settlemaker 3.0.0 → 3.0.1

package/docs/fmg-embed-zoom.md

@@ -0,0 +1,54 @@
+# Embedding and zoom
+
+This is guidance for an application hosting the [URL renderer](url-api.md), not
+an API for controlling a cross-origin iframe after loading it. The npm package
+generates SVG; the host page supplies layout, zoom, downloads and diagnostics.
+
+## Responsive preview
+
+Put the map in a viewport-sized container and scale the SVG with CSS using its
+`viewBox`. City and village roots need not have identical size attributes. Size
+the displayed element explicitly rather than assuming that generated width and
+height attributes alone implement a responsive layout.
+
+```css
+html, body, #map { margin: 0; width: 100%; height: 100%; }
+#map svg { display: block; width: 100%; height: 100%; }
+```
+
+Keep the full view box as the initial fit if the preview is intended to show the
+entire settlement and its surrounding terrain. Cropping the frame is a host
+presentation decision; it changes what is visible, not the generated settlement.
+There is no `fit=cover` URL parameter in the current library parser.
+
+## Host-owned navigation
+
+A parent page can pan a larger iframe inside an overflow-hidden container. If it
+uses layout resizing for zoom, the renderer should remain responsive to viewport
+changes without regenerating the settlement. Regeneration on each resize can
+block interaction and does not belong in zoom handling.
+
+A host using its own SVG DOM can implement local pan/zoom directly. A cross-origin
+iframe does not expose that DOM to its parent. This contract defines no
+`postMessage` zoom, result, or automatic water-resurvey messages. Specific zoom
+limits and input gestures are application choices, not engine guarantees.
+
+## Diagnostics remain visible
+
+A renderer must show parse/generation errors and measured-water warnings within
+the page. Some embedded previews disable pointer events, so explanations must be
+readable without hovering or clicking. Do not replace a failed measured-water map
+with a plain dry map. Include required survey coverage when an error supplies it.
+
+Map navigation and diagnostics need deliberate layout: a warning should remain
+readable at the initial fit rather than being reduced to an unreadable part of a
+zoomed map. The older expectation of an SVG-only page does not override the
+measured-water diagnostic requirements.
+
+## Multiple maps and tiles
+
+Use separate image/iframe documents for independent maps. Inline SVGs can share
+conflicting IDs even with different city `clipId` options. See the
+[SVG embedding rules](scene-schema.md#embedding-svg) and
+[local tile helpers](geojson.md#tiling). Preserve `data-bg="paper"` and village
+scale metadata when post-processing output for those helpers.

package/docs/gallery.md

@@ -0,0 +1,139 @@
+# Gallery
+
+These maps were generated with SettleMaker 3.0.1 through the public
+`generateSettlement` API. PNG previews and full SVGs come from the same output.
+The gallery covers all five built-in artwork biomes in both engines, plus Copperline.
+
+[Exact inputs and seeds](examples/gallery/fixtures.json) · [Regenerate the gallery](development.md#documentation-checks)
+
+Hosted preview links carry the saved inputs; the website's deployed generator may
+differ from this package version. Skins are loaded by the library API, so the
+Copperline examples link to their SVGs rather than an unsupported skin URL.
+
+## Ashford — temperate village
+
+Roads, individual homes, a green and cultivated fields.
+
+Population **300** · seed **2** · engine **village**
+
+[![Ashford — temperate village](examples/gallery/temperate-village.png)](examples/gallery/temperate-village.svg)
+
+[Full SVG](examples/gallery/temperate-village.svg) · [Hosted preview](https://settlemaker.com/fmg?i=dZDLasMwEEX_5a5VSNzSBO3a3yghTKJJLCpLQhrXtCb_3nEeDg10pyvuORrNiC_YpcGuL0fYETkVgT1QqGyw90KOw5wHCqHOKQf6IVgpvQbhLge-pdpSlO-7h7Ka7p6SyL0zFR-PqvsYsbuErWMdYrk2-PTRwaIjHzH1e-Gtn26iztc-TQKczCP40sykpOGBrHr8j2xeVzMZ0l5H_YMOXOVKbgwidfpRvNX2kIrTZk65DyQ-RdjnxUKX6dO5Mi2FCwnri6jM6mpOvw)
+
+## Thornwall — walled city
+
+Native city buildings, denser central wards, greener outskirts and defensive walls.
+
+Population **10000** · seed **2** · engine **settlement**
+
+[![Thornwall — walled city](examples/gallery/temperate-city.png)](examples/gallery/temperate-city.svg)
+
+[Full SVG](examples/gallery/temperate-city.svg) · [Hosted preview](https://settlemaker.com/fmg?i=dZDBasMwEET_Zc4qNKakRcd-Q24hmE28jUVkSUjrmNbk37tqa5cGqpNGzJsd7Ywr7MbgOOYz7IwUs8C-kS9scHJCHXtYyaPKibwvi0iePmgRwkPyvKjSU5D33xRKmrOm5EjdK1N24axh-xnHb9F2rA02LwYXFzpYDOQCqn8Ubl19CVquf6gBuJl78KlZSYnTHVn0-h_ZbJ9X0seTNv2DTlzkhzwYBBr0n9j1MYe6D_WmmEZP4mLQFo96dJsuftnqXjiTsE5FYda85vYJ)
+
+## Qasra — desert village
+
+Desert buildings, sparse vegetation and irrigated field textures.
+
+Population **300** · seed **2** · engine **village**
+
+[![Qasra — desert village](examples/gallery/desert-village.png)](examples/gallery/desert-village.svg)
+
+[Full SVG](examples/gallery/desert-village.svg) · [Hosted preview](https://settlemaker.com/fmg?i=dZDBasMwEET_Zc4KJE5oi479g55LMJtom4jKkpDWNa3xv3fdJg4N9KYR84bZGfEBuzE49OUEOyKnIrBvFCobHL2Q47DogUKoi8qBvghWSq9CuMuBr6qeKcrnLYeyJt1ySiL3zFR8PGnc64jDr2gda4nNk8G7jw4WHfmI2d8Lt37-idrvvJoDMJl7cNcspKThjqz6_I9sHh4XMqSjVv2DDlzlQu4NInV6KF6oFlJfTrkPJD5F2O16rVP69GNwXFnHnHQOZo1ppm8)
+
+## Qasr — desert city
+
+Urban desert architecture, religious buildings and courtyards.
+
+Population **10000** · seed **2** · engine **settlement**
+
+[![Qasr — desert city](examples/gallery/desert-city.png)](examples/gallery/desert-city.svg)
+
+[Full SVG](examples/gallery/desert-city.svg) · [Hosted preview](https://settlemaker.com/fmg?i=dZBRi8IwEIT_yz5HOIt4kkf_gc8iZTV7GtwmIdlatPS_u7279jjBPGXCfMNkeriBXRo4tvkMtocUs4D9Qi5k4OQFHTFYya3KDpnLJBLjAych1CSmSZULBrn_pWDSHJ51jui2hNmHs6btezj-iNqRVlhuDFx9cGChQR9g9LdCtR9fgra7LMYAGMwruKpmUmL3Qha9viOr9edMcjxp1X9oR0V-yYOBgI1-FHZYstpSTC2j-Bi0wIceXdLHb4ejQrrloHsQaU41PAE)
+
+## Snowmere — tundra village
+
+Snowy dwellings and low tundra vegetation with natural ground instead of arable fields.
+
+Population **300** · seed **2** · engine **village**
+
+[![Snowmere — tundra village](examples/gallery/tundra-village.png)](examples/gallery/tundra-village.svg)
+
+[Full SVG](examples/gallery/tundra-village.svg) · [Hosted preview](https://settlemaker.com/fmg?i=dZDRTgIxEEX_5T7XBFaDpo_8go_GkIGO0NBtm3bqRjb8u7OgSyTxrbe553SmIz5hlwbbVvawI3IqAvtBobLBzgs5DnMeKIQ6pxzoRLBSmgbhPgf-TfVAUb5uHspqunlKIrdmKj7uVfc2YnsNG8c6xPLF4Oijg0VPPmLqN-GNn26iznd4mAQ4m3vwqZtJScMdWfX4H9mtnmcypJ2O-gcduMoP-W4QqddF8RrT0HNhreaUWyDxKcI-Lhb6mz5dOtKiK6TvoTKrqTt_Aw)
+
+## Frosthold — tundra city
+
+Northern roofs, fortifications and biome-specific ground.
+
+Population **10000** · seed **2** · engine **settlement**
+
+[![Frosthold — tundra city](examples/gallery/tundra-city.png)](examples/gallery/tundra-city.svg)
+
+[Full SVG](examples/gallery/tundra-city.svg) · [Hosted preview](https://settlemaker.com/fmg?i=dZDRTsMwDEX_xc9BYhUClEce-AmEJm_x1gg3jhKHCqr9O-6gnTaJPOVEPjc3meAT_MbBrpUj-AmyFAV_QK7kYB8VAzF4Lc1wROa6QGb8xgWUhsy0UO0x6dclBbPl8MpFMLwQlpiOlvY2we4XtoGswubZwUdMATwMGBPM801pG-eTZO36uzkATu5WfOhWU2W8Matt_zO7x6fVZNlb1St1pKp_5ruDhIM9FF6LVO2Fg81myY1RoyRrcW_LvjPKeUxbCgXtSqhEFtadfgA)
+
+## Reedbank — tropical river village
+
+A supplied river enables tropical paddy selection; fields follow real parcels.
+
+Population **300** · seed **2** · engine **village**
+
+[![Reedbank — tropical river village](examples/gallery/tropical-village.png)](examples/gallery/tropical-village.svg)
+
+[Full SVG](examples/gallery/tropical-village.svg) · [Hosted preview](https://settlemaker.com/fmg?i=dZBBT8MwDIX_i8-d1A0YkCP3XbiiaXIbs1pLkyhxV6Dqf8fdRgeTuPlZ_p6fPcARzLKAqkt7MAPEkATMO7pMBdQsaMnNukfn8qyiwy8EI6lTIdRGRz8qN-jl8-qDUZ2uPimgfSFM7Pdq9zZAdRY7Sxpi-VTAgb0FAy2yh2m-E9rx1PGar1lMBjAWt-D9aiYl9Ddk1vI_crV-nEkXao36B-0py4XcFuCx1UPhlchW6A86GkPsHAoHD-auLPWbHE4zkkLkix0fKZ2vrclLIseeTvIDzOJhovRhz-WUTTu_GrqyZyvNBsx63I76Xd2smcdv)
+
+## Palmreach — tropical city
+
+Tropical architecture and vegetation in the city engine.
+
+Population **10000** · seed **2** · engine **settlement**
+
+[![Palmreach — tropical city](examples/gallery/tropical-city.png)](examples/gallery/tropical-city.svg)
+
+[Full SVG](examples/gallery/tropical-city.svg) · [Hosted preview](https://settlemaker.com/fmg?i=dZDRisIwEEX_ZZ4jaBGVPPoFvouUsZ21wWkSkqllt_Tfne5uu6xgnnLDnMPNDPAAuzFw7dIN7AAxJAH7gZzJQOUEa2KwkjqNPTLnOUTGL5yDUBuZ5pQb9PL5Z8GoHl5yClgfCZPzN7WdB7j-hLImrbA5GLg7X4OFFp2Hab4TKt304rVds5oEMJpXcFsspIT-hcx6fUcWu_1Ccqi06j-0pyy_5MWAx1Y_CifkNhFWjc7GEDtGccFri7UeXacL32OSQnSTcdS1EKmuGJ8)
+
+## Dunewick — coastal village
+
+A generated coast from oceanBearing, with coastal buildings and vegetation.
+
+Population **300** · seed **2** · engine **village**
+
+[![Dunewick — coastal village](examples/gallery/coastal-village.png)](examples/gallery/coastal-village.svg)
+
+[Full SVG](examples/gallery/coastal-village.svg) · [Hosted preview](https://settlemaker.com/fmg?i=XY_RbsIwDEX_xc9Bapn2sDyi_cU0ITfxICLEUepQbVX_fW6BIng8lu_x9QgXsK2BrpYD2BEyFwH7g7EnAy4IeoorDxhjv1KO-IdgpVQFoXOOdKf-iEl-Hx7Manp4CqPfEZaQDqr7GqG7wt6Tlti2jYFTSB4sCA8J5kAV2od54hh72cwGmMxL8q19X5ORnV58ivqaaJNRjjB9G0h41r7wqcMhuJOuZs41ogROqmq0RBd42VluLjZ2hOlWHexHM-mvRCrfTv8)
+
+## Saltmouth — port city
+
+Port infrastructure beside a generated coastline. This is a bearing-based coast, not a measured survey.
+
+Population **12000** · seed **2** · engine **settlement**
+
+[![Saltmouth — port city](examples/gallery/coastal-city.png)](examples/gallery/coastal-city.svg)
+
+[Full SVG](examples/gallery/coastal-city.svg) · [Hosted preview](https://settlemaker.com/fmg?i=RY69DsIwDITfxXOGUCYy8godEYNpTRvJjaP8gGjVd8dFFMY7n7-7BR7gDgZuNQ3gFoiSCriSKhnofMGeGNwdOat-InPej5Fxxl0UmiLTrvKIobx-bx1GBf0xSbA_EyYfBqVdGmvN0dqrgYCTMqBFLpPUMoK2SKyMxUvQlZq0utTLJ9YJ5g1rYMR0k5paP28-YxpIXekIw7cH3MmuOoyoB9esbw)
+
+## Copperline — industrial village
+
+The same village planner with a complete replacement skin and industrial artwork.
+
+Population **250** · seed **2** · engine **village**
+
+[![Copperline — industrial village](examples/gallery/copperline-village.png)](examples/gallery/copperline-village.svg)
+
+[Full SVG](examples/gallery/copperline-village.svg) · [Skin JSON](examples/copperline.skin.json)
+
+## Brassworks — steampunk city
+
+Copperline machinery and brass materials on the existing city layout and semantic feature types.
+
+Population **2000** · seed **2** · engine **settlement**
+
+[![Brassworks — steampunk city](examples/gallery/copperline-city.png)](examples/gallery/copperline-city.svg)
+
+[Full SVG](examples/gallery/copperline-city.svg) · [Skin JSON](examples/copperline.skin.json)
+
+## One layout, another palette
+
+Thornwall with the same inputs and seed, using `svg.palette: PALETTES.night`.
+City palettes alter presentation; they do not replace all native material tokens.
+Use a skin for complete artwork and material control.
+
+[![Thornwall with the night palette](examples/gallery/temperate-city-night.png)](examples/gallery/temperate-city-night.svg)

package/docs/geojson.md

@@ -0,0 +1,188 @@
+# GeoJSON, coordinates and identity
+
+Both planners return a `FeatureCollection` with a top-level `metadata` foreign
+member. The current `metadata.schema_version` is **4**. Filter features by
+`properties.layer`, then inspect the geometry type and the fields for that engine.
+Do not assume that sharing a schema number makes the two planners interchangeable
+at the individual property level.
+
+The return type is the standard GeoJSON `FeatureCollection` type. It does not
+expose every engine-specific foreign member statically. Applications reading
+metadata from external files should validate it before use; the tables below
+describe the generated data.
+
+## Coordinate frames
+
+| Property | Village | City |
+| --- | --- | --- |
+| `metadata.coordinate_system` | `burg_local_y_down` | `local_origin_y_down` |
+| `metadata.coordinate_units` | `metres` | `settlement_units` |
+| Origin | Original burg position | Local output frame; may include the coastal translation |
+| Axes | x east, y south | x right/east, y down/south |
+| `scale.meters_per_unit` | 1 | Population-based estimate |
+| `scale.source` | `village_metres` | `population_heuristic_v1` |
+| `local_origin_shift` | `{dx: 0, dy: 0, source: 'none'}` | Actual translation and reason |
+
+These are **local planar coordinates**, not WGS84 longitude and latitude. A GIS
+or map library expecting geographic GeoJSON needs an explicit placement transform.
+Do not feed them directly into a geographic map and expect correct placement.
+The city scale is an estimate, not a physical survey. This is why measured
+`waterContext` is currently restricted to the village planner.
+
+`metadata.local_bounds` has `min_x`, `min_y`, `max_x`, `max_y`. For villages this is
+the drawn tile frame in metres. Village SVG coordinates are translated and scaled
+for display; the root's `data-px-per-metre` records that scale. In particular,
+changing `village.pxPerMetre` does not change GeoJSON coordinates.
+
+## Shared metadata
+
+| Key | Meaning |
+| --- | --- |
+| `schema_version` | Output structure version, currently 4. |
+| `settlemaker_version` | Package/generator version. Record it with saved maps. |
+| `settlement_generation_version` | City input hash or the village marker `'village'`; not a complete cache key. |
+| `generated_at` | Generation timestamp; differs between otherwise identical runs. |
+| `local_bounds` | Local output extent. |
+| `scale` | `meters_per_unit`, `diameter_meters`, `diameter_local`, `source`. Diameter describes settlement scale, not necessarily the full surrounding frame. |
+| `stable_ids` | Engine-specific ID hints; treat actual IDs as opaque strings. |
+| `poi_density` | `'hamlet'` or `'town'` POI regime. This is not the village/city planner discriminator. |
+| `degraded_flags` | Dropped city walls/citadel requests; empty for villages. |
+| `local_origin_shift` | Output translation. Do not apply it again to already generated output. |
+
+City outputs above population 1,000 also carry `building_capacity`:
+`basis: 'ordinary-building-budget'`, `target`, `placed`, `shortfall`, `corePlaced`,
+`outerPlaced`, and `status: 'met' | 'shortfall'`. `corePlaced + outerPlaced = placed`;
+`shortfall = max(0, target - placed)`. These are ordinary-building counts, not a
+certified housed population. The same object is available through
+`Model.getBuildingCapacity()` and `Scene.buildingCapacity`.
+
+Village metadata adds `contract_radius_m`, `green_relation`, optional `outline_m`
+and `diagnostics`. The contract circle locates supplied approaches, while
+`local_bounds` describes the drawn frame; they are different extents. Measured
+water diagnostics are returned as `result.waterContextResult` and on the village
+site. Do not assume there is an equivalent top-level GeoJSON field.
+
+## City features
+
+| `layer` | Geometry | Selected properties |
+| --- | --- | --- |
+| `ward` | Polygon | `wardType` |
+| `building` | Polygon | `building_id`, `wardType` |
+| `street` | LineString | `street_id`, `streetType` (`artery`, `road`, `alley`, `park`), optional `width` |
+| `green` | Polygon | `kind: 'garden'`, `wardType` |
+| `water` | Polygon / MultiPolygon | Water geometry; inspect the emitted geometry type. |
+| `wall` | LineString | `wallType` |
+| `tower` | Point | `wallType` |
+| `entrance` | Point | `entrance_id`, gate type, bearings and matched route information |
+| `pier` | Polygon | `wardType` |
+| `poi` | Point | `poi_id`, `kind`, `ward_type`, `building_id` |
+
+City POIs may be attached to an ordinary building, or float at a placed well,
+market, mill or pier. Those floating kinds use `building_id: null`; other adopted
+POIs have a building ID. Ward labels describe attribution, not a guarantee that
+the feature lies inside the corresponding ward polygon. The engine does not
+supply narrative names for streets or POIs.
+
+City bridge rendering information is available in `Scene.layers.bridges`;
+there is no matching promise that city GeoJSON contains village-style `crossing`
+features. Likewise, city park/field/vegetation rendering is richer than the
+selected GeoJSON layers above; use the scene when reproducing city presentation.
+
+## Village features
+
+| `layer` | Geometry | Selected properties |
+| --- | --- | --- |
+| `building` | Polygon | `building_id`, `lot_id`, `glyph`, `occupancy`, `bearing_deg` |
+| `street` | LineString | `street_id`, `streetType`, widths, setback, optional route provenance and role |
+| `green` | Point | `shape`, `variant`, `diameter_m`, `bearing_deg`, `relation`, optional `outline_m` |
+| `field` | Polygon | `field_id`, `glyph`, `furrow_bearing_deg` |
+| `water` | Polygon | `water_id`; interior rings preserve land islands when present |
+| `crossing` | Point | `crossing_id`, `street_id`, `span_m`, `bearing_deg`, `narrow`, optional deck and centreline |
+| `wall` | LineString | `wall_id`, `wallType: 'village_wall'`, `material` |
+| `gate` | Point | `gate_id`, `route_ids` |
+| `junction` | Point | `junction_id`, `street_ids` |
+| `poi` | Point | `poi_id`, `kind`, `glyph`, `bearing_deg` |
+
+Village POIs do not carry the city POI `building_id`/`ward_type` contract. A village
+green is a Point plus shape data, whereas a city garden is a Polygon. Village
+wall openings are `gate` features, not city `entrance` features. Consumers must
+branch where these differences matter.
+
+### Village road cross-sections
+
+| Property | Meaning in metres |
+| --- | --- |
+| `width_m` | Reserved road corridor. |
+| `surface_width_m` | Painted travelled surface. |
+| `setback_m` | Additional distance from corridor edge to parcel frontage. |
+| `surface_clip_m` | Optional polygon limiting paint at a width transition. |
+
+The frontage offset from the centreline is `width_m / 2 + setback_m`. A surface
+width is not a parcel reservation. `route_role` can be `approach`, `street` or
+`through`; `streetType` describes the drawn segment's class, which may differ
+from the incoming route class. `route_ids` carries provenance on shared or
+continuing streets. Optional `parent_street_id` records the model's parent lane.
+
+Street LineStrings stay continuous for connectivity. To reproduce the map's
+surfaces, clip road paint out of water and apply any `surface_clip_m`. Render
+short bridge decks separately using crossing `deck_m` and `centreline_m` where
+present and `narrow` is true. A continuous line through water alone is not a
+bridge surface. Decks include dry abutments; do not use the Point feature as the
+entire deck geometry.
+
+## IDs and persistence
+
+Every street feature has its own `street_id`. A supplied route ID can appear on
+multiple approach/continuation features; it identifies external provenance, not
+a unique generated street. Village junctions name the participating street IDs.
+City gate features echo matched input routes in `matched_route_id` and, where
+present, `matched_route_ids`.
+
+Do not parse prefixes to discover geometry or engine type. City IDs are allocated
+with prefixes such as `b`, `s`, `p`, `g`; village IDs use their own content-derived
+forms. IDs repeat for identical inputs within a generator version, but are not
+promised stable across releases. Persist user annotations with the generating
+configuration and have a migration strategy if you regenerate after an upgrade.
+
+Skins retain semantic IDs and categories. A Copperline power-station drawing can
+occupy a religious-building slot; it does not turn the GeoJSON kind into a new
+industrial feature taxonomy. Store the requested skin and biome separately.
+
+## Tiling
+
+The package crops an SVG into a local square tile pyramid. It does not assign
+geographic web-map coordinates or rasterize PNG tiles for you. Starting with a
+`result` and its original `burg`:
+
+```js
+import {
+  parseSvgViewBox, declaredMetersPerUnit, computeTileInfo, cropSvgToTile,
+} from 'settlemaker';
+
+const viewBox = parseSvgViewBox(result.svg);
+if (!viewBox) throw new Error('SVG has no usable viewBox');
+const tileInfo = computeTileInfo(
+  viewBox,
+  burg.population,
+  declaredMetersPerUnit(result.svg),
+);
+const rootTileSvg = cropSvgToTile(result.svg, tileInfo, 0, 0, 0);
+```
+
+`declaredMetersPerUnit` reads village SVG scale so the tile helper does not
+substitute its population heuristic. City SVGs use the helper's scale estimate
+when no explicit override is supplied. Preserve `data-bg="paper"` if you
+post-process a generated SVG: the cropper uses that rectangle to extend the
+background to the tile bounds.
+
+Use `enumerateTiles(tileInfo.maxZoom)` or `totalTileCount` to plan the pyramid,
+and a rasterizer such as your application's SVG image pipeline if you need PNGs.
+Keep your host-map placement transform separate from this local z/x/y scheme.
+
+## Version handling
+
+Check `metadata.schema_version === 4` for this contract, and tolerate optional
+fields and unfamiliar layers that your application does not use. A future
+breaking structure change needs a new schema version. Additive artwork or road
+fields need not change that number. The old [schema-v3 note](schema-v3.md) is a
+historical migration record, not the schema check for current output.

package/docs/getting-started.md

@@ -0,0 +1,157 @@
+# Getting started
+
+SettleMaker is an ES module library. The examples here use Node 24, the runtime
+used to validate the 3.0.x npm release. A source checkout also includes an optional
+Nix development shell; Nix is not required to install or use the npm package.
+
+## Node.js
+
+```sh
+mkdir my-settlements
+cd my-settlements
+npm init -y
+npm install settlemaker
+```
+
+Save the following as `generate.mjs`. The `.mjs` extension enables ESM without
+changing your project's package settings; alternatively use `.js` and set
+`"type": "module"` in your package.json.
+
+```js
+import { writeFile } from 'node:fs/promises';
+import { generateSettlement } 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 = generateSettlement(burg, { seed: 42 });
+await writeFile('thornwall.svg', result.svg);
+await writeFile('thornwall.geojson', JSON.stringify(result.geojson, null, 2));
+console.log(result.kind, result.degradedFlags);
+```
+
+```sh
+node generate.mjs
+```
+
+Open the SVG in a browser or vector editor. Generation is synchronous; it can take
+noticeable time for large inputs. In an interactive app, run expensive generation
+in a worker so it does not block the UI. There is no asynchronous generator or
+cancellation API in this release.
+
+For CommonJS, load the ESM package from an async function:
+
+```js
+async function main() {
+  const { generateSettlement } = await import('settlemaker');
+  // Call generateSettlement with the complete burg object shown above.
+  console.log(typeof generateSettlement);
+}
+main().catch(console.error);
+```
+
+## TypeScript
+
+Declarations are included, and `@types/geojson` is installed transitively.
+For Node ESM projects, use `module: "NodeNext"` and `moduleResolution: "NodeNext"`,
+with a modern target and the `DOM` library if you explicitly configure `lib`:
+URL helpers use Web Platform types. Install `@types/node` in your own project
+when your code imports Node built-ins.
+
+```ts
+import { generateSettlement, type AzgaarBurgInput } from 'settlemaker';
+
+const burg: AzgaarBurgInput = {
+  name: 'Ashford', population: 300,
+  port: false, citadel: false, walls: false, plaza: true,
+  temple: true, shanty: false, capital: false,
+};
+const result = generateSettlement(burg, { seed: 2 });
+if (result.kind === 'village') {
+  console.log(result.model.buildings.length); // VillageModel
+} else {
+  console.log(result.model.patches.length);   // city Model
+}
+```
+
+`GenerationParams` is an interface, not a constructor. For the city pipeline use
+`mapToGenerationParams(burg, seed)` before `new Model(params).generate()`.
+See [lower-level rendering](scene-schema.md#render-an-existing-city-model).
+
+## Browser applications
+
+With a bundler, use the same package import as Node:
+
+```js
+import { generateSettlement } from 'settlemaker';
+```
+
+For a page without a bundler, copy
+`node_modules/settlemaker/dist/settlemaker.browser.js` into an asset directory
+served by your application. This standalone ESM bundle includes the runtime
+code and default artwork; it does not fetch SVG files during generation.
+
+```html
+<!doctype html>
+<html lang="en">
+  <meta charset="utf-8">
+  <title>My settlement</title>
+  <style>#map svg { display: block; width: 100%; height: auto; }</style>
+  <div id="map"></div>
+  <script type="module">
+    import { generateSettlement } from './assets/settlemaker.browser.js';
+    const result = generateSettlement({
+      name: 'Ashford', population: 300, biome: 'temperate',
+      port: false, citadel: false, walls: false, plaza: true,
+      temple: true, shanty: false, capital: false,
+      roadBearings: [18, 142, 267],
+    }, { seed: 2 });
+    document.querySelector('#map').innerHTML = result.svg;
+  </script>
+</html>
+```
+
+Serve the page over HTTP during development. Use a separate image document or
+iframe for each map when displaying several maps: generated SVGs contain IDs
+that can collide if multiple copies are inserted into the same DOM. See
+[SVG embedding](scene-schema.md#embedding-svg).
+
+## Load a portable skin
+
+In Node, resolve the example distributed inside the installed package:
+
+```js
+import { readFile } from 'node:fs/promises';
+import { createSkin, generateSettlement } from 'settlemaker';
+
+const definitionUrl = import.meta.resolve('settlemaker/docs/examples/copperline.skin.json');
+const definition = JSON.parse(await readFile(new URL(definitionUrl), 'utf8'));
+const skin = createSkin(definition);
+const result = generateSettlement({
+  name: 'Brassworks', population: 2000, biome: 'steampunk',
+  port: false, citadel: false, walls: false, plaza: true,
+  temple: true, shanty: false, capital: false,
+  roadBearings: [20, 145, 270],
+}, { seed: 42, skin });
+console.log(result.kind, result.svg.length);
+```
+
+In a browser, host a skin JSON file with your application, fetch it, check the
+response and pass its parsed JSON to `createSkin`. Create the runtime handle with
+the same loaded module instance that performs generation. To transfer a skin to
+a worker or save it, transfer the definition JSON and load it there; do not
+serialize or move the runtime handle between independently loaded bundles.
+
+## Save and reproduce
+
+Store the complete burg input, explicit seed, package version, rendering options
+and skin definition/version. The same configuration reproduces the geometry and
+SVG within a package version. Geometry and feature IDs may change on upgrades.
+GeoJSON includes a creation timestamp, so complete JSON strings will differ even
+when the geometry is identical. The city-only `geojson.generatedAt` option can
+fix that timestamp; the village generator has no corresponding option.
+
+[Full API](api.md) · [Output coordinates](geojson.md) · [Skin authoring](skins.md)

package/docs/landscape-character-review.md

@@ -0,0 +1,55 @@
+# Landscape character review
+
+Historical review of the 2.7.0 artwork pass. Counts and validation below record
+that review, not the current release. See the [current gallery](gallery.md) and
+[artwork integration](artwork-integration.md) for maintained guidance.
+
+Reviewed through the public `generateSettlement` API in `output/art-integration/`.
+The river fixtures use coarse centrelines with default meandering enabled;
+straight authored polygons and the straight-channel override are not used for
+these natural rivers. The gallery links the previous release for visual comparison. Source changes are
+in the city-glyphs worktree; this refinement has not been released.
+
+## Observed results
+
+The gallery includes villages and 10,000-person cities in all five biomes,
+50,000- and 100,000-person temperate cities, a bridge village and a tropical
+river village with rice paddies. All use seed 2 except the bridge fixture (3).
+
+Roof coverage is building polygon area / residential ward area, grouped by
+centre-to-edge character. It excludes parks, roads outside wards and farmland;
+it is a visual-density diagnostic, not an occupancy or population claim.
+
+| Population | Centre | Middle | Edge | Main parks | Rural house glyphs |
+| --- | --- | --- | --- | --- | --- |
+| 10000 | 71.7% | 61.5% | 43.6% | 3 | 264 |
+| 50000 | 68.3% | 61.1% | 37.2% | 3 | 452 |
+| 100000 | 68.9% | 57.7% | 37.7% | 3 | 1678 |
+
+The 10,000-person capacity regression fixture retains its full 953-building
+budget. City planning keeps a 10% local supply reserve before the final census
+trim, with the existing minimum legible building size and capped core intact.
+The metropolis still reports any capacity shortfall instead of inventing housing.
+Gardens are actual parcel backgrounds, exported as additive green features.
+
+Village enclosure support lines sit 3.5 metres outside measured roof and porch
+bounds. Intersecting henge reservations enlarge only the affected part of that
+boundary; detached henges do not replace the village perimeter. Roads retain
+real openings and wet wall sections are omitted.
+
+## Validation
+
+- Full regression report: 1,417 passed, zero failures, `success: true`.
+- New behavioural coverage: species clustering, valid biome plant selections,
+  source-identical biome greens, softened crowns, desert versus paddy irrigation,
+  ocean-versus-river eligibility, measured wall clearance, city density gradient,
+  varied roofs, rural outskirts and garden GeoJSON correspondence.
+- Existing geometry/access, household budgets, POI identities, collision, water,
+  determinism and SVG/GeoJSON tests remain active. Tests that assumed one park,
+  one housing style, or no nested SVG groups now check the new contracts.
+- 372 saved landscape assets, 210 additional plant seeds, 42 snow comparisons,
+  30 seamless tiles, clear farm entrances and live gallery controls passed.
+- 60 green SVGs and 14 generated map SVGs parsed with unique IDs and resolved
+  internal references. Golden city renders were inspected and regenerated twice
+  to verify byte-for-byte determinism before updating their hashes.
+- TypeScript build, script typecheck and browser bundle passed.

package/docs/releases/3.0.1.md

@@ -0,0 +1,18 @@
+# 3.0.1 — current documentation and generated examples
+
+The npm README and public documentation now describe the 3.0.x library and its
+portable skin system. The README includes regenerated PNG/SVG examples from the
+current public API, with release-pinned links that work on npm and GitHub.
+
+New getting-started, API, GeoJSON, gallery and development guides replace the
+outdated entry-point examples and fragmented contract guidance. The URL and city
+scene guides document current options, coordinate/engine differences, rendering
+limits and separate website deployment. Schema v3 is clearly historical.
+
+The examples cover five default artwork biomes in both planners and Copperline.
+Documentation checks run the README examples, typecheck snippets and check links,
+anchors and gallery provenance. Public docs and gallery files ship in the package.
+
+Generation algorithms and artwork are unchanged from 3.0.0. Exported generator
+metadata reports 3.0.1; GeoJSON schema 4, Scene 2, URL payload 1, skin format 1 and
+water context 1 remain unchanged.