# pragma: full docs for agents > pragma is a web framework built for coding agents. An app is native HTML, CSS and plain JavaScript (never TypeScript) with a closed set of directives; a Rust CLI compiles, lints and validates it and answers every error with the file, the line, the rule and the fix. Pages ship prebuilt with only the JavaScript they use, and every form is a WebMCP tool by default. This file has everything needed to build a pragma app: install, the loop, the app rules (AGENTS.md) and every doc. Index: https://pragma.leonavas.com/llms.txt. Each part is also a separate file under https://pragma.leonavas.com/docs/. ## Install and create pragma is one Rust binary. Linux x64 binary: https://pragma.leonavas.com/downloads/pragma-linux-x64.tar.gz. Node 22 or newer only runs `.server.js` files. ```sh curl -fsSL https://pragma.leonavas.com/install.sh | sh pragma new my-app cd my-app pragma dev ``` Or build from source with Cargo: ```sh git clone https://github.com/leonavas/pragma && cd pragma && cargo install --path core/cli/crates/pragma-cli ``` ## The loop 1. Read `AGENTS.md` in the app (the rules below), then the doc for the task. 2. Write the code: one `.html` per page or component, plain JS, utility classes. 3. Run `pragma check --strict` and fix every error and warning at its cause, never around the rule. 4. Done when `pragma check --strict` prints no problems. `pragma build` writes `dist/`. ## Contents - [App rules (AGENTS.md)](https://pragma.leonavas.com/docs/rules.md): the rules every pragma app follows; read first - [App structure](https://pragma.leonavas.com/docs/structure.md): where each file goes, pragma.json - [HTML syntax](https://pragma.leonavas.com/docs/syntax.md): HTML directives ({path}, :, ., @, $) and blocks - [Components](https://pragma.leonavas.com/docs/components.md): components, props, slots - [State: script, actions, derived values, stores](https://pragma.leonavas.com/docs/state.md): script: state, actions, derived values, mount, stores - [Routes and router](https://pragma.leonavas.com/docs/routes.md): pages, links, params, query, layout, head tags - [Data: load, server actions, skeleton, SSR](https://pragma.leonavas.com/docs/data.md): load, server actions, skeleton, SSR - [Overlays: modal, alert, dropdown](https://pragma.leonavas.com/docs/overlays.md): modal, alert, dropdown - [CSS](https://pragma.leonavas.com/docs/css.md): styles and theme - [Utility classes](https://pragma.leonavas.com/docs/classes.md): every utility class - [WebMCP: forms are agent tools](https://pragma.leonavas.com/docs/webmcp.md): forms as WebMCP tools, markdown for agents - [npm packages](https://pragma.leonavas.com/docs/packages.md): npm packages: when and which - [Performance](https://pragma.leonavas.com/docs/performance.md): performance defaults and budgets - [Logs](https://pragma.leonavas.com/docs/logs.md): OpenTelemetry logs - [pragma CLI](https://pragma.leonavas.com/docs/cli.md): commands, check rules, deploy --- Source: https://pragma.leonavas.com/docs/rules.md # AGENTS.md pragma app: native HTML, CSS and JS, no framework, usable by AI agents. Docs are in `core/docs/`: read the relevant one before changing code. ## Syntax A page or component is one `.html`: an optional `
{$label} {$count}
``` Usage: ```html ``` ## Slots ```html

The body goes in the default slot.

``` - `` receives the children; `` receives `slot="actions"`. Filling a slot the component lacks = error. - Slot content belongs to whoever wrote it: its `$` and `@` resolve there. ## Rules - In a component without a script, `@` calls the caller's function. - State is per instance. A component's script loads only on pages that use it. - No `.server.js` in components: data comes from the page's `load`. - Never read or change a child's state: pass props; the child changes a store or calls its own action. - No `customElements.define`, no shadow DOM. Overlays: use `c-modal`, `c-alert`, `c-dropdown` (overlays.md). --- Source: https://pragma.leonavas.com/docs/state.md # State: script, actions, derived values, stores The top-level `

{$error}

``` A function made by a call (debounce, throttle, once) is a top-level `const`, used directly as the handler; no wrapper function: ```html

Saved: {$saved}

