Compiled against your types
A template reads a Jai struct. Every name, member, prop, function and call is checked when the app builds: a typo stops the build with its line, its column and the members that do exist.
See it →For agents
This repository ships a Claude Code skill at .claude/skills/motus/SKILL.md: a short, precise brief on the language, the Jai side of an entry, and the mistakes worth avoiding. With it, an agent writes templates that compile the first time, and checks them before it says it is done.
Its description, which Claude Code reads to decide when to load it:
Write, check and wire Motus templates (.mot) in Jaiweb — components, styles, regions, routes, forms, queries — and mount them as entries from Jai controllers. Use when creating or editing any .mot file, a page or entry, a component's styles, or the Jai code (controllers, @Call/@Action/@Enter) that a template calls.
361 lines. It points to the sources of truth (the modules' headers, the tests, Argoshot) rather than repeating them, and sets the workflow: write, motus check, motus fmt, build.
A skill is a folder. Claude Code finds the ones under .claude/skills/ of the repository it works in, and loads one when a task matches its description: here, any .mot file, an entry, a component's styles, or the Jai a template calls.
Copy the folder into the other repository's skills.
# from the other repository's root; JAIWEB is where this repository is
mkdir -p .claude/skills
cp -R "$JAIWEB/.claude/skills/motus" .claude/skills/
# Claude Code loads it when a task matches its description (a .mot file, an entry...)Keep its paths true. It sends the agent to sdk/Motus/module.jai, sdk/Motus_Flows/entries.jai, the Motus tests, examples/argoshot and tools/motus/motus. In a repository that vendors Jaiweb at its root they resolve as they are; elsewhere, edit those lines to where Jaiweb is.
Ask for the work. “Add a usage page to the dashboard entry, with the last 30 days as a chart”: the agent reads the skill, writes the .mot and its controller, runs motus check and motus fmt, then builds.
---
name: motus
description: Write, check and wire Motus templates (.mot) in Jaiweb — components, styles, regions, routes, forms, queries — and mount them as entries from Jai controllers. Use when creating or editing any .mot file, a page or entry, a component's styles, or the Jai code (controllers, @Call/@Action/@Enter) that a template calls.
---
# Motus
Motus is Jaiweb's template language: HTML plus a few elements and expressions, compiled against Jai types
(a typo or a wrong type is a build error), rendered by a small VM natively, in WebAssembly, or at the edge.
Templates are `.mot` files; the build turns `views/foo.mot` into the constant `TEMPLATE_views_foo`.
Source of truth when in doubt — read these, they are short and precise:
- `sdk/Motus/module.jai` (header): the language, styles, edge pages.
- `sdk/Motus_Flows/entries.jai` (header): entries, calls, actions, routes, `@Enter`, live regions.
- `sdk/Motus/tests/test.jai`: one passing example of nearly every feature.
- `examples/argoshot/` (`app.jai`, `views/*.mot`): a complete product on entries. A product: native, it
links its modules (`build.jai`: `build_app(..., link = .["Screenshots", "Products", ..., "Marketing"])`),
their rows its own; its code `#import`s them (`#import "Screenshots";`) and calls their public procedures
directly (`Screenshots.account()`, `(answer, failed)` as anywhere: how_to/101_modules), and a module's
own page, if it has one, comes as a template constant (`<NAME>_TEMPLATE`).
`examples/argoshot/test.sh` runs it end to end.
## Workflow
1. Write or edit the `.mot` (and the Jai controller it calls).
2. `tools/motus/motus check <files or dirs>` — the compiler's errors with file:line:column, no build needed.
3. `tools/motus/motus fmt -w <files>` — the repo's formatting (CI runs `fmt --check`).
4. Build the app (`jai build.jai`) and run its tests. Template type errors are build errors.
(`tools/motus/motus lsp` is the language server the VS Code extension in `editors/vscode` uses.)
## The language
```xml
<output product.name> <!-- escaped text -->
<output body_html> <!-- a member noted @Html in Jai: inserted as HTML -->
<let total (price * qty)> ... </let> <!-- a binding for its children only -->
<let o {a: 1, b: "two"}><output o.b></let> <!-- object and array literals: {..}, [..] -->
<if (stock > 0)>In stock<elsif backorder>Soon<else>Sold out</if>
<for p, i in products> <output i>: <output p.name> </for>
<for n in 1..3><output n></for>
<match status><case "ACTIVE">on</case><case "DRAFT">draft</case><default>off</default></match>
<a href=(base + "/keys") class=(if active then "on" else null)> <!-- computed attributes; null/false: left out -->
```
- Jai's operators: `== != < <= > >= && || ! + - * / %`. In a tag, outside parentheses, a `>` ends the
tag: put a comparison with `>` or `>=` in parentheses, `<if (a > b)>` (the compiler refuses the slip
`<if a > b>`). `+` adds numbers or joins text. Inline condition: `(if a then b else c)`.
- Functions are called: `<output money(price, "brl")>`, `default(a, b)`, `number(n, 2)`: `uppercase
lowercase trim length default join truncate first last money date plural paragraphs where number
percent url css`. No pipes, no filters. Their formats are `Presentation`'s procedures (product code
calls the same: `money` is always `$1,234.56` / `R$ 1.234,56`).
- The app's procedures are functions too: any top-level procedure of a `.jai` the template `<load>`s or a
module it `<import>`s, by its bare name: `<import Presentation>` then `<output when(k.created_at)>`.
Arguments in order (trailing defaults allowed); whole numbers, floats, bools and text in, one of them
out; Motus's own names win; overloaded or polymorphic ones are not callable. They run at once as the
page renders, at origin: no effects in them, and an edge part cannot call one. Prefer this to
pre-formatting values in a controller only for the template.
- `can("orders.read")`: whether the viewer has a permission (decided at the edge for edge pages).
### Components
```xml
<defcomp Card | product: Product, highlight: bool = false, footer: html = "" |>
<article class=(if highlight then "card hot" else "card")>
<h3><output product.name></h3>
<children /> <!-- what the caller put inside <Card>...</Card> -->
<output footer>
</article>
</defcomp>
<Card product=p highlight=p.sold_out><p>body</p><@footer><small>fine print</small></@footer></Card>
```
Prop types: `string int number bool html`, a Jai type by name (`Product`, `Logs.One`), lists `[] T`.
`<@name>…</@name>` fills an `html` prop. A `<defcomp>` is visible in its enclosing scope (local ones
too); a layout library (`views/layout.mot`) holds shared components.
**A component needs more than one call site** (owner's rule). A section used in one place stays
inline in its route, however long: no single-use components or `#expand` macros for "structure".
**Components from modules.** `<import Stripe_Card>` makes the module's `.mot` files' components available
(framework, sdk ... layers, or the app's `modules/`), as `<load>` would; the editor tools find them so
too. Such a file holds components and root styles only. Framework components carry no scoped styles:
they document their classes and take `class=`, so the app's CSS decides their look.
### Behavior: no application JavaScript
An app writes no `.js` of its own (owner's goal: Argoshot ships none). Motus's attributes, which the
browser runtime (`/_jaiweb/client.js`) carries out:
```xml
<form method="get" region="pg" submit-on="change"> <!-- sent as it is filled: a choice made -->
<input type="search" name="q" submit-on="input"> <!-- ... as it is typed (250 ms after the last key) -->
</form>
<form call=Keys.revoke(id = k.id) confirm="Revoke this key?"> <!-- asked first (a form's or a button's) -->
<button type="button" copy=k.access_key>Copy</button> <!-- to the clipboard; .jw-copied a moment -->
```
- A GET form sent this way replaces the address without a history step; a newer GET navigation cancels
an older one still on its way. After a navigation, a field takes the server's value only where the
server's HTML changed it (a preset, a mode's choices) and the person has not touched it meanwhile;
the focused field is never overwritten. A new `[autofocus]` element gets the focus.
- State lives in the URL and the server renders the whole form from it: what shows, which choices,
summaries. No hidden fields packed by script, no client copies of server rules.
- **State variables** (docs/motus-reactivity.md): a route's query parameter that a control binds is one. `<input bind=q>`
(`bind=params.q` under `|params: T|`) shows it and writes the URL's `q` as it changes, with no form: what reads only it is
redrawn in the browser by compiled code, no request; what origin draws from it is asked for alone; `motus graph <file>`
shows each field's plan. Checkbox `bind=` a bool; radio `bind=s value="x"`; `<select bind=s>` (its options' `value=`, or
their text as written). `value=` is only ever shown. A GET form is plain HTML: its fields are state only when bound.
- **Page state**: `<state open = false>...</state>` (`<state tab: string = "a">`), scoped as a `<let>`, the browser's alone (a
tab, a disclosure, a selection): kept by its key across every morph; in a `<for>` one for each row, keyed by the row's `id`
(else `key=`). Only browser parts read it (origin reading it is a build error).
- **Events** on any element: `on:click=(open = !open, page = page + 1)` writes state when it happens, computed in the browser;
`on:click=Cart.add(sku = p.sku)` posts an action (signed where the page is drawn). On the element that triggers (a bound
control, an event's): `debounce=300` (ms; 150 while typing, else 0), `throttle=200`, `edge="leading"`, `requests="latest"`
(cancel the one before: parts' default) | `"first"` (ignore while one goes: actions' default) | `"queue"` | `"all"`.
- **Typed forms**: `<form buyer: Buyer call=Box.pay(buyer, event = e.code)>` (the action's argument `buyer: Buyer`; posted as
`buyer.name`), `<form Buyer call=X.y>` (the action takes `Buyer` itself; its state `it`), `= n.draft` a starting value
(origin's), `note := n.draft` (its type the action's). `<field buyer.name label="Name" autocomplete="name" />` draws a label
and its control from the member's type (text, number, yes/no, an enum's select, `@Multiline` textarea, `@Hidden`; other
attributes go to the control); `<fields />` the members not placed, `<fields after=buyer.name />` / `before=`. Each member is
a page state (`<output buyer.name>` drawn as typed); the action's notes are the checks, browser and origin; `@Private` never
drawn nor sent; forgotten once the action took it. Labels are the template's (Jai's notes hold no text with spaces).
- **Edge pages**: a request parameter a control binds (the mount's `params` struct) is a state variable too; it is drawn in the
browser inside the edge part, the rest of what it reaches is the page again (the edge's).
- Dialogs: HTML's own `popover` / `<dialog>` with `popovertarget`, not script.
**A component's script** (only for what HTML and the attributes above cannot do: a third party's
widget, Stripe's card): a `<script>` with no attributes right inside a `<defcomp>` is the component's
behavior. It is not drawn where the component is; the build bundles every such script (an entry's
library's into one cached `/_mot/js/<hash>.js`, as its stylesheet), and the runtime runs it once for
each outermost element of the component as it appears (first load, navigation, fill, live update),
with `element` bound to it. The component's outermost elements carry `data-jw-c="<Name>"`; give it one
outermost element and pass what the script needs as attributes of it (`data-key=key`).
```xml
<defcomp Stripe_Card | key: string, secret: string, class: string = "" |> <!-- sdk/Stripe_Card/card.mot -->
<div class=(...) data-key=key data-secret=secret> ... </div>
<script> const form = element.closest("form"); ... </script>
</defcomp>
```
A `<script src=...>` stays where it is written; a store's template has no scripts at all.
### Styles (three levels)
```xml
<style> <!-- ROOT: a file's top-level <style>: every element's -->
:root { --ink: #16212a }
body { font: 16px/1.5 system-ui; color: var(--ink) }
</style>
<defcomp Meter | pct: int, tone: string |>
<style> <!-- SCOPED: the component's direct child: its own elements only -->
.bar {
width: calc(var(pct) * 1%); /* var(prop): a Motus value, becomes a CSS variable */
background: var(tone, gray);
transition: width .3s; /* changes from live updates animate */
&:hover { opacity: .8 } /* nesting; & is the outer selector */
.full & { background: red }
@media (max-width: 600px) { display: none }
}
.dot { translate: calc(var(pointer.x) * 1px) 0 } /* the browser's: pointer.x/y, scroll.x/y,
scroll.progress (0-1), viewport.width/height */
</style>
<div class="bar" style="height: 6px"></div> <!-- INLINE: one node -->
</defcomp>
```
- A `var(name)` without `--` reads the component's props; `--name` stays plain CSS. Values are sanitized
(`css()`). Root styles read only the browser's values.
- An entry links its CSS: one stylesheet for the whole library (cached for every page of the app) plus one
for the template's own components. `motus_render` pages get an inline `<style>`.
- Styles go at `<styles />` or the end of `<head>`; a fragment with no `<head>` gets none.
- Scoping adds an attribute to each selector's last part, so a scoped rule beats a root rule of the same
selector. Keep shared classes root; scope only what is the component's alone (and move its `@media`
rules with it).
### Regions, loading, motion
```xml
<region id="preview" transition="fade"> <!-- a part kept/replaced alone on navigation and actions -->
<loading><Spinner label="Rendering…" /></loading> <!-- shown at once while a request that changes it goes -->
...
</region>
<region live id="recent">...</region> <!-- re-rendered and pushed when the rows it read change -->
<form method="get" action=(base + "/play") region="preview">...</form>
```
Transitions: `fade slide rise scale` (view transitions; reduced motion respected). A first render whose
regions wait on calls streams the frame first, then each region (`<template jw-fill>`) the moment its own
calls answer: the calls a render asks for run at once (each a lane of a `for parallel`, in the page's own
flow), so the slowest holds back only its own region. Keep the frame free of calls (a call outside every region turns
streaming off for the page). `motus_mount(..., whole = true)`: never streamed.
### Entries: routes, calls, actions
```xml
<!-- views/app.mot, mounted at /app -->
<let g Account.current(path = path)>
<if g.redirect><redirect to=g.redirect /></if>
<App title=route.title>
<routes transition="fade">
<route "/" title="Overview">...</route>
<route "/logs/:id" params=Logs.One title=("Log #" + id) can="logs.read" else="/app">
<let log Logs.one(id = id)><output log.text></let>
</route>
<route "/keys" title="API keys"><@actions><a href=(base + "/keys/new")>New</a></@actions>
<form call=Keys.save(id = k.id)>
<input name="name"><button>Save</button>
</form>
</route>
<route "*"><Not_Found /></route>
</routes>
</App>
</let>
```
- The template reads `Motus_Request`: `base` (where the entry is: prefix links with it), `root`, `path`,
`query`, `signed_in`, `notice`, `error` (an action's answer).
- `route.title` (any attribute of the matching route, or its `<@name>` HTML) is readable anywhere, so the
frame is written once. `<routes whole>`: full pages, no in-place navigation. `<redirect to=…/>`,
`<status code=404 />`.
- `<form call=X.y(fixed args)>` posts to its own page with the action and the fixed arguments signed in the
URL; the rest of the input comes from the fields, checked by the action's notes (`@Required`,
`@MaxLength(n)`), which also become the inputs' HTML attributes. `optimistic="remove"` /
`optimistic="add" into="list"` show the change before the answer. `<form call=Room.read(upto = last) seen>` is sent
once by itself when it comes into view while the tab is seen (a read marker), its redirect not followed; never
`hidden` (it takes no room anyway). Who has the app's pages open: `presence()` (Flows) in a live view's render, which
renders again when that changes.
- Queries (Jaiweb models, one index range): `<let items query Part where category == c order by number after
:cursor limit 24>`. In an edge page a query is origin's, its rows baked into the frame, unless it says
`edge` (`<let items edge query Part ...>`): then its rows are fetched at the edge, cached apart. A query
reading the request must say `edge`. `<let items edge lazy query Part ...>` reads nothing where it is
bound: only where the render first uses its rows (a branch not taken never fetches them), a part of its
own at the edge, its region drawn by the rows' shape until they come. Refine it before it is read, one
query of both: `<let newest lazy query items order by number desc limit 1 single>`.
- A query inside a `<for>` over another query's rows, reading the row, is an include: `<for o in orders><let
lines query Order_Line where order_number == o.number limit 2>`. It is read with its collection, once per
row, in the same part (one trip, no cascade). The collection needs a limit (at most 100); one level deep.
- A query reads all its model's public columns. `<let items fields query Part ...>` reads only the columns
the template uses (followed into components' props and includes); `fields(name, price)` reads those named
and refuses a template reading others. The columns are part of the cache key: opt in where it pays.
- A model's member noted `@Private` (a password's hash) is never read by a template nor fetched by its
queries. A record is never written whole into a page: output, attributes, a form's arguments and an edge
wrapper's props take values (`m.id`, not `m`).
- Except for debugging: `<debug><output m></debug>` writes a record or a list whole (its members, never the
`@Private` ones), drawn only for the product's staff (`JAIWEB_PAGE_DEBUG`: `team`, the default, a user of
the realm's own organization; `anyone` on a developer's machine; `off`). Never at the edge nor cached: in
an edge page a staff's request goes to origin, the page whole, `no-store`.
## The Jai side
```jai
routes :: () {
motus_mount("/app", TEMPLATE_views_app, .[Account, Keys, Logs], TEMPLATE_views_layout);
motus_mount("/orgs/:org", TEMPLATE_views_orgs, .[Orgs, Billing], TEMPLATE_views_layout);
motus_mount("/", TEMPLATE_views_site, .[Site]); // last: every other path
} @Handler
render_view :: () { motus_render_view(routes); } @Job // live regions
setup :: () { register_job(render_view); }
Keys :: struct {
list :: () -> (keys: [] Api_Key = .[]) { ... } @Call // a read, called from the template
save :: (p: struct { id: int; name: string; @Required @MaxLength(60) }) -> (done: Motus_Done = .{}) {
...
return .{notice = "Saved."}; // or .{error = "..."}, or .{redirect = "/app/keys"} (as written)
} @Action @Permission(keys.manage)
}
Orgs :: struct {
At :: struct { org: int; } // the mount's :org
enter :: (p: At) -> (done: Motus_Done = .{}) { // once per request, before every call and action
if !enter_org(p.org) return .{error = "No such organization."}; // 404
return .{};
} @Enter @Async
}
// a call or action that needs the mount's params: motus_mounted(Orgs.At).org
Panel :: struct { // motus_mount("/app", ...): who may be in, said once
enter :: () -> (done: Motus_Done = .{}) { // no params: a mount without :params
if !signed_in() return .{redirect = "/login"};
plan := current_plan();
if !plan.active return .{redirect = "/start"};
return .{};
} @Enter @Async
// every call and action below: no sign-in check of its own (enter ran first)
}
```
- **Access to a whole area is the entry's `@Enter`**: signed in, a plan, staff, the organization entered.
It runs before every render, call and action of the mount, each request. Never repeat
`if !signed_in() return .{redirect = ...}` at the top of each call (one forgotten is a hole); a call
that needs more (a permission) says `@Permission(x)`.
- One `@Enter` per entry; it takes the mount's `:params` as a struct, or nothing (else a build error).
- `@Call` and `@Action` are `@Async` already (do not write both). `@Enter` still says `@Async`. `@Permission(x)` needs an `@Async` procedure: a call or action is one; on a call, a refusal is the page's 401/403.
- A call renders only: code that writes on a read checks `reads_only()` first.
- Templates rendered to a string (emails, invoices, fragments): `program, err := motus_program(TEMPLATE_x,
X_View, TEMPLATE_layout); html, err2 := motus_render(*program, *view);`.
- An entry reads models with queries of its own: `motus_mount("/parts", TEMPLATE_views_parts, .[Catalog],
TEMPLATE_views_shell, models = .[type_info(Part)], params = Parts_Query)` (`params`: a struct of its query
string's parameters, read by name). A query said `edge` makes the page one made in two places, cached at
the edge by read set; nothing else says so. See the catalog example.
- Caching follows what the render did: a page that read only public data is `public` and kept at the edge
until a write to what it read purges it; one that read who asks (a `@Session` model or member, a cookie, a
varying header), wrote, or set a cookie is `private`. A model noted `@Session` is whoever's signed in.
### Effects at once, in a controller (lanes)
A page's calls already run at once (each a lane). Inside one call or action, several slow effects
(other services, app calls) go at once with a block of lanes (Flows/lanes.jai; the long form,
with every option and what the build refuses: `how_to/060_parallel` to `how_to/063_timeouts_and_retries`):
```jai
price, stock, eta, reviews: string; // declared before: a lane is a statement
for parallel() {
price = Prices.get(id); // each statement a lane, started at once
{ stock = Stock.of(id); eta = Stock.eta(stock); } // { }: steps in order, in one lane
reviews = Reviews.top(id);
} // past the block: every lane finished
for parallel(ids) quotes[it_index] = Quotes.of(it); // a lane per item: write its own slot
won := -1;
for first(*won) { a = Mirror_A.get(k); b = Mirror_B.get(k); } // first to finish wins, rest cancelled
r: Lanes_Result;
for parallel(timeout_ms = 300, result = *r) { ... } // deadline; failures reported, not fatal
for with_effects(.{timeout_ms = 800, retries = 2, backoff = .{initial_ms = 100}}) { rate = fx(c); }
```
- The build refuses: a lane reading or writing what another lane writes; every lane of a
`for parallel(items)` writing one variable; a declaration as a lane; a transaction in a lane (or a
block in a transaction); in `for first`, effects that tell the world (External, Respond, Push).
- Without `result = *r` a lane's failure fails the flow; a deadline's cancelled lanes just stop.
- Retries: only failures that surely did not happen, unless the driver is `idempotent` or the block
says `retry_uncertain = true`.
## Gotchas
- `remove` is a Jai reserved word: name actions `erase`, `remove_item`…
- `@Async` procedures have no `_async` suffix (`find`, `error`, `redirect`, `respond`). A local named like
one (`error := ...`, `profile := profile()`) shadows it; and a leftover bare `if error` after renaming
the local still compiles (the procedure is truthy). Rename every use.
- A controller struct must not share its name with a module's namespace (`Campaigns`, `Products`…) that
`#import "<Name>"` gives (its `api.jai`, `modules/<Name>/api.jai`, written by the build).
- The platform's business apps are all modules (`framework/Crm`, `Email`, `Sms`, `Whatsapp_Cloud`, `Support`,
`Campaigns`, `Analytics`, `Storefront`, `Marketing`, and the commerce ones): code `#import`s them,
never `#load`s an `api.jai`; products link them. The channels are also platform apps
(`modules/Jaiweb_Channel_<Name>` builds each). Email's namespace is
`Email_App` (`API_NAME` in its `module.jai`); its, Sms' and Whatsapp_Cloud's types bring the channel
answers (`Mail_Channel_Answer`...): don't `#load` `Stack/*_channel_types.jai` beside the import.
- A seller's site using Marketing `#import`s it and `#load`s `framework/Marketing/touches.jai` and its
`site.jai` (`marketing_touch()`, the consent banner's answer). A product linking it calls
`Marketing.connect()` once (no catalogue install tells a linked module it is there: Argoshot's staff claim).
- `#import "<Module>"` gives a linked module's public types and constants by their own names, for the
templates too; the module itself, for what is no API (its routes, its page's procedures), is
`<Name>__linked`. `motus check` warns that a module's component is not defined unless its `.mot` is given too.
- Comparisons are words; `<`/`>` in an expression would end the tag.
- Action redirects are used as written (absolute paths), not relative to the entry.
- Scoped styles add `data-m-<hash>` attributes to the component's elements; tests matching exact markup
must expect them.
A template language for Jaiweb
Motus is HTML plus a few elements — output, let, if, for, match, components, regions, routes — compiled against the Jai types your app already has. A misspelled member is a build error, not a blank on the page.
In one screen
A template reads a Jai struct. Every name, member, prop, function and call is checked when the app builds: a typo stops the build with its line, its column and the members that do exist.
See it →A compiled template is plain data: a small program that reads the view in place. The same VM runs it in the server, in a WebAssembly build of the app, and in a Cloudflare worker.
See it →Typed props, defaults, children, <@slot> fills. Styles at the root, scoped to a component (nesting with &, props as var(name)), or on one element.
A region is replaced alone on navigation, its <loading> shown at once. A first render streams the frame, then each region; a live one renders again when the rows it read change.
An entry's <routes> are its pages, their params typed. Its data comes from controller procedures called as expressions; its forms call @Actions, whose notes check the inputs.
bind= ties a control to the URL's state, <state> keeps the page's, on:click= writes either, a typed form holds a Jai value. The compiler draws in the browser what it can, asks origin for the parts only origin can draw, alone.
An edge page is made in two places: origin's part once, the request's part at the edge. Each part is cached by what it read and purged when that changes, so a write drops only what it touched.
See it →Mistakes are build errors
These three templates are compiled right now, against the playground's Shop. Under each is what the compiler answered: the message a build stops with, line and column first.
In an app the templates compile with the program (motus_program, an entry's motus_mount), so a template that no longer fits its type is caught before anything runs.
Small programs
Static HTML merges into single literals, constants fold, a branch on a constant keeps only the branch taken. What is left is a few instructions, serialized as plain data for a worker or a WebAssembly unit to run.
Where next
Tour
Each example is a .mot file of this site, compiled when the site was built by the compiler the playground uses (a store's rules: no scripts, CSS checked), and rendered now by the VM with a sample's data. The parts that need a server are working pages of this site.
<output x> writes a value as text, escaped. A computed attribute (title=store.tagline) is escaped too, and an href or src from data is checked: the javascript: URL in the data became #. A value that is not there writes nothing. A member noted @Html in Jai is the one way to insert HTML: what the program made, never what a visitor typed.
<let name value> binds for its children only. <if> takes a bool (a number is not a condition; a text or a list is, when not empty), with <elsif> and <else>. <for p, i in products> gives the index too; 1..5 is a range. <match> compares with each <case>; on an enum, by its names, checked.
Expressions are Jai's: == != < <= > >= && || !, + - * / %. In a tag, outside parentheses, a > ends the tag, so a comparison with > goes in parentheses: <if (stock > 0)> (the compiler refuses the slip <if stock > 0>). + adds numbers or joins text; (if a then b else c) is an inline condition; {a: 1} and [1, 2] are literals. Every expression has a type at compile time: cart == "3" is an error.
Functions are called: money(price, "eur"), default(owner, "nobody yet"), truncate(note, 28). These are Motus's own. An app's procedures are functions too: any top-level procedure of a .jai the template <load>s or a module it <import>s, called by its bare name with whole numbers, floats, bools and text, run at once as the page renders.
<defcomp Card | product: Product, featured: bool = false |> declares a component and its props: string int number bool html, a Jai type by name, or a list [] T. A prop with a default may be left out; one without is required. <children /> is what the caller put inside; <@badge>…</@badge> fills an html prop. Giving a Store where a Product goes is a compile error.
A file's top-level <style> is every element's. A component's <style> is scoped: each selector's last part gets the component's data-m- attribute. Rules nest; & is where the outer selector goes, and a @media inside a rule keeps it. var(pct) reads a prop: the CSS is the same for every render, the value rides on the element as a CSS variable, so a live change animates with the CSS's own transition.
var(pointer.x), var(pointer.y), var(scroll.x), var(scroll.y), var(scroll.progress), var(viewport.width) and var(viewport.height) are the browser's: the client writes them on the page's root once a frame, only when a style reads one. This page's top bar follows scroll.progress; the light on the home page follows the pointer. In the preview below there is no script, so they stay 0.
A <region id="results"> is a part of the page the browser keeps or replaces alone: a navigation or an action's answer sends only the regions whose hash changed. Its <loading> shows at once while a request that changes it goes — a link or form inside it, or one naming it with region="results". transition is fade, slide, rise or scale: a view transition, off when motion is reduced. Open “The HTML it rendered” to see what the client reads.
An entry is mounted at a path; its <routes> say what shows under it. A route binds its parameters to a Jai struct, <route "/posts/:id" |{id}: Post_Params|>, so id is an int (a path where id is not one is not this route). Its other attributes are values readable anywhere — route.title above the routes, so the frame is written once. can= asks for a permission: refused, else= says where to go instead, or the page is a 403. The example is rendered at six paths; in the playground, can() answers yes to what ends in .read.
<routes whole> makes each route a whole page — its own document, no region, no in-place navigation — and <status code=404 /> its answer.
<form call=Comments.add(post = post.id)> posts to its own page, the action's name and fixed arguments signed in the URL (the preview leaves them unsigned and posts nowhere). The other fields come from the inputs, checked by the action's notes — @Required @MaxLength(40) — which also become the inputs' required maxlength="40". An input the action does not take is a compile error. optimistic="remove" and optimistic="add" into="comments" show the change before the answer: for an add, the list's own item is the template, the form's fields in it.
A page's state lives in one of three places, and the template says which. The URL's query: a route's parameter a control binds, <input bind=q> (a checkbox, a radio with its value=, a select's options alike); typing writes q in the address, without a history step. The page: <state open = false>…</state>, scoped as a <let>, one for each row in a loop (by its id), kept across every update of the page; only the browser reads it. A form: its state a value of a Jai type (below).
An element's events write state: on:click=(open = !open), on:click=(price = p), on any element; on:click=Cart.add(sku = p.sku) calls an action. The element that triggers says when and how often: debounce=300, throttle=200, edge="leading", requests="latest" (the default for drawing: a newer one cancels the older), "first" (the default for actions: no double submits), "queue", "all".
A change of state draws, in the browser, what the browser can compute from it (the template's own code, compiled from it: no request), asks origin for the parts it reaches that only origin can draw, each alone, and only else the page whole. The page carries no script of the app's: the runtime is the same for every app.
<form buyer: Buyer call=Box.pay(buyer, event = e.code)> declares the form's state, a value of a Jai type, sent whole to the action whose argument it is (posted as buyer.name, buyer.email). <form Buyer call=X.y> is a form whose action takes the type itself (its state named it); = note.draft gives a starting value, origin's, and note := n.draft takes its type from the action.
<field buyer.name /> draws one member: a label (label=, else the member's name) and its control from its type: a text, a number, a yes/no checkbox, an enum's select, @Multiline a textarea, @Hidden a hidden field; its other attributes are the control's. <fields /> draws the members not placed, <fields after=buyer.name /> those declared after one (before=). Any control binds a member (<input bind=buyer.email>), and anything reads one: <output buyer.name> is drawn in the browser as it is typed.
The action's notes are the checks: @Required, @MaxLength(80) become the controls' required maxlength="80", checked in the browser, then again at origin when it is sent, a refused field marked in place. @Private members are never drawn nor sent. Taken by its action, the form starts again from its starting value.
The compiler reads a template once and records, for every node and expression, what it reads: state, the request, origin's data. Then it cuts the page into parts. A local part reads state and nothing only origin has: its code is the template's, translated for the browser, origin's values it needs lifted into the page beside it. A server part reads state through origin (a call given it): origin renders it alone when asked. An edge part reads the request on an edge page: the edge makes it. What no part can hold (a route's values, the <title>) makes the page whole.
Each state variable gets a plan: the local parts and attributes to draw, the server parts to fetch, or the page whole and why. motus graph prints it for a template; the parts are keyed by the graph, so a part's HTML stands alone in a live push, a fill or a parts answer.
On an edge page a parameter a control binds is a state variable as well: the wall's Cards and List switch is drawn in the browser, the address following; the rest of what it reaches is the page again, made and cached at the edge.
<region live id="wall"> is a live view: the engine keeps what its render read (index ranges of the rows), and when a commit changes those rows it renders the region again, as the viewer, and pushes it to the page, which morphs it in. Nobody says what to watch or when to push.
Where it runs: on the Jaiweb platform, a sandboxed app's live regions are pushed by the engine to signed-in viewers; an edge page's are kept current at the edge by a hub, for every viewer. This site runs alone (./motus_site), where the engine keeps the wall's live region current itself; run ./edge.sh, open the wall through the edge, sign a guestbook in another window, and the wall updates in place.
To watch it happen, open the wall with ?_jw=debug (see how it flows): the debug panel's Flow draws the write, the view's render again (at origin, or at the edge's hub after origin's purge) and the push to the page, each as a pulse along its path, with why it happened.
A template may read an app's models directly: <let rows query Guest_Entry where room == room order by number desc after :before limit 12>. Every query is one index range: the compiler plans it on the model's indexes, and a query no index serves does not compile (it says which @Index would). Its rows are read in place, as the model's struct. Queries are for edge pages and Motus_Flows' own pages; the wall is one. In an edge page, where the rows are read is the template's to say: a query is origin's, its rows baked into the part origin makes once; <let rows edge query ...> makes them a part of their own, fetched at the edge for each request and cached apart from the frame. A query that reads the request (the wall's room, its cursor) must say edge. <let rows edge lazy query ...> reads nothing where it is bound: the render reads it where it first uses its rows (a branch not taken never does), a part of its own at the edge, its region drawn by the rows' shape until they come; refined before it is read (<let newest lazy query rows limit 1 single>), it is still one query. A query inside a <for> over another's rows, reading the row (where order_number == o.number), is an include: read with its collection, once for each row, in the same part: one trip, never a cascade. A query reads its model's public columns; fields reads only those the template reads (followed into components and includes), fields(name, price) those named. The columns are its cache key's too, so it is a choice. A member noted @Private (a password's hash) is never read by a template nor fetched by its queries, and a record is never written whole into a page: a form's argument or an edge wrapper's prop is a value (m.id), not the record. For debugging, <debug><output m></debug> writes it whole (its members, never the @Private ones), drawn only for the product's staff and never cached: in an edge page, a staff's request goes to origin, the page whole.
A page whose frame is all there but whose regions wait on calls answers at once: the frame, each waiting region as its skeleton (its <loading>), then each region as its calls answer, sent down the same response as a <template jw-fill>. Nothing in the template asks for it: the census below waits 900 ms on purpose.
An entry mounted under a path with parameters (/rooms/:room) may have one procedure noted @Enter: it runs before anything under it, every call and every action, each request. Answering redirect goes there instead; error is a 404. Calls and actions read the parameters with motus_mounted(Rooms.At).
@Permission(guestbook.write) on an action (or a call) is checked before it runs: refused, the answer is 401 (nobody signed in) or 403. In the rooms a visitor joins as a guest — an account of their own, which holds the permission — and the template asks the same question with can("guestbook.write").
A template with a query said edge is made in two places; nothing else says so. What reads the request (its parameters, who asks) or the rows of a query said edge is the edge's; the rest is origin's, made once with its calls answered, as the residual program the edge keeps. A wrapper the page calls with children (the wall's <Page>) is a fragment of its own, shared by every page with it. Each part is a URL kept in the colo's cache and the CDN's, purged by tag when a write touches what it read: signing the lobby's guestbook drops the lobby's wall pages and the rooms' counts, nothing else.
A page that reads nothing of who asks is public; one that reads @Session members or can() is decided at the edge, from the session's home there. Without an edge in front — this server alone — origin makes the page whole.
Any page with ?_jw=debug says how it was made, and its debug panel's Flow draws it: through ./edge.sh, the wall shows each part coming from the colo's cache, the CDN's tiers or origin's stream, the edge rendering it, and, when a guestbook is signed, origin's purge by tag, the colo and the tiers dropping it, and the hub rendering the wall again and pushing it. A room is made at origin and passes through the edge.
Streaming · a working demo
The census below waits 900 ms before it counts. The page did not wait: its frame and the census's loading state came in the response's first chunk, and the census filled in when its call answered.
| Room | Entries |
|---|
Counted after a
A template and its data, compiled and rendered by the server as you type, under a store's rules.
Integrations
Motus lives in this repository as sdk/Motus (the language and its VM) and sdk/Motus_Flows (entries, calls, actions, edge pages). The code below is from apps in this repository, read from their files when this site was built.
A part of an app — a dashboard, a site — is one template mounted at a path with the controllers whose procedures it calls. Argoshot mounts five. @Call procedures are its reads, @Action ones its forms'. The template compiles with the program: a misspelled call, an argument of the wrong type, a field the action does not take, is a build error.
Emails, invoices, a fragment to push: motus_program(TEMPLATE_x, View) compiles with the program, so its errors are build errors, and motus_render(*program, *view) renders. The campaigns app sends its emails this way.
A merchant's store template is text, compiled when it is saved with untrusted = true: no scripts, no event handlers, no frames, forms post to the store, CSS checked. Its errors go back with their lines; the program is serialized and kept. This site's playground compiles visitors' templates the same way, and renders them within limits.
motus_mount(path, template, controllers, library, models = ..., params = ...): the models are what its queries read, params a struct of the query string's parameters the template reads by name, the controllers answer origin's part. The catalog example serves 20,000 parts this way; sdk/Motus/edge holds the worker.
Next
The plan is one standalone package around the same compiler and VM, built for wasm32, with two functions: compile(source, schema), which compiles a template against a description of its data and returns a program or its errors with lines and columns, and render(program, json), which renders a program with data given as JSON. Each host wraps those two.
The compiler and VM of Motus, freestanding, exporting compile and render. The VM already runs in WebAssembly (the edge worker's motus_edge.wasm); what it lacks is the compiler beside it and a schema in place of Jai's type information.
The core with typings, for Node, Deno, Bun and workers: templates compiled at build time against a schema of your types, rendered on the server or at the edge.
The same .wasm, run by wasmtime behind a typed wrapper: a program compiled once and rendered per request, its errors surfaced at build time from a build.rs.
A template handler for .mot files that compiles each view against a schema of its locals and renders through the core, so a view that no longer fits its data fails in CI, not in production.
Today motus_compile_with takes a Jai *Type_Info: the names a template reads, their types and their layout in memory all come from it, and the VM reads the view in place. A compile driven by a schema — JSON Schema in, the same checks out, the data laid out from JSON — is the piece the package needs, and it does not exist yet.
For agents
This repository ships a Claude Code skill at .claude/skills/motus/SKILL.md: a short, precise brief on the language, the Jai side of an entry, and the mistakes worth avoiding. With it, an agent writes templates that compile the first time, and checks them before it says it is done.
Its description, which Claude Code reads to decide when to load it:
motus check, motus fmt, build.
A skill is a folder. Claude Code finds the ones under .claude/skills/ of the repository it works in, and loads one when a task matches its description: here, any .mot file, an entry, a component's styles, or the Jai a template calls.
Copy the folder into the other repository's skills.
Keep its paths true. It sends the agent to sdk/Motus/module.jai, sdk/Motus_Flows/entries.jai, the Motus tests, examples/argoshot and tools/motus/motus. In a repository that vendors Jaiweb at its root they resolve as they are; elsewhere, edit those lines to where Jaiweb is.
Ask for the work. “Add a usage page to the dashboard entry, with the last 30 days as a chart”: the agent reads the skill, writes the .mot and its controller, runs motus check and motus fmt, then builds.
404
There is no page at this address. The tour and the playground are where most things are.