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

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;
@@ -32,7 +75,440 @@ declare function registerTileflowWorldRequestBridge(input: {
 declare function tileflowFairUseNoticeMessage(state: TileflowFairUseNoticeState): string;
 declare function attachTileflowFairUseNotice(container: HTMLElement): TileflowFairUseNoticeController;
 
+declare const expressionBrand: unique symbol;
+declare const themeValueBrand: unique symbol;
+declare const zoomBrand: unique symbol;
+declare const tileflowThemeTokenCategories: readonly ["color", "font", "image", "number"];
+type TileflowThemeTokenCategory = (typeof tileflowThemeTokenCategories)[number];
+type TileflowThemeTokenPrimitive = {
+    color: string;
+    font: string;
+    image: string;
+    number: number;
+};
+/** A JSON-safe semantic reference. The category is carried at runtime as well as in its type. */
+type TileflowThemeTokenReference<TCategory extends TileflowThemeTokenCategory = TileflowThemeTokenCategory> = {
+    readonly category: TCategory;
+    readonly kind: 'theme-token';
+    readonly token: string;
+    readonly [themeValueBrand]: TileflowThemeTokenPrimitive[TCategory];
+};
+/** An explicit opt-out from theme substitution. A reason is mandatory for auditability. */
+type TileflowFixedValue<T> = {
+    readonly kind: 'theme-fixed';
+    readonly reason: string;
+    readonly value: T;
+    readonly [themeValueBrand]: T;
+};
+type TileflowThemeColorMix = {
+    readonly amount: TileflowThemeNumberValue;
+    readonly from: TileflowThemeColorValue;
+    readonly kind: 'theme-color';
+    readonly operation: 'mix';
+    readonly space: 'oklch';
+    readonly to: TileflowThemeColorValue;
+    readonly [themeValueBrand]: string;
+};
+type TileflowThemeColorAlpha = {
+    readonly color: TileflowThemeColorValue;
+    readonly kind: 'theme-color';
+    readonly opacity: TileflowThemeNumberValue;
+    readonly operation: 'alpha';
+    readonly [themeValueBrand]: string;
+};
+type TileflowThemeColorOperation = TileflowThemeColorAlpha | TileflowThemeColorMix;
+type TileflowThemeNumberValue = number | TileflowFixedValue<number> | TileflowThemeTokenReference<'number'>;
+type TileflowThemeColorValue = string | TileflowFixedValue<string> | TileflowThemeColorOperation | TileflowThemeTokenReference<'color'>;
+type TileflowThemeFontValue = string | TileflowFixedValue<string> | TileflowThemeTokenReference<'font'>;
+type TileflowThemeImageValue = string | TileflowFixedValue<string> | TileflowThemeTokenReference<'image'>;
+type TileflowExpression<T> = {
+    readonly kind: 'expression';
+    readonly value: readonly unknown[];
+    /** Opaque result type. Only Tileflow's closed `expr.*` builders expose this brand publicly. */
+    readonly [expressionBrand]: T;
+};
+type TileflowZoomValueCommon<T> = {
+    readonly kind: 'zoom';
+    readonly stops: readonly (readonly [number, T])[];
+    readonly [zoomBrand]?: T;
+};
+type TileflowZoomValue<T> = TileflowZoomValueCommon<T> & ({
+    readonly base: number;
+    readonly interpolation: 'exponential';
+} | {
+    readonly base?: never;
+    readonly interpolation: 'linear' | 'step';
+});
+
+/** A color literal, semantic color token, color operation, expression, or zoom ramp. */
+type TileflowColorStyleValue = TileflowExpression<string> | TileflowThemeColorValue | TileflowZoomValue<TileflowThemeColorValue>;
+/** An image name, semantic image token, expression, or zoom ramp. */
+type TileflowImageStyleValue = TileflowExpression<string> | TileflowThemeImageValue | TileflowZoomValue<TileflowThemeImageValue>;
+/** A number, semantic number token, expression, or zoom ramp. */
+type TileflowNumberStyleValue = TileflowExpression<number> | TileflowThemeNumberValue | TileflowZoomValue<TileflowThemeNumberValue>;
+/** A visual numeric array whose components may be themed, or whose full shape is fixed. */
+type TileflowThemeNumberArrayValue = readonly TileflowThemeNumberValue[] | TileflowFixedValue<readonly number[]>;
+/** A visual numeric array, expression, or zoom ramp with explicit theme intent. */
+type TileflowNumberArrayStyleValue = TileflowExpression<readonly number[]> | TileflowThemeNumberArrayValue | TileflowZoomValue<TileflowThemeNumberArrayValue>;
+/** A two-dimensional visual offset with category-safe numeric components. */
+type TileflowNumberOffsetStyleValue = readonly [TileflowThemeNumberValue, TileflowThemeNumberValue] | TileflowFixedValue<readonly number[]> | TileflowExpression<readonly number[]> | TileflowZoomValue<readonly [TileflowThemeNumberValue, TileflowThemeNumberValue] | TileflowFixedValue<readonly number[]>>;
+/** Top, right, bottom, and left visual insets with category-safe numeric components. */
+type TileflowNumberInsetsStyleValue = readonly [
+    TileflowThemeNumberValue,
+    TileflowThemeNumberValue,
+    TileflowThemeNumberValue,
+    TileflowThemeNumberValue
+] | TileflowFixedValue<readonly [number, number, number, number]> | TileflowExpression<readonly number[]> | TileflowZoomValue<readonly [
+    TileflowThemeNumberValue,
+    TileflowThemeNumberValue,
+    TileflowThemeNumberValue,
+    TileflowThemeNumberValue
+] | TileflowFixedValue<readonly [number, number, number, number]>>;
+/** A structural value that does not participate in semantic theme-token substitution. */
+type TileflowStructuralStyleValue<T> = T | TileflowExpression<T> | TileflowZoomValue<T>;
+/** Structural text, including expressions and zoom-dependent literal strings. */
+type TileflowStringStyleValue = TileflowStructuralStyleValue<string>;
+type TileflowLineCap = 'butt' | 'round' | 'square';
+type TileflowLineJoin = 'bevel' | 'miter' | 'round';
+type TileflowSymbolPlacement = 'line' | 'line-center' | 'point';
+type TileflowSymbolZOrder = 'auto' | 'source' | 'viewport-y';
+type TileflowPriorityOrder = 'higher-first' | 'lower-first';
+type TileflowTextAnchor = 'bottom' | 'bottom-left' | 'bottom-right' | 'center' | 'left' | 'right' | 'top' | 'top-left' | 'top-right';
+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;
+    minZoom?: number;
+    visible?: boolean;
+};
+type TileflowBackgroundPaint = {
+    color?: TileflowColorStyleValue;
+    opacity?: TileflowNumberStyleValue;
+    pattern?: TileflowImageStyleValue;
+};
+type TileflowBackgroundStyle = TileflowLayerRange & TileflowBackgroundPaint;
+type TileflowFillPaint = {
+    antialias?: boolean;
+    color?: TileflowColorStyleValue;
+    opacity?: TileflowNumberStyleValue;
+    pattern?: TileflowImageStyleValue;
+    translate?: TileflowNumberOffsetStyleValue;
+    translateAnchor?: 'map' | 'viewport';
+};
+type TileflowFillStyle = TileflowLayerRange & TileflowFillPaint;
+type TileflowLinePaint = {
+    blur?: TileflowNumberStyleValue;
+    color?: TileflowColorStyleValue;
+    dash?: TileflowNumberArrayStyleValue;
+    gapWidth?: TileflowNumberStyleValue;
+    offset?: TileflowNumberStyleValue;
+    opacity?: TileflowNumberStyleValue;
+    pattern?: TileflowImageStyleValue;
+    translate?: TileflowNumberOffsetStyleValue;
+    translateAnchor?: 'map' | 'viewport';
+    width?: TileflowNumberStyleValue;
+};
+type TileflowLineLayout = {
+    cap?: TileflowStructuralStyleValue<TileflowLineCap>;
+    join?: TileflowStructuralStyleValue<TileflowLineJoin>;
+    miterLimit?: TileflowNumberStyleValue;
+    roundLimit?: TileflowNumberStyleValue;
+};
+type TileflowLineStyle = TileflowLayerRange & TileflowLinePaint & TileflowLineLayout;
+/** Repeated diagonal marks placed along a stroked geographic feature. */
+type TileflowLineHatchStyle = TileflowLayerRange & {
+    angle?: TileflowNumberStyleValue;
+    color?: TileflowColorStyleValue;
+    opacity?: TileflowNumberStyleValue;
+    /** Sprite pattern clipped to the line deck; when set, it replaces glyph hatching. */
+    pattern?: TileflowImageStyleValue;
+    /**
+     * Intrinsic pixel heights available as `${pattern}-${width}` sprites. Tileflow
+     * selects the closest height to the rendered line width so marks retain a
+     * nearly fixed screen-pixel thickness instead of stretching with the road.
+     * Requires `pattern` to be a literal sprite-name prefix.
+     */
+    patternWidths?: TileflowThemeNumberArrayValue;
+    size?: TileflowNumberStyleValue;
+    spacing?: TileflowNumberStyleValue;
+};
+type TileflowTextPaint = {
+    color?: TileflowColorStyleValue;
+    haloBlur?: TileflowNumberStyleValue;
+    haloColor?: TileflowColorStyleValue;
+    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[];
+    ignorePlacement?: boolean;
+    justify?: TileflowTextJustify;
+    keepUpright?: boolean;
+    letterSpacing?: TileflowNumberStyleValue;
+    lineHeight?: TileflowNumberStyleValue;
+    maxAngle?: TileflowNumberStyleValue;
+    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;
+    rotate?: TileflowNumberStyleValue;
+    rotationAlignment?: TileflowAlignment;
+    size?: TileflowNumberStyleValue;
+    transform?: 'lowercase' | 'none' | 'uppercase';
+    variableAnchors?: readonly TileflowTextAnchor[];
+};
+type TileflowTextStyle = TileflowLayerRange & TileflowTextPaint & TileflowTextLayout;
+type TileflowIconPaint = {
+    color?: TileflowColorStyleValue;
+    haloBlur?: TileflowNumberStyleValue;
+    haloColor?: TileflowColorStyleValue;
+    haloWidth?: TileflowNumberStyleValue;
+    opacity?: TileflowNumberStyleValue;
+};
+type TileflowIconLayout = {
+    allowOverlap?: boolean;
+    anchor?: TileflowIconAnchor;
+    image?: TileflowImageStyleValue;
+    ignorePlacement?: boolean;
+    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;
+    rotationAlignment?: TileflowAlignment;
+    size?: TileflowNumberStyleValue;
+    textFit?: TileflowIconTextFit;
+    textFitPadding?: TileflowNumberInsetsStyleValue;
+};
+type TileflowIconStyle = TileflowLayerRange & TileflowIconPaint & TileflowIconLayout;
+type TileflowSymbolPlacementStyle = TileflowLayerRange & {
+    placement?: TileflowSymbolPlacement;
+    priority?: TileflowStructuralStyleValue<number>;
+    /** Collision order for the semantic priority value. Defaults to `higher-first`. */
+    priorityOrder?: TileflowPriorityOrder;
+    spacing?: TileflowNumberStyleValue;
+    zOrder?: TileflowSymbolZOrder;
+};
+type TileflowCirclePaint = {
+    blur?: TileflowNumberStyleValue;
+    color?: TileflowColorStyleValue;
+    opacity?: TileflowNumberStyleValue;
+    pitchAlignment?: 'map' | 'viewport';
+    pitchScale?: 'map' | 'viewport';
+    priority?: TileflowStructuralStyleValue<number>;
+    /** Drawing order for the semantic priority value. Defaults to `higher-first`. */
+    priorityOrder?: TileflowPriorityOrder;
+    radius?: TileflowNumberStyleValue;
+    strokeColor?: TileflowColorStyleValue;
+    strokeOpacity?: TileflowNumberStyleValue;
+    strokeWidth?: TileflowNumberStyleValue;
+    translate?: TileflowNumberOffsetStyleValue;
+    translateAnchor?: 'map' | 'viewport';
+};
+type TileflowCircleStyle = TileflowLayerRange & TileflowCirclePaint;
+type TileflowExtrusionPaint = {
+    base?: TileflowNumberStyleValue;
+    color?: TileflowColorStyleValue;
+    height?: TileflowNumberStyleValue;
+    opacity?: TileflowNumberStyleValue;
+    pattern?: TileflowImageStyleValue;
+    verticalGradient?: boolean;
+};
+type TileflowExtrusionStyle = TileflowLayerRange & TileflowExtrusionPaint;
+/** A polygon rendered as a fill and, when requested, a separate line layer. */
+type TileflowAreaStyle = {
+    fill?: TileflowFillStyle;
+    outline?: TileflowLineStyle;
+};
+/** The canonical ordered phases used for roads, aeroways, and other stroked paths. */
+type TileflowLineStackStyle = {
+    casing?: TileflowLineStyle;
+    fill?: TileflowLineStyle;
+    shadow?: TileflowLineStyle;
+};
+/** A symbol layer composed from one placement policy and optional text/icon parts. */
+type TileflowSymbolStyle = TileflowSymbolPlacementStyle & {
+    icon?: TileflowIconStyle;
+    text?: TileflowTextStyle;
+};
+/** A symbol style that may also materialize a separate circle marker layer. */
+type TileflowMarkerSymbolStyle = TileflowSymbolStyle & {
+    marker?: TileflowCircleStyle;
+};
+
 type TileflowColor = `#${string}`;
+type TileflowRoadDetail = 'none' | 'highways' | 'major' | 'streets' | 'all';
+type TileflowRoadClass = 'motorway' | 'trunk' | 'primary' | 'secondary' | 'tertiary' | 'minor' | 'service' | 'track' | 'pathway' | 'footway' | 'cycleway' | 'steps' | 'pedestrian';
+type TileflowRoadHierarchy = 'subtle' | 'clear' | 'strong';
+type TileflowRoadWeight = 'thin' | 'regular' | 'bold';
+type TileflowRoadOutline = 'none' | 'subtle' | 'strong';
+type TileflowRoadStructure = 'bridge' | 'surface' | 'tunnel';
+type TileflowRoadExtras = {
+    paths?: boolean;
+};
+type TileflowRoadLayerStyle = TileflowLineStackStyle & {
+    hatch?: TileflowLineHatchStyle;
+};
+type TileflowRoadTreatmentLineStyle = Pick<TileflowLinePaint, 'blur' | 'color' | 'dash' | 'gapWidth' | 'offset' | 'opacity' | 'width'>;
+type TileflowRoadTreatmentLayerStyle = {
+    casing?: TileflowRoadTreatmentLineStyle;
+    fill?: TileflowRoadTreatmentLineStyle;
+    shadow?: TileflowRoadTreatmentLineStyle;
+};
+type TileflowRoadTreatmentStyle = Partial<Record<TileflowRoadStructure, TileflowRoadTreatmentLayerStyle>> & {
+    enabled?: boolean;
+    widthScale?: TileflowThemeNumberValue;
+};
+type TileflowRoadModifier = 'construction' | 'expressway' | 'indoor' | 'official' | 'ramp' | 'unpaved';
+type TileflowRoadRestriction = 'access' | 'bicycle' | 'foot' | 'horse' | 'toll';
+type TileflowMountainBikeScale = '0' | '0+' | '1' | '1+' | '2' | '2+' | '3' | '3+' | '4' | '5' | '6';
+type TileflowRoadServiceType = 'alley' | 'crossover' | 'driveway' | 'parkingAisle' | 'yard';
+type TileflowRoadClassStyle = Partial<Record<TileflowRoadStructure, TileflowRoadLayerStyle>> & {
+    enabled?: boolean;
+};
+type TileflowRoadAreaStyle = {
+    pedestrian?: TileflowAreaStyle;
+    pier?: TileflowAreaStyle;
+    road?: TileflowAreaStyle;
+};
+type TileflowRoadCrossingStyle = Omit<TileflowIconStyle, 'image'> & Required<Pick<TileflowIconStyle, 'image'>>;
+type TileflowRoadRoundaboutStyle = {
+    casing?: TileflowCircleStyle;
+    fill?: TileflowCircleStyle;
+};
+type TileflowRoadSidewalkStyle = {
+    outline?: TileflowLineStyle;
+    pattern?: TileflowFillStyle;
+    surface?: TileflowFillStyle;
+};
+type TileflowRoadsModuleConfig = {
+    type: 'roads';
+    areas?: TileflowRoadAreaStyle;
+    classes?: Partial<Record<TileflowRoadClass, TileflowRoadClassStyle>>;
+    crossings?: TileflowRoadCrossingStyle;
+    detail?: TileflowRoadDetail;
+    extras?: TileflowRoadExtras;
+    hierarchy?: TileflowRoadHierarchy;
+    modifiers?: Partial<Record<TileflowRoadModifier, TileflowRoadTreatmentStyle>>;
+    mountainBike?: Partial<Record<TileflowMountainBikeScale, TileflowRoadTreatmentStyle>>;
+    oneWayMarkers?: boolean;
+    outline?: TileflowRoadOutline;
+    restrictions?: Partial<Record<TileflowRoadRestriction, TileflowRoadTreatmentStyle>>;
+    roundabouts?: TileflowRoadRoundaboutStyle;
+    serviceTypes?: Partial<Record<TileflowRoadServiceType, TileflowRoadTreatmentStyle>>;
+    sidewalks?: TileflowRoadSidewalkStyle;
+    structures?: Partial<Record<TileflowRoadStructure, TileflowRoadLayerStyle>>;
+    weight?: TileflowRoadWeight;
+    widthScale?: Partial<Record<TileflowRoadClass, TileflowThemeNumberValue>>;
+};
+type TileflowLabelDetail = 'none' | 'major' | 'all';
+type TileflowAerodromeCodeDetail = 'none' | 'iata' | 'all';
+type TileflowRoadLabelDetail = TileflowRoadDetail;
+type TileflowLabelLanguage = 'auto' | 'local' | 'en' | (string & {});
+type TileflowPlaceLabelClass = 'city' | 'continent' | 'country' | 'neighborhood' | 'other' | 'state' | 'town' | 'village';
+type TileflowWaterLabelClass = 'line' | 'ocean' | 'other' | 'waterway';
+type TileflowRoadShieldDetail = 'none' | 'major' | 'all';
+type TileflowLabelCollisionPriority = 'balanced' | 'navigation';
+type TileflowRoadShieldStyles = {
+    default?: TileflowSymbolStyle;
+    detail?: TileflowSymbolStyle;
+    kinds?: Record<string, {
+        image: TileflowThemeImageValue;
+    }>;
+    overview?: TileflowSymbolStyle;
+    textColors?: Record<string, {
+        color: TileflowThemeColorValue;
+    }>;
+};
+type TileflowLabelStyles = {
+    aerodrome?: TileflowSymbolStyle;
+    junctions?: TileflowSymbolStyle;
+    places?: Partial<Record<TileflowPlaceLabelClass, TileflowSymbolStyle>>;
+    roads?: Partial<Record<TileflowRoadClass, TileflowSymbolStyle>>;
+    shields?: TileflowRoadShieldStyles;
+    water?: Partial<Record<TileflowWaterLabelClass, TileflowSymbolStyle>>;
+};
+type TileflowLabelsModuleConfig = {
+    type: 'labels';
+    aerodromeCodes?: TileflowAerodromeCodeDetail;
+    collisionPriority?: TileflowLabelCollisionPriority;
+    junctions?: boolean;
+    language?: TileflowLabelLanguage;
+    places?: TileflowLabelDetail;
+    roadClasses?: readonly TileflowRoadClass[];
+    roads?: TileflowRoadLabelDetail;
+    shields?: TileflowRoadShieldDetail;
+    styles?: TileflowLabelStyles;
+    water?: TileflowLabelDetail;
+};
+/** Closed editorial vocabulary emitted by Tileflow World's canonical POI projection. */
+declare const tileflowPoiCategories: readonly ["arts-entertainment", "education", "food-drink", "landmark", "lodging", "medical", "park-nature", "public-services", "religion", "retail", "sport-leisure", "transport", "visitor-amenity"];
+type TileflowPoiCategory = (typeof tileflowPoiCategories)[number];
+type TileflowPoiDensity = 1 | 2 | 3 | 4 | 5;
+type TileflowPoiColorMode = 'uniform' | 'category';
+type TileflowPoiCategoryStyle = Omit<TileflowMarkerSymbolStyle, 'priority'> & {
+    /** Optional category-local cap within the module's canonical density tiers. */
+    density?: TileflowPoiDensity;
+};
+type TileflowPoiModuleConfig = {
+    type: 'poi';
+    categories?: readonly TileflowPoiCategory[];
+    color?: TileflowPoiColorMode;
+    density?: TileflowPoiDensity;
+    icons?: boolean;
+    labels?: boolean;
+    minZoom?: number;
+    placement?: {
+        coupleIconAndLabel?: boolean;
+        iconPadding?: number;
+        textPadding?: number;
+    };
+    styles?: Partial<Record<TileflowPoiCategory, TileflowPoiCategoryStyle>>;
+};
 type MapLibreSprite = string | Array<{
     id: string;
     url: string;
@@ -93,6 +569,217 @@ 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. */
+    labels?: TileflowSymbolStyle;
+};
+type TileflowAddressesModuleConfig = TileflowAddressesModuleOptions & {
+    type: 'addresses';
+};
+
+type TileflowAerowaysModuleOptions = {
+    area?: TileflowAreaStyle;
+    runway?: TileflowLineStackStyle;
+    runwayRef?: TileflowSymbolStyle;
+    taxiway?: TileflowLineStackStyle;
+};
+type TileflowAerowaysModuleConfig = TileflowAerowaysModuleOptions & {
+    type: 'aeroways';
+};
+
+type TileflowBoundariesModuleOptions = {
+    admin2?: TileflowLineStyle;
+    admin4?: TileflowLineStyle;
+    disputed?: TileflowLineStyle;
+    maritime?: TileflowLineStyle;
+};
+type TileflowBoundariesModuleConfig = TileflowBoundariesModuleOptions & {
+    type: 'boundaries';
+};
+
+type TileflowBuildingMode = '3d' | 'flat';
+type TileflowBuildingsModuleOptions = {
+    businessCorridor?: TileflowAreaStyle;
+    extrusion?: TileflowExtrusionStyle;
+    flat?: TileflowAreaStyle;
+    mode?: TileflowBuildingMode;
+};
+type TileflowBuildingsModuleConfig = TileflowBuildingsModuleOptions & {
+    type: 'buildings';
+};
+
+type TileflowLanduseClass = 'cemetery' | 'civic' | 'commercial' | 'education' | 'government' | 'industrial' | 'medical' | 'military' | 'parking' | 'railway' | 'recreation' | 'residential';
+type TileflowLandcoverClass = 'farmland' | 'flowerbed' | 'grass' | 'ice' | 'meadow' | 'protected' | 'recreationGround' | 'rock' | 'sand' | 'scrub' | 'urbanPark' | 'villageGreen' | 'wetland' | 'wood';
+type TileflowLandModuleOptions = {
+    background?: TileflowBackgroundStyle;
+    globalLandcover?: TileflowFillStyle;
+    landcover?: Partial<Record<TileflowLandcoverClass, TileflowAreaStyle>>;
+    landuse?: Partial<Record<TileflowLanduseClass, TileflowAreaStyle>>;
+};
+type TileflowLandModuleConfig = TileflowLandModuleOptions & {
+    type: 'land';
+};
+
+declare const tileflowLandformClasses: readonly ["peak", "volcano", "saddle", "ridge", "cliff", "arete"];
+type TileflowLandformClass = (typeof tileflowLandformClasses)[number];
+type TileflowLandformsModuleOptions = {
+    classes?: Partial<Record<TileflowLandformClass, TileflowSymbolStyle>>;
+    /** Append source elevation in metres when the feature provides it. */
+    elevation?: boolean;
+};
+type TileflowLandformsModuleConfig = TileflowLandformsModuleOptions & {
+    type: 'landforms';
+};
+
+/** Labels anchored inside polygon features; point-feature labels remain on their feature style. */
+type TileflowNauticalAreaLabelStyles = {
+    coverage?: TileflowSymbolStyle;
+    hazards?: TileflowSymbolStyle;
+    navigationAreas?: TileflowSymbolStyle;
+    reefs?: TileflowSymbolStyle;
+    wrecks?: TileflowSymbolStyle;
+};
+type TileflowNauticalModuleOptions = {
+    aids?: TileflowMarkerSymbolStyle;
+    coverage?: TileflowAreaStyle;
+    hazardAreas?: TileflowAreaStyle;
+    hazards?: TileflowMarkerSymbolStyle;
+    labels?: TileflowNauticalAreaLabelStyles;
+    lighthouses?: TileflowMarkerSymbolStyle;
+    lights?: TileflowMarkerSymbolStyle;
+    navigationAreas?: TileflowAreaStyle;
+    reefs?: TileflowAreaStyle;
+    soundings?: TileflowMarkerSymbolStyle;
+    wreckAreas?: TileflowAreaStyle;
+    wrecks?: TileflowMarkerSymbolStyle;
+};
+type TileflowNauticalModuleConfig = TileflowNauticalModuleOptions & {
+    type: 'nautical';
+};
+
+type TileflowTransitModuleOptions = {
+    cableway?: TileflowLineStyle;
+    ferry?: TileflowLineStyle;
+    rail?: TileflowTransitRailStyle;
+    railHatching?: TileflowTransitRailStyle;
+    serviceRail?: TileflowTransitRailStyle;
+};
+type TileflowTransitRailStyle = {
+    bridge?: TileflowLineStyle;
+    surface?: TileflowLineStyle;
+    tunnel?: TileflowLineStyle;
+};
+type TileflowTransitModuleConfig = TileflowTransitModuleOptions & {
+    type: 'transit';
+};
+
+type TileflowVegetationMode = '3d' | 'flat';
+type TileflowVegetationThreeDimensionalStyle = {
+    barkColor?: TileflowThemeColorValue;
+    broadleafColors?: readonly TileflowThemeColorValue[];
+    coniferColors?: readonly TileflowThemeColorValue[];
+    crownScale?: TileflowThemeNumberValue;
+    heightScale?: TileflowThemeNumberValue;
+};
+type TileflowVegetationModuleOptions = {
+    flat?: TileflowCircleStyle;
+    mode?: TileflowVegetationMode;
+    threeDimensional?: TileflowVegetationThreeDimensionalStyle;
+};
+type TileflowVegetationModuleConfig = TileflowVegetationModuleOptions & {
+    type: 'vegetation';
+};
+
+type TileflowWaterwayClass = 'canal' | 'other' | 'river' | 'stream';
+type TileflowWaterModuleOptions = {
+    bathymetry?: TileflowFillStyle;
+    /** Opt-in approximate contours traced from discrete bathymetry polygon band edges. */
+    bathymetryContours?: TileflowLineStyle;
+    /** Opt-in labels for bathymetry polygon band floors, not measured survey soundings. */
+    bathymetryLabels?: TileflowSymbolStyle;
+    bodies?: TileflowAreaStyle;
+    intermittent?: {
+        bodies?: TileflowAreaStyle;
+        waterways?: TileflowLineStyle;
+    };
+    waterways?: Partial<Record<TileflowWaterwayClass, TileflowLineStyle>>;
+};
+type TileflowWaterModuleConfig = TileflowWaterModuleOptions & {
+    type: 'water';
+};
+
+type TileflowSemanticModules = {
+    addresses?: TileflowAddressesModuleConfig;
+    aeroways?: TileflowAerowaysModuleConfig;
+    boundaries?: TileflowBoundariesModuleConfig;
+    buildings?: TileflowBuildingsModuleConfig;
+    labels?: TileflowLabelsModuleConfig;
+    land?: TileflowLandModuleConfig;
+    landforms?: TileflowLandformsModuleConfig;
+    nautical?: TileflowNauticalModuleConfig;
+    poi?: TileflowPoiModuleConfig;
+    roads?: TileflowRoadsModuleConfig;
+    transit?: TileflowTransitModuleConfig;
+    vegetation?: TileflowVegetationModuleConfig;
+    water?: TileflowWaterModuleConfig;
+};
+type TileflowSemanticModuleName = keyof TileflowSemanticModules;
+
+/**
+ * Layer metadata naming the semantic module that owns a compiled layer, such as `roads` or `water`.
+ * Runtime features that address a module, such as map emphasis, read it instead of physical layer
+ * IDs. Layers that a theme blend splits or copies keep it.
+ */
+declare const tileflowLayerDomainMetadataKey: "tileflow:domain";
+
+type TileflowLayerDomain = TileflowSemanticModuleName | 'terrain';
+
+/**
+ * Map emphasis lets an application's own content read first: chosen modules of the map recede
+ * towards the map's ground colour, and the map's labels and icons fade, except inside an area the
+ * application keeps at full strength. It only touches layers that a Tileflow map compiled, which
+ * name their module in their metadata; an application's own layers are never changed.
+ *
+ * This module plans which paint values an emphasis changes and computes each value for a strength
+ * from 0 (the map as designed) to 1 (the full emphasis). The browser controller writes them.
+ */
+/** A module of a compiled Tileflow map, such as `roads`, `transit`, `boundaries`, or `water`. */
+type TileflowEmphasisModule = TileflowLayerDomain;
+/** A GeoJSON polygon or multipolygon, in longitude and latitude. */
+type TileflowEmphasisArea = Readonly<{
+    coordinates: readonly (readonly (readonly number[])[])[];
+    type: 'Polygon';
+}> | Readonly<{
+    coordinates: readonly (readonly (readonly (readonly number[])[])[])[];
+    type: 'MultiPolygon';
+}>;
+/** How the map steps back so an application's content reads first. */
+type TileflowEmphasis = Readonly<{
+    /**
+     * Modules whose ground recedes towards the map's ground colour, and how far, from 0 (as
+     * designed) to 1 (the ground colour itself). Artwork that cannot be recoloured, such as
+     * patterns, fades by the same amount instead.
+     */
+    recede?: Readonly<Partial<Record<TileflowEmphasisModule, number>>>;
+    /** The share of their opacity the map's labels and icons keep, from 0 to 1. */
+    labels?: number;
+    /** An area in which the map's labels and icons keep their full strength. */
+    keep?: TileflowEmphasisArea;
+}>;
+/** Why an emphasis cannot be shown, or undefined when it can. */
+declare function validateTileflowEmphasis(value: unknown): TypeError | undefined;
 
 /**
  * Browser helpers for theme transitions and blends. They use only methods that MapLibre GL JS maps
@@ -102,6 +789,8 @@ type TileflowThemeMotionMap = {
     areTilesLoaded?: unknown;
     getCanvas?: unknown;
     getImage?: unknown;
+    getLayer?: unknown;
+    getStyle?: unknown;
     isStyleLoaded?: unknown;
     off(event: string, listener: (event?: unknown) => void): unknown;
     on(event: string, listener: (event?: unknown) => void): unknown;
@@ -166,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<{
@@ -221,28 +910,78 @@ 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
      * position and take effect at once, so they can follow an animation or a slider.
      */
     setBlend(request: TileflowThemeBlendRequest, options?: TileflowThemeChangeOptions): Promise<TileflowThemeTransitionResult>;
+    /**
+     * Makes chosen modules of the map recede and its labels and icons fade, so an application's own
+     * content reads first; `undefined` returns the map to its design. The change eases over the
+     * transition, and the emphasis stays through later theme changes and blend positions. Values
+     * 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>;
 };
 /**
@@ -293,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;
@@ -312,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 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 };
+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 };