@zwishing/emap 0.1.0

package/dist/edit/commands/split-shared-arcs.d.ts

@@ -0,0 +1,71 @@
+import type { EditCommand } from '../edit-command';
+import { type MapshaperLayer, type PathShape } from '../../types/mapshaper-types';
+import type { TopologySource } from '../../source/source';
+/**
+ * One feature whose shape was rewritten to point at duplicated arc ids.
+ * Captured at command-construction time so undo restores it exactly.
+ */
+export interface SplitSharedArcsRemap {
+    layer: MapshaperLayer;
+    featureId: number;
+    /** Snapshot of `layer.shapes[featureId]` BEFORE the split (deep cloned). */
+    originalShape: PathShape;
+    /** The post-split shape that uses the new arc ids. */
+    newShape: PathShape;
+}
+/**
+ * Vertex data for a single arc to be appended onto the source's `ArcCollection`.
+ * Slices of the original arc's xx/yy (and zz when simplification is in play).
+ */
+export interface AppendedArc {
+    xx: Float64Array;
+    yy: Float64Array;
+    zz?: Float64Array | null;
+}
+export interface SplitSharedArcsCommandOptions {
+    source: TopologySource;
+    /** Pre-computed shape rewrites — one entry per affected feature. */
+    remaps: SplitSharedArcsRemap[];
+    /**
+     * Vertex data for every arc to append, in the order the new arc ids were
+     * assigned (first appended arc id = `originalArcCount`, second = +1, …).
+     */
+    appendedArcs: AppendedArc[];
+    /** Arc count BEFORE the split. Used by undo to truncate. */
+    originalArcCount: number;
+}
+/**
+ * Duplicate "shared" arcs (arcs referenced by both selected and unselected
+ * features) so a subsequent translate / rotate / scale on the selection no
+ * longer drags unselected neighbours along by their shared boundary.
+ *
+ * Topology stays valid: unselected features keep their original arc ids,
+ * selected features get rewritten to point at the duplicates.
+ *
+ * Undo restores every rewritten shape to its captured pre-split state and
+ * truncates the appended arcs off the `ArcCollection`. Redo re-appends and
+ * re-rewrites. Both directions go through `arcs.updateVertexData` so the
+ * collection's bounds and indices stay coherent.
+ */
+export declare class SplitSharedArcsCommand implements EditCommand {
+    private readonly opts;
+    readonly label: string;
+    constructor(opts: SplitSharedArcsCommandOptions);
+    do(): void;
+    undo(): void;
+}
+/**
+ * Walks the dataset's path-feature shapes once, finds arcs referenced by
+ * BOTH selected and unselected features, and returns the data needed to
+ * construct a {@link SplitSharedArcsCommand}. Returns `null` (no command
+ * needed) when the selection has no boundary shared with anything outside.
+ *
+ * `selected` lists `(layer, featureId)` pairs in the active selection; the
+ * caller is responsible for restricting these to one source. `allLayers`
+ * is the full layer list of that source so we can find unselected
+ * references.
+ */
+export declare function planSharedArcSplit(source: TopologySource, selected: Array<{
+    layer: MapshaperLayer;
+    featureId: number;
+}>, allLayers: MapshaperLayer[]): SplitSharedArcsCommandOptions | null;

package/dist/edit/commands/vertex-delete.d.ts

@@ -0,0 +1,26 @@
+import type { EditCommand } from '../edit-command';
+import { type ArcCollection } from '../../types/mapshaper-types';
+import type { TopologySource } from '../../source/source';
+import { type MapshaperAdapter } from '../../adapter/mapshaper-adapter';
+export interface VertexDeleteCommandOptions {
+    /** Global vertex index of the deleted vertex (recorded before deletion). */
+    vertexIndex: number;
+    /** Coordinate of the deleted vertex (recorded before deletion). */
+    coords: [number, number];
+    arcs: ArcCollection;
+    source: TopologySource;
+    /** Adapter override for tests; defaults to the process-wide singleton. */
+    adapter?: MapshaperAdapter;
+}
+/**
+ * Reverse a vertex deletion by re-inserting at the same global index. Pair
+ * with `VertexInsertCommand`'s symmetry: this command's `do()` performs the
+ * deletion (called only on redo), `undo()` restores the vertex.
+ */
+export declare class VertexDeleteCommand implements EditCommand {
+    private readonly opts;
+    readonly label = "Delete vertex";
+    constructor(opts: VertexDeleteCommandOptions);
+    do(): void;
+    undo(): void;
+}

