@webjsdev/server 0.8.11 → 0.8.12

package/src/importmap.js

@@ -2,6 +2,7 @@ import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { digestHex } from './crypto-utils.js';
 import { jsonForScriptTag } from './script-tag-json.js';
+import { withBasePath } from './base-path.js';
 
 // Local attribute escaper. Matches ssr.js's escapeAttr (the source
 // of truth for HTML attribute escaping in this package). Kept inline
@@ -26,6 +27,45 @@ function escapeAttr(s) {
 /** @type {Record<string, string>} */
 let _extraEntries = {};
 
+/**
+ * The normalized `webjs.basePath` for a sub-path deployment (issue #256),
+ * `''` (the default) for a root mount. When non-empty, every same-origin
+ * absolute importmap TARGET (the `/__webjs/core/*` core entries and any
+ * same-origin `/__webjs/vendor/*` local vendor target) is prefixed with it
+ * so module resolution works under the prefix. A cross-origin `https://`
+ * CDN vendor target is absolute and is left untouched. Set once at boot by
+ * `setBasePath`, which recomputes the importmap hash so `importMapHash()`
+ * stays synchronous on the hot path.
+ *
+ * @type {string}
+ */
+let _basePath = '';
+
+/**
+ * Bind the importmap to a sub-path deployment's base path (issue #256).
+ * Called once at boot by `dev.js`. With the empty default the map is
+ * byte-identical to a root mount. The importmap hash is recomputed eagerly
+ * (like `setCoreInstall` / `setVendorEntries`) so `importMapHash()` stays
+ * synchronous on the per-request SSR path.
+ *
+ * @param {string} basePath the normalized base path (`''` = root mount)
+ * @returns {Promise<void>}
+ */
+export async function setBasePath(basePath) {
+  _basePath = basePath || '';
+  _importMapHash = await digestHex('SHA-256', JSON.stringify(buildImportMap()));
+}
+
+/**
+ * The active base path, for callers that prefix their own emitted URLs
+ * against the same value (ssr.js's boot specifiers, preloads, reload src).
+ *
+ * @returns {string}
+ */
+export function basePath() {
+  return _basePath;
+}
+
 /**
  * SRI integrity hashes keyed by FINAL URL (post-importmap-rewrite).
  * Populated only when a pin file with `integrity` is present;
@@ -292,7 +332,12 @@ export function buildImportMap() {
   // even though the content didn't actually change.
   /** @type {Record<string, string>} */
   const imports = {};
-  for (const k of Object.keys(merged).sort()) imports[k] = merged[k];
+  // Prefix every same-origin absolute target with the sub-path base
+  // (issue #256). `withBasePath` is a no-op when the base path is empty
+  // (so a root-mounted app's map is byte-identical) and leaves a
+  // cross-origin `https://` CDN vendor target untouched (only the
+  // framework's own `/__webjs/*` and same-origin vendor targets move).
+  for (const k of Object.keys(merged).sort()) imports[k] = withBasePath(merged[k], _basePath);
 
   // Emit `integrity` per the importmap-integrity spec (Chrome 132+,
   // Safari 18.4+, Firefox flagged). Browsers without support ignore
@@ -305,11 +350,17 @@ export function buildImportMap() {
   // unrelated pin file edits, and leak removed URLs to the wire.
   const out = { imports };
   const usedUrls = new Set(Object.values(imports));
-  const intKeys = Object.keys(_vendorIntegrity).filter(k => usedUrls.has(k)).sort();
+  // Integrity keys are the FINAL post-rewrite URLs, so prefix a same-origin
+  // local vendor key with the base path to match its (now prefixed) imports
+  // value. A cross-origin CDN key is untouched by `withBasePath` and lines
+  // up with its unprefixed imports value.
+  const intKeys = Object.keys(_vendorIntegrity)
+    .filter(k => usedUrls.has(withBasePath(k, _basePath)))
+    .sort();
   if (intKeys.length) {
     /** @type {Record<string, string>} */
     const integrity = {};
-    for (const k of intKeys) integrity[k] = _vendorIntegrity[k];
+    for (const k of intKeys) integrity[withBasePath(k, _basePath)] = _vendorIntegrity[k];
     out.integrity = integrity;
   }
   return out;

package/src/redirects.js

@@ -0,0 +1,389 @@
+/**
+ * Declarative permanent / temporary redirects (issue #254).
+ *
+ * webjs already ships `redirect(url)` (a per-request throw sentinel) for
+ * imperative, request-time redirects. This module adds the missing
+ * DECLARATIVE surface: a config of old-path -> new-path rules an app
+ * declares once and the framework applies at the very start of request
+ * handling, before routing / SSR / asset serving. This is what SEO wants
+ * for a moved URL, a permanent 308 (or legacy 301) so link equity
+ * transfers and search engines update their index.
+ *
+ * Config lives in `package.json` -> `webjs.redirects`, an array of
+ * `{ source, destination, permanent?, statusCode? }`, cohesive with the
+ * #232 `webjs.headers` config (same `source` URLPattern matching, same
+ * fail-safe "a malformed entry is dropped at config-load, never a
+ * throw" posture, patterns compiled ONCE at boot):
+ *
+ *   "webjs": { "redirects": [
+ *     { "source": "/old", "destination": "/new" },
+ *     { "source": "/blog/:slug", "destination": "/posts/:slug" },
+ *     { "source": "/legacy", "destination": "/", "permanent": false },
+ *     { "source": "/docs", "destination": "https://docs.example.com" }
+ *   ] }
+ *
+ * Status code. `permanent` defaults to true (308 Permanent Redirect);
+ * `permanent: false` is 307 (Temporary Redirect). 308 / 307 are the
+ * MODERN choice because they preserve the request method and body
+ * (a redirected POST stays a POST). The legacy 301 / 302 do not
+ * guarantee that. An app that needs a specific legacy code (e.g. a 301
+ * for a tool that only understands it) can set `statusCode` explicitly,
+ * which wins over `permanent`.
+ *
+ * Destination. A `destination` may be:
+ *   - a path (`/new`), optionally referencing named groups captured by
+ *     the source pattern (`/posts/:slug` filled from `/blog/:slug`),
+ *   - an absolute URL (`https://docs.example.com`) for an external
+ *     redirect (group substitution applies there too).
+ *
+ * Query string. The incoming query string is PRESERVED by default and
+ * appended to the destination (a destination that carries its own query
+ * is merged, the destination's keys winning). This matches Next.js's
+ * default redirect behavior.
+ */
+
+/**
+ * Trailing-slash canonicalization (issue #255).
+ *
+ * A page reachable at BOTH `/about` and `/about/` is duplicate content:
+ * webjs's file router matches both (every route pattern ends with `/?$`,
+ * so the slashed and unslashed forms render IDENTICAL HTML), but search
+ * engines treat them as two URLs that split link equity, and the client
+ * router caches them under two keys. The trailing-slash policy picks ONE
+ * canonical form and 308-redirects the other to it, exactly like the
+ * `webjs.redirects` config does for a moved URL.
+ *
+ * Config lives in `package.json` -> `webjs.trailingSlash`, cohesive with
+ * `webjs.redirects` / `webjs.headers` / `webjs.csp`:
+ *
+ *   "webjs": { "trailingSlash": "never" }    // /about/ -> /about (recommended)
+ *   "webjs": { "trailingSlash": "always" }   // /about  -> /about/
+ *   "webjs": { "trailingSlash": "ignore" }   // no canonicalization (default)
+ *
+ * Default. Absent or `"ignore"` means NO redirect (current behavior, so an
+ * existing app is unchanged). Most apps want `"never"`; it is the
+ * recommendation, but it is opt-in so adding the feature never silently
+ * starts 308-ing an app that was happy serving both forms.
+ *
+ * Rules (a redirect is a permanent 308, so the SEO equity transfers and a
+ * redirected POST stays a POST):
+ *   - `never`: a path ending in `/` (other than the root `/`) redirects to
+ *     the same path without the trailing slash.
+ *   - `always`: a path with NO trailing slash redirects to the same path
+ *     WITH one, UNLESS the last segment looks like a file (has a dot in it,
+ *     e.g. `/foo.js`, `/image.png`); a file path is left alone, since
+ *     `/foo.js/` is not a sensible canonical form.
+ *   - The ROOT path `/` is ALWAYS left alone under either policy.
+ *   - The query string and hash are preserved on the redirect.
+ *   - `/__webjs/*` framework paths are exempt (handled by the caller).
+ */
+
+/** Permanent (308) is the canonicalization status, like a moved URL. */
+const CANONICAL_STATUS = 308;
+
+/** The valid `webjs.trailingSlash` policy values. */
+const TRAILING_SLASH_POLICIES = new Set(['never', 'always', 'ignore']);
+
+/**
+ * Read the trailing-slash policy from the app's package.json
+ * (`webjs.trailingSlash`). Returns `'never'` / `'always'` / `'ignore'`,
+ * defaulting to `'ignore'` (no canonicalization) for an absent, malformed,
+ * or unrecognized value, so a missing or typo'd config is a no-op rather
+ * than a throw or an accidental redirect.
+ *
+ * @param {unknown} pkg parsed package.json (or any object)
+ * @returns {'never' | 'always' | 'ignore'}
+ */
+export function readTrailingSlashPolicy(pkg) {
+  const raw =
+    pkg &&
+    typeof pkg === 'object' &&
+    /** @type {any} */ (pkg).webjs &&
+    /** @type {any} */ (pkg).webjs.trailingSlash;
+  if (typeof raw === 'string' && TRAILING_SLASH_POLICIES.has(raw)) {
+    return /** @type {'never' | 'always' | 'ignore'} */ (raw);
+  }
+  return 'ignore';
+}
+
+/**
+ * Apply the trailing-slash canonicalization policy to an incoming request.
+ * Returns a 308 redirect Response to the canonical form when the request
+ * path is non-canonical under the policy, else null so the request falls
+ * through to normal routing (or to the declarative redirects). Runs AFTER
+ * `applyRedirects` (see the wiring in `dev.js`): an explicit `webjs.redirects`
+ * rule wins first, then the survivor is slash-canonicalized. This does NOT
+ * guarantee loop-freedom. A redirect whose `destination` CONTRADICTS the slash
+ * policy (e.g. policy `never` with `{ destination: '/x/' }`) ping-pongs forever
+ * (`/x` -> 308 `/x/` -> 308 `/x` -> ...). There is no server-side loop guard
+ * (matching `applyRedirects`), so keeping a redirect destination consistent with
+ * the policy is the app author's responsibility.
+ *
+ * Framework-internal `/__webjs/*` paths are never canonicalized (the caller
+ * also guards this, defense in depth here).
+ *
+ * SECURITY: the canonical path is built from `url.pathname` and emitted as the
+ * `Location`, so a request whose path is a NETWORK-PATH REFERENCE (begins with
+ * `//`, or `/\` which the URL parser normalizes to `//`) would otherwise emit a
+ * protocol-relative `Location` (`//attacker.com`) that the browser resolves to a
+ * FOREIGN origin, an open redirect. Such a path is not a normal route, so we
+ * REFUSE to canonicalize it (return null) and let the router 404 it, rather than
+ * emit a cross-origin redirect. The sibling `applyRedirects` avoids this by only
+ * ever emitting app-authored `destination` literals (and keeping user-controlled
+ * `:slug` captures percent-encoded so they cannot escape the origin); here the
+ * Location is derived from the request path, so the guard is on the path itself.
+ *
+ * @param {Request} req
+ * @param {'never' | 'always' | 'ignore'} policy
+ * @returns {Response | null}
+ */
+export function applyTrailingSlash(req, policy) {
+  if (policy !== 'never' && policy !== 'always') return null;
+  let url;
+  try {
+    url = new URL(req.url);
+  } catch {
+    return null;
+  }
+  const path = url.pathname;
+  // The root path is always canonical under either policy.
+  if (path === '/') return null;
+  if (path.startsWith('/__webjs/')) return null;
+  // Refuse a network-path reference (`//host`, or `/\host` normalized to
+  // `//host`): canonicalizing it would emit a protocol-relative, cross-origin
+  // Location (an open redirect). Let the router handle the weird path instead.
+  if (!isSameOriginPath(path)) return null;
+
+  /** @type {string | null} */
+  let canonical = null;
+  if (policy === 'never') {
+    // Strip a single trailing slash. (A multi-slash path like `/about//`
+    // collapses one slash per redirect; the next request re-canonicalizes,
+    // and the common single-slash case settles in one hop.)
+    if (path.endsWith('/')) canonical = path.replace(/\/+$/, '') || '/';
+  } else {
+    // policy === 'always'
+    if (!path.endsWith('/') && !lastSegmentLooksLikeFile(path)) {
+      canonical = path + '/';
+    }
+  }
+  if (canonical === null || canonical === path) return null;
+
+  // Preserve the query string and hash on the canonical URL.
+  const location = canonical + url.search + url.hash;
+  return new Response(null, {
+    status: CANONICAL_STATUS,
+    headers: { location: location },
+  });
+}
+
+/**
+ * Whether the LAST path segment looks like a file (contains a dot), e.g.
+ * `/foo.js` or `/assets/logo.png`. Such a path must NOT get a trailing
+ * slash added under the `always` policy: a file is a leaf, not a "page"
+ * directory, so `/foo.js/` is never a sensible canonical form.
+ *
+ * @param {string} path a pathname (no query / hash)
+ * @returns {boolean}
+ */
+function lastSegmentLooksLikeFile(path) {
+  const lastSlash = path.lastIndexOf('/');
+  const segment = path.slice(lastSlash + 1);
+  return segment.includes('.');
+}
+
+/**
+ * Whether a pathname is a SAFE same-origin path (a single leading slash, not a
+ * network-path reference). A path beginning with `//` or `/\` resolves to a
+ * foreign origin when emitted as a `Location`, so it is rejected. The URL parser
+ * normalizes a backslash to a forward slash in the pathname, so `/\evil.com` is
+ * seen here as `//evil.com`; the explicit backslash check is belt-and-braces in
+ * case a caller passes a raw, unparsed path.
+ *
+ * @param {string} path a pathname
+ * @returns {boolean}
+ */
+function isSameOriginPath(path) {
+  if (path[0] !== '/') return false;
+  const second = path[1];
+  return second !== '/' && second !== '\\';
+}
+
+/** Default status for `permanent: true` (the SEO permanent redirect). */
+const PERMANENT_STATUS = 308;
+/** Default status for `permanent: false` (a temporary redirect). */
+const TEMPORARY_STATUS = 307;
+
+/** Redirect status codes a `statusCode` override may legitimately set. */
+const ALLOWED_STATUS = new Set([301, 302, 303, 307, 308]);
+
+/**
+ * Read the redirect config from the app's package.json
+ * (`webjs.redirects`) and compile it to a cached array of rules, each
+ * pairing a URLPattern (matched on the pathname) against a destination
+ * template + resolved status. A malformed or absent config yields an
+ * empty array (no redirects), never a throw: a broken redirect config
+ * must not take the request pipeline down. Each malformed entry is
+ * DROPPED with a one-line warning, so a single typo never disables the
+ * valid rules around it.
+ *
+ * @param {unknown} pkg parsed package.json (or any object)
+ * @returns {Array<{ pattern: URLPattern, destination: string, status: number }>}
+ */
+export function compileRedirectRules(pkg) {
+  const raw =
+    pkg &&
+    typeof pkg === 'object' &&
+    /** @type {any} */ (pkg).webjs &&
+    /** @type {any} */ (pkg).webjs.redirects;
+  if (!Array.isArray(raw)) return [];
+  /** @type {Array<{ pattern: URLPattern, destination: string, status: number }>} */
+  const rules = [];
+  for (const entry of raw) {
+    if (!entry || typeof entry !== 'object') continue;
+    const source = /** @type {any} */ (entry).source;
+    const destination = /** @type {any} */ (entry).destination;
+    if (typeof source !== 'string' || !source) {
+      warnDrop('source must be a non-empty string', entry);
+      continue;
+    }
+    if (typeof destination !== 'string' || !destination) {
+      warnDrop('destination must be a non-empty string', entry);
+      continue;
+    }
+    let pattern;
+    try {
+      // Match on the pathname only, like the #232 header config. A bare
+      // path string is the common Next-style usage; URLPattern treats it
+      // as the pathname component, so `:slug` / `:rest*` syntax works.
+      pattern = new URLPattern({ pathname: source });
+    } catch {
+      warnDrop(`invalid source pattern "${source}"`, entry);
+      continue;
+    }
+    const status = resolveStatus(entry);
+    if (status === null) {
+      warnDrop(`invalid statusCode on "${source}"`, entry);
+      continue;
+    }
+    rules.push({ pattern, destination, status });
+  }
+  return rules;
+}
+
+/**
+ * Resolve the redirect status for one entry. `statusCode` wins when set
+ * (must be one of the allowed redirect codes), else `permanent` chooses
+ * 308 (default true) vs 307.
+ *
+ * @param {any} entry
+ * @returns {number | null} the status, or null if `statusCode` is invalid
+ */
+function resolveStatus(entry) {
+  const raw = entry.statusCode;
+  if (raw !== undefined && raw !== null) {
+    const n = Number(raw);
+    if (!Number.isInteger(n) || !ALLOWED_STATUS.has(n)) return null;
+    return n;
+  }
+  // `permanent` defaults to TRUE (the SEO permanent redirect). Only an
+  // explicit `false` opts into the temporary 307.
+  return entry.permanent === false ? TEMPORARY_STATUS : PERMANENT_STATUS;
+}
+
+/** @param {string} reason @param {unknown} entry */
+function warnDrop(reason, entry) {
+  // eslint-disable-next-line no-console
+  console.warn(`[webjs] dropping invalid webjs.redirects entry (${reason}):`, entry);
+}
+
+/**
+ * Substitute named groups captured by the source pattern into the
+ * destination template. A `:name` token in the destination is replaced
+ * by the matching group's value (URL-pathname-encoded by URLPattern's
+ * own capture). An undefined group leaves the literal token in place
+ * (a misconfigured destination, not a crash).
+ *
+ * @param {string} destination the destination template
+ * @param {Record<string, string | undefined>} groups URLPattern exec groups
+ * @returns {string}
+ */
+function fillGroups(destination, groups) {
+  if (!groups) return destination;
+  // Replace `:name` tokens. The name charset matches URLPattern's
+  // (letters, digits, underscore). A token with no matching group is
+  // left untouched.
+  return destination.replace(/:([A-Za-z0-9_]+)/g, (whole, name) => {
+    const v = groups[name];
+    return v === undefined ? whole : v;
+  });
+}
+
+/**
+ * Build the final redirect Location for a matched rule: fill named
+ * groups, then merge the incoming query string onto the destination
+ * (preserved by default, the destination's own query keys winning).
+ *
+ * @param {{ destination: string, status: number }} rule
+ * @param {Record<string, string | undefined>} groups
+ * @param {URL} url the incoming request URL
+ * @returns {string} the Location header value
+ */
+function buildLocation(rule, groups, url) {
+  let dest = fillGroups(rule.destination, groups);
+  const incoming = url.search; // includes the leading '?', or '' when absent
+  if (!incoming) return dest;
+  // Preserve the incoming query string. If the destination already
+  // carries its own query, merge, with the destination's keys winning
+  // (an explicit redirect target is intentional).
+  const hashIdx = dest.indexOf('#');
+  const hash = hashIdx === -1 ? '' : dest.slice(hashIdx);
+  const noHash = hashIdx === -1 ? dest : dest.slice(0, hashIdx);
+  const qIdx = noHash.indexOf('?');
+  const base = qIdx === -1 ? noHash : noHash.slice(0, qIdx);
+  const destQuery = qIdx === -1 ? '' : noHash.slice(qIdx + 1);
+  const merged = new URLSearchParams(incoming.slice(1));
+  for (const [k, v] of new URLSearchParams(destQuery)) merged.set(k, v);
+  const qs = merged.toString();
+  return base + (qs ? '?' + qs : '') + hash;
+}
+
+/**
+ * Apply the declarative redirect rules to an incoming request. Returns a
+ * redirect Response (308 / 307 / the configured status, with the
+ * computed `Location`) on the FIRST matching rule, else null so the
+ * request falls through to normal routing. Framework-internal paths
+ * (`/__webjs/*`) are never redirected.
+ *
+ * Compiled rules are passed in (built once at boot), so this is O(rules)
+ * per request with no per-request pattern compilation.
+ *
+ * @param {Request} req
+ * @param {Array<{ pattern: URLPattern, destination: string, status: number }>} rules
+ * @returns {Response | null}
+ */
+export function applyRedirects(req, rules) {
+  if (!rules || !rules.length) return null;
+  let url;
+  try {
+    url = new URL(req.url);
+  } catch {
+    return null;
+  }
+  // Never redirect framework-internal paths (probes, the core runtime,
+  // the action endpoint, the dev reload stream). They are infrastructure,
+  // not app URLs.
+  if (url.pathname.startsWith('/__webjs/')) return null;
+
+  for (const rule of rules) {
+    const match = rule.pattern.exec({ pathname: url.pathname });
+    if (!match) continue;
+    const groups = (match.pathname && match.pathname.groups) || {};
+    const location = buildLocation(rule, groups, url);
+    return new Response(null, {
+      status: rule.status,
+      headers: { location: location },
+    });
+  }
+  return null;
+}

package/src/route-types.js

@@ -0,0 +1,176 @@
+/**
+ * Route-types generator (#258).
+ *
+ * `generateRouteTypes(appDir)` walks `app/` (reusing `buildRouteTable`, the
+ * one route enumerator) and emits the `.d.ts` TEXT that augments
+ * `@webjsdev/core`, narrowing the `Route` href union and the per-route
+ * `params` shape. It is the opt-in codegen behind `webjs types`; the static
+ * types in `@webjsdev/core` (`PageProps`, `LayoutProps`, `Route`, …) work
+ * without it (un-generated apps see `Route = string`).
+ *
+ * Design choices:
+ *   - PAGES ONLY. A `route.{js,ts}` handler is an API endpoint, not a
+ *     navigable HTML page, so its path is excluded from the navigable `Route`
+ *     union. Pages (including page-action pages) are what a valid href points
+ *     at.
+ *   - The route KEY is the literal pattern (`/blog/[slug]`), derived from the
+ *     page's directory with route groups `(group)` stripped and `_private`
+ *     dirs excluded, matching `buildRouteTable`'s own URL normalization.
+ *   - The optional catch-all `[[...slug]]` emits TWO `WebjsRoutes` keys (the
+ *     with-segment `/docs/[[...slug]]` and the without-segment `/docs`), so a
+ *     bare `/docs` and a `/docs/a/b` both type-check. Keeping the with/without
+ *     split in the generator lets the pure `RoutePattern` type stay simple.
+ *   - Param object shapes are known here: `[slug]` -> `{ slug: string }`,
+ *     `[...rest]` -> `{ rest: string[] }`, `[[...rest]]` -> `{ rest?: string[] }`.
+ *   - Deterministic: keys are sorted so re-running yields a byte-identical
+ *     file (clean diffs, idempotent).
+ */
+
+import { buildRouteTable } from './router.js';
+
+/** @param {string} seg */
+function isUrlSegment(seg) {
+  if (seg.startsWith('(') && seg.endsWith(')')) return false; // route group
+  if (seg.startsWith('_')) return false; // private
+  return true;
+}
+
+/**
+ * The literal route key for a page directory, e.g. `app/blog/[slug]/page.ts`
+ * (routeDir `blog/[slug]`) -> `/blog/[slug]`. The root page (routeDir `.`)
+ * -> `/`. Route groups and private segments are dropped from the path.
+ *
+ * @param {string} routeDir  POSIX-style, `.` for the app root.
+ * @returns {string}
+ */
+export function routeKeyFromDir(routeDir) {
+  if (routeDir === '.' || routeDir === '') return '/';
+  const segs = routeDir.split('/').filter(isUrlSegment);
+  if (segs.length === 0) return '/';
+  return '/' + segs.join('/');
+}
+
+/**
+ * @typedef {{ name: string, kind: 'single' | 'catchAll' | 'optionalCatchAll' }} DynSeg
+ */
+
+/**
+ * Extract the dynamic segments of a route key in order.
+ *
+ * @param {string} key  A literal route key like `/blog/[slug]`.
+ * @returns {DynSeg[]}
+ */
+export function dynamicSegments(key) {
+  /** @type {DynSeg[]} */
+  const out = [];
+  for (const seg of key.split('/')) {
+    if (seg.startsWith('[[...') && seg.endsWith(']]')) {
+      out.push({ name: seg.slice(5, -2), kind: 'optionalCatchAll' });
+    } else if (seg.startsWith('[...') && seg.endsWith(']')) {
+      out.push({ name: seg.slice(4, -1), kind: 'catchAll' });
+    } else if (seg.startsWith('[') && seg.endsWith(']')) {
+      out.push({ name: seg.slice(1, -1), kind: 'single' });
+    }
+  }
+  return out;
+}
+
+/**
+ * The TypeScript params-object literal for a route key, e.g.
+ * `{ slug: string }` / `{ rest: string[] }` / `{ slug?: string[] }`. Returns
+ * null for a static route (no entry needed in `RouteParamMap`).
+ *
+ * @param {string} key
+ * @returns {string | null}
+ */
+export function paramTypeForKey(key) {
+  const dyn = dynamicSegments(key);
+  if (dyn.length === 0) return null;
+  const fields = dyn.map((d) => {
+    if (d.kind === 'single') return `${d.name}: string`;
+    if (d.kind === 'catchAll') return `${d.name}: string[]`;
+    return `${d.name}?: string[]`; // optionalCatchAll
+  });
+  return `{ ${fields.join('; ')} }`;
+}
+
+/**
+ * Build the set of `WebjsRoutes` HREF keys for a route key. These keys drive
+ * the `Route` href union, so each must be a form the pure `RoutePattern` type
+ * can expand cleanly (it only understands the single `[x]` and catch-all
+ * `[...x]` segments, NOT the doubled `[[...x]]`). So:
+ *   - A static route yields itself.
+ *   - A normal dynamic route (`[x]` / `[...x]`) yields itself.
+ *   - An OPTIONAL catch-all `[[...x]]` yields TWO keys: the WITHOUT-segment
+ *     form (the segment elided, the `//` collapsed) so a bare path matches,
+ *     and a NORMALIZED with-segment form where `[[...x]]` is rewritten to the
+ *     plain catch-all `[...x]` so the deep path matches. The author-facing
+ *     literal `[[...x]]` stays the `RouteParamMap` key (that is what a page
+ *     passes to `PageProps`), but it is NOT a Route-union key.
+ *
+ * @param {string} key
+ * @returns {string[]}
+ */
+export function webjsRoutesKeysForKey(key) {
+  if (!key.includes('[[...')) return [key];
+  // With-segment: rewrite each `[[...name]]` to the plain catch-all `[...name]`.
+  const withSeg = key.replace(/\[\[\.\.\.([^\]]+)\]\]/g, '[...$1]');
+  // Without-segment: drop the optional catch-all segment entirely.
+  let without = key.replace(/\/\[\[\.\.\.[^\]]+\]\]/g, '');
+  if (without === '') without = '/';
+  const out = new Set([withSeg]);
+  out.add(without);
+  return [...out];
+}
+
+/**
+ * Generate the augmentation `.d.ts` text for an app's routes.
+ *
+ * @param {string} appDir  The app root (the dir containing `app/`).
+ * @returns {Promise<string>}
+ */
+export async function generateRouteTypes(appDir) {
+  const table = await buildRouteTable(appDir);
+
+  /** @type {Set<string>} */
+  const routeKeys = new Set();
+  /** @type {Map<string, string>} */
+  const paramEntries = new Map();
+
+  for (const page of table.pages) {
+    const key = routeKeyFromDir(page.routeDir);
+    const paramType = paramTypeForKey(key);
+    if (paramType) paramEntries.set(key, paramType);
+    for (const k of webjsRoutesKeysForKey(key)) routeKeys.add(k);
+  }
+
+  const sortedKeys = [...routeKeys].sort();
+  const sortedParamKeys = [...paramEntries.keys()].sort();
+
+  const routeLines = sortedKeys.map((k) => `    ${JSON.stringify(k)}: true;`);
+  const paramLines = sortedParamKeys.map(
+    (k) => `    ${JSON.stringify(k)}: ${paramEntries.get(k)};`,
+  );
+
+  // The without-segment optional-catch-all key has no dynamic segment, so it
+  // gets no RouteParamMap entry (its params are optional anyway); the
+  // with-segment key carries the `{ name?: string[] }` shape.
+
+  const out = `// AUTO-GENERATED by \`webjs types\`. Do not edit. Regenerated from app/ routes.
+//
+// Augments @webjsdev/core so the Route href union, navigate(), and per-route
+// params are typed for this app. Regenerated per machine (gitignored, like
+// Next's .next/types). Re-run \`webjs types\` after adding or removing a route.
+import '@webjsdev/core';
+
+declare module '@webjsdev/core' {
+  interface WebjsRoutes {
+${routeLines.join('\n')}
+  }
+  interface RouteParamMap {
+${paramLines.join('\n')}
+  }
+}
+`;
+  return out;
+}