@kasperrt/smolter 0.4.1 → 0.4.3

package/.generated/client/deployment.ts

@@ -1,6 +1,14 @@
 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;
@@ -18,47 +26,50 @@ export function watchDeployment(
 ): () => 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;
-  let mutations = 0;
   const dataRouter = router as NavigationRouter &
-    Partial<Pick<Router, "createFetcher">>;
+    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();
-      const submit = fetcher.submit;
-
-      fetcher.submit = (...args) => {
-        sequence++;
-        mutations++;
-
-        return submit(...args).finally(() => {
-          mutations--;
-        });
-      };
+      fetcher.submit = trackSubmission(fetcher.submit);
 
       return fetcher;
     });
 
+  if (guardedSubmit) dataRouter.submit = guardedSubmit;
   if (guardedFetcher) dataRouter.createFetcher = guardedFetcher;
-  const valid = (current: number) => current === sequence && !stopped;
-  const canReload = (current: number) => valid(current) && mutations === 0;
-  const unsubscribe = router.subscribe(() => {
-    if (read().state === "submitting") sequence++;
-  });
+  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 &&
@@ -70,7 +81,7 @@ export function watchDeployment(
         return;
     }
 
-    if (current === sequence && !stopped) await navigate(href, operation);
+    if (current === state.sequence && !stopped) await navigate(href, operation);
   };
 
   const pop = (event: PopStateEvent) => {
@@ -78,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 &&
@@ -105,7 +116,7 @@ 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)
@@ -120,14 +131,17 @@ 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 (dataRouter.createFetcher === guardedFetcher)
+    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;
@@ -138,6 +152,7 @@ export function watchDeployment(
     dispose();
   }
 
+  state.cleanup = cleanup;
   router.navigate = guarded;
   router.dispose = guardedDispose;
   window.addEventListener("popstate", pop, true);

package/.generated/core/environment.ts

