@sakuzu/maplibre-gl-draw 1.0.0 → 2.1.0

package/dist/api/impl/options.js

@@ -0,0 +1,851 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * `draw.options` and the options of `createDraw`: their checks, their translation into the
+ * configuration of the engine, and their application while the instance runs
+ *
+ * The options are kept as they were given, merged patch by patch. Each change is translated
+ * again from the whole of them into the configuration of the engine (`src/shared/config/`),
+ * which the renderers, the modes and the services read in place.
+ */
+import { MESSAGES_EN, resolveMessages } from '../../messages.js';
+import { formatColor, isColor, toColor } from '../../shared/color.js';
+import { DEFAULT_FEATURE_STYLE_CONFIG } from '../../shared/config/feature-style.js';
+import { DEFAULT_BOX_SELECTION_STYLE_CONFIG } from '../../shared/config/rendering.js';
+import { DEFAULT_SELECTION_CONFIG } from '../../shared/config/selection.js';
+import { DrawStore } from '../../store/draw-store.js';
+import { describeStyleProblem } from './import-export/style-validation.js';
+import { invalidInput, isRecord, onlyKeys } from './shared.js';
+/** The options that can only be given when the instance is created */
+const CREATION_KEYS = ['defaultMode', 'store', 'initDefaultLayer'];
+/** The options that change while the instance runs */
+const RUNTIME_KEYS = [
+    'messages',
+    'autoName',
+    'style',
+    'previewStyle',
+    'selectionStyle',
+    'scaleWithZoom',
+    'snapping',
+    'tracing',
+    'topology',
+    'clickTolerance',
+    'dragThreshold',
+    'rendering',
+    'isExternalEntry',
+];
+/** Runs a check on each key of the object that is given */
+function checkFields(value, what, checks) {
+    onlyKeys(value, Object.keys(checks), what);
+    for (const [key, check] of Object.entries(checks)) {
+        if (value[key] !== undefined)
+            check(value[key], `${what}.${key}`);
+    }
+}
+const bool = (value, what) => {
+    if (typeof value !== 'boolean')
+        throw invalidInput(`${what} must be a boolean`);
+};
+const string = (value, what) => {
+    if (typeof value !== 'string')
+        throw invalidInput(`${what} must be a string`);
+};
+const func = (value, what) => {
+    if (typeof value !== 'function')
+        throw invalidInput(`${what} must be a function`);
+};
+const nonNegative = (value, what) => {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+        throw invalidInput(`${what} must be a number from 0`);
+    }
+};
+const positive = (value, what) => {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+        throw invalidInput(`${what} must be a number above 0`);
+    }
+};
+const opacity = (value, what) => {
+    if (typeof value !== 'number' || !Number.isFinite(value) || value < 0 || value > 1) {
+        throw invalidInput(`${what} must be a number from 0 to 1`);
+    }
+};
+const color = (value, what) => {
+    if (!isColor(value))
+        throw invalidInput(`${what} must be a CSS color`);
+};
+const oneOf = (...values) => (value, what) => {
+    if (typeof value !== 'string' || !values.includes(value)) {
+        throw invalidInput(`${what} must be one of ${values.join(', ')}`);
+    }
+};
+const record = (checks) => (value, what) => {
+    if (!isRecord(value))
+        throw invalidInput(`${what} must be an object`);
+    checkFields(value, what, checks);
+};
+const featureStyle = (value, what) => {
+    const problem = describeStyleProblem(value);
+    if (problem)
+        throw invalidInput(`${what} is ${problem}`);
+};
+const numbers = (value, what) => {
+    if (!Array.isArray(value) || value.some((n) => typeof n !== 'number' || !Number.isFinite(n))) {
+        throw invalidInput(`${what} must be an array of numbers`);
+    }
+};
+const LINE_STYLE = oneOf('solid', 'dashed', 'dotted');
+const STROKE = record({
+    width: nonNegative,
+    color,
+    opacity,
+    lineStyle: LINE_STYLE,
+    dashArray: numbers,
+});
+const POINT = record({
+    shape: oneOf('circle', 'square', 'triangle', 'star', 'icon'),
+    size: nonNegative,
+    fillColor: color,
+    fillOpacity: opacity,
+    strokeColor: color,
+    strokeWidth: nonNegative,
+    strokeOpacity: opacity,
+    iconId: string,
+});
+const MARK = record({
+    shape: oneOf('circle', 'square', 'triangle', 'star'),
+    size: nonNegative,
+    fillColor: color,
+    fillOpacity: opacity,
+    strokeColor: color,
+    strokeWidth: nonNegative,
+    strokeOpacity: opacity,
+});
+const SELECTION_STYLE_CHECKS = {
+    boundingBox: record({ stroke: STROKE, margin: nonNegative }),
+    resizeHandle: record({ point: POINT }),
+    rotateHandle: record({ point: POINT, distance: nonNegative, connector: STROKE }),
+    vertexHandle: record({ point: POINT, selected: POINT, followed: POINT }),
+    midpointHandle: record({ point: POINT }),
+    radiusHandle: record({ point: POINT }),
+    centerMarker: record({ point: POINT }),
+    radiusLine: record({ stroke: STROKE }),
+    boxSelection: record({
+        fillColor: color,
+        fillOpacity: opacity,
+        strokeColor: color,
+        strokeWidth: nonNegative,
+    }),
+};
+const RUNTIME_CHECKS = {
+    messages(value, what) {
+        if (!isRecord(value))
+            throw invalidInput(`${what} must be an object`);
+        onlyKeys(value, Object.keys(MESSAGES_EN), what);
+        for (const [key, entry] of Object.entries(value)) {
+            const expected = typeof MESSAGES_EN[key];
+            if (entry !== undefined && typeof entry !== expected) {
+                throw invalidInput(`${what}.${key} must be a ${expected}`);
+            }
+        }
+    },
+    autoName(value, what) {
+        if (value === false)
+            return;
+        if (!isRecord(value))
+            throw invalidInput(`${what} must be false or an object`);
+        checkFields(value, what, {
+            typeNames(names, where) {
+                if (!isRecord(names))
+                    throw invalidInput(`${where} must be an object`);
+                for (const [key, name] of Object.entries(names)) {
+                    if (name !== undefined)
+                        string(name, `${where}.${key}`);
+                }
+            },
+            formatter: func,
+        });
+    },
+    style: record({
+        point: featureStyle,
+        line: featureStyle,
+        polygon: featureStyle,
+        circle: featureStyle,
+        image: featureStyle,
+    }),
+    previewStyle: featureStyle,
+    selectionStyle: record(SELECTION_STYLE_CHECKS),
+    scaleWithZoom: bool,
+    snapping: record({
+        enabled: bool,
+        tolerancePx: nonNegative,
+        disableKey: oneOf('alt', 'shift', 'ctrl', 'meta', 'none'),
+        kinds: record({ vertex: bool, edge: bool, intersection: bool, guide: bool }),
+        datasets: bool,
+        guideStepDegrees: positive,
+        indicator: record({ vertex: MARK, edge: MARK, intersection: MARK, guide: MARK }),
+        guideLine: STROKE,
+    }),
+    tracing: record({ enabled: bool }),
+    topology: record({ sharedVertexDrag: bool }),
+    clickTolerance: nonNegative,
+    dragThreshold: nonNegative,
+    rendering: record({
+        renderScale: positive,
+        pixelRatio: positive,
+        cacheGeometry: bool,
+        timeSlicing: bool,
+    }),
+    isExternalEntry: func,
+};
+/** The members of the public Store the instance calls; `abortIntermediateUpdates` is optional */
+const STORE_METHODS = [
+    'getFeature',
+    'listFeatures',
+    'listFeaturesInOrder',
+    'getLayer',
+    'listLayers',
+    'getLayerOrder',
+    'getGroup',
+    'listGroups',
+    'getFile',
+    'listFiles',
+    'getMetadata',
+    'getSelection',
+    'getEditingIds',
+    'getVertexSelection',
+    'getMode',
+    'isReadOnly',
+    'isInteractionLocked',
+    'isHidden',
+    'listHidden',
+    'subscribe',
+    'transact',
+    'createFeature',
+    'updateFeature',
+    'deleteFeature',
+    'createLayer',
+    'updateLayer',
+    'deleteLayer',
+    'setLayerOrder',
+    'reorderInLayer',
+    'reorderInGroup',
+    'createGroup',
+    'updateGroup',
+    'deleteGroup',
+    'createFile',
+    'deleteFile',
+    'setMetadata',
+    'setSelection',
+    'startEditing',
+    'endEditing',
+    'setSelectedVertices',
+    'setMode',
+    'setReadOnly',
+    'setInteractionLock',
+    'setLocallyHidden',
+];
+/**
+ * Checks the options of `createDraw`
+ *
+ * @throws `DrawError` with the code `invalid-input` for an unknown option or a value of the
+ *   wrong type
+ * @internal
+ */
+export function checkDrawOptions(options) {
+    if (!isRecord(options))
+        throw invalidInput('The options must be an object');
+    checkFields(options, 'options', {
+        ...RUNTIME_CHECKS,
+        defaultMode: string,
+        initDefaultLayer: bool,
+        store(value, what) {
+            if (!isRecord(value) && !(value instanceof DrawStore)) {
+                throw invalidInput(`${what} must be a Store`);
+            }
+            const store = value;
+            for (const method of STORE_METHODS) {
+                if (typeof store[method] !== 'function') {
+                    throw invalidInput(`${what} must be a Store: ${method} is missing`, { member: method });
+                }
+            }
+        },
+    });
+}
+/**
+ * Checks a patch of `draw.options.update`
+ *
+ * @internal
+ */
+function checkPatch(patch) {
+    if (!isRecord(patch))
+        throw invalidInput('The options must be an object');
+    for (const key of CREATION_KEYS) {
+        if (key in patch)
+            throw invalidInput(`${key} can only be given when the instance is created`);
+    }
+    checkFields(patch, 'options', RUNTIME_CHECKS);
+}
+// ============================================================================
+// Merging
+// ============================================================================
+/**
+ * The options with a patch merged in: plain objects are merged key by key, every other value
+ * (a function, an array, `false`) replaces the one before, and a key given as `undefined`
+ * keeps it
+ *
+ * @internal
+ */
+export function mergeOptions(base, patch) {
+    const result = { ...base };
+    for (const [key, value] of Object.entries(patch)) {
+        if (value === undefined)
+            continue;
+        const before = result[key];
+        result[key] = isRecord(value) && isRecord(before) ? mergeOptions(before, value) : value;
+    }
+    return result;
+}
+/** The options that change while the instance runs, out of the options of `createDraw` */
+function runtimePart(options) {
+    const result = {};
+    for (const key of RUNTIME_KEYS) {
+        if (options[key] !== undefined)
+            result[key] = options[key];
+    }
+    return mergeOptions({}, result);
+}
+// ============================================================================
+// The configuration of the engine
+// ============================================================================
+/** The alpha of a CSS color, 1 when there is none */
+function alphaOf(css) {
+    return css === undefined ? 1 : toColor(css)[3];
+}
+/** A color with another alpha */
+function withAlpha(color, alpha) {
+    return [color[0], color[1], color[2], alpha];
+}
+/**
+ * A stroke with the stroke keys of a style: the opacity is folded into the alpha of the color,
+ * as the style of a feature does
+ */
+function applyStroke(stroke, style, lineStyle = true) {
+    if (style.strokeColor !== undefined || style.strokeOpacity !== undefined) {
+        const base = style.strokeColor !== undefined ? toColor(style.strokeColor) : stroke.color;
+        const alpha = style.strokeOpacity !== undefined
+            ? alphaOf(style.strokeColor) * style.strokeOpacity
+            : base[3];
+        stroke.color = withAlpha(base, alpha);
+    }
+    if (style.strokeWidth !== undefined)
+        stroke.width = style.strokeWidth;
+    if (lineStyle && style.lineStyle !== undefined)
+        stroke.lineStyle = style.lineStyle;
+}
+/**
+ * A point marker with the point keys of a style: `pointStrokeColor` and `pointStrokeWidth` give
+ * its outline, and `pointOpacity` is multiplied into its fill and its outline
+ */
+function applyPoint(point, style) {
+    if (style.pointShape !== undefined)
+        point.shape = style.pointShape;
+    if (style.pointRadius !== undefined)
+        point.size = style.pointRadius * 2;
+    if (style.pointColor !== undefined)
+        point.fillColor = withAlpha(toColor(style.pointColor), 1);
+    if (style.pointColor !== undefined || style.pointOpacity !== undefined) {
+        point.fillOpacity = alphaOf(style.pointColor) * (style.pointOpacity ?? 1);
+    }
+    if (style.pointStrokeColor !== undefined) {
+        point.strokeColor = withAlpha(toColor(style.pointStrokeColor), 1);
+    }
+    if (style.pointStrokeColor !== undefined || style.pointOpacity !== undefined) {
+        point.strokeOpacity = alphaOf(style.pointStrokeColor) * (style.pointOpacity ?? 1);
+    }
+    if (style.pointStrokeWidth !== undefined)
+        point.strokeWidth = style.pointStrokeWidth;
+}
+/** A fill with the fill keys of a style; a color without an opacity keeps the alpha before */
+function applyFill(fill, style) {
+    if (style.fillColor === undefined && style.fillOpacity === undefined)
+        return;
+    const base = style.fillColor !== undefined ? toColor(style.fillColor) : fill.color;
+    const alpha = alphaOf(style.fillColor) * (style.fillOpacity ?? fill.color[3]);
+    fill.color = withAlpha(base, alpha);
+}
+/**
+ * The look of the features for the options: the defaults of each type and the look of the
+ * geometry being drawn
+ *
+ * @internal
+ */
+export function toFeatureStyleConfig(options) {
+    const config = structuredClone(DEFAULT_FEATURE_STYLE_CONFIG);
+    const style = options.style ?? {};
+    if (style.point)
+        applyPoint(config.point.point, style.point);
+    if (style.line)
+        applyStroke(config.lineString.stroke, style.line);
+    if (style.polygon) {
+        applyStroke(config.polygon.stroke, style.polygon);
+        applyFill(config.polygon.fill, style.polygon);
+    }
+    if (style.circle) {
+        const circle = structuredClone(config.polygon);
+        applyStroke(circle.stroke, style.circle);
+        applyFill(circle.fill, style.circle);
+        config.circle = circle;
+    }
+    if (style.image?.imageOpacity !== undefined) {
+        config.image = { opacity: style.image.imageOpacity };
+    }
+    const preview = options.previewStyle;
+    if (preview) {
+        const tentative = config.tentative;
+        applyStroke(tentative.stroke, preview);
+        // The line to the pointer keeps its dashes
+        applyStroke(tentative.tentativeStroke, preview, false);
+        for (const vertex of [tentative.vertex, tentative.highlightedVertex]) {
+            applyPoint(vertex, preview);
+        }
+        // The highlighted vertex stays larger than the others
+        if (preview.pointRadius !== undefined) {
+            tentative.highlightedVertex.size = preview.pointRadius * 2 + 4;
+        }
+        for (const marker of [tentative.circleCenterMarker, tentative.circleRadiusHandle]) {
+            if (preview.pointStrokeColor !== undefined) {
+                marker.strokeColor = withAlpha(toColor(preview.pointStrokeColor), 1);
+            }
+        }
+    }
+    return config;
+}
+/** A color of the defaults as a CSS color, its alpha left to the opacity */
+function defaultCss(color) {
+    return formatColor([color[0], color[1], color[2], 1]);
+}
+/**
+ * A paint with the color and the opacity of a style put over it, as {@link applyFill} and
+ * {@link applyStroke} fold them into the configuration: a color keeps the string it was given,
+ * and takes the opacity given, or `fallback` of the paint before; an opacity on its own sets
+ * the alpha the color is drawn with
+ */
+function layerPaint(paint, color, opacity, fallback) {
+    if (color !== undefined)
+        return { color, opacity: opacity ?? fallback(paint) };
+    if (opacity === undefined)
+        return paint;
+    const alpha = alphaOf(paint.color);
+    if (alpha === 1)
+        return { color: paint.color, opacity };
+    // The color before has an alpha of its own, which the opacity replaces
+    const rgb = toColor(paint.color);
+    return alpha > 0
+        ? { color: paint.color, opacity: opacity / alpha }
+        : { color: defaultCss(rgb), opacity };
+}
+/** The opacity a fill keeps when a style gives only its color: the alpha it was drawn with */
+const drawnAlpha = (paint) => alphaOf(paint.color) * paint.opacity;
+/** The opacity a stroke takes when a style gives only its color */
+const opaque = () => 1;
+/** The types whose outline takes the stroke of an area */
+const AREA_TYPES = new Set(['Polygon', 'MultiPolygon', 'Circle']);
+/**
+ * The look the options give a feature of a type before its layer rule and its own style, in
+ * the shape of the style of a feature
+ *
+ * The colors are the strings the options give, as they were given; a color the options leave
+ * out is the default as `#rrggbb`. The opacities are what the colors are drawn with, so that
+ * the look drawn is the same as the configuration of {@link toFeatureStyleConfig}.
+ *
+ * @param style - The `style` option
+ * @param type - The type of the feature
+ * @internal
+ */
+export function toAppliedDefaults(style, type) {
+    const defaults = DEFAULT_FEATURE_STYLE_CONFIG;
+    const point = style?.point ?? {};
+    // A circle takes the look of the circles over the look of the polygons, as it is drawn
+    const layers = AREA_TYPES.has(type)
+        ? [style?.polygon ?? {}, ...(type === 'Circle' && style?.circle ? [style.circle] : [])]
+        : [style?.line ?? {}];
+    const defaultStroke = AREA_TYPES.has(type) ? defaults.polygon.stroke : defaults.lineString.stroke;
+    const fillDefault = defaults.polygon.fill.color;
+    let fill = { color: defaultCss(fillDefault), opacity: fillDefault[3] };
+    let stroke = {
+        color: defaultCss(defaultStroke.color),
+        opacity: defaultStroke.color[3] * defaultStroke.opacity,
+    };
+    let strokeWidth = defaultStroke.width;
+    let lineStyle = defaultStroke.lineStyle;
+    for (const layer of layers) {
+        if (AREA_TYPES.has(type)) {
+            fill = layerPaint(fill, layer.fillColor, layer.fillOpacity, drawnAlpha);
+        }
+        stroke = layerPaint(stroke, layer.strokeColor, layer.strokeOpacity, opaque);
+        strokeWidth = layer.strokeWidth ?? strokeWidth;
+        lineStyle = layer.lineStyle ?? lineStyle;
+    }
+    const marker = defaults.point.point;
+    return {
+        fillColor: fill.color,
+        fillOpacity: fill.opacity,
+        strokeColor: stroke.color,
+        strokeWidth,
+        strokeOpacity: stroke.opacity,
+        lineStyle,
+        pointColor: point.pointColor ?? defaultCss(marker.fillColor),
+        pointRadius: point.pointRadius ?? marker.size / 2,
+        pointShape: point.pointShape ?? (marker.shape === 'icon' ? 'circle' : marker.shape),
+        pointOpacity: point.pointOpacity ?? 1,
+        pointStrokeColor: point.pointStrokeColor ?? defaultCss(marker.strokeColor),
+        pointStrokeWidth: point.pointStrokeWidth ?? marker.strokeWidth,
+        imageOpacity: style?.image?.imageOpacity ?? defaults.image?.opacity ?? 1,
+    };
+}
+/** A stroke of the selection from its options */
+function toStroke(stroke, given) {
+    if (!given)
+        return;
+    if (given.color !== undefined)
+        stroke.color = toColor(given.color);
+    if (given.width !== undefined)
+        stroke.width = given.width;
+    if (given.opacity !== undefined)
+        stroke.opacity = given.opacity;
+    if (given.lineStyle !== undefined)
+        stroke.lineStyle = given.lineStyle;
+    if (given.dashArray !== undefined)
+        stroke.dashArray = [...given.dashArray];
+}
+/** A handle of the selection from its options */
+function toPoint(point, given) {
+    if (!given)
+        return;
+    for (const [key, value] of Object.entries(given)) {
+        if (value === undefined)
+            continue;
+        const target = point;
+        target[key] = key === 'fillColor' || key === 'strokeColor' ? toColor(value) : value;
+    }
+}
+/**
+ * The look of the selection for the options
+ *
+ * @internal
+ */
+export function toSelectionConfig(options) {
+    const config = structuredClone(DEFAULT_SELECTION_CONFIG);
+    const given = (options.selectionStyle ?? {});
+    const part = (key) => given[key] ?? {};
+    const sub = (key, name) => part(key)[name];
+    toStroke(config.boundingBox.stroke, sub('boundingBox', 'stroke'));
+    if (part('boundingBox').margin !== undefined) {
+        config.boundingBox.margin = part('boundingBox').margin;
+    }
+    toPoint(config.resizeHandle.point, sub('resizeHandle', 'point'));
+    toPoint(config.rotateHandle.point, sub('rotateHandle', 'point'));
+    toStroke(config.rotateHandle.connector, sub('rotateHandle', 'connector'));
+    if (part('rotateHandle').distance !== undefined) {
+        config.rotateHandle.distance = part('rotateHandle').distance;
+    }
+    toPoint(config.vertexHandle.point, sub('vertexHandle', 'point'));
+    toPoint(config.vertexHandle.selected, sub('vertexHandle', 'selected'));
+    toPoint(config.vertexHandle.followed, sub('vertexHandle', 'followed'));
+    toPoint(config.midpointHandle.point, sub('midpointHandle', 'point'));
+    toPoint(config.radiusHandle.point, sub('radiusHandle', 'point'));
+    toPoint(config.centerMarker.point, sub('centerMarker', 'point'));
+    toStroke(config.radiusLine.stroke, sub('radiusLine', 'stroke'));
+    return config;
+}
+/**
+ * The rectangle of a box selection for the options
+ *
+ * @internal
+ */
+export function toBoxSelectionStyle(options) {
+    const config = structuredClone(DEFAULT_BOX_SELECTION_STYLE_CONFIG);
+    const box = options.selectionStyle?.boxSelection;
+    if (!box)
+        return config;
+    if (box.fillColor !== undefined || box.fillOpacity !== undefined) {
+        const base = box.fillColor !== undefined ? toColor(box.fillColor) : config.fillColor;
+        config.fillColor = withAlpha(base, alphaOf(box.fillColor) * (box.fillOpacity ?? config.fillColor[3]));
+    }
+    if (box.strokeColor !== undefined)
+        config.strokeColor = toColor(box.strokeColor);
+    if (box.strokeWidth !== undefined)
+        config.strokeWidth = box.strokeWidth;
+    return config;
+}
+/** The configuration of the automatic names */
+function toAutoName(autoName) {
+    if (autoName === undefined)
+        return true;
+    if (autoName === false)
+        return false;
+    return { enabled: true, typeNames: autoName.typeNames, formatter: autoName.formatter };
+}
+/**
+ * The options of the engine for the options of `createDraw`
+ *
+ * @param isExternalEntry - The function the engine asks about the entries of the stacking
+ *   order; the one of the options is reached through it, so that it can change
+ * @internal
+ */
+export function toEngineOptions(options, isExternalEntry) {
+    const runtime = runtimePart(options);
+    const result = {
+        messages: runtime.messages,
+        autoName: toAutoName(runtime.autoName),
+        // Always given, so that the engine gets copies it can change in place
+        style: toFeatureStyleConfig(runtime),
+        selectionStyle: toSelectionConfig(runtime),
+        renderingStyle: {
+            boxSelectionStyle: toBoxSelectionStyle(runtime),
+            storeRetained: runtime.rendering?.cacheGeometry ?? true,
+            timeSlicing: runtime.rendering?.timeSlicing ?? true,
+        },
+        snap: runtime.snapping,
+        trace: runtime.tracing,
+        topology: runtime.topology,
+        pixelRatio: runtime.rendering?.pixelRatio,
+        isExternalEntry,
+    };
+    if (options.defaultMode !== undefined)
+        result.defaultMode = options.defaultMode;
+    if (options.initDefaultLayer !== undefined)
+        result.initDefaultLayer = options.initDefaultLayer;
+    if (runtime.scaleWithZoom !== undefined)
+        result.scaleWithZoom = runtime.scaleWithZoom;
+    if (runtime.clickTolerance !== undefined)
+        result.clickTolerance = runtime.clickTolerance;
+    if (runtime.dragThreshold !== undefined)
+        result.dragThreshold = runtime.dragThreshold;
+    if (options.store !== undefined) {
+        // A Store of the library is used as it is; the Store of an application is read and written
+        // through the public contract only, and the instance keeps the drawing state around it
+        result.store = options.store;
+    }
+    return result;
+}
+// ============================================================================
+// draw.options
+// ============================================================================
+/**
+ * Changes an object of the configuration in place to the value of another, so that everything
+ * holding it sees the new value
+ */
+function assignInPlace(target, source) {
+    for (const key of Object.keys(target)) {
+        if (!(key in source))
+            delete target[key];
+    }
+    for (const [key, value] of Object.entries(source)) {
+        const before = target[key];
+        if (isRecord(value) && isRecord(before))
+            assignInPlace(before, value);
+        else
+            target[key] = value;
+    }
+}
+/**
+ * Creates `draw.options` over the engine
+ *
+ * @param engine - The engine of the instance
+ * @param options - The options the instance was created with
+ * @param setExternalEntry - Replaces the function that tells the entries from outside the
+ *   document
+ * @param onChanged - Receives the options after and before an update that changed them
+ * @internal
+ */
+export function createOptions(engine, options, setExternalEntry, onChanged = () => { }) {
+    const { context, map, customLayer } = engine;
+    let current = runtimePart(options);
+    const apply = (patch) => {
+        let redraw = false;
+        let rebuild = false;
+        const next = current;
+        if (patch.messages !== undefined) {
+            Object.assign(context.messages, resolveMessages(next.messages));
+        }
+        if (patch.autoName !== undefined) {
+            context.autoNameGenerator.configure(toAutoName(next.autoName));
+        }
+        if (patch.style !== undefined || patch.previewStyle !== undefined) {
+            assignInPlace(context.featureStyle, toFeatureStyleConfig(next));
+            rebuild = true;
+        }
+        if (patch.selectionStyle !== undefined) {
+            assignInPlace(context.selectionStyle, toSelectionConfig(next));
+            assignInPlace(context.renderingConfig.boxSelectionStyle, toBoxSelectionStyle(next));
+            rebuild = true;
+        }
+        if (patch.scaleWithZoom !== undefined)
+            context.options.scaleWithZoom = patch.scaleWithZoom;
+        const snapping = patch.snapping;
+        if (snapping) {
+            const { snapService, snapOptions } = context;
+            if (snapping.enabled !== undefined)
+                snapService.setEnabled(snapping.enabled);
+            if (snapping.tolerancePx !== undefined) {
+                snapService.setTolerance(snapping.tolerancePx);
+                snapOptions.tolerancePx = snapping.tolerancePx;
+            }
+            if (snapping.disableKey !== undefined) {
+                snapService.setDisableKey(snapping.disableKey);
+                // The shared vertices read the same key
+                snapOptions.disableKey = snapping.disableKey;
+            }
+            for (const [kind, enabled] of Object.entries(snapping.kinds ?? {})) {
+                if (enabled === undefined)
+                    continue;
+                snapService.setKindEnabled(kind, enabled);
+            }
+            if (snapping.datasets !== undefined)
+                snapService.setDatasetsEnabled(snapping.datasets);
+            if (snapping.guideStepDegrees !== undefined) {
+                snapService.setGuideStep(snapping.guideStepDegrees);
+            }
+            const look = context.snapIndicator;
+            for (const [kind, mark] of Object.entries(snapping.indicator ?? {})) {
+                toPoint(look.styles[kind], mark);
+                redraw = true;
+            }
+            if (snapping.guideLine) {
+                toStroke(look.guideLine, snapping.guideLine);
+                redraw = true;
+            }
+        }
+        if (patch.tracing?.enabled !== undefined)
+            context.trace.enabled = patch.tracing.enabled;
+        if (patch.topology?.sharedVertexDrag !== undefined) {
+            context.topology.sharedVertexDrag = patch.topology.sharedVertexDrag;
+        }
+        if (patch.clickTolerance !== undefined) {
+            context.options.clickTolerance = patch.clickTolerance;
+            context.hitTestService.setClickTolerance(patch.clickTolerance);
+        }
+        if (patch.dragThreshold !== undefined) {
+            context.options.dragThreshold = patch.dragThreshold;
+            engine.runtime.setDragThreshold(patch.dragThreshold);
+        }
+        const rendering = patch.rendering;
+        if (rendering) {
+            if (rendering.renderScale !== undefined) {
+                if (context.pixelRatioSource.setScaleFactor(rendering.renderScale))
+                    redraw = true;
+            }
+            if (rendering.pixelRatio !== undefined) {
+                context.pixelRatio = rendering.pixelRatio;
+                if (context.pixelRatioSource.setPixelRatio(rendering.pixelRatio))
+                    redraw = true;
+            }
+            if (rendering.cacheGeometry !== undefined) {
+                context.renderingConfig.storeRetained = rendering.cacheGeometry;
+                rebuild = true;
+            }
+            if (rendering.timeSlicing !== undefined) {
+                engine.runtime.setTimeSlicing(rendering.timeSlicing);
+                rebuild = true;
+            }
+        }
+        if (patch.isExternalEntry !== undefined) {
+            setExternalEntry(patch.isExternalEntry);
+            rebuild = true;
+        }
+        if (rebuild && 'refresh' in customLayer)
+            customLayer.refresh();
+        else if (redraw)
+            map.triggerRepaint();
+    };
+    const get = () => {
+        const { snapService, trace, topology, pixelRatioSource, renderingConfig } = context;
+        const snap = snapService.getOptions();
+        const values = {
+            ...current,
+            scaleWithZoom: context.options.scaleWithZoom,
+            clickTolerance: context.options.clickTolerance,
+            dragThreshold: context.options.dragThreshold,
+            snapping: {
+                ...current.snapping,
+                enabled: snap.enabled,
+                tolerancePx: snap.tolerancePx,
+                disableKey: snap.disableKey,
+                kinds: { ...snap.kinds },
+                datasets: snap.datasets,
+                guideStepDegrees: snap.guideStepDegrees,
+            },
+            tracing: { enabled: trace.enabled },
+            topology: { sharedVertexDrag: topology.sharedVertexDrag },
+            rendering: {
+                ...current.rendering,
+                renderScale: pixelRatioSource.getScaleFactor(),
+                cacheGeometry: renderingConfig.storeRetained !== false,
+                timeSlicing: renderingConfig.timeSlicing !== false,
+            },
+        };
+        return structuredCloneOptions(values);
+    };
+    return {
+        get,
+        update(patch) {
+            checkPatch(patch);
+            const previous = get();
+            current = mergeOptions(current, patch);
+            apply(patch);
+            const next = get();
+            if (!sameOptions(previous, next))
+                onChanged({ options: next, previous });
+        },
+        getStyle() {
+            return current.style;
+        },
+        applyCreation() {
+            const scale = current.rendering?.renderScale;
+            if (scale !== undefined)
+                apply({ rendering: { renderScale: scale } });
+            // The look of the snapping indicator is not an option of the engine
+            const { indicator, guideLine } = current.snapping ?? {};
+            if (indicator || guideLine) {
+                apply({
+                    snapping: { ...(indicator && { indicator }), ...(guideLine && { guideLine }) },
+                });
+            }
+        },
+    };
+}
+/**
+ * Whether two copies of the options hold the same values: plain objects and arrays are
+ * compared item by item, a function by identity, and a key given as `undefined` is the same
+ * as a key left out
+ */
+function sameOptions(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        return (Array.isArray(a) &&
+            Array.isArray(b) &&
+            a.length === b.length &&
+            a.every((item, i) => sameOptions(item, b[i])));
+    }
+    if (!isRecord(a) || !isRecord(b))
+        return false;
+    const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+    for (const key of keys) {
+        if (!sameOptions(a[key], b[key]))
+            return false;
+    }
+    return true;
+}
+/** A copy of the options that shares the functions and nothing else */
+function structuredCloneOptions(value) {
+    if (Array.isArray(value))
+        return value.map(structuredCloneOptions);
+    if (!isRecord(value))
+        return value;
+    const copy = {};
+    for (const [key, entry] of Object.entries(value))
+        copy[key] = structuredCloneOptions(entry);
+    return copy;
+}