@emkodev/emroute 1.7.3 → 1.8.0-beta.2

package/core/server/emroute.server.ts

@@ -0,0 +1,324 @@
+/**
+ * Emroute
+ *
+ * Framework entry point. Reads manifests from Runtime,
+ * builds Pipeline + Renderers, handles Request → Response.
+ */
+
+import type { WidgetManifestEntry } from '../type/widget.type.ts';
+import type { WidgetComponent } from '../component/widget.component.ts';
+import type { Runtime } from '../runtime/abstract.runtime.ts';
+import { Pipeline } from '../pipeline/pipeline.ts';
+import { SsrHtmlRenderer } from '../renderer/html.renderer.ts';
+import { SsrMdRenderer } from '../renderer/md.renderer.ts';
+import { WidgetRegistry } from '../widget/widget.registry.ts';
+import { escapeHtml } from '../util/html.util.ts';
+import { rewriteMdLinks } from '../util/md.util.ts';
+import type { RouteNode } from '../type/route-tree.type.ts';
+import type { MarkdownRenderer } from '../type/markdown.type.ts';
+import type { SpaMode } from '../type/widget.type.ts';
+import type { ContextProvider } from '../type/component.type.ts';
+import {
+  ROUTES_MANIFEST_PATH,
+  WIDGETS_MANIFEST_PATH,
+} from '../runtime/abstract.runtime.ts';
+export const DEFAULT_BASE_PATH = { html: '/html', md: '/md', app: '/app' };
+export type BasePath = Record<keyof typeof DEFAULT_BASE_PATH, string>;
+
+export class Emroute {
+  readonly htmlRenderer: SsrHtmlRenderer | null;
+  readonly mdRenderer: SsrMdRenderer | null;
+  readonly shell: string;
+
+  private constructor(
+    htmlRenderer: SsrHtmlRenderer | null,
+    mdRenderer: SsrMdRenderer | null,
+    shell: string,
+    private readonly runtime: Runtime,
+    private readonly htmlBase: string,
+    private readonly mdBase: string,
+    private readonly appBase: string,
+    private readonly spa: string,
+    private readonly title: string,
+  ) {
+    this.htmlRenderer = htmlRenderer;
+    this.mdRenderer = mdRenderer;
+    this.shell = shell;
+  }
+
+  static async create(
+    config: {
+      routeTree?: RouteNode;
+      widgets?: WidgetRegistry;
+      spa?: SpaMode;
+      basePath?: BasePath;
+      title?: string;
+      markdownRenderer?: MarkdownRenderer;
+      extendContext?: ContextProvider;
+      moduleLoaders?: Record<string, () => Promise<unknown>>;
+    },
+    runtime: Runtime,
+  ): Promise<Emroute> {
+    const { spa = 'root' } = config;
+    const { html: htmlBase, md: mdBase, app: appBase } = config.basePath ?? DEFAULT_BASE_PATH;
+
+    // ── Verify route manifest exists ──────────────────────────────────
+
+    const manifestResponse = await runtime.query(ROUTES_MANIFEST_PATH);
+    if (manifestResponse.status === 404 && !config.routeTree) {
+      throw new Error(
+        `[emroute] ${ROUTES_MANIFEST_PATH} not found in runtime. ` +
+          'Provide routeTree in config or ensure the runtime produces it.',
+      );
+    }
+
+    if (config.routeTree && manifestResponse.status === 404) {
+      await runtime.command(ROUTES_MANIFEST_PATH, {
+        body: JSON.stringify(config.routeTree),
+      });
+    }
+
+    // ── Pipeline ──────────────────────────────────────────────────────
+
+    const pipeline = new Pipeline({
+      runtime,
+      ...(config.extendContext ? { contextProvider: config.extendContext } : {}),
+      ...(config.moduleLoaders ? { moduleLoaders: config.moduleLoaders } : {}),
+    });
+
+    // ── Widgets ───────────────────────────────────────────────────────
+
+    let widgets: WidgetRegistry | undefined = config.widgets;
+
+    const widgetsResponse = await runtime.query(WIDGETS_MANIFEST_PATH);
+    if (widgetsResponse.status !== 404) {
+      const entries: WidgetManifestEntry[] = await widgetsResponse.json();
+      if (!config.widgets) {
+        widgets = await Emroute.importWidgets(entries, runtime);
+      }
+    }
+
+    // ── Renderers ─────────────────────────────────────────────────────
+
+    let ssrHtmlRenderer: SsrHtmlRenderer | null = null;
+    let ssrMdRenderer: SsrMdRenderer | null = null;
+
+    if (spa !== 'only') {
+      ssrHtmlRenderer = new SsrHtmlRenderer(pipeline, {
+        ...(config.markdownRenderer ? { markdownRenderer: config.markdownRenderer } : {}),
+        ...(widgets ? { widgets } : {}),
+      });
+
+      ssrMdRenderer = new SsrMdRenderer(pipeline, {
+        ...(widgets ? { widgets } : {}),
+      });
+    }
+
+    // ── HTML shell ────────────────────────────────────────────────────
+
+    const title = config.title ?? 'emroute';
+    const shellBase = (spa === 'root' || spa === 'only') ? appBase : htmlBase;
+    let shell = await Emroute.resolveShell(runtime, title, shellBase);
+
+    if ((await runtime.query('/main.css')).status !== 404) {
+      shell = shell.replace('</head>', '  <link rel="stylesheet" href="/main.css">\n</head>');
+    }
+
+    return new Emroute(
+      ssrHtmlRenderer,
+      ssrMdRenderer,
+      shell,
+      runtime,
+      htmlBase,
+      mdBase,
+      appBase,
+      spa,
+      title,
+    );
+  }
+
+  // ── handleRequest ─────────────────────────────────────────────────
+
+  async handleRequest(req: Request): Promise<Response | null> {
+    const url = new URL(req.url);
+    const pathname = url.pathname;
+
+    const mdPrefix = this.mdBase + '/';
+    const htmlPrefix = this.htmlBase + '/';
+    const appPrefix = this.appBase + '/';
+
+    // SSR Markdown: /md/*
+    if (
+      this.mdRenderer &&
+      (pathname.startsWith(mdPrefix) || pathname === this.mdBase)
+    ) {
+      const routePath = pathname === this.mdBase ? '/' : pathname.slice(this.mdBase.length);
+      if (routePath.length > 1 && routePath.endsWith('/')) {
+        const canonical = this.mdBase + routePath.slice(0, -1) + (url.search || '');
+        return Response.redirect(new URL(canonical, url.origin), 301);
+      }
+      try {
+        const routeUrl = new URL(routePath + url.search, url.origin);
+        const { content, status, redirect } = await this.mdRenderer.render(routeUrl, req.signal);
+        if (redirect) {
+          const target = redirect.startsWith('/') ? this.mdBase + redirect : redirect;
+          return Response.redirect(new URL(target, url.origin), status);
+        }
+        return new Response(rewriteMdLinks(content, this.mdBase, [this.mdBase, this.htmlBase]), {
+          status,
+          headers: { 'Content-Type': 'text/markdown; charset=utf-8; variant=CommonMark' },
+        });
+      } catch (e) {
+        console.error(`[emroute] Error rendering ${pathname}:`, e);
+        return new Response('Internal Server Error', { status: 500 });
+      }
+    }
+
+    // SSR HTML: /html/*
+    if (
+      this.htmlRenderer &&
+      (pathname.startsWith(htmlPrefix) || pathname === this.htmlBase)
+    ) {
+      const routePath = pathname === this.htmlBase ? '/' : pathname.slice(this.htmlBase.length);
+      if (routePath.length > 1 && routePath.endsWith('/')) {
+        const canonical = this.htmlBase + routePath.slice(0, -1) + (url.search || '');
+        return Response.redirect(new URL(canonical, url.origin), 301);
+      }
+      try {
+        const routeUrl = new URL(routePath + url.search, url.origin);
+        const result = await this.htmlRenderer.render(routeUrl, req.signal);
+        if (result.redirect) {
+          const target = result.redirect.startsWith('/') ? this.htmlBase + result.redirect : result.redirect;
+          return Response.redirect(new URL(target, url.origin), result.status);
+        }
+        const ssrTitle = result.title ?? this.title;
+        const html = Emroute.injectSsrContent(this.shell, result.content, ssrTitle, pathname);
+        return new Response(html, {
+          status: result.status,
+          headers: { 'Content-Type': 'text/html; charset=utf-8' },
+        });
+      } catch (e) {
+        console.error(`[emroute] Error rendering ${pathname}:`, e);
+        return new Response('Internal Server Error', { status: 500 });
+      }
+    }
+
+    // /app/*
+    if (pathname.startsWith(appPrefix) || pathname === this.appBase) {
+      return new Response(this.shell, {
+        status: 200,
+        headers: { 'Content-Type': 'text/html; charset=utf-8' },
+      });
+    }
+
+    // Unhandled SSR paths in 'only' mode — serve shell
+    if (
+      pathname.startsWith(htmlPrefix) || pathname === this.htmlBase ||
+      pathname.startsWith(mdPrefix) || pathname === this.mdBase
+    ) {
+      return new Response(this.shell, {
+        status: 200,
+        headers: { 'Content-Type': 'text/html; charset=utf-8' },
+      });
+    }
+
+    // Static files
+    const lastSegment = pathname.split('/').pop() ?? '';
+    if (lastSegment.includes('.')) {
+      const fileResponse = await this.runtime.handle(pathname);
+      if (fileResponse.status === 200) return fileResponse;
+      return null;
+    }
+
+    // Bare paths → redirect
+    const base = (this.spa === 'root' || this.spa === 'only') ? this.appBase : this.htmlBase;
+    const bare = pathname === '/' ? '' : pathname.slice(1).replace(/\/$/, '');
+    return Response.redirect(new URL(`${base}/${bare}`, url.origin), 302);
+  }
+
+  // ── Private static helpers ────────────────────────────────────────
+
+  private static extractWidgetExport(
+    mod: Record<string, unknown>,
+  ): WidgetComponent | null {
+    for (const value of Object.values(mod)) {
+      if (!value) continue;
+      if (typeof value === 'object' && 'getData' in value) {
+        return value as WidgetComponent;
+      }
+      if (typeof value === 'function' && value.prototype?.getData) {
+        return new (value as new () => WidgetComponent)();
+      }
+    }
+    return null;
+  }
+
+  private static async importWidgets(
+    entries: WidgetManifestEntry[],
+    runtime: Runtime,
+  ): Promise<WidgetRegistry> {
+    const registry = new WidgetRegistry();
+
+    for (const entry of entries) {
+      try {
+        const runtimePath = entry.modulePath.startsWith('/')
+          ? entry.modulePath
+          : `/${entry.modulePath}`;
+
+        const mod = await runtime.loadModule(runtimePath) as Record<string, unknown>;
+        const instance = Emroute.extractWidgetExport(mod);
+        if (!instance) continue;
+        registry.add(instance, runtimePath);
+      } catch (e) {
+        console.error(`[emroute] Failed to load widget ${entry.modulePath}:`, e);
+      }
+    }
+
+    return registry;
+  }
+
+  private static buildHtmlShell(title: string, htmlBase: string): string {
+    const baseTag = htmlBase ? `\n  <base href="${escapeHtml(htmlBase)}/">` : '';
+    return `<!DOCTYPE html>
+<html>
+<head>${baseTag}
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>${escapeHtml(title)}</title>
+  <style>@view-transition { navigation: auto; } router-slot { display: contents; }</style>
+</head>
+<body>
+  <router-slot></router-slot>
+</body>
+</html>`;
+  }
+
+  private static injectSsrContent(
+    html: string,
+    content: string,
+    title: string | undefined,
+    ssrRoute?: string,
+  ): string {
+    const slotPattern = /<router-slot\b[^>]*>.*?<\/router-slot>/s;
+    if (!slotPattern.test(html)) return html;
+
+    const ssrAttr = ssrRoute ? ` data-ssr-route="${ssrRoute}"` : '';
+    html = html.replace(slotPattern, `<router-slot${ssrAttr}>${content}</router-slot>`);
+
+    if (title) {
+      html = html.replace(/<title>[^<]*<\/title>/, `<title>${escapeHtml(title)}</title>`);
+    }
+
+    return html;
+  }
+
+  private static async resolveShell(
+    runtime: Runtime,
+    title: string,
+    htmlBase: string,
+  ): Promise<string> {
+    const response = await runtime.query('/index.html');
+    if (response.status !== 404) return await response.text();
+    return Emroute.buildHtmlShell(title, htmlBase);
+  }
+}

