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

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
@@ -536,6 +536,137 @@ type MapLibreStyle = {
536
536
  metadata?: Record<string, unknown>;
537
537
  };
538
538
 
539
+ declare const tileflowSunMetadataKey = "tileflow:sun";
540
+ /** A theme's sun and sky light with every value resolved; see `TileflowThemeSun`. */
541
+ type TileflowSunPreset = Readonly<{
542
+ /** Degrees clockwise from north, from 0 to 360. */
543
+ azimuth: number;
544
+ /** Degrees above the horizon, from -90 to 90. */
545
+ altitude: number;
546
+ /** The direct light's colour. */
547
+ color: string;
548
+ /** The direct light's strength, from 0 to 1. */
549
+ intensity: number;
550
+ /** How dark the shadows the sun casts fall, from 0 (none) to 1. */
551
+ shadowIntensity: number;
552
+ /** The light from the sky, which reaches every surface and fills the shadows. */
553
+ ambient: Readonly<{
554
+ color: string;
555
+ intensity: number;
556
+ }>;
557
+ }>;
558
+ /** The sun as the map shows it, ready for an application's own layers. */
559
+ type TileflowSun = Readonly<{
560
+ /** Degrees clockwise from north, from 0 to 360. */
561
+ azimuth: number;
562
+ /** Degrees above the horizon, from -90 to 90. */
563
+ altitude: number;
564
+ /** A unit vector towards the sun: x east, y north, z up. */
565
+ direction: readonly [number, number, number];
566
+ /** The direct light's colour, as a CSS colour. */
567
+ color: string;
568
+ /** The direct light's colour as sRGB channels from 0 to 1. */
569
+ rgb: readonly [number, number, number];
570
+ /**
571
+ * The direct light's strength, from 0 to 1. It fades to 0 as the sun sets: a sun below the
572
+ * horizon lights nothing and casts no shadow.
573
+ */
574
+ intensity: number;
575
+ /** How dark the shadows the sun casts fall, from 0 (none) to 1. */
576
+ shadowIntensity: number;
577
+ /** The light from the sky, which reaches every surface and fills the shadows. */
578
+ ambient: Readonly<{
579
+ color: string;
580
+ rgb: readonly [number, number, number];
581
+ intensity: number;
582
+ }>;
583
+ /**
584
+ * How bright flat, open ground is under this light, from 0 (dark) to 1: the sky's light plus the
585
+ * sun's at its height, each weighted by its colour's luminance. Use it to switch lamps or windows
586
+ * on as a scene darkens, whatever theme or sun lights it.
587
+ */
588
+ brightness: number;
589
+ /** Where the direction comes from: the themes, angles, or a date and place. */
590
+ source: 'theme' | 'direction' | 'date';
591
+ }>;
592
+ /** The sun of a theme that leaves a value unset: high in the south-south-west, in white light. */
593
+ declare const tileflowDefaultSunPreset: TileflowSunPreset;
594
+ /**
595
+ * Where the sun stands for an instant and a place ([longitude, latitude] in degrees): its azimuth
596
+ * in degrees clockwise from north and its apparent altitude above the horizon, with atmospheric
597
+ * refraction. It follows NOAA's solar equations, accurate to about a hundredth of a degree for
598
+ * years 1800 to 2200.
599
+ */
600
+ declare function tileflowSunPosition(date: Date | number, location: readonly [number, number]): Readonly<{
601
+ azimuth: number;
602
+ altitude: number;
603
+ }>;
604
+ /** A unit vector towards a direction in the sky: x east, y north, z up. */
605
+ declare function tileflowSunDirection(azimuth: number, altitude: number): readonly [number, number, number];
606
+ /**
607
+ * The sun as the map shows it: a preset's light from a direction. Direct light fades out over the
608
+ * sun's last degrees above the horizon and is gone below it.
609
+ */
610
+ declare function resolveTileflowSun(preset: TileflowSunPreset, direction?: Readonly<{
611
+ azimuth: number;
612
+ altitude: number;
613
+ }>, source?: TileflowSun['source']): TileflowSun;
614
+ /**
615
+ * A preset `t` of the way from `from` to `to`: the azimuth turns the short way round, colours mix
616
+ * in OKLab, as theme blends mix paint colours, and numbers linearly.
617
+ */
618
+ declare function mixTileflowSunPresets(from: TileflowSunPreset, to: TileflowSunPreset, t: number): TileflowSunPreset;
619
+ /** Reads the sun a compiled style publishes, or undefined when its metadata has none. */
620
+ declare function readTileflowSunPreset(metadata: unknown): TileflowSunPreset | undefined;
621
+ /**
622
+ * The sun of a compiled style: the one it publishes, else one read from its light (a style whose
623
+ * theme describes no sun lights its extrusions from `light.position`), else the default.
624
+ */
625
+ declare function tileflowStyleSunPreset(style: {
626
+ light?: unknown;
627
+ metadata?: unknown;
628
+ } | undefined): TileflowSunPreset;
629
+
630
+ type TileflowThemeColorScheme = 'dark' | 'light';
631
+
632
+ declare const tileflowRouteMetadataKey = "tileflow:route";
633
+ /** The resolved inks of a route, from its outer glow to its bright core. */
634
+ type TileflowRouteInks = Readonly<{
635
+ /** The chosen route's line. */
636
+ line: string;
637
+ /** The edge on each side of the line, which sets it apart from the roads under it. */
638
+ casing: string;
639
+ /** A thin line along the middle of the route. */
640
+ core: string;
641
+ /** A soft halo around the route. */
642
+ glow: string;
643
+ /** Other routes offered beside the chosen one. */
644
+ alternative: string;
645
+ /** Opacity of the glow, from 0 (no glow) to 1. */
646
+ glowOpacity: number;
647
+ /** Opacity of the core, from 0 (no core) to 1. */
648
+ coreOpacity: number;
649
+ }>;
650
+ /** The inks of a theme that sets no route tokens: a blue that reads on either kind of map. */
651
+ declare const tileflowDefaultRouteInks: Readonly<Record<TileflowThemeColorScheme, TileflowRouteInks>>;
652
+ /**
653
+ * Reads the route inks a compiled style publishes, or undefined when its metadata has none (a
654
+ * style compiled before route inks, or not by Tileflow).
655
+ */
656
+ declare function readTileflowRouteInks(metadata: unknown): TileflowRouteInks | undefined;
657
+ /**
658
+ * The route inks of a compiled style: those it publishes, or the defaults of its colour scheme
659
+ * (from its `tileflow:colorScheme` metadata, else `fallbackScheme`).
660
+ */
661
+ declare function tileflowStyleRouteInks(style: {
662
+ metadata?: unknown;
663
+ } | undefined, fallbackScheme?: TileflowThemeColorScheme): TileflowRouteInks;
664
+ /**
665
+ * Inks between two themes' inks, `t` of the way from `from` to `to`: colours mix in OKLab, as theme
666
+ * blends mix paint colours, and opacities linearly.
667
+ */
668
+ declare function mixTileflowRouteInks(from: TileflowRouteInks, to: TileflowRouteInks, t: number): TileflowRouteInks;
669
+
539
670
  type TileflowRuntimeColorScheme = 'dark' | 'light';
