@sakuzu/maplibre-gl-draw 1.0.0

package/dist/api/geometry/targets.js

@@ -0,0 +1,158 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+import { generateCirclePolygon } from '../../shared/math/index.js';
+import { getCircleRadius } from '../../shared/utils/property.js';
+import { getDisplayFeatures } from '../../store/local-visibility.js';
+import { isFeatureLocked } from '../../store/lock.js';
+/**
+ * Whether the feature can be a target of a boolean operation.
+ *
+ * The area types (Polygon / MultiPolygon / Circle) only. A Circle without a radius has no
+ * area, so it is excluded from the targets.
+ */
+export function isAreaFeature(feature) {
+    if (feature.type === 'Circle') {
+        const radiusMeters = getCircleRadius(feature);
+        return radiusMeters !== undefined && radiusMeters > 0;
+    }
+    return feature.type === 'Polygon' || feature.type === 'MultiPolygon';
+}
+/**
+ * Converts a feature into the area coordinates of the geometry module.
+ *
+ * A Circle is reduced to a ring with the default number of segments (64) of
+ * generateCirclePolygon, the same as in the rendering (view/renderers/drawer.ts). An input
+ * that has no area returns null.
+ */
+export function toAreaCoordinates(feature) {
+    if (feature.type === 'Circle') {
+        const radiusMeters = getCircleRadius(feature);
+        if (radiusMeters === undefined || radiusMeters <= 0)
+            return null;
+        return [generateCirclePolygon(feature.coordinates, radiusMeters)];
+    }
+    if (feature.type === 'Polygon' || feature.type === 'MultiPolygon') {
+        return feature.coordinates;
+    }
+    return null;
+}
+/**
+ * The feature types that can be the cutting side of a split.
+ *
+ * Only the types whose coordinates can be read as a polyline are accepted. The area types
+ * cannot be a "cutting line" (cutting with a polygon is the job of punching out = subtract).
+ */
+const SPLIT_LINE_TYPES = new Set([
+    'LineString',
+    'MultiLineString',
+    'Freehand',
+]);
+/**
+ * Whether the feature can be the cutting side of a split.
+ */
+export function isSplitLineFeature(feature) {
+    return SPLIT_LINE_TYPES.has(feature.type);
+}
+/**
+ * Reduces a line feature to an array of polylines.
+ *
+ * A MultiLineString becomes one polyline per part. A type that cannot be the cutting side
+ * returns an empty array.
+ */
+export function toSplitPaths(feature) {
+    if (feature.type === 'MultiLineString')
+        return feature.coordinates;
+    if (isSplitLineFeature(feature))
+        return [feature.coordinates];
+    return [];
+}
+/**
+ * The feature types that are targets of the buffer.
+ *
+ * The types that can be reduced to the GeometryInput of the geometry module, plus Circle,
+ * which is handled as a special case. The other types such as Freehand / Image / Text are
+ * excluded from the targets because the meaning of their coordinates does not match a
+ * geometry (an image is a rectangle, a text is an anchor point).
+ */
+const BUFFERABLE_TYPES = new Set([
+    'Point',
+    'MultiPoint',
+    'LineString',
+    'MultiLineString',
+    'Polygon',
+    'MultiPolygon',
+    'Circle',
+]);
+/**
+ * Whether the feature can be a target of the buffer.
+ *
+ * Only a Circle that has a radius is a target (a Circle without a radius has no starting
+ * point to grow or shrink from).
+ */
+export function isBufferableFeature(feature) {
+    if (feature.type === 'Circle') {
+        const radiusMeters = getCircleRadius(feature);
+        return radiusMeters !== undefined && radiusMeters > 0;
+    }
+    return BUFFERABLE_TYPES.has(feature.type);
+}
+/**
+ * Converts a feature into the GeometryInput of the geometry module.
+ *
+ * The shape of the coordinates matches the shape of the core Feature coordinates and is
+ * GeoJSON compatible, so it can be passed by only re-typing it. A Circle is handled as a
+ * special case (growing or shrinking the radius), so it is not converted here.
+ */
+export function toBufferGeometry(feature) {
+    switch (feature.type) {
+        case 'Point':
+        case 'MultiPoint':
+        case 'LineString':
+        case 'MultiLineString':
+        case 'Polygon':
+        case 'MultiPolygon':
+            return { type: feature.type, coordinates: feature.coordinates };
+        default:
+            return null;
+    }
+}
+/**
+ * Builds the type and coordinates of the feature to create from the MultiPolygon coordinates
+ * returned by the geometry module.
+ *
+ * Polygon when there is one part, MultiPolygon when there are several. An empty array (no
+ * area) returns null.
+ */
+export function toResultGeometry(parts) {
+    if (parts.length === 0)
+        return null;
+    if (parts.length === 1)
+        return { type: 'Polygon', coordinates: parts[0] };
+    return { type: 'MultiPolygon', coordinates: parts };
+}
+/** The IDs of the current feature selection (empty on a group or layer selection). */
+export function currentSelectionIds(store) {
+    const selection = store.getSelection();
+    return selection.type === 'feature' ? selection.ids : [];
+}
+/**
+ * Resolves the targets of an operation in z order (the head is the backmost, the tail is the
+ * frontmost).
+ *
+ * The order follows getDisplayFeatures (= getOrderedFeatures with the locally hidden features
+ * removed). That is "the order between the layers -> the order within a layer -> the
+ * featureIds within a group", which is the draw order of core itself. Hidden features (both
+ * the shared visible and the local hidden) do not appear in this list, so they are
+ * automatically excluded from the targets here.
+ * Locked features (the effective lock) are excluded explicitly.
+ *
+ * @param ids The target IDs. When undefined, the current selection
+ * @param accept The acceptance test, on the type and so on
+ */
+export function resolveTargetFeatures(store, ids, accept) {
+    const wanted = ids ?? currentSelectionIds(store);
+    if (wanted.length === 0)
+        return [];
+    const wantedIds = new Set(wanted);
+    return getDisplayFeatures(store).filter((feature) => wantedIds.has(feature.id) && accept(feature) && !isFeatureLocked(feature, store));
+}

