@emkodev/emroute 1.6.2 → 1.6.3

package/dist/server/scanner.util.js

@@ -0,0 +1,194 @@
+/**
+ * Standalone Scanning Utilities
+ *
+ * Runtime-agnostic route and widget scanning. Works with any Runtime
+ * that implements query() — used by tests with mock runtimes and by
+ * the CLI generate command.
+ *
+ * Note: BunFsRuntime has these as instance methods with lazy caching.
+ * These standalone functions are the same logic without caching.
+ */
+import { filePathToPattern, getPageFileType, getRouteType, sortRoutesBySpecificity, } from "../src/route/route.matcher.js";
+/** Walk directory recursively and collect files via Runtime. */
+async function* walkDirectory(runtime, dir) {
+    const trailingDir = dir.endsWith('/') ? dir : dir + '/';
+    const response = await runtime.query(trailingDir);
+    const entries = await response.json();
+    for (const entry of entries) {
+        const path = `${trailingDir}${entry}`;
+        if (entry.endsWith('/')) {
+            yield* walkDirectory(runtime, path);
+        }
+        else {
+            yield path;
+        }
+    }
+}
+/** Generate routes manifest by scanning a directory via Runtime. */
+export async function generateRoutesManifest(routesDir, runtime) {
+    const pageFiles = [];
+    const redirects = [];
+    const errorBoundaries = [];
+    const statusPages = new Map();
+    let errorHandler;
+    const allFiles = [];
+    for await (const file of walkDirectory(runtime, routesDir)) {
+        allFiles.push(file);
+    }
+    for (const filePath of allFiles) {
+        const relativePath = filePath.replace(`${routesDir}/`, '');
+        const filename = relativePath.split('/').pop() ?? '';
+        if (filename === 'index.error.ts' && relativePath === 'index.error.ts') {
+            errorHandler = {
+                pattern: '/',
+                type: 'error',
+                modulePath: filePath,
+            };
+            continue;
+        }
+        const cssFileType = getPageFileType(filename);
+        if (cssFileType === 'css') {
+            const pattern = filePathToPattern(relativePath);
+            pageFiles.push({ path: filePath, pattern, fileType: 'css' });
+            continue;
+        }
+        const routeType = getRouteType(filename);
+        if (!routeType)
+            continue;
+        const statusMatch = filename.match(/^(\d{3})\.page\.(ts|html|md)$/);
+        if (statusMatch) {
+            const statusCode = parseInt(statusMatch[1], 10);
+            const fileType = getPageFileType(filename);
+            if (fileType) {
+                const existing = statusPages.get(statusCode);
+                if (existing) {
+                    existing.files ??= {};
+                    existing.files[fileType] = filePath;
+                    existing.modulePath = existing.files.ts ?? existing.files.html ?? existing.files.md ?? '';
+                }
+                else {
+                    const files = { [fileType]: filePath };
+                    statusPages.set(statusCode, {
+                        pattern: `/${statusCode}`,
+                        type: 'page',
+                        modulePath: filePath,
+                        statusCode,
+                        files,
+                    });
+                }
+            }
+            continue;
+        }
+        const pattern = filePathToPattern(relativePath);
+        if (routeType === 'error') {
+            const boundaryPattern = pattern.replace(/\/[^/]+$/, '') || '/';
+            errorBoundaries.push({ pattern: boundaryPattern, modulePath: filePath });
+            continue;
+        }
+        if (routeType === 'redirect') {
+            redirects.push({ pattern, type: 'redirect', modulePath: filePath });
+            continue;
+        }
+        const fileType = getPageFileType(filename);
+        if (fileType) {
+            pageFiles.push({ path: filePath, pattern, fileType });
+        }
+    }
+    // Group files by pattern
+    const groups = new Map();
+    for (const { path, pattern, fileType } of pageFiles) {
+        let group = groups.get(pattern);
+        if (!group) {
+            group = { pattern, files: {} };
+            const segments = pattern.split('/').filter(Boolean);
+            if (segments.length > 1) {
+                group.parent = '/' + segments.slice(0, -1).join('/');
+            }
+            groups.set(pattern, group);
+        }
+        const existing = group.files[fileType];
+        if (existing?.includes('/index.page.') && !path.includes('/index.page.')) {
+            continue;
+        }
+        group.files[fileType] = path;
+    }
+    // Detect collisions
+    const warnings = [];
+    for (const [pattern, group] of groups) {
+        const filePaths = Object.values(group.files).filter(Boolean);
+        const hasIndex = filePaths.some((p) => p?.includes('/index.page.'));
+        const hasFlat = filePaths.some((p) => p && !p.includes('/index.page.'));
+        if (hasIndex && hasFlat) {
+            warnings.push(`Warning: Mixed file structure for ${pattern}:\n` +
+                filePaths.map((p) => `     ${p}`).join('\n') +
+                `\n     Both folder/index and flat files detected`);
+        }
+    }
+    // Convert groups to RouteConfig array
+    const routes = [];
+    for (const [_, group] of groups) {
+        const modulePath = group.files.ts ?? group.files.html ?? group.files.md ?? '';
+        if (!modulePath)
+            continue;
+        const route = {
+            pattern: group.pattern,
+            type: 'page',
+            modulePath,
+            files: group.files,
+        };
+        if (group.parent)
+            route.parent = group.parent;
+        routes.push(route);
+    }
+    routes.push(...redirects);
+    const sortedRoutes = sortRoutesBySpecificity(routes);
+    return {
+        routes: sortedRoutes,
+        errorBoundaries,
+        statusPages,
+        errorHandler,
+        warnings,
+    };
+}
+/**
+ * Discover widget modules and companion files by scanning a directory.
+ */
+export async function discoverWidgets(widgetsDir, runtime, pathPrefix) {
+    const COMPANION_EXTENSIONS = ['html', 'md', 'css'];
+    const WIDGET_FILE_SUFFIX = '.widget.ts';
+    const entries = [];
+    const trailingDir = widgetsDir.endsWith('/') ? widgetsDir : widgetsDir + '/';
+    const response = await runtime.query(trailingDir);
+    const listing = await response.json();
+    for (const item of listing) {
+        if (!item.endsWith('/'))
+            continue;
+        const name = item.slice(0, -1);
+        const moduleFile = `${name}${WIDGET_FILE_SUFFIX}`;
+        const modulePath = `${trailingDir}${name}/${moduleFile}`;
+        if ((await runtime.query(modulePath)).status === 404)
+            continue;
+        const prefix = pathPrefix ? `${pathPrefix}/` : '';
+        const entry = {
+            name,
+            modulePath: `${prefix}${name}/${moduleFile}`,
+            tagName: `widget-${name}`,
+        };
+        const files = {};
+        let hasFiles = false;
+        for (const ext of COMPANION_EXTENSIONS) {
+            const companionFile = `${name}.widget.${ext}`;
+            const companionPath = `${trailingDir}${name}/${companionFile}`;
+            if ((await runtime.query(companionPath)).status !== 404) {
+                files[ext] = `${prefix}${name}/${companionFile}`;
+                hasFiles = true;
+            }
+        }
+        if (hasFiles)
+            entry.files = files;
+        entries.push(entry);
+    }
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    return entries;
+}
+//# sourceMappingURL=scanner.util.js.map

