@emkodev/emroute 1.6.2 → 1.6.4

package/dist/src/route/route.matcher.js

@@ -0,0 +1,214 @@
+/**
+ * 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) {
+    return typeof url === 'string' ? new URL(url, 'http://url-parse') : url;
+}
+/**
+ * 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 {
+    compiledRoutes = [];
+    errorBoundaries = [];
+    statusPages = new Map();
+    errorHandler;
+    /**
+     * Initialize matcher with routes manifest.
+     * Routes should be pre-sorted by specificity in the manifest.
+     */
+    constructor(manifest) {
+        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) {
+        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) {
+        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) {
+        return this.statusPages.get(status);
+    }
+    /**
+     * Get generic error handler.
+     */
+    getErrorHandler() {
+        return this.errorHandler;
+    }
+    /**
+     * Find a route by its exact pattern or by matching a pathname.
+     * Used for building route hierarchy.
+     */
+    findRoute(patternOrPath) {
+        // 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.
+     */
+    extractParams(result) {
+        const groups = result.pathname.groups;
+        const params = {};
+        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) {
+    // 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) {
+    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) {
+    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) {
+    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;
+    });
+}
+//# sourceMappingURL=route.matcher.js.map

package/dist/src/route/route.matcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route.matcher.js","sourceRoot":"","sources":["../../../src/route/route.matcher.ts"],"names":[],"mappings":"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"}

package/dist/src/type/logger.type.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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;
+}
+/** Module-level logger. Always callable — defaults to no-op. */
+export declare const logger: Logger;
+/** Replace the logger implementation. Call once at startup. */
+export declare function setLogger(impl: Logger): void;

package/dist/src/type/logger.type.js

@@ -0,0 +1,9 @@
+const noop = () => { };
+/** Module-level logger. Always callable — defaults to no-op. */
+export const logger = { error: noop, warn: noop };
+/** Replace the logger implementation. Call once at startup. */
+export function setLogger(impl) {
+    logger.error = impl.error.bind(impl);
+    logger.warn = impl.warn.bind(impl);
+}
+//# sourceMappingURL=logger.type.js.map

package/dist/src/type/logger.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.type.js","sourceRoot":"","sources":["../../../src/type/logger.type.ts"],"names":[],"mappings":"AAcA,MAAM,IAAI,GAAG,GAAG,EAAE,GAAE,CAAC,CAAC;AAEtB,gEAAgE;AAChE,MAAM,CAAC,MAAM,MAAM,GAAW,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AAE1D,+DAA+D;AAC/D,MAAM,UAAU,SAAS,CAAC,IAAY;IACpC,MAAM,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACrC,MAAM,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACrC,CAAC"}

package/dist/src/type/markdown.type.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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/dist/src/type/markdown.type.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=markdown.type.js.map

package/dist/src/type/markdown.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.type.js","sourceRoot":"","sources":["../../../src/type/markdown.type.ts"],"names":[],"mappings":""}

package/dist/src/type/route.type.d.ts

@@ -0,0 +1,112 @@
+/**
+ * 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/dist/src/type/route.type.js

@@ -0,0 +1,8 @@
+/**
+ * Router Types
+ *
+ * Native browser APIs only - no external dependencies.
+ * Follows islands architecture: pages = HTML, widgets = web components.
+ */
+export {};
+//# sourceMappingURL=route.type.js.map

package/dist/src/type/route.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route.type.js","sourceRoot":"","sources":["../../../src/type/route.type.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/src/type/widget.type.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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/dist/src/type/widget.type.js

@@ -0,0 +1,10 @@
+/**
+ * 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
+ */
+export {};
+//# sourceMappingURL=widget.type.js.map

