@emkodev/emroute 1.7.3 → 1.8.0-beta.1

package/README.md

@@ -145,7 +145,7 @@ Pick your runtime: [Bun](doc/01a-setup-bun.md) | [Node](doc/01b-setup-node.md) |
 - [Routing](doc/04-routing.md) — dynamic segments, catch-all, redirects
 - [Nesting](doc/05-nesting.md) — layouts, slots, passthrough pages, tips and tricks
 - [Widgets](doc/06-widgets.md) — interactive islands with data lifecycle
-- [Server](doc/07-server.md) — `createEmrouteServer`, composition, static files
+- [Server](doc/07-server.md) — `Emroute.create`, composition, static files
 - [Markdown renderers](doc/08-markdown-renderer.md) — pluggable parser interface and setup
 - [Runtime](doc/09-runtime.md) — abstract runtime, UniversalFsRuntime, BunFsRuntime, BunSqliteRuntime
 - [SPA modes](doc/10-spa-mode.md) — none, leaf, root, only

package/core/component/abstract.component.ts

@@ -0,0 +1,74 @@
+/**
+ * Component Base Class
+ *
+ * Everything is a Component: pages and widgets.
+ * Components render differently based on context:
+ * - /md/* → Markdown (LLMs, text clients)
+ * - /html/* → Pre-rendered HTML (SSR)
+ * - SPA → Hydrated custom elements
+ */
+
+import type { ComponentContext } from '../type/component.type.ts';
+import { escapeHtml } from '../util/html.util.ts';
+
+export abstract class Component<
+  TParams = unknown,
+  TData = unknown,
+  TContext extends ComponentContext = ComponentContext,
+> {
+  declare readonly DataArgs: {
+    params: TParams;
+    signal?: AbortSignal;
+    context: TContext;
+  };
+
+  declare readonly RenderArgs: {
+    data: TData | null;
+    params: TParams;
+    context: TContext;
+  };
+
+  abstract readonly name: string;
+
+  /** Host element reference, set by ComponentElement in the browser. */
+  element?: HTMLElement | undefined;
+
+  /** Associated file paths for pre-loaded content (html, md, css). */
+  readonly files?: { html?: string; md?: string; css?: string };
+
+  /**
+   * When true, SSR serializes the getData() result into the element's
+   * light DOM so the client can access it immediately in hydrate()
+   * without re-fetching.
+   */
+  readonly exposeSsrData?: boolean;
+
+  abstract getData(args: this['DataArgs']): Promise<TData | null>;
+  abstract renderMarkdown(args: this['RenderArgs']): string;
+
+  renderHTML(args: this['RenderArgs']): string {
+    if (args.data === null) {
+      return `<div data-component="${this.name}">Loading...</div>`;
+    }
+    const markdown = this.renderMarkdown({
+      data: args.data,
+      params: args.params,
+      context: args.context,
+    });
+    return `<div data-component="${this.name}" data-markdown>${escapeHtml(markdown)}</div>`;
+  }
+
+  hydrate?(args: this['RenderArgs']): void;
+  destroy?(): void;
+  validateParams?(params: TParams): string | undefined;
+
+  renderError(args: { error: unknown; params: TParams }): string {
+    const msg = args.error instanceof Error ? args.error.message : String(args.error);
+    return `<div data-component="${this.name}">Error: ${escapeHtml(msg)}</div>`;
+  }
+
+  renderMarkdownError(error: unknown): string {
+    const msg = error instanceof Error ? error.message : String(error);
+    return `> **Error** (\`${this.name}\`): ${msg}`;
+  }
+}

package/{src → core}/component/page.component.ts

@@ -1,7 +1,7 @@
 /**
  * Page Component
  *
- * Page component — params come from URL, context carries file content.
+ * Params come from URL, context carries file content.
  *
  * Default implementations follow the fallback table:
  * - renderHTML: html file → md via <mark-down> → <router-slot /> (non-leaf only)
@@ -9,7 +9,8 @@
  * - getData: no-op (returns null)
  */
 
-import { Component, type ComponentContext } from './abstract.component.ts';
+import { Component } from './abstract.component.ts';
+import type { ComponentContext } from '../type/component.type.ts';
 import { escapeHtml } from '../util/html.util.ts';
 
 export class PageComponent<
