@webjsdev/server 0.8.11 → 0.8.12

package/index.js

@@ -2,6 +2,7 @@ export { startServer, createRequestHandler } from './src/dev.js';
 export { assertNodeVersion, checkNodeVersion, requiredNodeMajor, parseMajor, parseRequiredMajor } from './src/node-version.js';
 export { validateEnv, formatEnvErrors, loadEnvSchema, applyEnvValidation } from './src/env-schema.js';
 export { buildRouteTable, matchPage, matchApi } from './src/router.js';
+export { generateRouteTypes } from './src/route-types.js';
 export { ssrPage, ssrNotFound } from './src/ssr.js';
 export { handleApi } from './src/api.js';
 export {

package/package.json

@@ -1,16 +1,18 @@
 {
   "name": "@webjsdev/server",
-  "version": "0.8.11",
+  "version": "0.8.12",
   "type": "module",
   "description": "webjs dev/prod server: SSR, router, API, server actions, live reload",
   "main": "index.js",
   "exports": {
     ".": "./index.js",
-    "./check": "./src/check.js"
+    "./check": "./src/check.js",
+    "./webjs-config.schema.json": "./webjs-config.schema.json"
   },
   "files": [
     "index.js",
     "src",
+    "webjs-config.schema.json",
     "README.md"
   ],
   "dependencies": {

package/src/actions.js

@@ -9,6 +9,8 @@ import { getSerializer } from './serializer.js';
 import { resolveOrigin } from './cors.js';
 import { readTextBounded, payloadTooLarge, DEFAULT_MAX_BODY_BYTES } from './body-limit.js';
 import { getBodyLimits } from './context.js';
+import { basePath } from './importmap.js';
+import { withBasePath } from './base-path.js';
 
 /**
  * The JSON / RPC body cap in effect for the current request: the per-request
@@ -257,6 +259,12 @@ export async function serveActionStub(idx, absFile) {
   if (typeof mod.default === 'function' && !fnNames.includes('default')) {
     fnNames.push('default');
   }
+  // The RPC endpoint is a framework-emitted same-origin URL, so it must
+  // carry the basePath prefix under a sub-path deploy (#256), exactly like
+  // the importmap targets and the boot module specifiers. Without this the
+  // stub would POST to a bare /__webjs/action/... that the ingress strip
+  // 404s, breaking every server action when webjs.basePath is set.
+  const actionUrl = withBasePath(`/__webjs/action/${hash}/`, basePath());
   const body = `// webjs: generated server-action stub for ${relative(idx.appDir, absFile)}\n` +
     `import { stringify as __wjStringify, parse as __wjParse } from '@webjsdev/core';\n` +
     `function __csrf() {\n` +
@@ -265,7 +273,7 @@ export async function serveActionStub(idx, absFile) {
     `}\n` +
     `async function __rpc(fn, args) {\n` +
     `  const body = await __wjStringify(args);\n` +
-    `  const res = await fetch(${JSON.stringify(`/__webjs/action/${hash}/`)} + fn, {\n` +
+    `  const res = await fetch(${JSON.stringify(actionUrl)} + fn, {\n` +
     `    method: 'POST',\n` +
     `    headers: {\n` +
     `      'content-type': ${JSON.stringify(RPC_CONTENT_TYPE)},\n` +

package/src/base-path.js

@@ -0,0 +1,149 @@
+/**
+ * Sub-path deployment support: `webjs.basePath` (issue #256).
+ *
+ * An app deployed under a sub-path (example.com/app/) behind a proxy that
+ * does NOT strip the prefix is broken without this: every
+ * framework-emitted absolute URL (the importmap targets, the modulepreload
+ * hints, the boot script's `/__webjs/core/*` specifiers and per-route
+ * module URLs, the dev reload `src`) assumes the app sits at the origin
+ * root, so they point at `/__webjs/core/*` instead of
+ * `/app/__webjs/core/*`, module resolution 404s, and the page never
+ * hydrates. `createRequestHandler` explicitly targets embedding, where a
+ * sub-path mount is the norm.
+ *
+ * The model is strip-at-ingress + prefix-on-emit, two seams only:
+ *
+ *   1. STRIP AT INGRESS. At the very start of request handling, when the
+ *      request pathname starts with the basePath, strip it so all
+ *      downstream logic (route matching, the `/__webjs/*` checks, the
+ *      source-file gate, redirects, trailing-slash) sees a ROOT-relative
+ *      path and works UNCHANGED. This single strip is why the rest of the
+ *      framework needs no per-site changes. `stripBasePath` does the path
+ *      computation; `dev.js` rewrites the Request URL with it.
+ *
+ *   2. PREFIX ON EMIT. Every framework-emitted same-origin absolute URL
+ *      (begins with a single `/`) gets the basePath prepended via the one
+ *      `withBasePath` helper. Applied to the importmap targets
+ *      (`importmap.js`), the modulepreload hrefs + boot module specifiers +
+ *      dev reload `src` (`ssr.js`). A cross-origin URL (a `https://` CDN
+ *      vendor target) is absolute and is left untouched.
+ *
+ * Empty basePath (the default) makes both seams pure no-ops, so an
+ * unconfigured app is byte-identical to before this feature. That
+ * invariant is the #1 risk and is guarded differentially in the tests.
+ *
+ * OUT OF SCOPE (a documented follow-up, the same boundary Next draws):
+ * rewriting AUTHOR-written `<a href="/about">` links and client-router
+ * navigation prefixing. This module covers framework-emitted URLs and the
+ * ingress match only.
+ */
+
+/**
+ * Normalize a raw `webjs.basePath` value to the canonical internal form:
+ * either `''` (the no-op default) or a string with exactly one leading
+ * `/` and no trailing `/`. So `'app'`, `'/app'`, and `'/app/'` all map to
+ * `'/app'`, and a nested `'/foo/bar'` is preserved.
+ *
+ * Empty / undefined / non-string / `'/'` all map to `''` (no base path).
+ * A value that cannot be a safe, single-origin path prefix is rejected to
+ * `''`: anything containing `..` (path traversal), a protocol (`://`), a
+ * backslash, whitespace, or a network-path `//host` reference. So a typo
+ * or a hostile value fails safe to "no base path" rather than poisoning
+ * every emitted URL.
+ *
+ * @param {unknown} raw the configured value
+ * @returns {string} `''` or `/segment[/segment...]`
+ */
+export function normalizeBasePath(raw) {
+  if (typeof raw !== 'string') return '';
+  let v = raw.trim();
+  if (v === '' || v === '/') return '';
+  // Reject anything that is not a plain same-origin path prefix.
+  if (v.includes('..')) return '';
+  if (v.includes('://')) return '';
+  if (v.includes('\\')) return '';
+  if (/\s/.test(v)) return '';
+  // Reject a network-path reference (`//host`) BEFORE collapsing leading
+  // slashes: such a value would emit a protocol-relative, cross-origin URL
+  // once prefixed (an open redirect / origin escape), so it fails safe to
+  // "no base path" rather than being collapsed to `/host`.
+  if (v.startsWith('//')) return '';
+  // Ensure exactly one leading slash.
+  v = '/' + v.replace(/^\/+/, '');
+  // Strip any trailing slash(es).
+  v = v.replace(/\/+$/, '');
+  // A leading-slash-only value collapses to '' here (already handled as
+  // '/' above, but guard a value like '//' that slipped a different path).
+  if (v === '' || v === '/') return '';
+  return v;
+}
+
+/**
+ * Read and normalize the `webjs.basePath` config from a parsed
+ * package.json (or any object). Pure; `dev.js` wraps it with the
+ * package.json read like the other `webjs.*` readers.
+ *
+ * @param {unknown} pkg parsed package.json (or any object)
+ * @returns {string} the normalized base path (`''` when unset)
+ */
+export function readBasePath(pkg) {
+  const raw =
+    pkg &&
+    typeof pkg === 'object' &&
+    /** @type {any} */ (pkg).webjs &&
+    /** @type {any} */ (pkg).webjs.basePath;
+  return normalizeBasePath(raw);
+}
+
+/**
+ * Prefix a framework-emitted same-origin absolute URL with the base path.
+ * Returns the URL unchanged when basePath is empty (the no-op default) or
+ * when the URL is not a same-origin absolute path (a cross-origin
+ * `https://` CDN target, a protocol-relative `//host` reference, or a
+ * relative URL), so only the framework's own `/`-rooted paths are moved.
+ *
+ * @param {string} url the URL to (maybe) prefix
+ * @param {string} basePath the normalized base path (`''` = no-op)
+ * @returns {string}
+ */
+export function withBasePath(url, basePath) {
+  if (!basePath) return url;
+  if (typeof url !== 'string') return url;
+  // Only a single-leading-slash same-origin path is prefixed. A
+  // protocol-relative `//host` or an absolute `scheme://` URL is left
+  // alone (a vendor CDN target), as is a relative URL.
+  if (url[0] !== '/' || url[1] === '/') return url;
+  return basePath + url;
+}
+
+/**
+ * Compute the root-relative pathname for an incoming request pathname
+ * under the base path (the ingress strip). Returns:
+ *   - the stripped, root-relative pathname (always begins with `/`) when
+ *     the request is for this app, OR
+ *   - `null` when the request path is NOT under the base path, so the
+ *     caller can 404 it (the request is not for this mounted app).
+ *
+ * Mapping: `<basePath>` and `<basePath>/` both map to the root `/`.
+ * `<basePath>/foo` maps to `/foo`. A path that merely shares a prefix but
+ * is not a real segment boundary (e.g. `/application` under basePath
+ * `/app`) is NOT under the base path and returns null. When basePath is
+ * empty this is a pure pass-through (returns the input unchanged).
+ *
+ * @param {string} pathname the incoming request pathname (begins with `/`)
+ * @param {string} basePath the normalized base path (`''` = no-op)
+ * @returns {string | null}
+ */
+export function stripBasePath(pathname, basePath) {
+  if (!basePath) return pathname;
+  if (pathname === basePath) return '/';
+  const withSlash = basePath + '/';
+  if (pathname.startsWith(withSlash)) {
+    // Slice off the base path; keep the leading slash of the remainder.
+    const rest = pathname.slice(basePath.length);
+    return rest || '/';
+  }
+  // Not under the base path (`/application` vs basePath `/app`, or an
+  // unrelated path): not this app.
+  return null;
+}

package/src/dev.js

@@ -47,6 +47,7 @@ process.emitWarning = function (warning, type, code, ctor) {
 };
 
 import { buildRouteTable, matchPage, matchApi } from './router.js';
+import { generateRouteTypes } from './route-types.js';
 import { ssrPage, ssrNotFound } from './ssr.js';
 import { loadPageAction, runPageAction } from './page-action.js';
 import { handleApi } from './api.js';
@@ -112,9 +113,16 @@ function resolveRequestId(req) {
 function shouldAccessLog(pathname) {
   return !pathname.startsWith('/__webjs/');
 }
-import { setVendorEntries, setCoreInstall, publishBuildId } from './importmap.js';
+import { setVendorEntries, setCoreInstall, publishBuildId, setBasePath, basePath } from './importmap.js';
+import { readBasePath, stripBasePath, withBasePath } from './base-path.js';
 import { urlFromRequest } from './forwarded.js';
 import { compileHeaderRules, applySecurityHeaders, webRequestIsHttps } from './headers.js';
+import {
+  compileRedirectRules,
+  applyRedirects,
+  readTrailingSlashPolicy,
+  applyTrailingSlash,
+} from './redirects.js';
 import { readBodyLimits, computeServerTimeouts } from './body-limit.js';
 import { applyConditionalGet, BUFFERED_MARKER } from './conditional-get.js';
 import { commitHtmlCache } from './html-cache.js';
@@ -261,6 +269,61 @@ export async function readHeaderRules(appDir) {
   }
 }
 
+/**
+ * Read the declarative redirect config (`webjs.redirects`) from the app's
+ * package.json and compile it to URLPattern rules (issue #254). A missing,
+ * malformed, or unreadable config yields an empty rule set (no redirects),
+ * never a throw. Patterns are compiled ONCE here at boot, not per request.
+ *
+ * @param {string} appDir
+ * @returns {Promise<ReturnType<typeof compileRedirectRules>>}
+ */
+export async function readRedirectRules(appDir) {
+  try {
+    const pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'));
+    return compileRedirectRules(pkg);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Read the trailing-slash policy (`webjs.trailingSlash`) from the app's
+ * package.json (issue #255). A missing, malformed, or unreadable config
+ * yields `'ignore'` (no canonicalization), never a throw, so an
+ * unconfigured app is unchanged.
+ *
+ * @param {string} appDir
+ * @returns {Promise<'never' | 'always' | 'ignore'>}
+ */
+export async function readTrailingSlashFromApp(appDir) {
+  try {
+    const pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'));
+    return readTrailingSlashPolicy(pkg);
+  } catch {
+    return 'ignore';
+  }
+}
+
+/**
+ * Read the sub-path base path (`webjs.basePath`) from the app's
+ * package.json (issue #256). A missing, malformed, or unreadable config
+ * yields `''` (root mount), never a throw, so an unconfigured app is
+ * byte-identical to before this feature. Normalized to `''` or
+ * `/segment[/segment...]` by `readBasePath`.
+ *
+ * @param {string} appDir
+ * @returns {Promise<string>}
+ */
+export async function readBasePathFromApp(appDir) {
+  try {
+    const pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'));
+    return readBasePath(pkg);
+  } catch {
+    return '';
+  }
+}
+
 /**
  * Read the CSP config (`webjs.csp`) from the app's package.json and
  * normalize it (issue #233). A missing, malformed, or unreadable config
@@ -380,6 +443,15 @@ export async function createRequestHandler(opts) {
       logger.error?.('[webjs] onError hook threw (ignored)', { err: String(e) });
     }
   }
+  // Sub-path deployment base path (issue #256), read once from the app's
+  // package.json `webjs.basePath` and bound into the importmap builder BEFORE
+  // setCoreInstall / setVendorEntries so every importmap target (and the
+  // recomputed hash) reflects the prefix. Empty (the default) makes both the
+  // ingress strip and the emit-side prefix pure no-ops, so an unconfigured app
+  // is byte-identical to before this feature.
+  const basePathValue = await readBasePathFromApp(appDir);
+  await setBasePath(basePathValue);
+
   const coreDir = locateCoreDir(appDir);
   // Switch the importmap between dist/ bundles and src/ per-file
   // URLs depending on whether the resolved @webjsdev/core install
@@ -446,11 +518,53 @@ export async function createRequestHandler(opts) {
   // Hints, and WebSocket lookups need it available before the first request.
   const routeTable = await buildRouteTable(appDir);
 
+  // Emit `.webjs/routes.d.ts` (typed Route union + per-route params, #258) in
+  // dev so an editor's tsserver always has up-to-date route types without the
+  // developer remembering to run `webjs types`. Best-effort and fire-and-
+  // forget: a failure logs and never blocks boot. Re-emitted after each route
+  // rebuild (see doRebuild) so adding/removing a route refreshes the types.
+  /** @returns {Promise<void>} */
+  async function emitRouteTypes() {
+    try {
+      const { mkdir, writeFile, rename } = await import('node:fs/promises');
+      const text = await generateRouteTypes(appDir);
+      const outDir = join(appDir, '.webjs');
+      await mkdir(outDir, { recursive: true });
+      // Write to a temp sibling then rename, so tsserver (which reads this
+      // file) never observes a half-written body if two rebuilds race. rename
+      // is atomic within the same dir. Both paths sit under the watcher-ignored
+      // .webjs/, so neither the temp write nor the rename re-triggers a rebuild.
+      const dest = join(outDir, 'routes.d.ts');
+      const tmp = join(outDir, `routes.d.ts.${process.pid}.tmp`);
+      await writeFile(tmp, text);
+      await rename(tmp, dest);
+    } catch (e) {
+      logger.warn?.(`[webjs] could not write .webjs/routes.d.ts (route types): ${e?.message || e}`);
+    }
+  }
+  if (dev) void emitRouteTypes();
+
   // Per-path response-header rules (issue #232), read once from the
   // app's package.json `webjs.headers`. Static config, so no rebuild
   // re-read; the secure defaults need no config and apply regardless.
   const headerRules = await readHeaderRules(appDir);
 
+  // Declarative redirect rules (issue #254), read once from the app's
+  // package.json `webjs.redirects` and compiled to URLPattern rules at
+  // boot (never per request). Empty when unconfigured, so an app with no
+  // redirects is unchanged. Applied at the very start of request handling,
+  // before routing / SSR / asset serving, so a moved URL returns a 308/307
+  // immediately.
+  const redirectRules = await readRedirectRules(appDir);
+
+  // Trailing-slash policy (issue #255), read once from the app's package.json
+  // `webjs.trailingSlash`. Default `'ignore'` (no canonicalization), so an
+  // unconfigured app is unchanged; `'never'` (recommended) strips a trailing
+  // slash and `'always'` adds one, each via a 308 to the canonical form.
+  // Applied in produce() AFTER the declarative redirects, so an explicit
+  // redirect rule wins first and the two never loop.
+  const trailingSlashPolicy = await readTrailingSlashFromApp(appDir);
+
   // CSP config (issue #233), read once from the app's package.json
   // `webjs.csp`. OFF by default: when disabled no nonce is minted and no
   // Content-Security-Policy header is set, so an unconfigured app is
@@ -715,6 +829,10 @@ export async function createRequestHandler(opts) {
     // The route table is the only eager artifact (cheap directory scan); rebuild
     // it so routing reflects added/removed route files immediately.
     state.routeTable = await buildRouteTable(appDir);
+    // Refresh the generated route types (#258) so adding/removing a route file
+    // updates `.webjs/routes.d.ts` without a manual `webjs types`. Dev only,
+    // best-effort (see emitRouteTypes).
+    if (dev) void emitRouteTypes();
     clearVendorCache();
     state.tsCache.clear();
     // Invalidate the lazy analysis; the next request rebuilds the graph,
@@ -762,6 +880,19 @@ export async function createRequestHandler(opts) {
 
       let pathname = '/';
       try { pathname = new URL(req.url).pathname; } catch { /* keep default */ }
+      // Sub-path deployment (issue #256): the per-path response-header rules
+      // (`webjs.headers`) author their `source` patterns app-root-relative,
+      // exactly like `webjs.redirects` / `webjs.trailingSlash` (which the
+      // ingress strip in produce() already sees root-relative). So match the
+      // header rules against the STRIPPED path too, keeping the whole config
+      // surface consistent under a base path. `pathname` itself (used for the
+      // access log) stays the RAW path the client hit. No-op when basePath is
+      // empty or the request is not under it.
+      let headerPathname = pathname;
+      if (basePathValue) {
+        const s = stripBasePath(pathname, basePathValue);
+        if (s !== null) headerPathname = s;
+      }
       const startedAt = performance.now();
 
       let res;
@@ -788,7 +919,7 @@ export async function createRequestHandler(opts) {
       // Applied to every served response (documents, assets, the core
       // runtime, probes), since the defaults are universally safe.
       let merged = applySecurityHeaders(res, {
-        pathname,
+        pathname: headerPathname,
         https: webRequestIsHttps(req),
         prod: !dev,
         rules: headerRules,
@@ -826,6 +957,14 @@ export async function createRequestHandler(opts) {
       // stripped here regardless. Best-effort: a store failure is swallowed.
       try {
         const reqUrl = new URL(req.url);
+        // Sub-path deployment (issue #256): the HTML cache READ (in ssrPage)
+        // and `revalidatePath` both key on the app-root-relative path, so key
+        // the WRITE on the stripped path too, or a cached page would never
+        // hit. No-op when basePath is empty / the path is not under it.
+        if (basePathValue) {
+          const s = stripBasePath(reqUrl.pathname, basePathValue);
+          if (s !== null) reqUrl.pathname = s;
+        }
         merged = await commitHtmlCache(req, merged, reqUrl);
       } catch { /* never let the cache write crash the response */ }
 
@@ -847,7 +986,10 @@ export async function createRequestHandler(opts) {
       // duration / requestId (no bodies, no secrets). Suppressed for the
       // framework's own /__webjs/* probe + static traffic so it does not spam.
       // Best-effort: a logger that throws must not take the response down.
-      if (shouldAccessLog(pathname)) {
+      // Use the STRIPPED path for the suppression check (issue #256) so a
+      // framework probe at `<basePath>/__webjs/*` is suppressed just like the
+      // root-mounted `/__webjs/*`. The logged `path` stays the RAW client URL.
+      if (shouldAccessLog(headerPathname)) {
         try {
           logger.info?.('request', {
             requestId: reqId,
@@ -866,6 +1008,69 @@ export async function createRequestHandler(opts) {
   /** @param {Request} req */
   function produce(req) {
     return (async () => {
+      // Sub-path deployment ingress strip (issue #256). When `webjs.basePath`
+      // is set and the request path is under it, STRIP the prefix and rewrite
+      // the Request so EVERYTHING downstream (redirects, trailing-slash, the
+      // probes, the `/__webjs/*` checks, the source-file gate, route matching,
+      // SSR) sees a ROOT-relative path and works UNCHANGED. This single strip
+      // is why the rest of the framework needs no per-site changes. A request
+      // whose path is NOT under the base path is not for this mounted app, so
+      // return a 404 (the safe default for a mounted app). Empty basePath (the
+      // default) is a pure pass-through, so an unconfigured app is unchanged.
+      if (basePathValue) {
+        let reqUrl;
+        try { reqUrl = new URL(req.url); } catch { reqUrl = null; }
+        if (reqUrl) {
+          const stripped = stripBasePath(reqUrl.pathname, basePathValue);
+          if (stripped === null) {
+            // Not under the base path: this request is not for this app.
+            return new Response('Not found', {
+              status: 404,
+              headers: { 'content-type': 'text/plain; charset=utf-8' },
+            });
+          }
+          if (stripped !== reqUrl.pathname) {
+            reqUrl.pathname = stripped;
+            // Rewrite the Request with the stripped URL, preserving method,
+            // headers, and body. `duplex: 'half'` is required by the spec when
+            // a body stream is present on a non-GET/HEAD request.
+            const hasBody = req.method !== 'GET' && req.method !== 'HEAD';
+            req = new Request(
+              reqUrl.toString(),
+              /** @type {any} */ ({
+                method: req.method,
+                headers: req.headers,
+                body: hasBody ? req.body : undefined,
+                duplex: hasBody ? 'half' : undefined,
+                redirect: req.redirect,
+                signal: req.signal,
+              }),
+            );
+          }
+        }
+      }
+
+      // Declarative redirects (issue #254): apply the configured old-path ->
+      // new-path rules at the VERY START of request handling, before the
+      // probes, routing, SSR, or asset serving. A matched source returns a
+      // 308 (permanent, the SEO default) / 307 (temporary) / configured
+      // status immediately, so a moved URL never reaches the router.
+      // `applyRedirects` skips /__webjs/* itself, so the framework probes /
+      // runtime below are never redirected. The secure-header + conditional-GET
+      // funnel in handle() still wraps this Response, like any other.
+      const redirectResp = applyRedirects(req, redirectRules);
+      if (redirectResp) return redirectResp;
+
+      // Trailing-slash canonicalization (issue #255): after the explicit
+      // redirects above (so an explicit rule wins first and the two never
+      // form a loop), 308-redirect a non-canonical path to the policy's
+      // canonical form (`never` strips a trailing slash, `always` adds one).
+      // Default `'ignore'` is a no-op. The root `/` and file paths are
+      // exempt; `/__webjs/*` is exempt too (defense in depth, the redirects
+      // above already skip it). The funnel in handle() still wraps this.
+      const slashResp = applyTrailingSlash(req, trailingSlashPolicy);
+      if (slashResp) return slashResp;
+
       // Health and readiness probes are answered BEFORE ensureReady so a probe
       // never blocks on the analysis. `/__webjs/health` is liveness (the
       // process is up and accepting connections). `/__webjs/ready` is 503 until
@@ -950,14 +1155,25 @@ export async function createRequestHandler(opts) {
    * BEFORE running SSR: resolves a pathname to its page-route module URLs
    * without loading them. Returns null for non-page paths.
    *
+   * Sub-path deployment (issue #256): the HTTP layer passes the RAW request
+   * pathname (still carrying the base path, since the ingress strip happens
+   * inside `produce`, not here), so strip it for route matching and prefix
+   * the emitted module URLs so the early-hint preloads resolve under the
+   * prefix. A path not under the base path yields null (no hints).
+   *
    * @param {string} pathname
    */
   function routeFor(pathname) {
-    const page = matchPage(state.routeTable, pathname);
+    const matchPathname = basePathValue
+      ? stripBasePath(pathname, basePathValue)
+      : pathname;
+    if (matchPathname === null) return null;
+    const page = matchPage(state.routeTable, matchPathname);
     if (!page) return null;
     const moduleUrls = [page.route.file, ...page.route.layouts].map((f) => {
       let rel = f.startsWith(appDir) ? f.slice(appDir.length) : f;
-      return rel.split('\\').join('/').replace(/^\/?/, '/');
+      const url = rel.split('\\').join('/').replace(/^\/?/, '/');
+      return withBasePath(url, basePathValue);
     });
     return { moduleUrls };
   }
@@ -997,6 +1213,25 @@ export async function createRequestHandler(opts) {
  * etc.) sitting in front of this process. See the deployment docs for
  * the recommended topology.
  *
+/**
+ * Paths under the app root whose changes must NOT trigger a dev rebuild.
+ * `node_modules` / `.git` are noise. `.webjs/` is the framework's generated
+ * artefact dir (the #258 routes.d.ts and the vendor pin) that the dev server
+ * itself writes on startup and on every rebuild, so without this skip the
+ * write fires a watch event, triggers a rebuild, re-writes the file, and loops
+ * forever. `prisma/dev*` / `prisma/migrations` churn during db:migrate. The
+ * prisma branch is prefix-only (no trailing separator) so the SQLite sidecars
+ * `prisma/dev.db` / `prisma/dev.db-journal` match too; the others stay
+ * separator-anchored so an unrelated name like `node_modules.bak/foo` does not.
+ *
+ * @param {string} filename relative path from an fs.watch `event.filename`
+ * @returns {boolean} true when the change should be ignored
+ */
+export function shouldIgnoreWatchPath(filename) {
+  return /(?:^|[\\/])(?:node_modules|\.git|\.webjs)(?:[\\/]|$)|(?:^|[\\/])prisma[\\/](?:dev|migrations)/.test(filename || '');
+}
+
+/**
  * @param {{
  *   appDir: string,
  *   port?: number,
@@ -1032,18 +1267,9 @@ export async function startServer(opts) {
     // `fs.promises.watch`. Stable on macOS, Windows, and Linux as of
     // Node 24. No external dep needed.
     //
-    // fs.watch returns relative paths in event.filename. We apply
-    // the same ignore filter chokidar used before: skip
-    // node_modules, .git, and prisma's dev artefacts (dev.db,
-    // dev.db-journal, migrations/) which the dev server writes
-    // during db:migrate and would otherwise loop.
-    //
-    // The prisma branch uses prefix-only matching (no required
-    // trailing separator) so the SQLite sidecar files like
-    // `prisma/dev.db` and `prisma/dev.db-journal` are ignored too.
-    // node_modules / .git stay separator-anchored so unrelated
-    // names like `node_modules.bak/foo` don't get caught.
-    const IGNORE = /(?:^|[\\/])(?:node_modules|\.git)(?:[\\/]|$)|(?:^|[\\/])prisma[\\/](?:dev|migrations)/;
+    // fs.watch returns relative paths in event.filename. `shouldIgnoreWatchPath`
+    // (module-level, exported for tests) skips node_modules, .git, .webjs/, and
+    // prisma's dev artefacts so a file the dev server itself writes never loops.
     const rebuild = debounce(() => app.rebuild(), 80);
     watcherAbort = new AbortController();
     (async () => {
@@ -1051,7 +1277,7 @@ export async function startServer(opts) {
         const events = fsWatch(app.appDir, { recursive: true, signal: watcherAbort.signal });
         for await (const event of events) {
           const filename = event.filename || '';
-          if (IGNORE.test(filename)) continue;
+          if (shouldIgnoreWatchPath(filename)) continue;
           rebuild();
         }
       } catch (err) {
@@ -1075,8 +1301,11 @@ export async function startServer(opts) {
     try {
       const url = urlFromRequest(req);
 
-      // SSE: handled specially; doesn't fit the req→Response model.
-      if (url.pathname === '/__webjs/events') {
+      // SSE: handled specially; doesn't fit the req→Response model. Match the
+      // base-path-stripped pathname so the reload stream answers at
+      // `<basePath>/__webjs/events` under a sub-path deploy (#256). With no
+      // basePath this is a pure pass-through (the bare path still matches).
+      if (stripBasePath(url.pathname, basePath()) === '/__webjs/events') {
         if (!dev) { res.writeHead(404); res.end(); return; }
         res.writeHead(200, {
           'content-type': 'text/event-stream',
@@ -1195,7 +1424,7 @@ async function tryServeFrameworkStatic(path, method, ctx) {
   // Dev live-reload client.
   if (path === '/__webjs/reload.js') {
     if (!dev) return new Response('Not found', { status: 404 });
-    return new Response(RELOAD_CLIENT_JS, {
+    return new Response(reloadClientJs(basePath()), {
       headers: { 'content-type': 'application/javascript; charset=utf-8' },
     });
   }
@@ -2012,7 +2241,17 @@ function locatePackageDir(appDir, pkgName) {
   return null;
 }
 
-const RELOAD_CLIENT_JS = `// webjs dev reload client
-const es = new EventSource('/__webjs/events');
+/**
+ * The dev live-reload client. The `EventSource` URL is a framework-emitted
+ * same-origin path, so it must carry the base path under a sub-path deploy
+ * (#256), like the importmap targets and the RPC stub. No-op when basePath
+ * is empty.
+ * @param {string} bp the normalized base path (`''` = no-op)
+ * @returns {string}
+ */
+function reloadClientJs(bp) {
+  return `// webjs dev reload client
+const es = new EventSource(${JSON.stringify(withBasePath('/__webjs/events', bp))});
 es.addEventListener('reload', () => location.reload());
 `;
+}