@zwishing/emap 0.1.0

package/dist/renderer/canvas-painter.d.ts

@@ -0,0 +1,50 @@
+import { Painter, DrawOverlayState } from './painter';
+import { AffineTransform } from '../geo/transform';
+import type { ArcCollection, StrokeStyle, PointStyle, VertexDotStyle } from '../types/mapshaper-types';
+export declare class CanvasPainter implements Painter {
+    private _canvas;
+    private _ctx;
+    private _transform;
+    private _pixelRatio;
+    constructor(_canvas: HTMLCanvasElement);
+    setTransform(transform: AffineTransform): void;
+    setPixelRatio(ratio: number): void;
+    drawPaths(shapes: any[], style: StrokeStyle, arcs: ArcCollection): void;
+    drawArcs(arcs: ArcCollection, style: StrokeStyle, filter?: (i: number) => boolean): void;
+    private drawPathSnapping;
+    drawPoints(_shapes: any[], _style: PointStyle): void;
+    /**
+     * Draw vertex dots on the main canvas context.
+     * Called during render() when in vertex edit mode.
+     */
+    drawVertexDots(shapes: any[], arcs: ArcCollection, style?: VertexDotStyle): void;
+    /**
+     * Draw a fill for polygon shapes in vertex edit mode.
+     *
+     * IMPORTANT: Must use getShapeIter (not getArcIter) so that reversed arcs
+     * (~arcId) are traversed backwards, preserving correct polygon winding order.
+     * This is what mapshaper does via ShapeIter and is the reason plain getArcIter
+     * produces incorrect fills (doesn't cover the whole polygon, or fills holes).
+     */
+    drawPolygonFill(shapes: any[], arcs: ArcCollection & {
+        getShapeIter?: (part: number[]) => {
+            x: number;
+            y: number;
+            hasNext(): boolean;
+        };
+    }, fillColor: string, filter?: (i: number) => boolean, 
+    /**
+     * Multiplier on top of `fillColor`'s own alpha. `1` (default) leaves
+     * the colour as-is; `0.5` halves the resulting alpha. Matches MapLibre's
+     * `fill-opacity` semantics — independent of the colour's own alpha.
+     */
+    opacity?: number): void;
+    /**
+     * Draw the in-progress feature creation overlay.
+     * Renders placed vertices, connecting lines, rubber-band line to cursor,
+     * and snap indicator.
+     */
+    drawDrawingOverlay(state: DrawOverlayState): void;
+    clear(): void;
+    resize(width: number, height: number): void;
+}

package/dist/renderer/edit-overlay-renderer.d.ts

@@ -0,0 +1,22 @@
+import type { EditPainter } from './painter';
+import type { EditVertexState, EditDrawState } from '../map/types';
+/**
+ * Draws edit-mode-only decorations on top of the regular layer pass:
+ *   - polygon fill highlight while editing a polygon's vertices
+ *   - vertex dots (with hover affordance) while in vertex mode
+ *   - the in-progress draw overlay while creating a new feature
+ *
+ * Pulled out of `Emap.render()` so the main render loop deals with layers
+ * only and doesn't need to introspect edit-mode flags or downcast the
+ * Painter to a concrete implementation.
+ */
+export declare class EditOverlayRenderer {
+    private _painter;
+    constructor(_painter: EditPainter);
+    /**
+     * Render the edit-mode overlay for the current frame. No-op when
+     * `editMode === 'none'` or the relevant state object is `null`.
+     */
+    render(editMode: 'none' | 'vertex' | 'draw', vertexState: EditVertexState | null, drawState: EditDrawState | null): void;
+    private _renderVertexOverlay;
+}

package/dist/renderer/painter.d.ts

