@ecopages/core 0.2.0-alpha.27 → 0.2.0-alpha.28

package/src/route-renderer/orchestration/ownership-planning.service.d.ts

@@ -0,0 +1,24 @@
+import type { OwnershipPlan, OwnershipValidationError, EcoComponent } from '../../types/public-types.js';
+type OwnershipPlanBuildInput = {
+    routeFile: string;
+    currentIntegrationName: string;
+    HtmlTemplate: EcoComponent;
+    Layout?: EcoComponent;
+    Page: EcoComponent;
+    validationErrors?: OwnershipValidationError[];
+};
+/**
+ * Builds a declared ownership plan from the component dependency graph.
+ *
+ * The plan reflects the declared component dependency graph for one route after
+ * route-root ownership validation has already run. It records ownership shape,
+ * foreign-edge counts, and any validation errors supplied by an earlier
+ * validation pass.
+ */
+export declare class OwnershipPlanningService {
+    /**
+     * Builds the structural ownership plan for one route render.
+     */
+    buildPlan(input: OwnershipPlanBuildInput): OwnershipPlan;
+}
+export {};

package/src/route-renderer/orchestration/ownership-planning.service.js

@@ -0,0 +1,63 @@
+import { mapDeclaredOwnershipGraph } from "./declared-ownership-graph.js";
+class OwnershipPlanningService {
+  /**
+   * Builds the structural ownership plan for one route render.
+   */
+  buildPlan(input) {
+    const validationErrors = input.validationErrors ?? [];
+    const rendererNames = /* @__PURE__ */ new Set([input.currentIntegrationName]);
+    let foreignEdgeCount = 0;
+    const roots = [
+      { component: input.HtmlTemplate, source: "html-template" },
+      ...input.Layout ? [{ component: input.Layout, source: "layout" }] : [],
+      { component: input.Page, source: "page" }
+    ];
+    const children = mapDeclaredOwnershipGraph({
+      roots,
+      currentIntegrationName: input.currentIntegrationName,
+      mapNode: ({ component, source, integrationName, componentId, isForeignToParent }, children2) => {
+        const componentMeta = component.config?.__eco;
+        rendererNames.add(integrationName);
+        if (isForeignToParent) {
+          foreignEdgeCount += 1;
+        }
+        return {
+          id: componentId,
+          source,
+          ownership: {
+            integrationName,
+            componentId,
+            componentFile: componentMeta?.file,
+            isPageEntry: source === "page",
+            isForeignToParent
+          },
+          children: children2,
+          declaredDependenciesValid: true
+        };
+      }
+    });
+    const root = {
+      id: `route:${input.routeFile}`,
+      source: "route",
+      ownership: {
+        integrationName: input.currentIntegrationName,
+        componentId: `route:${input.routeFile}`,
+        componentFile: input.routeFile,
+        isPageEntry: false,
+        isForeignToParent: false
+      },
+      children,
+      declaredDependenciesValid: validationErrors.length === 0
+    };
+    return {
+      root,
+      rendererNames: Array.from(rendererNames),
+      foreignEdgeCount,
+      hasValidationErrors: validationErrors.length > 0,
+      validationErrors
+    };
+  }
+}
+export {
+  OwnershipPlanningService
+};

package/src/route-renderer/orchestration/ownership-validation.service.d.ts

@@ -0,0 +1,29 @@
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+import type { OwnershipPlanNodeSource, OwnershipValidationError, EcoComponent } from '../../types/public-types.js';
+type OwnershipValidationInput = {
+    currentIntegrationName: string;
+    roots: Array<{
+        component: EcoComponent;
+        source: Extract<OwnershipPlanNodeSource, 'page' | 'layout' | 'html-template'>;
+    }>;
+};
+/**
+ * Validates foreign ownership as soon as the route root graph is loaded.
+ *
+ * This check runs before route data and dependency preparation so ownership and
+ * metadata problems are surfaced from the loaded component graph itself rather
+ * than being entangled with ownership-plan construction.
+ */
+export declare class OwnershipValidationService {
+    private readonly appConfig;
+    /**
+     * Creates the ownership validator for one finalized app config.
+     */
+    constructor(appConfig: EcoPagesAppConfig);
+    /**
+     * Validates foreign ownership edges reachable from the supplied route roots.
+     */
+    validate(input: OwnershipValidationInput): OwnershipValidationError[];
+    private isRegisteredIntegration;
+}
+export {};

