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

package/src/types/internal-types.d.ts

@@ -5,7 +5,7 @@ import type { BuildRuntime } from '../build/runtime/build-runtime.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 './public-types.js';
+import type { PageMetadataProps, SitemapConfig } from './public-types.js';
 import type { RouteRegistry } from '../router/server/route-registry.js';
 import type { CacheConfig } from '../services/cache/cache.types.js';
 import type { DevGraphService } from '../services/runtime-state/dev-graph.service.js';
@@ -99,6 +99,12 @@ export type EcoPagesAppConfig = {
          */
         preferences: RobotsPreference;
     };
+    /**
+     * Automatic sitemap.xml generation during static export.
+     *
+     * @default { enabled: false, fileName: 'sitemap.xml', extraUrls: [], exclude: [] }
+     */
+    sitemap: SitemapConfig;
     /** Additional paths to watch. Use this to monitor extra files. It is relative to the rootDir */
     additionalWatchPaths: string[];
     /**
@@ -123,6 +129,7 @@ export type EcoPagesAppConfig = {
         srcDir: string;
         htmlTemplatePath: string;
         error404TemplatePath: string;
+        error500TemplatePath: string;
     };
     /**
      * The processors to be used in the app

package/src/types/public-types.d.ts

@@ -534,6 +534,21 @@ export type EcoComponent<P = any, R = any> = IsAny<P> extends true ? EcoFunction
 export type PageProps<T = unknown> = T & StaticPageContext & {
     locals?: RequestLocals;
 };
+/**
+ * Page-level robots directives for the document head and sitemap filtering.
+ *
+ * @remarks
+ * When `index` is `false`, the page is omitted from the auto-generated sitemap
+ * for routes whose metadata can be resolved during static export (filesystem
+ * pages and `app.static()` views with `metadata`). Defaults when omitted:
+ * `index: true`, `follow: true`. A `<meta name="robots">` tag is emitted by the
+ * route HTML finalization path when directives differ from those defaults.
+ */
+export interface PageRobotsMetadata {
+    index?: boolean;
+    follow?: boolean;
+    nocache?: boolean;
+}
 /**
  * Represents the metadata for a page.
  */
@@ -543,6 +558,48 @@ export interface PageMetadataProps {
     image?: string;
     url?: string;
     keywords?: string[];
+    robots?: PageRobotsMetadata;
+}
+/**
+ * Configuration for automatic `sitemap.xml` generation during static export.
+ *
+ * @remarks
+ * Disabled by default. When enabled, the sitemap is written after
+ * `afterStaticExport` so integration-generated URLs can be listed via
+ * `extraUrls`. Use `exclude` for bulk pathname filters and `metadata.robots.index: false`
+ * for page-level noindex that also removes the URL from the sitemap when metadata
+ * is available during export.
+ */
+export interface SitemapConfig {
+    /** Emit sitemap.xml during static generation. @default false */
+    enabled?: boolean;
+    /** Output file name. @default "sitemap.xml" */
+    fileName?: string;
+    /**
+     * Extra, non-page URLs to include (e.g. "/rss.xml").
+     *
+     * @remarks
+     * Relative paths are resolved against `baseUrl`. Absolute `http(s)` URLs pass
+     * through. Always appended after page URLs; not filtered by `exclude` or page robots.
+     */
+    extraUrls?: string[];
+    /**
+     * Pathname patterns to exclude even if a page exists.
+     *
+     * @remarks
+     * Supported patterns: exact paths (`/admin`) and prefix wildcards (`/admin/**`).
+     * Unsupported patterns are treated as exact matches. This is not a full glob engine.
+     */
+    exclude?: string[];
+}
+/**
+ * Slim route descriptor for static-export hooks and runtime consumers.
+ */
+export interface EcopagesRouteInfo {
+    /** Resolved URL pathname, e.g. `/blog/my-post`. */
+    pathname: string;
+    /** Route params for dynamic routes (empty for static routes). */
+    params: Record<string, string>;
 }
 /**
  * Represents the props for the head of a page.
@@ -622,12 +679,25 @@ export type EcoLayoutComponent<T = EcoPagesElement> = EcoComponent<LayoutProps<T
  */
 export type EcoHtmlComponent<T = EcoPagesElement> = EcoComponent<HtmlTemplateProps, T>;
 /**
- * Represents the props for the error 404 template.
+ * Props type for the semantic `404.*` page template.
+ * @remarks `message` and `stack` are declared for future error context. The
+ * runtime does not currently pass these props when rendering the custom 404 page.
  */
 export interface Error404TemplateProps extends Omit<HtmlTemplateProps, 'children'> {
     message: string;
     stack?: string;
 }
