@kasperrt/smolter 0.2.0 → 0.3.1

package/README.md

@@ -1,8 +1,8 @@
 # smolter _
 
 <!-- bundlejs:start -->
-[![react gzip size](https://deno.bundlejs.com/?q=%40kasperrt%2Fsmolter%400.2.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.2.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.2.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.2.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.3.1%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.1%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.1%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.1%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.**
@@ -20,6 +20,8 @@ Start with [loaders](https://kasperrt.github.io/smolter/react/docs/loaders/), [a
 
 ## Contents
 
+- [Deployment updates](#deployment-updates)
+
 - [Install](#install)
 - [Try the four standalone examples](#try-the-four-standalone-examples)
 - [Choose file routing or manual routes](#choose-file-routing-or-manual-routes)
@@ -29,7 +31,10 @@ Start with [loaders](https://kasperrt.github.io/smolter/react/docs/loaders/), [a
 - [Types follow the handler](#types-follow-the-handler)
 - [Server rendering](#server-rendering)
 - [Package entries](#package-entries)
+- [Application integration](#application-integration)
+- [Resource subscriptions](#resource-subscriptions)
 - [Size and checks](#size-and-checks)
+- [Routing without data hooks](#routing-without-data-hooks)
 
 ## Install
 
@@ -40,7 +45,7 @@ pnpm add @kasperrt/smolter
 ```
 
 ```ts
-import { createRouter, useFetcher } from "@kasperrt/smolter/react";
+import { createDataRouter, useFetcher } from "@kasperrt/smolter/react";
 // Preact: import from "@kasperrt/smolter/preact".
 ```
 
@@ -61,7 +66,8 @@ pnpm dev
 Each app has its own entrypoints, routes, and data code. Only UI components are
 shared. Preact examples do not import React. Each includes:
 
-- `/`: counter, fetcher POST, automatic and manual revalidation.
+- `/`: a short introduction and a link to the docs.
+- `/examples/counter`: fetcher POST, automatic and manual revalidation.
 - `/tasks`: list, create form, and a fetcher-only task preview.
 - `/tasks/:id`: PATCH, DELETE, validation, and skipping no-op revalidation.
 - `/about`: the separation between data and rendering.
@@ -94,10 +100,10 @@ export default defineConfig({
 
 ```ts
 // app.ts
-import { createRouter } from "@kasperrt/smolter/react";
+import { createDataRouter } from "@kasperrt/smolter/react";
 import routes from "virtual:smolter/routes";
 
-export const router = createRouter(routes, { browser: true });
+export const router = createDataRouter(routes, { browser: true });
 ```
 
 | File or folder | URL |
@@ -136,14 +142,14 @@ Outside Vite, `flatRoutes(directory)` from `@kasperrt/smolter/react/vite` return
 ### Manual routes
 
 ```tsx
-import { createRouter, defineRoute } from "@kasperrt/smolter/react";
+import { createDataRouter, defineRoute } from "@kasperrt/smolter/react";
 import * as tasks from "./tasks/route";
 import * as task from "./task/route";
 
 export const tasksRoute = defineRoute("/tasks", tasks);
 export const taskRoute = defineRoute("/tasks/:id", task);
 export const routes = [tasksRoute, taskRoute];
-export const router = createRouter(routes, { browser: true });
+export const router = createDataRouter(routes, { browser: true });
 ```
 
 Or pass handlers directly to `defineRoute(path, { loader, action, default: View })`.
@@ -171,11 +177,12 @@ export { default } from "./view";
 export { loader } from "./loader";
 export { action } from "./action";
 
-export { clientLoader } from "./client-loader";
-export { clientAction } from "./client-action";
+export { clientLoader } from "./clientLoader";
+export { clientAction } from "./clientAction";
 
-export { shouldRevalidate } from "./should-revalidate";
-export { HydrateFallback, ErrorBoundary } from "../../boundaries";
+export { shouldRevalidate } from "./shouldRevalidate";
+export { HydrateFallback } from "./HydrateFallback";
+export { ErrorBoundary } from "./ErrorBoundary";
 ```
 
 With the optional server integration:
@@ -187,7 +194,7 @@ With the optional server integration:
 - SSR executes the server loader and hydration reuses that data.
 
 ```ts
-// client-loader.ts
+// clientLoader.ts
 import type { ClientLoaderArgs } from "@kasperrt/smolter/react/client";
 import type { loader } from "./loader";
 
@@ -197,7 +204,7 @@ export async function clientLoader({ serverLoader }: ClientLoaderArgs<typeof loa
 ```
 
 ```ts
-// client-action.ts
+// clientAction.ts
 import type { ClientActionArgs } from "@kasperrt/smolter/react/client";
 import type { action } from "./action";
 
@@ -258,7 +265,7 @@ routerPlugin({
 
 Each table exports `routes`. The standalone examples contain both tables.
 
-Without the optional integration, `createRouter` invokes handlers locally:
+Without the optional integration, `createDataRouter` invokes handlers locally:
 client handlers take precedence, with ordinary handlers as fallbacks.
 `loadRouter` selects server handlers only. Core-only usage does not create HTTP
 endpoints or compiler boundaries by itself.
@@ -319,7 +326,7 @@ Fetcher results belong to `fetcher.data`, not `useActionData()`.
 ## Decide when to revalidate
 
 ```ts
-// should-revalidate.ts
+// shouldRevalidate.ts
 import type { RevalidationArgs } from "@kasperrt/smolter/react";
 
 export function shouldRevalidate({ actionResult, defaultShouldRevalidate }: RevalidationArgs) {
@@ -344,7 +351,25 @@ and explicit `fetcher.load()` calls always load their destination.
 This controls loader refreshes; it does not rerun actions or reload the document.
 Existing page data stays visible during manual and post-action refreshes.
 
-`const revalidate = useRevalidator(); await revalidate()` requests a manual refresh.
+`useRevalidator()` returns an async function. Target a registered route ID or path
+pattern to refresh only its active data, including loaded fetchers:
+
+```tsx
+const revalidate = useRevalidator();
+
+await revalidate({ route: "/tasks/:id" });
+await revalidate({ route: "root" });
+await revalidate({ route: ["root", "/tasks/:id"] });
+```
+
+Without a target, `revalidate()` refreshes the active page, loaded fetchers, and
+registered root/layout data. `shouldRevalidate` still applies. Inactive routes
+are not loaded, unknown targets do nothing, and revalidation never navigates.
+
+The Preact root integration uses `root` as its default ID. Configure its
+`loaderPath` with a registered data route to enable root refreshes. Custom React
+or Preact layouts can use `router.registerRevalidator(id, callback)`; call its
+returned cleanup function when the layout is removed.
 The task-detail examples return `{ changed: false }` for an unchanged title;
 the corresponding loader is skipped.
 
@@ -381,17 +406,17 @@ const hydrationJSON = serialize(router.getSnapshot());
 
 Create a fresh router per request. Embed the serialized snapshot in a JSON
 script, restore it with `deserialize` from `@kasperrt/smolter/react/client`, and pass it as
-`hydrationData` to `createRouter`. This preserves loader errors through hydration
+`hydrationData` to `createDataRouter`. This preserves loader errors through hydration
 without exposing server stacks or causes. Error boundaries should display the
 error message, not its stack.
 
 ```ts
 import { deserialize } from "@kasperrt/smolter/react/client";
-import { createRouter } from "@kasperrt/smolter/react";
+import { createDataRouter } from "@kasperrt/smolter/react";
 import routes from "virtual:smolter/routes";
 
 const data = document.getElementById("smolter-data");
-const router = createRouter(routes, {
+const router = createDataRouter(routes, {
   browser: true,
   hydrationData: data?.textContent ? deserialize(data.textContent) : undefined,
 });
@@ -406,7 +431,7 @@ The SSR examples use the same server route definitions for HTML and data request
 
 ## Package entries
 
-Use `@kasperrt/smolter/react` for React 18+ and `@kasperrt/smolter/preact` for Preact 10.25+.
+Use `@kasperrt/smolter/react` for React 18+ and `@kasperrt/smolter/preact` for Preact 11.0.1+.
 Choose one renderer for your application. Both expose the same routing API:
 
 | Purpose | React | Preact |
@@ -421,39 +446,196 @@ The main renderer entries never import server or build modules. Named imports
 are tree-shaken; optional transport is included only when you import `/client`.
 Server entries do not import either UI renderer. Vite entries are build-time only.
 
-**Migrating to 0.2.0:** replace `/core` imports for types, `createRouter`, and
+**Migrating renderer subpaths:** replace `/core` imports for types, router factories, and
 `defineRoute` with your renderer entry. Use `/utils` for `matchRoutes`,
 `internalURL` and `safeWrapAsync`. Move `/client`, `/server`,
 `/files`, and `/vite` imports to the corresponding renderer-prefixed path above.
 The bare package root and old top-level subpaths are no longer exported.
 
+See the [0.3 migration guide](https://kasperrt.github.io/smolter/react/docs/migration-0.3/) and [changelog](./CHANGELOG.md).
+
+**Router factory migration:** code that previously used `createRouter` with
+loaders, actions, fetchers or revalidation must now use `createDataRouter`.
+`createRouter` now creates a navigation-only router. SSR and file-router
+application helpers select `createDataRouter` automatically.
+
 On JSR, install `@kasperrt/smolter` using the
 [JSR package instructions](https://jsr.io/docs/npm-compatibility) and import
-`@kasperrt/smolter/react` or `@kasperrt/smolter/preact`. Its `core`, `client`,
-`server`, and `files` subpaths match npm. The Vite plugin is npm-only:
+`@kasperrt/smolter/react` or `@kasperrt/smolter/preact`. Its renderer, client, server and utility subpaths match npm. The Vite plugin is npm-only:
 use `@kasperrt/smolter/react/vite` from the npm package when adding file routing.
 
+## Application integration
+
+Import routing, forms and data hooks from `@kasperrt/smolter/preact`.
+Document rendering is optional: `@kasperrt/smolter/preact/document` supplies
+`Document`, `Meta`, `Links`, `Scripts` and `ScrollRestoration`.
+`@kasperrt/smolter/preact/client` supplies `mountApplication`,
+`configureApplication` and the server transport helpers. Mounting connects
+hydration, root data and navigation presentation to the same core router.
+These modules remain tree-shakable; basic routing does not import the document
+or mounting code. The size table also measures all three together, because
+moving APIs to subpaths does not make their implementation disappear.
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { applicationPlugins } from "@kasperrt/smolter/preact/vite";
+
+export default defineConfig({
+  plugins: applicationPlugins({ directory: "src/routes" }),
+});
+```
+
+```tsx
+// src/entry.client.tsx
+import routes from "virtual:smolter/routes";
+import { mountApplication } from "@kasperrt/smolter/preact/client";
+import * as root from "./root";
+
+mountApplication(routes, root);
+```
+
+`root` exports a default component containing `Outlet` and a `Layout` wrapping
+it in `Document`, a head, and a body containing `Scripts`. Its optional loader
+supplies root data. `renderApplication(request, routes, root, entry)` from
+`preact/server` renders the same tree and serializes hydration data;
+`dispatchRoute(request, routes)` handles route data requests. Server rendering
+requires the optional `preact-render-to-string` peer.
+
+Deployment-specific URL mapping can be configured once at startup with
+`configureApplication({ resolveURL, isDocumentHandoff, leaveDocument,
+entryScript })`. Do not put user-specific or request-specific state there.
+The library does not define application domains, ports, or branding.
+
+`utils/http` contains the Node request/response adapter; `utils/assets` contains
+manifest/preload helpers; `utils/responses` contains response normalization.
+Keep the first two in server/build entrypoints. Browser application imports do
+not include them.
+
+### Virtual modules and entrypoints
+
+`virtual:smolter/routes` is the default route-array export generated by the Vite
+plugin from `src/routes`. It is not a physical file or a runtime package.
+The server build retains loaders/actions; the browser build strips their
+re-exports and installs server proxies. `entry.client.tsx` and `entry.server.tsx`
+are application-owned files wiring those manifests to hydration and SSR.
+Manual tables can be imported directly instead.
+
+See the [virtual routes guide](https://kasperrt.github.io/smolter/react/docs/virtual-routes)
+for the exact contract, TypeScript declaration, and both entrypoint examples.
+
+### Express hosting
+
+Keep Express in control of metrics, tracing, authentication and static files.
+Mount `createRequestHandler({ build, entry })` from
+`@kasperrt/smolter/utils/http` after those middleware. `build` is the compiled
+server entry and `entry` is the browser entry URL from Vite's manifest. Do not
+consume request bodies with Express body parsers before this handler.
+The adapter has no Express dependency and forwards failures to `next(error)`.
+
+See the [Express guide](https://kasperrt.github.io/smolter/react/docs/express)
+for a complete server example and current buffering limitations.
+
+## Resource subscriptions
+
+`@kasperrt/smolter/react/data` adds subscriptions to named resources when their
+lifetime is independent of URL navigation. The state and cancellation logic
+lives in core; the entry adds React bindings without DOM or HTTP globals.
+
+```ts
+import { createResourceRouter } from "@kasperrt/smolter/react/data";
+
+const resources = createResourceRouter(new Map([
+  ["settings", {
+    loader: async ({ signal }) => ({
+      data: await readSettings(signal),
+      error: "",
+    }),
+    action: async ({ input, signal }) => ({
+      data: await saveSettings(input, signal),
+      error: "",
+    }),
+  }],
+]));
+```
+
+`ResourceProvider` owns the store lifetime. `Resource` selects a resource by
+`routeId` and params. `useResourceData` reads it; `useRouteLoaderData` reads a
+named resource. `useResourceFetcher` returns `[state, operations]`, with
+independent `load` and `submit` operations. Successful mutations consult the
+resource's `shouldRevalidate` before reloading its data. Last-subscriber cleanup
+aborts pending work; `persistent` keeps a resource until explicitly disposed.
+This optional entry does not contribute to the base React bundle measurement.
+
 ## Size and checks
 
-`pnpm size` measures every browser export with esbuild, Terser, and gzip level 9.
-Frameworks are excluded; library dependencies are included. It compares the same
-build settings against pinned wouter entries. Both adapters must be strictly
-smaller than their corresponding wouter entry; exceeding either fails the check. Optional server transport is measured separately and included in SSR
-example labels. File discovery is build-only.
+| Need | Public import |
+| --- | --- |
+| Navigation only | `@kasperrt/smolter/react` or `/preact`, using `createRouter` |
+| Loaders, actions, forms and fetchers | Same entry, using `createDataRouter` |
+| Browser server-request transport | Renderer `/client` subpath |
+| Preact application hydration | `@kasperrt/smolter/preact/client` |
+| Preact document components | `@kasperrt/smolter/preact/document` |
+| Lazy Preact route modules | `@kasperrt/smolter/preact/lazy-route` |
+| Optional React resources | `@kasperrt/smolter/react/data` |
+| Server rendering / Vite integration | Renderer `/server` / `/vite` subpaths; keep out of browser imports |
+
+The measurements below describe retained exports, not the cost of an import
+statement. Browser transport rows include the router and transport together;
+application rows include the listed modules together. Server and Vite modules
+have no browser cost when kept in their intended server/build entrypoints.
+
+Use `createRouter` for navigation only, or `createDataRouter` for loaders,
+actions, fetchers and revalidation. Both are named exports from
+`@kasperrt/smolter/preact` and `/react`. No extra package or plugin is required.
+The production bundler can remove the data engine when only `createRouter` is used.
+
+`pnpm size` regenerates this table and the site's size data using identical
+minifiers. The routing-only gate compares our selected exports with wouter's
+routing subset: `Router`, `Route`, `Switch`, `Link`, `useParams`, and `useLocation`.
+Both complete wouter entries are reported too. The APIs differ; this is not
+a claim of identical features.
 
 <!-- size-comparison:start -->
 | Browser exports | Gzip bytes |
 | --- | ---: |
-| `@kasperrt/smolter/react` | 2445 |
-| `@kasperrt/smolter/preact` | 2445 |
-| `@kasperrt/smolter/react + @kasperrt/smolter/react/client` | 2782 |
-| `@kasperrt/smolter/preact + @kasperrt/smolter/preact/client` | 2781 |
+| `React Router: declarative routing subset` | 12882 |
+| `React Router: data routing subset` | 29780 |
+| `React: routing-only named exports` | 1245 |
+| `Preact: routing-only named exports` | 1405 |
+| `@kasperrt/smolter/react` | 2873 |
+| `@kasperrt/smolter/preact` | 4748 |
+| `@kasperrt/smolter/react + @kasperrt/smolter/react/client` | 3870 |
+| `@kasperrt/smolter/preact + server transport` | 5697 |
+| `@kasperrt/smolter/preact + client + document (application without lazy routes)` | 8033 |
+| `@kasperrt/smolter/preact + client + document + lazy-route (file-routed application)` | 8317 |
+| `@kasperrt/smolter/react/data (optional resource API)` | 2962 |
+| `React: common routing/data exports` | 2683 |
+| `Preact: common routing/data exports` | 2966 |
+| `wouter: routing subset (Router, Route, Switch, Link, useParams, useLocation)` | 2854 |
+| `wouter-preact: same routing subset` | 2211 |
 | `wouter@3.13.0` | 3091 |
 | `wouter-preact@3.13.0` | 2450 |
 | `react-router@8.4.0` | 60994 |
 <!-- size-comparison:end -->
 
-The table is generated by `pnpm size` from all exports of each listed entry,
+The common-export rows measure the same named API set: `createDataRouter`,
+`defineRoute`, `RouterProvider`, `Routes`, `Link`, `Form`, `useRouter`,
+`useLoaderData`, `useActionData`, `useParams`, `useLocation`,
+`useRevalidator` and `useFetcher`. Preact’s link and submission APIs currently
+have additional behavior; equal names do not imply identical implementations.
+React Router's declarative subset retains `BrowserRouter`, `Routes`, `Route`,
+`Link`, `useParams`, and `useLocation`. Its data subset retains
+`createBrowserRouter`, `RouterProvider`, `Link`, `Form`, `useLoaderData`,
+`useActionData`, `useParams`, `useLocation`, `useRevalidator`, and `useFetcher`.
+React Router has no dedicated Preact entry; these are React API measurements,
+not a Preact compatibility build. The selected APIs have different capabilities.
+
+The routing-only rows retain `createRouter`, `defineRoute`, `RouterProvider`,
+`Routes`, `Link`, `useParams` and `useLocation`. Full Preact also exposes richer
+application APIs. These tiers overlap: do not add the rows together.
+
+The table is generated by `pnpm size` from the named subsets above or all exports of each other listed entry,
 using production ESM bundles, esbuild, Terser, and gzip level 9. React, React DOM,
 and Preact are external in every bundle. Transitive library dependencies are
 included. React Router provides a broader API; this compares complete entry
@@ -461,6 +643,43 @@ sizes, not equivalent feature sets or the minimum code for one route.
 `@kasperrt/smolter/react/client` adds browser transport for server loaders/actions; server-only
 rendering code and the Vite plugin are not shipped to the browser.
 
+### Routing without data hooks
+
+```tsx
+import { render } from "preact";
+import {
+  createRouter,
+  defineRoute,
+  Link,
+  RouterProvider,
+  Routes,
+} from "@kasperrt/smolter/preact";
+import Home from "./routes/home";
+import About from "./routes/about";
+
+const router = createRouter([
+  defineRoute("/", { default: Home }),
+  defineRoute("/about", { default: About }),
+], { browser: true });
+
+render(
+  <RouterProvider router={router}>
+    <nav>
+      <Link href="/">Home</Link>
+      <Link href="/about">About</Link>
+    </nav>
+    <Routes />
+  </RouterProvider>,
+  document.getElementById("app")!,
+);
+```
+
+Add `useParams` for dynamic paths such as `/tasks/:id` and `useLocation` for
+the current URL. Both are included in the routing-only measurement, even though
+this example does not need them. Switch the factory to `createDataRouter` when
+adding loaders, actions or fetchers, importing it from the same entry. SSR hydration and file-routed applications use the
+larger client/document/lazy-route tier; they are not represented by the routing-only number.
+
 Exact current measurements are generated in
 [`packages/ui/src/size.json`](./packages/ui/src/size.json).
 
@@ -486,8 +705,31 @@ PRs. [Release workflow](https://github.com/kasperrt/smolter/blob/main/RELEASING.
 To test a local package build in another project:
 
 ```sh
-pnpm --dir packages/smolter pack --pack-destination ../..
+pnpm pack
 pnpm add /absolute/path/to/kasperrt-smolter-0.0.1.tgz
 ```
 
 Workspace structure and rendering checks are documented in [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## Deployment updates
+
+For production tabs that survive a deployment, add `deploymentPlugin()` from
+`@kasperrt/smolter/react/vite` or `/preact/vite`, then connect the router:
+
+```ts
+import deployment from "virtual:smolter/deployment";
+import { watchDeployment } from "@kasperrt/smolter/preact/client";
+
+watchDeployment(router, deployment);
+```
+
+Serve the emitted `smolter-manifest.json` with `Cache-Control: no-store` and HTML
+with `no-cache`. Navigation checks its build version before loading another route;
+a newer version reloads the destination, including its query and hash. Vite chunk
+failures are checked again. Hash-only links skip the check, failed checks continue
+normally, and a session marker prevents reload loops. Development/SSR builds
+disable the helper. This optional client module adds nothing to the routing-only
+entrypoints and never replays form submissions.
+
+See [deployment updates](https://kasperrt.github.io/smolter/react/docs/deployments/)
+for Express, CDN paths, TypeScript declarations and unsaved-state handling.

package/dist/client/deployment.d.ts

@@ -0,0 +1,12 @@
+import type { NavigationRouter } from "../core/index.ts";
+/** Build identity and the fresh, non-cacheable manifest URL emitted by deploymentPlugin. */
+export interface DeploymentOptions {
+    version: string;
+    manifestURL: string;
+    /** Maximum time to wait for the update check before continuing navigation. */
+    timeout?: number;
+    /** Override document navigation, for example to ask about unsaved changes. */
+    reload?: (destination: URL) => void;
+}
+/** Check for deployment changes before navigation. Returns a cleanup function. */
+export declare function watchDeployment(router: NavigationRouter, options: DeploymentOptions | null): () => void;

package/dist/client/deployment.js

@@ -0,0 +1,102 @@
+//#region .generated/client/deployment.ts
+/** Check for deployment changes before navigation. Returns a cleanup function. */
+function watchDeployment(router, options) {
+	if (!options || typeof window === "undefined") return () => {};
+	const { version, manifestURL, timeout = 2e3 } = options;
+	const navigate = router.navigate;
+	const dispose = router.dispose;
+	const manifest = new URL(manifestURL, location.href);
+	const key = `smolter:deployment:${manifest.href}:${version}`;
+	let sequence = 0;
+	let stopped = false;
+	let replay = false;
+	let destination = new URL(location.href);
+	let pending;
+	let controller;
+	function changed() {
+		if (pending) return pending;
+		controller = new AbortController();
+		const timer = setTimeout(() => controller?.abort(), timeout);
+		pending = fetch(manifest, {
+			cache: "no-store",
+			signal: controller.signal
+		}).then(async (response) => {
+			if (!response.ok) return false;
+			const data = await response.json();
+			return typeof data === "object" && data !== null && "version" in data && typeof data.version === "string" && data.version.length > 0 && data.version !== version;
+		}).catch(() => false).finally(() => {
+			clearTimeout(timer);
+			pending = void 0;
+		});
+		return pending;
+	}
+	async function reload(target) {
+		const allowed = await Promise.resolve().then(() => {
+			if (sessionStorage.getItem(key)) return false;
+			sessionStorage.setItem(key, "1");
+			return true;
+		}).catch(() => false);
+		if (allowed && !stopped) {
+			if (options?.reload) options.reload(target);
+			if (!options?.reload) {
+				if (target.href === location.href) location.reload();
+				if (target.href !== location.href) location.assign(target.href);
+			}
+		}
+		return allowed && !stopped;
+	}
+	const guarded = async (href, operation) => {
+		const target = new URL(href, router.getSnapshot().url);
+		const currentURL = new URL(router.getSnapshot().url);
+		const current = ++sequence;
+		destination = target;
+		if (target.origin === location.origin && (target.pathname !== currentURL.pathname || target.search !== currentURL.search) && await changed()) {
+			if (current !== sequence || stopped || await reload(target)) return;
+		}
+		if (current === sequence && !stopped) await navigate(href, operation);
+	};
+	const pop = (event) => {
+		if (replay) return;
+		const target = new URL(location.href);
+		const previous = new URL(router.getSnapshot().url);
+		if (target.pathname === previous.pathname && target.search === previous.search) return;
+		event.stopImmediatePropagation();
+		const current = ++sequence;
+		destination = target;
+		changed().then(async (updated) => {
+			if (stopped || current !== sequence) return;
+			if (updated && await reload(target)) return;
+			replay = true;
+			window.dispatchEvent(new PopStateEvent("popstate", { state: event.state }));
+			replay = false;
+		});
+	};
+	const preloadError = () => {
+		if (router.getSnapshot().state === "submitting") return;
+		const current = sequence;
+		const target = destination;
+		changed().then((updated) => {
+			if (updated && current === sequence && !stopped) return reload(target);
+		});
+	};
+	function cleanup() {
+		stopped = true;
+		sequence++;
+		controller?.abort();
+		window.removeEventListener("popstate", pop, true);
+		window.removeEventListener("vite:preloadError", preloadError);
+		if (router.navigate === guarded) router.navigate = navigate;
+		if (router.dispose === guardedDispose) router.dispose = dispose;
+	}
+	function guardedDispose() {
+		cleanup();
+		dispose();
+	}
+	router.navigate = guarded;
+	router.dispose = guardedDispose;
+	window.addEventListener("popstate", pop, true);
+	window.addEventListener("vite:preloadError", preloadError);
+	return cleanup;
+}
+//#endregion
+export { watchDeployment };

package/dist/client/deserialize.js

@@ -0,0 +1,10 @@
+//#region .generated/client/deserialize.ts
+/** Restore a trusted snapshot produced by @kasperrt/smolter/server serialize, including its route error. */
+function deserialize(json) {
+	const snapshot = JSON.parse(json);
+	const error = snapshot.error;
+	if (error) snapshot.error = Object.assign(new Error(error.message), { name: error.name });
+	return snapshot;
+}
+//#endregion
+export { deserialize };

package/dist/{internal/client → client}/index.d.ts

@@ -7,6 +7,7 @@ export type { ClientActionArgs, ClientLoaderArgs } from "../core/index.ts";
 export { deserialize } from "./deserialize.ts";
 /** Browser-safe route exports, excluding server implementation code. */
 export interface ClientRouteModule {
+    id?: string;
     default?: unknown;
     HydrateFallback?: unknown;
     ErrorBoundary?: unknown;
@@ -21,3 +22,4 @@ export interface ServerHandlers {
 }
 /** Browser transport for server routes. File-router builds generate this call. */
 export declare function serverRoute<M extends RouteModule = RouteModule>(path: string, module: ClientRouteModule, handlers?: ServerHandlers): Route<M>;
+export { type DeploymentOptions, watchDeployment } from "./deployment.ts";

package/dist/client/index.js

@@ -0,0 +1,47 @@
+import { deserialize } from "./deserialize.js";
+import { watchDeployment } from "./deployment.js";
+//#region .generated/client/index.ts
+/** Browser transport for server routes. File-router builds generate this call. */
+function serverRoute(path, module, handlers = {
+	loader: true,
+	action: true
+}) {
+	const remote = async ({ request, signal }) => {
+		const url = new URL(request.url);
+		const response = await fetch(`/_smolter?url=${encodeURIComponent(url.pathname + url.search)}`, {
+			method: request.method,
+			signal,
+			...request.method !== "GET" && { body: await request.formData() }
+		});
+		const location = response.headers.get("X-Smolter-Redirect");
+		if (location) return new Response(null, {
+			status: 303,
+			headers: { Location: location }
+		});
+		const data = await response.json();
+		if (!response.ok) return new Error(data.error ?? "Route request failed");
+		return data;
+	};
+	return {
+		...module,
+		path,
+		...handlers.loader && { loader: remote },
+		...handlers.action && { action: remote },
+		...module.clientLoader && { clientLoader: (args) => module.clientLoader({
+			...args,
+			serverLoader: () => remote(args)
+		}) },
+		...module.clientAction && { clientAction: (args) => {
+			const request = args.request.clone();
+			return module.clientAction({
+				...args,
+				serverAction: () => remote({
+					...args,
+					request: request.clone()
+				})
+			});
+		} }
+	};
+}
+//#endregion
+export { deserialize, serverRoute, watchDeployment };