@tileflow/core 0.1.0-alpha.35 → 0.1.0-alpha.37

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/browser.d.ts CHANGED
@@ -380,386 +380,6 @@ type TileflowMarkerSymbolStyle = TileflowSymbolStyle & {
380
380
  marker?: TileflowCircleStyle;
381
381
  };
382
382
 
383
- type TileflowColor = `#${string}`;
384
- type TileflowRoadDetail = 'none' | 'highways' | 'major' | 'streets' | 'all';
385
- type TileflowRoadClass = 'motorway' | 'trunk' | 'primary' | 'secondary' | 'tertiary' | 'minor' | 'service' | 'track' | 'pathway' | 'footway' | 'cycleway' | 'steps' | 'pedestrian';
386
- type TileflowRoadHierarchy = 'subtle' | 'clear' | 'strong';
387
- type TileflowRoadWeight = 'thin' | 'regular' | 'bold';
388
- type TileflowRoadOutline = 'none' | 'subtle' | 'strong';
389
- type TileflowRoadStructure = 'bridge' | 'surface' | 'tunnel';
390
- type TileflowRoadExtras = {
391
- paths?: boolean;
392
- };
393
- type TileflowRoadLayerStyle = TileflowLineStackStyle & {
394
- hatch?: TileflowLineHatchStyle;
395
- };
396
- type TileflowRoadTreatmentLineStyle = Pick<TileflowLinePaint, 'blur' | 'color' | 'dash' | 'gapWidth' | 'offset' | 'opacity' | 'width'>;
397
- type TileflowRoadTreatmentLayerStyle = {
398
- casing?: TileflowRoadTreatmentLineStyle;
399
- fill?: TileflowRoadTreatmentLineStyle;
400
- shadow?: TileflowRoadTreatmentLineStyle;
401
- };
402
- type TileflowRoadTreatmentStyle = Partial<Record<TileflowRoadStructure, TileflowRoadTreatmentLayerStyle>> & {
403
- enabled?: boolean;
404
- widthScale?: TileflowThemeNumberValue;
405
- };
406
- type TileflowRoadModifier = 'construction' | 'expressway' | 'indoor' | 'official' | 'ramp' | 'unpaved';
407
- type TileflowRoadRestriction = 'access' | 'bicycle' | 'foot' | 'horse' | 'toll';
408
- type TileflowMountainBikeScale = '0' | '0+' | '1' | '1+' | '2' | '2+' | '3' | '3+' | '4' | '5' | '6';
409
- type TileflowRoadServiceType = 'alley' | 'crossover' | 'driveway' | 'parkingAisle' | 'yard';
410
- type TileflowRoadClassStyle = Partial<Record<TileflowRoadStructure, TileflowRoadLayerStyle>> & {
411
- enabled?: boolean;
412
- };
413
- type TileflowRoadAreaStyle = {
414
- pedestrian?: TileflowAreaStyle;
415
- pier?: TileflowAreaStyle;
416
- road?: TileflowAreaStyle;
417
- };
418
- type TileflowRoadCrossingStyle = Omit<TileflowIconStyle, 'image'> & Required<Pick<TileflowIconStyle, 'image'>>;
419
- type TileflowRoadRoundaboutStyle = {
420
- casing?: TileflowCircleStyle;
421
- fill?: TileflowCircleStyle;
422
- };
423
- /**
424
- * How Core's street lights renderer lights the map's streets at night, from the lamps and lit
425
- * streets its data holds.
426
- */
427
- type TileflowRoadStreetLightStyle = {
428
- /** The light of lamps whose data gives no colour; a warm white by default. */
429
- color?: TileflowThemeColorValue;
430
- /** Whether the map has street lights; defaults to true where the data binds street furniture. */
431
- enabled?: boolean;
432
- /**
433
- * Where light is estimated where the data maps no lamps: `lit` (the default) along streets and
434
- * pavements mapped as lit; `streets` also along streets the data says nothing about, in tiles
435
- * that map few lamps, which invents light; `none` nowhere.
436
- */
437
- estimate?: 'lit' | 'streets' | 'none';
438
- /** How bright the lights shine, from 0 to 2; defaults to 1. */
439
- intensity?: TileflowThemeNumberValue;
440
- };
441
- type TileflowRoadSidewalkStyle = {
442
- outline?: TileflowLineStyle;
443
- pattern?: TileflowFillStyle;
444
- surface?: TileflowFillStyle;
445
- };
446
- type TileflowRoadsModuleConfig = {
447
- type: 'roads';
448
- areas?: TileflowRoadAreaStyle;
449
- classes?: Partial<Record<TileflowRoadClass, TileflowRoadClassStyle>>;
450
- crossings?: TileflowRoadCrossingStyle;
451
- detail?: TileflowRoadDetail;
452
- extras?: TileflowRoadExtras;
453
- hierarchy?: TileflowRoadHierarchy;
454
- modifiers?: Partial<Record<TileflowRoadModifier, TileflowRoadTreatmentStyle>>;
455
- mountainBike?: Partial<Record<TileflowMountainBikeScale, TileflowRoadTreatmentStyle>>;
456
- oneWayMarkers?: boolean;
457
- outline?: TileflowRoadOutline;
458
- restrictions?: Partial<Record<TileflowRoadRestriction, TileflowRoadTreatmentStyle>>;
459
- roundabouts?: TileflowRoadRoundaboutStyle;
460
- serviceTypes?: Partial<Record<TileflowRoadServiceType, TileflowRoadTreatmentStyle>>;
461
- sidewalks?: TileflowRoadSidewalkStyle;
462
- streetLights?: TileflowRoadStreetLightStyle;
463
- structures?: Partial<Record<TileflowRoadStructure, TileflowRoadLayerStyle>>;
464
- weight?: TileflowRoadWeight;
465
- widthScale?: Partial<Record<TileflowRoadClass, TileflowThemeNumberValue>>;
466
- };
467
- type TileflowLabelDetail = 'none' | 'major' | 'all';
468
- type TileflowAerodromeCodeDetail = 'none' | 'iata' | 'all';
469
- type TileflowRoadLabelDetail = TileflowRoadDetail;
470
- type TileflowLabelLanguage = 'auto' | 'local' | 'en' | (string & {});
471
- type TileflowPlaceLabelClass = 'city' | 'continent' | 'country' | 'neighborhood' | 'other' | 'state' | 'town' | 'village';
472
- type TileflowWaterLabelClass = 'line' | 'ocean' | 'other' | 'waterway';
473
- type TileflowRoadShieldDetail = 'none' | 'major' | 'all';
474
- type TileflowLabelCollisionPriority = 'balanced' | 'navigation';
475
- type TileflowRoadShieldStyles = {
476
- default?: TileflowSymbolStyle;
477
- detail?: TileflowSymbolStyle;
478
- kinds?: Record<string, {
479
- image: TileflowThemeImageValue;
480
- }>;
481
- overview?: TileflowSymbolStyle;
482
- textColors?: Record<string, {
483
- color: TileflowThemeColorValue;
484
- }>;
485
- };
486
- type TileflowLabelStyles = {
487
- aerodrome?: TileflowSymbolStyle;
488
- junctions?: TileflowSymbolStyle;
489
- places?: Partial<Record<TileflowPlaceLabelClass, TileflowSymbolStyle>>;
490
- roads?: Partial<Record<TileflowRoadClass, TileflowSymbolStyle>>;
491
- shields?: TileflowRoadShieldStyles;
492
- water?: Partial<Record<TileflowWaterLabelClass, TileflowSymbolStyle>>;
493
- };
494
- type TileflowLabelsModuleConfig = {
495
- type: 'labels';
496
- aerodromeCodes?: TileflowAerodromeCodeDetail;
497
- collisionPriority?: TileflowLabelCollisionPriority;
498
- junctions?: boolean;
499
- language?: TileflowLabelLanguage;
500
- places?: TileflowLabelDetail;
501
- roadClasses?: readonly TileflowRoadClass[];
502
- roads?: TileflowRoadLabelDetail;
503
- shields?: TileflowRoadShieldDetail;
504
- styles?: TileflowLabelStyles;
505
- water?: TileflowLabelDetail;
506
- };
507
- /** Closed editorial vocabulary emitted by Tileflow World's canonical POI projection. */
508
- declare const tileflowPoiCategories: readonly ["arts-entertainment", "education", "food-drink", "landmark", "lodging", "medical", "park-nature", "public-services", "religion", "retail", "sport-leisure", "transport", "visitor-amenity"];
509
- type TileflowPoiCategory = (typeof tileflowPoiCategories)[number];
510
- type TileflowPoiDensity = 1 | 2 | 3 | 4 | 5;
511
- type TileflowPoiColorMode = 'uniform' | 'category';
512
- /**
513
- * How POI categories are placed against each other. `importance` places every category in one
514
- * order, by World's ranks. `categories` gives each category its own layer and places the
515
- * categories in the order they are listed, the first on top; ranks order each category only.
516
- */
517
- type TileflowPoiPlacementOrder = 'categories' | 'importance';
518
- /**
519
- * The appearance of one POI category. With the default `importance` order every category shares
520
- * one placement layer, so categories may differ only in properties MapLibre evaluates per feature
521
- * (image, size, colors, font, offsets); layer-wide properties such as zoom ranges, padding,
522
- * overlap or `optional` must match, or the module uses `placement.order: 'categories'`.
523
- */
524
- type TileflowPoiCategoryStyle = Omit<TileflowMarkerSymbolStyle, 'priority'>;
525
- type TileflowPoiModuleConfig = {
526
- type: 'poi';
527
- categories?: readonly TileflowPoiCategory[];
528
- color?: TileflowPoiColorMode;
529
- /** One density for the whole module: World's ranks decide what each category shows. */
530
- density?: TileflowPoiDensity;
531
- icons?: boolean;
532
- labels?: boolean;
533
- minZoom?: number;
534
- placement?: {
535
- /**
536
- * Places each pictogram with its name as one unit that needs room for both. Defaults to
537
- * `false`.
538
- */
539
- coupleIconAndLabel?: boolean;
540
- iconPadding?: number;
541
- /**
542
- * World POI `type` values whose pictogram explains them. When pictograms and names are both
543
- * drawn, every other POI needs a name, and these types are drawn as a pictogram alone.
544
- * Defaults to parking and public toilets.
545
- */
546
- iconOnlyTypes?: readonly string[];
547
- /** Defaults to `importance`. */
548
- order?: TileflowPoiPlacementOrder;
549
- /**
550
- * With the `importance` order, POIs whose World `filter_rank` is at most this value are placed
551
- * before the map's road and place labels, and the others after them. A map that gives street
552
- * names priority over POIs (labels `collisionPriority: 'navigation'`) keeps its landmarks this
553
- * way. Unset, every POI is placed at the module's own position.
554
- */
555
- prominentRank?: 0 | 1 | 2 | 3 | 4 | 5;
556
- textPadding?: number;
557
- };
558
- styles?: Partial<Record<TileflowPoiCategory, TileflowPoiCategoryStyle>>;
559
- };
560
- type MapLibreSprite = string | Array<{
561
- id: string;
562
- url: string;
563
- }>;
564
- type TileflowProjection = 'globe' | 'mercator';
565
- type TileflowLight = {
566
- anchor?: 'map' | 'viewport';
567
- color?: TileflowColor;
568
- intensity?: number;
569
- position?: readonly [number, number, number];
570
- };
571
- type MapLibreStyle = {
572
- sky?: Record<string, unknown>;
573
- version: 8;
574
- name: string;
575
- glyphs?: string;
576
- light?: TileflowLight;
577
- projection?: {
578
- type: TileflowProjection;
579
- };
580
- sprite?: MapLibreSprite;
581
- sources: Record<string, Record<string, unknown>>;
582
- layers: Array<Record<string, unknown>>;
583
- terrain?: Record<string, unknown>;
584
- metadata?: Record<string, unknown>;
585
- };
586
-
587
- declare const tileflowSunMetadataKey = "tileflow:sun";
588
- /** A theme's sun and sky light with every value resolved; see `TileflowThemeSun`. */
589
- type TileflowSunPreset = Readonly<{
590
- /** Degrees clockwise from north, from 0 to 360. */
591
- azimuth: number;
592
- /** Degrees above the horizon, from -90 to 90. */
593
- altitude: number;
594
- /** The direct light's colour. */
595
- color: string;
596
- /** The direct light's strength, from 0 to 1. */
597
- intensity: number;
598
- /** How dark the shadows the sun casts fall, from 0 (none) to 1. */
599
- shadowIntensity: number;
600
- /** The light from the sky, which reaches every surface and fills the shadows. */
601
- ambient: Readonly<{
602
- color: string;
603
- intensity: number;
604
- }>;
605
- }>;
606
- /** The sun as the map shows it, ready for an application's own layers. */
607
- type TileflowSun = Readonly<{
608
- /** Degrees clockwise from north, from 0 to 360. */
609
- azimuth: number;
610
- /** Degrees above the horizon, from -90 to 90. */
611
- altitude: number;
612
- /** A unit vector towards the sun: x east, y north, z up. */
613
- direction: readonly [number, number, number];
614
- /** The direct light's colour, as a CSS colour. */
615
- color: string;
616
- /** The direct light's colour as sRGB channels from 0 to 1. */
617
- rgb: readonly [number, number, number];
618
- /**
619
- * The direct light's strength, from 0 to 1. It fades to 0 as the sun sets: a sun below the
620
- * horizon lights nothing and casts no shadow.
621
- */
622
- intensity: number;
623
- /** How dark the shadows the sun casts fall, from 0 (none) to 1. */
624
- shadowIntensity: number;
625
- /** The light from the sky, which reaches every surface and fills the shadows. */
626
- ambient: Readonly<{
627
- color: string;
628
- rgb: readonly [number, number, number];
629
- intensity: number;
630
- }>;
631
- /**
632
- * How bright flat, open ground is under this light, from 0 (dark) to 1: the sky's light plus the
633
- * sun's at its height, each weighted by its colour's luminance. Use it to switch lamps or windows
634
- * on as a scene darkens, whatever theme or sun lights it.
635
- */
636
- brightness: number;
637
- /** Where the direction comes from: the themes, angles, or a date and place. */
638
- source: 'theme' | 'direction' | 'date';
639
- }>;
640
- /** The sun of a theme that leaves a value unset: high in the south-south-west, in white light. */
641
- declare const tileflowDefaultSunPreset: TileflowSunPreset;
642
- /**
643
- * Where the sun stands for an instant and a place ([longitude, latitude] in degrees): its azimuth
644
- * in degrees clockwise from north and its apparent altitude above the horizon, with atmospheric
645
- * refraction. It follows NOAA's solar equations, accurate to about a hundredth of a degree for
646
- * years 1800 to 2200.
647
- */
648
- declare function tileflowSunPosition(date: Date | number, location: readonly [number, number]): Readonly<{
649
- azimuth: number;
650
- altitude: number;
651
- }>;
652
- /** A unit vector towards a direction in the sky: x east, y north, z up. */
653
- declare function tileflowSunDirection(azimuth: number, altitude: number): readonly [number, number, number];
654
- /**
655
- * The sun as the map shows it: a preset's light from a direction. Direct light fades out over the
656
- * sun's last degrees above the horizon and is gone below it.
657
- */
658
- declare function resolveTileflowSun(preset: TileflowSunPreset, direction?: Readonly<{
659
- azimuth: number;
660
- altitude: number;
661
- }>, source?: TileflowSun['source']): TileflowSun;
662
- /**
663
- * A preset `t` of the way from `from` to `to`: the azimuth turns the short way round, colours mix
664
- * in OKLab, as theme blends mix paint colours, and numbers linearly.
665
- */
666
- declare function mixTileflowSunPresets(from: TileflowSunPreset, to: TileflowSunPreset, t: number): TileflowSunPreset;
667
- /** Reads the sun a compiled style publishes, or undefined when its metadata has none. */
668
- declare function readTileflowSunPreset(metadata: unknown): TileflowSunPreset | undefined;
669
- /**
670
- * The sun of a compiled style: the one it publishes, else one read from its light (a style whose
671
- * theme describes no sun lights its extrusions from `light.position`), else the default.
672
- */
673
- declare function tileflowStyleSunPreset(style: {
674
- light?: unknown;
675
- metadata?: unknown;
676
- } | undefined): TileflowSunPreset;
677
-
678
- type TileflowThemeColorScheme = 'dark' | 'light';
679
-
680
- declare const tileflowRouteMetadataKey = "tileflow:route";
681
- /** The resolved inks of a route, from its outer glow to its bright core. */
682
- type TileflowRouteInks = Readonly<{
683
- /** The chosen route's line. */
684
- line: string;
685
- /** The edge on each side of the line, which sets it apart from the roads under it. */
686
- casing: string;
687
- /** A thin line along the middle of the route. */
688
- core: string;
689
- /** A soft halo around the route. */
690
- glow: string;
691
- /** Other routes offered beside the chosen one. */
692
- alternative: string;
693
- /** Opacity of the glow, from 0 (no glow) to 1. */
694
- glowOpacity: number;
695
- /** Opacity of the core, from 0 (no core) to 1. */
696
- coreOpacity: number;
697
- }>;
698
- /** The inks of a theme that sets no route tokens: a blue that reads on either kind of map. */
699
- declare const tileflowDefaultRouteInks: Readonly<Record<TileflowThemeColorScheme, TileflowRouteInks>>;
700
- /**
701
- * Reads the route inks a compiled style publishes, or undefined when its metadata has none (a
702
- * style compiled before route inks, or not by Tileflow).
703
- */
704
- declare function readTileflowRouteInks(metadata: unknown): TileflowRouteInks | undefined;
705
- /**
706
- * The route inks of a compiled style: those it publishes, or the defaults of its colour scheme
707
- * (from its `tileflow:colorScheme` metadata, else `fallbackScheme`).
708
- */
709
- declare function tileflowStyleRouteInks(style: {
710
- metadata?: unknown;
711
- } | undefined, fallbackScheme?: TileflowThemeColorScheme): TileflowRouteInks;
712
- /**
713
- * Inks between two themes' inks, `t` of the way from `from` to `to`: colours mix in OKLab, as theme
714
- * blends mix paint colours, and opacities linearly.
715
- */
716
- declare function mixTileflowRouteInks(from: TileflowRouteInks, to: TileflowRouteInks, t: number): TileflowRouteInks;
717
-
718
- type TileflowRuntimeColorScheme = 'dark' | 'light';
719
-
720
- type TileflowAnalytics = {
721
- apiUrl?: string;
722
- endpoint?: string;
723
- enabled?: boolean;
724
- mapId?: string;
725
- metadata?: Record<string, unknown>;
726
- projectId?: string;
727
- sdkVersion?: string;
728
- source?: string;
729
- styleId?: string;
730
- surfaceId?: string;
731
- };
732
- type TileflowSessionController = {
733
- readonly sessionId: string;
734
- resolveRequestUrl(url: string, analytics: TileflowAnalytics | undefined): Promise<string | undefined>;
735
- };
736
- type TileflowRuntimeStyle = {
737
- analytics?: TileflowAnalytics;
738
- colorScheme?: TileflowRuntimeColorScheme;
739
- /** An explicit empty array means the manifest declares that no web fonts are required. */
740
- fontFaces?: TileflowStyleFontFace[];
741
- revision?: string;
742
- style: MapLibreStyle | string;
743
- theme?: string;
744
- };
745
- type TileflowStyleFontFace = {
746
- family: string;
747
- source: string;
748
- style?: 'italic' | 'normal' | 'oblique';
749
- weight?: '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900';
750
- };
751
- /**
752
- * A continuous blend of named themes of one Tileflow map. `position` places the map between
753
- * neighbouring themes: 0 is the first, 1 the second, and 1.25 a quarter of the way from the second
754
- * to the third.
755
- */
756
- type TileflowThemeBlendSelection = Readonly<{
757
- /** From 0 to `themes.length - 1`. */
758
- position: number;
759
- /** Two to eight concrete theme names of the map, in blend order. */
760
- themes: readonly string[];
761
- }>;
762
-
763
383
  type TileflowAddressesModuleOptions = {
764
384
  /** Styling for OpenMapTiles point house-number labels. */
765
385
  labels?: TileflowSymbolStyle;
@@ -788,25 +408,92 @@ type TileflowBoundariesModuleConfig = TileflowBoundariesModuleOptions & {
788
408
  type: 'boundaries';
789
409
  };
790
410
 
411
+ /** The parts of a model, each coloured by the theme: the model's materials name them. */
412
+ declare const tileflowModelParts: Readonly<{
413
+ surface: 0;
414
+ secondary: 1;
415
+ glass: 2;
416
+ accent: 3;
417
+ roof: 4;
418
+ }>;
419
+ type TileflowModelPart = keyof typeof tileflowModelParts;
420
+ /** Architectural roles control lighting independently of the model's palette slots. */
421
+ declare const tileflowModelLightingRoles: Readonly<{
422
+ unclassified: 0;
423
+ wall: 1;
424
+ door: 2;
425
+ roof: 3;
426
+ window: 4;
427
+ lamp: 5;
428
+ logo: 6;
429
+ }>;
430
+ type TileflowModelLightingRole = keyof typeof tileflowModelLightingRoles;
431
+
791
432
  type TileflowBuildingMode = '3d' | 'flat';
792
433
  /**
793
434
  * How Core's 3D buildings renderer draws the map's buildings. Their colour is the map's own 3D
794
435
  * building colour (its extrusion), else its roofs'.
795
436
  */
796
437
  type TileflowBuildingsThreeDimensionalStyle = {
797
- /** Use the style's extrusion light (default), or the theme controller's scene sun. */
438
+ /** Use the scene sun (default), or the style's native extrusion light. */
798
439
  lighting?: 'style' | 'sun';
799
440
  /** Per-building brightness variation, from 0 to 1; defaults to 0 (authored colour). */
800
441
  colorVariation?: TileflowThemeNumberValue;
801
442
  /** How strongly roof outlines and outer corners catch the light, from 0 (default) to 1. */
802
443
  edges?: TileflowThemeNumberValue;
444
+ /** Radius in metres for softened exterior corners and roof lighting, from 0 to 1; defaults to 0.8. */
445
+ edgeRadius?: number;
803
446
  /** Their own colour, drawn unlit; without it they take the building's colour, lightened. */
804
447
  edgeColor?: TileflowThemeColorValue;
805
448
  /** How bright the buildings light the street at night, from 0 (none) to 2; defaults to 0. */
806
449
  nightLight?: TileflowThemeNumberValue;
807
- /** Contact shadow at the foot of the walls and in tight corners; defaults to false. */
450
+ /** Height-selected architectural flood lighting. Off by default; follows scene darkness. */
451
+ floodLight?: {
452
+ intensity?: TileflowThemeNumberValue;
453
+ /** Compensates authored light-colour transforms during darkness evaluation; defaults to 1. */
454
+ brightnessScale?: TileflowThemeNumberValue;
455
+ color?: TileflowThemeColorValue;
456
+ /** Stable per-building ground radius range in metres; defaults to [30, 100]. */
457
+ groundRadius?: readonly [number, number];
458
+ /** Ground light starts at this height in metres; defaults to 30. */
459
+ minGroundHeight?: number;
460
+ /** Wall light starts above this height in metres; defaults to 200. */
461
+ minWallHeight?: number;
462
+ /** Wall radius as a fraction of building height; defaults to 1/3. */
463
+ wallHeightRatio?: number;
464
+ };
465
+ /** Per-role physical materials and emission, separate from palette slots and occlusion. */
466
+ modelLighting?: Partial<Record<TileflowModelLightingRole, {
467
+ emissiveStrength?: TileflowThemeNumberValue;
468
+ /** Stable per-model addition to emission, from zero to this amount. */
469
+ emissiveVariation?: TileflowThemeNumberValue;
470
+ emissiveColor?: TileflowThemeColorValue;
471
+ /** Height fractions, multipliers and curve exponent; defaults to a constant multiplier of one. */
472
+ emissiveHeight?: readonly [
473
+ TileflowThemeNumberValue,
474
+ TileflowThemeNumberValue,
475
+ TileflowThemeNumberValue,
476
+ TileflowThemeNumberValue,
477
+ TileflowThemeNumberValue
478
+ ];
479
+ /** Physical-material tint. Explicit modelColors take precedence. */
480
+ color?: TileflowThemeColorValue;
481
+ colorMix?: TileflowThemeNumberValue;
482
+ metallic?: TileflowThemeNumberValue;
483
+ roughness?: TileflowThemeNumberValue;
484
+ /** Independent HSL ranges, seeded by model identity; no window geometry is invented. */
485
+ colorVariation?: {
486
+ hue: readonly [TileflowThemeNumberValue, TileflowThemeNumberValue];
487
+ saturation: readonly [TileflowThemeNumberValue, TileflowThemeNumberValue];
488
+ lightness: readonly [TileflowThemeNumberValue, TileflowThemeNumberValue];
489
+ space?: 'srgb' | 'linear';
490
+ };
491
+ }>>;
492
+ /** Contact shadow at the foot of the walls and in tight corners; defaults to true. */
808
493
  occlusion?: boolean;
809
- /** Shadows from the sun, on the buildings and the flat map; defaults to false. */
494
+ /** Prepared model ambient occlusion strength, from 0 to 1; defaults to 0.75. */
495
+ modelOcclusion?: TileflowThemeNumberValue;
496
+ /** Shadows from the sun, on the buildings and the flat map; defaults to true. */
810
497
  shadows?: boolean;
811
498
  /**
812
499
  * Invented night windows, lit by rooms: decoration, not data. With World's `class`, none on sheds,
@@ -859,8 +546,24 @@ type TileflowBuildingsModuleConfig = TileflowBuildingsModuleOptions & {
859
546
 
860
547
  type TileflowLanduseClass = 'cemetery' | 'civic' | 'commercial' | 'education' | 'government' | 'industrial' | 'medical' | 'military' | 'parking' | 'railway' | 'recreation' | 'residential';
861
548
  type TileflowLandcoverClass = 'farmland' | 'flowerbed' | 'grass' | 'ice' | 'meadow' | 'protected' | 'recreationGround' | 'rock' | 'sand' | 'scrub' | 'urbanPark' | 'villageGreen' | 'wetland' | 'wood';
549
+ /** The barriers of the data's barrier layer (World's `traffic_control`) the land module draws. */
550
+ type TileflowBarrierClass = 'fence' | 'hedge' | 'wall';
551
+ /**
552
+ * A barrier's line, a shadow line drawn under it (usually offset with `translate`), and the fill of
553
+ * those mapped as areas, such as broad hedges.
554
+ */
555
+ type TileflowBarrierStyle = {
556
+ area?: TileflowFillStyle;
557
+ shadow?: TileflowLineStyle;
558
+ line?: TileflowLineStyle;
559
+ };
862
560
  type TileflowLandModuleOptions = {
863
561
  background?: TileflowBackgroundStyle;
562
+ /**
563
+ * Hedges, fences and walls, drawn at the top of the land band with hedges uppermost. A barrier
564
+ * without a style is not drawn, and neither is any when the data has no barrier layer.
565
+ */
566
+ barriers?: Partial<Record<TileflowBarrierClass, TileflowBarrierStyle>>;
864
567
  globalLandcover?: TileflowFillStyle;
865
568
  landcover?: Partial<Record<TileflowLandcoverClass, TileflowAreaStyle>>;
866
569
  landuse?: Partial<Record<TileflowLanduseClass, TileflowAreaStyle>>;
@@ -882,22 +585,47 @@ type TileflowLandformsModuleConfig = TileflowLandformsModuleOptions & {
882
585
 
883
586
  /** Labels anchored inside polygon features; point-feature labels remain on their feature style. */
884
587
  type TileflowNauticalAreaLabelStyles = {
588
+ /** Provider coverage cells; hidden unless a map makes this style visible. */
885
589
  coverage?: TileflowSymbolStyle;
886
590
  hazards?: TileflowSymbolStyle;
887
591
  navigationAreas?: TileflowSymbolStyle;
888
592
  reefs?: TileflowSymbolStyle;
889
593
  wrecks?: TileflowSymbolStyle;
890
594
  };
595
+ /**
596
+ * One style per semantic group of `nautical-v1` objects. Point groups draw a circle `marker`, an
597
+ * `icon` from the theme's nautical image tokens, and `text`; area groups draw a `fill` and an
598
+ * `outline`; line groups draw one stroke. Every group respects each feature's `min_zoom`, and
599
+ * point groups place more important features (lower `rank`) first.
600
+ */
891
601
  type TileflowNauticalModuleOptions = {
602
+ /** Other aids: moorings, fog signals, racons, radio and signal stations, and virtual aids. */
892
603
  aids?: TileflowMarkerSymbolStyle;
604
+ /** Fixed beacons and daymarks, coloured by their first colour. */
605
+ beacons?: TileflowMarkerSymbolStyle;
606
+ /** Buoys, light floats, and light vessels, coloured by their first colour. */
607
+ buoys?: TileflowMarkerSymbolStyle;
608
+ /** Submarine cable and pipeline lines. */
609
+ cables?: TileflowLineStyle;
610
+ /** Restrained indication of where a provider publishes marks. */
893
611
  coverage?: TileflowAreaStyle;
612
+ /** Harbour and marina points. */
613
+ harbours?: TileflowMarkerSymbolStyle;
614
+ /** Hazard areas; the outline also strokes linear hazards such as booms. */
894
615
  hazardAreas?: TileflowAreaStyle;
616
+ /** Rocks by water level, obstructions, and offshore platforms. */
895
617
  hazards?: TileflowMarkerSymbolStyle;
896
618
  labels?: TileflowNauticalAreaLabelStyles;
897
619
  lighthouses?: TileflowMarkerSymbolStyle;
620
+ /** Light flares coloured by the light's first colour, with the chart light label. */
898
621
  lights?: TileflowMarkerSymbolStyle;
622
+ /** Restricted, military, anchorage, traffic-separation, and other navigation areas. */
899
623
  navigationAreas?: TileflowAreaStyle;
624
+ /** Ports, sized by `size` and placed by `rank` from low zooms. */
625
+ ports?: TileflowMarkerSymbolStyle;
900
626
  reefs?: TileflowAreaStyle;
627
+ /** Traffic-separation lines and recommended routes, tracks, and ferry routes. */
628
+ routes?: TileflowLineStyle;
901
629
  soundings?: TileflowMarkerSymbolStyle;
902
630
  wreckAreas?: TileflowAreaStyle;
903
631
  wrecks?: TileflowMarkerSymbolStyle;
@@ -989,6 +717,10 @@ type TileflowTreeFields = Readonly<{
989
717
  canopyCover: string;
990
718
  /** A canopy point's measured canopy height, in metres. */
991
719
  canopyHeight: string;
720
+ /** The kind of barrier in the hedge layer: hedges are `hedge`. */
721
+ subclass: string;
722
+ /** A hedge's kind: `hedge_bank` when it stands on an earth bank. */
723
+ hedge: string;
992
724
  }>;
993
725
  type TileflowTreePlacementOptions = Readonly<{
994
726
  /** The tile's address, for regions and for a stable look per tree. */
@@ -1016,6 +748,11 @@ type TileflowTreeLayers = Readonly<{
1016
748
  trees?: TileflowTileLayer;
1017
749
  /** Decorative canopy points in parks and gardens (World's `canopy`). */
1018
750
  canopy?: TileflowTileLayer;
751
+ /**
752
+ * World's `traffic_control`: its hedges, lines and areas of `subclass=hedge`, stand as clipped
753
+ * pieces along each line and round each area. Other barriers are left out.
754
+ */
755
+ hedges?: TileflowTileLayer;
1019
756
  }>;
1020
757
  /** Where some trees are in a placement, and how many of them have each rank or a lower one. */
1021
758
  type TileflowTreeRange = Readonly<{
@@ -1034,7 +771,12 @@ type TileflowTreePlacement = Readonly<{
1034
771
  /** `tileflowTreeBytes` bytes per tree, ordered by form, model, then rank; see the layout below. */
1035
772
  trees: Uint8Array;
1036
773
  forms: Readonly<Record<TileflowTreeForm, TileflowTreeFormRange>>;
1037
- /** The tallest tree, in metres. */
774
+ /**
775
+ * `tileflowTreeBytes` bytes per piece of hedge, as a tree's: its middle, its height, its length
776
+ * as the crown, and its turn along the hedge.
777
+ */
778
+ hedges: Uint8Array;
779
+ /** The tallest tree or hedge, in metres. */
1038
780
  tallest: number;
1039
781
  /** Trees from the data's trees and rows, and trees from canopy points. */
1040
782
  mapped: number;
@@ -1059,19 +801,24 @@ declare function placeTileflowTrees(layers: TileflowTreeLayers, options: Tileflo
1059
801
  declare const tileflowVegetationMetadataKey = "tileflow:vegetation";
1060
802
  /** How a compiled map's 3D trees look and where their data is, resolved for one theme. */
1061
803
  type TileflowVegetation3D = Readonly<{
1062
- /** The vector source and its layers with the trees and the canopy points. */
804
+ /** The vector source and its layers with the trees, the canopy points and the hedges. */
1063
805
  source: string;
1064
806
  layers: Readonly<{
1065
807
  tree: string;
1066
808
  canopy?: string;
809
+ hedge?: string;
1067
810
  }>;
1068
811
  fields: TileflowTreeFields;
1069
- /** Sunlit colours: bark, and the leaves of each kind of tree from darkest to lightest. */
812
+ /**
813
+ * Sunlit colours: bark, the leaves of each kind of tree from darkest to lightest, and those of
814
+ * hedges.
815
+ */
1070
816
  colors: Readonly<{
1071
817
  bark: string;
1072
818
  broadleaf: readonly string[];
1073
819
  conifer: readonly string[];
1074
820
  palm: readonly string[];
821
+ hedge: readonly string[];
1075
822
  }>;
1076
823
  heightScale: number;
1077
824
  crownScale: number;
@@ -1103,6 +850,13 @@ type TileflowVegetationThreeDimensionalStyle = {
1103
850
  coniferColors?: readonly TileflowThemeColorValue[];
1104
851
  /** Sunlit frond colours of palms, from darkest to lightest; the broadleaf colours by default. */
1105
852
  palmColors?: readonly TileflowThemeColorValue[];
853
+ /**
854
+ * Whether the data's hedges stand as clipped green walls beside the trees, at their height or
855
+ * 1.3 m, a metre higher on an earth bank. Defaults to true where the data has hedges.
856
+ */
857
+ hedges?: boolean;
858
+ /** Sunlit colours of hedges, from darkest to lightest; the two darkest broadleaf colours by default. */
859
+ hedgeColors?: readonly TileflowThemeColorValue[];
1106
860
  crownScale?: TileflowThemeNumberValue;
1107
861
  heightScale?: TileflowThemeNumberValue;
1108
862
  /**
@@ -1155,6 +909,16 @@ type TileflowVegetationModuleConfig = TileflowVegetationModuleOptions & {
1155
909
  };
1156
910
 
1157
911
  type TileflowWaterwayClass = 'canal' | 'other' | 'river' | 'stream';
912
+ /** Explicit placement for every geometry family in a declared Bathymetry name layer. */
913
+ type TileflowBathymetryNamePlacement = {
914
+ point: 'point';
915
+ line: TileflowSymbolPlacement;
916
+ polygon: TileflowSymbolPlacement;
917
+ };
918
+ type TileflowBathymetryNameStyle = TileflowSymbolStyle & {
919
+ /** Overrides scalar placement for these names; omission preserves scalar placement. */
920
+ placementByGeometry?: TileflowBathymetryNamePlacement;
921
+ };
1158
922
  type TileflowWaterModuleOptions = {
1159
923
  bathymetry?: TileflowFillStyle;
1160
924
  /** Contour lines when declared by Bathymetry; otherwise approximate polygon band edges. */
@@ -1162,20 +926,247 @@ type TileflowWaterModuleOptions = {
1162
926
  /** Contour-depth or legacy band-floor labels, not measured survey soundings. */
1163
927
  bathymetryLabels?: TileflowSymbolStyle;
1164
928
  /** Names from an explicitly declared seafloor_landform layer. */
1165
- bathymetryLandforms?: TileflowSymbolStyle;
929
+ bathymetryLandforms?: TileflowBathymetryNameStyle;
1166
930
  /** Names from an explicitly declared water_name layer. */
1167
- bathymetryWaterNames?: TileflowSymbolStyle;
931
+ bathymetryWaterNames?: TileflowBathymetryNameStyle;
1168
932
  bodies?: TileflowAreaStyle;
1169
933
  intermittent?: {
1170
934
  bodies?: TileflowAreaStyle;
1171
935
  waterways?: TileflowLineStyle;
1172
936
  };
1173
- waterways?: Partial<Record<TileflowWaterwayClass, TileflowLineStyle>>;
1174
- };
1175
- type TileflowWaterModuleConfig = TileflowWaterModuleOptions & {
1176
- type: 'water';
937
+ waterways?: Partial<Record<TileflowWaterwayClass, TileflowLineStyle>>;
938
+ };
939
+ type TileflowWaterModuleConfig = TileflowWaterModuleOptions & {
940
+ type: 'water';
941
+ };
942
+
943
+ type TileflowColor = `#${string}`;
944
+ type TileflowRoadDetail = 'none' | 'highways' | 'major' | 'streets' | 'all';
945
+ type TileflowRoadClass = 'motorway' | 'trunk' | 'primary' | 'secondary' | 'tertiary' | 'minor' | 'service' | 'track' | 'pathway' | 'footway' | 'cycleway' | 'steps' | 'pedestrian';
946
+ type TileflowRoadHierarchy = 'subtle' | 'clear' | 'strong';
947
+ type TileflowRoadWeight = 'thin' | 'regular' | 'bold';
948
+ type TileflowRoadOutline = 'none' | 'subtle' | 'strong';
949
+ type TileflowRoadStructure = 'bridge' | 'surface' | 'tunnel';
950
+ type TileflowRoadExtras = {
951
+ paths?: boolean;
952
+ };
953
+ type TileflowRoadLayerStyle = TileflowLineStackStyle & {
954
+ hatch?: TileflowLineHatchStyle;
955
+ };
956
+ type TileflowRoadTreatmentLineStyle = Pick<TileflowLinePaint, 'blur' | 'color' | 'dash' | 'gapWidth' | 'offset' | 'opacity' | 'width'>;
957
+ type TileflowRoadTreatmentLayerStyle = {
958
+ casing?: TileflowRoadTreatmentLineStyle;
959
+ fill?: TileflowRoadTreatmentLineStyle;
960
+ shadow?: TileflowRoadTreatmentLineStyle;
961
+ };
962
+ type TileflowRoadTreatmentStyle = Partial<Record<TileflowRoadStructure, TileflowRoadTreatmentLayerStyle>> & {
963
+ enabled?: boolean;
964
+ widthScale?: TileflowThemeNumberValue;
965
+ };
966
+ type TileflowRoadModifier = 'construction' | 'expressway' | 'indoor' | 'official' | 'ramp' | 'unpaved';
967
+ type TileflowRoadRestriction = 'access' | 'bicycle' | 'foot' | 'horse' | 'toll';
968
+ type TileflowMountainBikeScale = '0' | '0+' | '1' | '1+' | '2' | '2+' | '3' | '3+' | '4' | '5' | '6';
969
+ type TileflowRoadServiceType = 'alley' | 'crossover' | 'driveway' | 'parkingAisle' | 'yard';
970
+ type TileflowRoadClassStyle = Partial<Record<TileflowRoadStructure, TileflowRoadLayerStyle>> & {
971
+ enabled?: boolean;
972
+ };
973
+ type TileflowRoadAreaStyle = {
974
+ pedestrian?: TileflowAreaStyle;
975
+ pier?: TileflowAreaStyle;
976
+ road?: TileflowAreaStyle;
977
+ };
978
+ type TileflowRoadCrossingStyle = Omit<TileflowIconStyle, 'image'> & Required<Pick<TileflowIconStyle, 'image'>>;
979
+ type TileflowRoadRoundaboutStyle = {
980
+ /** Extra casing width in pixels, split equally across both edges; defaults to the road border. */
981
+ borderWidth?: TileflowNumberStyleValue;
982
+ casing?: TileflowCircleStyle;
983
+ /** Road width in pixels when metric radii are absent; defaults to the effective surface fill width. */
984
+ fallbackWidth?: TileflowNumberStyleValue;
985
+ fill?: TileflowCircleStyle;
986
+ };
987
+ /**
988
+ * How Core's street lights renderer lights the map's streets at night, from the lamps and lit
989
+ * streets its data holds.
990
+ */
991
+ type TileflowRoadStreetLightStyle = {
992
+ /** The light of lamps whose data gives no colour; a warm white by default. */
993
+ color?: TileflowThemeColorValue;
994
+ /** Whether the map has street lights; defaults to false. Set true to opt in. */
995
+ enabled?: boolean;
996
+ /**
997
+ * Where light is estimated where the data maps no lamps: `lit` (the default) along streets and
998
+ * pavements mapped as lit; `streets` also along streets the data says nothing about, in tiles
999
+ * that map few lamps, which invents light; `none` nowhere.
1000
+ */
1001
+ estimate?: 'lit' | 'streets' | 'none';
1002
+ /** How bright the lights shine, from 0 to 2; defaults to 1. */
1003
+ intensity?: TileflowThemeNumberValue;
1004
+ };
1005
+ type TileflowRoadSidewalkStyle = {
1006
+ outline?: TileflowLineStyle;
1007
+ pattern?: TileflowFillStyle;
1008
+ surface?: TileflowFillStyle;
1009
+ };
1010
+ type TileflowRoadsModuleConfig = {
1011
+ type: 'roads';
1012
+ areas?: TileflowRoadAreaStyle;
1013
+ classes?: Partial<Record<TileflowRoadClass, TileflowRoadClassStyle>>;
1014
+ crossings?: TileflowRoadCrossingStyle;
1015
+ detail?: TileflowRoadDetail;
1016
+ extras?: TileflowRoadExtras;
1017
+ hierarchy?: TileflowRoadHierarchy;
1018
+ modifiers?: Partial<Record<TileflowRoadModifier, TileflowRoadTreatmentStyle>>;
1019
+ mountainBike?: Partial<Record<TileflowMountainBikeScale, TileflowRoadTreatmentStyle>>;
1020
+ oneWayMarkers?: boolean;
1021
+ outline?: TileflowRoadOutline;
1022
+ /** Draw ramp fills below receiving roads by default; `by-class` keeps their class's order. */
1023
+ rampOrder?: 'below-roads' | 'by-class';
1024
+ restrictions?: Partial<Record<TileflowRoadRestriction, TileflowRoadTreatmentStyle>>;
1025
+ roundabouts?: TileflowRoadRoundaboutStyle;
1026
+ serviceTypes?: Partial<Record<TileflowRoadServiceType, TileflowRoadTreatmentStyle>>;
1027
+ sidewalks?: TileflowRoadSidewalkStyle;
1028
+ streetLights?: TileflowRoadStreetLightStyle;
1029
+ structures?: Partial<Record<TileflowRoadStructure, TileflowRoadLayerStyle>>;
1030
+ weight?: TileflowRoadWeight;
1031
+ widthScale?: Partial<Record<TileflowRoadClass, TileflowThemeNumberValue>>;
1032
+ };
1033
+ type TileflowLabelDetail = 'none' | 'major' | 'all';
1034
+ type TileflowAerodromeCodeDetail = 'none' | 'iata' | 'all';
1035
+ type TileflowRoadLabelDetail = TileflowRoadDetail;
1036
+ type TileflowLabelLanguage = 'auto' | 'local' | 'en' | (string & {});
1037
+ type TileflowPlaceLabelClass = 'city' | 'continent' | 'country' | 'neighborhood' | 'other' | 'state' | 'town' | 'village';
1038
+ type TileflowWaterLabelClass = 'line' | 'ocean' | 'other' | 'waterway';
1039
+ type TileflowRoadShieldDetail = 'none' | 'major' | 'all';
1040
+ type TileflowLabelCollisionPriority = 'balanced' | 'navigation';
1041
+ type TileflowRoadShieldStyles = {
1042
+ default?: TileflowSymbolStyle;
1043
+ detail?: TileflowSymbolStyle;
1044
+ kinds?: Record<string, {
1045
+ image: TileflowThemeImageValue;
1046
+ }>;
1047
+ overview?: TileflowSymbolStyle;
1048
+ textColors?: Record<string, {
1049
+ color: TileflowThemeColorValue;
1050
+ }>;
1051
+ };
1052
+ type TileflowLabelStyles = {
1053
+ aerodrome?: TileflowSymbolStyle;
1054
+ junctions?: TileflowSymbolStyle;
1055
+ places?: Partial<Record<TileflowPlaceLabelClass, TileflowSymbolStyle>>;
1056
+ roads?: Partial<Record<TileflowRoadClass, TileflowSymbolStyle>>;
1057
+ shields?: TileflowRoadShieldStyles;
1058
+ water?: Partial<Record<TileflowWaterLabelClass, TileflowSymbolStyle>>;
1059
+ };
1060
+ type TileflowLabelsModuleConfig = {
1061
+ type: 'labels';
1062
+ aerodromeCodes?: TileflowAerodromeCodeDetail;
1063
+ collisionPriority?: TileflowLabelCollisionPriority;
1064
+ junctions?: boolean;
1065
+ language?: TileflowLabelLanguage;
1066
+ places?: TileflowLabelDetail;
1067
+ roadClasses?: readonly TileflowRoadClass[];
1068
+ /**
1069
+ * Where street names draw. `foreground` (the default) keeps them above buildings and
1070
+ * vegetation. `ground` places them below buildings, with map-aligned text by default.
1071
+ * Ground names retain their road-class collision order, but foreground symbols are offered
1072
+ * first by the renderer; `collisionPriority` cannot make ground names outrank those symbols.
1073
+ * Shields and junction numbers keep their foreground placement.
1074
+ */
1075
+ roadPlacement?: 'ground' | 'foreground';
1076
+ roads?: TileflowRoadLabelDetail;
1077
+ shields?: TileflowRoadShieldDetail;
1078
+ styles?: TileflowLabelStyles;
1079
+ water?: TileflowLabelDetail;
1080
+ };
1081
+ /** Closed editorial vocabulary emitted by Tileflow World's canonical POI projection. */
1082
+ declare const tileflowPoiCategories: readonly ["arts-entertainment", "education", "food-drink", "landmark", "lodging", "medical", "park-nature", "public-services", "religion", "retail", "sport-leisure", "transport", "visitor-amenity"];
1083
+ type TileflowPoiCategory = (typeof tileflowPoiCategories)[number];
1084
+ type TileflowPoiDensity = 1 | 2 | 3 | 4 | 5;
1085
+ type TileflowPoiColorMode = 'uniform' | 'category';
1086
+ /**
1087
+ * How POI categories are placed against each other. `importance` places every category in one
1088
+ * order, by World's ranks. `categories` gives each category its own layer and places the
1089
+ * categories in the order they are listed, the first on top; ranks order each category only.
1090
+ */
1091
+ type TileflowPoiPlacementOrder = 'categories' | 'importance';
1092
+ /**
1093
+ * The appearance of one POI category. With the default `importance` order every category shares
1094
+ * one placement layer, so categories may differ only in properties MapLibre evaluates per feature
1095
+ * (image, size, colors, font, offsets); layer-wide properties such as zoom ranges, padding,
1096
+ * overlap or `optional` must match, or the module uses `placement.order: 'categories'`.
1097
+ */
1098
+ type TileflowPoiCategoryStyle = Omit<TileflowMarkerSymbolStyle, 'priority'>;
1099
+ type TileflowPoiModuleConfig = {
1100
+ type: 'poi';
1101
+ categories?: readonly TileflowPoiCategory[];
1102
+ color?: TileflowPoiColorMode;
1103
+ /** One density for the whole module: World's ranks decide what each category shows. */
1104
+ density?: TileflowPoiDensity;
1105
+ icons?: boolean;
1106
+ labels?: boolean;
1107
+ minZoom?: number;
1108
+ placement?: {
1109
+ /**
1110
+ * Places each pictogram with its name as one unit that needs room for both. Defaults to
1111
+ * `false`.
1112
+ */
1113
+ coupleIconAndLabel?: boolean;
1114
+ iconPadding?: number;
1115
+ /**
1116
+ * World POI `type` values whose pictogram explains them. When pictograms and names are both
1117
+ * drawn, every other POI needs a name, and these types are drawn as a pictogram alone.
1118
+ * Defaults to parking and public toilets.
1119
+ */
1120
+ iconOnlyTypes?: readonly string[];
1121
+ /** Defaults to `importance`. */
1122
+ order?: TileflowPoiPlacementOrder;
1123
+ /**
1124
+ * With the `importance` order, POIs whose World `filter_rank` is at most this value are placed
1125
+ * before the map's road and place labels, and the others after them. A map that gives street
1126
+ * names priority over POIs (labels `collisionPriority: 'navigation'`) keeps its landmarks this
1127
+ * way. Unset, every POI is placed at the module's own position.
1128
+ */
1129
+ prominentRank?: 0 | 1 | 2 | 3 | 4 | 5;
1130
+ textPadding?: number;
1131
+ };
1132
+ styles?: Partial<Record<TileflowPoiCategory, TileflowPoiCategoryStyle>>;
1133
+ };
1134
+ type MapLibreSprite = string | Array<{
1135
+ id: string;
1136
+ url: string;
1137
+ }>;
1138
+ type TileflowProjection = 'globe' | 'mercator';
1139
+ type TileflowLight = {
1140
+ anchor?: 'map' | 'viewport';
1141
+ color?: TileflowColor;
1142
+ intensity?: number;
1143
+ position?: readonly [number, number, number];
1144
+ };
1145
+ type MapLibreStyle = {
1146
+ sky?: Record<string, unknown>;
1147
+ version: 8;
1148
+ name: string;
1149
+ glyphs?: string;
1150
+ light?: TileflowLight;
1151
+ projection?: {
1152
+ type: TileflowProjection;
1153
+ };
1154
+ sprite?: MapLibreSprite;
1155
+ sources: Record<string, Record<string, unknown>>;
1156
+ layers: Array<Record<string, unknown>>;
1157
+ terrain?: Record<string, unknown>;
1158
+ metadata?: Record<string, unknown>;
1177
1159
  };
1178
1160
 
1161
+ /**
1162
+ * Layer metadata naming the semantic module that owns a compiled layer, such as `roads` or `water`.
1163
+ * Runtime features that address a module, such as map emphasis, read it instead of physical layer
1164
+ * IDs. Layers that a theme blend splits or copies keep it.
1165
+ */
1166
+ declare const tileflowLayerDomainMetadataKey: "tileflow:domain";
1167
+
1168
+ type TileflowLayerDomain = TileflowSemanticModuleName | 'terrain';
1169
+
1179
1170
  type TileflowSemanticModules = {
1180
1171
  addresses?: TileflowAddressesModuleConfig;
1181
1172
  aeroways?: TileflowAerowaysModuleConfig;
@@ -1193,14 +1184,181 @@ type TileflowSemanticModules = {
1193
1184
  };
1194
1185
  type TileflowSemanticModuleName = keyof TileflowSemanticModules;
1195
1186
 
1187
+ declare const tileflowSunMetadataKey = "tileflow:sun";
1188
+ /** A theme's sun and sky light with every value resolved; see `TileflowThemeSun`. */
1189
+ type TileflowSunPreset = Readonly<{
1190
+ /** Degrees clockwise from north, from 0 to 360. */
1191
+ azimuth: number;
1192
+ /** Degrees above the horizon, from -90 to 90. */
1193
+ altitude: number;
1194
+ /** The direct light's colour. */
1195
+ color: string;
1196
+ /** The direct light's strength, from 0 to 1. */
1197
+ intensity: number;
1198
+ /** How dark the shadows the sun casts fall, from 0 (none) to 1. */
1199
+ shadowIntensity: number;
1200
+ /** The light from the sky, which reaches every surface and fills the shadows. */
1201
+ ambient: Readonly<{
1202
+ color: string;
1203
+ intensity: number;
1204
+ }>;
1205
+ }>;
1206
+ /** The sun as the map shows it, ready for an application's own layers. */
1207
+ type TileflowSun = Readonly<{
1208
+ /** Degrees clockwise from north, from 0 to 360. */
1209
+ azimuth: number;
1210
+ /** Degrees above the horizon, from -90 to 90. */
1211
+ altitude: number;
1212
+ /** A unit vector towards the sun: x east, y north, z up. */
1213
+ direction: readonly [number, number, number];
1214
+ /** The direct light's colour, as a CSS colour. */
1215
+ color: string;
1216
+ /** The direct light's colour as sRGB channels from 0 to 1. */
1217
+ rgb: readonly [number, number, number];
1218
+ /**
1219
+ * The direct light's strength, from 0 to 1. It fades to 0 as the sun sets: a sun below the
1220
+ * horizon lights nothing and casts no shadow.
1221
+ */
1222
+ intensity: number;
1223
+ /** How dark the shadows the sun casts fall, from 0 (none) to 1. */
1224
+ shadowIntensity: number;
1225
+ /** The light from the sky, which reaches every surface and fills the shadows. */
1226
+ ambient: Readonly<{
1227
+ color: string;
1228
+ rgb: readonly [number, number, number];
1229
+ intensity: number;
1230
+ }>;
1231
+ /**
1232
+ * How bright flat, open ground is under this light, from 0 (dark) to 1: the sky's light plus the
1233
+ * sun's at its height, each weighted by its colour's luminance. Use it to switch lamps or windows
1234
+ * on as a scene darkens, whatever theme or sun lights it.
1235
+ */
1236
+ brightness: number;
1237
+ /** Where the direction comes from: the themes, angles, or a date and place. */
1238
+ source: 'theme' | 'direction' | 'date';
1239
+ }>;
1240
+ /** Unset sun values: high in the south-south-west, with soft white daylight and ambient fill. */
1241
+ declare const tileflowDefaultSunPreset: TileflowSunPreset;
1196
1242
  /**
1197
- * Layer metadata naming the semantic module that owns a compiled layer, such as `roads` or `water`.
1198
- * Runtime features that address a module, such as map emphasis, read it instead of physical layer
1199
- * IDs. Layers that a theme blend splits or copies keep it.
1243
+ * Where the sun stands for an instant and a place ([longitude, latitude] in degrees): its azimuth
1244
+ * in degrees clockwise from north and its apparent altitude above the horizon, with atmospheric
1245
+ * refraction. It follows NOAA's solar equations, accurate to about a hundredth of a degree for
1246
+ * years 1800 to 2200.
1200
1247
  */
1201
- declare const tileflowLayerDomainMetadataKey: "tileflow:domain";
1248
+ declare function tileflowSunPosition(date: Date | number, location: readonly [number, number]): Readonly<{
1249
+ azimuth: number;
1250
+ altitude: number;
1251
+ }>;
1252
+ /** A unit vector towards a direction in the sky: x east, y north, z up. */
1253
+ declare function tileflowSunDirection(azimuth: number, altitude: number): readonly [number, number, number];
1254
+ /**
1255
+ * The sun as the map shows it: a preset's light from a direction. Direct light fades out over the
1256
+ * sun's last degrees above the horizon and is gone below it.
1257
+ */
1258
+ declare function resolveTileflowSun(preset: TileflowSunPreset, direction?: Readonly<{
1259
+ azimuth: number;
1260
+ altitude: number;
1261
+ }>, source?: TileflowSun['source']): TileflowSun;
1262
+ /**
1263
+ * A preset `t` of the way from `from` to `to`: the azimuth turns the short way round, colours mix
1264
+ * in OKLab, as theme blends mix paint colours, and numbers linearly.
1265
+ */
1266
+ declare function mixTileflowSunPresets(from: TileflowSunPreset, to: TileflowSunPreset, t: number): TileflowSunPreset;
1267
+ /** Reads the sun a compiled style publishes, or undefined when its metadata has none. */
1268
+ declare function readTileflowSunPreset(metadata: unknown): TileflowSunPreset | undefined;
1269
+ /**
1270
+ * The sun of a compiled style: the one it publishes, else one read from its light (a style whose
1271
+ * theme describes no sun lights its extrusions from `light.position`), else the default.
1272
+ */
1273
+ declare function tileflowStyleSunPreset(style: {
1274
+ light?: unknown;
1275
+ metadata?: unknown;
1276
+ } | undefined): TileflowSunPreset;
1202
1277
 
1203
- type TileflowLayerDomain = TileflowSemanticModuleName | 'terrain';
1278
+ type TileflowThemeColorScheme = 'dark' | 'light';
1279
+
1280
+ declare const tileflowRouteMetadataKey = "tileflow:route";
1281
+ /** The resolved inks of a route, from its outer glow to its bright core. */
1282
+ type TileflowRouteInks = Readonly<{
1283
+ /** The chosen route's line. */
1284
+ line: string;
1285
+ /** The edge on each side of the line, which sets it apart from the roads under it. */
1286
+ casing: string;
1287
+ /** A thin line along the middle of the route. */
1288
+ core: string;
1289
+ /** A soft halo around the route. */
1290
+ glow: string;
1291
+ /** Other routes offered beside the chosen one. */
1292
+ alternative: string;
1293
+ /** Opacity of the glow, from 0 (no glow) to 1. */
1294
+ glowOpacity: number;
1295
+ /** Opacity of the core, from 0 (no core) to 1. */
1296
+ coreOpacity: number;
1297
+ }>;
1298
+ /** The inks of a theme that sets no route tokens: a blue that reads on either kind of map. */
1299
+ declare const tileflowDefaultRouteInks: Readonly<Record<TileflowThemeColorScheme, TileflowRouteInks>>;
1300
+ /**
1301
+ * Reads the route inks a compiled style publishes, or undefined when its metadata has none (a
1302
+ * style compiled before route inks, or not by Tileflow).
1303
+ */
1304
+ declare function readTileflowRouteInks(metadata: unknown): TileflowRouteInks | undefined;
1305
+ /**
1306
+ * The route inks of a compiled style: those it publishes, or the defaults of its colour scheme
1307
+ * (from its `tileflow:colorScheme` metadata, else `fallbackScheme`).
1308
+ */
1309
+ declare function tileflowStyleRouteInks(style: {
1310
+ metadata?: unknown;
1311
+ } | undefined, fallbackScheme?: TileflowThemeColorScheme): TileflowRouteInks;
1312
+ /**
1313
+ * Inks between two themes' inks, `t` of the way from `from` to `to`: colours mix in OKLab, as theme
1314
+ * blends mix paint colours, and opacities linearly.
1315
+ */
1316
+ declare function mixTileflowRouteInks(from: TileflowRouteInks, to: TileflowRouteInks, t: number): TileflowRouteInks;
1317
+
1318
+ type TileflowRuntimeColorScheme = 'dark' | 'light';
1319
+
1320
+ type TileflowAnalytics = {
1321
+ apiUrl?: string;
1322
+ endpoint?: string;
1323
+ enabled?: boolean;
1324
+ mapId?: string;
1325
+ metadata?: Record<string, unknown>;
1326
+ projectId?: string;
1327
+ sdkVersion?: string;
1328
+ source?: string;
1329
+ styleId?: string;
1330
+ surfaceId?: string;
1331
+ };
1332
+ type TileflowSessionController = {
1333
+ readonly sessionId: string;
1334
+ resolveRequestUrl(url: string, analytics: TileflowAnalytics | undefined): Promise<string | undefined>;
1335
+ };
1336
+ type TileflowRuntimeStyle = {
1337
+ analytics?: TileflowAnalytics;
1338
+ colorScheme?: TileflowRuntimeColorScheme;
1339
+ /** An explicit empty array means the manifest declares that no web fonts are required. */
1340
+ fontFaces?: TileflowStyleFontFace[];
1341
+ revision?: string;
1342
+ style: MapLibreStyle | string;
1343
+ theme?: string;
1344
+ };
1345
+ type TileflowStyleFontFace = {
1346
+ family: string;
1347
+ source: string;
1348
+ style?: 'italic' | 'normal' | 'oblique';
1349
+ weight?: '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900';
1350
+ };
1351
+ /**
1352
+ * A continuous blend of named themes of one Tileflow map. `position` places the map between
1353
+ * neighbouring themes: 0 is the first, 1 the second, and 1.25 a quarter of the way from the second
1354
+ * to the third.
1355
+ */
1356
+ type TileflowThemeBlendSelection = Readonly<{
1357
+ /** From 0 to `themes.length - 1`. */
1358
+ position: number;
1359
+ /** Two to eight concrete theme names of the map, in blend order. */
1360
+ themes: readonly string[];
1361
+ }>;
1204
1362
 
1205
1363
  /**
1206
1364
  * Map emphasis lets an application's own content read first: chosen modules of the map recede
@@ -1286,6 +1444,79 @@ type TileflowAtmosphereMap = {
1286
1444
  */
1287
1445
  declare function attachTileflowAtmosphere(map: TileflowAtmosphereMap): () => void;
1288
1446
 
1447
+ /**
1448
+ * Boundaries families. Each one has its own license, attribution, TileJSON path and style source
1449
+ * ID; families are never merged.
1450
+ */
1451
+ declare const tileflowBoundaryFamilies: Readonly<{
1452
+ boundaries: Readonly<{
1453
+ attribution: "© OpenStreetMap contributors";
1454
+ license: "ODbL-1.0";
1455
+ path: "/tiles/boundaries/tiles.json";
1456
+ sourceId: "tileflow-boundaries";
1457
+ }>;
1458
+ }>;
1459
+ type TileflowBoundaryFamily = keyof typeof tileflowBoundaryFamilies;
1460
+
1461
+ /** A value a choropleth can colour: a number for scales, a string for categories. */
1462
+ type TileflowBoundaryValue = number | string;
1463
+ /** One row of an application's data, keyed by a registry ID or an official code. */
1464
+ type TileflowBoundaryRow = Readonly<{
1465
+ key: number | string;
1466
+ /** `null` leaves the area without a value. */
1467
+ value: TileflowBoundaryValue | null;
1468
+ }>;
1469
+ /** Keys present on every `boundary_area` polygon, usable without the lookup table. */
1470
+ type TileflowBoundaryFeatureKey = 'id' | 'iso_3166_1' | 'ref';
1471
+ /** Rows joined to areas by one polygon key. */
1472
+ type TileflowBoundaryValues = Readonly<{
1473
+ joinBy: TileflowBoundaryFeatureKey;
1474
+ rows: readonly TileflowBoundaryRow[];
1475
+ }>;
1476
+
1477
+ type FeatureTarget = {
1478
+ id?: number | string;
1479
+ source: string;
1480
+ sourceLayer?: string;
1481
+ };
1482
+ /** The part of a MapLibre map the controller uses. */
1483
+ type TileflowFeatureStateMap = {
1484
+ getSource(id: string): unknown;
1485
+ getStyle?(): {
1486
+ sources?: Record<string, unknown>;
1487
+ } | undefined;
1488
+ off(type: 'styledata', listener: () => void): unknown;
1489
+ on(type: 'styledata', listener: () => void): unknown;
1490
+ removeFeatureState(target: FeatureTarget, key?: string): void;
1491
+ setFeatureState(target: FeatureTarget & {
1492
+ id: number | string;
1493
+ }, state: Record<string, unknown>): void;
1494
+ };
1495
+ type CreateBoundaryFeatureStateOptions = Readonly<{
1496
+ /** Defaults to `boundaries`. */
1497
+ family?: TileflowBoundaryFamily;
1498
+ /** Also set the values on `boundary_label` points, for labels styled by value. */
1499
+ labels?: boolean;
1500
+ /** Feature-state key; it must match the choropleth's `state`. Defaults to `value`. */
1501
+ state?: string;
1502
+ }>;
1503
+ type TileflowBoundaryFeatureState = Readonly<{
1504
+ /** Remove every value this controller set. */
1505
+ clear: () => void;
1506
+ /** Remove the values and stop following style reloads. */
1507
+ dispose: () => void;
1508
+ /**
1509
+ * Replace the values. Rows must be keyed by the source's feature ID: `id` by default, or `ref`
1510
+ * when the map declares `promoteId: 'ref'`. Rows with a `null` value are removed.
1511
+ */
1512
+ set: (values: TileflowBoundaryValues) => void;
1513
+ }>;
1514
+ /**
1515
+ * Keep Boundaries feature-state in sync with application rows. Values survive a style reload: the
1516
+ * controller sets them again once the source is back.
1517
+ */
1518
+ declare function createBoundaryFeatureState(map: TileflowFeatureStateMap, options?: CreateBoundaryFeatureStateOptions): TileflowBoundaryFeatureState;
1519
+
1289
1520
  /** The drawn stretch of a line and its highlights, as shares of the line's length from its start. */
1290
1521
  type TileflowLineProgressState = Readonly<{
1291
1522
  /** Where the drawn stretch starts, from 0 (the default) to 1. */
@@ -1484,16 +1715,26 @@ declare function readTileflowMapTileSource(map: TileflowTileSourceMap, sourceId:
1484
1715
  maxzoom: number;
1485
1716
  } | undefined;
1486
1717
 
1718
+ type ShadowPoint = readonly number[];
1719
+ type ShadowBox = Readonly<{
1720
+ min: ShadowPoint;
1721
+ max: ShadowPoint;
1722
+ }>;
1723
+ type ShadowView = Readonly<{
1724
+ /** Visible receiver points, in the caster box's metre frame. All casters still draw. */
1725
+ receivers?: readonly ShadowPoint[];
1726
+ /** Snap to world-aligned texels; omit for an unsnapped mathematical projection. */
1727
+ resolution?: number;
1728
+ origin?: ShadowPoint;
1729
+ /** Metres per fixed world unit; keeps texel quantization independent of latitude scale. */
1730
+ gridScale?: number;
1731
+ }>;
1487
1732
  /**
1488
- * The sun's view of a box of buildings: an orthographic projection along `direction` (towards the
1489
- * sun; x east, y north, z up, in metres) as a column-major matrix to clip space, with the metres its
1490
- * depth runs over and the metres its wider side spans. It follows only the sun, never the camera,
1491
- * so shadows hold still while the camera moves.
1733
+ * The sun's orthographic view, in metres, with room for each caster's shadow to reach the ground.
1734
+ * Optional receivers concentrate XY resolution without dropping offscreen casters along a ray;
1735
+ * quantized extents and a world-anchored texel grid keep stationary shadows stable during pans.
1492
1736
  */
1493
- declare function tileflowSunLightMatrix(direction: readonly number[], box: Readonly<{
1494
- min: readonly number[];
1495
- max: readonly number[];
1496
- }>): {
1737
+ declare function tileflowSunLightMatrix(direction: readonly number[], box: ShadowBox, view?: ShadowView): {
1497
1738
  matrix: Float32Array;
1498
1739
  depth: number;
1499
1740
  extent: number;
@@ -1507,6 +1748,10 @@ type TileflowBuildings3DMap = {
1507
1748
  lng: number;
1508
1749
  };
1509
1750
  getBearing(): number;
1751
+ getCanvas?(): {
1752
+ clientHeight: number;
1753
+ };
1754
+ getVerticalFieldOfView?(): number;
1510
1755
  getLight?(): unknown;
1511
1756
  getLayer(id: string): unknown;
1512
1757
  getPaintProperty(layer: string, name: string): unknown;
@@ -1532,7 +1777,7 @@ type TileflowBuildings3DOptions = Readonly<{
1532
1777
  map: TileflowBuildings3DMap;
1533
1778
  /** The theme controller, for the sun and the buildings' design in every theme. */
1534
1779
  controller?: TileflowBuildings3DThemes;
1535
- /** The zoom from which buildings stand; below it they sink into the flat map. Defaults to 14.5. */
1780
+ /** The zoom where buildings start fading in, reaching full opacity 0.25 zoom later. Defaults to 15. */
1536
1781
  minzoom?: number;
1537
1782
  /** The most tiles raised round the camera, from 1 to 64; defaults to 25. */
1538
1783
  maxTiles?: number;
@@ -1575,7 +1820,7 @@ type TileflowBuildings3D = {
1575
1820
  };
1576
1821
  declare const tileflowBuildings3DLayerId = "tileflow-buildings-3d";
1577
1822
  /**
1578
- * Creates the renderer and puts its layer on the map, flat until `show()`. It reads the source's
1823
+ * Creates the renderer, showing buildings automatically above zoom 15 unless hidden. It reads the source's
1579
1824
  * z15 tiles round the camera, the zoom at which World's buildings carry their heights.
1580
1825
  */
1581
1826
  declare function createTileflowBuildings3D(options: TileflowBuildings3DOptions): TileflowBuildings3D;
@@ -1589,6 +1834,10 @@ type TileflowBuildingMeshOptions = Readonly<{
1589
1834
  tileMetres: number;
1590
1835
  /** Height used where a building has none, in metres; defaults to 5, World's own fallback. */
1591
1836
  defaultHeight?: number;
1837
+ /** Exterior corner radius in metres, up to 1; 0 leaves the footprint unchanged. */
1838
+ edgeRadius?: number;
1839
+ /** Maximum turn per rounded segment; defaults to 30 degrees for close views. */
1840
+ cornerAngle?: number;
1592
1841
  /**
1593
1842
  * The tile's places (World's `poi` layer), for the night use of buildings when the tile's
1594
1843
  * buildings do not carry World's `night_use`: a place inside a building, or on its facade, gives
@@ -1602,8 +1851,17 @@ type TileflowBuildingMeshOptions = Readonly<{
1602
1851
  */
1603
1852
  masks?: readonly (readonly number[])[];
1604
1853
  }>;
1854
+ type BuildingMeshGroup = {
1855
+ /** Conservative tile-space x/y bounds and maximum height in metres. */
1856
+ bounds: [number, number, number, number, number];
1857
+ roofsFrom: number;
1858
+ roofsCount: number;
1859
+ wallsFrom: number;
1860
+ wallsCount: number;
1861
+ };
1605
1862
  /** One tile's buildings, ready to upload. */
1606
1863
  type TileflowBuildingMesh = Readonly<{
1864
+ groups?: readonly BuildingMeshGroup[];
1607
1865
  vertices: Uint8Array;
1608
1866
  indices: Uint32Array;
1609
1867
  /** The first wall index: roofs come before it, walls from it. */
@@ -1655,6 +1913,11 @@ type TileflowStreetLightsMap = {
1655
1913
  };
1656
1914
  type TileflowStreetLightsOptions = Readonly<{
1657
1915
  map: TileflowStreetLightsMap;
1916
+ /**
1917
+ * By default, only a map that enables roads.streetLights supplies lights. Set true to opt in
1918
+ * with the fallback design when metadata is absent, or false to keep every theme's lights off.
1919
+ */
1920
+ enabled?: boolean;
1658
1921
  /**
1659
1922
  * The theme controller, whose sun switches the lights on and off and whose themes hold the map's
1660
1923
  * street lights (the roads module's `streetLights`).
@@ -1699,15 +1962,34 @@ declare const tileflowStreetLightsLayerId = "tileflow-street-lights";
1699
1962
  */
1700
1963
  declare function createTileflowStreetLights(options: TileflowStreetLightsOptions): TileflowStreetLights;
1701
1964
 
1702
- /** The parts of a model, each coloured by the theme: the model's materials name them. */
1703
- declare const tileflowModelParts: Readonly<{
1704
- surface: 0;
1705
- secondary: 1;
1706
- glass: 2;
1707
- accent: 3;
1708
- roof: 4;
1965
+ /** Begin/end height fractions, begin/end multipliers and the base-10 curve exponent. */
1966
+ type TileflowModelEmissionGradient = readonly [number, number, number, number, number];
1967
+ type TileflowModelRoleLighting = Readonly<{
1968
+ emissiveStrength: number;
1969
+ emissiveVariation?: number;
1970
+ emissiveColor?: string;
1971
+ emissiveHeight: TileflowModelEmissionGradient;
1972
+ color?: string;
1973
+ colorMix?: number;
1974
+ metallic?: number;
1975
+ roughness?: number;
1976
+ colorVariation?: Readonly<{
1977
+ hue: readonly [number, number];
1978
+ saturation: readonly [number, number];
1979
+ lightness: readonly [number, number];
1980
+ /** Colour factors may be authored in linear light, as in glTF. Defaults to sRGB. */
1981
+ space?: 'srgb' | 'linear';
1982
+ }>;
1983
+ }>;
1984
+ type TileflowBuildingFloodLight = Readonly<{
1985
+ intensity: number;
1986
+ brightnessScale: number;
1987
+ color: string;
1988
+ groundRadius: readonly [number, number];
1989
+ minGroundHeight: number;
1990
+ minWallHeight: number;
1991
+ wallHeightRatio: number;
1709
1992
  }>;
1710
- type TileflowModelPart = keyof typeof tileflowModelParts;
1711
1993
 
1712
1994
  /** The style metadata key under which a compiled map describes its 3D buildings. */
1713
1995
  declare const tileflowBuildingsMetadataKey = "tileflow:buildings";
@@ -1726,7 +2008,9 @@ type TileflowBuildings3DDesign = Readonly<{
1726
2008
  color: string | readonly unknown[];
1727
2009
  /** How strongly roof outlines and outer corners catch the light, from 0 to 1. */
1728
2010
  edges: number;
1729
- /** Style extrusion light by default; scene sun lighting is opt-in. */
2011
+ /** Exterior corner radius and roof lighting transition, in metres; 0 keeps sharp edges. */
2012
+ edgeRadius?: number;
2013
+ /** Scene sun lighting by default; `style` uses the native extrusion light. */
1730
2014
  lighting: 'style' | 'sun';
1731
2015
  /** Per-building brightness variation, from 0 to 1; 0 preserves the authored colour. */
1732
2016
  colorVariation: number;
@@ -1736,11 +2020,17 @@ type TileflowBuildings3DDesign = Readonly<{
1736
2020
  edgeColor?: string;
1737
2021
  /** How bright the buildings light the street at night, from 0 to 2. */
1738
2022
  nightLight: number;
2023
+ /** Height-selected light on ordinary buildings and the ground, independent of shop windows. */
2024
+ floodLight?: TileflowBuildingFloodLight;
2025
+ /** Emission by architectural role, independent of model palette slots. */
2026
+ modelLighting?: Readonly<Partial<Record<TileflowModelLightingRole, TileflowModelRoleLighting>>>;
1739
2027
  /** Invented night windows, lit by rooms: decoration, not data. */
1740
2028
  windows: boolean;
1741
2029
  /** Shadows from the sun, and contact shadow at the foot of the walls. */
1742
2030
  shadows: boolean;
1743
2031
  occlusion: boolean;
2032
+ /** Strength of prepared model ambient visibility; zero leaves the sky contribution unchanged. */
2033
+ modelOcclusion?: number;
1744
2034
  /** Building models the map places in its city, each replacing the buildings under it. */
1745
2035
  models?: readonly TileflowBuildingModelPlacement[];
1746
2036
  /** The colours of the models' parts; a part without one takes it from the building colour. */
@@ -1771,6 +2061,13 @@ type TileflowBuildingModelPlacement = Readonly<{
1771
2061
  declare function readTileflowBuildings3D(metadata: unknown): TileflowBuildings3DDesign | undefined;
1772
2062
  /** The most models one map places. */
1773
2063
  declare const tileflowBuildingModelPlacementLimit = 256;
2064
+ /**
2065
+ * The address a hosted build gives a placement of one of the map's own models: a placeholder that
2066
+ * Tileflow replaces, when the map is deployed, with that model's address in the map's Team.
2067
+ */
2068
+ declare function tileflowTeamModelUrl(model: string): string;
2069
+ /** The Team model a placement's address is the placeholder of, if it is one. */
2070
+ declare function readTileflowTeamModelName(url: string): string | undefined;
1774
2071
 
1775
2072
  /** The MapLibre GL JS map capabilities the trees use. */
1776
2073
  type TileflowTrees3DMap = {
@@ -1807,7 +2104,7 @@ type TileflowTrees3DOptions = Readonly<{
1807
2104
  controller?: TileflowTrees3DThemes;
1808
2105
  /** The vector source with the canopy points, when not the map's World source. */
1809
2106
  canopySource?: string;
1810
- /** The zoom from which trees stand; they fade in over the zoom above it. Defaults to 15. */
2107
+ /** The zoom from which trees stand; they reach full opacity 0.25 zoom later. Defaults to 15. */
1811
2108
  minzoom?: number;
1812
2109
  /** The most tiles of trees round the camera, from 1 to 64; defaults to 25. */
1813
2110
  maxTiles?: number;
@@ -1836,7 +2133,8 @@ type TileflowTrees3D = {
1836
2133
  readonly scale: number;
1837
2134
  /**
1838
2135
  * Whether the map's style describes 3D trees (`vegetation({mode: '3d'})`), tiles of trees,
1839
- * trees placed (mapped and from canopy points) and trees drawn in the last frame.
2136
+ * trees placed (mapped and from canopy points), pieces of hedge placed and trees drawn in the
2137
+ * last frame.
1840
2138
  */
1841
2139
  readonly stats: Readonly<{
1842
2140
  declared: boolean;
@@ -1844,6 +2142,7 @@ type TileflowTrees3D = {
1844
2142
  trees: number;
1845
2143
  mapped: number;
1846
2144
  canopy: number;
2145
+ hedges: number;
1847
2146
  drawn: number;
1848
2147
  }>;
1849
2148
  /** Takes the layer off the map and lets go of its buffers. */
@@ -2156,6 +2455,54 @@ type TileflowShotPlayback = {
2156
2455
  */
2157
2456
  declare function playTileflowShot(map: TileflowShotPlayerMap, shot: TileflowShotMotion, options?: TileflowShotPlaybackOptions): TileflowShotPlayback;
2158
2457
 
2458
+ type TileflowNoticeControlPosition = 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right';
2459
+ /** A MapLibre control; its methods receive the map that owns it. */
2460
+ type TileflowNoticeControl = {
2461
+ onAdd(map: unknown): HTMLElement;
2462
+ onRemove(map: unknown): void;
2463
+ };
2464
+ type TileflowNoticeEvent = 'remove' | 'style.load' | 'styledata';
2465
+ /** Structural MapLibre capabilities; importing this module never loads a renderer. */
2466
+ type TileflowNoticesMap = {
2467
+ addControl(control: TileflowNoticeControl, position?: TileflowNoticeControlPosition): unknown;
2468
+ getContainer(): HTMLElement;
2469
+ getStyle(): {
2470
+ metadata?: unknown;
2471
+ } | undefined;
2472
+ off(event: TileflowNoticeEvent, listener: () => void): unknown;
2473
+ on(event: TileflowNoticeEvent, listener: () => void): unknown;
2474
+ removeControl(control: TileflowNoticeControl): unknown;
2475
+ };
2476
+ type TileflowNoticesOptions = {
2477
+ /** Map corner for the notice. Defaults to the attribution corner, `bottom-right`. */
2478
+ position?: TileflowNoticeControlPosition;
2479
+ };
2480
+ /**
2481
+ * Render the notices a compiled style declares, such as "Not for navigation" for Nautical, as a
2482
+ * compact always-visible map control. Call after constructing a browser map. Follows style
2483
+ * replacements and removes its control, listeners, and pending read on disposal or map removal.
2484
+ */
2485
+ declare function attachTileflowNotices(map: TileflowNoticesMap, options?: TileflowNoticesOptions): () => void;
2486
+
2487
+ /** Style metadata key for notices that must stay visible whenever the map is displayed. */
2488
+ declare const tileflowNoticesMetadataKey: "tileflow:notices";
2489
+ /**
2490
+ * A short plain-text notice the compiled style declares for the sources it names. Runtimes render
2491
+ * it on the map, next to the attribution; it never replaces a source's own attribution.
2492
+ */
2493
+ type TileflowMapNotice = Readonly<{
2494
+ id: string;
2495
+ sources: readonly string[];
2496
+ text: string;
2497
+ }>;
2498
+ declare const tileflowNoticeLimits: Readonly<{
2499
+ maxNotices: 8;
2500
+ maxSources: 16;
2501
+ maxTextLength: 120;
2502
+ }>;
2503
+ /** Read bounded notices from style metadata; malformed entries are ignored, never rendered. */
2504
+ declare function readTileflowNotices(metadata: unknown): readonly TileflowMapNotice[];
2505
+
2159
2506
  declare const tileflowMaplibreContourVersion: "0.1.0";
2160
2507
  type TileflowContourProtocolRequest = Readonly<{
2161
2508
  url: string;
@@ -2476,4 +2823,4 @@ declare function createTileflowTransformRequest<TRequest extends TileflowTransfo
2476
2823
  worldRequestBridge?: TileflowWorldRequestBridge;
2477
2824
  }): TileflowTransformRequest<TRequest, TResourceType>;
2478
2825
 
2479
- export { type TileflowAtmosphereMap, type TileflowBrowserThemeBlendSelection, type TileflowBuildingMesh, type TileflowBuildingMeshOptions, type TileflowBuildingModelPlacement, type TileflowBuildings3D, type TileflowBuildings3DChange, type TileflowBuildings3DDesign, type TileflowBuildings3DMap, type TileflowBuildings3DOptions, type TileflowBuildings3DThemes, type TileflowComposedRequest, type TileflowContourProtocolHandler, type TileflowContourProtocolRegistrationOptions, type TileflowContourProtocolRegistry, type TileflowContourProtocolRequest, type TileflowContourProtocolResponse, type TileflowDepthMarker, type TileflowDepthMarkerHandle, type TileflowDepthMarkerMap, type TileflowDepthMarkers, type TileflowDepthMarkersOptions, type TileflowDynamicImage, type TileflowDynamicImageContext, type TileflowDynamicImageHandle, type TileflowEmphasis, type TileflowEmphasisArea, type TileflowEmphasisModule, type TileflowFairUseNotice, type TileflowFairUseNoticeController, type TileflowFairUseNoticeState, type TileflowFrameScheduler, type TileflowGroundLayer, type TileflowGroundLayers, type TileflowGroundLayersMap, type TileflowGroundLayersOptions, type TileflowGroundOrderMap, type TileflowLineProgressAnimation, type TileflowLineProgressController, type TileflowLineProgressGradientOptions, type TileflowLineProgressLayer, type TileflowLineProgressMap, type TileflowLineProgressOptions, type TileflowLineProgressShown, type TileflowLineProgressState, type TileflowMapLifecycleAttachment, type TileflowMapLifecycleEvent, type TileflowMapLifecycleSubscriber, type TileflowMapReadinessState, type TileflowPmtilesProtocolHandler, type TileflowPmtilesProtocolRegistrationOptions, type TileflowPmtilesProtocolRegistry, type TileflowRouteInks, type TileflowSessionSender, type TileflowSessionStarter, type TileflowShotCamera, type TileflowShotCue, type TileflowShotKeyframe, type TileflowShotMotion, type TileflowShotPlayback, type TileflowShotPlaybackOptions, type TileflowShotPlayerMap, type TileflowShotState, type TileflowStreetLightEstimate, type TileflowStreetLightLayers, type TileflowStreetLightPlacement, type TileflowStreetLightPlacementOptions, type TileflowStreetLights, type TileflowStreetLightsDesign, type TileflowStreetLightsMap, type TileflowStreetLightsOptions, type TileflowStyleFontLoadOptions, type TileflowStyleStateValue, type TileflowStyleSwitchMap, type TileflowSun, type TileflowSunPreset, type TileflowSunRequest, type TileflowThemeBlendRequest, type TileflowThemeBlendState, type TileflowThemeChangeOptions, type TileflowThemeController, type TileflowThemeTransition, type TileflowThemeTransitionOptions, type TileflowThemeTransitionPhase, type TileflowThemeTransitionResult, type TileflowTile, type TileflowTileAddress, type TileflowTileAreaRequest, type TileflowTileFeature, type TileflowTileGeometryType, type TileflowTileLayer, type TileflowTileReader, type TileflowTileReaderOptions, type TileflowTileRequestTransform, type TileflowTileSourceMap, type TileflowTransformRequest, type TileflowTransformRequestParameters, type TileflowTreeFields, type TileflowTreeForm, type TileflowTreeFormMix, type TileflowTreeFormRange, type TileflowTreeLayers, type TileflowTreePlacement, type TileflowTreePlacementOptions, type TileflowTreeRange, type TileflowTreeRegion, type TileflowTrees3D, type TileflowTrees3DChange, type TileflowTrees3DMap, type TileflowTrees3DOptions, type TileflowTrees3DThemes, type TileflowUserTransformRequest, type TileflowVectorTileDecodeOptions, type TileflowVegetation3D, type TileflowVegetationController, type TileflowVegetationDisplay, type TileflowVegetationOptions, type TileflowVegetationRepresentation, type TileflowViewMode, type TileflowWorldProtocolHandler, type TileflowWorldProtocolRequest, type TileflowWorldProtocolResponse, type TileflowWorldRequestBridge, attachTileflowAtmosphere, attachTileflowFairUseNotice, attachTileflowMapLifecycle, createTileflowBuildings3D, createTileflowDepthMarkers, createTileflowGroundLayers, createTileflowLineProgress, createTileflowSessionStarter, createTileflowStreetLights, createTileflowThemeController, createTileflowTileReader, createTileflowTransformRequest, createTileflowTrees3D, createTileflowVegetation, decodeTileflowVectorTile, getTileflowSystemColorScheme, loadTileflowStyleFonts, meshTileflowBuildings, mixTileflowRouteInks, mixTileflowSunPresets, placeTileflowStreetLights, placeTileflowTrees, playTileflowShot, readTileflowBuildings3D, readTileflowMapTileSource, readTileflowRouteInks, readTileflowStreetLights, readTileflowSunPreset, readTileflowVegetation3D, readTileflowVegetationDisplay, registerTileflowContourProtocol, registerTileflowPmtilesProtocol, registerTileflowWorldRequestBridge, resolveTileflowSun, resolveTileflowVegetationRepresentation, subscribeTileflowSystemColorScheme, tileflowBuildingExtent, tileflowBuildingModelPlacementLimit, tileflowBuildingVertexBytes, tileflowBuildings3DLayerId, tileflowBuildingsMetadataKey, tileflowDefaultRouteInks, tileflowDefaultSunPreset, tileflowDepthMarkerPlacement, tileflowFairUseNoticeMessage, tileflowGroundBeforeId, tileflowLayerDomainMetadataKey, tileflowLineProgressGradient, tileflowMaplibreContourVersion, tileflowPmtilesMaximumDirectoryDepth, tileflowPmtilesProtocol, tileflowRouteMetadataKey, tileflowShotStateAt, tileflowStreetLightBytes, tileflowStreetLightsLayerId, tileflowStreetLightsMetadataKey, tileflowStyleRouteInks, tileflowStyleSunPreset, tileflowSunDirection, tileflowSunLightMatrix, tileflowSunMetadataKey, tileflowSunPosition, tileflowTilePointToLngLat, tileflowTilesForBounds, tileflowTreeBytes, tileflowTreeFormOf, tileflowTreeForms, tileflowTrees3DLayerId, tileflowVegetationDisplayMetadataKey, tileflowVegetationMetadataKey, validateTileflowBrowserThemeBlendSelection, validateTileflowEmphasis };
2826
+ export { type CreateBoundaryFeatureStateOptions, type TileflowAtmosphereMap, type TileflowBoundaryFeatureState, type TileflowBrowserThemeBlendSelection, type TileflowBuildingMesh, type TileflowBuildingMeshOptions, type TileflowBuildingModelPlacement, type TileflowBuildings3D, type TileflowBuildings3DChange, type TileflowBuildings3DDesign, type TileflowBuildings3DMap, type TileflowBuildings3DOptions, type TileflowBuildings3DThemes, type TileflowComposedRequest, type TileflowContourProtocolHandler, type TileflowContourProtocolRegistrationOptions, type TileflowContourProtocolRegistry, type TileflowContourProtocolRequest, type TileflowContourProtocolResponse, type TileflowDepthMarker, type TileflowDepthMarkerHandle, type TileflowDepthMarkerMap, type TileflowDepthMarkers, type TileflowDepthMarkersOptions, type TileflowDynamicImage, type TileflowDynamicImageContext, type TileflowDynamicImageHandle, type TileflowEmphasis, type TileflowEmphasisArea, type TileflowEmphasisModule, type TileflowFairUseNotice, type TileflowFairUseNoticeController, type TileflowFairUseNoticeState, type TileflowFeatureStateMap, type TileflowFrameScheduler, type TileflowGroundLayer, type TileflowGroundLayers, type TileflowGroundLayersMap, type TileflowGroundLayersOptions, type TileflowGroundOrderMap, type TileflowLineProgressAnimation, type TileflowLineProgressController, type TileflowLineProgressGradientOptions, type TileflowLineProgressLayer, type TileflowLineProgressMap, type TileflowLineProgressOptions, type TileflowLineProgressShown, type TileflowLineProgressState, type TileflowMapLifecycleAttachment, type TileflowMapLifecycleEvent, type TileflowMapLifecycleSubscriber, type TileflowMapNotice, type TileflowMapReadinessState, type TileflowNoticeControl, type TileflowNoticeControlPosition, type TileflowNoticesMap, type TileflowNoticesOptions, type TileflowPmtilesProtocolHandler, type TileflowPmtilesProtocolRegistrationOptions, type TileflowPmtilesProtocolRegistry, type TileflowRouteInks, type TileflowSessionSender, type TileflowSessionStarter, type TileflowShotCamera, type TileflowShotCue, type TileflowShotKeyframe, type TileflowShotMotion, type TileflowShotPlayback, type TileflowShotPlaybackOptions, type TileflowShotPlayerMap, type TileflowShotState, type TileflowStreetLightEstimate, type TileflowStreetLightLayers, type TileflowStreetLightPlacement, type TileflowStreetLightPlacementOptions, type TileflowStreetLights, type TileflowStreetLightsDesign, type TileflowStreetLightsMap, type TileflowStreetLightsOptions, type TileflowStyleFontLoadOptions, type TileflowStyleStateValue, type TileflowStyleSwitchMap, type TileflowSun, type TileflowSunPreset, type TileflowSunRequest, type TileflowThemeBlendRequest, type TileflowThemeBlendState, type TileflowThemeChangeOptions, type TileflowThemeController, type TileflowThemeTransition, type TileflowThemeTransitionOptions, type TileflowThemeTransitionPhase, type TileflowThemeTransitionResult, type TileflowTile, type TileflowTileAddress, type TileflowTileAreaRequest, type TileflowTileFeature, type TileflowTileGeometryType, type TileflowTileLayer, type TileflowTileReader, type TileflowTileReaderOptions, type TileflowTileRequestTransform, type TileflowTileSourceMap, type TileflowTransformRequest, type TileflowTransformRequestParameters, type TileflowTreeFields, type TileflowTreeForm, type TileflowTreeFormMix, type TileflowTreeFormRange, type TileflowTreeLayers, type TileflowTreePlacement, type TileflowTreePlacementOptions, type TileflowTreeRange, type TileflowTreeRegion, type TileflowTrees3D, type TileflowTrees3DChange, type TileflowTrees3DMap, type TileflowTrees3DOptions, type TileflowTrees3DThemes, type TileflowUserTransformRequest, type TileflowVectorTileDecodeOptions, type TileflowVegetation3D, type TileflowVegetationController, type TileflowVegetationDisplay, type TileflowVegetationOptions, type TileflowVegetationRepresentation, type TileflowViewMode, type TileflowWorldProtocolHandler, type TileflowWorldProtocolRequest, type TileflowWorldProtocolResponse, type TileflowWorldRequestBridge, attachTileflowAtmosphere, attachTileflowFairUseNotice, attachTileflowMapLifecycle, attachTileflowNotices, createBoundaryFeatureState, createTileflowBuildings3D, createTileflowDepthMarkers, createTileflowGroundLayers, createTileflowLineProgress, createTileflowSessionStarter, createTileflowStreetLights, createTileflowThemeController, createTileflowTileReader, createTileflowTransformRequest, createTileflowTrees3D, createTileflowVegetation, decodeTileflowVectorTile, getTileflowSystemColorScheme, loadTileflowStyleFonts, meshTileflowBuildings, mixTileflowRouteInks, mixTileflowSunPresets, placeTileflowStreetLights, placeTileflowTrees, playTileflowShot, readTileflowBuildings3D, readTileflowMapTileSource, readTileflowNotices, readTileflowRouteInks, readTileflowStreetLights, readTileflowSunPreset, readTileflowTeamModelName, readTileflowVegetation3D, readTileflowVegetationDisplay, registerTileflowContourProtocol, registerTileflowPmtilesProtocol, registerTileflowWorldRequestBridge, resolveTileflowSun, resolveTileflowVegetationRepresentation, subscribeTileflowSystemColorScheme, tileflowBuildingExtent, tileflowBuildingModelPlacementLimit, tileflowBuildingVertexBytes, tileflowBuildings3DLayerId, tileflowBuildingsMetadataKey, tileflowDefaultRouteInks, tileflowDefaultSunPreset, tileflowDepthMarkerPlacement, tileflowFairUseNoticeMessage, tileflowGroundBeforeId, tileflowLayerDomainMetadataKey, tileflowLineProgressGradient, tileflowMaplibreContourVersion, tileflowNoticeLimits, tileflowNoticesMetadataKey, tileflowPmtilesMaximumDirectoryDepth, tileflowPmtilesProtocol, tileflowRouteMetadataKey, tileflowShotStateAt, tileflowStreetLightBytes, tileflowStreetLightsLayerId, tileflowStreetLightsMetadataKey, tileflowStyleRouteInks, tileflowStyleSunPreset, tileflowSunDirection, tileflowSunLightMatrix, tileflowSunMetadataKey, tileflowSunPosition, tileflowTeamModelUrl, tileflowTilePointToLngLat, tileflowTilesForBounds, tileflowTreeBytes, tileflowTreeFormOf, tileflowTreeForms, tileflowTrees3DLayerId, tileflowVegetationDisplayMetadataKey, tileflowVegetationMetadataKey, validateTileflowBrowserThemeBlendSelection, validateTileflowEmphasis };