@rshono/core 1.0.0-rc.0 → 1.0.0-rc.10

package/dist/runtime/context.js

@@ -1,6 +1,6 @@
 /// <reference path="../types/rshono-config.d.ts" />
 /**
- * The request context: {@link getContext} and the {@link Ctx} wrapper it returns,
+ * The request context: {@link getRequestContext} and the {@link RequestContext} 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.
@@ -14,38 +14,77 @@ import { deleteCookie, getCookie, setCookie } from 'hono/cookie';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { NotFoundSignal, RedirectSignal } from './control.js';
 const contextStorage = new AsyncLocalStorage();
-/** One {@link Ctx} per Hono {@link Context}, so repeated `getContext()` calls in a request share its lazy getters. */
+/** One {@link RequestContext} per Hono {@link Context}, so repeated `getRequestContext()` calls in a request share its lazy getters. */
 const wrappers = new WeakMap();
+/**
+ * Requests whose page render has begun — the point past which nothing can change the response head.
+ *
+ * A `WeakSet` keyed on the Hono {@link Context} rather than a field on {@link RequestContext},
+ * so marking a request costs nothing for the pages that never read their context: the wrapper is
+ * built lazily by {@link getRequestContext} and this must not be what forces it into existence.
+ */
+const rendering = new WeakSet();
+/**
+ * Marks the request as having entered its page render, which is what makes
+ * {@link RequestContext.setHeader} and `ctx.cookies.set()` start throwing.
+ *
+ * Framework internal — `renderComponent` calls this immediately before handing the page to React.
+ * Everything that legitimately writes to the response (middleware, a `'use server'` action, an
+ * endpoint route) has already run by then, so none of them are affected.
+ *
+ * @internal
+ */
+export function beginPageRender(c) {
+    rendering.add(c);
+}
+/**
+ * The shared explanation for a response mutation that arrived too late, thrown by
+ * {@link RequestContext.setHeader} and the `cookies` writers.
+ *
+ * Refusing beats the alternative, which was silent *and* inconsistent: a page setting a cookie got it
+ * on a full page load and lost it on a soft navigation, because the flight stream's response head is
+ * committed before the page component's first line runs. Nothing inside the render can fix that, so
+ * the message says where the write does belong instead.
+ */
+function tooLateToWrite(call) {
+    throw new Error(`[rshono] ${call} was called while rendering a page, which is too late to affect the response. ` +
+        'A page streams, so its response head is already committed by the time the component runs — the ' +
+        'write would land on a full page load and be silently dropped on a soft navigation. Do it from a ' +
+        "'use server' action instead; or, in middleware and { type: 'endpoint' } routes — which are handed " +
+        "Hono's `c` directly and run outside the request context — with `c.header(…)` / `setCookie(c, …)`.");
+}
+/** The shared explanation for a Hono `Context` member that a page has no way to use. See the stubs on {@link RequestContext}. */
+function notOnContext(call, instead) {
+    throw new Error(`[rshono] ctx.${call} does not exist. A page returns JSX and the framework builds the response from it, ` +
+        `so Hono's response builders have nothing to return to. ${instead}`);
+}
 /**
  * `process.env`, snapshotted on first read.
  *
- * It is not a plain object — every enumeration crosses into the host environment, which made
- * spreading it (~20µs) by far the most expensive thing {@link Ctx.env} did, once per request that
- * touched it. Snapshotted lazily rather than at module load because `loadEnvFiles()` runs *after*
- * this module is imported, so an eager copy would miss everything from `.env`. The trade-off: a
- * `process.env` mutation after the first `ctx.env` read is not picked up.
+ * Enumerating it crosses into the host environment, which made the spread (~20µs) by far the most
+ * expensive thing {@link RequestContext.env} did, once per request that touched it. Lazily rather
+ * than at module load, because `loadEnvFiles()` runs *after* this module is imported and an eager
+ * copy would miss everything from `.env`. The trade-off: a `process.env` mutation after the first
+ * `ctx.env` read is not picked up.
  */
 let envSnapshot;
 function processEnv() {
     return (envSnapshot ??= typeof process !== 'undefined' && process.env ? { ...process.env } : {});
 }
 /**
- * True when this process is the SSG build prerendering `render: 'static'` routes,
- * rather than a server handling real requests. `build.ts` sets `RSHONO_PRERENDER`
- * before importing the app bundle and starting the prerender pass; the app bundle
- * inlines its own copy of this module, so a shared `process.env` (not a module-level
- * flag) is what reliably crosses that boundary. Read by {@link getContext} to turn a
- * static route's request-context read into a clear build-time error instead of
- * silently baking synthetic build-time values (a `localhost` URL, no cookies, build
- * env) into the snapshot.
+ * True when this process is the SSG build prerendering `render: 'static'` routes rather than a server
+ * handling real requests. `build.ts` sets `RSHONO_PRERENDER` before importing the app bundle, which
+ * inlines its own copy of this module — so `process.env` is what crosses that boundary, not a
+ * module-level flag. {@link getRequestContext} reads it to fail loudly instead of baking synthetic
+ * build-time values (a `localhost` URL, no cookies, build env) into the prerendered page.
  */
 const prerendering = typeof process !== 'undefined' && !!process.env?.RSHONO_PRERENDER;
 /**
  * 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.
+ * context, so that {@link getRequestContext} resolves to it anywhere in the call tree.
  *
  * Framework internal — the request handler wraps every render and action in
- * this. Application code should reach for {@link getContext} instead.
+ * this. Application code should reach for {@link getRequestContext} instead.
  *
  * @internal
  */
