@tileflow/maps 0.1.0-alpha.16 → 0.1.0-alpha.17

package/README.md

@@ -65,7 +65,7 @@ The CLI owns the interface; compiler and runtime changes require rebuilding thos
 - `baedeker`: warm travel-atlas styling, serif labels, original engraved patterns, and contours.
 - `civica`: illustrated civic-print styling with warm paper, olive parks, blue annotations, and
   vermilion landmarks.
-- [`map1777` (1777)](docs/map-1777.md): 1777 ink and watercolor on current data, with 3D and four times of day.
+- `map1777` (1777): 1777 ink and watercolor on current data, with 3D and four times of day.
 - `siegfried`: a terrain atlas with coordinated light/dark ink palettes, contours, and engraved patterns.
 - `soundings`: bathymetric reference cartography with depth bands, continuous relief, and port context.
 - `blueprint`: a dark architectural drawing style, with a default camera centered on San Francisco.
@@ -76,31 +76,30 @@ to create an application-owned map.
 
 ### Streets appearance
 
-Streets follows the visual direction of [Mapbox Standard](https://docs.mapbox.com/playground/standard-style/)
-(twelve theme/time combinations), calibrated on 2026-10-18. Inspector offers **Default**, **Faded**, and
-**Monochrome** in its Theme control, independently of the Time of day control's `day`, `dawn`,
-`dusk`, and `night` presets. Each of the twelve combinations selects a complete theme, including
-its map colors and artwork. Default retains the configuration key `light` for compatibility:
-`theme="light" timeOfDay="night"` selects `dark`, while `theme="light" timeOfDay="day"`
-selects `light`. The other concrete themes are `dawn`, `dusk`, `faded`, `monochrome`,
-`dawn-faded`, `dawn-monochrome`, `dusk-faded`, `dusk-monochrome`, `dark-faded`, and
-`dark-monochrome`. Dawn and day use light artwork; dusk and night use dark artwork. Time presets
-adjust authored map colors; selecting one does not apply a global lighting tint to the flat map.
-Ground, water, vegetation, roads, zoning, labels and halos use independently evaluated colors
-from Standard's 2026-10-08 style, including each material's theme LUT, lighting, emission and
-transparency. Ground colors are checked against sRGB framebuffer samples from Mapbox GL JS
-3.28.1 across all twelve combinations; footprints and 3D roofs use separate GPU measurements.
-Water retains its own material and zoom 5–7 / 13–14 transitions; it no longer inherits a
-swimming pool's color offset. Background emission changes between zoom 13 and 14. These values
-are baked into theme tokens, so they add no lighting or LUT work per frame.
-Scene-sun lighting preserves unshadowed roof paint while allowing light color to affect walls.
-The underlying tile data and rendering pipeline differ, so these are close palette matches rather
-than a pixel-identical copy. Streets' own semantic design retains slate-blue
-roads, uppercase road names, warm building footprints, green parks, and compact category-colored
-POI discs. Dark mode uses pale discs with dark pictograms. Pictograms adapted from Maki follow
-World's transport mode and POI type: metro, rail, tram, bus, ferry, cable-car, and airport stations
-are distinct, as are bars, cafés, museums, galleries, car dealers, and places of worship by
-religion.
+Streets has twelve theme/time combinations. Inspector offers **Default**, **Faded**, and
+**Monochrome** independently of the Time of day control's `day`, `dawn`, `dusk`, and `night`
+presets. Default retains the configuration key `light`: `theme="light" timeOfDay="night"`
+selects `dark`, while `theme="light" timeOfDay="day"` selects `light`. The other concrete themes
+are `dawn`, `dusk`, `faded`, `monochrome`, `dawn-faded`, `dawn-monochrome`, `dusk-faded`,
+`dusk-monochrome`, `dark-faded`, and `dark-monochrome`. Each combination selects a complete
+palette and artwork; time presets do not apply a global lighting tint to the flat map.
+
+Scene lighting is calibrated against Mapbox Standard. Streets owns its cartography: slate-blue
+roads with stronger regional outlines, neutral urban surfaces, pale warm rural ground, green
+parks and subtle cream buildings. Its palette is not a fixed copy of the provider's reference
+colors. Day uses category-colored POI discs; dark mode uses pale discs with dark pictograms.
+Maki pictograms distinguish transport modes and POI types. Scene-sun lighting preserves
+unshadowed roof paint while allowing light color to affect walls.
+
+At regional scales, the default day theme uses a packaged, attributed climate underlay to
+separate humid and dry regions. It fades out by zoom 11, where mapped land cover and land use
+supply local detail. Climate is broad context, not a claim of surveyed vegetation at a specific
+site. The other themes retain their own authored land-cover palettes. Urban and education
+areas use neutral surfaces; farmland stays pale, while mapped orchards and nurseries remain
+green. Underground footprints flagged `hide_3d` are omitted from the flat building layers. Streets
+suspends duplicate flat building footprints in 3D so roads remain visible under open landmarks;
+2D mode restores ordinary footprints. Normal 3D buildings keep a small neutral/active tone difference. Authored models use
+the neutral building color and independently configurable window shading.
 
 Streets packages DINish Medium for roads, house numbers and POIs, and Bold for shields, approximating
 the reference's DIN Pro lettering. Other roles retain Noto Sans Regular, Bold and Italic. All
@@ -110,26 +109,25 @@ Maki's 15px artwork is composed into a centered 12px box, leaving room inside th
 interior. Their 1x and 2x atlases rasterize these SVG compositions separately; the map displays
 each complete icon at native scale instead of rescaling the bitmap as the zoom changes.
 
-The light surface palette is compared with lossless captures of Standard with 3D buildings and
-trees disabled. Parks use a stronger green with lighter lawns and meadows drawn above them;
-flat buildings use a neutral cream. Day keeps regional connections clear through z10, softens avenues at z12–14 and retains a
-readable local grid. Colors and widths recover their original detail at z15. Widths interpolate
-exponentially (base 1.5), including fractional zooms. Motorways and trunks start at z3, primary roads at z6, secondary and tertiary
-roads at z8, streets and links at z12, and service roads at z15. Surface casings begin at z15
-(z16 for service roads and tracks), growing independently of the carriageway gap.
-Major overview strokes include bridges and tunnels until structural layers take over at z13.
-Local structures join streets at z12. Links retain narrower widths and draw before receiving roads.
-Surface and bridge casings are continuous; tunnel casings are dashed. Construction carriageway
-fills and marks draw below roads in service, including motorway ramps.
-Borders use Standard's 2026-10-08 style, theme LUTs and unshadowed ground lighting, without
-carriageway emissive lift. HD-road borders match across classes, bridges, tunnels and roundabouts
-from z15; lower-zoom tunnels retain class colors. Paths keep separate emission. Streets uses the reference border colors without an additional darkening multiplier. These baked
-2D colors exclude fog and Standard's full lighting pipeline.
-Surface caps round at z14; tunnels retain butt caps and bridges use round fills.
-Crosswalks and compact blue-gray arrows with filled triangular heads fade in from z16.5.
-Day overview colors, from motorway/trunk to primary, secondary, tertiary and local:
-`#AAB9C9`, `#D5DBDF`, `#DEE3E6`, `#E3E7E9`, `#DDE2E5`. Unpaved roads follow the same city hierarchy. From z15: `#AAB9C9`
-for motorway/trunk/primary; `#BDCCD9` for secondary/local.
+The day road network keeps major routes distinct at regional and city scales. Motorways and
+trunks gain a darker outline from z6 through z14, blending into the detailed treatment at z15.
+Regional connector widths remain readable between towns; their city casing palette holds through z14.
+Primary, secondary, tertiary and local roads widen slightly at intermediate zooms and converge
+with their detailed profiles at z15. Local streets become readable when their geometry arrives
+at z12. Casing passes sit below all receiving road fills, preventing exposed round segment caps
+at junctions. Links remain narrower and draw before receiving roads. Tunnel casings are dashed;
+surface and bridge casings are continuous. Construction fills and marks draw below roads in
+service. Crosswalks and compact blue-gray arrows fade in from z16.5.
+
+Daytime surface footpaths and cycleways use white strokes over mapped green ground and a
+muted gray-earth stroke elsewhere, at 92% of their authored width and without a casing.
+The shared `roads.pathGround` compiler and browser protocol clip the green portions from the
+same vector tiles; a complete ground-colored path remains visible if context cannot load.
+Road carriageway outlines draw above these paths. This treatment belongs to the Streets
+definition and survives normal artifact regeneration; other themes retain their own path styles.
+Road palettes, width profiles, building outlines and the overview backgrounds are authored here
+in Maps; consumers inherit them without installing a separately edited style snapshot.
+
 From z13, pedestrian plazas use an opaque pale surface above commercial zoning and below
 explicit grass, gardens and parks. The `roads.pedestrian.surface` token follows the ground's
 theme and time of day. From z17, mapped sidewalks add a translucent tint and dot pattern through
@@ -156,12 +154,12 @@ and draw above flat footprints but below 3D buildings, with viewport-aligned let
 southeast at dawn, southwest at dusk and western moonlight at night. Monochrome has distinct
 directions and strengths. Tileflow holds zoom 14+ values; Standard varies intensity below z14.
 Shading differs; `controller.setSun({date, location})` uses the real sun instead of presets.
-Landmark material profiles and subtle dusk/night illumination are covered in
-[3D buildings](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/buildings-3d.md).
+Streets enables `camera.adaptivePerspective`. See camera, landmark and lighting settings in
+[3D buildings](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/README.md).
 The buildings' `threeDimensional.lighting` and `shadows` options control the effect, and each
 theme's `lighting.sun.shadowIntensity` and `lighting.ambient` control its strength.
 Street lights are opt-in: set `roads.streetLights.enabled: true`.
-Core rounds corners and shades facades; Streets uses `groundOcclusion: 0.12` for ground contact.
+Streets uses `groundOcclusion: 0.07` and `groundOcclusionRadius: 1.5` for subtle ground contact.
 `buildings.threeDimensional.occlusion: false` disables contact and model occlusion.
 `buildings.contactShadow` styles the flat fallback.
 Streets selects Core's `labels.roadPlacement: 'ground'`: street names follow the road plane below
@@ -170,9 +168,9 @@ Road names retain class zoom/size curves, favor major roads and add padding thro
 Pedestrian paths group separately. Compact types preserve language;
 `labels.roadNameFormat: 'full'` keeps source names.
 Disabling roads omits their names.
-Road rings, ramp and surface ordering use [Core's replaceable defaults](../core/docs/cartographic-defaults.md).
+Road rings, ramp and surface ordering use [Core's replaceable defaults](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/README.md).
 Streets owns colors, widths, typography and time-of-day themes.
-Each theme paints a [street sky](../core/docs/street-sky.md) with night stars; `atmosphere: true`
+Each theme paints a [street sky](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/README.md) with night stars; `atmosphere: true`
 on a globe map adds space around it. Mercator and native targets remain supported.
 
 Streets enables model trees by default (`mode: '3d'`, `fallback: 'none'`). They stay three-dimensional
@@ -189,7 +187,7 @@ changing source heights. All presets style bark and crowns independently.
 The models have 222–386 triangles nearby and 44–78 at distance, using Core's instanced tree
 renderer; flat crowns use the existing sprite atlas. Tree locations and attributes still come
 from the source tiles. The artwork does not add trees to parks whose data has none. See
-[3D trees](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/trees-3d.md) for
+[3D trees](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/README.md) for
 browser rendering and platform support. To remove both representations, extend the map:
 
 <!-- docs:check -->
@@ -207,9 +205,12 @@ export default defineMap({
 ```
 
 POIs follow World ranks and category density, with extra detail for parks and transport.
+Generic airport POIs are limited to rank 0 to reduce misplaced business listings; the dedicated
+aerodrome layer continues to label mapped airports. This display policy does not repair source data.
+Road-reference repetition is reduced at z11–13 and retains its detail interval from z14.
 Gardens stay at ranks 0–1 at every zoom, keeping principal destinations while omitting botanical
 collections and some small independent gardens. Other park and landmark types retain their usual
-eligibility. See [Streets POI selection and placement](docs/design-and-assets.md#streets-pois).
+eligibility.
 
 Cities and districts hand over at z15, smaller settlements at z13. Co-located cities share one
 anchor. Districts use rank gates below z12, then source availability and collisions. Street names use 0.15 em letter spacing and
@@ -221,7 +222,6 @@ The map uses Tileflow data and assets, including packaged DINish and Noto Sans f
 reference uses DIN Pro Medium, so font shapes and stroke weight
 remain an approximation. Available POIs, abbreviated names,
 proprietary landmark models, transit branding, and building detail can differ from the reference.
-See [map design and asset provenance](https://github.com/tileflow/tileflow-sdk/blob/main/packages/maps/docs/design-and-assets.md).
 
 ### Blueprint naming
 
@@ -318,10 +318,7 @@ for inheritance and styling, or the
 [public exports](https://github.com/tileflow/tileflow-sdk/blob/main/packages/maps/src/index.ts)
 for exact names. The installed package's definitions and README take precedence over a newer `main`.
 
-## Design and asset reference
-
-The [design and asset notes](https://github.com/tileflow/tileflow-sdk/blob/main/packages/maps/docs/design-and-assets.md) describe each map's visual grammar, source references, and third-party asset boundaries. They are also included under
-`docs/` in the installed package.
+## Streets themes
 
 Streets offers three time-of-day families: `light` (displayed as Default), `faded`, and `monochrome`, each with
 `day`, `dawn`, `dusk`, and `night`. For example, `theme="faded" timeOfDay="night"` resolves to
@@ -329,3 +326,8 @@ Streets offers three time-of-day families: `light` (displayed as Default), `fade
 concrete theme names remain available for existing applications and captures. This catalog
 is inherited when extending Streets without overriding it.
 See the [time-of-day contract](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/README.md#style-with-themes-and-semantic-modules).
+
+Streets packages its low-zoom climate artwork and attribution, contrasted routes and compact trees.
+Models inherit ordinary-building shading. Glass parts can be recoloured independently through
+`modelColors.glass`; windows use `modelLighting.window.colorScale: 0.94`.
+Other maps can override their colour and material without regenerating the model.

package/THIRD_PARTY_NOTICES.md

@@ -205,3 +205,10 @@ Cívica includes five unmodified upstream font files under `assets/civica/fonts/
 component filenames and source revisions for Tileflow's generic font preparation pipeline.
 `assets/civica/fonts/README.md` records individual pinned source links and verified OpenType full
 names. No font file has been subsetted, renamed internally, or modified.
+
+## Historical climate context
+
+Streets uses a smoothed colour proxy derived from Beck et al. (2023),
+https://doi.org/10.1038/s41597-023-02549-6, under CC BY 4.0.
+Source, attribution and adaptation details: assets/streets/climate/NOTICE.txt.
+The image is historical context, not live vegetation.