@webjsdev/core 0.7.7 → 0.7.9

package/index.d.ts

@@ -9,6 +9,50 @@
  */
 
 export * from './src/component.d.ts';
+export type {
+  Metadata,
+  MetadataContext,
+  TitleMetadata,
+  ViewportMetadata,
+  RobotsMetadata,
+  AlternatesMetadata,
+  VerificationMetadata,
+  OpenGraphMetadata,
+  TwitterMetadata,
+  AppleWebAppMetadata,
+  IconsMetadata,
+  IconDescriptor,
+  AuthorMetadata,
+  PreloadDescriptor,
+  JsonLd,
+} from './src/metadata.d.ts';
+
+// Typed route props + the opt-in generated route union (#258). The
+// `WebjsRoutes` / `RouteParamMap` interfaces are exported as VALUES-of-types
+// (interfaces) so app code and the generated `.webjs/routes.d.ts` can augment
+// them via `declare module '@webjsdev/core'`.
+export type {
+  Route,
+  RouteParams,
+  PageProps,
+  LayoutProps,
+  RouteHandlerContext,
+  WebjsRoutes,
+  RouteParamMap,
+} from './src/routes.d.ts';
+
+// The package.json `webjs` config block (#259). Typed reference for the
+// elide / headers / redirects / trailingSlash / csp / ingress-limit knobs;
+// the companion JSON Schema (packages/server/webjs-config.schema.json) gives
+// editors native validation of package.json itself.
+export type {
+  WebjsConfig,
+  WebjsHeaderRule,
+  WebjsHeaderDirective,
+  WebjsRedirectRule,
+  WebjsTrailingSlash,
+  WebjsCspConfig,
+} from './src/webjs-config.d.ts';
 
 export { html, isTemplate, MARKER } from './src/html.js';
 export { css, isCSS, adoptStyles, stylesToString } from './src/css.js';
@@ -17,12 +61,19 @@ export { renderToString, renderToStream } from './src/render-server.js';
 export { render } from './src/render-client.js';
 export { escapeText, escapeAttr } from './src/escape.js';
 export { notFound, redirect, isNotFound, isRedirect } from './src/nav.js';
-export { expose, getExposed } from './src/expose.js';
+export { expose, getExposed, validateInput } from './src/expose.js';
 export { repeat, isRepeat } from './src/repeat.js';
 export { Suspense, isSuspense } from './src/suspense.js';
 export { connectWS } from './src/websocket-client.js';
 export { richFetch } from './src/rich-fetch.js';
-export { enableClientRouter, disableClientRouter, navigate } from './src/router-client.js';
+export { enableClientRouter, disableClientRouter } from './src/router-client.js';
+
+// `navigate` is typed against the generated `Route` union (#258) rather than
+// the JSDoc `string`. Until an app runs `webjs types`, `Route` resolves to
+// `string`, so this is non-breaking; once generated, a bogus in-app path is a
+// tsserver error. The runtime is the same async function in router-client.js.
+import type { Route } from './src/routes.d.ts';
+export function navigate(url: Route, opts?: { replace?: boolean }): Promise<void>;
 export { unsafeHTML, isUnsafeHTML, live, isLive } from './src/directives.js';
 export { createContext, ContextProvider, ContextConsumer, ContextRequestEvent } from './src/context.js';
 export { Task, TaskStatus } from './src/task.js';

package/index.js

@@ -15,7 +15,7 @@ export { render } from './src/render-client.js';
 export { escapeText, escapeAttr } from './src/escape.js';
 export { notFound, redirect, isNotFound, isRedirect } from './src/nav.js';
 export { cspNonce, setCspNonceProvider } from './src/csp-nonce.js';
-export { expose, getExposed } from './src/expose.js';
+export { expose, getExposed, validateInput } from './src/expose.js';
 export { repeat, isRepeat } from './src/repeat.js';
 export { Suspense, isSuspense } from './src/suspense.js';
 export { connectWS } from './src/websocket-client.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/core",
-  "version": "0.7.7",
+  "version": "0.7.9",
   "type": "module",
   "description": "webjs core runtime - html/css tags, WebComponent base, isomorphic renderers",
   "types": "./index.d.ts",

