@depup/h3 2.0.1-depup.0

package/dist/cors.mjs

@@ -0,0 +1,292 @@
+import { HTTPResponse, onDispose as onDispose$1 } from "./response.mjs";
+const textEncoder = /* @__PURE__ */ new TextEncoder();
+const textDecoder = /* @__PURE__ */ new TextDecoder();
+const base64Chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+function base64Encode(data) {
+	const buff = validateBinaryLike(data);
+	if (globalThis.Buffer) return globalThis.Buffer.from(buff).toString("base64url");
+	let result = "";
+	let i;
+	const len = buff.length;
+	for (i = 2; i < len; i += 3) result += base64Chars[buff[i - 2] >> 2] + base64Chars[(buff[i - 2] & 3) << 4 | buff[i - 1] >> 4] + base64Chars[(buff[i - 1] & 15) << 2 | buff[i] >> 6] + base64Chars[buff[i] & 63];
+	if (i === len + 1) result += base64Chars[buff[i - 2] >> 2] + base64Chars[(buff[i - 2] & 3) << 4];
+	if (i === len) result += base64Chars[buff[i - 2] >> 2] + base64Chars[(buff[i - 2] & 3) << 4 | buff[i - 1] >> 4] + base64Chars[(buff[i - 1] & 15) << 2];
+	return result;
+}
+function base64Decode(b64Url) {
+	if (globalThis.Buffer) return new Uint8Array(globalThis.Buffer.from(b64Url, "base64url"));
+	const b64 = b64Url.replace(/-/g, "+").replace(/_/g, "/");
+	const binString = atob(b64);
+	const size = binString.length;
+	const bytes = new Uint8Array(size);
+	for (let i = 0; i < size; i++) bytes[i] = binString.charCodeAt(i);
+	return bytes;
+}
+function validateBinaryLike(source) {
+	if (typeof source === "string") return textEncoder.encode(source);
+	else if (source instanceof Uint8Array) return source;
+	else if (source instanceof ArrayBuffer) return new Uint8Array(source);
+	throw new TypeError(`The input must be a Uint8Array, a string, or an ArrayBuffer.`);
+}
+function serializeIterableValue(value) {
+	switch (typeof value) {
+		case "string": return textEncoder.encode(value);
+		case "boolean":
+		case "number":
+		case "bigint":
+		case "symbol": return textEncoder.encode(value.toString());
+		case "object":
+			if (value instanceof Uint8Array) return value;
+			return textEncoder.encode(JSON.stringify(value));
+	}
+	return /* @__PURE__ */ new Uint8Array();
+}
+function coerceIterable(iterable) {
+	if (typeof iterable === "function") iterable = iterable();
+	if (Symbol.iterator in iterable) return iterable[Symbol.iterator]();
+	if (Symbol.asyncIterator in iterable) return iterable[Symbol.asyncIterator]();
+	return iterable;
+}
+function onDispose(event, cb) {
+	onDispose$1(event, cb);
+}
+function noContent(status = 204) {
+	return new HTTPResponse(null, {
+		status,
+		statusText: "No Content"
+	});
+}
+function redirect(location, status = 302, statusText) {
+	const body = `<html><head><meta http-equiv="refresh" content="0; url=${escapeHtml(location)}" /></head></html>`;
+	return new HTTPResponse(body, {
+		status,
+		statusText: statusText || (status === 301 ? "Moved Permanently" : "Found"),
+		headers: {
+			"content-type": "text/html; charset=utf-8",
+			location
+		}
+	});
+}
+function redirectBack(event, opts = {}) {
+	const referer = event.req.headers.get("referer");
+	let location = opts.fallback ?? "/";
+	if (referer && URL.canParse(referer)) {
+		const refererURL = new URL(referer);
+		if (refererURL.origin === event.url.origin) {
+			let pathname = refererURL.pathname;
+			if (pathname.startsWith("//")) pathname = "/" + pathname.replace(/^\/+/, "");
+			location = pathname + (opts.allowQuery ? refererURL.search : "");
+		}
+	}
+	return redirect(location, opts.status);
+}
+function writeEarlyHints(event, hints) {
+	const linkValues = [];
+	for (const [name, value] of Object.entries(hints)) if (name.toLowerCase() === "link") {
+		for (const v of Array.isArray(value) ? value : [value]) if (v) linkValues.push(v);
+	}
+	if (event.runtime?.node?.res?.writeEarlyHints) {
+		if (linkValues.length === 0) return Promise.resolve();
+		const normalizedHints = { link: linkValues };
+		for (const [name, value] of Object.entries(hints)) if (name.toLowerCase() !== "link") normalizedHints[name] = value;
+		return new Promise((resolve) => {
+			event.runtime?.node?.res?.writeEarlyHints(normalizedHints, () => resolve());
+		});
+	}
+	for (const v of linkValues) event.res.headers.append("link", v);
+}
+async function iterable(iterable, options) {
+	const serializer = options?.serializer ?? serializeIterableValue;
+	const iterator = coerceIterable(iterable);
+	let first = await iterator.next();
+	return new HTTPResponse(new ReadableStream({
+		async pull(controller) {
+			const { value, done } = first ?? await iterator.next();
+			first = void 0;
+			if (value !== void 0) {
+				const chunk = serializer(value);
+				if (chunk !== void 0) controller.enqueue(chunk);
+			}
+			if (done) controller.close();
+		},
+		cancel() {
+			iterator.return?.();
+		}
+	}));
+}
+function html(first, ...values) {
+	let body;
+	if (typeof first === "string") {
+		body = escapeHtml(first);
+		if (body !== first && html._isWarned !== true) {
+			html._isWarned = true;
+			console.warn("[h3] `html()` received a plain string containing HTML characters and escaped it. Use the html`` tagged template for dynamic values, or wrap trusted markup with `raw()`.");
+		}
+	} else if (isRawHTML(first)) body = first.value;
+	else body = first.reduce((out, str, i) => {
+		const value = values[i];
+		const rendered = value == null ? "" : isRawHTML(value) ? value.value : escapeHtml(String(value));
+		return out + str + rendered;
+	}, "");
+	return new HTTPResponse(body, { headers: { "content-type": "text/html; charset=utf-8" } });
+}
+function raw(value) {
+	return {
+		[kRawHTML]: true,
+		value
+	};
+}
+const kRawHTML = /* @__PURE__ */ Symbol("h3.rawHTML");
+function isRawHTML(value) {
+	return typeof value === "object" && value !== null && value[kRawHTML] === true;
+}
+const HTML_ESCAPES = {
+	"&": "&amp;",
+	"\"": "&quot;",
+	"'": "&#39;",
+	"<": "&lt;",
+	">": "&gt;"
+};
+function escapeHtml(str) {
+	return str.replace(/[&"'<>]/g, (c) => HTML_ESCAPES[c]);
+}
+function resolveCorsOptions(options = {}) {
+	const defaultOptions = {
+		origin: "*",
+		methods: "*",
+		allowHeaders: "*",
+		exposeHeaders: "*",
+		credentials: false,
+		maxAge: false,
+		preflight: { statusCode: 204 }
+	};
+	const resolved = {
+		...defaultOptions,
+		...options,
+		preflight: {
+			...defaultOptions.preflight,
+			...options.preflight
+		}
+	};
+	if (resolved.credentials && resolved.origin === "*") warnOnce("[h3] CORS: `credentials: true` with wildcard origin is not allowed. Browsers will reject the response.");
+	if (resolved.credentials && (resolved.origin === "null" || Array.isArray(resolved.origin) && resolved.origin.includes("null"))) warnOnce("[h3] CORS: `credentials: true` with a `\"null\"` origin is dangerous. Any sandboxed iframe, `data:`/`file:` document, or opaque origin sends `Origin: null`, so credentials would be shared across untrusted contexts.");
+	if (resolved.credentials && resolved.exposeHeaders === "*") warnOnce("[h3] CORS: `credentials: true` with wildcard `exposeHeaders` has no effect. Browsers treat `*` literally on credentialed requests — list the headers explicitly.");
+	return resolved;
+}
+function isCorsOriginAllowed(origin, options) {
+	const { origin: originOption } = options;
+	if (!origin) return false;
+	if (!originOption || originOption === "*") return true;
+	if (typeof originOption === "function") return originOption(origin);
+	if (Array.isArray(originOption)) return originOption.some((_origin) => {
+		if (_origin instanceof RegExp) return _origin.test(origin);
+		return origin === _origin;
+	});
+	return originOption === origin;
+}
+function createOriginHeaders(event, options) {
+	const { origin: originOption } = options;
+	const origin = event.req.headers.get("origin");
+	if (!originOption || originOption === "*") return { "access-control-allow-origin": "*" };
+	if (isCorsOriginAllowed(origin, options)) return {
+		"access-control-allow-origin": origin,
+		vary: "origin"
+	};
+	return { vary: "origin" };
+}
+function createMethodsHeaders(event, options) {
+	const { methods, credentials } = options;
+	if (!methods) return {};
+	if (methods === "*") {
+		if (credentials) {
+			const requestMethod = event.req.headers.get("access-control-request-method");
+			return requestMethod ? {
+				"access-control-allow-methods": requestMethod,
+				vary: "access-control-request-method"
+			} : {};
+		}
+		return { "access-control-allow-methods": "*" };
+	}
+	return methods.length > 0 ? { "access-control-allow-methods": methods.join(",") } : {};
+}
+function createCredentialsHeaders(options) {
+	const { credentials } = options;
+	if (credentials) return { "access-control-allow-credentials": "true" };
+	return {};
+}
+function createAllowHeaderHeaders(event, options) {
+	const { allowHeaders } = options;
+	if (!allowHeaders || allowHeaders === "*" || allowHeaders.length === 0) {
+		const header = event.req.headers.get("access-control-request-headers");
+		return header ? {
+			"access-control-allow-headers": header,
+			vary: "access-control-request-headers"
+		} : { vary: "access-control-request-headers" };
+	}
+	return {
+		"access-control-allow-headers": allowHeaders.join(","),
+		vary: "access-control-request-headers"
+	};
+}
+function createExposeHeaders(options) {
+	const { exposeHeaders, credentials } = options;
+	if (!exposeHeaders) return {};
+	if (exposeHeaders === "*") return credentials ? {} : { "access-control-expose-headers": exposeHeaders };
+	return { "access-control-expose-headers": exposeHeaders.join(",") };
+}
+function createMaxAgeHeader(options) {
+	const { maxAge } = options;
+	if (maxAge) return { "access-control-max-age": maxAge };
+	return {};
+}
+let warnedMessages;
+function warnOnce(message) {
+	warnedMessages ??= /* @__PURE__ */ new Set();
+	if (warnedMessages.has(message)) return;
+	warnedMessages.add(message);
+	console.warn(message);
+}
+function isPreflightRequest(event) {
+	const origin = event.req.headers.get("origin");
+	const accessControlRequestMethod = event.req.headers.get("access-control-request-method");
+	return event.req.method === "OPTIONS" && !!origin && !!accessControlRequestMethod;
+}
+function appendCorsPreflightHeaders(event, options) {
+	const headerGroups = [
+		createOriginHeaders(event, options),
+		createCredentialsHeaders(options),
+		createMethodsHeaders(event, options),
+		createAllowHeaderHeaders(event, options),
+		createMaxAgeHeader(options)
+	];
+	const headers = Object.assign({}, ...headerGroups);
+	const varyValues = headerGroups.map((group) => group.vary).filter(Boolean);
+	if (varyValues.length > 0) headers.vary = varyValues.join(", ");
+	setCorsHeaders(event, headers);
+}
+function appendCorsHeaders(event, options) {
+	setCorsHeaders(event, {
+		...createOriginHeaders(event, options),
+		...createCredentialsHeaders(options),
+		...createExposeHeaders(options)
+	});
+}
+function setCorsHeaders(event, headers) {
+	for (const [key, value] of Object.entries(headers)) if (key === "vary") {
+		event.res.headers.append(key, value);
+		event.res.errHeaders.append(key, value);
+	} else {
+		event.res.headers.set(key, value);
+		event.res.errHeaders.set(key, value);
+	}
+}
+function handleCors(event, options) {
+	const _options = resolveCorsOptions(options);
+	if (isPreflightRequest(event)) {
+		appendCorsPreflightHeaders(event, _options);
+		return noContent(_options.preflight.statusCode);
+	}
+	appendCorsHeaders(event, _options);
+	return false;
+}
+export { appendCorsHeaders, appendCorsPreflightHeaders, base64Decode, base64Encode, handleCors, html, isCorsOriginAllowed, isPreflightRequest, iterable, noContent, onDispose, raw, redirect, redirectBack, textDecoder, textEncoder, writeEarlyHints };

package/dist/docs/0.guide/0.index/index.md

@@ -0,0 +1,117 @@
+# Getting Started
+
+> Get started with H3.
+
+> [!IMPORTANT]
+> You are currently reading H3 v2 docs. See [v1.h3.dev](https://v1.h3.dev/) for legacy docs.
+
+## Overview
+
+⚡ H3 (short for H(TTP), pronounced as /eɪtʃθriː/, like h-3) is a lightweight, fast, and composable server framework for modern JavaScript runtimes. It is based on web standard primitives such as [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request), [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response), [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL), and [Headers](https://developer.mozilla.org/en-US/docs/Web/API/Headers). You can integrate H3 with any compatible runtime or [mount](/guide/api/h3#h3mount) other web-compatible handlers to H3 with almost no added latency.
+
+H3 is designed to be extendable and composable. Instead of providing one big core, you start with a lightweight [H3 instance](/guide/api/h3) and then import built-in, tree-shakable [utilities](/utils) or bring your own for more functionality.
+Composable utilities has several advantages:
+
+- The server only includes used code and runs them exactly where is needed.
+- Application size can scale better. Usage of utilities is explicit and clean, with less global impact.
+- H3 is minimally opinionated and won't limit your choices.
+All utilities, share an [H3Event](/guide/api/h3event) context.
+
+<read-more></read-more>
+
+## Quick Start
+
+> [!TIP]
+> You try H3 online [on ⚡️ Stackblitz ](https://stackblitz.com/github/h3js/h3/tree/main/playground?file=server.mjs).
+
+Install `h3` as a dependency:
+
+<pm-install></pm-install>
+
+Create a new file for server entry:
+
+```ts [server.mjs]
+import { H3, serve } from "h3";
+
+const app = new H3().get("/", (event) => "⚡️ Tadaa!");
+
+serve(app, { port: 3000 });
+```
+
+Then, run the server using your favorite runtime:
+
+<code-group>
+
+```bash [node]
+node --watch ./server.mjs
+```
+
+```bash [deno]
+deno run -A --watch ./server.mjs
+```
+
+```bash [bun]
+bun run --watch server.mjs
+```
+</code-group>
+
+And tadaa! We have a web server running locally.
+
+### What Happened?
+
+Okay, let's now break down our hello world example.
+
+We first created an [H3](/guide/api/h3) app instance using `new H3()`:
+
+```ts
+const app = new H3();
+```
+
+[H3](/guide/api/h3) is a tiny class capable of [matching routes](/guide/basics/routing), [generating responses](/guide/basics/response) and calling [middleware](/guide/basics/middleware) and [global hooks](/guide/api/h3#global-hooks).
+
+Then we add a route for handling HTTP GET requests to `/` path.
+
+```ts
+app.get("/", (event) => {
+  return { message: "⚡️ Tadaa!" };
+});
+```
+
+<read-more></read-more>
+
+We simply returned an object. H3 automatically [converts](/guide/basics/response#response-types) values into web responses.
+
+<read-more></read-more>
+
+Finally, we use `serve` method to start the server listener. Using `serve` method you can easily start an H3 server in various runtimes.
+
+```js
+serve(app, { port: 3000 });
+```
+
+> [!TIP]
+> The `serve` method is powered by [💥 srvx](https://srvx.h3.dev/), a runtime-agnostic universal server listener based on web standards that works seamlessly with [Deno](https://deno.com/), [Node.js](https://nodejs.org/) and [Bun](https://bun.sh/).
+
+We also have [`app.fetch`](/guide/api/h3#h3fetch) which can be directly used to run H3 apps in any web-compatible runtime or even directly called for testing purposes.
+
+<read-more></read-more>
+
+```js
+import { H3, serve } from "h3";
+
+const app = new H3().get("/", () => "⚡️ Tadaa!");
+
+// Test without listening
+const response = await app.request("/");
+console.log(await response.text());
+```
+
+You can directly import `h3` library from CDN alternatively. This method can be used for Bun, Deno and other runtimes such as Cloudflare Workers.
+
+```js
+import { H3 } from "https://esm.sh/h3";
+
+const app = new H3().get("/", () => "⚡️ Tadaa!");
+
+export const fetch = app.fetch;
+```

package/dist/docs/0.guide/1.basics/0.lifecycle.md

@@ -0,0 +1,68 @@
+# Request Lifecycle
+
+> H3 dispatches incoming web requests to final web responses.
+
+Below is an overview of what happens in a H3 server from when an HTTP request arrives until a response is generated.
+
+## 1. Incoming Request
+
+When An HTTP request is made by Browser or [fetch()](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API), server fetch handler receives a [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object.
+
+```mermaid
+%%{init: {'theme':'neutral'}}%%
+flowchart LR
+  A1["<code>fetch(request)</code>"] --> A2["<code>server.fetch(request)</code>"]
+
+click A2 "/guide/api/h3#h3fetch"
+```
+
+> [!TIP]
+> ​[💥 Srvx](https://srvx.h3.dev) provides unified `server.fetch` interface and adds [Node.js compatibility](https://srvx.h3.dev/guide/node).
+
+## 2. Accept Request
+
+H3 Initializes an [`H3Event`](/guide/api/h3event) instance from incoming request, calls [`onRequest`](/guide/api/h3#global-hooks) global hook and finally [`H3.handler`](/guide/api/h3#h3handler) with the initialized event.
+
+```mermaid
+%%{init: {'theme':'neutral'}}%%
+flowchart LR
+  B1["<code>new H3Event(request)</code>"] --> B2["<code>onRequest(event)</code>"] --> B3["<code>h3.handler(event)</code>"]
+
+click B1 "/guide/api/h3event"
+click B2 "/guide/api/h3#global-hooks"
+click B3 "/guide/api/h3#apphandler"
+```
+
+## 3. Dispatch Request
+
+H3 [matches route](/guide/basics/routing) based on `request.url` and `request.method`, calls global [middleware](/guide/basics/middleware) and finally matched route handler function with event.
+
+```mermaid
+%%{init: {'theme':'neutral'}}%%
+sequenceDiagram
+    participant MiddlewareA as Middleware1(event, next)
+    participant MiddlewareB as Middleware2(event, next)
+    participant Route as RouteHandler(event)
+
+    MiddlewareA->>+MiddlewareB: await next()
+    MiddlewareB->>+Route: await next()
+    Route-->>-MiddlewareB: rawBody
+    MiddlewareB-->>-MiddlewareA: rawBody
+
+```
+
+> [!TIP]
+> 🚀 Internally, H3 uses srvx `FastURL` instead of `new URL(req.url).pathname`.
+
+## 4. Send Response
+
+H3 [converts](/guide/basics/response#response-types) returned value and [prepared headers](/guide/basics/response#preparing-response) into a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response), calls [`onResponse`](/guide/api/h3#global-hooks) global hook and finally returns response back to the server fetch handler.
+
+```mermaid
+%%{init: {'theme':'neutral'}}%%
+flowchart LR
+ D1["Returned Value => Response"] --> D2["<code>onResponse(response)</code>"] --> D3["Response"]
+
+click D1 "/guide/basics/response"
+click D2 "/guide/api/h3#global-hooks"
+```

package/dist/docs/0.guide/1.basics/1.routing.md

@@ -0,0 +1,167 @@
+# Routing
+
+> Each request is matched to one (most specific) route handler.
+
+## Adding Routes
+
+You can register route [handlers](/guide/basics/handler) to [H3 instance](/guide/api/h3) using [`H3.on`](/guide/api/h3#h3on), [`H3.[method]`](/guide/api/h3#h3method), or [`H3.all`](/guide/api/h3#h3all).
+
+> [!TIP]
+> Router is powered by [🌳 Rou3](https://github.com/h3js/rou3), an ultra-fast and tiny route matcher engine.
+
+**Example:** Register a route to match requests to the `/hello` endpoint with HTTP **GET** method.
+
+- Using [`H3.[method]`](/guide/api/h3#h3method)
+
+  ```js
+  app.get("/hello", () => "Hello world!");
+  ```
+
+- Using [`H3.on`](/guide/api/h3#h3on)
+
+  ```js
+  app.on("GET", "/hello", () => "Hello world!");
+  ```
+
+
+You can register multiple event handlers for the same route with different methods:
+
+```js
+app
+  .get("/hello", () => "GET Hello world!")
+  .post("/hello", () => "POST Hello world!")
+  .all("/hello", () => "Any other method!");
+```
+
+You can also use [`H3.all`](/guide/api/h3#h3all) method to register a route accepting any HTTP method:
+
+```js
+app.all("/hello", (event) => `This is a ${event.req.method} request!`);
+```
+
+## HEAD Requests
+
+Following [RFC 9110](https://www.rfc-editor.org/rfc/rfc9110#name-head), `HEAD` requests automatically match the corresponding `GET` route and run its handler, but the response body is omitted (only the headers and status are sent). You don't need to register a separate `HEAD` handler:
+
+```js
+app.get("/hello", () => "Hello world!");
+
+// HEAD /hello → 200 with the same headers as GET, but an empty body
+```
+
+Register an explicit `HEAD` handler when you want to override this — for example, to skip computing the body:
+
+```js
+app.head("/hello", (event) => {
+  event.res.headers.set("content-length", "12");
+  return null;
+});
+```
+
+An explicit `head()` route always takes precedence over the automatic `GET` fallback.
+
+## HTTP `QUERY` Method
+
+H3 supports the [HTTP `QUERY` method (RFC 10008)](https://www.rfc-editor.org/rfc/rfc10008) as a first-class method. `QUERY` is like `GET` — **safe, idempotent, and cacheable** — but carries a request body (with a `Content-Type`), closing the long-standing "GET with a body" gap. It's ideal for complex read operations where filters don't fit in a URL.
+
+Register a `QUERY` handler with `app.query()` (or `app.on("QUERY", …)`) and read the request body as usual:
+
+```js
+import { readBody } from "h3";
+
+app.query("/search", async (event) => {
+  const criteria = await readBody(event); // read the query body
+  return runSearch(criteria);
+});
+```
+
+Because `QUERY` carries an attacker-controllable body, [body-size limits](/utils/request#assertbodysizeevent-limit) apply just like `POST`.
+
+Two utilities help implement the RFC:
+
+- [`requireContentType(event, acceptedTypes)`](/utils/request#requirecontenttypeevent-acceptedtypes) — assert the request `Content-Type` (`400`/`415`/`422`).
+- [`appendAcceptQuery(event, mediaTypes)`](/utils/request#appendacceptqueryevent-mediatypes) — advertise accepted query formats via the `Accept-Query` response header.
+
+> [!NOTE]
+`QUERY` is treated like `GET` for [conditional caching](/utils/request#handlecacheheadersevent-opts) (`304` responses via `handleCacheHeaders`), and [`proxy`](/utils/proxy) forwards it **with** its body. Unlike `GET`, `QUERY` is **not** CORS-safelisted, so browsers send a preflight — if you pass an explicit `methods` allowlist to [`handleCors`](/utils/security#handlecorsevent-options), include `"QUERY"`.
+
+<read-more>
+
+See the [HTTP `QUERY` method example](/examples/handle-query) for a runnable `/books` resource that validates the `Content-Type` and advertises a cacheable `GET` alternative.
+</read-more>
+
+## Route Patterns
+
+A route pattern is a **pathname**, not a URL: the same shape as `event.url.pathname`, plus [rou3](https://github.com/h3js/rou3) syntax. [`H3.on`](/guide/api/h3#h3on), [`H3.[method]`](/guide/api/h3#h3method), [`H3.all`](/guide/api/h3#h3all), [`H3.use(route, ...)`](/guide/api/h3#h3use), [`H3.mount`](/guide/api/h3#h3mount) and [`removeRoute`](/utils/more#removerouteapp-method-route) normalize it identically, so a middleware registered with the same string as a route always guards that route.
+
+Normalization rules:
+
+- A leading `/` is added when missing (`"hello"` → `/hello`).
+- A URL is **rejected** (`app.get("http://example.com/admin")` throws). An authority is never silently dropped: `//admin` registers as the two-segment path `//admin`, not as `/`.
+- `.` and `..` segments resolve exactly as the URL parser resolves them in a request path (`/admin/../admin` → `/admin`).
+- Characters that a request pathname always carries percent-encoded are encoded: space, non-ASCII, control characters, `"`, `#`, `<`, `>` and ```. So `app.get("/café")` registers `/caf%C3%A9` — what the browser actually sends.
+- Needless escapes are decoded to the literal that the request pathname is canonicalized to (`/%40handle` → `/@handle`, see [Security utils](/utils/security)).
+Characters that carry rou3 meaning are left exactly as written, including the escape `\` (never valid in a request pathname). To match `?`, `{`, `}` or `^` **literally**, write it percent-encoded:
+
+```js
+app.get("/u/:id?", () => "optional param"); // rou3 syntax, kept as written
+app.get("/x%3Fy", () => "literal ?"); // matches the path a client sends for /x?y
+```
+
+> [!NOTE]
+> Non-ASCII text mixes freely with dynamic syntax — `app.get("/café/:id")` registers `/caf%C3%A9/:id` and matches `/café/42` — with two exceptions, both from the encoded form reaching rou3's own syntax. A **param name** must be ASCII (`[\w-]`): `/:naïve` becomes `/:na%C3%AFve`, which rou3 reads as a param named `na` followed by the literal `%C3%AFve`. And inside a `(...)` group, only literal text and alternation survive encoding (`(café|thé)` works); a **character class** does not, since `[é]` becomes `[%C3%A9]` — write the encoded alternation `(?:%C3%A9)` instead.
+
+## Dynamic Routes
+
+You can define dynamic route parameters using `:` prefix:
+
+```js
+// [GET] /hello/Bob => "Hello, Bob!"
+app.get("/hello/:name", (event) => {
+  return `Hello, ${event.context.params.name}!`;
+});
+```
+
+To make a parameter optional, add `?`:
+
+```js
+// Matches /hello and /hello/Bob
+app.get("/hello/:name?", (event) => `Hello, ${event.context.params?.name ?? "you"}!`);
+```
+
+## Wildcard Routes
+
+Adding `/hello/:name` route will match `/hello/world` or `/hello/123`. But it will not match `/hello/foo/bar`.
+When you need to match multiple levels of sub routes, you can use a `**` (or `*`) catch-all:
+
+```js
+app.get("/hello/**", (event) => `Hello ${event.context.params?.[0] ?? ""}!`);
+```
+
+This will match `/hello`, `/hello/world`, `/hello/123`, `/hello/world/123`, etc.
+
+> [!NOTE]
+> An unnamed `**` or `*` stores the matched sub-path as a single string keyed by position (`params[0]`), and is left out when it matches nothing. `params._` still works for `**` but is deprecated. A named catch-all (`/hello/**:path`) stores it as `params.path`, but needs at least one segment, so it does not match `/hello`.
+
+> A route can have only one catch-all (`*`, `**`, `:name+`, `:name*` or `(.*)`).
+
+## Route Meta
+
+You can define optional route meta when registering them, accessible from any middleware.
+
+```js
+import { H3 } from "h3";
+
+const app = new H3();
+
+app.use((event) => {
+  console.log(event.context.matchedRoute?.meta); // { auth: true }
+});
+
+app.get("/", (event) => "Hi!", { meta: { auth: true } });
+```
+
+<read-more>
+
+It is also possible to add route meta when defining them using `defineHandler` object syntax.
+</read-more>