package/dist/edit/commands/vertex-insert.d.ts

@@ -0,0 +1,26 @@
+import type { EditCommand } from '../edit-command';
+import { type ArcCollection } from '../../types/mapshaper-types';
+import type { TopologySource } from '../../source/source';
+import { type MapshaperAdapter } from '../../adapter/mapshaper-adapter';
+export interface VertexInsertCommandOptions {
+    /** Global vertex index where the new vertex was inserted. */
+    insertionId: number;
+    /** Coordinate of the inserted vertex. */
+    point: [number, number];
+    arcs: ArcCollection;
+    source: TopologySource;
+    /** Adapter override for tests; defaults to the process-wide singleton. */
+    adapter?: MapshaperAdapter;
+}
+/**
+ * Reverse a vertex insertion by deleting at the same global index.
+ * mapshaper's deleteVertex shifts subsequent indices back into place via
+ * updateVertexData, which also rebuilds arc bounds.
+ */
+export declare class VertexInsertCommand implements EditCommand {
+    private readonly opts;
+    readonly label = "Insert vertex";
+    constructor(opts: VertexInsertCommandOptions);
+    do(): void;
+    undo(): void;
+}

package/dist/edit/commands/vertex-move.d.ts

@@ -0,0 +1,45 @@
+import type { EditCommand } from '../edit-command';
+import { type ArcCollection } from '../../types/mapshaper-types';
+import type { TopologySource } from '../../source/source';
+import { type MapshaperAdapter } from '../../adapter/mapshaper-adapter';
+export interface VertexMoveCommandOptions {
+    /**
+     * IDs of every vertex at the moved topological node. mapshaper's
+     * snapVerticesToPoint moves them all in lock-step, preserving topology.
+     */
+    vertexIds: number[];
+    /** Original coordinate of the topological node before the drag. */
+    from: [number, number];
+    /** Final coordinate after the drag. */
+    to: [number, number];
+    arcs: ArcCollection;
+    source: TopologySource;
+    /** Adapter override for tests; defaults to the process-wide singleton. */
+    adapter?: MapshaperAdapter;
+}
+/**
+ * Reverse a vertex drag (including topologically shared vertices) by
+ * re-running mapshaper's snapVertices with the captured `from` /
+ * `to` coordinates. The function updates each affected arc's bounds
+ * internally, so no extra bookkeeping is required.
+ *
+ * Mergeable: consecutive moves of the SAME topological node within
+ * {@link MERGE_WINDOW_MS} collapse into one undo entry. The merged
+ * command keeps the original `from` (the very first pre-drag snapshot)
+ * and adopts the latest `to`, so a single undo reverses an entire
+ * arrow-key nudge sequence.
+ */
+export declare class VertexMoveCommand implements EditCommand {
+    private readonly opts;
+    readonly label = "Move vertex";
+    /**
+     * Wall-clock at construction time; refreshed by `merge()`. Used by
+     * `mergeable()` to bound coalescence to a short interactive window.
+     */
+    private _mergeAt;
+    constructor(opts: VertexMoveCommandOptions);
+    do(): void;
+    undo(): void;
+    mergeable(prev: EditCommand): boolean;
+    merge(next: EditCommand): void;
+}

package/dist/edit/edit-command.d.ts

