@sakuzu/maplibre-gl-draw 1.0.0 → 2.0.0

package/dist/api/{import-export → impl/import-export}/geojson-import.js

@@ -1,15 +1,13 @@
 // SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
 // SPDX-License-Identifier: AGPL-3.0-only
-/**
- * Conversion from GeoJSON to the internal Feature format + load of a
- * GeoJSON FeatureCollection
- */
-import { createId } from '../../shared/utils/id.js';
-import { GEOJSON_PREFIX, LIBRARY_PROPERTIES } from './constants.js';
+import { DRAW_PROPERTY_NAMES, DRAW_PROPERTY_PREFIX, drawPropertyKey, hasDrawProperty, setDrawProperty, } from '../../../shared/properties.js';
+import { createId } from '../../../shared/utils/id.js';
+import { DrawError } from '../../errors.js';
 import { normalizeEmbeddedFile } from './embedded-file.js';
 import { COORDINATE_DEPTH, describeCoordinateProblem } from './geometry-validation.js';
+import { foldLegacyImageStyle } from './legacy-image-style.js';
 import { setOwnProperty } from './own-property.js';
-import { isHexColor, sanitizeFeatureStyle } from './style-validation.js';
+import { isCssColor, sanitizeFeatureStyle } from './style-validation.js';
 /**
  * Converts a single geometry (Point/LineString/Polygon) into the Feature format
  */
