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

package/docs/public-api-and-browser-subpath.md

@@ -0,0 +1,93 @@
+# Public API and browser subpath
+
+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.
+
+Config, data, modules, compilation, validation, runtime resolution, and capture-scene APIs remain
+available from the package root. Capture scenes, manifests, and browser-runtime surfaces also have
+explicit `@tileflow/core/capture`, `@tileflow/core/manifest`, and `@tileflow/core/runtime`
+subpaths. Node build integrations import the small deterministic map-identity contract from
+`@tileflow/core/build`: `collectTileflowMapBuildLineage`, `createTileflowMapBuildManifest`,
+`hashTileflowMapRevision`, `hashTileflowAssetSet`, and `hashTileflowAssetSetIdentities`. The latter
+reproduces the same asset-set v1 hash from exact per-file identities after another system has
+independently confirmed the immutable bytes; package or bundle hashes are not substitutes. The
+previous aggregate-wrapper and recipe-selector APIs, `renderer`, top-level `tiles`/`tileset`, module
+arrays, and top-level raw `layers` are not part of this API. Raw MapLibre layers are accepted only
+inside a named `maplibreOverlay()` bound to a named Team source.
+
+Advanced cartography remains in the same public language: `withRenderStack()`, `renderPass()`, and
+`refineRenderTarget()` address owner-local semantic targets without exposing physical layer IDs,
+sources, source layers, raw filters, or before/after anchors. Typed `field()` references and
+`expr.*` builders stay semantic until the compiler's single lowering boundary. There is no recipe
+subpath or alternate compiler integration API.
+
+`mapRevisionSha256` hashes only resolved cartography: the effective design after `extends`, the
+semantic language, compiler-owned effective contributions, and exact source icon/font identities.
+Leaf `id`, `name`, editorial `mapVersion`, default `view`, capture `scenes`, and `delivery` policy do
+not change that content identity. They remain explicit on the map, manifest, Style, capture receipt,
+or Hosted deployment fingerprint that owns them. Compiler ABI, package versions, generated assets,
+and the concrete release selected by World `current` likewise have separate identities.
+
+Runtime manifest version 1 has one shape for local and Hosted delivery. Every map entry owns
+`defaultTheme`, optional `systemThemes`, and a `themes` record whose leaves contain
+`colorScheme`, `styleUrl`, and optional font/deployment identity. Hosted-only identity is additive
+metadata on the same map entry; there is no delivery discriminator or parallel `styles` alias.
+`parseTileflowRuntimeManifest()` accepts only this canonical shape. The strict bounded schema uses
+the same portable map and theme IDs as authoring, rejects `system` as a published name, duplicate
+font identities, unsafe owner-relative URLs, prototype-bearing input, unknown fields, and JSON
+larger than 1 MiB.
+
+```json
+{
+  "version": 1,
+  "maps": {
+    "madrid": {
+      "defaultTheme": "light",
+      "systemThemes": {"light": "light", "dark": "dark"},
+      "themes": {
+        "light": {"colorScheme": "light", "styleUrl": "/styles/madrid/light.json"},
+        "dark": {"colorScheme": "dark", "styleUrl": "/styles/madrid/dark.json"}
+      }
+    }
+  }
+}
+```
+
+Runtime fetches share a successful result for 30 seconds, never cache failures, use
+`cache: 'no-store'`, enforce a 10-second timeout (configurable up to 60 seconds), compose an
+external abort signal, and can be invalidated with `clearTileflowManifestCache()`.
+
+Named map `view` values travel in the manifest. `resolveTileflowRuntimeTheme()` turns an omitted,
+explicit, or `system` request with a supplied color scheme into one concrete published entry;
+unknown names fail closed. `resolveTileflowRuntimeView()` defines the shared precedence as explicit
+runtime values, then the manifest view, then the single exported `defaultTileflowRuntimeView`
+(`[0, 20]`, zoom 2, bearing/pitch 0).
+
+`TileflowRuntimeSource` is one object, `{map, manifestUrl?}`, selecting a named Tileflow map only
+through its published manifest. React, Vue and Svelte share that source contract. Omitting the URL
+means exactly `/tileflow/manifest.json`; other locations must be explicit. The native Core contract
+uses `{map, manifestUrl}` with a required absolute URL and no discovery, as described in the
+[native guide](native-resource-urls.md). The React Native type contract preserves that requirement.
+No public framework Map source exposes a renderer discriminator or direct-style branch. The obsolete
+`kind` and `style` fields are rejected; completely unmanaged maps use upstream MapLibre directly.
+The runtime subpath does not import the config compiler, invent a localhost style URL, or change
+image mode by environment.
+
+Framework adapters import the browser-only lifecycle kernel explicitly:
+
+```ts
+import {
+  attachTileflowAtmosphere,
+  attachTileflowFairUseNotice,
+  attachTileflowMapLifecycle,
+  createTileflowSessionStarter,
+  createTileflowTransformRequest,
+  registerTileflowWorldRequestBridge,
+} from '@tileflow/core/browser';
+```
+
+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](https://github.com/tileflow/tileflow-sdk/blob/main/docs/contracts/framework-browser-runtime.md) and the
+[cartographic authoring contract](https://github.com/tileflow/tileflow-sdk/blob/main/docs/contracts/cartographic-authoring.md). Exact field
+resolution and asset rules live in the
+[map inheritance contract](https://github.com/tileflow/tileflow-sdk/blob/main/docs/contracts/map-inheritance.md).

package/docs/shared-visual-primitives.md

@@ -0,0 +1,81 @@
+# Shared visual primitives
+
+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 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:
+
+- `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, exact font face, exact fallback faces, size, color, halo, line-fitted
+  background, 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.
+
+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.
+
+## Line-fitted text backgrounds
+
+`text.background` draws one opaque strip behind each shaped line of a label, fitted to that line's
+own width. Use it for captions whose lines differ in length, where a stretched icon plate
+(`icon.textFit`) would cover the whole block.
+
+<!-- docs:check -->
+
+```ts
+import {fixed, poi, zoom} from '@tileflow/core';
+
+export const captions = poi({
+  categories: ['arts-entertainment'],
+  styles: {
+    'arts-entertainment': {
+      text: {
+        background: {
+          color: fixed('#080E11', {reason: 'Caption strip'}),
+          fit: 'lines',
+          padding: 0.33,
+        },
+        color: fixed('#ECEEE9', {reason: 'Caption text'}),
+        font: fixed('Noto Sans Bold', {reason: 'Caption face'}),
+        letterSpacing: fixed(0.08, {reason: 'Caption tracking'}),
+        lineHeight: fixed(1.2, {reason: 'Caption leading'}),
+        size: zoom.linear([
+          [14, 11],
+          [18, 14],
+        ]),
+      },
+    },
+  },
+});
+```
+
+Tileflow lowers the background to MapLibre properties only. `text-font` becomes a derived stack,
+such as `Noto Sans Bold lines-v1-t80-l1200-p330`. Its glyphs keep the source advances and shapes and
+add a rectangular cell, which the text halo paints. The halo width tracks `text-size / 6`, including
+zoom curves. Shaping, wrapping, collision, variable anchors, fading and right-to-left text therefore
+stay native, and the compiled style needs no runtime extension.
+
+- The colour must be opaque. Neighbouring cells overlap where they join.
+- `font` must name one stack served by the map's `glyphs` provider, without `fallbacks`. Maps that
+  use browser-rendered `fonts` reject backgrounds.
+- `letterSpacing` and `lineHeight` must be constants. The derived stack encodes them in thousandths
+  of an em, and the layer uses those rounded values. Tracking runs from 0 to 0.5em, leading from 0.8
+  to 3 and padding from 0 to 1em.
+- The background replaces the text halo. While a background is active, `haloWidth` and `haloBlur`
+  are derived, and `haloColor` is the strip colour. Later refinements of size, tracking, leading or
+  font re-derive the stack and halo.
+- Collision still reserves the shaped block. Padding beyond it is drawn outside that box, so keep
+  `padding` (text padding) at least as large as the strip padding in pixels.
+
+The map's `glyphs` provider must serve derived stacks. `deriveTileflowLineBackgroundGlyphs`
+computes any range from the source stack's range, and `parseTileflowLineBackgroundFontStack`
+recognises derived requests. Local previews and captures derive ranges themselves; hosted and
+self-hosted providers must do the same.

package/docs/theme-transitions-and-blends.md

@@ -0,0 +1,165 @@
+# Theme transitions and blends
+
+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.
+
+A Tileflow map can change theme with a cross-fade, or show any point between two or more of its
+themes. Use a transition when people switch between appearances, such as light and dark. Use a
+blend when the application controls the appearance continuously, such as a slider or a day that
+passes from night to day.
+
+Both work on the one MapLibre map the application already has. They create no second map, add no
+map views, and request the same tiles as a map that does not change theme. They need a browser
+document and MapLibre GL JS; the React Native package does not offer them.
+
+## Cross-fade a theme change
+
+Pass `themeTransition` to the React, Vue, or Svelte map. This React example assumes a map named
+`city` with `light` and `dark` themes in the published manifest:
+
+```tsx
+import {Map} from '@tileflow/react';
+import {useState} from 'react';
+
+export function CityMap() {
+  const [theme, setTheme] = useState<'dark' | 'light'>('light');
+  return (
+    <>
+      <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>Switch theme</button>
+      <Map source={{map: 'city'}} theme={theme} themeTransition={{duration: 450}} />
+    </>
+  );
+}
+```
+
+When the theme changes, a snapshot of the current frame covers the map. The snapshot follows the
+camera while people pan, zoom, rotate, or tilt, and fades out once the new theme is drawn. The map
+stays interactive throughout. `onThemeChange` reports `preloading`, `applying`, and finally `ready`
+after the fade. A `theme="system"` change, entering a blend, and leaving one use the same
+transition.
+
+`duration` is in milliseconds, from 0 to 5000. It defaults to 0, which changes the theme at once.
+When the browser asks for reduced motion, every change happens at once.
+
+## Blend themes
+
+Pass `themeBlend` with the themes to blend, in order, and a `position` between them. Position 0
+shows the first theme, 1 the second, and 1.25 a quarter of the way from the second to the third:
+
+```tsx
+import {Map} from '@tileflow/react';
+import {useState} from 'react';
+
+export function DayMap() {
+  const [position, setPosition] = useState(0);
+  return (
+    <>
+      <input
+        aria-label="Time of day"
+        max={2}
+        min={0}
+        onChange={(event) => setPosition(Number(event.target.value))}
+        step={0.01}
+        type="range"
+        value={position}
+      />
+      <Map source={{map: 'city'}} themeBlend={{position, themes: ['night', 'dusk', 'day']}} />
+    </>
+  );
+}
+```
+
+The first blend of a set of themes loads each theme's style and fonts, prepares one style that
+holds every theme, and replaces the map's style once, with `themeTransition` if set. Until then the
+map shows the theme nearest to the position. After that, changing `position` updates the map at
+once without loading anything, so it can follow a slider, a clock, or an animation frame by frame.
+Changing `themes` prepares a new blend. Removing `themeBlend` returns to `theme`.
+
+While a blend is shown, `data-tileflow-theme` names the theme nearest to the position.
+`onThemeChange` reports the preparation of a blend; moving its position reports nothing.
+
+### What follows the position
+
+- Colours and numbers of the ground, such as land, water, roads, buildings, and their widths and
+  opacities, follow the position continuously. Colours mix in the OKLab colour space, so halfway
+  between two themes looks halfway to the eye.
+- Patterns, the sky, and light follow the position too. Pattern artwork is mixed in its pixels.
+- Labels, icons, and other symbols change when the nearest theme changes, with a short cross-fade.
+  Light lettering on a dark plate and dark lettering on a light plate would meet in the same grey
+  halfway, so symbols do not follow the position.
+- A value that depends on feature state, such as a caption that changes colour when highlighted,
+  changes with the nearest theme. MapLibre lays its source out again for that change; a cross-fade
+  covers it.
+
+### Which themes can be blended
+
+Blend themes of the same map. Every theme of a map exposes the same token keys, so its compiled
+styles share sources, layers, filters, and expressions, and differ only in colours, numbers, and
+image names. Up to eight themes can be blended. A blend fails, and the map keeps its current
+appearance, when the styles differ in structure, sources, sprite, or glyphs.
+
+Icon and pattern artwork is mixed in place of the first theme's image when every theme's version
+has the same size. Otherwise that image changes with the nearest theme instead.
+
+### Cost
+
+The prepared style holds every theme. A value that depends on feature data, such as a land-use
+colour chosen by class, becomes one layer per class while the blend is shown, so the prepared
+style has more layers than one theme. Physical layer IDs are diagnostic, not stable; semantic
+interactions are not affected.
+
+Entering a blend replaces the map's style once. MapLibre then takes about as long as it takes to
+load the map: for a detailed city map, around half a second on a desktop computer and longer on a
+phone, while the transition snapshot, if any, covers the map. Start a blend before people need it
+to move, for example when the map loads.
+
+Each position change after that sets the map's themed values directly, without expression parsing.
+For a detailed city map this takes a few milliseconds on a mid-range phone. Positions closer than a
+four-hundredth of a theme are not applied, so a slowly moving position leaves the map at rest
+between changes.
+
+## Use the core controller
+
+Framework adapters use `createTileflowThemeController` from `@tileflow/core/browser`. A direct
+MapLibre integration can use it too. Resolve runtime styles from the published manifest with
+`resolveTileflowRuntimeStyle` and `resolveTileflowRuntimeThemeBlend` from `@tileflow/core/runtime`:
+
+```ts
+import {createTileflowThemeController} from '@tileflow/core/browser';
+import {
+  resolveTileflowRuntimeStyle,
+  resolveTileflowRuntimeThemeBlend,
+} from '@tileflow/core/runtime';
+import type {Map as MapLibreMap} from 'maplibre-gl';
+import type {TileflowRuntimeManifestMap} from '@tileflow/core/runtime';
+
+export async function moveThroughTheDay(map: MapLibreMap, manifestMap: TileflowRuntimeManifestMap) {
+  const source = {map: 'city'};
+  const styleOf = (theme: string) => {
+    const style = resolveTileflowRuntimeStyle({manifestMap, source, theme});
+    if (!style) throw new Error(`The manifest has no ${theme} theme for ${source.map}.`);
+    return style;
+  };
+  // `initial` is the runtime style the map was created with.
+  const controller = createTileflowThemeController({initial: styleOf('day'), map});
+
+  await controller.setTheme(styleOf('night'), {transition: {duration: 450}});
+
+  const themes = resolveTileflowRuntimeThemeBlend({
+    blend: {position: 0, themes: ['night', 'dusk', 'day']},
+    manifestMap,
+    source,
+  });
+  await controller.setBlend({position: 0.5, themes});
+  // The same themes: the position applies at once.
+  await controller.setBlend({position: 0.6, themes});
+  return controller.getBlend(); // {position: 0.6, themes: ['night', 'dusk', 'day']}
+}
+```
+
+`setTheme` and `setBlend` accept `{transition: {duration}}`;
+`createTileflowThemeController({transition})` sets a default. Requests are serialized and the
+latest wins. A failed change restores the previous appearance and reports `failed` with its error.
+
+The controller loads blended themes' style documents with the same request policy it uses for
+style font metadata: same-origin credentials, no redirects, and a bounded size. Pass `loadStyle`
+when styles need another loader.

package/docs/themes-and-module-styles.md

@@ -0,0 +1,83 @@
+# Themes and module styles
+
+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.
+
+A map declares complete named appearances in `themes`, chooses one deterministic
+`defaultTheme`, and may map the browser's light/dark preference through `systemThemes`. `system` is
+never a compiled theme name: it is a runtime request that resolves immediately to one concrete
+name. Disk builds write `styles/<map>/<theme>.json` beneath their output root. Public and
+content-addressed Style URLs belong to the runtime manifest and may include a deployment prefix;
+capture scenes and receipts store the concrete name rather than `system`.
+
+Themes are flat, JSON-safe documents with `colorScheme`, identity, typography, lighting, and four
+typed token catalogs: `color`, `font`, `image`, and `number`. Every theme on one map must expose the
+same token keys, so changing a theme can never change map structure or silently lose a semantic
+role. `defineTheme(base, definition)` is an authoring convenience that returns a fully materialized
+document; it does not leave an inheritance edge in the resolved config.
+
+The key in the `themes` record is its concrete runtime selector and output-path segment. The
+theme's own `id` and `version` are its editorial identity and build provenance, so they need not
+equal that key. Concrete keys may be names such as `day` and `night`; every `systemThemes.light` or
+`systemThemes.dark` value must name an existing theme whose `colorScheme` matches that branch.
+
+```ts
+import {color, defineMap, defineTheme, fixed, roads, token} from '@tileflow/core';
+import {streets, streetsThemes} from '@tileflow/maps';
+
+const dark = defineTheme(streetsThemes.dark, {
+  id: 'company-dark',
+  version: 1,
+  colorScheme: 'dark',
+  tokens: {
+    color: {
+      'surface.land': '#101722',
+      'labels.primary': color.mix('#eef3fb', token.color('surface.background'), {amount: 0.08}),
+    },
+  },
+});
+
+export default defineMap({
+  id: 'company',
+  version: 1,
+  extends: streets,
+  themes: {light: streetsThemes.light, dark},
+  defaultTheme: 'light',
+  systemThemes: {light: 'light', dark: 'dark'},
+  modules: {
+    roads: roads({
+      classes: {
+        primary: {
+          surface: {
+            fill: {
+              color: fixed('#ff2d78', {reason: 'Regulatory primary-road ink is invariant'}),
+            },
+          },
+        },
+        secondary: {
+          surface: {
+            fill: {
+              color: token.color('roads.secondary'),
+            },
+          },
+        },
+      },
+    }),
+  },
+});
+```
+
+Semantic modules own structure and behavior; visual fields accept typed token references.
+Use a visual literal only inside a theme. If a module value intentionally must not vary, wrap it in
+`fixed(value, {reason})`. `tileflow inspect --json` reports stable `THEME_IMPLICIT_FIXED`
+diagnostics: implicit color, font, and image literals block Style compilation, while direct visual
+number literals are warnings so an agent can document their invariance deliberately. Structural
+numbers such as zoom bounds and ranks are not visual-theme diagnostics. `color.alpha()` and
+deterministic OKLCH `color.mix()` keep derived palette logic inspectable. Unknown refs, cycles,
+cross-category refs, token-schema drift, and unresolved visual nodes fail before Style JSON is
+emitted.
+
+There is no physical-layer override for the Tileflow basemap or separate official-map authoring
+surface. Basemap behavior belongs to a typed control or owner-local render stack. Every
+official and application map therefore follows the same schema, inheritance rules, diagnostics,
+and lowering path. `createStyle()` validates the final planned Style JSON with the MapLibre style
+spec and never returns an invalid style.

package/package.json

@@ -1,16 +1,18 @@
 {
   "name": "@tileflow/core",
-  "version": "0.1.0-alpha.3",
+  "version": "0.1.0-alpha.30",
+  "license": "Apache-2.0",
   "description": "Typed Tileflow config and MapLibre style compiler.",
   "type": "module",
+  "sideEffects": false,
   "homepage": "https://tileflow.dev",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/tileflow/tileflow.git",
+    "url": "git+https://github.com/tileflow/tileflow-sdk.git",
     "directory": "packages/core"
   },
   "bugs": {
-    "url": "https://github.com/tileflow/tileflow/issues"
+    "url": "https://github.com/tileflow/tileflow-sdk/issues"
   },
   "keywords": [
     "tileflow",
@@ -22,25 +24,73 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "docs",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md"
   ],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
-    }
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "import": "./dist/browser.js",
+      "default": "./dist/browser.js"
+    },
+    "./build": {
+      "types": "./dist/build.d.ts",
+      "import": "./dist/build.js",
+      "default": "./dist/build.js"
+    },
+    "./capture": {
+      "types": "./dist/capture.d.ts",
+      "import": "./dist/capture.js",
+      "default": "./dist/capture.js"
+    },
+    "./config-reference.json": "./dist/config-reference.json",
+    "./manifest": {
+      "types": "./dist/manifest.d.ts",
+      "import": "./dist/manifest.js",
+      "default": "./dist/manifest.js"
+    },
+    "./native": {
+      "types": "./dist/native.d.ts",
+      "import": "./dist/native.js",
+      "default": "./dist/native.js"
+    },
+    "./native-profile": {
+      "types": "./dist/native-profile.d.ts",
+      "import": "./dist/native-profile.js",
+      "default": "./dist/native-profile.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime.d.ts",
+      "import": "./dist/runtime.js",
+      "default": "./dist/runtime.js"
+    },
+    "./package.json": "./package.json"
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
+    "@maplibre/maplibre-gl-style-spec": "24.8.5",
     "zod": "^4.4.3"
   },
+  "devDependencies": {
+    "maplibre-contour": "0.1.0",
+    "pmtiles": "4.4.0",
+    "whatwg-url": "15.1.0"
+  },
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts --clean",
-    "verify": "tsx scripts/verify.ts",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "build": "tsup --config tsup.build.config.ts && tsup --config tsup.native-profile.config.ts && tsup src/browser.ts --format esm --dts --no-splitting --platform browser && tsup --config tsup.native.config.ts && cp ../../docs/modules-api-reference.json dist/config-reference.json",
+    "reference:check": "tsx scripts/generate-config-reference.ts --check",
+    "reference:generate": "tsx scripts/generate-config-reference.ts --write",
+    "verify": "pnpm run build && tsx --test test/*.test.ts",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.contract.json",
     "lint": "tsc -p tsconfig.json --noEmit"
   }
 }