caishen

State Machine Visual Designer

RISE Framework Specification

Spec ID: 63 Version: 1.2 Document ID: caishen-rise-smvd-v1.2 Last Updated: 2026-02-24 Source: Replaces defunct StateForge.com online designer; informed by StateBuilderGui patterns Implementation: smcraft/web/ — Next.js 16 + React 19 + Tailwind + Zustand | MCP Server: smcraft/mcp/

Creative Intent

What the Visual Designer Enables Users to Create:

Desired Outcomes:

  1. Users design complex state machines visually without writing definition files by hand
  2. The visual representation is always synchronized with the underlying definition model
  3. Structural errors are highlighted in real-time on the canvas with clickable error navigation
  4. Definitions can be imported, edited visually, and re-exported seamlessly
  5. The designer integrates with the code generator (Spec 62) for one-click code generation
  6. LLM agents can design state machines through conversation via MCP tools (smcraft-mcp)

MCP Server (Agent Interface)

The smcraft-mcp server enables LLM agents to design state machines conversationally:

Tools

| Tool | Purpose | |——|———| | create_state_machine | Create a new definition with namespace/name | | add_state | Add a state (with parent, kind, description) | | add_event | Add an event to the definition | | add_transition | Wire a transition between states | | remove_state | Remove a state from the tree | | validate_definition | Run all validation rules (V001–V008+) | | generate_code | Generate Python or TypeScript code | | get_definition | Export current definition as JSON | | load_definition | Import a definition from JSON | | list_states | Show state tree with transitions | | list_events | Show all defined events |

Resources

Prompts

Architecture Overview

┌────────────────────────────────────────────────────────────┐
│                  Visual Designer Application                │
│  Stack: Next.js 16 + React 19 + Tailwind + Zustand         │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │               Canvas Layer (SVG)                     │   │
│  │  ┌──────────┐ ┌──────────────┐ ┌───────────────┐   │   │
│  │  │  State   │ │  Transition  │ │  Draw Mode    │   │   │
│  │  │  Nodes   │ │  Arrows      │ │  (click→pick) │   │   │
│  │  └──────────┘ └──────────────┘ └───────────────┘   │   │
│  │  Context Menu │ Event Labels │ Error Indicators     │   │
│  └─────────────────────────────────────────────────────┘   │
│                           │                                 │
│  ┌────────────────────────▼────────────────────────────┐   │
│  │       Zustand Store (useDesignerStore)               │   │
│  │  StateMachineDefinition ←→ DesignerLayout            │   │
│  │  Undo/Redo (snapshot stack, MAX_UNDO=50)             │   │
│  │  Draw mode │ Selection │ Context menu │ Validation   │   │
│  └──────────────────────────────────────────────────────┘   │
│                           │                                 │
│  ┌────────────────────────▼────────────────────────────┐   │
│  │              Tabbed Right Sidebar                    │   │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐ │   │
│  │  │Properties│ │ Events   │ │ Settings │ │Errors  │ │   │
│  │  │+Actions  │ │  Table   │ │  Panel   │ │(click) │ │   │
│  │  └──────────┘ └──────────┘ └──────────┘ └────────┘ │   │
│  └──────────────────────────────────────────────────────┘   │
│                           │                                 │
│  ┌────────────────────────▼────────────────────────────┐   │
│  │              Toolbar                                 │   │
│  │  Undo/Redo │ Draw Mode │ Open/Save │ Validate/Gen   │   │
│  └──────────────────────────────────────────────────────┘   │
└────────────────────────────────────────────────────────────┘

Screens

MainDesigner

The primary workspace where users visually create and edit state machines.

Layout: Full-height flex layout with Toolbar (top), Canvas (center-left), tabbed right sidebar (Properties Events Settings Errors)

Behavior:

Components (Implemented)

Canvas (Canvas.tsx)

The main SVG workspace where states and transitions are rendered.

Behavior:

Styling:

PropertiesPanel (PropertiesPanel.tsx)

Behavior:

EventsPanel (EventsPanel.tsx)

Behavior:

SettingsPanel (SettingsPanel.tsx)

Behavior:

ValidationPanel (ValidationPanel.tsx)

Behavior:

Validation Rules (Implemented): | Rule | Description | |——|————-| | V001 | No events defined | | V002 | Duplicate state name | | V003 | Transition references unknown event / Duplicate event ID | | V004 | Transition targets unknown state | | V005 | Root must have at least one child state | | V007 | Final state must not have outgoing transitions | | V008 | Final state must not have child states |

