@ecopages/core 0.2.0-beta.31 → 0.2.0-beta.33

package/src/config/constants.js

@@ -1,26 +1,46 @@
-const STATUS_MESSAGE = {
-  404: "404 Not Found",
-  500: "Internal Server Error"
+/**
+ * This file contains constants used throughout the project.
+ * @module constants
+ **/
+/**
+ * Collection of status messages used in the application.
+ */
+export const STATUS_MESSAGE = {
+    404: '404 Not Found',
+    500: 'Internal Server Error',
 };
-const IS_BUN = typeof Bun !== "undefined";
-const RESOLVED_ASSETS_DIR = "assets";
-const RESOLVED_ASSETS_VENDORS_DIR = `${RESOLVED_ASSETS_DIR}/vendors`;
-const GENERATED_BASE_PATHS = {
-  types: "node_modules/@types",
-  cache: "cache"
-};
-const DEFAULT_ECOPAGES_PORT = 3e3;
-const DEFAULT_ECOPAGES_HOSTNAME = "localhost";
-const DEFAULT_ECOPAGES_DIST_DIR = "dist";
-const DEFAULT_ECOPAGES_WORK_DIR = ".eco";
-export {
-  DEFAULT_ECOPAGES_DIST_DIR,
-  DEFAULT_ECOPAGES_HOSTNAME,
-  DEFAULT_ECOPAGES_PORT,
-  DEFAULT_ECOPAGES_WORK_DIR,
-  GENERATED_BASE_PATHS,
-  IS_BUN,
-  RESOLVED_ASSETS_DIR,
-  RESOLVED_ASSETS_VENDORS_DIR,
-  STATUS_MESSAGE
+/**
+ *Variables used to determine if the app is running on Bun
+ */
+export const IS_BUN = typeof Bun !== 'undefined';
+/**
+ * Directory used for storing assets.
+ */
+export const RESOLVED_ASSETS_DIR = 'assets';
+/**
+ * Directory used for storing vendor assets.
+ * This is a subdirectory of the assets directory.
+ */
+export const RESOLVED_ASSETS_VENDORS_DIR = `${RESOLVED_ASSETS_DIR}/vendors`;
+/**
+ * Base paths for generated project files.
+ */
+export const GENERATED_BASE_PATHS = {
+    types: 'node_modules/@types',
+    cache: 'cache',
 };
+export const DEFAULT_ECOPAGES_PORT = 3000;
+export const DEFAULT_ECOPAGES_HOSTNAME = 'localhost';
+/**
+ * Default directory used for deployable output.
+ */
+export const DEFAULT_ECOPAGES_DIST_DIR = 'dist';
+/**
+ * Default internal working directory used for runtime-only artifacts.
+ *
+ * @remarks
+ * This directory is a local tool workspace and is not intended for deployment.
+ * It owns transpiled server modules, runtime manifests, and processor caches
+ * so the export directory can remain a clean deployable tree.
+ */
+export const DEFAULT_ECOPAGES_WORK_DIR = '.eco';

package/src/declarations.d.ts

@@ -15,6 +15,7 @@ type EcoPagesWindowRuntime = {
 		cleanupPageRoot?: CleanupPageRootFunction;
 		pageRoot?: EcoPageRoot | null;
 	};
+	islandRoots?: Record<string, EcoPageRoot>;
 	page?: EcoPageData;
 };
 

package/src/dev/README.md

@@ -0,0 +1,24 @@
+Development-only browser tooling is opt-in per application.
+
+## Dev toolbar
+
+- `/_dev_toolbar.js` — browser bundle built by core from `devToolbar.package` (for example `@ecopages/dev-toolbar`)
+- `#__ECO_DEV_MANIFEST__` — per-page dependency graph payload for the Deps panel
+
+Public docs: [Dev toolbar](/docs/core/dev-toolbar) (built-in apps, manifest fields).
+
+Configure in `eco.config.ts`:
+
+```ts
+import { devToolbar } from '@ecopages/dev-toolbar/config';
+
+.setDevToolbar(devToolbar())
+```
+
+For a custom client package, use `defineDevTool` from `@ecopages/core/dev-toolbar/define-dev-tool`.
+
+Install the client package in the app project. Core resolves it from the application root and bundles it during watch mode.
+
+Disable per project with `devToolbar: { enabled: false }`, or per process with `ECOPAGES_DEV_TOOLBAR=false`.
+
+Server wiring: [dev-toolbar/README.md](../dev-toolbar/README.md) (`DevToolbarHost`, manifest, runtime bundling, HTML injection). Bring-your-own toolbars export `src/bootstrap.ts` and use the same `devToolbar.package` config key.

package/src/dev/client-bridge-registry.js

@@ -1,15 +1,10 @@
-const appDevClientBridges = /* @__PURE__ */ new WeakMap();
-function setAppDevClientBridge(appConfig, bridge) {
-  appDevClientBridges.set(appConfig, bridge);
+const appDevClientBridges = new WeakMap();
+export function setAppDevClientBridge(appConfig, bridge) {
+    appDevClientBridges.set(appConfig, bridge);
 }
-function getAppDevClientBridge(appConfig) {
-  return appDevClientBridges.get(appConfig);
+export function getAppDevClientBridge(appConfig) {
+    return appDevClientBridges.get(appConfig);
 }
-function clearAppDevClientBridge(appConfig) {
-  appDevClientBridges.delete(appConfig);
+export function clearAppDevClientBridge(appConfig) {
+    appDevClientBridges.delete(appConfig);
 }
-export {
-  clearAppDevClientBridge,
-  getAppDevClientBridge,
-  setAppDevClientBridge
-};

package/src/dev/dev-client-ownership.js

@@ -1,6 +1,8 @@
-function hostOwnsDevClient(runtime) {
-  return runtime?.devClientOwner === "host" || runtime?.delegateBrowserReloadToHost === true;
+/**
+ * Returns whether the host dev server owns all browser dev-client bootstrap.
+ *
+ * When true, core must not inject the HMR runtime or signal full-page reloads.
+ */
+export function hostOwnsDevClient(runtime) {
+    return runtime?.devClientOwner === 'host';
 }
-export {
-  hostOwnsDevClient
-};

package/src/dev/hmr-manager-registry.js

@@ -1,15 +1,10 @@
-const appHmrManagers = /* @__PURE__ */ new WeakMap();
-function setAppHmrManager(appConfig, hmrManager) {
-  appHmrManagers.set(appConfig, hmrManager);
+const appHmrManagers = new WeakMap();
+export function setAppHmrManager(appConfig, hmrManager) {
+    appHmrManagers.set(appConfig, hmrManager);
 }
-function getAppHmrManager(appConfig) {
-  return appHmrManagers.get(appConfig);
+export function getAppHmrManager(appConfig) {
+    return appHmrManagers.get(appConfig);
 }
-function clearAppHmrManager(appConfig) {
-  appHmrManagers.delete(appConfig);
+export function clearAppHmrManager(appConfig) {
+    appHmrManagers.delete(appConfig);
 }
-export {
-  clearAppHmrManager,
-  getAppHmrManager,
-  setAppHmrManager
-};

package/src/dev/host-runtime.js

@@ -1,31 +1,26 @@
-import {
-  DevelopmentInvalidationService
-} from "../services/invalidation/development-invalidation.service.js";
-import { getAppDevClientBridge } from "./client-bridge-registry.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);
-    },
-    broadcastClientEvent(event) {
-      getAppDevClientBridge(appConfig)?.broadcast(event);
-    },
-    isServerRenderedTemplatePlan(plan) {
-      return plan.category === "include-source" || plan.category === "explicit-server-view";
-    }
-  };
+import { DevelopmentInvalidationService, } from '../services/invalidation/development-invalidation.service.js';
+import { getAppDevClientBridge } from './client-bridge-registry.js';
+import { setHostModuleLoader } from '../services/module-loading/host-module-loader-registry.js';
+export 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);
+        },
+        broadcastClientEvent(event) {
+            getAppDevClientBridge(appConfig)?.broadcast(event);
+        },
+        isServerRenderedTemplatePlan(plan) {
+            return plan.category === 'include-source' || plan.category === 'explicit-server-view';
+        },
+    };
 }
-export {
-  createDevelopmentHostRuntime
-};

package/src/dev/runtime-server-started-message.js

@@ -1,6 +1,3 @@
-function formatRuntimeServerStartedMessage(runtime, origin) {
-  return `${runtime} server running at ${origin.replace(/\/$/, "")}`;
+export function formatRuntimeServerStartedMessage(runtime, origin) {
+    return `${runtime} server running at ${origin.replace(/\/$/, '')}`;
 }
-export {
-  formatRuntimeServerStartedMessage
-};

package/src/dev/sc-server.js

@@ -1,111 +1,114 @@
-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
-      });
+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';
+/**
+ * Static content server for production builds.
+ * Serves pre-built static files from the dist directory with gzip compression support.
+ */
+export class StaticContentServer {
+    server = null;
+    appConfig;
+    options = { port: 3000 };
+    constructor({ appConfig, options }) {
+        this.appConfig = appConfig;
+        if (options)
+            this.options = options;
+        this.startServer();
     }
-    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"
-            }
-          });
+    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,
+            });
         }
