@ecopages/core 0.2.0-alpha.7 → 0.2.0-alpha.9

package/src/route-renderer/component-graph/component-graph-executor.d.ts

@@ -0,0 +1,32 @@
+import type { ComponentMarker } from './component-marker.js';
+import type { ComponentGraph } from './component-graph.js';
+/**
+ * Render result returned by a graph node resolver.
+ *
+ * `html` is inserted in place of the corresponding marker token.
+ */
+export type GraphNodeRenderResult = {
+    html: string;
+};
+/**
+ * Callback used to render one marker node during graph execution.
+ *
+ * Resolver implementations may call integration-specific `renderComponent`
+ * and can use closure state to wire child output into parent render calls.
+ */
+export type GraphNodeResolver = (marker: ComponentMarker) => Promise<GraphNodeRenderResult>;
+/**
+ * Resolves all markers in bottom-up order based on computed graph levels.
+ *
+ * Child nodes are resolved first so parent slot content can consume already
+ * resolved child HTML in subsequent resolver invocations.
+ *
+ * If a node id exists in `graph.levels` but no marker is present in `inputHtml`,
+ * that node is skipped.
+ *
+ * @param inputHtml HTML containing marker tokens.
+ * @param graph Precomputed marker graph with topological levels.
+ * @param resolver Async callback that renders each marker node.
+ * @returns HTML with resolved markers replaced.
+ */
+export declare function resolveComponentGraph(inputHtml: string, graph: ComponentGraph, resolver: GraphNodeResolver): Promise<string>;

package/src/route-renderer/component-graph/component-graph-executor.js