package/dist/api/geometry/types.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The option and dependency types of the draw.geometry namespace
+ */
+import type { EventEmitter } from '../../shared/utils/event-emitter.js';
+import type { Store } from '../../store/store.js';
+/**
+ * The options of `draw.geometry.buffer` (see {@link GeometryOperations.buffer})
+ *
+ * @example
+ * ```typescript
+ * draw.geometry.buffer({ distanceMeters: 250, segments: 32 });
+ * ```
+ */
+export interface GeometryBufferOptions {
+    /**
+     * The buffer distance (in meters). A negative value shrinks (area types only); 0 or a value
+     * that is not finite does nothing
+     */
+    distanceMeters: number;
+    /**
+     * The number of segments of a full circle for the rounded parts (64 by default). It is
+     * rounded down and clamped to 3-1024
+     */
+    segments?: number;
+}
+/** The dependencies of the geometry operations (a bare Store is enough for tests) */
+export interface GeometryApiDeps {
+    store: Store;
+    eventEmitter: EventEmitter;
+    generateFeatureId: () => string;
+}

package/dist/api/geometry/types.js

@@ -0,0 +1,3 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+export {};

package/dist/api/geometry-operations.d.ts

@@ -0,0 +1,162 @@
+import type { MapLibreGLDraw } from './api.js';
+import type { GeometryApiDeps, GeometryBufferOptions } from './geometry/types.js';
+export type { GeometryApiDeps, GeometryBufferOptions } from './geometry/types.js';
+/**
+ * The geometry operations of a draw instance, reached as `draw.geometry`.
+ *
+ * When the arguments are omitted, the current feature selection is the target (a group or
+ * layer selection gives no target). Locked features (either the feature itself, the group it
+ * belongs to, or the layer it belongs to) and hidden features (by the shared visible flag or
+ * by local hiding) are excluded from the targets, and nothing happens while read-only.
+ *
+ * Each operation is one transaction, so one undo reverts it, and the result features become
+ * selected. When it ran, `draw.geometry.applied` reports the inputs and the results, with
+ * `status: 'empty'` when the result had no area and nothing changed. The computation is done
+ * by the pure functions of `@sakuzu/maplibre-gl-draw/geometry`.
+ *
+ * The boolean editing operations (union / subtract / intersect) take the area types
+ * (Polygon / MultiPolygon / Circle) and need at least two targets. They replace the inputs
+ * with one feature, a Polygon or else a MultiPolygon (a Circle becomes a 64-segment polygon
+ * first), which takes the style, the properties and the place of the frontmost input. The
+ * buffer and the split instead return an array of IDs, since they can create several
+ * features.
+ *
+ * @example
+ * ```typescript
+ * draw.on('draw.geometry.applied', ({ operation, status, resultIds }) => {
+ *   if (status === 'empty') console.log(operation, 'left nothing');
+ * });
+ * const merged = draw.geometry.union(); // the selected areas
+ * ```
+ */
+export interface GeometryOperations {
+    /**
+     * Merges the targets into a single feature.
+     *
+     * Areas that do not touch give a MultiPolygon.
+     *
+     * @param ids The IDs of the target features. When omitted, the current selection
+     * @returns The ID of the result feature. null when there are fewer than 2 targets
+     * @throws {@link geometry!GeometryError} when the computation fails on the input (a degenerate or
+     *   malformed ring, for example); nothing changes
+     *
+     * @example
+     * ```typescript
+     * const id = draw.geometry.union([parcelA, parcelB]);
+     * ```
+     */
+    union(ids?: string[]): string | null;
+    /**
+     * Punches out: subtracts the other targets from the target.
+     *
+     * When `targetId` is given it is a target even when `ids` does not list it. The result
+     * still takes the style and the properties of the frontmost input, not of the target.
+     *
+     * @param targetId The ID of the feature that is subtracted from. When omitted, the
+     *   backmost of the targets
+     * @param ids The IDs of the target features. When omitted, the current selection
+     * @returns The ID of the result feature. null when there are fewer than 2 targets or the
+     *   result is empty
+     * @throws {@link geometry!GeometryError} when the computation fails on the input; nothing changes
+     *
+     * @example
+     * ```typescript
+     * // Subtract the selected features in front from the backmost one
+     * draw.geometry.subtract();
+     * // Name the feature to subtract from
+     * draw.geometry.subtract(parcelId, [parcelId, roadId]);
+     * ```
+     */
+    subtract(targetId?: string, ids?: string[]): string | null;
+    /**
+     * Keeps the part that is common to all the targets.
+     *
+     * @param ids The IDs of the target features. When omitted, the current selection
+     * @returns The ID of the result feature. null when there are fewer than 2 targets or they
+     *   do not overlap
+     * @throws {@link geometry!GeometryError} when the computation fails on the input; nothing changes
+     *
+     * @example
+     * ```typescript
+     * const id = draw.geometry.intersect();
+     * if (id === null) {
+     *   // no overlap, or fewer than two targets
+     * }
+     * ```
+     */
+    intersect(ids?: string[]): string | null;
+    /**
+     * Creates the area within the given distance of the targets as new features.
+     *
+     * The inputs remain, and one result is created per input, just in front of it, with its
+     * style and properties. The targets are all geometries
+     * (Point / MultiPoint / LineString / MultiLineString / Polygon / MultiPolygon / Circle),
+     * and every other type is excluded from the targets. It works from a single target.
+     * A negative value (shrinking) applies to the area types only; an input that is a point or
+     * a line given a negative value produces no result, and parts of an area narrower than twice
+     * the distance disappear. A Circle stays a Circle whose radius grows or shrinks. The
+     * distance is laid out along great circles, so it holds at any latitude. A distance of 0 or
+     * one that is not finite does nothing.
+     *
+     * @param options The distance (in meters) and the number of segments
+     * @returns The IDs of the result features that were created (in z order). An empty array
+     *   when nothing was created
+     * @throws {@link geometry!GeometryError} when the computation fails on the input; nothing changes
+     *
+     * @example
+     * ```typescript
+     * // The area within 100 m of the selected features
+     * const ids = draw.geometry.buffer({ distanceMeters: 100 });
+     * // Shrink two areas by 50 m
+     * draw.geometry.buffer([parcelA, parcelB], { distanceMeters: -50 });
+     * ```
+     */
+    buffer(options: GeometryBufferOptions): string[];
+    /**
+     * Creates the area within the given distance of the named features as new features (see
+     * the other overload for the details).
+     *
+     * @param ids The IDs of the target features. When undefined, the current selection
+     * @param options The distance (in meters) and the number of segments
+     * @returns The IDs of the result features that were created (in z order). An empty array
+     *   when nothing was created
+     */
+    buffer(ids: string[] | undefined, options: GeometryBufferOptions): string[];
+    /**
+     * Cuts a polygon with a line and replaces it with the several features that result from the
+     * split.
+     *
+     * The targets are one polygon (Polygon / MultiPolygon / Circle) and one line (LineString /
+     * MultiLineString / Freehand). The side that is omitted is picked from the current
+     * selection by type; when it does not come down to exactly one of each, nothing happens and
+     * no event is emitted. The cutting line is not deleted and remains, and the results inherit
+     * the place, the style and the properties of the original polygon.
+     *
+     * When the line does not pass through the polygon (it does not intersect, it stops inside
+     * the polygon, or it only touches), nothing is changed. When the line crosses several times
+     * the polygon is split into three or more, and when only a part of a MultiPolygon is cut the
+     * parts that were not cut also become a single feature. A hole stays on the side that holds
+     * it.
+     *
+     * @param targetId The ID of the polygon feature to be cut. When omitted, the selected polygon
+     * @param lineId The ID of the line feature that cuts. When omitted, the selected line
+     * @returns The IDs of the result features that were created (in z order). An empty array
+     *   when nothing was split
+     * @throws {@link geometry!GeometryError} when the computation fails on the input; nothing changes
+     *
+     * @example
+     * ```typescript
+     * // With one area and one line selected
+     * const ids = draw.geometry.split();
+     * // Or by name
+     * draw.geometry.split(parcelId, cutLineId);
+     * ```
+     */
+    split(targetId?: string, lineId?: string): string[];
+}
+/** The `geometry` namespace on its own (what `createGeometryApi` returns) */
+export type GeometryApi = Pick<MapLibreGLDraw, 'geometry'>;
+/**
+ * Creates the draw.geometry namespace.
+ */
+export declare function createGeometryApi(deps: GeometryApiDeps): GeometryApi;

