# Lith

> Lith is a web language for AI agents: TypeScript + JSX + Prisma-style queries plus the declarations
> `table page api crud layout` and `state`/`effect`/`auth`. One global namespace, server/client split
> inferred, compiles to standard JS/HTML/CSS on Node. Status: v0 specification.

This file holds the language card followed by the full specification.

## Language card

Lith = TypeScript + JSX + Prisma-style queries + the declarations `table page api crud layout` (at line start) and
`state`/`effect`/`auth`. All `.lith` files share one global namespace: never import your own files or Lith names; import
npm packages normally. JS built-ins (`Date`, `Set`, `fetch`, `setTimeout`, regex) work as in TS. Server code needs no
`await` (harmless).

## Tables
```tsx
table Post {
  title: string(1..200)            // refinement: length 1..200, checked on every write
  body: string                     // any text, "" allowed
  slug: string(1..80) unique       // modifiers (unique, index, renamedFrom("old")) go anywhere after the base type
  views: int(0..) = 0              // int(a..b) / number(a..b): value range
  done: boolean = false
  status: "Draft" | "Live" = "Draft"
  due: day | null                  // day = "YYYY-MM-DD" (from <input type="date">); compare with today()
  author: User | null              // reference: field authorId; include: { author: true } loads it
  tags: Tag[]                      // many-to-many (join table is automatic)
  created: Date = now()
}
```
- `id: int` is automatic; never declare it. `T | null` = optional. A new column with a default or `| null` needs no
  migration. To rename a column and keep its data: `unitPriceCents: int(0..) renamedFrom("priceCents")`.
- `table Note own { ... }` adds `owner: User`, fills it on create and limits every query, update and delete to the
  logged-in user's rows (others act as missing; login required). Use it only for private data. Shared rows with an owner
  get `owner: User` plus checks in code. `system(() => ...)` runs code without `own` scoping; it is allowed only in
  `auth(...)` pages/functions, `test` and `seed { }` blocks.
- `User` exists (`email: email unique`, `name: string`, `passwordHash`; `email` = text "@" text "." text). Add columns
  with `table User { role: "Admin" | "Member" = "Member" }`. `passwordHash` never reaches the browser or JSON. Table
  names may be any word (`Image`, `Event`).

## Queries (Prisma Client)
`db.post.findMany findFirst findUnique findUniqueOrThrow count create update delete updateMany deleteMany` with `where
data orderBy skip take include`; operators `equals not in contains startsWith endsWith lt lte gt gte AND OR NOT`
(`contains` and string sorting ignore case). `findUniqueOrThrow` → the row or a 404; `update`/`delete` of a missing row
→ 404. Nulls: `orderBy: [{ done: "asc" }, { due: { sort: "asc", nulls: "last" } }]`. Many-to-many:
`data: { tags: [tagA, tagB] }` sets the list, `where: { tags: { some: { name } } }` filters, `include: { tags: true }`.
A row loaded with `include` has those fields in its type: a `posts: Post[]` prop may read `p.tags` if the page loaded them.

## Pages and layout
```tsx
auth page "/posts/:id/:slug" (id: int, slug: string, q: string = "") {   // path params typed and URL-decoded;
  const post = db.post.findUniqueOrThrow({ where: { id } })            // other params come from the query string
  if (slug !== post.slug) redirect(`/posts/${id}/${post.slug}`, 301)   // default status 303
  return <main><title>{post.title}</title><h1>{post.title}</h1><p>{post.created}</p></main>
}
layout {                                // optional; wraps every page; `children`, `me` and `path` are in scope
  return <html data-theme="system">
    <nav><a href="/" class={path === "/" ? "font-bold" : ""}>Home</a></nav>
    {children}
  </html>
}
```
`auth page` requires login (else redirect to `/login`); `auth(me.role === "Admin") page` also answers 403. `me` is the
logged-in `User` or `null` (`User` under `auth`); `path` is the current URL path. A bad typed path param gives 404. Links
are plain `<a href>`; a search form is `<form method="get">`. A `Date` renders as `2026-10-16 14:05`.
`<html data-theme="light" | "dark" | "system">` in `layout` forces or frees light/dark (built-in styles and Tailwind
`dark:`). Stop anywhere with `redirect(path, status?)`, `notFound()`, `forbidden()`, `unauthorized()`, `fail(...)`.