package/core/type/component.type.ts

@@ -0,0 +1,39 @@
+/**
+ * Component Types
+ *
+ * Types for the component system. Separate from route types.
+ */
+
+import type { RouteInfo } from './route.type.ts';
+
+/** Shape of companion file contents (html, md, css). */
+export type FileContents = { html?: string; md?: string; css?: string };
+
+/** Context passed to components during rendering. */
+export interface ComponentContext extends RouteInfo {
+  /** @deprecated Use context.url.pathname */
+  readonly pathname: string;
+  /** @deprecated Use context.url.searchParams */
+  readonly searchParams: URLSearchParams;
+  readonly files?: Readonly<FileContents>;
+  readonly signal?: AbortSignal;
+  readonly isLeaf?: boolean;
+}
+
+/**
+ * Enriches the base ComponentContext with app-level services.
+ * Registered once at server creation; called for every context construction.
+ */
+export type ContextProvider = (base: ComponentContext) => ComponentContext;
+
+/** Render context determines how components are rendered. */
+export type RenderContext = 'markdown' | 'html' | 'spa';
+
+/** Component manifest entry for code generation. */
+export interface ComponentManifestEntry {
+  name: string;
+  modulePath: string;
+  tagName: string;
+  type: 'page' | 'widget';
+  pattern?: string;
+}