package/dist/api/geometry-operations.js

@@ -0,0 +1,94 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Geometry API (the draw.geometry namespace)
+ *
+ * Provides the boolean editing operations (union / subtract / intersect), the buffer (buffer)
+ * and the split (split) on the selected features. The computation itself lives in the pure
+ * functions of the geometry module (src/geometry); this file and api/geometry/ are the
+ * integration layer that connects the selection, the transactions, the spatial index and the
+ * events.
+ *
+ * This file holds the namespace and its entry checks. The steps live in api/geometry/.
+ *
+ *   targets.ts  which features each operation accepts, feature <-> geometry module input and
+ *               result, and resolveTargetFeatures (selection / z order / lock / hidden)
+ *   apply.ts    the common part: applyResult places one result, commitResult wraps it in one
+ *               transaction and moves the selection, emitApplied emits draw.geometry.applied
+ *   boolean.ts  union / subtract / intersect on the area types
+ *   buffer.ts   the buffer (keeps the inputs, one result per input)
+ *   split.ts    the split of a polygon by a line
+ *   types.ts    the option and dependency types
+ */
+import { differenceAll, intersectionAll, unionAll } from '../geometry/index.js';
+import { resolveSubtractInputs, runAreaOperation } from './geometry/boolean.js';
+import { runBuffer } from './geometry/buffer.js';
+import { runSplit } from './geometry/split.js';
+import { isAreaFeature, isBufferableFeature, isSplitLineFeature, resolveTargetFeatures, } from './geometry/targets.js';
+/**
+ * Creates the draw.geometry namespace.
+ */
+export function createGeometryApi(deps) {
+    const { store } = deps;
+    // While readOnly, writes to the Store become a no-op, so an operation would report results
+    // that were never created. It is rejected at the entry point.
+    const blocked = () => store.isReadOnly();
+    return {
+        geometry: {
+            union(ids) {
+                if (blocked())
+                    return null;
+                const inputs = resolveTargetFeatures(store, ids, isAreaFeature);
+                if (inputs.length < 2)
+                    return null;
+                return runAreaOperation(deps, 'union', inputs, (areas) => unionAll(areas));
+            },
+            subtract(targetId, ids) {
+                if (blocked())
+                    return null;
+                const resolved = resolveSubtractInputs(store, targetId, ids);
+                if (resolved === null)
+                    return null;
+                const { inputs, targetIndex } = resolved;
+                return runAreaOperation(deps, 'subtract', inputs, (areas) => differenceAll(areas[targetIndex], areas.filter((_, index) => index !== targetIndex)));
+            },
+            intersect(ids) {
+                if (blocked())
+                    return null;
+                const inputs = resolveTargetFeatures(store, ids, isAreaFeature);
+                if (inputs.length < 2)
+                    return null;
+                return runAreaOperation(deps, 'intersect', inputs, (areas) => intersectionAll(areas));
+            },
+            buffer(idsOrOptions, maybeOptions) {
+                // It accepts the two forms buffer(options) and buffer(ids, options).
+                const ids = Array.isArray(idsOrOptions) ? idsOrOptions : undefined;
+                const options = Array.isArray(idsOrOptions) ? maybeOptions : idsOrOptions;
+                if (blocked() || options === undefined)
+                    return [];
+                // A distance of 0 is "a copy of the original shape", a non-finite value is meaningless.
+                // The operation itself is not performed.
+                const { distanceMeters } = options;
+                if (!Number.isFinite(distanceMeters) || distanceMeters === 0)
+                    return [];
+                const inputs = resolveTargetFeatures(store, ids, isBufferableFeature);
+                // Unlike the boolean operations, it works from a single target.
+                if (inputs.length === 0)
+                    return [];
+                return runBuffer(deps, inputs, options);
+            },
+            split(targetId, lineId) {
+                if (blocked())
+                    return [];
+                // The polygon and the line are resolved separately. When omitted, both are picked from
+                // the current selection by type.
+                const areas = resolveTargetFeatures(store, targetId === undefined ? undefined : [targetId], isAreaFeature);
+                const lines = resolveTargetFeatures(store, lineId === undefined ? undefined : [lineId], isSplitLineFeature);
+                // When it does not come down to exactly one polygon and one line, nothing is done.
+                if (areas.length !== 1 || lines.length !== 1)
+                    return [];
+                return runSplit(deps, areas[0], lines[0]);
+            },
+        },
+    };
+}

