@warlock.js/web 5.5.0 → 5.7.0

package/CHANGELOG.md

@@ -2,6 +2,55 @@
 
 All notable changes to `@warlock.js/web` are documented here.
 
+## 5.7.0 - 2026-09-11
+
+### Removed
+
+- **`route.validate` and `route.middleware` are withdrawn, one release after 5.6.0 added them.** They were a second way to say what the top-level `validation` and `middleware` exports already said, on the same file — and the two validation surfaces disagreed about the status code. **Migration is a move, not a rewrite:** the schema shape is unchanged (`params` and `query` stay separate, never merged) and the failure is still 400.
+
+  ```diff
+  - export const route = { path: "/products/:id", validate: v.object({ … }), middleware: [guard] } as const;
+  + export const route = { path: "/products/:id" } as const;
+  + export const validation = { params: v.object({ … }), query: v.object({ … }) };
+  + export const middleware = [guard];
+  ```
+
+  **A page still declaring either one refuses to boot and names the file.** It is never silently ignored — which for `route.middleware` is the difference between a deploy that fails and a route that serves without its auth guard.
+
+### Fixed
+
+- **Dev and production agree about stylesheets.** A stylesheet reached only through a component import was collected by production's bundler-graph walk and was structurally invisible to dev's scan of the page file — so a page rendered unstyled in development and correct in production. Both sides now end in one traversal, gated by a fixture built through **both** pipelines with the outputs diffed.
+- **A client navigation whose data payload is incomplete now loads the page normally instead of rendering it blank.** Navigation carried its own copy of the payload rule and checked two of the six required keys, so a payload that could not render a page was accepted and handed to React anyway; the failure surfaced later, somewhere else, pointing at nothing. It now falls back to a full page load — slower for that one click, and the page arrives.
+- **The dev server no longer says it is watching for changes while it is not yet serving.** On a slow boot that line arrived up to three minutes before the port was bound; every word of it was true and the impression it left was false.
+- **The `create-a-page` skill and `llms-full.txt` taught `route.validate` and `route.middleware`** — with a complete worked example — after both were withdrawn. Following our own documentation produced an app that would not start.
+
+### Changed
+
+- The dev and production page installers now agree on the layout **chain**, the layout **level**, and the hydration entry URL by construction rather than by inspection, each gated with a red control. The three places they still differ — live `public/` serving, its cache header, and hashed-asset caching — are deliberate and are now declared in the code that implements them.
+
+## 5.6.0 - 2026-09-08
+### Added
+
+- **A page can declare its input contract on its `route` export.** The export now accepts an object as well as a string: `{ path, name?, cache?, validate?, middleware? }`. `validate` is a Seal schema over `{ params, query }` — kept separate, never merged — and the validated value reaches the loader typed from the schema. A failure renders the **error page at 400** carrying the failure, and travels the same way over the client-navigation wire. Layout middleware runs outermost-first with the page's own last, so a layout's auth gate cannot be bypassed by a page that declares its own.
+- `useQueryString(key)` — a subscription to one query-string parameter that re-renders on client navigation. Wiring it up exposed that `routerEvents` was only ever fired by `refresh()`: `<Link>` and browser back/forward emitted nothing, so anything subscribed to navigation silently never updated. Navigation now emits its events on every path.
+
+### Fixed
+
+- **Every rendered page returned 500 in `warlock dev`.** The dev server decided the client/server boundary by FILE LOCATION — anything under `src/web/**` was treated as inherently client-safe — which contradicts the rule the production build applies and made a server-only import reachable from the client graph. Dev now decides the boundary by the import graph, exactly as production does.
+- **A page route could not be served at all in `warlock dev`.** The handler read the Fastify instance from the container while running inside Vite's SSR module graph, where that lookup can never hit. The instance is now resolved on the Node side and handed in.
+- **Page files were ignored in silence.** A `*.page.tsx` or a layout under `src/app/**/web/**` was discovered by nothing and reported by nothing — an app with seven pages served zero. Discovery now NAMES every file it ignores, at boot, and for a layout it says what was lost: its `prefix`, `middleware` and `loader` apply to no page, so a guard a page relied on is silently absent.
+- **A file added to `public/` after the last build 404'd in production with no diagnostic.** The build-time snapshot is deliberate and stays — but production now names the files its snapshot missed instead of failing them wordlessly.
+- One page that fails to import no longer takes the whole dev boot down with it.
+- Writing to `shared` from the browser failed with a message that read as a fixable wiring bug — "the server bootstrap must call `connectSharedStore(...)`". It now names the value, explains that what the client holds is a dead server-render snapshot that can never be written to, and says what to use instead.
+- The `public/` staleness check runs on every client build rather than only some.
+
+### Changed
+
+- **The dev and production page installers now share their composition rules** — layout-level selection, loader folding, route identity, and the duplicate-route message — instead of implementing them twice. A route collision reported in dev used to quote a dev-only file path in a message production also raises.
+- The published `./vite` subpath is a barrel again: the connector no longer authors Vite plugins, so importing the runtime never drags the build tooling in behind it.
+- Importing the metadata linter no longer pulls 4544 modules and 18 MB into a build-tool module for the sake of one function; it now costs 17 modules.
+- One name for one thing: "runtime" everywhere, `hydration/` renamed to `entry/`, and four files renamed to match what they contain.
+
 ## 5.5.0 - 2026-09-07
 
 ### Fixed
