@abide/abide 0.51.0 → 0.52.0

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

@@ -0,0 +1,19 @@
+import ts from 'typescript'
+
+/*
+Maps a compound-assignment operator to its plain binary counterpart, for lowering
+`x += y` into an unconditional read-combine-write. Logical assignments
+(`||=`/`&&=`/`??=`) lower the same way — the patch/cell write always fires,
+consistent with how `+=` lowers. Shared by lowerDocAccess (the `$$model` write path)
+and renameSignalRefs (the `$$writeCell` linked-cell path) so the two lowerings can't
+drift.
+*/
+export const COMPOUND_ASSIGNMENT_OPERATORS = new Map<ts.SyntaxKind, ts.BinaryOperator>([
+    [ts.SyntaxKind.PlusEqualsToken, ts.SyntaxKind.PlusToken],
+    [ts.SyntaxKind.MinusEqualsToken, ts.SyntaxKind.MinusToken],
+    [ts.SyntaxKind.AsteriskEqualsToken, ts.SyntaxKind.AsteriskToken],
+    [ts.SyntaxKind.SlashEqualsToken, ts.SyntaxKind.SlashToken],
+    [ts.SyntaxKind.BarBarEqualsToken, ts.SyntaxKind.BarBarToken],
+    [ts.SyntaxKind.AmpersandAmpersandEqualsToken, ts.SyntaxKind.AmpersandAmpersandToken],
+    [ts.SyntaxKind.QuestionQuestionEqualsToken, ts.SyntaxKind.QuestionQuestionToken],
+])

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

