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

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

@@ -1,317 +0,0 @@
-# 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

@@ -1,156 +0,0 @@
-# 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.