@ecopages/core 0.2.0-beta.4 → 0.2.0-beta.40

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

@@ -1,287 +1,270 @@
-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);
+import { DefaultHtmlRewriterProvider, } from './html-rewriter-provider.service.js';
+import { buildProcessedAssetDedupeKey, dedupeProcessedAssets, } from '../../route-renderer/orchestration/page-browser-graph/processed-asset-dedupe.js';
+export 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);
     }
-  }
-  /**
-   * 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 });
+    formatAttributes(attrs) {
+        if (!attrs)
+            return '';
+        return ` ${Object.entries(attrs)
+            .map(([key, value]) => `${key}="${value}"`)
+            .join(' ')}`;
     }
-  }
-  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 });
+    generateScriptTag(dep) {
+        return dep.inline
+            ? `<script${this.formatAttributes(dep.attributes)}>${dep.content}</script>`
+            : `<script src="${dep.srcUrl}"${this.formatAttributes(dep.attributes)}></script>`;
     }
-  }
-  /**
-   * 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;
+    generateStylesheetTag(dep) {
+        return dep.inline
+            ? `<style${this.formatAttributes(dep.attributes)}>${dep.content}</style>`
+            : `<link rel="stylesheet" href="${dep.srcUrl}"${this.formatAttributes(dep.attributes)}>`;
     }
-    const closingTag = `</${tag}>`;
-    const lowerHtml = html.toLowerCase();
-    const closingTagIndex = lowerHtml.lastIndexOf(closingTag);
-    if (closingTagIndex !== -1) {
-      return `${html.slice(0, closingTagIndex)}${content}${html.slice(closingTagIndex)}`;
+    appendDependencies(element, dependencies) {
+        for (const dep of dependencies) {
+            const tag = dep.kind === 'script' ? this.generateScriptTag(dep) : this.generateStylesheetTag(dep);
+            element.append(tag, { html: true });
+        }
     }
-    if (tag === "head") {
-      return `${content}${html}`;
+    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 });
+        }
     }
-    return `${html}${content}`;
-  }
-  injectAfterOpeningTag(html, tag, content) {
-    if (!content) {
-      return html;
+    /**
+     * 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}`;
     }
-    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}`);
+    injectAfterOpeningTag(html, tag, content) {
+        if (!content) {
+            return html;
+        }
+        const openingTag = new RegExp(`<${tag}\\b[^>]*>`, 'i');
+        const match = html.match(openingTag);
+        if (!match || match.index === undefined) {
+            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)}`;
     }
-    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;
+    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'),
+        };
     }
-    const attrs = this.buildAttributeString(attributes);
-    if (attrs.length === 0) {
-      return html;
+    /**
+     * Replaces the current processed dependency set used during HTML finalization.
+     */
+    setProcessedDependencies(processedDependencies) {
+        this.pagePackage = undefined;
+        this.processedDependencies = processedDependencies;
     }
-    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;
+    /**
+     * Replaces the current structured page package used during HTML finalization.
+     */
+    setPagePackage(pagePackage) {
+        this.pagePackage = pagePackage;
+        this.processedDependencies = this.resolvePagePackageHtmlDependencies(pagePackage);
     }
-    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;
+    /**
+     * Returns the processed dependencies queued for the next transform pass.
+     */
+    getProcessedDependencies() {
+        return this.processedDependencies;
     }
-    const attrs = this.buildAttributeString(attributes);
-    if (attrs.length === 0) {
-      return html;
+    /**
+     * Returns the structured page package queued for the next transform pass.
+     */
+    getPagePackage() {
+        return this.pagePackage;
     }
-    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;
+    /**
+     * Applies attributes to the opening `<html>` tag when present.
+     */
+    applyAttributesToHtmlElement(html, attributes) {
+        const htmlTagMatch = html.match(/<html\b[^>]*>/i);
+        if (!htmlTagMatch || htmlTagMatch.index === undefined) {
+            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)}`;
     }
-    const attrs = this.buildAttributeString(attributes);
-    if (attrs.length === 0) {
-      return html;
+    /**
+     * Applies attributes to the first element nested directly under `<body>`.
+     */
+    applyAttributesToFirstBodyElement(html, attributes) {
+        const bodyMatch = html.match(/<body\b[^>]*>/i);
+        if (!bodyMatch || bodyMatch.index === undefined) {
+            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 === undefined) {
+            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)}`;
     }