@@ -56,6 +56,7 @@ export const UI_RUNTIME_IMPORTS: { name: string; specifier: string; alias?: stri
     { name: 'spreadAttrs', specifier: 'ui/dom/spreadAttrs', alias: '$$spreadAttrs' },
     { name: 'readCall', specifier: 'ui/dom/readCall', alias: '$$readCall' },
     { name: 'readCell', specifier: 'ui/dom/readCell', alias: '$$readCell' },
+    { name: 'writeCell', specifier: 'ui/dom/writeCell', alias: '$$writeCell' },
     { name: 'cellPending', specifier: 'ui/dom/cellPending', alias: '$$cellPending' },
     { name: 'withPath', specifier: 'ui/runtime/withPath', alias: '$$withPath' },
     { name: 'settleAsyncCells', specifier: 'ui/settleAsyncCells', alias: '$$settleAsyncCells' },

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

@@ -94,6 +94,14 @@ export function compileShadow(
         watchLocalName,
     } = analyzeScript(scriptBody, scriptStart)
     builder.raw(shadowPreamble(importedReactives))
+    /* Every `computed`/`linked` scope line reads through this: it invokes the seed thunk and
+       unwraps a promise/stream to the value a BARE cell read peeks (ADR-0019/0032) — so an async
+       `computed(await …)` / stream `computed(src)` type-checks as its resolved value, and a sync
+       seed keeps its return type (`Awaited` is identity on a non-thenable). Reserved `$$` name so
+       it can never collide with an author binding; `declare`-only, so it carries no runtime. */
+    builder.raw(
+        'declare function $$cellValue<R>(seed: () => R): R extends AsyncIterable<infer F> ? F : Awaited<R>\n',
+    )
     /* The peek helpers the async-interpolation wrap targets (ADR-0032): `$$peek` unwraps a promise
        sub-expression to its resolved value (`undefined` while pending) and `$$peekStream` reads an
        async iterable's latest frame, so `getFoo()?.name`/`{#if getFoo()}` type-check against the
@@ -395,27 +403,38 @@ function collectReservedNameDiagnostics(
    top-level await transpiles to `await` in a non-async function and breaks the bundle; the
    shadow's render fn is async, so `tsc` alone never flags it (a check/runtime parity gap).
    Stops descending at function boundaries — their own async-ness is the author's concern —
-   and catches both `await expr` and `for await (… of …)`, flagging the `await` keyword. */
+   and catches both `await expr` and `for await (… of …)`, flagging the `await` keyword. A
+   `computed`/`linked` SEED argument is exempt: `wrapSeed` (desugarSignals) lowers a top-level
+   `await` there into an async thunk (`computed(await load())` → `async () => await load()`), so
+   its await runs off the sync build — flagging it would be a false positive. */
 function collectTopLevelAwaitDiagnostics(
     file: ts.SourceFile,
     scriptStart: number,
     diagnostics: ShadowDiagnostic[],
+    bindings: ReactiveImportBindings,
 ): void {
     const message =
         'top-level `await` is not allowed in a `<script>` — the component build runs synchronously. Use `{#await expr}…{:then value}…{/await}` markup for blocking data, or `await` inside an async event handler.'
     const visit = (node: ts.Node): void => {
         /* A nested function introduces its own (possibly async) scope; its awaits are legal. */
-        if (
-            ts.isFunctionDeclaration(node) ||
-            ts.isFunctionExpression(node) ||
-            ts.isArrowFunction(node) ||
-            ts.isMethodDeclaration(node) ||
-            ts.isGetAccessorDeclaration(node) ||
-            ts.isSetAccessorDeclaration(node) ||
-            ts.isConstructorDeclaration(node)
-        ) {
+        if (isFunctionScopeBoundary(node)) {
             return
         }
+        /* A `computed`/`linked` seed becomes an async thunk (`wrapSeed`), so an await in it is
+           legal — visit the callee and any trailing args, but skip the seed (`arguments[0]`). */
+        if (ts.isCallExpression(node) && node.arguments.length > 0) {
+            const callee = resolveReactiveExport(node.expression, bindings)
+            if (callee === 'computed' || callee === 'linked') {
+                visit(node.expression)
+                for (let index = 1; index < node.arguments.length; index++) {
+                    const argument = node.arguments[index]
+                    if (argument !== undefined) {
+                        visit(argument)
+                    }
+                }
+                return
+            }
+        }
         /* The `await` keyword token: the AwaitExpression's first child, or a `for await`'s
            await modifier. */
         const keyword = ts.isAwaitExpression(node)
@@ -449,7 +468,8 @@ function collectNestedScriptAwaitDiagnostics(
         }
         if (node.kind === 'script' && node.loc !== undefined) {
             const file = ts.createSourceFile('nested.ts', node.code, ts.ScriptTarget.Latest, true)
-            collectTopLevelAwaitDiagnostics(file, node.loc, diagnostics)
+            /* A nested script inherits the surface by canonical name (no imports of its own). */
+            collectTopLevelAwaitDiagnostics(file, node.loc, diagnostics, NESTED_REACTIVE_BINDINGS)
         }
         if ('children' in node) {
             collectNestedScriptAwaitDiagnostics(node.children, diagnostics)
@@ -503,7 +523,7 @@ function analyzeScript(scriptBody: string, scriptStart: number): ScriptAnalysis
     collectReservedNameDiagnostics(file, scriptStart, diagnostics)
     /* The leading script runs in the synchronous `build()`, so a top-level await breaks the
        bundle — catch it here with a legible message instead of an opaque transpile error. */
-    collectTopLevelAwaitDiagnostics(file, scriptStart, diagnostics)
+    collectTopLevelAwaitDiagnostics(file, scriptStart, diagnostics, bindings)
     /* A verbatim span: original text + the segment mapping it back, relative to the
        line start (the caller rebases shadowStart onto the running shadow length). */
     const span = (node: ts.Node, prefixLength: number): ScopeLine['segments'][number] => ({
@@ -683,13 +703,71 @@ function scopeLineFor(
             segments: [span(declaration.name, keywordOffset)],
         })
     }
-    const prefix = `${keyword} ${name}${annotation} = (`
+    /* Mirror `wrapSeed` (desugarSignals): a bare (non-thunk) seed is normalised to `() => (seed)`,
+       made ASYNC when it carries a top-level `await` — so `computed(await load())` projects as a
+       legal async thunk instead of a raw top-level await (`(await load())()` — a build-breaker that
+       also mis-called the resolved value). A literal thunk passes through unchanged. `$$cellValue`
+       then invokes it and unwraps a promise/stream to the value a bare read peeks, so an async or
+       stream seed types as its RESOLVED value (`Promise<T>` → `T`) rather than the raw promise. */
+    const fnIsThunk = ts.isArrowFunction(fn) || ts.isFunctionExpression(fn)
+    const wrapPrefix = fnIsThunk ? '' : seedIsAsync(fn) ? 'async () => (' : '() => ('
+    const wrapSuffix = fnIsThunk ? '' : ')'
+    const prefix = `${keyword} ${name}${annotation} = $$cellValue(${wrapPrefix}`
     return withCalleeRef({
-        text: `${prefix}${verbatim(fn)})();`,
+        text: `${prefix}${verbatim(fn)}${wrapSuffix});`,
         segments: [span(declaration.name, keywordOffset), span(fn, prefix.length)],
     })
 }
 
+/* True for a `computed`/`linked` seed that `wrapSeed` (desugarSignals) turns into an ASYNC thunk —
+   a thunk the author wrote `async`, or a bare seed carrying a top-level `await` (`computed(await
+   x)`). The shadow must agree so it unwraps the promise to the resolved value AND so the top-level
+   await scan spares the seed. Stops at function boundaries — an inner `async` callback is its own
+   scope, mirroring `hasTopLevelAwait`. */
+function seedIsAsync(seed: ts.Expression): boolean {
+    if (ts.isArrowFunction(seed) || ts.isFunctionExpression(seed)) {
+        return (
+            ts
+                .getModifiers(seed)
+                ?.some((modifier) => modifier.kind === ts.SyntaxKind.AsyncKeyword) ?? false
+        )
+    }
+    return expressionHasTopLevelAwait(seed)
+}
+
+/* True when `node` contains an `await` at its own top level — not nested inside a function. The
+   seed-classification counterpart to `collectTopLevelAwaitDiagnostics`' walk; kept local so the
+   shadow doesn't reach into `desugarSignals`' private `hasTopLevelAwait`. */
+function expressionHasTopLevelAwait(node: ts.Node): boolean {
+    let found = false
+    const visit = (child: ts.Node): void => {
+        if (found || isFunctionScopeBoundary(child)) {
+            return
+        }
+        if (ts.isAwaitExpression(child)) {
+            found = true
+            return
+        }
+        ts.forEachChild(child, visit)
+    }
+    visit(node)
+    return found
+}
+
+/* A node that opens its own (possibly async) function scope — awaits inside it are the author's
+   concern, so both the top-level-await walk and the seed classifier stop descending here. */
+function isFunctionScopeBoundary(node: ts.Node): boolean {
+    return (
+        ts.isFunctionDeclaration(node) ||
+        ts.isFunctionExpression(node) ||
+        ts.isArrowFunction(node) ||
+        ts.isMethodDeclaration(node) ||
+        ts.isGetAccessorDeclaration(node) ||
+        ts.isSetAccessorDeclaration(node) ||
+        ts.isConstructorDeclaration(node)
+    )
+}
+
 /* Whether any ELEMENT in the tree carries an `attach` — gates emitting the DOM-typed
    attachment aliases. All nested content (block bodies, await/switch branches, snippet
    bodies) routes through `children`, so a recursive `children` walk is complete. */

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

@@ -1,5 +1,6 @@
 import ts from 'typescript'
 import { escapeKey } from '../runtime/escapeKey.ts'
+import { COMPOUND_ASSIGNMENT_OPERATORS } from './COMPOUND_ASSIGNMENT_OPERATORS.ts'
 
 /*
 The linchpin compiler pass. Rewrites idiomatic data access on a reactive document
@@ -30,9 +31,6 @@ used as an index lowers too. Exposed as `docAccessTransformer` (a
 /* A path segment is either a literal key or a runtime expression (a dynamic index). */
 type Segment = { kind: 'literal'; value: string } | { kind: 'expression'; node: ts.Expression }
 
-/* Maps a compound-assignment operator to its plain binary counterpart. Logical
-   assignments (`||=`/`&&=`/`??=`) lower to an unconditional replace of the
-   combined value — consistent with how `+=` lowers (the patch always writes). */
 /* Methods that mutate a doc-rooted container in place — Array, Map and Set (the three
    mutable containers the doc codec serializes). Called on a doc value these can't lower to
    a bare `readCall` (which would mutate the live tree by reference and never emit a patch —
@@ -57,16 +55,6 @@ const MUTATING_CONTAINER_METHODS = new Set([
     'clear',
 ])
 
-const COMPOUND_OPERATORS = new Map<ts.SyntaxKind, ts.BinaryOperator>([
-    [ts.SyntaxKind.PlusEqualsToken, ts.SyntaxKind.PlusToken],
-    [ts.SyntaxKind.MinusEqualsToken, ts.SyntaxKind.MinusToken],
-    [ts.SyntaxKind.AsteriskEqualsToken, ts.SyntaxKind.AsteriskToken],
-    [ts.SyntaxKind.SlashEqualsToken, ts.SyntaxKind.SlashToken],
-    [ts.SyntaxKind.BarBarEqualsToken, ts.SyntaxKind.BarBarToken],
-    [ts.SyntaxKind.AmpersandAmpersandEqualsToken, ts.SyntaxKind.AmpersandAmpersandToken],
-    [ts.SyntaxKind.QuestionQuestionEqualsToken, ts.SyntaxKind.QuestionQuestionToken],
-])
-
 export function docAccessTransformer(docName: string): ts.TransformerFactory<ts.SourceFile> {
     return (context) => (root) => {
         /* Collects the path of an access chain rooted at `docName`, visiting any
@@ -114,7 +102,7 @@ export function docAccessTransformer(docName: string): ts.TransformerFactory<ts.
                             ts.visitNode(node.right, visit) as ts.Expression,
                         ])
                     }
-                    const binary = COMPOUND_OPERATORS.get(operator)
+                    const binary = COMPOUND_ASSIGNMENT_OPERATORS.get(operator)
                     if (binary) {
                         const next = ts.factory.createBinaryExpression(
                             docCall(docName, 'read', [buildPath(segments)]),

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

@@ -117,9 +117,14 @@ export function lowerScript(
         ...computedNames,
         ...cellReadNames,
     ])
+    /* `wrapReactionCellSources` only folds `watch(cell, …)` calls, so it's a pure
+       identity walk when the script imports no `watch` (the common case) — skip the
+       extra full-tree pass entirely then. */
+    const reactionTransforms =
+        watchLocalNames.size > 0 ? [wrapReactionCellSources(cellNames, watchLocalNames)] : []
     const result = ts.transform(source, [
         transformer,
-        wrapReactionCellSources(cellNames, watchLocalNames),
+        ...reactionTransforms,
         signalRefsTransformer(
             stateNames,
             derivedNames,

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

@@ -1,4 +1,5 @@
 import ts from 'typescript'
+import { COMPOUND_ASSIGNMENT_OPERATORS } from './COMPOUND_ASSIGNMENT_OPERATORS.ts'
 
 /*
 Rewrites references to a component's signal bindings into the document form the
@@ -21,6 +22,21 @@ Exposed as a `ts.TransformerFactory`, so the script pipeline can chain it with
 `docAccessTransformer` over a SINGLE parsed tree (see `lowerScript`) instead of
 print-then-reparse between passes.
 */
+/* `$$readCell(name)` — the unified cell read (peek async / `.value` sync). */
+function cellReadCall(name: string): ts.Expression {
+    return ts.factory.createCallExpression(ts.factory.createIdentifier('$$readCell'), undefined, [
+        ts.factory.createIdentifier(name),
+    ])
+}
+
+/* `$$writeCell(name, value)` — the unified cell write (`.value =` sync / `.set(...)` async). */
+function writeCellCall(name: string, value: ts.Expression): ts.Expression {
+    return ts.factory.createCallExpression(ts.factory.createIdentifier('$$writeCell'), undefined, [
+        ts.factory.createIdentifier(name),
+        value,
+    ])
+}
+
 export function signalRefsTransformer(
     stateNames: ReadonlySet<string>,
     derivedNames: ReadonlySet<string>,
@@ -87,6 +103,55 @@ export function signalRefsTransformer(
                 if (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) {
                     return node
                 }
+                /* An assignment to a `linked` cell (a `cellReadNames` name) — its read form
+                   is `$$readCell(name)`, a call, so it can't sit on an assignment's left.
+                   Lower the write to `$$writeCell(name, value)`, which dispatches `.value =`
+                   (sync `State`) vs `.set(...)` (async `AsyncState`). A compound/logical
+                   assignment folds the current value in through the read form. `state` and
+                   `derived` writes stay on their own paths (`$$model.replace` / `.value =`). */
+                if (
+                    ts.isBinaryExpression(node) &&
+                    ts.isIdentifier(node.left) &&
+                    cellReadNames.has(node.left.text) &&
+                    !shadowed.has(node.left.text)
+                ) {
+                    const target = node.left.text
+                    const right = ts.visitNode(node.right, visit) as ts.Expression
+                    if (node.operatorToken.kind === ts.SyntaxKind.EqualsToken) {
+                        return writeCellCall(target, right)
+                    }
+                    const binary = COMPOUND_ASSIGNMENT_OPERATORS.get(node.operatorToken.kind)
+                    if (binary !== undefined) {
+                        return writeCellCall(
+                            target,
+                            ts.factory.createBinaryExpression(cellReadCall(target), binary, right),
+                        )
+                    }
+                }
+                /* `draft++` / `++draft` / `draft--` on a `linked` cell → a `$$writeCell` of the
+                   stepped value, mirroring the `+= 1` shape (the bare `++` would otherwise land
+                   on `$$readCell(draft)`, an invalid lvalue). */
+                if (
+                    (ts.isPostfixUnaryExpression(node) || ts.isPrefixUnaryExpression(node)) &&
+                    (node.operator === ts.SyntaxKind.PlusPlusToken ||
+                        node.operator === ts.SyntaxKind.MinusMinusToken) &&
+                    ts.isIdentifier(node.operand) &&
+                    cellReadNames.has(node.operand.text) &&
+                    !shadowed.has(node.operand.text)
+                ) {
+                    const step =
+                        node.operator === ts.SyntaxKind.PlusPlusToken
+                            ? ts.SyntaxKind.PlusToken
+                            : ts.SyntaxKind.MinusToken
+                    return writeCellCall(
+                        node.operand.text,
+                        ts.factory.createBinaryExpression(
+                            cellReadCall(node.operand.text),
+                            step,
+                            ts.factory.createNumericLiteral(1),
+                        ),
+                    )
+                }
                 /* Shorthand `{ count }` → `{ count: $$model.count }` / `{ total: total.value }`,
                    unless a nearer scope shadows the name. */
                 if (ts.isShorthandPropertyAssignment(node) && !shadowed.has(node.name.text)) {

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

@@ -46,6 +46,23 @@ export function wrapReactionCellSources(
         return false
     }
 
+    /* The inert footgun: a member access (`s.foo`, `s['foo']`) whose base is a known cell.
+       abide has no per-property cells — the whole object lives in the one cell — so a member
+       expression is read ONCE as a plain value (outside any tracking scope) and handed to the
+       runtime as a dead value: nothing subscribes, the reaction never fires. It can't be folded
+       like a bare cell (a member access isn't a whole-cell subscription), so return the base
+       name to warn on and leave the source for the author to rewrite. */
+    function cellMemberBase(source: ts.Expression): string | undefined {
+        if (
+            (ts.isPropertyAccessExpression(source) || ts.isElementAccessExpression(source)) &&
+            ts.isIdentifier(source.expression) &&
+            cellNames.has(source.expression.text)
+        ) {
+            return source.expression.text
+        }
+        return undefined
+    }
+
     return (context) => (root) => {
         function visit(node: ts.Node): ts.Node {
             const [sourceArg, handlerArg] = ts.isCallExpression(node) ? node.arguments : []
@@ -78,6 +95,21 @@ export function wrapReactionCellSources(
                 )
                 return ts.factory.createCallExpression(node.expression, undefined, [thunk])
             }
+            /* Warn on the inert member-expression form `watch(s.foo, handler)` — it looks valid but
+               subscribes to nothing (see `cellMemberBase`). Not foldable; the fix is the author's. */
+            if (
+                ts.isCallExpression(node) &&
+                ts.isIdentifier(node.expression) &&
+                watchLocalNames.has(node.expression.text) &&
+                node.arguments.length === 2 &&
+                sourceArg !== undefined &&
+                cellMemberBase(sourceArg) !== undefined
+            ) {
+                const sourceText = sourceArg.getText(root)
+                console.warn(
+                    `[abide] \`watch(${sourceText}, …)\` does not track \`${sourceText}\` — a member access on a cell is read once as a plain value (abide has no per-property cells), so the reaction is inert. Wrap it in a thunk (\`watch(() => …(${sourceText}))\`) or watch the whole cell (\`watch(${cellMemberBase(sourceArg)}, v => …)\`).`,
+                )
+            }
             return ts.visitEachChild(node, visit, context)
         }
         return ts.visitNode(root, visit) as ts.SourceFile

package/src/lib/ui/createScope.ts

@@ -1,8 +1,11 @@
+import { decodeRefJson } from '../shared/decodeRefJson.ts'
+import { docSnapshotsSlot } from '../shared/docSnapshotsSlot.ts'
 import { computed } from './computed.ts'
 import { effect } from './effect.ts'
 import { linked } from './linked.ts'
 import { CURRENT_PATH } from './runtime/CURRENT_PATH.ts'
 import { createDoc } from './runtime/createDoc.ts'
+import { DOC_SEED } from './runtime/DOC_SEED.ts'
 import type { Cell } from './runtime/types/Cell.ts'
 import type { Doc } from './runtime/types/Doc.ts'
 import { state } from './state.ts'
@@ -43,6 +46,33 @@ export function createScope(
             : parent === undefined
               ? `scope-${nextId++}`
               : `${parent.id}.${nextId++}`
+    /* Doc-state warm-seed (client hydration only): a plain `state(initial)` re-runs its initializer
+       on the client, so a uuid/timestamp/random would diverge from the SSR HTML. The server snapshot
+       for this scope's render-path id is decoded here and consumed by `replace` on each slot's FIRST
+       write (the eager init), keeping the server value while the throwaway init is discarded. One-shot
+       — deleted on read so an SPA re-nav to the same path re-inits fresh; empty on the server. */
+    let pendingSeed: Map<string, unknown> | undefined
+    /* `DOC_SEED` is populated only on the client by `startClient` (empty on the server), so the read
+       needs no window guard — it mirrors the async-cell warm read. */
+    const encodedSeed = DOC_SEED[id]
+    if (encodedSeed !== undefined) {
+        delete DOC_SEED[id]
+        try {
+            pendingSeed = new Map(
+                Object.entries(decodeRefJson(encodedSeed) as Record<string, unknown>),
+            )
+        } catch {
+            /* A corrupt seed falls back to a cold init — the same failure mode as a warm cell. */
+        }
+    }
+    /* Server: register this scope's doc snapshot for the `__SSR__.docs` warm-seed, keyed by its
+       render-path id. Lazy — taken at render-return, after the synchronous state inits have run.
+       Only a rendered scope (stable render-path id) registers; a detached scope (counter id) and the
+       client never do. An empty/unused doc is dropped at the stamp, so a stateless scope costs only
+       the push. */
+    if (typeof window === 'undefined' && renderPath !== '') {
+        docSnapshotsSlot.get()?.entries.push({ id, take: () => document?.snapshot() })
+    }
     /* Adopted build teardowns (the reactivity stopper from the mount core). Disposed
        first and in reverse on teardown — so the one `dispose` runs the order the call sites
        hand-composed as `stop(); lexical.dispose()`. */
@@ -65,7 +95,18 @@ export function createScope(
         nextCellIndex: () => cellIndex++,
         parent,
         read: (path) => data().read(path),
-        replace: (path, value) => data().replace(path, value),
+        /* Consume-once seed adoption: on the client's hydrating build, the FIRST write to each seeded
+           slot is the eager `state(initial)` init — swap in the server value and drop the seed, so a
+           `state(uuid())` keeps the SSR value while its throwaway fresh init is discarded. Every later
+           write (a real reassignment) and every non-seeded path passes straight through. */
+        replace: (path, value) => {
+            if (pendingSeed?.has(path)) {
+                const seeded = pendingSeed.get(path)
+                pendingSeed.delete(path)
+                return data().replace(path, seeded)
+            }
+            return data().replace(path, value)
+        },
         add: (path, value) => data().add(path, value),
         remove: (path) => data().remove(path),
         apply: (patch) => data().apply(patch),

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
+}