@warlock.js/web 5.1.0 → 5.2.0

package/CHANGELOG.md

@@ -2,6 +2,180 @@
 
 All notable changes to `@warlock.js/web` are documented here.
 
+## 5.2.0
+
+### Added
+
+- **`error.page.tsx`** — the application's one error boundary. It renders when
+  a middleware, loader, or component throws; declares no `route`, exactly like
+  `404.page.tsx`; and a second `error.page.tsx` anywhere beneath `src/web` is a
+  build error. Its component receives `{ error, status }` — the real thrown
+  value during SSR, a JSON-safe `{ name, message, stack? }` after hydration.
+  `robots: noindex` is a framework default on this path and cannot be
+  overridden away. If the failure happens before any page module could load —
+  a module-load or `register()` throw — the response falls back further, to a
+  framework-owned boundary with no application code at all, and is served
+  without a hydration script rather than risk hydrating against markup nothing
+  can vouch for.
+- **A page's `route` export is now optional.** A `*.page.tsx` with no `route`
+  derives its path and its name from its location beneath `src/web`:
+  directories contribute segments, `(group)` directories contribute nothing,
+  `index.page.tsx` claims its own directory, and `[id]` becomes `:id`. An
+  explicit `route` still always wins over the derived one. This replaces the
+  5.1 behaviour, where an omitted `route` threw `MissingRouteExportError` at
+  install time — that error class no longer exists.
+- **Live page-route re-registration in `warlock dev`.** Creating, deleting, or
+  editing a page's `route` export used to require a manual restart to take
+  effect — the route table was built once at boot and never again, so a
+  renamed route kept serving its old path and a deleted page kept 404-ing at
+  its old URL forever. The dev connector now re-registers the affected routes
+  in place, atomically, with no dev-server restart and no loss of Vite's HMR
+  state. A component-body-only edit still takes the ordinary Fast Refresh
+  path; only membership and route-identity changes go through this path.
+- **A dev-only diagnostic for a page file that exists but isn't reachable.**
+  When a request 404s, Warlock checks whether an unregistered `*.page.tsx`
+  under `src/web` would have matched it, and if so, warns naming the file.
+  This is the case that used to be silent: a page created after boot, or one
+  whose `route` was edited to a path nothing else claims, previously 404'd
+  with no explanation anywhere in the terminal.
+- **`export const register`** — an optional, synchronous, no-argument hook on
+  `root.tsx`, `layout.tsx`, and `*.page.tsx`. It runs once per module
+  namespace instance, on both the server and the browser, before that
+  module's middleware or loader — the seam for one-time setup a page or
+  layout needs on both sides of hydration. It must not return a Promise;
+  returning one throws.
+
+### Changed
+
+- **Page requests now tolerate one trailing slash identically in development
+  and production.** `/about` and `/about/` serve the same page; `/` remains the
+  root path and case handling is unchanged. Previously the development
+  dispatcher accepted the slash while the production Fastify route returned
+  404.
+
+- ⚠ **BREAKING — `process.env` is refused entirely in the client/universal
+  graph, and there is no `PUBLIC_` exception.** Neither a static key
+  (`process.env.PUBLIC_API_URL`) nor a computed one (`process.env[key]`) is
+  allowed: `process` does not exist in a browser, so there is no such thing as
+  a "public" `process.env` key. **Bare value-reads of the object now fail
+  too** — `const { X } = process.env`, `{ ...process.env }`,
+  `Object.keys(process.env)`, `JSON.stringify(process.env)`, or passing it as
+  an argument — which is the case that previously let an entire server
+  environment reach a component in one line while every keyed read was being
+  refused. `globalThis.process.env`, `window.process.env` and
+  `process["env"]` are matched as well.
+
+  **Enforcement now covers dev SSR as well as the client bundle, and a
+  violation fails the build** rather than being a production-only surprise.
+  Files under `node_modules` stay out of scope by design — a dependency's own
+  `process.env.NODE_ENV` guard is not the application's problem.
+
+  ⚠ **`env("PUBLIC_X")` does not work client-side either**, and never did:
+  `env` comes from `@warlock.js/core`, which declares itself server-only, so
+  the import is refused before the call is ever examined. **The supported
+  pattern is to read the value in a page loader — server code — and pass it to
+  the page as loader data:**
+
+  ```tsx
+  export const loader = (async () => ({
+    siteName: env("PUBLIC_SITE_NAME"),
+  })) satisfies PageLoader;
+
+  export default function HomePage({ data }: PageProps<typeof loader>) {
+    return <h1>{data.siteName}</h1>;
+  }
+  ```
+
+  If a value must genuinely be inlined into browser code instead of passed as
+  loader data, the one supported spelling is `import.meta.env.PUBLIC_*` with a
+  static key — Vite's env surface, baked in at build time, so it cannot vary
+  per request. Server-side code is unrestricted.
+
+- ⚠ **BREAKING — a `*.page.tsx` with no default export is now a hard
+  discovery/build failure, naming the file.** It previously built and
+  registered, then served a blank `200` at its URL — a page that looked
+  deployed, rendered nothing, and produced no error anywhere.
+
+  ```
+  The page "src/web/contact.page.tsx" has no runtime default export. Every
+  `*.page.tsx` file must default-export the React component it renders.
+  ```
+
+  `export { Page as default }` satisfies the rule — the check is for a runtime
+  default binding, not for the keyword form. `export default interface Page {}`
+  does not: a type-only default is erased and leaves no component behind. A
+  file that cannot be parsed reports as a parse failure instead, so a syntax
+  error never masquerades as a missing export.
+
+- **Initial stylesheet links are route-scoped in development and production.**
+  Each response now links the ordered, deduplicated CSS chain for its own
+  `[root, ...matched layouts, page]`. Production follows those source entries
+  and their static imports in Vite's manifest instead of collecting CSS across
+  the whole application; development promotes direct stylesheet imports from
+  the matched page and layouts as well as the root. Unrelated page CSS no
+  longer ships on every response, and page-local critical CSS no longer waits
+  for hydration in development.
+- **The production static-asset refusal now names the working 5.2 alternative.**
+  Imported non-stylesheet assets still work under Vite in development but are
+  refused by the esbuild server bundle rather than risk a server/client URL
+  mismatch. The diagnostic now tells the developer to place the file under the
+  application's `public/` directory and reference its root URL
+  (`public/logo.svg` → `/logo.svg`) instead of waiting for an unspecified future
+  server build. Stylesheet imports remain supported.
+- **Loader execution is sequential, root to leaf, and terminal responses stop
+  lower work.** The `root.tsx` App loader runs first, followed by every matched
+  layout loader from outermost to innermost, then the page loader. The runtime
+  has three top-level slots (`app`, `layout`, `page`), but the layout slot
+  composes the full matched layout chain. A page still has at most one
+  *rendering* layout; loader-only and middleware-only layouts may appear at
+  multiple ancestry levels.
+
+  ⚠ **This package's own documentation previously described the three levels as
+  running in parallel, and told you not to rely on ordering between them.** The
+  implementation now awaits the App slot, the composed outer-to-inner layout
+  slot, and the Page slot in that order.
+
+  **The first core `Response` a loader returns is terminal**: it stops every
+  lower loader from starting, and — because the response is returned whole — it
+  also bypasses buffer commit and metadata resolution, discarding the header
+  and cookie writes buffered at that same level. A short-circuit
+  (`response.redirect()`, `response.notFound()`) commits its own level's buffer
+  inclusively and is the right choice when those writes should survive; a throw
+  discards the throwing level's buffer and commits only the levels above it.
+
+- **Catch-all page routes are documented as unsupported.** `[...slug].page.tsx`
+  does not do what it looks like: filesystem routing recognizes only `[name]` as
+  a dynamic segment, so `[...slug]` is taken as a **literal** segment and derives
+  the path `/docs/[...slug]` and the name `docs.[...slug]` — reachable only at
+  the literal URL `/docs/%5B...slug%5D`. ⚠ **Nothing warns about it**: no build
+  error, no dev warning, no refusal, just a page that answers a URL nobody will
+  request. A real catch-all is deferred; until then use a terminal wildcard with
+  an explicit route (`route = { path: "/docs/*" }`). This entry records the gap,
+  it does not close it.
+
+- **`src/web` is the only page root.** A per-module `src/app/<module>/web/`
+  tree is no longer discovered, walked, or installed as a page root by either
+  `warlock dev` or `warlock build`. Move any page, layout, or root file that
+  lived under `src/app/<module>/web/` into `src/web/` (a subdirectory is
+  fine — it still contributes a route segment the same way).
+
+### Fixed
+
+- **A custom `404.page.tsx` loader no longer executes.** The not-found page
+  still registers and renders its real module namespace, but its request
+  triple omits the page loader in both development and production. A missing
+  URL therefore cannot trigger application data work, redirect, or fail a
+  second time through the fallback itself.
+
+  Precisely what is skipped, because "the 404 page doesn't run loaders" is a
+  useful shorthand and not the whole rule: only the **page-level `loader`** is
+  omitted. The real module namespace is still used, so `register()` runs and
+  the component renders normally, and the page's **middleware still runs**.
+  Layout loaders don't run because this page has an empty layout chain by
+  construction, not because loaders are disabled on it. And the **`root.tsx`
+  App loader does still run** on a 404 request — keep it cheap, and make sure
+  it tolerates a request that matched nothing.
+
 ## 5.1.0
 
 > **Upgrade if you installed 5.0.0, 5.0.1 or 5.0.2.** React did not execute at all in