Toolbar (Toolbar.tsx)

Behavior:

CodePreview (CodePreview.tsx)

Behavior:

Data

DesignerState (Zustand Store)

DesignerState:
  definition: StateMachineDefinition (Spec 60 model)
  layout: DesignerLayout
    positions: Record<string, StatePosition>
      StatePosition: { x, y, width, height }
  fileName: string | null
  dirty: boolean
  selection: { kind: "state"|"transition"|"event"|null, id: string|null }
  drawMode: "select" | "transition"
  drawSource: string | null
  contextMenu: { visible, x, y, target: {kind, id?} | null }
  undoStack: HistoryEntry[]  (max 50)
  redoStack: HistoryEntry[]
  errors: ValidationError[]
  showCodePreview: boolean
  generatedCode: string | null

Undo/Redo Pattern

Before every mutation, _pushHistory() deep-clones current {definition, layout} onto undoStack. Redo swaps current ↔ redoStack top. redoStack clears on any new mutation (standard behavior). Maximum 50 undo levels.

Store Operations

State Operations

Event Operations

Action Operations (onEntry/onExit)

Transition Operations

Creative Advancement Scenarios

Scenario: Visual Strategy Design

Desired Outcome: A trader designs a BDBO strategy state machine visually Current Reality: State machines are defined by editing raw JSON files Natural Progression:

  1. Trader opens the designer and clicks “＋State” in toolbar, names it “Active”
  2. Adds more states: WaitingBreakout, WaitingSignal, WaitingEntry
  3. Adds Final states: Completed, Failed (set Kind=final in Properties)
  4. Opens Events tab, types event IDs: PriceBreakout, SignalFound, OrderFilled
  5. Expands each event to add parameters (e.g., price: float, volume: int)
  6. Clicks “↗ Draw” in toolbar to enter draw mode
  7. Clicks WaitingBreakout → clicks WaitingSignal → picks PriceBreakout event from popup
  8. Selects the transition, adds condition in Properties: strategy.CanRetry()
  9. Opens Settings tab, sets namespace and target language
  10. Selects WaitingSignal state, adds onEntry action: timer start code
  11. Errors tab shows green — all rules pass
  12. Clicks “⚡ Generate” → sees JSON definition in code preview Resolution: Complete, visual-to-code workflow without manually writing definition files

Scenario: Import and Refine Existing Definition

Desired Outcome: Load an existing JSON definition and refine it visually Current Reality: Editing complex nested JSON is error-prone Natural Progression:

  1. User clicks 📂 Open → selects existing bdbo_strategy.smdf.json
  2. Designer parses definition and auto-layouts states on canvas
  3. User visually identifies a missing transition — enters draw mode
  4. Clicks source state → target state → picks event from popup
  5. Properties panel shows the new transition; user adds condition guard
  6. User clicks an event in the Events table, adds a new parameter
  7. Saves the updated definition (💾) Resolution: Visual editing of existing definitions with immediate re-export

Scenario: LLM Agent Designs State Machine via MCP

Desired Outcome: An AI agent creates a state machine through conversation Natural Progression:

  1. Agent calls create_state_machine with namespace and name
  2. Agent calls add_event for each domain event
  3. Agent calls add_state for each state in the workflow
  4. Agent calls add_transition to wire events to state transitions
  5. Agent calls validate_definition to check for structural errors
  6. Agent calls generate_code with target language Resolution: Conversational state machine design without visual tool

Technology Stack (Implemented)

Component Technology
Framework Next.js 16 + React 19 + TypeScript
Canvas SVG-based with React components
State Management Zustand (single store with undo/redo)
Layout Auto-layout with hierarchical child positioning
Styling Tailwind CSS, dark theme
File I/O Browser FileReader API + Blob download
Export Direct JSON serialization from model
MCP Server @modelcontextprotocol/sdk + StdioServerTransport

Dependencies

File Format: Designer Project

The designer saves definitions as .smdf.json files:

{
  "stateMachine": {
    "settings": { "namespace": "...", "name": "...", "asynchronous": false },
    "events": [{ "name": "Internal", "events": [...] }],
    "state": { "name": "Root", "states": [...] }
  }
}

Visual layout data (positions) is managed in-memory by the Zustand store and regenerated via auto-layout on file load.