package/dist/server/scanner.util.js.map

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

package/dist/server/server-api.type.d.ts

@@ -0,0 +1,71 @@
+/**
+ * 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 { RoutesManifest } from '../src/type/route.type.ts';
+import type { MarkdownRenderer } from '../src/type/markdown.type.ts';
+import type { SpaMode, WidgetManifestEntry } from '../src/type/widget.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';
+/** 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;
+}
+/**
+ * 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 manifest (alternative to reading from runtime) */
+    routesManifest?: RoutesManifest;
+    /** 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;
+}
+/**
+ * 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 routes manifest. */
+    readonly manifest: RoutesManifest;
+    /** Discovered widget entries. */
+    readonly widgetEntries: WidgetManifestEntry[];
+    /** The resolved HTML shell. */
+    readonly shell: string;
+}

package/dist/server/server-api.type.js

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

package/dist/server/server-api.type.js.map

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

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

@@ -0,0 +1,197 @@
+/**
+ * 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';
+/**
+ * Context passed to components during rendering.
+ * Extends RouteInfo (pathname, pattern, params, searchParams)
+ * 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 {
+    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;
+    /** Base path for SSR HTML links (e.g. '/html'). */
+    readonly basePath?: string;
+}
+/**
+ * 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 declare abstract class Component<TParams = unknown, TData = unknown, TContext extends ComponentContext = ComponentContext> {
+    /** Type carrier for getData args — use as `this['DataArgs']` in overrides. */
+    readonly DataArgs: {
+        params: TParams;
+        signal?: AbortSignal;
+        context: TContext;
+    };
+    /** Type carrier for render args — use as `this['RenderArgs']` in overrides. */
+    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;
+    /** 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;
+    /**
+     * 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;
+    /**
+     * Render error as markdown.
+     */
+    renderMarkdownError(error: unknown): string;
+}
+/**
+ * Component manifest entry for code generation.
+ */
+export interface ComponentManifestEntry {
+    name: string;
+    modulePath: string;
+    tagName: string;
+    type: 'page' | 'widget';
+    pattern?: string;
+}