package/core/type/element.type.ts

@@ -0,0 +1,10 @@
+/**
+ * Element Types
+ */
+
+/** Custom element manifest entry for discovery and registration. */
+export interface ElementManifestEntry {
+  name: string;
+  modulePath: string;
+  tagName: string;
+}

package/core/type/logger.type.ts

@@ -0,0 +1,20 @@
+/**
+ * Logger Interface
+ *
+ * Minimal pluggable logger. Default: no-op (silent degradation).
+ * Pass via PipelineOptions to wire in.
+ */
+export interface Logger {
+  error(msg: string, error?: Error): void;
+  warn(msg: string): void;
+}
+
+const noop = () => {};
+
+/** Default no-op logger. */
+export const defaultLogger: Logger = { error: noop, warn: noop };
+
+/** @deprecated Pass `logger` in Emroute.create() config instead. This function is a no-op. */
+export function setLogger(_logger: Logger): void {
+  console.warn('[emroute] setLogger() is deprecated. Pass `logger` in Emroute.create() config instead.');
+}

package/core/type/markdown.type.ts

@@ -0,0 +1,8 @@
+/**
+ * Markdown Renderer Interface
+ */
+
+export interface MarkdownRenderer {
+  render(markdown: string): string;
+  init?(): Promise<void>;
+}

