@navaramap/core 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -89,8 +89,8 @@ export declare class ColorMap<T extends ColorMapType = ColorMapType> {
     createImage(): HTMLCanvasElement;
     /**
      * Flatten the color map LUT into a Float32Array for WASM/GPU usage.
-     * Each color tuple [r, g, b] is flattened into consecutive array elements.
-     * @returns A Float32Array with length = lut.length * 3
+     * Each color tuple [r, g, b] becomes [r, g, b, 1] (RGBA, fully opaque).
+     * @returns A Float32Array with length = lut.length * 4
      */
     flatten(): Float32Array;
 }
@@ -152,17 +152,19 @@ export declare class ConstructedPolylineGeometryLike {
     end_high_size: number | undefined;
     end_low: Float32Array | undefined;
     end_low_size: number | undefined;
-    start_normals: Float32Array | undefined;
-    start_normals_size: number | undefined;
-    end_normal_and_texture_coordinate_normalization_x: Float32Array | undefined;
-    end_normal_and_texture_coordinate_normalization_x_size: number | undefined;
-    right_normal_and_texture_coordinate_normalization_y: Float32Array;
-    right_normal_and_texture_coordinate_normalization_y_size: number;
+    start_normal_and_length_high: Float32Array | undefined;
+    start_normal_and_length_high_size: number | undefined;
+    end_normal_and_segment_length: Float32Array | undefined;
+    end_normal_and_segment_length_size: number | undefined;
+    right_normal_and_line_length: Float32Array;
+    right_normal_and_line_length_size: number;
     batch_id: Float32Array | undefined;
     batch_id_size: number | undefined;
     batch_index: Uint32Array | undefined;
     batch_index_size: number | undefined;
     indices: Uint32Array;
+    line_segments: Float32Array | undefined;
+    line_distance_and_ends: Float32Array | undefined;
     constructor(t: ConstructedPolylineGeometry);
 }
 
@@ -196,33 +198,6 @@ export declare class EventHandler<T extends BaseEventMap = BaseEventMap, K exten
     emit<E extends K>(k: E, ...args: Parameters<T[E]>): void;
 }
 