package/src/route-renderer/orchestration/ownership-validation.service.js

@@ -0,0 +1,53 @@
+import { mapDeclaredOwnershipGraph } from "./declared-ownership-graph.js";
+class OwnershipValidationService {
+  appConfig;
+  /**
+   * Creates the ownership validator for one finalized app config.
+   */
+  constructor(appConfig) {
+    this.appConfig = appConfig;
+  }
+  /**
+   * Validates foreign ownership edges reachable from the supplied route roots.
+   */
+  validate(input) {
+    return mapDeclaredOwnershipGraph({
+      roots: input.roots,
+      currentIntegrationName: input.currentIntegrationName,
+      mapNode: ({ component, integrationName, componentId, isForeignToParent }, children) => {
+        const componentMeta = component.config?.__eco;
+        const errors = children.flat();
+        if (!isForeignToParent) {
+          return errors;
+        }
+        if (!componentMeta) {
+          errors.push({
+            code: "MISSING_COMPONENT_METADATA",
+            message: `[ecopages] Foreign child "${componentId}" must provide stable __eco metadata so ownership diagnostics stay actionable. Declared dependencies must include all possible foreign children.`,
+            componentId,
+            integrationName
+          });
+        }
+        if (!this.isRegisteredIntegration(integrationName, input.currentIntegrationName)) {
+          errors.push({
+            code: "UNKNOWN_INTEGRATION_OWNER",
+            message: `[ecopages] Foreign child "${componentId}" references unknown integration owner "${integrationName}". Declared dependencies must include all possible foreign children and those integrations must be registered.`,
+            componentId,
+            componentFile: componentMeta?.file,
+            integrationName
+          });
+        }
+        return errors;
+      }
+    }).flat();
+  }
+  isRegisteredIntegration(integrationName, currentIntegrationName) {
+    if (integrationName === currentIntegrationName) {
+      return true;
+    }
+    return this.appConfig.integrations.some((integration) => integration.name === integrationName);
+  }
+}
+export {
+  OwnershipValidationService
+};

package/src/route-renderer/orchestration/processed-asset-dedupe.d.ts

@@ -0,0 +1,2 @@
+import type { ProcessedAsset } from '../../services/assets/asset-processing-service/index.js';
+export declare function dedupeProcessedAssets(assets: ProcessedAsset[]): ProcessedAsset[];

package/src/route-renderer/orchestration/processed-asset-dedupe.js

@@ -0,0 +1,23 @@
+function dedupeProcessedAssets(assets) {
+  const unique = /* @__PURE__ */ new Map();
+  for (const asset of assets) {
+    const key = [
+      asset.kind,
+      asset.position ?? "",
+      asset.srcUrl ?? "",
+      asset.filepath ?? "",
+      asset.content ?? "",
+      asset.inline ? "inline" : "external",
+      asset.excludeFromHtml ? "excluded" : "included",
+      asset.packageRole ?? "",
+      JSON.stringify(asset.attributes ?? {})
+    ].join("|");
+    if (!unique.has(key)) {
+      unique.set(key, asset);
+    }
+  }
+  return [...unique.values()];
+}
+export {
+  dedupeProcessedAssets
+};

package/src/route-renderer/orchestration/queued-foreign-subtree-resolution.service.d.ts

