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

package/src/route-renderer/orchestration/document-shell/document-shell-render.service.js

@@ -0,0 +1,155 @@
+import { HtmlTransformerService, } from '../../../services/html/html-transformer.service.js';
+function resolveDocumentShellLayouts(input) {
+    if (input.layouts && input.layouts.length > 0) {
+        return input.layouts;
+    }
+    return input.layout ? [input.layout] : [];
+}
+function resolveComponentIntegrationName(component) {
+    return component.config?.integration ?? component.config?.identity?.integration ?? 'ecopages';
+}
+/**
+ * Default sequential string-child composition for document shell layers.
+ */
+export async function composeSequentialLayoutChildren(context) {
+    if (!context.primaryRender) {
+        throw new Error('[ecopages] composeSequentialLayoutChildren requires primaryRender.');
+    }
+    let children = context.primaryRender.html;
+    const layoutRenders = [];
+    for (const layout of [...context.layouts].reverse()) {
+        const layoutRender = await context.renderComponentWithForeignChildren({
+            component: layout.component,
+            props: layout.props ?? {},
+            children,
+            integrationContext: { rendererCache: context.rendererCache },
+        });
+        layoutRenders.push(layoutRender);
+        children = layoutRender.html;
+    }
+    return {
+        children,
+        layoutRenders,
+    };
+}
+/**
+ * Composes page or view content through optional layout and document shells.
+ *
+ * One execution-scoped renderer cache is threaded through every shell layer so
+ * repeated foreign delegation reuses initialized renderers within one render pass.
+ */
+export async function composeDocumentShell(dependencies, input) {
+    const rendererCache = new Map();
+    const layouts = resolveDocumentShellLayouts(input);
+    const composeChildren = input.composeChildren ?? composeSequentialLayoutChildren;
+    const usesCustomComposeChildren = input.composeChildren !== undefined;
+    let primaryRender;
+    let children;
+    let layoutRenders;
+    if (usesCustomComposeChildren) {
+        const composed = await composeChildren({
+            primaryComponent: input.primaryComponent,
+            primaryProps: input.primaryProps,
+            layouts,
+            rendererCache,
+            renderComponentWithForeignChildren: dependencies.renderComponentWithForeignChildren,
+        });
+        children = composed.children;
+        layoutRenders = composed.layoutRenders;
+        primaryRender = composed.primaryRender ?? {
+            html: typeof composed.children === 'string' ? composed.children : '',
+            assets: [],
+            canAttachAttributes: true,
+            rootTag: 'main',
+            integrationName: resolveComponentIntegrationName(input.primaryComponent),
+        };
+    }
+    else {
+        primaryRender = await dependencies.renderComponentWithForeignChildren({
+            component: input.primaryComponent,
+            props: input.primaryProps,
+            integrationContext: { rendererCache },
+        });
+        const composed = await composeChildren({
+            primaryComponent: input.primaryComponent,
+            primaryProps: input.primaryProps,
+            primaryRender,
+            layouts,
+            rendererCache,
+            renderComponentWithForeignChildren: dependencies.renderComponentWithForeignChildren,
+        });
+        children = composed.children;
+        layoutRenders = composed.layoutRenders;
+    }
+    const documentRender = await dependencies.renderComponentWithForeignChildren({
+        component: input.htmlTemplate,
+        props: input.documentProps,
+        children,
+        integrationContext: { rendererCache },
+    });
+    dependencies.appendProcessedDependencies(primaryRender.assets, ...layoutRenders.map((layoutRender) => layoutRender.assets), documentRender.assets);
+    return {
+        documentHtml: documentRender.html,
+    };
+}
+/**
+ * Applies optional component-root and document-root attribute stamping before HTML
+ * transformation runs on explicit renderer-owned paths.
+ */
+export function applyDocumentShellAttributeStamping(html, stamping, options) {
+    let nextHtml = html;
+    if (options.componentRootAttributes && Object.keys(options.componentRootAttributes).length > 0) {
+        nextHtml = stamping.applyAttributesToFirstBodyElement(nextHtml, options.componentRootAttributes);
+    }
+    if (options.documentAttributes && Object.keys(options.documentAttributes).length > 0) {
+        nextHtml = stamping.applyAttributesToHtmlElement(nextHtml, options.documentAttributes);
+    }
+    return nextHtml;
+}
+/**
+ * Builds the final serialized document HTML for one route page render.
+ */
+export async function renderPageDocumentShell(dependencies, input, docType) {
+    const { documentHtml: composedDocumentHtml } = await composeDocumentShell(dependencies, {
+        primaryComponent: input.page.component,
+        primaryProps: input.page.props,
+        layout: input.layout,
+        layouts: input.layouts,
+        composeChildren: input.composeChildren,
+        htmlTemplate: input.htmlTemplate,
+        documentProps: {
+            metadata: input.metadata,
+            pageProps: input.pageProps,
+            ...(input.documentProps ?? {}),
+        },
+    });
+    const documentHtml = input.transformDocumentHtml
+        ? input.transformDocumentHtml(composedDocumentHtml)
+        : composedDocumentHtml;
+    return `${docType}${documentHtml}`;
+}
+/**
+ * Finalizes already-resolved HTML for explicit renderer-owned paths.
+ *
+ * @remarks
+ * Callers append renderer bootstrap dependencies before invoking this helper.
+ * Stamps document/root attributes and runs HTML transformation after nested
+ * foreign-subtree resolution without routing back through shared route execution.
+ */
+export async function finalizeDocumentShellHtml(htmlTransformer, options) {
+    const html = applyDocumentShellAttributeStamping(options.html, {
+        applyAttributesToFirstBodyElement: (nextHtml, attributes) => htmlTransformer.applyAttributesToFirstBodyElement(nextHtml, attributes),
+        applyAttributesToHtmlElement: (nextHtml, attributes) => htmlTransformer.applyAttributesToHtmlElement(nextHtml, attributes),
+    }, {
+        componentRootAttributes: options.componentRootAttributes,
+        documentAttributes: options.documentAttributes,
+    });
+    const shouldTransform = options.transformHtml ?? !options.partial;
+    if (!shouldTransform) {
+        return html;
+    }
+    const transformedResponse = await htmlTransformer.transform(new Response(html, {
+        headers: { 'Content-Type': 'text/html' },
+    }), options.htmlContributions);
+    return await transformedResponse.text();
+}

