@ecopages/core 0.2.0-alpha.1

package/src/route-renderer/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.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.ts

@@ -0,0 +1,159 @@
+import type { ComponentMarker, MarkerNodeId } from './component-marker.ts';
+import { parseComponentMarkers } from './component-marker.ts';
+
+/**
+ * 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[][];
+};
+
+/**
+ * Ensures adjacency maps are initialized and registers one directed edge.
+ *
+ * @param edges Parent -> children adjacency map.
+ * @param reverseEdges Child -> parents adjacency map.
+ * @param from Parent node id.
+ * @param to Child node id.
+ */
+function ensureEdgeMaps(
+	edges: Map<MarkerNodeId, Set<MarkerNodeId>>,
+	reverseEdges: Map<MarkerNodeId, Set<MarkerNodeId>>,
+	from: MarkerNodeId,
+	to: MarkerNodeId,
+): void {
+	if (!edges.has(from)) {
+		edges.set(from, new Set());
+	}
+	if (!reverseEdges.has(to)) {
+		reverseEdges.set(to, new Set());
+	}
+	edges.get(from)?.add(to);
+	reverseEdges.get(to)?.add(from);
+}
+
+/**
+ * Builds topological levels from graph adjacency maps.
+ *
+ * Levels are ordered from roots to leaves and each level preserves source order.
+ *
+ * @param nodes Graph node registry.
+ * @param edges Parent -> children adjacency map.
+ * @param reverseEdges Child -> parents adjacency map.
+ * @returns Topological levels from root level to leaf level.
+ * @throws Error when a cycle or unresolved dependency remains.
+ */
+function computeLevels(
+	nodes: Map<MarkerNodeId, ComponentGraphNode>,
+	edges: Map<MarkerNodeId, Set<MarkerNodeId>>,
+	reverseEdges: Map<MarkerNodeId, Set<MarkerNodeId>>,
+): MarkerNodeId[][] {
+	const indegree = new Map<MarkerNodeId, number>();
+	for (const nodeId of nodes.keys()) {
+		indegree.set(nodeId, reverseEdges.get(nodeId)?.size ?? 0);
+	}
+
+	const levels: MarkerNodeId[][] = [];
+	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 = new Set<MarkerNodeId>();
+
+	while (frontier.length > 0) {
+		levels.push(frontier);
+		const next: MarkerNodeId[] = [];
+
+		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;
+}
+
+/**
+ * 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 function extractComponentGraph(html: string, slotChildrenRegistry: SlotChildrenRegistry = {}): ComponentGraph {
+	const markers = parseComponentMarkers(html);
+	const nodes = new Map<MarkerNodeId, ComponentGraphNode>();
+	const edges = new Map<MarkerNodeId, Set<MarkerNodeId>>();
+	const reverseEdges = new Map<MarkerNodeId, Set<MarkerNodeId>>();
+
+	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 };
+}

package/src/route-renderer/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-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-marker.ts

@@ -0,0 +1,117 @@
+/**
+ * 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;
+};
+
+/**
+ * Escapes marker attribute values for safe HTML output.
+ *
+ * @param value Raw attribute value.
+ * @returns HTML-escaped attribute value.
+ */
+function escapeAttribute(value: string): string {
+	return value.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+/**
+ * Reads a single attribute value from a raw marker tag.
+ *
+ * @param tag Full marker tag text.
+ * @param name Attribute name to read.
+ * @returns Attribute value when present; otherwise `undefined`.
+ */
+function readAttribute(tag: string, name: string): string | undefined {
+	const match = tag.match(new RegExp(`${name}="([^"]*)"`));
+	return match?.[1];
+}
+
+/**
+ * Creates the canonical `<eco-marker>` token used for deferred component rendering.
+ *
+ * @param input Marker payload fields.
+ * @returns Serialized marker HTML token.
+ */
+export function createComponentMarker(input: MarkerRenderInput): string {
+	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>`;
+}
+
+/**
+ * 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 function parseComponentMarkers(html: string): ComponentMarker[] {
+	const markerRegex = /<eco-marker\b[^>]*><\/eco-marker>/g;
+	const results: ComponentMarker[] = [];
+
+	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: nodeId as MarkerNodeId,
+			integration,
+			componentRef,
+			propsRef,
+			slotRef,
+		});
+	}
+
+	return results;
+}

package/src/route-renderer/dependency-resolver.d.ts

@@ -0,0 +1,24 @@
+import type { EcoComponent } from '../public-types.js';
+import type { EcoPagesAppConfig } from '../internal-types.js';
+import type { AssetProcessingService, ProcessedAsset } from '../services/asset-processing-service/index.js';
+export declare const DEPENDENCY_ERRORS: {
+    readonly INVALID_STYLESHEET_ENTRY: "Invalid stylesheet dependency entry: expected src or content";
+    readonly INVALID_SCRIPT_ENTRY: "Invalid script dependency entry: expected src or content";
+    readonly LAZY_SCRIPT_MISSING_SRC: "Lazy script dependency entry in dependencies.scripts requires a src value";
+};
+export declare class DependencyResolverService {
+    private appConfig;
+    private assetProcessingService;
+    constructor(appConfig: EcoPagesAppConfig, assetProcessingService: AssetProcessingService);
+    resolveDependencyPath(componentDir: string, pathUrl: string): string;
+    /**
+     * Maps lazy script source entries to deterministic fallback public URLs
+     * used when bundling output URLs are unavailable.
+     */
+    resolveLazyScripts(componentDir: string, scripts: string[]): string;
+    /**
+     * Collects and processes component dependencies (styles, scripts, modules, lazy scripts).
+     * Lazy dependencies are always resolved into global-injector trigger maps.
+     */
+    processComponentDependencies(components: (EcoComponent | Partial<EcoComponent>)[], integrationName: string): Promise<ProcessedAsset[]>;
+}