@@ -0,0 +1,90 @@
+import type { ProcessedAsset } from '../../services/assets/asset-processing-service/index.js';
+import type { BaseIntegrationContext, ForeignSubtreeRenderPayload, ComponentRenderInput, EcoComponent } from '../../types/public-types.js';
+import type { ForeignChildRuntime } from './component-render-context.js';
+export type QueuedForeignChildDecisionInput = {
+    currentIntegration: string;
+    targetIntegration?: string;
+    component: EcoComponent;
+    props: Record<string, unknown>;
+};
+export type QueuedForeignSubtreeResolution = {
+    token: string;
+    component: EcoComponent;
+    props: Record<string, unknown>;
+    componentInstanceId: string;
+};
+/**
+ * Shared mutable state for one renderer-owned queued foreign-subtree runtime.
+ *
+ * Renderers that cannot resolve foreign children inline can enqueue transport
+ * tokens during their initial render, then resolve those tokens against the
+ * owning renderer before returning final HTML.
+ */
+export type QueuedForeignSubtreeResolutionContext = {
+    rendererCache: Map<string, unknown>;
+    componentInstanceScope?: string;
+    nextForeignSubtreeId: number;
+    queuedResolutions: QueuedForeignSubtreeResolution[];
+};
+type QueuedForeignSubtreeIntegrationContext = BaseIntegrationContext & Record<string, unknown>;
+type QueuedForeignSubtreeChildRenderResult = {
+    assets: ProcessedAsset[];
+    html?: string;
+};
+/**
+ * Lower-level queue orchestration for renderer-owned foreign-child runtimes that emit
+ * temporary transport tokens during one render pass.
+ *
+ * The service keeps three responsibilities in one place:
+ * - storing per-render queue state on the active integration context
+ * - creating a `ForeignChildRuntime` that enqueues foreign children
+ * - resolving queued tokens back through the owning renderer before final HTML
+ *   leaves the current renderer
+ *
+ * The deeper Foreign Subtree execution module composes this queue helper with
+ * renderer-cache delegation and active render-context execution. This service
+ * stays focused on queue bookkeeping, recursion, cycle detection, and asset merging.
+ */
+export declare class QueuedForeignSubtreeResolutionService {
+    /**
+     * Reads the queued foreign-subtree runtime state previously attached to one render.
+     */
+    getRuntimeContext<TContext extends QueuedForeignSubtreeResolutionContext>(input: ComponentRenderInput, runtimeContextKey: string): TContext | undefined;
+    /**
+     * Creates the runtime hook used by `runWithComponentRenderContext()` for one
+     * renderer-owned queue.
+     *
+     * When the renderer decides a foreign child must be handed off, the runtime returns
+     * a resolved transport token instead of rendering the foreign component inline.
+     */
+    createRuntime<TContext extends QueuedForeignSubtreeResolutionContext>(options: {
+        renderInput: ComponentRenderInput;
+        rendererCache: Map<string, unknown>;
+        runtimeContextKey: string;
+        tokenPrefix: string;
+        shouldQueueForeignChild: (input: QueuedForeignChildDecisionInput) => boolean;
+        createRuntimeContext?: (integrationContext: QueuedForeignSubtreeIntegrationContext, rendererCache: Map<string, unknown>) => TContext;
+    }): ForeignChildRuntime;
+    /**
+     * Resolves every queued transport token in one renderer-owned HTML fragment.
+     *
+     * The caller supplies framework-specific child rendering, while this service
+     * handles recursive token replacement, cycle detection, root-attribute
+     * application, and merged asset collection.
+     */
+    resolveQueuedHtml<TContext extends QueuedForeignSubtreeResolutionContext>(options: {
+        html: string;
+        runtimeContext?: TContext;
+        queueLabel: string;
+        renderQueuedChildren: (children: unknown, runtimeContext: TContext, queuedResolutionsByToken: Map<string, QueuedForeignSubtreeResolution>, resolveToken: (token: string) => Promise<string>) => Promise<QueuedForeignSubtreeChildRenderResult>;
+        resolveForeignSubtree: (input: ComponentRenderInput, rendererCache: Map<string, unknown>) => Promise<ForeignSubtreeRenderPayload | undefined>;
+        applyAttributesToFirstElement: (html: string, attributes: Record<string, string>) => string;
+        dedupeProcessedAssets: (assets: ProcessedAsset[]) => ProcessedAsset[];
+    }): Promise<{
+        assets: ProcessedAsset[];
+        html: string;
+    }>;
+    private createForeignSubtreeToken;
+    private ensureRuntimeContext;
+}
+export {};

package/src/route-renderer/orchestration/queued-foreign-subtree-resolution.service.js

