@emkodev/emroute 1.7.3 → 1.8.0-beta.1

package/src/route/route.trie.ts

@@ -1,265 +0,0 @@
-/**
- * Route Trie
- *
- * Segment-based trie implementing RouteResolver for O(depth) route matching.
- *
- * Each URL segment maps to a trie node. Nodes are tried 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.
- *
- * Accepts a RouteNode tree (the JSON-serializable manifest from Runtime)
- * and converts it to an internal trie with Map-based static children for
- * O(1) segment lookup.
- */
-
-import type { RouteNode } from '../type/route-tree.type.ts';
-import type { RouteResolver, ResolvedRoute } from './route.resolver.ts';
-
-/** Internal trie node with Map for O(1) static child lookup. */
-interface TrieNode {
-  /** RouteNode when this node is a terminal route. */
-  route?: RouteNode;
-  /** Reconstructed pattern for this node (e.g. "/projects/:id"). */
-  pattern?: string;
-  /** Error boundary module path scoped to this prefix. */
-  errorBoundary?: string;
-  /** Static children keyed by exact segment. */
-  static: Map<string, TrieNode>;
-  /** Dynamic child for single-segment params (:param). */
-  dynamic?: { param: string; node: TrieNode };
-  /** Wildcard child for catch-all params (:rest*). */
-  wildcard?: { param: string; node: TrieNode };
-}
-
-function createNode(): TrieNode {
-  return { static: new Map() };
-}
-
-/** Try decodeURIComponent, return the original segment on malformed input. */
-function safeDecode(segment: string): string {
-  try {
-    return decodeURIComponent(segment);
-  } catch {
-    return segment;
-  }
-}
-
-/**
- * Split a normalized pathname into segments.
- * Assumes leading slash, no trailing slash. Must NOT be called with '/'.
- */
-function splitSegments(pathname: string): string[] {
-  return pathname.substring(1).split('/');
-}
-
-/**
- * Convert a RouteNode tree into a TrieNode tree.
- * Recursively walks the RouteNode, converting Record children to Map
- * and reconstructing URL patterns at each node.
- */
-function convertNode(source: RouteNode, pattern: string): TrieNode {
-  const node = createNode();
-
-  // Terminal route (has files or redirect)
-  if (source.files || source.redirect) {
-    node.route = source;
-    node.pattern = pattern;
-  }
-
-  // Error boundary
-  if (source.errorBoundary) {
-    node.errorBoundary = source.errorBoundary;
-  }
-
-  // Static children
-  if (source.children) {
-    for (const [segment, child] of Object.entries(source.children)) {
-      const childPattern = pattern === '/' ? `/${segment}` : `${pattern}/${segment}`;
-      node.static.set(segment, convertNode(child, childPattern));
-    }
-  }
-
-  // Dynamic child
-  if (source.dynamic) {
-    const { param, child } = source.dynamic;
-    const childPattern = pattern === '/' ? `/:${param}` : `${pattern}/:${param}`;
-    node.dynamic = { param, node: convertNode(child, childPattern) };
-  }
-
-  // Wildcard child
-  if (source.wildcard) {
-    const { param, child } = source.wildcard;
-    const childPattern = pattern === '/' ? `/:${param}*` : `${pattern}/:${param}*`;
-    node.wildcard = { param, node: convertNode(child, childPattern) };
-  }
-
-  return node;
-}
-
-/**
- * Trie-based route resolver.
- *
- * Implements RouteResolver with O(depth) matching by walking the trie.
- * Constructed from a RouteNode tree (produced by Runtime.scanRoutes).
- */
-export class RouteTrie implements RouteResolver {
-  private readonly root: TrieNode;
-
-  constructor(tree: RouteNode) {
-    this.root = convertNode(tree, '/');
-  }
-
-  match(pathname: string): ResolvedRoute | undefined {
-    // Normalize: strip trailing slash (except bare '/')
-    if (pathname.length > 1 && pathname.endsWith('/')) {
-      pathname = pathname.slice(0, -1);
-    }
-
-    if (!pathname.startsWith('/')) {
-      pathname = '/' + pathname;
-    }
-
-    if (pathname === '/') {
-      if (this.root.route) {
-        return { node: this.root.route, pattern: '/', params: {} };
-      }
-      return undefined;
-    }
-
-    const segments = splitSegments(pathname);
-    return this.walk(this.root, segments, 0, {});
-  }
-
-  findErrorBoundary(pathname: string): string | undefined {
-    if (pathname.length > 1 && pathname.endsWith('/')) {
-      pathname = pathname.slice(0, -1);
-    }
-    if (!pathname.startsWith('/')) {
-      pathname = '/' + pathname;
-    }
-
-    if (pathname === '/') return this.root.errorBoundary;
-
-    const segments = splitSegments(pathname);
-    return this.walkForBoundary(this.root, segments, 0, this.root.errorBoundary);
-  }
-
-  findRoute(pattern: string): RouteNode | undefined {
-    if (pattern === '/') {
-      return this.root.route;
-    }
-
-    const segments = splitSegments(pattern);
-    let node = this.root;
-
-    for (const segment of segments) {
-      let child: TrieNode | undefined;
-
-      if (segment.startsWith(':') && segment.endsWith('*')) {
-        child = node.wildcard?.node;
-      } else if (segment.startsWith(':')) {
-        child = node.dynamic?.node;
-      } else {
-        child = node.static.get(segment);
-      }
-
-      if (!child) return undefined;
-      node = child;
-    }
-
-    return node.route;
-  }
-
-  // ── Private matching ──────────────────────────────────────────────────
-
-  private walk(
-    node: TrieNode,
-    segments: string[],
-    index: number,
-    params: Record<string, string>,
-  ): ResolvedRoute | undefined {
-    if (index === segments.length) {
-      if (node.route) {
-        return { node: node.route, pattern: node.pattern!, params: { ...params } };
-      }
-      if (node.wildcard?.node.route) {
-        return {
-          node: node.wildcard.node.route,
-          pattern: node.wildcard.node.pattern!,
-          params: { ...params, [node.wildcard.param]: '' },
-        };
-      }
-      return undefined;
-    }
-
-    const segment = segments[index];
-
-    // 1. Try static child
-    const staticChild = node.static.get(segment);
-    if (staticChild) {
-      const result = this.walk(staticChild, segments, index + 1, params);
-      if (result) return result;
-    }
-
-    // 2. Try dynamic child (single segment)
-    if (node.dynamic) {
-      const { param, node: dynamicNode } = node.dynamic;
-      params[param] = safeDecode(segment);
-      const result = this.walk(dynamicNode, segments, index + 1, params);
-      if (result) return result;
-      delete params[param];
-    }
-
-    // 3. Try wildcard (consumes all remaining segments)
-    if (node.wildcard?.node.route) {
-      const { param, node: wildcardNode } = node.wildcard;
-      let rest = safeDecode(segments[index]);
-      for (let i = index + 1; i < segments.length; i++) {
-        rest += '/' + safeDecode(segments[i]);
-      }
-      return {
-        node: wildcardNode.route!,
-        pattern: wildcardNode.pattern!,
-        params: { ...params, [param]: rest },
-      };
-    }
-
-    return undefined;
-  }
-
-  /**
-   * Walk for error boundary. Follows the same priority as match
-   * (static → dynamic → wildcard) without backtracking across branches.
-   * Returns the deepest error boundary module path found along the path.
-   */
-  private walkForBoundary(
-    node: TrieNode,
-    segments: string[],
-    index: number,
-    deepest: string | undefined,
-  ): string | undefined {
-    if (index === segments.length) {
-      return node.errorBoundary ?? deepest;
-    }
-
-    const segment = segments[index];
-
-    const staticChild = node.static.get(segment);
-    if (staticChild) {
-      return this.walkForBoundary(staticChild, segments, index + 1, staticChild.errorBoundary ?? deepest);
-    }
-
-    if (node.dynamic) {
-      return this.walkForBoundary(node.dynamic.node, segments, index + 1, node.dynamic.node.errorBoundary ?? deepest);
-    }
-
-    if (node.wildcard) {
-      return node.wildcard.node.errorBoundary ?? deepest;
-    }
-
-    return deepest;
-  }
-}

