@tileflow/core 0.1.0-alpha.3 → 0.1.0-alpha.31

package/docs/map-and-terrain-examples.md

@@ -0,0 +1,149 @@
+# Map and terrain examples
+
+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.
+
+Typed Tileflow map contracts, semantic modules, and deterministic MapLibre style compilation.
+
+Every public `tileflow.config.ts` exports one map. Most maps import an existing map and override only
+the design fields they own:
+
+```ts
+import {
+  defineMap,
+  defineTheme,
+  fixed,
+  labels,
+  poi,
+  roads,
+  token,
+  water,
+  zoom,
+} from '@tileflow/core';
+import {streets, streetsThemes} from '@tileflow/maps';
+
+const madridDark = defineTheme(streetsThemes.dark, {
+  id: 'madrid-dark',
+  version: 1,
+  colorScheme: 'dark',
+  tokens: {color: {'surface.land': '#0d1320', 'surface.water': '#081e2e'}},
+});
+
+export default defineMap({
+  id: 'madrid',
+  name: 'Madrid',
+  version: 1,
+  extends: streets,
+  themes: {light: streetsThemes.light, dark: madridDark},
+  defaultTheme: 'light',
+  systemThemes: {light: 'light', dark: 'dark'},
+  projection: 'globe',
+  modules: {
+    water: water({
+      bodies: {
+        fill: {
+          opacity: fixed(0.95, {reason: 'Madrid keeps this water density in every theme'}),
+        },
+      },
+    }),
+    roads: roads({
+      detail: 'streets',
+      hierarchy: 'strong',
+      classes: {
+        primary: {
+          surface: {
+            fill: {
+              color: fixed('#E4A85B', {reason: 'Madrid brand roads stay warm in every theme'}),
+              width: zoom.linear([
+                [7, fixed(0.6, {reason: 'Madrid keeps its primary-road hierarchy across themes'})],
+                [16, fixed(8, {reason: 'Madrid keeps its primary-road hierarchy across themes'})],
+              ]),
+            },
+          },
+        },
+        secondary: {surface: {fill: {color: token.color('roads.secondary')}}},
+      },
+    }),
+    labels: labels({
+      language: 'local',
+      places: 'all',
+      roads: 'streets',
+      styles: {
+        places: {
+          city: {
+            text: {
+              size: fixed(18, {reason: 'Madrid keeps its city-label scale across themes'}),
+              haloWidth: fixed(1.5, {reason: 'Madrid keeps its city-label halo across themes'}),
+            },
+          },
+        },
+      },
+    }),
+    poi: poi({categories: ['food-drink', 'arts-entertainment', 'transport'], color: 'category'}),
+  },
+  view: {center: [-3.7038, 40.4168], pitch: 35, zoom: 12},
+});
+```
+
+Map identity and scenes belong to the leaf and do not inherit. Hosted browser policy is configured
+in Tileflow and does not enter cartographic authoring or compilation.
+
+Set `projection: 'globe'` for MapLibre's adaptive globe preset. Global zooms render as a sphere,
+then transition to Mercator between zoom 10 and 12 so detailed streets remain planar. Omit the
+property, or set it to `'mercator'`, for a consistently flat map.
+
+Terrain keeps the original `'none' | 'hillshade' | '3d'` shorthand. The object form can style every
+MapLibre hillshade paint control, or generate vector contours in the browser from an explicit DEM
+tile template. Contours require `demUrl`, `demMaxZoom`, and zoom-indexed `[minor, index]`
+`thresholds`; the raster `url` remains the separate TileJSON endpoint. Set `mode: 'none'` to compile
+contours without adding a raster source, hillshade, or 3D terrain:
+
+```ts
+terrain: {
+  mode: 'none',
+  encoding: 'terrarium',
+  contours: {
+    demUrl: 'https://terrain.example.test/{z}/{x}/{y}.webp',
+    demMaxZoom: 13,
+    maxZoom: 15,
+    overzoom: 2,
+    thresholds: {
+      9: [100, 500],
+      11: [50, 250],
+      13: [20, 100],
+      15: [10, 50],
+    },
+    minor: {
+      color: token.color('terrain.contour.minor'),
+      width: token.number('terrain.contour.minor-width'),
+    },
+    index: {
+      color: token.color('terrain.contour.index'),
+      width: token.number('terrain.contour.index-width'),
+    },
+    labels: {
+      color: token.color('terrain.contour.label'),
+      haloColor: token.color('terrain.contour.halo'),
+    },
+  },
+}
+```
+
+Declare those `terrain.*` color and number roles with the same keys in every map theme. The
+compiled source is ordinary MapLibre vector data with source layer `contours`; its tile URL
+contains the safely encoded DEM template and complete generation parameters. Register the generic
+protocol before MapLibre reads the style. It lazily initializes the pinned, locally bundled
+`maplibre-contour@0.1.0` browser module on the first contour tile; no public CDN runtime is needed.
+`overzoom` may not exceed the lowest threshold zoom, so generated DEM requests never use a negative
+zoom. Every index interval must be a whole multiple of its minor interval. Contour labels emit the
+scaled numeric elevation without assuming a display unit. Source and layer visibility cannot begin
+before the first configured threshold zoom. To bound main-thread work, effective minor intervals
+must be at least 250 units at z0–4, 100 at z5–7, 50 at z8–10, 20 at z11–12, and 10 from z13 onward.
+Use a trusted, size-bounded DEM tile service; the protocol intentionally accepts author-supplied
+HTTP(S) templates rather than proxying or republishing terrain data.
+
+```ts
+import maplibregl from 'maplibre-gl';
+import {registerTileflowContourProtocol} from '@tileflow/core/browser';
+
+registerTileflowContourProtocol({addProtocol: maplibregl.addProtocol});
+```

