@ecopages/core 0.2.0-alpha.54 → 0.2.0-alpha.55

package/src/services/html/html-rewriter-provider.service.d.ts

@@ -0,0 +1,40 @@
+export type HtmlRewriterElement = {
+    prepend(content: string, options?: {
+        html?: boolean;
+    }): void;
+    append(content: string, options?: {
+        html?: boolean;
+    }): void;
+};
+export type HtmlRewriterRuntime = {
+    on(selector: 'head' | 'body', handler: {
+        element: (element: HtmlRewriterElement) => void;
+    }): HtmlRewriterRuntime;
+    transform(response: Response): Response;
+};
+export type HtmlRewriterConstructor = new () => HtmlRewriterRuntime;
+export type HtmlRewriterMode = 'auto' | 'native' | 'worker-tools' | 'fallback';
+export interface HtmlRewriterProvider {
+    createHtmlRewriter(): Promise<HtmlRewriterRuntime | null>;
+    setMode(mode: HtmlRewriterMode): void;
+}
+export interface HtmlRewriterLogger {
+    warn(message: string): void;
+}
+export interface DefaultHtmlRewriterProviderOptions {
+    mode?: HtmlRewriterMode;
+    logger?: HtmlRewriterLogger;
+    getNativeHtmlRewriter?: () => HtmlRewriterConstructor | undefined;
+    loadWorkerToolsHtmlRewriter?: () => Promise<HtmlRewriterConstructor | null>;
+}
+export declare class DefaultHtmlRewriterProvider implements HtmlRewriterProvider {
+    private htmlRewriterConstructorPromise?;
+    private htmlRewriterMode;
+    private logger;
+    private getNativeHtmlRewriter;
+    private loadWorkerToolsHtmlRewriter;
+    constructor(options?: DefaultHtmlRewriterProviderOptions);
+    setMode(mode: HtmlRewriterMode): void;
+    createHtmlRewriter(): Promise<HtmlRewriterRuntime | null>;
+    private resolveHtmlRewriterConstructor;
+}

package/src/services/html/html-rewriter-provider.service.js

@@ -0,0 +1,68 @@
+import { appLogger } from "../../global/app-logger.js";
+class DefaultHtmlRewriterProvider {
+  htmlRewriterConstructorPromise;
+  htmlRewriterMode;
+  logger;
+  getNativeHtmlRewriter;
+  loadWorkerToolsHtmlRewriter;
+  constructor(options = {}) {
+    this.htmlRewriterMode = options.mode ?? "auto";
+    this.logger = options.logger ?? appLogger;
+    this.getNativeHtmlRewriter = options.getNativeHtmlRewriter ?? (() => globalThis.HTMLRewriter);
+    this.loadWorkerToolsHtmlRewriter = options.loadWorkerToolsHtmlRewriter ?? loadWorkerToolsHtmlRewriter;
+  }
+  setMode(mode) {
+    this.htmlRewriterMode = mode;
+    this.htmlRewriterConstructorPromise = void 0;
+  }
+  async createHtmlRewriter() {
+    const RuntimeHtmlRewriter = await this.resolveHtmlRewriterConstructor();
+    return RuntimeHtmlRewriter ? new RuntimeHtmlRewriter() : null;
+  }
+  async resolveHtmlRewriterConstructor() {
+    if (!this.htmlRewriterConstructorPromise) {
+      const mode = this.htmlRewriterMode;
+      const RuntimeHtmlRewriter = this.getNativeHtmlRewriter();
+      if (mode === "fallback") {
+        this.htmlRewriterConstructorPromise = Promise.resolve(null);
+      } else if (mode === "native") {
+        if (RuntimeHtmlRewriter) {
+          this.htmlRewriterConstructorPromise = Promise.resolve(RuntimeHtmlRewriter);
+        } else {
+          this.logger.warn(
+            "[HtmlTransformerService] Native HTMLRewriter was forced but is unavailable, falling back to string injection."
+          );
+          this.htmlRewriterConstructorPromise = Promise.resolve(null);
+        }
+      } else if (mode === "auto" && RuntimeHtmlRewriter) {
+        this.htmlRewriterConstructorPromise = Promise.resolve(RuntimeHtmlRewriter);
+      } else {
+        this.htmlRewriterConstructorPromise = this.loadWorkerToolsHtmlRewriter();
+      }
+    }
+    return this.htmlRewriterConstructorPromise;
+  }
+}
+async function loadWorkerToolsHtmlRewriter() {
+  try {
+    const module = await import("@worker-tools/html-rewriter/base64");
+    return module.HTMLRewriter;
+  } catch (primaryError) {
+    try {
+      const runtimeLocalModule = await import(
+        /* @vite-ignore */
+        new URL("../node_modules/@worker-tools/html-rewriter/base64.js", import.meta.url).href
+      );
+      return runtimeLocalModule.HTMLRewriter;
+    } catch {
+      const message = primaryError instanceof Error ? primaryError.message : String(primaryError);
+      appLogger.warn(
+        `[HtmlTransformerService] Failed to load @worker-tools/html-rewriter/base64, falling back to string injection: ${message}`
+      );
+      return null;
+    }
+  }
+}
+export {
+  DefaultHtmlRewriterProvider
+};

