@zwishing/emap 0.1.0

package/dist/map/highlight-manager.d.ts

@@ -0,0 +1,17 @@
+import type { CorePainter } from '../renderer/painter';
+import { AffineTransform } from '../geo/transform';
+import { TopologySource } from '../source/source';
+import type { HighlightStyle, HighlightFeatureRef, QueriedFeature } from './map';
+/**
+ * Manages feature highlighting state and rendering.
+ * Extracted from Emap to isolate highlight concerns.
+ */
+export declare class HighlightManager {
+    private _highlighted;
+    private _highlightStyle;
+    get size(): number;
+    setHighlightedFeatures(features: Array<QueriedFeature | HighlightFeatureRef>, style?: HighlightStyle): void;
+    clearHighlightedFeatures(): boolean;
+    setHighlightStyle(style: HighlightStyle): boolean;
+    renderHighlights(painter: CorePainter, sources: globalThis.Map<string, TopologySource>, transform: AffineTransform, lineScale: number, visibleLayers?: Set<string>): void;
+}

package/dist/map/layer-registry.d.ts

@@ -0,0 +1,33 @@
+import type { TopologySource } from '../source/source';
+import type { MapshaperLayer } from '../types/mapshaper-types';
+/**
+ * Resolve `layerId` against an ad-hoc layer list. Callable as a free
+ * function so ops that take a dataset snapshot (and don't have a host
+ * reference) can share the same matching rule. Use {@link LayerRegistry.resolve}
+ * when you have a `(sourceId, layerId)` tuple instead.
+ */
+export declare function resolveLayerInList(layers: ReadonlyArray<MapshaperLayer>, layerId: string): MapshaperLayer | null;
+export declare class LayerRegistry {
+    private readonly _sources;
+    constructor(_sources: globalThis.Map<string, TopologySource>);
+    /**
+     * Resolve `(sourceId, layerId)` to the underlying MapshaperLayer, or
+     * `null` when neither the source nor any layer name/id match.
+     *
+     * `layerId` is matched in this priority order:
+     *   1. The canonical id from `getLayerId(layer, idx)` — i.e. layer.name,
+     *      then layer.id, then the positional `'layer-N'` fallback.
+     *   2. `layer.name` (exact match).
+     *   3. `layer.id` (exact match).
+     *
+     * Returns the FIRST hit; in a well-formed dataset every layer's
+     * `getLayerId` is unique so the priority list is theoretical.
+     */
+    resolve(sourceId: string, layerId: string): MapshaperLayer | null;
+    /**
+     * Resolve a layer id against an ad-hoc layer list — used by ops that
+     * snapshot the dataset before a mapshaper command runs (the source's
+     * registered dataset has already advanced).
+     */
+    resolveInLayers(layers: ReadonlyArray<MapshaperLayer>, layerId: string): MapshaperLayer | null;
+}

package/dist/map/layer.d.ts

@@ -0,0 +1,29 @@
+import type { StrokeStyle, PointStyle } from '../types/mapshaper-types';
+export type LayerType = 'fill' | 'line' | 'circle';
+export interface FillPaint {
+    'fill-color'?: string;
+    'fill-opacity'?: number;
+}
+export interface LinePaint {
+    'line-color'?: string;
+    'line-width'?: number;
+}
+export interface CirclePaint {
+    'circle-color'?: string;
+    'circle-radius'?: number;
+    'circle-fill'?: boolean;
+}
+export type LayerPaint = FillPaint | LinePaint | CirclePaint;
+export interface LayerLayout {
+    visibility?: 'visible' | 'none';
+}
+export interface LayerSpecification {
+    id: string;
+    type: LayerType;
+    source: string;
+    'source-layer'?: string;
+    paint?: LayerPaint;
+    layout?: LayerLayout;
+}
+export declare function resolveStrokeStyle(paint: LinePaint | FillPaint | undefined, lineScale: number): StrokeStyle;
+export declare function resolvePointStyle(paint: CirclePaint | undefined): PointStyle;

package/dist/map/map.d.ts

