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

package/README.md

@@ -144,6 +144,12 @@ show a continuous blend of them on the same MapLibre instance, with no extra req
 [theme transitions and blends](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/theme-transitions-and-blends.md).
 The same controller can make chosen modules recede and the map's labels fade so an application's
 own content reads first; see [map emphasis](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/map-emphasis.md).
+It also sets the style-wide states that themes read with `expr.globalState`, easing numbers so the
+values a theme interpolates on them move smoothly; see
+[style states](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/style-states.md).
+For application-drawn RGBA symbols, it also manages fixed-size
+[dynamic style images](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/dynamic-style-images.md),
+including state refresh, theme changes and restoration without changing layer placement.
 
 The semantic domains are `land`, `water`, `nautical`, `roads`, `buildings`, `boundaries`, `labels`,
 `poi`, `aeroways`, `transit`, `vegetation`, `addresses`, and `landforms`. Style stable geographic
@@ -239,7 +245,7 @@ standalone capture apply the browser effect automatically. Direct MapLibre integ
 
 A map with text must declare exactly one text provider. Streets, Ferraris, Härad, Soundings,
 and Blueprint use URL glyph providers. Baedeker and Siegfried use packaged Cormorant
-fonts; Cyberpunk and Matrix use packaged Oxanium fonts. Hosted deployment currently rejects
+fonts, and Cívica uses its packaged lettering. Hosted deployment currently rejects
 package/local font bundles; use self-hosted output or explicitly replace the provider with compatible
 public glyphs. Tile URLs and font providers do not establish redistribution rights.
 
@@ -265,6 +271,7 @@ revision; prefer the installed copy when working with an older release.
 - [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)
 - [Map emphasis](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/map-emphasis.md)
