@abide/abide 0.43.1 → 0.44.1

package/src/lib/shared/setGlobalCacheStoreResolver.ts

@@ -1,6 +1,4 @@
-import { globalCacheStoreSlot } from './globalCacheStoreSlot.ts'
-import type { CacheStore } from './types/CacheStore.ts'
+import { globalCacheStoreResolver } from './globalCacheStoreResolver.ts'
 
-export function setGlobalCacheStoreResolver(fn: () => CacheStore | undefined): void {
-    globalCacheStoreSlot.resolver = fn
-}
+// Registers the process-level cache store resolver. Called once per side at boot.
+export const setGlobalCacheStoreResolver = globalCacheStoreResolver.set

package/src/lib/shared/setPageResolver.ts

@@ -1,7 +1,4 @@
-import { pageSlot } from './pageSlot.ts'
-import type { PageSnapshot } from './types/PageSnapshot.ts'
+import { pageResolver } from './pageResolver.ts'
 
 // Registers the runtime's page resolver. Called once per side at boot.
-export function setPageResolver(fn: () => PageSnapshot | undefined): void {
-    pageSlot.resolver = fn
-}
+export const setPageResolver = pageResolver.set

package/src/lib/shared/setRequestScopeResolver.ts

@@ -1,6 +1,4 @@
-import { requestScopeSlot } from './requestScopeSlot.ts'
-import type { RequestScopeInfo } from './types/RequestScopeInfo.ts'
+import { requestScopeResolver } from './requestScopeResolver.ts'
 
-export function setRequestScopeResolver(fn: () => RequestScopeInfo | undefined): void {
-    requestScopeSlot.resolver = fn
-}
+// Registers the runtime's request-scope resolver. Called once per side at boot.
+export const setRequestScopeResolver = requestScopeResolver.set

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/DebugGate.ts

@@ -0,0 +1,10 @@
+/*
+The two questions a DEBUG string answers for one channel name. `enabled` gates a
+diagnostic channel (inclusion, with exclusions winning); `negated` is the off
+switch for always-on channels (a `-name` pattern silencing the app's own or
+abide's framework voice). Returned by debugGate, already bound to one env value.
+*/
+export type DebugGate = {
+    enabled(name: string): boolean
+    negated(name: string): 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/types/ResolverSlot.ts

@@ -0,0 +1,10 @@
+/*
+The mutable cell a runtime entry registers its resolver into, plus the single
+lazy/value fallback used when no resolver is registered. createServer and
+startClient install side-specific resolvers; isolated tests poke `.resolver` /
+`.fallback` directly, so both fields stay public and mutable.
+*/
+export type ResolverSlot<T> = {
+    resolver: (() => T | undefined) | undefined
+    fallback: T | undefined
+}

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,9 +4,16 @@ 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`)
+    const next = `${DTS_BANNER}\n${body}\n\nexport {}\n`
+    const file = Bun.file(`${cwd}/src/.abide/${name}.d.ts`)
+    // Skip the write when byte-identical — an unchanged rebuild (the common case)
+    // otherwise bumps mtime every save, forcing the editor's TS server to re-typecheck.
+    if ((await file.exists()) && (await file.text()) === next) {
+        return
+    }
+    await Bun.write(file, next)
 }

package/src/lib/shared/writePublicAssetsDts.ts

@@ -1,3 +1,4 @@
+import { augmentModule } from './augmentModule.ts'
 import { writeDts } from './writeDts.ts'
 
 /*
@@ -19,13 +20,8 @@ export async function writePublicAssetsDts({
     importName: string
 }): Promise<void> {
     const entries = publicFiles
-        .map((file) => `        ${JSON.stringify(`/${file}`)}: true`)
-        .toSorted()
-        .join('\n')
-    const body = `declare module '${importName}/shared/url' {
-    interface PublicAssets {
-${entries}
-    }
-}`
-    await writeDts(cwd, 'publicAssets', body)
+        .map((file): [string, string] => [`/${file}`, 'true'])
+        .toSorted(([a], [b]) => (JSON.stringify(a) < JSON.stringify(b) ? -1 : 1))
+    const module = augmentModule(`${importName}/shared/url`, 'PublicAssets', entries)
+    await writeDts(cwd, 'publicAssets', module)
 }

package/src/lib/shared/writeRoutesDts.ts

@@ -1,30 +1,8 @@
+import { augmentModule } from './augmentModule.ts'
 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,28 +24,18 @@ 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)}`,
-        )
-        .join('\n')
+    const routesModule = augmentModule(
+        `${importName}/shared/page`,
+        'Routes',
+        routes.map(({ route }): [string, string] => [route, routeParamsShape(route)]),
+    )
     /* Keys-only mirror for url()'s autocomplete (values unused — PathParams derives the shape). */
-    const urlKeys = routes.map(({ route }) => `        ${JSON.stringify(route)}: true`).join('\n')
-    const body = `declare module '${importName}/shared/page' {
-    interface Routes {
-${entries}
-    }
-}
-
-declare module '${importName}/shared/url' {
-    interface PageRoutes {
-${urlKeys}
-    }
-}`
-    await writeDts(cwd, 'routes', body)
+    const urlModule = augmentModule(
+        `${importName}/shared/url`,
+        'PageRoutes',
+        routes.map(({ route }): [string, string] => [route, 'true']),
+    )
+    await writeDts(cwd, 'routes', `${routesModule}\n\n${urlModule}`)
 }

package/src/lib/shared/writeRpcDts.ts

@@ -1,6 +1,8 @@
+import { augmentModule } from './augmentModule.ts'
 import { carriesBodyArgs } from './carriesBodyArgs.ts'
 import { detectRpcMethod } from './detectRpcMethod.ts'
 import { fileStem } from './fileStem.ts'