@@ -0,0 +1,386 @@
+import { EventDispatcher } from '../core/events';
+import { Bounds } from '../geo/bounds';
+import { AffineTransform } from '../geo/transform';
+import { Painter } from '../renderer/painter';
+import { MapshaperOps } from './mapshaper-ops';
+import { EditSessions } from './edit-sessions';
+import { AttributeOps } from './attribute-ops';
+import { type EditMode } from './edit-state-store';
+import { LayerRegistry } from './layer-registry';
+import { TopologySource } from '../source/source';
+import { MapshaperWorkerPool } from '../core/mapshaper-worker-pool';
+import { FeatureAccessor } from './feature-accessor';
+import { ValidatorRegistry } from '../validation/registry';
+import { Selection, SelectMode, SelectionDiff } from './selection';
+import { EditHistory } from '../edit/edit-history';
+import type { EditCommand } from '../edit/edit-command';
+import { Transaction, type TransactionInternal } from '../edit/transaction';
+import { Control, ControlPosition } from '../ui/control';
+import type { LayerSpecification } from './layer';
+import type { MapshaperLayer } from '../types/mapshaper-types';
+export * from './types';
+import { type ExpressionEvaluationPolicy, type MapOptions, type QueryFeaturesOptions, type QueriedFeature, type FeatureRef, type HighlightFeatureRef, type ExportSnapshotOptions, type LoadSnapshotOptions, type HighlightStyle, type EditVertexState, type EditDrawState } from './types';
+export declare class Emap extends EventDispatcher {
+    private _container;
+    private _canvasContainer;
+    private _canvas;
+    private _painter;
+    private _editOverlay;
+    private _viewport;
+    private _projection;
+    _sources: globalThis.Map<string, TopologySource>;
+    /**
+     * Single resolution surface for `(sourceId, layerId) → MapshaperLayer`.
+     * Exposed to managers via `EmapHostInternal.layers`. Reads `_sources`
+     * lazily so it stays in sync with `addSource`/`removeSource` without
+     * needing its own listener. Constructed on first access so test paths
+     * that bypass the constructor via `Object.create(Emap.prototype)` still
+     * see a working registry once they `setPrivate(map, '_sources', ...)`.
+     */
+    private _layersCache?;
+    get layers(): LayerRegistry;
+    private _sourceListeners;
+    private _layers;
+    private _effectiveLayersCache;
+    private _defaultLayersDirty;
+    private _layerArcFlagsCache;
+    private _mouseWheel;
+    private _dragPan;
+    private _pendingRender;
+    private _rafId;
+    private _controlContainers;
+    private _controls;
+    private _highlightManager;
+    private _featureQuery;
+    /**
+     * Read-side feature accessor — `engine.features.get(ref)` returns one
+     * feature's geometry + frozen properties; `iter(sourceId, layerId)`
+     * walks a layer; `count(...)` is O(1). Constructed lazily in the
+     * Emap constructor so test paths that bypass it via
+     * `Object.create(Emap.prototype)` still see a working accessor once
+     * they wire up the host.
+     */
+    features: FeatureAccessor;
+    _selection: Selection;
+    _history: EditHistory;
+    /**
+     * Currently active transaction, or `null`. Mutated by
+     * `Transaction`'s constructor / commit / rollback. Exposed via the
+     * `EmapHostInternal` contract so the runner can record per-source
+     * snapshots without threading a transaction param through every op
+     * signature.
+     */
+    _activeTransaction: TransactionInternal | null;
+    /**
+     * Post-commit validator registry. Validators registered here run
+     * after every `historychange` event; failures surface via
+     * `validationfailed` (no auto-undo — apps decide how to react).
+     *
+     * Public-facing alias is `engine.validators` (see initialiser below).
+     */
+    readonly _validators: ValidatorRegistry;
+    /** Public alias for the validator registry. */
+    get validators(): ValidatorRegistry;
+    private _historyShortcutUnbind;
+    private _ops?;
+    private _editSession?;
+    private _attributes?;
+    /** Mapshaper layer ops (clip / dissolve / buffer / project / ...). */
+    get ops(): MapshaperOps;
+    /** Selection editing (translate / rotate / scale + live drag sessions). */
+    get editSession(): EditSessions;
+    /** Per-feature property and per-layer field editing. */
+    get attributes(): AttributeOps;
+    private _editState;
+    _workerPool: MapshaperWorkerPool | null;
+    _workerMode: boolean | 'auto';
+    _workerThreshold: number;
+    /**
+     * Optional caller-supplied routing decision. When set, `_runDatasetCommand`
+     * forwards every command-info bundle to it and uses the boolean result
+     * verbatim. Pass `MapOptions.workerRouting` to install one. Read by
+     * `MapshaperOps` via the host.
+     */
+    _workerRouting?: import('./worker-routing').WorkerRoutingFn;
+    private _expressionPolicy;
+    constructor(options: MapOptions);
+    /**
+     * Hard-cancel any in-flight worker jobs. Safe to call when no worker
+     * pool exists (no-op). The pool stays usable — subsequent dataset-replace
+     * ops re-spawn a fresh worker.
+     *
+     * mapshaper isn't interruptible mid-command, so this is the only sound
+     * abandonment path: terminate the worker, lose any other queued jobs as
+     * collateral, and let the next op start over.
+     */
+    cancelWorkerJobs(): void;
+    setExpressionPolicy(policy: ExpressionEvaluationPolicy): void;
+    getExpressionPolicy(): ExpressionEvaluationPolicy;
+    _allowExpressionEvaluation(values: Array<string | undefined>, operation: string): boolean;
+    getCanvasContainer(): HTMLElement;
+    getEditMode(): EditMode;
+    setEditMode(mode: EditMode): void;
+    setEditVertexState(state: EditVertexState): void;
+    clearEditVertexState(): void;
+    setEditDrawState(state: EditDrawState): void;
+    clearEditDrawState(): void;
+    private _attachEventListeners;
+    private _createCanvasContainer;
+    private _updateSize;
+    addSource(id: string, source: TopologySource): void;
+    removeSource(id: string): void;
+    getSource(id: string): TopologySource | undefined;
+    /**
+     * Pack every topology source on this map into one `.msx` snapshot Blob via
+     * mapshaper's session pack pipeline. Source IDs are preserved in a custom
+     * `emap.sources` field on the packed object so {@link loadSnapshot} can
+     * re-register sources under their original IDs.
+     *
+     * Sources that have no dataset yet (load not completed) are skipped.
+     *
+     * The output file is a valid mapshaper `.msx` — vanilla mapshaper will
+     * load it (just dropping the `emap` metadata).
+     */
+    exportSnapshot(opts?: ExportSnapshotOptions): Promise<Blob>;
+    /**
+     * Restore one or more topology sources from a `.msx` snapshot via
+     * mapshaper's session unpack pipeline. Returns the list of registered
+     * source IDs in registration order.
+     *
+     * ID resolution priority (per restored dataset, in order):
+     * 1. `opts.idPrefix` + ID from snapshot's `emap.sources[i].id` (if metadata present)
+     * 2. `opts.idPrefix` + `opts.defaultIds[i]` (if supplied)
+     * 3. `opts.idPrefix` + `snapshot-<i>` fallback
+     *
+     * On ID collision: `replace: true` (default) removes the existing source
+     * first; `replace: false` rejects without registering anything.
+     *
+     * Edit history and selection are cleared because feature IDs in the
+     * replayed history would point to features that no longer exist after
+     * dataset replacement. Same semantics as the dataset-replace family
+     * (clip, dissolve, mosaic, ...).
+     */
+    loadSnapshot(input: Blob | Uint8Array | ArrayBuffer, opts?: LoadSnapshotOptions): Promise<string[]>;
+    addLayer(layer: LayerSpecification, before?: string): void;
+    removeLayer(id: string): void;
+    getLayer(id: string): LayerSpecification | undefined;
+    getLayers(): LayerSpecification[];
+    setLayerVisibility(id: string, visibility: 'visible' | 'none'): void;
+    setPaintProperty(id: string, name: string, value: unknown): void;
+    moveLayer(id: string, beforeId?: string): void;
+    private _getEffectiveLayers;
+    private _resolveSourceLayer;
+    /**
+     * Generates a boolean flag array for arcs that belong to a specific source layer.
+     * Cached to prevent walking shapes on every frame.
+     *
+     * Only meaningful for path layers (polygon/polyline). Point layers have no
+     * arc references, so iterating their shapes contributes nothing — caller
+     * should filter by `isPathLayer` before invoking.
+     */
+    private _getLayerArcFlags;
+    private _getVisibleLayerKeys;
+    getPainter(): Painter;
+    getCRS(): string;
+    setCRS(crs: string): void;
+    reproject(targetCrs: string): Promise<void>;
+    getCenter(): [number, number];
+    getZoom(): number;
+    getTransform(): AffineTransform;
+    getExtent(): Bounds;
+    setExtent(bounds: Bounds): void;
+    reset(): void;
+    addControl(control: Control, position?: ControlPosition): void;
+    removeControl(control: Control): void;
+    zoomIn(): void;
+    zoomOut(): void;
+    _scheduleRender(): void;
+    private _doRender;
+    render(): void;
+    private _renderLayers;
+    private _renderLineLayer;
+    private _renderFillLayer;
+    private _combineArcFilters;
+    private _renderHighlight;
+    project(x: number, y: number): [number, number];
+    unproject(px: number, py: number): [number, number];
+    resize(): void;
+    queryFeatures(geometryOrOptions?: [number, number] | [[number, number], [number, number]] | QueryFeaturesOptions, options?: QueryFeaturesOptions): QueriedFeature[];
+    /**
+     * Eagerly build the per-layer Flatbush spatial index for one source (or
+     * every registered source when `sourceId` is omitted). Useful for paying
+     * the build cost in idle time before the user's first hit-test.
+     *
+     * Idempotent — already-cached layer indexes are skipped. No-op for
+     * sources without a dataset.
+     *
+     * Subsequent `queryFeatures` calls automatically use whatever's
+     * cached, regardless of whether `prebuildSpatialIndex` was called.
+     */
+    prebuildSpatialIndex(sourceId?: string): void;
+    /**
+     * Drop cached per-layer spatial indexes for one source (or all sources
+     * when `sourceId` is omitted).
+     *
+     * Required after in-place geometry edits (`translateSelected`,
+     * `rotateSelected`, vertex commands) that mutate arc coordinates without
+     * changing shape or arc counts — the cache key wouldn't notice and
+     * subsequent queries would return prefilter-stale results.
+     *
+     * Dataset-replace ops (clip / dissolve / etc.) automatically invalidate
+     * via shape-count or arc-count change; this method is only needed for
+     * in-place edits.
+     */
+    clearSpatialIndex(sourceId?: string): void;
+    _clearSpatialIndexesForSources(sourceIds: Iterable<string>): void;
+    setHighlightedFeatures(features: Array<QueriedFeature | HighlightFeatureRef>, style?: HighlightStyle): void;
+    clearHighlightedFeatures(): void;
+    setHighlightStyle(style: HighlightStyle): void;
+    /**
+     * Mutate the persistent feature selection.
+     *
+     * @param features Refs to apply. `QueriedFeature` is structurally
+     *   compatible with `FeatureRef`, so results from `queryFeatures` can
+     *   be passed directly.
+     * @param options.mode `'replace'` (default) wipes prior contents,
+     *   `'add'` unions, `'toggle'` flips membership.
+     *
+     * Fires a `selectionchange` event with `{ selected, added, removed }` only
+     * when the set actually changes.
+     */
+    select(features: ReadonlyArray<FeatureRef>, options?: {
+        mode?: SelectMode;
+    }): void;
+    /** Remove the listed features from the selection. No-op if absent. */
+    deselect(features: ReadonlyArray<FeatureRef>): void;
+    /** Empty the selection. No-op (and no event) if it was already empty. */
+    clearSelection(): void;
+    /** Snapshot of the current selection as a flat list of refs. */
+    getSelection(): FeatureRef[];
+    /** Test whether a single feature is currently selected. */
+    isSelected(feature: FeatureRef): boolean;
+    _fireSelectionChange(diff: SelectionDiff): void;
+    /**
+     * Delete every currently-selected feature in one undoable history step.
+     *
+     * Returns `true` when at least one feature was deleted, `false` when the
+     * selection was empty (in which case nothing is pushed and no events fire).
+     *
+     * Implementation matches mapshaper's `deleteFeature` / `insertFeature`
+     * pair: shape + data record are spliced out (and back in on undo). Within
+     * each layer, deletes proceed in descending-id order so each delete's
+     * index stays valid; a single Ctrl+Z reverses the entire batch.
+     *
+     * The selection is cleared on success — the deleted refs no longer exist.
+     */
+    deleteSelected(): boolean;
+    /**
+     * Drop derived caches (line-layer arc flags + spatial index) for the given
+     * sources. Call after any edit that mutates `layer.shapes` so subsequent
+     * frames and `queryFeatures` calls don't reference stale features.
+     */
+    _invalidateShapeCachesForSources(sourceIds: Iterable<string>): void;
+    /**
+     * Push an executed `EditCommand` onto the undo stack.
+     *
+     * Per the memento pattern, the caller is expected to have already performed
+     * the work; the command captures what changed so the operation can be
+     * reversed on undo. `pushCommand` does NOT call `cmd.do()`. It clears any
+     * pending redo entries and fires `historychange`.
+     */
+    pushCommand(cmd: EditCommand): void;
+    /**
+     * Reverse the most recent command. No-op when there is nothing to undo.
+     * Fires `historychange` and schedules a re-render after the reversal.
+     */
+    undo(): boolean;
+    /**
+     * Re-apply the most recently undone command. No-op when there is nothing
+     * to redo. Fires `historychange` and schedules a re-render.
+     */
+    redo(): boolean;
+    /** Drop every shape-derived cache. Used by undo/redo where per-source
+     *  invalidation isn't tracked. */
+    private _invalidateAllShapeCaches;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    /** Empty both undo and redo stacks. Fires `historychange` if non-empty. */
+    clearHistory(): void;
+    /**
+     * Begin an atomic multi-step edit. Every op or edit command pushed
+     * during the returned transaction's lifetime is staged; on
+     * `commit(label)` they collapse into a single undo entry, on
+     * `rollback()` every touched source's dataset is restored to its
+     * pre-transaction state and the selection is reverted.
+     *
+     * Throws if a transaction is already active — nesting isn't supported.
+     *
+     * @example
+     * const tx = engine.beginTransaction();
+     * const r1 = await engine.ops.clipLayer({ source, target, mask });
+     * if (!r1.ok) { tx.rollback(); return; }
+     * const r2 = await engine.ops.dissolveLayer({ source, target, field: 'STATE' });
+     * if (!r2.ok) { tx.rollback(); return; }
+     * await tx.commit('Process boundaries');
+     */
+    beginTransaction(): Transaction;
+    /**
+     * Bind Ctrl/Cmd+Z (undo) and Ctrl/Cmd+Shift+Z / Ctrl+Y (redo) on the given
+     * element (default: the canvas container). Returns an unbind function. Calls
+     * to this method are idempotent — subsequent calls unbind the prior binding.
+     */
+    bindHistoryShortcuts(target?: HTMLElement): () => void;
+    _fireHistoryChange(): void;
+    /**
+     * Internal — fan out every `'after-commit'` validator and fire
+     * `validationfailed` for the subset whose report is `!ok`. Skipped
+     * cheaply when no validators are registered (no microtask, no
+     * allocations).
+     *
+     * Ignored when the host has been removed mid-flight; the validator
+     * may have started against a dataset that's no longer the current
+     * one but its result is irrelevant once the host is gone.
+     */
+    private _runAfterCommitValidators;
+    /**
+     * Clip a layer to the polygons in a mask layer using mapshaper's `-clip`
+     * pipeline. Target and mask must live in the same source. Returns `true`
+     * on success, `false` for unresolvable source / target / mask.
+     *
+     * The operation is recorded as a single undoable history entry. Note that
+     * dataset-replace operations clear prior fine-grained edit history (see
+     * design.md for the rationale).
+     */
+    /**
+     * Translate every selected feature by `(dx, dy)` in source-data coordinates.
+     * Returns `false` for an empty selection or zero offset.
+     *
+     * Lightweight in-place mutation — does not replace the dataset, does not
+     * clear the selection, composes freely with other commands in one undo
+     * timeline. For multi-source selections, one `FeatureTranslateCommand` is
+     * built per source and they are wrapped in a single `CompositeCommand` so
+     * one undo reverses the whole nudge.
+     *
+     * Known limitation: arcs shared with unselected features will be translated
+     * along with the selection, distorting the unselected neighbours. Safe for
+     * isolated features and contiguous polygon subsets; documented in the spec.
+     */
+    /**
+     * @deprecated Prefer `emap.layers.resolve(sourceId, layerId)`. Kept as a
+     * thin shim while the composed managers migrate over.
+     */
+    _resolveLayer(sourceId: string, layerId: string): MapshaperLayer | null;
+    /**
+     * Tear the map down: cancel pending renders, detach every `data` listener
+     * we attached to sources, release each registered control, kill the worker
+     * pool, and unmount the canvas. Idempotent — calling it twice is safe.
+     *
+     * After `remove()` the instance must not be reused. Public methods that
+     * touch DOM / timers are left in place for now (they will fail naturally
+     * when the underlying resources are gone), but `_scheduleRender` is
+     * guarded so post-teardown event firings don't queue another frame.
+     */
+    remove(): void;
+    /** Read by composed managers via `EmapHostInternal._removed`. */
+    _removed: boolean;
+}

