Flow State

Flow State is a passive observer for the Flow Controller LOP. It watches the Flow Controller’s internal state in real time and logs every event — step transitions, context mutations, status changes, wait states, and flow completion — into a capped history list. That history can then be exported as JSON, a Mermaid diagram, or a GraphViz DOT file for debugging and visualization.

Overview

Flow State connects to a Flow Controller automatically via the internal LOPflow reference — no wired input is needed. An internal script CHOP polls the Flow Controller whenever its state changes and feeds events to the extension, which appends them to the history log. Each event carries a relative timestamp (seconds since flow start), an action type, a source label, and any relevant details such as context snapshots or step metadata.

The history is kept in memory and, optionally, mirrored to an internal table DAT for direct inspection inside TouchDesigner. When a flow run completes, the full sequence of steps and context values is available for export.

Key Features

• Reactive observation of all Flow Controller state — starts, step transitions, context sets, wait/continue, and finish events
• Capped history list prevents memory growth over long sessions
• Context snapshots captured at each step entry for full state reconstruction
• Export to JSON, Mermaid flowchart, and GraphViz DOT format
• Internal CHOP outputs provide live numeric signals for the current step index, running state, and event count
• Optional internal history_table DAT for direct visual inspection

Input / Output

Inputs

None. Flow State locates the Flow Controller automatically through the internal iop.LOPflow reference. No wired connection is required.

Outputs

Flow State has two outputs. The first carries the internal observer CHOP channels:

Channel	Description
history_count	Total number of events in the current history
current_step	Index of the step currently active in the Flow Controller
max_steps	Maximum steps configured on the Flow Controller
is_running	1 while the flow status is running, 0 otherwise
is_waiting	1 while the flow is paused waiting for a Continue signal
context_keys	Number of keys currently in the flow context

These channels update reactively as the Flow Controller runs and are suitable for driving UI feedback, triggering downstream logic, or monitoring flow progress in a CHOP network.

The second output carries the exported data DATs (history table, JSON export, Mermaid export) when they exist.

Setup Page

Max History sets the maximum number of events the operator will retain. Once the limit is reached, the oldest events are dropped to make room for new ones. The default is 1000. For long-running flows or debugging sessions with many context mutations, increase this value to preserve the full run.

Expose as DAT controls whether the history is mirrored to an internal history_table DAT in real time. Enable this when you want to inspect events visually inside the operator. Note that for performance reasons the DAT only shows the most recent 100 events, even when the full history holds more.

Status Page

The Status page shows a live read-only summary and provides export controls.

History Count shows how many events are currently stored. Last Event shows the action type and relative timestamp of the most recent event.

Flow Status reflects the current status string from the Flow Controller (e.g. idle, running, finished).

Clear History resets the history list and clears the internal history_table DAT. Use this before starting a new test run if you want a clean log.

Export JSON writes the full history to an internal export_json text DAT inside the operator. Open the operator and look for export_json to copy or forward the data.

Export Mermaid generates a Mermaid flowchart TD diagram from the step transition history and writes it to an internal export_mermaid text DAT. The diagram includes context changes as a subgraph when they exist. Copy the text and paste it into any Mermaid renderer (e.g. mermaid.live) to visualize the flow path.

Usage Examples

Monitoring a Live Flow Run

1. Place a Flow State operator in the same network as your Flow Controller.
2. Confirm that both operators are in the same LOPs environment so the internal iop.LOPflow reference resolves.
3. On the Setup page, enable Expose as DAT so events appear in the internal table immediately.
4. Run the Flow Controller. The History Count on the Status page increments as events arrive, and Last Event updates in real time.
5. When the flow finishes, dive into the operator and open the history_table DAT to review the full event sequence.

Exporting a Flowchart After a Run

1. Run the flow to completion.
2. On the Status page, pulse Export Mermaid.
3. Dive into the Flow State operator and open the export_mermaid text DAT.
4. Copy the diagram text and paste it into mermaid.live to render the flowchart.

Exporting the Full History as JSON

1. After a run, pulse Export JSON on the Status page.
2. Dive into the operator and open the export_json text DAT.
3. The text DAT contains the complete history array in JSON format — one object per event — with timestamps, action types, step names, context snapshots, and step metadata.

