@torpor/view 1.0.3 → 1.1.1

package/dist/ssr.cjs

@@ -22,14 +22,124 @@ function formatServerText(value) {
 	return require_fromWebSocket.formatText(value).replace(/[&<>]/g, (c) => ESCAPABLE[c]);
 }
 //#endregion
-//#region src/ssr/$serverAsync.ts
+//#region src/ssr/serverAwaitState.ts
 /**
-* Server no-op for the client-side `$async` getter primitive. Server renders
-* are synchronous, so an async value never resolves during SSR — `@await`
+* The sentinel thrown when the render pass hits a boundary state that the
+* collect pass didn't create (or a cursor that ran past the recorded reads).
+* Only this error degrades the boundary; real render errors propagate.
+*/
+var ServerAwaitMisaligned = class extends Error {
+	constructor() {
+		super("Server await render pass did not match the collect pass");
+	}
+};
+/** The innermost active server await state, or null outside any. */
+let current = null;
+/**
+* Runs `fn` with `state` as the current server await state. `fn` may be sync
+* or async; the pointer is restored when it settles. Because the pointer is
+* only read synchronously, interleaved async renders restore it correctly.
+*/
+async function withServerAwait(state, fn) {
+	const previous = current;
+	current = state;
+	try {
+		return await fn();
+	} finally {
+		current = previous;
+	}
+}
+/** The current server await state, or null. Only read synchronously. */
+function currentServerAwait() {
+	return current;
+}
+/** Creates a fresh state for one boundary (or component flush root). */
+function newServerAwaitState() {
+	return {
+		phase: "collect",
+		promises: [],
+		cursor: 0,
+		renderReads: 0,
+		clientReads: 0,
+		children: /* @__PURE__ */ new Map(),
+		counters: /* @__PURE__ */ new Map(),
+		degraded: false,
+		isRoot: false,
+		sentinels: /* @__PURE__ */ new Map()
+	};
+}
+/**
+* The occurrence key for a nested boundary call site: `"<id>:<n>"`. The
+* counter lives on the enclosing state and resets each pass, so the collect
+* and render passes derive identical key sequences.
+*/
+function childKey(state, id) {
+	const n = state.counters.get(id) ?? 0;
+	state.counters.set(id, n + 1);
+	return `${id}:${n}`;
+}
+/**
+* Server counterpart of the client-side `$async` getter primitive.
+*
+* Without options (the default), this is a no-op stub: server renders are
+* synchronous, an async value never resolves during SSR, and `@await`
 * boundaries render their `with` branch and never read the getter. The stub
 * exists so server builds importing `$async` don't emit a dangling import.
+* A read inside a boundary's render pass is still recorded, so the boundary
+* degrades to the `with` branch + client fetch instead of shipping content
+* that would suspend on the client.
+*
+* With `{ source: "server" }` the getter participates in the server's
+* collect/render pass (ASYNC.md → "Server rendering"):
+*
+* - **Collect pass** — calls the thunk (starting the fetch) and records the
+*   promise on the enclosing boundary, so sibling reads start in one wave.
+*   Returns `undefined`; the speculative pass's output is discarded.
+* - **Render pass** — returns the settled value from the recorded promise at
+*   the same position in read order, without calling the thunk again. A
+*   rejection is re-thrown here so `@try`/`@error` handles it like any other
+*   render error. Running past the recorded reads throws a sentinel that
+*   degrades the boundary (the render pass no longer matches the collect
+*   pass, so the shipped HTML can't be trusted).
+*
+* Outside any `@await` boundary (including in a `with` branch) a
+* `source: "server"` read returns `undefined` without fetching — the same
+* undefined-then-recover contract the client has for un-boundaried reads.
 */