package/dist/map/mapshaper-ops.d.ts

@@ -0,0 +1,56 @@
+import type { EmapHostInternal } from './emap-host';
+import type { OpResult } from './op-result';
+import type { AffineLayerOptions, ApplyExpressionOptions, BufferOptions, CleanOptions, CheckGeometryOptions, ClipEraseOptions, DataFillOptions, DivideOptions, DropLayerOptions, DissolveOptions, ExplodeOptions, FilterFieldsOptions, FilterGeomOptions, FilterIslandsOptions, FilterOptions, FilterSliversOptions, GeometryCheckReport, InnerlinesOptions, IntersectionPointsLayerOptions, JoinTableOptions, LinesOptions, MergeLayersOptions, MosaicOptions, PointsOptions, PolygonsOptions, ProjectOptions, RebuildTopologyOptions, RenameFieldsOptions, RenameLayerOptions, SimplifyOptions, SnapOptions, SortFeaturesOptions, SplitLayerOptions, UniqueFeaturesOptions, UnionOptions } from './types';
+/**
+ * Mapshaper command manager. Owned by Emap and exposed as `emap.ops`.
+ * Every method delegates straight to the corresponding free function
+ * under `src/map/ops/`. Construction takes the host; the per-call
+ * `OpContext` is rebuilt on each access of `_ctx` so test paths that
+ * substitute the manager via `Object.create(MapshaperOps.prototype)`
+ * still see a working context once they wire up the host.
+ */
+export declare class MapshaperOps {
+    private _emap;
+    constructor(_emap: EmapHostInternal);
+    /**
+     * Lazily-built `OpContext` handed to every op function. Recomputed
+     * on every call so nothing captures a stale `this`.
+     */
+    private get _ctx();
+    clipLayer(opts: ClipEraseOptions): Promise<OpResult>;
+    eraseLayer(opts: ClipEraseOptions): Promise<OpResult>;
+    dissolveLayer(opts: DissolveOptions): Promise<OpResult>;
+    bufferLayer(opts: BufferOptions): Promise<OpResult>;
+    applyExpression(opts: ApplyExpressionOptions): Promise<OpResult>;
+    filterFeatures(opts: FilterOptions): Promise<OpResult>;
+    filterIslands(opts: FilterIslandsOptions): Promise<OpResult>;
+    filterSlivers(opts: FilterSliversOptions): Promise<OpResult>;
+    filterGeom(opts: FilterGeomOptions): Promise<OpResult>;
+    explodeLayer(opts: ExplodeOptions): Promise<OpResult>;
+    innerlinesLayer(opts: InnerlinesOptions): Promise<OpResult>;
+    snapLayer(opts: SnapOptions): Promise<OpResult>;
+    cleanLayer(opts: CleanOptions): Promise<OpResult>;
+    mosaicLayer(opts: MosaicOptions): Promise<OpResult>;
+    unionLayers(opts: UnionOptions): Promise<OpResult>;
+    divideLayer(opts: DivideOptions): Promise<OpResult>;
+    pointsLayer(opts: PointsOptions): Promise<OpResult>;
+    linesLayer(opts: LinesOptions): Promise<OpResult>;
+    polygonsLayer(opts: PolygonsOptions): Promise<OpResult>;
+    simplifyLayer(opts: SimplifyOptions): Promise<OpResult>;
+    projectLayer(opts: ProjectOptions): Promise<OpResult>;
+    affineLayer(opts: AffineLayerOptions): Promise<OpResult>;
+    renameLayer(opts: RenameLayerOptions): Promise<OpResult>;
+    mergeLayers(opts: MergeLayersOptions): Promise<OpResult>;
+    splitLayer(opts: SplitLayerOptions): Promise<OpResult>;
+    dropLayer(opts: DropLayerOptions): Promise<OpResult>;
+    sortFeatures(opts: SortFeaturesOptions): Promise<OpResult>;
+    uniqueFeatures(opts: UniqueFeaturesOptions): Promise<OpResult>;
+    filterFields(opts: FilterFieldsOptions): Promise<OpResult>;
+    renameFields(opts: RenameFieldsOptions): Promise<OpResult>;
+    joinTable(opts: JoinTableOptions): Promise<OpResult>;
+    dataFill(opts: DataFillOptions): Promise<OpResult>;
+    rebuildTopology(opts: RebuildTopologyOptions): Promise<OpResult>;
+    checkGeometry(opts: CheckGeometryOptions): Promise<OpResult<GeometryCheckReport>>;
+    intersectionPointsLayer(opts: IntersectionPointsLayerOptions): Promise<OpResult>;
+    mergeSelected(): Promise<OpResult>;
+}

