@ecopages/core 0.2.0-alpha.9 → 0.2.1

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

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

@@ -1,31 +0,0 @@
-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-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/component-graph.d.ts

@@ -1,42 +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[]>;
-/**
- * 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

@@ -1,72 +0,0 @@
-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-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-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-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;
-}

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

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

@@ -1,19 +0,0 @@
-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
-};