@abide/abide 0.50.1 → 0.52.0

package/src/lib/ui/dom/assertClaimedText.ts

@@ -1,3 +1,6 @@
+import { CURRENT_PATH } from '../runtime/CURRENT_PATH.ts'
+import { reportHydrationDivergence } from '../runtime/reportHydrationDivergence.ts'
+
 /*
 A text claim that MUST match the server's rendered text. On hydrate,
 appendStatic/appendText adopt a merged SSR text node and split it at the CLIENT
@@ -12,9 +15,16 @@ the following siblings' text AFTER it, so the value is exactly the leading slice
 mismatch means SSR and the client build disagree on the text here.
 */
 export function assertClaimedText(node: Text, value: string): void {
-    if (!node.data.startsWith(value)) {
-        throw new Error(
-            `[abide] hydration desync: expected server text beginning with ${JSON.stringify(value)} here, but the server DOM had ${JSON.stringify(node.data)} — SSR markup and the client build disagree on the text at this position.`,
-        )
+    if (node.data.startsWith(value)) {
+        return
+    }
+    /* Report on the `hydrate` channel with the render-path. With the channel on, keep hydrating
+       (re-split proceeds below on the client length) so one reload surfaces every text divergence;
+       off, the hard throw stays the default. A text miss is cursor-safe to continue past. */
+    if (!reportHydrationDivergence('text desync', { expected: value, server: node.data })) {
+        return
     }
+    throw new Error(
+        `[abide] hydration desync at ${CURRENT_PATH.current || '(root)'}: expected server text beginning with ${JSON.stringify(value)} here, but the server DOM had ${JSON.stringify(node.data)} — SSR markup and the client build disagree on the text at this position.`,
+    )
 }

package/src/lib/ui/dom/attr.ts

@@ -1,4 +1,15 @@
 import { effect } from '../effect.ts'
+import { RENDER } from '../runtime/RENDER.ts'
+import { reportHydrationDivergence } from '../runtime/reportHydrationDivergence.ts'
+
+/* The attribute string an element carries for `value`, or `null` when absent — the present/absent +
+   stringify semantics below, factored so the hydration compare and the write agree exactly. */
+function attributeText(value: unknown): string | null {
+    if (value === false || value === null || value === undefined) {
+        return null
+    }
+    return value === true ? '' : String(value)
+}
 
 /*
 Binds an element attribute to `read()`. A boolean true sets the bare attribute,
@@ -8,12 +19,24 @@ changed attribute touches the DOM.
 */
 // @documentation plumbing
 export function attr(element: Element, name: string, read: () => unknown): void {
+    /* Captured at bind time (inside the hydrating build) so the first effect run can compare the
+       server-rendered attribute before overwriting it — an attribute divergence is otherwise
+       invisible, since the effect always overwrites. */
+    let hydrating = RENDER.hydration !== undefined
     effect(() => {
         const value = read()
-        if (value === false || value === null || value === undefined) {
+        const next = attributeText(value)
+        if (hydrating) {
+            hydrating = false
+            const server = element.getAttribute(name)
+            if (server !== next) {
+                reportHydrationDivergence(`attr "${name}" desync`, { server, client: next })
+            }
+        }
+        if (next === null) {
             element.removeAttribute(name)
         } else {
-            element.setAttribute(name, value === true ? '' : String(value))
+            element.setAttribute(name, next)
         }
     })
 }

package/src/lib/ui/dom/writeCell.ts

@@ -0,0 +1,22 @@
+import { isAsyncCell } from '../../shared/isAsyncCell.ts'
+import type { AsyncState } from '../../shared/types/AsyncState.ts'
+
+/*
+Unified write for a `linked` reference the compiler lowers to `$$writeCell(NAME, value)`
+from an author assignment (`draft = x`, `draft += 1`, `draft++`). The read side is
+`$$readCell` — a call, so not an assignable target — which is why an assignment to a
+`linked` binding needs its own lowering. A `linked` cell is a writable `State` for a
+sync seed (write `.value`) or a writable `AsyncState` for an async/stream seed (write
+`.set(value)`, which latches until the next reseed); one write shape covers both, so
+codegen never branches on the seed kind. Returns `value` so the lowered assignment still
+evaluates to the written value in expression position (`a = b = draft = x`).
+*/
+// @documentation plumbing
+export function writeCell(cell: unknown, value: unknown): unknown {
+    if (isAsyncCell(cell)) {
+        ;(cell as AsyncState<unknown>).set(value)
+    } else {
+        ;(cell as { value: unknown }).value = value
+    }
+    return value
+}

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

@@ -0,0 +1,11 @@
+/* The doc-state warm-seed manifest: an SSR-captured reactive-document snapshot, keyed by its
+   scope's serialization-stable render-path id, as a ref-json-encoded STRING (decoded at the read
+   site in `createScope`). `startClient` drains `__SSR__.docs` into here before mount; a hydrating
+   scope reads its key to seed a plain `state(initial)` to the SERVER value instead of the fresh
+   init — a uuid/timestamp/random otherwise diverges from the SSR HTML. Backed by
+   `globalThis.__abideDocs` so an inline pre-bundle script and the framework share one store —
+   whoever runs first creates it, the other adopts the same reference (mirrors CELL_SEED). */
+const globalScope = globalThis as { __abideDocs?: Record<string, string> }
+globalScope.__abideDocs ??= {}
+
+export const DOC_SEED: Record<string, string> = globalScope.__abideDocs

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

@@ -1,5 +1,7 @@
+import { CURRENT_PATH } from './CURRENT_PATH.ts'
 import { claimChild } from './claimChild.ts'
 import type { RENDER } from './RENDER.ts'
+import { reportHydrationDivergence } from './reportHydrationDivergence.ts'
 
 /*
 A hydration claim that MUST succeed. Like `claimChild`, but throws a structural error
@@ -18,8 +20,11 @@ export function claimExpected(
 ): Node {
     const node = claimChild(hydration, parent)
     if (node === null) {
+        /* Name where first on the `hydrate` channel (return ignored — a missing structural node
+           desyncs the claim cursor, so unlike a text miss this can't safely continue) then throw. */
+        reportHydrationDivergence('structure desync', { expected })
         throw new Error(
-            `[abide] hydration desync: expected ${expected} here, but the server DOM had no matching node — SSR markup and the client build disagree on structure at this position.`,
+            `[abide] hydration desync at ${CURRENT_PATH.current || '(root)'}: expected ${expected} here, but the server DOM had no matching node — SSR markup and the client build disagree on structure at this position.`,
         )
     }
     return node

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

@@ -0,0 +1,30 @@
+import { log } from '../../shared/log.ts'
+import type { ChannelLog } from '../../shared/types/ChannelLog.ts'
+import { CURRENT_PATH } from './CURRENT_PATH.ts'
+
+/* The `hydrate` diagnostic channel. `createChannelLog` attaches a live `enabled()` (re-read per
+   call, so toggling `abide-debug` in devtools takes effect without reload) that the public
+   `ChannelLog` type narrows away — reach it here in the one place that needs it. The channel is
+   silent unless DEBUG/`abide-debug` matches `hydrate`. */
+const hydrateChannel = log.channel('hydrate') as ChannelLog & { enabled(): boolean }
+
+/*
+Reports an SSR↔client hydration divergence on the DEBUG-gated `hydrate` channel, tagged with the
+ambient render-path of the enclosing component/branch/row (`CURRENT_PATH` is coarse — it does not
+descend to the individual node/attribute, so the path locates the component, the detail names the
+value). Returns whether the caller should STILL THROW: with the channel off it returns `true`, so
+the caller's hard throw stays the default and a real desync fails loudly; with the channel on it
+warns and returns `false`, so the caller can keep hydrating and one reload surfaces EVERY
+divergence instead of aborting at the first. Structural callers ignore the return (continuing past
+a missing node desyncs the claim cursor) and throw regardless — the warn just names where first.
+*/
+export function reportHydrationDivergence(
+    summary: string,
+    detail: Record<string, unknown>,
+): boolean {
+    if (!hydrateChannel.enabled()) {
+        return true
+    }
+    hydrateChannel.warn(`${summary} at ${CURRENT_PATH.current || '(root)'}`, detail)
+    return false
+}

package/src/lib/ui/startClient.ts

@@ -1,3 +1,5 @@
+import { applyCacheStalenessLocally } from '../shared/applyCacheStalenessLocally.ts'
+import { cacheStalenessSlot } from '../shared/cacheStalenessSlot.ts'
 import { cacheStoreSlot } from '../shared/cacheStoreSlot.ts'
 import { createCacheStore } from '../shared/createCacheStore.ts'
 import { pageSlot } from '../shared/pageSlot.ts'
@@ -8,9 +10,11 @@ import { probeNavigation } from './probeNavigation.ts'
 import { router } from './router.ts'
 import { CELL_SEED } from './runtime/CELL_SEED.ts'
 import { clientPage } from './runtime/clientPage.ts'
+import { DOC_SEED } from './runtime/DOC_SEED.ts'
 import type { RouteLoader } from './runtime/types/RouteLoader.ts'
 import { seedBootState } from './seedBootState.ts'
 import { seedStreamedResolution } from './seedStreamedResolution.ts'
+import { subscribeCacheStaleness } from './subscribeCacheStaleness.ts'
 
 /*
 The official abide-ui client entry. Reads the server's `window.__SSR__` payload,
@@ -49,6 +53,10 @@ export function startClient(
     cacheStoreSlot.resolver = () => store
     /* One tab store: cache(fn, { shared: true }) shares it, so shared is a no-op here. */
     sharedCacheStoreSlot.resolver = () => store
+    /* invalidate()/refresh() apply to THIS tab's cache (the server entry installs a
+       broadcaster instead — the ADR-0041 side-swap). Same function as the slot fallback so
+       the local-apply path can't diverge. */
+    cacheStalenessSlot.resolver = () => applyCacheStalenessLocally
     /* 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
@@ -66,6 +74,12 @@ export function startClient(
     if (ssr.cells !== undefined) {
         Object.assign(CELL_SEED, ssr.cells)
     }
+    /* Seed the doc-state warm partition into DOC_SEED before mount: a hydrating `createScope` reads
+       its render-path key to adopt the SSR doc snapshot, so a plain `state(initial)` keeps the server
+       value (the consume-once swap in `scope.replace`) instead of re-running a divergent init. */
+    if (ssr.docs !== undefined) {
+        Object.assign(DOC_SEED, ssr.docs)
+    }
     /* Keep the cache channel live past boot: replace the head's buffering collector with
        the store-connected sink so a post-boot resolution — the inline doc-stream cache
        script — seeds the store through `seedStreamedResolution` directly instead of pushing
@@ -74,5 +88,12 @@ export function startClient(
     ;(globalThis as { __abideResolve?: (resolution: StreamedResolution) => void }).__abideResolve =
         seedStreamedResolution
 
-    return router(target, routes, layoutRoutes, probeNavigation)
+    /* Subscribe to the reserved cache-staleness pipe (ADR-0041) AFTER seeding, so a server
+       broadcast drops/refetches this tab's freshly-hydrated cache — live-only, never replay. */
+    const disposeStaleness = subscribeCacheStaleness()
+    const disposeRouter = router(target, routes, layoutRoutes, probeNavigation)
+    return () => {
+        disposeStaleness()
+        disposeRouter()
+    }
 }

