@zwishing/emap 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -7,6 +7,216 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-05-21
+
+### Added
+
+- DX Phase 1 (toward 0.3.0): `Handler` interface + `HandlerManager`; the pan
+  and wheel interactions are now named handlers `map.dragPan` /
+  `map.scrollZoom` with `enable()/disable()/isEnabled()/setOptions()`.
+  Enables selective interaction toggling (e.g. disable wheel, keep pan)
+  without reaching into private internals. No behavior change for the
+  default path (`interactive` unset/true): the underlying pan/wheel
+  primitives are unchanged and all existing tests pass byte-identically.
+  One intentional fix: `MapOptions.interactive: false` was previously a
+  declared-but-unwired no-op — it is now functional and disables pan+zoom
+  as the option always implied. See
+  `docs/superpowers/specs/2026-05-17-emap-maplibre-dx-design.md`.
+- DX Phase 2a (toward 0.3.0): `HandlerManager` is now the single
+  pointer-event arbiter (`attach`/`detach`, normalized `NormalizedPointerEvent`,
+  priority-ordered dispatch with exclusive-gesture locking). `dragPan` pans
+  via `handlePointer` and owns no DOM listeners; the old internal pan
+  primitive (`src/core/drag-pan-handler.ts`) is removed. No pan behavior
+  change; this is the seam P2b's selection handlers slot into.
+- DX Phase 2b (toward 0.3.0): three opt-in named selection handlers —
+  `map.clickSelect`, `map.boxSelect`, `map.lassoSelect` (each a `Handler`
+  with `enable/disable/isEnabled/setOptions/getOptions`). Driven by the
+  Phase-2a pointer arbiter; `box`/`lasso` sit above `dragPan` so
+  `shift`+drag selects (when enabled) instead of panning, with no
+  `addControl` needed. Shared pure `resolveMode` (configurable
+  modifier→`SelectMode` table) and a shared `select-geometry` module
+  replace the duplicated private `_modeFromEvent`. `boxSelect` and
+  `lassoSelect` are mutually exclusive (`enable()` throws if the other is
+  on). Disabled by default → `new Emap()` behavior is unchanged; the
+  legacy `BoxSelectControl`/`LassoSelectControl` keep working unchanged
+  (thin-shell rewrite is Phase 2c).
+- DX Phase 2c (toward 0.3.0): `BoxSelectControl` / `LassoSelectControl`
+  are now button-only thin shells over the P2b `map.boxSelect` /
+  `map.lassoSelect` handlers (the ~490 lines of duplicated
+  listener/overlay/hit-test/select logic deleted) — public class,
+  constructor options, 0×0 anchor DOM, selection behaviour, and the
+  dashed-lasso visual are byte-identical (the handler now honours
+  `strokeDasharray`, default `'4 3'`). Adding both controls now surfaces
+  the handlers' mutual-exclusivity error instead of silently conflicting.
+  Duplicated types consolidated to one declaration each with re-export
+  shims (every public import path unchanged): `SelectMode` →
+  `core/handlers/select-mode`, `BoxSelectStyle` →
+  `core/handlers/box-select`, `LassoSelectStyle`/`LassoStyle` →
+  `core/handlers/lasso-select` (`LassoStyle` widened additively to include
+  the optional `strokeDasharray`). No arbiter/dispatch change.
+- DX Phase 3 (toward 0.3.0): delegated feature events —
+  `map.on('feature:click'|'feature:hover'|'feature:enter'|'feature:leave',
+  { source?, layers? }?, cb)`. Fed by the Phase-2a pointer arbiter, hit-test
+  reuses the existing `FeatureQuery` (no new path), decoupled from
+  selection. Zero cost when no `feature:*` listener is registered (the
+  pointer sink is installed lazily). Canonical highlight recipe:
+  `map.on('feature:enter', {}, e => map.setHighlightedFeatures([e.ref]));
+  map.on('feature:leave', {}, () => map.clearHighlightedFeatures());` —
+  replaces the manual mousemove-poll + highlight-sync boilerplate.
+- DX Phase 4 (toward 0.3.0): opened the emap design-token namespace —
+  `controls.css` now declares 9 `--emap-*` custom properties on `:root`
+  (`accent`, `accent-soft`, `surface-bg`, `surface-border`,
+  `surface-shadow`, `radius`, `hover-bg`, `danger`, `font`) with the
+  current literal values as defaults. The vertex-edit right-click menu
+  ("删除节点") migrated off inline styles + JS `mouseenter`/`mouseleave`
+  hover toggle onto class-based rules (`.emap-ctx-menu` /
+  `.emap-ctx-menu-item` with `:hover`) consuming the tokens. Default
+  rendering is byte-identical; themers override `--emap-*` on `:root` (or
+  a parent) to restyle. Existing controls' literal values are unchanged
+  — namespace opened but not retro-applied (follow-up phases may opt in).
+- DX Phase 5 (toward 0.3.0): vertex editing is now the arbiter-driven
+  `map.vertexEdit` handler (`enable/disable/isEnabled/setOptions/
+  getOptions`), consistent with the other handlers — usable without
+  `addControl`. The arbiter gained a `contextmenu` event kind (right-click
+  vertex delete). `VertexEditControl` is now a button-only thin shell over
+  `map.vertexEdit`; its public class, constructor options, button DOM,
+  `editmodechange`/edit-mode behavior, undo commands, and the
+  `vertex_moved` event are byte-identical. Disabled by default →
+  `new Emap()` behavior unchanged. (P4 will migrate the context-menu
+  inline styles to CSS tokens.)
+- DX Phase 6 (toward 0.3.0): feature drawing is now the arbiter-driven
+  `map.drawFeature` handler (`enable/disable/isEnabled/setOptions/
+  getOptions`) — usable without `addControl`. The arbiter gained a
+  `dblclick` event kind (finish polyline/polygon); `Escape`-to-cancel is a
+  handler-owned key listener. `enable()` throws if `source`/`type` are
+  unset. `DrawFeatureControl` is now a button-only thin shell over
+  `map.drawFeature`; its public class, constructor options (incl. `icon`),
+  button DOM, `feature_created` event, `FeatureCreateCommand`, and the
+  cross-mode auto-deactivate are byte-identical. Disabled (and
+  unconfigured) by default → `new Emap()` behavior unchanged.
+- DX Phase 7 (toward 0.3.0): feature transform is now the arbiter-driven
+  modal `map.transformFeature` handler (`setOptions({ mode:
+  'translate'|'rotate'|'scale' })`, `enable/disable/isEnabled/getOptions`).
+  Selection is delegated to `clickSelect` (click = replace, shift+click =
+  add, click on empty space = clear); `transformFeature` owns no
+  selection logic — it press-drags an already-selected feature:
+  pointerdown over a selected feature opens the matching `editSession`,
+  drag streams the delta, pointerup commits one undo entry, `Escape`
+  cancels. `EditMode` gained `'transform'` (enters the modal pan-disable +
+  `editmodechange` like vertex/draw; cross-deactivates with
+  vertexEdit/drawFeature). The headless `map.editSession` API is unchanged
+  — this only absorbs the pointer→session boilerplate. Disabled by default
+  → `new Emap()` behavior unchanged. The `feature-translate` /
+  `feature-rotate-scale` examples are rewritten to the one-line recipe.
+- DX Phase 8 (toward 0.3.0): delegated `map.on('mousemove', cb)` event
+  (payload `{ point, mapCoord, originalEvent }`), fed by the Phase-2a
+  pointer arbiter via the same sink mechanism as the Phase-3 `feature:*`
+  events — exported `PointerMoveEvent` type. `StatusControl` no longer
+  hand-wires a raw canvas `mousemove`; it subscribes the delegated event
+  (public class/options/DOM/coordinate-string unchanged). Zero cost when
+  no `mousemove`/`feature:*` listener is registered (the pointer sink is
+  installed lazily and shared). One intentional, documented behavior
+  change: the coordinate readout pauses during an exclusive pan/drag
+  gesture (consistent with `feature:hover`) and resumes on release.
+  Disabled-by-default cost model unchanged → `new Emap()` behavior
+  identical.
+- DX Phase 9 (toward 0.3.0): MapLibre-parity camera API — `map.jumpTo`,
+  `setCenter`, `setZoom`, `easeTo`, `panTo`, `panBy`, `zoomTo`, `flyTo`
+  (van-Wijk parabolic), `fitBounds`, `stop` (all chainable, return
+  `this`), built on the existing `Tween`/`Viewport`. Fires a
+  `movestart`/`move`/`moveend` + `zoomstart`/`zoom`/`zoomend` lifecycle.
+  Camera state is `{ center (projected/data coords, = the Phase-8
+  `mapCoord` space), scale }`; `zoom` is an optional Web-Mercator
+  convenience (`Projection.getScale` inverse) — non-Web-Mercator CRSs
+  pass `{ scale }`. 2D only (no bearing/pitch). A new camera call (or a
+  user pan/wheel) interrupts a running animation; the interrupted move
+  still fires its `moveend`. `getCenter`/`getZoom`/`setExtent`/`reset`/
+  `zoomIn`/`zoomOut` are byte-identical; default `new Emap()` behaviour
+  unchanged (no animation runs until a camera method is called).
+- DX Phase 10 (toward 0.3.0): typed `EmapEventMap` — `map.on` / `off` /
+  `once` now give
+  event-name autocomplete and payload inference for the camera lifecycle
+  (`movestart`/`move`/`moveend`/`zoomstart`/`zoom`/`zoomend`) and the
+  `data`/`error`/`selectionchange`/`historychange`/`editmodechange`/
+  `crschange`/`resize`/`validationfailed` events. `EmapEventMap` is an
+  augmentable `interface` (`declare module` to register custom events);
+  unknown event names still compile (escape hatch preserved). Compile-time
+  only — zero runtime change. Exported: `EmapEventMap`, `CameraEvent`.
+- DX Phase 11 (toward 0.3.0): per-handler cursor — each `Handler` may
+  implement `getCursor(): string | null`; `HandlerManager` arbitrates one
+  effective cursor (active gesture > priority order > default) and writes
+  it to the map element via `refreshCursor()` / on every dispatch. Adds
+  the previously-absent `grab`/`grabbing` pan cursors and the draw
+  crosshair (the old `.emap-draw-active` CSS rule was dead); the ad-hoc
+  `.emap-edit-active`/`.emap-draw-active` CSS-class mechanism is removed
+  (single source of truth). No dispatch/priority behaviour change.
+
+### Changed
+
+- **`LassoStyle` widened (additive, back-compat):** the public
+  `LassoStyle` type (`@zwishing/emap` index, from
+  `core/handlers/lasso-select`) gained an optional `strokeDasharray?:
+  string` field (default `'4 3'`). Every existing 3-field value remains
+  assignable; consumers passing an extra `strokeDasharray` to a lasso
+  handler/control now see the dashed visual previously only possible via
+  the `LassoSelectControl` surface.
+- **Adding `BoxSelectControl` + `LassoSelectControl` together now
+  throws:** the P2b handlers are mutually exclusive (one of `enable()`
+  throws `cannot enable boxSelect: lassoSelect is enabled`). The legacy
+  controls silently coexisted with undefined behavior; the P2c thin
+  shells surface the conflict honestly. Install one, OR call
+  `map.boxSelect.disable()` before enabling the other (see the updated
+  `test/examples/lasso-select.html` for the canonical toggle recipe).
+- Release metadata now targets `0.3.0`, matching the handler-centric public API
+  documented in README/FEATURES.
+
+### Fixed
+
+- Made the bundle self-contained smoke test portable on Windows by resolving
+  local CLI shims through `cmd /c`, adding explicit `esbuild` dev dependency
+  coverage, and relaxing the GeoJSON bundle-load timeout for slower full-suite
+  runs.
+- Completed the typed event surface: `EmapEventMap` now includes the delegated
+  `mousemove` and `feature:*` events, so facade authors can index the event map
+  for those 0.3.0 APIs instead of relying only on `map.on(...)` overloads.
+
+### Documentation
+
+- Added third-party release guidance: static asset deployment, full custom
+  box-selection wiring without bundled controls, known limitations, API
+  stability boundaries, and a release checklist. The build now cleans `dist`
+  before production output so stale declaration files are not packed.
+- Refreshed the project documentation for the current handler-centric public
+  API: rewrote `README.md` around third-party integration, headless handler
+  usage, custom UI patterns, feature events, editing, worker setup, theming,
+  and built-in controls; moved `docs/FEATURES.md` to the package root as
+  `FEATURES.md` and updated it as the canonical capability matrix. Removed
+  the mandatory OpenSpec workflow instructions from `AGENTS.md` and
+  `CLAUDE.md`, keeping them focused on current project architecture and
+  contribution rules.
+- Documented the explicit 0.2.0 loading contract: `setData()` resolves only
+  after the dataset is populated and `data{reason:'load'}` has fired, and
+  `map.addSource()` is order-independent (back-fills an already-loaded
+  source). Added a troubleshooting note — a blank map with no error after
+  "upgrading to 0.2.0" is the *pre-0.2.0* fire-and-forget symptom and
+  indicates a stale install, not an emap defect (a reopened Friction #9
+  report was root-caused to this; the published 0.2.0 runtime was verified
+  to settle the promise after the data event).
+- Modernized all 41 `test/examples/*.html` to the canonical awaitable
+  recipe (`await source.setData(...)` → `map.addSource(...)` →
+  `map.setExtent(...)` in a `try/catch`), replacing the older event-driven
+  `source.on('data'/'error')` load pattern. Examples now match the README
+  "Loading contract" verbatim, removing the example/doc divergence that
+  contributed to the reopened #9 misdiagnosis. Per-file status text,
+  post-load logic, and multi-file/Promise-wrapper variants preserved.
+
+### Tested
+
+- Added `src/map/setdata-addsource-ordering.test.ts`: end-to-end regression
+  proving both `addSource`→`await setData` and `await setData`→`addSource`
+  populate the dataset before the promise resolves and schedule a render
+  (guards the loading contract against regression).
+
 ## [0.2.0] - 2026-05-17
 
 ### Changed
