@abide/abide 0.34.2 → 0.35.0

package/src/lib/server/runtime/flushingGzipStream.ts

@@ -0,0 +1,62 @@
+import { constants, createGzip } from 'node:zlib'
+
+/*
+A gzip TransformStream that emits a decodable block after every input chunk via
+Z_SYNC_FLUSH, instead of buffering until its deflate window fills like the web
+CompressionStream. Used for the streamed SSR document so the head reaches the
+browser compressed-but-decodable immediately — the preload scanner sees the
+entry/css links and the pending shell paints — rather than only at stream close.
+node:zlib is required here: the web CompressionStream exposes no per-chunk flush.
+*/
+export function flushingGzipStream(): TransformStream<Uint8Array, Uint8Array> {
+    const gzip = createGzip()
+    let sink: TransformStreamDefaultController<Uint8Array>
+    /* `closed` gates enqueue: once the consumer cancels (client disconnect), the node
+       gzip can still emit a trailing `data` that would throw on the closed controller. */
+    let closed = false
+    gzip.on('data', (chunk: Buffer) => {
+        if (closed) {
+            return
+        }
+        /* enqueue can still race a just-closed controller (cancel is async); treat the
+           throw as the consumer having gone and tear down. */
+        try {
+            sink.enqueue(new Uint8Array(chunk))
+        } catch {
+            closed = true
+            gzip.destroy()
+        }
+    })
+    /* The spec'd Transformer.cancel hook (consumer-cancellation) postdates this TS lib's
+       Transformer type; declare it locally so the literal type-checks while the platform
+       (Bun) still invokes it. Typing the const sidesteps the fresh-literal excess-property
+       check without weakening start/transform/flush. */
+    const transformer: Transformer<Uint8Array, Uint8Array> & {
+        cancel(reason?: unknown): void
+    } = {
+        start(controller) {
+            sink = controller
+            gzip.on('error', (error) => controller.error(error))
+        },
+        /* Resolve only once the chunk is compressed AND sync-flushed, so its bytes are
+           on the wire before the stream pulls the next (possibly delayed) chunk. */
+        transform(chunk) {
+            return new Promise((resolve) => {
+                gzip.write(chunk, () => gzip.flush(constants.Z_SYNC_FLUSH, () => resolve()))
+            })
+        },
+        /* End the deflate stream; its trailing bytes arrive as `data` before `end`. */
+        flush() {
+            return new Promise((resolve) => {
+                gzip.on('end', () => resolve())
+                gzip.end()
+            })
+        },
+        /* Consumer went away — stop enqueueing and tear down the node stream. */
+        cancel() {
+            closed = true
+            gzip.destroy()
+        },
+    }
+    return new TransformStream(transformer)
+}

package/src/lib/server/runtime/gzipResponse.ts

@@ -1,5 +1,7 @@
 import { isStreamingResponse } from '../../shared/isStreamingResponse.ts'
 import { acceptsGzip } from './acceptsGzip.ts'
