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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tileflow/maps",
-  "version": "0.1.0-alpha.16",
+  "version": "0.1.0-alpha.18",
   "license": "Apache-2.0",
   "description": "Official themed Streets, Baedeker, Cívica, 1777, Siegfried, Soundings, and Blueprint maps for Tileflow.",
   "type": "module",
@@ -35,7 +35,6 @@
   "types": "./dist/index.d.ts",
   "files": [
     "assets",
-    "docs",
     "dist",
     "THIRD_PARTY_NOTICES.md",
     "LICENSE"
@@ -52,12 +51,12 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@tileflow/core": ">=0.1.0-alpha.42 <0.1.0-beta.0"
+    "@tileflow/core": ">=0.1.0-alpha.45 <0.1.0-beta.0"
   },
   "devDependencies": {
     "@maplibre/maplibre-gl-style-spec": "24.8.5",
     "@maplibre/maplibre-gl-style-spec-v6": "npm:@maplibre/maplibre-gl-style-spec@26.4.4",
-    "@tileflow/core": "0.1.0-alpha.42"
+    "@tileflow/core": "0.1.0-alpha.45"
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm --dts --clean --no-splitting",

package/docs/design-and-assets.md

@@ -1,247 +0,0 @@
-# Map designs and assets
-
-## Streets POIs
-
-Transport POIs with a recognized `network` use that network's symbol. The initial catalog covers
-`Metro de Madrid`, `Cercanías Madrid`, and `EMT Madrid`. Each network has one packaged SVG in a
-24px cell, shared across all themes without recoloring the identity. Matching uses the source's
-exact network value, including on older World tiles without `mode`; it never guesses from a
-station name or applies a city logo to every station. Unknown or missing networks retain the
-existing mode/type/category pictogram. Other railway services and intercity buses keep their
-generic symbols. Sources and asset licenses are recorded in `THIRD_PARTY_NOTICES.md`.
-
-POIs use World ranks with category density: parks and transport retain more detail than
-businesses, hotels and religious sites. Gardens are limited to World filter ranks 0–1 at every
-zoom, keeping principal destinations while suppressing botanical collections and other minor
-garden POIs. World currently classifies both as `garden`, so some small independent gardens are
-also omitted. Other park and landmark types keep their usual eligibility.
-
-All categories share importance order; the two most important ranks precede streets. Discs need
-names except parking and toilets. Native perspective and collisions select labels. See
-[label placement](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/cartographic-defaults.md#label-density-and-perspective).
-Ordinary POI/transit names use 13 px, major destinations 18 px. World size rank zero alone does
-not enlarge small parks. Text padding falls from 6 px to 4 px between z16 and z17; collision
-determines which names fit.
-
-## civica
-
-`civica` is a self-contained civic print design named “Cívica”. Pale paper, warm stone blocks,
-olive parkland, blue water, and vermilion landmarks give cities the character of an illustrated
-wall map. Broad urban shapes lead at overview scale; solid building masses, cream streets, and
-selected destinations describe the city. Large italic serif park titles and blue uppercase station
-names anchor the district drawing; smaller parks keep a quieter italic size, and condensed captions
-provide supporting detail. Fine paths and sparse landscape textures enter at closer zooms.
-It declares its complete World data selection,
-modules, render stacks, and theme directly,
-owns its patterns and symbols through `[civicaIcons]`, and selects its own packaged DM Serif Text
-Regular and Italic lettering, Barlow Semi Condensed detail labels, and Noto Sans Regular fallback
-through `[civicaFonts]`. Its graphic direction was informed by the
-[Inside the Beltway Washington DC print](https://www.etsy.com/listing/990932175/inside-the-belt-way-washington-dc).
-The map definition and vector artwork are original Tileflow work; no source map, image pixels,
-illustrations, or third-party style are included.
-
-Cívica changes its drawing and label hierarchy with scale:
-
-| Zoom  | Cartographic treatment                                                                                        |
-| ----- | ------------------------------------------------------------------------------------------------------------- |
-| 0–6   | Continental and country lettering over broad land and water shapes.                                           |
-| 7–11  | Regional roads, settlements, and landscape areas; global landcover fades out by z10.                          |
-| 12–14 | District names, broad pedestrian promenades, and generalized footprints from z13; eligible POIs use rank 0–1. |
-| 15–17 | Solid building masses and street names; POIs admit rank 2 from z15 and featured rank 3 from z17.              |
-| 18–19 | Fine paths and their names enter progressively; trees and sparse botanical textures begin at z19.             |
-| 20+   | Address numbers, sidewalks, and quiet industrial texture complete the close street view.                      |
-
-Buildings, park parcels, and water bodies have no outlines. Ordinary surface streets use one cream
-stroke, with broader widths at city and neighborhood scales to separate the printed blocks.
-Motorway, trunk, and bridge casings retain the main transport hierarchy. Pedestrian areas
-and roundabouts omit their extra outline, and tunnel hatches are disabled. Ordinary fine path lines
-are solid: cycleways begin at z17, footways and tracks at z17.5, paths at z18, and steps at z19. The
-corresponding labels wait until z18–20. Water remains a flat color at every zoom, and tree points
-have no stroke.
-
-The red building plate selects civic buildings directly and destination buildings only when
-`importanceTier` is at least 3. Tier-2 destinations use darker gray; lower-ranked destinations and
-ordinary buildings share the same warm-gray fill. It uses World `building_tone`; building height
-never determines landmark color.
-The generalized footprint pass ends at z15 with the same opacity at which the
-detail pass begins.
-
-POI symbols and names form one collision unit. Each category retains its own filter and layer
-(`placement.order: 'categories'`), and destinations listed first are placed first. Candidates
-must carry the schema-bound `poiCategory`, `poiFilterRank`, and `poiSizeRank` fields (`category`,
-`filter_rank`, and `size_rank` in World V1). Size ranks must be 0–16, filter ranks must be
-nonnegative, and the producer's `minZoom` (`min_zoom`) is honored when present. Landmarks, culture,
-parks, transport, and medical destinations can reach rank 3; other categories stop at rank 2.
-Food, retail, visitor amenities, and lodging begin at z17.5. Generic `public_transit_facility`
-POIs also wait until z17.5, while train stations retain their earlier schedule. Culture, education,
-public-service, and medical POIs with filter rank 2 or higher and size rank 16 enter at z17.5;
-rank-1 destinations and other valid size ranks retain their earlier schedule. These rules preserve
-major stations even when their size rank is 16 and leave room for parks and selected institutions
-at district scale. They use source categories and ranks without place-name or location exceptions.
-Park titles use DM Serif Text Italic, with larger type for size ranks 0–4. Transport uses Barlow
-Semi Condensed SemiBold in uppercase; supporting captions use Barlow Semi Condensed Regular.
-Classic OpenMapTiles data without those category and rank fields renders the base map without
-POIs; Cívica does not infer or retrofit those fields. All five font faces are packaged locally:
-DM Serif Text Regular and Italic, Barlow Semi Condensed Regular and SemiBold, and the Noto Sans
-Regular fallback.
-
-## baedeker
-
-`baedeker` is a self-contained travel-atlas and town-plan design with open warm paper, fine coral
-building and residential hatching, paper-negative streets, dominant black railways, horizontally
-engraved cyan water, ring-stippled gardens, and browser-derived Mapterhorn contours. Travel POIs
-are rendered as compact serif labels without modern pictograms; stations and landmarks use the
-semibold face, so each category keeps its own layer and the categories listed first are placed
-first. It declares
-`[baedekerIcons]`, whose eight original Tileflow SVG patterns describe hachures, orchards, paper
-grain, public gardens, residential blocks, sand, water lines, and wetlands, plus
-`[baedekerFonts]`, its own package copy of Cormorant Garamond Regular, SemiBold, and Italic. Its
-visual grammar was informed by the
-[Baedeker / Karl Wagner & Debes collection](https://www.antiquemapsandprints.com/collections/baedeker-karl-wagner-debes)
-and Wikimedia Commons'
-[maps by Karl Baedeker of Italy](https://commons.wikimedia.org/wiki/Category:Maps_by_Karl_Baedeker_of_Italy).
-The package includes no historical scan, raster pixel, historical typeface, legend artwork,
-geospatial data, or source map; the style and patterns are original Tileflow work. The packaged
-Cormorant faces are unmodified upstream font software under the SIL Open Font License 1.1. No
-Mapterhorn terrain tile is packaged or redistributed. Baedeker is an official Tileflow map and is
-not affiliated with or endorsed by Baedeker or Wagner & Debes.
-
-## 1777
-
-`map1777` is a self-contained printed-atlas design. It uses Core's semantic compiler, but
-it does not import or extend the `streets` map and it does not inherit Streets assets. It declares
-only `[map1777Icons]`, which contains eleven original material patterns in four palettes for paper,
-cultivated land, vegetation, settlements, sand, wetlands, and water. Its three Cormorant Garamond
-faces are packaged in `[map1777Fonts]`. Applications can import it directly or
-extend it like any other root.
-
-## soundings
-
-`soundings` is a self-contained bathymetric-chart design with ivory land, thirteen-stop
-depth-graded water, labelled band edges, continuous colour relief, multidirectional seabed shading,
-port context, named ferry routes, and restrained technical magenta. Its initial camera faces the
-Strait of Gibraltar, allowing an Iberian GEBCO pilot to exercise both Atlantic and Mediterranean
-relief. It selects the public semantic compiler contract without importing or extending `streets`
-and explicitly composes World with `bathymetry({display: 'hybrid'})` and the `nautical-v1`
-navigation marks.
-
-Vector bands come from `tileflow-bathymetry`; continuous colour relief and hillshade come from
-`tileflow-bathymetry-dem`. The DEM treatment is balanced against the vector wash, depth labels, and
-the navigation marks. Dashed outlines remain an honest
-fallback traced from broad GEBCO band polygons until native contour geometry is released. Labels
-show the absolute `min_depth` value, not an inferred range or vessel-specific safety contour.
-Ferries are ordinary World context. Navigation marks come from `tileflow-nautical`: the theme's
-`nautical.*` image tokens select the Soundings chart symbols for buoys (port can, starboard cone,
-cardinal double cone, and a pillar for other buoys), lights, lighthouses, wrecks, harbours, marinas,
-ports, inland notice boards by function, distance marks, and small-craft facilities. Buoys, light
-flares, and notice boards take each mark's own colour from the data; beacons stay small coloured
-dots, rocks are chart crosses and stars, and the other symbols are printed in the chart ink. Light
-flares flash in their rhythm in browser maps. Bridges and berths are drawn as ink structures with
-their clearances, and marinas and harbours as light outlines. Technical magenta remains reserved for
-operational overlays: restricted, military, anchorage, and traffic-separation areas,
-traffic-separation lines, and submarine and overhead cables. Coverage is
-a faint tint before marks appear. The map shows a "Not for navigation" notice wherever it is
-displayed. Soundings is reference cartography and is not a navigation product.
-
-## siegfried
-
-`siegfried` is a self-contained terrain atlas based on the visual grammar documented for
-swisstopo's nineteenth-century Siegfried Map. It does not import or extend `streets`. The default
-`light` theme preserves black, brown, blue, and an ivory paper substrate; browser-derived contours
-replace modern hillshade and retain the 30-metre Alpine cadence at detailed zooms. Rock and scree
-are re-engraved in key ink after the contour deck, while dedicated SVG motifs distinguish forest,
-glacier, wetland, gravel, orchard, and water. Its coordinated `dark` theme is explicitly a nocturnal
-engraver's proof, not a historical facsimile: it keeps identical geometry and semantic ink roles on
-charcoal paper. `[siegfriedIcons]` owns nine light and nine dark pattern variants,
-`[siegfriedFonts]` owns the locally packaged Cormorant Garamond Regular, SemiBold, and Italic faces,
-and `[siegfriedThemes]` exposes the two complete visual vocabularies for safe derivation.
-
-## blueprint
-
-`blueprint` is a self-contained dark architectural-blueprint design centered on San Francisco.
-Fine technical road strokes, survey-like uppercase labels, precise building footprints, contour
-dimensions, and dedicated landscape and water hatches replace naturalistic map color. It declares
-the canonical Noto Sans glyph provider and only `[blueprintIcons]`, whose four original patterns
-and schematic POI node form its complete sprite vocabulary. Medical and transport callouts start
-before the other POI labels, so each category keeps its own layer, placed in the listed order.
-Prominent building height callouts use World `render_height`; the map does not require unpublished
-building names or raw heights.
-
-## Shared themes and asset preparation
-
-`streetsThemes.light` and `streetsThemes.dark` are complete appearance documents consumed by the
-same semantic module structure. Selecting `dark` changes colors, typography roles, image roles, and
-lighting without changing a source, filter, layer order, zoom gate, collision rule, or module. Both
-sidewalk patterns live in the shared `[streetsIcons]` atlas and the selected theme resolves the
-semantic `roads.sidewalkPattern` image token to the correct asset.
-
-Streets places every POI category in World's importance order, with one density for the whole
-module: `filter_rank` and then `size_rank` decide which destinations win, so a metro station is not
-displaced by a nearby cash machine because of its category, and no category waits for a later
-zoom. Its labels give street and place names priority over everyday destinations; World's two most
-important ranks (`prominentRank: 1`) are placed before them, so landmarks such as Palais du Louvre,
-Plaza Mayor, or Battery Park remain at z14. Each destination is one collision unit made from a
-colored disc and its name in the category color: both must fit. Parking and public toilets are
-self-explanatory and appear as a disc alone; other unnamed POIs are omitted. Three-pixel icon and
-text padding keeps nearby names available without disabling collision. Portal-number labels are
-disabled.
-
-Pictograms follow World's transport `mode` first, then its POI `type`, then the category. World's
-own `icon` field is coarser (one `shop` for every store, one `transport` for metro, bus, and cable
-car), so Streets reads the type. `src/official/streets-poi.ts` owns the type and mode tables, the
-85 pictograms, and their disc palette; `scripts/generate-streets-poi-icons.ts` writes each light
-disc and its `-dark` variant, a pale disc with a dark pictogram. Themes bind each type's pictogram
-through a `poi.pictogram.<id>` image token and each category's default pictogram through Core's
-`poi.<category>` image role, so a theme that replaces a category role replaces that category's
-default pictogram. The pictograms keep the CC0 Maki provenance documented in
-`THIRD_PARTY_NOTICES.md`.
-
-Regional hillshade uses the public Mapterhorn TileJSON endpoint with Terrarium encoding, from
-z5 to before z14. Day and night use separate highlight, accent, and shadow tokens. The DEM is a
-remote runtime dependency with its own attribution, and `terrain: 'none'` removes it. The layer
-adds shaded relief without displacing geometry. Flat building footprints, runtime-toggle
-extrusions, and the existing vegetation renderer remain separate from the hillshade.
-
-Road references use a compact Tileflow-owned family of generic rectangular and circular shields.
-The data's normalized `shield_kind` selects neutral, blue, green, red, orange, yellow, or circular
-artwork; `shield_text_color` independently selects the light or dark theme token. Unknown and
-unsupported networks fall back to the neutral rectangle with dark text instead of guessing a
-country from the spelling of `ref`. Both themes retain the same signaling colors.
-
-Streets has separate shield phases for scale, not separate hand-authored network layers. Overview
-uses pre-deduplicated point candidates; detail switches to repeated line placement. Both the fitted
-plate and its complete route reference are viewport-aligned, so shields remain horizontal as the
-map rotates or pitches. The rectangular base plate is 20 by 14 pixels with a one-pixel outline;
-the circular neutral base is 14 by 14. Both use 9-pixel bold text and a small width-only fit
-allowance. Streets limits shields to the motorway-through-tertiary hierarchy; collision padding
-and the overview candidate schedule keep regional views legible while preserving useful repetition
-at street scale.
-
-The two palettes are Tileflow-owned, deterministic snapshots calibrated from rendered Mapbox
-Standard `default/day` and `default/night` references on 2026-10-14. The [Standard playground](https://docs.mapbox.com/playground/standard-style/) is the visual
-reference; the map does not import its style JSON, assets, or runtime dependencies. Public roles such as `surface.background`,
-`landuse.industrial`, `landuse.medical`, `labels.settlement`, `labels.neighborhood`, and
-`labels.road` remain independently wired; `hydro.ocean` also separates Standard Night's deep sea
-from urban and inland water. An agent can alter one cartographic intent without
-knowing or perturbing the physical layer topology. Because Standard is evergreen, later parity work
-must be an explicit dated recalibration rather than an implicit network-dependent change.
-
-At detailed zooms, the road-bearing official maps round-cap ordinary surface-road and bridge
-feature endpoints so adjacent vector segments overlap their antialiasing fringe instead of exposing
-hairline cuts. Tunnel portals retain butt caps; Streets also keeps butt caps on
-steps and controlled surface approaches so those structural ends do not protrude into connected
-geometry. Streets pairs its blue/slate road decks with a darker casing that grows from
-1 px at z15 to 2 px at z22; tunnel casings use the compact dashed rhythm of the calibrated reference.
-
-A theme is not a loose override cascade. Module styles explicitly reference roles such as
-`roads.motorway`, `labels.road`, and `hydro.water`; the selected complete theme resolves those
-references before MapLibre output is generated. Use `defaultTheme` for a deterministic default and
-`systemThemes` plus the runtime `theme="system"` selection when the browser should follow the OS.
-
-The directory descriptors point into this installed package. A map inherits its parent's icon or
-font list when the property is omitted. Declaring a list replaces the inherited list, a later
-directory wins for an exact duplicate ID, and `[]` selects no directories.
-
-`@tileflow/maps` has a peer dependency on `@tileflow/core`. Core owns the map language and compiler;
-this package owns the official map definitions, icon and pattern sources, Baedeker, Cívica,
-and Siegfried fonts, and their notices. Core never depends on this package.

package/docs/map-1777.md

@@ -1,91 +0,0 @@
-# 1777
-
-`map1777` adapts the ink and watercolor vocabulary of the 1777 cabinet atlas to current
-Tileflow World data. Pale cream paper, vermilion buildings, green landscape washes, fine
-agricultural strokes and serif lettering carry the style. 1777 describes the visual reference,
-not historical coverage.
-
-The reference is the large-scale manuscript cabinet atlas held by KBR. The visual study
-compared Namur, Uccle/Sonian Forest, Dilbeek, Mon Plaisir, Park Abbey and Sart-Bernard:
-urban blocks, estate gardens, open farmland and woodland need different marks.
-
-Mapped fields use three wash colors and three fine hatch directions, selected by feature ID;
-features without IDs use the first plate (including the current World landcover tiles). This changes the surface treatment within existing
-polygons, without drawing invented parcel boundaries. Woods and gardens use subtle pigment grain and fibers; their textures contain no tree
-silhouettes or repeated orchard dots. Modern residential zoning has a quiet fiber texture,
-so decorative rectangles do not compete with actual footprints. Study of the Brussels and Namur sheets informs the finer building divisions, pale water interiors and softly pooled bank pigment.
-Building outlines become more distinct as the camera approaches, allowing red blocks to read
-together at neighborhood scale. Opaque water covers shared bank edges at river confluences
-and its survey centerlines; small streams
-without polygons keep their ink strokes and intermittent marks. Ferry routes remain as fine,
-subdued dashes. Water names use dark italic ink, a soft water-colored halo and wider repetition
-spacing. Roads use ivory paper-colored interiors and fine brown borders, following the
-[Cabinet Map detail published by KBR](https://www.kbr.be/wp-content/uploads/2026/05/detail-van-de-kabinetskaart.png).
-Width carries the hierarchy; major roads do not use an ochre fill. Dawn and dusk warm the
-ivory, while night uses a legible cool grey-blue.
-
-At regional and city scales, mapped residential areas use a pale red wash to distinguish
-settlements from open country. This wash transitions to the detailed paper ground between
-zoom 12 and 14 as individual buildings appear. Minor street and tertiary road borders enter
-gradually over their first two zoom levels. Peak and aerodrome names start at zoom 12 and 13,
-respectively, leaving settlement names clear at regional scales.
-
-The packaged Cormorant Garamond Regular, SemiBold and Italic faces replace the former sans-serif
-lettering. Major settlements use spaced capitals; local names, roads and water use mixed-case
-italics. These are contemporary licensed fonts, not recovered historical lettering.
-
-In the SDK checkout, preview the source with:
-
-```sh
-node packages/cli/dist/index.js preview --config packages/maps/map-1777.config.ts
-```
-
-Use **3D** at street scale to raise the buildings and trees. Buildings retain their red
-pigment, with fine ink-colored edges, softened corners and contact shading. Trees and
-buildings share cast shadows. Light direction stays attached to the map, independent of the camera.
-
-The map offers one **Default** palette family with four artistic times of day:
-
-| Preset | Paper and pigment                                        | Light                                  |
-| ------ | -------------------------------------------------------- | -------------------------------------- |
-| Dawn   | Rose parchment, coral red roofs and sage olives          | Low warm eastern sun                   |
-| Day    | Pale laid paper, vermilion roofs and green washes        | Warm southwestern sun                  |
-| Dusk   | Amber parchment, russet roofs and dark plum-brown ink    | Low amber western sun and cool shade   |
-| Night  | Indigo paper, muted rose-slate roofs and ivory lettering | Cool moonlight with restrained shadows |
-
-Each preset recolors the paper, water and landscape patterns as well as the map
-and 3D geometry. There are no Faded or Monochrome families. These presets are fixed artistic
-lighting setups; they do not follow the clock. The `light` theme ID remains the Default family
-and its Day preset. For a prepared map, select `{theme: 'light', timeOfDay: 'dawn'}` (or `day`,
-`dusk`, `night`). Concrete theme IDs are `dawn`, `light`, `dusk`, and `dark`, respectively;
-system appearance selects Day or Night.
-
-Pattern SVG variants are package-owned assets. After changing their pigments or source plates,
-regenerate them from the SDK checkout with
-`pnpm exec tsx packages/maps/scripts/generate-map-1777-patterns.ts`.
-
-The overhead view retains red footprints and small vector circles for mapped trees. Vegetation uses `auto` mode:
-the explicit 3D view enables olive trees with illustrated shading, while 2D views and
-renderers without model support retain flat trees. Capture and Static Maps use that flat
-vegetation fallback. Core's custom building and shadow renderer requires WebGL2; a native
-extrusion fallback does not reproduce its shadows.
-
-Pedestrian plazas sit above residential zoning and below gardens and woodland. Broad road
-and pier polygons stay hidden so they cannot cover those surfaces. Street and path widths grow smoothly through zoom 22 using Streets' exponential progression,
-with carriageways 15% slimmer and fine ink borders. Bridge casings have square ends, tunnels have continuous interiors,
-and access restrictions and covered segments preserve the road's continuity. Tunnel dashes
-use a narrow border around a continuous interior. Paths use pale gravel with fine ink edges;
-pedestrian streets have a wider cream surface. Green garden washes stay distinct from the paper
-in all four palettes. Modern street lights and invented night windows
-remain off. Street names follow the ground plane and pass behind raised buildings; place
-names stay above the city.
-
-Construction carriageways use separate dashed ink plates below roads in service, keeping
-ordinary road borders crisp. Highway links draw before receiving carriageways within their
-surface or bridge level, with the same widths and access treatments as the adjoining roads.
-Major road names take priority over minor streets and service ways. Land-cover and land-use
-washes, paths and flat tree symbols fade in over one zoom level; their full-detail pigments
-remain consistent across zoom levels.
-
-For application integration, see [3D buildings](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/buildings-3d.md)
-and [vegetation controls](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/trees-3d.md).