@ecopages/core 0.2.0-beta.9 → 0.2.0-rc.0

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

@@ -1,19 +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 | boolean | Promise<void | boolean>;
 export interface RobotsPreference {
     /**
      * The user agent
@@ -95,8 +99,18 @@ 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[];
+    /** Static paths to SSR-prewarm in development before user navigation. */
+    devPrewarmPaths?: string[];
+    /** Static paths to SSR-prewarm before the development server reports ready. */
+    devPrewarmBeforeReadyPaths?: string[];
     /**
      * @default { title: 'Ecopages', description: 'Ecopages' }
      */
@@ -119,6 +133,7 @@ export type EcoPagesAppConfig = {
         srcDir: string;
         htmlTemplatePath: string;
         error404TemplatePath: string;
+        error500TemplatePath: string;
     };
     /**
      * The processors to be used in the app
@@ -150,20 +165,50 @@ export type EcoPagesAppConfig = {
         buildOwnership?: BuildOwnership;
         buildAdapter?: BuildAdapter;
         buildManifest?: AppBuildManifest;
-        buildExecutor?: BuildExecutor;
-        hmrBuildExecutor?: BuildExecutor;
-        routeModuleBuildExecutor?: BuildExecutor;
         devGraphService?: DevGraphService;
         entrypointDependencyGraph?: EntrypointDependencyGraph;
+        pageBrowserGraphSession?: SessionPageBrowserGraphCache;
         hostModuleLoader?: SourceModuleLoader;
         rendererModuleContext?: unknown;
         serverInvalidationState?: ServerInvalidationState;
         serverModuleTranspiler?: ServerModuleTranspiler;
         routeModuleBuildCaches?: Map<string, RouteModuleBuildCache>;
-        /** Serialized server-entry bundler installed by {@link getInstalledServerEntryBuildExecutor}. */
-        serverEntryBuildExecutor?: BuildExecutor;
+        /** 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[];
+    };
+    /**
+     * Development-only in-browser toolbar configuration.
+     */
+    devToolbar?: {
+        /**
+         * Whether the dev toolbar is enabled during watch mode.
+         *
+         * @default true when `package` is configured
+         */
+        enabled?: boolean;
+        /**
+         * Client package resolved from the application project and bundled to
+         * `/_dev_toolbar.js` during watch mode.
+         *
+         * @example '@ecopages/dev-toolbar'
+         */
+        package?: string;
     };
     /**
      * Experimental features.
@@ -230,11 +275,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/internal-types.js

@@ -0,0 +1 @@
+export {};

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

@@ -1,18 +1,17 @@
 import type { Readable } from 'node:stream';
-import type { ApiResponseBuilder } from '../adapters/shared/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 { ComponentIdentity } from '../eco/component-identity.js';
+import type { ApiResponseBuilder } from '../adapters/shared/http/api-response.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';
-import type { BrowserBundleExecutor } from '../services/assets/browser-bundle.service.js';
 import type { AssetDefinition, ProcessedAsset } from '../services/assets/asset-processing-service/assets.types.js';
 import type { CacheStats, CacheStrategy } from '../services/cache/cache.types.js';
 import type { InteractionEventsString as ScriptsInjectorInteractionEventsString } from '@ecopages/scripts-injector/types';
 import type { EntrypointDependencyGraph } from '../services/runtime-state/entrypoint-dependency-graph.service.js';
+import type { DevTransformBundleContributor } from '../dev/transform-server/types.js';
 export type { EcoPagesAppConfig } from './internal-types.js';
-export type { EcoPageComponent } from '../eco/eco.types.js';
+export type { EcoPageComponent, GetPageDependencies, GetPageDependenciesContext, PageDependenciesResult, } from '../eco/eco.types.js';
 export type { ProcessedAsset } from '../services/assets/asset-processing-service/assets.types.js';
 /**
  * Runtime-agnostic incoming WebSocket frame.
@@ -90,8 +89,8 @@ export interface EcopagesWebSocketHandler<TContext = unknown, TParams extends Re
     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 } from '../services/validation/standard-schema.types.js';
-export type { StandardSchema, StandardSchemaResult, StandardSchemaSuccessResult, StandardSchemaFailureResult, StandardSchemaIssue, InferOutput, ForeignChildRuntime, };
+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;
@@ -164,21 +163,14 @@ export interface CacheInvalidator {
 }
 /**
  * Context interface for HMR strategies.
- * Provides access to watched files, registered bare-specifier mappings, and build configuration.
+ * Provides access to registered entrypoints and build configuration.
  */
 export interface DefaultHmrContext {
     /**
-     * Map of registered entrypoints to their output URLs.
+     * Map of registered entrypoint source paths to their dev-transform output URLs.
      */
     getWatchedFiles(): Map<string, string>;
-    /**
-     * Directory where HMR bundles are written.
-     */
-    getDistDir(): string;
-    /**
-     * Build plugins to use during bundling.
-     */
-    getPlugins(): EcoBuildPlugin[];
+    getRegisteredEntrypoints(): ReadonlyMap<string, ResolvedHmrEntrypoint>;
     /**
      * Absolute path to the source directory.
      */
@@ -193,14 +185,6 @@ export interface DefaultHmrContext {
      * Used by plugins to identify page files for transformation.
      */
     getPagesDir(): string;
-    /**
-     * Build executor owned by the active app/runtime.
-     */
-    getBuildExecutor(): BuildExecutor;
-    /**
-     * Browser bundler owned by the active app/runtime.
-     */
-    getBrowserBundleService(): BrowserBundleExecutor;
     /**
      * Server-side module loader owned by the active app/runtime.
      */
@@ -230,6 +214,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.
@@ -243,40 +243,42 @@ export interface IClientBridge {
     error(message: string): void;
     subscriberCount: number;
 }
+export interface ResolvedHmrEntrypoint {
+    sourcePath: string;
+    outputPath: string;
+    outputUrl: string;
+    role: 'page' | 'script';
+}
 /**
  * Interface for the HMR Manager.
  * Used by integration plugins to register entrypoints and strategies.
  */
 export interface IHmrManager {
     /**
-     * Registers an integration-owned client entrypoint to be built and watched.
+     * Registers a client entrypoint for dev-transform delivery and HMR watching.
      *
      * @remarks
-     * This path is strict: the owning integration must emit the expected `_hmr`
-     * bundle. Missing output is treated as a development pipeline failure.
+     * Returns a stable `/assets/__eco_dev__/…` URL immediately; the module is
+     * transpiled on the first browser request (per-file ESM, not a page bundle).
      */
     registerEntrypoint(entrypointPath: string): Promise<string>;
     /**
-     * Registers a generic script asset entrypoint to be built and watched.
-     *
-     * @remarks
-     * This path exists for non-page script assets that are not owned by a
-     * framework integration. Unlike `registerEntrypoint()`, it may use the generic
-     * script bundling path.
+     * Registers an integration contributor that supplies per-module transform plugins.
      */
-    registerScriptEntrypoint(entrypointPath: string): Promise<string>;
+    registerDevTransformContributor(contributor: DevTransformBundleContributor): void;
+    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.
      */
@@ -289,18 +291,30 @@ 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;
     /**
      * Gets the map of watched files.
      */
     getWatchedFiles(): Map<string, string>;
     /**
-     * Gets the HMR dist directory.
+     * Gets registered dev-transform entrypoints keyed by resolved source path.
+     */
+    getRegisteredEntrypoints(): ReadonlyMap<string, ResolvedHmrEntrypoint>;
+    /**
+     * Gets the on-disk work directory for the bundled HMR client runtime.
      */
-    getDistDir(): string;
+    getRuntimeWorkDir(): 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.
      */
@@ -308,7 +322,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.
@@ -323,44 +337,43 @@ 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 bound component identity.
+     */
+    components?: EcoDeclaredComponent[];
 };
+/**
+ * Component returned from `eco.component()`, `eco.layout()`, or `eco.html()`.
+ *
+ * @remarks
+ * Used for `dependencies.components` and eco factory return types. Bound
+ * component identity 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.
  */
 export type EcoPagesConfig = Omit<Partial<EcoPagesAppConfig>, 'baseUrl' | 'derivedPaths' | 'templatesExt' | 'integrationsDependencies'> & Pick<EcoPagesAppConfig, 'baseUrl' | 'rootDir'>;
-/**
- * Internal metadata injected by eco-component-meta-plugin.
- * Contains component file path and integration info for dependency resolution.
- * @internal
- */
-export interface EcoInjectedMeta {
-    /** Hashed identifier for client-side use (doesn't expose file paths) */
-    id: string;
-    /** Full file path of the component (use path.dirname() to get directory) */
-    file: string;
-    /** The integration identifier (e.g., 'react', 'kitajs', 'lit', 'ghtml', 'mdx') */
-    integration: string;
-}
 export type EcoComponentConfig = {
-    /** @internal Injected by eco-component-meta-plugin */
-    __eco?: EcoInjectedMeta;
+    /** Canonical integration, module, and stable component attribution. */
+    identity?: ComponentIdentity;
     /**
      * Explicit integration override for this component.
      * When provided, this takes precedence over auto-detected integration metadata.
@@ -390,11 +403,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.
@@ -485,6 +500,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.
  */
@@ -494,6 +524,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.
@@ -517,7 +589,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.
  *
@@ -534,12 +645,27 @@ 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 Semantic error templates receive safe empty `pageLocals` rather than
+ * request-scoped locals. The runtime does not currently pass `message` / `stack`
+ * 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. Semantic error templates receive safe empty
+ * `pageLocals` rather than request-scoped locals.
+ */
+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.
@@ -663,6 +789,20 @@ export type RouteRendererOptions = {
     params?: PageParams;
     query?: PageQuery;
     locals?: RequestLocals;
+    /**
+     * Preloaded page module from request-time inspection.
+     *
+     * @remarks
+     * When present, render preparation reuses this module instead of importing the
+     * page file again for the same request.
+     */
+    pageModule?: EcoPageFile;
+    /**
+     * 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.
@@ -675,6 +815,8 @@ export type RouteRenderResult = {
     body: RouteRendererBody;
     /** Cache strategy from page component's eco.page({ cache }) option */
     cacheStrategy?: CacheStrategy;
+    /** Source paths observed during render preparation for HTML cache invalidation. */
+    sourceDependencyPaths?: readonly string[];
 };
 /**
  * Represents the dependencies required for an integration plugin.
@@ -735,15 +877,19 @@ export type IntegrationRendererRenderOptions<C = EcoPagesElement> = RouteRendere
     metadata: PageMetadataProps;
     HtmlTemplate: EcoHtmlComponent<C>;
     Page: EcoComponent<PageProps, C>;
+    Layouts?: EcoDeclaredComponent[];
     Layout?: EcoPageLayoutComponent<any>;
+    layoutEntries?: EcoPageLayoutEntry[];
     dependencies?: EcoComponentDependencies;
+    /** @internal Resolved page dependencies carried through the render pipeline. */
+    resolvedPageDependencyComponents?: ReadonlyArray<EcoComponent | Partial<EcoComponent>>;
     resolvedDependencies: ProcessedAsset[];
     pagePackage?: PagePackageResult;
-    componentRender?: ComponentRenderResult;
     pageProps?: Record<string, unknown>;
     cacheStrategy?: CacheStrategy;
     pageLocals?: RequestLocals;
-    ownershipPlan?: OwnershipPlan;
+    /** @internal Source paths from render preparation for HTML cache dependency registration. */
+    sourceDependencyPaths?: readonly string[];
 };
 /**
  * Structured page asset package produced after dependency resolution.
@@ -808,10 +954,16 @@ export interface PageBrowserGraphResult {
 export type PageBrowserGraphContributionContext = {
     file: string;
     pageModule: EcoPageFile;
+    props?: Record<string, unknown>;
+    params?: PageParams;
+    query?: PageQuery;
+    dependencyInstanceKey?: string;
 };
 export interface PageBrowserGraphContribution {
     dependencies?: AssetDefinition[];
     assets?: ProcessedAsset[];
+    /** Source files that should invalidate this graph entry when they change. */
+    watchPaths?: string[];
 }
 export type OwnershipValidationErrorCode = 'UNKNOWN_INTEGRATION_OWNER' | 'MISSING_COMPONENT_METADATA';
 export interface OwnershipValidationError {
@@ -822,27 +974,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';
 } | {
@@ -866,6 +997,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/types/public-types.js

@@ -0,0 +1 @@
+export {};