package/dist/map/op-result.d.ts

@@ -0,0 +1,46 @@
+/** Categories of failure surfaced by `MapshaperOps` methods. */
+export type OpError = {
+    kind: 'not-found';
+    what: 'source' | 'layer' | 'mask' | 'divider' | 'field';
+    id: string;
+} | {
+    kind: 'validation';
+    field: string;
+    reason: string;
+} | {
+    kind: 'expression-disabled';
+    operation: string;
+} | {
+    kind: 'mapshaper';
+    cause: unknown;
+    cmd?: string;
+    operation?: string;
+} | {
+    kind: 'host-removed';
+};
+/**
+ * Sum type returned by every op. `ok: true` carries an optional `value`
+ * (most ops have nothing to return; some — like `checkGeometry` — carry
+ * a report); `ok: false` carries the structured `error`.
+ */
+export type OpResult<T = void> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: OpError;
+};
+/** Singleton "successful, no payload" result. Cheap to return. */
+export declare const OK: OpResult<void>;
+/** Build a successful result with a payload value. */
+export declare function okValue<T>(value: T): OpResult<T>;
+export declare const Err: Readonly<{
+    notFound(what: "source" | "layer" | "mask" | "divider" | "field", id: string): OpResult<never>;
+    validation(field: string, reason: string): OpResult<never>;
+    expressionDisabled(operation: string): OpResult<never>;
+    mapshaper(cause: unknown, opts?: {
+        cmd?: string;
+        operation?: string;
+    }): OpResult<never>;
+    hostRemoved(): OpResult<never>;
+}>;

