registerLayer static method

void registerLayer({ required String id, required int activationOrder, required int stackLevel, required InterleavedLayerBuilder builder, BuildContext? context, })

Register or update a layer in the global interleaved host.

Implementation

static void registerLayer({
  required String id,
  required int activationOrder,
  required int stackLevel,
  required InterleavedLayerBuilder builder,
  BuildContext? context,
}) {
  if (!enabled) return;

  final existingIndex = _layers.value.indexWhere((layer) => layer.id == id);
  final next = List<InterleavedOverlayLayer>.from(_layers.value);
  final isNewLayer = existingIndex == -1;

  final candidate = InterleavedOverlayLayer(
    id: id,
    activationOrder: activationOrder,
    stackLevel: stackLevel,
    builder: builder,
  );

  if (existingIndex == -1) {
    // First time registration.
    next.add(candidate);
  } else {
    // Always update the layer in place, even when activation/stack are
    // unchanged. The builder closure may have changed (for example after a
    // rebuild or hot reload), and dropping that update leaves the overlay
    // entry rendering stale content.
    next[existingIndex] = candidate;
  }

  // Sort and publish the updated layer list.
  _sortLayers(next);
  _layers.value = next;
  ensureInstalled(context: context);
  // Only promote/restack on first insertion. Ordinary builder or metadata
  // updates must preserve the mounted subtree state of the layer; otherwise
  // stateful popup/modal content (for example a resized AnimatedContainer)
  // can be recreated and jump back to its initial size right before
  // dismissal.
  _syncEntries(forceToFront: isNewLayer, context: context);
  // Order is sorted by activationOrder (first) then stackLevel (second).
  // activationOrder preserves "first shown" semantics across systems.
  _debugInterleaveLog(
    'registerLayer id=$id order=${_formatLayerOrder(_layers.value)}',
  );
}