layerman library

A headless overlay queue orchestrator.

Manages when/which overlay is shown — serial one-at-a-time queueing with named slots, priority, replace, overlap, conditions and cooldown — while staying UI-agnostic: rendering is delegated to a Present backend (showDialog / GetX / bot_toast / a self-managed OverlayEntry / ...) that the manager invokes when the queue grants a slot. Overlays expose imperative Future<T?> results and a two-phase close so a backend can play its exit animation before the queue advances.

Classes

Layerman

A headless overlay queue orchestrator.

LayermanNavigatorObserver

Feeds real navigation into Layerman.setContext's route key automatically, so route/when/dismissWhenUnmet conditions and pauseOnRoutes react to actual navigation without the host writing setContext({'route': ...}) by hand in every page's lifecycle.

MemoryCooldownStorage

In-memory OverlayCooldownStorage (per-process; survives manager re-creation when the same instance is shared).

OverlayCooldown

Frequency-capping configuration. All present fields must pass (AND), and counts increment when the overlay actually opens (TS parity).

OverlayCooldownStorage

Pluggable persistence for OverlayCooldown counters. The default is MemoryCooldownStorage; back it with shared_preferences (or anything else) in real apps:

OverlayRecord

A lightweight view of one managed entry, handed to Layerman.clearWhere.

PresentContext

Context handed to a Present callback when the queue grants permission to show an overlay.

PresentedOverlay<T>

Bidirectional handle returned by a Present callback.

Typedefs

OverlayPredicate = bool Function(Map<String, Object?> context)

Condition predicate; receives the manager's context map (see Layerman.setContext). When provided it is the SOLE authority — route / requiresAuth sugar is ignored (TS parity).

Present<T> = PresentedOverlay<T> Function(PresentContext context)

Presents an overlay through a UI backend when the queue grants permission. Called at most once per queue entry.