@ecopages/core 0.2.0-beta.2 → 0.2.0-beta.21

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

@@ -1,7 +1,6 @@
 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 { ForeignChildRuntime } from '../route-renderer/orchestration/component-render-context.js';
 import type { EcoPageComponent } from '../eco/eco.types.js';
 import type { EcoPagesAppConfig } from './internal-types.js';
@@ -14,6 +13,82 @@ import type { EntrypointDependencyGraph } from '../services/runtime-state/entryp
 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';
+/**
+ * Runtime-agnostic incoming WebSocket frame.
+ *
+ * Both Bun and Node `ws` deliver text and binary frames; this discriminated
+ * union lets handlers deal with both without runtime-specific casts.
+ */
+export type IncomingWebSocketMessage = {
+    readonly kind: 'text';
+    readonly text: string;
+} | {
+    readonly kind: 'binary';
+    readonly data: Uint8Array;
+};
+/**
+ * Runtime-agnostic outgoing WebSocket payload.
+ *
+ * Strings are sent as text frames. Anything binary-shaped is sent as binary
+ * frames. `Blob` is included for cross-runtime parity and is normalized to a
+ * binary frame by each adapter.
+ */
+export type OutgoingWebSocketMessage = string | Uint8Array | ArrayBuffer | ArrayBufferView | Blob;
+/**
+ * Close event delivered to `onClose` after a connection terminates.
+ */
+export interface WebSocketCloseInfo {
+    readonly code: number;
+    readonly reason: string;
+    readonly wasClean: boolean;
+}
+/**
+ * Input passed to a WebSocket handler's `context()` factory.
+ *
+ * Adapters call `context()` exactly once per accepted upgrade. The returned
+ * value becomes `socket.context` and is shared by all lifecycle hooks.
+ */
+export interface WebSocketContextFactoryInput<TParams extends Record<string, string> = Record<string, string>> {
+    readonly request: Request;
+    readonly kind: string;
+    readonly params: TParams;
+    readonly search: Readonly<Record<string, string>>;
+    readonly locals?: RequestLocals;
+}
+/**
+ * Runtime-agnostic WebSocket socket view exposed to handlers.
+ *
+ * Framework-owned fields:
+ * - `kind`: the registered route pattern (e.g. '/ws/chat/:roomId')
+ * - `params`: dynamic segments captured at match time
+ * - `search`: query string, always string-typed
+ *
+ * App-owned field:
+ * - `context`: returned by the handler's `context()` factory
+ */
+export interface EcopagesSocket<TContext = unknown, TParams extends Record<string, string> = Record<string, string>> {
+    readonly kind: string;
+    readonly params: TParams;
+    readonly search: Readonly<Record<string, string>>;
+    readonly context: TContext;
+    send(message: OutgoingWebSocketMessage): void;
+    sendStream(stream: ReadableStream<Uint8Array>): Promise<void>;
+    close(code?: number, reason?: string): void;
+}
+/**
+ * Connection-lifecycle handler object.
+ *
+ * All hooks are optional. `context()` is the one-time initializer that
+ * produces the per-connection state shared by the lifecycle hooks. Returning
+ * a rejected promise from `context()` aborts the upgrade.
+ */
+export interface EcopagesWebSocketHandler<TContext = unknown, TParams extends Record<string, string> = Record<string, string>> {
+    context?(input: WebSocketContextFactoryInput<TParams>): TContext | Promise<TContext>;
+    onConnect?(socket: EcopagesSocket<TContext, TParams>): void | Promise<void>;
+    onMessage?(socket: EcopagesSocket<TContext, TParams>, message: IncomingWebSocketMessage): void | Promise<void>;
+    onClose?(socket: EcopagesSocket<TContext, TParams>, event: WebSocketCloseInfo): void | Promise<void>;
+    onError?(socket: EcopagesSocket<TContext, TParams>, error: unknown): void | Promise<void>;
+}
 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;
