@abide/abide 0.40.0 → 0.40.1

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # abide
 
+## 0.40.1
+
+### Patch Changes
+
+- [`32d6cb9`](https://github.com/briancray/abide/commit/32d6cb97a9ce2ad63b3fd768c02379e708c6d599) - share a single TS printer across compile passes ([`0626e68`](https://github.com/briancray/abide/commit/0626e68500b6cc8e7e2c770184ec4aa0fd06106d))
+
+- [`32d6cb9`](https://github.com/briancray/abide/commit/32d6cb97a9ce2ad63b3fd768c02379e708c6d599) - bind-check generated modules and collect identifiers via AST ([`1e9d350`](https://github.com/briancray/abide/commit/1e9d3506873121ffd978039653f920edbed6c9ce))
+
+- [`32d6cb9`](https://github.com/briancray/abide/commit/32d6cb97a9ce2ad63b3fd768c02379e708c6d599) - value-memoised push-pull reactivity (CLEAN/CHECK/DIRTY) ([`2ae8f14`](https://github.com/briancray/abide/commit/2ae8f141da5873bea0eb31a9a59d81182ca5a12a))
+
+- [`32d6cb9`](https://github.com/briancray/abide/commit/32d6cb97a9ce2ad63b3fd768c02379e708c6d599) - syntax fuzz corpus for the identifier-rewrite passes ([`2e7d604`](https://github.com/briancray/abide/commit/2e7d6043aeeb9ca894bdb45f3f27893fbc5bf2f8))
+
+- [`32d6cb9`](https://github.com/briancray/abide/commit/32d6cb97a9ce2ad63b3fd768c02379e708c6d599) - build control-flow subtrees untracked ([`33c0d8e`](https://github.com/briancray/abide/commit/33c0d8e834e5145a84d872ff496df122bbb0da95))
+
+- [`32d6cb9`](https://github.com/briancray/abide/commit/32d6cb97a9ce2ad63b3fd768c02379e708c6d599) - lower the component script in a single parse ([`53098f8`](https://github.com/briancray/abide/commit/53098f8c2fe36e46e61b41d8a617aba6ac75e96f))
+
+- [`32d6cb9`](https://github.com/briancray/abide/commit/32d6cb97a9ce2ad63b3fd768c02379e708c6d599) - regenerate README and AGENTS surface map ([`6bb6a39`](https://github.com/briancray/abide/commit/6bb6a3906d5aba522a4fe33bffae0911adf0b0fe))
+
+- [`32d6cb9`](https://github.com/briancray/abide/commit/32d6cb97a9ce2ad63b3fd768c02379e708c6d599) - spread reactive page.params before postMessage in inspector bridge ([`7c99395`](https://github.com/briancray/abide/commit/7c993959e9dfc0c7f7038f694f95b59093a10dfc))
+
+- [`32d6cb9`](https://github.com/briancray/abide/commit/32d6cb97a9ce2ad63b3fd768c02379e708c6d599) - make signal-rewrite parent-independent ([`868717a`](https://github.com/briancray/abide/commit/868717a6f7ff824b24ef8a96e5e5f59add5ceed1))
+
+- [`32d6cb9`](https://github.com/briancray/abide/commit/32d6cb97a9ce2ad63b3fd768c02379e708c6d599) - pick runtime imports by tokenizing the output, not substring grep ([`a102986`](https://github.com/briancray/abide/commit/a102986bef90609297246ea001528a32e111be53))
+
+- [`32d6cb9`](https://github.com/briancray/abide/commit/32d6cb97a9ce2ad63b3fd768c02379e708c6d599) - re-apply saved scroll offset until async content grows the page ([`a813b47`](https://github.com/briancray/abide/commit/a813b47387289c0049e63997a72a6805e461b18c))
+
+- [`32d6cb9`](https://github.com/briancray/abide/commit/32d6cb97a9ce2ad63b3fd768c02379e708c6d599) - aliased import mangled when its name collides with a signal ([`abfe25d`](https://github.com/briancray/abide/commit/abfe25dcf7c00e61156b5d36fe82f290fc6c4cfb))
+
+- [`32d6cb9`](https://github.com/briancray/abide/commit/32d6cb97a9ce2ad63b3fd768c02379e708c6d599) - granular reactive page snapshot + in-place same-route navigation ([`b561eb5`](https://github.com/briancray/abide/commit/b561eb52439577d3a75a7872befee4b9f0e98267))
+
+- [`32d6cb9`](https://github.com/briancray/abide/commit/32d6cb97a9ce2ad63b3fd768c02379e708c6d599) - lower the component script in a literal single parse ([`b72b238`](https://github.com/briancray/abide/commit/b72b238377ff6545de549589d36b49ad4ecebb2d))
+
+- [`32d6cb9`](https://github.com/briancray/abide/commit/32d6cb97a9ce2ad63b3fd768c02379e708c6d599) - chain per-expression lowering over a single parse ([`d808317`](https://github.com/briancray/abide/commit/d808317d817ae8a414695b7bfb037b8aff7017c3))
+
+- [`32d6cb9`](https://github.com/briancray/abide/commit/32d6cb97a9ce2ad63b3fd768c02379e708c6d599) - classify signal-rewrite positions at visit time ([`d99577e`](https://github.com/briancray/abide/commit/d99577e2ac77d8742088608fba554ff5c2e799a4))
+
+- [`32d6cb9`](https://github.com/briancray/abide/commit/32d6cb97a9ce2ad63b3fd768c02379e708c6d599) - make template-node generators exhaustive ([`e0f246d`](https://github.com/briancray/abide/commit/e0f246dfbbf4ea4f2dc481fc543a6e9f0a6fa43b))
+
+- [`32d6cb9`](https://github.com/briancray/abide/commit/32d6cb97a9ce2ad63b3fd768c02379e708c6d599) - lower ++/-- on a doc path; guard the whole generated module ([`f49c122`](https://github.com/briancray/abide/commit/f49c122354fc4ef65f4c44db820d703078dd57f4))
+
+- [`32d6cb9`](https://github.com/briancray/abide/commit/32d6cb97a9ce2ad63b3fd768c02379e708c6d599) - fold SSR effect-stripping into the single-parse chain ([`fa4515d`](https://github.com/briancray/abide/commit/fa4515d07164765ea0ee609cf1847535a41f95ed))
+
 ## 0.40.0
 
 ### Minor Changes

package/README.md

@@ -1,159 +1,157 @@
 # abide
 
-**One typed RPC declaration fans out to an HTTP route, a typed browser proxy, a CLI subcommand, an MCP tool, and an OpenAPI operation — built for humans and machines.**
+**One typed declaration fans out to HTTP, a CLI, an MCP tool, and an OpenAPI
+spec — and the bundler swaps the runtime per side.**
 
-abide is an isomorphic framework on Bun: the same callable has the same name and behaviour on both sides, and the bundler swaps the runtime per side — a server handler in `src/server`, a `fetch` proxy in the browser. Server-render and hydrate the same `.abide` components, broadcast over multiplexed sockets, and expose every read to an agent — all in a single Bun runtime.
+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.
 
-- One dependency (`typescript`, for the type-checking shadow); `tailwindcss` + `bun-plugin-tailwind` are optional peers.
-- Runs on Bun `>= 1.3.0`. No bundler config, no server framework, no client router to wire up.
+- 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.
 
 ## Quick start
 
 ```sh
-bunx abide scaffold my-app   # scaffolds, installs deps, and (in a TTY) starts dev
+bunx abide scaffold my-app   # copies the template, installs, starts dev
 ```
 
-Or read the exhaustive demo:
+Or clone the kitchen-sink and run it:
 
 ```sh
 git clone https://github.com/briancray/abide
-cd abide && bun install
-cd examples/kitchen-sink && bun dev
+cd abide/examples/kitchen-sink
+bun install
+bun run dev
 ```
 
-The whole public surface — every export, CLI command, route, env var, and the `.abide` grammar — is mapped in [`AGENTS.md`](./AGENTS.md).
-
 ## RPCs
 
-An RPC is one export per file under `src/server/rpc/`. The file path is the URL (`getMessages.ts` → `/rpc/getMessages`), and a [Standard Schema](https://standardschema.dev) (zod / valibot / arktype, unadapted) validates the args and projects every other surface.
+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.
 
 ```ts
-// src/server/rpc/getMessages.ts
+// src/server/rpc/getMessages.ts — file path is the route: GET /getMessages
 import { GET } from '@abide/abide/server/GET'
 import { json } from '@abide/abide/server/json'
 import { z } from 'zod'
-import { history } from '../../store.ts'
 
 const inputSchema = z.object({ room: z.string() })
 
-export const getMessages = GET(({ room }) => json({ messages: history(room) }), { inputSchema })
+export const getMessages = GET(({ room }) => json(board(room)), { inputSchema })
 ```
 
-That one declaration fans out:
+One declaration, five surfaces:
 
 ```text
-                  getMessages   (one declaration)
-                        │
-   ┌──────────┬─────────┼─────────┬──────────────┐
-   ▼          ▼         ▼         ▼              ▼
- SSR call   browser   MCP tool   CLI sub-     OpenAPI
-cache(fn)()  fetch   (read-only) command      operation
+              getMessages = GET(fn, { inputSchema })
+                              │
+   ┌───────────┬─────────────┼────────────┬──────────────┐
+ SSR call   browser fetch   MCP tool    CLI command    OpenAPI op
+cache(fn)() typed proxy()  (read-only)  abide ... cli  /openapi.json
 ```
 
-The `inputSchema` unlocks the CLI and — because a `GET`/`HEAD` is read-only — an MCP tool. A mutating verb (`POST`/`PUT`/`PATCH`/`DELETE`) never auto-exposes to an agent; opt in with `clients: { mcp: true }`. Consume the verb four ways, all typed against the declaration: `cache(getMessages)({ room })` for an SSR-memoized in-process read, the bundler-swapped `getMessages({ room })` `fetch` proxy in the browser, `.raw(args)` for the untouched `Response`, and `.stream(args)` for a frame-by-frame `jsonl`/`sse` body.
+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.
 
-> Query args travel as strings — use `z.coerce.*` for numbers and booleans. The per-verb `timeout` option fires a `504` on every surface and is distinct from the client-wide `ABIDE_CLIENT_TIMEOUT`.
+> Query args travel as strings — validate with `z.coerce.*`. The per-verb
+> `timeout` (504 on every surface) is distinct from `ABIDE_CLIENT_TIMEOUT`.
 
 ## Sockets
 
-A socket is one broadcast topic per file under `src/server/sockets/`. A `Socket<T>` is an isomorphic `AsyncIterable<T>` — `for await` it on the server, or read it reactively with `tail()` in a component — and every socket multiplexes onto one WebSocket at `/__abide/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`.
 
 ```ts
-// src/server/sockets/messages.ts
+// src/server/sockets/messages.ts — topic name = file name: `messages`
 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(),
-    at: z.number(),
-})
+const schema = z.object({ id: z.string(), room: z.string(), from: z.string(), text: z.string() })
 
-// retain the last 100 frames; lazily evict any older than an hour
-export const messages = socket({ schema, tail: 100, ttl: 3_600_000 })
+// 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>
 ```
 
-The schema validates every publish and flips on the read surfaces (a `messages-tail` MCP tool / CLI command). For clients that can't speak the ws multiplex, each socket has an HTTP face at `/__abide/sockets/messages`: `GET` returns the retained tail, `POST` publishes — gated by `clientPublish` (default `false`, so browsers publish through a validating verb instead).
+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).
 
 ## Components
 
-A component is an `.abide` file: valid HTML with a `<script>`, native `<template>` control flow, `{expr}` bindings, and a component-scoped `<style>`. `scope()` is the sole reactive surface; `props`, `effect`, and `html` are in scope without import. This one imports the verb and socket above:
+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.
 
 ```html
 <script>
 import { cache } from '@abide/abide/shared/cache'
 import { tail } from '@abide/abide/ui/tail'
 import { getMessages } from '$server/rpc/getMessages.ts'
-import { sendMessage } from '$server/rpc/sendMessage.ts'
+import { postMessage } from '$server/rpc/postMessage.ts'
 import { messages } from '$server/sockets/messages.ts'
 import Avatar from '$ui/Avatar.abide'
 
-const { room } = props<{ room: string }>()
+const { room = 'lobby' } = props<{ room?: string }>()
+
+// SSR-warm history; live frames then stream over the ws
+const seed = cache(getMessages)({ room })
+const live = scope().computed(() => tail(messages, { last: 50 }))
 
-let from = scope().state('alice')               // a writable cell — read/assign as a plain var
-let draft = scope().state('')
+let from = scope().state('alice')
+let text = scope().state('')
 let pinned = scope().state(false)
-let filter = scope().state('all')
-const live = scope().computed(() => tail(messages))   // re-renders on every new frame
-
-async function send(event: SubmitEvent) {
-    event.preventDefault()
-    if (draft.trim() === '') return
-    await sendMessage({ room, from, text: draft })     // a mutating verb
-    draft = ''
+let sort = scope().state('newest')
+
+async function send() {
+    await postMessage({ room, from, text })
+    text = ''
 }
 </script>
 
-<!-- a named snippet: a reusable builder, rendered like a function -->
 <template name="bubble" args={msg}>
-    <li><Avatar name={msg.from} /> <b>{msg.from}</b>: {msg.text}</li>
+    <li class="flex gap-2"><Avatar name={msg.from} /> <b>{msg.from}</b> {msg.text}</li>
 </template>
 
-<h1>#{room}</h1>
-
-<form onsubmit={send}>
-    <input bind:value={from} />
-    <input bind:value={draft} placeholder="message" />
+<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" />
     <label><input type="checkbox" bind:checked={pinned} /> pin</label>
-    <label><input type="radio" bind:group={filter} value="all" /> all</label>
-    <label><input type="radio" bind:group={filter} value="mine" /> mine</label>
-    <button type="submit" disabled={draft.trim() === ''}>send</button>
+    <label><input type="radio" bind:group={sort} value="newest" /> newest</label>
+    <button disabled={!text} class="border px-3">send</button>
 </form>
 
-<template if={live}>
-    <p class="live">latest: {live.text}</p>
-    <template else>
-        <p>no messages yet</p>
-    </template>
-</template>
-
-<template switch={filter}>
-    <template case={'all'}><p>showing everyone</p></template>
-    <template case={'mine'}><p>showing {from}</p></template>
-    <template default><p>—</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>
 
-<template await={cache(getMessages)({ room })}>
-    <p>loading…</p>
+<template await={seed}>
+    <p class="text-xs text-slate-500">loading…</p>
     <template then="history">
-        <ul>
-            <template each={history.messages} as="msg" key="msg.id">
+        <ul class="mt-3 space-y-1">
+            <template each={live ?? history} as="msg" key="msg.id">
                 {bubble(msg)}
             </template>
         </ul>
     </template>
-    <template catch="error">
-        <p>failed: {error.message}</p>
-    </template>
+    <template catch="err"><p class="text-rose-700">{err.message}</p></template>
 </template>
 
 <style>
-    .live {
-        font-weight: 600;
-    }
+    li { font-size: 0.875rem; }
 </style>
 ```
 

package/package.json

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

package/src/lib/shared/assertExhaustive.ts

@@ -0,0 +1,14 @@
+/*
+Exhaustiveness guard for a discriminated-union dispatch. When every variant is
+handled, the fall-through value narrows to `never`, so passing it here type-checks;
+adding a new variant without a branch makes this a COMPILE error AND, if it slips
+past types, throws at runtime naming the variant — converting a silent mis-dispatch
+(a new template-node kind routed to the wrong branch) into a loud failure. The
+enumeration's completeness becomes the type checker's job instead of inspection's.
+*/
+export function assertExhaustive(value: never, context = 'variant'): never {
+    const kind = (value as { kind?: unknown })?.kind
+    throw new Error(
+        `[abide] non-exhaustive ${context}${kind === undefined ? '' : `: ${String(kind)}`}`,
+    )
+}

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

@@ -0,0 +1,7 @@
+import ts from 'typescript'
+
+/* The shared TypeScript printer every compile pass prints its transformed tree with.
+   A `ts.Printer` is stateless and reusable, so the passes share one instance rather
+   than each re-creating the same `{ newLine: LineFeed }` printer. LineFeed keeps the
+   emitted source `\n`-delimited regardless of the host platform. */
+export const TS_PRINTER = ts.createPrinter({ newLine: ts.NewLineKind.LineFeed })

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

@@ -1,5 +1,4 @@
-import { desugarSignals } from './desugarSignals.ts'
-import { lowerDocAccess } from './lowerDocAccess.ts'
+import { lowerScript } from './lowerScript.ts'
 import { parseTemplate } from './parseTemplate.ts'
 import { scopeCss } from './scopeCss.ts'
 import type { AnalyzedComponent } from './types/AnalyzedComponent.ts'
@@ -30,19 +29,18 @@ export function analyzeComponent(source: string, scopeSeed?: string): AnalyzedCo
     const scriptBody = (scriptMatch?.[1] ?? '').trim()
     const template = source.replace(/^\s*<script[^>]*>[\s\S]*?<\/script>/, '').trim()
 
-    const { code: desugared, stateNames, derivedNames, computedNames } = desugarSignals(scriptBody)
-    const lowered = desugared.trim() === '' ? '' : lowerDocAccess(desugared, 'model')
-    /* Hoist top-level import statements (e.g. child components) out of the script
-       so the module wrapper can place them at module scope — they can't live
-       inside the mount callback / render function. */
-    const imports: string[] = []
-    const script = lowered
-        .replace(/^[ \t]*import\s[^\n]*$/gm, (line) => {
-            imports.push(line.trim())
-            return ''
-        })
-        .replace(/\n{2,}/g, '\n')
-        .trim()
+    /* `lowerScript` parses the script ONCE and chains signal desugaring, reference
+       renaming, and doc-access lowering over that single tree, then hoists top-level
+       imports off the tree structurally — imports live at module scope, not inside the
+       mount/render function the body becomes. It returns the collected signal name sets. */
+    const {
+        body: script,
+        ssrBody: ssrScript,
+        imports,
+        stateNames,
+        derivedNames,
+        computedNames,
+    } = lowerScript(scriptBody)
     /* The parser keeps each `<style>` as an in-place node (one inside an expression
        is text, never a node). `annotateScopes` mutates the tree — assigning each
        style its scope attribute and stamping covered elements — and returns the
@@ -51,7 +49,8 @@ export function analyzeComponent(source: string, scopeSeed?: string): AnalyzedCo
     const styles = annotateScopes(nodes, [], scopeSeed, { count: 0 })
     return {
         script,
-        imports: imports.join('\n'),
+        ssrScript,
+        imports,
         stateNames,
         derivedNames,
         computedNames,

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

@@ -0,0 +1,66 @@
+import ts from 'typescript'
+import { UI_RUNTIME_IMPORTS } from './UI_RUNTIME_IMPORTS.ts'
+
+/*
+Independent backstop on the per-component dead-import filter (`compileModule`). The filter
+decides which runtime helpers to import by reading the generated output's identifiers; if it
+ever undercounts — as a raw token scan once did, mis-reading the tail of a module after a
+`${…}` template substitution — a helper gets CALLED but never imported, and the bundle throws
+`ReferenceError` the instant `build()` runs. The router escalates that into a reload loop, so
+the failure is both opaque and unrecoverable.
+
+This re-derives the same question a DIFFERENT way (so it can't share the filter's blind spot):
+walk the final module's AST, find every call whose callee is a bare runtime-helper identifier,
+and require that name to be imported or locally bound. A helper name inside a string / template /
+comment is not a `CallExpression` callee, so a docs component quoting framework code
+(`mount(...)` in a snippet) never false-positives. Compile-time only; never on the hot path.
+*/
+export function assertRuntimeHelpersBound(module: string, context: string): void {
+    const helperNames = new Set(UI_RUNTIME_IMPORTS.map((entry) => entry.name))
+    const source = ts.createSourceFile(
+        'module.ts',
+        module,
+        ts.ScriptTarget.Latest,
+        /* setParentNodes */ true,
+    )
+    /* Names a bare call can resolve to: every import binding plus every declared name.
+       Collected generously (any identifier in a binding position) — over-approximating the
+       bound set only risks missing a defect, never raising a false alarm on valid output. */
+    const bound = new Set<string>()
+    const calledHelpers: { name: string; position: number }[] = []
+    const visit = (node: ts.Node): void => {
+        if (
+            (ts.isVariableDeclaration(node) ||
+                ts.isFunctionDeclaration(node) ||
+                ts.isParameter(node) ||
+                ts.isBindingElement(node) ||
+                ts.isImportSpecifier(node) ||
+                ts.isImportClause(node) ||
+                ts.isNamespaceImport(node)) &&
+            node.name !== undefined &&
+            ts.isIdentifier(node.name)
+        ) {
+            bound.add(node.name.text)
+        }
+        if (
+            ts.isCallExpression(node) &&
+            ts.isIdentifier(node.expression) &&
+            helperNames.has(node.expression.text)
+        ) {
+            calledHelpers.push({
+                name: node.expression.text,
+                position: node.expression.getStart(source),
+            })
+        }
+        node.forEachChild(visit)
+    }
+    visit(source)
+
+    const unbound = calledHelpers.find((call) => !bound.has(call.name))
+    if (unbound !== undefined) {
+        const { line, character } = source.getLineAndCharacterOfPosition(unbound.position)
+        throw new Error(
+            `[abide] ${context} calls runtime helper \`${unbound.name}\` at line ${line + 1}:${character + 1} but never imports it — the dead-import filter dropped it. Please report this with the component source.\nOutput:\n${module}`,
+        )
+    }
+}

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

@@ -0,0 +1,19 @@
+/*
+Fail-loud guard for generated code. The compile passes build modules as strings and
+AST — a corruption (an un-handled rewrite position, a generator bug, a stale lowering)
+otherwise ships as a broken bundle that fails opaquely at load. Transpiling the output
+turns it into a compile-time error naming the stage and showing the offending source.
+`context` labels which stage produced it. Compile-time only; never on the hot path.
+*/
+
+const transpiler = new Bun.Transpiler({ loader: 'ts' })
+
+export function assertTranspiles(code: string, context: string): void {
+    try {
+        transpiler.transformSync(code)
+    } catch (error) {
+        throw new Error(
+            `[abide] ${context} produced invalid syntax — please report this with the component source. Output:\n${code}\n\n${String(error)}`,
+        )
+    }
+}

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

@@ -1,5 +1,8 @@
+import ts from 'typescript'
 import { ABIDE_PACKAGE_NAME } from '../../shared/ABIDE_PACKAGE_NAME.ts'
 import { analyzeComponent } from './analyzeComponent.ts'
+import { assertRuntimeHelpersBound } from './assertRuntimeHelpersBound.ts'
+import { assertTranspiles } from './assertTranspiles.ts'
 import { compileComponent } from './compileComponent.ts'
 import { compileSSR } from './compileSSR.ts'
 import { UI_RUNTIME_IMPORTS } from './UI_RUNTIME_IMPORTS.ts'
@@ -58,14 +61,6 @@ if (!hotReplace(${id}, component)) location.reload()
     }
 
     const ssrBody = indent(compileSSR(source, isLayout, options.moduleId, analyzed))
-    /* Per-component dead-import elimination: emit only the runtime names this module
-       actually references. A component that uses no `each`/`await`/`html` shouldn't
-       drag those modules into its chunk. The package isn't globally side-effect-free
-       (the dev/runtime entries register globals), so a bundler can't tree-shake the
-       unused imports for us — but the generated code is the one place that knows
-       exactly which names it emitted, so it filters here. A name absent from the body
-       is unreferenced; erring toward inclusion (a stray match in user script) only
-       keeps a harmless unused import, never drops a needed one. */
     const moduleBody = `function build(host, $props) {
 ${body}
 }
@@ -89,37 +84,37 @@ component.hydrate = hydrateInto
 component.build = build
 component.hydratable = ${analyzed.hydratable}
 ${options.moduleId === undefined ? '' : `component.__abideId = ${JSON.stringify(options.moduleId)}\n`}`
-    /* Scope each name to the surface that genuinely references it. The SSR body
-       carries fixed boilerplate ($attr/$text helpers, `<!--abide:html-->` markers,
-       the `{ html, state, awaits }` return shape) whose substrings would falsely
-       match value/DOM imports — so client helpers are matched against the client
-       build, render-pass helpers against the SSR body, and the two wrapper calls
-       (mount/hydrate) are always present. */
-    const clientSurface = `${userImports}\n${body}`
-    const isReferenced = (entry: { name: string; specifier: string }): boolean => {
-        if (entry.name === 'mount' || entry.name === 'hydrate') {
-            return true
-        }
-        /* The SSR render always brackets itself with a per-render scope (compileSSR),
-           so these are referenced whenever the `render` export is — i.e. always. */
-        if (entry.name === 'enterScope' || entry.name === 'exitScope') {
-            return true
-        }
-        /* Render-pass helpers are emitted by both back-ends (e.g. client and server
-           await/try blocks both call nextBlockId); their names are distinctive enough
-           that scanning both surfaces adds no false match. */
-        const surface = entry.specifier.startsWith('ui/runtime/')
-            ? `${clientSurface}\n${ssrBody}`
-            : clientSurface
-        return new RegExp(`\\b${entry.name}\\b`).test(surface)
-    }
-    const importBlock = UI_RUNTIME_IMPORTS.filter(isReferenced)
+    /* Per-component dead-import elimination: emit only the runtime helpers this module
+       references. A component using no `each`/`await`/`html` shouldn't drag those modules
+       into its chunk, and the package isn't globally side-effect-free (the dev/runtime
+       entries register globals), so a bundler can't tree-shake them for us.
+       Which to keep: tokenize the generated body and keep the names it genuinely
+       references. Reading the ACTUAL output (not hand-tracking emit sites) is safe by
+       construction — it can never drop a needed import, the way a missed emit-site tag
+       could. Tokenizing rather than substring-matching (`\bname\b`) means a name inside a
+       string/comment/HTML literal (e.g. an `on`-attribute in static markup) no longer
+       forces a spurious import, so no per-surface scoping is needed: a client-only helper
+       simply doesn't appear as an identifier in the SSR body. */
+    const referenced = collectIdentifiers(`${userImports}\n${body}\n${ssrBody}\n${moduleBody}`)
+    const importBlock = UI_RUNTIME_IMPORTS.filter((entry) => referenced.has(entry.name))
         .map((entry) => `import { ${entry.name} } from '${ABIDE_PACKAGE_NAME}/${entry.specifier}'`)
         .join('\n')
-    return `${importBlock}
+    const module = `${importBlock}
 ${userImports}
 
 ${moduleBody}`
+    /* Fail-loud over the WHOLE module, not just the script: the `generateBuild` /
+       `generateSSR` back-ends emit the build and render bodies as string-codegen, the
+       largest un-typed surface in the pipeline. A corruption there (a bad emit on a
+       template shape no test exercises) otherwise ships as a broken bundle; this surfaces
+       it as a located compile error for every component. */
+    assertTranspiles(module, 'component module generation')
+    /* `assertTranspiles` only proves the output PARSES — a call to an un-imported helper is
+       valid syntax, so it slips through. This second guard proves the output is BOUND: every
+       runtime helper it calls is actually imported (an independent check of the dead-import
+       filter above), turning a runtime `ReferenceError` into a located compile error. */
+    assertRuntimeHelpersBound(module, 'component module generation')
+    return module
 }
 
 /* Indents a body block for embedding inside a wrapper function. Lines whose start
@@ -152,3 +147,30 @@ function unescapedBacktickCount(line: string): number {
     }
     return count
 }
+
+/* The identifier names a generated module references — every Identifier node, walked
+   from the real output's AST so string / comment / HTML-literal contents are excluded.
+   Used to decide which runtime helpers to import; reading the output (vs hand-tracking
+   emit sites) can never drop a needed import. A full parse (not a raw token scan) is what
+   keeps template literals honest: a `${…}` substitution — e.g. `navigate(`/p?ts=${Date.now()}`)`
+   in a handler — leaves the scanner unable to find the substitution's closing `}` without
+   the parser's re-scan, so a token-only pass mis-reads the rest of the module as template
+   text and drops every helper referenced after it (an `import`-less `effect`/`mountChild`
+   → a `ReferenceError` at mount → the router's reload fallback → a refresh loop). */
+function collectIdentifiers(code: string): Set<string> {
+    const source = ts.createSourceFile(
+        'module.ts',
+        code,
+        ts.ScriptTarget.Latest,
+        /* setParentNodes */ false,
+    )
+    const names = new Set<string>()
+    const visit = (node: ts.Node): void => {
+        if (ts.isIdentifier(node)) {
+            names.add(node.text)
+        }
+        node.forEachChild(visit)
+    }
+    visit(source)
+    return names
+}

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

@@ -1,7 +1,6 @@
 import { analyzeComponent } from './analyzeComponent.ts'
 import { generateSSR } from './generateSSR.ts'
 import { SSR_ESCAPE } from './SSR_ESCAPE.ts'
-import { stripEffects } from './stripEffects.ts'
 import type { AnalyzedComponent } from './types/AnalyzedComponent.ts'
 
 /*
@@ -44,8 +43,7 @@ export function compileSSR(
     scopeSeed?: string,
     analyzed: AnalyzedComponent = analyzeComponent(source, scopeSeed),
 ): string {
-    const { script, stateNames, derivedNames, computedNames, nodes } = analyzed
-    const lowered = stripEffects(script)
+    const { ssrScript: lowered, stateNames, derivedNames, computedNames, nodes } = analyzed
     const ssr = generateSSR(nodes, stateNames, derivedNames, computedNames, isLayout)
     /* No `<style>` in the markup — the scoped CSS is bundled into the entry stylesheet
        the shell links (see `abideUiPlugin`), so SSR output is styled by that sheet. The