@warlock.js/web 5.0.2 → 5.1.0

package/CHANGELOG.md

@@ -2,6 +2,82 @@
 
 All notable changes to `@warlock.js/web` are documented here.
 
+## 5.1.0
+
+> **Upgrade if you installed 5.0.0, 5.0.1 or 5.0.2.** React did not execute at all in
+> a published install of any of them — see the first entry under *Fixed*. Every
+> interactive page shipped on those versions was inert in the browser.
+
+### Added
+
+- **`404.page.tsx`** — an app-owned not-found page. It renders only when `text/html`
+  is explicitly present in the request's `Accept` header, so an unmatched `/api/...`
+  path still returns the JSON 404 an API client expects rather than a document. It
+  renders with no layouts: discovery reports an empty layout chain for this page only,
+  so the client hydration registry matches what the server has always rendered instead
+  of wrapping a failure page in chrome that can itself throw or need data. Ordinary
+  pages beside it keep their full layout chain, and nested-layout refusal on its path
+  is unchanged.
+- **`export const metadata` is typed (`PageMetadata`) and checked at build time.** An
+  unannotated object literal with a misspelled key — `{ tittle: "x" }` — now fails the
+  build, naming the file, the line and the offending key. It previously typechecked as
+  a plain object and was silently ignored at runtime.
+- **Fast Refresh in dev now applies only when an edit is confined to component
+  bodies.** Any module-level change — an import, a module-level declaration, or any
+  server export, `metadata` included — forces a full page reload instead of a stale hot
+  update; a JSX-only edit still hot-updates in place with component state intact.
+
+### Changed
+
+- **`warlock dev` now refuses a `*.page.tsx` that exports no route**, throwing
+  `MissingRouteExportError` and naming the file. It previously 404'd silently, so a
+  missing `export const route` looked like a routing bug at request time. This matches
+  what `warlock build` already did — dev and build now reject the same file.
+
+### Removed
+
+- **A false comment shipped in 5.0.0 through 5.0.2** claiming that a page's route is
+  derived from its file location. No such derivation has ever existed in this package;
+  the route comes from the page's `route` export and nothing else. The comment is gone
+  from the scaffold emitted by `warlock add web`, but **every app scaffolded on 5.0.0,
+  5.0.1 or 5.0.2 still carries it in its own source** — delete it by hand.
+
+### Fixed
+
+- **React did not run at all in published installs of 5.0.0 through 5.0.2.** The dev
+  Vite server served `react-dom/client` as raw CJS, so `hydrateRoot` did not exist and
+  the hydration module threw while being parsed. This one defect is the cause of all
+  four symptoms reported against those versions: `useState` never updated, Fast Refresh
+  never ran, metadata never refreshed, and `<Link>` fell back to a full page reload.
+  Fixed by declaring the React entries in the dev server's `optimizeDeps` so they are
+  pre-bundled to ESM before the browser asks for them. This is not a hydration
+  *improvement* — hydration did not happen.
+- **The browser was loading two copies of every `@warlock.js/web` client module.**
+  Module-level state (context, the navigation runtime) existed twice, so a value written
+  through one copy was invisible to the component reading the other.
+
+## 5.0.2 - 2026-08-25
+
+### Fixed
+
+- **`<Head/>` read an empty document context under SSR.** The connector now sets
+  `ssr.noExternal: ["@warlock.js/web"]` in `web-connector.ts`. Without it the server
+  loaded two instances of this package — one externalised, one bundled — so the context
+  the renderer wrote to was not the one `<Head/>` read from. A published 5.0.1 install
+  that returned 500 on a page request returns 200 after this fix.
+
+## 5.0.1 - 2026-08-25
+
+### Changed
+
+- Narrowed the `vite` peer dependency to `">=7.3.5 <8"`, so a consumer resolving vite
+  for this package cannot land on a version outside the range it is built against.
+
+### Fixed
+
+- Internal: a test in `gate-b-secrets.spec.ts` depended on the ambient `NODE_ENV` and
+  failed depending on how the suite was invoked. No runtime behaviour changed.
+
 ## 5.0.0 - 2026-08-25
 
 **First published release.**

package/esm/build/contribution.d.mts

@@ -27,6 +27,16 @@ 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.

