@ecopages/core 0.2.0-beta.8 → 0.2.0-rc.0

package/src/services/assets/asset-processing-service/processors/stylesheet/file-stylesheet.processor.js

@@ -1,69 +1,35 @@
-import path from "node:path";
-import { fileSystem } from "@ecopages/file-system";
-import { BaseProcessor } from "../base/base-processor.js";
-class FileStylesheetProcessor extends BaseProcessor {
-  static PROCESSABLE_STYLESHEET_EXTENSIONS = /* @__PURE__ */ new Set([".css", ".scss", ".sass", ".less"]);
-  getStyleContent = (srcUrl) => {
-    return fileSystem.readFileAsBuffer(srcUrl);
-  };
-  isProcessableStylesheet(filepath) {
-    return FileStylesheetProcessor.PROCESSABLE_STYLESHEET_EXTENSIONS.has(path.extname(filepath));
-  }
-  async applyStylesheetProcessors(content, filepath) {
-    if (!this.isProcessableStylesheet(filepath)) {
-      return content;
+import path from 'node:path';
+import { fileSystem } from '@ecopages/file-system';
+import { BaseProcessor } from '../base/base-processor.js';
+import { applyStylesheetProcessors } from './stylesheet-processor-pipeline.js';
+export class FileStylesheetProcessor extends BaseProcessor {
+    getStyleContent = (srcUrl) => {
+        return fileSystem.readFileAsBuffer(srcUrl);
+    };
+    async process(dep) {
+        const buffer = this.getStyleContent(dep.filepath);
+        const rawContent = buffer.toString();
+        const processedContent = await applyStylesheetProcessors(this.appConfig, rawContent, dep.filepath);
+        const hash = this.generateHash(processedContent);
+        const cachekey = this.buildCacheKey(dep.filepath, hash, dep);
+        return this.getOrProcess(cachekey, () => {
+            const filepath = path.join(this.getAssetsDir(), path.relative(this.appConfig.absolutePaths.srcDir, dep.filepath));
+            const outputBuffer = Buffer.from(processedContent);
+            if (!dep.inline) {
+                fileSystem.ensureDir(path.dirname(filepath));
+                fileSystem.write(filepath, outputBuffer);
+            }
+            return {
+                filepath: filepath,
+                sourceFilepath: dep.filepath,
+                content: dep.inline ? processedContent : undefined,
+                kind: 'stylesheet',
+                position: dep.position,
+                attributes: dep.attributes,
+                inline: dep.inline,
+                packageRole: dep.packageRole,
+                bundledSourceFilepaths: dep.bundledSourceFilepaths,
+            };
+        });
     }
-    let transformedContent = content;
-    for (const processor of this.appConfig.processors.values()) {
-      const hasCapabilities = processor.getAssetCapabilities().length > 0;
-      const canProcessStylesheet = processor.canProcessAsset("stylesheet", filepath);
-      if (!canProcessStylesheet && (hasCapabilities || !processor.getName().includes("postcss"))) {
-        continue;
-      }
-      if (!processor.matchesFileFilter(filepath)) {
-        continue;
-      }
-      const result = await processor.process(transformedContent, filepath);
-      if (typeof result === "string") {
-        transformedContent = result;
-        continue;
-      }
-      if (result instanceof Buffer) {
-        transformedContent = result.toString();
-      }
-    }
-    return transformedContent;
-  }
-  async process(dep) {
-    const buffer = this.getStyleContent(dep.filepath);
-    const rawContent = buffer.toString();
-    const processedContent = await this.applyStylesheetProcessors(rawContent, dep.filepath);
-    const hash = this.generateHash(processedContent);
-    const cachekey = this.buildCacheKey(dep.filepath, hash, dep);
-    return this.getOrProcess(cachekey, () => {
-      const filepath = path.join(
-        this.getAssetsDir(),
-        path.relative(this.appConfig.absolutePaths.srcDir, dep.filepath)
-      );
-      const outputBuffer = Buffer.from(processedContent);
-      if (!dep.inline) {
-        fileSystem.ensureDir(path.dirname(filepath));
-        fileSystem.write(filepath, outputBuffer);
-      }
-      return {
-        filepath,
-        sourceFilepath: dep.filepath,
-        content: dep.inline ? processedContent : void 0,
-        kind: "stylesheet",
-        position: dep.position,
-        attributes: dep.attributes,
-        inline: dep.inline,
-        packageRole: dep.packageRole,
-        bundledSourceFilepaths: dep.bundledSourceFilepaths
-      };
-    });
-  }
 }
-export {
-  FileStylesheetProcessor
-};

package/src/services/assets/asset-processing-service/processors/stylesheet/stylesheet-processor-pipeline.d.ts

@@ -0,0 +1,2 @@
+import type { EcoPagesAppConfig } from '../../../../../types/internal-types.js';
+export declare function applyStylesheetProcessors(appConfig: EcoPagesAppConfig, content: string, filepath: string): Promise<string>;

package/src/services/assets/asset-processing-service/processors/stylesheet/stylesheet-processor-pipeline.js

@@ -0,0 +1,44 @@
+import path from 'node:path';
+const PROCESSABLE_STYLESHEET_EXTENSIONS = new Set(['.css', '.scss', '.sass', '.less']);
+function isProcessableStylesheet(filepath) {
+    return PROCESSABLE_STYLESHEET_EXTENSIONS.has(path.extname(filepath));
+}
+/**
+ * Legacy fallback for processors that transform stylesheets without declaring
+ * capabilities (notably PostCSS before capability metadata was required).
+ */
+function shouldRunStylesheetProcessor(processor, filepath) {
+    const hasCapabilities = processor.getAssetCapabilities().length > 0;
+    const canProcessStylesheet = processor.canProcessAsset('stylesheet', filepath);
+    if (canProcessStylesheet) {
+        return true;
+    }
+    if (hasCapabilities) {
+        return false;
+    }
+    return processor.getName().includes('postcss');
+}
+export async function applyStylesheetProcessors(appConfig, content, filepath) {
+    if (!isProcessableStylesheet(filepath)) {
+        return content;
+    }
+    let transformedContent = content;
+    const processors = appConfig.processors ? Array.from(appConfig.processors.values()) : [];
+    for (const processor of processors) {
+        if (!shouldRunStylesheetProcessor(processor, filepath)) {
+            continue;
+        }
+        if (!processor.matchesFileFilter(filepath)) {
+            continue;
+        }
+        const result = await processor.process(transformedContent, filepath);
+        if (typeof result === 'string') {
+            transformedContent = result;
+            continue;
+        }
+        if (result instanceof Buffer) {
+            transformedContent = result.toString();
+        }
+    }
+    return transformedContent;
+}

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

@@ -0,0 +1,4 @@
+import type { AnyIntegrationPlugin } from '../../../plugins/integration-plugin.js';
+import type { EcoPagesAppConfig } from '../../../types/internal-types.js';
+/** Resolves the integration plugin that owns one asset-processing batch key. */
+export declare function resolveIntegrationPluginForProcessingKey(appConfig: EcoPagesAppConfig, processingKey: string): AnyIntegrationPlugin | undefined;

package/src/services/assets/asset-processing-service/resolve-integration-plugin.js

@@ -0,0 +1,15 @@
+/** Resolves the integration plugin that owns one asset-processing batch key. */
+export function resolveIntegrationPluginForProcessingKey(appConfig, processingKey) {
+    if (!appConfig.integrations?.length) {
+        return undefined;
+    }
+    const exactMatch = appConfig.integrations.find((integration) => integration.name === processingKey);
+    if (exactMatch) {
+        return exactMatch;
+    }
+    const baseName = processingKey.split(':')[0];
+    if (!baseName || baseName === processingKey) {
+        return undefined;
+    }
+    return appConfig.integrations.find((integration) => integration.name === baseName);
+}

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

@@ -2,7 +2,6 @@ import type { AssetProcessor } from './processor.interface.js';
 import type { AssetDefinition, ProcessedAsset } from './assets.types.js';
 type ProcessUngroupedDependencyOptions = {
     dep: AssetDefinition;
-    key: string;
     depKey: string;
     getCachedAsset: (dep: AssetDefinition, depKey: string) => ProcessedAsset | null;
     getProcessor: (dep: AssetDefinition) => AssetProcessor | undefined;

package/src/services/assets/asset-processing-service/ungrouped-dependency-processing.js

@@ -1,45 +1,28 @@
-import { fileSystem } from "@ecopages/file-system";
-async function processUngroupedDependency(options) {
-  const {
-    dep,
-    key,
-    depKey,
-    getCachedAsset,
-    getProcessor,
-    resolveProcessedAssetSrcUrl,
-    setCachedAsset,
-    logMissingProcessor,
-    logMissingFile,
-    logProcessingError
-  } = options;
-  const cached = getCachedAsset(dep, depKey);
-  if (cached) {
-    return { key, ...cached };
-  }
-  const processor = getProcessor(dep);
-  if (!processor) {
-    logMissingProcessor(dep);
-    return null;
-  }
-  if (dep.source === "file" && "filepath" in dep && !fileSystem.exists(dep.filepath)) {
-    logMissingFile(dep);
-    return null;
-  }
-  try {
-    const processed = await processor.process(dep);
-    const srcUrl = resolveProcessedAssetSrcUrl(processed);
-    const processedWithKey = {
-      key,
-      ...processed,
-      srcUrl
-    };
-    setCachedAsset(dep, depKey, processedWithKey);
-    return processedWithKey;
-  } catch (error) {
-    logProcessingError(dep, error);
-    return null;
-  }
+import { fileSystem } from '@ecopages/file-system';
+import { finalizeProcessedAsset } from './finalize-processed-asset.js';
+export async function processUngroupedDependency(options) {
+    const { dep, depKey, getCachedAsset, getProcessor, resolveProcessedAssetSrcUrl, setCachedAsset, logMissingProcessor, logMissingFile, logProcessingError, } = options;
+    const cached = getCachedAsset(dep, depKey);
+    if (cached) {
+        return finalizeProcessedAsset(cached, resolveProcessedAssetSrcUrl);
+    }
+    const processor = getProcessor(dep);
+    if (!processor) {
+        logMissingProcessor(dep);
+        return null;
+    }
+    if (dep.source === 'file' && 'filepath' in dep && !fileSystem.exists(dep.filepath)) {
+        logMissingFile(dep);
+        return null;
+    }
+    try {
+        const processed = await processor.process(dep);
+        const finalized = finalizeProcessedAsset(processed, resolveProcessedAssetSrcUrl);
+        setCachedAsset(dep, depKey, finalized);
+        return finalized;
+    }
+    catch (error) {
+        logProcessingError(dep, error);
+        return null;
+    }
 }
-export {
-  processUngroupedDependency
-};

package/src/services/assets/browser-bundle.service.d.ts

@@ -1,6 +1,24 @@
-import type { BuildResult, BuildTranspileProfile } from '../../build/build-adapter.js';
-import type { EcoBuildPlugin } from '../../build/build-types.js';
+import type { BuildResult } from '../../build/build-adapter.js';
+import type { BuildTranspileProfile } from '../../build/build-adapter.js';
+import type { EcoBuildPlugin } from '../../build/contracts/build-types.js';
 import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+/**
+ * Browser-oriented build request accepted by {@link BrowserBundleService}.
+ *
+ * @remarks
+ * `profile` is a {@link BuildTranspileProfile} (transpile settings only).
+ * `executor` selects the {@link BuildRuntime} concurrency slot:
+ * - `'hmr'` + (`hmr-entrypoint` | `hmr-runtime`) → `'browser-hmr'`
+ * - everything else (including `browser-script`, and `'build'`) → `'route-module'`
+ *
+ * Defaults `executor` to `'hmr'`. Request options are always assembled with
+ * browser-hmr *defaults* via {@link createBrowserBuildRequest}; only the
+ * concurrency/dedupe wrapper differs.
+ *
+ * Uses request-scope {@link requestBuildDedupe} plus in-flight
+ * {@link DedupingBuildExecutor} coalescing; both key on
+ * {@link createBuildRequestIdentity}.
+ */
 export type BrowserBundleOptions = {
     entrypoints: string[] | Record<string, string>;
     outdir?: string;
@@ -17,28 +35,10 @@ export type BrowserBundleOptions = {
     external?: string[];
     plugins?: EcoBuildPlugin[];
     executor?: 'build' | 'hmr';
-    [key: string]: unknown;
-    profile: BuildTranspileProfile;
-    excludeAppBuildPlugins?: string[];
-};
-type BrowserBundleGroupedOptions = {
-    outdir?: string;
-    outbase?: string;
-    naming?: string;
-    conditions?: string[];
-    define?: Record<string, string>;
-    minify?: boolean;
-    treeshaking?: boolean;
-    splitting?: boolean;
-    root?: string;
-    bundle?: boolean;
-    externalPackages?: boolean;
-    external?: string[];
-    plugins?: EcoBuildPlugin[];
-    [key: string]: unknown;
     profile: BuildTranspileProfile;
     excludeAppBuildPlugins?: string[];
 };
+type BrowserBundleGroupedOptions = Omit<BrowserBundleOptions, 'entrypoints'>;
 export interface BrowserBundleExecutor {
     bundle(options: BrowserBundleOptions): Promise<BuildResult>;
 }
@@ -50,23 +50,20 @@ export type BrowserBundleGroupedEntry = {
  * App-owned boundary for browser-oriented bundle work.
  *
  * @remarks
- * This service owns the shared browser transpile defaults and ensures browser
- * builds always run through the app-owned executor rather than direct backend
- * calls scattered across HMR and asset processing paths.
+ * Owns shared browser transpile defaults and ensures browser builds run through
+ * the app-owned executor rather than direct backend calls. Assembles a complete
+ * request via {@link createBrowserBuildRequest} before scheduling.
  */
 export declare class BrowserBundleService implements BrowserBundleExecutor {
     private readonly appConfig;
-    /**
-     * Creates the browser bundle boundary for one finalized app instance.
-     */
     constructor(appConfig: EcoPagesAppConfig);
     /**
      * Runs one browser-targeted build through the app-owned executor.
      *
      * @remarks
-     * Browser defaults and app-owned browser build plugins are applied here so HMR
-     * and runtime asset generation do not have to recreate that policy at each call
-     * site.
+     * Browser defaults, app-owned browser plugins, and
+     * {@link getAppSourceTransforms | app source transforms} are applied here
+     * so HMR and asset generation do not recreate that policy at each call site.
      */
     bundle(options: BrowserBundleOptions): Promise<BuildResult>;
     bundleGroupedEntries(entries: BrowserBundleGroupedEntry[], options: BrowserBundleGroupedOptions): Promise<BuildResult>;

package/src/services/assets/browser-bundle.service.js

@@ -1,47 +1,55 @@
-import {
-  getAppBrowserBuildPlugins,
-  getAppBuildExecutor,
-  getAppHmrBuildExecutor,
-  getAppTranspileOptions
-} from "../../build/build-adapter.js";
-import { mergeEcoBuildPlugins } from "../../build/build-manifest.js";
-class BrowserBundleService {
-  appConfig;
-  /**
-   * Creates the browser bundle boundary for one finalized app instance.
-   */
-  constructor(appConfig) {
-    this.appConfig = appConfig;
-  }
-  /**
-   * Runs one browser-targeted build through the app-owned executor.
-   *
-   * @remarks
-   * Browser defaults and app-owned browser build plugins are applied here so HMR
-   * and runtime asset generation do not have to recreate that policy at each call
-   * site.
-   */
-  async bundle(options) {
-    const { profile, excludeAppBuildPlugins, plugins, executor = "hmr", ...rawBuildOptions } = options;
-    const appBrowserPlugins = getAppBrowserBuildPlugins(this.appConfig);
-    const filteredAppBrowserPlugins = excludeAppBuildPlugins && excludeAppBuildPlugins.length > 0 ? appBrowserPlugins.filter((plugin) => !excludeAppBuildPlugins.includes(plugin.name)) : appBrowserPlugins;
-    const request = {
-      ...rawBuildOptions,
-      entrypoints: options.entrypoints,
-      ...getAppTranspileOptions(this.appConfig, profile),
-      plugins: mergeEcoBuildPlugins(plugins, filteredAppBrowserPlugins)
-    };
-    const buildExecutor = executor === "build" ? getAppBuildExecutor(this.appConfig) : getAppHmrBuildExecutor(this.appConfig);
-    return await buildExecutor.build(request);
-  }
-  async bundleGroupedEntries(entries, options) {
-    const request = {
-      ...options,
-      entrypoints: entries.map((entry) => entry.entrypoint)
-    };
-    return this.bundle(request);
-  }
+import { createBrowserBuildRequest } from '../../build/runtime/build-request-policy.js';
+import { requireBuildRuntime } from '../../build/runtime/build-runtime.js';
+import { startupTrace } from '../../diagnostics/startup-trace.js';
+import { requestBuildDedupe } from '../../diagnostics/request-build-dedupe.js';
+import { createBuildRequestIdentity } from '../../build/runtime/build-request-identity.js';
+function resolveBrowserBundleExecutor(appConfig, profile, executor) {
+    const buildRuntime = requireBuildRuntime(appConfig);
+    if (executor === 'hmr' && (profile === 'hmr-entrypoint' || profile === 'hmr-runtime')) {
+        return buildRuntime.getProfile('browser-hmr');
+    }
+    return buildRuntime.getProfile('route-module');
+}
+/**
+ * App-owned boundary for browser-oriented bundle work.
+ *
+ * @remarks
+ * Owns shared browser transpile defaults and ensures browser builds run through
+ * the app-owned executor rather than direct backend calls. Assembles a complete
+ * request via {@link createBrowserBuildRequest} before scheduling.
+ */
+export class BrowserBundleService {
+    appConfig;
+    constructor(appConfig) {
+        this.appConfig = appConfig;
+    }
+    /**
+     * Runs one browser-targeted build through the app-owned executor.
+     *
+     * @remarks
+     * Browser defaults, app-owned browser plugins, and
+     * {@link getAppSourceTransforms | app source transforms} are applied here
+     * so HMR and asset generation do not recreate that policy at each call site.
+     */
+    async bundle(options) {
+        const { profile, executor = 'hmr', ...requestInput } = options;
+        const request = createBrowserBuildRequest(this.appConfig, {
+            ...requestInput,
+            profile,
+        });
+        const buildExecutor = resolveBrowserBundleExecutor(this.appConfig, profile, executor);
+        const dedupeKey = createBuildRequestIdentity(request);
+        return requestBuildDedupe.dedupeBuild(dedupeKey, async () => {
+            const result = await buildExecutor.build(request);
+            startupTrace.recordBrowserBundle(result.outputs);
+            return result;
+        });
+    }
+    async bundleGroupedEntries(entries, options) {
+        const request = {
+            ...options,
+            entrypoints: Object.fromEntries(entries.map((entry) => [entry.entryName, entry.entrypoint])),
+        };
+        return this.bundle(request);
+    }
 }
-export {
-  BrowserBundleService
-};

package/src/services/assets/browser-runtime-asset-generation.d.ts

@@ -0,0 +1,17 @@
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+/**
+ * Returns the current browser-runtime asset generation for one app.
+ *
+ * @remarks
+ * Development HTML caches include this generation so rebuilt bootstrap and
+ * vendor URLs cannot leave stale script references behind.
+ */
+export declare function getBrowserRuntimeAssetGeneration(appConfig: EcoPagesAppConfig): number;
+/**
+ * Bumps browser-runtime asset generation and clears rendered HTML cache entries.
+ *
+ * @remarks
+ * Only call this when a previously cached runtime/page-script asset filepath changes.
+ * First inserts must not bump generation or cold start thrash-clears the HTML cache.
+ */
+export declare function bumpBrowserRuntimeAssetGeneration(appConfig: EcoPagesAppConfig): Promise<void>;

package/src/services/assets/browser-runtime-asset-generation.js

@@ -0,0 +1,28 @@
+import { clearAppPageCache } from '../cache/page-cache-service.js';
+import { isDevelopmentRuntime } from '../../utils/runtime.js';
+const generationByAppConfig = new WeakMap();
+/**
+ * Returns the current browser-runtime asset generation for one app.
+ *
+ * @remarks
+ * Development HTML caches include this generation so rebuilt bootstrap and
+ * vendor URLs cannot leave stale script references behind.
+ */
+export function getBrowserRuntimeAssetGeneration(appConfig) {
+    return generationByAppConfig.get(appConfig) ?? 0;
+}
+/**
+ * Bumps browser-runtime asset generation and clears rendered HTML cache entries.
+ *
+ * @remarks
+ * Only call this when a previously cached runtime/page-script asset filepath changes.
+ * First inserts must not bump generation or cold start thrash-clears the HTML cache.
+ */
+export async function bumpBrowserRuntimeAssetGeneration(appConfig) {
+    if (!isDevelopmentRuntime()) {
+        return;
+    }
+    const nextGeneration = getBrowserRuntimeAssetGeneration(appConfig) + 1;
+    generationByAppConfig.set(appConfig, nextGeneration);
+    await clearAppPageCache(appConfig);
+}

package/src/services/cache/cache.types.d.ts

@@ -8,6 +8,8 @@
 export interface RenderResult {
     html: string;
     strategy: CacheStrategy;
+    /** Source paths that contributed to this render; used for selective HTML cache invalidation. */
+    sourceDependencyPaths?: readonly string[];
 }
 /**
  * Render strategy configuration for pages.
@@ -83,8 +85,8 @@ export interface CacheConfig {
     defaultStrategy?: CacheStrategy;
     /**
      * Whether caching is enabled.
-     * Automatically disabled in dev mode unless explicitly set.
-     * @default true (production), false (development)
+     * In watch mode, defaults to `false` unless explicitly enabled.
+     * @default true in production builds, false in watch when omitted
      */
     enabled?: boolean;
     /**

package/src/services/cache/cache.types.js

@@ -0,0 +1,5 @@
+/**
+ * Cache types and interfaces for page caching and ISR
+ * @module
+ */
+export {};

package/src/services/cache/html-page-cache-dependency-index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Maps source dependency paths to rendered HTML cache keys for selective invalidation.
+ */
+export declare class HtmlPageCacheDependencyIndex {
+    private readonly sourcePathToCacheKeys;
+    private readonly cacheKeyToSourcePaths;
+    /**
+     * Records which source paths contributed to one cached HTML entry.
+     */
+    register(cacheKey: string, sourcePaths: readonly string[]): void;
+    /**
+     * Removes dependency metadata for one cache key.
+     */
+    unregister(cacheKey: string): void;
+    /**
+     * Returns cache keys that depend on any of the given source paths.
+     */
+    resolveCacheKeysForSourcePaths(sourcePaths: readonly string[]): string[];
+    clear(): void;
+}
+type CollectHtmlCacheSourceDependencyPathsInput = {
+    routeFile: string;
+    processedAssets: readonly {
+        sourceFilepath?: string;
+        bundledSourceFilepaths?: readonly string[];
+    }[];
+    graphDependencyPaths?: ReadonlySet<string>;
+    additionalSourcePaths?: readonly string[];
+};
+/**
+ * Merges route, graph, processed-asset, and caller-supplied source paths for HTML cache invalidation.
+ */
+export declare function collectHtmlCacheSourceDependencyPaths(input: CollectHtmlCacheSourceDependencyPathsInput): string[];
+export {};

package/src/services/cache/html-page-cache-dependency-index.js

@@ -0,0 +1,88 @@
+import path from 'node:path';
+/**
+ * Maps source dependency paths to rendered HTML cache keys for selective invalidation.
+ */
+export class HtmlPageCacheDependencyIndex {
+    sourcePathToCacheKeys = new Map();
+    cacheKeyToSourcePaths = new Map();
+    /**
+     * Records which source paths contributed to one cached HTML entry.
+     */
+    register(cacheKey, sourcePaths) {
+        this.unregister(cacheKey);
+        if (sourcePaths.length === 0) {
+            return;
+        }
+        const normalizedSourcePaths = new Set(sourcePaths.map((sourcePath) => normalizeSourcePath(sourcePath)));
+        this.cacheKeyToSourcePaths.set(cacheKey, normalizedSourcePaths);
+        for (const sourcePath of normalizedSourcePaths) {
+            const cacheKeys = this.sourcePathToCacheKeys.get(sourcePath) ?? new Set();
+            cacheKeys.add(cacheKey);
+            this.sourcePathToCacheKeys.set(sourcePath, cacheKeys);
+        }
+    }
+    /**
+     * Removes dependency metadata for one cache key.
+     */
+    unregister(cacheKey) {
+        const sourcePaths = this.cacheKeyToSourcePaths.get(cacheKey);
+        if (!sourcePaths) {
+            return;
+        }
+        for (const sourcePath of sourcePaths) {
+            const cacheKeys = this.sourcePathToCacheKeys.get(sourcePath);
+            cacheKeys?.delete(cacheKey);
+            if (cacheKeys?.size === 0) {
+                this.sourcePathToCacheKeys.delete(sourcePath);
+            }
+        }
+        this.cacheKeyToSourcePaths.delete(cacheKey);
+    }
+    /**
+     * Returns cache keys that depend on any of the given source paths.
+     */
+    resolveCacheKeysForSourcePaths(sourcePaths) {
+        const cacheKeys = new Set();
+        for (const sourcePath of sourcePaths) {
+            const normalizedSourcePath = normalizeSourcePath(sourcePath);
+            const matches = this.sourcePathToCacheKeys.get(normalizedSourcePath);
+            if (!matches) {
+                continue;
+            }
+            for (const cacheKey of matches) {
+                cacheKeys.add(cacheKey);
+            }
+        }
+        return [...cacheKeys];
+    }
+    clear() {
+        this.sourcePathToCacheKeys.clear();
+        this.cacheKeyToSourcePaths.clear();
+    }
+}
+function normalizeSourcePath(sourcePath) {
+    return path.resolve(sourcePath);
+}
+/**
+ * Merges route, graph, processed-asset, and caller-supplied source paths for HTML cache invalidation.
+ */
+export function collectHtmlCacheSourceDependencyPaths(input) {
+    const sourcePaths = new Set([normalizeSourcePath(input.routeFile)]);
+    for (const additionalPath of input.additionalSourcePaths ?? []) {
+        sourcePaths.add(normalizeSourcePath(additionalPath));
+    }
+    if (input.graphDependencyPaths) {
+        for (const graphPath of input.graphDependencyPaths) {
+            sourcePaths.add(normalizeSourcePath(graphPath));
+        }
+    }
+    for (const asset of input.processedAssets) {
+        if (asset.sourceFilepath) {
+            sourcePaths.add(normalizeSourcePath(asset.sourceFilepath));
+        }
+        for (const bundledSourceFilepath of asset.bundledSourceFilepaths ?? []) {
+            sourcePaths.add(normalizeSourcePath(bundledSourceFilepath));
+        }
+    }
+    return [...sourcePaths];
+}

package/src/services/cache/index.d.ts

@@ -4,4 +4,6 @@
  */
 export type { CacheConfig, CacheEntry, CacheResult, CacheStats, CacheStore, CacheStrategy, RenderResult, } from './cache.types.js';
 export { MemoryCacheStore, type MemoryCacheStoreOptions } from './memory-cache-store.js';
+export { HtmlPageCacheDependencyIndex } from './html-page-cache-dependency-index.js';
 export { getCacheControlHeader, PageCacheService, type PageCacheServiceOptions } from './page-cache-service.js';
+export { clearAppPageCache, getAppPageCacheService, invalidateAppPageCacheBySourcePaths, registerAppPageCacheService, } from './page-cache-service.js';