@weft-js/cli 0.0.0-stage → 0.1.1

package/docs/lists.md

@@ -0,0 +1,23 @@
+# Lists and conditionals
+
+- `xs.map(x => <Row key={x.id} … />)` in JSX is a keyed list. Each key keeps its row; a new object under the same
+  key updates the row in place.
+- Over objects, a missing `key` is **W010** (autofix to `key={x.id}` when items have `id`). Over primitives, the
+  value is the key.
+- `xs.filter(…).sort(…).map(…)` works; put the chain in a `derived` when other code needs it too.
+- No early `return` inside the `.map` callback (**W013**). Filter first.
+- `cond && <X/>` with a number on the left renders `0` (**W011**). Write `n > 0 &&`.
+- **Stable items (W014).** `xs.value = xs.value.map(p => ({ ...p, price }))` gives every item a new identity, so
+  every row re-runs on every change (1 DOM write, hundreds of re-runs). Replace only what changed:
+
+  ```ts
+  products.value = products.value.map(p => (p.id === id ? { ...p, price } : p))
+  ```
+
+  The compiler sees this inside one file; `weft check` follows the box through props into other files.
+- **One entry per row (W017).** A row that reads `cart[p.id]` (a prop) or `cart.value[p.id]` depends on the whole
+  `cart`, so adding one item re-runs all 150 rows. Read the entry from the box: `cart.get(p.id)` re-runs only the row
+  whose entry changed (`Object.is`). For a prop, pass the box (`cart={cart}`, typed `State<Cart>`); the box form
+  has an autofix. The same holds one step further: passing `live={live.value[s.id]}` to a row component, or a row
+  component reading `live.value[stock.id]` (in JSX or `derived`), re-runs every row. Pass the box and read
+  `live.get(stock.id)` in the row.

package/docs/meta.md