package/esm/build/contribution.mjs

@@ -37,6 +37,40 @@ 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";
 /**
@@ -96,6 +130,8 @@ function createWebBuildContribution(options = {}) {
 	let pageCount = 0;
 	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({
 				appRoot: context.appRoot,

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\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/** 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      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":";;;;;;;;;;;;;;;;;;;AAsDA,SAAS,oBAAoB,SAAwC;CACnE,OAAO,KAAK,QAAQ,QAAQ,SAAS,QAAQ,QAAQ,QAAQ,QAAQ;AACvE;;;;;;;;;;;;AAaA,IAAa,gCAAb,cAAmD,MAAM;CACvD,AAAO,cAAc;EACnB,MACE,6RAIF;EACA,KAAK,OAAO;CACd;AACF;;AAGA,MAAM,mBAAmB;;;;;;;;;AAUzB,IAAa,gCAAb,cAAmD,MAAM;CACvD,AAAO,YAAY,SAAiB,QAAgB,OAAiB;EACnE,MACE,uBAAuB,iBAAiB,mBAAmB,QAAQ,IAAI,OAAO,2HAEpC,iBAAiB,KAC3D,EAAE,MAAM,CACV;EACA,KAAK,OAAO;CACd;AACF;;;;;AAMA,SAAgB,qBAAqB,SAAyB;CAC5D,MAAM,eAAe,KAAK,KAAK,SAAS,cAAc;CAEtD,IAAI;CAEJ,IAAI;EACF,MAAM,aAAa,cAAc,OAAO;CAC1C,SAAS,OAAO;EACd,MAAM,IAAI,8BAA8B,SAAS,gCAAgC,KAAK;CACxF;CAEA,IAAI;CAEJ,IAAI;EACF,SAAS,KAAK,MAAM,GAAG;CACzB,SAAS,OAAO;EACd,MAAM,IAAI,8BACR,SACA,6CACA,KACF;CACF;CAEA,IAAI,OAAO,WAAW,YAAY,WAAW,QAAQ,MAAM,QAAQ,MAAM,GACvE,MAAM,IAAI,8BACR,SACA,oDACF;CAGF,MAAM,OAAQ,OAA8B;CAE5C,IAAI,SAAS,kBACX,MAAM,IAAI,8BACR,SACA,yBAAyB,KAAK,UAAU,IAAI,EAAE,SAAS,iBAAiB,EAC1E;CAGF,OAAO;AACT;AAEA,eAAsB,sBAAsB,YAAiD;CAC3F,IAAI,eAAe,QACjB,OAAO,qBAAqB,KAAK,QAAQ,UAAU,CAAC;CAGtD,MAAM,EAAE,kBAAkB,MAAM,OAAO;CAIvC,OAAO,qBACL,KAAK,QAAQ,KAAK,QAAQ,cAAc,OAAO,KAAK,GAAG,CAAC,GAAG,MAAM,IAAI,CACvE;AACF;;;;;;;;;;;AAYA,SAAgB,2BACd,UAA2B,CAAC,GACA;CAC5B,IAAI,QAAQ,iBAAiB,QAC3B,MAAM,IAAI,8BAA8B;CAG1C,IAAI,YAAY;CAEhB,OAAO;EACL,MAAM,SAAS,SAA8E;GAC3F,MAAM,EAAE,qBAAqB,kBAAkB,sBAAsB,MAAM,OACzE;GAoBF,aAAY,MAjBS,oBAAoB;IACvC,SAAS,QAAQ;IACjB,eAAe,QAAQ;IACvB,QAAQ,QAAQ;IAQhB,WAAW,KACR,SAAS,QAAQ,SAAS,oBAAoB,OAAO,CAAC,CAAC,CACvD,MAAM,KAAK,GAAG,CAAC,CACf,KAAK,GAAG;GACb,CAAC,EAEiB,CAAC;GAOnB,OAAO;IAAE,cAAc,CAAC,gBAAgB;IAAG,SAAS;GAAkB;EACxE;EAEA,MAAM,KAAK,SAA+C;GACxD,IAAI,cAAc,GAChB;GAGF,MAAM,EAAE,gCAAgC,MAAM,OAAO;GACrD,MAAM,EAAE,yBAAyB,MAAM,OAAO;GAM9C,MAAM,gBAAgB,OAAO,QAAQ,QAAQ,WAAW,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,kBAAkB;IACxF;IACA;GACF,EAAE;GAEF,MAAM,4BAA4B;IAChC,SAAS,QAAQ;IACjB,SAAS,MAAM,sBAAsB,QAAQ,OAAO;IACpD,QAAQ,oBAAoB,OAAO;IACnC,gBAAgB,CACd,GAAG,eACH,GAAG,qBAAqB,KAAK,KAAK,QAAQ,SAAS,QAAQ,UAAU,KAAK,CAAC,CAC7E;IACA,UAAU,QAAQ;GACpB,CAAC;EACH;CACF;AACF"}
+{"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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"}

package/esm/build/discover-pages.mjs

@@ -1,6 +1,8 @@
 import { composeRoutePath } from "../routing/compose-route-path.mjs";
 import { NestedLayoutsNotSupportedError, selectPageLayout } from "../routing/layout-policy.mjs";
 import { deriveFallbackRouteName } from "../routing/route-identity.mjs";
+import { NOT_FOUND_ROUTE_NAME, NOT_FOUND_ROUTE_PATH, NotFoundPageDeclaresRouteError, isNotFoundPageFile } from "../server/not-found-page.mjs";
+import { METADATA_KEYS, OPEN_GRAPH_KEYS, TWITTER_KEYS } from "../metadata.mjs";
 import { NonLiteralRouteExportError, readRouteExports } from "./read-route-exports.mjs";
 import path from "node:path";
 import fs from "node:fs";
@@ -42,6 +44,10 @@ import { parse } from "@babel/parser";
 * ({@link "../routing/layout-policy.ts"}) owns the rule but may not touch a
 * filesystem to learn the facts the rule needs. That classification is another
 * parse, never an import: a layout is read exactly the way a page's `route` is.
+*
+* And it CHECKS the page's `metadata` keys ({@link UnknownMetadataKeyError}) —
+* see that error and {@link readMetadataKeys} for why a type alone does not
+* close that hole.
 */
 /** Raised when two pages claim one route name. */
 var DuplicatePageRouteNameError = class extends Error {
@@ -183,22 +189,223 @@ function assertUniqueRouteNames(pages, appRoot) {
 var MissingRouteExportError = class extends Error {
 	pageFile;
 	constructor(pageFile) {
-		super(`"${pageFile}" is a page file but declares no \`route\` export. A page with no route is a page the dev server would still serve and production would 404 on, so the build refuses it instead. For example: export const route = "/list";`);
+		super(`"${pageFile}" is a page file but declares no \`route\` export. A page with no route is a page nothing can ever reach, so both the dev server and the build refuse it instead of serving a silent 404. For example: export const route = "/list";`);
 		this.pageFile = pageFile;
 		this.name = "MissingRouteExportError";
 	}
 };
 /**
+* Raised when a page's `metadata` export declares a key nothing reads.
+*
+* THE POINT OF THIS ERROR IS THE UNANNOTATED CASE. A page that writes
+* `export const metadata: PageMetadata = { tittle: "x" }` is already refused by
+* TypeScript, and if that were the whole story this class would not need to
+* exist. But the annotation is optional, nobody writes it, and
+* `export const metadata = { tittle: "x" }` is a perfectly well-typed program:
+* the compiler infers `{ tittle: string }`, has nothing to check it against, and
+* says nothing. The page is then served with no `<title>` — not a wrong title, a
+* missing one — and no error is raised anywhere, at build or at runtime, ever.
+*
+* So the check lives HERE instead, at the gate every page already passes
+* through, where a `route`-less page is refused by name for the same reason: a
+* page that silently does not work is worse than a build that stops and says
+* which line to fix.
+*
+* The alternative considered and rejected was a `defineMetadata({...})` wrapper,
+* which would infer the type for free. It also puts framework ceremony in every
+* page, and a page is meant to be two lines of framework surface (canon
+* `6ea0662f`). The gate gets the same safety without spending that.
+*/
+var UnknownMetadataKeyError = class extends Error {
+	pageFile;
+	unknownKeys;
+	constructor(pageFile, unknownKeys) {
+		const findings = unknownKeys.map(({ container, key, line, suggestion }) => {
+			const where = `line ${line}: \`${container}.${key}\` — no such key.`;
+			return suggestion === void 0 ? where : `${where} Did you mean \`${suggestion}\`?`;
+		}).join("\n  ");
+		super(`The \`metadata\` export of "${pageFile}" declares a key nothing reads:\n  ${findings}\nNothing writes an unknown key to \`<head>\`, so the tag it was meant to produce would simply be absent from every response, with no error at build time or at runtime. The build refuses it here instead.
+  Known keys: ${METADATA_KEYS.join(", ")}.\n  Inside \`openGraph\`: ${OPEN_GRAPH_KEYS.join(", ")}.\n  Inside \`twitter\`: ${TWITTER_KEYS.join(", ")}.\nAnnotating the export — \`export const metadata: PageMetadata = { … }\` — gets you the same list as autocomplete in the editor, before the build runs.`);
+		this.pageFile = pageFile;
+		this.unknownKeys = unknownKeys;
+		this.name = "UnknownMetadataKeyError";
+	}
+};
+/** `as const`, `satisfies`, `!` and parentheses wrap a value without changing it. */
+function unwrapValue(node) {
+	switch (node.type) {
+		case "TSAsExpression":
+		case "TSSatisfiesExpression":
+		case "TSNonNullExpression":
+		case "TypeCastExpression":
+		case "ParenthesizedExpression": return unwrapValue(node.expression);
+		default: return node;
+	}
+}
+/** Levenshtein distance — small strings, so the plain two-row table is the whole cost. */
+function editDistance(left, right) {
+	let previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+	for (let row = 1; row <= left.length; row++) {
+		const current = [row];
+		for (let column = 1; column <= right.length; column++) {
+			const substitution = previous[column - 1] + (left[row - 1] === right[column - 1] ? 0 : 1);
+			current[column] = Math.min(substitution, previous[column] + 1, current[column - 1] + 1);
+		}
+		previous = current;
+	}
+	return previous[right.length];
+}
+/**
+* The known key the written one was probably meant to be.
+*
+* Two edits, because that covers the typos this exists for — `tittle`,
+* `descriptoin`, `keywrods` — without reaching so far that `image` gets
+* suggested for `alt`. Case is ignored first, so `Title` resolves exactly.
+*/
+function suggestKey(written, known) {
+	const lowered = written.toLowerCase();
+	const sameLetters = known.find((candidate) => candidate.toLowerCase() === lowered);
+	if (sameLetters !== void 0) return sameLetters;
+	let best;
+	let bestDistance = Number.POSITIVE_INFINITY;
+	for (const candidate of known) {
+		const distance = editDistance(lowered, candidate.toLowerCase());
+		if (distance < bestDistance) {
+			best = candidate;
+			bestDistance = distance;
+		}
+	}
+	return bestDistance <= 2 ? best : void 0;
+}
+/** The name an object key denotes, or `undefined` when knowing it needs evaluation. */
+function propertyKeyName(property) {
+	if (property.computed) return void 0;
+	const { key } = property;
+	if (key.type === "Identifier") return key.name;
+	if (key.type === "StringLiteral") return key.value;
+}
+/** The nested objects that carry a key set of their own. */
+const NESTED_METADATA_KEYS = {
+	openGraph: OPEN_GRAPH_KEYS,
+	twitter: TWITTER_KEYS
+};
+/**
+* Every unknown key in one metadata object literal, and in the `openGraph` /
+* `twitter` literals inside it.
+*
+* A SPREAD does not suppress the check, unlike the route reader's rule: a
+* spread can only ADD keys, and no value it contributes can make a key written
+* out beside it correct. A COMPUTED key is skipped — its name is not knowable
+* without running the page, and refusing what cannot be read would fail builds
+* that are fine. Both are silence in the narrow places where the parse genuinely
+* does not know, and the annotation is the second net there.
+*/
+function collectUnknownKeys(object, allowed, container, into) {
+	for (const property of object.properties) {
+		if (property.type === "SpreadElement") continue;
+		const key = propertyKeyName(property);
+		if (key === void 0) continue;
+		if (!allowed.includes(key)) {
+			const suggestion = suggestKey(key, allowed);
+			into.push({
+				container,
+				key,
+				line: property.loc?.start.line ?? 0,
+				...suggestion === void 0 ? {} : { suggestion }
+			});
+			continue;
+		}
+		const nested = container === "metadata" ? NESTED_METADATA_KEYS[key] : void 0;
+		if (nested === void 0 || property.type !== "ObjectProperty") continue;
+		const value = unwrapValue(property.value);
+		if (value.type === "ObjectExpression") collectUnknownKeys(value, nested, `${container}.${key}`, into);
+	}
+}
+/**
+* Every object literal a function form RETURNS, without descending into
+* functions nested inside it — a callback's return value is not the metadata.
+*
+* A generic walk rather than a statement-by-statement one because a `return` is
+* legal anywhere a statement is: inside an `if`, a `switch`, a `try`. Enumerating
+* the statement types that may contain one is a list that is wrong the moment
+* the language grows.
+*/
+function collectReturnedObjects(node, into) {
+	if (node === null || typeof node !== "object") return;
+	if (Array.isArray(node)) {
+		for (const item of node) collectReturnedObjects(item, into);
+		return;
+	}
+	const candidate = node;
+	if (candidate.type === "FunctionDeclaration" || candidate.type === "FunctionExpression" || candidate.type === "ArrowFunctionExpression" || candidate.type === "ObjectMethod" || candidate.type === "ClassMethod") return;
+	if (candidate.type === "ReturnStatement") {
+		if (candidate.argument === null || candidate.argument === void 0) return;
+		const returned = unwrapValue(candidate.argument);
+		if (returned.type === "ObjectExpression") into.push(returned);
+		return;
+	}
+	for (const value of Object.values(node)) collectReturnedObjects(value, into);
+}
+/** The metadata object literals one `metadata` export declares, if any can be seen at all. */
+function metadataObjectsOf(init) {
+	const value = unwrapValue(init);
+	if (value.type === "ObjectExpression") return [value];
+	if (value.type === "ArrowFunctionExpression" || value.type === "FunctionExpression") {
+		const body = unwrapValue(value.body);
+		if (body.type === "ObjectExpression") return [body];
+		const returned = [];
+		collectReturnedObjects(value.body, returned);
+		return returned;
+	}
+	return [];
+}
+/**
+* The unknown keys a page's `metadata` export declares, read by PARSING — the
+* same rule the rest of this module lives by, and the reason this check can run
+* before anything is built.
+*
+* Empty for a page with no `metadata` export, for one whose metadata is a value
+* this file cannot see into, and for a correct one.
+*/
+function readMetadataKeys(pageFile, source) {
+	let program;
+	try {
+		program = parse(source, {
+			sourceType: "module",
+			plugins: ["typescript", "jsx"],
+			errorRecovery: false
+		}).program;
+	} catch (error) {
+		throw new Error(`Cannot read the \`metadata\` export of "${pageFile}": the file could not be parsed (${error.message}). Fix the syntax error and the build will continue.`);
+	}
+	const unknownKeys = [];
+	for (const statement of program.body) {
+		if (statement.type !== "ExportNamedDeclaration" || statement.exportKind === "type") continue;
+		const { declaration } = statement;
+		if (declaration?.type !== "VariableDeclaration") continue;
+		for (const declarator of declaration.declarations) {
+			if (declarator.id.type !== "Identifier" || declarator.id.name !== "metadata") continue;
+			if (declarator.init === null || declarator.init === void 0) continue;
+			for (const object of metadataObjectsOf(declarator.init)) collectUnknownKeys(object, METADATA_KEYS, "metadata", unknownKeys);
+		}
+	}
+	return unknownKeys;
+}
+/**
 * The declared exports of one file, or a thrown
 * {@link NonLiteralRouteExportError} when they cannot be read without running
 * the application. Layouts are read once per run and remembered: a layout is
 * the nearest one for every page beside it, and parsing it once per page would
 * be the same answer bought repeatedly.
+*
+* `source` is the file's text when the caller already holds it — the page loop
+* reads each page once and spends that read on both the route declarations and
+* the metadata check, rather than opening the same file twice.
 */
-function readDeclarations(sourceFile, cache) {
+function readDeclarations(sourceFile, cache, source) {
 	let result = cache.get(sourceFile);
 	if (result === void 0) {
-		result = readRouteExports(sourceFile);
+		result = readRouteExports(sourceFile, source);
 		cache.set(sourceFile, result);
 	}
 	if (!result.ok) throw new NonLiteralRouteExportError(result.rejection);
@@ -264,7 +471,9 @@ function readLayoutShape(layoutFile, cache) {
 * to return at all — the alternative is an artefact in which one of them is
 * silently unreachable; a `route` or `prefix` that cannot be read without
 * running the application, which is refused before any page is reported at
-* all; and a page whose layout chain holds more than one RENDERING layout, which
+* all; a `metadata` export declaring a key nothing reads, which no compiler
+* catches unless the page opted into the type and which otherwise serves a page
+* with a silently missing tag; and a page whose layout chain holds more than one RENDERING layout, which
 * the production installer would refuse anyway — discovery refuses it first so
 * that artefact is never produced.
 */
@@ -279,8 +488,13 @@ function discoverPages(options) {
 	const relativeToApp = (file) => toPosix(path.relative(appRoot, file));
 	const pages = [];
 	for (const webRoot of webRoots) for (const pageFile of walkFiles(webRoot, (fileName) => fileName.endsWith(".page.tsx"))) {
-		const { route } = readDeclarations(pageFile, declarations);
-		if (route === void 0) throw new MissingRouteExportError(relativeToApp(pageFile));
+		const pageSource = fs.readFileSync(pageFile, "utf-8");
+		const { route } = readDeclarations(pageFile, declarations, pageSource);
+		const isNotFoundPage = isNotFoundPageFile(pageFile);
+		if (isNotFoundPage && route !== void 0) throw new NotFoundPageDeclaresRouteError(relativeToApp(pageFile));
+		if (route === void 0 && !isNotFoundPage) throw new MissingRouteExportError(relativeToApp(pageFile));
+		const unknownMetadataKeys = readMetadataKeys(relativeToApp(pageFile), pageSource);
+		if (unknownMetadataKeys.length > 0) throw new UnknownMetadataKeyError(relativeToApp(pageFile), unknownMetadataKeys);
 		const layouts = layoutChainFor(pageFile, webRoot);
 		const shapes = layouts.map((layoutFile) => readLayoutShape(layoutFile, layoutShapes));
 		const selection = selectPageLayout(layouts.map((layout, index) => ({
@@ -291,15 +505,15 @@ function discoverPages(options) {
 		const middlewareLayouts = layouts.filter((_, index) => shapes[index].hasMiddleware);
 		const layoutPrefix = layouts.reduce((composed, layoutFile) => composeRoutePath(composed, readDeclarations(layoutFile, declarations).prefix ?? "/"), "/");
 		pages.push({
-			routeName: route.name ?? deriveFallbackRouteName({
-				routePath: route.path,
+			routeName: isNotFoundPage ? NOT_FOUND_ROUTE_NAME : route?.name ?? deriveFallbackRouteName({
+				routePath: route?.path ?? "/",
 				sourceFile: relativeToApp(pageFile)
 			}),
-			routePath: composeRoutePath(layoutPrefix, route.path),
+			routePath: isNotFoundPage ? "*" : composeRoutePath(layoutPrefix, route?.path ?? "/"),
 			pageFile,
 			webRoot,
-			layouts,
-			middlewareLayouts,
+			layouts: isNotFoundPage ? [] : layouts,
+			middlewareLayouts: isNotFoundPage ? [] : middlewareLayouts,
 			...hasAppFile ? { appFile } : {}
 		});
 	}
@@ -309,5 +523,5 @@ function discoverPages(options) {
 }
 
 //#endregion
-export { DuplicatePageRouteNameError, discoverPageFiles, discoverPages, discoverWebRoots, isFile, layoutChainFor, toPosix, walkFiles };
+export { DuplicatePageRouteNameError, MissingRouteExportError, discoverPageFiles, discoverPages, discoverWebRoots, isFile, layoutChainFor, toPosix, walkFiles };
 //# sourceMappingURL=discover-pages.mjs.map