package/docs/map-emphasis.md

@@ -0,0 +1,89 @@
+# Map emphasis
+
+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.
+
+An application that draws its own content over a Tileflow map, such as a route, a selected place, or
+search results, often needs the map to step back so that content reads first. Map emphasis does
+that on the map's own MapLibre instance: chosen modules recede towards the map's ground colour, and
+the map's labels and icons fade, except inside an area the application keeps at full strength. The
+change eases in and out, stays when the theme changes, and follows a theme blend.
+
+Emphasis needs a browser document and MapLibre GL JS. It changes only the layers a Tileflow map
+compiled, so an application's own layers, such as the route it draws, keep their appearance.
+
+## Show an emphasis
+
+Create the theme controller for the map, then ask for an emphasis. This example assumes an existing
+MapLibre map named `map` that shows the `dark` theme of a published Tileflow map, and a route the
+application has already drawn:
+
+```ts
+import type {Map as MapLibreMap} from 'maplibre-gl';
+import {createTileflowThemeController} from '@tileflow/core/browser';
+
+export function focusOnRoute(map: MapLibreMap, styleUrl: string) {
+  const controller = createTileflowThemeController({
+    initial: {style: styleUrl, theme: 'dark'},
+    map,
+  });
+  void controller.setEmphasis(
+    {
+      labels: 0.6,
+      recede: {boundaries: 0.55, roads: 0.5, transit: 0.5},
+    },
+    {transition: {duration: 560}},
+  );
+  return () => controller.setEmphasis(undefined, {transition: {duration: 560}});
+}
+```
+
+Roads, transit, and boundaries move halfway or a little more towards the ground colour, labels and
+icons keep 60 % of their opacity, and the change eases in over 560 milliseconds. Calling
+`setEmphasis(undefined)` eases the map back to its design. Each call supersedes the previous one;
+the promise of a superseded call resolves with `status: 'superseded'`.
+
+## Choose what steps back
+
+- `recede` maps module names to an amount from 0 (as designed) to 1 (the ground colour itself). The
+  modules are the semantic domains a map compiles, such as `roads`, `transit`, `boundaries`,
+  `water`, `land`, `buildings`, and `vegetation`. Every colour of a receding layer moves towards the
+  ground colour, including the colours inside zoom curves and data cases. Artwork that cannot be
+  recoloured, such as a pattern, fades by the same amount instead.
+- `labels` is the share of their opacity that the map's labels and icons keep, from 0 to 1.
+- `keep` is a GeoJSON `Polygon` or `MultiPolygon`. Labels and icons whose features fall inside it
+  keep their full strength. It can hold up to 4,096 positions. A corridor round a route is a
+  typical keep area.
+
+The ground colour is the map's background colour. During a blend it is the blended background, so
+receding colours follow the hour as the blend moves.
+
+## How it changes over time
+
+Values that depend only on the camera, such as a colour or an opacity with a zoom curve, ease every
+frame. A value that MapLibre evaluates per feature, such as a road colour chosen by class or any
+label opacity once a keep area is given, would make MapLibre lay its source out again on every
+change. Such values change once, at the start of the change, under a snapshot of the map that fades
+out as the transition runs. When the browser asks for reduced motion, every change happens at once.
+
+An emphasis stays through `setTheme` and `setBlend`: after a new style is applied, the emphasis is
+written again under the same cross-fade, and each blend position recomputes the receded colours.
+
+## How it finds modules
+
+Every compiled layer names its semantic module in its metadata:
+
+```json
+{"id": "tileflow-road-major-fill", "metadata": {"tileflow:domain": "roads"}}
+```
+
+Layers that a theme blend splits or copies keep the same entry. Applications can read the key from
+`tileflowLayerDomainMetadataKey` in `@tileflow/core/browser`. Physical layer IDs remain diagnostic;
+use the module name instead. Styles compiled before this metadata existed have no module names, so
+an emphasis leaves them unchanged.
+
+## Cost
+
+Each eased frame writes only the values that changed, with `setPaintProperty` and without
+validation. For a detailed city map with roads, transit, and boundaries receding, that is about 150
+values a frame on a desktop computer. Writing values directly is faster than reading a MapLibre
+global state from every value, because a global state change re-evaluates every layer that reads it.