@@ -105,8 +154,7 @@ All notable changes to `@warlock.js/web` are documented here.
 - **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.
+  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
@@ -182,7 +230,7 @@ All notable changes to `@warlock.js/web` are documented here.
   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
+  _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
@@ -234,7 +282,7 @@ 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
+> 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
@@ -280,7 +328,7 @@ All notable changes to `@warlock.js/web` are documented here.
   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.
+  _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.

package/esm/build/contribution.d.mts

@@ -6,8 +6,8 @@ type WebBuildOptions = {
   /** Source directory name under the app root. Default: `"src"`. */srcDir?: string;
   /**
    * Absolute path to the `@warlock.js/web` package root, which holds the
-   * hydration entry (packaged as `esm/hydration/index.mjs`, with a source
-   * fallback at `src/hydration/index.ts` for this checkout).
+   * hydration entry (packaged as `esm/entry/index.mjs`, with a source
+   * fallback at `src/entry/index.ts` for this checkout).
    *
    * Defaults to this module's own package root, derived from `import.meta.url`
    * at emit time. Set it explicitly when the build process loads this module

package/esm/build/contribution.mjs

@@ -1,5 +1,5 @@
-import { readFileSync } from "node:fs";
 import path from "node:path";
+import { readFileSync } from "node:fs";
 
 //#region ../web/src/build/contribution.ts
 /**

package/esm/build/contribution.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"contribution.mjs","names":[],"sources":["../../../../../../../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":";;;;;;;;;;;;;;;;;;;AAuDA,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;;;;;;;;;;;;;;;;;AAkBA,SAAgB,2BACd,UAA2B,CAAC,GAC5B,mBAA4C,CAAC,GACjB;CAC5B,IAAI,QAAQ,iBAAiB,QAC3B,MAAM,IAAI,8BAA8B;CAG1C,IAAI,YAAY;CAChB,IAAI,aAAmE;EACrE,SAAS;EACT,QAAQ,CAAC;CACX;CACA,IAAI,cAAwB,CAAC;CAE7B,OAAO;EACL,MAAM,SAAS,SAA8E;GAC3F,MAAM,EAAE,qBAAqB,kBAAkB,sBAC7C,MAAM,OAAO;GACf,MAAM,EAAE,uBAAuB,MAAM,OAAO;GAE5C,cAAc,MAAM,mBAAmB,KAAK,KAAK,QAAQ,SAAS,QAAQ,CAAC;GAE3E,MAAM,SAAS,MAAM,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;IACX;GACF,CAAC;GAED,YAAY,OAAO;GACnB,aAAa,OAAO;GAOpB,OAAO;IAAE,cAAc,CAAC,gBAAgB;IAAG,SAAS;GAAkB;EACxE;EAEA,MAAM,KAAK,SAA+C;GACxD,IAAI,YAAY,GAAG;IACjB,MAAM,EAAE,gCAAgC,MAAM,OAAO;IACrD,MAAM,EAAE,yBAAyB,MAAM,OAAO;IAM9C,MAAM,gBAAgB,OAAO,QAAQ,QAAQ,WAAW,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,kBAAkB;KACxF;KACA;IACF,EAAE;IAEF,MAAM,4BAA4B;KAChC,SAAS,QAAQ;KACjB,SAAS,MAAM,sBAAsB,QAAQ,OAAO;KACpD,QAAQ,oBAAoB,OAAO;KACnC,gBAAgB,CACd,GAAG,eACH,GAAG,qBAAqB,KAAK,KAAK,QAAQ,SAAS,QAAQ,UAAU,KAAK,CAAC,CAC7E;KACA,UAAU,QAAQ;KAClB,SAAS;IACX,CAAC;GACH;GAEA,IAAI,YAAY,SAAS,GAAG;IAC1B,MAAM,EAAE,oBAAoB,MAAM,OAAO;IACzC,MAAM,gBACJ,KAAK,KAAK,QAAQ,SAAS,QAAQ,GACnC,KAAK,KAAK,oBAAoB,OAAO,GAAG,QAAQ,GAChD,WACF;GACF;GAEA,MAAM,EAAE,4BAA4B,MAAM,OAAO;GACjD,MAAM,wBACJ,KAAK,QAAQ,QAAQ,SAAS,QAAQ,QAAQ,MAAM,GACpD,UACF;EACF;CACF;AACF"}
+{"version":3,"file":"contribution.mjs","names":[],"sources":["../../../../../../../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/entry/index.mjs`, with a source\r\n   * fallback at `src/entry/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\r\n * exact app-public file list. A build with zero pages skips the hydration\r\n * bundle but still copies public files when present. `generate` itself does\r\n * NOT skip: the barrel and its entry import are emitted either way, so the\r\n * runtime can tell a page-free web build from a build without web.\r\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 = {\r\n    version: 1,\r\n    routes: [],\r\n  };\r\n  let publicFiles: string[] = [];\r\n\r\n  return {\r\n    async generate(context: ConnectorBuildContext): Promise<ConnectorBuildGenerateResult | void> {\r\n      const { generatePagesBarrel, WEB_ENTRY_IMPORT, WEB_ESBUILD_PATCH } =\r\n        await import(\"./generate-pages-barrel\");\r\n      const { collectPublicFiles } = await import(\"./public-files\");\r\n\r\n      publicFiles = await collectPublicFiles(path.join(context.appRoot, \"public\"));\r\n\r\n      const result = await generatePagesBarrel({\r\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)\r\n          .join(\"/\"),\r\n        publicFiles,\r\n      });\r\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) {\r\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        });\r\n      }\r\n\r\n      if (publicFiles.length > 0) {\r\n        const { copyPublicFiles } = await import(\"./public-files\");\r\n        await copyPublicFiles(\r\n          path.join(context.appRoot, \"public\"),\r\n          path.join(resolveClientOutDir(context), \"public\"),\r\n          publicFiles,\r\n        );\r\n      }\r\n\r\n      const { writePageRoutesManifest } = await import(\"./page-routes-manifest\");\r\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":";;;;;;;;;;;;;;;;;;;AAuDA,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;;;;;;;;;;;;;;;;;AAkBA,SAAgB,2BACd,UAA2B,CAAC,GAC5B,mBAA4C,CAAC,GACjB;CAC5B,IAAI,QAAQ,iBAAiB,QAC3B,MAAM,IAAI,8BAA8B;CAG1C,IAAI,YAAY;CAChB,IAAI,aAAmE;EACrE,SAAS;EACT,QAAQ,CAAC;CACX;CACA,IAAI,cAAwB,CAAC;CAE7B,OAAO;EACL,MAAM,SAAS,SAA8E;GAC3F,MAAM,EAAE,qBAAqB,kBAAkB,sBAC7C,MAAM,OAAO;GACf,MAAM,EAAE,uBAAuB,MAAM,OAAO;GAE5C,cAAc,MAAM,mBAAmB,KAAK,KAAK,QAAQ,SAAS,QAAQ,CAAC;GAE3E,MAAM,SAAS,MAAM,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;IACX;GACF,CAAC;GAED,YAAY,OAAO;GACnB,aAAa,OAAO;GAOpB,OAAO;IAAE,cAAc,CAAC,gBAAgB;IAAG,SAAS;GAAkB;EACxE;EAEA,MAAM,KAAK,SAA+C;GACxD,IAAI,YAAY,GAAG;IACjB,MAAM,EAAE,gCAAgC,MAAM,OAAO;IACrD,MAAM,EAAE,yBAAyB,MAAM,OAAO;IAM9C,MAAM,gBAAgB,OAAO,QAAQ,QAAQ,WAAW,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,kBAAkB;KACxF;KACA;IACF,EAAE;IAEF,MAAM,4BAA4B;KAChC,SAAS,QAAQ;KACjB,SAAS,MAAM,sBAAsB,QAAQ,OAAO;KACpD,QAAQ,oBAAoB,OAAO;KACnC,gBAAgB,CACd,GAAG,eACH,GAAG,qBAAqB,KAAK,KAAK,QAAQ,SAAS,QAAQ,UAAU,KAAK,CAAC,CAC7E;KACA,UAAU,QAAQ;KAClB,SAAS;IACX,CAAC;GACH;GAEA,IAAI,YAAY,SAAS,GAAG;IAC1B,MAAM,EAAE,oBAAoB,MAAM,OAAO;IACzC,MAAM,gBACJ,KAAK,KAAK,QAAQ,SAAS,QAAQ,GACnC,KAAK,KAAK,oBAAoB,OAAO,GAAG,QAAQ,GAChD,WACF;GACF;GAEA,MAAM,EAAE,4BAA4B,MAAM,OAAO;GACjD,MAAM,wBACJ,KAAK,QAAQ,QAAQ,SAAS,QAAQ,QAAQ,MAAM,GACpD,UACF;EACF;CACF;AACF"}

package/esm/build/discover-pages.mjs

@@ -1,13 +1,14 @@
 import { composeRoutePath } from "../routing/compose-route-path.mjs";
-import { deriveFilesystemRoutePath } from "../routing/filesystem-route.mjs";
+import { NOT_FOUND_ROUTE_NAME, NOT_FOUND_ROUTE_PATH, NotFoundPageDeclaresRouteError, isNotFoundPageFile } from "../server/not-found-page.mjs";
 import { NestedLayoutsNotSupportedError, selectPageLayout } from "../routing/layout-policy.mjs";
+import { deriveFilesystemRoutePath } from "../routing/filesystem-route.mjs";
 import { canonicalizeRouteExport, resolvePageRouteName } 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 { assertPageHasDefaultExport } from "./page-default-export.mjs";
+import { UnknownMetadataKeyError, readMetadataKeys } from "./read-metadata-keys.mjs";
 import { NonLiteralRouteExportError, readRouteExports } from "./read-route-exports.mjs";
-import fs from "node:fs";
+import { toPosix } from "../shared/to-posix.mjs";
 import path from "node:path";
+import fs from "node:fs";
 import { parse } from "@babel/parser";
 
 //#region ../web/src/build/discover-pages.ts
@@ -44,10 +45,6 @@ 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.
 */
 function isDiscoveredRoutablePage(page) {
 	return page.type === "page";
@@ -93,9 +90,6 @@ var DuplicatePageRoutePathError = class extends Error {
 		this.name = "DuplicatePageRoutePathError";
 	}
 };
-function toPosix(value) {
-	return value.replace(/\\/g, "/");
-}
 function isDirectory(candidate) {
 	try {
 		return fs.statSync(candidate).isDirectory();
@@ -122,6 +116,113 @@ function byName(left, right) {
 	return left.name < right.name ? -1 : left.name > right.name ? 1 : 0;
 }
 /**
+* Every directory named exactly `web` beneath `src/app`, at any depth — the
+* shape a page or a named layout takes BEFORE it moves to the one supported
+* page root, {@link discoverWebRoots}. Descent stops at a `web` directory
+* itself: a `web` folder nested inside another is not a shape this codebase
+* uses, so there is nothing further down worth walking.
+*/
+function discoverIgnoredAppWebDirs(srcRoot) {
+	const appDir = path.join(srcRoot, "app");
+	if (!isDirectory(appDir)) return [];
+	const found = [];
+	const walk = (dir) => {
+		for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+			if (!entry.isDirectory()) continue;
+			const full = path.join(dir, entry.name);
+			if (entry.name === "web") found.push(full);
+			else walk(full);
+		}
+	};
+	walk(appDir);
+	return found;
+}
+/**
+* Every `*.page.tsx` and every `layout.tsx` (named or positional) beneath
+* `src/app/**\/web/**`, sorted lexicographically (POSIX) for a stable
+* diagnostic.
+*
+* `src/web` is the only page root (canon `4a6524f3`) — nothing found here is
+* registered, ever. This function exists only to NAME what is being ignored
+* instead of ignoring it in silence; see {@link warnIgnoredAppWebFiles}.
+*
+* A POSITIONAL `layout.tsx` is scanned here deliberately (closes board card
+* `eb82c3c7`): it may declare `middleware`, and a page that loses its layout
+* chain by moving to `src/app/**\/web/**` loses that guard with it, silently —
+* the page still serves, just unprotected. This function does not read
+* whether a given layout actually declares `middleware`; it reports every
+* `layout.tsx` under the ignored tree, because a layout's whole job — prefix,
+* middleware, loader — is lost the moment it is wired to nothing.
+*/
+function discoverIgnoredAppWebFiles(srcRoot) {
+	const found = [];
+	for (const webDir of discoverIgnoredAppWebDirs(srcRoot)) {
+		for (const file of walkFiles(webDir, (fileName) => fileName.endsWith(".page.tsx"))) found.push({
+			file,
+			kind: "page"
+		});
+		for (const file of walkFiles(webDir, (fileName) => fileName.endsWith(".layout.tsx") || fileName === "layout.tsx")) found.push({
+			file,
+			kind: "layout"
+		});
+	}
+	return found.sort((left, right) => compareStrings(toPosix(left.file), toPosix(right.file)));
+}
+/**
+* Files {@link discoverIgnoredAppWebFiles} has already reported once this
+* process — the "once per boot" guard. Keyed by absolute path rather than
+* cleared between calls: {@link discoverPages} runs once per dev reload as
+* well as once per production build, and the point of this set is that the
+* same stray file does not get a fresh warning on every one of those calls
+* within a single boot.
+*/
+const warnedIgnoredAppWebFiles = /* @__PURE__ */ new Set();
+/** Renders one ignored file's path, relative to `appRoot`, POSIX. */
+function namedFile(file, appRoot) {
+	return `  - ${toPosix(path.relative(appRoot, file))}`;
+}
+/**
+* The page half of the diagnostic: a missing page is visible the moment
+* someone loads its URL, so this says only that it is absent from the route
+* graph.
+*/
+function pageIgnoredMessage(files, appRoot) {
+	const plural = files.length === 1 ? "" : "s";
+	const named = files.map((file) => namedFile(file, appRoot)).join("\n");
+	return `${files.length} page file${plural} under src/app/**/web/** ${files.length === 1 ? "is" : "are"} ignored — the only supported page root is src/web/**, so ${files.length === 1 ? "it is" : "they are"} absent from the route graph:\n${named}\nMove ${files.length === 1 ? "it" : "them"} under src/web/** to register ${files.length === 1 ? "it" : "them"}.`;
+}
+/**
+* The layout half of the diagnostic: worded differently from
+* {@link pageIgnoredMessage} on purpose. A missing route guard is not visible
+* at all — the page it would have gated still serves, just unprotected — so
+* this names what is lost (`prefix`, `middleware`, `loader`) rather than
+* merely saying a file was ignored.
+*/
+function layoutIgnoredMessage(files, appRoot) {
+	const plural = files.length === 1 ? "" : "s";
+	const named = files.map((file) => namedFile(file, appRoot)).join("\n");
+	return `${files.length} layout file${plural} under src/app/**/web/** ${files.length === 1 ? "is" : "are"} ignored — the only supported page root is src/web/**, so ${files.length === 1 ? "its" : "their"} \`prefix\`, \`middleware\` and \`loader\` apply to no page at all:\n${named}\nA page that relied on ${files.length === 1 ? "it" : "them"} for a guard — auth, a redirect, anything in \`middleware\` — is served with that guard silently absent. Move ${files.length === 1 ? "it" : "them"} under src/web/** to apply ${files.length === 1 ? "it" : "them"} again.`;
+}
+/**
+* The one place this module writes to the console. Reports every file
+* {@link discoverIgnoredAppWebFiles} found and has not already warned about
+* this boot — never crashes the build, because an application mid-migration
+* off `src/app/**\/web/**` is legitimate, not broken.
+*
+* Pages and layouts are worded separately (see {@link pageIgnoredMessage},
+* {@link layoutIgnoredMessage}) but printed in ONE `console.warn` call, so a
+* boot that has both still prints once.
+*/
+function warnIgnoredAppWebFiles(files, appRoot) {
+	const unwarned = files.filter((entry) => !warnedIgnoredAppWebFiles.has(entry.file));
+	if (unwarned.length === 0) return;
+	for (const entry of unwarned) warnedIgnoredAppWebFiles.add(entry.file);
+	const pages = unwarned.filter((entry) => entry.kind === "page").map((entry) => entry.file);
+	const layouts = unwarned.filter((entry) => entry.kind === "layout").map((entry) => entry.file);
+	const sections = [...pages.length > 0 ? [pageIgnoredMessage(pages, appRoot)] : [], ...layouts.length > 0 ? [layoutIgnoredMessage(layouts, appRoot)] : []];
+	console.warn(sections.map((section) => `[warlock:web] ${section}`).join("\n\n"));
+}
+/**
 * The subject list: every `*.page.tsx` under the page root, one call for the
 * whole graph.
 *
@@ -131,9 +232,19 @@ function byName(left, right) {
 * `ssrLoadModule`-driven installer, chiefly) can share the walk without
 * inheriting the static-parsing refusals that answering "what route is this"
 * requires.
+*
+* ALSO the ignored-`src/app/**\/web/**` diagnostic's boot-path call site: dev's
+* route installer (`../server/install-page-routes.ts`) calls this function,
+* not {@link discoverPages}, so the warning has to fire from here too or a
+* plain `warlock dev` boot never prints it — only a request for a page's
+* hydration bundle would. `appRoot` is derived as this srcRoot's parent, which
+* holds for every real caller: both this function and {@link discoverPages}
+* are only ever handed `<appRoot>/src`.
 */
 function discoverPageFiles(srcRoot) {
 	const found = [];
+	const ignoredAppWebFiles = discoverIgnoredAppWebFiles(srcRoot);
+	if (ignoredAppWebFiles.length > 0) warnIgnoredAppWebFiles(ignoredAppWebFiles, path.dirname(srcRoot));
 	for (const webRoot of discoverWebRoots(srcRoot)) for (const pageFile of walkFiles(webRoot, (fileName) => fileName.endsWith(".page.tsx"))) found.push({
 		pageFile,
 		webRoot
@@ -229,202 +340,6 @@ function assertUniqueRoutePaths(pages, appRoot, explicitFiles) {
 	}
 }
 /**
-* 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: a page that silently omits requested metadata 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
@@ -508,6 +423,11 @@ function readLayoutShape(layoutFile, cache) {
 * 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.
+*
+* It also WARNS — never refuses — when it finds a `*.page.tsx` or named
+* `*.layout.tsx` under `src/app/**\/web/**`, the shape the page root took
+* before it moved to `src/web`. Those files are not registered either way;
+* see {@link discoverIgnoredAppWebFiles}.
 */
 function discoverPages(options) {
 	const { appRoot } = options;
@@ -521,6 +441,8 @@ function discoverPages(options) {
 	const pages = [];
 	const explicitRouteFiles = /* @__PURE__ */ new Set();
 	let errorPage;
+	const ignoredAppWebFiles = discoverIgnoredAppWebFiles(srcRoot);
+	if (ignoredAppWebFiles.length > 0) warnIgnoredAppWebFiles(ignoredAppWebFiles, appRoot);
 	for (const webRoot of webRoots) for (const pageFile of walkFiles(webRoot, (fileName) => fileName.endsWith(".page.tsx"))) {
 		const pageSource = fs.readFileSync(pageFile, "utf-8");
 		assertPageHasDefaultExport(relativeToApp(pageFile), pageSource);
@@ -581,5 +503,5 @@ function discoverPages(options) {
 }
 
 //#endregion
-export { DuplicatePageRouteNameError, ErrorPageDeclaresRouteError, discoverPageFiles, discoverPages, discoverWebRoots, isDiscoveredRoutablePage, isErrorPageFile, isFile, layoutChainFor, toPosix, walkFiles };
+export { ErrorPageDeclaresRouteError, discoverPageFiles, discoverPages, discoverWebRoots, isDiscoveredRoutablePage, isErrorPageFile, isFile, layoutChainFor, walkFiles };
 //# sourceMappingURL=discover-pages.mjs.map