@ecopages/core 0.2.0-alpha.7 → 0.2.0-alpha.9

package/src/services/cache/page-request-cache-coordinator.service.js

@@ -0,0 +1,109 @@
+import { getCacheControlHeader } from "./page-cache-service.js";
+class PageRequestCacheCoordinator {
+  cacheService;
+  defaultCacheStrategy;
+  constructor(cacheService, defaultCacheStrategy) {
+    this.cacheService = cacheService;
+    this.defaultCacheStrategy = defaultCacheStrategy;
+  }
+  /**
+   * Builds the cache key used for page lookups.
+   *
+   * Query parameters are part of the key so two requests that hit the same
+   * pathname but differ by search params do not share the same rendered entry.
+   *
+   * @param input Pathname plus optional query record.
+   * @returns Stable cache key for the request.
+   */
+  buildCacheKey(input) {
+    let key = input.pathname;
+    if (input.query && Object.keys(input.query).length > 0) {
+      const queryString = new URLSearchParams(input.query).toString();
+      key += `?${queryString}`;
+    }
+    return key;
+  }
+  /**
+   * Resolves a render request through the configured cache policy.
+   *
+   * Pages using `dynamic` rendering, or applications without a cache service,
+   * bypass cache lookup entirely and still receive the same response header
+   * contract as cached pages.
+   *
+   * @param options Cache coordination inputs for one page request.
+   * @returns HTTP response with cache headers applied.
+   */
+  async render(options) {
+    if (!this.cacheService || options.pageCacheStrategy === "dynamic") {
+      const { html, strategy } = await options.renderFn();
+      return this.createCachedResponse(html, strategy, "disabled");
+    }
+    const result = await this.cacheService.getOrCreate(
+      options.cacheKey,
+      options.pageCacheStrategy,
+      options.renderFn
+    );
+    return this.createCachedResponse(result.html, result.strategy, result.status);
+  }
+  /**
+   * Exposes the underlying cache service for invalidation and adapter plumbing.
+   *
+   * @returns Configured cache service or `null` when caching is disabled.
+   */
+  getCacheService() {
+    return this.cacheService;
+  }
+  /**
+   * Returns the default render strategy used when a page does not declare one.
+   *
+   * @returns Application-level fallback cache strategy.
+   */
+  getDefaultCacheStrategy() {
+    return this.defaultCacheStrategy;
+  }
+  /**
+   * Normalizes various route render body shapes into a cacheable string.
+   *
+   * Page rendering may produce strings, buffers, byte arrays, or streams. The
+   * matcher needs a single representation before passing HTML through the cache
+   * layer, so this method centralizes the conversion rules.
+   *
+   * @param body Render output body in any supported form.
+   * @returns HTML string representation.
+   */
+  async bodyToString(body) {
+    if (typeof body === "string") {
+      return body;
+    }
+    if (Buffer.isBuffer(body)) {
+      return body.toString("utf-8");
+    }
+    if (body instanceof ReadableStream) {
+      return new Response(body).text();
+    }
+    if (body instanceof Uint8Array) {
+      return new TextDecoder().decode(body);
+    }
+    return String(body);
+  }
+  /**
+   * Creates the final HTML response with the current cache semantics encoded in
+   * response headers.
+   *
+   * @param html Rendered page HTML.
+   * @param strategy Effective cache strategy for the response.
+   * @param cacheStatus Status used for `X-Cache` and `Cache-Control` generation.
+   * @returns HTTP response ready to send to the client.
+   */
+  createCachedResponse(html, strategy, cacheStatus) {
+    const headers = {
+      "Content-Type": "text/html",
+      "Cache-Control": getCacheControlHeader(cacheStatus === "disabled" ? "disabled" : strategy),
+      "X-Cache": cacheStatus.toUpperCase()
+    };
+    return new Response(html, { headers });
+  }
+}
+export {
+  PageRequestCacheCoordinator
+};

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

