@pitlane/dev 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,67 @@
 # @pitlane/dev
 
+## 0.4.0
+
+SPA mode.
+
+- `remix({ server: false })` targets client-rendered apps. No server
+  environment is configured, nothing builds to `dist/ssr`, and `vite build`
+  emits a static site from `index.html`. What remains is the part a SPA still
+  wants: component HMR through the `remix/ui-hmr` browser transform, including
+  the arrow-form normalization, so edits hot-swap in place and keep live
+  component state. Every `server*` option goes with it, and `clientEntry` too,
+  and `<HMR />` from `pitlane:dev` resolves to the inert component — there is
+  no server data to revalidate.
+- The option is named for what it removes. React Router spells the same switch
+  `ssr: false`, which reads like it only turns off server rendering; it does
+  not, in either plugin. An app that wants browser-rendered UI in front of
+  routes that still run per request keeps `server: true` and writes a server
+  entry that answers data and a shell.
+- SPA mode works under Vite's experimental bundled dev mode
+  (`experimental.bundledDev` / `vite dev --experimentalBundle`), component
+  hot-swap included. Server-rendered apps do not: bundled dev serves only
+  bundle entrypoints, so the client module URLs an SSR render writes into its
+  HTML have nothing behind them. That is upstream's Phase 4 (server
+  environments), still a prototype.
+
+## 0.3.0
+
+Dev-time hot module replacement.
+
+- Component HMR: component and `clientEntry()` exports hot-swap in place
+  during `vite dev`, preserving live island state, via the `remix/ui-hmr`
+  browser and server transforms. Both named-function and arrow forms work —
+  arrow-form component/`clientEntry()` exports are normalized to named
+  function expressions before instrumentation, so idiomatic Remix code
+  hot-swaps with no source changes.
+- Server-data HMR: editing a server-only module re-fetches the current page
+  through the app's fetch handler and reconciles the new server-rendered HTML
+  into the DOM, keeping hydrated island state — the Remix 3 analog of React
+  Router's loader/action revalidation, driven through the frame runtime. A
+  changed file the client graph serves as a script is left to component HMR
+  instead. Only `js` client modules count as client-served: plugins that scan
+  sources for their own purposes register non-script nodes for ordinary server
+  files (Tailwind's content scanner, for one), which previously classified
+  every server module as client-owned and silenced server-data HMR for the
+  whole app.
+- Revalidating is one line in the document, `<HMR />` from the new `pitlane:dev`
+  module. It is a hydrated island, so it holds a component handle and
+  revalidates with `handle.frames.top.reload()`; `remix/ui` hands the top frame
+  to components only, so nothing the plugin injects could reach it. A frame
+  reload produces no history entry and fires no `navigate` event, which leaves
+  apps that intercept navigation themselves working unchanged. Needs no
+  environment guard: in a build, and in apps with no client runtime to hydrate
+  it, the specifier resolves to a component that renders nothing and carries no
+  client code. Types come with `@pitlane/dev/assets`.
+- Revalidation waits a beat after a server change before refetching, so it
+  cannot reach the fetch handler while the server entry is still half-applied
+  (which served a dev error page on slower runtimes like workerd), and a burst
+  of saves coalesces into one refetch.
+- `@pitlane/dev/runtime` imports now inline this package's real runtime module
+  rather than a hand-written copy of `mergeAssets`, so every export stays in
+  one place. What that module imports is bundled too, which keeps the built
+  server free of any dev-dependency import.
+
 ## 0.2.0
 
 Target Remix `3.0.0-beta.10`.

package/README.md

@@ -70,13 +70,51 @@ run({
 
 `vite dev` serves the app through your router. `vite build` produces `dist/ssr` and `dist/client`. `vite preview` serves the production build through the same fetch handler production runs.
 
-> [!NOTE]
-> Dev updates are coarse-grained today: the server entry is re-imported per request, and client edits trigger a page refresh. Remix UI's first-class HMR runtime is in progress upstream ([remix-run/remix#11515](https://github.com/remix-run/remix/pull/11515)) — we're tracking it, and `@pitlane/dev` will ship the companion transform once it lands so components hot-swap in place.
+## Hot module replacement
+
+`vite dev` hot-updates both halves of a Remix app in place, keeping live client state. Full details, including which edits preserve state and which remount, are in the [HMR guide](https://pitlane.tools/guides/hmr).
+
+**Components.** Editing a component swaps its new code in without remounting, so hydrated `clientEntry()` islands keep their state (open menus, form input, counters). This runs the [`remix/ui-hmr`](https://github.com/remix-run/remix/tree/main/packages/ui-hmr) transforms during dev. Both authoring styles hot-swap, because `@pitlane/dev` normalizes arrow-form component and `clientEntry()` exports to named functions before instrumenting them:
+
+```tsx
+// All of these hot-swap in place, preserving live state:
+export const Counter = clientEntry(import.meta.url, handle => {
+    /* ... */
+});
+export const Toggle = clientEntry(import.meta.url, function Toggle(handle) {
+    /* ... */
+});
+export const Card = handle => () => <div />;
+export function Panel(handle) {
+    /* ... */
+}
+```
+
+Only named (PascalCase) component exports in `.tsx`/`.jsx` files whose setup returns a render function are instrumented; other exports are left untouched. Editing the render function keeps live state. Editing the setup scope above the `return` remounts the component, so its state resets.
+
+**Server data.** Editing a server-only module (the document, a middleware, a route handler, any module the client never imports) re-fetches the current page through your fetch handler and reconciles the new server-rendered HTML into the DOM. Hydrated island state survives, so you see fresh server output without a full-page reload. This is the Remix 3 analog of React Router's loader/action revalidation, driven through the frame runtime rather than a client data router.
+
+It needs one line in your document:
+
+```tsx
+import { HMR } from "pitlane:dev";
+
+// ...
+<body>
+    <HMR />
+    {/* ... */}
+</body>;
+```
+
+`<HMR />` is a hydrated island, so it has a component handle, and it revalidates with `handle.frames.top.reload()`. Remix hands the top frame to components only, which is why this is a component rather than something the plugin injects. Reloading the frame produces no history entry and fires no `navigate` event, so apps that intercept navigation themselves work unchanged.
+
+Leave it unguarded: in a production build the specifier resolves to a component that renders nothing and carries no client code. Apps with `clientEntry: false` have nothing to hydrate it, so it stays inert there too. See the [HMR guide](https://pitlane.tools/guides/hmr).
 
 ## Options
 
 ```ts
 remix({
+    server: true, // default — false selects SPA mode
     clientEntry: "app/entry.browser", // default — false disables the client build
     serverEntry: "app/entry.server", // default
     serverEnvironments: ["ssr"], // default
@@ -86,11 +124,57 @@ remix({
 
 | Option               | Type              | Default               | Purpose                                                                                                                                                           |
 | -------------------- | ----------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `server`             | `boolean`         | `true`                | Whether the app has a server. Pass `false` for [SPA mode](#spa-mode), which ignores every option below.                                                           |
 | `clientEntry`        | `string \| false` | `"app/entry.browser"` | Client entry module. Pass `false` for fully server-rendered apps with no hydration.                                                                               |
 | `serverEntry`        | `string`          | `"app/entry.server"`  | Server entry module, built as `dist/ssr/index.js`.                                                                                                                |
 | `serverEnvironments` | `string[]`        | `["ssr"]`             | Environment names the `clientEntry()` transform treats as "server".                                                                                               |
 | `serverHandler`      | `boolean`         | `true`                | Serve dev requests through your server entry. Set `false` when `@cloudflare/vite-plugin`, `@netlify/vite-plugin`, or `nitro/vite` owns dev-time request handling. |
 
+## SPA mode
+
+Some apps have no server — a static host, a router that never touches one.
+`remix({ server: false })` targets those. React Router spells the same switch
+`ssr: false`:
+
+```ts
+// vite.config.ts
+import { remix } from "@pitlane/dev";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+    plugins: [remix({ server: false })],
+});
+```
+
+There is no server environment, nothing is built to `dist/ssr`, and
+`vite build` emits a static site from your `index.html`. The plugin's one
+remaining job is the one a SPA still wants: component HMR. Editing a component
+swaps it in place and keeps live state, arrow forms included.
+
+Every `server*` option goes with it, and `clientEntry` too — the browser entry
+is whatever `index.html` loads. `<HMR />` from `pitlane:dev` resolves to the
+inert component, because there is no server data to revalidate.
+
+Deploying means pointing every unknown URL at `index.html` so the client router
+can resolve it; on GitHub Pages that is a copy of `index.html` at `404.html`,
+on Netlify a `/* /index.html 200` redirect.
+
+The option removes the server, not the server rendering, which is what React
+Router's `ssr: false` does too. For a browser-rendered UI in front of routes
+that still run per request, stay in the default mode and let the server entry
+answer JSON on its data routes and one `remix/ui` shell on its document
+routes: nothing here asks it to render app UI. [Client rendering with a
+server](https://pitlane.tools/guides/spa#client-rendering-with-a-server) shows
+the shape.
+
+SPA mode also works under Vite's experimental bundled dev mode
+(`experimental.bundledDev`, or `vite dev --experimentalBundle`), component
+hot-swap included. Server-rendered apps do not yet: bundled dev serves only
+bundle entrypoints, so the client module URLs an SSR render writes into its
+HTML resolve to nothing. That is upstream's
+[Phase 4](https://github.com/vitejs/vite/discussions/22746) — server
+environments — still a prototype.
+
 ## The server entry contract
 
 The server entry **default-exports a fetch handler** — an object exposing `fetch(request: Request): Response | Promise<Response>`. A `createRouter()` router already is one:

package/dist/assets.d.mts

@@ -1,7 +1,8 @@
 /**
- * Type declarations for Pitlane's `?assets=` import convention.
+ * Type declarations for Pitlane's `?assets=` import convention and the
+ * `pitlane:dev` module.
  *
- * Add to an app's tsconfig to type `?assets=` imports:
+ * Add to an app's tsconfig to type both:
  *
  * ```jsonc
  * { "compilerOptions": { "types": ["@pitlane/dev/assets"] } }
@@ -26,3 +27,20 @@ declare module "*?assets=ssr" {
     const assets: import("@pitlane/dev/runtime").ImportedAssets;
     export default assets;
 }
+
+declare module "pitlane:dev" {
+    /**
+     * Revalidates the page when a server-only module changes during `vite dev`,
+     * keeping hydrated island state. Render it once, anywhere in the document:
+     *
+     * ```tsx
+     * import { HMR } from "pitlane:dev";
+     * // ...
+     * <HMR />
+     * ```
+     *
+     * Renders nothing, and carries no client code in a production build, so it
+     * needs no environment guard.
+     */
+    export const HMR: () => () => null;
+}

package/dist/index.d.mts

@@ -9,6 +9,21 @@ interface RemixPluginOptions {
    * @default "app/entry.browser"
    */
   clientEntry?: string | false;
+  /**
+   * Whether the app has a server at all. Pass `false` for SPA mode: no
+   * server environment is configured, nothing is built to `dist/ssr`, and
+   * `vite build` emits a static site from `index.html`.
+   *
+   * This is about the server, not about server rendering. With `false`
+   * every `server*` option below goes with it, because there is no server
+   * for them to describe, and `clientEntry` goes too: the browser entry is
+   * whatever `index.html` loads. An app that wants its UI rendered in the
+   * browser while its routes still answer per request keeps `true` and
+   * writes a server entry that serves data and a shell.
+   *
+   * @default true
+   */
+  server?: boolean;
   /**
    * Server entry module, built as `dist/ssr/index.js`. Must default-export
    * a fetch handler: an object exposing
@@ -31,6 +46,8 @@ interface RemixPluginOptions {
    * Set to `false` when another plugin owns dev-time request handling —
    * e.g. `@cloudflare/vite-plugin`, `@netlify/vite-plugin`, or `nitro/vite`.
    *
+   * Ignored when `server` is `false`, which has no fetch handler.
+   *
    * @default true
    */
   serverHandler?: boolean;
@@ -41,6 +58,13 @@ interface RemixPluginOptions {
  * `clientEntry(import.meta.url, …)` hydration transform, dev serving through
  * the app's fetch handler, and a preview server for the production build.
  *
+ * During `vite dev` it also installs hot module replacement: component edits
+ * swap in place through the `remix/ui-hmr` transforms, and edits to modules the
+ * browser never loads refetch the current page through the app's fetch handler,
+ * keeping hydrated island state. Both are dev-only. The second half needs the
+ * app to render `<HMR />` from the `pitlane:dev` module, which resolves to an
+ * inert component in a build and when `clientEntry` is `false`.
+ *
  * Platform-agnostic by design: deploy targets compose alongside it in the
  * plugin array (`@cloudflare/vite-plugin`, `@netlify/vite-plugin`,
  * `nitro/vite`), or the built fetch handler runs directly on Node, Bun, and

package/dist/index.mjs

@@ -1,9 +1,10 @@
-import { mergeAssets } from "./runtime.mjs";
 import fullstack from "@hiogawa/vite-plugin-fullstack";
 import * as fs from "node:fs";
 import * as path from "node:path";
+import * as url from "node:url";
 import MagicString from "magic-string";
 import { parseSync } from "oxc-parser";
+import { transformComponentsForBrowser, transformComponentsForServer } from "remix/ui-hmr";
 //#region src/build.ts
 function isFullstackBuilder(builder) {
 	return "writeAssetsManifest" in builder && typeof builder.writeAssetsManifest === "function";
@@ -189,7 +190,7 @@ function build({ clientEntry, serverEntry }) {
 						rollupOptions: { input: hasUserClientInput ? void 0 : clientEntry || void 0 }
 					} } },
 					ssr: {
-						resolve: { noExternal: [/^@pitlane\/dev(\/|$)/] },
+						resolve: { noExternal: [/^@pitlane\/dev(\/|$)/, /^@hiogawa\/vite-plugin-fullstack(\/|$)/] },
 						build: {
 							outDir: "dist/ssr",
 							rollupOptions: { input: hasUserServerInput ? void 0 : { index: serverEntry } }
@@ -208,6 +209,11 @@ const RUNTIME_MODULE_FILTER = new RegExp(`^${RUNTIME_MODULE_ID}$`);
 * import it at runtime (pruned containers, Deno import maps, serverless
 * bundles), and dependency-externalization behavior varies across cores and
 * orchestrators — inlining by construction removes the variable.
+*
+* The virtual module re-exports this package's own runtime file by absolute
+* path, so the bundler inlines it and every export stays in one place. Emitting
+* hand-written source here instead would drift from the real module the moment
+* it gained an export.
 */
 function runtimeInline() {
 	return {
@@ -222,11 +228,296 @@ function runtimeInline() {
 		load: {
 			filter: { id: RUNTIME_MODULE_FILTER },
 			handler(id) {
-				if (id === RUNTIME_MODULE_ID) return `export const mergeAssets = ${mergeAssets.toString()};\n`;
+				if (id === RUNTIME_MODULE_ID) return `export * from ${JSON.stringify(runtimeImplementationPath())};\n`;
 			}
 		}
 	};
 }
+/**
+* Absolute path to this package's runtime module. Sits beside the built plugin
+* as `runtime.mjs` in an installed package, and beside the source as
+* `runtime.ts` when the repo's own fixtures load the plugin from `src`.
+*/
+function runtimeImplementationPath() {
+	let here = path.dirname(url.fileURLToPath(import.meta.url));
+	for (let name of ["runtime.mjs", "runtime.ts"]) {
+		let candidate = path.join(here, name);
+		if (fs.existsSync(candidate)) return candidate;
+	}
+	throw new Error(`@pitlane/dev: runtime module not found next to ${here}`);
+}
+//#endregion
+//#region src/hmr-protocol.ts
+/**
+* The dev-only contract between the `serverDataHmr` plugin and the island that
+* revalidates. Shared so the two cannot drift apart.
+*/
+/** Custom Vite HMR event that asks the browser to revalidate server-rendered data. */
+const SERVER_UPDATE_EVENT = "pitlane:server-update";
+//#endregion
+//#region src/hmr-component.ts
+/** Public specifier apps import the dev HMR component from. */
+const PUBLIC_ID = "pitlane:dev";
+const ISLAND_ID = `\0${PUBLIC_ID}`;
+const INERT_ID = `\0${PUBLIC_ID}?inert`;
+/**
+* The `clientEntry()` transform asks a module for its own client URL through
+* `?assets=client` on its resolved id. This module answers for itself.
+*/
+const ISLAND_ASSETS_ID = `${ISLAND_ID}?assets=client`;
+const RESOLVED_ISLAND_ASSETS_ID = `\0${PUBLIC_ID}?island-assets`;
+/**
+* Serves the `<HMR />` component apps render in their document, which drives
+* server-data revalidation.
+*
+* The specifier is an indirection the plugin repoints by mode. During `vite dev`
+* it is a hydrated island whose handle reaches the top frame. In a build, and in
+* apps with no client runtime to hydrate it, it is a component that renders
+* nothing, so `<HMR />` can stay in the document unconditionally and cost
+* nothing in production.
+*
+* Kept virtual rather than shipped as a file on disk: a file inside the package
+* resolves outside the app's root, and the dev server hands out a `file://` URL
+* for those, which a browser refuses to import.
+*/
+function hmrComponent(clientEntry) {
+	return {
+		name: "pitlane-remix-hmr-component",
+		enforce: "pre",
+		resolveId(id) {
+			if (id === ISLAND_ASSETS_ID) return RESOLVED_ISLAND_ASSETS_ID;
+			if (id !== PUBLIC_ID) return;
+			if (this.environment.mode === "build" || clientEntry === false) return INERT_ID;
+			return ISLAND_ID;
+		},
+		load(id) {
+			if (id === INERT_ID) return INERT_SOURCE;
+			if (id === ISLAND_ID) return ISLAND_SOURCE;
+			if (id === RESOLVED_ISLAND_ASSETS_ID) return islandAssetsSource(this.environment.config.base);
+		}
+	};
+}
+/** A component that renders nothing and carries no client code. */
+const INERT_SOURCE = `export const HMR = () => () => null;\n`;
+/**
+* The island. Revalidates by reloading its top frame, which refetches the page
+* through the app's fetch handler and reconciles it, with no navigation
+* involved. Overlapping revalidations collapse into one follow-up.
+*
+* Renders nothing: it contributes markup only as the hydration marker Remix
+* emits around it, which is what gives it a handle in the browser.
+*/
+const ISLAND_SOURCE = `import { clientEntry } from "remix/ui";
+
+export const HMR = clientEntry(import.meta.url, function HMR(handle) {
+    if (import.meta.hot) {
+        let inFlight = false;
+        let queued = false;
+
+        let revalidate = async () => {
+            if (inFlight) {
+                queued = true;
+                return;
+            }
+            inFlight = true;
+            try {
+                await handle.frames.top.reload();
+            } finally {
+                inFlight = false;
+            }
+            if (queued) {
+                queued = false;
+                await revalidate();
+            }
+        };
+
+        import.meta.hot.on(${JSON.stringify(SERVER_UPDATE_EVENT)}, () => void revalidate());
+    }
+
+    return () => null;
+});
+`;
+/**
+* The island's own `?assets=client` answer: the dev-server URL for a virtual
+* module, which is what the server writes into the hydration marker for the
+* browser to import.
+*/
+function islandAssetsSource(base) {
+	let url = `${base.endsWith("/") ? base : `${base}/`}@id/__x00__${PUBLIC_ID}`;
+	return `export default { entry: ${JSON.stringify(url)}, js: [], css: [] };\n`;
+}
+//#endregion
+//#region src/hmr.ts
+/**
+* Component modules Remix authors as `.tsx`/`.jsx`. The `remix/ui-hmr` transform
+* self-guards (it returns the source unchanged when a module holds no
+* `function`-form component or `clientEntry`), so this filter only trims the
+* common non-candidates — non-JSX source, query variants like `?assets=`, and
+* dependencies — before the parse cost.
+*/
+const COMPONENT_ID_FILTER = /\.[jt]sx$/;
+/**
+* How long to wait after a server module changes before asking the browser to
+* revalidate. Vite applies the update to the server environment on its own
+* schedule; revalidating in the same tick can reach the fetch handler while the
+* server entry is still half-applied, which serves a dev error page instead of
+* the new content. The delay also coalesces bursts of saves into one refetch.
+*/
+const SERVER_UPDATE_SETTLE_MS = 50;
+/**
+* Instruments Remix UI components and `clientEntry()` exports with the
+* `remix/ui-hmr` transforms so component edits hot-swap in place while
+* preserving live component state.
+*
+* `ui-hmr` only recognizes named-function component forms, so arrow-form
+* exports (`export const Name = clientEntry(url, (handle) => …)` and
+* `export const Name = (handle) => …`) are first normalized to named function
+* expressions — the idiomatic Remix authoring style then hot-swaps without any
+* source changes. The normalization is discarded when `ui-hmr` does not
+* instrument the module, so non-component arrows are never rewritten.
+*
+* The browser transform runs in the client environment and the server transform
+* in the server environment(s); both emit the standard `import.meta.hot.accept()`
+* protocol that Vite's own HMR runtime drives.
+*
+* Dev-only: production builds never carry the wrapper indirection or the runtime
+* imports.
+*/
+function componentHmr(serverEnvironments) {
+	return {
+		name: "pitlane-remix-component-hmr",
+		apply: "serve",
+		transform: {
+			filter: { id: {
+				include: COMPONENT_ID_FILTER,
+				exclude: /\/node_modules\//
+			} },
+			handler(code, id) {
+				let source = normalizeArrowComponents(code, id) ?? code;
+				let result = serverEnvironments.has(this.environment.name) ? transformComponentsForServer(source, {
+					importSource: "remix",
+					moduleUrl: id,
+					sourceMap: true
+				}) : transformComponentsForBrowser(source, {
+					importSource: "remix",
+					moduleUrl: id,
+					sourceMap: true
+				});
+				if (!result.transformed) return;
+				return {
+					code: result.code,
+					map: result.map
+				};
+			}
+		}
+	};
+}
+/**
+* Server-data HMR, broadcast half: when a server-only module changes, tell the
+* browser to revalidate its server-rendered content. The `<HMR />` component
+* from the `pitlane:dev` module receives the event and reloads the top frame,
+* which refetches the page through the app's fetch handler and reconciles it,
+* keeping hydrated island state. This is the Remix 3 analog of React Router's
+* loader/action revalidation.
+*
+* A file counts as server-only when the client graph does not serve it as a
+* script; those are left to the client component-HMR boundary, so a
+* `function`-form component edit still hot-swaps instantly instead of triggering
+* a network reload. Only `js` client modules count: plugins that scan sources
+* for other reasons (Tailwind's content scanner, for one) register `asset` nodes
+* for ordinary server files, and treating those as client modules would silently
+* disable server-data HMR for the whole app.
+*
+* Dev-only. An app that never renders `<HMR />` simply has no listener, so the
+* event is inert.
+*/
+function serverDataHmr(serverEnvironments) {
+	let pending;
+	return {
+		name: "pitlane-remix-server-data-hmr",
+		apply: "serve",
+		hotUpdate({ file, server }) {
+			if (!serverEnvironments.has(this.environment.name)) return;
+			if (!/\.[jt]sx?$/.test(file)) return;
+			if ([...(server.environments.client?.moduleGraph)?.getModulesByFile(file) ?? []].some((module) => module.type === "js")) return;
+			clearTimeout(pending);
+			pending = setTimeout(() => {
+				pending = void 0;
+				server.hot.send({
+					type: "custom",
+					event: SERVER_UPDATE_EVENT
+				});
+			}, SERVER_UPDATE_SETTLE_MS);
+			pending.unref?.();
+		}
+	};
+}
+/**
+* Rewrites arrow-form component and `clientEntry()` exports to named function
+* expressions so `remix/ui-hmr` can instrument them. Returns the rewritten
+* source, or `undefined` when nothing qualified.
+*
+* Handles the two idiomatic Remix arrow forms:
+*
+* - `export const Name = clientEntry(url, (handle) => …)`
+* - `export const Name = (handle) => () => <jsx/>`
+*
+* Both become `export const Name = clientEntry(url, function Name(handle) { … })`
+* / `export const Name = function Name(handle) { … }`, which is behavior-
+* identical for component setup functions (they never rely on a lexical `this`
+* or `arguments`).
+*/
+function normalizeArrowComponents(code, id) {
+	if (!code.includes("=>")) return;
+	let program = parseSync(id, code).program;
+	let rewritten;
+	for (let node of program.body) {
+		if (node.type !== "ExportNamedDeclaration") continue;
+		if (node.declaration?.type !== "VariableDeclaration") continue;
+		for (let declarator of node.declaration.declarations) {
+			if (declarator.id.type !== "Identifier") continue;
+			if (!isPascalCase(declarator.id.name)) continue;
+			if (!declarator.init) continue;
+			let arrow = getNormalizableArrow(declarator.init);
+			if (!arrow) continue;
+			rewritten ??= new MagicString(code);
+			let params = getParamsSource(code, arrow);
+			let bodySource = code.slice(arrow.body.start, arrow.body.end);
+			let block = arrow.body.type === "BlockStatement" ? bodySource : `{ return ${bodySource} }`;
+			let asyncPrefix = arrow.async ? "async " : "";
+			rewritten.overwrite(arrow.start, arrow.end, `${asyncPrefix}function ${declarator.id.name}${params} ${block}`);
+		}
+	}
+	return rewritten?.toString();
+}
+/**
+* Returns the arrow function to normalize for a component export initializer:
+* the setup argument of a `clientEntry()` call, or a bare arrow component whose
+* body returns a render function. Anything else yields `undefined`.
+*/
+function getNormalizableArrow(init) {
+	if (init.type === "CallExpression" && init.callee.type === "Identifier" && init.callee.name === "clientEntry") {
+		let setup = init.arguments[1];
+		return setup?.type === "ArrowFunctionExpression" ? setup : void 0;
+	}
+	if (init.type === "ArrowFunctionExpression" && returnsRenderFunction(init)) return init;
+}
+/** A Remix component setup returns a render function; that is the HMR signal. */
+function returnsRenderFunction(arrow) {
+	let body = arrow.body;
+	if (body.type === "ArrowFunctionExpression" || body.type === "FunctionExpression") return true;
+	if (body.type === "BlockStatement") return body.body.some((statement) => statement.type === "ReturnStatement" && (statement.argument?.type === "ArrowFunctionExpression" || statement.argument?.type === "FunctionExpression"));
+	return false;
+}
+/** Source of the arrow's parameter list, always parenthesized. */
+function getParamsSource(code, arrow) {
+	let params = arrow.params;
+	if (params.length === 0) return "()";
+	return `(${code.slice(params[0].start, params[params.length - 1].end)})`;
+}
+function isPascalCase(name) {
+	return /^[A-Z]/.test(name);
+}
 //#endregion
 //#region src/preview.ts
 function isFetchHandler(value) {
@@ -345,13 +636,22 @@ function findClientEntryCalls(program) {
 * `clientEntry(import.meta.url, …)` hydration transform, dev serving through
 * the app's fetch handler, and a preview server for the production build.
 *
+* During `vite dev` it also installs hot module replacement: component edits
+* swap in place through the `remix/ui-hmr` transforms, and edits to modules the
+* browser never loads refetch the current page through the app's fetch handler,
+* keeping hydrated island state. Both are dev-only. The second half needs the
+* app to render `<HMR />` from the `pitlane:dev` module, which resolves to an
+* inert component in a build and when `clientEntry` is `false`.
+*
 * Platform-agnostic by design: deploy targets compose alongside it in the
 * plugin array (`@cloudflare/vite-plugin`, `@netlify/vite-plugin`,
 * `nitro/vite`), or the built fetch handler runs directly on Node, Bun, and
 * Deno.
 */
 function remix(options = {}) {
-	let { clientEntry = "app/entry.browser", serverEntry = "app/entry.server", serverEnvironments = ["ssr"], serverHandler = true } = options;
+	let { clientEntry = "app/entry.browser", server = true, serverEntry = "app/entry.server", serverEnvironments = ["ssr"], serverHandler = true } = options;
+	if (!server) return spa();
+	let serverEnvironmentSet = new Set(serverEnvironments);
 	return [
 		fullstack({
 			serverEnvironments,
@@ -366,7 +666,28 @@ function remix(options = {}) {
 		preview(),
 		suppressAbortErrors(),
 		normalizeWriteHead(),
-		clientEntryTransform(new Set(serverEnvironments))
+		componentHmr(serverEnvironmentSet),
+		hmrComponent(clientEntry),
+		clientEntryTransform(serverEnvironmentSet),
+		serverDataHmr(serverEnvironmentSet)
+	];
+}
+/**
+* SPA mode: the subset of `remix()` that applies when there is no server.
+* Vite already serves `index.html` and builds it to a static site, so the only
+* thing left to wire is component hot module replacement — which a
+* client-rendered app wants just as much as a server-rendered one.
+*
+* Everything server-shaped is absent by construction: no server environment,
+* no `dist/ssr`, no dev fetch handler, and no server-data HMR (there is no
+* server data to revalidate, so `<HMR />` resolves to the inert component).
+*/
+function spa() {
+	let serverEnvironmentSet = /* @__PURE__ */ new Set();
+	return [
+		componentHmr(serverEnvironmentSet),
+		hmrComponent(false),
+		clientEntryTransform(serverEnvironmentSet)
 	];
 }
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@pitlane/dev",
-    "version": "0.2.0",
-    "description": "remix() — the Remix 3 Vite plugin: build orchestration, clientEntry() hydration transform, dev server, and preview for any Vite or Vite+ project.",
+    "version": "0.4.0",
+    "description": "remix() — the Remix 3 Vite plugin: build orchestration, clientEntry() hydration transform, dev server with component and server-data HMR, and preview for any Vite or Vite+ project.",
     "keywords": [
         "pitlane",
         "remix",
@@ -49,6 +49,7 @@
     "devDependencies": {
         "@cloudflare/vite-plugin": "^1.31.0",
         "@types/node": "^25.5.0",
+        "playwright": "1.61.1",
         "remix": "3.0.0-beta.10",
         "typescript": "^7.0.2",
         "vite": "^8.1.5",