@rshono/core 1.0.0-rc.2 → 1.0.0-rc.21

package/dist/runtime/context.d.ts

@@ -1,170 +1,308 @@
 /**
- * The request context: {@link getContext} and the {@link Ctx} wrapper it returns,
- * the {@link redirect} / {@link notFound} control-flow helpers, and the
- * {@link onServerError} reporting funnel — plus the `@internal` plumbing that binds
- * a request to the async context in the first place.
- *
- * The public half of this module is re-exported by `runtime/server.ts`, which is
- * what the `@rshono/core/server` subpath resolves to; import *that* from an app. Nothing
- * here is safe in a `'use client'` module — those run in the browser, with no bound
- * request context.
+ * The request context: {@link getRequestContext} and the {@link RequestContext} it returns, the
+ * {@link redirect} / {@link notFound} control-flow helpers, and the {@link onServerError} reporting
+ * funnel — plus the `@internal` plumbing that binds a request to the async context.
+ *
+ * The public half is re-exported by `runtime/server.ts`, which is what `@rshono/core/server` resolves
+ * to; an app imports that.
  */
-import type { Context, Env, HonoRequest } from 'hono';
+import type { Context, Env } from 'hono';
 import type { CookieOptions } from 'hono/utils/cookie';
 /**
  * HTTP status codes accepted by {@link redirect}.
  *
  * - `301` Moved Permanently, `308` Permanent Redirect — cacheable, permanent.
  * - `302` Found, `307` Temporary Redirect — temporary.
- * - `303` See Other — the default; forces a `GET` on the target, which is what
- *   you almost always want after a form action (post/redirect/get).
+ * - `303` See Other — the default; forces a `GET` on the target, which is what you almost always want
+ *   after a form action (post/redirect/get).
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status#redirection_messages | MDN — redirection status codes}
  */
 export type RedirectStatus = 301 | 302 | 303 | 307 | 308;
 /**
- * Runs `fn` with the given Hono {@link Context} bound as the ambient request
- * context, so that {@link getContext} resolves to it anywhere in the call tree.
+ * Marks the request as having entered its page render, which is what makes
+ * {@link RequestContext.setHeader} and `ctx.cookies.set()` start throwing.
  *
- * Framework internal — the request handler wraps every render and action in
- * this. Application code should reach for {@link getContext} instead.
+ * @internal
+ */
+export declare function beginPageRender(c: Context): void;
+/**
+ * Runs `fn` with `c` bound as the ambient request context, so {@link getRequestContext} resolves to it
+ * anywhere in the call tree.
  *
  * @internal
  */
 export declare function runWithContext<T>(c: Context, fn: () => T): T;
 /**
- * Reads the matched route params, returning an empty object when there is no
- * active route match (rather than throwing). Shared by {@link Ctx.params} and the
- * request renderer so the fallback behaviour stays in one place.
- *
- * Framework internal — read params from {@link Ctx.params} or a page's
- * `PageProps` instead.
+ * The matched route params, or an empty object when there is no active match.
  *
  * @internal
  */
 export declare function readParams(c: Context): Record<string, string>;
 /**
- * Resolves the browser-facing {@link URL} for a request.
+ * The browser-facing {@link URL} for a request, resolved from Hono's {@link Context} — a fresh
+ * instance per call.
  *
- * `c.req.url` reflects the internal address the server was reached on, which is wrong behind a
- * proxy or load balancer. `X-Forwarded-Host` / `X-Forwarded-Proto` fix that up — **but only when
- * `trustProxy` is enabled in `rshono.config.ts`** (always the case under `rshono dev`). Those
- * headers are client-supplied: honouring them unconditionally lets anyone who can reach the server
- * dictate the origin of every absolute URL the app builds — canonical tags, emails, redirects — and
- * poison a shared cache with them. So the default is to ignore them entirely.
+ * `c.req.url` is the internal address the server was reached on, which is wrong behind a proxy;
+ * `X-Forwarded-Host` / `-Proto` correct it, but only when `trustProxy` is enabled in
+ * `rshono.config.ts` — they are client-supplied, so trusting them unconditionally would let anyone
+ * dictate the origin of every absolute URL the app builds.
  *
- * Framework internal — prefer {@link Ctx.url}, which caches the result per request.
+ * This is the form for **middleware**, which is handed `c` and runs outside the request context — and
+ * so the way to give Hono's own middleware the origin the browser actually used. In a server component
+ * or action, prefer {@link RequestContext.url}, the same value cached per request.
  *
- * @internal
+ * @param c - The Hono {@link Context} for the request.
+ * @returns The browser-facing URL — proxy-corrected under `trustProxy`, `c.req.url` otherwise.
+ *
+ * @example
+ * ```ts
+ * // src/server.ts — a CSRF check that still works behind a proxy that rewrites Host
+ * import { publicUrl } from '@rshono/core/server';
+ * import { csrf } from 'hono/csrf';
+ *
+ * server.use(csrf({ origin: (origin, c) => origin === publicUrl(c).origin }));
+ * ```
+ *
+ * @see {@link https://www.rshono.com/docs/configuration#proxy-headers | Docs — proxy headers}
  */
 export declare function publicUrl(c: Context): URL;
 /**
- * The environment available to a request: Cloudflare/Workers `Bindings` merged
- * with process env vars. Values not declared in `Bindings` are typed as
- * `string | undefined`. See {@link Ctx.env}.
+ * The environment available to a request: Workers `Bindings` merged with process env vars. Values not
+ * declared in `Bindings` are typed as `string | undefined`. See {@link RequestContext.env}.
+ *
+ * @see {@link https://hono.dev/docs/getting-started/cloudflare-workers#bindings | Hono — bindings}
  */
 export type EnvVars<E extends Env> = E['Bindings'] & Record<string, string | undefined>;
 /**
- * Ergonomic, read-mostly wrapper around Hono's {@link Context} for use inside
- * server components and server actions.
+ * Read-mostly wrapper around Hono's {@link Context}, for server components and server actions.
+ *
+ * Obtain one with {@link getRequestContext}, or take it off a page's `ctx` prop — the same object.
+ * Never construct it yourself. One instance is reused for the whole request, so its lazy getters
+ * ({@link RequestContext.url}, {@link RequestContext.env}) are computed at most once.
  *
- * Obtain one with {@link getContext}, or — in a page component — take it straight
- * off the `ctx` prop, which is this same object. Never construct it yourself. One
- * instance is reused for the lifetime of a request, so its lazy getters
- * ({@link Ctx.url}, {@link Ctx.env}) are computed at most once.
+ * The eight members that only throw — `redirect`, `notFound`, `json`, `text`, `html`, `body`, `status`,
+ * `header` — are **permanent, and exist to throw**. Every one of them is a silent no-op when reached through
+ * {@link RequestContext.hono} from a page, so a stub that names the thing that does work is the difference
+ * between a message and a page that renders while quietly ignoring half of what it was asked for. They carry
+ * `@deprecated` for the strike-through an editor draws with it, not because they are on the way out: nothing
+ * will un-deprecate or remove them, and dropping them would leave `ctx.redirect('/x')` as
+ * "property does not exist", which says what is wrong and not what to do.
  *
- * @typeParam E - The Hono {@link Env} describing this app's `Bindings` and
- *   `Variables`, so {@link Ctx.var} and {@link Ctx.env} stay typed.
+ * @typeParam E - The Hono {@link Env} describing this app's `Bindings` and `Variables`, so
+ *   {@link RequestContext.var} and {@link RequestContext.env} stay typed.
  *
  * @example
  * ```tsx
- * import { getContext } from '@rshono/core/server';
+ * import { getRequestContext } from '@rshono/core/server';
  *
  * export default async function Whoami() {
- *   const ctx = getContext();
+ *   const ctx = getRequestContext();
  *   const session = ctx.cookies.get('session');
  *   return <p>{ctx.url.pathname} — {session ?? 'anonymous'}</p>;
  * }
  * ```
+ *
+ * @see {@link https://www.rshono.com/docs/api#rshonocoreserver | Docs — `@rshono/core/server`}
+ * @see {@link https://hono.dev/docs/api/context | Hono — Context}, reachable in full via {@link RequestContext.hono}
  */
