@ecopages/core 0.2.0-alpha.9 → 0.2.0-beta.1

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

@@ -1,19 +1,21 @@
 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 { 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 { 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 { HmrStrategy } from '../hmr/hmr-strategy.js';
+import type { BrowserBundleExecutor } from '../services/assets/browser-bundle.service.js';
+import type { AssetDefinition, 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';
-export type { MarkerGraphContext } from './route-renderer/component-graph/marker-graph-resolver.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, };
+import type { EntrypointDependencyGraph } from '../services/runtime-state/entrypoint-dependency-graph.service.js';
+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;
@@ -93,10 +95,6 @@ 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.
      */
@@ -130,7 +128,11 @@ export interface DefaultHmrContext {
     /**
      * Server-side module loader owned by the active app/runtime.
      */
-    importServerModule<T = unknown>(filePath: string): Promise<T>;
+    importServerModule<T = unknown>(filePath: string | URL): Promise<T>;
+    /**
+     * Entrypoint dependency graph for selective HMR invalidation.
+     */
+    getEntrypointDependencyGraph(): EntrypointDependencyGraph;
 }
 /**
  * Represents an event broadcast to connected clients via the ClientBridge.
@@ -187,15 +189,6 @@ export interface IHmrManager {
      * 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.
      */
@@ -224,10 +217,6 @@ export interface IHmrManager {
      * 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.
      */
@@ -261,6 +250,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.
  */
@@ -432,10 +436,10 @@ export interface LayoutProps<T = EcoPagesElement> extends Partial<RequestPageCon
 /**
  * Represents the props for the HTML template of a page.
  */
-export interface HtmlTemplateProps extends PageHeadProps {
-    children: EcoPagesElement;
+export interface HtmlTemplateProps<T = EcoPagesElement> extends PageHeadProps<T> {
+    children: T;
     language?: string;
-    headContent?: EcoPagesElement;
+    headContent?: T;
     pageProps: Record<string, unknown>;
 }
 /**
@@ -658,16 +662,139 @@ export type IntegrationRendererRenderOptions<C = EcoPagesElement> = RouteRendere
     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[];
+    /**
+     * Optional structured Page Browser Graph carried through route preparation.
+     */
+    pageBrowserGraph?: PageBrowserGraphResult;
+    /**
+     * 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.
+ *
+ * This shape keeps page-browser ownership explicit without forcing downstream
+ * HTML packaging to understand how integrations discovered the graph. Entry
+ * assets represent the initial page bootstrap outputs, while chunk assets stay
+ * separate so callers can preserve lazy/shared chunk identity until the point
+ * they intentionally flatten for page packaging.
+ */
+export interface PageBrowserGraphResult {
+    /**
+     * Processed assets needed for the initial page browser bootstrap.
+     */
+    entryAssets: ProcessedAsset[];
+    /**
+     * Processed browser chunks referenced after the initial page bootstrap.
+     */
+    chunkAssets: ProcessedAsset[];
+}
+export type PageBrowserGraphContributionContext = {
+    file: string;
+    pageModule: EcoPageFile;
+};
+export interface PageBrowserGraphContribution {
+    dependencies?: AssetDefinition[];
+    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;
@@ -718,6 +845,24 @@ export interface ResponseOptions {
  * Provides methods to render eco.page views and return formatted responses.
  */
 export interface RenderContext {
+    /**
+     * Import a server-executed module through the active Ecopages module loader.
+     *
+     * This applies the runtime's cache-busting and source-transpilation rules so
+     * request-time lazy imports participate in development invalidation.
+     *
+     * @param filePath - Absolute filesystem path or file URL for the server module
+     */
+    importServerModule<T = unknown>(filePath: string | URL): Promise<T>;
+    /**
+     * Import a server module through the active Ecopages module loader and render
+     * its default-exported eco.page view.
+     *
+     * @param filePath - Absolute filesystem path or file URL for the server module
+     * @param props - Props to pass to the default-exported view
+     * @param options - Optional status code and headers
+     */
+    renderServerModule<P = Record<string, unknown>>(filePath: string | URL, props?: P, options?: RenderOptions): Promise<Response>;
     /**
      * Render an eco.page view with full layout and includes.
      * @param view - The eco.page component to render
@@ -908,6 +1053,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' | 'importServerModule' | 'renderServerModule'> {
+}
 /**
  * Next function for middleware chain.
  * Call to continue to the next middleware or final handler.
@@ -943,6 +1097,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-entry-file.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The default entry file name when no other source provides a value.
+ */
+export declare const DEFAULT_ENTRY_FILE = "app.ts";
+/**
+ * The environment variable used to override the entry file path.
+ */
+export declare const ENTRY_FILE_ENV = "ECOPAGES_ENTRY_FILE";
+/**
+ * Centralized definition of the entry-file CLI argument.
+ *
+ * Exported so callers (CLI, tests, docs) reference a single source of truth
+ * for the flag name, short alias, and type. Keep this in sync with
+ * `resolveEntryFile` below.
+ */
+export declare const entryFileOptions: {
+    readonly 'entry-file': {
+        readonly type: "string";
+        readonly short: "e";
+    };
+};
+/**
+ * The long flag name for the entry file option. Re-exported as a
+ * constant so consumers don't hardcode the string.
+ */
+export declare const ENTRY_FILE_FLAG = "entry-file";
+/**
+ * Resolved sources for the entry file, in precedence order (highest first):
+ *
+ * 1. `entryFile` argument — explicit caller override (e.g. constructor)
+ * 2. `ECOPAGES_ENTRY_FILE` env var — set by the CLI when spawning
+ * 3. `--entry-file` / `-e` CLI flag — read from `process.argv` via `parseArgs`
+ * 4. `app.ts` — the framework default
+ */
+export interface ResolveEntryFileOptions {
+    /** Explicit override (e.g. constructor param or test fixture). */
+    entryFile?: string;
+    /** Environment to read `ECOPAGES_ENTRY_FILE` from. Defaults to `process.env`. */
+    env?: Record<string, string | undefined>;
+    /** Argv to parse. Defaults to `process.argv`. */
+    argv?: string[];
+}
+/**
+ * Resolves the entry file path using standard precedence.
+ *
+ * This is the single source of truth for entry-file resolution across
+ * the CLI, build pipeline, and runtime. Both the CLI layer and the
+ * runtime builders call into this function instead of reimplementing
+ * the precedence chain.
+ *
+ * @example
+ *   resolveEntryFile();                                     // 'app.ts' (or env/argv)
+ *   resolveEntryFile({ entryFile: 'src/server.ts' });       // 'src/server.ts'
+ *   resolveEntryFile({ env: { ECOPAGES_ENTRY_FILE: 'x' }}); // 'x'
+ *   resolveEntryFile({ argv: ['node', '-e', 'flag.ts'] });  // 'flag.ts'
+ */
+export declare function resolveEntryFile({ entryFile, env, argv, }?: ResolveEntryFileOptions): string;
+/**
+ * Parses argv for the entry-file flag using the shared `parseArgs` config.
+ *
+ * Exposed for callers that need the raw flag value without the full
+ * precedence chain (e.g. CLI help text, validation).
+ */
+export declare function readEntryFileFlag(argv?: string[]): string | undefined;
+/**
+ * The subdirectory inside `dist/` where the bundled server entry is placed.
+ */
+export declare const SERVER_BUNDLE_DIR = ".server";
+/**
+ * The filename of the bundled server entry.
+ */
+export declare const SERVER_BUNDLE_FILENAME = "app.mjs";

package/src/utils/resolve-entry-file.js

@@ -0,0 +1,41 @@
+import { parseArgs } from "node:util";
+import { getRuntimeArgv } from "./runtime.js";
+const DEFAULT_ENTRY_FILE = "app.ts";
+const ENTRY_FILE_ENV = "ECOPAGES_ENTRY_FILE";
+const entryFileOptions = {
+  "entry-file": { type: "string", short: "e" }
+};
+const ENTRY_FILE_FLAG = "entry-file";
+function resolveEntryFile({
+  entryFile,
+  env = process.env,
+  argv = getRuntimeArgv()
+} = {}) {
+  if (entryFile && entryFile.length > 0) return entryFile;
+  const fromEnv = env[ENTRY_FILE_ENV];
+  if (fromEnv && fromEnv.length > 0) return fromEnv;
+  const fromFlag = readEntryFileFlag(argv);
+  if (fromFlag) return fromFlag;
+  return DEFAULT_ENTRY_FILE;
+}
+function readEntryFileFlag(argv = getRuntimeArgv()) {
+  const { values } = parseArgs({
+    args: argv.slice(1),
+    options: { ...entryFileOptions },
+    strict: false
+  });
+  const raw = values[ENTRY_FILE_FLAG];
+  return typeof raw === "string" && raw.length > 0 ? raw : void 0;
+}
+const SERVER_BUNDLE_DIR = ".server";
+const SERVER_BUNDLE_FILENAME = "app.mjs";
+export {
+  DEFAULT_ENTRY_FILE,
+  ENTRY_FILE_ENV,
+  ENTRY_FILE_FLAG,
+  SERVER_BUNDLE_DIR,
+  SERVER_BUNDLE_FILENAME,
+  entryFileOptions,
+  readEntryFileFlag,
+  resolveEntryFile
+};

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

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { DEFAULT_ECOPAGES_WORK_DIR } from "../constants.js";
+import { DEFAULT_ECOPAGES_WORK_DIR } from "../config/constants.js";
 function isInsideNodeModules(directory) {
   return path.normalize(directory).split(path.sep).includes("node_modules");
 }

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;
 }
@@ -112,7 +112,7 @@ export declare class ProjectWatcher {
      *
      * @param {string} path - Path of the changed directory
      */
-    triggerRouterRefresh(changedPath: string): void;
+    triggerRouterRefresh(changedPath: string): Promise<void>;
     /**
      * Handles and logs errors that occur during file watching.
      *

package/src/watchers/project-watcher.js

@@ -115,7 +115,7 @@ class ProjectWatcher {
         this.invalidationService.invalidateServerModules([filePath]);
       }
       if (plan.refreshRoutes) {
-        this.refreshRouterRoutesCallback();
+        await this.refreshRouterRoutesCallback();
       }
       if (plan.category === "additional-watch") {
         this.bridge.reload();
@@ -196,11 +196,11 @@ class ProjectWatcher {
    *
    * @param {string} path - Path of the changed directory
    */
-  triggerRouterRefresh(changedPath) {
+  async triggerRouterRefresh(changedPath) {
     const resolvedPath = path.resolve(changedPath);
     const isPageDir = resolvedPath.startsWith(this.appConfig.absolutePaths.pagesDir) && path.extname(resolvedPath) === "";
     if (isPageDir || this.isRouteSourceFile(resolvedPath)) {
-      this.refreshRouterRoutesCallback();
+      await this.refreshRouterRoutesCallback();
     }
   }
   /**
@@ -228,45 +228,39 @@ class ProjectWatcher {
    * rapid file changes efficiently.
    */
   async createWatcherSubscription() {
-    if (!this.watcher) {
-      const processorPaths = [];
-      for (const processor of this.appConfig.processors.values()) {
-        const watchConfig = processor.getWatchConfig();
-        if (!watchConfig) continue;
-        processorPaths.push(...watchConfig.paths);
-      }
-      if (fileSystem.exists(this.appConfig.absolutePaths.includesDir)) {
-        processorPaths.push(this.appConfig.absolutePaths.includesDir);
-      }
-      if (fileSystem.exists(this.appConfig.absolutePaths.srcDir)) {
-        processorPaths.push(this.appConfig.absolutePaths.srcDir);
-      }
-      if (fileSystem.exists(this.appConfig.absolutePaths.pagesDir)) {
-        processorPaths.push(this.appConfig.absolutePaths.pagesDir);
-      }
-      if (fileSystem.exists(this.appConfig.absolutePaths.publicDir)) {
-        processorPaths.push(this.appConfig.absolutePaths.publicDir);
-      }
-      if (this.appConfig.additionalWatchPaths.length) {
-        processorPaths.push(...this.appConfig.additionalWatchPaths);
-      }
-      this.watcher = chokidar.watch(processorPaths, {
-        ignoreInitial: true,
-        ignorePermissionErrors: true,
-        awaitWriteFinish: {
-          stabilityThreshold: 50,
-          pollInterval: 50
-        }
-      });
+    if (this.watcher) {
+      return this.watcher;
+    }
+    const processorPaths = [];
+    for (const processor of this.appConfig.processors.values()) {
+      const watchConfig = processor.getWatchConfig();
+      if (!watchConfig) continue;
+      processorPaths.push(...watchConfig.paths);
+    }
+    if (fileSystem.exists(this.appConfig.absolutePaths.includesDir)) {
+      processorPaths.push(this.appConfig.absolutePaths.includesDir);
+    }
+    if (fileSystem.exists(this.appConfig.absolutePaths.srcDir)) {
+      processorPaths.push(this.appConfig.absolutePaths.srcDir);
     }
-    this.watcher.add(this.appConfig.absolutePaths.srcDir);
-    this.watcher.on("change", (p) => this.enqueueChange(() => this.handleFileChange(p, "change"))).on("add", (p) => {
-      this.enqueueChange(() => this.handleFileChange(p, "add"));
-      this.triggerRouterRefresh(p);
-    }).on("addDir", (p) => this.triggerRouterRefresh(p)).on("unlink", (p) => {
-      this.enqueueChange(() => this.handleFileChange(p, "unlink"));
-      this.triggerRouterRefresh(p);
-    }).on("unlinkDir", (p) => this.triggerRouterRefresh(p)).on("error", (error) => this.handleError(error));
+    if (fileSystem.exists(this.appConfig.absolutePaths.pagesDir)) {
+      processorPaths.push(this.appConfig.absolutePaths.pagesDir);
+    }
+    if (fileSystem.exists(this.appConfig.absolutePaths.publicDir)) {
+      processorPaths.push(this.appConfig.absolutePaths.publicDir);
+    }
+    if (this.appConfig.additionalWatchPaths.length) {
+      processorPaths.push(...this.appConfig.additionalWatchPaths);
+    }
+    this.watcher = chokidar.watch(processorPaths, {
+      ignoreInitial: true,
+      ignorePermissionErrors: true,
+      awaitWriteFinish: {
+        stabilityThreshold: 50,
+        pollInterval: 50
+      }
+    });
+    this.watcher.on("change", (p) => this.enqueueChange(() => this.handleFileChange(p, "change"))).on("add", (p) => this.enqueueChange(() => this.handleFileChange(p, "add"))).on("addDir", (p) => this.enqueueChange(() => this.triggerRouterRefresh(p))).on("unlink", (p) => this.enqueueChange(() => this.handleFileChange(p, "unlink"))).on("unlinkDir", (p) => this.enqueueChange(() => this.triggerRouterRefresh(p))).on("error", (error) => this.handleError(error));
     for (const processor of this.appConfig.processors.values()) {
       const watchConfig = processor.getWatchConfig();
       if (watchConfig?.onError) {

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

@@ -1,4 +1,4 @@
-import type { IHmrManager } from '../internal-types';
-import type { ClientBridge } from '../adapters/bun/client-bridge';
+import type { IHmrManager } from '../types/internal-types.js';
+import type { ClientBridge } from '../adapters/bun/client-bridge.js';
 export declare const createMockHmrManager: () => IHmrManager;
 export declare const createMockBridge: () => ClientBridge;