## Server functions and forms
A top-level function that uses `db`, `me`, `login`/`logout`/`loginWithPassword`/`hashPassword` or `process.env` runs on
the server; the browser calls it automatically. `auth function` requires login (401). Parameters are typed and validated.
```tsx
<form action={addComment}><input type="hidden" name="postId" value={post.id} /><textarea name="body" /><button>Send</button></form>
auth function addComment(postId: int, body: string(1..1000)) {
  if (body.includes("http")) fail({ body: "No links" })      // field message; fail("msg") = form message
  db.comment.create({ data: { postId, body, authorId: me.id } })
}
<button onClick={() => deleteComment(c.id)}>Delete</button>    // in a page a handler is one server-function call;
                                                               // anything else needs a component with `state`
```
- Inputs, textareas, selects and hidden inputs fill parameters by `name`, converted to the parameter type (`int`,
  `number`, checkbox → `boolean`, `type="date"` → `day`, repeated input names → `T[]`). An empty field is `""` for
  `string` and `null` for `T | null`.
- All parameter checks run first, all at once. `email: User.email` reuses a column's type; `email: User.email unique` also checks it is not taken. For your
  own message, type the param loosely (`url: string`) and `fail` in the body.
- On any failure the form re-shows by itself: each field message after its input, other messages at the end, typed values
  kept (not passwords). Nothing to write. Without JS it is a native POST. `fail("Already voted", 409)` sets the
  status (default 400).
- After a server function succeeds, the page re-renders from the server: island props update, `state` is kept and the
  form resets. `redirect` navigates.

## Components and client state
```tsx
function Search(placeholder: string, onPick: (id: int) => void) {   // props are parameters: <Search placeholder="Find" onPick={f} />
  state q = ""
  state hits: Person[] | null = null                // typed state
  const empty = hits !== null && hits.length === 0  // recomputes
  effect(() => {                                    // runs after render and whenever q changes
    if (q === "") { hits = null; return }
    let stale = false
    const timer = setTimeout(async () => {
      const res = await fetch(`/api/people?q=${encodeURIComponent(q)}`)
      if (!stale) hits = await res.json()
    }, 300)
    return () => { stale = true; clearTimeout(timer) }   // cleanup before the next run
  })
  return <div><input value={q} onInput={e => q = e.target.value} placeholder={placeholder} />{empty && <p>No matches</p>}</div>
}
```
No React hooks. A component with `state` runs in the browser too. It cannot read `db` or `me`, so pass rows as props. It
may `fetch` the app's own routes. Server functions called from it are async: `await` them in `try`/`catch` (`e.status`,
`e.message`). A component without `state` renders on the server and may read `db` and `me`. `children: Html` receives
nested JSX. In handlers, `e.target` is the element (`e.target.value`, `e.target.checked`).

## APIs
```tsx
crud "/api/products" Product         // GET list, GET /:id (404 {"error":"not found"}), POST 201, PATCH /:id, DELETE /:id 204
crud "/api/notes" Note: list, get    // only some operations
auth api GET "/api/orders.csv" (from: day | null) {   // params from path, query string or JSON body
  return new Response(csv, { headers: { "Content-Type": "text/csv" } })   // or return a value → JSON 200
}
```
Errors are JSON: 400 `{"error":msg,"field":f}`, 401, 403, 404. `Response.json(v, { status: 201 })` sets a status.

## Auth
`loginWithPassword(email, pw)` → `User | null`, and it starts the session on success. `login(user)`, `logout()`,
`hashPassword(pw)` (scrypt).

## Styling
Plain HTML already looks good (centered `main`, `form` as a column, `li` as a row, no `ul` bullets, styled controls,
tables and links). Add Tailwind via `class` (not `className`, no `style`) only for extras: `flex-row font-bold
text-red-600 text-gray-500 whitespace-pre-wrap grid grid-cols-3 gap-4`. Class strings may be combined (`ok ? "a" : "b"`, `` `p-2 ${x}` ``),
but each class name must appear whole somewhere, never `"bg-" + c`.

## Check and test
`lith check` reports the first error as JSON with a patch. `test("name", () => { ... })` may sit in any file: fresh
database per test, vitest `expect`, `asUser(user, () => ...)`.


# Lith specification (sections 2-10)

## 2. Reference program

The reference program is the first end-to-end acceptance test. It must compile, pass its tests and run unchanged.