@@ -0,0 +1,52 @@
+import type { AffineTransform } from '../geo/transform';
+import type { ArcCollection, StrokeStyle, PointStyle, VertexDotStyle } from '../types/mapshaper-types';
+/** Geometry kind currently being authored by the draw overlay. */
+export type DrawOverlayGeometryType = 'polygon' | 'polyline' | 'point';
+/** Snap-target kind under the draw cursor. `null` when no target. */
+export type DrawOverlaySnapKind = 'vertex' | 'edge' | null;
+/**
+ * Render-domain state for {@link Painter.drawDrawingOverlay}.
+ * Owned by the renderer so painters do not back-reference `map/`.
+ * The map module re-exports this as `EditDrawState` for back-compat.
+ */
+export interface DrawOverlayState {
+    vertices: [number, number][];
+    cursorCoord: [number, number] | null;
+    snapCoord: [number, number] | null;
+    snapKind: DrawOverlaySnapKind;
+    geometryType: DrawOverlayGeometryType;
+    drawColor: string;
+}
+/**
+ * Stateless drawing primitives: enough to render basemap topology, points,
+ * polygons, and arc highlights. Anything that paints actual map content
+ * should depend on `CorePainter`, not the broader `Painter`/`EditPainter`.
+ */
+export interface CorePainter {
+    drawPaths(shapes: any[], style: StrokeStyle, arcs: ArcCollection): void;
+    drawArcs(arcs: ArcCollection, style: StrokeStyle, filter?: (i: number) => boolean): void;
+    drawPoints(shapes: any[], style: PointStyle): void;
+    drawPolygonFill(shapes: any[], arcs: ArcCollection, fillColor: string, filter?: (i: number) => boolean, opacity?: number): void;
+    clear(): void;
+    resize(width: number, height: number): void;
+    setTransform(transform: AffineTransform): void;
+    setPixelRatio(ratio: number): void;
+}
+/**
+ * Adds the edit-mode-only overlay primitives — vertex dots and the
+ * draw-overlay state machine — on top of `CorePainter`. Code that does
+ * not paint editing affordances should not depend on this interface.
+ */
+export interface EditPainter extends CorePainter {
+    drawVertexDots(shapes: any[], arcs: ArcCollection, style: VertexDotStyle): void;
+    drawDrawingOverlay(state: DrawOverlayState): void;
+}
+/**
+ * Legacy alias preserved for callers that already import `Painter`.
+ * The full painter interface is the edit-aware one because every
+ * existing concrete painter (`CanvasPainter`) implements both halves.
+ */
+export type Painter = EditPainter;
+export interface RenderOptions {
+    antialias?: boolean;
+}

package/dist/shim.d.ts

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

package/dist/source/display-arcs.d.ts

@@ -0,0 +1,49 @@
+import type { ArcCollection } from '../types/mapshaper-types';
+/**
+ * Wraps a Mapshaper ArcCollection and provides Level of Detail (LOD) switching.
+ * For large datasets (>500k points), generates a low-detail copy for faster
+ * rendering at zoomed-out scales.
+ *
+ * Based on Mapshaper's gui-display-arcs.mjs implementation.
+ */
+export declare class DisplayArcs {
+    private _unfilteredArcs;
+    private _filteredArcs;
+    private _filteredSegLen;
+    /**
+     * Set by {@link markDirty} when an in-place edit (translate / vertex move /
+     * shared-arc split / …) mutates the underlying arcs. Cleared the next time
+     * {@link getScaledArcs} actually needs the filtered copy and rebuilds it.
+     *
+     * The flag lets per-frame edit sessions defer the (~O(N)) filtered-copy
+     * rebuild until the renderer asks for it. Most drags happen at zoom levels
+     * where the unfiltered arcs are used directly, so the rebuild often fires
+     * exactly once — at the next zoom-out.
+     */
+    private _dirty;
+    constructor(arcs: ArcCollection);
+    /**
+     * Mark the cached LOD copy stale. Cheap (O(1) flag flip) so callers
+     * inside per-frame drag loops can safely invoke this on every step;
+     * the actual rebuild happens lazily inside {@link getScaledArcs}.
+     *
+     * For datasets below `LARGE_DATASET_THRESHOLD` (no LOD copy ever
+     * created), this is effectively a no-op.
+     */
+    markDirty(): void;
+    private _initFilteredArcs;
+    /**
+     * Returns the appropriate arc collection based on current zoom level.
+     * @param unitsPerPixel - Map units per screen pixel (1 / transform.mx)
+     * @returns Low-detail arcs when zoomed out, full-detail arcs when zoomed in
+     */
+    getScaledArcs(unitsPerPixel: number): ArcCollection;
+    /**
+     * Returns the original (full-detail) arc collection.
+     */
+    getArcs(): ArcCollection;
+    /**
+     * Returns true if a low-detail LOD copy exists.
+     */
+    hasLOD(): boolean;
+}

package/dist/source/layer-utils.d.ts

