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

package/src/eco/eco.browser.js

@@ -1,87 +1,74 @@
-import { applyPageLayoutConfig, mergeLayoutDependencies, normalizePageLayouts } from "./page-layout-normalization.js";
+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 = {
+        __eco: options.__eco,
+        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 layoutEntries = normalizePageLayouts(pageLayout);
-  const pageComponent = createComponentFactory({
-    __eco: options.__eco,
-    integration: options.integration,
-    dependencies: mergeLayoutDependencies(dependencies, layoutEntries),
-    render
-  });
-  if (pageComponent.config) {
-    applyPageLayoutConfig(pageComponent.config, layoutEntries);
-  }
-  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, render, staticPaths, staticProps, metadata, cache, requires, middleware, } = options;
+    const layoutEntries = normalizePageLayouts(pageLayout);
+    const pageComponent = createComponentFactory({
+        __eco: options.__eco,
+        integration: options.integration,
+        dependencies: mergeLayoutDependencies(dependencies, layoutEntries),
+        render,
+    });
+    if (pageComponent.config) {
+        applyPageLayoutConfig(pageComponent.config, layoutEntries);
+    }
+    if (staticPaths) {
+        pageComponent.staticPaths = staticPaths;
+    }
+    if (staticProps) {
+        pageComponent.staticProps = staticProps;
+    }
+    if (metadata) {
+        pageComponent.metadata = metadata;
+    }
+    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,118 +1,178 @@
-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";
+/**
+ * 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';
+/**
+ * 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.__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;
+                }
+                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.__eco?.file ?? 'unknown component'}.`);
+        }
+        return renderInline();
+    });
+    comp.config = {
+        __eco: options.__eco,
+        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 ?? ecoComponent.config?.__eco?.integration;
+    const componentFile = ecoComponent.config?.__eco?.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 layoutEntries = normalizePageLayouts(layout2);
-  const componentOptions = {
-    __eco: options.__eco,
-    integration: options.integration,
-    dependencies: mergeLayoutDependencies(dependencies, layoutEntries),
-    render
-  };
-  const pageComponent = createComponentFactory(componentOptions);
-  if (pageComponent.config) {
-    applyPageLayoutConfig(pageComponent.config, layoutEntries);
-  }
-  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, render, staticPaths, staticProps, metadata, cache, requires, middleware } = options;
+    const layoutEntries = normalizePageLayouts(layout);
+    const componentOptions = {
+        __eco: options.__eco,
+        integration: options.integration,
+        dependencies: mergeLayoutDependencies(dependencies, layoutEntries),
+        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 (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.js

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

package/src/eco/eco.utils.js

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

package/src/eco/global-injector-map.js

@@ -1,44 +1,62 @@
+/**
+ * Converts a flat list of resolved triggers into the map structure consumed
+ * by the `initGlobalInjector` bootstrap. Multiple triggers sharing the same
+ * `triggerId` are merged so their script lists are deduplicated.
+ */
 function buildGlobalInjectorMap(triggers) {
-  const map = {};
-  for (const { triggerId, rules } of triggers) {
-    const entry = map[triggerId] ?? {};
-    for (const rule of rules) {
-      if ("on:idle" in rule) {
-        const { scripts } = rule["on:idle"];
-        entry["on:idle"] = {
-          scripts: Array.from(/* @__PURE__ */ new Set([...entry["on:idle"]?.scripts ?? [], ...scripts]))
-        };
-        continue;
-      }
-      if ("on:interaction" in rule) {
-        const { value, scripts } = rule["on:interaction"];
-        entry["on:interaction"] = {
-          value,
-          scripts: Array.from(/* @__PURE__ */ new Set([...entry["on:interaction"]?.scripts ?? [], ...scripts]))
-        };
-        continue;
-      }
-      if ("on:visible" in rule) {
-        const { value, scripts } = rule["on:visible"];
-        entry["on:visible"] = {
-          ...value ? { value } : {},
-          scripts: Array.from(/* @__PURE__ */ new Set([...entry["on:visible"]?.scripts ?? [], ...scripts]))
-        };
-        continue;
-      }
+    const map = {};
+    for (const { triggerId, rules } of triggers) {
+        const entry = map[triggerId] ?? {};
+        for (const rule of rules) {
+            if ('on:idle' in rule) {
+                const { scripts } = rule['on:idle'];
+                entry['on:idle'] = {
+                    scripts: Array.from(new Set([...(entry['on:idle']?.scripts ?? []), ...scripts])),
+                };
+                continue;
+            }
+            if ('on:interaction' in rule) {
+                const { value, scripts } = rule['on:interaction'];
+                entry['on:interaction'] = {
+                    value,
+                    scripts: Array.from(new Set([...(entry['on:interaction']?.scripts ?? []), ...scripts])),
+                };
+                continue;
+            }
+            if ('on:visible' in rule) {
+                const { value, scripts } = rule['on:visible'];
+                entry['on:visible'] = {
+                    ...(value ? { value } : {}),
+                    scripts: Array.from(new Set([...(entry['on:visible']?.scripts ?? []), ...scripts])),
+                };
+                continue;
+            }
+        }
+        if (Object.keys(entry).length > 0) {
+            map[triggerId] = entry;
+        }
     }
-    if (Object.keys(entry).length > 0) {
-      map[triggerId] = entry;
-    }
-  }
-  return map;
+    return map;
 }
-function buildGlobalInjectorMapScript(triggers) {
-  const map = buildGlobalInjectorMap(triggers);
-  return JSON.stringify(map).replace(/<\/script/gi, "<\\/script");
+/**
+ * Serializes resolved lazy triggers into a JSON string safe for embedding
+ * inside an inline `<script type="ecopages/global-injector-map">` tag.
+ *
+ * The `</script` sequence is escaped because an unescaped occurrence in inline
+ * script content causes the HTML parser to close the script tag prematurely,
+ * breaking page rendering. `JSON.stringify` does not perform this escape by
+ * default, so a targeted replacement is applied after serialization.
+ */
+export function buildGlobalInjectorMapScript(triggers) {
+    const map = buildGlobalInjectorMap(triggers);
+    return JSON.stringify(map).replace(/<\/script/gi, '<\\/script');
 }
-function buildGlobalInjectorBootstrapContent(globalInjectorModuleSpecifier) {
-  return `import { initGlobalInjector } from ${JSON.stringify(globalInjectorModuleSpecifier)};
+/**
+ * Builds the module source that boots the global lazy injector on the client.
+ * Emitted once per page alongside the `ecopages/global-injector-map` script block.
+ */
+export function buildGlobalInjectorBootstrapContent(globalInjectorModuleSpecifier) {
+    return `import { initGlobalInjector } from ${JSON.stringify(globalInjectorModuleSpecifier)};
 
 function pruneStaleTriggerMaps() {
 	const mapScripts = Array.from(document.querySelectorAll('script[type="ecopages/global-injector-map"]'));
@@ -74,7 +92,3 @@ globalScope.__ecoGlobalInjectorCleanup = () => {
 	injector.cleanup();
 };`;
 }
-export {
-  buildGlobalInjectorBootstrapContent,
-  buildGlobalInjectorMapScript
-};