package/dist/api/group-api.d.ts

@@ -0,0 +1,10 @@
+import type { AutoNameGenerator } from '../shared/utils/name-generator.js';
+import type { Store } from '../store/store.js';
+import type { MapLibreGLDraw } from './api.js';
+export type GroupApi = Pick<MapLibreGLDraw, 'getAllGroups' | 'getGroup' | 'addGroup' | 'updateGroup' | 'deleteGroup' | 'reorderInGroup' | 'addFeatureToGroup' | 'removeFeatureFromGroup' | 'groupSelection' | 'ungroupSelection' | 'ungroupGroup'>;
+export interface GroupApiDeps {
+    store: Store;
+    generateFeatureId: () => string;
+    autoNameGenerator: AutoNameGenerator;
+}
+export declare function createGroupApi(deps: GroupApiDeps): GroupApi;

package/dist/api/group-api.js

@@ -0,0 +1,78 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Group API
+ *
+ * Provides the Group CRUD and grouping operations of MapLibreGLDraw.
+ */
+import { addFeatureToGroup as addFeatureToGroupImpl, groupSelection as groupSelectionImpl, removeFeatureFromGroup as removeFeatureFromGroupImpl, ungroupGroup as ungroupGroupImpl, ungroupSelection as ungroupSelectionImpl, } from '../operations/layer-operations.js';
+import { isGroupLocked } from '../store/lock.js';
+import { onlyLockOrVisibility } from './feature-api.js';
+export function createGroupApi(deps) {
+    const { store, generateFeatureId, autoNameGenerator } = deps;
+    return {
+        getAllGroups() {
+            return store.getAllGroups();
+        },
+        getGroup(id) {
+            return store.getGroup(id);
+        },
+        addGroup(featureIds, layerId, name) {
+            // While read-only every write below would be refused: report it as null up front
+            if (store.isReadOnly())
+                return null;
+            const id = generateFeatureId();
+            const groupName = name || autoNameGenerator.generateGroupName();
+            const group = {
+                id,
+                name: groupName,
+                featureIds: [...featureIds],
+                locked: false,
+                visible: true,
+            };
+            // Remove the features from the order of the layer
+            const layer = store.getLayer(layerId);
+            if (layer) {
+                const newOrder = layer.order.filter((itemId) => !featureIds.includes(itemId));
+                // Add the group to the order
+                newOrder.push(id);
+                store.updateLayer(layerId, { order: newOrder });
+            }
+            // Create the group (this sets groupId on the features)
+            return store.createGroup(group) ? id : null;
+        },
+        updateGroup(id, updates) {
+            const group = store.getGroup(id);
+            if (group && !onlyLockOrVisibility(updates)) {
+                // While locked (itself or its layer), reject any change other than locked/visible
+                // (full protection)
+                const findLayerOfGroup = (gid) => store.getAllLayers().find((l) => l.order.includes(gid));
+                if (isGroupLocked(group, findLayerOfGroup))
+                    return false;
+            }
+            return store.updateGroup(id, updates);
+        },
+        deleteGroup(id) {
+            // The Store puts the features of the group in its place in the order of its layer
+            return store.deleteGroup(id);
+        },
+        reorderInGroup(featureId, groupId, newIndex) {
+            return store.reorderInGroup(featureId, groupId, newIndex);
+        },
+        addFeatureToGroup(featureId, groupId, index) {
+            addFeatureToGroupImpl(store, featureId, groupId, index);
+        },
+        removeFeatureFromGroup(featureId) {
+            removeFeatureFromGroupImpl(store, featureId);
+        },
+        groupSelection() {
+            return groupSelectionImpl(store, generateFeatureId, autoNameGenerator);
+        },
+        ungroupSelection() {
+            ungroupSelectionImpl(store);
+        },
+        ungroupGroup(groupId) {
+            ungroupGroupImpl(store, groupId);
+        },
+    };
+}