package/src/expose.js

@@ -22,10 +22,22 @@
  *   - For methods with a body (POST/PUT/PATCH/DELETE), the parsed JSON body
  *     is merged on top of params/query. The function receives ONE argument:
  *     the merged object.
- *   - If `opts.validate` is provided, it runs BEFORE the function and can
- *     transform / reject the input. Throw to fail (→ 400 response). Return
- *     value replaces the input. Works cleanly with zod, valibot, or any
- *     parser that throws: `expose('...', fn, { validate: Schema.parse })`.
+ *   - If `opts.validate` is provided, it runs BEFORE the function on EVERY
+ *     call path (the REST path here AND the internal RPC path), so a single
+ *     validator declared once guards both. The framework calls `validate(input)`
+ *     and interprets the return (see the validator contract below):
+ *       - a `{ success: true, data? }` envelope passes (the action receives
+ *         `data` when present, else the original input);
+ *       - a `{ success: false, fieldErrors, message? }` envelope FAILS with a
+ *         structured field-error result (422), without calling the action;
+ *       - a THROW fails (→ 400 on REST, sanitized error on RPC), preserving the
+ *         classic `Schema.parse`-style contract;
+ *       - any OTHER returned plain value is treated as the transformed input
+ *         (back-compat with the `validate: Schema.parse` transform style).
+ *     The zod adapter is three lines and keeps the framework zod-free:
+ *       `validate: (i) => { const r = Schema.safeParse(i);
+ *          return r.success ? { success: true, data: r.data }
+ *            : { success: false, fieldErrors: r.error.flatten().fieldErrors }; }`
  *   - Return value becomes a JSON `Response`; throw or return a `Response`
  *     directly for full control.
  *
@@ -84,6 +96,84 @@ function normaliseCors(c) {
   };
 }
 
