@ecopages/core 0.2.0-alpha.4 → 0.2.0-alpha.41

package/src/services/html/html-transformer.service.js

@@ -0,0 +1,287 @@
+import {
+  DefaultHtmlRewriterProvider
+} from "./html-rewriter-provider.service.js";
+import {
+  buildProcessedAssetDedupeKey,
+  dedupeProcessedAssets
+} from "../../route-renderer/orchestration/processed-asset-dedupe.js";
+class HtmlTransformerService {
+  processedDependencies = [];
+  pagePackage;
+  htmlRewriterProvider;
+  constructor(options = {}) {
+    this.htmlRewriterProvider = options.htmlRewriterProvider ?? new DefaultHtmlRewriterProvider();
+    if (options.htmlRewriterMode) {
+      this.htmlRewriterProvider.setMode(options.htmlRewriterMode);
+    }
+  }
+  /**
+   * Overrides the HTML rewriter runtime selection.
+   *
+   * This is intended for internal/runtime tests that need deterministic
+   * selection between native, worker-tools, and string fallback behavior.
+   *
+   * @param mode Requested runtime selection strategy.
+   */
+  setHtmlRewriterMode(mode) {
+    this.htmlRewriterProvider.setMode(mode);
+  }
+  formatAttributes(attrs) {
+    if (!attrs) return "";
+    return ` ${Object.entries(attrs).map(([key, value]) => `${key}="${value}"`).join(" ")}`;
+  }
+  generateScriptTag(dep) {
+    return dep.inline ? `<script${this.formatAttributes(dep.attributes)}>${dep.content}<\/script>` : `<script src="${dep.srcUrl}"${this.formatAttributes(dep.attributes)}><\/script>`;
+  }
+  generateStylesheetTag(dep) {
+    return dep.inline ? `<style${this.formatAttributes(dep.attributes)}>${dep.content}</style>` : `<link rel="stylesheet" href="${dep.srcUrl}"${this.formatAttributes(dep.attributes)}>`;
+  }
+  appendDependencies(element, dependencies) {
+    for (const dep of dependencies) {
+      const tag = dep.kind === "script" ? this.generateScriptTag(dep) : this.generateStylesheetTag(dep);
+      element.append(tag, { html: true });
+    }
+  }
+  buildDependencyTags(dependencies) {
+    return dependencies.map(
+      (dep) => dep.kind === "script" ? this.generateScriptTag(dep) : this.generateStylesheetTag(dep)
+    ).join("");
+  }
+  applyContributions(element, contributions, placement) {
+    for (const contribution of contributions) {
+      element[placement](contribution.html, { html: true });
+    }
+  }
+  /**
+   * Injects generated markup immediately before the closing HTML tag when it is
+   * present, or appends/prepends a fallback insertion otherwise.
+   */
+  injectBeforeClosingTag(html, tag, content) {
+    if (!content) {
+      return html;
+    }
+    const closingTag = `</${tag}>`;
+    const lowerHtml = html.toLowerCase();
+    const closingTagIndex = lowerHtml.lastIndexOf(closingTag);
+    if (closingTagIndex !== -1) {
+      return `${html.slice(0, closingTagIndex)}${content}${html.slice(closingTagIndex)}`;
+    }
+    if (tag === "head") {
+      return `${content}${html}`;
+    }
+    return `${html}${content}`;
+  }
+  injectAfterOpeningTag(html, tag, content) {
+    if (!content) {
+      return html;
+    }
+    const openingTag = new RegExp(`<${tag}\\b[^>]*>`, "i");
+    const match = html.match(openingTag);
+    if (!match || match.index === void 0) {
+      return tag === "head" ? `${content}${html}` : html.replace(/<body\b[^>]*>/i, (value) => `${value}${content}`);
+    }
+    const insertAt = match.index + match[0].length;
+    return `${html.slice(0, insertAt)}${content}${html.slice(insertAt)}`;
+  }
+  groupContributionsByPlacement(contributions) {
+    return {
+      headPrepend: contributions.filter((item) => item.placement === "head-prepend"),
+      headAppend: contributions.filter((item) => item.placement === "head-append"),
+      bodyPrepend: contributions.filter((item) => item.placement === "body-prepend"),
+      bodyAppend: contributions.filter((item) => item.placement === "body-append")
+    };
+  }
+  /**
+   * Replaces the current processed dependency set used during HTML finalization.
+   */
+  setProcessedDependencies(processedDependencies) {
+    this.pagePackage = void 0;
+    this.processedDependencies = processedDependencies;
+  }
+  /**
+   * Replaces the current structured page package used during HTML finalization.
+   */
+  setPagePackage(pagePackage) {
+    this.pagePackage = pagePackage;
+    this.processedDependencies = this.resolvePagePackageHtmlDependencies(pagePackage);
+  }
+  /**
+   * Returns the processed dependencies queued for the next transform pass.
+   */
+  getProcessedDependencies() {
+    return this.processedDependencies;
+  }
+  /**
+   * Returns the structured page package queued for the next transform pass.
+   */
+  getPagePackage() {
+    return this.pagePackage;
+  }
+  /**
+   * Applies attributes to the opening `<html>` tag when present.
+   */
+  applyAttributesToHtmlElement(html, attributes) {
+    const htmlTagMatch = html.match(/<html\b[^>]*>/i);
+    if (!htmlTagMatch || htmlTagMatch.index === void 0) {
+      return html;
+    }
+    const attrs = this.buildAttributeString(attributes);
+    if (attrs.length === 0) {
+      return html;
+    }
+    const injectionOffset = htmlTagMatch.index + htmlTagMatch[0].length - 1;
+    return `${html.slice(0, injectionOffset)}${attrs}${html.slice(injectionOffset)}`;
+  }
+  /**
+   * Applies attributes to the first element nested directly under `<body>`.
+   */
+  applyAttributesToFirstBodyElement(html, attributes) {
+    const bodyMatch = html.match(/<body\b[^>]*>/i);
+    if (!bodyMatch || bodyMatch.index === void 0) {
+      return html;
+    }
+    const bodyOpenEnd = bodyMatch.index + bodyMatch[0].length;
+    const afterBody = html.slice(bodyOpenEnd);
+    const firstTagMatch = afterBody.match(/^(\s*<)([a-zA-Z][a-zA-Z0-9:-]*)(\b[^>]*>)/);
+    if (!firstTagMatch || firstTagMatch.index === void 0) {
+      return html;
+    }
+    const attrs = this.buildAttributeString(attributes);
+    if (attrs.length === 0) {
+      return html;
+    }
+    const injectionOffset = bodyOpenEnd + firstTagMatch[1].length + firstTagMatch[2].length;
+    return `${html.slice(0, injectionOffset)}${attrs}${html.slice(injectionOffset)}`;
+  }
+  /**
+   * Applies attributes to the first element in a fragment or full-document HTML
+   * string.
+   */
+  applyAttributesToFirstElement(html, attributes) {
+    const firstTagMatch = html.match(/^(\s*<)([a-zA-Z][a-zA-Z0-9:-]*)(\b[^>]*>)/);
+    if (!firstTagMatch || firstTagMatch.index === void 0) {
+      return html;
+    }
+    const attrs = this.buildAttributeString(attributes);
+    if (attrs.length === 0) {
+      return html;
+    }
+    const injectionOffset = firstTagMatch[1].length + firstTagMatch[2].length;
+    return `${html.slice(0, injectionOffset)}${attrs}${html.slice(injectionOffset)}`;
+  }
+  /**
+   * Removes duplicate processed assets while preserving first-seen order.
+   *
+   * @remarks
+   * Dedupe keys include structural asset fields and HTML attributes so repeated
+   * orchestration passes can merge assets safely without collapsing distinct tag
+   * variants.
+   */
+  dedupeProcessedAssets(assets) {
+    return dedupeProcessedAssets(assets);
+  }
+  /**
+   * Injects the currently processed dependencies into an HTML response.
+   *
+   * @remarks
+   * Native or worker-tools HTML rewriter support is preferred when available. A
+   * string-based fallback remains in place for runtimes that cannot provide one
+   * of those rewriter implementations.
+   */
+  async transform(res, contributions = []) {
+    const { head, body } = this.groupDependenciesByPosition();
+    const { headPrepend, headAppend, bodyPrepend, bodyAppend } = this.groupContributionsByPlacement(contributions);
+    const htmlRewriter = await this.htmlRewriterProvider.createHtmlRewriter();
+    if (htmlRewriter) {
+      htmlRewriter.on("head", {
+        element: (element) => {
+          this.applyContributions(element, headPrepend, "prepend");
+          this.appendDependencies(element, head);
+          this.applyContributions(element, headAppend, "append");
+        }
+      }).on("body", {
+        element: (element) => {
+          this.applyContributions(element, bodyPrepend, "prepend");
+          this.appendDependencies(element, body);
+          this.applyContributions(element, bodyAppend, "append");
+        }
+      });
+      return htmlRewriter.transform(res);
+    }
+    const html = await res.text();
+    const headers = new Headers(res.headers);
+    const withHeadPrependedContent = this.injectAfterOpeningTag(
+      html,
+      "head",
+      headPrepend.map((item) => item.html).join("")
+    );
+    const withHeadDependencies = this.injectBeforeClosingTag(
+      withHeadPrependedContent,
+      "head",
+      `${this.buildDependencyTags(head)}${headAppend.map((item) => item.html).join("")}`
+    );
+    const withBodyPrependedContent = this.injectAfterOpeningTag(
+      withHeadDependencies,
+      "body",
+      bodyPrepend.map((item) => item.html).join("")
+    );
+    const transformedHtml = this.injectBeforeClosingTag(
+      withBodyPrependedContent,
+      "body",
+      `${this.buildDependencyTags(body)}${bodyAppend.map((item) => item.html).join("")}`
+    );
+    return new Response(transformedHtml, {
+      headers,
+      status: res.status,
+      statusText: res.statusText
+    });
+  }
+  /**
+   * Splits processed assets into head and body injection groups.
+   */
+  groupDependenciesByPosition() {
+    const dependencies = this.pagePackage ? this.resolvePagePackageHtmlDependencies(this.pagePackage) : this.processedDependencies;
+    return dependencies.reduce(
+      (acc, dep) => {
+        if (dep.kind === "script") {
+          if (dep.excludeFromHtml) return acc;
+          const position = dep.position || "body";
+          acc[position].push(dep);
+        } else if (dep.kind === "stylesheet") {
+          acc.head.push(dep);
+        }
+        return acc;
+      },
+      { head: [], body: [] }
+    );
+  }
+  resolvePagePackageHtmlDependencies(pagePackage) {
+    if (!pagePackage.pageBrowserGraph) {
+      return pagePackage.htmlAssets;
+    }
+    const chunkKeys = new Set(
+      pagePackage.pageBrowserGraph.chunkAssets.map((asset) => buildProcessedAssetDedupeKey(asset))
+    );
+    const graphKeys = new Set(
+      [...pagePackage.pageBrowserGraph.entryAssets, ...pagePackage.pageBrowserGraph.chunkAssets].map(
+        (asset) => buildProcessedAssetDedupeKey(asset)
+      )
+    );
+    const nonGraphHtmlAssets = pagePackage.htmlAssets.filter(
+      (asset) => !graphKeys.has(buildProcessedAssetDedupeKey(asset))
+    );
+    const entryHtmlAssets = pagePackage.pageBrowserGraph.entryAssets.filter(
+      (asset) => !chunkKeys.has(buildProcessedAssetDedupeKey(asset))
+    );
+    return dedupeProcessedAssets([...nonGraphHtmlAssets, ...entryHtmlAssets]);
+  }
+  /**
+   * Builds a serialized HTML attribute string from an attribute object.
+   */
+  buildAttributeString(attributes) {
+    return Object.entries(attributes).filter(([key, value]) => key.length > 0 && value.length > 0).map(([key, value]) => ` ${key}="${value}"`).join("");
+  }
+}
+export {
+  HtmlTransformerService
+};