@@ -0,0 +1,158 @@
+class QueuedForeignSubtreeResolutionService {
+  /**
+   * Reads the queued foreign-subtree runtime state previously attached to one render.
+   */
+  getRuntimeContext(input, runtimeContextKey) {
+    const integrationContext = input.integrationContext;
+    const runtimeContext = integrationContext?.[runtimeContextKey];
+    if (typeof runtimeContext !== "object" || runtimeContext === null) {
+      return void 0;
+    }
+    return runtimeContext;
+  }
+  /**
+   * Creates the runtime hook used by `runWithComponentRenderContext()` for one
+   * renderer-owned queue.
+   *
+   * When the renderer decides a foreign child must be handed off, the runtime returns
+   * a resolved transport token instead of rendering the foreign component inline.
+   */
+  createRuntime(options) {
+    const runtimeContext = this.ensureRuntimeContext(options);
+    const interceptForeignChild = (input) => {
+      if (!options.shouldQueueForeignChild(input)) {
+        return { kind: "inline" };
+      }
+      runtimeContext.nextForeignSubtreeId += 1;
+      const foreignSubtreeId = runtimeContext.nextForeignSubtreeId;
+      const token = this.createForeignSubtreeToken(options.tokenPrefix, runtimeContext, foreignSubtreeId);
+      runtimeContext.queuedResolutions.push({
+        token,
+        component: input.component,
+        props: { ...input.props },
+        componentInstanceId: runtimeContext.componentInstanceScope ? `${runtimeContext.componentInstanceScope}_n_${foreignSubtreeId}` : `n_${foreignSubtreeId}`
+      });
+      return {
+        kind: "resolved",
+        value: token
+      };
+    };
+    return {
+      interceptForeignChild,
+      interceptForeignChildSync: interceptForeignChild
+    };
+  }
+  /**
+   * Resolves every queued transport token in one renderer-owned HTML fragment.
+   *
+   * The caller supplies framework-specific child rendering, while this service
+   * handles recursive token replacement, cycle detection, root-attribute
+   * application, and merged asset collection.
+   */
+  async resolveQueuedHtml(options) {
+    if (!options.runtimeContext || options.runtimeContext.queuedResolutions.length === 0) {
+      return { assets: [], html: options.html };
+    }
+    const runtimeContext = options.runtimeContext;
+    const queuedResolutionsByToken = new Map(
+      runtimeContext.queuedResolutions.map((resolution) => [resolution.token, resolution])
+    );
+    const resolvedHtmlByToken = /* @__PURE__ */ new Map();
+    const resolvingTokens = /* @__PURE__ */ new Set();
+    const collectedAssets = [];
+    const resolveToken = async (token) => {
+      const cachedHtml = resolvedHtmlByToken.get(token);
+      if (cachedHtml) {
+        return cachedHtml;
+      }
+      const resolution = queuedResolutionsByToken.get(token);
+      if (!resolution) {
+        return token;
+      }
+      if (resolvingTokens.has(token)) {
+        throw new Error(
+          `[ecopages] ${options.queueLabel} foreign-subtree queue contains a cycle or unresolved dependency links.`
+        );
+      }
+      resolvingTokens.add(token);
+      try {
+        const renderedChildren = await options.renderQueuedChildren(
+          resolution.props.children,
+          runtimeContext,
+          queuedResolutionsByToken,
+          resolveToken
+        );
+        if (renderedChildren.assets.length > 0) {
+          collectedAssets.push(...renderedChildren.assets);
+        }
+        const foreignSubtreeRender = await options.resolveForeignSubtree(
+          {
+            component: resolution.component,
+            props: { ...resolution.props },
+            children: renderedChildren.html,
+            integrationContext: {
+              rendererCache: runtimeContext.rendererCache,
+              componentInstanceId: resolution.componentInstanceId
+            }
+          },
+          runtimeContext.rendererCache
+        );
+        if (!foreignSubtreeRender) {
+          throw new Error(
+            `[ecopages] ${options.queueLabel} queued foreign subtree could not resolve its owning renderer.`
+          );
+        }
+        if ((foreignSubtreeRender.assets?.length ?? 0) > 0) {
+          collectedAssets.push(...foreignSubtreeRender.assets ?? []);
+        }
+        const resolvedHtml2 = foreignSubtreeRender.attachmentPolicy.kind === "first-element" && foreignSubtreeRender.rootAttributes ? options.applyAttributesToFirstElement(
+          foreignSubtreeRender.html,
+          foreignSubtreeRender.rootAttributes
+        ) : foreignSubtreeRender.html;
+        resolvedHtmlByToken.set(token, resolvedHtml2);
+        return resolvedHtml2;
+      } finally {
+        resolvingTokens.delete(token);
+      }
+    };
+    let resolvedHtml = options.html;
+    for (const resolution of runtimeContext.queuedResolutions) {
+      if (!resolvedHtml.includes(resolution.token)) {
+        continue;
+      }
+      resolvedHtml = resolvedHtml.split(resolution.token).join(await resolveToken(resolution.token));
+    }
+    return {
+      assets: options.dedupeProcessedAssets(collectedAssets),
+      html: resolvedHtml
+    };
+  }
+  createForeignSubtreeToken(tokenPrefix, runtimeContext, foreignSubtreeId) {
+    return `${tokenPrefix}${runtimeContext.componentInstanceScope ?? "root"}__${foreignSubtreeId}__`;
+  }
+  ensureRuntimeContext(options) {
+    let integrationContext;
+    if (typeof options.renderInput.integrationContext === "object" && options.renderInput.integrationContext !== null) {
+      integrationContext = options.renderInput.integrationContext;
+    } else {
+      integrationContext = {};
+    }
+    const existingRuntimeContext = integrationContext[options.runtimeContextKey];
+    if (typeof existingRuntimeContext !== "object" || existingRuntimeContext === null) {
+      integrationContext[options.runtimeContextKey] = options.createRuntimeContext?.(integrationContext, options.rendererCache) ?? {
+        rendererCache: options.rendererCache,
+        componentInstanceScope: integrationContext.componentInstanceId,
+        nextForeignSubtreeId: 0,
+        queuedResolutions: []
+      };
+    } else {
+      existingRuntimeContext.rendererCache = options.rendererCache;
+    }
+    integrationContext.rendererCache = options.rendererCache;
+    options.renderInput.integrationContext = integrationContext;
+    return integrationContext[options.runtimeContextKey];
+  }
+}
+export {
+  QueuedForeignSubtreeResolutionService
+};

