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

package/README.md

@@ -139,12 +139,18 @@ export default defineMap({
 `system` is a runtime selection policy, not a stored theme. Builds, captures, static scenes, and
 receipts must use a concrete theme such as `light` or `dark`.
 
+Because every theme of a map shares one structure, a browser map can cross-fade between themes or
+show a continuous blend of them on the same MapLibre instance, with no extra requests. See
+[theme transitions and blends](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/theme-transitions-and-blends.md).
+
 The semantic domains are `land`, `water`, `nautical`, `roads`, `buildings`, `boundaries`, `labels`,
 `poi`, `aeroways`, `transit`, `vegetation`, `addresses`, and `landforms`. Style stable geographic
 targets rather than compiler-generated MapLibre layer IDs. Shared primitives cover fills, lines,
 text, icons, circles, and extrusions. `zoom.*` supplies zoom curves; `expr.*` and `field(...)` supply
 the closed data-expression language. `renderPass`, `refineRenderTarget`, and `withRenderStack` add
-owner-local rendering behavior without bypassing the compiler.
+owner-local rendering behavior without bypassing the compiler. A pass, or a target its module moves,
+is placed at a band edge such as `'above-relief'` or `'below-labels'`, or `{above}` / `{below}` one
+semantic target.
 
 ## Compile and inspect
 
@@ -255,6 +261,7 @@ revision; prefer the installed copy when working with an older release.
 - [Shared visual primitives](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/shared-visual-primitives.md)
 - [Compiled-style performance](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/compiled-style-performance.md)
 - [Themes and module styles](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/themes-and-module-styles.md)
+- [Theme transitions and blends](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/theme-transitions-and-blends.md)
 - [Data is separate from design](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/data-is-separate-from-design.md)
 - [Capture scenes](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/capture-scenes.md)
 - [Public API and browser subpath](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/public-api-and-browser-subpath.md)

package/dist/browser.d.ts

@@ -94,6 +94,27 @@ type TileflowStyleFontFace = {
     weight?: '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900';
 };
 
+/**
+ * Browser helpers for theme transitions and blends. They use only methods that MapLibre GL JS maps
+ * provide and check each one at runtime, so a map without them falls back to an immediate change.
+ */
+type TileflowThemeMotionMap = {
+    areTilesLoaded?: unknown;
+    getCanvas?: unknown;
+    getImage?: unknown;
+    isStyleLoaded?: unknown;
+    off(event: string, listener: (event?: unknown) => void): unknown;
+    on(event: string, listener: (event?: unknown) => void): unknown;
+    project?: unknown;
+    redraw?: unknown;
+    setLayoutProperty?: unknown;
+    setLight?: unknown;
+    setPaintProperty?: unknown;
+    setSky?: unknown;
+    unproject?: unknown;
+    updateImage?: unknown;
+};
+
 /** Structural MapLibre capabilities; importing this module never loads a renderer. */
 type TileflowAtmosphereMap = {
     getBearing(): number;
@@ -178,15 +199,51 @@ type TileflowThemeTransitionResult = Readonly<{
     status: 'applied' | 'failed' | 'superseded';
     theme?: string;
 }>;
-type TileflowStyleSwitchMap = {
-    off(event: 'error' | 'style.load', listener: (event?: unknown) => void): unknown;
-    on(event: 'error' | 'style.load', listener: (event?: unknown) => void): unknown;
+/**
+ * How a theme change appears. With a `duration`, the map cross-fades from the previous theme to
+ * the new one: a snapshot of the previous frame covers the map, follows the camera, and fades out
+ * once the new theme is drawn. A browser preference for reduced motion changes at once.
+ */
+type TileflowThemeTransitionOptions = Readonly<{
+    /** Cross-fade length in milliseconds, from 0 (the default, an immediate change) to 5000. */
+    duration?: number;
+}>;
+type TileflowThemeChangeOptions = Readonly<{
+    transition?: TileflowThemeTransitionOptions;
+}>;
+/**
+ * A continuous mix of two or more themes of the same map. `position` places the map between
+ * neighbouring themes: 0 is the first, 1 the second, and 1.25 a quarter of the way from the second
+ * to the third. Ground colours, patterns, the sky, and light follow the position; labels and icons
+ * cross-fade when the nearest theme changes.
+ */
+type TileflowThemeBlendRequest = Readonly<{
+    position: number;
+    /** Two to eight concrete themes of one map, in blend order. */
+    themes: readonly TileflowRuntimeStyle[];
+}>;
+type TileflowThemeBlendState = Readonly<{
+    position: number;
+    themes: readonly string[];
+}>;
+type TileflowStyleSwitchMap = TileflowThemeMotionMap & {
+    off(event: string, listener: (event?: unknown) => void): unknown;
+    on(event: string, listener: (event?: unknown) => void): unknown;
     setStyle: unknown;
 };
 type TileflowThemeController = {
     dispose(): void;
+    /** The active blend, or undefined when the map shows one theme. */
+    getBlend(): TileflowThemeBlendState | undefined;
+    /** The theme the map shows; during a blend, the nearest theme. */
     getCurrent(): TileflowRuntimeStyle;
-    setTheme(style: TileflowRuntimeStyle): Promise<TileflowThemeTransitionResult>;
+    /**
+     * Shows a blend of themes. The first request for a set of themes loads their styles and
+     * prepares one style that holds all of them; later requests for the same themes only move the
+     * position and take effect at once, so they can follow an animation or a slider.
+     */
+    setBlend(request: TileflowThemeBlendRequest, options?: TileflowThemeChangeOptions): Promise<TileflowThemeTransitionResult>;
+    setTheme(style: TileflowRuntimeStyle, options?: TileflowThemeChangeOptions): Promise<TileflowThemeTransitionResult>;
 };
 /**
  * Transactionally changes a MapLibre style while preserving the map instance and camera.
@@ -195,9 +252,13 @@ type TileflowThemeController = {
 declare function createTileflowThemeController(options: {
     initial: TileflowRuntimeStyle;
     loadFonts?: (style: TileflowRuntimeStyle) => Promise<void>;
+    /** Loads a theme's style document for a blend; defaults to a same-origin-credentials fetch. */
+    loadStyle?: (url: string) => Promise<MapLibreStyle>;
     map: TileflowStyleSwitchMap;
     onTransition?: (transition: TileflowThemeTransition) => void;
     timeoutMs?: number;
+    /** The default for every change; each change may pass its own. */
+    transition?: TileflowThemeTransitionOptions;
 }): TileflowThemeController;
 type TileflowMapLifecycleEvent = 'dataloading' | 'error' | 'idle' | 'load' | 'styledataloading';
 type TileflowFrameScheduler<TFrame> = {
@@ -270,4 +331,4 @@ declare function createTileflowTransformRequest<TRequest extends TileflowTransfo
     worldRequestBridge?: TileflowWorldRequestBridge;
 }): TileflowTransformRequest<TRequest, TResourceType> | undefined;
 
-export { type TileflowAsyncAnalyticsTiming, type TileflowAtmosphereMap, type TileflowComposedRequest, type TileflowContourProtocolHandler, type TileflowContourProtocolRegistrationOptions, type TileflowContourProtocolRegistry, type TileflowContourProtocolRequest, type TileflowContourProtocolResponse, type TileflowFairUseNotice, type TileflowFairUseNoticeController, type TileflowFairUseNoticeState, type TileflowFrameScheduler, type TileflowMapLifecycleAttachment, type TileflowMapLifecycleEvent, type TileflowMapLifecycleSubscriber, type TileflowMapReadinessState, type TileflowPmtilesProtocolHandler, type TileflowPmtilesProtocolRegistrationOptions, type TileflowPmtilesProtocolRegistry, type TileflowSessionSender, type TileflowSessionStarter, type TileflowStyleFontLoadOptions, type TileflowStyleSwitchMap, type TileflowThemeController, type TileflowThemeTransition, type TileflowThemeTransitionPhase, type TileflowThemeTransitionResult, type TileflowTransformRequest, type TileflowTransformRequestParameters, type TileflowUserTransformRequest, type TileflowWorldProtocolHandler, type TileflowWorldProtocolRequest, type TileflowWorldProtocolResponse, type TileflowWorldRequestBridge, attachTileflowAtmosphere, attachTileflowFairUseNotice, attachTileflowMapLifecycle, createTileflowSessionStarter, createTileflowThemeController, createTileflowTransformRequest, getTileflowSystemColorScheme, loadTileflowStyleFonts, registerTileflowContourProtocol, registerTileflowPmtilesProtocol, registerTileflowWorldRequestBridge, subscribeTileflowSystemColorScheme, tileflowFairUseNoticeMessage, tileflowMaplibreContourVersion, tileflowPmtilesMaximumDirectoryDepth, tileflowPmtilesProtocol };
+export { type TileflowAsyncAnalyticsTiming, type TileflowAtmosphereMap, type TileflowComposedRequest, type TileflowContourProtocolHandler, type TileflowContourProtocolRegistrationOptions, type TileflowContourProtocolRegistry, type TileflowContourProtocolRequest, type TileflowContourProtocolResponse, type TileflowFairUseNotice, type TileflowFairUseNoticeController, type TileflowFairUseNoticeState, type TileflowFrameScheduler, type TileflowMapLifecycleAttachment, type TileflowMapLifecycleEvent, type TileflowMapLifecycleSubscriber, type TileflowMapReadinessState, type TileflowPmtilesProtocolHandler, type TileflowPmtilesProtocolRegistrationOptions, type TileflowPmtilesProtocolRegistry, type TileflowSessionSender, type TileflowSessionStarter, type TileflowStyleFontLoadOptions, type TileflowStyleSwitchMap, type TileflowThemeBlendRequest, type TileflowThemeBlendState, type TileflowThemeChangeOptions, type TileflowThemeController, type TileflowThemeTransition, type TileflowThemeTransitionOptions, type TileflowThemeTransitionPhase, type TileflowThemeTransitionResult, type TileflowTransformRequest, type TileflowTransformRequestParameters, type TileflowUserTransformRequest, type TileflowWorldProtocolHandler, type TileflowWorldProtocolRequest, type TileflowWorldProtocolResponse, type TileflowWorldRequestBridge, attachTileflowAtmosphere, attachTileflowFairUseNotice, attachTileflowMapLifecycle, createTileflowSessionStarter, createTileflowThemeController, createTileflowTransformRequest, getTileflowSystemColorScheme, loadTileflowStyleFonts, registerTileflowContourProtocol, registerTileflowPmtilesProtocol, registerTileflowWorldRequestBridge, subscribeTileflowSystemColorScheme, tileflowFairUseNoticeMessage, tileflowMaplibreContourVersion, tileflowPmtilesMaximumDirectoryDepth, tileflowPmtilesProtocol };