@sakuzu/maplibre-gl-draw 1.0.0

package/dist/view/globe-subdivision.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The subdivision of the geometry on the globe
+ *
+ * On the globe the vertex shaders project each vertex onto the sphere, and the GPU joins two
+ * vertices with a straight line in space: a chord through the sphere, not the path maplibre
+ * draws its own layers along (the straight line of the Mercator plane carried onto the sphere,
+ * `shared/math/globe-subdivision.ts`). So the geometry is cut finely on the Mercator plane
+ * before it is projected, as maplibre cuts its own:
+ *
+ * - Fills and their outlines are cut on the CPU, through the same subdivision as the terrain
+ *   (`terrain/tessellation.ts`), with the cell of maplibre's fill granularity. The terrain
+ *   takes precedence: while it gives a step, the globe adds nothing
+ * - Lines are cut on the GPU, by the stations of the line shader (`resolveLineStations`),
+ *   with the cell of maplibre's line granularity; the stations move along the Mercator plane
+ * - The other paths drawn on the CPU (the dashes, the selection outlines) are cut with the
+ *   line cell
+ *
+ * On a flat map nothing here is used and the geometry is exactly what it was.
+ */
+import { type GlobeSubdivisionKind } from '../shared/math/globe-subdivision.js';
+import type { Coordinate } from '../store/types.js';
+import type { TerrainContext } from './terrain/context.js';
+import { type TessellationStep } from './terrain/tessellation.js';
+/**
+ * The most points the globe adds to one fill or one path
+ *
+ * At the coarsest zoom a cell is 1/128 of the world for fills, so even a fill as large as the
+ * world is cut into about 16,000 cells. The limit only guards against a runaway; the fill
+ * subdivision coarsens the cell rather than stopping halfway when it is reached.
+ */
+export declare const GLOBE_MAX_SUBDIVISION_POINTS = 65536;
+/**
+ * Records the cells the globe asks for in this frame
+ *
+ * The globe is drawn while maplibre's projection transition is above 0 (it falls to 0 as a
+ * globe map zooms in past its switch to Mercator). The generation advances when the globe
+ * starts or stops being drawn and when a cell changes, which happens only when the zoom
+ * crosses an integer.
+ *
+ * @param context The terrain state of the draw instance
+ * @param transition `projectionTransition` of the frame's projection data (0 = Mercator)
+ * @param zoom The zoom of the camera
+ */
+export declare function updateGlobeSubdivision(context: TerrainContext, transition: number, zoom: number): void;
+/**
+ * The cell of the globe for a kind of geometry, in Mercator world units (0 on a flat map)
+ */
+export declare function globeGridOf(context: TerrainContext, kind: GlobeSubdivisionKind): number;
+/**
+ * The subdivision step of the globe (null on a flat map)
+ */
+export declare function getGlobeTessellationStep(context: TerrainContext, kind: GlobeSubdivisionKind): TessellationStep | null;
+/**
+ * The subdivision step of the surface in this frame: the terrain's when the terrain is drawn,
+ * the globe's otherwise, and null on a flat map without terrain
+ *
+ * @param context The terrain state of the draw instance
+ * @param kind Which cell of the globe applies (the terrain has one step for everything)
+ */
+export declare function getSurfaceTessellationStep(context: TerrainContext, kind: GlobeSubdivisionKind): TessellationStep | null;
+/**
+ * Subdivides the fill of one feature with the step of the surface
+ *
+ * The terrain's step goes to `tessellatePolygonFill` as before. With the globe's, a fill that
+ * lies inside one cell is left as it is: nothing in it crosses a cell, and most features of a
+ * large dataset are that small at the zooms the globe is seen at.
+ */
+export declare function tessellateSurfaceFill(context: TerrainContext, featureId: string | undefined, partIndex: number, flatCoords: number[], indices: number[], step: TessellationStep): {
+    flatCoords: number[];
+    indices: number[];
+    step: TessellationStep;
+};
+/**
+ * Cuts a path drawn on the CPU along the Mercator plane with the line cell of the globe
+ *
+ * The path itself is returned on a flat map, and when no edge is longer than a cell.
+ */
+export declare function densifyPathForGlobe(context: TerrainContext, path: Coordinate[]): Coordinate[];

package/dist/view/globe-subdivision.js

