@pitlane/dev 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# @pitlane/dev
+
+## 0.1.0
+
+Initial release.
+
+- `remix()` — Remix 3 build orchestration for any Vite or Vite+ project:
+  SSR-before-client multi-environment builds into `dist/ssr` + `dist/client`,
+  dev serving through the app's default-exported fetch handler, and a preview
+  server for the production build.
+- `clientEntry()` hydration transform: named-export components become
+  hydratable islands; `import.meta.url` resolves to production asset URLs.
+- The `?assets=` import protocol plus `mergeAssets` from
+  `@pitlane/dev/runtime`, with ambient types via `@pitlane/dev/assets`.
+- Platform-agnostic by construction: composes with
+  `@cloudflare/vite-plugin`, `@netlify/vite-plugin`, and `nitro/vite`, or the
+  built handler runs directly on Node, Bun, and Deno. The assets manifest is
+  written eagerly and synthesized from bundle captures when an orchestrator
+  bundles the SSR output itself; runtime helpers are inlined into builds; dev
+  responses are normalized for runtimes with strict `node:http` semantics.
+- Tested against Vite 8.1 (Rolldown), Vite+ 0.2 (`vp`), and
+  `remix@3.0.0-beta.5` across the eight
+  [pitlane-tools/templates](https://github.com/pitlane-tools/templates)
+  deploy targets.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Malstrom
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,310 @@
+# @pitlane/dev
+
+The `remix()` Vite plugin for [Remix 3](https://remix.run). One plugin wires a Remix app into any Vite or [Vite+](https://viteplus.dev) project: multi-environment build orchestration, the `clientEntry()` hydration transform, dev serving through your app's fetch handler, and a preview server for the production build.
+
+`@pitlane/dev` is deliberately platform-agnostic. Your server entry default-exports a standard fetch handler, and hosting composes around it — platform plugins (`@cloudflare/vite-plugin`, `@netlify/vite-plugin`, `nitro/vite`) in the same plugin array, or plain runtimes (Node, Bun, Deno) running the built output directly. Composable hosting, not a hosting engine.
+
+## Install
+
+```sh
+npm install --save-dev @pitlane/dev
+# or
+vp add -D @pitlane/dev
+```
+
+Requires `remix@^3.0.0-beta.5` and `vite@>=7` as peers. v0.1.0 is tested against **Vite 8.1** (Rolldown), **Vite+ 0.2** (`vp`), and `remix@3.0.0-beta.5` — the [templates](https://github.com/pitlane-tools/templates) are the continuously tested reference.
+
+## Quick start
+
+```ts
+// vite.config.ts
+import { remix } from "@pitlane/dev";
+import { defineConfig } from "vite"; // or "vite-plus"
+
+export default defineConfig({
+    plugins: [remix()],
+});
+```
+
+```tsx
+// app/entry.server.tsx
+import { staticFiles } from "remix/middleware/static";
+import { createRouter, type MiddlewareContext } from "remix/router";
+
+import { Document } from "./document.tsx";
+import { render, type RenderMiddleware } from "./render.tsx";
+import { routes } from "./routes.ts";
+
+type AppContext = MiddlewareContext<[RenderMiddleware]>;
+
+declare module "remix/router" {
+    interface RouterTypes {
+        context: AppContext;
+    }
+}
+
+export let router = createRouter<AppContext>({
+    middleware: [staticFiles("./dist/client"), render()],
+});
+
+router.map(routes.home, ({ render }) => render(<Document />));
+
+export default router;
+
+if (import.meta.hot) {
+    import.meta.hot.accept();
+}
+```
+
+```ts
+// app/entry.browser.ts
+import { run } from "remix/ui";
+
+run({
+    async loadModule(moduleUrl, exportName) {
+        let mod = await import(/* @vite-ignore */ moduleUrl);
+        return mod[exportName];
+    },
+    async resolveFrame(src, signal) {
+        let response = await fetch(src, { headers: { accept: "text/html" }, signal });
+        return response.body ?? (await response.text());
+    },
+});
+```
+
+`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.
+
+## Options
+
+```ts
+remix({
+    clientEntry: "app/entry.browser", // default — false disables the client build
+    serverEntry: "app/entry.server", // default
+    serverEnvironments: ["ssr"], // default
+    serverHandler: true, // default — false when a platform plugin serves dev requests
+});
+```
+
+| Option               | Type              | Default               | Purpose                                                                                                                         |
+| -------------------- | ----------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `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. |
+
+## 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:
+
+```ts
+export default router;
+```
+
+Every consumer speaks that same shape:
+
+- **Dev** imports the entry through Vite's module runner and calls `default.fetch`.
+- **Preview** imports `dist/ssr/index.js` and calls `default.fetch`.
+- **Production** is whatever your target does with a fetch handler: `export default { fetch: router.fetch }` on Workers, `Bun.serve({ fetch: router.fetch })`, `deno serve dist/ssr/index.js`, or Node via `remix/node-fetch-server`.
+
+Need extra worker exports? Wrap it:
+
+```ts
+export default {
+    fetch: router.fetch,
+    async queue(batch) {
+        /* ... */
+    },
+};
+```
+
+## Asset references — `?assets=`
+
+Server-rendered documents need the hashed URLs of client assets. Import any module with the `?assets=` query to get its resolved assets for an environment:
+
+```tsx
+// app/document.tsx
+import { mergeAssets } from "@pitlane/dev/runtime";
+
+import clientAssets from "./entry.browser.ts?assets=client";
+import serverAssets from "./entry.server.tsx?assets=ssr";
+
+export function Document() {
+    let assets = mergeAssets(clientAssets, serverAssets);
+
+    return () => (
+        <html lang="en">
+            <head>
+                {assets.css.map(attrs => (
+                    <link key={attrs.href} {...attrs} rel="stylesheet" />
+                ))}
+                <script async src={clientAssets.entry} type="module" />
+                {assets.js.map(attrs => (
+                    <link key={attrs.href} {...attrs} rel="modulepreload" />
+                ))}
+            </head>
+            <body>{/* ... */}</body>
+        </html>
+    );
+}
+```
+
+Each result is `{ entry?, js: [{ href }], css: [{ href }] }`; `mergeAssets` dedupes by href. In dev, URLs point at source modules and `js` is empty (Vite handles module loading); in production they point at hashed files in `dist/client`.
+
+Type the query imports by adding the ambient declarations to your tsconfig:
+
+```jsonc
+{ "compilerOptions": { "types": ["@pitlane/dev/assets"] } }
+```
+
+## `clientEntry()` authoring rules
+
+The transform rewrites `clientEntry(import.meta.url, …)` so the first argument becomes the module's asset URL plus an `#ExportName` fragment — on the server via the `?assets=client` manifest, on the client via `import.meta.url` itself.
+
+```tsx
+import { clientEntry, on } from "remix/ui";
+
+export const Counter = clientEntry(import.meta.url, handle => {
+    let count = 0;
+    return () => (
+        <button mix={[on("click", () => { count++; handle.update(); })]}>
+            Count: <span>{count}</span>
+        </button>
+    );
+});
+```
+
+The matched pattern is strict, by design:
+
+- **Named, top-level exports only** — `export const Name = clientEntry(import.meta.url, …)`. The `#Name` fragment comes from the export name.
+- Default exports, aliased imports of `clientEntry`, and non-exported calls are left untouched.
+- Multiple `clientEntry` exports per file share one assets import.
+
+## Deployment
+
+The client build and component authoring never change across targets. Only two things vary: the `serverHandler` option and how production runs the built fetch handler.
+
+### Node
+
+```ts
+// server.ts
+import * as http from "node:http";
+import { createRequestListener } from "remix/node-fetch-server";
+
+// @ts-expect-error - built output has no types
+import ssr from "./dist/ssr/index.js";
+
+let server = http.createServer(createRequestListener(request => ssr.fetch(request)));
+server.listen(process.env.PORT ? Number.parseInt(process.env.PORT, 10) : 3000);
+```
+
+Static assets are served by the `staticFiles("./dist/client")` middleware inside your router, so `server.ts` stays a one-liner and preview/production share one code path.
+
+### Bun
+
+```ts
+// server.ts
+import router from "./app/entry.server.tsx";
+
+Bun.serve({
+    port: 3000,
+    fetch: request => router.fetch(request),
+});
+```
+
+### Deno
+
+The built entry already satisfies `deno serve`'s default-export contract:
+
+```sh
+deno serve --allow-read --allow-net dist/ssr/index.js
+```
+
+### Cloudflare Workers
+
+```ts
+// vite.config.ts
+import { remix } from "@pitlane/dev";
+import { cloudflare } from "@cloudflare/vite-plugin";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+    plugins: [remix({ serverHandler: false }), cloudflare({ viteEnvironment: { name: "ssr" } })],
+});
+```
+
+```jsonc
+// wrangler.jsonc
+{
+    "name": "my-remix-app",
+    "main": "app/entry.server.tsx",
+    "assets": { "directory": "dist/client" },
+    "compatibility_date": "2026-04-02",
+    "compatibility_flags": ["nodejs_compat"],
+}
+```
+
+`vite dev` runs your server code inside workerd (real bindings, real runtime), `vite preview` serves the production build through Miniflare, and `wrangler deploy` ships it.
+
+### Netlify
+
+Keep the defaults — Netlify's plugin emulates the platform in dev while your fetch handler serves SSR. A three-line Netlify Function (`netlify/functions/server.mjs`) wraps the built entry; see the [Netlify guide](https://pitlane.tools/deploy/netlify).
+
+```ts
+export default defineConfig({
+    plugins: [remix(), netlify()],
+});
+```
+
+### Vercel (via Nitro)
+
+```ts
+import { nitro } from "nitro/vite";
+
+export default defineConfig({
+    plugins: [remix({ serverHandler: false }), nitro()],
+});
+```
+
+## Build layout
+
+```
+dist/
+├── client/          # static assets, hashed — serve as-is
+│   └── assets/*
+└── ssr/
+    └── index.js     # your fetch handler, bundled
+```
+
+`vite build` builds the SSR environment first, then the client (the client build resolves asset references against the SSR manifest). When another plugin also orchestrates builds — Cloudflare's, for example — `remix()` coordinates so each environment builds exactly once.
+
+## Compatibility
+
+| Dependency | Tested against |
+| ---------- | -------------- |
+| `vite`     | 8.1.5          |
+| `vite-plus`| 0.2.6          |
+| `remix`    | 3.0.0-beta.5   |
+| Node       | 24 LTS, 25     |
+
+Remix 3 is in beta; each `@pitlane/dev` release records the exact beta it was verified against. Rolldown is not required — the transform runs identically on generic Vite and Vite+.
+
+### Troubleshooting
+
+**`AssertionError: isRunnableDevEnvironment(environment)` on `vite dev`** — your project resolves two different `vite` packages (typically Vite+ running the server while a plain `vite` install satisfies peer ranges). Give the project a single vite identity by aliasing, e.g. with pnpm:
+
+```jsonc
+// package.json
+{
+    "devDependencies": { "vite": "npm:@voidzero-dev/vite-plus-core@latest" },
+    "pnpm": { "overrides": { "vite": "npm:@voidzero-dev/vite-plus-core@latest" } }
+}
+```
+
+Generic-Vite projects have one vite by construction and are unaffected.
+
+## License
+
+MIT

package/dist/assets.d.mts

@@ -0,0 +1,28 @@
+/**
+ * Type declarations for Pitlane's `?assets=` import convention.
+ *
+ * Add to an app's tsconfig to type `?assets=` imports:
+ *
+ * ```jsonc
+ * { "compilerOptions": { "types": ["@pitlane/dev/assets"] } }
+ * ```
+ *
+ * Ambient by necessity: these wildcard module declarations must stay global,
+ * so types are referenced with inline `import()` instead of top-level
+ * `import type` (which would turn this file into a module).
+ */
+
+declare module "*?assets" {
+    const assets: import("@pitlane/dev/runtime").ImportedAssets;
+    export default assets;
+}
+
+declare module "*?assets=client" {
+    const assets: import("@pitlane/dev/runtime").ImportedAssets;
+    export default assets;
+}
+
+declare module "*?assets=ssr" {
+    const assets: import("@pitlane/dev/runtime").ImportedAssets;
+    export default assets;
+}

package/dist/index.d.mts

@@ -0,0 +1,51 @@
+import { PluginOption } from "vite";
+//#region src/index.d.ts
+interface RemixPluginOptions {
+  /**
+   * Client entry module, used as the client environment's build input.
+   * Pass `false` to disable the client environment entirely (fully
+   * server-rendered apps with no hydration).
+   *
+   * @default "app/entry.browser"
+   */
+  clientEntry?: string | false;
+  /**
+   * Server entry module, built as `dist/ssr/index.js`. Must default-export
+   * a fetch handler: an object exposing
+   * `fetch(request: Request): Response | Promise<Response>`, e.g. a
+   * `createRouter()` router.
+   *
+   * @default "app/entry.server"
+   */
+  serverEntry?: string;
+  /**
+   * Environment names the `clientEntry()` transform treats as "server".
+   * In these environments the transform resolves the client chunk URL via a
+   * `?assets=client` import.
+   *
+   * @default ["ssr"]
+   */
+  serverEnvironments?: string[];
+  /**
+   * Serve dev-server requests through the server entry's fetch handler.
+   * Set to `false` when another plugin owns dev-time request handling —
+   * e.g. `@cloudflare/vite-plugin`, `@netlify/vite-plugin`, or `nitro/vite`.
+   *
+   * @default true
+   */
+  serverHandler?: boolean;
+}
+/**
+ * Wires Remix 3 into a Vite or Vite+ project: multi-environment build
+ * orchestration (`dist/ssr` + `dist/client`), the
+ * `clientEntry(import.meta.url, …)` hydration transform, dev serving through
+ * the app's fetch handler, and a preview server for the production build.
+ *
+ * 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.
+ */
+declare function remix(options?: RemixPluginOptions): PluginOption;
+//#endregion
+export { RemixPluginOptions, remix };

package/dist/index.mjs

@@ -0,0 +1,413 @@
+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 MagicString from "magic-string";
+import { parseSync } from "oxc-parser";
+//#region src/build.ts
+function isFullstackBuilder(builder) {
+	return "writeAssetsManifest" in builder && typeof builder.writeAssetsManifest === "function";
+}
+/**
+* Patches the builder so pitlane-remix-build coexists with plugins that also
+* orchestrate builds (e.g. @cloudflare/vite-plugin). Runs at "pre" order so
+* the guards are in place before any building starts, regardless of plugin
+* registration order.
+*
+* Written against builder semantics, not any platform: everything is
+* feature-detected, nothing platform-specific is imported.
+*/
+function buildCompat() {
+	return {
+		name: "pitlane-remix-build:compat",
+		buildApp: {
+			order: "pre",
+			async handler(builder) {
+				let originalBuild = builder.build.bind(builder);
+				builder.build = (async (environment) => {
+					if ("isBuilt" in environment && environment.isBuilt) return;
+					return originalBuild(environment);
+				});
+				if (isFullstackBuilder(builder)) {
+					let originalWrite = builder.writeAssetsManifest.bind(builder);
+					builder.writeAssetsManifest = async () => {
+						try {
+							await originalWrite();
+						} catch (error) {
+							if (error.code !== "ENOENT") throw error;
+						}
+					};
+				}
+			}
+		}
+	};
+}
+/**
+* Keyed on globalThis so the captures survive duplicate plugin instantiation —
+* config files can be evaluated more than once in a single process.
+*/
+function bundleStore() {
+	let host = globalThis;
+	return host.__pitlaneBundleStore ??= /* @__PURE__ */ new Map();
+}
+const MANIFEST_NAME = "__fullstack_assets_manifest.js";
+const MANIFEST_REFERENCE = /__assets_manifest\["([^"]+)"\]\["([^"]+)"\]/g;
+function joinBase(base, fileName) {
+	return (base.endsWith("/") ? base : base + "/") + fileName;
+}
+function findChunkForModule(bundle, root, key) {
+	let moduleId = root.replaceAll("\\", "/") + "/" + key;
+	for (let entry of Object.values(bundle)) {
+		if (entry.type !== "chunk" || !entry.facadeModuleId) continue;
+		if (entry.facadeModuleId.replaceAll("\\", "/") === moduleId) return entry;
+	}
+}
+function collectDependencies(bundle, entryChunk) {
+	let js = [];
+	let css = /* @__PURE__ */ new Set();
+	let visited = /* @__PURE__ */ new Set();
+	let queue = [entryChunk];
+	while (queue.length > 0) {
+		let chunk = queue.shift();
+		if (visited.has(chunk.fileName)) continue;
+		visited.add(chunk.fileName);
+		js.push(chunk.fileName);
+		for (let file of chunk.viteMetadata?.importedCss ?? []) css.add(file);
+		for (let imported of chunk.imports) {
+			let entry = bundle[imported];
+			if (entry?.type === "chunk") queue.push(entry);
+		}
+	}
+	return {
+		js,
+		css: [...css]
+	};
+}
+/**
+* Synthesizes the `?assets=` manifest module when the upstream write never
+* landed. Some orchestrators (observed with Nitro) bundle the SSR output
+* inside their own buildApp without the upstream post-order write having run
+* against the same builder, leaving the built server entry importing a
+* manifest file that does not exist. Everything needed to produce it is in
+* the captured output bundles: the built server code names the exact
+* `(environment, module)` pairs it reads, and the chunk graph names the JS
+* and CSS dependencies of each module.
+*
+* No-op whenever the upstream write already produced the file.
+*/
+function ensureAssetsManifest() {
+	let ssr = bundleStore().get("ssr");
+	if (!ssr) return;
+	let ssrOutDir = path.resolve(ssr.root, ssr.outDir);
+	let manifestPath = path.join(ssrOutDir, MANIFEST_NAME);
+	if (fs.existsSync(manifestPath)) return;
+	let references = /* @__PURE__ */ new Map();
+	for (let entry of Object.values(ssr.bundle)) {
+		if (entry.type !== "chunk") continue;
+		let code = entry.code;
+		if (code === void 0) try {
+			code = fs.readFileSync(path.join(ssrOutDir, entry.fileName), "utf8");
+		} catch {
+			continue;
+		}
+		for (let match of code.matchAll(MANIFEST_REFERENCE)) {
+			let keys = references.get(match[1]) ?? /* @__PURE__ */ new Set();
+			keys.add(match[2]);
+			references.set(match[1], keys);
+		}
+	}
+	if (references.size === 0) return;
+	let client = bundleStore().get("client");
+	let base = (client ?? ssr).base;
+	let manifest = {};
+	for (let [environmentName, keys] of references) {
+		let captured = bundleStore().get(environmentName);
+		if (!captured) continue;
+		for (let key of keys) {
+			let chunk = findChunkForModule(captured.bundle, captured.root, key);
+			if (!chunk) continue;
+			let dependencies = collectDependencies(captured.bundle, chunk);
+			let record = {
+				js: [],
+				css: []
+			};
+			if (environmentName === "client") {
+				record.entry = joinBase(base, chunk.fileName);
+				record.js = dependencies.js.map((fileName) => ({ href: joinBase(base, fileName) }));
+			}
+			record.css = dependencies.css.map((fileName) => ({ href: joinBase(base, fileName) }));
+			(manifest[environmentName] ??= {})[key] = record;
+		}
+	}
+	fs.mkdirSync(ssrOutDir, { recursive: true });
+	fs.writeFileSync(manifestPath, `export default ${JSON.stringify(manifest)};\n`);
+	if (client) {
+		let clientOutDir = path.resolve(client.root, client.outDir);
+		for (let entry of Object.values(ssr.bundle)) {
+			if (entry.type !== "asset") continue;
+			let source = path.join(ssrOutDir, entry.fileName);
+			let destination = path.join(clientOutDir, entry.fileName);
+			if (!fs.existsSync(source) || fs.existsSync(destination)) continue;
+			fs.mkdirSync(path.dirname(destination), { recursive: true });
+			fs.copyFileSync(source, destination);
+		}
+	}
+}
+/**
+* Environment defaults and build sequencing. SSR builds first, then the
+* client: the client build resolves `?assets=ssr` against the SSR manifest,
+* so the order is load-bearing.
+*/
+function build({ clientEntry, serverEntry }) {
+	let hasClientEntry = clientEntry !== false;
+	return {
+		name: "pitlane-remix-build",
+		writeBundle(_options, bundle) {
+			bundleStore().set(this.environment.name, {
+				bundle,
+				root: this.environment.config.root,
+				base: this.environment.config.base,
+				outDir: this.environment.config.build.outDir
+			});
+		},
+		async buildApp(builder) {
+			await builder.build(builder.environments.ssr);
+			if (hasClientEntry) await builder.build(builder.environments.client);
+			if (isFullstackBuilder(builder)) await builder.writeAssetsManifest();
+			ensureAssetsManifest();
+		},
+		config(userConfig) {
+			let environments = userConfig.environments;
+			let hasUserClientInput = Boolean(environments?.client?.build?.rollupOptions?.input);
+			let hasUserServerInput = Boolean(environments?.ssr?.build?.rollupOptions?.input);
+			return {
+				builder: {},
+				build: { assetsInlineLimit: 0 },
+				environments: {
+					...hasClientEntry && { client: { build: {
+						outDir: "dist/client",
+						rollupOptions: { input: hasUserClientInput ? void 0 : clientEntry || void 0 }
+					} } },
+					ssr: {
+						resolve: { noExternal: [/^@pitlane\/dev(\/|$)/] },
+						build: {
+							outDir: "dist/ssr",
+							rollupOptions: { input: hasUserServerInput ? void 0 : { index: serverEntry } }
+						}
+					}
+				}
+			};
+		}
+	};
+}
+const RUNTIME_MODULE_ID = "\0pitlane:runtime";
+/**
+* Resolves `@pitlane/dev/runtime` imports to an inlined copy of the
+* implementation. The package is a dev dependency: built output must never
+* 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.
+*/
+function runtimeInline() {
+	return {
+		name: "pitlane-runtime-inline",
+		enforce: "pre",
+		resolveId: {
+			filter: { id: /^@pitlane\/dev\/runtime$/ },
+			handler(source) {
+				if (source === "@pitlane/dev/runtime") return RUNTIME_MODULE_ID;
+			}
+		},
+		load: {
+			filter: { id: /^\0pitlane:runtime$/ },
+			handler(id) {
+				if (id === RUNTIME_MODULE_ID) return `export const mergeAssets = ${mergeAssets.toString()};\n`;
+			}
+		}
+	};
+}
+//#endregion
+//#region src/preview.ts
+function isFetchHandler(value) {
+	return typeof value === "object" && value !== null && "fetch" in value && typeof value.fetch === "function";
+}
+/**
+* Serves the production build through `vite preview` using the same SSR entry
+* that production deploys, adapted with `remix/node-fetch-server`.
+*
+* When the SSR bundle targets a non-Node runtime (e.g. Cloudflare Workers,
+* whose bundle imports `cloudflare:workers`), the dynamic import fails and the
+* plugin skips itself so the platform plugin's preview can take over. That
+* failure → skip contract is documented behavior, not an accident.
+*/
+function preview() {
+	return {
+		name: "pitlane-remix-preview-server",
+		async configurePreviewServer(server) {
+			let ssrOutDir = server.config.environments.ssr?.build?.outDir ?? "dist/ssr";
+			let entryPath = new URL(`${ssrOutDir}/index.js`, `file://${server.config.root}/`).href;
+			let mod;
+			try {
+				mod = await import(
+					/* @vite-ignore */
+					entryPath
+);
+			} catch {
+				return;
+			}
+			let handler = mod.default;
+			if (!isFetchHandler(handler)) throw new Error(`[@pitlane/dev] ${ssrOutDir}/index.js must default-export a fetch handler (an object with fetch(request: Request)), e.g. \`export default router\`.`);
+			let { createRequestListener } = await import("remix/node-fetch-server");
+			return () => {
+				server.middlewares.use(createRequestListener((request) => handler.fetch(request)));
+			};
+		}
+	};
+}
+//#endregion
+//#region src/transform.ts
+const CLIENT_ENTRY_PATTERN = /\bclientEntry\b/;
+/**
+* Rewrites `export const Name = clientEntry(import.meta.url, …)` so the first
+* argument resolves to a production asset URL carrying an `#ExportName`
+* fragment.
+*
+* - In server environments the module gains one
+*   `import ___clientEntryAssets from "<id>?assets=client"` prepend, and each
+*   call site becomes `___clientEntryAssets.entry + "#Name"`.
+* - In the client environment `import.meta.url` already resolves to the chunk
+*   URL at runtime, so each call site becomes `import.meta.url + "#Name"`.
+*
+* One code path runs everywhere — dev and build, generic Vite and Vite+.
+* (Rolldown's native `meta.ast`/`meta.magicString` fast path was tried and
+* reverted: unfinished types, never exercised. Revisit once it is real.)
+*/
+function clientEntryTransform(serverEnvironments) {
+	return {
+		name: "pitlane-remix-client-entry-transform",
+		transform: {
+			filter: { code: { include: CLIENT_ENTRY_PATTERN } },
+			handler(code, id) {
+				if (!code.includes("import.meta.url")) return;
+				let ast = parseSync(id, code).program;
+				let calls = findClientEntryCalls(ast);
+				if (calls.length === 0) return;
+				let ms = new MagicString(code);
+				if (serverEnvironments.has(this.environment.name)) {
+					ms.prepend(`import ___clientEntryAssets from "${id}?assets=client";\n`);
+					for (let call of calls) ms.overwrite(call.metaUrlStart, call.metaUrlEnd, `___clientEntryAssets.entry + "#${call.exportName}"`);
+				} else for (let call of calls) ms.overwrite(call.metaUrlStart, call.metaUrlEnd, `import.meta.url + "#${call.exportName}"`);
+				return {
+					code: ms.toString(),
+					map: ms.generateMap({
+						hires: "boundary",
+						source: id
+					})
+				};
+			}
+		}
+	};
+}
+/**
+* Matches exactly `export const Name = clientEntry(import.meta.url, …)` at the
+* top level, with at least two arguments. Default exports, aliased callees,
+* and non-exported calls are intentionally ignored — the `#Name` fragment
+* requires a named export.
+*/
+function findClientEntryCalls(program) {
+	let results = [];
+	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 (declarator.init?.type !== "CallExpression") continue;
+			let call = declarator.init;
+			if (call.callee.type !== "Identifier" || call.callee.name !== "clientEntry") continue;
+			if (call.arguments.length < 2) continue;
+			let firstArg = call.arguments[0];
+			if (firstArg.type !== "MemberExpression" || firstArg.object.type !== "MetaProperty" || firstArg.property.type !== "Identifier" || firstArg.property.name !== "url") continue;
+			results.push({
+				exportName: declarator.id.name,
+				metaUrlStart: firstArg.start,
+				metaUrlEnd: firstArg.end
+			});
+		}
+	}
+	return results;
+}
+//#endregion
+//#region src/index.ts
+/**
+* Wires Remix 3 into a Vite or Vite+ project: multi-environment build
+* orchestration (`dist/ssr` + `dist/client`), the
+* `clientEntry(import.meta.url, …)` hydration transform, dev serving through
+* the app's fetch handler, and a preview server for the production build.
+*
+* 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;
+	return [
+		fullstack({
+			serverEnvironments,
+			serverHandler
+		}),
+		buildCompat(),
+		build({
+			clientEntry,
+			serverEntry
+		}),
+		runtimeInline(),
+		preview(),
+		suppressAbortErrors(),
+		normalizeWriteHead(),
+		clientEntryTransform(new Set(serverEnvironments))
+	];
+}
+/**
+* Suppresses `aborted` errors from client disconnects (e.g. search-as-you-type
+* or navigating away mid-fetch) that would otherwise trigger Vite's dev error
+* overlay. The match is deliberately narrow so real failures still propagate.
+*/
+function suppressAbortErrors() {
+	return {
+		name: "pitlane-remix-suppress-abort-errors",
+		configureServer(server) {
+			return () => {
+				server.middlewares.use((err, _req, _res, next) => {
+					if (err?.message === "aborted") return;
+					next(err);
+				});
+			};
+		}
+	};
+}
+/**
+* Flattens `[["key", "value"], …]` header arguments to the documented flat
+* form before they reach `res.writeHead`. Node tolerates nested pairs, but
+* runtimes implementing the documented `node:http` contract (Deno) reject
+* them — and dev-serving dependencies send pairs. Dev-only; production
+* responses never pass through this server.
+*/
+function normalizeWriteHead() {
+	return {
+		name: "pitlane-remix-normalize-write-head",
+		configureServer(server) {
+			server.middlewares.use((_req, res, next) => {
+				let original = res.writeHead.bind(res);
+				res.writeHead = ((...args) => {
+					let last = args[args.length - 1];
+					if (Array.isArray(last) && last.every((entry) => Array.isArray(entry))) args[args.length - 1] = last.flat();
+					return original(...args);
+				});
+				next();
+			});
+		}
+	};
+}
+//#endregion
+export { remix };

package/dist/runtime.d.mts

@@ -0,0 +1,32 @@
+//#region src/runtime.d.ts
+/**
+ * The result shape of a `?assets=` import: the resolved entry URL (client
+ * environment only), plus the JS and CSS assets reachable from the imported
+ * module in that environment.
+ *
+ * During dev, `js` is always empty (no chunk graph exists yet) and
+ * `?assets=client` carries no CSS — Vite injects dev styles itself; the
+ * server-environment results carry `data-vite-dev-id` stylesheet links.
+ */
+interface ImportedAssets {
+  entry?: string;
+  js: Array<{
+    href: string;
+  }>;
+  css: Array<{
+    href: string;
+    "data-vite-dev-id"?: string;
+  }>;
+  merge(...results: ImportedAssets[]): ImportedAssets;
+}
+/**
+ * Merges multiple `?assets=` results, deduplicating `js` and `css` entries by
+ * href. Typical use: combining the client entry's assets with the SSR
+ * module's CSS inside a `<Document>` component.
+ *
+ * The annotation re-types the delegated implementation against Pitlane-owned
+ * shapes so the dependency never appears in this package's public types.
+ */
+declare const mergeAssets: (...results: ImportedAssets[]) => ImportedAssets;
+//#endregion
+export { ImportedAssets, mergeAssets };

package/dist/runtime.mjs

@@ -0,0 +1,19 @@
+import { mergeAssets as mergeAssets$1 } from "@hiogawa/vite-plugin-fullstack/runtime";
+//#region src/runtime.ts
+/**
+* Server- and client-safe runtime helpers for the `?assets=` import
+* convention. Import from `@pitlane/dev/runtime` in application code.
+*
+* @module @pitlane/dev/runtime
+*/
+/**
+* Merges multiple `?assets=` results, deduplicating `js` and `css` entries by
+* href. Typical use: combining the client entry's assets with the SSR
+* module's CSS inside a `<Document>` component.
+*
+* The annotation re-types the delegated implementation against Pitlane-owned
+* shapes so the dependency never appears in this package's public types.
+*/
+const mergeAssets = mergeAssets$1;
+//#endregion
+export { mergeAssets };

package/package.json

@@ -0,0 +1,65 @@
+{
+    "name": "@pitlane/dev",
+    "version": "0.1.0",
+    "description": "remix() \u2014 the Remix 3 Vite plugin: build orchestration, clientEntry() hydration transform, dev server, and preview for any Vite or Vite+ project.",
+    "homepage": "https://pitlane.tools/package/dev/",
+    "bugs": {
+        "url": "https://github.com/pitlane-tools/pitlane/issues"
+    },
+    "license": "MIT",
+    "author": "Mark Malstrom <mark@malstrom.me>",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/pitlane-tools/pitlane.git",
+        "directory": "packages/dev"
+    },
+    "keywords": [
+        "remix",
+        "vite",
+        "vite-plugin",
+        "pitlane"
+    ],
+    "files": [
+        "dist",
+        "CHANGELOG.md"
+    ],
+    "type": "module",
+    "types": "./dist/index.d.mts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.mts",
+            "import": "./dist/index.mjs"
+        },
+        "./runtime": {
+            "types": "./dist/runtime.d.mts",
+            "import": "./dist/runtime.mjs"
+        },
+        "./assets": {
+            "types": "./dist/assets.d.mts"
+        }
+    },
+    "scripts": {
+        "prepublishOnly": "vp run build"
+    },
+    "dependencies": {
+        "@hiogawa/vite-plugin-fullstack": "0.0.11",
+        "magic-string": "^0.30.21",
+        "oxc-parser": "^0.141.0"
+    },
+    "peerDependencies": {
+        "remix": "^3.0.0-beta.5",
+        "vite": ">=7.0.0"
+    },
+    "devDependencies": {
+        "@cloudflare/vite-plugin": "^1.31.0",
+        "@types/node": "^25.5.0",
+        "remix": "3.0.0-beta.5",
+        "typescript": "^7.0.2",
+        "vite": "^8.1.5",
+        "vite-plus": "^0.2.6",
+        "wrangler": "^4.114.0"
+    },
+    "engines": {
+        "node": "^20.19.0 || >=22.12.0"
+    }
+}