@emkodev/emroute 1.6.2 → 1.6.4

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

@@ -0,0 +1,26 @@
+/**
+ * Logger Utility
+ *
+ * Provides structured logging for emroute internals.
+ * Enable via localStorage: localStorage.setItem('emroute:debug', 'true')
+ */
+export declare const logger: {
+    /** Enable debug logging (persists in localStorage) */
+    enable(): void;
+    /** Disable debug logging */
+    disable(): void;
+    /** Log general information */
+    info(category: string, message: string, data?: unknown): void;
+    /** Log navigation events */
+    nav(action: string, from: string, to: string, data?: Record<string, unknown>): void;
+    /** Log rendering events */
+    render(component: string, route: string, mode?: string): void;
+    /** Log link interception */
+    link(action: "intercept" | "passthrough", href: string, reason?: string): void;
+    /** Log widget lifecycle */
+    widget(event: string, name: string, data?: unknown): void;
+    /** Log warnings (always shown, not gated by debug flag) */
+    warn(message: string): void;
+    /** Log SSR adoption */
+    ssr(action: string, route: string): void;
+};

package/dist/src/util/logger.util.js

@@ -0,0 +1,80 @@
+/**
+ * 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() {
+    if (typeof globalThis.localStorage === 'undefined')
+        return false;
+    return globalThis.localStorage.getItem(STORAGE_KEY) === 'true';
+}
+export const logger = {
+    /** Enable debug logging (persists in localStorage) */
+    enable() {
+        if (typeof globalThis.localStorage !== 'undefined') {
+            globalThis.localStorage.setItem(STORAGE_KEY, 'true');
+            console.log(`${PREFIX} Debug logging enabled`);
+        }
+    },
+    /** Disable debug logging */
+    disable() {
+        if (typeof globalThis.localStorage !== 'undefined') {
+            globalThis.localStorage.removeItem(STORAGE_KEY);
+            console.log(`${PREFIX} Debug logging disabled`);
+        }
+    },
+    /** Log general information */
+    info(category, message, data) {
+        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, from, to, data) {
+        if (!isEnabled())
+            return;
+        console.log(`${PREFIX} [nav] ${action}:`, { from, to, ...(data ?? {}) });
+    },
+    /** Log rendering events */
+    render(component, route, mode) {
+        if (!isEnabled())
+            return;
+        const modeStr = mode ? ` [mode=${mode}]` : '';
+        console.log(`${PREFIX} [render]${modeStr} ${component} → ${route}`);
+    },
+    /** Log link interception */
+    link(action, href, reason) {
+        if (!isEnabled())
+            return;
+        const reasonStr = reason ? ` (${reason})` : '';
+        console.log(`${PREFIX} [link] ${action}: ${href}${reasonStr}`);
+    },
+    /** Log widget lifecycle */
+    widget(event, name, data) {
+        if (!isEnabled())
+            return;
+        console.log(`${PREFIX} [widget] ${event}: ${name}`, data ?? '');
+    },
+    /** Log warnings (always shown, not gated by debug flag) */
+    warn(message) {
+        console.warn(`${PREFIX}`, message);
+    },
+    /** Log SSR adoption */
+    ssr(action, route) {
+        if (!isEnabled())
+            return;
+        console.log(`${PREFIX} [ssr] ${action}: ${route}`);
+    },
+};
+// Expose globally for console access
+globalThis.__emroute_logger = logger;
+//# sourceMappingURL=logger.util.js.map

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

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

package/dist/src/util/widget-resolve.util.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Widget Resolve Utilities
+ *
+ * Server-side resolution of <widget-*> tags in HTML.
+ * Calls getData() + renderHTML() on widgets and injects SSR hydration data.
+ */
+import type { Component, ContextProvider } from '../component/abstract.component.ts';
+import type { RouteInfo } from '../type/route.type.ts';
+/** Maximum nesting depth for widgets to prevent infinite loops */
+export declare 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 declare function resolveRecursively<T>(content: string, parse: (content: string) => T[], resolve: (widget: T) => Promise<string>, replace: (content: string, replacements: Map<T, string>) => string, depth?: number): Promise<string>;
+/**
+ * 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>
+ */
+export declare function resolveWidgetTags(html: string, registry: {
+    get(name: string): Component | undefined;
+}, routeInfo: RouteInfo, loadFiles?: (widgetName: string, declaredFiles?: {
+    html?: string;
+    md?: string;
+    css?: string;
+}) => Promise<{
+    html?: string;
+    md?: string;
+    css?: string;
+}>, contextProvider?: ContextProvider): Promise<string>;
+/** Parse HTML attribute string into params object (kebab→camelCase, JSON.parse with string fallback). */
+export declare function parseAttrsToParams(attrsString: string): Record<string, unknown>;