``` The build accepts any top-level `const` as a handler; if its value is not a function, the event throws in dev (`@input="saveLater" needs a function, but "saveLater" holds …`). A timer just assigns the `let`: ```js let now = Date.now() function mount() { const timer = setInterval(() => { now = Date.now() }, 1000) return () => clearInterval(timer) } ``` `mount(el)` gets the component's root element, for what needs its own DOM (an observer, a measurement, focus): ```js let lines = 0 function mount(el) { const observer = new ResizeObserver(() => { lines = Math.round(el.clientHeight / 24) }) observer.observe(el) return () => observer.disconnect() } ``` `mount` runs only in the browser; read from `el`, never write to it (change state instead). It may be `async`: the function it resolves to is the cleanup. What only `mount` needs (a timer id, an observer, a DOM node) is a `const` inside `mount`, not a top-level `let`: a top-level `let` is state, renders on every change and keeps a DOM node in the instance scope. ## Derived values A value computed from state is a function, called on each render: `$total` in HTML, `total()` in JS. A top-level `let` or `const` computed from state once is stale (`js/stale-derived`), and a function used in JS without `()` is always truthy (`js/derived-call`): ```js let count = 0 let doubled = count * 2 // js/stale-derived: computed once const doubled = () => count * 2 // right: `$doubled` in HTML, `doubled()` in JS function check() { if (empty) return // js/derived-call: always true if (empty()) return // right } ``` `let count = start` (a prop) is fine when an action assigns `count` later: it is state that starts from the prop. A value per item is a field of the rows a derived function returns (`{}` takes paths, not calls): ```js const rows = () => items.map(item => ({ item, label: formatPrice(item.price) })) ``` ```html
  • {row.item.name}: {row.label}
  • ``` Keep the original item in the row (`row.item`) and change that one: `{ ...item, label }` is a copy, so `item.done = true` on it changes nothing. ## Services (`import { … } from 'pragma'`) | Name | Use | |---|---| | `shared` | stores: `shared.tasks.items`, `shared.tasks.add(title)` | | `data` | `load` result (data.md); undefined until the load ends | | `params` `query` `page` | route params, query, `page.loading`/`page.error` | | `call(name, input)` | server action (data.md) | | `navigate(url)` | navigate through the router | | `open(id)` `close(id)` `confirm(id)` | overlays (overlays.md) | | `log` | logs (logs.md) | ## Store `lib/state/tasks.js`, read as `shared.tasks` in HTML and in scripts: ```js let items = [] export const persist = ['items'] const pending = () => items.filter(task => !task.done).length function add(title) { items.push({ id: crypto.randomUUID(), title, done: false }) } ``` ## Rules - State is a deep Proxy: `items.push(x)`, `task.done = true` and reassignment all render, from actions, `await`, timers or promises. Maps, Sets, Dates and class instances are not tracked: assign a new value. - Derived values are functions; call them in JS (`total()`). Never keep a derived copy in a `let` updated by actions (`js/stale-derived`, `js/derived-call`). - `data` exists only after the load: read it in functions (`js/top-level-data` at the top level), and put the elements that read it inside the `` of `page.loading`. - In a script write `count`, never `$count` (`js/dollar-in-script`): `$` is HTML only. - Page-only state: the page script. Shared across pages or persisted: a store. A change used by 2+ pages: a store function. - Filters, tabs, pagination: in the `query`, read by a derived function. - `persist` lists `let` names saved to `localStorage`; only for preferences, drafts and local-only data. - A top-level `const` changed in place (`items.push`) does not update the page (`js/const-state`): use `let`. - No `var`, no destructuring `let`, no top-level `await` (do it in `mount()` or an action); `export` only declares props (a store exports only `persist`). - Reach stores only through `shared`; importing a store file is `js/store-import`. - Never write to the DOM (`textContent`, `classList`, `setAttribute`). `addEventListener` only on `window`/`document`, inside `mount`. Never fetch data in `mount`. No custom pub/sub. - The old API (`export const state`/`actions`, `ctx.$`, `ctx.update`, `store()`) is an error (`js/legacy-api`). --- Source: https://pragma.leonavas.com/docs/routes.md # Routes and router | File | Route | |---|---| | `routes/index.html` | `/` | | `routes/about.html` | `/about` | | `routes/shop/index.html` | `/shop` | | `routes/shop/[id].html` | `/shop/:id` | - Every `.html` in `routes/` is a route, except names starting with `_`. `x.html` plus `x/index.html` = error. - `[name]` (file or folder) = path param; a static segment beats a param. No `[...rest]`, no nested layouts. - A page is a fragment: no ``, ``, ``. ``, `<meta>` and `<link>` at the top level of the page go to `<head>` (see SEO). - Read params as `params.id`, `query.filter` in HTML and in scripts (`import { params, query } from 'pragma'`). Always strings. ## Layout `routes/_layout.html`: ```html <head> <link rel="icon" href="/favicon.svg" type="image/svg+xml"> </head> <header> <nav aria-label="Main"> <a href="/" class="nav-link">Home</a> <a href="/shop" class="nav-link">Shop</a> <span>{shared.cart.count}</span> </nav> </header> <main data-page><slot></slot></main> ``` - `<head>` is optional and must come first. Its tags go on every page; it is static (no `:` bindings, no `{}`). Exactly one `<main data-page>` containing only `<slot></slot>`. - The layout has no script: it reads only `shared`, `params`, `query`. For behavior, use a component with a `<script>`. - `routes/_404.html` renders unknown routes. Neither it nor the layout has a `.server.js`. ## SEO and link previews Site-wide tags go in the layout `<head>`. Each page writes its own `<title>`, `<meta>` and `<link>` at the top level; a page tag replaces the layout tag with the same `name`, `property`, `http-equiv` or `rel` (+ `hreflang`); new ones are added. `routes/about.html`: ```html <title>About · Shop

    About

    ``` From server data: write `{path}` in `` and `:<attr>` or `{path}` in a `<meta>`/`<link>` attribute, with `data`, `params` or `query`, and `export const ssr = true` in the page's `.server.js`. The server renders them into the first HTML, so crawlers and link-preview bots (no JS) see them. `routes/blog/[slug].html`: ```html <title>{data.post.title} · Shop

    {data.post.title}

    ``` `routes/blog/[slug].server.js`: ```js export const ssr = true export async function load({ params, request }) { return { post: await findPost(params.slug), url: new URL(request.url).href } } ``` - A missing value keeps the tag's static text or attribute; a `` without `content` or a `` without `href` is dropped. - Structured data (JSON-LD): one ` Pending ``` ## Navigation - Use ``. The router swaps only `
    `, prefetches links and keeps the layout. - Every navigation, including query-only changes, recreates the page state. - From JS after an action: `navigate('/shop?filter=sale')` (`import { navigate } from 'pragma'`). - Full page load: ``. Links with `target` or `download` also bypass the router. - Never use `