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

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

@@ -17,7 +17,7 @@ import type { ServerInvalidationState } from '../services/runtime-state/server-i
 import type { ServerModuleTranspiler } from '../services/module-loading/server-module-transpiler.service.js';
 import type { RouteModuleBuildCache } from '../services/module-loading/route-module-build-cache.store.js';
 /** Integration hook for registered `dependencies.scripts` entrypoint changes in dev. */
-export type RegisteredScriptEntrypointChangeHandler = (filePath: string) => void | Promise<void>;
+export type RegisteredScriptEntrypointChangeHandler = (filePath: string) => void | boolean | Promise<void | boolean>;
 export interface RobotsPreference {
     /**
      * The user agent
@@ -187,8 +187,24 @@ export type EcoPagesAppConfig = {
         devClientOwner?: 'core' | 'host';
         /** Integration hooks run when a registered `dependencies.scripts` entrypoint changes. */
         registeredScriptEntrypointChangeHandlers?: RegisteredScriptEntrypointChangeHandler[];
-        /** @deprecated Prefer {@link devClientOwner}: `'host'`. */
-        delegateBrowserReloadToHost?: boolean;
+    };
+    /**
+     * Development-only in-browser toolbar configuration.
+     */
+    devToolbar?: {
+        /**
+         * Whether the dev toolbar is enabled during watch mode.
+         *
+         * @default true when `package` is configured
+         */
+        enabled?: boolean;
+        /**
+         * Client package resolved from the application project and bundled to
+         * `/_dev_toolbar.js` during watch mode.
+         *
+         * @example '@ecopages/dev-toolbar'
+         */
+        package?: string;
     };
     /**
      * Experimental features.

package/src/types/internal-types.js

@@ -0,0 +1 @@
+export {};

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

@@ -1,15 +1,14 @@
 import type { Readable } from 'node:stream';
 import type { ApiResponseBuilder } from '../adapters/shared/http/api-response.js';
-import type { BuildExecutor } from '../build/build-adapter.js';
 import type { ForeignChildRuntime } from '../route-renderer/orchestration/foreign-child/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 { 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';
 import type { EntrypointDependencyGraph } from '../services/runtime-state/entrypoint-dependency-graph.service.js';
+import type { DevTransformBundleContributor } from '../dev/transform-server/types.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';
@@ -163,17 +162,14 @@ export interface CacheInvalidator {
 }
 /**
  * Context interface for HMR strategies.
- * Provides access to watched files, registered bare-specifier mappings, and build configuration.
+ * Provides access to registered entrypoints and build configuration.
  */
 export interface DefaultHmrContext {
     /**
-     * Map of registered entrypoints to their output URLs.
+     * Map of registered entrypoint source paths to their dev-transform output URLs.
      */
     getWatchedFiles(): Map<string, string>;
-    /**
-     * Directory where HMR bundles are written.
-     */
-    getDistDir(): string;
+    getRegisteredEntrypoints(): ReadonlyMap<string, ResolvedHmrEntrypoint>;
     /**
      * Absolute path to the source directory.
      */
@@ -188,14 +184,6 @@ 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.
      */
@@ -204,14 +192,6 @@ export interface DefaultHmrContext {
      * Entrypoint dependency graph for selective HMR invalidation.
      */
     getEntrypointDependencyGraph(): EntrypointDependencyGraph;
-    /**
-     * Registers an already-materialized HMR entrypoint without rebuilding it.
-     *
-     * @remarks
-     * Cold dev batches seed the registrar after grouped builds so the first SSR
-     * resolves the artifact from disk instead of triggering a rebuild.
-     */
-    seedResolvedEntrypoint(resolved: ResolvedHmrEntrypoint): void;
 }
 /**
  * Represents an event broadcast to connected clients via the ClientBridge.
@@ -262,13 +242,11 @@ 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;
+    role: 'page' | 'script';
 }
 /**
  * Interface for the HMR Manager.
@@ -276,21 +254,17 @@ export interface ResolvedHmrEntrypoint {
  */
 export interface IHmrManager {
     /**
-     * Registers an integration-owned client entrypoint to be built and watched.
+     * Registers a client entrypoint for dev-transform delivery and HMR watching.
      *
      * @remarks
-     * This path is strict: the owning integration must emit the expected `_hmr`
-     * bundle. Missing output is treated as a development pipeline failure.
+     * Returns a stable `/assets/__eco_dev__/…` URL immediately; the module is
+     * transpiled on the first browser request (per-file ESM, not a page bundle).
      */
     registerEntrypoint(entrypointPath: string): Promise<string>;
     /**
-     * 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.
+     * Registers an integration contributor that supplies per-module transform plugins.
      */
+    registerDevTransformContributor(contributor: DevTransformBundleContributor): void;
     registerScriptEntrypoint(entrypointPath: string): Promise<ResolvedHmrEntrypoint>;
     /**
      * Registers a custom HMR strategy.
@@ -320,22 +294,18 @@ export interface IHmrManager {
      * Returns an existing emitted HMR script artifact without registering it.
      */
     getResolvedScriptOutput?(entrypointPath: string): ResolvedHmrEntrypoint | undefined;
-    /**
-     * Registers an already-materialized HMR entrypoint without rebuilding it.
-     *
-     * @remarks
-     * Cold dev batches seed the registrar after grouped builds so the first SSR
-     * resolves the artifact from disk instead of triggering a rebuild.
-     */
-    seedResolvedEntrypoint?(resolved: ResolvedHmrEntrypoint): void;
     /**
      * Gets the map of watched files.
      */
     getWatchedFiles(): Map<string, string>;
     /**
-     * Gets the HMR dist directory.
+     * Gets registered dev-transform entrypoints keyed by resolved source path.
+     */
+    getRegisteredEntrypoints(): ReadonlyMap<string, ResolvedHmrEntrypoint>;
+    /**
+     * Gets the on-disk work directory for the bundled HMR client runtime.
      */
-    getDistDir(): string;
+    getRuntimeWorkDir(): string;
     /**
      * Returns the on-disk path to the bundled HMR runtime script.
      */

package/src/types/public-types.js

@@ -0,0 +1 @@
+export {};

package/src/utils/deep-merge.js

@@ -1,32 +1,45 @@
+/**
+ * This module contains a simple utility function to merge two objects deeply
+ * @module
+ */
 function isObject(item) {
-  return item && typeof item === "object" && !Array.isArray(item);
+    return item && typeof item === 'object' && !Array.isArray(item);
 }
 function isArray(item) {
-  return Array.isArray(item);
+    return Array.isArray(item);
 }
-function deepMerge(target, source) {
-  if (isArray(target) && isArray(source)) {
-    return [...target, ...source];
-  }
-  if (!isObject(target) || !isObject(source)) {
-    return source;
-  }
-  const output = Object.assign({}, target);
-  for (const key in source) {
-    if (isObject(source[key])) {
-      if (!target[key]) {
-        Object.assign(output, { [key]: source[key] });
-      } else {
-        output[key] = deepMerge(target[key], source[key]);
-      }
-    } else if (isArray(source[key])) {
-      output[key] = [...target[key] || [], ...source[key]];
-    } else if (source[key] !== void 0) {
-      Object.assign(output, { [key]: source[key] });
+/**
+ * Deeply merges two objects or arrays
+ * @function deepMerge
+ * @template T - Type of target object
+ * @template U - Type of source object
+ * @param target - The target object to merge into
+ * @param source - The source object to merge from
+ * @returns A new object with merged properties
+ */
+export function deepMerge(target, source) {
+    if (isArray(target) && isArray(source)) {
+        return [...target, ...source];
     }
-  }
-  return output;
+    if (!isObject(target) || !isObject(source)) {
+        return source;
+    }
+    const output = Object.assign({}, target);
+    for (const key in source) {
+        if (isObject(source[key])) {
+            if (!target[key]) {
+                Object.assign(output, { [key]: source[key] });
+            }
+            else {
+                output[key] = deepMerge(target[key], source[key]);
+            }
+        }
+        else if (isArray(source[key])) {
+            output[key] = [...(target[key] || []), ...source[key]];
+        }
+        else if (source[key] !== undefined) {
+            Object.assign(output, { [key]: source[key] });
+        }
+    }
+    return output;
 }
-export {
-  deepMerge
-};

package/src/utils/ecopages-route-info.js

@@ -1,26 +1,30 @@
-import { normalizePathname } from "./path-pattern.js";
-function toEcopagesRouteInfo(route) {
-  return {
-    pathname: normalizePathname(route.pathname),
-    params: normalizeRouteParams(route.params)
-  };
+import { normalizePathname } from './path-pattern.js';
+/**
+ * Maps a static-generation or registry route into the public slim route shape.
+ */
+export function toEcopagesRouteInfo(route) {
+    return {
+        pathname: normalizePathname(route.pathname),
+        params: normalizeRouteParams(route.params),
+    };
 }
-function normalizeRouteParams(params) {
-  const normalized = {};
-  for (const [key, value] of Object.entries(params)) {
-    normalized[key] = Array.isArray(value) ? value.join("/") : value;
-  }
-  return normalized;
+/**
+ * Flattens string | string[] route params into string values for public APIs.
+ */
+export function normalizeRouteParams(params) {
+    const normalized = {};
+    for (const [key, value] of Object.entries(params)) {
+        normalized[key] = Array.isArray(value) ? value.join('/') : value;
+    }
+    return normalized;
 }
-async function resolveAppStartRoutes(input) {
-  if (!input.listStaticGenerationRoutes) {
-    return [];
-  }
-  const routes = await input.listStaticGenerationRoutes({ runtimeOrigin: input.runtimeOrigin });
-  return routes.map(toEcopagesRouteInfo);
+/**
+ * Resolves {@link EcopagesRouteInfo} entries for app-start and similar consumers.
+ */
+export async function resolveAppStartRoutes(input) {
+    if (!input.listStaticGenerationRoutes) {
+        return [];
+    }
+    const routes = await input.listStaticGenerationRoutes({ runtimeOrigin: input.runtimeOrigin });
+    return routes.map(toEcopagesRouteInfo);
 }
-export {
-  normalizeRouteParams,
-  resolveAppStartRoutes,
-  toEcopagesRouteInfo
-};

package/src/utils/hash.js

@@ -1,7 +1,4 @@
-import { runtimeHash } from "./runtime.js";
-const rapidhash = (content) => {
-  return runtimeHash(content);
-};
-export {
-  rapidhash
+import { runtimeHash } from './runtime.js';
+export const rapidhash = (content) => {
+    return runtimeHash(content);
 };

package/src/utils/html-escaping.js

@@ -1,10 +1,23 @@
-function escapeHtmlAttribute(value) {
-  return value.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+/**
+ * Escapes a string for safe use inside a double-quoted HTML attribute value.
+ *
+ * @param value Raw attribute value.
+ * @returns Escaped attribute-safe string.
+ */
+export function escapeHtmlAttribute(value) {
+    return value.replaceAll('&', '&amp;').replaceAll('"', '&quot;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
 }
-function escapeXmlText(value) {
-  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&apos;");
+/**
+ * Escapes a string for safe use as XML text content (e.g. `<loc>` values).
+ *
+ * @param value Raw text node value.
+ * @returns Escaped XML-safe string.
+ */
+export function escapeXmlText(value) {
+    return value
+        .replaceAll('&', '&amp;')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('"', '&quot;')
+        .replaceAll("'", '&apos;');
 }
-export {
-  escapeHtmlAttribute,
-  escapeXmlText
-};

package/src/utils/html.js

@@ -1,4 +1 @@
-import { html } from "ghtml";
-export {
-  html
-};
+export { html } from 'ghtml';

package/src/utils/invariant.js

@@ -1,11 +1,12 @@
-const prefix = "[ecopages]";
-function invariant(condition, message) {
-  if (condition) {
-    return;
-  }
-  const value = message ? `${prefix} ${message}` : `${prefix} An error occurred`;
-  throw new Error(value);
+/**
+ * This module contains a simple utility invariant function that throws an error if the condition is not met
+ * @module
+ */
+const prefix = '[ecopages]';
+export function invariant(condition, message) {
+    if (condition) {
+        return;
+    }
+    const value = message ? `${prefix} ${message}` : `${prefix} An error occurred`;
+    throw new Error(value);
 }
-export {
-  invariant
-};

package/src/utils/locals-utils.js

@@ -1,24 +1,34 @@
-function createRequire(getLocals) {
-  return (keyOrKeys, onMissing) => {
-    const locals = getLocals();
-    if (Array.isArray(keyOrKeys)) {
-      const result = {};
-      for (const key of keyOrKeys) {
-        const value2 = locals[key];
-        if (value2 === void 0 || value2 === null) {
-          throw onMissing();
+/**
+ * Creates a require function for validating and retrieving request locals.
+ * Supports both single key access and multiple keys with type safety.
+ *
+ * @param getLocals - Function that returns the current locals object
+ * @returns A require function that throws the onMissing response if keys are not found
+ *
+ * @example
+ * ```ts
+ * const require = createRequire(() => context.locals);
+ * const userId = require('userId', () => new Response('Unauthorized', { status: 401 }));
+ * ```
+ */
+export function createRequire(getLocals) {
+    return (keyOrKeys, onMissing) => {
+        const locals = getLocals();
+        if (Array.isArray(keyOrKeys)) {
+            const result = {};
+            for (const key of keyOrKeys) {
+                const value = locals[key];
+                if (value === undefined || value === null) {
+                    throw onMissing();
+                }
+                result[key] = value;
+            }
+            return result;
         }
-        result[key] = value2;
-      }
-      return result;
-    }
-    const value = locals[keyOrKeys];
-    if (value === void 0 || value === null) {
-      throw onMissing();
-    }
-    return value;
-  };
+        const value = locals[keyOrKeys];
+        if (value === undefined || value === null) {
+            throw onMissing();
+        }
+        return value;
+    };
 }
-export {
-  createRequire
-};

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

@@ -1,68 +1,76 @@
-import { parseArgs } from "node:util";
-import { getRuntimeArgv } from "./runtime.js";
+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,
-    force: false,
-    serveOnly: false,
-    port: void 0,
-    hostname: void 0,
-    reactFastRefresh: void 0
-  };
+    const isDevelopment = process.env.NODE_ENV === 'development';
+    return {
+        preview: false,
+        build: false,
+        start: !isDevelopment,
+        dev: isDevelopment,
+        force: false,
+        serveOnly: false,
+        port: undefined,
+        hostname: undefined,
+        reactFastRefresh: undefined,
+    };
 }
-const ECOPAGES_BIN_FILES = ["ecopages.ts", "ecopages.js", "cli.js"];
-const ECOPAGES_AVAILABLE_COMMANDS = ["dev", "build", "start", "preview"];
-function parseCliArgs(options = {}) {
-  if (options.embeddedRuntime || process.env.ECOPAGES_INTERNAL_EMBEDDED_RUNTIME === "true") {
-    return getEmbeddedRuntimeCommandOptions();
-  }
-  const runtimeArgv = getRuntimeArgv();
-  const { values } = parseArgs({
-    args: runtimeArgv,
-    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" }
-    },
-    allowPositionals: true
-  });
-  let command = "";
-  const ecopagesIndex = runtimeArgv.findIndex((arg) => ECOPAGES_BIN_FILES.some((filename) => arg.endsWith(filename)));
-  const isAvailableCommand = ecopagesIndex !== -1;
-  if (isAvailableCommand) {
-    command = ecopagesIndex < runtimeArgv.length - 1 && ECOPAGES_AVAILABLE_COMMANDS.some((cmd) => {
-      return runtimeArgv[ecopagesIndex + 1] === cmd;
-    }) ? runtimeArgv[ecopagesIndex + 1] : "start";
-  }
-  const isStartCommand = command === "start" || !values.dev && !values.build && !values.preview;
-  const isDevCommand = command === "dev" || !!values.dev;
-  const isBuildCommand = command === "build" || !!values.build;
-  const isPreviewCommand = command === "preview" || !!values.preview;
-  const parsedCommandOptions = {
-    preview: isPreviewCommand,
-    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"]
-  };
-  if (!process.env.NODE_ENV) {
-    process.env.NODE_ENV = isDevCommand ? "development" : "production";
-  }
-  return parsedCommandOptions;
+const ECOPAGES_BIN_FILES = ['ecopages.ts', 'ecopages.js', 'cli.js'];
+const ECOPAGES_AVAILABLE_COMMANDS = ['dev', 'build', 'start', 'preview'];
+/**
+ * Parses command line arguments for the server.
+ * It returns {@link ReturnParseCliArgs}
+ */
+export function parseCliArgs(options = {}) {
+    if (options.embeddedRuntime || process.env.ECOPAGES_INTERNAL_EMBEDDED_RUNTIME === 'true') {
+        return getEmbeddedRuntimeCommandOptions();
+    }
+    const runtimeArgv = getRuntimeArgv();
+    const { values } = parseArgs({
+        args: runtimeArgv,
+        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' },
+        },
+        allowPositionals: true,
+    });
+    let command = '';
+    const ecopagesIndex = runtimeArgv.findIndex((arg) => ECOPAGES_BIN_FILES.some((filename) => arg.endsWith(filename)));
+    const isAvailableCommand = ecopagesIndex !== -1;
+    if (isAvailableCommand) {
+        command =
+            ecopagesIndex < runtimeArgv.length - 1 &&
+                ECOPAGES_AVAILABLE_COMMANDS.some((cmd) => {
+                    return runtimeArgv[ecopagesIndex + 1] === cmd;
+                })
+                ? runtimeArgv[ecopagesIndex + 1]
+                : 'start';
+    }
+    const isStartCommand = command === 'start' || (!values.dev && !values.build && !values.preview);
+    const isDevCommand = command === 'dev' || !!values.dev;
+    const isBuildCommand = command === 'build' || !!values.build;
+    const isPreviewCommand = command === 'preview' || !!values.preview;
+    const parsedCommandOptions = {
+        preview: isPreviewCommand,
+        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) : undefined,
+        hostname: values.hostname,
+        reactFastRefresh: values['react-fast-refresh'],
+    };
+    if (isDevCommand) {
+        process.env.NODE_ENV ??= 'development';
+    }
+    else {
+        process.env.NODE_ENV = 'production';
+    }
+    return parsedCommandOptions;
 }
-export {
-  parseCliArgs
-};

package/src/utils/path-pattern.js

@@ -1,27 +1,42 @@
-function normalizePathname(pathname) {
-  if (!pathname || pathname === "/") {
-    return "/";
-  }
-  const withLeadingSlash = pathname.startsWith("/") ? pathname : `/${pathname}`;
-  return withLeadingSlash.replace(/\/+$/, "") || "/";
+/**
+ * Normalizes a URL pathname for matching and sitemap location building.
+ *
+ * @remarks
+ * Ensures a leading slash and strips trailing slashes except for `/`.
+ */
+export function normalizePathname(pathname) {
+    if (!pathname || pathname === '/') {
+        return '/';
+    }
+    const withLeadingSlash = pathname.startsWith('/') ? pathname : `/${pathname}`;
+    return withLeadingSlash.replace(/\/+$/, '') || '/';
 }
-function matchPathPattern(pathname, pattern) {
-  const normalizedPath = normalizePathname(pathname);
-  const normalizedPattern = pattern.trim();
-  if (normalizedPattern.endsWith("/**")) {
-    const prefix = normalizePathname(normalizedPattern.slice(0, -3));
-    if (prefix === "/") {
-      return true;
+/**
+ * Matches a pathname against a small set of supported patterns.
+ *
+ * @remarks
+ * Supported forms:
+ * - exact: `/admin`
+ * - prefix wildcard: `/admin/**` (matches `/admin` and descendants)
+ * - trailing `**` only as a full segment after `/`
+ *
+ * This is not a full glob engine. Unsupported patterns are treated as exact matches.
+ */
+export function matchPathPattern(pathname, pattern) {
+    const normalizedPath = normalizePathname(pathname);
+    const normalizedPattern = pattern.trim();
+    if (normalizedPattern.endsWith('/**')) {
+        const prefix = normalizePathname(normalizedPattern.slice(0, -3));
+        if (prefix === '/') {
+            return true;
+        }
+        return normalizedPath === prefix || normalizedPath.startsWith(`${prefix}/`);
     }
-    return normalizedPath === prefix || normalizedPath.startsWith(`${prefix}/`);
-  }
-  return normalizedPath === normalizePathname(normalizedPattern);
+    return normalizedPath === normalizePathname(normalizedPattern);
 }
-function matchesAnyPathPattern(pathname, patterns) {
-  return patterns.some((pattern) => matchPathPattern(pathname, pattern));
+/**
+ * Returns true when the pathname matches any of the patterns.
+ */
+export function matchesAnyPathPattern(pathname, patterns) {
+    return patterns.some((pattern) => matchPathPattern(pathname, pattern));
 }
-export {
-  matchPathPattern,
-  matchesAnyPathPattern,
-  normalizePathname
-};