@ecopages/core 0.2.0-alpha.1 → 0.2.0-alpha.11

package/src/services/assets/asset-processing-service/asset-processing.service.d.ts

@@ -0,0 +1,120 @@
+import type { EcoPagesAppConfig, IHmrManager } from '../../../types/internal-types.js';
+import type { AssetDefinition, AssetKind, AssetSource, ProcessedAsset } from './assets.types.js';
+import { ProcessorRegistry } from './processor.registry.js';
+/**
+ * Processes declared component and page asset dependencies for one app instance.
+ *
+ * @remarks
+ * This service is the shared bridge between dependency declarations and emitted
+ * runtime-ready assets. It owns deduplication, processor dispatch, cache reuse,
+ * output URL normalization, and production gzip preparation so route rendering
+ * and HMR flows do not need to understand processor-specific behavior.
+ */
+export declare class AssetProcessingService {
+    static readonly RESOLVED_ASSETS_DIR = "assets";
+    private registry;
+    private hmrManager?;
+    private cache;
+    private readonly config;
+    /**
+     * Creates the asset-processing service bound to one finalized app config.
+     */
+    constructor(config: EcoPagesAppConfig);
+    /**
+     * Set the HMR manager for the asset processing service.
+     * @param hmrManager The HMR manager to set.
+     */
+    setHmrManager(hmrManager: IHmrManager): void;
+    getHmrManager(): IHmrManager | undefined;
+    /**
+     * Register a processor for a specific asset kind and source.
+     * @param kind The asset kind.
+     * @param variant The asset source.
+     * @param processor The processor to register.
+     */
+    registerProcessor(kind: AssetKind, variant: AssetSource, processor: any): void;
+    /**
+     * Processes one dependency list into normalized emitted assets.
+     *
+     * @remarks
+     * Dependencies are deduplicated before processor execution so repeated
+     * declarations across the render tree reuse the same emitted outputs and cache
+     * entries.
+     */
+    processDependencies(deps: AssetDefinition[], key: string): Promise<ProcessedAsset[]>;
+    /**
+     * Removes duplicate dependency declarations while preserving first-seen order.
+     */
+    private deduplicateDependencies;
+    /**
+     * Builds the cache signature fragment for script dependencies that can vary by
+     * bundling policy.
+     */
+    private getScriptDependencyBuildSignature;
+    /**
+     * Derives the stable cache key for one dependency declaration.
+     */
+    private getDependencyKey;
+    /**
+     * Hashes content used in dependency cache and signature keys.
+     */
+    private generateHash;
+    /**
+     * Processes deduplicated dependencies grouped by processor type.
+     *
+     * @remarks
+     * Grouping keeps cache and processor behavior isolated by asset kind/source
+     * pair, while still allowing the overall dependency set to resolve in
+     * parallel.
+     */
+    private processDependenciesParallel;
+    /**
+     * Groups dependencies by processor bucket.
+     */
+    private groupDependenciesByType;
+    /**
+     * Converts a dist-local file path into its public URL.
+     */
+    private getSrcUrl;
+    /**
+     * Normalizes the public source URL for one processed asset.
+     */
+    private resolveProcessedAssetSrcUrl;
+    /**
+     * Returns whether a value should be interpreted as a filesystem path instead
+     * of an already-public URL.
+     */
+    private isFilesystemPath;
+    /**
+     * Applies post-processing for emitted production assets.
+     *
+     * @remarks
+     * Current optimization is intentionally conservative: only generated CSS and
+     * JavaScript files inside the app dist directory are gzipped.
+     */
+    private optimizeDependencies;
+    /**
+     * Returns the cached processed asset for a dependency key when available.
+     */
+    private getCachedAsset;
+    /**
+     * Stores one processed asset in the dependency cache.
+     */
+    private setCachedAsset;
+    /**
+     * Clears all cached processed assets.
+     */
+    clearCache(): void;
+    /**
+     * Removes cached assets that were produced from the given file path.
+     */
+    invalidateCacheForFile(filepath: string): void;
+    /**
+     * Creates a service prewired with the default core processors.
+     */
+    static createWithDefaultProcessors(appConfig: EcoPagesAppConfig): AssetProcessingService;
+    /**
+     * Returns the processor registry owned by this service.
+     */
+    getRegistry(): ProcessorRegistry;
+}

