@kasperrt/smolter 0.3.4 → 0.4.0

package/.generated/preact/client.tsx

@@ -11,6 +11,7 @@ import { connectNavigation } from "../core/navigation.ts";
 import { retainRoute } from "../core/presentation.ts";
 import { hydrate, render } from "preact";
 import { flushSync } from "preact/compat";
+import { readHydration } from "./deferred-hydration.ts";
 import { attachRootData } from "./root-data.ts";
 import type { AppRoute, Hydration, RootModule } from "./route-types.ts";
 import { prepareRoutes, RouterApplication } from "./router.tsx";
@@ -46,25 +47,10 @@ export async function mountApplication(
 
   routes = prepareRoutes(routes);
   const element = document.getElementById("smolter-data");
-  const hydration: Hydration | undefined = element?.textContent
-    ? JSON.parse(element.textContent, (_key, value) => {
-        if (
-          !value ||
-          typeof value !== "object" ||
-          !("__smolterRejected" in value)
-        )
-          return value;
-
-        const error = Object.assign(
-          new Error(value.__smolterRejected.message),
-          value.__smolterRejected,
-        );
-        const rejected = Promise.reject(error);
-        void rejected.catch(() => {});
-
-        return rejected;
-      })
+  const initial = element?.textContent
+    ? readHydration(element.textContent)
     : undefined;
+  const hydration: Hydration | undefined = initial?.hydration;
 
   if (hydration?.snapshot.error)
     hydration.snapshot.error = Object.assign(
@@ -79,6 +65,11 @@ export async function mountApplication(
       : location.href,
     ...(hydration && { hydrationData: hydration.snapshot }),
   });
+  const dispose = router.dispose;
+  router.dispose = () => {
+    initial?.dispose();
+    dispose();
+  };
   watchDeployment(router, deployment);
   if (hash) connectHashHistory(router);
 
@@ -96,7 +87,21 @@ export async function mountApplication(
   };
 
   if (hydration) {
-    hydrate(<RouterApplication {...props} document />, document);
+    // Explicitly unmanaged head nodes must not participate in positional hydration.
+    const preserved = Array.from(
+      document.querySelectorAll(
+        "head > [data-smolter-preserve], body > [data-smolter-stream]",
+      ),
+      (node) => ({ node, next: node.nextSibling, parent: node.parentNode! }),
+    );
+    for (const { node } of preserved) node.remove();
+
+    await Promise.resolve()
+      .then(() => hydrate(<RouterApplication {...props} document />, document))
+      .finally(() => {
+        for (const { node, next, parent } of preserved.reverse())
+          parent.insertBefore(node, next?.parentNode === parent ? next : null);
+      });
 
     return router;
   }

package/.generated/preact/deferred-hydration.ts

@@ -0,0 +1,87 @@
+type Settlement = [number, unknown, string | null];
+
+interface PendingValue {
+  promise: Promise<unknown>;
+  resolve: (value: unknown) => void;
+  reject: (reason: Error) => void;
+}
+
+declare global {
+  interface Window {
+    __smolterDeferred?: Settlement[];
+  }
+}
+
+/** Restore promise identity before hydrating Suspense boundaries. */
+export function readHydration(json: string) {
+  const pending = new Map<number, PendingValue>();
+  const queue = (window.__smolterDeferred ??= []);
+
+  function revive(_key: string, value: unknown): unknown {
+    if (!value || typeof value !== "object") return value;
+    if ("__smolterUndefined" in value) return undefined;
+
+    if (
+      "__smolterPending" in value &&
+      typeof value.__smolterPending === "number"
+    ) {
+      const id = value.__smolterPending;
+      const existing = pending.get(id);
+      if (existing) return existing.promise;
+
+      let resolve!: PendingValue["resolve"];
+      let reject!: PendingValue["reject"];
+      const promise = new Promise((accept, fail) => {
+        resolve = accept;
+        reject = fail;
+      });
+      void promise.catch(() => {});
+      pending.set(id, { promise, resolve, reject });
+
+      return promise;
+    }
+
+    if ("__smolterRejected" in value) {
+      const failure = value.__smolterRejected as { message: string };
+      const rejected = Promise.reject(
+        Object.assign(new Error(failure.message), failure),
+      );
+      void rejected.catch(() => {});
+
+      return rejected;
+    }
+
+    return value;
+  }
+
+  const hydration = JSON.parse(json, revive);
+  const dispose = () => {
+    window.removeEventListener("DOMContentLoaded", dispose);
+    for (const target of pending.values())
+      target.reject(new Error("Hydration stream closed"));
+    pending.clear();
+    queue.push = () => 0;
+  };
+  const receive = (packet: Settlement) => {
+    const [id, value, error] = packet;
+    if (id === -1) return dispose();
+
+    const target = pending.get(id);
+    if (!target) return;
+
+    if (error !== null) target.reject(new Error(error));
+    if (error === null)
+      target.resolve(JSON.parse(JSON.stringify(value), revive));
+  };
+  const buffered = queue.splice(0);
+  queue.push = (...packets) => {
+    packets.forEach(receive);
+    return 0;
+  };
+
+  window.addEventListener("DOMContentLoaded", dispose, { once: true });
+  buffered.forEach(receive);
+  if (document.readyState !== "loading") dispose();
+
+  return { hydration, dispose };
+}

package/.generated/preact/document.tsx

@@ -72,10 +72,12 @@ export interface ScriptProps {
 }
 
 export function Scripts({ nonce }: ScriptProps): import("preact").JSX.Element {
-  const { root, rootError, router, entry, streaming } = useApplication();
+  const { root, rootError, router, entry, streaming, initialData } =
+    useApplication();
   // The bootstrap payload describes this document's initial SSR snapshot.
   // Navigation and revalidation update the router, not the hydration script.
   const [json] = useState(() => {
+    if (initialData !== undefined) return initialData;
     if (streaming) return "";
 
     const current = router.getSnapshot();
@@ -105,7 +107,14 @@ export function Scripts({ nonce }: ScriptProps): import("preact").JSX.Element {
         {...(nonce && { nonce })}
         dangerouslySetInnerHTML={{ __html: json }}
       />
-      {entry && <script type="module" src={entry} {...(nonce && { nonce })} />}
+      {entry && (
+        <script
+          type="module"
+          async={initialData !== undefined}
+          src={entry}
+          {...(nonce && { nonce })}
+        />
+      )}
     </Fragment>
   );
 }

package/.generated/preact/root-context.ts

@@ -8,6 +8,7 @@ export interface ApplicationContext {
   root: unknown;
   rootError?: boolean;
   streaming?: boolean;
+  initialData?: string;
   rootModule?: RootModule;
   hydration?: Hydration;
   entry?: string;

package/.generated/server/application.tsx

@@ -10,11 +10,14 @@ import type { AppRoute, RootModule } from "../preact/route-types.ts";
 import { prepareRoutes, RouterApplication } from "../preact/router.tsx";
 import { loadRouter } from "./index.ts";
 import { renderToReadableStream } from "preact-render-to-string/stream";
+import { deferredHydration } from "./deferred-hydration.ts";
 import { privateResponse } from "./private-response.ts";
+import { progressiveDocument } from "./progressive-document.ts";
 import { resolveHydration, streamDocument } from "./stream-document.ts";
 
 export interface RenderApplicationOptions {
   nonce?: string;
+  earlyHydration?: boolean;
 }
 
 export async function renderApplication(
@@ -120,6 +123,21 @@ export async function renderApplication(
   }
 
   const snapshot = router.getSnapshot();
+  const hydrationData = {
+    root,
+    snapshot: {
+      ...snapshot,
+      error: snapshot.error && {
+        ...snapshot.error,
+        name: snapshot.error.name,
+        message: snapshot.error.message,
+      },
+    },
+    ...(rootError && { rootError: true }),
+  };
+  const deferred = options.earlyHydration
+    ? deferredHydration(hydrationData, options.nonce)
+    : undefined;
   const stream = renderToReadableStream(
     <RouterApplication
       router={router}
@@ -129,22 +147,11 @@ export async function renderApplication(
       entry={entry}
       rootError={Boolean(rootError)}
       streaming
+      initialData={deferred?.initial}
       document
     />,
     options,
   );
-  const hydration = resolveHydration({
-    root,
-    snapshot: {
-      ...snapshot,
-      error: snapshot.error && {
-        ...snapshot.error,
-        name: snapshot.error.name,
-        message: snapshot.error.message,
-      },
-    },
-    ...(rootError && { rootError: true }),
-  });
   // The renderer reports the same rejection through its stream reader.
   void stream.allReady.catch(() => {});
   const headers = new Headers(actionResponse?.headers);
@@ -154,12 +161,17 @@ export async function renderApplication(
   headers.set("Cache-Control", "no-store");
 
   return new Response(
-    streamDocument(stream, {
-      hydration,
-      signal: request.signal,
-      nonce: options.nonce,
-      dispose: () => router.dispose(),
-    }),
+    deferred
+      ? progressiveDocument(stream, deferred.stream, {
+          signal: request.signal,
+          dispose: () => router.dispose(),
+        })
+      : streamDocument(stream, {
+          hydration: resolveHydration(hydrationData),
+          signal: request.signal,
+          nonce: options.nonce,
+          dispose: () => router.dispose(),
+        }),
     {
       status: snapshot.error
         ? Number("status" in snapshot.error ? snapshot.error.status : 500)

package/.generated/server/assets.ts

@@ -3,6 +3,7 @@ import { matchRoutes } from "../core/index.ts";
 export interface RouteAssets {
   path: string;
   files: string[];
+  styles?: string[];
 }
 
 export function routePreloads(
@@ -13,7 +14,14 @@ export function routePreloads(
   const match = matchRoutes(routes, pathname);
   const route = match?.route as RouteAssets | undefined;
 
-  return (route?.files ?? [])
-    .map((file) => `<${base.replace(/\/$/, "")}/${file}>; rel=modulepreload`)
-    .join(", ");
+  const prefix = base.replace(/\/$/, "");
+
+  return [
+    ...(route?.styles ?? []).map(
+      (file) => `<${prefix}/${file}>; rel=preload; as=style; crossorigin`,
+    ),
+    ...(route?.files ?? []).map(
+      (file) => `<${prefix}/${file}>; rel=modulepreload`,
+    ),
+  ].join(", ");
 }

package/.generated/server/deferred-hydration.ts

@@ -0,0 +1,89 @@
+import { serializeData } from "../core/serialize.ts";
+
+/** Encode deferred values without delaying the initial document snapshot. */
+export function deferredHydration(value: unknown, nonce?: string) {
+  const promises = new Map<Promise<unknown>, number>();
+  let pending = 0;
+  let closed = false;
+  let controller!: ReadableStreamDefaultController<Uint8Array>;
+  const encoder = new TextEncoder();
+  const attribute = nonce
+    ? ` nonce="${nonce.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("<", "&lt;")}"`
+    : "";
+  const stream = new ReadableStream<Uint8Array>({
+    start(value) {
+      controller = value;
+    },
+    cancel() {
+      closed = true;
+    },
+  });
+
+  function encode(value: unknown): unknown {
+    if (value instanceof Promise) {
+      const existing = promises.get(value);
+      if (existing !== undefined) return { __smolterPending: existing };
+
+      const id = promises.size;
+      promises.set(value, id);
+      pending++;
+      void value
+        .then((result) => settle(id, encode(result)))
+        .catch((error: unknown) =>
+          settle(
+            id,
+            null,
+            error instanceof Error ? error.message : String(error),
+          ),
+        );
+
+      return { __smolterPending: id };
+    }
+
+    if (Array.isArray(value)) return value.map(encode);
+
+    if (
+      value &&
+      typeof value === "object" &&
+      Object.getPrototypeOf(value) === Object.prototype
+    )
+      return Object.fromEntries(
+        Object.entries(value).map(([key, field]) => [key, encode(field)]),
+      );
+
+    return value;
+  }
+
+  function settle(id: number, value: unknown, error?: string) {
+    if (closed) return;
+
+    const packet = serializeData([
+      id,
+      value === undefined ? { __smolterUndefined: true } : value,
+      error,
+    ]);
+    controller.enqueue(
+      encoder.encode(
+        `<script${attribute}>(window.__smolterDeferred??=[]).push(${packet});document.currentScript.remove()</script>`,
+      ),
+    );
+    pending--;
+    if (!pending) {
+      closed = true;
+      controller.enqueue(
+        encoder.encode(
+          `<script${attribute}>(window.__smolterDeferred??=[]).push([-1,null,null]);document.currentScript.remove()</script>`,
+        ),
+      );
+      controller.close();
+    }
+  }
+
+  const initial = serializeData(encode(value));
+  if (!pending) {
+    closed = true;
+    controller.close();
+  }
+
+  return { initial, stream };
+}

package/.generated/server/progressive-document.ts

@@ -0,0 +1,102 @@
+interface ProgressiveDocumentOptions {
+  signal: AbortSignal;
+  dispose: () => void;
+}
+
+/** Interleave deferred settlements with complete HTML chunks, respecting backpressure. */
+export function progressiveDocument(
+  source: ReadableStream<Uint8Array>,
+  settlements: ReadableStream<Uint8Array>,
+  options: ProgressiveDocumentOptions,
+): ReadableStream<Uint8Array> {
+  const html = source.getReader();
+  const data = settlements.getReader();
+  const encoder = new TextEncoder();
+  const decoder = new TextDecoder();
+  let stopped = false;
+  let cancelled = false;
+  let first = true;
+  let suffix = "";
+  const readHTML = () =>
+    html.read().then(
+      (result) => ({ ...result, html: true }),
+      (error: unknown) => ({ error }),
+    );
+  const readData = () =>
+    data.read().then(
+      (result) => ({ ...result, html: false }),
+      (error: unknown) => ({ error }),
+    );
+  let nextHTML: ReturnType<typeof readHTML> | undefined;
+  let nextData: ReturnType<typeof readData> | undefined;
+
+  const stop = () => {
+    if (stopped) return;
+
+    stopped = true;
+    options.signal.removeEventListener("abort", stop);
+    options.dispose();
+    void html.cancel().catch(() => {});
+    void data.cancel().catch(() => {});
+  };
+  options.signal.addEventListener("abort", stop, { once: true });
+  if (options.signal.aborted) stop();
+
+  return new ReadableStream({
+    async pull(controller) {
+      const work = async () => {
+        if (first && !stopped) nextHTML = readHTML();
+
+        while (!stopped && (nextHTML || nextData)) {
+          const reads = [nextHTML, nextData].filter(
+            (value) => value !== undefined,
+          );
+          const result = await Promise.race(reads);
+          if (stopped) break;
+          if ("error" in result) return Promise.reject(result.error);
+
+          if (result.html) nextHTML = result.done ? undefined : readHTML();
+          if (!result.html) nextData = result.done ? undefined : readData();
+          if (first) nextData = readData();
+          if (result.done) {
+            first = false;
+            continue;
+          }
+
+          if (!result.html) {
+            controller.enqueue(result.value);
+            return;
+          }
+
+          let chunk = decoder.decode(result.value, { stream: true });
+          if (chunk === "<div hidden>")
+            chunk = "<div hidden data-smolter-stream>";
+          if (first && !/^<!doctype/i.test(chunk))
+            chunk = `<!doctype html>${chunk}`;
+          first = false;
+          const closing = chunk.lastIndexOf("</body>");
+          if (closing !== -1) {
+            suffix = chunk.slice(closing);
+            chunk = chunk.slice(0, closing);
+          }
+          controller.enqueue(encoder.encode(chunk));
+          return;
+        }
+
+        if (cancelled) return;
+        if (!stopped) controller.enqueue(encoder.encode(suffix));
+        stop();
+        controller.close();
+      };
+
+      await work().catch((error: unknown) => {
+        stop();
+        controller.error(error);
+      });
+    },
+    cancel() {
+      cancelled = true;
+      stop();
+    },
+  });
+}

package/.generated/vite/application/lazy-files.ts

@@ -3,6 +3,10 @@ import { resolve } from "node:path";
 import { flatRoutes } from "../../files/index.ts";
 import { type Plugin, transformWithOxc } from "vite";
 
+interface ChunkMetadata {
+  importedCss?: Set<string>;
+}
+
 // Reuse Smolter's file discovery and server-export stripping. Only the browser
 // route manifest changes: matched routes load before their data is committed.
 export function lazyFiles(
@@ -31,21 +35,27 @@ export function lazyFiles(
         if (!path) continue;
 
         const files = new Set<string>();
+        const styles = new Set<string>();
 
         function visit(file: string) {
           if (files.has(file)) return;
 
-          files.add(file);
-
           const dependency = bundle[file];
 
           if (dependency?.type !== "chunk") return;
 
+          files.add(file);
+
+          const metadata = dependency.viteMetadata as ChunkMetadata | undefined;
+          for (const stylesheet of metadata?.importedCss ?? []) {
+            if (bundle[stylesheet]?.type === "asset") styles.add(stylesheet);
+          }
+
           for (const imported of dependency.imports) visit(imported);
         }
 
         visit(chunk.fileName);
-        routes.push({ path, files: [...files] });
+        routes.push({ path, files: [...files], styles: [...styles] });
       }
 
       const paths = [...modules.values()];

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.4.0
+
+- Add opt-in `earlyHydration: true` to Preact `renderApplication`: hydrate the shell before optional nested loader promises settle, using Preact Suspense and independently streamed values/errors. Default hydration timing is unchanged.
+- Preserve shared promise identity, nonce-aware script serialization and the renderer's streaming container. Reject unfinished values when the document stream ends or the router is disposed; cancel server readers on disconnect.
+- Add production regressions for interaction and input retention during a 1,500 ms delay, independent deferred boundaries, rejection, one-time mutation, navigation before settlement, injected head nodes and CSP nonces. These are fixture results, not Vibes performance or device sign-off.
+- Include matched-route CSS in generated asset manifests and stylesheet preload hints using Vite’s anonymous CORS mode. Verify cross-origin preload reuse in Chromium. Keep transitive JavaScript dependencies discoverable and optional dynamic imports lazy. Preload hints do not apply styles or imply a measured latency improvement.
+- Update SSR and loading documentation, including removal of stale claims that the Express adapter buffers responses.
+
+## 0.3.5
+
+- Preserve explicitly unmanaged head elements marked data-smolter-preserve during Preact document hydration, without matching them to application-owned nodes.
+- Test injected script/meta preservation, one-time script execution, styling and subsequent navigation.
+- Add interaction-before/after-deferred-completion assertions and document that streaming does not provide progressive hydration.
+- Fix route asset manifests incorrectly including external module specifiers as preload file URLs; retain transitive emitted chunks and leave optional dynamic imports lazy. No general request-count or latency improvement is claimed.
+
 ## 0.3.4
 
 - Cancel stale deployment checks when newer Back/Forward operations return to the current route, including hash changes.

package/README.md

@@ -1,8 +1,8 @@
 # smolter _
 
 <!-- bundlejs:start -->
-[![react gzip size](https://deno.bundlejs.com/?q=%40kasperrt%2Fsmolter%400.3.4%2Freact&treeshake=%5B*%5D&config=%7B%22compression%22%3A%22gzip%22%2C%22esbuild%22%3A%7B%22external%22%3A%5B%22react%22%2C%22react%2F*%22%5D%7D%7D&badge)](https://bundlejs.com/?q=%40kasperrt%2Fsmolter%400.3.4%2Freact&treeshake=%5B*%5D&config=%7B%22compression%22%3A%22gzip%22%2C%22esbuild%22%3A%7B%22external%22%3A%5B%22react%22%2C%22react%2F*%22%5D%7D%7D&bundle)
-[![preact gzip size](https://deno.bundlejs.com/?q=%40kasperrt%2Fsmolter%400.3.4%2Fpreact&treeshake=%5B*%5D&config=%7B%22compression%22%3A%22gzip%22%2C%22esbuild%22%3A%7B%22external%22%3A%5B%22preact%22%2C%22preact%2F*%22%5D%7D%7D&badge)](https://bundlejs.com/?q=%40kasperrt%2Fsmolter%400.3.4%2Fpreact&treeshake=%5B*%5D&config=%7B%22compression%22%3A%22gzip%22%2C%22esbuild%22%3A%7B%22external%22%3A%5B%22preact%22%2C%22preact%2F*%22%5D%7D%7D&bundle)
+[![react gzip size](https://deno.bundlejs.com/?q=%40kasperrt%2Fsmolter%400.4.0%2Freact&treeshake=%5B*%5D&config=%7B%22compression%22%3A%22gzip%22%2C%22esbuild%22%3A%7B%22external%22%3A%5B%22react%22%2C%22react%2F*%22%5D%7D%7D&badge)](https://bundlejs.com/?q=%40kasperrt%2Fsmolter%400.4.0%2Freact&treeshake=%5B*%5D&config=%7B%22compression%22%3A%22gzip%22%2C%22esbuild%22%3A%7B%22external%22%3A%5B%22react%22%2C%22react%2F*%22%5D%7D%7D&bundle)
+[![preact gzip size](https://deno.bundlejs.com/?q=%40kasperrt%2Fsmolter%400.4.0%2Fpreact&treeshake=%5B*%5D&config=%7B%22compression%22%3A%22gzip%22%2C%22esbuild%22%3A%7B%22external%22%3A%5B%22preact%22%2C%22preact%2F*%22%5D%7D%7D&badge)](https://bundlejs.com/?q=%40kasperrt%2Fsmolter%400.4.0%2Fpreact&treeshake=%5B*%5D&config=%7B%22compression%22%3A%22gzip%22%2C%22esbuild%22%3A%7B%22external%22%3A%5B%22preact%22%2C%22preact%2F*%22%5D%7D%7D&bundle)
 <!-- bundlejs:end -->
 
 A typed data router for React and Preact. **Zero runtime dependencies.**
@@ -607,8 +607,8 @@ a claim of identical features.
 | `@kasperrt/smolter/preact` | 4842 |
 | `@kasperrt/smolter/react + @kasperrt/smolter/react/client` | 4104 |
 | `@kasperrt/smolter/preact + server transport` | 5950 |
-| `@kasperrt/smolter/preact + client + document (application without lazy routes)` | 8478 |
-| `@kasperrt/smolter/preact + client + document + lazy-route (file-routed application)` | 8761 |
+| `@kasperrt/smolter/preact + client + document (application without lazy routes)` | 8949 |
+| `@kasperrt/smolter/preact + client + document + lazy-route (file-routed application)` | 9227 |
 | `@kasperrt/smolter/react/data (optional resource API)` | 2962 |
 | `React: common routing/data exports` | 2761 |
 | `Preact: common routing/data exports` | 3046 |
@@ -748,6 +748,33 @@ import { mountApplication } from "@kasperrt/smolter/preact/client";
 await mountApplication(routes, root, { deployment });
 ```
 
-Preact SSR starts root and route loaders concurrently. Return nested promises and render them with `Await` inside `Suspense` to stream a shell before optional data resolves. The Node/Express adapter streams the response; hydration starts after the document stream finishes. Root-loader failures render the root error boundary. Vite development HTML transformation still buffers the document.
+Preact SSR starts root and route loaders concurrently. Return nested promises and render them with `Await` inside `Suspense` to stream a shell before optional data resolves. The Node/Express adapter streams the response; hydration starts after the document stream finishes by default. Pass `{ earlyHydration: true }` to `renderApplication` to hydrate the shell while optional promises stream independently. Root-loader failures render the root error boundary. Vite development HTML transformation still buffers the document.
 
 Successful action redirects refresh registered root data without replaying the mutation. Loader arguments expose `reason` to distinguish initial loads, navigation, revalidation and fetcher reads without comparing browser URLs.
+
+
+### Document hydration and injected tags
+
+Preact hydrates after document completion by default. For an interactive shell while optional data is pending:
+
+```ts
+return renderApplication(request, routes, root, entry, {
+  earlyHydration: true,
+  nonce,
+});
+```
+
+Keep optional nested promises inside `Suspense` and `Await`. The browser entry runs asynchronously; each deferred result settles without rerunning the initial loader. Required top-level loader data still blocks the shell. Use production streaming hosting; Vite development HTML transformation buffers. Measure a successful interaction rather than treating TTFB or DOMContentLoaded as hydration completion.
+
+Infrastructure that injects direct children of `<head>` can mark those external nodes with `data-smolter-preserve`. Smolter excludes them from positional hydration and restores the same nodes afterward. Do not also render them in the application layout. Unmarked HTML rewriting, body injection and changes to the hydration payload are not supported.
+
+```html
+<script data-smolter-preserve src="/infrastructure-instrumentation.js"></script>
+```
+
+The generated route asset manifest follows static imports for each route and leaves optional dynamic imports lazy. Serve the matched route's preload hints with the correct asset base; do not preload every route to reduce a waterfall. Chunk counts and total emitted bytes alone do not establish initial-load latency.
+
+
+### Matched-route asset hints
+
+The file-router build emits `.vite/route-assets.json` with each route's static JavaScript dependency closure and its CSS in `styles`. `routePreloads` from `@kasperrt/smolter/utils/assets` produces modulepreload hints for JavaScript and `preload; as=style; crossorigin` hints for CSS (matching Vite’s anonymous CORS mode), respecting your CDN/base URL. Set these hints on the document response or send Early Hints from your host. Stylesheet preloads fetch files; they do not apply styles. Keep the application stylesheet links and Vite's CSS handling in place. Optional dynamic imports are excluded, and unrelated routes stay lazy.

package/dist/preact/client.js

@@ -8,6 +8,7 @@ import { RouterApplication, prepareRoutes } from "./router.js";
 import { deserialize } from "../client/deserialize.js";
 import { recoverDeployment, watchDeployment } from "../client/deployment.js";
 import { serverRoute } from "../client/index.js";
+import { readHydration } from "./deferred-hydration.js";
 import { flushSync } from "preact/compat";
 import { jsx } from "preact/jsx-runtime";
 import { hydrate, render } from "preact";
@@ -23,19 +24,19 @@ async function mountApplication(routes, rootModule, options = false) {
 	});
 	routes = prepareRoutes(routes);
 	const element = document.getElementById("smolter-data");
-	const hydration = element?.textContent ? JSON.parse(element.textContent, (_key, value) => {
-		if (!value || typeof value !== "object" || !("__smolterRejected" in value)) return value;
-		const error = Object.assign(new Error(value.__smolterRejected.message), value.__smolterRejected);
-		const rejected = Promise.reject(error);
-		rejected.catch(() => {});
-		return rejected;
-	}) : void 0;
+	const initial = element?.textContent ? readHydration(element.textContent) : void 0;
+	const hydration = initial?.hydration;
 	if (hydration?.snapshot.error) hydration.snapshot.error = Object.assign(new Error(hydration.snapshot.error.message), hydration.snapshot.error);
 	const router = createDataRouter(routes, {
 		browser: !hash,
 		url: hash ? new URL(location.hash.slice(1) || "/", location.origin).href : location.href,
 		...hydration && { hydrationData: hydration.snapshot }
 	});
+	const dispose = router.dispose;
+	router.dispose = () => {
+		initial?.dispose();
+		dispose();
+	};
 	watchDeployment(router, deployment);
 	if (hash) connectHashHistory(router);
 	retainRoute(router, flushSync);
@@ -50,10 +51,18 @@ async function mountApplication(routes, rootModule, options = false) {
 		rootError: hydration?.rootError
 	};
 	if (hydration) {
-		hydrate(/* @__PURE__ */ jsx(RouterApplication, {
+		const preserved = Array.from(document.querySelectorAll("head > [data-smolter-preserve], body > [data-smolter-stream]"), (node) => ({
+			node,
+			next: node.nextSibling,
+			parent: node.parentNode
+		}));
+		for (const { node } of preserved) node.remove();
+		await Promise.resolve().then(() => hydrate(/* @__PURE__ */ jsx(RouterApplication, {
 			...props,
 			document: true
-		}), document);
+		}), document)).finally(() => {
+			for (const { node, next, parent } of preserved.reverse()) parent.insertBefore(node, next?.parentNode === parent ? next : null);
+		});
 		return router;
 	}
 	const target = document.getElementById("root");

package/dist/preact/deferred-hydration.d.ts

@@ -0,0 +1,12 @@
+type Settlement = [number, unknown, string | null];
+declare global {
+    interface Window {
+        __smolterDeferred?: Settlement[];
+    }
+}
+/** Restore promise identity before hydrating Suspense boundaries. */
+export declare function readHydration(json: string): {
+    hydration: any;
+    dispose: () => void;
+};
+export {};

package/dist/preact/deferred-hydration.js

@@ -0,0 +1,64 @@
+//#region .generated/preact/deferred-hydration.ts
+/** Restore promise identity before hydrating Suspense boundaries. */
+function readHydration(json) {
+	const pending = /* @__PURE__ */ new Map();
+	const queue = window.__smolterDeferred ??= [];
+	function revive(_key, value) {
+		if (!value || typeof value !== "object") return value;
+		if ("__smolterUndefined" in value) return void 0;
+		if ("__smolterPending" in value && typeof value.__smolterPending === "number") {
+			const id = value.__smolterPending;
+			const existing = pending.get(id);
+			if (existing) return existing.promise;
+			let resolve;
+			let reject;
+			const promise = new Promise((accept, fail) => {
+				resolve = accept;
+				reject = fail;
+			});
+			promise.catch(() => {});
+			pending.set(id, {
+				promise,
+				resolve,
+				reject
+			});
+			return promise;
+		}
+		if ("__smolterRejected" in value) {
+			const failure = value.__smolterRejected;
+			const rejected = Promise.reject(Object.assign(new Error(failure.message), failure));
+			rejected.catch(() => {});
+			return rejected;
+		}
+		return value;
+	}
+	const hydration = JSON.parse(json, revive);
+	const dispose = () => {
+		window.removeEventListener("DOMContentLoaded", dispose);
+		for (const target of pending.values()) target.reject(/* @__PURE__ */ new Error("Hydration stream closed"));
+		pending.clear();
+		queue.push = () => 0;
+	};
+	const receive = (packet) => {
+		const [id, value, error] = packet;
+		if (id === -1) return dispose();
+		const target = pending.get(id);
+		if (!target) return;
+		if (error !== null) target.reject(new Error(error));
+		if (error === null) target.resolve(JSON.parse(JSON.stringify(value), revive));
+	};
+	const buffered = queue.splice(0);
+	queue.push = (...packets) => {
+		packets.forEach(receive);
+		return 0;
+	};
+	window.addEventListener("DOMContentLoaded", dispose, { once: true });
+	buffered.forEach(receive);
+	if (document.readyState !== "loading") dispose();
+	return {
+		hydration,
+		dispose
+	};
+}
+//#endregion
+export { readHydration };

package/dist/preact/document.js

@@ -44,8 +44,9 @@ function Links() {
 	return /* @__PURE__ */ jsx(Fragment$1, { children: rootModule?.links?.().map((props, index) => /* @__PURE__ */ jsx("link", { ...props }, index)) });
 }
 function Scripts({ nonce }) {
-	const { root, rootError, router, entry, streaming } = useApplication();
+	const { root, rootError, router, entry, streaming, initialData } = useApplication();
 	const [json] = useState(() => {
+		if (initialData !== void 0) return initialData;
 		if (streaming) return "";
 		const current = router.getSnapshot();
 		const snapshot = {
@@ -75,6 +76,7 @@ function Scripts({ nonce }) {
 		}),
 		entry && /* @__PURE__ */ jsx("script", {
 			type: "module",
+			async: initialData !== void 0,
 			src: entry,
 			...nonce && { nonce }
 		})

package/dist/preact/root-context.d.ts

@@ -6,6 +6,7 @@ export interface ApplicationContext {
     root: unknown;
     rootError?: boolean;
     streaming?: boolean;
+    initialData?: string;
     rootModule?: RootModule;
     hydration?: Hydration;
     entry?: string;

package/dist/server/application.d.ts

@@ -2,6 +2,7 @@
 import type { AppRoute, RootModule } from "../preact/route-types.ts";
 export interface RenderApplicationOptions {
     nonce?: string;
+    earlyHydration?: boolean;
 }
 export declare function renderApplication(request: Request, routes: AppRoute[], rootModule: RootModule, entry: string, options?: RenderApplicationOptions): Promise<Response>;
 export declare function dispatchRoute(request: Request, routes: AppRoute[], document?: boolean): Promise<Response>;

package/dist/server/application.js

@@ -5,6 +5,8 @@ import { normalizeResult, resolveData } from "../core/responses.js";
 import { RouterApplication, prepareRoutes } from "../preact/router.js";
 import { privateResponse } from "./private-response.js";
 import { loadRouter } from "./index.js";
+import { deferredHydration } from "./deferred-hydration.js";
+import { progressiveDocument } from "./progressive-document.js";
 import { resolveHydration, streamDocument } from "./stream-document.js";
 import { jsx } from "preact/jsx-runtime";
 import { renderToReadableStream } from "preact-render-to-string/stream";
@@ -68,17 +70,7 @@ async function renderApplication(request, routes, rootModule, entry, options = {
 		router = createDataRouter(router.routes, { hydrationData });
 	}
 	const snapshot = router.getSnapshot();
-	const stream = renderToReadableStream(/* @__PURE__ */ jsx(RouterApplication, {
-		router,
-		routes,
-		root,
-		rootModule,
-		entry,
-		rootError: Boolean(rootError),
-		streaming: true,
-		document: true
-	}), options);
-	const hydration = resolveHydration({
+	const hydrationData = {
 		root,
 		snapshot: {
 			...snapshot,
@@ -89,15 +81,30 @@ async function renderApplication(request, routes, rootModule, entry, options = {
 			}
 		},
 		...rootError && { rootError: true }
-	});
+	};
+	const deferred = options.earlyHydration ? deferredHydration(hydrationData, options.nonce) : void 0;
+	const stream = renderToReadableStream(/* @__PURE__ */ jsx(RouterApplication, {
+		router,
+		routes,
+		root,
+		rootModule,
+		entry,
+		rootError: Boolean(rootError),
+		streaming: true,
+		initialData: deferred?.initial,
+		document: true
+	}), options);
 	stream.allReady.catch(() => {});
 	const headers = new Headers(actionResponse?.headers);
 	headers.delete("Content-Length");
 	headers.delete("Content-Encoding");
 	headers.set("Content-Type", "text/html; charset=utf-8");
 	headers.set("Cache-Control", "no-store");
-	return new Response(streamDocument(stream, {
-		hydration,
+	return new Response(deferred ? progressiveDocument(stream, deferred.stream, {
+		signal: request.signal,
+		dispose: () => router.dispose()
+	}) : streamDocument(stream, {
+		hydration: resolveHydration(hydrationData),
 		signal: request.signal,
 		nonce: options.nonce,
 		dispose: () => router.dispose()

package/dist/server/assets.d.ts

@@ -1,5 +1,6 @@
 export interface RouteAssets {
     path: string;
     files: string[];
+    styles?: string[];
 }
 export declare function routePreloads(routes: RouteAssets[], pathname: string, base: string): string;

package/dist/server/assets.js

@@ -1,7 +1,9 @@
 import { matchRoutes } from "../core/match.js";
 //#region .generated/server/assets.ts
 function routePreloads(routes, pathname, base) {
-	return ((matchRoutes(routes, pathname)?.route)?.files ?? []).map((file) => `<${base.replace(/\/$/, "")}/${file}>; rel=modulepreload`).join(", ");
+	const route = matchRoutes(routes, pathname)?.route;
+	const prefix = base.replace(/\/$/, "");
+	return [...(route?.styles ?? []).map((file) => `<${prefix}/${file}>; rel=preload; as=style; crossorigin`), ...(route?.files ?? []).map((file) => `<${prefix}/${file}>; rel=modulepreload`)].join(", ");
 }
 //#endregion
 export { routePreloads };

package/dist/server/deferred-hydration.d.ts

@@ -0,0 +1,5 @@
+/** Encode deferred values without delaying the initial document snapshot. */
+export declare function deferredHydration(value: unknown, nonce?: string): {
+    initial: string;
+    stream: ReadableStream<Uint8Array<ArrayBufferLike>>;
+};

package/dist/server/deferred-hydration.js

@@ -0,0 +1,59 @@
+import { serializeData } from "../core/serialize.js";
+//#region .generated/server/deferred-hydration.ts
+/** Encode deferred values without delaying the initial document snapshot. */
+function deferredHydration(value, nonce) {
+	const promises = /* @__PURE__ */ new Map();
+	let pending = 0;
+	let closed = false;
+	let controller;
+	const encoder = new TextEncoder();
+	const attribute = nonce ? ` nonce="${nonce.replaceAll("&", "&amp;").replaceAll("\"", "&quot;").replaceAll("<", "&lt;")}"` : "";
+	const stream = new ReadableStream({
+		start(value) {
+			controller = value;
+		},
+		cancel() {
+			closed = true;
+		}
+	});
+	function encode(value) {
+		if (value instanceof Promise) {
+			const existing = promises.get(value);
+			if (existing !== void 0) return { __smolterPending: existing };
+			const id = promises.size;
+			promises.set(value, id);
+			pending++;
+			value.then((result) => settle(id, encode(result))).catch((error) => settle(id, null, error instanceof Error ? error.message : String(error)));
+			return { __smolterPending: id };
+		}
+		if (Array.isArray(value)) return value.map(encode);
+		if (value && typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype) return Object.fromEntries(Object.entries(value).map(([key, field]) => [key, encode(field)]));
+		return value;
+	}
+	function settle(id, value, error) {
+		if (closed) return;
+		const packet = serializeData([
+			id,
+			value === void 0 ? { __smolterUndefined: true } : value,
+			error
+		]);
+		controller.enqueue(encoder.encode(`<script${attribute}>(window.__smolterDeferred??=[]).push(${packet});document.currentScript.remove()<\/script>`));
+		pending--;
+		if (!pending) {
+			closed = true;
+			controller.enqueue(encoder.encode(`<script${attribute}>(window.__smolterDeferred??=[]).push([-1,null,null]);document.currentScript.remove()<\/script>`));
+			controller.close();
+		}
+	}
+	const initial = serializeData(encode(value));
+	if (!pending) {
+		closed = true;
+		controller.close();
+	}
+	return {
+		initial,
+		stream
+	};
+}
+//#endregion
+export { deferredHydration };

package/dist/server/progressive-document.d.ts

@@ -0,0 +1,7 @@
+interface ProgressiveDocumentOptions {
+    signal: AbortSignal;
+    dispose: () => void;
+}
+/** Interleave deferred settlements with complete HTML chunks, respecting backpressure. */
+export declare function progressiveDocument(source: ReadableStream<Uint8Array>, settlements: ReadableStream<Uint8Array>, options: ProgressiveDocumentOptions): ReadableStream<Uint8Array>;
+export {};

package/dist/server/progressive-document.js

@@ -0,0 +1,81 @@
+//#region .generated/server/progressive-document.ts
+/** Interleave deferred settlements with complete HTML chunks, respecting backpressure. */
+function progressiveDocument(source, settlements, options) {
+	const html = source.getReader();
+	const data = settlements.getReader();
+	const encoder = new TextEncoder();
+	const decoder = new TextDecoder();
+	let stopped = false;
+	let cancelled = false;
+	let first = true;
+	let suffix = "";
+	const readHTML = () => html.read().then((result) => ({
+		...result,
+		html: true
+	}), (error) => ({ error }));
+	const readData = () => data.read().then((result) => ({
+		...result,
+		html: false
+	}), (error) => ({ error }));
+	let nextHTML;
+	let nextData;
+	const stop = () => {
+		if (stopped) return;
+		stopped = true;
+		options.signal.removeEventListener("abort", stop);
+		options.dispose();
+		html.cancel().catch(() => {});
+		data.cancel().catch(() => {});
+	};
+	options.signal.addEventListener("abort", stop, { once: true });
+	if (options.signal.aborted) stop();
+	return new ReadableStream({
+		async pull(controller) {
+			const work = async () => {
+				if (first && !stopped) nextHTML = readHTML();
+				while (!stopped && (nextHTML || nextData)) {
+					const reads = [nextHTML, nextData].filter((value) => value !== void 0);
+					const result = await Promise.race(reads);
+					if (stopped) break;
+					if ("error" in result) return Promise.reject(result.error);
+					if (result.html) nextHTML = result.done ? void 0 : readHTML();
+					if (!result.html) nextData = result.done ? void 0 : readData();
+					if (first) nextData = readData();
+					if (result.done) {
+						first = false;
+						continue;
+					}
+					if (!result.html) {
+						controller.enqueue(result.value);
+						return;
+					}
+					let chunk = decoder.decode(result.value, { stream: true });
+					if (chunk === "<div hidden>") chunk = "<div hidden data-smolter-stream>";
+					if (first && !/^<!doctype/i.test(chunk)) chunk = `<!doctype html>${chunk}`;
+					first = false;
+					const closing = chunk.lastIndexOf("</body>");
+					if (closing !== -1) {
+						suffix = chunk.slice(closing);
+						chunk = chunk.slice(0, closing);
+					}
+					controller.enqueue(encoder.encode(chunk));
+					return;
+				}
+				if (cancelled) return;
+				if (!stopped) controller.enqueue(encoder.encode(suffix));
+				stop();
+				controller.close();
+			};
+			await work().catch((error) => {
+				stop();
+				controller.error(error);
+			});
+		},
+		cancel() {
+			cancelled = true;
+			stop();
+		}
+	});
+}
+//#endregion
+export { progressiveDocument };

package/dist/vite/application/lazy-files.js

@@ -20,17 +20,21 @@ function lazyFiles(directory, dataEndpoint = "/_smolter") {
 				const path = modules.get(chunk.facadeModuleId);
 				if (!path) continue;
 				const files = /* @__PURE__ */ new Set();
+				const styles = /* @__PURE__ */ new Set();
 				function visit(file) {
 					if (files.has(file)) return;
-					files.add(file);
 					const dependency = bundle[file];
 					if (dependency?.type !== "chunk") return;
+					files.add(file);
+					const metadata = dependency.viteMetadata;
+					for (const stylesheet of metadata?.importedCss ?? []) if (bundle[stylesheet]?.type === "asset") styles.add(stylesheet);
 					for (const imported of dependency.imports) visit(imported);
 				}
 				visit(chunk.fileName);
 				routes.push({
 					path,
-					files: [...files]
+					files: [...files],
+					styles: [...styles]
 				});
 			}
 			const paths = [...modules.values()];

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@kasperrt/smolter",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "exports": {
     "./react": "./.generated/react/index.ts",
     "./preact": "./.generated/preact/index.ts",

package/package.json

@@ -56,7 +56,7 @@
     "wouter": "3.13.0",
     "wouter-preact": "3.13.0"
   },
-  "version": "0.3.4",
+  "version": "0.4.0",
   "description": "A tiny typed data router for React and Preact.",
   "sideEffects": false,
   "license": "MIT",