@@ -53,12 +92,10 @@ export function runWithContext(c, fn) {
     return contextStorage.run(c, fn);
 }
 /**
- * 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.
+ * The matched route params, or an empty object when there is no active match.
  *
- * Framework internal — read params from {@link Ctx.params} or a page's
- * `PageProps` instead.
+ * Framework internal — the request renderer calls this to build a page's `params` prop, and
+ * {@link RequestContext.params} caches it. Read them from that prop, or from `ctx.params`.
  *
  * @internal
  */
@@ -80,18 +117,36 @@ function firstForwardedValue(header) {
 // Read through `typeof` so that degrades to the safe answer — don't trust — instead of a ReferenceError.
 const trustProxy = typeof __RSHONO_CONFIG__ !== 'undefined' && __RSHONO_CONFIG__.trustProxy;
 /**
- * Resolves the browser-facing {@link URL} for a request.
+ * Resolves the browser-facing {@link URL} for a request, from a Hono {@link Context}.
  *
- * `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` reflects the internal address the server was reached on, which is wrong behind a proxy.
+ * `X-Forwarded-Host` / `X-Forwarded-Proto` fix that up — **but only when `trustProxy` is enabled in
+ * `rshono.config.ts`** (always so under `rshono dev`). They are client-supplied, so honouring them
+ * unconditionally would let anyone who can reach the server dictate the origin of every absolute URL
+ * the app builds, and poison a shared cache with it.
  *
- * 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. In
+ * a server component or a `'use server'` action prefer {@link RequestContext.url}, which is this same
+ * value cached per request.
  *
- * @internal
+ * Its main use is giving Hono's own middleware the origin the browser actually used, since they all
+ * read `c.req.url` on their own and so see the internal one:
+ *
+ * @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 }));
+ * ```
+ *
+ * A fresh instance per call, so mutating it disturbs nothing else.
+ *
+ * @param c - The Hono {@link Context} for the request.
+ * @returns The browser-facing URL — proxy-corrected under `trustProxy`, `c.req.url` otherwise.
+ *
+ * @see {@link https://www.rshono.com/docs/configuration#proxy-headers | Docs — proxy headers}
  */
 export function publicUrl(c) {
     const url = new URL(c.req.url);
@@ -116,73 +171,125 @@ export function publicUrl(c) {
  * Ergonomic, read-mostly wrapper around Hono's {@link Context} for use inside
  * server components and server actions.
  *
- * Obtain one with {@link getContext}, or — in a page component — take it straight
+ * Obtain one with {@link getRequestContext}, 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.
+ * ({@link RequestContext.url}, {@link RequestContext.env}) are computed at most once.
  *
  * @typeParam E - The Hono {@link Env} describing this app's `Bindings` and
- *   `Variables`, so {@link Ctx.var} and {@link Ctx.env} stay typed.
+ *   `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 class Ctx {
+export class RequestContext {
     #raw;
     #url;
     #env;
+    #params;
+    /**
+     * Framework internal — one instance is created per request and handed to you by
+     * {@link getRequestContext} or the `ctx` page prop. Application code never calls this.
+     *
+     * @internal
+     */
     constructor(c) {
         this.#raw = c;
     }
     /**
-     * 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.
+     *
+     * Its response builders (`redirect`, `notFound`, `json`, `body`, `status`, …) still do nothing from
+     * inside a page, for the reason the stubs on this class explain: reaching them through here
+     * bypasses the error, it does not make them work.
+     *
+     * @example
+     * ```ts
+     * getRequestContext().hono.executionCtx.waitUntil(logAsync()); // 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.
+     * @see {@link https://hono.dev/docs/api/context | Hono — Context}
      */
-    get raw() {
+    // A prototype getter rather than a plain property, so it is not *own enumerable*. React's
+    // diagnostic for a value that cannot be sent to a client component 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` — as a plain property this blew the stack inside the
+    // message builder, so React's accurate "you cannot pass this" error never got printed. Every member
+    // here is a getter or method for the same reason; `cookies` is the one own enumerable property, and
+    // it is a shallow object of four functions.
+    get hono() {
         return this.#raw;
     }
-    /** The parsed Hono request (`c.req`) — headers, body parsing, param access, etc. */
+    /**
+     * 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 in a
+     * different place — Hono's `c.header()` writing the response while `c.req.header()` reads the
+     * request is a well-worn source of confusion.
+     *
+     * @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 req() {
         return this.#raw.req;
     }
     /**
-     * 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.
+     * Matched route params for this request, e.g. `{ id: '42' }` for `/profile/:id`. Empty when there
+     * is no active route match.
+     *
+     * 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 is available. This is for everywhere else — a nested server
+     * component, or a `'use server'` action — which get no props from the framework.
      */
-    get url() {
-        return (this.#url ??= publicUrl(this.#raw));
-    }
-    /** The HTTP method of the request, e.g. `GET` or `POST`. */
-    get method() {
-        return this.#raw.req.method;
+    get params() {
+        return (this.#params ??= readParams(this.#raw));
     }
     /**
-     * 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).
+     * The browser-facing request URL — 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.
+     *
+     * `X-Forwarded-Host` / `-Proto` are honoured only when `trustProxy` is enabled in
+     * `rshono.config.ts`, since any client can send them.
+     *
+     * @see {@link https://www.rshono.com/docs/configuration#proxy-headers | Docs — proxy headers}
      */
-    get params() {
-        return readParams(this.#raw);
+    get url() {
+        return (this.#url ??= publicUrl(this.#raw));
     }
     /**
      * 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() {
         return this.#raw.var;
@@ -191,7 +298,10 @@ export class Ctx {
      * Environment for the request: process env vars merged with runtime bindings
      * (bindings win on conflict). Computed once and cached.
      *
-     * @example `const key = getContext().env.STRIPE_SECRET_KEY;`
+     * @example `const key = getRequestContext().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() {
         if (this.#env)
@@ -200,47 +310,137 @@ export class Ctx {
         // The snapshot is shared, so hand it back as-is when there are no bindings to merge over it.
         return (this.#env = (bindings ? { ...processEnv(), ...bindings } : processEnv()));
     }
-    /** Sets a response header. Thin pass-through to `c.header(name, value)`. */
-    header(name, value) {
-        this.#raw.header(name, value);
-    }
     /**
      * 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) => getCookie(this.#raw, name),
-        /** Reads every cookie as a `{ name: value }` record. */
+        /** Reads every cookie as a `{ name: value }` record. Safe anywhere, a page included. */
         all: () => getCookie(this.#raw),
-        /** Sets a cookie on the response. See Hono's {@link CookieOptions} for `path`, `httpOnly`, `maxAge`, etc. */
-        set: (name, value, options) => setCookie(this.#raw, name, value, options),
-        /** Clears a cookie. Pass the same `path`/`domain` it was set with so the browser matches it. */
+        /**
+         * Sets a cookie on the response. See Hono's {@link CookieOptions} for `path`, `httpOnly`,
+         * `maxAge`, etc.
+         *
+         * **Throws inside a page render** — see {@link RequestContext.setHeader}, of which a `Set-Cookie`
+         * is a special case. 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, value, options) => {
+            this.#assertWritable('ctx.cookies.set()');
+            setCookie(this.#raw, name, value, options);
+        },
+        /**
+         * 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, options) => {
+            this.#assertWritable('ctx.cookies.delete()');
             deleteCookie(this.#raw, name, options);
         },
     };
+    /** Guards every write that has to reach the response head. See {@link tooLateToWrite}. */
+    #assertWritable(call) {
+        if (rendering.has(this.#raw))
+            tooLateToWrite(call);
+    }
+    /**
+     * 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 by then the response head is committed. Hono's
+     * `c.header()` fails there silently and inconsistently — landing on a full page load, vanishing on
+     * a soft navigation — so this refuses rather than doing it half the time.
+     *
+     * Middleware and `{ type: 'endpoint' }` routes run outside the request context but are handed
+     * Hono's `c` directly, so they use `c.header(…)`. That is also where a header belonging to the
+     * *page* rather than to one action 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, value, options) {
+        this.#assertWritable('ctx.setHeader()');
+        this.#raw.header(name, value, options);
+    }
+    // Hono's response builders, restated as errors naming what to use instead. A page returns JSX and
+    // `renderComponent` builds the response from it, so every one of these is a silent no-op through
+    // `ctx.hono`. `@deprecated` is the compile-time signal — an editor strikes them through in
+    // autocomplete — and the thrown message is the one that explains. Each takes `...args: unknown[]`
+    // it never reads so that `ctx.redirect('/dashboard')` reaches that message rather than stopping at
+    // "Expected 0 arguments, but got 1".
+    /** @deprecated Not available on a page's context — use `redirect()` from `@rshono/core/server`. */
+    redirect(...args) {
+        return notOnContext('redirect(location, status?)', "Use `redirect()` from '@rshono/core/server', which throws a signal the framework turns into a real redirect.");
+    }
+    /** @deprecated Not available on a page's context — use `notFound()` from `@rshono/core/server`. */
+    notFound(...args) {
+        return notOnContext('notFound()', "Use `notFound()` from '@rshono/core/server', which aborts the render and shows the app's not-found page.");
+    }
+    /** @deprecated A page renders JSX. For a JSON response, use an `{ type: 'endpoint' }` route. */
+    json(...args) {
+        return notOnContext('json(object)', "For a JSON response use an { type: 'endpoint' } route; to read the request body use `ctx.req.json()`.");
+    }
+    /** @deprecated A page renders JSX. For a text response, use an `{ type: 'endpoint' }` route. */
+    text(...args) {
+        return notOnContext('text(string)', "For a text response use an { type: 'endpoint' } route; to read the request body use `ctx.req.text()`.");
+    }
+    /** @deprecated A page renders JSX, which the framework turns into HTML for you. */
+    html(...args) {
+        return notOnContext('html(string)', "A page's JSX is already its HTML; for a hand-built HTML response use an { type: 'endpoint' } route.");
+    }
+    /** @deprecated Not available on a page's context. To read the request body, use `ctx.req`. */
+    body(...args) {
+        return notOnContext('body(data, …)', "To read the *request* body use `ctx.req.json()` / `ctx.req.text()` / `ctx.req.formData()`; to build a response, use an { type: 'endpoint' } route.");
+    }
+    /** @deprecated A page's status is set by the framework — use `notFound()`, or an endpoint route. */
+    status(...args) {
+        return notOnContext('status(code)', "A page's status is the framework's: 200, 404 via `notFound()`, 500 when it throws. For any other code use an { type: 'endpoint' } route.");
+    }
+    /** @deprecated Renamed — use `ctx.setHeader(name, value)`, which is valid from a `'use server'` action. */
+    header(...args) {
+        return notOnContext('header(name, value)', "Use `ctx.setHeader(name, value)` from a 'use server' action, or `c.header(…)` in middleware — a page renders too late to set one.");
+    }
 }
 /**
- * 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.
+ * Returns the {@link RequestContext} for the current request — the 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** component 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.
@@ -248,28 +448,30 @@ export class Ctx {
  * @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 function getContext() {
+export function getRequestContext() {
     if (prerendering) {
-        throw new Error("[rshono] getContext() was called while prerendering a `render: 'static'` route. A static page " +
+        throw new Error("[rshono] getRequestContext() was called while prerendering a `render: 'static'` route. A static page " +
             'is rendered once at build time, so it has no per-request context to read (URL, cookies, ' +
             "headers, env). Change this route to `render: 'dynamic'` so it renders per request, or remove " +
-            'the getContext() call.');
+            'the getRequestContext() call.');
     }
     const c = contextStorage.getStore();
     if (!c) {
-        throw new Error('[rshono] getContext() was called outside a request. It only works inside a server component or a server action, not at module load.');
+        throw new Error('[rshono] getRequestContext() was called outside a request. It only works inside a server component or a server action, not at module load.');
     }
     let ctx = wrappers.get(c);
     if (!ctx) {
-        ctx = new Ctx(c);
+        ctx = new RequestContext(c);
         wrappers.set(c, ctx);
     }
     return ctx;
@@ -288,7 +490,7 @@ export function getContext() {
  *
  * @example
  * ```ts
- * const session = getContext().cookies.get('session');
+ * const session = getRequestContext().cookies.get('session');
  * if (!session) redirect('/login');
  * // session is defined below this line
  * ```
@@ -304,9 +506,11 @@ export function redirect(location, status = 303) {
  *
  * @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 function notFound() {
@@ -334,6 +538,8 @@ let errorHandler;
  *   Sentry.captureException(error, { tags: { source }, extra: { url: request.url } });
  * });
  * ```
+ *
+ * @see {@link https://www.rshono.com/docs/hono#error-reporting | Docs — error reporting}
  */
 export function onServerError(handler) {
     errorHandler = handler;