@ecopages/core 0.2.0-beta.3 → 0.2.0-beta.31

package/src/client/view-transitions.js

@@ -0,0 +1,63 @@
+const VIEW_TRANSITION_ATTR = "data-view-transition";
+const VIEW_TRANSITION_ANIMATE_ATTR = "data-view-transition-animate";
+const VIEW_TRANSITION_DURATION_ATTR = "data-view-transition-duration";
+const DYNAMIC_STYLES_ID = "eco-vt-dynamic-styles";
+function applyViewTransitionNames() {
+  const elements = document.querySelectorAll(`[${VIEW_TRANSITION_ATTR}]`);
+  const morphNames = [];
+  const customDurations = [];
+  elements.forEach((el) => {
+    const name = el.getAttribute(VIEW_TRANSITION_ATTR);
+    if (!name) {
+      return;
+    }
+    el.style.viewTransitionName = name;
+    const animate = el.getAttribute(VIEW_TRANSITION_ANIMATE_ATTR);
+    if (animate !== "fade") {
+      morphNames.push(name);
+    }
+    const duration = el.getAttribute(VIEW_TRANSITION_DURATION_ATTR);
+    if (duration) {
+      customDurations.push({ name, duration });
+    }
+  });
+  if (morphNames.length > 0 || customDurations.length > 0) {
+    injectDynamicStyles(morphNames, customDurations);
+  }
+}
+function clearViewTransitionNames() {
+  const elements = document.querySelectorAll(`[${VIEW_TRANSITION_ATTR}]`);
+  elements.forEach((el) => {
+    el.style.viewTransitionName = "";
+  });
+  const styleEl = document.getElementById(DYNAMIC_STYLES_ID);
+  if (styleEl) {
+    styleEl.textContent = "";
+  }
+}
+function injectDynamicStyles(morphNames, customDurations) {
+  let styleEl = document.getElementById(DYNAMIC_STYLES_ID);
+  if (!styleEl) {
+    styleEl = document.createElement("style");
+    styleEl.id = DYNAMIC_STYLES_ID;
+    styleEl.setAttribute("data-eco-persist", "");
+    document.head.append(styleEl);
+  }
+  const morphCss = morphNames.map(
+    (name) => `
+		::view-transition-old(${name}) { display: none !important; }
+		::view-transition-new(${name}) { animation: none !important; opacity: 1 !important; }
+	`
+  ).join("\n");
+  const durationCss = customDurations.map(
+    ({ name, duration }) => `
+		::view-transition-group(${name}) { animation-duration: ${duration} !important; }
+	`
+  ).join("\n");
+  styleEl.textContent = `${morphCss}
+${durationCss}`;
+}
+export {
+  applyViewTransitionNames,
+  clearViewTransitionNames
+};

package/src/config/config-builder.d.ts

@@ -3,12 +3,12 @@
  * @module
  */
 import { type BuildOwnership } from '../build/build-adapter.js';
-import type { EcoBuildPlugin } from '../build/build-types.js';
+import type { EcoBuildPlugin } from '../build/contracts/build-types.js';
 import type { EcoPagesAppConfig, RobotsPreference } from '../types/internal-types.js';
 import type { AnyIntegrationPlugin } from '../plugins/integration-plugin.js';
 import type { Processor } from '../plugins/processor.js';
 import type { EcoSourceTransform } from '../plugins/source-transform.js';