package/dist/map/ops/_context.d.ts

@@ -0,0 +1,41 @@
+import type { EmapHostInternal } from '../emap-host';
+import type { MapshaperDataset } from '../../types/mapshaper-types';
+import type { OpResult } from '../op-result';
+import type { ParsedCommand } from '../../adapter/mapshaper-adapter';
+/**
+ * Run a CLI-style mapshaper command against a source's dataset, snapshotting
+ * for undo and pushing a `DatasetReplaceCommand`. Provided to ops via the
+ * `OpContext` rather than as a method on a class so unit tests can mock the
+ * whole pipeline by injecting a stub function.
+ */
+export type RunDatasetCommand = (sourceId: string, cmd: string, label: string, inputFiles?: Record<string, Uint8Array | string>) => Promise<OpResult>;
+/**
+ * PR-4b parsed-command runner. Same dataset-replace pipeline as
+ * {@link RunDatasetCommand} but accepts pre-built `ParsedCommand[]`. New
+ * ops should prefer this — it skips the CLI parser, eliminating an entire
+ * class of escaping bugs.
+ */
+export type RunDatasetCommandParsed = (sourceId: string, commands: ParsedCommand[], label: string, inputFiles?: Record<string, Uint8Array | string>) => Promise<OpResult>;
+/**
+ * Worker-only path used by `intersectionPointsLayer` / `rebuildTopology`
+ * which bypass `parseCommands` and call mapshaper internals directly to
+ * produce the `after` dataset. Centralised here so the dataset-replace
+ * bookkeeping (history barrier flag, selection clear, render schedule)
+ * stays consistent across every op that produces an `after` snapshot.
+ */
+export type ApplyDatasetReplace = (sourceId: string, before: MapshaperDataset, after: MapshaperDataset, label: string) => OpResult;
+/**
+ * Everything an op function needs from the host. Intentionally narrow —
+ * adding new fields here is a deliberate signal that the op surface is
+ * growing.
+ */
+export interface OpContext {
+    /** Internal host surface (sources, history, selection, worker config…). */
+    host: EmapHostInternal;
+    /** Shared CLI-command runner; see {@link RunDatasetCommand}. */
+    runDatasetCommand: RunDatasetCommand;
+    /** Parsed-command runner (PR-4b); see {@link RunDatasetCommandParsed}. */
+    runDatasetCommandParsed: RunDatasetCommandParsed;
+    /** Direct dataset-replace path; see {@link ApplyDatasetReplace}. */
+    applyDatasetReplace: ApplyDatasetReplace;
+}

