@abide/abide 0.29.0 → 0.31.0

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

@@ -0,0 +1,7 @@
+/* The callee names the `.abide` compiler recognises as reactive declarations
+   (`let x = state(...)`, `linked(...)`, `derived(...)`, `prop(...)`): the shared
+   "is this a reactive binding" allowlist read by the desugarer, the nested-script
+   scoper, and the type-checking shadow. How each lowers — a serializable doc slot
+   vs a `.value` cell — is decided per-site; this is only the membership set, so a
+   new primitive is a single edit here. */
+export const REACTIVE_CALLEES: ReadonlySet<string> = new Set(['state', 'linked', 'derived', 'prop'])

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

@@ -10,6 +10,7 @@ export const UI_RUNTIME_IMPORTS: { name: string; specifier: string }[] = [
     { name: 'snippet', specifier: 'shared/snippet' },
     { name: 'doc', specifier: 'ui/doc' },
     { name: 'state', specifier: 'ui/state' },
+    { name: 'linked', specifier: 'ui/linked' },
     { name: 'derived', specifier: 'ui/derived' },
     { name: 'effect', specifier: 'ui/effect' },
     { name: 'mount', specifier: 'ui/dom/mount' },

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

@@ -1,7 +1,8 @@
 /*
-HTML void elements — they have no closing tag and no children. Shared by the SSR
-generator and the static-clone skeleton generator so both emit `<img>` not
-`<img></img>`, keeping server markup and the client clone template identical.
+HTML void elements — they have no closing tag and no children. Shared by the
+template parser, the SSR generator, and the static-clone skeleton generator so
+all self-close consistently and the back-ends emit `<img>` not `<img></img>`,
+keeping server markup and the client clone template identical.
 */
 export const VOID_TAGS: ReadonlySet<string> = new Set([
     'area',

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

@@ -1,6 +1,7 @@
 import { analyzeComponent } from './analyzeComponent.ts'
 import { generateBuild } from './generateBuild.ts'
 import { hoistCells } from './hoistCells.ts'
+import type { AnalyzedComponent } from './types/AnalyzedComponent.ts'
 
 /*
 Compiles a single-file abide component into the body of a client build function.
@@ -9,9 +10,18 @@ template, and hoists static paths to cells. The returned body runs against a
 `host` element with `doc`/`state`/`derived`/`effect` and the dom bindings in
 scope and defines `model` itself. `compileModule` wraps it (and the SSR body) into
 a real module; tests wrap it with `new Function`.
+
+`analyzed` is a lazy default: a direct caller (tests) omits it and the front-end
+runs here, but `compileModule` analyzes once and passes the result to both
+back-ends, so the shared front-end runs once per build instead of three times.
 */
-export function compileComponent(source: string, isLayout = false, scopeSeed?: string): string {
-    const { script, stateNames, derivedNames, nodes } = analyzeComponent(source, scopeSeed)
+export function compileComponent(
+    source: string,
+    isLayout = false,
+    scopeSeed?: string,
+    analyzed: AnalyzedComponent = analyzeComponent(source, scopeSeed),
+): string {
+    const { script, stateNames, derivedNames, nodes } = analyzed
     const build = generateBuild(nodes, 'host', stateNames, derivedNames, isLayout)
     /* The scoped CSS is bundled into the entry stylesheet (see `abideUiPlugin`), not
        injected at runtime; the build only needs the `data-a-…` scope attributes on

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

@@ -22,10 +22,13 @@ export function compileModule(
     options: { isLayout?: boolean; moduleId?: string; hot?: boolean } = {},
 ): string {
     const isLayout = options.isLayout ?? false
-    /* Component-authored imports (e.g. child components) hoisted to module scope. */
-    const analyzed = analyzeComponent(source)
+    /* Run the shared front-end once and feed it to both back-ends — the analysis is
+       pure over (source, moduleId), so the client and SSR builds reuse one parse
+       instead of re-running it. `imports` (hoisted child-component imports) and the
+       per-element scopes both come from this single pass. */
+    const analyzed = analyzeComponent(source, options.moduleId)
     const userImports = analyzed.imports
-    const body = indent(compileComponent(source, isLayout, options.moduleId))
+    const body = indent(compileComponent(source, isLayout, options.moduleId, analyzed))
 
     /* Hot module (dev component HMR): the same client build, but its runtime comes
        from the live bundle via `window.__abide` — so it shares the one reactive graph
@@ -49,7 +52,7 @@ if (!hotReplace(${id}, component)) location.reload()
 `
     }
 
-    const ssrBody = indent(compileSSR(source, isLayout, options.moduleId))
+    const ssrBody = indent(compileSSR(source, isLayout, options.moduleId, analyzed))
     /* Per-component dead-import elimination: emit only the runtime names this module
        actually references. A component that uses no `each`/`await`/`html` shouldn't
        drag those modules into its chunk. The package isn't globally side-effect-free

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

@@ -2,6 +2,7 @@ import { analyzeComponent } from './analyzeComponent.ts'
 import { generateSSR } from './generateSSR.ts'
 import { SSR_ESCAPE } from './SSR_ESCAPE.ts'
 import { stripEffects } from './stripEffects.ts'
+import type { AnalyzedComponent } from './types/AnalyzedComponent.ts'
 
 /*
 Compiles a component into the body of a server render function. Runs the shared
@@ -19,9 +20,17 @@ Runs with `doc`/`state`/`derived`/`effect`/`nextBlockId`/`enterRenderPass`/
 `exitRenderPass` in scope and defines `model`. The body is bracketed by a render
 pass so the outermost render resets the block-id counter and an inlined child
 render continues it — keeping await/try ids unique and aligned with the client.
+
+`analyzed` is a lazy default: a direct caller (tests) omits it and the front-end
+runs here, but `compileModule` shares one analysis across both back-ends.
 */
-export function compileSSR(source: string, isLayout = false, scopeSeed?: string): string {
-    const { script, stateNames, derivedNames, nodes } = analyzeComponent(source, scopeSeed)
+export function compileSSR(
+    source: string,
+    isLayout = false,
+    scopeSeed?: string,
+    analyzed: AnalyzedComponent = analyzeComponent(source, scopeSeed),
+): string {
+    const { script, stateNames, derivedNames, nodes } = analyzed
     const ssr = generateSSR(nodes, stateNames, derivedNames, isLayout)
     /* No `<style>` in the markup — the scoped CSS is bundled into the entry stylesheet
        the shell links (see `abideUiPlugin`), so SSR output is styled by that sheet. The

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

@@ -1,6 +1,7 @@
 import ts from 'typescript'
 import { ABIDE_PACKAGE_NAME } from '../../shared/ABIDE_PACKAGE_NAME.ts'
 import { parseTemplate } from './parseTemplate.ts'
+import { REACTIVE_CALLEES } from './REACTIVE_CALLEES.ts'
 import type { CompiledShadow, ShadowMapping } from './types/CompiledShadow.ts'
 import type { TemplateNode } from './types/TemplateNode.ts'
 
@@ -14,13 +15,14 @@ never appears here — every `prop()` declaration is rewritten away. `$props` is
 legacy untyped prop bag (pre-`prop()` sugar) made available raw.
 */
 const SHADOW_PREAMBLE = `import { state } from '${ABIDE_PACKAGE_NAME}/ui/state'
+import { linked } from '${ABIDE_PACKAGE_NAME}/ui/linked'
 import { derived } from '${ABIDE_PACKAGE_NAME}/ui/derived'
 import { effect } from '${ABIDE_PACKAGE_NAME}/ui/effect'
 import { doc } from '${ABIDE_PACKAGE_NAME}/ui/doc'
 import { html } from '${ABIDE_PACKAGE_NAME}/shared/html'
 import { snippet } from '${ABIDE_PACKAGE_NAME}/shared/snippet'
 declare const $props: Record<string, (() => unknown) | undefined>
-void [state, derived, effect, doc, html, snippet]
+void [state, linked, derived, effect, doc, html, snippet]
 `
 
 /*
@@ -46,11 +48,18 @@ export function compileShadow(source: string): CompiledShadow {
     const scriptStart = leadingScript ? source.indexOf('>', leadingScript.index) + 1 : 0
     const templateStart = leadingScript ? (leadingScript.index ?? 0) + leadingScript[0].length : 0
 
-    const { imports, scope, props } = analyzeScript(scriptBody, scriptStart)
+    const { imports, types, scope, props } = analyzeScript(scriptBody, scriptStart)
     builder.raw(SHADOW_PREAMBLE)
     for (const line of imports) {
         builder.flush(line)
     }
+    /* Component-local `type`/`interface` declarations are hoisted to module scope —
+       above `__Props` so prop annotations referencing them resolve, and still visible
+       inside the function body where the rest of the scope and template expressions use
+       them. (Emitting them as in-function scope lines would hide them from `__Props`.) */
+    for (const line of types) {
+        builder.flush(line)
+    }
     builder.raw(`interface __Props {\n${props.join('\n')}\n}\n`)
     /* async so `await` blocks are legal; never executed, so the return is void. */
     builder.raw('export default async function (props: __Props): Promise<void> {\n')
@@ -59,9 +68,7 @@ export function compileShadow(source: string): CompiledShadow {
     for (const line of scope) {
         builder.flush(line)
     }
-    for (const node of parseTemplate(source.slice(templateStart), templateStart).nodes) {
-        emitNode(node, builder)
-    }
+    emitNodes(parseTemplate(source.slice(templateStart), templateStart).nodes, builder)
     builder.raw('}\n')
     return builder.result()
 }
@@ -75,6 +82,9 @@ type Builder = {
     expr: (code: string, sourceLoc: number | undefined) => void
     stmt: (code: string, sourceLoc: number | undefined) => void
     flush: (line: ScopeLine) => void
+    /* A fresh shadow-local binding name (`__<base>_<n>`) — for synthesised bindings
+       like an await's resolved value, kept distinct so nested blocks never collide. */
+    unique: (base: string) => string
     result: () => CompiledShadow
 }
 
@@ -84,8 +94,12 @@ type ScopeLine = { text: string; segments: ShadowMapping[] }
 
 function createBuilder(): Builder {
     let code = ''
+    let uniqueCounter = 0
     const mappings: ShadowMapping[] = []
     const builder: Builder = {
+        unique(base) {
+            return `__${base}_${uniqueCounter++}`
+        },
         raw(text) {
             code += text
         },
@@ -117,17 +131,24 @@ function createBuilder(): Builder {
     return builder
 }
 
-type ScriptAnalysis = { imports: ScopeLine[]; scope: ScopeLine[]; props: string[] }
+type ScriptAnalysis = {
+    imports: ScopeLine[]
+    types: ScopeLine[]
+    scope: ScopeLine[]
+    props: string[]
+}
 
 /* Walks the leading `<script>` and produces the shadow's module imports, the
-   value-typed scope lines, and the Props interface fields. `scriptStart` is the
-   body's absolute offset in the source, so verbatim spans map back exactly. */
+   module-scope type declarations, the value-typed scope lines, and the Props
+   interface fields. `scriptStart` is the body's absolute offset in the source, so
+   verbatim spans map back exactly. */
 function analyzeScript(scriptBody: string, scriptStart: number): ScriptAnalysis {
     const imports: ScopeLine[] = []
+    const types: ScopeLine[] = []
     const scope: ScopeLine[] = []
     const props: string[] = []
     if (scriptBody.trim() === '') {
-        return { imports, scope, props }
+        return { imports, types, scope, props }
     }
     const file = ts.createSourceFile('script.ts', scriptBody, ts.ScriptTarget.Latest, true)
     /* A verbatim span: original text + the segment mapping it back, relative to the
@@ -145,6 +166,11 @@ function analyzeScript(scriptBody: string, scriptStart: number): ScriptAnalysis
             imports.push({ text: verbatim(statement), segments: [span(statement, 0)] })
             continue
         }
+        if (ts.isTypeAliasDeclaration(statement) || ts.isInterfaceDeclaration(statement)) {
+            /* Hoist to module scope (verbatim, mapped) so prop annotations resolve them. */
+            types.push({ text: verbatim(statement), segments: [span(statement, 0)] })
+            continue
+        }
         const reactive = reactiveDeclarations(statement)
         if (reactive === undefined) {
             /* Plain statement (function, const, expression) — emit verbatim, mapped. */
@@ -155,7 +181,7 @@ function analyzeScript(scriptBody: string, scriptStart: number): ScriptAnalysis
             scope.push(scopeLineFor(declaration, props, verbatim, span))
         }
     }
-    return { imports, scope, props }
+    return { imports, types, scope, props }
 }
 
 /* The `state`/`derived`/`prop` declarations in a variable statement, or undefined
@@ -170,14 +196,15 @@ function reactiveDeclarations(statement: ts.Statement): ts.VariableDeclaration[]
     return reactive.length === declarations.length && reactive.length > 0 ? reactive : undefined
 }
 
-/* The callee name of a `NAME = state(...)` / `derived(...)` / `prop(...)` decl. */
+/* The callee name of a `NAME = state(...)` / `linked(...)` / `derived(...)` /
+   `prop(...)` decl. */
 function signalCallee(declaration: ts.VariableDeclaration): string | undefined {
     const initializer = declaration.initializer
     if (
         initializer !== undefined &&
         ts.isCallExpression(initializer) &&
         ts.isIdentifier(initializer.expression) &&
-        ['state', 'derived', 'prop'].includes(initializer.expression.text)
+        REACTIVE_CALLEES.has(initializer.expression.text)
     ) {
         return initializer.expression.text
     }
@@ -207,9 +234,10 @@ function scopeLineFor(
         const prefix = `let ${name}${annotation} = (`
         return { text: `${prefix}${verbatim(init)});`, segments: [span(init, prefix.length)] }
     }
-    if (callee === 'derived') {
-        /* derived<T>(compute): T is the value type — annotate so an explicit
-           argument isn't lost to inference of the compute's return. */
+    if (callee === 'derived' || callee === 'linked') {
+        /* derived<T>(compute) / linked<T>(seed): T is the value type — the call's
+           first arg is a thunk, so invoking it yields the value. Annotate so an
+           explicit type argument isn't lost to inference of the thunk's return. */
         const typeNode = call.typeArguments?.[0]
         const annotation = typeNode === undefined ? '' : `: ${verbatim(typeNode)}`
         const fn = call.arguments[0]
@@ -229,9 +257,56 @@ function scopeLineFor(
     return { text: `let ${name} = props[${JSON.stringify(keyText)}];`, segments: [] }
 }
 
-/* Emits a template node's expressions into the shadow's `if (false) {…}` render
-   body. Control flow introduces its binding so children type-check against it;
-   every expression is referenced in a statement so a type error surfaces and maps. */
+/* Emits a sibling list. Walks with lookahead so an `if` and its trailing `else`
+   (the next meaningful sibling — a `case` with no match) fuse into one
+   `if (…) {…} else {…}`, giving the else branch the condition's negative narrowing
+   instead of being checked bare against the un-narrowed type. Every other node is
+   emitted standalone via `emitNode`. */
+function emitNodes(nodes: TemplateNode[], builder: Builder): void {
+    for (let index = 0; index < nodes.length; index += 1) {
+        const node = nodes[index]
+        if (node === undefined) {
+            continue
+        }
+        if (node.kind !== 'if') {
+            emitNode(node, builder)
+            continue
+        }
+        builder.raw('if ')
+        builder.expr(node.condition, node.loc)
+        builder.raw(' {\n')
+        emitNodes(node.children, builder)
+        builder.raw('}')
+        const elseIndex = nextMeaningful(nodes, index + 1)
+        const elseNode = elseIndex === -1 ? undefined : nodes[elseIndex]
+        if (elseNode?.kind === 'case' && elseNode.match === undefined) {
+            builder.raw(' else {\n')
+            emitNodes(elseNode.children, builder)
+            builder.raw('}')
+            index = elseIndex
+        }
+        builder.raw('\n')
+    }
+}
+
+/* Index of the next node that isn't whitespace-only text (which separates the `if`
+   and `else` tags in source but carries no checkable content); -1 if none remain. */
+function nextMeaningful(nodes: TemplateNode[], from: number): number {
+    for (let index = from; index < nodes.length; index += 1) {
+        const node = nodes[index]
+        const blank =
+            node?.kind === 'text' &&
+            node.parts.every((part) => part.kind === 'static' && part.value.trim() === '')
+        if (!blank) {
+            return index
+        }
+    }
+    return -1
+}
+
+/* Emits a template node's expressions into the shadow's render body. Control flow
+   introduces its binding so children type-check against it; every expression is
+   referenced in a statement so a type error surfaces and maps. */
 function emitNode(node: TemplateNode, builder: Builder): void {
     switch (node.kind) {
         case 'text':
@@ -247,9 +322,7 @@ function emitNode(node: TemplateNode, builder: Builder): void {
                     builder.stmt(attr.code, attr.loc)
                 }
             }
-            node.children.forEach((child) => {
-                emitNode(child, builder)
-            })
+            emitNodes(node.children, builder)
             return
         case 'component': {
             /* Check each prop against the child's declared type. The imported tag
@@ -265,79 +338,117 @@ function emitNode(node: TemplateNode, builder: Builder): void {
                 builder.expr(prop.code, prop.loc)
                 builder.raw(');\n')
             }
-            node.children.forEach((child) => {
-                emitNode(child, builder)
-            })
+            emitNodes(node.children, builder)
             return
         }
         case 'if':
+            /* Reached only for an `if` emitted outside a sibling list (none today);
+               `emitNodes` owns the `if`/`else` fusion. Emit without an else. */
             builder.raw('if ')
             builder.expr(node.condition, node.loc)
             builder.raw(' {\n')
-            node.children.forEach((child) => {
-                emitNode(child, builder)
-            })
+            emitNodes(node.children, builder)
             builder.raw('}\n')
             return
         case 'each':
-            builder.raw(`for (const ${node.as} of `)
+            /* `for await` over an async each's AsyncIterable, plain `for…of` otherwise —
+               so the item binds to the element type under either iteration protocol. */
+            builder.raw(
+                node.async ? `for await (const ${node.as} of ` : `for (const ${node.as} of `,
+            )
             builder.expr(node.items, node.loc)
             builder.raw(') {\n')
             if (node.key !== undefined) {
                 builder.raw(`void (${node.key});\n`)
             }
-            node.children.forEach((child) => {
-                emitNode(child, builder)
-            })
+            emitNodes(node.children, builder)
             builder.raw('}\n')
             return
-        case 'await':
+        case 'await': {
+            /* Resolve once into a shadow-local; `then` binds it (carrying the awaited
+               type so resolved-content props are checked), `catch` binds the error as
+               `any` (statically unknowable), `finally` binds nothing. Blocking: the
+               non-branch children are the resolved content, bound to `as`. Streaming:
+               they're the pending content, checked without the resolved value. */
+            const resolved = builder.unique('awaited')
             builder.raw('{\n')
-            builder.raw(node.as !== undefined ? `const ${node.as} = await ` : 'await ')
+            builder.raw(`const ${resolved} = await `)
             builder.expr(node.promise, node.loc)
-            builder.raw(';\n')
-            node.children.forEach((child) => {
-                emitNode(child, builder)
-            })
+            builder.raw(`;\nvoid ${resolved};\n`)
+            const pending = node.children.filter((child) => child.kind !== 'branch')
+            const branches = node.children.filter((child) => child.kind === 'branch')
+            if (node.blocking && node.as !== undefined) {
+                builder.raw(`{\nconst ${node.as} = ${resolved};\n`)
+                emitNodes(pending, builder)
+                builder.raw('}\n')
+            } else {
+                emitNodes(pending, builder)
+            }
+            for (const branch of branches) {
+                if (branch.kind !== 'branch') {
+                    continue
+                }
+                builder.raw('{\n')
+                if (branch.branch === 'then' && branch.as !== undefined) {
+                    builder.raw(`const ${branch.as} = ${resolved};\n`)
+                } else if (branch.branch === 'catch' && branch.as !== undefined) {
+                    builder.raw(`const ${branch.as} = undefined as any;\n`)
+                }
+                emitNodes(branch.children, builder)
+                builder.raw('}\n')
+            }
             builder.raw('}\n')
             return
+        }
         case 'switch':
-            builder.stmt(node.subject, node.loc)
-            node.children.forEach((child) => {
-                emitNode(child, builder)
-            })
+            /* A real `switch` so a discriminant subject narrows into each case body;
+               non-case children (whitespace between cases) carry nothing and are
+               skipped. `break` keeps cases independent under `noFallthroughCasesInSwitch`. */
+            builder.raw('switch (')
+            builder.expr(node.subject, node.loc)
+            builder.raw(') {\n')
+            for (const child of node.children) {
+                if (child.kind !== 'case') {
+                    continue
+                }
+                if (child.match !== undefined) {
+                    builder.raw('case ')
+                    builder.expr(child.match, child.loc)
+                    builder.raw(': {\n')
+                } else {
+                    builder.raw('default: {\n')
+                }
+                emitNodes(child.children, builder)
+                builder.raw('break;\n}\n')
+            }
+            builder.raw('}\n')
             return
         case 'case':
+            /* Reached only for a stray case outside a switch/if-else (none today); a
+               `switch` emits its own cases and `emitNodes` consumes an `else`. */
             if (node.match !== undefined) {
                 builder.stmt(node.match, node.loc)
             }
-            node.children.forEach((child) => {
-                emitNode(child, builder)
-            })
+            emitNodes(node.children, builder)
             return
         case 'branch':
-            /* then/catch bind the resolved value / error as `any` so children check. */
+            /* Reached only for a stray branch outside an await (none today); the await
+               handler binds resolved/error types for its own branch children. */
             builder.raw('{\n')
             if (node.as !== undefined) {
                 builder.raw(`const ${node.as} = undefined as any;\n`)
             }
-            node.children.forEach((child) => {
-                emitNode(child, builder)
-            })
+            emitNodes(node.children, builder)
             builder.raw('}\n')
             return
         case 'try':
             builder.raw('{\n')
-            node.children.forEach((child) => {
-                emitNode(child, builder)
-            })
+            emitNodes(node.children, builder)
             builder.raw('}\n')
             return
         case 'snippet':
             builder.raw(`const ${node.name} = (${node.params ?? ''}) => {\n`)
-            node.children.forEach((child) => {
-                emitNode(child, builder)
-            })
+            emitNodes(node.children, builder)
             builder.raw('};\n')
             return
         case 'script':

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

@@ -1,5 +1,6 @@
 import { resolve } from 'node:path'
 import ts from 'typescript'
+import { messageFromError } from '../../shared/messageFromError.ts'
 import { assetModulesFile } from './assetModulesFile.ts'
 import { compileShadow } from './compileShadow.ts'
 import { loadShadowTsConfig } from './loadShadowTsConfig.ts'
@@ -59,7 +60,7 @@ export function createShadowLanguageService(cwd: string): ShadowLanguageService
             return compiled.code
         } catch (error) {
             shadows.set(abidePath, { code: '', mappings: [] })
-            parseErrors.set(abidePath, error instanceof Error ? error.message : String(error))
+            parseErrors.set(abidePath, messageFromError(error))
             return 'export default function (): void {}\n'
         }
     }

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

@@ -1,5 +1,6 @@
 import { resolve } from 'node:path'
 import ts from 'typescript'
+import { messageFromError } from '../../shared/messageFromError.ts'
 import { assetModulesFile } from './assetModulesFile.ts'
 import { compileShadow } from './compileShadow.ts'
 import { loadShadowTsConfig } from './loadShadowTsConfig.ts'
@@ -51,7 +52,7 @@ export function createShadowProgram(cwd: string, abidePaths?: string[]): ShadowP
             return compiled.code
         } catch (error) {
             shadows.set(abidePath, { code: '', mappings: [] })
-            parseErrors.set(abidePath, error instanceof Error ? error.message : String(error))
+            parseErrors.set(abidePath, messageFromError(error))
             return 'export default function (): void {}\n'
         }
     }

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

@@ -1,4 +1,5 @@
 import ts from 'typescript'
+import { REACTIVE_CALLEES } from './REACTIVE_CALLEES.ts'
 import { renameSignalRefs } from './renameSignalRefs.ts'
 
 /*
@@ -9,14 +10,16 @@ declares reactive state as signals:
   let items = state([])
   const total = derived(() => count + items.length)
 
-This collects the `state`/`derived` binding names, turns each `state` declaration
+This collects the binding names, turns each plain `state(initial)` declaration
 into an initialising assignment on a shared `model` document (in source order, so
-a later state can read an earlier one), keeps `derived`/`effect`/functions, then
-renames every reference through `renameSignalRefs`. The result is plain `model.x`
-access that `lowerDocAccess` lowers to patches/reads — so the signal surface gets
-the document substrate's deep, fine-grained, serializable reactivity for free.
-No state declarations → the script is returned untouched (the explicit
-`const model = doc(...)` form still works).
+a later state can read an earlier one), keeps the rest, then renames every
+reference through `renameSignalRefs`. Plain `state` becomes `model.x` access that
+`lowerDocAccess` lowers to patches/reads — the document substrate's deep,
+fine-grained, serializable reactivity for free. `linked`, `derived`, and
+`state(initial, transform)` stay verbatim as runtime `.value` cells (referenced
+as `name.value`): they own no doc slot, so they reseed/recompute on resume rather
+than serialize. No reactive declarations → the script is returned untouched (the
+explicit `const model = doc(...)` form still works).
 */
 export function desugarSignals(scriptBody: string): {
     code: string
@@ -32,13 +35,16 @@ export function desugarSignals(scriptBody: string): {
         }
         for (const declaration of statement.declarationList.declarations) {
             const callee = signalCallee(declaration)
-            if (callee === 'state' && ts.isIdentifier(declaration.name)) {
+            if (!ts.isIdentifier(declaration.name)) {
+                continue
+            }
+            if (isPlainStateSlot(declaration)) {
+                /* Plain `state(initial)` → a serializable `model` doc slot. */
                 stateNames.add(declaration.name.text)
-            } else if (
-                (callee === 'derived' || callee === 'prop') &&
-                ts.isIdentifier(declaration.name)
-            ) {
-                /* A prop reads like a derived (read-only); both are referenced as `.value`. */
+            } else if (callee !== undefined && REACTIVE_CALLEES.has(callee)) {
+                /* `.value` cells, referenced as `name.value`: `linked`, `derived`, a
+                   `prop` (reads like a read-only derived), and `state(initial, transform)`
+                   (the transform must run on writes, so it can't be a bare doc slot). */
                 derivedNames.add(declaration.name.text)
             }
         }
@@ -70,6 +76,24 @@ export function desugarSignals(scriptBody: string): {
     }
 }
 
+/* True for `state(initial, transform)` — the write-coercion transform forces a
+   `.value` cell (writes run it) rather than a bare, serializable doc slot. */
+function hasTransform(declaration: ts.VariableDeclaration): boolean {
+    const initializer = declaration.initializer
+    return (
+        initializer !== undefined &&
+        ts.isCallExpression(initializer) &&
+        initializer.arguments.length >= 2
+    )
+}
+
+/* A plain `state(initial)` with no transform → a serializable `model` doc slot;
+   every other reactive declaration is a `.value` cell. The one rule shared by the
+   name-collection pass and the slot lowering. */
+function isPlainStateSlot(declaration: ts.VariableDeclaration): boolean {
+    return signalCallee(declaration) === 'state' && !hasTransform(declaration)
+}
+
 /* The callee name of a `NAME = state(...)` / `derived(...)` declaration, else undefined. */
 function signalCallee(declaration: ts.VariableDeclaration): string | undefined {
     const initializer = declaration.initializer
@@ -119,7 +143,10 @@ function stateDeclarationAssignments(
     }
     const assignments: string[] = []
     for (const declaration of statement.declarationList.declarations) {
-        if (signalCallee(declaration) !== 'state' || !ts.isIdentifier(declaration.name)) {
+        if (!ts.isIdentifier(declaration.name) || !isPlainStateSlot(declaration)) {
+            /* Only a plain `state(initial)` becomes a slot; `state(initial, transform)`
+               (and everything else) is a `.value` cell — print it verbatim so the
+               runtime call (and its transform) survives. */
             return undefined
         }
         const initial = (declaration.initializer as ts.CallExpression).arguments[0]