@emkodev/emroute 1.0.3 → 1.6.0

package/src/type/navigation-api.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Navigation API type declarations.
+ *
+ * The Navigation API is supported by all major browsers (Chrome 102+, Edge 102+,
+ * Firefox 147+, Safari 26.2+) but TypeScript's lib.dom.d.ts does not yet include
+ * these types. This file provides the subset used by the SPA renderer.
+ *
+ * Will be removed once TypeScript ships native Navigation API types.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Navigation_API
+ * @see ADR-0014
+ */
+
+interface NavigationNavigateOptions {
+  state?: unknown;
+  history?: 'auto' | 'push' | 'replace';
+}
+
+interface NavigationResult {
+  committed: Promise<NavigationHistoryEntry>;
+  finished: Promise<NavigationHistoryEntry>;
+}
+
+interface NavigationHistoryEntry extends EventTarget {
+  readonly key: string;
+  readonly id: string;
+  readonly url: string | null;
+  readonly index: number;
+  readonly sameDocument: boolean;
+  getState(): unknown;
+}
+
+interface NavigationDestination {
+  readonly url: string;
+  readonly key: string | null;
+  readonly id: string | null;
+  readonly index: number;
+  readonly sameDocument: boolean;
+  getState(): unknown;
+}
+
+interface NavigationInterceptOptions {
+  handler?: () => Promise<void>;
+  focusReset?: 'after-transition' | 'manual';
+  scroll?: 'after-transition' | 'manual';
+}
+
+interface NavigateEvent extends Event {
+  readonly navigationType: 'push' | 'replace' | 'reload' | 'traverse';
+  readonly destination: NavigationDestination;
+  readonly canIntercept: boolean;
+  readonly userInitiated: boolean;
+  readonly hashChange: boolean;
+  readonly signal: AbortSignal;
+  readonly formData: FormData | null;
+  readonly downloadRequest: string | null;
+  readonly info: unknown;
+  intercept(options?: NavigationInterceptOptions): void;
+  scroll(): void;
+}
+
+interface NavigationUpdateCurrentEntryOptions {
+  state: unknown;
+}
+
+interface Navigation extends EventTarget {
+  readonly currentEntry: NavigationHistoryEntry | null;
+  readonly transition: NavigationTransition | null;
+  entries(): NavigationHistoryEntry[];
+  navigate(url: string, options?: NavigationNavigateOptions): NavigationResult;
+  reload(options?: NavigationNavigateOptions): NavigationResult;
+  back(): NavigationResult;
+  forward(): NavigationResult;
+  traverseTo(key: string): NavigationResult;
+  updateCurrentEntry(options: NavigationUpdateCurrentEntryOptions): void;
+  addEventListener(
+    type: 'navigate',
+    listener: (event: NavigateEvent) => void,
+    options?: AddEventListenerOptions,
+  ): void;
+  addEventListener(
+    type: 'navigatesuccess' | 'navigateerror' | 'currententrychange',
+    listener: (event: Event) => void,
+    options?: AddEventListenerOptions,
+  ): void;
+}
+
+interface NavigationTransition {
+  readonly navigationType: 'push' | 'replace' | 'reload' | 'traverse';
+  readonly from: NavigationHistoryEntry;
+  readonly finished: Promise<void>;
+}
+
+// deno-lint-ignore no-var
+declare var navigation: Navigation;

package/src/type/route.type.ts

