@ecopages/core 0.2.0-alpha.54 → 0.2.0-alpha.55

package/src/dev/host-runtime.js

@@ -0,0 +1,24 @@
+import {
+  DevelopmentInvalidationService
+} from "../services/invalidation/development-invalidation.service.js";
+import { setHostModuleLoader } from "../services/module-loading/host-module-loader-registry.js";
+function createDevelopmentHostRuntime(appConfig) {
+  const invalidationService = new DevelopmentInvalidationService(appConfig);
+  return {
+    registerHostModuleLoader(loader) {
+      setHostModuleLoader(loader);
+    },
+    planFileChange(filePath) {
+      return invalidationService.planFileChange(filePath);
+    },
+    invalidateServerModules(changedFiles) {
+      invalidationService.invalidateServerModules(changedFiles);
+    },
+    resetRuntimeState(changedFiles) {
+      invalidationService.resetRuntimeState(changedFiles);
+    }
+  };
+}
+export {
+  createDevelopmentHostRuntime
+};

package/src/dev/sc-server.d.ts

@@ -0,0 +1,30 @@
+import type { Server } from 'bun';
+import type { EcoPagesAppConfig } from '../types/internal-types.js';
+type StaticContentServerOptions = {
+    port?: number;
+};
+/**
+ * Static content server for production builds.
+ * Serves pre-built static files from the dist directory with gzip compression support.
+ */
+export declare class StaticContentServer {
+    server: Server<unknown> | null;
+    private appConfig;
+    private options;
+    constructor({ appConfig, options }: {
+        appConfig: EcoPagesAppConfig;
+        options?: StaticContentServerOptions;
+    });
+    private shouldServeGzip;
+    private isHtml;
+    private sendNotFoundPage;
+    private serveFromDir;
+    fetch(request: Request): Promise<Response>;
+    private startServer;
+    stop(): void;
+    static createServer({ appConfig, options, }: {
+        appConfig: EcoPagesAppConfig;
+        options?: StaticContentServerOptions;
+    }): StaticContentServer;
+}
+export {};

package/src/dev/sc-server.js

@@ -0,0 +1,111 @@
+import { extname, join } from "node:path";
+import { STATUS_MESSAGE } from "../config/constants.js";
+import { fileSystem } from "@ecopages/file-system";
+import { ServerUtils } from "../utils/server-utils.module.js";
+import { getRequiredBunRuntime } from "../utils/runtime.js";
+class StaticContentServer {
+  server = null;
+  appConfig;
+  options = { port: 3e3 };
+  constructor({ appConfig, options }) {
+    this.appConfig = appConfig;
+    if (options) this.options = options;
+    this.startServer();
+  }
+  shouldServeGzip(contentType) {
+    return ["text/javascript", "text/css"].includes(contentType);
+  }
+  isHtml(contentType) {
+    return contentType === "text/html";
+  }
+  async sendNotFoundPage() {
+    const error404TemplatePath = `${this.appConfig.absolutePaths.distDir}/404.html`;
+    try {
+      fileSystem.exists(error404TemplatePath);
+    } catch {
+      return new Response(STATUS_MESSAGE[404], {
+        status: 404
+      });
+    }
+    const response = new Response(fileSystem.readFileAsBuffer(error404TemplatePath), {
+      headers: { "Content-Type": "text/html" }
+    });
+    return response;
+  }
+  async serveFromDir({ path, request }) {
+    const { absolutePaths } = this.appConfig;
+    const basePath = join(absolutePaths.distDir, path);
+    const contentType = ServerUtils.getContentType(extname(basePath));
+    const acceptsGzip = request.headers.get("Accept-Encoding")?.includes("gzip");
+    try {
+      if (acceptsGzip && this.shouldServeGzip(contentType)) {
+        const gzipPath = `${basePath}.gz`;
+        if (fileSystem.exists(gzipPath)) {
+          const file = fileSystem.readFileAsBuffer(gzipPath);
+          return new Response(file, {
+            headers: {
+              "Content-Type": contentType,
+              "Content-Encoding": "gzip",
+              Vary: "Accept-Encoding"
+            }
+          });
+        }
+      }
+      if (path.includes(".") && fileSystem.exists(basePath)) {
+        const file = fileSystem.readFileAsBuffer(basePath);
+        return new Response(file, {
+          headers: { "Content-Type": contentType }
+        });
+      }
+      const htmlCandidates = [`${basePath}.html`, `${basePath}/index.html`];
+      for (const candidate of htmlCandidates) {
+        if (fileSystem.exists(candidate)) {
+          const file = fileSystem.readFileAsBuffer(candidate);
+          return new Response(file, {
+            headers: {
+              "Content-Type": ServerUtils.getContentType(extname(candidate))
+            }
+          });
+        }
+      }
+      return this.sendNotFoundPage();
+    } catch {
+      return this.sendNotFoundPage();
+    }
+  }
+  async fetch(request) {
+    let reqPath = new URL(request.url).pathname;
+    if (reqPath === "/") reqPath = "/index.html";
+    const response = this.serveFromDir({
+      path: reqPath,
+      request
+    });
+    if (response) return response;
+    return new Response(STATUS_MESSAGE[404], {
+      status: 404
+    });
+  }
+  startServer() {
+    this.server = getRequiredBunRuntime().serve({
+      fetch: this.fetch.bind(this),
+      port: this.options.port
+    });
+  }
+  stop() {
+    if (this.server) {
+      this.server.stop(true);
+    }
+  }
+  static createServer({
+    appConfig,
+    options
+  }) {
+    return new StaticContentServer({
+      appConfig,
+      options
+    });
+  }
+}
+export {
+  StaticContentServer
+};