-      }
-      if (path.includes(".") && fileSystem.exists(basePath)) {
-        const file = fileSystem.readFileAsBuffer(basePath);
-        return new Response(file, {
-          headers: { "Content-Type": contentType }
+        const response = new Response(fileSystem.readFileAsBuffer(error404TemplatePath), {
+            headers: { 'Content-Type': 'text/html' },
         });
-      }
-      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 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();
         }
-      }
-      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);
+    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: appConfig,
+            options,
+        });
     }
-  }
-  static createServer({
-    appConfig,
-    options
-  }) {
-    return new StaticContentServer({
-      appConfig,
-      options
-    });
-  }
 }
-export {
-  StaticContentServer
-};

package/src/dev/transform-server/dev-transform-bundler.d.ts

@@ -0,0 +1,24 @@
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+import type { DevTransformVendorRegistry } from './dev-transform-vendor-registry.js';
+import type { DevTransformBundleContributor, DevTransformBundleResult } from './types.js';
+export type DevTransformBundlerOptions = {
+    appConfig: EcoPagesAppConfig;
+    contributors?: readonly DevTransformBundleContributor[];
+    getRuntimeSpecifierMap: () => ReadonlyMap<string, string>;
+    vendorRegistry: DevTransformVendorRegistry;
+};
+/**
+ * Transpiles one dev client module at a time to browser ESM with rewritten imports.
+ */
+export declare class DevTransformBundler {
+    private readonly appConfig;
+    private readonly browserBundleService;
+    private readonly getRuntimeSpecifierMap;
+    private readonly vendorRegistry;
+    private readonly contributors;
+    constructor(options: DevTransformBundlerOptions);
+    addContributor(contributor: DevTransformBundleContributor): void;
+    private selectContributor;
+    private resolveTempOutdir;
+    transpileModule(sourcePath: string): Promise<DevTransformBundleResult>;
+}

