@ecopages/core 0.2.0-beta.27 → 0.2.0-beta.29

package/src/route-renderer/orchestration/page-browser-graph/page-browser-graph-merge.utils.js

@@ -0,0 +1,29 @@
+import { createPagePackage } from "../../../services/assets/asset-processing-service/index.js";
+import { buildProcessedAssetDedupeKey, dedupeProcessedAssets } from "./processed-asset-dedupe.js";
+function mergePageBrowserGraph(currentPagePackage, processedDependencies, pageBrowserGraph) {
+  const mergedGraph = currentPagePackage?.pageBrowserGraph ? {
+    entryAssets: dedupeProcessedAssets([
+      ...currentPagePackage.pageBrowserGraph.entryAssets,
+      ...pageBrowserGraph.entryAssets
+    ]),
+    chunkAssets: dedupeProcessedAssets([
+      ...currentPagePackage.pageBrowserGraph.chunkAssets,
+      ...pageBrowserGraph.chunkAssets
+    ])
+  } : pageBrowserGraph;
+  const pageBrowserGraphAssetKeys = new Set(
+    [...mergedGraph.entryAssets, ...mergedGraph.chunkAssets].map((asset) => buildProcessedAssetDedupeKey(asset))
+  );
+  const baseAssets = currentPagePackage ? currentPagePackage.assets.filter(
+    (asset) => !pageBrowserGraphAssetKeys.has(buildProcessedAssetDedupeKey(asset))
+  ) : processedDependencies;
+  return {
+    pagePackage: createPagePackage(dedupeProcessedAssets(baseAssets), {
+      pageBrowserGraph: mergedGraph
+    }),
+    mergedGraph
+  };
+}
+export {
+  mergePageBrowserGraph
+};

package/src/route-renderer/orchestration/{page-browser-graph-session.d.ts → page-browser-graph/page-browser-graph-session.d.ts}

