@emkodev/emroute 1.7.2 → 1.8.0-beta.1

package/{src/renderer/ssr → core/renderer}/md.renderer.ts

@@ -5,13 +5,14 @@
  * Generates Markdown strings for LLM consumption, text clients, curl.
  */
 
-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';
-import { resolveRecursively } from '../../util/widget-resolve.util.ts';
-import { parseWidgetBlocks, replaceWidgetBlocks } from '../../widget/widget.parser.ts';
+import type { RouteConfig, RouteInfo } from '../type/route.type.ts';
+import type { ComponentContext } from '../type/component.type.ts';
+import type { PageComponent } from '../component/page.component.ts';
+import type { Pipeline } from '../pipeline/pipeline.ts';
+import { DEFAULT_ROOT_ROUTE } from '../pipeline/pipeline.ts';
+import { STATUS_MESSAGES } from '../util/html.util.ts';
+import { resolveRecursively } from '../util/widget-resolve.util.ts';
+import { parseWidgetBlocks, replaceWidgetBlocks } from '../widget/widget.parser.ts';
 import { SsrRenderer, type SsrRendererOptions } from './ssr.renderer.ts';
 
 const BARE_SLOT_BLOCK = '```router-slot\n```';
@@ -20,17 +21,13 @@ function routerSlotBlock(pattern: string): string {
   return `\`\`\`router-slot\n{"pattern":"${pattern}"}\n\`\`\``;
 }
 
-/** Options for SSR Markdown Router */
-export type SsrMdRouterOptions = SsrRendererOptions;
+export type SsrMdRendererOptions = SsrRendererOptions;
 