@@ -0,0 +1,12 @@
+import type { Coord2, MapshaperLayer } from '../types/mapshaper-types';
+/**
+ * Derive a stable layer identifier from a Mapshaper layer object.
+ * Falls back to a positional `layer-N` string.
+ */
+export declare function getLayerId(layer: MapshaperLayer, index: number): string;
+/**
+ * Coerce a mapshaper point shape to a uniform `Coord2[]` (multi-point) form.
+ * Tolerates the legacy bare `[x, y]` single-point shape that some older
+ * datasets carry by wrapping it in a one-element array.
+ */
+export declare function normalizePointShape(shape: unknown): Coord2[];

package/dist/source/mapshaper-runner.d.ts

@@ -0,0 +1,22 @@
+import type { MapshaperDataset } from '../types/mapshaper-types';
+import { type MapshaperAdapter } from '../adapter/mapshaper-adapter';
+/** Files injected into the runner's input cache (e.g. `.shp` payloads). */
+export type RunnerInputFiles = Record<string, Uint8Array | string>;
+export interface MapshaperRunner {
+    /**
+     * Run a mapshaper CLI-style command string and resolve to the first
+     * default-target dataset. Throws on parse / runtime errors.
+     */
+    runImport(cmd: string, inputFiles: RunnerInputFiles): Promise<MapshaperDataset>;
+}
+/**
+ * Production runner that delegates to {@link MapshaperAdapter.runImport}.
+ * Kept as a class so callers can subclass for instrumentation (timing,
+ * telemetry, error remapping).
+ */
+export declare class DefaultMapshaperRunner implements MapshaperRunner {
+    private readonly _adapter;
+    constructor(_adapter?: MapshaperAdapter);
+    runImport(cmd: string, inputFiles: RunnerInputFiles): Promise<MapshaperDataset>;
+}
+export declare function getDefaultMapshaperRunner(): MapshaperRunner;

package/dist/source/source.d.ts

@@ -0,0 +1,80 @@
+import { EventDispatcher } from '../core/events';
+import type { ArcCollection, MapshaperDataset } from '../types/mapshaper-types';
+import type { DisplayArcs } from './display-arcs';
+import type { Bounds } from '../geo/bounds';
+export interface Source extends EventDispatcher {
+    id: string;
+    type: 'topology' | 'geojson';
+    getExtent(): Bounds;
+}
+/** File formats emap can serialize a dataset to. Mirrors the import format set. */
+export type ExportFormat = 'geojson' | 'topojson' | 'shapefile' | 'msx';
+/** Options for {@link TopologySource.export}. */
+export interface ExportOptions {
+    format: ExportFormat;
+}
+export interface TopologySource extends Source {
+    type: 'topology';
+    getArcs(): ArcCollection | undefined;
+    getLayers(): any[];
+    /**
+     * Returns the live mapshaper dataset reference owned by this source.
+     *
+     * **Do not mutate the returned object directly**. Edit-history caches
+     * (arc-flag flags, Flatbush spatial indices, the LOD copy in DisplayArcs)
+     * key off `(layer, shape, arc)` identity and shape/arc counts; mutations
+     * applied outside the official edit-command surface will silently desync
+     * those caches. To change a dataset, route the change through
+     * `Emap.ops.*` (clip / dissolve / buffer / …), `Emap.editSession.*`
+     * (translate / rotate / scale), or a custom `EditCommand`. Read-only
+     * inspection — `getDataset()?.info?.crs_string`, `dataset.layers[0].name`,
+     * arc iteration via `dataset.arcs.getArcIter()` — is always safe.
+     *
+     * The TypeScript return type intentionally stays `MapshaperDataset` (not
+     * `Readonly<MapshaperDataset>`) because mapshaper's own internal helpers
+     * — and a number of in-tree edit commands — receive the dataset and
+     * mutate it through trusted code paths. A blanket `Readonly` would just
+     * force casts everywhere.
+     */
+    getDataset(): MapshaperDataset | undefined;
+    getDisplayArcs(): DisplayArcs | null;
+    /**
+     * Eagerly re-initialize the LOD copy in DisplayArcs from the current
+     * dataset arcs. Use for one-shot mutations that need the new copy ready
+     * immediately. Per-frame in-place edits (drag sessions) should prefer
+     * {@link markDisplayArcsDirty} to defer the rebuild until the renderer
+     * actually needs the filtered copy.
+     */
+    refreshDisplayArcs(): void;
+    /**
+     * Mark the LOD copy stale; the next `getScaledArcs` rebuilds it lazily.
+     * O(1); safe inside per-frame drag callbacks.
+     */
+    markDisplayArcsDirty?(): void;
+    /**
+     * Replace the active dataset (used by undo/redo of dataset-replace commands
+     * and by reproject). Rebuilds DisplayArcs and fires the `data` event so the
+     * map re-renders.
+     */
+    setDataset(dataset: MapshaperDataset): void;
+    /**
+     * Sticky simplification floor (in arc-Z units). Set by the most recent
+     * `-simplify` run via `setDataset`; cleared on a fresh load. The render
+     * loop uses this as a lower-bound for `setRetainedInterval` so the
+     * per-frame zoom-LOD never re-introduces detail the user filtered out.
+     */
+    getSimplifyFloor?(): number;
+    /**
+     * Serialize the current in-memory dataset to a browser `Blob`.
+     *
+     * Always emits full-detail geometry; the source's render-time LOD interval
+     * is restored before the promise resolves.
+     *
+     * - `geojson` / `topojson` — single-file output, returned as `application/json`
+     * - `shapefile` — multi-file output (.shp/.shx/.dbf/.prj), returned as a
+     *   single `application/zip` Blob packed via fflate
+     */
+    export(options: ExportOptions): Promise<Blob>;
+    getCRS?(): string;
+    reproject?(targetCrs: string): Promise<void>;
+}

