@navaramap/three 0.0.4 → 0.0.5

package/dist/index.d.ts

@@ -28,7 +28,6 @@ import { FontManager } from '@navaramap/font';
 import { FontWorkerMemoryStats } from '@navaramap/font';
 import { Geometry } from 'geojson';
 import { Group } from 'three';
-import { InstancedBufferGeometry } from 'three';
 import { InstancedMesh as InstancedMesh_2 } from 'three';
 import { Light as Light_2 } from 'three';
 import { Line2 } from 'three-stdlib';
@@ -59,6 +58,7 @@ import { Scene } from 'three';
 import { ShaderLibShader } from 'three';
 import { ShaderMaterial } from 'three';
 import { ShapedGlyph } from '@navaramap/font';
+import { ShapeTextResult } from '@navaramap/font';
 import { Sprite } from 'three';
 import { Texture } from 'three';
 import { TextureEventMap } from 'three';
@@ -141,10 +141,11 @@ export declare class Atmosphere extends EventHandler<AtmosphereEvents> {
      */
     private rotationMatrix;
     /**
-     * Precomputed atmosphere textures used for rendering.
-     * Loaded asynchronously via {@link initTextures}.
+     * Precomputed atmosphere textures used for rendering. Each texture is
+     * loaded lazily when a consumer declares a need for it via
+     * {@link onTexturesReady}, so the object may hold any subset at a time.
      */
-    textures?: PrecomputedTextures;
+    textures: Partial<PrecomputedTextures>;
     overlay: Observed<AtmosphereOverlay | null>;
     shadow: Observed<AtmosphereShadow | null>;
     shadowLength: Observed<AtmosphereShadowLength | null>;
@@ -162,11 +163,11 @@ export declare class Atmosphere extends EventHandler<AtmosphereEvents> {
      */
     private _camera;
     /**
-     * In-flight texture loading promise, shared across concurrent
-     * {@link initTextures} calls so the assets are fetched only once.
+     * In-flight per-texture loading promises, shared across consumers so each
+     * asset is fetched only once.
      * @private
      */
-    private texturesPromise;
+    private texturePromises;
     /**
      * Creates a new Atmosphere instance.
      * @param renderer - The WebGL renderer used for texture type detection.
@@ -180,24 +181,45 @@ export declare class Atmosphere extends EventHandler<AtmosphereEvents> {
      */
     onUpdate: () => void;
     /**
-     * Loads precomputed atmosphere textures asynchronously.
-     * If textures are already loaded, this method returns immediately.
-     * @returns A promise that resolves when textures are loaded.
+     * Loads all precomputed atmosphere textures asynchronously.
+     *
+     * Each texture loads automatically once a consumer declares a need for it
+     * via {@link onTexturesReady}; call this manually only to prefetch every
+     * texture ahead of time.
+     *
+     * @returns A promise that resolves when all textures are loaded.
      */
     initTextures(): Promise<void>;
     /**
+     * Loads a single precomputed texture, sharing in-flight loads and caching
+     * the result. A failed load is forgotten so the next request retries it.
      * @private
      */
-    _init(): Promise<void>;
+    private loadTexture;
+    private fetchTexture;
     /**
      * @private
      */
     _dispose(): void;
     /**
-     * Invokes the callback with precomputed textures immediately if already loaded,
-     * or registers a one-time listener to invoke it once textures are ready.
+     * Invokes the callback once every needed precomputed texture is loaded —
+     * immediately if they already are.
+     *
+     * Registering also starts loading the needed textures if they aren't loaded
+     * yet, so a texture is only fetched once something that needs it exists.
+     *
+     * @param callback - Receives the textures; the ones listed in `needs` are
+     * guaranteed to be present.
+     * @param needs - The textures the caller needs, e.g.
+     * `{ transmittance: true }`. Omit to load all of them.
+     *
+     * @example
+     * atmosphere.onTexturesReady(
+     *   (t) => light.setTransmittanceTexture(t.transmittanceTexture),
+     *   { transmittance: true },
+     * );
      */
-    onTexturesReady(callback: (textures: PrecomputedTextures) => void): void;
+    onTexturesReady<N extends AtmosphereTextureNeeds = Record<AtmosphereTextureName, true>>(callback: (textures: LoadedAtmosphereTextures<N>) => void, needs?: N): void;
     /**
      * Returns a clone of the current sun direction vector.
      * @returns A new Vector3 representing the sun direction in ECEF coordinates.
@@ -346,7 +368,22 @@ export declare class Atmosphere extends EventHandler<AtmosphereEvents> {
     }): void;
 }
 
-export declare const ATMOSPHERE_ASSETS_URL: string;
+export declare const ATMOSPHERE_HIGHER_ORDER_SCATTERING_URL: string;
+
+export declare const ATMOSPHERE_IRRADIANCE_URL: string;
+
+export declare const ATMOSPHERE_SCATTERING_URL: string;
+
+export declare const ATMOSPHERE_SINGLE_MIE_SCATTERING_URL: string;
+
+/**
+ * Filenames requested by `PrecomputedTexturesLoader` mapped to their
+ * statically-resolved URLs. Used to remap directory-relative requests when
+ * loading the bundled default atmosphere assets.
+ */
+export declare const ATMOSPHERE_TEXTURE_URLS: Record<string, string>;
+
+export declare const ATMOSPHERE_TRANSMITTANCE_URL: string;
 
 /**
  * Events emitted by the {@link Atmosphere} class.
@@ -354,7 +391,7 @@ export declare const ATMOSPHERE_ASSETS_URL: string;
 declare type AtmosphereEvents = {
     /** Emitted when the atmosphere needs to trigger a re-render. */
     needsUpdate: () => void;
-    /** Emitted when precomputed atmosphere textures have been loaded. */
+    /** Emitted each time a precomputed atmosphere texture finishes loading. */
     textureLoaded: () => void;
     /** Emitted when the atmosphere is disposed. */
     disposed: () => void;
@@ -366,14 +403,31 @@ declare type AtmosphereEvents = {
  * Configuration options for the {@link Atmosphere} class.
  */
 export declare type AtmosphereOptions = {
-    /** URL to load precomputed atmosphere textures from. */
-    atmosphereAssetsUrl?: string;
+    /**
+     * URL of a directory to load precomputed atmosphere textures from. The
+     * directory must keep the original filenames (`transmittance.exr` etc.).
+     * When omitted, the assets bundled with the package are used.
+     */
+    atmosphereAssetsUrl?: string | undefined;
     /** URL to load STBN (Spatio-Temporal Blue Noise) textures from. */
     stbnUrl?: string;
     /** Date used for calculating sun/moon positions. Defaults to current date. */
     date?: Date;
 };
 
+/**
+ * Names of the precomputed atmosphere textures that can be loaded
+ * individually.
+ */
+declare type AtmosphereTextureName = "transmittance" | "scattering" | "irradiance" | "higherOrderScattering";
+
+/**
+ * Which precomputed textures a consumer needs, e.g.
+ * `{ transmittance: true }`. Only `true` is allowed as a value so that every
+ * listed texture is guaranteed to be loaded.
+ */
+declare type AtmosphereTextureNeeds = Partial<Record<AtmosphereTextureName, true>>;
+
 declare type Attributes = BatchedFeatureAttributes<{
     position?: BufferAttribute;
     position_3d_high?: BufferAttribute;
@@ -897,13 +951,30 @@ export declare class BatchedFeatureMesh<Buf extends BufferGeometry<BatchedFeatur
     clone(): this;
 }
 
-export declare class BatchedSdfTextMesh extends InstancedMesh<SDFTextMesh> implements PickableMesh, DeclutterParticipant {
+/**
+ * Every text label in a tile-layer, drawn in a single call.
+ *
+ * Instances are glyphs, not labels: each label owns a contiguous run of glyph
+ * slots ({@link GlyphSlotAllocator}) and one row block in a float texture
+ * ({@link LabelDataTexture}) that the vertex shader reads through the
+ * `labelIndex` attribute. A label changing its text rewrites only its own run
+ * — and not even that when the new glyph count stays inside the run's
+ * power-of-two size class.
+ *
+ * Still extends {@link InstancedMesh} because `FeatureEvaluator` dispatches
+ * per-feature styling on `instanceof InstancedMesh`; the inherited child-mesh
+ * machinery (`allMeshes`, `markVisibility`) is deliberately unused.
+ */
+export declare class BatchedSdfTextMesh extends InstancedMesh<Object3D> implements PickableMesh, DeclutterParticipant {
+    /**
+     * Geometry type of this mesh.
+     */
+    readonly geometryType: "text";
     readonly ctx: EventContext;
     /** The font identifier from material — may be a family name or a URL. */
     private _fontIdentifier;
-    /** Per-batch text quality. All instanced meshes in this batch share it
-     *  because they all sample the same atlas texture; flipping quality requires
-     *  a new BatchedSdfTextMesh. */
+    /** Per-batch text quality. All labels in the batch share it because they
+     *  sample the same atlas texture; flipping quality requires a new batch. */
     private _highQuality;
     private _fontManager;
     private _needRender?;
@@ -915,16 +986,86 @@ export declare class BatchedSdfTextMesh extends InstancedMesh<SDFTextMesh> imple
      * and must be balanced with unloadFont() on dispose or font change.
      */
     private _loadedFaceUrls;
-    /** Geometry-extracted anchor data; per-index meshes slice it lazily. */
     private _positions;
-    /** Sparse batchIndex → mesh; `allMeshes` holds only created meshes. */
-    private _meshByIndex;
-    /** Evaluator state received before a feature's mesh exists. */
-    private _pending;
-    /** Material/transform used when creating meshes lazily. */
     private _material;
     private _transform;
+    /** Labels in slot order — `_labels[slot]` is also the declutter handle map. */
+    private _labels;
+    /** Sparse batchIndex → label; labels are created on first per-feature touch. */
+    private _labelByIndex;
+    private _glyphs;
+    private _slots;
+    private _labelData;
+    /** Layout inputs baked into glyph quads; a change forces a re-layout. */
+    private _maxWidth;
+    private _lineHeight;
+    private _textAlign;
+    /** Layer-level declutter settings, mirrored from the material. */
+    private _declutter;
+    private _declutterPriority;
+    /** Skips the per-frame fade walk entirely once everything has settled. */
+    private _declutterAnimating;
+    private _enhancer;
     constructor(ctx: EventContext, m: TextMesh, fontIdentifier: string, options: InstancedMeshOptions, loadedFaceUrls?: Set<string>);
+    get fontIdentifier(): string;
+    get highQuality(): boolean;
+    /** Mount the enhancer and install the batch's single per-frame hook. */
+    private _setupMaterial;
+    /** Re-point the shader at the label texture (it is swapped on grow). */
+    private _syncLabelDataUniform;
+    /**
+     * A material-level text renders without the evaluator ever setting text, so
+     * that case needs a label per anchor up front. With per-feature texts (MVT)
+     * most features never receive one, so labels are otherwise created lazily on
+     * the first per-feature setter — a label slot is just an index plus a few
+     * float writes, unlike the mesh-per-label this replaced.
+     */
+    private _initLabels;
+    private _ensureLabel;
+    private _writeAnchor;
+    private _writeStyle;
+    private _writeBox;
+    private _writeState;
+    private _writeFontSize;
+    private _writeAddHeight;
+    private _writeShow;
+    private _writeDeclutterHide;
+    private _layoutOptions;
+    /**
+     * Shape `text`, lay it out, and write the label's glyph run. Assumes the
+     * text is already prepared in the font worker.
+     */
+    private _applyText;
+    /** Return a label's glyph slots and blank them. */
+    private _releaseRun;
+    /** Replace the retained glyph set, releasing the old references and (if
+     *  shown) retaining the new ones. */
+    private _setGlyphKeys;
+    /**
+     * Reconcile atlas references with visibility: retain glyphs while the label
+     * is shown, release them when hidden. If shown after the glyphs were evicted
+     * (cache no longer prepared), re-prepare to re-rasterize them and rebuild
+     * with fresh metrics.
+     */
+    private _syncGlyphRefs;
+    /**
+     * Fold `requestedShow` and "has text" into the effective visibility, pushing
+     * it to the shader and reconciling atlas retains when it flips.
+     */
+    private _recomputeShow;
+    /**
+     * After an atlas eviction, re-lay-out any shown label whose text is now
+     * stale (its pinned glyphs may have been evicted before the retain landed
+     * and its rect reused). Fresh labels short-circuit on the cheap
+     * `isTextPrepared` check, so this is inexpensive to run per eviction.
+     */
+    private _revalidateStaleLabels;
+    private _refreshAtlasTextures;
+    /**
+     * Build each shown label's collision box. The local box mirrors the vertex
+     * shader's layout: glyphs span [0, textWidth] x [bgMinY, bgMaxY] in em
+     * units, shifted by the `center` anchor and scaled by the font size.
+     */
     collectDeclutterCandidates(out: DeclutterCandidate[]): void;
     applyDeclutter(handle: number, hidden: boolean): void;
     stepDeclutterFade(deltaMs: number): boolean;
@@ -932,58 +1073,25 @@ export declare class BatchedSdfTextMesh extends InstancedMesh<SDFTextMesh> imple
      *  declutter pass to re-place on its next update. */
     private _markDeclutterDirty;
     setActive(active: boolean): void;
-    /**
-     * After an atlas eviction, re-prepare and force-rebuild any visible mesh whose
-     * shaped text is now stale (its pinned glyphs may have been evicted before the
-     * retain landed and its rect reused). Fresh meshes short-circuit on the cheap
-     * `isTextPrepared` check, so this is inexpensive to run per eviction.
-     */
-    private _revalidateStaleMeshes;
-    get fontIdentifier(): string;
-    get highQuality(): boolean;
-    /**
-     * A mesh per anchor is expensive (geometry + ShaderMaterial + enhancer
-     * mount), and with per-feature texts (MVT) most features never receive a
-     * non-empty text — they'd sit invisible while still costing construction and
-     * every per-frame loop. So meshes are created lazily by `_ensureMeshAt` on
-     * the first non-empty `setTextByBatchIndex`. Only a non-empty material-level
-     * default text (single-label sources) renders without the evaluator ever
-     * setting text, so only that case creates all meshes eagerly.
-     */
-    private initMeshes;
-    /** The font-level shared atlas textures for this batch's font+quality (the
-     *  color atlas is `null` for monochrome fonts). */
-    private _sharedTextures;
-    /**
-     * The feature's mesh, created on first need (see `initMeshes`). `shared`
-     * lets a batch creation pass hoist the atlas lookups; when omitted (a single
-     * lazy creation) they are fetched here, since the atlas may have been
-     * (re)allocated since this batch was constructed.
-     */
-    private _ensureMeshAt;
-    /** Pending-state slot for a feature whose mesh doesn't exist yet. */
-    private _pendingAt;
-    _update(m: TextMesh, needRender?: () => void): Promise<void>;
-    private _applyUpdate;
     onBeforePicking(): void;
     onAfterPicking(): void;
+    getRenderable(): Object3D;
     private extractPositions;
+    _update(m: TextMesh, needRender?: () => void): Promise<void>;
+    private _applyUpdate;
     setTextByBatchIndex(batchIndex: number, text: string): void;
-    /**
-     * The mesh for a feature's `batchIndex`, or `undefined` if not created yet.
-     * Meshes are created lazily and pushed onto `allMeshes` in creation order, so
-     * `allMeshes[batchIndex]` (the base-class mapping) does NOT hold here; the
-     * batchIndex→mesh mapping lives in `_meshByIndex`. Overriding this one
-     * accessor keeps the base-class setters and any external caller (picking,
-     * plugins) correct without patching each call site.
-     */
-    getMeshByBatchIndex(batchIndex: number): SDFTextMesh | undefined;
     setFeatureColorByBatchIndex(batchIndex: number, color: Color_3): void;
     setFeatureShowByBatchIndex(batchIndex: number, rawVisible: boolean): void;
     setFeatureHeightByBatchIndex(batchIndex: number, height: number): void;
     setFeatureSizeByBatchIndex(batchIndex: number, size: number): void;
-    setFeatureDeclutterPriorityByBatchIndex(batchIndex: number, priority: number): void;
     setFeatureOpacityByBatchIndex(batchIndex: number, opacity: number): void;
+    setFeatureDeclutterPriorityByBatchIndex(batchIndex: number, priority: number): void;
+    /**
+     * Labels are no longer three.js objects, so there is no child mesh to hand
+     * back. Overridden to stop the base class returning an unrelated object from
+     * its (unused) `allMeshes` array.
+     */
+    getMeshByBatchIndex(): undefined;
     dispose(): void;
 }
 
@@ -1153,7 +1261,6 @@ declare class BoundingSphere {
  * the sentence start and lines stack top-to-bottom in reading order, then
  * every line is flipped back to visual order for rendering. Mixed-direction
  * lines may still break sub-optimally — same trade other map renderers make.
- * Exported for tests.
  */
 export declare function breakLines(glyphs: ShapedGlyph[], maxWidthFu: number, rtl?: boolean): ShapedGlyph[][];
 
@@ -1204,6 +1311,18 @@ export declare class BufferView {
     dispose(): void;
 }
 
+/**
+ * Turn a shaping result into positioned glyph quads.
+ *
+ * Lines lay out top-down: line 0 keeps its baseline at y=0, later baselines
+ * step down by the line height, and alignment shifts each line within the
+ * widest line's width. Each glyph carries its own normalization scale so SDF
+ * and colour glyphs share one em-space coordinate system downstream — the two
+ * paths rasterize at different sizes (`SDF_PX_SIZE` vs `COLOR_GLYPH_PX_SIZE`)
+ * but both end up in ems after dividing by their respective pixel size.
+ */
+export declare function buildLabelLayout(shapeResult: ShapeTextResult, options: LayoutOptions): LabelLayout;
+
 export declare type BuiltInEffectDescription = FinalCopyPassConfig | MRTPassConfig | SkyEnvMapPassConfig | TransparentPassConfig;
 
 declare class CachedMeshHandle {
@@ -1485,7 +1604,13 @@ declare class Cesium3dTilesLayerDescription {
     set type(value: string | null | undefined);
 }
 
-export declare const CLOUD_ASSETS_URL: string;
+export declare const CLOUD_LOCAL_WEATHER_URL: string;
+
+export declare const CLOUD_SHAPE_DETAIL_URL: string;
+
+export declare const CLOUD_SHAPE_URL: string;
+
+export declare const CLOUD_TURBULENCE_URL: string;
 
 /**
  * Class representing a color.
@@ -2388,7 +2513,7 @@ declare type DeclutterCandidate = {
     isShown: boolean;
     /** Participant that owns this candidate; receives the placement result. */
     owner: DeclutterParticipant;
-    /** Participant-defined id (mesh index for text batches, instance index for
+    /** Participant-defined id (label slot for text batches, instance index for
      *  sprites) passed back to `applyDeclutter`. */
     handle: number;
 };
@@ -3383,6 +3508,21 @@ export declare class FeatureEvaluator {
      */
     private obj;
     constructor(handler: FeatureHandler, layerId: LayerId, featureSetId: FeatureSetId, obj: Object3D);
+    /**
+     * Track objects we've already warned about to avoid log spam.
+     * Uses WeakSet so objects can be garbage collected.
+     */
+    private static readonly warnedObjects;
+    /**
+     * Type guard to check if an Object3D has a geometryType getter.
+     */
+    private hasGeometryType;
+    /**
+     * Determine geometry type from the mesh object.
+     * Reads geometryType getter if available on the mesh.
+     * Validates that the returned value is a valid GeometryType literal.
+     */
+    private determineGeometryType;
     /**
      * Gets the unique identifier of this feature set.
      */
@@ -3509,6 +3649,8 @@ export declare type FeatureInfo = {
     batchId: number;
     properties: Record<string, unknown> | undefined;
     layerId: LayerId | undefined;
+    /** Mesh geometry type (e.g., "billboard", "text"). Not GeoJSON geometry ("Point", "Polygon"). */
+    meshGeomType?: GeometryType;
 };
 
 export declare class FeatureMesh {
@@ -3686,6 +3828,24 @@ declare class GeoJsonSourceDescription {
     set url(value: string | null | undefined);
 }
 
+/**
+ * Geometry type constants for mesh objects.
+ * These types are used for feature evaluation and runtime validation.
+ */
+export declare const GEOMETRY_TYPES: {
+    readonly Billboard: "billboard";
+    readonly Text: "text";
+    readonly Point: "point";
+    readonly Polyline: "polyline";
+    readonly Polygon: "polygon";
+    readonly Model: "model";
+};
+
+/**
+ * Type representing a valid geometry type value.
+ */
+export declare type GeometryType = (typeof GEOMETRY_TYPES)[keyof typeof GEOMETRY_TYPES];
+
 export declare function getBatchDataTexture(material: Material): DataTexture | undefined;
 
 /**
@@ -3903,6 +4063,33 @@ declare type GlobeOptions = Partial<Omit<Globe_2, "constructor" | "free" | "elev
     color?: Color_2;
 };
 
+/** Per-instance `glyphKind` values. Must match the `GLYPH_KIND_*` defines in
+ *  `shaders/glsl/sdfText.vert.glsl`. */
+export declare const GlyphKind: {
+    readonly SDF: 0;
+    readonly COLOR: 1;
+    readonly BACKGROUND: 2;
+    /** A slot inside a label's run that its text doesn't use, or a hole left by
+     *  a freed run. Culled in the vertex shader. */
+    readonly EMPTY: 3;
+};
+
+/** One positioned glyph quad in em space, ready to become an instance. */
+export declare type GlyphQuad = {
+    offsetEmX: number;
+    offsetEmY: number;
+    sizeEmX: number;
+    sizeEmY: number;
+    /** Atlas sub-rect in PIXEL space; the shader divides by the live atlas size
+     *  uniform so an atlas resize doesn't invalidate the instance data. */
+    uvL: number;
+    uvT: number;
+    uvR: number;
+    uvB: number;
+    /** Sample the COLRv1 colour atlas rather than the SDF atlas. */
+    isColor: boolean;
+};
+
 /**
  * Events emitted by handles.
  */
@@ -4352,6 +4539,7 @@ export declare type InstancedSpriteMaterialProps = {
 };
 
 export declare class InstancedSpriteMesh extends Mesh_2<BufferGeometry, Material | Material[], CustomObject3DEventMap> implements PickableMesh, DeclutterParticipant {
+    private _geometryType;
     private _batchIdToInstance;
     private _initialColor;
     private _initialHeight;
@@ -4392,6 +4580,23 @@ export declare class InstancedSpriteMesh extends Mesh_2<BufferGeometry, Material
     private _declutterAnimating;
     constructor(options: InstancedSpriteOptions);
     setActive(active: boolean): void;
+    /**
+     * Set the geometry type for this mesh.
+     *
+     * This affects how FeatureEvaluator provides meshGeomType to evaluators,
+     * which is used by MapLibreStylePlugin to determine which properties to apply
+     * (e.g., billboard vs text rendering for symbol layers).
+     *
+     * Changing this after initialization is supported and will affect subsequent
+     * feature evaluations, but does NOT automatically trigger re-evaluation.
+     * Call layer.forceUpdate() if you need to re-evaluate existing features.
+     */
+    setGeometryType(type: SpriteGeometryType): void;
+    /**
+     * Get the geometry type of this mesh.
+     * Defaults to GEOMETRY_TYPES.Point if not explicitly set.
+     */
+    get geometryType(): SpriteGeometryType;
     collectDeclutterCandidates(out: DeclutterCandidate[]): void;
     applyDeclutter(handle: number, hidden: boolean): void;
     stepDeclutterFade(deltaMs: number): boolean;
@@ -4468,6 +4673,7 @@ export declare class InstancedSpriteMesh extends Mesh_2<BufferGeometry, Material
 export declare type InstancedSpriteOptions = {
     renderOrder?: number;
     ctx: EventContext;
+    geometryType: SpriteGeometryType;
 };
 
 /** Type guard distinguishing a raw HTML credit from a structured source. */
@@ -4479,7 +4685,7 @@ export declare const isPickableMesh: (v: object) => v is PickableMesh;
 
 /** Paragraph direction from the first strong directional character (UAX #9
  *  P2/P3 approximation): the first letter decides, RTL ranges win over other
- *  letters. Exported for tests. */
+ *  letters. */
 export declare function isRtlText(text: string): boolean;
 
 export declare const JAPAN_GSI_ELEVATION_DECODER: () => ElevationDecoder;
@@ -4490,6 +4696,19 @@ declare type JsEvents = {
 
 declare type JsEventsKey = keyof JsEvents;
 
+/** A laid-out label: its glyph quads plus the block metrics the shader and the
+ *  declutter pass need. All measurements are in ems. */
+export declare type LabelLayout = {
+    quads: GlyphQuad[];
+    /** Unique atlas glyphs referenced, for retain/release against the atlas. */
+    glyphKeys: bigint[];
+    widthEm: number;
+    heightEm: number;
+    /** Y bounds of the actual rendered glyph bboxes, for the background quad. */
+    minYEm: number;
+    maxYEm: number;
+};
+
 export declare type LatLng = Omit<LatLngHeight, "height">;
 
 export declare type LatLngHeight = Required<NormalizeWASMClass<LLE>>;
@@ -4591,6 +4810,17 @@ declare class LayersManager {
     getEffectDescs(): Generator<EffectHandle>;
 }
 
+declare type LayoutOptions = {
+    /** The source string — only used to detect paragraph direction. */
+    text: string;
+    /** Wrap width in ems (multiples of font size); 0 disables soft wrapping. */
+    maxWidth: number;
+    /** Multiplier on the font's natural line height. */
+    lineHeight: number;
+    /** 0 left, 0.5 center, 1 right. */
+    textAlign: number;
+};
+
 declare class LegacyElevationHeatmapMaterial {
     private constructor();
     free(): void;
@@ -4943,7 +5173,7 @@ export declare class LightHandle<T extends LightDesc = LightDesc> extends BaseHa
 export declare type LightUpdate = Pick<LightConfig, "position"> & BaseDescConfigUpdate;
 
 /** Line width in font units: advances summed, trailing whitespace ignored so
- *  it never affects alignment or the block width. Exported for tests. */
+ *  it never affects alignment or the block width. */
 export declare function lineWidthFu(line: ShapedGlyph[]): number;
 
 declare class LLE {
@@ -4955,6 +5185,12 @@ declare class LLE {
     lng: number;
 }
 
+/**
+ * The textures guaranteed to be present in an {@link Atmosphere.onTexturesReady}
+ * callback for a given needs declaration.
+ */
+declare type LoadedAtmosphereTextures<N extends AtmosphereTextureNeeds> = Required<Pick<PrecomputedTextures, `${Extract<keyof N, AtmosphereTextureName>}Texture`>>;
+
 /**
  * LOD fog settings: a distance-based screen-space-error relaxation used by
  * the tile traversals (far tiles tolerate a larger error and stay coarser,
@@ -5581,8 +5817,6 @@ declare class ModelMaterial_2 {
     set applyWaterNormal(value: boolean | null | undefined);
     get castShadow(): boolean | undefined;
     set castShadow(value: boolean | null | undefined);
-    get clampToGround(): boolean | undefined;
-    set clampToGround(value: boolean | null | undefined);
     get color(): number | undefined;
     set color(value: number | null | undefined);
     /**
@@ -5754,6 +5988,10 @@ export declare class ModelMesh extends Object3D<CustomObject3DEventMap> implemen
         scene: Group;
         credit?: string;
     }, m: ModelMesh_2);
+    /**
+     * Geometry type of this mesh.
+     */
+    readonly geometryType: "model";
     get water(): boolean;
     set water(v: boolean);
     private init;
@@ -5972,8 +6210,6 @@ declare class MvtLayerDescription {
     set vectorTile(value: LegacyVectorTileMaterial | null | undefined);
 }
 
-export declare const NOISE_ASSETS_URL: string;
-
 /**
  * A pass that copies normal buffer contents to a render target.
  */
@@ -6881,6 +7117,10 @@ export declare class PolygonMesh extends BatchedFeatureMesh<BufferGeometry<Attri
     private _enhancedMaterial?;
     constructor(ctx: EventContext, layerId: string);
     ready(): boolean;
+    /**
+     * Geometry type of this mesh.
+     */
+    readonly geometryType: "polygon";
     init(mesh: PolygonMesh_2, tileHandle: TileHandle | undefined): this;
     clone(): this;
     private initGeometry;
@@ -7274,6 +7514,10 @@ export declare class PolylineMesh extends BatchedFeatureMesh<BufferGeometry<Attr
     /** Flag indicating geometry initialization failed - mesh should never be visible */
     private _geometryInitFailed;
     constructor(ctx: EventContext);
+    /**
+     * Geometry type of this mesh.
+     */
+    readonly geometryType: "polyline";
     init(mesh: PolylineMesh_2): this;
     private initGeometry;
     private initMaterial;
@@ -7362,8 +7606,6 @@ declare class QuantizedMeshSourceDescription {
  */
 export declare function radianToDegree(radian: number): number;
 
-export declare const RAIN_ASSETS_URL: string;
-
 /** One baked raster layer: its overlapping WM tile textures, mosaicked into one
  * render target. Heatmap layers carry encoded DEM, copied raw (nearest, no
  * color conversion) so the composite decode stays valid. */
@@ -7915,10 +8157,6 @@ export declare type SdfTextBaseMutates = Mutates<SdfTextBaseState, SdfTextBaseUn
      * Update per-frame camera uniforms (FOV, screen height, far plane, RTE eye).
      */
     updatePerFrame: (fovRad: number, screenHeightPx: number, farPlane: number, cameraX: number, cameraY: number, cameraZ: number, viewMatrix: Matrix4, state: SdfTextBaseState) => void;
-    /**
-     * Update text dimension uniforms after text shaping.
-     */
-    updateTextDimensions: (textWidth: number, textHeight: number, bgMinY: number, bgMaxY: number) => void;
     /**
      * Set the SDF atlas texture external ref.
      */
@@ -7934,39 +8172,33 @@ export declare type SdfTextBaseMutates = Mutates<SdfTextBaseState, SdfTextBaseUn
      */
     updateAtlasSizes: () => void;
     /**
-     * Update position uniforms (RTE or RTC).
+     * Point the shader at the mesh's per-label data texture. Must be re-called
+     * whenever the mesh grows it, since growing allocates a new texture.
      */
-    setPosition: (position: Float32Array | {
-        high: Float32Array;
-        low: Float32Array;
-    }, useRTE: boolean, rtcCenter?: [number, number, number]) => void;
+    setLabelDataTexture: (texture: DataTexture | null, width: number, height: number) => void;
     /**
-     * Set the batch ID uniform (immutable after mount, but needed for batch creation).
+     * Update the batch's RTC center (the tile transform). Only meaningful in
+     * RTC mode; in RTE mode anchors carry their own high/low split.
      */
-    setBatchId: (batchId: number) => void;
-    /**
-     * Set the declutter hide factor (0 = shown … 1 = hidden); the fragment
-     * shader scales opacity by `1 - value` and the vertex shader hard-culls
-     * at 1. Kept separate from `show`/`opacity` so user-driven visibility and
-     * declutter results compose instead of clobbering each other.
-     */
-    setDeclutterHide: (value: number) => void;
+    setRtcCenter: (center: [number, number, number]) => void;
 }>;
 
 /**
  * Props for the sdfText base enhancer.
+ *
+ * Everything here is **batch-wide**: one material draws every label in a
+ * tile-layer. Per-label values (position, colour, opacity, font size, height,
+ * block metrics, batch id, declutter fade) live in the label data texture
+ * owned by `BatchedSdfTextMesh`, not in this state — see
+ * `web/navara_three/src/mesh/sdfText/labelData.ts`.
  */
 export declare type SdfTextBaseProps = {
     useRTE?: boolean;
     /** When `true` the fragment shader samples the atlas as 4-channel MTSDF
      *  (median of RGB + true SDF in alpha) instead of single-channel R8. */
     useMsdf?: boolean;
-    color?: number;
-    opacity?: number;
-    fontSize?: number;
     center?: [number, number];
     sizeInMeters?: boolean;
-    addHeight?: number;
     offsetDepth?: boolean;
     outlineWidth?: number;
     outlineColor?: number;
@@ -7988,12 +8220,8 @@ export declare type SdfTextBaseProps = {
  * Internal type - not exposed externally.
  */
 declare type SdfTextBaseRefs = {
-    uColor: UniformValue<Color_3>;
-    uOpacity: UniformValue<number>;
-    uFontSize: UniformValue<number>;
     uCenter: UniformValue<Vector2>;
     uSizeInMeters: UniformValue<boolean>;
-    uAddHeight: UniformValue<number>;
     uOffsetDepth: UniformValue<boolean>;
     uSdfThreshold: UniformValue<number>;
     uOutlineWidth: UniformValue<number>;
@@ -8006,20 +8234,12 @@ declare type SdfTextBaseRefs = {
     uFovRad: UniformValue<number>;
     uScreenHeightPx: UniformValue<number>;
     uFarPlane: UniformValue<number>;
-    uTextWidth: UniformValue<number>;
-    uTextHeight: UniformValue<number>;
-    uBgYBounds: UniformValue<Vector2>;
-    /** Screen-space declutter hide factor (0 = shown … 1 = hidden), animated
-     *  by the declutter fade. Driven by the declutter pass, not by material
-     *  style updates. */
-    uDeclutterHide: UniformValue<number>;
     uRTCCenter: UniformValue<Vector3>;
     uRTCCenterView: UniformValue<Vector3>;
     uEyeRTELow: UniformValue<Vector3>;
     uEyeRTEHigh: UniformValue<Vector3>;
     /** Always 1.0 — blocks fast-math reassociation of the RTE recombination. */
     u_rteOne?: UniformValue<number>;
-    nvr_uBatchId: UniformValue<number>;
     nvr_uPickable: UniformValue<number>;
     uAtlas: UniformValue<DataTexture | null>;
     /** COLRv1 RGBA atlas. `null` when the font has no color glyphs. */
@@ -8028,9 +8248,12 @@ declare type SdfTextBaseRefs = {
     uSdfAtlasSize: UniformValue<Vector2>;
     /** Current color atlas pixel dimensions; updated when the color atlas grows. */
     uColorAtlasSize: UniformValue<Vector2>;
-    uRTEPositionLOW?: UniformValue<Vector3>;
-    uRTEPositionHIGH?: UniformValue<Vector3>;
-    uRTCPosition?: UniformValue<Vector3>;
+    /** Per-label state, indexed by the `labelIndex` instance attribute. Owned by
+     *  the mesh and swapped wholesale when it outgrows its capacity. */
+    uLabelData: UniformValue<DataTexture | null>;
+    /** Dimensions of `uLabelData` in texels, for the shader's index-to-texel
+     *  math. Read as an `ivec2`. */
+    uLabelTexSize: UniformValue<Vector2>;
 };
 
 /**
@@ -8039,12 +8262,8 @@ declare type SdfTextBaseRefs = {
 export declare type SdfTextBaseState = Readonly<{
     useRTE: boolean;
     useMsdf: boolean;
-    color: Color_3;
-    opacity: number;
-    fontSize: number;
     center: [number, number];
     sizeInMeters: boolean;
-    addHeight: number;
     offsetDepth: boolean;
     outlineWidth: number;
     outlineColor: Color_3;
@@ -8068,163 +8287,6 @@ export declare type SdfTextMaterialProps = {
     base?: SdfTextBaseProps;
 };
 
-/**
- * A text mesh that renders glyphs from an SDF atlas using instanced geometry.
- *
- * Each glyph is an instanced unit quad positioned by shaping data,
- * sampling from a per-font SDF atlas texture. Uses billboard rendering
- * so text always faces the camera.
- */
-export declare class SDFTextMesh extends Mesh_2<InstancedBufferGeometry, ShaderMaterial> implements PickableMesh {
-    private _fontManager;
-    private _fontUrl;
-    /** Per-material text quality. Immutable after construction — switching
-     *  quality requires a separate (font, atlas) pair, so callers create a new
-     *  mesh rather than mutating this one. */
-    private _highQuality;
-    private _text;
-    /** Wrap width in ems (multiples of font size); 0 disables soft wrapping. */
-    private _maxWidth;
-    /** Multiplier on the font's natural line height (ascender − descender + gap). */
-    private _lineHeight;
-    /** Alignment factor for multi-line blocks: 0 left, 0.5 center, 1 right. */
-    private _textAlign;
-    private _atlasTexture;
-    /** Atlas texture is owned externally; do not dispose on cleanup when true. */
-    private _sharedAtlas;
-    /** Unique atlas glyphs this mesh currently renders (composite keys). */
-    private _glyphKeys;
-    /** The glyph set currently retained in the atlas (one visible-label
-     *  reference per key), or null when this mesh holds no references. */
-    private _retainedKeys;
-    /** Re-prepare a text in the worker (re-rasterizing evicted glyphs) using the
-     *  owner's font identity and loaded faces. Set by the parent batch. */
-    private _reprepare?;
-    /** Ask the owner to schedule a render after an async re-prepare. */
-    private _requestRender?;
-    /** World-space anchor in ECEF meters (f64), kept in sync with the position
-     *  uniforms so the declutter pass can project it without touching WASM. */
-    private _worldAnchor;
-    /** Whether this label participates in screen-space decluttering. */
-    private _declutter;
-    /** Layer-level placement priority from the material. */
-    private _declutterPriority;
-    /** Per-feature priority set through the evaluator; overrides the layer
-     *  value when defined. */
-    private _declutterPriorityOverride;
-    /** Current animated hide factor (mirrors the uDeclutterHide uniform) and
-     *  the placement target it is fading toward. */
-    private _declutterHide;
-    private _declutterTarget;
-    /** Text block dimensions in em units, mirroring the uTextWidth/uTextHeight/
-     *  uBgYBounds uniforms; 0 width means "no collision box" (empty text). */
-    private _labelWidthEm;
-    private _labelHeightEm;
-    private _labelMinYEm;
-    private _labelMaxYEm;
-    private _enhancer;
-    constructor(position: Float32Array | {
-        high: Float32Array;
-        low: Float32Array;
-    }, material: TextMaterial, transform: Transform_2, fontManager: FontManager, fontUrl: string, batchId: number | undefined, RTE: boolean, highQuality: boolean);
-    /** The text this mesh currently renders (its baked glyph string). */
-    get text(): string;
-    /**
-     * Set a shared atlas texture. When set, setText() will skip creating its own texture.
-     * The caller is responsible for the texture lifecycle.
-     */
-    setAtlasTexture(tex: DataTexture): void;
-    /**
-     * Set a shared color (COLRv1 RGBA) atlas texture.
-     * Pass `null` to clear when the font has no color glyphs.
-     */
-    setColorAtlasTexture(tex: DataTexture | null): void;
-    /**
-     * Wire the callbacks the parent batch uses to re-prepare evicted glyphs and
-     * request a render. `reprepare` must apply the batch's font identity and
-     * loaded faces so font refcounts stay balanced.
-     */
-    setGlyphLifecycleHandlers(reprepare: (text: string) => Promise<void>, requestRender: () => void): void;
-    /** Replace the retained glyph set, releasing the old references and (if
-     *  visible) retaining the new ones. */
-    private _setGlyphKeys;
-    /** Reconcile atlas references with current visibility: retain glyphs while
-     *  on screen, release them when hidden. If shown after the glyphs were
-     *  evicted (cache no longer prepared), re-prepare to re-rasterize them and
-     *  rebuild with fresh metrics. */
-    private _syncGlyphRefs;
-    /**
-     * Set text to render. Shapes via WASM, rebuilds instanced geometry, updates atlas texture.
-     */
-    setText(text: string, forceUpdate?: boolean): void;
-    /**
-     * Update visual properties: color, size, visibility, etc.
-     */
-    setFont(fontUrl: string): void;
-    setColor(color: Color_3): void;
-    setFontSize(size: number): void;
-    setSizeInMeters(enabled: boolean): void;
-    setCenter(x: number, y: number): void;
-    setHeight(height: number): void;
-    setSize(size: number): void;
-    setOpacity(opacity: number): void;
-    /**
-     * Set this label's declutter fade target; the actual hide factor animates
-     * toward it in {@link stepDeclutterFade}. Deliberately separate from
-     * `visible`/`show`: it neither churns scene-graph membership nor releases
-     * glyph atlas retains, so the declutter pass can retarget it every
-     * placement run at no cost.
-     */
-    setDeclutterHidden(hidden: boolean): void;
-    /**
-     * Advance the hide factor toward its target by `deltaMs / DECLUTTER_FADE_MS`
-     * and push it to the uniform. Returns true while still mid-fade.
-     */
-    stepDeclutterFade(deltaMs: number): boolean;
-    _setFeatureWidth(_width: number): void;
-    _setFeatureOpacity(opacity: number): void;
-    setPosition(position: Float32Array | {
-        high: Float32Array;
-        low: Float32Array;
-    }, RTE: boolean, transform: Transform_2): void;
-    /** Reconstruct the absolute ECEF anchor from the same inputs the position
-     *  uniforms receive (RTE high+low split, or RTC-relative + center). */
-    private _cacheWorldAnchor;
-    /**
-     * Build this label's collision candidate for the shared declutter pass, or
-     * null when it doesn't participate (declutter disabled, hidden, or empty).
-     * The local box mirrors the vertex shader's layout: glyphs span
-     * [0, textWidth] × [bgMinY, bgMaxY] in em units, shifted by the `center`
-     * anchor and scaled by the font size (sdfText.vert.glsl:111-115).
-     */
-    getDeclutterCandidate(owner: DeclutterParticipant, handle: number): DeclutterCandidate | null;
-    /**
-     * Set a per-feature placement priority (higher wins), overriding the
-     * layer-level `declutterPriority` for this label. Pass `undefined` to fall
-     * back to the layer value. Driven by the feature evaluator.
-     */
-    setDeclutterPriority(priority: number | undefined): void;
-    /**
-     * Apply material properties from WASM TextMaterial.
-     * Maps relevant properties to enhancer updates, with change tracking.
-     */
-    update(material: TextMaterial, forceUpdate?: boolean): void;
-    _setFeatureColor(color: Color_3): void;
-    _getFeatureColor(): Color_3;
-    _setFeatureShow(visible: boolean): void;
-    _setFeatureExtrudedHeight(_height: number): void;
-    _setFeatureHeight(height: number): void;
-    _setFrustumCulled(culled: boolean): void;
-    onBeforePicking(): void;
-    onAfterPicking(): void;
-    getRenderable(): Object3D;
-    dispose(): void;
-    private _createBaseGeometry;
-    private _buildGlyphInstances;
-    private _setInstanceAttribute;
-    private _updateAtlasTexture;
-}
-
 export declare type SelectiveEffectConfig = {
     selectiveEffect?: true;
 } & EffectConfig;
@@ -8632,6 +8694,8 @@ export declare type SourceLayerBase<Layer extends {
  */
 export declare type SourceRef = string | Source;
 
+declare type SpriteGeometryType = Extract<GeometryType, typeof GEOMETRY_TYPES.Point | typeof GEOMETRY_TYPES.Billboard>;
+
 export declare const STARS_ASSETS_URL: string;
 
 export declare const STARS_RENDER_ORDER: number;
@@ -10343,6 +10407,11 @@ export declare class UnknownTypeError extends Error {
      set watermask(value: number | null | undefined);
  }
 
+ /**
+  * Array of valid geometry type values for runtime validation.
+  */
+ export declare const VALID_GEOMETRY_TYPES: ("billboard" | "text" | "point" | "polyline" | "polygon" | "model")[];
+
  export declare type Vec2 = Required<NormalizeWASMClass<Vec2_3>>;
 
  declare class Vec2_2 {
@@ -10651,8 +10720,6 @@ export declare class UnknownTypeError extends Error {
      idle: () => void;
  };
 
- export declare const WATER_ASSETS_URL: string;
-
  export declare const WATER_NORMAL_URL: string;
 
  /**