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

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

@@ -1,21 +1,96 @@
 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';
-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;
@@ -88,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.
      */
@@ -117,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.
      */
@@ -154,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.
@@ -167,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.
      */
@@ -213,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.
      */
-    getDistDir(): string;
+    getRegisteredEntrypoints(): ReadonlyMap<string, ResolvedHmrEntrypoint>;
     /**
-     * Gets the build plugins.
+     * Gets the on-disk work directory for the bundled HMR client runtime.
      */
-    getPlugins(): EcoBuildPlugin[];
+    getRuntimeWorkDir(): string;
+    /**
+     * Returns the on-disk path to the bundled HMR runtime script.
+     */
+    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 +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.
@@ -247,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.
@@ -314,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.
@@ -409,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.
  */
@@ -418,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.
@@ -441,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.
  *
@@ -458,12 +645,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 +787,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.
@@ -599,6 +813,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.
@@ -659,15 +875,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.
@@ -732,10 +952,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 {
@@ -746,27 +972,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 +995,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 {};

package/src/utils/deep-merge.js

@@ -1,32 +1,45 @@
+/**
+ * This module contains a simple utility function to merge two objects deeply
+ * @module
+ */
 function isObject(item) {
-  return item && typeof item === "object" && !Array.isArray(item);
+    return item && typeof item === 'object' && !Array.isArray(item);
 }
 function isArray(item) {
-  return Array.isArray(item);
+    return Array.isArray(item);
 }
-function deepMerge(target, source) {
-  if (isArray(target) && isArray(source)) {
-    return [...target, ...source];
-  }
-  if (!isObject(target) || !isObject(source)) {
-    return source;
-  }
-  const output = Object.assign({}, target);
-  for (const key in source) {
-    if (isObject(source[key])) {
-      if (!target[key]) {
-        Object.assign(output, { [key]: source[key] });
-      } else {
-        output[key] = deepMerge(target[key], source[key]);
-      }
-    } else if (isArray(source[key])) {
-      output[key] = [...target[key] || [], ...source[key]];
-    } else if (source[key] !== void 0) {
-      Object.assign(output, { [key]: source[key] });
+/**
+ * Deeply merges two objects or arrays
+ * @function deepMerge
+ * @template T - Type of target object
+ * @template U - Type of source object
+ * @param target - The target object to merge into
+ * @param source - The source object to merge from
+ * @returns A new object with merged properties
+ */
+export function deepMerge(target, source) {
+    if (isArray(target) && isArray(source)) {
+        return [...target, ...source];
     }
-  }
-  return output;
+    if (!isObject(target) || !isObject(source)) {
+        return source;
+    }
+    const output = Object.assign({}, target);
+    for (const key in source) {
+        if (isObject(source[key])) {
+            if (!target[key]) {
+                Object.assign(output, { [key]: source[key] });
+            }
+            else {
+                output[key] = deepMerge(target[key], source[key]);
+            }
+        }
+        else if (isArray(source[key])) {
+            output[key] = [...(target[key] || []), ...source[key]];
+        }
+        else if (source[key] !== undefined) {
+            Object.assign(output, { [key]: source[key] });
+        }
+    }
+    return output;
 }
-export {
-  deepMerge
-};