@@ -0,0 +1,82 @@
+# Page metadata and share cards
+
+Every page has a title, a description, a canonical URL, Open Graph and Twitter tags and a share card, in the first
+response, where a crawler can read them. Most of it is automatic. The words are yours.
+
+## Set `meta` as you build the page
+
+Writing a page includes writing what a search result or a shared link says about it. A title, and one plain sentence
+on what the reader gets, from what is on the page:
+
+```tsx
+import type { Meta } from '@weft-js/start'
+
+export const meta: Meta = { title: 'Pricing', description: 'Three plans, billed monthly, and what each one includes.' }
+```
+
+On a param route, build it from `data` and `params`, so each page says what it is:
+
+<!-- example: skip needs the app's own getUser query -->
+```tsx
+// src/routes/users/[id].tsx
+import { notFound, type LoadArgs, type Meta } from '@weft-js/start'
+import { getUser } from '#/server/users'
+
+export const load = async ({ params }: LoadArgs<'/users/[id]'>) => (await getUser.fetch({ id: params.id })) ?? notFound()
+export const meta: Meta<typeof load> = ({ data }) => ({ title: data.name, description: data.bio })
+```
+
+`meta` is plain data: it runs once per request after the loaders and before the first byte. It can't read a box (H006)
+or a deferred field (H007). Set `title: { absolute: 'Home' }` to skip the template, `og`, `twitter` and `extra` for
+what else a page needs, and `jsonLd` for structured data. Layers merge in this order, later winning: `site` in
+`weft.config.ts`, what the page rendered, each layout's `meta`, the route's `meta`.
+
+## What weft does for you
+
+With no `meta`, or a `meta` that leaves a field out:
+
+- **Title:** the page's `h1`, or with none its first `h2` or `h3`, through `site.title`.
+- **Description:** the first paragraph after the `h1` that reads as prose, inside `<main>`, with lists, code, tables,
+  navigation and footers skipped, cleaned, and cut at a sentence by 155 characters. With none, `site.description`.
+- **Share card:** `site.image` defaults to `'auto'`: a 1200×630 PNG of the title, description, app name and address,
+  in warp's colours and the text plugin's faces. `site.card` sets them (`scheme: 'light'`, `accent: '#rrggbb'`).
+  `routes/x.og.tsx` replaces one route's card, `_default.og.tsx` every card; `og: { image: '/x.png' }` or `image: false`
+  skips it. The URL holds a hash of what it draws, so it's cached forever and changes when the page does.
+- **`twitter:card`** is `summary_large_image` when there is an image. **Canonical and `og:url`** come from the origin.
+- **Structured data:** a `WebSite` on `/` when `site.name` is set, and nothing else unless `jsonLd` sets it: weft
+  doesn't guess.
+
+Pages with a card are drawn by `weft build` when they have no params or are in `prerender`. Every other param page's
+card is drawn on the first request, and only for params the route's own `load` accepts. A static host has no server, so
+there a param route needs `prerender` (H002).
+
+## The site's address
+
+Absolute URLs need one: `site.url`, or `WEFT_SITE_URL`, or what the host sets (`VERCEL_PROJECT_PRODUCTION_URL`,
+`VERCEL_URL`, Netlify's `URL`, `CF_PAGES_URL`, `RENDER_EXTERNAL_URL`, `RAILWAY_PUBLIC_DOMAIN`, `FLY_APP_NAME`). With none, a
+server uses the request's origin, which is only what its `Host` header said, and warns once in production (H001). A
+prerendered page has no request, so it stays relative: crawlers don't resolve that, so set `site.url` before you ship.
+
+## See it, and fix it
+
+`weft check` reports metadata for every route, from what the routes really produce. Param routes are sampled from
+`prerender` and from the links on rendered pages. Each diagnostic says what to write; H011's fix is a `meta` to start from.
+
+| Code | What it says |
+|---|---|
+| H001 | no `site.url` |
+| H002 | a param route's card, on a static host, with no `prerender` |
+| H003, H004 | no description; a title over 60 or a description over 160 |
+| H005, H008 | a card's style or image failed |
+| H006, H007 | `meta` read a box or a deferred field |
+| H011 | no `meta`, or a field left out: says what was derived |
+| H012, H013 | two routes share a title or a description |
+| H014 | a param route whose pages all look alike |
+| H015 | a description that reads like code, markdown or a fragment |
+| H016 | a route that couldn't be checked here (`check: { routes: false }` turns the pass off) |
+
+`weft routes --meta` is a table of each page: title, description, image and where each came from (`route`, `layout`,
+`config`, `auto`, `card`). `--json` has every tag. It's the `routes_meta` tool of `weft mcp`.
+
+Never slice raw markdown or code into `description`: `body.slice(0, 155)` is how a page's card ends up reading
+`- xs.map(x = <Row`. Write the sentence, or leave it out and let the page speak.

package/docs/plugins.md

@@ -0,0 +1,143 @@
+# How pay is built
+
+A plugin is one pure manifest. `@weft-js/pay` is the worked example: payments, with a webhook, a ledger, a fake for tests, its
+own diagnostics and `weft add` steps. It uses only what any plugin can use, and a test holds that to be true: `weft`,
+`@weft-js/start` and the CLI don't name it. Read `packages/pay/plugin.mjs` next to this page. It's 50 lines.
+
+## The shape
+
+```
+packages/pay/                     packages/pay/ (`src/stripe.ts`)
+  plugin.mjs       the manifest     plugin.mjs       a `pay.rail` provider
+  src/index.ts     client-safe      src/index.ts     stripeRail(options)
+  src/server.ts    the ledger
+  src/test.ts      fakePay, payRailSuite
+  src/checks.mjs   PAY-codes
+  src/setup.mjs    `weft add pay`
+  docs/pay.md      `weft docs pay`
+```
+
+Two packages, because they answer different questions. `@weft-js/pay` is what payments means here, and it names no provider.
+A rail is how a payment happens. `fakePay` is a second rail, which is how you know the seam is real.
+
+## 1. Start from `definePlugin`
+
+```js
+export const pay = definePlugin({
+  name: '@weft-js/pay', version: '0.1.0', weft: '*', namespace: 'PAY', permissions: {},
+  contribute: () => ({ provides: [...], diagnostics, check, docs, setup, agents, catalog, map }),
+})
+```
+
+`weft check` loads every plugin, so `plugin.mjs` stays pure and light: no I/O, nothing heavy imported. Heavy parts sit behind
+`import()`. `namespace` is the prefix of your diagnostic codes, by default `<name>/`. `permissions` is what the plugin
+reaches. Pay reaches nothing, so it's `{}`; the Stripe plugin declares `net: ['api.stripe.com']` and the two `env` keys it reads,
+and `weft add` shows them for approval (`weft docs config` has the lock).
+
+## 2. Reach the server with a slot
+
+A slot is a typed seam: the id, a version, keyed or one, and the sides it runs on. Providers name a module, which weft
+imports lazily, on that side only. That's why an app that doesn't use a plugin carries none of its bytes.
+
+Pay provides `server.extension`, the slot for anything that needs a server presence:
+
+```js
+provide(defineSlot({ id: 'server.extension', version: 1, cardinality: 'keyed', sides: ['server'] }),
+  { key: 'pay', sides: { server: { module: '@weft-js/pay/server', export: 'extension' } } })
+```
+
+The key is the mount: `/_weft/x/pay/...`. A keyed provider also needs `src/<key>.server.ts`, the app's own configuration, and
+weft passes that module's default export to your provider. So `src/pay.server.ts` is `definePay({...})`, and the provider is
+one line: `extension = app => app`. A `ServerExtension` (`@weft-js/start/extension`) may have any of:
+
+| Member | What it does | What pay uses it for |
+| --- | --- | --- |
+| `handle(request, path, api)` | Answers `/_weft/x/<key>/<path>` | Webhooks; `api.invalidate(tags)` pokes live queries |
+| `context(ctx)` | Adds to `ctx`, once per request | `ctx.entitlements` |
+| `guard(fn, ctx)` | Runs before every server function | `requires: ['pro']`, a typed 403 |
+| `options` | The `FnOptions` keys it enforces; with no extension, a call using one is refused | `requires` |
+| `personal` | `ctx` keys a shared cache can't read | `entitlements` (Q006) |
+| `check(dev)` | Refuses a bad boot | The in-memory ledger in production |
+
+Types follow: augment `Context` and `FnOptions` in `declare module '@weft-js/start'`, and `ctx.entitlements` and `requires`
+are typed in any app that imports your server module. An error class with an `answer` getter reaches the client as a
+typed error, with that code and status.
+
+## 3. Define a slot of your own
+
+Pay's `pay.rail` slot is why Stripe is one line in `plugins`. Say what a provider must implement, as a TypeScript interface
+(`PayRail`), and ship a suite that holds any provider to it (`payRailSuite`). Your consumer reads the slot like any other:
+
+```ts
+const { load, providers } = await import('weft:slot/pay.rail')
+const rail = await load('stripe')
+```
+
+Another provider means another `provide(...)`, and app code doesn't change. A plugin's own slot is named `<plugin name>.<slot>`;
+`pay.rail` keeps its short name only because it was in weft's slot table from the start. `@weft-js/pay/stripe` is a short manifest,
+and a good template for a provider.
+
+## 4. Report your own diagnostics
+
+`diagnostics` declares each code: severity, what it catches, the fix. `check` finds them:
+
+```js
+check: { include: ['src/**/*.{ts,tsx}'], run: ctx => import('./src/checks.mjs').then(c => c.run(ctx)) }
+```
+
+`run(ctx)` gets `files`, `read`, `exists`, `jsx`, `slots`, and returns findings: `{ code, file, start, end, why, help?, fix? }`.
+A `fix` is `{ description, safe, edits: [{ start, end, text }] }`; `weft fix` applies the safe ones. Weft does the spans,
+`--json` and `weft docs PAY012`. A code outside your namespace is `P111`. A hook that throws is `P119` and nothing worse.
+
+`src/checks.mjs` is the example to copy: a regex decides which files parse, TypeScript is imported only there, and the
+checks that say the most are the ones a type can't: PAY013 (an entitlement read on the client that no server code names),
+PAY011 (a webhook handler with no signature check). Test a hook as a plain function of a map of files
+(`test/checks.test.mjs`).
+
+## 5. Give it a fake
+
+A plugin that talks to the outside world ships the fake with it. `fakePay` is a real `PayRail` in memory, and reaches `@weft-js/core/test`
+only through what's public: `net.extension(pay)` puts your extension in the test's scope and resets it afterwards, `net.poke`
+delivers tags to live queries, `clock` moves time. Events go through the app's real webhook and ledger, so a test
+sees what a user sees. It's imported from `@weft-js/pay/test`, since core can't depend on a plugin.
+
+## 6. Make `weft add` do the wiring
+
+`setup` is data. `weft add pay` reads it after installing the package:
+
+```js
+export const setup = {
+  with: ['@weft-js/pay/stripe'],     // added too
+  needs: ['db', 'auth'],                 // refused, with nothing changed, until they're there
+  run({ engine, layer, read }) {
+    return { files: {...}, edits: {...}, env: { STRIPE_SECRET_KEY: 'sk_test_placeholder' }, next: ['...'] }
+  },
+}
+```
+
+`run` describes and never writes, so a dry run and a refusal are free. A file that already exists stops it before anything
+changes. `env` goes to `.env` and `.env.example`: use placeholders.
+
+## 7. Say what an agent needs
+
+- `agents`: one paragraph for the generated `AGENTS.md`, 1 KB at most.
+- `docs`: `{ topic, summary, file }`, served by `weft docs <topic>`.
+- `catalog`: your exports, `{ name, import, summary }`, listed by `weft plugins --json`.
+- `map`: "want this, call that" lines.
+- `diagnostics`: each is a page: `weft docs PAY012`.
+
+## Checklist
+
+1. `plugin.mjs` is pure, with heavy code behind `import()`.
+2. No app code names your provider; one line in `plugins` changes it.
+3. Client entries hold no server code. `packed.mjs` checks that an app without you has none of your bytes.
+4. A fake that goes through your real code path.
+5. A suite for providers, passing on your fake and each real provider.
+6. Every failure a type can't catch is a code with a fix.
+7. If the API lacks something you need, add it for everyone. Pay added `server.extension`, `setup`, plugin `docs`, `net.extension`
+   and the `FnOptions` interface that way.
+
+## Rust, and when not to
+
+A plugin can carry its own wasm, with a TS fallback and nothing in client bytes. Measure first. `packages/pay/bench/verify.mjs`
+did, for webhook verification, and pay stayed on WebCrypto, which was fast enough.

package/docs/props.md

@@ -0,0 +1,77 @@
+# Props
+
+## Types
+
+Leave a component's props unannotated. weft infers them from its callers and its body, in the editor (the plugin in
+`tsconfig.json`), `weft check`, `weft tsc` and `weft dev`. Nothing is left at run time.
+
+```tsx
+function Row(props) {
+  return <li><button type="button" onClick={props.onPick}>{props.label.toUpperCase()}</button></li>
+}
+export default function List() {
+  return <ul><Row label="One" onPick={() => console.log('picked one')} /></ul>
+}
+```
+
+| Case | What you get |
+|---|---|
+| Several callers | A union if the body handles it; if not, **W084** at the odd caller |
+| Some callers omit a prop | Optional; a default value also types it |
+| `<Button {...props} />` | `Button`'s props |
+| A component in a variable, map or prop | Its sites count, and prop sets merge |
+| Callers that differ by a string prop | A union of shapes the body can narrow |
+| `src/routes` default export | `RouteProps` |
+| An export | `weft dev` or `weft fix` writes the type with an `/*inferred*/` comment, so it shows in a diff. **W082** when callers move on; delete the comment to keep the type |
+| An `any` from a caller | The body's use, or `any`, with **W083** naming where it came from |
+| No caller | **W080**, with what to do |
+| `bind:x={box}` | The box's value, and it satisfies a required `x` under `weft tsc` and in the editor |
+
+Write a type yourself when two props must agree (a type parameter), when the file is `.jsx`, or for a public API with no
+caller in this repository. `Props<typeof Button>` names another component's props. `tsc` alone reports TS7006 on an
+inferred parameter; run `weft tsc` in CI. `check: { props: false }` turns this off; `'manual'` leaves writing to `weft fix`.
+
+## Reactivity
+
+The compiler turns a component's props into live reads, so a parent writing `count={count.value}` is correct.
+
+| Form | Behaviour |
+|---|---|
+| `({ a, b }) =>` | Each name is a live read of `props.a` |
+| `(props) =>` | `props.a` is a live getter |
+| `({ size = 'md' }) =>` | Default applied on every read when the prop is `undefined` |
+| `({ a, ...rest }) =>` | `rest` is a live object; `<div {...rest}>` stays live |
+| `const x = props.y` in the body | `x` is another name for the prop: each use reads it live, at no cost |
+| `const { a: b, c = 1, ...rest } = props` in the body | The same as in the parameter: renames, defaults and rest stay live |
+| `const n = props.items.length` in the body | A path off a prop is live too |
+| `({ user: { name } }) =>` | **W006**: nested destructuring can't stay live. Read `user.name` at the use site (autofix) |
+
+- The local isn't a copy: every use, closures included, reads the prop as it is at that moment. For a value that must
+  stay as it was, write the snapshot out: `const first = untrack(() => props.x)`.
+- Computing in the body runs once: `const n = items.length + 1`, `const a = props.a ?? 1` or `makeChart(items)` is
+  **W001**. Use `derived`, `watch`, JSX or a handler.
+- Array patterns and computed keys (`const [a] = props.pair`, `const { [k]: a } = props`) are **W001**: read them at
+  the use site.
+- `const` stays read-only: assigning to a `const` alias is **W001**, which says to use `let` or `props.x =`.
+- `state(prop)` never follows the prop (**W005**). Use `state.linked(() => prop)` for an editable local copy.
+- Pass a box (`value={coupon}`) only when the child must write it; otherwise pass `.value`.
+
+## Writing a prop
+
+A component can write its own props. `let` makes a local writable; `+=`, `++` and `let { a } = props` work too.
+
+| In the child | Parent passed `n={x}` | Parent passed `bind:n={box}` |
+|---|---|---|
+| Read `n` or `props.n` | Live | Live |
+| `let n = props.n; n = 5` | Holds in the child until the parent's value next changes, then the parent wins | Writes `box` |
+| `props.n = 5` | The same | The same: writes `box` |
+| `const n = props.n; n = 5` | **W001**: use `let` or `props.n =` | **W001** |
+
+`bind:` at the call site alone decides whether a write leaves the component. `<Card n={box.value} />` never writes
+`box`, whatever `Card` does. It takes a box, on a component (**W061** otherwise). `weft tsc` and the editor read
+`bind:n={box}` as `n` with the box's value, so it satisfies a required prop and a wrong type is an error. Plain `tsc`
+can't connect `bind:n` to `n` and reports the prop as missing: run `weft tsc`. `n={bind(box)}` is the same binding in
+a form plain `tsc` accepts. An island's props arrive as data, so a write there is always local.
+
+Only a whole prop can be written this way. `let n = props.user.name; n = 1` is **W001**; `props.user.name = 1` writes
+that object, as in any JavaScript.

