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.

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.

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.

Clock injection point for tests. Defaults to Date.now.

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.

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.