@emkodev/emroute 1.7.3 → 1.8.0-beta.2

package/server/esbuild-manifest.plugin.ts

@@ -1,209 +0,0 @@
-/**
- * esbuild Virtual Manifest Plugin
- *
- * Intercepts `emroute:routes` and `emroute:widgets` import specifiers.
- * Reads JSON manifests from the runtime and generates TypeScript modules
- * with `moduleLoaders` (dynamic `import()` calls) in-memory — no .g.ts
- * files on disk.
- *
- * This is the single source of truth: JSON manifest → esbuild bundle.
- */
-
-import type { Runtime } from '../runtime/abstract.runtime.ts';
-import { ROUTES_MANIFEST_PATH, WIDGETS_MANIFEST_PATH } from '../runtime/abstract.runtime.ts';
-import { EMROUTE_VIRTUAL_NS } from './build.util.ts';
-
-/** Escape a string for use inside a single-quoted JS/TS string literal. */
-function esc(value: string): string {
-  return value.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
-}
-
-interface ManifestPluginOptions {
-  runtime: Runtime;
-  /**
-   * Directory prefix to strip from module paths so that import() calls
-   * are relative to the entry point (e.g. 'routes/' strips '/routes/').
-   */
-  stripPrefix?: string;
-  /** Absolute directory for resolving relative import() paths in generated code. */
-  resolveDir: string;
-}
-
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-type EsbuildPlugin = any;
-
-export function createManifestPlugin(options: ManifestPluginOptions): EsbuildPlugin {
-  const { runtime, stripPrefix = '', resolveDir } = options;
-
-  const strip = (p: string): string =>
-    stripPrefix && p.startsWith(stripPrefix) ? p.slice(stripPrefix.length) : p;
-
-  return {
-    name: 'emroute-manifest',
-
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    setup(build: any) {
-      // ── Resolve virtual specifiers ──────────────────────────────────
-      build.onResolve(
-        { filter: /^emroute:/ },
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        (args: any) => ({ path: args.path, namespace: EMROUTE_VIRTUAL_NS }),
-      );
-
-      // ── Load virtual modules ────────────────────────────────────────
-      build.onLoad(
-        { filter: /.*/, namespace: EMROUTE_VIRTUAL_NS },
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        async (args: any) => {
-          if (args.path === 'emroute:routes') {
-            return { contents: await generateRoutesModule(), loader: 'ts' as const, resolveDir };
-          }
-          if (args.path === 'emroute:widgets') {
-            return { contents: await generateWidgetsModule(), loader: 'ts' as const, resolveDir };
-          }
-          return undefined;
-        },
-      );
-    },
-  };
-
-  // ── Routes module generator ───────────────────────────────────────
-
-  async function generateRoutesModule(): Promise<string> {
-    const response = await runtime.query(ROUTES_MANIFEST_PATH);
-    if (response.status === 404) {
-      return `import type { RouteNode } from '@emkodev/emroute';
-export const routeTree: RouteNode = {};
-export const moduleLoaders: Record<string, () => Promise<unknown>> = {};
-`;
-    }
-    const raw = await response.json();
-
-    // Walk the RouteNode tree to collect all .ts module paths for import() loaders
-    const tsModulePaths = new Set<string>();
-    collectModulePaths(raw, tsModulePaths);
-
-    // Serialize the tree with stripped file paths
-    const strippedTree = stripTreePaths(raw);
-
-    const moduleLoadersCode = [...tsModulePaths]
-      .map((p) => {
-        const key = strip(p);
-        const rel = key.replace(/^\.?\//, '');
-        return `  '${esc(key)}': () => import('./${esc(rel)}'),`;
-      })
-      .join('\n');
-
-    return `import type { RouteNode } from '@emkodev/emroute';
-
-export const routeTree: RouteNode = ${JSON.stringify(strippedTree, null, 2)};
-
-export const moduleLoaders: Record<string, () => Promise<unknown>> = {
-${moduleLoadersCode}
-};
-`;
-  }
-
-  /**
-   * Recursively collect .ts module paths from a RouteNode tree.
-   */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  function collectModulePaths(node: any, paths: Set<string>): void {
-    const modulePath = node.files?.ts ?? node.files?.js;
-    if (modulePath) paths.add(modulePath);
-    if (node.errorBoundary) paths.add(node.errorBoundary);
-    if (node.redirect) paths.add(node.redirect);
-    if (node.children) {
-      for (const child of Object.values(node.children)) {
-        collectModulePaths(child, paths);
-      }
-    }
-    if (node.dynamic) collectModulePaths(node.dynamic.child, paths);
-    if (node.wildcard) collectModulePaths(node.wildcard.child, paths);
-  }
-
-  /**
-   * Deep-clone a RouteNode tree with stripped file paths.
-   */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  function stripTreePaths(node: any): any {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const out: any = {};
-
-    if (node.files) {
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      out.files = {} as any;
-      for (const [ext, path] of Object.entries(node.files)) {
-        if (path) out.files[ext] = strip(path as string);
-      }
-    }
-
-    if (node.errorBoundary) out.errorBoundary = strip(node.errorBoundary);
-    if (node.redirect) out.redirect = strip(node.redirect);
-
-    if (node.children) {
-      out.children = {};
-      for (const [seg, child] of Object.entries(node.children)) {
-        out.children[seg] = stripTreePaths(child);
-      }
-    }
-
-    if (node.dynamic) {
-      out.dynamic = { param: node.dynamic.param, child: stripTreePaths(node.dynamic.child) };
-    }
-
-    if (node.wildcard) {
-      out.wildcard = { param: node.wildcard.param, child: stripTreePaths(node.wildcard.child) };
-    }
-
-    return out;
-  }
-
-  // ── Widgets module generator ──────────────────────────────────────
-
-  async function generateWidgetsModule(): Promise<string> {
-    const response = await runtime.query(WIDGETS_MANIFEST_PATH);
-    if (response.status === 404) {
-      return `export const widgetsManifest = { widgets: [], moduleLoaders: {} };`;
-    }
-    const entries = await response.json();
-
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const widgetEntries = (entries as any[]).map((e) => {
-      const filesStr = e.files
-        ? `\n      files: { ${
-          Object.entries(e.files)
-            .filter(([_, v]) => v)
-            .map(([k, v]) => `${k}: '${esc(strip(v as string))}'`)
-            .join(', ')
-        } },`
-        : '';
-
-      return `    {
-      name: '${esc(e.name)}',
-      modulePath: '${esc(strip(e.modulePath))}',
-      tagName: '${esc(e.tagName)}',${filesStr}
-    }`;
-    }).join(',\n');
-
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const loaderEntries = (entries as any[]).map((e) => {
-      const key = strip(e.modulePath);
-      const rel = key.replace(/^\.?\//, '');
-      return `    '${esc(key)}': () => import('./${esc(rel)}'),`;
-    }).join('\n');
-
-    return `import type { WidgetsManifest } from '@emkodev/emroute';
-
-export const widgetsManifest: WidgetsManifest = {
-  widgets: [
-${widgetEntries}
-  ],
-
-  moduleLoaders: {
-${loaderEntries}
-  },
-};
-`;
-  }
-}

package/server/server-api.type.ts

@@ -1,101 +0,0 @@
-/**
- * Server API Types
- *
- * Interfaces for the emroute server.
- * Consumers use `createEmrouteServer()` to get a server that handles
- * SSR rendering, static file serving, and route matching.
- */
-
-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';
-import type { SsrHtmlRouter } from '../src/renderer/ssr/html.renderer.ts';
-import type { SsrMdRouter } from '../src/renderer/ssr/md.renderer.ts';
-
-// ── SSR Render Result ──────────────────────────────────────────────────
-
-/** Result of rendering a URL through an SSR renderer. */
-export interface SsrRenderResult {
-  /** Rendered content (HTML or Markdown) */
-  content: string;
-  /** HTTP status code */
-  status: number;
-  /** Page title (from the leaf route's getTitle) */
-  title?: string;
-  /** Redirect target URL (for 301/302 responses) */
-  redirect?: string;
-}
-
-// ── Server ─────────────────────────────────────────────────────────────
-
-/**
- * Config for `createEmrouteServer()`.
- *
- * The server reads manifests from the Runtime and handles SSR rendering,
- * static file serving, and route matching.
- */
-export interface EmrouteServerConfig {
-  /** Pre-built route tree (alternative to reading from runtime) */
-  routeTree?: RouteNode;
-
-  /** Pre-built widget registry (alternative to reading from runtime) */
-  widgets?: WidgetRegistry;
-
-  /** SPA mode — controls which routers are constructed and what gets served */
-  spa?: SpaMode;
-
-  /** Base paths for SSR endpoints (default: { html: '/html', md: '/md' }) */
-  basePath?: BasePath;
-
-  /** Page title (fallback when no route provides one) */
-  title?: string;
-
-  /** Markdown renderer for server-side <mark-down> expansion */
-  markdownRenderer?: MarkdownRenderer;
-
-  /** Enrich every ComponentContext with app-level services. */
-  extendContext?: ContextProvider;
-
-  /**
-   * Pre-bundled module loaders (route + widget modules).
-   * When provided, skips `runtime.loadModule()` — used in the browser
-   * where modules are already bundled into app.js.
-   */
-  moduleLoaders?: Record<string, () => Promise<unknown>>;
-}
-
-/**
- * An emroute server instance.
- *
- * Handles SSR rendering, static file serving, and route matching.
- * Use `handleRequest(req)` to compose with your own request handling.
- */
-export interface EmrouteServer {
-  /**
-   * Handle an HTTP request for SSR routes and bare paths.
-   * Returns `null` for unmatched file requests — consumer handles 404.
-   */
-  handleRequest(req: Request): Promise<Response | null>;
-
-  /** The SSR HTML router (null in 'only' mode — no server rendering). */
-  readonly htmlRouter: SsrHtmlRouter | null;
-
-  /** The SSR Markdown router (null in 'only' mode). */
-  readonly mdRouter: SsrMdRouter | null;
-
-  /** The resolved route tree. */
-  readonly routeTree: RouteNode;
-
-  /** 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

@@ -1,231 +0,0 @@
-/**
- * Unified Component Architecture
- *
- * 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
- *
- * Precedence (like .ts/.html/.md):
- * - renderHTML() if defined → full HTML control
- * - renderMarkdown() → converted to HTML via markdown renderer
- */
-
-import type { RouteInfo } from '../type/route.type.ts';
-import { escapeHtml } from '../util/html.util.ts';
-
-/**
- * Context passed to components during rendering.
- * Extends RouteInfo (pathname, pattern, params)
- * with pre-loaded file content and an abort signal.
- *
- * Consumers can extend this interface via module augmentation
- * to add app-level services (RPC clients, auth, feature flags, etc.).
- */
-/** Shape of companion file contents (html, md, css). Used by generated `.page.files.g.ts` modules. */
-export type FileContents = { html?: string; md?: string; css?: string };
-
-export interface ComponentContext extends RouteInfo {
-  /** @deprecated Use context.url.pathname */
-  readonly pathname: string;
-  /** @deprecated Use context.url.searchParams */
-  readonly searchParams: URLSearchParams;
-  readonly files?: Readonly<FileContents>;
-  readonly signal?: AbortSignal;
-  /** True when this component is the leaf (matched) route, false when rendered as a layout parent. */
-  readonly isLeaf?: boolean;
-}
-
-/**
- * Callback that enriches the base ComponentContext with app-level services.
- * Registered once at router creation; called for every context construction.
- *
- * **1. Register** — always spread `base` to preserve routing/file/signal data:
- * ```ts
- * createSpaHtmlRouter(manifest, {
- *   extendContext: (base) => ({ ...base, rpc: myRpcClient }),
- * });
- * ```
- *
- * **2. Access** — expose custom properties to components via module augmentation:
- * ```ts
- * declare module '@emkodev/emroute' {
- *   interface ComponentContext { rpc: RpcClient; }
- * }
- * ```
- * or per-component via the third generic:
- * ```ts
- * class MyPage extends PageComponent<Params, Data, AppContext> {}
- * ```
- */
-export type ContextProvider = (base: ComponentContext) => ComponentContext;
-
-/**
- * Render context determines how components are rendered.
- */
-export type RenderContext = 'markdown' | 'html' | 'spa';
-
-/**
- * Abstract base class for all components.
- *
- * Subclasses must implement:
- * - name: unique identifier for custom element tag
- * - getData(): fetch/compute data
- * - renderMarkdown(): render as markdown
- *
- * Optional override:
- * - renderHTML(): custom HTML rendering (defaults to markdown→HTML conversion)
- * - validateParams(): params validation
- *
- * @typeParam TContext — custom context shape; defaults to ComponentContext.
- *   Use with `extendContext` on the router to inject app-level services.
- *   See {@link ContextProvider} for details.
- */
-export abstract class Component<
-  TParams = unknown,
-  TData = unknown,
-  TContext extends ComponentContext = ComponentContext,
-> {
-  /** Type carrier for getData args — use as `this['DataArgs']` in overrides. */
-  declare readonly DataArgs: {
-    params: TParams;
-    signal?: AbortSignal;
-    context: TContext;
-  };
-
-  /** Type carrier for render args — use as `this['RenderArgs']` in overrides. */
-  declare readonly RenderArgs: {
-    data: TData | null;
-    params: TParams;
-    context: TContext;
-  };
-
-  /** Unique name in kebab-case. Used for custom element: `<widget-{name}>` */
-  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.
-   *
-   * Default is false — hydrate() receives `data: null`. Most widgets
-   * don't need this because the rendered Shadow DOM already contains
-   * the visual representation of the data.
-   *
-   * If you find yourself parsing the shadow DOM in hydrate() trying to
-   * reconstruct the original data object, set this to true instead.
-   * The server-fetched data will be available as `args.data` in hydrate().
-   */
-  readonly exposeSsrData?: boolean;
-
-  /**
-   * Fetch or compute data based on params.
-   * Called server-side for SSR, client-side for SPA.
-   *
-   * @example
-   * ```ts
-   * override async getData({ params, signal }: this['DataArgs']) {
-   *   const res = await fetch(`/api/${params.id}`, { signal });
-   *   return res.json();
-   * }
-   * ```
-   */
-  abstract getData(args: this['DataArgs']): Promise<TData | null>;
-
-  /**
-   * Render as markdown.
-   * This is the canonical content representation.
-   *
-   * @example
-   * ```ts
-   * override renderMarkdown({ data }: this['RenderArgs']) {
-   *   return `# ${data?.title}`;
-   * }
-   * ```
-   */
-  abstract renderMarkdown(args: this['RenderArgs']): string;
-
-  /**
-   * Render as HTML for browser context.
-   *
-   * Default implementation converts renderMarkdown() output to HTML.
-   * Override for custom HTML rendering with rich styling/interactivity.
-   */
-  renderHTML(args: this['RenderArgs']): string {
-    if (args.data === null) {
-      return `<div data-component="${this.name}">Loading...</div>`;
-    }
-    // Default: wrap markdown in a container
-    // The actual markdown→HTML conversion happens at render time
-    const markdown = this.renderMarkdown({
-      data: args.data,
-      params: args.params,
-      context: args.context,
-    });
-    return `<div data-component="${this.name}" data-markdown>${escapeHtml(markdown)}</div>`;
-  }
-
-  /**
-   * Hydration hook called after SSR content is adopted or after SPA rendering.
-   * Use to attach event listeners to existing DOM without re-rendering.
-   *
-   * @example
-   * ```ts
-   * override hydrate({ data, params, context }: this['RenderArgs']) {
-   *   const button = this.element?.querySelector('button');
-   *   button?.addEventListener('click', () => this.deleteItem(data.id));
-   * }
-   * ```
-   */
-  hydrate?(args: this['RenderArgs']): void;
-
-  /**
-   * Cleanup hook called when the component is removed from the DOM.
-   * Use for clearing timers, removing event listeners, unmounting
-   * third-party renderers, closing connections, etc.
-   *
-   * Intentionally synchronous (called from disconnectedCallback). You can
-   * fire async cleanup here, but it will not be awaited.
-   */
-  destroy?(): void;
-
-  /**
-   * Validate params.
-   * @returns Error message if invalid, undefined if valid.
-   */
-  validateParams?(params: TParams): string | undefined;
-
-  /**
-   * Render error state.
-   */
-  renderError(args: { error: unknown; params: TParams }): string {
-    const msg = args.error instanceof Error ? args.error.message : String(args.error);
-    return `<div data-component="${this.name}">Error: ${escapeHtml(msg)}</div>`;
-  }
-
-  /**
-   * Render error as markdown.
-   */
-  renderMarkdownError(error: unknown): string {
-    const msg = error instanceof Error ? error.message : String(error);
-    return `> **Error** (\`${this.name}\`): ${msg}`;
-  }
-}
-
-/**
- * Component manifest entry for code generation.
- */
-export interface ComponentManifestEntry {
-  name: string;
-  modulePath: string;
-  tagName: string;
-  type: 'page' | 'widget';
-  pattern?: string;
-}

package/src/component/widget.component.ts

@@ -1,85 +0,0 @@
-/**
- * WidgetComponent — 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.
- *
- * Pages live in the routes manifest. Widgets live in the registry.
- *
- * Default rendering fallback chains (parallel to PageComponent):
- * - renderHTML:     html file → md file in <mark-down> → base Component default
- * - renderMarkdown: md file → ''
- */
-
-import { Component, type ComponentContext } from './abstract.component.ts';
-import { escapeHtml, scopeWidgetCss } from '../util/html.util.ts';
-
-export abstract class WidgetComponent<
-  TParams = unknown,
-  TData = unknown,
-  TContext extends ComponentContext = ComponentContext,
-> extends Component<TParams, TData, TContext> {
-  /**
-   * Render widget as HTML.
-   *
-   * Fallback chain:
-   * 1. html file content from context
-   * 2. md file content wrapped in `<mark-down>`
-   * 3. base Component default (markdown→HTML conversion)
-   *
-   * @example
-   * ```ts
-   * override renderHTML({ data, params }: this['RenderArgs']) {
-   *   return `<span>${params.coin}: $${data?.price}</span>`;
-   * }
-   * ```
-   */
-  override renderHTML(
-    args: this['RenderArgs'],
-  ): string {
-    const files = args.context.files;
-    // @scope needed for SSR Light DOM output; redundant but harmless in SPA Shadow DOM
-    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);
-  }
-
-  /**
-   * Render widget as Markdown.
-   *
-   * Fallback chain:
-   * 1. md file content from context
-   * 2. empty string
-   *
-   * @example
-   * ```ts
-   * override renderMarkdown({ data, params }: this['RenderArgs']) {
-   *   return `**${params.coin}**: $${data?.price}`;
-   * }
-   * ```
-   */
-  override renderMarkdown(
-    args: this['RenderArgs'],
-  ): string {
-    const files = args.context.files;
-
-    if (files?.md) {
-      return files.md;
-    }
-
-    return '';
-  }
-}