package/src/services/html/html-transformer.service.d.ts

@@ -0,0 +1,96 @@
+import type { ProcessedAsset } from '../assets/asset-processing-service/assets.types.js';
+import type { PagePackageResult } from '../../types/public-types.js';
+import { type HtmlRewriterMode, type HtmlRewriterProvider } from './html-rewriter-provider.service.js';
+export type HtmlDocumentContributionPlacement = 'head-prepend' | 'head-append' | 'body-prepend' | 'body-append';
+export type HtmlDocumentContribution = {
+    placement: HtmlDocumentContributionPlacement;
+    html: string;
+};
+export interface HtmlTransformerServiceOptions {
+    htmlRewriterMode?: HtmlRewriterMode;
+    htmlRewriterProvider?: HtmlRewriterProvider;
+}
+export declare class HtmlTransformerService {
+    private processedDependencies;
+    private pagePackage?;
+    private htmlRewriterProvider;
+    constructor(options?: HtmlTransformerServiceOptions);
+    /**
+     * 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: HtmlRewriterMode): void;
+    private formatAttributes;
+    private generateScriptTag;
+    private generateStylesheetTag;
+    private appendDependencies;
+    private buildDependencyTags;
+    private applyContributions;
+    /**
+     * Injects generated markup immediately before the closing HTML tag when it is
+     * present, or appends/prepends a fallback insertion otherwise.
+     */
+    private injectBeforeClosingTag;
+    private injectAfterOpeningTag;
+    private groupContributionsByPlacement;
+    /**
+     * Replaces the current processed dependency set used during HTML finalization.
+     */
+    setProcessedDependencies(processedDependencies: ProcessedAsset[]): void;
+    /**
+     * Replaces the current structured page package used during HTML finalization.
+     */
+    setPagePackage(pagePackage: PagePackageResult): void;
+    /**
+     * Returns the processed dependencies queued for the next transform pass.
+     */
+    getProcessedDependencies(): ProcessedAsset[];
+    /**
+     * Returns the structured page package queued for the next transform pass.
+     */
+    getPagePackage(): PagePackageResult | undefined;
+    /**
+     * Applies attributes to the opening `<html>` tag when present.
+     */
+    applyAttributesToHtmlElement(html: string, attributes: Record<string, string>): string;
+    /**
+     * Applies attributes to the first element nested directly under `<body>`.
+     */
+    applyAttributesToFirstBodyElement(html: string, attributes: Record<string, string>): string;
+    /**
+     * Applies attributes to the first element in a fragment or full-document HTML
+     * string.
+     */
+    applyAttributesToFirstElement(html: string, attributes: Record<string, string>): string;
+    /**
+     * 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: ProcessedAsset[]): ProcessedAsset[];
+    /**
+     * 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.
+     */
+    transform(res: Response, contributions?: HtmlDocumentContribution[]): Promise<Response>;
+    /**
+     * Splits processed assets into head and body injection groups.
+     */
+    private groupDependenciesByPosition;
+    private resolvePagePackageHtmlDependencies;
+    /**
+     * Builds a serialized HTML attribute string from an attribute object.
+     */
+    private buildAttributeString;
+}

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;
+}