```tsx
// app.lith
table Todo own {
  title: string(1..200)
  done: boolean = false
  due: day | null
  created: Date = now()
}

page "/" {
  const todos = db.todo.findMany({ orderBy: [{ done: "asc" }, { due: { sort: "asc", nulls: "last" } }] })
  return <main>
    <h1>Todos for {me.name}</h1>
    <form action={addTodo} class="flex-row">
      <input name="title" /><input name="due" type="date" /><button>Add</button>
    </form>
    <ul>
      {todos.map(t => <li>
        <input type="checkbox" checked={t.done} onChange={() => setDone(t.id, !t.done)} />
        <a href={`/todos/${t.id}/${slug(t.title)}`}>{t.title}</a>
        {!t.done && t.due !== null && t.due < today() && <span class="text-red-600">Overdue</span>}
      </li>)}
    </ul>
    <Counter start={todos.length} />
  </main>
}

page "/todos/:id/:s" (id: int, s: string) {
  const t = db.todo.findUniqueOrThrow({ where: { id } })
  if (s !== slug(t.title)) redirect(`/todos/${id}/${slug(t.title)}`, 301)
  return <main><h1>{t.title}</h1><p>{t.created}</p></main>
}

layout {
  return <html data-theme="system">
    <nav><a href="/" class={path === "/" ? "font-bold" : ""}>Todos</a>{me && <form action={signOut}><button>Log out</button></form>}</nav>
    {children}
  </html>
}

function addTodo(title: string, due: day | null) { db.todo.create({ data: { title, due } }) }
function setDone(id: int, done: boolean) { db.todo.update({ where: { id }, data: { done } }) }
function signOut() { logout(); redirect("/login") }
function slug(s: string) { return s.toLowerCase().replace(/[^a-z0-9]+/g, "-") }

function Counter(start: int) {
  state n = start
  return <button onClick={() => n++}>{n}</button>
}

crud "/api/todos" Todo: list, get

test("adding a todo stores it", () => {
  const u = db.user.create({ data: { email: "a@b.c", name: "A", passwordHash: hashPassword("x") } })
  asUser(u, () => addTodo("milk", null))
  expect(system(() => db.todo.count())).toBe(1)
})
```

What the compiler infers here, with nothing written:
- `addTodo`, `setDone` and `signOut` use `db` or `logout`, so they are server functions, and the page's handlers and
  form become RPC and form posts.
- `slug` is pure and ships wherever it is used.
- `Counter` uses `state`, so it is an island.
- `/todos/:id/:s` has no island and ships 0 kB JS.
- `Todo` is `own`, so every query on it gets `ownerId = :me` and the pages require login.
- The test runs against an in-memory database.

## 3. Lexical structure and grammar

Lith source is the TypeScript 5 TSX grammar (strict) plus a few contextual declarations. Files end in `.lith`. All files
of a project form one module with one global namespace. Importing an own file or a Lith name is E0206 (safe patch:
delete). npm packages are imported with ES `import`. Declaration keywords are keywords only at the start of a top-level
statement, so `page`, `table`, `state`, `path` and `day` remain valid names elsewhere (an r0 measurement: a reserved
`page` keyword made a task unfixable).

```
decl       = tableDecl | pageDecl | apiDecl | crudDecl | layoutDecl | seedDecl | authFn | tsTopLevel
seedDecl   = "seed" block                                                // runs once on an empty database
tableDecl  = "table" Ident ["own"] "{" { field (NEWLINE | ",") } "}"
field      = ident ":" ktype { modifier } ["=" expr] { modifier }
modifier   = "unique" | "index" | "renamedFrom" "(" STRING ")"
ktype      = base [range] { "|" base } [ "|" "null" ] | Ident "[]"          // Ident[] = many-to-many
range      = "(" [num] ".." [num] ")"
base       = "string" | "int" | "number" | "boolean" | "Date" | "day" | "email" | Ident | STRING
pageDecl   = [auth] "page" STRING [params] block
apiDecl    = [auth] "api" METHOD STRING [params] block                     // METHOD = GET POST PUT PATCH DELETE
crudDecl   = [auth] "crud" STRING Ident [":" op { "," op }]                // op = list get create update delete
layoutDecl = "layout" block                                                // children, me, path in scope
authFn     = auth "function" ...                                           // TS function declaration
auth       = "auth" ["(" expr ")"]
params     = "(" [ param { "," param } ] ")"      param = ident ":" ktype ["=" expr]
```

Inside function bodies, `state ident [":" type] "=" expr` is a statement (components only). Refinement types
(`string(1..200)`) are allowed in every parameter annotation.

**Modifier order is free** (`string(1..32) unique | null` and `string(1..32) | null unique` both parse). In r3, 5 of 8
blind testers wrote `unique` before `| null`, and three designs rejected it. `lith fmt` rewrites to the canonical
order: type, `| null`, modifiers, default. Empty `()` after a page path is accepted and removed by `fmt`.

**Restricted TypeScript.** No `enum`, `namespace`, decorators, `var`, class components, or `==`/`!=` (E0110, with a
safe patch to `===`/`!==`); no `any` written in source (E0302); no `className` (E0605, safe patch: `class`); no `style`
attribute (E0606, a patch to Tailwind classes when they map).

**Formatter canon.** Prettier style (no semicolons, double quotes, width 110, no trailing commas) extended to the
declarations. `fmt(fmt(x)) == fmt(x)`.

