Skip to main content

The Unified DSL Editor Workspace

Botgami features a powerful, high-fidelity developer workspace that pairs a full-featured code editor with an interactive visual preview canvas. At the center of this experience is the Unified DSL Editor—an in-browser code workspace optimized for writing, formatting, and analyzing .botgami bot scripts.

This page covers the architecture of the DSL editor, its integrated developer features, and how it synchronizes in real time with the visual canvas.

Editor Architecture​

The Botgami workspace does not rely on a sluggish, server-side language server process. Instead, the entire IDE suite runs completely in-browser inside a dedicated web worker for maximum speed and instant feedback:

  • CodeMirror 6: A modular, performant text editor engine providing custom themes (like OLED-first dark mode), linting panels, and keymap bindings.
  • Langium LSP Worker: A dedicated web worker running a full language server protocol. Because the LSP is loaded in the browser as a client-side thread, syntax checking, autocomplete completions, and hovers are computed with zero network round-trips and zero lag.
  • Server Compilation: When you save (debounced to 150ms), the editor automatically invokes the compiler, lower projections, and runs full static simulations on the backend.

Workspace Features​

The Code mode is packed with classic developer utilities:

1. In-Context Auto-Completions​

The editor matches active tokens against Step contracts (gen/contracts.bundle.json) to suggest commands and signatures dynamically:

  • Autocompletes statement methods such as send.text, send.photo, and ask.number.
  • Suggests available variables in the local scope, including read-only context variables (like user.first_name and callback.data).
  • Lists signatures for all 45+ built-in expressions (e.g. compact, len, sortBy).

2. High-Fidelity Diagnostics​

If your script violates syntax, references an undeclared variable, or violates type safety, a red line highlights the specific line and range.

  • LSP Diagnostics: Computed locally by the Langium worker. Shows grammar errors and syntax problems.
  • Compiler Projections: When saved, server-side compile checks (typegraph audits, edge pins) are mapped back to source ranges via the DSL Source Map.

3. Smart Hover Tips​

Hovering over any built-in statement, variable scope, or function presents descriptive markdown tooltips, parameters, expected return types, and example code snippets.

Bi-Directional Canvas Sync​

The most unique feature of the Botgami workspace is its bi-directional layout synchronization:

1. Code-to-Canvas Sync​

  1. You write code in the DSL editor (e.g. adding a new send.text line) and save.
  2. The client compiles the DSL to FlowSpec v2 JSON via compileBotgamiDsl and dispatches it over the WebSocket using a replace_spec patch.
  3. The server runs the 14-stage compilation pipeline, generates a fresh ProjectionBundle (detailing nodes, ports, and layout positions), and returns it.
  4. React Flow renders the new nodes and wires instantly, maintaining a clean visual representation of your code.

2. Canvas-to-Code Sync​

  1. You interact with the Visual Canvas (e.g. dragging a node to reorganize the layout or adding a connection wire).
  2. The canvas dispatches an atomic patch (e.g. move_layout or connect) via spec/preview_patch over the WebSocket.
  3. The server applies the patch, compiles the graph, and returns the modified FlowSpec JSON.
  4. The client's Langium printer (printFlowSpec) takes the new spec, converts it back into formatted .botgami text, and updates your code editor buffer—all while preserving your comments and formatting!

Isolated Code Focus (Focus Scopes)​

When managing massive bots with hundreds of flows, a single text file can become overwhelming. To resolve this, the workspace supports Focus Scopes:

  • Click any node on the Visual Canvas or select a specific flow in the trigger outline, and the workspace can isolate that specific flow in the code panel.
  • CodeMirror collapses all surrounding flows and blocks, constraining your cursor and line indexes from 1 to the size of the focused block.
  • You edit in clean isolation, while the background Langium parser continues to compile the absolute, full-sized document buffer to ensure all variables and scopes remain completely validated.

Next Steps​