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

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

@@ -8,8 +8,9 @@ blend when the application controls the appearance continuously, such as a slide
 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.
+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.
 
 ## Cross-fade a theme change
 
@@ -82,7 +83,8 @@ While a blend is shown, `data-tileflow-theme` names the theme nearest to the pos
 - 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.
+- 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.
@@ -117,6 +119,48 @@ For a detailed city map this takes a few milliseconds on a mid-range phone. Posi
 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:
+
+```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'}}
+      themeTransition={{duration: 450}}
+      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
@@ -124,12 +168,12 @@ MapLibre integration can use it too. Resolve runtime styles from the published m
 `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 {Map as MapLibreMap} from 'maplibre-gl';
 import type {TileflowRuntimeManifestMap} from '@tileflow/core/runtime';
 
 export async function moveThroughTheDay(map: MapLibreMap, manifestMap: TileflowRuntimeManifestMap) {
@@ -152,7 +196,8 @@ export async function moveThroughTheDay(map: MapLibreMap, manifestMap: TileflowR
   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']}
+  // {held: false, position: 0.6, relayoutAt: [...], themes: ['night', 'dusk', 'day']}
+  return controller.getBlend();
 }
 ```
 
@@ -163,3 +208,53 @@ latest wins. A failed change restores the previous appearance and reports `faile
 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`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tileflow/core",
-  "version": "0.1.0-alpha.30",
+  "version": "0.1.0-alpha.32",
   "license": "Apache-2.0",
   "description": "Typed Tileflow config and MapLibre style compiler.",
   "type": "module",