@@ -28,7 +26,7 @@ function convertSingleGeometry(geometry, meta, userProperties, featureType, file
         case 'Point': {
             const type = resolveFeatureType('Point', featureType);
             return {
-                feature: { ...base, type, coordinates: geometry.coordinates },
+                feature: { ...base, type, geometry },
                 // The embedded image belongs only to a feature that really is an Image
                 fileData: type === 'Image' ? fileData : undefined,
             };
@@ -39,19 +37,16 @@ function convertSingleGeometry(geometry, meta, userProperties, featureType, file
             // (this pairs with the default branch on export).
             const type = resolveFeatureType('LineString', featureType);
             return {
-                feature: {
-                    ...base,
-                    type,
-                    coordinates: geometry.coordinates,
-                },
+                feature: { ...base, type, geometry },
             };
         }
         case 'Polygon':
+            // A custom type whose geometry is an area comes back from its marker as the others do
             return {
                 feature: {
                     ...base,
-                    type: 'Polygon',
-                    coordinates: geometry.coordinates,
+                    type: resolveFeatureType('Polygon', featureType),
+                    geometry,
                 },
             };
         default:
@@ -64,7 +59,7 @@ function convertSingleGeometry(geometry, meta, userProperties, featureType, file
  * The parts are kept as they are instead of being split, so that properties are not
  * duplicated.
  */
-function convertMultiGeometry(geometry, meta, userProperties) {
+function convertMultiGeometry(geometry, meta, userProperties, featureType) {
     if (geometry.coordinates.length === 0)
         return null;
     return [
@@ -77,8 +72,8 @@ function convertMultiGeometry(geometry, meta, userProperties) {
                 style: meta.style,
                 locked: meta.locked,
                 visible: meta.visible,
-                type: geometry.type,
-                coordinates: geometry.coordinates,
+                type: resolveFeatureType(geometry.type, featureType),
+                geometry,
             },
         },
     ];
@@ -164,7 +159,7 @@ function convertGeometryCollection(geometry, meta, userProperties, generateFeatu
                 locked: meta.locked,
                 visible: meta.visible,
                 type,
-                coordinates,
+                geometry: { type, coordinates },
             },
         });
     };
@@ -187,14 +182,15 @@ const GEOMETRY_TYPE_NAMES = new Set([
     'geometrycollection',
 ]);
 /**
- * Resolves the feature type of a Point or LineString from the featureType marker
+ * Resolves the feature type of a geometry from the featureType marker
  *
  * The marker restores a type that GeoJSON has no geometry for (Image, Circle, Freehand and
- * custom types). The export writes the type name as it is, and the marker is read as that exact
- * name. It is used only when it is a non-empty string, does not name a GeoJSON geometry type
- * (in any letter case), and names a type whose coordinates have the shape of the geometry.
- * Anything else is ignored and the geometry type is kept, so the marker can never pair a type
- * with coordinates of another shape.
+ * custom types, whatever their geometry). The export writes the type name as it is, and the
+ * marker is read as that exact name: it wins over the kind of the geometry. It is used only
+ * when it is a non-empty string, does not name a GeoJSON geometry type (in any letter case),
+ * and does not name a built-in type whose coordinates have another shape. Anything else is
+ * ignored and the geometry type is kept, so the marker can never pair a built-in type with
+ * coordinates of another shape.
  */
 function resolveFeatureType(geometryType, marker) {
     if (typeof marker !== 'string' || marker === '')
@@ -202,9 +198,13 @@ function resolveFeatureType(geometryType, marker) {
     if (GEOMETRY_TYPE_NAMES.has(marker.toLowerCase()))
         return geometryType;
     const expectedDepth = COORDINATE_DEPTH[marker];
-    const actualDepth = geometryType === 'Point' ? 0 : 1;
+    const actualDepth = COORDINATE_DEPTH[geometryType];
     return expectedDepth === undefined || expectedDepth === actualDepth ? marker : geometryType;
 }
+/** The keys of `properties` that hold the values of this library */
+const LIBRARY_KEYS = new Set(DRAW_PROPERTY_NAMES.map((name) => drawPropertyKey(name)));
+/** The values of a Circle that an earlier export wrote without the prefix */
+const LEGACY_CIRCLE_PROPERTIES = ['radiusMeters', 'radiusHandleAngle'];
 /** The geometry types the import converts */
 const SUPPORTED_GEOMETRY_TYPES = new Set([
     'Point',
@@ -286,7 +286,7 @@ function simplestyleToFeatureStyle(properties) {
     let found = false;
     const copyString = (key, target) => {
         const value = properties[key];
-        if (isHexColor(value)) {
+        if (isCssColor(value)) {
             style[target] = value;
             found = true;
         }
@@ -333,7 +333,7 @@ export function convertGeoJSONToFeature(geoFeature, layerId, generateFeatureId,
     // form, and anything else gets a new id. The prefixed property takes precedence, then the
     // standard id member of the Feature. Whether it collides with existing data is resolved by
     // the caller, which knows the store.
-    const prefixedId = properties?.[`${GEOJSON_PREFIX}id`];
+    const prefixedId = properties?.[`${DRAW_PROPERTY_PREFIX}id`];
     const rawId = prefixedId === undefined || prefixedId === null || prefixedId === ''
         ? geoFeature.id
         : prefixedId;
@@ -342,54 +342,65 @@ export function convertGeoJSONToFeature(geoFeature, layerId, generateFeatureId,
         : typeof rawId === 'number' && Number.isFinite(rawId)
             ? String(rawId)
             : generateFeatureId();
-    const rawLayerId = properties?.[`${GEOJSON_PREFIX}layerId`];
+    const rawLayerId = properties?.[`${DRAW_PROPERTY_PREFIX}layerId`];
     const featureLayerId = typeof rawLayerId === 'string' && rawLayerId !== '' ? rawLayerId : layerId;
-    const rawGroupId = properties?.[`${GEOJSON_PREFIX}groupId`];
+    const rawGroupId = properties?.[`${DRAW_PROPERTY_PREFIX}groupId`];
     const groupId = typeof rawGroupId === 'string' && rawGroupId !== '' ? rawGroupId : undefined;
     // The round-trip style key takes precedence; only when it is absent is the style built
     // from simplestyle-spec (they are not merged). Either way the keys are validated.
-    const roundTripStyle = properties?.[`${GEOJSON_PREFIX}style`];
-    const style = roundTripStyle !== undefined && roundTripStyle !== null
+    const roundTripStyle = properties?.[`${DRAW_PROPERTY_PREFIX}style`];
+    const style = (roundTripStyle !== undefined && roundTripStyle !== null
         ? sanitizeFeatureStyle(roundTripStyle)
-        : simplestyleToFeatureStyle(properties);
-    const featureType = properties?.[`${GEOJSON_PREFIX}featureType`];
+        : simplestyleToFeatureStyle(properties)) ?? {};
+    const featureType = properties?.[`${DRAW_PROPERTY_PREFIX}featureType`];
     // visible is hidden only when it is explicitly false, and locked is treated as locked
     // only when it is explicitly true
-    const visible = properties?.[`${GEOJSON_PREFIX}visible`] !== false;
-    const locked = properties?.[`${GEOJSON_PREFIX}locked`] === true;
+    const visible = properties?.[`${DRAW_PROPERTY_PREFIX}visible`] !== false;
+    const locked = properties?.[`${DRAW_PROPERTY_PREFIX}locked`] === true;
     // Extract the embedded image data. It is taken only for a single point that really is an
     // Image.
-    const imageData = properties?.[`${GEOJSON_PREFIX}imageData`];
-    const imageMimeType = properties?.[`${GEOJSON_PREFIX}imageMimeType`];
+    const imageData = properties?.[`${DRAW_PROPERTY_PREFIX}imageData`];
+    const imageMimeType = properties?.[`${DRAW_PROPERTY_PREFIX}imageMimeType`];
     const embedsImage = Boolean(imageData && imageMimeType) &&
         geometry.type === 'Point' &&
         resolveFeatureType('Point', featureType) === 'Image';
     // Extract the properties
     // - without a prefix: added as is as a user-defined property
-    // - with a prefix and one of this library's own properties: added with the prefix stripped
+    // - with a prefix and one of this library's own values: added as is
     // - any other prefixed key (id, layerId, style, visible, locked and so on): excluded
     //   (they are handled separately)
     // Keys are defined as own properties so that a `__proto__` key stays an ordinary key.
     const userProperties = {};
     if (properties) {
         for (const [key, value] of Object.entries(properties)) {
-            if (key.startsWith(GEOJSON_PREFIX)) {
-                const keyWithoutPrefix = key.slice(GEOJSON_PREFIX.length);
-                if (LIBRARY_PROPERTIES.has(keyWithoutPrefix)) {
-                    // When there is image data, imageFileId is replaced with a new ID, so it is
-                    // not added here
-                    if (keyWithoutPrefix !== 'imageFileId' || !embedsImage) {
-                        setOwnProperty(userProperties, keyWithoutPrefix, value);
-                    }
+            if (key.startsWith(DRAW_PROPERTY_PREFIX)) {
+                // When there is image data, imageFileId is replaced with a new ID, so it is not
+                // added here. Anything else that is not a value of this library (id, layerId, style,
+                // featureType, visible, locked, imageData and so on) is excluded
+                if (LIBRARY_KEYS.has(key) && (key !== drawPropertyKey('imageFileId') || !embedsImage)) {
+                    setOwnProperty(userProperties, key, value);
                 }
-                // Anything else (id, layerId, style, featureType, visible, locked, imageData and
-                // so on) is excluded
             }
             else {
                 setOwnProperty(userProperties, key, value);
             }
         }
     }
+    // An earlier export wrote the radius of a Circle and the direction of its handle without
+    // the prefix; they are read as the values of this library when the prefixed ones are absent
+    if (geometry.type === 'Point' && resolveFeatureType('Point', featureType) === 'Circle') {
+        for (const name of LEGACY_CIRCLE_PROPERTIES) {
+            if (userProperties[name] !== undefined && !hasDrawProperty(userProperties, name)) {
+                setOwnProperty(userProperties, drawPropertyKey(name), userProperties[name]);
+                delete userProperties[name];
+            }
+        }
+    }
+    // The style of an Image written by an earlier export can carry its size, a rotation and an
+    // opacity of its own; they are read as the values of this library and imageOpacity
+    if (geometry.type === 'Point' && resolveFeatureType('Point', featureType) === 'Image') {
+        foldLegacyImageStyle(userProperties, style);
+    }
     // When there is image data on a single Image point, create the FileData and set a new
     // imageFileId
     let fileData;
@@ -400,7 +411,7 @@ export function convertGeoJSONToFeature(geoFeature, layerId, generateFeatureId,
             mimeType: imageMimeType,
             dataURL: imageData,
         };
-        userProperties.imageFileId = newFileId;
+        setDrawProperty(userProperties, 'imageFileId', newFileId);
     }
     const meta = {
         id,
@@ -420,17 +431,17 @@ export function convertGeoJSONToFeature(geoFeature, layerId, generateFeatureId,
             }
             case 'MultiPoint':
                 if (!flattenMulti) {
-                    return convertMultiGeometry(geometry, meta, userProperties);
+                    return convertMultiGeometry(geometry, meta, userProperties, featureType);
                 }
                 return flattenMultiGeometry(geometry.coordinates, (coords) => ({ type: 'Point', coordinates: coords }), generateFeatureId, meta, userProperties, featureType, fileData);
             case 'MultiLineString':
                 if (!flattenMulti) {
-                    return convertMultiGeometry(geometry, meta, userProperties);
+                    return convertMultiGeometry(geometry, meta, userProperties, featureType);
                 }
                 return flattenMultiGeometry(geometry.coordinates, (coords) => ({ type: 'LineString', coordinates: coords }), generateFeatureId, meta, userProperties, undefined, undefined);
             case 'MultiPolygon':
                 if (!flattenMulti) {
-                    return convertMultiGeometry(geometry, meta, userProperties);
+                    return convertMultiGeometry(geometry, meta, userProperties, featureType);
                 }
                 return flattenMultiGeometry(geometry.coordinates, (coords) => ({ type: 'Polygon', coordinates: coords }), generateFeatureId, meta, userProperties, undefined, undefined);
             case 'GeometryCollection':
@@ -447,15 +458,20 @@ export function convertGeoJSONToFeature(geoFeature, layerId, generateFeatureId,
 /** How many times a colliding feature id is regenerated before the import gives up */
 const MAX_ID_ATTEMPTS = 1000;
 /**
- * Imports a GeoJSON FeatureCollection (adds to the existing data)
+ * Reads a GeoJSON FeatureCollection for a load that adds to the existing data (or replaces
+ * the features and groups): the features are converted and checked and the embedded images
+ * decoded here, and the writes are left to the transaction of the caller. The IDs and the
+ * references to layers and groups are resolved when the features are written, against the
+ * document as it is then (another load of the same transaction may have changed it).
  */
-export async function loadGeoJSON(data, deps, options) {
+export async function prepareGeoJSON(data, deps, options) {
     const { store, autoNameGenerator, generateFeatureId, getCurrentLayerId } = deps;
     const layerId = getCurrentLayerId();
     const generateFileId = () => createId();
-    // 1. Validate, convert and resolve everything before writing. store.transact does not roll
-    //    back, so nothing may throw once the writing has started. A feature that cannot be
-    //    imported is skipped with its reason instead of rejecting the whole load.
+    // 1. Validate and convert everything, and decode the embedded images, before writing.
+    //    store.transact does not roll back, so nothing may throw once the writing has started. A
+    //    feature that cannot be imported is skipped with its reason instead of rejecting the
+    //    whole load.
     const results = [];
     const skipped = [];
     data.features.forEach((geoFeature, index) => {
@@ -467,33 +483,6 @@ export async function loadGeoJSON(data, deps, options) {
             results.push(...converted.results);
         }
     });
-    // Feature and group IDs share the entries of layer.order, so an id taken by either (or by
-    // an earlier feature of this import) is replaced with a new one. This is what makes a
-    // GeoJSON exported from a store loadable into the same store again.
-    const takenIds = new Set();
-    const isTaken = (id) => takenIds.has(id) || store.getFeature(id) !== undefined || store.getGroup(id) !== undefined;
-    const resolveId = (id) => {
-        let resolved = id;
-        for (let attempt = 0; isTaken(resolved); attempt++) {
-            if (attempt >= MAX_ID_ATTEMPTS) {
-                throw new Error('Failed to generate a unique feature id for the GeoJSON import');
-            }
-            resolved = generateFeatureId();
-        }
-        takenIds.add(resolved);
-        return resolved;
-    };
-    for (const { feature } of results) {
-        feature.id = resolveId(feature.id);
-        // References are resolved against this store: a layer it does not have falls back to
-        // the current layer, and a group it does not have is dropped (a feature pointing at a
-        // missing group would belong to no layer order and never be drawn).
-        if (!store.getLayer(feature.layerId))
-            feature.layerId = layerId;
-        if (feature.groupId !== undefined && !store.getGroup(feature.groupId)) {
-            delete feature.groupId;
-        }
-    }
     // Embedded images are accepted only as PNG / JPEG / WebP / GIF data URLs, and an oversized
     // one is scaled down. Unlike a malformed geometry, a bad image rejects the whole load: the
     // image fields are written only by this library's export, so a bad one means the file was
@@ -503,16 +492,67 @@ export async function loadGeoJSON(data, deps, options) {
             continue;
         const content = await normalizeEmbeddedFile(result.fileData.dataURL, result.fileData.mimeType);
         if (!content) {
-            throw new Error(`Invalid GeoJSON: the image data of feature "${result.feature.id}" is not an embedded ` +
+            throw new DrawError('invalid-input', `Invalid GeoJSON: the image data of feature "${result.feature.id}" is not an embedded ` +
                 'PNG / JPEG / WebP / GIF data URL of its declared type');
         }
         result.fileData = { ...result.fileData, ...content };
     }
-    // 2. Write. Written with batch: the whole import is one notification, one step for a
-    //    subscriber that records changes. Hosts that rebuild a view should subscribe to the
-    //    per-flush `features.change` event rather than the per-feature events.
-    const featureIds = [];
-    store.transact(() => {
+    const replace = options?.replace === true;
+    // 2. The writes, in the transaction of the caller, the deletion of a replace included: the
+    //    whole import is one notification, one step for a subscriber that records changes
+    const write = () => {
+        const currentLayerId = getCurrentLayerId();
+        if (replace) {
+            for (const feature of store.listFeatures())
+                store.deleteFeature(feature.id);
+            for (const group of store.listGroups())
+                store.deleteGroup(group.id);
+        }
+        // Feature and group IDs share the entries of layer.order, so an id taken by either (or by
+        // an earlier feature of this import) is replaced with a new one. This is what makes a
+        // GeoJSON exported from a store loadable into the same store again.
+        // With replace, the features and groups of the document are gone by the time the new ones
+        // are written, so only the IDs of this import can collide
+        const takenIds = new Set();
+        const isTaken = (id) => takenIds.has(id) ||
+            options?.reservedIds?.has(id) === true ||
+            (!replace && (store.getFeature(id) !== undefined || store.getGroup(id) !== undefined));
+        const resolveId = (id) => {
+            let resolved = id;
+            for (let attempt = 0; isTaken(resolved); attempt++) {
+                if (attempt >= MAX_ID_ATTEMPTS) {
+                    throw new DrawError('invalid-input', 'Failed to generate a unique feature id for the GeoJSON import');
+                }
+                resolved = generateFeatureId();
+            }
+            takenIds.add(resolved);
+            return resolved;
+        };
+        const forcedLayerId = options?.layerId;
+        const oneGroup = options?.oneGroup === true;
+        for (const { feature } of results) {
+            feature.id = resolveId(feature.id);
+            // References are resolved against this store: a layer given to the load wins over the one
+            // the feature names, a layer the store does not have falls back to the current layer, and a
+            // group it does not have (or a group of another layer, or any group when the groups are
+            // replaced) is dropped: a feature pointing at a missing group would belong to no layer
+            // order and never be drawn.
+            if (forcedLayerId !== undefined && store.getLayer(forcedLayerId)) {
+                feature.layerId = forcedLayerId;
+            }
+            else if (forcedLayerId !== undefined || oneGroup || !store.getLayer(feature.layerId)) {
+                feature.layerId = currentLayerId;
+            }
+            // The features of a load that makes a group of them leave the group they name
+            if (oneGroup)
+                delete feature.groupId;
+            if (feature.groupId !== undefined) {
+                const group = replace ? undefined : store.getGroup(feature.groupId);
+                if (!group || group.layerId !== feature.layerId)
+                    delete feature.groupId;
+            }
+        }
+        const featureIds = [];
         for (const result of results) {
             // When there is image data, add the file first
             if (result.fileData) {
@@ -528,11 +568,13 @@ export async function loadGeoJSON(data, deps, options) {
             store.createFeature(result.feature);
             featureIds.push(result.feature.id);
         }
-    }, 'batch');
-    return {
-        format: 'geojson',
-        featureIds,
-        replaced: false,
-        skipped,
+        const loaded = {
+            format: 'geojson',
+            featureIds,
+            replaced: replace,
+            skipped,
+        };
+        return loaded;
     };
+    return { write };
 }

package/dist/api/{import-export → impl/import-export}/geometry-validation.d.ts

@@ -18,3 +18,17 @@ export declare const COORDINATE_DEPTH: Readonly<Record<string, number>>;
  *   null
  */
 export declare function describeCoordinateProblem(type: string, coordinates: unknown): string | null;
+/**
+ * Returns why a GeoJSON geometry cannot be used for a feature of the type, or null when it
+ * can
+ *
+ * The geometry must be an object of one of the six kinds with coordinates (a
+ * GeometryCollection is not a geometry of a feature), a built-in type must hold its own kind
+ * (a Circle and an Image a Point, a Freehand a LineString), and the coordinates must pass
+ * {@link describeCoordinateProblem} for the kind. A custom type may hold any of the kinds.
+ *
+ * @param type - the feature type
+ * @param geometry - the geometry to check
+ * @returns a short phrase that reads after "has", or null
+ */
+export declare function describeGeometryProblem(type: string, geometry: unknown): string | null;

package/dist/api/{import-export → impl/import-export}/geometry-validation.js

@@ -1,5 +1,13 @@
 // SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
 // SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Validation of feature coordinates at the import boundary
+ *
+ * Both imports (the native format and GeoJSON) check coordinates with the same rules before
+ * anything is written, so that malformed geometry never reaches the store, the spatial index
+ * or the renderers. The rules follow docs/reference/data-format.md.
+ */
+import { builtInGeometryKind } from '../../../shared/utils/coordinates.js';
 /**
  * The nesting depth of the coordinates of each built-in feature type
  * (0 = a single position, 1 = a sequence of positions, and so on).
@@ -105,3 +113,40 @@ export function describeCoordinateProblem(type, coordinates) {
             return null;
     }
 }
+/** The kinds of GeoJSON geometry a feature can hold */
+const GEOMETRY_KINDS = new Set([
+    'Point',
+    'LineString',
+    'Polygon',
+    'MultiPoint',
+    'MultiLineString',
+    'MultiPolygon',
+]);
+/**
+ * Returns why a GeoJSON geometry cannot be used for a feature of the type, or null when it
+ * can
+ *
+ * The geometry must be an object of one of the six kinds with coordinates (a
+ * GeometryCollection is not a geometry of a feature), a built-in type must hold its own kind
+ * (a Circle and an Image a Point, a Freehand a LineString), and the coordinates must pass
+ * {@link describeCoordinateProblem} for the kind. A custom type may hold any of the kinds.
+ *
+ * @param type - the feature type
+ * @param geometry - the geometry to check
+ * @returns a short phrase that reads after "has", or null
+ */
+export function describeGeometryProblem(type, geometry) {
+    if (typeof geometry !== 'object' || geometry === null || Array.isArray(geometry)) {
+        return 'no geometry object';
+    }
+    const { type: kind, coordinates } = geometry;
+    if (typeof kind !== 'string' || !GEOMETRY_KINDS.has(kind)) {
+        return `a geometry of the unsupported type "${String(kind)}"`;
+    }
+    const expected = builtInGeometryKind(type);
+    if (expected !== undefined && kind !== expected) {
+        return `a ${kind} geometry that does not match the type ${type}`;
+    }
+    const problem = describeCoordinateProblem(kind, coordinates);
+    return problem ? `a ${kind} geometry with ${problem}` : null;
+}

package/dist/api/impl/import-export/image-import.d.ts

@@ -0,0 +1,16 @@
+import type { AutoNameGenerator } from '../../../shared/utils/name-generator.js';
+import type { Store } from '../../../store/store.js';
+import type { LoadOptions } from '../../../store/types.js';
+import type { PreparedLoad } from './types.js';
+/**
+ * Decodes an image file for a load that creates an Image feature; the writes are left to the
+ * transaction of the caller
+ *
+ * @param beforeWrite - Runs first when the image is written, such as the deletion of a replace
+ */
+export declare function prepareImage(file: File, options: LoadOptions, deps: {
+    store: Store;
+    autoNameGenerator: AutoNameGenerator;
+    generateFeatureId: () => string;
+    getCurrentLayerId: () => string;
+}, beforeWrite?: () => void): Promise<PreparedLoad>;

package/dist/api/impl/import-export/image-import.js

@@ -0,0 +1,73 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Import of image files (creates an Image feature)
+ */
+import { drawProperties } from '../../../shared/properties.js';
+import { processImageFile } from '../../../shared/utils/image.js';
+import { DrawError } from '../../errors.js';
+/**
+ * Decodes an image file for a load that creates an Image feature; the writes are left to the
+ * transaction of the caller
+ *
+ * @param beforeWrite - Runs first when the image is written, such as the deletion of a replace
+ */
+export async function prepareImage(file, options, deps, beforeWrite) {
+    const coordinate = options.coordinate;
+    if (!coordinate) {
+        throw new DrawError('invalid-input', 'Image files require coordinate option');
+    }
+    const { store, autoNameGenerator, generateFeatureId, getCurrentLayerId } = deps;
+    let processed;
+    try {
+        processed = await processImageFile(file);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new DrawError('unsupported-format', `The image cannot be read: ${message}`, {
+            cause: error,
+        });
+    }
+    // The IDs, the layer and the automatic name are taken when the image is written, so that a
+    // load that fails later takes nothing
+    const write = () => {
+        const fileId = generateFeatureId();
+        const fileData = {
+            id: fileId,
+            mimeType: processed.mimeType,
+            dataURL: processed.dataUrl,
+        };
+        const featureId = generateFeatureId();
+        const layerId = options.layerId && store.getLayer(options.layerId) ? options.layerId : getCurrentLayerId();
+        const autoName = autoNameGenerator.generateName('Image');
+        const feature = {
+            groupId: undefined,
+            id: featureId,
+            type: 'Image',
+            geometry: { type: 'Point', coordinates: coordinate },
+            layerId,
+            properties: {
+                ...drawProperties({
+                    imageFileId: fileId,
+                    imageWidth: processed.width,
+                    imageHeight: processed.height,
+                    createdZoom: options.zoom ?? 1,
+                }),
+                ...(autoName !== undefined && { name: autoName }),
+            },
+            locked: false,
+            visible: true,
+            style: {},
+        };
+        beforeWrite?.();
+        store.createFile(fileData);
+        store.createFeature(feature);
+        store.setSelection('feature', [featureId]);
+        return {
+            format: 'image',
+            featureIds: [featureId],
+            replaced: false,
+        };
+    };
+    return { write };
+}

package/dist/api/impl/import-export/legacy-image-style.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Folds the style keys of an Image of 1.0 into its properties and its style
+ *
+ * - `width` and `height`, when they are positive, become the size the image is drawn at
+ *   (`maplibre-gl-draw:imageWidth` and `maplibre-gl-draw:imageHeight`)
+ * - `rotation` is added to `maplibre-gl-draw:rotation` (1.0 drew the sum of the two)
+ * - `opacity` becomes `imageOpacity` when the style has no `imageOpacity` (1.0 read it only
+ *   then)
+ *
+ * The four keys are removed from the style. The objects given are changed in place.
+ *
+ * @param properties - the properties of the feature, with the values of the library prefixed
+ * @param style - the style of the feature
+ * @returns whether anything was folded
+ */
+export declare function foldLegacyImageStyle(properties: Record<string, unknown>, style: Record<string, unknown>): boolean;

package/dist/api/impl/import-export/legacy-image-style.js

@@ -0,0 +1,49 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * The style keys an Image had in 1.0, folded into the model of 2.0
+ *
+ * In 1.0 the style of an Image could carry its size, a rotation and an opacity of its own. In
+ * 2.0 the size and the rotation are values of the library in `properties` and the opacity is
+ * `imageOpacity` of the style. Data written by 1.0 (native data of version 2 and GeoJSON) is
+ * read through this fold so that the image keeps its look.
+ */
+import { drawPropertyKey } from '../../../shared/properties.js';
+/** The style keys of an Image that 2.0 does not have */
+const LEGACY_KEYS = ['width', 'height', 'rotation', 'opacity'];
+function isNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+/**
+ * Folds the style keys of an Image of 1.0 into its properties and its style
+ *
+ * - `width` and `height`, when they are positive, become the size the image is drawn at
+ *   (`maplibre-gl-draw:imageWidth` and `maplibre-gl-draw:imageHeight`)
+ * - `rotation` is added to `maplibre-gl-draw:rotation` (1.0 drew the sum of the two)
+ * - `opacity` becomes `imageOpacity` when the style has no `imageOpacity` (1.0 read it only
+ *   then)
+ *
+ * The four keys are removed from the style. The objects given are changed in place.
+ *
+ * @param properties - the properties of the feature, with the values of the library prefixed
+ * @param style - the style of the feature
+ * @returns whether anything was folded
+ */
+export function foldLegacyImageStyle(properties, style) {
+    if (!LEGACY_KEYS.some((key) => key in style))
+        return false;
+    const { width, height, rotation, opacity } = style;
+    if (isNumber(width) && width > 0)
+        properties[drawPropertyKey('imageWidth')] = width;
+    if (isNumber(height) && height > 0)
+        properties[drawPropertyKey('imageHeight')] = height;
+    if (isNumber(rotation) && rotation !== 0) {
+        const current = properties[drawPropertyKey('rotation')];
+        properties[drawPropertyKey('rotation')] = (isNumber(current) ? current : 0) + rotation;
+    }
+    if (style.imageOpacity === undefined && isNumber(opacity))
+        style.imageOpacity = opacity;
+    for (const key of LEGACY_KEYS)
+        delete style[key];
+    return true;
+}

package/dist/api/impl/import-export/native-format.d.ts

@@ -0,0 +1,14 @@
+import type { Store } from '../../../store/store.js';
+import type { Data, ExportOptions } from '../../../store/types.js';
+import type { PreparedLoad } from './types.js';
+/**
+ * Exports the current data in the native format
+ */
+export declare function exportNative(store: Store, options?: ExportOptions): Data;
+/**
+ * Reads the native format for a load that replaces the existing data: everything is checked
+ * here, and the writes are left to the transaction of the caller
+ */
+export declare function prepareNative(data: Data, deps: {
+    store: Store;
+}): Promise<PreparedLoad>;