package/dist/src/component/abstract.component.js

@@ -0,0 +1,84 @@
+/**
+ * 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 { escapeHtml } from "../util/html.util.js";
+/**
+ * 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 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.
+     *
+     * 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().
+     */
+    exposeSsrData;
+    /**
+     * Render as HTML for browser context.
+     *
+     * Default implementation converts renderMarkdown() output to HTML.
+     * Override for custom HTML rendering with rich styling/interactivity.
+     */
+    renderHTML(args) {
+        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>`;
+    }
+    /**
+     * Render error state.
+     */
+    renderError(args) {
+        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) {
+        const msg = error instanceof Error ? error.message : String(error);
+        return `> **Error** (\`${this.name}\`): ${msg}`;
+    }
+}
+//# sourceMappingURL=abstract.component.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"abstract.component.js","sourceRoot":"","sources":["../../../src/component/abstract.component.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAmDlD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAgB,SAAS;IAsB7B,sEAAsE;IACtE,OAAO,CAAe;IAEtB,oEAAoE;IAC3D,KAAK,CAAgD;IAE9D;;;;;;;;;;;;OAYG;IACM,aAAa,CAAW;IA6BjC;;;;;OAKG;IACH,UAAU,CAAC,IAAwB;QACjC,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;YACvB,OAAO,wBAAwB,IAAI,CAAC,IAAI,oBAAoB,CAAC;QAC/D,CAAC;QACD,wCAAwC;QACxC,6DAA6D;QAC7D,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;IAgCD;;OAEG;IACH,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;;OAEG;IACH,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/src/component/page.component.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Page Component
+ *
+ * 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, type ComponentContext } from './abstract.component.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;
+    /** Route pattern this page handles (optional — set by subclasses) */
+    readonly pattern?: string;
+    /**
+     * Fetch or compute page data. Override in subclasses.
+     * Default: returns null (no data needed).
+     *
+     * @example
+     * ```ts
+     * override getData({ params, context }: this['DataArgs']) {
+     *   return fetch(`/api/${params.id}`, { signal: context?.signal });
+     * }
+     * ```
+     */
+    getData(_args: this['DataArgs']): Promise<TData | null>;
+    /**
+     * Render page as HTML.
+     *
+     * Fallback chain:
+     * 1. html file content from context
+     * 2. md file content wrapped in `<mark-down>`
+     * 3. `<router-slot />` (bare slot for child routes)
+     *
+     * @example
+     * ```ts
+     * override renderHTML({ data, params, context }: this['RenderArgs']) {
+     *   return `<h1>${params.id}</h1><p>${context?.files?.html ?? ''}</p>`;
+     * }
+     * ```
+     */
+    renderHTML(args: this['RenderArgs']): string;
+    /**
+     * Render page as Markdown.
+     *
+     * Fallback chain:
+     * 1. md file content from context
+     * 2. `` ```router-slot\n``` `` (slot placeholder in markdown — newline required)
+     *
+     * @example
+     * ```ts
+     * override renderMarkdown({ data, params, context }: this['RenderArgs']) {
+     *   return `# ${params.id}\n\n${context?.files?.md ?? ''}`;
+     * }
+     * ```
+     */
+    renderMarkdown(args: this['RenderArgs']): string;
+    /**
+     * Page title. Override in subclasses.
+     * Default: undefined (no title).
+     *
+     * @example
+     * ```ts
+     * override getTitle({ data, params }: this['RenderArgs']) {
+     *   return `Project ${params.id}`;
+     * }
+     * ```
+     */
+    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;