-function $serverAsync(_fn) {}
+function $serverAsync(fn, options) {
+	const state = currentServerAwait();
+	if (state === null || state.isRoot || options?.source !== "server") {
+		if (state !== null && !state.isRoot && state.phase === "render") state.clientReads++;
+		return;
+	}
+	if (state.phase === "collect") {
+		const entry = {
+			promise: fn(),
+			timeout: options.timeout ?? 5e3
+		};
+		entry.promise.then((value) => {
+			entry.result = {
+				ok: true,
+				value
+			};
+		}, (error) => {
+			entry.result = {
+				ok: false,
+				error
+			};
+		});
+		state.promises.push(entry);
+		return;
+	}
+	const index = state.cursor;
+	if (index >= state.promises.length) throw new ServerAwaitMisaligned();
+	state.cursor++;
+	state.renderReads++;
+	const result = state.promises[index].result;
+	if (result === void 0) throw new ServerAwaitMisaligned();
+	if (result.ok) return result.value;
+	throw result.error;
+}
 //#endregion
 //#region src/ssr/$serverBatch.ts
 function $serverBatch(fn) {
@@ -96,6 +206,182 @@ function $serverUnwrap(object) {
 function $serverWatch(object) {
 	return object;
 }
+/**
+* Renders a component's (or a degraded boundary's `with` branch's) markup
+* with a fresh flush root as the enclosing await state, then substitutes any
+* boundary sentinels with their final HTML.
+*
+* Boundaries created during the render stash their lifecycle promise under a
+* sentinel comment and return the sentinel immediately, so the render itself
+* never blocks on a fetch — every `source: "server"` read in the render
+* starts in the same wave. Substitution awaits the stashed promises at the
+* end, which is the only point an async component render actually waits.
+*
+* On the client this has no counterpart: `render` here is the compiled
+* component body closure that the generated component function returns.
+*/
+async function serverFlush(render) {
+	const state = newServerAwaitState();
+	state.isRoot = true;
+	return substituteSentinels(await withServerAwait(state, render), state);
+}
+/**
+* Renders a degraded boundary's `with` branch inside its own flush root, so
+* a `with` branch containing its own `@await` boundaries still resolves
+* them, then wraps it in the boundary's hydration markers. The `with` branch
+* must not start server fetches for its own reads — the flush root isn't a
+* recording context.
+*/
+async function renderWithBranch(renderWith) {
+	const html = await serverFlush(async () => {
+		if (renderWith === null) return {
+			body: "",
+			head: ""
+		};
+		return renderWith();
+	});
+	return {
+		body: `<![>${html.body}<!]><!>`,
+		head: html.head
+	};
+}
+/**
+* Replaces every sentinel the state stashed with its boundary's final HTML.
+* Boundary head tags are appended to the head (they hoist into the document
+* head regardless of where the boundary sits in the body). Any sentinel left
+* over means a boundary's state was lost — a bug, not a degradation path, so
+* it throws.
+*/
+async function substituteSentinels(result, state) {
+	let { body, head } = result;
+	for (const [sentinel, promise] of state.sentinels) {
+		const html = await promise;
+		body = body.split(sentinel).join(html.body);
+		head += html.head;
+	}
+	if (body.includes("<!--t-aw:") || head.includes("<!--t-aw:")) throw new Error("Unsubstituted async boundary sentinel — boundary state was lost");
+	return {
+		body,
+		head
+	};
+}
+//#endregion
+//#region src/ssr/runServerAwait.ts
+let sentinelCount = 0;
+function nextSentinel() {
+	return `<!--t-aw:${sentinelCount++}-->`;
+}
+/**
+* Renders an `@await` boundary on the server (compiled as `t_await_server`).
+*
+* The generated code calls this for every `@await`, passing the boundary's
+* site id, a closure that renders the content branch, and one that renders
+* the `with` branch. It always returns a `{ body, head }` pair to append:
+*
+* - **Inside a boundary's render pass** — this boundary was already started
+*   during the collect pass; its body/head is the finished HTML (awaited if
+*   still in flight). A missing entry means the render pass doesn't match
+*   the collect pass, which degrades the enclosing boundary.
+* - **Inside a collect pass or a component flush** — start the full
+*   lifecycle (collect, settle, render) without blocking the enclosing
+*   render, and return a sentinel comment as the body. Sibling reads and
+*   nested boundaries keep rendering, so every fetch in the pass starts in
+*   one wave. The sentinel is substituted later: by the enclosing boundary's
+*   render pass (which re-invokes this helper and awaits the finished HTML),
+*   or by the component flush (which replaces top-level sentinels directly).
+*
+* The lifecycle: render content once to start the `source: "server"` fetches
+* (discarding the output), wait for them with a per-getter timeout, then
+* render again with the settled values. The second pass ships wrapped in
+* hydration markers plus a `<!--t-await:...-->` comment carrying the values
+* for the client's `$async` hydration path. Any instability — timeout, a
+* render pass that reads a different set of getters, a client-fetch read —
+* degrades to the `with` branch + client fetch, exactly the pre-`source`
+* behavior.
+*
+* @param id The boundary's site id (unique per `@await` in the component)
+* @param renderContent Renders the content branch (may read `$async` getters)
+* @param renderWith Renders the `with` branch, or null for empty
+*/
+function runServerAwait(id, renderContent, renderWith) {
+	const parent = currentServerAwait();
+	if (parent !== null && parent.phase === "render") {
+		const cached = parent.children.get(childKey(parent, id));
+		if (cached === void 0) throw new ServerAwaitMisaligned();
+		return cached;
+	}
+	const final = renderBoundary(newServerAwaitState(), renderContent, renderWith);
+	const sentinel = nextSentinel();
+	if (parent !== null) {
+		if (parent.isRoot) parent.sentinels.set(sentinel, final);
+		else parent.children.set(childKey(parent, id), final);
+	}
+	return {
+		body: sentinel,
+		head: ""
+	};
+}
+/**
+* The full lifecycle for one boundary: speculative collect pass, settle, and
+* resolved render pass. Runs concurrently with the enclosing render; the
+* returned promise resolves to the boundary's final HTML.
+*/
+async function renderBoundary(state, renderContent, renderWith) {
+	await withServerAwait(state, renderContent).catch(() => {});
+	if (state.promises.length === 0) return renderWithBranch(renderWith);
+	const timeout = Math.max(...state.promises.map((entry) => entry.timeout));
+	let degraded = await Promise.race([Promise.all(state.promises.map((entry) => entry.promise.then(() => true, () => true))).then(() => true, () => true), new Promise((resolve) => setTimeout(resolve, timeout, false))]) === false;
+	let content;
+	if (!degraded) {
+		state.phase = "render";
+		state.cursor = 0;
+		state.renderReads = 0;
+		state.clientReads = 0;
+		state.counters.clear();
+		try {
+			content = await withServerAwait(state, renderContent);
+			if (state.cursor !== state.promises.length || state.clientReads > 0) degraded = true;
+		} catch {
+			degraded = true;
+		}
+	}
+	if (degraded || content === void 0) {
+		state.degraded = true;
+		try {
+			return await renderWithBranch(renderWith);
+		} catch {
+			return {
+				body: "<![><!]><!>",
+				head: ""
+			};
+		}
+	}
+	const values = [];
+	for (let i = 0; i < state.cursor; i++) {
+		const result = state.promises[i].result;
+		if (result === void 0) {
+			degraded = true;
+			break;
+		}
+		values.push(result.ok ? result.value : void 0);
+	}
+	if (degraded) {
+		state.degraded = true;
+		return renderWithBranch(renderWith);
+	}
+	return {
+		body: `<![>${content.body}<!]><!>${payloadComment(values)}`,
+		head: content.head
+	};
+}
+/**
+* The `<!--t-await:...-->` comment carrying the boundary's resolved values,
+* in read order, for the client's `$async` hydration path. `-->` inside the
+* JSON is escaped so the comment can't terminate early.
+*/
+function payloadComment(values) {
+	return `<!--t-await:${JSON.stringify(values).replaceAll("-->", "--\\u003E")}-->`;
+}
 //#endregion
 exports.$async = $serverAsync;
 exports.$batch = $serverBatch;
@@ -113,6 +399,8 @@ exports.fromElement = require_fromWebSocket.fromElement;
 exports.fromServer = require_fromWebSocket.fromServer;
 exports.fromWebSocket = require_fromWebSocket.fromWebSocket;
 exports.t_attr = formatAttributeText;
+exports.t_await_server = runServerAwait;
 exports.t_class = require_fromWebSocket.buildClasses;
 exports.t_fmt = formatServerText;
+exports.t_server_flush = serverFlush;
 exports.t_style = require_fromWebSocket.buildStyles;

package/dist/ssr.d.cts

@@ -1,5 +1,5 @@
 import { t as Cleanup } from "./Cleanup-D0wvGW5d.cjs";
-import { a as buildStyles, i as StreamSource, n as fromServer, r as fromElement, s as buildClasses, t as fromWebSocket } from "./fromWebSocket-DeB35Q4w.cjs";
+import { a as StreamSource, c as buildClasses, i as fromElement, n as fromWebSocket, o as buildStyles, r as fromServer, t as AsyncOptions } from "./AsyncOptions-BtMe2PAd.cjs";
 //#region src/render/formatAttributeText.d.ts
 declare function formatAttributeText(value: any): string;
 //#endregion
@@ -15,12 +15,34 @@ declare function formatServerText(value: any): string;
 //#endregion
 //#region src/ssr/$serverAsync.d.ts
 /**
- * Server no-op for the client-side `$async` getter primitive. Server renders
- * are synchronous, so an async value never resolves during SSR — `@await`
+ * Server counterpart of the client-side `$async` getter primitive.
+ *
+ * Without options (the default), this is a no-op stub: server renders are
+ * synchronous, an async value never resolves during SSR, and `@await`
  * boundaries render their `with` branch and never read the getter. The stub
  * exists so server builds importing `$async` don't emit a dangling import.
+ * A read inside a boundary's render pass is still recorded, so the boundary
+ * degrades to the `with` branch + client fetch instead of shipping content
+ * that would suspend on the client.
+ *
+ * With `{ source: "server" }` the getter participates in the server's
+ * collect/render pass (ASYNC.md → "Server rendering"):
+ *
+ * - **Collect pass** — calls the thunk (starting the fetch) and records the
+ *   promise on the enclosing boundary, so sibling reads start in one wave.
+ *   Returns `undefined`; the speculative pass's output is discarded.
+ * - **Render pass** — returns the settled value from the recorded promise at
+ *   the same position in read order, without calling the thunk again. A
+ *   rejection is re-thrown here so `@try`/`@error` handles it like any other
+ *   render error. Running past the recorded reads throws a sentinel that
+ *   degrades the boundary (the render pass no longer matches the collect
+ *   pass, so the shipped HTML can't be trusted).
+ *
+ * Outside any `@await` boundary (including in a `with` branch) a
+ * `source: "server"` read returns `undefined` without fetching — the same
+ * undefined-then-recover contract the client has for un-boundaried reads.
  */
-declare function $serverAsync<T>(_fn: () => Promise<T>): T;
+declare function $serverAsync<T>(fn: () => Promise<T>, options?: AsyncOptions): T;
 //#endregion
 //#region src/ssr/$serverBatch.d.ts
 declare function $serverBatch<T>(fn: () => T): T;
@@ -78,17 +100,94 @@ declare function $serverUnwrap<T extends Record<PropertyKey, any>>(object: T): T
 //#region src/ssr/$serverWatch.d.ts
 declare function $serverWatch<T extends Record<PropertyKey, any>>(object: T): T;
 //#endregion
+//#region src/ssr/runServerAwait.d.ts
+/**
+ * Renders an `@await` boundary on the server (compiled as `t_await_server`).
+ *
+ * The generated code calls this for every `@await`, passing the boundary's
+ * site id, a closure that renders the content branch, and one that renders
+ * the `with` branch. It always returns a `{ body, head }` pair to append:
+ *
+ * - **Inside a boundary's render pass** — this boundary was already started
+ *   during the collect pass; its body/head is the finished HTML (awaited if
+ *   still in flight). A missing entry means the render pass doesn't match
+ *   the collect pass, which degrades the enclosing boundary.
+ * - **Inside a collect pass or a component flush** — start the full
+ *   lifecycle (collect, settle, render) without blocking the enclosing
+ *   render, and return a sentinel comment as the body. Sibling reads and
+ *   nested boundaries keep rendering, so every fetch in the pass starts in
+ *   one wave. The sentinel is substituted later: by the enclosing boundary's
+ *   render pass (which re-invokes this helper and awaits the finished HTML),
+ *   or by the component flush (which replaces top-level sentinels directly).
+ *
+ * The lifecycle: render content once to start the `source: "server"` fetches
+ * (discarding the output), wait for them with a per-getter timeout, then
+ * render again with the settled values. The second pass ships wrapped in
+ * hydration markers plus a `<!--t-await:...-->` comment carrying the values
+ * for the client's `$async` hydration path. Any instability — timeout, a
+ * render pass that reads a different set of getters, a client-fetch read —
+ * degrades to the `with` branch + client fetch, exactly the pre-`source`
+ * behavior.
+ *
+ * @param id The boundary's site id (unique per `@await` in the component)
+ * @param renderContent Renders the content branch (may read `$async` getters)
+ * @param renderWith Renders the `with` branch, or null for empty
+ */
+declare function runServerAwait(id: string, renderContent: () => Promise<{
+  body: string;
+  head: string;
+}>, renderWith: (() => Promise<{
+  body: string;
+  head: string;
+}>) | null): {
+  body: string;
+  head: string;
+} | Promise<{
+  body: string;
+  head: string;
+}>;
+//#endregion
+//#region src/ssr/serverSentinels.d.ts
+/** The body/head pair that server components and boundaries render into. */
+interface ServerHtml {
+  body: string;
+  head: string;
+}
+/**
+ * Renders a component's (or a degraded boundary's `with` branch's) markup
+ * with a fresh flush root as the enclosing await state, then substitutes any
+ * boundary sentinels with their final HTML.
+ *
+ * Boundaries created during the render stash their lifecycle promise under a
+ * sentinel comment and return the sentinel immediately, so the render itself
+ * never blocks on a fetch — every `source: "server"` read in the render
+ * starts in the same wave. Substitution awaits the stashed promises at the
+ * end, which is the only point an async component render actually waits.
+ *
+ * On the client this has no counterpart: `render` here is the compiled
+ * component body closure that the generated component function returns.
+ */
+declare function serverFlush(render: () => Promise<ServerHtml>): Promise<ServerHtml>;
+//#endregion
 //#region src/types/ServerSlotRender.d.ts
-type ServerSlotRender = ($slot?: Record<PropertyKey, any>, $context?: Record<PropertyKey, any>) => string;
+/**
+ * Renders a slot fill to HTML. Async so the fill can contain an `@await`
+ * boundary with a `source: "server"` getter (ASYNC.md → "Server rendering").
+ */
+type ServerSlotRender = ($slot?: Record<PropertyKey, any>, $context?: Record<PropertyKey, any>) => Promise<string>;
 //#endregion
 //#region src/types/ServerComponent.d.ts
 /**
- * A component that generates HTML
+ * A component that generates HTML. Server components are async so that a
+ * `source: "server"` `@await` boundary can fetch during the render (see
+ * ASYNC.md → "Server rendering"); call sites await the result, which also
+ * accepts the plain object a component without boundaries effectively
+ * resolves to.
  */
-type ServerComponent = ($props?: Record<PropertyKey, any>, $context?: Record<PropertyKey, any>, $slots?: Record<string, ServerSlotRender>) => {
+type ServerComponent = ($props?: Record<PropertyKey, any>, $context?: Record<PropertyKey, any>, $slots?: Record<string, ServerSlotRender>) => Promise<{
   body: string;
   head: string;
-};
+}>;
 //#endregion
-export { $serverAsync as $async, $serverBatch as $batch, $serverBind as $bind, $serverCache as $cache, $serverOnmount as $onmount, $serverPeek as $peek, $serverPending as $pending, $serverRefresh as $refresh, $serverRun as $run, $serverStream as $stream, $serverUnwrap as $unwrap, $serverWatch as $watch, type ServerComponent, type ServerSlotRender, type StreamSource, fromElement, fromServer, fromWebSocket, formatAttributeText as t_attr, buildClasses as t_class, formatServerText as t_fmt, buildStyles as t_style };
+export { $serverAsync as $async, $serverBatch as $batch, $serverBind as $bind, $serverCache as $cache, $serverOnmount as $onmount, $serverPeek as $peek, $serverPending as $pending, $serverRefresh as $refresh, $serverRun as $run, $serverStream as $stream, $serverUnwrap as $unwrap, $serverWatch as $watch, type AsyncOptions, type ServerComponent, type ServerSlotRender, type StreamSource, fromElement, fromServer, fromWebSocket, formatAttributeText as t_attr, runServerAwait as t_await_server, buildClasses as t_class, formatServerText as t_fmt, serverFlush as t_server_flush, buildStyles as t_style };
 //# sourceMappingURL=ssr.d.cts.map

package/dist/ssr.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"ssr.d.cts","names":[],"sources":["../src/render/formatAttributeText.ts","../src/ssr/formatText.ts","../src/ssr/$serverAsync.ts","../src/ssr/$serverBatch.ts","../src/ssr/$serverBind.ts","../src/ssr/$serverCache.ts","../src/ssr/$serverOnmount.ts","../src/ssr/$serverPeek.ts","../src/ssr/$serverPending.ts","../src/ssr/$serverRefresh.ts","../src/ssr/$serverRun.ts","../src/ssr/$serverStream.ts","../src/ssr/$serverUnwrap.ts","../src/ssr/$serverWatch.ts","../src/types/ServerSlotRender.ts","../src/types/ServerComponent.ts"],"mappings":";;;iBAAwB,oBAAoB;;;;;;;;;;iBCepB,iBAAiB;;;;;;;;;iBCTjB,aAAa,GAAG,WAAW,QAAQ,KAAK;;;iBCNxC,aAAa,GAAG,UAAU,IAAI;;;;;;;;;iBCM9B,YACvB,QAAQ,OAAO,mBACf,QAAQ,OAAO,kCACZ;;;iBCToB,aAAa,GAAG,UAAU,IAAI;;;iBCE9B,eAAe,WAAW;;;iBCF1B,YAAY,GAAG,UAAU,IAAI;;;;;;;;iBCK7B,eAAe;;;;;;;;iBCAf,eAAe;;;iBCHf,WAAW,WAAW;;;;;;;;iBCKtB,cAAc,GACrC,SAAS,aAAa,IACtB,WAAW,OAAO,YAClB;EAAa;;;;iBCVU,cAAc,UAAU,OAAO,mBAAmB,QAAQ,IAAI;;;iBCA9D,aAAa,UAAU,OAAO,mBAAmB,QAAQ,IAAI;;;KCAhF,oBACJ,QAAQ,OAAO,mBACf,WAAW,OAAO;;;;;;KCGd,mBACJ,SAAS,OAAO,mBAChB,WAAW,OAAO,mBAClB,SAAS,eAAe;EAClB;EAAc"}
+{"version":3,"file":"ssr.d.cts","names":[],"sources":["../src/render/formatAttributeText.ts","../src/ssr/formatText.ts","../src/ssr/$serverAsync.ts","../src/ssr/$serverBatch.ts","../src/ssr/$serverBind.ts","../src/ssr/$serverCache.ts","../src/ssr/$serverOnmount.ts","../src/ssr/$serverPeek.ts","../src/ssr/$serverPending.ts","../src/ssr/$serverRefresh.ts","../src/ssr/$serverRun.ts","../src/ssr/$serverStream.ts","../src/ssr/$serverUnwrap.ts","../src/ssr/$serverWatch.ts","../src/ssr/runServerAwait.ts","../src/ssr/serverSentinels.ts","../src/types/ServerSlotRender.ts","../src/types/ServerComponent.ts"],"mappings":";;;iBAAwB,oBAAoB;;;;;;;;;;iBCepB,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBC2BjB,aAAa,GAAG,UAAU,QAAQ,IAAI,UAAU,eAAe;;;iBC1C/D,aAAa,GAAG,UAAU,IAAI;;;;;;;;;iBCM9B,YACvB,QAAQ,OAAO,mBACf,QAAQ,OAAO,kCACZ;;;iBCToB,aAAa,GAAG,UAAU,IAAI;;;iBCE9B,eAAe,WAAW;;;iBCF1B,YAAY,GAAG,UAAU,IAAI;;;;;;;;iBCK7B,eAAe;;;;;;;;iBCAf,eAAe;;;iBCHf,WAAW,WAAW;;;;;;;;iBCKtB,cAAc,GACrC,SAAS,aAAa,IACtB,WAAW,OAAO,YAClB;EAAa;;;;iBCVU,cAAc,UAAU,OAAO,mBAAmB,QAAQ,IAAI;;;iBCA9D,aAAa,UAAU,OAAO,mBAAmB,QAAQ,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBCgD7D,eACvB,YACA,qBAAqB;EAAU;EAAc;IAC7C,mBAAmB;EAAU;EAAc;;EACvC;EAAc;IAAiB;EAAU;EAAc;;;;;UC7C3C;EAChB;EACA;;;;;;;;;;;;;;;;iBAiBqB,YAAY,cAAc,QAAQ,cAAc,QAAQ;;;;;;;KCtBzE,oBACJ,QAAQ,OAAO,mBACf,WAAW,OAAO,sBACd;;;;;;;;;;KCEA,mBACJ,SAAS,OAAO,mBAChB,WAAW,OAAO,mBAClB,SAAS,eAAe,sBACpB;EAAU;EAAc"}

package/dist/ssr.d.mts

@@ -1,5 +1,5 @@
 import { t as Cleanup } from "./Cleanup-D0wvGW5d.mjs";
-import { a as buildStyles, i as StreamSource, n as fromServer, r as fromElement, s as buildClasses, t as fromWebSocket } from "./fromWebSocket-B52kN3-W.mjs";
+import { a as StreamSource, c as buildClasses, i as fromElement, n as fromWebSocket, o as buildStyles, r as fromServer, t as AsyncOptions } from "./AsyncOptions-ClS1_ERX.mjs";
 //#region src/render/formatAttributeText.d.ts
 declare function formatAttributeText(value: any): string;
 //#endregion
@@ -15,12 +15,34 @@ declare function formatServerText(value: any): string;
 //#endregion
 //#region src/ssr/$serverAsync.d.ts
 /**
- * Server no-op for the client-side `$async` getter primitive. Server renders
- * are synchronous, so an async value never resolves during SSR — `@await`
+ * Server counterpart of the client-side `$async` getter primitive.
+ *
+ * Without options (the default), this is a no-op stub: server renders are
+ * synchronous, an async value never resolves during SSR, and `@await`
  * boundaries render their `with` branch and never read the getter. The stub
  * exists so server builds importing `$async` don't emit a dangling import.
+ * A read inside a boundary's render pass is still recorded, so the boundary
+ * degrades to the `with` branch + client fetch instead of shipping content
+ * that would suspend on the client.
+ *
+ * With `{ source: "server" }` the getter participates in the server's
+ * collect/render pass (ASYNC.md → "Server rendering"):
+ *
+ * - **Collect pass** — calls the thunk (starting the fetch) and records the
+ *   promise on the enclosing boundary, so sibling reads start in one wave.
+ *   Returns `undefined`; the speculative pass's output is discarded.
+ * - **Render pass** — returns the settled value from the recorded promise at
+ *   the same position in read order, without calling the thunk again. A
+ *   rejection is re-thrown here so `@try`/`@error` handles it like any other
+ *   render error. Running past the recorded reads throws a sentinel that
+ *   degrades the boundary (the render pass no longer matches the collect
+ *   pass, so the shipped HTML can't be trusted).
+ *
+ * Outside any `@await` boundary (including in a `with` branch) a
+ * `source: "server"` read returns `undefined` without fetching — the same
+ * undefined-then-recover contract the client has for un-boundaried reads.
  */
-declare function $serverAsync<T>(_fn: () => Promise<T>): T;
+declare function $serverAsync<T>(fn: () => Promise<T>, options?: AsyncOptions): T;
 //#endregion
 //#region src/ssr/$serverBatch.d.ts
 declare function $serverBatch<T>(fn: () => T): T;
@@ -78,17 +100,94 @@ declare function $serverUnwrap<T extends Record<PropertyKey, any>>(object: T): T
 //#region src/ssr/$serverWatch.d.ts
 declare function $serverWatch<T extends Record<PropertyKey, any>>(object: T): T;
 //#endregion
+//#region src/ssr/runServerAwait.d.ts
+/**
+ * Renders an `@await` boundary on the server (compiled as `t_await_server`).
+ *
+ * The generated code calls this for every `@await`, passing the boundary's
+ * site id, a closure that renders the content branch, and one that renders
+ * the `with` branch. It always returns a `{ body, head }` pair to append:
+ *
+ * - **Inside a boundary's render pass** — this boundary was already started
+ *   during the collect pass; its body/head is the finished HTML (awaited if
+ *   still in flight). A missing entry means the render pass doesn't match
+ *   the collect pass, which degrades the enclosing boundary.
+ * - **Inside a collect pass or a component flush** — start the full
+ *   lifecycle (collect, settle, render) without blocking the enclosing
+ *   render, and return a sentinel comment as the body. Sibling reads and
+ *   nested boundaries keep rendering, so every fetch in the pass starts in
+ *   one wave. The sentinel is substituted later: by the enclosing boundary's
+ *   render pass (which re-invokes this helper and awaits the finished HTML),
+ *   or by the component flush (which replaces top-level sentinels directly).
+ *
+ * The lifecycle: render content once to start the `source: "server"` fetches
+ * (discarding the output), wait for them with a per-getter timeout, then
+ * render again with the settled values. The second pass ships wrapped in
+ * hydration markers plus a `<!--t-await:...-->` comment carrying the values
+ * for the client's `$async` hydration path. Any instability — timeout, a
+ * render pass that reads a different set of getters, a client-fetch read —
+ * degrades to the `with` branch + client fetch, exactly the pre-`source`
+ * behavior.
+ *
+ * @param id The boundary's site id (unique per `@await` in the component)
+ * @param renderContent Renders the content branch (may read `$async` getters)
+ * @param renderWith Renders the `with` branch, or null for empty
+ */
+declare function runServerAwait(id: string, renderContent: () => Promise<{
+  body: string;
+  head: string;
+}>, renderWith: (() => Promise<{
+  body: string;
+  head: string;
+}>) | null): {
+  body: string;
+  head: string;
+} | Promise<{
+  body: string;
+  head: string;
+}>;
+//#endregion
+//#region src/ssr/serverSentinels.d.ts
+/** The body/head pair that server components and boundaries render into. */
+interface ServerHtml {
+  body: string;
+  head: string;
+}
+/**
+ * Renders a component's (or a degraded boundary's `with` branch's) markup
+ * with a fresh flush root as the enclosing await state, then substitutes any
+ * boundary sentinels with their final HTML.
+ *
+ * Boundaries created during the render stash their lifecycle promise under a
+ * sentinel comment and return the sentinel immediately, so the render itself
+ * never blocks on a fetch — every `source: "server"` read in the render
+ * starts in the same wave. Substitution awaits the stashed promises at the
+ * end, which is the only point an async component render actually waits.
+ *
+ * On the client this has no counterpart: `render` here is the compiled
+ * component body closure that the generated component function returns.
+ */
+declare function serverFlush(render: () => Promise<ServerHtml>): Promise<ServerHtml>;
+//#endregion
 //#region src/types/ServerSlotRender.d.ts
-type ServerSlotRender = ($slot?: Record<PropertyKey, any>, $context?: Record<PropertyKey, any>) => string;
+/**
+ * Renders a slot fill to HTML. Async so the fill can contain an `@await`
+ * boundary with a `source: "server"` getter (ASYNC.md → "Server rendering").
+ */
+type ServerSlotRender = ($slot?: Record<PropertyKey, any>, $context?: Record<PropertyKey, any>) => Promise<string>;
 //#endregion
 //#region src/types/ServerComponent.d.ts
 /**
- * A component that generates HTML
+ * A component that generates HTML. Server components are async so that a
+ * `source: "server"` `@await` boundary can fetch during the render (see
+ * ASYNC.md → "Server rendering"); call sites await the result, which also
+ * accepts the plain object a component without boundaries effectively
+ * resolves to.
  */
-type ServerComponent = ($props?: Record<PropertyKey, any>, $context?: Record<PropertyKey, any>, $slots?: Record<string, ServerSlotRender>) => {
+type ServerComponent = ($props?: Record<PropertyKey, any>, $context?: Record<PropertyKey, any>, $slots?: Record<string, ServerSlotRender>) => Promise<{
   body: string;
   head: string;
-};
+}>;
 //#endregion
-export { $serverAsync as $async, $serverBatch as $batch, $serverBind as $bind, $serverCache as $cache, $serverOnmount as $onmount, $serverPeek as $peek, $serverPending as $pending, $serverRefresh as $refresh, $serverRun as $run, $serverStream as $stream, $serverUnwrap as $unwrap, $serverWatch as $watch, type ServerComponent, type ServerSlotRender, type StreamSource, fromElement, fromServer, fromWebSocket, formatAttributeText as t_attr, buildClasses as t_class, formatServerText as t_fmt, buildStyles as t_style };
+export { $serverAsync as $async, $serverBatch as $batch, $serverBind as $bind, $serverCache as $cache, $serverOnmount as $onmount, $serverPeek as $peek, $serverPending as $pending, $serverRefresh as $refresh, $serverRun as $run, $serverStream as $stream, $serverUnwrap as $unwrap, $serverWatch as $watch, type AsyncOptions, type ServerComponent, type ServerSlotRender, type StreamSource, fromElement, fromServer, fromWebSocket, formatAttributeText as t_attr, runServerAwait as t_await_server, buildClasses as t_class, formatServerText as t_fmt, serverFlush as t_server_flush, buildStyles as t_style };
 //# sourceMappingURL=ssr.d.mts.map

package/dist/ssr.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"ssr.d.mts","names":[],"sources":["../src/render/formatAttributeText.ts","../src/ssr/formatText.ts","../src/ssr/$serverAsync.ts","../src/ssr/$serverBatch.ts","../src/ssr/$serverBind.ts","../src/ssr/$serverCache.ts","../src/ssr/$serverOnmount.ts","../src/ssr/$serverPeek.ts","../src/ssr/$serverPending.ts","../src/ssr/$serverRefresh.ts","../src/ssr/$serverRun.ts","../src/ssr/$serverStream.ts","../src/ssr/$serverUnwrap.ts","../src/ssr/$serverWatch.ts","../src/types/ServerSlotRender.ts","../src/types/ServerComponent.ts"],"mappings":";;;iBAAwB,oBAAoB;;;;;;;;;;iBCepB,iBAAiB;;;;;;;;;iBCTjB,aAAa,GAAG,WAAW,QAAQ,KAAK;;;iBCNxC,aAAa,GAAG,UAAU,IAAI;;;;;;;;;iBCM9B,YACvB,QAAQ,OAAO,mBACf,QAAQ,OAAO,kCACZ;;;iBCToB,aAAa,GAAG,UAAU,IAAI;;;iBCE9B,eAAe,WAAW;;;iBCF1B,YAAY,GAAG,UAAU,IAAI;;;;;;;;iBCK7B,eAAe;;;;;;;;iBCAf,eAAe;;;iBCHf,WAAW,WAAW;;;;;;;;iBCKtB,cAAc,GACrC,SAAS,aAAa,IACtB,WAAW,OAAO,YAClB;EAAa;;;;iBCVU,cAAc,UAAU,OAAO,mBAAmB,QAAQ,IAAI;;;iBCA9D,aAAa,UAAU,OAAO,mBAAmB,QAAQ,IAAI;;;KCAhF,oBACJ,QAAQ,OAAO,mBACf,WAAW,OAAO;;;;;;KCGd,mBACJ,SAAS,OAAO,mBAChB,WAAW,OAAO,mBAClB,SAAS,eAAe;EAClB;EAAc"}
+{"version":3,"file":"ssr.d.mts","names":[],"sources":["../src/render/formatAttributeText.ts","../src/ssr/formatText.ts","../src/ssr/$serverAsync.ts","../src/ssr/$serverBatch.ts","../src/ssr/$serverBind.ts","../src/ssr/$serverCache.ts","../src/ssr/$serverOnmount.ts","../src/ssr/$serverPeek.ts","../src/ssr/$serverPending.ts","../src/ssr/$serverRefresh.ts","../src/ssr/$serverRun.ts","../src/ssr/$serverStream.ts","../src/ssr/$serverUnwrap.ts","../src/ssr/$serverWatch.ts","../src/ssr/runServerAwait.ts","../src/ssr/serverSentinels.ts","../src/types/ServerSlotRender.ts","../src/types/ServerComponent.ts"],"mappings":";;;iBAAwB,oBAAoB;;;;;;;;;;iBCepB,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBC2BjB,aAAa,GAAG,UAAU,QAAQ,IAAI,UAAU,eAAe;;;iBC1C/D,aAAa,GAAG,UAAU,IAAI;;;;;;;;;iBCM9B,YACvB,QAAQ,OAAO,mBACf,QAAQ,OAAO,kCACZ;;;iBCToB,aAAa,GAAG,UAAU,IAAI;;;iBCE9B,eAAe,WAAW;;;iBCF1B,YAAY,GAAG,UAAU,IAAI;;;;;;;;iBCK7B,eAAe;;;;;;;;iBCAf,eAAe;;;iBCHf,WAAW,WAAW;;;;;;;;iBCKtB,cAAc,GACrC,SAAS,aAAa,IACtB,WAAW,OAAO,YAClB;EAAa;;;;iBCVU,cAAc,UAAU,OAAO,mBAAmB,QAAQ,IAAI;;;iBCA9D,aAAa,UAAU,OAAO,mBAAmB,QAAQ,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBCgD7D,eACvB,YACA,qBAAqB;EAAU;EAAc;IAC7C,mBAAmB;EAAU;EAAc;;EACvC;EAAc;IAAiB;EAAU;EAAc;;;;;UC7C3C;EAChB;EACA;;;;;;;;;;;;;;;;iBAiBqB,YAAY,cAAc,QAAQ,cAAc,QAAQ;;;;;;;KCtBzE,oBACJ,QAAQ,OAAO,mBACf,WAAW,OAAO,sBACd;;;;;;;;;;KCEA,mBACJ,SAAS,OAAO,mBAChB,WAAW,OAAO,mBAClB,SAAS,eAAe,sBACpB;EAAU;EAAc"}