540
671
 
541
672
  type TileflowAnalytics = {
@@ -830,6 +961,730 @@ type TileflowAtmosphereMap = {
830
961
  */
831
962
  declare function attachTileflowAtmosphere(map: TileflowAtmosphereMap): () => void;
832
963
 
964
+ /** The drawn stretch of a line and its highlights, as shares of the line's length from its start. */
965
+ type TileflowLineProgressState = Readonly<{
966
+ /** Where the drawn stretch starts, from 0 (the default) to 1. */
967
+ start?: number;
968
+ /** Where the drawn stretch ends, from 0 to 1 (the default, the whole line). */
969
+ end?: number;
970
+ /** Where a light sits along the line, or undefined (the default) for none. */
971
+ light?: number;
972
+ /** The whole line's opacity, multiplied with each layer's own, from 0 to 1 (the default). */
973
+ opacity?: number;
974
+ }>;
975
+ type TileflowLineProgressGradientOptions = Readonly<{
976
+ /** The line's colour. */
977
+ color: string;
978
+ /** The colour at the head and in the light; defaults to `color`, which shows neither. */
979
+ highlight?: string;
980
+ /**
981
+ * Length of the head's highlight, as a share of the line. The head shows while the drawn stretch
982
+ * ends before the line does. Defaults to 0.04; 0 shows no head.
983
+ */
984
+ headLength?: number;
985
+ /** Length of the light, as a share of the line. Defaults to `headLength`. */
986
+ lightLength?: number;
987
+ }>;
988
+ /**
989
+ * The `line-gradient` of a line drawn from `state.start` to `state.end`. The source of the layer
990
+ * must be GeoJSON with `lineMetrics: true`.
991
+ */
992
+ declare function tileflowLineProgressGradient(state: TileflowLineProgressState, options: TileflowLineProgressGradientOptions): unknown[];
993
+
994
+ /** Structural MapLibre capabilities; importing this module never loads a renderer. */
995
+ type TileflowLineProgressMap = {
996
+ getCanvas?: unknown;
997
+ getLayer(id: string): unknown;
998
+ setPaintProperty(layer: string, name: string, value: unknown): unknown;
999
+ on(event: 'styledata', listener: () => void): unknown;
1000
+ off(event: 'styledata', listener: () => void): unknown;
1001
+ };
1002
+ /** One line layer of the group, over a GeoJSON source with `lineMetrics: true`. */
1003
+ type TileflowLineProgressLayer = Readonly<{
1004
+ id: string;
1005
+ /** The layer's colour along the drawn line. */
1006
+ color: string;
1007
+ /** The colour at the head and in the light; defaults to `color`. */
1008
+ highlight?: string;
1009
+ /** The layer's own opacity, from 0 to 1 (the default). */
1010
+ opacity?: number;
1011
+ }>;
1012
+ type TileflowLineProgressOptions = Readonly<{
1013
+ /** The layers drawn together, such as a route's glow, casing, line and core. */
1014
+ layers: readonly TileflowLineProgressLayer[];
1015
+ /** Length of the head's highlight, as a share of the line; defaults to 0.04. */
1016
+ headLength?: number;
1017
+ /** Length of the light, as a share of the line; defaults to `headLength`. */
1018
+ lightLength?: number;
1019
+ /** What the layers show at first; defaults to the whole line, without a light. */
1020
+ initial?: TileflowLineProgressState;
1021
+ }>;
1022
+ type TileflowLineProgressAnimation = Readonly<{
1023
+ /** The values to reach; values left out keep what they show. */
1024
+ to: TileflowLineProgressState;
1025
+ /** Milliseconds, from 0 to 60000. */
1026
+ duration: number;
1027
+ /** Maps elapsed time (0 to 1) to progress (0 to 1); defaults to an ease in and out. */
1028
+ easing?: (t: number) => number;
1029
+ }>;
1030
+ /** What the layers show: `light` is absent when no light shows. */
1031
+ type TileflowLineProgressShown = Readonly<{
1032
+ start: number;
1033
+ end: number;
1034
+ light?: number;
1035
+ opacity: number;
1036
+ }>;
1037
+ type TileflowLineProgressController = {
1038
+ /** What the layers show now, mid-animation included. */
1039
+ get(): TileflowLineProgressShown;
1040
+ /**
1041
+ * Shows new values at once and stops a running animation. Values left out keep what they show;
1042
+ * `light: undefined` takes the light off.
1043
+ */
1044
+ set(state: TileflowLineProgressState): void;
1045
+ /**
1046
+ * Moves to new values over a duration and resolves `true` when it gets there, or `false` when
1047
+ * `set`, another animation, or `dispose` stops it first. A light that is not showing starts from
1048
+ * the start of the drawn stretch. With reduced motion requested, it shows the values at once.
1049
+ */
1050
+ animate(animation: TileflowLineProgressAnimation): Promise<boolean>;
1051
+ /** Changes the layers' colours or the highlight lengths, for example when the theme changes. */
1052
+ configure(options: Partial<Omit<TileflowLineProgressOptions, 'initial'>>): void;
1053
+ /** Stops writing to the map. The layers keep what they show. */
1054
+ dispose(): void;
1055
+ };
1056
+ /**
1057
+ * Draws a line on, a share of its length at a time, over a group of MapLibre line layers: their
1058
+ * `line-gradient` shows the drawn stretch, a bright head where it is being drawn, and a light that
1059
+ * can run along it. The controller owns each layer's `line-gradient` and `line-opacity`, writes
1060
+ * only what changed, and paints a layer again when a style change re-creates it. Layers that are
1061
+ * not on the map are skipped until they are.
1062
+ */
1063
+ declare function createTileflowLineProgress(map: TileflowLineProgressMap, options: TileflowLineProgressOptions): TileflowLineProgressController;
1064
+
1065
+ type TileflowTileGeometryType = 'Point' | 'LineString' | 'Polygon';
1066
+ type TileflowTileFeature = Readonly<{
1067
+ /** The feature's id in the tile, when it has one. */
1068
+ id?: number;
1069
+ type: TileflowTileGeometryType;
1070
+ properties: Readonly<Record<string, string | number | boolean>>;
1071
+ /**
1072
+ * One flat `[x0, y0, x1, y1, …]` array per point set, line or ring, in tile units from 0 to the
1073
+ * layer's extent (coordinates in a tile's buffer fall outside that range). Polygon rings follow
1074
+ * the MVT winding: an exterior ring is clockwise in tile units, a hole anticlockwise.
1075
+ */
1076
+ geometry: readonly (readonly number[])[];
1077
+ }>;
1078
+ type TileflowTileLayer = Readonly<{
1079
+ /** Tile units across the tile, usually 4096. */
1080
+ extent: number;
1081
+ features: readonly TileflowTileFeature[];
1082
+ }>;
1083
+ type TileflowVectorTileDecodeOptions = Readonly<{
1084
+ /** The layers to decode; others are skipped without decoding. Defaults to every layer. */
1085
+ layers?: readonly string[];
1086
+ }>;
1087
+ /** Decodes a Mapbox Vector Tile's layers. Throws on bytes that are not a vector tile. */
1088
+ declare function decodeTileflowVectorTile(bytes: Uint8Array, options?: TileflowVectorTileDecodeOptions): Readonly<Record<string, TileflowTileLayer>>;
1089
+
1090
+ type TileflowTileAddress = Readonly<{
1091
+ z: number;
1092
+ x: number;
1093
+ y: number;
1094
+ }>;
1095
+ /** A decoded tile: its address and the chosen layers it holds. */
1096
+ type TileflowTile = TileflowTileAddress & Readonly<{
1097
+ layers: Readonly<Record<string, TileflowTileLayer>>;
1098
+ }>;
1099
+ /** Rewrites a tile request as a MapLibre map's `transformRequest` does. */
1100
+ type TileflowTileRequestTransform = (url: string, resourceType: 'Tile') => Readonly<{
1101
+ url: string;
1102
+ headers?: Readonly<Record<string, string>>;
1103
+ credentials?: RequestCredentials;
1104
+ }> | undefined;
1105
+ type TileflowTileReaderOptions = Readonly<{
1106
+ /** The tile address with `{z}`, `{x}` and `{y}`, such as a MapLibre vector source's `tiles[0]`. */
1107
+ tiles: string;
1108
+ /** The lowest zoom the source has tiles for; defaults to 0. */
1109
+ minzoom?: number;
1110
+ /** The highest zoom the source has tiles for; deeper reads use its tiles. Defaults to 14. */
1111
+ maxzoom?: number;
1112
+ /** The layers to decode; defaults to every layer. */
1113
+ layers?: readonly string[];
1114
+ /** Decoded tiles kept for later reads, from 0 to 4096; defaults to 128. */
1115
+ cacheSize?: number;
1116
+ /** Requests in flight at once, from 1 to 32; defaults to 6. */
1117
+ concurrency?: number;
1118
+ /** The map's request rules, applied to every tile request. */
1119
+ transformRequest?: TileflowTileRequestTransform;
1120
+ /** Defaults to the global `fetch`. */
1121
+ fetch?: (url: string, init: RequestInit) => Promise<Response>;
1122
+ }>;
1123
+ type TileflowTileAreaRequest = Readonly<{
1124
+ /** `[west, south, east, north]` in degrees. */
1125
+ bounds: readonly [number, number, number, number];
1126
+ /** The zoom to read at, clamped to the source's zooms. */
1127
+ zoom: number;
1128
+ /** The most tiles the area may take; a larger area is refused. Defaults to 64. */
1129
+ maxTiles?: number;
1130
+ signal?: AbortSignal;
1131
+ }>;
1132
+ type TileflowTileReader = {
1133
+ /** A tile's chosen layers, or undefined when the source has no tile there (404 or 204). */
1134
+ readTile(address: TileflowTileAddress, options?: {
1135
+ signal?: AbortSignal;
1136
+ }): Promise<TileflowTile | undefined>;
1137
+ /** The tiles covering an area at a zoom, without the absent ones, nearest the centre first. */
1138
+ readArea(request: TileflowTileAreaRequest): Promise<TileflowTile[]>;
1139
+ /** Forgets every cached tile. */
1140
+ clear(): void;
1141
+ };
1142
+ /** The tiles at `zoom` covering `[west, south, east, north]`, nearest the centre first. */
1143
+ declare function tileflowTilesForBounds(bounds: readonly [number, number, number, number], zoom: number): TileflowTileAddress[];
1144
+ /** The longitude and latitude of a point in a tile, given in tile units of an `extent`. */
1145
+ declare function tileflowTilePointToLngLat(tile: TileflowTileAddress, x: number, y: number, extent?: number): [number, number];
1146
+ /**
1147
+ * Reads a vector source's tiles in an application: for example a MapLibre map's World source, with
1148
+ * `tiles`, `minzoom` and `maxzoom` taken from `map.getSource(id)`, and the map's `transformRequest`.
1149
+ */
1150
+ declare function createTileflowTileReader(options: TileflowTileReaderOptions): TileflowTileReader;
1151
+ /** Structural MapLibre capability; importing this module never loads a renderer. */
1152
+ type TileflowTileSourceMap = {
1153
+ getSource(id: string): unknown;
1154
+ };
1155
+ /**
1156
+ * The tile address and zooms of a map's vector source once the map has loaded it, ready for
1157
+ * `createTileflowTileReader`; undefined while the source is not loaded or has no tile address.
1158
+ */
1159
+ declare function readTileflowMapTileSource(map: TileflowTileSourceMap, sourceId: string): {
1160
+ tiles: string;
1161
+ minzoom: number;
1162
+ maxzoom: number;
1163
+ } | undefined;
1164
+
1165
+ /** The MapLibre GL JS map capabilities the renderer uses. */
1166
+ type TileflowBuildings3DMap = {
1167
+ addLayer(layer: object, beforeId?: string): unknown;
1168
+ getCenter(): {
1169
+ lat: number;
1170
+ lng: number;
1171
+ };
1172
+ getBearing(): number;
1173
+ getLayer(id: string): unknown;
1174
+ getPaintProperty(layer: string, name: string): unknown;
1175
+ getPitch(): number;
1176
+ getSource(id: string): unknown;
1177
+ getStyle(): unknown;
1178
+ getZoom(): number;
1179
+ isStyleLoaded(): boolean | void;
1180
+ off(event: string, listener: () => void): unknown;
1181
+ on(event: string, listener: () => void): unknown;
1182
+ removeLayer(id: string): unknown;
1183
+ triggerRepaint(): unknown;
1184
+ };
1185
+ /** Where the renderer reads the sun and the themes: a Tileflow theme controller. */
1186
+ type TileflowBuildings3DThemes = {
1187
+ getBlend?(): {
1188
+ position: number;
1189
+ themes: readonly string[];
1190
+ } | undefined;
1191
+ getCurrent?(): {
1192
+ theme?: string;
1193
+ };
1194
+ getSun?(): TileflowSun;
1195
+ };
1196
+ type TileflowBuildings3DOptions = Readonly<{
1197
+ map: TileflowBuildings3DMap;
1198
+ /** The theme controller, for the sun and, with `color`, the themes on screen. */
1199
+ controller?: TileflowBuildings3DThemes;
1200
+ /** The vector source to read; defaults to `tileflow`, a Tileflow map's World source. */
1201
+ source?: string;
1202
+ /** The source layer with the buildings; defaults to `building`. */
1203
+ sourceLayer?: string;
1204
+ /**
1205
+ * The source layer with the places, for the night use of buildings in tiles whose buildings do
1206
+ * not carry World's `night_use`; defaults to `poi`.
1207
+ */
1208
+ placesLayer?: string;
1209
+ /**
1210
+ * A building's colour for a theme, from its feature properties, as a CSS colour. Each building
1211
+ * is coloured once per theme, and the renderer mixes the colours of the themes either side of
1212
+ * a blend's position. Without it, buildings take the theme's 3D building colour.
1213
+ */
1214
+ color?: (properties: Readonly<Record<string, string | number | boolean>>, theme: string) => string;
1215
+ /** Shadows from the sun, on the buildings and the flat map; defaults to true. */
1216
+ shadows?: boolean;
1217
+ /** Contact shadow at the foot of the walls and in tight corners; defaults to true. */
1218
+ occlusion?: boolean;
1219
+ /**
1220
+ * How bright the buildings light the street at night, from 0 (none) to 2; defaults to 1, a quiet
1221
+ * light. Landmarks (World's `building_tone`) and towers are flood-lit at their foot, and buildings
1222
+ * with places busy at night (World's `night_use`) light their ground floor windows and the
1223
+ * pavement in front: bars and clubs in neon or a warm light, theatres and cinemas in white,
1224
+ * places to eat in amber.
1225
+ */
1226
+ nightLight?: number;
1227
+ /**
1228
+ * How strongly roof outlines and buildings' outer corners catch the light, from 0 (none) to 1;
1229
+ * defaults to 1. They keep a constant width on screen, so where one building ends and the next
1230
+ * starts stays legible at any distance, at night most of all.
1231
+ */
1232
+ edges?: number;
1233
+ /**
1234
+ * The colour of roof outlines and outer corners, as a CSS colour or per theme, drawn as it is,
1235
+ * unlit, at the full `edges` strength by day and night. The renderer asks for each theme's colour
1236
+ * once and mixes the colours of the themes either side of a blend's position; a theme without a
1237
+ * valid colour keeps the default. Without it, edges take the building's own colour, lightened as
1238
+ * if catching the light, half as strong by day as at night.
1239
+ */
1240
+ edgeColor?: string | ((theme: string) => string);
1241
+ /** Invented night windows, lit by rooms; decoration, not data. Defaults to false. */
1242
+ windows?: boolean;
1243
+ /** The zoom from which buildings stand; below it they sink into the flat map. Defaults to 14.5. */
1244
+ minzoom?: number;
1245
+ /** The most tiles raised round the camera, from 1 to 64; defaults to 25. */
1246
+ maxTiles?: number;
1247
+ /** The layer to draw before; defaults to the style's `above-buildings` placement. */
1248
+ beforeId?: string;
1249
+ /** The map's request rules, for the tiles the renderer reads. */
1250
+ transformRequest?: TileflowTileRequestTransform;
1251
+ }>;
1252
+ type TileflowBuildings3DChange = Readonly<{
1253
+ transition?: Readonly<{
1254
+ duration?: number;
1255
+ }>;
1256
+ }>;
1257
+ type TileflowBuildings3D = {
1258
+ /** Raises the buildings out of the ground; resolves once they stand. */
1259
+ show(options?: TileflowBuildings3DChange): Promise<void>;
1260
+ /** Sinks the buildings back into the flat map; resolves once they are gone. */
1261
+ hide(options?: TileflowBuildings3DChange): Promise<void>;
1262
+ /** Eases the buildings to `scale` of their height, from 0 (flat) to 1. */
1263
+ grow(scale: number, options?: TileflowBuildings3DChange): Promise<void>;
1264
+ /** The height scale shown now. */
1265
+ readonly scale: number;
1266
+ /** Tiles raised, buildings and vertices, for diagnostics. */
1267
+ readonly stats: Readonly<{
1268
+ tiles: number;
1269
+ buildings: number;
1270
+ vertices: number;
1271
+ }>;
1272
+ /** Takes the layer off the map and lets go of its buffers. */
1273
+ dispose(): void;
1274
+ };
1275
+ declare const tileflowBuildings3DLayerId = "tileflow-buildings-3d";
1276
+ /**
1277
+ * Creates the renderer and puts its layer on the map, flat until `show()`. It reads the source's
1278
+ * z15 tiles round the camera, the zoom at which World's buildings carry their heights.
1279
+ */
1280
+ declare function createTileflowBuildings3D(options: TileflowBuildings3DOptions): TileflowBuildings3D;
1281
+ /**
1282
+ * The sun's view of a box of buildings: an orthographic projection along `direction` (towards the
1283
+ * sun; x east, y north, z up, in metres) as a column-major matrix to clip space, with the metres its
1284
+ * depth runs over and the metres its wider side spans. It follows only the sun, never the camera,
1285
+ * so shadows hold still while the camera moves.
1286
+ */
1287
+ declare function tileflowSunLightMatrix(direction: readonly number[], box: Readonly<{
1288
+ min: readonly number[];
1289
+ max: readonly number[];
1290
+ }>): {
1291
+ matrix: Float32Array;
1292
+ depth: number;
1293
+ extent: number;
1294
+ };
1295
+
1296
+ /** The renderer's tile units: MapLibre projects custom layers' tiles over 8192. */
1297
+ declare const tileflowBuildingExtent = 8192;
1298
+ /** Bytes per vertex; see `meshTileflowBuildings` for the layout. */
1299
+ declare const tileflowBuildingVertexBytes = 28;
1300
+ type TileflowBuildingMeshOptions = Readonly<{
1301
+ /** The tile's width in metres, for the length of each wall. */
1302
+ tileMetres: number;
1303
+ /** Height used where a building has none, in metres; defaults to 5, World's own fallback. */
1304
+ defaultHeight?: number;
1305
+ /**
1306
+ * The tile's places (World's `poi` layer), for the night use of buildings when the tile's
1307
+ * buildings do not carry World's `night_use`: a place inside a building, or on its facade, gives
1308
+ * the building its use.
1309
+ */
1310
+ places?: TileflowTileLayer;
1311
+ }>;
1312
+ /** One tile's buildings, ready to upload. */
1313
+ type TileflowBuildingMesh = Readonly<{
1314
+ vertices: Uint8Array;
1315
+ indices: Uint32Array;
1316
+ /** The first wall index: roofs come before it, walls from it. */
1317
+ wallsFrom: number;
1318
+ /** The tallest building, in metres. */
1319
+ top: number;
1320
+ /** Each vertex's building is an index into these feature properties. */
1321
+ features: readonly Readonly<Record<string, string | number | boolean>>[];
1322
+ }>;
1323
+ /**
1324
+ * Meshes the buildings of one decoded tile layer, or returns undefined when it has none. It reads
1325
+ * World's `render_height`, `render_min_height`, `hide_3d`, `building_tone` and `night_use`. Vertex layout:
1326
+ * 0 position in the tile, 0 to 8192 (uint16 ×2); 4 base and top in decimetres (uint16 ×2); 8 the
1327
+ * wall's outward normal (int8 ×2, normalised); 10 raised to the top, part of a wall (uint8 ×2);
1328
+ * 12 decimetres along the wall (uint16); 14 a per-building jitter and seed (uint8 ×2, normalised);
1329
+ * 16 the building's centre in the tile (uint16 ×2); 20 tone and night use (uint8 ×2: none, dining,
1330
+ * entertainment, nightlife); 22 the wall's
1331
+ * tight corners, bit 0 at its start and bit 1 at its end, and bit 2 when it faces a courtyard, and
1332
+ * its length in metres up to 255
1333
+ * (uint8 ×2); 24 the building's feature index (uint16); 26 on a roof, the vertex's corner of its
1334
+ * triangle (0 to 2), on a wall, 0 at its start and 1 at its end (uint8); 27 on a roof, the triangle's
1335
+ * sides that are the roof's outline, bit n for the side facing corner n, on a wall, bit 0 when its
1336
+ * start and bit 1 when its end lies on the tile's edge (uint8).
1337
+ *
1338
+ * A building's jitter is the same for every piece of it a tile edge cuts, so the renderer can vary
1339
+ * buildings' brightness with it without a seam along the tile's edge.
1340
+ */
1341
+ declare function meshTileflowBuildings(layer: TileflowTileLayer, options: TileflowBuildingMeshOptions): TileflowBuildingMesh | undefined;
1342
+
1343
+ /** Bytes per lamp; see `placeTileflowStreetLights` for the layout. */
1344
+ declare const tileflowStreetLightBytes = 12;
1345
+ /**
1346
+ * Where light is estimated where the data maps no lamps: `lit` (the default) along the streets and
1347
+ * pavements the data maps as lit; `streets` also along the streets the data says nothing about,
1348
+ * wherever it maps few lamps, which invents light as night windows do; `none` nowhere, so only
1349
+ * mapped lamps shine.
1350
+ */
1351
+ type TileflowStreetLightEstimate = 'streets' | 'lit' | 'none';
1352
+ type TileflowStreetLightPlacementOptions = Readonly<{
1353
+ /** The tile's width in metres. */
1354
+ tileMetres: number;
1355
+ /** Defaults to `lit`. */
1356
+ estimate?: TileflowStreetLightEstimate;
1357
+ }>;
1358
+ /** A tile's layers the lamps come from, as World names them. */
1359
+ type TileflowStreetLightLayers = Readonly<{
1360
+ /** Points with `subclass` `street_lamp` (World's `street_furniture`). */
1361
+ streetFurniture?: TileflowTileLayer;
1362
+ /** Streets by `class`, with `lit` where mapped (World's `transportation`). */
1363
+ transportation?: TileflowTileLayer;
1364
+ /** Pavements, as lines or areas, with `lit` where mapped (World's `sidewalk`). */
1365
+ sidewalks?: TileflowTileLayer;
1366
+ }>;
1367
+ /** One tile's lamps, ready to upload. */
1368
+ type TileflowStreetLightPlacement = Readonly<{
1369
+ lamps: Uint8Array;
1370
+ /** Lamps from the data. */
1371
+ mapped: number;
1372
+ /** Points of soft light estimated along streets. */
1373
+ estimated: number;
1374
+ }>;
1375
+ /**
1376
+ * Places one tile's lamps and estimated light, or returns undefined when it has none. Each is a
1377
+ * point of light, flagged as mapped or estimated. Layout: 0 position in the
1378
+ * tile, 0 to 8192 (uint16 ×2); 4 height in decimetres (uint16); 6 the reach of its light on the
1379
+ * ground in metres (uint8); 7 flags (uint8: bit 0 mapped, bit 1 its own colour); 8 its colour
1380
+ * (uint8 ×3, sRGB); 11 a seed (uint8, normalised).
1381
+ */
1382
+ declare function placeTileflowStreetLights(layers: TileflowStreetLightLayers, options: TileflowStreetLightPlacementOptions): TileflowStreetLightPlacement | undefined;
1383
+
1384
+ /** The MapLibre GL JS map capabilities the street lights use. */
1385
+ type TileflowStreetLightsMap = {
1386
+ addLayer(layer: object, beforeId?: string): unknown;
1387
+ getBearing(): number;
1388
+ getCenter(): {
1389
+ lat: number;
1390
+ lng: number;
1391
+ };
1392
+ getLayer(id: string): unknown;
1393
+ getPitch(): number;
1394
+ getSource(id: string): unknown;
1395
+ getStyle(): unknown;
1396
+ getZoom(): number;
1397
+ isStyleLoaded(): boolean | void;
1398
+ off(event: string, listener: () => void): unknown;
1399
+ on(event: string, listener: () => void): unknown;
1400
+ removeLayer(id: string): unknown;
1401
+ triggerRepaint(): unknown;
1402
+ };
1403
+ type TileflowStreetLightsOptions = Readonly<{
1404
+ map: TileflowStreetLightsMap;
1405
+ /** The theme controller, whose sun switches the lights on and off. */
1406
+ controller?: {
1407
+ getSun?(): TileflowSun;
1408
+ };
1409
+ /** The vector source to read; defaults to `tileflow`, a Tileflow map's World source. */
1410
+ source?: string;
1411
+ /**
1412
+ * Where soft light is estimated where the data maps no lamps: `lit` (the default) along the
1413
+ * streets and pavements the data maps as lit; `streets` also along the streets the data says
1414
+ * nothing about, wherever it maps few lamps, which invents light as night windows do; `none`
1415
+ * nowhere, so only mapped lamps shine.
1416
+ */
1417
+ estimate?: TileflowStreetLightEstimate;
1418
+ /** The light of the lamps whose data gives no colour, as a CSS colour; a warm white by default. */
1419
+ color?: string;
1420
+ /** How bright the lights shine, from 0 to 2; defaults to 1. */
1421
+ intensity?: number;
1422
+ /** The zoom from which the lights shine. Defaults to 14. */
1423
+ minzoom?: number;
1424
+ /** The most tiles lit round the camera, from 1 to 64; defaults to 25. */
1425
+ maxTiles?: number;
1426
+ /** The layer to draw before; defaults to the style's `above-buildings` placement. */
1427
+ beforeId?: string;
1428
+ /** The map's request rules, for the tiles the layer reads. */
1429
+ transformRequest?: TileflowTileRequestTransform;
1430
+ }>;
1431
+ type TileflowStreetLights = {
1432
+ /** How far the lights have switched on, from 0 by day to 1 at night. */
1433
+ readonly on: number;
1434
+ /** Tiles lit, lamps, and how many of them the data maps or the layer estimates. */
1435
+ readonly stats: Readonly<{
1436
+ tiles: number;
1437
+ lamps: number;
1438
+ mapped: number;
1439
+ estimated: number;
1440
+ }>;
1441
+ /** Takes the layer off the map and lets go of its buffers. */
1442
+ dispose(): void;
1443
+ };
1444
+ declare const tileflowStreetLightsLayerId = "tileflow-street-lights";
1445
+ /**
1446
+ * Creates the street lights and puts their layer on the map. They read the source's z15 tiles round
1447
+ * the camera once the controller's sun darkens the map, and shine from `minzoom`.
1448
+ */
1449
+ declare function createTileflowStreetLights(options: TileflowStreetLightsOptions): TileflowStreetLights;
1450
+
1451
+ /** The capabilities `tileflowGroundBeforeId` reads; importing this module never loads a renderer. */
1452
+ type TileflowGroundOrderMap = {
1453
+ getLayer(id: string): unknown;
1454
+ getLayersOrder(): string[];
1455
+ getStyle(): unknown;
1456
+ };
1457
+ /** Structural MapLibre capabilities of a map that holds a ground layer group. */
1458
+ type TileflowGroundLayersMap = TileflowGroundOrderMap & {
1459
+ addLayer(layer: unknown, beforeId?: string): unknown;
1460
+ getSource(id: string): unknown;
1461
+ moveLayer(id: string, beforeId?: string): unknown;
1462
+ removeLayer(id: string): unknown;
1463
+ setPaintProperty(layer: string, name: string, value: unknown): unknown;
1464
+ setLayoutProperty(layer: string, name: string, value: unknown): unknown;
1465
+ getCanvas?(): unknown;
1466
+ on(event: 'styledata', listener: () => void): unknown;
1467
+ off(event: 'styledata', listener: () => void): unknown;
1468
+ };
1469
+ /**
1470
+ * A layer of the group: a MapLibre style layer drawn in 2D, such as a line or a fill, or a custom
1471
+ * layer whose `renderingMode` is `2d`.
1472
+ */
1473
+ type TileflowGroundLayer = Readonly<Record<string, unknown> & {
1474
+ id: string;
1475
+ type: string;
1476
+ }> | Readonly<{
1477
+ id: string;
1478
+ type: 'custom';
1479
+ renderingMode?: '2d' | '3d';
1480
+ }>;
1481
+ type TileflowGroundLayersOptions = Readonly<{
1482
+ /** The layers, bottom to top, such as a route's glow, casing, line and core. */
1483
+ layers: readonly TileflowGroundLayer[];
1484
+ /**
1485
+ * How much of each line layer shows where 3D content hides it, by layer id: from 0 (nothing, the
1486
+ * default) to 1 (as much as where it shows). Only line layers whose `line-opacity` is a number
1487
+ * can show through.
1488
+ */
1489
+ occludedOpacity?: Readonly<Record<string, number>>;
1490
+ }>;
1491
+ type TileflowGroundLayers = {
1492
+ /** The group's layer ids, bottom to top. */
1493
+ readonly ids: readonly string[];
1494
+ /** The map's layer, so helpers that paint layers, such as line progress, can paint the group. */
1495
+ getLayer(id: string): unknown;
1496
+ /**
1497
+ * Sets a paint property of one of the group's layers, and keeps it for when a style change brings
1498
+ * the layer back. A layer that shows through 3D content passes it to its see-through copy too, at
1499
+ * its `line-opacity` times its occluded opacity. Other layers' properties pass straight to the map.
1500
+ */
1501
+ setPaintProperty(layer: string, name: string, value: unknown): void;
1502
+ /** Sets a layout property, such as `visibility`, the same way. */
1503
+ setLayoutProperty(layer: string, name: string, value: unknown): void;
1504
+ getCanvas(): unknown;
1505
+ on(event: 'styledata', listener: () => void): void;
1506
+ off(event: 'styledata', listener: () => void): void;
1507
+ /** Takes the group's layers and their copies off the map and stops following style changes. */
1508
+ dispose(): void;
1509
+ };
1510
+ /**
1511
+ * The layer a layer lying on the ground goes before: the first 3D layer above the roads, or the
1512
+ * start of the vegetation when the buildings are flat, so the layer covers the roads and the flat
1513
+ * buildings, and every 3D layer hides it where it stands in front. A style without Tileflow's
1514
+ * overlay placements uses its first 3D layer or its first symbol layer. Undefined means the top.
1515
+ */
1516
+ declare function tileflowGroundBeforeId(map: TileflowGroundOrderMap): string | undefined;
1517
+ /**
1518
+ * Keeps a group of application layers on the ground, under the map's 3D content, from bottom to
1519
+ * top as given. Layers already on the map are moved into place; a layer whose source is not on the
1520
+ * map yet is added when it is. The group follows the map: after a style change it brings back the
1521
+ * layers the change dropped, and it moves its layers again when a 3D layer lands above them, so
1522
+ * a layer added later in 3D hides them too. A line with an occluded opacity gets a see-through
1523
+ * copy over the 3D content, painted through the group.
1524
+ */
1525
+ declare function createTileflowGroundLayers(map: TileflowGroundLayersMap, options: TileflowGroundLayersOptions): TileflowGroundLayers;
1526
+
1527
+ /** Structural MapLibre capabilities; importing this module never loads a renderer. */
1528
+ type TileflowDepthMarkerMap = {
1529
+ addLayer(layer: unknown, beforeId?: string): unknown;
1530
+ getLayer(id: string): unknown;
1531
+ removeLayer(id: string): unknown;
1532
+ getCanvas(): HTMLCanvasElement;
1533
+ getPixelRatio?(): number;
1534
+ triggerRepaint(): void;
1535
+ on(event: 'styledata', listener: () => void): unknown;
1536
+ off(event: 'styledata', listener: () => void): unknown;
1537
+ };
1538
+ type TileflowDepthMarker = Readonly<{
1539
+ /** `[longitude, latitude]`. */
1540
+ lngLat: readonly [number, number];
1541
+ /** The marker's picture. Pass it again to `update` after drawing into it. */
1542
+ image: TexImageSource;
1543
+ /** Width and height: CSS pixels for a screen marker, metres for a ground marker. */
1544
+ size: readonly [number, number];
1545
+ /**
1546
+ * `screen` (the default) faces the viewer at a fixed size in pixels, as a pin does; `ground`
1547
+ * lies flat on the ground at a size in metres, as a ring or an arrow on the street does.
1548
+ */
1549
+ alignment?: 'screen' | 'ground';
1550
+ /** The point of the image that sits on the position: `center` (the default) or `bottom`. */
1551
+ anchor?: 'center' | 'bottom';
1552
+ /** A screen marker's shift in CSS pixels, right and down. */
1553
+ offset?: readonly [number, number];
1554
+ /** Degrees clockwise: from the screen's up for a screen marker, from north for a ground one. */
1555
+ rotation?: number;
1556
+ /** Metres above the ground; defaults to 0. */
1557
+ altitude?: number;
1558
+ /** From 0 to 1 (the default). */
1559
+ opacity?: number;
1560
+ /** Whether nearer 3D content hides the marker; defaults to true. */
1561
+ occlude?: boolean;
1562
+ }>;
1563
+ type TileflowDepthMarkerHandle = {
1564
+ /** Changes the marker; an `image` passed again is uploaded again. */
1565
+ update(change: Partial<TileflowDepthMarker>): void;
1566
+ remove(): void;
1567
+ };
1568
+ type TileflowDepthMarkersOptions = Readonly<{
1569
+ /** The custom layer's id; defaults to `tileflow-depth-markers`. */
1570
+ id?: string;
1571
+ /** The layer the markers are drawn under, or a function that finds it after a style change. */
1572
+ beforeId?: string | (() => string | undefined);
1573
+ }>;
1574
+ type TileflowDepthMarkers = {
1575
+ add(marker: TileflowDepthMarker): TileflowDepthMarkerHandle;
1576
+ /** Removes the markers' layer and releases its GPU resources. */
1577
+ dispose(): void;
1578
+ };
1579
+ /** Where a marker sits: its tile and its position there in tile units, and metres in tile units. */
1580
+ declare function tileflowDepthMarkerPlacement(lngLat: readonly [number, number]): {
1581
+ tile: {
1582
+ x: number;
1583
+ y: number;
1584
+ z: number;
1585
+ };
1586
+ position: [number, number];
1587
+ unitsPerMetre: number;
1588
+ };
1589
+ /**
1590
+ * Draws markers in the map's 3D scene, hidden by nearer 3D buildings. Needs a MapLibre GL JS map
1591
+ * on WebGL 2 (GL JS 5 or later). The layer puts itself back after a style change.
1592
+ */
1593
+ declare function createTileflowDepthMarkers(map: TileflowDepthMarkerMap, options?: TileflowDepthMarkersOptions): TileflowDepthMarkers;
1594
+
1595
+ /** A camera between keyframes: always the center form, with bearing and pitch resolved. */
1596
+ type TileflowShotCamera = {
1597
+ type: 'center';
1598
+ center: [number, number];
1599
+ zoom: number;
1600
+ bearing: number;
1601
+ pitch: number;
1602
+ };
1603
+ type TileflowShotKeyframe = Readonly<{
1604
+ /** Milliseconds from the start: the first keyframe is at 0, later ones rise strictly. */
1605
+ at: number;
1606
+ camera: Readonly<{
1607
+ /** Shots committed on a map name the center camera form; the motion needs no other. */
1608
+ type?: 'center';
1609
+ center: readonly [number, number];
1610
+ zoom: number;
1611
+ bearing?: number;
1612
+ pitch?: number;
1613
+ }>;
1614
+ blend?: Readonly<{
1615
+ themes: readonly string[];
1616
+ position: number;
1617
+ }>;
1618
+ }>;
1619
+ type TileflowShotMotion = Readonly<{
1620
+ keyframes: readonly TileflowShotKeyframe[];
1621
+ /** `smooth` (the default) eases each segment in and out; `linear` does not. */
1622
+ easing?: 'linear' | 'smooth';
1623
+ }>;
1624
+ /** The camera and blend position of a shot at a time. */
1625
+ type TileflowShotState = {
1626
+ at: number;
1627
+ camera: TileflowShotCamera;
1628
+ /** Present when the shot blends themes. */
1629
+ blendPosition?: number;
1630
+ };
1631
+ /**
1632
+ * Where a shot is at `at` milliseconds, clamped to its first and last keyframes. Within each
1633
+ * keyframe segment the center moves in Web Mercator coordinates along the shorter way around the
1634
+ * world, zoom and pitch change linearly, bearing turns along the shorter arc, and the blend position
1635
+ * changes linearly; `easing: 'smooth'` eases each segment in and out. A time on a keyframe shows
1636
+ * that keyframe exactly.
1637
+ */
1638
+ declare function tileflowShotStateAt(shot: TileflowShotMotion, at: number): TileflowShotState;
1639
+
1640
+ /** Structural MapLibre capabilities; importing this module never loads a renderer. */
1641
+ type TileflowShotPlayerMap = {
1642
+ getCanvas?: unknown;
1643
+ jumpTo(camera: {
1644
+ center: [number, number];
1645
+ zoom: number;
1646
+ bearing: number;
1647
+ pitch: number;
1648
+ }): unknown;
1649
+ };
1650
+ /** Something to do once the shot reaches a time, such as drawing a route or showing a title. */
1651
+ type TileflowShotCue = Readonly<{
1652
+ at: number;
1653
+ run: () => void;
1654
+ }>;
1655
+ type TileflowShotPlaybackOptions = Readonly<{
1656
+ /**
1657
+ * Receives the blend position at each frame of a shot that blends themes, to pass on to the
1658
+ * theme controller: `(position) => controller.setBlend({themes, position})`.
1659
+ */
1660
+ blend?: (position: number) => void;
1661
+ /** Run once each, in time order, as the shot reaches them. */
1662
+ cues?: readonly TileflowShotCue[];
1663
+ /** Receives the camera after each frame's move. */
1664
+ onFrame?: (state: {
1665
+ at: number;
1666
+ camera: TileflowShotCamera;
1667
+ blendPosition?: number;
1668
+ }) => void;
1669
+ /** Stops the shot where it is. */
1670
+ signal?: AbortSignal;
1671
+ }>;
1672
+ type TileflowShotPlayback = {
1673
+ /** True when the shot played to its last keyframe; false when it was stopped first. */
1674
+ readonly finished: Promise<boolean>;
1675
+ /** Milliseconds the shot has played. */
1676
+ readonly at: number;
1677
+ /** Stops the shot where it is. */
1678
+ stop(): void;
1679
+ };
1680
+ /**
1681
+ * Plays a timed shot live on a map: the camera follows the shot's keyframes frame by frame, the
1682
+ * blend position goes to `blend`, and cues run as the shot reaches them. It moves as Capture renders
1683
+ * the same shot to video, so the page and the film agree. With reduced motion requested, or without
1684
+ * a browser window, it shows the last keyframe at once and runs every cue in order.
1685
+ */
1686
+ declare function playTileflowShot(map: TileflowShotPlayerMap, shot: TileflowShotMotion, options?: TileflowShotPlaybackOptions): TileflowShotPlayback;
1687
+
833
1688
  declare const tileflowMaplibreContourVersion: "0.1.0";
834
1689
  type TileflowContourProtocolRequest = Readonly<{
835
1690
  url: string;
@@ -940,6 +1795,7 @@ type TileflowThemeBlendState = Readonly<{
940
1795
  themes: readonly string[];
941
1796
  }>;
942
1797
  type TileflowStyleSwitchMap = TileflowThemeMotionMap & TileflowDynamicImageMap & {
1798
+ getCenter?: unknown;
943
1799
  getGlobalState?: unknown;
944
1800
  off(event: string, listener: (event?: unknown) => void): unknown;
945
1801
  on(event: string, listener: (event?: unknown) => void): unknown;
@@ -948,6 +1804,18 @@ type TileflowStyleSwitchMap = TileflowThemeMotionMap & TileflowDynamicImageMap &
948
1804
  };
949
1805
  /** A value an application sets for the whole style, which themes read with `expr.globalState`. */
950
1806
  type TileflowStyleStateValue = boolean | number | string | null;
1807
+ /**
1808
+ * Where an application places the sun. `azimuth` (degrees clockwise from north) and `altitude`
1809
+ * (degrees above the horizon) place it directly; `date` places the real sun of that instant over
1810
+ * `location` ([longitude, latitude]), the map's centre when it is left out.
1811
+ */
1812
+ type TileflowSunRequest = Readonly<{
1813
+ altitude: number;
1814
+ azimuth: number;
1815
+ }> | Readonly<{
1816
+ date: Date | number;
1817
+ location?: readonly [number, number];
1818
+ }>;
951
1819
  type TileflowThemeController = {
952
1820
  dispose(): void;
953
1821
  /** Own a fixed-size RGBA image with a stable name across themes, restored after style reloads. */
@@ -958,8 +1826,21 @@ type TileflowThemeController = {
958
1826
  getCurrent(): TileflowRuntimeStyle;
959
1827
  /** The emphasis requested last, or undefined when the map is shown as designed. */
960
1828
  getEmphasis(): TileflowEmphasis | undefined;
1829
+ /**
1830
+ * The route inks of the theme on screen, for an application's own route layers. During a blend
1831
+ * they are mixed between the neighbouring themes at the blend's position, as the map's colours
1832
+ * are. Read them again after a theme change or a blend move.
1833
+ */
1834
+ getRouteInks(): TileflowRouteInks;
961
1835
  /** The value a style state was set to last, or undefined when it has not been set. */
962
1836
  getState(name: string): TileflowStyleStateValue | undefined;
1837
+ /**
1838
+ * The sun the map shows, for an application's own 3D layers: its direction, the light it and
1839
+ * the sky give, and how dark its shadows fall. It is the theme's sun (`lighting.sun`), mixed
1840
+ * between neighbouring themes during a blend, unless `setSun` placed it. Read it when drawing;
1841
+ * the map redraws whenever it changes.
1842
+ */
1843
+ getSun(): TileflowSun;
963
1844
  /**
964
1845
  * Shows a blend of themes. The first request for a set of themes loads their styles and
965
1846
  * prepares one style that holds all of them; later requests for the same themes only move the
@@ -982,6 +1863,13 @@ type TileflowThemeController = {
982
1863
  * and blends. Needs a MapLibre map with global state (GL JS 5.6 or later).
983
1864
  */
984
1865
  setState(name: string, value: TileflowStyleStateValue, options?: TileflowThemeChangeOptions): Promise<TileflowThemeTransitionResult>;
1866
+ /**
1867
+ * Places the sun by direction or by the real sun of a date and place; `undefined` returns it to
1868
+ * the themes' suns. The themes keep the sun's colours, strengths, and shadow strength, and the
1869
+ * map's light turns to the new direction, anchored to the map. The sun turns the short way round
1870
+ * over the transition; a request that follows an animation, such as a clock, passes none.
1871
+ */
1872
+ setSun(request: TileflowSunRequest | undefined, options?: TileflowThemeChangeOptions): Promise<TileflowThemeTransitionResult>;
985
1873
  setTheme(style: TileflowRuntimeStyle, options?: TileflowThemeChangeOptions): Promise<TileflowThemeTransitionResult>;
986
1874
  };
987
1875
  /**
@@ -1063,4 +1951,4 @@ declare function createTileflowTransformRequest<TRequest extends TileflowTransfo
1063
1951
  worldRequestBridge?: TileflowWorldRequestBridge;
1064
1952
  }): TileflowTransformRequest<TRequest, TResourceType>;
1065
1953
 
1066
- export { type TileflowAtmosphereMap, type TileflowBrowserThemeBlendSelection, type TileflowComposedRequest, type TileflowContourProtocolHandler, type TileflowContourProtocolRegistrationOptions, type TileflowContourProtocolRegistry, type TileflowContourProtocolRequest, type TileflowContourProtocolResponse, type TileflowDynamicImage, type TileflowDynamicImageContext, type TileflowDynamicImageHandle, type TileflowEmphasis, type TileflowEmphasisArea, type TileflowEmphasisModule, type TileflowFairUseNotice, type TileflowFairUseNoticeController, type TileflowFairUseNoticeState, type TileflowFrameScheduler, type TileflowMapLifecycleAttachment, type TileflowMapLifecycleEvent, type TileflowMapLifecycleSubscriber, type TileflowMapReadinessState, type TileflowPmtilesProtocolHandler, type TileflowPmtilesProtocolRegistrationOptions, type TileflowPmtilesProtocolRegistry, type TileflowSessionSender, type TileflowSessionStarter, type TileflowStyleFontLoadOptions, type TileflowStyleStateValue, type TileflowStyleSwitchMap, type TileflowThemeBlendRequest, type TileflowThemeBlendState, type TileflowThemeChangeOptions, type TileflowThemeController, type TileflowThemeTransition, type TileflowThemeTransitionOptions, type TileflowThemeTransitionPhase, type TileflowThemeTransitionResult, type TileflowTransformRequest, type TileflowTransformRequestParameters, type TileflowUserTransformRequest, type TileflowWorldProtocolHandler, type TileflowWorldProtocolRequest, type TileflowWorldProtocolResponse, type TileflowWorldRequestBridge, attachTileflowAtmosphere, attachTileflowFairUseNotice, attachTileflowMapLifecycle, createTileflowSessionStarter, createTileflowThemeController, createTileflowTransformRequest, getTileflowSystemColorScheme, loadTileflowStyleFonts, registerTileflowContourProtocol, registerTileflowPmtilesProtocol, registerTileflowWorldRequestBridge, subscribeTileflowSystemColorScheme, tileflowFairUseNoticeMessage, tileflowLayerDomainMetadataKey, tileflowMaplibreContourVersion, tileflowPmtilesMaximumDirectoryDepth, tileflowPmtilesProtocol, validateTileflowBrowserThemeBlendSelection, validateTileflowEmphasis };
1954
+ export { type TileflowAtmosphereMap, type TileflowBrowserThemeBlendSelection, type TileflowBuildingMesh, type TileflowBuildingMeshOptions, type TileflowBuildings3D, type TileflowBuildings3DChange, 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 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 TileflowUserTransformRequest, type TileflowVectorTileDecodeOptions, type TileflowWorldProtocolHandler, type TileflowWorldProtocolRequest, type TileflowWorldProtocolResponse, type TileflowWorldRequestBridge, attachTileflowAtmosphere, attachTileflowFairUseNotice, attachTileflowMapLifecycle, createTileflowBuildings3D, createTileflowDepthMarkers, createTileflowGroundLayers, createTileflowLineProgress, createTileflowSessionStarter, createTileflowStreetLights, createTileflowThemeController, createTileflowTileReader, createTileflowTransformRequest, decodeTileflowVectorTile, getTileflowSystemColorScheme, loadTileflowStyleFonts, meshTileflowBuildings, mixTileflowRouteInks, mixTileflowSunPresets, placeTileflowStreetLights, playTileflowShot, readTileflowMapTileSource, readTileflowRouteInks, readTileflowSunPreset, registerTileflowContourProtocol, registerTileflowPmtilesProtocol, registerTileflowWorldRequestBridge, resolveTileflowSun, subscribeTileflowSystemColorScheme, tileflowBuildingExtent, tileflowBuildingVertexBytes, tileflowBuildings3DLayerId, tileflowDefaultRouteInks, tileflowDefaultSunPreset, tileflowDepthMarkerPlacement, tileflowFairUseNoticeMessage, tileflowGroundBeforeId, tileflowLayerDomainMetadataKey, tileflowLineProgressGradient, tileflowMaplibreContourVersion, tileflowPmtilesMaximumDirectoryDepth, tileflowPmtilesProtocol, tileflowRouteMetadataKey, tileflowShotStateAt, tileflowStreetLightBytes, tileflowStreetLightsLayerId, tileflowStyleRouteInks, tileflowStyleSunPreset, tileflowSunDirection, tileflowSunLightMatrix, tileflowSunMetadataKey, tileflowSunPosition, tileflowTilePointToLngLat, tileflowTilesForBounds, validateTileflowBrowserThemeBlendSelection, validateTileflowEmphasis };