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

package/dist/{manifest-types-BZU4zbmI.d.ts → manifest-types-CTT2eLbp.d.ts}

@@ -189,9 +189,26 @@ type TileflowTextPaint = {
     haloWidth?: TileflowNumberStyleValue;
     opacity?: TileflowNumberStyleValue;
 };
+/**
+ * One opaque strip behind each shaped line of a label. Tileflow lowers it to a derived glyph stack
+ * whose cells MapLibre's text halo paints, so placement, wrapping and collision stay native.
+ */
+type TileflowTextBackground = {
+    /** Strip colour. Cells overlap at their joins, so the colour must be opaque. */
+    color: TileflowColorStyleValue;
+    /** `lines` fits one strip to each shaped line. */
+    fit: 'lines';
+    /** Strip extension beyond the first and last glyph of each line, in ems. Defaults to 0.33. */
+    padding?: TileflowThemeNumberValue;
+};
 type TileflowTextLayout = {
     allowOverlap?: boolean;
     anchor?: TileflowTextAnchor;
+    /**
+     * Replaces the text halo with line-fitted strips. Requires a map `glyphs` provider that serves
+     * derived stacks, one font without fallbacks, and constant `letterSpacing` and `lineHeight`.
+     */
+    background?: TileflowTextBackground;
     field?: TileflowStringStyleValue;
     font?: TileflowThemeFontValue;
     fallbacks?: readonly TileflowThemeFontValue[];
@@ -653,6 +670,30 @@ declare function shouldLoadTileflowManifest(options: TileflowManifestLoadOptions
 declare function validateTileflowRuntimeSource(source: unknown): TileflowRuntimeSourceValidation;
 /** Validate the only runtime selection grammar: one concrete portable name or `system`. */
 declare function validateTileflowThemeSelection(value: unknown): value is TileflowThemeSelection;
+/**
+ * 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[];
+}>;
+declare const tileflowThemeBlendLimits: Readonly<{
+    maximumThemes: 8;
+    minimumThemes: 2;
+}>;
+declare function validateTileflowThemeBlendSelection(value: unknown): value is TileflowThemeBlendSelection;
+/** The theme nearest to a blend position, which a blend shows when it cannot blend. */
+declare function nearestTileflowBlendTheme(blend: TileflowThemeBlendSelection): string;
+/** Resolves every theme of a blend to its published runtime style, in blend order. */
+declare function resolveTileflowRuntimeThemeBlend(options: {
+    blend: TileflowThemeBlendSelection;
+    manifestMap: TileflowRuntimeManifestMap;
+    source: TileflowRuntimeSource;
+}): TileflowRuntimeStyle[];
 declare function assertValidTileflowRuntimeSource(source: unknown): asserts source is TileflowRuntimeSource;
 declare function resolveTileflowRuntimeStyle(options: TileflowRuntimeStyleOptions): TileflowRuntimeStyle | null;
 /** Resolve one concrete published theme without consulting ambient browser state. */
@@ -746,4 +787,4 @@ type TileflowRuntimeManifest = {
     version: typeof tileflowRuntimeManifestVersion;
 };
 
-export { type TileflowManifestFetchOptions as $, type TileflowAreaStyle as A, type TileflowBackgroundPaint as B, type TileflowCirclePaint as C, type TileflowColor as D, type TileflowColorStyleValue as E, type TileflowExtrusionPaint as F, type TileflowFillPaint as G, type TileflowIconAnchor as H, type TileflowIconLayout as I, type TileflowIconPaint as J, type TileflowIconStyle as K, type TileflowIconTextFit as L, type MapLibreStyle as M, type TileflowImageStyleValue as N, type TileflowLabelDetail as O, type TileflowLabelLanguage as P, type TileflowLabelStyles as Q, type TileflowLayerRange as R, type TileflowLight as S, type TileflowRuntimeManifest as T, type TileflowLineCap as U, type ValidationMessage as V, type TileflowLineHatchStyle as W, type TileflowLineJoin as X, type TileflowLineLayout as Y, type TileflowLinePaint as Z, type TileflowLineStackStyle as _, type TileflowRuntimeColorScheme as a, type TileflowTextJustify as a$, type TileflowManifestLoadOptions as a0, type TileflowMapMode as a1, type TileflowMapModeOptions as a2, type TileflowMarkerSymbolStyle as a3, type TileflowMountainBikeScale as a4, type TileflowNumberInsetsStyleValue as a5, type TileflowNumberStyleValue as a6, type TileflowPlaceLabelClass as a7, type TileflowPoiCategory as a8, type TileflowPoiCategoryStyle as a9, type TileflowRoadWeight as aA, type TileflowRuntimeCenterLike as aB, type TileflowRuntimeManifestMap as aC, type TileflowRuntimeSource as aD, type TileflowRuntimeSourceValidation as aE, type TileflowRuntimeStyle as aF, type TileflowRuntimeStyleOptions as aG, type TileflowRuntimeViewOptions as aH, type TileflowSessionController as aI, type TileflowSessionGrantResponse as aJ, type TileflowStringStyleValue as aK, type TileflowStructuralStyleValue as aL, type TileflowStyleFontFace as aM, type TileflowStyleValue as aN, type TileflowSymbolPlacement as aO, type TileflowSymbolPlacementStyle as aP, type TileflowSymbolZOrder as aQ, type TileflowTerrain as aR, type TileflowTerrainConfig as aS, type TileflowTerrainContourLabelStyle as aT, type TileflowTerrainContourLineStyle as aU, type TileflowTerrainContoursConfig as aV, type TileflowTerrainEncoding as aW, type TileflowTerrainHillshadeStyle as aX, type TileflowTerrainLayerRange as aY, type TileflowTerrainMode as aZ, type TileflowTextAnchor as a_, type TileflowPoiColorMode as aa, type TileflowPoiDensity as ab, type TileflowPriorityOrder as ac, type TileflowProjection as ad, type TileflowResolvedRuntimeTheme as ae, type TileflowRoadAreaStyle as af, type TileflowRoadClass as ag, type TileflowRoadClassStyle as ah, type TileflowRoadCrossingStyle as ai, type TileflowRoadDetail as aj, type TileflowRoadExtras as ak, type TileflowRoadHierarchy as al, type TileflowRoadLabelDetail as am, type TileflowRoadLayerStyle as an, type TileflowRoadModifier as ao, type TileflowRoadOutline as ap, type TileflowRoadRestriction as aq, type TileflowRoadRoundaboutStyle as ar, type TileflowRoadServiceType as as, type TileflowRoadShieldDetail as at, type TileflowRoadShieldStyles as au, type TileflowRoadSidewalkStyle as av, type TileflowRoadStructure as aw, type TileflowRoadTreatmentLayerStyle as ax, type TileflowRoadTreatmentLineStyle as ay, type TileflowRoadTreatmentStyle as az, type TileflowRuntimeManifestMapEntry as b, type TileflowTextLayout as b0, type TileflowTextPaint as b1, type TileflowTextStyle as b2, type TileflowThemeColorAlpha as b3, type TileflowThemeColorMix as b4, type TileflowThemeColorValue as b5, type TileflowThemeFontValue as b6, type TileflowThemeImageValue as b7, type TileflowThemeNumberValue as b8, type TileflowThemeSelection as b9, resolveTileflowRuntimeStyle as bA, resolveTileflowRuntimeTheme as bB, resolveTileflowRuntimeView as bC, resolveTileflowStaticImageUrl as bD, shouldLoadTileflowManifest as bE, startTileflowSession as bF, tileflowPoiCategories as bG, tileflowStyleFontFaceLimits as bH, tileflowStyleFontFacesMetadataKey as bI, tileflowThemeTokenCategories as bJ, token as bK, validateTileflowRuntimeSource as bL, validateTileflowThemeSelection as bM, zoom as bN, type TileflowTypographyStyle as bO, type ResolvedTileflowTypography as bP, normalizeTileflowSurfaceId as bQ, type TileflowThemeTokenCategory as ba, type TileflowThemeValue as bb, type TileflowViewConfig as bc, type TileflowWaterLabelClass as bd, type TileflowZoomInterpolation as be, type TileflowZoomValue as bf, type ValidationResult as bg, assertValidTileflowRuntimeSource as bh, clearTileflowManifestCache as bi, color as bj, createTileflowSessionController as bk, createTileflowSessionId as bl, defaultTileflowManifestUrl as bm, defaultTileflowRuntimeView as bn, fixed as bo, getTileflowAnalyticsApiUrl as bp, getTileflowStyleFontFaces as bq, inferTileflowAnalyticsFromStyleUrl as br, loadTileflowManifest as bs, mergeTileflowAnalytics as bt, normalizeTileflowRuntimeCenter as bu, normalizeTileflowStaticImageSize as bv, normalizeTileflowUrl as bw, resolveTileflowAnalyticsRequestUrl as bx, resolveTileflowManifestMap as by, resolveTileflowMapMode as bz, type TileflowRuntimeManifestTheme as c, type TileflowRuntimeSystemThemes as d, tileflowRuntimeManifestVersion as e, type TileflowExpression as f, type TileflowFixedValue as g, type TileflowThemeTokenReference as h, type TileflowThemeColorOperation as i, type TileflowBackgroundStyle as j, type TileflowCircleStyle as k, type TileflowExtrusionStyle as l, type TileflowFillStyle as m, type TileflowLineStyle as n, type TileflowSymbolStyle as o, type TileflowRoadsModuleOptions as p, type TileflowRoadsModuleConfig as q, type TileflowLabelsModuleOptions as r, type TileflowLabelsModuleConfig as s, tileflowRuntimeManifestLimits as t, type TileflowPoiModuleOptions as u, type TileflowPoiModuleConfig as v, type MapLibreSprite as w, type TileflowAerodromeCodeDetail as x, type TileflowAlignment as y, type TileflowAnalytics as z };
+export { type TileflowManifestFetchOptions as $, type TileflowAreaStyle as A, type TileflowBackgroundPaint as B, type TileflowCirclePaint as C, type TileflowColor as D, type TileflowColorStyleValue as E, type TileflowExtrusionPaint as F, type TileflowFillPaint as G, type TileflowIconAnchor as H, type TileflowIconLayout as I, type TileflowIconPaint as J, type TileflowIconStyle as K, type TileflowIconTextFit as L, type MapLibreStyle as M, type TileflowImageStyleValue as N, type TileflowLabelDetail as O, type TileflowLabelLanguage as P, type TileflowLabelStyles as Q, type TileflowLayerRange as R, type TileflowLight as S, type TileflowRuntimeManifest as T, type TileflowLineCap as U, type ValidationMessage as V, type TileflowLineHatchStyle as W, type TileflowLineJoin as X, type TileflowLineLayout as Y, type TileflowLinePaint as Z, type TileflowLineStackStyle as _, type TileflowRuntimeColorScheme as a, type TileflowTextBackground as a$, type TileflowManifestLoadOptions as a0, type TileflowMapMode as a1, type TileflowMapModeOptions as a2, type TileflowMarkerSymbolStyle as a3, type TileflowMountainBikeScale as a4, type TileflowNumberInsetsStyleValue as a5, type TileflowNumberStyleValue as a6, type TileflowPlaceLabelClass as a7, type TileflowPoiCategory as a8, type TileflowPoiCategoryStyle as a9, type TileflowRoadWeight as aA, type TileflowRuntimeCenterLike as aB, type TileflowRuntimeManifestMap as aC, type TileflowRuntimeSource as aD, type TileflowRuntimeSourceValidation as aE, type TileflowRuntimeStyle as aF, type TileflowRuntimeStyleOptions as aG, type TileflowRuntimeViewOptions as aH, type TileflowSessionController as aI, type TileflowSessionGrantResponse as aJ, type TileflowStringStyleValue as aK, type TileflowStructuralStyleValue as aL, type TileflowStyleFontFace as aM, type TileflowStyleValue as aN, type TileflowSymbolPlacement as aO, type TileflowSymbolPlacementStyle as aP, type TileflowSymbolZOrder as aQ, type TileflowTerrain as aR, type TileflowTerrainConfig as aS, type TileflowTerrainContourLabelStyle as aT, type TileflowTerrainContourLineStyle as aU, type TileflowTerrainContoursConfig as aV, type TileflowTerrainEncoding as aW, type TileflowTerrainHillshadeStyle as aX, type TileflowTerrainLayerRange as aY, type TileflowTerrainMode as aZ, type TileflowTextAnchor as a_, type TileflowPoiColorMode as aa, type TileflowPoiDensity as ab, type TileflowPriorityOrder as ac, type TileflowProjection as ad, type TileflowResolvedRuntimeTheme as ae, type TileflowRoadAreaStyle as af, type TileflowRoadClass as ag, type TileflowRoadClassStyle as ah, type TileflowRoadCrossingStyle as ai, type TileflowRoadDetail as aj, type TileflowRoadExtras as ak, type TileflowRoadHierarchy as al, type TileflowRoadLabelDetail as am, type TileflowRoadLayerStyle as an, type TileflowRoadModifier as ao, type TileflowRoadOutline as ap, type TileflowRoadRestriction as aq, type TileflowRoadRoundaboutStyle as ar, type TileflowRoadServiceType as as, type TileflowRoadShieldDetail as at, type TileflowRoadShieldStyles as au, type TileflowRoadSidewalkStyle as av, type TileflowRoadStructure as aw, type TileflowRoadTreatmentLayerStyle as ax, type TileflowRoadTreatmentLineStyle as ay, type TileflowRoadTreatmentStyle as az, type TileflowRuntimeManifestMapEntry as b, type TileflowTextJustify as b0, type TileflowTextLayout as b1, type TileflowTextPaint as b2, type TileflowTextStyle as b3, type TileflowThemeBlendSelection as b4, type TileflowThemeColorAlpha as b5, type TileflowThemeColorMix as b6, type TileflowThemeColorValue as b7, type TileflowThemeFontValue as b8, type TileflowThemeImageValue as b9, resolveTileflowAnalyticsRequestUrl as bA, resolveTileflowManifestMap as bB, resolveTileflowMapMode as bC, resolveTileflowRuntimeStyle as bD, resolveTileflowRuntimeTheme as bE, resolveTileflowRuntimeThemeBlend as bF, resolveTileflowRuntimeView as bG, resolveTileflowStaticImageUrl as bH, shouldLoadTileflowManifest as bI, startTileflowSession as bJ, tileflowPoiCategories as bK, tileflowStyleFontFaceLimits as bL, tileflowStyleFontFacesMetadataKey as bM, tileflowThemeBlendLimits as bN, tileflowThemeTokenCategories as bO, token as bP, validateTileflowRuntimeSource as bQ, validateTileflowThemeBlendSelection as bR, validateTileflowThemeSelection as bS, zoom as bT, type TileflowTypographyStyle as bU, type ResolvedTileflowTypography as bV, normalizeTileflowSurfaceId as bW, type TileflowThemeNumberValue as ba, type TileflowThemeSelection as bb, type TileflowThemeTokenCategory as bc, type TileflowThemeValue as bd, type TileflowViewConfig as be, type TileflowWaterLabelClass as bf, type TileflowZoomInterpolation as bg, type TileflowZoomValue as bh, type ValidationResult as bi, assertValidTileflowRuntimeSource as bj, clearTileflowManifestCache as bk, color as bl, createTileflowSessionController as bm, createTileflowSessionId as bn, defaultTileflowManifestUrl as bo, defaultTileflowRuntimeView as bp, fixed as bq, getTileflowAnalyticsApiUrl as br, getTileflowStyleFontFaces as bs, inferTileflowAnalyticsFromStyleUrl as bt, loadTileflowManifest as bu, mergeTileflowAnalytics as bv, nearestTileflowBlendTheme as bw, normalizeTileflowRuntimeCenter as bx, normalizeTileflowStaticImageSize as by, normalizeTileflowUrl as bz, type TileflowRuntimeManifestTheme as c, type TileflowRuntimeSystemThemes as d, tileflowRuntimeManifestVersion as e, type TileflowExpression as f, type TileflowFixedValue as g, type TileflowThemeTokenReference as h, type TileflowThemeColorOperation as i, type TileflowBackgroundStyle as j, type TileflowCircleStyle as k, type TileflowExtrusionStyle as l, type TileflowFillStyle as m, type TileflowLineStyle as n, type TileflowSymbolStyle as o, type TileflowRoadsModuleOptions as p, type TileflowRoadsModuleConfig as q, type TileflowLabelsModuleOptions as r, type TileflowLabelsModuleConfig as s, tileflowRuntimeManifestLimits as t, type TileflowPoiModuleOptions as u, type TileflowPoiModuleConfig as v, type MapLibreSprite as w, type TileflowAerodromeCodeDetail as x, type TileflowAlignment as y, type TileflowAnalytics as z };

package/dist/manifest.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import { T as TileflowRuntimeManifest } from './manifest-types-BZU4zbmI.js';
-export { a as TileflowRuntimeColorScheme, b as TileflowRuntimeManifestMapEntry, c as TileflowRuntimeManifestTheme, d as TileflowRuntimeSystemThemes, t as tileflowRuntimeManifestLimits, e as tileflowRuntimeManifestVersion } from './manifest-types-BZU4zbmI.js';
+import { T as TileflowRuntimeManifest } from './manifest-types-CTT2eLbp.js';
+export { a as TileflowRuntimeColorScheme, b as TileflowRuntimeManifestMapEntry, c as TileflowRuntimeManifestTheme, d as TileflowRuntimeSystemThemes, t as tileflowRuntimeManifestLimits, e as tileflowRuntimeManifestVersion } from './manifest-types-CTT2eLbp.js';
 
 declare const tileflowRuntimeManifestSchema: z.ZodType<TileflowRuntimeManifest>;
 declare function parseTileflowRuntimeManifest(input: unknown): TileflowRuntimeManifest;

package/dist/native.js

@@ -4605,6 +4605,7 @@ var manifestCache = new globalThis.Map();
 function validateTileflowThemeSelection(value) {
   return value === "system" || isTileflowThemeName(value);
 }
+var tileflowThemeBlendLimits = Object.freeze({ maximumThemes: 8, minimumThemes: 2 });
 function resolveTileflowRuntimeTheme(map2, selection, colorScheme) {
   let name;
   if (selection === void 0) {

package/dist/runtime.d.ts

@@ -1 +1 @@
-export { z as TileflowAnalytics, $ as TileflowManifestFetchOptions, a0 as TileflowManifestLoadOptions, a1 as TileflowMapMode, a2 as TileflowMapModeOptions, ae as TileflowResolvedRuntimeTheme, aB as TileflowRuntimeCenterLike, a as TileflowRuntimeColorScheme, T as TileflowRuntimeManifest, aC as TileflowRuntimeManifestMap, b as TileflowRuntimeManifestMapEntry, c as TileflowRuntimeManifestTheme, aD as TileflowRuntimeSource, aE as TileflowRuntimeSourceValidation, aF as TileflowRuntimeStyle, aG as TileflowRuntimeStyleOptions, d as TileflowRuntimeSystemThemes, aH as TileflowRuntimeViewOptions, aI as TileflowSessionController, aJ as TileflowSessionGrantResponse, aM as TileflowStyleFontFace, b9 as TileflowThemeSelection, bh as assertValidTileflowRuntimeSource, bi as clearTileflowManifestCache, bk as createTileflowSessionController, bl as createTileflowSessionId, bm as defaultTileflowManifestUrl, bn as defaultTileflowRuntimeView, bp as getTileflowAnalyticsApiUrl, bq as getTileflowStyleFontFaces, br as inferTileflowAnalyticsFromStyleUrl, bs as loadTileflowManifest, bt as mergeTileflowAnalytics, bu as normalizeTileflowRuntimeCenter, bv as normalizeTileflowStaticImageSize, bQ as normalizeTileflowSurfaceId, bw as normalizeTileflowUrl, bx as resolveTileflowAnalyticsRequestUrl, by as resolveTileflowManifestMap, bz as resolveTileflowMapMode, bA as resolveTileflowRuntimeStyle, bB as resolveTileflowRuntimeTheme, bC as resolveTileflowRuntimeView, bD as resolveTileflowStaticImageUrl, bE as shouldLoadTileflowManifest, bF as startTileflowSession, bH as tileflowStyleFontFaceLimits, bI as tileflowStyleFontFacesMetadataKey, bL as validateTileflowRuntimeSource, bM as validateTileflowThemeSelection } from './manifest-types-BZU4zbmI.js';
+export { z as TileflowAnalytics, $ as TileflowManifestFetchOptions, a0 as TileflowManifestLoadOptions, a1 as TileflowMapMode, a2 as TileflowMapModeOptions, ae as TileflowResolvedRuntimeTheme, aB as TileflowRuntimeCenterLike, a as TileflowRuntimeColorScheme, T as TileflowRuntimeManifest, aC as TileflowRuntimeManifestMap, b as TileflowRuntimeManifestMapEntry, c as TileflowRuntimeManifestTheme, aD as TileflowRuntimeSource, aE as TileflowRuntimeSourceValidation, aF as TileflowRuntimeStyle, aG as TileflowRuntimeStyleOptions, d as TileflowRuntimeSystemThemes, aH as TileflowRuntimeViewOptions, aI as TileflowSessionController, aJ as TileflowSessionGrantResponse, aM as TileflowStyleFontFace, b4 as TileflowThemeBlendSelection, bb as TileflowThemeSelection, bj as assertValidTileflowRuntimeSource, bk as clearTileflowManifestCache, bm as createTileflowSessionController, bn as createTileflowSessionId, bo as defaultTileflowManifestUrl, bp as defaultTileflowRuntimeView, br as getTileflowAnalyticsApiUrl, bs as getTileflowStyleFontFaces, bt as inferTileflowAnalyticsFromStyleUrl, bu as loadTileflowManifest, bv as mergeTileflowAnalytics, bw as nearestTileflowBlendTheme, bx as normalizeTileflowRuntimeCenter, by as normalizeTileflowStaticImageSize, bW as normalizeTileflowSurfaceId, bz as normalizeTileflowUrl, bA as resolveTileflowAnalyticsRequestUrl, bB as resolveTileflowManifestMap, bC as resolveTileflowMapMode, bD as resolveTileflowRuntimeStyle, bE as resolveTileflowRuntimeTheme, bF as resolveTileflowRuntimeThemeBlend, bG as resolveTileflowRuntimeView, bH as resolveTileflowStaticImageUrl, bI as shouldLoadTileflowManifest, bJ as startTileflowSession, bL as tileflowStyleFontFaceLimits, bM as tileflowStyleFontFacesMetadataKey, bN as tileflowThemeBlendLimits, bQ as validateTileflowRuntimeSource, bR as validateTileflowThemeBlendSelection, bS as validateTileflowThemeSelection } from './manifest-types-CTT2eLbp.js';

package/dist/runtime.js

@@ -496,6 +496,30 @@ function validateTileflowRuntimeSource(source) {
 function validateTileflowThemeSelection(value) {
   return value === "system" || isTileflowThemeName(value);
 }
+var tileflowThemeBlendLimits = Object.freeze({ maximumThemes: 8, minimumThemes: 2 });
+function validateTileflowThemeBlendSelection(value) {
+  if (!value || typeof value !== "object") return false;
+  const { position, themes } = value;
+  return Array.isArray(themes) && themes.length >= tileflowThemeBlendLimits.minimumThemes && themes.length <= tileflowThemeBlendLimits.maximumThemes && themes.every((theme) => isTileflowThemeName(theme)) && typeof position === "number" && Number.isFinite(position) && position >= 0 && position <= themes.length - 1;
+}
+function nearestTileflowBlendTheme(blend) {
+  const index = Math.min(blend.themes.length - 1, Math.max(0, Math.round(blend.position)));
+  return blend.themes[index];
+}
+function resolveTileflowRuntimeThemeBlend(options) {
+  if (!validateTileflowThemeBlendSelection(options.blend)) {
+    throw new TypeError(
+      "A Tileflow theme blend requires two to eight concrete themes and a position."
+    );
+  }
+  return options.blend.themes.map(
+    (theme) => resolveTileflowRuntimeStyle({
+      manifestMap: options.manifestMap,
+      source: options.source,
+      theme
+    })
+  );
+}
 function assertValidTileflowRuntimeSource(source) {
   const validation = validateTileflowRuntimeSource(source);
   if (!validation.ok) {
@@ -1269,6 +1293,7 @@ export {
   inferTileflowAnalyticsFromStyleUrl,
   loadTileflowManifest,
   mergeTileflowAnalytics,
+  nearestTileflowBlendTheme,
   normalizeTileflowRuntimeCenter,
   normalizeTileflowStaticImageSize,
   normalizeTileflowSurfaceId,
@@ -1278,12 +1303,15 @@ export {
   resolveTileflowMapMode,
   resolveTileflowRuntimeStyle,
   resolveTileflowRuntimeTheme,
+  resolveTileflowRuntimeThemeBlend,
   resolveTileflowRuntimeView,
   resolveTileflowStaticImageUrl,
   shouldLoadTileflowManifest,
   startTileflowSession,
   tileflowStyleFontFaceLimits,
   tileflowStyleFontFacesMetadataKey,
+  tileflowThemeBlendLimits,
   validateTileflowRuntimeSource,
+  validateTileflowThemeBlendSelection,
   validateTileflowThemeSelection
 };

package/docs/authoring-model.md

@@ -158,6 +158,21 @@ Structural controls such as presets, visibility, and zoom gates remain ordinary
 controls address stable concepts such as `roads.classes.primary.surface.fill`, not renderer layer
 IDs.
 
+`expr.id()` reads the source-owned feature identifier: a string, number, or `null` when absent.
+It performs no I/O and does not derive an identifier from geometry. `expr.modulo(dividend, divisor)`
+uses native numeric remainder, including its sign behavior. Normalize input and provide a deliberate
+fallback before using numeric IDs for decorative variation; missing or non-numeric IDs must not
+silently imply distinct features. Identity stability across data releases belongs to the producer.
+
+<!-- docs:check -->
+
+```ts
+import {expr} from '@tileflow/core';
+
+const numericIdentity = expr.abs(expr.toNumber(expr.id(), 0));
+const decorativeBucket = expr.modulo(numericIdentity, 7);
+```
+
 The `land` module exposes stable land-use targets for `cemetery`, `civic`, `commercial`,
 `education`, `government`, `industrial`, `medical`, `military`, `parking`, `railway`,
 `recreation`, and `residential`. Its land-cover taxonomy distinguishes physical cover from authored
@@ -194,6 +209,18 @@ broadleaf and conifer palettes, and independent height and crown scales. The leg
 shortcut remains available; `flat.minZoom` takes precedence when both are present. The binding
 includes height, crown diameter, genus, leaf type, and species fields so compatible runtimes can
 preserve source measurements and botanical form without hard-coding raw property names. The
-pitched-scene stack follows physical height: pedestrian and transport surfaces, transport markings
-and road names, buildings, then vegetation. Place, water, aerodrome, and POI annotations remain
-last so geographic names stay readable without making street paint or text float over 3D geometry.
+pitched-scene stack follows physical height: pedestrian and transport surfaces, transport markings,
+buildings, then vegetation, so street paint never floats over 3D geometry. Text draws last: road
+names, route shields, junction numbers, and place, water, aerodrome, and POI annotations stay above
+every ground layer, so building fills, boundaries, and trees cannot cover them.
+`labels.collisionPriority` only orders labels within that final stack.
+
+Render passes, and refinements that move a target their module owns, share one `placement`
+vocabulary. A band edge is `below-` or `above-` one of `land`, `relief`, `water`, `roads`,
+`boundaries`, `buildings`, `vegetation`, and `labels`; it needs no anchor, so a vegetation pass can
+draw `'above-relief'` without depending on another module. `{above: target}` and `{below: target}`
+draw beside one semantic target and inherit its band and, without their own `feature`, its vector
+data; passes placed beside a moved target follow it. Operations sharing a placement paint in
+declaration order, the first lowest. For symbols, a higher layer is also placed first in MapLibre
+collisions, so placement decides both drawing and precedence. An owner whose layers are all
+render passes still satisfies other operations' `requirements`.

package/docs/data-is-separate-from-design.md

@@ -116,7 +116,8 @@ to right; a later exact name replaces an earlier face and case-only collisions f
 faces used by the final style become content-addressed assets and strict `tileflow:fontFaces`
 metadata. `font` names an exact OpenType full name or glyph face; local `fallbacks` name exact faces
 or explicit CSS generic families. Tileflow never appends a weight suffix or derives one face from
-another. Browser adapters load local faces before MapLibre. Native releases use a locked PBF
+another; the only derived stacks are line-fitted text backgrounds on a `glyphs` provider, which keep
+their source faces' shapes. Browser adapters load local faces before MapLibre. Native releases use a locked PBF
 `glyphs` URL provider instead, which enumerates the exact comma-joined MapLibre request keys in
 `fontStacks`.
 

package/docs/shared-visual-primitives.md

@@ -10,8 +10,9 @@ having to learn different spellings for the same MapLibre behavior:
 - `LineStyle`: color, width, opacity, dash, blur, gap, offset, pattern, caps, joins, and zoom range.
 - `LineHatchStyle`: repeated diagonal detail with color, opacity, spacing, size, angle, and zoom
   range for a road structure.
-- `TextStyle`: field, exact font face, exact fallback faces, size, color, halo, spacing metrics, transform,
-  collision policy, rotation, fixed/variable anchoring, line constraints, and zoom range.
+- `TextStyle`: field, exact font face, exact fallback faces, size, color, halo, line-fitted
+  background, spacing metrics, transform, collision policy, rotation, fixed/variable anchoring, line
+  constraints, and zoom range.
 - `IconStyle`: image, size, color, halo, rotation/alignment, collision policy, and zoom range.
 - `CircleStyle`: radius, fill/stroke appearance, blur, opacity, pitch behavior, and zoom range.
 - `ExtrusionStyle`: color, height, base, opacity, pattern, vertical gradient, and zoom range.
@@ -20,3 +21,61 @@ Compounds express common cartographic structures: `AreaStyle` has `fill` and `ou
 `LineStackStyle` has `shadow`, `casing`, and `fill`, and `SymbolStyle` combines placement with
 optional `text`, `icon`, and `marker`. Geographic selection remains owned by semantic modules;
 ordinary visual styles intentionally do not accept raw source filters.
+
+## Line-fitted text backgrounds
+
+`text.background` draws one opaque strip behind each shaped line of a label, fitted to that line's
+own width. Use it for captions whose lines differ in length, where a stretched icon plate
+(`icon.textFit`) would cover the whole block.
+
+<!-- docs:check -->
+
+```ts
+import {fixed, poi, zoom} from '@tileflow/core';
+
+export const captions = poi({
+  categories: ['arts-entertainment'],
+  styles: {
+    'arts-entertainment': {
+      text: {
+        background: {
+          color: fixed('#080E11', {reason: 'Caption strip'}),
+          fit: 'lines',
+          padding: 0.33,
+        },
+        color: fixed('#ECEEE9', {reason: 'Caption text'}),
+        font: fixed('Noto Sans Bold', {reason: 'Caption face'}),
+        letterSpacing: fixed(0.08, {reason: 'Caption tracking'}),
+        lineHeight: fixed(1.2, {reason: 'Caption leading'}),
+        size: zoom.linear([
+          [14, 11],
+          [18, 14],
+        ]),
+      },
+    },
+  },
+});
+```
+
+Tileflow lowers the background to MapLibre properties only. `text-font` becomes a derived stack,
+such as `Noto Sans Bold lines-v1-t80-l1200-p330`. Its glyphs keep the source advances and shapes and
+add a rectangular cell, which the text halo paints. The halo width tracks `text-size / 6`, including
+zoom curves. Shaping, wrapping, collision, variable anchors, fading and right-to-left text therefore
+stay native, and the compiled style needs no runtime extension.
+
+- The colour must be opaque. Neighbouring cells overlap where they join.
+- `font` must name one stack served by the map's `glyphs` provider, without `fallbacks`. Maps that
+  use browser-rendered `fonts` reject backgrounds.
+- `letterSpacing` and `lineHeight` must be constants. The derived stack encodes them in thousandths
+  of an em, and the layer uses those rounded values. Tracking runs from 0 to 0.5em, leading from 0.8
+  to 3 and padding from 0 to 1em.
+- The background replaces the text halo. While a background is active, `haloWidth` and `haloBlur`
+  are derived, and `haloColor` is the strip colour. Later refinements of size, tracking, leading or
+  font re-derive the stack and halo.
+- Collision still reserves the shaped block. Padding beyond it is drawn outside that box, so keep
+  `padding` (text padding) at least as large as the strip padding in pixels.
+
+The map's `glyphs` provider must serve derived stacks. `deriveTileflowLineBackgroundGlyphs`
+computes any range from the source stack's range, and `parseTileflowLineBackgroundFontStack`
+recognises derived requests. Local previews and captures derive ranges themselves; hosted and
+self-hosted providers must do the same.

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

@@ -0,0 +1,165 @@
+# 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 change theme with a cross-fade, 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. They need a browser
+document and MapLibre GL JS; the React Native package does not offer them.
+
+## Cross-fade a theme change
+
+Pass `themeTransition` to the React, Vue, or Svelte map. 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} themeTransition={{duration: 450}} />
+    </>
+  );
+}
+```
+
+When the theme changes, a snapshot of the current frame covers the map. The snapshot follows the
+camera while people pan, zoom, rotate, or tilt, and fades out once the new theme is drawn. The map
+stays interactive throughout. `onThemeChange` reports `preloading`, `applying`, and finally `ready`
+after the fade. A `theme="system"` change, entering a blend, and leaving one use the same
+transition.
+
+`duration` is in milliseconds, from 0 to 5000. It defaults to 0, which changes 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, with `themeTransition` if set. 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.
+- 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 cross-fade
+  covers it.
+
+### 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, or glyphs.
+
+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.
+
+## 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 {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) {
+  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'), {transition: {duration: 450}});
+
+  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});
+  return controller.getBlend(); // {position: 0.6, themes: ['night', 'dusk', 'day']}
+}
+```
+
+`setTheme` and `setBlend` accept `{transition: {duration}}`;
+`createTileflowThemeController({transition})` sets a default. 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.

package/package.json

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