@abide/abide 0.28.0 → 0.30.0

package/AGENTS.md

@@ -0,0 +1,242 @@
+# AGENTS.md — abide complete surface map
+
+> Generated from the source as the single index of abide's public featureset, so an
+> agent can grasp the whole API in one read and know which file to open for depth.
+> The README is the curated human intro (3 primitives); this is the exhaustive map.
+> CONTEXT.md is the domain glossary; docs/adr/ holds design rationale.
+>
+> **Ground rule:** every public name has its own module path — no barrels. The
+> namespace marks the side: `abide/server/*` server-only, `abide/ui/*` client-only,
+> `abide/shared/*` isomorphic (same callable, same behaviour on both sides; the
+> bundler swaps the runtime). Package: `@abide/abide`. Runtime: Bun ≥ 1.3, web
+> standards only, zero runtime deps.
+>
+> **Two kinds of path below.** Import specifiers (`abide/server/GET`) are the stable
+> identity — that's what you import. File paths like `src/lib/...` are *inside the
+> abide package* (relative to this file: `packages/abide/` in this repo,
+> `node_modules/@abide/abide/` when abide is a dependency); the published package
+> ships `src`, so those files are readable in both. Paths like `src/server/rpc/...`
+> and `src/.abide/...` in the conventions table refer to **your own app**, not the
+> package.
+
+---
+
+## The premise
+
+One declared verb fans out to every surface, with no extra work:
+
+```
+       export const getMessages = GET(fn, { inputSchema })
+                                 │
+   ┌───────────────┬────────────┼──────────────┬────────────────┐
+ SSR call      browser fetch    MCP tool      CLI subcommand   OpenAPI op
+cache(fn)()   fetch /rpc/...   (read-only +    app get-messages  /openapi.json
+(in-process)  (typed proxy)     schema → tool)  (schema → flags)  (described)
+```
+
+A Standard Schema (zod / valibot / arktype, unadapted) is the contract: it
+validates args and projects the CLI flags, the MCP tool, and the OpenAPI operation.
+The schema gates the machine surfaces — it unlocks CLI and (for read-only/GET verbs)
+MCP; a mutating verb never auto-exposes to MCP, it needs explicit `clients: { mcp: true }`.
+
+## File-based conventions (the bundler reads these paths)
+
+| Path | Meaning |
+|---|---|
+| `src/server/rpc/<name>.ts` | one RPC verb per file; file path = URL (`/rpc/<name>`), one export named after the file |
+| `src/server/sockets/<name>.ts` | one broadcast socket per file; multiplexes onto `/__abide/sockets` |
+| `src/mcp/prompts/<name>.md` | MCP prompt template (`{{arg}}` placeholders) → `definePrompt` |
+| `src/server/config.ts` | `export const config = env(schema)` — boot-validated env, also drives the bundle setup form |
+| `src/app.ts` | optional app module: `handleError`, `health()` hook, lifecycle (see `AppModule`) |
+| `src/bundle/window.ts` | optional desktop bundle window config (`BundleWindow`, default export) |
+| `**/page.abide` | a page; directory path → route in bracket form (`/post/[id]`, `/docs/[...rest]`) |
+| `**/layout.abide` | nearest-only layout wrapping a page via `<slot/>` (layouts never stack) |
+| `src/.abide/*.d.ts` | generated: route/param/rpc/health types (do not hand-edit) |
+| `public/<file>` | static asset, served at `/<file>` |
+| `dist/_app/` | `abide build` output; `dist/` is what `abide start` serves |
+
+## CLI (`bunx abide <cmd>` / `abide <cmd>`)
+
+| Command | Does |
+|---|---|
+| `scaffold <name>` | scaffold a project, install, start dev (`--no-install` / `--no-dev`) |
+| `dev` | build + run with hot reload |
+| `build` | build the client into `dist/_app/` |
+| `check` | type-check `.abide` templates + props |
+| `start` | run the production server against `dist/` |
+| `run <file> [args]` | run a script under the abide preload (same runtime as the server) |
+| `compile [--target] [--out]` | build a standalone server executable |
+| `cli [--target] [--out] [--platforms]` | build the cli client binary (ships the server beside it; cross-compiles) |
+| `bundle` | build a movable self-contained desktop app bundle (unsigned) |
+| `lsp` | language server for `.abide` files |
+
+For `bun test`, add `preload = ["@abide/abide/preload"]` under `[test]` in `bunfig.toml`.
+
+---
+
+## Server surface — `abide/server/*` (and authored helpers)
+
+### RPC verbs — `@readme rpc`
+Each is `Verb(fn, opts?)` with three overloads (see `src/lib/server/rpc/types/VerbHelper.ts`):
+`Verb(fn, { inputSchema, outputSchema?, filesSchema?, clients?, timeout?, maxBodySize?, crossOrigin? })`,
+`Verb(fn, { clients })`, and bare `Verb(fn)`. Return type usually infers from the
+`TypedResponse<T>` brand on `json`/`error`/`redirect`/`jsonl`/`sse`.
+
+- `abide/server/GET` · `abide/server/POST` · `abide/server/PUT` · `abide/server/PATCH` · `abide/server/DELETE` · `abide/server/HEAD`
+- **Query args travel as strings** — use `z.coerce.*` in the schema for numbers/booleans.
+- `timeout` (ms) bounds the handler on *every* surface → 504; on the network path it also aborts `request().signal`.
+- `crossOrigin: true` exempts a mutating verb from the same-origin CSRF gate (non-GET/HEAD cross-origin browser requests are 403 by default).
+- `filesSchema` enables multipart upload: handler gets text fields ∩ validated `File` parts; call with a `FormData`.
+- `abide/shared/withJsonSchema(schema, toJsonSchema)` — attach `toJSONSchema()` to a schema whose library lacks one (feeds OpenAPI / MCP / CLI help).
+
+The reference each verb returns is a `RemoteFunction<Args, Return>` (see `src/lib/shared/types/RemoteFunction.ts`):
+plain call decodes the body + throws `HttpError` on non-2xx; `.raw` resolves to the
+`Response` undecoded; `.stream(args)` returns a `Subscribable` (SSE/JSONL frames, or
+the decoded body once) for `tail()`; `.fetch(req)` is framework-internal dispatch.
+
+### Responses — `@readme response`
+- `abide/server/json(data, init?)` — JSON with `Cache-Control: no-store`; `json(undefined)` → 204 that round-trips to `undefined`.
+- `abide/server/error(status, message?, init?)` — text/plain error; message defaults to the status reason phrase.
+- `abide/server/redirect(url, status=302, init?)` — accepts relative URLs (platform `Response.redirect` doesn't); 301/302/303/307/308.
+- `abide/server/jsonl(iterable, init?)` — wrap an `AsyncIterable` as JSON Lines stream; errors → final `{"$error":…}` line.
+- `abide/server/sse(iterable, init?)` — wrap an `AsyncIterable` as Server-Sent Events; 15s keepalive; errors → `event: error`.
+- `abide/shared/HttpError` — thrown by remote calls on non-2xx; carries `status`, `statusText`, raw `response`.
+
+### Sockets — `@readme sockets`
+- `abide/server/socket(opts?)` — declare a `Socket<T>` (an isomorphic `AsyncIterable<T>`) inside `src/server/sockets/<name>.ts`. Opts: `{ schema?, tail?, ttl?, clientPublish?, clients? }`. `tail: n` retains last n frames; `ttl` evicts older. HTTP face at `/__abide/sockets/<name>`: GET = retained tail, POST = publish (gated by `clientPublish`).
+
+### Agents — `@readme agent`
+- `abide/server/agent(engine, messages)` — run a model engine against the app's own (already-gated) MCP surface; returns the engine's `AgentFrame` stream. Wrap in `jsonl()`/`sse()` to pick the transport. Types exported: `NeutralMessage`, `AgentFrame` (`text`/`tool_use`/`tool_result`/`done`), `AgentSurface`, `AgentEngine`. Engines live in `@abide/<provider>` packages, never in core.
+
+### Request scope — `@readme request-scope`
+Resolve only during an in-flight SSR render or RPC handler (throw outside one):
+- `abide/server/request()` → the inbound `Request`.
+- `abide/server/cookies()` → Bun `CookieMap`; writes flush as `Set-Cookie` on return.
+- `abide/server/server()` → active `Bun.serve` (or a no-op in-process server under CLI/MCP/test).
+
+### Config / data — `@readme configuration` / `reference`
+- `abide/server/env(schema, opts?)` — validate `Bun.env` against a Standard Schema at module top level; fails boot loudly. Registered so the bundle launcher derives its setup form.
+- `abide/server/appDataDir()` → the running bundle's per-user data dir (cwd-independent, pure).
+
+### Observability — `@readme observability`
+- `abide/server/reachable(host)` — server-only outbound reachability; first call probes (HEAD), then warm-polls every TTL. Tuned by `ABIDE_REACHABLE_TTL` / `ABIDE_REACHABLE_TIMEOUT`.
+- `abide/shared/health()` → `HealthState` (framework + app `health()` hook payload, typed via generated `health.d.ts`); also at `/__abide/health`.
+- `abide/shared/log` — unified logger carrying request-scope context; `log()/warn/error/trace` on the app channel, `log.channel(name)` on a `DEBUG`-gated channel. `ABIDE_LOG_FORMAT=json` for JSON lines.
+- `abide/shared/trace()` → current W3C `traceparent` (isomorphic; client reads the SSR-stamped trace).
+
+### App / inspector types — `@readme plumbing`
+- `abide/server/AppModule` — shape of `src/app.ts` (error handler, health hook, lifecycle).
+- `abide/server/InspectorContext` — inspector wiring type.
+- `abide/server/rpc/defineVerb`, `abide/server/sockets/defineSocket`, `abide/server/prompts/definePrompt`, `abide/server/prompts/renderPromptTemplate` — bundler-emitted runtime bindings; you don't call these by hand (the `GET`/`socket`/`.md` files compile down to them).
+
+---
+
+## Isomorphic surface — `abide/shared/*`
+
+### Cache — `@readme cache`
+- `abide/shared/cache(fnOrProducer)` → a memoised callable. Key auto-derives (method+url+args for a remote fn; producer-reference+args for a producer). Options `{ ttl?, scope?, global?, invalidate? }`: `ttl` ms-past-resolve (omit = forever, `0` = dedupe-only / the **mutation idiom**); `scope` tags for group invalidation; `global` = process-level store (server); `invalidate: { throttle | debounce }` = stale-while-revalidate refetch policy (GET-only, throws on a write).
+- `cache.invalidate(selector?, args?)` — end retention early (by fn, fn+args, `{ scope }`, or all).
+- `cache.patch(selector, updater, args?)` — optimistic local fold over matching entries.
+- `cache.on(subscribable, (frame, ctx) => …)` — event-driven cache maintenance: run a handler per socket/stream frame; `ctx.invalidate` / `ctx.patch` are coverage-tracked and resync on reconnect. Client-only (no-op on server).
+
+### Probes — `@readme probes` (read-only; reading never triggers work)
+- `abide/shared/pending(selector?, args?)` — "no value yet" (in-flight call, or stream awaiting first frame).
+- `abide/shared/refreshing(selector?, args?)` — "holding a value while a fresher source is in flight".
+- `abide/shared/online()` — reactive connectivity probe (server: the calling client's reported state via offline header).
+
+Same selector grammar as `cache.invalidate`; also accept a `Subscribable`. See CONTEXT.md → Probe.
+
+### Routing / page — `@readme page` / `url`
+- `abide/shared/page` — reactive proxy: `route`, `params`, `url` (browser-space), `navigating`. Isomorphic; re-runs reactive readers on navigation.
+- `abide/shared/url(path, query?)` — type-safe URL builder; augmented by generated `RpcRoutes`/`PageRoutes`/`PublicAssets` for autocomplete. Applies mount base.
+
+### Templating values — `@readme plumbing`
+- `abide/shared/html` — `html\`...\`` tagged template → `RawHtml` (trusted markup); `rawHtmlString(v)`.
+- `abide/shared/snippet(payload)` → `Snippet` — a reusable template builder (the `<template name=…>` form).
+- `abide/shared/createSubscriber(start)` — the subscription primitive behind sockets/streams/probes.
+
+---
+
+## UI surface — `abide/ui/*` (client-only)
+
+### Reactive primitives — `@readme plumbing` (in scope inside `.abide`, no import)
+- `abide/ui/state(initial)` → writable `State<T>` (`.value` getter/setter).
+- `abide/ui/derived(compute)` → lazy read-only computed (`.value`); re-derived on resume, never serialized.
+- `abide/ui/effect(fn)` → run now, re-run on dependency change; `fn` may return teardown / be async; returns dispose.
+- `abide/ui/doc(initial?)` → reactive document: immutable tree addressed by path, every change a patch (the substrate under all reactivity / resumability / sync).
+
+### Streams
+- `abide/ui/tail(subscribable)` → latest frame (`T | undefined`); `tail(x, { last: n })` → window `T[]`. Reactive latest-wins read of a socket/stream. `tail.status` / `tail.error` expose richer stream state. See CONTEXT.md → Tail.
+
+### Navigation / lifecycle — `@readme plumbing`
+- `abide/ui/navigate(path, replace?)` — client navigation.
+- `abide/ui/router(...)`, `abide/ui/startClient(...)`, `abide/ui/renderToStream(render)` — bootstrap/render runtime (compiler/launcher uses these).
+
+### DOM + render runtime — `@readme plumbing` (compiler-emitted; you don't hand-write these)
+`abide/ui/dom/{mount,mountChild,hydrate,text,openChild,openRoot,appendText,appendSnippet,appendStatic,cloneStatic,attr,on,attach,each,eachAsync,when,awaitBlock,tryBlock,switchBlock,applyResolved}` and `abide/ui/runtime/{nextBlockId,enterRenderPass,exitRenderPass}`. These are what `analyzeComponent → generateBuild/generateSSR` lower a `.abide` file into. Read them only to understand compiler output.
+- `abide/ui/remoteProxy`, `abide/ui/socketProxy` — the browser-side implementations the bundler swaps in for `GET(...)` / `socket(...)`.
+
+### `.abide` component format (see `src/lib/ui/README.md`)
+Valid HTML with `<script>` + native `<template>` control flow + scoped `<style>`.
+- **Bindings:** `{expr}` text, `name={expr}` attr, `onclick={fn}`, `bind:value={…}` / `bind:checked` / `bind:group`, `attach={fn}` (node-lifetime attachment — the dual of `on`; the `use:`-action / `{@attach}` equivalent, lowered to `ui/dom/attach`).
+- **Control flow (native `<template>`):** `if`/`else`, `each={list} as="x" key="x.id"`, `await={p}`/`then`/`catch`, `switch`/`case`/`default`.
+- **Components:** capitalised tags (`<Layout title=…>`); children fill `<slot/>`; props are reactive (passed as thunks). `prop('name')` reads a typed page param.
+- **Snippets / named slots:** `<template name="x" args={…}>` declares a reusable named builder (the `snippet()` form), rendered like a function — covers named slots / `{@render}`.
+- **Reactivity:** write plain assignment (`count += 1`, `items.push(x)`); the compiler lowers it to patches. Deep-field edits wake only that field.
+- **SSR:** byte-identical HTML string; `renderToStream` ships the shell then streams `<template await>` fragments out of order; `hydrate` adopts static structure in place (control-flow blocks + child components fall back to `mount`/re-render — known gap).
+
+---
+
+## Build / tooling — `@readme plumbing`
+- `abide/ui-plugin` — Bun loader plugin for `.abide` files.
+- `abide/resolver-plugin` — resolves the `$server`/`$ui`/virtual modules and swaps server↔client runtime per target.
+- `abide/preload` — Bun preload registering both plugins (use in `bunfig.toml` `[test]`).
+- `abide/build`, `abide/compile` — programmatic build / standalone-executable compile.
+- `abide/tsconfig` — base tsconfig for consumer apps.
+
+## Desktop bundle — `@readme bundle`
+- `abide/bundle/BundleWindow` — `src/bundle/window.ts` default-export shape (`title`, `width`, `height`, `menu`, `config` schema for the first-run setup form).
+- `abide/bundle/BundleMenu`, `abide/bundle/BundleMenuItem` — custom menu types.
+- `abide/bundle/onMenu(handler)` / `onMenu(name, handler)` — subscribe to native menu clicks (returns unsubscribe; drop into an `effect`). Inert outside the bundle.
+- `abide/bundle/bundled()` — true inside the desktop webview (isomorphic detection).
+
+## MCP — `@readme plumbing`
+- `abide/mcp/createMcpServer(opts)` — framework-internal; the `abide:mcp` virtual constructs it. Tools derive from verbs/sockets flagged `clients.mcp: true`; auth inherits from the inbound request; optional `authorize` hook. Served at `/__abide/mcp`.
+
+## Testing — `@readme testing`
+- `abide/test/createTestApp()` → `TestApp` with typed `RpcClient` / `SocketClient` — in-process dispatch, no network.
+- `abide/test/createScriptedSurface(...)` — records tool dispatches for engine tests.
+- `abide/test/assertAgentFrameConformance(...)` — the frame contract every engine must satisfy (exactly one `done`, last; every `tool_use` answered by a same-id/name `tool_result`).
+
+---
+
+## Generated machine surfaces (runtime, from the user's app)
+- `/openapi.json` — full OpenAPI for every exposed verb.
+- `/__abide/mcp` — MCP endpoint (tools/sockets/prompts).
+- `/__abide/health` — health payload. `/__abide/identity` — app identity.
+- `/__abide/sockets` — ws multiplex (per-socket HTTP face at `/__abide/sockets/<name>`).
+- `/__abide/cli` — CLI dispatch endpoint. `/__abide/hot` — dev hot-reload. `/__abide/inspector` — inspector stream (gated by `ABIDE_ENABLE_INSPECTOR=true`).
+
+## Environment variables (consumer-facing)
+
+| Var | Effect |
+|---|---|
+| `PORT` | TCP port the server binds |
+| `APP_URL` | public URL; its pathname becomes the mount base (e.g. `…/v2` → `/v2`) |
+| `ABIDE_APP_URL` / `ABIDE_APP_TOKEN` | remote server URL + bearer token for the CLI client / bundle |
+| `ABIDE_DATA_DIR` | override the per-user data dir |
+| `ABIDE_CLIENT_TIMEOUT` | client-side RPC timeout (ms); distinct from per-verb `timeout` |
+| `ABIDE_IDLE_TIMEOUT` | Bun per-connection idle timeout (s) |
+| `ABIDE_MAX_REQUEST_BODY_SIZE` | server-wide request body ceiling |
+| `ABIDE_REACHABLE_TTL` / `ABIDE_REACHABLE_TIMEOUT` | `reachable()` poll cadence / per-HEAD bound (ms) |
+| `ABIDE_LOG_FORMAT` | `json` for one JSON object per log line (default: tsv) |
+| `ABIDE_ENABLE_INSPECTOR` | `true` to enable the inspector endpoint |
+| `ABIDE_INSPECT` | enable Bun inspector on the build |
+| `DEBUG` | enable diagnostic log channels (e.g. `abide:cache`, `abide:build`); browser uses the `abide-debug` localStorage key |
+
+---
+
+*Maintenance (abide repo only): this file mirrors `package.json` `exports`. After
+adding/renaming an export, run `bun run scripts/readmeSurfaces.ts` from
+`packages/abide/` (it lists every export by `@readme` slug and fails on any untagged
+one) and reflect the change here.*

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # abide
 
+## 0.30.0
+
+### Minor Changes
+
+- [`311f3e7`](https://github.com/briancray/abide/commit/311f3e76732eb2b98d2739f2f7eff0fbbb667645) - cross-fade navigations via the View Transition API ([`d3ea6c0`](https://github.com/briancray/abide/commit/d3ea6c001c47748dd2be3ae47dfc3624ae7c65ee))
+
+### Patch Changes
+
+- [`311f3e7`](https://github.com/briancray/abide/commit/311f3e76732eb2b98d2739f2f7eff0fbbb667645) - surface attach= binding and named-template snippets in .abide grammar ([`51a37ee`](https://github.com/briancray/abide/commit/51a37ee0b0cef708d0571de272ace3584d45a8c0))
+
+- [`311f3e7`](https://github.com/briancray/abide/commit/311f3e76732eb2b98d2739f2f7eff0fbbb667645) - hoist component-local types above \_\_Props so prop annotations resolve ([`8d674c5`](https://github.com/briancray/abide/commit/8d674c543be53ae5775124f392ee44fd8731204f))
+
+## 0.29.0
+
+### Minor Changes
+
+- [`2d2c141`](https://github.com/briancray/abide/commit/2d2c141a59d3643f997ef4bb16773d29e4149c95) - add 'abide init-agent' command ([`b5e9158`](https://github.com/briancray/abide/commit/b5e915862a74febffb8df28c68f444a73bd371da))
+
+### Patch Changes
+
+- [`2d2c141`](https://github.com/briancray/abide/commit/2d2c141a59d3643f997ef4bb16773d29e4149c95) - add AGENTS.md complete public-surface map for agents ([`b0539ec`](https://github.com/briancray/abide/commit/b0539ec69c880106dc1b0cb8573203e7113964ed))
+
 ## 0.28.0
 
 ### Minor Changes

package/bin/abide.ts

@@ -5,6 +5,7 @@ import { buildCli } from '../src/buildCli.ts'
 import { bundleApp } from '../src/bundleApp.ts'
 import { checkAbide } from '../src/checkAbide.ts'
 import { compile } from '../src/compile.ts'
+import { initAgent } from '../src/initAgent.ts'
 import { normalizeTarget } from '../src/lib/shared/normalizeTarget.ts'
 import { scaffold } from '../src/scaffold.ts'
 
@@ -156,6 +157,13 @@ async function scaffoldCmd(): Promise<void> {
     await scaffold({ cwd, name, install, dev })
 }
 
+// Writes/refreshes the abide agent-guide pointer in the project's root CLAUDE.md so
+// Claude (which never reads node_modules) is told where abide's surface map lives.
+// For projects that added abide as a dependency without scaffolding.
+async function initAgentCmd(): Promise<void> {
+    await initAgent({ cwd })
+}
+
 // Prints the CLI synopsis to stderr and exits non-zero. Marked `never` because the process is gone.
 function usage(): never {
     console.error(
@@ -182,7 +190,9 @@ function usage(): never {
             '  abide bundle                         build a movable, self-contained app\n' +
             '                                       bundle for this platform (unsigned). Boots\n' +
             '                                       into a connect screen — start the embedded\n' +
-            '                                       server or connect to a remote one',
+            '                                       server or connect to a remote one\n' +
+            "  abide init-agent                     write/refresh a CLAUDE.md pointer to abide's\n" +
+            '                                       surface map (for non-scaffolded projects)',
     )
     process.exit(1)
 }
@@ -207,6 +217,8 @@ if (command === 'scaffold') {
     await checkCmd()
 } else if (command === 'lsp') {
     await lspCmd()
+} else if (command === 'init-agent') {
+    await initAgentCmd()
 } else {
     usage()
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@abide/abide",
-    "version": "0.28.0",
+    "version": "0.30.0",
     "type": "module",
     "sideEffects": false,
     "description": "Isomorphic multimodal HTTP framework built for humans and machines in a single Bun runtime",
@@ -130,6 +130,7 @@
         "bin",
         "template",
         "tsconfig.app.json",
+        "AGENTS.md",
         "CHANGELOG.md"
     ],
     "dependencies": {

package/src/initAgent.ts

@@ -0,0 +1,50 @@
+/* Marker pair fencing the abide block, so a re-run replaces it in place rather
+   than duplicating, and the rest of an existing CLAUDE.md stays untouched. */
+const GUIDE_START = '<!-- abide:agent-guide -->'
+const GUIDE_END = '<!-- /abide:agent-guide -->'
+
+/* The pointer injected into the consumer's root CLAUDE.md. Claude Code auto-loads
+   root CLAUDE.md but never reads node_modules, so this is the only reliable hook
+   telling it where abide's full surface map lives. */
+const GUIDE_BLOCK = `${GUIDE_START}
+## Working with abide
+
+This project uses **abide**. Before using any abide API, read the complete surface
+map: \`node_modules/@abide/abide/AGENTS.md\` — every export (import path + signature),
+the file-based conventions, the CLI, env vars, and the \`.abide\` component grammar.
+Open the source under \`node_modules/@abide/abide/src/lib/\` for depth.
+${GUIDE_END}`
+
+/* Folds the guide block into existing CLAUDE.md content: replaces a fenced block
+   when both markers are present, otherwise appends it; titles a fresh file when
+   there is no content. Pure — the side effect (write) stays in initAgent. */
+function mergeGuide(existing: string | undefined): string {
+    if (existing === undefined) {
+        return `# Project guide for Claude\n\n${GUIDE_BLOCK}\n`
+    }
+    const start = existing.indexOf(GUIDE_START)
+    const end = existing.indexOf(GUIDE_END)
+    if (start !== -1 && end > start) {
+        return existing.slice(0, start) + GUIDE_BLOCK + existing.slice(end + GUIDE_END.length)
+    }
+    return `${existing.replace(/\s*$/, '')}\n\n${GUIDE_BLOCK}\n`
+}
+
+/*
+Writes (or refreshes) the abide agent-guide block in the project's root CLAUDE.md
+so Claude is pointed at node_modules/@abide/abide/AGENTS.md. Idempotent: the marker
+pair fences the block, so re-running updates it in place instead of duplicating, and
+any surrounding CLAUDE.md content is preserved. For projects that added abide as a
+dependency without scaffolding (the scaffold ships this pointer already).
+*/
+export async function initAgent({ cwd }: { cwd: string }): Promise<void> {
+    const path = `${cwd}/CLAUDE.md`
+    const file = Bun.file(path)
+    const existed = await file.exists()
+    await Bun.write(path, mergeGuide(existed ? await file.text() : undefined))
+    console.log(
+        existed
+            ? `[abide] refreshed the abide agent-guide in ${path}`
+            : `[abide] wrote ${path} pointing Claude at node_modules/@abide/abide/AGENTS.md`,
+    )
+}

package/src/lib/ui/compile/compileShadow.ts

@@ -46,11 +46,18 @@ export function compileShadow(source: string): CompiledShadow {
     const scriptStart = leadingScript ? source.indexOf('>', leadingScript.index) + 1 : 0
     const templateStart = leadingScript ? (leadingScript.index ?? 0) + leadingScript[0].length : 0
 
-    const { imports, scope, props } = analyzeScript(scriptBody, scriptStart)
+    const { imports, types, scope, props } = analyzeScript(scriptBody, scriptStart)
     builder.raw(SHADOW_PREAMBLE)
     for (const line of imports) {
         builder.flush(line)
     }
+    /* Component-local `type`/`interface` declarations are hoisted to module scope —
+       above `__Props` so prop annotations referencing them resolve, and still visible
+       inside the function body where the rest of the scope and template expressions use
+       them. (Emitting them as in-function scope lines would hide them from `__Props`.) */
+    for (const line of types) {
+        builder.flush(line)
+    }
     builder.raw(`interface __Props {\n${props.join('\n')}\n}\n`)
     /* async so `await` blocks are legal; never executed, so the return is void. */
     builder.raw('export default async function (props: __Props): Promise<void> {\n')
@@ -117,17 +124,24 @@ function createBuilder(): Builder {
     return builder
 }
 
-type ScriptAnalysis = { imports: ScopeLine[]; scope: ScopeLine[]; props: string[] }
+type ScriptAnalysis = {
+    imports: ScopeLine[]
+    types: ScopeLine[]
+    scope: ScopeLine[]
+    props: string[]
+}
 
 /* Walks the leading `<script>` and produces the shadow's module imports, the
-   value-typed scope lines, and the Props interface fields. `scriptStart` is the
-   body's absolute offset in the source, so verbatim spans map back exactly. */
+   module-scope type declarations, the value-typed scope lines, and the Props
+   interface fields. `scriptStart` is the body's absolute offset in the source, so
+   verbatim spans map back exactly. */
 function analyzeScript(scriptBody: string, scriptStart: number): ScriptAnalysis {
     const imports: ScopeLine[] = []
+    const types: ScopeLine[] = []
     const scope: ScopeLine[] = []
     const props: string[] = []
     if (scriptBody.trim() === '') {
-        return { imports, scope, props }
+        return { imports, types, scope, props }
     }
     const file = ts.createSourceFile('script.ts', scriptBody, ts.ScriptTarget.Latest, true)
     /* A verbatim span: original text + the segment mapping it back, relative to the
@@ -145,6 +159,11 @@ function analyzeScript(scriptBody: string, scriptStart: number): ScriptAnalysis
             imports.push({ text: verbatim(statement), segments: [span(statement, 0)] })
             continue
         }
+        if (ts.isTypeAliasDeclaration(statement) || ts.isInterfaceDeclaration(statement)) {
+            /* Hoist to module scope (verbatim, mapped) so prop annotations resolve them. */
+            types.push({ text: verbatim(statement), segments: [span(statement, 0)] })
+            continue
+        }
         const reactive = reactiveDeclarations(statement)
         if (reactive === undefined) {
             /* Plain statement (function, const, expression) — emit verbatim, mapped. */
@@ -155,7 +174,7 @@ function analyzeScript(scriptBody: string, scriptStart: number): ScriptAnalysis
             scope.push(scopeLineFor(declaration, props, verbatim, span))
         }
     }
-    return { imports, scope, props }
+    return { imports, types, scope, props }
 }
 
 /* The `state`/`derived`/`prop` declarations in a variable statement, or undefined

package/src/lib/ui/router.ts

@@ -264,12 +264,29 @@ export function router(
                 const hydrating =
                     first && pageView?.hydratable === true && pageView.hydrate !== undefined
                 first = false
-                const base = disposeFrom(divergence)
-                /* A fresh mount clears the torn-down DOM; hydration adopts it in place. */
-                if (!hydrating) {
-                    base.textContent = ''
+                /* The DOM mutation a navigation makes: tear the divergent chain down,
+                   clear its DOM (a fresh mount; hydration adopts in place), rebuild. */
+                const swap = (): void => {
+                    const base = disposeFrom(divergence)
+                    if (!hydrating) {
+                        base.textContent = ''
+                    }
+                    buildFrom(base, divergence, chainKeys, layoutViews, pageView, params, hydrating)
+                }
+                /* Wrap the swap in a View Transition where the browser supports it, so
+                   the page change cross-fades (and shared `view-transition-name` elements
+                   morph) — the synchronous swap is exactly the mutation the API snapshots
+                   around. Skipped while hydrating: the first paint adopts SSR DOM in place,
+                   not animate. CSS owns opting out (e.g. prefers-reduced-motion). */
+                if (
+                    !hydrating &&
+                    typeof document !== 'undefined' &&
+                    'startViewTransition' in document
+                ) {
+                    document.startViewTransition(swap)
+                } else {
+                    swap()
                 }
-                buildFrom(base, divergence, chainKeys, layoutViews, pageView, params, hydrating)
             })
         })
     })

package/template/CLAUDE.md

@@ -0,0 +1,22 @@
+# Project guide for Claude
+
+This app is built with **abide** — a type-safe isomorphic framework on Bun.
+
+**Before working with any abide API, read the complete surface map:**
+`node_modules/@abide/abide/AGENTS.md` — every export (with import path + signature),
+the file-based conventions, the CLI, env vars, and the `.abide` component grammar.
+Open the source under `node_modules/@abide/abide/src/lib/` for depth; the README is
+at `node_modules/@abide/abide/README.md`.
+
+> Tip: to keep that map permanently in context instead of reading it on demand,
+> replace the line above with an import: `@node_modules/@abide/abide/AGENTS.md`
+
+## Conventions (see AGENTS.md for the full list)
+
+- One export per file, named after the file. No barrels — import each name by its
+  own path (`@abide/abide/server/GET`, `@abide/abide/shared/cache`, …).
+- RPC verbs live in `src/server/rpc/<name>.ts`; sockets in `src/server/sockets/`;
+  pages are `**/page.abide`, layouts `**/layout.abide`.
+- Generated types land in `src/.abide/` — do not hand-edit them; run `abide dev`/
+  `abide check` to regenerate.
+- Prefer Bun and web-standard APIs over Node APIs.