@faclon-labs/app-sdk 0.1.0 → 0.3.0

package/vendor/map-engine/maplibre/renderer.d.ts

@@ -0,0 +1,173 @@
+import type { BasemapConfig, MapConfig, MapViewport, RendererCapabilities, TerrainConfig, Position, ScenePatch, SceneState, Size, Unsubscribe } from '../core/types.js';
+import type { MapClickEvent, PickEvent, Renderer, RendererOptions } from '../render/renderer.js';
+import type { MapLibreModuleLike } from './map-like.js';
+import { type DeckModules } from './deck-host.js';
+import { type RendererTheme } from './style.js';
+export interface MapLibreRendererOptions {
+    /** Inject the module (tests, or apps that already loaded it). Default: lazy `import('maplibre-gl')`. */
+    maplibre?: MapLibreModuleLike;
+    theme?: Partial<RendererTheme>;
+    /** Pixels around the pointer that count as a hit. Default 4. */
+    hitTolerance?: number;
+    /** Reject initialize() if the style has not loaded by then. Default 15 s. */
+    loadTimeoutMs?: number;
+    /**
+     * URL of `maplibre-gl-worker.mjs` (MapLibre v6). Needed when a bundler separates the module from its worker
+     * (for example Vite pre-bundling). With Vite: `import workerUrl from 'maplibre-gl/dist/maplibre-gl-worker.mjs?url'`.
+     */
+    workerUrl?: string;
+    /** Extra MapLibre Map options (controls, interaction). Engine-owned keys win. */
+    mapOptions?: Record<string, unknown>;
+    /**
+     * After the first objects are written, how long their data may take to load before the renderer reports that
+     * MapLibre's web worker is probably not wired (the map would otherwise stay silently empty). Default 8000 ms.
+     */
+    workerCheckMs?: number;
+    /** deck.gl for 3D layers (phase 3C). Default: lazy-loaded the first time a map has such a layer. Tests inject a fake. */
+    deck?: DeckModules;
+    /** Fetch used to read a style-URL basemap (so the label font can be added to it). Default: global fetch. */
+    fetch?: (url: string) => Promise<{
+        ok: boolean;
+        status: number;
+        json(): Promise<unknown>;
+    }>;
+    /** Reads one DEM tile's pixels for sampleElevation. Default: fetch + decode in the browser. Tests inject one. */
+    loadDemTile?: (url: string) => Promise<{
+        rgba: Uint8ClampedArray | Uint8Array;
+        size: number;
+    } | undefined>;
+}
+type Listener<T> = (value: T) => void;
+export declare class MapLibreRenderer implements Renderer {
+    private readonly options;
+    /**
+     * Globe, terrain and ground heights (3B); heights and models through deck.gl, extrusions natively (3C).
+     * Known limit: with MapLibre v6 and deck.gl 9.4, deck.gl layers do not draw in the globe projection — so in globe
+     * mode heights and models are not claimed (the runtime reports the gap) and those layers are drawn flat by
+     * MapLibre instead of disappearing. A full 3D globe is the Cesium renderer's job (phase 3D).
+     */
+    get capabilities(): RendererCapabilities;
+    /** The layers last given by the scene (before any globe-mode flattening). */
+    private sceneLayers;
+    /** deck.gl host for layers at a height and models (created with the map, loads deck.gl on first use). */
+    private deckHost;
+    private fontName;
+    private groundRefresh;
+    private projection;
+    private terrain;
+    private dem;
+    private map;
+    private lib;
+    private offline;
+    /** Image layers: per layer, per object, the image source drawn (doc 28 G12). */
+    private readonly images;
+    /** Contour tiles from the terrain's DEM (doc 28 G11), created on first use. */
+    private contourDem;
+    private readonly theme;
+    private readonly layers;
+    private readonly features;
+    private readonly mapHandlers;
+    private hoverKey;
+    private hasFont;
+    private warnedNoFont;
+    /** Bumped by destroy(): an initialize() or setBasemap() that started before it is stale. */
+    private gen;
+    /** Rejects the style load being waited for (destroy() during initialize or a basemap swap). */
+    private cancelWait;
+    /** The one-off check that engine data really reached MapLibre's worker (see workerCheckMs). */
+    private workerCheck;
+    private workerChecked;
+    private readonly listeners;
+    constructor(options?: MapLibreRendererOptions);
+    initialize(container: HTMLElement, options: RendererOptions): Promise<void>;
+    setProjection(projection: NonNullable<MapConfig['projection']>): void;
+    /**
+     * The layer as this renderer can draw it now: in globe mode, layers at a height and models are drawn flat by
+     * MapLibre (see `capabilities`), so their objects stay visible.
+     */
+    private drawable;
+    setTerrain(terrain: TerrainConfig | null): void;
+    /** pmtiles:// archives (offline tile packs, doc 28 G14): the protocol is loaded the first time a URL uses it. */
+    private ensurePmtiles;
+    /**
+     * Ground heights from the terrain the map shows. MapLibre answers only where terrain tiles are loaded (null
+     * elsewhere) and multiplies by the exaggeration; the engine reports true metres, so that is divided out.
+     */
+    /**
+     * True heights from the DEM tiles, decoded by the engine. Not MapLibre's queryTerrainElevation: it answers 0 (sea
+     * level, not "unknown") wherever the view has no tile loaded, so a line of sight off screen came out flat.
+     */
+    sampleElevation(positions: Position[]): Promise<Array<number | null>>;
+    /**
+     * Projection, terrain (3D surface + hillshade) and sky — the map's environment, under every engine layer.
+     * Applied after load and again after a basemap swap (a new style drops them).
+     */
+    private applyEnvironment;
+    /** Contour lines from the terrain's DEM tiles (doc 28 G11), under every engine layer; removed when off. */
+    private applyContours;
+    /** The first engine style layer in draw order, so environment layers can go beneath it. */
+    private firstEngineLayer;
+    /**
+     * A style swap (MapLibre setStyle): the camera, canvas and GPU context stay. Every engine source and layer goes
+     * with the old style, so the caller renders the full scene again afterwards (Renderer contract).
+     */
+    setBasemap(basemap: BasemapConfig): Promise<void>;
+    /** The style for a basemap. A street-map style brings its own glyph server; engine labels use the app font, so it is added. */
+    private resolveStyle;
+    /** Waits for a style to load ('load' first time, 'style.load' after a swap); destroy() cancels the wait. */
+    private waitFor;
+    setViewport(viewport: MapViewport, options?: {
+        animate?: boolean;
+    }): void;
+    render(scene: SceneState): void;
+    update(patch: ScenePatch): void;
+    resize(): void;
+    project(position: Position): {
+        x: number;
+        y: number;
+    } | null;
+    onCameraMove(l: () => void): Unsubscribe;
+    getSize(): Size;
+    destroy(): void;
+    onViewportChange(l: Listener<MapViewport>): Unsubscribe;
+    onPick(l: Listener<PickEvent>): Unsubscribe;
+    onMapClick(l: Listener<MapClickEvent>): Unsubscribe;
+    onHover(l: Listener<PickEvent | null>): Unsubscribe;
+    onError(l: Listener<Error>): Unsubscribe;
+    /** Adds, removes, restyles, shows/hides and reorders engine layers. Basemap layers are never touched. */
+    private applyLayers;
+    private imageId;
+    private imageLayerIds;
+    /** One image source and raster layer per object, placed by its corners; follows moves, image changes and removal. */
+    private syncImages;
+    private dropImages;
+    /** Registers the icon images a layer uses (built-in shapes synchronously, URLs when they load). */
+    private ensureImages;
+    private removeEngineLayer;
+    private applyObjects;
+    /**
+     * Hands deck.gl the layers it draws; a layer that moves back to MapLibre (its height removed) gets its features
+     * written to its source again, since they were not kept there while deck.gl drew it.
+     */
+    private syncDeck;
+    /** The shape, plus for labelled areas its one label point (an area is labelled once, not once per map tile). */
+    private featuresOf;
+    private feature;
+    /**
+     * MapLibre's v6 module needs its worker bundled by the app; without it nothing errors, the map just stays empty.
+     * Once, after the first objects are written, check that their source finished loading — and name the fix if not.
+     */
+    private watchWorker;
+    private writeSource;
+    private source;
+    private bindMapEvents;
+    private setHover;
+    /** Top-most engine feature under the pointer: an object (stable objectId) or a cluster bubble. Heatmaps are not pickable. */
+    private hitTest;
+    /** A click on a cluster bubble zooms to where it splits; the camera move then reaches the engine as usual. */
+    private zoomIntoCluster;
+    private currentViewport;
+    private emitError;
+    private add;
+}
+export {};