-export declare class EventManager {
-    stacks: EventsStacks;
-    addedEventIds: Map<string, Set<unknown>>;
-    private sortedLengths;
-    private transactionManager;
-    needsUpdate(): boolean;
-    pushEvents(events: Events | undefined): void;
-    forEachStack<Key extends JsEventsKey>(key: Key, cb: (value: GetJsEventValue<Key>) => void, max?: number): void;
-    /** Order the stack for dispatch. Pushes only append, so only the events
-     * added since the last pass are sorted and merged into the already sorted
-     * prefix (the prefix wins ties, keeping equal keys FIFO). */
-    private sortPending;
-    private removeAt;
-    forEachStackAsync<Key extends JsEventsKey>(key: Key, cb: (value: GetJsEventValue<Key>) => Promise<void>, max?: number, shouldProcess?: (value: GetJsEventValue<Key>) => boolean, order?: (a: GetJsEventValue<Key>, b: GetJsEventValue<Key>) => number): Promise<void>;
-    removeDuplicatedTransactionEvents<AddKey extends JsEventsKey, RemoveKey extends JsEventsKey, ChangeKey extends JsEventsKey>(options: TransactionProcessOption<AddKey, RemoveKey, ChangeKey>): void;
-    removeStacksByIndices(key: JsEventsKey, removedIndices: Set<number>): void;
-    processTransactionEvents<AddKey extends JsEventsKey, RemoveKey extends JsEventsKey, ChangeKey extends JsEventsKey>(transactionKey: string, options: TransactionProcessOption<AddKey, RemoveKey, ChangeKey>, cb: (ev: TransactionCallbackParams<AddKey, RemoveKey, ChangeKey>) => Promise<void>, handlers?: {
-        shouldProcess?: (ev: TransactionCallbackParams<AddKey, RemoveKey, ChangeKey>) => boolean;
-        generateEventId?: (ev: TransactionCallbackParams<AddKey, RemoveKey, ChangeKey>) => string;
-        onAbort?: (ev: GetJsEventValue<RemoveKey>) => void | Promise<void>;
-    }): void;
-}
-
-declare type EventsStacks = {
-    [K in JsEventsKey]-?: JsEvents[K] extends unknown[] ? JsEvents[K] : JsEvents[K][];
-};
-
 export declare class ExtentRadianF32Like implements RemoveFreeRecursively<ExtentRadianF32> {
     east: number;
     north: number;
@@ -244,17 +219,14 @@ export declare function generate_id_from_entity(entity: EntityEvent): string;
  * instead of an `EntityEvent` instance. */
 export declare function generate_id_from_ind_gen(ind: number, gen: number): string;
 
-declare type GetJsEventValue<K extends JsEventsKey> = EventsStacks[K] extends unknown[] ? EventsStacks[K][number] : EventsStacks[K];
-
 /**
  * Globe configuration manager.
  *
  * Provides an interface for accessing and modifying globe properties
  * that are shared across different material types (VectorTile, RasterTile, RasterTerrain).
  */
-export declare class Globe implements Omit<RemoveFreeRecursively<Globe_2>, "elevationColormap" | "color" | "isGeographicTiling"> {
+export declare class Globe implements Omit<RemoveFreeRecursively<Globe_2>, "color" | "isGeographicTiling"> {
     private handler;
-    private _elevationColormap?;
     constructor(handler: GlobeHandler, options?: GlobeOptions);
     setOptions(options?: GlobeOptions): void;
     get maxSse(): number;
@@ -273,8 +245,6 @@ export declare class Globe implements Omit<RemoveFreeRecursively<Globe_2>, "elev
     set opacity(value: number);
     get wireframe(): boolean;
     set wireframe(value: boolean);
-    get elevationColormap(): ColorMap | undefined;
-    set elevationColormap(value: ColorMap);
 }
 
 /**
@@ -290,7 +260,6 @@ export declare type GlobeHandler = {
     getUseNormal: () => boolean | undefined;
     getOpacity: () => number | undefined;
     getWireframe: () => boolean | undefined;
-    getElevationColormap: () => Float32Array | undefined;
     setTransparent: (value: boolean) => void;
     setMaxSse: (value: number) => void;
     setSegments: (value: number) => void;
@@ -299,11 +268,9 @@ export declare type GlobeHandler = {
     setUseNormal: (value: boolean) => void;
     setOpacity: (value: number) => void;
     setWireframe: (value: boolean) => void;
-    setElevationColormap: (value: ColorMap) => void;
 };
 
-export declare type GlobeOptions = Partial<Omit<Globe_2, "constructor" | "free" | "elevationColormap" | "color" | "isGeographicTiling">> & {
-    elevationColormap?: ColorMap;
+export declare type GlobeOptions = Partial<Omit<Globe_2, "constructor" | "free" | "color" | "isGeographicTiling">> & {
     color?: Color;
 };
 
@@ -317,12 +284,108 @@ export declare function isNotNullish<T>(value: T | null | undefined): value is T
 
 export declare function isNotUndefined<T>(value: T | undefined): value is T;
 
+/**
+ * Consumes the per-frame engine events and dispatches them to the registered
+ * handlers with no queueing: every `requested` starts its job in the same
+ * tick (admission and priority are the engine's job), every `removed` aborts
+ * or tears down, every `changed` applies or waits for the in-flight `start`.
+ * Taken WASM event objects are freed here, once the handler that received
+ * them has settled, so handlers never call `free()` on an event.
+ */
+export declare class JobDispatcher {
+    private readonly sync;
+    private readonly registered;
+    private readonly onSettled?;
+    private disposed;
+    private inFlightJobs;
+    constructor(options?: JobDispatcherOptions);
+    register<Req, Chg, Rem, Product>(handler: JobHandler<Req, Chg, Rem, Product>): RegisteredJobKind;
+    /** A synchronous, stateless handler; events are freed right after it. */
+    registerSync<K extends JsEventsKey>(key: K, handle: (ev: JsEventValue<K>) => void): void;
+    /** Jobs whose `start` or `change` has not settled yet. */
+    inFlight(): number;
+    tick(events: Events | undefined): void;
+    /** Aborts every in-flight job and forgets the table. Live products are the
+     * owner's to dispose (they are indexed outside the dispatcher). */
+    dispose(): void;
+    private start;
+    private settleStart;
+    private remove;
+    private change;
+    private applyChange;
+    /**
+     * The async call on `job` settled. Runs the deferred teardown when a
+     * `removed` arrived (or the dispatcher was disposed) meanwhile, otherwise
+     * applies the change that waited; returns whether the job is gone.
+     */
+    private finish;
+    private teardown;
+}
+
+export declare type JobDispatcherOptions = {
+    /** Called whenever a job's `start` settles with a product, i.e. something
+     * new is on screen. */
+    onSettled?: () => void;
+};
+
+/**
+ * One kind of frontend job: the engine emits `requested` when it wants the
+ * frontend to run async work for an entity (fetch, worker task, mesh build),
+ * `changed` while the entity is alive, and `removed` when the entity is
+ * despawned — unconditionally, including while the job is still in flight.
+ *
+ * The dispatcher turns these into calls on this handler and owns the job
+ * table; the handler never sees ordering, dedupe or abort bookkeeping.
+ */
+export declare type JobHandler<Req, Chg, Rem, Product> = {
+    /** Used in error logs only. */
+    name: string;
+    events: {
+        requested: JsEventsKey;
+        changed?: JsEventsKey;
+        removed: JsEventsKey;
+    };
+    /**
+     * Called right away for every admitted `requested` event. After each
+     * `await`, check `abort.signal.aborted` before touching shared state or
+     * reporting to the engine: a removed job must not report. Resolving
+     * `undefined` means "done, no product" (an empty geometry, a fetch whose
+     * result went straight into the buffer store, ...); the job is then
+     * forgotten, like one whose `start` failed.
+     */
+    start(ev: Req, abort: AbortController): Promise<Product | undefined>;
+    /**
+     * Applies a `changed` snapshot to a live product. Calls on one job never
+     * overlap: a change arriving while `start` or a previous change is in
+     * flight waits, and only the latest waiting one is applied.
+     */
+    change?(product: Product, ev: Chg): void | Promise<void>;
+    /**
+     * Called exactly once per `removed` event, when nothing is in flight for
+     * the job any more: immediately for a live or unknown job (`product` is
+     * `undefined` for an unknown one or one whose `start` failed), or once the
+     * aborted `start` / `change` settles. The job's abort signal has fired by
+     * then, so continuations still running after `start` see the removal.
+     * `ev` is `undefined` only when the dispatcher itself is disposed while
+     * the job is in flight.
+     */
+    teardown(product: Product | undefined, ev: Rem | undefined): void;
+    /** Reports a rejected / thrown `start` to the engine (kind specific); a
+     * kind without it gets the error logged instead. Not called once the job
+     * was removed or the dispatcher disposed; an abort the handler fires on
+     * its own still reports. */
+    failed?(ev: Req, error: unknown): void;
+};
+
 export declare type JsEvents = {
     [K in keyof Events as K extends `take_${infer P}` ? P : never]: Events[K] extends (...args: never[]) => infer R ? R : never;
 };
 
 export declare type JsEventsKey = keyof JsEvents;
 
+/** One element of a stack (the value itself for the `Option` stacks). */
+export declare type JsEventValue<K extends JsEventsKey> = JsEvents[K] extends unknown[] ? JsEvents[K][number] : JsEvents[K];
+
 /** Geodetic position: `lat`/`lng` in **degrees**. */
 export declare type LatLng = Omit<LatLngHeight, "height">;
 
@@ -416,6 +479,12 @@ export declare class PolylineMaterialLike {
 
 export declare type Ray = Required<NormalizeWASMClass<Ray_2>>;
 
+/** A registered kind, as returned by {@link JobDispatcher.register}. */
+export declare type RegisteredJobKind = {
+    /** Jobs of this kind whose `start` or `change` has not settled yet. */
+    inFlight(): number;
+};
+
 export declare type RemoveFreeRecursively<T> = T extends {
     free: unknown;
 } ? {
@@ -435,6 +504,7 @@ export declare class ReturnedConstructedTerrainMeshLike implements RemoveFreeRec
     skirt_uvs: Float32Array | undefined;
     skirt_indices: Uint32Array | undefined;
     skirt_normals: Float32Array | undefined;
+    skirt_heights: Float32Array | undefined;
     watermask: Uint8Array | undefined;
     constructor(t: ReturnedConstructedTerrainMesh);
     transferVertices(): Float32Array;
@@ -446,6 +516,7 @@ export declare class ReturnedConstructedTerrainMeshLike implements RemoveFreeRec
     transferSkirtUvs(): Float32Array | undefined;
     transferSkirtIndices(): Uint32Array | undefined;
     transferSkirtNormals(): Float32Array | undefined;
+    transferSkirtHeights(): Float32Array | undefined;
     transferWatermask(): Uint8Array | undefined;
     hasSkirt(): boolean;
     hasNormals(): boolean;
@@ -463,52 +534,6 @@ export declare class TileXYZLike implements RemoveFreeRecursively<TileXYZ> {
     constructor(t: TileXYZ);
 }
 
-export declare class Transaction {
-    id: string;
-    continuable: boolean;
-    currentPending?: Promise<void>;
-    next?: Transaction;
-    parent?: Transaction;
-    constructor(id: string, continuable?: boolean);
-    then(cb: () => Promise<void>): Transaction;
-    end(): void;
-}
-
-declare type TransactionCallbackParams<AddKey extends JsEventsKey, RemoveKey extends JsEventsKey, ChangeKey extends JsEventsKey> = {
-    type: "add";
-    event: GetJsEventValue<AddKey>;
-} | {
-    type: "remove";
-    event: GetJsEventValue<RemoveKey>;
-} | {
-    type: "change";
-    event: GetJsEventValue<ChangeKey>;
-};
-
-export declare class TransactionManager {
-    private record;
-    getOrInsert(id: string): Transaction;
-}
-
-declare type TransactionProcessOption<AddKey extends JsEventsKey, RemoveKey extends JsEventsKey, ChangeKey extends JsEventsKey> = {
-    add: {
-        key: AddKey;
-        max?: number;
-        /** Dispatch order for the pending stack. Events a `shouldProcess` gate
-         * leaves behind are re-sorted against newer ones every pass, so this turns
-         * the FIFO stack into a priority queue (stable: equal keys stay FIFO). */
-        order?: (a: GetJsEventValue<AddKey>, b: GetJsEventValue<AddKey>) => number;
-    };
-    remove: {
-        key: RemoveKey;
-        max?: number;
-    };
-    change?: {
-        key: ChangeKey;
-        max?: number;
-    };
-};
-
 export declare class TransferableMartiniLike implements RemoveFreeRecursively<TransferableMartini> {
     coords: Uint32Array;
     size: number;