# Norns docs — full corpus

> Documentation for the Norns platform: SvelteKit with Pug + Civet, the norns runtime, norns-ui and norns-tron.


---

<!-- https://norns-docs.humansynthesis.ai/norns-app -->

# norns-app

> The starter template — a single page that exercises the whole runtime in about sixty lines you can read in one sitting and rewrite in two.

```sh
bun create human-synthesis/norns-app my-app
cd my-app
bun install
bun run dev          # http://localhost:5173
```

`bun create` clones the public repository `human-synthesis/norns-app` and runs `bun install`, which resolves `@human-synthesis/norns`, `norns-core` (through norns), `norns-ui`, `norns-tron`, the SvelteKit and Svelte peers, Tailwind v4 and valibot from npm. You never see the framework's forks.

## Stack

Svelte 5, SvelteKit 2, Pug, Civet, Tailwind CSS v4, Vite, bun, the three Norns packages, and valibot for validation.

## Commands

```sh
bun run dev          # dev server
bun run build        # production build
bun run preview      # preview the build
bun run lint         # norns lint: Civet + Pug pitfall scan
bun run check        # norns check: preprocess + compile every .n / .c through svelte.config.js
bun test             # tests/*.test.js — the feature through the DI container
bun run build        # full Vite build
bunx norns diag src/lib/norns/messages/server/service.c
bun run check:svelte # svelte-check over the .js / .ts / .svelte parts only
```

Run them in that order before calling a change done; `norns check`, not `svelte-check`, is the pass signal for Norns code. The template ships one bun test as the pattern for testing a feature through the container (a small bun plugin in `tests/civet-loader.js` compiles `.c` files on import). The framework's own suites live in the framework repositories.

- [Walkthrough](/norns-app/walkthrough) — every file in the template and what to do next.

---

<!-- https://norns-docs.humansynthesis.ai/norns-core -->

# norns-core

> The Svelte preprocessor behind .n files — Civet scripts, Pug templates, +if and +snippet chains, class-shorthand rewriting and source-mapped errors.

`@human-synthesis/norns-core` is the syntax layer. It is a dependency of [norns](/norns) and most apps never install it directly; the pages here explain what happens to a `.n` file between your editor and the Svelte compiler.

## What it does