package/src/route-renderer/orchestration/render-output.utils.d.ts

@@ -0,0 +1,66 @@
+import type { EcoComponent } from '../../types/public-types.js';
+type ResolvedLazyScriptGroups = Readonly<NonNullable<EcoComponent['config']>['_resolvedLazyScripts']>;
+type TemplateContentShape = {
+    strings: readonly string[];
+    values?: readonly unknown[];
+    [key: string]: unknown;
+};
+type MarkupNodeLikeShape = {
+    nodeType: number;
+    outerHTML?: string;
+    childNodes?: readonly unknown[];
+    textContent?: string;
+    [key: string]: unknown;
+};
+/**
+ * Returns `true` when `value` is a thenable (Promise-like) object.
+ *
+ * Used to transparently handle both synchronous and asynchronous component
+ * render results without requiring every caller to branch on `instanceof Promise`.
+ *
+ * @typeParam T Expected resolved type of the thenable.
+ */
+export declare function isThenable<T>(value: unknown): value is PromiseLike<T>;
+/**
+ * Injects `data-eco-trigger` into the first real HTML element opening tag of
+ * a component's rendered output string.
+ *
+ * The scan skips over leading whitespace, HTML comments (`<!-- -->`), CDATA
+ * sections, and doctype declarations so that the attribute is always placed on
+ * the first actual element — not spurious markup that can precede it.
+ *
+ * The insertion point is the end of the element's tag name, before any existing
+ * attributes or the closing `>`, which produces output like:
+ *
+ * ```html
+ * <my-element data-eco-trigger="eco-trigger-abc123" class="foo">…</my-element>
+ * ```
+ *
+ * When no eligible opening tag is found the original string is returned
+ * unchanged so callers never receive a broken fragment.
+ *
+ * @param content Rendered HTML string (or any value coercible to string).
+ * @param triggerId Stable trigger identifier produced by `buildResolvedLazyTriggers`.
+ */
+export declare function addTriggerAttribute(content: string, triggerId: string): string;
+export declare function addTriggerAttribute<T extends TemplateContentShape>(content: T, triggerId: string): T;
+export declare function addTriggerAttribute<T extends MarkupNodeLikeShape>(content: T, triggerId: string): T;
+export declare function addTriggerAttribute(content: unknown, triggerId: string): string | TemplateContentShape | MarkupNodeLikeShape;
+/**
+ * Wraps rendered component output in a `<scripts-injector>` element that
+ * carries an inline injector map for the legacy (non-global-injector) path.
+ *
+ * @param content Rendered component HTML.
+ * @param lazyGroups Resolved lazy script groups attached to the component config.
+ */
+export declare function wrapWithScriptsInjector(content: string, lazyGroups: ResolvedLazyScriptGroups): string;
+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 {};