@abide/abide 0.50.1 → 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

@@ -39,9 +39,6 @@ function shadowPreamble(importedReactives: ReadonlySet<string>): string {
         importedReactives.has('effect')
             ? undefined
             : `import { effect } from '${ABIDE_PACKAGE_NAME}/ui/effect'`,
-        importedReactives.has('watch')
-            ? undefined
-            : `import { watch } from '${ABIDE_PACKAGE_NAME}/ui/watch'`,
         `import { snippet } from '${ABIDE_PACKAGE_NAME}/shared/snippet'`,
         `import { scope } from '${ABIDE_PACKAGE_NAME}/ui/currentScope'`,
         importedReactives.has('state')
@@ -86,9 +83,25 @@ export function compileShadow(
     const scriptStart = leadingScript ? source.indexOf('>', leadingScript.index) + 1 : 0
     const templateStart = leadingScript ? (leadingScript.index ?? 0) + leadingScript[0].length : 0
 
-    const { imports, types, scope, propsShapes, diagnostics, importedReactives, propsLocalName } =
-        analyzeScript(scriptBody, scriptStart)
+    const {
+        imports,
+        types,
+        scope,
+        propsShapes,
+        diagnostics,
+        importedReactives,
+        propsLocalName,
+        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
@@ -112,15 +125,30 @@ export function compileShadow(
     if (propsLocalName !== undefined) {
         builder.raw(`declare function ${propsLocalName}<T = {}>(): (${propsType}) & T\n`)
     }
+    /* `watch` is re-typed with a trailing value-source overload: the real overloads
+       (`State`/socket/rpc/thunk) intersected with `<T>(source: T, handler: (value: T) => void)`.
+       A `watch(cell, handler)` source is projected to the cell's VALUE type (like every read),
+       so it never matches the real `State<T>` overload — the value-source form catches it and
+       types `handler`'s parameter as that value. Ordered after the real overloads (intersection
+       left-to-right), so a socket/rpc source still resolves to its specific frame/return type.
+       The real type is referenced through `typeof import(...)` (no value import to keep live), and
+       the binding uses the author's local alias — or the `watch` fallback for a bare/nested use
+       that isn't author-imported. */
+    const watchSpecifier = `${ABIDE_PACKAGE_NAME}/ui/watch`
+    builder.raw(
+        `declare const ${watchLocalName ?? 'watch'}: typeof import('${watchSpecifier}').watch & (<__WatchT>(source: __WatchT, handler: (value: __WatchT) => void) => () => void)\n`,
+    )
     const propsSpecifier = `${ABIDE_PACKAGE_NAME}/ui/props`
     for (const line of imports) {
-        /* The `props` import is replaced by the contextual `declare function` above;
-           emitting it too would be a duplicate-identifier error. Matched by EXACT specifier
+        /* The `props`/`watch` imports are replaced by the contextual declarations above;
+           emitting one too would be a duplicate-identifier error. Matched by EXACT specifier
            (either quote style, not a loose suffix match) so an unrelated user module merely
-           named `.../ui/props` survives verbatim. */
+           named `.../ui/props` (or `.../ui/watch`) survives verbatim. */
         if (
             line.text.includes(`from '${propsSpecifier}'`) ||
-            line.text.includes(`from "${propsSpecifier}"`)
+            line.text.includes(`from "${propsSpecifier}"`) ||
+            line.text.includes(`from '${watchSpecifier}'`) ||
+            line.text.includes(`from "${watchSpecifier}"`)
         ) {
             continue
         }
@@ -331,6 +359,11 @@ type ScriptAnalysis = {
        for the canonical import, `p` for `props as p`), or undefined when not imported. The
        `declare function` for `props` must target this name, not the canonical `'props'`. */
     propsLocalName: string | undefined
+    /* The LOCAL binding name the author's `watch` import is bound to (alias-safe), or undefined
+       when not imported. The shadow re-types `watch` under this name with a value-source
+       overload so the `watch(cell, handler)` form type-checks (the cell is projected to its
+       value, so the real State/socket/rpc overloads never match it). */
+    watchLocalName: string | undefined
 }
 
 /* Pushes a diagnostic for every author binding whose name starts with the reserved `$$`
@@ -370,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)
@@ -424,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)
@@ -451,6 +496,7 @@ function analyzeScript(scriptBody: string, scriptStart: number): ScriptAnalysis
             diagnostics,
             importedReactives: new Set(),
             propsLocalName: undefined,
+            watchLocalName: undefined,
         }
     }
     const file = ts.createSourceFile('script.ts', scriptBody, ts.ScriptTarget.Latest, true)
@@ -462,10 +508,13 @@ function analyzeScript(scriptBody: string, scriptStart: number): ScriptAnalysis
     /* The local name bound to `props` (alias-safe): the key whose value is the canonical
        `'props'`. At most one — a file imports `props` from one specifier. */
     let propsLocalName: string | undefined
+    let watchLocalName: string | undefined
     for (const [local, canonical] of bindings.direct) {
         if (canonical === 'props') {
             propsLocalName = local
-            break
+        }
+        if (canonical === 'watch') {
+            watchLocalName = local
         }
     }
     /* The `$$` prefix is reserved for the compiler's injected runtime (`$$each`, `$$model`,
@@ -474,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] => ({
@@ -507,7 +556,16 @@ function analyzeScript(scriptBody: string, scriptStart: number): ScriptAnalysis
             scope.push(scopeLineFor(declaration, propsShapes, verbatim, span, bindings))
         }
     }
-    return { imports, types, scope, propsShapes, diagnostics, importedReactives, propsLocalName }
+    return {
+        imports,
+        types,
+        scope,
+        propsShapes,
+        diagnostics,
+        importedReactives,
+        propsLocalName,
+        watchLocalName,
+    }
 }
 
 /* Value-projects a nested control-flow `<script>` body the way `analyzeScript`
@@ -645,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

@@ -5,9 +5,11 @@ import { desugarSignals } from './desugarSignals.ts'
 import { identifierReferencePattern } from './identifierReferencePattern.ts'
 import { docAccessTransformer } from './lowerDocAccess.ts'
 import { signalRefsTransformer } from './renameSignalRefs.ts'
+import { reactiveImportBindings } from './resolveReactiveExport.ts'
 import { stripEffectsTransformer } from './stripEffects.ts'
 import { TS_PRINTER } from './TS_PRINTER.ts'
 import type { SeedTypeClassifier } from './types/SeedTypeClassifier.ts'
+import { wrapReactionCellSources } from './wrapReactionCellSources.ts'
 
 /* The `abide/ui/*` modules the reactive surface is imported from. An author's import of
    one is compiler-recognised and lowered, so its binding is often fully consumed — a plain
@@ -100,8 +102,29 @@ export function lowerScript(
         seedClassify,
         scriptBase,
     )
+    /* The local names bound to `watch` (alias-safe), and the full set of read-rewritten cell
+       names — together they let `wrapReactionCellSources` fold a `watch(cell, handler)` into
+       the thunk form BEFORE the read-lowering turns the cell reference into a value read. */
+    const watchLocalNames = new Set<string>()
+    for (const [local, canonical] of reactiveImportBindings(source).direct) {
+        if (canonical === 'watch') {
+            watchLocalNames.add(local)
+        }
+    }
+    const cellNames = new Set<string>([
+        ...stateNames,
+        ...derivedNames,
+        ...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,
+        ...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

@@ -0,0 +1,117 @@
+import ts from 'typescript'
+
+/*
+Folds a cell-source `watch(source, handler)` into the auto-tracked thunk form
+`watch(() => (handler)(source))`, so the reaction reads the cell reactively
+instead of receiving a one-time value.
+
+The plain-variable ergonomic makes a bare `count` a VALUE read everywhere the
+read-lowering runs (`renameSignalRefs` → `docAccessTransformer`). That is right
+for `{count}` / `count + 1`, but it also lowered `watch(count, handler)`'s source
+to `$$model.read("count")` — a number — so the runtime `watch` (which expects a
+`State` and reads `.value` inside an effect) never subscribed: the reaction was
+inert. The `watch(count, n => …)` form was documented but silently dead.
+
+This runs BEFORE the read-lowering, so the `source` moved inside the new thunk is
+lowered to its normal reactive read there — one rewrite covers every cell kind
+(doc-slot `state`, `.value` cell, `computed`, `linked`), because it reuses the
+read the rest of the pipeline already emits. The runtime `watch(thunk)` is the
+same auto-tracked effect the compiler's own bindings use, so semantics match the
+old `effect(() => handler(cell.value))` cell branch exactly.
+
+Only a bare cell reference (or an array literal of them — the `watch([a, b], …)`
+form) is folded. A socket / rpc / arbitrary object source is left untouched so the
+runtime's own source dispatch (`cache.on` / `reactToRpc`) still handles it; the
+thunk (`watch(() => …)`) and rpc-with-args (`watch(fn, args, handler)`) forms are
+already correct and are matched out by arity.
+*/
+export function wrapReactionCellSources(
+    cellNames: ReadonlySet<string>,
+    watchLocalNames: ReadonlySet<string>,
+): ts.TransformerFactory<ts.SourceFile> {
+    /* A source that names a reactive cell: a bare cell identifier, or a non-empty array
+       literal whose every element is one (the multi-cell `watch([a, b], …)` form). */
+    function isCellSource(source: ts.Expression): boolean {
+        if (ts.isIdentifier(source)) {
+            return cellNames.has(source.text)
+        }
+        if (ts.isArrayLiteralExpression(source)) {
+            return (
+                source.elements.length > 0 &&
+                source.elements.every(
+                    (element) => ts.isIdentifier(element) && cellNames.has(element.text),
+                )
+            )
+        }
+        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 : []
+            if (
+                ts.isCallExpression(node) &&
+                ts.isIdentifier(node.expression) &&
+                watchLocalNames.has(node.expression.text) &&
+                node.arguments.length === 2 &&
+                sourceArg !== undefined &&
+                handlerArg !== undefined &&
+                isCellSource(sourceArg)
+            ) {
+                /* Visit the operands first — a handler body may itself contain a nested cell-source
+                   watch, and the source stays a plain identifier the read-lowering rewrites next. */
+                const source = ts.visitNode(sourceArg, visit) as ts.Expression
+                const handler = ts.visitNode(handlerArg, visit) as ts.Expression
+                /* `(handler)(source)` — parenthesise the handler so an arrow callee prints callable. */
+                const call = ts.factory.createCallExpression(
+                    ts.factory.createParenthesizedExpression(handler),
+                    undefined,
+                    [source],
+                )
+                const thunk = ts.factory.createArrowFunction(
+                    undefined,
+                    undefined,
+                    [],
+                    undefined,
+                    ts.factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken),
+                    call,
+                )
+                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),