@abide/abide 0.43.1 → 0.44.0

package/src/lib/shared/online.ts

@@ -3,7 +3,7 @@ import { requestScopeSlot } from './requestScopeSlot.ts'
 
 /*
 Reactive network-connectivity probe in the pending()/refreshing() family:
-reading it from a $derived/$effect re-runs that scope when the browser's
+reading it from a scope().computed() / scope().effect() re-runs that scope when the browser's
 online/offline events fire. navigator.onLine's *offline* signal is reliable
 (a true network loss always reports); its online value can false-positive
 behind captive portals — verified backend reachability is a separate,

package/src/lib/shared/outboxProbeSlot.ts

@@ -2,7 +2,7 @@
 Internal slot the browser outbox registry registers its prober into, so the
 shared pending() probe can count parked durable-rpc writes without shared/
 importing browser/. Mirrors tailProbeSlot. The prober reads the doc-backed
-queue entries (reactive inside $derived / $effect) and reports whether any
+queue entries (reactive inside scope().computed() / scope().effect()) and reports whether any
 undelivered entry matches the selector: a durable rpc selector (carries a
 `url`) narrows to its own queue, the bare form spans every registered queue,
 optional args narrow to one parked call by structural compare. Outbox state is

package/src/lib/shared/pageUrlForFile.ts

@@ -4,7 +4,7 @@ folder-based: every leaf is `page.abide` or `layout.abide`, and the URL
 is the directory path. Pages mount at the directory path; layouts mount at
 the directory prefix. Dynamic segments keep their `[name]` / `[...rest]`
 shape — translation to Bun's `:name` / `*` happens at server registration
-via toBunRoutePattern; consumers see the readable form in `nav.route`.
+via toBunRoutePattern; consumers see the readable form in `page.route`.
 */
 export function pageUrlForFile(relPath: string): string {
     const segments = relPath.split('/')

package/src/lib/shared/routeParamsShape.ts

@@ -0,0 +1,20 @@
+import { parseRouteSegments } from './parseRouteSegments.ts'
+
+/*
+The TypeScript type literal for a route's path params — `{ "id": string }` for
+`/post/[id]`, `Record<string, never>` for a param-less route. Walks the `[name]` /
+`[...rest]` segments; catch-all segments map to `string` under their declared name
+(the server's toBunRoutePattern renames Bun's `*` key back to that name when
+dispatching, so the page sees `params.rest`, not `params['*']`). The single source of
+truth shared by `writeRoutesDts` (page.params typing) and the `.abide` check shadow
+(page `props()` typing).
+*/
+export function routeParamsShape(routeUrl: string): string {
+    const keys = parseRouteSegments(routeUrl)
+        .filter((segment) => segment.kind === 'param')
+        .map((segment) => segment.name)
+    if (keys.length === 0) {
+        return 'Record<string, never>'
+    }
+    return `{ ${keys.map((key) => `${JSON.stringify(key)}: string`).join('; ')} }`
+}

package/src/lib/shared/snapshotShippable.ts

@@ -0,0 +1,22 @@
+import { hasReplayableRequest } from './hasReplayableRequest.ts'
+import type { CacheEntry } from './types/CacheEntry.ts'
+
+/*
+The one store-filter predicate selecting which cache entries are candidates for a
+warm snapshot: settled AND carrying a replayable (GET-only) wire request, so it
+can ship without re-firing a write or losing a body. Every selection site
+(serializeCacheSnapshot, the renderer's render-return and streaming-drain filters)
+calls this instead of re-spelling the guard, so they cannot drift.
+
+Composed from `hasReplayableRequest` — the request half snapshotEntryFromCache
+also gates on. snapshotEntryFromCache itself uses ONLY the request half (not
+`settled`): the streaming-drain path hands it still-pending entries and awaits
+them, so it can't require `settled` up front.
+
+This is the SYNC half of shippability — what's knowable from the entry without
+awaiting its body. The async response-level half (non-streaming + warmable kind)
+lives in snapshotEntryFromCache, reading the resolved Response.
+*/
+export function snapshotShippable(entry: CacheEntry): boolean {
+    return entry.settled === true && hasReplayableRequest(entry)
+}

package/src/lib/shared/types/CacheEntry.ts

@@ -75,7 +75,7 @@ type InvalidationState = {
     timer?: ReturnType<typeof setTimeout>
     /*
     An invalidation that arrived while a refetch was already in flight: fireRefetch
-    can't run concurrently, so it records the request here and re-schedules once the
+    can't run concurrently, so it sets this flag and re-schedules once the
     in-flight refetch settles, rather than dropping the newer invalidation.
     */
     pending?: boolean

package/src/lib/shared/types/CacheInvalidation.ts

@@ -2,8 +2,8 @@
 Detail payload of the cache store's 'invalidate' event — the set of cache
 keys one invalidation touched. A Set so each subscriber's membership check
 is O(1) regardless of how many keys a single invalidate spans. Shared
-between both dispatchers (cache.invalidate + streamed-resolution settling)
-and the cache store's listener, so the event's shape has one definition
-instead of an inline cast repeated at every site.
+between the dispatcher (cache.invalidate) and the cache store's listener,
+so the event's shape has one definition instead of an inline cast repeated
+at every site.
 */
 export type CacheInvalidation = Set<string>

package/src/lib/shared/types/ClientFlags.ts

@@ -1,8 +1,10 @@
 /*
 Which client surfaces a rpc or socket is exposed to. Browser is the
-historical default; MCP and CLI flip on automatically when the
-declaration carries a Standard Schema (the schema is what makes the
-non-browser surfaces safe to advertise). Explicit values always win.
+historical default. CLI flips on for any rpc or socket with a Standard
+Schema. MCP flips on automatically only for read-only rpcs (GET/HEAD)
+with a schema, and for any socket with a schema — mutating rpcs require
+an explicit clients.mcp even when a schema is present. Explicit values
+always win.
 */
 export type ClientFlags = {
     browser: boolean

package/src/lib/shared/types/LastConnection.ts

@@ -4,6 +4,6 @@ survives relaunch and is readable before any window or session opens. It records
 the *intent*, not a concrete embedded URL — an embedded server picks a fresh port
 each launch, so only `{ kind: 'embedded' }` is durable; a remote connection keeps
 its url. resolveLaunchTarget / resolveCliTarget read it; /connect and /start write
-it; /disconnect clears it.
+it; /__abide/disconnect clears it.
 */
 export type LastConnection = { kind: 'embedded' } | { kind: 'url'; url: string }

package/src/lib/shared/url.ts

@@ -8,6 +8,9 @@ import { queryStringFromArgs } from './queryStringFromArgs.ts'
 type QueryValue = string | number | boolean | undefined
 type Query = Record<string, QueryValue>
 
+/* Compiled once — a scheme-qualified URL (`http:`, `mailto:`). */
+const SCHEME_QUALIFIED = /^[a-z][a-z0-9+.-]*:/i
+
 /*
 Augmentable rpc map. Codegen emits a `declare module '<importName>/shared/url'`
 block filling this with `'/rpc/<file>': args` for each query-carrying (GET)
@@ -77,7 +80,7 @@ export function url<P extends KnownPath | (string & {})>(
 ): string
 export function url(path: string, first?: Query, second?: Query): string {
     // Scheme-qualified (http:, mailto:) or protocol-relative URLs are external — leave them whole.
-    if (/^[a-z][a-z0-9+.-]*:/i.test(path) || path.startsWith('//')) {
+    if (SCHEME_QUALIFIED.test(path) || path.startsWith('//')) {
         return appendQuery(path, first)
     }
     const segments = parseRouteSegments(path)

package/src/lib/shared/withBase.ts

@@ -3,8 +3,7 @@ import { basePath } from './basePath.ts'
 /*
 Prefixes a rooted internal path (`/rpc/…`, `/__abide/…`) with the mount base
 so the client's framework requests route through the proxy (`/v2/rpc/…`). The
-single rule the runtime fetch sites (remoteProxy, openResolveStream,
-socketChannel, the streaming placeholders) share — '' at root is a no-op.
+single rule the runtime fetch sites (remoteProxy, socketChannel, health) share — '' at root is a no-op.
 */
 export function withBase(path: string): string {
     return `${basePath()}${path}`

package/src/lib/shared/writeDts.ts

@@ -4,8 +4,8 @@ const DTS_BANNER = '// Generated by abide. Do not edit by hand.'
 /*
 Writes a generated `.d.ts` to `src/.abide/<name>.d.ts` (the path the consumer's
 src tsconfig include picks up), wrapping `body` in the shared banner + the
-`export {}` footer that makes the file a module. The three codegen writers
-(routes, rpc, public assets) differ only in `body`, so the envelope lives here.
+`export {}` footer that makes the file a module. All codegen writers (routes, rpc, publicAssets, testRpc, testSockets, health)
+differ only in `body`, so the envelope lives here.
 */
 export async function writeDts(cwd: string, name: string, body: string): Promise<void> {
     await Bun.write(`${cwd}/src/.abide/${name}.d.ts`, `${DTS_BANNER}\n${body}\n\nexport {}\n`)

package/src/lib/shared/writeRoutesDts.ts

@@ -1,30 +1,7 @@
 import { pageUrlForFile } from './pageUrlForFile.ts'
-import { parseRouteSegments } from './parseRouteSegments.ts'
+import { routeParamsShape } from './routeParamsShape.ts'
 import { writeDts } from './writeDts.ts'
 
-/*
-Walks a `[name]` / `[...rest]` route URL and returns the param shape it
-declares. Catch-all segments map to `string` under their declared name —
-the server's toBunRoutePattern renames Bun's `*` key back to that name
-when dispatching, so the page component sees `params.rest`, not
-`params['*']`.
-*/
-function paramsForRoute(routeUrl: string): Record<string, 'string'> {
-    return Object.fromEntries(
-        parseRouteSegments(routeUrl)
-            .filter((segment) => segment.kind === 'param')
-            .map((segment) => [segment.name, 'string'] as const),
-    )
-}
-
-function renderParamsShape(shape: Record<string, 'string'>): string {
-    const keys = Object.keys(shape)
-    if (keys.length === 0) {
-        return 'Record<string, never>'
-    }
-    return `{ ${keys.map((key) => `${JSON.stringify(key)}: string`).join('; ')} }`
-}
-
 /*
 Emits a `.d.ts` that augments abide's `Routes` interface with one entry per
 page file in the project. Page picks this up as a discriminated union keyed
@@ -46,15 +23,10 @@ export async function writeRoutesDts({
     importName: string
 }): Promise<void> {
     const routes = pageFiles
-        .map((file) => ({
-            route: pageUrlForFile(file),
-            params: paramsForRoute(pageUrlForFile(file)),
-        }))
+        .map((file) => ({ route: pageUrlForFile(file) }))
         .toSorted((a, b) => a.route.localeCompare(b.route))
     const entries = routes
-        .map(
-            ({ route, params }) => `        ${JSON.stringify(route)}: ${renderParamsShape(params)}`,
-        )
+        .map(({ route }) => `        ${JSON.stringify(route)}: ${routeParamsShape(route)}`)
         .join('\n')
     /* Keys-only mirror for url()'s autocomplete (values unused — PathParams derives the shape). */
     const urlKeys = routes.map(({ route }) => `        ${JSON.stringify(route)}: true`).join('\n')

package/src/lib/test/createTestSocketChannel.ts

@@ -14,9 +14,9 @@ machinery — a test owns the connection lifecycle through `close()`, so a drop
 is teardown, not something to recover from. Frames sent before the ws opens
 queue and flush on open, the one piece of timing a test can't sidestep.
 
-Implements SocketChannel (subscribe/unsubscribe/publish), so `socket(name)`
-hands its sockets to the same buildSocketOverChannel the browser socketProxy
-uses — the Socket<T> surface can't drift between the test path and production.
+Uses the same createSocketSubRegistry-backed SocketChannel the browser channel
+uses, so `socket(name)` passes it to the same buildSocketOverChannel the browser
+socketProxy uses — the Socket<T> surface can't drift between the test path and production.
 */
 export function createTestSocketChannel(wsUrl: string): {
     socket: <T>(name: string) => Socket<T>

package/src/lib/ui/COMPONENT_WRAPPER_PREFIX.ts

@@ -1,5 +1,5 @@
 /* The `abide-` tag prefix on framework-owned custom elements (the router's
    `abide-outlet`, the streaming `abide-resolve`/`abide-cache` fragments). `scopeLabel`
-   strips it to read the outlet host's bare name. Child components no longer mount into
+   strips it to derive the bare name from a framework-owned host tag (e.g. `abide-resolve` → `resolve`). Child components no longer mount into
    an `abide-<name>` wrapper — they build as marker ranges (see `mountRange`). */
 export const COMPONENT_WRAPPER_PREFIX = 'abide-'

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

@@ -1,9 +1,16 @@
+import ts from 'typescript'
+
 /*
-The LSP semantic-tokens legend abide lsp advertises, and the decoder from
+The LSP semantic-tokens legend abide lsp advertises, and the decoders from
 TypeScript's encoded classifications to legend names. TypeScript encodes a
-classification as `((tokenType + 1) << 8) + modifierBitset`; its TokenType and
-TokenModifier enums fix the orders below. `keyword`/`operator` carry the `{#…}`
-block framing the structural tokenizer emits.
+*semantic* classification as `((tokenType + 1) << 8) + modifierBitset`; its
+TokenType and TokenModifier enums fix the orders below. `keyword`/`operator` carry
+the `{#…}` block framing the structural tokenizer emits; `string`/`number`/`regexp`
+carry the literal *syntactic* classifications the semantic classifier never reports
+(so a template-literal string inside `{…}` gets string coloring); `tag`/`attribute`/
+`comment` carry the HTML markup structure the markup tokenizer emits, so the LSP
+owns element/attribute/comment coloring instead of leaning on tree-sitter (which
+desyncs on abide's `attr={expr}` values).
 */
 
 /* TS TokenType order (class=0 … member=11) → LSP token-type name. */
@@ -25,12 +32,32 @@ const TS_TYPE_TO_LSP = [
 /* TS TokenModifier order (declaration=bit 0 … local=bit 5). */
 const TS_MODIFIERS = ['declaration', 'static', 'async', 'readonly', 'defaultLibrary', 'local']
 
+/* TS syntactic `ClassificationType` (legacy direct enum value) → literal legend
+   type. Only the literals the semantic classifier omits; identifiers, keywords, and
+   punctuation are left to the semantic pass (or untouched). */
+const SYNTACTIC_LITERAL_TO_LSP: Partial<Record<ts.ClassificationType, string>> = {
+    [ts.ClassificationType.stringLiteral]: 'string',
+    [ts.ClassificationType.numericLiteral]: 'number',
+    [ts.ClassificationType.bigintLiteral]: 'number',
+    [ts.ClassificationType.regularExpressionLiteral]: 'regexp',
+}
+
 export const ABIDE_SEMANTIC_TOKENS_LEGEND = {
-    tokenTypes: [...TS_TYPE_TO_LSP, 'keyword', 'operator'],
+    tokenTypes: [
+        ...TS_TYPE_TO_LSP,
+        'keyword',
+        'operator',
+        'string',
+        'number',
+        'regexp',
+        'tag',
+        'attribute',
+        'comment',
+    ],
     tokenModifiers: TS_MODIFIERS,
 }
 
-/* Decodes one TypeScript encoded classification into legend names. */
+/* Decodes one TypeScript encoded *semantic* classification into legend names. */
 export function mapTsClassification(
     classification: number,
 ): { type: string; modifiers: string[] } | undefined {
@@ -43,3 +70,10 @@ export function mapTsClassification(
     const modifiers = TS_MODIFIERS.filter((_, bit) => (modifierSet & (1 << bit)) !== 0)
     return { type, modifiers }
 }
+
+/* Decodes one TypeScript *syntactic* classification (the legacy direct enum value,
+   not the bit-shifted semantic form) into a literal legend type, or undefined for
+   classifications the semantic pass already covers. */
+export function mapSyntacticClassification(classification: number): string | undefined {
+    return SYNTACTIC_LITERAL_TO_LSP[classification as ts.ClassificationType]
+}

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

@@ -1,5 +1,5 @@
 /* The callee names the `.abide` compiler recognises as reactive declarations
-   (`let x = state(...)`, `linked(...)`, `computed(...)`, and the destructuring
+   (`scope().state(...)`, `scope().linked(...)`, `scope().computed(...)`, and the destructuring
    `const {…} = props()`): the shared "is this a reactive binding" allowlist read by
    the desugarer, the nested-script scoper, and the type-checking shadow. How each
    lowers — a serializable doc slot vs a `.value` cell — is decided per-site; this is

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

@@ -4,42 +4,54 @@ paired with its package subpath (after the package name). One source of truth so
 three things can't drift: the normal module's import block (`compileModule`), the
 hot module's `window.__abide` destructure (dev component HMR), and the dev bridge
 that populates `window.__abide`. Order is the emit order.
+
+`alias` (when set) is the LOCAL name codegen emits — a `$$`-prefixed form reserved
+for the compiler so a user variable of the helper's bare name can never collide
+(`each as $$each`). It defaults to `name`; the dev bridge keys stay bare (the import
+source), so a hot module destructures `{ name: alias }`. As each helper's emit sites
+flip to its `$$` alias, set `alias` here in lockstep.
 */
-export const UI_RUNTIME_IMPORTS: { name: string; specifier: string }[] = [
-    { name: 'html', specifier: 'shared/html' },
-    { name: 'snippet', specifier: 'shared/snippet' },
-    { name: 'scope', specifier: 'ui/scope' },
-    { name: 'enterScope', specifier: 'ui/enterScope' },
-    { name: 'exitScope', specifier: 'ui/exitScope' },
-    { name: 'effect', specifier: 'ui/effect' },
-    { name: 'mount', specifier: 'ui/dom/mount' },
-    { name: 'appendText', specifier: 'ui/dom/appendText' },
-    { name: 'appendTextAt', specifier: 'ui/dom/appendTextAt' },
-    { name: 'appendSnippet', specifier: 'ui/dom/appendSnippet' },
-    { name: 'appendStatic', specifier: 'ui/dom/appendStatic' },
-    { name: 'cloneStatic', specifier: 'ui/dom/cloneStatic' },
-    { name: 'skeleton', specifier: 'ui/dom/skeleton' },
-    { name: 'anchorCursor', specifier: 'ui/dom/anchorCursor' },
-    { name: 'attr', specifier: 'ui/dom/attr' },
-    { name: 'on', specifier: 'ui/dom/on' },
-    { name: 'attach', specifier: 'ui/dom/attach' },
-    { name: 'each', specifier: 'ui/dom/each' },
-    { name: 'eachAsync', specifier: 'ui/dom/eachAsync' },
-    { name: 'when', specifier: 'ui/dom/when' },
-    { name: 'awaitBlock', specifier: 'ui/dom/awaitBlock' },
-    { name: 'tryBlock', specifier: 'ui/dom/tryBlock' },
-    { name: 'switchBlock', specifier: 'ui/dom/switchBlock' },
-    { name: 'mountSlot', specifier: 'ui/dom/mountSlot' },
-    { name: 'outlet', specifier: 'ui/dom/outlet' },
-    { name: 'mountChild', specifier: 'ui/dom/mountChild' },
-    { name: 'mergeProps', specifier: 'ui/dom/mergeProps' },
-    { name: 'spreadProps', specifier: 'ui/dom/spreadProps' },
-    { name: 'restProps', specifier: 'ui/dom/restProps' },
-    { name: 'spreadAttrs', specifier: 'ui/dom/spreadAttrs' },
-    { name: 'readCall', specifier: 'ui/dom/readCall' },
-    { name: 'hydrate', specifier: 'ui/dom/hydrate' },
-    { name: 'escapeKey', specifier: 'ui/runtime/escapeKey' },
-    { name: 'nextBlockId', specifier: 'ui/runtime/nextBlockId' },
-    { name: 'enterRenderPass', specifier: 'ui/runtime/enterRenderPass' },
-    { name: 'exitRenderPass', specifier: 'ui/runtime/exitRenderPass' },
+export const UI_RUNTIME_IMPORTS: { name: string; specifier: string; alias?: string }[] = [
+    { name: 'snippet', specifier: 'shared/snippet', alias: '$$snippet' },
+    /* `scope` is author-facing (`scope().state(...)`) but lowers to `$$scope` shadowably:
+       `referenceFor` rewrites a bare `scope` read to `$$scope` only when not lexically
+       shadowed, so the aliased import is the binding that emitted code resolves to. */
+    { name: 'scope', specifier: 'ui/scope', alias: '$$scope' },
+    { name: 'enterScope', specifier: 'ui/enterScope', alias: '$$enterScope' },
+    { name: 'exitScope', specifier: 'ui/exitScope', alias: '$$exitScope' },
+    { name: 'effect', specifier: 'ui/effect', alias: '$$effect' },
+    { name: 'mount', specifier: 'ui/dom/mount', alias: '$$mount' },
+    { name: 'appendText', specifier: 'ui/dom/appendText', alias: '$$appendText' },
+    { name: 'appendTextAt', specifier: 'ui/dom/appendTextAt', alias: '$$appendTextAt' },
+    { name: 'appendSnippet', specifier: 'ui/dom/appendSnippet', alias: '$$appendSnippet' },
+    { name: 'appendStatic', specifier: 'ui/dom/appendStatic', alias: '$$appendStatic' },
+    { name: 'cloneStatic', specifier: 'ui/dom/cloneStatic', alias: '$$cloneStatic' },
+    { name: 'skeleton', specifier: 'ui/dom/skeleton', alias: '$$skeleton' },
+    { name: 'anchorCursor', specifier: 'ui/dom/anchorCursor', alias: '$$anchorCursor' },
+    { name: 'attr', specifier: 'ui/dom/attr', alias: '$$attr' },
+    { name: 'on', specifier: 'ui/dom/on', alias: '$$on' },
+    { name: 'attach', specifier: 'ui/dom/attach', alias: '$$attach' },
+    { name: 'each', specifier: 'ui/dom/each', alias: '$$each' },
+    { name: 'eachAsync', specifier: 'ui/dom/eachAsync', alias: '$$eachAsync' },
+    { name: 'when', specifier: 'ui/dom/when', alias: '$$when' },
+    { name: 'awaitBlock', specifier: 'ui/dom/awaitBlock', alias: '$$awaitBlock' },
+    { name: 'tryBlock', specifier: 'ui/dom/tryBlock', alias: '$$tryBlock' },
+    { name: 'switchBlock', specifier: 'ui/dom/switchBlock', alias: '$$switchBlock' },
+    { name: 'mountSlot', specifier: 'ui/dom/mountSlot', alias: '$$mountSlot' },
+    { name: 'outlet', specifier: 'ui/dom/outlet', alias: '$$outlet' },
+    { name: 'mountChild', specifier: 'ui/dom/mountChild', alias: '$$mountChild' },
+    { name: 'mergeProps', specifier: 'ui/dom/mergeProps', alias: '$$mergeProps' },
+    { name: 'spreadProps', specifier: 'ui/dom/spreadProps', alias: '$$spreadProps' },
+    { name: 'restProps', specifier: 'ui/dom/restProps', alias: '$$restProps' },
+    { name: 'spreadAttrs', specifier: 'ui/dom/spreadAttrs', alias: '$$spreadAttrs' },
+    { name: 'readCall', specifier: 'ui/dom/readCall', alias: '$$readCall' },
+    { name: 'hydrate', specifier: 'ui/dom/hydrate', alias: '$$hydrate' },
+    { name: 'escapeKey', specifier: 'ui/runtime/escapeKey', alias: '$$escapeKey' },
+    { name: 'nextBlockId', specifier: 'ui/runtime/nextBlockId', alias: '$$nextBlockId' },
+    {
+        name: 'enterRenderPass',
+        specifier: 'ui/runtime/enterRenderPass',
+        alias: '$$enterRenderPass',
+    },
+    { name: 'exitRenderPass', specifier: 'ui/runtime/exitRenderPass', alias: '$$exitRenderPass' },
 ]

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

@@ -15,7 +15,7 @@ only UI loader in the dev/build/preload pipeline; the emitted module's
 `abide/ui/*` imports resolve through the package exports.
 
 A `layout.abide` compiles as a layout: its `<slot/>` lowers to the router's page
-outlet (`<abide-outlet>`) rather than a passed-children slot — the file's role is
+outlet (a `<!--abide:outlet-->…<!--/abide:outlet-->` comment boundary the router fills) rather than a passed-children slot — the file's role is
 its name, so the loader flags it from the path stem.
 
 The emitted module embeds the component's `<script>` and `{expr}` bodies verbatim,

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

@@ -16,7 +16,9 @@ comment is not a `CallExpression` callee, so a docs component quoting framework
 (`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))
+    /* The EMITTED local names (the `$$` alias when set) — codegen calls those, and the
+       aliased import binds them, so the bound/called check must use the same form. */
+    const helperNames = new Set(UI_RUNTIME_IMPORTS.map((entry) => entry.alias ?? entry.name))
     const source = ts.createSourceFile(
         'module.ts',
         module,

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

@@ -1,4 +1,6 @@
+import { catchBinding } from './catchBinding.ts'
 import { resolveBranches } from './resolveBranches.ts'
+import type { Binding } from './types/Binding.ts'
 import type { TemplateNode } from './types/TemplateNode.ts'
 
 /* The structural shape of an `await` block, resolved ONCE from the node so the build and
@@ -23,6 +25,12 @@ export type AwaitPlan = {
     /* Neither catch nor finally → a rejection must surface (re-throw / `undefined` catch thunk)
        instead of rendering an empty branch. */
     surfaceRejection: boolean
+    /* The resolved branch's binding (`resolvedAs`, `reactive` — a `.value` cell on the
+       client, a re-settle updates it in place). One element. */
+    resolvedBindings: Binding[]
+    /* The catch branch's binding (`catchAs`, `plain`); empty when no catch branch. The
+       `finally` branch binds nothing, so it registers no binding. */
+    catchBindings: Binding[]
 }
 
 /* Resolves an `await` node's branches into the shared structural plan. */
@@ -35,14 +43,18 @@ export function awaitPlan(node: Extract<TemplateNode, { kind: 'await' }>): Await
     )
     const finallyChildren = finallyBranch?.children ?? []
     const nonBranch = node.children.filter((child) => child.kind !== 'branch')
+    const resolvedAs = (node.blocking ? node.as : thenBranch?.as) ?? '_value'
+    const catchAs = catchBranch?.as ?? '_error'
     return {
         blocking: node.blocking,
         pending: node.blocking ? [] : nonBranch,
         resolvedChildren: node.blocking ? nonBranch : (thenBranch?.children ?? []),
-        resolvedAs: (node.blocking ? node.as : thenBranch?.as) ?? '_value',
+        resolvedAs,
         catchChildren: catchBranch?.children ?? [],
-        catchAs: catchBranch?.as ?? '_error',
+        catchAs,
         finallyChildren,
         surfaceRejection: catchBranch === undefined && finallyChildren.length === 0,
+        resolvedBindings: [{ name: resolvedAs, classification: 'reactive' }],
+        catchBindings: catchBinding(catchAs, catchBranch !== undefined),
     }
 }

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

@@ -0,0 +1,8 @@
+import type { Binding } from './types/Binding.ts'
+
+/* A block's `catch` branch binding — the error name bound `plain`, or none when the block
+   has no catch branch. Shared by the await/each/try plans so the one catch-binding shape
+   stays single-source. */
+export function catchBinding(catchAs: string, hasCatch: boolean): Binding[] {
+    return hasCatch ? [{ name: catchAs, classification: 'plain' }] : []
+}

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

@@ -0,0 +1,108 @@
+import { interpolatedTemplateLiteral } from './interpolatedTemplateLiteral.ts'
+import type { TemplateAttr } from './types/TemplateAttr.ts'
+
+/*
+The one decision site for how an element's `class`/`style` base attribute composes
+with its `class:`/`style:` directives — lifted out of the two code-gen back-ends
+(`generateBuild`, `generateSSR`) so the load-bearing congruence (which attrs fold
+into a merged value, and HOW that value's parts concatenate) lives once. Each
+back-end RENDERS the returned plan differently — the build into a reactive `effect`,
+SSR into a pushed attribute string — but consults the same decision, so the markup
+the client clones and the server emits can never drift on the merge logic.
+
+The two back-ends differ ONLY in their merge TRIGGER, because their non-merge
+fallbacks differ: the build leaves a STATIC base in the cloned skeleton and toggles
+directives surgically, so it merges only when the base is INTERPOLATED (re-set on
+every update, which would wipe additive toggles) — `mergeClassBuild`/`mergeStyleBuild`.
+SSR must always emit ONE merged attribute string (a duplicate `class`/`style` is
+invalid), so it merges whenever a directive exists — `mergeClass`/`mergeStyle`. The
+PARTS that compose the value (`classParts`/`styleParts`) are identical either way, so
+they are built here once.
+
+`attrs` classified up front; `lower` rewrites the signal surface to `model` (the same
+transformer each back-end already threads through its expressions).
+*/
+
+/* The base class/style attribute (static or interpolated) found on the element. */
+type MergeBase =
+    | Extract<TemplateAttr, { kind: 'static' }>
+    | Extract<TemplateAttr, { kind: 'interpolated' }>
+    | undefined
+
+export type ClassStyleMergePlan = {
+    classBase: MergeBase
+    styleBase: MergeBase
+    classDirectives: Extract<TemplateAttr, { kind: 'class' }>[]
+    styleDirectives: Extract<TemplateAttr, { kind: 'style' }>[]
+    /* SSR trigger: merge whenever a directive exists (must emit one attribute). */
+    mergeClass: boolean
+    mergeStyle: boolean
+    /* Build trigger: merge only when the base is interpolated (a static base stays in
+       the skeleton + surgical toggles). */
+    mergeClassBuild: boolean
+    mergeStyleBuild: boolean
+    /* The JS expression list a merged value joins — base (if any) + directive parts.
+       `class` joins on a space (directive name when truthy); `style` joins on `;`
+       (`property:value`, String-coerced). Identical across back-ends. */
+    classParts: string[]
+    styleParts: string[]
+}
+
+/* The base class/style attribute (static or interpolated) for one property name. */
+function findBase(attrs: TemplateAttr[], name: 'class' | 'style'): MergeBase {
+    return attrs.find(
+        (attr): attr is NonNullable<MergeBase> =>
+            (attr.kind === 'static' || attr.kind === 'interpolated') && attr.name === name,
+    )
+}
+
+/* The base value as a lowered JS string expression, or undefined when there is no
+   base. A static base is a JSON string literal; an interpolated base is its
+   template-literal source run through `lower` (embedded signals → `model`). */
+function baseExpr(base: MergeBase, lower: (code: string) => string): string | undefined {
+    if (base === undefined) {
+        return undefined
+    }
+    return base.kind === 'static'
+        ? JSON.stringify(base.value)
+        : lower(interpolatedTemplateLiteral(base.parts))
+}
+
+/* Classifies an element's attrs into the class/style merge plan. */
+export function classStyleMergePlan(
+    attrs: TemplateAttr[],
+    lower: (code: string) => string,
+): ClassStyleMergePlan {
+    const classBase = findBase(attrs, 'class')
+    const styleBase = findBase(attrs, 'style')
+    const classDirectives = attrs.filter(
+        (attr): attr is Extract<TemplateAttr, { kind: 'class' }> => attr.kind === 'class',
+    )
+    const styleDirectives = attrs.filter(
+        (attr): attr is Extract<TemplateAttr, { kind: 'style' }> => attr.kind === 'style',
+    )
+    const classBaseExpr = baseExpr(classBase, lower)
+    const styleBaseExpr = baseExpr(styleBase, lower)
+    return {
+        classBase,
+        styleBase,
+        classDirectives,
+        styleDirectives,
+        mergeClass: classDirectives.length > 0,
+        mergeStyle: styleDirectives.length > 0,
+        mergeClassBuild: classBase?.kind === 'interpolated' && classDirectives.length > 0,
+        mergeStyleBuild: styleBase?.kind === 'interpolated' && styleDirectives.length > 0,
+        classParts: [
+            ...(classBaseExpr === undefined ? [] : [classBaseExpr]),
+            ...classDirectives.map(
+                (dir) => `((${lower(dir.code)}) ? ${JSON.stringify(dir.name)} : "")`,
+            ),
+        ],
+        styleParts: [
+            ...(styleBaseExpr === undefined ? [] : [styleBaseExpr]),
+            ...styleDirectives.map(
+                (dir) => `(${JSON.stringify(`${dir.property}:`)} + String(${lower(dir.code)}))`,
+            ),
+        ],
+    }
+}

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

@@ -25,6 +25,17 @@ export function collectAbideDiagnostics(shadow: ShadowProgram): AbideDiagnostic[
             })
             continue
         }
+        /* Shadow-raised author rules (e.g. importing a compiler-internal helper) are
+           already in source coordinates — emit them directly, no segment remap. */
+        for (const diagnostic of shadows.get(abidePath)?.diagnostics ?? []) {
+            diagnostics.push({
+                file: abidePath,
+                start: diagnostic.start,
+                length: diagnostic.length,
+                message: diagnostic.message,
+                category: ts.DiagnosticCategory.Error,
+            })
+        }
         const sourceFile = program.getSourceFile(`${abidePath}.ts`)
         const mappings = shadows.get(abidePath)?.mappings
         if (sourceFile === undefined || mappings === undefined) {