package/src/type/element.type.ts

@@ -1,22 +0,0 @@
-/**
- * Custom Element - Type Definitions
- *
- * Custom elements are plain HTMLElement subclasses auto-discovered from
- * `elementsDir/{name}/{name}.element.ts`. They are registered in the
- * browser via `customElements.define()` during `bootEmrouteApp()`.
- */
-
-/**
- * Custom element manifest entry.
- * Discovered from `elementsDir/{name}/{name}.element.ts`.
- */
-export interface ElementManifestEntry {
-  /** Element name in kebab-case (must contain a hyphen per web spec) */
-  name: string;
-
-  /** Path to element module file */
-  modulePath: string;
-
-  /** Custom element tag name (same as name) */
-  tagName: string;
-}

package/src/type/logger.type.ts

@@ -1,24 +0,0 @@
-/**
- * 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

@@ -1,21 +0,0 @@
-/**
- * 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;
-}

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

@@ -1,51 +0,0 @@
-/**
- * Route Tree
- *
- * Serializable tree structure that mirrors the filesystem layout.
- * Replaces the flat array manifest as the canonical route format.
- *
- * 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 {
-  /** TypeScript module (e.g. "routes/about.page.ts") */
-  ts?: string;
-  /** JavaScript module — merged module with inlined companions (e.g. "routes/about.page.js") */
-  js?: string;
-  /** HTML template (e.g. "routes/about.page.html") */
-  html?: string;
-  /** Markdown content (e.g. "routes/about.page.md") */
-  md?: string;
-  /** Scoped stylesheet (e.g. "routes/about.page.css") */
-  css?: string;
-}
-
-/** A single node in the route tree. */
-export interface RouteNode {
-  /** Route files when this node is a terminal route. */
-  files?: RouteFiles;
-
-  /** Error boundary module path scoped to this prefix (from .error.ts). */
-  errorBoundary?: string;
-
-  /** Redirect module path (from .redirect.ts). Mutually exclusive with files. */
-  redirect?: string;
-
-  /** Static children keyed by URL segment (e.g. "about", "projects"). */
-  children?: Record<string, RouteNode>;
-
-  /** Single-segment dynamic param (from [param] directories/files). */
-  dynamic?: {
-    param: string;
-    child: RouteNode;
-  };
-
-  /** Catch-all wildcard (from directory index.page.* files). */
-  wildcard?: {
-    param: string;
-    child: RouteNode;
-  };
-}