package/src/eco/eco.browser.d.ts

@@ -0,0 +1,2 @@
+import type { Eco } from './eco.types.js';
+export declare const eco: Eco;

package/src/eco/eco.browser.js

@@ -0,0 +1,88 @@
+function createComponentFactory(options) {
+  const component2 = ((props) => options.render(props));
+  component2.config = {
+    __eco: options.__eco,
+    integration: options.integration,
+    dependencies: options.dependencies
+  };
+  return component2;
+}
+function component(options) {
+  return createComponentFactory(options);
+}
+function embed(component2, props, children) {
+  const nextProps = children === void 0 ? props : { ...props, children };
+  return component2(nextProps);
+}
+function html(options) {
+  return createComponentFactory(options);
+}
+function layout(options) {
+  return createComponentFactory(options);
+}
+function page(options) {
+  const {
+    layout: pageLayout,
+    dependencies,
+    render,
+    staticPaths: staticPaths2,
+    staticProps: staticProps2,
+    metadata: metadata2,
+    cache,
+    requires,
+    middleware
+  } = options;
+  const pageComponent = createComponentFactory({
+    __eco: options.__eco,
+    integration: options.integration,
+    dependencies: pageLayout ? {
+      ...dependencies,
+      components: [...dependencies?.components ?? [], pageLayout]
+    } : dependencies,
+    render
+  });
+  if (pageLayout && pageComponent.config) {
+    pageComponent.config.layout = pageLayout;
+  }
+  if (staticPaths2) {
+    pageComponent.staticPaths = staticPaths2;
+  }
+  if (staticProps2) {
+    pageComponent.staticProps = staticProps2;
+  }
+  if (metadata2) {
+    pageComponent.metadata = metadata2;
+  }
+  if (cache) {
+    pageComponent.cache = cache;
+  }
+  if (requires) {
+    pageComponent.requires = requires;
+  }
+  if (middleware) {
+    pageComponent.middleware = middleware;
+  }
+  return pageComponent;
+}
+function metadata(fn) {
+  return fn;
+}
+function staticPaths(fn) {
+  return fn;
+}
+function staticProps(fn) {
+  return fn;
+}
+const eco = {
+  component,
+  embed,
+  html,
+  layout,
+  page,
+  metadata,
+  staticPaths,
+  staticProps
+};
+export {
+  eco
+};

package/src/eco/eco.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The eco namespace - unified component and page factory API
+ * @module
+ */
+import type { Eco } from './eco.types.js';
+/**
+ * The eco namespace - provides factories for components and pages
+ */
+export declare const eco: Eco;

package/src/eco/eco.js

