@tileflow/core 0.1.0-alpha.18 → 0.1.0-alpha.19

package/README.md

@@ -1,261 +1,280 @@
 # @tileflow/core
 
-Typed Tileflow config helpers and the MapLibre style compiler.
+Typed Tileflow authoring primitives and the deterministic Tileflow Streets compiler.
 
 ```ts
-import {defineTileflow, labels, osm, poi, roads} from '@tileflow/core';
+import {defineTileflow, labels, poi, roads, streets, water, zoom} from '@tileflow/core';
 
 export default defineTileflow({
-  icons: {
-    brand: {
-      sprite: 'https://cdn.example.com/tileflow/brand/sprite',
-    },
-  },
   themes: {
-    light: {
+    editorial: {
+      extends: 'light',
       colors: {
-        background: '#F8F7F7',
-        land: '#F4F2ED',
-        water: '#8ED6E8',
-        park: '#C3F1D5',
-        building: '#EEF0F2',
-        road: '#FFFFFF',
-        roadMajor: '#F5D58A',
-        roadCasing: '#DDE0E3',
-        boundary: '#C9CED3',
-        text: '#566371',
-        textMuted: '#8A98A8',
-        textHalo: '#FFFFFF',
-      },
-      modules: {
-        labels: {
-          road: '#7A8794',
-          water: '#4B8FA8',
-        },
-        poi: {
-          food: '#D97706',
-          transit: '#2563EB',
-        },
-        roads: {
-          motorway: '#F7C56F',
-        },
-      },
-      typography: {
-        font: 'Inter',
-        roads: {weight: 'bold'},
+        background: '#E4DFD4',
+        land: '#F5F2EB',
+        water: '#A7CED7',
+        park: '#C6D8B7',
+        building: '#D6CFC3',
+        road: '#FCFBF8',
+        roadMajor: '#EBCB8F',
+        roadCasing: '#BBB1A1',
+        boundary: '#999184',
+        text: '#252B2D',
+        textMuted: '#626866',
+        textHalo: '#FBF9F4',
       },
+      typography: {font: 'Noto Sans', places: {weight: 'bold'}},
     },
   },
   maps: {
     madrid: {
-      basemap: osm({version: '2026-06-07'}),
-      icons: 'brand',
-      theme: 'light',
-      modules: [
-        labels({roads: 'major', roadClasses: ['motorway', 'trunk', 'primary']}),
-        poi({
-          categories: ['food', 'coffee', 'culture', 'transit'],
-          color: 'category',
-          density: 'balanced',
-          icons: 'essential',
-        }),
-        roads({
+      basemap: streets(),
+      theme: 'editorial',
+      modules: {
+        water: water({bodies: {fill: {opacity: 0.95}}}),
+        roads: roads({
           detail: 'streets',
-          hierarchy: 'clear',
-          oneWayMarkers: true,
-          outline: 'subtle',
-          weight: 'regular',
-          widthScale: {motorway: 1.15, minor: 0.9},
+          hierarchy: 'strong',
+          classes: {
+            primary: {
+              surface: {
+                fill: {
+                  color: '#E4A85B',
+                  width: zoom.linear([
+                    [7, 0.6],
+                    [16, 8],
+                  ]),
+                },
+              },
+            },
+          },
         }),
-      ],
-      layers: {
-        'highway-primary': {
-          paint: {
-            'line-opacity': 0.9,
+        labels: labels({
+          language: 'local',
+          places: 'all',
+          roads: 'streets',
+          styles: {
+            places: {city: {text: {size: 18, haloWidth: 1.5}}},
           },
-        },
-      },
-      view: {
-        center: [-3.7038, 40.4168],
-        zoom: 12,
+        }),
+        poi: poi({categories: ['food', 'culture', 'transit'], color: 'category'}),
       },
+      view: {center: [-3.7038, 40.4168], pitch: 35, zoom: 12},
     },
   },
 });
 ```
 