package/dist/api/import-export/constants.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Constants related to Import/Export
+ */
+/**
+ * Version of the native format
+ *
+ * Semantic versioning. A minor version only adds fields; a major version can change the
+ * meaning of any field, and data of another major version is rejected. 2.0.0 made the
+ * stacking order (`layerOrder`) a required part of the data.
+ */
+export declare const NATIVE_VERSION = "2.0.0";
+/** Prefix of the GeoJSON properties that hold this library's own data */
+export declare const GEOJSON_PREFIX = "maplibre-gl-draw:";
+/**
+ * The properties this library itself keeps in `Feature.properties`
+ *
+ * They are stored without a prefix in the native format, and the
+ * `maplibre-gl-draw:` prefix is added when exporting to GeoJSON. Every other property, those
+ * of the host and of extensions included, is written as a plain key. `name` and `description`
+ * are plain keys too: other GIS tools read them as the name and the description.
+ */
+export declare const LIBRARY_PROPERTIES: ReadonlySet<string>;
+/**
+ * The number of decimal places the GeoJSON export keeps in a coordinate
+ *
+ * 1e-7 degrees is about 1.1 cm at the equator, finer than any edit on the map, and it keeps
+ * the file from carrying the noise digits of floating-point arithmetic (RFC 7946, 11.2).
+ */
+export declare const GEOJSON_COORDINATE_DECIMALS = 7;

