@kasperrt/smolter 0.4.0 → 0.4.2

package/.generated/client/deployment.ts

@@ -1,6 +1,14 @@
-import type { NavigationRouter } from "../core/index.ts";
+import type { NavigationRouter, Router } from "../core/index.ts";
 import { deploymentCheck } from "./deployment-check.ts";
 
+interface WatcherState {
+  sequence: number;
+  mutations: number;
+  cleanup?: () => void;
+}
+
+const watchers = new WeakMap<NavigationRouter, WatcherState>();
+
 /** Build identity and the fresh, non-cacheable manifest URL emitted by deploymentPlugin. */
 export interface DeploymentOptions {
   version: string;
@@ -11,30 +19,57 @@ export interface DeploymentOptions {
   reload?: (destination: URL) => void;
 }
 
-/** Check for deployment changes before navigation. Returns a cleanup function. */
+/** Check for deployment changes before navigation. Install before creating fetchers. Returns a cleanup function. */
 export function watchDeployment(
   router: NavigationRouter,
   options: DeploymentOptions | null,
 ): () => void {
   if (!options || typeof window === "undefined") return () => {};
 
+  const state = watchers.get(router) ?? { sequence: 0, mutations: 0 };
+  state.cleanup?.();
+  watchers.set(router, state);
   const check = deploymentCheck(options);
   const { changed, reload } = check;
   const read = router.getSnapshot;
   const navigate = router.navigate;
   const dispose = router.dispose;
-  let sequence = 0;
   let stopped = false;
   let replay = false;
-  const valid = (current: number) => current === sequence && !stopped;
-  const unsubscribe = router.subscribe(() => {
-    if (read().state === "submitting") sequence++;
-  });
+  const dataRouter = router as NavigationRouter &
+    Partial<Pick<Router, "createFetcher" | "submit">>;
+  const createFetcher = dataRouter.createFetcher;
+  const submit = dataRouter.submit;
+  const trackSubmission =
+    (submit: Router["submit"]): Router["submit"] =>
+    (...args) => {
+      state.sequence++;
+      state.mutations++;
+
+      return submit(...args).finally(() => {
+        state.mutations--;
+      });
+    };
+  const guardedSubmit = submit && trackSubmission(submit);
+  const guardedFetcher =
+    createFetcher &&
+    (() => {
+      const fetcher = createFetcher();
+      fetcher.submit = trackSubmission(fetcher.submit);
+
+      return fetcher;
+    });
+
+  if (guardedSubmit) dataRouter.submit = guardedSubmit;
+  if (guardedFetcher) dataRouter.createFetcher = guardedFetcher;
+  const valid = (current: number) => current === state.sequence && !stopped;
+  const canReload = (current: number) =>
+    valid(current) && state.mutations === 0;
 
   const guarded: NavigationRouter["navigate"] = async (href, operation) => {
     const target = new URL(href, router.getSnapshot().url);
     const currentURL = new URL(router.getSnapshot().url);
-    const current = ++sequence;
+    const current = ++state.sequence;
 
     if (
       target.origin === location.origin &&
@@ -42,11 +77,11 @@ export function watchDeployment(
         target.search !== currentURL.search) &&
       (await changed())
     ) {
-      if (!valid(current) || (await reload(target, () => valid(current))))
+      if (!valid(current) || (await reload(target, () => canReload(current))))
         return;
     }
 
-    if (current === sequence && !stopped) await navigate(href, operation);
+    if (current === state.sequence && !stopped) await navigate(href, operation);
   };
 
   const pop = (event: PopStateEvent) => {
@@ -54,7 +89,7 @@ export function watchDeployment(
 
     const target = new URL(location.href);
     const previous = new URL(read().url);
-    const current = ++sequence;
+    const current = ++state.sequence;
 
     if (
       target.pathname === previous.pathname &&
@@ -65,7 +100,7 @@ export function watchDeployment(
     event.stopImmediatePropagation();
     void changed().then(async (updated) => {
       if (!valid(current)) return;
-      if (updated && (await reload(target, () => valid(current)))) return;
+      if (updated && (await reload(target, () => canReload(current)))) return;
       if (!valid(current)) return;
 
       replay = true;
@@ -81,14 +116,14 @@ export function watchDeployment(
     // consume the recovery marker before a click records its destination.
     if (read().state !== "loading") return;
 
-    const current = sequence;
+    const current = state.sequence;
     const target = new URL(read().url);
     void changed().then((updated) => {
       if (updated)
         return reload(
           target,
           () =>
-            valid(current) &&
+            canReload(current) &&
             read().state !== "submitting" &&
             read().url === target.href,
         );
@@ -96,13 +131,18 @@ export function watchDeployment(
   };
 
   function cleanup() {
+    if (stopped) return;
+    if (state.cleanup === cleanup) state.cleanup = undefined;
     stopped = true;
-    sequence++;
+    state.sequence++;
     check.dispose();
-    unsubscribe();
     window.removeEventListener("popstate", pop, true);
     window.removeEventListener("vite:preloadError", preloadError);
 
+    if (guardedSubmit && dataRouter.submit === guardedSubmit)
+      dataRouter.submit = submit;
+    if (guardedFetcher && dataRouter.createFetcher === guardedFetcher)
+      dataRouter.createFetcher = createFetcher;
     if (router.navigate === guarded) router.navigate = navigate;
     if (router.dispose === guardedDispose) router.dispose = dispose;
   }
@@ -112,6 +152,7 @@ export function watchDeployment(
     dispose();
   }
 
+  state.cleanup = cleanup;
   router.navigate = guarded;
   router.dispose = guardedDispose;
   window.addEventListener("popstate", pop, true);

package/.generated/files/index.ts

@@ -47,10 +47,12 @@ export async function flatRoutes(
         name = name.replace(flatFile, "");
       }
 
-      if (/[()[\]:*?]/.test(name))
+      const escaped = name.replaceAll("[.]", "\0");
+
+      if (/[()[\]:*?]/.test(escaped))
         return new Error(`Unsupported flat route name: ${name}`);
 
-      const segments = name.split(".");
+      const segments = escaped.split(".");
       const parts: string[] = [];
 
       for (const [index, segment] of segments.entries()) {
@@ -64,7 +66,7 @@ export async function flatRoutes(
 
         if (segment.startsWith("_")) continue;
 
-        const part = segment.replace(/_$/, "");
+        const part = segment.replace(/_$/, "").replaceAll("\0", ".");
         parts.push(part === "$" ? "*" : part.replace(/^\$/, ":"));
       }
 

package/.generated/preact/await-fallback.tsx

@@ -0,0 +1,33 @@
+/** @jsxImportSource preact */
+import { useEffect, useState } from "preact/hooks";
+
+import type { AwaitProps } from "./await.tsx";
+
+type Result<T> = { source: Promise<T> } & ({ value: T } | { error: unknown });
+
+export function AwaitFallback<T>({
+  resolve,
+  fallback,
+  errorElement,
+  children,
+}: AwaitProps<T> & { resolve: Promise<T> }) {
+  const [result, setResult] = useState<Result<T>>();
+  useEffect(() => {
+    let current = true;
+    void resolve.then(
+      (value) => {
+        if (current) setResult({ source: resolve, value });
+      },
+      (error: unknown) => {
+        if (current) setResult({ source: resolve, error });
+      },
+    );
+    return () => {
+      current = false;
+    };
+  }, [resolve]);
+  if (!result || result.source !== resolve) return fallback;
+  if ("value" in result) return children(result.value as Awaited<T>);
+  if (errorElement !== undefined) return errorElement;
+  throw result.error;
+}

package/.generated/preact/await.tsx

@@ -1,10 +1,15 @@
+/** @jsxImportSource preact */
 import type { ComponentChildren } from "preact";
-import { use } from "preact/compat";
+import { use, useContext } from "preact/compat";
+import { AwaitFallback } from "./await-fallback.tsx";
+import { Application } from "./root-context.ts";
 
 export interface AwaitProps<T> {
   resolve: T | Promise<T>;
   children: (value: Awaited<T>) => ComponentChildren;
   errorElement?: ComponentChildren;
+  /** Component-owned pending content, safe during early hydration. Pass null to render nothing. */
+  fallback?: ComponentChildren;
 }
 
 type Resolution = { value: unknown } | { error: unknown };
@@ -12,13 +17,25 @@ type Resolution = { value: unknown } | { error: unknown };
 // Cache only the error-as-data adapter. Preact owns pending and resolved state.
 const resolutions = new WeakMap<Promise<unknown>, Promise<Resolution>>();
 
-export function Await<T>({
+export function Await<T>(props: AwaitProps<T>): ComponentChildren {
+  const app = useContext(Application);
+  if (!(props.resolve instanceof Promise))
+    return props.children(props.resolve as Awaited<T>);
+  if (!("fallback" in props))
+    return <SuspendedAwait {...props} resolve={props.resolve} />;
+  if (app?.deferredBoundary)
+    return app.deferredBoundary(
+      <SuspendedAwait {...props} resolve={props.resolve} />,
+      props.fallback,
+    );
+  return <AwaitFallback {...props} resolve={props.resolve} />;
+}
+
+function SuspendedAwait<T>({
   resolve,
   children,
   errorElement,
-}: AwaitProps<T>): ComponentChildren {
-  if (!(resolve instanceof Promise)) return children(resolve as Awaited<T>);
-
+}: AwaitProps<T> & { resolve: Promise<T> }): ComponentChildren {
   let pending = resolutions.get(resolve);
 
   if (!pending) {

package/.generated/preact/client.tsx

@@ -22,6 +22,8 @@ export { configureApplication } from "../core/environment.ts";
 export interface MountApplicationOptions {
   hash?: boolean;
   deployment?: DeploymentOptions | null;
+  /** Total initial deferred-data budget in integer milliseconds; not an inactivity timeout. Defaults to 30,000. */
+  deferredTimeout?: number;
 }
 
 export async function mountApplication(
@@ -29,8 +31,11 @@ export async function mountApplication(
   rootModule?: RootModule,
   options: boolean | MountApplicationOptions = false,
 ): Promise<Router> {
-  const { hash = false, deployment = null } =
-    typeof options === "boolean" ? { hash: options } : options;
+  const {
+    hash = false,
+    deployment = null,
+    deferredTimeout,
+  } = typeof options === "boolean" ? { hash: options } : options;
   const initialURL = new URL(
     hash ? location.hash.slice(1) || "/" : location.href,
     location.origin,
@@ -48,7 +53,7 @@ export async function mountApplication(
   routes = prepareRoutes(routes);
   const element = document.getElementById("smolter-data");
   const initial = element?.textContent
-    ? readHydration(element.textContent)
+    ? readHydration(element.textContent, deferredTimeout)
     : undefined;
   const hydration: Hydration | undefined = initial?.hydration;
 

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

@@ -6,16 +6,19 @@ interface PendingValue {
   reject: (reason: Error) => void;
 }
 
-declare global {
-  interface Window {
-    __smolterDeferred?: Settlement[];
-  }
+export interface DeferredWindow extends Window {
+  __smolterDeferred?: Settlement[];
 }
 
 /** Restore promise identity before hydrating Suspense boundaries. */
-export function readHydration(json: string) {
+export function readHydration(json: string, timeout = 30_000) {
+  if (!Number.isInteger(timeout) || timeout < 1 || timeout > 2_147_483_647)
+    throw new RangeError(
+      "deferredTimeout must be an integer between 1 and 2147483647 ms",
+    );
+
   const pending = new Map<number, PendingValue>();
-  const queue = (window.__smolterDeferred ??= []);
+  const queue = ((window as DeferredWindow).__smolterDeferred ??= []);
 
   function revive(_key: string, value: unknown): unknown {
     if (!value || typeof value !== "object") return value;
@@ -56,12 +59,20 @@ export function readHydration(json: string) {
 
   const hydration = JSON.parse(json, revive);
   const dispose = () => {
+    clearTimeout(deadline);
     window.removeEventListener("DOMContentLoaded", dispose);
     for (const target of pending.values())
       target.reject(new Error("Hydration stream closed"));
     pending.clear();
     queue.push = () => 0;
   };
+  const deadline = pending.size
+    ? setTimeout(() => {
+        for (const target of pending.values())
+          target.reject(new Error("Hydration stream timed out"));
+        dispose();
+      }, timeout)
+    : undefined;
   const receive = (packet: Settlement) => {
     const [id, value, error] = packet;
     if (id === -1) return dispose();

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

@@ -8,6 +8,10 @@ export interface ApplicationContext {
   root: unknown;
   rootError?: boolean;
   streaming?: boolean;
+  deferredBoundary?: (
+    children: import("preact").ComponentChildren,
+    fallback: import("preact").ComponentChildren,
+  ) => import("preact").ComponentChildren;
   initialData?: string;
   rootModule?: RootModule;
   hydration?: Hydration;

package/.generated/server/application.tsx

@@ -9,6 +9,8 @@ import {
 import type { AppRoute, RootModule } from "../preact/route-types.ts";
 import { prepareRoutes, RouterApplication } from "../preact/router.tsx";
 import { loadRouter } from "./index.ts";
+import type { ComponentChildren } from "preact";
+import { Suspense } from "preact/compat";
 import { renderToReadableStream } from "preact-render-to-string/stream";
 import { deferredHydration } from "./deferred-hydration.ts";
 import { privateResponse } from "./private-response.ts";
@@ -147,6 +149,7 @@ export async function renderApplication(
       entry={entry}
       rootError={Boolean(rootError)}
       streaming
+      deferredBoundary={options.earlyHydration ? undefined : deferredBoundary}
       initialData={deferred?.initial}
       document
     />,
@@ -181,6 +184,13 @@ export async function renderApplication(
   );
 }
 
+function deferredBoundary(
+  children: ComponentChildren,
+  fallback: ComponentChildren,
+) {
+  return <Suspense fallback={fallback}>{children}</Suspense>;
+}
+
 async function dispatch(
   request: Request,
   routes: AppRoute[],

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

@@ -87,10 +87,7 @@ export function lazyFiles(
         const source = await readFile(route.file, "utf8");
         const transformed = await transformWithOxc(source, route.file);
         const ast = this.parse(transformed.code);
-        const fields: Record<string, string | boolean> = {
-          path: route.path,
-          dataEndpoint,
-        };
+        const fields: Record<string, string | boolean> = {};
 
         for (const statement of ast.body) {
           if (statement.type === "ExportDefaultDeclaration") {
@@ -120,22 +117,18 @@ export function lazyFiles(
           for (const declaration of statement.declaration.declarations) {
             if (declaration.id.type === "Identifier")
               fields[declaration.id.name] = true;
-
-            if (
-              declaration.id.type !== "Identifier" ||
-              declaration.init?.type !== "Literal" ||
-              typeof declaration.init.value !== "string"
-            )
-              continue;
-
-            const name = declaration.id.name;
-
-            if (name === "id") fields.id = declaration.init.value;
-
-            if (name === "routePath") fields.path = declaration.init.value;
           }
         }
 
+        if (fields.id || fields.routePath)
+          return this.error(
+            `File routes derive identity and paths from filenames: remove id/routePath exports from ${route.file}. Use [.] for a literal dot.`,
+          );
+
+        // Export discovery records capabilities, never routing configuration.
+        fields.path = route.path;
+        fields.dataEndpoint = dataEndpoint;
+
         const file = `${route.file.replaceAll("\\", "/")}?smolter-client`;
 
         if (fields.default) modules.set(file, String(fields.path));

package/.generated/vite/index.ts

@@ -152,6 +152,20 @@ export function routerPlugin({
         for (const statement of ast.body) {
           if (statement.type !== "ExportNamedDeclaration") continue;
 
+          const declared = statement.declaration;
+          const names = statement.specifiers.map((specifier) =>
+            specifier.exported.type === "Identifier"
+              ? specifier.exported.name
+              : specifier.exported.value,
+          );
+          if (declared?.type === "VariableDeclaration")
+            for (const item of declared.declarations)
+              if (item.id.type === "Identifier") names.push(item.id.name);
+          if (names.some((name) => name === "id" || name === "routePath"))
+            return this.error(
+              `File routes derive identity and paths from filenames: remove id/routePath exports from ${file}. Use [.] for a literal dot.`,
+            );
+
           for (const specifier of statement.specifiers) {
             const name =
               specifier.exported.type === "Identifier"

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.4.2
+
+- Add integrated `Await fallback` for early hydration: pending and resolved content belongs to the mounted component, so navigation, root revalidation and late settlement cannot leave abandoned content behind. Migrate early-hydrated deferred sections from outer Preact `Suspense` to this prop, including root sections. Native Preact streamed Suspense remains unsupported for this ownership contract; it is not patched. Ordinary non-early SSR still streams resolved HTML.
+- Preserve deployment recovery ownership across overlapping page/fetcher submissions and watcher replacement, including old cleanup calls. Mutations are not replayed and pending submissions continue to prevent recovery reloads.
+- Bound initial deferred-data hydration with one total deadline (30 seconds by default); validate integer millisecond budgets, reject outstanding promises on expiry and clear lifecycle state on disposal. This is not an inactivity timer or an immediate network-disconnect detector.
+- Support literal dots in flat route filenames and folders: `robots[.]txt` maps to `/robots.txt`. Generated file routes reject `id` and `routePath` overrides; derive identity from their filename and use their path for targeted revalidation. Manually defined route arrays retain explicit identities.
+- Keep the thirteen-case ownership matrix, streaming/CSP/head-preservation checks, scoped transports, deployment recovery and route HMR as production regression gates. Preserve the native Preact diagnostic separately; passing Smolter tests do not claim native Preact or Vibes/device parity.
+
+## 0.4.1
+
+- Invalidate pending deployment recovery when an independent fetcher submits. Prevent recovery reloads while any tracked fetcher submission is pending, without blocking ordinary client navigation. Install the watcher before creating fetchers; mountApplication already does this.
+- Add regressions for two fetcher mutations completing before an older manifest check, overlapping pending submissions, unused recovery markers, later recovery, and watcher cleanup. These deterministic tests do not establish the complete streaming/offline browser matrix.
+- Clarify that root stylesheet URL imports rely on rendered stylesheet links and are outside route CSS discovery. Empty route styles arrays are expected in that setup; explicit host preload hints should be justified by measurements.
+
 ## 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.

package/README.md

@@ -1,8 +1,8 @@
 # smolter _
 
 <!-- bundlejs:start -->
-[![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)
+[![react gzip size](https://deno.bundlejs.com/?q=%40kasperrt%2Fsmolter%400.4.2%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.2%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.2%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.2%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.**
@@ -123,7 +123,11 @@ route folders are ignored. `.ts`, `.tsx`, `.js`, and `.jsx` are supported.
 **Only flat matching:** there are no nested outlets, inherited loaders, or layout
 chains. A pathless group module itself is not rendered or executed. Group names
 do not provide authentication. Static paths are ordered before parameters, then
-splats. Conflicting patterns and unsupported optional/escaped syntax are rejected.
+splats. Escape a literal dot with `[.]`: `robots[.]txt.ts` and
+`robots[.]txt/route.ts` both map to `/robots.txt`. File routes derive their
+identity and URL from their filename; do not export `id` or `routePath`.
+Target revalidation with the generated path (or `root` for root data).
+Conflicting patterns and unsupported optional/bracket syntax are rejected.
 
 For the virtual module, add this declaration to your app:
 
@@ -604,11 +608,11 @@ a claim of identical features.
 | `React: routing-only named exports` | 1245 |
 | `Preact: routing-only named exports` | 1405 |
 | `@kasperrt/smolter/react` | 2948 |
-| `@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)` | 8949 |
-| `@kasperrt/smolter/preact + client + document + lazy-route (file-routed application)` | 9227 |
+| `@kasperrt/smolter/preact` | 5024 |
+| `@kasperrt/smolter/react + @kasperrt/smolter/react/client` | 4281 |
+| `@kasperrt/smolter/preact + server transport` | 6300 |
+| `@kasperrt/smolter/preact + client + document (application without lazy routes)` | 9405 |
+| `@kasperrt/smolter/preact + client + document + lazy-route (file-routed application)` | 9692 |
 | `@kasperrt/smolter/react/data (optional resource API)` | 2962 |
 | `React: common routing/data exports` | 2761 |
 | `Preact: common routing/data exports` | 3046 |
@@ -748,7 +752,7 @@ 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 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.
+Preact SSR starts root and route loaders concurrently. Return nested promises and use `Await` with an explicit `fallback` for component-owned pending content during early hydration. 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. Initial deferred values share a total 30-second budget after their payload is read, not an inactivity timeout or reliable disconnect detector. Settlements do not extend it; configure `mountApplication` with `{ deferredTimeout: 60_000 }` for intentionally slower data (integer milliseconds from 1 through 2147483647; invalid values throw RangeError). A broken document can emit no completion event, so this deadline rejects unfinished values without retrying requests. 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.
 
@@ -778,3 +782,21 @@ The generated route asset manifest follows static imports for each route and lea
 ### 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.
+
+Root stylesheet URL imports such as `import stylesUrl from "./index.css?url"` are not route CSS imports. Keep rendering `<link rel="stylesheet" href={stylesUrl}>` in the root document; an empty route `styles` array is expected when all CSS is loaded this way. Smolter does not infer stylesheet use from arbitrary asset URLs. If measurements show late root CSS discovery, your host can send an explicit preload or Early Hint for that same resolved URL, with the same CORS mode as the stylesheet link. Preloading does not replace the stylesheet link. Do not reorganize CSS merely to populate the route manifest.
+
+
+### Component-owned deferred loading
+
+For early Preact hydration, pass pending content directly to the built-in `Await`:
+
+```tsx
+import { Await } from "@kasperrt/smolter/preact";
+
+<Await resolve={data.stats} fallback={<p>Loading statistics…</p>}
+  errorElement={<p>Statistics unavailable.</p>}>
+  {(stats) => <Stats value={stats} />}
+</Await>
+```
+
+Replace the surrounding native `Suspense` for each deferred section, including root sections. This uses ordinary component-owned fallback HTML and the existing deferred data stream, avoiding Preact 11.0.1's abandoned streamed-boundary problem. No separate entrypoint, dependency patch, DOM cleanup, extra request or polling is needed. Late results cannot update an unmounted owner. Early-mode resolved content requires JavaScript; ordinary SSR without early hydration still streams resolved HTML. Existing `Await` without `fallback` keeps its Suspense semantics and its known early-hydration limitation. This does not repair arbitrary native Suspense/lazy boundaries.

package/dist/client/deployment.d.ts

@@ -8,7 +8,7 @@ export interface DeploymentOptions {
     /** Override document navigation, for example to ask about unsaved changes. */
     reload?: (destination: URL) => void;
 }
-/** Check for deployment changes before navigation. Returns a cleanup function. */
+/** Check for deployment changes before navigation. Install before creating fetchers. Returns a cleanup function. */
 export declare function watchDeployment(router: NavigationRouter, options: DeploymentOptions | null): () => void;
 /** Recover an initial lazy-import failure before a router has mounted. Returns whether a reload was requested. */
 export declare function recoverDeployment(options: DeploymentOptions | null, destination?: URL): Promise<boolean>;

package/dist/client/deployment.js

@@ -1,39 +1,61 @@
 import { deploymentCheck } from "./deployment-check.js";
 //#region .generated/client/deployment.ts
-/** Check for deployment changes before navigation. Returns a cleanup function. */
+var watchers = /* @__PURE__ */ new WeakMap();
+/** Check for deployment changes before navigation. Install before creating fetchers. Returns a cleanup function. */
 function watchDeployment(router, options) {
 	if (!options || typeof window === "undefined") return () => {};
+	const state = watchers.get(router) ?? {
+		sequence: 0,
+		mutations: 0
+	};
+	state.cleanup?.();
+	watchers.set(router, state);
 	const check = deploymentCheck(options);
 	const { changed, reload } = check;
 	const read = router.getSnapshot;
 	const navigate = router.navigate;
 	const dispose = router.dispose;
-	let sequence = 0;
 	let stopped = false;
 	let replay = false;
-	const valid = (current) => current === sequence && !stopped;
-	const unsubscribe = router.subscribe(() => {
-		if (read().state === "submitting") sequence++;
+	const dataRouter = router;
+	const createFetcher = dataRouter.createFetcher;
+	const submit = dataRouter.submit;
+	const trackSubmission = (submit) => (...args) => {
+		state.sequence++;
+		state.mutations++;
+		return submit(...args).finally(() => {
+			state.mutations--;
+		});
+	};
+	const guardedSubmit = submit && trackSubmission(submit);
+	const guardedFetcher = createFetcher && (() => {
+		const fetcher = createFetcher();
+		fetcher.submit = trackSubmission(fetcher.submit);
+		return fetcher;
 	});
+	if (guardedSubmit) dataRouter.submit = guardedSubmit;
+	if (guardedFetcher) dataRouter.createFetcher = guardedFetcher;
+	const valid = (current) => current === state.sequence && !stopped;
+	const canReload = (current) => valid(current) && state.mutations === 0;
 	const guarded = async (href, operation) => {
 		const target = new URL(href, router.getSnapshot().url);
 		const currentURL = new URL(router.getSnapshot().url);
-		const current = ++sequence;
+		const current = ++state.sequence;
 		if (target.origin === location.origin && (target.pathname !== currentURL.pathname || target.search !== currentURL.search) && await changed()) {
-			if (!valid(current) || await reload(target, () => valid(current))) return;
+			if (!valid(current) || await reload(target, () => canReload(current))) return;
 		}
-		if (current === sequence && !stopped) await navigate(href, operation);
+		if (current === state.sequence && !stopped) await navigate(href, operation);
 	};
 	const pop = (event) => {
 		if (replay) return;
 		const target = new URL(location.href);
 		const previous = new URL(read().url);
-		const current = ++sequence;
+		const current = ++state.sequence;
 		if (target.pathname === previous.pathname && target.search === previous.search) return;
 		event.stopImmediatePropagation();
 		changed().then(async (updated) => {
 			if (!valid(current)) return;
-			if (updated && await reload(target, () => valid(current))) return;
+			if (updated && await reload(target, () => canReload(current))) return;
 			if (!valid(current)) return;
 			replay = true;
 			window.dispatchEvent(new PopStateEvent("popstate", { state: event.state }));
@@ -42,19 +64,22 @@ function watchDeployment(router, options) {
 	};
 	const preloadError = () => {
 		if (read().state !== "loading") return;
-		const current = sequence;
+		const current = state.sequence;
 		const target = new URL(read().url);
 		changed().then((updated) => {
-			if (updated) return reload(target, () => valid(current) && read().state !== "submitting" && read().url === target.href);
+			if (updated) return reload(target, () => canReload(current) && read().state !== "submitting" && read().url === target.href);
 		});
 	};
 	function cleanup() {
+		if (stopped) return;
+		if (state.cleanup === cleanup) state.cleanup = void 0;
 		stopped = true;
-		sequence++;
+		state.sequence++;
 		check.dispose();
-		unsubscribe();
 		window.removeEventListener("popstate", pop, true);
 		window.removeEventListener("vite:preloadError", preloadError);
+		if (guardedSubmit && dataRouter.submit === guardedSubmit) dataRouter.submit = submit;
+		if (guardedFetcher && dataRouter.createFetcher === guardedFetcher) dataRouter.createFetcher = createFetcher;
 		if (router.navigate === guarded) router.navigate = navigate;
 		if (router.dispose === guardedDispose) router.dispose = dispose;
 	}
@@ -62,6 +87,7 @@ function watchDeployment(router, options) {
 		cleanup();
 		dispose();
 	}
+	state.cleanup = cleanup;
 	router.navigate = guarded;
 	router.dispose = guardedDispose;
 	window.addEventListener("popstate", pop, true);

package/dist/files/index.js

@@ -26,15 +26,16 @@ async function flatRoutes(directory) {
 				if (!entry.isFile() || !flatFile.test(name) || name.endsWith(".d.ts")) continue;
 				name = name.replace(flatFile, "");
 			}
-			if (/[()[\]:*?]/.test(name)) return /* @__PURE__ */ new Error(`Unsupported flat route name: ${name}`);
-			const segments = name.split(".");
+			const escaped = name.replaceAll("[.]", "\0");
+			if (/[()[\]:*?]/.test(escaped)) return /* @__PURE__ */ new Error(`Unsupported flat route name: ${name}`);
+			const segments = escaped.split(".");
 			const parts = [];
 			for (const [index, segment] of segments.entries()) {
 				if (!segment) return /* @__PURE__ */ new Error(`Empty route segment: ${name}`);
 				if (segment === "_index" && index !== segments.length - 1) return /* @__PURE__ */ new Error(`_index must be last: ${name}`);
 				if (segment === "$" && index !== segments.length - 1) return /* @__PURE__ */ new Error(`Splat must be last: ${name}`);
 				if (segment.startsWith("_")) continue;
-				const part = segment.replace(/_$/, "");
+				const part = segment.replace(/_$/, "").replaceAll("\0", ".");
 				parts.push(part === "$" ? "*" : part.replace(/^\$/, ":"));
 			}
 			if (segments.at(-1)?.startsWith("_") && segments.at(-1) !== "_index") continue;

package/dist/preact/await-fallback.d.ts

@@ -0,0 +1,4 @@
+import type { AwaitProps } from "./await.tsx";
+export declare function AwaitFallback<T>({ resolve, fallback, errorElement, children, }: AwaitProps<T> & {
+    resolve: Promise<T>;
+}): import("preact").ComponentChildren;

package/dist/preact/await-fallback.js

@@ -0,0 +1,29 @@
+import { useEffect, useState } from "preact/hooks";
+//#region .generated/preact/await-fallback.tsx
+/** @jsxImportSource preact */
+function AwaitFallback({ resolve, fallback, errorElement, children }) {
+	const [result, setResult] = useState();
+	useEffect(() => {
+		let current = true;
+		resolve.then((value) => {
+			if (current) setResult({
+				source: resolve,
+				value
+			});
+		}, (error) => {
+			if (current) setResult({
+				source: resolve,
+				error
+			});
+		});
+		return () => {
+			current = false;
+		};
+	}, [resolve]);
+	if (!result || result.source !== resolve) return fallback;
+	if ("value" in result) return children(result.value);
+	if (errorElement !== void 0) return errorElement;
+	throw result.error;
+}
+//#endregion
+export { AwaitFallback };

package/dist/preact/await.d.ts

@@ -1,7 +1,10 @@
+/** @jsxImportSource preact */
 import type { ComponentChildren } from "preact";
 export interface AwaitProps<T> {
     resolve: T | Promise<T>;
     children: (value: Awaited<T>) => ComponentChildren;
     errorElement?: ComponentChildren;
+    /** Component-owned pending content, safe during early hydration. Pass null to render nothing. */
+    fallback?: ComponentChildren;
 }
-export declare function Await<T>({ resolve, children, errorElement, }: AwaitProps<T>): ComponentChildren;
+export declare function Await<T>(props: AwaitProps<T>): ComponentChildren;

package/dist/preact/await.js

@@ -1,8 +1,26 @@
-import { use } from "preact/compat";
+import { AwaitFallback } from "./await-fallback.js";
+import { Application } from "./root-context.js";
+import { use, useContext } from "preact/compat";
+import { jsx } from "preact/jsx-runtime";
 //#region .generated/preact/await.tsx
 var resolutions = /* @__PURE__ */ new WeakMap();
-function Await({ resolve, children, errorElement }) {
-	if (!(resolve instanceof Promise)) return children(resolve);
+function Await(props) {
+	const app = useContext(Application);
+	if (!(props.resolve instanceof Promise)) return props.children(props.resolve);
+	if (!("fallback" in props)) return /* @__PURE__ */ jsx(SuspendedAwait, {
+		...props,
+		resolve: props.resolve
+	});
+	if (app?.deferredBoundary) return app.deferredBoundary(/* @__PURE__ */ jsx(SuspendedAwait, {
+		...props,
+		resolve: props.resolve
+	}), props.fallback);
+	return /* @__PURE__ */ jsx(AwaitFallback, {
+		...props,
+		resolve: props.resolve
+	});
+}
+function SuspendedAwait({ resolve, children, errorElement }) {
 	let pending = resolutions.get(resolve);
 	if (!pending) {
 		pending = resolve.then((value) => ({ value }), (error) => ({ error }));

package/dist/preact/client.d.ts

@@ -8,5 +8,7 @@ export { configureApplication } from "../core/environment.ts";
 export interface MountApplicationOptions {
     hash?: boolean;
     deployment?: DeploymentOptions | null;
+    /** Total initial deferred-data budget in integer milliseconds; not an inactivity timeout. Defaults to 30,000. */
+    deferredTimeout?: number;
 }
 export declare function mountApplication(routes: AppRoute[], rootModule?: RootModule, options?: boolean | MountApplicationOptions): Promise<Router>;

package/dist/preact/client.js

@@ -16,7 +16,7 @@ import { hydrate, render } from "preact";
 /** Browser mounting and hydration for Preact applications. @module */
 /** @jsxImportSource preact */
 async function mountApplication(routes, rootModule, options = false) {
-	const { hash = false, deployment = null } = typeof options === "boolean" ? { hash: options } : options;
+	const { hash = false, deployment = null, deferredTimeout } = typeof options === "boolean" ? { hash: options } : options;
 	const initialURL = new URL(hash ? location.hash.slice(1) || "/" : location.href, location.origin);
 	await (matchRoutes(routes, initialURL.pathname)?.route)?.preload?.().catch(async (error) => {
 		await recoverDeployment(deployment, initialURL);
@@ -24,7 +24,7 @@ async function mountApplication(routes, rootModule, options = false) {
 	});
 	routes = prepareRoutes(routes);
 	const element = document.getElementById("smolter-data");
-	const initial = element?.textContent ? readHydration(element.textContent) : void 0;
+	const initial = element?.textContent ? readHydration(element.textContent, deferredTimeout) : 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, {

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

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

package/dist/preact/deferred-hydration.js

@@ -1,6 +1,7 @@
 //#region .generated/preact/deferred-hydration.ts
 /** Restore promise identity before hydrating Suspense boundaries. */
-function readHydration(json) {
+function readHydration(json, timeout = 3e4) {
+	if (!Number.isInteger(timeout) || timeout < 1 || timeout > 2147483647) throw new RangeError("deferredTimeout must be an integer between 1 and 2147483647 ms");
 	const pending = /* @__PURE__ */ new Map();
 	const queue = window.__smolterDeferred ??= [];
 	function revive(_key, value) {
@@ -34,11 +35,16 @@ function readHydration(json) {
 	}
 	const hydration = JSON.parse(json, revive);
 	const dispose = () => {
+		clearTimeout(deadline);
 		window.removeEventListener("DOMContentLoaded", dispose);
 		for (const target of pending.values()) target.reject(/* @__PURE__ */ new Error("Hydration stream closed"));
 		pending.clear();
 		queue.push = () => 0;
 	};
+	const deadline = pending.size ? setTimeout(() => {
+		for (const target of pending.values()) target.reject(/* @__PURE__ */ new Error("Hydration stream timed out"));
+		dispose();
+	}, timeout) : void 0;
 	const receive = (packet) => {
 		const [id, value, error] = packet;
 		if (id === -1) return dispose();

package/dist/preact/document.js

@@ -1,9 +1,9 @@
 import { serializeData } from "../core/serialize.js";
+import { useApplication } from "./root-context.js";
 import { useSnapshot } from "./context.js";
 import { applicationEnvironment } from "../core/environment.js";
 import { scrollPositions } from "../core/navigation.js";
 import { useNavigationSnapshot } from "./navigation-state.js";
-import { useApplication } from "./root-context.js";
 import { useEffect, useLayoutEffect, useRef, useState } from "preact/hooks";
 import { Fragment, jsx, jsxs } from "preact/jsx-runtime";
 import { Fragment as Fragment$1, createElement } from "preact";

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

@@ -6,6 +6,7 @@ export interface ApplicationContext {
     root: unknown;
     rootError?: boolean;
     streaming?: boolean;
+    deferredBoundary?: (children: import("preact").ComponentChildren, fallback: import("preact").ComponentChildren) => import("preact").ComponentChildren;
     initialData?: string;
     rootModule?: RootModule;
     hydration?: Hydration;

package/dist/preact/route-hooks.js

@@ -1,9 +1,9 @@
 import { submissionBody, submissionSearch } from "../core/submission.js";
 import { useContext, useMemo } from "./runtime.js";
+import { OutletContext, useApplication } from "./root-context.js";
 import { useRouter, useSnapshot } from "./context.js";
 import { pendingLocation } from "../core/presentation.js";
 import { useNavigationSnapshot } from "./navigation-state.js";
-import { OutletContext, useApplication } from "./root-context.js";
 import { useCallback } from "preact/hooks";
 //#region .generated/preact/route-hooks.tsx
 function useRootData() {

package/dist/preact/router.js

@@ -1,8 +1,8 @@
 import { normalizeResult } from "../core/responses.js";
 import { useContext, useMemo, useSyncExternalStore } from "./runtime.js";
+import { Application, OutletContext } from "./root-context.js";
 import { RouterProvider } from "./context.js";
 import { createStore } from "../core/store.js";
-import { Application, OutletContext } from "./root-context.js";
 import { Routes } from "./routes.js";
 import { jsx } from "preact/jsx-runtime";
 //#region .generated/preact/router.tsx

package/dist/server/application.js

@@ -8,6 +8,7 @@ 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 { Suspense } from "preact/compat";
 import { jsx } from "preact/jsx-runtime";
 import { renderToReadableStream } from "preact-render-to-string/stream";
 //#region .generated/server/application.tsx
@@ -91,6 +92,7 @@ async function renderApplication(request, routes, rootModule, entry, options = {
 		entry,
 		rootError: Boolean(rootError),
 		streaming: true,
+		deferredBoundary: options.earlyHydration ? void 0 : deferredBoundary,
 		initialData: deferred?.initial,
 		document: true
 	}), options);
@@ -113,6 +115,12 @@ async function renderApplication(request, routes, rootModule, entry, options = {
 		headers
 	});
 }
+function deferredBoundary(children, fallback) {
+	return /* @__PURE__ */ jsx(Suspense, {
+		fallback,
+		children
+	});
+}
 async function dispatch(request, routes, document = false) {
 	const match = matchRoutes(routes.map((route) => ({
 		...route,

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

@@ -56,10 +56,7 @@ function lazyFiles(directory, dataEndpoint = "/_smolter") {
 				const source = await readFile(route.file, "utf8");
 				const transformed = await transformWithOxc(source, route.file);
 				const ast = this.parse(transformed.code);
-				const fields = {
-					path: route.path,
-					dataEndpoint
-				};
+				const fields = {};
 				for (const statement of ast.body) {
 					if (statement.type === "ExportDefaultDeclaration") {
 						fields.default = true;
@@ -75,14 +72,11 @@ function lazyFiles(directory, dataEndpoint = "/_smolter") {
 						fields[name] = true;
 					}
 					if (statement.declaration?.type !== "VariableDeclaration") continue;
-					for (const declaration of statement.declaration.declarations) {
-						if (declaration.id.type === "Identifier") fields[declaration.id.name] = true;
-						if (declaration.id.type !== "Identifier" || declaration.init?.type !== "Literal" || typeof declaration.init.value !== "string") continue;
-						const name = declaration.id.name;
-						if (name === "id") fields.id = declaration.init.value;
-						if (name === "routePath") fields.path = declaration.init.value;
-					}
+					for (const declaration of statement.declaration.declarations) if (declaration.id.type === "Identifier") fields[declaration.id.name] = true;
 				}
+				if (fields.id || fields.routePath) return this.error(`File routes derive identity and paths from filenames: remove id/routePath exports from ${route.file}. Use [.] for a literal dot.`);
+				fields.path = route.path;
+				fields.dataEndpoint = dataEndpoint;
 				const file = `${route.file.replaceAll("\\", "/")}?smolter-client`;
 				if (fields.default) modules.set(file, String(fields.path));
 				definitions.push(`lazyRoute(${JSON.stringify(fields)}, () => import(${JSON.stringify(file)}))`);

package/dist/vite/index.js

@@ -69,6 +69,12 @@ function routerPlugin({ directory = "src/routes", dataEndpoint = "/_smolter", cl
 				const handlers = {};
 				for (const statement of ast.body) {
 					if (statement.type !== "ExportNamedDeclaration") continue;
+					const declared = statement.declaration;
+					const names = statement.specifiers.map((specifier) => specifier.exported.type === "Identifier" ? specifier.exported.name : specifier.exported.value);
+					if (declared?.type === "VariableDeclaration") {
+						for (const item of declared.declarations) if (item.id.type === "Identifier") names.push(item.id.name);
+					}
+					if (names.some((name) => name === "id" || name === "routePath")) return this.error(`File routes derive identity and paths from filenames: remove id/routePath exports from ${file}. Use [.] for a literal dot.`);
 					for (const specifier of statement.specifiers) {
 						const name = specifier.exported.type === "Identifier" ? specifier.exported.name : specifier.exported.value;
 						if (name === "loader" || name === "action") handlers[name] = true;

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@kasperrt/smolter",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "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.4.0",
+  "version": "0.4.2",
   "description": "A tiny typed data router for React and Preact.",
   "sideEffects": false,
   "license": "MIT",