@emkodev/emroute 1.7.2 → 1.7.3

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

@@ -1 +1 @@
-{"version":3,"file":"widget.registry.js","sourceRoot":"","sources":["../../../src/widget/widget.registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,MAAM,OAAO,cAAc;IACjB,OAAO,GAAG,IAAI,GAAG,EAA2B,CAAC;IAErD,qCAAqC;IACrC,GAAG,CAAC,MAAuB;QACzB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACxC,CAAC;IAED,gCAAgC;IAChC,GAAG,CAAC,IAAY;QACd,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAChC,CAAC;IAED,sCAAsC;IACtC,CAAC,MAAM,CAAC,QAAQ,CAAC;QACf,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;IAC/B,CAAC;IAED,sDAAsD;IACtD,UAAU;QACR,MAAM,OAAO,GAA0B,EAAE,CAAC;QAC1C,MAAM,aAAa,GAA2C,EAAE,CAAC;QAEjE,KAAK,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAC1C,MAAM,KAAK,GAAwB;gBACjC,IAAI;gBACJ,UAAU,EAAE,IAAI;gBAChB,OAAO,EAAE,UAAU,IAAI,EAAE;gBACzB,KAAK,EAAE,MAAM,CAAC,KAAK;aACpB,CAAC;YACF,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACpB,aAAa,CAAC,IAAI,CAAC,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC;QAC/E,CAAC;QAED,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,CAAC;IACpC,CAAC;CACF"}
+{"version":3,"file":"widget.registry.js","sourceRoot":"","sources":["../../../src/widget/widget.registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,MAAM,OAAO,cAAc;IACjB,OAAO,GAAG,IAAI,GAAG,EAA2B,CAAC;IAErD,qCAAqC;IACrC,GAAG,CAAC,MAAuB;QACzB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACxC,CAAC;IAED,gCAAgC;IAChC,GAAG,CAAC,IAAY;QACd,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAChC,CAAC;IAED,sCAAsC;IACtC,CAAC,MAAM,CAAC,QAAQ,CAAC;QACf,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;IAC/B,CAAC;IAED,sDAAsD;IACtD,UAAU;QACR,MAAM,OAAO,GAA0B,EAAE,CAAC;QAC1C,MAAM,aAAa,GAA2C,EAAE,CAAC;QAEjE,KAAK,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YAC1C,MAAM,KAAK,GAAwB;gBACjC,IAAI;gBACJ,UAAU,EAAE,IAAI;gBAChB,OAAO,EAAE,UAAU,IAAI,EAAE;gBACzB,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACjD,CAAC;YACF,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACpB,aAAa,CAAC,IAAI,CAAC,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC;QAC/E,CAAC;QAED,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,CAAC;IACpC,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emkodev/emroute",
-  "version": "1.7.2",
+  "version": "1.7.3",
   "description": "File-based (but storage-agnostic) router with triple rendering (SPA, SSR HTML, SSR Markdown). Zero dependencies.",
   "license": "BSD-3-Clause",
   "author": "emko.dev",

package/runtime/abstract.runtime.ts

@@ -1,6 +1,7 @@
 import type { RouteNode, RouteFiles } from '../src/type/route-tree.type.ts';
 import { resolveTargetNode } from '../src/route/route-tree.util.ts';
 import type { WidgetManifestEntry } from '../src/type/widget.type.ts';
+import type { ElementManifestEntry } from '../src/type/element.type.ts';
 
 export const CONTENT_TYPES: Map<string, string> = new Map<string, string>([
   ['.html', 'text/html; charset=utf-8'],
@@ -31,12 +32,15 @@ export type FetchReturn = ReturnType<typeof fetch>;
 
 export const DEFAULT_ROUTES_DIR = '/routes';
 export const DEFAULT_WIDGETS_DIR = '/widgets';
+export const DEFAULT_ELEMENTS_DIR = '/elements';
 export const ROUTES_MANIFEST_PATH = '/routes.manifest.json';
 export const WIDGETS_MANIFEST_PATH = '/widgets.manifest.json';
+export const ELEMENTS_MANIFEST_PATH = '/elements.manifest.json';
 
 export interface RuntimeConfig {
   routesDir?: string;
   widgetsDir?: string;
+  elementsDir?: string;
 }
 
 /**
@@ -168,11 +172,13 @@ export abstract class Runtime {
 
   private routesManifestCache: Response | null = null;
   private widgetsManifestCache: Response | null = null;
+  private elementsManifestCache: Response | null = null;
 
   /** Clear cached manifests so the next query triggers a fresh scan. */
   invalidateManifests(): void {
     this.routesManifestCache = null;
     this.widgetsManifestCache = null;
+    this.elementsManifestCache = null;
   }
 
   /**
@@ -215,6 +221,25 @@ export abstract class Runtime {
     return this.widgetsManifestCache.clone();
   }
 
+  /**
+   * Resolve the elements manifest. Called when the concrete runtime returns
+   * 404 for ELEMENTS_MANIFEST_PATH. Scans `config.elementsDir` (or default).
+   */
+  async resolveElementsManifest(): Promise<Response> {
+    if (this.elementsManifestCache) return this.elementsManifestCache.clone();
+
+    const elementsDir = this.config.elementsDir ?? DEFAULT_ELEMENTS_DIR;
+
+    const dirResponse = await this.query(elementsDir + '/');
+    if (dirResponse.status === 404) {
+      return new Response('Not Found', { status: 404 });
+    }
+
+    const entries = await this.scanElements(elementsDir, elementsDir.replace(/^\//, ''));
+    this.elementsManifestCache = Response.json(entries);
+    return this.elementsManifestCache.clone();
+  }
+
   // ── Scanning ──────────────────────────────────────────────────────────
 
   protected async *walkDirectory(dir: string): AsyncGenerator<string> {
@@ -344,4 +369,46 @@ export abstract class Runtime {
     entries.sort((a, b) => a.name.localeCompare(b.name));
     return entries;
   }
+
+  protected async scanElements(
+    elementsDir: string,
+    pathPrefix?: string,
+  ): Promise<ElementManifestEntry[]> {
+    const entries: ElementManifestEntry[] = [];
+
+    const trailingDir = elementsDir.endsWith('/') ? elementsDir : elementsDir + '/';
+    const response = await this.query(trailingDir);
+    const listing: string[] = await response.json();
+
+    for (const item of listing) {
+      if (!item.endsWith('/')) continue;
+
+      const name = item.slice(0, -1);
+
+      // Custom element names must contain a hyphen (web spec requirement)
+      if (!name.includes('-')) {
+        console.warn(`[emroute] Skipping element "${name}": custom element names must contain a hyphen (e.g. "my-element")`);
+        continue;
+      }
+
+      // Try .element.ts first, then .element.js
+      let moduleFile = `${name}.element.ts`;
+      let modulePath = `${trailingDir}${name}/${moduleFile}`;
+      if ((await this.query(modulePath)).status === 404) {
+        moduleFile = `${name}.element.js`;
+        modulePath = `${trailingDir}${name}/${moduleFile}`;
+        if ((await this.query(modulePath)).status === 404) continue;
+      }
+
+      const prefix = pathPrefix ? `${pathPrefix}/` : '';
+      entries.push({
+        name,
+        modulePath: `${prefix}${name}/${moduleFile}`,
+        tagName: name,
+      });
+    }
+
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    return entries;
+  }
 }

package/runtime/bun/fs/bun-fs.runtime.ts

@@ -8,6 +8,7 @@ import {
   Runtime,
   type RuntimeConfig,
   WIDGETS_MANIFEST_PATH,
+  ELEMENTS_MANIFEST_PATH,
 } from '../../abstract.runtime.ts';
 
 export class BunFsRuntime extends Runtime {
@@ -99,6 +100,7 @@ export class BunFsRuntime extends Runtime {
         const pathname = path.slice(this.root.length);
         if (pathname === ROUTES_MANIFEST_PATH) return this.resolveRoutesManifest();
         if (pathname === WIDGETS_MANIFEST_PATH) return this.resolveWidgetsManifest();
+        if (pathname === ELEMENTS_MANIFEST_PATH) return this.resolveElementsManifest();
         return new Response('Not Found', { status: 404 });
       }
       return new Response(`Internal Error: ${error}`, { status: 500 });

package/runtime/bun/sqlite/bun-sqlite.runtime.ts

@@ -7,6 +7,7 @@ import {
   Runtime,
   type RuntimeConfig,
   WIDGETS_MANIFEST_PATH,
+  ELEMENTS_MANIFEST_PATH,
 } from '../../abstract.runtime.ts';
 
 export class BunSqliteRuntime extends Runtime {
@@ -108,6 +109,7 @@ export class BunSqliteRuntime extends Runtime {
     if (!row) {
       if (path === ROUTES_MANIFEST_PATH) return this.resolveRoutesManifest();
       if (path === WIDGETS_MANIFEST_PATH) return this.resolveWidgetsManifest();
+      if (path === ELEMENTS_MANIFEST_PATH) return this.resolveElementsManifest();
       return new Response('Not Found', { status: 404 });
     }
 

package/runtime/universal/fs/universal-fs.runtime.ts

@@ -8,6 +8,7 @@ import {
   Runtime,
   type RuntimeConfig,
   WIDGETS_MANIFEST_PATH,
+  ELEMENTS_MANIFEST_PATH,
 } from '../../abstract.runtime.ts';
 
 /**
@@ -107,6 +108,7 @@ export class UniversalFsRuntime extends Runtime {
         const pathname = path.slice(this.root.length);
         if (pathname === ROUTES_MANIFEST_PATH) return this.resolveRoutesManifest();
         if (pathname === WIDGETS_MANIFEST_PATH) return this.resolveWidgetsManifest();
+        if (pathname === ELEMENTS_MANIFEST_PATH) return this.resolveElementsManifest();
         return new Response('Not Found', { status: 404 });
       }
       return new Response(`Internal Error: ${error}`, { status: 500 });

package/server/build.util.ts

@@ -20,9 +20,11 @@ import type { Runtime } from '../runtime/abstract.runtime.ts';
 import {
   ROUTES_MANIFEST_PATH,
   WIDGETS_MANIFEST_PATH,
+  ELEMENTS_MANIFEST_PATH,
 } from '../runtime/abstract.runtime.ts';
 import type { RouteNode } from '../src/type/route-tree.type.ts';
 import type { WidgetManifestEntry } from '../src/type/widget.type.ts';
+import type { ElementManifestEntry } from '../src/type/element.type.ts';
 import { generateMainTs } from './codegen.util.ts';
 import type { SpaMode } from '../src/type/widget.type.ts';
 
@@ -146,10 +148,23 @@ async function writeShell(
 ): Promise<void> {
   if ((await runtime.query('/index.html')).status !== 404) return;
 
+  // Base emroute imports
   const imports: Record<string, string> = {};
   for (const pkg of EMROUTE_EXTERNALS) {
     imports[pkg] = paths.emroute;
   }
+
+  // Merge user-provided importmap.json (user entries win on conflict)
+  const mapResponse = await runtime.query('/importmap.json');
+  if (mapResponse.status !== 404) {
+    const userMap = await mapResponse.json() as { imports?: Record<string, string> };
+    if (userMap.imports) {
+      for (const [key, value] of Object.entries(userMap.imports)) {
+        imports[key] = value;
+      }
+    }
+  }
+
   const importMap = JSON.stringify({ imports }, null, 2);
 
   const html = `<!DOCTYPE html>
@@ -251,11 +266,10 @@ async function mergeModules(runtime: Runtime): Promise<void> {
   // Merge route modules
   async function walkRoutes(node: RouteNode): Promise<void> {
     if (node.files?.ts) {
-      const companions = {
-        html: node.files.html,
-        md: node.files.md,
-        css: node.files.css,
-      };
+      const companions: { html?: string; md?: string; css?: string } = {};
+      if (node.files.html) companions.html = node.files.html;
+      if (node.files.md) companions.md = node.files.md;
+      if (node.files.css) companions.css = node.files.css;
       node.files.js = await transpileAndMerge(runtime, node.files.ts, companions);
       delete node.files.ts;
       delete node.files.html;
@@ -290,6 +304,19 @@ async function mergeModules(runtime: Runtime): Promise<void> {
     }
   }
 
+  // Read element manifest
+  const elementsResponse = await runtime.query(ELEMENTS_MANIFEST_PATH);
+  const elementEntries: ElementManifestEntry[] = elementsResponse.status !== 404
+    ? await elementsResponse.json()
+    : [];
+
+  // Merge element modules
+  for (const entry of elementEntries) {
+    if (entry.modulePath.endsWith('.ts')) {
+      entry.modulePath = await transpileAndMerge(runtime, entry.modulePath);
+    }
+  }
+
   // Write updated manifests back
   await runtime.command(ROUTES_MANIFEST_PATH, {
     body: JSON.stringify(routeTree),
@@ -297,6 +324,11 @@ async function mergeModules(runtime: Runtime): Promise<void> {
   await runtime.command(WIDGETS_MANIFEST_PATH, {
     body: JSON.stringify(widgetEntries),
   });
+  if (elementEntries.length > 0) {
+    await runtime.command(ELEMENTS_MANIFEST_PATH, {
+      body: JSON.stringify(elementEntries),
+    });
+  }
 }
 
 // ── esbuild loader ────────────────────────────────────────────────────

package/server/emroute.server.ts

@@ -34,6 +34,7 @@ import { SsrHtmlRouter } from '../src/renderer/ssr/html.renderer.ts';
 import { SsrMdRouter } from '../src/renderer/ssr/md.renderer.ts';
 import type { RouteNode } from '../src/type/route-tree.type.ts';
 import type { WidgetManifestEntry } from '../src/type/widget.type.ts';
+import type { ElementManifestEntry } from '../src/type/element.type.ts';
 import { WidgetRegistry } from '../src/widget/widget.registry.ts';
 import type { WidgetComponent } from '../src/component/widget.component.ts';
 import { escapeHtml } from '../src/util/html.util.ts';
@@ -42,6 +43,7 @@ import {
   ROUTES_MANIFEST_PATH,
   Runtime,
   WIDGETS_MANIFEST_PATH,
+  ELEMENTS_MANIFEST_PATH,
 } from '../runtime/abstract.runtime.ts';
 import type { EmrouteServer, EmrouteServerConfig } from './server-api.type.ts';
 
@@ -254,6 +256,14 @@ export async function createEmrouteServer(
     }
   }
 
+  // ── Elements (read from runtime) ──────────────────────────────────
+
+  let discoveredElementEntries: ElementManifestEntry[] = [];
+  const elementsResponse = await runtime.query(ELEMENTS_MANIFEST_PATH);
+  if (elementsResponse.status !== 404) {
+    discoveredElementEntries = await elementsResponse.json();
+  }
+
   // ── SSR routers ──────────────────────────────────────────────────────
 
   let ssrHtmlRouter: SsrHtmlRouter | null = null;
@@ -269,17 +279,17 @@ export async function createEmrouteServer(
     ssrHtmlRouter = new SsrHtmlRouter(resolver, {
       fileReader: (path) => runtime.query(path, { as: 'text' }),
       moduleLoaders,
-      markdownRenderer: config.markdownRenderer,
-      extendContext: config.extendContext,
-      widgets,
+      ...(config.markdownRenderer ? { markdownRenderer: config.markdownRenderer } : {}),
+      ...(config.extendContext ? { extendContext: config.extendContext } : {}),
+      ...(widgets ? { widgets } : {}),
       widgetFiles,
     });
 
     ssrMdRouter = new SsrMdRouter(resolver, {
       fileReader: (path) => runtime.query(path, { as: 'text' }),
       moduleLoaders,
-      extendContext: config.extendContext,
-      widgets,
+      ...(config.extendContext ? { extendContext: config.extendContext } : {}),
+      ...(widgets ? { widgets } : {}),
       widgetFiles,
     });
   }
@@ -289,7 +299,8 @@ export async function createEmrouteServer(
   // ── HTML shell ───────────────────────────────────────────────────────
 
   const title = config.title ?? 'emroute';
-  let shell = await resolveShell(runtime, title, htmlBase);
+  const shellBase = (spa === 'root' || spa === 'only') ? appBase : htmlBase;
+  let shell = await resolveShell(runtime, title, shellBase);
 
   // Auto-discover main.css and inject <link> into <head>
   if ((await runtime.query('/main.css')).status !== 404) {
@@ -413,6 +424,9 @@ export async function createEmrouteServer(
     get widgetEntries() {
       return discoveredWidgetEntries;
     },
+    get elementEntries() {
+      return discoveredElementEntries;
+    },
     get shell() {
       return shell;
     },

package/server/server-api.type.ts

@@ -9,6 +9,7 @@
 import type { RouteNode } from '../src/type/route-tree.type.ts';
 import type { MarkdownRenderer } from '../src/type/markdown.type.ts';
 import type { SpaMode, WidgetManifestEntry } from '../src/type/widget.type.ts';
+import type { ElementManifestEntry } from '../src/type/element.type.ts';
 import type { ContextProvider } from '../src/component/abstract.component.ts';
 import type { BasePath } from '../src/route/route.core.ts';
 import type { WidgetRegistry } from '../src/widget/widget.registry.ts';
@@ -92,6 +93,9 @@ export interface EmrouteServer {
   /** Discovered widget entries. */
   readonly widgetEntries: WidgetManifestEntry[];
 
+  /** Discovered element entries. */
+  readonly elementEntries: ElementManifestEntry[];
+
   /** The resolved HTML shell. */
   readonly shell: string;
 }

package/src/component/abstract.component.ts

@@ -105,7 +105,7 @@ export abstract class Component<
   abstract readonly name: string;
 
   /** Host element reference, set by ComponentElement in the browser. */
-  element?: HTMLElement;
+  element?: HTMLElement | undefined;
 
   /** Associated file paths for pre-loaded content (html, md, css). */
   readonly files?: { html?: string; md?: string; css?: string };

package/src/element/component.element.ts

@@ -18,6 +18,17 @@ import { HTMLElementBase, LAZY_ATTR, SSR_ATTR } from '../util/html.util.ts';
 
 type ComponentState = 'idle' | 'loading' | 'ready' | 'error';
 
+/** Strip keys with undefined values — returns the filtered object, or undefined if all values are undefined. */
+function filterUndefined<T extends Record<string, unknown>>(obj: T): { [K in keyof T as T[K] extends undefined ? never : K]: NonNullable<T[K]> } | undefined {
+  const result: Record<string, unknown> = {};
+  let hasValue = false;
+  for (const [k, v] of Object.entries(obj)) {
+    if (v !== undefined) { result[k] = v; hasValue = true; }
+  }
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return hasValue ? result as any : undefined;
+}
+
 type WidgetFiles = { html?: string; md?: string; css?: string };
 
 /**
@@ -42,7 +53,7 @@ export class ComponentElement<TParams, TData> extends HTMLElementBase {
   }
 
   private component: Component<TParams, TData>;
-  private effectiveFiles?: WidgetFiles;
+  private effectiveFiles?: WidgetFiles | undefined;
   private params: TParams | null = null;
   private data: TData | null = null;
   private context!: ComponentContext;
@@ -231,12 +242,13 @@ export class ComponentElement<TParams, TData> extends HTMLElementBase {
     if (signal.aborted) return;
 
     const currentUrl = globalThis.location ? new URL(location.href) : new URL('http://localhost/');
+    const filteredFiles = filterUndefined(files);
     const base: ComponentContext = {
       url: currentUrl,
       pathname: currentUrl.pathname,
       searchParams: currentUrl.searchParams,
       params: this.params ?? {},
-      files: (files.html || files.md || files.css) ? files : undefined,
+      ...(filteredFiles ? { files: filteredFiles } : {}),
     };
     this.context = ComponentElement.extendContext ? ComponentElement.extendContext(base) : base;
 
@@ -350,7 +362,7 @@ export class ComponentElement<TParams, TData> extends HTMLElementBase {
       filePaths.css ? ComponentElement.loadFile(filePaths.css) : undefined,
     ]);
 
-    return { html, md, css };
+    return filterUndefined({ html, md, css }) ?? {};
   }
 
   private async loadData(): Promise<void> {
@@ -364,7 +376,7 @@ export class ComponentElement<TParams, TData> extends HTMLElementBase {
     try {
       const promise = this.component.getData({
         params: this.params,
-        signal,
+        ...(signal ? { signal } : {}),
         context: this.context,
       });
       this.dataPromise = promise;

package/src/element/markdown.element.ts

@@ -80,7 +80,7 @@ export class MarkdownElement extends HTMLElementBase {
     const signal = this.abortController?.signal;
 
     try {
-      const response = await fetch(src, { signal });
+      const response = await fetch(src, signal ? { signal } : {});
 
       if (!response.ok) {
         throw new Error(`Failed to fetch ${src}: ${response.status}`);

package/src/index.ts

@@ -40,6 +40,7 @@ export type {
   WidgetsManifest,
 } from './type/widget.type.ts';
 
+export type { ElementManifestEntry } from './type/element.type.ts';
 export type { MarkdownRenderer } from './type/markdown.type.ts';
 export { type Logger, setLogger } from './type/logger.type.ts';
 

package/src/renderer/spa/thin-client.ts

@@ -11,10 +11,11 @@
 import type { EmrouteServer } from '../../../server/server-api.type.ts';
 import { createEmrouteServer } from '../../../server/emroute.server.ts';
 import { FetchRuntime } from '../../../runtime/fetch.runtime.ts';
-import { ROUTES_MANIFEST_PATH, WIDGETS_MANIFEST_PATH } from '../../../runtime/abstract.runtime.ts';
+import { ROUTES_MANIFEST_PATH, WIDGETS_MANIFEST_PATH, ELEMENTS_MANIFEST_PATH } from '../../../runtime/abstract.runtime.ts';
 import type { RouteNode } from '../../type/route-tree.type.ts';
 import type { NavigateOptions } from '../../type/route.type.ts';
 import type { WidgetManifestEntry } from '../../type/widget.type.ts';
+import type { ElementManifestEntry } from '../../type/element.type.ts';
 import { assertSafeRedirect, type BasePath, DEFAULT_BASE_PATH } from '../../route/route.core.ts';
 import { escapeHtml } from '../../util/html.util.ts';
 import { ComponentElement } from '../../element/component.element.ts';
@@ -207,8 +208,14 @@ export async function bootEmrouteApp(options?: BootOptions): Promise<EmrouteApp>
     ? await widgetsResponse.json()
     : [];
 
-  // Build lazy module loaders for all route + widget modules
-  const moduleLoaders = buildLazyLoaders(routeTree, widgetEntries, runtime);
+  // Fetch element manifest (optional — app may have no custom elements)
+  const elementsResponse = await runtime.handle(ELEMENTS_MANIFEST_PATH);
+  const elementEntries: ElementManifestEntry[] = elementsResponse.ok
+    ? await elementsResponse.json()
+    : [];
+
+  // Build lazy module loaders for all route + widget + element modules
+  const moduleLoaders = buildLazyLoaders(routeTree, widgetEntries, elementEntries, runtime);
 
   // Register widgets eagerly (tag defined immediately, module loads on connectedCallback)
   const widgets = new WidgetRegistry();
@@ -216,24 +223,41 @@ export async function bootEmrouteApp(options?: BootOptions): Promise<EmrouteApp>
     ComponentElement.registerLazy(entry.name, entry.files, moduleLoaders[entry.modulePath]);
   }
 
+  // Register custom elements — import all modules, define when loaded
+  for (const entry of elementEntries) {
+    const loader = moduleLoaders[entry.modulePath];
+    if (loader) {
+      loader().then((mod) => {
+        const cls = (mod as Record<string, unknown>).default;
+        if (typeof cls === 'function' && !customElements.get(entry.tagName)) {
+          customElements.define(entry.tagName, cls as CustomElementConstructor);
+        }
+      }).catch((e) => {
+        console.error(`[emroute] Failed to load element ${entry.tagName}:`, e);
+      });
+    }
+  }
+
   // Create the server (reuses the same createEmrouteServer as SSR)
+  const mdRenderer = MarkdownElement.getConfiguredRenderer();
   const server = await createEmrouteServer({
     routeTree,
     widgets,
     moduleLoaders,
-    markdownRenderer: MarkdownElement.getConfiguredRenderer() ?? undefined,
+    ...(mdRenderer ? { markdownRenderer: mdRenderer } : {}),
   }, runtime);
 
   return createEmrouteApp(server, options);
 }
 
 /**
- * Walk the route tree and widget entries to build a map of
+ * Walk the route tree, widget entries, and element entries to build a map of
  * `path → () => runtime.loadModule(path)` lazy loaders.
  */
 function buildLazyLoaders(
   tree: RouteNode,
   widgetEntries: WidgetManifestEntry[],
+  elementEntries: ElementManifestEntry[],
   runtime: FetchRuntime,
 ): Record<string, () => Promise<unknown>> {
   const paths = new Set<string>();
@@ -252,6 +276,7 @@ function buildLazyLoaders(
 
   walk(tree);
   for (const entry of widgetEntries) paths.add(entry.modulePath);
+  for (const entry of elementEntries) paths.add(entry.modulePath);
 
   const loaders: Record<string, () => Promise<unknown>> = {};
   for (const path of paths) {

package/src/renderer/ssr/html.renderer.ts

@@ -87,7 +87,7 @@ export class SsrHtmlRouter extends SsrRenderer {
       );
     }
 
-    return { content, title };
+    return { content, ...(title != null ? { title } : {}) };
   }
 
   protected override renderContent(

package/src/renderer/ssr/md.renderer.ts

@@ -6,6 +6,7 @@
  */
 
 import type { RouteConfig, RouteInfo } from '../../type/route.type.ts';
+import type { ComponentContext } from '../../component/abstract.component.ts';
 import type { RouteResolver } from '../../route/route.resolver.ts';
 import type { PageComponent } from '../../component/page.component.ts';
 import { DEFAULT_ROOT_ROUTE } from '../../route/route.core.ts';
@@ -68,7 +69,7 @@ export class SsrMdRouter extends SsrRenderer {
       content = await this.resolveWidgets(content, routeInfo);
     }
 
-    return { content, title };
+    return { content, ...(title != null ? { title } : {}) };
   }
 
   protected override renderContent(
@@ -118,13 +119,13 @@ export class SsrMdRouter extends SsrRenderer {
             files = await this.core.loadWidgetFiles(filePaths);
           }
 
-          const baseContext = {
+          const baseContext: ComponentContext = {
             ...routeInfo,
             pathname: routeInfo.url.pathname,
             searchParams: routeInfo.url.searchParams,
-            files,
+            ...(files ? { files } : {}),
           };
-          const context = this.core.contextProvider
+          const context: ComponentContext = this.core.contextProvider
             ? this.core.contextProvider(baseContext)
             : baseContext;
           const data = await widget.getData({ params: block.params, context });

package/src/renderer/ssr/ssr.renderer.ts

@@ -60,7 +60,7 @@ export abstract class SsrRenderer {
         try {
           const ri: RouteInfo = { url, params: {} };
           const result = await this.renderRouteContent(ri, statusPage, undefined, signal);
-          return { content: this.stripSlots(result.content), status: 404, title: result.title };
+          return { content: this.stripSlots(result.content), status: 404, ...(result.title != null ? { title: result.title } : {}) };
         } catch (e) {
           logger.error(
             `[${this.label}] Failed to render 404 status page for ${url.pathname}`,
@@ -89,7 +89,7 @@ export abstract class SsrRenderer {
 
     try {
       const { content, title } = await this.renderPage(routeInfo, matched, signal);
-      return { content, status: 200, title };
+      return { content, status: 200, ...(title != null ? { title } : {}) };
     } catch (error) {
       if (error instanceof Response) {
         const statusPage = this.core.getStatusPage(error.status);
@@ -100,7 +100,7 @@ export abstract class SsrRenderer {
             return {
               content: this.stripSlots(result.content),
               status: error.status,
-              title: result.title,
+              ...(result.title != null ? { title: result.title } : {}),
             };
           } catch (e) {
             logger.error(
@@ -196,7 +196,7 @@ export abstract class SsrRenderer {
 
     result = this.stripSlots(result);
 
-    return { content: result, title: pageTitle };
+    return { content: result, ...(pageTitle != null ? { title: pageTitle } : {}) };
   }
 
   protected abstract renderRouteContent(
@@ -221,11 +221,11 @@ export abstract class SsrRenderer {
       : defaultPageComponent;
 
     const context = await this.core.buildComponentContext(routeInfo, route, signal, isLeaf);
-    const data = await component.getData({ params: routeInfo.params, signal, context });
+    const data = await component.getData({ params: routeInfo.params, ...(signal ? { signal } : {}), context });
     const content = this.renderContent(component, { data, params: routeInfo.params, context });
     const title = component.getTitle({ data, params: routeInfo.params, context });
 
-    return { content, title };
+    return { content, ...(title != null ? { title } : {}) };
   }
 
   /** Render a component to the output format (HTML or Markdown). */