@@ -0,0 +1,37 @@
+export type HtmlRewriterElement = {
+    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,65 @@
+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(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,77 @@
+import type { ProcessedAsset } from '../assets/asset-processing-service/assets.types';
+import { type HtmlRewriterMode, type HtmlRewriterProvider } from './html-rewriter-provider.service';
+export interface HtmlTransformerServiceOptions {
+    htmlRewriterMode?: HtmlRewriterMode;
+    htmlRewriterProvider?: HtmlRewriterProvider;
+}
+export declare class HtmlTransformerService {
+    private processedDependencies;
+    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;
+    /**
+     * Injects generated markup immediately before the closing HTML tag when it is
+     * present, or appends/prepends a fallback insertion otherwise.
+     */
+    private injectBeforeClosingTag;
+    /**
+     * Replaces the current processed dependency set used during HTML finalization.
+     */
+    setProcessedDependencies(processedDependencies: ProcessedAsset[]): void;
+    /**
+     * Returns the processed dependencies queued for the next transform pass.
+     */
+    getProcessedDependencies(): ProcessedAsset[];
+    /**
+     * 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): Promise<Response>;
+    /**
+     * Splits processed assets into head and body injection groups.
+     */
+    private groupDependenciesByPosition;
+    /**
+     * Builds a serialized HTML attribute string from an attribute object.
+     */
+    private buildAttributeString;
+}

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

@@ -0,0 +1,221 @@
+import {
+  DefaultHtmlRewriterProvider
+} from "./html-rewriter-provider.service";
+class HtmlTransformerService {
+  processedDependencies = [];
+  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("");
+  }
+  /**
+   * 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}`;
+  }
+  /**
+   * Replaces the current processed dependency set used during HTML finalization.
+   */
+  setProcessedDependencies(processedDependencies) {
+    this.processedDependencies = processedDependencies;
+  }
+  /**
+   * Returns the processed dependencies queued for the next transform pass.
+   */
+  getProcessedDependencies() {
+    return this.processedDependencies;
+  }
+  /**
+   * 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) {
+    const unique = /* @__PURE__ */ new Map();
+    for (const asset of assets) {
+      const key = [
+        asset.kind,
+        asset.position ?? "",
+        asset.srcUrl ?? "",
+        asset.filepath ?? "",
+        asset.content ?? "",
+        asset.inline ? "inline" : "external",
+        asset.excludeFromHtml ? "excluded" : "included",
+        JSON.stringify(asset.attributes ?? {})
+      ].join("|");
+      if (!unique.has(key)) {
+        unique.set(key, asset);
+      }
+    }
+    return [...unique.values()];
+  }
+  /**
+   * 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) {
+    const { head, body } = this.groupDependenciesByPosition();
+    const htmlRewriter = await this.htmlRewriterProvider.createHtmlRewriter();
+    const html = await res.text();
+    const headers = new Headers(res.headers);
+    if (htmlRewriter) {
+      htmlRewriter.on("head", {
+        element: (element) => this.appendDependencies(element, head)
+      }).on("body", {
+        element: (element) => this.appendDependencies(element, body)
+      });
+      return htmlRewriter.transform(
+        new Response(html, {
+          headers,
+          status: res.status,
+          statusText: res.statusText
+        })
+      );
+    }
+    const withHeadDependencies = this.injectBeforeClosingTag(html, "head", this.buildDependencyTags(head));
+    const transformedHtml = this.injectBeforeClosingTag(
+      withHeadDependencies,
+      "body",
+      this.buildDependencyTags(body)
+    );
+    return new Response(transformedHtml, {
+      headers,
+      status: res.status,
+      statusText: res.statusText
+    });
+  }
+  /**
+   * Splits processed assets into head and body injection groups.
+   */
+  groupDependenciesByPosition() {
+    return this.processedDependencies.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: [] }
+    );
+  }
+  /**
+   * 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 '../../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;
+}