@@ -0,0 +1,72 @@
+/**
+ * An undoable edit memento. NOT to be confused with a mapshaper
+ * "operation" (`emap.ops.*`) — those wrap a CLI / parsed-command run
+ * against a dataset and internally push a `DatasetReplaceCommand` to
+ * history. `EditCommand` is the lower-level abstraction that lives on
+ * the undo / redo stack.
+ *
+ * Lifecycle (memento pattern):
+ * - The caller mutates the data, then constructs the command and calls
+ *   `Emap.pushCommand(cmd)`. The command stores any state needed to
+ *   reverse the change. `pushCommand` does NOT call `do()`.
+ * - On undo, `EditHistory` invokes `cmd.undo()` to restore the prior state.
+ * - On redo, `EditHistory` invokes `cmd.do()` to re-apply the change.
+ *
+ * Implementations must capture enough state in their constructor that
+ * both `do()` and `undo()` can run multiple times without diverging.
+ */
+export interface EditCommand {
+    /** Re-apply the operation. Called by `EditHistory.redo()`. */
+    do(): void;
+    /** Reverse the operation. Called by `EditHistory.undo()`. */
+    undo(): void;
+    /** Optional human-readable label, surfaced in `historychange` events. */
+    readonly label?: string;
+    /**
+     * Optional merge predicate, evaluated by `EditHistory.push` against the
+     * current top of the undo stack. When `true`, the new command is NOT
+     * pushed; instead `prev.merge(this)` is invoked and `prev` absorbs the
+     * follow-up's effect. Used to collapse rapid repeated edits — successive
+     * arrow-key vertex nudges, mouse-drag tween steps, etc. — into one
+     * undoable entry.
+     *
+     * Implementations should be cheap (O(N) at worst over command-internal
+     * fields) and stable (no I/O, no side effects).
+     */
+    mergeable?(prev: EditCommand): boolean;
+    /**
+     * Companion to {@link mergeable}: invoked by `EditHistory.push` only
+     * when `next.mergeable(this)` returned `true`. Mutates this command in
+     * place to absorb `next`'s effect; `next` is discarded after the call
+     * returns. Implementations typically refresh a "newest-coordinate"
+     * field while preserving the oldest "starting" capture so undo still
+     * reverses the cumulative work.
+     */
+    merge?(next: EditCommand): void;
+    /**
+     * Static marker: when `true`, pushing this command tells `EditHistory`
+     * to flag every command currently in the undo stack as `stale`. Used by
+     * `DatasetReplaceCommand` (clip / dissolve / buffer / …) — those swap
+     * out the live dataset object, so commands captured against the OLD
+     * dataset can no longer mutate the right reference.
+     *
+     * The command itself is NOT stale at push time; only the entries below
+     * it become stale.
+     */
+    readonly invalidatesPriorCommands?: boolean;
+    /**
+     * Set by `EditHistory.push` when an `invalidatesPriorCommands` command
+     * is pushed above this entry. Stays `true` for the rest of this entry's
+     * lifetime — even after the invalidating command is undone, the captured
+     * dataset reference is still orphaned (the in-place undo of a
+     * dataset-swap restores a deep copy that has a different identity from
+     * the object this command was constructed against).
+     *
+     * `EditHistory.undo` skips stale commands: pops them onto the redo
+     * stack without invoking `undo()` and surfaces the skip via the
+     * `HistoryStateSnapshot.skippedStale` flag on the next change event.
+     * UIs should treat the boundary as a "history barrier" — visible in
+     * the list, but un-replayable.
+     */
+    stale?: boolean;
+}

package/dist/edit/edit-history.d.ts