package/core/type/route-tree.type.ts

@@ -0,0 +1,28 @@
+/**
+ * Route Tree
+ *
+ * Serializable tree structure that mirrors the filesystem layout.
+ *
+ * Each node corresponds to a URL segment. The tree is JSON-serializable
+ * (no Maps, no classes) so it can be written to disk, sent over the wire,
+ * or used directly as the in-memory trie for O(depth) route matching.
+ */
+
+/** Files associated with a route (companion files discovered alongside the page). */
+export interface RouteFiles {
+  ts?: string;
+  js?: string;
+  html?: string;
+  md?: string;
+  css?: string;
+}
+
+/** A single node in the route tree. */
+export interface RouteNode {
+  files?: RouteFiles;
+  errorBoundary?: string;
+  redirect?: string;
+  children?: Record<string, RouteNode>;
+  dynamic?: { param: string; child: RouteNode };
+  wildcard?: { param: string; child: RouteNode };
+}

package/core/type/route.type.ts

@@ -0,0 +1,75 @@
+/**
+ * Route Types
+ *
+ * Pure routing types. No rendering, no navigation, no browser concerns.
+ */
+
+export type { RouteNode, RouteFiles } from './route-tree.type.ts';
+
+/** Parameters extracted from URL patterns. */
+export type RouteParams = Readonly<Record<string, string>>;
+
+/** Immutable route context built once per navigation, shared across the render pipeline. */
+export interface RouteInfo {
+  readonly url: URL;
+  readonly params: RouteParams;
+}
+
+/** Supported file patterns in file-based routing. */
+export type RouteFileType = 'page' | 'error' | 'redirect';
+
+/** Redirect configuration. */
+export interface RedirectConfig {
+  to: string;
+  status: 301 | 302;
+}
+
+/** Route configuration for a single matched route. */
+export interface RouteConfig {
+  pattern: string;
+  type: RouteFileType;
+  modulePath: string;
+  files?: import('./route-tree.type.ts').RouteFiles;
+  parent?: string;
+  statusCode?: number;
+}
+
+/** Result of matching a URL against routes. */
+export interface MatchedRoute {
+  readonly route: RouteConfig;
+  readonly params: RouteParams;
+}
+
+/** Error boundary configuration. */
+export interface ErrorBoundary {
+  pattern: string;
+  modulePath: string;
+}
+
+/** Router state for history management. */
+export interface RouterState {
+  pathname: string;
+  params: RouteParams;
+  scrollY?: number;
+}
+
+/** Navigation options. */
+export interface NavigateOptions {
+  replace?: boolean;
+  state?: RouterState;
+  hash?: string;
+}
+
+/** Router event types. */
+export type RouterEventType = 'navigate' | 'error' | 'load';
+
+/** Router event payload. */
+export interface RouterEvent {
+  type: RouterEventType;
+  pathname: string;
+  params: RouteParams;
+  error?: Error;
+}
+
+/** Router event listener. */
+export type RouterEventListener = (event: RouterEvent) => void;