package/src/type/route.type.ts

@@ -1,124 +0,0 @@
-/**
- * Router Types
- *
- * Native browser APIs only - no external dependencies.
- * Follows islands architecture: pages = HTML, widgets = web components.
- */
-
-/** 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 {
-  /** The URL being rendered. Components read pathname, searchParams, hash from this. */
-  readonly url: URL;
-
-  /** URL parameters extracted by the trie match. */
-  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;
-}
-
-/** Available files for a route */
-export interface RouteFiles {
-  /** TypeScript module path (.page.ts) */
-  ts?: string;
-
-  /** JavaScript module — merged module with inlined companions (.page.js) */
-  js?: string;
-
-  /** HTML template path (.page.html) */
-  html?: string;
-
-  /** Markdown content path (.page.md) */
-  md?: string;
-
-  /** CSS stylesheet path (.page.css) */
-  css?: string;
-}
-
-/** Route configuration for a single route */
-export interface RouteConfig {
-  /** URLPattern pathname pattern (e.g., '/projects/:id') */
-  pattern: string;
-
-  /** Type of route file */
-  type: RouteFileType;
-
-  /** Module path for dynamic import (primary file based on precedence) */
-  modulePath: string;
-
-  /** Available files for this route */
-  files?: RouteFiles;
-
-  /** Parent route pattern for nested routes */
-  parent?: string;
-
-  /** HTTP status code (for status-specific pages like 404, 401, 403) */
-  statusCode?: number;
-}
-
-/** Result of matching a URL against routes */
-export interface MatchedRoute {
-  /** The matched route configuration */
-  readonly route: RouteConfig;
-
-  /** Extracted URL parameters */
-  readonly params: RouteParams;
-}
-
-/** Error boundary configuration */
-export interface ErrorBoundary {
-  /** Pattern prefix this error boundary handles */
-  pattern: string;
-
-  /** Module path for the error handler */
-  modulePath: string;
-}
-
-export type { RouteNode } from './route-tree.type.ts';
-
-/** Router state for history management */
-export interface RouterState {
-  /** Current URL pathname */
-  pathname: string;
-
-  /** Extracted route parameters */
-  params: RouteParams;
-
-  /** Scroll position to restore */
-  scrollY?: number;
-}
-
-/** Navigation options */
-export interface NavigateOptions {
-  /** Replace current history entry instead of pushing */
-  replace?: boolean;
-
-  /** State to store in history */
-  state?: RouterState;
-
-  /** Hash to scroll to after navigation */
-  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/src/type/widget.type.ts

@@ -1,65 +0,0 @@
-/**
- * Widget System - Type Definitions
- *
- * Widgets are data-fetching components that work across three contexts:
- * 1. /md/ (LLMs) - Returns markdown with JSON data
- * 2. SSR/HTML - Pre-fetched data embedded in custom element
- * 3. SPA/Browser - Custom element fetches and hydrates
- */
-
-/**
- * Parsed widget block from markdown.
- * Represents a fenced code block with widget syntax.
- */
-export interface ParsedWidgetBlock {
-  /** Full matched string including fences */
-  fullMatch: string;
-
-  /** Widget name extracted from widget:{name} */
-  widgetName: string;
-
-  /** Parsed JSON params, or null if empty/invalid */
-  params: Record<string, unknown> | null;
-
-  /** Parse error message if params JSON was invalid */
-  parseError?: string;
-
-  /** Start index in original markdown */
-  startIndex: number;
-
-  /** End index in original markdown */
-  endIndex: number;
-}
-
-/** Custom element tag name for widgets: `widget-{name}` */
-export type WidgetTagName = `widget-${string}`;
-
-/** SPA rendering mode. */
-export type SpaMode = 'none' | 'leaf' | 'root' | 'only';
-
-/**
- * Widget manifest entry for code generation.
- */
-export interface WidgetManifestEntry {
-  /** Widget name in kebab-case */
-  name: string;
-
-  /** Path to widget module file */
-  modulePath: string;
-
-  /** Custom element tag name (widget-{name}) */
-  tagName: WidgetTagName;
-
-  /** Discovered/declared companion file paths (html, md, css) */
-  files?: { html?: string; md?: string; css?: string };
-}
-
-/**
- * Generated widgets manifest structure.
- */
-export interface WidgetsManifest {
-  widgets: WidgetManifestEntry[];
-
-  /** Pre-bundled module loaders keyed by module path (for SPA bundles) */
-  moduleLoaders?: Record<string, () => Promise<unknown>>;
-}

package/src/util/logger.util.ts

@@ -1,83 +0,0 @@
-/**
- * Logger Utility
- *
- * Provides structured logging for emroute internals.
- * Enable via localStorage: localStorage.setItem('emroute:debug', 'true')
- */
-
-const STORAGE_KEY = 'emroute:debug';
-const PREFIX = '[emroute]';
-
-function isEnabled(): boolean {
-  if (typeof globalThis.localStorage === 'undefined') return false;
-  return globalThis.localStorage.getItem(STORAGE_KEY) === 'true';
-}
-
-export const logger = {
-  /** Enable debug logging (persists in localStorage) */
-  enable(): void {
-    if (typeof globalThis.localStorage !== 'undefined') {
-      globalThis.localStorage.setItem(STORAGE_KEY, 'true');
-      console.log(`${PREFIX} Debug logging enabled`);
-    }
-  },
-
-  /** Disable debug logging */
-  disable(): void {
-    if (typeof globalThis.localStorage !== 'undefined') {
-      globalThis.localStorage.removeItem(STORAGE_KEY);
-      console.log(`${PREFIX} Debug logging disabled`);
-    }
-  },
-
-  /** Log general information */
-  info(category: string, message: string, data?: unknown): void {
-    if (!isEnabled()) return;
-    const prefix = `${PREFIX} [${category}]`;
-    if (data !== undefined) {
-      console.log(prefix, message, data);
-    } else {
-      console.log(prefix, message);
-    }
-  },
-
-  /** Log navigation events */
-  nav(action: string, from: string, to: string, data?: Record<string, unknown>): void {
-    if (!isEnabled()) return;
-    console.log(`${PREFIX} [nav] ${action}:`, { from, to, ...(data ?? {}) });
-  },
-
-  /** Log rendering events */
-  render(component: string, route: string, mode?: string): void {
-    if (!isEnabled()) return;
-    const modeStr = mode ? ` [mode=${mode}]` : '';
-    console.log(`${PREFIX} [render]${modeStr} ${component} → ${route}`);
-  },
-
-  /** Log link interception */
-  link(action: 'intercept' | 'passthrough', href: string, reason?: string): void {
-    if (!isEnabled()) return;
-    const reasonStr = reason ? ` (${reason})` : '';
-    console.log(`${PREFIX} [link] ${action}: ${href}${reasonStr}`);
-  },
-
-  /** Log widget lifecycle */
-  widget(event: string, name: string, data?: unknown): void {
-    if (!isEnabled()) return;
-    console.log(`${PREFIX} [widget] ${event}: ${name}`, data ?? '');
-  },
-
-  /** Log warnings (always shown, not gated by debug flag) */
-  warn(message: string): void {
-    console.warn(`${PREFIX}`, message);
-  },
-
-  /** Log SSR adoption */
-  ssr(action: string, route: string): void {
-    if (!isEnabled()) return;
-    console.log(`${PREFIX} [ssr] ${action}: ${route}`);
-  },
-};
-
-// Expose globally for console access
-(globalThis as Record<string, unknown>).__emroute_logger = logger;