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

package/src/eco/eco.browser.js

@@ -1,88 +1,81 @@
+import { applyPageLayoutConfig, mergeLayoutDependencies, normalizePageLayouts } from './page-layout-normalization.js';
 function createComponentFactory(options) {
-  const component2 = ((props) => options.render(props));
-  component2.config = {
-    __eco: options.__eco,
-    integration: options.integration,
-    dependencies: options.dependencies
-  };
-  return component2;
+    const component = ((props) => options.render(props));
+    component.config = {
+        identity: options.identity,
+        integration: options.integration,
+        dependencies: options.dependencies,
+    };
+    return component;
 }
 function component(options) {
-  return createComponentFactory(options);
+    return createComponentFactory(options);
 }
-function embed(component2, props, children) {
-  const nextProps = children === void 0 ? props : { ...props, children };
-  return component2(nextProps);
+function embed(component, props, children) {
+    const nextProps = (children === undefined ? props : { ...props, children });
+    return component(nextProps);
 }
 function html(options) {
-  return createComponentFactory(options);
+    return createComponentFactory(options);
 }
 function layout(options) {
-  return createComponentFactory(options);
+    return createComponentFactory(options);
 }
 function page(options) {
-  const {
-    layout: pageLayout,
-    dependencies,
-    render,
-    staticPaths: staticPaths2,
-    staticProps: staticProps2,
-    metadata: metadata2,
-    cache,
-    requires,
-    middleware
-  } = options;
-  const pageComponent = createComponentFactory({
-    __eco: options.__eco,
-    integration: options.integration,
-    dependencies: pageLayout ? {
-      ...dependencies,
-      components: [...dependencies?.components ?? [], pageLayout]
-    } : dependencies,
-    render
-  });
-  if (pageLayout && pageComponent.config) {
-    pageComponent.config.layout = pageLayout;
-  }
-  if (staticPaths2) {
-    pageComponent.staticPaths = staticPaths2;
-  }
-  if (staticProps2) {
-    pageComponent.staticProps = staticProps2;
-  }
-  if (metadata2) {
-    pageComponent.metadata = metadata2;
-  }
-  if (cache) {
-    pageComponent.cache = cache;
-  }
-  if (requires) {
-    pageComponent.requires = requires;
-  }
-  if (middleware) {
-    pageComponent.middleware = middleware;
-  }
-  return pageComponent;
+    const { layout: pageLayout, dependencies: dependenciesInput, render, staticPaths, staticProps, metadata, cache, requires, middleware, } = options;
+    const layoutEntries = normalizePageLayouts(pageLayout);
+    const resolveDependencies = typeof dependenciesInput === 'function' ? dependenciesInput : undefined;
+    const staticDependencies = typeof dependenciesInput === 'function'
+        ? mergeLayoutDependencies(undefined, layoutEntries)
+        : mergeLayoutDependencies(dependenciesInput, layoutEntries);
+    const pageComponent = createComponentFactory({
+        identity: options.identity,
+        integration: options.integration,
+        dependencies: staticDependencies,
+        render,
+    });
+    if (pageComponent.config) {
+        applyPageLayoutConfig(pageComponent.config, layoutEntries);
+    }
+    if (staticPaths) {
+        pageComponent.staticPaths = staticPaths;
+    }
+    if (staticProps) {
+        pageComponent.staticProps = staticProps;
+    }
+    if (metadata) {
+        pageComponent.metadata = metadata;
+    }
+    if (resolveDependencies) {
+        pageComponent.resolveDependencies = resolveDependencies;
+    }
+    if (cache) {
+        pageComponent.cache = cache;
+    }
+    if (requires) {
+        pageComponent.requires = requires;
+    }
+    if (middleware) {
+        pageComponent.middleware = middleware;
+    }
+    return pageComponent;
 }
 function metadata(fn) {
-  return fn;
+    return fn;
 }
 function staticPaths(fn) {
-  return fn;
+    return fn;
 }
 function staticProps(fn) {
-  return fn;
+    return fn;
 }
-const eco = {
-  component,
-  embed,
-  html,
-  layout,
-  page,
-  metadata,
-  staticPaths,
-  staticProps
-};
-export {
-  eco
+export const eco = {
+    component,
+    embed,
+    html,
+    layout,
+    page,
+    metadata,
+    staticPaths,
+    staticProps,
 };

package/src/eco/eco.js

@@ -1,119 +1,185 @@
-import {
-  finalizeComponentRender,
-  getComponentRenderContext,
-  interceptForeignChild
-} from "../route-renderer/orchestration/component-render-context.js";
-import { isThenable } from "../route-renderer/orchestration/render-output.utils.js";
+/**
+ * The eco namespace - unified component and page factory API
+ * @module
+ */
+import { finalizeComponentRender, getComponentRenderContext, interceptForeignChild, } from '../route-renderer/orchestration/foreign-child/component-render-context.js';
+import { isThenable } from '../route-renderer/orchestration/foreign-child/foreign-child-output.utils.js';
+import { applyPageLayoutConfig, mergeLayoutDependencies, normalizePageLayouts } from './page-layout-normalization.js';
+import { getComponentIdentity } from './component-identity.js';
+/**
+ * Creates a component factory with lazy-trigger support and foreign-child-runtime
+ * interception.
+ *
+ * Behavior:
+ * - In normal render flow, returns `options.render(props)` with optional lazy
+ *   trigger/script wrapping.
+ * - When rendering under an active foreign-child runtime and the current
+ *   renderer-owned foreign-child runtime resolves the foreign child immediately, returns
+ *   that resolved output instead of rendering the component inline.
+ *
+ * @param options Component options for rendering and dependency declaration.
+ * @returns Configured eco component.
+ */
 function createComponentFactory(options) {
-  const integrationName = options.integration ?? options.__eco?.integration;
-  const comp = ((props) => {
-    const componentProps = props ?? {};
-    const renderInline = (nextProps = props) => finalizeComponentRender(comp, options.render(nextProps));
-    const activeRenderContext = getComponentRenderContext();
-    const foreignChildRender = interceptForeignChild({
-      component: comp,
-      props: componentProps,
-      targetIntegration: integrationName
-    });
-    if (isThenable(foreignChildRender)) {
-      return foreignChildRender.then((resolvedForeignChildRender) => {
-        if (resolvedForeignChildRender?.kind === "resolved") {
-          return resolvedForeignChildRender.value;
+    const integrationName = options.integration ?? options.identity?.integration;
+    const comp = ((props) => {
+        const componentProps = (props ?? {});
+        const renderInline = (nextProps = props) => finalizeComponentRender(comp, options.render(nextProps));
+        const activeRenderContext = getComponentRenderContext();
+        const foreignChildRender = interceptForeignChild({
+            component: comp,
+            props: componentProps,
+            targetIntegration: integrationName,
+        });
+        if (isThenable(foreignChildRender)) {
+            return foreignChildRender.then((resolvedForeignChildRender) => {
+                if (resolvedForeignChildRender?.kind === 'resolved') {
+                    return resolvedForeignChildRender.value;
+                }
+                return renderInline((resolvedForeignChildRender?.props ?? props));
+            });
         }
-        return renderInline(resolvedForeignChildRender?.props ?? props);
-      });
-    }
-    if (foreignChildRender?.kind === "resolved") {
-      return foreignChildRender.value;
-    }
-    if (foreignChildRender?.kind === "inline") {
-      return renderInline(foreignChildRender.props ?? props);
-    }
-    if (activeRenderContext && activeRenderContext.foreignChildRuntime && integrationName && integrationName !== activeRenderContext.currentIntegration) {
-      throw new Error(
-        `[ecopages] Missing foreign-child interception from ${activeRenderContext.currentIntegration} to ${integrationName} for ${options.__eco?.file ?? "unknown component"}.`
-      );
-    }
-    return renderInline();
-  });
-  comp.config = {
-    __eco: options.__eco,
-    integration: options.integration,
-    dependencies: options.dependencies
-  };
-  return comp;
+        if (foreignChildRender?.kind === 'resolved') {
+            return foreignChildRender.value;
+        }
+        if (foreignChildRender?.kind === 'inline') {
+            return renderInline((foreignChildRender.props ?? props));
+        }
+        if (activeRenderContext &&
+            activeRenderContext.foreignChildRuntime &&
+            integrationName &&
+            integrationName !== activeRenderContext.currentIntegration) {
+            throw new Error(`[ecopages] Missing foreign-child interception from ${activeRenderContext.currentIntegration} to ${integrationName} for ${options.identity?.file ?? 'unknown component'}.`);
+        }
+        return renderInline();
+    });
+    comp.config = {
+        identity: options.identity,
+        integration: options.integration,
+        dependencies: options.dependencies,
+    };
+    return comp;
 }
+/**
+ * Creates a reusable component with optional dependencies.
+ *
+ * @param options Component definition options.
+ * @returns Eco component function.
+ */
 function component(options) {
-  return createComponentFactory(options);
+    return createComponentFactory(options);
 }
 function isMissingForeignChildInterceptionError(error) {
-  return error instanceof Error && error.message.startsWith("[ecopages] Missing foreign-child interception from ");
+    return error instanceof Error && error.message.startsWith('[ecopages] Missing foreign-child interception from ');
 }
-function embed(component2, props, children) {
-  const activeRenderContext = getComponentRenderContext();
-  const ecoComponent = component2;
-  const targetIntegration = ecoComponent.config?.integration ?? ecoComponent.config?.__eco?.integration;
-  const componentFile = ecoComponent.config?.__eco?.file ?? "unknown component";
-  const nextProps = children === void 0 ? props : { ...props, children };
-  try {
-    return component2(nextProps);
-  } catch (error) {
-    if (!isMissingForeignChildInterceptionError(error)) {
-      throw error;
+/**
+ * Renders a component explicitly and optionally injects `children` into the
+ * props bag before invocation.
+ */
+function embed(component, props, children) {
+    const activeRenderContext = getComponentRenderContext();
+    const ecoComponent = component;
+    const targetIntegration = ecoComponent.config?.integration ?? getComponentIdentity(ecoComponent)?.integration;
+    const componentFile = getComponentIdentity(ecoComponent)?.file ?? 'unknown component';
+    const nextProps = (children === undefined ? props : { ...props, children });
+    try {
+        return component(nextProps);
+    }
+    catch (error) {
+        if (!isMissingForeignChildInterceptionError(error)) {
+            throw error;
+        }
+        throw new Error(`[ecopages] eco.embed() could not hand off the Foreign Child from ${activeRenderContext?.currentIntegration ?? 'unknown integration'} to ${targetIntegration ?? 'unknown integration'} for ${componentFile}. The active Integration renderer exposed a foreign-child runtime, but it did not intercept this cross-integration render. Ensure mixed-integration Page, Layout, Html, or Component renders install foreign-child handoff before calling eco.embed().`);
     }
-    throw new Error(
-      `[ecopages] eco.embed() could not hand off the Foreign Child from ${activeRenderContext?.currentIntegration ?? "unknown integration"} to ${targetIntegration ?? "unknown integration"} for ${componentFile}. The active Integration renderer exposed a foreign-child runtime, but it did not intercept this cross-integration render. Ensure mixed-integration Page, Layout, Html, or Component renders install foreign-child handoff before calling eco.embed().`
-    );
-  }
 }
+/**
+ * Creates a document shell component.
+ */
 function html(options) {
-  return createComponentFactory(options);
+    return createComponentFactory(options);
 }
+/**
+ * Creates a route layout component.
+ */
 function layout(options) {
-  return createComponentFactory(options);
+    return createComponentFactory(options);
 }
+/**
+ * Creates a page component and attaches optional static APIs.
+ *
+ * @param options Page options.
+ * @returns Eco page component.
+ */
 function page(options) {
-  const { layout: layout2, dependencies, render, staticPaths: staticPaths2, staticProps: staticProps2, metadata: metadata2, cache, requires, middleware } = options;
-  const componentOptions = {
-    __eco: options.__eco,
-    integration: options.integration,
-    dependencies: layout2 ? {
-      ...dependencies,
-      components: [...dependencies?.components || [], layout2]
-    } : dependencies,
-    render
-  };
-  const pageComponent = createComponentFactory(componentOptions);
-  if (layout2 && pageComponent.config) {
-    pageComponent.config.layout = layout2;
-  }
-  if (staticPaths2) pageComponent.staticPaths = staticPaths2;
-  if (staticProps2) pageComponent.staticProps = staticProps2;
-  if (metadata2) pageComponent.metadata = metadata2;
-  if (cache) pageComponent.cache = cache;
-  if (requires) pageComponent.requires = requires;
-  if (middleware) pageComponent.middleware = middleware;
-  return pageComponent;
+    const { layout, dependencies: dependenciesInput, render, staticPaths, staticProps, metadata, cache, requires, middleware, } = options;
+    const layoutEntries = normalizePageLayouts(layout);
+    const resolveDependencies = typeof dependenciesInput === 'function' ? dependenciesInput : undefined;
+    const staticDependencies = typeof dependenciesInput === 'function'
+        ? mergeLayoutDependencies(undefined, layoutEntries)
+        : mergeLayoutDependencies(dependenciesInput, layoutEntries);
+    const componentOptions = {
+        identity: options.identity,
+        integration: options.integration,
+        dependencies: staticDependencies,
+        render,
+    };
+    const pageComponent = createComponentFactory(componentOptions);
+    if (pageComponent.config) {
+        applyPageLayoutConfig(pageComponent.config, layoutEntries);
+    }
+    if (staticPaths)
+        pageComponent.staticPaths = staticPaths;
+    if (staticProps)
+        pageComponent.staticProps = staticProps;
+    if (metadata)
+        pageComponent.metadata = metadata;
+    if (resolveDependencies)
+        pageComponent.resolveDependencies = resolveDependencies;
+    if (cache)
+        pageComponent.cache = cache;
+    if (requires)
+        pageComponent.requires = requires;
+    if (middleware)
+        pageComponent.middleware = middleware;
+    return pageComponent;
 }
+/**
+ * Type-safe wrapper for metadata functions.
+ *
+ * @param fn Metadata factory function.
+ * @returns The same function.
+ */
 function metadata(fn) {
-  return fn;
+    return fn;
 }
+/**
+ * Type-safe wrapper for static paths functions.
+ *
+ * @param fn Static paths function.
+ * @returns The same function.
+ */
 function staticPaths(fn) {
-  return fn;
+    return fn;
 }
+/**
+ * Type-safe wrapper for static props functions.
+ *
+ * @param fn Static props function.
+ * @returns The same function.
+ */
 function staticProps(fn) {
-  return fn;
+    return fn;
 }
-const eco = {
-  component,
-  embed,
-  html,
-  layout,
-  page,
-  metadata,
-  staticPaths,
-  staticProps
-};
-export {
-  eco
+/**
+ * The eco namespace - provides factories for components and pages
+ */
+export const eco = {
+    component,
+    embed,
+    html,
+    layout,
+    page,
+    metadata,
+    staticPaths,
+    staticProps,
 };

package/src/eco/eco.types.d.ts

@@ -2,8 +2,9 @@
  * Type definitions for the eco namespace API
  * @module
  */
-import type { DependencyLazyTrigger, EcoComponent, EcoComponentDependencies, EcoHtmlComponent, EcoInjectedMeta, EcoLayoutComponent, EcoPageLayoutComponent, EcoPagesElement, FileRouteMiddleware, GetMetadata, GetStaticPaths, GetStaticProps, HtmlTemplateProps, LayoutProps, RequestLocals, RequestPageContext } from '../types/public-types.js';
+import type { DependencyLazyTrigger, EcoComponent, EcoComponentDependencies, EcoHtmlComponent, EcoLayoutComponent, EcoPageLayouts, EcoPagesElement, FileRouteMiddleware, GetMetadata, GetStaticPaths, GetStaticProps, HtmlTemplateProps, LayoutProps, RequestLocals, RequestPageContext, PageParams, PageQuery } from '../types/public-types.js';
 import type { CacheStrategy } from '../services/cache/cache.types.js';
+import type { ComponentIdentity } from './component-identity.js';
 /**
  * Extracts the props type from one eco component.
  */
@@ -54,6 +55,28 @@ type WithRequiredLocals<K extends keyof RequestLocals> = Omit<RequestLocals, K>
 };
 type RequiresKeys = keyof RequestLocals;
 export type PageRequires<K extends RequiresKeys = RequiresKeys> = K | readonly K[];
+/**
+ * Context passed to a page `dependencies` resolver for one concrete route render.
+ */
+export type GetPageDependenciesContext<T = Record<string, unknown>> = {
+    props: PagePropsFor<T>;
+    params?: PageParams;
+    query?: PageQuery;
+};
+/**
+ * Page dependency bag optionally scoped to a declaring file.
+ */
+export type PageDependenciesResult = EcoComponentDependencies & {
+    ownerFile?: string;
+};
+/**
+ * Resolves request-specific page dependencies for one route render.
+ */
+export type GetPageDependencies<T = Record<string, unknown>> = (context: GetPageDependenciesContext<T>) => PageDependenciesResult | undefined | Promise<PageDependenciesResult | undefined>;
+/**
+ * Static page dependencies or a per-render resolver.
+ */
+export type PageDependenciesInput<T = Record<string, unknown>> = EcoComponentDependencies | GetPageDependencies<T>;
 /**
  * Lazy trigger options map directly to scripts-injector attributes.
  * Only one trigger type can be active at a time.
@@ -65,23 +88,38 @@ export type LazyTrigger = DependencyLazyTrigger;
  * @template E - The element/return type (defaults to EcoPagesElement for Kita, use ReactNode for React)
  */
 export interface ComponentOptions<P, E = EcoPagesElement> {
-    /** @internal Injected by eco-component-meta-plugin */
-    __eco?: EcoInjectedMeta;
+    /** @internal Bound by the component identity attribution transform. */
+    identity?: ComponentIdentity;
     integration?: string;
     dependencies?: EcoComponentDependencies;
     render: (props: P) => E | Promise<E>;
 }
 export type HtmlOptions<E = EcoPagesElement> = ComponentOptions<HtmlTemplateProps, E>;
-export type LayoutOptions<E = EcoPagesElement> = ComponentOptions<LayoutProps<E>, E>;
+export type LayoutOptions<E = EcoPagesElement> = ComponentOptions<LayoutProps<E>, E> & {
+    /**
+     * Marks this layout as mounting shared client runtime state such as React context
+     * providers or query clients.
+     *
+     * @remarks
+     * When any layout in the app sets this flag, only flagged layouts participate in
+     * React auto-vendoring discovery. This keeps shell-only layouts out of provider
+     * scans while persisted SPA navigation stays on one shared vendor instance.
+     */
+    runtimeProvider?: boolean;
+};
 /**
  * Base options shared by all page variants
  */
 export interface PageOptionsBase<T, E = EcoPagesElement> {
-    /** @internal Injected by eco-component-meta-plugin */
-    __eco?: EcoInjectedMeta;
+    /** @internal Bound by the component identity attribution transform. */
+    identity?: ComponentIdentity;
     integration?: string;
-    dependencies?: EcoComponentDependencies;
-    layout?: EcoPageLayoutComponent<E>;
+    /**
+     * Declares browser dependencies for the page, or resolves them per render after
+     * `staticProps` are available.
+     */
+    dependencies?: PageDependenciesInput<T>;
+    layout?: EcoPageLayouts<E>;
     /**
      * Define static paths for dynamic routes (e.g., [slug].tsx).
      * Returns all possible paths that should be pre-rendered at build time.
@@ -167,6 +205,7 @@ export type EcoPageComponent<T> = EcoComponent<PagePropsFor<T> & Partial<Request
     staticPaths?: GetStaticPaths;
     staticProps?: GetStaticProps<T>;
     metadata?: GetMetadata<T>;
+    resolveDependencies?: GetPageDependencies<T>;
     cache?: CacheStrategy;
     requires?: PageRequires;
     middleware?: FileRouteMiddleware[];

package/src/eco/eco.types.js

@@ -0,0 +1,5 @@
+/**
+ * Type definitions for the eco namespace API
+ * @module
+ */
+export {};

package/src/eco/eco.utils.d.ts

@@ -1 +1 @@
-export { addTriggerAttribute, isThenable, wrapWithScriptsInjector, } from '../route-renderer/orchestration/render-output.utils.js';
+export { addTriggerAttribute, isThenable, wrapWithScriptsInjector, } from '../route-renderer/orchestration/foreign-child/foreign-child-output.utils.js';

package/src/eco/eco.utils.js

@@ -1,10 +1 @@
-import {
-  addTriggerAttribute,
-  isThenable,
-  wrapWithScriptsInjector
-} from "../route-renderer/orchestration/render-output.utils.js";
-export {
-  addTriggerAttribute,
-  isThenable,
-  wrapWithScriptsInjector
-};
+export { addTriggerAttribute, isThenable, wrapWithScriptsInjector, } from '../route-renderer/orchestration/foreign-child/foreign-child-output.utils.js';