+/**
+ * Props type for the semantic `500.*` page template.
+ * @remarks In development, the page-pipeline passes `message` and `stack` from the
+ * thrown error when rendering this page after a failure. In production those
+ * fields are omitted so stacks are not serialized into HTML. Direct visits to
+ * `/500` also omit them.
+ */
+export interface Error500TemplateProps extends Omit<HtmlTemplateProps, 'children'> {
+    message?: string;
+    stack?: string;
+}
 /**
  * Represents the parameters for a page.
  * The keys are strings, and the values can be either a string or an array of strings.
@@ -751,6 +821,12 @@ export type RouteRendererOptions = {
     params?: PageParams;
     query?: PageQuery;
     locals?: RequestLocals;
+    /**
+     * Extra props merged into the page props for this render.
+     * @remarks Used by semantic error pages (for example development `message` /
+     * `stack` on the custom 500 page).
+     */
+    props?: Record<string, unknown>;
 };
 /**
  * The body of the route renderer.

package/src/utils/ecopages-route-info.d.ts

@@ -0,0 +1,26 @@
+import type { EcopagesRouteInfo } from '../types/public-types.js';
+/**
+ * Maps a static-generation or registry route into the public slim route shape.
+ */
+export declare function toEcopagesRouteInfo(route: {
+    pathname: string;
+    params: Record<string, string | string[]>;
+}): EcopagesRouteInfo;
+/**
+ * Flattens string | string[] route params into string values for public APIs.
+ */
+export declare function normalizeRouteParams(params: Record<string, string | string[]>): Record<string, string>;
+type StaticGenerationRouteLister = (input: {
+    runtimeOrigin: string;
+}) => Promise<readonly {
+    pathname: string;
+    params: Record<string, string | string[]>;
+}[]>;
+/**
+ * Resolves {@link EcopagesRouteInfo} entries for app-start and similar consumers.
+ */
+export declare function resolveAppStartRoutes(input: {
+    listStaticGenerationRoutes?: StaticGenerationRouteLister;
+    runtimeOrigin: string;
+}): Promise<EcopagesRouteInfo[]>;
+export {};

package/src/utils/ecopages-route-info.js

@@ -0,0 +1,26 @@
+import { normalizePathname } from "./path-pattern.js";
+function toEcopagesRouteInfo(route) {
+  return {
+    pathname: normalizePathname(route.pathname),
+    params: normalizeRouteParams(route.params)
+  };
+}
+function normalizeRouteParams(params) {
+  const normalized = {};
+  for (const [key, value] of Object.entries(params)) {
+    normalized[key] = Array.isArray(value) ? value.join("/") : value;
+  }
+  return normalized;
+}
+async function resolveAppStartRoutes(input) {
+  if (!input.listStaticGenerationRoutes) {
+    return [];
+  }
+  const routes = await input.listStaticGenerationRoutes({ runtimeOrigin: input.runtimeOrigin });
+  return routes.map(toEcopagesRouteInfo);
+}
+export {
+  normalizeRouteParams,
+  resolveAppStartRoutes,
+  toEcopagesRouteInfo
+};

package/src/utils/html-escaping.d.ts

@@ -5,3 +5,10 @@
  * @returns Escaped attribute-safe string.
  */
 export declare function escapeHtmlAttribute(value: string): string;
+/**
+ * Escapes a string for safe use as XML text content (e.g. `<loc>` values).
+ *
+ * @param value Raw text node value.
+ * @returns Escaped XML-safe string.
+ */
+export declare function escapeXmlText(value: string): string;

package/src/utils/html-escaping.js

@@ -1,6 +1,10 @@
 function escapeHtmlAttribute(value) {
   return value.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
 }
+function escapeXmlText(value) {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&apos;");
+}
 export {
-  escapeHtmlAttribute
+  escapeHtmlAttribute,
+  escapeXmlText
 };

package/src/utils/path-pattern.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Normalizes a URL pathname for matching and sitemap location building.
+ *
+ * @remarks
+ * Ensures a leading slash and strips trailing slashes except for `/`.
+ */
+export declare function normalizePathname(pathname: string): string;
+/**
+ * Matches a pathname against a small set of supported patterns.
+ *
+ * @remarks
+ * Supported forms:
+ * - exact: `/admin`
+ * - prefix wildcard: `/admin/**` (matches `/admin` and descendants)
+ * - trailing `**` only as a full segment after `/`
+ *
+ * This is not a full glob engine. Unsupported patterns are treated as exact matches.
+ */
+export declare function matchPathPattern(pathname: string, pattern: string): boolean;
+/**
+ * Returns true when the pathname matches any of the patterns.
+ */
+export declare function matchesAnyPathPattern(pathname: string, patterns: readonly string[]): boolean;

package/src/utils/path-pattern.js

@@ -0,0 +1,27 @@
+function normalizePathname(pathname) {
+  if (!pathname || pathname === "/") {
+    return "/";
+  }
+  const withLeadingSlash = pathname.startsWith("/") ? pathname : `/${pathname}`;
+  return withLeadingSlash.replace(/\/+$/, "") || "/";
+}
+function matchPathPattern(pathname, pattern) {
+  const normalizedPath = normalizePathname(pathname);
+  const normalizedPattern = pattern.trim();
+  if (normalizedPattern.endsWith("/**")) {
+    const prefix = normalizePathname(normalizedPattern.slice(0, -3));
+    if (prefix === "/") {
+      return true;
+    }
+    return normalizedPath === prefix || normalizedPath.startsWith(`${prefix}/`);
+  }
+  return normalizedPath === normalizePathname(normalizedPattern);
+}
+function matchesAnyPathPattern(pathname, patterns) {
+  return patterns.some((pattern) => matchPathPattern(pathname, pattern));
+}
+export {
+  matchPathPattern,
+  matchesAnyPathPattern,
+  normalizePathname
+};