npm - @zwishing/emap - Versions diffs - 0.1.0 - Mend

@zwishing/emap 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (114) hide show

package/CHANGELOG.md +38 -0
package/LICENSE +373 -0
package/README.md +294 -0
package/SECURITY.md +56 -0
package/dist/adapter/mapshaper-adapter.d.ts +282 -0
package/dist/core/drag-pan-handler.d.ts +28 -0
package/dist/core/events.d.ts +16 -0
package/dist/core/interactions.d.ts +20 -0
package/dist/core/mapshaper-worker-pool.d.ts +151 -0
package/dist/core/tween.d.ts +26 -0
package/dist/edit/commands/composite.d.ts +16 -0
package/dist/edit/commands/dataset-replace.d.ts +43 -0
package/dist/edit/commands/feature-affine.d.ts +72 -0
package/dist/edit/commands/feature-create.d.ts +47 -0
package/dist/edit/commands/feature-delete.d.ts +72 -0
package/dist/edit/commands/feature-property-change.d.ts +34 -0
package/dist/edit/commands/feature-translate.d.ts +55 -0
package/dist/edit/commands/field-add.d.ts +24 -0
package/dist/edit/commands/field-remove.d.ts +20 -0
package/dist/edit/commands/field-rename.d.ts +19 -0
package/dist/edit/commands/split-shared-arcs.d.ts +71 -0
package/dist/edit/commands/vertex-delete.d.ts +26 -0
package/dist/edit/commands/vertex-insert.d.ts +26 -0
package/dist/edit/commands/vertex-move.d.ts +45 -0
package/dist/edit/edit-command.d.ts +72 -0
package/dist/edit/edit-history.d.ts +130 -0
package/dist/edit/transaction.d.ts +59 -0
package/dist/emap-worker.js +1 -0
package/dist/emap.css +157 -0
package/dist/emap.js +5 -0
package/dist/emap.mjs +5 -0
package/dist/geo/bounds.d.ts +18 -0
package/dist/geo/crs-resolver.d.ts +35 -0
package/dist/geo/projection.d.ts +28 -0
package/dist/geo/transform.d.ts +19 -0
package/dist/geo/viewport.d.ts +52 -0
package/dist/index.d.ts +86 -0
package/dist/map/attribute-ops.d.ts +61 -0
package/dist/map/command-args.d.ts +28 -0
package/dist/map/edit-sessions.d.ts +97 -0
package/dist/map/edit-state-store.d.ts +41 -0
package/dist/map/emap-host.d.ts +79 -0
package/dist/map/feature-accessor.d.ts +43 -0
package/dist/map/feature-query.d.ts +58 -0
package/dist/map/highlight-manager.d.ts +17 -0
package/dist/map/layer-registry.d.ts +33 -0
package/dist/map/layer.d.ts +29 -0
package/dist/map/map.d.ts +386 -0
package/dist/map/mapshaper-ops.d.ts +56 -0
package/dist/map/op-result.d.ts +46 -0
package/dist/map/ops/_context.d.ts +41 -0
package/dist/map/ops/_runner.d.ts +55 -0
package/dist/map/ops/affine.d.ts +4 -0
package/dist/map/ops/buffer.d.ts +4 -0
package/dist/map/ops/check-geometry.d.ts +4 -0
package/dist/map/ops/clean.d.ts +4 -0
package/dist/map/ops/clip-erase.d.ts +5 -0
package/dist/map/ops/data-fill.d.ts +4 -0
package/dist/map/ops/dissolve.d.ts +20 -0
package/dist/map/ops/divide.d.ts +4 -0
package/dist/map/ops/drop-layer.d.ts +4 -0
package/dist/map/ops/each-filter.d.ts +5 -0
package/dist/map/ops/explode.d.ts +4 -0
package/dist/map/ops/filter-fields.d.ts +4 -0
package/dist/map/ops/filter-geom.d.ts +4 -0
package/dist/map/ops/filter-islands.d.ts +4 -0
package/dist/map/ops/filter-slivers.d.ts +4 -0
package/dist/map/ops/innerlines.d.ts +4 -0
package/dist/map/ops/intersection-points.d.ts +4 -0
package/dist/map/ops/join-table.d.ts +4 -0
package/dist/map/ops/lines.d.ts +4 -0
package/dist/map/ops/merge-layers.d.ts +4 -0
package/dist/map/ops/mosaic.d.ts +4 -0
package/dist/map/ops/points.d.ts +4 -0
package/dist/map/ops/polygons.d.ts +4 -0
package/dist/map/ops/project.d.ts +4 -0
package/dist/map/ops/rebuild-topology.d.ts +4 -0
package/dist/map/ops/rename-fields.d.ts +4 -0
package/dist/map/ops/rename-layer.d.ts +4 -0
package/dist/map/ops/simplify.d.ts +4 -0
package/dist/map/ops/snap.d.ts +4 -0
package/dist/map/ops/sort-features.d.ts +4 -0
package/dist/map/ops/split-layer.d.ts +4 -0
package/dist/map/ops/union.d.ts +4 -0
package/dist/map/ops/unique-features.d.ts +4 -0
package/dist/map/selection.d.ts +73 -0
package/dist/map/types.d.ts +1072 -0
package/dist/map/worker-routing.d.ts +40 -0
package/dist/mapshaper-vendor.js +1 -0
package/dist/renderer/canvas-painter.d.ts +50 -0
package/dist/renderer/edit-overlay-renderer.d.ts +22 -0
package/dist/renderer/painter.d.ts +52 -0
package/dist/shim.d.ts +1 -0
package/dist/source/display-arcs.d.ts +49 -0
package/dist/source/layer-utils.d.ts +12 -0
package/dist/source/mapshaper-runner.d.ts +22 -0
package/dist/source/source.d.ts +80 -0
package/dist/source/topology-source.d.ts +145 -0
package/dist/types/mapshaper-types.d.ts +182 -0
package/dist/ui/basemap-control.d.ts +35 -0
package/dist/ui/box-select-control.d.ts +67 -0
package/dist/ui/control.d.ts +6 -0
package/dist/ui/draw-feature-control.d.ts +82 -0
package/dist/ui/edit-toolbar.d.ts +27 -0
package/dist/ui/history-control.d.ts +29 -0
package/dist/ui/lasso-select-control.d.ts +96 -0
package/dist/ui/navigation-control.d.ts +16 -0
package/dist/ui/simplify-control.d.ts +40 -0
package/dist/ui/status-control.d.ts +23 -0
package/dist/ui/vertex-edit-control.d.ts +111 -0
package/dist/validation/builtin/topology.d.ts +19 -0
package/dist/validation/registry.d.ts +23 -0
package/dist/validation/validator.d.ts +47 -0
package/package.json +90 -0

