@emkodev/emroute 1.6.5 → 1.6.6-beta.2

package/src/renderer/spa/html.renderer.ts

@@ -17,10 +17,10 @@ import type {
   RedirectConfig,
   RouteParams,
   RouterState,
-  RoutesManifest,
 } from '../../type/route.type.ts';
 import type { ContextProvider } from '../../component/abstract.component.ts';
 import type { PageComponent } from '../../component/page.component.ts';
+import type { RouteResolver } from '../../route/route.resolver.ts';
 import { ComponentElement } from '../../element/component.element.ts';
 import {
   assertSafeRedirect,
@@ -40,6 +40,8 @@ export interface SpaHtmlRouterOptions {
   extendContext?: ContextProvider;
   /** Base paths for SSR endpoints. SPA uses html basePath for routing, md for passthrough. */
   basePath?: BasePath;
+  /** Pre-bundled module loaders keyed by file path. Bridges JSON route tree → bundled code in the browser. */
+  moduleLoaders?: Record<string, () => Promise<unknown>>;
 }
 
 /**
@@ -51,11 +53,12 @@ export class SpaHtmlRouter extends BaseRenderer {
   private htmlBase: string;
   private mdBase: string;
 
-  constructor(manifest: RoutesManifest, options?: SpaHtmlRouterOptions) {
+  constructor(resolver: RouteResolver, options?: SpaHtmlRouterOptions) {
     const bp = options?.basePath ?? DEFAULT_BASE_PATH;
-    const core = new RouteCore(manifest, {
+    const core = new RouteCore(resolver, {
       extendContext: options?.extendContext,
       basePath: bp.html,
+      moduleLoaders: options?.moduleLoaders,
     });
     super(core);
     this.htmlBase = bp.html;
@@ -120,8 +123,8 @@ export class SpaHtmlRouter extends BaseRenderer {
       logger.ssr('check-adoption', `SSR route=${ssrRoute}, current=${currentPath}`);
 
       if (currentPath === ssrRoute || currentPath === ssrRoute + '/') {
-        // Adopt SSR content — patterns are prefixed, match directly
-        const matched = this.core.match(new URL(ssrRoute, location.origin));
+        // Adopt SSR content — strip basePath before matching unprefixed trie
+        const matched = this.core.match(new URL(this.stripBase(ssrRoute), location.origin));
         if (matched) {
           logger.ssr('adopt', ssrRoute);
           this.core.currentRoute = matched;
@@ -195,6 +198,17 @@ export class SpaHtmlRouter extends BaseRenderer {
     return this.core.currentRoute;
   }
 
+  /**
+   * Strip the HTML basePath prefix from a browser pathname.
+   * Browser URLs include the prefix (e.g. /html/about) but trie patterns don't.
+   */
+  private stripBase(pathname: string): string {
+    if (this.htmlBase && (pathname.startsWith(this.htmlBase + '/') || pathname === this.htmlBase)) {
+      return pathname === this.htmlBase ? '/' : pathname.slice(this.htmlBase.length);
+    }
+    return pathname;
+  }
+
   /**
    * Handle navigation to a URL.
    *
@@ -217,8 +231,11 @@ export class SpaHtmlRouter extends BaseRenderer {
       return;
     }
 
+    // Strip basePath prefix — trie holds unprefixed patterns
+    const routePath = this.stripBase(pathname);
+
     try {
-      const matched = this.core.match(urlObj);
+      const matched = this.core.match(new URL(routePath, location.origin));
 
       if (!matched) {
         logger.nav('not-found', pathname, pathname);
@@ -267,7 +284,7 @@ export class SpaHtmlRouter extends BaseRenderer {
         await this.renderStatusPage(error.status, pathname);
         return;
       }
-      await this.handleError(error, pathname);
+      await this.handleError(error, routePath);
     }
   }
 
@@ -280,7 +297,7 @@ export class SpaHtmlRouter extends BaseRenderer {
   ): Promise<void> {
     if (!this.slot) return;
 
-    const statusPage = this.core.matcher.getStatusPage(status);
+    const statusPage = this.core.getStatusPage(status);
 
     if (statusPage) {
       try {
@@ -342,10 +359,10 @@ export class SpaHtmlRouter extends BaseRenderer {
       error: error instanceof Error ? error : new Error(String(error)),
     });
 
-    const boundary = this.core.matcher.findErrorBoundary(pathname);
+    const boundary = this.core.findErrorBoundary(pathname);
     if (boundary && await this.tryRenderErrorModule(boundary.modulePath)) return;
 
-    const errorHandler = this.core.matcher.getErrorHandler();
+    const errorHandler = this.core.getErrorHandler();
     if (errorHandler && await this.tryRenderErrorModule(errorHandler.modulePath)) return;
 
     if (this.slot) {
@@ -367,7 +384,7 @@ export class SpaHtmlRouter extends BaseRenderer {
  * Calling this function twice returns the existing router with a warning.
  */
 export async function createSpaHtmlRouter(
-  manifest: RoutesManifest,
+  resolver: RouteResolver,
   options?: SpaHtmlRouterOptions,
 ): Promise<SpaHtmlRouter> {
   const g = globalThis as Record<string, unknown>;
@@ -375,7 +392,7 @@ export async function createSpaHtmlRouter(
     console.warn('eMroute: SPA router already initialized. Remove duplicate <script> tags.');
     return g.__emroute_router as SpaHtmlRouter;
   }
-  const router = new SpaHtmlRouter(manifest, options);
+  const router = new SpaHtmlRouter(resolver, options);
   await router.initialize();
   g.__emroute_router = router;
   return router;

package/src/renderer/spa/mod.ts

@@ -39,8 +39,10 @@ export type {
   RouterEvent,
   RouterEventListener,
   RouterEventType,
-  RoutesManifest,
 } from '../../type/route.type.ts';
+export type { RouteNode } from '../../type/route-tree.type.ts';
+export type { RouteResolver, ResolvedRoute } from '../../route/route.resolver.ts';
+export { RouteTrie } from '../../route/route.trie.ts';
 export type { MarkdownRenderer } from '../../type/markdown.type.ts';
 export { type BasePath, DEFAULT_BASE_PATH } from '../../route/route.core.ts';
 export { escapeHtml, scopeWidgetCss } from '../../util/html.util.ts';

package/src/renderer/ssr/html.renderer.ts

@@ -6,7 +6,8 @@
  * Expands <mark-down> tags server-side when a markdown renderer is provided.
  */
 
-import type { RouteConfig, RouteInfo, RoutesManifest } from '../../type/route.type.ts';
+import type { RouteConfig, RouteInfo } from '../../type/route.type.ts';
+import type { RouteResolver } from '../../route/route.resolver.ts';
 import type { MarkdownRenderer } from '../../type/markdown.type.ts';
 import type { PageComponent } from '../../component/page.component.ts';
 import { DEFAULT_ROOT_ROUTE } from '../../route/route.core.ts';
@@ -28,8 +29,8 @@ export class SsrHtmlRouter extends SsrRenderer {
   private markdownRenderer: MarkdownRenderer | null;
   private markdownReady: Promise<void> | null = null;
 
-  constructor(manifest: RoutesManifest, options: SsrHtmlRouterOptions = {}) {
-    super(manifest, options);
+  constructor(resolver: RouteResolver, options: SsrHtmlRouterOptions = {}) {
+    super(resolver, options);
     this.markdownRenderer = options.markdownRenderer ?? null;
 
     if (this.markdownRenderer?.init) {
@@ -152,8 +153,8 @@ export class SsrHtmlRouter extends SsrRenderer {
  * Create SSR HTML router.
  */
 export function createSsrHtmlRouter(
-  manifest: RoutesManifest,
+  resolver: RouteResolver,
   options?: SsrHtmlRouterOptions,
 ): SsrHtmlRouter {
-  return new SsrHtmlRouter(manifest, options);
+  return new SsrHtmlRouter(resolver, options);
 }

package/src/renderer/ssr/md.renderer.ts

@@ -5,7 +5,8 @@
  * Generates Markdown strings for LLM consumption, text clients, curl.
  */
 
-import type { RouteConfig, RouteInfo, RoutesManifest } from '../../type/route.type.ts';
+import type { RouteConfig, RouteInfo } from '../../type/route.type.ts';
+import type { RouteResolver } from '../../route/route.resolver.ts';
 import type { PageComponent } from '../../component/page.component.ts';
 import { DEFAULT_ROOT_ROUTE } from '../../route/route.core.ts';
 import { STATUS_MESSAGES } from '../../util/html.util.ts';
@@ -28,8 +29,8 @@ export type SsrMdRouterOptions = SsrRendererOptions;
 export class SsrMdRouter extends SsrRenderer {
   protected override readonly label = 'SSR MD';
 
-  constructor(manifest: RoutesManifest, options: SsrMdRouterOptions = {}) {
-    super(manifest, options);
+  constructor(resolver: RouteResolver, options: SsrMdRouterOptions = {}) {
+    super(resolver, options);
   }
 
   protected override injectSlot(parent: string, child: string, parentPattern: string): string {
@@ -135,8 +136,8 @@ export class SsrMdRouter extends SsrRenderer {
  * Create SSR Markdown router.
  */
 export function createSsrMdRouter(
-  manifest: RoutesManifest,
+  resolver: RouteResolver,
   options?: SsrMdRouterOptions,
 ): SsrMdRouter {
-  return new SsrMdRouter(manifest, options);
+  return new SsrMdRouter(resolver, options);
 }

package/src/renderer/ssr/ssr.renderer.ts

@@ -9,7 +9,6 @@ import type {
   MatchedRoute,
   RouteConfig,
   RouteInfo,
-  RoutesManifest,
 } from '../../type/route.type.ts';
 import { logger } from '../../type/logger.type.ts';
 import type { ComponentContext } from '../../component/abstract.component.ts';
@@ -20,6 +19,7 @@ import {
   RouteCore,
   type RouteCoreOptions,
 } from '../../route/route.core.ts';
+import type { RouteResolver } from '../../route/route.resolver.ts';
 import { toUrl } from '../../route/route.matcher.ts';
 import type { WidgetRegistry } from '../../widget/widget.registry.ts';
 
@@ -40,8 +40,8 @@ export abstract class SsrRenderer {
   protected widgetFiles: Record<string, { html?: string; md?: string; css?: string }>;
   protected abstract readonly label: string;
 
-  constructor(manifest: RoutesManifest, options: SsrRendererOptions = {}) {
-    this.core = new RouteCore(manifest, options);
+  constructor(resolver: RouteResolver, options: SsrRendererOptions = {}) {
+    this.core = new RouteCore(resolver, options);
     this.widgets = options.widgets ?? null;
     this.widgetFiles = options.widgetFiles ?? {};
   }
@@ -55,19 +55,12 @@ export abstract class SsrRenderer {
     const urlObj = toUrl(url);
     const pathname = urlObj.pathname;
 
-    // Redirect trailing-slash URLs to canonical form (301)
-    const normalized = this.core.normalizeUrl(pathname);
-    if (normalized !== pathname) {
-      const query = urlObj.search || '';
-      return { content: '', status: 301, redirect: normalized + query };
-    }
-
     const matched = this.core.match(urlObj);
 
     const searchParams = urlObj.searchParams ?? new URLSearchParams();
 
     if (!matched) {
-      const statusPage = this.core.matcher.getStatusPage(404);
+      const statusPage = this.core.getStatusPage(404);
       if (statusPage) {
         try {
           const ri: RouteInfo = { pathname, pattern: statusPage.pattern, params: {}, searchParams };
@@ -93,6 +86,7 @@ export abstract class SsrRenderer {
       return {
         content: this.renderRedirect(redirectConfig.to),
         status: redirectConfig.status ?? 301,
+        redirect: redirectConfig.to,
       };
     }
 
@@ -103,7 +97,7 @@ export abstract class SsrRenderer {
       return { content, status: 200, title };
     } catch (error) {
       if (error instanceof Response) {
-        const statusPage = this.core.matcher.getStatusPage(error.status);
+        const statusPage = this.core.getStatusPage(error.status);
         if (statusPage) {
           try {
             const ri: RouteInfo = {
@@ -132,13 +126,13 @@ export abstract class SsrRenderer {
         error instanceof Error ? error : undefined,
       );
 
-      const boundary = this.core.matcher.findErrorBoundary(pathname);
+      const boundary = this.core.findErrorBoundary(pathname);
       if (boundary) {
         const result = await this.tryRenderErrorModule(boundary.modulePath, pathname, 'boundary');
         if (result) return result;
       }
 
-      const errorHandler = this.core.matcher.getErrorHandler();
+      const errorHandler = this.core.getErrorHandler();
       if (errorHandler) {
         const result = await this.tryRenderErrorModule(errorHandler.modulePath, pathname, 'handler');
         if (result) return result;
@@ -163,10 +157,10 @@ export abstract class SsrRenderer {
 
     for (let i = 0; i < hierarchy.length; i++) {
       const routePattern = hierarchy[i];
-      let route = this.core.matcher.findRoute(routePattern);
+      let route = this.core.findRoute(routePattern);
 
-      if (!route && routePattern === this.core.root) {
-        route = { ...DEFAULT_ROOT_ROUTE, pattern: this.core.root };
+      if (!route && routePattern === '/') {
+        route = DEFAULT_ROOT_ROUTE;
       }
 
       if (!route) continue;

package/src/route/route-tree.util.ts

@@ -0,0 +1,35 @@
+/**
+ * Route Tree Utilities
+ *
+ * Pure functions for building a RouteNode tree from filesystem paths.
+ */
+
+import type { RouteNode } from '../type/route-tree.type.ts';
+
+/**
+ * Resolve the target node for a page or redirect file based on its name.
+ *
+ * - "index" at root → the node itself (root route)
+ * - "index" in a subdirectory → wildcard catch-all on the node
+ * - "[param]" → dynamic child
+ * - anything else → static child
+ */
+export function resolveTargetNode(node: RouteNode, name: string, isRoot: boolean): RouteNode {
+  if (name === 'index') {
+    if (isRoot) return node;
+    // Non-root index → wildcard catch-all
+    node.wildcard ??= { param: 'rest', child: {} };
+    return node.wildcard.child;
+  }
+
+  if (name.startsWith('[') && name.endsWith(']')) {
+    const param = name.slice(1, -1);
+    node.dynamic ??= { param, child: {} };
+    return node.dynamic.child;
+  }
+
+  // Static segment
+  node.children ??= {};
+  node.children[name] ??= {};
+  return node.children[name];
+}

package/src/route/route.core.ts

@@ -2,10 +2,11 @@
  * Route Core
  *
  * Shared routing logic used by all renderers:
- * - Route matching and hierarchy building
+ * - Route matching (delegates to RouteResolver)
  * - Module loading and caching
  * - Event emission
  * - URL normalization
+ * - BasePath stripping
  */
 
 import type {
@@ -15,10 +16,10 @@ import type {
   RouteParams,
   RouterEvent,
   RouterEventListener,
-  RoutesManifest,
 } from '../type/route.type.ts';
 import type { ComponentContext, ContextProvider } from '../component/abstract.component.ts';
-import { RouteMatcher, toUrl } from './route.matcher.ts';
+import type { RouteResolver, ResolvedRoute } from './route.resolver.ts';
+import { toUrl } from './route.matcher.ts';
 
 /** Base paths for the two SSR rendering endpoints. */
 export interface BasePath {
@@ -31,34 +32,6 @@ export interface BasePath {
 /** Default base paths — backward compatible with existing /html/ and /md/ prefixes. */
 export const DEFAULT_BASE_PATH: BasePath = { html: '/html', md: '/md' };
 
-/**
- * Create a copy of a manifest with basePath prepended to all patterns.
- * Used by the server to prefix bare in-memory manifests before passing to routers.
- */
-export function prefixManifest(manifest: RoutesManifest, basePath: string): RoutesManifest {
-  if (!basePath) return manifest;
-  return {
-    routes: manifest.routes.map((r) => ({
-      ...r,
-      // Root pattern '/' becomes basePath itself (e.g. '/html'), not '/html/'
-      pattern: r.pattern === '/' ? basePath : basePath + r.pattern,
-      parent: r.parent ? (r.parent === '/' ? basePath : basePath + r.parent) : undefined,
-    })),
-    errorBoundaries: manifest.errorBoundaries.map((e) => ({
-      ...e,
-      pattern: e.pattern === '/' ? basePath : basePath + e.pattern,
-    })),
-    statusPages: new Map(
-      [...manifest.statusPages].map(([status, route]) => [
-        status,
-        { ...route, pattern: basePath + route.pattern },
-      ]),
-    ),
-    errorHandler: manifest.errorHandler,
-    moduleLoaders: manifest.moduleLoaders,
-  };
-}
-
 const BLOCKED_PROTOCOLS = /^(javascript|data|vbscript):/i;
 
 /** Throw if a redirect URL uses a dangerous protocol. */
@@ -68,13 +41,24 @@ export function assertSafeRedirect(url: string): void {
   }
 }
 
-/** Default root route - renders a slot for child routes */
+/** Default root route — renders a slot for child routes. */
 export const DEFAULT_ROOT_ROUTE: RouteConfig = {
   pattern: '/',
   type: 'page',
   modulePath: '__default_root__',
 };
 
+/** Synthesize a RouteConfig from a ResolvedRoute (bridge for renderer compatibility). */
+function toRouteConfig(resolved: ResolvedRoute): RouteConfig {
+  const node = resolved.node;
+  return {
+    pattern: resolved.pattern,
+    type: node.redirect ? 'redirect' : 'page',
+    modulePath: node.redirect ?? node.files?.ts ?? node.files?.html ?? node.files?.md ?? '',
+    files: node.files,
+  };
+}
+
 /** Options for RouteCore */
 export interface RouteCoreOptions {
   /**
@@ -85,23 +69,21 @@ export interface RouteCoreOptions {
   fileReader?: (path: string) => Promise<string>;
   /** Enriches every ComponentContext with app-level services before it reaches components. */
   extendContext?: ContextProvider;
-  /** Base path prepended to route patterns for URL matching (e.g. '/html'). No trailing slash. */
+  /** Base path stripped from URLs before matching (e.g. '/html'). No trailing slash. */
   basePath?: string;
+  /** Module loaders keyed by path — server provides these for SSR imports. */
+  moduleLoaders?: Record<string, () => Promise<unknown>>;
 }
 
 /**
  * Core router functionality shared across all rendering contexts.
  */
 export class RouteCore {
-  readonly matcher: RouteMatcher;
+  private readonly resolver: RouteResolver;
   /** Registered context provider (if any). Exposed so renderers can apply it to inline contexts. */
   readonly contextProvider: ContextProvider | undefined;
   /** Base path for URL matching (e.g. '/html'). Empty string when no basePath. */
   readonly basePath: string;
-  /** The root pattern — basePath when set, '/' otherwise. */
-  get root(): string {
-    return this.basePath || '/';
-  }
   private listeners: Set<RouterEventListener> = new Set();
   private moduleCache: Map<string, unknown> = new Map();
   private widgetFileCache: Map<string, string> = new Map();
@@ -109,13 +91,13 @@ export class RouteCore {
   currentRoute: MatchedRoute | null = null;
   private readFile: (path: string) => Promise<string>;
 
-  constructor(manifest: RoutesManifest, options: RouteCoreOptions = {}) {
+  constructor(resolver: RouteResolver, options: RouteCoreOptions = {}) {
+    this.resolver = resolver;
     this.basePath = options.basePath ?? '';
-    this.matcher = new RouteMatcher(manifest);
     this.readFile = options.fileReader ??
       ((path) => fetch(path, { headers: { Accept: 'text/plain' } }).then((r) => r.text()));
     this.contextProvider = options.extendContext;
-    this.moduleLoaders = manifest.moduleLoaders ?? {};
+    this.moduleLoaders = options.moduleLoaders ?? {};
   }
 
   /**
@@ -148,16 +130,24 @@ export class RouteCore {
 
   /**
    * Match a URL to a route.
-   * Falls back to the default root route for the basePath root (or '/' when no basePath).
+   * Falls back to the default root route for '/'.
    */
   match(url: URL | string): MatchedRoute | undefined {
-    const matched = this.matcher.match(url);
-    if (matched) return matched;
-
     const urlObj = toUrl(url);
-    if (urlObj.pathname === this.root || urlObj.pathname === this.root + '/') {
+    const pathname = urlObj.pathname;
+
+    const resolved = this.resolver.match(pathname);
+    if (resolved) {
+      return {
+        route: toRouteConfig(resolved),
+        params: resolved.params,
+        searchParams: urlObj.searchParams,
+      };
+    }
+
+    if (pathname === '/' || pathname === '') {
       return {
-        route: { ...DEFAULT_ROOT_ROUTE, pattern: this.root },
+        route: DEFAULT_ROOT_ROUTE,
         params: {},
         searchParams: urlObj.searchParams,
       };
@@ -166,29 +156,67 @@ export class RouteCore {
     return undefined;
   }
 
+  /** Get status-specific page (404, 401, 403). */
+  getStatusPage(status: number): RouteConfig | undefined {
+    const node = this.resolver.findRoute(`/${status}`);
+    if (!node) return undefined;
+    return {
+      pattern: `/${status}`,
+      type: 'page',
+      modulePath: node.files?.ts ?? node.files?.html ?? node.files?.md ?? '',
+      files: node.files,
+    };
+  }
+
+  /** Get global error handler (root errorBoundary). */
+  getErrorHandler(): RouteConfig | undefined {
+    const modulePath = this.resolver.findErrorBoundary('/');
+    if (!modulePath) return undefined;
+    return { pattern: '/', type: 'error', modulePath };
+  }
+
+  /**
+   * Find error boundary for a given pathname.
+   * Note: pattern is the input pathname, not the boundary's own pattern.
+   * Callers should only rely on modulePath.
+   */
+  findErrorBoundary(pathname: string): { pattern: string; modulePath: string } | undefined {
+    const modulePath = this.resolver.findErrorBoundary(pathname);
+    if (!modulePath) return undefined;
+    return { pattern: pathname, modulePath };
+  }
+
+  /**
+   * Find a route by its exact pattern.
+   * Used for building route hierarchy.
+   */
+  findRoute(pattern: string): RouteConfig | undefined {
+    const node = this.resolver.findRoute(pattern);
+    if (!node) return undefined;
+    return {
+      pattern,
+      type: node.redirect ? 'redirect' : 'page',
+      modulePath: node.redirect ?? node.files?.ts ?? node.files?.html ?? node.files?.md ?? '',
+      files: node.files,
+    };
+  }
+
   /**
    * Build route hierarchy from a pattern.
+   * Patterns are always unprefixed (no basePath).
    *
-   * When basePath is set, the root is the basePath itself and only
-   * segments after it are split into ancestors.
-   *
-   * e.g., basePath='/html', pattern='/html/projects/:id/tasks'
-   *   → ['/html', '/html/projects', '/html/projects/:id', '/html/projects/:id/tasks']
-   *
-   * Without basePath: '/projects/:id/tasks'
+   * e.g., '/projects/:id/tasks'
    *   → ['/', '/projects', '/projects/:id', '/projects/:id/tasks']
    */
   buildRouteHierarchy(pattern: string): string[] {
-    if (pattern === this.root || pattern === this.root + '/') {
-      return [this.root];
+    if (pattern === '/') {
+      return ['/'];
     }
 
-    // Extract the part after basePath
-    const tail = this.basePath ? pattern.slice(this.basePath.length) : pattern;
-    const segments = tail.split('/').filter(Boolean);
+    const segments = pattern.split('/').filter(Boolean);
 
-    const hierarchy: string[] = [this.root];
-    let current = this.basePath || '';
+    const hierarchy: string[] = ['/'];
+    let current = '';
     for (const segment of segments) {
       current += '/' + segment;
       hierarchy.push(current);
@@ -238,7 +266,6 @@ export class RouteCore {
 
   /**
    * Load widget file contents with caching.
-   * Returns an object with loaded file contents.
    */
   async loadWidgetFiles(
     widgetFiles: { html?: string; md?: string; css?: string },
@@ -285,8 +312,6 @@ export class RouteCore {
 
   /**
    * Build a ComponentContext by extending RouteInfo with loaded file contents.
-   * When a signal is provided it is forwarded to fetch() calls and included
-   * in the returned context so that getData() can observe cancellation.
    */
   async buildComponentContext(
     routeInfo: RouteInfo,

package/src/route/route.resolver.ts

@@ -0,0 +1,33 @@
+/**
+ * Route Resolver
+ *
+ * Interface for route lookup. Accepts a RouteNode tree (the manifest),
+ * provides O(depth) matching, error boundary lookup, and hierarchy traversal.
+ *
+ * Implementations: RouteTrie (in-memory trie from RouteNode tree).
+ * RouteCore depends on this interface, not on the algorithm.
+ */
+
+import type { RouteNode } from '../type/route-tree.type.ts';
+
+/** Result of matching a URL pathname against the route tree. */
+export interface ResolvedRoute {
+  /** The matched route node. */
+  readonly node: RouteNode;
+  /** URL pattern reconstructed from the tree path (e.g. "/projects/:id"). */
+  readonly pattern: string;
+  /** Extracted URL parameters (e.g. { id: "42" }). */
+  readonly params: Record<string, string>;
+}
+
+/** Route lookup interface. Decouples matching algorithm from the router. */
+export interface RouteResolver {
+  /** Match a URL pathname to a route. */
+  match(pathname: string): ResolvedRoute | undefined;
+
+  /** Find the most specific error boundary for a pathname. */
+  findErrorBoundary(pathname: string): string | undefined;
+
+  /** Look up a route node by its exact pattern (e.g. "/projects/:id"). */
+  findRoute(pattern: string): RouteNode | undefined;
+}