Clearing History Before a Test Run

1. On the Status page, pulse Clear History.
2. History Count returns to 0 and the internal history_table DAT is wiped.
3. Start the Flow Controller. The new run’s events are captured from scratch.

Event Types

Each history event has an action field. The recorded action types are:

Action	When it fires
start	Flow Controller begins a new run
enter	Flow enters a new step (includes full context snapshot and step metadata)
exit	Flow leaves the previous step
set	A context value is changed via the Flow Controller’s Set() method
status	Flow status string changes (records old and new values)
wait	Flow pauses waiting for a Continue signal
continue	Flow resumes after a wait
update	An update event fires on the current step
finish	Flow run completes (records the result and final context snapshot)

Best Practices

• Keep Expose as DAT disabled during normal production use. The internal DAT rebuild on every event has overhead at high event rates.
• Increase Max History when debugging flows that loop or have many context mutations. The default of 1000 may not capture the full picture for complex runs.
• Pulse Clear History between test runs to keep the log readable.
• Use Export Mermaid as a quick sanity check that branching logic followed the expected path.
• The history_count and is_running CHOP output channels are useful for driving visual indicators in your TD network — connect them to a Reorder CHOP or a Script DAT that updates a UI element.

Troubleshooting

History Count stays at 0 / no events appear Flow State locates the Flow Controller through iop.LOPflow. If the Flow Controller is not present in the expected location within the LOPs hierarchy, the observer silently does nothing. Verify that a Flow Controller is active in the same LOPs environment.

History is truncated mid-run The Max History cap drops the oldest events when the limit is reached. Increase Max History on the Setup page before the run.

history_table DAT only shows 100 rows even with more events The DAT is intentionally capped at the most recent 100 events for performance. The full history is still held in memory. Use Export JSON to access the complete event list.

Duplicate finish events do not appear Flow State guards against duplicate finish events because the internal script CHOP may cook multiple times when the Flow Controller transitions to a finished state. Only the first finish event per run is recorded.

Parameters

Setup

Max History (Maxhistory) op('flow_state').par.Maxhistory Int

Maximum number of history events to keep

Default:

0

Range:

100 to 10000

Slider Range:

0 to 1

Expose as DAT (Exposeasdat) op('flow_state').par.Exposeasdat Toggle

Write history to internal tableDAT for visibility

Default:

False

Status

History Count (Historycount) op('flow_state').par.Historycount Int

Number of events in history

Default:

0

Range:

0 to 1

Slider Range:

0 to 1

Last Event (Lastevent) op('flow_state').par.Lastevent Str

Most recent event

Default:

"" (Empty String)

Clear History (Clear) op('flow_state').par.Clear Pulse

Clear all history events

Default:

False

Export JSON (Export) op('flow_state').par.Export Pulse

Export history to JSON file

Default:

False

Flow Status (Flowstatus) op('flow_state').par.Flowstatus Str

Current flow status

Default:

"" (Empty String)

Export Mermaid (Exportmermaid) op('flow_state').par.Exportmermaid Pulse

Export flowchart as Mermaid diagram

Default:

False

Changelog

v0.1.0

First version of FlowState observer for FlowController.

Features

• History Tracking: Captures all FlowController events (start, step enter/exit, context changes, updates, waits, finish)
• Context Snapshots: Records full context state at key moments for state reconstruction
• Reactive Observation: Uses ScriptCHOP watching FC dependencies for automatic event capture
• DAT Persistence: History table survives extension reinit (DAT is source of truth)
• Flowchart Export:
• Mermaid format with step shapes based on type (wait=parallelogram, auto=rounded)
• DOT (GraphViz) format with visit counts and context labels
• JSON graph structure for custom visualization
• ASCII timeline for quick debugging
• Query API: Filter history by step name, action type, or timestamp
• Deduplication: Guards against duplicate finish events from multiple scriptCHOP cooks

Integration

• Works with FlowController's new Context system (Get()/Set() with source tracking)
• Observes OnContextChange dependency for context mutation logging
• Compatible with FlowTrigger source tracking for full audit trail

Related Operators

• Flow Controller
• Flow Action