package/src/route-renderer/orchestration/document-shell/layout-shell-props.service.d.ts

@@ -0,0 +1,32 @@
+import type { EcoComponent, EcoPageLayoutEntry, LayoutPropsContext } from '../../../types/public-types.js';
+import type { DocumentShellLayoutInput } from './document-shell-render.service.js';
+export type LayoutShellPropsContext = LayoutPropsContext & {
+    pageProps?: Record<string, unknown>;
+};
+export type DocumentShellLayoutResolutionInput = LayoutShellPropsContext & {
+    layout?: EcoComponent;
+    layoutEntries?: EcoPageLayoutEntry[];
+};
+/**
+ * Resolves the default shell props passed to a layout tier during route render.
+ */
+export declare function resolveLayoutShellProps(context: LayoutShellPropsContext): Record<string, unknown>;
+/**
+ * Resolves props for one layout entry, merging shell props with an optional factory.
+ */
+export declare function resolveLayoutEntryProps(entry: EcoPageLayoutEntry, context: LayoutShellPropsContext): Record<string, unknown>;
+/**
+ * Resolves declarative layout entries into the document-shell inputs used during route render.
+ *
+ * @remarks Layout prop factories must be evaluated here so integrations do not
+ * silently fall back to the innermost layout and discard route-specific props.
+ */
+export declare function resolveDocumentShellLayouts(input: DocumentShellLayoutResolutionInput): DocumentShellLayoutInput[];
+/**
+ * Reads the normalized layout stack from a page component config.
+ */
+export declare function resolvePageLayoutComponents(layouts?: EcoPageLayoutEntry['component'][]): EcoPageLayoutEntry['component'][];
+/**
+ * Returns the innermost layout component from a normalized page layout stack.
+ */
+export declare function resolveInnermostPageLayout(layouts?: EcoPageLayoutEntry['component'][]): EcoPageLayoutEntry['component'] | undefined;