@@ -1,6 +1,6 @@
-import type { EcoPagesAppConfig } from '../../types/internal-types.js';
-import type { PageBrowserGraphContribution, PageBrowserGraphResult } from '../../types/public-types.js';
-import type { ProcessedAsset } from '../../services/assets/asset-processing-service/assets.types.js';
+import type { EcoPagesAppConfig } from '../../../types/internal-types.js';
+import type { PageBrowserGraphContribution, PageBrowserGraphResult } from '../../../types/public-types.js';
+import type { ProcessedAsset } from '../../../services/assets/asset-processing-service/assets.types.js';
 export type GraphPolicy = 'development' | 'production';
 export type GraphKey = {
     integrationName: string;

package/src/route-renderer/orchestration/{page-browser-graph-session.js → page-browser-graph/page-browser-graph-session.js}

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { createHash } from "node:crypto";
-import { appLogger } from "../../global/app-logger.js";
+import { appLogger } from "../../../global/app-logger.js";
 function isSkipCacheGroupedOutcome(outcome) {
   return "skipCache" in outcome;
 }

package/src/route-renderer/orchestration/{page-browser-graph.service.d.ts → page-browser-graph/page-browser-graph.service.d.ts}

@@ -1,6 +1,6 @@
-import type { EcoPagesAppConfig } from '../../types/internal-types.js';
-import type { PageBrowserGraphContribution, PageBrowserGraphResult } from '../../types/public-types.js';
-import { type AssetProcessingService } from '../../services/assets/asset-processing-service/index.js';
+import type { EcoPagesAppConfig } from '../../../types/internal-types.js';
+import type { PageBrowserGraphContribution, PageBrowserGraphResult } from '../../../types/public-types.js';
+import { type AssetProcessingService } from '../../../services/assets/asset-processing-service/index.js';
 import { type GraphPolicy } from './page-browser-graph-session.js';
 export type PageBrowserGraphResolveInput = {
     routeFile: string;

package/src/route-renderer/orchestration/{page-browser-graph.service.js → page-browser-graph/page-browser-graph.service.js}

@@ -1,9 +1,9 @@
 import path from "node:path";
 import { fileSystem } from "@ecopages/file-system";
 import {
-} from "../../services/assets/asset-processing-service/index.js";
-import { appLogger } from "../../global/app-logger.js";
-import { startupTrace } from "../../diagnostics/startup-trace.js";
+} from "../../../services/assets/asset-processing-service/index.js";
+import { appLogger } from "../../../global/app-logger.js";
+import { startupTrace } from "../../../diagnostics/startup-trace.js";
 import {
   collectPageBrowserGraphDependencyPaths,
   createPageBrowserGraphEntryFingerprint,

package/src/route-renderer/orchestration/{processed-asset-dedupe.d.ts → page-browser-graph/processed-asset-dedupe.d.ts}

@@ -1,3 +1,3 @@
-import type { ProcessedAsset } from '../../services/assets/asset-processing-service/index.js';
+import type { ProcessedAsset } from '../../../services/assets/asset-processing-service/index.js';
 export declare function buildProcessedAssetDedupeKey(asset: ProcessedAsset): string;
 export declare function dedupeProcessedAssets(assets: ProcessedAsset[]): ProcessedAsset[];

package/src/route-renderer/orchestration/{integration-route-render-adapter.d.ts → route-pipeline/integration-route-render-adapter.d.ts}

@@ -1,6 +1,6 @@
-import type { ProcessedAsset } from '../../services/assets/asset-processing-service/index.js';
-import type { HtmlDocumentContribution } from '../../services/html/html-transformer.service.js';
-import type { EcoComponent, EcoPageFile, IntegrationRendererRenderOptions, PageBrowserGraphContribution, PageBrowserGraphContributionContext, PagePackageResult, RouteRendererBody, RouteRendererOptions } from '../../types/public-types.js';
+import type { ProcessedAsset } from '../../../services/assets/asset-processing-service/index.js';
+import type { HtmlDocumentContribution } from '../../../services/html/html-transformer.service.js';
+import type { EcoComponent, EcoPageFile, IntegrationRendererRenderOptions, PageBrowserGraphContribution, PageBrowserGraphContributionContext, PagePackageResult, RouteRendererBody, RouteRendererOptions } from '../../../types/public-types.js';
 import type { RouteHtmlFinalization, RouteRenderOrchestratorAdapter, RouteRenderOrchestratorResolvedInputs } from './route-render-orchestrator.js';
 /**
  * Host surface required to build the orchestrator adapter for one integration renderer.

package/src/route-renderer/orchestration/{integration-route-render-adapter.js → route-pipeline/integration-route-render-adapter.js}

@@ -1,4 +1,4 @@
-import { loadPageBrowserGraphContribution } from "./page-browser-graph-contribution.loader.js";
+import { loadPageBrowserGraphContribution } from "../page-browser-graph/page-browser-graph-contribution.loader.js";
 import { buildRouteHtmlFinalization } from "./route-html-finalization.service.js";
 function createIntegrationRouteRenderAdapter(host) {
   return {

package/src/route-renderer/orchestration/route-pipeline/marker-artifact.utils.d.ts

@@ -0,0 +1,6 @@
+export declare function decodeHtmlEntities(value: string): string;
+export declare function normalizeUnresolvedMarkerArtifactHtml(html: string): string;
+export declare function inspectUnresolvedMarkerArtifactHtml(html: string): {
+    hasUnresolvedMarkerArtifacts: boolean;
+    normalizedHtml: string;
+};

package/src/route-renderer/orchestration/route-pipeline/marker-artifact.utils.js

@@ -0,0 +1,27 @@
+function decodeHtmlEntities(value) {
+  let decoded = value;
+  let previous;
+  do {
+    previous = decoded;
+    decoded = decoded.replaceAll("&quot;", '"').replaceAll("&#39;", "'").replaceAll("&#x27;", "'").replaceAll("&lt;", "<").replaceAll("&gt;", ">").replaceAll("&amp;", "&");
+  } while (decoded !== previous);
+  return decoded;
+}
+function normalizeUnresolvedMarkerArtifactHtml(html) {
+  return html.replace(
+    /&(?:amp;)?lt;eco-marker\b[\s\S]*?&(?:amp;)?gt;&(?:amp;)?lt;\/eco-marker&(?:amp;)?gt;/g,
+    (marker) => decodeHtmlEntities(marker)
+  );
+}
+function inspectUnresolvedMarkerArtifactHtml(html) {
+  const normalizedHtml = normalizeUnresolvedMarkerArtifactHtml(html);
+  return {
+    normalizedHtml,
+    hasUnresolvedMarkerArtifacts: normalizedHtml.includes("<eco-marker")
+  };
+}
+export {
+  decodeHtmlEntities,
+  inspectUnresolvedMarkerArtifactHtml,
+  normalizeUnresolvedMarkerArtifactHtml
+};

package/src/route-renderer/orchestration/route-pipeline/robots-meta.contribution.d.ts

@@ -0,0 +1,15 @@
+import type { HtmlDocumentContribution } from '../../../services/html/html-transformer.service.js';
+import type { PageMetadataProps, PageRobotsMetadata } from '../../../types/public-types.js';
+/**
+ * Builds a head contribution for non-default `metadata.robots` values.
+ *
+ * @remarks
+ * When `robots` is omitted or matches the default `index,follow` behaviour,
+ * no tag is emitted (Next.js parity). Otherwise a single
+ * `<meta name="robots" content="...">` contribution is returned.
+ */
+export declare function buildRobotsMetaContribution(metadata: Pick<PageMetadataProps, 'robots'>): HtmlDocumentContribution | undefined;
+/**
+ * Formats robots directives for a meta tag, or `undefined` when defaults apply.
+ */
+export declare function formatRobotsMetaContent(robots: PageRobotsMetadata | undefined): string | undefined;

package/src/route-renderer/orchestration/route-pipeline/robots-meta.contribution.js

@@ -0,0 +1,36 @@
+import { escapeHtmlAttribute } from "../../../utils/html-escaping.js";
+function buildRobotsMetaContribution(metadata) {
+  const content = formatRobotsMetaContent(metadata.robots);
+  if (!content) {
+    return void 0;
+  }
+  return {
+    placement: "head-append",
+    html: `<meta name="robots" content="${escapeHtmlAttribute(content)}">`
+  };
+}
+function formatRobotsMetaContent(robots) {
+  if (!robots) {
+    return void 0;
+  }
+  const index = robots.index !== false;
+  const follow = robots.follow !== false;
+  const directives = [];
+  if (!index) {
+    directives.push("noindex");
+  }
+  if (!follow) {
+    directives.push("nofollow");
+  }
+  if (robots.nocache) {
+    directives.push("nocache");
+  }
+  if (directives.length === 0) {
+    return void 0;
+  }
+  return directives.join(", ");
+}
+export {
+  buildRobotsMetaContribution,
+  formatRobotsMetaContent
+};

package/src/route-renderer/orchestration/{route-html-finalization.service.d.ts → route-pipeline/route-html-finalization.service.d.ts}

@@ -1,5 +1,5 @@
-import type { HtmlDocumentContribution } from '../../services/html/html-transformer.service.js';
-import type { IntegrationRendererRenderOptions } from '../../types/public-types.js';
+import type { HtmlDocumentContribution } from '../../../services/html/html-transformer.service.js';
+import type { IntegrationRendererRenderOptions } from '../../../types/public-types.js';
 import type { RouteHtmlFinalization } from './route-render-orchestrator.js';
 export type RouteHtmlFinalizationContext<C> = {
     renderOptions: IntegrationRendererRenderOptions<C>;
@@ -12,5 +12,9 @@ export type RouteHtmlFinalizationContext<C> = {
 };
 /**
  * Builds the structural HTML finalization plan for one prepared route render.
+ *
+ * @remarks
+ * Merges core robots meta contributions with integration-owned document
+ * contributions so page-level `metadata.robots` works across templates.
  */
 export declare function buildRouteHtmlFinalization<C>(context: RouteHtmlFinalizationContext<C>): RouteHtmlFinalization;

package/src/route-renderer/orchestration/{route-html-finalization.service.js → route-pipeline/route-html-finalization.service.js}

@@ -1,9 +1,12 @@
+import { buildRobotsMetaContribution } from "./robots-meta.contribution.js";
 function buildRouteHtmlFinalization(context) {
   const { renderOptions } = context;
   const documentAttributes = context.getDocumentAttributes(renderOptions);
-  const htmlContributions = context.getHtmlDocumentContributions({ renderOptions, partial: false });
+  const integrationContributions = context.getHtmlDocumentContributions({ renderOptions, partial: false }) ?? [];
+  const robotsContribution = buildRobotsMetaContribution(renderOptions.metadata ?? {});
+  const htmlContributions = robotsContribution ? [robotsContribution, ...integrationContributions] : integrationContributions;
   const hasStructuralFinalization = documentAttributes && Object.keys(documentAttributes).length > 0;
-  if (!hasStructuralFinalization && (!htmlContributions || htmlContributions.length === 0)) {
+  if (!hasStructuralFinalization && htmlContributions.length === 0) {
     return {};
   }
   return {

package/src/route-renderer/orchestration/{route-prepared-options.builder.d.ts → route-pipeline/route-prepared-options.builder.d.ts}

@@ -1,6 +1,6 @@
-import type { EcoPagesAppConfig } from '../../types/internal-types.js';
-import type { EcoComponent, EcoPageComponent, EcoPageFile, HtmlTemplateProps, IntegrationRendererRenderOptions, PageBrowserGraphResult, PageMetadataProps, EcoPageLayoutEntry, RouteRendererOptions } from '../../types/public-types.js';
-import { type ProcessedAsset } from '../../services/assets/asset-processing-service/index.js';
+import type { EcoPagesAppConfig } from '../../../types/internal-types.js';
+import type { EcoComponent, EcoPageComponent, EcoPageFile, HtmlTemplateProps, IntegrationRendererRenderOptions, PageBrowserGraphResult, PageMetadataProps, EcoPageLayoutEntry, RouteRendererOptions } from '../../../types/public-types.js';
+import { type ProcessedAsset } from '../../../services/assets/asset-processing-service/index.js';
 type PreparedRenderInputs = {
     Page: EcoPageFile['default'] | EcoPageComponent<any>;
     HtmlTemplate: EcoComponent<HtmlTemplateProps>;

package/src/route-renderer/orchestration/{route-prepared-options.builder.js → route-pipeline/route-prepared-options.builder.js}

@@ -1,13 +1,17 @@
-import { createPagePackage } from "../../services/assets/asset-processing-service/index.js";
-import { dedupeProcessedAssets } from "./processed-asset-dedupe.js";
+import { createPagePackage } from "../../../services/assets/asset-processing-service/index.js";
+import { dedupeProcessedAssets } from "../page-browser-graph/processed-asset-dedupe.js";
 import { createPageLocalsProxy } from "./route-prepared-options.utils.js";
 function buildPreparedRenderOptions(input) {
   const { routeOptions, resolvedInputs, resolvedDependencies, allDependencies, pageBrowserGraph, appConfig } = input;
   const { Page, HtmlTemplate, Layouts, Layout, layoutEntries, props, metadata, integrationSpecificProps } = resolvedInputs;
   const dedupedDependencies = dedupeProcessedAssets(allDependencies);
   const pagePackage = createPagePackage(dedupedDependencies, { pageBrowserGraph });
-  const pageProps = {
+  const resolvedProps = {
     ...props,
+    ...routeOptions.props ?? {}
+  };
+  const pageProps = {
+    ...resolvedProps,
     params: routeOptions.params || {},
     query: routeOptions.query || {}
   };
@@ -25,7 +29,7 @@ function buildPreparedRenderOptions(input) {
     Layouts,
     Layout,
     layoutEntries,
-    props,
+    props: resolvedProps,
     Page,
     metadata,
     params: routeOptions.params || {},

package/src/route-renderer/orchestration/{route-prepared-options.utils.js → route-pipeline/route-prepared-options.utils.js}

@@ -1,4 +1,4 @@
-import { LocalsAccessError } from "../../errors/locals-access-error.js";
+import { LocalsAccessError } from "../../../errors/locals-access-error.js";
 function createPageLocalsProxy(filePath) {
   const errorMessage = `[ecopages] Request locals are only available during request-time rendering with cache: 'dynamic'. Page: ${filePath}. If you meant to use locals here, set cache: 'dynamic' and provide locals from route middleware/handlers.`;
   return new Proxy(

package/src/route-renderer/orchestration/{route-render-orchestrator.d.ts → route-pipeline/route-render-orchestrator.d.ts}

@@ -1,9 +1,9 @@
-import type { EcoPagesAppConfig } from '../../types/internal-types.js';
-import type { EcoComponent, EcoPageComponent, EcoPageFile, HtmlTemplateProps, IntegrationRendererRenderOptions, PageBrowserGraphContribution, PageBrowserGraphResult, PageMetadataProps, RouteRendererBody, RouteRendererOptions, RouteRenderResult, EcoPageLayoutEntry } from '../../types/public-types.js';
-import type { AssetProcessingService, ProcessedAsset } from '../../services/assets/asset-processing-service/index.js';
-import type { HtmlDocumentContribution } from '../../services/html/html-transformer.service.js';
-import { OwnershipValidationService } from './ownership-validation.service.js';
-import { PageBrowserGraphService } from './page-browser-graph.service.js';
+import type { EcoPagesAppConfig } from '../../../types/internal-types.js';
+import type { EcoComponent, EcoPageComponent, EcoPageFile, HtmlTemplateProps, IntegrationRendererRenderOptions, PageBrowserGraphContribution, PageBrowserGraphResult, PageMetadataProps, RouteRendererBody, RouteRendererOptions, RouteRenderResult, EcoPageLayoutEntry } from '../../../types/public-types.js';
+import type { AssetProcessingService, ProcessedAsset } from '../../../services/assets/asset-processing-service/index.js';
+import type { HtmlDocumentContribution } from '../../../services/html/html-transformer.service.js';
+import { OwnershipValidationService } from '../ownership-graph/ownership-validation.service.js';
+import { PageBrowserGraphService } from '../page-browser-graph/page-browser-graph.service.js';
 export type RouteRenderOrchestratorResolvedInputs = {
     Page: EcoPageFile['default'] | EcoPageComponent<any>;
     HtmlTemplate: EcoComponent<HtmlTemplateProps>;

package/src/route-renderer/orchestration/{route-render-orchestrator.js → route-pipeline/route-render-orchestrator.js}

@@ -1,12 +1,15 @@
-import { inspectUnresolvedMarkerArtifactHtml } from "./render-output.utils.js";
-import { OwnershipValidationService, throwIfOwnershipInvalid } from "./ownership-validation.service.js";
+import { inspectUnresolvedMarkerArtifactHtml } from "./marker-artifact.utils.js";
+import {
+  OwnershipValidationService,
+  throwIfOwnershipInvalid
+} from "../ownership-graph/ownership-validation.service.js";
 import {
   buildEagerSsrLazyAssetsFromGraph,
   collectResolvedLazyTriggersFromGraph,
   collectUsedIntegrationDependenciesFromGraph
-} from "./component-graph-collectors.js";
-import { buildGlobalInjectorAssets } from "./global-injector-assets.service.js";
-import { PageBrowserGraphService } from "./page-browser-graph.service.js";
+} from "../ownership-graph/component-graph-collectors.js";
+import { buildGlobalInjectorAssets } from "../page-browser-graph/global-injector-assets.service.js";
+import { PageBrowserGraphService } from "../page-browser-graph/page-browser-graph.service.js";
 import { buildPreparedRenderOptions } from "./route-prepared-options.builder.js";
 class RouteRenderOrchestrator {
   appConfig;

package/src/route-renderer/orchestration/string-markup-renderer.js

@@ -1,5 +1,5 @@
 import { IntegrationRenderer } from "./integration-renderer.js";
-import { resolveInnermostPageLayout } from "./layout-shell-props.service.js";
+import { resolveInnermostPageLayout } from "./document-shell/layout-shell-props.service.js";
 class StringMarkupRenderer extends IntegrationRenderer {
   async renderComponent(input) {
     if (typeof input.component !== "function") {

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

@@ -4,7 +4,7 @@ import {
 import {
   buildProcessedAssetDedupeKey,
   dedupeProcessedAssets
-} from "../../route-renderer/orchestration/processed-asset-dedupe.js";
+} from "../../route-renderer/orchestration/page-browser-graph/processed-asset-dedupe.js";
 class HtmlTransformerService {
   processedDependencies = [];
   pagePackage;

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

@@ -87,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;
 }

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

@@ -218,21 +218,20 @@ class DevelopmentInvalidationService {
   }
   /**
    * 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) {
     for (const processor of this.appConfig.processors.values()) {
       const capabilities = processor.getAssetCapabilities?.() ?? [];
-      if (capabilities.length > 0) {
-        const matchesConfiguredAsset = typeof processor.matchesFileFilter !== "function" || processor.matchesFileFilter(filePath);
-        if (matchesConfiguredAsset && capabilities.some((capability) => processor.canProcessAsset?.(capability.kind, filePath))) {
-          return true;
-        }
+      if (capabilities.length === 0) {
         continue;
       }
-      const watchConfig = processor.getWatchConfig();
-      if (!watchConfig) continue;
-      const { extensions = [] } = watchConfig;
-      if (extensions.length && extensions.some((ext) => filePath.endsWith(ext))) {
+      const matchesConfiguredAsset = typeof processor.matchesFileFilter !== "function" || processor.matchesFileFilter(filePath);
+      if (matchesConfiguredAsset && capabilities.some((capability) => processor.canProcessAsset?.(capability.kind, filePath))) {
         return true;
       }
     }

package/src/static-site-generator/README.md

@@ -29,8 +29,10 @@ It should not invent a parallel rendering stack just for build mode.
 
 | File                           | Role                                                                         |
 | ------------------------------ | ---------------------------------------------------------------------------- |
-| `static-site-generator.ts`     | Route enumeration, HTML artifact writes, integration export hooks            |
+| `static-site-generator.ts`     | Route enumeration, HTML artifact writes, integration export hooks, sitemap   |
 | `static-export-context.ts`     | Hook context type for `beforeStaticExport` / `afterStaticExport`             |
+| `sitemap.ts`                   | Pure sitemap.xml renderer                                                    |
+| `sitemap-routes.ts`            | Sitemap location assembly (`exclude`, `extraUrls`, dedupe)                   |
 | `static-build-invalidation.ts` | `dist/` reset policy, production cache clearing, static-render cache context |
 
 Build-input fingerprinting (`hashAppConfigFile`, `createBuildInputsFingerprint`) lives in `packages/core/src/build/cache/build-input-fingerprint.ts` and is shared with server-entry and unified-graph caches.
@@ -56,4 +58,10 @@ Integrations may implement:
 - `beforeStaticExport(context)` — runs after unified-graph prebuild, before page rendering
 - `afterStaticExport(context)` — runs in a `finally` block after generation completes
 
+When `appConfig.sitemap.enabled` is true, `sitemap.xml` is written **after** `afterStaticExport` so integration-generated URLs can be listed via `extraUrls`.
+
+Sitemap eligibility is decided during successful page export (`activeStaticPathnames` plus `robots.index !== false`, fail-closed on metadata errors). `resolveSitemapLocations` then applies `exclude` and appends `extraUrls`.
+
+`StaticExportContext.routes` is the unfiltered static-generation route list. Sitemap filtering is applied separately.
+
 See `StaticExportContext` in `static-export-context.ts`.

package/src/static-site-generator/production-page-browser-graph-prebuild.js

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { getAppPageBrowserGraphSession } from "../route-renderer/orchestration/page-browser-graph-session.js";
+import { getAppPageBrowserGraphSession } from "../route-renderer/orchestration/page-browser-graph/page-browser-graph-session.js";
 function shouldPrebuildProductionPageBrowserGraphs() {
   return process.env.NODE_ENV === "production";
 }

package/src/static-site-generator/sitemap-routes.d.ts

@@ -0,0 +1,14 @@
+import type { SitemapConfig } from '../types/public-types.js';
+/**
+ * Builds the ordered absolute locations for sitemap.xml.
+ *
+ * @remarks
+ * `eligiblePathnames` must already be successfully exported and robots-indexable.
+ * Filtering here is only `sitemap.exclude`, then `extraUrls` are appended.
+ * `extraUrls` always include (deduped) and are not subject to `exclude` or page robots.
+ */
+export declare function resolveSitemapLocations(input: {
+    eligiblePathnames: readonly string[];
+    sitemap: SitemapConfig;
+    baseUrl: string;
+}): string[];

package/src/static-site-generator/sitemap-routes.js

@@ -0,0 +1,31 @@
+import { matchesAnyPathPattern, normalizePathname } from "../utils/path-pattern.js";
+import { buildSitemapLocation } from "./sitemap.js";
+function resolveSitemapLocations(input) {
+  const exclude = input.sitemap.exclude ?? [];
+  const locations = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const pathname of input.eligiblePathnames) {
+    const normalized = normalizePathname(pathname);
+    if (matchesAnyPathPattern(normalized, exclude)) {
+      continue;
+    }
+    const location = buildSitemapLocation(input.baseUrl, normalized);
+    if (seen.has(location)) {
+      continue;
+    }
+    seen.add(location);
+    locations.push(location);
+  }
+  for (const extraUrl of input.sitemap.extraUrls ?? []) {
+    const location = buildSitemapLocation(input.baseUrl, extraUrl);
+    if (seen.has(location)) {
+      continue;
+    }
+    seen.add(location);
+    locations.push(location);
+  }
+  return locations;
+}
+export {
+  resolveSitemapLocations
+};

package/src/static-site-generator/sitemap.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Joins a base origin with a pathname or absolute URL into a sitemap `<loc>` value.
+ *
+ * @remarks
+ * Trailing slashes are stripped except for the site root (`/`). Absolute `http(s)`
+ * URLs in `extraUrls` are returned as-is (still slash-normalized).
+ */
+export declare function buildSitemapLocation(baseUrl: string, pathnameOrUrl: string): string;
+/**
+ * Renders a sitemap.org 0.9 urlset document from absolute location URLs.
+ *
+ * @remarks
+ * Callers are responsible for deduplication; this serializer preserves input order.
+ */
+export declare function renderSitemap(locations: readonly string[]): string;

package/src/static-site-generator/sitemap.js

@@ -0,0 +1,33 @@
+import { escapeXmlText } from "../utils/html-escaping.js";
+import { normalizePathname } from "../utils/path-pattern.js";
+function buildSitemapLocation(baseUrl, pathnameOrUrl) {
+  const trimmed = pathnameOrUrl.trim();
+  if (/^https?:\/\//i.test(trimmed)) {
+    return normalizeLocation(trimmed);
+  }
+  const origin = baseUrl.replace(/\/+$/, "");
+  const pathname = normalizePathname(trimmed);
+  return pathname === "/" ? `${origin}/` : `${origin}${pathname}`;
+}
+function renderSitemap(locations) {
+  const urls = locations.map((loc) => `  <url>
+    <loc>${escapeXmlText(normalizeLocation(loc))}</loc>
+  </url>`).join("\n");
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">',
+    urls,
+    "</urlset>",
+    ""
+  ].join("\n");
+}
+function normalizeLocation(location) {
+  if (/^https?:\/\/[^/]+\/?$/i.test(location)) {
+    return `${location.replace(/\/+$/, "")}/`;
+  }
+  return location.replace(/\/+$/, "");
+}
+export {
+  buildSitemapLocation,
+  renderSitemap
+};

package/src/static-site-generator/static-export-context.d.ts

@@ -1,5 +1,5 @@
 import type { EcoPagesAppConfig } from '../types/internal-types.js';
-import type { StaticRoute } from '../types/public-types.js';
+import type { EcopagesRouteInfo, StaticRoute } from '../types/public-types.js';
 import type { StaticGenerationRendererResolver } from '../route-renderer/route-renderer.js';
 import type { StaticGenerationRoute } from '../router/server/route-registry.js';
 type StaticGenerationRouteSource = {
@@ -18,5 +18,13 @@ export interface StaticExportContext {
     staticRoutes?: StaticRoute[];
     force: boolean;
     preserveExportDirectory: boolean;
+    /**
+     * Unfiltered static-generation routes (exact + expanded dynamic).
+     *
+     * @remarks
+     * Sitemap filtering is applied separately; integrations that build custom
+     * artifacts should start from this full list.
+     */
+    routes: EcopagesRouteInfo[];
 }
 export {};

package/src/static-site-generator/static-site-generator.d.ts

@@ -1,5 +1,5 @@
 import type { EcoPagesAppConfig } from '../types/internal-types.js';
-import type { StaticRoute } from '../types/public-types.js';
+import type { SitemapConfig, StaticRoute } from '../types/public-types.js';
 import type { PageRendererResolver, StaticGenerationRendererResolver } from '../route-renderer/route-renderer.js';
 import type { StaticGenerationRoute } from '../router/server/route-registry.js';
 import type { RouteModuleBuildCache } from '../services/module-loading/route-module-build-cache.store.js';
@@ -31,6 +31,7 @@ export declare class StaticSiteGenerator {
     private readonly routeModuleBuildCacheOverride?;
     private staticRenderCacheContext;
     private forceFullStaticGeneration;
+    private pageModuleLoader?;
     /**
      * Creates the static-site generator for one app config.
      */
@@ -46,6 +47,10 @@ export declare class StaticSiteGenerator {
      * Writes the robots.txt file declared by the app config.
      */
     generateRobotsTxt(): void;
+    /**
+     * Writes the configured sitemap file to the export directory.
+     */
+    generateSitemap(locations: readonly string[], sitemap: SitemapConfig): void;
     /**
      * Returns whether the input path points at the root directory.
      */
@@ -56,6 +61,18 @@ export declare class StaticSiteGenerator {
     getDirectories(routes: string[]): string[];
     private writeStaticOutput;
     private writeStaticPageArtifact;
+    /**
+     * Marks a successfully exported pathname as sitemap-eligible when robots allow indexing.
+     *
+     * @remarks
+     * Fail-closed: metadata resolution errors omit the URL. `robots.index === false`
+     * also omits it. Eligibility is decided during generation, not by reloading modules
+     * after `afterStaticExport`.
+     */
+    private considerSitemapEligibility;
+    private getPageModuleLoader;
+    private resolveFilesystemPageMetadata;
+    private resolveExplicitViewMetadata;
     private pruneStaleStaticOutputs;
     private createFilesystemStaticContents;
     /**
@@ -64,7 +81,15 @@ export declare class StaticSiteGenerator {
      * @remarks
      * Routes are rendered through the normal route renderer directly.
      */
-    generateStaticPages(router: StaticGenerationRouteSource, baseUrl: string, routeRendererFactory?: StaticPageRouteRendererFactory, skipped?: string[], activeStaticPathnames?: Set<string>, preloadedRoutes?: readonly StaticGenerationRoute[]): Promise<void>;
+    generateStaticPages(input: {
+        router: StaticGenerationRouteSource;
+        baseUrl: string;
+        routeRendererFactory?: StaticPageRouteRendererFactory;
+        skipped?: string[];
+        activeStaticPathnames?: Set<string>;
+        preloadedRoutes?: readonly StaticGenerationRoute[];
+        sitemapEligiblePathnames?: Set<string>;
+    }): Promise<void>;
     private createStaticExportContext;
     private invokeStaticExportHook;
     /**
@@ -78,10 +103,6 @@ export declare class StaticSiteGenerator {
         force?: boolean;
         preserveExportDirectory?: boolean;
     }): Promise<void>;
-    /**
-     * Generates static pages from explicit static routes registered via app.static().
-     * These routes use eco.page views via loader functions for HMR support.
-     */
     private generateExplicitStaticPages;
     private resolveExplicitViewSourceFile;
     private generateExplicitStaticRoute;