-import type { PageMetadataProps } from '../types/public-types.js';
+import type { PageMetadataProps, SitemapConfig } from '../types/public-types.js';
 import type { CacheConfig } from '../services/cache/cache.types.js';
 export declare const CONFIG_BUILDER_ERRORS: {
     readonly DUPLICATE_INTEGRATION_NAMES: "Integrations names must be unique";
@@ -16,7 +16,7 @@ export declare const CONFIG_BUILDER_ERRORS: {
     readonly MIXED_JSX_ENGINES: "Both kitajs and react integrations are enabled. Use per-file JSX import source/pragma consistently (e.g. `/** @jsxImportSource react */` for React files and `/** @jsxImportSource @kitajs/html */` for Kita files).";
     readonly duplicateProcessorName: (name: string) => string;
     readonly duplicateLoaderName: (name: string) => string;
-    readonly duplicateSemanticTemplate: (kind: "html" | "404", matches: string[]) => string;
+    readonly duplicateSemanticTemplate: (kind: "html" | "404" | "500", matches: string[]) => string;
     readonly incompatibleRuntimeCapability: (kind: "integration" | "processor", name: string, runtime: RuntimeKind, reason: string) => string;
     readonly unsupportedRuntimeVersion: (kind: "integration" | "processor", name: string, runtime: RuntimeKind, current: string, min: string) => string;
     readonly invalidRuntimeVersion: (kind: "integration" | "processor", name: string, version: string) => string;
@@ -70,12 +70,7 @@ export declare class ConfigBuilder {
      *
      * - `'rolldown'` (default): Ecopages runs builds through
      *   {@link RolldownBuildAdapter}, creating a new `rolldown()` instance
-     *   per build. Best for one-shot production builds and benchmarks.
-     * - `'rolldown-dev'`: Ecopages runs builds through
-     *   {@link RolldownDevBuildAdapter}, which wraps Rolldown's experimental
-     *   `DevEngine` and reuses the cached module graph, resolver, and
-     *   transform cache across rebuilds. Best for HMR and watch mode where
-     *   the same entrypoints are rebuilt repeatedly.
+     *   per build.
      * - `'vite-host'`: a host runtime owns the build. Ecopages exposes a
      *   {@link ViteHostBuildAdapter} boundary marker that throws on direct
      *   use. Select this only for host-driven compatibility flows where
@@ -143,6 +138,16 @@ export declare class ConfigBuilder {
     setRobotsTxt(robotsTxt: {
         preferences: RobotsPreference;
     }): this;
+    /**
+     * Sets automatic sitemap.xml generation during static export.
+     *
+     * @remarks
+     * Merged over `{ enabled: false, fileName: 'sitemap.xml', extraUrls: [], exclude: [] }`.
+     * Existing apps stay unchanged until `enabled: true` is set. Page-level
+     * `metadata.robots.index: false` and metadata resolution failures are handled
+     * during static generation (not by this config merge).
+     */
+    setSitemap(sitemap: SitemapConfig): this;
     /**
      * Sets the integration plugins to use.
      * These plugins provide additional functionality to the application.
@@ -250,7 +255,17 @@ export declare class ConfigBuilder {
     private compareVersions;
     /**
      * Initializes default loaders that are required for EcoPages to function.
-     * This includes the eco-component-meta-plugin which auto-injects __eco metadata into component configs.
+     *
+     * @remarks
+     * `eco-component-meta` is registered twice on purpose:
+     *
+     * - `sourceTransforms` is the canonical browser/HMR path. The Rolldown bridge
+     *   runs these after first-wins `onLoad` plugins rewrite module source.
+     * - `loaders` keeps the same transform available to server-oriented builds
+     *   that still use competing `onLoad` handlers directly.
+     *
+     * Browser builds exclude the loader copy in {@link getAppBrowserBuildPlugins}
+     * when the transform name is already present in `sourceTransforms`.
      */
     private initializeDefaultLoaders;
     private reviewBaseUrl;

package/src/config/config-builder.js

@@ -9,7 +9,6 @@ import {
   collectConfiguredAppBuildManifestContributions,
   createBuildAdapter,
   setAppBuildAdapter,
-  setAppBuildExecutor,
   updateAppBuildManifest
 } from "../build/build-adapter.js";
 import { GHTML_PLUGIN_NAME } from "../integrations/ghtml/ghtml.constants.js";
@@ -54,6 +53,12 @@ class ConfigBuilder {
         "*": []
       }
     },
+    sitemap: {
+      enabled: false,
+      fileName: "sitemap.xml",
+      extraUrls: [],
+      exclude: []
+    },
     integrations: [],
     integrationsDependencies: [],
     distDir: DEFAULT_ECOPAGES_DIST_DIR,
@@ -75,7 +80,8 @@ class ConfigBuilder {
       publicDir: "",
       srcDir: "",
       htmlTemplatePath: "",
-      error404TemplatePath: ""
+      error404TemplatePath: "",
+      error500TemplatePath: ""
     },
     processors: /* @__PURE__ */ new Map(),
     loaders: /* @__PURE__ */ new Map(),
@@ -112,12 +118,7 @@ class ConfigBuilder {
    *
    * - `'rolldown'` (default): Ecopages runs builds through
    *   {@link RolldownBuildAdapter}, creating a new `rolldown()` instance
-   *   per build. Best for one-shot production builds and benchmarks.
-   * - `'rolldown-dev'`: Ecopages runs builds through
-   *   {@link RolldownDevBuildAdapter}, which wraps Rolldown's experimental
-   *   `DevEngine` and reuses the cached module graph, resolver, and
-   *   transform cache across rebuilds. Best for HMR and watch mode where
-   *   the same entrypoints are rebuilt repeatedly.
+   *   per build.
    * - `'vite-host'`: a host runtime owns the build. Ecopages exposes a
    *   {@link ViteHostBuildAdapter} boundary marker that throws on direct
    *   use. Select this only for host-driven compatibility flows where
@@ -207,6 +208,31 @@ class ConfigBuilder {
     this.config.robotsTxt = robotsTxt;
     return this;
   }
+  /**
+   * Sets automatic sitemap.xml generation during static export.
+   *
+   * @remarks
+   * Merged over `{ enabled: false, fileName: 'sitemap.xml', extraUrls: [], exclude: [] }`.
+   * Existing apps stay unchanged until `enabled: true` is set. Page-level
+   * `metadata.robots.index: false` and metadata resolution failures are handled
+   * during static generation (not by this config merge).
+   */
+  setSitemap(sitemap) {
+    const defaults = {
+      enabled: false,
+      fileName: "sitemap.xml",
+      extraUrls: [],
+      exclude: []
+    };
+    this.config.sitemap = {
+      ...defaults,
+      ...this.config.sitemap,
+      ...sitemap,
+      extraUrls: sitemap.extraUrls ?? this.config.sitemap.extraUrls ?? defaults.extraUrls,
+      exclude: sitemap.exclude ?? this.config.sitemap.exclude ?? defaults.exclude
+    };
+    return this;
+  }
   /**
    * Sets the integration plugins to use.
    * These plugins provide additional functionality to the application.
@@ -387,11 +413,18 @@ class ConfigBuilder {
       error404TemplatePath: this.resolveSemanticTemplatePath({
         dirPath: absolutePagesDir,
         basename: "404"
+      }),
+      error500TemplatePath: this.resolveSemanticTemplatePath({
+        dirPath: absolutePagesDir,
+        basename: "500"
       })
     };
     return this;
   }
-  resolveSemanticTemplatePath({ dirPath, basename }) {
+  resolveSemanticTemplatePath({
+    dirPath,
+    basename
+  }) {
     const extensions = this.config.templatesExt.length > 0 ? this.config.templatesExt : [".ghtml.ts"];
     const matches = extensions.map((extension) => path.join(dirPath, `${basename}${extension}`)).filter((candidate) => fileSystem.exists(candidate));
     invariant(matches.length <= 1, CONFIG_BUILDER_ERRORS.duplicateSemanticTemplate(basename, matches));
@@ -547,7 +580,17 @@ class ConfigBuilder {
   }
   /**
    * Initializes default loaders that are required for EcoPages to function.
-   * This includes the eco-component-meta-plugin which auto-injects __eco metadata into component configs.
+   *
+   * @remarks
+   * `eco-component-meta` is registered twice on purpose:
+   *
+   * - `sourceTransforms` is the canonical browser/HMR path. The Rolldown bridge
+   *   runs these after first-wins `onLoad` plugins rewrite module source.
+   * - `loaders` keeps the same transform available to server-oriented builds
+   *   that still use competing `onLoad` handlers directly.
+   *
+   * Browser builds exclude the loader copy in {@link getAppBrowserBuildPlugins}
+   * when the transform name is already present in `sourceTransforms`.
    */
   async initializeDefaultLoaders() {
     const componentMetaTransform = createEcoComponentMetaTransform({ config: this.config });
@@ -593,7 +636,6 @@ class ConfigBuilder {
     updateAppBuildManifest(this.config, await collectConfiguredAppBuildManifestContributions(this.config));
     setAppServerInvalidationState(this.config, new CounterServerInvalidationState());
     setAppEntrypointDependencyGraph(this.config, new NoopEntrypointDependencyGraph());
-    setAppBuildExecutor(this.config, buildAdapter);
     return this.config;
   }
 }

package/src/config/constants.d.ts

@@ -7,6 +7,7 @@
  */
 export declare const STATUS_MESSAGE: {
     404: string;
+    500: string;
 };
 /**
  *Variables used to determine if the app is running on Bun

package/src/config/constants.js

@@ -1,5 +1,6 @@
 const STATUS_MESSAGE = {
-  404: "404 Not Found"
+  404: "404 Not Found",
+  500: "Internal Server Error"
 };
 const IS_BUN = typeof Bun !== "undefined";
 const RESOLVED_ASSETS_DIR = "assets";

package/src/dev/client-bridge-registry.d.ts

@@ -0,0 +1,5 @@
+import type { EcoPagesAppConfig } from '../types/public-types.js';
+import type { IClientBridge } from '../types/public-types.js';
+export declare function setAppDevClientBridge(appConfig: EcoPagesAppConfig, bridge: IClientBridge): void;
+export declare function getAppDevClientBridge(appConfig: EcoPagesAppConfig): IClientBridge | undefined;
+export declare function clearAppDevClientBridge(appConfig: EcoPagesAppConfig): void;

package/src/dev/client-bridge-registry.js

@@ -0,0 +1,15 @@
+const appDevClientBridges = /* @__PURE__ */ new WeakMap();
+function setAppDevClientBridge(appConfig, bridge) {
+  appDevClientBridges.set(appConfig, bridge);
+}
+function getAppDevClientBridge(appConfig) {
+  return appDevClientBridges.get(appConfig);
+}
+function clearAppDevClientBridge(appConfig) {
+  appDevClientBridges.delete(appConfig);
+}
+export {
+  clearAppDevClientBridge,
+  getAppDevClientBridge,
+  setAppDevClientBridge
+};

package/src/dev/dev-client-ownership.d.ts

@@ -0,0 +1,7 @@
+import type { ApplicationRuntimeOptions } from '../adapters/abstract/application-adapter.js';
+/**
+ * Returns whether the host dev server owns all browser dev-client bootstrap.
+ *
+ * When true, core must not inject the HMR runtime or signal full-page reloads.
+ */
+export declare function hostOwnsDevClient(runtime?: ApplicationRuntimeOptions): boolean;

package/src/dev/dev-client-ownership.js

@@ -0,0 +1,6 @@
+function hostOwnsDevClient(runtime) {
+  return runtime?.devClientOwner === "host" || runtime?.delegateBrowserReloadToHost === true;
+}
+export {
+  hostOwnsDevClient
+};

package/src/dev/hmr-manager-registry.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Per-app registry for the shared HMR manager used by host-owned dev clients.
+ */
+import type { EcoPagesAppConfig } from '../types/public-types.js';
+import type { IHmrManager } from '../types/public-types.js';
+export declare function setAppHmrManager(appConfig: EcoPagesAppConfig, hmrManager: IHmrManager): void;
+export declare function getAppHmrManager(appConfig: EcoPagesAppConfig): IHmrManager | undefined;
+export declare function clearAppHmrManager(appConfig: EcoPagesAppConfig): void;

package/src/dev/hmr-manager-registry.js

@@ -0,0 +1,15 @@
+const appHmrManagers = /* @__PURE__ */ new WeakMap();
+function setAppHmrManager(appConfig, hmrManager) {
+  appHmrManagers.set(appConfig, hmrManager);
+}
+function getAppHmrManager(appConfig) {
+  return appHmrManagers.get(appConfig);
+}
+function clearAppHmrManager(appConfig) {
+  appHmrManagers.delete(appConfig);
+}
+export {
+  clearAppHmrManager,
+  getAppHmrManager,
+  setAppHmrManager
+};

package/src/dev/host-runtime.d.ts

@@ -1,10 +1,13 @@
 import type { EcoPagesAppConfig } from '../types/public-types.js';
 import { type DevelopmentInvalidationPlan } from '../services/invalidation/development-invalidation.service.js';
+import type { ClientBridgeEvent } from '../types/public-types.js';
 export type HostRuntimeModuleLoader = (id: string) => Promise<unknown>;
 export interface DevelopmentHostRuntime {
     registerHostModuleLoader(loader: HostRuntimeModuleLoader): void;
     planFileChange(filePath: string): DevelopmentInvalidationPlan;
     invalidateServerModules(changedFiles?: string[]): void;
     resetRuntimeState(changedFiles?: string[]): void;
+    broadcastClientEvent(event: ClientBridgeEvent): void;
+    isServerRenderedTemplatePlan(plan: DevelopmentInvalidationPlan): boolean;
 }
 export declare function createDevelopmentHostRuntime(appConfig: EcoPagesAppConfig): DevelopmentHostRuntime;

package/src/dev/host-runtime.js

@@ -1,6 +1,7 @@
 import {
   DevelopmentInvalidationService
 } from "../services/invalidation/development-invalidation.service.js";
+import { getAppDevClientBridge } from "./client-bridge-registry.js";
 import { setHostModuleLoader } from "../services/module-loading/host-module-loader-registry.js";
 function createDevelopmentHostRuntime(appConfig) {
   const invalidationService = new DevelopmentInvalidationService(appConfig);
@@ -16,6 +17,12 @@ function createDevelopmentHostRuntime(appConfig) {
     },
     resetRuntimeState(changedFiles) {
       invalidationService.resetRuntimeState(changedFiles);
+    },
+    broadcastClientEvent(event) {
+      getAppDevClientBridge(appConfig)?.broadcast(event);
+    },
+    isServerRenderedTemplatePlan(plan) {
+      return plan.category === "include-source" || plan.category === "explicit-server-view";
     }
   };
 }

package/src/dev/runtime-server-started-message.d.ts

@@ -0,0 +1,2 @@
+export type EcopagesRuntimeLabel = 'Bun' | 'Node';
+export declare function formatRuntimeServerStartedMessage(runtime: EcopagesRuntimeLabel, origin: string): string;

package/src/dev/runtime-server-started-message.js

@@ -0,0 +1,6 @@
+function formatRuntimeServerStartedMessage(runtime, origin) {
+  return `${runtime} server running at ${origin.replace(/\/$/, "")}`;
+}
+export {
+  formatRuntimeServerStartedMessage
+};

package/src/diagnostics/request-build-dedupe.d.ts

@@ -0,0 +1,18 @@
+import type { BuildResult } from '../build/build-adapter.js';
+/**
+ * Per-request browser build dedupe cache.
+ *
+ * @remarks
+ * `DedupingBuildExecutor` only coalesces concurrent identical builds. Asset
+ * processing can call the same logical bundle several times in one request
+ * (page graph, HMR, content scripts) after the first build settles. This cache
+ * reuses the settled result until the request scope ends.
+ */
+declare class RequestBuildDedupe {
+    private readonly storage;
+    run<T>(fn: () => Promise<T>): Promise<T>;
+    dedupeBuild(key: string, build: () => Promise<BuildResult>): Promise<BuildResult>;
+    getCachedCountForTests(): number;
+}
+export declare const requestBuildDedupe: RequestBuildDedupe;
+export {};

package/src/diagnostics/request-build-dedupe.js

@@ -0,0 +1,33 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+class RequestBuildDedupe {
+  storage = new AsyncLocalStorage();
+  run(fn) {
+    if (this.storage.getStore()) {
+      return fn();
+    }
+    return this.storage.run(/* @__PURE__ */ new Map(), fn);
+  }
+  dedupeBuild(key, build) {
+    const store = this.storage.getStore();
+    if (!store) {
+      return build();
+    }
+    const existing = store.get(key);
+    if (existing) {
+      return existing;
+    }
+    const buildPromise = build().catch((error) => {
+      store.delete(key);
+      throw error;
+    });
+    store.set(key, buildPromise);
+    return buildPromise;
+  }
+  getCachedCountForTests() {
+    return this.storage.getStore()?.size ?? 0;
+  }
+}
+const requestBuildDedupe = new RequestBuildDedupe();
+export {
+  requestBuildDedupe
+};

package/src/diagnostics/startup-trace.d.ts

@@ -0,0 +1,72 @@
+export type StartupTracePhase = 'config-ready' | 'setupAppRuntimePlugins' | 'route-registry' | 'server-listen' | 'first-byte' | 'first-page-browser-graph' | 'first-request-ssr' | 'client-transfer' | 'client-hydration';
+type PhaseRecord = {
+    durationMs: number;
+    wallMs: number;
+};
+export type StartupTraceReport = {
+    generatedAt: string;
+    runtime: string;
+    platform: string;
+    phases: Partial<Record<StartupTracePhase, PhaseRecord>>;
+    firstRequest?: {
+        path: string;
+        bundleCount: number;
+        clientBundleBytes: number;
+        graphBuildCount: number;
+        wallMs: number;
+    };
+    client?: {
+        requestCount: number;
+        transferredBytes: number;
+        hmrConnected: boolean;
+        hydrationReadyMs: number | null;
+    };
+};
+declare class StartupTrace {
+    private readonly phaseNesting;
+    private readonly phases;
+    private firstRequestPending;
+    private firstRequestPath;
+    private firstRequestBundleCount;
+    private firstRequestClientBytes;
+    private firstRequestGraphBuildCount;
+    private summaryEmitted;
+    private firstPageBrowserGraphEmitted;
+    private clientRequestCount;
+    private clientTransferredBytes;
+    private hmrConnected;
+    private hydrationReadyMs;
+    isEnabled(): boolean;
+    markPhaseStart(phase: StartupTracePhase): void;
+    markPhaseEnd(phase: StartupTracePhase): void;
+    markConfigReady(): void;
+    markServerListening(): void;
+    beginServerListen(): void;
+    markFirstByte(): void;
+    beginFirstByte(): void;
+    markFirstPageBrowserGraphReady(graphBuildCount?: number): void;
+    recordBrowserBundle(outputs: Array<{
+        path: string;
+    }>): void;
+    recordClientTransfer(requestCount: number, transferredBytes: number): void;
+    beginClientTransfer(): void;
+    recordClientHydration(durationMs: number): void;
+    beginClientHydration(): void;
+    recordHmrConnected(): void;
+    traceFirstRequest<T>(request: Request, handler: () => Promise<T>): Promise<T>;
+    private emitFirstRequestSummary;
+    private writeJsonReport;
+    createReport(): StartupTraceReport;
+    /** Resets mutable trace state for unit tests. */
+    resetForTests(): void;
+    /**
+     * Resets only the first-request bundle counters.
+     *
+     * @remarks
+     * Used by tests that need to re-measure first-request browser bundle work
+     * without clearing earlier startup phase records.
+     */
+    resetFirstRequestCounters(): void;
+}
+export declare const startupTrace: StartupTrace;
+export {};