## 4. Types and standard library

TypeScript strict mode, with these Lith types:

| Type | Meaning |
| --- | --- |
| `int`, `number` | integer / float JS numbers; `int` is checked at every boundary |
| `string(a..b)`, `int(a..b)`, `number(a..b)` | refinements (length / value); assignable to the base type |
| `email` | string matching text `@` text `.` text, with no spaces |
| `day` | `"YYYY-MM-DD"` string; `today()` gives the current UTC day; compares and sorts as a string |
| `Date` | JS Date (timestamp); JSON is ISO 8601; renders in JSX as `YYYY-MM-DD HH:mm` |
| `T \| null` | absence (no `undefined` in table or param types) |
| `"A" \| "B"` | string-literal union (no `enum`) |
| table `T` | row type with implicit `id: int`; a reference field `author: User` adds `authorId: int`; relation fields (`author`, `tags`) are in the type only where loaded with `include` (6.2) |
| `Html` | JSX value; the type of `children` |

**Annotations at boundaries only:** parameters of top-level functions, components, pages and apis, and table fields.
Everything else is inferred.

**Boundary validation.** Page params, api params and bodies, server-function arguments from forms and RPC, and every
`create`/`update` are checked against the declared types, refinements included. All failures are collected at once
(section 6.6). `p: Table.field` reuses that column's type and refinement; `p: Table.field unique` also checks that
no row has the value yet (opt-in, so login and profile-edit lookups do not fail with "already exists").

**Standard library (global, never imported).**
- `db` (section 6.2).
- `me`, `path`.
- `login`, `logout`, `loginWithPassword`, `hashPassword`.
- `redirect`, `notFound`, `forbidden`, `unauthorized`, `fail`.
- `today`, `now`, `system`.
- Tests: `test`, `expect`, `asUser`.
- `state`/`effect` for components.
- The web platform: `Response`, `Request`, `fetch`, `URL`, `setTimeout`.

## 5. Effects and the server/client split

Effects are inferred, never written, and shown by `lith sig`.

| Effect | Introduced by | Tier |
| --- | --- | --- |
| `db` | any `db.*` call, `system` | server |
| `auth` | `me`, `login`, `logout`, `loginWithPassword`, `hashPassword` | server |
| `env` | `process.env.X` (except `PUBLIC_*`, inlined) | server |
| `client` | `state`, `effect`, `window`, `document`, `localStorage` | client |

1. `page`, `api`, `crud`, `layout` and tests run on the server, as does any component that is not an island. Such a
   component may read `db` and `me`.
2. A top-level function with a server effect is a **server function**. On the server it is a plain synchronous call. A
   server function that client code references (a form `action`, a server-markup `on*` handler, or an island) gets an
   endpoint and becomes a typed RPC (`POST /_lith/rpc/<id>`, JSON array of arguments, validated), returning a Promise in
   the browser. Server functions that only server code calls get no endpoint.
3. A component that declares `state` or calls `effect` is an **island**: rendered on the server, then hydrated.
   Components rendered inside an island are client code too. Reading `db` or `me` in island render is E0401 (message:
   load in the page and pass as a prop). Islands may `fetch` the app's own routes and any URL.
4. In server markup (a page, layout or component without `state`), an `on*` handler must be a single call to one server
   function. Its arguments may be any expressions; they are evaluated on the server at render (`!t.done` is fine). It
   compiles to a delegated listener that posts those values, and no island is needed. Any other handler body needs a
   component with `state` (E0406). This rule is on the card.
5. Function props may pass between components on the same tier. A function cannot cross from server to client (E0403),
   except a server function, which becomes an RPC. Rows crossing to the client never include `passwordHash`.
6. **Revalidation.** After a browser-invoked server function succeeds, the runtime re-fetches the current page and
   morphs the DOM. Islands receive the new props from the server render, island state is preserved by position and
   key, and the submitted form resets (the final blind test had 2 of 2 testers relying on props updating without the
   card saying so). After a failed **form**
   submission (enhanced or not), the page re-renders with messages and kept values (6.6). After a failed `on*` or island
   call nothing re-renders, and the Promise rejects (see 7).
7. **Await.** Server code is written synchronously; `await` is accepted and ignored there. The compiler lowers every `db`
   call to a suspension point, so async drivers (edge targets) need no source change. In islands, server calls and
   `fetch` are Promises. A Promise used as a condition or as a value (`if (save())`, `x = save()`) is E0311 (safe
   patch: `await`). A server-call Promise that is discarded without a handler is W0311 (warning). In that case the island's
   error boundary handles a rejection: it restores the island's state to what it was before the handler ran and shows
   the default inline message "Couldn't save — try again". `await` in `try`/`catch` stays the recommended form for custom
   messages.

