@abide/abide 0.41.0 → 0.41.1

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # abide
 
+## 0.41.1
+
+### Patch Changes
+
+- [`74f5312`](https://github.com/briancray/abide/commit/74f531260e17f48162397142fb19b3df9e081b2c) - shared replaceRange region-update seam ([`184cf41`](https://github.com/briancray/abide/commit/184cf41157ef0a5340a4a916d6cfc4f4e09b6c71))
+
+- [`74f5312`](https://github.com/briancray/abide/commit/74f531260e17f48162397142fb19b3df9e081b2c) - single-source the marker-depth and isElement helpers ([`188c6ff`](https://github.com/briancray/abide/commit/188c6ff29fcaff2c9c206b971a2f04daf9a18cb3))
+
+- [`74f5312`](https://github.com/briancray/abide/commit/74f531260e17f48162397142fb19b3df9e081b2c) - guard against double-dispose on reentrant branch swap ([`40600c7`](https://github.com/briancray/abide/commit/40600c7921c9fee9b6be947472c770af795f60c6))
+
+- [`74f5312`](https://github.com/briancray/abide/commit/74f531260e17f48162397142fb19b3df9e081b2c) - await block on marker ranges, not a node array ([`5d12e83`](https://github.com/briancray/abide/commit/5d12e83b7313a04a925df3464ef5c7669bcbc1e6))
+
+- [`74f5312`](https://github.com/briancray/abide/commit/74f531260e17f48162397142fb19b3df9e081b2c) - refresh AGENTS surface map, README, and kitchen-sink example ([`6cd7a3f`](https://github.com/briancray/abide/commit/6cd7a3f5686a69f4dd5faf87026d7f1ab0362bdb))
+
+- [`74f5312`](https://github.com/briancray/abide/commit/74f531260e17f48162397142fb19b3df9e081b2c) - single client warm-seed intake (seedResolved) ([`8c3c19e`](https://github.com/briancray/abide/commit/8c3c19ed0a4d4244cb2634c025ef9ff88b7c9670))
+
+- [`74f5312`](https://github.com/briancray/abide/commit/74f531260e17f48162397142fb19b3df9e081b2c) - centralize comment-marker sentinels and detached-range builder ([`99d4499`](https://github.com/briancray/abide/commit/99d44991c499b96fc016c3d204cb4dafa340cbe1))
+
+- [`74f5312`](https://github.com/briancray/abide/commit/74f531260e17f48162397142fb19b3df9e081b2c) - unify skeleton positional model on shared walks ([`cbb9daa`](https://github.com/briancray/abide/commit/cbb9daaa6f31532331df44136dd029f3e32cdfd7))
+
+- [`f3e0a13`](https://github.com/briancray/abide/commit/f3e0a132f9f9fbb020a8c783a0b54d3b37457e39) - Coalesce reactive writes inside event handlers
+
+    Event handlers now batch their writes: a handler that sets several signals re-runs
+    each dependent effect/computed/DOM-binding once on the handler's exit instead of once
+    per write (the previous default flushed eagerly per write). The change stays fully
+    synchronous — the flush runs at handler-end before it returns — so the causal stack
+    (`dispatch → handler → effects`) is intact and server/client scheduling stays identical.
+
+    Factored the batch idiom `createDoc`/`clientPage` inlined into a shared, nesting-safe
+    `batch()` (flushes only on the depth-0 exit) and migrated both onto it, so a handler
+    that triggers a doc patch now coalesces end-to-end rather than flushing mid-handler.
+
+    A handler writing N fields cuts dependent re-runs N× (bench: an 8-field form handler
+    drops aggregate re-runs 8× and runs ~4.8× faster). Single-write handlers and navigation
+    (already batched) are unchanged. New contract, pinned by tests: a handler that writes
+    then synchronously reads the bound DOM sees the pre-write value until it returns; signal
+    reads stay current.
+
+- [`f26cba2`](https://github.com/briancray/abide/commit/f26cba22b92683f7316cc7212c5fe10500bdad13) - `abide check`: declare the `each` `index` binding in the type-check shadow
+
+    `index="i"` (0.41.0) was bound in the build and SSR passes but not in the shadow the
+    type-checker reads, so `{i}` in a row body false-positived "Cannot find name 'i'". The
+    shadow now declares the index as a `number` inside the loop body, matching the runtime.
+
 ## 0.41.0
 
 ### Minor Changes

package/README.md

@@ -1,24 +1,24 @@
 # abide
 
-**One typed declaration fans out to HTTP, a CLI, an MCP tool, and an OpenAPI
-spec — and the bundler swaps the runtime per side.**
+**One typed declaration fans out to HTTP, a CLI, an MCP tool, and an
+OpenAPI spec — the bundler swaps the runtime per side.**
 
-abide is an isomorphic framework on Bun and web standards: you declare a verb,
-a socket, or a component once, and the same callable runs server-side, in the
-browser, from the terminal, and from an agent — the bundler decides which
-runtime each side gets. Built for humans *and* machines.
+abide is an isomorphic framework on Bun where you write a function once and
+it serves every consumer: a browser fetch, an in-process SSR call, a CLI
+subcommand, an MCP tool, an OpenAPI operation. The same callable keeps its
+name and behaviour on both sides — the bundler decides whether it runs the
+real handler or a network proxy. Built for humans _and_ machines.
 
-- One direct dependency — the TypeScript compiler, used by `abide check`.
-  Tailwind is an optional peer. Everything runs on a single Bun runtime
-  (≥ 1.3.0); no second toolchain.
+- One direct dependency (`typescript`); `tailwindcss` + `bun-plugin-tailwind`
+  are optional peers. Single runtime: Bun ≥ 1.3.0.
 
 ## Quick start
 
 ```sh
-bunx abide scaffold my-app   # copies the template, installs, starts dev
+bunx abide scaffold my-app   # scaffolds, installs deps, and starts dev
 ```
 
-Or clone the kitchen-sink and run it:
+Or read the full feature tour in the kitchen-sink example:
 
 ```sh
 git clone https://github.com/briancray/abide
@@ -29,134 +29,143 @@ bun run dev
 
 ## RPCs
 
-An RPC is one export per file under `src/server/rpc/`. **The file path is the
-URL.** The schema validates arguments and projects the MCP tool, the CLI flags,
-and the OpenAPI operation. The contract is Standard Schema — zod, valibot, or
-arktype, unadapted.
+An RPC is one export per file under `src/server/rpc/`. The file path is the
+URL; the export name is the verb. A Standard Schema (zod / valibot / arktype,
+unadapted) validates the args and projects the same shape into the MCP tool,
+the CLI flags, and the OpenAPI operation.
 
 ```ts
-// src/server/rpc/getMessages.ts — file path is the route: GET /getMessages
+// src/server/rpc/getMessages.ts
 import { GET } from '@abide/abide/server/GET'
 import { json } from '@abide/abide/server/json'
 import { z } from 'zod'
+import { recent } from '../../chatState.ts'
 
-const inputSchema = z.object({ room: z.string() })
+const inputSchema = z.object({ room: z.string(), limit: z.coerce.number().default(20) })
 
-export const getMessages = GET(({ room }) => json(board(room)), { inputSchema })
+export const getMessages = GET(({ room, limit }) => json(recent(room).slice(-limit)), {
+    inputSchema,
+})
 ```
 
-One declaration, five surfaces:
+One declaration, every surface:
 
 ```text
               getMessages = GET(fn, { inputSchema })
                               │
-   ┌───────────┬─────────────┼────────────┬──────────────┐
- SSR call   browser fetch   MCP tool    CLI command    OpenAPI op
-cache(fn)() typed proxy()  (read-only)  abide ... cli  /openapi.json
+      ┌─────────────┬─────────┼──────────┬──────────────┐
+      ▼             ▼         ▼          ▼              ▼
+  SSR call      browser    MCP tool   CLI sub-      OpenAPI
+  cache(fn)()   fetch       (read)    command       operation
+                proxy
 ```
 
-A schema unlocks the CLI everywhere and MCP for read-only verbs; a mutating
-verb never auto-exposes to MCP — it needs explicit `clients: { mcp: true }`.
-Consume the verb four ways: `cache(getMessages)({ room })` resolves in-process
-during SSR, the same call hits a swapped `fetch` in the browser,
-`getMessages.raw(args)` returns the undecoded `Response`, and
-`getMessages.stream(args)` is an iterable view of the body.
+A schema unlocks the CLI for every verb and MCP for read-only verbs (`GET` /
+`HEAD`); a mutating verb never auto-exposes to MCP — it needs an explicit
+`clients: { mcp: true }`. Consume the verb four ways: `cache(getMessages)(args)`
+in-process (warm SSR hydration), the swapped `fetch` proxy in the browser,
+`getMessages.raw(args)` for the untouched `Response`, and
+`getMessages.stream(args)` to iterate a `jsonl`/`sse` body.
 
-> Query args travel as strings — validate with `z.coerce.*`. The per-verb
-> `timeout` (504 on every surface) is distinct from `ABIDE_CLIENT_TIMEOUT`.
+> Query args arrive as strings — wrap numeric/boolean fields in `z.coerce.*`.
+> The per-verb `timeout` (504 on every surface) is distinct from the
+> client-side `ABIDE_CLIENT_TIMEOUT`.
 
 ## Sockets
 
 A socket is one broadcast topic per file under `src/server/sockets/`. A
-`Socket<T>` is an isomorphic `AsyncIterable<T>`, and every socket multiplexes
-onto one websocket at `/__abide/sockets`.
+`Socket<T>` is an isomorphic `AsyncIterable<T>`; every socket multiplexes onto
+one WebSocket at `/__abide/sockets`.
 
 ```ts
-// src/server/sockets/messages.ts — topic name = file name: `messages`
+// src/server/sockets/chat.ts
 import { socket } from '@abide/abide/server/socket'
 import { z } from 'zod'
 
-const schema = z.object({ id: z.string(), room: z.string(), from: z.string(), text: z.string() })
+const schema = z.object({ id: z.string(), from: z.string(), text: z.string(), at: z.number() })
 
-// retain the last 50 frames; evict any older than an hour
-export const messages = socket({ schema, tail: 50, ttl: 3_600_000 })
-export type Message = z.infer<typeof schema>
+// retain the last 100 frames; evict any older than an hour
+export const chat = socket({ schema, tail: 100, ttl: 3_600_000 })
+export type ChatMessage = z.infer<typeof schema>
 ```
 
-The socket also has an HTTP face at `/__abide/sockets/messages`, for clients
-that can't speak the ws multiplex: `GET` returns the retained tail, `POST`
-publishes — gated by `clientPublish` (off by default, so the POST 403s).
+It also has an HTTP face for clients that can't speak the multiplex (the CLI
+and MCP): `GET /__abide/sockets/chat` returns the retained tail, and
+`POST /__abide/sockets/chat` publishes — gated by `clientPublish` (default off,
+so browsers publish through a validating verb instead).
 
-## Components
+## Components — the full template
 
-A `.abide` component is the payoff: it imports the verb and the socket above
-and ties them together with the native `<template>` grammar. Reactive state is
-reached only through `scope()` — `scope().state()` is writable,
-`scope().computed()` is read-only. `props()` and `effect()` are in-scope, no
-import.
+A `.abide` component pulls the verb and the socket above into one page and
+exercises the template grammar. `scope`, `props`, `effect`, `html`, and
+`snippet` are ambient — no import needed.
 
+<!-- prettier-ignore -->
 ```html
 <script>
 import { cache } from '@abide/abide/shared/cache'
 import { tail } from '@abide/abide/ui/tail'
 import { getMessages } from '$server/rpc/getMessages.ts'
-import { postMessage } from '$server/rpc/postMessage.ts'
-import { messages } from '$server/sockets/messages.ts'
+import { publishChat } from '$server/rpc/publishChat.ts'
+import { chat } from '$server/sockets/chat.ts'
 import Avatar from '$ui/Avatar.abide'
 
-const { room = 'lobby' } = props<{ room?: string }>()
+const { room } = props()
 
-// SSR-warm history; live frames then stream over the ws
-const seed = cache(getMessages)({ room })
-const live = scope().computed(() => tail(messages, { last: 50 }))
+// warm on the server, live on the client
+const history = scope().computed(() => cache(getMessages)({ room }))
+const latest = scope().computed(() => tail(chat))
 
 let from = scope().state('alice')
 let text = scope().state('')
 let pinned = scope().state(false)
-let sort = scope().state('newest')
+let view = scope().state('all')
 
 async function send() {
-    await postMessage({ room, from, text })
+    await publishChat({ from, text })
     text = ''
 }
 </script>
 
-<template name="bubble" args={msg}>
-    <li class="flex gap-2"><Avatar name={msg.from} /> <b>{msg.from}</b> {msg.text}</li>
+<template name="line" args={message}>
+    <li><Avatar name={message.from} /> <b>{message.from}</b>: {message.text}</li>
 </template>
 
-<form onsubmit={send} class="flex gap-2">
-    <input bind:value={from} class="border px-2" />
-    <input bind:value={text} placeholder="message" class="flex-1 border px-2" />
+<form onsubmit={send}>
+    <input bind:value={from} placeholder="name" />
+    <input bind:value={text} placeholder="message" />
     <label><input type="checkbox" bind:checked={pinned} /> pin</label>
-    <label><input type="radio" bind:group={sort} value="newest" /> newest</label>
-    <button disabled={!text} class="border px-3">send</button>
+    <label><input type="radio" bind:group={view} value="all" /> all</label>
+    <label><input type="radio" bind:group={view} value="mine" /> mine</label>
+    <button disabled={!text}>send</button>
 </form>
 
-<template if={pinned}>
-    <p class="text-xs text-amber-700">room pinned</p>
-    <template else><p class="text-xs text-slate-400">not pinned</p></template>
+<template if={latest}>
+    <p>latest from {latest.from}</p>
+<template else>
+    <p>no messages yet</p>
 </template>
 
-<template switch={sort}>
-    <template case={'newest'}><p class="text-xs">newest first</p></template>
-    <template default><p class="text-xs">oldest first</p></template>
+<template switch={view}>
+<template case="mine"><p>showing your messages</p></template>
+<template default><p>showing every message</p></template>
 </template>
 
-<template await={seed}>
-    <p class="text-xs text-slate-500">loading…</p>
-    <template then="history">
-        <ul class="mt-3 space-y-1">
-            <template each={live ?? history} as="msg" key="msg.id">
-                {bubble(msg)}
-            </template>
-        </ul>
-    </template>
-    <template catch="err"><p class="text-rose-700">{err.message}</p></template>
+<template await={history}>
+    <p>loading…</p>
+<template then="data">
+    <ul>
+        <template each={data} as="message" key="message.id" index="i">
+            {i}. {line(message)}
+        </template>
+    </ul>
+<template catch="reason">
+    <p>failed: {reason.message}</p>
+</template>
 </template>
 
 <style>
-    li { font-size: 0.875rem; }
+form { display: flex; gap: 0.5rem; }
 </style>
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@abide/abide",
-    "version": "0.41.0",
+    "version": "0.41.1",
     "type": "module",
     "sideEffects": false,
     "description": "Isomorphic multimodal HTTP framework built for humans and machines in a single Bun runtime",

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

@@ -1,3 +1,5 @@
+import { SNIPPET_CLOSE, SNIPPET_OPEN } from '../runtime/RANGE_MARKER.ts'
+
 /*
 Source text for the `$esc` / `$attr` / `$spread` / `$text` / `$snip` helpers injected
 into every SSR render body. `$esc` escapes the five HTML-significant characters. `$attr`
@@ -30,6 +32,6 @@ export const SSR_ESCAPE =
     "const $SNIP = Symbol.for('abide.snippet');\n" +
     'const $snip = (s) => ({ [$SNIP]: s });\n' +
     'const $text = (v) => (v !== null && typeof v === "object" && $SNIP in v) ' +
-    "? ('<!--abide:snippet-->' + v[$SNIP] + '<!--/abide:snippet-->') " +
+    `? ('<!--${SNIPPET_OPEN}-->' + v[$SNIP] + '<!--${SNIPPET_CLOSE}-->') ` +
     ': (v !== null && typeof v === "object" && $RAW in v) ' +
     "? ('<!--abide:html-->' + v[$RAW] + '<!--/abide:html-->') : $esc(v);"

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

@@ -417,6 +417,11 @@ function emitNode(node: TemplateNode, builder: Builder): void {
             if (node.key !== undefined) {
                 builder.raw(`void (${node.key});\n`)
             }
+            /* `index="i"` binds the row's position — always a number (the row ordinal,
+               or an async stream's arrival count). Declare it so body references check. */
+            if (node.index !== undefined) {
+                builder.raw(`const ${node.index}: number = 0;\n`)
+            }
             emitNodes(node.children, builder)
             builder.raw('}\n')
             return

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

@@ -1,6 +1,7 @@
 import { assertExhaustive } from '../../shared/assertExhaustive.ts'
 import { HOLE_ATTRIBUTE } from '../runtime/HOLE_ATTRIBUTE.ts'
 import { OUTLET_TAG } from '../runtime/OUTLET_TAG.ts'
+import { ANCHOR } from '../runtime/RANGE_MARKER.ts'
 import { asOutlet } from './asOutlet.ts'
 import { bindListenEvent } from './bindListenEvent.ts'
 import { composeProps } from './composeProps.ts'
@@ -18,6 +19,12 @@ import { staticTextPart } from './staticTextPart.ts'
 import type { TemplateNode } from './types/TemplateNode.ts'
 import { VOID_TAGS } from './VOID_TAGS.ts'
 
+/* The skeleton positioning anchor a control-flow block / component / slot / outlet
+   stamps into its skeleton markup, sourced from the same `ANCHOR` wire-alphabet constant
+   the client's anchor scan (`skeleton`) matches — so the markup the build clones and the
+   markup the scan reads can never drift on a literal. */
+const ANCHOR_COMMENT = `<!--${ANCHOR}-->`
+
 /*
 Generates the build statements for a parsed template: element creation, static
 attributes, reactive `attr`/`text` bindings, `on` listeners, keyed `each`, and
@@ -213,7 +220,7 @@ export function generateBuild(
                     binds.push(
                         `appendTextAt(${skVar}.an[${holeIndex(anIndex, part)}], ${namedThunk('text', `return (${lowerExpression(part.code)})`)});\n`,
                     )
-                    return '<!--a-->'
+                    return ANCHOR_COMMENT
                 })
                 .join('')
         }
@@ -226,7 +233,7 @@ export function generateBuild(
                element — so its root lays out as a true direct child of `anchor.parentNode`. */
             const anchorVar = anchorVarAt(node, skVar, binds)
             binds.push(generateChild(node, `${anchorVar}.parentNode`, `anchorCursor(${anchorVar})`))
-            return '<!--a-->'
+            return ANCHOR_COMMENT
         }
         if (node.kind === 'script') {
             /* A nested `<script>` (scoped reactive block) emits no markup — its lowered body
@@ -251,7 +258,7 @@ export function generateBuild(
                No wrapper element — the filled child lays out as a direct child of the parent. */
             const anchorVar = anchorVarAt(node, skVar, binds)
             binds.push(`outlet(${anchorVar}.parentNode, anchorCursor(${anchorVar}));\n`)
-            return '<!--a-->'
+            return ANCHOR_COMMENT
         }
         if (node.tag === 'slot') {
             /* A `<slot>` outlet at its position: an `<!--a-->` anchor, the slot's content
@@ -261,7 +268,7 @@ export function generateBuild(
             binds.push(
                 `mountSlot(${anchorVar}.parentNode, (${hostVar}) => {\n${generateSlot(node, hostVar)}}, anchorCursor(${anchorVar}));\n`,
             )
-            return '<!--a-->'
+            return ANCHOR_COMMENT
         }
         const hasReactiveAttr = node.attrs.some((attr) => attr.kind !== 'static')
         const reactiveTextChild = node.children.find(

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

@@ -1,6 +1,11 @@
 import { assertExhaustive } from '../../shared/assertExhaustive.ts'
 import { OUTLET_CLOSE, OUTLET_OPEN } from '../runtime/OUTLET_MARKER.ts'
 import { OUTLET_TAG } from '../runtime/OUTLET_TAG.ts'
+import {
+    ANCHOR,
+    RANGE_CLOSE as RANGE_CLOSE_DATA,
+    RANGE_OPEN as RANGE_OPEN_DATA,
+} from '../runtime/RANGE_MARKER.ts'
 import { asOutlet } from './asOutlet.ts'
 import { composeProps } from './composeProps.ts'
 import { groupBindParts } from './groupBindParts.ts'
@@ -16,12 +21,16 @@ import { stripEffects } from './stripEffects.ts'
 import type { TemplateNode } from './types/TemplateNode.ts'
 import { VOID_TAGS } from './VOID_TAGS.ts'
 
-/* The range boundary comments a control-flow block emits around its content. They
-   serialize exactly as the client's `document.createComment('[' | ']')` markers, so
-   the client claims the same `[ … ]` boundary it builds — the comment-marked range
-   that lets a branch hold any content. */
-const RANGE_OPEN = '<!--[-->'
-const RANGE_CLOSE = '<!--]-->'
+/* The range boundary comments a control-flow block emits around its content. Sourced
+   from the SAME wire-alphabet constants the client's `document.createComment` markers
+   use (`RANGE_MARKER`), wrapped in comment syntax — so a server-emitted boundary and the
+   client `[ … ]` boundary it claims can never drift on a literal. */
+const RANGE_OPEN = `<!--${RANGE_OPEN_DATA}-->`
+const RANGE_CLOSE = `<!--${RANGE_CLOSE_DATA}-->`
+
+/* The skeleton positioning anchor a control-flow block / slot / outlet emits, sourced
+   from the same `ANCHOR` constant the client's anchor scan matches. */
+const ANCHOR_COMMENT = `<!--${ANCHOR}-->`
 
 /*
 Server code generator: turns the parsed template into statements that push HTML
@@ -172,7 +181,7 @@ export function generateSSR(
        Outside a skeleton (top-level / inside a branch) blocks mount on the host directly,
        so no anchor. */
     const anchorMark = (node: TemplateNode, target: string): string =>
-        inSkeleton.get(node) ? push(target, '<!--a-->') : ''
+        inSkeleton.get(node) ? push(target, ANCHOR_COMMENT) : ''
 
     function generate(node: TemplateNode, target: string): string {
         /* Every kind that mounts as a marker range is positioned by an `<!--a-->` anchor when
@@ -197,7 +206,7 @@ export function generateSSR(
                         ? `$text(await (${lowered}))`
                         : `$text(${lowered})`
                     return markText.get(node)
-                        ? `${target}.push('<!--a-->' + ${value});\n`
+                        ? `${target}.push('${ANCHOR_COMMENT}' + ${value});\n`
                         : `${target}.push(${value});\n`
                 })
                 .join('')