@emkodev/emroute 1.7.3 → 1.8.0-beta.2

package/{src → core}/util/widget-resolve.util.ts

@@ -5,8 +5,9 @@
  * Calls getData() + renderHTML() on widgets and injects SSR hydration data.
  */
 
-import type { Component, ComponentContext, ContextProvider } from '../component/abstract.component.ts';
-import { logger } from '../type/logger.type.ts';
+import type { Component } from '../component/abstract.component.ts';
+import type { ComponentContext, ContextProvider } from '../type/component.type.ts';
+import { type Logger, defaultLogger } from '../type/logger.type.ts';
 import type { RouteInfo } from '../type/route.type.ts';
 import { LAZY_ATTR, SSR_ATTR } from './html.util.ts';
 
@@ -15,17 +16,6 @@ export const MAX_WIDGET_DEPTH = 10;
 
 /**
  * Recursively resolve widgets in content with depth limit.
- *
- * Generic utility used by both HTML and Markdown widget resolution.
- * Each depth level processes all widgets concurrently, then recurses
- * into each rendered result to resolve nested widgets.
- *
- * @param content - Content containing widgets
- * @param parse - Find widgets in content
- * @param resolve - Resolve a single widget to rendered output
- * @param replace - Replace widgets with resolved content
- * @param depth - Current recursion depth (internal)
- * @returns Content with all widgets recursively resolved
  */
 export async function resolveRecursively<T>(
   content: string,
@@ -33,6 +23,7 @@ export async function resolveRecursively<T>(
   resolve: (widget: T) => Promise<string>,
   replace: (content: string, replacements: Map<T, string>) => string,
   depth = 0,
+  logger: Logger = defaultLogger,
 ): Promise<string> {
   if (depth >= MAX_WIDGET_DEPTH) {
     logger.warn(
@@ -49,10 +40,7 @@ export async function resolveRecursively<T>(
   await Promise.all(
     widgets.map(async (widget) => {
       let rendered = await resolve(widget);
-
-      // Recursively resolve any nested widgets in the rendered output
-      rendered = await resolveRecursively(rendered, parse, resolve, replace, depth + 1);
-
+      rendered = await resolveRecursively(rendered, parse, resolve, replace, depth + 1, logger);
       replacements.set(widget, rendered);
     }),
   );
@@ -61,18 +49,7 @@ export async function resolveRecursively<T>(
 }
 
 /**
- * Resolve <widget-*> tags in HTML by calling getData() + renderHTML()
- * via the widget registry. Injects rendered content and boolean ssr attribute.
- *
- * Supports nested widgets: if a widget's renderHTML() returns HTML containing
- * other <widget-*> tags, those will be resolved recursively up to MAX_WIDGET_DEPTH.
- *
- * Before: <widget-crypto-price coin="bitcoin"></widget-crypto-price>
- * After:  <widget-crypto-price coin="bitcoin" ssr><template shadowrootmode="open"><span>$42,000</span></template></widget-crypto-price>
- *
- * When a widget has `exposeSsrData = true`, the getData() result is serialized
- * as JSON text in the light DOM (alongside the shadow root template):
- * After:  <widget-crypto-price coin="bitcoin" ssr><template shadowrootmode="open"><span>$42,000</span></template>{"price":42000}</widget-crypto-price>
+ * Resolve <widget-*> tags in HTML by calling getData() + renderHTML().
  */
 export function resolveWidgetTags(
   html: string,
@@ -80,20 +57,16 @@ export function resolveWidgetTags(
   routeInfo: RouteInfo,
   loadFiles?: (
     widgetName: string,
-    declaredFiles?: { html?: string; md?: string; css?: string },
   ) => Promise<{ html?: string; md?: string; css?: string }>,
   contextProvider?: ContextProvider,
+  logger: Logger = defaultLogger,
 ): Promise<string> {
   const tagPattern =
     /<widget-(?<name>[a-z][a-z0-9-]*)(?<attrs>\s[^>]*)?>(?<content>.*?)<\/widget-\k<name>>/gis;
 
-  // Wrapping info stored per-match so replace() can apply it after recursion
   const wrappers = new Map<RegExpExecArray, { tagName: string; attrs: string; ssrData: string }>();
-
-  // Matches standalone ssr attribute (boolean or with value), not as substring of another value
   const ssrAttrPattern = new RegExp(`\\s${SSR_ATTR}(?:\\s|=|$)`);
 
-  // Parse: find unprocessed widget tags
   const parse = (content: string) => {
     const matches = content.matchAll(tagPattern).toArray();
     return matches.filter((match) => {
@@ -102,20 +75,19 @@ export function resolveWidgetTags(
     });
   };
 
-  // Resolve: render a single widget's inner content (no outer tag wrapping — that's in replace)
   const resolve = async (match: RegExpExecArray): Promise<string> => {
-    const widgetName = match.groups!.name;
+    const widgetName = match.groups!.name!;
     const attrsString = match.groups!.attrs?.trim() ?? '';
     const widget = registry.get(widgetName);
 
-    if (!widget) return match[0]; // no widget found — leave original tag as-is
+    if (!widget) return match[0];
 
     const params = parseAttrsToParams(attrsString);
 
     try {
       let files: { html?: string; md?: string; css?: string } | undefined;
       if (loadFiles) {
-        files = await loadFiles(widgetName, widget.files);
+        files = await loadFiles(widgetName);
       }
 
       const baseContext: ComponentContext = {
@@ -129,7 +101,6 @@ export function resolveWidgetTags(
       const data = await widget.getData({ params, context });
       const rendered = widget.renderHTML({ data, params, context });
 
-      // Store wrapping info — applied in replace() after recursion resolves nested widgets
       wrappers.set(match, {
         tagName: `widget-${widgetName}`,
         attrs: attrsString ? ` ${attrsString}` : '',
@@ -142,11 +113,10 @@ export function resolveWidgetTags(
         `[SSR HTML] Widget "${widgetName}" render failed`,
         e instanceof Error ? e : undefined,
       );
-      return match[0]; // render failed — leave original tag as-is
+      return match[0];
     }
   };
 
-  // Replace: wrap resolved content in outer tag + DSD template, then substitute by index
   const replace = (content: string, replacements: Map<RegExpExecArray, string>) => {
     let result = content;
     const entries = [...replacements.entries()].sort((a, b) => b[0].index! - a[0].index!);
@@ -157,16 +127,16 @@ export function resolveWidgetTags(
       const lightDomData = wrap?.ssrData ? wrap.ssrData : '';
       const replacement = wrap
         ? `<${wrap.tagName}${wrap.attrs} ${SSR_ATTR}><template shadowrootmode="open">${innerHtml}</template>${lightDomData}</${wrap.tagName}>`
-        : innerHtml; // no wrapper = unresolved widget, innerHtml is the original tag
+        : innerHtml;
       result = result.slice(0, start) + replacement + result.slice(end);
     }
     return result;
   };
 
-  return resolveRecursively(html, parse, resolve, replace);
+  return resolveRecursively(html, parse, resolve, replace, 0, logger);
 }
 
-/** Parse HTML attribute string into params object (kebab→camelCase, JSON.parse with string fallback). */
+/** Parse HTML attribute string into params object. */
 export function parseAttrsToParams(attrsString: string): Record<string, unknown> {
   const params: Record<string, unknown> = {};
   if (!attrsString) return params;
@@ -175,7 +145,7 @@ export function parseAttrsToParams(attrsString: string): Record<string, unknown>
     /(?<attr>[a-z][a-z0-9-]*)(?:="(?<dq>[^"]*)"|='(?<sq>[^']*)'|=(?<uq>[^\s>]+))?/gi;
   for (const match of attrsString.matchAll(attrPattern)) {
     const { attr: attrName, dq, sq, uq } = match.groups!;
-    if (attrName === SSR_ATTR || attrName === LAZY_ATTR) continue;
+    if (!attrName || attrName === SSR_ATTR || attrName === LAZY_ATTR) continue;
     const key = attrName.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
     const rawValue = dq ?? sq ?? uq;
     if (rawValue === undefined) {
@@ -196,7 +166,6 @@ export function parseAttrsToParams(attrsString: string): Record<string, unknown>
   return params;
 }
 
-/** Escape a value for use in a single-quoted HTML attribute. */
 function escapeAttr(value: string): string {
   return value.replaceAll('&', '&amp;').replaceAll("'", '&#39;');
 }

package/{src → core}/widget/widget.parser.ts

@@ -11,36 +11,25 @@
 
 import type { ParsedWidgetBlock } from '../type/widget.type.ts';
 
-/**
- * Pattern to match widget fenced code blocks.
- * Captures: widget name, params content
- */
 const WIDGET_PATTERN = /```widget:(?<name>[a-z][a-z0-9-]*)\n(?<params>.*?)```/gs;
 
-/**
- * Parse all widget blocks from markdown content.
- *
- * @param markdown - Markdown content to parse
- * @returns Array of parsed widget blocks with positions
- */
 export function parseWidgetBlocks(markdown: string): ParsedWidgetBlock[] {
   const blocks: ParsedWidgetBlock[] = [];
 
   for (const match of markdown.matchAll(WIDGET_PATTERN)) {
     const fullMatch = match[0];
     const { name: widgetName, params: paramsRaw } = match.groups!;
-    const paramsJson = paramsRaw.trim();
+    const paramsJson = paramsRaw!.trim();
     const startIndex = match.index;
 
     const block: ParsedWidgetBlock = {
       fullMatch,
-      widgetName,
+      widgetName: widgetName!,
       params: null,
       startIndex,
       endIndex: startIndex + fullMatch.length,
     };
 
-    // Parse JSON params if present
     if (paramsJson) {
       try {
         const parsed = JSON.parse(paramsJson);
@@ -53,7 +42,6 @@ export function parseWidgetBlocks(markdown: string): ParsedWidgetBlock[] {
         block.parseError = `Invalid JSON: ${e instanceof Error ? e.message : String(e)}`;
       }
     } else {
-      // Empty params is valid - use empty object
       block.params = {};
     }
 
@@ -63,19 +51,10 @@ export function parseWidgetBlocks(markdown: string): ParsedWidgetBlock[] {
   return blocks;
 }
 
-/**
- * Replace widget blocks in markdown with rendered content.
- *
- * @param markdown - Original markdown content
- * @param replacements - Map of parsed blocks to replacement strings
- * @returns Markdown with widget blocks replaced
- */
 export function replaceWidgetBlocks(
   markdown: string,
   replacements: Map<ParsedWidgetBlock, string>,
 ): string {
-  // Sort blocks by position descending to replace from end first
-  // This preserves indices during replacement
   const sortedBlocks = [...replacements.entries()].sort(
     ([a], [b]) => b.startIndex - a.startIndex,
   );

package/core/widget/widget.registry.ts

@@ -0,0 +1,36 @@
+/**
+ * Widget Registry
+ *
+ * Name → Component lookup. Used by all renderers.
+ * Pages are NOT in this registry — they live in the routes manifest.
+ */
+
+import type { WidgetComponent } from '../component/widget.component.ts';
+
+interface RegistryEntry {
+  widget: WidgetComponent;
+  modulePath?: string | undefined;
+}
+
+export class WidgetRegistry {
+  private entries = new Map<string, RegistryEntry>();
+
+  add(widget: WidgetComponent, modulePath?: string): void {
+    this.entries.set(widget.name, { widget, modulePath });
+  }
+
+  get(name: string): WidgetComponent | undefined {
+    return this.entries.get(name)?.widget;
+  }
+
+  getModulePath(name: string): string | undefined {
+    return this.entries.get(name)?.modulePath;
+  }
+
+  [Symbol.iterator](): IterableIterator<WidgetComponent> {
+    const entries = this.entries.values();
+    return (function* () {
+      for (const entry of entries) yield entry.widget;
+    })();
+  }
+}

package/dist/core/component/abstract.component.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Component Base Class
+ *
+ * Everything is a Component: pages and widgets.
+ * Components render differently based on context:
+ * - /md/* → Markdown (LLMs, text clients)
+ * - /html/* → Pre-rendered HTML (SSR)
+ * - SPA → Hydrated custom elements
+ */
+import type { ComponentContext } from '../type/component.type.ts';
+export declare abstract class Component<TParams = unknown, TData = unknown, TContext extends ComponentContext = ComponentContext> {
+    readonly DataArgs: {
+        params: TParams;
+        signal?: AbortSignal;
+        context: TContext;
+    };
+    readonly RenderArgs: {
+        data: TData | null;
+        params: TParams;
+        context: TContext;
+    };
+    abstract readonly name: string;
+    /** Host element reference, set by ComponentElement in the browser. */
+    element?: HTMLElement | undefined;
+    /** Associated file paths for pre-loaded content (html, md, css). */
+    readonly files?: {
+        html?: string;
+        md?: string;
+        css?: string;
+    };
+    /**
+     * When true, SSR serializes the getData() result into the element's
+     * light DOM so the client can access it immediately in hydrate()
+     * without re-fetching.
+     */
+    readonly exposeSsrData?: boolean;
+    abstract getData(args: this['DataArgs']): Promise<TData | null>;
+    abstract renderMarkdown(args: this['RenderArgs']): string;
+    renderHTML(args: this['RenderArgs']): string;
+    hydrate?(args: this['RenderArgs']): void;
+    destroy?(): void;
+    validateParams?(params: TParams): string | undefined;
+    renderError(args: {
+        error: unknown;
+        params: TParams;
+    }): string;
+    renderMarkdownError(error: unknown): string;
+}

package/dist/core/component/abstract.component.js

@@ -0,0 +1,42 @@
+/**
+ * Component Base Class
+ *
+ * Everything is a Component: pages and widgets.
+ * Components render differently based on context:
+ * - /md/* → Markdown (LLMs, text clients)
+ * - /html/* → Pre-rendered HTML (SSR)
+ * - SPA → Hydrated custom elements
+ */
+import { escapeHtml } from "../util/html.util.js";
+export class Component {
+    /** Host element reference, set by ComponentElement in the browser. */
+    element;
+    /** Associated file paths for pre-loaded content (html, md, css). */
+    files;
+    /**
+     * When true, SSR serializes the getData() result into the element's
+     * light DOM so the client can access it immediately in hydrate()
+     * without re-fetching.
+     */
+    exposeSsrData;
+    renderHTML(args) {
+        if (args.data === null) {
+            return `<div data-component="${this.name}">Loading...</div>`;
+        }
+        const markdown = this.renderMarkdown({
+            data: args.data,
+            params: args.params,
+            context: args.context,
+        });
+        return `<div data-component="${this.name}" data-markdown>${escapeHtml(markdown)}</div>`;
+    }
+    renderError(args) {
+        const msg = args.error instanceof Error ? args.error.message : String(args.error);
+        return `<div data-component="${this.name}">Error: ${escapeHtml(msg)}</div>`;
+    }
+    renderMarkdownError(error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        return `> **Error** (\`${this.name}\`): ${msg}`;
+    }
+}
+//# sourceMappingURL=abstract.component.js.map

package/dist/core/component/abstract.component.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"abstract.component.js","sourceRoot":"","sources":["../../../core/component/abstract.component.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAElD,MAAM,OAAgB,SAAS;IAmB7B,sEAAsE;IACtE,OAAO,CAA2B;IAElC,oEAAoE;IAC3D,KAAK,CAAgD;IAE9D;;;;OAIG;IACM,aAAa,CAAW;IAKjC,UAAU,CAAC,IAAwB;QACjC,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;YACvB,OAAO,wBAAwB,IAAI,CAAC,IAAI,oBAAoB,CAAC;QAC/D,CAAC;QACD,MAAM,QAAQ,GAAG,IAAI,CAAC,cAAc,CAAC;YACnC,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,OAAO,EAAE,IAAI,CAAC,OAAO;SACtB,CAAC,CAAC;QACH,OAAO,wBAAwB,IAAI,CAAC,IAAI,mBAAmB,UAAU,CAAC,QAAQ,CAAC,QAAQ,CAAC;IAC1F,CAAC;IAMD,WAAW,CAAC,IAAyC;QACnD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAClF,OAAO,wBAAwB,IAAI,CAAC,IAAI,YAAY,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC;IAC9E,CAAC;IAED,mBAAmB,CAAC,KAAc;QAChC,MAAM,GAAG,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACnE,OAAO,kBAAkB,IAAI,CAAC,IAAI,QAAQ,GAAG,EAAE,CAAC;IAClD,CAAC;CACF"}

package/dist/core/component/page.component.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Page Component
+ *
+ * Params come from URL, context carries file content.
+ *
+ * Default implementations follow the fallback table:
+ * - renderHTML: html file → md via <mark-down> → <router-slot /> (non-leaf only)
+ * - renderMarkdown: md file → ```router-slot\n``` (non-leaf only)
+ * - getData: no-op (returns null)
+ */
+import { Component } from './abstract.component.ts';
+import type { ComponentContext } from '../type/component.type.ts';
+export declare class PageComponent<TParams extends Record<string, string> = Record<string, string>, TData = unknown, TContext extends ComponentContext = ComponentContext> extends Component<TParams, TData, TContext> {
+    readonly name: string;
+    readonly pattern?: string;
+    getData(_args: this['DataArgs']): Promise<TData | null>;
+    renderHTML(args: this['RenderArgs']): string;
+    renderMarkdown(args: this['RenderArgs']): string;
+    getTitle(_args: this['RenderArgs']): string | undefined;
+}
+/** Shared default instance used by renderers when no custom .page.ts exists. */
+declare const _default: PageComponent<Record<string, string>, unknown, ComponentContext>;
+export default _default;

package/dist/core/component/page.component.js

@@ -0,0 +1,49 @@
+/**
+ * Page Component
+ *
+ * Params come from URL, context carries file content.
+ *
+ * Default implementations follow the fallback table:
+ * - renderHTML: html file → md via <mark-down> → <router-slot /> (non-leaf only)
+ * - renderMarkdown: md file → ```router-slot\n``` (non-leaf only)
+ * - getData: no-op (returns null)
+ */
+import { Component } from "./abstract.component.js";
+import { escapeHtml } from "../util/html.util.js";
+export class PageComponent extends Component {
+    name = 'page';
+    pattern;
+    getData(_args) {
+        return Promise.resolve(null);
+    }
+    renderHTML(args) {
+        const files = args.context.files;
+        const style = files?.css ? `<style>${files.css}</style>\n` : '';
+        if (files?.html) {
+            let html = style + files.html;
+            if (files.md && html.includes('<mark-down></mark-down>')) {
+                html = html.replace('<mark-down></mark-down>', `<mark-down>${escapeHtml(files.md)}</mark-down>`);
+            }
+            return html;
+        }
+        if (files?.md) {
+            const hasSlot = files.md.includes('```router-slot');
+            const slot = args.context.isLeaf || hasSlot ? '' : '\n<router-slot></router-slot>';
+            return `${style}<mark-down>${escapeHtml(files.md)}</mark-down>${slot}`;
+        }
+        return args.context.isLeaf ? '' : '<router-slot></router-slot>';
+    }
+    renderMarkdown(args) {
+        const files = args.context.files;
+        if (files?.md) {
+            return files.md;
+        }
+        return args.context.isLeaf ? '' : '```router-slot\n```';
+    }
+    getTitle(_args) {
+        return undefined;
+    }
+}
+/** Shared default instance used by renderers when no custom .page.ts exists. */
+export default new PageComponent();
+//# sourceMappingURL=page.component.js.map

package/dist/core/component/page.component.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"page.component.js","sourceRoot":"","sources":["../../../core/component/page.component.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEpD,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAElD,MAAM,OAAO,aAIX,SAAQ,SAAmC;IACzB,IAAI,GAAW,MAAM,CAAC;IAC/B,OAAO,CAAU;IAEjB,OAAO,CACd,KAAuB;QAEvB,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;IAEQ,UAAU,CACjB,IAAwB;QAExB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC;QACjC,MAAM,KAAK,GAAG,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,UAAU,KAAK,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC;QAEhE,IAAI,KAAK,EAAE,IAAI,EAAE,CAAC;YAChB,IAAI,IAAI,GAAG,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC;YAC9B,IAAI,KAAK,CAAC,EAAE,IAAI,IAAI,CAAC,QAAQ,CAAC,yBAAyB,CAAC,EAAE,CAAC;gBACzD,IAAI,GAAG,IAAI,CAAC,OAAO,CACjB,yBAAyB,EACzB,cAAc,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC,cAAc,CACjD,CAAC;YACJ,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;QAED,IAAI,KAAK,EAAE,EAAE,EAAE,CAAC;YACd,MAAM,OAAO,GAAG,KAAK,CAAC,EAAE,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAC;YACpD,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,+BAA+B,CAAC;YACnF,OAAO,GAAG,KAAK,cAAc,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC,eAAe,IAAI,EAAE,CAAC;QACzE,CAAC;QAED,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,6BAA6B,CAAC;IAClE,CAAC;IAEQ,cAAc,CACrB,IAAwB;QAExB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC;QAEjC,IAAI,KAAK,EAAE,EAAE,EAAE,CAAC;YACd,OAAO,KAAK,CAAC,EAAE,CAAC;QAClB,CAAC;QAED,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,qBAAqB,CAAC;IAC1D,CAAC;IAED,QAAQ,CACN,KAAyB;QAEzB,OAAO,SAAS,CAAC;IACnB,CAAC;CACF;AAED,gFAAgF;AAChF,eAAe,IAAI,aAAa,EAAE,CAAC"}

package/dist/core/component/widget.component.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Widget Component
+ *
+ * Embeddable unit within page content. Everything reusable that is not
+ * a page is a Widget. Widgets render across all contexts (HTML, Markdown, SPA)
+ * and are resolved by name via WidgetRegistry.
+ *
+ * Default rendering fallback chains (parallel to PageComponent):
+ * - renderHTML:     html file → md file in <mark-down> → base Component default
+ * - renderMarkdown: md file → ''
+ */
+import { Component } from './abstract.component.ts';
+import type { ComponentContext } from '../type/component.type.ts';
+export declare abstract class WidgetComponent<TParams = unknown, TData = unknown, TContext extends ComponentContext = ComponentContext> extends Component<TParams, TData, TContext> {
+    renderHTML(args: this['RenderArgs']): string;
+    renderMarkdown(args: this['RenderArgs']): string;
+}

package/dist/core/component/widget.component.js

@@ -0,0 +1,37 @@
+/**
+ * Widget Component
+ *
+ * Embeddable unit within page content. Everything reusable that is not
+ * a page is a Widget. Widgets render across all contexts (HTML, Markdown, SPA)
+ * and are resolved by name via WidgetRegistry.
+ *
+ * Default rendering fallback chains (parallel to PageComponent):
+ * - renderHTML:     html file → md file in <mark-down> → base Component default
+ * - renderMarkdown: md file → ''
+ */
+import { Component } from "./abstract.component.js";
+import { escapeHtml, scopeWidgetCss } from "../util/html.util.js";
+export class WidgetComponent extends Component {
+    renderHTML(args) {
+        const files = args.context.files;
+        const style = files?.css ? `<style>${scopeWidgetCss(files.css, this.name)}</style>\n` : '';
+        if (files?.html) {
+            return style + files.html;
+        }
+        if (files?.md) {
+            return `${style}<mark-down>${escapeHtml(files.md)}</mark-down>`;
+        }
+        if (style) {
+            return style + super.renderHTML(args);
+        }
+        return super.renderHTML(args);
+    }
+    renderMarkdown(args) {
+        const files = args.context.files;
+        if (files?.md) {
+            return files.md;
+        }
+        return '';
+    }
+}
+//# sourceMappingURL=widget.component.js.map

package/dist/core/component/widget.component.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget.component.js","sourceRoot":"","sources":["../../../core/component/widget.component.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEpD,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAElE,MAAM,OAAgB,eAIpB,SAAQ,SAAmC;IAClC,UAAU,CACjB,IAAwB;QAExB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC;QACjC,MAAM,KAAK,GAAG,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,UAAU,cAAc,CAAC,KAAK,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC;QAE3F,IAAI,KAAK,EAAE,IAAI,EAAE,CAAC;YAChB,OAAO,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC;QAC5B,CAAC;QAED,IAAI,KAAK,EAAE,EAAE,EAAE,CAAC;YACd,OAAO,GAAG,KAAK,cAAc,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC,cAAc,CAAC;QAClE,CAAC;QAED,IAAI,KAAK,EAAE,CAAC;YACV,OAAO,KAAK,GAAG,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QACxC,CAAC;QAED,OAAO,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;IAChC,CAAC;IAEQ,cAAc,CACrB,IAAwB;QAExB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC;QAEjC,IAAI,KAAK,EAAE,EAAE,EAAE,CAAC;YACd,OAAO,KAAK,CAAC,EAAE,CAAC;QAClB,CAAC;QAED,OAAO,EAAE,CAAC;IACZ,CAAC;CACF"}

package/dist/core/pipeline/pipeline.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Pipeline
+ *
+ * Orchestration layer between Router, Runtime, and Component.
+ *
+ * Owns:
+ * - Route matching (reads manifest from Runtime, walks RouteNode tree)
+ * - Module loading (delegates to Runtime)
+ * - Companion file reading (delegates to Runtime)
+ * - ComponentContext building
+ * - Route hierarchy construction
+ *
+ * Does NOT own:
+ * - Rendering (that's Renderer)
+ * - HTTP routing / base paths (that's Server)
+ * - Storage I/O (that's Runtime)
+ * - Navigation events (that's the browser adapter)
+ */
+import type { RouteConfig, MatchedRoute, RouteInfo } from '../type/route.type.ts';
+import type { ComponentContext, ContextProvider, FileContents } from '../type/component.type.ts';
+import type { Runtime } from '../runtime/abstract.runtime.ts';
+import { type Logger } from '../type/logger.type.ts';
+/** Default root route — renders a slot for child routes. */
+export declare const DEFAULT_ROOT_ROUTE: RouteConfig;
+/** Pipeline configuration. */
+export interface PipelineOptions {
+    runtime: Runtime;
+    contextProvider?: ContextProvider;
+    /** Pre-bundled module loaders (browser boot passes these). */
+    moduleLoaders?: Record<string, () => Promise<unknown>>;
+    logger?: Logger;
+}
+export declare class Pipeline {
+    private readonly runtime;
+    readonly contextProvider: ContextProvider | undefined;
+    readonly logger: Logger;
+    private readonly moduleLoaders;
+    constructor(options: PipelineOptions);
+    private getResolver;
+    match(url: URL): Promise<MatchedRoute | undefined>;
+    findRoute(pattern: string): Promise<RouteConfig | undefined>;
+    findErrorBoundary(pathname: string): Promise<{
+        pattern: string;
+        modulePath: string;
+    } | undefined>;
+    getStatusPage(status: number): Promise<RouteConfig | undefined>;
+    getErrorHandler(): Promise<RouteConfig | undefined>;
+    buildRouteHierarchy(pattern: string): string[];
+    loadModule<T>(modulePath: string): Promise<T>;
+    /**
+     * Get inlined `__files` from a loaded module (merged module pattern).
+     */
+    getModuleFiles(mod: unknown): FileContents | undefined;
+    loadFiles(files: {
+        html?: string;
+        md?: string;
+        css?: string;
+    }): Promise<FileContents>;
+    toRouteInfo(matched: MatchedRoute, url: URL): RouteInfo;
+    buildContext(routeInfo: RouteInfo, route: RouteConfig, signal?: AbortSignal, isLeaf?: boolean, loadedModule?: unknown): Promise<ComponentContext>;
+}