@ecopages/core 0.2.0-alpha.3 → 0.2.0-alpha.31

package/src/{public-types.d.ts → types/public-types.d.ts}

@@ -1,15 +1,20 @@
 import type { Readable } from 'node:stream';
-import type { ApiResponseBuilder } from './adapters/shared/api-response.js';
-import type { EcoBuildPlugin } from './build/build-types.js';
-import type { EcoPageComponent } from './eco/eco.types.js';
+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 { ForeignChildRuntime } 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 { ProcessedAsset } from './services/asset-processing-service/assets.types.js';
-import type { CacheStats, CacheStrategy } from './services/cache/cache.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 { EcoPageComponent } from './eco/eco.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, };
+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, ForeignChildRuntime, };
 export type InteractionEventsString = ScriptsInjectorInteractionEventsString;
 export type DependencyLazyTrigger = {
     'on:idle': true;
@@ -82,17 +87,13 @@ export interface CacheInvalidator {
 }
 /**
  * Context interface for HMR strategies.
- * Provides access to watched files, specifier mappings, and build configuration.
+ * 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 vendor URLs for import resolution.
-     */
-    getSpecifierMap(): Map<string, string>;
     /**
      * Directory where HMR bundles are written.
      */
@@ -115,6 +116,18 @@ export interface DefaultHmrContext {
      * 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.
@@ -155,13 +168,22 @@ export interface IClientBridge {
  */
 export interface IHmrManager {
     /**
-     * Registers a client entrypoint to be built and watched.
+     * 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 mappings from bare specifiers to vendor URLs.
+     * 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.
      */
-    registerSpecifierMap(map: Record<string, string>): void;
+    registerScriptEntrypoint(entrypointPath: string): Promise<string>;
     /**
      * Registers a custom HMR strategy.
      */
@@ -178,10 +200,6 @@ export interface IHmrManager {
      * Returns whether HMR is enabled.
      */
     isEnabled(): boolean;
-    /**
-     * Returns true when a changed file matches a non-fallback HMR strategy.
-     */
-    canHandleFileChange(path: string): boolean;
     /**
      * Broadcasts an HMR event to connected clients.
      */
@@ -194,10 +212,6 @@ export interface IHmrManager {
      * Gets the map of watched files.
      */
     getWatchedFiles(): Map<string, string>;
-    /**
-     * Gets the specifier map.
-     */
-    getSpecifierMap(): Map<string, string>;
     /**
      * Gets the HMR dist directory.
      */
@@ -231,6 +245,21 @@ export type EcoComponentDependencies = {
     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.
  */
@@ -284,7 +313,7 @@ export type EcoComponentConfig = {
      * MyPage.config = { layout: Layout };
      * ```
      */
-    layout?: EcoComponent;
+    layout?: EcoPageLayoutComponent<any>;
     dependencies?: EcoComponentDependencies;
     /**
      * Internal: Resolved lazy scripts grouped by trigger.
@@ -393,6 +422,12 @@ export interface PageHeadProps<T = EcoPagesElement> {
     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.
  */
@@ -402,6 +437,21 @@ export interface HtmlTemplateProps extends PageHeadProps {
     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.
  */
@@ -602,21 +652,127 @@ type StylesheetContentIntegrationPluginDependencies = {
 export type IntegrationRendererRenderOptions<C = EcoPagesElement> = RouteRendererOptions & {
     props?: Record<string, unknown>;
     metadata: PageMetadataProps;
-    HtmlTemplate: EcoComponent<HtmlTemplateProps, C>;
+    HtmlTemplate: EcoHtmlComponent<C>;
     Page: EcoComponent<PageProps, C>;
-    Layout?: EcoComponent;
+    Layout?: EcoPageLayoutComponent<any>;
     dependencies?: EcoComponentDependencies;
     resolvedDependencies: ProcessedAsset[];
+    pagePackage?: PagePackageResult;
     componentRender?: ComponentRenderResult;
     pageProps?: Record<string, unknown>;
     cacheStrategy?: CacheStrategy;
     pageLocals?: RequestLocals;
+    ownershipPlan?: OwnershipPlan;
 };
-export interface ComponentRenderInput {
+/**
+ * Structured page asset package produced after dependency resolution.
+ *
+ * `assets` retains the full processed asset list, while the remaining fields
+ * split that list into the subsets used during final HTML injection and
+ * renderer-owned follow-up work.
+ */
+export interface PagePackageResult {
+    /**
+     * Full processed asset list before any page-level partitioning.
+     */
+    assets: ProcessedAsset[];
+    /**
+     * Assets that should still be injected into the final HTML document.
+     */
+    htmlAssets: ProcessedAsset[];
+    /**
+     * Primary page-owned browser entry when one was identified during packaging.
+     */
+    pageScript?: ProcessedAsset;
+    /**
+     * Primary page-owned stylesheet when one was identified during packaging.
+     */
+    pageStylesheet?: ProcessedAsset;
+    /**
+     * Inline assets that remain embedded directly in the document.
+     */
+    inlineAssets: ProcessedAsset[];
+    /**
+     * Assets kept outside the main page package so callers can manage them explicitly.
+     */
+    separateAssets: ProcessedAsset[];
+    /**
+     * Browser chunks needed after initial page bootstrap, including eager lazy-entry bundles.
+     */
+    dynamicChunks: ProcessedAsset[];
+}
+/**
+ * Page-scoped browser output planned before final HTML packaging.
+ *
+ * The initial seam keeps the graph payload intentionally small: integrations
+ * return the processed assets that belong to the Page browser graph, while the
+ * surrounding route pipeline remains free to evolve toward richer entry/lazy/
+ * shared chunk structure later.
+ */
+export interface PageBrowserGraphResult {
+    /**
+     * Processed assets owned by the current Page browser graph.
+     */
+    assets: ProcessedAsset[];
+}
+export type OwnershipValidationErrorCode = 'UNKNOWN_INTEGRATION_OWNER' | 'MISSING_COMPONENT_METADATA';
+export interface OwnershipValidationError {
+    code: OwnershipValidationErrorCode;
+    message: string;
+    componentId?: string;
+    componentFile?: string;
+    integrationName?: string;
+}
+export type OwnershipPlanNodeSource = 'route' | 'page' | 'layout' | 'html-template' | 'dependency';
+export interface IntegrationOwnership {
+    integrationName: string;
+    componentId: string;
+    componentFile?: string;
+    isPageEntry: boolean;
+    isForeignToParent: boolean;
+}
+export interface OwnershipPlanNode {
+    id: string;
+    source: OwnershipPlanNodeSource;
+    ownership: IntegrationOwnership;
+    children: OwnershipPlanNode[];
+    declaredDependenciesValid: boolean;
+}
+export interface OwnershipPlan {
+    root: OwnershipPlanNode;
+    rendererNames: string[];
+    foreignEdgeCount: number;
+    hasValidationErrors: boolean;
+    validationErrors: OwnershipValidationError[];
+}
+export type ForeignSubtreeAttachmentPolicy = {
+    kind: 'none';
+} | {
+    kind: 'first-element';
+};
+export interface ForeignSubtreeRenderPayload {
+    html: string;
+    assets: ProcessedAsset[];
+    rootTag?: string;
+    rootAttributes?: Record<string, string>;
+    attachmentPolicy: ForeignSubtreeAttachmentPolicy;
+    integrationName: string;
+}
+/**
+ * Shared execution-scoped context threaded through foreign-child 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?: string;
-    integrationContext?: unknown;
+    children?: unknown;
+    integrationContext?: TIntegrationContext;
 }
 export interface ComponentRenderResult {
     html: string;
@@ -673,7 +829,7 @@ export interface RenderContext {
      * @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<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
@@ -857,6 +1013,15 @@ export interface ApiHandlerContext<TRequest extends Request = Request, TServer =
      */
     headers?: unknown;
 }
+/**
+ * Context available to file-route page middleware.
+ *
+ * Page middleware can mutate locals, short-circuit the request, and use the
+ * response helpers, but final document rendering stays owned by the page route
+ * execution path.
+ */
+export interface FileRouteMiddlewareContext<TRequest extends Request = Request, TServer = any> extends Omit<ApiHandlerContext<TRequest, TServer>, 'render' | 'renderPartial'> {
+}
 /**
  * Next function for middleware chain.
  * Call to continue to the next middleware or final handler.
@@ -892,6 +1057,10 @@ export type MiddlewareNext = () => Promise<Response>;
  * ```
  */
 export type Middleware<TRequest extends Request = Request, TServer = any, TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>> = (context: TContext, next: MiddlewareNext) => Promise<Response> | Response;
+/**
+ * Middleware contract for file-based page routes.
+ */
+export type FileRouteMiddleware<TRequest extends Request = Request, TServer = any, TContext extends FileRouteMiddlewareContext<TRequest, TServer> = FileRouteMiddlewareContext<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.

package/src/utils/html-escaping.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Escapes a string for safe use inside a double-quoted HTML attribute value.
+ *
+ * @param value Raw attribute value.
+ * @returns Escaped attribute-safe string.
+ */
+export declare function escapeHtmlAttribute(value: string): string;

package/src/utils/html-escaping.js

@@ -0,0 +1,6 @@
+function escapeHtmlAttribute(value) {
+  return value.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+export {
+  escapeHtmlAttribute
+};

package/src/utils/locals-utils.d.ts

@@ -1,4 +1,4 @@
-import type { ApiHandlerContext } from '../public-types.js';
+import type { ApiHandlerContext } from '../types/public-types.js';
 /**
  * Creates a require function for validating and retrieving request locals.
  * Supports both single key access and multiple keys with type safety.

package/src/utils/parse-cli-args.d.ts

@@ -17,8 +17,11 @@ export type ReturnParseCliArgs = {
     hostname?: string;
     reactFastRefresh?: boolean;
 };
+export type ParseCliArgsOptions = {
+    embeddedRuntime?: boolean;
+};
 /**
  * Parses command line arguments for the server.
  * It returns {@link ReturnParseCliArgs}
  */
-export declare function parseCliArgs(): ReturnParseCliArgs;
+export declare function parseCliArgs(options?: ParseCliArgsOptions): ReturnParseCliArgs;

package/src/utils/parse-cli-args.js

@@ -1,8 +1,23 @@
 import { parseArgs } from "node:util";
 import { getRuntimeArgv } from "./runtime.js";
+function getEmbeddedRuntimeCommandOptions() {
+  const isDevelopment = process.env.NODE_ENV === "development";
+  return {
+    preview: false,
+    build: false,
+    start: !isDevelopment,
+    dev: isDevelopment,
+    port: void 0,
+    hostname: void 0,
+    reactFastRefresh: void 0
+  };
+}
 const ECOPAGES_BIN_FILES = ["ecopages.ts", "ecopages.js", "cli.js"];
 const ECOPAGES_AVAILABLE_COMMANDS = ["dev", "build", "start", "preview"];
-function parseCliArgs() {
+function parseCliArgs(options = {}) {
+  if (options.embeddedRuntime || process.env.ECOPAGES_INTERNAL_EMBEDDED_RUNTIME === "true") {
+    return getEmbeddedRuntimeCommandOptions();
+  }
   const runtimeArgv = getRuntimeArgv();
   const { values } = parseArgs({
     args: runtimeArgv,

package/src/utils/resolve-work-dir.d.ts

@@ -0,0 +1,11 @@
+type InternalPathConfig = {
+    rootDir?: string;
+    workDir?: string;
+    absolutePaths?: {
+        workDir?: string;
+        distDir?: string;
+    };
+};
+export declare function resolveInternalWorkDir(appConfig: InternalPathConfig): string;
+export declare function resolveInternalExecutionDir(appConfig: InternalPathConfig): string;
+export {};

package/src/utils/resolve-work-dir.js

@@ -0,0 +1,31 @@
+import path from "node:path";
+import { DEFAULT_ECOPAGES_WORK_DIR } from "../config/constants.js";
+function isInsideNodeModules(directory) {
+  return path.normalize(directory).split(path.sep).includes("node_modules");
+}
+function resolveInternalWorkDir(appConfig) {
+  if (appConfig.absolutePaths?.workDir) {
+    return appConfig.absolutePaths.workDir;
+  }
+  if (appConfig.rootDir) {
+    return path.join(appConfig.rootDir, appConfig.workDir ?? DEFAULT_ECOPAGES_WORK_DIR);
+  }
+  if (appConfig.workDir) {
+    return appConfig.workDir;
+  }
+  return DEFAULT_ECOPAGES_WORK_DIR;
+}
+function resolveInternalExecutionDir(appConfig) {
+  const workDir = resolveInternalWorkDir(appConfig);
+  if (!isInsideNodeModules(workDir)) {
+    return workDir;
+  }
+  if (appConfig.rootDir) {
+    return path.join(appConfig.rootDir, DEFAULT_ECOPAGES_WORK_DIR);
+  }
+  return DEFAULT_ECOPAGES_WORK_DIR;
+}
+export {
+  resolveInternalExecutionDir,
+  resolveInternalWorkDir
+};

package/src/watchers/project-watcher.d.ts

@@ -1,16 +1,16 @@
 import { type FSWatcher } from 'chokidar';
-import type { EcoPagesAppConfig, IHmrManager, IClientBridge } from '../internal-types.js';
+import type { EcoPagesAppConfig, IHmrManager, IClientBridge } from '../types/internal-types.js';
 /**
  * Configuration options for the ProjectWatcher
  * @interface ProjectWatcherConfig
  * @property {EcoPagesAppConfig} config - The application configuration
- * @property {() => void} refreshRouterRoutesCallback - Callback to refresh router routes
+ * @property {() => Promise<void>} refreshRouterRoutesCallback - Callback to refresh router routes
  * @property {IHmrManager} hmrManager - The HMR manager instance
  * @property {ClientBridge} bridge - The client bridge instance
  */
 export interface ProjectWatcherConfig {
     config: EcoPagesAppConfig;
-    refreshRouterRoutesCallback: () => void;
+    refreshRouterRoutesCallback: () => Promise<void>;
     hmrManager: IHmrManager;
     bridge: IClientBridge;
 }
@@ -42,8 +42,10 @@ export declare class ProjectWatcher {
     private refreshRouterRoutesCallback;
     private hmrManager;
     private bridge;
+    private readonly invalidationService;
     private watcher;
     private lastHandledChange;
+    private changeQueue;
     constructor({ config, refreshRouterRoutesCallback, hmrManager, bridge }: ProjectWatcherConfig);
     /**
      * Uncaches modules in the source directory to ensure fresh imports.
@@ -51,24 +53,45 @@ export declare class ProjectWatcher {
      * @private
      */
     private uncacheModules;
+    private isRouteSourceFile;
+    private isIncludeSourceFile;
     /**
      * Handles public directory file changes by copying only the changed file.
      * @param filePath - Absolute path of the changed file
      */
     private handlePublicDirFileChange;
+    /**
+     * Serializes file change handling so that concurrent chokidar events are
+     * processed one at a time, preventing overlapping builds and race conditions.
+     */
+    private enqueueChange;
     /**
      * Handles file changes by uncaching modules, refreshing routes, and delegating appropriately.
-     * Follows 4-rule priority:
-     * 0. Public directory match? → copy file and reload
-     * 1. additionalWatchPaths match? → reload
-     * 2. Processor extension match? → processor handles (skip HMR)
-     * 3. Otherwise → HMR strategies
+     * Follows 5-rule priority:
+     * 0. Public directory match? -> copy file and reload
+     * 1. additionalWatchPaths match? -> reload
+     * 2. Include template source? -> reload after processor notifications
+     * 3. Processor-owned asset? -> processor already handled it via notification, skip HMR
+     * 4. Otherwise -> HMR strategies
+     *
+     * Processors that watch a file extension as a dependency (e.g. PostCSS watching
+     * .tsx for Tailwind class scanning) are always notified first, but do not
+     * prevent the file from flowing through the normal HMR strategy pipeline.
      *
      * Duplicate identical watcher events for the same file are coalesced within a
      * short window before any of the priority rules run.
      * @param rawPath - Path of the changed file
+     * @param event - The type of file system event
      */
     private handleFileChange;
+    /**
+     * Notifies all processors whose watch config matches the given file extension.
+     * This is called before checking processor ownership so that dependency-only
+     * processors (e.g. PostCSS watching .tsx for class scanning) receive their
+     * notifications regardless of whether they own the file.
+     */
+    private notifyProcessors;
+    private getProcessorHandler;
     /**
      * Checks if a file is in the public directory.
      */
@@ -77,14 +100,10 @@ export declare class ProjectWatcher {
      * Checks if file path matches any additionalWatchPaths patterns.
      */
     private matchesAdditionalWatchPaths;
-    /**
-     * Checks whether a file is watched by any processor, even if that processor
-     * does not own the file as a primary asset.
-     */
-    private isWatchedByProcessor;
     /**
      * Checks if a file is handled by a processor.
-     * Processors that declare extensions own those file types.
+     * Processors that declare asset capabilities own those file types.
+     * Processors without capabilities fall back to checking watch extensions.
      */
     private isHandledByProcessor;
     /**
@@ -93,30 +112,22 @@ export declare class ProjectWatcher {
      *
      * @param {string} path - Path of the changed directory
      */
-    triggerRouterRefresh(path: string): void;
+    triggerRouterRefresh(changedPath: string): Promise<void>;
     /**
      * Handles and logs errors that occur during file watching.
      *
      * @param {unknown} error - The error to handle
      */
     handleError(error: unknown): void;
-    /**
-     * Processes file changes for specific file extensions.
-     * Used by processors to handle their specific file types.
-     *
-     * @private
-     * @param {string} path - Path of the changed file
-     * @param {string[]} extensions - File extensions to process
-     * @param {(ctx: ProcessorWatchContext) => void} handler - Handler function for the file change
-     */
-    private shouldProcess;
     /**
      * Creates and configures the file system watcher.
      * This sets up:
-     * 1. Processor-specific file watching
-     * 2. Page file watching
-     * 3. Directory watching
-     * 4. Error handling
+     * 1. Page file watching
+     * 2. Directory watching
+     * 3. Error handling
+     *
+     * Processor notifications are dispatched inside handleFileChange, ensuring
+     * a single unified event pipeline with no parallel chokidar bindings.
      *
      * Uses chokidar's built-in debouncing through `awaitWriteFinish` to handle
      * rapid file changes efficiently.