@@ -0,0 +1,130 @@
+import type { EditCommand } from './edit-command';
+export interface EditHistoryOptions {
+    /**
+     * Maximum number of commands retained in the undo stack. Older commands
+     * are evicted when this is exceeded. Defaults to 200.
+     */
+    maxSize?: number;
+}
+export interface HistoryStateSnapshot {
+    canUndo: boolean;
+    canRedo: boolean;
+    /** Label of the most recent command at the top of the undo stack, if any. */
+    label?: string;
+    /**
+     * Number of commands currently in the undo stack flagged as
+     * `stale`. Non-zero after any `DatasetReplaceCommand` lands; the UI
+     * can render a divider in the history list at the boundary.
+     */
+    staleCount: number;
+    /**
+     * `true` iff the command that {@link undo} would next visit is stale
+     * (i.e. cannot be reversed in place). Provides a single boolean for UI
+     * tooltips like "the next undo crosses a topology rebuild — earlier
+     * edits cannot be replayed".
+     */
+    topIsStale: boolean;
+    /**
+     * `true` only on the {@link HistoryStateSnapshot} produced immediately
+     * after `undo()` skipped a stale command. Resets on the next event.
+     * Used by UI to surface a one-shot toast.
+     */
+    skippedStale?: boolean;
+}
+/**
+ * Linear undo / redo history.
+ *
+ * - `push(cmd)` records `cmd` and clears any pending redo entries. It does NOT
+ *   invoke `cmd.do()` — the caller is expected to have already performed the
+ *   work; the command captures what was changed so it can be reversed.
+ * - `undo()` invokes `cmd.undo()` and moves `cmd` from the undo stack to the
+ *   redo stack.
+ * - `redo()` invokes `cmd.do()` and moves `cmd` back onto the undo stack.
+ */
+export declare class EditHistory {
+    private _undoStack;
+    private _redoStack;
+    private _maxSize;
+    /**
+     * `true` for exactly one snapshot following an `undo()` / `redo()` call
+     * that traversed a stale command. Surfaced via `snapshot().skippedStale`
+     * so the host can fire one-shot UI feedback. Reset on the next
+     * non-stale traversal or on `clear()`.
+     */
+    private _lastSkippedStale;
+    /**
+     * Active capture buffer for the {@link beginCapture} protocol used by
+     * `Transaction`. While non-null, every `push(cmd)` diverts into this
+     * buffer instead of mutating the undo stack. `endCapture()` returns
+     * the collected commands and unsets this. Nested captures are not
+     * supported — a second `beginCapture()` while one is active throws.
+     */
+    private _captureBuffer;
+    constructor(options?: EditHistoryOptions);
+    /**
+     * Push a new command, evicting the oldest entry if at capacity.
+     *
+     * Merge fast-path: if the top of the undo stack defines a `merge`
+     * companion AND the incoming command's `mergeable(top)` returns true,
+     * the top absorbs the incoming command and nothing is pushed. The
+     * redo stack is still cleared (the new edit invalidates forward
+     * replay). Used by `VertexMoveCommand` / `FeatureTranslateCommand`
+     * to coalesce rapid drag / nudge sequences into one undo step.
+     *
+     * If `cmd.invalidatesPriorCommands` is `true` (DatasetReplaceCommand),
+     * every entry currently in the undo stack is flagged `stale = true`
+     * before this command is pushed. The command itself is NOT marked
+     * stale — it remains undoable as the boundary itself.
+     */
+    push(cmd: EditCommand): void;
+    /**
+     * Begin a transaction-style capture session. While active, `push(cmd)`
+     * routes every command into an internal buffer instead of mutating the
+     * undo stack, so a multi-step transaction can batch its child commands
+     * and present them as a single undo entry on commit.
+     *
+     * Throws if a capture is already in progress — nested transactions are
+     * not supported. Pair with {@link endCapture}; for safety, transaction
+     * code should call `endCapture()` from a `finally`-style path so an
+     * error in the middle doesn't leave the history stuck in capture mode.
+     */
+    beginCapture(): void;
+    /**
+     * End the active capture session and return the collected commands in
+     * push order. No-op (returns `[]`) if no capture is active. After this
+     * call, subsequent `push()` calls resume normal undo-stack behaviour.
+     */
+    endCapture(): EditCommand[];
+    /** True iff a {@link beginCapture} session is currently active. */
+    isCapturing(): boolean;
+    /**
+     * Pop the top command, invoke its `undo()`, and move it to the redo stack.
+     * Returns the executed command, or `null` if there was nothing to undo.
+     *
+     * **Stale handling**: when the top command's `stale` flag is `true`, the
+     * command is moved to the redo stack WITHOUT invoking `undo()` (its
+     * captured references point at an object the live dataset no longer
+     * uses; running it would write to the wrong place). The skip is
+     * reflected in the next {@link snapshot} via `skippedStale: true`.
+     * `undo()` still returns the moved command so callers can detect that
+     * a step was traversed.
+     */
+    undo(): EditCommand | null;
+    /**
+     * Pop the top redo entry, invoke its `do()`, and move it back to the undo
+     * stack. Returns the executed command, or `null` if there was nothing.
+     *
+     * Stale commands on the redo stack get the same skip semantics as
+     * `undo()` — the redo is a no-op transition because the captured refs
+     * are still orphaned even though the entry is moving forward in time.
+     */
+    redo(): EditCommand | null;
+    /** Empty both stacks. */
+    clear(): void;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    /** Number of commands currently in the undo stack. */
+    size(): number;
+    /** Snapshot of the public history state, suitable for event payloads. */
+    snapshot(): HistoryStateSnapshot;
+}

