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

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

@@ -1,84 +0,0 @@
-import type { ComponentMarker, MarkerNodeId } from './component-marker.ts';
-import { parseComponentMarkers } from './component-marker.ts';
-import type { ComponentGraph } from './component-graph.ts';
-
-/**
- * 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>;
-
-/**
- * Escapes dynamic content before embedding it in a regular expression.
- *
- * @param value Raw regex input.
- * @returns Escaped regex-safe value.
- */
-function escapeRegex(value: string): string {
-	return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-
-/**
- * Replaces exactly one marker token matching the provided node id.
- *
- * @param html Current HTML buffer.
- * @param nodeId Marker node id to replace.
- * @param replacement Rendered HTML replacement.
- * @returns Updated HTML buffer.
- */
-function replaceMarkerByNodeId(html: string, nodeId: MarkerNodeId, replacement: string): string {
-	const pattern = `<eco-marker[^>]*data-eco-node-id="${escapeRegex(nodeId)}"[^>]*><\\/eco-marker>`;
-	const markerRegex = new RegExp(pattern);
-	return html.replace(markerRegex, replacement);
-}
-
-/**
- * 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 async function resolveComponentGraph(
-	inputHtml: string,
-	graph: ComponentGraph,
-	resolver: GraphNodeResolver,
-): Promise<string> {
-	let html = inputHtml;
-	const markersById = new Map<MarkerNodeId, ComponentMarker>();
-	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;
-}

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

@@ -1,159 +0,0 @@
-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.ts

@@ -1,117 +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;
-};
-
-/**
- * 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;
-}