-/**
- * SSR Markdown Router for server-side markdown rendering.
- */
-export class SsrMdRouter extends SsrRenderer {
+export class SsrMdRenderer extends SsrRenderer {
   protected override readonly label = 'SSR MD';
 
-  constructor(resolver: RouteResolver, options: SsrMdRouterOptions = {}) {
-    super(resolver, options);
+  constructor(pipeline: Pipeline, options: SsrMdRendererOptions = {}) {
+    super(pipeline, options);
   }
 
   protected override injectSlot(parent: string, child: string, parentPattern: string): string {
@@ -43,9 +40,6 @@ export class SsrMdRouter extends SsrRenderer {
       .trim();
   }
 
-  /**
-   * Render a single route's content to Markdown.
-   */
   protected override async renderRouteContent(
     routeInfo: RouteInfo,
     route: RouteConfig,
@@ -60,15 +54,14 @@ export class SsrMdRouter extends SsrRenderer {
     let content = rawContent;
 
     // Attribute bare router-slot blocks with this route's pattern
-    // (before widget resolution so widget-internal blocks are not affected)
     content = content.replaceAll(BARE_SLOT_BLOCK, routerSlotBlock(route.pattern));
 
-    // Resolve fenced widget blocks: call getData() + renderMarkdown()
+    // Resolve fenced widget blocks
     if (this.widgets) {
       content = await this.resolveWidgets(content, routeInfo);
     }
 
-    return { content, title };
+    return { content, ...(title !== undefined ? { title } : {}) };
   }
 
   protected override renderContent(
@@ -90,10 +83,6 @@ export class SsrMdRouter extends SsrRenderer {
     return `# Internal Server Error\n\nPath: \`${url.pathname}\``;
   }
 
-  /**
-   * Resolve fenced widget blocks in markdown content.
-   * Replaces ```widget:name blocks with rendered markdown output.
-   */
   private resolveWidgets(
     content: string,
     routeInfo: RouteInfo,
@@ -115,17 +104,17 @@ export class SsrMdRouter extends SsrRenderer {
           let files: { html?: string; md?: string } | undefined;
           const filePaths = this.widgetFiles[block.widgetName] ?? widget.files;
           if (filePaths) {
-            files = await this.core.loadWidgetFiles(filePaths);
+            files = await this.pipeline.loadFiles(filePaths);
           }
 
-          const baseContext = {
+          const baseContext: ComponentContext = {
             ...routeInfo,
             pathname: routeInfo.url.pathname,
             searchParams: routeInfo.url.searchParams,
-            files,
+            ...(files ? { files } : {}),
           };
-          const context = this.core.contextProvider
-            ? this.core.contextProvider(baseContext)
+          const context: ComponentContext = this.pipeline.contextProvider
+            ? this.pipeline.contextProvider(baseContext)
             : baseContext;
           const data = await widget.getData({ params: block.params, context });
           return widget.renderMarkdown({ data, params: block.params, context });
@@ -134,16 +123,8 @@ export class SsrMdRouter extends SsrRenderer {
         }
       },
       replaceWidgetBlocks,
+      0,
+      this.logger,
     );
   }
 }
-
-/**
- * Create SSR Markdown router.
- */
-export function createSsrMdRouter(
-  resolver: RouteResolver,
-  options?: SsrMdRouterOptions,
-): SsrMdRouter {
-  return new SsrMdRouter(resolver, options);
-}

package/{src/renderer/ssr → core/renderer}/ssr.renderer.ts

@@ -9,24 +9,17 @@ import type {
   MatchedRoute,
   RouteConfig,
   RouteInfo,
-} from '../../type/route.type.ts';
-import { logger } from '../../type/logger.type.ts';
-import type { ComponentContext } from '../../component/abstract.component.ts';
-import defaultPageComponent, { type PageComponent } from '../../component/page.component.ts';
-import {
-  assertSafeRedirect,
-  DEFAULT_ROOT_ROUTE,
-  RouteCore,
-  type RouteCoreOptions,
-} from '../../route/route.core.ts';
-import type { RouteResolver } from '../../route/route.resolver.ts';
-import type { WidgetRegistry } from '../../widget/widget.registry.ts';
-
-/** Base options for SSR renderers */
-export interface SsrRendererOptions extends RouteCoreOptions {
-  /** Widget registry for server-side widget rendering */
+} from '../type/route.type.ts';
+import type { ComponentContext } from '../type/component.type.ts';
+import type { Logger } from '../type/logger.type.ts';
+import defaultPageComponent, { type PageComponent } from '../component/page.component.ts';
+import { DEFAULT_ROOT_ROUTE, type Pipeline } from '../pipeline/pipeline.ts';
+import { assertSafeRedirect } from '../util/html.util.ts';
+import type { WidgetRegistry } from '../widget/widget.registry.ts';
+
+/** Options for SSR renderers. */
+export interface SsrRendererOptions {
   widgets?: WidgetRegistry;
-  /** Widget companion file paths, keyed by widget name */
   widgetFiles?: Record<string, { html?: string; md?: string; css?: string }>;
 }
 
@@ -34,13 +27,16 @@ export interface SsrRendererOptions extends RouteCoreOptions {
  * Abstract SSR renderer with shared routing pipeline.
  */
 export abstract class SsrRenderer {
-  protected core: RouteCore;
+  protected readonly pipeline: Pipeline;
   protected widgets: WidgetRegistry | null;
   protected widgetFiles: Record<string, { html?: string; md?: string; css?: string }>;
   protected abstract readonly label: string;
 
-  constructor(resolver: RouteResolver, options: SsrRendererOptions = {}) {
-    this.core = new RouteCore(resolver, options);
+  protected readonly logger: Logger;
+
+  constructor(pipeline: Pipeline, options: SsrRendererOptions = {}) {
+    this.pipeline = pipeline;
+    this.logger = pipeline.logger;
     this.widgets = options.widgets ?? null;
     this.widgetFiles = options.widgetFiles ?? {};
   }
@@ -52,17 +48,17 @@ export abstract class SsrRenderer {
     url: URL,
     signal?: AbortSignal,
   ): Promise<{ content: string; status: number; title?: string; redirect?: string }> {
-    const matched = this.core.match(url);
+    const matched = await this.pipeline.match(url);
 
     if (!matched) {
-      const statusPage = this.core.getStatusPage(404);
+      const statusPage = await this.pipeline.getStatusPage(404);
       if (statusPage) {
         try {
           const ri: RouteInfo = { url, params: {} };
           const result = await this.renderRouteContent(ri, statusPage, undefined, signal);
-          return { content: this.stripSlots(result.content), status: 404, title: result.title };
+          return { content: this.stripSlots(result.content), status: 404, ...(result.title !== undefined ? { title: result.title } : {}) };
         } catch (e) {
-          logger.error(
+          this.logger.error(
             `[${this.label}] Failed to render 404 status page for ${url.pathname}`,
             e instanceof Error ? e : undefined,
           );
@@ -73,7 +69,7 @@ export abstract class SsrRenderer {
 
     // Handle redirect
     if (matched.route.type === 'redirect') {
-      const module = await this.core.loadModule<{ default: { to: string; status?: number } }>(
+      const module = await this.pipeline.loadModule<{ default: { to: string; status?: number } }>(
         matched.route.modulePath,
       );
       const redirectConfig = module.default;
@@ -85,14 +81,14 @@ export abstract class SsrRenderer {
       };
     }
 
-    const routeInfo = this.core.toRouteInfo(matched, url);
+    const routeInfo = this.pipeline.toRouteInfo(matched, url);
 
     try {
       const { content, title } = await this.renderPage(routeInfo, matched, signal);
-      return { content, status: 200, title };
+      return { content, status: 200, ...(title !== undefined ? { title } : {}) };
     } catch (error) {
       if (error instanceof Response) {
-        const statusPage = this.core.getStatusPage(error.status);
+        const statusPage = await this.pipeline.getStatusPage(error.status);
         if (statusPage) {
           try {
             const ri: RouteInfo = { url, params: {} };
@@ -100,10 +96,10 @@ export abstract class SsrRenderer {
             return {
               content: this.stripSlots(result.content),
               status: error.status,
-              title: result.title,
+              ...(result.title !== undefined ? { title: result.title } : {}),
             };
           } catch (e) {
-            logger.error(
+            this.logger.error(
               `[${this.label}] Failed to render ${error.status} status page for ${url.pathname}`,
               e instanceof Error ? e : undefined,
             );
@@ -111,18 +107,18 @@ export abstract class SsrRenderer {
         }
         return { content: this.renderStatusPage(error.status, url), status: error.status };
       }
-      logger.error(
+      this.logger.error(
         `[${this.label}] Error rendering ${url.pathname}:`,
         error instanceof Error ? error : undefined,
       );
 
-      const boundary = this.core.findErrorBoundary(url.pathname);
+      const boundary = await this.pipeline.findErrorBoundary(url.pathname);
       if (boundary) {
         const result = await this.tryRenderErrorModule(boundary.modulePath, url, 'boundary');
         if (result) return result;
       }
 
-      const errorHandler = this.core.getErrorHandler();
+      const errorHandler = await this.pipeline.getErrorHandler();
       if (errorHandler) {
         const result = await this.tryRenderErrorModule(errorHandler.modulePath, url, 'handler');
         if (result) return result;
@@ -140,13 +136,12 @@ export abstract class SsrRenderer {
     matched: MatchedRoute,
     signal?: AbortSignal,
   ): Promise<{ content: string; title?: string }> {
-    const hierarchy = this.core.buildRouteHierarchy(matched.route.pattern);
+    const hierarchy = this.pipeline.buildRouteHierarchy(matched.route.pattern);
 
-    // Resolve routes for each hierarchy segment (skip missing / duplicate wildcard)
     const segments: { route: RouteConfig; isLeaf: boolean }[] = [];
     for (let i = 0; i < hierarchy.length; i++) {
       const routePattern = hierarchy[i];
-      let route = this.core.findRoute(routePattern);
+      let route = await this.pipeline.findRoute(routePattern);
 
       if (!route && routePattern === '/') {
         route = DEFAULT_ROOT_ROUTE;
@@ -158,14 +153,12 @@ export abstract class SsrRenderer {
       segments.push({ route, isLeaf: i === hierarchy.length - 1 });
     }
 
-    // Fire all renderRouteContent calls in parallel
     const results = await Promise.all(
       segments.map(({ route, isLeaf }) =>
         this.renderRouteContent(routeInfo, route, isLeaf, signal),
       ),
     );
 
-    // Sequential slot injection
     let result = '';
     let pageTitle: string | undefined;
     let lastRenderedPattern = '';
@@ -182,7 +175,7 @@ export abstract class SsrRenderer {
       } else {
         const injected = this.injectSlot(result, content, lastRenderedPattern);
         if (injected === result) {
-          logger.warn(
+          this.logger.warn(
             `[${this.label}] Route "${lastRenderedPattern}" has no <router-slot> ` +
               `for child route "${hierarchy[i]}" to render into. ` +
               `Add <router-slot></router-slot> to the parent template.`,
@@ -196,7 +189,7 @@ export abstract class SsrRenderer {
 
     result = this.stripSlots(result);
 
-    return { content: result, title: pageTitle };
+    return { content: result, ...(pageTitle !== undefined ? { title: pageTitle } : {}) };
   }
 
   protected abstract renderRouteContent(
@@ -216,25 +209,24 @@ export abstract class SsrRenderer {
     const files = route.files ?? {};
 
     const tsModule = files.ts ?? files.js;
-    const component: PageComponent = tsModule
-      ? (await this.core.loadModule<{ default: PageComponent }>(tsModule)).default
-      : defaultPageComponent;
+    const loadedModule = tsModule
+      ? await this.pipeline.loadModule<{ default: PageComponent }>(tsModule)
+      : undefined;
+    const component: PageComponent = loadedModule?.default ?? defaultPageComponent;
 
-    const context = await this.core.buildComponentContext(routeInfo, route, signal, isLeaf);
-    const data = await component.getData({ params: routeInfo.params, signal, context });
+    const context = await this.pipeline.buildContext(routeInfo, route, signal, isLeaf, loadedModule);
+    const data = await component.getData({ params: routeInfo.params, ...(signal ? { signal } : {}), context });
     const content = this.renderContent(component, { data, params: routeInfo.params, context });
     const title = component.getTitle({ data, params: routeInfo.params, context });
 
-    return { content, title };
+    return { content, ...(title !== undefined ? { title } : {}) };
   }
 
-  /** Render a component to the output format (HTML or Markdown). */
   protected abstract renderContent(
     component: PageComponent,
     args: PageComponent['RenderArgs'],
   ): string;
 
-  /** Render a component for error boundary/handler with minimal context. */
   protected renderComponent(
     component: PageComponent,
     data: unknown,
@@ -245,14 +237,13 @@ export abstract class SsrRenderer {
 
   private static readonly EMPTY_URL = new URL('http://error');
 
-  /** Try to load and render an error boundary or handler module. Returns null on failure. */
   private async tryRenderErrorModule(
     modulePath: string,
     url: URL,
     kind: 'boundary' | 'handler',
   ): Promise<{ content: string; status: number } | null> {
     try {
-      const module = await this.core.loadModule<{ default: PageComponent }>(modulePath);
+      const module = await this.pipeline.loadModule<{ default: PageComponent }>(modulePath);
       const component = module.default;
       const minCtx: ComponentContext = {
         url: SsrRenderer.EMPTY_URL,
@@ -264,7 +255,7 @@ export abstract class SsrRenderer {
       const content = this.renderComponent(component, data, minCtx);
       return { content, status: 500 };
     } catch (e) {
-      logger.error(
+      this.logger.error(
         `[${this.label}] Error ${kind} failed for ${url.pathname}`,
         e instanceof Error ? e : undefined,
       );
@@ -278,9 +269,7 @@ export abstract class SsrRenderer {
 
   protected abstract renderErrorPage(error: unknown, url: URL): string;
 
-  /** Inject child content into the slot owned by parentPattern. */
   protected abstract injectSlot(parent: string, child: string, parentPattern: string): string;
 
-  /** Strip all unconsumed slot placeholders from the final result. */
   protected abstract stripSlots(result: string): string;
 }

package/{src/route → core/router}/route.resolver.ts

@@ -5,29 +5,20 @@
  * 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. */
+/** Route lookup interface. Decouples matching algorithm from the server. */
 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;
 }

package/core/router/route.trie.ts

@@ -0,0 +1,175 @@
+/**
+ * Route Trie
+ *
+ * Default RouteResolver implementation. O(depth) route matching over
+ * the RouteNode tree.
+ *
+ * Walks the RouteNode tree directly — no conversion step, no internal state
+ * beyond the tree reference. Each URL segment is matched in order:
+ * static → dynamic (:param) → wildcard (:rest*). Backtracking handles
+ * cases where a dynamic path leads to a dead end but a wildcard at an
+ * ancestor would match.
+ *
+ * Static segment matching is case-sensitive, per RFC 3986.
+ */
+
+import type { RouteNode } from '../type/route-tree.type.ts';
+import type { ResolvedRoute, RouteResolver } from './route.resolver.ts';
+
+/**
+ * Default RouteResolver implementation.
+ * Walks the RouteNode tree directly — no conversion, no Maps.
+ */
+export class RouteTrie implements RouteResolver {
+  constructor(private readonly tree: RouteNode) {}
+
+  match(pathname: string): ResolvedRoute | undefined {
+    pathname = this.normalizePath(pathname);
+    if (pathname === '/') {
+      if (this.tree.files || this.tree.redirect) {
+        return { node: this.tree, pattern: '/', params: {} };
+      }
+      return undefined;
+    }
+    return this.walk(this.tree, this.splitSegments(pathname), 0, {}, '/');
+  }
+
+  findErrorBoundary(pathname: string): string | undefined {
+    pathname = this.normalizePath(pathname);
+    if (pathname === '/') return this.tree.errorBoundary;
+    return this.walkForBoundary(this.tree, this.splitSegments(pathname), 0, this.tree.errorBoundary);
+  }
+
+  findRoute(pattern: string): RouteNode | undefined {
+    if (pattern === '/') {
+      return (this.tree.files || this.tree.redirect) ? this.tree : undefined;
+    }
+    const segments = this.splitSegments(pattern);
+    let node = this.tree;
+    for (const segment of segments) {
+      let child: RouteNode | undefined;
+      if (segment.startsWith(':') && segment.endsWith('*')) {
+        child = node.wildcard?.child;
+      } else if (segment.startsWith(':')) {
+        child = node.dynamic?.child;
+      } else {
+        child = node.children?.[segment];
+      }
+      if (!child) return undefined;
+      node = child;
+    }
+    return (node.files || node.redirect) ? node : undefined;
+  }
+
+  // ── Private helpers ─────────────────────────────────────────────────
+
+  private safeDecode(segment: string): string {
+    try {
+      return decodeURIComponent(segment);
+    } catch {
+      return segment;
+    }
+  }
+
+  private splitSegments(pathname: string): string[] {
+    return pathname.substring(1).split('/');
+  }
+
+  private normalizePath(pathname: string): string {
+    if (pathname.length > 1 && pathname.endsWith('/')) {
+      pathname = pathname.slice(0, -1);
+    }
+    if (!pathname.startsWith('/')) {
+      pathname = '/' + pathname;
+    }
+    return pathname;
+  }
+
+  private walk(
+    node: RouteNode,
+    segments: string[],
+    index: number,
+    params: Record<string, string>,
+    pattern: string,
+  ): ResolvedRoute | undefined {
+    if (index === segments.length) {
+      if (node.files || node.redirect) {
+        return { node, pattern, params: { ...params } };
+      }
+      if (node.wildcard && (node.wildcard.child.files || node.wildcard.child.redirect)) {
+        const wp = pattern === '/' ? `/:${node.wildcard.param}*` : `${pattern}/:${node.wildcard.param}*`;
+        return {
+          node: node.wildcard.child,
+          pattern: wp,
+          params: { ...params, [node.wildcard.param]: '' },
+        };
+      }
+      return undefined;
+    }
+
+    const segment = segments[index];
+
+    // Static
+    const staticChild = node.children?.[segment];
+    if (staticChild) {
+      const childPattern = pattern === '/' ? `/${segment}` : `${pattern}/${segment}`;
+      const result = this.walk(staticChild, segments, index + 1, params, childPattern);
+      if (result) return result;
+    }
+
+    // Dynamic
+    if (node.dynamic) {
+      const { param, child } = node.dynamic;
+      params[param] = this.safeDecode(segment);
+      const childPattern = pattern === '/' ? `/:${param}` : `${pattern}/:${param}`;
+      const result = this.walk(child, segments, index + 1, params, childPattern);
+      if (result) return result;
+      delete params[param];
+    }
+
+    // Wildcard
+    if (node.wildcard && (node.wildcard.child.files || node.wildcard.child.redirect)) {
+      const { param, child } = node.wildcard;
+      let rest = this.safeDecode(segments[index]);
+      for (let i = index + 1; i < segments.length; i++) {
+        rest += '/' + this.safeDecode(segments[i]);
+      }
+      const wp = pattern === '/' ? `/:${param}*` : `${pattern}/:${param}*`;
+      return {
+        node: child,
+        pattern: wp,
+        params: { ...params, [param]: rest },
+      };
+    }
+
+    return undefined;
+  }
+
+  private walkForBoundary(
+    node: RouteNode,
+    segments: string[],
+    index: number,
+    deepest: string | undefined,
+  ): string | undefined {
+    if (index === segments.length) {
+      return node.errorBoundary ?? deepest;
+    }
+
+    const segment = segments[index];
+
+    const staticChild = node.children?.[segment];
+    if (staticChild) {
+      return this.walkForBoundary(staticChild, segments, index + 1, staticChild.errorBoundary ?? deepest);
+    }
+
+    if (node.dynamic) {
+      return this.walkForBoundary(node.dynamic.child, segments, index + 1, node.dynamic.child.errorBoundary ?? deepest);
+    }
+
+    if (node.wildcard) {
+      return node.wildcard.child.errorBoundary ?? deepest;
+    }
+
+    return deepest;
+  }
+}

package/core/runtime/abstract.runtime.ts

@@ -0,0 +1,47 @@
+/**
+ * Abstract Runtime
+ *
+ * Storage contract. Speaks Request/Response.
+ * Concrete implementations decide how to store, cache, scan, and serve.
+ *
+ * Three access patterns:
+ * - handle() — raw passthrough
+ * - query()  — read (Response or string)
+ * - command() — write/delete
+ */
+
+export type FetchParams = Parameters<typeof fetch>;
+export type FetchReturn = ReturnType<typeof fetch>;
+
+/** Well-known manifest paths (convention between Runtime and consumers). */
+export const ROUTES_MANIFEST_PATH = '/routes.manifest.json';
+export const WIDGETS_MANIFEST_PATH = '/widgets.manifest.json';
+export const ELEMENTS_MANIFEST_PATH = '/elements.manifest.json';
+
+export abstract class Runtime {
+  /** Raw passthrough — same signature as fetch(). */
+  abstract handle(resource: FetchParams[0], init?: FetchParams[1]): FetchReturn;
+
+  /** Read. Returns Response, or string with { as: 'text' }. */
+  abstract query(
+    resource: FetchParams[0],
+    options: FetchParams[1] & { as: 'text' },
+  ): Promise<string>;
+  abstract query(
+    resource: FetchParams[0],
+    options?: FetchParams[1],
+  ): FetchReturn;
+
+  /** Write (PUT) or delete (DELETE). */
+  abstract command(resource: FetchParams[0], options?: FetchParams[1]): FetchReturn;
+
+  /** Dynamically import a module from storage. */
+  loadModule(_path: string): Promise<unknown> {
+    throw new Error(`loadModule not implemented for ${this.constructor.name}`);
+  }
+
+  /** Transpile TypeScript to JavaScript. */
+  transpile(_source: string): Promise<string> {
+    throw new Error(`transpile not implemented for ${this.constructor.name}`);
+  }
+}