package/docs/rules.md

@@ -0,0 +1,32 @@
+```tsx
+import { derived } from '@weft-js/core'
+
+export function Cart({ items, taxRate }: { items: { id: string; name: string; price: number }[]; taxRate: number }) {
+  const subtotal = derived(() => items.reduce((s, i) => s + i.price, 0))
+  const total = derived(() => subtotal.value * (1 + taxRate))
+  return (
+    <section>
+      <ul>{items.map(item => <li key={item.id}>{item.name}</li>)}</ul>
+      <p>{total.value.toFixed(2)}</p>
+    </section>
+  )
+}
+```
+
+1. **State is a box. Read and write `.value`.** Everywhere, JSX included (W015).
+2. **Anything computed from other values is `derived`.** Not in a `watch` or the component body (W001).
+3. **JSX is always live.** Every `{expr}` and attribute re-evaluates when what it reads changes.
+4. **Props are always current.** Destructure them (one level, W006). Read them in `derived`, `watch`, JSX or handlers.
+   `const x = props.y` is a live read-only alias. `let x = props.y` and `props.y =` write locally; only `bind:y={box}`
+   writes out.
+5. **The component body runs once.** No early returns on state (W040), no `let` counters (W041). Branch in JSX.
+6. **Pass a box only to give write access** (`value={coupon}`, child prop typed `State<string | null>`), or so list
+   rows can read one entry: `cart.get(p.id)` re-runs one row, `cart[p.id]` or `cart.value[p.id]` re-runs them all
+   (W017), in the list and in the row component alike.
+7. **Lists and conditionals the way you know them**: `.map` with `key` (W010), `&&`, ternaries. Keep list items
+   stable: replace only the item that changed (`p.id === id ? { ...p, price } : p`), never `({ ...p })` every item
+   (W014).
+8. **Copy a prop into state with `state.linked(() => prop)`**, not `state(prop)` (W005). `untrack(() => …)` is a
+   snapshot that never updates: not for anything you render (W018).
+9. **Side effects go in `watch(() => source, value => cleanup?)`**; DOM work in `onMount`. `flush()` applies pending
+   DOM updates now.