@@ -18,42 +19,14 @@ export class PageComponent<
   TContext extends ComponentContext = ComponentContext,
 > extends Component<TParams, TData, TContext> {
   override readonly name: string = 'page';
-
-  /** Route pattern this page handles (optional — set by subclasses) */
   readonly pattern?: string;
 
-  /**
-   * Fetch or compute page data. Override in subclasses.
-   * Default: returns null (no data needed).
-   *
-   * @example
-   * ```ts
-   * override getData({ params, context }: this['DataArgs']) {
-   *   return fetch(`/api/${params.id}`, { signal: context?.signal });
-   * }
-   * ```
-   */
   override getData(
     _args: this['DataArgs'],
   ): Promise<TData | null> {
     return Promise.resolve(null);
   }
 
-  /**
-   * Render page as HTML.
-   *
-   * Fallback chain:
-   * 1. html file content from context
-   * 2. md file content wrapped in `<mark-down>`
-   * 3. `<router-slot />` (bare slot for child routes)
-   *
-   * @example
-   * ```ts
-   * override renderHTML({ data, params, context }: this['RenderArgs']) {
-   *   return `<h1>${params.id}</h1><p>${context?.files?.html ?? ''}</p>`;
-   * }
-   * ```
-   */
   override renderHTML(
     args: this['RenderArgs'],
   ): string {
@@ -72,12 +45,6 @@ export class PageComponent<
     }
 
     if (files?.md) {
-      // HOTFIX: skip external <router-slot> when markdown already defines one
-      // via ```router-slot fenced block. Without this, SPA mode produces two
-      // slots with the same pattern — one inside <mark-down> (from the fenced
-      // block) and one outside (from this suffix). SSR strips empty duplicates
-      // via stripSlots, but SPA has no equivalent cleanup.
-      // See: issues/pending/spa-duplicate-router-slot.issue.md
       const hasSlot = files.md.includes('```router-slot');
       const slot = args.context.isLeaf || hasSlot ? '' : '\n<router-slot></router-slot>';
       return `${style}<mark-down>${escapeHtml(files.md)}</mark-down>${slot}`;
@@ -86,20 +53,6 @@ export class PageComponent<
     return args.context.isLeaf ? '' : '<router-slot></router-slot>';
   }
 
-  /**
-   * Render page as Markdown.
-   *
-   * Fallback chain:
-   * 1. md file content from context
-   * 2. `` ```router-slot\n``` `` (slot placeholder in markdown — newline required)
-   *
-   * @example
-   * ```ts
-   * override renderMarkdown({ data, params, context }: this['RenderArgs']) {
-   *   return `# ${params.id}\n\n${context?.files?.md ?? ''}`;
-   * }
-   * ```
-   */
   override renderMarkdown(
     args: this['RenderArgs'],
   ): string {
@@ -112,17 +65,6 @@ export class PageComponent<
     return args.context.isLeaf ? '' : '```router-slot\n```';
   }
 
-  /**
-   * Page title. Override in subclasses.
-   * Default: undefined (no title).
-   *
-   * @example
-   * ```ts
-   * override getTitle({ data, params }: this['RenderArgs']) {
-   *   return `Project ${params.id}`;
-   * }
-   * ```
-   */
   getTitle(
     _args: this['RenderArgs'],
   ): string | undefined {

package/core/component/widget.component.ts

@@ -0,0 +1,54 @@
+/**
+ * Widget Component
+ *
+ * Embeddable unit within page content. Everything reusable that is not
+ * a page is a Widget. Widgets render across all contexts (HTML, Markdown, SPA)
+ * and are resolved by name via WidgetRegistry.
+ *
+ * Default rendering fallback chains (parallel to PageComponent):
+ * - renderHTML:     html file → md file in <mark-down> → base Component default
+ * - renderMarkdown: md file → ''
+ */
+
+import { Component } from './abstract.component.ts';
+import type { ComponentContext } from '../type/component.type.ts';
+import { escapeHtml, scopeWidgetCss } from '../util/html.util.ts';
+
+export abstract class WidgetComponent<
+  TParams = unknown,
+  TData = unknown,
+  TContext extends ComponentContext = ComponentContext,
+> extends Component<TParams, TData, TContext> {
+  override renderHTML(
+    args: this['RenderArgs'],
+  ): string {
+    const files = args.context.files;
+    const style = files?.css ? `<style>${scopeWidgetCss(files.css, this.name)}</style>\n` : '';
+
+    if (files?.html) {
+      return style + files.html;
+    }
+
+    if (files?.md) {
+      return `${style}<mark-down>${escapeHtml(files.md)}</mark-down>`;
+    }
+
+    if (style) {
+      return style + super.renderHTML(args);
+    }
+
+    return super.renderHTML(args);
+  }
+
+  override renderMarkdown(
+    args: this['RenderArgs'],
+  ): string {
+    const files = args.context.files;
+
+    if (files?.md) {
+      return files.md;
+    }
+
+    return '';
+  }
+}

package/core/pipeline/pipeline.ts

@@ -0,0 +1,224 @@
+/**
+ * Pipeline
+ *
+ * Orchestration layer between Router, Runtime, and Component.
+ *
+ * Owns:
+ * - Route matching (reads manifest from Runtime, walks RouteNode tree)
+ * - Module loading (delegates to Runtime)
+ * - Companion file reading (delegates to Runtime)
+ * - ComponentContext building
+ * - Route hierarchy construction
+ *
+ * Does NOT own:
+ * - Rendering (that's Renderer)
+ * - HTTP routing / base paths (that's Server)
+ * - Storage I/O (that's Runtime)
+ * - Navigation events (that's the browser adapter)
+ */
+
+import { RouteTrie } from '../router/route.trie.ts';
+import type { RouteNode } from '../type/route-tree.type.ts';
+import type { RouteConfig, MatchedRoute, RouteInfo } from '../type/route.type.ts';
+import type { ComponentContext, ContextProvider, FileContents } from '../type/component.type.ts';
+import type { Runtime } from '../runtime/abstract.runtime.ts';
+import { ROUTES_MANIFEST_PATH } from '../runtime/abstract.runtime.ts';
+import { type Logger, defaultLogger } from '../type/logger.type.ts';
+
+/** 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 matched route data. */
+function toRouteConfig(node: RouteNode, pattern: string): RouteConfig {
+  return {
+    pattern,
+    type: node.redirect ? 'redirect' : 'page',
+    modulePath: node.redirect ?? node.files?.ts ?? node.files?.js ?? node.files?.html ?? node.files?.md ?? '',
+    ...(node.files ? { files: node.files } : {}),
+  };
+}
+
+/** Pipeline configuration. */
+export interface PipelineOptions {
+  runtime: Runtime;
+  contextProvider?: ContextProvider;
+  /** Pre-bundled module loaders (browser boot passes these). */
+  moduleLoaders?: Record<string, () => Promise<unknown>>;
+  logger?: Logger;
+}
+
+export class Pipeline {
+  private readonly runtime: Runtime;
+  readonly contextProvider: ContextProvider | undefined;
+  readonly logger: Logger;
+  private readonly moduleLoaders: Record<string, () => Promise<unknown>>;
+
+  constructor(options: PipelineOptions) {
+    this.runtime = options.runtime;
+    this.contextProvider = options.contextProvider;
+    this.logger = options.logger ?? defaultLogger;
+    this.moduleLoaders = options.moduleLoaders ?? {};
+  }
+
+  // ── Route resolver (from Runtime) ───────────────────────────────────
+
+  private async getResolver(): Promise<RouteTrie> {
+    const response = await this.runtime.query(ROUTES_MANIFEST_PATH);
+    const tree: RouteNode = response.status === 404 ? {} : await response.json();
+    return new RouteTrie(tree);
+  }
+
+  // ── Matching ────────────────────────────────────────────────────────
+
+  async match(url: URL): Promise<MatchedRoute | undefined> {
+    const resolver = await this.getResolver();
+    const resolved = resolver.match(url.pathname);
+    if (resolved) {
+      return { route: toRouteConfig(resolved.node, resolved.pattern), params: resolved.params };
+    }
+    if (url.pathname === '/' || url.pathname === '') {
+      return { route: DEFAULT_ROOT_ROUTE, params: {} };
+    }
+    return undefined;
+  }
+
+  async findRoute(pattern: string): Promise<RouteConfig | undefined> {
+    const resolver = await this.getResolver();
+    const node = resolver.findRoute(pattern);
+    if (!node) return undefined;
+    return toRouteConfig(node, pattern);
+  }
+
+  async findErrorBoundary(pathname: string): Promise<{ pattern: string; modulePath: string } | undefined> {
+    const resolver = await this.getResolver();
+    const modulePath = resolver.findErrorBoundary(pathname);
+    if (!modulePath) return undefined;
+    return { pattern: pathname, modulePath };
+  }
+
+  async getStatusPage(status: number): Promise<RouteConfig | undefined> {
+    const resolver = await this.getResolver();
+    const node = resolver.findRoute(`/${status}`);
+    if (!node) return undefined;
+    return toRouteConfig(node, `/${status}`);
+  }
+
+  async getErrorHandler(): Promise<RouteConfig | undefined> {
+    const resolver = await this.getResolver();
+    const modulePath = resolver.findErrorBoundary('/');
+    if (!modulePath) return undefined;
+    return { pattern: '/', type: 'error', modulePath };
+  }
+
+  // ── Route hierarchy ────────────────────────────────────────────────
+
+  buildRouteHierarchy(pattern: string): string[] {
+    if (pattern === '/') return ['/'];
+    const segments = pattern.split('/').filter(Boolean);
+    const hierarchy: string[] = ['/'];
+    let current = '';
+    for (const segment of segments) {
+      current += '/' + segment;
+      hierarchy.push(current);
+    }
+    return hierarchy;
+  }
+
+  // ── Module loading ─────────────────────────────────────────────────
+
+  async loadModule<T>(modulePath: string): Promise<T> {
+    const loader = this.moduleLoaders[modulePath];
+    if (loader) {
+      return await loader() as T;
+    }
+    const abs = modulePath.startsWith('/') ? modulePath : '/' + modulePath;
+    return await this.runtime.loadModule(abs) as T;
+  }
+
+  /**
+   * Get inlined `__files` from a loaded module (merged module pattern).
+   */
+  getModuleFiles(mod: unknown): FileContents | undefined {
+    if (!mod || typeof mod !== 'object') return undefined;
+    const files = (mod as Record<string, unknown>).__files;
+    if (!files || typeof files !== 'object') return undefined;
+    return files as FileContents;
+  }
+
+  // ── File loading ───────────────────────────────────────────────────
+
+  async loadFiles(
+    files: { html?: string; md?: string; css?: string },
+  ): Promise<FileContents> {
+    const load = async (path: string): Promise<string | undefined> => {
+      const abs = path.startsWith('/') ? path : '/' + path;
+      try {
+        return await this.runtime.query(abs, { as: 'text' });
+      } catch (e) {
+        console.warn(
+          `[Pipeline] Failed to load file ${path}:`,
+          e instanceof Error ? e.message : e,
+        );
+        return undefined;
+      }
+    };
+
+    const [html, md, css] = await Promise.all([
+      files.html ? load(files.html) : undefined,
+      files.md ? load(files.md) : undefined,
+      files.css ? load(files.css) : undefined,
+    ]);
+
+    const result: FileContents = {};
+    if (html !== undefined) result.html = html;
+    if (md !== undefined) result.md = md;
+    if (css !== undefined) result.css = css;
+    return result;
+  }
+
+  // ── Context building ───────────────────────────────────────────────
+
+  toRouteInfo(matched: MatchedRoute, url: URL): RouteInfo {
+    return { url, params: matched.params };
+  }
+
+  async buildContext(
+    routeInfo: RouteInfo,
+    route: RouteConfig,
+    signal?: AbortSignal,
+    isLeaf?: boolean,
+    loadedModule?: unknown,
+  ): Promise<ComponentContext> {
+    const rf = route.files;
+
+    // Try inlined __files from merged module first
+    const inlined = loadedModule ? this.getModuleFiles(loadedModule) : undefined;
+
+    let files: FileContents;
+    if (inlined) {
+      files = inlined;
+    } else if (rf) {
+      const filePaths: { html?: string; md?: string; css?: string } = {};
+      if (rf.html) filePaths.html = rf.html;
+      if (rf.md) filePaths.md = rf.md;
+      if (rf.css) filePaths.css = rf.css;
+      files = await this.loadFiles(filePaths);
+    } else {
+      files = {};
+    }
+
+    const base: ComponentContext = {
+      ...routeInfo,
+      pathname: routeInfo.url.pathname,
+      searchParams: routeInfo.url.searchParams,
+      files,
+      ...(signal ? { signal } : {}),
+      ...(isLeaf !== undefined ? { isLeaf } : {}),
+    };
+    return this.contextProvider ? this.contextProvider(base) : base;
+  }
+}

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

@@ -6,31 +6,27 @@
  * Expands <mark-down> tags server-side when a markdown renderer is provided.
  */
 
-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';
-import { escapeHtml, STATUS_MESSAGES, unescapeHtml } from '../../util/html.util.ts';
-import { resolveWidgetTags } from '../../util/widget-resolve.util.ts';
+import type { RouteConfig, RouteInfo } from '../type/route.type.ts';
+import type { MarkdownRenderer } from '../type/markdown.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 { escapeHtml, STATUS_MESSAGES, unescapeHtml } from '../util/html.util.ts';
+import { resolveWidgetTags } from '../util/widget-resolve.util.ts';
 import { SsrRenderer, type SsrRendererOptions } from './ssr.renderer.ts';
 
-/** Options for SSR HTML Router */
-export interface SsrHtmlRouterOptions extends SsrRendererOptions {
-  /** Markdown renderer for server-side <mark-down> expansion */
+/** Options for SSR HTML Renderer. */
+export interface SsrHtmlRendererOptions extends SsrRendererOptions {
   markdownRenderer?: MarkdownRenderer;
 }
 
-/**
- * SSR HTML Router for server-side rendering.
- */
-export class SsrHtmlRouter extends SsrRenderer {
+export class SsrHtmlRenderer extends SsrRenderer {
   protected override readonly label = 'SSR HTML';
   private markdownRenderer: MarkdownRenderer | null;
   private markdownReady: Promise<void> | null = null;
 
-  constructor(resolver: RouteResolver, options: SsrHtmlRouterOptions = {}) {
-    super(resolver, options);
+  constructor(pipeline: Pipeline, options: SsrHtmlRendererOptions = {}) {
+    super(pipeline, options);
     this.markdownRenderer = options.markdownRenderer ?? null;
 
     if (this.markdownRenderer?.init) {
@@ -50,9 +46,6 @@ export class SsrHtmlRouter extends SsrRenderer {
     return result.replace(/<router-slot[^>]*><\/router-slot>/g, '');
   }
 
-  /**
-   * Render a single route's content.
-   */
   protected override async renderRouteContent(
     routeInfo: RouteInfo,
     route: RouteConfig,
@@ -66,14 +59,12 @@ export class SsrHtmlRouter extends SsrRenderer {
     const { content: rawContent, title } = await this.loadRouteContent(routeInfo, route, isLeaf, signal);
     let content = rawContent;
 
-    // Expand <mark-down> tags server-side
     content = await this.expandMarkdown(content);
 
-    // Attribute bare <router-slot> tags with this route's pattern (before widget
-    // resolution so widget-internal slots inside <template> are not affected)
+    // Attribute bare <router-slot> tags with this route's pattern
     content = this.attributeSlots(content, route.pattern);
 
-    // Resolve <widget-*> tags: call getData() + renderHTML(), inject ssr attribute
+    // Resolve <widget-*> tags
     if (this.widgets) {
       content = await resolveWidgetTags(
         content,
@@ -81,13 +72,14 @@ export class SsrHtmlRouter extends SsrRenderer {
         routeInfo,
         (name, declared) => {
           const files = this.widgetFiles[name] ?? declared;
-          return files ? this.core.loadWidgetFiles(files) : Promise.resolve({});
+          return files ? this.pipeline.loadFiles(files) : Promise.resolve({});
         },
-        this.core.contextProvider,
+        this.pipeline.contextProvider,
+        this.logger,
       );
     }
 
-    return { content, ...(title != null ? { title } : {}) };
+    return { content, ...(title !== undefined ? { title } : {}) };
   }
 
   protected override renderContent(
@@ -117,7 +109,6 @@ export class SsrHtmlRouter extends SsrRenderer {
     `;
   }
 
-  /** Add pattern attribute to bare <router-slot> tags. */
   private attributeSlots(content: string, routePattern: string): string {
     return content.replace(
       /<router-slot(?![^>]*\bpattern=)([^>]*)><\/router-slot>/g,
@@ -125,10 +116,6 @@ export class SsrHtmlRouter extends SsrRenderer {
     );
   }
 
-  /**
-   * Expand <mark-down> tags by rendering markdown to HTML server-side.
-   * Leaves content unchanged if no markdown renderer is configured.
-   */
   private async expandMarkdown(content: string): Promise<string> {
     if (!this.markdownRenderer) return content;
     if (!content.includes('<mark-down>')) return content;
@@ -138,24 +125,11 @@ export class SsrHtmlRouter extends SsrRenderer {
     }
 
     const renderer = this.markdownRenderer;
-
-    // Match <mark-down>escaped content</mark-down>
     const pattern = /<mark-down>([\s\S]*?)<\/mark-down>/g;
 
     return content.replace(pattern, (_match, escaped: string) => {
       const markdown = unescapeHtml(escaped);
-      const rendered = renderer.render(markdown);
-      return rendered;
+      return renderer.render(markdown);
     });
   }
 }
-
-/**
- * Create SSR HTML router.
- */
-export function createSsrHtmlRouter(
-  resolver: RouteResolver,
-  options?: SsrHtmlRouterOptions,
-): SsrHtmlRouter {
-  return new SsrHtmlRouter(resolver, options);
-}