package/src/lib/ui/subscribeCacheStaleness.ts

@@ -0,0 +1,85 @@
+import { abideLog } from '../shared/abideLog.ts'
+import { CACHE_STALENESS_SOCKET } from '../shared/CACHE_STALENESS_SOCKET.ts'
+import { cache } from '../shared/cache.ts'
+import { matcherFromEnvelope } from '../shared/matcherFromEnvelope.ts'
+import { SocketDisconnectedError } from '../shared/SocketDisconnectedError.ts'
+import type { CacheStalenessFrame } from '../shared/types/CacheStalenessFrame.ts'
+import type { Socket } from '../shared/types/Socket.ts'
+import { socketProxy } from './socketProxy.ts'
+
+/*
+The client half of the cross-client staleness broadcast (ADR-0041): every tab
+subscribes to the reserved __abide/cache socket at boot and applies each frame to
+its own cache. A frame rebuilds the entry predicate via matcherFromEnvelope and
+drives the SAME store loop a local invalidate()/refresh() does
+(cache.invalidateMatching / cache.refreshMatching), so wire-driven and local applies
+can't diverge.
+
+LIVE-ONLY, never replay: bare iteration (replay 0) on both boot and reconnect — a
+client applies only frames published while it is connected. The reserved topic keeps
+no tail, so there is nothing to catch up on; a client offline when a frame was
+published misses it and falls back to SWR staleness. Applies are idempotent, so
+correctness has no dependency on frame ordering.
+
+No-op on the server (no window): the broadcast is the server's job, not something it
+consumes. Returns a disposer that stops the loop and closes the subscription.
+*/
+export function subscribeCacheStaleness(injectedSocket?: Socket<CacheStalenessFrame>): () => void {
+    if (typeof window === 'undefined') {
+        return () => undefined
+    }
+    /* Default to the browser channel proxy; tests inject a socket over their own channel. */
+    const socket = injectedSocket ?? socketProxy<CacheStalenessFrame>(CACHE_STALENESS_SOCKET)
+    const controller = new AbortController()
+    /* `let`: a reconnect swaps in a fresh live iterator after a transport loss. */
+    let iterator = socket[Symbol.asyncIterator]()
+    ;(async () => {
+        while (!controller.signal.aborted) {
+            let next: IteratorResult<CacheStalenessFrame>
+            try {
+                next = await iterator.next()
+            } catch (error) {
+                if (controller.signal.aborted) {
+                    return
+                }
+                /* Transport loss: re-open a fresh LIVE subscription (no replay) and keep going. */
+                if (error instanceof SocketDisconnectedError) {
+                    iterator = socket[Symbol.asyncIterator]()
+                    continue
+                }
+                abideLog.error(error)
+                return
+            }
+            if (controller.signal.aborted || next.done === true) {
+                return
+            }
+            /* One malformed frame must not tear down the live pipe: a throw from decode/apply
+               is logged and swallowed so every subsequent frame still delivers. Frames come
+               only from the trusted server (clientPublish is false), so this is defense in
+               depth, not an expected path. */
+            try {
+                applyFrame(next.value)
+            } catch (error) {
+                abideLog.error(error)
+            }
+        }
+    })()
+    return () => {
+        controller.abort()
+        iterator.return?.(undefined)?.catch(() => undefined)
+    }
+}
+
+/* Applies one decoded frame to this tab's cache via the shared apply-by-matcher seam. */
+function applyFrame(frame: CacheStalenessFrame): void {
+    const matches = matcherFromEnvelope(frame)
+    /* The tripwire label + the rpc-error-registry prefix, mirroring what a local selector
+       derives: a tag frame has no key prefix to clear. */
+    const label = frame.mode === 'tags' ? `tags: ${frame.tags.join(', ')}` : frame.match
+    const prefix = frame.mode === 'tags' ? undefined : frame.match
+    if (frame.op === 'invalidate') {
+        cache.invalidateMatching(matches, label, prefix)
+    } else {
+        cache.refreshMatching(matches, label, prefix)
+    }
+}

