@ecopages/core 0.2.0-alpha.22 → 0.2.0-alpha.24

package/src/types/public-types.d.ts

@@ -1,1219 +0,0 @@
-import type { Readable } from 'node:stream';
-import type { ApiResponseBuilder } from '../adapters/shared/api-response.js';
-import type { BuildExecutor } from '../build/build-adapter.js';
-import type { EcoBuildPlugin } from '../build/build-types.js';
-import type { ComponentBoundaryRuntime } from '../route-renderer/orchestration/component-render-context.js';
-import type { EcoPageComponent } from '../eco/eco.types.js';
-import type { EcoPagesAppConfig } from './internal-types.js';
-import type { HmrStrategy } from '../hmr/hmr-strategy.js';
-import type { BrowserBundleExecutor } from '../services/assets/browser-bundle.service.js';
-import type { ProcessedAsset } from '../services/assets/asset-processing-service/assets.types.js';
-import type { CacheStats, CacheStrategy } from '../services/cache/cache.types.js';
-import type { InteractionEventsString as ScriptsInjectorInteractionEventsString } from '@ecopages/scripts-injector/types';
-export type { EcoPagesAppConfig } from './internal-types.js';
-export type { EcoPageComponent } from '../eco/eco.types.js';
-export type { ProcessedAsset } from '../services/assets/asset-processing-service/assets.types.js';
-import type { StandardSchema, StandardSchemaResult, StandardSchemaSuccessResult, StandardSchemaFailureResult, StandardSchemaIssue, InferOutput } from '../services/validation/standard-schema.types.js';
-export type { StandardSchema, StandardSchemaResult, StandardSchemaSuccessResult, StandardSchemaFailureResult, StandardSchemaIssue, InferOutput, ComponentBoundaryRuntime, };
-export type InteractionEventsString = ScriptsInjectorInteractionEventsString;
-export type DependencyLazyTrigger = {
-    'on:idle': true;
-} | {
-    'on:interaction': InteractionEventsString;
-} | {
-    'on:visible': true | string;
-};
-export type DependencyAttributes = Record<string, string>;
-export type EcoComponentStylesheetEntry = {
-    src?: string;
-    content?: string;
-    attributes?: DependencyAttributes;
-};
-export type EcoComponentScriptEntry = {
-    src?: string;
-    content?: string;
-    attributes?: DependencyAttributes;
-    lazy?: DependencyLazyTrigger;
-    ssr?: boolean;
-};
-export type ResolvedLazyScriptGroup = {
-    lazy: DependencyLazyTrigger;
-    scripts: string;
-};
-export type LazyTriggerRule = {
-    'on:idle': {
-        scripts: string[];
-    };
-} | {
-    'on:interaction': {
-        value: string;
-        scripts: string[];
-    };
-} | {
-    'on:visible': {
-        value?: string;
-        scripts: string[];
-    };
-};
-export type ResolvedLazyTrigger = {
-    triggerId: string;
-    rules: LazyTriggerRule[];
-};
-/**
- * Narrow interface for cache invalidation in API handlers.
- * Exposes only the methods needed for programmatic cache control.
- */
-export interface CacheInvalidator {
-    /**
-     * Invalidate all cached entries matching any of the provided tags.
-     * @param tags - Array of tags to invalidate
-     * @returns Number of entries invalidated
-     */
-    invalidateByTags(tags: string[]): Promise<number>;
-    /**
-     * Invalidate cached entries by exact path.
-     * @param paths - Array of URL paths to invalidate
-     * @returns Number of entries invalidated
-     */
-    invalidateByPaths(paths: string[]): Promise<number>;
-    /**
-     * Clear all cached entries.
-     */
-    clear(): Promise<void>;
-    /**
-     * Get cache statistics for debugging.
-     */
-    stats(): Promise<CacheStats>;
-}
-/**
- * Context interface for HMR strategies.
- * Provides access to watched files, registered bare-specifier mappings, and build configuration.
- */
-export interface DefaultHmrContext {
-    /**
-     * Map of registered entrypoints to their output URLs.
-     */
-    getWatchedFiles(): Map<string, string>;
-    /**
-     * Map of bare specifiers to runtime URLs for browser import resolution.
-     */
-    getSpecifierMap(): Map<string, string>;
-    /**
-     * Directory where HMR bundles are written.
-     */
-    getDistDir(): string;
-    /**
-     * Build plugins to use during bundling.
-     */
-    getPlugins(): EcoBuildPlugin[];
-    /**
-     * Absolute path to the source directory.
-     */
-    getSrcDir(): string;
-    /**
-     * Absolute path to the layouts directory.
-     * Used to detect layout file changes that require full page reloads.
-     */
-    getLayoutsDir(): string;
-    /**
-     * Absolute path to the pages directory.
-     * Used by plugins to identify page files for transformation.
-     */
-    getPagesDir(): string;
-    /**
-     * Build executor owned by the active app/runtime.
-     */
-    getBuildExecutor(): BuildExecutor;
-    /**
-     * Browser bundler owned by the active app/runtime.
-     */
-    getBrowserBundleService(): BrowserBundleExecutor;
-    /**
-     * Server-side module loader owned by the active app/runtime.
-     */
-    importServerModule<T = unknown>(filePath: string): Promise<T>;
-}
-/**
- * Represents an event broadcast to connected clients via the ClientBridge.
- */
-export type ClientBridgeEvent = {
-    /**
-     * Event type: 'reload' triggers full refresh, 'update' for JS modules, 'css-update' for stylesheets, 'layout-update' for layout changes
-     */
-    type: 'reload' | 'error' | 'update' | 'css-update' | 'layout-update';
-    /**
-     * Path to the changed file
-     */
-    path?: string;
-    /**
-     * Optional message for error or debug info
-     */
-    message?: string;
-    /**
-     * Timestamp for cache busting
-     */
-    timestamp?: number;
-};
-/**
- * Adapter-agnostic interface for broadcasting development events to connected clients.
- * Implemented by both the Bun and Node client bridges.
- */
-export interface IClientBridge {
-    broadcast(event: ClientBridgeEvent): void;
-    reload(): void;
-    cssUpdate(path: string): void;
-    update(path: string): void;
-    error(message: string): void;
-    subscriberCount: number;
-}
-/**
- * Interface for the HMR Manager.
- * Used by integration plugins to register entrypoints and strategies.
- */
-export interface IHmrManager {
-    /**
-     * Registers an integration-owned client entrypoint to be built and watched.
-     *
-     * @remarks
-     * This path is strict: the owning integration must emit the expected `_hmr`
-     * bundle. Missing output is treated as a development pipeline failure.
-     */
-    registerEntrypoint(entrypointPath: string): Promise<string>;
-    /**
-     * Registers a generic script asset entrypoint to be built and watched.
-     *
-     * @remarks
-     * This path exists for non-page script assets that are not owned by a
-     * framework integration. Unlike `registerEntrypoint()`, it may use the generic
-     * script bundling path.
-     */
-    registerScriptEntrypoint(entrypointPath: string): Promise<string>;
-    /**
-     * Registers mappings from bare specifiers to runtime URLs.
-     *
-     * @remarks
-     * This is the shared registration seam for integration-owned runtime alias
-     * maps. The registry may later back a broader import-map-style facility, but
-     * the mappings themselves remain integration-owned.
-     */
-    registerSpecifierMap(map: Record<string, string>): void;
-    /**
-     * Registers a custom HMR strategy.
-     */
-    registerStrategy(strategy: HmrStrategy): void;
-    /**
-     * Sets the build plugins to use during bundling.
-     */
-    setPlugins(plugins: EcoBuildPlugin[]): void;
-    /**
-     * Enables or disables HMR.
-     */
-    setEnabled(enabled: boolean): void;
-    /**
-     * Returns whether HMR is enabled.
-     */
-    isEnabled(): boolean;
-    /**
-     * Broadcasts an HMR event to connected clients.
-     */
-    broadcast(event: ClientBridgeEvent): void;
-    /**
-     * Gets the output URL for a registered entrypoint.
-     */
-    getOutputUrl(entrypointPath: string): string | undefined;
-    /**
-     * Gets the map of watched files.
-     */
-    getWatchedFiles(): Map<string, string>;
-    /**
-     * Gets the registered bare-specifier map.
-     */
-    getSpecifierMap(): Map<string, string>;
-    /**
-     * Gets the HMR dist directory.
-     */
-    getDistDir(): string;
-    /**
-     * Gets the build plugins.
-     */
-    getPlugins(): EcoBuildPlugin[];
-    /**
-     * Gets the default HMR context.
-     */
-    getDefaultContext(): DefaultHmrContext;
-    /**
-     * Handles a file change event.
-     */
-    handleFileChange(path: string): Promise<void>;
-}
-/**
- * Represents the dependencies for an EcoComponent.
- */
-export type EcoComponentDependencies = {
-    stylesheets?: Array<string | EcoComponentStylesheetEntry>;
-    scripts?: Array<string | EcoComponentScriptEntry>;
-    /**
-     * Browser module declarations resolved from node_modules.
-     *
-     * Supports grammar entries such as `react-aria-components{Table,Select}`
-     * to express explicit module imports for client bundles.
-     */
-    modules?: string[];
-    components?: EcoComponent[];
-};
-export type EcoPagesElement = string | Promise<string>;
-/**
- * Serializable child payloads accepted by cross-integration deferred rendering.
- *
- * This models the broad value shapes that EcoPages already flattens when a
- * foreign component boundary serializes its children for another integration.
- * It is intentionally transport-oriented rather than framework-native, so it
- * can be shared across Kita, Lit, React, and Ecopages JSX authoring surfaces
- * without coupling core types to any one renderer.
- */
-export type EcoChildren = string | Promise<string> | number | bigint | boolean | null | undefined | readonly EcoChildren[] | {
-    strings: readonly string[];
-    values?: readonly EcoChildren[];
-} | {
-    [key: string]: EcoChildren;
-};
-/**
- * Represents the input configuration for EcoPages.
- */
-export type EcoPagesConfig = Omit<Partial<EcoPagesAppConfig>, 'baseUrl' | 'derivedPaths' | 'templatesExt' | 'integrationsDependencies'> & Pick<EcoPagesAppConfig, 'baseUrl' | 'rootDir'>;
-/**
- * Internal metadata injected by eco-component-meta-plugin.
- * Contains component file path and integration info for dependency resolution.
- * @internal
- */
-export interface EcoInjectedMeta {
-    /** Hashed identifier for client-side use (doesn't expose file paths) */
-    id: string;
-    /** Full file path of the component (use path.dirname() to get directory) */
-    file: string;
-    /** The integration identifier (e.g., 'react', 'kitajs', 'lit', 'ghtml', 'mdx') */
-    integration: string;
-}
-export type EcoComponentConfig = {
-    /** @internal Injected by eco-component-meta-plugin */
-    __eco?: EcoInjectedMeta;
-    /**
-     * Explicit integration override for this component.
-     * When provided, this takes precedence over auto-detected integration metadata.
-     */
-    integration?: string;
-    /**
-     * The layout component to wrap this page during rendering.
-     *
-     * The layout receives the page content as `children` and is responsible for
-     * providing the page structure (header, footer, navigation, etc.).
-     *
-     * For React pages with client-side routing, the layout also handles the router context.
-     * Use `EcoRouter` and `PageContent` from `@ecopages/react-router` in layouts that
-     * need SPA navigation support.
-     *
-     * @example
-     * ```tsx
-     * // Simple layout (no routing)
-     * const Layout = ({ children }) => <main>{children}</main>;
-     *
-     * // Layout with SPA routing
-     * const Layout = ({ children }) => (
-     *   <EcoRouter page={...} pageProps={...}>
-     *     <Header />
-     *     <PageContent />
-     *   </EcoRouter>
-     * );
-     *
-     * // Page using the layout
-     * const MyPage = () => <h1>Hello</h1>;
-     * MyPage.config = { layout: Layout };
-     * ```
-     */
-    layout?: EcoPageLayoutComponent<any>;
-    dependencies?: EcoComponentDependencies;
-    /**
-     * Internal: Resolved lazy scripts grouped by trigger.
-     * Set by the renderer, used by eco.component() for multi-trigger auto-wrapping.
-     * @internal
-     */
-    _resolvedLazyScripts?: ResolvedLazyScriptGroup[];
-    /**
-     * Internal: Resolved lazy triggers for the global injector map.
-     * Set by the renderer in the default full orchestration flow.
-     * @internal
-     */
-    _resolvedLazyTriggers?: ResolvedLazyTrigger[];
-};
-/**
- * The base structure for any EcoPages component.
- */
-export type EcoComponentBase = {
-    /**
-     * The configuration options for the EcoComponent.
-     */
-    config?: EcoComponentConfig;
-    /**
-     * Static paths for dynamic routes (consolidated eco.page API).
-     * @internal Used by the renderer to retrieve static paths from the page component.
-     */
-    staticPaths?: GetStaticPaths;
-    /**
-     * Static props fetcher (consolidated eco.page API).
-     * @internal Used by the renderer to retrieve static props from the page component.
-     */
-    staticProps?: GetStaticProps<any>;
-    /**
-     * Metadata generator (consolidated eco.page API).
-     * @internal Used by the renderer to retrieve metadata from the page component.
-     */
-    metadata?: GetMetadata<any>;
-};
-/**
- * Checks if a type is `any`.
- */
-export type IsAny<T> = 0 extends 1 & T ? true : false;
-/**
- * A function component type that is framework-agnostic.
- * Uses a broader signature to support both direct calls and HOC wrappers.
- */
-export type EcoFunctionComponent<P, R> = {
-    (props: P, ...args: any[]): R;
-} & EcoComponentBase;
-/**
- * Represents an EcoComponent.
- *
- * It can be defined by passing the props type as the first generic,
- * or by passing the component type itself to infer the signature.
- *
- * @template T - The type of the props object or the component function itself.
- * @template C - The type of the rendered element.
- *
- * @example
- * //1. Simplest usage
- * export const MyComponent: EcoComponent<{prop1: string}> = ({prop1}) => {
- *   return <div>...</div>;
- * };
- *
- * @example
- * // 2. Using with HOCs like MobX observer (passing the props type)
- * export const MyObservedComponent: EcoComponent<object> = observer(function MyObservedComponent() {
- *   return <div>...</div>;
- * });
- *
- * @example
- * // 3. Passing the full function signature (Perfect for Generic Components)
- * export const Select: EcoComponent<<T extends object>(props: SelectProps<T>) => JSX.Element> = <T extends object>({
- *   label,
- *   items,
- * }: SelectProps<T>) => {
- *   return <select>...</select>;
- * };
- */
-/**
- * A function component type that is framework-agnostic.
- * Uses a broader signature to support both direct calls and HOC wrappers.
- */
-export type EcoComponent<P = any, R = any> = IsAny<P> extends true ? EcoFunctionComponent<any, any> | EcoComponentBase : P extends (props: infer Props, ...args: any[]) => infer Return ? EcoFunctionComponent<Props, Return> : EcoFunctionComponent<P, R>;
-/**
- * Represents a page in EcoPages.
- */
-export type PageProps<T = unknown> = T & StaticPageContext & {
-    locals?: RequestLocals;
-};
-/**
- * Represents the metadata for a page.
- */
-export interface PageMetadataProps {
-    title: string;
-    description: string;
-    image?: string;
-    url?: string;
-    keywords?: string[];
-}
-/**
- * Represents the props for the head of a page.
- */
-export interface PageHeadProps<T = EcoPagesElement> {
-    metadata: PageMetadataProps;
-    dependencies?: EcoComponentDependencies;
-    children?: T;
-}
-/**
- * Represents the props for a route layout.
- */
-export interface LayoutProps<T = EcoPagesElement> extends Partial<RequestPageContext> {
-    children: T;
-}
-/**
- * Represents the props for the HTML template of a page.
- */
-export interface HtmlTemplateProps extends PageHeadProps {
-    children: EcoPagesElement;
-    language?: string;
-    headContent?: EcoPagesElement;
-    pageProps: Record<string, unknown>;
-}
-/**
- * Layout components accepted by pages.
- *
- * This preserves compatibility with existing `eco.component()` layouts while
- * also supporting semantic `eco.layout()` declarations.
- */
-export type EcoPageLayoutComponent<T = EcoPagesElement> = EcoLayoutComponent<T> | EcoComponent<any, T>;
-/**
- * Represents a layout component created with eco.layout().
- */
-export type EcoLayoutComponent<T = EcoPagesElement> = EcoComponent<LayoutProps<T>, T>;
-/**
- * Represents an HTML shell component created with eco.html().
- */
-export type EcoHtmlComponent<T = EcoPagesElement> = EcoComponent<HtmlTemplateProps, T>;
-/**
- * Represents the props for the error 404 template.
- */
-export interface Error404TemplateProps extends Omit<HtmlTemplateProps, 'children'> {
-    message: string;
-    stack?: string;
-}
-/**
- * Represents the parameters for a page.
- * The keys are strings, and the values can be either a string or an array of strings.
- */
-export type PageParams = Record<string, string | string[]>;
-/**
- * Represents a query object for a page.
- * The keys are strings and the values can be either a string or an array of strings.
- */
-export type PageQuery = Record<string, string | string[]>;
-/**
- * Request-scoped data that is only available during request-time rendering.
- *
- * Apps should augment this interface via module augmentation:
- *
- * declare module '@ecopages/core' {
- *   interface RequestLocals { session?: Session | null }
- * }
- */
-export interface RequestLocals {
-}
-/**
- * Represents the context object for a static page.
- */
-export type StaticPageContext = {
-    params?: PageParams;
-    query?: PageQuery;
-};
-/**
- * Request-time page context.
- *
- * This is only populated during SSR. Static generation must not access locals.
- */
-export type RequestPageContext = {
-    locals: RequestLocals;
-};
-/**
- * Adds optional `locals` to a props type.
- * Primarily used for layouts that may receive request-scoped data from middleware.
- *
- * @template P - The base props type
- *
- * @example
- * ```ts
- * type MyLayoutProps = WithLocals<{ children: ReactNode }>;
- * // { children: ReactNode; locals?: RequestLocals }
- * ```
- */
-export type WithLocals<P> = P & {
-    locals?: RequestLocals;
-};
-/**
- * Represents the params for a static path.
- */
-export type StaticPath = {
-    params: PageParams;
-};
-/**
- * The function that returns the static paths for a page.
- */
-export type GetStaticPaths = (context: {
-    appConfig: EcoPagesAppConfig;
-    runtimeOrigin: string;
-}) => Promise<{
-    paths: StaticPath[];
-}>;
-/**
- * The context object for the getMetadata function.
- */
-export type GetMetadataContext<T = Record<string, unknown>> = Required<StaticPageContext> & {
-    props: T;
-    appConfig: EcoPagesAppConfig;
-};
-/**
- * The function that returns the metadata for a page.
- */
-export type GetMetadata<T = Record<string, unknown>> = (context: GetMetadataContext<T>) => PageMetadataProps | Promise<PageMetadataProps>;
-/**
- * The function that returns the static props for a page.
- */
-export type GetStaticProps<T> = (context: {
-    pathname: StaticPath;
-    appConfig: EcoPagesAppConfig;
-    runtimeOrigin: string;
-}) => Promise<{
-    props: T;
-}>;
-/**
- * Represents a page file in EcoPages.
- * @template T - The type of the page props.
- */
-export type EcoPageFile<T = unknown> = T & {
-    default: EcoComponent<any, any>;
-    getStaticPaths?: GetStaticPaths;
-    getStaticProps?: GetStaticProps<Record<string, unknown>>;
-    getMetadata?: GetMetadata;
-    cache?: CacheStrategy;
-};
-/**
- * Represents a CSS processor.
- */
-export interface CssProcessor {
-    /**
-     * Processes a CSS file at the specified path.
-     * @param path - The path to the CSS file.
-     * @returns A promise that resolves to the processed CSS as a string.
-     */
-    processPath: (path: string, options?: any) => Promise<string>;
-    /**
-     * Processes a CSS string or buffer.
-     * @param contents - The CSS contents as a string or buffer.
-     * @returns A promise that resolves to the processed CSS as a string.
-     */
-    processStringOrBuffer: (contents: string | Buffer, options?: any) => Promise<string>;
-}
-/**
- * The options for the route renderer.
- */
-export type RouteRendererOptions = {
-    file: string;
-    params?: PageParams;
-    query?: PageQuery;
-    locals?: RequestLocals;
-};
-/**
- * The body of the route renderer.
- */
-export type RouteRendererBody = BodyInit | Readable;
-/**
- * Result of rendering a route, including body and optional cache configuration.
- */
-export type RouteRenderResult = {
-    body: RouteRendererBody;
-    /** Cache strategy from page component's eco.page({ cache }) option */
-    cacheStrategy?: CacheStrategy;
-};
-/**
- * Represents the dependencies required for an integration plugin.
- * It combines the base integration plugin dependencies with specific integration plugin dependencies.
- */
-export type IntegrationPluginDependencies = BaseIntegrationPluginDependencies & SpecificIntegrationPluginDependencies;
-type BaseIntegrationPluginDependencies = {
-    inline?: boolean;
-};
-/**
- * Represents the dependencies required for a specific integration plugin.
- * It can be one of the following types:
- * {@link ScriptImportIntegrationPluginDependencies}
- * {@link ScriptContentIntegrationPluginDependencies}
- * {@link StylesheetImportIntegrationPluginDependencies}
- * {@link StylesheetContentIntegrationPluginDependencies}
- */
-type SpecificIntegrationPluginDependencies = ScriptImportIntegrationPluginDependencies | ScriptContentIntegrationPluginDependencies | StylesheetImportIntegrationPluginDependencies | StylesheetContentIntegrationPluginDependencies;
-/**
- * Script dependencies for an integration plugin with an import path.
- */
-type ScriptImportIntegrationPluginDependencies = {
-    kind: 'script';
-    importPath: string;
-    position?: 'head' | 'body';
-    /** @default true */
-    minify?: boolean;
-};
-/**
- * Script dependencies for an integration plugin with content.
- */
-type ScriptContentIntegrationPluginDependencies = {
-    kind: 'script';
-    content: string;
-    position?: 'head' | 'body';
-    /** @default true */
-    minify?: boolean;
-};
-/**
- * Stylesheet dependencies for an integration plugin with an import path.
- */
-type StylesheetImportIntegrationPluginDependencies = {
-    kind: 'stylesheet';
-    importPath: string;
-};
-/**
- * Stylesheet dependencies for an integration plugin with content.
- */
-type StylesheetContentIntegrationPluginDependencies = {
-    kind: 'stylesheet';
-    content: string;
-};
-/**
- * The options for the integration renderer.
- */
-export type IntegrationRendererRenderOptions<C = EcoPagesElement> = RouteRendererOptions & {
-    props?: Record<string, unknown>;
-    metadata: PageMetadataProps;
-    HtmlTemplate: EcoHtmlComponent<C>;
-    Page: EcoComponent<PageProps, C>;
-    Layout?: EcoPageLayoutComponent<any>;
-    dependencies?: EcoComponentDependencies;
-    resolvedDependencies: ProcessedAsset[];
-    componentRender?: ComponentRenderResult;
-    pageProps?: Record<string, unknown>;
-    cacheStrategy?: CacheStrategy;
-    pageLocals?: RequestLocals;
-    boundaryPlan?: BoundaryPlan;
-};
-export type BoundaryValidationErrorCode = 'UNKNOWN_INTEGRATION_OWNER' | 'MISSING_COMPONENT_METADATA';
-export interface BoundaryValidationError {
-    code: BoundaryValidationErrorCode;
-    message: string;
-    componentId?: string;
-    componentFile?: string;
-    integrationName?: string;
-}
-export type BoundaryPlanNodeSource = 'route' | 'page' | 'layout' | 'html-template' | 'dependency';
-export interface BoundaryOwnership {
-    integrationName: string;
-    componentId: string;
-    componentFile?: string;
-    isPageEntry: boolean;
-    isForeignToParent: boolean;
-}
-export interface BoundaryPlanNode {
-    id: string;
-    source: BoundaryPlanNodeSource;
-    ownership: BoundaryOwnership;
-    children: BoundaryPlanNode[];
-    declaredDependenciesValid: boolean;
-}
-export interface BoundaryPlan {
-    root: BoundaryPlanNode;
-    rendererNames: string[];
-    foreignEdgeCount: number;
-    hasValidationErrors: boolean;
-    validationErrors: BoundaryValidationError[];
-}
-export type BoundaryAttachmentPolicy = {
-    kind: 'none';
-} | {
-    kind: 'first-element';
-};
-export interface BoundaryRenderPayload {
-    html: string;
-    assets: ProcessedAsset[];
-    rootTag?: string;
-    rootAttributes?: Record<string, string>;
-    attachmentPolicy: BoundaryAttachmentPolicy;
-    integrationName: string;
-}
-/**
- * Shared execution-scoped context threaded through component boundary renders.
- *
- * Integrations can extend this with renderer-local runtime keys, but the cache
- * and optional component instance identity are shared across all renderers.
- */
-export interface BaseIntegrationContext {
-    rendererCache?: Map<string, unknown>;
-    componentInstanceId?: string;
-}
-export interface ComponentRenderInput<TIntegrationContext extends BaseIntegrationContext = BaseIntegrationContext> {
-    component: EcoComponent;
-    props: Record<string, unknown>;
-    children?: unknown;
-    integrationContext?: TIntegrationContext;
-}
-export interface ComponentRenderResult {
-    html: string;
-    canAttachAttributes: boolean;
-    rootTag?: string;
-    integrationName: string;
-    rootAttributes?: Record<string, string>;
-    assets?: ProcessedAsset[];
-}
-/**
- * Represents a deep required type for a given object
- */
-export type DeepRequired<T> = Required<{
-    [K in keyof T]: T[K] extends Required<T[K]> ? T[K] : DeepRequired<T[K]>;
-}>;
-/**
- * The Prettify helper is a utility type that takes an object type and makes the hover overlay more readable.
- */
-export type Prettify<T> = {
-    [K in keyof T]: T[K];
-} & {};
-/**
- * Services available to API handlers.
- */
-export interface ApiHandlerServices {
-    /**
-     * Cache invalidation service.
-     * Null when caching is disabled.
-     */
-    cache: CacheInvalidator | null;
-}
-/**
- * Options for rendering a view.
- */
-export interface RenderOptions {
-    status?: number;
-    headers?: HeadersInit;
-}
-/**
- * Options for JSON/HTML response helpers.
- */
-export interface ResponseOptions {
-    status?: number;
-    headers?: HeadersInit;
-}
-/**
- * Context for rendering views in route handlers.
- * Provides methods to render eco.page views and return formatted responses.
- */
-export interface RenderContext {
-    /**
-     * Render an eco.page view with full layout and includes.
-     * @param view - The eco.page component to render
-     * @param props - Props to pass to the view
-     * @param options - Optional status code and headers
-     */
-    render<P = Record<string, unknown>>(view: EcoComponent<P>, props?: P, options?: RenderOptions): Promise<Response>;
-    /**
-     * Render an eco.page view without layout (for partials/fragments).
-     * @param view - The eco.page component to render
-     * @param props - Props to pass to the view
-     * @param options - Optional status code and headers
-     */
-    renderPartial<P = Record<string, unknown>>(view: EcoComponent<P>, props: P, options?: RenderOptions): Promise<Response>;
-    /**
-     * Return a JSON response.
-     * @param data - Data to serialize as JSON
-     * @param options - Optional status code and headers
-     */
-    json(data: unknown, options?: ResponseOptions): Response;
-    /**
-     * Return an HTML response.
-     * @param content - HTML string content
-     * @param options - Optional status code and headers
-     */
-    html(content: string, options?: ResponseOptions): Response;
-}
-/**
- * Context provided to the API handler.
- */
-export interface ApiHandlerContext<TRequest extends Request = Request, TServer = any> extends RenderContext {
-    request: TRequest;
-    params: Record<string, string>;
-    response: ApiResponseBuilder;
-    server: TServer;
-    /**
-     * Request-scoped data store.
-     * Only valid during request-time handling (SSR/API). Must not be used for static generation.
-     */
-    locals: RequestLocals;
-    /**
-     * Require one or more locals keys. If missing, executes `onMissing` to produce a terminating Response.
-     */
-    require: {
-        <K extends keyof RequestLocals>(key: K, onMissing: () => Response): Exclude<RequestLocals[K], null | undefined>;
-        <K extends keyof RequestLocals>(keys: readonly K[], onMissing: () => Response): {
-            [P in K]-?: Exclude<RequestLocals[P], null | undefined>;
-        };
-    };
-    /**
-     * Services available to the API handler.
-     */
-    services: ApiHandlerServices;
-    /**
-     * Parsed and optionally validated request body.
-     *
-     * - Without schema: Contains the parsed JSON body as `unknown`
-     * - With schema: Contains the validated and type-safe body data
-     *
-     * For raw access to the request body stream, use `ctx.request.body`.
-     *
-     * @example Without validation
-     * ```typescript
-     * app.post('/posts', async (ctx) => {
-     *   const data = ctx.body; // [unknown] - parsed JSON
-     *   return ctx.json({ received: data });
-     * });
-     * ```
-     *
-     * @example With validation
-     * ```typescript
-     * import { z } from 'zod';
-     *
-     * app.post('/posts', async (ctx) => {
-     *   const { title, author } = ctx.body; // [type-safe]
-     *   return ctx.json({ title, author });
-     * }, {
-     *   schema: {
-     *     body: z.object({ title: z.string(), author: z.string() })
-     *   }
-     * });
-     * ```
-     *
-     * Validation runs before the handler executes. Invalid requests receive a 400 response.
-     */
-    body?: unknown;
-    /**
-     * Parsed and optionally validated query parameters.
-     *
-     * - Without schema: Contains the parsed query params as a string record
-     * - With schema: Contains the validated and type-safe query data
-     *
-     * For raw access to query parameters, use `ctx.request.url` and parse manually.
-     *
-     * @example Pagination with type coercion
-     * ```typescript
-     * import { z } from 'zod';
-     *
-     * app.get('/posts', async (ctx) => {
-     *   const { page, limit, sortBy } = ctx.query;
-     *   // page: number, limit: number, sortBy: 'date' | 'title' | 'views'
-     *   return ctx.json({ page, limit, sortBy });
-     * }, {
-     *   schema: {
-     *     query: z.object({
-     *       page: z.coerce.number().min(1).default(1),
-     *       limit: z.coerce.number().min(1).max(100).default(20),
-     *       sortBy: z.enum(['date', 'title', 'views']).default('date')
-     *     })
-     *   }
-     * });
-     * ```
-     *
-     * @example Search with filters
-     * ```typescript
-     * app.get('/search', async (ctx) => {
-     *   const { q, category } = ctx.query;
-     *   return ctx.json({ results: await search(q, category) });
-     * }, {
-     *   schema: {
-     *     query: z.object({
-     *       q: z.string().min(2).max(100),
-     *       category: z.enum(['posts', 'users', 'comments']).optional()
-     *     })
-     *   }
-     * });
-     * ```
-     */
-    query?: unknown;
-    /**
-     * Parsed and optionally validated request headers.
-     *
-     * - Without schema: Contains the parsed headers as a string record
-     * - With schema: Contains the validated and type-safe header data
-     *
-     * For raw access to headers, use `ctx.request.headers`.
-     *
-     * @example API key authentication
-     * ```typescript
-     * import { z } from 'zod';
-     *
-     * app.post('/api/webhooks', async (ctx) => {
-     *   const apiKey = ctx.headers['x-api-key'];
-     *   // apiKey is guaranteed to be a valid UUID
-     *   return ctx.json({ received: true });
-     * }, {
-     *   schema: {
-     *     headers: z.object({
-     *       'x-api-key': z.string().uuid()
-     *     })
-     *   }
-     * });
-     * ```
-     *
-     * @example Webhook signature validation
-     * ```typescript
-     * app.post('/webhooks/stripe', async (ctx) => {
-     *   const signature = ctx.headers['stripe-signature'];
-     *   // signature is guaranteed to exist
-     *   const isValid = verifyStripeSignature(ctx.body, signature);
-     *   return ctx.json({ verified: isValid });
-     * }, {
-     *   schema: {
-     *     headers: z.object({
-     *       'stripe-signature': z.string().min(1)
-     *     })
-     *   }
-     * });
-     * ```
-     *
-     * @example Content negotiation
-     * ```typescript
-     * app.post('/api/data', async (ctx) => {
-     *   const { accept } = ctx.headers;
-     *   if (accept === 'application/xml') {
-     *     return ctx.html(toXml(data), { headers: { 'Content-Type': 'application/xml' } });
-     *   }
-     *   return ctx.json(data);
-     * }, {
-     *   schema: {
-     *     headers: z.object({
-     *       'content-type': z.literal('application/json'),
-     *       accept: z.enum(['application/json', 'application/xml']).optional()
-     *     })
-     *   }
-     * });
-     * ```
-     */
-    headers?: unknown;
-}
-/**
- * Next function for middleware chain.
- * Call to continue to the next middleware or final handler.
- */
-export type MiddlewareNext = () => Promise<Response>;
-/**
- * Middleware function signature.
- * Receives the request context and a next function to continue the chain.
- * Can short-circuit by returning a Response directly without calling next().
- *
- * @typeParam TRequest - Request type
- * @typeParam TServer - Server type
- * @typeParam TContext - Extended context type, defaults to base ApiHandlerContext
- *
- * @example Basic middleware (no context extension)
- * ```typescript
- * const loggingMiddleware: Middleware = async (ctx, next) => {
- *   console.log(`${ctx.request.method} ${ctx.request.url}`);
- *   return next();
- * };
- * ```
- *
- * @example Middleware with extended context (use EcoMiddleware helper)
- * ```typescript
- * type AuthContext = ApiHandlerContext<BunRequest<string>, Server> & { user: User };
- *
- * const authMiddleware: EcoMiddleware<AuthContext> = async (ctx, next) => {
- *   const user = await authenticate(ctx.request);
- *   if (!user) return ctx.response.status(401).json({ error: 'Unauthorized' });
- *   ctx.user = user;
- *   return next();
- * };
- * ```
- */
-export type Middleware<TRequest extends Request = Request, TServer = any, TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>> = (context: TContext, next: MiddlewareNext) => Promise<Response> | Response;
-/**
- * Helper type for defining middleware with extended context.
- * Automatically infers TRequest and TServer from the provided context type.
- *
- * @typeParam TContext - The extended context type that includes TRequest and TServer
- *
- * @example
- * ```typescript
- * type AuthContext = ApiHandlerContext<BunRequest<string>, Server> & {
- *   session: { user: User };
- * };
- *
- * const authMiddleware: EcoMiddleware<AuthContext> = async (ctx, next) => {
- *   const session = await authenticate(ctx.request);
- *   if (!session) return Response.redirect('/login');
- *   ctx.session = session;
- *   return next();
- * };
- * ```
- */
-export type EcoMiddleware<TContext extends ApiHandlerContext<any, any>> = TContext extends ApiHandlerContext<infer TRequest, infer TServer> ? Middleware<TRequest, TServer, TContext> : never;
-/**
- * Represents an API handler in EcoPages.
- * Defines the path, method, handler function, optional middleware, and validation schemas.
- *
- * @example Basic handler
- * ```typescript
- * app.get('/users/:id', async (ctx) => {
- *   return ctx.json({ id: ctx.params.id });
- * });
- * ```
- *
- * @example With validation
- * ```typescript
- * import { z } from 'zod';
- *
- * app.post('/posts', async (ctx) => {
- *   const { title, content } = ctx.body;
- *   return ctx.json({ success: true, title, content });
- * }, {
- *   schema: {
- *     body: z.object({
- *       title: z.string().min(3),
- *       content: z.string()
- *     })
- *   }
- * });
- * ```
- *
- * @example With middleware
- * ```typescript
- * const authMiddleware = async (ctx, next) => {
- *   if (!ctx.request.headers.get('authorization')) {
- *     return ctx.response.status(401).json({ error: 'Unauthorized' });
- *   }
- *   return next();
- * };
- *
- * app.get('/protected', async (ctx) => {
- *   return ctx.json({ message: 'Secret data' });
- * }, {
- *   middleware: [authMiddleware]
- * });
- * ```
- *
- * @example Multiple validations
- * ```typescript
- * import { z } from 'zod';
- *
- * app.post('/api/search', async (ctx) => {
- *   const { q, page } = ctx.query;
- *   const filters = ctx.body;
- *   return ctx.json({ query: q, page, filters });
- * }, {
- *   schema: {
- *     query: z.object({ q: z.string(), page: z.string() }),
- *     body: z.object({ category: z.string().optional() })
- *   }
- * });
- * ```
- */
-export interface ApiHandler<TPath extends string = string, TRequest extends Request = Request, TServer = any> {
-    path: TPath;
-    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'OPTIONS' | 'HEAD';
-    handler: (context: ApiHandlerContext<TRequest, TServer>) => Promise<Response> | Response;
-    /** Optional middleware chain executed before the handler */
-    middleware?: Middleware<TRequest, TServer, any>[];
-    /** Optional validation schemas for request body, query parameters, and headers */
-    schema?: {
-        body?: StandardSchema;
-        query?: StandardSchema;
-        headers?: StandardSchema;
-        params?: StandardSchema;
-    };
-}
-/**
- * Global error handler for centralized error handling across all routes.
- * Receives the error and full request context, returns a Response.
- * Falls back to default handling if the handler itself throws.
- */
-export type ErrorHandler<TRequest extends Request = Request, TServer = any> = (error: unknown, context: ApiHandlerContext<TRequest, TServer>) => Promise<Response> | Response;
-/**
- * Options for route handlers.
- */
-export interface RouteOptions<TRequest extends Request = Request, TServer = any, TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>> {
-    middleware?: Middleware<TRequest, TServer, TContext>[];
-    schema?: RouteSchema;
-}
-export interface RouteSchema {
-    body?: StandardSchema;
-    query?: StandardSchema;
-    headers?: StandardSchema;
-    params?: StandardSchema;
-}
-/**
- * Helper type to extract inferred types from a schema, with fallback to unknown.
- */
-export type InferSchemaOutput<T> = T extends StandardSchema ? InferOutput<T> : unknown;
-/**
- * Context with typed body/query/headers based on the provided schema.
- */
-export type TypedApiHandlerContext<TSchema extends RouteSchema, TRequest extends Request = Request, TServer = any> = Omit<ApiHandlerContext<TRequest, TServer>, 'body' | 'query' | 'headers'> & {
-    body: InferSchemaOutput<TSchema['body']>;
-    query: InferSchemaOutput<TSchema['query']>;
-    headers: InferSchemaOutput<TSchema['headers']>;
-    params: InferSchemaOutput<TSchema['params']>;
-};
-/**
- * Options for the group method.
- *
- * @typeParam TContext - Extended context type that middleware provides to handlers
- *
- * @example Group with auth middleware extending context
- * ```typescript
- * type AuthContext = ApiHandlerContext<BunRequest<string>, Server> & { user: User };
- *
- * app.group<AuthContext>('/api', (r) => {
- *   r.get('/profile', (ctx) => {
- *     // ctx.user is properly typed!
- *     return ctx.json({ name: ctx.user.name });
- *   });
- * }, { middleware: [authMiddleware] });
- * ```
- */
-export interface GroupOptions<TRequest extends Request = Request, TServer = any, TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>> {
-    middleware?: Middleware<TRequest, TServer, TContext>[];
-}
-/**
- * Context type that combines schema-typed fields with an extended base context.
- * Used by RouteGroupBuilder to merge schema validation types with middleware-extended context.
- * Note: Path parameter typing (e.g., :id -> params.id) comes from the TContext.request type.
- */
-export type TypedGroupHandlerContext<TSchema extends RouteSchema, TContext extends ApiHandlerContext<any, any>> = Omit<TContext, 'body' | 'query' | 'headers' | 'params'> & {
-    body: InferSchemaOutput<TSchema['body']>;
-    query: InferSchemaOutput<TSchema['query']>;
-    headers: InferSchemaOutput<TSchema['headers']>;
-    params: InferSchemaOutput<TSchema['params']>;
-};
-/**
- * Builder interface for defining routes within a group.
- * Provides chainable methods for registering routes with shared prefix and middleware.
- *
- * @typeParam TRequest - The request type
- * @typeParam TServer - The server type
- * @typeParam TContext - Extended context type from group middleware
- */
-export interface RouteGroupBuilder<TRequest extends Request = Request, TServer = any, TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>> {
-    get<P extends string, TSchema extends RouteSchema = RouteSchema>(path: P, handler: (context: TypedGroupHandlerContext<TSchema, TContext>) => Promise<Response> | Response, options?: RouteOptions<TRequest, TServer, TContext> & {
-        schema?: TSchema;
-    }): RouteGroupBuilder<TRequest, TServer, TContext>;
-    post<P extends string, TSchema extends RouteSchema = RouteSchema>(path: P, handler: (context: TypedGroupHandlerContext<TSchema, TContext>) => Promise<Response> | Response, options?: RouteOptions<TRequest, TServer, TContext> & {
-        schema?: TSchema;
-    }): RouteGroupBuilder<TRequest, TServer, TContext>;
-    put<P extends string, TSchema extends RouteSchema = RouteSchema>(path: P, handler: (context: TypedGroupHandlerContext<TSchema, TContext>) => Promise<Response> | Response, options?: RouteOptions<TRequest, TServer, TContext> & {
-        schema?: TSchema;
-    }): RouteGroupBuilder<TRequest, TServer, TContext>;
-    delete<P extends string, TSchema extends RouteSchema = RouteSchema>(path: P, handler: (context: TypedGroupHandlerContext<TSchema, TContext>) => Promise<Response> | Response, options?: RouteOptions<TRequest, TServer, TContext> & {
-        schema?: TSchema;
-    }): RouteGroupBuilder<TRequest, TServer, TContext>;
-    patch<P extends string, TSchema extends RouteSchema = RouteSchema>(path: P, handler: (context: TypedGroupHandlerContext<TSchema, TContext>) => Promise<Response> | Response, options?: RouteOptions<TRequest, TServer, TContext> & {
-        schema?: TSchema;
-    }): RouteGroupBuilder<TRequest, TServer, TContext>;
-    options<P extends string, TSchema extends RouteSchema = RouteSchema>(path: P, handler: (context: TypedGroupHandlerContext<TSchema, TContext>) => Promise<Response> | Response, options?: RouteOptions<TRequest, TServer, TContext> & {
-        schema?: TSchema;
-    }): RouteGroupBuilder<TRequest, TServer, TContext>;
-    head<P extends string, TSchema extends RouteSchema = RouteSchema>(path: P, handler: (context: TypedGroupHandlerContext<TSchema, TContext>) => Promise<Response> | Response, options?: RouteOptions<TRequest, TServer, TContext> & {
-        schema?: TSchema;
-    }): RouteGroupBuilder<TRequest, TServer, TContext>;
-}
-/**
- * A function that dynamically imports a view module.
- * Used by app.static() to enable HMR in development.
- */
-export type ViewLoader<P = any> = () => Promise<{
-    default: EcoPageComponent<P>;
-}>;
-/**
- * Represents a static route registered via app.static().
- * Uses a loader function to enable HMR in development mode.
- */
-export interface StaticRoute<P = any> {
-    path: string;
-    loader: ViewLoader<P>;
-}