package/dist/api/import-export/constants.js

@@ -0,0 +1,40 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Constants related to Import/Export
+ */
+/**
+ * Version of the native format
+ *
+ * Semantic versioning. A minor version only adds fields; a major version can change the
+ * meaning of any field, and data of another major version is rejected. 2.0.0 made the
+ * stacking order (`layerOrder`) a required part of the data.
+ */
+export const NATIVE_VERSION = '2.0.0';
+/** Prefix of the GeoJSON properties that hold this library's own data */
+export const GEOJSON_PREFIX = 'maplibre-gl-draw:';
+/**
+ * The properties this library itself keeps in `Feature.properties`
+ *
+ * They are stored without a prefix in the native format, and the
+ * `maplibre-gl-draw:` prefix is added when exporting to GeoJSON. Every other property, those
+ * of the host and of extensions included, is written as a plain key. `name` and `description`
+ * are plain keys too: other GIS tools read them as the name and the description.
+ */
+export const LIBRARY_PROPERTIES = new Set([
+    // Common
+    'createdZoom',
+    'rotation',
+    'scale',
+    // Image
+    'imageFileId',
+    'imageWidth',
+    'imageHeight',
+]);
+/**
+ * The number of decimal places the GeoJSON export keeps in a coordinate
+ *
+ * 1e-7 degrees is about 1.1 cm at the equator, finer than any edit on the map, and it keeps
+ * the file from carrying the noise digits of floating-point arithmetic (RFC 7946, 11.2).
+ */
+export const GEOJSON_COORDINATE_DECIMALS = 7;

