@sakuzu/maplibre-gl-draw 1.0.0

package/dist/operations/rotate.js

@@ -0,0 +1,166 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Rotation operation
+ *
+ * The operation that rotates features. It rotates in Web Mercator (see mercator-plane.ts),
+ * which is conformal, so the shape on the map is kept however large the feature is and however
+ * often it is rotated. The extension points of the draw instance are passed in as an argument
+ * ({@link RotateExtensions}).
+ */
+import { fromPlane, toPlane } from '../shared/math/mercator-plane.js';
+import { mapCoordinatesDeep } from '../shared/utils/coordinates.js';
+import { getImageProperties } from '../shared/utils/property.js';
+/**
+ * Decides whether a feature has a rotation property
+ *
+ * It covers Image, the custom feature types registered with resizeStrategy: 'scale' in the
+ * draw instance's registry (they rotate through the rotation property even when it is not
+ * set yet), and features that have a rotation property in properties.
+ */
+function hasRotationProperty(feature, extensions) {
+    // Image is covered explicitly
+    if (feature.type === 'Image') {
+        return true;
+    }
+    // A custom type that scales (rather than rewriting its coordinates) rotates by property
+    if (extensions?.getResizeStrategy(feature.type) === 'scale') {
+        return true;
+    }
+    // Also covers features that have a rotation property in properties
+    return (feature.properties !== null &&
+        typeof feature.properties === 'object' &&
+        'rotation' in feature.properties);
+}
+/**
+ * Gets the value of the rotation property of a feature
+ */
+function getFeatureRotation(feature) {
+    if (feature.type === 'Image') {
+        const props = getImageProperties(feature);
+        return props.rotation ?? 0;
+    }
+    const props = feature.properties;
+    return typeof props.rotation === 'number' ? props.rotation : 0;
+}
+/**
+ * Computes the angle of a point around the center (radians, counterclockwise from east, in
+ * the transform plane)
+ */
+function computeAngle(center, point) {
+    const [cx, cy] = toPlane(center);
+    const [px, py] = toPlane([point.lng, point.lat]);
+    return Math.atan2(py - cy, px - cx);
+}
+/**
+ * Rotates a coordinate around the center in the transform plane
+ */
+function rotateCoordinate(coord, center, angle) {
+    const cos = Math.cos(angle);
+    const sin = Math.sin(angle);
+    const [cx, cy] = toPlane(center);
+    const [x, y] = toPlane(coord);
+    const dx = x - cx;
+    const dy = y - cy;
+    return fromPlane(cx + dx * cos - dy * sin, cy + dx * sin + dy * cos);
+}
+/**
+ * Rotates an array of coordinates
+ *
+ * It uses a common traversal that does not depend on the nesting depth, so Multi
+ * geometries (a MultiPolygon is nested 4 levels deep) can be rotated as they are.
+ */
+function rotateCoordinates(coords, center, angle) {
+    return mapCoordinatesDeep(coords, (coord) => rotateCoordinate(coord, center, angle));
+}
+/**
+ * Computes the rotation
+ *
+ * @internal
+ */
+export function computeRotation(state, currentLngLat, features) {
+    const { startAngle, center } = state;
+    // Compute the current angle
+    const currentAngle = computeAngle(center, currentLngLat);
+    // Compute the amount of rotation
+    const deltaAngle = currentAngle - startAngle;
+    // Compute the new coordinates of each feature
+    const result = new Map();
+    // Decide whether there are only features with a rotation property (the case of a
+    // single selection where the coordinates are not changed). Which features rotate by
+    // property was decided when the rotation started (initialRotations)
+    const byProperty = (f) => state.initialRotations.has(f.id);
+    const rotationFeatures = features.filter(byProperty);
+    const otherFeatures = features.filter((f) => !byProperty(f));
+    const isSingleRotationFeature = rotationFeatures.length === 1 && otherFeatures.length === 0;
+    for (const feature of features) {
+        const initialCoords = state.initialCoordinates.get(feature.id);
+        if (!initialCoords)
+            continue;
+        if (byProperty(feature)) {
+            // For a feature that has a rotation property (Image, custom types and so on)
+            // rotation is stored in degrees (because the rendering side expects degrees)
+            const initialRotation = state.initialRotations.get(feature.id) ?? 0;
+            const deltaAngleDeg = (deltaAngle * 180) / Math.PI;
+            const newRotation = initialRotation + deltaAngleDeg;
+            if (isSingleRotationFeature) {
+                // For a single selection: leave the coordinates unchanged and change only rotation
+                result.set(feature.id, {
+                    coordinates: initialCoords,
+                    rotation: newRotation,
+                });
+            }
+            else {
+                // For a multiple selection: rotate the coordinates too, around the center
+                const newCoords = rotateCoordinates(initialCoords, center, deltaAngle);
+                result.set(feature.id, {
+                    coordinates: newCoords,
+                    rotation: newRotation,
+                });
+            }
+        }
+        else {
+            // Point, LineString, Polygon and so on: change only the coordinates
+            const newCoords = rotateCoordinates(initialCoords, center, deltaAngle);
+            result.set(feature.id, { coordinates: newCoords });
+        }
+    }
+    return result;
+}
+/**
+ * Starts the rotation operation
+ *
+ * @param extensions The draw instance's extension points (a custom type registered with
+ *   resizeStrategy: 'scale' rotates through its rotation property)
+ *
+ * @internal
+ */
+export function startRotation(startLngLat, bbox, features, extensions) {
+    const center = bbox.center;
+    const startAngle = computeAngle(center, startLngLat);
+    const initialCoordinates = new Map();
+    const initialRotations = new Map();
+    for (const feature of features) {
+        initialCoordinates.set(feature.id, JSON.parse(JSON.stringify(feature.coordinates)));
+        // For a feature that has a rotation property, store the initial rotation angle
+        if (hasRotationProperty(feature, extensions)) {
+            initialRotations.set(feature.id, getFeatureRotation(feature));
+        }
+    }
+    return {
+        startLngLat,
+        startAngle,
+        center,
+        initialCoordinates,
+        initialRotations,
+    };
+}
+/**
+ * Gets the rotation angle (for debugging)
+ *
+ * @internal
+ */
+export function getRotationDelta(state, currentLngLat) {
+    const currentAngle = computeAngle(state.center, currentLngLat);
+    return currentAngle - state.startAngle;
+}

