@ecopages/core 0.2.0-beta.9 → 0.2.0-rc.0

package/src/eco/global-injector-map.js

@@ -1,44 +1,62 @@
+/**
+ * Converts a flat list of resolved triggers into the map structure consumed
+ * by the `initGlobalInjector` bootstrap. Multiple triggers sharing the same
+ * `triggerId` are merged so their script lists are deduplicated.
+ */
 function buildGlobalInjectorMap(triggers) {
-  const map = {};
-  for (const { triggerId, rules } of triggers) {
-    const entry = map[triggerId] ?? {};
-    for (const rule of rules) {
-      if ("on:idle" in rule) {
-        const { scripts } = rule["on:idle"];
-        entry["on:idle"] = {
-          scripts: Array.from(/* @__PURE__ */ new Set([...entry["on:idle"]?.scripts ?? [], ...scripts]))
-        };
-        continue;
-      }
-      if ("on:interaction" in rule) {
-        const { value, scripts } = rule["on:interaction"];
-        entry["on:interaction"] = {
-          value,
-          scripts: Array.from(/* @__PURE__ */ new Set([...entry["on:interaction"]?.scripts ?? [], ...scripts]))
-        };
-        continue;
-      }
-      if ("on:visible" in rule) {
-        const { value, scripts } = rule["on:visible"];
-        entry["on:visible"] = {
-          ...value ? { value } : {},
-          scripts: Array.from(/* @__PURE__ */ new Set([...entry["on:visible"]?.scripts ?? [], ...scripts]))
-        };
-        continue;
-      }
+    const map = {};
+    for (const { triggerId, rules } of triggers) {
+        const entry = map[triggerId] ?? {};
+        for (const rule of rules) {
+            if ('on:idle' in rule) {
+                const { scripts } = rule['on:idle'];
+                entry['on:idle'] = {
+                    scripts: Array.from(new Set([...(entry['on:idle']?.scripts ?? []), ...scripts])),
+                };
+                continue;
+            }
+            if ('on:interaction' in rule) {
+                const { value, scripts } = rule['on:interaction'];
+                entry['on:interaction'] = {
+                    value,
+                    scripts: Array.from(new Set([...(entry['on:interaction']?.scripts ?? []), ...scripts])),
+                };
+                continue;
+            }
+            if ('on:visible' in rule) {
+                const { value, scripts } = rule['on:visible'];
+                entry['on:visible'] = {
+                    ...(value ? { value } : {}),
+                    scripts: Array.from(new Set([...(entry['on:visible']?.scripts ?? []), ...scripts])),
+                };
+                continue;
+            }
+        }
+        if (Object.keys(entry).length > 0) {
+            map[triggerId] = entry;
+        }
     }
-    if (Object.keys(entry).length > 0) {
-      map[triggerId] = entry;
-    }
-  }
-  return map;
+    return map;
 }
-function buildGlobalInjectorMapScript(triggers) {
-  const map = buildGlobalInjectorMap(triggers);
-  return JSON.stringify(map).replace(/<\/script/gi, "<\\/script");
+/**
+ * Serializes resolved lazy triggers into a JSON string safe for embedding
+ * inside an inline `<script type="ecopages/global-injector-map">` tag.
+ *
+ * The `</script` sequence is escaped because an unescaped occurrence in inline
+ * script content causes the HTML parser to close the script tag prematurely,
+ * breaking page rendering. `JSON.stringify` does not perform this escape by
+ * default, so a targeted replacement is applied after serialization.
+ */
+export function buildGlobalInjectorMapScript(triggers) {
+    const map = buildGlobalInjectorMap(triggers);
+    return JSON.stringify(map).replace(/<\/script/gi, '<\\/script');
 }
-function buildGlobalInjectorBootstrapContent(globalInjectorModuleSpecifier) {
-  return `import { initGlobalInjector } from ${JSON.stringify(globalInjectorModuleSpecifier)};
+/**
+ * Builds the module source that boots the global lazy injector on the client.
+ * Emitted once per page alongside the `ecopages/global-injector-map` script block.
+ */
+export function buildGlobalInjectorBootstrapContent(globalInjectorModuleSpecifier) {
+    return `import { initGlobalInjector } from ${JSON.stringify(globalInjectorModuleSpecifier)};
 
 function pruneStaleTriggerMaps() {
 	const mapScripts = Array.from(document.querySelectorAll('script[type="ecopages/global-injector-map"]'));
@@ -74,7 +92,3 @@ globalScope.__ecoGlobalInjectorCleanup = () => {
 	injector.cleanup();
 };`;
 }
-export {
-  buildGlobalInjectorBootstrapContent,
-  buildGlobalInjectorMapScript
-};

package/src/eco/lazy-injector-map.js

@@ -1,70 +1,100 @@
+/**
+ * Normalizes a comma-separated scripts string into absolute script URLs.
+ *
+ * @param scripts Comma-separated script paths.
+ * @returns Normalized script path list.
+ */
 function normalizeScripts(scripts) {
-  return scripts.split(",").map((scriptPath) => scriptPath.trim()).filter(Boolean).map((scriptPath) => {
-    if (scriptPath.startsWith("/")) {
-      return scriptPath;
-    }
-    const normalizedRelativePath = scriptPath.replace(/^\/+/, "").replace(/^(\.\/)+/, "");
-    return `/${normalizedRelativePath}`;
-  });
+    return scripts
+        .split(',')
+        .map((scriptPath) => scriptPath.trim())
+        .filter(Boolean)
+        .map((scriptPath) => {
+        if (scriptPath.startsWith('/')) {
+            return scriptPath;
+        }
+        const normalizedRelativePath = scriptPath.replace(/^\/+/, '').replace(/^(\.\/)+/, '');
+        return `/${normalizedRelativePath}`;
+    });
 }
+/**
+ * Deduplicates comma-separated values while preserving first-seen order.
+ *
+ * @param values CSV value list.
+ * @returns A single normalized CSV string.
+ */
 function dedupeCsvValues(values) {
-  const seen = /* @__PURE__ */ new Set();
-  for (const value of values) {
-    for (const token of value.split(",").map((part) => part.trim()).filter(Boolean)) {
-      seen.add(token);
+    const seen = new Set();
+    for (const value of values) {
+        for (const token of value
+            .split(',')
+            .map((part) => part.trim())
+            .filter(Boolean)) {
+            seen.add(token);
+        }
     }
-  }
-  return Array.from(seen).join(",");
+    return Array.from(seen).join(',');
 }
+/**
+ * Builds a scripts-injector map config from resolved lazy script groups.
+ *
+ * @param lazyGroups Lazy script groups resolved during dependency processing.
+ * @returns Injector map config keyed by lazy trigger.
+ */
 function buildInjectorMap(lazyGroups) {
-  const map = {};
-  for (const group of lazyGroups) {
-    const scripts = normalizeScripts(group.scripts);
-    const lazy = group.lazy;
-    if ("on:idle" in lazy) {
-      map["on:idle"] = {
-        scripts: [...map["on:idle"]?.scripts ?? [], ...scripts]
-      };
-      continue;
-    }
-    if ("on:interaction" in lazy) {
-      const currentValue = map["on:interaction"]?.value;
-      const nextValue = lazy["on:interaction"];
-      map["on:interaction"] = {
-        value: typeof currentValue === "string" ? dedupeCsvValues([currentValue, nextValue]) : nextValue,
-        scripts: [...map["on:interaction"]?.scripts ?? [], ...scripts]
-      };
-      continue;
-    }
-    if ("on:visible" in lazy) {
-      const currentValue = map["on:visible"]?.value;
-      const currentThreshold = typeof currentValue === "string" ? currentValue : void 0;
-      const nextValue = lazy["on:visible"];
-      map["on:visible"] = {
-        ...nextValue === true ? currentThreshold ? { value: currentThreshold } : {} : { value: String(nextValue) },
-        scripts: [...map["on:visible"]?.scripts ?? [], ...scripts]
-      };
-      continue;
+    const map = {};
+    for (const group of lazyGroups) {
+        const scripts = normalizeScripts(group.scripts);
+        const lazy = group.lazy;
+        if ('on:idle' in lazy) {
+            map['on:idle'] = {
+                scripts: [...(map['on:idle']?.scripts ?? []), ...scripts],
+            };
+            continue;
+        }
+        if ('on:interaction' in lazy) {
+            const currentValue = map['on:interaction']?.value;
+            const nextValue = lazy['on:interaction'];
+            map['on:interaction'] = {
+                value: typeof currentValue === 'string' ? dedupeCsvValues([currentValue, nextValue]) : nextValue,
+                scripts: [...(map['on:interaction']?.scripts ?? []), ...scripts],
+            };
+            continue;
+        }
+        if ('on:visible' in lazy) {
+            const currentValue = map['on:visible']?.value;
+            const currentThreshold = typeof currentValue === 'string' ? currentValue : undefined;
+            const nextValue = lazy['on:visible'];
+            map['on:visible'] = {
+                ...(nextValue === true
+                    ? currentThreshold
+                        ? { value: currentThreshold }
+                        : {}
+                    : { value: String(nextValue) }),
+                scripts: [...(map['on:visible']?.scripts ?? []), ...scripts],
+            };
+            continue;
+        }
+        throw new Error(`Invalid lazy options: must specify on:idle, on:interaction, or on:visible. Received: ${JSON.stringify(lazy)}`);
     }
-    throw new Error(
-      `Invalid lazy options: must specify on:idle, on:interaction, or on:visible. Received: ${JSON.stringify(lazy)}`
-    );
-  }
-  for (const key of Object.keys(map)) {
-    const scripts = map[key]?.scripts;
-    if (scripts) {
-      map[key] = {
-        ...map[key],
-        scripts: Array.from(new Set(scripts))
-      };
+    for (const key of Object.keys(map)) {
+        const scripts = map[key]?.scripts;
+        if (scripts) {
+            map[key] = {
+                ...map[key],
+                scripts: Array.from(new Set(scripts)),
+            };
+        }
     }
-  }
-  return map;
+    return map;
 }
-function buildInjectorMapScript(lazyGroups) {
-  const map = buildInjectorMap(lazyGroups);
-  return JSON.stringify(map).replace(/<\/script/gi, "<\\/script");
+/**
+ * Creates a safe JSON payload string for `<script type="ecopages/injector-map">`.
+ *
+ * @param lazyGroups Lazy script groups resolved during dependency processing.
+ * @returns Escaped JSON string safe for inline script embedding.
+ */
+export function buildInjectorMapScript(lazyGroups) {
+    const map = buildInjectorMap(lazyGroups);
+    return JSON.stringify(map).replace(/<\/script/gi, '<\\/script');
 }
-export {
-  buildInjectorMapScript
-};

package/src/eco/module-dependencies.js

@@ -1,49 +1,57 @@
 function normalizeImports(imports) {
-  if (!imports || imports.length === 0) {
-    return void 0;
-  }
-  const normalized = Array.from(new Set(imports.map((entry) => entry.trim()).filter((entry) => entry.length > 0)));
-  return normalized.length > 0 ? normalized : void 0;
+    if (!imports || imports.length === 0) {
+        return undefined;
+    }
+    const normalized = Array.from(new Set(imports.map((entry) => entry.trim()).filter((entry) => entry.length > 0)));
+    return normalized.length > 0 ? normalized : undefined;
 }
-function parseModuleDeclaration(value) {
-  const source = value.trim();
-  if (source.length === 0) {
-    throw new Error("Module declaration cannot be empty");
-  }
-  const openBraceIndex = source.indexOf("{");
-  if (openBraceIndex < 0) {
-    return { from: source };
-  }
-  const closeBraceIndex = source.lastIndexOf("}");
-  if (closeBraceIndex !== source.length - 1 || closeBraceIndex <= openBraceIndex) {
-    throw new Error(`Invalid module declaration '${value}'`);
-  }
-  const from = source.slice(0, openBraceIndex).trim();
-  if (from.length === 0) {
-    throw new Error(`Invalid module declaration '${value}'`);
-  }
-  const importsSlice = source.slice(openBraceIndex + 1, closeBraceIndex);
-  const imports = normalizeImports(importsSlice.split(","));
-  return {
-    from,
-    imports
-  };
+/**
+ * Parses a module grammar declaration into normalized object form.
+ *
+ * Supported input examples:
+ * - `react-aria-components`
+ * - `react-aria-components{Table,Select}`
+ */
+export function parseModuleDeclaration(value) {
+    const source = value.trim();
+    if (source.length === 0) {
+        throw new Error('Module declaration cannot be empty');
+    }
+    const openBraceIndex = source.indexOf('{');
+    if (openBraceIndex < 0) {
+        return { from: source };
+    }
+    const closeBraceIndex = source.lastIndexOf('}');
+    if (closeBraceIndex !== source.length - 1 || closeBraceIndex <= openBraceIndex) {
+        throw new Error(`Invalid module declaration '${value}'`);
+    }
+    const from = source.slice(0, openBraceIndex).trim();
+    if (from.length === 0) {
+        throw new Error(`Invalid module declaration '${value}'`);
+    }
+    const importsSlice = source.slice(openBraceIndex + 1, closeBraceIndex);
+    const imports = normalizeImports(importsSlice.split(','));
+    return {
+        from,
+        imports,
+    };
 }
-function normalizeModuleDeclarations(modules) {
-  const declarations = modules ?? [];
-  const output = [];
-  const seen = /* @__PURE__ */ new Set();
-  for (const declaration of declarations) {
-    const normalized = parseModuleDeclaration(declaration);
-    const key = `${normalized.from}::${(normalized.imports ?? []).join(",")}`;
-    if (!seen.has(key)) {
-      seen.add(key);
-      output.push(normalized);
+/**
+ * Normalizes and deduplicates module declarations from `modules`.
+ *
+ * Returns canonical object declarations suitable for downstream bundling logic.
+ */
+export function normalizeModuleDeclarations(modules) {
+    const declarations = modules ?? [];
+    const output = [];
+    const seen = new Set();
+    for (const declaration of declarations) {
+        const normalized = parseModuleDeclaration(declaration);
+        const key = `${normalized.from}::${(normalized.imports ?? []).join(',')}`;
+        if (!seen.has(key)) {
+            seen.add(key);
+            output.push(normalized);
+        }
     }
-  }
-  return output;
+    return output;
 }
-export {
-  normalizeModuleDeclarations,
-  parseModuleDeclaration
-};

package/src/eco/page-layout-normalization.d.ts

@@ -0,0 +1,21 @@
+import type { EcoComponentConfig, EcoComponentDependencies, EcoPageLayoutEntry, EcoPageLayouts } from '../types/public-types.js';
+/**
+ * Normalizes `layout` page options to an outer→inner stack of layout entries.
+ */
+export declare function normalizePageLayouts<E>(layout?: EcoPageLayouts<E>): EcoPageLayoutEntry<E>[];
+/**
+ * Merges layout components into `dependencies.components` without duplicates.
+ */
+export declare function mergeLayoutDependencies(dependencies: EcoComponentDependencies | undefined, layoutEntries: EcoPageLayoutEntry[]): EcoComponentDependencies | undefined;
+/**
+ * Writes normalized layout metadata onto a page `config`.
+ */
+export declare function applyPageLayoutConfig(pageConfig: EcoComponentConfig, layoutEntries: EcoPageLayoutEntry[]): void;
+/**
+ * Migrates MDX-exported `config.layout` values onto normalized layout metadata.
+ *
+ * @remarks
+ * `eco.page({ layout })` already normalizes at factory time. MDX modules that
+ * export `config.layout` directly still need this import-time migration.
+ */
+export declare function ensurePageConfigLayouts(config: EcoComponentConfig | undefined): EcoComponentConfig | undefined;

package/src/eco/page-layout-normalization.js

@@ -0,0 +1,69 @@
+function isLayoutSpecObject(spec) {
+    return typeof spec === 'object' && spec !== null && 'component' in spec;
+}
+/**
+ * Normalizes `layout` page options to an outer→inner stack of layout entries.
+ */
+export function normalizePageLayouts(layout) {
+    if (!layout) {
+        return [];
+    }
+    const specs = Array.isArray(layout) ? layout : [layout];
+    return specs.map((spec) => {
+        if (isLayoutSpecObject(spec)) {
+            return {
+                component: spec.component,
+                props: spec.props,
+            };
+        }
+        return {
+            component: spec,
+        };
+    });
+}
+/**
+ * Merges layout components into `dependencies.components` without duplicates.
+ */
+export function mergeLayoutDependencies(dependencies, layoutEntries) {
+    if (layoutEntries.length === 0) {
+        return dependencies;
+    }
+    const mergedComponents = [...(dependencies?.components ?? [])];
+    for (const entry of layoutEntries) {
+        if (!mergedComponents.includes(entry.component)) {
+            mergedComponents.push(entry.component);
+        }
+    }
+    return {
+        ...dependencies,
+        components: mergedComponents,
+    };
+}
+/**
+ * Writes normalized layout metadata onto a page `config`.
+ */
+export function applyPageLayoutConfig(pageConfig, layoutEntries) {
+    if (layoutEntries.length === 0) {
+        return;
+    }
+    pageConfig.layouts = layoutEntries.map((entry) => entry.component);
+    pageConfig.layoutEntries = layoutEntries;
+}
+/**
+ * Migrates MDX-exported `config.layout` values onto normalized layout metadata.
+ *
+ * @remarks
+ * `eco.page({ layout })` already normalizes at factory time. MDX modules that
+ * export `config.layout` directly still need this import-time migration.
+ */
+export function ensurePageConfigLayouts(config) {
+    if (!config || (config.layouts && config.layouts.length > 0)) {
+        return config;
+    }
+    const legacyLayout = config.layout;
+    if (!legacyLayout) {
+        return config;
+    }
+    applyPageLayoutConfig(config, normalizePageLayouts(legacyLayout));
+    return config;
+}

package/src/env.d.ts

@@ -3,6 +3,8 @@ interface EcopagesEnv {
 	ECOPAGES_HOSTNAME: string;
 	ECOPAGES_PORT: string;
 	ECOPAGES_LOGGER_DEBUG: 'true' | 'false';
+	/** When `true`, emits startup phase timings to stderr. Also enabled when `ECOPAGES_LOGGER_DEBUG=true`. */
+	ECOPAGES_STARTUP_TRACE?: 'true' | 'false';
 }
 
 declare global {

package/src/errors/http-error.d.ts

@@ -14,6 +14,14 @@ export declare class HttpError extends Error {
     readonly status: number;
     readonly details?: HttpErrorDetails;
     constructor(status: number, message: string, details?: HttpErrorDetails);
+    /**
+     * Detects HttpError across bundle boundaries where `instanceof` can fail.
+     *
+     * @remarks
+     * Page modules may load a different class identity than core runtime code.
+     * Prefer this over `instanceof` when catching errors from app page bundles.
+     */
+    static isHttpError(error: unknown): error is HttpError;
     /**
      * Serialize error to JSON for API responses.
      */

package/src/errors/http-error.js

@@ -1,50 +1,67 @@
-class HttpError extends Error {
-  status;
-  details;
-  constructor(status, message, details) {
-    super(message);
-    this.name = "HttpError";
-    this.status = status;
-    this.details = details;
-  }
-  /**
-   * Serialize error to JSON for API responses.
-   */
-  toJSON() {
-    const json = {
-      error: this.message,
-      status: this.status
-    };
-    if (this.details) {
-      json.details = this.details;
-    }
-    return json;
-  }
-  /**
-   * Create a Response object from this error.
-   */
-  toResponse() {
-    return Response.json(this.toJSON(), { status: this.status });
-  }
-  static BadRequest(message = "Bad Request", details) {
-    return new HttpError(400, message, details);
-  }
-  static Unauthorized(message = "Unauthorized") {
-    return new HttpError(401, message);
-  }
-  static Forbidden(message = "Forbidden") {
-    return new HttpError(403, message);
-  }
-  static NotFound(message = "Not Found") {
-    return new HttpError(404, message);
-  }
-  static Conflict(message = "Conflict", details) {
-    return new HttpError(409, message, details);
-  }
-  static InternalServerError(message = "Internal Server Error") {
-    return new HttpError(500, message);
-  }
+/**
+ * HTTP error class for structured error handling in route handlers.
+ * Provides static factory methods for common HTTP error responses.
+ */
+export class HttpError extends Error {
+    status;
+    details;
+    constructor(status, message, details) {
+        super(message);
+        this.name = 'HttpError';
+        this.status = status;
+        this.details = details;
+    }
+    /**
+     * Detects HttpError across bundle boundaries where `instanceof` can fail.
+     *
+     * @remarks
+     * Page modules may load a different class identity than core runtime code.
+     * Prefer this over `instanceof` when catching errors from app page bundles.
+     */
+    static isHttpError(error) {
+        if (error instanceof HttpError) {
+            return true;
+        }
+        return (typeof error === 'object' &&
+            error !== null &&
+            error.name === 'HttpError' &&
+            typeof error.status === 'number');
+    }
+    /**
+     * Serialize error to JSON for API responses.
+     */
+    toJSON() {
+        const json = {
+            error: this.message,
+            status: this.status,
+        };
+        if (this.details) {
+            json.details = this.details;
+        }
+        return json;
+    }
+    /**
+     * Create a Response object from this error.
+     */
+    toResponse() {
+        return Response.json(this.toJSON(), { status: this.status });
+    }
+    static BadRequest(message = 'Bad Request', details) {
+        return new HttpError(400, message, details);
+    }
+    static Unauthorized(message = 'Unauthorized') {
+        return new HttpError(401, message);
+    }
+    static Forbidden(message = 'Forbidden') {
+        return new HttpError(403, message);
+    }
+    static NotFound(message = 'Not Found') {
+        return new HttpError(404, message);
+    }
+    static Conflict(message = 'Conflict', details) {
+        return new HttpError(409, message, details);
+    }
+    static InternalServerError(message = 'Internal Server Error') {
+        return new HttpError(500, message);
+    }
 }
-export {
-  HttpError
-};

package/src/errors/index.d.ts

@@ -1,3 +1,4 @@
 export { HttpError } from './http-error.js';
 export type { HttpErrorDetails, HttpErrorJson } from './http-error.js';
 export { LocalsAccessError } from './locals-access-error.js';
+export { UndeclaredComponentDependencyError, getUndeclaredComponentDependencyMessage, } from './undeclared-component-dependency-error.js';

package/src/errors/index.js

@@ -1,6 +1,3 @@
-import { HttpError } from "./http-error.js";
-import { LocalsAccessError } from "./locals-access-error.js";
-export {
-  HttpError,
-  LocalsAccessError
-};
+export { HttpError } from './http-error.js';
+export { LocalsAccessError } from './locals-access-error.js';
+export { UndeclaredComponentDependencyError, getUndeclaredComponentDependencyMessage, } from './undeclared-component-dependency-error.js';

package/src/errors/locals-access-error.js

@@ -1,9 +1,6 @@
-class LocalsAccessError extends Error {
-  name = "LocalsAccessError";
-  constructor(message) {
-    super(message);
-  }
+export class LocalsAccessError extends Error {
+    name = 'LocalsAccessError';
+    constructor(message) {
+        super(message);
+    }
 }
-export {
-  LocalsAccessError
-};

package/src/errors/undeclared-component-dependency-error.d.ts

@@ -0,0 +1,11 @@
+export declare function getUndeclaredComponentDependencyMessage(parentComponentFile?: string): string;
+/**
+ * Thrown when `dependencies.components` contains a plain function or component
+ * without plugin-bound component identity attribution.
+ */
+export declare class UndeclaredComponentDependencyError extends Error {
+    name: string;
+    /** Parent component file path when the invalid entry was declared. */
+    readonly parentComponentFile?: string;
+    constructor(parentComponentFile?: string);
+}