@@ -0,0 +1,128 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * The subdivision of the geometry on the globe
+ *
+ * On the globe the vertex shaders project each vertex onto the sphere, and the GPU joins two
+ * vertices with a straight line in space: a chord through the sphere, not the path maplibre
+ * draws its own layers along (the straight line of the Mercator plane carried onto the sphere,
+ * `shared/math/globe-subdivision.ts`). So the geometry is cut finely on the Mercator plane
+ * before it is projected, as maplibre cuts its own:
+ *
+ * - Fills and their outlines are cut on the CPU, through the same subdivision as the terrain
+ *   (`terrain/tessellation.ts`), with the cell of maplibre's fill granularity. The terrain
+ *   takes precedence: while it gives a step, the globe adds nothing
+ * - Lines are cut on the GPU, by the stations of the line shader (`resolveLineStations`),
+ *   with the cell of maplibre's line granularity; the stations move along the Mercator plane
+ * - The other paths drawn on the CPU (the dashes, the selection outlines) are cut with the
+ *   line cell
+ *
+ * On a flat map nothing here is used and the geometry is exactly what it was.
+ */
+import { densifyOnMercatorPlane, globeSubdivisionGrid, } from '../shared/math/globe-subdivision.js';
+import { getTerrainTessellationStep, tessellatePolygonFill } from './terrain/polygon.js';
+import { mercatorX, mercatorY } from './terrain/tessellation.js';
+/**
+ * The most points the globe adds to one fill or one path
+ *
+ * At the coarsest zoom a cell is 1/128 of the world for fills, so even a fill as large as the
+ * world is cut into about 16,000 cells. The limit only guards against a runaway; the fill
+ * subdivision coarsens the cell rather than stopping halfway when it is reached.
+ */
+export const GLOBE_MAX_SUBDIVISION_POINTS = 65536;
+/**
+ * Records the cells the globe asks for in this frame
+ *
+ * The globe is drawn while maplibre's projection transition is above 0 (it falls to 0 as a
+ * globe map zooms in past its switch to Mercator). The generation advances when the globe
+ * starts or stops being drawn and when a cell changes, which happens only when the zoom
+ * crosses an integer.
+ *
+ * @param context The terrain state of the draw instance
+ * @param transition `projectionTransition` of the frame's projection data (0 = Mercator)
+ * @param zoom The zoom of the camera
+ */
+export function updateGlobeSubdivision(context, transition, zoom) {
+    const next = transition > 0
+        ? { fill: globeSubdivisionGrid(zoom, 'fill'), line: globeSubdivisionGrid(zoom, 'line') }
+        : null;
+    const previous = context.globeGrids;
+    if (previous?.fill === next?.fill && previous?.line === next?.line)
+        return;
+    context.globeGrids = next;
+    context.globeGeneration++;
+}
+/**
+ * The cell of the globe for a kind of geometry, in Mercator world units (0 on a flat map)
+ */
+export function globeGridOf(context, kind) {
+    return context.globeGrids?.[kind] ?? 0;
+}
+/**
+ * The subdivision step of the globe (null on a flat map)
+ */
+export function getGlobeTessellationStep(context, kind) {
+    const grid = globeGridOf(context, kind);
+    if (!(grid > 0))
+        return null;
+    return { grid, maxPoints: GLOBE_MAX_SUBDIVISION_POINTS, region: null };
+}
+/**
+ * The subdivision step of the surface in this frame: the terrain's when the terrain is drawn,
+ * the globe's otherwise, and null on a flat map without terrain
+ *
+ * @param context The terrain state of the draw instance
+ * @param kind Which cell of the globe applies (the terrain has one step for everything)
+ */
+export function getSurfaceTessellationStep(context, kind) {
+    return getTerrainTessellationStep(context) ?? getGlobeTessellationStep(context, kind);
+}
+/**
+ * Subdivides the fill of one feature with the step of the surface
+ *
+ * The terrain's step goes to `tessellatePolygonFill` as before. With the globe's, a fill that
+ * lies inside one cell is left as it is: nothing in it crosses a cell, and most features of a
+ * large dataset are that small at the zooms the globe is seen at.
+ */
+export function tessellateSurfaceFill(context, featureId, partIndex, flatCoords, indices, step) {
+    if (!getTerrainTessellationStep(context) && withinOneCell(flatCoords, step.grid)) {
+        return { flatCoords, indices, step };
+    }
+    return tessellatePolygonFill(context, featureId, partIndex, flatCoords, indices, step);
+}
+/**
+ * Whether the bounding box of a flat coordinate array lies inside one cell of the grid
+ */
+function withinOneCell(flatCoords, grid) {
+    if (flatCoords.length < 2)
+        return true;
+    let minLng = Number.POSITIVE_INFINITY;
+    let maxLng = Number.NEGATIVE_INFINITY;
+    let minLat = Number.POSITIVE_INFINITY;
+    let maxLat = Number.NEGATIVE_INFINITY;
+    for (let i = 0; i < flatCoords.length; i += 2) {
+        const lng = flatCoords[i];
+        const lat = flatCoords[i + 1];
+        if (lng < minLng)
+            minLng = lng;
+        if (lng > maxLng)
+            maxLng = lng;
+        if (lat < minLat)
+            minLat = lat;
+        if (lat > maxLat)
+            maxLat = lat;
+    }
+    return (Math.floor(mercatorX(minLng) / grid) === Math.floor(mercatorX(maxLng) / grid) &&
+        Math.floor(mercatorY(maxLat) / grid) === Math.floor(mercatorY(minLat) / grid));
+}
+/**
+ * Cuts a path drawn on the CPU along the Mercator plane with the line cell of the globe
+ *
+ * The path itself is returned on a flat map, and when no edge is longer than a cell.
+ */
+export function densifyPathForGlobe(context, path) {
+    const grid = globeGridOf(context, 'line');
+    if (!(grid > 0))
+        return path;
+    return densifyOnMercatorPlane(path, grid, GLOBE_MAX_SUBDIVISION_POINTS);
+}