@@ -0,0 +1,119 @@
+import {
+  finalizeComponentRender,
+  getComponentRenderContext,
+  interceptForeignChild
+} from "../route-renderer/orchestration/component-render-context.js";
+import { isThenable } from "../route-renderer/orchestration/render-output.utils.js";
+function createComponentFactory(options) {
+  const integrationName = options.integration ?? options.__eco?.integration;
+  const comp = ((props) => {
+    const componentProps = props ?? {};
+    const renderInline = (nextProps = props) => finalizeComponentRender(comp, options.render(nextProps));
+    const activeRenderContext = getComponentRenderContext();
+    const foreignChildRender = interceptForeignChild({
+      component: comp,
+      props: componentProps,
+      targetIntegration: integrationName
+    });
+    if (isThenable(foreignChildRender)) {
+      return foreignChildRender.then((resolvedForeignChildRender) => {
+        if (resolvedForeignChildRender?.kind === "resolved") {
+          return resolvedForeignChildRender.value;
+        }
+        return renderInline(resolvedForeignChildRender?.props ?? props);
+      });
+    }
+    if (foreignChildRender?.kind === "resolved") {
+      return foreignChildRender.value;
+    }
+    if (foreignChildRender?.kind === "inline") {
+      return renderInline(foreignChildRender.props ?? props);
+    }
+    if (activeRenderContext && activeRenderContext.foreignChildRuntime && integrationName && integrationName !== activeRenderContext.currentIntegration) {
+      throw new Error(
+        `[ecopages] Missing foreign-child interception from ${activeRenderContext.currentIntegration} to ${integrationName} for ${options.__eco?.file ?? "unknown component"}.`
+      );
+    }
+    return renderInline();
+  });
+  comp.config = {
+    __eco: options.__eco,
+    integration: options.integration,
+    dependencies: options.dependencies
+  };
+  return comp;
+}
+function component(options) {
+  return createComponentFactory(options);
+}
+function isMissingForeignChildInterceptionError(error) {
+  return error instanceof Error && error.message.startsWith("[ecopages] Missing foreign-child interception from ");
+}
+function embed(component2, props, children) {
+  const activeRenderContext = getComponentRenderContext();
+  const ecoComponent = component2;
+  const targetIntegration = ecoComponent.config?.integration ?? ecoComponent.config?.__eco?.integration;
+  const componentFile = ecoComponent.config?.__eco?.file ?? "unknown component";
+  const nextProps = children === void 0 ? props : { ...props, children };
+  try {
+    return component2(nextProps);
+  } catch (error) {
+    if (!isMissingForeignChildInterceptionError(error)) {
+      throw error;
+    }
+    throw new Error(
+      `[ecopages] eco.embed() could not hand off the Foreign Child from ${activeRenderContext?.currentIntegration ?? "unknown integration"} to ${targetIntegration ?? "unknown integration"} for ${componentFile}. The active Integration renderer exposed a foreign-child runtime, but it did not intercept this cross-integration render. Ensure mixed-integration Page, Layout, Html, or Component renders install foreign-child handoff before calling eco.embed().`
+    );
+  }
+}
+function html(options) {
+  return createComponentFactory(options);
+}
+function layout(options) {
+  return createComponentFactory(options);
+}
+function page(options) {
+  const { layout: layout2, dependencies, render, staticPaths: staticPaths2, staticProps: staticProps2, metadata: metadata2, cache, requires, middleware } = options;
+  const componentOptions = {
+    __eco: options.__eco,
+    integration: options.integration,
+    dependencies: layout2 ? {
+      ...dependencies,
+      components: [...dependencies?.components || [], layout2]
+    } : dependencies,
+    render
+  };
+  const pageComponent = createComponentFactory(componentOptions);
+  if (layout2 && pageComponent.config) {
+    pageComponent.config.layout = layout2;
+  }
+  if (staticPaths2) pageComponent.staticPaths = staticPaths2;
+  if (staticProps2) pageComponent.staticProps = staticProps2;
+  if (metadata2) pageComponent.metadata = metadata2;
+  if (cache) pageComponent.cache = cache;
+  if (requires) pageComponent.requires = requires;
+  if (middleware) pageComponent.middleware = middleware;
+  return pageComponent;
+}
+function metadata(fn) {
+  return fn;
+}
+function staticPaths(fn) {
+  return fn;
+}
+function staticProps(fn) {
+  return fn;
+}
+const eco = {
+  component,
+  embed,
+  html,
+  layout,
+  page,
+  metadata,
+  staticPaths,
+  staticProps
+};
+export {
+  eco
+};

