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

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

@@ -1,18 +1,23 @@
-import type { EcoBuildPlugin } from '../build/build-types.js';
-import type { AppBuildManifest } from '../build/build-manifest.js';
-import type { BuildAdapter, BuildExecutor, BuildOwnership } from '../build/build-adapter.js';
+import type { EcoBuildPlugin } from '../build/contracts/build-types.js';
+import type { AppBuildManifest } from '../build/contracts/build-manifest.js';
+import type { BuildAdapter, BuildOwnership } from '../build/build-adapter.js';
+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';
 import type { AppModuleLoader } from '../services/module-loading/app-module-loader.service.js';
 import type { SourceModuleLoader } from '../services/module-loading/module-loading-types.js';
 import type { EntrypointDependencyGraph } from '../services/runtime-state/entrypoint-dependency-graph.service.js';
+import type { SessionPageBrowserGraphCache } from '../route-renderer/orchestration/page-browser-graph/page-browser-graph-session.js';
 import type { ServerInvalidationState } from '../services/runtime-state/server-invalidation-state.service.js';
 import type { ServerModuleTranspiler } from '../services/module-loading/server-module-transpiler.service.js';
+import type { RouteModuleBuildCache } from '../services/module-loading/route-module-build-cache.store.js';
+/** Integration hook for registered `dependencies.scripts` entrypoint changes in dev. */
+export type RegisteredScriptEntrypointChangeHandler = (filePath: string) => void | Promise<void>;
 export interface RobotsPreference {
     /**
      * The user agent
@@ -94,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[];
     /**
@@ -118,6 +129,7 @@ export type EcoPagesAppConfig = {
         srcDir: string;
         htmlTemplatePath: string;
         error404TemplatePath: string;
+        error500TemplatePath: string;
     };
     /**
      * The processors to be used in the app
@@ -149,13 +161,34 @@ export type EcoPagesAppConfig = {
         buildOwnership?: BuildOwnership;
         buildAdapter?: BuildAdapter;
         buildManifest?: AppBuildManifest;
-        buildExecutor?: BuildExecutor;
         devGraphService?: DevGraphService;
         entrypointDependencyGraph?: EntrypointDependencyGraph;
+        pageBrowserGraphSession?: SessionPageBrowserGraphCache;
         hostModuleLoader?: SourceModuleLoader;
         rendererModuleContext?: unknown;
         serverInvalidationState?: ServerInvalidationState;
         serverModuleTranspiler?: ServerModuleTranspiler;
+        routeModuleBuildCaches?: Map<string, RouteModuleBuildCache>;
+        /** Profile-based build runtime installed by {@link installBuildRuntime}. */
+        buildRuntime?: BuildRuntime;
+        /** Set after {@link setupAppRuntimePlugins} runs processor/integration setup once per process. */
+        runtimeAssetsPrepared?: boolean;
+        /** Registers integration runtime plugins when lazy activation completes. */
+        onRuntimePlugin?: (plugin: import('../build/contracts/build-types.js').EcoBuildPlugin) => void;
+        /**
+         * In-flight or completed lazy integration activation promises, keyed by integration name.
+         *
+         * @remarks
+         * Concurrent callers (background prewarm + first render) share the same promise.
+         * Failed activations are removed so a later caller can retry.
+         */
+        integrationActivations?: Map<string, Promise<void>>;
+        /** When `'host'`, the embedded dev server owns browser dev-client bootstrap. */
+        devClientOwner?: 'core' | 'host';
+        /** Integration hooks run when a registered `dependencies.scripts` entrypoint changes. */
+        registeredScriptEntrypointChangeHandlers?: RegisteredScriptEntrypointChangeHandler[];
+        /** @deprecated Prefer {@link devClientOwner}: `'host'`. */
+        delegateBrowserReloadToHost?: boolean;
     };
     /**
      * Experimental features.
@@ -222,11 +255,4 @@ export interface EcoPagesFileSystemServerAdapter<ServerInstanceOptions = unknown
         server: unknown;
     }>;
 }
-export interface ProcessorPlugin {
-    name: string;
-    description?: string;
-    setup(): Promise<void>;
-    process<T = unknown>(input: T): Promise<T>;
-    teardown?(): Promise<void>;
-}
-export type { ClientBridgeEvent, DefaultHmrContext, IHmrManager, IClientBridge } from './public-types.js';
+export type { ClientBridgeEvent, DefaultHmrContext, HmrFileChangeOptions, IHmrManager, IClientBridge, } from './public-types.js';

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

@@ -1,8 +1,7 @@
 import type { Readable } from 'node:stream';
-import type { ApiResponseBuilder } from '../adapters/shared/api-response.js';
+import type { ApiResponseBuilder } from '../adapters/shared/http/api-response.js';
 import type { BuildExecutor } from '../build/build-adapter.js';
-import type { EcoBuildPlugin } from '../build/build-types.js';
-import type { ForeignChildRuntime } from '../route-renderer/orchestration/component-render-context.js';
+import type { ForeignChildRuntime } from '../route-renderer/orchestration/foreign-child/component-render-context.js';
 import type { EcoPageComponent } from '../eco/eco.types.js';
 import type { EcoPagesAppConfig } from './internal-types.js';
 import type { HmrStrategy } from '../hmr/hmr-strategy.js';
@@ -14,8 +13,84 @@ import type { EntrypointDependencyGraph } from '../services/runtime-state/entryp
 export type { EcoPagesAppConfig } from './internal-types.js';
 export type { EcoPageComponent } from '../eco/eco.types.js';
 export type { ProcessedAsset } from '../services/assets/asset-processing-service/assets.types.js';
-import type { StandardSchema, StandardSchemaResult, StandardSchemaSuccessResult, StandardSchemaFailureResult, StandardSchemaIssue, InferOutput } from '../services/validation/standard-schema.types.js';
-export type { StandardSchema, StandardSchemaResult, StandardSchemaSuccessResult, StandardSchemaFailureResult, StandardSchemaIssue, InferOutput, ForeignChildRuntime, };
+/**
+ * Runtime-agnostic incoming WebSocket frame.
+ *
+ * Both Bun and Node `ws` deliver text and binary frames; this discriminated
+ * union lets handlers deal with both without runtime-specific casts.
+ */
+export type IncomingWebSocketMessage = {
+    readonly kind: 'text';
+    readonly text: string;
+} | {
+    readonly kind: 'binary';
+    readonly data: Uint8Array;
+};
+/**
+ * Runtime-agnostic outgoing WebSocket payload.
+ *
+ * Strings are sent as text frames. Anything binary-shaped is sent as binary
+ * frames. `Blob` is included for cross-runtime parity and is normalized to a
+ * binary frame by each adapter.
+ */
+export type OutgoingWebSocketMessage = string | Uint8Array | ArrayBuffer | ArrayBufferView | Blob;
+/**
+ * Close event delivered to `onClose` after a connection terminates.
+ */
+export interface WebSocketCloseInfo {
+    readonly code: number;
+    readonly reason: string;
+    readonly wasClean: boolean;
+}
+/**
+ * Input passed to a WebSocket handler's `context()` factory.
+ *
+ * Adapters call `context()` exactly once per accepted upgrade. The returned
+ * value becomes `socket.context` and is shared by all lifecycle hooks.
+ */
+export interface WebSocketContextFactoryInput<TParams extends Record<string, string> = Record<string, string>> {
+    readonly request: Request;
+    readonly kind: string;
+    readonly params: TParams;
+    readonly search: Readonly<Record<string, string>>;
+    readonly locals?: RequestLocals;
+}
+/**
+ * Runtime-agnostic WebSocket socket view exposed to handlers.
+ *
+ * Framework-owned fields:
+ * - `kind`: the registered route pattern (e.g. '/ws/chat/:roomId')
+ * - `params`: dynamic segments captured at match time
+ * - `search`: query string, always string-typed
+ *
+ * App-owned field:
+ * - `context`: returned by the handler's `context()` factory
+ */
+export interface EcopagesSocket<TContext = unknown, TParams extends Record<string, string> = Record<string, string>> {
+    readonly kind: string;
+    readonly params: TParams;
+    readonly search: Readonly<Record<string, string>>;
+    readonly context: TContext;
+    send(message: OutgoingWebSocketMessage): void;
+    sendStream(stream: ReadableStream<Uint8Array>): Promise<void>;
+    close(code?: number, reason?: string): void;
+}
+/**
+ * Connection-lifecycle handler object.
+ *
+ * All hooks are optional. `context()` is the one-time initializer that
+ * produces the per-connection state shared by the lifecycle hooks. Returning
+ * a rejected promise from `context()` aborts the upgrade.
+ */
+export interface EcopagesWebSocketHandler<TContext = unknown, TParams extends Record<string, string> = Record<string, string>> {
+    context?(input: WebSocketContextFactoryInput<TParams>): TContext | Promise<TContext>;
+    onConnect?(socket: EcopagesSocket<TContext, TParams>): void | Promise<void>;
+    onMessage?(socket: EcopagesSocket<TContext, TParams>, message: IncomingWebSocketMessage): void | Promise<void>;
+    onClose?(socket: EcopagesSocket<TContext, TParams>, event: WebSocketCloseInfo): void | Promise<void>;
+    onError?(socket: EcopagesSocket<TContext, TParams>, error: unknown): void | Promise<void>;
+}
+import type { StandardSchema, StandardSchemaResult, StandardSchemaSuccessResult, StandardSchemaFailureResult, StandardSchemaIssue, InferOutput, StandardSchemaV1 } from '../services/validation/standard-schema.types.js';
+export type { StandardSchema, StandardSchemaResult, StandardSchemaSuccessResult, StandardSchemaFailureResult, StandardSchemaIssue, InferOutput, StandardSchemaV1, ForeignChildRuntime, };
 export type InteractionEventsString = ScriptsInjectorInteractionEventsString;
 export type DependencyLazyTrigger = {
     'on:idle': true;
@@ -99,10 +174,6 @@ export interface DefaultHmrContext {
      * Directory where HMR bundles are written.
      */
     getDistDir(): string;
-    /**
-     * Build plugins to use during bundling.
-     */
-    getPlugins(): EcoBuildPlugin[];
     /**
      * Absolute path to the source directory.
      */
@@ -133,6 +204,14 @@ export interface DefaultHmrContext {
      * Entrypoint dependency graph for selective HMR invalidation.
      */
     getEntrypointDependencyGraph(): EntrypointDependencyGraph;
+    /**
+     * Registers an already-materialized HMR entrypoint without rebuilding it.
+     *
+     * @remarks
+     * Cold dev batches seed the registrar after grouped builds so the first SSR
+     * resolves the artifact from disk instead of triggering a rebuild.
+     */
+    seedResolvedEntrypoint(resolved: ResolvedHmrEntrypoint): void;
 }
 /**
  * Represents an event broadcast to connected clients via the ClientBridge.
@@ -154,6 +233,22 @@ export type ClientBridgeEvent = {
      * Timestamp for cache busting
      */
     timestamp?: number;
+    /**
+     * Page Browser Graph identities invalidated by the originating file change.
+     */
+    graphIdentities?: Array<{
+        integrationName: string;
+        routeFile: string;
+        policy: 'development' | 'production';
+        entryFingerprint: string;
+    }>;
+};
+/**
+ * Options for handling a development file change through HMR.
+ */
+export type HmrFileChangeOptions = {
+    broadcast?: boolean;
+    graphIdentities?: ClientBridgeEvent['graphIdentities'];
 };
 /**
  * Adapter-agnostic interface for broadcasting development events to connected clients.
@@ -167,6 +262,14 @@ export interface IClientBridge {
     error(message: string): void;
     subscriberCount: number;
 }
+/**
+ * Verified HMR entrypoint artifact produced by registration.
+ */
+export interface ResolvedHmrEntrypoint {
+    sourcePath: string;
+    outputPath: string;
+    outputUrl: string;
+}
 /**
  * Interface for the HMR Manager.
  * Used by integration plugins to register entrypoints and strategies.
@@ -188,19 +291,19 @@ export interface IHmrManager {
      * framework integration. Unlike `registerEntrypoint()`, it may use the generic
      * script bundling path.
      */
-    registerScriptEntrypoint(entrypointPath: string): Promise<string>;
+    registerScriptEntrypoint(entrypointPath: string): Promise<ResolvedHmrEntrypoint>;
     /**
      * Registers a custom HMR strategy.
      */
     registerStrategy(strategy: HmrStrategy): void;
-    /**
-     * Sets the build plugins to use during bundling.
-     */
-    setPlugins(plugins: EcoBuildPlugin[]): void;
     /**
      * Enables or disables HMR.
      */
     setEnabled(enabled: boolean): void;
+    /**
+     * Stops active HMR watchers and releases dev-time resources.
+     */
+    stop(): void;
     /**
      * Returns whether HMR is enabled.
      */
@@ -213,6 +316,18 @@ export interface IHmrManager {
      * Gets the output URL for a registered entrypoint.
      */
     getOutputUrl(entrypointPath: string): string | undefined;
+    /**
+     * Returns an existing emitted HMR script artifact without registering it.
+     */
+    getResolvedScriptOutput?(entrypointPath: string): ResolvedHmrEntrypoint | undefined;
+    /**
+     * Registers an already-materialized HMR entrypoint without rebuilding it.
+     *
+     * @remarks
+     * Cold dev batches seed the registrar after grouped builds so the first SSR
+     * resolves the artifact from disk instead of triggering a rebuild.
+     */
+    seedResolvedEntrypoint?(resolved: ResolvedHmrEntrypoint): void;
     /**
      * Gets the map of watched files.
      */
@@ -222,9 +337,13 @@ export interface IHmrManager {
      */
     getDistDir(): string;
     /**
-     * Gets the build plugins.
+     * Returns the on-disk path to the bundled HMR runtime script.
      */
-    getPlugins(): EcoBuildPlugin[];
+    getRuntimePath(): string;
+    /**
+     * Serves a development HMR asset request when the URL matches a known HMR path.
+     */
+    tryHandleAssetRequest(request: Request): Response | null;
     /**
      * Gets the default HMR context.
      */
@@ -232,7 +351,7 @@ export interface IHmrManager {
     /**
      * Handles a file change event.
      */
-    handleFileChange(path: string): Promise<void>;
+    handleFileChange(path: string, options?: HmrFileChangeOptions): Promise<void>;
 }
 /**
  * Represents the dependencies for an EcoComponent.
@@ -247,23 +366,35 @@ export type EcoComponentDependencies = {
      * to express explicit module imports for client bundles.
      */
     modules?: string[];
-    components?: EcoComponent[];
+    /**
+     * Child components whose assets and foreign-child graph are collected transitively.
+     * Each entry must be an `eco.component()`, `eco.layout()`, or `eco.html()` result
+     * with plugin-injected `config.__eco` metadata.
+     */
+    components?: EcoDeclaredComponent[];
 };
+/**
+ * Component returned from `eco.component()`, `eco.layout()`, or `eco.html()`.
+ *
+ * @remarks
+ * Used for `dependencies.components` and eco factory return types. Plugin-injected
+ * `config.__eco` is enforced at runtime via `isEcoDeclaredComponent()`, not by this alias.
+ */
+export type EcoDeclaredComponent<P = any, R = any> = EcoComponent<P, R>;
 export type EcoPagesElement = string | Promise<string>;
 /**
  * Serializable child payloads accepted by cross-integration deferred rendering.
  *
- * This models the broad value shapes that EcoPages already flattens when a
- * foreign component boundary serializes its children for another integration.
- * It is intentionally transport-oriented rather than framework-native, so it
- * can be shared across Kita, Lit, React, and Ecopages JSX authoring surfaces
- * without coupling core types to any one renderer.
+ * @remarks
+ * Covers primitives, arrays, and Kita/Lit-style template results (`strings` /
+ * optional `values`). Plain opaque objects are intentionally excluded; foreign
+ * composition boundaries reject them before serializers can coerce `String(object)`.
+ * Framework-native trees (React nodes, JSX elements) stay outside this type and
+ * use EcoEmbed or already-serialized HTML at the boundary.
  */
 export type EcoChildren = string | Promise<string> | number | bigint | boolean | null | undefined | readonly EcoChildren[] | {
     strings: readonly string[];
     values?: readonly EcoChildren[];
-} | {
-    [key: string]: EcoChildren;
 };
 /**
  * Represents the input configuration for EcoPages.
@@ -314,11 +445,13 @@ export type EcoComponentConfig = {
      * );
      *
      * // Page using the layout
-     * const MyPage = () => <h1>Hello</h1>;
-     * MyPage.config = { layout: Layout };
+     * const MyPage = eco.page({ layout: Layout, render: () => <h1>Hello</h1> });
      * ```
      */
-    layout?: EcoPageLayoutComponent<any>;
+    /** Normalized outer→inner layout stack from `eco.page({ layout: [...] })`. */
+    layouts?: EcoDeclaredComponent[];
+    /** Layout entries retained for per-tier prop factories. */
+    layoutEntries?: EcoPageLayoutEntry[];
     dependencies?: EcoComponentDependencies;
     /**
      * Internal: Resolved lazy scripts grouped by trigger.
@@ -409,6 +542,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.
  */
@@ -418,6 +566,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.
@@ -441,7 +631,46 @@ export interface HtmlTemplateProps<T = EcoPagesElement> extends PageHeadProps<T>
     language?: string;
     headContent?: T;
     pageProps: Record<string, unknown>;
+    /**
+     * Browser-importable page module URL for router-enabled documents.
+     *
+     * @remarks
+     * Transport-only: threaded into HTML shells (for example `EcoPropsScript`
+     * `moduleUrl`) and serialized as the page-data envelope `moduleUrl`. Not page
+     * component state.
+     */
+    pageModuleUrl?: string;
 }
+/**
+ * Request-scoped context available to layout prop factories on `eco.page`.
+ */
+export type LayoutPropsContext = {
+    params?: Record<string, string>;
+    query?: Record<string, string>;
+    locals?: RequestLocals;
+};
+/**
+ * One layout tier in a page layout stack (outer→inner).
+ */
+export type EcoPageLayoutEntry<E = EcoPagesElement> = {
+    component: EcoDeclaredComponent<any, E>;
+    props?: (context: LayoutPropsContext) => Record<string, unknown>;
+};
+/**
+ * Layout declaration accepted by `eco.page()`.
+ *
+ * @remarks
+ * Array order is outer→inner, matching Next.js App Router segment nesting.
+ */
+export type EcoPageLayoutSpec<E = EcoPagesElement> = EcoDeclaredComponent<any, E> | EcoPageLayoutEntry<E>;
+/**
+ * One or more layout tiers for `eco.page({ layout })`.
+ *
+ * @remarks
+ * When an array, order is **outer → inner** (outermost layout wraps all inner tiers).
+ * Normalized at factory time to `config.layouts` and `config.layoutEntries`.
+ */
+export type EcoPageLayouts<E = EcoPagesElement> = EcoPageLayoutSpec<E> | EcoPageLayoutSpec<E>[];
 /**
  * Layout components accepted by pages.
  *
@@ -458,12 +687,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.
@@ -587,6 +829,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.
@@ -659,15 +907,15 @@ export type IntegrationRendererRenderOptions<C = EcoPagesElement> = RouteRendere
     metadata: PageMetadataProps;
     HtmlTemplate: EcoHtmlComponent<C>;
     Page: EcoComponent<PageProps, C>;
+    Layouts?: EcoDeclaredComponent[];
     Layout?: EcoPageLayoutComponent<any>;
+    layoutEntries?: EcoPageLayoutEntry[];
     dependencies?: EcoComponentDependencies;
     resolvedDependencies: ProcessedAsset[];
     pagePackage?: PagePackageResult;
-    componentRender?: ComponentRenderResult;
     pageProps?: Record<string, unknown>;
     cacheStrategy?: CacheStrategy;
     pageLocals?: RequestLocals;
-    ownershipPlan?: OwnershipPlan;
 };
 /**
  * Structured page asset package produced after dependency resolution.
@@ -746,27 +994,6 @@ export interface OwnershipValidationError {
     integrationName?: string;
 }
 export type OwnershipPlanNodeSource = 'route' | 'page' | 'layout' | 'html-template' | 'dependency';
-export interface IntegrationOwnership {
-    integrationName: string;
-    componentId: string;
-    componentFile?: string;
-    isPageEntry: boolean;
-    isForeignToParent: boolean;
-}
-export interface OwnershipPlanNode {
-    id: string;
-    source: OwnershipPlanNodeSource;
-    ownership: IntegrationOwnership;
-    children: OwnershipPlanNode[];
-    declaredDependenciesValid: boolean;
-}
-export interface OwnershipPlan {
-    root: OwnershipPlanNode;
-    rendererNames: string[];
-    foreignEdgeCount: number;
-    hasValidationErrors: boolean;
-    validationErrors: OwnershipValidationError[];
-}
 export type ForeignSubtreeAttachmentPolicy = {
     kind: 'none';
 } | {
@@ -790,6 +1017,16 @@ export interface BaseIntegrationContext {
     rendererCache?: Map<string, unknown>;
     componentInstanceId?: string;
 }
+/**
+ * Shared input for renderer-owned component execution.
+ *
+ * @remarks
+ * `children` stays `unknown` at this boundary so integrations can receive
+ * queued tokens, already-serialized HTML, or framework-native values before
+ * their own placement rules apply. Opaque values must be rejected or converted
+ * by foreign-child interception before string serializers run; adapters keep
+ * framework-specific placement (React raw HTML, Lit slot markers).
+ */
 export interface ComponentRenderInput<TIntegrationContext extends BaseIntegrationContext = BaseIntegrationContext> {
     component: EcoComponent;
     props: Record<string, unknown>;

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
 };