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

package/src/plugins/processor.test.ts

@@ -0,0 +1,148 @@
+import { afterAll, beforeEach, describe, expect, test } from 'vitest';
+import fs from 'node:fs';
+import path from 'node:path';
+import type { EcoBuildPlugin } from '../build/build-types.ts';
+import type { EcoPagesAppConfig } from '../internal-types';
+import { Processor, type ProcessorConfig } from './processor.ts';
+
+class TestProcessor extends Processor {
+	override buildPlugins?: EcoBuildPlugin[] = [];
+	override plugins?: EcoBuildPlugin[] = [];
+
+	override async setup(): Promise<void> {}
+
+	override async process(input: unknown, _filePath?: string): Promise<unknown> {
+		return input;
+	}
+
+	override async teardown(): Promise<void> {}
+}
+
+describe('Processor', () => {
+	let processor: TestProcessor;
+	let config: ProcessorConfig;
+	let appConfig: EcoPagesAppConfig;
+
+	beforeEach(() => {
+		config = {
+			name: 'test-processor',
+			options: { test: true },
+			watch: {
+				paths: ['/test'],
+			},
+		};
+
+		const testRoot = path.join(process.cwd(), '.test-tmp', 'processor-test');
+
+		if (fs.existsSync(testRoot)) {
+			fs.rmSync(testRoot, { recursive: true, force: true });
+		}
+
+		appConfig = {
+			rootDir: testRoot,
+			absolutePaths: {
+				srcDir: path.join(testRoot, 'src'),
+				distDir: path.join(testRoot, 'dist'),
+			},
+		} as EcoPagesAppConfig;
+
+		processor = new TestProcessor(config);
+		processor.setContext(appConfig);
+	});
+
+	afterAll(() => {
+		fs.rmSync(path.join(process.cwd(), '.test-tmp'), { recursive: true, force: true });
+	});
+
+	test('should initialize with correct name', () => {
+		expect(processor.getName()).toBe('test-processor');
+	});
+
+	test('should retain runtime capability declarations', () => {
+		const runtimeProcessor = new TestProcessor({
+			name: 'runtime-processor',
+			runtimeCapability: {
+				tags: ['requires-node-builtins'],
+				minRuntimeVersion: '18.0.0',
+			},
+		});
+
+		expect(runtimeProcessor.runtimeCapability).toEqual({
+			tags: ['requires-node-builtins'],
+			minRuntimeVersion: '18.0.0',
+		});
+	});
+
+	test('should return watch config', () => {
+		expect(processor.getWatchConfig()).toEqual({
+			paths: ['/test'],
+		});
+	});
+});
+
+describe('Processor capability matching', () => {
+	test('matches all extensions with * pattern', () => {
+		const processor = new TestProcessor({
+			name: 'wildcard-all',
+			capabilities: [{ kind: 'stylesheet', extensions: ['*'] }],
+		});
+
+		expect(processor.canProcessAsset('stylesheet', '/src/styles/app.css')).toBe(true);
+		expect(processor.canProcessAsset('stylesheet', '/src/styles/app.scss')).toBe(true);
+	});
+
+	test('matches explicit *.ext patterns', () => {
+		const processor = new TestProcessor({
+			name: 'wildcard-explicit',
+			capabilities: [{ kind: 'stylesheet', extensions: ['*.css'] }],
+		});
+
+		expect(processor.canProcessAsset('stylesheet', '/src/styles/app.css')).toBe(true);
+		expect(processor.canProcessAsset('stylesheet', '/src/styles/app.scss')).toBe(false);
+	});
+
+	test('matches grouped extension patterns', () => {
+		const processor = new TestProcessor({
+			name: 'wildcard-group',
+			capabilities: [{ kind: 'stylesheet', extensions: ['*.{css,scss,sass}'] }],
+		});
+
+		expect(processor.canProcessAsset('stylesheet', '/src/styles/app.css')).toBe(true);
+		expect(processor.canProcessAsset('stylesheet', '/src/styles/app.scss')).toBe(true);
+		expect(processor.canProcessAsset('stylesheet', '/src/styles/app.sass')).toBe(true);
+		expect(processor.canProcessAsset('stylesheet', '/src/styles/app.less')).toBe(false);
+	});
+
+	test('matches grouped patterns with mixed case and spacing', () => {
+		const processor = new TestProcessor({
+			name: 'wildcard-group-normalized',
+			capabilities: [{ kind: 'stylesheet', extensions: ['*.{ CSS, ScSs , .SASS }'] }],
+		});
+
+		expect(processor.canProcessAsset('stylesheet', '/src/styles/app.css')).toBe(true);
+		expect(processor.canProcessAsset('stylesheet', '/src/styles/app.scss')).toBe(true);
+		expect(processor.canProcessAsset('stylesheet', '/src/styles/app.sass')).toBe(true);
+		expect(processor.canProcessAsset('stylesheet', '/src/styles/app.less')).toBe(false);
+	});
+
+	test('matches plain extension and dotted extension forms', () => {
+		const processor = new TestProcessor({
+			name: 'plain-ext',
+			capabilities: [{ kind: 'stylesheet', extensions: ['css', '.scss'] }],
+		});
+
+		expect(processor.canProcessAsset('stylesheet', '/src/styles/app.css')).toBe(true);
+		expect(processor.canProcessAsset('stylesheet', '/src/styles/app.scss')).toBe(true);
+		expect(processor.canProcessAsset('stylesheet', '/src/styles/app.sass')).toBe(false);
+	});
+
+	test('respects capability kind filtering', () => {
+		const processor = new TestProcessor({
+			name: 'kind-filter',
+			capabilities: [{ kind: 'image', extensions: ['*.png'] }],
+		});
+
+		expect(processor.canProcessAsset('stylesheet', '/src/styles/app.css')).toBe(false);
+		expect(processor.canProcessAsset('image', '/src/assets/logo.png')).toBe(true);
+	});
+});