package/docs/rust.md

@@ -0,0 +1,223 @@
+# Rust: `native()` and `remote()`
+
+Rust is optional. weft needs no Rust toolchain to create, run, build or check an app, on any platform: the compiler ships as
+WASM, and a prebuilt native addon installs by itself where one fits, which makes builds faster and changes no output.
+`weft doctor` says which one is running. Rust is for this page: the code you choose to write in it, which is the only thing
+that calls `cargo`.
+
+A server function can have a Rust body. The client doesn't change: the same import, call, cache, tags and errors. Zod
+stays the only schema. Reach for this at about 1 ms of CPU per call or on byte payloads (search, parsing, images), not for
+IO-bound CRUD.
+
+| | `native('media')` | `remote('rust://search')` |
+|---|---|---|
+| Runs | in the server's process: an addon, or WASM where one can't load | a sidecar, over loopback or another host |
+| Good for | one hot CPU function | many functions, IO, anything with its own state or runtime |
+| Costs per call | ~10–30 µs | ~50–80 µs |
+| A panic costs | that call | that call |
+| A hang costs | a worker thread until it returns | nothing here: the sidecar is killable |
+
+`weft add rust [name]` writes a working crate, its module and one function, with `native()`; `--remote` writes a sidecar.
+The crate's code is the same `impl Service` either way, so moving between them is a line in `src/server/rust.ts` and the
+glue at the bottom of the crate.
+
+## Swap a `run` for `impl`
+
+```ts
+// src/server/rust.ts: the only place Rust targets are named
+import { remote } from '@weft-js/start/rust'
+export const search = remote('rust://search')
+```
+
+<!-- example: skip imports src/server/rust.ts from the block above -->
+```ts
+// src/server/docs.ts
+import { query } from '@weft-js/start'
+import { z } from 'zod'
+import { search } from './rust'
+
+export const searchDocs = query({
+  input: z.object({ q: z.string().trim().min(1).max(200), limit: z.int().min(1).max(50).default(10) }),
+  output: z.array(z.object({ id: z.string(), title: z.string(), score: z.number() })),
+  tags: ['docs'],
+  impl: search,          // was: run: ({ input }) => rank(input.q, input.limit)
+})
+```
+
+`output` is required on an `impl`. `crates/search` is the crate, unless config says otherwise. `weft add rust` writes all of
+this; the `weft` path is inside `@weft-js/start`, because the crate isn't on crates.io yet:
+
+```toml
+# crates/search/Cargo.toml
+[dependencies]
+serde = { version = "1", features = ["derive"] }
+tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
+weft = { path = "../../node_modules/@weft-js/start/crate" }
+
+[build-dependencies]
+weft = { path = "../../node_modules/@weft-js/start/crate", default-features = false, features = ["build"] }
+```
+
+```rust
+// crates/search/build.rs
+fn main() { weft::build::generate("search"); }
+```
+
+```rust
+// crates/search/src/main.rs
+weft::contract!();          // types and a `Service` trait, generated from your Zod: never hand-written
+use contract::*;
+
+struct Search;
+
+impl Service for Search {
+    async fn search_docs(&self, ctx: weft::Ctx, input: SearchDocsInput) -> Result<SearchDocsOutput, weft::Error> {
+        ctx.touch("docs");
+        Ok(vec![])
+    }
+}
+
+#[tokio::main]
+async fn main() -> std::io::Result<()> {
+    weft::serve(weft::router(contract::functions(Search))).await
+}
+```
+
+Use Rust 1.99 or newer (`rust-toolchain.toml` pins it). A method is the function's name in snake case; a type is its name plus `Input`, `Output`, or a
+property's name in pascal case.
+
+## In-process: `native()`
+
+The same `Service`, in a library. `crate-type = ["cdylib"]`, and `features = ["native"]` on `weft` in place of the server:
+
+```rust
+// crates/media/src/lib.rs
+weft::contract!();
+use contract::*;
+
+struct Media;
+impl Service for Media {
+    async fn thumbnail(&self, ctx: weft::Ctx, input: ThumbnailInput) -> Result<ThumbnailOutput, weft::Error> { /* … */ }
+}
+
+weft::native!(contract::functions(Media));
+```
+
+```ts
+// src/server/rust.ts
+import { native } from '@weft-js/start/rust'
+export const media = native('media')          // options: timeout, claims, validate, as for remote()
+```
+
+- An addon runs each call on the worker pool, so a long one doesn't hold the event loop. `native()` sizes the pool to the
+  machine unless `UV_THREADPOOL_SIZE` is set.
+- `weft build` also builds `wasm32-unknown-unknown` with SIMD on. With no addon for the platform, the server loads the
+  `.wasm` and says so. WASM runs on the event loop, as a TS `run` does.
+- There's no async runtime in it. A method may be `async`, but one that waits on IO belongs in `remote()`; on WASM, one that
+  waits is R108.
+- `timeout` stops TS waiting (R107). A call can't be stopped from outside: check `ctx.cancelled()` in a long loop.
+- A panic is R108 for that call. On WASM it ends the instance, and the next call gets a new one, so a static is lost.
+- Bytes cross as JSON, so `z.base64()` for now: the call costs more than the `Buffer` it could be.
+
+## What happens where
+
+TS keeps the public edge: sessions, CSRF, input validation, the cache, `auth`, `tags`, `invalidates`. Rust gets one crossing
+per call (a signed POST for a sidecar): the parsed input, the user's claims (never cookies), `traceparent` and a deadline.
+TS then validates the output, in production too. Set `remote(target, { validate: false })` to trust it.
+
+Options on `remote(target, options)`: `url` (else `WEFT_RUST_<NAME>_URL`), `timeout` (ms, default 10000), `claims`
+(`user => …`, default `id`, `roles`, `tenant`), `validate`.
+
+## The context
+
+| A function that is | Its `ctx` | `user()` |
+|---|---|---|
+| `auth: 'user'` | `weft::UserCtx` | `&User`, always there |
+| cached with shared scope | `weft::SharedCtx` | doesn't exist, so it can't leak into a shared cache |
+| anything else | `weft::Ctx` | `Option<&User>` |
+
+All three have `ctx.touch(table)`, `ctx.tag(tag)`, `ctx.remaining()`, `ctx.cancelled()`, `ctx.request_id()`,
+`ctx.traceparent()`.
+
+- `ctx.touch("docs")` reports a table it read or wrote. In dev it feeds Q011, like a TS `run`'s. A cached query with `tags`
+  that never calls it is R105; a query that reads no table should drop `tags`.
+- `ctx.tag("doc:7")` adds a cache tag. It joins the declared ones; Rust can't remove any.
+
+## Typed errors
+
+<!-- example: skip a fragment of src/server/docs.ts -->
+```ts
+export const getDoc = query({ input, output, errors: { NotFound: z.object({ id: z.string() }) }, impl: search })
+// a TS body raises the same thing: run: () => raise('NotFound', { id })
+```
+
+```rust
+async fn get_doc(&self, ctx: weft::Ctx, input: GetDocInput) -> Result<GetDocOutput, GetDocError> {
+    Err(GetDocError::NotFound(GetDocNotFound { id: input.id.to_string() }))
+}
+```
+
+The client catches `e.code === 'NotFound'` and `e.data`, either way. A panic or `weft::Error` is R108: the client gets a
+request id, and the detail stays in the sidecar's log.
+
+## Types that cross
+
+- JSON only. `z.date()` is R101: use `z.iso.datetime()`, or `z.codec(z.iso.datetime(), z.date(), …)` for a `Date` in TS.
+- `.trim()`, `.default()` and codecs are fine. A one-way `.transform()` on an input is R101, as it can't be encoded back.
+- An output may transform: TS parses what Rust sends.
+- `z.void()` is R101: use `z.null()`.
+- Tag a union of objects with `z.discriminatedUnion`. A plain one is R102, or set `rust: { unions: 'allow' }`.
+- The wire is the input side of each schema, so Rust sees what the codec encodes.
+
+## `weft dev`, `build`, `start`
+
+- `weft dev` builds each sidecar, waits for the first build, and rebuilds on an edit. The new binary starts beside the old
+  one, takes over when it's healthy, and the old one drains, so no request fails. A failed build keeps the old one
+  running and prints R103 or R109.
+- A `native()` crate rebuilds the same way, and no restart is needed: each build is a new file, the next call loads it, and
+  calls on the old one finish. An addon can't be unloaded, so a long session holds its old copies (about 0.5 MB each); they
+  go when `weft dev` stops.
+- `weft check` runs `cargo check`, and stops at the Rust a schema edit broke, with the function's id (R103). For a
+  `native()` crate it checks the WASM build too (R104), and reads each cached query for `touch` (R105).
+- `weft build` runs `cargo build --release`, runs the sidecars while it prerenders, and ships them in `.output/rust/`.
+  A `native()` crate's addon and `.wasm` go in `.output/server/rust/`, so whatever moves the server moves them.
+- `weft start` runs them on loopback, restarts a crash with backoff, and stops them when it stops. A dead sidecar costs
+  its functions (R107), not the server.
+
+## Deployment and settings
+
+```ts
+// weft.config.ts
+rust: {
+  unions: 'allow',                                   // let plain object unions through (R102)
+  services: {
+    search: { crate: 'native/search' },              // default: crates/<name>
+    core: { external: true },                        // built and run elsewhere: no cargo here
+    imaging: { wasm: false },                        // links C, and this host has an addon: no fallback (R104)
+  },
+}
+```
+
+A sidecar on another host needs `external: true`, `WEFT_RUST_<NAME>_URL`, and the same `WEFT_RUST_SECRET` on both sides;
+`weft dev` and `weft start` make those themselves for sidecars they run. Bind it privately: it trusts only the signature,
+and the claims in it. The binary reads `WEFT_LISTEN` (default a free loopback port); a build reads `WEFT_CONTRACT`, or finds
+`.weft/contract.json` above the crate. `GET /_weft/health` gives its service, contract hash, functions and pid. An edge preset can call `remote()`, as it is only
+`fetch`, but something else must run the sidecar. `native()` needs a file system, so on an edge preset it's R104: use
+`remote()`, the same crate behind `weft::router`.
+
+Each call is a `tracing` span with `trace_id` and `parent_id`. With the `otel` feature and your own OpenTelemetry layer,
+the span continues TS's trace.
+
+In a test, `handlers` replaces a function as it does a `run`, and nothing crosses.
+
+## Diagnostics
+
+- **R101** no `output`, a type JSON can't carry, or a one-way input transform.
+- **R102** a plain `z.union` of objects.
+- **R103** the Rust and the contract disagree: at `cargo`, in a binary's hash, or in an output or undeclared error at runtime.
+- **R104** `native()` on a preset that can't run it, a `.wasm` that won't build, or a build with nothing for this platform.
+- **R105** a cached query with `tags` that reports no table.
+- **R106** no address, no secret, or a refused signature.
+- **R107** not answering, or past the deadline.
+- **R108** a panic or `weft::Error`.
+- **R109** the crate doesn't build for a reason unrelated to the contract, or it isn't there.

