@ecopages/core 0.2.0-alpha.11 → 0.2.0-alpha.13

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

@@ -1,53 +0,0 @@
-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[]>;
-/**
- * Serializable props captured for deferred marker nodes.
- *
- * The graph builder reads this registry to discover child markers that were not
- * emitted into the outer HTML stream because they were captured inside a
- * deferred parent's serialized `children` prop.
- */
-export type PropsRegistry = Record<string, Record<string, unknown>>;
-/**
- * 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. Discover nested child markers captured inside serialized `children` props.
- * 3. 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.
- * @param propsRegistry Optional props registry used to discover nested markers
- * captured inside deferred parent `children` props.
- * @returns Component graph structure with levels ready for execution.
- */
-export declare function extractComponentGraph(html: string, slotChildrenRegistry?: SlotChildrenRegistry, propsRegistry?: PropsRegistry): ComponentGraph;

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

@@ -1,94 +0,0 @@
-import { parseComponentMarkers } from "./component-marker.js";
-function readNestedChildMarkers(marker, propsRegistry) {
-  const children = propsRegistry[marker.propsRef]?.children;
-  if (typeof children !== "string" || !children.includes("<eco-marker")) {
-    return [];
-  }
-  return parseComponentMarkers(children);
-}
-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 = {}, propsRegistry = {}) {
-  const markers = parseComponentMarkers(html);
-  const nodes = /* @__PURE__ */ new Map();
-  const edges = /* @__PURE__ */ new Map();
-  const reverseEdges = /* @__PURE__ */ new Map();
-  const discoveredMarkers = [];
-  const registerMarker = (marker) => {
-    if (nodes.has(marker.nodeId)) {
-      return false;
-    }
-    discoveredMarkers.push(marker);
-    nodes.set(marker.nodeId, {
-      ...marker,
-      order: discoveredMarkers.length - 1
-    });
-    return true;
-  };
-  for (const marker of markers) {
-    registerMarker(marker);
-  }
-  for (let index = 0; index < discoveredMarkers.length; index += 1) {
-    const marker = discoveredMarkers[index];
-    for (const nestedMarker of readNestedChildMarkers(marker, propsRegistry)) {
-      registerMarker(nestedMarker);
-    }
-  }
-  for (const marker of discoveredMarkers) {
-    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

@@ -1,52 +0,0 @@
-/**
- * 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

@@ -1,46 +0,0 @@
-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

@@ -1,11 +0,0 @@
-import type { EcoComponent } from '../../types/public-types.js';
-export declare function registerRuntimeComponentHint(component: EcoComponent, hint: string): void;
-/**
- * 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

@@ -1,39 +0,0 @@
-import { rapidhash } from "../../utils/hash.js";
-const runtimeComponentRefs = /* @__PURE__ */ new WeakMap();
-const runtimeComponentHints = /* @__PURE__ */ new WeakMap();
-const runtimeComponentHintSymbol = /* @__PURE__ */ Symbol.for("ecopages.runtimeComponentHint");
-let nextRuntimeComponentRef = 0;
-function registerRuntimeComponentHint(component, hint) {
-  runtimeComponentHints.set(component, hint);
-  component[runtimeComponentHintSymbol] = hint;
-}
-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;
-  }
-  const runtimeHint = runtimeComponentHints.get(component);
-  if (runtimeHint) {
-    const hintedRef = `eco-runtime-component-${rapidhash(runtimeHint).toString(36)}`;
-    runtimeComponentRefs.set(component, hintedRef);
-    return hintedRef;
-  }
-  const componentHint = component[runtimeComponentHintSymbol];
-  if (componentHint) {
-    const hintedRef = `eco-runtime-component-${rapidhash(componentHint).toString(36)}`;
-    runtimeComponentRefs.set(component, hintedRef);
-    return hintedRef;
-  }
-  nextRuntimeComponentRef += 1;
-  const runtimeRef = `eco-runtime-component-${nextRuntimeComponentRef}`;
-  runtimeComponentRefs.set(component, runtimeRef);
-  return runtimeRef;
-}
-export {
-  getComponentReference,
-  registerRuntimeComponentHint
-};

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

@@ -1,79 +0,0 @@
-import type { ComponentRenderInput, ComponentRenderResult, EcoComponent } from '../../types/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 {
-    renderComponentForMarkerGraph(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;
-    instanceIdScope?: 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 {
-    private restoreSerializedChildren;
-    /**
-     * 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

@@ -1,117 +0,0 @@
-import { getComponentReference } from "./component-reference.js";
-import { extractComponentGraph } from "./component-graph.js";
-import { resolveComponentGraph } from "./component-graph-executor.js";
-class MarkerGraphResolver {
-  restoreSerializedChildren(serializedChildren, childNodeIds, resolvedNodeHtml) {
-    let restoredChildren = serializedChildren;
-    for (const childNodeId of childNodeIds) {
-      const resolvedChildHtml = resolvedNodeHtml.get(childNodeId);
-      if (!resolvedChildHtml) {
-        continue;
-      }
-      const markerRegex = new RegExp(
-        `<eco-marker\\b(?=[^>]*data-eco-node-id="${childNodeId}")[^>]*><\\/eco-marker>`,
-        "g"
-      );
-      restoredChildren = restoredChildren.replace(markerRegex, resolvedChildHtml);
-    }
-    return restoredChildren;
-  }
-  /**
-   * 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 ?? {},
-      options.graphContext.propsByRef ?? {}
-    );
-    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}`);
-      }
-      const normalizedProps = { ...props };
-      let children;
-      if (marker.slotRef) {
-        const childNodeIds = options.graphContext.slotChildrenByRef?.[marker.slotRef] ?? [];
-        if (childNodeIds.length > 0) {
-          const serializedChildren = normalizedProps.children;
-          children = typeof serializedChildren === "string" ? this.restoreSerializedChildren(serializedChildren, childNodeIds, resolvedNodeHtml) : childNodeIds.map((childNodeId) => resolvedNodeHtml.get(childNodeId) ?? "").join("");
-        }
-      }
-      const renderer = options.resolveRenderer(marker.integration);
-      const componentInstanceId = options.instanceIdScope ? `${options.instanceIdScope}_${marker.nodeId}` : marker.nodeId;
-      const componentRender = await renderer.renderComponentForMarkerGraph({
-        component,
-        props: normalizedProps,
-        children,
-        integrationContext: {
-          componentInstanceId
-        }
-      });
-      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
-};