-## Capture scenes
+## Authoring model
 
-Commit named visual scenes beside the maps they exercise. Scenes are strict, bounded test inputs;
-they do not change style or manifest identity.
+`streets()` is the only built-in basemap. It identifies a versioned cartographic recipe and does
+not inherit or patch another style. The compiler resolves the complete Streets design and asks
+each domain module to create its own MapLibre layers. A shared graph then determines layer order.
 
-```ts
-export default defineTileflow({
-  maps: {
-    madrid: {basemap: osm(), theme: 'light'},
-  },
-  scenes: {
-    'madrid-desktop': {
-      map: 'madrid',
-      camera: {type: 'center', center: [-3.7038, 40.4168], zoom: 12},
-      viewport: {width: 1280, height: 800, dpr: 1},
-    },
-    'madrid-product': {
-      map: 'madrid',
-      camera: {type: 'center', center: [-3.7038, 40.4168], zoom: 12},
-      viewport: {width: 390, height: 844, dpr: 2},
-      target: {
-        kind: 'application',
-        path: '/maps/madrid',
-        captureId: 'product-map',
-      },
-    },
-  },
-});
+```mermaid
+flowchart LR
+  A["Human or agent edits config"] --> B["Streets defaults + theme + keyed modules"]
+  B --> C["Domain compilers"]
+  C --> D["Ordered Streets layers"]
+  D --> E["Validated MapLibre Style JSON"]
 ```
 
-The default target renders autonomously with no server. An application target uses the app's
-normal loopback development server and selects exactly one wrapper by `captureId`, explicit
-selector, or map name. Cameras accept `center` or `bounds`; viewports are 64–4096 CSS pixels at DPR
-1 or 2 within the public physical-pixel budget. Standalone capture applies the camera; an
-application route must render it itself because capture does not mutate application component
-state. Use `tileflow capture <scene>` or the `@tileflow/capture` Node package to render them.
+Modules are keyed by domain, so object order never controls rendering and a domain can appear only
+once. Omit a module to keep the complete Streets default. Use `enabled: false` to remove a domain
+deliberately. The public domains are `land`, `water`, `roads`, `buildings`, `boundaries`, `labels`,
+`poi`, `aeroways`, and `transit`.
+
+Every styling module supports semantic shortcuts and exact semantic targets. Style values accept
+constants, raw MapLibre expressions through `expression(...)`, and zoom functions through
+`zoom.step(...)`, `zoom.linear(...)`, or `zoom.exponential(...)`. Exact controls address stable
+concepts such as `roads.classes.primary.surface.fill`, not renderer layer IDs.
 
-## Style contract
+## Shared visual primitives
 
-Tileflow keeps these levels separate:
+The same small visual language is reused across every geographic domain. This keeps an agent from
+having to learn different spellings for the same MapLibre behavior:
 
-- `basemap: osm()` chooses the source defaults, glyphs, sprites, and OSM Bright layer template.
-- `theme.colors` contains human-scale base tokens such as `water`, `park`, `road`, `roadMajor`, `roadCasing`, `text`, and `textHalo`.
-- `theme.modules.<name>` contains advanced, module-specific tokens. These are granular: setting `theme.modules.roads.rail` does not recolor primary roads.
-- `maps.<name>.icons` can point at a reusable root icon set, a hosted MapLibre sprite URL, or a local icon folder for Vite/build output.
-- `maps.<name>.modules` enables semantic behavior such as `labels()`, `poi()`, and `roads()`. Road colors remain in `theme.modules.roads`; `roads()` controls detail, hierarchy, weight, outline, and optional transport extras.
-- `typography` sets a global font/weight and optional `places`, `roads`, `water`, and `poi` overrides. The hosted Noto Sans endpoint guarantees `regular` and `bold`; custom glyph endpoints may provide the other typed weights.
-- `buildingStyle` controls generated building fill opacity, outline opacity/width, and a height threshold that selects the theme's low/high-rise colors. Generated landuse and landcover layers consume their corresponding module colors.
-- `maps.<name>.renderer` can be `auto`, `osm-bright`, or `generated`. `auto` preserves the default template when compatible; `generated` always uses Tileflow's generated layers; `osm-bright` throws if the map config cannot be rendered with the template.
-- `layers` is the raw MapLibre escape hatch for exact layer patches.
+- `BackgroundStyle`: color, opacity, pattern, visibility, and zoom range.
+- `FillStyle`: color, opacity, pattern, antialiasing, visibility, and zoom range.
+- `LineStyle`: color, width, opacity, dash, blur, gap, offset, pattern, caps, joins, and zoom range.
+- `LineHatchStyle`: repeated diagonal detail with color, opacity, spacing, size, angle, and zoom
+  range for a road structure.
+- `TextStyle`: field, font, weight, fallbacks, size, color, halo, spacing metrics, transform,
+  collision policy, rotation, fixed/variable anchoring, line constraints, and zoom range.
+- `IconStyle`: image, size, color, halo, rotation/alignment, collision policy, and zoom range.
+- `CircleStyle`: radius, fill/stroke appearance, blur, opacity, pitch behavior, and zoom range.
+- `ExtrusionStyle`: color, height, base, opacity, pattern, vertical gradient, and zoom range.
 
-Missing colors preserve the basemap default. Legacy aliases such as `accent`, `canvas`, `greenspace`, `fontFamily`, and `fonts` are accepted for compatibility but are not the recommended API.
+Compounds express common cartographic structures: `AreaStyle` has `fill` and `outline`,
+`LineStackStyle` has `shadow`, `casing`, and `fill`, and `SymbolStyle` combines placement with
+optional `text`, `icon`, and `marker`. Geographic selection remains owned by semantic modules;
+ordinary visual styles intentionally do not accept raw source filters.
 
-## Roads module
+A `SymbolStyle` root zoom range governs its text/icon layer and is inherited by its marker layer.
+Because a marker is materialized as a separate circle layer, an explicit marker range may refine
+that inherited default. Text and icon ranges must agree because MapLibre renders them together.
 
-Control each independent road-network decision directly:
+The road module distinguishes the path family semantically:
 
 ```ts
 roads({
-  detail: 'streets',
-  hierarchy: 'strong',
-  weight: 'regular',
-  outline: 'strong',
-  oneWayMarkers: true,
-  widthScale: {motorway: 1.15, primary: 1.05, minor: 0.9},
-  extras: {
-    paths: false,
-    rail: false,
-    ferry: false,
+  extras: {paths: true},
+  areas: {
+    pedestrian: {
+      fill: {color: '#F1F3F5'},
+      outline: {color: '#D5DCE3', width: 1},
+    },
+  },
+  classes: {
+    primary: {
+      tunnel: {
+        casing: {color: '#8EA3B8', width: 10},
+        fill: {color: '#F5F8FA', width: 8},
+        hatch: {color: '#8EA3B8', opacity: 0.25, spacing: 10},
+      },
+    },
+    pedestrian: {surface: {fill: {color: '#F5F6F7', width: 6}}},
+    footway: {surface: {fill: {color: '#D9DEE3', width: 1.2}}},
+    cycleway: {surface: {fill: {color: '#9ED8C5', width: 1.5}}},
+    steps: {surface: {fill: {color: '#C7CED6', dash: [1, 1], width: 1.4}}},
+    pathway: {surface: {fill: {color: '#E8ECEF', width: 1.2}}},
+  },
+  modifiers: {
+    expressway: {widthScale: 1.06},
+    ramp: {widthScale: 0.7},
+    unpaved: {surface: {fill: {color: '#E6DFD3', dash: [2, 1]}}},
+    construction: {surface: {fill: {dash: [2, 1], opacity: 0.7}}},
+    indoor: {surface: {fill: {dash: [1, 1], opacity: 0.4}}},
+  },
+  restrictions: {
+    access: {surface: {fill: {dash: [1.5, 1], opacity: 0.55}}},
+    toll: {surface: {casing: {color: '#C5B7D8'}}},
+  },
+  serviceTypes: {
+    driveway: {widthScale: 0.75},
+    parkingAisle: {widthScale: 0.6},
   },
 });
 ```
 
-`detail` is progressive: `none` hides roads; `highways` shows motorway and trunk roads;
-`major` adds primary, secondary, and tertiary roads; `streets` adds minor streets; and `all`
-adds service roads and tracks. `hierarchy` accepts `subtle`, `clear`, or `strong`; `weight`
-accepts `thin`, `regular`, or `bold`; and `outline` accepts `none`, `subtle`, or `strong`.
-`extras.paths`, `extras.rail`, and `extras.ferry` are independent and default to `false`.
-`widthScale` accepts bounded multipliers for selected road classes, and `oneWayMarkers` adds
-direction markers to eligible one-way roads.
-
-Without options, `roads()` uses `detail: 'streets'`, `hierarchy: 'clear'`,
-`weight: 'regular'`, `outline: 'subtle'`, and all extras disabled. Named visual recipes belong
-in examples rather than the runtime API, so the resolved behavior is always visible in config.
+These targets are non-overlapping translations of the OpenMapTiles road class and subclass. The
+same names are available under `labels().roadClasses` and `labels().styles.roads`. Surface, tunnel,
+and bridge phases can be controlled independently for each target; each structure has
+`shadow`/`casing`/`fill` and an optional `hatch`. Hatch marks inherit the resolved fill width when
+`size` is omitted and never participate in label collision. No raw source filter or generated layer
+ID is needed.
 
-Colors never belong in `roads()`. Put common colors in `theme.colors` and granular road colors in `theme.modules.roads`. Road-label detail remains a `labels({roads: ...})` concern.
+`classes.pedestrian` styles line-like pedestrian ways. Polygon pedestrian plazas are a distinct
+geometry and use `areas.pedestrian`, including optional fill opacity, outline color, or sprite
+pattern. This prevents plazas from degrading into a thin polygon outline.
 
-## Labels module
+Road treatments refine a class without creating another class or exposing source fields.
+`construction`, `expressway`, `indoor`, `official`, `ramp`, and `unpaved` live under `modifiers`;
+general, bicycle, foot, horse, and toll restrictions live under `restrictions`; `alley`,
+`crossover`, `driveway`, `parkingAisle`, and `yard` live under `serviceTypes`; and exact
+mountain-bike difficulty values live under `mountainBike`. Treatments reuse
+surface/tunnel/bridge and casing/fill/shadow paint controls, plus a relative `widthScale`. The
+compiler emits feature-driven paint expressions inside the existing stable class layers rather
+than multiplying every possible combination.
 
-Control label families independently without a preset:
+Road names, shields, and motorway junctions remain label concerns:
 
 ```ts
 labels({
-  language: 'auto',
-  places: 'major',
-  roads: 'major',
-  roadClasses: ['motorway', 'trunk', 'primary', 'secondary'],
-  water: 'major',
+  roads: 'all',
+  shields: 'all',
+  junctions: true,
+  styles: {
+    shields: {
+      default: {text: {color: '#405264', haloColor: '#fff', haloWidth: 2, weight: 'bold'}},
+      networks: {
+        'network-value': {text: {color: '#B43A35'}},
+      },
+    },
+    junctions: {text: {color: '#405264', haloColor: '#fff', haloWidth: 2}},
+  },
 });
 ```
 
-`places` and `water` accept `none`, `major`, or `all`. Road labels follow the road hierarchy and
-accept `none`, `highways`, `major`, `streets`, or `all`: `highways` includes motorway and trunk
-labels, `major` adds primary through tertiary, `streets` adds minor streets, and `all` adds service
-roads and tracks. Path labels are eligible at `all` only when path geometry is visible; when
-`roads()` is present, enable it with `roads({extras: {paths: true}})`.
+POI `density`, `labels`, and `icons` are independent policies. Density bounds eligible feature
+ranks, label detail controls text ranks, icon detail controls icon ranks, and
+`placement.coupleIconAndLabel` deliberately keeps only features eligible for both. Without
+coupling, icon and label layers collide normally but can be styled and zoomed independently.
+The `balanced` policy keeps a practical cross-category candidate set from an overscaled
+OpenMapTiles source tile; MapLibre collision placement still decides which candidates fit the
+current viewport. Use a category style's inclusive `maxRank` when different feature families need
+different candidate ceilings; the explicit category value replaces the density/label/icon preset
+ceiling for that category without exposing a raw layer ID or filter.
 
-Detail values select which feature classes may be labeled; they do not force every name onto the
-map. Labels keep the template's natural zoom ranges and MapLibre collision handling. Road labels
-are also clamped to the classes currently visible through `roads({detail})`, so the effective result
-is the intersection of both modules. `language` accepts `auto`, `local`, or a language code such as
-`en` or `es`.
+Theme tokens provide shared color and typography defaults. A module-level exact style wins over a
+theme token for that target. Precedence is deterministic:
 
-`roadClasses` is an optional explicit eligibility list. It is intersected with both the label
-detail and visible `roads()` classes, so it cannot label a road family that the map has hidden.
+1. Streets recipe defaults.
+2. Selected theme and inherited named theme.
+3. Explicit keyed module fields.
+4. Ordered raw overrides.
 
-Without options, `labels()` uses `language: 'auto'` and `major` for all three label families.
-Label colors remain in `theme.modules.labels`; font family and weight remain in `typography`.
+Raw `addLayer`, `patchLayer`, `moveLayer`, and `removeLayer` operations are the final MapLibre escape
+hatch. They are ordered, target generated `streets-*` IDs explicitly, and fail when a target or
+anchor does not exist. They should be used for one-off MapLibre behavior, not ordinary design.
 
-## POI module
+## Data is separate from design
 
-POI category policy is resolved once for filtering, icon selection, label color, and collision
-priority:
+Omitting `data` selects Tileflow World at the revision pinned by this SDK version:
 
 ```ts
-poi({
-  categories: ['food', 'culture', 'lodging'],
-  classMapping: {culture: ['planetarium']},
-  color: 'category',
-  density: 'balanced',
-  icons: 'full',
-  labels: 'full',
-  placement: {coupleIconAndLabel: true, iconPadding: 4, textPadding: 8},
-});
+{
+  basemap: streets();
+}
 ```
 
-Built-in mappings inspect both `class` and `subclass`; `classMapping` adds source-specific values
-without removing the defaults. `color: 'category'` uses `theme.modules.poi` colors end to end.
-Named density is opt-in and adds bounded category-aware rank gates plus stable sort priority;
-omitting it preserves legacy layer behavior. Raw source rank expressions remain available through
-`styleOverride` when a particular dataset needs a bespoke rule.
+Pin the official data deliberately, or use another OpenMapTiles-compatible vector source:
 
-## Tile-source revision
+```ts
+import {openMapTiles, tileflowWorld, vectorTiles} from '@tileflow/core';
+
+const official = tileflowWorld({revision: '2026-06-07'});
+const external = vectorTiles({
+  url: 'https://tiles.example.com/tiles.json',
+  attribution: '© Example © OpenStreetMap contributors',
+  schema: openMapTiles(),
+});
+```
 
-Set `version` on `osm({...})`, `maps.<name>.tiles`, or a named project tileset to pin an immutable
-archive identifier. Map-level `tiles.version` wins over basemap and named-tileset defaults. Tileflow
-adds it as `archiveVersion` to the TileJSON URL and records it as
-`metadata['tileflow:tilesetVersion']`; it never infers stability from an unversioned response.
+The basemap controls how data is drawn; `data` controls where compatible features come from. The
+compiler performs no network request. `openMapTiles({layers, fields})` can bind renamed
+source-layers or properties while preserving the versioned semantic contract. External browser
+credentials do not belong in public Style JSON; supply them through the framework's
+`transformRequest` integration.
 
-## Public API
+## Capture scenes
 
-Application config, compilation, runtime resolution, and capture-scene APIs come from the package
-root:
+Commit named scenes beside maps. Scenes affect visual evidence, not style or manifest identity.
 
 ```ts
-import {
-  createStyle,
-  defineTileflow,
-  labels,
-  osm,
-  poi,
-  roads,
-  styleOverride,
-  validateConfig,
-} from '@tileflow/core';
+export default defineTileflow({
+  maps: {madrid: {basemap: streets()}},
+  scenes: {
+    'madrid-desktop': {
+      map: 'madrid',
+      camera: {type: 'center', center: [-3.7038, 40.4168], zoom: 12},
+      viewport: {width: 1280, height: 800, dpr: 1},
+    },
+  },
+});
 ```
 
-Capture scene schemas, types, normalization, limits, and schema version are also exported from the
-package root. See the [local visual capture contract](https://tileflow.dev/docs/agent-workflow) for
-the CLI workflow and readiness boundary.
+Use `tileflow dev --scene madrid-desktop` for live review and `tileflow capture madrid-desktop`
+for exact pixels and a schema-version-2 receipt containing the Streets, data, style, renderer, and
+image identities.
+
+## Public API and browser subpath
+
+Config, data, modules, compilation, validation, runtime resolution, and capture-scene APIs come
+from the package root. Legacy basemap factories, `renderer`, top-level `tiles`/`tileset`, module
+arrays, and raw `layers` are not part of this API.
 
-Framework adapters can import the browser-only lifecycle kernel explicitly:
+Framework adapters import the browser-only lifecycle kernel explicitly:
 
 ```ts
 import {
@@ -266,11 +285,10 @@ import {
 } from '@tileflow/core/browser';
 ```
 
-The browser subpath is not re-exported from the root. It is safe to import during SSR, does not
-depend on MapLibre, and reads no browser globals during module evaluation. Adapter authors inject
-their frame scheduler plus MapLibre event and marker operations after mount. The package contract
-is documented in
-[`docs/contracts/framework-browser-runtime.md`](../../docs/contracts/framework-browser-runtime.md).
+The browser entry is not re-exported from the root. It is SSR-safe to import, has no MapLibre
+runtime dependency, and reads no browser global during module evaluation. See the
+[framework browser runtime contract](../../docs/contracts/framework-browser-runtime.md) and the
+[cartographic authoring contract](../../docs/contracts/cartographic-authoring.md).
 
 ## Hosted session authorization
 
@@ -288,4 +306,9 @@ then decorates only the resulting eligible URL and preserves the other request o
 Other subpaths under `src/`, `themes/`, `templates/`, and `modules/` are internal implementation
 details and can change during alpha releases.
 
-Docs: https://tileflow.dev/docs
+Streets build, preview, capture, and deploy flows supply a built-in POI sprite with Google Places
+glyphs inside Tileflow circular markers. The markers use Google's category colors, a white rim, and
+a compact shadow. A project-local icon source or explicit hosted sprite replaces that catalog;
+build and deploy replace local sources with generated sprite URLs without exposing source paths.
+Calling the pure core style compiler without asset preparation remains text-only unless the map
+provides `icons` or `sprite` explicitly.

package/dist/browser.d.ts

@@ -1,4 +1,4 @@
-import { T as TileflowAnalytics, a as TileflowSessionController } from './runtime-Bg--GMWM.js';
+import { T as TileflowAnalytics, a as TileflowSessionController } from './runtime-Dd_xGAXq.js';
 import 'zod';
 
 type TileflowMapReadinessState = 'error' | 'idle' | 'loading';