@@ -99,10 +174,6 @@ export interface DefaultHmrContext {
      * Directory where HMR bundles are written.
      */
     getDistDir(): string;
-    /**
-     * Build plugins to use during bundling.
-     */
-    getPlugins(): EcoBuildPlugin[];
     /**
      * Absolute path to the source directory.
      */
@@ -167,6 +238,14 @@ export interface IClientBridge {
     error(message: string): void;
     subscriberCount: number;
 }
+/**
+ * Verified HMR entrypoint artifact produced by registration.
+ */
+export interface ResolvedHmrEntrypoint {
+    sourcePath: string;
+    outputPath: string;
+    outputUrl: string;
+}
 /**
  * Interface for the HMR Manager.
  * Used by integration plugins to register entrypoints and strategies.
@@ -188,19 +267,19 @@ export interface IHmrManager {
      * framework integration. Unlike `registerEntrypoint()`, it may use the generic
      * script bundling path.
      */
-    registerScriptEntrypoint(entrypointPath: string): Promise<string>;
+    registerScriptEntrypoint(entrypointPath: string): Promise<ResolvedHmrEntrypoint>;
     /**
      * 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;
+    /**
+     * Stops active HMR watchers and releases dev-time resources.
+     */
+    stop(): void;
     /**
      * Returns whether HMR is enabled.
      */
@@ -213,6 +292,10 @@ export interface IHmrManager {
      * Gets the output URL for a registered entrypoint.
      */
     getOutputUrl(entrypointPath: string): string | undefined;
+    /**
+     * Returns an existing emitted HMR script artifact without registering it.
+     */
+    getResolvedScriptOutput?(entrypointPath: string): ResolvedHmrEntrypoint | undefined;
     /**
      * Gets the map of watched files.
      */
@@ -221,10 +304,6 @@ export interface IHmrManager {
      * Gets the HMR dist directory.
      */
     getDistDir(): string;
-    /**
-     * Gets the build plugins.
-     */
-    getPlugins(): EcoBuildPlugin[];
     /**
      * Gets the default HMR context.
      */
@@ -247,8 +326,21 @@ export type EcoComponentDependencies = {
      * to express explicit module imports for client bundles.
      */
     modules?: string[];
-    components?: EcoComponent[];
+    /**
+     * Child components whose assets and foreign-child graph are collected transitively.
+     * Each entry must be an `eco.component()`, `eco.layout()`, or `eco.html()` result
+     * with plugin-injected `config.__eco` metadata.
+     */
+    components?: EcoDeclaredComponent[];
 };
+/**
+ * Component returned from `eco.component()`, `eco.layout()`, or `eco.html()`.
+ *
+ * @remarks
+ * Used for `dependencies.components` and eco factory return types. Plugin-injected
+ * `config.__eco` is enforced at runtime via `isEcoDeclaredComponent()`, not by this alias.
+ */
+export type EcoDeclaredComponent<P = any, R = any> = EcoComponent<P, R>;
 export type EcoPagesElement = string | Promise<string>;
 /**
  * Serializable child payloads accepted by cross-integration deferred rendering.
@@ -314,11 +406,13 @@ export type EcoComponentConfig = {
      * );
      *
      * // Page using the layout
-     * const MyPage = () => <h1>Hello</h1>;
-     * MyPage.config = { layout: Layout };
+     * const MyPage = eco.page({ layout: Layout, render: () => <h1>Hello</h1> });
      * ```
      */
-    layout?: EcoPageLayoutComponent<any>;
+    /** Normalized outer→inner layout stack from `eco.page({ layout: [...] })`. */
+    layouts?: EcoDeclaredComponent[];
+    /** Layout entries retained for per-tier prop factories. */
+    layoutEntries?: EcoPageLayoutEntry[];
     dependencies?: EcoComponentDependencies;
     /**
      * Internal: Resolved lazy scripts grouped by trigger.
@@ -442,6 +536,36 @@ export interface HtmlTemplateProps<T = EcoPagesElement> extends PageHeadProps<T>
     headContent?: T;
     pageProps: Record<string, unknown>;
 }
+/**
+ * Request-scoped context available to layout prop factories on `eco.page`.
+ */
+export type LayoutPropsContext = {
+    params?: Record<string, string>;
+    query?: Record<string, string>;
+    locals?: RequestLocals;
+};
+/**
+ * One layout tier in a page layout stack (outer→inner).
+ */
+export type EcoPageLayoutEntry<E = EcoPagesElement> = {
+    component: EcoDeclaredComponent<any, E>;
+    props?: (context: LayoutPropsContext) => Record<string, unknown>;
+};
+/**
+ * Layout declaration accepted by `eco.page()`.
+ *
+ * @remarks
+ * Array order is outer→inner, matching Next.js App Router segment nesting.
+ */
+export type EcoPageLayoutSpec<E = EcoPagesElement> = EcoDeclaredComponent<any, E> | EcoPageLayoutEntry<E>;
+/**
+ * One or more layout tiers for `eco.page({ layout })`.
+ *
+ * @remarks
+ * When an array, order is **outer → inner** (outermost layout wraps all inner tiers).
+ * Normalized at factory time to `config.layouts` and `config.layoutEntries`.
+ */
+export type EcoPageLayouts<E = EcoPagesElement> = EcoPageLayoutSpec<E> | EcoPageLayoutSpec<E>[];
 /**
  * Layout components accepted by pages.
  *
@@ -659,7 +783,9 @@ export type IntegrationRendererRenderOptions<C = EcoPagesElement> = RouteRendere
     metadata: PageMetadataProps;
     HtmlTemplate: EcoHtmlComponent<C>;
     Page: EcoComponent<PageProps, C>;
+    Layouts?: EcoDeclaredComponent[];
     Layout?: EcoPageLayoutComponent<any>;
+    layoutEntries?: EcoPageLayoutEntry[];
     dependencies?: EcoComponentDependencies;
     resolvedDependencies: ProcessedAsset[];
     pagePackage?: PagePackageResult;
@@ -667,7 +793,6 @@ export type IntegrationRendererRenderOptions<C = EcoPagesElement> = RouteRendere
     pageProps?: Record<string, unknown>;
     cacheStrategy?: CacheStrategy;
     pageLocals?: RequestLocals;
-    ownershipPlan?: OwnershipPlan;
 };
 /**
  * Structured page asset package produced after dependency resolution.
@@ -746,27 +871,6 @@ export interface OwnershipValidationError {
     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';
 } | {

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

@@ -13,6 +13,8 @@ export type ReturnParseCliArgs = {
     build: boolean;
     start: boolean;
     dev: boolean;
+    force: boolean;
+    serveOnly: boolean;
     port?: number;
     hostname?: string;
     reactFastRefresh?: boolean;

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

@@ -7,6 +7,8 @@ function getEmbeddedRuntimeCommandOptions() {
     build: false,
     start: !isDevelopment,
     dev: isDevelopment,
+    force: false,
+    serveOnly: false,
     port: void 0,
     hostname: void 0,
     reactFastRefresh: void 0
@@ -25,6 +27,8 @@ function parseCliArgs(options = {}) {
       dev: { type: "boolean" },
       preview: { type: "boolean" },
       build: { type: "boolean" },
+      force: { type: "boolean" },
+      "serve-only": { type: "boolean" },
       port: { type: "string" },
       hostname: { type: "string" },
       "react-fast-refresh": { type: "boolean" }
@@ -48,6 +52,8 @@ function parseCliArgs(options = {}) {
     build: isBuildCommand,
     start: isStartCommand,
     dev: isDevCommand,
+    force: !!values.force,
+    serveOnly: !!values["serve-only"] || process.env.ECOPAGES_PREVIEW_SERVE_ONLY === "true",
     port: values.port ? Number(values.port) : void 0,
     hostname: values.hostname,
     reactFastRefresh: values["react-fast-refresh"]

package/src/utils/server-utils.module.d.ts

@@ -1,3 +1,4 @@
+import { hasKnownStaticExtension } from './static-file-extensions.js';
 /**
  * Get the content type of a file based on its extension.
  * @param file - The file name.
@@ -9,11 +10,11 @@ export declare const getContentType: (file: string) => string;
  * @param file - The file name or path.
  * @returns true if the extension is recognized.
  */
-export declare const hasKnownExtension: (file: string) => boolean;
+export { hasKnownStaticExtension } from './static-file-extensions.js';
 /**
  * A module for server utilities.
  */
 export declare const ServerUtils: {
     getContentType: (file: string) => string;
-    hasKnownExtension: (file: string) => boolean;
+    hasKnownStaticExtension: typeof hasKnownStaticExtension;
 };

package/src/utils/server-utils.module.js

@@ -1,3 +1,4 @@
+import { hasKnownStaticExtension } from "./static-file-extensions.js";
 const ContentTypeMap = /* @__PURE__ */ new Map([
   ["jpg", "image/jpeg"],
   ["jpeg", "image/jpeg"],
@@ -17,6 +18,7 @@ const ContentTypeMap = /* @__PURE__ */ new Map([
   ["ogv", "video/ogg"],
   ["mov", "video/quicktime"],
   ["txt", "text/plain"],
+  ["md", "text/markdown"],
   ["html", "text/html"],
   ["css", "text/css"],
   ["js", "text/javascript"],
@@ -41,16 +43,13 @@ const getContentType = (file) => {
   const extension = file.split(".").pop() || "txt";
   return ContentTypeMap.get(extension) || "text/plain";
 };
-const hasKnownExtension = (file) => {
-  const extension = file.split(".").pop();
-  return extension !== void 0 && ContentTypeMap.has(extension);
-};
+import { hasKnownStaticExtension as hasKnownStaticExtension2 } from "./static-file-extensions.js";
 const ServerUtils = {
   getContentType,
-  hasKnownExtension
+  hasKnownStaticExtension
 };
 export {
   ServerUtils,
   getContentType,
-  hasKnownExtension
+  hasKnownStaticExtension2 as hasKnownStaticExtension
 };

package/src/utils/static-file-extensions.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Known static asset extensions served directly from disk.
+ *
+ * @remarks
+ * Keep this list aligned with server static-file handling and client routers
+ * that must bypass SPA navigation for same-origin asset links.
+ */
+export declare const STATIC_FILE_EXTENSIONS: Set<string>;
+/**
+ * Returns whether a path or filename ends with a known static asset extension.
+ */
+export declare function hasKnownStaticExtension(fileOrPath: string): boolean;

package/src/utils/static-file-extensions.js

@@ -0,0 +1,48 @@
+const STATIC_FILE_EXTENSIONS = /* @__PURE__ */ new Set([
+  "jpg",
+  "jpeg",
+  "png",
+  "gif",
+  "bmp",
+  "svg",
+  "tiff",
+  "webp",
+  "avif",
+  "ico",
+  "mp3",
+  "ogg",
+  "wav",
+  "mp4",
+  "webm",
+  "ogv",
+  "mov",
+  "txt",
+  "md",
+  "html",
+  "css",
+  "js",
+  "mjs",
+  "json",
+  "map",
+  "xml",
+  "webmanifest",
+  "wasm",
+  "csv",
+  "ttf",
+  "woff",
+  "woff2",
+  "otf",
+  "eot",
+  "gz",
+  "zip",
+  "pdf",
+  "doc"
+]);
+function hasKnownStaticExtension(fileOrPath) {
+  const extension = fileOrPath.split(".").pop();
+  return extension !== void 0 && STATIC_FILE_EXTENSIONS.has(extension);
+}
+export {
+  STATIC_FILE_EXTENSIONS,
+  hasKnownStaticExtension
+};

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

@@ -0,0 +1,11 @@
+export type ProjectWatcherIgnorePaths = {
+    workDir: string;
+    distDir: string;
+};
+/**
+ * @remarks
+ * chokidar v4+ no longer treats glob strings in `ignored` as patterns. A path
+ * predicate keeps node_modules, VCS metadata, and scoped artifact dirs out of
+ * the watch tree without descending into symlinked monorepo node_modules.
+ */
+export declare function createProjectWatcherIgnorePredicate(absolutePaths: ProjectWatcherIgnorePaths): (watchedPath: string) => boolean;

package/src/watchers/project-watcher-ignore.js

@@ -0,0 +1,16 @@
+import path from "node:path";
+function createProjectWatcherIgnorePredicate(absolutePaths) {
+  const ignoredPrefixes = [absolutePaths.workDir, absolutePaths.distDir];
+  return (watchedPath) => {
+    const segments = watchedPath.split(path.sep);
+    if (segments.includes("node_modules") || segments.includes(".git")) {
+      return true;
+    }
+    return ignoredPrefixes.some(
+      (prefix) => watchedPath === prefix || watchedPath.startsWith(`${prefix}${path.sep}`)
+    );
+  };
+}
+export {
+  createProjectWatcherIgnorePredicate
+};

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

@@ -13,6 +13,10 @@ export interface ProjectWatcherConfig {
     refreshRouterRoutesCallback: () => Promise<void>;
     hmrManager: IHmrManager;
     bridge: IClientBridge;
+    /** When true, the host dev server owns browser dev-client bootstrap. */
+    hostOwnsDevClient?: boolean;
+    /** Delay before a change event is processed; 0 disables debouncing. */
+    changeDebounceMs?: number;
 }
 /**
  * ProjectWatcher handles file system changes for hot module replacement (HMR).
@@ -42,11 +46,14 @@ export declare class ProjectWatcher {
     private refreshRouterRoutesCallback;
     private hmrManager;
     private bridge;
+    private readonly hostOwnsDevClient;
     private readonly invalidationService;
+    private readonly changeDebounceMs;
     private watcher;
-    private lastHandledChange;
+    private closed;
+    private pendingChangeEvents;
     private changeQueue;
-    constructor({ config, refreshRouterRoutesCallback, hmrManager, bridge }: ProjectWatcherConfig);
+    constructor({ config, refreshRouterRoutesCallback, hmrManager, bridge, hostOwnsDevClient, changeDebounceMs, }: ProjectWatcherConfig);
     /**
      * Uncaches modules in the source directory to ensure fresh imports.
      * This is necessary for hot module replacement to work correctly.
@@ -55,6 +62,7 @@ export declare class ProjectWatcher {
     private uncacheModules;
     private isRouteSourceFile;
     private isIncludeSourceFile;
+    private requestBrowserReload;
     /**
      * Handles public directory file changes by copying only the changed file.
      * @param filePath - Absolute path of the changed file
@@ -70,7 +78,7 @@ export declare class ProjectWatcher {
      * Follows 5-rule priority:
      * 0. Public directory match? -> copy file and reload
      * 1. additionalWatchPaths match? -> reload
-     * 2. Include template source? -> reload after processor notifications
+     * 2. Include template source? -> current-page refresh via HMR after processor notifications are deferred
      * 3. Processor-owned asset? -> processor already handled it via notification, skip HMR
      * 4. Otherwise -> HMR strategies
      *
@@ -84,6 +92,13 @@ export declare class ProjectWatcher {
      * @param event - The type of file system event
      */
     private handleFileChange;
+    private processFileChange;
+    /**
+     * Re-imports server modules before HMR broadcast so reload/refetch does not
+     * race stale in-memory imports or custom-element registry state.
+     */
+    private prewarmBeforeHmr;
+    private prewarmServerModuleImports;
     /**
      * Notifies all processors whose watch config matches the given file extension.
      * This is called before checking processor ownership so that dependency-only
@@ -133,4 +148,12 @@ export declare class ProjectWatcher {
      * rapid file changes efficiently.
      */
     createWatcherSubscription(): Promise<FSWatcher>;
+    /**
+     * Closes the active filesystem watcher subscription.
+     *
+     * @remarks
+     * Safe to call multiple times. Used when tearing down dev servers in tests
+     * and other short-lived Ecopages runtimes.
+     */
+    close(): Promise<void>;
 }