settlemaker 3.0.0 → 3.0.1

package/docs/README.md

@@ -0,0 +1,54 @@
+# SettleMaker documentation
+
+These guides describe the 3.0.x npm library. The declarations shipped in `dist/`
+and the corresponding [source](../src/index.ts) are the complete type reference.
+
+## Start here
+
+- [Getting started](getting-started.md): install, generate a map, use TypeScript or a browser.
+- [Gallery](gallery.md): current output across five biomes and both planners, plus Copperline.
+- [Library API](api.md): input fields, engine selection, options, errors and reproducibility.
+- [GeoJSON and coordinates](geojson.md): schema 4, local units, IDs, road geometry and tiling.
+
+## Create a setting
+
+- [Skin authoring](skins.md): portable JSON, SVG slots, biome inheritance and validation.
+- [Skin JSON schema](skins.schema.json): editor assistance for skin format 1.
+- [Current symbol library](current-symbol-library.md): downloadable collections versus runtime slots.
+- [Artwork integration](artwork-integration.md): how the planners place the current artwork.
+- [Copperline](../symbols/copperline/README.md): a complete example skin for technological settings.
+
+## Integrate an application
+
+- [URL adapter contract](url-api.md): compressed inputs and presentation parameters for `/fmg` hosts.
+- [Water context v1](water-context-v1.md): measured village water, precision, precedence and errors.
+- [Scene and rendering](scene-schema.md): city Scene v2, appearance controls and SVG embedding.
+- [Embedding and zoom](fmg-embed-zoom.md): responsive previews and host-owned navigation.
+
+## Maintain the project
+
+- [Development](development.md): build, checks, documentation images and release workflow.
+- [Example URLs](test-urls.md): reproducible fixtures for integration checks.
+- [3.0.1](releases/3.0.1.md) and [3.0.0](releases/3.0.0.md) release notes.
+
+## Contract versions
+
+| Contract | Current value | Meaning |
+| --- | --- | --- |
+| npm package | 3.0.1 | A specific engine and documentation release. |
+| GeoJSON `metadata.schema_version` | 4 | Output structure; both planners share this number. |
+| City `Scene.version` | 2 | Semantic city scene; villages do not use this scene type. |
+| URL envelope `v` | 1 | Compressed burg input for a URL adapter. |
+| Skin `version` | 1 | Portable artwork and biome definition. |
+| `waterContext.version` | 1 | Measured-water input, supported for villages only. |
+
+A shared schema version does not imply identical fields in every engine's feature
+properties. Check the [output reference](geojson.md) before sharing a renderer.
+Cache against the package version, inputs, seed and rendering/skin configuration.
+
+## Historical material
+
+[Schema v3](schema-v3.md) records an earlier city-output migration. Files under
+`plans/`, `superpowers/`, and older release notes record design discussions and
+past behaviour; they are not the current API specification. Start from the guides
+above when building a new integration.

package/docs/api.md