package/dist/operations/selection-operations.d.ts

@@ -0,0 +1,20 @@
+import type { Store } from '../store/store.js';
+/**
+ * Deletes what is selected, as one change. The Delete key of the select mode and
+ * `draw.deleteSelection()` both run this.
+ *
+ * - vertices selected: deletes those vertices
+ * - feature: deletes the selected features
+ * - group: deletes the contents of the group (its features) (a group that becomes empty is
+ *   deleted automatically)
+ * - layer: deletes the layer (the features / groups under it are deleted too). At least one
+ *   layer is kept
+ *
+ * A deletion never removes a locked feature: a group loses only its unlocked members (it
+ * stays with the locked ones), and a layer that holds a locked feature or group is not
+ * deleted.
+ *
+ * @returns true when something was deleted; false while read-only or the interaction lock is
+ *   on, when nothing is selected, or when everything selected is locked
+ */
+export declare function deleteSelection(store: Store): boolean;

package/dist/operations/selection-operations.js

@@ -0,0 +1,159 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Selection operations
+ *
+ * Deletes what is selected. The Delete key of the select mode (modes/) and
+ * `draw.deleteSelection()` (api/) both call this, so the two paths delete the same things.
+ */
+import { isFeatureLocked, isGroupLocked } from '../store/lock.js';
+import { deleteVertex as deleteVertexOp, sortVertexRefsForDeletion } from './vertex.js';
+/**
+ * Deletes what is selected, as one change. The Delete key of the select mode and
+ * `draw.deleteSelection()` both run this.
+ *
+ * - vertices selected: deletes those vertices
+ * - feature: deletes the selected features
+ * - group: deletes the contents of the group (its features) (a group that becomes empty is
+ *   deleted automatically)
+ * - layer: deletes the layer (the features / groups under it are deleted too). At least one
+ *   layer is kept
+ *
+ * A deletion never removes a locked feature: a group loses only its unlocked members (it
+ * stays with the locked ones), and a layer that holds a locked feature or group is not
+ * deleted.
+ *
+ * @returns true when something was deleted; false while read-only or the interaction lock is
+ *   on, when nothing is selected, or when everything selected is locked
+ */
+export function deleteSelection(store) {
+    // Do not start a deletion while readOnly / the interaction lock is on (group and layer
+    // deletion does not go through the per-feature isFeatureLocked).
+    if (store.isReadOnly() || store.isInteractionLocked())
+        return false;
+    // Delete the vertices when vertices are selected
+    const selectedVertices = store.getSelectedVertices();
+    if (selectedVertices && selectedVertices.vertexIndices.length > 0) {
+        return deleteSelectedVertices(store, selectedVertices) > 0;
+    }
+    const selection = store.getSelection();
+    if (selection.ids.length === 0)
+        return false;
+    if (selection.type === 'feature') {
+        // Locked features (themselves / their group / their layer) are not deleted
+        const selectedIds = selection.ids.filter((id) => {
+            const feature = store.getFeature(id);
+            return feature !== undefined && !isFeatureLocked(feature, store);
+        });
+        if (selectedIds.length === 0)
+            return false;
+        store.transact(() => {
+            store.setSelection(null, []);
+            for (const id of selectedIds) {
+                store.deleteFeature(id);
+            }
+        });
+        return true;
+    }
+    if (selection.type === 'group') {
+        // Locked groups (themselves / the layer they belong to) are not deleted
+        const findLayerOfGroup = (groupId) => store.getAllLayers().find((l) => l.order.includes(groupId));
+        const groupIds = selection.ids.filter((groupId) => {
+            const group = store.getGroup(groupId);
+            return group !== undefined && !isGroupLocked(group, findLayerOfGroup);
+        });
+        if (groupIds.length === 0)
+            return false;
+        store.transact(() => {
+            store.setSelection(null, []);
+            for (const groupId of groupIds) {
+                const group = store.getGroup(groupId);
+                if (!group)
+                    continue;
+                // Delete the unlocked contents of the group. The group itself is deleted automatically
+                // the moment the last feature is removed.
+                for (const featureId of [...group.featureIds]) {
+                    const feature = store.getFeature(featureId);
+                    if (feature && isFeatureLocked(feature, store))
+                        continue;
+                    store.deleteFeature(featureId);
+                }
+                // When an empty group (a group with no contents) was selected, delete the group itself
+                // (a group that keeps locked members stays)
+                if (store.getGroup(groupId)?.featureIds.length === 0) {
+                    store.deleteGroup(groupId);
+                }
+            }
+        });
+        return true;
+    }
+    if (selection.type === 'layer') {
+        // Locked layers, and layers holding a locked feature or group, are not deleted.
+        // At least one layer is kept (prevents deleting every layer).
+        const layerIds = [...new Set(selection.ids)].filter((layerId) => {
+            const layer = store.getLayer(layerId);
+            return layer !== undefined && !layer.locked && !holdsLockedItem(store, layerId);
+        });
+        const deletable = layerIds.slice(0, Math.max(0, store.getAllLayers().length - 1));
+        if (deletable.length === 0)
+            return false;
+        store.transact(() => {
+            store.setSelection(null, []);
+            for (const layerId of deletable) {
+                store.deleteLayer(layerId);
+            }
+        });
+        return true;
+    }
+    return false;
+}
+/**
+ * Whether a layer holds a feature or a group that is locked on its own
+ */
+function holdsLockedItem(store, layerId) {
+    const layer = store.getLayer(layerId);
+    if (!layer)
+        return false;
+    for (const itemId of layer.order) {
+        const group = store.getGroup(itemId);
+        if (group?.locked)
+            return true;
+    }
+    return store.getAllFeatures().some((f) => f.layerId === layerId && isFeatureLocked(f, store));
+}
+/**
+ * Deletes the selected vertices of one feature as one change
+ *
+ * @returns The number of vertices deleted
+ */
+function deleteSelectedVertices(store, selection) {
+    const feature = store.getFeature(selection.featureId);
+    if (!feature)
+        return 0;
+    // The vertices of a locked feature are not deleted
+    if (isFeatureLocked(feature, store))
+        return 0;
+    // Within the same part and the same ring, deletion goes in descending index order
+    // (avoiding the shift caused by what was already removed. For MultiPoint the part itself
+    // disappears, so parts are in descending order too)
+    const sortedRefs = sortVertexRefsForDeletion(selection.vertexIndices);
+    // deleteVertex does not mutate its input and returns a new coordinate structure
+    // (copy-on-write), so no upfront copy is needed. Successive deletions only need the return
+    // value fed into the next input
+    let coords = feature.coordinates;
+    let deletedCount = 0;
+    for (const ref of sortedRefs) {
+        const result = deleteVertexOp({ ...feature, coordinates: coords }, ref);
+        if (result !== null) {
+            coords = result;
+            deletedCount++;
+        }
+    }
+    if (deletedCount > 0) {
+        store.transact(() => {
+            store.updateFeature(selection.featureId, { coordinates: coords });
+            store.setSelectedVertices(null);
+        });
+    }
+    return deletedCount;
+}