package/dist/map/ops/_runner.d.ts

@@ -0,0 +1,55 @@
+import type { MapshaperDataset } from '../../types/mapshaper-types';
+import type { EmapHostInternal } from '../emap-host';
+import { type OpResult } from '../op-result';
+import { type ParsedCommand } from '../../adapter/mapshaper-adapter';
+/**
+ * What a dataset-replace op CHANGES about the dataset. Drives the
+ * selection-preservation policy in `_applyDatasetReplace`:
+ *
+ *   - `shape-count`     — features added / removed / reordered. Selection
+ *                         refs by feature id are stale; clear.
+ *   - `topology-only`   — arc storage rebuilt (clean / snap / simplify /
+ *                         rebuildTopology / mosaic). Feature ids may
+ *                         shift; clear conservatively.
+ *   - `attribute-only`  — only data-table fields changed (each / join /
+ *                         rename-fields / filter-fields / sort / etc.).
+ *                         Feature ids stay; preserve selection.
+ *   - `crs-only`        — coords reprojected, ids unchanged. Preserve.
+ *   - `unknown`         — no information — fall back to clearing for
+ *                         safety. Treated identically to `shape-count`.
+ */
+export type OpEffect = 'shape-count' | 'topology-only' | 'attribute-only' | 'crs-only' | 'unknown';
+/**
+ * Infer the effect category of a CLI command. Considers every `-NAME`
+ * head in the command string and returns the **strongest** effect (in
+ * the order `shape-count` > `topology-only` > `crs-only` > `attribute-only`).
+ * `target` (a no-op selector head) is ignored.
+ */
+export declare function inferEffect(cmd: string): OpEffect;
+/**
+ * Same as {@link inferEffect} but consuming a pre-extracted heads array.
+ * Used by the parsed-command runner so we don't reconstruct then re-parse
+ * a CLI string just to classify the effect.
+ */
+export declare function inferEffectForHeads(heads: string[]): OpEffect;
+export declare function _runDatasetCommand(host: EmapHostInternal, sourceId: string, cmd: string, label: string, inputFiles?: Record<string, Uint8Array | string>): Promise<OpResult>;
+/**
+ * PR-4b parsed-command path. Same dataset-replace pipeline as
+ * {@link _runDatasetCommand} but consumes a pre-built `ParsedCommand[]`
+ * instead of a CLI string. Eliminates the escape/re-parse round-trip
+ * and the class of bugs that come with it.
+ */
+export declare function _runDatasetCommandParsed(host: EmapHostInternal, sourceId: string, commands: ParsedCommand[], label: string, inputFiles?: Record<string, Uint8Array | string>): Promise<OpResult>;
+/**
+ * Stage C in isolation: swap the source dataset, push the
+ * DatasetReplaceCommand (which flags prior commands stale), conditionally
+ * clear selection (PR-10 — depends on `effect`), schedule a render. Used
+ * directly by ops that produce an `after` dataset via mapshaper internal
+ * primitives instead of the CLI runner — `intersectionPointsLayer`,
+ * `rebuildTopology`.
+ *
+ * `effect` defaults to `'unknown'` (= clear selection) for safety. Ops
+ * that know they only changed attributes / CRS should pass the more
+ * specific value so the UI's selection survives the operation.
+ */
+export declare function _applyDatasetReplace(host: EmapHostInternal, sourceId: string, before: MapshaperDataset, after: MapshaperDataset, label: string, effect?: OpEffect): OpResult;