package/src/route-renderer/orchestration/document-shell/layout-shell-props.service.js

@@ -0,0 +1,52 @@
+/**
+ * Resolves the default shell props passed to a layout tier during route render.
+ */
+export function resolveLayoutShellProps(context) {
+    return context.locals ? { locals: context.locals } : {};
+}
+/**
+ * Resolves props for one layout entry, merging shell props with an optional factory.
+ */
+export function resolveLayoutEntryProps(entry, context) {
+    const shellProps = resolveLayoutShellProps(context);
+    if (!entry.props) {
+        return shellProps;
+    }
+    const layoutPropsContext = {
+        params: context.params,
+        query: context.query,
+        locals: context.locals,
+    };
+    return {
+        ...shellProps,
+        ...entry.props(layoutPropsContext),
+    };
+}
+/**
+ * Resolves declarative layout entries into the document-shell inputs used during route render.
+ *
+ * @remarks Layout prop factories must be evaluated here so integrations do not
+ * silently fall back to the innermost layout and discard route-specific props.
+ */
+export function resolveDocumentShellLayouts(input) {
+    if (input.layoutEntries && input.layoutEntries.length > 0) {
+        return input.layoutEntries.map((entry) => ({
+            component: entry.component,
+            props: resolveLayoutEntryProps(entry, input),
+        }));
+    }
+    return input.layout ? [{ component: input.layout, props: resolveLayoutShellProps(input) }] : [];
+}
+/**
+ * Reads the normalized layout stack from a page component config.
+ */
+export function resolvePageLayoutComponents(layouts) {
+    return layouts && layouts.length > 0 ? layouts : [];
+}
+/**
+ * Returns the innermost layout component from a normalized page layout stack.
+ */
+export function resolveInnermostPageLayout(layouts) {
+    const stack = resolvePageLayoutComponents(layouts);
+    return stack[stack.length - 1];
+}

package/src/route-renderer/orchestration/{component-render-context.d.ts → foreign-child/component-render-context.d.ts}

@@ -1,24 +1,17 @@
-import type { EcoComponent } from '../../types/public-types.js';
+import type { EcoComponent } from '../../../types/public-types.js';
 /**
  * Result returned by a renderer-owned foreign-child runtime.
  *
- * `inline` keeps rendering inside the current integration. `resolved` returns a
- * renderer-owned value immediately, which can be final HTML or a renderer-local
- * transport token for later queue resolution.
+ * `inline` keeps rendering inside the current integration. `resolved.value` is
+ * the queue transport token string allocated by `createQueuedRuntime`; callers
+ * must not treat arbitrary objects as resolved output.
  */
 export type ForeignChildInterceptionResult = {
     kind: 'inline';
     props?: Record<string, unknown>;
 } | {
     kind: 'resolved';
-    value: unknown;
-};
-export type ForeignChildRenderInterception = {
-    kind: 'inline';
-    props?: Record<string, unknown>;
-} | {
-    kind: 'resolved';
-    value: unknown;
+    value: string;
 } | undefined;
 /**
  * Foreign-child metadata passed into the active renderer-owned runtime.
@@ -44,7 +37,7 @@ export interface ForeignChildRuntime {
      * which decides whether the child stays inline or leaves the current renderer.
      */
     interceptForeignChild?(input: ForeignChildInterceptionInput): ForeignChildInterceptionResult | Promise<ForeignChildInterceptionResult>;
