Documentation

Learn Motus — the compiled XML template language that outputs streaming HTML from the edge.

Overview

Note: Motus is heavily experimental and was entirely vibecoded. It’s built on ideas 5+ years in the making — an exploration of how a language designed for the web from scratch could approach data fetching, rendering, and reactivity without inheriting assumptions from general-purpose languages.

Motus is a compiled XML-based template language. You write .mot files that look like HTML with extra powers: scoped variables, SQL queries, components, reactive state, and pipe transforms. The compiler turns these into binary bytecode, which a WASM VM interprets at the edge to stream HTML to browsers.

AI-Friendly: Motus uses standard HTML + CSS as its output format and XML as its input. LLMs already know both. No virtual DOM, no JSX, no framework-specific abstractions — just markup that any AI can read, write, and reason about.

Quick Start

A minimal Motus page is just HTML:

hello.mot

To add dynamic data, use let bindings and output:

greeting.mot

Templates

Let Bindings

The let tag creates scoped variables. The variable is visible only inside the body of the let tag. Use output to interpolate values.

Conditionals

Use if, elsif, and else for conditional rendering:

Loops

Iterate over collections with for. An optional index variable is available:

Match

Pattern matching for multi-branch conditionals:

Components

Define reusable components with defcomp. Props are declared between pipes. Use children for the default slot.

Card.mot

Import and use components:

Component Features

Feature	Syntax	Description
Props	`\| name, price: string = "0" \|`	Typed props with defaults
Slots	`<children>`	Default slot for nested content
Scoped CSS	`<style>` inside defcomp	CSS scoped to component
Dynamic import	`<import X from "..." dynamic>`	Load at edge render time

SQL Queries

Security: SQL queries are compiled to queryRef signatures. At runtime, the edge worker sends the queryRef to the origin, which validates and executes the query. Raw SQL never reaches the browser.

Schema Types

Schema File

Define your data models as standard Cap'n Proto schemas with Motus-specific annotations:

models/contact.capnp

Importing Schemas

Import schema files with the schema keyword. The compiler auto-invokes the capnp toolchain:

SQL Auto-Typing

Type Mapping

Cap'n Proto	Motus Type
`Bool`	bool
`Int8–64, UInt8–64`	int
`Float32, Float64`	number
`Text, Data`	string
`List(T)`	array of T
`Void`	void
Named struct	object (with typed fields)

Annotations

Motus recognizes these annotations on schema fields for form generation and validation:

Annotation	Effect
`$table("name")`	Links struct to SQL table for auto-typing
`$label("text")`	Form label text
`$placeholder("text")`	Input placeholder
`$computed`	Backend-generated — excluded from all forms
`$noInsert`	Excluded from insert forms
`$noUpdate`	Excluded from update forms
`$formOptional`	Optional in form even if required in model
`$multiline`	Render as textarea instead of input
`$hidden`	Excluded from visible form fields

Compile-time safety: When you access contact.phone on a Contact-typed variable, the compiler emits an error if phone is not a field in the schema. No more runtime surprises from typos.

Reactive State

Use var to declare reactive state and set to update it. Reactive binding markers enable browser-side targeted DOM updates.

Reactive Binding Markers

The compiler emits special markers (@bind, @set, @exprbind) that the browser runtime uses to update only the affected DOM nodes when state changes.

Pipe Transforms

Chain built-in transforms with the pipe operator:

Built-in Functions

Function	Description
`uppercase`	Convert string to uppercase
`lowercase`	Convert string to lowercase
`trim`	Strip leading/trailing whitespace
`length`	Return collection or string length
`reverse`	Reverse a string or array
`json`	Serialize value to JSON string

AI-Friendly Design

Motus is designed to be the ideal language for AI-assisted development:

XML syntax — LLMs are trained on billions of HTML/XML tokens. Motus templates are immediately familiar.
HTML + CSS output — The output format is standard HTML and CSS. No framework-specific runtime, no virtual DOM diffing, no hydration mismatch.
Position-based — No namespace prefixes or complex attribute binding syntax. <let name "Alice"> is self-evident.
Scoped components — Each component is a self-contained file with markup, style, and behavior. Perfect context window for an LLM.

Why this matters: When an AI generates or modifies a Motus template, the output is standard web markup. There is no transpilation gap, no framework-specific gotchas, and no hidden runtime behavior. What the AI writes is what the browser renders.

Architecture

The Motus compilation pipeline:

Origin Server (C99) — Compiles .mot source to bytecode. Caches modules. Handles SQL data RPCs.
Edge Worker (Cloudflare) — Interprets bytecode via WASM VM. Streams HTML response chunks.
Browser — Receives streamed HTML. Reactive markers enable targeted DOM updates.

Bytecode format: little-endian binary, magic 0x00544F4D ("MOT\0"), version 1.2. Contains: constants pool, interned strings, data request signatures, dependency paths, component references, and instruction chunks.

Comparison Operators

Because Motus uses XML syntax, angle brackets are reserved. Use keyword operators instead:

Keyword	Meaning	Equivalent
`eq`	Equal	`==`
`neq`	Not equal	`!=`
`lt`	Less than	`<`
`gt`	Greater than	`>`
`lte`	Less than or equal	`<=`
`gte`	Greater than or equal	`>=`