package/src/services/{asset-processing-service → assets/asset-processing-service}/asset-processing.service.js

@@ -1,25 +1,29 @@
 import path from "node:path";
-import { RESOLVED_ASSETS_DIR } from "../../constants";
-import { appLogger } from "../../global/app-logger";
-import { rapidhash } from "../../utils/hash";
+import { RESOLVED_ASSETS_DIR } from "../../../config/constants.js";
+import { appLogger } from "../../../global/app-logger.js";
+import { rapidhash } from "../../../utils/hash.js";
 import { fileSystem } from "@ecopages/file-system";
-import { isHmrAware } from "./processor.interface";
-import { ProcessorRegistry } from "./processor.registry";
+import { isHmrAware } from "./processor.interface.js";
+import { ProcessorRegistry } from "./processor.registry.js";
 import {
   ContentScriptProcessor,
   ContentStylesheetProcessor,
   FileScriptProcessor,
   FileStylesheetProcessor,
   NodeModuleScriptProcessor
-} from "./processors";
+} from "./processors/index.js";
 class AssetProcessingService {
-  constructor(config) {
-    this.config = config;
-  }
   static RESOLVED_ASSETS_DIR = RESOLVED_ASSETS_DIR;
   registry = new ProcessorRegistry();
   hmrManager;
   cache = /* @__PURE__ */ new Map();
+  config;
+  /**
+   * Creates the asset-processing service bound to one finalized app config.
+   */
+  constructor(config) {
+    this.config = config;
+  }
   /**
    * Set the HMR manager for the asset processing service.
    * @param hmrManager The HMR manager to set.
@@ -47,6 +51,14 @@ class AssetProcessingService {
     }
     this.registry.register(kind, variant, processor);
   }
+  /**
+   * Processes one dependency list into normalized emitted assets.
+   *
+   * @remarks
+   * Dependencies are deduplicated before processor execution so repeated
+   * declarations across the render tree reuse the same emitted outputs and cache
+   * entries.
+   */
   async processDependencies(deps, key) {
     const depsDir = path.join(this.config.absolutePaths.distDir, RESOLVED_ASSETS_DIR);
     fileSystem.ensureDir(depsDir);
@@ -55,6 +67,9 @@ class AssetProcessingService {
     await this.optimizeDependencies(results);
     return results;
   }
+  /**
+   * Removes duplicate dependency declarations while preserving first-seen order.
+   */
   deduplicateDependencies(deps) {
     const seen = /* @__PURE__ */ new Map();
     for (const dep of deps) {
@@ -65,6 +80,10 @@ class AssetProcessingService {
     }
     return Array.from(seen.values());
   }
+  /**
+   * Builds the cache signature fragment for script dependencies that can vary by
+   * bundling policy.
+   */
   getScriptDependencyBuildSignature(dep) {
     if (dep.kind !== "script") {
       return void 0;
@@ -81,6 +100,9 @@ class AssetProcessingService {
     };
     return this.generateHash(JSON.stringify(signature));
   }
+  /**
+   * Derives the stable cache key for one dependency declaration.
+   */
   getDependencyKey(dep) {
     const parts = [dep.kind, dep.source];
     if ("filepath" in dep) {
@@ -99,9 +121,20 @@ class AssetProcessingService {
     }
     return parts.join(":");
   }
+  /**
+   * Hashes content used in dependency cache and signature keys.
+   */
   generateHash(content) {
     return rapidhash(content).toString();
   }
+  /**
+   * Processes deduplicated dependencies grouped by processor type.
+   *
+   * @remarks
+   * Grouping keeps cache and processor behavior isolated by asset kind/source
+   * pair, while still allowing the overall dependency set to resolve in
+   * parallel.
+   */
   async processDependenciesParallel(deps, key) {
     const grouped = this.groupDependenciesByType(deps);
     const groupPromises = Object.entries(grouped).map(async ([, typeDeps]) => {
@@ -147,6 +180,9 @@ class AssetProcessingService {
     const allTypeResults = await Promise.all(groupPromises);
     return allTypeResults.flat();
   }
+  /**
+   * Groups dependencies by processor bucket.
+   */
   groupDependenciesByType(deps) {
     return deps.reduce(
       (acc, dep) => {
@@ -158,6 +194,9 @@ class AssetProcessingService {
       {}
     );
   }
+  /**
+   * Converts a dist-local file path into its public URL.
+   */
   getSrcUrl(filepath) {
     const distDir = this.config.absolutePaths.distDir;
     if (!filepath.startsWith(distDir)) return void 0;
@@ -165,6 +204,9 @@ class AssetProcessingService {
     const urlPath = relativePath.startsWith("/") ? relativePath : `/${relativePath}`;
     return urlPath.replace(/\\/g, "/");
   }
+  /**
+   * Normalizes the public source URL for one processed asset.
+   */
   resolveProcessedAssetSrcUrl(processed) {
     if (processed.srcUrl) {
       if (this.isFilesystemPath(processed.srcUrl)) {
@@ -179,6 +221,10 @@ class AssetProcessingService {
     }
     return void 0;
   }
+  /**
+   * Returns whether a value should be interpreted as a filesystem path instead
+   * of an already-public URL.
+   */
   isFilesystemPath(value) {
     if (value.startsWith("http://") || value.startsWith("https://") || value.startsWith("//")) {
       return false;
@@ -192,6 +238,13 @@ class AssetProcessingService {
     }
     return /^[A-Za-z]:\\/.test(value);
   }
+  /**
+   * Applies post-processing for emitted production assets.
+   *
+   * @remarks
+   * Current optimization is intentionally conservative: only generated CSS and
+   * JavaScript files inside the app dist directory are gzipped.
+   */
   async optimizeDependencies(processedAssets) {
     if (process.env.NODE_ENV !== "production") {
       return;
@@ -215,16 +268,38 @@ class AssetProcessingService {
       }
     }
   }
+  /**
+   * Returns the cached processed asset for a dependency key when available.
+   */
   getCachedAsset(dep, depKey) {
+    if (process.env.NODE_ENV !== "production" && dep.source === "file" && dep.kind === "stylesheet") {
+      return null;
+    }
     const cached = this.cache.get(depKey);
-    return cached?.asset ?? null;
+    if (!cached) {
+      return null;
+    }
+    if (cached.asset.filepath && !fileSystem.exists(cached.asset.filepath)) {
+      this.cache.delete(depKey);
+      return null;
+    }
+    return cached.asset;
   }
+  /**
+   * Stores one processed asset in the dependency cache.
+   */
   setCachedAsset(dep, depKey, asset) {
     this.cache.set(depKey, { asset });
   }
+  /**
+   * Clears all cached processed assets.
+   */
   clearCache() {
     this.cache.clear();
   }
+  /**
+   * Removes cached assets that were produced from the given file path.
+   */
   invalidateCacheForFile(filepath) {
     for (const [key, value] of this.cache.entries()) {
       if (value.asset.filepath === filepath) {
@@ -232,6 +307,9 @@ class AssetProcessingService {
       }
     }
   }
+  /**
+   * Creates a service prewired with the default core processors.
+   */
   static createWithDefaultProcessors(appConfig) {
     const service = new AssetProcessingService(appConfig);
     service.registerProcessor("script", "content", new ContentScriptProcessor({ appConfig }));
@@ -241,6 +319,9 @@ class AssetProcessingService {
     service.registerProcessor("stylesheet", "file", new FileStylesheetProcessor({ appConfig }));
     return service;
   }
+  /**
+   * Returns the processor registry owned by this service.
+   */
   getRegistry() {
     return this.registry;
   }

package/src/services/{asset-processing-service → assets/asset-processing-service}/asset.factory.d.ts

@@ -1,4 +1,4 @@
-import type { ContentScriptAsset, ContentStylesheetAsset, FileScriptAsset, FileStylesheetAsset, InlineContentScriptAsset, InlineContentStylesheetAsset, InlineFileScriptAsset, JsonScriptAsset, NodeModuleScriptAsset } from './assets.types';
+import type { ContentScriptAsset, ContentStylesheetAsset, FileScriptAsset, FileStylesheetAsset, InlineContentScriptAsset, InlineContentStylesheetAsset, InlineFileScriptAsset, JsonScriptAsset, NodeModuleScriptAsset } from './assets.types.js';
 type CreateAssetOptions<T> = Omit<T, 'kind' | 'source' | 'inline'>;
 export declare class AssetFactory {
     static readonly RESOLVED_ASSETS_DIR = "assets";

package/src/services/{asset-processing-service → assets/asset-processing-service}/asset.factory.js

@@ -1,5 +1,5 @@
-import { RESOLVED_ASSETS_DIR, RESOLVED_ASSETS_VENDORS_DIR } from "../../constants";
-import { deepMerge } from "../../utils/deep-merge";
+import { RESOLVED_ASSETS_DIR, RESOLVED_ASSETS_VENDORS_DIR } from "../../../config/constants.js";
+import { deepMerge } from "../../../utils/deep-merge.js";
 class AssetFactory {
   static RESOLVED_ASSETS_DIR = RESOLVED_ASSETS_DIR;
   static RESOLVED_ASSETS_VENDORS_DIR = RESOLVED_ASSETS_VENDORS_DIR;

package/src/services/{asset-processing-service → assets/asset-processing-service}/assets.types.d.ts

@@ -1,4 +1,4 @@
-import type { EcoBuildPlugin } from '../../build/build-types.js';
+import type { EcoBuildPlugin } from '../../../build/build-types.js';
 export type AssetSource = 'content' | 'file' | 'node-module';
 export type AssetKind = 'script' | 'stylesheet';
 export type AssetPosition = 'head' | 'body';
@@ -13,6 +13,7 @@ export interface ScriptAsset extends BaseAsset {
     inline?: boolean;
     bundle?: boolean;
     bundleOptions?: {
+        define?: Record<string, string>;
         minify?: boolean;
         external?: string[];
         naming?: string;

package/src/services/assets/asset-processing-service/browser-runtime-asset.factory.d.ts

@@ -0,0 +1,55 @@
+import type { EcoBuildPlugin } from '../../../build/build-types.js';
+import type { AssetDefinition } from './assets.types.js';
+import { type BrowserRuntimeEntryModuleConfig } from './browser-runtime-entry.factory.js';
+export declare const BROWSER_RUNTIME_SCRIPT_ATTRIBUTES: {
+    readonly type: "module";
+    readonly defer: "";
+};
+/**
+ * Builds the public vendor URL used for generated browser runtime assets.
+ */
+export declare function buildBrowserRuntimeAssetUrl(fileName: string): string;
+/**
+ * Declares a browser runtime script asset backed by one importable module.
+ *
+ * @remarks
+ * Runtime assets are emitted as excluded head scripts because integrations often
+ * need the bundler output and specifier registration without injecting the raw
+ * asset directly into HTML during dependency resolution.
+ */
+export declare function createBrowserRuntimeScriptAsset(options: {
+    importPath: string;
+    name: string;
+    fileName: string;
+    bundleOptions?: {
+        define?: Record<string, string>;
+        minify?: boolean;
+        external?: string[];
+        naming?: string;
+        plugins?: EcoBuildPlugin[];
+    };
+    attributes?: Record<string, string>;
+}): AssetDefinition;
+/**
+ * Creates a browser runtime asset from a generated re-export entry module.
+ *
+ * @remarks
+ * This is the shared "module list -> generated entry file -> runtime asset"
+ * path used by integrations that need browser-side runtime bundles without
+ * owning bespoke entry-file generation logic.
+ */
+export declare function createBrowserRuntimeModuleAsset(options: {
+    modules: BrowserRuntimeEntryModuleConfig[];
+    name: string;
+    fileName: string;
+    cacheDirName?: string;
+    rootDir?: string;
+    bundleOptions?: {
+        define?: Record<string, string>;
+        minify?: boolean;
+        external?: string[];
+        naming?: string;
+        plugins?: EcoBuildPlugin[];
+    };
+    attributes?: Record<string, string>;
+}): AssetDefinition;

package/src/services/assets/asset-processing-service/browser-runtime-asset.factory.js

@@ -0,0 +1,48 @@
+import { AssetFactory } from "./asset.factory.js";
+import {
+  createBrowserRuntimeEntryModule
+} from "./browser-runtime-entry.factory.js";
+const BROWSER_RUNTIME_SCRIPT_ATTRIBUTES = {
+  type: "module",
+  defer: ""
+};
+function buildBrowserRuntimeAssetUrl(fileName) {
+  return `/${AssetFactory.RESOLVED_ASSETS_VENDORS_DIR}/${fileName}`;
+}
+function createBrowserRuntimeScriptAsset(options) {
+  return AssetFactory.createNodeModuleScript({
+    position: "head",
+    importPath: options.importPath,
+    name: options.name,
+    excludeFromHtml: true,
+    bundleOptions: {
+      naming: options.fileName,
+      ...options.bundleOptions
+    },
+    attributes: {
+      ...BROWSER_RUNTIME_SCRIPT_ATTRIBUTES,
+      ...options.attributes ?? {}
+    }
+  });
+}
+function createBrowserRuntimeModuleAsset(options) {
+  const importPath = createBrowserRuntimeEntryModule({
+    modules: options.modules,
+    fileName: `${options.name}-entry.mjs`,
+    rootDir: options.rootDir,
+    cacheDirName: options.cacheDirName
+  });
+  return createBrowserRuntimeScriptAsset({
+    importPath,
+    name: options.name,
+    fileName: options.fileName,
+    bundleOptions: options.bundleOptions,
+    attributes: options.attributes
+  });
+}
+export {
+  BROWSER_RUNTIME_SCRIPT_ATTRIBUTES,
+  buildBrowserRuntimeAssetUrl,
+  createBrowserRuntimeModuleAsset,
+  createBrowserRuntimeScriptAsset
+};

package/src/services/assets/asset-processing-service/browser-runtime-entry.factory.d.ts

@@ -0,0 +1,20 @@
+export type BrowserRuntimeEntryModuleConfig = {
+    specifier: string;
+    defaultExport?: boolean;
+};
+/**
+ * Creates a generated ESM entry module that re-exports runtime modules through
+ * one stable file.
+ *
+ * @remarks
+ * Integrations use this helper when they need a browser runtime asset composed
+ * from multiple bare specifiers but do not want to own temporary file assembly
+ * logic themselves. The generated file lives under a cache directory inside the
+ * consuming app root so repeated runs can reuse the same location.
+ */
+export declare function createBrowserRuntimeEntryModule(options: {
+    modules: BrowserRuntimeEntryModuleConfig[];
+    fileName: string;
+    rootDir?: string;
+    cacheDirName?: string;
+}): string;

package/src/services/assets/asset-processing-service/browser-runtime-entry.factory.js

@@ -0,0 +1,41 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+function createBrowserRuntimeEntryModule(options) {
+  const rootDir = options.rootDir ?? process.cwd();
+  const artifactsDir = path.join(
+    rootDir,
+    "node_modules",
+    ".cache",
+    options.cacheDirName ?? "ecopages-browser-runtime"
+  );
+  fs.mkdirSync(artifactsDir, { recursive: true });
+  const requireFromRoot = createRequire(path.join(rootDir, "package.json"));
+  const seenExports = /* @__PURE__ */ new Set();
+  const statements = [];
+  for (const module of options.modules) {
+    if (module.defaultExport) {
+      statements.push(`import __ecopages_default_export__ from '${module.specifier}';`);
+      statements.push("export default __ecopages_default_export__;");
+    }
+    const exportNames = getModuleExportNames(module.specifier, requireFromRoot).filter(
+      (name) => !seenExports.has(name)
+    );
+    if (exportNames.length > 0) {
+      statements.push(`export { ${exportNames.join(", ")} } from '${module.specifier}';`);
+      for (const exportName of exportNames) {
+        seenExports.add(exportName);
+      }
+    }
+  }
+  const filePath = path.join(artifactsDir, options.fileName);
+  fs.writeFileSync(filePath, statements.join("\n"), "utf-8");
+  return filePath;
+}
+function getModuleExportNames(specifier, requireFromRoot) {
+  const moduleExports = requireFromRoot(specifier);
+  return Object.keys(moduleExports).filter((name) => name !== "__esModule" && name !== "default").filter((name) => /^[$A-Z_a-z][$\w]*$/.test(name)).sort();
+}
+export {
+  createBrowserRuntimeEntryModule
+};

package/src/services/assets/asset-processing-service/index.d.ts

@@ -0,0 +1,5 @@
+export * from './asset.factory.js';
+export * from './asset-processing.service.js';
+export * from './assets.types.js';
+export * from './browser-runtime-asset.factory.js';
+export * from './browser-runtime-entry.factory.js';

package/src/services/assets/asset-processing-service/index.js

@@ -0,0 +1,5 @@
+export * from "./asset.factory.js";
+export * from "./asset-processing.service.js";
+export * from "./assets.types.js";
+export * from "./browser-runtime-asset.factory.js";
+export * from "./browser-runtime-entry.factory.js";

package/src/services/{asset-processing-service → assets/asset-processing-service}/processor.interface.d.ts

@@ -1,5 +1,5 @@
-import type { IHmrManager } from '../../internal-types';
-import type { AssetDefinition, ProcessedAsset } from './assets.types';
+import type { IHmrManager } from '../../../types/internal-types.js';
+import type { AssetDefinition, ProcessedAsset } from './assets.types.js';
 /**
  * Base interface for asset processors.
  * Processors transform asset definitions into processed assets.

package/src/services/{asset-processing-service → assets/asset-processing-service}/processor.registry.d.ts

@@ -1,5 +1,5 @@
-import type { AssetKind, AssetSource } from './assets.types';
-import type { BaseProcessor } from './processors/base/base-processor';
+import type { AssetKind, AssetSource } from './assets.types.js';
+import type { BaseProcessor } from './processors/base/base-processor.js';
 export declare class ProcessorRegistry {
     private processors;
     register(kind: AssetKind, variant: AssetSource, processor: BaseProcessor<any>): void;

package/src/services/{asset-processing-service → assets/asset-processing-service}/processors/base/base-processor.d.ts

@@ -1,4 +1,4 @@
-import type { EcoPagesAppConfig } from '../../../../internal-types.js';
+import type { EcoPagesAppConfig } from '../../../../../types/internal-types.js';
 import type { BaseAsset, ProcessedAsset } from '../../assets.types.js';
 export declare abstract class BaseProcessor<T extends BaseAsset> {
     protected appConfig: EcoPagesAppConfig;

package/src/services/{asset-processing-service → assets/asset-processing-service}/processors/base/base-processor.js

@@ -1,7 +1,8 @@
 import path from "node:path";
-import { RESOLVED_ASSETS_DIR } from "../../../../constants.js";
-import { rapidhash } from "../../../../utils/hash.js";
-import { isDevelopmentRuntime, isProductionRuntime } from "../../../../utils/runtime.js";
+import { RESOLVED_ASSETS_DIR } from "../../../../../config/constants.js";
+import { rapidhash } from "../../../../../utils/hash.js";
+import { isDevelopmentRuntime, isProductionRuntime } from "../../../../../utils/runtime.js";
+import { fileSystem } from "@ecopages/file-system";
 class BaseProcessor {
   appConfig;
   /**
@@ -41,7 +42,11 @@ class BaseProcessor {
   }
   getOrProcess(cacheKey, processFn) {
     if (this.hasCacheFile(cacheKey)) {
-      return Promise.resolve(this.getCacheFile(cacheKey));
+      const cached = this.getCacheFile(cacheKey);
+      if (!cached.filepath || fileSystem.exists(cached.filepath)) {
+        return Promise.resolve(cached);
+      }
+      this.cache.delete(cacheKey);
     }
     const result = processFn();
     if (result instanceof Promise) {

package/src/services/{asset-processing-service → assets/asset-processing-service}/processors/base/base-script-processor.d.ts

@@ -1,8 +1,9 @@
-import type { EcoPagesAppConfig } from '../../../../internal-types';
-import type { EcoBuildPlugin } from '../../../../build/build-types.js';
-import type { ScriptAsset } from '../../assets.types';
-import { BaseProcessor } from './base-processor';
+import type { EcoPagesAppConfig } from '../../../../../types/internal-types.js';
+import type { EcoBuildPlugin } from '../../../../../build/build-types.js';
+import type { ScriptAsset } from '../../assets.types.js';
+import { BaseProcessor } from './base-processor.js';
 export declare abstract class BaseScriptProcessor<T extends ScriptAsset> extends BaseProcessor<T> {
+    private readonly browserBundleService;
     constructor({ appConfig }: {
         appConfig: EcoPagesAppConfig;
     });