Expands README to describe the three-tab UX, the source-of-
truth model (YAML + sidecar layout), the FlowRunDriver
contract, the folder layout, and how to swap the editor.
Version 0.2.0 -> 0.2.1 — picks up the live step status,
the empty-graph CTA, and the fit-to-screen button added
since the initial 0.2.0 commit.
Signed-off-by: flemming-it <sf@flemming.it>
Two polishing tweaks on the graph tab:
- When the active flow has no steps, the canvas would have
rendered as a near-empty grid (just inputs / outputs
sidebars). Overlay a centred call-to-action with the
graph icon, the "No steps yet" / "Noch keine Schritte"
heading, a one-liner explainer, and a primary Add Step
button that opens the capability picker directly.
- Auto-fit zoom on first open of each flow + a floating
"Fit to screen" button (bottom-right corner of the
canvas viewport). The auto-fit re-runs only when the
flow name changes, so the operator's manual pan / zoom
on the current flow is preserved. The fit math expands
the bounding box to include inputs + outputs pseudo-
nodes too, so wide flows zoom out enough to show every
port at once.
Fit math:
- Walk every step's stored position + height; merge with
the inputs sidebar's known position.
- Compute scale that makes the bounding box fit the
viewport with 80 px padding on each side.
- Clamp to [0.4, 2.0] — InteractiveViewer's own bounds.
- Translate so the box centres in the viewport.
`flutter analyze` clean, all 11 tests still pass.
Signed-off-by: flemming-it <sf@flemming.it>
Step run events were previously visible only on the run tab.
Operators who triggered a run there and then switched to
the graph tab saw a static graph — the canvas had no idea
something was executing.
Wire the run events through the FlowEditorController so all
three tabs share the same status snapshot:
- New StepRunStatus enum on the controller
(idle / running / done / failed / awaiting).
- controller.stepStatuses exposes the live map.
- controller.updateStepStatus is called from the run tab's
event handler — one source of truth, both views read it.
- FlowCanvas drops its own stepStatuses parameter and
pulls from the controller instead, so the canvas now
shows the running pulse + done check + error cross + pause
icon in each step's header live, in lockstep with the
step list on the run tab.
When a fresh run starts (controller.running = true) the
status map is cleared so stale events from a previous run
don't paint the new one.
Signed-off-by: flemming-it <sf@flemming.it>
Four behaviour tests guarding the controller's contract with
the rest of the editor:
- openFlow seeds the graph + clears the dirty flag against
the freshly-captured baseline.
- graph edits re-emit YAML into the shared CodeController
so the text tab stays in lockstep.
- graph edits mark the buffer dirty against the baseline;
markSaved snaps it back to clean.
- selectStep is idempotent: re-selecting the same step
doesn't notify listeners (cheap rebuild guard for the
properties panel).
11/11 tests pass.
Signed-off-by: flemming-it <sf@flemming.it>
Full rewrite of the editor surface, layered on top of the
FlowGraph foundation. One in-memory flow drives three tabs
that the operator can flip between freely:
- Graph: a drag-and-drop canvas. Nodes are step cards with
port dots on their left (one per `with:` field) and a
combined output port on the right. Pinned inputs and
outputs pseudo-nodes sit at the left and right edges so
every flow has a visually obvious source and sink. Pan +
zoom via InteractiveViewer; drag a node by its body to
reposition it (positions persisted to a sidecar JSON file
under ~/.fai/data/flows/.layout/<name>.json — kept OUT of
the YAML so `fai run` stays byte-stable).
- Text: the existing YAML CodeField with expands:true so
line 1 anchors at the top edge. YAML-aware syntax
highlighting picks up the theme's primary / secondary /
tertiary palette for keys / strings / numbers.
- Run: an inputs form (text fields + file-pick), a Start
button that calls the host's FlowRunDriver, a live step
list driven by the driver's event stream (matches the
`fai run` CLI rendering — ◻ pending, · running, ✔ done +
duration, ✗ failed, ⏸ awaiting approval), and the typed
outputs once the run resolves.
Source of truth = the YAML text. Graph edits emit fresh YAML
into the shared CodeController; text edits re-parse the
graph on a 350 ms debounce. Layout sidecar persists drag
positions only.
New public API (lib/fai_studio_flow_editor.dart):
FlowEditorPage(
initialFlowName: ...,
locale: ...,
runDriver: FlowRunDriver?, // NEW — host bridge
availableCapabilities: List<String>, // NEW — for the
// capability picker
// dialog when adding
// a step
)
The host (Studio) implements FlowRunDriver to bridge the
hub's gRPC SDK into the editor's event vocabulary. The
StepStarted/Completed/Failed/AwaitingApproval events are
shared verbatim with the CLI's run_progress renderer so
both surfaces speak the same visual language.
Files in this commit:
- lib/src/editor_controller.dart — shared state +
debounced reparse loop
- lib/src/run_driver.dart — host bridge
interface + event types
- lib/src/widgets/flow_canvas.dart — pan / zoom / drag /
port-to-port connection drawing
- lib/src/widgets/flow_node.dart — node card primitive
(module / approval / inputs / outputs variants)
- lib/src/widgets/edge_painter.dart — single CustomPainter
for every edge + draft drag line, cubic bezier with
arrow-head caps
- lib/src/widgets/properties_panel.dart — right-side editor
when a step is selected (rename id, change capability, add
/ remove / rename with-fields, delete step)
- lib/src/widgets/capability_picker.dart — searchable list
dialog used by Add-step
- lib/src/widgets/run_tab.dart — inputs form +
live step progress + outputs renderer
- lib/src/flow_editor_page.dart — host scaffolding,
toolbar, file list, three-tab body, keyboard shortcuts
- lib/src/l10n.dart — EN + DE strings for
every new label
- lib/fai_studio_flow_editor.dart — exports the new
public types (FlowRunDriver, FlowRunEvent variants,
FlowOutputValue variants)
flutter analyze: 0 issues. flutter test: 7/7 green.
Signed-off-by: flemming-it <sf@flemming.it>
First piece of the v0.2.0 rewrite. The graph view, text view,
and run view will all share a single source of truth: the
YAML text. This commit introduces the parsing layer + the
sidecar that keeps layout metadata OUT of the YAML.
FlowGraph (lib/src/model/flow_graph.dart):
- Parses + emits the F-Delta-I flow YAML shape (inputs +
steps + outputs + leading comment block).
- Recognises both inputs shorthand (`name: text`) and the
expanded form (`name: { type: text, default: ..., hint: ... }`).
- Detects edges by scanning step.with + outputs for
$source.field references; understands both the short
$x.y form (canonical) and the long ${{ x.y }} form (legacy).
- Flags system.approval@ steps via FlowStep.isApproval so
the graph can paint them with the human-gate styling.
- Immutable update helpers (withStepUpdated, withStepAdded,
withStepRemoved) used by the property panel + add-step
button.
- tryParse returns null on YAML syntax errors so the text
tab can keep the last valid graph while the operator
types.
LayoutStore + FlowLayout (lib/src/model/layout_store.dart):
- Per-flow JSON sidecar at
~/.fai/data/flows/.layout/<name>.json. Atomic write via
tmp + rename so a crash mid-save leaves the previous
copy intact.
- The YAML stays byte-identical to what `fai run` consumes
— positions never bleed into the flow file.
AutoLayout (lib/src/model/auto_layout.dart):
- Deterministic topological column layout for flows that
have never been opened in the graph view before.
- Steps with no $step refs sit in column 0; steps whose
refs all point at column-0 steps sit in column 1; etc.
- Cycles + dangling refs collapse to column 0 so nothing
is ever invisible.
Tests (test/flow_graph_test.dart): 7 cases cover canonical
parsing, edge detection across both ref forms, approval-step
flagging, leading-comment round-trip, structural round-trip,
parser robustness on broken YAML, immutability invariant.
All pass.
Version 0.1.4 -> 0.2.0 (minor bump — significant new module
graph; public FlowEditorPage constructor API unchanged).
Signed-off-by: flemming-it <sf@flemming.it>
Two changes Stefan flagged on 0.1.3:
(1) Short files were still vertically centered. The previous
fix (CrossAxisAlignment.stretch on the Row) only stretched
the SingleChildScrollView viewport — the CodeField inside
still had its natural content-sized height and sat centered
in the larger viewport. Drop the SCV wrapper entirely and
set `expands: true` (with `minLines: null` + `maxLines:
null`, the underlying TextField's required combination) on
the CodeField. The widget now fills its parent's bounded
height, the line-number gutter runs the full editor height,
and line 1 sits at the literal top edge. Standard IDE
behaviour.
(2) The round outlined Refresh button sandwiched between
New (filled-tonal) and Save (filled-tonal) in the editor
toolbar was a visual-style outlier — Stefan called it
"dazwischen, sieht falsch aus". Refresh is also
semantically scoped to the file list, not the open
editor, so move it out of the editor toolbar entirely and
into a small FLOWS header bar at the top of the file-list
panel. The editor toolbar now reads:
[Back] file.yaml ● [Spacer] [New] [Save] [Run]
— four filled-tonal/filled buttons, no style outliers.
The file-list panel reads:
┌───────────────────────┐
│ FLOWS ⟲ │
├───────────────────────┤
│ flow-a │
│ flow-b │
└───────────────────────┘
Adds `listHeader` to FlowEditorStrings (de + en both
"FLOWS" — same word, all-caps).
Version 0.1.3 -> 0.1.4.
Signed-off-by: flemming-it <sf@flemming.it>
Row was using CrossAxisAlignment.center by default, so a
short YAML file appeared visually centered in the editor
viewport — uncomfortable in any IDE-style surface where
content is expected to start at the top edge regardless of
how much of the viewport it fills.
Set CrossAxisAlignment.stretch on the outer Row so the
SingleChildScrollView fills the full vertical extent. The
SCV's default scroll origin is the top, so once the
viewport is taller than the content the file renders at
the top with empty space below.
Version 0.1.2 -> 0.1.3.
Signed-off-by: flemming-it <sf@flemming.it>
Stefan reported that opening a flow (hello) sometimes showed
content from a different flow (extract-with-approval). Cause:
flutter_code_editor's CodeController distinguishes between
`text` (the visible buffer, post-fold) and `fullText` (the
underlying source). Setting `_code.text = newFile` only
updates the visible buffer; the underlying `_code` data
structure retains the previous file's source, so subsequent
folding/scrolling can surface its content.
Switch all three load sites + the save site to the canonical
setter:
Before _code.text = text (visible buffer only)
After _code.fullText = text (replaces underlying source)
Save also moves to writing `_code.fullText` so any text the
operator collapsed behind a fold survives the round-trip.
Verified against flutter_code_editor 0.3.5 source — the
fullText setter calls `_updateCodeIfChanged` then re-emits
`TextEditingValue(text: _code.visibleText)`, which is the
documented "fully reset the editor" path.
Bump version 0.1.1 → 0.1.2. Studio's pubspec already pins
`ref: main` so the next `flutter pub upgrade` picks it up.
Signed-off-by: flemming-it <sf@flemming.it>
Stefan reported false-positive "Discard unsaved changes?"
dialogs when clicking around in the file list. Cause: the
naive `_code.text == _loadedText` check fired stale even
right after _code.text = text, because CodeController
silently rewrites the visible text during the assignment
(trailing-newline normalisation, fold marker insertion on
some YAML constructs, …) so _code.text deviated from the
just-stored _loadedText immediately.
Fix:
* Drop `_loadedText` field, replace with `_baseline`.
* Set `_code.text = ...` first (outside setState), then
capture `_baseline = _code.fullText` inside setState.
fullText is the canonical post-processed value, not the
visible-after-folding text — comparing fullText against
fullText eliminates the spurious diff.
* _dirty getter now compares `_code.fullText != _baseline`.
Applied to all four load / save / new-flow sites.
Bump version 0.1.0 → 0.1.1. Studio's pubspec already pins
`ref: main` so the next `flutter pub get` picks the fix up.
Signed-off-by: flemming-it <sf@flemming.it>
Extracted from fai/studio's lib/pages/flow_editor.dart so the
editor can be swapped out independently of the host.
Public surface kept minimal — a single FlowEditorPage widget
with three named parameters (initialFlowName, locale, onRun).
The package brings its own design tokens, empty/error
widgets, l10n table; no host-internal types leak through.
Studio depends on this repo via pubspec.yaml git reference.
Forks point Studio at a different URL and rebuild.
See README.md for the swap recipe.
Signed-off-by: F∆I Platform <platform@flemming.ai>