package/src/services/invalidation/development-invalidation.service.d.ts

@@ -0,0 +1,74 @@
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+export type DevelopmentInvalidationCategory = 'public-asset' | 'additional-watch' | 'include-source' | 'route-source' | 'processor-owned-asset' | 'server-source' | 'other';
+/**
+ * Framework-owned invalidation plan for one changed file.
+ *
+ * @remarks
+ * This is the explicit invalidation matrix Workstream 4 needs. Watchers and
+ * runtime adapters consume this plan instead of encoding file-category rules in
+ * host-specific control flow.
+ */
+export interface DevelopmentInvalidationPlan {
+    category: DevelopmentInvalidationCategory;
+    invalidateServerModules: boolean;
+    refreshRoutes: boolean;
+    reloadBrowser: boolean;
+    delegateToHmr: boolean;
+    processorHandledAsset: boolean;
+}
+/**
+ * Framework-owned development invalidation service.
+ *
+ * @remarks
+ * This service centralizes two responsibilities:
+ * - file-change classification for watcher behavior
+ * - app-owned server-module invalidation versioning backed by the dev graph
+ *
+ * Hosts and watchers should ask this service what a file change means instead
+ * of deciding invalidation semantics inline.
+ */
+export declare class DevelopmentInvalidationService {
+    private readonly appConfig;
+    constructor(appConfig: EcoPagesAppConfig);
+    /**
+     * Returns the current app-owned server-module invalidation version.
+     */
+    getServerModuleInvalidationVersion(): number;
+    /**
+     * Invalidates the app-owned server-module graph.
+     */
+    invalidateServerModules(changedFiles?: string[]): void;
+    /**
+     * Resets runtime-owned graph state and invalidates server modules.
+     */
+    resetRuntimeState(changedFiles?: string[]): void;
+    /**
+     * Classifies one changed file into an explicit framework invalidation plan.
+     */
+    planFileChange(filePath: string): DevelopmentInvalidationPlan;
+    /**
+     * Returns whether the file lives under the public directory.
+     */
+    isPublicDirFile(filePath: string): boolean;
+    /**
+     * Returns whether the file matches `additionalWatchPaths`.
+     */
+    matchesAdditionalWatchPaths(filePath: string): boolean;
+    /**
+     * Returns whether the file is a route source file.
+     */
+    isRouteSourceFile(filePath: string): boolean;
+    /**
+     * Returns whether the file is an include/template source file.
+     */
+    isIncludeSourceFile(filePath: string): boolean;
+    /**
+     * Returns whether the file is a server-executed source module outside the
+     * special route/include buckets.
+     */
+    isServerModuleSourceFile(filePath: string): boolean;
+    /**
+     * Returns whether a processor owns the changed file as an asset input.
+     */
+    isProcessorOwnedAsset(filePath: string): boolean;
+}

