routup 6.0.0-beta.0 → 6.0.0-beta.2

package/dist/{index-kxLRw2Wc.d.mts → index-6qjxyFZh.d.mts}

@@ -97,7 +97,11 @@ interface IAppEvent {
    */
   readonly method: MethodNameLike;
   /**
-   * Accumulated mount path from nested routers.
+   * Prefix the active route was matched on (the substring of the
+   * request path the matcher consumed). Set per dispatched handler
+   * and restored when the handler returns; useful for static-asset
+   * / mount-aware helpers that need to strip this off `path` to
+   * recover a mount-relative path.
    */
   readonly mountPath: string;
   /**
@@ -234,7 +238,12 @@ interface IDispatcherEvent {
    */
   readonly method: MethodNameLike;
   /**
-   * Accumulated mount path from nested routers.
+   * Prefix the active route was matched on. Set per dispatched
+   * handler to the resolver's `match.path` (the substring of the
+   * request path the matcher consumed) and restored to the prior
+   * value when the handler returns. Static-asset / mount-aware
+   * helpers strip this off `event.path` to recover a mount-relative
+   * path.
    */
   mountPath: string;
   /**
@@ -251,16 +260,17 @@ interface IDispatcherEvent {
   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.
+   * entry to `App.dispatch`; restored on exit so that re-entering
+   * `App.dispatch` for the same event (programmatic use of the
+   * `IDispatcher` interface) leaves the caller's view intact.
    */
   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.
+   * `true` while an `App.dispatch` call is on the stack for this
+   * event. Used by `App.dispatch` to derive whether the current
+   * call is the root (and so should drive root-only behaviour like
+   * OPTIONS auto-Allow synthesis). Saved/restored around the
+   * dispatch body so re-entrant calls behave correctly.
    */
   isDispatching: boolean;
   /**
@@ -315,16 +325,17 @@ declare class DispatcherEvent implements IDispatcherEvent {
   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.
+   * entry to `App.dispatch` and restored on exit so re-entrant
+   * dispatch calls leave the caller's view intact. 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.
+   * `true` while an `App.dispatch` call is on the stack for this
+   * event. `App.dispatch` reads this on entry to derive `isRoot`
+   * and writes it on entry/exit so re-entrant calls behave
+   * correctly.
    */
   isDispatching: boolean;
   protected _dispatched: boolean;
@@ -360,54 +371,6 @@ declare class DispatcherEvent implements IDispatcherEvent {
   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";
@@ -416,6 +379,22 @@ declare const HandlerType: {
 type HandlerType = typeof HandlerType[keyof typeof HandlerType];
 declare const HandlerSymbol: unique symbol;
 //#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/path/type.d.ts
 type PathMatcherOptions = PathToRegexpOptions & ParseOptions;
 type PathMatcherExecResult = {
@@ -443,6 +422,31 @@ declare class PathMatcher implements IPathMatcher {
 declare function isPath(input: unknown): input is Path;
 //#endregion
 //#region src/handler/types-base.d.ts
+/**
+ * Side-effect callback fired before the handler's `fn` is invoked.
+ * Receives the same `AppEvent` the handler will see. Throwing here is
+ * equivalent to the handler throwing — `onError` (if set) fires next
+ * and the error propagates to the surrounding error chain. Return
+ * value is ignored; if you need to short-circuit, use middleware.
+ */
+type HandlerBeforeListener = (event: IAppEvent) => unknown | Promise<unknown>;
+/**
+ * Side-effect callback fired after the handler's `fn` returns and
+ * `toResponse` builds the final response. Receives the same
+ * `AppEvent` `fn` saw plus the produced `Response` (`undefined` when
+ * the handler did not produce a response). Throwing here is treated
+ * like the handler throwing — `onError` (if set) fires next and the
+ * already-built response is dropped in favour of the error path.
+ */
+type HandlerAfterListener = (event: IAppEvent, response: Response | undefined) => unknown | Promise<unknown>;
+/**
+ * Side-effect callback fired when the handler's `fn`, `onBefore`, or
+ * `onAfter` throws. Receives the resolved `AppError` and the
+ * handler's event. Throwing here replaces `event.error` with the
+ * new error before the pipeline observes it; returning normally
+ * lets the original error propagate.
+ */
+type HandlerErrorListener = (error: AppError, event: IAppEvent) => unknown | Promise<unknown>;
 type HandlerBaseOptions = {
   method?: Uppercase<MethodName> | Lowercase<MethodName>;
   path?: Path;
@@ -454,9 +458,24 @@ type HandlerBaseOptions = {
    * `handlerTimeoutOverridable` option.
    */
   timeout?: number;
-  onError?: HookErrorListener;
-  onBefore?: HookDefaultListener;
-  onAfter?: HookDefaultListener;
+  /**
+   * Instrumentation hook fired before `fn` is invoked. Plain
+   * optional callback — no event-name dispatch, no priorities;
+   * for cross-handler instrumentation, prefer middleware.
+   */
+  onBefore?: HandlerBeforeListener;
+  /**
+   * Instrumentation hook fired after the response is built (or
+   * the handler resolved without one). Receives `(event, response)`.
+   */
+  onAfter?: HandlerAfterListener;
+  /**
+   * Instrumentation hook fired when `fn` (or `onBefore`) throws.
+   * Receives `(error, event)`. Re-throwing replaces the active
+   * `event.error`; returning normally lets the original error
+   * propagate.
+   */
+  onError?: HandlerErrorListener;
 };
 //#endregion
 //#region src/handler/error/types.d.ts
@@ -490,7 +509,6 @@ type HandlerOptions = CoreHandlerOptions | ErrorHandlerOptions;
 //#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";
@@ -510,7 +528,6 @@ declare class Handler implements IDispatcher {
   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
@@ -683,7 +700,11 @@ type Plugin = {
 };
 type PluginInstallContext = {
   /**
-   * By specifying a path, the plugin will be installed as a child router.
+   * Mount-path prefix to prepend onto every route the plugin
+   * registers. Equivalent to passing the same prefix to
+   * `app.use(path, plugin)`. The plugin installs into a scratch
+   * `App`; that scratch is then flattened into the host App with
+   * this prefix joined onto each route.
    */
   path?: Path;
 };
@@ -712,22 +733,6 @@ type EtagInput = boolean | null | EtagOptions | EtagFn;
 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
@@ -764,14 +769,6 @@ interface ICache<V> {
    * 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
@@ -793,14 +790,12 @@ type LruCacheOptions = {
  * `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
@@ -858,8 +853,7 @@ 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.
+   * `setNext` continuation ("resume from index + 1").
    */
   index: number;
   /**
@@ -944,15 +938,6 @@ interface IRouter<T extends ObjectLiteral = ObjectLiteral> {
    * 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
@@ -1039,11 +1024,11 @@ type AppOptionsInput = Omit<AppOptions, 'etag' | 'trustProxy'> & {
  *
  * 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.
+ * `path`) and the `router` injectable. 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 = {
   /**
@@ -1071,113 +1056,12 @@ type AppContext = {
    * 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;
+  router?: IRouter<Handler>;
 };
 interface IApp extends IDispatcher {
   /**
@@ -1189,16 +1073,6 @@ interface IApp extends IDispatcher {
    * 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
@@ -1209,24 +1083,31 @@ interface IApp extends IDispatcher {
    * comparing implementations mid-flight without rebuilding the
    * App.
    */
-  setRouter(router: IRouter<RouteEntry>): void;
+  setRouter(router: IRouter<Handler>): void;
   /**
-   * Check if a plugin with the given name is installed on this router.
+   * Check if a plugin with the given name is installed on this
+   * App. Plugins installed on a mounted child are merged into the
+   * parent at mount time, so this reflects the flattened view.
    */
   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.
+   * Get the version of an installed plugin by name, or `undefined`
+   * if the plugin is not installed.
    */
   getPluginVersion(name: string): string | undefined;
   /**
-   * Register a handler, router, or plugin.
-   * When a path is provided, the item is mounted at that path.
+   * Register a handler, App, or plugin.
+   *
+   * When another App is passed, its routes are snapshotted, the
+   * mount path is prefixed onto each, and the entries are
+   * registered on this App's router. The child's plugin registry
+   * is merged into this one. The child is discarded post-mount —
+   * later mutations on it do **not** propagate.
    */
-  use(router: IApp): this;
+  use(app: IApp): this;
   use(handler: Handler | HandlerOptions): this;
   use(plugin: Plugin): this;
-  use(path: Path, router: IApp): this;
+  use(path: Path, app: IApp): this;
   use(path: Path, handler: Handler | HandlerOptions): this;
   use(path: Path, plugin: Plugin): this;
   /** Register GET handler(s). */
@@ -1250,35 +1131,8 @@ interface IApp extends IDispatcher {
   /** 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;
@@ -1493,7 +1347,6 @@ declare class LinearRouter<T extends ObjectLiteral = ObjectLiteral> implements I
   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
@@ -1510,7 +1363,7 @@ type SmartRouterOptions<T extends ObjectLiteral = ObjectLiteral> = BaseRouterOpt
  * 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.
+ * — `add`, `lookup` — 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
@@ -1534,7 +1387,6 @@ declare class SmartRouter<T extends ObjectLiteral = ObjectLiteral> implements IR
   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
@@ -1716,7 +1568,6 @@ declare class TrieRouter<T extends ObjectLiteral = ObjectLiteral> implements IRo
   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
@@ -1763,7 +1614,7 @@ declare function buildRoutePathMatcher<T extends ObjectLiteral = ObjectLiteral>(
 //#region src/app/module.d.ts
 declare class App implements IApp {
   /**
-   * A label for the router instance.
+   * A label for the App instance.
    */
   readonly name?: string;
   /**
@@ -1781,52 +1632,55 @@ declare class App implements IApp {
    *
    * @protected
    */
-  protected router: IRouter<RouteEntry>;
-  /**
-   * Lifecycle hook registry.
-   *
-   * @protected
-   */
-  protected hooks: IHooks;
+  protected router: IRouter<Handler>;
   /**
    * 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.
+   * Frozen on construction — once published to `event.appOptions`
+   * it is shared across all requests, and a handler must not be
+   * able to mutate router-global state.
    */
   protected _options: Readonly<AppOptions>;
   /**
-   * Registry of installed plugins (name → version) on this router.
+   * Registry of installed plugins (name → version) on this App.
+   *
+   * Read by `use(otherApp)` (via the public `plugins` getter) so
+   * plugin registries merge into the parent at flatten time —
+   * `parent.hasPlugin('foo')` then reflects plugins installed on
+   * apps mounted into it.
    *
    * @protected
    */
-  protected plugins: Map<string, string | undefined>;
+  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
+   * Read by `use(otherApp)` to snapshot routes at flatten time.
+   * Late mutations to `_routes` after a flatten do not propagate.
    */
-  protected _routes: Route<RouteEntry>[];
+  protected _routes: Route<Handler>[];
   constructor(input?: AppContext);
+  /**
+   * Public read of the canonical route list. Used by `use(child)`
+   * to snapshot the child's routes at flatten time. Returned
+   * as `readonly` — callers must not mutate.
+   */
+  get routes(): readonly Route<Handler>[];
+  /**
+   * Public read of the installed-plugin registry. Used by
+   * `use(child)` to merge child plugins into the parent at
+   * flatten time. Returned as `ReadonlyMap` — callers must not
+   * mutate; go through `use(plugin)` to install.
+   */
+  get plugins(): ReadonlyMap<string, string | undefined>;
   /**
    * 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.
+   * App so `setRouter` / `use(child)` can read the canonical list
+   * back.
    *
    * @protected
    */
-  protected register(route: Route<RouteEntry>): void;
+  protected register(route: Route<Handler>): void;
   /**
    * Swap the active router. Replays every previously-registered
    * route onto the new router so lookups stay correct.
@@ -1836,46 +1690,20 @@ declare class App implements IApp {
    * mid-flight without rebuilding the App. Any cache the previous
    * router carried is dropped along with it.
    */
-  setRouter(router: IRouter<RouteEntry>): void;
+  setRouter(router: IRouter<Handler>): 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>;
+  /**
+   * Walk the matched routes for the current event, dispatching each
+   * handler in order. Re-entered (recursively) from the `setNext`
+   * continuation so `event.next()` resumes from the next match.
+   */
+  protected runMatches(event: IDispatcherEvent, matches: readonly RouteMatch<Handler>[], matchesPath: string, startIndex: number): Promise<Response | undefined>;
   delete(...handlers: (Handler | HandlerOptions)[]): this;
   delete(path: Path, ...handlers: (Handler | HandlerOptions)[]): this;
   get(...handlers: (Handler | HandlerOptions)[]): this;
@@ -1891,60 +1719,37 @@ declare class App implements IApp {
   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(app: IApp): this;
   use(handler: Handler | HandlerOptions): this;
   use(plugin: Plugin): this;
-  use(path: Path, router: IApp): this;
+  use(path: Path, app: 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
+   * Snapshot a child App's routes and plugin registry into this
+   * one. Each route's path is prefixed with `this._path`, the
+   * supplied mount `path`, and the route's own path (in that
+   * order); the resulting entry is registered on this App's
+   * router. The child app is not retained — late mutations on it
+   * after this call do not propagate.
    *
-   * 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.
+   * @protected
    */
-  clone(): IApp;
+  protected flatten(child: App, path: Path | undefined): void;
   /**
-   * Add a hook listener.
-   *
-   * @param name
-   * @param fn
-   * @param priority
+   * Check if a plugin with the given name is installed on this App.
    */
-  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;
+  hasPlugin(name: string): boolean;
   /**
-   * Remove single or all hook listeners.
-   *
-   * @param name
+   * Get the version of an installed plugin by name, or `undefined`
+   * if the plugin is not installed.
    */
-  off(name: HookName): this;
-  off(name: HookName, fn: HookListener): this;
+  getPluginVersion(name: string): string | undefined;
+  protected install(plugin: Plugin, context?: PluginInstallContext): 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
+export { AppOptions as $, HandlerType as $t, sendFormat as A, NodeHandler as At, setResponseHeaderAttachment as B, HandlerAfterListener as Bt, getRequestAcceptableContentTypes as C, isWebHandler as Ct, setResponseContentTypeByFileName as D, WebHandlerProvider as Dt, toResponse as E, WebHandler as Et, SendFileStats as F, Handler as Ft, EventStreamHandle as G, PathMatcher as Gt, appendResponseHeader as H, HandlerBeforeListener as Ht, sendFile as I, HandlerOptions as It, EventStreamListener as J, PathMatcherExecResult as Jt, EventStreamOptions as K, IPathMatcher as Kt, sendCreated as L, defineErrorHandler as Lt, SendFileContentOptions as M, defineCoreHandler as Mt, SendFileDisposition as N, CoreHandler as Nt, sendStream as O, fromNodeHandler as Ot, SendFileOptions as P, CoreHandlerOptions as Pt, AppContext as Q, HandlerSymbol as Qt, sendAccepted as R, ErrorHandler as Rt, getRequestAcceptableContentType as S, isHandlerOptions as St, isRequestCacheable as T, fromWebHandler as Tt, appendResponseHeaderDirective as U, HandlerErrorListener as Ut, setResponseHeaderInline as V, HandlerBaseOptions as Vt, serializeEventStreamMessage as W, isPath as Wt, ResponseCacheHeadersOptions as X, isError as Xt, EventStreamMessage as Y, PathMatcherOptions as Yt, setResponseCacheHeaders as Z, createError as Zt, getRequestAcceptableLanguages as _, isPluginError as _t, SmartRouter as a, AppRequest as an, Route as at, getRequestAcceptableCharset as b, matchHandlerMethod as bt, RequestProtocolOptions as c, NextFn as cn, LruCacheOptions as ct, RequestIpOptions as d, MethodNameLike as dn, Plugin as dt, DispatcherEvent as en, AppOptionsInput as et, getRequestIP as f, AppError as fn, PluginInstallContext as ft, getRequestAcceptableLanguage as g, PluginAlreadyInstalledError as gt, matchRequestContentType as h, PluginInstallError as ht, TrieRouter as i, AppEventCreateContext as in, ObjectLiteral as it, SendFileContent as j, NodeMiddleware as jt, sendRedirect as k, fromNodeMiddleware as kt, getRequestProtocol as l, HeaderName as ln, ICache as lt, getRequestHostName as m, HTTPErrorInput$1 as mn, PluginNotInstalledError as mt, App as n, IDispatcherEvent as nn, BaseRouterOptions as nt, SmartRouterOptions as o, AppResponse as on, RouteMatch as ot, RequestHostNameOptions as p, ErrorSymbol as pn, PluginInstallFn as pt, createEventStream as q, Path as qt, buildRoutePathMatcher as r, AppEvent as rn, IRouter as rt, LinearRouter as s, IAppEvent as sn, LruCache as st, normalizeAppOptions as t, IDispatcher as tn, IApp as tt, useRequestNegotiator as u, MethodName as un, isPlugin as ut, getRequestAcceptableEncoding as v, PluginError as vt, getRequestHeader as w, isWebHandlerProvider as wt, getRequestAcceptableCharsets as x, isHandler as xt, getRequestAcceptableEncodings as y, PluginErrorCode as yt, setResponseHeaderContentType as z, ErrorHandlerOptions as zt };
+//# sourceMappingURL=index-6qjxyFZh.d.mts.map