25. Web UI Overview

MALDA supports more than one way to build user interfaces. The models below share HTTP and routing concepts but target different runtimes and delivery styles. Start here before diving into a specific chapter. Prefer one model per surface (IDE UI1002 when a file mixes @PAGE/@AIPAGE with ui.mount/ui.render).

25.1 Choose your UI model

25.2 Decision guide

Pick HTML fragment components when…

• You want server-rendered HTML with targeted fragment updates instead of full page reloads.
• Forms post to @ACTION handlers and you need @LIVE push updates.
• You already think in HTML templates and componentFragment(targetId, html).

Pick server-driven ui.* trees when…

• You want incremental patches (ui.mount / ui.render) instead of HTML strings.
• You compose controls as ui.control(props, children?, key?) and keep state in ui.state.
• You will use the embedded UIHost (a program that calls ui.mount can start it). Do not pass HTML into ui.mount.

Pick HttpServer / @PAGE when…

• Each request should return a complete HTML page or redirect.
• You rely on @AIPAGE or generateUI() for LLM-generated HTML.
• Your app is mostly document-oriented (dashboards, wizards, marketing pages).

Pick browser JavaScript when…

• The UI must run client-side (rich DOM interaction, offline-ish bundles).
• You use a hybrid stack: MALDA backend API + MALDA or JS frontend bundle.
• You need @client() / @shared() split from a single .malda source file.

Pick browser games when…

• You need a canvas loop, keyboard/gamepad, three.*, or @shader() GLSL kernels.
• The host is malda play (or malda compile --mode js), not the interpreter.
• You want the playable GPU billiards appendix as a smoke test — 39.

25.3 How the models relate

                    ┌─────────────────────────────────────┐
                    │         MALDA Web UI choices          │
                    └─────────────────────────────────────┘
                                      │
     ┌───────────────┬────────────────┼────────────────┬────────────────┐
     ▼               ▼                ▼                ▼
 HTML fragments   ui.* trees     HttpServer / @PAGE   Browser JS
 (component +     (mount/render  (full pages +        (transpile +
  ACTION + LIVE)   + UIHost)      AI HTML)             dom.* / canvas)
     │               │                │                │
     └───────────────┴────────────────┴────────────────┘
                                      │
                              HTTP / REST API layer
                         (see REST API + REST Web Client)

You can combine models in one product when boundaries are explicit: for example, @PAGE for marketing routes, a ui.* app shell, and a browser JS bundle for an interactive widget. See 29. REST API Server for JSON endpoints that any UI model can call.

25.4 Runtime boundary reminder

• Server (interpreter or transpiled .exe): HttpServer, database clients, agents, server components, @PAGE.
• Browser (JS transpile): DOM helpers, canvas/game APIs, local actors—no direct SQL or filesystem on the server from browser code.
• Hybrid: browser UI calls MALDA REST routes; server keeps secrets and persistence.

See 2. Tools & Tooling (Runtime modes at a glance) for interpreter vs transpile vs JavaScript trade-offs.

25.5 Browser games