package/src/plugins/processor.ts

@@ -2,8 +2,12 @@ import path from 'node:path';
 import { fileSystem } from '@ecopages/file-system';
 import type { EcoBuildPlugin } from '../build/build-types.ts';
 import type { EcoPagesAppConfig, IClientBridge } from '../internal-types';
-import type { AssetDefinition } from '../services/asset-processing-service';
+import type { AssetDefinition } from '../services/assets/asset-processing-service';
+import { DEFAULT_ECOPAGES_WORK_DIR } from '../constants.ts';
 import { GENERATED_BASE_PATHS } from '../constants';
+import type { RuntimeCapabilityDeclaration } from './runtime-capability.ts';
+
+export type { RuntimeCapabilityDeclaration, RuntimeCapabilityTag } from './runtime-capability.ts';
 
 export const PROCESSOR_ERRORS = {
 	CACHE_DIRECTORY_NOT_SET: 'Cache directory not set in context',
@@ -56,6 +60,7 @@ export interface ProcessorConfig<TOptions = Record<string, unknown>> {
 	options?: TOptions;
 	watch?: ProcessorWatchConfig;
 	capabilities?: ProcessorAssetCapability[];
+	runtimeCapability?: RuntimeCapabilityDeclaration;
 }
 export interface ProcessorContext {
 	config: EcoPagesAppConfig;
@@ -78,6 +83,7 @@ export abstract class Processor<TOptions = Record<string, unknown>> {
 	protected options?: TOptions;
 	protected watchConfig?: ProcessorWatchConfig;
 	protected capabilities: ProcessorAssetCapability[] = [];
+	readonly runtimeCapability?: RuntimeCapabilityDeclaration;
 
 	/** Plugins that are only used during the build process */
 	abstract buildPlugins?: EcoBuildPlugin[];
@@ -90,11 +96,15 @@ export abstract class Processor<TOptions = Record<string, unknown>> {
 		this.options = config.options;
 		this.watchConfig = config.watch;
 		this.capabilities = config.capabilities ?? [];
+		this.runtimeCapability = config.runtimeCapability;
 	}
 
 	setContext(appConfig: EcoPagesAppConfig): void {
+		const workDir =
+			appConfig.absolutePaths.workDir ??
+			path.join(appConfig.rootDir, appConfig.workDir ?? DEFAULT_ECOPAGES_WORK_DIR);
 		const cachePath = resolveGeneratedPath('cache', {
-			root: appConfig.absolutePaths.distDir,
+			root: workDir,
 			module: this.name,
 		});
 
@@ -109,6 +119,16 @@ export abstract class Processor<TOptions = Record<string, unknown>> {
 		};
 	}
 
+	/**
+	 * Prepares build-facing processor contributions before config finalization.
+	 *
+	 * @remarks
+	 * Override this when a processor must compute runtime/build plugins or other
+	 * manifest-owned state before startup. Runtime-only work such as cache
+	 * warming or watcher registration should stay in `setup()`.
+	 */
+	async prepareBuildContributions(): Promise<void> {}
+
 	abstract setup(): Promise<void>;
 	abstract teardown(): Promise<void>;
 	abstract process(input: unknown, filePath?: string): Promise<unknown>;

package/src/plugins/runtime-capability.ts

@@ -0,0 +1,14 @@
+export type RuntimeCapabilityTag =
+	| 'bun-only'
+	| 'node-compatible'
+	| 'requires-native-bun-api'
+	| 'requires-node-builtins';
+
+/**
+ * Declares the runtime assumptions a plugin makes so config finalization can
+ * reject incompatible startup environments before bootstrapping the app.
+ */
+export interface RuntimeCapabilityDeclaration {
+	tags: RuntimeCapabilityTag[];
+	minRuntimeVersion?: string;
+}

package/src/public-types.ts

@@ -1,14 +1,18 @@
 import type { Readable } from 'node:stream';
-import type { ApiResponseBuilder } from './adapters/shared/api-response.js';
+import type { ApiResponseBuilder } from './adapters/shared/api-response.ts';
+import type { BuildExecutor } from './build/build-adapter.ts';
 import type { EcoBuildPlugin } from './build/build-types.ts';
 import type { EcoPageComponent } from './eco/eco.types.ts';
 import type { EcoPagesAppConfig } from './internal-types.ts';
 import type { HmrStrategy } from './hmr/hmr-strategy.ts';
-import type { ProcessedAsset } from './services/asset-processing-service/assets.types.ts';
+import type { BrowserBundleExecutor } from './services/assets/browser-bundle.service.ts';
+import type { ProcessedAsset } from './services/assets/asset-processing-service/assets.types.ts';
 import type { CacheStats, CacheStrategy } from './services/cache/cache.types.ts';
 import type { InteractionEventsString as ScriptsInjectorInteractionEventsString } from '@ecopages/scripts-injector/types';
 
 export type { EcoPageComponent } from './eco/eco.types.ts';
+export type { MarkerGraphContext } from './route-renderer/component-graph/marker-graph-resolver.ts';
+export type { ProcessedAsset } from './services/assets/asset-processing-service/assets.types.ts';
 
 import type {
 	StandardSchema,
@@ -98,7 +102,7 @@ export interface CacheInvalidator {
 
 /**
  * Context interface for HMR strategies.
- * Provides access to watched files, specifier mappings, and build configuration.
+ * Provides access to watched files, registered bare-specifier mappings, and build configuration.
  */
 export interface DefaultHmrContext {
 	/**
@@ -107,7 +111,7 @@ export interface DefaultHmrContext {
 	getWatchedFiles(): Map<string, string>;
 
 	/**
-	 * Map of bare specifiers to vendor URLs for import resolution.
+	 * Map of bare specifiers to runtime URLs for browser import resolution.
 	 */
 	getSpecifierMap(): Map<string, string>;
 
@@ -137,6 +141,20 @@ export interface DefaultHmrContext {
 	 * Used by plugins to identify page files for transformation.
 	 */
 	getPagesDir(): string;
+
+	/**
+	 * Build executor owned by the active app/runtime.
+	 */
+	getBuildExecutor(): BuildExecutor;
+
+	/**
+	 * Browser bundler owned by the active app/runtime.
+	 */
+	getBrowserBundleService(): BrowserBundleExecutor;
+	/**
+	 * Server-side module loader owned by the active app/runtime.
+	 */
+	importServerModule<T = unknown>(filePath: string): Promise<T>;
 }
 
 /**
@@ -180,12 +198,31 @@ export interface IClientBridge {
  */
 export interface IHmrManager {
 	/**
-	 * Registers a client entrypoint to be built and watched.
+	 * Registers an integration-owned client entrypoint to be built and watched.
+	 *
+	 * @remarks
+	 * This path is strict: the owning integration must emit the expected `_hmr`
+	 * bundle. Missing output is treated as a development pipeline failure.
 	 */
 	registerEntrypoint(entrypointPath: string): Promise<string>;
 
 	/**
-	 * Registers mappings from bare specifiers to vendor URLs.
+	 * Registers a generic script asset entrypoint to be built and watched.
+	 *
+	 * @remarks
+	 * This path exists for non-page script assets that are not owned by a
+	 * framework integration. Unlike `registerEntrypoint()`, it may use the generic
+	 * script bundling path.
+	 */
+	registerScriptEntrypoint(entrypointPath: string): Promise<string>;
+
+	/**
+	 * Registers mappings from bare specifiers to runtime URLs.
+	 *
+	 * @remarks
+	 * This is the shared registration seam for integration-owned runtime alias
+	 * maps. The registry may later back a broader import-map-style facility, but
+	 * the mappings themselves remain integration-owned.
 	 */
 	registerSpecifierMap(map: Record<string, string>): void;
 
@@ -225,7 +262,7 @@ export interface IHmrManager {
 	getWatchedFiles(): Map<string, string>;
 
 	/**
-	 * Gets the specifier map.
+	 * Gets the registered bare-specifier map.
 	 */
 	getSpecifierMap(): Map<string, string>;
 
@@ -327,7 +364,7 @@ export type EcoComponentConfig = {
 	 * MyPage.config = { layout: Layout };
 	 * ```
 	 */
-	layout?: EcoComponent;
+	layout?: EcoPageLayoutComponent<any>;
 	dependencies?: EcoComponentDependencies;
 	/**
 	 * Internal: Resolved lazy scripts grouped by trigger.
@@ -450,6 +487,13 @@ export interface PageHeadProps<T = EcoPagesElement> {
 	children?: T;
 }
 
+/**
+ * Represents the props for a route layout.
+ */
+export interface LayoutProps<T = EcoPagesElement> extends Partial<RequestPageContext> {
+	children: T;
+}
+
 /**
  * Represents the props for the HTML template of a page.
  */
@@ -460,6 +504,24 @@ export interface HtmlTemplateProps extends PageHeadProps {
 	pageProps: Record<string, unknown>;
 }
 
+/**
+ * Layout components accepted by pages.
+ *
+ * This preserves compatibility with existing `eco.component()` layouts while
+ * also supporting semantic `eco.layout()` declarations.
+ */
+export type EcoPageLayoutComponent<T = EcoPagesElement> = EcoLayoutComponent<T> | EcoComponent<any, T>;
+
+/**
+ * Represents a layout component created with eco.layout().
+ */
+export type EcoLayoutComponent<T = EcoPagesElement> = EcoComponent<LayoutProps<T>, T>;
+
+/**
+ * Represents an HTML shell component created with eco.html().
+ */
+export type EcoHtmlComponent<T = EcoPagesElement> = EcoComponent<HtmlTemplateProps, T>;
+
 /**
  * Represents the props for the error 404 template.
  */
@@ -683,9 +745,9 @@ type StylesheetContentIntegrationPluginDependencies = {
 export type IntegrationRendererRenderOptions<C = EcoPagesElement> = RouteRendererOptions & {
 	props?: Record<string, unknown>;
 	metadata: PageMetadataProps;
-	HtmlTemplate: EcoComponent<HtmlTemplateProps, C>;
+	HtmlTemplate: EcoHtmlComponent<C>;
 	Page: EcoComponent<PageProps, C>;
-	Layout?: EcoComponent;
+	Layout?: EcoPageLayoutComponent<any>;
 	dependencies?: EcoComponentDependencies;
 	resolvedDependencies: ProcessedAsset[];
 	componentRender?: ComponentRenderResult;
@@ -762,7 +824,7 @@ export interface RenderContext {
 	 * @param props - Props to pass to the view
 	 * @param options - Optional status code and headers
 	 */
-	render<P = Record<string, unknown>>(view: EcoComponent<P>, props: P, options?: RenderOptions): Promise<Response>;
+	render<P = Record<string, unknown>>(view: EcoComponent<P>, props?: P, options?: RenderOptions): Promise<Response>;
 
 	/**
 	 * Render an eco.page view without layout (for partials/fragments).

package/src/route-renderer/GRAPH.md

@@ -136,7 +136,7 @@ flowchart TD
   K -- Yes --> L[buildGlobalInjectorAssets]
   K -- No --> M[continue]
   L --> M
-  M --> N[HtmlPostProcessingService dedupeProcessedAssets]
+  M --> N[HtmlTransformerService dedupeProcessedAssets]
   N --> O[htmlTransformer setProcessedDependencies]
   O --> P[return normalized render options]
 ```
@@ -155,11 +155,11 @@ flowchart TD
   F --> G{contains eco marker token?}
   G -- Yes --> H[resolveMarkerGraphHtml]
   G -- No --> I[skip graph resolution]
-  H --> J[HtmlPostProcessingService dedupeProcessedAssets]
+  H --> J[HtmlTransformerService dedupeProcessedAssets]
   J --> K[merge marker assets into transformer deps]
   I --> L{root attributes attachable?}
   K --> L
-  L -- Yes --> M[HtmlPostProcessingService applyAttributesToFirstBodyElement]
+  L -- Yes --> M[HtmlTransformerService applyAttributesToFirstBodyElement]
   L -- No --> N[leave html unchanged]
   M --> O[htmlTransformer transform]
   N --> O
@@ -190,16 +190,14 @@ flowchart LR
   A[IntegrationRenderer] --> B[RenderPreparationService]
   A --> C[RenderExecutionService]
   A --> D[MarkerGraphResolver]
-  A --> E[HtmlPostProcessingService]
   A --> F[PageModuleLoaderService]
   A --> G[DependencyResolverService]
   A --> H[HtmlTransformerService]
 
   B --> F
   B --> G
-  B --> E
+  B --> H
   C --> D
-  C --> E
   C --> H
 ```
 
@@ -348,7 +346,7 @@ For someone new to the rendering system, this is probably the most useful order
 7. `render-preparation.service.ts`
 8. `render-execution.service.ts`
 9. `marker-graph-resolver.ts`
-10. `html-post-processing.service.ts`
+10. `html-transformer.service.ts`
 11. `page-module-loader.ts`
 12. `dependency-resolver.ts`
 13. `component-marker.ts`
@@ -356,7 +354,6 @@ For someone new to the rendering system, this is probably the most useful order
 15. `component-graph-executor.ts`
 16. `eco.ts`
 17. `component-render-context.ts`
-18. `html-transformer.service.ts`
 
 ## 9) Key Files
 
@@ -368,18 +365,17 @@ For someone new to the rendering system, this is probably the most useful order
 - `packages/core/src/adapters/shared/explicit-static-route-matcher.ts`
 - `packages/core/src/adapters/shared/render-context.ts`
 - `packages/core/src/route-renderer/route-renderer.ts`
-- `packages/core/src/route-renderer/integration-renderer.ts`
-- `packages/core/src/route-renderer/render-preparation.service.ts`
-- `packages/core/src/route-renderer/render-execution.service.ts`
-- `packages/core/src/route-renderer/html-post-processing.service.ts`
-- `packages/core/src/route-renderer/marker-graph-resolver.ts`
-- `packages/core/src/route-renderer/component-marker.ts`
-- `packages/core/src/route-renderer/component-graph.ts`
-- `packages/core/src/route-renderer/component-graph-executor.ts`
-- `packages/core/src/route-renderer/page-module-loader.ts`
-- `packages/core/src/route-renderer/dependency-resolver.ts`
-- `packages/core/src/services/page-module-import.service.ts`
-- `packages/core/src/services/page-request-cache-coordinator.service.ts`
+- `packages/core/src/route-renderer/orchestration/integration-renderer.ts`
+- `packages/core/src/route-renderer/orchestration/render-preparation.service.ts`
+- `packages/core/src/route-renderer/orchestration/render-execution.service.ts`
+- `packages/core/src/route-renderer/component-graph/marker-graph-resolver.ts`
+- `packages/core/src/route-renderer/component-graph/component-marker.ts`
+- `packages/core/src/route-renderer/component-graph/component-graph.ts`
+- `packages/core/src/route-renderer/component-graph/component-graph-executor.ts`
+- `packages/core/src/route-renderer/page-loading/page-module-loader.ts`
+- `packages/core/src/route-renderer/page-loading/dependency-resolver.ts`
+- `packages/core/src/services/module-loading/page-module-import.service.ts`
+- `packages/core/src/services/cache/page-request-cache-coordinator.service.ts`
 - `packages/core/src/eco/component-render-context.ts`
 - `packages/core/src/eco/eco.ts`
 - `packages/core/src/services/html-transformer.service.ts`

package/src/route-renderer/README.md

@@ -19,15 +19,13 @@ The route renderer layer is responsible for:
 - `RouteRendererFactory` chooses integration renderers based on route file extension.
 - `RouteRenderer` delegates route execution to the selected integration renderer.
 
-### `integration-renderer.ts`
+### `orchestration/`
 
-Abstract base class that coordinates end-to-end route rendering:
+Framework-owned orchestration services and renderer base class:
 
-1. Resolve page module and page data.
-2. Resolve and process component dependencies.
-3. Add route-level assets and orchestration assets.
-4. Render HTML via integration-specific `render()`.
-5. Inject processed assets into final HTML through `HtmlTransformerService`.
+- `integration-renderer.ts`: abstract base class that coordinates end-to-end route rendering.
+- `render-preparation.service.ts`: page module/data/dependency preparation before render.
+- `render-execution.service.ts`: render capture, marker-graph resolution, and finalization.
 
 It also provides:
 
@@ -35,26 +33,17 @@ It also provides:
 - `renderComponent()` contract for component-level orchestration and artifact reporting.
 - marker graph resolution for nested cross-integration component boundaries.
 
-### `component-marker.ts`
+### `component-graph/`
 
-Defines marker token contract for component-level orchestration:
+Component marker contracts and graph resolution:
 
 - `createComponentMarker()` for canonical `<eco-marker ...></eco-marker>` generation.
 - `parseComponentMarkers()` for marker extraction from rendered HTML.
-
-### `component-graph.ts`
-
-Builds a deterministic DAG from marker nodes:
-
 - node collection by marker id.
 - parent/child edges from slot reference registry.
 - topological levels for bottom-up execution.
 
-### `component-graph-executor.ts`
-
-Resolves graph levels in reverse order (leaf to root) and replaces markers with rendered HTML via integration `renderComponent()`.
-
-### `page-module-loader.ts`
+### `page-loading/`
 
 Service for loading page modules and deriving page data:
 
@@ -62,8 +51,6 @@ Service for loading page modules and deriving page data:
 - `resolvePageModule()` normalizes exports and statics.
 - `resolvePageData()` resolves static props then metadata.
 
-### `dependency-resolver.ts`
-
 Builds processed assets from component dependency declarations:
 
 - Scripts/styles/components/modules.

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

@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest';
+import { createComponentMarker } from './component-marker.ts';
+import { extractComponentGraph } from './component-graph.ts';
+import { resolveComponentGraph } from './component-graph-executor.ts';
+
+describe('component graph executor', () => {
+	it('resolves markers bottom-up using graph levels', async () => {
+		const html = [
+			'<main>',
+			createComponentMarker({
+				nodeId: 'n_1',
+				integration: 'lit',
+				componentRef: 'c_parent',
+				propsRef: 'p_parent',
+				slotRef: 's_parent',
+			}),
+			createComponentMarker({
+				nodeId: 'n_2',
+				integration: 'react',
+				componentRef: 'c_child',
+				propsRef: 'p_child',
+			}),
+			'</main>',
+		].join('');
+
+		const graph = extractComponentGraph(html, {
+			s_parent: ['n_2'],
+		});
+
+		const resolved = await resolveComponentGraph(html, graph, async (marker) => {
+			if (marker.nodeId === 'n_2') {
+				return { html: '<section>child</section>' };
+			}
+			return { html: '<article>parent</article>' };
+		});
+
+		expect(resolved).toContain('<article>parent</article>');
+		expect(resolved).toContain('<section>child</section>');
+		expect(resolved).not.toContain('<eco-marker');
+	});
+});

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

@@ -0,0 +1,63 @@
+import { describe, expect, it } from 'vitest';
+import { createComponentMarker } from './component-marker.ts';
+import { extractComponentGraph } from './component-graph.ts';
+
+describe('component graph extraction', () => {
+	it('extracts nodes in deterministic order without slot links', () => {
+		const html = [
+			createComponentMarker({ nodeId: 'n_1', integration: 'lit', componentRef: 'c_1', propsRef: 'p_1' }),
+			createComponentMarker({ nodeId: 'n_2', integration: 'react', componentRef: 'c_2', propsRef: 'p_2' }),
+		].join('');
+
+		const graph = extractComponentGraph(html);
+		expect([...graph.nodes.keys()]).toEqual(['n_1', 'n_2']);
+		expect(graph.levels).toEqual([['n_1', 'n_2']]);
+	});
+
+	it('builds parent child edges from slot registry', () => {
+		const html = [
+			createComponentMarker({
+				nodeId: 'n_1',
+				integration: 'lit',
+				componentRef: 'c_1',
+				propsRef: 'p_1',
+				slotRef: 's_1',
+			}),
+			createComponentMarker({ nodeId: 'n_2', integration: 'react', componentRef: 'c_2', propsRef: 'p_2' }),
+		].join('');
+
+		const graph = extractComponentGraph(html, {
+			s_1: ['n_2'],
+		});
+
+		expect(graph.edges.get('n_1')).toEqual(new Set(['n_2']));
+		expect(graph.reverseEdges.get('n_2')).toEqual(new Set(['n_1']));
+		expect(graph.levels).toEqual([['n_1'], ['n_2']]);
+	});
+
+	it('throws when slot links create cycles', () => {
+		const html = [
+			createComponentMarker({
+				nodeId: 'n_1',
+				integration: 'lit',
+				componentRef: 'c_1',
+				propsRef: 'p_1',
+				slotRef: 's_1',
+			}),
+			createComponentMarker({
+				nodeId: 'n_2',
+				integration: 'react',
+				componentRef: 'c_2',
+				propsRef: 'p_2',
+				slotRef: 's_2',
+			}),
+		].join('');
+
+		expect(() =>
+			extractComponentGraph(html, {
+				s_1: ['n_2'],
+				s_2: ['n_1'],
+			}),
+		).toThrow('Component marker graph contains a cycle');
+	});
+});