@@ -0,0 +1,149 @@
+/**
+ * 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 {
+  /** Actual URL path (e.g., '/projects/123') */
+  readonly pathname: string;
+
+  /** Matched route pattern (e.g., '/projects/:id') */
+  readonly pattern: string;
+
+  /** URL parameters extracted by the router */
+  readonly params: RouteParams;
+
+  /** Query string parameters */
+  readonly searchParams: URLSearchParams;
+}
+
+/** 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;
+
+  /** 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;
+
+  /** Query string parameters from the matched URL */
+  readonly searchParams?: URLSearchParams;
+
+  /** The URLPatternResult from matching */
+  readonly patternResult?: URLPatternResult;
+}
+
+/** Error boundary configuration */
+export interface ErrorBoundary {
+  /** Pattern prefix this error boundary handles */
+  pattern: string;
+
+  /** Module path for the error handler */
+  modulePath: string;
+}
+
+/** Generated routes manifest from build tool */
+export interface RoutesManifest {
+  /** All page routes */
+  routes: RouteConfig[];
+
+  /** Error boundaries by pattern prefix */
+  errorBoundaries: ErrorBoundary[];
+
+  /** Status-specific pages (404, 401, 403) */
+  statusPages: Map<number, RouteConfig>;
+
+  /** Generic error handler */
+  errorHandler?: RouteConfig;
+
+  /** Pre-bundled module loaders keyed by module path (for SPA bundles) */
+  moduleLoaders?: Record<string, () => Promise<unknown>>;
+}
+
+/** 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

@@ -0,0 +1,65 @@
+/**
+ * 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/html.util.ts

@@ -0,0 +1,186 @@
+/**
+ * Core HTML utilities for emroute
+ */
+
+/** HTML attribute name marking a widget as server-rendered (skip client getData + render). */
+export const SSR_ATTR = 'ssr';
+
+/** HTML attribute name for lazy-loading widgets via IntersectionObserver. */
+export const LAZY_ATTR = 'lazy';
+
+/**
+ * SSR-compatible ShadowRoot mock.
+ * Provides a 1-to-1 subset of the browser ShadowRoot API for server-side rendering.
+ */
+class SsrShadowRoot {
+  private _innerHTML = '';
+
+  constructor(public readonly host: SsrHTMLElement) {}
+
+  get innerHTML(): string {
+    return this._innerHTML;
+  }
+
+  set innerHTML(value: string) {
+    this._innerHTML = value;
+  }
+
+  setHTMLUnsafe(html: string, _options?: Record<string, unknown>): void {
+    this._innerHTML = html;
+  }
+
+  append(..._nodes: (Node | string)[]): void {
+    // On the server, append is a no-op — SSR content is already serialized via innerHTML.
+  }
+
+  querySelector(_selector: string): Element | null {
+    return null;
+  }
+
+  querySelectorAll(_selector: string): Element[] {
+    return [];
+  }
+
+  get childNodes(): Node[] {
+    return [];
+  }
+
+  get firstChild(): Node | null {
+    return null;
+  }
+}
+
+/**
+ * SSR-compatible HTMLElement mock.
+ * Provides a 1-to-1 subset of the browser HTMLElement API for server-side rendering.
+ * Methods that require DOM parsing (querySelector, childNodes) return empty results —
+ * SSR code should use innerHTML for content, not DOM traversal.
+ */
+class SsrHTMLElement {
+  private _innerHTML = '';
+  private _shadowRoot: SsrShadowRoot | null = null;
+  private _attributes = new Map<string, string>();
+  // Accept any CSS property assignment without error
+  readonly style = new Proxy({} as CSSStyleDeclaration, {
+    set(_target, _prop, _value) {
+      return true;
+    },
+    get(_target, prop) {
+      if (typeof prop === 'string') return '';
+      return undefined;
+    },
+  });
+
+  get innerHTML(): string {
+    return this._innerHTML;
+  }
+
+  set innerHTML(value: string) {
+    this._innerHTML = value;
+  }
+
+  get shadowRoot(): ShadowRoot | null {
+    return this._shadowRoot as unknown as ShadowRoot;
+  }
+
+  get childNodes(): Node[] {
+    return [];
+  }
+
+  get firstChild(): Node | null {
+    return null;
+  }
+
+  get attributes(): NamedNodeMap {
+    const attrs: Attr[] = [];
+    for (const [name, value] of this._attributes) {
+      attrs.push({ name, value } as Attr);
+    }
+    return attrs as unknown as NamedNodeMap;
+  }
+
+  attachShadow(_init: ShadowRootInit): ShadowRoot {
+    this._shadowRoot = new SsrShadowRoot(this);
+    return this._shadowRoot as unknown as ShadowRoot;
+  }
+
+  getAttribute(name: string): string | null {
+    return this._attributes.get(name) ?? null;
+  }
+
+  setAttribute(name: string, value: string): void {
+    this._attributes.set(name, value);
+  }
+
+  removeAttribute(name: string): void {
+    this._attributes.delete(name);
+  }
+
+  hasAttribute(name: string): boolean {
+    return this._attributes.has(name);
+  }
+
+  querySelector(_selector: string): Element | null {
+    return null;
+  }
+
+  querySelectorAll(_selector: string): Element[] {
+    return [];
+  }
+
+  append(..._nodes: (Node | string)[]): void {
+    // No-op on server — use innerHTML for content
+  }
+
+  appendChild(node: Node): Node {
+    return node;
+  }
+}
+
+/** Server-safe base class: HTMLElement in browser, SSR mock on server. */
+export const HTMLElementBase = globalThis.HTMLElement ??
+  (SsrHTMLElement as unknown as typeof HTMLElement);
+
+/**
+ * Escape HTML entities for safe display.
+ */
+export function escapeHtml(text: string): string {
+  return text
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#39;')
+    .replaceAll('`', '&#96;');
+}
+
+/**
+ * Unescape HTML entities back to plain text (server-side, no DOM).
+ */
+export function unescapeHtml(text: string): string {
+  return text
+    .replaceAll('&#96;', '`')
+    .replaceAll('&#39;', "'")
+    .replaceAll('&quot;', '"')
+    .replaceAll('&gt;', '>')
+    .replaceAll('&lt;', '<')
+    .replaceAll('&amp;', '&');
+}
+
+/**
+ * Wrap CSS in a `@scope` rule scoped to the widget's custom element tag.
+ * Used by `WidgetComponent.renderHTML()` for companion CSS files.
+ */
+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/util/logger.util.ts

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