package/src/dev/transform-server/dev-transform-bundler.js

@@ -0,0 +1,79 @@
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { fileSystem } from '@ecopages/file-system';
+import { BrowserBundleService } from '../../services/assets/browser-bundle.service.js';
+import { createDevTransformExternalizeImportsPlugin } from './dev-transform-externalize-plugin.js';
+import { rewriteModuleImports } from './dev-transform-import-rewriter.js';
+/**
+ * Transpiles one dev client module at a time to browser ESM with rewritten imports.
+ */
+export class DevTransformBundler {
+    appConfig;
+    browserBundleService;
+    getRuntimeSpecifierMap;
+    vendorRegistry;
+    contributors = [];
+    constructor(options) {
+        this.appConfig = options.appConfig;
+        this.browserBundleService = new BrowserBundleService(options.appConfig);
+        this.getRuntimeSpecifierMap = options.getRuntimeSpecifierMap;
+        this.vendorRegistry = options.vendorRegistry;
+        this.contributors.push(...(options.contributors ?? []));
+    }
+    addContributor(contributor) {
+        this.contributors.push(contributor);
+    }
+    selectContributor(sourcePath) {
+        return this.contributors.find((contributor) => contributor.ownsModule(sourcePath));
+    }
+    resolveTempOutdir() {
+        const distDir = this.appConfig.absolutePaths?.distDir ?? path.join(this.appConfig.rootDir, '.eco', 'assets');
+        return path.join(distDir, '.dev-transform');
+    }
+    async transpileModule(sourcePath) {
+        const normalized = path.resolve(sourcePath);
+        const contributor = this.selectContributor(normalized);
+        const pagePlugins = contributor ? await contributor.getModulePlugins(normalized) : [];
+        const tempDir = this.resolveTempOutdir();
+        fileSystem.ensureDir(tempDir);
+        /**
+         * @remarks
+         * Entry key is a path hash so concurrent transpiles of different modules that
+         * share a basename (e.g. multiple `index.tsx`) never collide on disk output.
+         */
+        const entryKey = createHash('sha256').update(normalized).digest('hex').slice(0, 16);
+        const result = await this.browserBundleService.bundle({
+            profile: 'hmr-entrypoint',
+            entrypoints: { [entryKey]: normalized },
+            outdir: tempDir,
+            naming: '[name].js',
+            plugins: [createDevTransformExternalizeImportsPlugin(), ...pagePlugins],
+            minify: false,
+        });
+        if (!result.success) {
+            const details = result.logs.map((log) => log.message).join('\n');
+            throw new Error(details
+                ? `[dev-transform] Transpile failed for ${normalized}:\n${details}`
+                : `[dev-transform] Transpile failed for ${normalized}`);
+        }
+        const outputPath = result.entryOutputs?.[normalized] ??
+            result.outputs.find((output) => path.basename(output.path) === `${entryKey}.js`)?.path ??
+            result.outputs[0]?.path;
+        if (!outputPath) {
+            throw new Error(`[dev-transform] No transpile output for ${normalized}`);
+        }
+        const transpiledCode = fileSystem.readFileSync(outputPath);
+        const rewritten = await rewriteModuleImports({
+            code: transpiledCode,
+            sourcePath: normalized,
+            srcDir: this.appConfig.absolutePaths.srcDir,
+            projectRoot: this.appConfig.rootDir,
+            runtimeSpecifierMap: this.getRuntimeSpecifierMap(),
+            resolveVendorUrl: (specifier) => this.vendorRegistry.resolveVendorUrl(specifier),
+        });
+        return {
+            code: rewritten.code,
+            dependencies: rewritten.dependencies,
+        };
+    }
+}