## 6. Declare layer

### 6.1 table

- Fields are `name: type [modifiers] [= default]`, separated by newlines or commas. Defaults are literals, `now()`
  (Date) and `today()` (day). A field is required on create when it is non-null and has no default.
- `id: int` is implicit; declaring it is E0508 (safe patch: delete).
- `unique` adds a unique index and allows several nulls. `index` adds an index. `renamedFrom("old")` keeps data across a
  rename.
- **Many-to-many:** `tags: Tag[]` creates a hidden join table `PostTag(postId, tagId)`. Writes take
  `data: { tags: Tag[] | int[] }` and replace the set. Reads use `include: { tags: true }`. Filters use
  `where: { tags: { some: { … } } }`.
- **`User`** is predeclared `{ email: email unique, name: string, passwordHash: string }`. `table User {…}` adds columns
  (redeclaring a built-in is E0509). `passwordHash` is never serialized to JSON, RPC or island props.
- **`own`:** `table Note own {…}` adds `owner: User`. Every read appends `ownerId = :me` (joins included),
  `update`/`delete` match only owned rows, and `create` fills `ownerId` and rejects it in `data`. Without a login any
  access is `unauthorized()`, which redirects pages to `/login` and gives 401 elsewhere. `system(() => …)` runs a block
  without `own` scoping. It is allowed only inside `test` blocks, `seed { … }` blocks (run once on an empty database)
  and functions or pages declared `auth(pred)`; anywhere else it is error E0510. `lith check --list-system` lists every
  use. For shared rows with an owner, use a plain `owner: User` reference and check it in
  code. Lith therefore has one declarative row rule (`own`) plus code checks (`auth(pred)`, `forbidden()`), so the
  authorization axis is `both`. General `allow` rules were measured and not adopted (`provenance.md`).
- **Table names** live in the Lith module scope and shadow browser globals (`Image`, `Event`). Naming a table `Request`
  or `Response` is W0207.

### 6.2 Queries (`db`)

`db.<lowerCamel table>` exposes this Prisma Client subset:

| Call | Returns |
| --- | --- |
| `findMany({ where, orderBy, skip, take, include, select })` | `T[]` |
| `findFirst(args)` / `findUnique({ where })` | `T \| null` |
| `findUniqueOrThrow({ where })` | `T`, or throws `notFound()` |
| `count({ where })` | `int` |
| `create({ data })` / `update({ where, data })` | `T` (update on a missing or not-owned row: `notFound()`) |
| `delete({ where })` | `T` (missing: `notFound()`) |
| `updateMany` / `deleteMany` | `{ count }` |

Where operators are `equals not in contains startsWith endsWith lt lte gt gte AND OR NOT` and relation filters
`some/none/every`. `contains`/`startsWith`/`endsWith` ignore case, and string columns sort `NOCASE`. `orderBy` entries
take `"asc" | "desc"` or `{ sort, nulls: "first" | "last" }`. `findUnique`/`update`/`delete` may add non-unique
filters beside `id` (Prisma ≥ 5), e.g. `update({ where: { id, archived: false } })`. A `NaN` in `where` matches
nothing.

**Included relations in types.** A query with `include: { tags: true, author: true }` returns rows of type
`Post & { tags: Tag[], author: User | null }`. A parameter typed with the table type (`posts: Post[]`) may read a
relation field (`p.tags`). The compiler then requires every call site to pass rows loaded with that `include`; a call
site whose rows lack it is E0513 (patch: add the field to the query's `include`, safe when the rows come from one
query). The final blind test had 2 of 2 testers type an island prop `Card[]` and read `c.labels`; this rule makes that
program correct as written. Every query compiles at build time to one parameterized SQL string. Unknown fields or operators are E0502
(nearest-name patch).

### 6.3 Migrations

`db/schema.lock.json` records the applied schema. `lith dev` applies additive changes automatically: new tables,
nullable or defaulted columns, and renames declared with `renamedFrom`. `lith migrate` writes
`db/migrations/NNNN.sql`. Drops and type changes need `--allow-destructive` (E0505, with a patch that suggests
`renamedFrom` when one column disappears and one appears).

### 6.4 page and layout

- `page "/a/:id/:b" (id: int, b: string, q: string = "", n: int = 1) { … }`. Path params must be declared; they are
  URL-decoded and coerced, and a value that does not parse gives 404. Other params come from the query string and need
  a default or `| null` (E0601). Pages are GET only and return JSX, a `Response`, or throw a helper.
- `auth page` requires a login (else 303 to `/login`, configurable). `auth(pred) page` also requires `pred`, else 403.
  `me: User` inside.
