routup 5.1.1 → 6.0.0-beta.0

package/dist/index-kxLRw2Wc.d.mts

@@ -0,0 +1,1950 @@
+import QuickLRU from "quick-lru";
+import { FastURL, ServerRequest } from "srvx";
+import { HTTPError, HTTPErrorInput, HTTPErrorInput as HTTPErrorInput$1 } from "@ebec/http";
+import Negotiator from "negotiator";
+import { Key, ParseOptions, PathToRegexpOptions } from "path-to-regexp";
+import { IncomingMessage, ServerResponse } from "node:http";
+
+//#region src/error/module.d.ts
+declare const ErrorSymbol: unique symbol;
+declare class AppError extends HTTPError {
+  constructor(input?: HTTPErrorInput$1);
+}
+//#endregion
+//#region src/constants.d.ts
+declare const MethodName: {
+  readonly GET: "GET";
+  readonly POST: "POST";
+  readonly PUT: "PUT";
+  readonly PATCH: "PATCH";
+  readonly DELETE: "DELETE";
+  readonly OPTIONS: "OPTIONS";
+  readonly HEAD: "HEAD";
+};
+type MethodName = typeof MethodName[keyof typeof MethodName];
+/**
+ * `MethodName` plus the open-enum escape hatch for non-standard
+ * methods (`PROPFIND`, `MKCOL`, custom verbs). The `(string & {})`
+ * intersection is structurally identical to `string` but TypeScript
+ * doesn't collapse the union — so callers still get autocomplete
+ * for the canonical methods while remaining free to pass anything.
+ */
+type MethodNameLike = MethodName | (string & {});
+declare const HeaderName: {
+  readonly ACCEPT: "accept";
+  readonly ACCEPT_CHARSET: "accept-charset";
+  readonly ACCEPT_ENCODING: "accept-encoding";
+  readonly ACCEPT_LANGUAGE: "accept-language";
+  readonly ACCEPT_RANGES: "accept-ranges";
+  readonly ALLOW: "allow";
+  readonly CACHE_CONTROL: "cache-control";
+  readonly CONTENT_DISPOSITION: "content-disposition";
+  readonly CONTENT_ENCODING: "content-encoding";
+  readonly CONTENT_LENGTH: "content-length";
+  readonly CONTENT_RANGE: "content-range";
+  readonly CONTENT_TYPE: "content-type";
+  readonly CONNECTION: "connection";
+  readonly COOKIE: "cookie";
+  readonly ETag: "etag";
+  readonly HOST: "host";
+  readonly IF_MODIFIED_SINCE: "if-modified-since";
+  readonly IF_NONE_MATCH: "if-none-match";
+  readonly LAST_MODIFIED: "last-modified";
+  readonly LOCATION: "location";
+  readonly RANGE: "range";
+  readonly RATE_LIMIT_LIMIT: "ratelimit-limit";
+  readonly RATE_LIMIT_REMAINING: "ratelimit-remaining";
+  readonly RATE_LIMIT_RESET: "ratelimit-reset";
+  readonly RETRY_AFTER: "retry-after";
+  readonly SET_COOKIE: "set-cookie";
+  readonly TRANSFER_ENCODING: "transfer-encoding";
+  readonly X_ACCEL_BUFFERING: "x-accel-buffering";
+  readonly X_FORWARDED_HOST: "x-forwarded-host";
+  readonly X_FORWARDED_FOR: "x-forwarded-for";
+  readonly X_FORWARDED_PROTO: "x-forwarded-proto";
+};
+type HeaderName = typeof HeaderName[keyof typeof HeaderName];
+//#endregion
+//#region src/event/types.d.ts
+type AppResponse = {
+  status: number;
+  headers: Headers;
+};
+type AppRequest = ServerRequest;
+type NextFn = (error?: Error) => unknown | Promise<unknown>;
+interface IAppEvent {
+  /**
+   * The srvx ServerRequest (extends Web Standard Request).
+   */
+  readonly request: AppRequest;
+  /**
+   * Route parameters extracted from the URL path pattern. Values
+   * are `string` (or `undefined` for an optional param that
+   * didn't match) — both the trie router (`extractTrieParams`)
+   * and the linear router (path-to-regexp output) only ever
+   * produce string values.
+   */
+  readonly params: Record<string, string | undefined>;
+  /**
+   * Current request path, adjusted relative to the mount point during router nesting.
+   */
+  readonly path: string;
+  /**
+   * HTTP method (GET, POST, PUT, etc.). Typed as the canonical
+   * `MethodName` set with an open-enum escape hatch — non-
+   * standard methods (`PROPFIND`, custom verbs) still type-check
+   * while standard ones autocomplete.
+   */
+  readonly method: MethodNameLike;
+  /**
+   * Accumulated mount path from nested routers.
+   */
+  readonly mountPath: string;
+  /**
+   * Web Standard Headers from the request.
+   */
+  readonly headers: Headers;
+  /**
+   * Lazily-parsed URL search parameters.
+   *
+   * For advanced query parsing (arrays, nesting), use `@routup/query`.
+   */
+  readonly searchParams: URLSearchParams;
+  /**
+   * Response accumulator — set status/headers before returning a plain value.
+   *
+   * If the handler returns a `Response` object directly, these values are
+   * ignored. They only apply when returning plain values (string, object, etc.)
+   * that go through `toResponse()`.
+   */
+  readonly response: AppResponse;
+  /**
+   * Per-request store for caching and plugin state.
+   *
+   * Use symbol keys (e.g., `Symbol.for('routup:body')`) to avoid collisions.
+   * Data is garbage collected with the event when the request completes.
+   */
+  readonly store: Record<string | symbol, unknown>;
+  /**
+   * Pre-resolved router options for the current dispatch context.
+   *
+   * Contains merged options from the router path stack with defaults applied.
+   */
+  readonly appOptions: Readonly<AppOptions>;
+  /**
+   * Abort signal tied to the request lifecycle.
+   *
+   * When a `timeout` router option is set, this signal aborts after the
+   * specified duration. Handlers performing long I/O (fetch, streams, DB queries)
+   * can pass this signal to those operations for cooperative cancellation.
+   */
+  readonly signal: AbortSignal;
+  /**
+   * Call the next handler in the pipeline (onion model).
+   *
+   * The result is cached — calling `next()` multiple times returns the same response.
+   * Returns the downstream `Response`, or `undefined` if no handler matched.
+   */
+  next(error?: Error): Promise<Response | undefined>;
+  /**
+   * Whether `next()` has been invoked on this event.
+   *
+   * Used by the dispatch pipeline to disambiguate an `undefined` return value:
+   * a handler that returns `undefined` after calling `next()` is forwarding the
+   * downstream result; one that returns `undefined` without calling `next()` is
+   * unresolved and will wait on `signal` (timeout-bounded).
+   */
+  readonly nextCalled: boolean;
+  /**
+   * The cached promise returned by the first `next()` call on this event,
+   * or `undefined` if `next()` has not been invoked.
+   */
+  readonly nextResult: Promise<Response | undefined> | undefined;
+  /**
+   * Returns a promise that resolves the first time `next()` is invoked on this event.
+   *
+   * If `next()` has already been called, the returned promise is already resolved.
+   * Used by the dispatch pipeline so a handler that returns `undefined` and later
+   * calls `next()` asynchronously (e.g. from a `setTimeout`) still propagates the
+   * downstream response instead of hanging until `signal` aborts.
+   */
+  whenNextCalled(): Promise<void>;
+}
+//#endregion
+//#region src/event/module.d.ts
+type AppEventCreateContext = {
+  request: AppRequest;
+  params: Record<string, string | undefined>;
+  path: string;
+  method: MethodNameLike;
+  mountPath: string;
+  headers: Headers;
+  searchParams: URLSearchParams;
+  response: AppResponse;
+  store: Record<string | symbol, unknown>;
+  signal: AbortSignal;
+  appOptions: Readonly<AppOptions>;
+  next: (event: IAppEvent, error?: Error) => Promise<Response | undefined>;
+};
+declare class AppEvent implements IAppEvent {
+  readonly request: AppRequest;
+  readonly params: Record<string, string | undefined>;
+  readonly path: string;
+  readonly method: MethodNameLike;
+  readonly mountPath: string;
+  readonly headers: Headers;
+  readonly searchParams: URLSearchParams;
+  readonly response: AppResponse;
+  readonly store: Record<string | symbol, unknown>;
+  readonly signal: AbortSignal;
+  readonly appOptions: Readonly<AppOptions>;
+  protected _context: AppEventCreateContext;
+  protected _nextCalled: boolean;
+  protected _nextResult: Promise<Response | undefined> | undefined;
+  protected _nextCalledDeferred: {
+    promise: Promise<void>;
+    resolve: () => void;
+  } | undefined;
+  constructor(context: AppEventCreateContext);
+  get nextCalled(): boolean;
+  get nextResult(): Promise<Response | undefined> | undefined;
+  whenNextCalled(): Promise<void>;
+  next(error?: Error): Promise<Response | undefined>;
+}
+//#endregion
+//#region src/dispatcher/types.d.ts
+interface IDispatcherEvent {
+  /**
+   * The srvx ServerRequest (extends Web Standard Request).
+   */
+  readonly request: AppRequest;
+  /**
+   * Route parameters extracted from the URL path pattern. Values
+   * are `string` (or `undefined` for an optional param that
+   * didn't match).
+   */
+  params: Record<string, string | undefined>;
+  /**
+   * Current request path, adjusted relative to the mount point during router nesting.
+   */
+  path: string;
+  /**
+   * HTTP method (GET, POST, PUT, etc.). See `IAppEvent.method`
+   * for the open-enum typing rationale.
+   */
+  readonly method: MethodNameLike;
+  /**
+   * Accumulated mount path from nested routers.
+   */
+  mountPath: string;
+  /**
+   * Response accumulator — set status/headers before returning a plain value.
+   */
+  readonly response: AppResponse;
+  /**
+   * Whether a response has been produced.
+   */
+  dispatched: boolean;
+  /**
+   * Error that occurred during dispatch, if any.
+   */
+  error?: AppError;
+  /**
+   * Options of the App currently dispatching this event. Set on
+   * entry to `App.dispatch` and restored on exit so nested apps
+   * temporarily override the parent's view.
+   */
+  appOptions: Readonly<AppOptions>;
+  /**
+   * `true` while at least one `App.dispatch` is on the call stack
+   * for this event. Used by `App.dispatch` to derive whether a
+   * given dispatch call is the root (the first one entered) or
+   * nested. Saved/restored across the call so nested dispatches
+   * leave the flag in the state their caller expects.
+   */
+  isDispatching: boolean;
+  /**
+   * Abort signal for cooperative cancellation.
+   *
+   * When a `timeout` router option is set, this signal aborts after the
+   * specified duration. Handlers can pass it to fetch(), streams, or other
+   * AbortSignal-aware APIs.
+   */
+  signal: AbortSignal;
+  /**
+   * Collected allowed methods for the current path (used for OPTIONS / 405 responses).
+   */
+  methodsAllowed: Set<string>;
+  /**
+   * Set the continuation function for this event.
+   *
+   * Replaces the current continuation. The provided function receives
+   * an optional error and may return any value — it will be converted
+   * to a `Response` via `toResponse()`.
+   *
+   * Passing `undefined` clears the continuation function.
+   */
+  setNext(fn?: NextFn): void;
+  /**
+   * Build a public AppEvent from the current dispatch state.
+   *
+   * Creates a lightweight snapshot with shared references (store, response, headers)
+   * and the current App's options. This is the event passed to handler functions.
+   *
+   * @param signal - Optional AbortSignal override. When provided, the built event
+   *                 uses this signal instead of the dispatcher event's own signal.
+   *                 Used by per-handler timeout to provide a handler-scoped signal.
+   */
+  build(signal?: AbortSignal): IAppEvent;
+}
+interface IDispatcher {
+  dispatch(event: IDispatcherEvent): Promise<Response | undefined>;
+}
+//#endregion
+//#region src/dispatcher/module.d.ts
+declare class DispatcherEvent implements IDispatcherEvent {
+  readonly request: AppRequest;
+  params: Record<string, string | undefined>;
+  path: string;
+  readonly method: MethodNameLike;
+  /**
+   * Collected allowed methods (for OPTIONS).
+   */
+  methodsAllowed: Set<string>;
+  mountPath: string;
+  error?: AppError;
+  /**
+   * Options of the App currently dispatching this event. Set on
+   * entry to `App.dispatch` and restored on exit (so nested apps
+   * temporarily override). Initialized to `{}` so consumers
+   * reading before any dispatch get a valid (empty) shape.
+   */
+  appOptions: Readonly<AppOptions>;
+  /**
+   * `true` while at least one `App.dispatch` is on the call stack
+   * for this event. `App.dispatch` reads this on entry to derive
+   * `isRoot` and writes it on entry/exit so nested calls see it
+   * already set.
+   */
+  isDispatching: boolean;
+  protected _dispatched: boolean;
+  protected _response?: AppResponse;
+  protected _store?: Record<string | symbol, unknown>;
+  /**
+   * Cached parsed URL (avoids double-parsing).
+   */
+  protected _url: InstanceType<typeof FastURL>;
+  /**
+   * Continuation function for middleware onion model.
+   */
+  protected _next?: (event: IAppEvent, error?: Error) => Promise<Response | undefined>;
+  protected _signal?: AbortSignal;
+  protected _signalCleanup?: () => void;
+  /**
+   * Whether _next has already been called (guard against double-invocation).
+   */
+  protected _nextCalled: boolean;
+  /**
+   * The cached result of the next handler.
+   */
+  protected _nextResult?: Promise<Response | undefined>;
+  constructor(request: AppRequest);
+  get response(): AppResponse;
+  get signal(): AbortSignal;
+  set signal(value: AbortSignal);
+  get dispatched(): boolean;
+  set dispatched(value: boolean);
+  protected next(event: IAppEvent, error?: Error): Promise<Response | undefined>;
+  setNext(fn?: NextFn): void;
+  build(signal?: AbortSignal): AppEvent;
+  protected get store(): Record<string | symbol, unknown>;
+}
+//#endregion
+//#region src/hook/constants.d.ts
+declare const HookName: {
+  /**
+   * Fired at the start of `App.dispatch`, before the pipeline walk.
+   * Once per router per request.
+   */
+  readonly START: "start";
+  /**
+   * Fired at the end of `App.dispatch`, after the pipeline walk
+   * (and OPTIONS auto-Allow synthesis) completes. Once per router per
+   * request.
+   */
+  readonly END: "end";
+  readonly ERROR: "error";
+  readonly CHILD_MATCH: "childMatch";
+  readonly CHILD_DISPATCH_BEFORE: "childDispatchBefore";
+  readonly CHILD_DISPATCH_AFTER: "childDispatchAfter";
+};
+type HookName = typeof HookName[keyof typeof HookName];
+//#endregion
+//#region src/hook/types.d.ts
+type HookErrorListener = (event: IDispatcherEvent) => Promise<unknown> | unknown;
+type HookDefaultListener = (event: IDispatcherEvent) => Promise<unknown> | unknown;
+type HookListener = HookErrorListener | HookDefaultListener;
+type HookUnsubscribeFn = () => void;
+interface IHooks {
+  addListener(name: HookName, fn: HookListener, priority?: number): HookUnsubscribeFn;
+  removeListener(name: HookName): void;
+  removeListener(name: HookName, fn: HookListener): void;
+  removeListener(name: HookName, fn?: HookListener): void;
+  /**
+   * Returns true if at least one listener is registered for the given
+   * hook name. Used by the dispatch pipeline to skip the
+   * `await trigger(...)` microtask hop on the hot path when nothing
+   * is listening.
+   */
+  hasListeners(name: HookName): boolean;
+  /**
+   * Returns true if at least one listener is registered across *any*
+   * hook name. Cheap (single boolean read). Useful as a coarse
+   * fast-path guard before any per-name `hasListeners(...)` lookup
+   * for apps that never register a hook — the common workload.
+   */
+  hasAny(): boolean;
+  clone(): IHooks;
+  trigger(name: HookName, event: IDispatcherEvent): Promise<void>;
+}
+//#endregion
+//#region src/handler/constants.d.ts
+declare const HandlerType: {
+  readonly CORE: "core";
+  readonly ERROR: "error";
+};
+type HandlerType = typeof HandlerType[keyof typeof HandlerType];
+declare const HandlerSymbol: unique symbol;
+//#endregion
+//#region src/path/type.d.ts
+type PathMatcherOptions = PathToRegexpOptions & ParseOptions;
+type PathMatcherExecResult = {
+  path: string;
+  params: Record<string, any>;
+};
+type Path = string;
+interface IPathMatcher {
+  test(path: string): boolean;
+  exec(path: string): PathMatcherExecResult | undefined;
+}
+//#endregion
+//#region src/path/matcher.d.ts
+declare class PathMatcher implements IPathMatcher {
+  protected path: Path;
+  protected regexp: RegExp;
+  protected regexpKeys: Key[];
+  protected regexpOptions: PathMatcherOptions;
+  constructor(path: Path, options?: PathMatcherOptions);
+  test(path: string): boolean;
+  exec(path: string): PathMatcherExecResult | undefined;
+}
+//#endregion
+//#region src/path/utils.d.ts
+declare function isPath(input: unknown): input is Path;
+//#endregion
+//#region src/handler/types-base.d.ts
+type HandlerBaseOptions = {
+  method?: Uppercase<MethodName> | Lowercase<MethodName>;
+  path?: Path;
+  /**
+   * Per-handler timeout in milliseconds.
+   *
+   * Overrides the router's `handlerTimeout` default. Whether this value
+   * can extend or only narrow the default is controlled by the router's
+   * `handlerTimeoutOverridable` option.
+   */
+  timeout?: number;
+  onError?: HookErrorListener;
+  onBefore?: HookDefaultListener;
+  onAfter?: HookDefaultListener;
+};
+//#endregion
+//#region src/handler/error/types.d.ts
+type ErrorHandler = (error: AppError, event: IAppEvent) => unknown | Promise<unknown>;
+type ErrorHandlerOptions = HandlerBaseOptions & {
+  type: typeof HandlerType.ERROR;
+  fn: ErrorHandler;
+};
+//#endregion
+//#region src/handler/error/define.d.ts
+/**
+ * Create an error handler.
+ *
+ * Error handlers receive errors thrown by preceding handlers in the pipeline.
+ *
+ * @param input - Handler function `(error, event) => value` or options object `{ fn, path? }`
+ *
+ * @example
+ * ```typescript
+ * router.use(defineErrorHandler((error, event) => {
+ *     return { message: error.message };
+ * }));
+ * ```
+ */
+declare function defineErrorHandler(input: Omit<ErrorHandlerOptions, 'type'>): Handler;
+declare function defineErrorHandler(input: ErrorHandler): Handler;
+//#endregion
+//#region src/handler/types.d.ts
+type HandlerOptions = CoreHandlerOptions | ErrorHandlerOptions;
+//#endregion
+//#region src/handler/module.d.ts
+declare class Handler implements IDispatcher {
+  protected config: HandlerOptions;
+  protected hooks: IHooks;
+  readonly method: MethodName | undefined;
+  constructor(handler: HandlerOptions);
+  get type(): "error" | "core";
+  get path(): string | undefined;
+  dispatch(event: IDispatcherEvent): Promise<Response | undefined>;
+  /**
+   * Resolve a handler's return value into the final value handed to `toResponse`.
+   *
+   * Contract:
+   * - non-undefined value → return as-is (becomes the response)
+   * - `undefined` + `event.next()` was called → forward downstream result
+   * - `undefined` + `event.next()` not yet called → wait until either `next()` is
+   *   invoked (e.g. from an async callback) or `signal` aborts. A global or
+   *   per-handler timeout aborts `signal` and surfaces as 408. With no timeout
+   *   configured and no eventual `next()` call, the request hangs by design.
+   */
+  protected resolveHandlerResult(invocation: unknown | Promise<unknown>, handlerEvent: IAppEvent): Promise<unknown>;
+  protected executeWithTimeout(fn: () => unknown | Promise<unknown>, effectiveTimeout: number | undefined, controller?: AbortController): Promise<unknown>;
+  protected resolveTimeout(appOptions: AppOptions): number | undefined;
+  protected mountHooks(): void;
+}
+//#endregion
+//#region src/handler/core/types.d.ts
+type CoreHandler = (event: IAppEvent) => unknown | Promise<unknown>;
+type CoreHandlerOptions = HandlerBaseOptions & {
+  type: typeof HandlerType.CORE;
+  fn: CoreHandler;
+};
+//#endregion
+//#region src/handler/core/define.d.ts
+/**
+ * Create a request handler.
+ *
+ * @param input - Handler function `(event) => value` or options object `{ fn, path?, method? }`
+ *
+ * @example
+ * ```typescript
+ * // Shorthand — function only
+ * router.get('/', defineCoreHandler((event) => 'Hello'));
+ *
+ * // Verbose — with path and method
+ * router.use(defineCoreHandler({
+ *     path: '/users/:id',
+ *     method: 'GET',
+ *     fn: (event) => ({ id: event.params.id }),
+ * }));
+ * ```
+ */
+declare function defineCoreHandler(input: Omit<CoreHandlerOptions, 'type'>): Handler;
+declare function defineCoreHandler(input: CoreHandler): Handler;
+//#endregion
+//#region src/handler/adapters/node/types.d.ts
+type NodeHandler = (req: IncomingMessage, res: ServerResponse) => unknown | Promise<unknown>;
+type NodeMiddleware = (req: IncomingMessage, res: ServerResponse, next: (err?: unknown) => void) => unknown | Promise<unknown>;
+//#endregion
+//#region src/handler/adapters/node/define.d.ts
+/**
+ * Wraps a Node.js `(req, res)` handler for use in the routup pipeline.
+ *
+ * @example
+ * ```typescript
+ * import { fromNodeHandler } from 'routup/node';
+ *
+ * router.use(fromNodeHandler((req, res) => {
+ *     res.end('Hello');
+ * }));
+ * ```
+ */
+declare function fromNodeHandler(handler: NodeHandler): Handler;
+/**
+ * Wraps a Node.js `(req, res, next)` middleware for use in the routup pipeline.
+ *
+ * @example
+ * ```typescript
+ * import cors from 'cors';
+ * import { fromNodeMiddleware } from 'routup/node';
+ *
+ * router.use(fromNodeMiddleware(cors()));
+ * ```
+ */
+declare function fromNodeMiddleware(handler: NodeMiddleware): Handler;
+//#endregion
+//#region src/handler/adapters/web/types.d.ts
+/**
+ * A plain function that follows the Web Fetch API signature.
+ * Compatible with any framework that exposes a fetch-style entry point.
+ */
+interface WebHandler {
+  (request: Request): Response | Promise<Response>;
+}
+/**
+ * An object with a `fetch` method (e.g. another router, Hono app, etc.).
+ */
+interface WebHandlerProvider {
+  fetch(request: Request): Response | Promise<Response>;
+}
+//#endregion
+//#region src/handler/adapters/web/define.d.ts
+/**
+ * Create a handler from a Web Fetch API-compatible function or object.
+ *
+ * Wraps an external app (e.g. Hono, another App) so it can be mounted
+ * via `router.use()`. The original request is passed through as-is.
+ *
+ * @param input - Fetch function `(request) => Response` or object with a `fetch` method
+ *
+ * @experimental
+ *
+ * @example
+ * ```ts
+ * // Mount an object with a fetch method
+ * router.use('/api', fromWebHandler(honoApp));
+ *
+ * // Mount a plain fetch function
+ * router.use('/proxy', fromWebHandler((req) => fetch(req)));
+ * ```
+ */
+declare function fromWebHandler(input: WebHandler): Handler;
+declare function fromWebHandler(input: WebHandlerProvider): Handler;
+//#endregion
+//#region src/handler/adapters/web/is.d.ts
+declare function isWebHandlerProvider(input: unknown): input is WebHandlerProvider;
+declare function isWebHandler(input: unknown): input is WebHandler;
+//#endregion
+//#region src/handler/is.d.ts
+declare function isHandlerOptions(input: unknown): input is HandlerOptions;
+declare function isHandler(input: unknown): input is Handler;
+//#endregion
+//#region src/handler/utils.d.ts
+/**
+ * Match a request method against a handler's bound method.
+ *
+ * - When the handler has no method bound, matches every request method.
+ * - Otherwise matches when the request method is the same.
+ * - HEAD requests additionally match GET handlers.
+ */
+declare function matchHandlerMethod(handlerMethod: MethodName | undefined, requestMethod: MethodName): boolean;
+//#endregion
+//#region src/plugin/error/constants.d.ts
+declare const PluginErrorCode: {
+  readonly PLUGIN: "PLUGIN";
+  readonly NOT_INSTALLED: "PLUGIN_NOT_INSTALLED";
+  readonly ALREADY_INSTALLED: "PLUGIN_ALREADY_INSTALLED";
+  readonly INSTALL: "PLUGIN_INSTALL";
+};
+type PluginErrorCode = typeof PluginErrorCode[keyof typeof PluginErrorCode];
+//#endregion
+//#region src/plugin/error/module.d.ts
+declare class PluginError extends AppError {
+  constructor(input?: HTTPErrorInput);
+}
+//#endregion
+//#region src/plugin/error/is.d.ts
+declare function isPluginError(input: unknown): input is PluginError;
+//#endregion
+//#region src/plugin/error/sub/already-installed.d.ts
+declare class PluginAlreadyInstalledError extends PluginError {
+  readonly pluginName: string;
+  constructor(pluginName: string);
+}
+//#endregion
+//#region src/plugin/error/sub/install.d.ts
+declare class PluginInstallError extends PluginError {
+  readonly pluginName: string;
+  constructor(pluginName: string, cause?: Error);
+}
+//#endregion
+//#region src/plugin/error/sub/not-installed.d.ts
+declare class PluginNotInstalledError extends PluginError {
+  readonly pluginName: string;
+  readonly helperName: string;
+  constructor(pluginName: string, helperName: string);
+}
+//#endregion
+//#region src/plugin/types.d.ts
+type PluginInstallFn = (router: IApp) => any;
+type Plugin = {
+  /**
+   * The name of the plugin.
+   */
+  name: string;
+  /**
+   * The version of the plugin (semver).
+   */
+  version?: string;
+  /**
+   * The installation function called on registration.
+   */
+  install: PluginInstallFn;
+};
+type PluginInstallContext = {
+  /**
+   * By specifying a path, the plugin will be installed as a child router.
+   */
+  path?: Path;
+};
+//#endregion
+//#region src/plugin/is.d.ts
+declare function isPlugin(input: unknown): input is Plugin;
+//#endregion
+//#region src/utils/etag/types.d.ts
+type EtagOptions = {
+  /**
+   * Create a weak ETag?
+   * Output is prefixed with: /W
+   */
+  weak?: boolean;
+  /**
+   * Threshold of bytes from which an etag is generated.
+   *
+   * default: undefined
+   */
+  threshold?: number;
+};
+type EtagFn = (body: string, size?: number) => Promise<string | undefined>;
+type EtagInput = boolean | null | EtagOptions | EtagFn;
+//#endregion
+//#region src/utils/trust-proxy/type.d.ts
+type TrustProxyFn = (address: string, hop: number) => boolean;
+type TrustProxyInput = boolean | number | string | string[] | TrustProxyFn;
+//#endregion
+//#region src/app/constants.d.ts
+declare const AppPipelineStep: {
+  readonly START: 0;
+  readonly LOOKUP: 1;
+  readonly CHILD_BEFORE: 2;
+  readonly CHILD_DISPATCH: 3;
+  readonly CHILD_AFTER: 4;
+  readonly FINISH: 5;
+};
+type AppPipelineStep = typeof AppPipelineStep[keyof typeof AppPipelineStep];
+declare const RouteEntryType: {
+  readonly APP: "app";
+  readonly HANDLER: "handler";
+};
+type RouteEntryType = typeof RouteEntryType[keyof typeof RouteEntryType];
+//#endregion
+//#region src/cache/types.d.ts
+/**
+ * Pluggable cache strategy used by `IRouter` implementations to
+ * memoize `lookup(path)` results by request path. The default
+ * implementation (`LruCache`) is a `quick-lru`-backed bounded LRU;
+ * users can supply their own `ICache` (e.g. wrapping `lru-cache` for
+ * TTL/size-based eviction) via `BaseRouterOptions.cache`, or pass
+ * `null` to disable caching.
+ *
+ * The cache is opaque about value type so the same `ICache`
+ * implementation can be reused for non-router caching needs.
+ */
+interface ICache<V> {
+  /**
+   * Return the cached value for `key`, or `undefined` when the key
+   * is absent (or has been evicted). Implementations should treat
+   * `undefined` as "no entry" — callers cannot store `undefined`.
+   * Other falsy values (`null`, `0`, `''`, `false`) are storable
+   * and must be returned unchanged on hit.
+   */
+  get(key: string): V | undefined;
+  /**
+   * Store `value` under `key`. Bounded implementations (LRU, TTL,
+   * size-based) decide eviction at this point.
+   */
+  set(key: string, value: V): void;
+  /**
+   * Remove a single entry. No-op when `key` is absent.
+   */
+  delete(key: string): void;
+  /**
+   * Drop every entry. Routers call this from inside `add()` so a
+   * newly registered route can never be hidden by stale matches
+   * cached against an earlier route set.
+   */
+  clear(): void;
+  /**
+   * Return a fresh, **empty** cache of the same shape — same class
+   * for leaf implementations. Used by `IRouter.clone()` so the
+   * clone preserves the configured cache family (size, eviction
+   * policy, …) without inheriting the parent's cached values.
+   * Mirrors `IRouter.clone()`.
+   */
+  clone(): ICache<V>;
+}
+//#endregion
+//#region src/cache/lru.d.ts
+type LruCacheOptions = {
+  /**
+   * Maximum number of entries before the least-recently-used entry
+   * is evicted on `set`. Default: `1024`.
+   */
+  maxSize?: number;
+};
+/**
+ * Default `ICache` implementation — a bounded LRU backed by
+ * [`quick-lru`](https://github.com/sindresorhus/quick-lru). Picked for
+ * its small footprint (~1kB), ESM-only build (matches routup), and
+ * stable API.
+ *
+ * For TTL, size-based eviction, or dispose hooks, write your own
+ * `ICache` (e.g. wrapping `lru-cache`) and pass it via the router's
+ * `BaseRouterOptions.cache` slot.
+ */
+declare class LruCache<V> implements ICache<V> {
+  protected options: LruCacheOptions;
+  protected inner: QuickLRU<string, V>;
+  constructor(options?: LruCacheOptions);
+  get(key: string): V | undefined;
+  set(key: string, value: V): void;
+  delete(key: string): void;
+  clear(): void;
+  clone(): ICache<V>;
+}
+//#endregion
+//#region src/types.d.ts
+/**
+ * Constraint on `IRouter<T>`'s data slot — routers store object-shaped
+ * per-route data (handlers, child apps, custom records). Primitives
+ * (`string`, `number`) aren't supported as route data; if you need to
+ * carry a primitive, wrap it in an object.
+ */
+type ObjectLiteral = Record<string, any>;
+/**
+ * A registered route — what `IRouter.add` consumes. Only `path` and
+ * `method` are routing-relevant; `data` is opaque to the router and
+ * returned as-is on match. Apps store their own discrimination
+ * (e.g. handler-vs-nested-app) inside `data`.
+ *
+ * **Match-semantics convention:**
+ * - `method !== undefined` → router treats the entry as method-bound
+ *   and matches the path **exactly**.
+ * - `method === undefined` → entry is method-agnostic (middleware /
+ *   nested app) and matches by **prefix**.
+ *
+ * Custom `IRouter` implementations should honor this convention so
+ * apps can swap routers transparently.
+ */
+type Route<T extends ObjectLiteral = ObjectLiteral> = {
+  /**
+   * Mount path.
+   * - `undefined` means "no path" (route matches every request).
+   * - `'/'` behaves like "no path" for method-agnostic prefix routes
+   *   (middleware / mount-less nested apps).
+   * - Method-bound `'/'` is treated as an exact root match
+   *   (`app.get('/', …)` matches only the root).
+   */
+  path?: Path;
+  /**
+   * Bound HTTP method. When set, the router treats this route as an
+   * exact match; when undefined, the route matches by prefix.
+   */
+  method?: MethodName;
+  /**
+   * Opaque to the router. Returned via `RouteMatch.route.data` on
+   * match; consumers (typically `App`) decide what's inside.
+   */
+  data: T;
+};
+/**
+ * A single matched route returned by `IRouter.lookup`. The dispatch
+ * loop consumes these instead of walking the raw routes — `params`
+ * are pre-extracted at lookup time so we don't re-run the matcher
+ * later, and `path` (when set) tells the loop how much of
+ * `event.path` to strip when recursing into a child app.
+ */
+type RouteMatch<T extends ObjectLiteral = ObjectLiteral> = {
+  route: Route<T>;
+  /**
+   * Registration index in the router. Used by the dispatch loop's
+   * `setNext` continuation ("resume from index + 1") and by
+   * `App.clone()` to re-register routes in their original order.
+   */
+  index: number;
+  /**
+   * Path params extracted from the route's matcher. Values are
+   * `string` (or `undefined` for an optional param that didn't
+   * match). Empty object when the route has no path or no params.
+   */
+  params: Record<string, string | undefined>;
+  /**
+   * For routes with a matcher: the path substring the matcher
+   * consumed. Used by `executePipelineStepChildDispatch` to strip
+   * the matched prefix off `event.path` before dispatching into a
+   * child app. Undefined for routes without a matcher.
+   */
+  path?: string;
+};
+//#endregion
+//#region src/router/types.d.ts
+/**
+ * Options shared by every built-in router. Custom `IRouter`
+ * implementations are encouraged to extend this so users can swap
+ * routers without rewiring caching.
+ *
+ * - `cache` (omitted): no caching — every `lookup()` runs the
+ *   router's full match logic. This is the default.
+ * - `cache: <ICache>`: enable lookup memoization. Pass `LruCache`
+ *   for the built-in bounded LRU, or your own `ICache` (e.g.
+ *   wrapping `lru-cache` for TTL or size-based eviction).
+ *
+ * The router is responsible for invalidating its own cache whenever
+ * `add()` is called — registering a new route can change the match
+ * set for any cached path.
+ */
+type BaseRouterOptions<T extends ObjectLiteral = ObjectLiteral> = {
+  cache?: ICache<readonly RouteMatch<T>[]>;
+};
+/**
+ * Pluggable strategy for storing routes and answering "which entries
+ * match this path?". The default `LinearRouter` walks the stored
+ * entries linearly. Alternative implementations (radix tree,
+ * aggregated regex, …) can swap in via `AppContext.router` to
+ * skip the walk entirely on apps with many routes.
+ *
+ * The router operates on `Route<T>` where `T` is opaque data; the
+ * router never inspects `entry.data`. Only `entry.path` and
+ * `entry.method` are routing-relevant.
+ *
+ * **Match-semantics convention** (custom implementations must honor):
+ * - `entry.method !== undefined` → match the path **exactly** (the
+ *   entry is method-bound, e.g. a verb-shortcut handler).
+ * - `entry.method === undefined` → match by **prefix** (middleware,
+ *   nested apps).
+ *
+ * Method matching against the request method is kept at the dispatch-
+ * loop call site, not here, because method semantics differ between
+ * handler and nested-app entries (only handler entries are
+ * method-bound).
+ */
+interface IRouter<T extends ObjectLiteral = ObjectLiteral> {
+  /**
+   * Register a route. Entries are stored in registration order —
+   * the order they were passed to `App.use` / `.get` / `.post` /
+   * etc. — and lookup results preserve that order.
+   */
+  add(route: Route<T>): void;
+  /**
+   * Return every entry that matches the given path, in registration
+   * order. The dispatch loop iterates this list; nested `setNext`
+   * re-entries resume from a later index in the same list.
+   *
+   * `method`, when provided, is the request HTTP method. Routers
+   * MAY use it to filter at lookup time (e.g. method-bucketed
+   * tries) — but the App's dispatch loop still runs its own
+   * method check on every returned match, so a router that
+   * ignores `method` and emits more candidates than necessary
+   * stays correct, just not optimally fast.
+   *
+   * When the request method is `OPTIONS` (auto-Allow surface) or
+   * `HEAD` (falls through to GET), method-aware routers should
+   * widen their emission to cover those cases — see the OPTIONS /
+   * HEAD handling notes on `TrieRouter` for the canonical
+   * implementation.
+   */
+  lookup(path: string, method?: MethodNameLike): readonly RouteMatch<T>[];
+  /**
+   * Return a fresh, **empty** router of the same shape — same class
+   * for leaf implementations; composable wrappers should recursively
+   * clone their inner router. Used by `App.install()` and
+   * `App.clone()` so plugin sub-apps and cloned apps preserve the
+   * active router family instead of silently downgrading to
+   * `LinearRouter`.
+   */
+  clone(): IRouter<T>;
+}
+//#endregion
+//#region src/app/types.d.ts
+type AppOptions = {
+  /**
+   * Global request timeout in milliseconds.
+   *
+   * Applies to the entire dispatch pipeline in `fetch()`. When exceeded,
+   * the request is aborted and a 408 response is returned. The AbortSignal
+   * on the event is also aborted for cooperative cancellation.
+   */
+  timeout?: number;
+  /**
+   * Default per-handler timeout in milliseconds.
+   *
+   * Applies individually to each handler's `fn()` execution. Handlers can
+   * override this value via their own `timeout` option — see
+   * `handlerTimeoutOverridable` to control whether overrides can extend
+   * or only narrow this default.
+   */
+  handlerTimeout?: number;
+  /**
+   * Whether handlers can extend the `handlerTimeout` default.
+   *
+   * When `false` (default), a handler's `timeout` is clamped to
+   * `Math.min(handlerTimeout, handler.timeout)`. When `true`, the
+   * handler's `timeout` fully replaces the router default.
+   */
+  handlerTimeoutOverridable?: boolean;
+  /**
+   * Number of trailing labels in the request hostname that make up
+   * the registrable domain (e.g. `example.com` → 2). Subdomain
+   * helpers strip this many labels from the right before returning
+   * the subdomain portion.
+   */
+  subdomainOffset?: number;
+  /**
+   * Maximum number of proxy IPs to walk when resolving the client
+   * IP from `X-Forwarded-For`. Caps how far back the chain is
+   * trusted, regardless of `trustProxy`.
+   */
+  proxyIpMax?: number;
+  /**
+   * ETag generator, or `null` to disable ETag/304 entirely.
+   *
+   * - `undefined` (the default): consumers fall back to a
+   *   framework-provided `EtagFn`.
+   * - `null`: explicit opt-out — the response pipeline branches
+   *   synchronously and skips the `await applyEtag(...)` microtask hop.
+   * - `EtagFn`: the user's own generator.
+   */
+  etag?: EtagFn | null;
+  /**
+   * Predicate that decides whether a given upstream address is a
+   * trusted proxy when resolving the client IP / protocol /
+   * hostname from forwarding headers.
+   */
+  trustProxy?: TrustProxyFn;
+};
+/**
+ * User-facing input variant of `AppOptions`.
+ *
+ * Accepts looser shapes for `etag` and `trustProxy` (string,
+ * boolean, list-of-CIDRs, …) which `normalizeAppOptions` lowers to
+ * the resolved `EtagFn | null` / `TrustProxyFn` shape stored on the
+ * App.
+ */
+type AppOptionsInput = Omit<AppOptions, 'etag' | 'trustProxy'> & {
+  /**
+   * ETag input — accepts an `EtagFn`, `false`/`null` to disable,
+   * or other shapes accepted by `buildEtagFn`. Normalized to
+   * `EtagFn | null` on the App.
+   */
+  etag?: EtagInput;
+  /**
+   * Trust-proxy input — accepts a predicate, a list of trusted
+   * CIDRs, `'loopback'`, etc., as accepted by `buildTrustProxyFn`.
+   * Normalized to `TrustProxyFn` on the App.
+   */
+  trustProxy?: TrustProxyInput;
+};
+/**
+ * Constructor input for `App`.
+ *
+ * Splits true runtime options (which propagate to mounted children
+ * via mount-time inheritance) from App-local identity (`name`,
+ * `path`) and constructor injectables (`hooks`, `plugins`,
+ * `router`). Keeping these separate prevents identity from leaking
+ * across the mount boundary — e.g. a parent's `path: '/api'` would
+ * otherwise propagate into a child whose own `path` is unset and
+ * silently double-prefix on registration.
+ */
+type AppContext = {
+  /**
+   * Optional label for the App instance.
+   */
+  name?: string;
+  /**
+   * Registration-time path prefix for entries registered on this
+   * App.
+   *
+   * When set, every entry registered via `use`, `get`, `post`, …
+   * has this prefix prepended to its mount path.
+   * `new App({ path: '/api' })` followed by `app.get('/users', h)`
+   * is equivalent to `app.get('/api/users', h)` on an App without
+   * a `path`.
+   *
+   * Path matching itself still happens inside the active `IRouter`
+   * — this only affects how entries are registered, not how
+   * lookup is performed. Local to this App; not propagated to
+   * mounted children.
+   */
+  path?: Path;
+  /**
+   * Runtime options that propagate to mounted children via
+   * mount-time inheritance.
+   */
+  options?: AppOptionsInput;
+  /**
+   * Lifecycle hook registry. Defaults to a fresh `Hooks` instance.
+   * Pass an existing registry to share listeners across Apps (used
+   * by `clone()` to seed the copy with the original's listeners).
+   */
+  hooks?: IHooks;
+  /**
+   * Map of installed plugin name → version. Defaults to an empty
+   * map. Used by `clone()` to carry the installed-plugin registry
+   * over so duplicate installs are still rejected on the copy.
+   */
+  plugins?: Map<string, string | undefined>;
+  /**
+   * Pluggable router (route table). Defaults to `LinearRouter` —
+   * walks registered entries linearly per request. Swap in an
+   * alternative (e.g. `TrieRouter`) on apps with many routes.
+   */
+  router?: IRouter<RouteEntry>;
+};
+/**
+ * App-internal data that gets stored as `Route.data` in the active
+ * router. Tagged union — the discriminator `type` (HANDLER / APP)
+ * tells the dispatch loop which branch of the union to read.
+ *
+ * `path` and `method` are not part of this type — they live on
+ * `Route<RouteEntry>` itself (the router's routing-relevant fields),
+ * and App resolves the handler's intrinsic method into `Route.method`
+ * at registration time.
+ */
+type AppRouteEntry = {
+  /**
+   * Discriminator marking this entry as a mounted child App (vs a
+   * leaf handler). The dispatch loop branches on this to recurse
+   * via `IApp.dispatch` rather than invoking a handler `fn`.
+   */
+  type: typeof RouteEntryType.APP;
+  /**
+   * The mounted child App. Path/method live on the wrapping
+   * `Route<RouteEntry>`, not here.
+   */
+  data: IApp;
+};
+/**
+ * Leaf entry in the route table: a handler invoked directly by the
+ * dispatch loop.
+ */
+type HandlerRouteEntry = {
+  /**
+   * Discriminator marking this entry as a leaf handler (vs a
+   * mounted child App).
+   */
+  type: typeof RouteEntryType.HANDLER;
+  /**
+   * The handler invoked when this entry matches. Path/method live
+   * on the wrapping `Route<RouteEntry>`, not here.
+   */
+  data: Handler;
+};
+/**
+ * Tagged union of route-table entries. The active `IRouter` stores
+ * one of these as `Route.data` per registered entry; the dispatch
+ * loop reads `type` to choose the right branch.
+ */
+type RouteEntry = AppRouteEntry | HandlerRouteEntry;
+type AppPipelineContext = {
+  /**
+   * Current pipeline phase — drives the state machine in
+   * `App.executePipelineStep`. Mutated as the loop advances.
+   */
+  step: AppPipelineStep;
+  /**
+   * The dispatcher event being processed. Carries request, path,
+   * params, and the response accumulator across pipeline steps.
+   */
+  event: IDispatcherEvent;
+  /**
+   * `true` when this dispatch is the outermost App on the call
+   * stack (the root). Captured in `App.dispatch` from the event's
+   * pre-overwrite `appOptions` and used to gate root-only
+   * behaviour like OPTIONS auto-Allow.
+   */
+  isRoot: boolean;
+  /**
+   * Position within `matches`. Replaces the old "raw stack index" —
+   * the dispatch loop now iterates the resolved-matches list rather
+   * than the unfiltered registration order.
+   */
+  matchIndex: number;
+  /**
+   * Resolved matches for the current `event.path`, populated on the
+   * first LOOKUP entry and threaded through `setNext` recursion so
+   * we don't re-run `IRouter.lookup` per cycle. Invalidated
+   * automatically when `event.path` changes (a hook mutating the
+   * path between entries triggers a refresh).
+   */
+  matches?: readonly RouteMatch<RouteEntry>[];
+  /**
+   * The `event.path` that was used to compute `matches`. Stored so
+   * we can detect a mid-walk path mutation and refresh the cache.
+   */
+  matchesPath?: string;
+  /**
+   * The Response produced by the pipeline. Set by handlers (via
+   * `toResponse`) or by terminal pipeline steps; returned from
+   * `App.dispatch` once `FINISH` is reached.
+   */
+  response?: Response;
+};
+interface IApp extends IDispatcher {
+  /**
+   * Optional label for the router instance.
+   */
+  readonly name?: string;
+  /**
+   * Public entry point — processes a request through the pipeline
+   * and returns a Response (with 404/500 fallbacks).
+   */
+  fetch(request: AppRequest): Promise<Response>;
+  /**
+   * Return a new router that mirrors this one but owns independent
+   * mountable state — fresh stack of shallow-copied entries (handlers and
+   * child routers shared by reference), fresh `Hooks` seeded with the
+   * current listeners, shallow copy of options, and a fresh plugins map.
+   *
+   * Intended for mounting the same logical router under multiple paths
+   * without sharing mutable state across mount points.
+   */
+  clone(): IApp;
+  /**
+   * Swap the active `IRouter`. Every previously-registered route
+   * is replayed onto the new router so lookups stay correct. Any
+   * cache the previous router carried is dropped along with it.
+   *
+   * Useful when the right router family is only known after
+   * routes are registered (a SmartRouter-style decision), or for
+   * comparing implementations mid-flight without rebuilding the
+   * App.
+   */
+  setRouter(router: IRouter<RouteEntry>): void;
+  /**
+   * Check if a plugin with the given name is installed on this router.
+   */
+  hasPlugin(name: string): boolean;
+  /**
+   * Get the version of an installed plugin by name on this router,
+   * or `undefined` if the plugin is not installed here.
+   */
+  getPluginVersion(name: string): string | undefined;
+  /**
+   * Register a handler, router, or plugin.
+   * When a path is provided, the item is mounted at that path.
+   */
+  use(router: IApp): this;
+  use(handler: Handler | HandlerOptions): this;
+  use(plugin: Plugin): this;
+  use(path: Path, router: IApp): this;
+  use(path: Path, handler: Handler | HandlerOptions): this;
+  use(path: Path, plugin: Plugin): this;
+  /** Register GET handler(s). */
+  get(...handlers: (Handler | HandlerOptions)[]): this;
+  get(path: Path, ...handlers: (Handler | HandlerOptions)[]): this;
+  /** Register POST handler(s). */
+  post(...handlers: (Handler | HandlerOptions)[]): this;
+  post(path: Path, ...handlers: (Handler | HandlerOptions)[]): this;
+  /** Register PUT handler(s). */
+  put(...handlers: (Handler | HandlerOptions)[]): this;
+  put(path: Path, ...handlers: (Handler | HandlerOptions)[]): this;
+  /** Register PATCH handler(s). */
+  patch(...handlers: (Handler | HandlerOptions)[]): this;
+  patch(path: Path, ...handlers: (Handler | HandlerOptions)[]): this;
+  /** Register DELETE handler(s). */
+  delete(...handlers: (Handler | HandlerOptions)[]): this;
+  delete(path: Path, ...handlers: (Handler | HandlerOptions)[]): this;
+  /** Register HEAD handler(s). */
+  head(...handlers: (Handler | HandlerOptions)[]): this;
+  head(path: Path, ...handlers: (Handler | HandlerOptions)[]): this;
+  /** Register OPTIONS handler(s). */
+  options(...handlers: (Handler | HandlerOptions)[]): this;
+  options(path: Path, ...handlers: (Handler | HandlerOptions)[]): this;
+  /**
+   * Add a hook listener.
+   */
+  on(name: typeof HookName.START | typeof HookName.END | typeof HookName.CHILD_DISPATCH_BEFORE | typeof HookName.CHILD_DISPATCH_AFTER, fn: HookDefaultListener): HookUnsubscribeFn;
+  on(name: typeof HookName.CHILD_MATCH, fn: HookDefaultListener): HookUnsubscribeFn;
+  on(name: typeof HookName.ERROR, fn: HookErrorListener): HookUnsubscribeFn;
+  /**
+   * Remove a specific or all hook listeners for the given hook name.
+   */
+  off(name: HookName): this;
+  off(name: HookName, fn: HookListener): this;
+}
+//#endregion
+//#region src/error/create.d.ts
+/**
+ * Create an internal error object by
+ * - an existing AppError (returned as-is)
+ * - an HTTPError (wrapped into a AppError preserving status)
+ * - an Error (wrapped preserving message and cause)
+ * - an options object (status, message, etc.)
+ * - a message string
+ *
+ * @param input
+ */
+declare function createError(input: HTTPErrorInput | unknown): AppError;
+//#endregion
+//#region src/error/is.d.ts
+declare function isError(input: unknown): input is AppError;
+//#endregion
+//#region src/response/helpers/cache.d.ts
+type ResponseCacheHeadersOptions = {
+  maxAge?: number;
+  modifiedTime?: string | Date;
+  cacheControls?: string[];
+};
+declare function setResponseCacheHeaders(event: IAppEvent, options?: ResponseCacheHeadersOptions): void;
+//#endregion
+//#region src/response/helpers/event-stream/types.d.ts
+/**
+ * https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#event_stream_format
+ */
+type EventStreamMessage = {
+  /**
+   * The event ID to set the EventSource object's last event ID value.
+   */
+  id?: string;
+  /**
+   * The reconnection time.
+   * If the connection to the server is lost, the browser will wait for the specified time before attempting to reconnect.
+   * This must be an integer, specifying the reconnection time in milliseconds.
+   */
+  retry?: number;
+  /**
+   * The data field for the message.
+   */
+  data: string;
+  /**
+   * A string identifying the type of event described.
+   */
+  event?: string;
+};
+type EventStreamListener<T = any> = (err: Error | null, data: T) => void | Promise<void>;
+//#endregion
+//#region src/response/helpers/event-stream/module.d.ts
+type EventStreamOptions = {
+  maxMessageSize?: number;
+};
+type EventStreamHandle = {
+  write(message: string | EventStreamMessage): boolean;
+  end(): void;
+  response: Response;
+};
+declare function createEventStream(event: IAppEvent, options?: EventStreamOptions): EventStreamHandle;
+//#endregion
+//#region src/response/helpers/event-stream/utils.d.ts
+declare function serializeEventStreamMessage(message: EventStreamMessage): string;
+//#endregion
+//#region src/response/helpers/header.d.ts
+declare function appendResponseHeader(event: IAppEvent, name: string, value: string | string[]): void;
+declare function appendResponseHeaderDirective(event: IAppEvent, name: string, value: string | string[]): void;
+//#endregion
+//#region src/response/helpers/header-disposition.d.ts
+declare function setResponseHeaderAttachment(event: IAppEvent, filename?: string): void;
+declare function setResponseHeaderInline(event: IAppEvent, filename?: string): void;
+//#endregion
+//#region src/response/helpers/header-content-type.d.ts
+declare function setResponseHeaderContentType(event: IAppEvent, input: string, ifNotExists?: boolean): void;
+//#endregion
+//#region src/response/helpers/send-accepted.d.ts
+declare function sendAccepted(event: IAppEvent, data?: unknown): Promise<Response>;
+//#endregion
+//#region src/response/helpers/send-created.d.ts
+declare function sendCreated(event: IAppEvent, data?: unknown): Promise<Response>;
+//#endregion
+//#region src/response/helpers/send-file.d.ts
+type SendFileContentOptions = {
+  end?: number;
+  start?: number;
+};
+/**
+ * File metadata used by {@link sendFile}. All fields are optional, but each
+ * missing field disables related response features:
+ *
+ * - `size`  — without it, range requests, `Accept-Ranges`, `Content-Length`,
+ *             `ETag`, and `Last-Modified` are all omitted (the response is sent
+ *             without HTTP-level caching or seekability).
+ * - `mtime` — without it, `Last-Modified` is omitted and the `ETag` is not
+ *             emitted (`ETag` requires both `size` and `mtime`).
+ * - `name`  — falls back to `SendFileOptions.name` when set; if both are
+ *             missing, no `Content-Disposition` or extension-derived
+ *             `Content-Type` is set.
+ */
+type SendFileStats = {
+  size?: number;
+  mtime?: Date | number | string;
+  name?: string;
+};
+type SendFileDisposition = 'attachment' | 'inline';
+type SendFileContent = ReadableStream | ArrayBuffer | Uint8Array;
+type SendFileOptions = {
+  stats: (() => Promise<SendFileStats> | SendFileStats) | SendFileStats;
+  content: (options: SendFileContentOptions) => Promise<SendFileContent> | SendFileContent;
+  /**
+   * @deprecated Use `disposition: 'attachment'` instead. Kept for backwards
+   * compatibility — when `disposition` is set, it takes precedence.
+   */
+  attachment?: boolean;
+  disposition?: SendFileDisposition;
+  name?: string;
+};
+declare function sendFile(event: IAppEvent, options: SendFileOptions): Promise<Response>;
+//#endregion
+//#region src/response/helpers/send-format.d.ts
+type ResponseFormatHandler = () => Response | unknown;
+type ResponseFormats = {
+  default: ResponseFormatHandler;
+  [key: string]: ResponseFormatHandler;
+};
+declare function sendFormat(event: IAppEvent, input: ResponseFormats): Response | unknown | undefined;
+//#endregion
+//#region src/response/helpers/send-redirect.d.ts
+declare function sendRedirect(event: IAppEvent, location: string, statusCode?: number): Response;
+//#endregion
+//#region src/response/helpers/send-stream.d.ts
+declare function sendStream(event: IAppEvent, stream: ReadableStream): Response;
+//#endregion
+//#region src/response/helpers/utils.d.ts
+declare function setResponseContentTypeByFileName(event: IAppEvent, fileName: string): void;
+//#endregion
+//#region src/response/to-response.d.ts
+/**
+ * Convert a handler's return value into a Web `Response`.
+ *
+ * Returns synchronously for the common cases (string, JSON object,
+ * binary, stream, blob) when ETag generation is disabled. Returns a
+ * `Promise` when an ETag must be computed (the generator is async).
+ *
+ * Callers that want the async return uniformly can `await` the result
+ * — `await` on a non-Promise still works but pays a microtask hop.
+ * The App fast path branches on `instanceof Promise` to keep the
+ * sync return truly sync.
+ */
+declare function toResponse(value: unknown, event: IAppEvent): Response | undefined | Promise<Response | undefined>;
+//#endregion
+//#region src/request/helpers/cache.d.ts
+declare function isRequestCacheable(event: IAppEvent, modifiedTime: string | Date): boolean;
+//#endregion
+//#region src/request/helpers/header.d.ts
+declare function getRequestHeader(event: IAppEvent, name: string): string | null;
+//#endregion
+//#region src/request/helpers/header-accept.d.ts
+declare function getRequestAcceptableContentTypes(event: IAppEvent): string[];
+declare function getRequestAcceptableContentType(event: IAppEvent, input?: string | string[]): string | undefined;
+//#endregion
+//#region src/request/helpers/header-accept-charset.d.ts
+declare function getRequestAcceptableCharsets(event: IAppEvent): string[];
+declare function getRequestAcceptableCharset(event: IAppEvent, input: string | string[]): string | undefined;
+//#endregion
+//#region src/request/helpers/header-accept-encoding.d.ts
+declare function getRequestAcceptableEncodings(event: IAppEvent): string[];
+declare function getRequestAcceptableEncoding(event: IAppEvent, input: string | string[]): string | undefined;
+//#endregion
+//#region src/request/helpers/header-accept-language.d.ts
+declare function getRequestAcceptableLanguages(event: IAppEvent): string[];
+declare function getRequestAcceptableLanguage(event: IAppEvent, input?: string | string[]): string | undefined;
+//#endregion
+//#region src/request/helpers/header-content-type.d.ts
+declare function matchRequestContentType(event: IAppEvent, contentType: string): boolean;
+//#endregion
+//#region src/request/helpers/hostname.d.ts
+type RequestHostNameOptions = {
+  trustProxy?: TrustProxyInput;
+};
+declare function getRequestHostName(event: IAppEvent, options?: RequestHostNameOptions): string | undefined;
+//#endregion
+//#region src/request/helpers/ip.d.ts
+type RequestIpOptions = {
+  trustProxy?: TrustProxyInput;
+};
+/**
+ * Get the client IP address from the request.
+ *
+ * When `trustProxy` is configured, walks the `X-Forwarded-For` chain
+ * and returns the rightmost untrusted address (the actual client IP).
+ * Falls back to `event.request.ip` (the direct connection IP).
+ */
+declare function getRequestIP(event: IAppEvent, options?: RequestIpOptions): string | undefined;
+//#endregion
+//#region src/request/helpers/negotiator.d.ts
+declare function useRequestNegotiator(event: IAppEvent): Negotiator;
+//#endregion
+//#region src/request/helpers/protocol.d.ts
+type RequestProtocolOptions = {
+  trustProxy?: TrustProxyInput;
+  default?: string;
+};
+declare function getRequestProtocol(event: IAppEvent, options?: RequestProtocolOptions): string;
+//#endregion
+//#region src/router/linear/module.d.ts
+/**
+ * Default router — walks registered routes linearly per request and
+ * runs each route's mount-level matcher (built via `buildRoutePathMatcher`,
+ * path-to-regexp-backed). Routes without a mount path (mount-less
+ * middleware / nested apps registered via `.use(handler)`) match every
+ * request directly — there is no per-route `matchPath()` fallback.
+ *
+ * Behaviour-preserving wrapper around the previous in-line stack walk
+ * in `executePipelineStepLookup`. The matcher allocations live here
+ * (not on the registered route), so routers using a different matching
+ * strategy (radix tree, aggregated regex, …) can ignore this file
+ * entirely.
+ *
+ * Optional per-router lookup cache: pass an `ICache` via
+ * `BaseRouterOptions.cache` to skip the linear walk on repeated
+ * requests for the same path. Default is no caching.
+ */
+declare class LinearRouter<T extends ObjectLiteral = ObjectLiteral> implements IRouter<T> {
+  protected _routes: Route<T>[];
+  protected _matchers: (IPathMatcher | undefined)[];
+  protected cache?: ICache<readonly RouteMatch<T>[]>;
+  constructor(options?: BaseRouterOptions<T>);
+  add(route: Route<T>): void;
+  lookup(path: string, _method?: MethodNameLike): readonly RouteMatch<T>[];
+  clone(): IRouter<T>;
+}
+//#endregion
+//#region src/router/smart/module.d.ts
+type SmartRouterOptions<T extends ObjectLiteral = ObjectLiteral> = BaseRouterOptions<T> & {
+  /**
+       * Route count at or above which `SmartRouter` switches from
+       * `LinearRouter` (faster at small N) to `TrieRouter` (faster
+       * at large N). Default `30`.
+       */
+  threshold?: number;
+};
+/**
+ * Auto-selecting router. Accumulates registered routes in a pending
+ * buffer; on the first `lookup()` call, picks `LinearRouter` or
+ * `TrieRouter` based on the registered route count and replays the
+ * pending list onto the chosen inner router. Every subsequent call
+ * — `add`, `lookup`, `clone` — forwards to the inner.
+ *
+ * Use this when you don't want to commit to a router family up-front
+ * (e.g. a library that registers a variable number of routes
+ * depending on configuration). For known workloads, prefer the
+ * concrete router — `SmartRouter` adds one indirection per call.
+ *
+ * Inspired by Hono's `SmartRouter` (which auto-selects across more
+ * candidates including `RegExpRouter`); ours covers the only choice
+ * that matters in routup today: linear-vs-trie at the registration-
+ * size crossover.
+ */
+declare class SmartRouter<T extends ObjectLiteral = ObjectLiteral> implements IRouter<T> {
+  protected inner?: IRouter<T>;
+  protected pending: Route<T>[];
+  protected readonly threshold: number;
+  /**
+   * Cache handed off to whichever inner router gets chosen. Stays
+   * `undefined` if the user didn't configure one.
+   */
+  protected readonly cache?: ICache<readonly RouteMatch<T>[]>;
+  constructor(options?: SmartRouterOptions<T>);
+  add(route: Route<T>): void;
+  lookup(path: string, method?: string): readonly RouteMatch<T>[];
+  clone(): IRouter<T>;
+  /**
+   * Pick the inner router based on the registered route count.
+   * `LinearRouter` for tiny tables, `TrieRouter` past the
+   * configured threshold.
+   *
+   * @protected
+   */
+  protected choose(): IRouter<T>;
+}
+//#endregion
+//#region src/router/trie/types.d.ts
+/**
+ * Tagged param-extraction instruction. Built at registration time
+ * during `insertIntoTrie`; consumed at lookup time to build the
+ * params object directly from the request's pre-split segments —
+ * no regex execution per match.
+ *
+ * - `segment`: capture `segments[depth]` as `name`.
+ * - `splat`: capture `segments[depth..]` joined with `/` as `name`.
+ *   `name` is `'*'` for the unnamed bare splat (`/files/*`).
+ */
+type ParamCapture = {
+  kind: 'segment';
+  depth: number;
+  name: string;
+} | {
+  kind: 'splat';
+  depth: number;
+  name: string;
+};
+/**
+ * Per-variant route record stored at a trie leaf.
+ *
+ * `paramsIndexMap` populated for trie-walked variants so lookup can
+ * extract params without running `matcher.exec`. `matcher` is only
+ * populated for universal-bucket routes (registered paths the trie
+ * parser couldn't handle — regex constraints, compound segments,
+ * escapes — that fall back to path-to-regexp).
+ *
+ * `index` is shared across every variant produced from a single
+ * `add()` call so the candidate list deduplicates naturally on
+ * registration order.
+ */
+type IndexedRoute<T extends ObjectLiteral = ObjectLiteral> = {
+  route: Route<T>;
+  index: number;
+  /**
+   * Universal-bucket-only — populated for paths the trie parser
+   * couldn't handle (regex constraints, compound segments, escapes).
+   * The lookup loop runs `matcher.exec(path)` to confirm the match
+   * and extract params, identical to `LinearRouter`.
+   */
+  matcher?: IPathMatcher;
+  /**
+   * Trie-walked-only — populated for variants that came out of
+   * `parsePath`. The lookup loop walks this list to build the
+   * `params` object directly from request segments, no regex.
+   */
+  paramsIndexMap?: ParamCapture[];
+  /**
+   * Trie-walked-only — how many request segments this variant
+   * consumes when matched. Used to compute `match.path` (the
+   * matched prefix) at lookup time without re-running a matcher.
+   *
+   * - Exact / prefix variants: `segments.length` (consume up to
+   *   the leaf).
+   * - Splat variants: depth of the splat segment (it then absorbs
+   *   the rest — see `splatTerminated`).
+   */
+  matchDepth?: number;
+  /**
+   * Trie-walked-only — `true` when this variant ends in a splat.
+   * `match.path` is then computed from the *full* request length
+   * (the splat absorbed every remaining segment), not from
+   * `matchDepth` (which is only the depth of the splat node).
+   */
+  splatTerminated?: boolean;
+};
+type Segment = {
+  kind: 'static';
+  value: string;
+} | {
+  kind: 'param';
+  name: string;
+} | {
+  kind: 'splat';
+  name: string;
+};
+/**
+ * Method-keyed bucket of indexed routes. The empty-string key
+ * (`''`) holds method-agnostic entries (handlers registered without
+ * a method binding). Stored as a prototype-less object so user-
+ * controlled method strings can't collide with `Object.prototype`
+ * keys (`__proto__`, `hasOwnProperty`, …).
+ */
+type MethodBuckets<T extends ObjectLiteral = ObjectLiteral> = Record<string, IndexedRoute<T>[]>;
+type TrieNode<T extends ObjectLiteral = ObjectLiteral> = {
+  staticChildren: Map<string, TrieNode<T>>;
+  paramChild?: TrieNode<T>;
+  /**
+   * Entries whose path ends with a splat at this depth (`/files/*`,
+   * `/foo/*name`, …). They match the current node and every deeper
+   * request path. Bucketed by HTTP method (`''` = method-agnostic).
+   */
+  splatRoutes: MethodBuckets<T>;
+  /**
+   * Exact-match routes whose path ends at this node — only matched
+   * when the request path is fully consumed at this depth.
+   * Bucketed by HTTP method (`''` = method-agnostic).
+   */
+  exactRoutes: MethodBuckets<T>;
+  /**
+   * Prefix-match routes (middleware / nested apps) whose path ends
+   * at this node — matched whenever this node is reached,
+   * regardless of remaining depth. Not bucketed: middleware is
+   * method-agnostic by design (the inner handler does its own
+   * method discrimination).
+   */
+  prefixRoutes: IndexedRoute<T>[];
+};
+//#endregion
+//#region src/router/trie/module.d.ts
+/**
+ * Radix-trie router — registers routes into a per-segment tree at
+ * `add()` time and walks the tree at `lookup()` to collect
+ * candidates by structure rather than by linear scan.
+ *
+ * Inspired by Hono's `TrieRouter` and rou3. The trie handles
+ * routup's path vocabulary directly via its own parser
+ * (`./parser.ts`):
+ *
+ *   - Static segments (`/users`)
+ *   - Named params (`:id`)
+ *   - Optional params (`:id?`) — expanded to two route variants at
+ *     registration (T2)
+ *   - Optional groups (`/users{/edit}`) — same expansion strategy
+ *   - Bare and named splats (`/files/*`, `/files/*rest`)
+ *
+ * Per-leaf storage is bucketed by HTTP method (T4) so lookup
+ * narrows to the request method's bucket(s) instead of emitting
+ * every entry at the leaf and letting the dispatcher's filter
+ * discard mismatches.
+ *
+ * Param extraction is `paramsIndexMap`-driven (T3): a pre-built
+ * `Array<{ depth, name }>` per variant lets `extractTrieParams`
+ * read params straight from the request's pre-split segments — no
+ * regex execution per match.
+ *
+ * Paths the trie parser doesn't handle (compound segments like
+ * `/files/:n.ext`, escape sequences `\:`, regex constraints) and
+ * empty/root paths fall through to the `universal` bucket. That
+ * bucket still uses `path-to-regexp` via `buildRoutePathMatcher`,
+ * so correctness is preserved.
+ *
+ * Pure-static-spine fast path (`shortCircuit`): when the request
+ * walks a static spine with no param/splat/prefix siblings on any
+ * traversed node, the leaf's `exactRoutes` (filtered to the request
+ * method's buckets) is the full answer — no need to walk the param
+ * branch or collect prefix candidates at intermediate nodes.
+ */
+declare class TrieRouter<T extends ObjectLiteral = ObjectLiteral> implements IRouter<T> {
+  /**
+   * Monotonic counter assigned as the registration `index` on each
+   * route — the dispatch loop uses it to preserve registration
+   * order across the candidate list. App owns the canonical
+   * `Route<T>[]` list (Plan 019); the trie no longer keeps a
+   * parallel copy.
+   */
+  protected _routeCount: number;
+  protected root: TrieNode<T>;
+  /**
+   * Routes that bypass the trie — registered with no path, with
+   * the root path `/`, or with a path containing syntax the
+   * parser doesn't recognise. Walked linearly on every lookup,
+   * merged into the result in registration order.
+   */
+  protected universal: IndexedRoute<T>[];
+  protected cache?: ICache<readonly RouteMatch<T>[]>;
+  constructor(options?: BaseRouterOptions<T>);
+  add(route: Route<T>): void;
+  lookup(path: string, method?: MethodNameLike): readonly RouteMatch<T>[];
+  clone(): IRouter<T>;
+  /**
+   * T1: returns the pre-computed candidate list when the request's
+   * static spine has no param sibling, no prefix routes, and no
+   * splats along the way. The leaf node's `exactRoutes` (filtered
+   * to the request method's buckets) is then the complete answer —
+   * no need to walk the param branch or collect prefix/splat
+   * candidates from intermediate nodes. When any branch is
+   * encountered, returns `null` and the caller falls through to
+   * the regular `walk`.
+   */
+  protected shortCircuit(segments: string[], method: MethodNameLike | undefined): IndexedRoute<T>[] | null;
+  protected parseRequestPath(path: string): string[];
+  protected insertIntoTrie(segments: Segment[], route: Route<T>, index: number): void;
+  protected walk(node: TrieNode<T>, segments: string[], depth: number, collected: IndexedRoute<T>[], method: MethodNameLike | undefined): void;
+  protected isExactMatchRoute(route: Route<T>): boolean;
+  /**
+   * T5: copy params onto a prototype-less object so downstream
+   * lookups skip prototype-chain traversal and avoid `__proto__` /
+   * `hasOwnProperty` shadowing from user-controlled segment values.
+   */
+  protected assignParams(source: Record<string, string | undefined>): Record<string, string | undefined>;
+}
+//#endregion
+//#region src/router/utils.d.ts
+/**
+ * Build a path-to-regexp-backed `PathMatcher` for the route's mount
+ * path, applying the exact-vs-prefix convention every router should
+ * agree on:
+ *
+ * - `route.method !== undefined` → exact match (method-bound route)
+ * - `route.method === undefined` → prefix match (middleware / nested
+ *   app)
+ *
+ * Returns `undefined` when the route has no mount path — middleware
+ * registered without a path matches every request.
+ *
+ * Routers are free to ignore this helper and build their own match
+ * mechanism (radix tree, single aggregated regex, etc.) — it's
+ * provided as a convenience for routers that want path-to-regexp
+ * semantics with minimal boilerplate.
+ */
+declare function buildRoutePathMatcher<T extends ObjectLiteral = ObjectLiteral>(route: Route<T>): IPathMatcher | undefined;
+//#endregion
+//#region src/app/module.d.ts
+declare class App implements IApp {
+  /**
+   * A label for the router instance.
+   */
+  readonly name?: string;
+  /**
+   * Registration-time path prefix for entries registered on this
+   * App. Local to this instance — never inherited from a parent.
+   *
+   * @protected
+   */
+  protected _path?: Path;
+  /**
+   * Pluggable router (route table) — owns the "which entries match
+   * this path?" lookup. Defaults to `LinearRouter` (walks entries
+   * linearly per request); swap in via `AppContext.router`
+   * for a radix/trie implementation on apps with many routes.
+   *
+   * @protected
+   */
+  protected router: IRouter<RouteEntry>;
+  /**
+   * Lifecycle hook registry.
+   *
+   * @protected
+   */
+  protected hooks: IHooks;
+  /**
+   * Normalized options for this App instance.
+   *
+   * Frozen on construction and on every `extendOptions` update —
+   * once published to `event.appOptions` it is shared across all
+   * requests, and a handler must not be able to mutate
+   * router-global state. `extendOptions` therefore uses a
+   * functional update (build a new object, freeze it, replace
+   * the slot) rather than mutating in place.
+   */
+  protected _options: Readonly<AppOptions>;
+  /**
+   * Registry of installed plugins (name → version) on this router.
+   *
+   * @protected
+   */
+  protected plugins: Map<string, string | undefined>;
+  /**
+   * Every route registered on this App, in registration order.
+   *
+   * App owns the canonical list — the `IRouter` contract has no
+   * `routes` field, so cascades / clones / `setRouter` replay
+   * read from here instead of asking the router. Routes are
+   * pushed alongside every `this.router.add()` via the `register`
+   * helper.
+   *
+   * @protected
+   */
+  protected _routes: Route<RouteEntry>[];
+  constructor(input?: AppContext);
+  /**
+   * Register a route with the active router and record it on the
+   * App so we can replay it onto a different router later (see
+   * `setRouter`) and so cascades / clones have a source of truth
+   * independent of the router instance.
+   *
+   * @protected
+   */
+  protected register(route: Route<RouteEntry>): void;
+  /**
+   * Swap the active router. Replays every previously-registered
+   * route onto the new router so lookups stay correct.
+   *
+   * Useful for picking a router after route shape is known (e.g.
+   * a SmartRouter-style decision), or for testing alternatives
+   * mid-flight without rebuilding the App. Any cache the previous
+   * router carried is dropped along with it.
+   */
+  setRouter(router: IRouter<RouteEntry>): void;
+  /**
+   * Public entry point — creates a DispatcherEvent from the request,
+   * runs the pipeline, and returns a Response (with 404/500 fallbacks).
+   */
+  fetch(request: AppRequest): Promise<Response>;
+  protected buildFallbackResponse(request: AppRequest, event: IDispatcherEvent, status: number, message: string): Response;
+  /**
+   * Mount-time option inheritance — fill in any of this App's
+   * unset option keys from the supplied parent options. Called by
+   * `App.use(child)` after narrowing to `App` via `isAppInstance`.
+   *
+   * Public so callers don't need to reach into another App's
+   * protected fields: the parent passes its options by value and
+   * the child decides what to do with them.
+   *
+   * Shallow per-key merge. App-local concerns — `name`, `path`,
+   * `hooks`, `plugins`, `router`, and the router's cache — are
+   * deliberately not propagated; they sit on `AppContext`, not
+   * inside `AppOptions`.
+   *
+   * Cascades to any Apps already mounted on this one — a deeper
+   * grandchild gets the new keys too. Without this, mounting
+   * grandchild → child → parent in that order would leave the
+   * grandchild without parent's options (it adopted from child
+   * before child had them).
+   *
+   * Late mutation of the parent's options after this call does NOT
+   * propagate. `AppOptions` is configured at construction-and-mount;
+   * later changes are not a supported workflow.
+   */
+  extendOptions(incoming: Readonly<AppOptions>): void;
+  protected executePipelineStep(context: AppPipelineContext): Promise<void>;
+  protected executePipelineStepStart(context: AppPipelineContext): Promise<void>;
+  protected executePipelineStepLookup(context: AppPipelineContext): Promise<void>;
+  protected executePipelineStepChildBefore(context: AppPipelineContext): Promise<void>;
+  protected executePipelineStepChildAfter(context: AppPipelineContext): Promise<void>;
+  protected executePipelineStepChildDispatch(context: AppPipelineContext): Promise<void>;
+  protected executePipelineStepFinish(context: AppPipelineContext): Promise<void>;
+  dispatch(event: IDispatcherEvent): Promise<Response | undefined>;
+  delete(...handlers: (Handler | HandlerOptions)[]): this;
+  delete(path: Path, ...handlers: (Handler | HandlerOptions)[]): this;
+  get(...handlers: (Handler | HandlerOptions)[]): this;
+  get(path: Path, ...handlers: (Handler | HandlerOptions)[]): this;
+  post(...handlers: (Handler | HandlerOptions)[]): this;
+  post(path: Path, ...handlers: (Handler | HandlerOptions)[]): this;
+  put(...handlers: (Handler | HandlerOptions)[]): this;
+  put(path: Path, ...handlers: (Handler | HandlerOptions)[]): this;
+  patch(...handlers: (Handler | HandlerOptions)[]): this;
+  patch(path: Path, ...handlers: (Handler | HandlerOptions)[]): this;
+  head(...handlers: (Handler | HandlerOptions)[]): this;
+  head(path: Path, ...handlers: (Handler | HandlerOptions)[]): this;
+  options(...handlers: (Handler | HandlerOptions)[]): this;
+  options(path: Path, ...handlers: (Handler | HandlerOptions)[]): this;
+  protected useForMethod(method: MethodName, ...input: (Path | Handler | HandlerOptions)[]): void;
+  use(router: IApp): this;
+  use(handler: Handler | HandlerOptions): this;
+  use(plugin: Plugin): this;
+  use(path: Path, router: IApp): this;
+  use(path: Path, handler: Handler | HandlerOptions): this;
+  use(path: Path, plugin: Plugin): this;
+  /**
+   * Check if a plugin with the given name is installed on this router.
+   */
+  hasPlugin(name: string): boolean;
+  /**
+   * Get the version of an installed plugin by name on this router,
+   * or `undefined` if the plugin is not installed here.
+   */
+  getPluginVersion(name: string): string | undefined;
+  protected install(plugin: Plugin, context?: PluginInstallContext): this;
+  /**
+   * Return a new `App` that mirrors this one but owns independent
+   * mountable state.
+   *
+   * The new router has:
+   * - a fresh `stack` array of shallow-copied entries (handlers and child
+   *   routers are shared by reference; only the wrapping entries are new)
+   * - the same `pathMatcher` reference (it is stateless)
+   * - a fresh `Hooks` instance seeded with the current listeners
+   * - a shallow copy of `_options`
+   * - a fresh `plugins` map with the same entries
+   *
+   * Use this when the same logical router needs to be mounted under
+   * multiple paths — each mount can receive its own clone so subsequent
+   * mutations on one mount do not bleed into the others.
+   */
+  clone(): IApp;
+  /**
+   * Add a hook listener.
+   *
+   * @param name
+   * @param fn
+   * @param priority
+   */
+  on(name: typeof HookName.START | typeof HookName.END | typeof HookName.CHILD_DISPATCH_BEFORE | typeof HookName.CHILD_DISPATCH_AFTER, fn: HookDefaultListener, priority?: number): HookUnsubscribeFn;
+  on(name: typeof HookName.CHILD_MATCH, fn: HookDefaultListener, priority?: number): HookUnsubscribeFn;
+  on(name: typeof HookName.ERROR, fn: HookErrorListener, priority?: number): HookUnsubscribeFn;
+  /**
+   * Remove single or all hook listeners.
+   *
+   * @param name
+   */
+  off(name: HookName): this;
+  off(name: HookName, fn: HookListener): this;
+}
+//#endregion
+//#region src/app/options.d.ts
+declare function normalizeAppOptions(input: AppOptionsInput): AppOptions;
+//#endregion
+export { createError as $, HandlerSymbol as $t, sendFormat as A, isWebHandlerProvider as At, setResponseHeaderAttachment as B, CoreHandlerOptions as Bt, getRequestAcceptableContentTypes as C, isPluginError as Ct, setResponseContentTypeByFileName as D, isHandler as Dt, toResponse as E, matchHandlerMethod as Et, SendFileStats as F, fromNodeMiddleware as Ft, EventStreamHandle as G, ErrorHandlerOptions as Gt, appendResponseHeader as H, HandlerOptions as Ht, sendFile as I, NodeHandler as It, EventStreamListener as J, PathMatcher as Jt, EventStreamOptions as K, HandlerBaseOptions as Kt, sendCreated as L, NodeMiddleware as Lt, SendFileContentOptions as M, WebHandler as Mt, SendFileDisposition as N, WebHandlerProvider as Nt, sendStream as O, isHandlerOptions as Ot, SendFileOptions as P, fromNodeHandler as Pt, isError as Q, PathMatcherOptions as Qt, sendAccepted as R, defineCoreHandler as Rt, getRequestAcceptableContentType as S, PluginAlreadyInstalledError as St, isRequestCacheable as T, PluginErrorCode as Tt, appendResponseHeaderDirective as U, defineErrorHandler as Ut, setResponseHeaderInline as V, Handler as Vt, serializeEventStreamMessage as W, ErrorHandler as Wt, ResponseCacheHeadersOptions as X, Path as Xt, EventStreamMessage as Y, IPathMatcher as Yt, setResponseCacheHeaders as Z, PathMatcherExecResult as Zt, getRequestAcceptableLanguages as _, Plugin as _t, SmartRouter as a, AppEventCreateContext as an, HandlerRouteEntry as at, getRequestAcceptableCharset as b, PluginNotInstalledError as bt, RequestProtocolOptions as c, IAppEvent as cn, BaseRouterOptions as ct, RequestIpOptions as d, MethodName as dn, Route as dt, HandlerType as en, AppContext as et, getRequestIP as f, MethodNameLike as fn, RouteMatch as ft, getRequestAcceptableLanguage as g, isPlugin as gt, matchRequestContentType as h, HTTPErrorInput$1 as hn, ICache as ht, TrieRouter as i, AppEvent as in, AppRouteEntry as it, SendFileContent as j, fromWebHandler as jt, sendRedirect as k, isWebHandler as kt, getRequestProtocol as l, NextFn as ln, IRouter as lt, getRequestHostName as m, ErrorSymbol as mn, LruCacheOptions as mt, App as n, IDispatcher as nn, AppOptionsInput as nt, SmartRouterOptions as o, AppRequest as on, IApp as ot, RequestHostNameOptions as p, AppError as pn, LruCache as pt, createEventStream as q, isPath as qt, buildRoutePathMatcher as r, IDispatcherEvent as rn, AppPipelineContext as rt, LinearRouter as s, AppResponse as sn, RouteEntry as st, normalizeAppOptions as t, DispatcherEvent as tn, AppOptions as tt, useRequestNegotiator as u, HeaderName as un, ObjectLiteral as ut, getRequestAcceptableEncoding as v, PluginInstallContext as vt, getRequestHeader as w, PluginError as wt, getRequestAcceptableCharsets as x, PluginInstallError as xt, getRequestAcceptableEncodings as y, PluginInstallFn as yt, setResponseHeaderContentType as z, CoreHandler as zt };
+//# sourceMappingURL=index-kxLRw2Wc.d.mts.map