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

package/src/eco/eco.ts

@@ -5,6 +5,8 @@
 
 import type {
 	EcoComponent,
+	EcoHtmlComponent,
+	EcoLayoutComponent,
 	EcoPagesElement,
 	EcoPageComponent,
 	GetMetadata,
@@ -18,6 +20,8 @@ import type { CacheStrategy } from '../services/cache/cache.types.ts';
 import type {
 	ComponentOptions,
 	Eco,
+	HtmlOptions,
+	LayoutOptions,
 	PageOptions,
 	PageOptionsBase,
 	PagePropsFor,
@@ -25,7 +29,8 @@ import type {
 	PageRequires,
 } from './eco.types.ts';
 import { createNodeId, createPropsRef, createSlotRef, getComponentRenderContext } from './component-render-context.ts';
-import { createComponentMarker, parseComponentMarkers } from '../route-renderer/component-marker.ts';
+import { createComponentMarker, parseComponentMarkers } from '../route-renderer/component-graph/component-marker.ts';
+import { getComponentReference } from '../route-renderer/component-graph/component-reference.ts';
 import { addTriggerAttribute, isThenable, wrapWithScriptsInjector } from './eco.utils.ts';
 
 /**
@@ -57,13 +62,7 @@ function createComponentFactory<P, E>(options: ComponentOptions<P, E>): EcoCompo
 		if (shouldEmitMarker && renderContext) {
 			const nodeId = createNodeId(renderContext);
 			const propsRef = createPropsRef(renderContext);
-			const componentRef = comp.config?.__eco?.id ?? comp.config?.__eco?.file;
-
-			if (!componentRef) {
-				throw new Error(
-					'[ecopages] Missing component reference metadata for cross-integration marker emission.',
-				);
-			}
+			const componentRef = getComponentReference(comp);
 
 			const componentProps = (props ?? {}) as Record<string, unknown>;
 			renderContext.propsByRef[propsRef] = componentProps;
@@ -129,6 +128,26 @@ function component<P = {}, E = EcoPagesElement>(options: ComponentOptions<P, E>)
 	return createComponentFactory(options);
 }
 
+/**
+ * Creates a document shell component.
+ *
+ * Phase 1 keeps this as a semantic alias over eco.component() so existing
+ * renderer behavior remains unchanged.
+ */
+function html<E = EcoPagesElement>(options: HtmlOptions<E>): EcoHtmlComponent<E> {
+	return createComponentFactory(options) as EcoHtmlComponent<E>;
+}
+
+/**
+ * Creates a route layout component.
+ *
+ * Phase 1 keeps this as a semantic alias over eco.component() so existing
+ * renderer behavior remains unchanged.
+ */
+function layout<E = EcoPagesElement>(options: LayoutOptions<E>): EcoLayoutComponent<E> {
+	return createComponentFactory(options) as EcoLayoutComponent<E>;
+}
+
 /**
  * Creates a page component with typed props and optional static helpers.
  */
@@ -214,6 +233,8 @@ function staticProps<P>(fn: GetStaticProps<P>): GetStaticProps<P> {
  */
 export const eco: Eco = {
 	component,
+	html,
+	layout,
 	page,
 	metadata,
 	staticPaths,

package/src/eco/eco.types.ts

@@ -7,11 +7,16 @@ import type {
 	DependencyLazyTrigger,
 	EcoComponent,
 	EcoComponentDependencies,
+	EcoHtmlComponent,
 	EcoInjectedMeta,
+	EcoLayoutComponent,
+	EcoPageLayoutComponent,
 	EcoPagesElement,
 	GetMetadata,
 	GetStaticPaths,
 	GetStaticProps,
+	HtmlTemplateProps,
+	LayoutProps,
 	Middleware,
 	RequestLocals,
 	RequestPageContext,
@@ -45,6 +50,10 @@ export interface ComponentOptions<P, E = EcoPagesElement> {
 	render: (props: P) => E | Promise<E>;
 }
 
+export type HtmlOptions<E = EcoPagesElement> = ComponentOptions<HtmlTemplateProps, E>;
+
+export type LayoutOptions<E = EcoPagesElement> = ComponentOptions<LayoutProps<E>, E>;
+
 /**
  * Base options shared by all page variants
  */
@@ -53,7 +62,7 @@ export interface PageOptionsBase<T, E = EcoPagesElement> {
 	__eco?: EcoInjectedMeta;
 	integration?: string;
 	dependencies?: EcoComponentDependencies;
-	layout?: EcoComponent<{ children: E } & Partial<RequestPageContext>>;
+	layout?: EcoPageLayoutComponent<E>;
 
 	/**
 	 * Define static paths for dynamic routes (e.g., [slug].tsx).
@@ -169,6 +178,16 @@ export interface Eco {
 	 */
 	component: <P = {}, E = EcoPagesElement>(options: ComponentOptions<P, E>) => EcoComponent<P, E>;
 
+	/**
+	 * Create a document shell component for the HTML wrapper.
+	 */
+	html: <E = EcoPagesElement>(options: HtmlOptions<E>) => EcoHtmlComponent<E>;
+
+	/**
+	 * Create a route layout component.
+	 */
+	layout: <E = EcoPagesElement>(options: LayoutOptions<E>) => EcoLayoutComponent<E>;
+
 	/**
 	 * Create a page component with type-safe props from getStaticProps.
 	 * Returns an EcoPageComponent with attached staticPaths, staticProps, and metadata.

package/src/eco/eco.utils.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, test } from 'vitest';
+import { addTriggerAttribute, isThenable } from './eco.utils.ts';
+
+const TRIGGER_ID = 'eco-trigger-abc123';
+
+describe('addTriggerAttribute', () => {
+	describe('basic element injection', () => {
+		test('injects into a plain div', () => {
+			const result = addTriggerAttribute('<div>content</div>', TRIGGER_ID);
+			expect(result).toBe(`<div data-eco-trigger="${TRIGGER_ID}">content</div>`);
+		});
+
+		test('injects into a custom element', () => {
+			const result = addTriggerAttribute('<my-counter value="0"></my-counter>', TRIGGER_ID);
+			expect(result).toBe(`<my-counter data-eco-trigger="${TRIGGER_ID}" value="0"></my-counter>`);
+		});
+
+		test('injects into an element that already has attributes', () => {
+			const result = addTriggerAttribute('<div class="foo" id="bar">content</div>', TRIGGER_ID);
+			expect(result).toBe(`<div data-eco-trigger="${TRIGGER_ID}" class="foo" id="bar">content</div>`);
+		});
+
+		test('injects into a self-closing void element', () => {
+			const result = addTriggerAttribute('<img src="x.png" alt="" />', TRIGGER_ID);
+			expect(result).toBe(`<img data-eco-trigger="${TRIGGER_ID}" src="x.png" alt="" />`);
+		});
+
+		test('injects into an element with no attributes and immediate close', () => {
+			const result = addTriggerAttribute('<section></section>', TRIGGER_ID);
+			expect(result).toBe(`<section data-eco-trigger="${TRIGGER_ID}"></section>`);
+		});
+	});
+
+	describe('leading non-element nodes are skipped', () => {
+		test('skips leading whitespace and injects into the first element', () => {
+			const result = addTriggerAttribute('   \n  <div>content</div>', TRIGGER_ID);
+			expect(result).toBe(`   \n  <div data-eco-trigger="${TRIGGER_ID}">content</div>`);
+		});
+
+		test('skips a leading HTML comment', () => {
+			const result = addTriggerAttribute('<!-- wrapper --><div>content</div>', TRIGGER_ID);
+			expect(result).toBe(`<!-- wrapper --><div data-eco-trigger="${TRIGGER_ID}">content</div>`);
+		});
+
+		test('skips multiple leading HTML comments', () => {
+			const result = addTriggerAttribute('<!-- a --><!-- b --><span>text</span>', TRIGGER_ID);
+			expect(result).toBe(`<!-- a --><!-- b --><span data-eco-trigger="${TRIGGER_ID}">text</span>`);
+		});
+
+		test('skips a leading doctype declaration', () => {
+			const result = addTriggerAttribute('<!DOCTYPE html><html lang="en"></html>', TRIGGER_ID);
+			expect(result).toBe(`<!DOCTYPE html><html data-eco-trigger="${TRIGGER_ID}" lang="en"></html>`);
+		});
+
+		test('skips a leading XML processing instruction', () => {
+			const result = addTriggerAttribute('<?xml version="1.0"?><root/>', TRIGGER_ID);
+			expect(result).toBe(`<?xml version="1.0"?><root data-eco-trigger="${TRIGGER_ID}"/>`);
+		});
+
+		test('skips comment then whitespace then element', () => {
+			const result = addTriggerAttribute('<!-- note -->\n<article>body</article>', TRIGGER_ID);
+			expect(result).toBe(`<!-- note -->\n<article data-eco-trigger="${TRIGGER_ID}">body</article>`);
+		});
+	});
+
+	describe('only the first element is modified', () => {
+		test('does not inject into sibling elements', () => {
+			const result = addTriggerAttribute('<div>first</div><div>second</div>', TRIGGER_ID);
+			expect(result).toBe(`<div data-eco-trigger="${TRIGGER_ID}">first</div><div>second</div>`);
+		});
+	});
+
+	describe('fallback when no element is found', () => {
+		test('returns the original string unchanged when there is no opening tag', () => {
+			const input = 'just some text';
+			expect(addTriggerAttribute(input, TRIGGER_ID)).toBe(input);
+		});
+
+		test('returns the original string unchanged when input is empty', () => {
+			expect(addTriggerAttribute('', TRIGGER_ID)).toBe('');
+		});
+	});
+
+	describe('non-string input coercion', () => {
+		test('coerces a number to string before injecting', () => {
+			const result = addTriggerAttribute(42, TRIGGER_ID);
+			expect(result).toBe('42');
+		});
+
+		test('coerces null to the string "null"', () => {
+			expect(addTriggerAttribute(null, TRIGGER_ID)).toBe('null');
+		});
+	});
+});
+
+describe('isThenable', () => {
+	test('returns true for a native Promise', () => {
+		expect(isThenable(Promise.resolve())).toBe(true);
+	});
+
+	test('returns true for a plain object with a then function', () => {
+		expect(isThenable({ then: () => {} })).toBe(true);
+	});
+
+	test('returns false for a plain string', () => {
+		expect(isThenable('hello')).toBe(false);
+	});
+
+	test('returns false for a number', () => {
+		expect(isThenable(42)).toBe(false);
+	});
+
+	test('returns false for null', () => {
+		expect(isThenable(null)).toBe(false);
+	});
+
+	test('returns false for an object without then', () => {
+		expect(isThenable({ value: 1 })).toBe(false);
+	});
+
+	test('returns false when then is not a function', () => {
+		expect(isThenable({ then: 'not-a-function' })).toBe(false);
+	});
+});

package/src/eco/global-injector-map.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, test } from 'vitest';
+import { buildGlobalInjectorBootstrapContent, buildGlobalInjectorMapScript } from './global-injector-map.ts';
+import type { ResolvedLazyTrigger } from '../public-types.ts';
+
+describe('buildGlobalInjectorMapScript', () => {
+	test('builds merged map by trigger id and escapes script closing tags', () => {
+		const triggers: ResolvedLazyTrigger[] = [
+			{
+				triggerId: 'eco-trigger-one',
+				rules: [
+					{ 'on:interaction': { value: 'click', scripts: ['/a.js', '/b</script>.js'] } },
+					{ 'on:idle': { scripts: ['/idle.js'] } },
+				],
+			},
+			{
+				triggerId: 'eco-trigger-one',
+				rules: [{ 'on:interaction': { value: 'click', scripts: ['/a.js', '/c.js'] } }],
+			},
+		];
+
+		const payload = buildGlobalInjectorMapScript(triggers);
+		expect(payload).toContain('<\\/script>');
+
+		const map = JSON.parse(payload) as Record<string, Record<string, { scripts: string[]; value?: string }>>;
+		expect(map['eco-trigger-one']?.['on:idle']?.scripts).toEqual(['/idle.js']);
+		expect(map['eco-trigger-one']?.['on:interaction']).toEqual({
+			value: 'click',
+			scripts: ['/a.js', '/b</script>.js', '/c.js'],
+		});
+	});
+});
+
+describe('buildGlobalInjectorBootstrapContent', () => {
+	test('binds refresh to after-swap and avoids before-swap cleanup listener', () => {
+		const bootstrap = buildGlobalInjectorBootstrapContent('/assets/injector-global.js');
+
+		expect(bootstrap).toContain("document.addEventListener('eco:after-swap', handleAfterSwap);");
+		expect(bootstrap).not.toContain("document.addEventListener('eco:before-swap'");
+		expect(bootstrap).not.toContain('const handleBeforeSwap');
+		expect(bootstrap).toContain("document.removeEventListener('eco:after-swap', handleAfterSwap);");
+	});
+});

package/src/eco/lazy-injector-map.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, test } from 'vitest';
+import { buildInjectorMapScript } from './lazy-injector-map.ts';
+import type { InjectorMapConfig } from '@ecopages/scripts-injector/types';
+import type { ResolvedLazyScriptGroup } from '../public-types.ts';
+
+describe('buildInjectorMapScript', () => {
+	test('builds injector map for mixed lazy triggers', () => {
+		const lazyGroups: ResolvedLazyScriptGroup[] = [
+			{ lazy: { 'on:idle': true }, scripts: './idle-a.js, /idle-b.js' },
+			{ lazy: { 'on:interaction': 'click' }, scripts: './int-a.js' },
+			{ lazy: { 'on:visible': '0.5' }, scripts: '/vis-a.js' },
+		];
+
+		const result = buildInjectorMapScript(lazyGroups);
+		const map = JSON.parse(result) as InjectorMapConfig;
+
+		expect(map['on:idle']).toEqual({ scripts: ['/idle-a.js', '/idle-b.js'] });
+		expect(map['on:interaction']).toEqual({
+			value: 'click',
+			scripts: ['/int-a.js'],
+		});
+		expect(map['on:visible']).toEqual({
+			value: '0.5',
+			scripts: ['/vis-a.js'],
+		});
+	});
+
+	test('dedupes scripts and merges interaction events while preserving order', () => {
+		const lazyGroups: ResolvedLazyScriptGroup[] = [
+			{ lazy: { 'on:interaction': 'click,mouseenter' }, scripts: './one.js,./two.js' },
+			{ lazy: { 'on:interaction': 'mouseenter,focusin' }, scripts: '/two.js,/three.js' },
+		];
+
+		const result = buildInjectorMapScript(lazyGroups);
+		const map = JSON.parse(result) as InjectorMapConfig;
+
+		expect(map['on:interaction']).toEqual({
+			value: 'click,mouseenter,focusin',
+			scripts: ['/one.js', '/two.js', '/three.js'],
+		});
+	});
+
+	test('keeps existing on:visible threshold when a later boolean trigger is encountered', () => {
+		const lazyGroups: ResolvedLazyScriptGroup[] = [
+			{ lazy: { 'on:visible': '100px' }, scripts: './threshold.js' },
+			{ lazy: { 'on:visible': true }, scripts: './fallback.js' },
+		];
+
+		const result = buildInjectorMapScript(lazyGroups);
+		const map = JSON.parse(result) as InjectorMapConfig;
+
+		expect(map['on:visible']).toEqual({
+			value: '100px',
+			scripts: ['/threshold.js', '/fallback.js'],
+		});
+	});
+
+	test('escapes closing script tags in output payload', () => {
+		const lazyGroups: ResolvedLazyScriptGroup[] = [
+			{ lazy: { 'on:idle': true }, scripts: '/safe.js, /x</script>y.js' },
+		];
+
+		const result = buildInjectorMapScript(lazyGroups);
+		expect(result).toContain('<\\/script>');
+	});
+});

package/src/eco/module-dependencies.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, test } from 'vitest';
+import { normalizeModuleDeclarations, parseModuleDeclaration } from './module-dependencies.ts';
+
+describe('module dependencies parser', () => {
+	test('parses simple module declaration', () => {
+		expect(parseModuleDeclaration('react-aria-components')).toEqual({
+			from: 'react-aria-components',
+		});
+	});
+
+	test('parses declaration with named imports', () => {
+		expect(parseModuleDeclaration('react-aria-components{Table,Select}')).toEqual({
+			from: 'react-aria-components',
+			imports: ['Table', 'Select'],
+		});
+	});
+
+	test('normalizes and deduplicates module declarations', () => {
+		expect(
+			normalizeModuleDeclarations([
+				'react-aria-components{Table,Select}',
+				'react-aria-components{Table,Select}',
+				'lodash-es{debounce}',
+			]),
+		).toEqual([
+			{ from: 'react-aria-components', imports: ['Table', 'Select'] },
+			{ from: 'lodash-es', imports: ['debounce'] },
+		]);
+	});
+});

package/src/errors/http-error.test.ts

@@ -0,0 +1,134 @@
+import { describe, expect, test } from 'vitest';
+import { HttpError } from './http-error.ts';
+
+describe('HttpError', () => {
+	describe('constructor', () => {
+		test('creates error with status and message', () => {
+			const error = new HttpError(400, 'Bad request');
+
+			expect(error).toBeInstanceOf(Error);
+			expect(error).toBeInstanceOf(HttpError);
+			expect(error.status).toBe(400);
+			expect(error.message).toBe('Bad request');
+			expect(error.name).toBe('HttpError');
+			expect(error.details).toBeUndefined();
+		});
+
+		test('creates error with details', () => {
+			const details = { field: 'email', reason: 'invalid format' };
+			const error = new HttpError(400, 'Validation failed', details);
+
+			expect(error.details).toEqual(details);
+		});
+	});
+
+	describe('toJSON', () => {
+		test('serializes error without details', () => {
+			const error = new HttpError(404, 'Not found');
+
+			expect(error.toJSON()).toEqual({
+				error: 'Not found',
+				status: 404,
+			});
+		});
+
+		test('serializes error with details', () => {
+			const details = { body: [{ path: ['title'], message: 'Required' }] };
+			const error = new HttpError(400, 'Validation failed', details);
+
+			expect(error.toJSON()).toEqual({
+				error: 'Validation failed',
+				status: 400,
+				details,
+			});
+		});
+	});
+
+	describe('toResponse', () => {
+		test('creates Response with correct status and body', async () => {
+			const error = new HttpError(403, 'Access denied');
+			const response = error.toResponse();
+
+			expect(response).toBeInstanceOf(Response);
+			expect(response.status).toBe(403);
+			expect(response.headers.get('content-type')).toContain('application/json');
+
+			const body = await response.json();
+			expect(body).toEqual({ error: 'Access denied', status: 403 });
+		});
+	});
+
+	describe('factory methods', () => {
+		test('BadRequest creates 400 error', () => {
+			const error = HttpError.BadRequest();
+			expect(error.status).toBe(400);
+			expect(error.message).toBe('Bad Request');
+		});
+
+		test('BadRequest accepts custom message and details', () => {
+			const details = { field: 'name' };
+			const error = HttpError.BadRequest('Invalid input', details);
+
+			expect(error.message).toBe('Invalid input');
+			expect(error.details).toEqual(details);
+		});
+
+		test('Unauthorized creates 401 error', () => {
+			const error = HttpError.Unauthorized();
+			expect(error.status).toBe(401);
+			expect(error.message).toBe('Unauthorized');
+		});
+
+		test('Unauthorized accepts custom message', () => {
+			const error = HttpError.Unauthorized('Token expired');
+			expect(error.message).toBe('Token expired');
+		});
+
+		test('Forbidden creates 403 error', () => {
+			const error = HttpError.Forbidden();
+			expect(error.status).toBe(403);
+			expect(error.message).toBe('Forbidden');
+		});
+
+		test('Forbidden accepts custom message', () => {
+			const error = HttpError.Forbidden('Admin access required');
+			expect(error.message).toBe('Admin access required');
+		});
+
+		test('NotFound creates 404 error', () => {
+			const error = HttpError.NotFound();
+			expect(error.status).toBe(404);
+			expect(error.message).toBe('Not Found');
+		});
+
+		test('NotFound accepts custom message', () => {
+			const error = HttpError.NotFound('Post not found');
+			expect(error.message).toBe('Post not found');
+		});
+
+		test('Conflict creates 409 error', () => {
+			const error = HttpError.Conflict();
+			expect(error.status).toBe(409);
+			expect(error.message).toBe('Conflict');
+		});
+
+		test('Conflict accepts custom message and details', () => {
+			const details = { resource: 'user', conflict: 'email already exists' };
+			const error = HttpError.Conflict('Resource conflict', details);
+
+			expect(error.message).toBe('Resource conflict');
+			expect(error.details).toEqual(details);
+		});
+
+		test('InternalServerError creates 500 error', () => {
+			const error = HttpError.InternalServerError();
+			expect(error.status).toBe(500);
+			expect(error.message).toBe('Internal Server Error');
+		});
+
+		test('InternalServerError accepts custom message', () => {
+			const error = HttpError.InternalServerError('Database connection failed');
+			expect(error.message).toBe('Database connection failed');
+		});
+	});
+});

package/src/global/utils.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, test } from 'vitest';
+import { invariant } from '../utils/invariant.ts';
+
+describe('Utils', () => {
+	test('invariant should throw error when condition is falsy', () => {
+		expect(() => invariant(false, 'Test error')).toThrowError('[ecopages] Test error');
+	});
+
+	test('invariant should not throw error when condition is truthy', () => {
+		expect(() => invariant(true, 'Test error')).not.toThrow();
+	});
+});

package/src/hmr/README.md

@@ -0,0 +1,26 @@
+# HMR Layer
+
+This directory contains the framework-owned hot-update strategy contracts used by runtime adapters and integrations.
+
+## Purpose
+
+The HMR layer separates change classification from update execution.
+
+It is responsible for:
+
+- defining the shared HMR manager and strategy contracts
+- letting integrations contribute framework-specific update strategies
+- keeping adapter transports independent from update policy
+
+## How It Fits
+
+1. `ProjectWatcher` observes file changes.
+2. `DevelopmentInvalidationService` classifies the change.
+3. The active HMR manager selects a strategy.
+4. The strategy coordinates browser rebuilds, metadata reloads, and client broadcasts.
+
+## Design Rule
+
+Generic invalidation policy belongs in core services.
+Framework-specific update behavior belongs in HMR strategies.
+Runtime-specific WebSocket or event-stream transport belongs in adapters.

package/src/hmr/client/hmr-runtime.ts

@@ -3,6 +3,8 @@
  * Injected into the browser to handle Hot Module Replacement updates.
  */
 
+import { getEcoNavigationRuntime } from '../../router/client/navigation-coordinator.ts';
+
 interface HMRPayload {
 	type: 'reload' | 'error' | 'update' | 'css-update' | 'layout-update';
 	path?: string;
@@ -41,14 +43,16 @@ interface HMRPayload {
 	}
 
 	async function handleMessage(payload: HMRPayload) {
+		const navigationRuntime = getEcoNavigationRuntime(window);
+
 		switch (payload.type) {
 			case 'reload':
+				await waitForNavigationToSettle(navigationRuntime);
 				location.reload();
 				break;
 			case 'layout-update': {
-				const reloadFn = window.__ecopages_reload_current_page__;
-				if (typeof reloadFn === 'function') {
-					await reloadFn({ clearCache: true });
+				await waitForNavigationToSettle(navigationRuntime);
+				if (await navigationRuntime.reloadCurrentPage({ clearCache: true })) {
 				} else {
 					location.reload();
 				}
@@ -78,7 +82,9 @@ interface HMRPayload {
 	async function applyUpdate(path: string, timestamp?: number) {
 		try {
 			const url = path + '?t=' + (timestamp || Date.now());
-			const handlers = window.__ecopages_hmr_handlers__;
+			const handlers = window.__ECO_PAGES__?.hmrHandlers;
+			const navigationRuntime = getEcoNavigationRuntime(window);
+			await waitForNavigationToSettle(navigationRuntime);
 
 			if (handlers?.[path]) {
 				await handlers[path](url);
@@ -89,15 +95,40 @@ interface HMRPayload {
 
 			// If we're inside the EcoRouter, we need to trigger a router navigation to render the new component.
 			// Passing clearCache: false preserves the persisted layout cache.
-			const reloadFn = window.__ecopages_reload_current_page__;
-			if (typeof reloadFn === 'function') {
-				await reloadFn({ clearCache: false });
+			if (await navigationRuntime.reloadCurrentPage({ clearCache: false })) {
 			}
 		} catch (e) {
 			console.error('[ecopages] Failed to apply HMR update:', e);
 		}
 	}
 
+	async function waitForNavigationToSettle(navigationRuntime: ReturnType<typeof getEcoNavigationRuntime>) {
+		if (!navigationRuntime.hasPendingNavigationTransaction()) {
+			return;
+		}
+
+		await new Promise<void>((resolve) => {
+			const startedAt = performance.now();
+			const timeoutMs = 2000;
+
+			const poll = () => {
+				if (!navigationRuntime.hasPendingNavigationTransaction()) {
+					resolve();
+					return;
+				}
+
+				if (performance.now() - startedAt >= timeoutMs) {
+					resolve();
+					return;
+				}
+
+				requestAnimationFrame(poll);
+			};
+
+			requestAnimationFrame(poll);
+		});
+	}
+
 	/**
 	 * Hot-reload CSS by updating stylesheet link href with cache-busting query param.
 	 * This causes the browser to re-fetch the stylesheet without a full page reload.