package/src/eco/eco.types.d.ts

@@ -0,0 +1,230 @@
+/**
+ * Type definitions for the eco namespace API
+ * @module
+ */
+import type { DependencyLazyTrigger, EcoComponent, EcoComponentDependencies, EcoHtmlComponent, EcoInjectedMeta, EcoLayoutComponent, EcoPageLayoutComponent, EcoPagesElement, FileRouteMiddleware, GetMetadata, GetStaticPaths, GetStaticProps, HtmlTemplateProps, LayoutProps, RequestLocals, RequestPageContext } from '../types/public-types.js';
+import type { CacheStrategy } from '../services/cache/cache.types.js';
+/**
+ * Extracts the props type from one eco component.
+ */
+export type PropsOf<TComponent extends EcoComponent> = TComponent extends EcoComponent<infer P, any> ? P : never;
+/**
+ * Extracts the render result type from one eco component.
+ */
+export type ResultOf<TComponent extends EcoComponent> = TComponent extends EcoComponent<any, infer R> ? R : never;
+/**
+ * Narrows an eco component to its callable function signature.
+ *
+ * This is useful for helper modules such as `EcoEmbed` that invoke a component
+ * directly and need to exclude the non-callable metadata shape from the public
+ * type surface.
+ */
+export type CallableComponentOf<TComponent extends EcoComponent> = Extract<TComponent, (props: any, ...args: any[]) => any>;
+/**
+ * Extracts the declared `children` type from one eco component when present.
+ */
+export type ChildrenOf<TComponent extends EcoComponent> = PropsOf<TComponent> extends {
+    children?: infer T;
+} ? T : PropsOf<TComponent> extends {
+    children: infer T;
+} ? T : never;
+/**
+ * Extracts the props accepted by `eco.embed()` before optional `children`
+ * injection.
+ *
+ * When the target component already declares `children`, callers pass the rest
+ * of the props bag here and provide `children` as the third `eco.embed()`
+ * argument or the `EcoEmbed` wrapper children slot.
+ */
+export type EmbedPropsOf<TComponent extends EcoComponent> = 'children' extends keyof PropsOf<TComponent> ? Omit<PropsOf<TComponent>, 'children'> : PropsOf<TComponent>;
+/**
+ * Props accepted by integration-owned `EcoEmbed` adapters.
+ *
+ * The `component` field is narrowed to the callable portion of the target eco
+ * component so JSX wrappers can invoke `eco.embed()` without repeating local
+ * callable-component extraction logic.
+ */
+export type EcoEmbedProps<TComponent extends EcoComponent> = {
+    component: CallableComponentOf<TComponent>;
+    props: EmbedPropsOf<TComponent>;
+    children?: unknown;
+};
+type WithRequiredLocals<K extends keyof RequestLocals> = Omit<RequestLocals, K> & {
+    [P in K]-?: Exclude<RequestLocals[P], null | undefined>;
+};
+type RequiresKeys = keyof RequestLocals;
+export type PageRequires<K extends RequiresKeys = RequiresKeys> = K | readonly K[];
+/**
+ * Lazy trigger options map directly to scripts-injector attributes.
+ * Only one trigger type can be active at a time.
+ */
+export type LazyTrigger = DependencyLazyTrigger;
+/**
+ * Options for creating a component with eco.component()
+ * @template P - The props type for the component
+ * @template E - The element/return type (defaults to EcoPagesElement for Kita, use ReactNode for React)
+ */
+export interface ComponentOptions<P, E = EcoPagesElement> {
+    /** @internal Injected by eco-component-meta-plugin */
+    __eco?: EcoInjectedMeta;
+    integration?: string;
+    dependencies?: EcoComponentDependencies;
+    render: (props: P) => E | Promise<E>;
+}
+export type HtmlOptions<E = EcoPagesElement> = ComponentOptions<HtmlTemplateProps, E>;
+export type LayoutOptions<E = EcoPagesElement> = ComponentOptions<LayoutProps<E>, E>;
+/**
+ * Base options shared by all page variants
+ */
+export interface PageOptionsBase<T, E = EcoPagesElement> {
+    /** @internal Injected by eco-component-meta-plugin */
+    __eco?: EcoInjectedMeta;
+    integration?: string;
+    dependencies?: EcoComponentDependencies;
+    layout?: EcoPageLayoutComponent<E>;
+    /**
+     * Define static paths for dynamic routes (e.g., [slug].tsx).
+     * Returns all possible paths that should be pre-rendered at build time.
+     */
+    staticPaths?: GetStaticPaths;
+    /**
+     * Fetch data for the page at build time.
+     * Props returned here are passed to both render() and metadata().
+     */
+    staticProps?: GetStaticProps<T>;
+    /**
+     * Generate page metadata (title, description, etc.).
+     * Receives props from staticProps if defined.
+     */
+    metadata?: GetMetadata<T>;
+    /**
+     * Declares which `locals` keys must be present for this page.
+     *
+     * This is a typing and documentation feature; runtime enforcement must be done via handler/page middleware.
+     */
+    requires?: PageRequires;
+    render: (props: PagePropsFor<T> & Partial<RequestPageContext>) => E | Promise<E>;
+}
+/**
+ * Page options without middleware - allows any cache strategy
+ */
+interface PageOptionsWithoutMiddleware<T, E = EcoPagesElement> extends PageOptionsBase<T, E> {
+    /**
+     * Cache configuration for ISR (Incremental Static Regeneration).
+     * - `'static'`: Cache indefinitely (default)
+     * - `'dynamic'`: No caching, render on every request
+     * - `{ revalidate: number, tags?: string[] }`: Cache with time-based revalidation
+     */
+    cache?: CacheStrategy;
+    middleware?: undefined;
+}
+/**
+ * Page options with middleware - requires cache: 'dynamic'
+ */
+interface PageOptionsWithMiddleware<T, E = EcoPagesElement> extends PageOptionsBase<T, E> {
+    /**
+     * Cache must be 'dynamic' when using middleware.
+     * Middleware runs on every request, so caching would bypass middleware effects.
+     */
+    cache: 'dynamic';
+    /**
+     * Request-time middleware for file-based routes.
+     * Runs before rendering and can short-circuit by returning a Response.
+     */
+    middleware: FileRouteMiddleware[];
+}
+/**
+ * Options for creating a page with eco.page()
+ *
+ * Define staticPaths, staticProps, and metadata inline. When using
+ * `middleware`, `cache` must be set to `'dynamic'` because middleware
+ * runs on every request and caching would bypass middleware effects.
+ *
+ * @template T - The props type for the page
+ * @template E - The element/return type (defaults to EcoPagesElement for Kita, use ReactNode for React)
+ */
+export type PageOptions<T, E = EcoPagesElement> = PageOptionsWithoutMiddleware<T, E> | PageOptionsWithMiddleware<T, E>;
+export type PagePropsForWithLocals<T, K extends RequiresKeys | never = never> = PagePropsFor<T> & (K extends never ? Partial<RequestPageContext> : Omit<Partial<RequestPageContext>, 'locals'> & {
+    locals: WithRequiredLocals<Extract<K, keyof RequestLocals>>;
+});
+/**
+ * Extracts props type from getStaticProps return type, or uses T directly if it's a props object.
+ * Always includes params and query for page context.
+ */
+export type PagePropsFor<T> = T extends GetStaticProps<infer P> ? P & {
+    params?: Record<string, string>;
+    query?: Record<string, string>;
+} : T & {
+    params?: Record<string, string>;
+    query?: Record<string, string>;
+};
+/**
+ * A page component with optional attached static functions.
+ * Used by the consolidated eco.page() API where staticPaths, staticProps,
+ * and metadata are defined inline and attached to the component.
+ */
+export type EcoPageComponent<T> = EcoComponent<PagePropsFor<T> & Partial<RequestPageContext>> & {
+    staticPaths?: GetStaticPaths;
+    staticProps?: GetStaticProps<T>;
+    metadata?: GetMetadata<T>;
+    cache?: CacheStrategy;
+    requires?: PageRequires;
+    middleware?: FileRouteMiddleware[];
+};
+/**
+ * The eco namespace interface
+ */
+export interface Eco {
+    /**
+     * Create a reusable component with dependencies and optional lazy-loading.
+     * @template P - Props type
+     * @template E - Element/return type (EcoPagesElement for Kita, ReactNode for React)
+     */
+    component: <P = {}, E = EcoPagesElement>(options: ComponentOptions<P, E>) => EcoComponent<P, E>;
+    /**
+     * Render a component explicitly, with an optional `children` argument.
+     *
+     * This is useful when authoring crosses integration boundaries and inline JSX
+     * would otherwise force one file to model multiple JSX namespaces.
+     */
+    embed: {
+        <TComponent extends EcoComponent>(component: CallableComponentOf<TComponent>, props: PropsOf<TComponent>): ResultOf<TComponent>;
+        <TComponent extends EcoComponent>(component: CallableComponentOf<TComponent>, props: EmbedPropsOf<TComponent>, children: ChildrenOf<TComponent> | unknown): ResultOf<TComponent>;
+    };
+    /**
+     * Create a document shell component for the HTML wrapper.
+     */
+    html: <E = EcoPagesElement>(options: HtmlOptions<E>) => EcoHtmlComponent<E>;
+    /**
+     * Create a route layout component.
+     */
+    layout: <E = EcoPagesElement>(options: LayoutOptions<E>) => EcoLayoutComponent<E>;
+    /**
+     * Create a page component with type-safe props from getStaticProps.
+     * Returns an EcoPageComponent with attached staticPaths, staticProps, and metadata.
+     *
+     * If `requires` is provided, the `render` callback receives `locals` as required and non-null for the required keys.
+     */
+    page: {
+        <T = {}, E = EcoPagesElement>(options: PageOptions<T, E> & {
+            requires?: undefined;
+        }): EcoPageComponent<T>;
+        <T = {}, E = EcoPagesElement, const K extends RequiresKeys = RequiresKeys>(options: Omit<PageOptions<T, E>, 'render' | 'requires'> & {
+            requires: PageRequires<K>;
+            render: (props: PagePropsForWithLocals<T, K>) => E | Promise<E>;
+        }): EcoPageComponent<T>;
+    };
+    /**
+     * Type-safe wrapper for page metadata (identity function)
+     */
+    metadata: <P = {}>(fn: GetMetadata<P>) => GetMetadata<P>;
+    /**
+     * Type-safe wrapper for static paths (identity function)
+     */
+    staticPaths: (fn: GetStaticPaths) => GetStaticPaths;
+    /**
+     * Type-safe wrapper for static props (identity function)
+     */
+    staticProps: <P>(fn: GetStaticProps<P>) => GetStaticProps<P>;
+}
+export {};