package/dist/operations/shared-vertex.d.ts

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

package/dist/operations/shared-vertex.js

@@ -0,0 +1,210 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Simultaneous movement of shared vertices
+ *
+ * The collection process for moving vertices that adjacent features hold at the
+ * same coordinate (shared vertices) together in a single drag. The "features that
+ * follow along and their vertex references" are fixed when the drag starts, and no
+ * further search is made afterwards (if the set changed during the drag it would
+ * interfere with other features such as snapping).
+ *
+ * The match test is an exact match with a tolerance of 0. Boundaries in GIS data
+ * are assumed to share the same coordinate values, and picking up neighbors would
+ * drag in unrelated vertices, so no rounding is applied.
+ *
+ * The targets are only the unlocked, visible features among the geometries that
+ * allow vertex editing (Point / LineString / Polygon and the Multi variants). Types
+ * without vertex movement, such as Circle / Image / Freehand, are excluded from the
+ * candidates.
+ */
+import { hasVertexRef } from '../shared/utils/vertex-ref.js';
+import { isLocallyHidden } from '../store/local-visibility.js';
+import { isFeatureLocked } from '../store/lock.js';
+import { startVertexMove } from './vertex.js';
+/**
+ * Geometry types eligible for the simultaneous movement of shared vertices
+ *
+ * They are kept identical to the types whose coordinates computeVertexMove can
+ * move.
+ */
+const VERTEX_MOVABLE_TYPES = new Set([
+    'Point',
+    'LineString',
+    'Polygon',
+    'MultiPoint',
+    'MultiLineString',
+    'MultiPolygon',
+]);
+/**
+ * Lists every vertex of a feature
+ *
+ * The end of a closed ring (the closing point) is also listed as one vertex. The
+ * match test for shared vertices is done on coordinates, so leaving out the closing
+ * point would lose track of "which of the first and the last one matched".
+ */
+function forEachVertex(feature, visit) {
+    const { type, coordinates } = feature;
+    if (type === 'Point') {
+        visit(coordinates, { ring: 0, index: 0 });
+        return;
+    }
+    if (type === 'LineString') {
+        const coords = coordinates;
+        for (let index = 0; index < coords.length; index++) {
+            visit(coords[index], { ring: 0, index });
+        }
+        return;
+    }
+    if (type === 'Polygon') {
+        visitRings(coordinates, visit);
+        return;
+    }
+    if (type === 'MultiPoint') {
+        // Each coordinate is one part. ring / index is always 0
+        const points = coordinates;
+        for (let part = 0; part < points.length; part++) {
+            visit(points[part], { part, ring: 0, index: 0 });
+        }
+        return;
+    }
+    if (type === 'MultiLineString') {
+        const parts = coordinates;
+        for (let part = 0; part < parts.length; part++) {
+            const coords = parts[part];
+            for (let index = 0; index < coords.length; index++) {
+                visit(coords[index], { part, ring: 0, index });
+            }
+        }
+        return;
+    }
+    if (type === 'MultiPolygon') {
+        const parts = coordinates;
+        for (let part = 0; part < parts.length; part++) {
+            visitRings(parts[part], visit, part);
+        }
+    }
+}
+/**
+ * Lists every vertex of an array of rings (including inner rings)
+ */
+function visitRings(rings, visit, part) {
+    for (let ring = 0; ring < rings.length; ring++) {
+        const coords = rings[ring];
+        for (let index = 0; index < coords.length; index++) {
+            visit(coords[index], part === undefined ? { ring, index } : { part, ring, index });
+        }
+    }
+}
+/**
+ * Whether the coordinates match exactly (tolerance 0)
+ */
+function isSameCoordinate(a, b) {
+    return a[0] === b[0] && a[1] === b[1];
+}
+/**
+ * Returns every vertex reference that matches one of the given coordinates exactly
+ *
+ * When a single feature has several vertices at the same coordinate (the first and
+ * the last one of a closed ring, for instance), all of them are returned.
+ *
+ * @internal
+ */
+export function findVertexRefsAt(feature, targets) {
+    const refs = [];
+    if (!VERTEX_MOVABLE_TYPES.has(feature.type))
+        return refs;
+    forEachVertex(feature, (coord, ref) => {
+        if (targets.some((target) => isSameCoordinate(coord, target))) {
+            refs.push(ref);
+        }
+    });
+    return refs;
+}
+/**
+ * Takes out the coordinates pointed to by the vertex references (duplicates removed)
+ *
+ * @internal
+ */
+export function resolveVertexCoordinates(feature, refs) {
+    const coords = [];
+    forEachVertex(feature, (coord, ref) => {
+        if (!hasVertexRef(refs, ref))
+            return;
+        if (coords.some((existing) => isSameCoordinate(existing, coord)))
+            return;
+        coords.push([coord[0], coord[1]]);
+    });
+    return coords;
+}
+/**
+ * Whether a feature can follow along with shared vertices
+ *
+ * Features under an effective lock (their own, their group's or their layer's) and
+ * hidden features are excluded. The cascade of the shared visible flag is aligned
+ * with the test in getOrderedFeatures, and local hiding with the one in
+ * getDisplayFeatures.
+ */
+function isFollowCandidate(feature, store) {
+    if (!VERTEX_MOVABLE_TYPES.has(feature.type))
+        return false;
+    if (isFeatureLocked(feature, store))
+        return false;
+    if (!feature.visible)
+        return false;
+    if (feature.groupId && !store.getGroup(feature.groupId)?.visible)
+        return false;
+    if (!store.getLayer(feature.layerId)?.visible)
+        return false;
+    return !isLocallyHidden(feature, store);
+}
+/**
+ * Fixes the targets of the simultaneous movement of shared vertices when the drag
+ * starts
+ *
+ * Candidate features are narrowed down with SpatialIndex.findNear (tolerance 0), and
+ * only the features among them that have a vertex matching the coordinate exactly
+ * are taken. No further search is made during the drag; the set fixed here keeps
+ * being used.
+ *
+ * @param feature The feature being dragged (the main one)
+ * @param vertexRefs The vertex references being dragged
+ *
+ * @internal
+ */
+export function collectSharedVertexMoves(params) {
+    const { store, spatialIndex, feature, vertexRefs, startLngLat } = params;
+    const targets = resolveVertexCoordinates(feature, vertexRefs);
+    const mainRefs = vertexRefs.map((ref) => ({ ...ref }));
+    if (targets.length === 0) {
+        return { mainRefs, followers: [] };
+    }
+    // Narrow down the candidate features with the spatial index (tolerance 0 = a point query)
+    const candidateIds = new Set();
+    for (const target of targets) {
+        for (const id of spatialIndex.findNear(target, 0)) {
+            candidateIds.add(id);
+        }
+    }
+    // Also move the vertices at the same coordinate within the main feature (the closing
+    // point of a closed ring, for instance)
+    for (const ref of findVertexRefsAt(feature, targets)) {
+        if (!hasVertexRef(mainRefs, ref))
+            mainRefs.push(ref);
+    }
+    const followers = [];
+    for (const id of candidateIds) {
+        if (id === feature.id)
+            continue;
+        const candidate = store.getFeature(id);
+        if (!candidate || !isFollowCandidate(candidate, store))
+            continue;
+        const refs = findVertexRefsAt(candidate, targets);
+        if (refs.length === 0)
+            continue;
+        const state = startVertexMove(candidate, refs, startLngLat);
+        if (state)
+            followers.push(state);
+    }
+    return { mainRefs, followers };
+}