package/dist/source/topology-source.d.ts

@@ -0,0 +1,145 @@
+import { EventDispatcher } from '../core/events';
+import { TopologySource as ITopologySource } from './source';
+import { Bounds } from '../geo/bounds';
+import { DisplayArcs } from './display-arcs';
+import type { MapshaperDataset } from '../types/mapshaper-types';
+import type { ExportOptions } from './source';
+import { type MapshaperRunner } from './mapshaper-runner';
+export type TopologySourceData = string | {
+    filename: string;
+    content: Uint8Array;
+};
+/**
+ * Input shapes accepted by {@link TopologySource.setData}:
+ * - URL string,
+ * - single `{filename, content}` object,
+ * - or an array of `{filename, content}` for multi-file imports (each file
+ *   becomes its own layer in a single dataset; matches mapshaper's
+ *   `-i FILE1 FILE2 ...` CLI behaviour).
+ */
+export type TopologySourceInput = TopologySourceData | Array<{
+    filename: string;
+    content: Uint8Array;
+}>;
+/**
+ * Resource ceilings applied by {@link TopologySource} when extracting a ZIP
+ * payload. Defaults are intentionally generous so legitimate shapefile zips
+ * keep working unchanged. Apps that load adversarial / public-internet zips
+ * should lower them.
+ */
+export interface ZipExtractionLimits {
+    /** Max summed uncompressed size of all kept entries, in bytes. Default 200 MB. */
+    maxBytes?: number;
+    /** Max entry count fflate may yield. Default 5000. */
+    maxEntries?: number;
+    /** Max `uncompressedTotal / compressedInput` ratio. Default 100. */
+    maxRatio?: number;
+}
+export interface TopologySourceOptions {
+    data?: TopologySourceInput;
+    zipLimits?: ZipExtractionLimits;
+    /**
+     * Optional injection point for the mapshaper command runner used by
+     * the load path. Defaults to a process-wide singleton that calls
+     * `MapshaperAdapter.runImport / runOnDataset` directly.
+     * Tests and instrumentation use this to swap in a mock runner.
+     */
+    mapshaperRunner?: MapshaperRunner;
+}
+export declare class TopologySource extends EventDispatcher implements ITopologySource {
+    id: string;
+    type: 'topology';
+    private _dataset;
+    private _displayArcs;
+    private _options;
+    private _data;
+    private _loadVersion;
+    private _abortController;
+    /**
+     * Sticky simplification floor. mapshaper's `-simplify` writes a
+     * `retainedInterval` into the resulting `ArcCollection`; we cache that
+     * value here so the render loop's per-frame zoom-LOD doesn't stomp it.
+     * Re-captured on every `setDataset` / `setData`.
+     */
+    private _simplifyFloor;
+    private _runner;
+    /** Max-detail threshold the user (or last `-simplify` run) asked for. */
+    getSimplifyFloor(): number;
+    constructor(id: string, options?: TopologySourceOptions);
+    /**
+     * Convenience loader for URL-backed sources.
+     *
+     * Resolves after the first successful `data` event and rejects on the first
+     * load `error`, so callers can safely add the returned source to a map.
+     */
+    static fromUrl(id: string, url: string, options?: Omit<TopologySourceOptions, 'data'>): Promise<TopologySource>;
+    /**
+     * Replace the source's data and trigger a re-import.
+     *
+     * Accepts a URL, a single `{filename, content}` object, or an array of
+     * `{filename, content}` for multi-file imports (each file becomes its own
+     * layer in one dataset — same behaviour as mapshaper's
+     * `-i FILE1 FILE2 ...` CLI invocation).
+     *
+     * Last-write-wins: rapid back-to-back calls supersede each other. Only the
+     * latest call's outcome fires `data` / `error`; in-flight URL fetches from
+     * superseded calls are aborted.
+     */
+    setData(data: TopologySourceInput): this;
+    private _updateData;
+    private _hasSupportedExtension;
+    private _filenameFromContentType;
+    getDataset(): MapshaperDataset | undefined;
+    /**
+     * Canonical CRS identifier for the loaded dataset (`EPSG:NNNN` or a
+     * passthrough label). Heuristics live in {@link resolveDatasetCRS} so the
+     * resolution can be unit-tested independently of TopologySource.
+     */
+    getCRS(): string;
+    reproject(targetCrs: string): Promise<void>;
+    getExtent(): Bounds;
+    getArcs(): any;
+    /**
+     * Returns the DisplayArcs wrapper for LOD support.
+     * Use getScaledArcs(unitsPerPixel) to get the appropriate LOD.
+     */
+    getDisplayArcs(): DisplayArcs | null;
+    /**
+     * Mark the cached LOD copy stale; the next `getScaledArcs()` call inside
+     * the renderer will rebuild it lazily. Cheap (O(1)) so per-frame edit
+     * sessions can call this on every step without paying the rebuild cost
+     * until the user actually zooms out far enough to need the filtered copy.
+     */
+    markDisplayArcsDirty(): void;
+    /**
+     * Eagerly re-initialize DisplayArcs from the current dataset arcs. Use
+     * for one-shot mutations where the caller wants the new LOD copy ready
+     * immediately (project, dataset-replace). Per-frame in-place edits
+     * should prefer {@link markDisplayArcsDirty}.
+     */
+    refreshDisplayArcs(): void;
+    /**
+     * Swap the active dataset. Used by dataset-replace commands (clip / erase /
+     * dissolve / …) and by reproject. Rebuilds the LOD copy and notifies
+     * listeners with the `data` event.
+     */
+    setDataset(dataset: MapshaperDataset): void;
+    /**
+     * Serialize the current dataset to a browser Blob via mapshaper's exporter.
+     *
+     * Multi-file shapefile output is packed into a single zip Blob using fflate
+     * so callers always receive one Blob per call.
+     */
+    export(options: ExportOptions): Promise<Blob>;
+    /**
+     * Pack mapshaper's `[{filename, content}]` output into a single Blob.
+     * Single-file formats use the first entry directly; shapefile is zipped.
+     */
+    private _filesToBlob;
+    getLayers(): any[];
+    private _isZipFile;
+    private _extractZip;
+    private _isTextFile;
+    private _findPrimaryFile;
+    private _isAuxiliaryFile;
+}