package/dist/view/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * View module
+ *
+ * The rendering layer of the Flux architecture.
+ * It watches the Store state and renders it with WebGL.
+ *
+ * Only the symbols that src/index.ts publishes are listed here (see "The public
+ * surface" in CONTRIBUTING.md). Internal code imports from the defining file.
+ */
+export type { CompanionHit, CompanionHitContext, FeatureCompanionHitResult, FeatureCompanionProvider, FeatureCompanionRegistry, } from './feature-companion.js';
+export { createFeatureCompanionRegistry } from './feature-companion.js';
+export type { BlendCapableGL } from './layer/blend.js';
+export { applyDrawBlendState } from './layer/blend.js';
+export type { RenderSlot } from './layer/slots.js';
+export type { DashSegment } from './renderers/line/dash.js';
+export { getStrokeDashPattern, splitIntoDashes } from './renderers/line/dash.js';
+export type { SDFLineRenderer, SDFStrokeOptions, SDFStrokeStyle, } from './renderers/line/sdf-line.js';
+export { drawBillboardsWithoutDepth } from './renderers/point/billboard-depth.js';
+export type { PointShape, PointShapeRenderer, PointStyle } from './renderers/point/point-shape.js';
+export type { FillShaderManager } from './renderers/polygon/fill.js';
+export type { Color, LineStyle, StrokeStyle, WidthUnit } from './renderers/stroke.js';
+export type { OffsetUniforms, ShaderData } from './shaders/helpers.js';
+export { calculateLngLatOffset, calculateOffsetUniforms, createProgram, getProjectionTransitionUniform, OFFSET_MODE_GLSL, } from './shaders/helpers.js';
+export type { ProjectionUniformLocations } from './shaders/projection.js';
+export { ProjectionUniformManager } from './shaders/projection.js';
+export type { QuadVertices } from './shaders/quad.js';
+export { computeQuadVertices, drawQuadSurfaceOnTerrain, QuadShader } from './shaders/quad.js';
+export type { LegendEntry, StyleRuleChannel } from './style-rule.js';
+export { applyRuleColor, deriveLegend, evaluateStyleRule, getStyleRuleChannel, resolveFeatureStyle, resolveRuleColor, } from './style-rule.js';
+export { anchorElevationMeters, getAnchorElevationGeneration } from './terrain/anchor.js';
+export type { TerrainContext, TerrainDrapeDebug, TerrainRenderState } from './terrain/context.js';
+export type { DrapeQuadCorners, QuadDrapeColor, QuadDrapeFill, QuadDrapeGlyphs, QuadDrapeSurface, } from './terrain/drape/quad.js';
+export { QUAD_GLYPH_STRIDE } from './terrain/drape/quad-glyphs.js';
+export { metersToMercatorScale } from './terrain/metrics.js';
+export { anchorGhostOpacity } from './terrain/occlusion.js';
+export { getTerrainTessellationStep } from './terrain/polygon.js';
+export type { MercatorRect, TessellationStep, TessellationTiling } from './terrain/tessellation.js';
+export { densifyPath } from './terrain/tessellation.js';
+export type { AuxiliaryHandle, AuxiliaryHandleContext, AuxiliaryHandleHit, AuxiliaryHandleProvider, AuxiliaryHandleRegistry, } from './ui/auxiliary-handles.js';
+export type { HandleInfo } from './ui/handles.js';
+export { getSelectedFeatureIds } from './ui/helper.js';
+export type { SelectionScope } from './ui/selection-scope.js';
+export { computeBoundingBox, hasZeroArea } from './ui/selection-ui/bounding-box.js';
+export type { SelectionExtensionRegistry } from './ui/selection-ui/extension-registry.js';
+export { createSelectionExtensionRegistry, DEFAULT_POINT_FRAME_SIZE, } from './ui/selection-ui/extension-registry.js';
+export type { AdditionalHandleInfo, AdditionalResizeHandlesCalculator, BoundingBoxCoords, CustomBoundingBoxCalculator, CustomResizeCalculator, PointFrameExtent, PointFrameExtentProvider, ResizeStrategy, } from './ui/selection-ui/types.js';
+export { DEFAULT_VIEWPORT_EXPANSION_FACTOR, getExpandedViewportBounds } from './viewport.js';

package/dist/view/index.js

@@ -0,0 +1,20 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+export { createFeatureCompanionRegistry } from './feature-companion.js';
+export { applyDrawBlendState } from './layer/blend.js';
+export { getStrokeDashPattern, splitIntoDashes } from './renderers/line/dash.js';
+export { drawBillboardsWithoutDepth } from './renderers/point/billboard-depth.js';
+export { calculateLngLatOffset, calculateOffsetUniforms, createProgram, getProjectionTransitionUniform, OFFSET_MODE_GLSL, } from './shaders/helpers.js';
+export { ProjectionUniformManager } from './shaders/projection.js';
+export { computeQuadVertices, drawQuadSurfaceOnTerrain, QuadShader } from './shaders/quad.js';
+export { applyRuleColor, deriveLegend, evaluateStyleRule, getStyleRuleChannel, resolveFeatureStyle, resolveRuleColor, } from './style-rule.js';
+export { anchorElevationMeters, getAnchorElevationGeneration } from './terrain/anchor.js';
+export { QUAD_GLYPH_STRIDE } from './terrain/drape/quad-glyphs.js';
+export { metersToMercatorScale } from './terrain/metrics.js';
+export { anchorGhostOpacity } from './terrain/occlusion.js';
+export { getTerrainTessellationStep } from './terrain/polygon.js';
+export { densifyPath } from './terrain/tessellation.js';
+export { getSelectedFeatureIds } from './ui/helper.js';
+export { computeBoundingBox, hasZeroArea } from './ui/selection-ui/bounding-box.js';
+export { createSelectionExtensionRegistry, DEFAULT_POINT_FRAME_SIZE, } from './ui/selection-ui/extension-registry.js';
+export { DEFAULT_VIEWPORT_EXPANSION_FACTOR, getExpandedViewportBounds } from './viewport.js';

package/dist/view/layer/attach.d.ts

@@ -0,0 +1,20 @@
+import type { CustomLayerInterface, Map as MapLibreMap } from 'maplibre-gl';
+/**
+ * Keeps the render slots of Draw on the map for as long as the returned detach function has not
+ * been called
+ *
+ * One rule covers every timing: the slots are added whenever the style accepts layers and a slot
+ * is missing. It is checked once now (for a map whose style is already parsed, even while tiles
+ * are still loading) and again on every `styledata` event. maplibre fires `styledata` when a
+ * style finishes loading (before `style.load` and `load`) and after changes to the style, so the
+ * slots are also restored after `setStyle`, including a diffed `setStyle` that drops layers it
+ * does not know. A slot that is already on the map is never added twice.
+ *
+ * The slots are added in order from the first (the backmost), which lines them up in the same
+ * order in maplibre (layers added later are on top).
+ *
+ * @param map The map
+ * @param getSlotLayers Returns the current list of slots (first = backmost)
+ * @returns A function that stops watching the style (it does not remove the layers)
+ */
+export declare function attachSlotLayers(map: MapLibreMap, getSlotLayers: () => readonly CustomLayerInterface[]): () => void;

package/dist/view/layer/attach.js

@@ -0,0 +1,47 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Whether the style of the map accepts new layers right now
+ *
+ * This is the same condition that maplibre checks in `map.addLayer` (the style has finished
+ * parsing its stylesheet). It is deliberately not `map.loaded()` or `map.isStyleLoaded()`: those
+ * are also false while tiles, sprites or images are loading, which happens after every pan or
+ * zoom, although layers can be added at that time.
+ */
+function styleAcceptsLayers(map) {
+    return map.style?._loaded === true;
+}
+/**
+ * Keeps the render slots of Draw on the map for as long as the returned detach function has not
+ * been called
+ *
+ * One rule covers every timing: the slots are added whenever the style accepts layers and a slot
+ * is missing. It is checked once now (for a map whose style is already parsed, even while tiles
+ * are still loading) and again on every `styledata` event. maplibre fires `styledata` when a
+ * style finishes loading (before `style.load` and `load`) and after changes to the style, so the
+ * slots are also restored after `setStyle`, including a diffed `setStyle` that drops layers it
+ * does not know. A slot that is already on the map is never added twice.
+ *
+ * The slots are added in order from the first (the backmost), which lines them up in the same
+ * order in maplibre (layers added later are on top).
+ *
+ * @param map The map
+ * @param getSlotLayers Returns the current list of slots (first = backmost)
+ * @returns A function that stops watching the style (it does not remove the layers)
+ */
+export function attachSlotLayers(map, getSlotLayers) {
+    const ensureSlots = () => {
+        if (!styleAcceptsLayers(map))
+            return;
+        for (const slotLayer of getSlotLayers()) {
+            if (!map.getLayer(slotLayer.id)) {
+                map.addLayer(slotLayer);
+            }
+        }
+    };
+    map.on('styledata', ensureSlots);
+    ensureSlots();
+    return () => {
+        map.off('styledata', ensureSlots);
+    };
+}

package/dist/view/layer/blend.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Blend state (alpha blending) for our own rendering
+ *
+ * The fragment shader of every renderer outputs a color that is not premultiplied by alpha.
+ * RGB therefore composites correctly with `SRC_ALPHA` / `ONE_MINUS_SRC_ALPHA`.
+ *
+ * The maplibre canvas, on the other hand, uses `premultipliedAlpha` (the WebGL default), so the
+ * alpha component of the destination represents the opacity of everything composited so far.
+ * Applying the same factors as RGB to it gives
+ *
+ *   dst.a = a × a + (1 - a) × dst.a
+ *
+ * which squares the alpha alone. A 25% fill drops to 6.25%, and where the destination alpha is 0
+ * (where the canvas is still transparent) it almost disappears when the canvas itself is
+ * composited. This is the 2026-08-10 bug where only the fill of a drawn feature vanished in the
+ * print preview while its outline (opaque) remained.
+ *
+ * Set the factor of the alpha component alone to `ONE` so that the correct over composition
+ *
+ *   dst.a = a + (1 - a) × dst.a
+ *
+ * is used. The RGB equation is exactly the same as before, so the appearance where the
+ * destination is opaque does not change.
+ *
+ * This state is a contract for the whole frame, and CustomLayer sets it once at the entry point
+ * of rendering. Handing control to an external renderer (a renderer for a custom feature type or
+ * an overlay renderer) may overwrite it in the middle of a frame, so call this function again at
+ * the point control comes back to re-establish the contract
+ * (rendering.md, "Ownership of the blend state").
+ */
+/**
+ * The part of a WebGL context {@link applyDrawBlendState} uses; a `WebGL2RenderingContext`
+ * satisfies it.
+ */
+export interface BlendCapableGL {
+    /** The `BLEND` capability constant */
+    BLEND: number;
+    /** The `ONE` blend factor constant */
+    ONE: number;
+    /** The `SRC_ALPHA` blend factor constant */
+    SRC_ALPHA: number;
+    /** The `ONE_MINUS_SRC_ALPHA` blend factor constant */
+    ONE_MINUS_SRC_ALPHA: number;
+    /** Enables a capability */
+    enable(cap: number): void;
+    /** Sets the RGB and alpha blend factors separately */
+    blendFuncSeparate(srcRGB: number, dstRGB: number, srcAlpha: number, dstAlpha: number): void;
+}
+/**
+ * Restores the blend state the library's renderers expect: blending on, straight alpha for
+ * RGB and `ONE` / `ONE_MINUS_SRC_ALPHA` for alpha.
+ *
+ * A custom renderer that changes the blend state calls it before handing control back.
+ *
+ * @param gl The WebGL context of the map
+ */
+export declare function applyDrawBlendState(gl: BlendCapableGL): void;

package/dist/view/layer/blend.js

@@ -0,0 +1,14 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Restores the blend state the library's renderers expect: blending on, straight alpha for
+ * RGB and `ONE` / `ONE_MINUS_SRC_ALPHA` for alpha.
+ *
+ * A custom renderer that changes the blend state calls it before handing control back.
+ *
+ * @param gl The WebGL context of the map
+ */
+export function applyDrawBlendState(gl) {
+    gl.enable(gl.BLEND);
+    gl.blendFuncSeparate(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA, gl.ONE, gl.ONE_MINUS_SRC_ALPHA);
+}

package/dist/view/layer/custom-layer.d.ts

@@ -0,0 +1 @@
+export {};