@@ -1,3 +1,4 @@
+/** Application base URLs, navigation handoff and document-transition settings shared by browser integrations. */
 export interface ApplicationEnvironment {
   resolveURL?: (url: URL) => URL;
   isDocumentHandoff?: (from: URL, to: URL) => boolean;

package/.generated/core/navigation.ts

@@ -7,6 +7,7 @@ import { createStore } from "./store.ts";
 import type { NavigateOptions, Router } from "./types.ts";
 import { navigationClick } from "./url.ts";
 
+/** Browser history operation: POP, PUSH or REPLACE. */
 export type NavigationType = "POP" | "PUSH" | "REPLACE";
 
 export interface NavigationSnapshot {

package/.generated/core/resource-types.ts

@@ -1,16 +1,19 @@
 export type Params = Readonly<Record<string, string>>;
 
+/** Resource parameters and cancellation signal supplied to a loader. */
 export interface LoaderFunctionArgs {
   params: Params;
   signal: AbortSignal;
 }
 
+/** Submitted input, resource parameters and cancellation signal supplied to an action. */
 export interface ActionFunctionArgs<Input = unknown> {
   input: Input;
   params: Params;
   signal: AbortSignal;
 }
 
+/** Successful resource data or a normalized resource failure. */
 export interface DataResult<Data> {
   data: Data | null;
   error: string;
@@ -23,6 +26,7 @@ export interface ResourceModule {
   shouldRevalidate?: (args: ShouldRevalidateFunctionArgs) => boolean;
 }
 
+/** Navigation or mutation context used to decide whether loader data should refresh. */
 export interface ShouldRevalidateFunctionArgs {
   actionResult: DataResult<unknown>;
   defaultShouldRevalidate: boolean;

package/.generated/core/resources.ts

@@ -18,6 +18,7 @@ const IDLE_ROUTE_STATE: RouteState = {
   unexpectedError: false,
 };
 
+/** Manage keyed resource reads, submissions, subscriptions and cancellation independently of navigation. */
 export class ResourceRouter {
   readonly #cleanupTimers = new Map<string, ReturnType<typeof setTimeout>>();
   readonly #controllers = new Map<string, AbortController>();
@@ -427,6 +428,7 @@ export class ResourceRouter {
   }
 }
 
+/** Create an independent resource-data router from registered modules; this does not manage URL history. */
 export function createResourceRouter(
   routes: ReadonlyMap<string, ResourceModule>,
 ): ResourceRouter {

package/.generated/core/responses.ts

@@ -1,19 +1,28 @@
+/**
+ * HTTP response helpers and loader result normalization.
+ *
+ * @module
+ */
+/** Normalized route failure with an HTTP status, status text and optional response data. */
 export interface RouteError extends Error {
   status: number;
   statusText: string;
   data?: unknown;
 }
 
+/** Loader value paired with HTTP response metadata. */
 export interface DataResponse<T> {
   value: T;
   init: ResponseInit;
   __routeData: true;
 }
 
+/** Wrap loader data with HTTP status and headers without creating a Response body. */
 export function data<T>(value: T, init: ResponseInit = {}): DataResponse<T> {
   return { value, init, __routeData: true };
 }
 
+/** Create an empty redirect Response with a Location header; defaults to HTTP 302. */
 export function redirect(
   location: string,
   init: number | ResponseInit = 302,
@@ -29,10 +38,12 @@ export function redirect(
   });
 }
 
+/** Identify normalized Error objects carrying an HTTP status. */
 export function isRouteErrorResponse(value: unknown): value is RouteError {
   return value instanceof Error && "status" in value;
 }
 
+/** Normalize transport responses and wrapped data, optionally resolving nested deferred values. */
 export async function normalizeResult(
   value: unknown,
   resolveDeferred = true,
@@ -68,6 +79,7 @@ export async function normalizeResult(
 }
 
 // Smolter transfers JSON snapshots. Resolve deferred fields before serialization.
+/** Recursively resolve promises in arrays and plain objects before JSON serialization. */
 export async function resolveData(value: unknown): Promise<unknown> {
   const resolved = await value;
 

package/.generated/core/utils.ts

@@ -1,5 +1,8 @@
-/** Framework-independent, browser-safe utilities. @module */
-export * from "./errors.ts";
+/**
+ * Routing patterns, query strings and serialized data utilities.
+ *
+ * @module
+ */
 export * from "./match.ts";
 export * from "./serialize.ts";
 export * from "./url.ts";

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,26 @@ 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>({
+/** Render a value or promise. An explicit fallback owns pending content during early hydration; errorElement handles rejection. */
+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

@@ -1,4 +1,8 @@
-/** Browser mounting and hydration for Preact applications. @module */
+/**
+ * Preact document hydration, browser history and deployment recovery.
+ *
+ * @module
+ */
 /** @jsxImportSource preact */
 
 import {
@@ -19,18 +23,25 @@ import { prepareRoutes, RouterApplication } from "./router.tsx";
 export * from "../client/index.ts";
 export { configureApplication } from "../core/environment.ts";
 
+/** Browser hydration settings for hash history, deployment recovery and deferred-data timeout. */
 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;
 }
 
+/** Create the browser application router and hydrate the document, installing recovery before initial lazy loading. */
 export async function mountApplication(
   routes: AppRoute[],
   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 +59,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

@@ -11,7 +11,12 @@ export interface DeferredWindow extends Window {
 }
 
 /** 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 as DeferredWindow).__smolterDeferred ??= []);
 
@@ -54,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/document.tsx

@@ -1,3 +1,8 @@
+/**
+ * Preact document metadata, resource links and hydration scripts.
+ *
+ * @module
+ */
 /** @jsxImportSource preact */
 
 import { applicationEnvironment } from "../core/environment.ts";
@@ -34,6 +39,7 @@ function renderMeta(item: MetaDescriptor, index: number) {
   });
 }
 
+/** Render root or active-route metadata in the document head. */
 export function Meta(): import("preact").JSX.Element {
   const { routes, rootModule } = useApplication();
   const snapshot = useSnapshot();
@@ -55,6 +61,7 @@ export function Meta(): import("preact").JSX.Element {
   return <Fragment>{values.map(renderMeta)}</Fragment>;
 }
 
+/** Render stylesheet and other link descriptors from the application root. */
 export function Links(): import("preact").JSX.Element {
   const { rootModule } = useApplication();
 
@@ -67,10 +74,12 @@ export function Links(): import("preact").JSX.Element {
   );
 }
 
+/** Nonce and browser entry options for the document hydration scripts. */
 export interface ScriptProps {
   nonce?: string;
 }
 
+/** Render the hydration snapshot and browser entry script with an optional CSP nonce. */
 export function Scripts({ nonce }: ScriptProps): import("preact").JSX.Element {
   const { root, rootError, router, entry, streaming, initialData } =
     useApplication();
@@ -119,6 +128,7 @@ export function Scripts({ nonce }: ScriptProps): import("preact").JSX.Element {
   );
 }
 
+/** Reset scroll after navigation unless the navigation requests preservation. */
 export function ScrollRestoration(_props: ScriptProps): null {
   const { router } = useApplication();
   const { url, state } = useSnapshot();

package/.generated/preact/index.ts

@@ -1,4 +1,8 @@
-/** Framework components and typed data hooks. @module */
+/**
+ * Preact routing components, typed data hooks and application integration.
+ *
+ * @module
+ */
 export type * from "../core/index.ts";
 export {
   createDataRouter,
@@ -30,5 +34,5 @@ export {
   useSubmit,
 } from "./route-hooks.tsx";
 export * from "./route-types.ts";
-export { Outlet, RouterApplication } from "./router.tsx";
+export { Outlet, type OutletProps, RouterApplication } from "./router.tsx";
 export * from "./routes.ts";

package/.generated/preact/lazy-route.ts

@@ -1,3 +1,8 @@
+/**
+ * On-demand Preact route modules with shared intent prefetching.
+ *
+ * @module
+ */
 import { serverRoute } from "../client/index.ts";
 import type { DataArgs, RouteModule, Router } from "../core/index.ts";
 import { type ComponentType, createElement } from "preact";
@@ -6,6 +11,7 @@ import type { AppRoute } from "./route-types.ts";
 import type { ErrorProps } from "./routes.ts";
 import { useSyncExternalStore } from "./runtime.ts";
 
+/** Lazy route path, server transport endpoint and available handler capabilities. */
 export interface LazyRouteOptions {
   path: string;
   dataEndpoint?: string;
@@ -36,6 +42,7 @@ function LazyView() {
   return Component && createElement(Component, {});
 }
 
+/** Create a route that imports its module on demand and shares the import with intent prefetching. */
 export function lazyRoute(
   options: LazyRouteOptions,
   importer: () => Promise<LoadedRoute>,

package/.generated/preact/navigation.tsx

@@ -15,11 +15,13 @@ export type { NavigateOptions } from "../core/index.ts";
 
 export type { NavigationType } from "../core/navigation.ts";
 
+/** Navigate to a URL or move through browser history using a numeric offset. */
 export type NavigateFunction = (
   to: string | number | Partial<Pick<URL, "pathname" | "search" | "hash">>,
   options?: NavigateOptions,
 ) => void;
 
+/** Anchor properties and router navigation options, including document reload and prefetch controls. */
 export interface LinkProps extends Omit<ComponentProps<"a">, "href" | "role"> {
   to?: string;
   href?: string;
@@ -47,11 +49,13 @@ export interface LinkProps extends Omit<ComponentProps<"a">, "href" | "role"> {
   reloadDocument?: boolean;
 }
 
+/** Active and pending flags supplied to NavLink render callbacks. */
 export interface NavLinkRenderProps {
   isActive: boolean;
   isPending: boolean;
 }
 
+/** Link options with matching rules and state-aware class or children callbacks. */
 export interface NavLinkProps
   extends Omit<LinkProps, "className" | "children"> {
   end?: boolean;
@@ -59,6 +63,7 @@ export interface NavLinkProps
   children?: ReactNode | ((state: NavLinkRenderProps) => ReactNode);
 }
 
+/** Render an anchor with same-origin router navigation and optional intent prefetching. */
 export function Link(options: LinkProps): ReactNode {
   const {
     href: hrefProp,
@@ -115,6 +120,7 @@ export function Link(options: LinkProps): ReactNode {
   });
 }
 
+/** Render a Link with active-route state and aria-current for the matching destination. */
 export function NavLink({
   href,
   to = href ?? "/",

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/preact/route-hooks.tsx

@@ -15,6 +15,7 @@ import { OutletContext, useApplication } from "./root-context.ts";
 import type { RouteData } from "./route-types.ts";
 import { useContext, useMemo } from "./runtime.ts";
 
+/** Read root loader data from the application context. */
 export function useRootData<T = unknown>(): RouteData<T> {
   return useApplication().root as RouteData<T>;
 }
@@ -37,10 +38,12 @@ export function useRouteLoaderData<T = unknown>(
 
 export { useSnapshot };
 
+/** Read the current route error for an error boundary. */
 export function useRouteError(): Error | undefined {
   return useSnapshot("error");
 }
 
+/** Read the current page navigation or submission state. */
 export function useNavigation(): {
   state: "idle" | "loading" | "submitting";
   location: URL | undefined;
@@ -58,24 +61,27 @@ export function useNavigation(): {
   );
 }
 
+/** Read the active flat route match and loader data; this is not a nested layout match chain. */
 export function useMatches(): {
   id: string;
   data: unknown;
   params: import("../core/index.ts").Params;
 }[] {
-  const { routes } = useApplication();
+  const router = useRouter();
   const snapshot = useSnapshot();
-  const route = routes.find((item) => item.path === snapshot.path);
+  const route = router.routes.find((item) => item.path === snapshot.path);
 
   return [
     { id: route?.id ?? "", data: snapshot.data, params: snapshot.params },
   ];
 }
 
+/** Read context supplied by the nearest Outlet. */
 export function useOutletContext<T>(): T {
   return useContext(OutletContext) as T;
 }
 
+/** Return a function that submits form data through the current router. */
 export function useSubmit(): (
   value: Submission,
   options?: SubmissionOptions,
@@ -103,6 +109,7 @@ export function useSubmit(): (
   );
 }
 
+/** Read the current router location as a URL. */
 export function useURLLocation(): URL & { state: unknown; key: string } {
   const href = useSnapshot("url");
   const snapshot = useNavigationSnapshot(useRouter<Router>());
@@ -117,6 +124,7 @@ export function useURLLocation(): URL & { state: unknown; key: string } {
   );
 }
 
+/** Return the application navigation function, including history offsets and relative destinations. */
 export function useNavigate(): NavigateFunction {
   const router = useRouter<Router>();
 
@@ -139,6 +147,7 @@ export function useNavigate(): NavigateFunction {
   );
 }
 
+/** Read URL search parameters and update them through router navigation. */
 export function useSearchParams(): [
   URLSearchParams,
   (
@@ -165,6 +174,7 @@ export function useSearchParams(): [
   return [params, set];
 }
 
+/** Read the last browser history operation. */
 export function useNavigationType(): NavigationType {
   return useNavigationSnapshot(useRouter<Router>()).type;
 }