package/dist/types/mapshaper-types.d.ts

@@ -0,0 +1,182 @@
+/**
+ * TypeScript interfaces for Mapshaper data structures.
+ * These replace pervasive `any` usage across the codebase.
+ */
+/** Iterator returned by ArcCollection.getArcIter() */
+export interface ArcIterator {
+    x: number;
+    y: number;
+    hasNext(): boolean;
+}
+/** Raw vertex storage exposed by ArcCollection.getVertexData() */
+export interface ArcVertexData {
+    xx: Float64Array;
+    yy: Float64Array;
+    /** Per-vertex simplification thresholds (Visvalingam Z-values). Null if arcs are flat. */
+    zz: Float64Array | null;
+    /** Number of vertices in each arc (length === arc count) */
+    nn: Int32Array | Uint32Array;
+    /** Starting vertex index of each arc within xx/yy (length === arc count) */
+    ii: Int32Array | Uint32Array;
+    /** Per-arc bounding boxes packed as [xmin,ymin,xmax,ymax,...] */
+    bb?: Float64Array;
+}
+/** Mapshaper's ArcCollection — manages all arcs in a dataset */
+export interface ArcCollection {
+    /** Number of arcs (NOT number of points — see getPointCount for that) */
+    size(): number;
+    getArcIter(arcId: number): ArcIterator;
+    getShapeIter?(part: number[]): ArcIterator;
+    forEachSegment?(cb: (i: number, j: number, xx: Float64Array, yy: Float64Array) => void): void;
+    forEachArcSegment?(arcId: number, cb: (i: number, j: number, xx: Float64Array, yy: Float64Array) => void): void;
+    setRetainedInterval?(interval: number): ArcCollection;
+    getRetainedInterval?(): number;
+    getThresholdByPct?(pct: number, nth?: number): number;
+    setThresholds?(zz: Float64Array): void;
+    isFlat?(): boolean;
+    flatten?(): void;
+    getFilteredCopy?(): ArcCollection;
+    getCopy?(): ArcCollection;
+    getPointCount?(): number;
+    getVertexData?(): ArcVertexData;
+    getVertex2?(vertexId: number): [number, number] | null;
+    transformPoints?(cb: (x: number, y: number, arcId?: number) => void | [number, number]): void;
+    /** Replace the arc storage. Triggers a full bounds rebuild internally. */
+    updateVertexData?(nn: Int32Array | Uint32Array, xx: Float64Array, yy: Float64Array, zz: Float64Array | null): void;
+    /** Recompute the bounding box of a single arc after in-place vertex mutation */
+    updateArcBounds?(arcId: number): void;
+    getSimpleShapeBbox?(shapeIds: number[], bbox: number[]): void;
+    arcIsSmaller?(i: number, minLen: number): boolean;
+    arcIntersectsBBox?(i: number, bbox: number[]): boolean;
+}
+export type GeometryType = 'point' | 'polyline' | 'polygon';
+export type PathGeometryType = 'polyline' | 'polygon';
+/**
+ * Mapshaper feature shape vocabulary.
+ *
+ * Path features (polygon / polyline):
+ * - {@link SignedArcId}: a signed arc id; negative values encode reversed
+ *   direction. Use `arcId >= 0 ? arcId : ~arcId` for the absolute id.
+ * - {@link PathPart}: list of signed arc ids that traverse one ring or
+ *   polyline stroke.
+ * - {@link PathShape}: list of parts. Polygons use multiple parts for rings
+ *   (outer + holes); polylines use multiple parts for multipart features.
+ *
+ * Point features:
+ * - {@link Coord2}: a single `[x, y]` pair. Mutable so in-place edits can
+ *   write back through the same array.
+ * - {@link PointShape}: list of points (multi-point features). Some legacy
+ *   mapshaper datasets store a single bare `[x, y]` instead of `[[x, y]]`;
+ *   prefer {@link normalizePointShape} from `source/layer-utils` to coerce.
+ *
+ * `null` is reserved for deleted-but-still-indexed features (mapshaper keeps
+ * positional alignment between `shapes` and `data.records`).
+ */
+export type SignedArcId = number;
+export type PathPart = SignedArcId[];
+export type PathShape = PathPart[];
+export type Coord2 = [number, number];
+export type PointShape = Coord2[];
+/** Legacy single-coord form some older datasets carry. */
+export type LegacyPointShape = Coord2;
+export type FeatureShape = PathShape | PointShape | LegacyPointShape;
+/** Mapshaper DataTable holding feature attributes for a layer */
+export interface DataTable {
+    getRecordAt?(id: number): Record<string, unknown>;
+    getRecords?(): Record<string, unknown>[];
+    getFields?(): string[];
+    size?(): number;
+}
+/**
+ * A single layer within a Mapshaper dataset.
+ *
+ * `shapes` is intentionally typed loosely (`(FeatureShape | null)[] | null`)
+ * because mapshaper itself does not statically tag the array. Use the
+ * {@link isPathLayer} / {@link isPointLayer} type guards to narrow to a
+ * {@link PathLayer} / {@link PointLayer} where shapes carry a precise type.
+ */
+export interface MapshaperLayer {
+    name?: string;
+    id?: string;
+    geometry_type?: GeometryType;
+    shapes: (FeatureShape | null)[] | null;
+    data?: DataTable;
+}
+/** Layer narrowed to path geometry. `shapes[i]` is `PathShape | null`. */
+export interface PathLayer extends MapshaperLayer {
+    geometry_type: PathGeometryType;
+    shapes: (PathShape | null)[] | null;
+}
+/**
+ * Layer narrowed to point geometry. `shapes[i]` is `PointShape | LegacyPointShape | null`;
+ * use {@link normalizePointShape} to coerce to a uniform `Coord2[]`.
+ */
+export interface PointLayer extends MapshaperLayer {
+    geometry_type: 'point';
+    shapes: ((PointShape | LegacyPointShape) | null)[] | null;
+}
+/** True iff `layer.geometry_type` is `'polygon'` or `'polyline'`. */
+export declare function isPathLayer(layer: MapshaperLayer): layer is PathLayer;
+/** True iff `layer.geometry_type` is `'point'`. */
+export declare function isPointLayer(layer: MapshaperLayer): layer is PointLayer;
+/** A Mapshaper dataset containing layers and arcs */
+export interface MapshaperDataset {
+    layers: MapshaperLayer[];
+    arcs?: ArcCollection;
+    info?: {
+        crs_string?: string;
+        prj?: string;
+        /** WKT1 CRS string, sometimes set by importers (e.g. FlatGeobuf, GeoPackage) */
+        wkt1?: string;
+        crs?: {
+            is_latlong?: boolean;
+            projName?: string;
+            a?: number;
+        };
+    };
+    /**
+     * Monotonic counter bumped by every in-place edit (vertex move / insert /
+     * delete, feature translate / affine, shared-arc split). Cache layers that
+     * key off arc geometry — the per-layer Flatbush spatial index, future
+     * arc-flag caches — include this in their cache key so coord-only
+     * mutations auto-invalidate without a manual `clear` call.
+     *
+     * Optional because mapshaper itself doesn't set it; emap initialises to
+     * `0` when first observed via {@link bumpEditVersion}.
+     */
+    editVersion?: number;
+}
+/**
+ * Bump (or initialise to `1`) the dataset's `editVersion` counter. Called
+ * by every in-place edit command at the end of `do()` / `undo()` so the
+ * spatial index sees a fresh cache key on the next query.
+ */
+export declare function bumpEditVersion(dataset: MapshaperDataset | null | undefined): void;
+/** Style for stroke-based rendering (lines, polygon outlines) */
+export interface StrokeStyle {
+    color?: string;
+    width?: number;
+}
+/** Style for point rendering */
+export interface PointStyle {
+    color?: string;
+    radius?: number;
+    fill?: boolean;
+}
+/** Style for vertex dot rendering in edit mode */
+export interface VertexDotStyle {
+    dotColor?: string;
+    dotRadius?: number;
+    hoverVertex?: [number, number] | null;
+    /**
+     * Distinguishes a vertex hover (drawn as a circle) from an interpolated
+     * edge-midpoint hover (drawn as a square — drag-to-insert affordance).
+     * Defaults to `'vertex'` when omitted.
+     */
+    hoverType?: 'vertex' | 'interpolated' | null;
+    hoverColor?: string;
+    hoverRadius?: number;
+    /** Fill color for polygon shapes in vertex edit mode */
+    polygonFill?: string | null;
+    geometryType?: string;
+}

package/dist/ui/basemap-control.d.ts

@@ -0,0 +1,35 @@
+import 'maplibre-gl/dist/maplibre-gl.css';
+import { Control } from './control';
+import { Emap } from '../map/map';
+export interface BasemapStyle {
+    name: string;
+    url: string;
+    type?: 'vector' | 'raster';
+}
+export interface BasemapOptions {
+    styles?: BasemapStyle[];
+    defaultStyle?: string;
+}
+export declare class BasemapControl implements Control {
+    private _map;
+    private _container;
+    private _basemapContainer;
+    private _maplibreMap;
+    private _styles;
+    private _activeStyle;
+    private _isOn;
+    private _syncBasemapBound;
+    constructor(options?: BasemapOptions);
+    onAdd(map: Emap): HTMLElement;
+    private _createBasemapLayer;
+    private _toggleStyle;
+    private _showBasemap;
+    private _initMapLibre;
+    private _setStyle;
+    private _createMapLibreStyle;
+    private _syncBasemap;
+    private _turnOff;
+    private _updateButtons;
+    isOn(): boolean;
+    onRemove(): void;
+}