- `layout { … }` (at most one) wraps every page, including error pages. In scope: `children: Html`, `me`, and
  `path: string` (the request path without the query string; r3 measured a 4/4-design failure without it). If it returns
  `<html …>`, those attributes go on the document's `<html>`.
- `<title>` and `<meta>` anywhere move into `<head>`. Literal `href`s that start with `/` are checked against declared
  routes (E0602).

### 6.5 api and crud

- `api METHOD "/path" (params) { … }`. Params come from the path, the query string or the JSON body and are validated
  (400 `{"error", "field"}`). A plain value returns 200 JSON (rows: all columns, `Date` as ISO); a `Response` passes
  through (`Response.json(v, { status })`, `new Response(csv, { headers })`). Literal segments may contain dots
  (`/api/orders.csv`).
- `crud "/api/x" T [: ops]` generates:
  - list: a JSON array in `id` order;
  - get: the row, or 404 `{"error":"not found"}`;
  - create: 201 with the row, or 400 `{"error","field"}`;
  - update: PATCH, partial, same validation, or 404;
  - delete: 204, or 404.

  `own` scoping and `auth` apply (401 logged out).
- Non-GET routes require a same-origin `Origin` or an `Authorization` header.

### 6.6 Server functions, forms and failure

- **Forms.** `<form action={fn}>` posts inputs, textareas, selects and hidden inputs by `name` to `fn`'s parameters,
  converted by type:
  - `string`;
  - `int`/`number` (`Number`, else a validation error);
  - checkbox → `boolean`;
  - `type="date"` → `day`;
  - unions from `select`;
  - repeated names → `T[]`.

  An empty field is `""` for `string` and `null` for `T | null`. It works without JS (POST + 303) and is enhanced with
  JS. Static forms whose input names match no parameter are E0607.
- **Validation order.** Parameter types and refinements, including `unique` on `Table.field unique` params, are checked
  together first. Then the body runs; `fail(msg)` or `fail({ field: msg })` adds messages. A second argument sets the
  HTTP status, `fail("Already voted", 409)` (default 400, any 4xx except 401/403/404, which have their own helpers;
  else E0612). Use it for refusals that are not about one input (already voted, closed, over a limit). The final blind
  test had 2 of 2 testers write exactly this form unprompted, and before it a server function could not refuse with
  409. To give a field a custom
  message for every bad value, type it loosely and check it in the body (this closes the r2 Ward silent where a
  refinement pre-empted the custom message).
- **Re-show.** On failure the page re-renders with typed values kept (passwords cleared). Each field message is placed
  after the input with that `name`, and the rest go at the end of the form.
- **Helpers** (type `never`): `redirect(path, status = 303)` (301/302/303/307/308, else E0612), `notFound()`,
  `forbidden()`, `unauthorized()`, `fail(msg | { field: msg }, status = 400)`.

| Error | Page / form (no JS) | api / crud | RPC from browser |
| --- | --- | --- | --- |
| `redirect` | that status | that status | client navigates |
| `notFound` / `OrThrow` miss | 404 page | 404 `{"error":"not found"}` | rejects, `status` 404 |
| `unauthorized`, `auth`, `own` without login | 303 `/login` | 401 | rejects, 401 |
| `forbidden`, `auth(pred)` false | 403 page | 403 `{"error":"forbidden"}` | rejects, 403 |
| validation / `fail` | form re-show, status 400 or `fail`'s | 400 or `fail`'s status, `{"error","field"}` | rejects with that status, `.message`, `.fields` |
| other / network | 500 page | 500 | rejects, 500 / `status` 0 |

### 6.7 Sessions

A signed cookie (HMAC-SHA256 with `LITH_SECRET`; HttpOnly, SameSite=Lax, Secure in production) holds the user id. `me`
is loaded once per request. `loginWithPassword(email, pw)` returns `User | null`: it finds the user, verifies scrypt in
constant time (hashing a dummy for unknown emails) and starts the session. `login(user)`, `logout()`,
`hashPassword(pw)`. Forms and RPCs carry a per-session CSRF token and require a same-origin `Origin`.

### 6.8 test

`test("name", () => { … })` may appear in any file. The semantics are vitest in-source testing with vitest `expect`.
Tests are stripped from builds and hidden by `lith sig`. Effects are handled by the runner:
- `db`: a fresh in-memory SQLite per test, with migrations applied;
- `asUser(user, fn)`: runs `fn` with a session;
- `now()`/`today()`: frozen at 2026-01-01T00:00:00Z;
- network: fails unless mocked with `vi.fn`.

Tests for changed files run on `lith check`.

## 7. Components, state, markup and styles

