@sakuzu/maplibre-gl-draw 1.0.0

package/dist/view/cache/texture.js

@@ -0,0 +1,292 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * TextureCache
+ *
+ * Manages the images of Image features as cached WebGL textures.
+ *
+ * Every texture is uploaded while the engine is rendering (inside the custom layer's render),
+ * never from a callback such as `img.onload`: the GL context is shared with maplibre, and
+ * outside a render call its state belongs to maplibre. An image is decoded asynchronously and
+ * kept as a decoded image; the next frame that asks for it uploads it.
+ */
+import { isEmbeddedImageDataUrl } from '../../shared/utils/embedded-image.js';
+/**
+ * TextureCache
+ *
+ * @internal
+ */
+export class TextureCache {
+    constructor(gl, maxCacheSize = 500) {
+        Object.defineProperty(this, "gl", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "imageCache", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "maxCacheSize", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Images decoded and waiting for their upload, by src */
+        Object.defineProperty(this, "decodedImages", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        /** Decodes in progress, by src (one decode per src, shared by every caller) */
+        Object.defineProperty(this, "loadingImages", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        /**
+         * srcs whose decode failed, with the error (not retried every frame; invalidateImage
+         * forgets them)
+         */
+        Object.defineProperty(this, "failedImages", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        /** Set by dispose(); a decode that finishes afterwards is dropped */
+        Object.defineProperty(this, "disposed", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        /** MAX_TEXTURE_SIZE of the context (read once, 0 = not read yet) */
+        Object.defineProperty(this, "maxTextureSize", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        this.gl = gl;
+        this.maxCacheSize = maxCacheSize;
+    }
+    /**
+     * The texture of an image, uploaded in this call if its decode has finished
+     *
+     * Call it while rendering. It returns null while the image is not decoded yet; the decode is
+     * started once per src (every caller shares it), and `onReady` is called when it finishes so
+     * that a frame can be requested. A decode that finishes after dispose() is dropped.
+     *
+     * @param src An embedded PNG/JPEG/WebP/GIF data URL
+     * @param onReady Called when the decode has finished (not called on failure)
+     * @param onError Called when the decode fails or the src is refused. Only the call that
+     *   starts the decode is told; a later caller reads the failure with `getImageError`
+     */
+    acquireImageTexture(src, onReady, onError) {
+        const cached = this.getImageTextureSync(src);
+        if (cached)
+            return cached;
+        const decoded = this.decodedImages.get(src);
+        if (decoded) {
+            this.decodedImages.delete(src);
+            return this.uploadImage(src, decoded);
+        }
+        if (this.failedImages.has(src) || this.loadingImages.has(src))
+            return null;
+        this.decodeImage(src).then(() => onReady?.(), (error) => {
+            this.failedImages.set(src, error);
+            onError?.(error);
+        });
+        return null;
+    }
+    /**
+     * The error of a src whose decode failed, or null (not failed, or not tried yet)
+     */
+    getImageError(src) {
+        return this.failedImages.get(src) ?? null;
+    }
+    /**
+     * Decodes an image (the shared decode of a src while one is in progress)
+     */
+    decodeImage(src) {
+        const loading = this.loadingImages.get(src);
+        if (loading)
+            return loading;
+        // Only embedded raster images are decoded. Any other URL would make every viewer of the
+        // data send a request to an outside host (the data may come from another participant).
+        if (!isEmbeddedImageDataUrl(src)) {
+            return Promise.reject(new Error('Refused to load an image that is not an embedded PNG/JPEG/WebP/GIF data URL'));
+        }
+        const promise = new Promise((resolve, reject) => {
+            const img = new Image();
+            img.crossOrigin = 'anonymous';
+            img.onload = () => {
+                this.loadingImages.delete(src);
+                // Only the decoded image is kept here; the upload happens in the next render
+                if (!this.disposed)
+                    this.decodedImages.set(src, img);
+                resolve();
+            };
+            img.onerror = () => {
+                this.loadingImages.delete(src);
+                reject(new Error(`Failed to load image: ${src.slice(0, 64)}`));
+            };
+            img.src = src;
+        });
+        this.loadingImages.set(src, promise);
+        return promise;
+    }
+    /**
+     * Uploads a decoded image and caches its texture
+     *
+     * An image larger than MAX_TEXTURE_SIZE is scaled down to fit (texImage2D would fail and the
+     * image would silently be missing). The info keeps the size of the image itself, which is what
+     * its display size is derived from.
+     */
+    uploadImage(src, img) {
+        if (this.imageCache.size >= this.maxCacheSize) {
+            this.evictOldestImage();
+        }
+        const texture = uploadRgbaTexture(this.gl, this.fitToTextureSize(img), true);
+        if (!texture)
+            return null;
+        const entry = {
+            texture,
+            width: img.width,
+            height: img.height,
+            lastUsed: Date.now(),
+        };
+        this.imageCache.set(src, entry);
+        return { texture, width: img.width, height: img.height };
+    }
+    /**
+     * The image itself, or a copy scaled down to MAX_TEXTURE_SIZE when it is larger
+     */
+    fitToTextureSize(img) {
+        if (this.maxTextureSize === 0) {
+            const max = Number(this.gl.getParameter(this.gl.MAX_TEXTURE_SIZE));
+            this.maxTextureSize = Number.isFinite(max) && max > 0 ? max : 4096;
+        }
+        const max = this.maxTextureSize;
+        if (img.width <= max && img.height <= max)
+            return img;
+        const scale = max / Math.max(img.width, img.height);
+        const canvas = document.createElement('canvas');
+        canvas.width = Math.max(1, Math.floor(img.width * scale));
+        canvas.height = Math.max(1, Math.floor(img.height * scale));
+        canvas.getContext('2d')?.drawImage(img, 0, 0, canvas.width, canvas.height);
+        return canvas;
+    }
+    /**
+     * Gets an image texture synchronously (only when it is already cached)
+     */
+    getImageTextureSync(src) {
+        const cached = this.imageCache.get(src);
+        if (cached) {
+            cached.lastUsed = Date.now();
+            return {
+                texture: cached.texture,
+                width: cached.width,
+                height: cached.height,
+            };
+        }
+        return null;
+    }
+    /**
+     * Deletes the oldest image entry
+     */
+    evictOldestImage() {
+        let oldestKey = null;
+        let oldestTime = Infinity;
+        for (const [key, entry] of this.imageCache) {
+            if (entry.lastUsed < oldestTime) {
+                oldestTime = entry.lastUsed;
+                oldestKey = key;
+            }
+        }
+        if (oldestKey) {
+            const entry = this.imageCache.get(oldestKey);
+            if (entry) {
+                this.gl.deleteTexture(entry.texture);
+            }
+            this.imageCache.delete(oldestKey);
+        }
+    }
+    /**
+     * Invalidates a specific image cache entry
+     */
+    invalidateImage(src) {
+        this.decodedImages.delete(src);
+        this.failedImages.delete(src);
+        const entry = this.imageCache.get(src);
+        if (entry) {
+            this.gl.deleteTexture(entry.texture);
+            this.imageCache.delete(src);
+        }
+    }
+    /**
+     * Clears the whole cache
+     */
+    clear() {
+        for (const entry of this.imageCache.values()) {
+            this.gl.deleteTexture(entry.texture);
+        }
+        this.imageCache.clear();
+        this.decodedImages.clear();
+    }
+    /**
+     * Disposes of the resources
+     *
+     * A decode still in progress is dropped when it finishes (it never reaches the GL context).
+     */
+    dispose() {
+        this.disposed = true;
+        this.clear();
+    }
+}
+/**
+ * Uploads an image to a new RGBA texture with the unpack state the engine's shaders expect
+ *
+ * The shaders output colors that are not premultiplied and read the image with its first row at
+ * the top, so the upload sets `UNPACK_PREMULTIPLY_ALPHA_WEBGL` and `UNPACK_FLIP_Y_WEBGL` to
+ * false explicitly instead of inheriting whatever maplibre left in the context. The pixel store
+ * and the texture binding are borrowed and given back (maplibre-coupling.md): the values found
+ * are restored after the upload.
+ *
+ * @param mipmap Whether to build mipmaps (for images, which are often drawn smaller than their
+ *   size)
+ * @returns The texture, or null when it cannot be created (a lost context)
+ */
+export function uploadRgbaTexture(gl, source, mipmap) {
+    const texture = gl.createTexture();
+    if (!texture)
+        return null;
+    const previousTexture = gl.getParameter(gl.TEXTURE_BINDING_2D);
+    const previousFlipY = gl.getParameter(gl.UNPACK_FLIP_Y_WEBGL) === true;
+    const previousPremultiply = gl.getParameter(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL) === true;
+    gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, false);
+    gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, false);
+    gl.bindTexture(gl.TEXTURE_2D, texture);
+    gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, source);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+    if (mipmap) {
+        gl.generateMipmap(gl.TEXTURE_2D);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR_MIPMAP_LINEAR);
+    }
+    else {
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+    }
+    gl.bindTexture(gl.TEXTURE_2D, previousTexture);
+    gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, previousFlipY);
+    gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, previousPremultiply);
+    return texture;
+}

package/dist/view/coordinator.d.ts

@@ -0,0 +1,27 @@
+/**
+ * RenderCoordinator
+ *
+ * Subscribes to the Store and automatically triggers a repaint when the state changes.
+ * This removes the need for each mode to call requestRepaint() explicitly.
+ */
+import type { Map as MapLibreMap } from 'maplibre-gl';
+import type { Store } from '../store/store.js';
+/**
+ * Dependencies of RenderCoordinator
+ */
+export interface RenderCoordinatorDeps {
+    map: MapLibreMap;
+    store: Store;
+}
+/**
+ * RenderCoordinator implementation
+ */
+export declare class RenderCoordinatorImpl implements RenderCoordinator {
+    private map;
+    private store;
+    private unsubscribe;
+    constructor(deps: RenderCoordinatorDeps);
+    start(): void;
+    stop(): void;
+    requestRender(): void;
+}

package/dist/view/coordinator.js

@@ -0,0 +1,72 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Determines whether a change requires a repaint
+ */
+function shouldRepaint(changes) {
+    // A repaint is required if any of the following changed
+    return !!((changes.features || // creation, update or deletion of features
+        changes.layers || // layer changes
+        changes.groups || // group changes (reordering, show/hide)
+        changes.layerReorder || // reordering of items within a layer
+        changes.groupReorder || // reordering of features within a group
+        changes.selection || // selection state changes
+        changes.tentative || // changes to the transient state while drawing
+        changes.uiStateChanged) // changes to the UI state (dragState, boxSelection)
+    );
+}
+/**
+ * RenderCoordinator implementation
+ */
+export class RenderCoordinatorImpl {
+    constructor(deps) {
+        Object.defineProperty(this, "map", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "store", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "unsubscribe", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        this.map = deps.map;
+        this.store = deps.store;
+    }
+    start() {
+        // Do nothing if already subscribed
+        if (this.unsubscribe) {
+            return;
+        }
+        this.unsubscribe = this.store.subscribe((changes) => {
+            if (shouldRepaint(changes)) {
+                this.map.triggerRepaint();
+            }
+        });
+    }
+    stop() {
+        if (this.unsubscribe) {
+            this.unsubscribe();
+            this.unsubscribe = null;
+        }
+    }
+    requestRender() {
+        this.map.triggerRepaint();
+    }
+}
+/**
+ * Creates a RenderCoordinator
+ *
+ * @internal
+ */
+export function createRenderCoordinator(deps) {
+    return new RenderCoordinatorImpl(deps);
+}

package/dist/view/feature-companion.d.ts

@@ -0,0 +1,173 @@
+/**
+ * The extension point for companion rendering and companion hits (feature companion)
+ *
+ * A hook for the extension implementation to add "things that are not the feature itself,
+ * but that accompany the feature, are drawn at the same z position, and are grabbable in
+ * that same z order". core knows nothing at all about what a companion means (it only asks
+ * where they are with has, lets them draw with draw, asks for hits with hitTest, and hands
+ * a click that hit back to the provider).
+ *
+ * Rendering and hit testing are given to the same provider so that what is visible and
+ * what is grabbable agree (they are resolved at the same position in the z scan).
+ *
+ * Where they are called:
+ *   - Rendering: immediately before the feature itself is drawn (= one step lower in the
+ *     z order). core flushes the batch in progress before and after the call to keep z
+ *     consistency
+ *   - Hits: in the front-to-back scan of a click, immediately after the test of the feature
+ *     itself misses and before moving on to the next (one step further back) feature
+ *
+ * `has` is called for every feature inside the per-frame z scan and the hit scan, so it
+ * must be O(1) (an index, or an O(1) derivation from the feature). As long as it returns
+ * false, no batch flush, no draw and no hitTest happen at all, and the conventional
+ * rendering efficiency and hit testing path are kept as they were.
+ *
+ * Unlike the extension points of auxiliary handles and the selection UI, there is one
+ * registry per draw instance (createFeatureCompanionRegistry). When several instances
+ * (the hidden renderers of printing and thumbnails) hold different Stores that have the
+ * same feature ids, the provider has no way to tell "is this a feature of my own Store?"
+ * (a replaced DocumentStore may return a new object from getFeature every time, so identity
+ * cannot be used), so ownership is expressed by separating the registries.
+ */
+import type { ProjectionData } from 'maplibre-gl';
+import type { CustomRendererDrawContext } from '../extension/index.js';
+import type { LngLat, ScreenPoint } from '../shared/math/index.js';
+import type { Coordinate, Feature } from '../store/types.js';
+/**
+ * A hit on a companion, as returned by {@link FeatureCompanionProvider.hitTest}.
+ *
+ * core does not interpret the contents. The provider puts its own identifier in and
+ * receives it back through `onCompanionClick`.
+ */
+export interface CompanionHit {
+    /** The identifier inside the provider */
+    id: string;
+}
+/**
+ * The context passed to {@link FeatureCompanionProvider.hitTest}.
+ *
+ * A minimal structure holding the point being tested (screen px) plus the coordinate
+ * transform, the zoom and the click tolerance. The coordinate transform follows the same
+ * style as the context of auxiliary handles (AuxiliaryHandleContext)
+ * (geographic coordinates [lng, lat] <-> screen px).
+ */
+export interface CompanionHitContext {
+    /** The point being tested (screen px) */
+    point: ScreenPoint;
+    /** Geographic coordinates -> screen px */
+    project(lngLat: Coordinate): ScreenPoint;
+    /** Screen px -> geographic coordinates */
+    unproject(point: ScreenPoint): LngLat;
+    /** The current zoom level */
+    zoom: number;
+    /** The click tolerance (screen px; the same value as core's hit testing setting) */
+    tolerancePx: number;
+}
+/**
+ * Draws something that accompanies a feature (a label, a callout) right below it in the
+ * draw order, and makes it clickable in the same order.
+ *
+ * Register one with `draw.registerFeatureCompanionProvider(provider)`. What is drawn and what
+ * is hit are resolved at the same position of the z order, so what is visible is what can be
+ * grabbed. A click on a companion does not change the selection; it is handed to
+ * `onCompanionClick`.
+ */
+export interface FeatureCompanionProvider {
+    /** An identifier unique within the registry (re-registering with the same id overwrites) */
+    id: string;
+    /**
+     * Whether this feature has companions.
+     *
+     * It is called for every feature in the per-frame z scan and the hit scan, so it must
+     * be O(1).
+     */
+    has(feature: Feature): boolean;
+    /**
+     * Called immediately before the feature itself (= one z step lower).
+     *
+     * core flushes the batch in progress before and after the call, so what is drawn always
+     * comes below this feature and above the feature one step further back.
+     */
+    draw(feature: Feature, projectionData: ProjectionData, zoom: number, context: CustomRendererDrawContext): void;
+    /**
+     * Called in the z scan of click resolution, after the feature itself misses and before
+     * the next feature.
+     *
+     * If it returns a hit, core consumes that click (it does not change the selection state,
+     * nor does it clear the selection as an empty click would) and calls
+     * `onCompanionClick`.
+     */
+    hitTest(feature: Feature, point: ScreenPoint, context: CompanionHitContext): CompanionHit | null;
+    /**
+     * The notification of a consumed click.
+     *
+     * @param featureId The ID of the feature that owns the companion
+     * @param hit The hit returned by hitTest
+     */
+    onCompanionClick(featureId: string, hit: CompanionHit): void;
+}
+/**
+ * A companion hit resolved in the z scan, with the provider and the feature it belongs to.
+ */
+export interface FeatureCompanionHitResult {
+    /** The id of the provider that returned the hit */
+    providerId: string;
+    /** The id of the feature that owns the companion */
+    featureId: string;
+    /** The hit as the provider returned it */
+    hit: CompanionHit;
+}
+/**
+ * The registered {@link FeatureCompanionProvider}s of one draw instance.
+ *
+ * One is held per draw instance. It has the same scope as the renderers of custom type
+ * features (customLayer.registerFeatureRenderer), so the providers of other instances
+ * (the hidden renderers of printing, thumbnails and previews) do not get mixed in.
+ *
+ * It must not be made a module-level singleton. A provider closes over its own Store, and
+ * feature IDs agree across several instances when the document is the same, so sharing it
+ * would draw things twice with the geometry of another instance's Store. The provider
+ * cannot tell "is this my own feature?" (depending on the Store implementation, getFeature
+ * builds a different object every time, so object identity cannot be used). Ownership is
+ * expressed by separating the registries.
+ */
+export interface FeatureCompanionRegistry {
+    /**
+     * Registers a provider
+     *
+     * @returns The function that cancels the registration (calling it after a re-registration
+     *   with the same id does not remove the provider that came in later)
+     */
+    register(provider: FeatureCompanionProvider): () => void;
+    /** Gets a registered provider by id */
+    get(id: string): FeatureCompanionProvider | undefined;
+    /** Enumerates the registered providers (in registration order) */
+    list(): FeatureCompanionProvider[];
+    /**
+     * Whether even one provider is registered
+     *
+     * An O(1) early exit looked at once at the entrance of a scan. If false, the path is the
+     * conventional one.
+     */
+    any(): boolean;
+    /**
+     * The generation number (for deciding cache invalidation)
+     *
+     * It increases on every registration and cancellation. The cache of retained mode
+     * (view/layer/store-retained) caches the classification that "cuts features having
+     * companions out into the immediate rendering run", and that classification can change
+     * as registrations come and go. Watch the generation number change and discard the cache.
+     */
+    generation(): number;
+    /** Cancels all registrations */
+    clear(): void;
+    /** Whether there is a provider that has companions for this feature */
+    has(feature: Feature): boolean;
+}
+/**
+ * Creates an empty {@link FeatureCompanionRegistry}, for testing a provider in isolation.
+ * Each draw instance holds its own; do not share one between instances.
+ *
+ * @returns A new registry with no provider
+ */
+export declare function createFeatureCompanionRegistry(): FeatureCompanionRegistry;

package/dist/view/feature-companion.js

@@ -0,0 +1,108 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Creates an empty {@link FeatureCompanionRegistry}, for testing a provider in isolation.
+ * Each draw instance holds its own; do not share one between instances.
+ *
+ * @returns A new registry with no provider
+ */
+export function createFeatureCompanionRegistry() {
+    const providers = new Map();
+    let generation = 0;
+    return {
+        register(provider) {
+            providers.set(provider.id, provider);
+            generation++;
+            return () => {
+                if (providers.get(provider.id) === provider) {
+                    providers.delete(provider.id);
+                    generation++;
+                }
+            };
+        },
+        get: (id) => providers.get(id),
+        list: () => [...providers.values()],
+        any: () => providers.size > 0,
+        generation: () => generation,
+        clear() {
+            if (providers.size === 0)
+                return;
+            providers.clear();
+            generation++;
+        },
+        has(feature) {
+            if (providers.size === 0)
+                return false;
+            for (const provider of providers.values()) {
+                if (provider.has(feature))
+                    return true;
+            }
+            return false;
+        },
+    };
+}
+/**
+ * Draws the things accompanying a feature after closing the batch frame (registration order)
+ *
+ * A batch is not painted until endFrame, so without a flush here the companions would be
+ * drawn before the features further back within the same layer (the same reason as the
+ * immediate rendering of custom type features). Once drawing is done, the frame is opened
+ * again for the features that follow.
+ *
+ * For features without companions, neither endFrame nor beginFrame is called. As long as
+ * has is false, the conventional batching efficiency is not harmed at all.
+ *
+ * @param restoreBlendState Restores the blend state that an external renderer may have
+ *   rewritten (if omitted, nothing is restored)
+ * @returns Whether even one thing was drawn
+ *
+ * @internal
+ */
+export function drawFeatureCompanionsInFrame(registry, feature, batch, projectionData, zoom, layer, context, restoreBlendState) {
+    if (!registry.any())
+        return false;
+    let drawn = false;
+    for (const provider of registry.list()) {
+        if (!provider.has(feature))
+            continue;
+        if (!drawn) {
+            batch.endFrame();
+            drawn = true;
+        }
+        provider.draw(feature, projectionData, zoom, context);
+    }
+    if (drawn) {
+        restoreBlendState?.();
+        batch.beginFrame(projectionData, zoom, layer);
+    }
+    return drawn;
+}
+/**
+ * Asks for hits on the things accompanying a feature (registration order; returns the
+ * first one that hits)
+ *
+ * @internal
+ */
+export function hitTestFeatureCompanions(registry, feature, context) {
+    if (!registry.any())
+        return null;
+    for (const provider of registry.list()) {
+        if (!provider.has(feature))
+            continue;
+        const hit = provider.hitTest(feature, context.point, context);
+        if (hit)
+            return { providerId: provider.id, featureId: feature.id, hit };
+    }
+    return null;
+}
+/**
+ * Hands a consumed click back to the provider
+ *
+ * If the provider has already been unregistered, nothing happens (the click stays
+ * consumed and the selection state does not change).
+ *
+ * @internal
+ */
+export function notifyFeatureCompanionClick(registry, result) {
+    registry.get(result.providerId)?.onCompanionClick(result.featureId, result.hit);
+}