@tileflow/core 0.1.0-alpha.42 → 0.1.0-alpha.43

package/docs/compiled-style-performance.md

@@ -1,286 +0,0 @@
-# Compiled-style performance
-
-Start with the [@tileflow/core guide](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/README.md) for installation and a complete first example.
-
-The semantic compiler resolves semantic modules and their owned contributions first, then compacts equivalent
-physical MapLibre layers. At high-detail zooms, road classes become a small set of data-driven
-cohorts; equivalent road labels and tunnel hatches share compatible buckets; and land-cover,
-land-use, and waterway classes share compatible buckets. Compaction selects
-cohorts from compiler-owned semantic targets, not by parsing physical IDs; its temporary
-owner/slot/target provenance is stripped from the public Style JSON.
-
-After physical planning, Core embeds a bounded private `tileflow:interaction-manifest` lookup for the
-final POI representations. `@tileflow/interactions/maplibre` validates and consumes that metadata
-so applications can bind to `domain: 'poi'` without depending on physical layer IDs. The lookup is
-paired atomically with the exact style it describes; it is not a public style-authoring API.
-
-Use the exported structural sweep to enforce budgets without loading tiles or a browser:
-
-```ts
-import {analyzeTileflowStylePerformance, createStyle} from '@tileflow/core';
-import map from './tileflow.config';
-
-const report = analyzeTileflowStylePerformance(createStyle(map));
-console.log(report.zooms[16]);
-```
-
-The report covers z0–z22 by default and includes active layers, conservative bucket estimates,
-symbols, and active layers per source-layer. It is intended for regression gates; browser traces
-remain the source of truth for decode, upload, placement, and frame time.
-
-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.
-
-The road module distinguishes the path family semantically:
-
-```ts
-roads({
-  extras: {paths: true},
-  crossings: {image: token.image('roads.crosswalk')},
-  sidewalks: {
-    surface: {color: token.color('roads.city.casing'), minZoom: 17},
-    pattern: {
-      pattern: token.image('roads.sidewalkPattern'),
-      minZoom: 17,
-      opacity: fixed(0.6, {reason: 'Sidewalk texture strength is invariant'}),
-    },
-  },
-  roundabouts: {
-    casing: {strokeColor: token.color('roads.default.casing')},
-    fill: {strokeColor: token.color('roads.default')},
-  },
-  areas: {
-    pedestrian: {
-      fill: {color: token.color('surface.land')},
-      outline: {
-        color: token.color('roads.default.casing'),
-        width: fixed(1, {reason: 'Pedestrian-area outline weight is invariant'}),
-      },
-    },
-  },
-  classes: {
-    primary: {
-      tunnel: {
-        casing: {
-          color: token.color('roads.city.tunnelCasing'),
-          width: fixed(10, {reason: 'Primary-tunnel hierarchy is invariant'}),
-        },
-        fill: {
-          color: token.color('roads.city.tunnel'),
-          width: fixed(8, {reason: 'Primary-tunnel hierarchy is invariant'}),
-        },
-        hatch: {
-          color: token.color('roads.city.tunnelCasing'),
-          opacity: fixed(0.25, {reason: 'Tunnel hatch strength is invariant'}),
-          spacing: fixed(10, {reason: 'Tunnel hatch rhythm is invariant'}),
-        },
-      },
-    },
-    pedestrian: {
-      surface: {
-        fill: {
-          color: token.color('roads.path.transition'),
-          width: fixed(6, {reason: 'Pedestrian-road hierarchy is invariant'}),
-        },
-      },
-    },
-    footway: {
-      surface: {
-        fill: {
-          color: token.color('roads.path'),
-          width: fixed(1.2, {reason: 'Path hierarchy is invariant'}),
-        },
-      },
-    },
-    cycleway: {
-      surface: {
-        fill: {
-          color: token.color('roads.cycleway'),
-          width: fixed(1.5, {reason: 'Cycleway hierarchy is invariant'}),
-        },
-      },
-    },
-    steps: {
-      surface: {
-        fill: {
-          color: token.color('roads.path.casing'),
-          width: fixed(1.4, {reason: 'Step hierarchy is invariant'}),
-        },
-      },
-    },
-    pathway: {
-      surface: {
-        fill: {
-          color: token.color('roads.path'),
-          width: fixed(1.2, {reason: 'Path hierarchy is invariant'}),
-        },
-      },
-    },
-  },
-  modifiers: {
-    expressway: {widthScale: 1.06},
-    ramp: {widthScale: 0.7},
-    unpaved: {surface: {fill: {color: token.color('roads.path')}}},
-    construction: {
-      surface: {
-        fill: {opacity: fixed(0.7, {reason: 'Construction emphasis is invariant'})},
-      },
-    },
-    indoor: {
-      surface: {fill: {opacity: fixed(0.4, {reason: 'Indoor-road emphasis is invariant'})}},
-    },
-  },
-  restrictions: {
-    access: {
-      surface: {fill: {opacity: fixed(0.55, {reason: 'Restricted-road emphasis is invariant'})}},
-    },
-    toll: {
-      surface: {
-        casing: {color: fixed('#C5B7D8', {reason: 'Toll ink is regulatory and invariant'})},
-      },
-    },
-  },
-  serviceTypes: {
-    driveway: {widthScale: 0.75},
-    parkingAisle: {widthScale: 0.6},
-  },
-});
-```
-
-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`. Glyph hatch marks inherit the resolved fill width
-when `size` is omitted and never participate in label collision. Setting `hatch.pattern` instead
-emits a repeated sprite texture clipped to the resolved fill width. No raw source filter or generated
-layer ID is needed. `hatch.patternWidths` can list intrinsic sprite heights named
-`${pattern}-${width}`; the compiler selects the nearest height from the resolved road width so the
-texture's marks remain approximately constant in screen pixels across classes, ramps, and zooms.
-
-`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. With a
-`transportationOutline` binding, as in Tileflow World, area outlines stroke only the outer boundary
-of each area, never its holes.
-
-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, which apply to paths and tracks, 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.
-
-A solid dash, `[1, 0]`, is emitted as no `line-dasharray` at all, so MapLibre draws the line with
-its solid-line shader rather than its dash shader. A treatment's dash that depends on the road
-class is settled for each class layer: a dash for construction paths leaves a motorway's layers
-solid. Roundabout rings state their road widths at each zoom as numbers where the widths allow,
-and name the feature conditions they repeat once with `let`, which keeps their style compact and
-quick to validate.
-
-Road names, shields, and motorway junctions remain label concerns:
-
-```ts
-labels({
-  roads: 'all',
-  shields: 'major',
-  junctions: true,
-  styles: {
-    shields: {
-      default: {
-        icon: {
-          image: token.image('roads.shield.rectangleNeutral'),
-          optional: false,
-          pitchAlignment: 'viewport',
-          rotationAlignment: 'viewport',
-          textFit: 'width',
-          textFitPadding: [0, 4, 0, 4],
-        },
-        text: {
-          color: token.color('labels.shieldDark'),
-          font: token.font('places'),
-          optional: false,
-          pitchAlignment: 'viewport',
-          rotationAlignment: 'viewport',
-        },
-      },
-      overview: {minZoom: 6, maxZoom: 11, placement: 'point'},
-      detail: {minZoom: 11, placement: 'line', spacing: 400},
-      kinds: {
-        'rectangle-neutral': {image: token.image('roads.shield.rectangleNeutral')},
-        'rectangle-blue': {image: token.image('roads.shield.rectangleBlue')},
-      },
-      textColors: {
-        dark: {color: token.color('labels.shieldDark')},
-        light: {color: token.color('labels.shieldLight')},
-      },
-    },
-    junctions: {
-      text: {
-        color: token.color('labels.strong'),
-        haloColor: token.color('labels.halo'),
-        haloWidth: fixed(2, {reason: 'Junction halo weight is invariant'}),
-      },
-    },
-  },
-});
-```
-
-`icon.textFit` and `icon.textFitPadding` let a symbol background grow with its text. Setting both
-icon and text `optional: false` keeps a route shield atomic during collision placement: neither an
-empty badge nor a detached reference can render alone. `overview` renders producer-selected points
-at low zoom and `detail` switches to line placement at street zooms; exclusive `maxZoom: 11` and
-inclusive `minZoom: 11` make that handoff atomic. Keeping both icon and text aligned to `viewport`
-makes the badge horizontal regardless of road bearing.
-
-`kinds` and `textColors` are closed presentation tables. The vector producer supplies semantic
-`shield_kind`, `shield_text_color`, `shield_text`, and `shield_rank` values; Core only matches them
-against the authored tables and falls back to `default`. Country, route-prefix, and network-shape
-rules therefore stay in the data authority instead of leaking into a map theme or multiplying
-runtime layers.
-
-Tileflow World owns POI classification, editorial zoom eligibility, and cross-source ranking. Its
-canonical `poi` layer exposes `category`, `type`, `icon`, `min_zoom`, `filter_rank`, and `size_rank`;
-Core validates that complete contract and never reconstructs those decisions from OpenMapTiles
-`class`, `subclass`, or `rank`. `filter_rank` is an
-integer from 0 through 5, with lower values reserved for the strongest candidates. The numeric
-`density` option is an inclusive threshold from 1 through 5 and defaults to 3. World publishes
-every eligible POI at z15, its last POI zoom, and higher zooms overzoom those tiles with more room,
-so the threshold rises by one rank at z16 and by two from z17. At the default density every rank is
-eligible from z17, and collision placement keeps what fits. `size_rank` is an
-integer from 0 through 16 used to order eligible candidates before MapLibre performs final
-collision placement.
-
-The closed category vocabulary is `arts-entertainment`, `education`, `food-drink`, `landmark`,
-`lodging`, `medical`, `park-nature`, `public-services`, `religion`, `retail`, `sport-leisure`,
-`transport`, and `visitor-amenity`. Producer `type` and `icon` values use stable snake_case names.
-When an `icon` sprite exists it is used directly; an unknown or absent icon safely falls back to the
-category's themed image role. `labels` and `icons` are booleans. Category styles control only
-presentation and never promote candidates above the producer's selection.
-`placement.coupleIconAndLabel` keeps a POI's icon and label atomic during collision placement:
-both are required.
-
-MapLibre orders symbol placement only within a layer, so the module compiles every category into
-one layer per representation and orders it by `filter_rank` and `size_rank`: a station is placed
-before a cash machine whatever their categories. Per-category appearance becomes a `match` on
-`category`; zoom curves are hoisted above it so each category keeps its exact curve. Categories that
-need different layer-wide properties use `placement.order: 'categories'`, one layer per category in
-listed order. `placement.prominentRank` places the most important ranks in a second layer above road
-and place labels, which keeps landmarks visible on maps whose labels give street names priority.
-When icons and labels are both drawn, unnamed POIs are omitted except the self-explanatory types in
-`placement.iconOnlyTypes` (parking and public toilets by default), which draw only their pictogram.
-
-```ts
-poi({
-  categories: ['food-drink', 'landmark', 'transport'],
-  density: 3,
-  icons: true,
-  labels: true,
-});
-```
-
-The same contract drives regular POI layers, custom HUD treatments, semantic interactions, and
-feature inspection. There is intentionally no compatibility path for the former class mapping,
-rank ceilings, per-category densities, or named density/detail presets.