- **Components** are UpperCamel functions whose parameters are the props: `function Row(task: Task, onDone: (id: int)
  => void)`, used as `<Row task={t} onDone={f} />`. A parameter `children: Html` receives nested JSX. Measured: −5
  tokens per component against React's destructured object, with 0 errors in 48 blind programs (Kern, Ward, Dex).
- **State.** `state x[: T] = init` is a signal owned by the instance. Reading subscribes and assigning (`x = …`, `x++`)
  updates. `const` values computed from state re-evaluate when it changes; the compiler tracks reads. `effect(() => {
  …; return cleanup })` runs after mount and after any change to state it reads while its body runs; reads inside
  callbacks it schedules (`setTimeout`, `fetch(…).then`) do not subscribe. The returned function runs before
  the next run and on unmount (r3: 2 Kern testers wrote exactly this and lost a silent bug when it was ignored). React
  hooks are E0411 (patch to `state`/`effect`).
- **Events.** `onClick onInput onChange onSubmit onKeyDown onFocus onBlur`. The event is the DOM event with `target` and
  `currentTarget` typed as the element, so `e.target.value` and `e.target.checked` type-check (r3 H22: all 8
  testers across the four designs wrote `e.target.value`; it failed type-checking only where React's `EventTarget`
  typing applied).
- **Markup.** JSX with `class`; keys are automatic for rows, otherwise `key=`. `null`, `false` and `""` render nothing.
  Text is escaped. `<style>`/`<script>` children must be strings and are emitted raw. Lowercase tags are checked against
  HTML5.
- **Styles.** Tailwind v3 classes in `class`, compiled at build time. An unknown class is warning W0604 (safe patch:
  nearest). Class strings may be combined from literals: ternaries, template strings with literal parts, and helper
  functions that return literals. Every class name must appear as a whole literal somewhere, because Tailwind scans
  source. A name built from non-literal parts (`"bg-" + color`) is E0605. A classless base stylesheet (~2 kB, Tailwind `base`
  layer) styles bare HTML:
  - a centered `main` (42rem, padding 2rem, spaced children) and sized headings;
  - `form` as a column (`flex-row` makes a row) and `li` as a centered row;
  - `ul` without bullets;
  - styled `button input textarea select table a`.
- **Theme.** All base colours are CSS variables. `<html data-theme="light" | "dark" | "system">` forces or frees them.
  Tailwind `dark:` uses the same selector (`darkMode: ["variant", "&:is([data-theme=dark] *),
  &:is([data-theme=system] *):where(@media (prefers-color-scheme: dark))"]`). With no `data-theme`, the scheme follows
  `prefers-color-scheme`.

## 8. Code generation, runtimes and compatibility

**Pipeline.** Each stage is an incremental query keyed by file:

1. lex and parse (TSX + declarations) into a lossless syntax tree;
2. resolve names across the single module;
3. type-check (TS semantics plus refinements), then infer effects per call-graph SCC;
4. assign tiers and mark RPC sites and islands;
5. lower to an IR with `db` calls as suspension points;
6. emit JS per tier, SQL per query, CSS, and source maps.

Output is deterministic.

- **Server** (`dist/server/index.mjs`, Node 22+ ESM): `node:http` with a radix router, streaming HTML rendering (JSX
  compiled to string concatenation), cookie sessions, form/JSON parsing, RPC dispatch, hashed static assets with
  immutable caching, and gzip/brotli. SQLite runs in-process through `node:sqlite`, with statements prepared once.
  There are no framework layers, so p95 stays within 10% of plain `node:http`.
- **Client** (`@lith/client`, ≤ 10 kB gz): compiled signals, DOM binding by cloning `<template>`s, delegated events,
  island hydration, page morph for revalidation, the RPC client and form enhancement. A page without islands or
  handlers ships no script.
- **CSS:** one file (Tailwind output + base layer + theme variables).

**Compatibility (hard requirement).**

| Requirement | How | Token cost in source |
| --- | --- | --- |
| Standard JS/HTML/CSS | ES2022 modules, HTML5, one CSS file, source maps | 0 |
| npm packages | ES `import x from "pkg"` in any file; types from the package's `.d.ts`; bundled by esbuild/swc. A package that imports `node:*` is server-only (tier inference treats it as a server effect) | one line per package, as in TS |
| Used from TypeScript | `lith build --lib` emits `.js` + `.d.ts` for every top-level function and table type, and typed `fetch` wrappers for server functions (`dist/rpc.ts`). The generated `lith-env.d.ts` lets `tsc`/editors type-check Lith globals | 0 |
| Standard hosts | `--target node` (any Node host, Docker), `--target edge` (a `fetch(Request): Response` handler for Cloudflare Workers, Deno or Vercel Edge, with D1/libSQL through the async `db` lowering), `--target static` (prerendered pages, no server functions) | 0 |
| Standard HTTP/JSON | Routes use WHATWG `Request`/`Response`, JSON bodies and the `{error, field}` shape. RPC is documented JSON over POST, so any client can call it. Forms are urlencoded | 0 |

