@weasel-js/history 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 orochi235
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,23 @@
+# @weasel-js/history
+
+Undo/redo history with scoped sub-history (Journal) primitive. No React, no DOM.
+
+Part of [weasel](https://github.com/orochi235/weasel), a domain-agnostic 2D
+scene-graph canvas kit for React. See the
+[API reference](https://orochi235.github.io/weasel/api/).
+
+## Install
+
+```sh
+npm install @weasel-js/history
+```
+
+## Usage
+
+```ts
+import { /* … */ } from '@weasel-js/history';
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,234 @@
+/**
+ * An invertible mutation. Applied via an adapter; produces an inverse op
+ * that, when applied to the same adapter, undoes the original.
+ *
+ * Adapters are intentionally typed loosely here so different op types can
+ * require different adapter capabilities. Each op is responsible for
+ * narrowing the adapter via the methods it calls.
+ *
+ * Lives here rather than in `@weasel-js/core` because an invertible,
+ * replayable mutation is a history concept: this package is what pushes ops
+ * onto a stack, inverts them, coalesces them, and rebuilds them from a
+ * serialized snapshot. Nothing about the shape is core-specific — it names no
+ * scene, node, or pose type. Core re-exports it from `core/ops/types` so its
+ * own call sites read unchanged.
+ */
+interface Op {
+    /** Apply the mutation. Return `false` (or `'noop'`) to signal that
+     *  nothing changed — the history layer then skips pushing an undo
+     *  entry for the batch when *every* op reports no-op. Returning
+     *  `undefined`/`void` means "mutated" (the common case; existing ops
+     *  don't need to change). */
+    apply(adapter: unknown): void | boolean | 'noop';
+    invert(): Op;
+    label?: string;
+    coalesceKey?: string;
+    /** Stable factory name for op-registry lookup. Kit-emitted ops always
+     *  set this; consumer ops without a name can't round-trip through
+     *  `History.serialize()` and are dropped from persisted snapshots. */
+    name?: string;
+    /** Serializable args (JSON / structured-clone-safe) that, paired with
+     *  `name`, reconstruct the op via the registry's `rebuildOp`. */
+    args?: unknown;
+}
+
+interface BeginJournalOptions {
+    label: string;
+    targetId?: string;
+}
+interface Journal {
+    readonly targetId: string | undefined;
+    readonly forkedAtEntryId: number;
+    applyBatch(ops: Op[], label: string): void;
+    undo(): void;
+    redo(): void;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    entries(): {
+        undo: HistoryEntry[];
+        redo: HistoryEntry[];
+    };
+    commit(label: string): void;
+    cancel(): void;
+    suspend(): void;
+    isActive(): boolean;
+}
+
+/** Wire form of a single op inside a serialized history. The pair
+ *  `(name, args)` reconstructs a live `Op` via the op-factory registry. */
+interface SerializedOp {
+    name: string;
+    args: unknown;
+}
+/** Wire form of one history entry. `forwardOps` / `baseOps` mirror the
+ *  in-memory entry's fields (see `Entry` above) but only carry the
+ *  serializable `(name, args)` projection of each op. */
+interface SerializedHistoryEntry {
+    id: number;
+    label: string;
+    forwardOps: SerializedOp[];
+    baseOps: SerializedOp[];
+}
+/** Snapshot of an entire `History` instance. Designed to live alongside the
+ *  scene snapshot in IDB so a reload restores the undo / redo stacks to
+ *  exactly where they were. */
+interface SerializedHistory {
+    version: 1;
+    undoStack: SerializedHistoryEntry[];
+    /** Stored newest-first, mirroring the in-memory stack so a deserialized
+     *  history matches the original's `entries().redo` ordering. */
+    redoStack: SerializedHistoryEntry[];
+    nextEntryId: number;
+    /** Entries dropped because at least one of their ops lacked a `name`
+     *  and therefore couldn't round-trip through the op-factory registry.
+     *  Always present (zero when nothing was dropped) so callers can detect
+     *  loss without parsing the debug log. */
+    droppedEntries: number;
+}
+/** Snapshot of an entry handed to `onEvict` when it permanently leaves the
+ *  reachable stacks. Ops are live references — read `name`/`args`, don't
+ *  mutate. */
+interface EvictedEntry {
+    id: number;
+    label: string;
+    forwardOps: readonly Op[];
+    baseOps: readonly Op[];
+}
+/** Read-only view of a history entry exposed via `History.entries()`. */
+interface HistoryEntry {
+    /** Stable monotonic id (preserved across coalesce merges). */
+    id: number;
+    /** Human-readable label (the `label` arg passed to `applyOps`). */
+    label: string;
+    /** Push/last-coalesce timestamp (ms). */
+    timestamp: number;
+    /** Set of node ids touched by any op in this entry. Populated from ops
+     *  whose `args` carry an `id` field (transform, setPath, reparent) or a
+     *  `node.id` field (insert, delete). Ops without a recognisable id field
+     *  contribute nothing. May be `undefined` for deserialized entries
+     *  restored from an older snapshot that predates this field. */
+    touchedIds?: ReadonlySet<string>;
+}
+/** Op-batched undo/redo controller returned by `createHistory`. */
+interface History {
+    apply(op: Op, label?: string): void;
+    applyOps(ops: Op[], label: string): void;
+    undo(): void;
+    redo(): void;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    /** Number of entries on the undo stack (O(1); `entries().undo.length`
+     *  without materializing the views). */
+    undoDepth(): number;
+    /** Number of entries on the redo stack (O(1)). */
+    redoDepth(): number;
+    clear(): void;
+    /** Snapshot of the current undo + redo stacks. `undo` is oldest→newest
+     *  (i.e. the last element is what `undo()` would pop next); `redo` is
+     *  also oldest→newest from the user's perspective (i.e. the *first*
+     *  element is what `redo()` would pop next — see implementation note).
+     *  Callers should treat the arrays as immutable. */
+    entries(): {
+        undo: HistoryEntry[];
+        redo: HistoryEntry[];
+    };
+    /** Walk the history forward/back until exactly `n` entries are on the
+     *  undo stack (0 ≤ n ≤ entries().undo.length + entries().redo.length).
+     *  Equivalent to repeated `undo()`/`redo()` calls but doesn't bother
+     *  rebuilding entry snapshots between steps. No-op if already at `n`. */
+    goto(n: number): void;
+    /** Monotonic counter bumped on every push/undo/redo/clear/coalesce.
+     *  Cheap to read; callers use it as a React dep to detect changes. */
+    getVersion(): number;
+    /** Subscribe to history changes. Fires after every push/undo/redo/
+     *  clear/coalesce. Returns an unsubscribe fn. */
+    subscribe(listener: () => void): () => void;
+    /** Snapshot the undo + redo stacks in a structured-clone-safe form.
+     *  Entries whose ops aren't all kit-registered (i.e. any op missing a
+     *  `name`) are dropped from the snapshot with a debug-level log — they
+     *  can't round-trip, so we omit them rather than emit a half-restorable
+     *  entry. The in-memory stacks aren't modified. */
+    serialize(): SerializedHistory;
+    /** Replace the current undo + redo stacks with the deserialized contents
+     *  of `snapshot`. Ops are rebuilt via the `rebuildOp` option when
+     *  provided, then the global registry; unknown names become no-op
+     *  placeholders so stack ordering survives across kit-version skew.
+     *  Bumps `version` and notifies subscribers exactly once. */
+    restore(snapshot: SerializedHistory): void;
+    /** Push an entry whose ops have already been applied to the adapter.
+     *  Unlike `applyOps`, does NOT call `op.apply()`. Used by Journal.commit
+     *  to flush a session's net forward ops to the parent as one entry without
+     *  re-mutating the scene. */
+    recordEntry(ops: Op[], label: string): void;
+    /** Concatenated forwardOps of every undo-stack entry, in order. Snapshot
+     *  of "what changes are currently applied via this history" — useful for
+     *  Journal.commit to flush to a parent, and for any caller that wants to
+     *  diff against a baseline. */
+    allForwardOps(): Op[];
+    /** The id that will be assigned to the *next* pushed entry. Stable
+     *  monotonic counter; callers use it to tag a fork point (see Journal). */
+    currentEntryId(): number;
+    /** Open a scoped sub-history. All apply/undo/redo on the returned Journal
+     *  affect the same adapter; on commit, the Journal's net forward ops are
+     *  flushed to this History as one entry. See spec docs/superpowers/specs/
+     *  2026-05-24-modality-design.md for the full lifecycle. */
+    beginJournal(opts: BeginJournalOptions): Journal;
+    /** Re-activate a suspended journal. Throws if the journal was committed or
+     *  cancelled (those are terminal). Staleness checking is the caller's
+     *  responsibility — consult `journal.forkedAtEntryId` against
+     *  `currentEntryId()` and your own op-semantic rules to decide whether
+     *  to resume or discard before calling this. */
+    resumeJournal(journal: Journal): void;
+}
+/** Options for `createHistory`. */
+interface CreateHistoryOptions {
+    /** Window (ms) within which a new entry may merge into the previous one
+     *  via matching `Op.coalesceKey`. Defaults to `0` (no coalescing — every
+     *  `applyOps` pushes a discrete entry). Recommended: ~500ms for typical
+     *  rapid-input UX (nudge, per-keystroke text edits). The window resets on
+     *  each successful coalesce, so a sustained burst keeps merging. */
+    coalesceWindowMs?: number;
+    /** Clock injection point for tests. Defaults to `Date.now`. */
+    now?: () => number;
+    /** Maximum undo-stack depth. When a push overflows the cap the oldest
+     *  entry is evicted (reported via `onEvict`) and can no longer be undone.
+     *  `0` disables the undo stack entirely — every push is evicted
+     *  synchronously (negative values are clamped to `0`). Default: unbounded. */
+    historyLimit?: number;
+    /** Fired once per entry that permanently leaves the reachable stacks:
+     *  redo entries dropped by a branch edit (a new push / coalesce /
+     *  `recordEntry` after undo) and undo entries evicted by `historyLimit`.
+     *  NOT fired by `clear()` or `restore()` — those wholesale-replace the
+     *  history and the caller already knows. Note `restore()` does not enforce
+     *  `historyLimit` either: a restored snapshot may exceed the cap, which
+     *  re-applies (evicting via `onEvict`) on the next push. */
+    onEvict?: (entry: EvictedEntry) => void;
+    /** Custom op rebuilder consulted by `restore()` before the global
+     *  op-factory registry. Return `null` to fall through (global registry,
+     *  then a no-op placeholder). Lets an owner rebuild ops whose handlers
+     *  live in per-instance state the global registry can't reach (e.g. a
+     *  Scene's registered op kinds).
+     *
+     *  May be invoked more than once per entry with the same `(name, args)` —
+     *  once per op for `forwardOps` and again for `baseOps` (the same array
+     *  until a coalesce splits them). Unlike `onEvict`, a throwing hook is
+     *  NOT caught: it aborts `restore()` mid-rebuild and can leave the
+     *  stacks partially rebuilt. */
+    rebuildOp?: (name: string, args: unknown) => Op | null;
+    /** Diagnostics sink. Omitted, the engine is silent — it deliberately owns no
+     *  logging utility, so that this package depends on nothing. `@weasel-js/core`'s
+     *  `createHistory` wrapper routes these into its `debug/flag` namespace, which
+     *  is what makes `DEBUG=history` work for kit consumers. */
+    debug?: HistoryLogger;
+}
+/** Diagnostics sink for {@link CreateHistoryOptions.debug}. Messages arrive
+ *  pre-formatted and unconditional; deciding whether to emit them is the
+ *  caller's job. */
+interface HistoryLogger {
+    log(message: string): void;
+    warn(message: string): void;
+}
+/** Build an op-batched undo/redo `History`. The adapter is passed to each op's `apply`/`invert`. */
+declare function createHistory(adapter: unknown, options?: CreateHistoryOptions): History;
+
+export { type BeginJournalOptions, type CreateHistoryOptions, type EvictedEntry, type History, type HistoryEntry, type HistoryLogger, type Journal, type Op, type SerializedHistory, type SerializedHistoryEntry, type SerializedOp, createHistory };

package/dist/index.js

@@ -0,0 +1,371 @@
+// src/journal.ts
+var RESUMERS = /* @__PURE__ */ new WeakMap();
+function _resumeJournalInternal(j) {
+  const r = RESUMERS.get(j);
+  if (!r) throw new Error("Journal is not resumable (already committed or cancelled)");
+  r();
+}
+function createJournalInternal(parent, adapter, opts, onClose) {
+  const inner = createHistory(adapter);
+  const forkedAtEntryId = parent.currentEntryId();
+  let state = "active";
+  const targetId = opts.targetId;
+  const journal = {
+    targetId,
+    forkedAtEntryId,
+    applyBatch(ops, label) {
+      if (state !== "active") throw new Error("Journal is not active");
+      inner.applyOps(ops, label);
+    },
+    undo() {
+      if (state !== "active") throw new Error("Journal is not active");
+      inner.undo();
+    },
+    redo() {
+      if (state !== "active") throw new Error("Journal is not active");
+      inner.redo();
+    },
+    canUndo() {
+      return inner.canUndo();
+    },
+    canRedo() {
+      return inner.canRedo();
+    },
+    entries() {
+      return inner.entries();
+    },
+    commit(label) {
+      if (state !== "active") throw new Error("Journal is not active");
+      const netOps = inner.allForwardOps();
+      if (netOps.length > 0) {
+        parent.recordEntry(netOps, label);
+      }
+      state = "closed";
+      RESUMERS.delete(journal);
+      onClose?.();
+    },
+    cancel() {
+      if (state !== "active") throw new Error("Journal is not active");
+      inner.goto(0);
+      state = "closed";
+      RESUMERS.delete(journal);
+      onClose?.();
+    },
+    suspend() {
+      if (state !== "active") throw new Error("Journal is not active");
+      state = "suspended";
+      onClose?.();
+    },
+    isActive() {
+      return state === "active";
+    }
+  };
+  RESUMERS.set(journal, () => {
+    if (state !== "suspended") throw new Error("Journal is not suspended");
+    state = "active";
+  });
+  return journal;
+}
+
+// src/history.ts
+var SILENT = { log: () => {
+}, warn: () => {
+} };
+function createHistory(adapter, options = {}) {
+  const undoStack = [];
+  const redoStack = [];
+  let activeJournal = null;
+  const coalesceWindowMs = options.coalesceWindowMs ?? 0;
+  const now = options.now ?? (() => Date.now());
+  const historyLimit = Math.max(0, options.historyLimit ?? Infinity);
+  const onEvict = options.onEvict;
+  const customRebuild = options.rebuildOp;
+  const logger = options.debug ?? SILENT;
+  let nextEntryId = 1;
+  let version = 0;
+  const listeners = /* @__PURE__ */ new Set();
+  function bump() {
+    version++;
+    for (const l of listeners) l();
+  }
+  function reportEvicted(entries) {
+    if (!onEvict) return;
+    for (const e of entries) {
+      try {
+        onEvict({ id: e.id, label: e.label, forwardOps: e.forwardOps, baseOps: e.baseOps });
+      } catch (err) {
+        logger.warn(`onEvict callback threw for entry id=${e.id} "${e.label}": ${String(err)}`);
+      }
+    }
+  }
+  function dropRedo() {
+    if (redoStack.length === 0) return;
+    reportEvicted(redoStack.splice(0));
+  }
+  function enforceLimit() {
+    while (undoStack.length > historyLimit) {
+      reportEvicted([undoStack.shift()]);
+    }
+  }
+  function applyOps(ops) {
+    for (const op of ops) op.apply(adapter);
+  }
+  function applyOpsAndDetectMutation(ops) {
+    let anyMutated = false;
+    for (const op of ops) {
+      const r = op.apply(adapter);
+      if (r !== false && r !== "noop") anyMutated = true;
+    }
+    return anyMutated;
+  }
+  function invertEntry(entry) {
+    return [...entry.baseOps].reverse().map((op) => op.invert());
+  }
+  function canCoalesce(top, incoming) {
+    if (coalesceWindowMs <= 0) return false;
+    if (now() - top.timestamp > coalesceWindowMs) return false;
+    if (top.forwardOps.length === 0 || incoming.length === 0) return false;
+    if (top.forwardOps.length !== incoming.length) return false;
+    const counts = /* @__PURE__ */ new Map();
+    for (const op of top.forwardOps) {
+      const k = op.coalesceKey;
+      if (k === void 0) return false;
+      counts.set(k, (counts.get(k) ?? 0) + 1);
+    }
+    for (const op of incoming) {
+      const k = op.coalesceKey;
+      if (k === void 0) return false;
+      const c = counts.get(k);
+      if (!c) return false;
+      counts.set(k, c - 1);
+    }
+    return true;
+  }
+  function pushOrCoalesce(ops, label) {
+    if (ops.length === 0) return;
+    const anyMutated = applyOpsAndDetectMutation(ops);
+    if (!anyMutated) {
+      logger.warn(
+        `'${label}' batch was a no-op \u2014 every op reported false/'noop'. Skipping the undo entry; consider gating the dispatch upstream to avoid the wasted work.`
+      );
+      return;
+    }
+    const incoming = touchedIdsFromOps(ops);
+    const top = undoStack[undoStack.length - 1];
+    if (top && canCoalesce(top, ops)) {
+      top.forwardOps = ops;
+      top.timestamp = now();
+      if (incoming.size > 0) {
+        const merged = new Set(top.touchedIds);
+        for (const id of incoming) merged.add(id);
+        top.touchedIds = merged;
+      }
+      dropRedo();
+      logger.log(`coalesce '${label}' into entry id=${top.id} (${ops.length} ops)`);
+      bump();
+      return;
+    }
+    logger.log(`push '${label}' (${ops.length} ops)`);
+    undoStack.push({ id: nextEntryId++, forwardOps: ops, baseOps: ops, label, timestamp: now(), touchedIds: incoming });
+    dropRedo();
+    enforceLimit();
+    bump();
+  }
+  return {
+    apply(op, label) {
+      pushOrCoalesce([op], label ?? op.label ?? "");
+    },
+    applyOps(ops, label) {
+      pushOrCoalesce(ops, label);
+    },
+    undo() {
+      const entry = undoStack.pop();
+      if (!entry) return;
+      applyOps(invertEntry(entry));
+      redoStack.push(entry);
+      bump();
+    },
+    redo() {
+      const entry = redoStack.pop();
+      if (!entry) return;
+      applyOps(entry.forwardOps);
+      undoStack.push(entry);
+      bump();
+    },
+    canUndo: () => undoStack.length > 0,
+    canRedo: () => redoStack.length > 0,
+    undoDepth: () => undoStack.length,
+    redoDepth: () => redoStack.length,
+    clear: () => {
+      const had = undoStack.length > 0 || redoStack.length > 0;
+      undoStack.length = 0;
+      redoStack.length = 0;
+      if (had) bump();
+    },
+    entries() {
+      const toView = (e) => ({ id: e.id, label: e.label, timestamp: e.timestamp, touchedIds: e.touchedIds });
+      return {
+        undo: undoStack.map(toView),
+        redo: [...redoStack].reverse().map(toView)
+      };
+    },
+    goto(n) {
+      const total = undoStack.length + redoStack.length;
+      if (n < 0 || n > total) return;
+      while (undoStack.length > n) {
+        const entry = undoStack.pop();
+        applyOps(invertEntry(entry));
+        redoStack.push(entry);
+      }
+      while (undoStack.length < n) {
+        const entry = redoStack.pop();
+        if (!entry) break;
+        applyOps(entry.forwardOps);
+        undoStack.push(entry);
+      }
+      bump();
+    },
+    getVersion: () => version,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    serialize() {
+      let dropped = 0;
+      const project = (e) => {
+        const s = entryToSerial(e, logger);
+        if (s === null) dropped++;
+        return s;
+      };
+      return {
+        version: 1,
+        undoStack: undoStack.map(project).filter((e) => e !== null),
+        redoStack: redoStack.map(project).filter((e) => e !== null),
+        nextEntryId,
+        droppedEntries: dropped
+      };
+    },
+    recordEntry(ops, label) {
+      if (ops.length === 0) return;
+      undoStack.push({ id: nextEntryId++, forwardOps: ops, baseOps: ops, label, timestamp: now(), touchedIds: touchedIdsFromOps(ops) });
+      dropRedo();
+      enforceLimit();
+      bump();
+    },
+    allForwardOps() {
+      const out = [];
+      for (const e of undoStack) {
+        for (const op of e.forwardOps) out.push(op);
+      }
+      return out;
+    },
+    currentEntryId() {
+      return nextEntryId;
+    },
+    beginJournal(opts) {
+      if (activeJournal !== null && activeJournal.isActive()) {
+        throw new Error("A journal is already active \u2014 commit, cancel, or suspend it first");
+      }
+      const j = createJournalInternal(this, adapter, opts, () => {
+        activeJournal = null;
+      });
+      activeJournal = j;
+      return j;
+    },
+    resumeJournal(journal) {
+      _resumeJournalInternal(journal);
+    },
+    restore(snapshot) {
+      undoStack.length = 0;
+      redoStack.length = 0;
+      for (const se of snapshot.undoStack) {
+        undoStack.push(serialToEntry(se, customRebuild, logger));
+      }
+      for (const se of snapshot.redoStack) {
+        redoStack.push(serialToEntry(se, customRebuild, logger));
+      }
+      nextEntryId = snapshot.nextEntryId;
+      for (const e of undoStack) if (e.id >= nextEntryId) nextEntryId = e.id + 1;
+      for (const e of redoStack) if (e.id >= nextEntryId) nextEntryId = e.id + 1;
+      bump();
+    }
+  };
+}
+function touchedIdsFromOps(ops) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const op of ops) {
+    if (op.args === null || typeof op.args !== "object") continue;
+    const a = op.args;
+    if (typeof a["id"] === "string") {
+      ids.add(a["id"]);
+    } else if (a["node"] !== null && typeof a["node"] === "object") {
+      const n = a["node"];
+      if (typeof n["id"] === "string") ids.add(n["id"]);
+    }
+  }
+  return ids;
+}
+function opToSerial(op) {
+  if (typeof op.name !== "string") return null;
+  return { name: op.name, args: op.args };
+}
+function entryToSerial(e, logger) {
+  const forwardOps = [];
+  for (const op of e.forwardOps) {
+    const s = opToSerial(op);
+    if (s === null) {
+      logger.log(`serialize: dropping entry id=${e.id} "${e.label}" \u2014 forwardOp without name`);
+      return null;
+    }
+    forwardOps.push(s);
+  }
+  const baseOps = [];
+  for (const op of e.baseOps) {
+    const s = opToSerial(op);
+    if (s === null) {
+      logger.log(`serialize: dropping entry id=${e.id} "${e.label}" \u2014 baseOp without name`);
+      return null;
+    }
+    baseOps.push(s);
+  }
+  return { id: e.id, label: e.label, forwardOps, baseOps };
+}
+function placeholderOp(name, args, label) {
+  const op = {
+    name,
+    args,
+    label,
+    apply: () => "noop",
+    invert: () => op
+  };
+  return op;
+}
+function rebuildSerialOp(so, label, custom, logger) {
+  const viaCustom = custom ? custom(so.name, so.args) : null;
+  if (viaCustom !== null) return viaCustom;
+  logger.log(`restore: unknown op name "${so.name}" \u2014 substituting no-op placeholder`);
+  return placeholderOp(so.name, so.args, label);
+}
+function serialToEntry(se, custom, logger) {
+  const forwardOps = se.forwardOps.map((so) => rebuildSerialOp(so, se.label, custom, logger));
+  const baseOps = se.baseOps.map((so) => rebuildSerialOp(so, se.label, custom, logger));
+  return {
+    id: se.id,
+    label: se.label,
+    forwardOps,
+    baseOps,
+    // Restored entries inherit a "now" timestamp — coalesce eligibility is
+    // a within-session concept and a restored entry shouldn't merge with a
+    // freshly-typed one regardless of when it was originally pushed.
+    timestamp: 0,
+    // Re-derive touchedIds from the rebuilt ops rather than trying to
+    // round-trip the Set through the serialized form (Sets aren't JSON-safe).
+    touchedIds: touchedIdsFromOps(forwardOps)
+  };
+}
+
+export { createHistory };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/journal.ts","../src/history.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import type { Op } from './op';\nimport { createHistory, type History, type HistoryEntry } from './history';\n\nconst RESUMERS = new WeakMap<Journal, () => void>();\n\n/** Called by `history.resumeJournal`. Not part of the public API. */\nexport function _resumeJournalInternal(j: Journal): void {\n  const r = RESUMERS.get(j);\n  if (!r) throw new Error('Journal is not resumable (already committed or cancelled)');\n  r();\n}\n\nexport interface BeginJournalOptions {\n  label: string;\n  targetId?: string;\n}\n\nexport interface Journal {\n  readonly targetId: string | undefined;\n  readonly forkedAtEntryId: number;\n\n  // Same operational surface as History\n  applyBatch(ops: Op[], label: string): void;\n  undo(): void;\n  redo(): void;\n  canUndo(): boolean;\n  canRedo(): boolean;\n  entries(): { undo: HistoryEntry[]; redo: HistoryEntry[] };\n\n  // Lifecycle\n  commit(label: string): void;\n  cancel(): void;\n  suspend(): void;\n  isActive(): boolean;\n}\n\n/** Internal factory used by `createHistory`'s `beginJournal` method.\n *  Not exported via the package's `index.ts` — callers go through\n *  `history.beginJournal()`. */\nexport function createJournalInternal(\n  parent: History,\n  adapter: unknown,\n  opts: BeginJournalOptions,\n  onClose?: () => void,\n): Journal {\n  const inner = createHistory(adapter);\n  const forkedAtEntryId = parent.currentEntryId();\n  type State = 'active' | 'suspended' | 'closed';\n  let state: State = 'active';\n  const targetId = opts.targetId;\n\n  const journal: Journal = {\n    targetId,\n    forkedAtEntryId,\n\n    applyBatch(ops: Op[], label: string): void {\n      if (state !== 'active') throw new Error('Journal is not active');\n      inner.applyOps(ops, label);\n    },\n    undo(): void {\n      if (state !== 'active') throw new Error('Journal is not active');\n      inner.undo();\n    },\n    redo(): void {\n      if (state !== 'active') throw new Error('Journal is not active');\n      inner.redo();\n    },\n    canUndo(): boolean {\n      return inner.canUndo();\n    },\n    canRedo(): boolean {\n      return inner.canRedo();\n    },\n    entries() {\n      return inner.entries();\n    },\n    commit(label: string): void {\n      if (state !== 'active') throw new Error('Journal is not active');\n      const netOps = inner.allForwardOps();\n      if (netOps.length > 0) {\n        parent.recordEntry(netOps, label);\n      }\n      state = 'closed';\n      RESUMERS.delete(journal);\n      onClose?.();\n    },\n    cancel(): void {\n      if (state !== 'active') throw new Error('Journal is not active');\n      inner.goto(0);\n      state = 'closed';\n      RESUMERS.delete(journal);\n      onClose?.();\n    },\n    suspend(): void {\n      if (state !== 'active') throw new Error('Journal is not active');\n      state = 'suspended';\n      onClose?.();\n    },\n    isActive(): boolean {\n      return state === 'active';\n    },\n  };\n\n  RESUMERS.set(journal, () => {\n    if (state !== 'suspended') throw new Error('Journal is not suspended');\n    state = 'active';\n  });\n\n  return journal;\n}\n","import type { Op } from './op';\nimport { createJournalInternal, _resumeJournalInternal, type Journal, type BeginJournalOptions } from './journal';\n\ninterface Entry {\n  /** Monotonic id assigned at first push. Stable across coalesce merges\n   *  (a merged entry keeps the original id) so UI lists keyed on `id` don't\n   *  flicker when the underlying entry mutates. */\n  id: number;\n  /** Forward ops — applied on redo, reflect the latest to-state after any\n   *  coalescing. Diverges from `baseOps` only after a coalesce. */\n  forwardOps: Op[];\n  /** Original ops at first push — their `.invert()` is what undo replays.\n   *  Preserved across coalesces so undo always returns to the original\n   *  pre-edit state, no matter how many coalesces happened. */\n  baseOps: Op[];\n  label: string;\n  /** ms timestamp at last push or coalesce; used to gate the coalesce window. */\n  timestamp: number;\n  /** Node ids touched by ops in this entry. See `HistoryEntry.touchedIds`. */\n  touchedIds: ReadonlySet<string>;\n}\n\n/** Wire form of a single op inside a serialized history. The pair\n *  `(name, args)` reconstructs a live `Op` via the op-factory registry. */\nexport interface SerializedOp {\n  name: string;\n  args: unknown;\n}\n\n/** Wire form of one history entry. `forwardOps` / `baseOps` mirror the\n *  in-memory entry's fields (see `Entry` above) but only carry the\n *  serializable `(name, args)` projection of each op. */\nexport interface SerializedHistoryEntry {\n  id: number;\n  label: string;\n  forwardOps: SerializedOp[];\n  baseOps: SerializedOp[];\n}\n\n/** Snapshot of an entire `History` instance. Designed to live alongside the\n *  scene snapshot in IDB so a reload restores the undo / redo stacks to\n *  exactly where they were. */\nexport interface SerializedHistory {\n  version: 1;\n  undoStack: SerializedHistoryEntry[];\n  /** Stored newest-first, mirroring the in-memory stack so a deserialized\n   *  history matches the original's `entries().redo` ordering. */\n  redoStack: SerializedHistoryEntry[];\n  nextEntryId: number;\n  /** Entries dropped because at least one of their ops lacked a `name`\n   *  and therefore couldn't round-trip through the op-factory registry.\n   *  Always present (zero when nothing was dropped) so callers can detect\n   *  loss without parsing the debug log. */\n  droppedEntries: number;\n}\n\n/** Snapshot of an entry handed to `onEvict` when it permanently leaves the\n *  reachable stacks. Ops are live references — read `name`/`args`, don't\n *  mutate. */\nexport interface EvictedEntry {\n  id: number;\n  label: string;\n  forwardOps: readonly Op[];\n  baseOps: readonly Op[];\n}\n\n/** Read-only view of a history entry exposed via `History.entries()`. */\nexport interface HistoryEntry {\n  /** Stable monotonic id (preserved across coalesce merges). */\n  id: number;\n  /** Human-readable label (the `label` arg passed to `applyOps`). */\n  label: string;\n  /** Push/last-coalesce timestamp (ms). */\n  timestamp: number;\n  /** Set of node ids touched by any op in this entry. Populated from ops\n   *  whose `args` carry an `id` field (transform, setPath, reparent) or a\n   *  `node.id` field (insert, delete). Ops without a recognisable id field\n   *  contribute nothing. May be `undefined` for deserialized entries\n   *  restored from an older snapshot that predates this field. */\n  touchedIds?: ReadonlySet<string>;\n}\n\n/** Op-batched undo/redo controller returned by `createHistory`. */\nexport interface History {\n  apply(op: Op, label?: string): void;\n  applyOps(ops: Op[], label: string): void;\n  undo(): void;\n  redo(): void;\n  canUndo(): boolean;\n  canRedo(): boolean;\n  /** Number of entries on the undo stack (O(1); `entries().undo.length`\n   *  without materializing the views). */\n  undoDepth(): number;\n  /** Number of entries on the redo stack (O(1)). */\n  redoDepth(): number;\n  clear(): void;\n  /** Snapshot of the current undo + redo stacks. `undo` is oldest→newest\n   *  (i.e. the last element is what `undo()` would pop next); `redo` is\n   *  also oldest→newest from the user's perspective (i.e. the *first*\n   *  element is what `redo()` would pop next — see implementation note).\n   *  Callers should treat the arrays as immutable. */\n  entries(): { undo: HistoryEntry[]; redo: HistoryEntry[] };\n  /** Walk the history forward/back until exactly `n` entries are on the\n   *  undo stack (0 ≤ n ≤ entries().undo.length + entries().redo.length).\n   *  Equivalent to repeated `undo()`/`redo()` calls but doesn't bother\n   *  rebuilding entry snapshots between steps. No-op if already at `n`. */\n  goto(n: number): void;\n  /** Monotonic counter bumped on every push/undo/redo/clear/coalesce.\n   *  Cheap to read; callers use it as a React dep to detect changes. */\n  getVersion(): number;\n  /** Subscribe to history changes. Fires after every push/undo/redo/\n   *  clear/coalesce. Returns an unsubscribe fn. */\n  subscribe(listener: () => void): () => void;\n  /** Snapshot the undo + redo stacks in a structured-clone-safe form.\n   *  Entries whose ops aren't all kit-registered (i.e. any op missing a\n   *  `name`) are dropped from the snapshot with a debug-level log — they\n   *  can't round-trip, so we omit them rather than emit a half-restorable\n   *  entry. The in-memory stacks aren't modified. */\n  serialize(): SerializedHistory;\n  /** Replace the current undo + redo stacks with the deserialized contents\n   *  of `snapshot`. Ops are rebuilt via the `rebuildOp` option when\n   *  provided, then the global registry; unknown names become no-op\n   *  placeholders so stack ordering survives across kit-version skew.\n   *  Bumps `version` and notifies subscribers exactly once. */\n  restore(snapshot: SerializedHistory): void;\n  /** Push an entry whose ops have already been applied to the adapter.\n   *  Unlike `applyOps`, does NOT call `op.apply()`. Used by Journal.commit\n   *  to flush a session's net forward ops to the parent as one entry without\n   *  re-mutating the scene. */\n  recordEntry(ops: Op[], label: string): void;\n  /** Concatenated forwardOps of every undo-stack entry, in order. Snapshot\n   *  of \"what changes are currently applied via this history\" — useful for\n   *  Journal.commit to flush to a parent, and for any caller that wants to\n   *  diff against a baseline. */\n  allForwardOps(): Op[];\n  /** The id that will be assigned to the *next* pushed entry. Stable\n   *  monotonic counter; callers use it to tag a fork point (see Journal). */\n  currentEntryId(): number;\n  /** Open a scoped sub-history. All apply/undo/redo on the returned Journal\n   *  affect the same adapter; on commit, the Journal's net forward ops are\n   *  flushed to this History as one entry. See spec docs/superpowers/specs/\n   *  2026-05-24-modality-design.md for the full lifecycle. */\n  beginJournal(opts: BeginJournalOptions): Journal;\n  /** Re-activate a suspended journal. Throws if the journal was committed or\n   *  cancelled (those are terminal). Staleness checking is the caller's\n   *  responsibility — consult `journal.forkedAtEntryId` against\n   *  `currentEntryId()` and your own op-semantic rules to decide whether\n   *  to resume or discard before calling this. */\n  resumeJournal(journal: Journal): void;\n}\n\n/** Options for `createHistory`. */\nexport interface CreateHistoryOptions {\n  /** Window (ms) within which a new entry may merge into the previous one\n   *  via matching `Op.coalesceKey`. Defaults to `0` (no coalescing — every\n   *  `applyOps` pushes a discrete entry). Recommended: ~500ms for typical\n   *  rapid-input UX (nudge, per-keystroke text edits). The window resets on\n   *  each successful coalesce, so a sustained burst keeps merging. */\n  coalesceWindowMs?: number;\n  /** Clock injection point for tests. Defaults to `Date.now`. */\n  now?: () => number;\n  /** Maximum undo-stack depth. When a push overflows the cap the oldest\n   *  entry is evicted (reported via `onEvict`) and can no longer be undone.\n   *  `0` disables the undo stack entirely — every push is evicted\n   *  synchronously (negative values are clamped to `0`). Default: unbounded. */\n  historyLimit?: number;\n  /** Fired once per entry that permanently leaves the reachable stacks:\n   *  redo entries dropped by a branch edit (a new push / coalesce /\n   *  `recordEntry` after undo) and undo entries evicted by `historyLimit`.\n   *  NOT fired by `clear()` or `restore()` — those wholesale-replace the\n   *  history and the caller already knows. Note `restore()` does not enforce\n   *  `historyLimit` either: a restored snapshot may exceed the cap, which\n   *  re-applies (evicting via `onEvict`) on the next push. */\n  onEvict?: (entry: EvictedEntry) => void;\n  /** Custom op rebuilder consulted by `restore()` before the global\n   *  op-factory registry. Return `null` to fall through (global registry,\n   *  then a no-op placeholder). Lets an owner rebuild ops whose handlers\n   *  live in per-instance state the global registry can't reach (e.g. a\n   *  Scene's registered op kinds).\n   *\n   *  May be invoked more than once per entry with the same `(name, args)` —\n   *  once per op for `forwardOps` and again for `baseOps` (the same array\n   *  until a coalesce splits them). Unlike `onEvict`, a throwing hook is\n   *  NOT caught: it aborts `restore()` mid-rebuild and can leave the\n   *  stacks partially rebuilt. */\n  rebuildOp?: (name: string, args: unknown) => Op | null;\n  /** Diagnostics sink. Omitted, the engine is silent — it deliberately owns no\n   *  logging utility, so that this package depends on nothing. `@weasel-js/core`'s\n   *  `createHistory` wrapper routes these into its `debug/flag` namespace, which\n   *  is what makes `DEBUG=history` work for kit consumers. */\n  debug?: HistoryLogger;\n}\n\n/** Diagnostics sink for {@link CreateHistoryOptions.debug}. Messages arrive\n *  pre-formatted and unconditional; deciding whether to emit them is the\n *  caller's job. */\nexport interface HistoryLogger {\n  log(message: string): void;\n  warn(message: string): void;\n}\n\n/** Silent default — keeps every call site unconditional. */\nconst SILENT: HistoryLogger = { log: () => {}, warn: () => {} };\n\n/** Build an op-batched undo/redo `History`. The adapter is passed to each op's `apply`/`invert`. */\nexport function createHistory(adapter: unknown, options: CreateHistoryOptions = {}): History {\n  const undoStack: Entry[] = [];\n  const redoStack: Entry[] = [];\n  let activeJournal: Journal | null = null;\n  const coalesceWindowMs = options.coalesceWindowMs ?? 0;\n  const now = options.now ?? (() => Date.now());\n  const historyLimit = Math.max(0, options.historyLimit ?? Infinity);\n  const onEvict = options.onEvict;\n  const customRebuild = options.rebuildOp;\n  const logger = options.debug ?? SILENT;\n  let nextEntryId = 1;\n  let version = 0;\n  const listeners = new Set<() => void>();\n  function bump(): void {\n    version++;\n    for (const l of listeners) l();\n  }\n\n  /** Report entries that just became permanently unreachable. A throwing\n   *  callback must not desync the stacks mid-mutation, so failures are\n   *  contained and surfaced via the debug flag. */\n  function reportEvicted(entries: Entry[]): void {\n    if (!onEvict) return;\n    for (const e of entries) {\n      try {\n        onEvict({ id: e.id, label: e.label, forwardOps: e.forwardOps, baseOps: e.baseOps });\n      } catch (err) {\n        logger.warn(`onEvict callback threw for entry id=${e.id} \"${e.label}\": ${String(err)}`);\n      }\n    }\n  }\n\n  /** Clear the redo stack (branch-on-edit), reporting dropped entries. */\n  function dropRedo(): void {\n    if (redoStack.length === 0) return;\n    reportEvicted(redoStack.splice(0));\n  }\n\n  /** Evict the oldest undo entries past `historyLimit`, reporting each. */\n  function enforceLimit(): void {\n    while (undoStack.length > historyLimit) {\n      reportEvicted([undoStack.shift()!]);\n    }\n  }\n\n  function applyOps(ops: Op[]): void {\n    for (const op of ops) op.apply(adapter);\n  }\n\n  /** Apply each op and collect whether any reported a real mutation.\n   *  Returns true iff at least one op did NOT explicitly return `false` /\n   *  `'noop'`. Used by `pushOrCoalesce` to skip pushing entries when every\n   *  op in the batch was a silent no-op (e.g. reorder where the order\n   *  already matched). Existing ops that return `undefined`/`void` count\n   *  as \"mutated\" — the default — so this is backwards-compatible. */\n  function applyOpsAndDetectMutation(ops: Op[]): boolean {\n    let anyMutated = false;\n    for (const op of ops) {\n      const r = op.apply(adapter);\n      if (r !== false && r !== 'noop') anyMutated = true;\n    }\n    return anyMutated;\n  }\n\n  function invertEntry(entry: Entry): Op[] {\n    return [...entry.baseOps].reverse().map((op) => op.invert());\n  }\n\n  /** Coalesce eligibility: every op on both sides has a `coalesceKey`, and\n   *  the multisets of keys match (order-independent). Match by multiset\n   *  rather than positional index so a multi-id selection can re-emit ops in\n   *  any order between batches without breaking the merge. */\n  function canCoalesce(top: Entry, incoming: Op[]): boolean {\n    if (coalesceWindowMs <= 0) return false;\n    if (now() - top.timestamp > coalesceWindowMs) return false;\n    if (top.forwardOps.length === 0 || incoming.length === 0) return false;\n    if (top.forwardOps.length !== incoming.length) return false;\n    const counts = new Map<string, number>();\n    for (const op of top.forwardOps) {\n      const k = op.coalesceKey;\n      if (k === undefined) return false;\n      counts.set(k, (counts.get(k) ?? 0) + 1);\n    }\n    for (const op of incoming) {\n      const k = op.coalesceKey;\n      if (k === undefined) return false;\n      const c = counts.get(k);\n      if (!c) return false;\n      counts.set(k, c - 1);\n    }\n    return true;\n  }\n\n  function pushOrCoalesce(ops: Op[], label: string): void {\n    if (ops.length === 0) return;\n    const anyMutated = applyOpsAndDetectMutation(ops);\n    if (!anyMutated) {\n      // Every op reported `false`/`'noop'`. Skip the push so undo stays\n      // tied to real state changes. Surfaced through the kit's debug\n      // flag so the upstream caller can consider avoiding the dispatch\n      // entirely. Hidden by default; enable via\n      // `localStorage.setItem('weasel.debug', '1')`.\n      logger.warn(\n        `'${label}' batch was a no-op — every op reported false/'noop'. ` +\n        `Skipping the undo entry; consider gating the dispatch upstream to avoid the wasted work.`,\n      );\n      return;\n    }\n    const incoming = touchedIdsFromOps(ops);\n    const top = undoStack[undoStack.length - 1];\n    if (top && canCoalesce(top, ops)) {\n      top.forwardOps = ops;\n      top.timestamp = now();\n      // Merge incoming touched ids into the coalesced entry's set.\n      if (incoming.size > 0) {\n        const merged = new Set(top.touchedIds);\n        for (const id of incoming) merged.add(id);\n        top.touchedIds = merged;\n      }\n      // baseOps + label + id intentionally preserved — undo returns to the\n      // pre-edit state, the original label sticks, and the entry id stays\n      // stable so React lists keyed on id don't flicker.\n      dropRedo();\n      logger.log(`coalesce '${label}' into entry id=${top.id} (${ops.length} ops)`);\n      bump();\n      return;\n    }\n    logger.log(`push '${label}' (${ops.length} ops)`);\n    undoStack.push({ id: nextEntryId++, forwardOps: ops, baseOps: ops, label, timestamp: now(), touchedIds: incoming });\n    dropRedo();\n    enforceLimit();\n    bump();\n  }\n\n  return {\n    apply(op, label) {\n      pushOrCoalesce([op], label ?? op.label ?? '');\n    },\n    applyOps(ops, label) {\n      pushOrCoalesce(ops, label);\n    },\n    undo() {\n      const entry = undoStack.pop();\n      if (!entry) return;\n      applyOps(invertEntry(entry));\n      redoStack.push(entry);\n      bump();\n    },\n    redo() {\n      const entry = redoStack.pop();\n      if (!entry) return;\n      applyOps(entry.forwardOps);\n      undoStack.push(entry);\n      bump();\n    },\n    canUndo: () => undoStack.length > 0,\n    canRedo: () => redoStack.length > 0,\n    undoDepth: () => undoStack.length,\n    redoDepth: () => redoStack.length,\n    clear: () => {\n      const had = undoStack.length > 0 || redoStack.length > 0;\n      undoStack.length = 0;\n      redoStack.length = 0;\n      if (had) bump();\n    },\n    entries() {\n      const toView = (e: Entry): HistoryEntry => ({ id: e.id, label: e.label, timestamp: e.timestamp, touchedIds: e.touchedIds });\n      // redoStack is internally stored newest-on-top (so `pop()` redoes the\n      // next-most-recent undo). Reverse on the way out so callers see the\n      // entries in chronological order — the user's next redo is the first\n      // element, matching `entries().redo[0]` semantics.\n      return {\n        undo: undoStack.map(toView),\n        redo: [...redoStack].reverse().map(toView),\n      };\n    },\n    goto(n) {\n      // Total length stays constant during this walk (we only shuffle\n      // entries between undo and redo stacks).\n      const total = undoStack.length + redoStack.length;\n      if (n < 0 || n > total) return;\n      while (undoStack.length > n) {\n        const entry = undoStack.pop()!;\n        applyOps(invertEntry(entry));\n        redoStack.push(entry);\n      }\n      while (undoStack.length < n) {\n        const entry = redoStack.pop();\n        if (!entry) break; // defensive — shouldn't fire given the bounds check above\n        applyOps(entry.forwardOps);\n        undoStack.push(entry);\n      }\n      bump();\n    },\n    getVersion: () => version,\n    subscribe(listener) {\n      listeners.add(listener);\n      return () => { listeners.delete(listener); };\n    },\n    serialize(): SerializedHistory {\n      let dropped = 0;\n      const project = (e: Entry): SerializedHistoryEntry | null => {\n        const s = entryToSerial(e, logger);\n        if (s === null) dropped++;\n        return s;\n      };\n      return {\n        version: 1,\n        undoStack: undoStack.map(project).filter((e): e is SerializedHistoryEntry => e !== null),\n        redoStack: redoStack.map(project).filter((e): e is SerializedHistoryEntry => e !== null),\n        nextEntryId,\n        droppedEntries: dropped,\n      };\n    },\n    recordEntry(ops: Op[], label: string): void {\n      if (ops.length === 0) return;\n      undoStack.push({ id: nextEntryId++, forwardOps: ops, baseOps: ops, label, timestamp: now(), touchedIds: touchedIdsFromOps(ops) });\n      dropRedo();\n      enforceLimit();\n      bump();\n    },\n    allForwardOps(): Op[] {\n      const out: Op[] = [];\n      for (const e of undoStack) {\n        for (const op of e.forwardOps) out.push(op);\n      }\n      return out;\n    },\n    currentEntryId(): number {\n      return nextEntryId;\n    },\n    beginJournal(opts: BeginJournalOptions): Journal {\n      if (activeJournal !== null && activeJournal.isActive()) {\n        throw new Error('A journal is already active — commit, cancel, or suspend it first');\n      }\n      // `adapter` is the closure-captured adapter passed to createHistory.\n      // The returned History object's `this` doesn't carry it, so we pass\n      // it through to the factory directly.\n      const j = createJournalInternal(this, adapter, opts, () => { activeJournal = null; });\n      activeJournal = j;\n      return j;\n    },\n    resumeJournal(journal: Journal): void {\n      _resumeJournalInternal(journal);\n    },\n    restore(snapshot: SerializedHistory): void {\n      undoStack.length = 0;\n      redoStack.length = 0;\n      for (const se of snapshot.undoStack) {\n        undoStack.push(serialToEntry(se, customRebuild, logger));\n      }\n      for (const se of snapshot.redoStack) {\n        redoStack.push(serialToEntry(se, customRebuild, logger));\n      }\n      // Seed nextEntryId from the snapshot, then defensively bump past any\n      // restored id — a malformed snapshot with duplicate or out-of-range\n      // ids should never produce a collision with future entries.\n      nextEntryId = snapshot.nextEntryId;\n      for (const e of undoStack) if (e.id >= nextEntryId) nextEntryId = e.id + 1;\n      for (const e of redoStack) if (e.id >= nextEntryId) nextEntryId = e.id + 1;\n      bump();\n    },\n  };\n}\n\n/** Extract node ids from an op's `args`. Handles the common patterns:\n *  - `args.id` (string) — transform, setPath, reparent\n *  - `args.node.id` (string) — insert, delete\n *  Ops that don't match either pattern contribute nothing.\n *  Exported for in-package test use; not part of the published package API. */\nexport function touchedIdsFromOps(ops: Op[]): ReadonlySet<string> {\n  const ids = new Set<string>();\n  for (const op of ops) {\n    if (op.args === null || typeof op.args !== 'object') continue;\n    const a = op.args as Record<string, unknown>;\n    if (typeof a['id'] === 'string') {\n      ids.add(a['id']);\n    } else if (a['node'] !== null && typeof a['node'] === 'object') {\n      const n = a['node'] as Record<string, unknown>;\n      if (typeof n['id'] === 'string') ids.add(n['id']);\n    }\n  }\n  return ids;\n}\n\n/** Project an `Op` to its `(name, args)` wire form. Returns `null` for ops\n *  missing `name` — the caller drops the containing entry. */\nfunction opToSerial(op: Op): SerializedOp | null {\n  if (typeof op.name !== 'string') return null;\n  return { name: op.name, args: op.args };\n}\n\n/** Project a runtime entry to its serialized form, or `null` if any op in\n *  the entry can't be serialized (we drop the whole entry then — a partially\n *  serializable entry would invert against the wrong baseline on undo). */\nfunction entryToSerial(e: Entry, logger: HistoryLogger): SerializedHistoryEntry | null {\n  const forwardOps: SerializedOp[] = [];\n  for (const op of e.forwardOps) {\n    const s = opToSerial(op);\n    if (s === null) {\n      logger.log(`serialize: dropping entry id=${e.id} \"${e.label}\" — forwardOp without name`);\n      return null;\n    }\n    forwardOps.push(s);\n  }\n  const baseOps: SerializedOp[] = [];\n  for (const op of e.baseOps) {\n    const s = opToSerial(op);\n    if (s === null) {\n      logger.log(`serialize: dropping entry id=${e.id} \"${e.label}\" — baseOp without name`);\n      return null;\n    }\n    baseOps.push(s);\n  }\n  return { id: e.id, label: e.label, forwardOps, baseOps };\n}\n\n/** Placeholder op used when the registry lacks the requested name. Stable\n *  identity (each placeholder is its own invert) keeps undo/redo plumbing\n *  happy without performing any adapter mutation. */\nfunction placeholderOp(name: string, args: unknown, label?: string): Op {\n  const op: Op = {\n    name,\n    args,\n    label,\n    apply: () => 'noop' as const,\n    invert: () => op,\n  };\n  return op;\n}\n\n/** Signature of a per-instance op rebuilder (`CreateHistoryOptions.rebuildOp`). */\ntype CustomRebuild = (name: string, args: unknown) => Op | null;\n\n/** Rebuild a single serialized op via `custom` (if provided), falling back to\n *  a no-op placeholder.\n *\n *  This engine deliberately knows nothing about any op registry: hydrating a\n *  `(name, args)` pair back into an op is the caller's concern, injected\n *  through `CreateHistoryOptions.rebuildOp`. `@weasel-js/core`'s\n *  `createHistory` wrapper supplies its global op-factory registry as that\n *  hook, so core consumers see unchanged behavior. */\nfunction rebuildSerialOp(so: SerializedOp, label: string, custom: CustomRebuild | undefined, logger: HistoryLogger): Op {\n  const viaCustom = custom ? custom(so.name, so.args) : null;\n  if (viaCustom !== null) return viaCustom;\n  logger.log(`restore: unknown op name \"${so.name}\" — substituting no-op placeholder`);\n  return placeholderOp(so.name, so.args, label);\n}\n\n/** Rebuild a runtime entry from its serialized form. Unknown op names become\n *  no-op placeholders so the entry still occupies its slot in the stack. */\nfunction serialToEntry(se: SerializedHistoryEntry, custom: CustomRebuild | undefined, logger: HistoryLogger): Entry {\n  const forwardOps = se.forwardOps.map((so) => rebuildSerialOp(so, se.label, custom, logger));\n  const baseOps = se.baseOps.map((so) => rebuildSerialOp(so, se.label, custom, logger));\n  return {\n    id: se.id,\n    label: se.label,\n    forwardOps,\n    baseOps,\n    // Restored entries inherit a \"now\" timestamp — coalesce eligibility is\n    // a within-session concept and a restored entry shouldn't merge with a\n    // freshly-typed one regardless of when it was originally pushed.\n    timestamp: 0,\n    // Re-derive touchedIds from the rebuilt ops rather than trying to\n    // round-trip the Set through the serialized form (Sets aren't JSON-safe).\n    touchedIds: touchedIdsFromOps(forwardOps),\n  };\n}\n"]}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@weasel-js/history",
+  "version": "0.5.0",
+  "description": "Undo/redo history with scoped sub-history (Journal) primitive. No React, no DOM.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "author": "orochi235",
+  "homepage": "https://orochi235.github.io/weasel/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/orochi235/weasel.git",
+    "directory": "packages/history"
+  },
+  "bugs": {
+    "url": "https://github.com/orochi235/weasel/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup"
+  }
+}