-    interceptForeignChildSync?(input: ForeignChildInterceptionInput): ForeignChildInterceptionResult;
+    interceptForeignChildSync?(input: ForeignChildInterceptionInput): Exclude<ForeignChildInterceptionResult, undefined>;
 }
 type ForeignChildRenderInput = {
     component: EcoComponent;
@@ -58,7 +51,7 @@ type ForeignChildRenderInput = {
 export type ComponentRenderContext = {
     currentIntegration: string;
     foreignChildRuntime?: ForeignChildRuntime;
-    interceptForeignChild(input: ForeignChildRenderInput): Promise<ForeignChildRenderInterception> | ForeignChildRenderInterception;
+    interceptForeignChild(input: ForeignChildRenderInput): Promise<ForeignChildInterceptionResult> | ForeignChildInterceptionResult;
     finalizeComponentRender<T>(component: EcoComponent, content: T): T;
 };
 /**
@@ -72,7 +65,7 @@ export declare function getComponentRenderContext(): ComponentRenderContext | un
  *
  * The active runtime may resolve the foreign child immediately or keep it inline.
  */
-export declare function interceptForeignChild(input: ForeignChildRenderInput): Promise<ForeignChildRenderInterception> | ForeignChildRenderInterception;
+export declare function interceptForeignChild(input: ForeignChildRenderInput): Promise<ForeignChildInterceptionResult> | ForeignChildInterceptionResult;
 /**
  * Applies lazy trigger or injector wrapping to completed component output.
  *

package/src/route-renderer/orchestration/foreign-child/component-render-context.js

@@ -0,0 +1,196 @@
+import { addTriggerAttribute, isThenable, wrapWithScriptsInjector } from './foreign-child-output.utils.js';
+/**
+ * Shared output finalization behavior used both inside and outside active render contexts.
+ *
+ * This stage is responsible only for lazy trigger or injector wrapping. Foreign-child
+ * interception stays in `ContextualComponentRenderRuntime`.
+ */
+class ComponentRenderOutputRuntime {
+    finalizeComponentRender(component, content) {
+        const lazyTriggers = component.config?._resolvedLazyTriggers;
+        if (lazyTriggers && lazyTriggers.length > 0) {
+            return this.addTriggerToContent(content, lazyTriggers[0].triggerId);
+        }
+        const lazyGroups = component.config?._resolvedLazyScripts;
+        if (lazyGroups && lazyGroups.length > 0) {
+            return this.wrapContentWithScriptsInjector(content, lazyGroups);
+        }
+        return content;
+    }
+    addTriggerToContent(content, triggerId) {
+        if (isThenable(content)) {
+            return content.then((resolvedContent) => addTriggerAttribute(resolvedContent, triggerId));
+        }
+        return addTriggerAttribute(content, triggerId);
+    }
+    wrapContentWithScriptsInjector(content, lazyGroups) {
+        if (isThenable(content)) {
+            return content.then((resolvedContent) => wrapWithScriptsInjector(resolvedContent, lazyGroups));
+        }
+        return wrapWithScriptsInjector(content, lazyGroups);
+    }
+}
+/**
+ * Render-context-aware runtime that delegates foreign-child interception.
+ */
+class ContextualComponentRenderRuntime extends ComponentRenderOutputRuntime {
+    context;
+    constructor(context) {
+        super();
+        this.context = context;
+    }
+    applyForeignChildInterceptionResult(result) {
+        if (result.kind === 'resolved') {
+            return result;
+        }
+        return result.props ? result : undefined;
+    }
+    /**
+     * Resolves one foreign-child interception through the active runtime.
+     *
+     * The runtime may choose inline rendering or immediate resolved output.
+     */
+    interceptForeignChild(input) {
+        const foreignChildRuntimeInput = {
+            currentIntegration: this.context.currentIntegration,
+            targetIntegration: input.targetIntegration,
+            component: input.component,
+            props: input.props,
+        };
+        const asyncInterception = this.context.foreignChildRuntime?.interceptForeignChild?.(foreignChildRuntimeInput);
+        if (asyncInterception !== undefined) {
+            if (isThenable(asyncInterception)) {
+                return asyncInterception.then((result) => result === undefined ? undefined : this.applyForeignChildInterceptionResult(result));
+            }
+            return this.applyForeignChildInterceptionResult(asyncInterception);
+        }
+        const syncInterception = this.context.foreignChildRuntime?.interceptForeignChildSync?.(foreignChildRuntimeInput);
+        if (syncInterception === undefined) {
+            return undefined;
+        }
+        return this.applyForeignChildInterceptionResult(syncInterception);
+    }
+}
+const GLOBAL_COMPONENT_RENDER_CONTEXT_STATE_KEY = '__ECOPAGES_COMPONENT_RENDER_CONTEXT_STATE__';
+/**
+ * Chooses the widest shared global scope available for process-wide state.
+ *
+ * `process` is preferred when present so duplicate bundles or module instances in
+ * the same runtime still converge on one shared context registry.
+ */
+function getSharedContextScope() {
+    const globalProcess = globalThis.process;
+    if (globalProcess && typeof globalProcess === 'object') {
+        return globalProcess;
+    }
+    return globalThis;
+}
+/**
+ * Returns the singleton mutable state used by component render contexts.
+ */
+function getComponentRenderContextState() {
+    const sharedScope = getSharedContextScope();
+    sharedScope[GLOBAL_COMPONENT_RENDER_CONTEXT_STATE_KEY] ??= {
+        contextStack: [],
+        nodeContextStorage: null,
+        nodeContextStorageLoader: null,
+    };
+    return sharedScope[GLOBAL_COMPONENT_RENDER_CONTEXT_STATE_KEY];
+}
+/**
+ * Lazily initializes async context storage for Node runtimes.
+ *
+ * Falls back to in-memory stack mode when async_hooks is unavailable.
+ *
+ * @returns Async context storage when available; otherwise `null`.
+ */
+async function getContextStorage() {
+    const state = getComponentRenderContextState();
+    if (state.nodeContextStorage) {
+        return state.nodeContextStorage;
+    }
+    if (state.nodeContextStorageLoader) {
+        return state.nodeContextStorageLoader;
+    }
+    state.nodeContextStorageLoader = import('node:async_hooks')
+        .then((module) => {
+        const storage = new module.AsyncLocalStorage();
+        state.nodeContextStorage = {
+            getStore: () => storage.getStore(),
+            run: (store, callback) => storage.run(store, callback),
+        };
+        return state.nodeContextStorage;
+    })
+        .catch(() => {
+        state.nodeContextStorage = null;
+        return null;
+    })
+        .finally(() => {
+        state.nodeContextStorageLoader = null;
+    });
+    return state.nodeContextStorageLoader;
+}
+/**
+ * Returns the current component render context, if one is active.
+ *
+ * @returns Active render context or `undefined` outside render execution.
+ */
+export function getComponentRenderContext() {
+    const state = getComponentRenderContextState();
+    return state.nodeContextStorage?.getStore() ?? state.contextStack[state.contextStack.length - 1];
+}
+const componentRenderOutputRuntime = new ComponentRenderOutputRuntime();
+/**
+ * Runs foreign-child interception for one component render step.
+ *
+ * The active runtime may resolve the foreign child immediately or keep it inline.
+ */
+export function interceptForeignChild(input) {
+    return getComponentRenderContext()?.interceptForeignChild(input);
+}
+/**
+ * Applies lazy trigger or injector wrapping to completed component output.
+ *
+ * This helper works both inside render-context execution and in fallback flows
+ * where no active context exists.
+ */
+export function finalizeComponentRender(component, content) {
+    const renderContext = getComponentRenderContext();
+    return (renderContext?.finalizeComponentRender(component, content) ??
+        componentRenderOutputRuntime.finalizeComponentRender(component, content));
+}
+/**
+ * Runs render work under a fresh component render context and returns the
+ * resulting value.
+ *
+ * @param input Execution metadata for current integration and foreign-child policy.
+ * @param render Async render function to execute inside the context.
+ * @returns Render result value.
+ */
+export async function runWithComponentRenderContext(input, render) {
+    const context = {
+        currentIntegration: input.currentIntegration,
+        foreignChildRuntime: input.foreignChildRuntime,
+    };
+    const runtime = new ContextualComponentRenderRuntime(context);
+    context.interceptForeignChild = (deferredInput) => runtime.interceptForeignChild(deferredInput);
+    context.finalizeComponentRender = (component, content) => runtime.finalizeComponentRender(component, content);
+    const storage = await getContextStorage();
+    let value;
+    if (storage) {
+        value = await storage.run(context, render);
+    }
+    else {
+        const state = getComponentRenderContextState();
+        state.contextStack.push(context);
+        try {
+            value = await render();
+        }
+        finally {
+            state.contextStack.pop();
+        }
+    }
+    return {
+        value,
+    };
+}

package/src/route-renderer/orchestration/{render-output.utils.d.ts → foreign-child/foreign-child-output.utils.d.ts}

@@ -1,4 +1,4 @@
-import type { EcoComponent } from '../../types/public-types.js';
+import type { EcoComponent } from '../../../types/public-types.js';
 type ResolvedLazyScriptGroups = Readonly<NonNullable<EcoComponent['config']>['_resolvedLazyScripts']>;
 type TemplateContentShape = {
     strings: readonly string[];
@@ -23,6 +23,20 @@ type MarkupNodeLikeShape = {
 export declare function isThenable<T>(value: unknown): value is PromiseLike<T>;
 /** Returns whether a value looks like a DOM-like markup node from SSR integrations. */
 export declare function isMarkupNodeLike(value: unknown): value is MarkupNodeLikeShape;
+/**
+ * Returns whether a value is a plain opaque object that string serializers would
+ * coerce via `String(value)` rather than render as markup.
+ *
+ * @remarks
+ * Template results (`strings`/`values`), markup nodes, arrays, and framework
+ * element markers (`$$typeof`) are not opaque. Cross-integration children that
+ * are only plain objects must use EcoEmbed or already-serialized HTML.
+ */
+export declare function isOpaqueForeignChildValue(children: unknown): boolean;
+/**
+ * Throws when foreign-path children would be coerced from an opaque object.
+ */
+export declare function assertForeignChildrenNotOpaque(children: unknown, context: string): void;
 /**
  * Injects `data-eco-trigger` into the first real HTML element opening tag of
  * a component's rendered output string.
@@ -41,6 +55,11 @@ export declare function isMarkupNodeLike(value: unknown): value is MarkupNodeLik
  * When no eligible opening tag is found the original string is returned
  * unchanged so callers never receive a broken fragment.
  *
+ * @remarks
+ * `@ecopages/jsx` beta.8+ keeps attribute names in `parts`, so template
+ * `strings[0]` is often just the opening tag name (`<html`) with no trailing
+ * delimiter. In that shape the attribute is appended at the end of that string.
+ *
  * @param content Rendered HTML string (or any value coercible to string).
  * @param triggerId Stable trigger identifier produced by `buildResolvedLazyTriggers`.
  */
@@ -59,10 +78,4 @@ export declare function wrapWithScriptsInjector(content: string, lazyGroups: Res
 export declare function wrapWithScriptsInjector<T extends TemplateContentShape>(content: T, lazyGroups: ResolvedLazyScriptGroups): T | string;
 export declare function wrapWithScriptsInjector<T extends MarkupNodeLikeShape>(content: T, lazyGroups: ResolvedLazyScriptGroups): T;
 export declare function wrapWithScriptsInjector(content: unknown, lazyGroups: ResolvedLazyScriptGroups): string | TemplateContentShape | MarkupNodeLikeShape;
-export declare function decodeHtmlEntities(value: string): string;
-export declare function normalizeUnresolvedMarkerArtifactHtml(html: string): string;
-export declare function inspectUnresolvedMarkerArtifactHtml(html: string): {
-    hasUnresolvedMarkerArtifacts: boolean;
-    normalizedHtml: string;
-};
 export {};