-    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");
+    /**
+     * 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 === undefined) {
+            return html;
         }
-      }).on("body", {
-        element: (element) => {
-          this.applyContributions(element, bodyPrepend, "prepend");
-          this.appendDependencies(element, body);
-          this.applyContributions(element, bodyAppend, "append");
+        const attrs = this.buildAttributeString(attributes);
+        if (attrs.length === 0) {
+            return html;
         }
-      });
-      return htmlRewriter.transform(res);
+        const injectionOffset = firstTagMatch[1].length + firstTagMatch[2].length;
+        return `${html.slice(0, injectionOffset)}${attrs}${html.slice(injectionOffset)}`;
     }
-    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);
+    /**
+     * 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 = [], pagePackage) {
+        const { head, body } = this.groupDependenciesByPosition(pagePackage);
+        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);
         }
-        return acc;
-      },
-      { head: [], body: [] }
-    );
-  }
-  resolvePagePackageHtmlDependencies(pagePackage) {
-    if (!pagePackage.pageBrowserGraph) {
-      return pagePackage.htmlAssets;
+        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(pagePackageOverride) {
+        const dependencies = pagePackageOverride
+            ? this.resolvePagePackageHtmlDependencies(pagePackageOverride)
+            : 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('');
     }
-    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

@@ -1,5 +1,6 @@
-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';
+import type { EcoPagesAppConfig, RegisteredScriptEntrypointChangeHandler } from '../../types/internal-types.js';
+export type { RegisteredScriptEntrypointChangeHandler };
+export type DevelopmentInvalidationCategory = 'public-asset' | 'additional-watch' | 'include-source' | 'explicit-server-view' | 'route-source' | 'processor-owned-asset' | 'server-source' | 'other';
 /**
  * Framework-owned invalidation plan for one changed file.
  *
@@ -38,6 +39,14 @@ export declare class DevelopmentInvalidationService {
      * Invalidates the app-owned server-module graph.
      */
     invalidateServerModules(changedFiles?: string[]): void;
+    /**
+     * Registers an integration-owned handler for registered script entrypoint edits.
+     */
+    registerRegisteredScriptEntrypointChangeHandler(handler: RegisteredScriptEntrypointChangeHandler): void;
+    /**
+     * Notifies integration handlers that a registered script entrypoint changed.
+     */
+    notifyRegisteredScriptEntrypointChange(filePath: string): Promise<void>;
     /**
      * Resets runtime-owned graph state and invalidates server modules.
      */
@@ -62,6 +71,15 @@ export declare class DevelopmentInvalidationService {
      * Returns whether the file is an include/template source file.
      */
     isIncludeSourceFile(filePath: string): boolean;
+    /**
+     * Returns whether the file is an explicit server-rendered view module.
+     *
+     * @remarks
+     * These modules are typically registered through `renderServerModule` in
+     * `app.ts` rather than the filesystem router. They need a full browser reload
+     * because their HTML is produced on the server, not through client HMR entrypoints.
+     */
+    isExplicitServerViewFile(filePath: string): boolean;
     /**
      * Returns whether the file is a server-executed source module outside the
      * special route/include buckets.
@@ -69,6 +87,11 @@ export declare class DevelopmentInvalidationService {
     isServerModuleSourceFile(filePath: string): boolean;
     /**
      * Returns whether a processor owns the changed file as an asset input.
+     *
+     * @remarks
+     * Watch config drives processor notifications only. Asset ownership requires
+     * declared capabilities so dependency-only watches (for example content
+     * collection MDX scans) do not skip server invalidation and HMR.
      */
     isProcessorOwnedAsset(filePath: string): boolean;
 }