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

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

@@ -1,316 +1,558 @@
-import path from "node:path";
-import { appLogger } from "../global/app-logger.js";
-import { fileSystem } from "@ecopages/file-system";
-import { PathUtils } from "../utils/path-utils.module.js";
-import { prepareExplicitStaticRender } from "../adapters/shared/explicit-static-render-preparation.js";
-const STATIC_SITE_GENERATOR_ERRORS = {
-  ROUTE_RENDERER_FACTORY_REQUIRED: "RouteRendererFactory is required for render strategy",
-  unsupportedBodyType: (bodyType) => `Unsupported body type for static generation: ${bodyType}`,
-  missingIntegration: (routePath) => `View at ${routePath} is missing __eco.integration. Ensure it's defined with eco.page().`,
-  noRendererForIntegration: (integrationName) => `No renderer found for integration: ${integrationName}`,
-  dynamicRouteRequiresStaticPaths: (routePath) => `Dynamic route ${routePath} requires staticPaths to be defined on the view.`
+import path from 'node:path';
+import { availableParallelism } from 'node:os';
+import { appLogger } from '../global/app-logger.js';
+import { fileSystem } from '@ecopages/file-system';
+import { prepareExplicitStaticRender } from '../adapters/shared/http/explicit-static-render-preparation.js';
+import { createRouteModuleStaticRenderCacheContext } from './static-build-invalidation.js';
+import { getServerModuleBuildCacheOutdir, getSharedRouteModuleBuildCache, } from '../services/module-loading/route-module-build-cache-registry.js';
+import { ensurePagesUnifiedGraphBuilt, shouldBuildPagesUnifiedGraph, } from '../build/cache/pages-unified-graph-build.js';
+import { clearProductionPageBrowserGraphSession, prebuildProductionPageBrowserGraphs, shouldPrebuildProductionPageBrowserGraphs, } from './production-page-browser-graph-prebuild.js';
+import { PageModuleLoaderService } from '../route-renderer/page-loading/page-module-loader.js';
+import { renderSitemap } from './sitemap.js';
+import { resolveSitemapLocations } from './sitemap-routes.js';
+import { toEcopagesRouteInfo } from '../utils/ecopages-route-info.js';
+import { normalizePathname } from '../utils/path-pattern.js';
+export const STATIC_SITE_GENERATOR_ERRORS = {
+    ROUTE_RENDERER_FACTORY_REQUIRED: 'RouteRendererFactory is required for render strategy',
+    unsupportedBodyType: (bodyType) => `Unsupported body type for static generation: ${bodyType}`,
+    missingIntegration: (routePath) => `View at ${routePath} is missing component identity integration. Ensure it's defined with eco.page().`,
+    noRendererForIntegration: (integrationName) => `No renderer found for integration: ${integrationName}`,
+    dynamicRouteRequiresStaticPaths: (routePath) => `Dynamic route ${routePath} requires staticPaths to be defined on the view.`,
 };
-class StaticSiteGenerator {
-  appConfig;
-  /**
-   * Creates the static-site generator for one app config.
-   */
-  constructor({ appConfig }) {
-    this.appConfig = appConfig;
-  }
-  getExportDir() {
-    return this.appConfig.absolutePaths?.distDir ?? path.join(this.appConfig.rootDir, this.appConfig.distDir);
-  }
-  /**
-   * Logs the standardized warning emitted when a dynamic-cache page is skipped.
-   */
-  warnDynamicPageSkipped(filePath) {
-    appLogger.warn(
-      "Pages with cache: 'dynamic' are not supported in static generation or preview, so they will be skipped\n",
-      `\u27A4 ${filePath}`
-    );
-  }
-  /**
-   * Determines whether one filesystem-discovered page should be excluded from
-   * static generation.
-   */
-  async shouldSkipStaticPageFile(filePath, routeRendererFactory) {
-    const module = await routeRendererFactory.getPageRenderer(filePath).loadPageModule(filePath, {
-      cacheScope: "static-page-probe"
+function resolveStaticPageConcurrency() {
+    return Math.max(1, availableParallelism() - 1);
+}
+async function runWithConcurrency(items, concurrency, worker) {
+    if (items.length === 0) {
+        return;
+    }
+    const limit = Math.max(1, concurrency);
+    let nextIndex = 0;
+    const runners = Array.from({ length: Math.min(limit, items.length) }, async () => {
+        while (nextIndex < items.length) {
+            const currentIndex = nextIndex++;
+            await worker(items[currentIndex]);
+        }
     });
-    if (module.default?.cache !== "dynamic") {
-      return false;
+    await Promise.all(runners);
+}
+/**
+ * Generates static output files from the finalized app config and route graph.
+ *
+ * @remarks
+ * This class intentionally reuses the same routing, renderer, and server-module
+ * loading seams used by runtime rendering. Static generation should be a build
+ * loop over the normal app model, not a parallel rendering stack with different
+ * semantics.
+ */
+export class StaticSiteGenerator {
+    appConfig;
+    routeModuleBuildCacheOverride;
+    staticRenderCacheContext;
+    forceFullStaticGeneration = false;
+    pageModuleLoader;
+    /**
+     * Creates the static-site generator for one app config.
+     */
+    constructor({ appConfig, routeModuleBuildCache, }) {
+        this.appConfig = appConfig;
+        this.routeModuleBuildCacheOverride = routeModuleBuildCache;
+        this.staticRenderCacheContext = createRouteModuleStaticRenderCacheContext(appConfig);
     }
-    this.warnDynamicPageSkipped(filePath);
-    return true;
-  }
-  /**
-   * Determines whether one explicit static route view should be excluded from
-   * static generation.
-   */
-  shouldSkipStaticView(routePath, view) {
-    if (view.cache !== "dynamic") {
-      return false;
+    getRouteModuleBuildCache() {
+        return (this.routeModuleBuildCacheOverride ??
+            getSharedRouteModuleBuildCache(getServerModuleBuildCacheOutdir(this.appConfig), this.appConfig));
     }
-    this.warnDynamicPageSkipped(routePath);
-    return true;
-  }
-  /**
-   * Writes the robots.txt file declared by the app config.
-   */
-  generateRobotsTxt() {
-    let data = "";
-    const preferences = this.appConfig.robotsTxt.preferences;
-    for (const userAgent in preferences) {
-      data += `user-agent: ${userAgent}
-`;
-      for (const path2 of preferences[userAgent]) {
-        data += `disallow: ${path2}
-`;
-      }
-      data += "\n";
+    getExportDir() {
+        return this.appConfig.absolutePaths?.distDir ?? path.join(this.appConfig.rootDir, this.appConfig.distDir);
     }
-    fileSystem.ensureDir(this.getExportDir());
-    fileSystem.write(path.join(this.getExportDir(), "robots.txt"), data);
-  }
-  /**
-   * Returns whether the input path points at the root directory.
-   */
-  isRootDir(path2) {
-    const slashes = path2.match(/\//g);
-    return slashes && slashes.length === 1;
-  }
-  /**
-   * Collects parent directories that must exist for the generated route set.
-   */
-  getDirectories(routes) {
-    const directories = /* @__PURE__ */ new Set();
-    for (const route of routes) {
-      const path2 = route.startsWith("http") ? new URL(route).pathname : route;
-      const segments = path2.split("/");
-      if (segments.length > 2) {
-        directories.add(segments.slice(0, segments.length - 1).join("/"));
-      }
+    async shouldSkipStaticPageFile(filePath, routeRendererFactory) {
+        const pageModule = await routeRendererFactory.getPageRenderer(filePath).loadPageModule(filePath);
+        const Page = pageModule.default;
+        return Page.cache === 'dynamic';
     }
-    return Array.from(directories);
-  }
-  writeStaticOutput(routePath, contents, directories = []) {
-    const outputPath = this.getOutputPath(routePath, directories);
-    fileSystem.ensureDir(path.dirname(outputPath));
-    fileSystem.write(outputPath, contents);
-    return outputPath;
-  }
-  getStaticBuildStrategy(filePath) {
-    const ext = PathUtils.getEcoTemplateExtension(filePath);
-    const integration = this.appConfig.integrations.find((plugin) => plugin.extensions.includes(ext));
-    return integration?.staticBuildStep || "render";
-  }
-  async createFilesystemStaticContents(route, baseUrl, routeRendererFactory) {
-    const {
-      templateRoute: { filePath },
-      params
-    } = route;
-    if (this.getStaticBuildStrategy(filePath) === "fetch") {
-      const fetchUrl = this.resolveStaticFetchUrl(route.requestUrl, baseUrl);
-      const response = await fetch(fetchUrl);
-      if (!response.ok) {
-        appLogger.error(`Failed to fetch ${fetchUrl}. Status: ${response.status}`);
-        return null;
-      }
-      return response.text();
+    shouldSkipStaticView(_routePath, view) {
+        return view.cache === 'dynamic';
     }
-    if (!routeRendererFactory) {
-      throw new Error(STATIC_SITE_GENERATOR_ERRORS.ROUTE_RENDERER_FACTORY_REQUIRED);
+    /**
+     * Writes the robots.txt file declared by the app config.
+     */
+    generateRobotsTxt() {
+        let data = '';
+        const preferences = this.appConfig.robotsTxt.preferences;
+        for (const userAgent in preferences) {
+            data += `user-agent: ${userAgent}\n`;
+            for (const path of preferences[userAgent]) {
+                data += `disallow: ${path}\n`;
+            }
+            data += '\n';
+        }
+        fileSystem.ensureDir(this.getExportDir());
+        fileSystem.write(path.join(this.getExportDir(), 'robots.txt'), data);
     }
-    if (await this.shouldSkipStaticPageFile(filePath, routeRendererFactory)) {
-      return null;
+    /**
+     * Writes the configured sitemap file to the export directory.
+     */
+    generateSitemap(locations, sitemap) {
+        const fileName = sitemap.fileName ?? 'sitemap.xml';
+        fileSystem.ensureDir(this.getExportDir());
+        fileSystem.write(path.join(this.getExportDir(), fileName), renderSitemap(locations));
     }
-    const renderer = routeRendererFactory.getPageRenderer(filePath);
-    const result = await renderer.execute({
-      file: filePath,
-      params
-    });
-    const body = result.body;
-    if (typeof body === "string" || Buffer.isBuffer(body)) {
-      return body;
+    /**
+     * Returns whether the input path points at the root directory.
+     */
+    isRootDir(path) {
+        const slashes = path.match(/\//g);
+        return slashes && slashes.length === 1;
+    }
+    /**
+     * Collects parent directories that must exist for the generated route set.
+     */
+    getDirectories(routes) {
+        const directories = new Set();
+        for (const route of routes) {
+            const path = route.startsWith('http') ? new URL(route).pathname : route;
+            const segments = path.split('/');
+            if (segments.length > 2) {
+                directories.add(segments.slice(0, segments.length - 1).join('/'));
+            }
+        }
+        return Array.from(directories);
     }
-    if (body instanceof ReadableStream) {
-      return new Response(body).text();
+    writeStaticOutput(routePath, contents, directories = []) {
+        const outputPath = this.getOutputPath(routePath, directories);
+        fileSystem.ensureDir(path.dirname(outputPath));
+        fileSystem.write(outputPath, contents);
+        return outputPath;
     }
-    throw new Error(STATIC_SITE_GENERATOR_ERRORS.unsupportedBodyType(typeof body));
-  }
-  /**
-   * Generates static output for all filesystem-discovered routes.
-   *
-   * @remarks
-   * Routes whose integrations opt into fetch-based static builds are rendered by
-   * issuing a request against the running server origin. Render-strategy routes
-   * go through the normal route renderer directly.
-   */
-  async generateStaticPages(router, baseUrl, routeRendererFactory) {
-    const routes = await router.listStaticGenerationRoutes({ runtimeOrigin: baseUrl });
-    appLogger.debug(
-      "Static Pages",
-      routes.map((route) => route.requestUrl)
-    );
-    const directories = this.getDirectories(routes.map((route) => route.requestUrl));
-    for (const route of routes) {
-      try {
-        const contents = await this.createFilesystemStaticContents(route, baseUrl, routeRendererFactory);
+    async writeStaticPageArtifact(options) {
+        const directories = options.directories ?? this.getDirectories([options.pathname]);
+        const renderedOutputPath = this.getOutputPath(options.pathname, directories);
+        const routeModuleBuildCache = this.getRouteModuleBuildCache();
+        if (options.reuseRenderedOutput !== false &&
+            options.sourceFile &&
+            routeModuleBuildCache.canReuseStaticRender({
+                sourceFile: options.sourceFile,
+                pathname: options.pathname,
+                renderedOutputPath,
+                context: this.staticRenderCacheContext,
+                force: this.forceFullStaticGeneration,
+            })) {
+            options.activeStaticPathnames?.add(options.pathname);
+            await options.onSuccessfulExport?.();
+            appLogger.debug(`Skipped unchanged static page: ${options.debugLabel ?? options.pathname}`);
+            return;
+        }
+        const contents = await options.createContents();
         if (contents === null) {
-          continue;
-        }
-        this.writeStaticOutput(route.pathname, contents, directories);
-      } catch (error) {
-        appLogger.error(
-          `Error generating static page for ${route.requestUrl}:`,
-          error instanceof Error ? error : String(error)
-        );
-      }
+            return;
+        }
+        const outputPath = this.writeStaticOutput(options.pathname, contents, directories);
+        options.activeStaticPathnames?.add(options.pathname);
+        if (options.sourceFile) {
+            try {
+                routeModuleBuildCache.recordStaticRender({
+                    filePath: options.sourceFile,
+                    pathname: options.pathname,
+                    sourceHash: fileSystem.hash(options.sourceFile),
+                    renderedOutputPath: outputPath,
+                    context: this.staticRenderCacheContext,
+                });
+            }
+            catch (error) {
+                appLogger.debug(`Failed to record static render cache for ${options.pathname}`, error instanceof Error ? error.message : String(error));
+            }
+        }
+        await options.onSuccessfulExport?.();
     }
-  }
-  resolveStaticFetchUrl(route, baseUrl) {
-    if (!route.startsWith("http://") && !route.startsWith("https://")) {
-      return `${baseUrl}${route}`;
+    /**
+     * 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`.
+     */
+    async considerSitemapEligibility(input) {
+        if (!input.sitemapEligiblePathnames || !this.appConfig.sitemap?.enabled) {
+            return;
+        }
+        try {
+            const metadata = await input.resolveMetadata();
+            if (metadata.robots?.index === false) {
+                return;
+            }
+            input.sitemapEligiblePathnames.add(normalizePathname(input.pathname));
+        }
+        catch (error) {
+            appLogger.debug(`Sitemap eligibility skipped for ${input.pathname}; metadata resolution failed`, error instanceof Error ? error.message : String(error));
+        }
     }
-    const targetUrl = new URL(route);
-    const buildUrl = new URL(baseUrl);
-    buildUrl.pathname = targetUrl.pathname;
-    buildUrl.search = targetUrl.search;
-    buildUrl.hash = targetUrl.hash;
-    return buildUrl.href;
-  }
-  /**
-   * Executes the full static-generation workflow for one app run.
-   */
-  async run({
-    router,
-    baseUrl,
-    routeRendererFactory,
-    staticRoutes
-  }) {
-    this.generateRobotsTxt();
-    await this.generateStaticPages(router, baseUrl, routeRendererFactory);
-    if (staticRoutes && staticRoutes.length > 0 && routeRendererFactory) {
-      await this.generateExplicitStaticPages(staticRoutes, routeRendererFactory);
+    getPageModuleLoader(baseUrl) {
+        this.pageModuleLoader ??= new PageModuleLoaderService(this.appConfig, baseUrl);
+        return this.pageModuleLoader;
     }
-  }
-  /**
-   * Generates static pages from explicit static routes registered via app.static().
-   * These routes use eco.page views via loader functions for HMR support.
-   */
-  async generateExplicitStaticPages(staticRoutes, routeRendererFactory) {
-    appLogger.debug(
-      "Generating explicit static routes",
-      staticRoutes.map((r) => r.path)
-    );
-    for (const route of staticRoutes) {
-      try {
-        const mod = await route.loader();
-        const view = mod.default;
-        if (this.shouldSkipStaticView(route.path, view)) {
-          continue;
-        }
-        await this.generateExplicitStaticRoute(route.path, view, routeRendererFactory);
-      } catch (error) {
-        appLogger.error(
-          `Error generating explicit static page for ${route.path}:`,
-          error instanceof Error ? error : String(error)
-        );
-      }
+    async resolveFilesystemPageMetadata(input) {
+        const loader = this.getPageModuleLoader(input.baseUrl);
+        const pageModule = await loader.resolvePageModule({
+            file: input.filePath,
+            importPageFileFn: (file) => input.routeRendererFactory.getPageRenderer(file).loadPageModule(file),
+        });
+        const { metadata } = await loader.resolvePageData({
+            pageModule,
+            routeOptions: {
+                file: input.filePath,
+                params: input.params,
+            },
+        });
+        return metadata;
     }
-  }
-  async generateExplicitStaticRoute(routePath, view, routeRendererFactory) {
-    const { renderer, routeEntries } = await this.planExplicitStaticRoute(routePath, view, routeRendererFactory);
-    for (const { pathname, params } of routeEntries) {
-      const contents = await this.createExplicitStaticContents(
-        routePath,
-        view,
-        params,
-        routeRendererFactory,
-        renderer
-      );
-      const outputPath = this.writeStaticOutput(pathname, contents);
-      appLogger.debug(`Generated static page: ${pathname} -> ${outputPath}`);
+    async resolveExplicitViewMetadata(input) {
+        if (!input.view.metadata) {
+            return this.appConfig.defaultMetadata;
+        }
+        const dynamicMetadata = await input.view.metadata({
+            params: input.params,
+            query: {},
+            props: input.props,
+            appConfig: this.appConfig,
+        });
+        return { ...this.appConfig.defaultMetadata, ...dynamicMetadata };
     }
-  }
-  async planExplicitStaticRoute(routePath, view, routeRendererFactory) {
-    const { renderer } = await prepareExplicitStaticRender({
-      routePath,
-      view,
-      params: {},
-      appConfig: this.appConfig,
-      runtimeOrigin: this.appConfig.baseUrl,
-      routeRendererFactory,
-      errors: STATIC_SITE_GENERATOR_ERRORS
-    });
-    return {
-      renderer,
-      routeEntries: await this.listExplicitStaticRouteEntries(routePath, view)
-    };
-  }
-  async createExplicitStaticContents(routePath, view, params, routeRendererFactory, renderer) {
-    const { props, view: renderableView } = await prepareExplicitStaticRender({
-      routePath,
-      view,
-      params,
-      appConfig: this.appConfig,
-      runtimeOrigin: this.appConfig.baseUrl,
-      routeRendererFactory,
-      errors: STATIC_SITE_GENERATOR_ERRORS
-    });
-    const response = await renderer.renderToResponse(renderableView, props, {});
-    return response.text();
-  }
-  async listExplicitStaticRouteEntries(routePath, view) {
-    const isDynamic = routePath.includes(":") || routePath.includes("[");
-    if (!isDynamic) {
-      return [{ pathname: routePath, params: {} }];
+    pruneStaleStaticOutputs(activeStaticPathnames) {
+        const removedOutputPaths = this.getRouteModuleBuildCache().pruneStaleRenderedOutputs(activeStaticPathnames);
+        for (const outputPath of removedOutputPaths) {
+            const resolvedOutputPath = path.isAbsolute(outputPath) ? outputPath : path.resolve(outputPath);
+            if (fileSystem.exists(resolvedOutputPath)) {
+                fileSystem.remove(resolvedOutputPath);
+                appLogger.debug(`Removed stale static output: ${resolvedOutputPath}`);
+            }
+        }
     }
-    if (!view.staticPaths) {
-      throw new Error(STATIC_SITE_GENERATOR_ERRORS.dynamicRouteRequiresStaticPaths(routePath));
+    async createFilesystemStaticContents(input) {
+        const { route: { templateRoute: { filePath }, params, }, routeRendererFactory, skipped, } = input;
+        if (!routeRendererFactory) {
+            throw new Error(STATIC_SITE_GENERATOR_ERRORS.ROUTE_RENDERER_FACTORY_REQUIRED);
+        }
+        if (await this.shouldSkipStaticPageFile(filePath, routeRendererFactory)) {
+            skipped?.push(filePath);
+            return null;
+        }
+        const renderer = routeRendererFactory.getPageRenderer(filePath);
+        const result = await renderer.execute({
+            file: filePath,
+            params: params,
+        });
+        const body = result.body;
+        if (typeof body === 'string' || Buffer.isBuffer(body)) {
+            return body;
+        }
+        if (body instanceof ReadableStream) {
+            return new Response(body).text();
+        }
+        throw new Error(STATIC_SITE_GENERATOR_ERRORS.unsupportedBodyType(typeof body));
     }
-    const { paths } = await view.staticPaths({
-      appConfig: this.appConfig,
-      runtimeOrigin: this.appConfig.baseUrl
-    });
-    return paths.map(({ params }) => ({
-      pathname: this.resolveRoutePath(routePath, params),
-      params
-    }));
-  }
-  /**
-   * Resolve a route path template with actual params.
-   * Supports both :param and [param] syntax.
-   */
-  resolveRoutePath(routePath, params) {
-    let resolved = routePath;
-    for (const [key, value] of Object.entries(params)) {
-      const paramValue = Array.isArray(value) ? value.join("/") : value;
-      resolved = resolved.replace(`:${key}`, paramValue);
-      resolved = resolved.replace(`[${key}]`, paramValue);
-      resolved = resolved.replace(`[...${key}]`, paramValue);
+    /**
+     * Generates static output for all filesystem-discovered routes.
+     *
+     * @remarks
+     * Routes are rendered through the normal route renderer directly.
+     */
+    async generateStaticPages(input) {
+        const { router, baseUrl, routeRendererFactory, skipped, activeStaticPathnames, sitemapEligiblePathnames } = input;
+        const routes = input.preloadedRoutes ?? (await router.listStaticGenerationRoutes({ runtimeOrigin: baseUrl }));
+        appLogger.debug('Static Pages', routes.map((route) => route.requestUrl));
+        const directories = this.getDirectories(routes.map((route) => route.requestUrl));
+        await runWithConcurrency(routes, resolveStaticPageConcurrency(), async (route) => {
+            try {
+                await this.writeStaticPageArtifact({
+                    pathname: route.pathname,
+                    sourceFile: route.templateRoute.filePath,
+                    directories,
+                    debugLabel: route.requestUrl,
+                    activeStaticPathnames,
+                    onSuccessfulExport: () => this.considerSitemapEligibility({
+                        pathname: route.pathname,
+                        sitemapEligiblePathnames,
+                        resolveMetadata: () => {
+                            if (!routeRendererFactory) {
+                                throw new Error(STATIC_SITE_GENERATOR_ERRORS.ROUTE_RENDERER_FACTORY_REQUIRED);
+                            }
+                            return this.resolveFilesystemPageMetadata({
+                                filePath: route.templateRoute.filePath,
+                                params: route.params,
+                                baseUrl,
+                                routeRendererFactory,
+                            });
+                        },
+                    }),
+                    createContents: () => this.createFilesystemStaticContents({
+                        route,
+                        baseUrl,
+                        routeRendererFactory,
+                        skipped,
+                    }),
+                });
+            }
+            catch (error) {
+                appLogger.error(`Error generating static page for ${route.requestUrl}:`, error instanceof Error ? error : String(error));
+            }
+        });
+    }
+    createStaticExportContext(input) {
+        return {
+            appConfig: this.appConfig,
+            router: input.router,
+            baseUrl: input.baseUrl,
+            routeRendererFactory: input.routeRendererFactory,
+            staticRoutes: input.staticRoutes,
+            force: input.force,
+            preserveExportDirectory: input.preserveExportDirectory,
+            routes: input.routes,
+        };
     }
-    return resolved;
-  }
-  /**
-   * Get the output file path for a given route.
-   */
-  getOutputPath(routePath, directories = []) {
-    let outputName;
-    if (routePath === "/") {
-      outputName = "index.html";
-    } else if (directories.includes(routePath)) {
-      outputName = `${routePath}/index.html`;
-    } else if (routePath.endsWith("/")) {
-      outputName = `${routePath}index.html`;
-    } else {
-      outputName = `${routePath}.html`;
+    async invokeStaticExportHook(hook, context) {
+        for (const integration of this.appConfig.integrations) {
+            const handler = integration[hook];
+            if (typeof handler === 'function') {
+                await handler.call(integration, context);
+            }
+        }
+    }
+    /**
+     * Executes the full static-generation workflow for one app run.
+     */
+    async run({ router, baseUrl, routeRendererFactory, staticRoutes, force = false, preserveExportDirectory = false, }) {
+        const skippedDynamicPages = [];
+        const activeStaticPathnames = new Set();
+        const sitemapEligiblePathnames = this.appConfig.sitemap?.enabled ? new Set() : undefined;
+        this.forceFullStaticGeneration = force;
+        this.staticRenderCacheContext = createRouteModuleStaticRenderCacheContext(this.appConfig);
+        this.pageModuleLoader = undefined;
+        if (!force) {
+            this.getRouteModuleBuildCache().ensureIncrementalStaticGenerationContext(this.staticRenderCacheContext);
+        }
+        if (shouldPrebuildProductionPageBrowserGraphs() && force) {
+            clearProductionPageBrowserGraphSession(this.appConfig);
+        }
+        const routes = await router.listStaticGenerationRoutes({ runtimeOrigin: baseUrl });
+        const exportRoutes = routes.map((route) => toEcopagesRouteInfo(route));
+        if (shouldBuildPagesUnifiedGraph()) {
+            await ensurePagesUnifiedGraphBuilt({
+                appConfig: this.appConfig,
+                entryPaths: routes.map((route) => route.templateRoute.filePath),
+                outdir: getServerModuleBuildCacheOutdir(this.appConfig),
+                force,
+            });
+        }
+        const staticExportContext = this.createStaticExportContext({
+            router,
+            baseUrl,
+            routeRendererFactory,
+            staticRoutes,
+            force,
+            preserveExportDirectory,
+            routes: exportRoutes,
+        });
+        await this.invokeStaticExportHook('beforeStaticExport', staticExportContext);
+        try {
+            if (shouldPrebuildProductionPageBrowserGraphs() && routeRendererFactory) {
+                await prebuildProductionPageBrowserGraphs(routes.map((route) => ({
+                    routeFile: route.templateRoute.filePath,
+                    params: route.params,
+                })), routeRendererFactory);
+            }
+            this.generateRobotsTxt();
+            await this.generateStaticPages({
+                router,
+                baseUrl,
+                routeRendererFactory,
+                skipped: skippedDynamicPages,
+                activeStaticPathnames,
+                preloadedRoutes: routes,
+                sitemapEligiblePathnames,
+            });
+            if (staticRoutes && staticRoutes.length > 0 && routeRendererFactory) {
+                await this.generateExplicitStaticPages({
+                    staticRoutes,
+                    routeRendererFactory,
+                    skipped: skippedDynamicPages,
+                    activeStaticPathnames,
+                    sitemapEligiblePathnames,
+                });
+            }
+            if (preserveExportDirectory) {
+                this.pruneStaleStaticOutputs(activeStaticPathnames);
+            }
+        }
+        catch (error) {
+            if (shouldPrebuildProductionPageBrowserGraphs()) {
+                clearProductionPageBrowserGraphSession(this.appConfig);
+            }
+            throw error;
+        }
+        finally {
+            await this.invokeStaticExportHook('afterStaticExport', staticExportContext);
+        }
+        if (this.appConfig.sitemap?.enabled && sitemapEligiblePathnames) {
+            const locations = resolveSitemapLocations({
+                eligiblePathnames: [...sitemapEligiblePathnames],
+                sitemap: this.appConfig.sitemap,
+                baseUrl,
+            });
+            this.generateSitemap(locations, this.appConfig.sitemap);
+        }
+        if (skippedDynamicPages.length > 0) {
+            appLogger.debug(`Skipped ${skippedDynamicPages.length} page(s) with cache: 'dynamic' (not supported in static generation)`, skippedDynamicPages);
+        }
+    }
+    async generateExplicitStaticPages(input) {
+        appLogger.debug('Generating explicit static routes', input.staticRoutes.map((r) => r.path));
+        for (const route of input.staticRoutes) {
+            try {
+                const mod = await route.loader();
+                const view = mod.default;
+                if (this.shouldSkipStaticView(route.path, view)) {
+                    input.skipped?.push(route.path);
+                    continue;
+                }
+                await this.generateExplicitStaticRoute({
+                    routePath: route.path,
+                    view,
+                    routeRendererFactory: input.routeRendererFactory,
+                    activeStaticPathnames: input.activeStaticPathnames,
+                    sitemapEligiblePathnames: input.sitemapEligiblePathnames,
+                });
+            }
+            catch (error) {
+                appLogger.error(`Error generating explicit static page for ${route.path}:`, error instanceof Error ? error : String(error));
+            }
+        }
+    }
+    resolveExplicitViewSourceFile(view) {
+        const sourceFile = view.config?.identity?.file;
+        if (!sourceFile) {
+            return undefined;
+        }
+        return path.isAbsolute(sourceFile) ? sourceFile : path.join(this.appConfig.rootDir, sourceFile);
+    }
+    async generateExplicitStaticRoute(input) {
+        const { routePath, view, routeRendererFactory, activeStaticPathnames, sitemapEligiblePathnames } = input;
+        const { renderer, routeEntries } = await this.planExplicitStaticRoute({
+            routePath,
+            view,
+            routeRendererFactory,
+        });
+        const sourceFile = this.resolveExplicitViewSourceFile(view);
+        for (const { pathname, params } of routeEntries) {
+            await this.writeStaticPageArtifact({
+                pathname,
+                sourceFile,
+                debugLabel: pathname,
+                activeStaticPathnames,
+                onSuccessfulExport: () => this.considerSitemapEligibility({
+                    pathname,
+                    sitemapEligiblePathnames,
+                    resolveMetadata: async () => {
+                        const { props } = await prepareExplicitStaticRender({
+                            routePath,
+                            view,
+                            params,
+                            appConfig: this.appConfig,
+                            runtimeOrigin: this.appConfig.baseUrl,
+                            routeRendererFactory,
+                            errors: STATIC_SITE_GENERATOR_ERRORS,
+                        });
+                        return this.resolveExplicitViewMetadata({ view, params, props });
+                    },
+                }),
+                createContents: () => this.createExplicitStaticContents({
+                    routePath,
+                    view,
+                    params,
+                    routeRendererFactory,
+                    renderer,
+                }),
+            });
+            appLogger.debug(`Generated static page: ${pathname}`);
+        }
+    }
+    async planExplicitStaticRoute(input) {
+        const { renderer } = await prepareExplicitStaticRender({
+            routePath: input.routePath,
+            view: input.view,
+            params: {},
+            appConfig: this.appConfig,
+            runtimeOrigin: this.appConfig.baseUrl,
+            routeRendererFactory: input.routeRendererFactory,
+            errors: STATIC_SITE_GENERATOR_ERRORS,
+        });
+        return {
+            renderer,
+            routeEntries: await this.listExplicitStaticRouteEntries(input.routePath, input.view),
+        };
+    }
+    async createExplicitStaticContents(input) {
+        const { props, view: renderableView } = await prepareExplicitStaticRender({
+            routePath: input.routePath,
+            view: input.view,
+            params: input.params,
+            appConfig: this.appConfig,
+            runtimeOrigin: this.appConfig.baseUrl,
+            routeRendererFactory: input.routeRendererFactory,
+            errors: STATIC_SITE_GENERATOR_ERRORS,
+        });
+        const response = await input.renderer.renderToResponse(renderableView, props, {});
+        return response.text();
+    }
+    async listExplicitStaticRouteEntries(routePath, view) {
+        const isDynamic = routePath.includes(':') || routePath.includes('[');
+        if (!isDynamic) {
+            return [{ pathname: routePath, params: {} }];
+        }
+        if (!view.staticPaths) {
+            throw new Error(STATIC_SITE_GENERATOR_ERRORS.dynamicRouteRequiresStaticPaths(routePath));
+        }
+        const { paths } = await view.staticPaths({
+            appConfig: this.appConfig,
+            runtimeOrigin: this.appConfig.baseUrl,
+        });
+        return paths.map(({ params }) => ({
+            pathname: this.resolveRoutePath(routePath, params),
+            params,
+        }));
+    }
+    /**
+     * Resolve a route path template with actual params.
+     * Supports both :param and [param] syntax.
+     */
+    resolveRoutePath(routePath, params) {
+        let resolved = routePath;
+        for (const [key, value] of Object.entries(params)) {
+            const paramValue = Array.isArray(value) ? value.join('/') : value;
+            resolved = resolved.replace(`:${key}`, paramValue);
+            resolved = resolved.replace(`[${key}]`, paramValue);
+            resolved = resolved.replace(`[...${key}]`, paramValue);
+        }
+        return resolved;
+    }
+    /**
+     * Get the output file path for a given route.
+     */
+    getOutputPath(routePath, directories = []) {
+        let outputName;
+        if (routePath === '/') {
+            outputName = 'index.html';
+        }
+        else if (directories.includes(routePath)) {
+            outputName = `${routePath}/index.html`;
+        }
+        else if (routePath.endsWith('/')) {
+            outputName = `${routePath}index.html`;
+        }
+        else {
+            outputName = `${routePath}.html`;
+        }
+        return path.join(this.getExportDir(), outputName);
     }
-    return path.join(this.getExportDir(), outputName);
-  }
 }
-export {
-  STATIC_SITE_GENERATOR_ERRORS,
-  StaticSiteGenerator
-};