package/README.md ADDED Viewed

@@ -0,0 +1,294 @@
+# emap
+A topology-oriented geographic map rendering and editing engine built around [Mapshaper](https://github.com/mbloch/mapshaper) data structures and HTML5 Canvas. Browser-only, framework-agnostic TypeScript.
+## What you get
+- **Topology rendering** — draws shared-arc datasets directly without re-tessellating per layer
+- **Loaders** — GeoJSON, TopoJSON, ZIP Shapefile (with per-archive resource limits)
+- **Editing** — pan / wheel-zoom / hover, plus vertex, feature, and topology-aware editing
+- **30+ data ops** under `emap.ops.*` — clip, erase, dissolve, buffer, simplify, project, snap, clean, mosaic, union, divide, points / lines / polygons conversions, join-table, filter, sort, uniq, split, merge, rename, …
+- **Worker pool** — expensive ops dispatch to off-thread workers automatically based on dataset size + command family
+- **Undo / redo** with command coalescing, dataset-replace barriers, and structured `OpResult` errors
+- **Selection model** — single / multi / box / lasso, with attribute-only ops preserving feature ids
+- **Snapshots** — pack / unpack a full session (datasets + history) to a compact binary blob
+- **HTML5 Canvas 2D rendering** — `CanvasPainter` with batched-stroke optimization for large topology datasets
+- **Built-in controls** — navigation, status, basemap, vertex edit, feature draw, history, box / lasso selection
+## Install
+```bash
+pnpm add emap
+# or
+npm install emap
+```
+## Hello map
+```html
+<!DOCTYPE html>
+<html>
+  <head>
+    <link rel="stylesheet" href="node_modules/emap/dist/emap.css" />
+    <style>#map { width: 100vw; height: 100vh; margin: 0; }</style>
+  </head>
+  <body>
+    <div id="map"></div>
+    <script src="node_modules/emap/dist/mapshaper-vendor.js"></script>
+    <script src="node_modules/emap/dist/emap.js"></script>
+    <script>
+      const { Emap, TopologySource, NavigationControl, EditToolbar } = emap;
+      const map = new Emap({ container: 'map' });
+      map.addControl(new NavigationControl(), 'top-left');
+      map.addControl(new EditToolbar(), 'top-left');
+      (async () => {
+        const source = await TopologySource.fromUrl(
+          'china',
+          'https://geojson.cn/api/china/1.6.3/china.topo.json',
+        );
+        map.addSource('china', source);
+        map.setExtent(source.getExtent());
+      })();
+    </script>
+  </body>
+</html>
+```
+Live demos in `test/examples/*.html` cover every feature area below.
+## API tour
+### Core map
+```ts
+const map = new Emap({ container: 'map' });
+map.addSource(id, source);
+map.addLayer({ id, source: 'china', type: 'fill', paint: { 'fill-color': '#eee' } });
+map.setExtent(source.getExtent());
+map.queryFeatures(point, { layers: ['borders'] });
+map.on('click', (e) => { /* … */ });
+```
+### Sources
+```ts
+const source = await TopologySource.fromUrl('id', url);     // GeoJSON / TopoJSON / ZIP
+const source2 = await TopologySource.fromBytes('id', buf);  // ArrayBuffer / Uint8Array
+source.getExtent();
+source.getLayers();
+```
+### Editing operations (`emap.ops`)
+All ops return `Promise<OpResult>` — a discriminated `{ ok: true, value? } | { ok: false, error: OpError }`. Errors are typed (`not-found`, `validation`, `expression-disabled`, `mapshaper`, `host-removed`).
+```ts
+// Whole-dataset CLI ops
+await map.ops.clipLayer({ source: 'roads', target: 'streets', mask: 'park' });
+await map.ops.dissolveLayer({ source: 'us', target: 'counties', field: 'STATE' });
+await map.ops.bufferLayer({ source: 'roads', target: 'streets', radius: 50 });
+await map.ops.simplifyLayer({ source: 'world', percentage: 10 });
+await map.ops.projectLayer({ source: 'world', crs: 'EPSG:3857' });
+// Layer management
+await map.ops.renameLayer({ source: 's', target: 'old', name: 'new' });
+await map.ops.mergeLayers({ source: 's', targets: ['a', 'b'], name: 'combined' });
+await map.ops.splitLayer({ source: 's', target: 'us', expression: 'STATE' });
+await map.ops.dropLayer({ source: 's', target: 'tmp' });
+// Attribute / data
+await map.ops.applyExpression({ source: 's', target: 'l', expression: 'this.area = $.area' });
+await map.ops.filterFeatures({ source: 's', target: 'l', expression: 'this.pop > 1e6' });
+await map.ops.joinTable({
+  source: 's', target: 'states',
+  data: { csv: csvBytes }, keys: ['STATE_FIPS', 'fips'],
+});
+// Topology repair / inspection
+await map.ops.cleanLayer({ source: 's', target: 'l' });
+await map.ops.snapLayer({ source: 's', target: 'l', interval: 0.001 });
+const report = await map.ops.checkGeometry({ source: 's' });
+//  → { ok: true, value: { ok, intersections: [...], intersectionCount } }
+// Selection-driven
+await map.ops.mergeSelected();
+```
+A full list of ops + their option types lives in `src/index.ts` (search for `*Options`).
+### Transactions
+Stage multiple ops as one atomic edit — commit collapses them into a single undo entry, rollback restores every touched source's dataset (and the selection) to the pre-transaction state.
+```ts
+const tx = map.beginTransaction();
+const r1 = await map.ops.clipLayer({ source, target, mask });
+if (!r1.ok)        { tx.rollback(); return; }
+const r2 = await map.ops.dissolveLayer({ source, target, field: 'STATE' });
+if (!r2.ok)        { tx.rollback(); return; }
+await tx.commit('Process boundaries');
+```
+Nesting is not supported — opening a transaction while one is active throws.
+### Undo / redo
+```ts
+map.undo();
+map.redo();
+map.clearHistory();
+map.on('historychange', (e) => {
+  console.log(e.canUndo, e.canRedo, e.label);
+});
+```
+Vertex drags / feature translates within a session merge into one undo step. Dataset-replace ops (clip, dissolve, …) keep prior commands in the stack but flag them as `stale` for the UI to render appropriately — there's no destructive `clear`.
+### Validation hooks
+Register validators that run after every committed edit. Failures fire `validationfailed` — the engine doesn't auto-undo, the app decides.
+```ts
+import { topologyValidator } from 'emap';
+const unregister = map.validators.register(topologyValidator({
+  sources: ['china'],
+}));
+map.on('validationfailed', (e) => {
+  console.warn(e.results);    // [{ validator, report }, ...]
+  // Optionally: map.undo();
+});
+```
+Custom validators implement `Validator { name, phase: 'after-commit', run(host, change) }` and return `{ ok, issues: [{ severity, message, ref? }] }`.
+### Feature accessor
+Read one feature (or iterate a layer) without indexing into raw `layer.shapes` / `layer.data.getRecords()`:
+```ts
+const f = map.features.get({ source: 'us', layer: 'states', id: 12 });
+if (f) console.log(f.properties.NAME, f.geometry);
+for (const f of map.features.iter('us', 'states')) {
+  /* … */
+}
+map.features.count('us', 'states'); // O(1)
+```
+`f.properties` is `Object.freeze`d so accidental mutation can't leak back into the dataset.
+### Selection
+```ts
+map.selection.add({ source: 'us', layer: 'counties', id: 42 });
+map.selection.toggle(ref);
+map.selection.clear();
+map.on('selectionchange', (e) => {
+  console.log(e.added, e.removed, e.current);
+});
+```
+Attribute-only ops (each / join / rename-fields / sort) preserve the selection across the operation. Shape-changing or topology-rebuilding ops clear it.
+### Worker offloading
+```ts
+const map = new Emap({
+  container: 'map',
+  workerUrl: '/emap-worker.js',     // built alongside dist/emap.js
+  workerMode: 'auto',                // 'auto' | true | false
+  workerThreshold: 200_000,          // vertex count
+  workerPoolSize: 2,                 // multiple workers (PR-22a)
+});
+map.on('workerjobstart', (e) => console.log('start', e.label));
+map.on('workerjobend',   (e) => console.log('end',   e.durationMs));
+```
+The router classifies each op as cheap / expensive and overrides the threshold accordingly. Override the decision globally with `MapOptions.workerRouting?: (info) => boolean`.
+### Snapshots
+```ts
+const blob = await map.exportSnapshot();           // → Uint8Array
+await map.loadSnapshot(blob);                       // restore datasets + history
+```
+The export is a mapshaper-pack with magic-byte validation on load.
+### Controls
+| Control | Purpose |
+|---|---|
+| `NavigationControl` | Zoom in/out + reset |
+| `StatusControl` | Cursor coordinates + EPSG |
+| `BasemapControl` | MapLibre raster basemap toggle |
+| `EditToolbar` | Mode switcher (vertex / feature / draw) |
+| `VertexEditControl` | Topology-aware vertex dragging |
+| `DrawFeatureControl` | Polygon / polyline / point drawing with edge snapping |
+| `HistoryControl` | Visual undo/redo stack with stale-entry markers |
+| `BoxSelectControl` | Drag-to-select bounding box |
+| `LassoSelectControl` | Free-form selection lasso |
+All controls implement `onAdd(map)` / `onRemove()` and accept `'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'`.
+## Architecture
+```
+src/
+├── map/                  # Emap orchestrator, ops facade, selection, history
+│   └── ops/              # one file per data op (clip, dissolve, buffer, …)
+├── adapter/              # MapshaperAdapter — sole bridge to mapshaper.internal.*
+├── source/               # TopologySource, DisplayArcs (LOD)
+├── core/                 # EventDispatcher, MapshaperWorkerPool, drag/wheel
+├── geo/                  # Viewport, Projection, Bounds, AffineTransform, CRS resolver
+├── renderer/             # CanvasPainter (HTML5 Canvas 2D)
+├── edit/                 # EditHistory + per-command memento classes
+├── ui/                   # Control implementations + controls.css
+├── worker/               # off-thread mapshaper entry
+└── types/                # central mapshaper type definitions
+```
+Design pillars:
+- **One adapter, no leaks.** `MapshaperAdapter` is the only place `mapshaper.internal.*` is touched. Tests stub it; future mapshaper upgrades reroute through it.
+- **Structured commands, no string-build.** Ops emit `ParsedCommand[]` directly — there is no CLI string between the op and mapshaper, on either thread.
+- **Memento commands.** Every edit captures enough state to round-trip do/undo without referencing live dataset internals.
+- **Effect-aware dataset replace.** Each op declares whether it changes shape / topology / attributes / CRS; selection is preserved or cleared accordingly.
+- **Affine coordinate math everywhere.** All viewport conversions pass through `AffineTransform`, never ad-hoc matrix math.
+- **Batch rendering.** `CanvasPainter` groups 25 paths per `stroke()` — measured optimization for large topology datasets.
+## Development
+```bash
+pnpm install
+npm run dev          # watch + sourcemaps
+npm run dev-build    # one-shot dev build
+npm run build        # production (minified) + .d.ts
+npm test             # vitest, ~760 unit tests
+npm run typecheck    # strict tsc
+```
+Build outputs in `dist/`:
+- `emap.js` — production IIFE bundle
+- `emap.mjs` — ES module
+- `emap-dev.js` — dev bundle with sourcemaps
+- `emap-worker.js` — worker entry
+- `mapshaper-vendor.js` — mapshaper vendor bundle (load before `emap.js` in IIFE mode)
+- `index.d.ts` — TypeScript declarations
+Manual testing: open any `test/examples/*.html` after building.
+## License
+[MPL-2.0](LICENSE)

package/SECURITY.md ADDED Viewed

@@ -0,0 +1,56 @@
+# Security
+## Expression evaluation policy
+Several `MapshaperOps` APIs accept JavaScript expression strings that
+mapshaper executes inside its own runner:
+- `applyExpression({ expression })`
+- `filterFeatures({ expression })`
+- `sortFeatures({ expression })`
+- `splitLayer({ expression })`
+- `joinTable({ where, calc })`
+- `mosaicLayer({ calc })`
+- ... and any other op that forwards `where=` / `calc=` to mapshaper.
+These expressions execute with full access to the JavaScript runtime
+(no sandbox). Treating an externally-supplied expression string as data
+is a remote code execution vulnerability.
+### Default: `'disabled'`
+`Emap` defaults `expressionPolicy` to `'disabled'`. Calls that carry a
+non-empty expression string return `false` and emit an `error` event
+with the message `"<op>: expression evaluation is disabled"`.
+### Opting in: `'trusted'`
+Apps that load only their own data — and never accept layer config,
+filter strings, or join expressions from end users or third-party
+sources — can opt in:
+```ts
+const map = new Emap({ container: 'map', expressionPolicy: 'trusted' });
+// or, to flip at runtime
+map.setExpressionPolicy('trusted');
+```
+Set the policy back to `'disabled'` before processing any
+externally-sourced strings.
+### Breaking change
+Prior to this release the default was `'trusted'`. Apps that broke
+after upgrading should either:
+1. Pass `expressionPolicy: 'trusted'` if all expression strings are
+   first-party and audited, or
+2. Stop forwarding user-supplied strings to expression-accepting APIs
+   and keep the secure default.
+## Reporting a vulnerability
+Please report security issues via GitHub's "Report a vulnerability"
+flow on this repository. Do not open public issues for unpatched
+security bugs.

package/dist/adapter/mapshaper-adapter.d.ts ADDED Viewed

@@ -0,0 +1,282 @@
+import type { ArcCollection, MapshaperDataset, MapshaperLayer } from '../types/mapshaper-types';
+/** Plain-object form produced by `exportDatasetsToPack` / consumed by `restoreSessionData`. */
+export type PackedSession = Record<string, unknown> & {
+    datasets?: unknown[];
+};
+/** Single export-file output — `exportFileContent` / `exportPackedDatasets` shape. */
+export interface ExportedFile {
+    filename: string;
+    content: string | Uint8Array | ArrayBuffer;
+}
+/** A single segment-intersection record; mapshaper carries extra fields we don't expose. */
+export interface SegmentIntersection {
+    x: number;
+    y: number;
+    [key: string]: unknown;
+}
+/** Bounding box returned by `getDatasetBounds` / `getLayerBounds`. */
+export interface MapshaperBBox {
+    xmin: number;
+    ymin: number;
+    xmax: number;
+    ymax: number;
+}
+/**
+ * One entry in a parsed mapshaper command pipeline. Equivalent to what
+ * `parseCommands('-clip source=mask')` returns: a `name` (kebab-case op
+ * name like `'clip'`, `'rename-layers'`, `'filter-fields'`) plus an
+ * `options` bag whose keys match mapshaper's snake_case internal naming
+ * (e.g. `cap_style`, `gap_fill_area`, `no_replace`).
+ *
+ * Hand-built ParsedCommands skip mapshaper's CLI parser entirely, which
+ * removes the quoting / escaping concern that drove PR-4 phase 1: option
+ * values are typed JS values (`string`, `number`, `boolean`, `string[]`)
+ * rather than tokens interpolated into a shell-like grammar.
+ *
+ * Op modules under `src/map/ops/` build these directly via
+ * `OpContext.runDatasetCommand(commands, ...)`.
+ */
+export interface ParsedCommand {
+    name: string;
+    options: Record<string, unknown>;
+}
+/** Files injected onto a `-i` command's `input` option. */
+export type RunnerInputFiles = Record<string, Uint8Array | string>;
+/**
+ * The mapshaper internal API surface the editor depends on. Methods are
+ * grouped by purpose to make it obvious which mapshaper subsystem each one
+ * pokes; signatures match the underlying mapshaper functions exactly so the
+ * default adapter implementation can stay a one-line delegation.
+ */
+export interface MapshaperAdapter {
+    /**
+     * Move every vertex in `vertexIds` to `to`, preserving topology. Mapshaper
+     * mutates the per-arc `xx`/`yy` slices in place and updates affected arc
+     * bounds. Used by VertexMoveCommand for both do() and undo().
+     */
+    snapVertices(vertexIds: number[], to: [number, number], arcs: ArcCollection): void;
+    /**
+     * Insert `point` immediately before the vertex at index `vertexIndex`,
+     * shifting the rest of the arc forward. Returns the index of the newly
+     * inserted vertex (== `vertexIndex` of the original arg).
+     *
+     * Note: the underlying mapshaper signature is `(arcs, i, point)` — there
+     * is no separate `arcId` parameter; mapshaper resolves the arc internally
+     * from the global vertex index. The tuple-based naming in the plan was
+     * inaccurate; this signature matches actual mapshaper.
+     */
+    insertVertex(arcs: ArcCollection, vertexIndex: number, point: [number, number]): void;
+    /** Remove the vertex at the given global vertex index. */
+    deleteVertex(arcs: ArcCollection, vertexIndex: number): void;
+    /** Append a new empty arc to the collection; subsequent `appendVertex`
+     *  calls write into it. */
+    appendEmptyArc(arcs: ArcCollection): void;
+    /**
+     * Append `[x, y]` onto the arc most recently created via `appendEmptyArc`.
+     * Mapshaper resolves the target arc implicitly; pass the coord pair
+     * directly (mapshaper accepts `[x, y]` rather than separate args).
+     */
+    appendVertex(arcs: ArcCollection, point: [number, number]): void;
+    /** Pop the most recently appended arc. Used by FeatureCreateCommand.undo. */
+    deleteLastArc(arcs: ArcCollection): void;
+    /**
+     * Find every vertex id that shares the same topological node as the
+     * vertex closest to `point` within the given `shape`. Returns an empty
+     * array when no vertex is close enough.
+     */
+    findNearestVertices(point: [number, number], shape: number[][], arcs: ArcCollection): number[];
+    /**
+     * Resolve a global vertex index back to its parent arc id, given the
+     * `ii` (per-arc start-index) array from `ArcCollection.getVertexData()`.
+     * Used by VertexEditControl when mapping a vertex hit to a single arc.
+     */
+    findArcIdFromVertexId(vertexId: number, ii: Int32Array | Uint32Array): number;
+    /**
+     * `true` iff the vertex at `idx` is the start- or end-vertex of its
+     * arc — those endpoints are shared topological nodes and cannot be
+     * deleted without breaking adjacency.
+     */
+    vertexIsArcEndpoint(idx: number, arcs: ArcCollection): boolean;
+    /**
+     * Walk every segment of every arc referenced by `shape`, invoking `cb`
+     * with the (i, j) global-vertex pair plus the shared `xx` / `yy`
+     * arrays. Used by VertexEditControl to find the closest edge under
+     * the cursor for drag-to-insert.
+     */
+    forEachSegmentInShape(shape: number[][], arcs: ArcCollection, cb: (i: number, j: number, xx: Float64Array, yy: Float64Array) => void): void;
+    /**
+     * Project (px, py) onto the segment from (ax, ay) to (bx, by). The
+     * returned coord is clamped to the segment endpoints when the
+     * projection falls outside them. `snapArg` mirrors mapshaper's
+     * snap-tolerance argument and is forwarded as-is.
+     */
+    findClosestPointOnSeg(px: number, py: number, ax: number, ay: number, bx: number, by: number, snapArg: number): [number, number];
+    /**
+     * Pre-pass run by every overlay command (clip / dissolve / union / …):
+     * inserts vertices at every detected segment intersection and rebuilds
+     * shared-arc topology. Mutates `dataset.arcs` in place. Surfaces as
+     * `Emap.ops.rebuildTopology()` when called explicitly.
+     */
+    addIntersectionCuts(dataset: MapshaperDataset, opts?: {
+        snap_interval?: number;
+        no_snap?: boolean;
+        rebuild_topology?: boolean;
+    }): void;
+    /**
+     * Read-only segment-intersection scan; populates the report consumed
+     * by `Emap.ops.checkGeometry`. Does NOT mutate the arcs.
+     */
+    findSegmentIntersections(arcs: ArcCollection, opts?: {
+        tolerance?: number;
+    }): SegmentIntersection[];
+    /**
+     * Materialise a multi-point layer at every intersection found by
+     * {@link findSegmentIntersections}. Used by
+     * `Emap.ops.intersectionPointsLayer` to expose intersections as a
+     * pickable / editable layer.
+     */
+    getIntersectionLayer(intersections: SegmentIntersection[], target: MapshaperLayer, arcs: ArcCollection): MapshaperLayer;
+    /**
+     * Average segment length across the arc collection. Used by
+     * `DisplayArcs` to pick a sensible per-frame simplification floor.
+     */
+    getAvgSegment(arcs: ArcCollection): number;
+    /**
+     * Fast (non-Visvalingam) simplification: drops vertices below a
+     * length threshold. Used to pre-build a coarse "always-on" LOD copy
+     * the renderer falls back to at zoomed-out scales.
+     */
+    simplifyArcsFast(arcs: ArcCollection, segLength: number): ArcCollection;
+    /**
+     * Returns `true` iff the layer carries renderable shape data (a
+     * `geometry_type` plus a non-empty `shapes` array). Used by the
+     * projection module to decide whether a layer participates in the
+     * extent rebuild.
+     */
+    layerHasGeometry(layer: MapshaperLayer): boolean;
+    /**
+     * Bounds of one layer's shapes against an arc collection. Returns a
+     * mapshaper-internal Bounds-like object — typed loosely because the
+     * caller only reads `xmin/ymin/xmax/ymax`.
+     */
+    getLayerBounds(layer: MapshaperLayer, arcs?: ArcCollection): MapshaperBBox;
+    /** Bounding box across every layer in the dataset. */
+    getDatasetBounds(dataset: MapshaperDataset): MapshaperBBox;
+    /**
+     * Pack one or more datasets into a structured-clone-friendly object
+     * suitable for `postMessage` (worker round-trips) or
+     * {@link pack} (`.msx` snapshot bytes). `compact: true` bakes
+     * simplification thresholds into `zz` and gzip-compresses arc
+     * buffers; `false` skips that for the worker pipeline.
+     */
+    exportDatasetsToPack(datasets: MapshaperDataset[], opts?: {
+        compact?: boolean;
+    }): Promise<PackedSession>;
+    /**
+     * Inverse of {@link exportDatasetsToPack}. Decodes a packed session
+     * (typically produced by the worker) back into live datasets.
+     */
+    restoreSessionData(packed: PackedSession): Promise<{
+        datasets: MapshaperDataset[];
+    }>;
+    /** Materialise a `.msx` snapshot byte buffer from a packed session. */
+    pack(obj: PackedSession): Uint8Array;
+    /** Inverse of {@link pack}: `.msx` bytes → packed session object. */
+    unpackSessionData(bytes: Uint8Array): Promise<PackedSession>;
+    /** Convenience: pack + bytes in one call (`.msx` export pipeline). */
+    exportPackedDatasets(datasets: MapshaperDataset[], opts?: {
+        compact?: boolean;
+    }): Promise<ExportedFile[]>;
+    /** Plain-text export (GeoJSON / TopoJSON). */
+    exportFileContent(dataset: MapshaperDataset, opts: {
+        format: string;
+    }): ExportedFile[];
+    /**
+     * Deep copy of `dataset` — separate arc storage, separate per-layer shape
+     * arrays. mapshaper's `_runDatasetCommand` snapshots this for undo before
+     * letting the in-place clip / dissolve / buffer pipeline run.
+     */
+    copyDataset(dataset: MapshaperDataset): MapshaperDataset;
+    /**
+     * Run a CLI-style command string starting with `-i` (import) and resolve
+     * with the first default-target dataset. `inputFiles` is injected as the
+     * import command's `input` option, matching the GUI import path.
+     */
+    runImport(cmd: string, inputFiles: RunnerInputFiles): Promise<MapshaperDataset>;
+    /**
+     * Run a CLI-style command (sans `-i`) against an existing dataset and
+     * resolve with the resulting dataset. `inputFiles` is forwarded to every
+     * parsed command's `options.input` so `-join FILE` / similar can resolve
+     * relative names. Rejects if mapshaper produced no default target
+     * (no-op command — see PR-21 / L1).
+     */
+    runOnDataset(cmd: string, dataset: MapshaperDataset, inputFiles?: RunnerInputFiles): Promise<MapshaperDataset>;
+    /**
+     * Variant of {@link runOnDataset} that accepts a pre-parsed
+     * `ParsedCommand[]` and skips the CLI parser entirely. Op modules
+     * use this so option values flow as typed JS (numbers / arrays /
+     * booleans) rather than as tokens interpolated into a shell-like
+     * grammar — eliminates the entire quoting / escaping concern.
+     *
+     * `inputFiles` is wired onto every command's `options.input` exactly
+     * like the string variant, so `-join FILE` works the same way.
+     */
+    runOnDatasetParsed(commands: ParsedCommand[], dataset: MapshaperDataset, inputFiles?: RunnerInputFiles): Promise<MapshaperDataset>;
+}
+export declare class DefaultMapshaperAdapter implements MapshaperAdapter {
+    snapVertices(vertexIds: number[], to: [number, number], arcs: ArcCollection): void;
+    insertVertex(arcs: ArcCollection, vertexIndex: number, point: [number, number]): void;
+    deleteVertex(arcs: ArcCollection, vertexIndex: number): void;
+    appendEmptyArc(arcs: ArcCollection): void;
+    appendVertex(arcs: ArcCollection, point: [number, number]): void;
+    deleteLastArc(arcs: ArcCollection): void;
+    findNearestVertices(point: [number, number], shape: number[][], arcs: ArcCollection): number[];
+    findArcIdFromVertexId(vertexId: number, ii: Int32Array | Uint32Array): number;
+    vertexIsArcEndpoint(idx: number, arcs: ArcCollection): boolean;
+    forEachSegmentInShape(shape: number[][], arcs: ArcCollection, cb: (i: number, j: number, xx: Float64Array, yy: Float64Array) => void): void;
+    findClosestPointOnSeg(px: number, py: number, ax: number, ay: number, bx: number, by: number, snapArg: number): [number, number];
+    addIntersectionCuts(dataset: MapshaperDataset, opts?: {
+        snap_interval?: number;
+        no_snap?: boolean;
+        rebuild_topology?: boolean;
+    }): void;
+    findSegmentIntersections(arcs: ArcCollection, opts?: {
+        tolerance?: number;
+    }): SegmentIntersection[];
+    getIntersectionLayer(intersections: SegmentIntersection[], target: MapshaperLayer, arcs: ArcCollection): MapshaperLayer;
+    getAvgSegment(arcs: ArcCollection): number;
+    simplifyArcsFast(arcs: ArcCollection, segLength: number): ArcCollection;
+    layerHasGeometry(layer: MapshaperLayer): boolean;
+    getLayerBounds(layer: MapshaperLayer, arcs?: ArcCollection): MapshaperBBox;
+    getDatasetBounds(dataset: MapshaperDataset): MapshaperBBox;
+    exportDatasetsToPack(datasets: MapshaperDataset[], opts?: {
+        compact?: boolean;
+    }): Promise<PackedSession>;
+    restoreSessionData(packed: PackedSession): Promise<{
+        datasets: MapshaperDataset[];
+    }>;
+    pack(obj: PackedSession): Uint8Array;
+    unpackSessionData(bytes: Uint8Array): Promise<PackedSession>;
+    exportPackedDatasets(datasets: MapshaperDataset[], opts?: {
+        compact?: boolean;
+    }): Promise<ExportedFile[]>;
+    exportFileContent(dataset: MapshaperDataset, opts: {
+        format: string;
+    }): ExportedFile[];
+    copyDataset(dataset: MapshaperDataset): MapshaperDataset;
+    runImport(cmd: string, inputFiles: RunnerInputFiles): Promise<MapshaperDataset>;
+    runOnDataset(cmd: string, dataset: MapshaperDataset, inputFiles?: RunnerInputFiles): Promise<MapshaperDataset>;
+    runOnDatasetParsed(commands: ParsedCommand[], dataset: MapshaperDataset, inputFiles?: RunnerInputFiles): Promise<MapshaperDataset>;
+}
+/**
+ * Process-wide singleton adapter. Constructed lazily on first access so
+ * importing this module doesn't pay the mapshaper bundle cost up-front for
+ * call sites that inject their own adapter explicitly.
+ */
+export declare function getDefaultMapshaperAdapter(): MapshaperAdapter;
+/**
+ * Swap the process-wide adapter — tests use this to inject a mock that
+ * records calls without invoking the real mapshaper bundle. Pass `null` to
+ * reset to the lazy-default behaviour.
+ */
+export declare function setDefaultMapshaperAdapter(adapter: MapshaperAdapter | null): void;

package/dist/core/drag-pan-handler.d.ts ADDED Viewed

@@ -0,0 +1,28 @@
+import { EventDispatcher } from './events';
+/**
+ * Handles mouse drag-to-pan interaction.
+ * Matches the MouseWheel pattern — extends EventDispatcher and emits events.
+ *
+ * Events:
+ *   'pan' — { dx: number, dy: number } — pixel delta to translate
+ *   'panstart' — drag started
+ *   'panend' — drag ended
+ */
+export declare class DragPanHandler extends EventDispatcher {
+    private _element;
+    private _isDragging;
+    private _lastMousePos;
+    private _enabled;
+    private _onMouseDownBound;
+    private _onMouseMoveBound;
+    private _onMouseUpBound;
+    constructor(element: HTMLElement);
+    /** Temporarily disable pan (e.g. during vertex editing) */
+    setEnabled(enabled: boolean): void;
+    isEnabled(): boolean;
+    isDragging(): boolean;
+    destroy(): void;
+    private _onMouseDown;
+    private _onMouseMove;
+    private _onMouseUp;
+}

package/dist/core/events.d.ts ADDED Viewed

@@ -0,0 +1,16 @@
+/** Event listener function type with typed event data */
+export type EventListener<T = Record<string, unknown>> = (event: {
+    type: string;
+} & T) => void;
+export declare class EventDispatcher {
+    private _listeners;
+    on<T = Record<string, unknown>>(type: string, listener: EventListener<T>): this;
+    /**
+     * Subscribe to `type` for exactly one delivery. The wrapper unsubscribes
+     * itself before invoking the user listener, so re-subscribing or firing
+     * synchronously inside the handler is safe.
+     */
+    once<T = Record<string, unknown>>(type: string, listener: EventListener<T>): this;
+    off<T = Record<string, unknown>>(type: string, listener: EventListener<T>): this;
+    fire<T = Record<string, unknown>>(type: string, data?: T): this;
+}