package/src/serverEntry.ts

@@ -26,11 +26,14 @@ import { shell } from './_virtual/shell.ts'
 import { sockets } from './_virtual/sockets.ts'
 import { exitWithParent } from './lib/bundle/exitWithParent.ts'
 import { loadEnvFromBinaryDir } from './lib/cli/loadEnvFromBinaryDir.ts'
+import { broadcastCacheStaleness } from './lib/server/runtime/cacheStalenessBroadcaster.ts'
 import { createServer } from './lib/server/runtime/createServer.ts'
 import { requestContext } from './lib/server/runtime/requestContext.ts'
 import { resolvePageSnapshot } from './lib/server/runtime/resolvePageSnapshot.ts'
+import { cacheStalenessSlot } from './lib/shared/cacheStalenessSlot.ts'
 import { cacheStoreSlot } from './lib/shared/cacheStoreSlot.ts'
 import { createCacheStore } from './lib/shared/createCacheStore.ts'
+import { docSnapshotsSlot } from './lib/shared/docSnapshotsSlot.ts'
 import { loadEnvFromDataDir } from './lib/shared/loadEnvFromDataDir.ts'
 import { pageSlot } from './lib/shared/pageSlot.ts'
 import { pendingAsyncCellsSlot } from './lib/shared/pendingAsyncCellsSlot.ts'