+import { flushingGzipStream } from './flushingGzipStream.ts'
+import { STREAMED_HTML_HEADER } from './STREAMED_HTML_HEADER.ts'
 
 /*
 Compressible Content-Types — text and structured-text payloads. Binary or
@@ -11,18 +13,27 @@ const COMPRESSIBLE_TYPE =
 
 /*
 Gzips a dynamic response (SSR HTML, rpc/json replies, the plain 404) when the
-client accepts it, piping the body through a CompressionStream so a buffered
-body and a streamed SSR document take the identical path. Static assets never
-reach here — they already carry a precompressed Content-Encoding, which
-short-circuits the first guard. Skipped for: already-encoded bodies, bodiless
-responses (204/304/HEAD), non-compressible types (images, fonts, archives),
-and frame-delimited streams (SSE/jsonl, where gzip buffering would stall
-per-frame flush). No byte-size floor: Bun doesn't expose a string body's length
-before send, and measuring would mean buffering the streamed SSR document —
-the framing overhead on the rare tiny body is negligible against compressing
-every page and rpc payload.
+client accepts it. Static assets never reach here — they already carry a
+precompressed Content-Encoding, which short-circuits the first guard. Skipped
+for: already-encoded bodies, bodiless responses (204/304/HEAD), non-compressible
+types (images, fonts, archives), and frame-delimited streams (SSE/jsonl, where
+gzip buffering would stall per-frame flush). No byte-size floor: Bun doesn't
+expose a string body's length before send, and measuring would mean buffering the
+body — the framing overhead on the rare tiny body is negligible against
+compressing every page and rpc payload.
+
+Buffered bodies take the web CompressionStream (best ratio, one flush at close).
+The streamed SSR document self-marks (STREAMED_HTML_HEADER) and takes a
+per-chunk-flushing gzip instead: the plain CompressionStream buffers the head
+until its deflate window fills, which defeats streaming (the browser can't
+preload-scan the head or paint the pending shell until the stream nearly closes).
+The marker is stripped so it never reaches the client.
 */
 export function gzipResponse(req: Request, response: Response): Response {
+    const streamedHtml = response.headers.has(STREAMED_HTML_HEADER)
+    if (streamedHtml) {
+        response.headers.delete(STREAMED_HTML_HEADER)
+    }
     if (!response.body || response.headers.has('Content-Encoding')) {
         return response
     }
@@ -38,7 +49,8 @@ export function gzipResponse(req: Request, response: Response): Response {
     headers.append('Vary', 'Accept-Encoding')
     /* The stored length no longer matches the compressed body (and is unknown for a stream). */
     headers.delete('Content-Length')
-    return new Response(response.body.pipeThrough(new CompressionStream('gzip')), {
+    const compressor = streamedHtml ? flushingGzipStream() : new CompressionStream('gzip')
+    return new Response(response.body.pipeThrough(compressor), {
         status: response.status,
         statusText: response.statusText,
         headers,

package/src/lib/server/runtime/serializeCacheSnapshot.ts

@@ -1,45 +1,34 @@
 import { isReplayableMethod } from '../../shared/isReplayableMethod.ts'
-import type { CacheEntry } from '../../shared/types/CacheEntry.ts'
-import type { CacheSnapshot } from '../../shared/types/CacheSnapshot.ts'
 import type { CacheSnapshotEntry } from '../../shared/types/CacheSnapshotEntry.ts'
 import type { CacheStore } from '../../shared/types/CacheStore.ts'
 import { snapshotEntryFromCache } from './snapshotEntryFromCache.ts'
 
 /*
-Partitions the request-scoped cache for SSR. Entries settled by the time
-`render()` returns were consumed via `await` (render blocked on them) and ship
-inline in the document's `__SSR__` blob. Entries still pending were consumed
-via `{#await}` — render emitted their pending branch without blocking — so they
-go to `pending` for the response streamer to drain and resolve over the wire.
+Snapshots the request-scoped cache for SSR at a single instant: every replayable
+(GET/DELETE) entry settled by now, serialized to a wire-safe CacheSnapshotEntry the
+client seeds its store from. Unsettled and non-replayable entries are skipped; a body
+that can't ship (binary / streaming / rejected) drops out via snapshotEntryFromCache.
 
-Unlike the old buffer-everything path, this never awaits the pending promises:
-that's the whole point of streaming. Settled entries are read concurrently (the
-awaits are immediate since they're already resolved, but their body reads run in
-parallel); pending entries are handed back as-is for the streamer to await one
-chunk at a time.
+Snapshots concurrently — the awaits are immediate (entries are already settled), but
+their body reads run in parallel. Never blocks on an unsettled entry.
+
+WHEN it's called decides what it sees. createUiPageRenderer calls it at render-return
+for `__SSR__` — that catches only top-level `await` reads (render blocked on them). A
+`{#await cache()}` read does NOT appear: its expression is a thunk renderToStream runs
+lazily, so its entry is created mid-stream, after this snapshot. The renderer snapshots
+AGAIN once the stream has drained (entries then exist and are settled) and seeds those
+over the wire — see its post-stream `__abideResolve` pass. So for a streaming page the
+render-return snapshot is typically empty; the warm cache arrives over the stream.
 */
-export async function serializeCacheSnapshot(store: CacheStore): Promise<CacheSnapshot> {
-    const settled: CacheEntry[] = []
-    const pending: CacheEntry[] = []
-    for (const entry of store.entries.values()) {
-        /* Producer entries carry no wire request — nothing to rehydrate against, skip. */
-        if (!entry.request) {
-            continue
-        }
-        if (!isReplayableMethod(entry.request.method.toUpperCase())) {
-            continue
-        }
-        if (entry.settled) {
-            settled.push(entry)
-        } else {
-            pending.push(entry)
-        }
-    }
+export async function serializeCacheSnapshot(store: CacheStore): Promise<CacheSnapshotEntry[]> {
+    const settled = Array.from(store.entries.values()).filter(
+        (entry) =>
+            entry.settled === true &&
+            entry.request !== undefined &&
+            isReplayableMethod(entry.request.method.toUpperCase()),
+    )
     const snapshots = await Promise.all(
         settled.map((entry) => snapshotEntryFromCache(store, entry)),
     )
-    const inline = snapshots.filter(
-        (snapshot): snapshot is CacheSnapshotEntry => snapshot !== undefined,
-    )
-    return { inline, pending }
+    return snapshots.filter((snapshot): snapshot is CacheSnapshotEntry => snapshot !== undefined)
 }

package/src/lib/ui/README.md

@@ -36,7 +36,7 @@ every page, and `.abide` files are the only component format.
 
 ## Idioms
 
-- **Signals are the surface**: `state(v)`, `derived(fn)`, `effect(fn)`, `prop(name)`.
+- **Signals are the surface**: `state(v)`, `derived(fn)`, `effect(fn)`, `props()`.
   You write plain assignment (`count += 1`, `items.push(x)`); the compiler lowers
   it. Templates auto-read (`{count}`); ordering and cross-references compose.
 - **Everything dynamic lives in `{ }`** — `{expr}` text, `name={expr}`,

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

@@ -1,12 +1,12 @@
 /* The callee names the `.abide` compiler recognises as reactive declarations
-   (`let x = state(...)`, `linked(...)`, `computed(...)`, `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. */
+   (`let x = state(...)`, `linked(...)`, `computed(...)`, and the destructuring
+   `const {…} = props()`): 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',
     'computed',
-    'prop',
+    'props',
 ])

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

@@ -32,6 +32,7 @@ export const UI_RUNTIME_IMPORTS: { name: string; specifier: string }[] = [
     { name: 'mountSlot', specifier: 'ui/dom/mountSlot' },
     { name: 'mountChild', specifier: 'ui/dom/mountChild' },
     { name: 'hydrate', specifier: 'ui/dom/hydrate' },
+    { name: 'escapeKey', specifier: 'ui/runtime/escapeKey' },
     { name: 'nextBlockId', specifier: 'ui/runtime/nextBlockId' },
     { name: 'enterRenderPass', specifier: 'ui/runtime/enterRenderPass' },
     { name: 'exitRenderPass', specifier: 'ui/runtime/exitRenderPass' },

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

@@ -12,9 +12,10 @@ calls type-check — `scope()` is the authored reactive surface (`scope().state(
 `.computed(...)` / `.undo()` …), so it must resolve like any import. `state`/`linked`/
 `computed` are ALSO declared ambiently as a fallback for the rare bare/nested use the
 top-level rewrite doesn't project (their top-level declarations become value types, so
-these are normally unused — fine, the shadow disables noUnusedLocals). `prop` is sugar
-too, but every `prop()` declaration is rewritten away, so it never appears here.
-`$props` is the legacy untyped prop bag (pre-`prop()` sugar) made available raw.
+these are normally unused — fine, the shadow disables noUnusedLocals). `props` is the prop
+reader — destructured (`const { a = 1 } = props<Shape>()`); declared returning its type
+argument (default `Record<string, any>`) so each binding inherits its prop type and its
+`= default` narrows.
 */
 const SHADOW_PREAMBLE = `import { effect } from '${ABIDE_PACKAGE_NAME}/ui/effect'
 import { html } from '${ABIDE_PACKAGE_NAME}/shared/html'
@@ -23,7 +24,7 @@ import { scope } from '${ABIDE_PACKAGE_NAME}/ui/scope'
 declare function state<T>(initial?: T, transform?: (next: T, previous: T) => T): { value: T }
 declare function linked<T>(seed: () => T, transform?: (next: T, previous: T) => T): { value: T }
 declare function computed<T>(compute: () => T): { readonly value: T }
-declare const $props: Record<string, (() => unknown) | undefined>
+declare function props<T = Record<string, any>>(): T
 void [effect, html, snippet, scope]
 `
 
@@ -36,9 +37,9 @@ expressions and child-component props, with diagnostics mapped back through the
 returned segments.
 
 The script's signal surface is rewritten to value types:
-  let count = state(0)            →  let count = (0)
-  const total = computed(() => …)  →  const total = (() => …)()
-  let title = prop<string>('t')   →  Props field + `let title = props['t']`
+  let count = state(0)               →  let count = (0)
+  const total = computed(() => …)     →  const total = (() => …)()
+  const { a } = props<{ a: T }>()    →  `__Props = { a: T }` + the verbatim destructure
 Everything else (functions, plain consts, imports) is emitted verbatim, so
 expressions inside it (e.g. a computed's compute body) are checked and mapped too.
 */
@@ -50,7 +51,7 @@ 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, types, scope, props } = analyzeScript(scriptBody, scriptStart)
+    const { imports, types, scope, propsShapes } = analyzeScript(scriptBody, scriptStart)
     builder.raw(SHADOW_PREAMBLE)
     for (const line of imports) {
         builder.flush(line)
@@ -62,11 +63,20 @@ export function compileShadow(source: string): CompiledShadow {
     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')
+    /* `__Props` is the parent-facing prop shape: each `props<Shape>()` destructure
+       contributes its whole `Shape` (intersected if there's more than one), or an empty
+       object for a component that reads no props. */
+    builder.raw(
+        propsShapes.length > 0
+            ? `type __Props = ${propsShapes.join(' & ')}\n`
+            : `interface __Props {}\n`,
+    )
+    /* `__props` (not `props`) so the destructuring `props()` sugar resolves to the
+       declared function, not this parameter. async so `await` blocks are legal; never
+       executed, so the return is void. */
+    builder.raw('export default async function (__props: __Props): Promise<void> {\n')
     /* Reference props so an all-optional bag with no reads doesn't read as unused. */
-    builder.raw('void props;\n')
+    builder.raw('void __props;\n')
     for (const line of scope) {
         builder.flush(line)
     }
@@ -137,20 +147,20 @@ type ScriptAnalysis = {
     imports: ScopeLine[]
     types: ScopeLine[]
     scope: ScopeLine[]
-    props: string[]
+    propsShapes: string[]
 }
 
 /* Walks the leading `<script>` and produces the shadow's module imports, the
-   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. */
+   module-scope type declarations, the value-typed scope lines, and the `props<Shape>()`
+   prop shapes. `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[] = []
+    const propsShapes: string[] = []
     if (scriptBody.trim() === '') {
-        return { imports, types, scope, props }
+        return { imports, types, scope, propsShapes }
     }
     const file = ts.createSourceFile('script.ts', scriptBody, ts.ScriptTarget.Latest, true)
     /* A verbatim span: original text + the segment mapping it back, relative to the
@@ -180,10 +190,10 @@ function analyzeScript(scriptBody: string, scriptStart: number): ScriptAnalysis
             continue
         }
         for (const declaration of reactive) {
-            scope.push(scopeLineFor(declaration, props, verbatim, span))
+            scope.push(scopeLineFor(declaration, propsShapes, verbatim, span))
         }
     }
-    return { imports, types, scope, props }
+    return { imports, types, scope, propsShapes }
 }
 
 /* Value-projects a nested control-flow `<script>` body the way `analyzeScript`
@@ -207,8 +217,8 @@ function projectNestedScript(code: string): string {
         .join('\n')
 }
 
-/* The `state`/`computed`/`prop` declarations in a variable statement, or undefined
-   if it isn't one declaring them (so the caller emits it verbatim). A statement
+/* The `state`/`computed`/`linked`/`props()` declarations in a variable statement, or
+   undefined if it isn't one declaring them (so the caller emits it verbatim). A statement
    mixing reactive and plain declarations is rare; treated as all-verbatim. */
 function reactiveDeclarations(statement: ts.Statement): ts.VariableDeclaration[] | undefined {
     if (!ts.isVariableStatement(statement)) {
@@ -220,7 +230,7 @@ function reactiveDeclarations(statement: ts.Statement): ts.VariableDeclaration[]
 }
 
 /* The callee name of a `NAME = state(...)` / `linked(...)` / `computed(...)` /
-   `prop(...)` decl — bare or the explicit scope form (`scope().state(...)` / `c.state(...)`),
+   `props()` decl — bare or the explicit scope form (`scope().state(...)` / `c.state(...)`),
    receiver-agnostic (the method name marks it reactive). */
 function signalCallee(declaration: ts.VariableDeclaration): string | undefined {
     const initializer = declaration.initializer
@@ -237,10 +247,10 @@ function signalCallee(declaration: ts.VariableDeclaration): string | undefined {
 }
 
 /* Builds one scope line for a reactive declaration, projecting it to its value
-   type. `prop` also contributes a Props field (pushed into `props`). */
+   type. A `props()` destructure contributes its whole shape (pushed into `propsShapes`). */
 function scopeLineFor(
     declaration: ts.VariableDeclaration,
-    props: string[],
+    propsShapes: string[],
     verbatim: (node: ts.Node) => string,
     span: (node: ts.Node, prefixLength: number) => ShadowMapping,
 ): ScopeLine {
@@ -250,6 +260,14 @@ function scopeLineFor(
     const callee = ts.isPropertyAccessExpression(call.expression)
         ? call.expression.name.text
         : (call.expression as ts.Identifier).text
+    if (callee === 'props') {
+        /* `const {…} = props<Shape>()`: the type arg (default `Record<string, any>`)
+           IS the parent-facing prop shape, and the destructure projects verbatim against
+           the declared typed `props()` so each binding inherits its value type. */
+        const shape = call.typeArguments?.[0]
+        propsShapes.push(shape === undefined ? 'Record<string, any>' : verbatim(shape))
+        return { text: `const ${verbatim(declaration)};`, segments: [span(declaration, 6)] }
+    }
     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. */
@@ -273,40 +291,27 @@ function scopeLineFor(
             segments: [span(declaration.name, 4), span(init, prefix.length)],
         }
     }
-    if (callee === 'computed' || callee === 'linked') {
-        /* computed<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]
-        /* `linked` is a writable `State<T>` at runtime (it reseeds AND accepts `.value =`
-           writes), so project it as `let`; `computed` is genuinely read-only, so `const`. */
-        const keyword = callee === 'linked' ? 'let' : 'const'
-        /* binding-name map offset = past the keyword + space (`let ` = 4, `const ` = 6) */
-        const keywordOffset = keyword.length + 1
-        if (fn === undefined) {
-            return {
-                text: `${keyword} ${name} = undefined;`,
-                segments: [span(declaration.name, keywordOffset)],
-            }
-        }
-        const prefix = `${keyword} ${name}${annotation} = (`
+    /* 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
+       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]
+    /* `linked` is a writable `State<T>` at runtime (it reseeds AND accepts `.value =`
+       writes), so project it as `let`; `computed` is genuinely read-only, so `const`. */
+    const keyword = callee === 'linked' ? 'let' : 'const'
+    /* binding-name map offset = past the keyword + space (`let ` = 4, `const ` = 6) */
+    const keywordOffset = keyword.length + 1
+    if (fn === undefined) {
         return {
-            text: `${prefix}${verbatim(fn)})();`,
-            segments: [span(declaration.name, keywordOffset), span(fn, prefix.length)],
+            text: `${keyword} ${name} = undefined;`,
+            segments: [span(declaration.name, keywordOffset)],
         }
     }
-    /* prop<T>('key'): Props field `key[?]: T`, scope binding read from props. */
-    const key = call.arguments[0]
-    const keyText = key !== undefined && ts.isStringLiteralLike(key) ? key.text : name
-    const typeNode = call.typeArguments?.[0]
-    const typeText = typeNode === undefined ? 'unknown' : verbatim(typeNode)
-    const optional = typeNode === undefined || /\bundefined\b/.test(typeText)
-    props.push(`    ${JSON.stringify(keyText)}${optional ? '?' : ''}: ${typeText}`)
+    const prefix = `${keyword} ${name}${annotation} = (`
     return {
-        text: `let ${name} = props[${JSON.stringify(keyText)}];`,
-        segments: [span(declaration.name, 4)],
+        text: `${prefix}${verbatim(fn)})();`,
+        segments: [span(declaration.name, keywordOffset), span(fn, prefix.length)],
     }
 }