-export declare class Ctx<E extends Env = Env> {
+export declare class RequestContext<E extends Env = Env> {
     #private;
+    /**
+     * One instance is created per request and handed out by {@link getRequestContext} or the `ctx` page
+     * prop. Application code never calls this.
+     *
+     * @internal
+     */
     constructor(c: Context<E>);
     /**
-     * The underlying Hono {@link Context}. Escape hatch for anything this wrapper does not expose.
+     * The underlying Hono {@link Context} — the escape hatch for what this wrapper does not expose, such
+     * as `executionCtx.waitUntil()` on Workers.
      *
-     * A getter over a private field rather than a plain property, so it is not an *own enumerable*
-     * one — which matters more than it looks. React's diagnostic for a value that cannot be sent to a
-     * client component (`describeObjectForErrorMessage`) walks `Object.keys` recursively with no depth
-     * limit and no cycle guard, and the Hono context graph reaches the socket and the whole server
-     * through `req.raw` and `env`. While this was a plain property, passing a `Ctx` to a `'use client'`
-     * component blew the stack *inside that message builder* — so React's actual, accurate "you cannot
-     * pass this" error never got printed. Hidden from `Object.keys`, the walk stops here.
+     * Its response builders (`redirect`, `json`, `body`, `status`, …) still do nothing from inside a
+     * page: reaching them through here bypasses the errors the stubs on this class throw, it does not
+     * make them work.
+     *
+     * @example
+     * ```ts
+     * getRequestContext().hono.executionCtx.waitUntil(logAsync()); // Workers
+     * ```
+     *
+     * @see {@link https://hono.dev/docs/api/context | Hono — Context}
      */
-    get raw(): Context<E>;
-    /** The parsed Hono request (`c.req`) — headers, body parsing, param access, etc. */
-    get req(): HonoRequest;
+    get hono(): Context<E>;
     /**
-     * The browser-facing request URL, proxy-header aware (see {@link publicUrl}) —
-     * read `url.pathname`, `url.searchParams` and the rest off it. Parsed once and
-     * cached, so the same instance comes back on every read within a request; treat
-     * it as read-only for that reason.
+     * The parsed request — method, headers, path params, query and the body readers. Hono's
+     * {@link Context.req}, unwrapped, so `ctx.req.header('authorization')` rather than
+     * `ctx.hono.req.header(…)`.
+     *
+     * Reads only; setting a *response* header is {@link RequestContext.setHeader}, deliberately spelled
+     * differently.
+     *
+     * @example
+     * ```ts
+     * const ctx = getRequestContext();
+     * ctx.req.method;                     // 'GET'
+     * ctx.req.header('authorization');    // string | undefined
+     * ctx.req.query('tab');               // string | undefined
+     * ```
+     *
+     * @see {@link https://hono.dev/docs/api/request | Hono — HonoRequest}
      */
-    get url(): URL;
-    /** The HTTP method of the request, e.g. `GET` or `POST`. */
-    get method(): string;
+    get req(): Context<E>['req'];
     /**
-     * Matched route params, e.g. `{ id }` for a `/users/[id]` route. Returns an
-     * empty object when there is no active route match (rather than throwing).
+     * Matched route params for this request, e.g. `{ id: '42' }` for `/profile/:id`. Empty when no route
+     * matched.
+     *
+     * A page is handed the same record as its `params` prop, typed key-by-key from its route path, and
+     * that is the better read where it exists. This is for everywhere else — a nested server component,
+     * or a `'use server'` action.
      */
     get params(): Record<string, string>;
     /**
-     * Typed variables set by middleware via `c.set('user', …)`, read here as
-     * `ctx.var.user`. Type them by parameterising this class's {@link Env}.
+     * The browser-facing request URL. Parsed once and cached, so every read within a request returns the
+     * same instance — treat it as read-only.
+     *
+     * `X-Forwarded-Host` / `-Proto` are honoured only when `trustProxy` is enabled in
+     * `rshono.config.ts`, since any client can send them.
+     *
+     * @example `const tab = getRequestContext().url.searchParams.get('tab');`
+     *
+     * @see {@link https://www.rshono.com/docs/configuration#proxy-headers | Docs — proxy headers}
+     */
+    get url(): URL;
+    /**
+     * Typed variables set by middleware via `c.set('user', …)`, read here as `ctx.var.user`. Type them by
+     * parameterising this class's {@link Env}.
+     *
+     * @example
+     * ```ts
+     * type AppEnv = { Variables: { user: { id: string } } };
+     * const { user } = getRequestContext<AppEnv>().var; // typed, set by your middleware
+     * ```
+     *
+     * @see {@link https://hono.dev/docs/api/context#var | Hono — c.var}
+     * @see {@link https://www.rshono.com/docs/hono#typing-the-context | Docs — typing the context}
      */
     get var(): Readonly<E['Variables']>;
     /**
-     * Environment for the request: process env vars merged with runtime bindings
-     * (bindings win on conflict). Computed once and cached.
+     * Environment for the request: process env vars, merged on a bindings platform with the bindings, which
+     * win on conflict.
+     *
+     * The `process.env` half is snapshotted **once per process**, not per request — enumerating it crosses
+     * into the host environment, and doing that on every request is a cost with nothing to show for it. So a
+     * `process.env` mutation made after the first `ctx.env` read anywhere in the process is never seen here.
+     * Read `process.env` directly if you have one. The bindings half is per request, since it comes off the
+     * request's own Hono context.
+     *
+     * Bindings are merged **only where the platform supplies them** — `deploy: 'cloudflare'`, today. Hono's
+     * `c.env` is whatever the host passed as the second argument to `app.fetch`, and off Workers that is the
+     * adapter's own private state: `{ incoming, outgoing }` on Node and Vercel, the entire invocation —
+     * headers, cookies, `authorization` — on Lambda. Merging it would make `ctx.env` uncloneable on one and
+     * a disclosure vector on the other, both behind names this type declares `string | undefined`. Reach for
+     * {@link RequestContext.hono}`.env` if you really do want the adapter's argument.
+     *
+     * @example `const key = getRequestContext().env.STRIPE_SECRET_KEY;`
      *
-     * @example `const key = getContext().env.STRIPE_SECRET_KEY;`
+     * @see {@link https://hono.dev/docs/api/context#env | Hono — c.env}
+     * @see {@link https://www.rshono.com/docs/configuration#environment-and-secrets | Docs — environment and secrets}
      */
     get env(): EnvVars<E>;
-    /** Sets a response header. Thin pass-through to `c.header(name, value)`. */
-    header(name: string, value: string): void;
     /**
      * Read and write request/response cookies.
      *
      * @example
      * ```ts
-     * const ctx = getContext();
+     * const ctx = getRequestContext();
      * ctx.cookies.get('session');                       // string | undefined
      * ctx.cookies.set('session', id, { httpOnly: true, sameSite: 'Lax', path: '/' });
      * ctx.cookies.delete('session', { path: '/' });
      * ```
+     *
+     * @see {@link https://hono.dev/docs/helpers/cookie | Hono — cookie helper}, which this wraps
      */
     cookies: {
-        /** Reads a single cookie by name, or `undefined` if absent. */
+        /** Reads a single cookie by name, or `undefined` if absent. Safe anywhere, a page included. */
         get: (name: string) => string | undefined;
-        /** Reads every cookie as a `{ name: value }` record. */
+        /** Reads every cookie as a `{ name: value }` record. Safe anywhere, a page included. */
         all: () => Record<string, string>;
-        /** Sets a cookie on the response. See Hono's {@link CookieOptions} for `path`, `httpOnly`, `maxAge`, etc. */
+        /**
+         * Sets a cookie on the response. See Hono's {@link CookieOptions} for `path`, `httpOnly`, `maxAge`
+         * and the rest.
+         *
+         * **Throws inside a page render** — a `Set-Cookie` is a special case of
+         * {@link RequestContext.setHeader}. Set cookies from a `'use server'` action, or with Hono's
+         * `setCookie(c, …)` in middleware and endpoint routes.
+         *
+         * @throws If called while a page is rendering, where it could not reach the browser reliably.
+         *
+         * @see {@link https://hono.dev/docs/helpers/cookie#options | Hono — cookie options}
+         */
         set: (name: string, value: string, options?: CookieOptions) => void;
-        /** Clears a cookie. Pass the same `path`/`domain` it was set with so the browser matches it. */
+        /**
+         * Clears a cookie. Pass the same `path`/`domain` it was set with so the browser matches it.
+         * Throws inside a page render, exactly as `set` does.
+         *
+         * @throws If called while a page is rendering.
+         */
         delete: (name: string, options?: CookieOptions) => void;
     };
+    /**
+     * Sets a header on the response — from a `'use server'` action, which is the one place a request
+     * context exists *and* the response is still open.
+     *
+     * From inside a page it throws: a page streams, so its response head is already committed by then,
+     * and the write would land on a full page load but vanish on a soft navigation.
+     *
+     * Middleware and `{ type: 'endpoint' }` routes are handed Hono's `c` directly and use `c.header(…)`.
+     * That is also where a header belonging to the *page* goes — `Cache-Control`, `X-Robots-Tag` — since
+     * middleware runs before the render.
+     *
+     * @param name - Header name, case-insensitive.
+     * @param value - Header value.
+     * @param options - `{ append: true }` to add another value rather than replace.
+     * @throws If called while a page is rendering, where it could not reach the browser reliably.
+     *
+     * @example
+     * ```ts
+     * 'use server';
+     * export async function logout() {
+     *   const ctx = getRequestContext();
+     *   ctx.cookies.delete('session', { path: '/' });
+     *   ctx.setHeader('clear-site-data', '"cache", "storage"');
+     *   redirect('/');
+     * }
+     * ```
+     */
+    setHeader(name: string, value: string, options?: {
+        append?: boolean;
+    }): void;
+    /** @deprecated Not available on a page's context — use `redirect()` from `@rshono/core/server`. */
+    redirect(..._args: unknown[]): never;
+    /** @deprecated Not available on a page's context — use `notFound()` from `@rshono/core/server`. */
+    notFound(..._args: unknown[]): never;
+    /** @deprecated A page renders JSX. For a JSON response, use an `{ type: 'endpoint' }` route. */
+    json(..._args: unknown[]): never;
+    /** @deprecated A page renders JSX. For a text response, use an `{ type: 'endpoint' }` route. */
+    text(..._args: unknown[]): never;
+    /** @deprecated A page renders JSX, which the framework turns into HTML for you. */
+    html(..._args: unknown[]): never;
+    /** @deprecated Not available on a page's context. To read the request body, use `ctx.req`. */
+    body(..._args: unknown[]): never;
+    /** @deprecated A page's status is set by the framework — use `notFound()`, or an endpoint route. */
+    status(..._args: unknown[]): never;
+    /** @deprecated Renamed — use `ctx.setHeader(name, value)`, which is valid from a `'use server'` action. */
+    header(..._args: unknown[]): never;
 }
 /**
- * Returns the {@link Ctx} for the current request.
- *
- * This is the primary entry point for reading request data from a server
- * component or server action — the URL, cookies, params, env, and middleware
- * variables. The returned wrapper is memoised per request, so repeated calls in
- * the same request are cheap and return the same instance.
+ * The {@link RequestContext} for the current request — URL, cookies, params, env and middleware
+ * variables — read from a server component or a server action. Memoised per request, so repeated calls
+ * return the same instance.
  *
- * A **page** component is handed the very same object as its `ctx` prop, so this
- * import is for everywhere else: a nested server component, or a `'use server'`
- * action module — neither of which receives props from the framework.
+ * A page is handed that same object as its `ctx` prop, so this import is for everywhere else: a nested
+ * server component, or a `'use server'` action module.
  *
- * @typeParam E - The app's Hono {@link Env}, to type {@link Ctx.var} and {@link Ctx.env}.
+ * @typeParam E - The app's Hono {@link Env}, to type {@link RequestContext.var} and {@link RequestContext.env}.
  * @throws If called at module load, where there is no ambient context to resolve.
  * @throws If called while prerendering a `render: 'static'` route, which has no
  *   per-request context at build time — mark the route `render: 'dynamic'` instead.
@@ -172,78 +310,114 @@ export declare class Ctx<E extends Env = Env> {
  * @example
  * ```ts
  * 'use server';
- * import { getContext, redirect } from '@rshono/core/server';
+ * import { getRequestContext, redirect } from '@rshono/core/server';
  *
  * export async function login(form: FormData) {
- *   getContext().cookies.set('session', String(form.get('email')), { httpOnly: true });
+ *   getRequestContext().cookies.set('session', String(form.get('email')), { httpOnly: true });
  *   redirect('/dashboard');
  * }
  * ```
+ *
+ * @see {@link https://www.rshono.com/docs/api#rshonocoreserver | Docs — `@rshono/core/server`}
  */
-export declare function getContext<E extends Env = Env>(): Ctx<E>;
+export declare function getRequestContext<E extends Env = Env>(): RequestContext<E>;
 /**
- * Redirects the request to `location` by throwing a control signal that the
- * framework catches and turns into an HTTP redirect response.
+ * Redirects the request to `location`, by throwing a control signal the framework turns into an HTTP
+ * redirect.
  *
- * Because it throws, it never returns — TypeScript narrows away any code after
- * the call, and you do not need to `return` it. Do not wrap it in a `try/catch`
- * that swallows the signal.
+ * Because it throws it never returns, so TypeScript narrows away everything after the call and there
+ * is nothing to `return`. Don't wrap it in a `try/catch` that swallows the signal.
  *
  * @param location - Absolute path or URL to redirect to, e.g. `/dashboard`.
- * @param status - Redirect {@link RedirectStatus}; defaults to `303` (See Other),
- *   the correct choice after a form action so the browser follows up with a `GET`.
+ * @param status - Redirect {@link RedirectStatus}; defaults to `303` (See Other), which is what makes
+ *   the browser follow up with a `GET` after a form action.
  *
  * @example
  * ```ts
- * const session = getContext().cookies.get('session');
+ * const session = getRequestContext().cookies.get('session');
  * if (!session) redirect('/login');
  * // session is defined below this line
  * ```
  */
 export declare function redirect(location: string, status?: RedirectStatus): never;
 /**
- * Aborts the current render with a 404, rendering the app's not-found page.
+ * Aborts the current render with a 404, rendering the app's `notFound` page.
  *
- * Like {@link redirect}, this throws a control signal and never returns, so
- * TypeScript narrows away everything after the call. Do not catch-and-swallow it.
+ * Like {@link redirect} it throws a control signal and never returns, so TypeScript narrows away
+ * everything after the call. Don't catch-and-swallow it.
+ *
+ * **A real 404 status is only possible on a document load.** A soft navigation asks for a flight payload,
+ * and that response is committed as `200 text/x-component` the moment the render hands its stream back —
+ * before anything is awaited — so there is no shell to beat and calling this from the first line of a page
+ * is already too late. The signal still reaches the browser as a digest, and the client recovers by
+ * reloading the page for real: correct, but an extra round trip and a full document parse every time. Unlike
+ * {@link redirect}, which the same client turns into a soft navigation and which costs nothing. Where the
+ * status matters — a crawler, a monitor — decide in Hono middleware, ahead of the render.
  *
  * @example
  * ```tsx
- * const user = await db.user.find(getContext().params.id);
- * if (!user) notFound();
- * return <Profile user={user} />; // user is non-null here
+ * export default async function Page({ params }: PageProps<'/users/:id'>) {
+ *   const user = await db.user.find(params.id);
+ *   if (!user) notFound();
+ *   return <Profile user={user} />; // user is non-null here
+ * }
  * ```
  */
 export declare function notFound(): never;
 /**
- * Which stage of a request produced an error handed to an {@link ServerErrorHandler}.
+ * Which stage of a request produced an error handed to a {@link ServerErrorHandler}.
  *
  * - `action` — a `'use server'` function threw. React sends the client an opaque marker with no
  *   message in production, so this is the only place the real error is visible.
  * - `render` — a server component threw while the flight payload was being produced.
  * - `ssr` — SSR failed before the HTML shell could be sent, so the `error` page was unreachable too.
- * - `request` — anything else that reached the top-level handler, including a thrown endpoint route.
+ * - `request` — anything else that reached the top-level handler, a thrown endpoint route included.
  */
 export type ServerErrorSource = 'action' | 'render' | 'ssr' | 'request';
-/** What an {@link ServerErrorHandler} is told about an error, beyond the error itself. */
-export interface ServerErrorContext {
+/**
+ * What an {@link ServerErrorHandler} is told about an error, beyond the error itself.
+ *
+ * @typeParam E - The app's Hono {@link Env}, to type {@link ServerErrorContext.hono}'s `var` and `env`.
+ */
+export interface ServerErrorContext<E extends Env = Env> {
     /** The stage that produced it — see {@link ServerErrorSource}. */
     source: ServerErrorSource;
     /** The request being served, for the URL, method and headers. */
     request: Request;
+    /**
+     * The Hono {@link Context} for this request — `hono.var` for whatever middleware put there, such as a
+     * request id to correlate the report on, and `hono.env` for a platform that passes bindings.
+     *
+     * Handed over rather than left to {@link getRequestContext}, which a handler cannot reach: an error with
+     * `source: 'request'` is reported from the top-level handler, which runs outside the ambient context.
+     */
+    hono: Context<E>;
+    /**
+     * Holds the invocation open until `promise` settles, where the platform has something to ask.
+     *
+     * Reporting is what this hook exists for, and on a serverless platform a report started here is cut off
+     * the moment the response ends unless something keeps the invocation alive. On Cloudflare Workers that is
+     * `executionCtx.waitUntil`, which this calls. On the `node` and `vercel` targets there is nothing to hold
+     * open — the process outlives the response — so it is a no-op and the report finishes on its own. On
+     * `aws-lambda` it is a no-op as well, because `hono/aws-lambda`'s streaming handler exposes no execution
+     * context to ask; a slow report there is best-effort, so prefer a tracker that batches over one that
+     * round-trips per error.
+     *
+     * A rejection is logged rather than propagated: reporting can never fail a request.
+     */
+    waitUntil: (promise: Promise<unknown>) => void;
 }
 /** Handler registered with {@link onServerError}. Called for the side effect; its return value is ignored. */
-export type ServerErrorHandler = (error: unknown, context: ServerErrorContext) => void;
+export type ServerErrorHandler<E extends Env = Env> = (error: unknown, context: ServerErrorContext<E>) => void;
 /**
  * Registers a handler for every error the framework catches, so they can reach an error tracker
  * (Sentry, Datadog, a log pipeline) instead of only `stderr`.
  *
- * Call it **once, at the top level of `src/server.ts`** — that module is imported as the server
- * starts, before any request is served. Registering again replaces the previous handler.
+ * Call it once, at the top level of `src/server.ts`, which is imported as the server starts.
+ * Registering again replaces the previous handler. Errors still go to `stderr` either way, and a
+ * handler that throws is caught and logged — reporting can never fail a request.
  *
- * Errors are still written to `stderr` either way, so a handler adds a destination rather than
- * replacing one. A handler that throws is caught and logged: reporting must never be able to fail
- * a request.
+ * @typeParam E - The app's Hono {@link Env}, to type the `hono` context the handler is given.
  *
  * @example
  * ```ts
@@ -251,21 +425,28 @@ export type ServerErrorHandler = (error: unknown, context: ServerErrorContext) =
  * import * as Sentry from '@sentry/node';
  * import { onServerError } from '@rshono/core/server';
  *
- * onServerError((error, { source, request }) => {
- *   Sentry.captureException(error, { tags: { source }, extra: { url: request.url } });
+ * onServerError((error, { source, request, hono, waitUntil }) => {
+ *   // `waitUntil` so a serverless invocation is not frozen before the report is sent.
+ *   waitUntil(
+ *     Sentry.captureException(error, {
+ *       tags: { source, requestId: hono.var.requestId },
+ *       extra: { url: request.url },
+ *     }),
+ *   );
  * });
  * ```
+ *
+ * @see {@link https://www.rshono.com/docs/hono#error-reporting | Docs — error reporting}
  */
-export declare function onServerError(handler: ServerErrorHandler): void;
+export declare function onServerError<E extends Env = Env>(handler: ServerErrorHandler<E>): void;
 /**
- * Logs an error and forwards it to the registered {@link ServerErrorHandler}.
- *
- * Framework internal — the single funnel every caught server-side error goes through, so that
- * adding a reporting destination is one registration rather than a hook per call site.
+ * Logs an error and forwards it to the registered {@link ServerErrorHandler} — the single funnel every
+ * caught server-side error goes through.
  *
  * @internal
  */
-export declare function reportServerError(error: unknown, info: ServerErrorContext & {
+export declare function reportServerError(error: unknown, info: {
+    source: ServerErrorSource;
+    hono: Context;
     message: string;
 }): void;
-//# sourceMappingURL=context.d.ts.map