package/src/services/invalidation/development-invalidation.service.js

@@ -0,0 +1,190 @@
+import path from "node:path";
+import { getAppServerInvalidationState } from "../runtime-state/server-invalidation-state.service.js";
+class DevelopmentInvalidationService {
+  appConfig;
+  constructor(appConfig) {
+    this.appConfig = appConfig;
+  }
+  /**
+   * Returns the current app-owned server-module invalidation version.
+   */
+  getServerModuleInvalidationVersion() {
+    return getAppServerInvalidationState(this.appConfig).getServerInvalidationVersion();
+  }
+  /**
+   * Invalidates the app-owned server-module graph.
+   */
+  invalidateServerModules(changedFiles) {
+    getAppServerInvalidationState(this.appConfig).invalidateServerModules(changedFiles);
+    this.appConfig.runtime?.appModuleLoader?.invalidateDevelopmentGraph();
+  }
+  /**
+   * Resets runtime-owned graph state and invalidates server modules.
+   */
+  resetRuntimeState(changedFiles) {
+    const serverInvalidationState = getAppServerInvalidationState(this.appConfig);
+    serverInvalidationState.invalidateServerModules(changedFiles);
+    serverInvalidationState.reset();
+  }
+  /**
+   * Classifies one changed file into an explicit framework invalidation plan.
+   */
+  planFileChange(filePath) {
+    if (this.isPublicDirFile(filePath)) {
+      return {
+        category: "public-asset",
+        invalidateServerModules: false,
+        refreshRoutes: false,
+        reloadBrowser: true,
+        delegateToHmr: false,
+        processorHandledAsset: false
+      };
+    }
+    if (this.matchesAdditionalWatchPaths(filePath)) {
+      return {
+        category: "additional-watch",
+        invalidateServerModules: false,
+        refreshRoutes: false,
+        reloadBrowser: true,
+        delegateToHmr: false,
+        processorHandledAsset: false
+      };
+    }
+    if (this.isIncludeSourceFile(filePath)) {
+      return {
+        category: "include-source",
+        invalidateServerModules: true,
+        refreshRoutes: false,
+        reloadBrowser: true,
+        delegateToHmr: false,
+        processorHandledAsset: false
+      };
+    }
+    if (this.isRouteSourceFile(filePath)) {
+      return {
+        category: "route-source",
+        invalidateServerModules: true,
+        refreshRoutes: true,
+        reloadBrowser: false,
+        delegateToHmr: true,
+        processorHandledAsset: false
+      };
+    }
+    if (this.isProcessorOwnedAsset(filePath)) {
+      return {
+        category: "processor-owned-asset",
+        invalidateServerModules: false,
+        refreshRoutes: false,
+        reloadBrowser: false,
+        delegateToHmr: false,
+        processorHandledAsset: true
+      };
+    }
+    if (this.isServerModuleSourceFile(filePath)) {
+      return {
+        category: "server-source",
+        invalidateServerModules: true,
+        refreshRoutes: false,
+        reloadBrowser: false,
+        delegateToHmr: true,
+        processorHandledAsset: false
+      };
+    }
+    return {
+      category: "other",
+      invalidateServerModules: false,
+      refreshRoutes: false,
+      reloadBrowser: false,
+      delegateToHmr: true,
+      processorHandledAsset: false
+    };
+  }
+  /**
+   * Returns whether the file lives under the public directory.
+   */
+  isPublicDirFile(filePath) {
+    return path.resolve(filePath).startsWith(this.appConfig.absolutePaths.publicDir);
+  }
+  /**
+   * Returns whether the file matches `additionalWatchPaths`.
+   */
+  matchesAdditionalWatchPaths(filePath) {
+    const normalizedPath = path.resolve(filePath);
+    const patterns = this.appConfig.additionalWatchPaths;
+    if (!patterns.length) return false;
+    for (const pattern of patterns) {
+      if (pattern.includes("*")) {
+        const ext = pattern.replace(/\*\*?\/\*/, "");
+        if (normalizedPath.endsWith(ext)) return true;
+      } else if (normalizedPath.endsWith(pattern) || normalizedPath === path.resolve(pattern)) {
+        return true;
+      }
+    }
+    return false;
+  }
+  /**
+   * Returns whether the file is a route source file.
+   */
+  isRouteSourceFile(filePath) {
+    const resolvedPath = path.resolve(filePath);
+    if (!resolvedPath.startsWith(this.appConfig.absolutePaths.pagesDir)) {
+      return false;
+    }
+    if (this.appConfig.templatesExt.some((extension) => resolvedPath.endsWith(extension))) {
+      return true;
+    }
+    return /\.(?:[cm]?ts|[jt]sx?|mdx)$/u.test(resolvedPath);
+  }
+  /**
+   * Returns whether the file is an include/template source file.
+   */
+  isIncludeSourceFile(filePath) {
+    const resolvedPath = path.resolve(filePath);
+    if (!resolvedPath.startsWith(this.appConfig.absolutePaths.includesDir)) {
+      return false;
+    }
+    if (this.appConfig.templatesExt.some((extension) => resolvedPath.endsWith(extension))) {
+      return true;
+    }
+    return /\.(?:[cm]?ts|[jt]sx?|mdx)$/u.test(resolvedPath);
+  }
+  /**
+   * Returns whether the file is a server-executed source module outside the
+   * special route/include buckets.
+   */
+  isServerModuleSourceFile(filePath) {
+    const resolvedPath = path.resolve(filePath);
+    if (!resolvedPath.startsWith(this.appConfig.absolutePaths.srcDir)) {
+      return false;
+    }
+    if (this.appConfig.templatesExt.some((extension) => resolvedPath.endsWith(extension))) {
+      return true;
+    }
+    return /\.(?:[cm]?ts|[jt]sx?|mdx)$/u.test(resolvedPath);
+  }
+  /**
+   * Returns whether a processor owns the changed file as an asset input.
+   */
+  isProcessorOwnedAsset(filePath) {
+    for (const processor of this.appConfig.processors.values()) {
+      const capabilities = processor.getAssetCapabilities?.() ?? [];
+      if (capabilities.length > 0) {
+        const matchesConfiguredAsset = typeof processor.matchesFileFilter !== "function" || processor.matchesFileFilter(filePath);
+        if (matchesConfiguredAsset && capabilities.some((capability) => processor.canProcessAsset?.(capability.kind, filePath))) {
+          return true;
+        }
+        continue;
+      }
+      const watchConfig = processor.getWatchConfig();
+      if (!watchConfig) continue;
+      const { extensions = [] } = watchConfig;
+      if (extensions.length && extensions.some((ext) => filePath.endsWith(ext))) {
+        return true;
+      }
+    }
+    return false;
+  }
+}
+export {
+  DevelopmentInvalidationService
+};