+- [Style states](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/style-states.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

@@ -1,3 +1,46 @@
+/** Inputs to one fixed-size, application-owned RGBA image. */
+type TileflowDynamicImageContext = Readonly<{
+    theme: string;
+    blend?: Readonly<{
+        position: number;
+        themes: readonly string[];
+    }>;
+    states: Readonly<Record<string, boolean | number | string | null | undefined>>;
+    /** Physical pixel dimensions, fixed for this registration. */
+    width: number;
+    height: number;
+    pixelRatio: number;
+}>;
+type TileflowDynamicImage = Readonly<{
+    /** Physical pixel dimensions, each from 1 through 2048. */
+    width: number;
+    height: number;
+    /** Physical pixels per logical pixel. Defaults to 1; fixed until disposal. */
+    pixelRatio?: number;
+    /** Controller states that invalidate this image, including interpolated values. */
+    states?: readonly string[];
+    /** Synchronous RGBA pixels; undefined keeps the previous pixels (initially transparent). */
+    render(context: TileflowDynamicImageContext): Uint8Array | Uint8ClampedArray | undefined;
+    /** Later render/restore failures retain good pixels. Defaults to console.error. */
+    onError?(error: Error): void;
+}>;
+type TileflowDynamicImageHandle = {
+    /** Refresh external inputs at the next frame. Repeated requests coalesce. */
+    refresh(): void;
+    /** Cancel queued work, release the name and remove only this resource's image. */
+    dispose(): void;
+};
+type TileflowDynamicImageMap = {
+    addImage?: unknown;
+    getCanvas?: unknown;
+    getImage?: unknown;
+    getStyle?: unknown;
+    removeImage?: unknown;
+    updateImage?: unknown;
+    on(event: string, listener: () => void): unknown;
+    off(event: string, listener: () => void): unknown;
+};
+
 type TileflowFairUseNoticeState = 'GRACE' | 'MANAGED_REQUIRED';
 type TileflowFairUseNotice = Readonly<{
     action: string;
@@ -135,6 +178,11 @@ type TileflowTextJustify = 'auto' | 'center' | 'left' | 'right';
 type TileflowIconAnchor = TileflowTextAnchor;
 type TileflowAlignment = 'auto' | 'map' | 'viewport';
 type TileflowIconTextFit = 'both' | 'height' | 'none' | 'width';
+/**
+ * How a symbol part treats collisions with symbols placed before it. `never` hides it, `always`
+ * shows it, and `cooperative` shows it unless the earlier symbol was placed with `never`.
+ */
+type TileflowSymbolOverlap = 'always' | 'cooperative' | 'never';
 /** Visibility and zoom bounds shared by every visual primitive. */
 type TileflowLayerRange = {
     maxZoom?: number;
@@ -231,6 +279,12 @@ type TileflowTextLayout = {
     maxWidth?: TileflowNumberStyleValue;
     offset?: TileflowNumberOffsetStyleValue;
     optional?: boolean;
+    /**
+     * Overlap mode. Takes precedence over `allowOverlap`, so the compiled layer carries only the mode.
+     * Native artifacts, whose renderer has no overlap modes, use `allowOverlap: false` for `never`
+     * and `true` otherwise.
+     */
+    overlap?: TileflowSymbolOverlap;
     padding?: TileflowNumberStyleValue;
     pitchAlignment?: TileflowAlignment;
     radialOffset?: TileflowNumberStyleValue;
@@ -256,6 +310,12 @@ type TileflowIconLayout = {
     keepUpright?: boolean;
     offset?: TileflowNumberOffsetStyleValue;
     optional?: boolean;
+    /**
+     * Overlap mode. Takes precedence over `allowOverlap`, so the compiled layer carries only the mode.
+     * Native artifacts, whose renderer has no overlap modes, use `allowOverlap: false` for `never`
+     * and `true` otherwise.
+     */
+    overlap?: TileflowSymbolOverlap;
     padding?: TileflowNumberStyleValue;
     pitchAlignment?: TileflowAlignment;
     rotate?: TileflowNumberStyleValue;
@@ -509,6 +569,17 @@ type TileflowStyleFontFace = {
     style?: 'italic' | 'normal' | 'oblique';
     weight?: '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900';
 };
+/**
+ * A continuous blend of named themes of one Tileflow 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.
+ */
+type TileflowThemeBlendSelection = Readonly<{
+    /** From 0 to `themes.length - 1`. */
+    position: number;
+    /** Two to eight concrete theme names of the map, in blend order. */
+    themes: readonly string[];
+}>;
 
 type TileflowAddressesModuleOptions = {
     /** Styling for OpenMapTiles point house-number labels. */
@@ -624,7 +695,6 @@ type TileflowVegetationThreeDimensionalStyle = {
 };
 type TileflowVegetationModuleOptions = {
     flat?: TileflowCircleStyle;
-    minZoom?: number;
     mode?: TileflowVegetationMode;
     threeDimensional?: TileflowVegetationThreeDimensionalStyle;
 };
@@ -785,7 +855,7 @@ type TileflowPmtilesProtocolHandler = (request: Readonly<{
     url: string;
 }>, abortController: AbortController) => Promise<Readonly<{
     cacheControl?: string;
-    data: unknown;
+    data: object | string;
     expires?: string;
 }>>;
 type TileflowPmtilesProtocolRegistry = Readonly<{
@@ -840,24 +910,56 @@ type TileflowThemeBlendRequest = Readonly<{
     position: number;
     /** Two to eight concrete themes of one map, in blend order. */
     themes: readonly TileflowRuntimeStyle[];
+    /**
+     * Holds back what would make MapLibre lay tiles out again: the change of nearest theme, with
+     * the labels, icons, and values it switches, and mixed pattern artwork. Colours, numbers, the
+     * sky, and light keep following the position, so a camera move or a recording never waits on
+     * the blend. The next request without `hold` brings what was held back in at once.
+     */
+    hold?: boolean;
 }>;
+/**
+ * A blend of named themes as the React, Vue, and Svelte maps take it: `hold` holds back what
+ * would make MapLibre lay tiles out again, as `TileflowThemeBlendRequest.hold` does, and the next
+ * selection without it brings what waited in at once.
+ */
+type TileflowBrowserThemeBlendSelection = TileflowThemeBlendSelection & Readonly<{
+    hold?: boolean;
+}>;
+declare function validateTileflowBrowserThemeBlendSelection(value: unknown): value is TileflowBrowserThemeBlendSelection;
 type TileflowThemeBlendState = Readonly<{
+    /** Whether changes held back by `hold` are waiting for a request without it. */
+    held: boolean;
     position: number;
+    /**
+     * Positions where the nearest theme changes over values that make MapLibre lay tiles out
+     * again, such as icon names, layout values, and values that read feature data or state. Plan
+     * a camera move or a recording around them, or pass `hold` across them.
+     */
+    relayoutAt: readonly number[];
     themes: readonly string[];
 }>;
-type TileflowStyleSwitchMap = TileflowThemeMotionMap & {
+type TileflowStyleSwitchMap = TileflowThemeMotionMap & TileflowDynamicImageMap & {
+    getGlobalState?: unknown;
     off(event: string, listener: (event?: unknown) => void): unknown;
     on(event: string, listener: (event?: unknown) => void): unknown;
+    setGlobalStateProperty?: unknown;
     setStyle: unknown;
 };
+/** A value an application sets for the whole style, which themes read with `expr.globalState`. */
+type TileflowStyleStateValue = boolean | number | string | null;
 type TileflowThemeController = {
     dispose(): void;
+    /** Own a fixed-size RGBA image with a stable name across themes, restored after style reloads. */
+    registerImage(name: string, image: TileflowDynamicImage): TileflowDynamicImageHandle;
     /** 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;
     /** The emphasis requested last, or undefined when the map is shown as designed. */
     getEmphasis(): TileflowEmphasis | undefined;
+    /** The value a style state was set to last, or undefined when it has not been set. */
+    getState(name: string): TileflowStyleStateValue | undefined;
     /**
      * 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
@@ -871,6 +973,15 @@ type TileflowThemeController = {
      * that MapLibre evaluates per feature change at once, under a cross-fade.
      */
     setEmphasis(emphasis: TileflowEmphasis | undefined, options?: TileflowThemeChangeOptions): Promise<TileflowThemeTransitionResult>;
+    /**
+     * Sets a style-wide state that the map's themes read with `expr.globalState(name)`. A number
+     * eases from the value it shows to the new one over the transition, so a colour or size that a
+     * theme interpolates on it moves smoothly; other values, and a number set for the first time,
+     * change at once. A value that also reads feature data or feature state is laid out again by
+     * MapLibre at each change, so it follows late and costs more. States stay through theme changes
+     * and blends. Needs a MapLibre map with global state (GL JS 5.6 or later).
+     */
+    setState(name: string, value: TileflowStyleStateValue, options?: TileflowThemeChangeOptions): Promise<TileflowThemeTransitionResult>;
     setTheme(style: TileflowRuntimeStyle, options?: TileflowThemeChangeOptions): Promise<TileflowThemeTransitionResult>;
 };
 /**
@@ -921,7 +1032,6 @@ type TileflowTransformRequestParameters = {
 type TileflowComposedRequest<TRequest extends TileflowTransformRequestParameters> = Pick<TRequest, 'url'> & Partial<Omit<TRequest, 'url'>>;
 type TileflowTransformRequest<TRequest extends TileflowTransformRequestParameters, TResourceType> = (url: string, resourceType?: TResourceType) => Promise<TileflowComposedRequest<TRequest>> | TileflowComposedRequest<TRequest> | undefined;
 type TileflowUserTransformRequest<TRequest extends TileflowTransformRequestParameters, TResourceType> = (url: string, resourceType?: TResourceType) => Promise<TRequest> | TRequest | undefined;
-type TileflowAsyncAnalyticsTiming = 'request' | 'resolution';
 declare function createTileflowSessionStarter(options: {
     getSessionId?: () => string;
     sessionId: string;
@@ -940,23 +1050,17 @@ declare function attachTileflowMapLifecycle<TMap, TFrame>(options: {
     setState: (state: TileflowMapReadinessState) => void;
     subscribe: TileflowMapLifecycleSubscriber<TMap>;
 }): TileflowMapLifecycleAttachment;
+/**
+ * Compose the caller's request transform with Tileflow analytics, the Hosted session, and the
+ * World bridge. Analytics are read when each request starts, so an asynchronous user transform
+ * never attaches analytics that changed while it was pending.
+ */
 declare function createTileflowTransformRequest<TRequest extends TileflowTransformRequestParameters = TileflowTransformRequestParameters, TResourceType = unknown>(options: {
-    always: true;
-    asyncAnalyticsTiming?: TileflowAsyncAnalyticsTiming;
     getAnalytics: () => TileflowAnalytics | undefined;
     sessionController?: TileflowSessionController;
     sessionId: string;
     transformRequest?: TileflowUserTransformRequest<TRequest, TResourceType>;
     worldRequestBridge?: TileflowWorldRequestBridge;
 }): TileflowTransformRequest<TRequest, TResourceType>;
-declare function createTileflowTransformRequest<TRequest extends TileflowTransformRequestParameters = TileflowTransformRequestParameters, TResourceType = unknown>(options: {
-    always?: boolean;
-    asyncAnalyticsTiming?: TileflowAsyncAnalyticsTiming;
-    getAnalytics: () => TileflowAnalytics | undefined;
-    sessionController?: TileflowSessionController;
-    sessionId: string;
-    transformRequest?: TileflowUserTransformRequest<TRequest, TResourceType>;
-    worldRequestBridge?: TileflowWorldRequestBridge;
-}): TileflowTransformRequest<TRequest, TResourceType> | undefined;
 
-export { type TileflowAsyncAnalyticsTiming, type TileflowAtmosphereMap, type TileflowComposedRequest, type TileflowContourProtocolHandler, type TileflowContourProtocolRegistrationOptions, type TileflowContourProtocolRegistry, type TileflowContourProtocolRequest, type TileflowContourProtocolResponse, type TileflowEmphasis, type TileflowEmphasisArea, type TileflowEmphasisModule, 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, tileflowLayerDomainMetadataKey, tileflowMaplibreContourVersion, tileflowPmtilesMaximumDirectoryDepth, tileflowPmtilesProtocol, validateTileflowEmphasis };
+export { type TileflowAtmosphereMap, type TileflowBrowserThemeBlendSelection, type TileflowComposedRequest, type TileflowContourProtocolHandler, type TileflowContourProtocolRegistrationOptions, type TileflowContourProtocolRegistry, type TileflowContourProtocolRequest, type TileflowContourProtocolResponse, type TileflowDynamicImage, type TileflowDynamicImageContext, type TileflowDynamicImageHandle, type TileflowEmphasis, type TileflowEmphasisArea, type TileflowEmphasisModule, 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 TileflowStyleStateValue, 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, tileflowLayerDomainMetadataKey, tileflowMaplibreContourVersion, tileflowPmtilesMaximumDirectoryDepth, tileflowPmtilesProtocol, validateTileflowBrowserThemeBlendSelection, validateTileflowEmphasis };