# Getting Started with Statum
## What is Statum
Statum is a stateful web application framework for Vala, built on top of
[Astralis](https://github.com/search/astralis) (HTTP server),
[Invercargill](https://github.com/search/invercargill) (data structures / JSON),
and [Inversion](https://github.com/search/inversion) (dependency injection).
It provides:
- **Server-rendered HTML pages** composed from templates and fragments at build
time (`statum-mkpstm`), precompressed with gzip/zstd/brotli and served with
encoding negotiation and ETags.
- **Client-carried state** — signed and (for private data) encrypted snapshots
that the browser holds and sends back, so the server is stateless between
requests (no session store, no database for ephemeral state).
- **Entrypoint hydration** — after a page loads, a lightweight JS client fetches
directives that set the initial slot data and bind the DOM.
- **GUID actions** — POST/GET handlers auto-mapped to `/_statum/action/{guid}`,
invoked from the client via `stm-action` attributes, carrying strongly-typed
private data.
- **Realtime updates** — a SharedWorker-backed SSE channel pushes slot changes
to subscribed tabs.
### Architecture at a glance
```
Browser Server
─────── ──────
GET / ──────────────────────► StatumPage (precompressed HTML)
page loads, the statum client modules boot GET /_statum/entrypoint ────► StatumEntrypoint → directives (set/clear/...)
client applies directives
client binds stm-* attributes
POST /_statum/action/{guid} ► StatumAction → directives
(with X-Statum-Slot headers) (mutate state, push to channels)
```
---
## Quick Start Examples
### 1. A page with an entrypoint
**`home.html`** — the page template, composed with a layout:
```html
/main
Counter: 0
```
**`main.html`** — the layout template:
```html
mainMy App
My App
```
**`HomeEntrypoint.vala`** — hydrates the page:
```vala
public class CounterPublic : Object {
public int value { get; set; }
public Model.ActionDto bump { get; set; }
}
public class HomeEntrypoint : StatumEntrypoint {
public override async DirectiveBuilder handle() throws GLib.Error {
var counter = new CounterPublic();
counter.value = 0;
counter.bump = action_registry.author_private(new BumpPrivate());
return directives().set_typed("counter", Scope.PAGE, counter);
}
}
```
**`Main.vala`** — wires it all up:
```vala
void main(string[] args) {
var app = new WebApplication(8080);
app.add_module();
var statum = app.configure_with();
statum.add_page(); // route from
statum.action(); // GUID auto-assigned
app.run();
}
```
### 2. A guarded page
```html
/dashboardmain
```
The guard redirects unauthenticated visitors to `/` before the entrypoint loads.
---
## HTML Templates
Statum pages are HTML files processed at build time by `statum-mkpstm`.
### Build-time directives (`pstm-*`)
All `pstm-*` elements **must appear inside ``** (except `pstm-content` and
`pstm-fragment`, which live in ``).
| Directive | Where | Purpose |
|---|---|---|
| `/path` | head | The page's route. **Required.** Supports templates: `/cats/{species}`. |
| `main` | head | Wraps this page in the named template (by ``). |
| `main` | head | Names this file so pages/fragments can reference it. |
| `…` | head | Page title, merged up the template chain. |
| `` | body (template) | The outlet where the child page's body is inserted. |
| `` | body | Inlines a fragment (component) by name. |
| `pstm-materialise-as="div"` | `` attr | When this body is composited into a template or fragment, it is wrapped in the named element. |
| `pstm-res-src="logo.png"` | any attr | Rewrites to `src="/_statum/resource/logo.png"`. Also `pstm-res-href`, etc. |
| `pstm-res-src="statum.js"` | `
```
You may cherry-pick trailing modules (core first, always): core + document
gives the full state-binding walk without the markdown engine — but note
`stm-markdown` and `stm-h-demotion` live in the markdown module and do
nothing without it. Core ALONE is headless: it never touches the DOM, so a
non-document templating framework can use it as its state layer (write your
endpoint URLs into `statum.config` before `statum.init()` runs and consume
`statum.addStateListener`).
A legacy `` still works:
`statum-mkpstm` expands it at build time into the four tags above (one build
warning per page names the expansion; a page mixing the legacy reference with
explicit module tags is deduplicated). Prefer writing the four tags
explicitly in new pages.
The client auto-initialises on DOMContentLoaded.
### Configuration overrides (body attributes)
```html
```
### HTML binding attributes (`stm-*`)
| Attribute | Description |
|---|---|
| `stm-text="counter.value"` | Sets the element's text content from the expression. |
| `stm-html="cart.summary"` | Sets the element's inner HTML. |
| `stm-markdown="post.body"` | Renders the value as CommonMark (all source HTML escaped first). |
| `stm-h-demotion="1"` | Demotes child `
`–`
` tags by N levels. Runs after `stm-html`/`stm-markdown`. |
| `stm-if="auth != null"` | Shows/hides the element (and its `stm-else-if`/`stm-else` siblings). |
| `stm-else-if="auth.role == 'admin'"` | Next sibling of `stm-if`/`stm-else-if`. |
| `stm-else` | Next sibling of `stm-if`/`stm-else-if`. |
| `stm-class.active="cart.count > 0"` | Toggles the class `active` based on the predicate. |
| `stm-disabled="!user.canSubmit"` | Disables the element + descendants when truthy. |
| `stm-action="cart.checkout"` | Invokes the action reference resolved from state. On a `