package/src/eco/eco.utils.d.ts

@@ -0,0 +1 @@
+export { addTriggerAttribute, isThenable, wrapWithScriptsInjector, } from '../route-renderer/orchestration/render-output.utils.js';

package/src/eco/eco.utils.js

@@ -0,0 +1,10 @@
+import {
+  addTriggerAttribute,
+  isThenable,
+  wrapWithScriptsInjector
+} from "../route-renderer/orchestration/render-output.utils.js";
+export {
+  addTriggerAttribute,
+  isThenable,
+  wrapWithScriptsInjector
+};

package/src/eco/global-injector-map.d.ts

@@ -0,0 +1,16 @@
+import type { ResolvedLazyTrigger } from '../types/public-types.js';
+/**
+ * Serializes resolved lazy triggers into a JSON string safe for embedding
+ * inside an inline `<script type="ecopages/global-injector-map">` tag.
+ *
+ * The `</script` sequence is escaped because an unescaped occurrence in inline
+ * script content causes the HTML parser to close the script tag prematurely,
+ * breaking page rendering. `JSON.stringify` does not perform this escape by
+ * default, so a targeted replacement is applied after serialization.
+ */
+export declare function buildGlobalInjectorMapScript(triggers: ResolvedLazyTrigger[]): string;
+/**
+ * Builds the module source that boots the global lazy injector on the client.
+ * Emitted once per page alongside the `ecopages/global-injector-map` script block.
+ */
+export declare function buildGlobalInjectorBootstrapContent(globalInjectorModuleSpecifier: string): string;