@@ -0,0 +1,31 @@
+import { parseComponentMarkers } from "./component-marker.js";
+function escapeRegex(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function replaceMarkerByNodeId(html, nodeId, replacement) {
+  const pattern = `<eco-marker[^>]*data-eco-node-id="${escapeRegex(nodeId)}"[^>]*><\\/eco-marker>`;
+  const markerRegex = new RegExp(pattern);
+  return html.replace(markerRegex, replacement);
+}
+async function resolveComponentGraph(inputHtml, graph, resolver) {
+  let html = inputHtml;
+  const markersById = /* @__PURE__ */ new Map();
+  for (const marker of parseComponentMarkers(inputHtml)) {
+    markersById.set(marker.nodeId, marker);
+  }
+  const levels = [...graph.levels].reverse();
+  for (const level of levels) {
+    for (const nodeId of level) {
+      const marker = markersById.get(nodeId);
+      if (!marker) {
+        continue;
+      }
+      const result = await resolver(marker);
+      html = replaceMarkerByNodeId(html, nodeId, result.html);
+    }
+  }
+  return html;
+}
+export {
+  resolveComponentGraph
+};

package/src/route-renderer/component-graph/component-graph.d.ts

@@ -0,0 +1,42 @@
+import type { ComponentMarker, MarkerNodeId } from './component-marker.js';
+/**
+ * Maps a parent slot reference to child marker node ids discovered in that slot.
+ *
+ * Keys are `slotRef` values emitted in marker payloads.
+ */
+export type SlotChildrenRegistry = Record<string, MarkerNodeId[]>;
+/**
+ * Graph node enriched with source-order information for deterministic traversal.
+ */
+export type ComponentGraphNode = ComponentMarker & {
+    order: number;
+};
+/**
+ * Directed acyclic graph representation for component marker orchestration.
+ *
+ * `levels` are topological layers from roots to leaves.
+ */
+export type ComponentGraph = {
+    nodes: Map<MarkerNodeId, ComponentGraphNode>;
+    edges: Map<MarkerNodeId, Set<MarkerNodeId>>;
+    reverseEdges: Map<MarkerNodeId, Set<MarkerNodeId>>;
+    levels: MarkerNodeId[][];
+};
+/**
+ * Extracts marker graph metadata from rendered HTML and slot linkage data.
+ *
+ * This is the canonical graph builder used by marker execution.
+ *
+ * Algorithm summary:
+ * 1. Parse markers from HTML in source order.
+ * 2. Create nodes and derive edges from `slotChildrenRegistry`.
+ * 3. Compute deterministic topological levels.
+ *
+ * Unknown child node ids in `slotChildrenRegistry` are ignored to keep the
+ * extractor tolerant to stale references.
+ *
+ * @param html Rendered HTML containing `eco-marker` tokens.
+ * @param slotChildrenRegistry Optional slot -> child linkage map.
+ * @returns Component graph structure with levels ready for execution.
+ */
+export declare function extractComponentGraph(html: string, slotChildrenRegistry?: SlotChildrenRegistry): ComponentGraph;

package/src/route-renderer/component-graph/component-graph.js

@@ -0,0 +1,72 @@
+import { parseComponentMarkers } from "./component-marker.js";
+function ensureEdgeMaps(edges, reverseEdges, from, to) {
+  if (!edges.has(from)) {
+    edges.set(from, /* @__PURE__ */ new Set());
+  }
+  if (!reverseEdges.has(to)) {
+    reverseEdges.set(to, /* @__PURE__ */ new Set());
+  }
+  edges.get(from)?.add(to);
+  reverseEdges.get(to)?.add(from);
+}
+function computeLevels(nodes, edges, reverseEdges) {
+  const indegree = /* @__PURE__ */ new Map();
+  for (const nodeId of nodes.keys()) {
+    indegree.set(nodeId, reverseEdges.get(nodeId)?.size ?? 0);
+  }
+  const levels = [];
+  let frontier = [...nodes.values()].filter((node) => (indegree.get(node.nodeId) ?? 0) === 0).sort((a, b) => a.order - b.order).map((node) => node.nodeId);
+  const visited = /* @__PURE__ */ new Set();
+  while (frontier.length > 0) {
+    levels.push(frontier);
+    const next = [];
+    for (const current of frontier) {
+      visited.add(current);
+      for (const child of edges.get(current) ?? []) {
+        const nextInDegree = (indegree.get(child) ?? 0) - 1;
+        indegree.set(child, nextInDegree);
+        if (nextInDegree === 0) {
+          next.push(child);
+        }
+      }
+    }
+    frontier = next.filter((nodeId, index) => next.indexOf(nodeId) === index).sort((a, b) => {
+      const orderA = nodes.get(a)?.order ?? 0;
+      const orderB = nodes.get(b)?.order ?? 0;
+      return orderA - orderB;
+    });
+  }
+  if (visited.size !== nodes.size) {
+    throw new Error("[ecopages] Component marker graph contains a cycle or unresolved dependency links.");
+  }
+  return levels;
+}
+function extractComponentGraph(html, slotChildrenRegistry = {}) {
+  const markers = parseComponentMarkers(html);
+  const nodes = /* @__PURE__ */ new Map();
+  const edges = /* @__PURE__ */ new Map();
+  const reverseEdges = /* @__PURE__ */ new Map();
+  markers.forEach((marker, index) => {
+    nodes.set(marker.nodeId, {
+      ...marker,
+      order: index
+    });
+  });
+  for (const marker of markers) {
+    if (!marker.slotRef) {
+      continue;
+    }
+    const linkedChildren = slotChildrenRegistry[marker.slotRef] ?? [];
+    for (const childNodeId of linkedChildren) {
+      if (!nodes.has(childNodeId)) {
+        continue;
+      }
+      ensureEdgeMaps(edges, reverseEdges, marker.nodeId, childNodeId);
+    }
+  }
+  const levels = computeLevels(nodes, edges, reverseEdges);
+  return { nodes, edges, reverseEdges, levels };
+}
+export {
+  extractComponentGraph
+};

package/src/route-renderer/component-graph/component-marker.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Stable marker node identifier used during one render graph resolution pass.
+ *
+ * @example
+ * `n_12`
+ */
+export type MarkerNodeId = `n_${string}`;
+/**
+ * Marker payload used by graph extraction and execution.
+ *
+ * Each marker references:
+ * - the owning integration renderer (`integration`)
+ * - a component definition key (`componentRef`)
+ * - a serialized props key (`propsRef`)
+ * - optional child-slot linkage (`slotRef`)
+ */
+export type ComponentMarker = {
+    nodeId: MarkerNodeId;
+    integration: string;
+    componentRef: string;
+    propsRef: string;
+    slotRef?: string;
+};
+/**
+ * Input contract for marker emission.
+ *
+ * This shape is intentionally close to `ComponentMarker` to keep emission and
+ * parsing symmetric.
+ */
+export type MarkerRenderInput = {
+    nodeId: MarkerNodeId;
+    integration: string;
+    componentRef: string;
+    propsRef: string;
+    slotRef?: string;
+};
+/**
+ * Creates the canonical `<eco-marker>` token used for deferred component rendering.
+ *
+ * @param input Marker payload fields.
+ * @returns Serialized marker HTML token.
+ */
+export declare function createComponentMarker(input: MarkerRenderInput): string;
+/**
+ * Parses all valid `<eco-marker>` tokens from HTML output.
+ *
+ * Invalid markers (missing required attributes) are ignored by design.
+ *
+ * @param html Rendered HTML fragment or document.
+ * @returns Parsed marker payloads in source order.
+ */
+export declare function parseComponentMarkers(html: string): ComponentMarker[];

package/src/route-renderer/component-graph/component-marker.js

@@ -0,0 +1,46 @@
+function escapeAttribute(value) {
+  return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function readAttribute(tag, name) {
+  const match = tag.match(new RegExp(`${name}="([^"]*)"`));
+  return match?.[1];
+}
+function createComponentMarker(input) {
+  const attributes = [
+    `data-eco-node-id="${escapeAttribute(input.nodeId)}"`,
+    `data-eco-integration="${escapeAttribute(input.integration)}"`,
+    `data-eco-component-ref="${escapeAttribute(input.componentRef)}"`,
+    `data-eco-props-ref="${escapeAttribute(input.propsRef)}"`
+  ];
+  if (input.slotRef) {
+    attributes.push(`data-eco-slot-ref="${escapeAttribute(input.slotRef)}"`);
+  }
+  return `<eco-marker ${attributes.join(" ")}></eco-marker>`;
+}
+function parseComponentMarkers(html) {
+  const markerRegex = /<eco-marker\b[^>]*><\/eco-marker>/g;
+  const results = [];
+  for (let match = markerRegex.exec(html); match; match = markerRegex.exec(html)) {
+    const tag = match[0];
+    const nodeId = readAttribute(tag, "data-eco-node-id");
+    const integration = readAttribute(tag, "data-eco-integration");
+    const componentRef = readAttribute(tag, "data-eco-component-ref");
+    const propsRef = readAttribute(tag, "data-eco-props-ref");
+    const slotRef = readAttribute(tag, "data-eco-slot-ref");
+    if (!nodeId || !integration || !componentRef || !propsRef) {
+      continue;
+    }
+    results.push({
+      nodeId,
+      integration,
+      componentRef,
+      propsRef,
+      slotRef
+    });
+  }
+  return results;
+}
+export {
+  createComponentMarker,
+  parseComponentMarkers
+};

package/src/route-renderer/component-graph/component-reference.d.ts

@@ -0,0 +1,10 @@
+import type { EcoComponent } from '../../public-types.js';
+/**
+ * Resolves a stable component reference for marker emission and lookup.
+ *
+ * Build-time metadata remains the preferred source. When a component is
+ * imported directly from source on the server and metadata has not been
+ * injected, fall back to a process-local stable runtime reference so explicit
+ * request-time rendering can still resolve deferred boundaries.
+ */
+export declare function getComponentReference(component: EcoComponent): string;

package/src/route-renderer/component-graph/component-reference.js

@@ -0,0 +1,19 @@
+const runtimeComponentRefs = /* @__PURE__ */ new WeakMap();
+let nextRuntimeComponentRef = 0;
+function getComponentReference(component) {
+  const metadataRef = component.config?.__eco?.id ?? component.config?.__eco?.file;
+  if (metadataRef) {
+    return metadataRef;
+  }
+  const existingRef = runtimeComponentRefs.get(component);
+  if (existingRef) {
+    return existingRef;
+  }
+  nextRuntimeComponentRef += 1;
+  const runtimeRef = `eco-runtime-component-${nextRuntimeComponentRef}`;
+  runtimeComponentRefs.set(component, runtimeRef);
+  return runtimeRef;
+}
+export {
+  getComponentReference
+};

package/src/route-renderer/component-graph/marker-graph-resolver.d.ts

@@ -0,0 +1,77 @@
+import type { ComponentRenderInput, ComponentRenderResult, EcoComponent } from '../../public-types.js';
+import type { ProcessedAsset } from '../../services/assets/asset-processing-service/index.js';
+import type { MarkerNodeId } from './component-marker.js';
+/**
+ * Serializable graph-context payload used during post-render marker resolution.
+ *
+ * `propsByRef` stores serialized props captured during the first render pass,
+ * while `slotChildrenByRef` preserves parent-child marker relationships for
+ * slot-like composition.
+ */
+export type MarkerGraphContext = {
+    propsByRef?: Record<string, Record<string, unknown>>;
+    slotChildrenByRef?: Record<string, MarkerNodeId[]>;
+};
+/**
+ * Minimal renderer contract needed for deferred component resolution.
+ *
+ * The marker graph resolver intentionally depends only on component-level render
+ * capabilities, not on the full integration renderer abstraction.
+ */
+export interface MarkerGraphComponentRenderer {
+    renderComponent(input: ComponentRenderInput): Promise<ComponentRenderResult>;
+}
+export interface MarkerGraphResolverOptions {
+    html: string;
+    componentsToResolve: EcoComponent[];
+    graphContext: MarkerGraphContext;
+    resolveRenderer: (integrationName: string) => MarkerGraphComponentRenderer;
+    applyAttributesToFirstElement: (html: string, attributes: Record<string, string>) => string;
+}
+/**
+ * Resolves deferred `eco-marker` tokens after the first render pass.
+ *
+ * This service owns the second-stage orchestration for cross-integration
+ * component rendering. It builds a component reference registry, constructs a
+ * deterministic marker DAG, resolves leaf nodes before parents, and collects any
+ * component-level assets emitted during that process.
+ *
+ * Responsibility split:
+ * - core resolves marker structure, refs, child ordering, and renderer dispatch
+ * - the target integration renderer resolves the actual component render through
+ *   `renderComponent()` once the marker has been decoded into component input
+ */
+export declare class MarkerGraphResolver {
+    /**
+     * Resolves every marker in the supplied HTML and returns the final HTML plus
+     * any assets produced by nested component renders.
+     *
+     * The resolver is intentionally fail-fast: missing component refs or props refs
+     * indicate a broken render graph and should surface immediately instead of
+     * producing partial output.
+     *
+     * The resolver does not render integration-specific HTML itself. Instead, it
+     * reconstructs `ComponentRenderInput` from the marker payload and then delegates
+     * the actual rendering to the target integration renderer.
+     *
+     * @param options Marker graph resolution inputs for one render pass.
+     * @returns Resolved HTML and collected component assets.
+     */
+    resolve(options: MarkerGraphResolverOptions): Promise<{
+        html: string;
+        assets: ProcessedAsset[];
+    }>;
+    /**
+     * Builds a reference registry from the root component set and all nested
+     * declared component dependencies.
+     *
+     * Component refs are keyed by build metadata when available, falling back to a
+     * stable runtime reference for source-imported components. Traversal is depth-
+     * first and deduplicated by component identity to remain stable in shared
+     * dependency graphs.
+     *
+     * @param components Root components participating in resolution.
+     * @returns Lookup table from component ref to component definition.
+     */
+    private buildComponentRefRegistry;
+}

package/src/route-renderer/component-graph/marker-graph-resolver.js

@@ -0,0 +1,95 @@
+import { getComponentReference } from "./component-reference.js";
+import { extractComponentGraph } from "./component-graph.js";
+import { resolveComponentGraph } from "./component-graph-executor.js";
+class MarkerGraphResolver {
+  /**
+   * Resolves every marker in the supplied HTML and returns the final HTML plus
+   * any assets produced by nested component renders.
+   *
+   * The resolver is intentionally fail-fast: missing component refs or props refs
+   * indicate a broken render graph and should surface immediately instead of
+   * producing partial output.
+   *
+   * The resolver does not render integration-specific HTML itself. Instead, it
+   * reconstructs `ComponentRenderInput` from the marker payload and then delegates
+   * the actual rendering to the target integration renderer.
+   *
+   * @param options Marker graph resolution inputs for one render pass.
+   * @returns Resolved HTML and collected component assets.
+   */
+  async resolve(options) {
+    const registry = this.buildComponentRefRegistry(options.componentsToResolve);
+    const graph = extractComponentGraph(options.html, options.graphContext.slotChildrenByRef ?? {});
+    const resolvedNodeHtml = /* @__PURE__ */ new Map();
+    const assets = [];
+    const resolvedHtml = await resolveComponentGraph(options.html, graph, async (marker) => {
+      const component = registry.get(marker.componentRef);
+      if (!component) {
+        throw new Error(`[ecopages] Missing component reference for marker: ${marker.componentRef}`);
+      }
+      const props = options.graphContext.propsByRef?.[marker.propsRef];
+      if (!props) {
+        throw new Error(`[ecopages] Missing props reference for marker: ${marker.propsRef}`);
+      }
+      let children;
+      if (marker.slotRef) {
+        const childNodeIds = options.graphContext.slotChildrenByRef?.[marker.slotRef] ?? [];
+        if (childNodeIds.length > 0) {
+          children = childNodeIds.map((childNodeId) => resolvedNodeHtml.get(childNodeId) ?? "").join("");
+        }
+      }
+      const renderer = options.resolveRenderer(marker.integration);
+      const componentRender = await renderer.renderComponent({
+        component,
+        props,
+        children,
+        integrationContext: {
+          componentInstanceId: marker.nodeId
+        }
+      });
+      if (componentRender.assets?.length) {
+        assets.push(...componentRender.assets);
+      }
+      const htmlWithAttributes = componentRender.canAttachAttributes && componentRender.rootAttributes ? options.applyAttributesToFirstElement(componentRender.html, componentRender.rootAttributes) : componentRender.html;
+      resolvedNodeHtml.set(marker.nodeId, htmlWithAttributes);
+      return { html: htmlWithAttributes };
+    });
+    return {
+      html: resolvedHtml,
+      assets
+    };
+  }
+  /**
+   * Builds a reference registry from the root component set and all nested
+   * declared component dependencies.
+   *
+   * Component refs are keyed by build metadata when available, falling back to a
+   * stable runtime reference for source-imported components. Traversal is depth-
+   * first and deduplicated by component identity to remain stable in shared
+   * dependency graphs.
+   *
+   * @param components Root components participating in resolution.
+   * @returns Lookup table from component ref to component definition.
+   */
+  buildComponentRefRegistry(components) {
+    const registry = /* @__PURE__ */ new Map();
+    const stack = [...components];
+    const seen = /* @__PURE__ */ new Set();
+    while (stack.length > 0) {
+      const current = stack.pop();
+      if (!current || seen.has(current)) {
+        continue;
+      }
+      seen.add(current);
+      registry.set(getComponentReference(current), current);
+      const nested = current.config?.dependencies?.components ?? [];
+      for (const component of nested) {
+        stack.push(component);
+      }
+    }
+    return registry;
+  }
+}
+export {
+  MarkerGraphResolver
+};