package/docs/start-short.md

@@ -0,0 +1,8 @@
+`@weft-js/start` app: file routes in `src/routes` (`_layout.tsx`, `[id].tsx`, `load`, `meta`), server functions in `src/server/**` or `*.server.ts`. Read `weft docs start` first. Import your own code as `#/server/todos` (`src/server/todos`); generated files are `weft:slot/<id>` and `weft:tokens/<name>`.
+
+- **Reads:** `query({ tags: ['todos'], auth: 'user', run: ({ ctx }) => ctx.db.select().from(todos) })`. In a component `todos().value ?? []`; in `load` and handlers `await todos.fetch()`.
+- **Writes:** `mutation({ input, auth: 'user', invalidates: ['todos'], optimistic, run })`.
+- **Database:** Drizzle; `await` every statement. Schema change: `weft db generate` (Q015). Inputs: `schemas.todos.insert.pick({ title: true })`.
+- **Auth:** `ctx.user` is the user or `null`; `auth: 'user'` refuses anyone else (A002). A guard is `redirect('/login')` in a layout's `load`. `run` must still check who owns a row.
+- **Never** copy query results into `state`, import `db` from a component (Q012), `fetch` `/_weft/*`, or poll (`todos.live()`; rooms: `channel`).
+- **Every page sets `meta` as you build it**, from `data` and `params`: `weft docs meta`.