package/README.md

@@ -41,7 +41,9 @@ export const route = "/products";
 export const loader = (async ({ response }) => {
   response.header("cache-control", "private, max-age=60");
 
-  return { products: productResourceCollection(await productsRepository.all()) };
+  return {
+    products: productResourceCollection(await productsRepository.all()),
+  };
 }) satisfies PageLoader;
 
 /** Server-only. Runs after the loader and receives its data. */
@@ -54,7 +56,7 @@ export const metadata = ({ data }) => ({
 export default function ProductsPage({ data }: PageProps<typeof loader>) {
   return (
     <ul>
-      {data.products.map(product => (
+      {data.products.map((product) => (
         <li key={product.id}>{product.name}</li>
       ))}
     </ul>
@@ -76,34 +78,146 @@ production.
   compile error.
 - **Loaders that are controllers.** Full request context, guards, DI, and the
   ability to set headers, cookies and status during the render.
-- **`revalidate()`.** POST to your own API, call it, and the page's loaders
-  re-run.
+- **`refresh()`.** POST to your own API, call it, and the page's loaders
+  re-run without pushing history. There is no `revalidate()` export.
 - **Return values are Resources, never models.** A model does not survive the
   wire: it carries methods, a connector handle and every column.
 
 ## The two halves of a page file
 
-| Server-only | Runs twice (server + browser) |
-|---|---|
-| `route`, `middleware`, `validation`, `loader`, `metadata` | `Layout`, `ErrorBoundary`, default `Page` |
+| Server-only                                                                        | Runs twice (server + browser)         |
+| ---------------------------------------------------------------------------------- | ------------------------------------- |
+| `route`, `middleware`, `validation`, `loader`, `metadata`, `prefix` (layouts only) | default `Page` / `Layout`, `register` |
 
 The server half is stripped before anything reaches the browser. The runs-twice
 half never receives `request` or `response` — it also executes in a browser,
 where neither exists — and is never `async`.
 
+**A `.client.tsx` suffix is a naming convention, not an SSR-isolation boundary
+in 5.2.** A module statically imported by a root, layout, page, or one of their
+imports is still evaluated by the server. Top-level browser globals such as
+`window` therefore crash SSR boot. Warlock 5.2 does not ship a client-only
+component primitive; code that requires browser globals at module scope cannot
+be part of the SSR page graph.
+
+**Imported non-stylesheet static assets are also unsupported by the production
+server build in 5.2.** An import such as `import logo from "./logo.svg"` works
+under Vite in development but is refused by `warlock build`. Put the file under
+the application's `public/` directory and reference its root URL instead:
+`public/logo.svg` is `/logo.svg`. Stylesheet imports remain supported.
+
+### Loader order
+
+Loaders run **sequentially, root to leaf, each awaited before the next
+starts**: the `root.tsx` App loader, then every matched layout loader from
+outermost to innermost, then the page loader. The runtime has three top-level
+slots (`app`, `layout`, `page`), but the layout slot composes the full matched
+layout chain. Only one layout on that chain may render; loader-only and
+middleware-only layouts still participate.
+
+**The first core `Response` returned by a loader is terminal**: it stops every
+lower loader from running, skips metadata, and is sent as-is. Because it is
+returned whole, the buffered header and cookie writes made at that level go
+with it — use `response.redirect()` / `response.notFound()` when you want those
+writes committed, and a raw `Response` only when you mean exactly that
+response.
+
+### Environment variables
+
+**`process.env` is refused entirely in the client/universal graph. There is no
+`PUBLIC_` exception to it — static or computed — and `env("PUBLIC_X")` does not
+work client-side either.** The supported pattern is to read the value in a page
+loader, which is server code, and pass it to the page as loader data:
+
+```tsx
+import { env } from "@warlock.js/core";
+import type { PageLoader, PageProps } from "@warlock.js/web";
+
+export const loader = (async () => ({
+  siteName: env("PUBLIC_SITE_NAME"),
+})) satisfies PageLoader;
+
+export default function HomePage({ data }: PageProps<typeof loader>) {
+  return <h1>{data.siteName}</h1>;
+}
+```
+
+The loader is server-only, so it may read configuration normally. Its return
+value becomes page data and is serialized to the browser; return only values
+that are safe to expose.
+
+The refusal applies to default page and layout components, `register()`, and
+any helper they import. It covers keyed reads (`process.env.X`,
+`process.env.PUBLIC_X`, `process.env[key]`) and **bare value-reads** of the
+object itself — `const { X } = process.env`, `{ ...process.env }`,
+`Object.keys(process.env)`, `JSON.stringify(process.env)`. `process` does not
+exist in a browser, so touching the object at all is already broken, and
+handing the whole object to a component is how a server secret ships in one
+line.
+
+**Enforcement covers dev SSR as well as the client bundle, and a violation
+fails the build** — this is not a production-only check you find out about
+late. Server-side code is unrestricted.
+
+If a value must genuinely be inlined into browser code rather than passed as
+loader data, the one supported spelling is `import.meta.env.PUBLIC_*` with a
+static key. That is Vite's surface, not Node's; it is baked in at build time,
+so it cannot vary per request — loader data remains the answer for anything
+request-scoped.
+
+## Routing
+
+A page's URL is its `route` export when it declares one. A page with no
+`route` derives its URL from its own location beneath `src/web`: directories
+contribute segments, `(group)` directories contribute nothing, `index.page.tsx`
+claims its directory, and `[id]` becomes `:id`. A layout's `prefix` still
+composes in front of either form. `route`, when present, always wins.
+
+Every `*.page.tsx` must have a **default export**. A page file with only named
+exports is a hard discovery/build failure naming the file — it used to build
+and then serve a blank `200` at its URL.
+
+**Catch-all routes are not supported.** `[...slug].page.tsx` is not a rest
+parameter: only `[name]` is recognized as dynamic, so `[...slug]` is taken as a
+literal segment and derives the unreachable path `/[...slug]`. Nothing warns
+about it. Use a terminal wildcard with an explicit route
+(`route = { path: "/docs/*" }`) until a real catch-all exists.
+
+`src/web` is the only page root — a per-module `src/app/<module>/web/` tree is
+not scanned.
+
+Incoming URLs may carry one trailing slash: `/about` and `/about/` match the
+same page in development and production. Route declarations remain canonical
+and slash-free, `/` stays the root path, and case handling is unchanged.
+
+Exactly two page filenames are special: `404.page.tsx` (the not-found page,
+reached by not matching, never declares `route`, renders with no layout) and
+`error.page.tsx` (the application's one error boundary, also declares no
+`route`). There is no `500.page.tsx`; an unmatched URL is not an error.
+
+**`404.page.tsx` never runs its own loader.** The module is registered and
+rendered for real — `register()` and its middleware still run — but the page
+loader is omitted from the request in both development and production, so a
+missing URL cannot trigger application data work, redirect, or fail a second
+time through the fallback. Layout loaders do not run either, because the page
+has an empty layout chain by construction. The `root.tsx` App loader **does**
+still run, so keep it cheap and make sure it tolerates a request that matched
+nothing.
+
+In development, creating, deleting, or editing a page's `route` export updates
+the live route table without restarting `warlock dev`.
+
 ## Where things live
 
 ```
-src/web/                    app-level web layer, and a page root
+src/web/                    app-level web layer and page root
   root.tsx                  owns <html>, renders #root
   layouts/                  shared layouts
   middleware/
-src/app/<module>/web/       that module's own pages
 ```
 
-Both are page roots. All client code lives in a `web/` folder, and nothing
-outside one may import from one — so `rm -rf src/web src/app/*/web` removes the
-page layer and leaves a working API.
+All client code lives in `src/web/`, so `rm -rf src/web` removes the page layer
+and leaves a working API.
 
 **`web/` means the web layer, not the browser.** Loaders and page middleware
 inside it are server code.

package/esm/build/contribution.d.mts

@@ -1,6 +1,7 @@
 import { ConnectorBuildContribution } from "@warlock.js/core";
+import { PluginOption } from "vite";
 
-//#region ../web/src/build/contribution.d.ts
+//#region web/src/build/contribution.d.ts
 type WebBuildOptions = {
   /** Source directory name under the app root. Default: `"src"`. */srcDir?: string;
   /**
@@ -27,16 +28,6 @@ type WebBuildOptions = {
   clientOutDir?: string; /** Client-build resolve aliases: specifier -> absolute path. */
   aliases?: Record<string, string>; /** Extra package names to keep external to the client bundle. */
   external?: string[];
-  /**
-   * NOT AN APP-FACING OPTION. Set by `webConnector()` from the length of its own
-   * `plugins` array; a COUNT rather than the array itself, because this options
-   * object is JSON-serializable-values-only (constraint B) and a plugin instance
-   * here would drag Vite into every config load.
-   *
-   * Its only consumer is the refusal in `generate` — see
-   * {@link ConnectorPluginsNotSupportedError}.
-   */
-  connectorPluginCount?: number;
 };
 /**
  * The resolved `@warlock.js/web` root is not that package.
@@ -54,12 +45,18 @@ declare class WebPackageRootResolutionError extends Error {
  *
  * `generate` writes the page barrel into `ctx.productionDir` and patches
  * esbuild; `emit` produces the client bundle esbuild cannot. The two share one
- * closure fact — how many pages exist — because a build with zero pages must
- * skip the client bundle rather than emit an orphan one. `generate` itself does
+ * closure facts — how many pages exist, the discovered route table, and the
+ * exact app-public file list. A build with zero pages skips the hydration
+ * bundle but still copies public files when present. `generate` itself does
  * NOT skip: the barrel and its entry import are emitted either way, so the
  * runtime can tell a page-free web build from a build without web.
+ *
+ * Connector plugins are a separate argument rather than a `WebBuildOptions`
+ * field: the app constructs them once, the factory snapshots that array for
+ * both dev and build, and this module keeps Vite as a type-only import until
+ * `emit` dynamically loads the real client builder.
  */
-declare function createWebBuildContribution(options?: WebBuildOptions): ConnectorBuildContribution;
+declare function createWebBuildContribution(options?: WebBuildOptions, connectorPlugins?: readonly PluginOption[]): ConnectorBuildContribution;
 //#endregion
 export { WebBuildOptions, WebPackageRootResolutionError, createWebBuildContribution };
 //# sourceMappingURL=contribution.d.mts.map

package/esm/build/contribution.mjs

@@ -1,7 +1,7 @@
-import path from "node:path";
 import { readFileSync } from "node:fs";
+import path from "node:path";
 
-//#region ../web/src/build/contribution.ts
+//#region web/src/build/contribution.ts
 /**
 * Web's build-time half — the object a `WebConnector` hands to
 * `warlock build` as its `build` contribution.
@@ -37,40 +37,6 @@ var ClientOutDirNotSupportedError = class extends Error {
 		this.name = "ClientOutDirNotSupportedError";
 	}
 };
-/**
-* `webConnector({ plugins })` was given plugins, and `warlock build` cannot
-* apply them.
-*
-* THE SILENT FAILURE THIS REPLACES. `plugins` reaches exactly one place: the
-* dev server's `createServer({ plugins: [...] })`. The production client bundle
-* is built by `buildWarlockHydrationClient`, which composes its own pipeline
-* (`web/src/vite/index.ts` — projection and the boundary gates) and is not
-* handed the connector's array by anyone. So a plugin worked in `warlock dev`
-* and was absent from `warlock build`, with no warning and a green build log:
-* the site shipped unstyled, or unprocessed in whatever way the plugin
-* mattered, and the build claimed success. That is worse than any loud failure.
-*
-* WHY REFUSE RATHER THAN WIRE IT THROUGH. Plugin ORDER is part of a pipeline's
-* behavior, and a plugin authored against a dev server can misbehave inside a
-* production build; threading the array in is a change to build behavior that
-* has to be verified, not assumed. Refusing removes the silent failure now and
-* is strictly additive to reverse — wiring the plugins through later breaks no
-* app that this error currently stops, while shipping a half-verified plugin
-* pipeline could break every one of them.
-*
-* The message names the option and says what to do instead, because an error
-* that only says "no" costs the reader the same hour it took to find this.
-*/
-var ConnectorPluginsNotSupportedError = class extends Error {
-	constructor(pluginCount) {
-		super(`"plugins" on the web connector is not supported by \`warlock build\`: webConnector({ plugins }) was given ${pluginCount} plugin${pluginCount === 1 ? "" : "s"}, and they reach the dev server ONLY. The production client bundle is built with the framework's own pipeline and would silently ship without them, so this build refuses rather than emit an artifact that differs from what you saw in \`warlock dev\`.
-
-What to do instead: express the transform somewhere BOTH dev and build already read.
-  - CSS/PostCSS (Tailwind, autoprefixer, ...): put a \`postcss.config.mjs\` at your app root. Vite loads it automatically in dev and in build — this is how Tailwind is supported today.
-  - Otherwise: remove \`plugins\` from webConnector() and open an issue describing what the plugin does, so the production pipeline can support it deliberately.`);
-		this.name = "ConnectorPluginsNotSupportedError";
-	}
-};
 /** The package name every candidate web root must declare to be one. */
 const WEB_PACKAGE_NAME = "@warlock.js/web";
 /**
@@ -120,45 +86,67 @@ async function resolveWebPackageRoot(configured) {
 *
 * `generate` writes the page barrel into `ctx.productionDir` and patches
 * esbuild; `emit` produces the client bundle esbuild cannot. The two share one
-* closure fact — how many pages exist — because a build with zero pages must
-* skip the client bundle rather than emit an orphan one. `generate` itself does
+* closure facts — how many pages exist, the discovered route table, and the
+* exact app-public file list. A build with zero pages skips the hydration
+* bundle but still copies public files when present. `generate` itself does
 * NOT skip: the barrel and its entry import are emitted either way, so the
 * runtime can tell a page-free web build from a build without web.
+*
+* Connector plugins are a separate argument rather than a `WebBuildOptions`
+* field: the app constructs them once, the factory snapshots that array for
+* both dev and build, and this module keeps Vite as a type-only import until
+* `emit` dynamically loads the real client builder.
 */
-function createWebBuildContribution(options = {}) {
+function createWebBuildContribution(options = {}, connectorPlugins = []) {
 	if (options.clientOutDir !== void 0) throw new ClientOutDirNotSupportedError();
 	let pageCount = 0;
+	let pageRoutes = {
+		version: 1,
+		routes: []
+	};
+	let publicFiles = [];
 	return {
 		async generate(context) {
-			const connectorPluginCount = options.connectorPluginCount ?? 0;
-			if (connectorPluginCount > 0) throw new ConnectorPluginsNotSupportedError(connectorPluginCount);
 			const { generatePagesBarrel, WEB_ENTRY_IMPORT, WEB_ESBUILD_PATCH } = await import("./generate-pages-barrel.mjs");
-			pageCount = (await generatePagesBarrel({
+			const { collectPublicFiles } = await import("./public-files.mjs");
+			publicFiles = await collectPublicFiles(path.join(context.appRoot, "public"));
+			const result = await generatePagesBarrel({
 				appRoot: context.appRoot,
 				productionDir: context.productionDir,
 				srcDir: options.srcDir,
-				clientDir: path.relative(context.appRoot, resolveClientOutDir(context)).split(path.sep).join("/")
-			})).pageCount;
+				clientDir: path.relative(context.appRoot, resolveClientOutDir(context)).split(path.sep).join("/"),
+				publicFiles
+			});
+			pageCount = result.pageCount;
+			pageRoutes = result.pageRoutes;
 			return {
 				entryImports: [WEB_ENTRY_IMPORT],
 				esbuild: WEB_ESBUILD_PATCH
 			};
 		},
 		async emit(context) {
-			if (pageCount === 0) return;
-			const { buildWarlockHydrationClient } = await import("../vite/index.mjs");
-			const { appConventionAliases } = await import("../vite/app-convention-aliases.mjs");
-			const callerAliases = Object.entries(options.aliases ?? {}).map(([find, replacement]) => ({
-				find,
-				replacement
-			}));
-			await buildWarlockHydrationClient({
-				appRoot: context.appRoot,
-				webRoot: await resolveWebPackageRoot(options.webRoot),
-				outDir: resolveClientOutDir(context),
-				resolveAliases: [...callerAliases, ...appConventionAliases(path.join(context.appRoot, options.srcDir ?? "src"))],
-				external: options.external
-			});
+			if (pageCount > 0) {
+				const { buildWarlockHydrationClient } = await import("../vite/index.mjs");
+				const { appConventionAliases } = await import("../vite/app-convention-aliases.mjs");
+				const callerAliases = Object.entries(options.aliases ?? {}).map(([find, replacement]) => ({
+					find,
+					replacement
+				}));
+				await buildWarlockHydrationClient({
+					appRoot: context.appRoot,
+					webRoot: await resolveWebPackageRoot(options.webRoot),
+					outDir: resolveClientOutDir(context),
+					resolveAliases: [...callerAliases, ...appConventionAliases(path.join(context.appRoot, options.srcDir ?? "src"))],
+					external: options.external,
+					plugins: connectorPlugins
+				});
+			}
+			if (publicFiles.length > 0) {
+				const { copyPublicFiles } = await import("./public-files.mjs");
+				await copyPublicFiles(path.join(context.appRoot, "public"), path.join(resolveClientOutDir(context), "public"), publicFiles);
+			}
+			const { writePageRoutesManifest } = await import("./page-routes-manifest.mjs");
+			await writePageRoutesManifest(path.resolve(context.appRoot, context.options.outdir), pageRoutes);
 		}
 	};
 }

package/esm/build/contribution.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"contribution.mjs","names":[],"sources":["../../../../../../../web/src/build/contribution.ts"],"sourcesContent":["/**\n * Web's build-time half — the object a `WebConnector` hands to\n * `warlock build` as its `build` contribution.\n *\n * KEPT DELIBERATELY LIGHT: everything this\n * module imports statically is a type or `node:path`. The heavy halves — the\n * filesystem discovery/barrel generator, and the Vite client build — are\n * `await import(...)`ed INSIDE the hooks, so a config file that merely\n * constructs the connector never drags Vite, React or the page graph into its\n * static import graph.\n *\n * {@link WebBuildOptions} carries JSON-SERIALIZABLE VALUES ONLY (constraint\n * B): no plugin instances, no functions, no class instances. Anything heavy is\n * constructed inside a hook after that hook's dynamic import.\n */\nimport { readFileSync } from \"node:fs\";\nimport path from \"node:path\";\nimport type {\n  ConnectorBuildContext,\n  ConnectorBuildContribution,\n  ConnectorBuildGenerateResult,\n} from \"@warlock.js/core\";\n\nexport type WebBuildOptions = {\n  /** Source directory name under the app root. Default: `\"src\"`. */\n  srcDir?: string;\n  /**\n   * Absolute path to the `@warlock.js/web` package root, which holds the\n   * hydration entry (packaged as `esm/hydration/index.mjs`, with a source\n   * fallback at `src/hydration/index.ts` for this checkout).\n   *\n   * Defaults to this module's own package root, derived from `import.meta.url`\n   * at emit time. Set it explicitly when the build process loads this module\n   * through a transform that rewrites `import.meta` (e.g. a CJS config\n   * pipeline) — the derivation is the only thing here that depends on it.\n   *\n   * Derived or configured, the root is VERIFIED at emit time against\n   * `<root>/package.json`'s `name`; a root that is not `@warlock.js/web`\n   * throws {@link WebPackageRootResolutionError} rather than being guessed at.\n   */\n  webRoot?: string;\n  /**\n   * NOT SUPPORTED. The client bundle always lands at `<build.outdir>/client`,\n   * the layout the runtime half reads (`resolveHydrationClientUrl`) — the\n   * runtime does not yet consult a relocated path. Setting this option throws\n   * {@link ClientOutDirNotSupportedError}.\n   */\n  clientOutDir?: string;\n  /** Client-build resolve aliases: specifier -> absolute path. */\n  aliases?: Record<string, string>;\n  /** Extra package names to keep external to the client bundle. */\n  external?: string[];\n  /**\n   * NOT AN APP-FACING OPTION. Set by `webConnector()` from the length of its own\n   * `plugins` array; a COUNT rather than the array itself, because this options\n   * object is JSON-serializable-values-only (constraint B) and a plugin instance\n   * here would drag Vite into every config load.\n   *\n   * Its only consumer is the refusal in `generate` — see\n   * {@link ConnectorPluginsNotSupportedError}.\n   */\n  connectorPluginCount?: number;\n};\n\nfunction resolveClientOutDir(context: ConnectorBuildContext): string {\n  return path.resolve(context.appRoot, context.options.outdir, \"client\");\n}\n\n/**\n * `build.clientOutDir` was set.\n *\n * The production runtime hardcodes where it reads the client bundle from\n * (`<outdir>/client`, via `resolveHydrationClientUrl`) — it does not yet\n * consult the build config for a relocated path. A build that honored a\n * custom `clientOutDir` would therefore produce an artifact the runtime\n * cannot find, silently. Rejected at build start, before any work happens,\n * rather than left to surface later as a missing-bundle failure in\n * production.\n */\nexport class ClientOutDirNotSupportedError extends Error {\n  public constructor() {\n    super(\n      '\"build.clientOutDir\" is not supported: the production server reads the client bundle ' +\n        \"from its default location and does not consult this option, so a build honoring it \" +\n        \"would produce an artifact production cannot serve correctly. Remove \" +\n        '\"build.clientOutDir\" from the build config.',\n    );\n    this.name = \"ClientOutDirNotSupportedError\";\n  }\n}\n\n/**\n * `webConnector({ plugins })` was given plugins, and `warlock build` cannot\n * apply them.\n *\n * THE SILENT FAILURE THIS REPLACES. `plugins` reaches exactly one place: the\n * dev server's `createServer({ plugins: [...] })`. The production client bundle\n * is built by `buildWarlockHydrationClient`, which composes its own pipeline\n * (`web/src/vite/index.ts` — projection and the boundary gates) and is not\n * handed the connector's array by anyone. So a plugin worked in `warlock dev`\n * and was absent from `warlock build`, with no warning and a green build log:\n * the site shipped unstyled, or unprocessed in whatever way the plugin\n * mattered, and the build claimed success. That is worse than any loud failure.\n *\n * WHY REFUSE RATHER THAN WIRE IT THROUGH. Plugin ORDER is part of a pipeline's\n * behavior, and a plugin authored against a dev server can misbehave inside a\n * production build; threading the array in is a change to build behavior that\n * has to be verified, not assumed. Refusing removes the silent failure now and\n * is strictly additive to reverse — wiring the plugins through later breaks no\n * app that this error currently stops, while shipping a half-verified plugin\n * pipeline could break every one of them.\n *\n * The message names the option and says what to do instead, because an error\n * that only says \"no\" costs the reader the same hour it took to find this.\n */\nexport class ConnectorPluginsNotSupportedError extends Error {\n  public constructor(pluginCount: number) {\n    super(\n      `\"plugins\" on the web connector is not supported by \\`warlock build\\`: ` +\n        `webConnector({ plugins }) was given ${pluginCount} plugin${pluginCount === 1 ? \"\" : \"s\"}, ` +\n        \"and they reach the dev server ONLY. The production client bundle is built with the \" +\n        \"framework's own pipeline and would silently ship without them, so this build refuses \" +\n        \"rather than emit an artifact that differs from what you saw in `warlock dev`.\\n\\n\" +\n        \"What to do instead: express the transform somewhere BOTH dev and build already read.\\n\" +\n        \"  - CSS/PostCSS (Tailwind, autoprefixer, ...): put a `postcss.config.mjs` at your app \" +\n        \"root. Vite loads it automatically in dev and in build — this is how Tailwind is \" +\n        \"supported today.\\n\" +\n        \"  - Otherwise: remove `plugins` from webConnector() and open an issue describing what \" +\n        \"the plugin does, so the production pipeline can support it deliberately.\",\n    );\n    this.name = \"ConnectorPluginsNotSupportedError\";\n  }\n}\n\n/** The package name every candidate web root must declare to be one. */\nconst WEB_PACKAGE_NAME = \"@warlock.js/web\";\n\n/**\n * The resolved `@warlock.js/web` root is not that package.\n *\n * Same posture as the manifest resolver's three named errors: a root that\n * cannot be proven is REJECTED, never quietly\n * repaired by walking upwards or falling back to `process.cwd()`. A wrong root\n * would otherwise surface much later as an unintelligible Vite entry failure.\n */\nexport class WebPackageRootResolutionError extends Error {\n  public constructor(webRoot: string, reason: string, cause?: unknown) {\n    super(\n      `Cannot resolve the \"${WEB_PACKAGE_NAME}\" package root: \"${webRoot}\" ${reason}. ` +\n        \"Pass `webRoot` explicitly in the web build options to point at the package root \" +\n        `whose package.json declares \"name\": \"${WEB_PACKAGE_NAME}\".`,\n      { cause },\n    );\n    this.name = \"WebPackageRootResolutionError\";\n  }\n}\n\n/**\n * Proves that `webRoot` really is the `@warlock.js/web` package root by reading\n * `<webRoot>/package.json` and matching its `name`. Returns the path unchanged.\n */\nexport function assertWebPackageRoot(webRoot: string): string {\n  const manifestPath = path.join(webRoot, \"package.json\");\n\n  let raw: string;\n\n  try {\n    raw = readFileSync(manifestPath, \"utf-8\");\n  } catch (error) {\n    throw new WebPackageRootResolutionError(webRoot, \"has no readable package.json\", error);\n  }\n\n  let parsed: unknown;\n\n  try {\n    parsed = JSON.parse(raw);\n  } catch (error) {\n    throw new WebPackageRootResolutionError(\n      webRoot,\n      \"has a package.json that is not valid JSON\",\n      error,\n    );\n  }\n\n  if (typeof parsed !== \"object\" || parsed === null || Array.isArray(parsed)) {\n    throw new WebPackageRootResolutionError(\n      webRoot,\n      \"has a package.json whose root is not a JSON object\",\n    );\n  }\n\n  const name = (parsed as { name?: unknown }).name;\n\n  if (name !== WEB_PACKAGE_NAME) {\n    throw new WebPackageRootResolutionError(\n      webRoot,\n      `declares package name ${JSON.stringify(name)}, not \"${WEB_PACKAGE_NAME}\"`,\n    );\n  }\n\n  return webRoot;\n}\n\nexport async function resolveWebPackageRoot(configured: string | undefined): Promise<string> {\n  if (configured !== undefined) {\n    return assertWebPackageRoot(path.resolve(configured));\n  }\n\n  const { fileURLToPath } = await import(\"node:url\");\n\n  // `web/src/build/contribution.ts` published as `web/esm/build/contribution.js`\n  // — two levels up is the package root under both layouts.\n  return assertWebPackageRoot(\n    path.resolve(path.dirname(fileURLToPath(import.meta.url)), \"..\", \"..\"),\n  );\n}\n\n/**\n * Builds web's `ConnectorBuildContribution`.\n *\n * `generate` writes the page barrel into `ctx.productionDir` and patches\n * esbuild; `emit` produces the client bundle esbuild cannot. The two share one\n * closure fact — how many pages exist — because a build with zero pages must\n * skip the client bundle rather than emit an orphan one. `generate` itself does\n * NOT skip: the barrel and its entry import are emitted either way, so the\n * runtime can tell a page-free web build from a build without web.\n */\nexport function createWebBuildContribution(\n  options: WebBuildOptions = {},\n): ConnectorBuildContribution {\n  if (options.clientOutDir !== undefined) {\n    throw new ClientOutDirNotSupportedError();\n  }\n\n  let pageCount = 0;\n\n  return {\n    async generate(context: ConnectorBuildContext): Promise<ConnectorBuildGenerateResult | void> {\n      // REFUSED HERE, NOT IN THE CONSTRUCTOR ABOVE, and the difference is the\n      // whole of `warlock dev` still working.\n      //\n      // `webConnector()` — and therefore `createWebBuildContribution()` — runs\n      // on every config load, dev included. Throwing at construction the way\n      // `clientOutDir` does would make a connector with dev-only plugins fail\n      // to boot the dev server those plugins exist for. `generate` is the first\n      // hook `warlock build` calls, and nothing but a build calls it: refusing\n      // here fails the build before any barrel is written or any bundle emitted,\n      // and is unreachable from dev.\n      //\n      // Unconditional on page count. `emit` skips the client bundle when the app\n      // has zero pages, but \"your plugins will not be applied\" is true either\n      // way, and a refusal that depends on how many pages you happen to have is\n      // a worse contract than one that does not.\n      const connectorPluginCount = options.connectorPluginCount ?? 0;\n\n      if (connectorPluginCount > 0) {\n        throw new ConnectorPluginsNotSupportedError(connectorPluginCount);\n      }\n\n      const { generatePagesBarrel, WEB_ENTRY_IMPORT, WEB_ESBUILD_PATCH } = await import(\n        \"./generate-pages-barrel\"\n      );\n\n      const result = await generatePagesBarrel({\n        appRoot: context.appRoot,\n        productionDir: context.productionDir,\n        srcDir: options.srcDir,\n        // Derived from `resolveClientOutDir` — the SAME function `emit` passes\n        // to the Vite build below — so the path baked into the manifest and\n        // the path the bundle is written to are one expression, not two that\n        // happen to agree today.\n        // POSIX-normalised inline rather than via the generator's `toPosix`:\n        // this module's static graph is `node:path` and types only, and the\n        // generator is reached by `await import` precisely to keep it that way.\n        clientDir: path\n          .relative(context.appRoot, resolveClientOutDir(context))\n          .split(path.sep)\n          .join(\"/\"),\n      });\n\n      pageCount = result.pageCount;\n\n      // Contributed unconditionally, zero pages included: the barrel is always\n      // written, and the entry has to IMPORT it for the empty table to reach\n      // the runtime. Withholding this line on zero pages would leave the\n      // manifest absent, which is the runtime's signal for \"never built with\n      // web\" — the exact confusion the always-written barrel removes.\n      return { entryImports: [WEB_ENTRY_IMPORT], esbuild: WEB_ESBUILD_PATCH };\n    },\n\n    async emit(context: ConnectorBuildContext): Promise<void> {\n      if (pageCount === 0) {\n        return;\n      }\n\n      const { buildWarlockHydrationClient } = await import(\"../vite\");\n      const { appConventionAliases } = await import(\"../vite/app-convention-aliases\");\n\n      // The app-tree convention (`web/*`, `app/*`) the dev server installs must\n      // also reach the production build, from the SAME definition — see\n      // `app-convention-aliases.ts`. Caller-supplied aliases come first so a\n      // caller can win a conflict, matching the dev server's ordering.\n      const callerAliases = Object.entries(options.aliases ?? {}).map(([find, replacement]) => ({\n        find,\n        replacement,\n      }));\n\n      await buildWarlockHydrationClient({\n        appRoot: context.appRoot,\n        webRoot: await resolveWebPackageRoot(options.webRoot),\n        outDir: resolveClientOutDir(context),\n        resolveAliases: [\n          ...callerAliases,\n          ...appConventionAliases(path.join(context.appRoot, options.srcDir ?? \"src\")),\n        ],\n        external: options.external,\n      });\n    },\n  };\n}\n"],"mappings":"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"}
+{"version":3,"file":"contribution.mjs","names":[],"sources":["C:/Work/Warlock.js/web/src/build/contribution.ts"],"sourcesContent":["/**\r\n * Web's build-time half — the object a `WebConnector` hands to\r\n * `warlock build` as its `build` contribution.\r\n *\r\n * KEPT DELIBERATELY LIGHT: everything this\r\n * module imports statically is a type or `node:path`. The heavy halves — the\r\n * filesystem discovery/barrel generator, and the Vite client build — are\r\n * `await import(...)`ed INSIDE the hooks, so a config file that merely\r\n * constructs the connector never drags Vite, React or the page graph into its\r\n * static import graph.\r\n *\r\n * {@link WebBuildOptions} carries JSON-SERIALIZABLE VALUES ONLY (constraint\r\n * B): no plugin instances, no functions, no class instances. Anything heavy is\r\n * constructed inside a hook after that hook's dynamic import.\r\n */\r\nimport { readFileSync } from \"node:fs\";\r\nimport path from \"node:path\";\r\nimport type {\r\n  ConnectorBuildContext,\r\n  ConnectorBuildContribution,\r\n  ConnectorBuildGenerateResult,\r\n} from \"@warlock.js/core\";\r\nimport type { PluginOption } from \"vite\";\r\n\r\nexport type WebBuildOptions = {\r\n  /** Source directory name under the app root. Default: `\"src\"`. */\r\n  srcDir?: string;\r\n  /**\r\n   * Absolute path to the `@warlock.js/web` package root, which holds the\r\n   * hydration entry (packaged as `esm/hydration/index.mjs`, with a source\r\n   * fallback at `src/hydration/index.ts` for this checkout).\r\n   *\r\n   * Defaults to this module's own package root, derived from `import.meta.url`\r\n   * at emit time. Set it explicitly when the build process loads this module\r\n   * through a transform that rewrites `import.meta` (e.g. a CJS config\r\n   * pipeline) — the derivation is the only thing here that depends on it.\r\n   *\r\n   * Derived or configured, the root is VERIFIED at emit time against\r\n   * `<root>/package.json`'s `name`; a root that is not `@warlock.js/web`\r\n   * throws {@link WebPackageRootResolutionError} rather than being guessed at.\r\n   */\r\n  webRoot?: string;\r\n  /**\r\n   * NOT SUPPORTED. The client bundle always lands at `<build.outdir>/client`,\r\n   * the layout the runtime half reads (`resolveHydrationClientUrl`) — the\r\n   * runtime does not yet consult a relocated path. Setting this option throws\r\n   * {@link ClientOutDirNotSupportedError}.\r\n   */\r\n  clientOutDir?: string;\r\n  /** Client-build resolve aliases: specifier -> absolute path. */\r\n  aliases?: Record<string, string>;\r\n  /** Extra package names to keep external to the client bundle. */\r\n  external?: string[];\r\n};\r\n\r\nfunction resolveClientOutDir(context: ConnectorBuildContext): string {\r\n  return path.resolve(context.appRoot, context.options.outdir, \"client\");\r\n}\r\n\r\n/**\r\n * `build.clientOutDir` was set.\r\n *\r\n * The production runtime hardcodes where it reads the client bundle from\r\n * (`<outdir>/client`, via `resolveHydrationClientUrl`) — it does not yet\r\n * consult the build config for a relocated path. A build that honored a\r\n * custom `clientOutDir` would therefore produce an artifact the runtime\r\n * cannot find, silently. Rejected at build start, before any work happens,\r\n * rather than left to surface later as a missing-bundle failure in\r\n * production.\r\n */\r\nexport class ClientOutDirNotSupportedError extends Error {\r\n  public constructor() {\r\n    super(\r\n      '\"build.clientOutDir\" is not supported: the production server reads the client bundle ' +\r\n        \"from its default location and does not consult this option, so a build honoring it \" +\r\n        \"would produce an artifact production cannot serve correctly. Remove \" +\r\n        '\"build.clientOutDir\" from the build config.',\r\n    );\r\n    this.name = \"ClientOutDirNotSupportedError\";\r\n  }\r\n}\r\n\r\n/** The package name every candidate web root must declare to be one. */\r\nconst WEB_PACKAGE_NAME = \"@warlock.js/web\";\r\n\r\n/**\r\n * The resolved `@warlock.js/web` root is not that package.\r\n *\r\n * Same posture as the manifest resolver's three named errors: a root that\r\n * cannot be proven is REJECTED, never quietly\r\n * repaired by walking upwards or falling back to `process.cwd()`. A wrong root\r\n * would otherwise surface much later as an unintelligible Vite entry failure.\r\n */\r\nexport class WebPackageRootResolutionError extends Error {\r\n  public constructor(webRoot: string, reason: string, cause?: unknown) {\r\n    super(\r\n      `Cannot resolve the \"${WEB_PACKAGE_NAME}\" package root: \"${webRoot}\" ${reason}. ` +\r\n        \"Pass `webRoot` explicitly in the web build options to point at the package root \" +\r\n        `whose package.json declares \"name\": \"${WEB_PACKAGE_NAME}\".`,\r\n      { cause },\r\n    );\r\n    this.name = \"WebPackageRootResolutionError\";\r\n  }\r\n}\r\n\r\n/**\r\n * Proves that `webRoot` really is the `@warlock.js/web` package root by reading\r\n * `<webRoot>/package.json` and matching its `name`. Returns the path unchanged.\r\n */\r\nexport function assertWebPackageRoot(webRoot: string): string {\r\n  const manifestPath = path.join(webRoot, \"package.json\");\r\n\r\n  let raw: string;\r\n\r\n  try {\r\n    raw = readFileSync(manifestPath, \"utf-8\");\r\n  } catch (error) {\r\n    throw new WebPackageRootResolutionError(webRoot, \"has no readable package.json\", error);\r\n  }\r\n\r\n  let parsed: unknown;\r\n\r\n  try {\r\n    parsed = JSON.parse(raw);\r\n  } catch (error) {\r\n    throw new WebPackageRootResolutionError(\r\n      webRoot,\r\n      \"has a package.json that is not valid JSON\",\r\n      error,\r\n    );\r\n  }\r\n\r\n  if (typeof parsed !== \"object\" || parsed === null || Array.isArray(parsed)) {\r\n    throw new WebPackageRootResolutionError(\r\n      webRoot,\r\n      \"has a package.json whose root is not a JSON object\",\r\n    );\r\n  }\r\n\r\n  const name = (parsed as { name?: unknown }).name;\r\n\r\n  if (name !== WEB_PACKAGE_NAME) {\r\n    throw new WebPackageRootResolutionError(\r\n      webRoot,\r\n      `declares package name ${JSON.stringify(name)}, not \"${WEB_PACKAGE_NAME}\"`,\r\n    );\r\n  }\r\n\r\n  return webRoot;\r\n}\r\n\r\nexport async function resolveWebPackageRoot(configured: string | undefined): Promise<string> {\r\n  if (configured !== undefined) {\r\n    return assertWebPackageRoot(path.resolve(configured));\r\n  }\r\n\r\n  const { fileURLToPath } = await import(\"node:url\");\r\n\r\n  // `web/src/build/contribution.ts` published as `web/esm/build/contribution.js`\r\n  // — two levels up is the package root under both layouts.\r\n  return assertWebPackageRoot(\r\n    path.resolve(path.dirname(fileURLToPath(import.meta.url)), \"..\", \"..\"),\r\n  );\r\n}\r\n\r\n/**\r\n * Builds web's `ConnectorBuildContribution`.\r\n *\r\n * `generate` writes the page barrel into `ctx.productionDir` and patches\r\n * esbuild; `emit` produces the client bundle esbuild cannot. The two share one\r\n * closure facts — how many pages exist, the discovered route table, and the\n * exact app-public file list. A build with zero pages skips the hydration\n * bundle but still copies public files when present. `generate` itself does\n * NOT skip: the barrel and its entry import are emitted either way, so the\n * runtime can tell a page-free web build from a build without web.\n *\r\n * Connector plugins are a separate argument rather than a `WebBuildOptions`\r\n * field: the app constructs them once, the factory snapshots that array for\r\n * both dev and build, and this module keeps Vite as a type-only import until\r\n * `emit` dynamically loads the real client builder.\r\n */\r\nexport function createWebBuildContribution(\r\n  options: WebBuildOptions = {},\r\n  connectorPlugins: readonly PluginOption[] = [],\r\n): ConnectorBuildContribution {\r\n  if (options.clientOutDir !== undefined) {\r\n    throw new ClientOutDirNotSupportedError();\r\n  }\r\n\r\n  let pageCount = 0;\r\n  let pageRoutes: import(\"./generate-pages-barrel\").PageRoutesManifest = {\n    version: 1,\n    routes: [],\n  };\n  let publicFiles: string[] = [];\n\r\n  return {\r\n    async generate(context: ConnectorBuildContext): Promise<ConnectorBuildGenerateResult | void> {\r\n      const { generatePagesBarrel, WEB_ENTRY_IMPORT, WEB_ESBUILD_PATCH } =\n        await import(\"./generate-pages-barrel\");\n      const { collectPublicFiles } = await import(\"./public-files\");\n\n      publicFiles = await collectPublicFiles(path.join(context.appRoot, \"public\"));\n\n      const result = await generatePagesBarrel({\n        appRoot: context.appRoot,\r\n        productionDir: context.productionDir,\r\n        srcDir: options.srcDir,\r\n        // Derived from `resolveClientOutDir` — the SAME function `emit` passes\r\n        // to the Vite build below — so the path baked into the manifest and\r\n        // the path the bundle is written to are one expression, not two that\r\n        // happen to agree today.\r\n        // POSIX-normalised inline rather than via the generator's `toPosix`:\r\n        // this module's static graph is `node:path` and types only, and the\r\n        // generator is reached by `await import` precisely to keep it that way.\r\n        clientDir: path\r\n          .relative(context.appRoot, resolveClientOutDir(context))\r\n          .split(path.sep)\n          .join(\"/\"),\n        publicFiles,\n      });\n\r\n      pageCount = result.pageCount;\r\n      pageRoutes = result.pageRoutes;\r\n\r\n      // Contributed unconditionally, zero pages included: the barrel is always\r\n      // written, and the entry has to IMPORT it for the empty table to reach\r\n      // the runtime. Withholding this line on zero pages would leave the\r\n      // manifest absent, which is the runtime's signal for \"never built with\r\n      // web\" — the exact confusion the always-written barrel removes.\r\n      return { entryImports: [WEB_ENTRY_IMPORT], esbuild: WEB_ESBUILD_PATCH };\r\n    },\r\n\r\n    async emit(context: ConnectorBuildContext): Promise<void> {\r\n      if (pageCount > 0) {\n        const { buildWarlockHydrationClient } = await import(\"../vite\");\r\n        const { appConventionAliases } = await import(\"../vite/app-convention-aliases\");\r\n\r\n        // The app-tree convention (`web/*`, `app/*`) the dev server installs must\r\n        // also reach the production build, from the SAME definition — see\r\n        // `app-convention-aliases.ts`. Caller-supplied aliases come first so a\r\n        // caller can win a conflict, matching the dev server's ordering.\r\n        const callerAliases = Object.entries(options.aliases ?? {}).map(([find, replacement]) => ({\r\n          find,\r\n          replacement,\r\n        }));\r\n\r\n        await buildWarlockHydrationClient({\r\n          appRoot: context.appRoot,\r\n          webRoot: await resolveWebPackageRoot(options.webRoot),\r\n          outDir: resolveClientOutDir(context),\r\n          resolveAliases: [\r\n            ...callerAliases,\r\n            ...appConventionAliases(path.join(context.appRoot, options.srcDir ?? \"src\")),\r\n          ],\r\n          external: options.external,\r\n          plugins: connectorPlugins,\r\n        });\n      }\n\n      if (publicFiles.length > 0) {\n        const { copyPublicFiles } = await import(\"./public-files\");\n        await copyPublicFiles(\n          path.join(context.appRoot, \"public\"),\n          path.join(resolveClientOutDir(context), \"public\"),\n          publicFiles,\n        );\n      }\n\n      const { writePageRoutesManifest } = await import(\"./page-routes-manifest\");\n      await writePageRoutesManifest(\r\n        path.resolve(context.appRoot, context.options.outdir),\r\n        pageRoutes,\r\n      );\r\n    },\r\n  };\r\n}\r\n"],"mappings":"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"}