**Read cost.** Files have no imports, directives or validation boilerplate. `lith sig` prints about 10 tokens per
declaration, for example:

```
table Note own { body string(1..5000), created Date=now() }
page /notes                  [server] calls addNote
function addNote(body: string)   [server, rpc] db
crud /api/notes Note: list
```

## 9. CLI and JSON contracts

`lith` is one static binary. With `--json`, machine output goes to stdout. Exit code 0 means ok, 1 means diagnostics or
failing tests, 2 means a usage error.

| Command | Does |
| --- | --- |
| `lith new <name>` | scaffold `app.lith`, `public/`, `lith.json` |
| `lith check [--all] [--list-system]` | parse, types, effects, schema, routes, classes, tests; first diagnostic unless `--all` |
| `lith fmt [--check]` | canonical formatting |
| `lith test [filter]` | tests only |
| `lith migrate [--dry-run] [--allow-destructive]` | write and apply migrations |
| `lith build [--target node\|edge\|static] [--lib]` | production output |
| `lith dev [--port 3000]` | watch, rebuild, auto-migrate additive changes, overlay with the first diagnostic |
| `lith sig [path]` | signatures with effects and tier |
| `lith ctx "<task>" --budget N` | minimal relevant context (BM25 over names, routes and strings; bodies of top hits, `sig` lines for references) |

`check --json` output:

```json
{ "ok": false, "elapsedMs": 41, "diagnostics": [{ "code": "E0311", "severity": "error", "file": "app.lith",
  "span": { "line": 18, "col": 5, "endLine": 18, "endCol": 21 }, "message": "Promise discarded; add await",
  "patch": { "span": { "line": 18, "col": 5, "endLine": 18, "endCol": 5 }, "insert": "await ", "safe": true } }],
  "tests": { "passed": 12, "failed": [] }, "remaining": 3 }
```

Only the first diagnostic in dependency order is shown; `remaining` counts the rest.

## 10. Error code catalog

| Code | Meaning | Patch (safe?) |
| --- | --- | --- |
| E0101 | Declaration syntax error (expected set listed) | single expected token (no) |
| E0110 | `==` / `!=` | `===` / `!==` (yes) |
| E0201 | Unknown name | nearest in scope (if unique) |
| E0206 | Import of an own file or a Lith name | delete (yes) |
| E0300 | TypeScript type error (wraps `tsCode`) | TS quick-fix (no) |
| E0302 | `any` written in source | — |
| E0311 | Promise used as a condition or value | `await` (yes) |
| E0401 | `db`/`me` in island render | — (load in page, pass as prop) |
| E0403 | Non-serializable value crosses tiers | — |
| E0404 | Server env var reached from client | — |
| E0406 | Server-markup handler is not a single server-function call | — (make a component with `state`) |
| E0510 | `system` outside `test`, `seed` or `auth(pred)` | — |
| E0513 | A function reads a relation field (`p.tags`) but a caller passes rows loaded without that `include` | add it to the query's `include` (yes, when the rows come from one query) |
| E0411 | React hook | `state`/`effect` (yes for `useState`) |
| E0502 | Unknown field, operator or relation in a query | nearest (if unique) |
| E0503 | `create` missing a required column | — |
| E0505 | Destructive migration without flag | `renamedFrom("old")` when one column was swapped (no) |
| E0508 | `id` declared | delete (yes) |
| E0509 | Built-in `User` column redeclared | delete (yes) |
| E0601 | Query param without default or `\| null` | add `\| null` (yes) |
| E0602 | `href` to an unknown route | nearest route (no) |
| E0605 | Class name built from non-literal parts, or `className` | literal names / `class` (yes for `className`) |
| E0606 | `style` attribute | Tailwind classes when they map (if every rule maps) |
| E0607 | Form input name matches no parameter, or a non-string `<style>` child | nearest param (no) |
| E0612 | Bad `redirect` or `fail` status | nearest (no) |
| E0701 | Test failed (shows both sides) | — |
| W0207 | Table named `Request`/`Response` | — |
| W0504 | Pending migration | run `lith migrate` |
| W0311 | Server-call Promise discarded (error boundary will revert) | `await` in `try` (no) |
| W0604 | Unknown Tailwind class | nearest (yes) |

Every code has `docs/errors/<code>.md` with one failing example and its fix. The safe-patch set is tuned from benchmark
transcripts.