@tileflow/core 0.1.0-alpha.4 → 0.1.0-alpha.41

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

@@ -0,0 +1,317 @@
+# 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 animate a theme change, 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. The React, Vue, and
+Svelte maps offer them with MapLibre GL JS, and the React Native map with MapLibre Native on iOS
+and Android; see [React Native](#react-native) for what differs there.
+
+## Animate a theme change
+
+Theme and `timeOfDay` changes animate over 450 ms by default in React, Vue, and Svelte.
+Pass `themeTransition` to customize the duration. 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} />
+    </>
+  );
+}
+```
+
+Compatible themes interpolate on the live map, including sky, lighting, buildings and vegetation.
+The globe and 3D camera can keep moving throughout the change. Temporary blend layers are removed
+when the destination theme is reached. No image of the previous map is projected over the scene.
+`onThemeChange` reports `preloading`, `applying`, and finally `ready` after the transition.
+
+Structurally different styles, entering a blend, or leaving one use a stationary snapshot while
+the new style loads, then fade it out. Moving the camera removes that cover immediately. A
+`theme="system"` change follows the same rules as an explicit theme selection.
+
+`duration` is in milliseconds, from 0 to 5000. It defaults to 450, including when `themeTransition`
+is omitted or empty. Set `themeTransition={{duration: 0}}` to change 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, using the default or configured transition.
+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;
+  artwork two neighbouring themes share, by name or pixel for pixel, is not uploaded again.
+- 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 stationary
+  cross-fade covers it until the camera moves.
+
+### 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, glyphs, projection, or terrain.
+
+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.
+
+## React Native
+
+The `Map` of `@tileflow/react-native` accepts the same `themeTransition` and `themeBlend` props.
+Theme and `timeOfDay` changes also cross-fade over 450 ms by default:
+
+```tsx
+import {Map} from '@tileflow/react-native';
+
+export function DayMap({position}: {position: number}) {
+  return (
+    <Map
+      source={{map: 'city', manifestUrl: 'https://maps.example.com/tileflow/manifest.json'}}
+      themeBlend={{position, themes: ['night', 'dusk', 'day']}}
+      style={{flex: 1}}
+    />
+  );
+}
+```
+
+A transition covers the drawn map with a snapshot of its current frame, below markers and map
+controls. The snapshot follows the camera and fades out once the new style is drawn.
+`onReadinessChange` and `onThemeChange` report `ready` after the fade. The device's reduce-motion
+setting (iOS) or removed animations (Android) change at once.
+
+A blend loads every blended theme's style once and replaces the map's style once. Position changes
+then apply in batches on the main thread, at most one at a time, and later positions replace any
+that are still waiting. MapLibre Native's style transition smooths values between batches.
+
+What follows the position differs from the browser in a few ways:
+
+- Ground colours and numbers, pattern artwork, and light follow the position. Native maps have no
+  sky.
+- Labels, icons, and switched values change at the nearest theme under a short cross-fade of the
+  whole map. Icon artwork changes by image name instead of mixing pixels, so stretchable images
+  keep their stretch and content areas.
+- A value that depends on feature data and cannot be split by class, such as a road casing chosen
+  by access and zoom together, is drawn once per theme. Only the nearest theme's copy is shown.
+  The map has a few more layers while the blend is shown.
+
+If the application's native build predates these props, for example after an over-the-air
+JavaScript update, themes change at once and a blend shows its nearest theme.
+
+## 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 type {Map as MapLibreMap} from 'maplibre-gl';
+import {createTileflowThemeController} from '@tileflow/core/browser';
+import {
+  resolveTileflowRuntimeStyle,
+  resolveTileflowRuntimeThemeBlend,
+} from '@tileflow/core/runtime';
+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'));
+
+  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});
+  // {held: false, position: 0.6, relayoutAt: [...], themes: ['night', 'dusk', 'day']}
+  return controller.getBlend();
+}
+```
+
+`setTheme` and `setBlend` accept `{transition: {duration}}`;
+`createTileflowThemeController({transition})` overrides the 450 ms default for themes and blends.
+Sun, emphasis, and style-state changes remain immediate unless a transition is configured.
+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.
+
+The controller also shows [map emphasis](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/map-emphasis.md),
+which stays through theme changes and follows every blend position.
+Its [dynamic style images](dynamic-style-images.md) receive theme, blend and declared state inputs
+under one resource owner, with fixed geometry and restoration after a style reload.
+
+## Fast sweeps on slower devices
+
+Each position change makes MapLibre evaluate the paint of every layer whose value changed. A clock
+that moves slowly changes few values per frame, and positions closer than a four-hundredth of a
+theme are skipped. A sweep that crosses a whole theme in a few seconds while the camera also moves
+changes most ground layers on every frame. Measured in Chromium on Apple silicon at 1440 × 900 for
+a detailed city map, such a sweep kept 76 frames a second; with the processor slowed four times, as
+on a mid-range phone, it fell to about 11, against 28 for the same camera move without the sweep.
+On slower devices, prefer short sweeps or move the position less often.
+
+## Camera moves and recordings
+
+Some changes make MapLibre lay tiles out again: when the nearest theme changes, the values that
+switch with it (icon names, layout values, and values that read feature data or feature state),
+and each step of pattern or icon artwork that is mixed in pixels. A camera move or a screen
+recording shows that work as dropped frames. `getBlend().relayoutAt` lists the positions where the
+nearest theme changes over such values, so a sequence can be planned around them.
+
+Pass `hold: true` to hold that work back. Colours, numbers, the sky, and light keep following the
+position; the nearest theme, the values that switch with it, and mixed artwork wait.
+`getBlend().held` reports whether anything waits. The next request without `hold` brings it in at
+once, so make it while the camera rests:
+
+```ts
+import type {TileflowThemeController} from '@tileflow/core/browser';
+import type {TileflowRuntimeStyle} from '@tileflow/core/runtime';
+
+export async function duskWhileFlying(
+  controller: TileflowThemeController,
+  themes: readonly TileflowRuntimeStyle[],
+  flight: Promise<void>,
+) {
+  // Through the camera move the ground darkens towards night with no layout work.
+  for (const position of [0.25, 0.5, 0.75])
+    await controller.setBlend({hold: true, position, themes});
+  await flight;
+  // The camera rests: labels, icons, and artwork follow at once.
+  await controller.setBlend({position: 0.75, themes});
+}
+```
+
+The React, Vue, and Svelte maps take the same flag in `themeBlend`: pass
+`themeBlend={{hold: true, position, themes}}` while the camera moves and drop `hold` when it rests.
+The React Native `Map` blends natively and does not take `hold`.
+
+## Time of day
+
+`timeOfDay` is an optional map capability. It maps a theme and an artistic preset (`day`,
+`dawn`, `dusk`, `night`) to a complete theme already in `themes`:
+
+<!-- docs:check -->
+
+```ts
+import {defineMap} from '@tileflow/core';
+import {streets, streetsThemes} from '@tileflow/maps';
+
+export default defineMap({
+  id: 'city',
+  version: 1,
+  extends: streets,
+  themes: {
+    paper: streetsThemes.light,
+    sunrise: streetsThemes.dawn,
+    evening: streetsThemes.dusk,
+    ink: streetsThemes.dark,
+  },
+  defaultTheme: 'paper',
+  systemThemes: {light: 'paper', dark: 'ink'},
+  timeOfDay: {
+    paper: {day: 'paper', dawn: 'sunrise', dusk: 'evening', night: 'ink'},
+  },
+});
+```
+
+Applications keep `theme` and optionally add `timeOfDay`: `theme="paper" timeOfDay="dusk"`
+selects `evening`. Compilation supports `createStyle(map, {theme: 'paper', timeOfDay: 'dusk'})`;
+`resolveTileflowRuntimeTheme(map, theme, colorScheme, timeOfDay)` uses the same resolution.
+Omitting the preset preserves the existing selection. `system` resolves its light/dark theme
+first. A concrete variant such as `ink` also identifies its family when a preset is supplied.
+Maps or themes without a family ignore this option. Within a declared family, an unavailable
+preset is an error; controls should offer only declared presets. Families must include their own
+name in their presets, and a concrete theme can belong to only one family.
+
+The catalog inherits atomically; `timeOfDay: {}` disables it on an extension. Replacing `themes`
+clears an inherited catalog. `defaultTheme`, `systemThemes`, and `themeTransition` retain their
+behavior. An explicit `themeBlend` owns its concrete theme sequence and takes precedence over
+`timeOfDay`. Changing the preset does not start a clock or call `setSun`; lighting is whatever the
+selected theme already declares, and an application's sun override retains its existing behavior.
+Captures, style URLs, and transition events use the resolved concrete theme name.
+
+Maps with a catalog publish runtime manifest version 2. Updated browser and native readers accept
+both versions. Old readers need a version 1 manifest: `createManifest(project, {manifestVersion: 1})`
+omits the catalog and keeps every concrete theme available. Maps without a catalog still emit
+version 1. Update readers before delivering a version 2 manifest.

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