package/dist/src/type/widget.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget.type.js","sourceRoot":"","sources":["../../../src/type/widget.type.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/src/util/html.util.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Core HTML utilities for emroute
+ */
+/** HTML attribute name marking a widget as server-rendered (skip client getData + render). */
+export declare const SSR_ATTR = "ssr";
+/** HTML attribute name for lazy-loading widgets via IntersectionObserver. */
+export declare const LAZY_ATTR = "lazy";
+/** Server-safe base class: HTMLElement in browser, SSR mock on server. */
+export declare const HTMLElementBase: {
+    new (): HTMLElement;
+    prototype: HTMLElement;
+};
+/**
+ * Escape HTML entities for safe display.
+ */
+export declare function escapeHtml(text: string): string;
+/**
+ * Unescape HTML entities back to plain text (server-side, no DOM).
+ */
+export declare function unescapeHtml(text: string): string;
+/**
+ * Wrap CSS in a `@scope` rule scoped to the widget's custom element tag.
+ * Used by `WidgetComponent.renderHTML()` for companion CSS files.
+ */
+export declare function scopeWidgetCss(css: string, widgetName: string): string;
+/**
+ * Status code to message mapping.
+ */
+export declare const STATUS_MESSAGES: Record<number, string>;

package/dist/src/util/html.util.js

@@ -0,0 +1,158 @@
+/**
+ * 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 {
+    host;
+    _innerHTML = '';
+    constructor(host) {
+        this.host = host;
+    }
+    get innerHTML() {
+        return this._innerHTML;
+    }
+    set innerHTML(value) {
+        this._innerHTML = value;
+    }
+    setHTMLUnsafe(html, _options) {
+        this._innerHTML = html;
+    }
+    append(..._nodes) {
+        // On the server, append is a no-op — SSR content is already serialized via innerHTML.
+    }
+    querySelector(_selector) {
+        return null;
+    }
+    querySelectorAll(_selector) {
+        return [];
+    }
+    get childNodes() {
+        return [];
+    }
+    get firstChild() {
+        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 {
+    _innerHTML = '';
+    _shadowRoot = null;
+    _attributes = new Map();
+    // Accept any CSS property assignment without error
+    style = new Proxy({}, {
+        set(_target, _prop, _value) {
+            return true;
+        },
+        get(_target, prop) {
+            if (typeof prop === 'string')
+                return '';
+            return undefined;
+        },
+    });
+    get innerHTML() {
+        return this._innerHTML;
+    }
+    set innerHTML(value) {
+        this._innerHTML = value;
+    }
+    get shadowRoot() {
+        return this._shadowRoot;
+    }
+    get childNodes() {
+        return [];
+    }
+    get firstChild() {
+        return null;
+    }
+    get attributes() {
+        const attrs = [];
+        for (const [name, value] of this._attributes) {
+            attrs.push({ name, value });
+        }
+        return attrs;
+    }
+    attachShadow(_init) {
+        this._shadowRoot = new SsrShadowRoot(this);
+        return this._shadowRoot;
+    }
+    getAttribute(name) {
+        return this._attributes.get(name) ?? null;
+    }
+    setAttribute(name, value) {
+        this._attributes.set(name, value);
+    }
+    removeAttribute(name) {
+        this._attributes.delete(name);
+    }
+    hasAttribute(name) {
+        return this._attributes.has(name);
+    }
+    querySelector(_selector) {
+        return null;
+    }
+    querySelectorAll(_selector) {
+        return [];
+    }
+    append(..._nodes) {
+        // No-op on server — use innerHTML for content
+    }
+    appendChild(node) {
+        return node;
+    }
+}
+/** Server-safe base class: HTMLElement in browser, SSR mock on server. */
+export const HTMLElementBase = globalThis.HTMLElement ??
+    SsrHTMLElement;
+/**
+ * Escape HTML entities for safe display.
+ */
+export function escapeHtml(text) {
+    return text
+        .replaceAll('&', '&')
+        .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) {
+    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, widgetName) {
+    return `@scope (widget-${widgetName}) {\n${css}\n}`;
+}
+/**
+ * Status code to message mapping.
+ */
+export const STATUS_MESSAGES = {
+    401: 'Unauthorized',
+    403: 'Forbidden',
+    404: 'Not Found',
+    500: 'Internal Server Error',
+};
+//# sourceMappingURL=html.util.js.map

package/dist/src/util/html.util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"html.util.js","sourceRoot":"","sources":["../../../src/util/html.util.ts"],"names":[],"mappings":"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"}