beginSaveState method

void beginSaveState(FluentDocument document, { String description = 'Document change', bool forceNewAction = false, })

Called BEFORE a mutation. Captures the old state of all top-level nodes so commitSaveState can compute a minimal delta afterwards.

Implementation

void beginSaveState(
  FluentDocument document, {
  String description = 'Document change',
  bool forceNewAction = false,
}) {
  if (_isRestoringState) return;

  final now = DateTime.now();

  // If we already have a pending snapshot and the description is the
  // same and within the grouping window, just extend the timer — the
  // old pending snapshot is still valid because no mutation happened yet.
  if (!forceNewAction &&
      _pending != null &&
      _currentGroupDescription != null &&
      description == _currentGroupDescription &&
      _lastActionTime != null &&
      now.difference(_lastActionTime!) <= _groupingTimeout) {
    // Same burst: update timer but keep the SAME old snapshot.
    _pending!.description = description;
    _groupingTimer?.cancel();
    _groupingTimer = Timer(_groupingTimeout, _resetGrouping);
    return;
  }

  // If there's a stale pending snapshot that was never committed,
  // drop it silently (can happen if a programmatic change skipped
  // updateContent).
  if (_pending != null) {
    _pending = null;
  }

  // Capture the old state of every top-level node.
  final nodes = document.content.nodes;
  _pending = _PendingSnapshot(
    description: description,
    timestamp: now,
    oldVersions: nodes.map((n) => n.contentVersion).toList(),
    oldTopLevelNodes: nodes.map((n) => n.toJson()).toList(),
    oldCursor: CursorSnapshot.fromDocument(document),
  );

  _currentGroupDescription = description;
  _lastActionTime = now;
  _groupingTimer?.cancel();
  _groupingTimer = Timer(_groupingTimeout, _resetGrouping);
}