# Getting Started

Elements is the full stack for building web apps; no other tools are required.
It includes the build tooling, package installer, test runner, job runner, and
hot program runner, plus an application framework (`@elements/app`) with its own
reactive, server-rendered html language. Deploy to any Ubuntu Linux box over
SSH; Elements handles load balancing and SSL automatically.

This is the getting-started guide. It covers the whole toolkit and app
framework end to end and is enough for a human or an agent to become
productive. Dive into any topic with `elements man <topic>` (for example
`elements man build`). Fuzzy-search everything with
`elements man -s <words...>`.

**Scaffold with `elements create`; don't hand-author files a generator
can make.** Use `elements create page/template/migration/job/email` to
add resources: the generators write the correct files and wire imports
that resolve, and page scaffolds surface the exact route line to register,
so the tool owns the output. Edit the generated files afterward;
hand-author only when no generator fits.
Commands under [Scaffolding](#scaffolding).

## The Build Loop

The basic workflow, especially for an agent, is:

1. Edit and save a file.
2. Run `elements build -json` to check for errors.
3. Correct each error and re-run `elements build -json` until it comes
   back empty.

A long-running project server runs in the background per project (lazy-started,
idle-shuts-down). Everything goes through it: installer, build, test, jobs,
deploy. `elements` commands connect as clients and all see the same state.
It rebuilds continuously on file changes, so `elements build -json` just queries
the current state and returns instantly. Save and check the build often.

`-json` is the structured-output flag across the `elements` command
surface (`build`, `test`, `deploy`, …): it writes JSON to stdout and
exits. Leave it off for plain text. The command then runs as a TUI that
adapts to pipes and agent shells automatically.

A build does everything required to get the app release-ready: install, parse,
compile, resolve, emit, test, release. There is no separate install, migrate, or
test step. Individual commands still exist for specific actions
(`elements install @elements/app`, `elements test -json`).

Every `elements` command supports `-h`/`--help` with a self-contained help
screen. Read the whole thing. See `elements man cli` for the command surface.

When you change UI, verify it renders. A green build means the code compiles,
not that the page looks right. If the app is running (the user starts it
with `elements start`, serving http://localhost:4000) and a Chromium-based
browser is installed (Chrome, Edge, or Chromium), screenshot the route headless
and read the image back:

```bash
# macOS Chrome; Windows: chrome.exe/msedge.exe, Linux: google-chrome, same flags.
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
  --headless=new --disable-gpu --hide-scrollbars --window-size=1200,900 \
  --screenshot=/tmp/page.png "http://localhost:4000/your-route"
```

Open the PNG and check layout, spacing, and that design-system classes render
right. Do this whenever you touch a template or stylesheet.

## Create and Run an App

```bash
elements create myapp
cd myapp
code .                          # open the project in your editor
elements create page pricing    # scaffold a page; prints the route line to add
elements start
```

In development, `elements start` runs the user's server and opens the browser to
the app at http://localhost:4000, switching to an error view if there are any
build errors. The user runs `elements start`; agents should not start the
application. They query `elements build -json` instead.

In VS Code or Cursor, the Elements extension adds an "Elements: New Project"
command to the command palette. It scaffolds the project, opens it in the
current window, and drops you into a terminal ready to run `elements start`.

There is nothing else to install. Elements bundles Postgres and manages
a local database cluster for you (see
[Database and Migrations](#database-and-migrations) below), so a freshly
created app builds and runs with no external services.

## Upgrading Elements

Run `elements upgrade` weekly. The tooling always produces a runnable
app; runtime packages like `@elements/app` follow semver, so upgrade
them more conservatively as time permits. Release notes:
[The Feed](https://elements.dev/feed).

## Project Layout

The first file you likely want to edit is `app/pages/home/template.html`, the
page the user has open in their browser.

```
.elements/               # private build/server state; do not read, write, or search here
AGENTS.md                # agent instructions (this getting-started guide)
index.ts                 # app entry: creates the App, registers routes, starts the server
worker.ts                # services setup for job and test worker processes
config.jsoc              # dependencies, the import map, and app config
package.lock             # resolved dependency lockfile (generated; don't edit by hand)
config/
  env/
    development.env      # committed; dev-safe values
    production.env       # gitignored; production secrets
app/
  pages/
    home/
      index.ts           # route handler
      template.html      # page markup and inline TypeScript
      style.css          # page styles
      test.ts            # page tests
      services.ts        # per-page rpc + shared interfaces (add by hand as the page grows)
    errors/
      not-found/         # 404 page
      unhandled/         # 500 page
  shared/
    templates/           # reusable templates (layout, etc.)
    services/            # cross-page rpc, LiveTables, channels
    styles/
      page.css           # site-wide page baseline (imports @elements/style)
      email.css          # site-wide email baseline
      vars.css           # design-token overrides
    assets/              # favicons, images
  jobs/                  # background jobs
  emails/                # email templates
  migrations/            # generated migration files
  types/
    session.d.ts         # SessionData augmentation (types session.get())
node_modules/
```

There is no root `package.json` or `tsconfig.json`. Dependencies, the import
map, and TypeScript options all live in `config.jsoc`, and the resolved
dependency set is written to `package.lock` (don't edit it by hand). Some
folders (`app/jobs/`, `app/emails/`, `app/shared/services/`,
`app/migrations/`) are created as you need them.

Hidden folders at the project root (anything starting with `.`, like
`.elements/`, `.git/`, `.claude/`) are not part of your source tree. Don't
grep, glob, or otherwise search inside them. Ripgrep and editor search already
skip hidden folders by default; if you shell out to `grep -r` or `find`, pass
`--exclude-dir=.elements` (grep) or `-not -path '*/.elements/*'` (find).

### The Entry Point

`index.ts` at the project root constructs the `App`, registers routes, and
starts the server:

```typescript
import { App } from "@elements/app";
import config from "#config";
import home from "#app/pages/home";

const app = new App();

app.route("/", home);

app.start(config);
```

`worker.ts` brings up the shared services (the database pool, email) that job
and test worker processes need, so `sql()`, `tx()`, and `email()` work inside
jobs and tests the same way they do in an `@rpc` handler. Delete it if your app
has no jobs and no database-touching tests.

## At a Glance

A small real-time comment app. Most of Elements in one place: html
templates, a route, a migration, and a `LiveTable`.

**index.ts**
```typescript
import { App } from "@elements/app";
import config from "#config";
import home from "#app/pages/home";

const app = new App();

app.route("/", home);

app.start(config);
```

**app/pages/home/models.ts**
```typescript
export interface Comment {
  id: string;
  text: string;
  selected?: boolean;
}
```

**app/migrations/20260509120000-add-comments-table.migration.sql**

Generated by
`elements create migration "add comments table" -tables=comments`. The
`-tables` flag scaffolds the canonical baseline (`id`, `createdAt`,
`updatedAt`, and the `touchUpdatedAt` trigger) for each named table. Pass
`-tables=comments,users` to scaffold several at once.

```sql
create or replace function touchUpdatedAt()
returns trigger
language plpgsql
as $$
begin
  new.updatedAt = now();
  return new;
end;
$$;

create table comments (
  id uuid primary key default uuidGenerateV7(),
  text text not null,
  createdAt timestamptz not null default now(),
  updatedAt timestamptz not null default now()
);

create trigger commentsTouchUpdatedAt
  before update on comments
  for each row execute function touchUpdatedAt();
```

`id` is UUIDv7: time-sortable, so newer rows sort after older ones without a
separate timestamp index. Columns are camelCase in the migration. Elements
converts to snake_case at the database boundary and back to camelCase on
results.

Save the file and the project server applies the migration to the
development database. Edit the file (add a column, an index, a
constraint) and the project server rolls back and re-applies. Once a
migration has run on staging or production it's frozen and never runs
again. Agents don't run `elements db migrate` or touch the database
directly.

**app/pages/home/index.ts**
```typescript
import { Request, Response, LiveTable } from "@elements/app";
import { Comment } from "./models";
import html from "./template";

// LiveTable for the `comments` table, inferred from the variable name.
// Wires up select/insert/update/delete rpc and optimistic browser-side
// mutations. `realtime: true` opts into the Postgres NOTIFY/LISTEN
// broadcast so every watching browser sees new rows live; leave it off
// for a snapshot read.
const comments = new LiveTable<Comment>({
  realtime: true,
});

export default function route(req: Request, res: Response) {
  return new html({
    comments,
    mode: req.params.mode ?? "light",
  });
}
```

**app/pages/home/template.html**
```html
import { Layout } from "#app/shared/templates/layout";
import { Comment } from "./models";
import { LiveTable } from "@elements/app";
import "./style.css";

// event handlers

function onAddComment(form: { text: string }, comments: LiveTable<Comment>) {
  comments.insert({ text: form.text }, () => form.text = "");
}

// templates

<html (comments: LiveTable<Comment>, mode: string = "dark") class="home">
  <Layout mode={mode}>
    <CommentList>
      <CommentItem e:for={comment of comments} {comment} />
    </CommentList>
    <CommentAdd {comments} />
  </Layout>
</html>

<CommentList>
  <ul class="comment-list">
    <slot/>
  </ul>
</CommentList>

<CommentItem (comment: Comment)>
  <li tabindex={0}
      class={["comment-item", comment.selected && "comment-selected"]}
      onfocus={() => comment.selected = true}
      onblur={() => comment.selected = false}>
    {comment.text}
  </li>
</CommentItem>

<CommentAdd (comments: LiveTable<Comment>, private form: { text: string } = { text: "" })>
  <form class="comment-add" onsubmit={() => onAddComment(form, comments)}>
    <input value={form.text} placeholder="Write a comment..." />
    <button type="submit">Post</button>
  </form>
</CommentAdd>
```

This one example covers: `App` and `app.route()`, a migration with
`id`/camelCase/trigger, a page route handler returning `new html({...})`,
a `LiveTable` with select/insert/update/delete and realtime, template
parameters with `private` and defaults, sub-templates and `<slot/>`,
`e:for` (keyed by `id`), event handlers, two-way form binding with
`value=`, reactive class arrays, and lifecycle-style reactivity via
mutating `comment.selected`.

## More Patterns

Things the example above doesn't show. Each subsection points to its topic for
the full story.

### Rpc

Use `/** @rpc */` to make a function callable from the browser. The compiler
rewrites browser call sites into network requests and removes the body from the
browser bundle. Call them like normal functions: no `await`, no `async`, no
fetch. Arguments and return types are checked end-to-end.

```typescript
// app/pages/home/services.ts
import { sql, ValidationError } from "@elements/app";
import { Comment } from "./models";

/** @rpc */
export function searchComments(query: string): Comment[] {
  if (query.length < 2) throw new ValidationError("query too short");
  return sql<Comment>(`
    select * from comments
    where text ilike ${"%" + query + "%"}
    order by createdAt desc limit 20
  `).all();
}
```

`@rpc` is the boundary between browser-reachable and server-only code. Once
execution crosses into an rpc, anywhere downstream (the rpc body, helpers it
calls, helpers those call) can call `sql()`, `tx()`, `session.login()` freely.
Browser-reachable code that calls them is a compile error pointing at the call
site.

Rpc go in `services.ts` next to a page, or in `app/shared/services/<topic>.ts`
for cross-page use. Never in a page's `index.ts`. Full topic:
`elements man rpc`.

### Sql and Transactions

```typescript
import { sql, tx } from "@elements/app";

let user = sql<User>(`select * from users where id = ${id}`).first();
let users = sql<User>(`select * from users where active = ${true}`);
for (let u of users) { /* ... */ }

tx(() => {
  let u = sql<User>(`insert into users (name) values (${name}) returning *`).firstOrThrow("insert returned no row");
  sql(`insert into auditLog (event, userId) values ('user_created', ${u.id})`);
});
```

`${value}` interpolations auto-extract as parameterized arguments at
build time; SQL injection is impossible by construction. `sql<T>(...)`
returns a `SqlResult<T>`: `.all()` for the array, `.first()` for
`T | undefined`, `.firstOrThrow(msg)` for a required row. `tx(fn)`
commits on return, rolls back on throw. Every `sql()` inside joins the
same connection. Full topic: `elements man database`.

### Auth, Errors, Validation

```typescript
import { session, AuthError, NotFoundError, ForbiddenError, ValidationError } from "@elements/app";

session.isLoggedInOrThrow();                                        // throws AuthError if not logged in
if (!isAdmin(session.getOrThrow("userId"))) throw new ForbiddenError();

throw new NotFoundError(`room ${id} not found`);                    // 404
throw new ForbiddenError();                                         // 403
throw new ValidationError("qty must be positive");                  // 422, single rule
throw new ValidationError({ email: ["must be a valid email"] });    // 422, per-field
```

`AppError` subclasses are `safe = true`: their messages reach the browser.
Internal errors are wrapped in `ServerError` before being sent.

- `AuthError` (401): unauthenticated
- `ForbiddenError` (403): authenticated but not permitted
- `NotFoundError` (404): resource missing
- `ValidationError` (422): invalid input (string or `FieldErrors<T>` map)
- `NotAcceptableError` (406): request body unparseable
- `ScopeMismatchError` (400): LiveTable scope mismatch
- `ServerError` (500): safe wrapper for internal errors

Errors thrown from an `@rpc` surface in the browser as the same class. Catch
with `instanceof` in a `try`/`catch` around the call site. `validate()` does not
exist. Throw `ValidationError` directly. Full topic: `elements man rpc`.

### Session

The current user's session. Available everywhere on the server and in the
browser. Read methods are reactive in the browser; a template that reads
`session.isLoggedIn()` updates when the user logs in or out.

```typescript
import { session } from "@elements/app";

session.login({ userId, userName });    // server-only
session.logout();                       // server-only
session.isLoggedIn();                   // boolean. reactive in browser.
session.get("userId");                  // SessionData["userId"] | undefined. reactive.
session.getOrThrow("userId");           // same, but throws if absent.
```

```html
<nav>
  <a e:if={session.isLoggedIn()} href="/account">{session.get("userName") ?? "account"}</a>
  <a e:else href="/login">log in</a>
</nav>
```

Session values are typed through the `SessionData` interface. Declare the keys
your app stores in `app/types/session.d.ts`:

```typescript
declare module "@elements/app" {
  interface SessionData {
    userId: string;
    userName: string;
    role: "admin" | "user";
  }
}

export {};
```

`session.get(key)` returns `SessionData[key] | undefined`; `getOrThrow(key)`
throws when the key is absent. There is no `getUserId()` / `getUserName()`; read
`session.get("userId")`. A logged-out visitor has no session at all (no row, no
token, no cookie), so identity is login state, not an anonymous id. Full topic:
`elements man session`.

### Sync-style and Async

Elements primitives (`sql`, `tx`, `@rpc`, `Channel`, `LiveTable`,
`session`) are written sync-style. The compiler rewrites each call to
its async variant (`sql` → `await sqlAsync`) and propagates
`async`/`await` up the call stack automatically, including across
function-expression arguments to schedulers (`setTimeout`,
`addEventListener`).

For third-party libraries that don't participate (fetch, Stripe SDK,
navigator.clipboard), declare your function `async` and `await` those calls
directly. The build leaves your manual `async`/`await` alone. For explicit
promise control (e.g. `Promise.all`), import the `xAsync` variant (`sqlAsync`,
`txAsync`, etc.).

### Channels

Typed pub/sub over Postgres `NOTIFY`/`LISTEN`. `LiveTable` uses `Channel` under
the hood; use `Channel` directly when you want raw pub/sub without table
semantics (push notifications, presence, side-channel events).

```typescript
import { Channel, session } from "@elements/app";

interface Alert { userId: string; level: "info" | "warning"; text: string; }

const alerts = new Channel<Alert>("alerts");

export default function route(req: Request, res: Response) {
  return new html({
    alerts: alerts.listen({ filter: (a) => a.userId === session.getOrThrow("userId") }),
  });
}

/** @rpc */
export function postAlert(text: string) {
  alerts.notify({ userId: session.getOrThrow("userId"), level: "info", text });
}
```

`listen()` returns a subscribed listener. Pass it to a template or return it
from an `@rpc`; the browser receives a live, subscribed handle. Full topic:
`elements man channel`.

### Routes

Url patterns are declared explicitly in `index.ts`, not file-based. Folder names
under `app/pages/` are labels.

```typescript
import { App } from "@elements/app";
import config from "#config";
import home from "#app/pages/home";
import roomsShow from "#app/pages/rooms-show";
import apiRouter from "#app/api";

const app = new App();

app.route("/", home);
app.route("/rooms/:id", roomsShow);
app.route("/api", apiRouter);                                     // mount a sub-router
app.route("/api/rooms", () => sql(`select id, name from rooms`)); // data route

app.start(config);
```

URL patterns use the URLPattern standard. Dynamic segments: `:name`. A page
route returns `new html({...})`. A data route returns serializable data
(Elements json), or writes to `res` directly with `res.write` / `res.end`.
`AppError` subclasses work the same in routes and `@rpc`. A `LiveTable` or
listener returned from a route or rpc arrives in the browser as a live,
subscribed handle.

Fetch initial page data inside the route, not from the browser via `@rpc` after
the page loads. Full topic: `elements man router`.

### Jobs and Cron

```typescript
// app/jobs/send-welcome.ts
import { Job, email } from "@elements/app";
import { WelcomeEmail } from "#app/emails/welcome";

/** @job */
export class SendWelcomeJob extends Job<{ to: string }> {
  static maxAttempts = 5;
  run() {
    email({ to: this.fields.to, subject: "welcome", body: new WelcomeEmail() });
  }
}
```

```typescript
// index.ts
app.cron("every 5m", "rank posts", () => new RankPostsJob().schedule());
app.cron("every day at 2am", "archive", () => new ArchiveOldRowsJob().schedule());
```

`.schedule()` inside `tx()` joins the surrounding transaction. The job becomes
visible only after commit. The project server runs the worker; jobs are stored
in Postgres. One machine runs each cron tick (Postgres-arbitrated leader
election). Keep cron callbacks small; enqueue and let the worker do the work.
Use `/** @job */` and suffix the class name with `Job`. Full topic:
`elements man jobs`.

### Tests

Tests run as part of every build; failures show up alongside compile errors.
Each `test()` body runs inside a Postgres transaction that rolls back at the
end, so writes never pollute the test database.

```typescript
// app/lib/users.test.ts
import { test, assert, equal, sql } from "@elements/app";

test("users", () => {
  test("create", () => {
    let user = sql<User>(`insert into users (name) values ('alice') returning *`).firstOrThrow("insert returned no row");
    equal(user.name, "alice");
  });

  test("does not see the previous test's row", () => {
    let count = sql<{ n: number }>(`select count(*) as n from users`).firstOrThrow();
    equal(count.n, 0);
  });
});
```

Files: `test.ts` or `<name>.test.ts`, anywhere in the tree. Run
`elements test -json` to query state. `test()` calls nest for grouping.
Assertions: `assert`, `equal`, `errorf`, `fatalf`. Full topic:
`elements man tests`.

### Config

`config.jsoc` is evaluated at build time. JSOC is JSON with comments, unquoted
keys, trailing commas, and an `env(...)` function. Missing required env vars or
wrong types fail the build, not the deploy.

```jsoc
{
  database: {
    name: "my_app",
    host: env("DB_HOST", "127.0.0.1"),     // default when unset
    port: env("DB_PORT", 5433),            // default when unset
  },
  session: {
    expires: "30d",                        // sliding expiry
  },
}
```

Env vars come from the OS at startup. After startup, edit
`config/env/<env>.env` for hot reload. Full topic: `elements man config`.

### Css Style

Every page imports `app/shared/styles/page.css`, which imports
`@elements/style`, a built-in, CSS-only design system: design tokens for
colors, spacing, type, and radii, a reset, finished styles for bare HTML
elements, and classes for buttons, forms, cards, callouts, pills, and
tabs.

Before writing CSS for anything `@elements/style` already covers, read
`elements man style` and use what it gives you. Bare elements are already
styled. A `<button>` is a finished secondary button; `<input>`, `<form>`,
headings, links, tables, and code all look right with no classes. Vary a button
with `is-` modifiers rather than a new class: `is-primary`, `is-ghost`,
`is-danger` for intent, `is-sm`/`is-lg` for size, `is-block` for full width.
Each owns one axis, and they combine in any order. Write custom CSS only for
layout the system doesn't provide (page composition, positioning, spacing
between sections). Maintain the Elements style language in new apps unless the
user directs otherwise. Full topic: `elements man @elements/style` (or
`elements man style`).

## Database and Migrations

The database is Postgres, and Elements bundles it. There is nothing to install.
A per-machine `elements-machine` daemon runs a single Postgres cluster shared by
all your projects; it is created automatically, kept healthy, and listens on
loopback port `5433` (not the usual `5432`, so it never collides with a Postgres
you already run). Data lives under `~/elements/db` in development.

On the first build, the project connects to the daemon, the cluster is ensured
ready, and your project's app database and test database are created
automatically. The names derive from the project directory (`MyApp` →
`my_app` and `my_app_test`), or from `database.name` in `config.jsoc`.

Migrations are SQL files under `app/migrations/`, and applying them is part of
the build loop. Save a migration and Elements applies it, to the test database
first, then the app database. In development you can edit an applied migration
and Elements rolls it back and replays it. On a deploy machine a migration runs
exactly once and is frozen thereafter.

To point at a remote or hosted Postgres instead of the bundled cluster, set
`DB_HOST` (and the other `DB_*` values) in the active environment. Full topics:
`elements man database`, `elements man migrations`.

## Gotchas

Everything below trips up agents. Each is a compile error, a silent bug, or a
productivity drain.

**Build and CLI**
- Before implementing against a subsystem you haven't verified this session,
  read `elements man <topic>`. Don't infer an API from nearby files.
- Run `elements build -json` after every edit. The project server is always
  building; `-json` just queries state.
- `-json` gives structured output on `elements build`, `elements test`,
  `elements deploy`, and every other command that supports it. Leave it off for
  plain text; commands adapt automatically to non-terminal interfaces.
- `elements db -sql "<stmt>"` runs a single sql statement and exits (same as
  `psql -c`). Available on `db` and `db shell`. Use this instead of an
  interactive `psql` session when scripting or driving from an agent.
- Migrations are hot in development, frozen in production. Don't run
  `elements db migrate` or touch the database directly.
- Don't install packages in test projects unless explicitly asked.

**Scaffolding**
- Scaffold with `elements create` (see the directive at the top of this guide);
  a hand-authored page is easy to leave half-wired.
- `elements create page <name>` scaffolds a page (`index.ts` route,
  `template.html`, `style.css`, `test.ts`) and prints the `import` and
  `app.route(...)` lines to add to `index.ts`. `-url /path` overrides the url.
- `elements create template <name>` scaffolds a template
  (`elements create template ui/card`); `-params='title, icon'` declares its
  parameters.
- `elements create migration <name> -tables=users,posts` scaffolds a migration
  with the standard columns and trigger.
- `elements create job <name>` scaffolds a background job;
  `elements create email <name>` scaffolds an email.
- After scaffolding, edit the generated files. Don't recreate their structure by
  hand.

**Project structure**
- Routes are declared in `index.ts`, not file-based. Folder names under
  `app/pages/` are labels, not URLs.
- A scaffolded page has `index.ts` (route only) and `template.html` (template +
  event handlers + inline rpc). As a page grows, move its `@rpc` functions and
  shared interfaces into a hand-authored `services.ts` sibling. Never put `@rpc`
  in `index.ts`.
- Cross-page services and templates live under `app/shared/`.
- Import app source with the `#app/...` map (`#app/pages/...`,
  `#app/shared/...`), never `../../`. `#config` imports config.
- Import a page's template extensionless: `import html from "./template"`.
- Hidden folders (`.elements/`, `.git/`, `.claude/`) are not source. Never read,
  write, or search them.
- Use kebab-case for all directories and filenames.

**Html templates**
- TypeScript goes outside template declarations or inside `{}` expressions. No
  `<script>` tags.
- Parameters live on the root tag only. `<div (form: Form)>` inside a template
  is invalid.
- `<html>` is the default-export page; `html` is a reserved name. Other
  top-level tags are named templates.
- `e:for` keys by the `id` field. Provide one or the runtime warns and falls
  back to object identity.
- Conditional directives: `e:for`, `e:if`/`e:elseif`/`e:else`,
  `e:switch`/`e:case`/`e:default`.
- Read and write data, not the DOM. `el.value = "..."` fights the runtime; bind
  via `value={form.x}` instead.
- Reference values (objects, arrays) passed to a handler stay reactive when
  mutated. For primitives, either reassign in template scope or pass a callback
  the handler invokes.
- `<form onsubmit={...}>` calls `e.preventDefault()` automatically.
- `{raw(html)}` for unescaped html. Never `el.innerHTML`.
- Class arrays: falsy entries are dropped. `class={["card", active &&
  "active"]}`.
- Lifecycle hooks: `oninit`, `oninsert`, `onremove`. Each receives an event
  object with `event.target` set to the element.
- Event handlers: declare a named function in the same `.html` file; the inline
  arrow just passes template params into it.
- Navigate with `redirect(url)`, not `window.location`. Don't render a
  `session.isLoggedIn()` view on a signin/signup page: login is an `@rpc`, so
  the session flips and repaints before `redirect()` runs. Bounce a signed-in
  visitor in the route via `res.redirect()`.

**Styling (@elements/style)**
- Before styling anything the design system covers (buttons, forms, cards,
  callouts, pills, tabs), read `elements man style` and use it. Don't hand-roll.
- Bare elements are already styled. A `<button>` is a finished button;
  `<input>`, `<form>`, headings, `<a>`, `<table>`, `<code>` need no classes.
- Vary a button with `is-` modifiers, never a new class:
  `is-primary`/`is-ghost`/`is-danger` (intent), `is-sm`/`is-lg` (size),
  `is-block` (full width). Render an `<a>` as a button with
  `class="button is-primary"`.
- Setting padding/border/radius/background on something the system already
  styles means you're rebuilding what exists. Stop and use the class.
- Custom CSS is for layout the system doesn't provide (page composition,
  positioning, section spacing), not for restyling covered elements.

**Database**
- `sql()`, `tx()`, `session.login()`, `session.logout()` are server-only.
  Calling them from browser-reachable code is a compile error pointing at the
  call site.
- `${value}` interpolations are auto-parameterized; SQL injection is impossible
  by construction.
- `sql<T>(...)` returns a `SqlResult<T>`. Use `.all()` for the array, `.first()`
  for `T | undefined`, `.firstOrThrow(msg)` for a required row.
- Nesting `tx()` joins the transaction already in progress. Inner `sql()` calls
  join the outer transaction automatically.
- Write camelCase in SQL. Elements translates at the database boundary;
  snake_case still works if you prefer it.
- `.firstOrThrow("msg")` instead of `.first()` + a manual `NotFoundError` throw.

**LiveTable**
- A LiveTable is snapshot-only by default. Set `realtime: true` (or `'db'`) for
  cross-client live updates; without it, other browsers don't see new rows until
  they reload.
- An optimistic `insert(...)` paints ONLY the object you pass. Include every
  field the template reads, or that cell renders `undefined` until the server
  reconciles.
- Server-generated columns count too. Timestamps (`createdAt default now()`),
  sequence numbers, and trigger-derived values don't exist client-side yet, so
  pass a placeholder: `createdAt: new Date()`. Omit a displayed `createdAt` and
  `new Date(undefined)` renders `Invalid Date` until the broadcast lands.

**Rpc and errors**
- `@rpc` is the boundary. Once across, anywhere downstream can call
  `sql()`/`tx()`/`session` freely.
- Internal errors are wrapped in `ServerError` before reaching the
  client. Throw an `AppError` subclass for client-safe messages.
- `ValidationError(message)` for a single rule;
  `ValidationError(fieldErrors)` for per-field maps. In templates,
  direct-assign: `errors = err.errors;`, not `Object.assign`.
- `validate()` does not exist in `@elements/app`. Throw
  `ValidationError` directly.

**Sync-style**
- Elements primitives are written sync-style. The compiler propagates
  `async`/`await` up the call stack.
- For third-party libraries (fetch, Stripe, navigator.clipboard),
  declare your function `async` and `await` those calls directly. Your
  manual `async`/`await` is left alone.
- Never write `async`/`await` in code that only uses Elements
  primitives. The sync-style transform handles it, and hand-writing it
  fights the compiler.
- The `xAsync` variants (`sqlAsync`, `txAsync`, `insertAsync`, etc.) are
  only for genuine promise control such as `Promise.all` over several
  calls. Do not reach for them to "fix" a call that seems not to work.
  That masks a real bug (often navigating away before a write is sent)
  and breaks sync-style. Diagnose the timing instead.

**Session**
- Read session values with `session.get("userId")` /
  `session.getOrThrow("userId")`; type them via the `SessionData`
  interface. There is no `getUserId()`.
- A logged-out visitor has no session: no row, no token, no cookie.
- Templates that read session methods update automatically when the
  session changes.

**Jobs**
- Use `/** @job */` build tag. `app.job(...)` is not a real API.
- Suffix class names with `Job` (`SendWelcomeJob`), never bare.

**Misc**
- Always use semicolons in TypeScript and JavaScript.
- Spell out environment names (development, production, staging); don't
  abbreviate.
- No decorative section-header or banner comments
  (`// ─── helpers ───`, boxed dividers, ASCII rules). They add
  noise and rot as code moves. A comment explains non-obvious logic,
  it doesn't label a region of the file.

## Deploy

Deploy to any Ubuntu Linux box with SSH access. Elements provisions the machine
on first deploy (installs elements, creates a system user, sets up systemd,
installs the license, configures the load balancer, provisions SSL, and brings
up the bundled Postgres cluster).

Deploys are fast and safe. They run peer-to-peer, your project server talking
directly to the deploy machine's, so only changed files transfer and rebuild: a
cold deploy takes a few seconds, a hot one a few hundred milliseconds when the
server is close. Each machine stages the new release, runs the full build
(compile, tests, migrations), and swaps it in with an atomic rename only after
everything succeeds, so the previous release keeps serving until the new one is
ready and a failed deploy leaves the running app untouched. Any failure (a
compile error, a test failure, a migration failure) stops the release, and the
cutover is coordinated across every machine, so if one fails none cut over and
the whole cluster stays on the current release.

You need SSH access (root or sudo user) and the machine's public and private IP
addresses. Add the machine to `config.jsoc`:

```jsoc
{
  deploy: {
    domain: "example.com",
    ssh: {
      user: "root",
      identityFile: "~/.ssh/id_ed25519",
    },
    env: {
      production: {
        machines: [
          { name: "production1", publicIp: "203.0.113.10", privateIp: "10.0.0.10" },
        ],
      },
    },
  },
}
```

Then:

```
elements deploy             # production by default
elements deploy staging     # named env
elements ssh production      # shell into the first production machine
```

The deploy machine runs the same bundled Postgres cluster as development. The
scaffolded `config.jsoc` defaults `host` to `env("DB_HOST", "127.0.0.1")` and
`production.env` sets `DB_HOST=127.0.0.1`, so a deploy uses the bundled cluster
with no extra setup. Point at a remote database by setting `DB_HOST` (and the
other `DB_*` values) in `production.env`. Local build failures block
deploy. Deploy runs the same build as `elements build`. The `[host]` tag
on a diagnostic identifies which machine the error came from; no
`[host]` means the local machine. Full topic: `elements man deploy`.

## Load Balancing

Every app server runs a built-in load balancer; no separate appliance, no config
file. Each reads the same `config.jsoc` and reloads on new builds. Every machine
knows the others, so any one can front the cluster: point DNS at one or all
public app servers and requests balance round-robin across machines, with
failover when one is unreachable. SSL is issued and renewed through
Let's Encrypt for every configured domain. A static maintenance page
serves only when every machine is down. Full topic: `elements man deploy`.

## Licenses and Purchasing

Elements is licensed per machine. You pay for the tooling and own everything it
produces. The trial is full functionality, no card. A purchase is a subscription
that bundles licenses for the machine you develop from and the machine you
deploy to. For current pricing and terms, see https://elements.dev/pricing.

```
elements purchase
```

After checkout, licenses are delivered automatically. Manual update:
`elements license checkout`.

- Pricing: https://elements.dev/pricing
- Purchase: https://elements.dev/purchase

Full topics: `elements man licenses`, `elements man purchase`.

## Support

- https://elements.dev/feed: HN-style ranked posts from the community
  and the Elements team. Release announcements land here.
- https://elements.dev/issues: bug reporting and tracking. Customers only.
- https://elements.dev/learn: courses, open to the public.
- support@elements.dev: direct support for customers.