Skip to content

Visual Editors Runtime Unification

Related: Companion ST, Visual Companion Model

Status: implementation specification for Ladder, Statechart, Blockly, and visual-SFC runtime/debug execution in VS Code.

1. Goal

All visual editors MUST execute through the same Structured Text runtime/debug pipeline as .st files. Editor-specific simulation/runtime engines MUST NOT be the primary execution path for runtime controls.

2. Scope

Applies to:

  • *.ladder.json
  • *.blockly.json
  • *.statechart.json
  • visual SFC documents/materialized companion ST generated by the editor

Applies to runtime actions:

  • mode selection (local / external)
  • start / stop
  • runtime I/O write / force / release
  • companion-ST generation and wrapper generation

3. Runtime Entry Contract

For each visual source file <base>.<kind suffix>, the language server generates (trust-lsp.visualCompanion, crate trust-visual) and the extension writes beside it, on save, on Sync Structured Text and on the editor's Generate:

  1. Companion function-block file: sibling <base>.st, a banner naming the source and one FUNCTION_BLOCK FB_<base>_<KIND>; for an SFC with actions, also the TYPE FB_<base>_SFC_ACTION of its action flags (sfc-profile.md).
  2. Launch wrapper: sibling <base>.visual.runtime.st with:
  3. PROGRAM PRG_<base>_VISUAL that calls the instance fb_<base> of the generated companion FB
  4. CONFIGURATION CFG_<base>_VISUAL whose VAR_GLOBAL declares that instance and the program's globals (a direct address the companion names as ld_io_<address> AT <address>, typed by its size per 03-variables.md §5), and RESOURCE + TASK TASK_<base>_VISUAL(INTERVAL := T#20ms, PRIORITY := 1) + PROGRAM PLC_PRG_<base> WITH TASK_<base>_VISUAL : PRG_<base>_VISUAL

<base> in identifiers is the base name made an IEC identifier (other characters become _). The wrapper file is the launch entry for local debug sessions.

3.1 Editor-to-ST Mapping

Each visual editor owns its own authoring model, but execution converges onto generated Structured Text:

Editor Source model Generated execution path
Ladder rung/network JSON companion FB + wrapper PROGRAM
Statechart state/transition JSON companion FB + wrapper PROGRAM
Blockly block graph JSON companion FB + wrapper PROGRAM
SFC visual step/transition model generated ST companion/runtime wrapper

The runtime/debug pipeline therefore validates one execution contract even when authoring happens in different editors.

3.2 Statechart

The companion of a statechart runs one scan of the chart per call: it starts in the initial state once, runs the transitions of the active state in file order, the first that fires taking the exit actions of its state, its own actions and the entry actions of its target, and then answers the active state (STATE_INDEX, STATE_NAME). Each event of an untimed transition is a BOOL input EV_<EVENT>.

A transition with after (milliseconds, rounded) fires when its state has been active that long. A state's TON starts in the scan that enters the state: the transition that enters a state calls its timers with IN TRUE once the state has changed, and the initial state's timers run with IN TRUE in the first scan. Each timer is then called once per scan with IN TRUE while its state is active and FALSE otherwise, so it reads ET T#0s in the scan that entered its state and adds the task interval in each later scan (specification 08 §5); with a 20 ms task, after: 100 fires five scans after the scan that entered the state, 100 ms later. A transition that fires resets the timers of its state with the exit actions, so a self-transition starts them again. The state's transitions are checked after its timers run, in the same scan.

4. Command Routing Contract

The visual editors have no runtime actions of their own (§5). A visual program is started, attached, stopped, written and forced like any Structured Text program, through the shared runtime commands (trust-lsp.debug.start, trust-lsp.debug.attach, trust-lsp.debug.stop, trust-lsp.debug.io.write, trust-lsp.debug.io.force, trust-lsp.debug.io.release) from the truST sidebar and Live Values; its runtime entry is a CONFIGURATION like any other Structured Text configuration of the project.

5. UI Behavior Contract

The runtime entry and command-routing contract in Sections 1 through 4 remains authoritative. Runtime-control placement is now owned by 25-vscode-product-contract.md and the reviewed product decision dated 2026-07-26.

Visual editors MUST NOT embed duplicate runtime, I/O, runtime-settings, or compile-diagnostics panes. They use the truST sidebar for runtime lifecycle and Live Values for runtime values. This supersedes the earlier requirement for right-pane runtime controls without changing the shared Structured Text generation, launch, attach, or debug-command route.

6. Current Constraints

  • Attach mode currently resolves endpoint/auth from existing attach configuration flow (runtime.toml/debug attach path).
  • Full end-to-end parity evidence requires manual visual verification in Extension Development Host for Ladder, Statechart, Blockly, and SFC editors.
  • Editor-specific authoring schemas are still separate; their rules (format checks, edits, companion generation) are in trust-visual (25-vscode-product-contract.md §11.4).

7. Implementation Anchors

  • crates/trust-visual/src/companion.rs (companion and runtime entry)
  • crates/trust-visual/src/{ladder,blockly,statechart,sfc} (the generators)
  • crates/trust-lsp/src/handlers/commands/visual.rs (the trust-lsp.visual* commands)
  • editors/vscode/src/visual/companionSt.ts (writes the files)
  • editors/vscode/src/debug.ts
  • editors/vscode/src/ioPanel.ts