Function createHistory

packages/sdk/src/history.ts:44–145

(session: Composition, opts: HistoryOptions = {})

}

export function createHistory(session: Composition, opts: HistoryOptions = {}): HistoryModule {
  const coalesceMs = opts.coalesceMs ?? 300;
  const maxEntries = opts.maxEntries ?? 100;
  const { trackedOrigins } = opts;

  const undoStack: HistoryEntry[] = [];
  let redoStack: HistoryEntry[] = [];

  function isTracked(origin: unknown): boolean {
    if (origin === ORIGIN_APPLY_PATCHES) return false;
    if (!trackedOrigins) return true;
    return trackedOrigins.includes(origin);
  }

  function pathsKey(patches: readonly JsonPatchOp[]): string {
    return patches
      .map((p) => p.path)
      .sort()
      .join("\n");
  }

  function opTypesKey(opTypes: readonly string[]): string {
    // Sorted: the same op-type SET coalesces regardless of dispatch order.
    return [...opTypes].sort().join(",");
  }

  function shouldCoalesce(entry: HistoryEntry, incoming: PatchEvent): boolean {
    if (coalesceMs <= 0) return false;
    if (opTypesKey(entry.opTypes) !== opTypesKey(incoming.opTypes)) return false;
    if (entry.origin !== incoming.origin) return false;
    // Coalesce only when the SAME paths are touched (e.g. slider drag on one
    // property). Without this, rapid edits to different elements would merge
    // into one entry holding the second forward + first inverse — undo would
    // then revert the wrong element.
    if (pathsKey(entry.patches) !== pathsKey(incoming.patches)) return false;
    const now = Date.now();
    return now - entry.timestamp <= coalesceMs;
  }

  // fallow-ignore-next-line complexity
  const unsubscribe = session.on("patch", (event: PatchEvent) => {
    if (!isTracked(event.origin)) return;

    const last = undoStack[undoStack.length - 1];
    if (last && shouldCoalesce(last, event)) {
      // Coalesce: keep first inverse (original prev), replace forward with latest value.
      // Slide timestamp forward so rapid-fire edits keep coalescing.
      const coalesced: HistoryEntry = {
        patches: event.patches,
        inversePatches: last.inversePatches,
        opTypes: last.opTypes,
        origin: last.origin,
        timestamp: Date.now(),
      };
      undoStack[undoStack.length - 1] = coalesced;
    } else {
      undoStack.push({
        patches: event.patches,