package/src/dev/transform-server/dev-transform-externalize-plugin.d.ts

@@ -0,0 +1,12 @@
+import type { EcoBuildPlugin } from '../../build/contracts/build-types.js';
+/**
+ * Marks dependency imports as external so Rolldown transpiles only the entry module.
+ *
+ * @remarks
+ * The Rolldown plugin bridge splits specifiers such as `ecopages:images` into
+ * `namespace` + `path` before `onResolve`. Returning `external: true` for those
+ * would emit a bare `from "images"` import and skip virtual-module `onLoad`.
+ * Namespaced imports are left for app plugins (image map, etc.) to inline into
+ * this single-file transpile.
+ */
+export declare function createDevTransformExternalizeImportsPlugin(): EcoBuildPlugin;

package/src/dev/transform-server/dev-transform-externalize-plugin.js

@@ -0,0 +1,29 @@
+/**
+ * Marks dependency imports as external so Rolldown transpiles only the entry module.
+ *
+ * @remarks
+ * The Rolldown plugin bridge splits specifiers such as `ecopages:images` into
+ * `namespace` + `path` before `onResolve`. Returning `external: true` for those
+ * would emit a bare `from "images"` import and skip virtual-module `onLoad`.
+ * Namespaced imports are left for app plugins (image map, etc.) to inline into
+ * this single-file transpile.
+ */
+export function createDevTransformExternalizeImportsPlugin() {
+    return {
+        name: 'ecopages-dev-transform-externalize-imports',
+        setup(build) {
+            build.onResolve({ filter: /.*/u }, (args) => {
+                if (!args.importer) {
+                    return undefined;
+                }
+                if (args.namespace) {
+                    return undefined;
+                }
+                return {
+                    path: args.path,
+                    external: true,
+                };
+            });
+        },
+    };
+}

package/src/dev/transform-server/dev-transform-import-rewriter.d.ts

@@ -0,0 +1,16 @@
+type RewriteModuleImportsOptions = {
+    code: string;
+    sourcePath: string;
+    srcDir: string;
+    projectRoot: string;
+    runtimeSpecifierMap: ReadonlyMap<string, string>;
+    resolveVendorUrl: (specifier: string) => Promise<string>;
+};
+/**
+ * Rewrites static and dynamic import specifiers to dev-transform or vendor URLs.
+ */
+export declare function rewriteModuleImports(options: RewriteModuleImportsOptions): Promise<{
+    code: string;
+    dependencies: string[];
+}>;
+export {};