Makepad 2.0 Splash Scripting Language

State Management

State is managed via the mod.state object and reactive on_render callbacks:

// Define state
let state = { counter: 0 }
mod.state = state

// Reactive rendering -- re-runs when .render() is called
main_view := View{
    on_render: ||{
        Label{ text: "Count: " + state.counter }
    }
}

Event Handling

Events are handled both inline in Splash and from Rust:

// Inline event handlers in Splash
add_button := Button{
    text: "Add"
    on_click: ||{
        add_todo(ui.todo_input.text(), "")
        ui.todo_input.set_text("")
    }
}

// TextInput return key
todo_input := TextInput{
    on_return: || ui.add_button.on_click()
}

// Startup event
on_startup: ||{
    ui.main_view.render()
}

From Rust, use script_eval! to execute Splash code:

impl MatchEvent for App {
    fn handle_actions(&mut self, cx: &mut Cx, actions: &Actions) {
        if self.ui.button(cx, ids!(increment_button)).clicked(actions) {
            script_eval!(cx, {
                mod.state.counter += 1
                ui.main_view.render()
            });
        }
    }
}

Functions

fn tag_color(tag) {
    if tag == "dev" theme.color_highlight
    else if tag == "design" theme.color_selection_focus
    else theme.color_highlight
}

fn add_todo(text, tag) {
    todos.push({text: text, tag: tag, done: false})
    ui.todo_list.render()
}

Control Flow

// If/else
if todos.len() == 0
    EmptyState{}
else for i, todo in todos {
    TodoItem{ label.text: todo.text }
}

// For loops
for i, item in array {
    Label{ text: item.name }
}

// While
while condition { ... }

HTTP Requests

let req = net.HttpRequest{
    url: "https://api.example.com/data"
    method: net.HttpMethod.GET
    headers: {"User-Agent": "MakepadApp/1.0"}
}
net.http_request(req) do net.HttpEvents{
    on_response: |res| {
        let text = res.body.to_string()
        let json = res.body.parse_json()
    }
    on_error: |e| { /* handle error */ }
}

Streaming responses use is_streaming: true with on_stream and on_complete callbacks.

HTML Parsing

let doc = html_string.parse_html()
doc.query("p")              // all <p> elements
doc.query("#main")           // by id
doc.query("p.bold")          // by class
doc.query("div > p")         // direct children
doc.query("p[0]").text       // text content
doc.query("a@href")          // attribute value

Streaming Evaluation

Splash's parser supports checkpoint-based incremental parsing, designed for AI/LLM streaming code generation:

// Rust API for streaming evaluation
vm.eval_with_append_source(script_mod, &code, NIL.into())

This enables real-time UI updates as code is generated token-by-token, without requiring a complete script before evaluation.

Hot Reload & Script Mod Tracking

Splash scripts support hot reload via the --hot flag. The VM tracks each script_mod! block with a unique ScriptModKey (file, line, column):

// Internal: ScriptModKey uniquely identifies a script_mod! block
ScriptModKey { file: "src/app.rs", line: 5, col: 1 }

// Runtime substitution via overrides
ScriptCode::script_mod_overrides  // HashMap of ScriptModKey -> updated source

How hot reload works:

1. File watcher (makepad_live_reload_core) detects source file changes
2. script_mod! blocks are extracted from Rust source (handles raw strings, comments, char literals)
3. Rust placeholder counts (#(...)) are tracked -- adding/removing placeholders requires full rebuild
4. Validated script mods are applied via script_mod_overrides
5. IP-to-location mapping provides source maps for error reporting (fallback to nearest token for synthetic opcodes)

ScriptSource variants:

• ScriptSource::Mod -- Standard module evaluation (startup)
• ScriptSource::Streaming -- Incremental streaming evaluation (AI/LLM)

Critical Layout Rules

1. Always set height: Fit on containers -- default height: Fill causes invisible UI (0px height)
2. Use width: Fill on the root container -- never fixed pixel width at the top level
3. Set new_batch: true on any View with show_bg: true that contains text children
4. Use := for named children in templates -- without it, text overrides fail silently
5. draw_bg.border_radius takes a float, not an Inset -- draw_bg.border_radius: 16.0
6. Use styled Views (RoundedView, SolidView) instead of raw View{show_bg: true}

Widget Reference

Core containers: View, SolidView, RoundedView, RectView, RoundedShadowView, CircleView, GradientXView, GradientYView, ScrollXYView, ScrollXView, ScrollYView

Text: Label, H1-H4, P, TextBox, TextInput, LinkLabel, Markdown, Html

Controls: Button, ButtonFlat, ButtonFlatter, CheckBox, Toggle, RadioButton, Slider, DropDown

Layout: Splitter, FoldHeader, Hr, Vr, Filler

Lists: PortalList, FlatList

Navigation: Modal, Tooltip, PopupNotification, SlidePanel, ExpandablePanel, PageFlip, StackNavigation

Dock: Dock, DockSplitter, DockTabs, DockTab

Media: Image, Icon, LoadingSpinner, Vector, MathView, MapView

Canvas: Rendering Splash from Claude Code

Makepad Canvas (tools/canvas/) is a standalone app that renders Splash code received via HTTP/WS. Used by Claude Code for visual output.

HTTP API (recommended for sending Splash)

PORT=$(cat /tmp/makepad-canvas.port)

# Full render
curl -s -X POST "http://127.0.0.1:$PORT/splash" -d 'View{width:Fill height:Fit Label{text:"Hello"}}'

# Streaming render
curl -s -X POST "http://127.0.0.1:$PORT/splash/stream"                    # begin
curl -s -X POST "http://127.0.0.1:$PORT/splash/stream" -d 'View{...'      # append
curl -s -X POST "http://127.0.0.1:$PORT/splash/end"                       # end

# Clear
curl -s -X POST "http://127.0.0.1:$PORT/clear"

WS Event Listening (for receiving click events)

# Long-lived WS connection receives button click events as JSON
mkfifo /tmp/ws_fifo; (sleep 99999 > /tmp/ws_fifo &)
websocat ws://127.0.0.1:$PORT < /tmp/ws_fifo > /tmp/canvas_events &

# Events arrive as: {"event":"click","widget":"btn_name"}

Interactive Buttons

Use name := Button{...} to create clickable buttons. The name is sent in click events:

View{width:Fill height:Fit flow:Right spacing:12
  btn_save := Button{text:"Save"}
  btn_cancel := Button{text:"Cancel"}
}

When clicked: {"event":"click","widget":"btn_save"}

Vector Animations in Splash

// Pulsing dot (loop_:true = indefinite, NOT "indefinite"!)
Vector{width:16 height:16
  Circle{cx:8 cy:8 r:6 fill:#x44ddaa opacity:Tween{from:0.3 to:1.0 dur:1.5 loop_:true}}
}

// Moving dot with color change
Vector{width:Fill height:30
  Path{d:"M 20 15 L 400 15" stroke:#x222244 stroke_width:1.}
  Circle{cx:Tween{from:20 to:400 dur:3.0 loop_:true} cy:15 r:4 fill:Tween{from:#x44ddaa to:#xffaa44 dur:3.0 loop_:true}}
}

Canvas Splash Syntax (CRITICAL -- differs from script_mod!)

When generating Splash for Canvas HTTP rendering (POST /splash), use these EXACT patterns. Canvas Splash syntax differs from script_mod! macro context in several critical ways:

1. Properties use dot-path inline, NOT nested blocks:

// WRONG -- nested block syntax does not render backgrounds
RoundedView{height: Fit draw_bg: { color: #x1a1a2e border_radius: 8.0 } }

// CORRECT -- dot-path inline
RoundedView{width: Fill height: Fit draw_bg.color: #x1a1a2e draw_bg.radius: 8.}

2. Border radius is draw_bg.radius, NOT draw_bg.border_radius:

// WRONG
draw_bg.border_radius: 8.0

// CORRECT
draw_bg.radius: 8.

3. Padding uses explicit Inset{} type with trailing-dot floats:

// WRONG -- bare number or nested block