package/docs/native-artifact-profile.md

@@ -0,0 +1,145 @@
+# Validate native artifacts
+
+`@tileflow/core/native-profile` checks a resolved MapLibre style against the static `native-v1`
+artifact profile. It is a build-time entry point, separate from the dependency-free URL helpers in
+`@tileflow/core/native`. Install Core as described in the [package README](../README.md).
+
+This is not a mobile SDK. It does not fetch a manifest, execute a renderer, start a commercial
+session, or qualify Hermes, iOS or Android. A passing result establishes static artifact checks,
+not native pixels, data availability, Hosted access, publication or mobile product availability.
+
+## Check a style
+
+<!-- docs:check -->
+
+```ts
+import {validateTileflowNativeStyle} from '@tileflow/core/native-profile';
+
+const diagnostics = validateTileflowNativeStyle({
+  version: 8,
+  sources: {},
+  layers: [{id: 'background', type: 'background', paint: {'background-color': '#ffffff'}}],
+});
+
+console.log(diagnostics);
+```
+
+The result is an empty array for a style that passes this profile, or bounded structured errors.
+`assertTileflowNativeStyle()` throws `TileflowNativeCompatibilityError` for the same errors.
+Neither function modifies the input. Both enforce the raw input budget, even when given a style
+that was already prepared. Relative resources require the explicit `documentUrl` option
+and resolve against that declaring style; it is not inferred from a browser or Metro address.
+
+Use the [Dev artifact pipeline](https://github.com/tileflow/tileflow-sdk/blob/main/packages/dev/docs/native-artifacts.md)
+for authored maps. It resolves inheritance and semantic modules once, prepares icons and fonts,
+checks every theme and returns a complete generation. Do not call a style validator instead of
+preparing the referenced resources.
+
+## Profile and metadata
+
+The exported `tileflowNativeProfile` targets MapLibre React Native 11.3.10 with Native Android 13.2.0
+and iOS 6.26.0. These are static compatibility targets, not a supported application dependency matrix.
+The wrapper's Style Spec version is 26.2.1. Tileflow retains its existing compiler and parser at
+24.8.5: `native-v1` checks that compiler's vocabulary and the intersection of its recorded Android
+and iOS support. It does not expose every feature of Style Spec 26.2.1 or upgrade the web compiler.
+
+The checker reads the full `sdk-support` and expression metadata from the pinned Style Spec
+package's `dist/latest.json`. Its minified JavaScript exports omit that information. A missing
+expression-support entry, issue link or required native version newer than either selected engine
+is not evidence of support. The metadata source is the
+[pinned specification](https://github.com/maplibre/maplibre-style-spec/blob/v24.8.5/src/reference/v8.json).
+
+`tileflowNativeProfileSchema`, `tileflowNativeDiagnosticSchema`, `tileflowRendererSchema` and
+`tileflowNativeBuildRecordSchema` are strict canonical Zod schemas. The map authoring grammar and
+its generated language JSON are unchanged: renderer selection belongs to build tooling, not maps.
+
+## Included representations and explicit rejections
+
+The profile admits fixed Mercator styles, standard vector/raster/GeoJSON/image sources, compatible
+hillshade and building extrusions, one effective sprite, glyph URLs and complete prepared TTF/OTF
+faces. Paint, layout and expression values must also pass the pinned semantic parser and native
+support metadata. Hillshade and building extrusions do not establish 3D terrain support.
+
+The raw style validator rejects globe or adaptive projection, terrain displacement, sky and global-state extensions,
+unsupported source/layer/property values, legacy stop-function objects, browser contour and PMTiles protocols, local file URLs,
+multiple sprite providers. The existing portable camera/view bounds are preserved; an artifact
+does not configure a native map instance's camera constraints. It does not silently remove
+an unsupported feature or replace a font. An explicit fixed-Mercator property can be omitted in the
+native representation because Native has no GL JS projection controller; this does not change the
+logical map revision.
+
+Dev's `native-lowering-v1` preparation policy explicitly converts a fixed `{type: 'globe'}`
+projection to Native's implicit Mercator before this validator runs. This is a recorded projection
+change, not globe support or visual equivalence. One authored map serves web and native preparation;
+no native-specific Streets definition is used. Preparation adapts only finite `line-cap` and
+`line-dasharray` decisions into constant-property layers. Other unsupported properties have no implicit fallback. The raw validator continues to reject
+unlowered unsupported expressions. See the [preparation contract](https://github.com/tileflow/tileflow-sdk/blob/main/packages/dev/docs/native-artifacts.md)
+for the grammar, expansion limits and pending native visual checks. The lowering checks establish
+per-feature selection and cap/dash values, not global feature draw order. A copied `line-sort-key`
+cannot preserve ordering between simultaneous physical branches; overlapping features may produce
+a different composition even when every property value is retained.
+
+`native-build.json` uses strict schema version 2 and `preparationVersion: 'native-lowering-v1'`.
+Its `transformations` array is ordered by map/theme and binds the input/lowered style hashes,
+projection policy and physical layer spans. The runtime manifest remains version 1. An old v1
+build-record decoder must reject v2 rather than silently ignore the preparation evidence.
+
+Text must use a valid glyph template containing `{fontstack}` and `{range}`, or a complete static
+font stack backed by prepared faces. Native preparation maps each exact OpenType full name to its
+verified TTF/OTF URL. WOFF2 conversion, Unicode-range split providers, dynamic font-stack closure and
+implicit system-font fallback are outside this artifact profile. A fallback name without a prepared
+face fails instead of being silently substituted. The existing font pipeline still owns parsing,
+font selection, content hashes and required licenses.
+
+The `deferFontClosure` option is only for compiler preflight before font preparation. It deliberately
+does not prove text-provider closure. The Dev pipeline always performs the final full validation
+after preparation; external callers must not present a preflight result as a complete artifact check.
+
+## Input and prepared-style budgets
+
+`tileflowNativeProfileLimits` and `validateTileflowNativeStyle()` keep untrusted compiler input at
+**160,000 visited JSON nodes**. Dev applies this gate before lowering. The raw validator has no
+option to borrow the output allowance, and preparation never retries rejected input with a larger
+budget. Exceeding the input bound remains `NATIVE_UNSUPPORTED_STYLE` at the root style pointer.
+
+`tileflowNativePreparedStyleLimits` and `validateTileflowNativePreparedStyle()` use a separate fixed
+ceiling of **540,000 nodes** for the expanded representation. The latter performs the same semantic,
+source, font and URL checks; it does not lower a style, relax unsupported properties or establish
+that the input came from a trusted build. Use it to check prepared artifact JSON, not as the entry
+gate for authoring. Dev uses it after lowering, after font preparation and after generation URL
+retargeting, before writing the output generation.
+
+Both stages use the same traversal. Each object key or array index and each value counts as a
+node. Both retain **8 MiB of serialized UTF-8, depth 64, 128 sources, 4,096 layers, 16 prepared font
+faces and 32 returned errors**. Cycles, getters, sparse arrays, non-JSON values and `toJSON` hooks
+remain invalid. The prepared budget changes only the node allowance; per-decision and per-layer
+expansion limits also remain mandatory.
+
+The measured full Streets family expands from 122,253 to 513,321 nodes for dark and from 122,163 to
+513,231 for light. The 540,000-node ceiling leaves 26,679/26,769 nodes (about 5.2%) of headroom rather
+than multiplying the raw allowance arbitrarily. This accommodates the bounded prepared
+representation, not unbounded growth of custom styles. Prepared font bytes retain the existing
+1 MiB per-face bound; URL, icon and sprite limits retain their owning pipelines' bounds. These are
+validation-work limits, not download, GPU-memory or billing limits.
+
+Allowing the larger prepared representation increases the maximum traversal and parser workload.
+The byte, depth, layer and decision bounds still apply; there is no caller-selected unlimited
+mode. The node traversal stops at its ceiling before JSON serialization and semantic parsing.
+These finite limits are not a latency guarantee for every machine or a substitute for admission
+controls in an application accepting arbitrary artifacts.
+
+## Read diagnostics
+
+Every native diagnostic has `code`, `phase`, `severity`, `path`, `renderer`, `profile`, `message`
+and `suggestion`. `path` is a JSON Pointer into the style; artifact preparation prefixes it with the
+map and theme. Error messages do not include rejected URLs, parser details or credentials. Unsafe
+object-key text is represented by its ancestor pointer.
+
+- `NATIVE_UNSUPPORTED_STYLE`: incompatible style semantics or artifact shape.
+- `NATIVE_UNSUPPORTED_SOURCE`: incompatible source, URL or browser protocol.
+- `NATIVE_FONT_UNAVAILABLE`: missing or incompatible native text-provider closure.
+- `NATIVE_MANIFEST_REQUIRED`: no declaring document URL for relative resources.
+- `NATIVE_RENDERER_UNSUPPORTED`: unavailable renderer/profile or native delivery target.
+
+Dev sessions and CLI commands retain their existing diagnostic envelopes and add the native
+`renderer`/`profile` context. Unchanged web calls do not gain extra diagnostic fields.