package/dist/api/import-export/embedded-file.d.ts

@@ -0,0 +1,13 @@
+/** An embedded image accepted for import */
+export interface EmbeddedFileContent {
+    mimeType: string;
+    dataURL: string;
+}
+/**
+ * Validates and normalizes an embedded image
+ *
+ * @param dataURL - the image data URL found in the data
+ * @param mimeType - the MIME type declared next to it
+ * @returns the content to store, or null when it is not an accepted embedded image
+ */
+export declare function normalizeEmbeddedFile(dataURL: unknown, mimeType: unknown): Promise<EmbeddedFileContent | null>;

package/dist/api/import-export/embedded-file.js

@@ -0,0 +1,31 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Validation of the image data carried by imported files
+ *
+ * Both the native format (`files[].dataURL`) and GeoJSON (`maplibre-gl-draw:imageData`) carry
+ * the pixels of an Image feature as a data URL. Only an embedded PNG / JPEG / WebP / GIF is
+ * accepted, its header must agree with the declared MIME type, and an image larger than the
+ * texture limit is scaled down here, the same as when an image file is loaded.
+ */
+import { readEmbeddedImage } from '../../shared/utils/embedded-image.js';
+import { exceedsMaxImageSize, processImageDataUrl } from '../../shared/utils/image.js';
+/**
+ * Validates and normalizes an embedded image
+ *
+ * @param dataURL - the image data URL found in the data
+ * @param mimeType - the MIME type declared next to it
+ * @returns the content to store, or null when it is not an accepted embedded image
+ */
+export async function normalizeEmbeddedFile(dataURL, mimeType) {
+    const info = readEmbeddedImage(dataURL);
+    if (!info || typeof dataURL !== 'string')
+        return null;
+    if (mimeType !== info.mimeType)
+        return null;
+    if (exceedsMaxImageSize(info.width, info.height)) {
+        const processed = await processImageDataUrl(dataURL);
+        return { mimeType: processed.mimeType, dataURL: processed.dataUrl };
+    }
+    return { mimeType: info.mimeType, dataURL };
+}

package/dist/api/import-export/file-name.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Generation of the export file name
+ */
+import type { Metadata } from '../../store/types.js';
+/**
+ * Builds the export file name
+ *
+ * Format: `{title}_{YYYY-MM-DD}_{HHMMSS}{suffix}`
+ */
+export declare function buildExportFileName(metadata: Metadata, suffix: string): string;