@ecopages/core 0.2.0-alpha.27 → 0.2.0-alpha.28

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

@@ -0,0 +1,70 @@
+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}`;
+  });
+}
+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);
+    }
+  }
+  return Array.from(seen).join(",");
+}
+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;
+    }
+    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))
+      };
+    }
+  }
+  return map;
+}
+function buildInjectorMapScript(lazyGroups) {
+  const map = buildInjectorMap(lazyGroups);
+  return JSON.stringify(map).replace(/<\/script/gi, "<\\/script");
+}
+export {
+  buildInjectorMapScript
+};

package/src/eco/module-dependencies.d.ts

@@ -0,0 +1,18 @@
+export type ModuleDependencyDeclaration = {
+    from: string;
+    imports?: string[];
+};
+/**
+ * Parses a module grammar declaration into normalized object form.
+ *
+ * Supported input examples:
+ * - `react-aria-components`
+ * - `react-aria-components{Table,Select}`
+ */
+export declare function parseModuleDeclaration(value: string): ModuleDependencyDeclaration;
+/**
+ * Normalizes and deduplicates module declarations from `modules`.
+ *
+ * Returns canonical object declarations suitable for downstream bundling logic.
+ */
+export declare function normalizeModuleDeclarations(modules?: string[]): ModuleDependencyDeclaration[];

package/src/eco/module-dependencies.js

@@ -0,0 +1,49 @@
+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;
+}
+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);
+    }
+  }
+  return output;
+}
+export {
+  normalizeModuleDeclarations,
+  parseModuleDeclaration
+};

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

@@ -0,0 +1,31 @@
+export interface HttpErrorDetails {
+    [key: string]: unknown;
+}
+export interface HttpErrorJson {
+    error: string;
+    status: number;
+    details?: HttpErrorDetails;
+}
+/**
+ * HTTP error class for structured error handling in route handlers.
+ * Provides static factory methods for common HTTP error responses.
+ */
+export declare class HttpError extends Error {
+    readonly status: number;
+    readonly details?: HttpErrorDetails;
+    constructor(status: number, message: string, details?: HttpErrorDetails);
+    /**
+     * Serialize error to JSON for API responses.
+     */
+    toJSON(): HttpErrorJson;
+    /**
+     * Create a Response object from this error.
+     */
+    toResponse(): Response;
+    static BadRequest(message?: string, details?: HttpErrorDetails): HttpError;
+    static Unauthorized(message?: string): HttpError;
+    static Forbidden(message?: string): HttpError;
+    static NotFound(message?: string): HttpError;
+    static Conflict(message?: string, details?: HttpErrorDetails): HttpError;
+    static InternalServerError(message?: string): HttpError;
+}

package/src/errors/http-error.js

@@ -0,0 +1,50 @@
+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);
+  }
+}
+export {
+  HttpError
+};

package/src/errors/index.d.ts

@@ -0,0 +1,3 @@
+export { HttpError } from './http-error.js';
+export type { HttpErrorDetails, HttpErrorJson } from './http-error.js';
+export { LocalsAccessError } from './locals-access-error.js';

package/src/errors/index.js

@@ -0,0 +1,6 @@
+import { HttpError } from "./http-error.js";
+import { LocalsAccessError } from "./locals-access-error.js";
+export {
+  HttpError,
+  LocalsAccessError
+};

package/src/errors/locals-access-error.d.ts

@@ -0,0 +1,4 @@
+export declare class LocalsAccessError extends Error {
+    name: string;
+    constructor(message: string);
+}

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

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

package/src/global/app-logger.d.ts

@@ -0,0 +1,2 @@
+import { Logger } from '@ecopages/logger';
+export declare const appLogger: Logger;

package/src/global/app-logger.js

@@ -0,0 +1,6 @@
+import { Logger } from "@ecopages/logger";
+const debug = process.env.ECOPAGES_LOGGER_DEBUG === "true";
+const appLogger = new Logger("[@ecopages/core]", { debug });
+export {
+  appLogger
+};

package/src/hmr/client/hmr-runtime.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Ecopages HMR Runtime
+ * Injected into the browser to handle Hot Module Replacement updates.
+ */
+export {};

package/src/hmr/client/hmr-runtime.js

@@ -0,0 +1,117 @@
+import { getEcoNavigationRuntime } from "../../router/client/navigation-coordinator.js";
+(function() {
+  const WS_URL = "ws://" + location.host + "/_hmr";
+  let socket;
+  let reconnectAttempts = 0;
+  function connect() {
+    socket = new WebSocket(WS_URL);
+    socket.addEventListener("open", () => {
+      console.log("[ecopages] HMR Connected");
+      reconnectAttempts = 0;
+    });
+    socket.addEventListener("message", async (event) => {
+      try {
+        const payload = JSON.parse(event.data);
+        handleMessage(payload);
+      } catch (e) {
+        console.error("[ecopages] Invalid HMR message:", e);
+      }
+    });
+    socket.addEventListener("close", () => {
+      if (reconnectAttempts < 10) {
+        setTimeout(connect, 1e3 * 2 ** reconnectAttempts);
+        reconnectAttempts++;
+      }
+    });
+  }
+  async function handleMessage(payload) {
+    const navigationRuntime = getEcoNavigationRuntime(window);
+    switch (payload.type) {
+      case "reload":
+        await waitForNavigationToSettle(navigationRuntime);
+        location.reload();
+        break;
+      case "layout-update": {
+        await waitForNavigationToSettle(navigationRuntime);
+        if (await navigationRuntime.reloadCurrentPage({ clearCache: true, moduleUrl: getActiveHmrModuleUrl() })) {
+        } else {
+          location.reload();
+        }
+        break;
+      }
+      case "error":
+        console.error("[ecopages] HMR Error:", payload.message);
+        break;
+      case "update":
+        if (payload.path) {
+          await applyUpdate(payload.path, payload.timestamp);
+        }
+        break;
+      case "css-update":
+        if (payload.path) {
+          refreshStylesheet(payload.path);
+        }
+        break;
+    }
+  }
+  async function applyUpdate(path, timestamp) {
+    try {
+      const url = path + "?t=" + (timestamp || Date.now());
+      const handlers = window.__ECO_PAGES__?.hmrHandlers;
+      const navigationRuntime = getEcoNavigationRuntime(window);
+      await waitForNavigationToSettle(navigationRuntime);
+      if (handlers?.[path]) {
+        await handlers[path](url);
+        return;
+      }
+      await import(url);
+      if (await navigationRuntime.reloadCurrentPage({ clearCache: false })) {
+      }
+    } catch (e) {
+      console.error("[ecopages] Failed to apply HMR update:", e);
+    }
+  }
+  function getActiveHmrModuleUrl() {
+    const pageModule = window.__ECO_PAGES__?.page?.module;
+    if (pageModule && pageModule.includes("/assets/_hmr/")) {
+      return pageModule.split("?")[0];
+    }
+    const handlerPaths = Object.keys(window.__ECO_PAGES__?.hmrHandlers ?? {});
+    return handlerPaths[handlerPaths.length - 1];
+  }
+  async function waitForNavigationToSettle(navigationRuntime) {
+    if (!navigationRuntime.hasPendingNavigationTransaction()) {
+      return;
+    }
+    await new Promise((resolve) => {
+      const startedAt = performance.now();
+      const timeoutMs = 2e3;
+      const poll = () => {
+        if (!navigationRuntime.hasPendingNavigationTransaction()) {
+          resolve();
+          return;
+        }
+        if (performance.now() - startedAt >= timeoutMs) {
+          resolve();
+          return;
+        }
+        requestAnimationFrame(poll);
+      };
+      requestAnimationFrame(poll);
+    });
+  }
+  function refreshStylesheet(path) {
+    const filename = path.split("/").pop() || "";
+    const links = document.querySelectorAll('link[rel="stylesheet"]');
+    links.forEach((link) => {
+      const href = link.href;
+      if (href.includes(filename) || href.includes(path.replace(/^.*\/src\//, "/assets/"))) {
+        const url = new URL(href, location.origin);
+        url.searchParams.set("t", Date.now().toString());
+        link.href = url.toString();
+        console.log("[ecopages] CSS updated:", filename);
+      }
+    });
+  }
+  connect();
+})();

package/src/hmr/hmr-strategy.d.ts

@@ -0,0 +1,162 @@
+import type { ClientBridgeEvent } from '../types/public-types.js';
+/**
+ * HMR Strategy Pattern
+ *
+ * This module defines the base classes and types for Hot Module Replacement strategies.
+ * Each strategy handles a specific type of file change and determines how to process it.
+ *
+ * @module
+ * @example
+ * ```typescript
+ * class CustomHmrStrategy extends HmrStrategy {
+ *   readonly type = HmrStrategyType.INTEGRATION;
+ *
+ *   matches(filePath: string): boolean {
+ *     return filePath.endsWith('.custom');
+ *   }
+ *
+ *   async process(filePath: string): Promise<HmrAction> {
+ *     return {
+ *       type: 'broadcast',
+ *       events: [{ type: 'update', path: filePath, timestamp: Date.now() }],
+ *     };
+ *   }
+ * }
+ * ```
+ */
+/**
+ * Defines the category of an HMR strategy, which determines its execution priority.
+ * Strategies are evaluated in descending order: INTEGRATION → ASSET → SCRIPT → FALLBACK.
+ *
+ * @remarks
+ * The numeric values represent base priorities. Strategies can fine-tune their priority
+ * using the `priorityOffset` property.
+ */
+export declare const HmrStrategyType: {
+    /**
+     * Integration-specific strategies (React, Lit, etc.)
+     * Highest priority to allow framework-specific HMR handling.
+     */
+    readonly INTEGRATION: 100;
+    /**
+     * Asset processing strategies (CSS, images, etc.)
+     * High priority for specialized asset handling.
+     */
+    readonly ASSET: 50;
+    /**
+     * Generic script bundling strategies (JS/TS)
+     * Medium priority for standard script processing.
+     */
+    readonly SCRIPT: 25;
+    /**
+     * Fallback strategy for unhandled file types.
+     * Lowest priority, triggers full page reload.
+     */
+    readonly FALLBACK: 0;
+};
+export type HmrStrategyType = (typeof HmrStrategyType)[keyof typeof HmrStrategyType];
+/**
+ * Represents an action to be taken after processing a file change.
+ */
+export interface HmrAction {
+    /**
+     * Whether to broadcast an HMR event to connected clients.
+     */
+    type: 'broadcast' | 'none';
+    /**
+     * The HMR events to broadcast, if type is 'broadcast'.
+     * Multiple events may be broadcast in one action.
+     */
+    events?: ClientBridgeEvent[];
+}
+/**
+ * Base class for HMR strategies.
+ *
+ * Each strategy handles a specific type of file change and determines how to process it.
+ * Strategies are selected based on their priority (higher values are evaluated first) and
+ * whether they match the changed file path.
+ *
+ * @remarks
+ * Strategies are expected to be stateless and idempotent. The same file change
+ * should produce the same result when processed by the same strategy.
+ *
+ * @example
+ * ```typescript
+ * class MyAssetStrategy extends HmrStrategy {
+ *   readonly type = HmrStrategyType.ASSET;
+ *   readonly priorityOffset = 5;
+ *
+ *   matches(filePath: string): boolean {
+ *     return /\.(png|jpg|svg)$/.test(filePath);
+ *   }
+ *
+ *   async process(filePath: string): Promise<HmrAction> {
+ *     await this.optimizeImage(filePath);
+ *     return {
+ *       type: 'broadcast',
+ *       events: [{ type: 'update', path: filePath, timestamp: Date.now() }]
+ *     };
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class HmrStrategy {
+    /**
+     * The category of this strategy, determining its base priority.
+     */
+    abstract readonly type: HmrStrategyType;
+    /**
+     * Optional offset to fine-tune priority within the same category.
+     * Useful when multiple strategies share the same type.
+     *
+     * @defaultValue 0
+     */
+    readonly priorityOffset: number;
+    /**
+     * Computed priority for strategy selection.
+     * Higher values are evaluated first.
+     *
+     * @returns The sum of the strategy type and priority offset
+     */
+    get priority(): number;
+    /**
+     * Determines if this strategy can handle the given file path.
+     *
+     * @param filePath - Absolute path to the changed file
+     * @returns `true` when this strategy should process the file
+     *
+     * @example
+     * ```typescript
+     * matches(filePath: string): boolean {
+     *   return filePath.endsWith('.css');
+     * }
+     * ```
+     */
+    abstract matches(filePath: string): boolean;
+    /**
+     * Processes a file change and returns the action to take.
+     *
+     * This method may perform side effects such as:
+     * - Rebuilding files
+     * - Writing to disk
+     * - Transforming code
+     * - Updating caches
+     *
+     * @param filePath - Absolute path to the changed file
+     * @returns Action to take (broadcast event or none)
+     *
+     * @example
+     * ```typescript
+     * async process(filePath: string): Promise<HmrAction> {
+     *   const processed = await this.transform(filePath);
+     *   await Bun.write(outputPath, processed);
+     *
+     *   return {
+     *     type: 'broadcast',
+     *     events: [{ type: 'update', path: outputPath, timestamp: Date.now() }]
+     *   };
+     * }
+     * ```
+     */
+    abstract process(filePath: string): Promise<HmrAction>;
+}

package/src/hmr/hmr-strategy.js

@@ -0,0 +1,44 @@
+const HmrStrategyType = {
+  /**
+   * Integration-specific strategies (React, Lit, etc.)
+   * Highest priority to allow framework-specific HMR handling.
+   */
+  INTEGRATION: 100,
+  /**
+   * Asset processing strategies (CSS, images, etc.)
+   * High priority for specialized asset handling.
+   */
+  ASSET: 50,
+  /**
+   * Generic script bundling strategies (JS/TS)
+   * Medium priority for standard script processing.
+   */
+  SCRIPT: 25,
+  /**
+   * Fallback strategy for unhandled file types.
+   * Lowest priority, triggers full page reload.
+   */
+  FALLBACK: 0
+};
+class HmrStrategy {
+  /**
+   * Optional offset to fine-tune priority within the same category.
+   * Useful when multiple strategies share the same type.
+   *
+   * @defaultValue 0
+   */
+  priorityOffset = 0;
+  /**
+   * Computed priority for strategy selection.
+   * Higher values are evaluated first.
+   *
+   * @returns The sum of the strategy type and priority offset
+   */
+  get priority() {
+    return this.type + this.priorityOffset;
+  }
+}
+export {
+  HmrStrategy,
+  HmrStrategyType
+};

package/src/hmr/hmr.postcss.test.e2e.d.ts

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

package/src/hmr/hmr.postcss.test.e2e.js

@@ -0,0 +1,31 @@
+import { test, expect } from "@playwright/test";
+import { readFileSync } from "node:fs";
+import { writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+const FIXTURE_DIR = resolve(process.cwd(), "packages/core/__fixtures__/app");
+const TEST_CSS_FILE = resolve(FIXTURE_DIR, "src/pages/postcss-hmr.css");
+test.describe("HMR E2E PostCSS", () => {
+  test("should hot-update processor-owned CSS without a full page reload", async ({ page }) => {
+    const originalCss = readFileSync(TEST_CSS_FILE, "utf-8");
+    const title = page.locator(".postcss-title").first();
+    try {
+      await page.goto("/postcss-hmr", { waitUntil: "networkidle" });
+      await expect(title).toBeVisible();
+      const initialColor = await title.evaluate((el) => getComputedStyle(el).color);
+      expect(initialColor).toBeTruthy();
+      await page.evaluate(() => {
+        window.__postcssReloadProbe = "before-change";
+      });
+      const modifiedCss = originalCss.replace(".postcss-title {", ".postcss-title {\n	color: rgb(255, 0, 0);");
+      await writeFile(TEST_CSS_FILE, modifiedCss, { flush: true });
+      await expect.poll(async () => title.evaluate((el) => getComputedStyle(el).color), { timeout: 1e4 }).toBe("rgb(255, 0, 0)");
+      await expect(
+        page.evaluate(
+          () => window.__postcssReloadProbe ?? null
+        )
+      ).resolves.toBe("before-change");
+    } finally {
+      await writeFile(TEST_CSS_FILE, originalCss, { flush: true });
+    }
+  });
+});

package/src/hmr/hmr.test.e2e.d.ts

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

package/src/hmr/hmr.test.e2e.js

@@ -0,0 +1,43 @@
+import { test, expect } from "@playwright/test";
+import { readFileSync } from "node:fs";
+import { writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+const FIXTURE_DIR = resolve(process.cwd(), "packages/core/__fixtures__/app");
+const TEST_CSS_FILE = resolve(FIXTURE_DIR, "src/pages/index.css");
+test.describe("HMR E2E", () => {
+  test("should load page with .main-title element", async ({ page }) => {
+    await page.goto("/", { waitUntil: "networkidle" });
+    const title = page.locator(".main-title").first();
+    await expect(title).toBeVisible();
+  });
+  test("should connect to HMR WebSocket", async ({ page }) => {
+    const socketPromise = page.waitForEvent("websocket", {
+      predicate: (socket2) => socket2.url().endsWith("/_hmr"),
+      timeout: 1e4
+    });
+    await page.goto("/", { waitUntil: "networkidle" });
+    const socket = await socketPromise;
+    expect(socket.url()).toMatch(/\/_hmr$/);
+  });
+  test("should fall back to a full page reload when raw CSS file changes", async ({ page }) => {
+    const originalCss = readFileSync(TEST_CSS_FILE, "utf-8");
+    const title = page.locator(".main-title").first();
+    try {
+      await page.goto("/", { waitUntil: "networkidle" });
+      await expect(title).toBeVisible();
+      const initialColor = await title.evaluate((el) => getComputedStyle(el).color);
+      expect(initialColor).toBeTruthy();
+      const modifiedCss = originalCss.replace(".main-title {", ".main-title {\n	color: rgb(255, 0, 0);");
+      const reloadPromise = page.waitForEvent("framenavigated", {
+        predicate: (frame) => frame === page.mainFrame(),
+        timeout: 1e4
+      });
+      await writeFile(TEST_CSS_FILE, modifiedCss, { flush: true });
+      await reloadPromise;
+      await page.waitForLoadState("networkidle");
+      await expect.poll(async () => title.evaluate((el) => getComputedStyle(el).color), { timeout: 1e4 }).toBe("rgb(255, 0, 0)");
+    } finally {
+      await writeFile(TEST_CSS_FILE, originalCss, { flush: true });
+    }
+  });
+});