package/dist/src/util/widget-resolve.util.js

@@ -0,0 +1,149 @@
+/**
+ * Widget Resolve Utilities
+ *
+ * Server-side resolution of <widget-*> tags in HTML.
+ * Calls getData() + renderHTML() on widgets and injects SSR hydration data.
+ */
+import { logger } from "../type/logger.type.js";
+import { LAZY_ATTR, SSR_ATTR } from "./html.util.js";
+/** Maximum nesting depth for widgets to prevent infinite loops */
+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(content, parse, resolve, replace, depth = 0) {
+    if (depth >= MAX_WIDGET_DEPTH) {
+        logger.warn(`Widget nesting depth limit reached (${MAX_WIDGET_DEPTH}). ` +
+            'Possible circular dependency or excessive nesting.');
+        return content;
+    }
+    const widgets = parse(content);
+    if (widgets.length === 0)
+        return content;
+    const replacements = new Map();
+    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);
+        replacements.set(widget, rendered);
+    }));
+    return replace(content, replacements);
+}
+/**
+ * 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>
+ */
+export function resolveWidgetTags(html, registry, routeInfo, loadFiles, contextProvider) {
+    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();
+    // 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) => {
+        const matches = content.matchAll(tagPattern).toArray();
+        return matches.filter((match) => {
+            const attrsString = match.groups.attrs || '';
+            return !ssrAttrPattern.test(attrsString);
+        });
+    };
+    // Resolve: render a single widget's inner content (no outer tag wrapping — that's in replace)
+    const resolve = async (match) => {
+        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
+        const params = parseAttrsToParams(attrsString);
+        try {
+            let files;
+            if (loadFiles) {
+                files = await loadFiles(widgetName, widget.files);
+            }
+            const baseContext = { ...routeInfo, files };
+            const context = contextProvider ? contextProvider(baseContext) : baseContext;
+            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}` : '',
+                ssrData: widget.exposeSsrData ? escapeAttr(JSON.stringify(data)) : '',
+            });
+            return rendered;
+        }
+        catch (e) {
+            logger.error(`[SSR HTML] Widget "${widgetName}" render failed`, e instanceof Error ? e : undefined);
+            return match[0]; // render failed — leave original tag as-is
+        }
+    };
+    // Replace: wrap resolved content in outer tag + DSD template, then substitute by index
+    const replace = (content, replacements) => {
+        let result = content;
+        const entries = [...replacements.entries()].sort((a, b) => b[0].index - a[0].index);
+        for (const [match, innerHtml] of entries) {
+            const start = match.index;
+            const end = start + match[0].length;
+            const wrap = wrappers.get(match);
+            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
+            result = result.slice(0, start) + replacement + result.slice(end);
+        }
+        return result;
+    };
+    return resolveRecursively(html, parse, resolve, replace);
+}
+/** Parse HTML attribute string into params object (kebab→camelCase, JSON.parse with string fallback). */
+export function parseAttrsToParams(attrsString) {
+    const params = {};
+    if (!attrsString)
+        return params;
+    const attrPattern = /(?<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;
+        const key = attrName.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+        const rawValue = dq ?? sq ?? uq;
+        if (rawValue === undefined) {
+            params[key] = '';
+            continue;
+        }
+        const raw = rawValue.replaceAll('&amp;', '&').replaceAll('&#39;', "'").replaceAll('&quot;', '"');
+        try {
+            params[key] = JSON.parse(raw);
+        }
+        catch {
+            params[key] = raw;
+        }
+    }
+    return params;
+}
+/** Escape a value for use in a single-quoted HTML attribute. */
+function escapeAttr(value) {
+    return value.replaceAll('&', '&amp;').replaceAll("'", '&#39;');
+}
+//# sourceMappingURL=widget-resolve.util.js.map

package/dist/src/util/widget-resolve.util.js.map

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

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

@@ -0,0 +1,48 @@
+/**
+ * Built-in Breadcrumb Widget
+ *
+ * Renders breadcrumb navigation from the current URL path.
+ * Uses /html/ prefix for links (content-first routing convention).
+ *
+ * Usage in .page.html:
+ *   <widget-breadcrumb></widget-breadcrumb>
+ *   <widget-breadcrumb separator=" / " class="my-breadcrumbs"></widget-breadcrumb>
+ *
+ * Usage in .page.md:
+ *   ```widget:breadcrumb
+ *   {}
+ *   ```
+ */
+import { WidgetComponent } from '../component/widget.component.ts';
+import type { ComponentContext } from '../component/abstract.component.ts';
+interface BreadcrumbParams {
+    separator?: string;
+    class?: string;
+}
+interface BreadcrumbSegment {
+    label: string;
+    href: string;
+}
+interface BreadcrumbData {
+    segments: BreadcrumbSegment[];
+}
+export declare class BreadcrumbWidget extends WidgetComponent<BreadcrumbParams, BreadcrumbData> {
+    readonly name = "breadcrumb";
+    getData(args: {
+        params: BreadcrumbParams;
+        signal?: AbortSignal;
+        context: ComponentContext;
+    }): Promise<BreadcrumbData | null>;
+    private resolvePathname;
+    renderHTML(args: {
+        data: BreadcrumbData | null;
+        params: BreadcrumbParams;
+        context: ComponentContext;
+    }): string;
+    renderMarkdown(args: {
+        data: BreadcrumbData | null;
+        params: BreadcrumbParams;
+        context: ComponentContext;
+    }): string;
+}
+export {};

package/dist/src/widget/breadcrumb.widget.js

@@ -0,0 +1,72 @@
+/**
+ * Built-in Breadcrumb Widget
+ *
+ * Renders breadcrumb navigation from the current URL path.
+ * Uses /html/ prefix for links (content-first routing convention).
+ *
+ * Usage in .page.html:
+ *   <widget-breadcrumb></widget-breadcrumb>
+ *   <widget-breadcrumb separator=" / " class="my-breadcrumbs"></widget-breadcrumb>
+ *
+ * Usage in .page.md:
+ *   ```widget:breadcrumb
+ *   {}
+ *   ```
+ */
+import { WidgetComponent } from "../component/widget.component.js";
+import { escapeHtml } from "../util/html.util.js";
+import { DEFAULT_BASE_PATH } from "../route/route.core.js";
+const DEFAULT_HTML_SEPARATOR = ' \u203A ';
+const DEFAULT_MD_SEPARATOR = ' > ';
+export class BreadcrumbWidget extends WidgetComponent {
+    name = 'breadcrumb';
+    getData(args) {
+        const htmlBase = args.context.basePath ?? DEFAULT_BASE_PATH.html;
+        const pathname = args.context.pathname ?? this.resolvePathname(htmlBase);
+        // Skip basePath segments for display — only show route segments
+        const barePathname = htmlBase && pathname.startsWith(htmlBase)
+            ? pathname.slice(htmlBase.length) || '/'
+            : pathname;
+        const parts = barePathname.split('/').filter(Boolean);
+        const segments = [
+            { label: 'Home', href: htmlBase + '/' },
+        ];
+        let accumulated = htmlBase;
+        for (const part of parts) {
+            accumulated += '/' + part;
+            segments.push({
+                label: part.charAt(0).toUpperCase() + part.slice(1).replace(/-/g, ' '),
+                href: accumulated,
+            });
+        }
+        return Promise.resolve({ segments });
+    }
+    resolvePathname(htmlBase) {
+        if (typeof globalThis.location === 'undefined')
+            return htmlBase + '/';
+        return location.pathname;
+    }
+    renderHTML(args) {
+        if (!args.data || args.data.segments.length === 0)
+            return '';
+        const sep = args.params.separator ?? DEFAULT_HTML_SEPARATOR;
+        const segments = args.data.segments;
+        const items = segments.map((seg, i) => {
+            const escaped = escapeHtml(seg.label);
+            if (i === segments.length - 1) {
+                return `<span aria-current="page">${escaped}</span>`;
+            }
+            return `<a href="${escapeHtml(seg.href)}">${escaped}</a>`;
+        });
+        return `<nav aria-label="Breadcrumb">${items.join(escapeHtml(sep))}</nav>`;
+    }
+    renderMarkdown(args) {
+        if (!args.data || args.data.segments.length === 0)
+            return '';
+        const sep = args.params.separator ?? DEFAULT_MD_SEPARATOR;
+        return args.data.segments
+            .map((seg, i, arr) => i === arr.length - 1 ? `**${seg.label}**` : `[${seg.label}](${seg.href})`)
+            .join(sep);
+    }
+}
+//# sourceMappingURL=breadcrumb.widget.js.map

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

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

package/dist/src/widget/page-title.widget.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Built-in Page Title Widget
+ *
+ * Sets document.title from .page.html and .page.md files without needing
+ * a .page.ts component. Renders no visible output.
+ *
+ * Usage in .page.html:
+ *   <widget-page-title title="About Us"></widget-page-title>
+ */
+import { WidgetComponent } from '../component/widget.component.ts';
+interface PageTitleParams {
+    title: string;
+}
+interface PageTitleData {
+    title: string;
+}
+export declare class PageTitleWidget extends WidgetComponent<PageTitleParams, PageTitleData> {
+    readonly name = "page-title";
+    getData(args: {
+        params: PageTitleParams;
+        signal?: AbortSignal;
+    }): Promise<PageTitleData | null>;
+    renderHTML(args: {
+        data: PageTitleData | null;
+        params: PageTitleParams;
+    }): string;
+    renderMarkdown(_args: {
+        data: PageTitleData | null;
+        params: PageTitleParams;
+    }): string;
+    validateParams(params: PageTitleParams): string | undefined;
+}
+export {};

package/dist/src/widget/page-title.widget.js

@@ -0,0 +1,33 @@
+/**
+ * Built-in Page Title Widget
+ *
+ * Sets document.title from .page.html and .page.md files without needing
+ * a .page.ts component. Renders no visible output.
+ *
+ * Usage in .page.html:
+ *   <widget-page-title title="About Us"></widget-page-title>
+ */
+import { WidgetComponent } from "../component/widget.component.js";
+export class PageTitleWidget extends WidgetComponent {
+    name = 'page-title';
+    getData(args) {
+        return Promise.resolve({ title: args.params.title });
+    }
+    renderHTML(args) {
+        const title = args.data?.title ?? args.params.title;
+        if (title && typeof document !== 'undefined') {
+            document.title = title;
+        }
+        return '';
+    }
+    renderMarkdown(_args) {
+        return '';
+    }
+    validateParams(params) {
+        if (!params.title || typeof params.title !== 'string') {
+            return 'page-title widget requires a "title" string param';
+        }
+        return undefined;
+    }
+}
+//# sourceMappingURL=page-title.widget.js.map

package/dist/src/widget/page-title.widget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-title.widget.js","sourceRoot":"","sources":["../../../src/widget/page-title.widget.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAUnE,MAAM,OAAO,eAAgB,SAAQ,eAA+C;IAChE,IAAI,GAAG,YAAY,CAAC;IAE7B,OAAO,CACd,IAAuD;QAEvD,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;IACvD,CAAC;IAEQ,UAAU,CACjB,IAA6D;QAE7D,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,EAAE,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC;QACpD,IAAI,KAAK,IAAI,OAAO,QAAQ,KAAK,WAAW,EAAE,CAAC;YAC7C,QAAQ,CAAC,KAAK,GAAG,KAAK,CAAC;QACzB,CAAC;QACD,OAAO,EAAE,CAAC;IACZ,CAAC;IAEQ,cAAc,CACrB,KAA8D;QAE9D,OAAO,EAAE,CAAC;IACZ,CAAC;IAEQ,cAAc,CAAC,MAAuB;QAC7C,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;YACtD,OAAO,mDAAmD,CAAC;QAC7D,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;CACF"}

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

@@ -0,0 +1,26 @@
+/**
+ * Widget Parser
+ *
+ * Parses fenced widget blocks from markdown content.
+ *
+ * Syntax:
+ * ```widget:widget-name
+ * {"key": "value"}
+ * ```
+ */
+import type { ParsedWidgetBlock } from '../type/widget.type.ts';
+/**
+ * Parse all widget blocks from markdown content.
+ *
+ * @param markdown - Markdown content to parse
+ * @returns Array of parsed widget blocks with positions
+ */
+export declare function parseWidgetBlocks(markdown: string): ParsedWidgetBlock[];
+/**
+ * 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 declare function replaceWidgetBlocks(markdown: string, replacements: Map<ParsedWidgetBlock, string>): string;

package/dist/src/widget/widget.parser.js

@@ -0,0 +1,76 @@
+/**
+ * Widget Parser
+ *
+ * Parses fenced widget blocks from markdown content.
+ *
+ * Syntax:
+ * ```widget:widget-name
+ * {"key": "value"}
+ * ```
+ */
+/**
+ * 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) {
+    const blocks = [];
+    for (const match of markdown.matchAll(WIDGET_PATTERN)) {
+        const fullMatch = match[0];
+        const { name: widgetName, params: paramsRaw } = match.groups;
+        const paramsJson = paramsRaw.trim();
+        const startIndex = match.index;
+        const block = {
+            fullMatch,
+            widgetName,
+            params: null,
+            startIndex,
+            endIndex: startIndex + fullMatch.length,
+        };
+        // Parse JSON params if present
+        if (paramsJson) {
+            try {
+                const parsed = JSON.parse(paramsJson);
+                if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+                    block.params = parsed;
+                }
+                else {
+                    block.parseError = 'Params must be a JSON object';
+                }
+            }
+            catch (e) {
+                block.parseError = `Invalid JSON: ${e instanceof Error ? e.message : String(e)}`;
+            }
+        }
+        else {
+            // Empty params is valid - use empty object
+            block.params = {};
+        }
+        blocks.push(block);
+    }
+    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, replacements) {
+    // 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);
+    let result = markdown;
+    for (const [block, replacement] of sortedBlocks) {
+        result = result.slice(0, block.startIndex) + replacement + result.slice(block.endIndex);
+    }
+    return result;
+}
+//# sourceMappingURL=widget.parser.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"widget.parser.js","sourceRoot":"","sources":["../../../src/widget/widget.parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH;;;GAGG;AACH,MAAM,cAAc,GAAG,yDAAyD,CAAC;AAEjF;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAgB;IAChD,MAAM,MAAM,GAAwB,EAAE,CAAC;IAEvC,KAAK,MAAM,KAAK,IAAI,QAAQ,CAAC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC;QACtD,MAAM,SAAS,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QAC3B,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,KAAK,CAAC,MAAO,CAAC;QAC9D,MAAM,UAAU,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC;QACpC,MAAM,UAAU,GAAG,KAAK,CAAC,KAAK,CAAC;QAE/B,MAAM,KAAK,GAAsB;YAC/B,SAAS;YACT,UAAU;YACV,MAAM,EAAE,IAAI;YACZ,UAAU;YACV,QAAQ,EAAE,UAAU,GAAG,SAAS,CAAC,MAAM;SACxC,CAAC;QAEF,+BAA+B;QAC/B,IAAI,UAAU,EAAE,CAAC;YACf,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;gBACtC,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;oBAC5E,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC;gBACxB,CAAC;qBAAM,CAAC;oBACN,KAAK,CAAC,UAAU,GAAG,8BAA8B,CAAC;gBACpD,CAAC;YACH,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,KAAK,CAAC,UAAU,GAAG,iBAAiB,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;YACnF,CAAC;QACH,CAAC;aAAM,CAAC;YACN,2CAA2C;YAC3C,KAAK,CAAC,MAAM,GAAG,EAAE,CAAC;QACpB,CAAC;QAED,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACrB,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CACjC,QAAgB,EAChB,YAA4C;IAE5C,+DAA+D;IAC/D,4CAA4C;IAC5C,MAAM,YAAY,GAAG,CAAC,GAAG,YAAY,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CACnD,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAC1C,CAAC;IAEF,IAAI,MAAM,GAAG,QAAQ,CAAC;IACtB,KAAK,MAAM,CAAC,KAAK,EAAE,WAAW,CAAC,IAAI,YAAY,EAAE,CAAC;QAChD,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,CAAC,GAAG,WAAW,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC1F,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

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

@@ -0,0 +1,23 @@
+/**
+ * Widget Registry
+ *
+ * Canonical registry where all widgets live. Used by all renderers:
+ * - SSR HTML: resolves widgets by name, calls getData() + renderHTML()
+ * - SSR Markdown: resolves widgets by name, calls getData() + renderMarkdown()
+ * - SPA: registers custom elements for each widget
+ *
+ * Pages are NOT in this registry — they live in the routes manifest.
+ */
+import type { WidgetComponent } from '../component/widget.component.ts';
+import type { WidgetsManifest } from '../type/widget.type.ts';
+export declare class WidgetRegistry {
+    private widgets;
+    /** Register a widget by its name. */
+    add(widget: WidgetComponent): void;
+    /** Look up a widget by name. */
+    get(name: string): WidgetComponent | undefined;
+    /** Iterate all registered widgets. */
+    [Symbol.iterator](): IterableIterator<WidgetComponent>;
+    /** Emit a WidgetsManifest from registered widgets. */
+    toManifest(): WidgetsManifest;
+}