package/dist/operations/trace-graph.d.ts

@@ -0,0 +1,96 @@
+import type { BoundingBox, Coordinate, Feature } from '../store/types.js';
+/**
+ * A connection from a node of a {@link TraceGraph} to an adjacent node, weighted by its
+ * geodesic length.
+ */
+export interface TraceGraphEdge {
+    /** The node key this edge connects to */
+    to: string;
+    /** The haversine length of the edge in meters */
+    weight: number;
+}
+/**
+ * A vertex of a {@link TraceGraph}. Vertices at exactly the same coordinate share one node.
+ */
+export interface TraceGraphNode {
+    /** The coordinate of the node, `[lng, lat]` in degrees */
+    coordinate: Coordinate;
+    /** The adjacent nodes */
+    edges: TraceGraphEdge[];
+}
+/**
+ * The undirected graph of the edges near the cursor, built by {@link buildTraceGraph} and
+ * searched by {@link findTracePath}.
+ */
+export interface TraceGraph {
+    /** The nodes by key (the key is `"lng,lat"`) */
+    nodes: Map<string, TraceGraphNode>;
+}
+/**
+ * One end of a trace: the snapping target of a click, expressed in coordinates.
+ *
+ * It holds either node (snapped to a vertex) or segment (snapped to the middle of an
+ * edge). An end point with neither (a snap to a guide or to an intersection with no
+ * reference) cannot be traced.
+ */
+export interface TraceGraphEndpoint {
+    /** The snapped coordinate `[lng, lat]` in degrees (may be in the middle of an edge) */
+    coordinate: Coordinate;
+    /** When snapped to a vertex, the coordinate of that vertex */
+    node?: Coordinate;
+    /** When snapped to the middle of an edge, the coordinates of both ends of that edge */
+    segment?: {
+        start: Coordinate;
+        end: Coordinate;
+    };
+}
+/**
+ * Builds the undirected graph of the edges of features within an extent, for
+ * {@link findTracePath}.
+ *
+ * Every segment of LineString, Polygon (holes included), MultiLineString and MultiPolygon
+ * features that touches `bbox` becomes an edge weighted by its haversine length in meters.
+ * Vertices at exactly the same coordinate share one node, so a path can cross from one
+ * feature to another through a shared vertex; edges that merely cross are not connected.
+ * Edges with the same pair of coordinates are folded into one, and edges of length 0 are
+ * skipped. Features of any other type contribute nothing. It is a pure
+ * function; it looks at neither the Store nor the map.
+ *
+ * @param features The features to build from (pass only the visible ones)
+ * @param bbox The extent in degrees; only the edges that touch it are taken in
+ * @returns The graph. It has no nodes when no edge falls in `bbox`
+ *
+ * @example
+ * ```ts
+ * import { buildTraceGraph, findTracePath } from '@sakuzu/maplibre-gl-draw';
+ *
+ * const graph = buildTraceGraph(draw.getAllFeatures(), {
+ *   minX: 139.7,
+ *   minY: 35.6,
+ *   maxX: 139.8,
+ *   maxY: 35.7,
+ * });
+ * // The boundary vertices between two vertices of the same parcel
+ * const between = findTracePath(
+ *   graph,
+ *   { coordinate: [139.71, 35.61], node: [139.71, 35.61] },
+ *   { coordinate: [139.75, 35.65], node: [139.75, 35.65] },
+ * );
+ * ```
+ */
+export declare function buildTraceGraph(features: readonly Feature[], bbox: BoundingBox): TraceGraph;
+/**
+ * Returns the boundary vertices on the shortest path between two snapped points.
+ *
+ * The search is Dijkstra over the geodesic lengths of {@link TraceGraph}. An end snapped to
+ * the middle of an edge is connected to both ends of that edge with the partial lengths;
+ * when both ends lie on the same edge they are connected directly. It is a pure function.
+ *
+ * @param graph The graph built from the nearby edges by {@link buildTraceGraph}
+ * @param from The snapping target of the click confirmed just before
+ * @param to The snapping target of this click (or of the cursor)
+ * @returns The vertices `[lng, lat]` in between, both ends excluded. An empty array when
+ *   the two ends are the same node or adjacent. `null` when an end has neither `node` nor
+ *   `segment`, when an end is not in the graph, and when the two ends are not connected
+ */
+export declare function findTracePath(graph: TraceGraph, from: TraceGraphEndpoint, to: TraceGraphEndpoint): Coordinate[] | null;