@nextrush/router 3.0.7 → 4.0.0-beta.1

package/dist/index.js

@@ -2,9 +2,9 @@ var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 
 // src/router.ts
-import { HTTP_METHODS } from "@nextrush/types";
+import { HTTP_METHODS as HTTP_METHODS3 } from "@nextrush/types";
 
-// src/radix-tree.ts
+// src/segment-trie.ts
 var NodeType = /* @__PURE__ */ (function(NodeType2) {
   NodeType2[NodeType2["STATIC"] = 0] = "STATIC";
   NodeType2[NodeType2["PARAM"] = 1] = "PARAM";
@@ -16,43 +16,41 @@ var NOOP_NEXT = /* @__PURE__ */ __name(() => RESOLVED_PROMISE, "NOOP_NEXT");
 function compileExecutor(handler, middleware) {
   const len = middleware.length;
   if (len === 0) {
-    return async (ctx) => {
-      await handler(ctx, NOOP_NEXT);
-    };
-  }
-  if (len === 1) {
-    const mw = middleware[0];
-    if (mw === void 0) throw new Error("middleware length mismatch");
-    return async (ctx) => {
-      await mw(ctx, async () => {
-        await handler(ctx, NOOP_NEXT);
-      });
-    };
-  }
-  if (len === 2) {
-    const mw0 = middleware[0];
-    const mw1 = middleware[1];
-    if (mw0 === void 0 || mw1 === void 0) throw new Error("middleware length mismatch");
-    return async (ctx) => {
-      await mw0(ctx, async () => {
-        await mw1(ctx, async () => {
-          await handler(ctx, NOOP_NEXT);
-        });
-      });
+    return (ctx) => {
+      if (ctx.setNext) ctx.setNext(NOOP_NEXT);
+      try {
+        return Promise.resolve(handler(ctx, NOOP_NEXT));
+      } catch (err) {
+        return Promise.reject(err instanceof Error ? err : new Error(String(err)));
+      }
     };
   }
-  return async (ctx) => {
-    let index = 0;
-    const dispatch = /* @__PURE__ */ __name(async () => {
-      if (index < len) {
-        const mw = middleware[index++];
-        if (mw === void 0) throw new Error("middleware length mismatch");
-        await mw(ctx, dispatch);
-      } else {
-        await handler(ctx, NOOP_NEXT);
+  return (ctx) => {
+    let index = -1;
+    const dispatch = /* @__PURE__ */ __name((i) => {
+      if (i <= index) {
+        return Promise.reject(new Error("next() called multiple times"));
+      }
+      index = i;
+      if (i < len) {
+        const mw = middleware[i];
+        if (mw === void 0) return Promise.reject(new Error("middleware length mismatch"));
+        const next = /* @__PURE__ */ __name(() => dispatch(i + 1), "next");
+        if (ctx.setNext) ctx.setNext(next);
+        try {
+          return Promise.resolve(mw(ctx, next));
+        } catch (err) {
+          return Promise.reject(err instanceof Error ? err : new Error(String(err)));
+        }
+      }
+      if (ctx.setNext) ctx.setNext(NOOP_NEXT);
+      try {
+        return Promise.resolve(handler(ctx, NOOP_NEXT));
+      } catch (err) {
+        return Promise.reject(err instanceof Error ? err : new Error(String(err)));
       }
     }, "dispatch");
-    await dispatch();
+    return dispatch(0);
   };
 }
 __name(compileExecutor, "compileExecutor");
@@ -65,6 +63,13 @@ function createNode(segment, type = 0) {
   };
 }
 __name(createNode, "createNode");
+function clearNode(node) {
+  node.children.clear();
+  node.handlers.clear();
+  node.paramChild = void 0;
+  node.wildcardChild = void 0;
+}
+__name(clearNode, "clearNode");
 function parseSegments(path, caseSensitive = true) {
   const normalized = path.startsWith("/") ? path.slice(1) : path;
   if (normalized === "") return [];
@@ -95,749 +100,1159 @@ function parseSegments(path, caseSensitive = true) {
 }
 __name(parseSegments, "parseSegments");
 
-// src/router.ts
-var EMPTY_PARAMS = Object.freeze(/* @__PURE__ */ Object.create(null));
-var Router = class _Router {
-  static {
-    __name(this, "Router");
-  }
-  root;
-  opts;
-  routerMiddleware = [];
-  /**
-  * Static route hash map for O(1) lookup.
-  * Key: "METHOD path" (e.g. "GET /users"), Value: HandlerEntry
-  */
-  staticRoutes = /* @__PURE__ */ new Map();
-  /** Whether any routes have params or wildcards (disables static-only fast path) */
-  hasParamRoutes = false;
-  constructor(options = {}) {
-    this.root = createNode("");
-    this.opts = {
-      prefix: options.prefix ?? "",
-      caseSensitive: options.caseSensitive ?? false,
-      strict: options.strict ?? false
-    };
-  }
-  /**
-  * Normalize path based on router options
-  */
-  normalizePath(path) {
-    let prefix = this.opts.prefix;
-    if (prefix.endsWith("/") && path.startsWith("/")) {
-      prefix = prefix.slice(0, -1);
-    }
-    let normalized = prefix + path;
-    if (normalized.includes("//")) {
-      normalized = normalized.replace(/\/+/g, "/");
+// src/group-router.ts
+import { HTTP_METHODS } from "@nextrush/types";
+
+// src/redirect.ts
+function compileRedirectTarget(to) {
+  const parts = [];
+  let pos = 0;
+  let found = false;
+  while (pos < to.length) {
+    let idx = -1;
+    for (let i = pos; i < to.length; i++) {
+      if (to[i] === ":" && (i === 0 || to[i - 1] === "/") && i + 1 < to.length && to[i + 1] !== "/") {
+        idx = i;
+        break;
+      }
     }
-    if (!this.opts.strict && normalized.length > 1 && normalized.endsWith("/")) {
-      normalized = normalized.slice(0, -1);
+    if (idx === -1) break;
+    found = true;
+    parts.push(to.slice(pos, idx));
+    const end = to.indexOf("/", idx + 1);
+    if (end === -1) {
+      parts.push(to.slice(idx + 1));
+      pos = to.length;
+    } else {
+      parts.push(to.slice(idx + 1, end));
+      pos = end;
     }
-    return normalized.startsWith("/") ? normalized : "/" + normalized;
   }
-  /**
-  * Add a route to the radix tree
-  */
-  addRoute(method, path, handlers, middleware = []) {
-    const normalized = this.normalizePath(path);
-    const segments = parseSegments(normalized, this.opts.caseSensitive);
-    let node = this.root;
-    for (const seg of segments) {
-      if (seg.type === NodeType.PARAM) {
-        if (!node.paramChild) {
-          node.paramChild = createNode(seg.segment, NodeType.PARAM);
-          node.paramChild.paramName = seg.paramName;
-        } else if (node.paramChild.paramName !== seg.paramName) {
-          if (typeof process !== "undefined" && process.env.NODE_ENV !== "production") {
-            const existing = node.paramChild.paramName;
-            console.warn(`[nextrush:router] Route param name conflict at "${normalized}": ":${String(seg.paramName)}" conflicts with existing ":${String(existing)}". The existing name ":${String(existing)}" will be used.`);
-          }
-        }
-        node = node.paramChild;
-      } else if (seg.type === NodeType.WILDCARD) {
-        node.wildcardChild ??= createNode("*", NodeType.WILDCARD);
-        node = node.wildcardChild;
-        break;
+  if (found) {
+    parts.push(to.slice(pos));
+    return parts;
+  }
+  return void 0;
+}
+__name(compileRedirectTarget, "compileRedirectTarget");
+function createRedirectHandler(to, status) {
+  const compiledParts = compileRedirectTarget(to);
+  return (ctx) => {
+    let targetPath;
+    if (compiledParts) {
+      const params = ctx.params;
+      const head = compiledParts[0];
+      if (head === void 0) {
+        targetPath = to;
       } else {
-        const key = seg.segment;
-        let child = node.children.get(key);
-        if (!child) {
-          child = createNode(seg.segment, NodeType.STATIC);
-          node.children.set(key, child);
+        let result = head;
+        for (let i = 1; i < compiledParts.length - 1; i += 2) {
+          const paramKey = compiledParts[i];
+          const tail = compiledParts[i + 1];
+          if (paramKey === void 0 || tail === void 0) break;
+          result += (params[paramKey] ?? "") + tail;
         }
-        node = child;
+        targetPath = result;
       }
-    }
-    const combinedMiddleware = [
-      ...middleware
-    ];
-    const finalHandler = handlers[handlers.length - 1];
-    if (!finalHandler) {
-      throw new Error("At least one handler is required");
-    }
-    const inlineMiddleware = handlers.slice(0, -1);
-    for (const mw of inlineMiddleware) {
-      combinedMiddleware.push(mw);
-    }
-    const executor = compileExecutor(finalHandler, combinedMiddleware);
-    const entry = {
-      handler: finalHandler,
-      middleware: combinedMiddleware,
-      executor
-    };
-    if (node.handlers.has(method)) {
-      throw new Error(`Route conflict: ${method} ${normalized} is already registered. Remove the duplicate or use a different path.`);
-    }
-    node.handlers.set(method, entry);
-    const hasParams = segments.some((s) => s.type === NodeType.PARAM || s.type === NodeType.WILDCARD);
-    if (hasParams) {
-      this.hasParamRoutes = true;
     } else {
-      const normalizedKey = this.opts.caseSensitive ? normalized : normalized.toLowerCase();
-      this.staticRoutes.set(`${method} ${normalizedKey}`, entry);
+      targetPath = to;
+    }
+    ctx.status = status;
+    ctx.set("Location", targetPath);
+    ctx.body = "";
+  };
+}
+__name(createRedirectHandler, "createRedirectHandler");
+
+// src/group-router.ts
+var GroupRouter = class {
+  static {
+    __name(this, "GroupRouter");
+  }
+  parent;
+  prefix;
+  middleware;
+  constructor(parent, prefix, middleware) {
+    this.parent = parent;
+    this.prefix = prefix;
+    this.middleware = middleware;
+  }
+  fullPath(path) {
+    if (path === "/" || path === "") {
+      return this.prefix;
     }
+    const cleanPrefix = this.prefix.endsWith("/") ? this.prefix.slice(0, -1) : this.prefix;
+    const cleanPath = path.startsWith("/") ? path : "/" + path;
+    return cleanPrefix + cleanPath;
   }
-  // ===========================================================================
-  // HTTP Method Shortcuts
-  // ===========================================================================
   get(path, ...handlers) {
-    this.addRoute("GET", path, handlers);
+    this.parent._addGroupRoute("GET", this.fullPath(path), handlers, this.middleware);
     return this;
   }
   post(path, ...handlers) {
-    this.addRoute("POST", path, handlers);
+    this.parent._addGroupRoute("POST", this.fullPath(path), handlers, this.middleware);
     return this;
   }
   put(path, ...handlers) {
-    this.addRoute("PUT", path, handlers);
+    this.parent._addGroupRoute("PUT", this.fullPath(path), handlers, this.middleware);
     return this;
   }
   delete(path, ...handlers) {
-    this.addRoute("DELETE", path, handlers);
+    this.parent._addGroupRoute("DELETE", this.fullPath(path), handlers, this.middleware);
     return this;
   }
   patch(path, ...handlers) {
-    this.addRoute("PATCH", path, handlers);
+    this.parent._addGroupRoute("PATCH", this.fullPath(path), handlers, this.middleware);
     return this;
   }
   head(path, ...handlers) {
-    this.addRoute("HEAD", path, handlers);
+    this.parent._addGroupRoute("HEAD", this.fullPath(path), handlers, this.middleware);
     return this;
   }
   options(path, ...handlers) {
-    this.addRoute("OPTIONS", path, handlers);
+    this.parent._addGroupRoute("OPTIONS", this.fullPath(path), handlers, this.middleware);
     return this;
   }
+  /**
+  * Register a route matching every HTTP method under a single introspection
+  * entry, mirroring `Router.all()` (T016) — a group's `.all()` must not
+  * regress to the pre-T016 one-row-per-method shape just because
+  * registration is routed through `_addGroupRoute` instead of `addRoute`
+  * directly.
+  */
   all(path, ...handlers) {
     for (const method of HTTP_METHODS) {
-      this.addRoute(method, path, handlers);
+      this.parent._addGroupRoute(method, this.fullPath(path), handlers, this.middleware, false);
     }
+    this.parent._pushAnyMethodRouteDefinition(this.fullPath(path));
     return this;
   }
-  route(method, path, ...handlers) {
-    this.addRoute(method, path, handlers);
+  /**
+  * Register a redirect within the group (uses the shared redirect handler,
+  * audit RT-4 — no more naive replaceAll param substitution).
+  */
+  redirect(from, to, status = 301) {
+    const redirectHandler = createRedirectHandler(to, status);
+    this.parent._addGroupRoute("GET", this.fullPath(from), [
+      redirectHandler
+    ], this.middleware);
+    this.parent._addGroupRoute("HEAD", this.fullPath(from), [
+      redirectHandler
+    ], this.middleware);
     return this;
   }
   /**
-  * Register a redirect route from one path to another
-  *
-  * @param from - Source path to redirect from
-  * @param to - Target path or URL to redirect to
-  * @param status - HTTP status code (default: 301 permanent redirect)
-  * @returns this for chaining
-  *
-  * @example
-  * ```typescript
-  * // Permanent redirect (301)
-  * router.redirect('/old-page', '/new-page');
-  *
-  * // Temporary redirect (302)
-  * router.redirect('/temp', '/destination', 302);
-  *
-  * // Redirect to external URL
-  * router.redirect('/docs', 'https://docs.example.com');
-  *
-  * // With parameters - redirects /users/:id to /profiles/:id
-  * router.redirect('/users/:id', '/profiles/:id');
-  * ```
+  * Nested group support — combines this group's prefix + middleware with the
+  * nested group's.
   */
-  redirect(from, to, status = 301) {
-    let compiledParts;
-    {
-      const parts = [];
-      let pos = 0;
-      let found = false;
-      while (pos < to.length) {
-        let idx = -1;
-        for (let i = pos; i < to.length; i++) {
-          if (to[i] === ":" && (i === 0 || to[i - 1] === "/") && i + 1 < to.length && to[i + 1] !== "/") {
-            idx = i;
-            break;
-          }
-        }
-        if (idx === -1) break;
-        found = true;
-        parts.push(to.slice(pos, idx));
-        const end = to.indexOf("/", idx + 1);
-        if (end === -1) {
-          parts.push(to.slice(idx + 1));
-          pos = to.length;
-        } else {
-          parts.push(to.slice(idx + 1, end));
-          pos = end;
-        }
+  group(prefix, middlewareOrCallback, callback) {
+    runRouteGroup(this.parent, this.fullPath(prefix), middlewareOrCallback, callback, this.middleware);
+    return this;
+  }
+};
+function runRouteGroup(host, prefix, middlewareOrCallback, callback, inheritedMiddleware = []) {
+  let middleware = [];
+  let cb;
+  if (Array.isArray(middlewareOrCallback)) {
+    middleware = middlewareOrCallback;
+    if (!callback) {
+      throw new Error("Callback function is required when providing middleware array");
+    }
+    cb = callback;
+  } else {
+    cb = middlewareOrCallback;
+  }
+  const combined = inheritedMiddleware.length > 0 ? [
+    ...inheritedMiddleware,
+    ...middleware
+  ] : middleware;
+  cb(new GroupRouter(host, prefix, combined));
+}
+__name(runRouteGroup, "runRouteGroup");
+
+// src/constants.ts
+var NULL_PROTO = /* @__PURE__ */ Object.create(null);
+var EMPTY_PARAMS = Object.freeze(Object.create(NULL_PROTO));
+
+// src/walk-pool.ts
+function createWalkPool(maxDepth) {
+  const frames = [];
+  for (let i = 0; i < maxDepth + 1; i++) {
+    frames.push({
+      node: void 0,
+      pos: 0,
+      stage: 0,
+      seg: "",
+      next: 0,
+      bound: false
+    });
+  }
+  return {
+    frames,
+    bindNames: [],
+    bindValues: []
+  };
+}
+__name(createWalkPool, "createWalkPool");
+function matchNodeIndexedPooled(root, path, startPos, bindNames, bindValues, method, decode, pool, originalPath) {
+  const { frames } = pool;
+  let depth = 0;
+  const first = frames[0];
+  if (first === void 0) return null;
+  first.node = root;
+  first.pos = startPos;
+  first.stage = 0;
+  first.seg = "";
+  first.next = 0;
+  first.bound = false;
+  while (depth >= 0) {
+    const frame = frames[depth];
+    if (frame === void 0) break;
+    if (frame.stage === 0) {
+      if (frame.pos >= path.length) {
+        const handler = frame.node.handlers.get(method);
+        if (handler) return handler;
+        depth--;
+        continue;
+      }
+      const slashPos = path.indexOf("/", frame.pos);
+      if (slashPos === -1) {
+        frame.seg = path.slice(frame.pos);
+        frame.next = path.length;
+      } else {
+        frame.seg = path.slice(frame.pos, slashPos);
+        frame.next = slashPos + 1;
+      }
+      if (frame.seg === "") {
+        const handler = frame.node.handlers.get(method);
+        if (handler) return handler;
+        depth--;
+        continue;
       }
-      if (found) {
-        parts.push(to.slice(pos));
-        compiledParts = parts;
+      frame.stage = 1;
+      const staticChild = frame.node.children.get(frame.seg);
+      if (staticChild) {
+        depth++;
+        const next = frames[depth];
+        if (next === void 0) {
+          depth--;
+          continue;
+        }
+        next.node = staticChild;
+        next.pos = frame.next;
+        next.stage = 0;
+        next.seg = "";
+        next.next = 0;
+        next.bound = false;
       }
+      continue;
     }
-    const redirectHandler = /* @__PURE__ */ __name((ctx) => {
-      let targetPath;
-      if (compiledParts) {
-        const params = ctx.params;
-        const parts = compiledParts;
-        const head = parts[0];
-        if (head === void 0) {
-          targetPath = to;
-        } else {
-          let result = head;
-          for (let i = 1; i < parts.length - 1; i += 2) {
-            const paramKey = parts[i];
-            const tail = parts[i + 1];
-            if (paramKey === void 0 || tail === void 0) break;
-            result += (params[paramKey] ?? "") + tail;
-          }
-          targetPath = result;
+    if (frame.stage === 1) {
+      frame.stage = 2;
+      const paramChild = frame.node.paramChild;
+      if (paramChild) {
+        const paramName = paramChild.paramName;
+        if (paramName === void 0) return null;
+        const value = originalPath !== void 0 ? decodeParam(segmentAt(originalPath, frame.pos), decode) : decodeParam(frame.seg, decode);
+        bindNames.push(paramName);
+        bindValues.push(value);
+        frame.bound = true;
+        depth++;
+        const next = frames[depth];
+        if (next === void 0) {
+          bindNames.pop();
+          bindValues.pop();
+          frame.bound = false;
+          depth--;
+          continue;
         }
-      } else {
-        targetPath = to;
+        next.node = paramChild;
+        next.pos = frame.next;
+        next.stage = 0;
+        next.seg = "";
+        next.next = 0;
+        next.bound = false;
       }
-      ctx.status = status;
-      ctx.set("Location", targetPath);
-      ctx.body = "";
-    }, "redirectHandler");
-    this.addRoute("GET", from, [
-      redirectHandler
-    ]);
-    this.addRoute("HEAD", from, [
-      redirectHandler
-    ]);
-    if (status === 307 || status === 308) {
-      this.addRoute("POST", from, [
-        redirectHandler
-      ]);
-      this.addRoute("PUT", from, [
-        redirectHandler
-      ]);
-      this.addRoute("PATCH", from, [
-        redirectHandler
-      ]);
-      this.addRoute("DELETE", from, [
-        redirectHandler
-      ]);
+      continue;
     }
-    return this;
-  }
-  // ===========================================================================
-  // Router Composition
-  // ===========================================================================
-  use(pathOrMiddleware, routerOrUndefined) {
-    if (typeof pathOrMiddleware === "function") {
-      this.routerMiddleware.push(pathOrMiddleware);
-    } else if (typeof pathOrMiddleware === "string" && routerOrUndefined instanceof _Router) {
-      this.mountRouter(pathOrMiddleware, routerOrUndefined);
-    } else if (typeof pathOrMiddleware === "string") {
-      throw new Error(`router.use('${pathOrMiddleware}', ...) requires a Router instance as the second argument. Use router.group(prefix, callback) for prefix-scoped middleware, or router.use(middlewareFn) to register middleware without a prefix.`);
-    } else if (pathOrMiddleware instanceof _Router) {
-      this.mountRouter("", pathOrMiddleware);
+    if (frame.bound) {
+      bindNames.pop();
+      bindValues.pop();
+      frame.bound = false;
     }
-    return this;
+    const wildcardChild = frame.node.wildcardChild;
+    if (wildcardChild) {
+      const src = originalPath ?? path;
+      bindNames.push("*");
+      bindValues.push(decodeParam(src.slice(frame.pos), decode));
+      const handler = wildcardChild.handlers.get(method);
+      if (handler) return handler;
+      bindNames.pop();
+      bindValues.pop();
+    }
+    depth--;
   }
-  /**
-  * Mount a sub-router at a path prefix (Hono-style)
-  *
-  * This is the explicit API for mounting sub-routers.
-  * Equivalent to `router.use(path, subRouter)` but more semantic.
-  *
-  * @param path - Path prefix for the sub-router
-  * @param router - Router instance to mount
-  * @returns this for chaining
-  *
-  * @example
-  * ```typescript
-  * // Create modular routers
-  * const users = createRouter();
-  * users.get('/', listUsers);
-  * users.get('/:id', getUser);
-  *
-  * const posts = createRouter();
-  * posts.get('/', listPosts);
-  *
-  * // Mount sub-routers
-  * const api = createRouter();
-  * api.mount('/users', users);
-  * api.mount('/posts', posts);
-  *
-  * // Or use on main router
-  * const router = createRouter();
-  * router.mount('/api', api);
-  *
-  * app.use(router.routes());
-  * ```
-  */
-  mount(path, router) {
-    this.mountRouter(path, router);
-    return this;
+  return null;
+}
+__name(matchNodeIndexedPooled, "matchNodeIndexedPooled");
+
+// src/matching.ts
+function decodeParam(value, decode) {
+  if (!decode || !value.includes("%")) return value;
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
   }
-  /**
-  * Mount a sub-router (internal)
-  *
-  * Carries the sub-router's own `routerMiddleware` forward so that
-  * `subrouter.use(mw)` middleware applies to every copied route.
-  */
-  mountRouter(prefix, router) {
-    this.copyRoutes(router.root, prefix, [], router.routerMiddleware);
+}
+__name(decodeParam, "decodeParam");
+function segmentAt(path, start) {
+  const slashPos = path.indexOf("/", start);
+  return slashPos === -1 ? path.slice(start) : path.slice(start, slashPos);
+}
+__name(segmentAt, "segmentAt");
+function isProvablyLowerAscii(path) {
+  for (let i = 0; i < path.length; i++) {
+    const c = path.charCodeAt(i);
+    if (c >= 65 && c <= 90 || c > 127) return false;
   }
-  /**
-  * Recursively copy routes from another router
-  */
-  copyRoutes(node, prefix, segments, subRouterMiddleware) {
-    for (const [method, entry] of node.handlers) {
-      const path = prefix + "/" + segments.join("/");
-      const combined = subRouterMiddleware.length > 0 ? [
-        ...subRouterMiddleware,
-        ...entry.middleware
-      ] : entry.middleware;
-      this.addRoute(method, path || "/", [
-        entry.handler
-      ], combined);
+  return true;
+}
+__name(isProvablyLowerAscii, "isProvablyLowerAscii");
+function collapseAndStrip(path, strict) {
+  let normalized = path;
+  if (normalized.includes("//")) {
+    normalized = normalized.replace(/\/+/g, "/");
+  }
+  if (!strict && normalized.length > 1 && normalized.endsWith("/")) {
+    normalized = normalized.slice(0, -1);
+  }
+  return normalized;
+}
+__name(collapseAndStrip, "collapseAndStrip");
+function normalizePathForMatch(path, caseSensitive, strict) {
+  const folded = caseSensitive || isProvablyLowerAscii(path) ? path : path.toLowerCase();
+  return collapseAndStrip(folded, strict);
+}
+__name(normalizePathForMatch, "normalizePathForMatch");
+function matchNodeIndexed(root, path, startPos, bindNames, bindValues, method, decode, originalPath, pool) {
+  if (pool) {
+    return matchNodeIndexedPooled(root, path, startPos, bindNames, bindValues, method, decode, pool, originalPath);
+  }
+  const stack = [
+    {
+      node: root,
+      pos: startPos,
+      stage: 0,
+      seg: "",
+      next: 0,
+      bound: false
     }
-    for (const [, child] of node.children) {
-      this.copyRoutes(child, prefix, [
-        ...segments,
-        child.segment
-      ], subRouterMiddleware);
-    }
-    if (node.paramChild) {
-      this.copyRoutes(node.paramChild, prefix, [
-        ...segments,
-        node.paramChild.segment
-      ], subRouterMiddleware);
-    }
-    if (node.wildcardChild) {
-      this.copyRoutes(node.wildcardChild, prefix, [
-        ...segments,
-        "*"
-      ], subRouterMiddleware);
-    }
-  }
-  // ===========================================================================
-  // Route Matching
-  // ===========================================================================
-  /**
-  * Match a route and return handler + params
-  */
-  match(method, path) {
-    const isCaseInsensitive = !this.opts.caseSensitive;
-    let normalized = isCaseInsensitive ? path.toLowerCase() : path;
-    if (normalized.includes("//")) {
-      normalized = normalized.replace(/\/+/g, "/");
+  ];
+  while (stack.length > 0) {
+    const frame = stack[stack.length - 1];
+    if (frame === void 0) break;
+    if (frame.stage === 0) {
+      if (frame.pos >= path.length) {
+        const handler = frame.node.handlers.get(method);
+        if (handler) return handler;
+        stack.pop();
+        continue;
+      }
+      const slashPos = path.indexOf("/", frame.pos);
+      if (slashPos === -1) {
+        frame.seg = path.slice(frame.pos);
+        frame.next = path.length;
+      } else {
+        frame.seg = path.slice(frame.pos, slashPos);
+        frame.next = slashPos + 1;
+      }
+      if (frame.seg === "") {
+        const handler = frame.node.handlers.get(method);
+        if (handler) return handler;
+        stack.pop();
+        continue;
+      }
+      frame.stage = 1;
+      const staticChild = frame.node.children.get(frame.seg);
+      if (staticChild) {
+        stack.push({
+          node: staticChild,
+          pos: frame.next,
+          stage: 0,
+          seg: "",
+          next: 0,
+          bound: false
+        });
+      }
+      continue;
     }
-    if (!this.opts.strict && normalized.length > 1 && normalized.endsWith("/")) {
-      normalized = normalized.slice(0, -1);
+    if (frame.stage === 1) {
+      frame.stage = 2;
+      const paramChild = frame.node.paramChild;
+      if (paramChild) {
+        const paramName = paramChild.paramName;
+        if (paramName === void 0) return null;
+        const value = originalPath !== void 0 ? decodeParam(segmentAt(originalPath, frame.pos), decode) : decodeParam(frame.seg, decode);
+        bindNames.push(paramName);
+        bindValues.push(value);
+        frame.bound = true;
+        stack.push({
+          node: paramChild,
+          pos: frame.next,
+          stage: 0,
+          seg: "",
+          next: 0,
+          bound: false
+        });
+      }
+      continue;
+    }
+    if (frame.bound) {
+      bindNames.pop();
+      bindValues.pop();
+      frame.bound = false;
+    }
+    const wildcardChild = frame.node.wildcardChild;
+    if (wildcardChild) {
+      const src = originalPath ?? path;
+      bindNames.push("*");
+      bindValues.push(decodeParam(src.slice(frame.pos), decode));
+      const handler = wildcardChild.handlers.get(method);
+      if (handler) return handler;
+      bindNames.pop();
+      bindValues.pop();
     }
-    const staticKey = normalized.length > 1 && normalized.endsWith("/") ? `${method} ${normalized.slice(0, -1)}` : `${method} ${normalized}`;
-    const staticEntry = this.staticRoutes.get(staticKey);
+    stack.pop();
+  }
+  return null;
+}
+__name(matchNodeIndexed, "matchNodeIndexed");
+
+// src/match-route.ts
+function matchRoute(method, rawPath, root, staticRoutes, hasParamRoutes, caseSensitive, strict, decode, routerMiddleware, preNormalized = false, walkPool) {
+  let path = rawPath;
+  if (!preNormalized) {
+    const queryIdx = path.indexOf("?");
+    if (queryIdx !== -1) path = path.slice(0, queryIdx);
+  }
+  let normalized;
+  let caseStable;
+  if (preNormalized) {
+    normalized = path;
+    caseStable = true;
+  } else {
+    caseStable = caseSensitive || isProvablyLowerAscii(path);
+    const folded = caseStable ? path : path.toLowerCase();
+    normalized = collapseAndStrip(folded, strict);
+  }
+  const methodMap = staticRoutes.get(method);
+  if (methodMap) {
+    const staticKey = normalized.length > 1 && normalized.endsWith("/") ? normalized.slice(0, -1) : normalized;
+    const staticEntry = methodMap.get(staticKey);
     if (staticEntry) {
       return {
         handler: staticEntry.handler,
         params: EMPTY_PARAMS,
-        middleware: this.routerMiddleware,
+        middleware: routerMiddleware,
         executor: staticEntry.executor
       };
     }
-    if (!this.hasParamRoutes) return null;
-    const params = {};
-    let originalPath;
-    if (isCaseInsensitive) {
-      originalPath = path;
-      if (originalPath.includes("//")) {
-        originalPath = originalPath.replace(/\/+/g, "/");
-      }
-      if (!this.opts.strict && originalPath.length > 1 && originalPath.endsWith("/")) {
-        originalPath = originalPath.slice(0, -1);
-      }
-    }
-    const result = this.matchNodeIndexed(this.root, normalized, 1, params, method, originalPath);
-    if (!result) return null;
-    let hasParams = false;
-    for (const key of Object.keys(params)) {
-      if (params[key] === void 0) {
-        Reflect.deleteProperty(params, key);
-      } else {
-        hasParams = true;
-      }
-    }
-    return {
-      handler: result.handler,
-      params: hasParams ? params : EMPTY_PARAMS,
-      middleware: this.routerMiddleware,
-      executor: result.executor
-    };
   }
-  /**
-  * Extract the next segment from path at given position without allocating arrays.
-  * Returns [segment, nextIndex] where nextIndex is position after the trailing '/'.
-  */
-  extractSegment(path, start) {
-    const slashPos = path.indexOf("/", start);
-    if (slashPos === -1) {
-      return [
-        path.slice(start),
-        path.length
-      ];
-    }
-    return [
-      path.slice(start, slashPos),
-      slashPos + 1
-    ];
+  if (!hasParamRoutes) return null;
+  const originalPath = caseStable ? void 0 : collapseAndStrip(path, strict);
+  const bindNames = walkPool ? walkPool.bindNames : [];
+  const bindValues = walkPool ? walkPool.bindValues : [];
+  if (walkPool) {
+    bindNames.length = 0;
+    bindValues.length = 0;
   }
-  /**
-  * Index-based recursive node matching (avoids array allocation)
-  */
-  matchNodeIndexed(node, path, pos, params, method, originalPath) {
-    if (pos >= path.length) {
-      return node.handlers.get(method) ?? null;
-    }
-    const [segment, nextPos] = this.extractSegment(path, pos);
-    if (segment === "") return node.handlers.get(method) ?? null;
-    const staticChild = node.children.get(segment);
-    if (staticChild) {
-      const result = this.matchNodeIndexed(staticChild, path, nextPos, params, method, originalPath);
-      if (result) return result;
-    }
-    if (node.paramChild) {
-      const paramName = node.paramChild.paramName;
-      if (paramName === void 0) return null;
-      if (originalPath) {
-        const [origSeg] = this.extractSegment(originalPath, pos);
-        params[paramName] = origSeg;
-      } else {
-        params[paramName] = segment;
-      }
-      const result = this.matchNodeIndexed(node.paramChild, path, nextPos, params, method, originalPath);
-      if (result) return result;
-      Reflect.deleteProperty(params, paramName);
-    }
-    if (node.wildcardChild) {
-      const src = originalPath ?? path;
-      params["*"] = src.slice(pos);
-      return node.wildcardChild.handlers.get(method) ?? null;
+  const entry = matchNodeIndexed(root, normalized, 1, bindNames, bindValues, method, decode, originalPath, walkPool);
+  if (!entry) return null;
+  const count = bindNames.length;
+  let params;
+  if (count === 0) {
+    params = EMPTY_PARAMS;
+  } else {
+    params = Object.create(NULL_PROTO);
+    for (let i = 0; i < count; i++) {
+      const name = bindNames[i];
+      const value = bindValues[i];
+      if (name !== void 0 && value !== void 0) params[name] = value;
     }
-    return null;
   }
-  // ===========================================================================
-  // Middleware Generation
-  // ===========================================================================
-  /**
-  * Get routes middleware function
-  * Mount this on the application
-  *
-  * @example
-  * ```typescript
-  * app.use(router.routes());
-  * ```
-  */
-  routes() {
-    const hasRouterMiddleware = this.routerMiddleware.length > 0;
-    if (hasRouterMiddleware) {
-      this.sealRouterMiddleware();
-    }
-    return async (ctx, next) => {
-      const match = this.match(ctx.method, ctx.path);
-      if (!match) {
-        ctx.status = 404;
-        if (next) await next();
-        return;
-      }
-      ctx.params = match.params;
-      if (match.executor) {
-        await match.executor(ctx);
-        return;
-      }
-      await match.handler(ctx, NOOP_NEXT);
-    };
+  return {
+    handler: entry.handler,
+    params,
+    middleware: routerMiddleware,
+    executor: entry.executor
+  };
+}
+__name(matchRoute, "matchRoute");
+function resolveMatch(state, hasParamRoutes, method, path, preNormalized = false) {
+  return matchRoute(method, path, state.root, state.staticRoutes, hasParamRoutes, state.caseSensitive, state.strict, state.decode, state.routerMiddleware, preNormalized, state.walkPool);
+}
+__name(resolveMatch, "resolveMatch");
+
+// src/composition.ts
+function copyRoutes(node, prefix, segments, subRouterMiddleware, addRoute2) {
+  for (const [method, entry] of node.handlers) {
+    if (entry.autoHead) continue;
+    const path = prefix + "/" + segments.join("/");
+    const combined = subRouterMiddleware.length > 0 ? [
+      ...subRouterMiddleware,
+      ...entry.middleware
+    ] : entry.middleware;
+    addRoute2(method, path || "/", [
+      entry.handler
+    ], combined);
   }
-  /**
-  * Re-compile all route executors to include router-level middleware.
-  * Called once when routes() is invoked, not per-request.
-  */
-  sealRouterMiddleware() {
-    const routerMw = [
-      ...this.routerMiddleware
-    ];
-    const walk = /* @__PURE__ */ __name((node) => {
-      for (const [method, entry] of node.handlers) {
-        const combinedMw = [
-          ...routerMw,
-          ...entry.middleware
-        ];
-        entry.executor = compileExecutor(entry.handler, combinedMw);
-        node.handlers.set(method, entry);
-      }
-      for (const [, child] of node.children) {
-        walk(child);
-      }
-      if (node.paramChild) walk(node.paramChild);
-      if (node.wildcardChild) walk(node.wildcardChild);
-    }, "walk");
-    walk(this.root);
-    for (const [key, entry] of this.staticRoutes) {
+  for (const [, child] of node.children) {
+    copyRoutes(child, prefix, [
+      ...segments,
+      child.segment
+    ], subRouterMiddleware, addRoute2);
+  }
+  if (node.paramChild) {
+    copyRoutes(node.paramChild, prefix, [
+      ...segments,
+      node.paramChild.segment
+    ], subRouterMiddleware, addRoute2);
+  }
+  if (node.wildcardChild) {
+    copyRoutes(node.wildcardChild, prefix, [
+      ...segments,
+      "*"
+    ], subRouterMiddleware, addRoute2);
+  }
+}
+__name(copyRoutes, "copyRoutes");
+
+// src/middleware-adapter.ts
+function sealRouterMiddleware(root, staticRoutes, routerMiddleware) {
+  const routerMw = [
+    ...routerMiddleware
+  ];
+  const walk = /* @__PURE__ */ __name((node) => {
+    for (const [method, entry] of node.handlers) {
       const combinedMw = [
         ...routerMw,
         ...entry.middleware
       ];
       entry.executor = compileExecutor(entry.handler, combinedMw);
-      this.staticRoutes.set(key, entry);
+      node.handlers.set(method, entry);
+    }
+    for (const [, child] of node.children) {
+      walk(child);
+    }
+    if (node.paramChild) walk(node.paramChild);
+    if (node.wildcardChild) walk(node.wildcardChild);
+  }, "walk");
+  walk(root);
+  for (const [, methodMap] of staticRoutes) {
+    for (const [key, entry] of methodMap) {
+      const combinedMw = [
+        ...routerMw,
+        ...entry.middleware
+      ];
+      entry.executor = compileExecutor(entry.handler, combinedMw);
+      methodMap.set(key, entry);
     }
   }
-  /**
-  * Generate allowed methods middleware
-  * Responds to OPTIONS and sets Allow header
-  */
-  allowedMethods() {
-    return async (ctx, next) => {
-      if (next) {
-        await next();
+}
+__name(sealRouterMiddleware, "sealRouterMiddleware");
+
+// src/registration.ts
+import { HTTP_METHODS as HTTP_METHODS2 } from "@nextrush/types";
+
+// src/route-metadata.ts
+import { ROUTE_METADATA } from "@nextrush/types";
+function endpoint(metadata) {
+  return {
+    [ROUTE_METADATA]: metadata
+  };
+}
+__name(endpoint, "endpoint");
+function mergeContributions(contributions) {
+  if (contributions.length === 0) return void 0;
+  const meta = {};
+  for (const c of contributions) {
+    if (c.summary !== void 0) meta.summary = c.summary;
+    if (c.description !== void 0) meta.description = c.description;
+    if (c.deprecated !== void 0) meta.deprecated = c.deprecated;
+    if (c.visibility !== void 0) meta.visibility = c.visibility;
+    if (c.tags !== void 0) meta.tags = c.tags;
+    if (c.request) meta.request = {
+      ...meta.request,
+      ...c.request
+    };
+    if (c.responses) meta.responses = {
+      ...meta.responses,
+      ...c.responses
+    };
+  }
+  return meta;
+}
+__name(mergeContributions, "mergeContributions");
+function readContribution(entry) {
+  return entry[ROUTE_METADATA];
+}
+__name(readContribution, "readContribution");
+
+// src/registration.ts
+function normalizeRegistrationPath(path, prefix, strict) {
+  let joinedPrefix = prefix;
+  if (joinedPrefix.endsWith("/") && path.startsWith("/")) {
+    joinedPrefix = joinedPrefix.slice(0, -1);
+  }
+  let normalized = joinedPrefix + path;
+  if (normalized.includes("//")) {
+    normalized = normalized.replace(/\/+/g, "/");
+  }
+  if (!strict && normalized.length > 1 && normalized.endsWith("/")) {
+    normalized = normalized.slice(0, -1);
+  }
+  return normalized.startsWith("/") ? normalized : "/" + normalized;
+}
+__name(normalizeRegistrationPath, "normalizeRegistrationPath");
+function setStaticEntry(staticRoutes, method, key, entry) {
+  let methodMap = staticRoutes.get(method);
+  if (!methodMap) {
+    methodMap = /* @__PURE__ */ new Map();
+    staticRoutes.set(method, methodMap);
+  }
+  methodMap.set(key, entry);
+}
+__name(setStaticEntry, "setStaticEntry");
+function addRoute(method, normalized, entries, middleware, state, recordIntrospection = true) {
+  const segments = parseSegments(normalized, state.caseSensitive);
+  if (segments.length > state.maxDepth) {
+    state.maxDepth = segments.length;
+  }
+  let node = state.root;
+  for (const seg of segments) {
+    if (seg.type === NodeType.PARAM) {
+      if (!node.paramChild) {
+        node.paramChild = createNode(seg.segment, NodeType.PARAM);
+        node.paramChild.paramName = seg.paramName;
+      } else if (node.paramChild.paramName !== seg.paramName) {
+        throw new Error(`Route param name conflict at "${normalized}": ":${String(seg.paramName)}" conflicts with existing ":${String(node.paramChild.paramName)}" at the same position. Use the same param name for this segment across all routes.`);
       }
-      if (ctx.status !== 404) return;
-      const allowed = this.findAllowedMethods(ctx.path);
-      if (allowed.length === 0) return;
-      const allowHeader = allowed.join(", ");
-      if (ctx.method === "OPTIONS") {
-        ctx.status = 200;
-        ctx.set("Allow", allowHeader);
-        ctx.body = "";
-        return;
+      node = node.paramChild;
+    } else if (seg.type === NodeType.WILDCARD) {
+      node.wildcardChild ??= createNode("*", NodeType.WILDCARD);
+      node = node.wildcardChild;
+      break;
+    } else {
+      const key = seg.segment;
+      let child = node.children.get(key);
+      if (!child) {
+        child = createNode(seg.segment, NodeType.STATIC);
+        node.children.set(key, child);
       }
-      ctx.status = 405;
-      ctx.set("Allow", allowHeader);
+      node = child;
+    }
+  }
+  const functions = [];
+  const contributions = [];
+  for (const routeEntry of entries) {
+    const contribution = readContribution(routeEntry);
+    if (contribution) contributions.push(contribution);
+    if (typeof routeEntry === "function") functions.push(routeEntry);
+  }
+  const combinedMiddleware = [
+    ...middleware
+  ];
+  const finalHandler = functions[functions.length - 1];
+  if (!finalHandler) {
+    throw new Error("At least one handler is required");
+  }
+  for (let i = 0; i < functions.length - 1; i++) {
+    const fn = functions[i];
+    if (fn) combinedMiddleware.push(fn);
+  }
+  const executor = compileExecutor(finalHandler, combinedMiddleware);
+  const handlerEntry = {
+    handler: finalHandler,
+    middleware: combinedMiddleware,
+    executor,
+    autoHead: false
+  };
+  const existing = node.handlers.get(method);
+  if (existing && !(method === "HEAD" && existing.autoHead)) {
+    throw new Error(`Route conflict: ${method} ${normalized} is already registered. Remove the duplicate or use a different path.`);
+  }
+  node.handlers.set(method, handlerEntry);
+  const hasParams = segments.some((s) => s.type === NodeType.PARAM || s.type === NodeType.WILDCARD);
+  const staticKey = hasParams ? void 0 : state.caseSensitive ? normalized : normalized.toLowerCase();
+  if (staticKey !== void 0) {
+    setStaticEntry(state.staticRoutes, method, staticKey, handlerEntry);
+  }
+  if (method === "GET" && !node.handlers.has("HEAD")) {
+    const derived = {
+      handler: finalHandler,
+      middleware: combinedMiddleware,
+      executor,
+      autoHead: true
     };
+    node.handlers.set("HEAD", derived);
+    if (staticKey !== void 0) {
+      setStaticEntry(state.staticRoutes, "HEAD", staticKey, derived);
+    }
   }
-  /**
-  * Find all HTTP methods registered for a given path via single tree walk
-  * @internal
-  */
-  findAllowedMethods(path) {
-    let normalized = this.opts.caseSensitive ? path : path.toLowerCase();
-    if (normalized.includes("//")) {
-      normalized = normalized.replace(/\/+/g, "/");
+  if (recordIntrospection) {
+    state.routeDefinitions.push({
+      key: `${method} ${normalized}`,
+      method,
+      path: normalized,
+      metadata: mergeContributions(contributions)
+    });
+  }
+  return hasParams;
+}
+__name(addRoute, "addRoute");
+function registerRedirect(from, to, status, addRoute2) {
+  const redirectHandler = createRedirectHandler(to, status);
+  addRoute2("GET", from, [
+    redirectHandler
+  ]);
+  addRoute2("HEAD", from, [
+    redirectHandler
+  ]);
+  if (status === 307 || status === 308) {
+    addRoute2("POST", from, [
+      redirectHandler
+    ]);
+    addRoute2("PUT", from, [
+      redirectHandler
+    ]);
+    addRoute2("PATCH", from, [
+      redirectHandler
+    ]);
+    addRoute2("DELETE", from, [
+      redirectHandler
+    ]);
+  }
+}
+__name(registerRedirect, "registerRedirect");
+function pushAnyMethodDefinition(routeDefinitions, normalized) {
+  routeDefinitions.push({
+    key: `${HTTP_METHODS2[0]} ${normalized}`,
+    method: HTTP_METHODS2[0],
+    path: normalized,
+    isAnyMethod: true
+  });
+}
+__name(pushAnyMethodDefinition, "pushAnyMethodDefinition");
+
+// src/find-node.ts
+function findNode(root, path, startPos) {
+  const stack = [
+    {
+      node: root,
+      pos: startPos,
+      stage: 0,
+      next: 0
     }
-    if (!this.opts.strict && normalized.length > 1 && normalized.endsWith("/")) {
-      normalized = normalized.slice(0, -1);
+  ];
+  while (stack.length > 0) {
+    const frame = stack[stack.length - 1];
+    if (frame === void 0) break;
+    if (frame.stage === 0) {
+      if (frame.pos >= path.length) {
+        return frame.node;
+      }
+      const seg = segmentAt(path, frame.pos);
+      if (seg === "") {
+        return frame.node;
+      }
+      const segEnd = frame.pos + seg.length;
+      frame.next = segEnd < path.length ? segEnd + 1 : path.length;
+      frame.stage = 1;
+      const staticChild = frame.node.children.get(seg);
+      if (staticChild) {
+        stack.push({
+          node: staticChild,
+          pos: frame.next,
+          stage: 0,
+          next: 0
+        });
+      }
+      continue;
     }
-    const segments = normalized.split("/").filter(Boolean);
-    const node = this.findNode(this.root, segments, 0);
-    if (!node || node.handlers.size === 0) return [];
-    return Array.from(node.handlers.keys());
+    if (frame.stage === 1) {
+      frame.stage = 2;
+      if (frame.node.paramChild) {
+        stack.push({
+          node: frame.node.paramChild,
+          pos: frame.next,
+          stage: 0,
+          next: 0
+        });
+      }
+      continue;
+    }
+    if (frame.node.wildcardChild) {
+      return frame.node.wildcardChild;
+    }
+    stack.pop();
   }
-  /**
-  * Walk the tree to find the node matching a path (ignoring HTTP method)
-  * @internal
-  */
-  findNode(node, segments, index) {
-    if (index === segments.length) {
-      return node;
+  return null;
+}
+__name(findNode, "findNode");
+function findAllowedMethods(path, root, caseSensitive, strict) {
+  const normalized = normalizePathForMatch(path, caseSensitive, strict);
+  const node = findNode(root, normalized, 1);
+  if (!node || node.handlers.size === 0) return [];
+  return Array.from(node.handlers.keys());
+}
+__name(findAllowedMethods, "findAllowedMethods");
+
+// src/canonicalize.ts
+var DOT = 46;
+var SLASH = 47;
+function hasDotSegment(path) {
+  const len = path.length;
+  let segStart = 0;
+  for (let i = 0; i <= len; i++) {
+    const atBoundary = i === len || path.charCodeAt(i) === SLASH;
+    if (!atBoundary) continue;
+    const segLen = i - segStart;
+    if (segLen === 1 && path.charCodeAt(segStart) === DOT) return true;
+    if (segLen === 2 && path.charCodeAt(segStart) === DOT && path.charCodeAt(segStart + 1) === DOT) {
+      return true;
     }
-    const segment = segments[index];
-    if (segment === void 0) return null;
-    const staticChild = node.children.get(segment);
-    if (staticChild) {
-      const result = this.findNode(staticChild, segments, index + 1);
-      if (result) return result;
+    segStart = i + 1;
+  }
+  return false;
+}
+__name(hasDotSegment, "hasDotSegment");
+var memoTarget = void 0;
+var memoCaseSensitive = false;
+var memoStrict = false;
+var memoResult = {
+  rejected: false,
+  path: "/"
+};
+function canonicalizePath(rawTarget, caseSensitive, strict) {
+  if (rawTarget === memoTarget && caseSensitive === memoCaseSensitive && strict === memoStrict) {
+    return memoResult;
+  }
+  const queryIdx = rawTarget.indexOf("?");
+  const path = queryIdx === -1 ? rawTarget : rawTarget.slice(0, queryIdx);
+  const result = hasDotSegment(path) ? {
+    rejected: true,
+    path
+  } : {
+    rejected: false,
+    path: collapseAndStrip(caseSensitive || isProvablyLowerAscii(path) ? path : path.toLowerCase(), strict)
+  };
+  memoTarget = rawTarget;
+  memoCaseSensitive = caseSensitive;
+  memoStrict = strict;
+  memoResult = result;
+  return result;
+}
+__name(canonicalizePath, "canonicalizePath");
+
+// src/dispatch.ts
+var RESOLVED = Promise.resolve();
+function createRoutesMiddleware(match, caseSensitive, strict) {
+  return (ctx, next) => {
+    const originalPath = ctx.path;
+    const canonical = canonicalizePath(originalPath, caseSensitive, strict);
+    if (canonical.rejected) {
+      ctx.status = 400;
+      ctx.originalPath = originalPath;
+      return RESOLVED;
     }
-    if (node.paramChild) {
-      const result = this.findNode(node.paramChild, segments, index + 1);
-      if (result) return result;
+    ctx.path = canonical.path;
+    ctx.originalPath = originalPath;
+    const routeMatch = match(ctx.method, canonical.path);
+    if (!routeMatch) {
+      ctx.status = 404;
+      return next ? next() : RESOLVED;
     }
-    if (node.wildcardChild) {
-      return node.wildcardChild;
+    ctx.params = routeMatch.params;
+    return routeMatch.executor ? routeMatch.executor(ctx) : (
+      // or thenable return still yields a Promise<void> and never a sync throw.
+      Promise.resolve(routeMatch.handler(ctx, NOOP_NEXT))
+    );
+  };
+}
+__name(createRoutesMiddleware, "createRoutesMiddleware");
+function createAllowedMethodsMiddleware(root, caseSensitive, strict) {
+  return async (ctx, next) => {
+    if (next) {
+      await next();
     }
-    return null;
+    if (ctx.status !== 404) return;
+    const allowed = findAllowedMethods(ctx.path, root, caseSensitive, strict);
+    if (allowed.length === 0) return;
+    const allowHeader = allowed.join(", ");
+    if (ctx.method === "OPTIONS") {
+      ctx.status = 200;
+      ctx.set("Allow", allowHeader);
+      ctx.body = "";
+      return;
+    }
+    ctx.status = 405;
+    ctx.set("Allow", allowHeader);
+  };
+}
+__name(createAllowedMethodsMiddleware, "createAllowedMethodsMiddleware");
+
+// src/state.ts
+function resolveRouterOptions(options) {
+  return {
+    prefix: options.prefix ?? "",
+    caseSensitive: options.caseSensitive ?? false,
+    strict: options.strict ?? false,
+    decode: options.decode ?? true
+  };
+}
+__name(resolveRouterOptions, "resolveRouterOptions");
+function createRouterState(root, opts, staticRoutes, routeDefinitions, routerMiddleware) {
+  return {
+    root,
+    staticRoutes,
+    routeDefinitions,
+    caseSensitive: opts.caseSensitive,
+    strict: opts.strict,
+    decode: opts.decode,
+    routerMiddleware,
+    maxDepth: 0
+  };
+}
+__name(createRouterState, "createRouterState");
+
+// src/router.ts
+var SLASH_CHAR_CODE = 47;
+var Router = class _Router {
+  static {
+    __name(this, "Router");
   }
-  // ===========================================================================
-  // Route Groups
-  // ===========================================================================
+  root;
+  opts;
+  routerMiddleware = [];
+  /** Static-route fast path: method-nested map for O(1) lookup with no per-request key string (HP-9). */
+  staticRoutes = /* @__PURE__ */ new Map();
   /**
-  * Create a route group with shared prefix and middleware
-  *
-  * @param prefix - Path prefix for all routes in the group
-  * @param middlewareOrCallback - Middleware array or callback function
-  * @param callback - Callback function if middleware is provided
-  * @returns this for chaining
-  *
-  * @example
-  * ```typescript
-  * // Simple group with prefix
-  * router.group('/api', (r) => {
-  *   r.get('/users', listUsers);
-  *   r.get('/posts', listPosts);
-  * });
-  *
-  * // Group with middleware
-  * router.group('/admin', [authMiddleware], (r) => {
-  *   r.get('/dashboard', dashboard);
-  *   r.post('/settings', updateSettings);
-  * });
-  *
-  * // Nested groups
-  * router.group('/api/v1', (r) => {
-  *   r.group('/users', [rateLimit], (ur) => {
-  *     ur.get('/', listUsers);
-  *     ur.get('/:id', getUser);
-  *   });
-  * });
-  * ```
+  * Introspection registry, kept SEPARATE from the hot-path trie/staticRoutes
+  * so request dispatch never reads metadata — only getRoutes() touches it.
   */
-  group(prefix, middlewareOrCallback, callback) {
-    let middleware = [];
-    let cb;
-    if (Array.isArray(middlewareOrCallback)) {
-      middleware = middlewareOrCallback;
-      if (!callback) {
-        throw new Error("Callback function is required when providing middleware array");
-      }
-      cb = callback;
-    } else {
-      cb = middlewareOrCallback;
-    }
-    const groupRouter = new GroupRouter(this, prefix, middleware);
-    cb(groupRouter);
-    return this;
-  }
+  routeDefinitions = [];
+  /** Whether any routes have params or wildcards (disables static-only fast path) */
+  hasParamRoutes = false;
+  /** Whether router-level middleware has already been sealed into executors (audit RT-7) */
+  _sealed = false;
   /**
-  * Remove all registered routes and middleware, resetting the router to its initial state.
-  * Useful for plugin `destroy()` to cleanly un-register routes.
+  * Single-entry memo for {@link matchesMountPrefix}'s canonicalization of the
+  * mount prefix, which is fixed at registration time. Declared as two fields
+  * rather than an object so a miss stores without allocating.
   */
-  reset() {
-    this.root.children.clear();
-    this.root.handlers.clear();
-    this.root.paramChild = void 0;
-    this.root.wildcardChild = void 0;
-    this.staticRoutes.clear();
-    this.routerMiddleware.length = 0;
-    this.hasParamRoutes = false;
+  _prefixMemoRaw = void 0;
+  _prefixMemoCanonical = "";
+  /** Memoized state the extracted registration/matching functions read (see {@link createRouterState}). */
+  state;
+  constructor(options = {}) {
+    this.root = createNode("");
+    this.opts = resolveRouterOptions(options);
+    this.state = createRouterState(this.root, this.opts, this.staticRoutes, this.routeDefinitions, this.routerMiddleware);
   }
   /**
-  * Internal method to add route with group context
-  * @internal
+  * Validate + normalize a raw path, then delegate trie insertion to the
+  * extracted `addRoute` (design.md D2); flips `hasParamRoutes` from its return.
   */
-  _addGroupRoute(method, path, handlers, groupMiddleware) {
-    this.addRoute(method, path, handlers, groupMiddleware);
+  addRoute(method, path, entries, middleware = [], recordIntrospection = true) {
+    const rawPath = path;
+    if (typeof rawPath !== "string") {
+      throw new TypeError(`Route path must be a string, received ${rawPath === null ? "null" : typeof rawPath}.`);
+    }
+    const normalized = normalizeRegistrationPath(path, this.opts.prefix, this.opts.strict);
+    const depthBefore = this.state.maxDepth;
+    if (addRoute(method, normalized, entries, middleware, this.state, recordIntrospection)) {
+      this.hasParamRoutes = true;
+    }
+    if (this.state.maxDepth > depthBefore) {
+      this.state.walkPool = createWalkPool(this.state.maxDepth);
+    }
   }
-};
-var GroupRouter = class GroupRouter2 {
-  static {
-    __name(this, "GroupRouter");
+  get(path, ...entries) {
+    this.addRoute("GET", path, entries);
+    return this;
   }
-  parent;
-  prefix;
-  middleware;
-  constructor(parent, prefix, middleware) {
-    this.parent = parent;
-    this.prefix = prefix;
-    this.middleware = middleware;
+  post(path, ...entries) {
+    this.addRoute("POST", path, entries);
+    return this;
   }
-  fullPath(path) {
-    if (path === "/" || path === "") {
-      return this.prefix;
-    }
-    const cleanPrefix = this.prefix.endsWith("/") ? this.prefix.slice(0, -1) : this.prefix;
-    const cleanPath = path.startsWith("/") ? path : "/" + path;
-    return cleanPrefix + cleanPath;
+  put(path, ...entries) {
+    this.addRoute("PUT", path, entries);
+    return this;
   }
-  get(path, ...handlers) {
-    this.parent._addGroupRoute("GET", this.fullPath(path), handlers, this.middleware);
+  delete(path, ...entries) {
+    this.addRoute("DELETE", path, entries);
     return this;
   }
-  post(path, ...handlers) {
-    this.parent._addGroupRoute("POST", this.fullPath(path), handlers, this.middleware);
+  patch(path, ...entries) {
+    this.addRoute("PATCH", path, entries);
     return this;
   }
-  put(path, ...handlers) {
-    this.parent._addGroupRoute("PUT", this.fullPath(path), handlers, this.middleware);
+  head(path, ...entries) {
+    this.addRoute("HEAD", path, entries);
     return this;
   }
-  delete(path, ...handlers) {
-    this.parent._addGroupRoute("DELETE", this.fullPath(path), handlers, this.middleware);
+  options(path, ...entries) {
+    this.addRoute("OPTIONS", path, entries);
     return this;
   }
-  patch(path, ...handlers) {
-    this.parent._addGroupRoute("PATCH", this.fullPath(path), handlers, this.middleware);
+  /**
+  * Register a route for every HTTP method under one consolidated `isAnyMethod`
+  * introspection row (T016) — matching is unchanged (see {@link pushAnyMethodDefinition}).
+  */
+  all(path, ...entries) {
+    for (const method of HTTP_METHODS3) {
+      this.addRoute(method, path, entries, [], false);
+    }
+    pushAnyMethodDefinition(this.routeDefinitions, normalizeRegistrationPath(path, this.opts.prefix, this.opts.strict));
     return this;
   }
-  head(path, ...handlers) {
-    this.parent._addGroupRoute("HEAD", this.fullPath(path), handlers, this.middleware);
+  route(method, path, ...entries) {
+    this.addRoute(method, path, entries);
     return this;
   }
-  options(path, ...handlers) {
-    this.parent._addGroupRoute("OPTIONS", this.fullPath(path), handlers, this.middleware);
+  /**
+  * Every registered route as a read-only list, for renderers (`@nextrush/openapi`,
+  * SDK/RPC generators). Doc-generation-time only — never on the request path.
+  */
+  getRoutes() {
+    return this.routeDefinitions;
+  }
+  /**
+  * Register a redirect from one path to another (301 by default). 307/308
+  * additionally register POST/PUT/PATCH/DELETE to preserve the method.
+  * @see {@link https://github.com/0xTanzim/nextRush/blob/main/packages/router/README.md#redirects | README: Redirects}
+  */
+  redirect(from, to, status = 301) {
+    registerRedirect(from, to, status, (method, path, entries) => {
+      this.addRoute(method, path, entries);
+    });
     return this;
   }
-  all(path, ...handlers) {
-    for (const method of HTTP_METHODS) {
-      this.parent._addGroupRoute(method, this.fullPath(path), handlers, this.middleware);
+  use(pathOrMiddleware, routerOrUndefined) {
+    if (typeof pathOrMiddleware === "function") {
+      this.routerMiddleware.push(pathOrMiddleware);
+    } else if (typeof pathOrMiddleware === "string" && routerOrUndefined instanceof _Router) {
+      this.mountRouter(pathOrMiddleware, routerOrUndefined);
+    } else if (typeof pathOrMiddleware === "string") {
+      throw new Error(`router.use('${pathOrMiddleware}', ...) requires a Router instance as the second argument. Use router.group(prefix, callback) for prefix-scoped middleware, or router.use(middlewareFn) to register middleware without a prefix.`);
+    } else if (pathOrMiddleware instanceof _Router) {
+      this.mountRouter("", pathOrMiddleware);
     }
     return this;
   }
   /**
-  * Register a redirect within the group
+  * Mount a sub-router at a path prefix (Hono-style) — the explicit, more
+  * semantic equivalent of `router.use(path, subRouter)`.
+  * @see {@link https://github.com/0xTanzim/nextRush/blob/main/packages/router/README.md#sub-router-mounting | README: Sub-Router Mounting}
   */
-  redirect(from, to, status = 301) {
-    const redirectHandler = /* @__PURE__ */ __name((ctx) => {
-      let targetPath = to;
-      if (targetPath.includes(":")) {
-        const entries = Object.entries(ctx.params).sort((a, b) => b[0].length - a[0].length);
-        for (const [key, value] of entries) {
-          targetPath = targetPath.replaceAll(`:${key}`, value);
-        }
-      }
-      ctx.status = status;
-      ctx.set("Location", targetPath);
-      ctx.body = "";
-    }, "redirectHandler");
-    this.parent._addGroupRoute("GET", this.fullPath(from), [
-      redirectHandler
-    ], this.middleware);
-    this.parent._addGroupRoute("HEAD", this.fullPath(from), [
-      redirectHandler
-    ], this.middleware);
+  mount(path, router) {
+    this.mountRouter(path, router);
     return this;
   }
+  /** Mount a sub-router, carrying its own `routerMiddleware` onto every copied route. */
+  mountRouter(prefix, router) {
+    copyRoutes(router.root, prefix, [], router.routerMiddleware, this.addRoute.bind(this));
+  }
+  /** Match a request to a route — delegates to {@link resolveMatch} (design.md D1). */
+  match(method, path) {
+    return resolveMatch(this.state, this.hasParamRoutes, method, path);
+  }
   /**
-  * Nested group support
+  * Test whether `path` falls under `prefix` using this router's OWN
+  * canonicalization (case folding per `caseSensitive`, structural
+  * normalization) — the mount-boundary counterpart to {@link match}, so a
+  * router mounted via `Application.route()` is tested with the identical
+  * rule it dispatches with (RFC-029, task 3.8). Implements the optional
+  * `Routable.matchesMountPrefix` contract from `@nextrush/core`.
+  *
+  * @param path - The full request path being tested for this mount.
+  * @param prefix - The normalized mount prefix (leading `/`, no trailing `/`).
+  * @returns The path's remainder past the prefix (e.g. `/users` for a
+  *   `/ADMIN/Users` request mounted at `/admin`), or `undefined` when `path`
+  *   is not under `prefix` per this router's canonicalization.
   */
-  group(prefix, middlewareOrCallback, callback) {
-    let nestedMiddleware = [];
-    let cb;
-    if (Array.isArray(middlewareOrCallback)) {
-      nestedMiddleware = middlewareOrCallback;
-      if (!callback) {
-        throw new Error("Callback function is required when providing middleware array");
-      }
-      cb = callback;
+  matchesMountPrefix(path, prefix) {
+    const canonical = canonicalizePath(path, this.opts.caseSensitive, this.opts.strict);
+    if (canonical.rejected) return void 0;
+    let canonicalPrefix;
+    if (this._prefixMemoRaw === prefix) {
+      canonicalPrefix = this._prefixMemoCanonical;
     } else {
-      cb = middlewareOrCallback;
+      canonicalPrefix = canonicalizePath(prefix, this.opts.caseSensitive, this.opts.strict).path;
+      this._prefixMemoRaw = prefix;
+      this._prefixMemoCanonical = canonicalPrefix;
     }
-    const nestedRouter = new GroupRouter2(this.parent, this.fullPath(prefix), [
-      ...this.middleware,
-      ...nestedMiddleware
-    ]);
-    cb(nestedRouter);
+    const prefixLen = canonicalPrefix.length;
+    if (!canonical.path.startsWith(canonicalPrefix)) return void 0;
+    const hasCharAfterPrefix = prefixLen < canonical.path.length;
+    if (hasCharAfterPrefix && canonical.path.charCodeAt(prefixLen) !== SLASH_CHAR_CODE) {
+      return void 0;
+    }
+    return canonical.path.slice(prefixLen) || "/";
+  }
+  /**
+  * Return the router's dispatch middleware — mount this on the application.
+  * @see {@link https://github.com/0xTanzim/nextRush/blob/main/packages/router/README.md#routerroutes | README: router.routes()}
+  */
+  routes() {
+    if (this.routerMiddleware.length > 0 && !this._sealed) {
+      this._sealed = true;
+      sealRouterMiddleware(this.root, this.staticRoutes, this.routerMiddleware);
+    }
+    return createRoutesMiddleware((method, path) => resolveMatch(this.state, this.hasParamRoutes, method, path, true), this.opts.caseSensitive, this.opts.strict);
+  }
+  /**
+  * Generate allowed-methods middleware. Responds to OPTIONS with an `Allow`
+  * header and returns 405 for a known path hit with an unregistered method.
+  */
+  allowedMethods() {
+    return createAllowedMethodsMiddleware(this.root, this.opts.caseSensitive, this.opts.strict);
+  }
+  /**
+  * Create a route group with a shared prefix and middleware. The callback
+  * receives a {@link RouteGroup} to register routes against.
+  * @see {@link https://github.com/0xTanzim/nextRush/blob/main/packages/router/README.md#route-groups | README: Route Groups}
+  */
+  group(prefix, middlewareOrCallback, callback) {
+    runRouteGroup(this, prefix, middlewareOrCallback, callback);
     return this;
   }
+  /**
+  * Remove all routes and middleware, resetting the router to its initial
+  * state — for test isolation or hot-reload re-registration.
+  */
+  reset() {
+    clearNode(this.root);
+    this.staticRoutes.clear();
+    this.routerMiddleware.length = 0;
+    this.hasParamRoutes = false;
+    this.routeDefinitions.length = 0;
+    this.state.maxDepth = 0;
+    this.state.walkPool = void 0;
+    this._sealed = false;
+  }
+  /** Register a route on behalf of a {@link RouteGroup} (group context). @internal */
+  _addGroupRoute(method, path, handlers, groupMiddleware, recordIntrospection = true) {
+    this.addRoute(method, path, handlers, groupMiddleware, recordIntrospection);
+  }
+  /**
+  * Group-facing entry point to {@link pushAnyMethodDefinition} — a group's `.all()`
+  * records its consolidated row here since group routes live on the parent. @internal
+  */
+  _pushAnyMethodRouteDefinition(path) {
+    pushAnyMethodDefinition(this.routeDefinitions, normalizeRegistrationPath(path, this.opts.prefix, this.opts.strict));
+  }
 };
 function createRouter(options) {
   return new Router(options);
@@ -846,8 +1261,11 @@ __name(createRouter, "createRouter");
 export {
   NodeType,
   Router,
+  canonicalizePath,
   createNode,
   createRouter,
+  endpoint,
+  hasDotSegment,
   parseSegments
 };
 //# sourceMappingURL=index.js.map