package/dist/edit/transaction.d.ts

@@ -0,0 +1,59 @@
+import { type OpResult } from '../map/op-result';
+import type { EmapHostInternal } from '../map/emap-host';
+import type { MapshaperDataset } from '../types/mapshaper-types';
+/**
+ * Internal-only view of a Transaction used by the runner. Public callers
+ * receive the wider {@link Transaction} class.
+ */
+export interface TransactionInternal {
+    /** Record the first-touch dataset snapshot for `sourceId`, if not already captured. */
+    _captureFirstTouch(sourceId: string, before: MapshaperDataset): void;
+}
+/**
+ * Atomic multi-step edit unit. Stages every command pushed during its
+ * lifetime; `commit()` collapses them into one history entry and
+ * `rollback()` restores the dataset + selection to the state at
+ * construction.
+ *
+ * Construct via `Emap.beginTransaction()` — direct construction is
+ * supported for tests but bypasses the Emap host wiring.
+ */
+export declare class Transaction implements TransactionInternal {
+    private readonly _host;
+    private readonly _datasetSnapshots;
+    private readonly _selectionSnapshot;
+    private _closed;
+    constructor(host: EmapHostInternal);
+    /**
+     * Internal — invoked by the runner the first time each source's
+     * dataset is about to be swapped within this transaction. The dataset
+     * passed here is the pre-op snapshot the runner already produced for
+     * its own undo bookkeeping; we keep a reference so rollback can
+     * restore the source to its true pre-transaction state regardless of
+     * how many ops touched it later.
+     */
+    _captureFirstTouch(sourceId: string, before: MapshaperDataset): void;
+    /** True iff `commit()` / `rollback()` has not been called yet. */
+    get isOpen(): boolean;
+    /**
+     * Drain the capture buffer, push a single `CompositeCommand` wrapping
+     * every staged child to the undo stack (no-op if nothing was staged),
+     * and close the transaction. Returns `OK` on success or
+     * `Err.hostRemoved()` if the host was torn down mid-transaction.
+     *
+     * The composite's children are NOT re-executed — their effects were
+     * applied as each child was originally captured.
+     */
+    commit(label: string): Promise<OpResult>;
+    /**
+     * Discard every staged command, restore each touched source's dataset
+     * to its pre-transaction snapshot, restore the selection, and close
+     * the transaction. Fires `selectionchange`, `historychange`, and
+     * schedules a render.
+     *
+     * Idempotent only in the sense that calling it twice throws — once
+     * the transaction is closed it cannot be re-used.
+     */
+    rollback(): void;
+    private _end;
+}