Monitor Scope

Watches for a condition while the nodes inside its zone run, and can redirect the run when it fires.

Monitor Scope is the answer to "something can interrupt my flow at any moment" — a popup, a disconnect, an unexpected dialog — without wrapping every node in a check.

Purpose

A zone drawn on the canvas. While the run is executing any node whose card lies fully inside that zone, a monitor periodically runs a separate detection flow. If that detection ends at a mapped exit, the run continues from a node you nominate.

When to use it

• An interruption can appear at any point during a phase — a popup, an ad, a disconnect warning.
• You need a safety net over a long sequence without adding checks between every step.
• Recovery should happen wherever the run currently is, not at a fixed checkpoint.

When not to use it

• For a check at one known point — a plain Find Image is simpler and cheaper.
• For anything that needs to act every single node — monitors run on an interval, not on every step.
• As a replacement for error handling. Wire your Failure ports too.

Requirements

• A detection-only flow to run as the watch.
• A zone with a real extent — a zone with no size covers nothing and never arms.
• The monitor must be enabled; it is born disabled.

How it works

Two things follow from this design:

The zone node is never wired into the flow. It has no incoming or outgoing edges you draw. It carries geometry and configuration only.

Membership is geometric. Moving a node into or out of the zone is a drag — no node stores a parent id that could go stale. This is the same model as Groups.

Next Node per exit

The single mechanism connecting a monitor to your flow: a map from the detection flow's Stop node id to the main-flow node the run continues from when a check ends at that Stop.

Detection flow ends at	Main flow continues from
Stop: popup found	Dismiss the popup
Stop: disconnected	Reconnect routine
Stop: all clear	(unmapped — pure observation)

An exit mapped to nothing is pure observation: the monitor notices, logs, and the run carries on undisturbed.

Settings

Setting	Type	Range	Default	Notes
Monitor name	string	≤ 120 chars	—	Display label
Monitor enabled	boolean	—	false	Born disabled — you must switch it on
Watch flow	flow ref	≤ 120 chars	—	The detection-only flow to run each check
Zone width / height	number	0–10000	—	The rectangle's size. Its origin is the node's canvas position
Exit next nodes	map	≤ 64 entries	—	Detection Stop id → main-flow node id
Priority	integer	bounded	—	Which monitor wins when several are armed
Check interval	integer	bounded ms	—	How often to run the detection
Cooldown	integer	0–max ms	—	Minimum gap between triggers
Sustained	integer	0–max ms	—	How long the condition must hold before firing
Max triggers per activation	integer	0–1000	—	Cap per arming; 0 = unlimited

Check interval is the cost dial

Every check runs a whole detection flow. A 500 ms interval over a 60-second phase is 120 detection runs.

Set it to the slowest interval that still catches the interruption in time.

Sustained prevents false positives

sustainedMs requires the condition to hold for that long before the monitor fires. This filters transient states — a dialog mid-animation, a flicker during a transition.

Cooldown prevents storms

cooldownMs is the minimum gap between triggers, so a persistent condition does not fire the recovery path repeatedly.

Max triggers per activation

A hard cap per arming. Use it when a recovery that keeps firing means something is genuinely wrong and looping is worse than stopping.

Ports

The zone node is never wired. It exposes a pass-through success port so a hand-wired legacy payload still routes, and a fatal port — but in normal authoring you connect nothing to it.

Port	Notes
Success	Pass-through for legacy payloads; not used in normal authoring
Fatal	Configuration fault. Never followed

Basic example

Watch for a popup during a long phase:

• Monitor name: Popup watch
• Monitor enabled: on
• Watch flow: Detect Popup
• Check interval: 1000 ms
• Exit map: Stop: popup found → Dismiss popup
• Zone: drawn around the phase's nodes

Realistic example — a safety net over one phase

The four nodes inside the zone are watched. If the detection flow ends at its "popup found" Stop, the run jumps to Dismiss popup, which then re-enters the phase.

Nodes outside the zone are not watched — so the monitor costs nothing during the rest of the flow.

Advanced example — layered monitors

Two zones with different priorities and intervals:

Monitor	Watches for	Interval	Priority	Exit maps to
Disconnect watch	Connection-lost dialog	2000 ms	high	Reconnect routine
Popup watch	Routine popups	1000 ms	lower	Dismiss popup

When both are armed and both could fire, priority decides which wins. Put the more serious condition at the higher priority.

Best practices

• Enable the monitor. It is born disabled, and this is the most common reason a monitor "does nothing".
• Give the zone a real extent and check that the nodes you mean are fully inside it.
• Keep the watch flow tiny — detection only, no actions. It runs on every check.
• Use the longest interval that still catches the problem.
• Set sustainedMs for anything that could appear mid-animation.
• Set cooldownMs so a persistent condition does not fire repeatedly.
• Map the recovery node so it re-enters the phase, or the run resumes somewhere that no longer makes sense.
• Scope tightly. A monitor over the whole flow pays its cost for the whole flow.

Performance notes

• Cost = (nodes executed inside the zone) × (check frequency) × (cost of the watch flow). All three multiply.
• A watch flow with a full-screen Find Image is far more expensive than one with a small search region. Give the watch flow tight regions.
• Monitors are armed and disarmed by diffing the scope chain before every node, which is cheap. The expense is the checks themselves.
• Prefer several small zones over one flow-wide zone.

Memory notes

• The watch flow runs as a detection pass; it holds a frame per check.
• Monitor state (last trigger time, trigger counts, sustained timers) is per-run and small.
• The compile-time scope chain is stamped on the expanded in-memory graph, never in your saved flow.

Common mistakes

Mistake	What happens	Fix
Monitor left disabled	Nothing happens	Enable it
Zone has no size	Covers nothing, never arms	Give it a real extent
Node only partly inside the zone	Not covered — membership needs the card fully inside	Resize the zone
Watch flow performs actions	Actions fire on every check	Detection only
Interval far too short	Large slowdown	Lengthen it
No cooldown on a persistent condition	Recovery fires repeatedly	Set a cooldown
Recovery node does not re-enter the phase	Run resumes in the wrong place	Map it to a node that rejoins
Trying to wire the zone node	It is never wired	Leave it unconnected

Troubleshooting

The monitor never fires. Check, in order: is it enabled; does the zone have a real size; are the nodes fully inside it; is a watch flow selected; does the detection flow actually reach the mapped Stop.

It fires constantly. No cooldown, or no sustained threshold. Add both.

The flow slows dramatically inside the zone. The check interval is too short, or the watch flow is expensive. Lengthen the interval and give the watch flow a search region.

The run resumes somewhere strange. The exit mapping points at a node that does not rejoin the phase. Re-map it.

A mapped exit key does nothing. The Stop was removed from the detection flow. A stale key is harmless — it can never fire — and the Properties panel surfaces it as missing.

FAQ

Does the zone node execute? No. It carries geometry and configuration only, and is never wired into the flow.

How is membership decided? Geometrically — a node is covered when its card lies fully inside the zone rectangle.

Can several monitors be armed at once? Yes. Priority decides which one wins.

What can the watch flow do? Detection only. It should not send input.

How many exits can be mapped? Up to 64.

Related nodes

• Find Image — what a watch flow typically uses
• Check Region — cheap watch conditions
• Sub Flow — the recovery routine a monitor jumps into
• Stop — the detection flow's exits are Stop nodes

Related pages

• Flow Anatomy — geometric membership
• Retry and Failures — monitors complement, not replace, error wiring