@@ -0,0 +1,175 @@
+# Library API
+
+The normal entry point is `generateSettlement(burg, options?)`. It returns
+synchronously and selects the planner by population. Import functions and types
+from `settlemaker`; the published declarations are the complete reference.
+
+## Engine selection
+
+| Entry point | Planner | Result |
+| --- | --- | --- |
+| `generateSettlement(burg, options)` | Village at population ≤ `VILLAGE_POP_CEILING` (1,000); city above it | Discriminated result: `kind: 'village'` or `'settlement'`. |
+| `generateFromBurg(burg, options)` | City, regardless of population | City result without a `kind` discriminator. |
+| `generateVillage(burg, seed)` | Village | `VillageModel`; call `renderVillage` and `generateVillageGeoJson` separately. |
+
+Use positive populations. The high-level API is typed but is not a complete
+validator of arbitrary input JSON. Validate external data in your application;
+water context and skin definitions have their own explicit validation gates.
+
+## Burg input
+
+The name `AzgaarBurgInput` reflects the original integration; you do not need an
+Azgaar map or database to use it.
+
+| Field | Type | Contract |
+| --- | --- | --- |
+| `name` | `string` | Required; also used to derive the default seed. |
+| `population` | `number` | Required; selects the planner and drives the building budget. |
+| `port` | `boolean` | Required; requests harbour/jetty infrastructure. Does not supply water. |
+| `citadel` | `boolean` | Required; requests a city citadel. |
+| `walls` | `boolean` | Required; requests fortifications. Village and city wall planners differ. |
+| `plaza` | `boolean` | Required; city plaza request. Villages have their own green planner. |
+| `temple` | `boolean` | Required; requests religious features, interpreted by each planner. |
+| `shanty` | `boolean` | Required; city shanty request. |
+| `capital` | `boolean` | Required; city capital/administrative request. |
+| `biome` | `string` | Optional; terrain and artwork selection, or a named biome from the supplied skin. |
+| `roadBearings` | `RoadBearingInput[]` | Optional; actual external approaches. See [roads](#roads). |
+| `oceanBearing` | `number` | Optional compass bearing for a generated coast when explicit water does not take precedence. |
+| `harbourSize` | `'large'` or `'small'` | Optional city harbour scale, used with `port: true`. |
+| `urbanDensity` | `number` | Optional positive occupancy input; alters the population/building budget. |
+| `coreCapacity` | `number` | Optional city core-population input; default 10,000. It is a planning input, not a certified housed population. |
+| `coastlineGeometry` | `{x, y}[][]` | Optional filled water polygons; **village metres or city mesh units**, never lon/lat. |
+| `rivers` | `{centreline, widthM, meander?}[]` | Optional village river surveys in metres. City generation does not use this field. |
+| `waterContext` | `WaterContextV1` | Optional measured/unknown-unit water mode; supported for villages only. |
+| `trade` | `boolean` | Optional city trade-centre/market request. |
+| `culture`, `elevation`, `temperature` | `string`, `number`, `number` | Accepted optional source metadata. No general culture, elevation or climate simulation is exposed by these fields. |
+
+Set all seven required flags explicitly, including `false` values. Flags are
+requests, not a promise that every output contains the feature. Do not infer
+village support for a city feature merely because the input interface is shared.
+In particular, villages do not use city wards or the city citadel planner.
+
+## Roads
+
+Bearings run clockwise from north: 0 north, 90 east, 180 south, 270 west.
+Each approach can be a number or a record:
+
+```ts
+import type { RoadBearingInput } from 'settlemaker';
+
+const roads: RoadBearingInput[] = [
+  { bearing_deg: 36, kind: 'royal', route_id: 'r17', through: true },
+  { bearing_deg: 209, kind: 'royal', route_id: 'r17', through: true },
+  { bearing_deg: 117, kind: 'town', route_id: 'r23', relief: 'valley' },
+  { bearing_deg: 281, kind: 'footpath', route_id: 'p4', group: 'trails' },
+];
+```
+
+Land classes are `royal`, `main`, `market`, `town`, `local`, `trail`, `footpath`.
+Legacy `road`, `foot`, `sea`, and group aliases `roads`, `trails` are also
+accepted. Bare bearings use the default main-road meaning in villages. Cities
+map rich classes to their legacy road/foot/sea categories. Sea records do not
+become village land streets.
+
+`through` is a continuation/growth hint; it **never invents another approach**.
+Supply both independently measured sides of a continuing road, with the same
+`route_id`. `group`, `relief` (`flat`, `valley`, `descent`, `ascent`, `ridge`) and
+`followsRiver` provide city growth hints. `followsRiver` does not generate water.
+
+`roadBearings: []` explicitly says there are no external approaches. Omitting the
+field also leaves villages without external approaches, but allows the city's
+legacy random-gate fallback. Shared village streets may carry several route IDs;
+input record count is not a promised street count. Road classes can change inside
+a village while approach provenance remains available in GeoJSON.
+
+## Water
+
+`coastlineGeometry` describes filled water areas, including rivers and lakes,
+using simple rings with at least three distinct points. Closure is implicit;
+repeating the first point is also accepted. Input rings are combined as filled
+water rather than interpreted as outer/hole pairs. Send banks, not a shoreline
+polyline. Use burg-local x-east/y-south coordinates with the correct engine's units.
+
+A nonempty polygon array takes precedence over the legacy `oceanBearing` coast.
+Without `waterContext`, an empty array does not declare a measured dry survey.
+Village `rivers` add channel polygons from at least two centreline points and a
+positive `widthM`. Generated meanders are on by default; `meander: false` preserves
+the surveyed centreline. Do not send the same river in both input fields.
+
+For physical distance/coverage guarantees, use [water context v1](water-context-v1.md).
+An empty measured survey suppresses a legacy coast; `unknown-units` reports missing
+scale rather than inventing a survey. A city call with `waterContext` throws
+`WaterContextError`, including a direct `generateFromBurg` call. City polygon units
+must not be guessed from the village metre convention.
+
+## Generation options
+
+| Option | Used by | Meaning |
+| --- | --- | --- |
+| `seed` | Both | Explicit numeric seed; otherwise derived from the settlement name. |
+| `skin` | Both | A validated handle from `createSkin`; selects artwork/materials and custom biome inheritance. |
+| `village.pxPerMetre` | Village | SVG display scale; default 4. Model and GeoJSON stay in metres. |
+| `village.theme` | Village | A complete `VillageTheme`; use `villageThemeFor` to start from a preset. |
+| `svg.palette` | City | A `PALETTES` entry. |
+| `svg.theme` | City | Partial `RenderTheme` overrides. |
+| `svg.assetSet` | City | Explicit low-level artwork set; overrides skin artwork. |
+| `svg.symbols` | City | Defaults true; false hides placed symbols/marks and exposes building polygons. Vegetation remains. |
+| `svg.padding` | City | Bounds padding in local units; default 20. |
+| `svg.clipId` | City | Frame clipping ID. Does not namespace all other SVG IDs. |
+| `svg.skin`, `svg.skinBiome` | City | Lower-level skin selection; prefer the top-level `skin` for shared generation. |
+| `geojson.generatedAt` | City | Override the output timestamp. |
+| `geojson.padding` | City | Bounds padding; match `svg.padding` if you change it. |
+| `geojson.settlemakerVersion` | City | Metadata override for specialised consumers; normally leave it alone. |
+
+Options are grouped by renderer, but the TypeScript signature does **not** infer
+an engine from the numeric population. City options are ignored on the village
+branch and village options on the city branch. `svg.shift` is a low-level
+rendering option; `generateFromBurg` calculates and supplies its own coastal
+shift, so callers should use the returned `originShift` for subsequent renders.
+
+Available city palette keys are `default`, `classic`, `parchment`, `blueprint`,
+`bw`, `ink`, `night`, `ancient`, `colour`, `simple`. Palette controls affect the
+city renderer's exposed styling; native artwork also carries material tokens.
+Use a skin when you need control across both planners and the full artwork set.
+
+The five named village themes are `temperate`, `desert`, `tundra`, `tropical`,
+`coastal`. Changing `village.theme` changes appearance without selecting a new
+building deck. Changing the input biome can change layout. Skin bases also accept
+`steppe`; it is not a sixth standalone village theme or downloadable collection.
+
+## Results and diagnostics
+
+`svg`, `geojson`, `model`, `degradedFlags` and `originShift` are present on both
+high-level branches. Narrow `result.kind` before using planner-specific model fields.
+`waterContextResult` is optional and belongs to the measured village-water path.
+
+City `degradedFlags` reports dropped `walls`/`citadel` requests. Villages return
+`[]`; that is not a guarantee that every supplied city-oriented flag was honoured.
+City `metadata.building_capacity` reports the ordinary-building target, placement
+and any shortfall. Village `metadata.diagnostics` reports its own planner diagnostics.
+See [GeoJSON](geojson.md) before treating building counts as population accounting.
+
+Fatal measured-water errors throw `WaterContextError`, whose
+`waterContextResult` contains the issue code and any required survey radius.
+Other generation errors should also be surfaced by your application rather than
+replaced with a successful-looking empty map.
+
+## Reproducibility and versioning
+
+Keep the full input, resolved seed, package version, options and skin definition.
+Seeded geometry and SVG output are deterministic within that configuration and
+version. GeoJSON's `generated_at` timestamp is deliberately time-dependent.
+Feature IDs are deterministic within a build, not permanent IDs across upgrades.
+The city's generation hash and the village's literal `'village'` metadata value
+are not substitutes for recording the package version and skin configuration.
+
+## Lower-level entry points
+
+- `mapToGenerationParams`, `Model`, `buildScene`, `assembleSvg`, `generateSvg`,
+  `generateGeoJson`: [city scene and rendering](scene-schema.md).
+- `generateVillage`, `renderVillage`, `generateVillageGeoJson`: village stages.
+- `createSkin`, `skinBiomeFor`, `SKIN_SLOTS`, `SKIN_TOKENS`: [skin authoring](skins.md).
+- `encodeBurgParam`, `decodeBurgParam`, `encodeJsonParam`, `decodeJsonParam`,
+  `parseSettlementUrl`: [URL integration](url-api.md).
+- `parseSvgViewBox`, `declaredMetersPerUnit`, `computeTileInfo`, `cropSvgToTile`,
+  `enumerateTiles`, `totalTileCount`: [tiling](geojson.md#tiling).

package/docs/artwork-integration.md

@@ -0,0 +1,104 @@
+# Integrated settlement artwork
+
+In 3.0.x, `generateSettlement` uses the reviewed city, village, landscape and shared
+infrastructure libraries by default. The village/city population routing remains
+unchanged. No feature flag or asset download is required.
+
+See the [current gallery](gallery.md) for output from both planners, the
+[collection catalogue](current-symbol-library.md) for source drawings, and the
+[skin guide](skins.md) for replacing their appearance in your own setting. This
+page describes placement behaviour; it is not a requirement to edit generator
+code when creating a skin.
+
+## Runtime contract
+
+- Villages retain their dwelling decks, detached forms, landmark sites and
+  per-building identities. Updated rural SVGs replace the old bodies under the
+  same IDs. Placement, collision and exported building bounds use freshly
+  measured roof and porch extents rather than generic house/hut ratios.
+- Cities fit native urban buildings to existing surveyed lots. The fitter uses
+  guarded ink measurements and preserves the building polygon/GeoJSON identity.
+  Central housing has one seeded row-house family, with five restrained biome roof
+  tones. Demand favours the centre; outer roofs sit in progressively larger gardens
+  and mix detached rural houses with urban forms. Parks scale with neighbourhood
+  count. Gardens are also exported as `layer: green`, `kind: garden` polygons. Actual POI assignments select
+  inns, shops, workshops, bathhouses, guildhalls and warehouses. The principal
+  religious form varies independently of biome. Castle keeps/barracks and capital
+  administrative halls/wings use the dedicated kits. Court-bearing forms scale
+  uniformly and their holes stay transparent. Unsuitable lots retain their real
+  polygon, coloured to match the city's roof palette.
+- Multi-building terrace and complete compound presets are available in the
+  artwork registry/catalogue but are not substituted for individual household
+  lots. Compound planning must retain constituent identities and real capacities;
+  this integration does not invent households to fill an aggregate illustration.
+- Vegetation uses native seeded variants, with separate metre footprints for
+  trees, shrubs and low plants. Tundra defaults to low vegetation, including snow
+  variants; treeline trees are not scattered across open tundra. Wet-margin
+  options require nearby water. Mangroves and geographically restricted cacti
+  remain explicit library options rather than indiscriminate default scatter.
+  Flora casts no ground shadows, and village clearance accounts for crown size.
+  Broad crown highlights have no internal outlines; conifer tiers share a light
+  outer contour. Seeded stands group dominant species over roughly 48 metres,
+  with local understory and individual saved variants in both engines.
+- Both engines fill their **actual field polygons** with native seamless tiles;
+  no rectangular preset is stretched across a planner's parcel. Texture pitch
+  is independent of parcel dimensions and crop angle lives on the pattern.
+  Cultivated parcels gain headlands and access strips. Desert irrigation uses
+  a local well/cistern and narrow channels. Tropical paddies use muted shallow
+  flooded beds with earth bunds, and are selected only when a river is supplied;
+  coastlines alone do not enable them. Other tropical crops use dry ground.
+  This is not a groundwater-yield or hydraulic simulation. Tundra ground remains
+  natural grazing/lichen/sedge, with no default arable fields or fringe gardens.
+- City walls follow existing arbitrary polylines, with actual gate gaps and
+  native towers. Walled villages enclose measured roof/porch extents with a
+  3.5-metre rear clearance, including intersecting reserved henge clearings.
+  Gates are cut where roads cross that enclosure. Wet wall segments are omitted.
+  Village walls and gates are included in GeoJSON.
+- Greens use biome-specific turf, sand or moss colours, a single soft earth
+  edge and sparse botanical marks. Village shapes and junction outlines keep
+  their surveyed geometry; city gardens and parks use actual parcel boundaries.
+  The 60 standalone variants are in `symbols/greens/`.
+- Bridges use planned river crossings. Village decks follow the existing
+  surveyed centreline and width. City scenes publish additive `layers.bridges`
+  records for bounded wet road runs between two dry banks; roads terminating in
+  open water do not produce a bridge. Ordinary city roads are masked off water.
+  Deck width remains independent of span; very short sections crop the detail.
+- The existing stone-circle POI now selects a biome-native henge form and saved
+  variation, preserving the POI kind and its placement clearances.
+
+Older version-2 scenes remain readable: field `glyph`, wall `material` and
+`layers.bridges` and symbol `materialVariant` are additive optional properties. The original `REFINED_SET`
+and `SCHEMATIC_SET` remain explicit rendering alternatives. The default is
+`SETTLEMENT_SET`. `symbols: false` still exposes real city building polygons.
+
+## Source and regeneration
+
+`src/assets/artwork.ts` is the shared registry. `scripts/build-runtime-art.mjs`
+compiles reviewed source drawings, metadata and measured bounds. Authored village
+and city building SVGs are embedded; procedural flora, fields and henges are
+generated and cached only when requested, using the same pure functions as the
+review galleries. The generated modules have no filesystem, DOM or Node dependency.
+
+```sh
+# Regenerate the landscape and green sources:
+node scripts/build-landscape-symbols.mjs
+node scripts/build-green-symbols.mjs
+
+# Compile reviewed drawings into the runtime:
+npm run build:art
+npm run build
+npm run build:lib
+
+# Public-API outputs: five biomes, large cities, river crossings and paddies:
+npm run review:art
+```
+
+The review writes SVGs, PNGs, GeoJSON, generation counts and a local gallery to
+`output/art-integration/`. It calls the public generator; it does not assemble
+separate demonstration scenes.
+
+The artwork integration tests cover native lookup, scale differences, POI
+coherence, seams/footprints through the existing asset checks, a closing-vertex
+wall gate, village wall exports, bounded river crossings and henge selection.
+Existing population, street, collision, deterministic scene and GeoJSON tests
+remain part of the regression suite.

package/docs/current-symbol-library.md

@@ -1,44 +1,64 @@
 # Current symbol library
 
-The downloadable library contains 852 drawings in six collections:
-
-| Collection | Drawings | Manifest |
-| --- | ---: | --- |
-| Village | 49 | `symbols/village/symbols.json` |
-| City | 170 | `symbols/city/symbols.json` |
-| Infrastructure | 165 | `symbols/infrastructure/symbols.json` |
-| Landscape | 372 | `symbols/landscape/symbols.json` |
-| Greens | 60 | `symbols/greens/symbols.json` |
-| Markers | 36 | `symbols/markers/markers.json` |
-
-Counts exclude structure silhouettes and combined sprites. Every declared drawing
-has a standalone SVG. Markers live directly in their collection directory; the
-other collections use `individual/`. View boxes vary: consumers must preserve
-aspect ratio rather than assume every drawing is a 64-unit square.
-
-The `symbols/batch001` and `symbols/refined` directories and their source extraction
-scripts have been retired. Village authoring now reads independent placement
-metadata from `scripts/art/village-footprints.json`; it no longer needs an older
-sprite collection to build. Village review sheets and their PNGs show only current
-art. Greens have a combined `catalogue.svg` review sheet.
-
-The existing embedded compatibility exports in `src/assets` remain available to
-API consumers and supply shared placement metadata and remaining common map
-primitives. They are not a downloadable collection or a source for the web gallery.
-Current runtime art continues to come from `scripts/build-runtime-art.mjs` and the
-procedural authoring modules. This change does not remove public rendering APIs.
-
-Settlemaker-web builds its catalogue from the six manifests in its pinned checkout.
-Its Vite plugin emits only allowlisted current drawings, silhouettes, sprites,
-manifests, review sheets and licence files; it does not maintain a copied library.
-No legacy comparison plates are published. Library and website licences remain
-separate from the generator's GPL licence.
-
-## Validation
-
-- Generator suite: 1,414 tests passed after retiring source extraction tests and
-  adding current-collection/placement checks.
-- TypeScript build, script typecheck and browser library bundle passed.
-- Marker check: all 36 original types and pin metadata retained; 38 SVG documents
-  parsed, matching standalone/sprite raster output, 144 small-size renders,
-  centred unclipped bounds, working gallery links and byte-checked ZIP contents.
+SettleMaker 3.0.x ships six default artwork collections containing **852 drawings**.
+These are the current authoring and download sources, distinct from the runtime
+slots used by the generator and by portable skins.
+
+| Collection | Drawings | Contents | Manifest |
+| --- | ---: | --- | --- |
+| Village | 49 | Rural dwellings and village forms | [symbols.json](../symbols/village/symbols.json) |
+| City | 170 | Urban buildings, religious forms and landmark kits | [symbols.json](../symbols/city/symbols.json) |
+| Infrastructure | 165 | Walls, gates, bridges, henges and supporting structures | [symbols.json](../symbols/infrastructure/symbols.json) |
+| Landscape | 372 | Flora, field textures and agricultural forms | [symbols.json](../symbols/landscape/symbols.json) |
+| Greens | 60 | Biome-specific green and ground variants | [symbols.json](../symbols/greens/symbols.json) |
+| Markers | 36 | Map markers, separate from automatic settlement placement | [markers.json](../symbols/markers/markers.json) |
+
+Counts exclude structure silhouettes and combined sprites. Every drawing has a
+standalone SVG: markers sit directly in their collection directory; the other
+collections use `individual/`. View boxes vary; preserve their aspect ratios.
+A drawing's presence in a download does not promise the engine automatically
+places it or that a portable skin can add a new placement category.
+
+## Runtime slots and portable skins
+
+The public `SKIN_SLOTS` catalogue contains **693 supported runtime slots**,
+including compatibility IDs. It provides each slot's view box, anchor, footprint,
+rotation, z-band and minimum scale. Use it as the exact contract when replacing
+engine artwork. For example, some native field slots use 32-unit art boxes even
+when other authoring assets have larger coordinate systems.
+
+```js
+import { SKIN_SLOTS, SKIN_TOKENS } from 'settlemaker';
+console.log(Object.keys(SKIN_SLOTS).length);
+console.log(SKIN_SLOTS['sm-house']);
+console.log(SKIN_TOKENS);
+```
+
+The current city default is `SETTLEMENT_SET`. Some older exports in `src/assets`
+remain for compatibility and shared placement metadata; they are not additional
+download collections. The retired `symbols/batch001` and `symbols/refined`
+directories are not required for skin authoring or current source generation.
+
+[Skin authoring](skins.md) explains inert SVG fragments, tokens, silhouettes,
+partial coverage and inherited biomes. [Artwork integration](artwork-integration.md)
+explains how existing planners select and fit the drawings. The [gallery](gallery.md)
+shows actual public-API output rather than assembled catalogue illustrations.
+
+## Copperline
+
+[Copperline](../symbols/copperline/README.md) is a separate, complete example skin.
+It maps 47 original drawings and shared variants across all 693 runtime slots,
+with industrial, steampunk and modern presets. It is not included in the 852
+count for the six default collections.
+
+## Source and licensing
+
+Collection authoring lives under `scripts/art/` and the `build-*-symbols.mjs`
+scripts. `scripts/build-runtime-art.mjs` compiles the current reviewed assets and
+placement measurements into browser-safe source modules. See
+[regeneration](artwork-integration.md#source-and-regeneration).
+
+The six default collections use [CC BY 4.0 with a rendered-output exception](../symbols/LICENSE),
+with attribution in [CREDITS](../symbols/CREDITS). Copperline uses the repository's
+[GPL-3.0-only license](../LICENSE). The engine's code license and the default
+artwork license are separate; `NOTICE` records the scopes and provenance.

package/docs/development.md

@@ -0,0 +1,102 @@
+# Development and documentation
+
+Use a source checkout for development and review commands. The npm tarball contains
+compiled modules, source maps, TypeScript source, build inputs, public docs and
+artwork, but is not a complete clone of the development repository.
+
+## Build
+
+```sh
+git clone https://github.com/barrulus/settlemaker.git
+cd settlemaker
+npm ci
+npm run build
+npm run build:lib
+```
+
+The 3.0.x release checks use Node 24. A Nix flake is available with `nix develop`
+if you prefer that environment; it is optional. No unlisted `tsx` command or
+root-level smoke-test file is required.
+
+`build` emits ESM JavaScript, declarations and source maps under `dist`.
+`build:lib` creates the standalone ESM browser bundle. `npm pack` runs `prepack`,
+which removes `dist` before rebuilding both formats so stale files cannot ship.
+`npm run build` alone does not clean an existing output directory.
+
+## Checks
+
+```sh
+npm run build
+npm run typecheck:scripts
+npm test -- --maxWorkers=2 --pool=threads
+npm run docs:check
+```
+
+The thread-pool invocation passed the full release suite without the worker RPC
+reporting timeout encountered in earlier runs with process workers. No assertions
+are disabled by these options. Use focused test files while iterating, then the
+appropriate release checks before publishing.
+
+For artwork or geometry changes, use the public-API review tools:
+
+```sh
+npm run review:art
+npm run review:roads
+npm run review:cities
+```
+
+They write local galleries and measurements under ignored `output/` directories.
+The public [artwork integration guide](artwork-integration.md) documents source
+regeneration when SVG authoring changes. Review images as well as measurements.
+
+## Documentation checks
+
+```sh
+npm run docs:images
+npm run docs:check
+```
+
+`docs:images` builds the library and runs `scripts/generate-examples.mjs`. It
+regenerates PNGs and SVGs together, the exact fixture manifest and `docs/gallery.md`.
+All maps use `generateSettlement`; the displayed engine is checked against the
+population. The same script supplies both the README images and the full gallery.
+PNG previews resolve the renderer-provided CSS-variable fallbacks for librsvg.
+Do not hand-replace gallery images with illustrations that bypass the engine.
+
+`docs:check` checks current documentation links and anchors, release-pinned README
+image paths, the fixture version and public API examples. It executes the README
+quick start and skin example and typechecks the standalone TypeScript examples.
+It also exercises the current URL/rendering examples and validates their outputs.
+Historical plans and release notes are not treated as current API guidance.
+
+Review the gallery at readable size, including the full SVGs. Version-pinned
+absolute README image/documentation links work from npm as well as GitHub; update
+their release tag when publishing the next documentation revision. They should
+point to committed artifacts belonging to that version.
+
+## Package verification
+
+```sh
+npm pack --pack-destination /tmp
+```
+
+Inspect the tarball's file list, then install that exact file in a fresh temporary
+project with production dependencies only. Exercise Node ESM import, CommonJS
+dynamic import, browser bundle import and strict NodeNext TypeScript compilation.
+Generate both a village and a city, with and without a skin. Verify that source
+maps resolve to packaged TypeScript source and that artwork LICENSE/CREDITS ship.
+
+## Release workflow
+
+1. Update `package.json`, lockfile and `SETTLEMAKER_VERSION` together; update the
+   metadata assertions and release notes.
+2. Regenerate documentation if the version or output changes, and run the checks.
+3. Pack and verify the artifact in an isolated consumer.
+4. Commit through a PR to protected `master`; tag the merged source.
+5. Publish the verified tarball, completing npm's authentication when prompted.
+6. Verify registry version, `latest` tag, integrity and a clean registry install;
+   publish the matching GitHub release notes.
+
+An npm version is immutable; README changes on npm require a new package version.
+A website consuming this repository or package must update its own pin/dependency
+and deploy separately. An npm release does not deploy `settlemaker.com`.