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

package/dist/browser.d.ts

@@ -32,7 +32,423 @@ 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';
+/** 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;
+    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;
+    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;
@@ -94,6 +510,207 @@ type TileflowStyleFontFace = {
     weight?: '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900';
 };
 
+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;
+    minZoom?: number;
+    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
  * provide and check each one at runtime, so a map without them falls back to an immediate change.
@@ -102,6 +719,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;
@@ -237,12 +856,21 @@ type TileflowThemeController = {
     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;
     /**
      * 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>;
     setTheme(style: TileflowRuntimeStyle, options?: TileflowThemeChangeOptions): Promise<TileflowThemeTransitionResult>;
 };
 /**
@@ -331,4 +959,4 @@ declare function createTileflowTransformRequest<TRequest extends TileflowTransfo
     worldRequestBridge?: TileflowWorldRequestBridge;
 }): TileflowTransformRequest<TRequest, TResourceType> | undefined;
 
-export { type TileflowAsyncAnalyticsTiming, type TileflowAtmosphereMap, type TileflowComposedRequest, type TileflowContourProtocolHandler, type TileflowContourProtocolRegistrationOptions, type TileflowContourProtocolRegistry, type TileflowContourProtocolRequest, type TileflowContourProtocolResponse, type TileflowFairUseNotice, type TileflowFairUseNoticeController, type TileflowFairUseNoticeState, type TileflowFrameScheduler, type TileflowMapLifecycleAttachment, type TileflowMapLifecycleEvent, type TileflowMapLifecycleSubscriber, type TileflowMapReadinessState, type TileflowPmtilesProtocolHandler, type TileflowPmtilesProtocolRegistrationOptions, type TileflowPmtilesProtocolRegistry, type TileflowSessionSender, type TileflowSessionStarter, type TileflowStyleFontLoadOptions, type TileflowStyleSwitchMap, type 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 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 };