@@ -79,6 +82,13 @@ sharedCacheStoreSlot.resolver = () => sharedCacheStore
 
 cacheStoreSlot.resolver = () => requestContext.getStore()?.cache ?? sharedCacheStore
 
+/*
+Server-side invalidate()/refresh() broadcast to every connected client instead of
+mutating a throwaway request store (ADR-0041). The broadcaster is imported ONLY here
+so its server socket code never enters the client reachability graph.
+*/
+cacheStalenessSlot.resolver = () => broadcastCacheStaleness
+
 /* One process-wide fallback list for reads with no request in flight (boot/cron/socket) —
    real requests each carry their own `pendingAsyncCells`, so the SSR barrier drains a
    per-request list and concurrent renders never cross-contaminate. */
@@ -89,6 +99,8 @@ const sharedResolvedCells = { entries: [] }
 resolvedCellsSlot.resolver = () => requestContext.getStore()?.resolvedCells ?? sharedResolvedCells
 const sharedStreamedCells = { entries: [] }
 streamedCellsSlot.resolver = () => requestContext.getStore()?.streamedCells ?? sharedStreamedCells
+const sharedDocSnapshots = { entries: [] }
+docSnapshotsSlot.resolver = () => requestContext.getStore()?.docSnapshots ?? sharedDocSnapshots
 
 pageSlot.resolver = resolvePageSnapshot