@emkodev/emroute 1.0.3 → 1.6.0

package/src/route/route.core.ts

@@ -0,0 +1,316 @@
+/**
+ * Route Core
+ *
+ * Shared routing logic used by all renderers:
+ * - Route matching and hierarchy building
+ * - Module loading and caching
+ * - Event emission
+ * - URL normalization
+ */
+
+import type {
+  MatchedRoute,
+  RouteConfig,
+  RouteInfo,
+  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';
+
+/** Base paths for the two SSR rendering endpoints. */
+export interface BasePath {
+  /** Base path for SSR HTML rendering (default: '/html') */
+  html: string;
+  /** Base path for SSR Markdown rendering (default: '/md') */
+  md: string;
+}
+
+/** 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. */
+export function assertSafeRedirect(url: string): void {
+  if (BLOCKED_PROTOCOLS.test(url.trim())) {
+    throw new Error(`Unsafe redirect URL blocked: ${url}`);
+  }
+}
+
+/** Default root route - renders a slot for child routes */
+export const DEFAULT_ROOT_ROUTE: RouteConfig = {
+  pattern: '/',
+  type: 'page',
+  modulePath: '__default_root__',
+};
+
+/** Options for RouteCore */
+export interface RouteCoreOptions {
+  /**
+   * Read a companion file (.html, .md, .css) by path — returns its text content.
+   * SSR: `(path) => runtime.query(path, { as: 'text' })`.
+   * SPA default: `fetch(path, { headers: { Accept: 'text/plain' } }).then(r => r.text())`.
+   */
+  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. */
+  basePath?: string;
+}
+
+/**
+ * Core router functionality shared across all rendering contexts.
+ */
+export class RouteCore {
+  readonly matcher: RouteMatcher;
+  /** 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();
+  private moduleLoaders: Record<string, () => Promise<unknown>>;
+  currentRoute: MatchedRoute | null = null;
+  private readFile: (path: string) => Promise<string>;
+
+  constructor(manifest: RoutesManifest, options: RouteCoreOptions = {}) {
+    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 ?? {};
+  }
+
+  /**
+   * Get current route parameters.
+   */
+  getParams(): RouteParams {
+    return this.currentRoute?.params ?? {};
+  }
+
+  /**
+   * Add event listener for router events.
+   */
+  addEventListener(listener: RouterEventListener): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  /**
+   * Emit router event to listeners.
+   */
+  emit(event: RouterEvent): void {
+    for (const listener of this.listeners) {
+      try {
+        listener(event);
+      } catch (e) {
+        console.error('[Router] Event listener error:', e);
+      }
+    }
+  }
+
+  /**
+   * Match a URL to a route.
+   * Falls back to the default root route for the basePath root (or '/' when no basePath).
+   */
+  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 + '/') {
+      return {
+        route: { ...DEFAULT_ROOT_ROUTE, pattern: this.root },
+        params: {},
+        searchParams: urlObj.searchParams,
+      };
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Build route hierarchy from a pattern.
+   *
+   * 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'
+   *   → ['/', '/projects', '/projects/:id', '/projects/:id/tasks']
+   */
+  buildRouteHierarchy(pattern: string): string[] {
+    if (pattern === this.root || pattern === this.root + '/') {
+      return [this.root];
+    }
+
+    // Extract the part after basePath
+    const tail = this.basePath ? pattern.slice(this.basePath.length) : pattern;
+    const segments = tail.split('/').filter(Boolean);
+
+    const hierarchy: string[] = [this.root];
+    let current = this.basePath || '';
+    for (const segment of segments) {
+      current += '/' + segment;
+      hierarchy.push(current);
+    }
+
+    return hierarchy;
+  }
+
+  /**
+   * Normalize URL by removing trailing slashes (except bare '/').
+   */
+  normalizeUrl(url: string): string {
+    if (url.length > 1 && url.endsWith('/')) {
+      return url.slice(0, -1);
+    }
+    return url;
+  }
+
+  /**
+   * Convert relative path to absolute path.
+   */
+  toAbsolutePath(path: string): string {
+    return path.startsWith('/') ? path : '/' + path;
+  }
+
+  /**
+   * Load a module with caching.
+   * Uses pre-bundled loaders when available, falls back to dynamic import.
+   */
+  async loadModule<T>(modulePath: string): Promise<T> {
+    if (this.moduleCache.has(modulePath)) {
+      return this.moduleCache.get(modulePath) as T;
+    }
+
+    let module: unknown;
+    const loader = this.moduleLoaders[modulePath];
+    if (loader) {
+      module = await loader();
+    } else {
+      const absolutePath = this.toAbsolutePath(modulePath);
+      module = await import(absolutePath);
+    }
+
+    this.moduleCache.set(modulePath, module);
+    return module as T;
+  }
+
+  /**
+   * Load widget file contents with caching.
+   * Returns an object with loaded file contents.
+   */
+  async loadWidgetFiles(
+    widgetFiles: { html?: string; md?: string; css?: string },
+  ): Promise<{ html?: string; md?: string; css?: string }> {
+    const load = async (path: string): Promise<string | undefined> => {
+      const absPath = this.toAbsolutePath(path);
+      const cached = this.widgetFileCache.get(absPath);
+      if (cached !== undefined) return cached;
+
+      try {
+        const content = await this.readFile(absPath);
+        this.widgetFileCache.set(absPath, content);
+        return content;
+      } catch (e) {
+        console.warn(
+          `[RouteCore] Failed to load widget file ${path}:`,
+          e instanceof Error ? e.message : e,
+        );
+        return undefined;
+      }
+    };
+
+    const [html, md, css] = await Promise.all([
+      widgetFiles.html ? load(widgetFiles.html) : undefined,
+      widgetFiles.md ? load(widgetFiles.md) : undefined,
+      widgetFiles.css ? load(widgetFiles.css) : undefined,
+    ]);
+
+    return { html, md, css };
+  }
+
+  /**
+   * Build a RouteInfo from a matched route and the resolved URL pathname.
+   * Called once per navigation; the result is reused across the route hierarchy.
+   */
+  toRouteInfo(matched: MatchedRoute, pathname: string): RouteInfo {
+    return {
+      pathname,
+      pattern: matched.route.pattern,
+      params: matched.params,
+      searchParams: matched.searchParams ?? new URLSearchParams(),
+    };
+  }
+
+  /**
+   * 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,
+    route: RouteConfig,
+    signal?: AbortSignal,
+    isLeaf?: boolean,
+  ): Promise<ComponentContext> {
+    const fetchFile = (filePath: string): Promise<string> =>
+      this.readFile(this.toAbsolutePath(filePath));
+
+    const rf = route.files;
+    const [html, md, css] = await Promise.all([
+      rf?.html ? fetchFile(rf.html) : undefined,
+      rf?.md ? fetchFile(rf.md) : undefined,
+      rf?.css ? fetchFile(rf.css) : undefined,
+    ]);
+
+    const base: ComponentContext = {
+      ...routeInfo,
+      files: { html, md, css },
+      signal,
+      isLeaf,
+      basePath: this.basePath || undefined,
+    };
+    return this.contextProvider ? this.contextProvider(base) : base;
+  }
+}

package/src/route/route.matcher.ts

@@ -0,0 +1,260 @@
+/**
+ * Route Matcher
+ *
+ * URLPattern-based route matching with support for:
+ * - Static routes (/about)
+ * - Dynamic segments (/projects/:id)
+ * - Wildcard/catch-all (future)
+ *
+ * Uses native URLPattern API (supported in all major browsers).
+ */
+
+/** Parse a URL path string into a URL object. Passes through URL objects unchanged. */
+export function toUrl(url: string | URL): URL {
+  return typeof url === 'string' ? new URL(url, 'http://url-parse') : url;
+}
+
+import type {
+  ErrorBoundary,
+  MatchedRoute,
+  RouteConfig,
+  RouteParams,
+  RoutesManifest,
+} from '../type/route.type.ts';
+
+/** Compiled route with URLPattern instance */
+interface CompiledRoute {
+  route: RouteConfig;
+  pattern: URLPattern;
+}
+
+/**
+ * Route matcher using native URLPattern API.
+ *
+ * Routes are matched in order of specificity:
+ * 1. Exact static matches first
+ * 2. Dynamic segment matches
+ * 3. More specific patterns before less specific
+ */
+export class RouteMatcher {
+  private compiledRoutes: CompiledRoute[] = [];
+  private errorBoundaries: ErrorBoundary[] = [];
+  private statusPages = new Map<number, RouteConfig>();
+  private errorHandler?: RouteConfig;
+
+  /**
+   * Initialize matcher with routes manifest.
+   * Routes should be pre-sorted by specificity in the manifest.
+   */
+  constructor(manifest: RoutesManifest) {
+    this.errorBoundaries = manifest.errorBoundaries.toSorted(
+      (a, b) => b.pattern.length - a.pattern.length,
+    );
+    this.statusPages = manifest.statusPages;
+    this.errorHandler = manifest.errorHandler;
+
+    // Compile URLPatterns for all routes
+    for (const route of manifest.routes) {
+      try {
+        const pattern = new URLPattern({ pathname: route.pattern });
+        this.compiledRoutes.push({ route, pattern });
+      } catch (e) {
+        console.error(`[Router] Invalid pattern: ${route.pattern}`, e);
+      }
+    }
+  }
+
+  /**
+   * Match a URL against registered routes.
+   * Returns the first matching route or undefined.
+   */
+  match(url: URL | string): MatchedRoute | undefined {
+    const urlObj = toUrl(url);
+
+    const searchParams = urlObj.searchParams;
+
+    for (const { route, pattern } of this.compiledRoutes) {
+      const result = pattern.exec(urlObj);
+      if (result) {
+        return {
+          route,
+          params: this.extractParams(result),
+          searchParams,
+          patternResult: result,
+        };
+      }
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Find error boundary for a given pathname.
+   * Searches from most specific to least specific.
+   */
+  findErrorBoundary(pathname: string): ErrorBoundary | undefined {
+    for (const boundary of this.errorBoundaries) {
+      const prefix = boundary.pattern.endsWith('/') ? boundary.pattern : boundary.pattern + '/';
+      if (pathname === boundary.pattern || pathname.startsWith(prefix)) {
+        return boundary;
+      }
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Get status-specific page (404, 401, 403).
+   */
+  getStatusPage(status: number): RouteConfig | undefined {
+    return this.statusPages.get(status);
+  }
+
+  /**
+   * Get generic error handler.
+   */
+  getErrorHandler(): RouteConfig | undefined {
+    return this.errorHandler;
+  }
+
+  /**
+   * Find a route by its exact pattern or by matching a pathname.
+   * Used for building route hierarchy.
+   */
+  findRoute(patternOrPath: string): RouteConfig | undefined {
+    // First try exact pattern match
+    for (const { route } of this.compiledRoutes) {
+      if (route.pattern === patternOrPath) {
+        return route;
+      }
+    }
+
+    // Then try to match as a URL path
+    const matched = this.match(toUrl(patternOrPath));
+    return matched?.route;
+  }
+
+  /**
+   * Extract params from URLPatternResult.
+   */
+  private extractParams(result: URLPatternResult): RouteParams {
+    const groups = result.pathname.groups;
+    const params: Record<string, string> = {};
+    for (const [key, value] of Object.entries(groups)) {
+      if (value !== undefined) {
+        params[key] = value;
+      }
+    }
+    return params;
+  }
+}
+
+/**
+ * Convert file-based route path to URLPattern.
+ *
+ * Examples:
+ * - index.page.ts → /
+ * - about.page.ts → /about
+ * - projects/index.page.ts → /projects/:rest*
+ * - projects/[id].page.ts → /projects/:id
+ * - projects/[id]/tasks.page.ts → /projects/:id/tasks
+ *
+ * Directory index files (non-root) become wildcard catch-all routes.
+ * See ADR-0002: Wildcard Routes via Directory Index Convention.
+ */
+export function filePathToPattern(filePath: string): string {
+  // Remove routes/ prefix and file extension
+  let pattern = filePath
+    .replace(/^routes\//, '')
+    .replace(/\.(page|error|redirect)\.(ts|html|md|css)$/, '');
+
+  // Detect non-root directory index before stripping
+  const isDirectoryIndex = pattern.endsWith('/index') && pattern !== 'index';
+
+  // Handle index files
+  pattern = pattern.replace(/\/index$/, '').replace(/^index$/, '');
+
+  // Convert [param] to :param
+  pattern = pattern.replace(/\[(?<param>[^\]]+)\]/g, ':$<param>');
+
+  // Ensure leading slash
+  pattern = '/' + pattern;
+
+  // Non-root directory index becomes wildcard catch-all
+  if (isDirectoryIndex) {
+    pattern += '/:rest*';
+  }
+
+  return pattern;
+}
+
+/**
+ * Determine route type from filename.
+ */
+export function getRouteType(
+  filename: string,
+): 'page' | 'error' | 'redirect' | null {
+  if (
+    filename.endsWith('.page.ts') ||
+    filename.endsWith('.page.html') ||
+    filename.endsWith('.page.md')
+  ) {
+    return 'page';
+  }
+  if (filename.endsWith('.error.ts')) {
+    return 'error';
+  }
+  if (filename.endsWith('.redirect.ts')) {
+    return 'redirect';
+  }
+  return null;
+}
+
+/**
+ * Get the file extension type from a page filename.
+ */
+export function getPageFileType(
+  filename: string,
+): 'ts' | 'html' | 'md' | 'css' | null {
+  if (filename.endsWith('.page.ts')) return 'ts';
+  if (filename.endsWith('.page.html')) return 'html';
+  if (filename.endsWith('.page.md')) return 'md';
+  if (filename.endsWith('.page.css')) return 'css';
+  return null;
+}
+
+/**
+ * Sort routes by specificity.
+ * Non-wildcards before wildcards, static before dynamic, longer paths first.
+ */
+export function sortRoutesBySpecificity(routes: RouteConfig[]): RouteConfig[] {
+  return routes.toSorted((a, b) => {
+    const aSegments = a.pattern.split('/').filter(Boolean);
+    const bSegments = b.pattern.split('/').filter(Boolean);
+
+    // Wildcards always sort last
+    const aIsWildcard = aSegments.some((s) => s.endsWith('*') || s.endsWith('+'));
+    const bIsWildcard = bSegments.some((s) => s.endsWith('*') || s.endsWith('+'));
+    if (aIsWildcard !== bIsWildcard) {
+      return aIsWildcard ? 1 : -1;
+    }
+
+    // More segments = more specific
+    if (aSegments.length !== bSegments.length) {
+      return bSegments.length - aSegments.length;
+    }
+
+    // Compare segment by segment
+    for (let i = 0; i < aSegments.length; i++) {
+      const aIsDynamic = aSegments[i].startsWith(':');
+      const bIsDynamic = bSegments[i].startsWith(':');
+
+      // Static segments are more specific than dynamic
+      if (aIsDynamic !== bIsDynamic) {
+        return aIsDynamic ? 1 : -1;
+      }
+    }
+
+    return 0;
+  });
+}

package/src/type/logger.type.ts

@@ -0,0 +1,24 @@
+/**
+ * Logger Interface
+ *
+ * Minimal pluggable logger for surfacing errors from silent catch blocks.
+ * Structurally compatible with hardkore's StructuredLogger — any instance
+ * of that class satisfies this interface without an explicit dependency.
+ *
+ * Default: no-op (silent degradation). Call setLogger() at startup to wire in.
+ */
+export interface Logger {
+  error(msg: string, error?: Error): void;
+  warn(msg: string): void;
+}
+
+const noop = () => {};
+
+/** Module-level logger. Always callable — defaults to no-op. */
+export const logger: Logger = { error: noop, warn: noop };
+
+/** Replace the logger implementation. Call once at startup. */
+export function setLogger(impl: Logger): void {
+  logger.error = impl.error.bind(impl);
+  logger.warn = impl.warn.bind(impl);
+}

package/src/type/markdown.type.ts

@@ -0,0 +1,21 @@
+/**
+ * Markdown Renderer Interface
+ *
+ * Implement this to provide custom markdown rendering.
+ * Used by MarkdownElement (browser) and SsrHtmlRouter (server).
+ */
+export interface MarkdownRenderer {
+  /**
+   * Initialize the renderer (e.g., load WASM).
+   * Called once before first render.
+   */
+  init?(): Promise<void>;
+
+  /**
+   * Render markdown to HTML.
+   *
+   * **Security:** Output is assigned to `innerHTML` — the renderer must
+   * sanitize dangerous markup. See `doc/08-markdown-renderer.md`.
+   */
+  render(markdown: string): string;
+}