- `.n` files default `<script>` to `lang="civet"` and `<template>` to `lang="pug"`. Write neither attribute and it just works.
- Top-level Pug is wrapped in `<template lang="pug">` automatically, and a trailing `<script>` or `<style>` without its closing tag is closed for you.
- `<script lang="civet">` blocks compile to JavaScript through [@danielx/civet](https://civet.dev) before svelte-preprocess sees them.
- `+if` / `+elseif` / `+else` chains and `+snippet('name', args)` blocks are rewritten to Svelte block syntax.
- Pug class shorthand is rewritten so Tailwind variants (`.hover:bg-x`), slashes (`.bg-white/40`) and fractions (`.gap-2.5`) work without escaping.
- Pug and Civet errors are mapped back to `file:line:column` in the source you wrote.

## Standalone use

```sh
bun add -D @human-synthesis/norns-core svelte
```

```js
// svelte.config.js
import { nornsPreprocess } from '@human-synthesis/norns-core/preprocess';

export default {
  extensions: ['.svelte', '.n'],
  preprocess: nornsPreprocess()
};
```

That gives you `.n` components in any Svelte 5 project. Auto-imports, the `.c` module extension and the runtime live in [norns](/norns), which needs Vite plugin hooks the preprocessor does not have.

The repository `human-synthesis/norns-core` is a fork of `sveltejs/svelte` in which `packages/svelte` is an untouched mirror and `packages/norns-core` is this package. See the [fork policy](/reference/upstream-policy).

---

<!-- https://norns-docs.humansynthesis.ai/norns-demo -->

# norns-demo

> The reference app — notes on Cloudflare D1, tic-tac-toe with stores, the norns-ui showcase, each example also written in vanilla SvelteKit for comparison.

```sh
git clone https://github.com/human-synthesis/norns-demo
cd norns-demo
bun install
bun run db:migrate   # apply migrations to the local D1 under .wrangler/state/
bun run dev          # http://localhost:5173
```

The dev server gets `event.platform.env.DB` from adapter-cloudflare's platform proxy, which reads `wrangler.toml` and keeps a local D1 under `.wrangler/state/`. No Cloudflare account is needed to run locally. Production runs at `norns-demo.humansynthesis.ai`.

## What it shows

- [Notes](/norns-demo/notes) — D1, dynamic routes, form actions, valibot, error pages, SSR `load`, the DI container, the facade boundary, the page wrappers, and a TRON endpoint in schema mode.
- [Tic-tac-toe](/norns-demo/tic-tac-toe) — multi-component composition, `$props` with defaults, Svelte stores, `$state` / `$effect`, scoped CSS and a small AI heuristic.
- [UI showcase](/norns-demo/ui-showcase) — every norns-ui component with live props.
- [Deploy](/norns-demo/deploy) — the Workers + D1 setup and the GitHub Actions workflow.

Each example exists twice, once in Norns (`src/routes/examples/norns/`, `src/lib/norns/`) and once in vanilla SvelteKit (`src/routes/examples/svelte/`, `src/lib/svelte/`), so the two can be compared line for line. Do not "convert" the vanilla side; it is the control group.

## Commands

```sh
bun run lint             # norns lint
bun run check            # norns check — every .n / .c / .svelte through svelte.config.js
bun run check:svelte     # svelte-check over the vanilla .svelte / .ts side
bun run build
bun run migrate create notes/<name>      # scaffold a migration (norns CLI)
bun run db:migrate / db:migrate:remote   # apply with wrangler, local / production
```

The repo has no test suite of its own; it is exercised through the dev server and the build.

---

<!-- https://norns-docs.humansynthesis.ai/norns-tron -->

# norns-tron

> TRON serialization for the Norns ecosystem — a token-efficient, faster-than-JSON wire format for APIs and LLM-facing output, with zero runtime dependencies.

TRON cuts **11–61% of tokens** compared to JSON and, used correctly, beats `JSON.parse` / `JSON.stringify` on decode, encode and round-trip. Plain JSON is valid TRON, so adoption is progressive and rollback is one line.

The encoder/decoder core is absorbed from the `apitron` research library; this package adds the Norns glue as subpath exports:

| Import | Contents |
|---|---|
| `@human-synthesis/norns-tron` | `encode`, `decode`, `defineSchema`, `createRegistry`, columnar helpers, WASM controls |
| `@human-synthesis/norns-tron/server` | `tronSerializer()` for `route()` and `boot()` |
| `@human-synthesis/norns-tron/client` | `api` / `createApi()` fetch wrapper that speaks TRON |
| `@human-synthesis/norns-tron/valibot` | derive wire schemas from valibot schemas |

```sh
bun add @human-synthesis/norns-tron
```

`valibot` is an optional peer, needed only for the `/valibot` subpath.

## Where to start

- [Turn it on app-wide](/norns-tron/guide/enable) — one option in `boot()`, content-negotiated.
- [Call it from the client](/norns-tron/guide/client)
- [Schema mode](/norns-tron/guide/schema-mode) — the fastest path for internal endpoints.
- [Semantics and limits](/norns-tron/guide/limits)
- [Performance guide](/norns-tron/guide/performance)

---

<!-- https://norns-docs.humansynthesis.ai/norns-ui -->

# norns-ui

> Component library for the Norns ecosystem — Pug + Civet components on Tailwind v4, headless behaviors on @floating-ui/dom, Iconify icons, theming tokens and motion.

`@human-synthesis/norns-ui` ships around seventy components written as `.n` files, so they compile through the same pipeline as your app and can be shadowed by dropping a file with the same name into your project.

## Stack

- Svelte 5 components and runes, Pug templates, Civet scripts.
- Tailwind CSS v4 as a hard peer dependency; tokens are a Tailwind `@theme` block.
- `@floating-ui/dom` for every overlay (Popover, Dropdown, Tooltip, ContextMenu, pickers).
- In-tree headless behaviors: focus trap, scroll lock, click outside, escape, portal, roving tabindex.
- Iconify with the Lucide set bundled.
- `tailwind-merge` behind `cn()` for class deduplication.
- `@human-synthesis/norns` as a peer, for `nornsAutoImport` and `presetUI()`.

## What is in the box

| Tier | Components |
|---|---|
| Atoms (CSS only) | `.btn`, `.input`, `.field`, `.form`, `.checkbox`, `.radio`, `.switch`, `.card`, `.surface-elevated`, `.badge`, `.chip`, `.avatar`, `.skeleton`, `.progress`, `.norns-header`, `.hero`, `.stepper`, `.breadcrumbs`, `.pagination`, `.accordion`, `.carousel`, with variants and sizes |
| Forms | `Btn`, `Form`, `Field`, `FieldGroup`, `Input`, `Textarea`, `Select`, `Checkbox`, `Radio`, `Switch`, `NumberInput`, `OtpField`, `TagsInput`, `Autocomplete`, `MultiSelect`, `DatePicker`, `DateRangePicker`, `TimePicker`, `Calendar`, `ColorPicker`, `Uploader` |
| Behavior | `Dialog`, `Sheet`, `Popover`, `Dropdown`, `Tooltip`, `Tabs`, `Accordion`, `ContextMenu`, `Collapsible`, `ScrollArea` |
| Display | `Card`, `Surface`, `Window`, `Banner`, `Badge`, `Chip`, `Avatar`, `AvatarGroup`, `Skeleton`, `Progress`, `ProgressCircular`, `Icon`, `Image`, `Audio`, `Video`, `Separator`, `GradientText`, `Timeline`, `DataTable`, `Tree` |
| Composite | `Header`, `HeroBanner`, `Stepper`, `Breadcrumbs`, `Pagination`, `Carousel`, `Toolbar`, `ButtonGroup`, `ToggleButton`, `ToggleButtonGroup`, `HierarchicalMenu`, `MegaMenu`, `CopyButton`, `ThemeToggler`, `ShinyButton`, `RippleButton` |
| Toast | `ToastProvider` plus `toast()` / `notify()` / `dismiss()` |
| Motion (opt-in) | `AnimatedNumber`, `GradientBackground`, `LiquidButton`, `Reveal`, `Sparkles` |

Every component accepts `class` and merges it with `cn()`. The [component reference](/norns-ui/reference/components) lists each one with its props; the live gallery is `/examples/ui` in [norns-demo](/norns-demo/ui-showcase).

---

<!-- https://norns-docs.humansynthesis.ai/norns -->

# norns

> SvelteKit preconfigured for Pug + Civet, plus a small opinionated runtime — feature folders, a DI container, page and route wrappers with valibot validation, migrations, and the norns CLI.

`@human-synthesis/norns` is the umbrella package. Install it and you get four things:

- **The build pipeline.** `nornsConfig()` for `svelte.config.js`, `nornsCivetPlugin()` for Vite, and the `.n` / `.c` file extensions wired into SvelteKit. The preprocessor that turns Pug + Civet into Svelte lives in [norns-core](/norns-core) and is pulled in as a dependency.
- **Auto-imports.** Framework helpers, your own components, UI-library presets and (opt-in) your project's named exports resolve by name, so a `.n` file that uses `<Btn>` or `onMount` needs no import line.
- **The runtime.** `boot()`, a DI container with per-request scopes, `page.load` / `page.actions` / `route()` wrappers that validate input with valibot, and database driver factories.
- **The CLI.** `norns dev | build | preview | migrate | lint | check | diag`.

## Where to start

- New project: [Install](/norns/getting-started/install), or just run `bun create human-synthesis/norns-app my-app`.
- Existing SvelteKit project: [svelte.config.js](/norns/config/svelte-config) and the [Vite plugin](/norns/config/vite-plugin).
- Building features: [Feature folders](/norns/getting-started/feature-folders), then the [Runtime](/norns/runtime) section.
- Something does not compile: [Pitfalls](/norns/pitfalls) and [check and diag](/norns/cli/check-and-diag).

## Relationship to SvelteKit and Svelte

Norns does not replace the framework you run. `@sveltejs/kit` and `svelte` are peer dependencies that come from the official packages; SvelteKit routing, `load`, form actions, adapters and everything else in the [SvelteKit docs](https://svelte.dev/docs/kit) apply unchanged. Norns adds file extensions, a preprocessor, an auto-importer and an opinionated server layer on top.

The `human-synthesis/norns` repository is a fork of `sveltejs/kit` only so that `packages/norns` can be developed next to an untouched `packages/kit`. Nothing in the upstream packages is modified; see the [fork and release policy](/reference/upstream-policy).

---

<!-- https://norns-docs.humansynthesis.ai/reference -->

# Reference

> Cross-cutting pages — the package matrix, a glossary, the fork and release policy, and how this site is built.

- [Packages](/reference/packages) — every repository, what it publishes, and how it is consumed.
- [Glossary](/reference/glossary)
- [Fork and release policy](/reference/upstream-policy)
- [About this site](/reference/this-site) — how the docs are built and how to contribute a page.

---

<!-- https://norns-docs.humansynthesis.ai/norns-ui/getting-started -->

# Getting started

> Install, wire the preset, add the styles, and set up dark mode and icons.

- [Install](/norns-ui/getting-started/install)
- [Setup](/norns-ui/getting-started/setup) — `presetUI()` in both config files and the CSS import.
- [Dark mode](/norns-ui/getting-started/dark-mode)
- [Icons](/norns-ui/getting-started/icons)

---

<!-- https://norns-docs.humansynthesis.ai/norns/getting-started -->

# Getting started

> Install norns, learn the project layout, and build your first feature folder.

- [Install](/norns/getting-started/install) — the starter template or a manual setup in an existing SvelteKit app.
- [Project structure](/norns/getting-started/project-structure) — what goes where, and which SvelteKit files can be written in Civet.
- [Feature folders](/norns/getting-started/feature-folders) — the unit of modularity: module, repo, service, facade, schema.

---

<!-- https://norns-docs.humansynthesis.ai/norns-core/guide -->

# Guide

> How a .n file is put together and what each preprocessing step does.

- [The .n file](/norns-core/guide/the-n-file) — structure, defaults, auto-wrapping.
- [Civet script](/norns-core/guide/civet-script) — the Civet you write in `<script>` and `.c` files, and what it emits.
- [Pug template](/norns-core/guide/pug-template) — tags, attributes, Svelte expressions, components.
- [Control flow](/norns-core/guide/control-flow) — `+if`, `+each`, `+snippet` and rendering snippets.
- [Class shorthand](/norns-core/guide/class-shorthand) — the rewriter and Tailwind extraction.
- [Error mapping](/norns-core/guide/error-mapping) — how Pug and Civet errors find the right line.

---

<!-- https://norns-docs.humansynthesis.ai/norns-tron/guide -->

# Guide

> Enabling TRON, calling it, schema mode, limits and performance.

- [Turn it on app-wide](/norns-tron/guide/enable)
- [Call it from the client](/norns-tron/guide/client)
- [Schema mode](/norns-tron/guide/schema-mode)
- [Semantics and limits](/norns-tron/guide/limits)
- [Performance guide](/norns-tron/guide/performance)

---

<!-- https://norns-docs.humansynthesis.ai/norns-demo/notes -->

# Notes

> A CRUD feature on Cloudflare D1 with form actions, a dynamic route, an error page and a schema-mode TRON endpoint.

## The feature folder

`src/lib/norns/notes/`:

- `shared/schema.c` defines `createNoteSchema` (title trimmed and required, optional body), `updateNoteSchema`, the row shape `noteSchema`, and `noteWire`, the TRON schema derived from it with `tronSchemaFromValibot(noteSchema, { id: 'notes.v1', path: '$.data' })`.
- `server/module.c` binds `db` transiently from the request's `event.platform.env.DB`, then `notes.repo` and `notes.service` transiently on top of it (see [Cloudflare D1](/norns/data/cloudflare-d1) for the code).
- `server/repo.c` is hand-written SQL on the raw D1 API: `list`, `get`, `create`, `update`, `remove`, every call async.
- `server/service.c` is a thin `NotesService` with typed `Note` and `NoteInput`.
- `server/public.c` exports `notes(container)` with the same five operations.

`migrations/notes/20260508_001_init.sql` creates the table.

## Routes

`src/routes/examples/norns/notes/+page.server.c`:

```civet
export load := page.load
	handler: async ({ container }) =>
		notes: await notes(container).list()

export actions := page.actions
	create:
		input: createNoteSchema
		run: async ({ input, container }) =>
			id := await notes(container).create input
			throw redirect 303, `/examples/norns/notes/${id}`
```

`+page.n` renders the create form with `Form`, `Field`, `Input`, `Textarea` and `Btn`, echoing `form?.values` back into the inputs, and lists notes as `Card` links.

`[id]/+page.server.c` loads one note (throwing `error 404` when missing) and defines `update` and `delete` actions that read `event.params.id`. `[id]/+error.n` renders the 404.

## The API endpoint

`src/routes/api/notes/+server.c` demonstrates schema-preloaded TRON:

```civet
export GET := route
	serializer: tronSerializer({ schema: noteWire })
	handler: async ({ container }) =>
		data: await notes(container).list()

export POST := route
	input: createNoteSchema
	handler: async ({ input, container }) =>
		id: await notes(container).create input
```

Both ends import the same compiled contract, so no shape declarations travel and the response is tagged `#notes.v1`. Clients without `Accept: application/tron` still get JSON.

## The vanilla twin

`src/lib/svelte/notes/` (`db.ts`, `repo.ts`, `service.ts`, `schema.ts`) and `src/routes/examples/svelte/notes/` implement the same feature in `.svelte` / `.ts` without the runtime, for a side-by-side comparison.

---

<!-- https://norns-docs.humansynthesis.ai/reference/packages -->

# Packages

> Every repository in the Norns platform, what it publishes, and how it is consumed.

| Package / repository | Contents | Distribution |
|---|---|---|
| `@human-synthesis/norns` (`human-synthesis/norns`, `packages/norns`) | config, Civet Vite plugin, auto-imports, server runtime, migrations, CLI | npm |
| `@human-synthesis/norns-core` (`human-synthesis/norns-core`, `packages/norns-core`) | the Pug + Civet preprocessor | npm |
| `@human-synthesis/norns-ui` (`human-synthesis/norns-ui`) | component library | npm |
| `@human-synthesis/norns-tron` (`human-synthesis/norns-tron`) | TRON wire format | npm |
| `norns-app` | starter template | `bun create human-synthesis/norns-app` |
| `norns-demo` | reference app | `git clone`; hosted at `norns-demo.humansynthesis.ai` |
| `norns-docs` | this site | `git clone`; hosted at `norns-docs.humansynthesis.ai` |

The installed versions this site was built against are shown on the [landing page](/). Releases are manual and user-gated; see the [policy](/reference/upstream-policy).

## Peer relationships

- `norns` depends on `norns-core` and on `@danielx/civet`; it has `@sveltejs/kit`, `svelte` and `vite` as peers.
- `norns-ui` has `norns`, `norns-core`, `svelte` and `tailwindcss` as peers (the first two non-optional, because its components need the Norns pipeline to compile).
- `norns-tron` has no runtime dependencies and `valibot` as an optional peer.

## Test suites

Every framework repository has a `bun test` suite: norns (boot, container and scopes, wrappers, validation, migrate, drivers, Vite plugin, auto-import), norns-core (preprocessor, vetted subset and known traps), norns-ui (`presetUI()` map, `cn()`), norns-tron (encode/decode round-trips, server and client glue, valibot derivation). norns-app carries one bun test that exercises its feature through the DI container; norns-demo has no suite. Every app is verified through `norns lint`, `norns check` and the build.

---

<!-- https://norns-docs.humansynthesis.ai/norns-app/walkthrough -->

# Walkthrough

> Every file in the starter, the messages feature, and how to go further.

```
src/
  hooks.server.c                # boots the norns runtime, eager-loads feature modules
  app.css, app.html             # global styles + html shell
  routes/
    +layout.c, +layout.n        # app shell with the <Header>
    +page.n                     # one-page demo: form + list of messages
    +page.server.c              # load() + send action wired to the messages feature
    api/messages/+server.c      # GET + POST endpoint through route()
  lib/
    components/Header.n         # site nav
    norns/
      messages/                 # one feature folder, in-memory store
        server/{module,repo,service,public}.c
        shared/schema.c         # valibot schema shared by the form action and the API route
tests/
  civet-loader.js               # bun plugin: compiles .c on import so tests can load feature code
  messages.test.js              # the feature through the DI container
wrangler.toml                   # commented Cloudflare stub
```

## The starter feature

`src/lib/norns/messages/` is a complete feature folder in miniature. The [feature folders](/norns/getting-started/feature-folders) page prints it in full.

- `repo.c` is an in-memory `list` / `add`. Replace it with a database when you need persistence; only `list` and `add` are called from outside.
- `service.c` holds the business logic and takes the validated input type from `shared/schema.c`.
- `module.c` registers `messages.repo` and `messages.service` on the container. It is the only file `boot()` reaches.
- `public.c` exports `messages(container)`, the facade routes import.

## How it is wired

- `src/routes/+page.server.c` calls `messages(container).list()` in `page.load` and `messages(container).create(input)` in the `send` action, validated by `sendMessageSchema`.
- `src/routes/+page.n` renders `<Form>` from norns-ui. Field errors arrive through the `form` prop and the Form context; no per-page boilerplate.
- `src/routes/api/messages/+server.c` exposes the same operations as `GET` and `POST` through `route()`. Responses are content-negotiated by the TRON serializer installed in `hooks.server.c`, so `Accept: application/tron` gets TRON and everyone else gets JSON.
- `hooks.server.c` globs `./lib/norns/*/server/module.c` and calls `boot({ features, serializer: tronSerializer() })`.

## The test

`tests/messages.test.js` boots the feature's module into a fresh container and calls the facade, the same way a route would. That is the pattern for every feature: no HTTP, no mocks of the framework, just the container. Bun loads the Civet files through the small plugin in `tests/civet-loader.js`.

## Going further

Delete `src/lib/norns/messages/` and `src/routes/+page.*` and rewrite, or copy the feature folder for each new domain. That is the whole pattern.

For persistence, bind a database in one module (see [Drivers](/norns/data/drivers) or [Cloudflare D1](/norns/data/cloudflare-d1)) and resolve it from the repo. For a fuller example with SQLite, dynamic routes, error pages and a component-heavy page, clone [norns-demo](/norns-demo).

The repository's `CLAUDE.md` carries the [pitfalls](/norns/pitfalls) and the [verification order](/norns/pitfalls/verification) so coding agents working in your app follow them.

---

<!-- https://norns-docs.humansynthesis.ai/norns-ui/getting-started/install -->

# Install

> Add norns-ui to a Norns app.

```sh
bun add -D @human-synthesis/norns-ui
```

Peer dependencies: `@human-synthesis/norns`, `@human-synthesis/norns-core`, `svelte` 5 and `tailwindcss` 4. The starter template has all of them.

The package ships source, not a build: `.n` components under `src/components/`, motion components under `src/motion/`, behaviors and helpers under `src/lib/`, styles under `src/styles/`, and hand-rolled `.d.ts` shims under `src/types/`. Because the components are Civet + Pug, they require the Norns preprocess pipeline in the consuming app; that is why `@human-synthesis/norns` is a non-optional peer.

## Subpath exports

| Import | Contents |
|---|---|
| `@human-synthesis/norns-ui` | barrel of every component and helper |
| `@human-synthesis/norns-ui/auto-import` | `presetUI()` |
| `@human-synthesis/norns-ui/components/<Name>.n` | one component (what the preset maps to) |
| `@human-synthesis/norns-ui/motion` | motion components, opt-in |
| `@human-synthesis/norns-ui/behaviors` | headless behaviors |
| `@human-synthesis/norns-ui/toast` | `toast`, `notify`, `dismiss`, `clear` |
| `@human-synthesis/norns-ui/cn` | `cn()` |
| `@human-synthesis/norns-ui/styles` | tokens + atoms CSS (`/styles/tokens`, `/styles/atoms` separately) |

---

<!-- https://norns-docs.humansynthesis.ai/norns/getting-started/install -->

# Install

> Create a Norns app from the starter template, or add norns to an existing SvelteKit project.

## Requirements

- [bun](https://bun.sh) as package manager and script runner. The norns CLI spawns Vite under Node, so Node 18 or newer must be installed too.
- A SvelteKit 2 / Svelte 5 project (the starter provides one).

## The starter template

```sh
bun create human-synthesis/norns-app my-app
cd my-app
bun install
bun run dev          # http://localhost:5173
```

`bun create` clones [norns-app](/norns-app), a one-page app with a single feature folder and everything wired: `svelte.config.js`, `vite.config.js`, `hooks.server.c`, Tailwind v4 and [norns-ui](/norns-ui). Delete the example feature and start from there.

## Manual setup in an existing SvelteKit app

```sh
bun add -D @human-synthesis/norns @sveltejs/kit svelte vite
```

`svelte.config.js`:

```js
import { nornsConfig } from '@human-synthesis/norns/config';

export default nornsConfig({
  // your overrides here
});
```

`vite.config.js`:

```js
import { defineConfig } from 'vite';
import { sveltekit } from '@sveltejs/kit/vite';
import { nornsCivetPlugin } from '@human-synthesis/norns/vite';

export default defineConfig({
  plugins: [nornsCivetPlugin(), sveltekit()]
});
```

`package.json` scripts:

```json
{
  "scripts": {
    "dev": "norns dev",
    "build": "norns build",
    "preview": "norns preview",
    "migrate": "norns migrate",
    "lint": "norns lint",
    "check": "norns check"
  }
}
```

That is enough to write `.n` components and `.c` modules. To use the runtime (DI, wrappers, migrations) add a `src/hooks.server.c` as shown in [boot](/norns/runtime/boot). To get auto-imports, register `nornsAutoImport` in both config files as shown in [Auto-imports](/norns/auto-imports/how-it-works).

> [!NOTE] The starter runs the CLI with `NODE_OPTIONS='--preserve-symlinks'`. That flag only matters inside the framework's own development workspace, where the packages are symlinked; a normal install does not need it.

---

<!-- https://norns-docs.humansynthesis.ai/norns-tron/guide/enable -->

# Turn it on app-wide

> Pass tronSerializer() to boot(); every route() response becomes content-negotiated and nothing breaks for JSON clients.

```civet
// src/hooks.server.c
import { tronSerializer } from '@human-synthesis/norns-tron/server'

features := import.meta.glob './lib/norns/*/server/module.c', { eager: true }
app := await boot { features, serializer: tronSerializer() }

{ handle, handleError } := app
export { handle, handleError }
```

From now on every `route()` response is content-negotiated: clients that send `Accept: application/tron` get TRON, everyone else (curl, third parties, existing code) keeps getting JSON. Remove the `serializer` line to roll the whole thing back.

## Per-route control

```civet
export GET  := route serializer: tronSerializer({ schema: noteWire }), handler: ...
export POST := route serializer: null, handler: ...   // force plain JSON
```

A per-route serializer overrides the app-wide one; `null` forces JSON.

## Request bodies

The serializer's `parseBody` hook lets `route()` read TRON request bodies (`Content-Type: application/tron`) in addition to JSON and form bodies, so the same endpoint accepts all three:

```civet
export POST := route
	input: createNoteSchema
	handler: async ({ input, container }) =>
		id: await notes(container).create input
```

## What goes on the wire

- Content type `application/tron`, never `application/json`: a TRON body may carry a declaration preamble that is not valid JSON.
- Payloads under about 1 KB are emitted as plain JSON automatically (and still decoded transparently); below that size TRON's fixed costs do not pay off.
- The serializer's options are the `EncodeOptions` (`minBytes`, `dict`, `table`, `force`) plus `schema` for [schema mode](/norns-tron/guide/schema-mode).

---

<!-- https://norns-docs.humansynthesis.ai/norns-core/guide/the-n-file -->

# The .n file

> A .n file is Pug on top, a Civet script block below, and an optional style block — no wrappers, no lang attributes.

```pug
section.space-y-4
	h1.text-4xl.font-bold Notes
	+each('data.notes as note (note.id)')
		Card(href!="/notes/{note.id}")
			.font-semibold {note.title}

<script>
	{ data } := $props()
</script>
```

## What the preprocessor does with it

The `norns-default-langs` step runs first on every file whose name ends in `.n`:

1. **Auto-close.** If the file ends inside a `<script>` or `<style>` block with no closing tag, the tag is appended. The reference apps use this: a component can end with the script block and nothing else.
2. **Rewrites.** `+if` chains, `+snippet` blocks and class shorthand are rewritten (next pages).
3. **Auto-wrap.** When there is no `<template>` tag, everything outside `<script>` and `<style>` blocks is wrapped in `<template lang="pug">` and the blocks are appended after it.
4. **Defaults.** A `<script>` without `lang` gets `lang="civet"`; a `<template>` without `lang` gets `lang="pug"`.

Then `norns-civet-script` compiles every `<script lang="civet">` (or `lang="cv"`) block to JavaScript with source maps and drops the `lang` attribute so svelte-preprocess does not look for a Civet transformer. Finally svelte-preprocess renders the Pug template (and handles `lang="ts"` scripts, should you write one).

## Writing it explicitly

All of these are equivalent to the defaults and allowed:

```pug
<template lang="pug">
section ...
</template>

<script lang="civet">
</script>
```

A `.svelte` file never goes through the `.n` defaults; it is compiled exactly as Svelte would, even with this preprocessor installed. Use that when you want a plain Svelte component next to your `.n` ones.

## Styles

`<style>` blocks work as in Svelte and are scoped. Both reference apps keep styling in Tailwind utilities and per-feature CSS files instead.

---

<!-- https://norns-docs.humansynthesis.ai/norns/getting-started/project-structure -->

# Project structure

> The layout of a Norns app and which SvelteKit files can be written in Civet.

A Norns app is an ordinary SvelteKit source tree. There is no generated tree and no spec directory.

```
src/
  hooks.server.c              boots the runtime, eager-loads feature modules
  app.html, app.css           html shell, global styles
  routes/                     SvelteKit routes
    +layout.n, +layout.c
    +page.n, +page.server.c
    api/<name>/+server.c
  lib/
    components/               components auto-imported by name (<Header>, <Card>, ...)
    norns/
      <feature>/              feature folders, see next page
        server/{module,repo,service,public}.c
        shared/schema.c
migrations/
  <feature>/<timestamp>_<slug>.sql
svelte.config.js, vite.config.js
wrangler.toml                 optional, Cloudflare deploys
```

## File types

| Extension | What it is | Compiled by |
|---|---|---|
| `.n` | A Svelte component whose template is Pug and whose `<script>` is Civet. No `lang` attributes needed. | norns-core preprocessor |
| `.c` | A Civet module. `.civet` is the same thing with a longer name. | `nornsCivetPlugin()` |
| `.svelte`, `.js`, `.ts` | Plain Svelte and JavaScript, still allowed anywhere. | Vite / Svelte as usual |

## SvelteKit special files in Civet

`nornsConfig()` sets `kit.moduleExtensions` to `['.js', '.ts', '.c', '.civet']`, so every SvelteKit module file has a Civet spelling: `+page.server.c`, `+layout.c`, `+server.c`, `+page.c`. Components use `extensions: ['.svelte', '.n']`, so `+page.n`, `+layout.n` and `+error.n` work.

Hooks are the one exception SvelteKit does not discover through `moduleExtensions`. `nornsConfig()` looks for `src/hooks.server.c` / `.civet` (and the client and universal counterparts) and sets `kit.files.hooks` explicitly when one exists. Name the file that way and nothing else is required.

## Where feature code goes

The starter and the demo keep features under `src/lib/norns/<feature>/` and boot them with:

```civet
features := import.meta.glob './lib/norns/*/server/module.c', { eager: true }
```

The glob in `hooks.server.c` is what decides; `src/lib/<feature>/` works just as well if you change it. Keep migrations outside `src/` so the bundler never sees them.

---

<!-- https://norns-docs.humansynthesis.ai/norns-ui/getting-started/setup -->

# Setup

> Register presetUI() with the auto-importer in both config files and import the stylesheet.

## Auto-imports

`presetUI()` returns a `components` map from name to import path. Pass it to `nornsAutoImport` in **both** `svelte.config.js` and `vite.config.js` (the same instance rules apply as for the [auto-importer](/norns/auto-imports/how-it-works)):

```js
// svelte.config.js
import { nornsConfig } from '@human-synthesis/norns/config';
import { nornsPreprocess } from '@human-synthesis/norns/preprocess';
import { nornsAutoImport } from '@human-synthesis/norns/auto-import';
import { presetUI } from '@human-synthesis/norns-ui/auto-import';

const ui = presetUI();

export default nornsConfig({
  preprocess: [
    ...nornsPreprocess(),
    nornsAutoImport({
      componentDirs: ['src/lib/components', 'src/routes'],
      components: ui.components
    })
  ]
});
```

```js
// vite.config.js
import { nornsCivetPlugin, pugTailwindExtract } from '@human-synthesis/norns/vite';
import { nornsAutoImport } from '@human-synthesis/norns/auto-import';
import { presetUI } from '@human-synthesis/norns-ui/auto-import';
import tailwindcss from '@tailwindcss/vite';

const ui = presetUI();

export default {
  plugins: [
    pugTailwindExtract(),
    nornsCivetPlugin(),
    nornsAutoImport({ components: ui.components }),
    tailwindcss(),
    sveltekit()
  ]
};
```

## Styles

```css
/* src/app.css */
@import 'tailwindcss';
@import '@fontsource-variable/outfit';
@import '@human-synthesis/norns-ui/styles';

@source "./**/*.n";
@source "../node_modules/.cache/norns/tailwind-pug-classes.html";
```

The library's tokens set `html` / `body` colour and background from role tokens; the two `@source` lines make Tailwind see the classes used in `.n` files (see [class shorthand](/norns-core/guide/class-shorthand)). The Outfit font import is optional.

## Use it

```pug
Form(action="?/save" form!="{form}")
	Field(label="Title" name="title" required)
		Input(name="title" placeholder="title…" required)
	Btn(type="submit" variant="primary" icon="lucide:save") Save
```

> [!NOTE] Versions before 0.0.6 required a `scopeToProject` wrapper around the preprocessors to keep them off Bits UI's TypeScript source. Bits UI is gone and the wrapper is no longer needed; remove it if you still have it. See the [migration note](/norns-ui/reference/migration-0-0-6).

---

<!-- https://norns-docs.humansynthesis.ai/norns-core/guide/civet-script -->

# Civet script

> The subset of Civet that Norns code is written in, and the JavaScript it becomes.

[Civet](https://civet.dev) is a TypeScript-flavoured, indentation-based language that compiles to plain JavaScript. Norns uses it for `<script>` blocks in `.n` files and for `.c` modules. Types are optional and erased.

## Emit characteristics that matter for Svelte

| You write | Civet emits |
|---|---|
| `count .= $state 0` | `let count = $state(0)` |
| `count := $state 0` | `const count = $state(0)` |
| `{ a, b = 0 } := $props()` | `const { a, b = 0 } = $props()` |
| `total := $derived a + b` | `const total = $derived(a + b)` |
| `$effect =>` with an indented body | `$effect(() => { ... })` |
| `results := $derived.by =>` with a body | `const results = $derived.by(() => { ... })` |

Imports stay where you write them. Civet emits ESM-correct output, so runes need no extra fusion or lifting passes.

## The everyday subset

```civet
import { notes } from '$lib/norns/notes/server/public'

export class NotesService
	repo: NotesRepo
	constructor(@repo: NotesRepo)

	list(): Promise<Note[]>
		@repo.list()

	async create(input: NoteInput): Promise<number>
		id := await @repo.create input.title, input.body
		throw new Error 'failed' unless id
		id

export notes := (c: Container) => {
	list: () => svc(c).list()
	create: (input: NoteInput) => svc(c).create(input)
}
```

- `:=` declares `const`, `.=` declares `let`; the last expression of a function is its return value.
- `@repo` is `this.repo`; `constructor(@repo: NotesRepo)` declares and assigns the field.
- Calls may omit parentheses when unambiguous. Prefer parentheses after `new` and inside longer chains.
- `unless`, postfix `if` / `unless`, `x?` existence checks, `if c then a else b` as an expression.
- Indented object literals as arguments and arrow bodies, which is how `page.load` and `route` calls read.
- Template literals use backticks and `${}`.

## Where to stop

Dense generator, stream or type-level code hits parser edges. Put that in a `.js` file next to the `.c` files; the [Civet pitfalls](/norns/pitfalls/civet) page lists the known traps and `norns diag` prints the emitted JavaScript when you need to see it.

---

<!-- https://norns-docs.humansynthesis.ai/norns-tron/guide/client -->

# Call it from the client

> The api wrapper sends the Accept header and decodes TRON or JSON transparently; inside load functions create one with SvelteKit's fetch.

```civet
import { api, createApi } from '@human-synthesis/norns-tron/client'

users := await api.get '/api/users'          // sends Accept: application/tron
await api.post '/api/notes', { title, body } // body goes out as TRON too

// inside a load function, keep SvelteKit's fetch semantics:
api := createApi { fetch }
```

| Method | Notes |
|---|---|
| `api.get(url, opts?)`, `api.del(url, opts?)` | no body |
| `api.post(url, body?, opts?)`, `api.put(...)`, `api.patch(...)` | body encoded as TRON |
| `api.request(method, url, body?, opts?)` | the general form |
| `createApi({ fetch?, base?, headers? })` | a new instance with defaults: a fetch implementation, a URL prefix, headers sent on every request |
| `parseResponse(res)` | decode any `Response` by its content type (TRON, JSON or text) |

Per-request `opts` accept `fetch`, `headers` and a raw `init` object.

A non-2xx response throws `ApiError` with `status`, the decoded `body` and the raw `response`.

## Browser notes

The 1.7 KB WASM scanner ships embedded as base64, so nothing needs to be served or wired; it works in Node, Bun and the browser. Under a strict CSP without `unsafe-eval` the decoder transparently falls back to the JavaScript scanner (about 1.1–1.5× slower). `setWasmBinary(bytes)` lets you supply the binary yourself, and `wasmAvailable()` reports which path is active.

---

<!-- https://norns-docs.humansynthesis.ai/norns-ui/getting-started/dark-mode -->

# Dark mode

> Every component swaps on <html data-theme="dark">; persist the choice with an inline script and the ThemeToggler component.

The tokens define light values at the root and dark values under `[data-theme='dark']`. Toggle that attribute and every component follows.

## Avoid the flash

Set the attribute before first paint with an inline script in `app.html`:

```html
<script>
  (function () {
    try {
      var t = localStorage.getItem('norns-theme');
      if (t === 'dark' || (t === null && window.matchMedia('(prefers-color-scheme: dark)').matches)) {
        document.documentElement.dataset.theme = 'dark';
      }
    } catch (_) {}
  })();
</script>
```

## Toggle

```pug
ThemeToggler(size="sm")
ThemeToggler(showLabel!="{true}" labelLight="Light" labelDark="Dark")
```

`ThemeToggler` reads and writes the same `norns-theme` localStorage key by default (`storageKey` changes it) and swaps between `lightIcon` and `darkIcon`.

## Your own styles

Reach for the role tokens rather than raw colours so your components swap too: `var(--color-fg)`, `var(--color-bg-elevated)`, `var(--color-border)` and the rest listed under [Theming](/norns-ui/guide/theming). Scope overrides with `[data-theme='dark'] .my-thing { ... }` when a token is not enough.

---

<!-- https://norns-docs.humansynthesis.ai/norns/getting-started/feature-folders -->

# Feature folders

> The unit of modularity in a Norns app — a bounded domain with a module, a repo, a service, a facade and a shared schema.

A feature is a folder that owns one domain. Its files have fixed roles:

| File | Role | Who may import it |
|---|---|---|
| `server/module.c` | Registers the feature's DI bindings (and migration dirs). The only file `boot()` reaches. | the runtime |
| `server/repo.c` | Data access. The only place SQL lives. | `service.c` |
| `server/service.c` | Business rules. No SQL, no HTTP. | `public.c` |
| `server/public.c` | The facade: the feature's public API. | routes and other features |
| `shared/schema.c` | valibot schemas shared by server and client. | routes, components, `service.c` |
| `ui/*.n` | Components that belong to the feature. | routes |

Routes and other features call a feature **only through its facade**. That rule is what makes a feature movable, testable with an overridden container, and safe for an agent to edit: the graph of who calls whom is explicit.

## The starter feature, in full

`norns-app` ships `src/lib/norns/messages/`, an in-memory message board. It is the whole pattern in forty lines.

`server/repo.c`:

```civet
export class MessagesRepo
	items: { id: number; text: string; at: number }[] = []

	list()
		[...@items]

	add(text: string)
		item := { id: @items.length + 1, text, at: Date.now() }
		@items.unshift item
		item
```

`server/service.c`:

```civet
import type { MessagesRepo } from './repo'
import type { SendMessageInput } from '../shared/schema'

export class MessagesService
	repo: MessagesRepo
	constructor(@repo: MessagesRepo)

	list()
		@repo.list()

	create(input: SendMessageInput)
		@repo.add input.text
```

`server/module.c` registers the tokens. The convention is `<feature>.<role>`:

```civet
import type { Container } from '@human-synthesis/norns/server'
import { MessagesRepo } from './repo'
import { MessagesService } from './service'

export default (app: Container) =>
	app.single 'messages.repo', => new MessagesRepo!
	app.single 'messages.service', (c: Container) => new MessagesService c.resolve('messages.repo')
```

`server/public.c` is what everyone else imports. It takes the request's container and returns the operations:

```civet
import type { Container } from '@human-synthesis/norns/server'
import type { MessagesService, SendMessageInput } from './service'

svc := (c: Container) => c.resolve('messages.service') as MessagesService

export messages := (c: Container) => {
	list: () => svc(c).list()
	create: (input: SendMessageInput) => svc(c).create(input)
}
```

And a route uses it through the [page wrappers](/norns/runtime/page-wrappers):

```civet
// src/routes/+page.server.c
import { messages } from '$lib/norns/messages/server/public'
import { sendMessageSchema } from '$lib/norns/messages/shared/schema'

export load := page.load
	handler: ({ container }) =>
		items: messages(container).list()

export actions := page.actions
	send:
		input: sendMessageSchema
		run: ({ input, container }) =>
			messages(container).create input
			{ ok: true }
```

## Adding a feature

1. Create `src/lib/norns/<feature>/server/` with `module.c`, `repo.c`, `service.c`, `public.c`, and `shared/schema.c` if the feature validates input.
2. Register bindings in `module.c`; use `app.single` for process-wide instances and `app.bind` for per-resolve instances (for example a request-scoped D1 handle, see [Cloudflare D1](/norns/data/cloudflare-d1)).
3. Import the facade from routes. Never import `service.c` or `repo.c` from outside the folder.
4. Migrations go to `migrations/<feature>/`, created with `norns migrate create <feature>/<name>`.

The `import.meta.glob` in `hooks.server.c` picks the new module up automatically; nothing else registers it.

---

<!-- https://norns-docs.humansynthesis.ai/norns-core/guide/pug-template -->

# Pug template

> Pug syntax as used in .n files, including the Svelte-specific attribute and text forms.

The template is rendered by svelte-preprocess's Pug support; norns-core adds the rewrites described on the next pages. The forms below are the ones used throughout the reference apps.

## Elements, classes, attributes

```pug
section.animate-in.space-y-4
	h1.text-4xl.font-bold(class="text-fg") Notes
	p.max-w-prose(class="text-fg-muted")
		| SQLite-backed CRUD with SvelteKit form
		code actions
		|  and SSR load.
```

- `tag.class-a.class-b` is the class shorthand; `(name="value")` is the attribute list. Both can appear on the same element.
- `| text` emits a text line; use it to mix text with inline elements and to emit Svelte block syntax.
- `//- comment` is a Pug comment that never reaches the output.

## Svelte expressions

| Form | Meaning |
|---|---|
| `{expr}` in text | Svelte interpolation (runtime) |
| `attr!="{expr}"` | attribute bound to an expression; `!=` is Pug's unescaped attribute |
| `class!="{cond ? 'a' : ''}"` | dynamic class next to static shorthand classes |
| `bind:value!="{value}"` | two-way binding |
| `onclick!="{handler}"` | event handler (Svelte 5 attribute events) |
| `\| {@render children?.()}` | render a snippet |
| `\| {@html html}` | raw HTML |

Never use Pug's own `#{expr}`; it runs at preprocess time with no runtime data.

## Components

A capitalised tag is a component. With auto-imports on, no import line is needed:

```pug
Form(action="?/create" form!="{form}")
	Field(label="Title" name="title" required)
		Input(name="title" placeholder="title…" required)
	Btn(type="submit" variant="primary" icon="lucide:save") Create note
```

Boolean props are passed as `prop!="{true}"`; a bare attribute like `required` passes the string form, which is what native inputs want.

## Special elements

```pug
svelte:head
	title Notes · My app
	meta(name="description" content!="{description}")
```

`svelte:head`, `svelte:window`, `svelte:element` and friends are ordinary tag names to Pug.

## Multi-line attribute lists

```pug
a.nav-link(
	href="https://github.com/human-synthesis/norns"
	target="_blank"
	rel="noopener"
)
	Icon(name="lucide:github")
```

Attributes may span lines inside the parentheses. Everything else is one element per line.

---

<!-- https://norns-docs.humansynthesis.ai/norns-tron/guide/schema-mode -->

# Schema mode

> When both ends know the shape, derive the wire schema from the valibot schema you already have and skip shape detection entirely.

Both ends of an internal endpoint already know the row shape from the feature contract, so nothing descriptive needs to travel. Derive the wire schema from the valibot schema in `shared/schema.c`:

```civet
// src/lib/norns/notes/shared/schema.c
import * as v from 'valibot'
import { tronSchemaFromValibot } from '@human-synthesis/norns-tron/valibot'

export noteSchema := v.object
	id: v.number()
	title: v.string()
	status: v.picklist ['draft', 'published']

export noteWire := tronSchemaFromValibot noteSchema, { id: 'notes.v1', path: '$.data' }
```

Server:

```civet
export GET := route
	serializer: tronSerializer({ schema: noteWire })
	handler: async ({ container }) =>
		data: await notes(container).list()
```

Client: the same `noteWire` decodes it, or `api.get('/api/notes')` when the client only ever sees this shape.

## Rules

- `picklist` / `enum` fields become dictionary columns (integers on the wire); booleans become 0/1.
- **Compile once at module scope, never per request.** `tronSchemaFromValibot` (and `defineSchema`) resolve field order, enum tables and the row path, and compile the row constructor. Doing that per request is the difference between winning and losing on small payloads.
- `path` says where the row array lives: `'$'` for the root, `'$.data'` for an envelope.
- The `#notes.v1` tag (`id`) is emitted as a header line and makes version mismatches fail loudly instead of misdecoding. A client that consumes several shapes uses `createRegistry()`, registers each schema, and calls `registry.decode(text)`, which peeks the tag and picks the schema.

## Without valibot

`defineSchema({ id, fields, enums, path })` builds the same compiled schema by hand; see the [core reference](/norns-tron/reference/core).

---

<!-- https://norns-docs.humansynthesis.ai/norns-ui/getting-started/icons -->

# Icons

> Iconify through @iconify/svelte, with the Lucide collection bundled; register it once, then use <Icon> anywhere.

The library depends on `@iconify/svelte` and `@iconify-json/lucide`. Register the collection once in your app entry so icons render on the server and the client:

```civet
// src/routes/+layout.c (or any module loaded once)
import { addCollection } from '@iconify/svelte'
import lucide from '@iconify-json/lucide/icons.json'
addCollection lucide
```

Then:

```pug
Icon(name="lucide:check" size="size-5")
Btn(icon="lucide:save") Save
Banner(variant="info" icon="lucide:info") No notes yet
```

`name` is Iconify's `<set>:<name>`; `size` is any Tailwind size utility (default `size-4`); `flip` and `rotate` are supported.

To use another set, install its JSON package (for example `@iconify-json/heroicons`) and `addCollection` it the same way. Components that take an `icon` prop (`Btn`, `Banner`, `Chip`, `Dropdown` items, `Timeline` items, ...) accept any registered icon name.

---

<!-- https://norns-docs.humansynthesis.ai/norns-core/guide/control-flow -->

# Control flow

> +if / +elseif / +else chains, +each, and +snippet blocks with {@render}.

## `+if` chains

```pug
+if('data.notes.length === 0')
	Banner(variant="info") No notes yet
+elseif('data.filtered')
	p Showing a filtered list
+else
	.space-y-2
		+each('data.notes as note (note.id)')
			Card {note.title}
```

norns-core rewrites the chain, at any nesting depth, into Svelte blocks emitted as Pug text:

```pug
| {#if data.notes.length === 0}
Banner(variant="info") No notes yet
| {:else if data.filtered}
p Showing a filtered list
| {:else}
.space-y-2
	...
| {/if}
```

The condition is the string inside the parentheses; quotes are stripped. The rewrite exists because svelte-preprocess's own `+if` mixin does not support chaining.

## `+each`

```pug
+each('data.notes as note (note.id)')
	li {note.title}
```

`+each` is svelte-preprocess's Pug mixin and its argument is copied verbatim into `{#each ...}`, so it must be in Svelte's `items as item` form, optionally with a `(key)`. The `item of items` form compiles to a block the Svelte compiler rejects; `norns lint` flags it.

Other svelte-preprocess mixins (`+await`, `+key`, `+html`, `+debug`) exist upstream but are not part of the vetted subset the framework tests pin; prefer `| {#key x}` text lines if you need them.

## `+snippet`

Svelte 5 snippets are how norns-ui components take named content. Define one with `+snippet` and render it with `{@render}` behind a pipe:

```pug
Header(sticky!="{true}")
	+snippet('brand')
		a(href="/") Norns
	+snippet('nav')
		a(href="/docs") Docs

DataTable(rows!="{rows}")
	+snippet('cell', row, key)
		span {row[key]}
```

`+snippet('name')` becomes `{#snippet name()}` and `+snippet('row', user, idx)` becomes `{#snippet row(user, idx)}`; the argument list may contain parentheses. Snippets nest, so a `Tabs` item snippet can contain a `Card` with its own `header` snippet.

Inside a component, render what you received:

```pug
header(class!="{classes}")
	.brand
		| {@render brand?.()}
	+if('nav')
		nav
			| {@render nav()}
```

---

<!-- https://norns-docs.humansynthesis.ai/norns-tron/guide/limits -->

# Semantics and limits

> What TRON preserves, what it does not, and where it should not be used.

- **Same value semantics as JSON.** `toJSON()` is honoured, so a `Date` arrives as its ISO string, not a `Date` (exactly like `response.json()`). `Map` and `Set` serialize as `{}` and `BigInt` throws, as with `JSON.stringify`; dev mode logs a warning when a route returns them.
- **Not for `load` or form actions.** SvelteKit serializes those with devalue, which preserves Dates, Maps and Sets. This package targets `route()` endpoints, LLM-facing output and service-to-service payloads.
- **Payloads under about 1 KB stay JSON** unless `minBytes: 0` or `force: true` is set. They are still decoded transparently.
- **Content type is `application/tron`.** A TRON body may carry a declaration preamble that is not valid JSON, so never label it `application/json`.
- **Schema mode uses `new Function`** for the row constructor where the runtime allows it. In CSP-restricted browsers the fallback scanner takes over, and on Cloudflare Workers, which forbid `new Function`, versions from 0.0.2 use a closure-based row constructor instead.
- **Numeric enum values are rejected** in `enums`: they would be ambiguous with dictionary indices and decode as `undefined`. Enum values must be strings or booleans.
- **`decodeColumnar` needs `encodeColumnar` output.** The default `encode()` emits `table` declarations that the WASM columnar scanner does not accept; it returns `undefined` for them.

---

<!-- https://norns-docs.humansynthesis.ai/norns-core/guide/class-shorthand -->

# Class shorthand

> The rewriter that lets Tailwind variants, slashes and fractions live in Pug's .class chains, and the extractor that tells Tailwind about them.

Pug's lexer rejects `:` and `/` inside class shorthand and mis-parses a fractional `.5` as a new class. norns-core rewrites element lines so the offending classes move into the `(class="...")` attribute before Pug sees them:

| You write | Pug receives |
|---|---|
| `.text-blue.hover:bg-red(href="/")` | `.text-blue(class="hover:bg-red" href="/")` |
| `.gap-2.5.flex` | `.flex(class="gap-2.5")` |
| `.bg-white/40.text-4xl(class="static")` | `.text-4xl(class="bg-white/40 static")` |
| `.a.sm:px-8(class!="{extra}")` | `.a(class!="sm:px-8 {extra}")` |

Routed classes are prepended to an existing static `class="..."`, or to a dynamic `class!="{...}"` where Svelte reads the result as text plus interpolation. Lines inside `<script>` / `<style>`, text lines (`|`), raw HTML (`<`), comments and mixin calls (`+if`) are left alone. Ids (`#main`) are always safe and stay in shorthand.

## Tailwind extraction

Tailwind v4's scanner cannot read a dotted chain as separate candidates, so the classes would render in the HTML without any CSS behind them. `extractPugClasses(content)` returns the set of shorthand classes plus the values of any `class="..."` / `class!="..."` attribute on the same line; the [`pugTailwindExtract()`](/norns/config/vite-plugin) Vite plugin in norns runs it over every `.n` file and writes a sidecar that Tailwind scans through `@source`.

Both functions share the same grammar for a class segment (`[\w/:-]` plus `.digits` continuations), so what the rewriter accepts the extractor also reports.

---

<!-- https://norns-docs.humansynthesis.ai/norns-tron/guide/performance -->

# Performance guide

> Pick the right mode, compile schemas once, declare enums, do not encode small payloads, and reach for the columnar tape when data is numeric.

The ratios below are measured (Node 22, interleaved pairs against native JSON, median of 15 rounds). **The ratio is TRON / JSON; under 1.00 means TRON is faster.** Absolute milliseconds depend on the machine; the ratios are the signal.

## 1. Choose the right mode

| Situation | Use | decode | encode | round-trip | tokens saved |
|---|---|---:|---:|---:|---:|
| Internal API, both ends are your code | `defineSchema` / `tronSchemaFromValibot` | 0.40–0.87× | 0.66–0.93× | 0.57–0.91× | 11–61% |
| LLM prompt or third-party consumer | `encode` / `decode` | 0.45–0.77× | 0.97–1.77× | 0.76–1.22× | 26–61% |
| Numeric or columnar data | `decodeColumnar` | ~0.30× | — | — | 35% |
| Payload under ~1 KB | plain JSON | — | — | — | 0% |

The gap between schema mode and self-describing mode is the largest optimisation available, bigger than any fine-tuning. Schema mode wins on every axis at every size.

## 2. Preload once, at application start

The number-one mistake is compiling the schema per request. `defineSchema` does real work: it resolves field order, enum tables and the path, and compiles the row constructor with `new Function`. Do it once at module scope, as [schema mode](/norns-tron/guide/schema-mode) shows. Measured effect on a 25-row envelope: decode 1.21× → **0.63×**, encode 2.49× → **0.90×**.

## 3. Declare `enums` for low-cardinality columns

Any string or boolean column with few distinct values (status, role, region, flags) becomes an integer on the wire. Three effects at once: fewer tokens (`events-10k`: 38% → **42%**), faster decode (no string allocation for that column), and WASM eligibility: a dictionary column is an integer on the wire, so a table with strings becomes eligible for the WASM scanner. Values must be strings or booleans.

## 4. Do not encode small payloads

`encode()` already returns plain JSON under 1 KB and `decode()` reads it transparently. In self-describing mode:

| rows | JSON | decode | round-trip |
|---:|---:|---:|---:|
| 5 | 0.5 KB | 4.80× | 5.16× |
| 25 | 2.1 KB | 1.21× | 1.70× |
| 100 | 8.4 KB | **0.78×** | 1.16× |
| 1000 | 86 KB | **0.68×** | **1.01×** |
| 10000 | 881 KB | **0.67×** | **0.94×** |

With a preloaded schema the threshold disappears (see §1).

## 5. Numeric data: take the columnar tape

The fastest path in the library; it never builds JavaScript objects.

```js
const wire = encodeColumnar(rows);               // server
const col = decodeColumnar(wire, /* copy */ true); // client
if (col) {
  const v = col.tape[r * col.cols + c];           // row-major
} else {
  const obj = decode(wire);                        // not eligible, normal path
}
```

About **0.30×** of `JSON.parse`. `copy: true` detaches the tape from WASM memory; without it the next decode invalidates it.

## 6. `table: 'nested'` trades tokens for speed

The default (`table: true`) tabulates only flat rows: a pure win, faster and fewer tokens. `'nested'` also accepts rows with nested objects: faster still, but the inner shapes lose their own compression. Measured on `nested-500`: round-trip 2.47× → **0.89×**, tokens saved 26% → 11%. Pick by what you pay for, latency or tokens.

## 7. Runtime details

- `new Function` is used by the trampoline and row constructors. Under a strict CSP without `unsafe-eval` the library falls back to the scanner (`parseFast`), about 1.1–1.5×. Correct, just slower.
- WASM is optional. Node and Bun load the embedded binary; in a browser you may also supply it with `setWasmBinary(...)`. Without it nothing breaks; the dispatcher just skips the WASM path.
- Send `Content-Type: application/tron` (`route()` does). Never `application/json`.
- HTTP compression still applies. TRON reduces bytes before gzip or brotli; the gains compound, less than linearly.
- Do not re-encode what has not changed; cacheable responses encode once and keep only the decode win.

## 8. Checklist

- `defineSchema` / `tronSchemaFromValibot` called once at startup, not per request
- `enums` declared for every categorical and boolean column
- payloads under ~1 KB left as JSON (the default threshold does this)
- `encodeColumnar` + `decodeColumnar` used together where data is numeric
- content type set to `application/tron`
- in the browser, `setWasmBinary` called or the fallback consciously accepted
- measured with your own data before relying on these figures

## Methodology

A naive benchmark gave contradictory results (two identical code paths differing by 43%) because running several decoders in one process makes V8's inline caches polymorphic. The numbers here use one child process per data set, interleaved A/B/A/B pairs with alternating order, and the median of 15 rounds. Correctness: 220,118 adversarial and fuzz checks across the suite, 22 dedicated schema-mode tests and 1,500 fuzz round-trips, zero failures.

---

<!-- https://norns-docs.humansynthesis.ai/norns-core/guide/error-mapping -->

# Error mapping

> Pug and Civet errors are mapped back to the file, line and column you wrote, with a code frame.

Two things make raw errors useless in a `.n` file. svelte-preprocess renders Pug with a ~50-line mixin prelude prepended, so Pug's line numbers point ~50 lines past the real one, on top of the `+if` / `+snippet` rewrites that move lines. And a Civet error inside a `<script>` block is relative to the block, not the file.

norns-core keeps the original source of each `.n` file it processes and maps both kinds of errors back:

- **Pug errors** become `PugError` with `code: 'norns_pug_error'`, `line`, `column`, a `frame` over your source, and a message of the form `Page.n:18:7: Pug: <message>`. The prelude offset is voted from the lines of Pug's own code frame that can be found verbatim in the template; rewritten lines (`| {#if x}` from `+if('x')`) are searched in their original spelling. When the exact line cannot be found the nearest plausible one is used and the message says `(approximate line)`.
- **Civet script errors** keep Civet's `ParseError` but get `code: 'norns_civet_error'` and a file-relative `line`, `column` and `frame`.

`norns check` prints these as `file:line:column` diagnostics, and the `stage` field tells you which compiler produced them. Svelte compile errors are a separate case handled by `norns check` through the preprocess source map; see [check and diag](/norns/cli/check-and-diag).

---

<!-- https://norns-docs.humansynthesis.ai/norns/config -->

# Configuration

> The two config files, the Vite plugins, and the file extensions norns registers.

- [svelte.config.js](/norns/config/svelte-config) — `nornsConfig()` and its defaults.
- [Vite plugin](/norns/config/vite-plugin) — `nornsCivetPlugin()`, `pugTailwindExtract()`, and the Vite options that matter.
- [File extensions](/norns/config/file-extensions) — `.n`, `.c`, `.civet`, and how they map onto SvelteKit's files.

---

<!-- https://norns-docs.humansynthesis.ai/reference/glossary -->

# Glossary

> Terms used across the Norns docs.

| Term | Meaning |
|---|---|
| **`.n` file** | A Svelte component written as Pug (template) and Civet (script). See [the .n file](/norns-core/guide/the-n-file). |
| **`.c` file** | A Civet module; `.civet` is the same. |
| **Civet** | A TypeScript-flavoured, indentation-based language that compiles to JavaScript ([civet.dev](https://civet.dev)). |
| **Pug** | An indentation-based HTML template language ([pugjs.org](https://pugjs.org)). |
| **Feature** | A bounded domain in `src/lib/norns/<feature>/` with a module, repo, service, facade and schema. |
| **Module** | `server/module.c`; the function that registers a feature's bindings on the container. |
| **Repo** | `server/repo.c`; data access, the only place SQL lives. |
| **Service** | `server/service.c`; business rules. |
| **Facade** | `server/public.c`; the feature's public API, the only legal entry point from routes and other features. |
| **Schema** | `shared/schema.c`; valibot schemas shared by server and client. |
| **Container** | The DI container: string tokens, `bind` / `single` / `override`, child scopes. |
| **Token** | A container key, conventionally `<feature>.<role>`. |
| **Request scope** | The child container created per request and attached to `event.locals.container`. |
| **Page wrappers** | `page.load` and `page.actions`, for `+page.server.c`. |
| **`route()`** | The wrapper for `+server.c` handlers. |
| **Serializer** | The hook that turns `route()` results into a `Response`; `tronSerializer()` is the shipped one. |
| **TRON** | The token-efficient wire format implemented by norns-tron. |
| **Auto-import** | Resolving helpers, components, presets and exports by name without import lines. |
| **Preset** | A UI library's `components` map for the auto-importer, e.g. `presetUI()`. |
| **Atom** | A CSS-only class from norns-ui (`.btn`, `.card`, ...). |
| **Snippet** | A Svelte 5 `{#snippet}`; written as `+snippet('name')` in Pug. |
| **Migration** | A forward-only SQL file under `migrations/<feature>/`. |
| **Vetted subset** | The Civet and Pug constructs the norns-core tests guarantee. |
| **Verification order** | `norns lint`, then `norns check`, then `bun run build`, then `curl` through the dev server. See [verification workflow](/norns/pitfalls/verification). |

---

<!-- https://norns-docs.humansynthesis.ai/norns-ui/guide -->

# Guide

> The tiers of the library and how they fit together.

- [Forms](/norns-ui/guide/forms) — `Form`, `Field` and the inputs, wired to `page.actions` errors.
- [Overlays](/norns-ui/guide/overlays) — dialogs, sheets, popovers, dropdowns, tooltips, tabs.
- [Toast](/norns-ui/guide/toast)
- [Behaviors](/norns-ui/guide/behaviors) — the headless actions the overlays are built on.
- [Theming](/norns-ui/guide/theming) — tokens and how to override them.
- [Motion](/norns-ui/guide/motion) — the opt-in animated components.
- [Overriding components](/norns-ui/guide/overriding)

---

<!-- https://norns-docs.humansynthesis.ai/norns-core/reference -->

# Reference

> The exported API and the vetted subset the tests pin.

- [API](/norns-core/reference/api) — `nornsPreprocess()` and the exported transform helpers.
- [Vetted subset](/norns-core/reference/vetted-subset) — the Civet and Pug constructs the framework guarantees, and the traps it guarantees stay trapped.

---

<!-- https://norns-docs.humansynthesis.ai/norns-tron/reference -->

# Reference

> The four entry points and their exported types.

- [Core](/norns-tron/reference/core) — `@human-synthesis/norns-tron`
- [Server](/norns-tron/reference/server) — `@human-synthesis/norns-tron/server`
- [Client](/norns-tron/reference/client) — `@human-synthesis/norns-tron/client`
- [valibot](/norns-tron/reference/valibot) — `@human-synthesis/norns-tron/valibot`

---

<!-- https://norns-docs.humansynthesis.ai/norns-demo/tic-tac-toe -->

# Tic-tac-toe

> Component composition, Svelte stores in a Civet module, $effect, a toggle group and a small AI.

`src/routes/examples/norns/tic-tac-toe/` has no server side; it is a client-side game built from `Game.n`, `Board.n`, `Cell.n`, `store.c` and `ai.c`.

## The store

`store.c` uses Svelte stores from a Civet module. `writable`, `derived` and `get` are auto-imported from `svelte/store`:

```civet
mode := writable '1v1'
board := writable newBoard()
turn := writable 'X'
stats := writable { X: 0, O: 0, draw: 0 }

result := derived board, ($b) =>
	for [a, x, y] of LINES
		if $b[a]? and $b[a] is $b[x] and $b[x] is $b[y]
			return { winner: $b[a], line: [a, x, y] }
	if $b.every((c) => c?) then { winner: null, line: [] } else null

play := (idx) =>
	return if get(result)?
	$b := get board
	return if $b[idx]?
	...
```

Note the Civet idioms: `is` for `===`, `x?` existence checks, `return if cond`, and `if ... then ... else` as an expression.

## The component

`Game.n` subscribes with the `$store` syntax in the template (`{$stats.X}`, `$board`), uses a `ToggleButtonGroup` for the mode, and a `$effect` that increments the stats once per finished game:

```civet
notified .= $state false

$effect =>
	if $result?
		unless notified
			incrementStats $result.winner
			notified = true
	else
		notified = false
```

`notified` is declared with `.=` because it is reassigned; `:=` would make it a `const` and `norns lint` would flag it.

`Board.n` and `Cell.n` are colocated components picked up by the auto-importer because `src/routes` is in `componentDirs`; `ai.c` exports `scheduleAiMove`, imported explicitly.

## The vanilla twin

`src/routes/examples/svelte/tic-tac-toe/` implements the same game in `.svelte` / `.ts`.

---

<!-- https://norns-docs.humansynthesis.ai/norns/config/svelte-config -->

# svelte.config.js

> nornsConfig() builds a SvelteKit config with the Norns defaults; spread your own overrides on top.

```js
import { nornsConfig } from '@human-synthesis/norns/config';

export default nornsConfig({
  kit: {
    adapter: adapter()
  }
});
```

## Defaults

| Key | Default | Notes |
|---|---|---|
| `extensions` | `['.svelte', '.n']` | both vanilla and Norns components |
| `preprocess` | `nornsPreprocess()` | Pug + Civet, from norns-core |
| `kit.moduleExtensions` | `['.js', '.ts', '.c', '.civet']` | makes `+page.server.c`, `+server.c`, `+layout.c` valid |
| `kit.files.hooks.server` | `src/hooks.server.c` or `.civet` when the file exists | SvelteKit only searches `.js` / `.ts` for hooks, so the path is set explicitly |
| `kit.files.hooks.client`, `kit.files.hooks.universal` | same rule for `hooks.client.*` and `hooks.*` | |

Anything you pass is merged: `kit` keys are spread over the defaults, `kit.files` is merged so your own `files` entries survive, and a `preprocess` or `extensions` you pass replaces the default outright.

## Replacing `preprocess`

You will replace `preprocess` whenever you add the auto-importer, because it is a Svelte preprocessor too. Keep `nornsPreprocess()` first:

```js
import { nornsConfig } from '@human-synthesis/norns/config';
import { nornsPreprocess } from '@human-synthesis/norns/preprocess';
import { nornsAutoImport } from '@human-synthesis/norns/auto-import';
import { presetUI } from '@human-synthesis/norns-ui/auto-import';

const ui = presetUI();

export default nornsConfig({
  preprocess: [
    ...nornsPreprocess(),
    nornsAutoImport({
      componentDirs: ['src/lib/components', 'src/routes'],
      components: ui.components
    })
  ]
});
```

`@human-synthesis/norns/preprocess` re-exports `nornsPreprocess` from norns-core so you do not have to depend on norns-core directly.

---

<!-- https://norns-docs.humansynthesis.ai/norns-ui/guide/forms -->

# Forms

> Form derives an error map from the page's form prop; each Field finds its own error by name; inputs inherit the field's id and name.

```pug
Form(action="?/create" form!="{form}")
	Field(label="Title" name="title" required)
		Input(name="title" value!="{form?.values?.title ?? ''}" required)
	Field(label="Body" name="body" help="Optional")
		Textarea(name="body" rows="3" value!="{form?.values?.body ?? ''}")
	Btn(type="submit" variant="primary") Create note

<script>
	{ data, form } := $props()
</script>
```

## How errors flow

1. `page.actions` validates the body with valibot and, on failure, returns `fail(400, { errors, values })` (see [validation](/norns/runtime/validation)).
2. SvelteKit hands that object to the page as `form`.
3. `<Form form={form}>` derives a `name → message` map from `errors[*].path[0].key` and exposes it through context.
4. `<Field name="title">` looks its message up from the context and switches the inner control to error styling. An explicit `error="..."` prop overrides the lookup.
5. `values` lets you echo what the user typed.

No per-page boilerplate; the same wiring works for every action.

## Field

| Prop | Notes |
|---|---|
| `label` | rendered above the control; used to derive an id when neither `id` nor `name` is set |
| `name` | key for the error lookup and the default id of the inner control |
| `help` | helper text shown when there is no error |
| `error` | explicit message, overrides the context |
| `required` | cosmetic asterisk; also set `required` on the input itself |
| `children` | snippet that renders the control |

`FieldGroup(legend="...")` wraps several fields in a `<fieldset>`.

## Inputs

`Input`, `Textarea`, `Select`, `Checkbox`, `Radio` and `Switch` are thin wrappers over the native elements: they accept the native attributes, an `error` boolean, `class`, and sizes where it makes sense. `Radio` takes `group` for `bind:group`. `Select` renders `<option>` children from its Pug body.

The richer inputs (`NumberInput`, `OtpField`, `TagsInput`, `Autocomplete`, `MultiSelect`, the date and time pickers, `ColorPicker`, `Uploader`) are custom components with bindable `value` props; see the [reference](/norns-ui/reference/components) for each prop list.

---

<!-- https://norns-docs.humansynthesis.ai/norns-core/reference/api -->

# API

> nornsPreprocess(options) and the four helper functions exported from @human-synthesis/norns-core/preprocess.

```js
import {
  nornsPreprocess,
  transformIfChains,
  transformSnippets,
  rewritePugClasses,
  extractPugClasses
} from '@human-synthesis/norns-core/preprocess';
```

## `nornsPreprocess(options?)`

Returns an array of three Svelte preprocessors, in order:

1. `norns-default-langs` — the `.n` rewrites and defaults.
2. `norns-civet-script` — compiles `<script lang="civet">` (or `cv`) blocks.
3. svelte-preprocess, configured with `pug: {}` and TypeScript compiler options `ignoreDeprecations: '6.0'`, `verbatimModuleSyntax: true`, `isolatedModules: true`, wrapped so Pug errors come back mapped.

`options` is spread into the svelte-preprocess configuration, so any svelte-preprocess option can be added or overridden. Use the spread form when composing with other preprocessors:

```js
preprocess: [...nornsPreprocess(), nornsAutoImport({ ... })]
```

`@human-synthesis/norns/preprocess` re-exports `nornsPreprocess`.

## Helpers

| Function | Input → output |
|---|---|
| `transformIfChains(content)` | rewrites `+if` / `+elseif` / `+else` chains to `\| {#if}` text lines, recursively |
| `transformSnippets(content)` | rewrites `+snippet('name', args)` blocks to `\| {#snippet name(args)}`, recursively |
| `rewritePugClasses(content)` | routes classes with `:`, `/` or fractional suffixes into `(class="...")`, skipping script and style blocks |
| `extractPugClasses(content)` | returns a `Set<string>` of shorthand and `class=` attribute classes, for Tailwind |

All four are pure string functions; `pugTailwindExtract()` in norns is built on the last one.

---

<!-- https://norns-docs.humansynthesis.ai/norns-tron/reference/core -->

# Core

> encode, decode, defineSchema, createRegistry, the columnar pair and the WASM controls.

```ts
import { encode, decode, defineSchema, createRegistry } from '@human-synthesis/norns-tron';
```

## Functions

| Function | Notes |
|---|---|
| `encode(value, opts?)` | self-describing TRON, or plain JSON when the equivalent JSON is under `minBytes` |
| `decode(text)` | any TRON document, including plain JSON |
| `defineSchema(spec)` | compile a schema once at startup; returns a `CompiledSchema` |
| `createRegistry()` | a `SchemaRegistry` for services that serve several response shapes |
| `encodeColumnar(value, opts?)` | emit the form `decodeColumnar` can take (no `table` declarations) |
| `decodeColumnar(text, copy?)` | a numeric / dictionary table as a flat `Float64Array`, or `undefined` when not eligible |
| `wasmAvailable()` | whether the WASM fast path is usable here |
| `setWasmBinary(bytes)` | supply the WASM binary yourself (browsers, bundlers, Deno) |
| `raw.stringify`, `raw.parse`, `raw.parseFast`, `raw.parsePrelude` | the underlying primitives |

## `EncodeOptions`

| Option | Default | Notes |
|---|---|---|
| `minBytes` | `1024` | below this many bytes of equivalent JSON, `encode()` returns plain JSON. `0` always encodes |
| `dict` | `true` | dictionary-encode low-cardinality string and boolean columns |
| `table` | `true` | emit `table` declarations so decoding needs no text transform. `true` = flat uniform rows only (always a win); `'nested'` = also rows with nested objects (faster, but inner shapes lose compression) |
| `force` | `false` | skip the `minBytes` check |

## `SchemaSpec`

```ts
interface SchemaSpec {
  id?: string;                                        // version tag, emitted as a `#id` line
  fields: string[];                                   // in the exact serialization order
  enums?: Record<string, Array<string | boolean>>;    // per-field dictionaries; numbers are rejected
  path?: string;                                      // '$' (root) or e.g. '$.data'; default '$'
}
```

## `CompiledSchema`

`encode(value)`, `decode(text)`, `peek(text)` (read the `#id` tag without parsing the body, `null` when untagged), and the readonly `fields` and `id`.

## `SchemaRegistry`

`register(spec)`, `get(id)`, and `decode(text)`, which peeks the tag and decodes with the matching schema.

## `ColumnarResult`

`{ fields, rows, cols, tape }` where `tape` is row-major with length `rows * cols`.

---

<!-- https://norns-docs.humansynthesis.ai/norns/config/vite-plugin -->

# Vite plugin

> nornsCivetPlugin() compiles Civet modules and teaches Vite the Norns extensions; pugTailwindExtract() closes Tailwind's blind spot on Pug class chains.

```js
import { defineConfig } from 'vite';
import { sveltekit } from '@sveltejs/kit/vite';
import tailwindcss from '@tailwindcss/vite';
import { nornsCivetPlugin, pugTailwindExtract } from '@human-synthesis/norns/vite';
import { nornsAutoImport } from '@human-synthesis/norns/auto-import';
import { presetUI } from '@human-synthesis/norns-ui/auto-import';

const ui = presetUI();

export default defineConfig({
  plugins: [
    pugTailwindExtract(),
    nornsCivetPlugin(),
    nornsAutoImport({ components: ui.components }),
    tailwindcss(),
    sveltekit()
  ],
  server: { allowedHosts: true }
});
```

## `nornsCivetPlugin()`

Runs with `enforce: 'pre'` and does four things:

- **Compiles `.c` and `.civet` files** through `@danielx/civet` with source maps, so `+page.server.c`, `hooks.server.c`, `+server.c` and any module you write in Civet load like `.js`.
- **Registers the extensions** `.svelte`, `.n`, `.civet`, `.c` with Vite's resolver, after Vite's defaults, so `import X from './Foo'` finds `Foo.n` or `Foo.c`.
- **Resolves bare sibling imports.** `import { play } from 'store'` (no `./`) resolves to a sibling `store.c` / `store.n` / `store.js` when one exists next to the importer. Package imports are untouched because they contain a slash or a scope; imports from inside `node_modules` are never rewritten.
- **Workspace mode.** When the framework packages resolve to symlinks outside `node_modules` (the framework's own development workspace), they are excluded from dependency pre-bundling and lifted out of the watch ignore list so edits to the framework source hot-reload. Published installs never enter this branch.

## `pugTailwindExtract(options?)`

Tailwind v4's scanner extracts class candidates from string contexts. Pug's chained shorthand, `.flex.items-center.p-4`, reads as one dotted token and is dropped, and `.grid.gap-6(class="...")` loses the class before the paren. The page renders with the classes in the HTML but no CSS for them.

The plugin walks every `.n` file, extracts each shorthand class with `extractPugClasses` from norns-core, and writes the deduplicated set into a sidecar HTML file that Tailwind can scan. It re-runs on every `.n` change in dev.

| Option | Default | Notes |
|---|---|---|
| `root` | `'src'` | directory to scan |
| `ext` | `'.n'` | file extension |
| `outFile` | `'node_modules/.cache/norns/tailwind-pug-classes.html'` | sidecar path, relative to the project root, taken verbatim |

Reference the sidecar from your CSS, with a path relative to the CSS file:

```css
@import 'tailwindcss';
@source "./**/*.n";
@source "../node_modules/.cache/norns/tailwind-pug-classes.html";
```

The first `@source` is the raw scan, which handles chains that end at whitespace; the sidecar covers the rest.

## Vite options worth setting

- `server.allowedHosts: true` (or an explicit list) when the dev server sits behind any reverse proxy. `norns lint` warns when it is missing.
- In the framework workspace only: `resolve.dedupe: ['@sveltejs/kit']` and `ssr.noExternal: ['@human-synthesis/norns']`, so the symlinked norns package uses the app's single copy of SvelteKit instead of the fork's. A normal install does not need either.

---

<!-- https://norns-docs.humansynthesis.ai/norns-ui/guide/overlays -->

# Overlays

> Dialog, Sheet, Popover, Dropdown, Tooltip, ContextMenu, Tabs, Accordion and Collapsible, all positioned by @floating-ui/dom and driven by the in-tree behaviors.

Every overlay takes a `trigger` snippet and renders its content from `children`; open state is a bindable `open` prop.

```pug
Dialog(title="Delete note" description="This cannot be undone.")
	+snippet('trigger')
		Btn(variant="danger" size="sm") Delete
	p Are you sure?
	+snippet('actions')
		Btn(variant="danger" onclick!="{confirm}") Delete

Popover(side="bottom" align="start")
	+snippet('trigger')
		Btn(variant="secondary") Filters
	.p-2 filter controls here

Tooltip(content="Save (⌘S)")
	+snippet('trigger')
		Btn(icon="lucide:save")

Dropdown(items!="{items}")
	+snippet('trigger')
		Btn(variant="ghost" icon="lucide:more-horizontal")
```

| Component | Notes |
|---|---|
| `Dialog` | modal with `title`, `description`, `actions` snippet, `dismissable` (overlay click and Escape, default true), `hideClose` |
| `Sheet` | side panel; `side` defaults to `'right'`, pass `'left'` for the old Drawer behaviour |
| `Popover` | `side`, `align`, `sideOffset` |
| `Dropdown` | menu from `items` (`{ label, icon, separator, disabled, onSelect }`) or custom `children` |
| `Tooltip` | `content` string, `delay`, `rich` for wider multiline styling; trigger can be a link |
| `ContextMenu` | right-click menu from `items`; nested submenus are accepted but ignored since 0.0.6 |
| `Tabs` | `items` with `panel` snippets, `value` bindable |
| `Accordion` | `items` with `content` snippets, `multiple` |
| `Collapsible` | `title` or `trigger`, `open`, `onopenchange` |

All of them use the [behaviors](/norns-ui/guide/behaviors) module underneath: portal into `body`, focus trap and scroll lock for modals, click-outside and Escape to dismiss, roving tabindex inside menus. Reuse the same actions in your own components so interactions stay consistent.

---

<!-- https://norns-docs.humansynthesis.ai/norns-tron/reference/server -->

# Server

> tronSerializer() and the helpers behind it.

```ts
import { tronSerializer, acceptsTron, TRON_CONTENT_TYPE } from '@human-synthesis/norns-tron/server';
```

| Export | Notes |
|---|---|
| `tronSerializer(opts?)` | builds a [`Serializer`](/norns/runtime/serializers) for `route()`, `setSerializer()` or `boot({ serializer })` |
| `acceptsTron(request)` | `true` when the request's `Accept` header asks for TRON |
| `TRON_CONTENT_TYPE` | `'application/tron'` |

`TronSerializerOptions` extends `EncodeOptions` with `schema?: CompiledSchema`, which skips shape detection (the fastest mode).

The serializer implements both hooks: `serialize(result, event)` returns a TRON `Response` when the client accepts it and `null` otherwise (so `route()` falls through to JSON), and `parseBody(request, contentType)` decodes `application/tron` request bodies and returns `undefined` for anything else.

---

<!-- https://norns-docs.humansynthesis.ai/norns-core/reference/vetted-subset -->

# Vetted subset

> The Civet and Pug constructs the norns-core test suite pins, and the documented traps it keeps trapped.

`norns-core` carries a test suite that compiles each construct below through Civet, the preprocessor and the Svelte compiler on every run, so an upgrade of civet, pug or svelte-preprocess cannot silently break apps written in this subset.

## Civet modules (`.c`)

| Construct | Pinned behaviour |
|---|---|
| header comments | pass through |
| `import * as dz from '...'`, `import { eq } from '...'`, default imports | emitted verbatim |
| `export x := { a: 1 }` | `export const x = { a: 1 }` |
| quoted operator keywords as object keys, `{ 'and': 1, 'or': 2, 'not': 3 }` | safe |
| JS-style async arrow bodies with braces and `return` | compile |
| template literals, including tagged (`` dz.sql`1 = 1` ``) | survive |

Traps pinned as traps:

- `x := a isnt b` does not compile to `!==` (the generated JavaScript references a bare identifier). If a Civet upgrade ever changes that, the ban can be lifted.
- `import { and } from 'drizzle-orm'` is a parse error. Use a namespace import.
- Async generator method shorthand currently compiles; it is excluded from the subset for minimalism, not breakage.

## Components (`.n`)

| Construct | Pinned behaviour |
|---|---|
| `section.norns-page` with children | `<section class="norns-page">` |
| `Kanban(data!="{data.board}" onMove="?/submit")` | attributes preserved for Svelte |
| `+if('data.ok')` / `+else` | `{#if data.ok}` / `{:else}` / `{/if}` |
| `+each('data.rows as row')` | `{#each data.rows as row}` and compiles |
| `{ data, form } := $props()` | `const { data, form } = $props()` |
| `selected := $state(null)` | `const selected = $state(null)` |
| bare Pug with no `<template>` block | auto-wrapped |
| `div.gap-2.5` | `class="gap-2.5"` (class rewriter) |

Traps pinned as traps:

- `+each('row of data.rows')` maps verbatim to `{#each row of data.rows}` and the Svelte compiler throws.
- A leading `{#if data.ok}` on a template line is not a Svelte block after Pug; prefix with `| `.

The same tables, phrased as do-and-don't rules, live on the [pitfalls](/norns/pitfalls) pages and in every app's `CLAUDE.md`.

---

<!-- https://norns-docs.humansynthesis.ai/norns/config/file-extensions -->

# File extensions

> What .n, .c and .civet mean, and why the framework did not invent a new component extension.

| Extension | Meaning |
|---|---|
| `.n` | A Svelte component with a Pug template and a Civet script. The [norns-core preprocessor](/norns-core) defaults `<script>` to `lang="civet"` and `<template>` to `lang="pug"`, wraps top-level Pug in a template block automatically, and rewrites `+if` / `+snippet` chains and class shorthand. |
| `.c` | A Civet module. Recognised everywhere `.civet` is; both compile through the same Civet compiler. |
| `.civet` | The same as `.c`, for people who prefer the long name. |

`.svelte`, `.js` and `.ts` keep working everywhere. Mixing is normal: write routes, components and feature code in `.n` / `.c`, and drop to `.js` for dense library-style code that Civet's parser dislikes (see [Civet pitfalls](/norns/pitfalls/civet)).

## Why not a `.norns` component extension

Norns keeps `.svelte` semantics and simply adds `.n` to SvelteKit's `extensions`. A truly new component format would mean forking the Svelte compiler and parser, which is high cost for no gain. `.n` and `.c` are aliases layered on `extensions` and `kit.moduleExtensions`.

## Seeing what a file compiles to

```sh
bunx norns diag src/lib/norns/notes/server/service.c    # the JS Civet emits
bunx norns diag --template src/routes/+page.n            # the Svelte source after Pug / Civet / auto-imports
```

See [check and diag](/norns/cli/check-and-diag).

---

<!-- https://norns-docs.humansynthesis.ai/norns-ui/guide/toast -->

# Toast

> Mount ToastProvider once and call toast(), notify() or dismiss() from anywhere.

```pug
//- src/routes/+layout.n
ToastProvider
| {@render children?.()}
```

```civet
import { toast, notify, dismiss } from '@human-synthesis/norns-ui/toast'

toast 'Saved', { variant: 'success' }
id := notify 'Uploading…', { duration: 0 }
dismiss id
```

`ToastOpts` is `{ variant?: 'info' | 'success' | 'warning' | 'error', duration?: number }`. `clear()` removes every toast. The store behind it is a Svelte 5 runes module (`toast.svelte.js`), so it works from `.c` modules and components alike.

`presetUI()` lists these helpers, but the auto-importer's `helpers` option replaces rather than extends the defaults, so import them explicitly (see the [auto-import options](/norns/auto-imports/options)).

---

<!-- https://norns-docs.humansynthesis.ai/norns-tron/reference/client -->

# Client

> The api wrapper, createApi, parseResponse and ApiError.

```ts
import { api, createApi, parseResponse, ApiError, TRON_CONTENT_TYPE } from '@human-synthesis/norns-tron/client';
```

## `Api`

```ts
interface Api {
  request(method: string, url: string, body?: unknown, opts?: RequestOptions): Promise<any>;
  get(url: string, opts?: RequestOptions): Promise<any>;
  del(url: string, opts?: RequestOptions): Promise<any>;
  post(url: string, body?: unknown, opts?: RequestOptions): Promise<any>;
  put(url: string, body?: unknown, opts?: RequestOptions): Promise<any>;
  patch(url: string, body?: unknown, opts?: RequestOptions): Promise<any>;
}
```

`api` is the default instance for browser code. `createApi(defaults?)` makes a new one:

| Default | Notes |
|---|---|
| `fetch` | fetch implementation; pass SvelteKit's `fetch` inside `load` functions |
| `base` | URL prefix, e.g. `'https://api.example.com'` |
| `headers` | sent on every request |

`RequestOptions` per call: `fetch`, `headers`, `init` (a raw `RequestInit`).

## `parseResponse(res)`

Decodes a `Response` by its content type: TRON, JSON, or raw text.

## `ApiError`

Thrown for non-2xx responses. `status`, `body` (decoded) and `response` (raw).

---

<!-- https://norns-docs.humansynthesis.ai/norns-ui/guide/behaviors -->

# Behaviors

> Headless Svelte 5 actions and a floating-ui factory, exported at @human-synthesis/norns-ui/behaviors.

```civet
import {
	portal, clickOutside, escape, focusTrap,
	scrollLock, useFloating, rovingTabindex
} from '@human-synthesis/norns-ui/behaviors'
```

| Export | Use as | Does |
|---|---|---|
| `portal` | `use:portal` | moves the element to `document.body` (or a target) |
| `clickOutside` | `use:clickOutside={handler}` | calls the handler on pointer-down outside the element |
| `escape` | `use:escape={handler}` | calls the handler on the Escape key |
| `focusTrap` | `use:focusTrap` | keeps Tab focus inside the element while mounted |
| `scrollLock` | `use:scrollLock` | locks body scroll while mounted |
| `rovingTabindex` | `use:rovingTabindex` | arrow-key navigation across the element's focusable children |
| `useFloating` | `useFloating(options)` | a small factory over `@floating-ui/dom` returning position state for a reference / floating pair |

Each behavior is also importable on its own from `@human-synthesis/norns-ui/behaviors/<name>.svelte.js`.

These are what every overlay in the library is built on, so building your own popover-like thing from them gives you the same keyboard and dismissal semantics for free.

```pug
.menu(use:portal use:clickOutside!="{close}" use:escape!="{close}")
	...
```

---

<!-- https://norns-docs.humansynthesis.ai/norns-tron/reference/valibot -->

# valibot

> Derive a TRON schema spec, or a compiled schema, from a valibot object schema.

```ts
import { tronSpecFromValibot, tronSchemaFromValibot } from '@human-synthesis/norns-tron/valibot';
```

| Function | Returns |
|---|---|
| `tronSpecFromValibot(objectSchema, opts?)` | a plain `SchemaSpec` (fields, enums, path) |
| `tronSchemaFromValibot(objectSchema, opts?)` | derive and compile in one step; a `CompiledSchema` |

`DeriveOptions`: `id` (version tag emitted as a `#id` line and used by `createRegistry()`) and `path` (`'$'` or e.g. `'$.data'`).

`v.picklist([...])` and `v.enum(...)` fields become dictionary columns; booleans become 0/1. Call at module scope, never per request. Requires `valibot` (optional peer, `>=0.31`).

---

<!-- https://norns-docs.humansynthesis.ai/norns-ui/guide/theming -->

# Theming

> The Tailwind v4 @theme tokens the library exposes and how to override them.

Tokens live in `src/styles/tokens.css` as a Tailwind `@theme` block, imported through `@human-synthesis/norns-ui/styles`.

| Group | Tokens |
|---|---|
| Colour scales | `primary`, `success`, `warning`, `danger`, `info`, each 50–950, in `oklch`. Use as `bg-primary-500`, `text-danger-700`, ... |
| Role tokens | `--color-fg`, `--color-fg-muted`, `--color-fg-subtle`, `--color-bg`, `--color-bg-muted`, `--color-bg-subtle`, `--color-bg-elevated`, `--color-border`, `--color-border-strong`, `--color-ring`. Atoms reference these; so should your components. They swap automatically in dark mode. |
| Feedback tokens | `--color-{success,warning,danger,info}-{bg,fg,border}` for tinted surfaces |
| Typography | `--font-sans`, `--font-mono` |
| Sizing | `--ui-radius-{sm,,lg,full}`, `--ui-h-{sm,md,lg}` (button heights), `--ui-icon-btn-{sm,md,lg}` |
| Motion | `--ui-motion-{fast,med,slow}` durations and `--ui-motion-ease`; every component transition uses them |
| Elevation | `--ui-elev-{1,2,3}` (subtle, floating, modal), deeper in dark mode |
| Focus | `--ui-focus-ring`, the one canonical focus indicator: `box-shadow: var(--ui-focus-ring)` on `:focus-visible` |

## Overriding

Re-declare in your `app.css` after the library import:

```css
@import '@human-synthesis/norns-ui/styles';

@theme {
  --color-primary-500: oklch(0.6 0.2 250);
  --font-sans: 'Inter Variable', sans-serif;
  --ui-radius-lg: 1rem;
}
```

Because the tokens are Tailwind theme variables, the generated utilities (`bg-primary-500`, `rounded-[var(--ui-radius-lg)]`) follow the override too.

---

<!-- https://norns-docs.humansynthesis.ai/norns-ui/guide/motion -->

# Motion

> Five animated components that are opt-in imports, not part of the auto-import preset.

The motion tier depends on the `motion` package and is kept out of `presetUI()` so apps that do not use it never pay for it. Import what you need:

```civet
import { Reveal, AnimatedNumber, Sparkles, GradientBackground, LiquidButton } from '@human-synthesis/norns-ui/motion'
```

```pug
Reveal(direction="up" delay!="{0.1}")
	Card ...

AnimatedNumber(value!="{stats.users}" duration!="{1.2}" decimals!="{0}")
```

| Component | Props |
|---|---|
| `Reveal` | `direction` (`up`, `down`, `left`, `right`), `distance` px, `duration` s, `delay` s, `once` (default true), `threshold` for the IntersectionObserver |
| `AnimatedNumber` | `value`, `from`, `duration`, `decimals`, `format` |
| `Sparkles` | `density`, `colors`, `minSize`, `maxSize`, wraps `children` |
| `GradientBackground` | `colors`, `duration`, `angle`, wraps `children` |
| `LiquidButton` | the `Btn` props (`variant`, `size`, `type`, `disabled`, `icon`, `onclick`) with a liquid hover effect |

`ShinyButton`, `RippleButton`, `GradientText` and `ThemeToggler` are CSS-only and live in the regular component set.

---

<!-- https://norns-docs.humansynthesis.ai/norns-ui/guide/overriding -->

# Overriding components

> Shadow any library component by file name, or extend one with class merging.

## Shadowing

`nornsAutoImport` resolves `componentDirs` before the preset map, first match wins. Put `src/lib/components/Btn.n` in your project and every `<Btn>` in your app now renders your file, with no configuration and no import changes. Copy the library file as a starting point:

```
node_modules/@human-synthesis/norns-ui/src/components/Btn.n  →  src/lib/components/Btn.n
```

The library's other components keep importing their own `Btn` through their explicit paths, so shadowing affects your markup only.

## Extending with `class`

Every component accepts `class` and merges it with `cn()` (tailwind-merge), so a utility you pass wins over the same utility in the component:

```pug
Card(class="p-8 bg-bg-subtle")
Btn(variant="primary" class="w-full") Continue
```

`cn` is exported for your own components:

```civet
import { cn } from '@human-synthesis/norns-ui/cn'

{ class: extra = '', ...rest } := $props()
classes := cn 'card p-4', extra
```

## Atoms without components

The CSS atoms (`.btn.btn-primary`, `.input`, `.card`, `.badge`, ...) work on plain elements. Use them where a component would be overkill, for example a bare `a.btn.btn-secondary(href="/")`.

---

<!-- https://norns-docs.humansynthesis.ai/norns/auto-imports -->

# Auto-imports

> Framework helpers, components, UI presets and project exports resolve by name in .n and .c files.

- [How it works](/norns/auto-imports/how-it-works) — the four resolvers, their priority, and what gets emitted.
- [Options](/norns/auto-imports/options) — every option with its default.
- [UI presets](/norns/auto-imports/ui-presets) — `presetUI()` from norns-ui and how to shadow a library component.

---

<!-- https://norns-docs.humansynthesis.ai/norns-ui/reference -->

# Reference

> The generated component reference and migration notes.

- [Component reference](/norns-ui/reference/components) — every component with its import path and prop types. Generated from the library's type shims at build time.
- [Migrating 0.0.5 → 0.0.6](/norns-ui/reference/migration-0-0-6)

`.d.ts` shims under `src/types/` are the source of the prop tables; they are hand-maintained in the library until a `svelte-package` build exists for Civet + Pug source, and `bun run check:shims` in the norns-ui repo keeps them aligned with the components.

---

<!-- https://norns-docs.humansynthesis.ai/norns-demo/ui-showcase -->

# UI showcase

> One page that renders every norns-ui component with its variants, in light and dark mode.

`src/routes/examples/ui/+page.n` (about 1,300 lines of Pug) is the live gallery for [norns-ui](/norns-ui): typography, every form control, every overlay with its trigger snippet, display and composite components, pickers, the data table and the motion tier, each with the props that matter. Toggle the theme from the page header to verify dark-mode contrast.

It is the best place to see how a component is used in practice; the [component reference](/norns-ui/reference/components) has the prop types. Splitting it into one demo per component, rendered next to each reference entry on this site, is a planned follow-up.

---

<!-- https://norns-docs.humansynthesis.ai/reference/upstream-policy -->

# Fork and release policy

> Two forks that never modify upstream, four npm packages published by hand, and the apps consumed from GitHub.

## The two forks

- `human-synthesis/norns-core` is a fork of `sveltejs/svelte`. `packages/svelte/` is an untouched mirror of upstream; `packages/norns-core/` is ours.
- `human-synthesis/norns` is a fork of `sveltejs/kit`. `packages/kit/` and the upstream `packages/adapter-*/` are untouched; `packages/norns/` is ours.

They are separate forks because their upstreams are separate repositories with independent release cycles. The forks exist to track upstream (`git fetch upstream && git merge upstream/main`) and to develop the Norns packages alongside the upstream packages in the same monorepo. **Nothing in the upstream packages is modified** beyond minimal package-manager script tweaks; every change there would be a future merge conflict.

We do not publish `svelte` or `@sveltejs/kit`. Users get those from the official packages through peer dependencies, and they never know the forks exist.

## What is published

| Published to npm | Not published |
|---|---|
| `@human-synthesis/norns-core`, `@human-synthesis/norns`, `@human-synthesis/norns-ui`, `@human-synthesis/norns-tron` | `norns-app` (consumed through `bun create`), `norns-demo` and `norns-docs` (cloned) |

Releases are manual: bump the version, verify locally (lint, check, build, the reference apps), commit and push, then publish from the package directory. Nothing is pushed or published without an explicit decision.

## Decisions baked in

- **No new component extension.** `.n` and `.c` are aliases on SvelteKit's `extensions` and `moduleExtensions`; forking the Svelte compiler for a `.norns` format would be high cost for no value.
- **Civet, not CoffeeScript** (since May 2026). Civet emits ESM-correct output and supports optional types, which removed two preprocessor passes that existed only to paper over CoffeeScript's emit.
- **norns-ui is standalone**, not a fork, and iterates faster than the framework; it only requires a compatible range of `norns` and `norns-core`.
- **Starter and demo are split** (May 2026) so each can be honest: `norns-app` is the smallest complete app, `norns-demo` is the showcase and comparison.
- **The runtime is opinionated.** Feature folders, DI, validated input and the facade boundary are the product, not syntax sugar.

---

<!-- https://norns-docs.humansynthesis.ai/norns/auto-imports/how-it-works -->

# How it works

> nornsAutoImport() is a Svelte preprocessor and a Vite plugin in one object, with four resolvers that run in priority order.

`nornsAutoImport()` returns one object that is both a Svelte preprocessor (for `.n` / `.svelte` files) and a Vite plugin (for standalone `.c` / `.civet` modules). Register the same instance in both places, because Svelte's compiler ignores the Vite hooks and Vite ignores the Svelte hooks:

```js
// svelte.config.js
import { nornsConfig } from '@human-synthesis/norns/config';
import { nornsPreprocess } from '@human-synthesis/norns/preprocess';
import { nornsAutoImport } from '@human-synthesis/norns/auto-import';

export default nornsConfig({
  preprocess: [
    ...nornsPreprocess(),
    nornsAutoImport({
      componentDirs: ['src/lib/components', 'src/routes']
    })
  ]
});
```

```js
// vite.config.js
import { nornsCivetPlugin } from '@human-synthesis/norns/vite';
import { nornsAutoImport } from '@human-synthesis/norns/auto-import';

export default {
  plugins: [
    nornsCivetPlugin(),
    nornsAutoImport(),
    sveltekit()
  ]
};
```

Keep the two option objects identical.

## The four resolvers

| Layer | Resolves | Examples |
|---|---|---|
| Helpers | Hard-coded module-name lists, optionally path-gated | `onMount` from `svelte`; `redirect` and `error` from `@sveltejs/kit`; `page` from `$app/state` in non-server files; `page`, `route`, `boot`, `Container` from `@human-synthesis/norns/server` in server files |
| Components (dir scan) | Capitalised basenames found in `componentDirs` | `<Card>` → `$lib/components/Card.svelte`; `<Game>` → `./Game.n` when the file sits next to the route |
| Components (preset map) | A bare-specifier `Record<name, importPath>` supplied by a UI library | `<Btn>` → `'@human-synthesis/norns-ui/components/Btn.n'`, used verbatim |
| Project utilities (opt-in) | Named exports (`export const X`, `export X := ...`, `export { a, b }`) found in files matching `exportGlobs` | `notes` from `$lib/norns/notes/server/public` when `exportGlobs: ['src/lib/**/public.c']` |

Resolution order is **helpers, then component dir, then component preset, then exports**. The first match wins and later matches are shadowed silently. That is deliberate: drop `src/lib/components/Btn.n` into your project and it replaces the library's `Btn` without any configuration.

`exportGlobs` is **off by default**: project code (facades, schemas, services, stores) is imported explicitly unless you opt in. The recommended opt-in is barrel scope only, `['src/lib/**/public.c']`, so a feature's internals never leak through auto-import. Server-path files (`/server/`, `*.server.*`, `+server.*`, `hooks.server.*`) are never auto-imported into client files, and a name exported from two files in the same scope is logged and excluded. Neither the starter nor the demo enables it.

The default helper modules are `svelte`, `svelte/store`, `@sveltejs/kit`, `$app/state` (non-server paths only) and `@human-synthesis/norns/server` (server paths only). A name you have already imported or declared in the file is never injected again, so explicit imports remain safe.

## What gets emitted

- Files inside `$lib` get `$lib/...` paths. Files outside `$lib` get a path relative to the importer.
- Project-utility paths are stripped of their extension (`'$lib/notes/server/public'`, not `.../public.c`); the configured `extensions` resolve the rest.
- A `.n` file that references a known component from markup but has no `<script>` block gets one prepended.
- Runes (`$state`, `$derived`, `$effect`, `$props`) are Svelte compiler globals. The plugin never touches them.

## Scope

In `.n` and `.svelte` files the plugin scans the markup and the `<script>` body. In `.c` modules it scans the JavaScript that `nornsCivetPlugin` produced, so only helpers apply: server code does not import components. The `match` regex on a helper entry gates it by file path, which is how `page` resolves to `$app/state` in a component and to the runtime's page wrapper in `+page.server.c`.

---

<!-- https://norns-docs.humansynthesis.ai/norns-ui/reference/components -->

# Component reference

> Every component with its import path and prop types, generated from the norns-ui type shims.

> [!NOTE] Generated from `src/types/*.d.ts` in `@human-synthesis/norns-ui` 0.0.13 by `scripts/gen-reference.mjs`. Do not edit this page by hand; fix the shim in norns-ui and re-run `bun run docs:components` there.

Every component under **components/** is auto-imported by name in `.n` files when the consumer wires `presetUI()` into `nornsAutoImport` (`Btn(variant="primary") Save`). Components under **motion/** are opt-in: `import { Reveal } from '@human-synthesis/norns-ui/motion'`. Snippet props (`children`, `header`, `trigger`, …) are filled with `+snippet('name')` blocks in Pug. Every component accepts `class` and merges it with `cn()`.

Live usage of every component: `norns-demo/src/routes/examples/ui/+page.n`.

## Components

[Accordion](#accordion) · [Audio](#audio) · [Autocomplete](#autocomplete) · [Avatar](#avatar) · [AvatarGroup](#avatargroup) · [Badge](#badge) · [Banner](#banner) · [Breadcrumbs](#breadcrumbs) · [Btn](#btn) · [ButtonGroup](#buttongroup) · [Calendar](#calendar) · [Card](#card) · [Carousel](#carousel) · [Checkbox](#checkbox) · [Chip](#chip) · [Collapsible](#collapsible) · [ColorPicker](#colorpicker) · [ContextMenu](#contextmenu) · [CopyButton](#copybutton) · [DataTable](#datatable) · [DatePicker](#datepicker) · [DateRangePicker](#daterangepicker) · [Dialog](#dialog) · [Dropdown](#dropdown) · [Field](#field) · [FieldGroup](#fieldgroup) · [Form](#form) · [GradientText](#gradienttext) · [Header](#header) · [HeroBanner](#herobanner) · [HierarchicalMenu](#hierarchicalmenu) · [Icon](#icon) · [Image](#image) · [Input](#input) · [MegaMenu](#megamenu) · [MultiSelect](#multiselect) · [NumberInput](#numberinput) · [OtpField](#otpfield) · [Pagination](#pagination) · [Popover](#popover) · [Progress](#progress) · [ProgressCircular](#progresscircular) · [Radio](#radio) · [RippleButton](#ripplebutton) · [ScrollArea](#scrollarea) · [Select](#select) · [Separator](#separator) · [Sheet](#sheet) · [ShinyButton](#shinybutton) · [Skeleton](#skeleton) · [Stepper](#stepper) · [Surface](#surface) · [Switch](#switch) · [Tabs](#tabs) · [TagsInput](#tagsinput) · [Textarea](#textarea) · [ThemeToggler](#themetoggler) · [Timeline](#timeline) · [TimePicker](#timepicker) · [ToastProvider](#toastprovider) · [ToggleButton](#togglebutton) · [ToggleButtonGroup](#togglebuttongroup) · [Toolbar](#toolbar) · [Tooltip](#tooltip) · [Tree](#tree) · [Uploader](#uploader) · [Video](#video) · [Window](#window)

### Accordion

`@human-synthesis/norns-ui/components/Accordion.n`

```ts
export type AccordionItem = {
	value: string;
	title: string;
	content?: Snippet;
};

export type AccordionProps = {
	items?: AccordionItem[];
	multiple?: boolean;
	value?: string | string[];
	class?: string;
};
```

### Audio

`@human-synthesis/norns-ui/components/Audio.n`

```ts
export type AudioSource = { src: string; type?: string };

export type AudioProps = {
	src?: string;
	sources?: AudioSource[];
	controls?: boolean;
	autoplay?: boolean;
	loop?: boolean;
	muted?: boolean;
	preload?: 'none' | 'metadata' | 'auto';
	fallback?: string;
	class?: string;
};
```

### Autocomplete

`@human-synthesis/norns-ui/components/Autocomplete.n`

```ts
export type ComboboxItem = { value: string; label: string };

export type AutocompleteProps = {
	items?: ComboboxItem[];
	value?: string;
	open?: boolean;
	placeholder?: string;
	disabled?: boolean;
	name?: string;
	id?: string;
	error?: boolean;
};
```

### Avatar

`@human-synthesis/norns-ui/components/Avatar.n`

```ts
export type AvatarSize = 'sm' | 'md' | 'lg' | 'xl';

export type AvatarProps = {
	src?: string;
	/** Display name; first + last initial used as fallback when `src` is missing. */
	name?: string;
	size?: AvatarSize;
	class?: string;
};
```

### AvatarGroup

`@human-synthesis/norns-ui/components/AvatarGroup.n`

```ts
export type AvatarGroupItem = { src?: string; name?: string };

export type AvatarGroupProps = {
	items?: AvatarGroupItem[];
	max?: number;
	size?: AvatarSize;
	label?: string;
	class?: string;
};
```

### Badge

`@human-synthesis/norns-ui/components/Badge.n`

```ts
export type BadgeVariant = 'default' | 'primary' | 'success' | 'warning' | 'danger' | 'info';
export type BadgeSize = 'sm' | 'md';

export type BadgeProps = {
	variant?: BadgeVariant;
	size?: BadgeSize;
	children?: Snippet;
	class?: string;
};
```

### Banner

`@human-synthesis/norns-ui/components/Banner.n`

```ts
export type BannerVariant = 'info' | 'success' | 'warning' | 'danger';

export type BannerProps = {
	variant?: BannerVariant;
	/** Iconify icon name (e.g. `"lucide:alert-triangle"`). */
	icon?: string;
	actions?: Snippet;
	children?: Snippet;
	class?: string;
};
```

### Breadcrumbs

`@human-synthesis/norns-ui/components/Breadcrumbs.n`

```ts
export type BreadcrumbItem = {
	label: string;
	href?: string;
};

export type BreadcrumbsProps = {
	items?: BreadcrumbItem[];
	separator?: string;
	class?: string;
};
```

### Btn

`@human-synthesis/norns-ui/components/Btn.n`

```ts
/**
 * Type shim for `Btn.n`. Hand-rolled until we have a proper
 * `svelte-package` build over the Civet+Pug source.
 */


export type BtnVariant = 'primary' | 'secondary' | 'ghost' | 'danger' | 'link';
export type BtnSize = 'sm' | 'md' | 'lg';

export type BtnProps = Omit<HTMLButtonAttributes, 'class' | 'children'> & {
	variant?: BtnVariant;
	size?: BtnSize;
	loading?: boolean;
	disabled?: boolean;
	type?: 'button' | 'submit' | 'reset';
	/**
	 * Convenience: Iconify icon name (e.g. `"lucide:save"`). Renders an
	 * `<Icon>` in the leading slot. If you also pass a `leading` snippet,
	 * the snippet wins.
	 */
	icon?: string;
	/** When set, renders as an `<a>` styled like the button. */
	href?: string;
	target?: string;
	rel?: string;
	class?: string;
	children?: Snippet;
	leading?: Snippet;
	trailing?: Snippet;
};
```

### ButtonGroup

`@human-synthesis/norns-ui/components/ButtonGroup.n`

```ts
export type ButtonGroupProps = {
	orientation?: 'horizontal' | 'vertical';
	children?: Snippet;
	class?: string;
};
```

### Calendar

`@human-synthesis/norns-ui/components/Calendar.n`

```ts
export type CalendarDateRange = { start: string; end: string };

export type CalendarProps = {
	/** ISO YYYY-MM-DD. Bindable. */
	value?: string;
	/** Range mode. Bindable. Use instead of `value` when `range` is true. */
	rangeValue?: CalendarDateRange;
	range?: boolean;
	/** ISO YYYY-MM-DD inclusive. */
	min?: string;
	max?: string;
	label?: string;
	onchange?: (next: string | CalendarDateRange) => void;
	class?: string;
};
```

### Card

`@human-synthesis/norns-ui/components/Card.n`

```ts
export type CardProps = {
	/** Wrap body in `.card-body` (default true). Set false for full-bleed content. */
	padded?: boolean;
	/** Apply `.card-interactive` hover/focus treatment. Implicit if `href` is set. */
	interactive?: boolean;
	/** Renders as `<a>` instead of `<div>` when set. */
	href?: string;
	target?: string;
	rel?: string;
	header?: Snippet;
	footer?: Snippet;
	children?: Snippet;
	class?: string;
};
```

### Carousel

`@human-synthesis/norns-ui/components/Carousel.n`

```ts
export type CarouselSlide = {
	src?: string;
	alt?: string;
	[key: string]: unknown;
};

export type CarouselProps = {
	slides?: CarouselSlide[];
	index?: number;
	autoplay?: boolean;
	/** Autoplay interval in milliseconds. Default 5000. */
	interval?: number;
	/** Default aspect ratio applied if no explicit `class="aspect-..."` is passed. */
	aspect?: 'video' | 'square' | 'wide' | 'none';
	/** Custom slide renderer; receives `(slide, i)` and runs only for slides without `src`. */
	children?: Snippet<[CarouselSlide, number]>;
	class?: string;
};
```

### Checkbox

`@human-synthesis/norns-ui/components/Checkbox.n`

```ts
export type CheckboxProps = Omit<HTMLInputAttributes, 'class' | 'type' | 'checked'> & {
	checked?: boolean;
	error?: boolean;
	class?: string;
};
```

### Chip

`@human-synthesis/norns-ui/components/Chip.n`

```ts
export type ChipProps = {
	icon?: string;
	removable?: boolean;
	onremove?: (event: MouseEvent) => void;
	children?: Snippet;
	class?: string;
};
```

### Collapsible

`@human-synthesis/norns-ui/components/Collapsible.n`

```ts
export type CollapsibleProps = {
	open?: boolean;
	title?: string;
	trigger?: Snippet;
	children?: Snippet;
	onopenchange?: (open: boolean) => void;
	class?: string;
};
```

### ColorPicker

`@human-synthesis/norns-ui/components/ColorPicker.n`

```ts
export type ColorPickerProps = {
	/** Hex value with leading `#`. Bindable. */
	value?: string;
	disabled?: boolean;
	/** Hide the clipboard-copy button. */
	hideCopy?: boolean;
	name?: string;
	id?: string;
	class?: string;
};
```

### ContextMenu

`@human-synthesis/norns-ui/components/ContextMenu.n`

```ts
export type ContextMenuItem = {
	label?: string;
	icon?: string;
	separator?: boolean;
	disabled?: boolean;
	onSelect?: () => void;
	/**
	 * NOTE: nested submenus are not supported in 0.0.6+ (the property is
	 * accepted but children are ignored). Re-introduce when the upstream
	 * design needs them.
	 */
	children?: ContextMenuItem[];
};

export type ContextMenuProps = {
	items?: ContextMenuItem[];
	trigger?: Snippet;
	triggerClass?: string;
};
```

### CopyButton

`@human-synthesis/norns-ui/components/CopyButton.n`

```ts
export type CopyButtonProps = {
	value?: string | number;
	variant?: 'primary' | 'secondary' | 'ghost' | 'danger' | 'link';
	size?: 'sm' | 'md' | 'lg';
	icon?: string;
	disabled?: boolean;
	label?: string;
	oncopy?: (value: string | number) => void;
	children?: Snippet;
	class?: string;
};
```

### DataTable

`@human-synthesis/norns-ui/components/DataTable.n`

```ts
export type DataTableColumn = {
	key: string;
	label?: string;
	width?: string;
	class?: string;
	cellClass?: string;
	sortable?: boolean;
};

export type DataTableProps = {
	columns?: DataTableColumn[];
	rows?: Record<string, unknown>[];
	striped?: boolean;
	dense?: boolean;
	stickyHeader?: boolean;
	emptyMessage?: string;
	/** Currently-sorted column key. Bindable. */
	sortKey?: string;
	sortDir?: 'asc' | 'desc';
	onrowclick?: (row: Record<string, unknown>, index: number) => void;
	class?: string;
};
```

### DatePicker

`@human-synthesis/norns-ui/components/DatePicker.n`

```ts
export type DatePickerProps = {
	/** ISO date string (YYYY-MM-DD). Bindable. */
	value?: string;
	/** Whether the popover is open. Bindable. */
	open?: boolean;
	min?: string;
	max?: string;
	placeholder?: string;
	disabled?: boolean;
	/** Close the popover automatically once a date is picked (default true). */
	closeOnSelect?: boolean;
	/** aria-label override; defaults to "Pick a date". */
	label?: string;
	name?: string;
	id?: string;
	error?: boolean;
	class?: string;
};
```

### DateRangePicker

`@human-synthesis/norns-ui/components/DateRangePicker.n`

```ts
export type DateRange = { start: string; end: string };

export type DateRangePickerProps = {
	value?: DateRange;
	/** Whether the popover is open. Bindable. */
	open?: boolean;
	min?: string;
	max?: string;
	placeholder?: string;
	disabled?: boolean;
	class?: string;
};
```

### Dialog

`@human-synthesis/norns-ui/components/Dialog.n`

```ts
export type DialogProps = {
	open?: boolean;
	title?: string;
	description?: string;
	hideClose?: boolean;
	/** Close on overlay click and Escape. Default true. */
	dismissable?: boolean;
	/** Used as `aria-label` on the dialog when no `title` is provided. */
	ariaLabel?: string;
	trigger?: Snippet;
	actions?: Snippet;
	children?: Snippet;
	triggerClass?: string;
	overlayClass?: string;
	class?: string;
};
```

### Dropdown

`@human-synthesis/norns-ui/components/Dropdown.n`

```ts
export type DropdownItem = {
	label?: string;
	icon?: string;
	separator?: boolean;
	disabled?: boolean;
	onSelect?: () => void;
};

export type DropdownProps = {
	open?: boolean;
	side?: 'top' | 'right' | 'bottom' | 'left';
	align?: 'start' | 'center' | 'end';
	sideOffset?: number;
	items?: DropdownItem[];
	trigger?: Snippet;
	children?: Snippet;
	triggerClass?: string;
	class?: string;
};
```

### Field

`@human-synthesis/norns-ui/components/Field.n`

```ts
export type FieldProps = {
	/** Label text rendered above the control. Used as id-derivation fallback if no `id`/`name` is given. */
	label?: string;
	/** Helper text shown below the control when there's no error. */
	help?: string;
	/**
	 * Explicit error message. Overrides any auto-resolved error from the
	 * parent `<Form form={...}>` context. Switches the inner control to
	 * error styling.
	 */
	error?: string;
	/**
	 * Field name — used to look up an auto-error from the parent `<Form>`
	 * context (matching `form.errors[*].path[0].key`) and as the default
	 * id for the inner control. When set, an inner `<Input>` doesn't need
	 * an explicit `name=` either if it inherits from this Field.
	 */
	name?: string;
	/** Adds a red asterisk after the label. Cosmetic; pair with `required` on the actual input. */
	required?: boolean;
	/** Explicit id for the control. Otherwise: `name`, then slugified `label`, then undefined. */
	id?: string;
	/** Optional class merged into the field wrapper. */
	class?: string;
	/** Snippet that renders the actual control. Children should call `<Input />`, `<Textarea />`, etc. */
	children?: Snippet;
};
```

### FieldGroup

`@human-synthesis/norns-ui/components/FieldGroup.n`

```ts
export type FieldGroupProps = {
	/** Optional legend text rendered as the fieldset's `<legend>`. */
	legend?: string;
	class?: string;
	children?: Snippet;
};
```

### Form

`@human-synthesis/norns-ui/components/Form.n`

```ts
/**
 * The shape returned by `fail(400, { errors, values })` from a SvelteKit
 * action — what `+page.server.c`'s `page.actions` produces on validation
 * failure (or a manually-constructed equivalent). `errors` is a valibot
 * issue list; `values` is the raw form data echoed back for re-rendering.
 */
export type FormActionResult = {
	errors?: Array<{ path?: Array<{ key?: string }>; message: string }>;
	values?: Record<string, string>;
} | null | undefined;

export type FormProps = Omit<HTMLFormAttributes, 'class' | 'children'> & {
	method?: 'GET' | 'POST';
	action?: string;
	enctype?: 'application/x-www-form-urlencoded' | 'multipart/form-data' | 'text/plain';
	/**
	 * Pass the page's `form` prop here. Form derives a `name → message` errors
	 * map and exposes it via context so descendant `<Field name="...">` looks
	 * up its own error automatically.
	 */
	form?: FormActionResult;
	class?: string;
	children?: Snippet;
};
```

### GradientText

`@human-synthesis/norns-ui/components/GradientText.n`

```ts
export type GradientTextProps = {
	/** Start color. Default `var(--color-primary-500)`. Accepts any CSS color. */
	from?: string;
	/** End color. Default `var(--color-info-500)`. */
	to?: string;
	/** Optional middle stop. */
	via?: string;
	/** Animate the gradient via background-position keyframes. Default true. */
	animate?: boolean;
	/** Gradient angle in degrees. Default 90. */
	angle?: number;
	children?: Snippet;
	class?: string;
};
```

### Header

`@human-synthesis/norns-ui/components/Header.n`

```ts
export type HeaderProps = {
	sticky?: boolean;
	brand?: Snippet;
	nav?: Snippet;
	actions?: Snippet;
	class?: string;
};
```

### HeroBanner

`@human-synthesis/norns-ui/components/HeroBanner.n`

```ts
export type HeroBannerProps = {
	title: string;
	description?: string;
	/** Background/decorative image src; rendered with reduced opacity behind the content. */
	image?: string;
	align?: 'left' | 'center';
	/** Apply animated `GradientText` to the title. Default false. */
	gradient?: boolean;
	actions?: Snippet;
	children?: Snippet;
	class?: string;
};
```

### HierarchicalMenu

`@human-synthesis/norns-ui/components/HierarchicalMenu.n`

```ts
export type HierarchicalMenuItem = {
	label: string;
	href?: string;
	icon?: string;
	description?: string;
	children?: HierarchicalMenuItem[];
};

export type HierarchicalMenuProps = {
	items?: HierarchicalMenuItem[];
	/** aria-label for the <nav> wrapper. */
	label?: string;
	onSelect?: (item: HierarchicalMenuItem) => void;
	class?: string;
};
```

### Icon

`@human-synthesis/norns-ui/components/Icon.n`

```ts
export type IconProps = {
	/**
	 * Iconify icon name in `<set>:<name>` form, e.g. `"lucide:check"` or
	 * `"mdi:home"`. The `@iconify-json/lucide` package ships with the library;
	 * other sets can be installed alongside (`@iconify-json/heroicons`, etc.).
	 */
	name: string;
	/**
	 * Tailwind size utility for the icon, e.g. `"size-4"`, `"size-5"`. Default
	 * `"size-4"`. Pass any class string accepted by Tailwind.
	 */
	size?: string;
	flip?: 'horizontal' | 'vertical' | 'horizontal,vertical';
	rotate?: 90 | 180 | 270 | string;
	class?: string;
};
```

### Image

`@human-synthesis/norns-ui/components/Image.n`

```ts
export type ImageProps = {
	src: string;
	alt?: string;
	loading?: 'lazy' | 'eager';
	fit?: 'cover' | 'contain' | 'fill' | 'none' | 'scale-down';
	rounded?: boolean | 'sm' | 'md' | 'lg' | 'full';
	width?: number | string;
	height?: number | string;
	class?: string;
};
```

### Input

`@human-synthesis/norns-ui/components/Input.n`

```ts
export type InputSize = 'sm' | 'md' | 'lg';
export type InputType =
	| 'text'
	| 'email'
	| 'password'
	| 'number'
	| 'tel'
	| 'url'
	| 'search'
	| 'date'
	| 'time'
	| 'datetime-local'
	| 'month'
	| 'week';

export type InputProps = Omit<HTMLInputAttributes, 'class' | 'type' | 'size' | 'value'> & {
	value?: string | number;
	type?: InputType;
	size?: InputSize;
	/** Force the error styling regardless of the parent Field's error state. */
	error?: boolean;
	class?: string;
};
```

### MegaMenu

`@human-synthesis/norns-ui/components/MegaMenu.n`

```ts
export type MegaMenuItem = {
	label: string;
	href?: string;
	icon?: string;
	description?: string;
};

export type MegaMenuColumn = {
	title?: string;
	items: MegaMenuItem[];
};

export type MegaMenuSection = {
	label: string;
	cols?: 2 | 3 | 4;
	columns: MegaMenuColumn[];
};

export type MegaMenuProps = {
	sections?: MegaMenuSection[];
	/** aria-label for the <nav> wrapper. */
	label?: string;
	class?: string;
};
```

### MultiSelect

`@human-synthesis/norns-ui/components/MultiSelect.n`

```ts
export type MultiSelectProps = {
	items?: ComboboxItem[];
	value?: string[];
	open?: boolean;
	placeholder?: string;
	disabled?: boolean;
	name?: string;
	id?: string;
	error?: boolean;
};
```

### NumberInput

`@human-synthesis/norns-ui/components/NumberInput.n`

```ts
export type NumberInputProps = {
	value?: number;
	min?: number;
	max?: number;
	stepSize?: number;
	disabled?: boolean;
	readonly?: boolean;
	name?: string;
	id?: string;
	error?: boolean;
	class?: string;
};
```

### OtpField

`@human-synthesis/norns-ui/components/OtpField.n`

```ts
export type OtpFieldProps = {
	value?: string;
	length?: number;
	mask?: boolean;
	label?: string;
	oncomplete?: (value: string) => void;
	class?: string;
};
```

### Pagination

`@human-synthesis/norns-ui/components/Pagination.n`

```ts
export type PaginationProps = {
	page?: number;
	total?: number;
	pageSize?: number;
	/** How many pages to show on each side of the current. Default 1. */
	siblingCount?: number;
	class?: string;
};
```

### Popover

`@human-synthesis/norns-ui/components/Popover.n`

```ts
export type PopoverSide = 'top' | 'right' | 'bottom' | 'left';
export type PopoverAlign = 'start' | 'center' | 'end';

export type PopoverProps = {
	open?: boolean;
	side?: PopoverSide;
	align?: PopoverAlign;
	sideOffset?: number;
	trigger?: Snippet;
	children?: Snippet;
	triggerClass?: string;
	class?: string;
};
```

### Progress

`@human-synthesis/norns-ui/components/Progress.n`

```ts
export type ProgressVariant = 'primary' | 'success' | 'warning' | 'danger';

export type ProgressProps = {
	value?: number;
	max?: number;
	variant?: ProgressVariant;
	indeterminate?: boolean;
	class?: string;
};
```

### ProgressCircular

`@human-synthesis/norns-ui/components/ProgressCircular.n`

```ts
export type ProgressCircularSize = 'sm' | 'md' | 'lg';

export type ProgressCircularProps = {
	value?: number;
	max?: number;
	size?: ProgressCircularSize;
	indeterminate?: boolean;
	class?: string;
};
```

### Radio

`@human-synthesis/norns-ui/components/Radio.n`

```ts
export type RadioProps = Omit<HTMLInputAttributes, 'class' | 'type'> & {
	/** Two-way bound shared group value — pass `bind:group={selected}` from parent. */
	group?: string;
	value?: string;
	error?: boolean;
	class?: string;
};
```

### RippleButton

`@human-synthesis/norns-ui/components/RippleButton.n`

```ts
export type RippleButtonProps = {
	variant?: 'primary' | 'secondary' | 'ghost' | 'danger' | 'link';
	size?: 'sm' | 'md' | 'lg';
	type?: 'button' | 'submit' | 'reset';
	disabled?: boolean;
	onclick?: (event: MouseEvent) => void;
	icon?: string;
	children?: Snippet;
	class?: string;
};
```

### ScrollArea

`@human-synthesis/norns-ui/components/ScrollArea.n`

```ts
export type ScrollAreaProps = {
	/** Allow horizontal scrolling instead of just vertical. */
	horizontal?: boolean;
	children?: Snippet;
	class?: string;
};
```

### Select

`@human-synthesis/norns-ui/components/Select.n`

```ts
export type SelectProps = Omit<HTMLSelectAttributes, 'class' | 'value' | 'children'> & {
	value?: string | number | string[];
	error?: boolean;
	class?: string;
	/** `<option>` children. Pass via Pug body. */
	children?: Snippet;
};
```

### Separator

`@human-synthesis/norns-ui/components/Separator.n`

```ts
export type SeparatorProps = {
	orientation?: 'horizontal' | 'vertical';
	class?: string;
};
```

### Sheet

`@human-synthesis/norns-ui/components/Sheet.n`

```ts
export type SheetSide = 'top' | 'right' | 'bottom' | 'left';

export type SheetProps = {
	open?: boolean;
	/** `'left'` was previously the default for the now-removed `<Drawer>`. */
	side?: SheetSide;
	title?: string;
	description?: string;
	hideClose?: boolean;
	dismissable?: boolean;
	ariaLabel?: string;
	trigger?: Snippet;
	actions?: Snippet;
	children?: Snippet;
	triggerClass?: string;
	overlayClass?: string;
	class?: string;
};
```

### ShinyButton

`@human-synthesis/norns-ui/components/ShinyButton.n`

```ts
export type ShinyButtonProps = {
	variant?: 'primary' | 'secondary' | 'ghost' | 'danger' | 'link';
	size?: 'sm' | 'md' | 'lg';
	type?: 'button' | 'submit' | 'reset';
	disabled?: boolean;
	onclick?: (event: MouseEvent) => void;
	icon?: string;
	children?: Snippet;
	class?: string;
};
```

### Skeleton

`@human-synthesis/norns-ui/components/Skeleton.n`

```ts
export type SkeletonVariant = 'rect' | 'text' | 'circle';

export type SkeletonProps = {
	variant?: SkeletonVariant;
	width?: number | string;
	height?: number | string;
	class?: string;
};
```

### Stepper

`@human-synthesis/norns-ui/components/Stepper.n`

```ts
export type StepperStep = {
	id?: string;
	label: string;
	complete?: boolean;
	current?: boolean;
};

export type StepperProps = {
	steps?: StepperStep[];
	/** Index of the active step. Steps before are auto-marked complete unless overridden. */
	current?: number;
	orientation?: 'horizontal' | 'vertical';
	class?: string;
};
```

### Surface

`@human-synthesis/norns-ui/components/Surface.n`

```ts
export type SurfaceProps = {
	tone?: 'glass';
	children?: Snippet;
	class?: string;
};
```

### Switch

`@human-synthesis/norns-ui/components/Switch.n`

```ts
export type SwitchProps = Omit<HTMLInputAttributes, 'class' | 'type' | 'checked' | 'role'> & {
	checked?: boolean;
	error?: boolean;
	class?: string;
};
```

### Tabs

`@human-synthesis/norns-ui/components/Tabs.n`

```ts
export type TabsItem = {
	value: string;
	label: string;
	panel?: Snippet;
	disabled?: boolean;
};

export type TabsProps = {
	value?: string;
	items?: TabsItem[];
	/** ARIA label for the tablist. Default 'Tabs'. */
	label?: string;
	class?: string;
};
```

### TagsInput

`@human-synthesis/norns-ui/components/TagsInput.n`

```ts
export type TagsInputProps = {
	value?: string[];
	max?: number;
	placeholder?: string;
	commitOnBlur?: boolean;
	separators?: string[];
	disabled?: boolean;
	name?: string;
	id?: string;
	error?: boolean;
	class?: string;
};
```

### Textarea

`@human-synthesis/norns-ui/components/Textarea.n`

```ts
export type TextareaProps = Omit<HTMLTextareaAttributes, 'class' | 'value' | 'rows'> & {
	value?: string;
	rows?: number;
	error?: boolean;
	class?: string;
};
```

### ThemeToggler

`@human-synthesis/norns-ui/components/ThemeToggler.n`

```ts
export type ThemeTogglerProps = {
	variant?: 'primary' | 'secondary' | 'ghost' | 'danger' | 'link';
	size?: 'sm' | 'md' | 'lg';
	showLabel?: boolean;
	labelLight?: string;
	labelDark?: string;
	lightIcon?: string;
	darkIcon?: string;
	/** localStorage key. Default `'norns-theme'`. */
	storageKey?: string;
	class?: string;
};
```

### Timeline

`@human-synthesis/norns-ui/components/Timeline.n`

```ts
export type TimelineItem = {
	time?: string;
	title?: string;
	description?: string;
	icon?: string;
	variant?: 'primary' | 'success' | 'warning' | 'danger' | 'info';
};

export type TimelineProps = {
	items?: TimelineItem[];
	class?: string;
};
```

### TimePicker

`@human-synthesis/norns-ui/components/TimePicker.n`

```ts
export type TimePickerProps = {
	/** Time string `HH:MM` (24h regardless of display `hourCycle`). Bindable. */
	value?: string;
	open?: boolean;
	/** Minute increment in the picker (5, 10, 15, 30). Default 5. */
	minuteStep?: number;
	hourCycle?: 12 | 24;
	placeholder?: string;
	disabled?: boolean;
	label?: string;
	name?: string;
	id?: string;
	error?: boolean;
	class?: string;
};
```

### ToastProvider

`@human-synthesis/norns-ui/components/ToastProvider.n`

```ts
export type ToastVariant = 'info' | 'success' | 'warning' | 'error';

export type ToastProviderProps = {
	class?: string;
};

export type ToastOpts = {
	variant?: ToastVariant;
	duration?: number;
};
```

### ToggleButton

`@human-synthesis/norns-ui/components/ToggleButton.n`

```ts
export type ToggleButtonProps = {
	pressed?: boolean;
	disabled?: boolean;
	icon?: string;
	/** Any `.btn-*` variant. The toggle visual state is controlled by `data-pressed`. */
	variant?: 'primary' | 'secondary' | 'ghost' | 'danger' | 'link';
	size?: 'sm' | 'md' | 'lg';
	onpressedchange?: (pressed: boolean) => void;
	children?: Snippet;
	class?: string;
};
```

### ToggleButtonGroup

`@human-synthesis/norns-ui/components/ToggleButtonGroup.n`

```ts
export type ToggleGroupItem = {
	value: string;
	label?: string;
	icon?: string;
	iconOnly?: boolean;
	disabled?: boolean;
};

export type ToggleButtonGroupProps = {
	items?: ToggleGroupItem[];
	value?: string | string[] | undefined;
	multiple?: boolean;
	disabled?: boolean;
	label?: string;
	class?: string;
};
```

### Toolbar

`@human-synthesis/norns-ui/components/Toolbar.n`

```ts
export type ToolbarProps = {
	orientation?: 'horizontal' | 'vertical';
	/** Accessible label, used as aria-label. */
	label?: string;
	children?: Snippet;
	class?: string;
};
```

### Tooltip

`@human-synthesis/norns-ui/components/Tooltip.n`

```ts
export type TooltipProps = {
	content?: string;
	side?: 'top' | 'right' | 'bottom' | 'left';
	align?: 'start' | 'center' | 'end';
	sideOffset?: number;
	delay?: number;
	/** Wider, surface-elevated styling for tooltips with markup/multiline content. */
	rich?: boolean;
	trigger?: Snippet;
	children?: Snippet;
	triggerClass?: string;
	class?: string;
};
```

### Tree

`@human-synthesis/norns-ui/components/Tree.n`

```ts
export type TreeNode = {
	id: string | number;
	label: string;
	icon?: string;
	children?: TreeNode[];
};

export type TreeProps = {
	items?: TreeNode[];
	/** Array of node ids that are expanded. Bindable. */
	expanded?: (string | number)[];
	/** Currently-selected node id. Bindable. */
	selected?: string | number;
	class?: string;
};
```

### Uploader

`@human-synthesis/norns-ui/components/Uploader.n`

```ts
export type UploaderProps = {
	files?: File[];
	multiple?: boolean;
	accept?: string;
	disabled?: boolean;
	placeholder?: string;
	helper?: string;
	onchange?: (files: File[]) => void;
	class?: string;
};
```

### Video

`@human-synthesis/norns-ui/components/Video.n`

```ts
export type VideoSource = { src: string; type?: string };

export type VideoProps = {
	src?: string;
	sources?: VideoSource[];
	controls?: boolean;
	autoplay?: boolean;
	loop?: boolean;
	muted?: boolean;
	playsinline?: boolean;
	preload?: 'none' | 'metadata' | 'auto';
	poster?: string;
	fallback?: string;
	class?: string;
};
```

### Window

`@human-synthesis/norns-ui/components/Window.n`

```ts
export type WindowProps = {
	/** Header title (truncated). */
	title?: string;
	/** Remove the whole header bar; keeps the rounded shell. */
	hideHeader?: boolean;
	/** When set, renders a `lucide:x` close button (marked `.nodrag`). */
	onClose?: () => void;
	/** Fires on double-click over the header bar (e.g. maximise). */
	onHeaderDoubleClick?: (event: MouseEvent) => void;
	/** Extra header controls, rendered before the close button. */
	actions?: Snippet;
	children?: Snippet;
	/** Classes for the outer shell — pass dimensions here (`w-[520px] h-[380px]`). */
	class?: string;
	/** Classes for the body section. */
	bodyClass?: string;
};
```

## Motion (opt-in)

[AnimatedNumber](#animatednumber) · [GradientBackground](#gradientbackground) · [LiquidButton](#liquidbutton) · [Reveal](#reveal) · [Sparkles](#sparkles)

### AnimatedNumber

`import { AnimatedNumber } from '@human-synthesis/norns-ui/motion'`

```ts
export type AnimatedNumberProps = {
	value: number;
	from?: number;
	/** Duration in seconds. */
	duration?: number;
	decimals?: number;
	/** Custom number-to-string formatter. */
	format?: (n: number) => string;
	class?: string;
};
```

### GradientBackground

`import { GradientBackground } from '@human-synthesis/norns-ui/motion'`

```ts
export type GradientBackgroundProps = {
	colors?: string[];
	/** Loop duration in seconds. Default 18. */
	duration?: number;
	/** Gradient angle. Default 130. */
	angle?: number;
	children?: Snippet;
	class?: string;
};
```

### LiquidButton

`import { LiquidButton } from '@human-synthesis/norns-ui/motion'`

```ts
export type LiquidButtonProps = {
	variant?: 'primary' | 'secondary' | 'ghost' | 'danger' | 'link';
	size?: 'sm' | 'md' | 'lg';
	type?: 'button' | 'submit' | 'reset';
	disabled?: boolean;
	onclick?: (event: MouseEvent) => void;
	icon?: string;
	children?: Snippet;
	class?: string;
};
```

### Reveal

`import { Reveal } from '@human-synthesis/norns-ui/motion'`

```ts
export type RevealProps = {
	direction?: 'up' | 'down' | 'left' | 'right';
	/** Travel distance in pixels. Default 12. */
	distance?: number;
	/** Animation duration in seconds. Default 0.5. */
	duration?: number;
	/** Delay before animating, seconds. Default 0. */
	delay?: number;
	/** Re-trigger on every entry (false) or just the first time (true). Default true. */
	once?: boolean;
	/** IntersectionObserver threshold (0–1). Default 0.15. */
	threshold?: number;
	children?: Snippet;
	class?: string;
};
```

### Sparkles

`import { Sparkles } from '@human-synthesis/norns-ui/motion'`

```ts
export type SparklesProps = {
	density?: number;
	colors?: string[];
	minSize?: number;
	maxSize?: number;
	children?: Snippet;
	class?: string;
};
```

---

<!-- https://norns-docs.humansynthesis.ai/norns/auto-imports/options -->

# Options

> Every nornsAutoImport() option with its default.

| Option | Default | Notes |
|---|---|---|
| `helpers` | the five default modules | Pass `false` to disable. Each entry is `{ from, imports: [...], match? }` where `match` is a regex tested against the file name. Passing your own list **replaces** the defaults. |
| `componentDirs` | `['src/lib/components']` | Directories scanned for capitalised component files. `false` or `[]` disables the scan. |
| `componentExtensions` | `['.svelte', '.n']` | |
| `components` | `null` | `Record<name, importPath>` — a bare-specifier preset map, typically `presetUI().components`. |
| `exportGlobs` | `[]` | Off by default. Project-relative glob patterns (POSIX separators) for files to scan for named exports; opt in with e.g. `['src/lib/**/public.c']`. Replaced the older `exportDirs` in 0.0.11. |
| `exportExtensions` | `['.c', '.civet', '.js']` | `.ts` is excluded: regex scanning cannot tell value exports from type-only ones under `verbatimModuleSyntax`. |
| `libRoot` | `'src/lib'` | Project-relative root that `libAlias` maps to. |
| `libAlias` | `'$lib'` | Alias prefix emitted in import paths. |
| `root` | `process.cwd()` | Project root. |

## Notes on `exportGlobs`

SvelteKit route and hook files (`+*`, `hooks.*`) are excluded from the export scan, because their named exports (`load`, `actions`, `handle`, ...) are consumed by the framework and must never be imported. Server-path files are never auto-imported into client files, and a name exported from two files in the same scope is logged and excluded rather than guessed.

The starter and demo leave `exportGlobs` off and import project code explicitly (`import { notes } from '$lib/norns/notes/server/public'`). Only framework helpers and components are auto-imported there. Both styles are supported; explicit imports keep the dependency graph visible, which is why the reference apps use them. If you opt in, keep the scope to barrels (`public.c`) so a feature's internals stay private.

## Notes on `helpers`

Because `helpers` replaces the default list, a UI library's helpers (for example `toast()` from norns-ui) cannot be merged in today without restating the defaults. A `presets` or `additionalHelpers` option that extends instead of replacing is a planned follow-up; until then, presets deliver components only and you import `toast` explicitly.

---

<!-- https://norns-docs.humansynthesis.ai/norns-ui/reference/migration-0-0-6 -->

# Migrating 0.0.5 → 0.0.6

> Bits UI was removed in 0.0.6; overlays moved to @floating-ui/dom plus the in-tree behaviors.

Most APIs are unchanged. The breaking changes:

- `<Drawer>` is gone. Use `<Sheet side="left">`; `Sheet` now defaults to `'right'`, so pass the side you want.
- `<RichTooltip>` is gone. Use `<Tooltip rich>`.
- `<PreviewCard>` is gone. Use `<Tooltip rich>` with the trigger as a link:

  ```pug
  Tooltip(rich!="{true}" content="...")
  	+snippet('trigger')
  		a(href="/profile") @daniel
  ```

- `<ContextMenu>` no longer renders nested submenus. The `children` field on items is accepted but ignored.
- The `scopeToProject` wrapper in `svelte.config.js` is no longer needed. It existed only to keep svelte-preprocess from corrupting Bits UI's TypeScript source; remove it.

---

<!-- https://norns-docs.humansynthesis.ai/norns/auto-imports/ui-presets -->

# UI presets

> A preset is a function returning a components map; compose it with your own options and shadow any component by file name.

A preset returns a config slice, usually just a `components` map. norns-ui ships one:

```js
// vite.config.js and svelte.config.js
import { presetUI } from '@human-synthesis/norns-ui/auto-import';

const ui = presetUI();

nornsAutoImport({
  componentDirs: ['src/lib/components', 'src/routes'],
  components: ui.components   // { Btn: '@human-synthesis/norns-ui/components/Btn.n', ... }
});
```

After that, every norns-ui component is available by name in `.n` files:

```pug
Form(action="?/save" form!="{form}")
  Field(label="Title" name="title" required)
    Input(name="title" required)
  Btn(type="submit" variant="primary" icon="lucide:save") Save
```

## Shadowing a library component

`componentDirs` resolves before the preset map. Put `src/lib/components/Btn.n` in your project and every `<Btn>` now points at your file, silently. Use this to restyle or extend a component without forking the library.

## Helpers from presets

`presetUI()` also returns a `helpers` entry (`toast`, `notify`, `dismiss` from `@human-synthesis/norns-ui/toast`), but because the `helpers` option replaces the defaults it is not wired in by default. Import those explicitly for now; see the note on the [options](/norns/auto-imports/options) page.

---

<!-- https://norns-docs.humansynthesis.ai/norns-demo/deploy -->

# Deploy

> The Workers + D1 configuration and the GitHub Actions workflow that applies migrations and deploys on push.

`wrangler.toml`:

```toml
name = "norns-demo"
main = ".svelte-kit/cloudflare/_worker.js"
compatibility_date = "2026-04-01"
compatibility_flags = ["nodejs_als", "nodejs_compat"]

routes = [
	{ pattern = "norns-demo.humansynthesis.ai", custom_domain = true }
]

[assets]
directory = ".svelte-kit/cloudflare"
binding = "ASSETS"

[observability]
enabled = true

[[d1_databases]]
binding = "DB"
database_name = "norns-demo-notes"
database_id = "<output of wrangler d1 create>"
migrations_dir = "migrations/notes"
```

`.github/workflows/deploy.yml` runs on every push to `main`: `bun install`, `bun run lint`, `bun run build`, then `wrangler d1 migrations apply norns-demo-notes --remote` and `wrangler deploy` through `cloudflare/wrangler-action`. It needs two repository secrets, `CLOUDFLARE_API_TOKEN` (Workers Scripts: Edit and D1: Edit) and `CLOUDFLARE_ACCOUNT_ID`.

By hand, with a logged-in wrangler:

```sh
bun run db:migrate:remote
bun run deploy           # bun run build && wrangler deploy
```

The general recipe is on the [Cloudflare Workers](/norns/deploy/cloudflare) page.

---

<!-- https://norns-docs.humansynthesis.ai/norns/runtime -->

# Runtime

> The server layer exported from @human-synthesis/norns/server — boot, the container, the page and route wrappers, validation, serializers and request scope.

Everything on these pages is exported from `@human-synthesis/norns/server` and auto-imported in server files:

| Export | Page |
|---|---|
| `boot`, `createApp` | [Boot](/norns/runtime/boot) |
| `Container`, `createContainer` | [Container](/norns/runtime/container) |
| `page` | [Page wrappers](/norns/runtime/page-wrappers) |
| `route`, `setSerializer`, `getSerializer` | [route()](/norns/runtime/route), [Serializers](/norns/runtime/serializers) |
| `validate`, `ValidationError` | [Validation](/norns/runtime/validation) |
| `withScope`, `getScope`, `getContainer`, `contextHandle`, `errorHandle` | [Request scope](/norns/runtime/request-scope) |
| `betterSqlite`, `d1`, `libsql`, `postgres`, `withTransaction` | [Drivers](/norns/data/drivers) |

The runtime is opinionated on purpose. Its value is an app architecture on top of SvelteKit's primitives, not syntax sugar: feature folders, a facade boundary, validated input at the edge, and a container that tools can reason about.

---

<!-- https://norns-docs.humansynthesis.ai/reference/this-site -->

# About this site

> The docs are a Norns app — markdown under content/, a docs feature folder, prerendered on Cloudflare Workers.

`norns-docs` is a Norns app like any other. It dogfoods the stack: the content is a feature folder, the pages are `.n` files, the shell is norns-ui.

## How it is put together

- **Content** is markdown under `content/<package>/NN-section/NN-page.md`, with `title` and `description` frontmatter. The numeric prefix orders sections and pages and is stripped from the URL; `index.md` is the page for its folder. Callouts use `> [!NOTE]`, `[!TIP]`, `[!WARNING]`, `[!IMPORTANT]`, `[!CAUTION]`.
- **The docs feature** (`src/lib/norns/docs/`) is a normal feature folder: a `shared/` content model, a `server/repo.js` that bundles the markdown at build time through `import.meta.glob`, a `service.c` that renders pages and builds the sidebar, and a `public.c` facade the routes import. Because the routes only see the facade, the content source can be swapped (a database, or the planned norns-cms) without touching them.
- **Rendering** is marked plus shiki with a dual light/dark theme. Civet blocks use the CoffeeScript grammar until a Civet grammar exists.
- **Every page is prerendered** and served as a static asset from Cloudflare Workers; the worker only answers misses.
- **Agent-readable:** every page has a Markdown twin at `/md/<package>/<slug>`, listed in [`/llms.txt`](/llms.txt); [`/llms-full.txt`](/llms-full.txt) is the whole corpus in one file.
- **Generated reference:** the norns-ui [component reference](/norns-ui/reference/components) is copied from the installed package's `COMPONENTS.md` by `scripts/gen-reference.mjs` before every dev run and build, so it always matches the installed version.

## Contributing a page

1. Add or edit a file under `content/`. Links between pages are site-absolute (`/norns/runtime/container`).
2. `bun run dev` and check the page and the sidebar.
3. `bun run lint`, `bun run check`, `bun run build`.
4. Open a pull request against `human-synthesis/norns-docs`. Deploys happen from `main`.

The "Edit this page" link at the bottom of every page opens the file on GitHub.

## Planned

- Move each package's pages into that package's repository and pull them at build time, so docs change in the same commit as the code.
- One page per norns-ui component with a live demo next to the props.
- The norns CLI reference generated from the CLI's own help text.
- Once norns-cms exists, this site is a candidate first tenant: its packages, sections and pages map directly onto content types.

---

<!-- https://norns-docs.humansynthesis.ai/norns/runtime/boot -->

# Boot

> boot() builds the root container, runs every feature module, and returns the SvelteKit hooks.

`src/hooks.server.c` is the whole wiring:

```civet
features := import.meta.glob './lib/norns/*/server/module.c', { eager: true }

app := await boot { features }

{ handle, handleError } := app
export { handle, handleError }
```

`boot` is auto-imported in server files; import it explicitly from `@human-synthesis/norns/server` if you prefer.

## What `boot()` does

1. Creates a fresh root `Container`.
2. If `serializer` is given, installs it as the app-wide [response serializer](/norns/runtime/serializers).
3. For every entry in `features`, takes the module's default export (or the module itself when it is a function) and calls it with the root container. Each `module.c` registers its bindings there. A module whose default export is not a function fails boot with a clear error naming the path.
4. Builds `handle` as `sequence(contextHandle(container), ...extraHandle)` and picks `handleError` (yours, or the default `errorHandle()`).

## Options

| Option | Type | Notes |
|---|---|---|
| `features` | `Record<path, module>` | Usually the result of `import.meta.glob(..., { eager: true })`. |
| `extraHandle` | `Handle` or `Handle[]` | Extra SvelteKit handles run after the context handle, for example auth. |
| `handleError` | `HandleServerError` | Replaces the default error handle. |
| `serializer` | `Serializer` or `null` | App-wide `route()` serializer, e.g. `tronSerializer()` from [norns-tron](/norns-tron). |

## Return value

`{ container, handle, handleError }`. `container` is the root container, useful in tests and scripts; requests never touch it directly, they get a child scope (see [Request scope](/norns/runtime/request-scope)).

## `createApp()`

Returns an empty root container with nothing registered. Use it in tests that want full control over bindings.

---

<!-- https://norns-docs.humansynthesis.ai/norns/runtime/container -->

# Container

> A small DI container with string tokens, singleton and transient bindings, overrides for tests, and child scopes per request.

Tokens are namespaced strings, conventionally `<feature>.<role>`: `notes.repo`, `notes.service`, `db`. Bindings register a factory that receives the container it is resolved through.

```civet
import type { Container } from '@human-synthesis/norns/server'

export default (app: Container) =>
	app.single 'notes.repo', (c: Container) => new NotesRepo c.resolve('db')
	app.single 'notes.service', (c: Container) => new NotesService c.resolve('notes.repo')
```

## Methods

| Method | Behaviour |
|---|---|
| `bind(token, factory)` | Transient: the factory runs on every `resolve(token)`. |
| `single(token, factory)` | Singleton: the factory runs once per container scope where the binding is declared, and the result is memoised there. |
| `override(token, factory)` | Wins over any binding in this scope or any parent. Made for tests: swap a real service for a fake without touching the production module. |
| `resolve(token)` | Returns the value. Walks the scope chain: nearest override first, then nearest binding; throws `Container: no binding for token "..."` when nothing matches. |
| `has(token)` | Whether a binding or override is reachable. |
| `scope()` | Creates a child container that inherits bindings through the parent walk but keeps its own overrides and singletons. |
| `migrations(dir)` | Registers a migrations directory on the root container. |
| `getMigrationDirs()` | All registered migration directories, from the root. |

Factories are called with the **leaf** container, the one `resolve` was called on. A factory can therefore resolve other tokens at the same scope, which is how `notes.service` gets a request-scoped `db` even though `notes.service` itself was declared on the root.

## Singleton versus transient

- `single` on the root container is a process-wide instance: a repo over a local SQLite file, a service without per-request state.
- `bind` re-runs the factory each resolve. Use it when the value depends on the request, such as a D1 binding that only exists on `event.platform.env` (see [Cloudflare D1](/norns/data/cloudflare-d1)). Resolving a transient binding several times inside one request yields several instances; resolve once and pass it along if that matters.
- A `single` declared on a **child** scope is per request, because the child scope is created per request.

## Tests

```civet
import { createContainer } from '@human-synthesis/norns/server'

c := createContainer()
c.single 'notes.repo', => new FakeRepo!
c.single 'notes.service', (c) => new NotesService c.resolve('notes.repo')

svc := c.resolve 'notes.service'
```

Or boot the real modules and `override` one token on a child scope.

---

<!-- https://norns-docs.humansynthesis.ai/norns/runtime/page-wrappers -->

# Page wrappers

> page.load and page.actions wrap +page.server.c exports with container resolution, form parsing and valibot validation.

`page` is auto-imported in server files. It mirrors [`route()`](/norns/runtime/route) with two differences that match SvelteKit's form conventions: `load` returns its result as plain data, and actions return `fail(400, ...)` on validation errors instead of throwing.

```civet
import { notes } from '$lib/norns/notes/server/public'
import { createNoteSchema } from '$lib/norns/notes/shared/schema'

export load := page.load
	handler: async ({ container }) =>
		notes: await notes(container).list()

export actions := page.actions
	create:
		input: createNoteSchema
		run: async ({ input, container }) =>
			id := await notes(container).create input
			throw redirect 303, `/notes/${id}`
```

## `page.load({ handler })`

The handler receives:

| Field | Value |
|---|---|
| `container` | the request-scoped container (`event.locals.container`) |
| `event` | the raw SvelteKit `ServerLoadEvent` |
| `params`, `url` | shortcuts for `event.params` and `event.url` |
| `user` | `event.locals.user`, whatever your auth handle put there |

Whatever the handler returns is the page's `data`. Throw `error(404, ...)` or `redirect(...)` as in plain SvelteKit.

## `page.actions({ name: { input?, run } })`

Each action is `{ input?, run }`:

- When `input` is present the form body is read with `request.formData()`, flattened with `Object.fromEntries`, and validated. On failure the action returns `fail(400, { errors, values })`: `errors` is the issue list, `values` is the raw form data echoed back so the page can re-render it.
- `run` receives `{ input, container, event, user }`. `input` is the validated value (or `undefined` when there is no schema).

A route with a dynamic parameter reads it from the event:

```civet
export actions := page.actions
	update:
		input: updateNoteSchema
		run: async ({ input, container, event }) =>
			id := Number event.params.id
			await notes(container).update id, input
			{ saved: true }

	delete:
		run: async ({ container, event }) =>
			await notes(container).remove Number(event.params.id)
			throw redirect 303, '/notes'
```

## Rendering errors

The `fail(400, { errors, values })` shape is what norns-ui's `<Form form={form}>` reads. Each `<Field name="...">` inside looks up its own message from `errors` by path, and `values` lets inputs keep what the user typed:

```pug
Form(action="?/create" form!="{form}")
	Field(label="Title" name="title" required)
		Input(name="title" value!="{form?.values?.title ?? ''}" required)
	Btn(type="submit" variant="primary") Create
```

> [!NOTE] Actions only see form-encoded bodies. A client that posts JSON must call a `+server.c` endpoint wrapped in `route()`, not a form action.

---

<!-- https://norns-docs.humansynthesis.ai/norns/runtime/route -->

# route()

> Wrap a +server.c handler with body parsing, validation, container resolution and JSON (or TRON) serialization.

```civet
import { messages } from '$lib/norns/messages/server/public'
import { sendMessageSchema } from '$lib/norns/messages/shared/schema'

export GET := route
	handler: ({ container }) =>
		data: messages(container).list()

export POST := route
	input: sendMessageSchema
	handler: ({ input, container }) =>
		messages(container).create input
		{ ok: true }
```

`route` is auto-imported in server files.

## What the wrapper does, in order

1. **Body parsing**, only when `input` is set. `application/json` is parsed as JSON; `application/x-www-form-urlencoded` and `multipart/form-data` are read with `formData()` and flattened. An app-wide or per-route serializer can claim other content types first through its `parseBody` hook (this is how TRON request bodies work). Empty or unsupported bodies become `null`, and the schema decides whether `null` is acceptable.
2. **Body validation** against `input`. Failure throws `error(400, { message, issues })`.
3. **Query validation** against `query`, over `Object.fromEntries(url.searchParams)`. Same 400 on failure.
4. **Handler call** with `{ input, query, container, event, user }`.
5. **Serialization.** A `Response` returned by the handler passes through untouched. Otherwise the serializer (per-route, else app-wide) may turn the value into a `Response`; if it declines, the value is sent as JSON with `json()`. `undefined` becomes `null`.

## Options

| Option | Notes |
|---|---|
| `input` | body schema: a valibot schema, any Standard Schema, or a function |
| `query` | query-string schema, same forms |
| `serializer` | per-route serializer; `null` forces plain JSON even when an app-wide one is set |
| `handler` | required |

For non-success outcomes throw `error(...)` or `redirect(...)` inside the handler; SvelteKit surfaces them.

## Returning something that is not JSON

Return a `Response` yourself:

```civet
export GET := route
	handler: ({ container }) =>
		new Response(docs(container).sitemap(), { headers: { 'content-type': 'application/xml' } })
```

## Calling it from the browser

Plain `fetch` works. With [norns-tron](/norns-tron) installed, `api.get('/api/messages')` sends `Accept: application/tron` and decodes either format transparently.

---

<!-- https://norns-docs.humansynthesis.ai/norns/runtime/validation -->

# Validation

> valibot at the edge — how page.actions and route() validate input, and what the error shapes look like.

Schemas live in the feature's `shared/schema.c` so the server wrapper and the client form share one definition:

```civet
import * as v from 'valibot'

export createNoteSchema := v.object
	title: v.pipe v.string(), v.trim(), v.minLength(1, 'title is required')
	body: v.optional v.string(), ''

export type CreateNoteInput = v.InferOutput<typeof createNoteSchema>
```

`valibot` is a dependency of your app, not of norns; the starter installs it.

## `validate(schema, raw)`

The function both wrappers use. It accepts a valibot schema (any Standard Schema implementation works the same way) or a plain function that returns the parsed value or throws. On failure it throws `ValidationError`, whose `issues` array is the schema's issue list and whose `message` summarises them.

## Error shapes

| Wrapper | On validation failure |
|---|---|
| `page.actions` | returns `fail(400, { errors: issues, values: rawForm })` |
| `route()` | throws `error(400, { message, issues })` |

The action shape is what norns-ui's `<Form>` and `<Field>` consume; each field finds its message by matching `errors[*].path[0].key` against its `name`. The route shape reaches API clients as a 400 with a JSON body.

## Type inference

Use `v.InferOutput<typeof schema>` for the service's input type, as above, so the service signature and the schema cannot drift.

## The same schema on the wire

[norns-tron](/norns-tron/guide/schema-mode) derives a TRON wire schema from the same valibot object, which is how internal endpoints get the fastest serialization mode without a second shape definition.

---

<!-- https://norns-docs.humansynthesis.ai/norns/runtime/serializers -->

# Serializers

> An app-wide or per-route hook that turns route() results into a Response and reads non-JSON request bodies.

A serializer is an object with two hooks:

```ts
interface Serializer {
  serialize(result: unknown, event: RequestEvent): Response | null;
  parseBody?(request: Request, contentType: string): Promise<unknown> | undefined;
}
```

- `serialize` turns the handler's return value into a `Response`, or returns `null` to fall through to the default JSON serialization.
- `parseBody` reads a request body for a content type `route()` does not handle natively, or returns `undefined` to fall through to the built-in JSON and form readers.

## Installing one

App-wide, through boot:

```civet
import { tronSerializer } from '@human-synthesis/norns-tron/server'

app := await boot { features, serializer: tronSerializer() }
```

Per route, which overrides the app-wide one. `null` forces plain JSON:

```civet
export GET := route
	serializer: tronSerializer({ schema: noteWire })
	handler: ...

export POST := route
	serializer: null
	handler: ...
```

`setSerializer(s)` and `getSerializer()` are the underlying functions; `boot({ serializer })` calls the first. The serializer is looked up per request, so module evaluation order does not matter.

## The one that ships

`tronSerializer()` from [norns-tron](/norns-tron) content-negotiates: clients that send `Accept: application/tron` get TRON, everyone else keeps getting JSON. Remove the option to roll back.

---

<!-- https://norns-docs.humansynthesis.ai/norns/runtime/request-scope -->

# Request scope

> Every request gets a child container on event.locals.container, also reachable through AsyncLocalStorage.

`boot()` installs `contextHandle(container)` as the first SvelteKit handle. For each request it:

1. creates `app.scope()`, a child of the root container;
2. sets it on `event.locals.container`;
3. runs the rest of the pipeline inside `withScope({ container, event }, ...)`, so code that never receives `event` can still find the scope.

The wrappers pass `container` to your handlers, so most code never needs the helpers below.

## Helpers

| Function | Use |
|---|---|
| `getScope()` | The current `{ container, event }` scope, or `undefined` outside a request. |
| `getContainer()` | The current request container; throws when called outside a request. |
| `withScope(scope, fn)` | Run `fn` with a given scope. `contextHandle` calls this; tests can too. |
| `contextHandle(app)` | The handle itself, for apps that assemble their own `handle` without `boot()`. |
| `errorHandle()` | The default `handleError`. |

A factory registered on the root container can read the request through the scope. This is how the demo binds a Cloudflare D1 database that only exists on `event.platform`:

```civet
app.bind 'db', =>
	db := getScope()?.event?.platform?.env?.DB
	throw new Error 'D1 binding `DB` is missing' unless db
	db
```

## Adding your own handle

Pass `extraHandle` to `boot()`; the handles run after the context handle, so `event.locals.container` is already set. A typical auth handle resolves a session and sets `event.locals.user`, which the wrappers expose as `user`.

## Platform note

The scope uses `AsyncLocalStorage` from `node:async_hooks`. On Cloudflare Workers that requires the `nodejs_als` and `nodejs_compat` compatibility flags in `wrangler.toml`; see [Deploy to Cloudflare](/norns/deploy/cloudflare).

---

<!-- https://norns-docs.humansynthesis.ai/norns/data -->

# Data

> Migrations, database driver factories, and the Cloudflare D1 pattern.

- [Migrations](/norns/data/migrations) — `norns migrate` and the `migrations/<feature>/` layout.
- [Drivers](/norns/data/drivers) — `betterSqlite`, `d1`, `libsql`, `postgres` and `withTransaction`.
- [Cloudflare D1](/norns/data/cloudflare-d1) — binding a per-request D1 handle and applying migrations with wrangler.

Norns takes no position on how you query. The reference apps use hand-written SQL on the raw driver; the driver factories give you a Drizzle instance if you want one.

---

<!-- https://norns-docs.humansynthesis.ai/norns/data/migrations -->

# Migrations

> Forward-only SQL files per feature, applied and tracked by the norns CLI.

```sh
bun run migrate create notes/add_pinned    # scaffold migrations/notes/<timestamp>_add_pinned.sql
bun run migrate up                         # apply pending migrations
bun run migrate status                     # list applied and pending
```

(`"migrate": "norns migrate"` in `package.json`.)

## Layout

```
<project>/migrations/<feature>/<timestamp>_<slug>.sql
```

Migrations live at the project root, outside `src/`, one folder per feature. They are operational artefacts read by tooling, not application code, and keeping them out of `src/lib` keeps the bundler away from them. Files apply in file-name order across features, so the timestamp prefix gives a global chronology; the feature name breaks ties.

`create` does not check that the feature exists, so nested layouts such as `src/lib/<group>/<feature>/` work too. A typo simply produces an orphan folder under `migrations/` that is easy to spot.

## Tracking

Applied migrations are recorded in a `norns_migrations` table (`id TEXT PRIMARY KEY, applied_at INTEGER`). The id is `<feature>/<file-without-.sql>`. Each migration runs in a transaction together with its tracking insert, so a failing file leaves nothing half-applied.

## Target database

The CLI reads `DATABASE_URL` and supports SQLite only in v1: `file:<path>`, defaulting to `file:./data/app.db`. Any other scheme fails with a message pointing at the alternatives.

The SQLite backend is chosen at runtime: `bun:sqlite` under Bun (no native build, works on Alpine) and `better-sqlite3` under Node, where the consumer app must have it installed.

```sh
DATABASE_URL=file:./data/notes.db bun run migrate up
```

## Cloudflare D1

`norns migrate` does not talk to D1. Point wrangler at the same folder and use its migration commands; see [Cloudflare D1](/norns/data/cloudflare-d1). Postgres and libSQL through the CLI are planned.

---

<!-- https://norns-docs.humansynthesis.ai/norns/data/drivers -->

# Drivers

> Driver factories that assemble a Drizzle instance for SQLite, D1, libSQL or Postgres, with a portable transaction helper.

The factories live in `@human-synthesis/norns/server`. Drizzle and the driver packages are **user-installed**; the framework only provides the assembly recipe and imports each driver lazily, so an app that never calls `d1()` does not need `drizzle-orm/d1` installed.

```civet
// module.c — Node with better-sqlite3 in development
import { betterSqlite } from '@human-synthesis/norns/server'

export default (app: Container) =>
	db := await betterSqlite 'data/app.db', { pragma: ['journal_mode = WAL'] }
	app.single 'db', => db
```

| Factory | Backend | Options |
|---|---|---|
| `betterSqlite(path, opts?)` | `bun:sqlite` + `drizzle-orm/bun-sqlite` under Bun, `better-sqlite3` + `drizzle-orm/better-sqlite3` under Node. The name is kept for compatibility; the runtime picks the backend. | `connection` (passed to the constructor), `pragma` (array of PRAGMA statements run after open), `drizzle` |
| `d1(binding, opts?)` | `drizzle-orm/d1` over a D1 binding from `event.platform.env` | `drizzle` |
| `libsql(url, opts?)` | `@libsql/client` + `drizzle-orm/libsql` (Turso, sqld) | `client`, `drizzle` |
| `postgres(url, opts?)` | `pg` Pool + `drizzle-orm/node-postgres` | `pool`, `drizzle` |
| `withTransaction(db, fn)` | `db.transaction(fn)`, uniform across drivers | |

All factories are async; `await` them in `module.c` before binding.

## Without Drizzle

Nothing requires an ORM. The demo's notes feature opens the raw D1 API and writes SQL by hand in `repo.c`; the starter keeps an in-memory array. Bind whatever handle you like as `db` and keep every `new Database(...)` in exactly one module so the rest of the app resolves it from the container.

---

<!-- https://norns-docs.humansynthesis.ai/norns/data/cloudflare-d1 -->

# Cloudflare D1

> Bind a per-request D1 handle from event.platform.env and apply migrations with wrangler.

On Workers the database binding arrives **per request** on `event.platform.env`, not at boot. Bind it transiently and read it from the request scope; the repo and service become transient too, because they close over that request's handle:

```civet
import { getScope } from '@human-synthesis/norns/server'
import type { Container } from '@human-synthesis/norns/server'
import { NotesRepo } from './repo'
import { NotesService } from './service'

export default (app: Container) =>
	app.bind 'db', =>
		db := getScope()?.event?.platform?.env?.DB
		throw new Error 'D1 binding `DB` is missing — check [[d1_databases]] in wrangler.toml' unless db
		db
	app.bind 'notes.repo', (c: Container) => new NotesRepo c.resolve('db')
	app.bind 'notes.service', (c: Container) => new NotesService c.resolve('notes.repo')
```

The repo then uses the D1 API directly; every call is async on Workers:

```civet
export class NotesRepo
	db: D1Database
	constructor(@db: D1Database)

	async list(): Promise<Note[]>
		result := await @db.prepare('SELECT * FROM notes ORDER BY updated_at DESC').all()
		result.results as Note[]

	async create(title: string, body: string): Promise<number>
		now := Date.now()
		stmt := @db.prepare('INSERT INTO notes (title, body, created_at, updated_at) VALUES (?, ?, ?, ?)').bind(title, body, now, now)
		result := await stmt.run()
		Number result.meta.last_row_id
```

## wrangler.toml

```toml
[[d1_databases]]
binding = "DB"
database_name = "my-app-notes"
database_id = "<output of wrangler d1 create>"
migrations_dir = "migrations/notes"
```

Under `vite dev`, `@sveltejs/adapter-cloudflare`'s platform proxy reads this file and serves a local D1 from `.wrangler/state/`, so `event.platform.env.DB` resolves without a Cloudflare account.

## Migrations

`norns migrate` is SQLite-only; use wrangler against the same SQL files:

```sh
wrangler d1 migrations apply my-app-notes --local    # dev database under .wrangler/state/
wrangler d1 migrations apply my-app-notes --remote   # production
```

The demo wires these as `bun run db:migrate` and `bun run db:migrate:remote`, and its deploy workflow applies remote migrations before deploying the worker. `norns migrate create` still scaffolds the files.

---

<!-- https://norns-docs.humansynthesis.ai/norns/cli -->

# CLI

> The norns binary — dev, build, preview, migrate, lint, check and diag.

- [Commands](/norns/cli/commands) — every subcommand and flag.
- [Lint rules](/norns/cli/lint-rules) — what `norns lint` reports and why.
- [check and diag](/norns/cli/check-and-diag) — compile-checking without a build, and seeing what a file compiles to.

The binary is `norns`, installed with `@human-synthesis/norns`. Run it through `bun run <script>` or `bunx norns <command>`.

---

<!-- https://norns-docs.humansynthesis.ai/norns/cli/commands -->

# Commands

> norns dev, build, preview, migrate, lint, check, diag, and the help screen.

```
norns <command>

Commands:
  dev                                start vite dev with framework-source watching (default)
  build                              run vite build
  preview                            run vite preview
  migrate status                     list applied + pending migrations
  migrate up                         apply pending migrations
  migrate create <feature>/<name>    scaffold a new SQL migration
  lint [--json]                      scan .c/.civet/.n (templates + script blocks) and vite.config for known pitfalls
  check [--json] [--warnings]        preprocess + compile every .n/.c/.civet through svelte.config.js; file:line:column errors
  diag <file>                        print the JS Civet compiles a .c/.civet/.n script to
  diag --template <file.n>           print the Svelte source the compiler sees after Pug/Civet/auto-import preprocessing
```

Running `norns` with no command is `norns dev`. `--flag` options are collected for the norns-owned commands; `dev`, `build` and `preview` pass everything through to Vite untouched, so `norns dev --port 3000 --host` works.

## `dev`

Spawns `vite dev` under Node using the Vite binary resolved from your project. Two extras exist for the framework's own workspace and are no-ops elsewhere: if the framework packages resolve to symlinks outside `node_modules`, their `src/` folders are watched and the dev server is respawned when they change (Node's ESM cache survives a plain Vite restart); and a published copy of a framework package that shadows a workspace symlink in the local `node_modules` is removed with a log line.

## `build`, `preview`

`vite build` and `vite preview`, with the same shadow cleanup.

## `migrate`

`status`, `up` and `create <feature>/<name>`; `status` is the default. Reads `DATABASE_URL` (SQLite `file:` URLs only in v1, default `file:./data/app.db`). See [Migrations](/norns/data/migrations).

## `lint [--json]`

Scans `src/` (or the project root when there is no `src/`) for `.c`, `.civet` and `.n` files plus `vite.config.{js,ts,mjs}` and prints findings grouped by file. Exit code 1 when there is at least one error. `--json` prints `{ ok, errors, warnings, findings }`. See [Lint rules](/norns/cli/lint-rules).

## `check [--json] [--warnings]`

Compiles every component and Civet module the way the build would, without running the build, and reports `file:line:column` diagnostics. Exit code 1 on errors, 2 when the check itself could not run. See [check and diag](/norns/cli/check-and-diag).

## `diag [--template] <file>`

Prints the JavaScript Civet emits for a `.c` / `.civet` file or for the `<script>` block of a `.n` / `.svelte` file. With `--template` (components only) prints the Svelte source after the project's whole preprocess chain: Pug rendered, Civet compiled, auto-imports injected.

---

<!-- https://norns-docs.humansynthesis.ai/norns/cli/lint-rules -->

# Lint rules

> The static checks behind norns lint, each tied to a documented Civet or Pug pitfall.

`norns lint` is a fast regex scan, not a compiler. It exists because the pitfalls below either compile to something wrong at runtime or fail with an error that points at the wrong line. Every rule maps to an entry on the [Civet](/norns/pitfalls/civet) or [Pug](/norns/pitfalls/pug) pitfalls page.

## Civet rules

Applied to whole `.c` / `.civet` files and to `<script>` blocks whose language is Civet (the default in `.n` files). Comment lines and string contents are ignored.

| Rule | Severity | Trigger | Fix |
|---|---|---|---|
| `civet/no-isnt` | error | `isnt` anywhere in code | use `!==`; `isnt` compiles to a bare identifier reference |
| `civet/no-async-generator-method` | error | an indented `async *name(` (class method shorthand) | a callback API or a top-level `async function*` |
| `civet/state-const-reassign` | error | `name := $state ...` followed later by an assignment to `name` | declare it with `.=`, which emits `let` |

## Pug rules

Applied to template lines of `.n` / `.svelte` files, outside `<script>` and `<style>` blocks.

| Rule | Severity | Trigger | Fix |
|---|---|---|---|
| `pug/svelte-block-needs-pipe` | error | a line starting with `{@`, `{#`, `{:` or `{/` | prefix with `\| ` so Pug emits it as text |
| `pug/no-pug-interpolation` | error | `#{` not escaped as `\#{` | Svelte `{expr}`; Pug interpolation runs at preprocess time with no runtime data |
| `pug/each-as-form` | error | `+each('item of items')` | `+each('items as item')`, optionally with a `(item.id)` key |

## Vite config

| Rule | Severity | Trigger |
|---|---|---|
| `vite/allowed-hosts` | warning | `server.allowedHosts` is neither `true` nor a list; reverse-proxied dev requests will be blocked |

## Scope

The walk skips `node_modules`, `.svelte-kit`, `.git`, `build`, `dist`, `static`, `.next`, `.cache`, `.turbo`, `data`, `coverage` and every dot-directory. A file that cannot be read produces a `lint/read-error` warning instead of aborting the run.

## Output

```
src/routes/+page.n
    18  error  pug/each-as-form  Svelte `{#each}` takes `items as item`, not `item of items`. ...

norns lint: 1 error(s), 0 warning(s) across 1 file(s).
```

`--json` returns the same findings as `{ file, line, severity, rule, msg }` records with `file` relative to the project root.

---

<!-- https://norns-docs.humansynthesis.ai/norns/cli/check-and-diag -->

# check and diag

> norns check compiles every file the way the build does and maps errors to the line you wrote; norns diag shows the compiled output.

## `norns check`

For every component file (each extension in your `svelte.config.js` `extensions`, so `.n` and `.svelte`) the command runs the project's own `preprocess` chain and then the Svelte compiler. For every `.c` / `.civet` module it runs the Civet compiler. Nothing is written; the result is a diagnostics list.

Each diagnostic carries `file`, `line`, `column`, `message`, `stage` (`civet`, `pug`, `preprocess` or `svelte`), a code frame, and `mapped`:

- **Pug and Civet errors** are mapped by norns-core to the source line you wrote, including inside `<script>` blocks of `.n` files (see [error mapping](/norns-core/guide/error-mapping)).
- **Svelte compile errors** are mapped back through the preprocess source map when the mapped line plausibly contains the offending text. Template positions usually cannot be mapped; those are reported against the preprocessed output with `mapped: false` and a hint to run `norns diag --template`.

```
src/routes/+page.n:18:7  error  Pug: Unexpected token ...
    > 18| 		li.rounded-md.border(
      19| 			.text-sm {item.text}

norns check: 1 error(s), 0 warning(s) across 12 file(s).
```

Flags: `--warnings` includes Svelte compiler warnings; `--json` prints `{ ok, files, errors, warnings }`. Exit code 1 on errors, 2 when the check could not run (for example a broken `svelte.config.js`).

`svelte-check` does not read `.n` or `.c` files at all. `norns check` is the pass signal for Norns code; keep `svelte-check` for the `.svelte` / `.ts` parts of a mixed project.

## `norns diag`

```sh
bunx norns diag src/lib/norns/notes/server/service.c
bunx norns diag src/routes/+page.n                  # the <script> block only
bunx norns diag --template src/routes/+page.n       # the whole component after preprocessing
```

The first form prints the JavaScript Civet emits. Use it when a Civet error is unhelpful or when the code compiles but behaves unexpectedly: the output proves whether your source means what you think it means.

`--template` runs the file through the project's `svelte.config.js` preprocess chain and prints the Svelte source the compiler sees: Pug rendered to markup, Civet compiled, auto-imports injected. This is the place to look when a Svelte error quotes markup you never wrote.

---

<!-- https://norns-docs.humansynthesis.ai/norns/deploy -->

# Deploy

> A Norns app deploys like any SvelteKit app. Cloudflare Workers is the reference target; Node and the other adapters work too.

- [Cloudflare Workers](/norns/deploy/cloudflare) — the adapter, `wrangler.toml`, compat flags, custom domains, GitHub Actions.
- [Node and other adapters](/norns/deploy/node-and-others) — what the runtime needs from a platform.

---

<!-- https://norns-docs.humansynthesis.ai/norns/deploy/cloudflare -->

# Cloudflare Workers

> adapter-cloudflare, the two compatibility flags the runtime needs, static assets, custom domains and a deploy workflow.

This is the setup the demo and the docs site use.

## svelte.config.js

```js
import adapter from '@sveltejs/adapter-cloudflare';

export default nornsConfig({
  // ...preprocess
  kit: { adapter: adapter() }
});
```

## wrangler.toml

```toml
name = "my-app"
main = ".svelte-kit/cloudflare/_worker.js"
compatibility_date = "2026-04-01"
compatibility_flags = ["nodejs_als", "nodejs_compat"]

routes = [
  { pattern = "my-app.example.com", custom_domain = true }
]

[assets]
directory = ".svelte-kit/cloudflare"
binding = "ASSETS"

[observability]
enabled = true
```

The two compatibility flags are not optional:

- `nodejs_als` provides `AsyncLocalStorage`, which the [request scope](/norns/runtime/request-scope) is built on.
- `nodejs_compat` is the general Node compatibility layer that Drizzle drivers and many libraries need.

`custom_domain = true` works when the zone is on Cloudflare; Workers issues the certificate. Otherwise point a CNAME at the `workers.dev` hostname.

Add a `[[d1_databases]]` block for a database; see [Cloudflare D1](/norns/data/cloudflare-d1).

## Local development

`vite dev` gets `event.platform` from the adapter's platform proxy, which reads `wrangler.toml` and keeps local state under `.wrangler/state/`. No account is needed to run locally. Add `.wrangler/` to `.gitignore`.

## Deploying

```sh
bun run build && wrangler deploy
```

A GitHub Actions workflow that lints, checks, builds and deploys on every push to `main`:

```yaml
name: Deploy
on:
  push:
    branches: [main]
  workflow_dispatch:
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - run: bun install
      - run: bun run lint
      - run: bun run check
      - run: bun run build
      - uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          packageManager: bun
          command: deploy
```

The token needs *Workers Scripts: Edit* (and *D1: Edit* when the workflow applies migrations). Keep it in repository secrets, never in `wrangler.toml`.

## Prerendering

A fully prerendered app (like this documentation site) still produces a worker, but every page lands in the assets directory and the worker only runs for misses. Set `export prerender := true` in the root `+layout.c`.

---

<!-- https://norns-docs.humansynthesis.ai/norns/deploy/node-and-others -->

# Node and other adapters

> The runtime needs AsyncLocalStorage and a SQLite driver; beyond that any SvelteKit adapter works.

Norns is plain SvelteKit at build time, so `@sveltejs/adapter-node`, `adapter-static`, `adapter-vercel`, `adapter-netlify` and `adapter-auto` all apply. The runtime has two platform requirements:

1. **`AsyncLocalStorage`** from `node:async_hooks`, for the per-request scope. Node and Bun have it natively; Cloudflare needs the `nodejs_als` flag; other edge runtimes vary.
2. **A database driver** if you use one. `better-sqlite3` is a native module that must be built for the deployment platform when the app runs under Node; under Bun the runtime picks `bun:sqlite` instead and no native build is involved.

## adapter-node

```js
import adapter from '@sveltejs/adapter-node';
export default nornsConfig({ kit: { adapter: adapter() } });
```

```sh
bun run build
DATABASE_URL=file:./data/app.db bunx norns migrate up
node build
```

Run migrations as a release step before starting the new version. `norns migrate` needs `better-sqlite3` installed when it runs under Node.

## adapter-static

Works for fully prerendered sites. Server-only code still runs at build time, so `boot()` and the container behave normally during prerendering.

## Environment

- Behind a reverse proxy in development, set `server.allowedHosts: true` in `vite.config.js`.
- Container environments read `.env` at create time; a restart does not pick up changes, a recreate does.

---

<!-- https://norns-docs.humansynthesis.ai/norns/pitfalls -->

# Pitfalls

> The handful of Civet and Pug constructs that compile to the wrong thing, and the verification order that catches them.

Civet is a good fit for app code and has rough edges on advanced syntax. The rule that saves the most time: **when something does not parse or compile in Civet, drop to plain `.js` for that file**. Libraries and dense generator, stream or type-heavy code belong in `.js`; routes, components and feature code stay in `.c` / `.n`.

- [Civet pitfalls](/norns/pitfalls/civet)
- [Pug pitfalls](/norns/pitfalls/pug)
- [Verification workflow](/norns/pitfalls/verification)

`norns lint` catches the mechanical cases; `norns check` catches everything that fails to compile. The `CLAUDE.md` shipped with the starter and the demo carries the same tables so coding agents see them.

---

<!-- https://norns-docs.humansynthesis.ai/norns/pitfalls/civet -->

# Civet pitfalls

> Constructs that Civet parses into something other than what you meant.

| Do not write | Write | Why |
|---|---|---|
| `if x isnt y` | `if x !== y` | `isnt` compiles to a bare identifier reference at runtime |
| `async *foo()` as a class method | a callback `foo(onEvent)` or a top-level `async function*` | the parser rejects async generators in class method shorthand |
| `value := $state ''` and later `value = 'x'` | `value .= $state ''` | `:=` creates `const`; reassigning `$state` needs `let`, which `.=` produces |
| `raw: unknown` / `raw: any` as a typed `let` | `raw .= null` (no annotation) or `let raw: any = null` | bare type annotations get read as identifier references |
| `# a comment` | `// a comment` | `#` is not a comment in Civet; `# x` compiles to a length shorthand (`this.length(x)`) and either fails or silently changes meaning |
| `import { and } from 'drizzle-orm'` | `import * as dz from 'drizzle-orm'` and `dz.and` | `and`, `or`, `not` are Civet operators and cannot appear bare in brace imports; as object keys quote them |

## Things that work and are worth knowing

- `x := 1` is `const`, `x .= 1` is `let`, `@x` is `this.x`, `constructor(@repo: Repo)` assigns the field.
- Implicit calls: `notes(container).create input` is `notes(container).create(input)`. Add parentheses whenever a chain could be read two ways, especially after `new`.
- `return x unless cond`, `return if cond`, `throw error 404, 'msg' unless doc` are all fine and used throughout the reference apps.
- `x?` is an existence check (`x != null`); `a?.b` is optional chaining.
- Indented object literals: an arrow body or an argument list can be a block of `key: value` lines; that is how `page.load handler: ...` and `boot features: ..., serializer: ...` are written.
- Double-quoted strings do not interpolate; use backtick template literals with `${}`.

When in doubt, `bunx norns diag <file>` prints the JavaScript and settles it.

---

<!-- https://norns-docs.humansynthesis.ai/norns/pitfalls/pug -->

# Pug pitfalls

> Template lines that Pug parses differently from what a Svelte author expects.

| Do not write | Write | Why |
|---|---|---|
| `{@html foo}` as a top-level Pug line | `\| {@html foo}` | Pug parses a leading `{` as a malformed tag; the pipe emits the line as text |
| `#{expr}` in text | `{expr}` | Pug interpolation runs at preprocess time with no runtime data in scope, and SSR fails with a 500 |
| `attr="#{expr}"` | `attr!="{expr}"` | same reason; `!=` is Pug's unescaped attribute, which Svelte then reads as an expression |
| `+each('row of rows')` | `+each('rows as row')`, optionally `+each('rows as row (row.id)')` | the `of` form is copied verbatim into the Svelte block and the compiler rejects it |
| a `.a.b` chain or `{expr}` split across a line break | one element per line | Pug is line-oriented; the parse error surfaces on the next line |

## Template syntax that works

- `+if('cond')` / `+elseif('cond')` / `+else`, nested to any depth.
- `+each('items as item (item.id)')`.
- `+snippet('name', arg)` to define, `| {@render name(x)}` to render.
- `attr!="{expr}"` for Svelte expressions; `bind:value!="{x}"`; `onclick!="{handler}"`.
- `.a.b` class shorthand, including Tailwind variants and fractions like `.hover:bg-x.gap-2.5`, which norns-core rewrites for you.
- `svelte:head` as a tag, with `title`, `meta(...)` and `link(...)` children.
- Components as tags: `Btn(variant="primary" href="/x") Save`.

See the norns-core [Pug template](/norns-core/guide/pug-template) and [control flow](/norns-core/guide/control-flow) pages for the details.

---

<!-- https://norns-docs.humansynthesis.ai/norns/pitfalls/verification -->

# Verification workflow

> The order to run checks before calling a change done, and the runtime gotchas that type checks do not catch.

1. **`bun run lint`** (`norns lint`). Must show 0 errors. `--json` for machine-readable output.
2. **`bun run check`** (`norns check`). Must exit 0. Pug and Civet errors point at the line you wrote; Svelte errors inside Pug-rendered markup are reported against the preprocessed output, which `norns diag --template` prints.
3. **`bunx norns diag <file>`** when an error message is unhelpful, to see whether the source is right and the bug is elsewhere.
4. **`bun run build`**. A few seconds on a small app and the final word on whether everything compiles.
5. **`curl` through the dev server** for any request-path change, including POST and form actions. That is where Bun-versus-Node and Pug-versus-Svelte differences surface.

## Gotchas type checks do not catch

- `event.locals.container` is the per-request DI scope set by `contextHandle` in `boot()`. Take `container` from the wrapper context; do not destructure DI out of raw event arguments.
- Body parsing is content-type driven. Form actions read `formData()`; a client that posts JSON must call a `+server.c` endpoint wrapped in `route()`.
- `svelte-check` never reads `.n` or `.c` files. In a workspace checkout it also reports framework-source errors reached through symlinks. It is not the pass signal for Norns code.
- Keep a single owner for the database handle. One `module.c` registers `db`; everyone else resolves it.
- `Bun.password.hash` is undefined when Vite launches under Node; use `node:crypto.scrypt` for passwords.