+/**
+ * Attach an input validator to a server action WITHOUT exposing it as a REST
+ * endpoint. The validator runs SERVER-SIDE before the action body on BOTH call
+ * paths: the internal RPC path (a client component importing the action) AND
+ * the `expose()` REST path (if the action is also exposed). This is the shared,
+ * declare-once validation surface (#245).
+ *
+ * It reuses the EXACT same `__webjsHttp` storage `expose()` writes, so the
+ * action index's `getExposed(fn)` already surfaces the validator with no new
+ * plumbing. The action stays a plain callable function (a direct unit-test
+ * import still works, just without the framework running validate).
+ *
+ * If the action is already `expose()`d, prefer passing `{ validate }` to
+ * `expose()` directly; calling both keeps the LAST validator attached.
+ *
+ * ```js
+ * // actions/posts.server.js
+ * 'use server';
+ * import { validateInput } from '@webjsdev/core';
+ *
+ * export const createPost = validateInput(
+ *   async ({ title }) => { ... },
+ *   (input) => {
+ *     const errs = {};
+ *     if (!input?.title?.trim()) errs.title = 'Title is required';
+ *     return Object.keys(errs).length
+ *       ? { success: false, fieldErrors: errs }
+ *       : { success: true };
+ *   },
+ * );
+ * ```
+ *
+ * The validator contract (the framework calls `validate(input)`):
+ *   - returns `{ success: true, data? }` → valid; the action is called with
+ *     `data` if present, else the original input;
+ *   - returns `{ success: false, fieldErrors, message? }` (an object with a
+ *     boolean `success` of `false`, or with a `fieldErrors`) → FAILED; the
+ *     framework returns a structured `ActionResult`
+ *     `{ success: false, fieldErrors, error: message?, status: 422 }` without
+ *     calling the action body;
+ *   - THROWS → mapped to a sanitized failure result (the classic
+ *     `Schema.parse` contract);
+ *   - returns ANY OTHER plain value → treated as the validated/coerced input
+ *     and passed to the action (the `validate: Schema.parse` transform style).
+ *
+ * Disambiguation: a return is a result-envelope ONLY when it is an object with
+ * a boolean `success` property OR a `fieldErrors` property; otherwise it is a
+ * transformed input value. Caveat: if your validator returns the input
+ * VERBATIM (the bare-transform style) and that input can itself carry a
+ * `success` boolean or a `fieldErrors` key, it would be misread as an envelope.
+ * Return the explicit `{ success: true, data }` envelope in that case (the zod
+ * adapter and the recommended hand-rolled form already do, so they never
+ * collide).
+ *
+ * Server-side only; import inside `.server.{js,ts}` files. The bare
+ * `@webjsdev/core` specifier resolves to the browser entry, which excludes
+ * `validateInput` (like `expose`), so an import from client-bound code reads
+ * `undefined`. The validator itself lives in the `.server` file and never
+ * reaches the client.
+ *
+ * @template {Function} F
+ * @param {F} fn the async action implementation
+ * @param {(input: any) => any} validate the validator (a plain function or a
+ *   zod-`safeParse` adapter)
+ * @returns {F} the same function, tagged with the validator
+ */
+export function validateInput(fn, validate) {
+  if (typeof fn !== 'function') {
+    throw new Error('validateInput(): first argument must be the action function');
+  }
+  if (typeof validate !== 'function') {
+    throw new Error('validateInput(): second argument must be a validator function');
+  }
+  const existing = /** @type any */ (fn).__webjsHttp || {};
+  /** @type any */ (fn).__webjsHttp = { ...existing, validate };
+  return fn;
+}
+
 /** @param {unknown} fn */
 export function getExposed(fn) {
   return fn && typeof fn === 'function' ? /** @type any */ (fn).__webjsHttp || null : null;

package/src/metadata.d.ts

@@ -0,0 +1,279 @@
+/**
+ * TypeScript overlay for the `metadata` / `generateMetadata` return shape.
+ *
+ * A page or layout exports `metadata` (static) or `generateMetadata(ctx)`
+ * (request-scoped). Both return a plain object that the SSR pipeline
+ * (packages/server/src/ssr.js) reads field by field and emits into the
+ * document `<head>`. This file types that object so authors get
+ * autocomplete and typo checking:
+ *
+ *     import type { Metadata } from '@webjsdev/core';
+ *     export const metadata: Metadata = { title: 'Home', description: '…' };
+ *     export async function generateMetadata(ctx: MetadataContext): Promise<Metadata> { … }
+ *
+ * The shape mirrors what ssr.js actually consumes (and agent-docs/metadata.md
+ * documents), NOT Next.js's full superset. Every field is optional. Zero
+ * runtime cost: nothing in this file ships to the browser.
+ */
+
+/** A URL or relative path. Relative values resolve against `metadataBase`. */
+type MetadataUrl = string;
+
+/** `title` accepts a plain string or the template object Next.js uses. */
+export type TitleMetadata =
+  | string
+  | {
+      /** Wraps a deeper plain-string title via the `%s` placeholder. */
+      template?: string;
+      /** Title used when a deeper layer supplies none. */
+      default?: string;
+      /** Bypasses the inherited template entirely for this layer. */
+      absolute?: string;
+    };
+
+/** An author entry: a bare name, or `{ name, url? }`. */
+export type AuthorMetadata = string | { name?: string; url?: MetadataUrl };
+
+/** `viewport` object form (Next.js 14+ split-export shape). */
+export interface ViewportMetadata {
+  width?: string | number;
+  height?: string | number;
+  initialScale?: number;
+  minimumScale?: number;
+  maximumScale?: number;
+  /** `false` emits `user-scalable=no`, `true` emits `yes`. */
+  userScalable?: boolean;
+  viewportFit?: 'auto' | 'contain' | 'cover';
+  interactiveWidget?: 'resizes-visual' | 'resizes-content' | 'overlays-content';
+  /** May also carry `themeColor` / `colorScheme` on the split `viewport` export. */
+  themeColor?: string;
+  colorScheme?: string;
+}
+
+/** `robots` object form (a bare string is also accepted). */
+export interface RobotsMetadata {
+  index?: boolean;
+  follow?: boolean;
+  noarchive?: boolean;
+  nosnippet?: boolean;
+  noimageindex?: boolean;
+  /** Emitted verbatim as `<meta name="googlebot">`. */
+  googleBot?: string;
+}
+
+/** `alternates`: canonical + i18n / media / type alternates. */
+export interface AlternatesMetadata {
+  canonical?: MetadataUrl;
+  /** hreflang -> URL, e.g. `{ 'es-ES': '/es' }`. */
+  languages?: Record<string, MetadataUrl>;
+  /** media query -> URL, e.g. `{ '(max-width: 600px)': '/mobile' }`. */
+  media?: Record<string, MetadataUrl>;
+  /** MIME type -> URL, e.g. `{ 'application/rss+xml': '/rss.xml' }`. */
+  types?: Record<string, MetadataUrl>;
+}
+
+/** Site-verification tokens. Each value is a token or list of tokens. */
+export interface VerificationMetadata {
+  google?: string | string[];
+  yandex?: string | string[];
+  yahoo?: string | string[];
+  /** IndieAuth / personal `<meta name="me">`. */
+  me?: string | string[];
+  /** Arbitrary `<meta name="…">` verification entries. */
+  other?: Record<string, string | string[]>;
+}
+
+/** A single icon descriptor. */
+export type IconDescriptor =
+  | MetadataUrl
+  | { url: MetadataUrl; sizes?: string; type?: string };
+
+/** `icons`: a bare URL, a list, or the bucketed object form. */
+export type IconsMetadata =
+  | MetadataUrl
+  | IconDescriptor[]
+  | {
+      icon?: IconDescriptor | IconDescriptor[];
+      apple?: IconDescriptor | IconDescriptor[];
+      shortcut?: IconDescriptor | IconDescriptor[];
+      /** Catch-all: each entry carries its own `rel`. */
+      other?:
+        | { rel: string; url: MetadataUrl; sizes?: string; type?: string }
+        | Array<{ rel: string; url: MetadataUrl; sizes?: string; type?: string }>;
+    };
+
+/**
+ * `openGraph`. Each key is emitted as `<meta property="og:<key>">`, so the
+ * indexer carries the documented keys plus an open-ended fallback for the
+ * `og:image:width` / `image:height` / `image:alt` style entries.
+ */
+export interface OpenGraphMetadata {
+  type?: string;
+  title?: string;
+  description?: string;
+  url?: MetadataUrl;
+  image?: MetadataUrl;
+  site_name?: string;
+  [key: string]: string | undefined;
+}
+
+/** `twitter` card. Each key is emitted as `<meta name="twitter:<key>">`. */
+export interface TwitterMetadata {
+  card?: 'summary' | 'summary_large_image' | 'app' | 'player';
+  title?: string;
+  description?: string;
+  image?: MetadataUrl;
+  site?: string;
+  creator?: string;
+  [key: string]: string | undefined;
+}
+
+/** A startup-image entry for `appleWebApp.startupImage`. */
+export type AppleStartupImage =
+  | MetadataUrl
+  | { url: MetadataUrl; media?: string };
+
+/** `appleWebApp`: `true` (capable) or the descriptor object. */
+export type AppleWebAppMetadata =
+  | boolean
+  | {
+      capable?: boolean;
+      title?: string;
+      statusBarStyle?: 'default' | 'black' | 'black-translucent';
+      startupImage?: AppleStartupImage | AppleStartupImage[];
+    };
+
+/**
+ * A single JSON-LD structured-data object (schema.org). The author owns the
+ * shape (Article, Product, BreadcrumbList, Organization, FAQPage, etc.), so
+ * this is intentionally permissive. The framework serializes it with
+ * `JSON.stringify` and HTML-safe-escapes the output into a
+ * `<script type="application/ld+json">` block.
+ */
+export type JsonLd = Record<string, unknown>;
+
+/** A `metadata.preload` link descriptor (emitted as `<link rel="preload">`). */
+export interface PreloadDescriptor {
+  href: MetadataUrl;
+  as?: string;
+  type?: string;
+  crossorigin?: string;
+  media?: string;
+  [attr: string]: string | undefined;
+}
+
+/**
+ * The return shape of `metadata` / `generateMetadata`.
+ *
+ * Mirrors exactly what packages/server/src/ssr.js consumes. Every field is
+ * optional. Where the framework accepts a string OR an object (`title`,
+ * `viewport`, `robots`, `appleWebApp`, `icons`), the type is a union.
+ *
+ * @see agent-docs/metadata.md for the field-by-field emission reference.
+ */
+export interface Metadata {
+  /** -> `<title>`. Plain string or `{ template, default, absolute }`. */
+  title?: TitleMetadata;
+  /** -> `<meta name="description">`. */
+  description?: string;
+  /** -> `<meta name="keywords">`. A list is comma-joined. */
+  keywords?: string | string[];
+  /** -> `<meta name="author">` (+ optional `<link rel="author">`). */
+  authors?: AuthorMetadata | AuthorMetadata[];
+  /** -> `<meta name="creator">`. */
+  creator?: string;
+  /** -> `<meta name="publisher">`. */
+  publisher?: string;
+  /** -> `<meta name="application-name">`. */
+  applicationName?: string;
+  /** -> `<meta name="generator">`. */
+  generator?: string;
+  /** -> `<meta name="referrer">`. */
+  referrer?: string;
+
+  /** Base for resolving every relative URL in this object. */
+  metadataBase?: string;
+
+  /** -> `<meta name="viewport">`. String form OR object form. */
+  viewport?: string | ViewportMetadata;
+  /** -> `<meta name="theme-color">`. */
+  themeColor?: string;
+  /** -> `<meta name="color-scheme">`. */
+  colorScheme?: string;
+
+  /** -> `<meta name="robots">`. A string OR the object form. */
+  robots?: string | RobotsMetadata;
+  /** Canonical + i18n / media / type alternates. */
+  alternates?: AlternatesMetadata;
+  /** Site-verification tokens. */
+  verification?: VerificationMetadata;
+
+  /** Icon links. Bare URL, list, or bucketed object. */
+  icons?: IconsMetadata;
+  /** -> `<link rel="manifest">`. */
+  manifest?: string;
+
+  /** Open Graph tags (`<meta property="og:*">`). */
+  openGraph?: OpenGraphMetadata;
+  /** Twitter card tags (`<meta name="twitter:*">`). */
+  twitter?: TwitterMetadata;
+
+  /** iOS web-app meta. `true` (capable) or the descriptor object. */
+  appleWebApp?: AppleWebAppMetadata;
+  /** -> `<meta name="format-detection">`. Each value is a boolean. */
+  formatDetection?: Record<string, boolean>;
+  /** -> `<meta name="apple-itunes-app">`. */
+  itunes?: { appId: string; appArgument?: string };
+
+  /** -> `<meta name="category">`. */
+  category?: string;
+  /** -> `<meta name="classification">`. */
+  classification?: string;
+  /** -> `<meta name="abstract">`. */
+  abstract?: string;
+  /** -> `<link rel="archives">`. */
+  archives?: string | string[];
+  /** -> `<link rel="assets">`. */
+  assets?: string | string[];
+  /** -> `<link rel="bookmark">`. */
+  bookmarks?: string | string[];
+
+  /**
+   * Response `Cache-Control` header (NOT a `<meta>` tag). Pages default to
+   * `no-store`; a public value (e.g. `public, max-age=60`) also enables
+   * conditional GET on the page.
+   */
+  cacheControl?: string;
+  /** `<link rel="preload">` hints (fonts, images, etc.). */
+  preload?: PreloadDescriptor[];
+
+  /**
+   * JSON-LD structured data (schema.org), emitted as one or more
+   * `<script type="application/ld+json">` blocks in `<head>`. A single
+   * object emits ONE script; an array emits one script PER element. The
+   * author owns the schema.org shape; the framework serializes with
+   * `JSON.stringify` and HTML-safe-escapes the output automatically (a
+   * value containing `</script>` can never break out of the tag). Works in
+   * `generateMetadata(ctx)` for per-request data (a per-post Article, etc.).
+   */
+  jsonLd?: JsonLd | JsonLd[];
+
+  /** Catch-all `<meta name="…">` entries. Value may be a list. */
+  other?: Record<string, string | number | Array<string | number>>;
+}
+
+/**
+ * The argument `generateMetadata(ctx)` receives. Mirrors the page context
+ * (the same `{ params, searchParams, url, actionData }` a page function gets).
+ */
+export interface MetadataContext {
+  params: Record<string, string>;
+  searchParams?: Record<string, string | string[]>;
+  url: string;
+  /**
+   * Present only on the re-render after a failed page `action` submission.
+   * `undefined` on a normal GET render. Read it to vary the title on a
+   * validation-error re-render.
+   */
+  actionData?: unknown;
+}

package/src/router-client.js

@@ -1473,6 +1473,23 @@ function applySwap(doc, frameId, revalidating, href, incomingBuild) {
       blurOutgoingFocus();
       return;
     }
+    // The response did not carry the requested frame (source null), or the
+    // target frame is gone from the live DOM (target null). Falling through
+    // would wholesale-replace the document, a silent full-page swap that
+    // destroys the page (e.g. an auth redirect returning a login page without
+    // the frame). Surface the contract violation with a cancelable event
+    // instead. Default: warn and leave the frame unchanged. A listener that
+    // calls preventDefault owns the outcome.
+    const evt = new CustomEvent('webjs:frame-missing', {
+      bubbles: true,
+      cancelable: true,
+      detail: { frameId, url: href || (typeof location !== 'undefined' ? location.href : null), document: doc },
+    });
+    (target || document).dispatchEvent(evt);
+    if (!evt.defaultPrevented) {
+      console.warn(`[webjs] frame "${frameId}" was not in the navigation response, leaving it unchanged. Handle "webjs:frame-missing" (preventDefault) to override.`);
+    }
+    return;
   }
 
   // 2. Auto-derived layout-marker swap.