@@ -0,0 +1,156 @@
+# 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.
+
+## Start with one appearance
+
+A map can have one appearance for its entire lifetime. Neither `systemThemes` nor `timeOfDay` is
+required. This complete theme supplies the twelve base color roles the semantic compiler needs;
+copy it and change its colors to start an independent design without inheriting an official map:
+
+<!-- docs:check -->
+
+```ts
+import {defineTheme} from '@tileflow/core';
+
+export const paper = defineTheme({
+  id: 'paper',
+  version: 1,
+  colorScheme: 'light',
+  tokens: {
+    color: {
+      'surface.background': '#F6F7F3',
+      'surface.land': '#F1F3ED',
+      'surface.water': '#A9D3F5',
+      'surface.park': '#CDE8B5',
+      'surface.building': '#E6E3DA',
+      'roads.default': '#FFFFFF',
+      'roads.major': '#F4C95D',
+      'roads.casing': '#D9DEE2',
+      'boundaries.default': '#C9D1D9',
+      'labels.primary': '#3C4043',
+      'labels.muted': '#727B84',
+      'labels.halo': '#FFFFFF',
+    },
+  },
+});
+```
+
+An existing map definition can select this appearance with `themes: {paper}` and
+`defaultTheme: 'paper'`. Supply that map's data and font assets separately; the default typography
+uses `Noto Sans Regular`. A theme without these base roles is a valid appearance document but cannot
+compile a semantic map. Colors above are an editable starting point, including for monochrome,
+historical, dark-only, or imagined worlds; `colorScheme` describes the appearance for consumers and
+does not generate a palette or choose a time of day.
+
+The compiler derives more specific roles when they are absent. For example, primary and motorway
+roads initially use `roads.major`; declaring `roads.motorway` replaces only that derived color.
+Land-use fills, road casings, and label colors have their own semantic roles, so an explicit role
+always wins over its fallback. Use `color.mix()` and `token.color()` in a theme when the relationship
+itself should be authored and inspectable. Derivations resolve during compilation, without a clock
+or a per-frame palette calculation.
+
+Add named appearances when the map needs them. A day/night pair does not need dawn or dusk, and a
+theme named `paper` or `fantasy` does not need a temporal family. Declare `timeOfDay` only when the
+application should offer those artistic moments; see
+[time-of-day selection](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/theme-transitions-and-blends.md#time-of-day).
+
+## Compose and replace appearance values
+
+Some optional tokens are for the application rather than the map's own layers. Route inks
+(`route.line`, `route.casing`, `route.core`, `route.glow`, `route.alternative`,
+`route.glow.opacity` and `route.core.opacity`) set how an application draws its routes; a theme
+without them uses its colour scheme's defaults. The compiler publishes them in the style's metadata
+and the theme controller returns them; see
+[route drawing](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/route-drawing.md).
+
+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.
+
+Theme lighting also supports explicit removal during `defineTheme` composition. Use
+`lighting: reset()` to remove the entire inherited lighting configuration, or
+`lighting: {sun: reset(), ambient: reset()}` to remove those presets while retaining other light
+properties. The same operation can remove a direct property such as `position` or `color`.
+Omitting a property, or supplying an empty object, continues to inherit it. Reset operations are
+materialized immediately and never enter the resolved theme or Style JSON. Removing a lighting
+preset restores the renderer's fallback; it does not disable 3D shadows or occlusion. Those remain
+explicit building settings. See
+[sun and light](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/sun-and-light.md#replace-inherited-lighting)
+for a complete example.
+
+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.