package/core/type/widget.type.ts

@@ -0,0 +1,27 @@
+/**
+ * Widget Types
+ */
+
+/** SPA rendering mode. */
+export type SpaMode = 'none' | 'leaf' | 'root' | 'only';
+
+/** Widget manifest entry for discovery and registration. */
+export interface WidgetManifestEntry {
+  name: string;
+  modulePath: string;
+  tagName: string;
+  files?: { html?: string; md?: string; css?: string };
+}
+
+/** Full widgets manifest (array, sorted by name). */
+export type WidgetsManifest = WidgetManifestEntry[];
+
+/** Parsed widget block from markdown fenced code. */
+export interface ParsedWidgetBlock {
+  fullMatch: string;
+  widgetName: string;
+  params: Record<string, unknown> | null;
+  parseError?: string;
+  startIndex: number;
+  endIndex: number;
+}

package/core/util/html.util.ts

@@ -0,0 +1,50 @@
+/**
+ * Pure HTML utilities. No DOM, no browser APIs.
+ */
+
+/** HTML attribute name marking a widget as server-rendered. */
+export const SSR_ATTR = 'ssr';
+
+/** HTML attribute name for lazy-loading widgets. */
+export const LAZY_ATTR = 'lazy';
+
+const BLOCKED_PROTOCOLS = /^(javascript|data|vbscript):/i;
+
+/** Throw if a redirect URL uses a dangerous protocol. */
+export function assertSafeRedirect(url: string): void {
+  if (BLOCKED_PROTOCOLS.test(url.trim())) {
+    throw new Error(`Unsafe redirect URL blocked: ${url}`);
+  }
+}
+
+export function escapeHtml(text: string): string {
+  return text
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#39;')
+    .replaceAll('`', '&#96;');
+}
+
+export function unescapeHtml(text: string): string {
+  return text
+    .replaceAll('&#96;', '`')
+    .replaceAll('&#39;', "'")
+    .replaceAll('&quot;', '"')
+    .replaceAll('&gt;', '>')
+    .replaceAll('&lt;', '<')
+    .replaceAll('&amp;', '&');
+}
+
+export function scopeWidgetCss(css: string, widgetName: string): string {
+  return `@scope (widget-${widgetName}) {\n${css}\n}`;
+}
+
+/** Status code to message mapping. */
+export const STATUS_MESSAGES: Record<number, string> = {
+  401: 'Unauthorized',
+  403: 'Forbidden',
+  404: 'Not Found',
+  500: 'Internal Server Error',
+};

package/{src → core}/util/md.util.ts

@@ -5,10 +5,8 @@
  * Skips fenced code blocks and links already under a known base path.
  */
 
-/** Rewrite internal absolute links in markdown to include the base path prefix. */
 export function rewriteMdLinks(markdown: string, base: string, skipPrefixes: string[]): string {
   const prefix = base + '/';
-  // Negative lookahead: skip links already under a known base path
   const skip = skipPrefixes.map((p) => p.slice(1) + '/').join('|');
   const inlineRe = new RegExp(`\\]\\(\\/(?!${skip})`, 'g');
   const refRe = new RegExp(`^(\\[[^\\]]+\\]:\\s+)\\/(?!${skip})`, 'g');
@@ -17,14 +15,14 @@ export function rewriteMdLinks(markdown: string, base: string, skipPrefixes: str
   let inCodeBlock = false;
 
   for (let i = 0; i < lines.length; i++) {
-    if (lines[i].startsWith('```')) {
+    if (lines[i]!.startsWith('```')) {
       inCodeBlock = !inCodeBlock;
       continue;
     }
     if (inCodeBlock) continue;
 
-    lines[i] = lines[i].replaceAll(inlineRe, `](${prefix}`);
-    lines[i] = lines[i].replaceAll(refRe, `$1${prefix}`);
+    lines[i] = lines[i]!.replaceAll(inlineRe, `](${prefix}`);
+    lines[i] = lines[i]!.replaceAll(refRe, `$1${prefix}`);
   }
 
   return lines.join('\n');

package/{src/route → core/util}/route-tree.util.ts

@@ -17,7 +17,6 @@ import type { RouteNode } from '../type/route-tree.type.ts';
 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;
   }
@@ -28,7 +27,6 @@ export function resolveTargetNode(node: RouteNode, name: string, isRoot: boolean
     return node.dynamic.child;
   }
 
-  // Static segment
   node.children ??= {};
   node.children[name] ??= {};
   return node.children[name];