@abide/abide 0.42.0 → 0.43.0

package/src/lib/shared/types/OutboxEntry.ts

@@ -0,0 +1,27 @@
+/* The lifecycle status of a parked mutation: waiting to (re)send, or currently sending.
+   A write lives in the outbox ONLY while it can't reach the server; the instant the server
+   responds at all — a 2xx OR a real 4xx/500 — the entry leaves the queue, so there is no
+   terminal `error` state. Only the unreachable family (transport failure / 502/503/504/52x)
+   keeps it `queued`. */
+export type OutboxStatus = 'queued' | 'sending'
+
+/* One durable, replayable mutation in an RPC's outbox — parked because the original
+   call couldn't reach the server (transport failure, or a 502/503/504/52x). `controller`
+   is the entry's own abort handle (cancel = `controller.abort()`); `request` is the
+   synthesized, persisted Request the drain re-sends; `args` is the typed input (for
+   rendering); `error` is why it's parked (the `kind: 'queued'` HttpError from the
+   unreachable attempt); `retry()` kicks a FIFO drain. `settled` is the eventual outcome
+   of THIS write as if the original call had reached the server — it resolves with the
+   decoded result on delivery and rejects with the real HttpError on a server refusal (or
+   an AbortError on cancel). It may stay pending indefinitely if the write is never
+   replayed; reading it is what arms it (a never-read `settled` never rejects). */
+export type OutboxEntry<Args> = {
+    id: string
+    controller: AbortController
+    request: Request
+    args: Args
+    status: OutboxStatus
+    error?: unknown
+    retry: () => Promise<void>
+    settled: Promise<unknown>
+}

package/src/lib/shared/types/RawRemoteFunction.ts

@@ -1,4 +1,4 @@
-import type { HttpVerb } from './HttpVerb.ts'
+import type { HttpMethod } from './HttpMethod.ts'
 import type { RemoteCallable } from './RemoteCallable.ts'
 
 /*
@@ -9,6 +9,6 @@ so callers that need status / headers / body streaming or want to
 implement custom error handling can opt out of the decode.
 */
 export type RawRemoteFunction<Args> = RemoteCallable<Args, Response> & {
-    readonly method: HttpVerb
+    readonly method: HttpMethod
     readonly url: string
 }

package/src/lib/shared/types/RemoteCallable.ts

@@ -2,8 +2,8 @@ import type { RpcOptions } from './RpcOptions.ts'
 
 /*
 Call signature shared by RemoteFunction and RawRemoteFunction. The base
-signature keeps `args` required so a schema'd verb can't silently drop its
-input; when `Args` admits undefined (no-input verbs) an intersected
+signature keeps `args` required so a schema'd rpc can't silently drop its
+input; when `Args` admits undefined (no-input rpcs) an intersected
 optional-arg signature lets call sites write `fn()` instead of
 `fn(undefined)`. Intersection rather than a bare conditional so the type
 stays callable while `Args` is still generic (cache() invokes producers

package/src/lib/shared/types/RemoteFunction.ts

@@ -1,7 +1,10 @@
 import type { ClientFlags } from './ClientFlags.ts'
-import type { HttpVerb } from './HttpVerb.ts'
+import type { ErrorSpec } from './ErrorSpec.ts'
+import type { HttpMethod } from './HttpMethod.ts'
+import type { Outbox } from './Outbox.ts'
 import type { RawRemoteFunction } from './RawRemoteFunction.ts'
 import type { RemoteCallable } from './RemoteCallable.ts'
+import type { RpcErrorGuard } from './RpcErrorGuard.ts'
 import type { Subscribable } from './Subscribable.ts'
 
 /*
@@ -25,23 +28,35 @@ HTTP rpc isn't the place for long-lived multi-publisher subscriptions.
 `.fetch(req)` is the framework's request-dispatch entry point — used by
 the router to invoke the handler from an incoming HTTP request, not
 for user code.
-`crossOrigin` (server-side only, set via the verb's opts) exempts a
-mutating verb from the router's same-origin CSRF gate, accepting browser
+`crossOrigin` (server-side only, set via the rpc's opts) exempts a
+mutating rpc from the router's same-origin CSRF gate, accepting browser
 requests whose Origin doesn't match the app's own host.
 */
 /*
-A body verb (POST/PUT/PATCH) also accepts a FormData in place of typed args:
+A body rpc (POST/PUT/PATCH) also accepts a FormData in place of typed args:
 buildRpcRequest ships it as a multipart body and the server splits text fields
 into args (still schema-validated) and File parts into files(). FormData is
 stringly-typed, so this is the upload escape hatch — typed object args remain
 the default for everything else.
 */