+import { RPC_ARGS_TYPE } from './RPC_ARGS_TYPE.ts'
 import { rpcUrlForFile } from './rpcUrlForFile.ts'
 import { writeDts } from './writeDts.ts'
 
@@ -26,24 +28,23 @@ export async function writeRpcDts({
     rpcFiles: string[]
     importName: string
 }): Promise<void> {
-    const lines = await Promise.all(
-        rpcFiles.map(async (file) => {
+    const pairs = await Promise.all(
+        rpcFiles.map(async (file): Promise<[string, string] | undefined> => {
             const method = detectRpcMethod(await Bun.file(`${rpcDir}/${file}`).text())
             // A body rpc's args can't ride a URL — leave it out of the url() rpc map.
             if (!method || carriesBodyArgs(method)) {
                 return undefined
             }
             const importPath = `../server/rpc/${file}`
-            return `        ${JSON.stringify(rpcUrlForFile(file))}: RpcArgs<typeof import(${JSON.stringify(importPath)}).${fileStem(file)}>`
+            return [
+                rpcUrlForFile(file),
+                `RpcArgs<typeof import(${JSON.stringify(importPath)}).${fileStem(file)}>`,
+            ]
         }),
     )
-    const entries = lines.filter((line) => line !== undefined).toSorted()
-    const body = `type RpcArgs<Fn> = Fn extends (args: infer Args) => unknown ? Exclude<Args, FormData> : never
-
-declare module '${importName}/shared/url' {
-    interface RpcRoutes {
-${entries.join('\n')}
-    }
-}`
-    await writeDts(cwd, 'rpc', body)
+    const entries = pairs
+        .filter((pair) => pair !== undefined)
+        .toSorted(([a], [b]) => (JSON.stringify(a) < JSON.stringify(b) ? -1 : 1))
+    const module = augmentModule(`${importName}/shared/url`, 'RpcRoutes', entries)
+    await writeDts(cwd, 'rpc', `${RPC_ARGS_TYPE}\n\n${module}`)
 }

package/src/lib/shared/writeTestRpcDts.ts

@@ -1,5 +1,7 @@
+import { augmentModule } from './augmentModule.ts'
 import { commandNameForUrl } from './commandNameForUrl.ts'
 import { fileStem } from './fileStem.ts'
+import { RPC_ARGS_TYPE } from './RPC_ARGS_TYPE.ts'
 import { rpcUrlForFile } from './rpcUrlForFile.ts'
 import { writeDts } from './writeDts.ts'
 
@@ -24,22 +26,20 @@ export async function writeTestRpcDts({
     importName: string
 }): Promise<void> {
     const entries = rpcFiles
-        .map((file) => {
+        .map((file): [string, string] => {
             const name = commandNameForUrl(rpcUrlForFile(file))
             const importPath = `../server/rpc/${file}`
-            return `        ${JSON.stringify(name)}: RpcInvoker<typeof import(${JSON.stringify(importPath)}).${fileStem(file)}>`
+            return [
+                name,
+                `RpcInvoker<typeof import(${JSON.stringify(importPath)}).${fileStem(file)}>`,
+            ]
         })
-        .toSorted()
-    const body = `type RpcArgs<Fn> = Fn extends (args: infer Args) => unknown ? Exclude<Args, FormData> : never
+        .toSorted(([a], [b]) => (JSON.stringify(a) < JSON.stringify(b) ? -1 : 1))
+    const helperTypes = `${RPC_ARGS_TYPE}
 type RpcReturn<Fn> = Fn extends (...args: never[]) => Promise<infer Return> ? Return : never
 type RpcInvoker<Fn> = ((args?: RpcArgs<Fn>) => Promise<RpcReturn<Fn>>) & {
     raw: (args?: RpcArgs<Fn>) => Promise<Response>
-}
-
-declare module '${importName}/test/createTestApp' {
-    interface RpcClient {
-${entries.join('\n')}
-    }
 }`
-    await writeDts(cwd, 'testRpc', body)
+    const module = augmentModule(`${importName}/test/createTestApp`, 'RpcClient', entries)
+    await writeDts(cwd, 'testRpc', `${helperTypes}\n\n${module}`)
 }

package/src/lib/shared/writeTestSocketsDts.ts

@@ -1,3 +1,4 @@
+import { augmentModule } from './augmentModule.ts'
 import { fileStem } from './fileStem.ts'
 import { socketNameForFile } from './socketNameForFile.ts'
 import { writeDts } from './writeDts.ts'
@@ -20,15 +21,14 @@ export async function writeTestSocketsDts({
     importName: string
 }): Promise<void> {
     const entries = socketFiles
-        .map((file) => {
+        .map((file): [string, string] => {
             const importPath = `../server/sockets/${file}`
-            return `        ${JSON.stringify(socketNameForFile(file))}: typeof import(${JSON.stringify(importPath)}).${fileStem(file)}`
+            return [
+                socketNameForFile(file),
+                `typeof import(${JSON.stringify(importPath)}).${fileStem(file)}`,
+            ]
         })
-        .toSorted()
-    const body = `declare module '${importName}/test/createTestApp' {
-    interface SocketClient {
-${entries.join('\n')}
-    }
-}`
-    await writeDts(cwd, 'testSockets', body)
+        .toSorted(([a], [b]) => (JSON.stringify(a) < JSON.stringify(b) ? -1 : 1))
+    const module = augmentModule(`${importName}/test/createTestApp`, 'SocketClient', entries)
+    await writeDts(cwd, 'testSockets', module)
 }

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' },
 ]