@abide/abide 0.46.0 → 0.48.0

package/src/lib/ui/renderToStream.ts

@@ -1,6 +1,5 @@
-import { deferResume } from './deferResume.ts'
 import { resumeSeedScript } from './resumeSeedScript.ts'
-import type { DeferMarker, ResumeEntry } from './runtime/RESUME.ts'
+import type { ResumeEntry } from './runtime/RESUME.ts'
 import type { SsrAwait, SsrRender } from './runtime/types/SsrRender.ts'
 import { tryEncodeResume } from './tryEncodeResume.ts'
 
@@ -40,8 +39,8 @@ export async function* renderToStream(
        instead of refetching. (`resume` is the render body's live object, so late writes
        appear here.) */
     const seededResume = new Set<number>(Object.keys(resume).map(Number))
-    const resumeDelta = (): Record<number, ResumeEntry | DeferMarker> => {
-        const delta: Record<number, ResumeEntry | DeferMarker> = {}
+    const resumeDelta = (): Record<number, ResumeEntry> => {
+        const delta: Record<number, ResumeEntry> = {}
         for (const [key, entry] of Object.entries(resume)) {
             const id = Number(key)
             if (!seededResume.has(id)) {
@@ -84,22 +83,19 @@ export async function* renderToStream(
     }
 }
 
-type Settled = { id: number; html: string; resume: ResumeEntry | DeferMarker }
+type Settled = { id: number; html: string; resume: ResumeEntry }
 
 /* Awaits one streaming block's promise and renders the resolved or error branch to
    HTML (the renderers are async so a nested `await` block composes), capturing the
    value (serializable) for the resume manifest. Errors serialize as their message —
-   enough for the catch branch, without leaking a stack. A cache-backed value defers via
-   `deferResume` (a `{defer,key}` marker + lazy body seed) — the client adopts the streamed
-   branch inert instead of decoding the value; a non-cache value ships inline as before. */
+   enough for the catch branch, without leaking a stack. The resolved value ships inline
+   so hydration adopts the streamed branch warm. */
 function settle(block: SsrAwait): Promise<Settled> {
-    /* Keep the promise: cache() tagged it with its key, which `deferResume` reads to defer. */
-    const pending = block.promise()
-    return Promise.resolve(pending).then(
+    return Promise.resolve(block.promise()).then(
         async (value) => ({
             id: block.id,
             html: await block.then(value),
-            resume: deferResume(pending, value),
+            resume: { ok: true, value },
         }),
         async (error) => {
             /* No catch branch → surface the rejection (500 before the first flush,
@@ -123,6 +119,6 @@ function settle(block: SsrAwait): Promise<Settled> {
    strings. `tryEncodeResume` handles the serialize-or-refetch policy (undefined → no
    script → the swap consumers skip registration → hydration re-runs that one promise).
    `applyResolved`/the inline swap script store it via `.textContent`; `awaitBlock` decodes it. */
-function encodeStreamResume(resume: ResumeEntry | DeferMarker, id: number): string | undefined {
+function encodeStreamResume(resume: ResumeEntry, id: number): string | undefined {
     return tryEncodeResume(resume, id)?.replace(/</g, '\\u003c')
 }

package/src/lib/ui/resumeSeedScript.ts

@@ -1,5 +1,5 @@
 import { safeJsonForScript } from '../shared/safeJsonForScript.ts'
-import type { DeferMarker, ResumeEntry } from './runtime/RESUME.ts'
+import type { ResumeEntry } from './runtime/RESUME.ts'
 import { tryEncodeResume } from './tryEncodeResume.ts'
 
 /* A self-contained `<script>` seeding the await-resume manifest with the blocking
@@ -11,7 +11,7 @@ import { tryEncodeResume } from './tryEncodeResume.ts'
    early or parse as a line terminator. Shared by the buffered (`createUiPageRenderer`)
    and streaming (`renderToStream`) paths. */
 // @documentation plumbing
-export function resumeSeedScript(resume: Record<number, ResumeEntry | DeferMarker>): string {
+export function resumeSeedScript(resume: Record<number, ResumeEntry>): string {
     /* ref-json (not JSON) so a value carrying cycles or shared back-references — a
        media tree with parent↔child links — seeds instead of being dropped. `tryEncodeResume`
        drops just an unserializable entry (the client re-runs that one branch's promise),

package/src/lib/ui/router.ts

@@ -1,8 +1,10 @@
+import { hydratingSlot } from '../shared/hydratingSlot.ts'
 import { layoutChainForRoute } from '../shared/layoutChainForRoute.ts'
+import { matchRoute } from '../shared/matchRoute.ts'
+import { wakeHydrationPeeks } from '../shared/wakeHydrationPeeks.ts'
 import { fillBoundary } from './dom/fillBoundary.ts'
 import { outlet } from './dom/outlet.ts'
 import { effect } from './effect.ts'
-import { matchRoute } from './matchRoute.ts'
 import { navigatePath } from './navigate.ts'
 import { CHILD_PRESENT } from './runtime/CHILD_PRESENT.ts'
 import { clientPage } from './runtime/clientPage.ts'
@@ -81,7 +83,8 @@ function clearRecoveryReloads(url: string): void {
 
 /*
 A minimal client router on the History API. `router` matches the current path
-against the route patterns (literal / `[name]` / `[...rest]`, via matchRoute),
+against the route patterns (literal / `[name]` / `[[name]]` / `[...rest]`, via
+the shared matchRoute — the same matcher the server dispatches with),
 imports the matching page's chunk — plus every `layout.abide` chunk that wraps it
 (`layoutChainForRoute`) — on demand, and mounts them as a chain: each layout into
 the previous layout's `<slot/>` outlet, the page into the innermost outlet.
@@ -249,13 +252,21 @@ export function router(
         }
         if (hydrating) {
             const previous = RENDER.hydration
+            const previousHydrating = hydratingSlot.active
             RENDER.hydration = { next: new Map() }
+            hydratingSlot.active = true
             enterRenderPass()
             try {
                 run()
             } finally {
                 exitRenderPass()
                 RENDER.hydration = previous
+                hydratingSlot.active = previousHydrating
+                /* Wake the peeks this pass withheld for SSR congruence, now that the pass is
+                   over and the warm value is congruent to show. Only on the outermost unwind. */
+                if (!previousHydrating) {
+                    wakeHydrationPeeks()
+                }
             }
             return
         }
@@ -428,6 +439,14 @@ export function router(
             ])
                 .then(([pageView, resolvedLayouts, decision]) => {
                     if (token !== sequence || disposed) {
+                        /* Consume the first-paint flag even when superseded: the boot SSR DOM
+                           is valid only for THIS boot navigation. Leaving `first` true would
+                           let a navigation that started before this settled (to a different
+                           page) skip its auth probe and hydrate the boot URL's SSR DOM as its
+                           own — claimExpected then throws and commit swallows it, stranding a
+                           broken page. Cleared here → the superseding nav builds create-mode
+                           (clearing the stale SSR DOM) and runs its probe. */
+                        first = false
                         return
                     }
                     /* handle() redirected: go where it pointed, replacing the blocked

package/src/lib/ui/runtime/RESUME.ts

@@ -16,12 +16,6 @@
    same reference. */
 export type ResumeEntry = { ok: true; value: unknown } | { ok: false; error: unknown }
 
-/* Deferred-resume marker (Tier 2): a large cache-backed `{#await cache()}` ships this in
-   place of its value — just the cache key, so hydration adopts the server branch inert and
-   pays no value decode. The client seeds that key lazily and materializes it only on a later
-   re-read. Discriminated from a ResumeEntry by the `defer` field. */
-export type DeferMarker = { defer: true; key: string }
-
 const globalScope = globalThis as { __abideResume?: Record<number, string> }
 globalScope.__abideResume ??= {}
 

package/src/lib/ui/runtime/ambientScopeBacking.ts

@@ -9,7 +9,7 @@ with `enterScope`/`exitScope` and `await`s inline between them (blocking `{#awai
 child renders, slots, a top-level `await`). A module global held across those awaits
 interleaves across concurrent requests — one render resumes to read another's scope.
 Keying the ambient off the per-request store (which the async context propagates
-correctly) isolates it. Mirrors `requestScopeResolver`'s server-installed slot; the
+correctly) isolates it. Mirrors `requestScopeSlot`'s server-installed slot; the
 indirection cost lands at build/effect-creation time, never on the signal hot path.
 */
 type ScopeBacking = { get(): Scope | undefined; set(value: Scope | undefined): void }

package/src/lib/ui/runtime/types/SsrRender.ts

@@ -1,4 +1,4 @@
-import type { DeferMarker, ResumeEntry } from '../RESUME.ts'
+import type { ResumeEntry } from '../RESUME.ts'
 
 /* One STREAMING await block captured during SSR (no `then` on the `await` tag): its
    boundary id, the promise to await, and the async string-renderers for the resolved
@@ -18,11 +18,10 @@ export type SsrAwait = {
 /* The result of a component's server `render()`: the pending-shell HTML, the
    serializable document snapshot for client resume, the STREAMING await blocks to
    flush out of order, and `resume` — the inline-rendered BLOCKING await values keyed
-   by boundary id, seeded into the manifest so hydration adopts them without a refetch. A
-   deferred (cache-backed) blocking value is a `DeferMarker` in place of the value. */
+   by boundary id, seeded into the manifest so hydration adopts them without a refetch. */
 export type SsrRender = {
     html: string
     state: unknown
     awaits: SsrAwait[]
-    resume: Record<number, ResumeEntry | DeferMarker>
+    resume: Record<number, ResumeEntry>
 }

package/src/lib/ui/scope.ts

@@ -5,10 +5,13 @@ import type { Scope } from './types/Scope.ts'
 /*
 Resolves the current lexical scope — established per lexical level by the compiler,
 so it reads "where you are" with no handle. Outside any scope (boot, a script) it
-mints a detached root once and reuses it. The returned value is passable: hand it to
-a child or a helper and it can read/extend/undo that scope (walk up via `.root()`).
+mints a detached root once and reuses it. Now the INTERNAL lowering host: the author
+reactive surface is the imported `state`/`state.linked`/`state.computed`/`effect`; the
+compiler lowers each onto this scope (`$$scope().derive`/`.linked`/`.effect`), and
+`state.share`/`.shared` route through it. Still published so generated code and the
+type-checking shadow can import it; not part of the author-facing surface.
 */
-// @documentation reactive-state
+// @documentation plumbing
 export function scope(): Scope {
     if (!CURRENT_SCOPE.current) {
         CURRENT_SCOPE.current = createScope()

package/src/lib/ui/seedBootState.ts

@@ -0,0 +1,53 @@
+import { baseSlot } from '../shared/baseSlot.ts'
+import { createTraceContext } from '../shared/createTraceContext.ts'
+import { healthSeedSlot } from '../shared/healthSeedSlot.ts'
+import { requestScopeSlot } from '../shared/requestScopeSlot.ts'
+import { rpcTimeoutSlot } from '../shared/rpcTimeoutSlot.ts'
+import { setAppName } from '../shared/setAppName.ts'
+import type { SsrBootState } from '../shared/types/SsrBootState.ts'
+
+/* Seeds every `__SSR__` boot-state field into its ambient slot. The map is typed
+   EXHAUSTIVELY over `SsrBootState`, so a boot field can't be added to the payload
+   without a seeder here — the compile error is what guarantees a stamped field is
+   never silently dropped client-side. Base is seeded first (object-key order), as the
+   prior hand-written sequence required: the cache seed that follows keys call urls
+   through the base resolver. */
+const SEED: { [K in keyof Required<SsrBootState>]: (value: SsrBootState[K]) => void } = {
+    base: (value) => {
+        baseSlot.resolver = () => value ?? ''
+    },
+    app: (value) => setAppName(value),
+    health: (value) => {
+        healthSeedSlot.payload = value
+    },
+    clientTimeout: (value) => {
+        rpcTimeoutSlot.ms = value
+    },
+    /* Continue the SSR request's trace (or mint a fresh sampled one if the stamp is
+       missing) and publish the browser's request scope: trace(), log line prefixes, and
+       the RPC traceparent header resolve through it. elapsedMs is navigation-relative —
+       exactly what performance.now() measures — and the path tracks client navigations
+       because the resolver reads location per call. */
+    trace: (value) => {
+        const traceContext = createTraceContext(value)
+        requestScopeSlot.resolver = () => ({
+            trace: traceContext,
+            elapsedMs: performance.now(),
+            method: 'GET',
+            path: typeof location === 'undefined' ? '' : location.pathname,
+        })
+    },
+}
+
+/* Applies one seeder to its own field — generic over the key so the seeder and its
+   value stay correlated (a bare `SEED[key](boot[key])` loses the correlation). */
+function seedField<K extends keyof SsrBootState>(key: K, boot: SsrBootState): void {
+    SEED[key](boot[key])
+}
+
+/* Seeds all boot-state slots from the payload, before mount. */
+export function seedBootState(boot: SsrBootState): void {
+    for (const key of Object.keys(SEED) as Array<keyof SsrBootState>) {
+        seedField(key, boot)
+    }
+}

package/src/lib/ui/socketChannel.ts

@@ -1,10 +1,10 @@
-import type { SocketClientFrame } from '../server/sockets/types/SocketClientFrame.ts'
-import type { SocketServerFrame } from '../server/sockets/types/SocketServerFrame.ts'
 import { createSocketSubRegistry } from '../shared/createSocketSubRegistry.ts'
 import { decodeRefJson } from '../shared/decodeRefJson.ts'
 import { encodeRefJson } from '../shared/encodeRefJson.ts'
 import { SOCKETS_PATH } from '../shared/SOCKETS_PATH.ts'
 import type { SocketChannel } from '../shared/types/SocketChannel.ts'
+import type { SocketClientFrame } from '../shared/types/SocketClientFrame.ts'
+import type { SocketServerFrame } from '../shared/types/SocketServerFrame.ts'
 import { withBase } from '../shared/withBase.ts'
 
 let singleton: SocketChannel | undefined

package/src/lib/ui/socketProxy.ts

@@ -1,6 +1,7 @@
-import type { Socket } from '../server/sockets/types/Socket.ts'
 import { buildSocketOverChannel } from '../shared/buildSocketOverChannel.ts'
+import type { Socket } from '../shared/types/Socket.ts'
 import { getSocketChannel } from './socketChannel.ts'
+import { watch } from './watch.ts'
 
 /*
 Client-side substitute for a server-declared Socket. The bundler emits
@@ -10,7 +11,7 @@ over the multiplexed ws channel). Both paths produce identical Socket
 shapes so user code reads the same on either side.
 
 The Socket surface — bare iteration as the live stream, `.tail(n)` seeded
-from the retained tail, `.publish` sending a server-validated `pub` frame —
+from the retained tail, `.broadcast` sending a server-validated `pub` frame —
 is built by buildSocketOverChannel over the page's lazily-opened singleton
 channel; this module only binds that builder to the browser channel so the
 test harness can reuse the identical surface over its own channel.
@@ -21,5 +22,10 @@ socketProxy API, not the wire layer.
 */
 // @documentation plumbing
 export function socketProxy<T>(name: string): Socket<T> {
-    return buildSocketOverChannel<T>(name, getSocketChannel)
+    const socket = buildSocketOverChannel<T>(name, getSocketChannel)
+    /* Overwrite the shared builder's inert `.watch` with the real reaction sugar
+       (`socket.watch(handler)` ≡ `watch(socket, handler)`). Attached here so the ui-only
+       `watch` primitive never rides into a server bundle. */
+    socket.watch = (handler) => watch(socket, handler)
+    return socket
 }

package/src/lib/ui/startClient.ts

@@ -1,14 +1,11 @@
+import { cacheStoreSlot } from '../shared/cacheStoreSlot.ts'
 import { createCacheStore } from '../shared/createCacheStore.ts'
-import { healthSeedSlot } from '../shared/healthSeedSlot.ts'
-import { rpcTimeoutSlot } from '../shared/rpcTimeoutSlot.ts'
-import { setAppName } from '../shared/setAppName.ts'
-import { setBaseResolver } from '../shared/setBaseResolver.ts'
-import { setCacheStoreResolver } from '../shared/setCacheStoreResolver.ts'
-import { setGlobalCacheStoreResolver } from '../shared/setGlobalCacheStoreResolver.ts'
-import { setPageResolver } from '../shared/setPageResolver.ts'
-import type { CacheSnapshotEntry } from '../shared/types/CacheSnapshotEntry.ts'
+import { pageSlot } from '../shared/pageSlot.ts'
+import { sharedCacheStoreSlot } from '../shared/sharedCacheStoreSlot.ts'
+import type { SsrPayload } from '../shared/types/SsrPayload.ts'
 import type { StreamedResolution } from '../shared/types/StreamedResolution.ts'
 import { probeNavigation } from './probeNavigation.ts'
+import { seedBootState } from './seedBootState.ts'
 
 /* Build-time flag the production client defines false (see build.ts `define`) so the dev-only
    hot bridge — and the entire DOM runtime it statically pulls in for re-builds — is dead-code-
@@ -21,15 +18,6 @@ import { clientPage } from './runtime/clientPage.ts'
 import type { RouteLoader } from './runtime/types/RouteLoader.ts'
 import { seedResolved } from './seedResolved.ts'
 
-/* The server's __SSR__ payload this entry consumes. */
-type SsrPayload = {
-    cache?: CacheSnapshotEntry[]
-    base?: string
-    app?: string
-    health?: Record<string, unknown>
-    clientTimeout?: number
-}
-
 /*
 The official abide-ui client entry. Reads the server's `window.__SSR__` payload,
 seeds a tab-scoped cache store from the inline snapshot (so a warm `cache()` read
@@ -67,23 +55,21 @@ export function startClient(
     if ((globalThis as { __abideInspect?: boolean }).__abideInspect) {
         import('./installInspectorBridge.ts').then((module) => module.installInspectorBridge())
     }
-    const ssr = (globalThis as { __SSR__?: SsrPayload }).__SSR__ ?? {}
-    setBaseResolver(() => ssr.base ?? '')
-    /* Seed the per-page __SSR__ stamps into their shared slots before mount: the app
-       name (default log channel), the health payload (so health()'s first probe is warm),
-       and the env-configured RPC timeout (ABIDE_CLIENT_TIMEOUT, shipped per request).
-       Without this the browser falls back to channel 'app', a cold first health probe,
-       and unbounded RPC fetches. */
-    setAppName(ssr.app)
-    healthSeedSlot.payload = ssr.health
-    rpcTimeoutSlot.ms = ssr.clientTimeout
+    const ssr = (globalThis as { __SSR__?: Partial<SsrPayload> }).__SSR__ ?? {}
+    /* Seed the per-page __SSR__ stamps into their shared slots before mount: the mount
+       base, app name (default log channel), health payload (so health()'s first probe is
+       warm), and the env-configured RPC timeout (ABIDE_CLIENT_TIMEOUT, shipped per
+       request). Driven by the exhaustive `seedBootState` map so a new boot field can't be
+       stamped server-side and silently dropped here. Without seeding: no mount base,
+       channel 'app', a cold first health probe, and unbounded RPC fetches. */
+    seedBootState(ssr)
     /* The `page` proxy reads route/params/url off the router-updated snapshot. */
-    setPageResolver(() => clientPage.value)
+    pageSlot.resolver = () => clientPage.value
 
     const store = createCacheStore()
-    setCacheStoreResolver(() => store)
-    /* One tab store: cache(fn, { global: true }) shares it, so global is a no-op here. */
-    setGlobalCacheStoreResolver(() => store)
+    cacheStoreSlot.resolver = () => store
+    /* One tab store: cache(fn, { shared: true }) shares it, so shared is a no-op here. */
+    sharedCacheStoreSlot.resolver = () => store
     /* Seed both SSR cache partitions through the one streamed-resolution sink: `ssr.cache`
        (inline — reads settled at render-return, in __SSR__) and `__abideResumeCache` (pending
        {#await} reads whose `__abideResolve(...)` chunks the stream pushed during parse, before

package/src/lib/ui/state.ts

@@ -1,15 +1,42 @@
+import { computed } from './computed.ts'
+import { linked } from './linked.ts'
 import { createSignalNode } from './runtime/createSignalNode.ts'
 import { readNode } from './runtime/readNode.ts'
 import type { State } from './runtime/types/State.ts'
 import { writeNode } from './runtime/writeNode.ts'
+import { scope } from './scope.ts'
+
+/* The imported reactive surface: the `state` callable plus its attached members.
+   `state`/`state.linked`/`state.computed` are the reactive primitives an author
+   imports (`import { state } from '@abide/abide/ui/state'`); the compiler resolves
+   the import binding (alias-safe) and lowers each onto the ambient scope. `.share`/
+   `.shared` are the context seam — the reference store the runtime scope exposes,
+   reached ambiently so a component can pass a named value down its subtree. */
+type StateFn = {
+    /* No-arg form for an undefined initial with a declared type: `state<Foo>()` is
+       `State<Foo | undefined>`. Without it `state<Foo>(undefined)` is an arity/assign
+       error and `state(undefined)` infers `T = undefined` (every `.value` access then
+       narrows to `never`). */
+    <T>(): State<T | undefined>
+    <T>(initial: T, transform?: (next: T, previous: T) => T): State<T>
+    /* A writable cell reseeded from a reactive thunk (`state.linked(() => src())`). */
+    linked: typeof linked
+    /* A read-only cell computed from other cells (`state.computed(() => a() + b())`). */
+    computed: typeof computed
+    /* Puts a named value on the ambient scope, read down the tree by `state.shared`. */
+    share: (key: string, value: unknown) => void
+    /* Reads the closest ancestor scope that shared `key`; undefined if none provided. */
+    shared: <T>(key: string) => T | undefined
+}
 
 /*
 A writable reactive cell — abide's from-scratch reactive primitive, with no
 compiler sigil and no external reactivity-library import. `.value` is a
 plain getter/setter over a signal node, so a read/write shows up as exactly that
-in a stack trace. The compiler enforces scope attachment (bare `state()` is a compile
-error — use `scope().state()`), desugars plain `state(initial)` to a serializable `model`
-doc slot, and keeps `state(initial, transform)` as a `.value` cell; the runtime needs no magic.
+in a stack trace. Imported and called bare (`let count = state(0)`); the compiler
+resolves the `state` import binding (alias-safe), desugars plain `state(initial)` to
+a serializable `model` doc slot, and keeps `state(initial, transform)` as a `.value`
+cell routed onto the ambient scope; the runtime needs no magic.
 
 `transform` is an optional coercion gate on the write path: every `.value =`
 runs it and stores what it returns, with `previous` for clamp-relative writes or
@@ -18,16 +45,7 @@ mirror of `computed`'s write-through `set` — here the value lives in this cell
 the gate *returns* what to store rather than writing an external target. The
 construction `initial` is taken verbatim; the gate runs on writes only.
 */
-/* No-arg form for an undefined initial with a declared type: `state<Foo>()` is
-   `State<Foo | undefined>`. Without it `state<Foo>(undefined)` is an arity/assign
-   error and `state(undefined)` infers `T = undefined` (every `.value` access then
-   narrows to `never`). */
-export function state<T>(): State<T | undefined>
-export function state<T>(initial: T, transform?: (next: T, previous: T) => T): State<T>
-export function state<T>(
-    initial?: T,
-    transform?: (next: T, previous: T) => T,
-): State<T | undefined> {
+function stateCell<T>(initial?: T, transform?: (next: T, previous: T) => T): State<T | undefined> {
     const node = createSignalNode(initial)
     return {
         get value(): T | undefined {
@@ -38,3 +56,16 @@ export function state<T>(
         },
     }
 }
+
+const stateFn = stateCell as StateFn
+stateFn.linked = linked
+stateFn.computed = computed
+/* `.share`/`.shared` route onto the ambient scope, read/written at call time so the
+   state ↔ scope module cycle resolves. */
+stateFn.share = (key: string, value: unknown): void => {
+    scope().share(key, value)
+}
+stateFn.shared = <T>(key: string): T | undefined => scope().shared<T>(key)
+
+// @documentation reactive-state
+export const state = stateFn

package/src/lib/ui/sync.ts

@@ -1,5 +1,6 @@
 import { PATCH_BUS } from './runtime/PATCH_BUS.ts'
 import type { Doc } from './runtime/types/Doc.ts'
+import type { Patch } from './runtime/types/Patch.ts'
 import type { SyncTransport } from './types/SyncTransport.ts'
 
 /*
@@ -17,20 +18,25 @@ this core). Returns a disposer.
 */
 // @documentation plumbing
 export function sync(doc: Doc, transport: SyncTransport): () => void {
-    /* True only while applying a received patch, so its bus echo isn't re-sent. */
-    let applying = false
+    /* The specific inbound patches currently being applied — their own bus echo must not be
+       re-sent. Tracked by IDENTITY (not a blanket `applying` flag): `doc.apply` emits the
+       patch on the bus inside its batch, then flushes effects on batch exit while still
+       synchronously inside this apply. A local effect that writes the doc in reaction emits
+       a DIFFERENT patch during that flush — a genuine new local change peers need — which a
+       blanket flag would wrongly suppress, diverging peers permanently. */
+    const applyingPatches = new Set<Patch>()
 
     const unsubscribeInbound = transport.subscribe((patch) => {
-        applying = true
+        applyingPatches.add(patch)
         try {
             doc.apply(patch)
         } finally {
-            applying = false
+            applyingPatches.delete(patch)
         }
     })
 
     const unsubscribeBus = PATCH_BUS.subscribe((event) => {
-        if (event.doc === doc && !applying) {
+        if (event.doc === doc && !applyingPatches.has(event.patch)) {
             transport.send(event.patch)
         }
     })

package/src/lib/ui/tryEncodeResume.ts

@@ -1,5 +1,5 @@
 import { encodeRefJson } from '../shared/encodeRefJson.ts'
-import type { DeferMarker, ResumeEntry } from './runtime/RESUME.ts'
+import type { ResumeEntry } from './runtime/RESUME.ts'
 
 /* ref-json-encode an await-resume entry, or `undefined` if it can't be serialized.
    encodeRefJson is total (cycles become back-references, functions fold to undefined),
@@ -7,10 +7,7 @@ import type { DeferMarker, ResumeEntry } from './runtime/RESUME.ts'
    entry and warn, so the client re-runs that one branch's promise while every other
    branch stays seeded. Shared by the streaming (`renderToStream`) and buffered/seed
    (`resumeSeedScript`) paths so the serialize-or-refetch policy lives in one place. */
-export function tryEncodeResume(
-    entry: ResumeEntry | DeferMarker,
-    id: number | string,
-): string | undefined {
+export function tryEncodeResume(entry: ResumeEntry, id: number | string): string | undefined {
     try {
         return encodeRefJson(entry)
     } catch (cause) {

package/src/lib/ui/types/Scope.ts

@@ -7,18 +7,22 @@ import type { SyncTransport } from './SyncTransport.ts'
 
 /*
 A lexical scope: the unit that owns a region's reactive data, its lifetime, and
-the capabilities applied to it. Its data surface MIRRORS `Doc` (read/replace/add/
-remove/derive/apply/snapshot) so the compiler can target a scope as a
-component's data binding directly. It nests (`child`/`root`), passes values
-down the tree as context (`share`/`shared`), and carries the capability surface as
-methods so a scope is a passable value: `<Child parentScope={scope} />`.
+the capabilities applied to it. This is the INTERNAL shape — the compiler's lowering
+host and the runtime object; it is no longer the author surface. The author reactive
+surface is the imported `state`/`state.linked`/`state.computed`/`effect` (see
+`state.ts`); the compiler resolves those import bindings and lowers each onto this
+scope (`$$scope().derive`/`.linked`/`.effect`, `state.share`/`.shared` → `share`/
+`shared`). The data surface MIRRORS `Doc` (read/replace/add/remove/derive/apply/
+snapshot) so the compiler can target a scope as a component's data binding directly;
+it nests (`child`/`root`) and passes values down the tree as context (`share`/`shared`).
 
+The reactive primitives and capabilities remain on this internal shape because the
+lowered runtime calls them (`$$scope().linked(...)`, generated undo/persist) — they are
+withdrawn from the AUTHOR-facing public surface (docs/examples), not the runtime object.
 Capabilities route where the scope's changes go: `record()` to an undo journal,
-`persist()` to durable storage, `broadcast()` to peers — declared once, then
-`undo`/`redo` act on a recorded scope. `id` is the scope's identity for the
-boundary-crossing capabilities — `persist()` defaults its key to it. `scope()` is the only user-facing public entry; `effect` is also exported
-but only for generated binding code and the SSR strip (tagged plumbing). The
-`history`/`persist`/`sync` helpers it composes are internal.
+`persist()` to durable storage, `broadcast()` to peers — declared once, then `undo`/
+`redo` act on a recorded scope. The `history`/`persist`/`sync` helpers it composes are
+internal.
 */
 export type Scope = {
     readonly id: string