@@ -112,7 +322,8 @@ Initial public release.
 - Distributed control stylesheet as `dist/emap.css` (importable via
   `@zwishing/emap/style.css`).
 
-[Unreleased]: https://github.com/zwishing/emap/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/zwishing/emap/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/zwishing/emap/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/zwishing/emap/compare/v0.1.3...v0.2.0
 [0.1.3]: https://github.com/zwishing/emap/compare/v0.1.2...v0.1.3
 [0.1.2]: https://github.com/zwishing/emap/compare/v0.1.1...v0.1.2

package/FEATURES.md

@@ -0,0 +1,455 @@
+# emap Feature Overview
+
+This document lists the current public capabilities of `emap`. It complements
+the quick-start focused [README.md](README.md).
+
+## 1. Runtime and Packaging
+
+- Browser-only TypeScript library.
+- Framework-agnostic: usable from vanilla HTML, React, Vue, Svelte, Angular, or
+  any other browser app.
+- IIFE and ESM builds.
+- Self-contained browser bundler path with Mapshaper supplied as package
+  sibling bundles.
+- Optional worker bundle for off-thread dataset operations.
+- Public CSS entry: `@zwishing/emap/style.css`.
+
+## 2. Public API Stability
+
+Recommended stable integration surface:
+
+- `Emap`
+- `TopologySource`
+- map source/layer/camera APIs
+- named handlers exposed on `map.*`
+- feature events and typed map events
+- `map.ops.*`
+- `map.features`, `map.validators`, `map.editSession`
+- built-in controls
+- documented types exported from the package root
+
+Advanced but less stable surfaces:
+
+- `HandlerManager`
+- concrete handler classes
+- `CanvasPainter` and `EditOverlayRenderer`
+- `MapshaperAdapter` replacement hooks
+- edit command classes
+- raw Mapshaper topology types
+
+These advanced exports are useful for custom integrations and tests, but they
+may change faster than the main `Emap` and `TopologySource` API while the
+project is still pre-production.
+
+## 3. Data Sources
+
+Supported inputs:
+
+| Input | Entry |
+|---|---|
+| GeoJSON | `TopologySource.fromUrl()`, `fromBytes()`, `setData()` |
+| TopoJSON | `TopologySource.fromUrl()`, `fromBytes()`, `setData()` |
+| ZIP Shapefile | `TopologySource.fromUrl()`, `fromBytes()`, `setData()` |
+| Mapshaper snapshot | `map.loadSnapshot()` |
+
+Source capabilities:
+
+- Awaitable loading contract: `setData()` resolves after data is ready.
+- Order-independent `map.addSource()`.
+- CRS inference from GeoJSON defaults and Shapefile `.prj`.
+- ZIP extraction limits for archive count, decompressed size, and ratio checks.
+- `getLayers()`, `getDataset()`, `getExtent()`, `getArcs()`, and export helpers.
+- `DisplayArcs` LOD wrapper for large datasets.
+
+## 4. Layers and Rendering
+
+Layer types:
+
+- `line`
+- `fill`
+- `circle`
+
+Layer APIs:
+
+- `map.addLayer(layer, before?)`
+- `map.removeLayer(id)`
+- `map.getLayer(id)`
+- `map.getLayers()`
+- `map.moveLayer(id, beforeId?)`
+- `map.setLayerVisibility(id, visibility)`
+- `map.setPaintProperty(id, name, value)`
+
+Rendering capabilities:
+
+- HTML5 Canvas 2D renderer.
+- Batched stroke drawing for topology arcs.
+- Shared-arc line rendering so polygon boundaries can be drawn once.
+- Polygon fill rendering with even-odd fill handling.
+- Point rendering.
+- Highlight overlay rendering.
+- Edit and draw overlay rendering.
+
+## 5. Camera and View
+
+Camera methods:
+
+- `jumpTo()`
+- `setCenter()`
+- `setZoom()`
+- `easeTo()`
+- `flyTo()`
+- `panTo()`
+- `panBy()`
+- `zoomTo()`
+- `fitBounds()`
+- `stop()`
+
+View and coordinate methods:
+
+- `getCenter()`
+- `getZoom()`
+- `getExtent()`
+- `setExtent()`
+- `reset()`
+- `project()`
+- `unproject()`
+- `resize()`
+
+Camera events:
+
+- `movestart`
+- `move`
+- `moveend`
+- `zoomstart`
+- `zoom`
+- `zoomend`
+
+## 6. Named Interaction Handlers
+
+`emap` exposes built-in interactions as named handlers. Third-party apps can use
+these directly without using bundled UI controls.
+
+| Handler | Purpose |
+|---|---|
+| `map.dragPan` | Pointer drag map panning |
+| `map.scrollZoom` | Wheel zoom |
+| `map.clickSelect` | Click selection |
+| `map.boxSelect` | Shift-drag rectangular selection |
+| `map.lassoSelect` | Free-form lasso selection |
+| `map.vertexEdit` | Topology-aware vertex editing |
+| `map.drawFeature` | Point, polyline, and polygon drawing |
+| `map.transformFeature` | Translate, rotate, or scale selected features |
+
+Uniform handler surface:
+
+- `enable()`
+- `disable()`
+- `isEnabled()`
+- `setOptions()`
+- `getOptions()`
+- `handlePointer()`
+- optional `getCursor()`
+
+`HandlerManager` arbitrates pointer events with priority ordering, exclusive
+gesture locking, and cursor resolution.
+
+## 7. Selection, Hit Testing, and Feature Events
+
+Selection APIs:
+
+- `map.select(features, { mode })`
+- `map.deselect(features)`
+- `map.clearSelection()`
+- `map.getSelection()`
+- `map.isSelected(feature)`
+- `map.deleteSelected()`
+
+Selection modes:
+
+- `replace`
+- `add`
+- `toggle`
+
+Feature querying:
+
+- Point query: `map.queryFeatures([x, y], options?)`
+- BBox query: `map.queryFeatures([[x1, y1], [x2, y2]], options?)`
+- Layer filtering through `{ layers: [...] }`
+- Lazy Flatbush spatial indexes.
+- `map.prebuildSpatialIndex(sourceId?)`
+- `map.clearSpatialIndex(sourceId?)`
+
+Delegated events:
+
+- `feature:click`
+- `feature:hover`
+- `feature:enter`
+- `feature:leave`
+- `mousemove`
+
+Feature accessor:
+
+- `map.features.get(ref)`
+- `map.features.iter(sourceId, layerId)`
+- `map.features.count(sourceId, layerId)`
+
+Highlighting:
+
+- `map.setHighlightedFeatures(features, style?)`
+- `map.clearHighlightedFeatures()`
+- `map.setHighlightStyle(style)`
+
+## 8. Editing Model
+
+Undoable command families:
+
+- Vertex commands: `VertexMoveCommand`, `VertexInsertCommand`,
+  `VertexDeleteCommand`.
+- Feature commands: `FeatureCreateCommand`, `FeatureDeleteCommand`,
+  `BulkFeatureDeleteCommand`, `FeatureTranslateCommand`, `FeatureAffineCommand`.
+- Topology commands: `SplitSharedArcsCommand`.
+- Dataset replace: `DatasetReplaceCommand`.
+- Attribute and schema commands: `FeaturePropertyChangeCommand`,
+  `FieldAddCommand`, `FieldRemoveCommand`, `FieldRenameCommand`.
+- Multi-command envelope: `CompositeCommand`.
+
+Session editing:
+
+- `map.editSession.translateSelected(dx, dy)`
+- `map.editSession.rotateSelected(angle, origin?)`
+- `map.editSession.scaleSelected(sx, sy?, origin?)`
+- `map.editSession.beginTranslateSession(options?)`
+- `map.editSession.beginAffineSession(matrix?, origin?)`
+
+Transactions:
+
+- `map.beginTransaction()`
+- `tx.commit(label?)`
+- `tx.rollback()`
+
+Undo/redo:
+
+- `map.undo()`
+- `map.redo()`
+- `map.canUndo()`
+- `map.canRedo()`
+- `map.clearHistory()`
+- `map.bindHistoryShortcuts()`
+
+## 9. Mapshaper Operations
+
+All operations live under `map.ops` and return `Promise<OpResult>`.
+
+Geometry and topology:
+
+- `clipLayer`
+- `eraseLayer`
+- `dissolveLayer`
+- `bufferLayer`
+- `simplifyLayer`
+- `projectLayer`
+- `affineLayer`
+- `cleanLayer`
+- `snapLayer`
+- `rebuildTopology`
+- `checkGeometry`
+
+Set and overlay operations:
+
+- `mosaicLayer`
+- `unionLayers`
+- `divideLayer`
+- `intersectionPointsLayer`
+
+Geometry conversion:
+
+- `pointsLayer`
+- `linesLayer`
+- `polygonsLayer`
+- `innerlinesLayer`
+- `explodeLayer`
+
+Layer management:
+
+- `renameLayer`
+- `mergeLayers`
+- `splitLayer`
+- `dropLayer`
+
+Filtering and attributes:
+
+- `applyExpression`
+- `filterFeatures`
+- `filterIslands`
+- `filterSlivers`
+- `filterGeom`
+- `sortFeatures`
+- `uniqueFeatures`
+- `filterFields`
+- `renameFields`
+- `joinTable`
+- `dataFill`
+
+Selection-driven:
+
+- `mergeSelected`
+
+Operation runtime features:
+
+- Parsed command objects instead of shell strings.
+- Effect-aware selection preservation.
+- Dataset-replace undo barriers.
+- Optional worker routing.
+- Structured `OpResult` and `OpError` responses.
+
+## 10. Validation
+
+Validator registry:
+
+- `map.validators.register(validator)`
+- returned unregister function
+- `validationfailed` event
+
+Built-in validator:
+
+- `topologyValidator(options)`
+
+Validation runs after committed history changes. The engine reports failures and
+leaves application policy decisions to the host app.
+
+## 11. Worker Offloading
+
+Worker options:
+
+- `useWorker: false | true | 'auto'`
+- `workerMode` compatibility alias
+- `workerThreshold`
+- `workerUrl`
+- `workerPoolSize`
+- `workerPool`
+- `workerRouting(info)`
+
+Worker features:
+
+- Lazy worker creation.
+- Multiple worker instances through `MapshaperWorkerPool`.
+- Command-family-aware routing.
+- Cancellation through `map.cancelWorkerJobs()`.
+- Transferable arc buffers where supported by the Mapshaper pack/unpack path.
+
+## 12. Snapshots and Export
+
+Map snapshot APIs:
+
+- `map.exportSnapshot(options?)`
+- `map.loadSnapshot(input, options?)`
+
+Source export formats:
+
+- GeoJSON
+- TopoJSON
+- Shapefile ZIP
+
+Snapshots use Mapshaper pack data with `emap` source metadata for multi-source
+restore.
+
+## 13. Built-In Controls
+
+| Control | Purpose |
+|---|---|
+| `NavigationControl` | Zoom in, zoom out, reset |
+| `StatusControl` | Pointer coordinates and CRS |
+| `BasemapControl` | MapLibre raster basemap toggle |
+| `HistoryControl` | Undo/redo |
+| `EditToolbar` | Combined edit toolbar |
+| `VertexEditControl` | Button shell over `map.vertexEdit` |
+| `DrawFeatureControl` | Button shell over `map.drawFeature` |
+| `BoxSelectControl` | Thin shell over `map.boxSelect` |
+| `LassoSelectControl` | Thin shell over `map.lassoSelect` |
+| `SimplifyControl` | Simplification UI |
+
+Custom controls implement:
+
+- `onAdd(map): HTMLElement`
+- `onRemove(map?)`
+
+Control positions:
+
+- `top-left`
+- `top-right`
+- `bottom-left`
+- `bottom-right`
+
+## 14. Events
+
+Typed map events include:
+
+- `data`
+- `error`
+- `selectionchange`
+- `historychange`
+- `editmodechange`
+- `validationfailed`
+- `crschange`
+- `resize`
+- camera lifecycle events
+
+`EmapEventMap` is augmentable through TypeScript module augmentation for
+application-specific events.
+
+## 15. CRS and Geometry Utilities
+
+Exports:
+
+- `Bounds`
+- `AffineTransform`
+- `Viewport`
+- `Projection`
+- `DEFAULT_CRS`
+- `inferFromPrj`
+- `normalizeCrsString`
+- `resolveDatasetCRS`
+
+Mapshaper topology types are also exported for consumers that need to build
+custom commands or inspect raw datasets.
+
+## 16. Public Advanced Surfaces
+
+Advanced exports include:
+
+- `DefaultMapshaperAdapter`
+- `getDefaultMapshaperAdapter`
+- `setDefaultMapshaperAdapter`
+- `MapshaperWorkerPool`
+- `HandlerManager`
+- built-in handler classes
+- `CanvasPainter`
+- `EditOverlayRenderer`
+- edit command classes
+- `ValidatorRegistry`
+- `Err`, `OK`, and `okValue`
+- layer paint resolvers
+- CLI safety helpers: `quoteCliArg`, `isValidLayerName`, `isValidFieldName`
+
+## 17. Security and Constraints
+
+- Browser runtime only.
+- No server dependency.
+- Mapshaper internals are isolated behind `MapshaperAdapter`.
+- Expression-bearing APIs default to `expressionPolicy: 'disabled'`.
+- Apps must opt in to `expressionPolicy: 'trusted'` before executing trusted
+  expression strings.
+- Worker assets must be served by the host app when worker offloading is used.
+
+## 18. Examples and Tests
+
+- Manual examples: `test/examples/*.html`.
+- Unit tests: `src/**/*.test.ts`.
+- Type tests: `*.test-d.ts`.
+- Build and verification:
+
+```bash
+cmd /c npm run typecheck
+cmd /c npm run test:run
+cmd /c npm run build
+```