package/src/routes.d.ts

@@ -0,0 +1,136 @@
+/**
+ * TypeScript overlay for typed page / layout / route-handler props plus an
+ * opt-in, generated route union that types `navigate()` and catches bad
+ * hrefs at tsserver time (#258).
+ *
+ * webjs identity holds: NO build step, NO runtime cost, types-only, opt-in
+ * for JSDoc apps. The mechanism mirrors Next 15's `typedRoutes` but via
+ * interface declaration-merging instead of a bundler.
+ *
+ *     import type { PageProps, LayoutProps } from '@webjsdev/core';
+ *     export default function Post({ params }: PageProps<'/blog/[slug]'>) { … }
+ *
+ * Two augmentation targets, `WebjsRoutes` and `RouteParamMap`, are EMPTY by
+ * default, so an un-generated app sees `Route = string` and `params =
+ * Record<string, string>` (non-breaking). Running `webjs types` writes
+ * `.webjs/routes.d.ts`, which augments both with one key per route literal,
+ * narrowing `Route` to the concrete app routes and giving every page typed
+ * `params`.
+ *
+ * The shapes mirror what packages/server/src/ssr.js actually constructs for
+ * the page / layout context and what packages/server/src/api.js passes a
+ * route handler, NOT a guess. Zero runtime cost: nothing here ships to the
+ * browser.
+ */
+
+import type { TemplateResult } from './html.js';
+
+/**
+ * The augmentation target the generated `.webjs/routes.d.ts` fills with one
+ * key per route literal (e.g. `'/blog/[slug]': true`). Empty by default so an
+ * un-generated app keeps `Route = string`. App code (or the generator)
+ * augments it via `declare module '@webjsdev/core'`.
+ */
+export interface WebjsRoutes {}
+
+/**
+ * The augmentation target mapping a dynamic route key to its params object
+ * (`'/blog/[slug]': { slug: string }`). Emitted by the generator with the
+ * exact `string` / `string[]` / optional shapes known at generation time,
+ * which is far more robust than deep template-literal inference. Empty by
+ * default; a static route is never given an entry here, so its params fall
+ * through to `Record<string, string>` (the runtime default), not `{}`.
+ */
+export interface RouteParamMap {}
+
+/** True once either augmentation target carries at least one key. */
+type _HasRoutes = keyof WebjsRoutes extends never ? false : true;
+
+/**
+ * Turn a route key into the set of concrete path patterns it matches by
+ * replacing each dynamic segment with `${string}`. The optional catch-all
+ * `[[...x]]` is handled by the GENERATOR, which emits BOTH the with-segment
+ * and without-segment keys as separate `WebjsRoutes` entries (so `/docs` and
+ * `/docs/a/b` both satisfy a `/docs/[[...slug]]` route). Keeping that collapse
+ * in the generator (not in pure types) avoids the fragile `//`-collapse, so
+ * `RoutePattern` only ever needs the single-segment `[x]` and catch-all
+ * `[...x]` cases.
+ */
+type RoutePattern<K extends string> =
+  K extends `${infer A}[...${string}]${infer B}`
+    ? `${A}${string}${RoutePattern<B>}`
+    : K extends `${infer A}[${string}]${infer B}`
+      ? `${A}${string}${RoutePattern<B>}`
+      : K;
+
+/**
+ * The valid-href type. `string` when no routes are generated (so `navigate()`
+ * and JSDoc apps are never broken); once `WebjsRoutes` is augmented it is the
+ * union of every static route literal PLUS a template-literal pattern per
+ * dynamic route.
+ */
+export type Route = _HasRoutes extends true
+  ? { [K in keyof WebjsRoutes]: RoutePattern<K & string> }[keyof WebjsRoutes]
+  : string;
+
+/**
+ * The params object for a route key. A generated dynamic route resolves to
+ * its `RouteParamMap` entry (`{ slug: string }`, `{ rest: string[] }`,
+ * `{ slug?: string[] }`); anything else (a static route, or any route in an
+ * un-generated app) resolves to `Record<string, string>`, the runtime
+ * default the SSR pipeline produces.
+ */
+export type RouteParams<R extends string> = R extends keyof RouteParamMap
+  ? RouteParamMap[R]
+  : Record<string, string>;
+
+/**
+ * The argument a page default-export receives. Mirrors the `ctx` object
+ * packages/server/src/ssr.js builds: `{ params, searchParams, url,
+ * actionData }`.
+ *
+ * `searchParams` is typed `Record<string, string | string[]>` to match the
+ * established page-context convention, even though the runtime builds it with
+ * `Object.fromEntries(url.searchParams.entries())` (so a repeated key is
+ * last-wins `string`, never an array). The wider type keeps a future
+ * multi-value reader source-compatible.
+ */
+export interface PageProps<R extends string = string> {
+  /**
+   * Path params. A generated dynamic route narrows this to its exact shape
+   * (`{ slug: string }`); a static or un-generated route is
+   * `Record<string, string>`.
+   */
+  params: R extends keyof RouteParamMap ? RouteParamMap[R] : Record<string, string>;
+  /** Query string, as an object. Repeated keys are last-wins at runtime. */
+  searchParams: Record<string, string | string[]>;
+  /** The full request URL string. */
+  url: string;
+  /**
+   * Present ONLY on the re-render after a failed page `action` submission
+   * (#244). `undefined` on a normal GET render. Read `actionData.fieldErrors`
+   * / `actionData.values` to surface validation errors and repopulate inputs.
+   */
+  actionData?: unknown;
+}
+
+/**
+ * The argument a layout default-export receives: every `PageProps` field plus
+ * the rendered `children`. Mirrors the `{ children, params, searchParams, url
+ * }` object packages/server/src/ssr.js passes a layout.
+ */
+export interface LayoutProps<R extends string = string> extends PageProps<R> {
+  /** The nested page / inner-layout content this layout must embed. */
+  children: TemplateResult;
+}
+
+/**
+ * The 2nd argument a `route.{js,ts}` `GET` / `POST` / … handler receives.
+ * Mirrors what packages/server/src/api.js passes: `{ params }`. The params
+ * are a plain `Record<string, string>` at the handler layer (the route table
+ * decodes each captured segment to a string), with an optional `R` generic to
+ * narrow them against a generated route the same way `PageProps` does.
+ */
+export interface RouteHandlerContext<R extends string = string> {
+  params: R extends keyof RouteParamMap ? RouteParamMap[R] : Record<string, string>;
+}