@ecopages/core 0.2.0-beta.4 → 0.2.0-beta.41

package/src/utils/runtime.js

@@ -1,40 +1,31 @@
-import { createHash } from "node:crypto";
-const RUNTIME_ERRORS = {
-  BUN_RUNTIME_REQUIRED: "Bun runtime is required"
+import { createHash } from 'node:crypto';
+export const RUNTIME_ERRORS = {
+    BUN_RUNTIME_REQUIRED: 'Bun runtime is required',
 };
-function getBunRuntime() {
-  return globalThis.Bun;
+export function getBunRuntime() {
+    return globalThis.Bun;
 }
-function getRequiredBunRuntime() {
-  const bun = getBunRuntime();
-  if (!bun) {
-    throw new Error(RUNTIME_ERRORS.BUN_RUNTIME_REQUIRED);
-  }
-  return bun;
+export function getRequiredBunRuntime() {
+    const bun = getBunRuntime();
+    if (!bun) {
+        throw new Error(RUNTIME_ERRORS.BUN_RUNTIME_REQUIRED);
+    }
+    return bun;
 }
-function getRuntimeArgv() {
-  return process.argv;
+export function getRuntimeArgv() {
+    return process.argv;
 }
-function isDevelopmentRuntime() {
-  return process.env.NODE_ENV === "development";
+export function isDevelopmentRuntime() {
+    return process.env.NODE_ENV === 'development';
 }
-function isProductionRuntime() {
-  return process.env.NODE_ENV === "production";
+export function isProductionRuntime() {
+    return process.env.NODE_ENV === 'production';
 }
-function runtimeHash(content) {
-  const bun = getBunRuntime();
-  if (bun) {
-    return bun.hash(content);
-  }
-  const hex = createHash("sha256").update(content).digest("hex").slice(0, 16);
-  return BigInt(`0x${hex}`);
+export function runtimeHash(content) {
+    const bun = getBunRuntime();
+    if (bun) {
+        return bun.hash(content);
+    }
+    const hex = createHash('sha256').update(content).digest('hex').slice(0, 16);
+    return BigInt(`0x${hex}`);
 }
-export {
-  RUNTIME_ERRORS,
-  getBunRuntime,
-  getRequiredBunRuntime,
-  getRuntimeArgv,
-  isDevelopmentRuntime,
-  isProductionRuntime,
-  runtimeHash
-};

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,56 +1,63 @@
-const ContentTypeMap = /* @__PURE__ */ new Map([
-  ["jpg", "image/jpeg"],
-  ["jpeg", "image/jpeg"],
-  ["png", "image/png"],
-  ["gif", "image/gif"],
-  ["bmp", "image/bmp"],
-  ["svg", "image/svg+xml"],
-  ["tiff", "image/tiff"],
-  ["webp", "image/webp"],
-  ["avif", "image/avif"],
-  ["ico", "image/x-icon"],
-  ["mp3", "audio/mpeg"],
-  ["ogg", "audio/ogg"],
-  ["wav", "audio/wav"],
-  ["mp4", "video/mp4"],
-  ["webm", "video/webm"],
-  ["ogv", "video/ogg"],
-  ["mov", "video/quicktime"],
-  ["txt", "text/plain"],
-  ["html", "text/html"],
-  ["css", "text/css"],
-  ["js", "text/javascript"],
-  ["mjs", "text/javascript"],
-  ["json", "application/json"],
-  ["map", "application/json"],
-  ["xml", "application/xml"],
-  ["webmanifest", "application/manifest+json"],
-  ["wasm", "application/wasm"],
-  ["csv", "text/csv"],
-  ["ttf", "font/ttf"],
-  ["woff", "font/woff"],
-  ["woff2", "font/woff2"],
-  ["otf", "font/otf"],
-  ["eot", "application/vnd.ms-fontobject"],
-  ["gz", "application/x-gzip"],
-  ["zip", "application/zip"],
-  ["pdf", "application/pdf"],
-  ["doc", "application/msword"]
+import { hasKnownStaticExtension } from './static-file-extensions.js';
+const ContentTypeMap = new Map([
+    ['jpg', 'image/jpeg'],
+    ['jpeg', 'image/jpeg'],
+    ['png', 'image/png'],
+    ['gif', 'image/gif'],
+    ['bmp', 'image/bmp'],
+    ['svg', 'image/svg+xml'],
+    ['tiff', 'image/tiff'],
+    ['webp', 'image/webp'],
+    ['avif', 'image/avif'],
+    ['ico', 'image/x-icon'],
+    ['mp3', 'audio/mpeg'],
+    ['ogg', 'audio/ogg'],
+    ['wav', 'audio/wav'],
+    ['mp4', 'video/mp4'],
+    ['webm', 'video/webm'],
+    ['ogv', 'video/ogg'],
+    ['mov', 'video/quicktime'],
+    ['txt', 'text/plain'],
+    ['md', 'text/markdown'],
+    ['html', 'text/html'],
+    ['css', 'text/css'],
+    ['js', 'text/javascript'],
+    ['mjs', 'text/javascript'],
+    ['json', 'application/json'],
+    ['map', 'application/json'],
+    ['xml', 'application/xml'],
+    ['webmanifest', 'application/manifest+json'],
+    ['wasm', 'application/wasm'],
+    ['csv', 'text/csv'],
+    ['ttf', 'font/ttf'],
+    ['woff', 'font/woff'],
+    ['woff2', 'font/woff2'],
+    ['otf', 'font/otf'],
+    ['eot', 'application/vnd.ms-fontobject'],
+    ['gz', 'application/x-gzip'],
+    ['zip', 'application/zip'],
+    ['pdf', 'application/pdf'],
+    ['doc', 'application/msword'],
 ]);
-const getContentType = (file) => {
-  const extension = file.split(".").pop() || "txt";
-  return ContentTypeMap.get(extension) || "text/plain";
+/**
+ * Get the content type of a file based on its extension.
+ * @param file - The file name.
+ * @returns The content type.
+ */
+export 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);
-};
-const ServerUtils = {
-  getContentType,
-  hasKnownExtension
-};
-export {
-  ServerUtils,
-  getContentType,
-  hasKnownExtension
+/**
+ * Check if a file path has a known static file extension.
+ * @param file - The file name or path.
+ * @returns true if the extension is recognized.
+ */
+export { hasKnownStaticExtension } from './static-file-extensions.js';
+/**
+ * A module for server utilities.
+ */
+export const ServerUtils = {
+    getContentType,
+    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,54 @@
+/**
+ * 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 const STATIC_FILE_EXTENSIONS = 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',
+]);
+/**
+ * Returns whether a path or filename ends with a known static asset extension.
+ */
+export function hasKnownStaticExtension(fileOrPath) {
+    const extension = fileOrPath.split('.').pop();
+    return extension !== undefined && STATIC_FILE_EXTENSIONS.has(extension);
+}

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,17 @@
+import path from 'node:path';
+/**
+ * @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 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}`));
+    };
+}

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
@@ -101,9 +116,9 @@ export declare class ProjectWatcher {
      */
     private matchesAdditionalWatchPaths;
     /**
-     * Checks if a file is handled by a processor.
-     * Processors that declare asset capabilities own those file types.
-     * Processors without capabilities fall back to checking watch extensions.
+     * Checks if a file is owned by a processor as an asset input.
+     * Ownership requires declared asset capabilities; watch config only drives
+     * {@link notifyProcessors} notifications.
      */
     private isHandledByProcessor;
     /**
@@ -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>;
 }