package/src/services/module-loading/app-module-loader.service.d.ts

@@ -0,0 +1,7 @@
+import type { PageModuleBuildImportOptions } from './page-module-import.service.js';
+export type AppModuleLoaderOwner = 'bun' | 'host';
+export interface AppModuleLoader {
+    readonly owner: AppModuleLoaderOwner;
+    importModule<T = unknown>(options: PageModuleBuildImportOptions): Promise<T>;
+    invalidateDevelopmentGraph(): void;
+}

package/src/services/module-loading/app-server-module-transpiler.service.d.ts

@@ -0,0 +1,24 @@
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+import { type AppModuleLoader } from './app-module-loader.service.js';
+import type { SourceModuleLoader } from './module-loading-types.js';
+import { ServerModuleTranspiler } from './server-module-transpiler.service.js';
+export declare function shouldAppUseHostModuleLoader(appConfig: EcoPagesAppConfig, filePath: string): boolean;
+export declare function getAppHostModuleLoader(appConfig: EcoPagesAppConfig): SourceModuleLoader | undefined;
+export declare function setAppHostModuleLoader(appConfig: EcoPagesAppConfig, hostModuleLoader?: SourceModuleLoader): void;
+export declare function createAppModuleLoader(appConfig: EcoPagesAppConfig): AppModuleLoader;
+export declare function getAppModuleLoader(appConfig: EcoPagesAppConfig): AppModuleLoader;
+export declare function setAppModuleLoader(appConfig: EcoPagesAppConfig, appModuleLoader: AppModuleLoader): void;
+/**
+ * Creates the shared app-scoped server-module transpiler for one runtime
+ * instance.
+ */
+export declare function createAppServerModuleTranspiler(appConfig: EcoPagesAppConfig): ServerModuleTranspiler;
+/**
+ * Returns the app-owned server-module transpiler, creating it lazily when the
+ * runtime first needs one.
+ */
+export declare function getAppServerModuleTranspiler(appConfig: EcoPagesAppConfig): ServerModuleTranspiler;
+/**
+ * Installs the server-module transpiler that should serve one app instance.
+ */
+export declare function setAppServerModuleTranspiler(appConfig: EcoPagesAppConfig, serverModuleTranspiler: ServerModuleTranspiler): void;