-export type RemoteFunction<Args, Return> = RemoteCallable<Args, Return> & {
-    readonly method: HttpVerb
+export type RemoteFunction<
+    Args,
+    Return,
+    Errors extends ErrorSpec = Record<never, never>,
+> = RemoteCallable<Args, Return> & {
+    readonly method: HttpMethod
     readonly url: string
     readonly clients: ClientFlags
     readonly crossOrigin?: boolean
     readonly raw: RawRemoteFunction<Args>
     stream(args?: Args | FormData): Subscribable<Return>
     fetch(request: Request): Promise<Response>
+    /* Type-guard a caught error against this rpc's declared `errors` (plus the framework
+       `'validation'` / `'queued'`): narrows `.kind` and, for a known kind, `.data` — the
+       per-rpc replacement for a global guard, since the error name → data type mapping
+       lives in the rpc's own spec. */
+    readonly isError: RpcErrorGuard<Errors>
+    /* Present only on a durable (`outbox`) RPC's client proxy: callable for the reactive
+       list of undelivered entries, with `retry()` to drain the queue. Undefined otherwise. */
+    readonly outbox?: Outbox<Args>
 }

package/src/lib/shared/types/RequestScopeInfo.ts

@@ -3,7 +3,7 @@ import type { TraceContext } from './TraceContext.ts'
 /*
 The request-scope facts the shared layer reads through requestScopeSlot:
 trace position, elapsed ms since the scope opened (request start on the
-server, navigation start in the browser), and the verb+path that anchors log
+server, navigation start in the browser), and the method+path that anchors log
 lines. Resolved fresh per read so `elapsedMs` is current at the call.
 */
 export type RequestScopeInfo = {

package/src/lib/shared/types/RpcErrorGuard.ts

@@ -0,0 +1,40 @@
+import type { HttpError } from '../HttpError.ts'
+import type { ErrorSpec } from './ErrorSpec.ts'
+import type { OutboxEntry } from './OutboxEntry.ts'
+import type { StandardSchemaV1 } from './StandardSchemaV1.ts'
+import type { ValidationErrorData } from './ValidationErrorData.ts'
+
+/* The payload a declared error name carries: its data schema's inferred input, or
+   `unknown` for a nullary error (no data schema). */
+type DeclaredErrorData<
+    Errors extends ErrorSpec,
+    Name extends keyof Errors,
+> = Errors[Name]['data'] extends StandardSchemaV1
+    ? StandardSchemaV1.InferInput<Errors[Name]['data']>
+    : unknown
+
+/*
+A rpc's `isError` guard — branch a caught error on a kind THIS rpc knows, with the
+data type narrowed from the rpc's own `errors` spec. `rpc.isError(err, 'outOfStock')`
+narrows `.data` to that error's payload; the framework-reserved `'validation'` /
+`'queued'` to their fixed shapes; any other string narrows `.kind` only (`.data`
+stays `unknown` — it belongs to a different rpc, whose type isn't in scope here).
+
+The declared-name overload comes first so an app error shadows the reserved ones on a
+name collision, and so the kind argument autocompletes to the rpc's declared names.
+*/
+export interface RpcErrorGuard<Errors extends ErrorSpec> {
+    <Name extends keyof Errors & string>(
+        error: unknown,
+        kind: Name,
+    ): error is HttpError & { kind: Name; data: DeclaredErrorData<Errors, Name> }
+    (
+        error: unknown,
+        kind: 'validation',
+    ): error is HttpError & { kind: 'validation'; data: ValidationErrorData }
+    (
+        error: unknown,
+        kind: 'queued',
+    ): error is HttpError & { kind: 'queued'; data: OutboxEntry<unknown> }
+    <Kind extends string>(error: unknown, kind: Kind): error is HttpError & { kind: Kind }
+}

package/src/lib/shared/types/RpcInvoker.ts

@@ -1,4 +1,4 @@
-/* A verb invoker mirrors the verb's own call: a plain call decodes the body
+/* A rpc invoker mirrors the rpc's own call: a plain call decodes the body
    (throws HttpError on non-2xx), `.raw` returns the Response untouched. Shared
    by every name→callable RPC proxy (the CLI client, the test harness). */
 export type RpcInvoker = ((args?: unknown) => Promise<unknown>) & {

package/src/lib/shared/types/StandardSchemaV1.ts

@@ -2,7 +2,7 @@
 Mirror of the Standard Schema v1 spec interface (standardschema.dev). Any
 library that implements the spec — zod, valibot, arktype, etc. — produces
 values whose `~standard` property structurally matches this shape, so users
-can pass their existing schemas to verb helpers without an adapter.
+can pass their existing schemas to rpc helpers without an adapter.
 
 Kept inline (no `@standard-schema/spec` dep) because the spec is type-only
 and tiny; adding a package for ~30 lines of interface would be churn. The

package/src/lib/shared/types/ValidationErrorData.ts

@@ -0,0 +1,20 @@
+import type { StandardSchemaV1 } from './StandardSchemaV1.ts'
+
+/*
+The `data` payload an input/file validation failure carries on its HttpError —
+`kind: 'validation'`, status 422. `issues` is the raw Standard Schema issue list
+(every message + full path); `fields` is the form-friendly top-level-field →
+first-message map (fieldErrorsFromIssues). Because a throw can't carry the rpc's
+per-kind type to the catch, `HttpError.data` is typed `unknown` — narrow it with
+this when `err.kind === 'validation'`:
+
+  if (err instanceof HttpError && err.kind === 'validation') {
+      const { fields } = err.data as ValidationErrorData
+      // fields.email === 'Required', …
+  }
+*/
+// @documentation response
+export type ValidationErrorData = {
+    readonly issues: readonly StandardSchemaV1.Issue[]
+    readonly fields: Record<string, string>
+}

package/src/lib/shared/url.ts

@@ -11,7 +11,7 @@ type Query = Record<string, QueryValue>
 /*
 Augmentable rpc map. Codegen emits a `declare module '<importName>/shared/url'`
 block filling this with `'/rpc/<file>': args` for each query-carrying (GET)
-verb, so url('/rpc/search', { q }) types its args against the verb's own
+rpc, so url('/rpc/search', { q }) types its args against the rpc's own
 signature. Empty by default — an absent entry falls through to the page/asset
 branch, so the helper works before the generated d.ts lands.
 */
@@ -47,7 +47,7 @@ no bracket segments yields {}, which collapses the params slot away. The
 catch-all branch recurses on its head too, so `[name]` segments before a
 `[...rest]` are kept.
 */
-type PathParams<P extends string> = P extends `${infer Head}[...${infer Rest}]${infer Tail}`
+export type PathParams<P extends string> = P extends `${infer Head}[...${infer Rest}]${infer Tail}`
     ? PathParams<Head> & { [K in Rest]: string | number } & PathParams<Tail>
     : P extends `${string}[${infer Name}]${infer Tail}`
       ? { [K in Name]: string | number } & PathParams<Tail>
@@ -59,7 +59,7 @@ Resolves any in-app URL to its base-correct, typed form — the single chokepoin
 so a project mounted under APP_URL's subpath (e.g. /v2) generates links, asset
 refs, and rpc hrefs that stay within the mount. Three disjoint URL kinds, keyed
 off the path:
-  - rpc (flat /rpc/*, present in RpcRoutes): the verb's args, serialised to query.
+  - rpc (flat /rpc/*, present in RpcRoutes): the rpc's args, serialised to query.
   - page route (has [name] segments): path params, then optional query.
   - asset / paramless / raw: bare path, then optional query.
 External URLs (scheme-qualified or protocol-relative) skip the base untouched,

package/src/lib/shared/writeRpcDts.ts

@@ -1,15 +1,15 @@
 import { carriesBodyArgs } from './carriesBodyArgs.ts'
-import { detectVerbMethod } from './detectVerbMethod.ts'
+import { detectRpcMethod } from './detectRpcMethod.ts'
 import { fileStem } from './fileStem.ts'
 import { rpcUrlForFile } from './rpcUrlForFile.ts'
 import { writeDts } from './writeDts.ts'
 
 /*
 Emits a `.d.ts` that augments abide's `RpcRoutes` interface with one entry per
-query-carrying $rpc verb, so `url('/rpc/search', { q })` types its args against
-the verb's own signature. Only GET/DELETE/HEAD (non-body) verbs are included —
-a url() can carry a query string but not a request body, so a POST verb has no
-URL form. `RpcArgs` lifts the args type out of the verb's RemoteFunction
+query-carrying $rpc rpc, so `url('/rpc/search', { q })` types its args against
+the rpc's own signature. Only GET/DELETE/HEAD (non-body) rpcs are included —
+a url() can carry a query string but not a request body, so a POST rpc has no
+URL form. `RpcArgs` lifts the args type out of the rpc's RemoteFunction
 (dropping the FormData upload variant); the file path resolves the export by
 its filename, the abide one-export-per-file convention. Written to
 `src/.abide/rpc.d.ts` so the consumer's src tsconfig include picks it up, keyed
@@ -28,8 +28,8 @@ export async function writeRpcDts({
 }): Promise<void> {
     const lines = await Promise.all(
         rpcFiles.map(async (file) => {
-            const method = detectVerbMethod(await Bun.file(`${rpcDir}/${file}`).text())
-            // A body verb's args can't ride a URL — leave it out of the url() rpc map.
+            const method = detectRpcMethod(await Bun.file(`${rpcDir}/${file}`).text())
+            // A body rpc's args can't ride a URL — leave it out of the url() rpc map.
             if (!method || carriesBodyArgs(method)) {
                 return undefined
             }

package/src/lib/shared/writeTestRpcDts.ts

@@ -5,9 +5,9 @@ import { writeDts } from './writeDts.ts'
 
 /*
 Emits a `.d.ts` that augments createTestApp's `RpcClient` interface with one
-entry per $rpc verb, keyed by command name (the same key `app.rpc.<name>`
-resolves at runtime). Each entry lifts the verb's args + resolved return out of
-its RemoteFunction so `app.rpc.getProduct({ id })` types against the verb's own
+entry per $rpc rpc, keyed by command name (the same key `app.rpc.<name>`
+resolves at runtime). Each entry lifts the rpc's args + resolved return out of
+its RemoteFunction so `app.rpc.getProduct({ id })` types against the rpc's own
 signature — args in, decoded body out, plus `.raw` for the Response. `RpcArgs`
 drops the FormData upload variant exactly as writeRpcDts does; `RpcReturn`
 reads the resolved body type. Written to `src/.abide/testRpc.d.ts` so the

package/src/lib/test/createTestApp.ts

@@ -25,7 +25,7 @@ import { rpc } from '../../_virtual/rpc.ts'
 import { shell } from '../../_virtual/shell.ts'
 // @ts-expect-error virtual module resolved by abideResolverPlugin
 import { sockets } from '../../_virtual/sockets.ts'
-import { verbRegistry } from '../server/rpc/verbRegistry.ts'
+import { rpcRegistry } from '../server/rpc/rpcRegistry.ts'
 import { createServer } from '../server/runtime/createServer.ts'
 import { ensureRegistriesLoaded } from '../server/runtime/registryManifests.ts'
 import { requestContext } from '../server/runtime/requestContext.ts'
@@ -46,8 +46,8 @@ import type { RemoteFunction } from '../shared/types/RemoteFunction.ts'
 import { createTestSocketChannel } from './createTestSocketChannel.ts'
 
 /*
-Augmentable verb/socket maps for `app.rpc.<verb>` / `app.sockets.<name>`. The
-build's writeTestRpcDts / writeTestSocketsDts emit one entry per verb/socket
+Augmentable rpc/socket maps for `app.rpc.<rpc>` / `app.sockets.<name>`. The
+build's writeTestRpcDts / writeTestSocketsDts emit one entry per rpc/socket
 (into src/.abide/), so the keys + signatures are the project's real surface
 with no imports. Empty here; types arrive once the app has been built. Mirrors
 url's RpcRoutes / health's AppHealthMap.
@@ -58,7 +58,7 @@ export interface RpcClient {}
 // biome-ignore lint/suspicious/noEmptyInterface: augmented by the generated testSockets.d.ts
 export interface SocketClient {}
 
-/* The booted app under test. Every named subsystem is reachable as the verb
+/* The booted app under test. Every named subsystem is reachable as the rpc
    you call, the socket you iterate, or a path you fetch — over the real
    server, so the full pipeline (CSRF, cookies, base path) runs. */
 export type TestApp = {
@@ -69,7 +69,7 @@ export type TestApp = {
        matches routes at raw paths — the APP_URL mount base is stripped by an
        external proxy in production, absent here — so paths carry no base. */
     fetch: (path: string, init?: RequestInit) => Promise<Response>
-    /* Verb calls over HTTP, keyed by command name: `app.rpc.getProduct({ id })`. */
+    /* Rpc calls over HTTP, keyed by command name: `app.rpc.getProduct({ id })`. */
     rpc: RpcClient
     /* Sockets keyed by name: `app.sockets.ticker` is the Socket — iterate it for
        the live stream, `.tail(n)` to seed, `.publish(m)` to send. */
@@ -88,7 +88,7 @@ export type TestApp = {
 Boots the real app on an ephemeral port — the same wiring serverEntry performs,
 minus the standalone-binary env layers. Imports the framework's virtual
 manifests (resolved by abideResolverPlugin, registered via `abide/preload`
-in the consumer's bunfig), so the routes, verbs, and sockets are the project's
+in the consumer's bunfig), so the routes, rpcs, and sockets are the project's
 real surface, not a fixture. Pass nothing: `await createTestApp()` is the app
 exactly as `bun start` would serve it.
 
@@ -138,19 +138,19 @@ export async function createTestApp(): Promise<TestApp> {
         return fetch(`${origin}${path}`, init)
     }
 
-    /* Verb modules loaded once so the registry holds every RemoteFunction; the
+    /* Rpc modules loaded once so the registry holds every RemoteFunction; the
        proxy maps command name → an HTTP call against the booted server. */
     await ensureRegistriesLoaded()
     const remotes = new Map<string, RemoteFunction<unknown, unknown>>(
-        Array.from(verbRegistry.values()).map((entry) => [
+        Array.from(rpcRegistry.values()).map((entry) => [
             commandNameForUrl(entry.remote.url),
             entry.remote,
         ]),
     )
 
     function send(remote: RemoteFunction<unknown, unknown>, args: unknown): Promise<Response> {
-        /* Same-origin Origin header so the CSRF gate admits mutating verbs; the
-           server serves verbs at their raw url (no mount base applied here). */
+        /* Same-origin Origin header so the CSRF gate admits mutating rpcs; the
+           server serves rpcs at their raw url (no mount base applied here). */
         const request = buildRpcRequest({
             method: remote.method,
             url: remote.url,

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

@@ -0,0 +1,48 @@
+import { resolveBranches } from './resolveBranches.ts'
+import type { TemplateNode } from './types/TemplateNode.ts'
+
+/* The structural shape of an `await` block, resolved ONCE from the node so the build and
+   SSR back-ends share one reading of it and only own emission. Both previously recomputed
+   branch resolution, the `finallyChildren` default, the blocking-vs-streaming split of the
+   resolved content/binding, and the surface-the-rejection rule — the parts that can silently
+   diverge. Same single-source-of-truth model the positional walks already use. */
+export type AwaitPlan = {
+    /* `then` on the tag → blocking: no pending branch, the children ARE the resolved content
+       (settled before first flush). Absent → streaming: pending flushes, `then` resolves later. */
+    blocking: boolean
+    /* The pending content (streaming) — `[]` when blocking. */
+    pending: TemplateNode[]
+    /* The resolved content + its bound name: the children-minus-branch bound to `node.as`
+       when blocking, the `then` branch bound to its `as` when streaming. `_value` default. */
+    resolvedChildren: TemplateNode[]
+    resolvedAs: string
+    /* The catch content + its bound name (`_error` default); empty when no catch branch. */
+    catchChildren: TemplateNode[]
+    catchAs: string
+    finallyChildren: TemplateNode[]
+    /* Neither catch nor finally → a rejection must surface (re-throw / `undefined` catch thunk)
+       instead of rendering an empty branch. */
+    surfaceRejection: boolean
+}
+
+/* Resolves an `await` node's branches into the shared structural plan. */
+export function awaitPlan(node: Extract<TemplateNode, { kind: 'await' }>): AwaitPlan {
+    const [thenBranch, catchBranch, finallyBranch] = resolveBranches(
+        node,
+        'then',
+        'catch',
+        'finally',
+    )
+    const finallyChildren = finallyBranch?.children ?? []
+    const nonBranch = node.children.filter((child) => child.kind !== 'branch')
+    return {
+        blocking: node.blocking,
+        pending: node.blocking ? [] : nonBranch,
+        resolvedChildren: node.blocking ? nonBranch : (thenBranch?.children ?? []),
+        resolvedAs: (node.blocking ? node.as : thenBranch?.as) ?? '_value',
+        catchChildren: catchBranch?.children ?? [],
+        catchAs: catchBranch?.as ?? '_error',
+        finallyChildren,
+        surfaceRejection: catchBranch === undefined && finallyChildren.length === 0,
+    }
+}

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

@@ -282,6 +282,14 @@ function scopeLineFor(
         propsShapes.push(shape === undefined ? 'Record<string, any>' : verbatim(shape))
         return { text: `const ${verbatim(declaration)};`, segments: [span(declaration, 6)] }
     }
+    /* The rewrite drops the callee from the line, so hovering `state`/`computed`/
+       `linked` at its call site has nothing to resolve. Append the callee as a
+       trailing reference statement (`…; state;`), mapped back to its source span,
+       so it resolves to the same primitive the destructure does. */
+    const withCalleeRef = (line: ScopeLine): ScopeLine => ({
+        text: `${line.text} ${verbatim(call.expression)};`,
+        segments: [...line.segments, span(call.expression, line.text.length + 1)],
+    })
     if (callee === 'state') {
         /* state<T>(initial): T is the value type — carry it onto the `let` so an
            explicit annotation isn't lost to `any`/`any[]` inference of the initial. */
@@ -297,13 +305,16 @@ function scopeLineFor(
                then correctly flagged possibly-undefined; a guard narrows cleanly. */
             const valueType = annotation === '' ? ': unknown' : `${annotation} | undefined`
             /* map the binding name (offset 4, past `let `) so hover/go-to resolve on it */
-            return { text: `let ${name}!${valueType};`, segments: [span(declaration.name, 4)] }
+            return withCalleeRef({
+                text: `let ${name}!${valueType};`,
+                segments: [span(declaration.name, 4)],
+            })
         }
         const prefix = `let ${name}${annotation} = (`
-        return {
+        return withCalleeRef({
             text: `${prefix}${verbatim(init)});`,
             segments: [span(declaration.name, 4), span(init, prefix.length)],
-        }
+        })
     }
     /* computed<T>(compute) / linked<T>(seed) — the only callees left: T is the value
        type — the call's first arg is a thunk, so invoking it yields the value. Annotate
@@ -317,16 +328,16 @@ function scopeLineFor(
     /* binding-name map offset = past the keyword + space (`let ` = 4, `const ` = 6) */
     const keywordOffset = keyword.length + 1
     if (fn === undefined) {
-        return {
+        return withCalleeRef({
             text: `${keyword} ${name} = undefined;`,
             segments: [span(declaration.name, keywordOffset)],
-        }
+        })
     }
     const prefix = `${keyword} ${name}${annotation} = (`
-    return {
+    return withCalleeRef({
         text: `${prefix}${verbatim(fn)})();`,
         segments: [span(declaration.name, keywordOffset), span(fn, prefix.length)],
-    }
+    })
 }
 
 /* Emits a sibling list — each node standalone via `emitNode`. */
@@ -359,23 +370,29 @@ function emitNode(node: TemplateNode, builder: Builder): void {
             emitNodes(node.children, builder)
             return
         case 'component': {
-            /* Check each prop against the child's declared type. The imported tag
-               resolves (via the shadow host) to the child's `(props: Props) => …`
-               default, so `Parameters<typeof Child>[0]["name"]` is that prop's type;
-               assigning the mapped value to it lands a mismatch diagnostic on the
-               offending expression (an annotated target reports the error on the RHS,
-               unlike an object literal which reports it on the key). */
-            for (const prop of node.props) {
-                /* Lead with a defensive `;`: this IIFE is the one shadow emission that
-                   starts with `(`, so without it a preceding scope statement left
-                   unterminated (a script ending in a call with no trailing semicolon,
-                   e.g. `effect(() => …)`) merges across the newline into `effect(…)(…)`
-                   — a spurious "not callable" on the author's last statement. */
+            /* The imported tag resolves (via the shadow host) to the child's
+               `(props: Props) => …` default, so `Parameters<typeof Child>[0]` is its prop
+               shape. `on*` / `bind:` / `attach` props are framework-handled passthrough
+               (not part of the declared shape), so they are checked leniently — each value
+               against its own declared key type — never flagged as excess. */
+            const handled = (prop: { name: string; spread?: boolean }): boolean =>
+                prop.spread === true ||
+                prop.name.startsWith('on') ||
+                prop.name.startsWith('bind:') ||
+                prop.name.startsWith('class:') ||
+                prop.name.startsWith('style:') ||
+                prop.name === 'attach'
+            const hasSpread = node.props.some((prop) => prop.spread)
+            for (const prop of node.props.filter(handled)) {
+                /* Lead with a defensive `;`: an IIFE/object-literal arg starts with `(` or
+                   `{`, so without it a preceding scope statement left unterminated (a script
+                   ending in a call with no trailing semicolon, e.g. `effect(() => …)`)
+                   merges across the newline into `effect(…)(…)` — a spurious "not callable". */
                 if (prop.spread) {
                     /* A `{...expr}` spread contributes a SUBSET of the props (required ones
                        may come from another spread/explicit prop), so check it against
-                       `Partial<Props>` — every key it does carry must match the child's
-                       declared type, without demanding completeness. */
+                       `Partial<Props>` — every key it does carry must match, without
+                       demanding completeness. */
                     builder.raw(`;((__spread: Partial<Parameters<typeof ${node.name}>[0]>) => {})(`)
                 } else {
                     builder.raw(
@@ -385,6 +402,43 @@ function emitNode(node: TemplateNode, builder: Builder): void {
                 builder.expr(prop.code, prop.loc)
                 builder.raw(');\n')
             }
+            /* The plain data props as one object-literal argument typed to the child's whole
+               prop shape: a missing required prop errors on the literal (anchored at the tag
+               via the mapped `{`), an unknown prop errors on its key, a wrong type on its
+               value. Skipped when a spread is present — a spread may supply required props,
+               so completeness can't be demanded; the data props fall back to lenient per-key
+               checks instead. */
+            const dataProps = node.props.filter((prop) => !handled(prop))
+            if (hasSpread) {
+                for (const prop of dataProps) {
+                    builder.raw(
+                        `;((__prop: Parameters<typeof ${node.name}>[0][${JSON.stringify(prop.name)}]) => {})(`,
+                    )
+                    builder.expr(prop.code, prop.loc)
+                    builder.raw(');\n')
+                }
+            } else {
+                builder.raw(`;((__c: Parameters<typeof ${node.name}>[0]): void => { void __c })({`)
+                /* A zero-length anchor right after `{`, pointing at the tag: a missing-
+                   required-prop error spans the literal from `{`, so it overlaps this and
+                   maps to the tag (an empty span trivially satisfies the source-text ==
+                   shadow-text invariant). */
+                builder.mapped('', node.loc)
+                builder.raw('\n')
+                for (const prop of dataProps) {
+                    /* The key mapped to its source name (excess-prop errors land on the key);
+                       the value verbatim-mapped (wrong-type errors land on the value). */
+                    if (prop.nameLoc !== undefined) {
+                        builder.mapped(prop.name, prop.nameLoc)
+                    } else {
+                        builder.raw(prop.name)
+                    }
+                    builder.raw(': ')
+                    builder.expr(prop.code, prop.loc)
+                    builder.raw(',\n')
+                }
+                builder.raw('});\n')
+            }
             emitNodes(node.children, builder)
             return
         }

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

@@ -4,20 +4,56 @@ import { REACTIVE_CALLEES } from './REACTIVE_CALLEES.ts'
 const factory = ts.factory
 
 /* The reactive primitives that must be reached through a scope. A bare call to one of
-   these is a compile error: reactive state is owned by a scope and the surface must show
-   it (`scope().state(...)`), so a reader always sees the scope interaction. */
-const SCOPE_PRIMITIVES: ReadonlySet<string> = new Set(['state', 'linked', 'computed'])
+   these is a compile error: a reactive primitive is owned by a scope and the surface must
+   show it (`scope().state(...)`), so a reader always sees the scope interaction. `effect`
+   is here too — a reaction is scope-owned (it tears down with the scope), so it joins the
+   one surface; unlike the cells it stays a runtime call (`scope().effect(...)` passes
+   through to the `effect` helper), not a doc slot. */
+const SCOPE_PRIMITIVES: ReadonlySet<string> = new Set(['state', 'linked', 'computed', 'effect'])
+
+/* The primitive names a top-level `const { state, computed } = scope()` destructure binds.
+   Such a name is scope-bound — its bare call below is the destructured method, not a stray
+   global — so it is exempt from the bare-primitive error. Only a destructure of a `scope()`
+   call counts (receiver-agnostic on the callee name, matching signalCallee); an aliased
+   binding (`{ state: s }`) is not recognised, so the canonical name must be kept. */
+function scopeDestructuredPrimitives(source: ts.SourceFile): Set<string> {
+    const bound = new Set<string>()
+    for (const statement of source.statements) {
+        if (!ts.isVariableStatement(statement)) {
+            continue
+        }
+        for (const declaration of statement.declarationList.declarations) {
+            if (
+                signalCallee(declaration) === 'scope' &&
+                ts.isObjectBindingPattern(declaration.name)
+            ) {
+                for (const element of declaration.name.elements) {
+                    if (
+                        element.propertyName === undefined &&
+                        ts.isIdentifier(element.name) &&
+                        SCOPE_PRIMITIVES.has(element.name.text)
+                    ) {
+                        bound.add(element.name.text)
+                    }
+                }
+            }
+        }
+    }
+    return bound
+}
 
 /* Throws on a bare scope primitive (`state(0)` instead of `scope().state(0)`) or on the
    removed `prop(...)` reader — props are now read by destructuring `props()`. Walks all
-   calls, so a stray one nested in a function is caught too, not just top-level declarations. */
+   calls, so a stray one nested in a function is caught too, not just top-level declarations.
+   A primitive destructured from `scope()` at the top is scope-bound and exempt. */
 function assertScopedPrimitives(source: ts.SourceFile): void {
+    const scopeBound = scopeDestructuredPrimitives(source)
     const visit = (node: ts.Node): void => {
         if (ts.isCallExpression(node) && ts.isIdentifier(node.expression)) {
             const name = node.expression.text
-            if (SCOPE_PRIMITIVES.has(name)) {
+            if (SCOPE_PRIMITIVES.has(name) && !scopeBound.has(name)) {
                 throw new Error(
-                    `abide: bare \`${name}(...)\` is not allowed — reactive state lives on a scope. Use \`scope().${name}(...)\` (or a captured handle: \`const s = scope(); s.${name}(...)\`).`,
+                    `abide: bare \`${name}(...)\` is not allowed — a reactive primitive lives on a scope. Use \`scope().${name}(...)\` (or a captured handle: \`const s = scope(); s.${name}(...)\`).`,
                 )
             }
             if (name === 'prop') {