@ecopages/core 0.2.0-alpha.26 → 0.2.0-alpha.27

package/src/adapters/shared/hmr-manager.dispatch.test.ts

@@ -0,0 +1,220 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, describe, test } from 'vitest';
+import { ConfigBuilder } from '../../config/config-builder.ts';
+import { HmrStrategy, HmrStrategyType, type HmrAction } from '../../hmr/hmr-strategy.ts';
+import type { ClientBridgeEvent } from '../../types/public-types.ts';
+import { HmrManager as BunHmrManager } from '../bun/hmr-manager.ts';
+import { NodeHmrManager } from '../node/node-hmr-manager.ts';
+
+class FakeHmrStrategy extends HmrStrategy {
+	readonly type: HmrStrategyType;
+	private readonly _matches: (filePath: string) => boolean;
+	private readonly _action: HmrAction;
+
+	constructor(type: HmrStrategyType, matchFn: (f: string) => boolean, action: HmrAction) {
+		super();
+		this.type = type;
+		this._matches = matchFn;
+		this._action = action;
+	}
+
+	matches(filePath: string): boolean {
+		return this._matches(filePath);
+	}
+
+	async process(_filePath: string): Promise<HmrAction> {
+		return this._action;
+	}
+}
+
+type BridgeSpy = {
+	broadcasts: ClientBridgeEvent[];
+	bridge: {
+		subscriberCount: number;
+		broadcast(event: ClientBridgeEvent): void;
+		subscribe(): void;
+		unsubscribe(): void;
+	};
+};
+
+function createBridgeSpy(): BridgeSpy {
+	const broadcasts: ClientBridgeEvent[] = [];
+	const bridge = {
+		subscriberCount: 0,
+		broadcast(event: ClientBridgeEvent) {
+			broadcasts.push(event);
+		},
+		subscribe() {},
+		unsubscribe() {},
+	};
+	return { broadcasts, bridge };
+}
+
+const tempRoots: string[] = [];
+
+function createTempRoot(prefix: string): string {
+	const root = fs.mkdtempSync(path.join(os.tmpdir(), `${prefix}-`));
+	tempRoots.push(root);
+	return root;
+}
+
+afterEach(() => {
+	for (const root of tempRoots.splice(0)) {
+		fs.rmSync(root, { recursive: true, force: true });
+	}
+});
+
+const runtimes = [
+	{
+		name: 'node',
+		async create(rootDir: string, bridgeSpy: BridgeSpy) {
+			const config = await new ConfigBuilder().setRootDir(rootDir).build();
+			return new NodeHmrManager({ appConfig: config, bridge: bridgeSpy.bridge as any });
+		},
+	},
+	{
+		name: 'bun',
+		async create(rootDir: string, bridgeSpy: BridgeSpy) {
+			const config = await new ConfigBuilder().setRootDir(rootDir).build();
+			return new BunHmrManager({ appConfig: config, bridge: bridgeSpy.bridge as any });
+		},
+	},
+] as const;
+
+describe.each(runtimes)('handleFileChange dispatch: $name', ({ create }) => {
+	test('CSS file change routes to DefaultHmrStrategy and broadcasts reload', async () => {
+		const rootDir = createTempRoot('ecopages-dispatch-css');
+		fs.mkdirSync(path.join(rootDir, 'src'), { recursive: true });
+		const spy = createBridgeSpy();
+		const manager = await create(rootDir, spy);
+
+		const cssFile = path.join(rootDir, 'src', 'styles', 'main.css');
+		await manager.handleFileChange(cssFile);
+
+		assert.equal(spy.broadcasts.length, 1);
+		assert.equal(spy.broadcasts[0].type, 'reload');
+		assert.equal(spy.broadcasts[0].path, cssFile);
+
+		manager.stop();
+	});
+
+	test('HTML file change routes to DefaultHmrStrategy and broadcasts reload', async () => {
+		const rootDir = createTempRoot('ecopages-dispatch-html');
+		fs.mkdirSync(path.join(rootDir, 'src'), { recursive: true });
+		const spy = createBridgeSpy();
+		const manager = await create(rootDir, spy);
+
+		const htmlFile = path.join(rootDir, 'src', 'pages', 'index.html');
+		await manager.handleFileChange(htmlFile);
+
+		assert.equal(spy.broadcasts.length, 1);
+		assert.equal(spy.broadcasts[0].type, 'reload');
+		assert.equal(spy.broadcasts[0].path, htmlFile);
+
+		manager.stop();
+	});
+
+	test('TS file with no registered entrypoints falls back to DefaultHmrStrategy reload', async () => {
+		const rootDir = createTempRoot('ecopages-dispatch-ts-fallback');
+		const srcDir = path.join(rootDir, 'src');
+		fs.mkdirSync(srcDir, { recursive: true });
+		const spy = createBridgeSpy();
+		const manager = await create(rootDir, spy);
+
+		const tsFile = path.join(srcDir, 'component.ts');
+		await manager.handleFileChange(tsFile);
+
+		assert.equal(spy.broadcasts.length, 1);
+		assert.equal(spy.broadcasts[0].type, 'reload');
+
+		manager.stop();
+	});
+
+	test('broadcast:false suppresses events even when the strategy returns a broadcast action', async () => {
+		const rootDir = createTempRoot('ecopages-dispatch-no-broadcast');
+		fs.mkdirSync(path.join(rootDir, 'src'), { recursive: true });
+		const spy = createBridgeSpy();
+		const manager = await create(rootDir, spy);
+
+		const cssFile = path.join(rootDir, 'src', 'main.css');
+		await manager.handleFileChange(cssFile, { broadcast: false });
+
+		assert.equal(spy.broadcasts.length, 0);
+
+		manager.stop();
+	});
+
+	test('INTEGRATION strategy wins over DefaultHmrStrategy for matched files', async () => {
+		const rootDir = createTempRoot('ecopages-dispatch-integration-priority');
+		fs.mkdirSync(path.join(rootDir, 'src'), { recursive: true });
+		const spy = createBridgeSpy();
+		const manager = await create(rootDir, spy);
+
+		const customFile = path.join(rootDir, 'src', 'component.jsx');
+		const integrationEvent: ClientBridgeEvent = {
+			type: 'update',
+			path: '/assets/_hmr/component.js',
+			timestamp: 1,
+		};
+		manager.registerStrategy(
+			new FakeHmrStrategy(HmrStrategyType.INTEGRATION, (f) => f === customFile, {
+				type: 'broadcast',
+				events: [integrationEvent],
+			}),
+		);
+
+		await manager.handleFileChange(customFile);
+
+		assert.equal(spy.broadcasts.length, 1);
+		assert.deepEqual(spy.broadcasts[0], integrationEvent);
+
+		manager.stop();
+	});
+
+	test('action.type none suppresses broadcast even when shouldBroadcast is true', async () => {
+		const rootDir = createTempRoot('ecopages-dispatch-none-action');
+		fs.mkdirSync(path.join(rootDir, 'src'), { recursive: true });
+		const spy = createBridgeSpy();
+		const manager = await create(rootDir, spy);
+
+		const customFile = path.join(rootDir, 'src', 'silent.ts');
+		manager.registerStrategy(
+			new FakeHmrStrategy(HmrStrategyType.INTEGRATION, (f) => f === customFile, { type: 'none' }),
+		);
+
+		await manager.handleFileChange(customFile);
+
+		assert.equal(spy.broadcasts.length, 0);
+
+		manager.stop();
+	});
+
+	test('all events returned by a strategy are each broadcast individually', async () => {
+		const rootDir = createTempRoot('ecopages-dispatch-multi-event');
+		fs.mkdirSync(path.join(rootDir, 'src'), { recursive: true });
+		const spy = createBridgeSpy();
+		const manager = await create(rootDir, spy);
+
+		const customFile = path.join(rootDir, 'src', 'multi.ts');
+		const events: ClientBridgeEvent[] = [
+			{ type: 'update', path: '/assets/_hmr/a.js', timestamp: 1 },
+			{ type: 'update', path: '/assets/_hmr/b.js', timestamp: 2 },
+		];
+		manager.registerStrategy(
+			new FakeHmrStrategy(HmrStrategyType.INTEGRATION, (f) => f === customFile, {
+				type: 'broadcast',
+				events,
+			}),
+		);
+
+		await manager.handleFileChange(customFile);
+
+		assert.equal(spy.broadcasts.length, 2);
+		assert.deepEqual(spy.broadcasts, events);
+
+		manager.stop();
+	});
+});

package/src/adapters/shared/render-context.test.ts

@@ -0,0 +1,150 @@
+import { describe, it, expect, vi } from 'vitest';
+import { createRenderContext } from './render-context.ts';
+import type { IntegrationPlugin } from '../../plugins/integration-plugin.ts';
+import type { IntegrationRenderer } from '../../route-renderer/orchestration/integration-renderer.ts';
+import type { EcoFunctionComponent } from '../../types/public-types.ts';
+
+describe('createRenderContext', () => {
+	const RenderToResponse = vi.fn(() => Promise.resolve(new Response('rendered')));
+	const rendererModules = {
+		integrationManifestModuleId: 'virtual:ecopages/integration-manifest.ts',
+	};
+
+	const Renderer = {
+		name: '-renderer',
+		renderToResponse: RenderToResponse,
+	} as unknown as IntegrationRenderer;
+
+	const ExplicitRenderer = {
+		name: 'explicit-renderer',
+		renderToResponse: RenderToResponse,
+	} as unknown as IntegrationRenderer;
+
+	const InitializeRenderer = vi.fn(() => Renderer);
+
+	const Plugin = {
+		name: '-integration',
+		initializeRenderer: InitializeRenderer,
+	} as unknown as IntegrationPlugin;
+
+	const ExplicitInitializeRenderer = vi.fn(() => ExplicitRenderer);
+
+	const ExplicitPlugin = {
+		name: 'explicit-renderer',
+		initializeRenderer: ExplicitInitializeRenderer,
+	} as unknown as IntegrationPlugin;
+
+	const ViewFn = ((props: { foo: string }) => `<div>${props.foo}</div>`) as EcoFunctionComponent<
+		{ foo: string },
+		string
+	>;
+	ViewFn.config = {
+		__eco: {
+			id: 'test',
+			file: '/some/dir/-view.ts',
+			integration: '-integration',
+		},
+	};
+
+	const renderContext = createRenderContext({
+		integrations: [Plugin, ExplicitPlugin],
+		rendererModules,
+	});
+
+	it('should create a render context with methods', () => {
+		expect(renderContext.render).toBeDefined();
+		expect(renderContext.renderPartial).toBeDefined();
+		expect(renderContext.json).toBeDefined();
+		expect(renderContext.html).toBeDefined();
+	});
+
+	describe('render', () => {
+		it('should call renderer.renderToResponse with partial: false', async () => {
+			RenderToResponse.mockClear();
+			InitializeRenderer.mockClear();
+			ExplicitInitializeRenderer.mockClear();
+			const props = { foo: 'bar' };
+			const options = { status: 201, headers: { 'X-Custom': '1' } };
+
+			const response = await renderContext.render(ViewFn, props, options);
+
+			expect(InitializeRenderer).toHaveBeenCalledWith({ rendererModules });
+			expect(RenderToResponse).toHaveBeenCalledWith(ViewFn, props, {
+				partial: false,
+				status: 201,
+				headers: { 'X-Custom': '1' },
+			});
+			expect(response instanceof Response).toBe(true);
+		});
+
+		it('should throw if view integration is unknown', async () => {
+			const badViewFn = (() => '<div></div>') as EcoFunctionComponent<{}, string>;
+			badViewFn.config = { __eco: { id: 'test', file: '/bad-view.ts', integration: 'unknown' } };
+			await expect(renderContext.render(badViewFn, {})).rejects.toThrow('No integration found for: unknown');
+		});
+
+		it('should throw if view integration is missing', async () => {
+			const badViewFn = (() => '<div></div>') as EcoFunctionComponent<{}, string>;
+			badViewFn.config = { __eco: undefined };
+			await expect(renderContext.render(badViewFn, {})).rejects.toThrow('Cannot determine integration for view');
+		});
+
+		it('should prefer explicit config.integration over injected metadata', async () => {
+			RenderToResponse.mockClear();
+			InitializeRenderer.mockClear();
+			ExplicitInitializeRenderer.mockClear();
+
+			const explicitViewFn = (() => '<div></div>') as EcoFunctionComponent<{}, string>;
+			explicitViewFn.config = {
+				integration: 'explicit-renderer',
+				__eco: { id: 'test', file: '/some/file.tsx', integration: '-integration' },
+			};
+
+			await renderContext.render(explicitViewFn, {});
+
+			expect(ExplicitInitializeRenderer).toHaveBeenCalled();
+			expect(InitializeRenderer).not.toHaveBeenCalled();
+		});
+	});
+
+	describe('renderPartial', () => {
+		it('should call renderer.renderToResponse with partial: true', async () => {
+			RenderToResponse.mockClear();
+			const props = { foo: 'bar' };
+			const options = { status: 200 };
+
+			await renderContext.renderPartial(ViewFn, props, options);
+
+			expect(InitializeRenderer).toHaveBeenCalled();
+			expect(RenderToResponse).toHaveBeenCalledWith(ViewFn, props, {
+				partial: true,
+				status: 200,
+				headers: undefined,
+			});
+		});
+	});
+
+	describe('json', () => {
+		it('should return a JSON response', async () => {
+			const data = { hello: 'world' };
+			const response = renderContext.json(data);
+			expect(response.headers.get('Content-Type')).toContain('application/json');
+			expect(await response.json()).toEqual(data);
+		});
+
+		it('should support custom status and headers', async () => {
+			const response = renderContext.json({}, { status: 201, headers: { 'X-Test': 'true' } });
+			expect(response.status).toBe(201);
+			expect(response.headers.get('X-Test')).toBe('true');
+		});
+	});
+
+	describe('html', () => {
+		it('should return an HTML response', async () => {
+			const html = '<div>hello</div>';
+			const response = renderContext.html(html);
+			expect(response.headers.get('Content-Type')).toContain('text/html');
+			expect(await response.text()).toBe(html);
+		});
+	});
+});

package/src/adapters/shared/render-context.ts

@@ -0,0 +1,123 @@
+import type { EcoComponent, RenderContext, RenderOptions, ResponseOptions } from '../../types/public-types.ts';
+import type {
+	IntegrationRenderer,
+	RenderToResponseContext,
+} from '../../route-renderer/orchestration/integration-renderer.ts';
+import type { AnyIntegrationPlugin } from '../../plugins/integration-plugin.ts';
+import { invariant } from '../../utils/invariant.ts';
+
+export interface CreateRenderContextOptions {
+	integrations: AnyIntegrationPlugin[];
+	rendererModules?: unknown;
+}
+
+/**
+ * Merges request locals into component props as a dedicated 'locals' property.
+ * This prevents naming conflicts and maintains type safety by keeping locals
+ * separate from other props.
+ *
+ * @param props - The original component props
+ * @param locals - Optional request-scoped locals from middleware
+ * @returns Props with locals merged in, or original props if no locals provided
+ */
+function mergePropsWithLocals<P>(props: P, locals: Record<string, unknown> | undefined): P {
+	if (!locals || typeof props !== 'object' || props === null) {
+		return props;
+	}
+	return { ...(props as Record<string, unknown>), locals } as P;
+}
+
+/**
+ * Creates a render context for route handlers.
+ * Provides render(), renderPartial(), json(), and html() methods that can be used
+ * within route handlers to generate responses.
+ *
+ * @param options - Configuration options including available integrations
+ * @returns A RenderContext object with methods for rendering views and creating responses
+ */
+export function createRenderContext(options: CreateRenderContextOptions): RenderContext {
+	const { integrations } = options;
+
+	/**
+	 * Resolves the appropriate renderer for a given view component based on its integration.
+	 * Throws an error if the integration cannot be determined or is not found.
+	 */
+	const getRendererForView = <P>(view: EcoComponent<P>): IntegrationRenderer => {
+		const integrationName = view.config?.integration ?? view.config?.__eco?.integration;
+		invariant(
+			!!integrationName,
+			'Cannot determine integration for view. Set view.config.integration explicitly or ensure the view is defined with eco.page() in a file with a recognized extension.',
+		);
+
+		const integration = integrations.find((i) => i.name === integrationName);
+		invariant(!!integration, `No integration found for: ${integrationName}`);
+
+		return integration.initializeRenderer({
+			rendererModules: options.rendererModules,
+		}) as IntegrationRenderer;
+	};
+
+	const renderContext: RenderContext = {
+		async render<P>(
+			this: { locals?: Record<string, unknown> } | undefined,
+			view: EcoComponent<P>,
+			props?: P,
+			renderOptions?: RenderOptions,
+		): Promise<Response> {
+			const locals = (this as { locals?: Record<string, unknown> } | undefined)?.locals;
+			const mergedProps = mergePropsWithLocals<P>(props ?? ({} as P), locals);
+
+			const renderer = getRendererForView(view);
+			const ctx: RenderToResponseContext = {
+				partial: false,
+				status: renderOptions?.status,
+				headers: renderOptions?.headers,
+			};
+			return renderer.renderToResponse(view, mergedProps, ctx);
+		},
+
+		async renderPartial<P>(
+			this: { locals?: Record<string, unknown> } | undefined,
+			view: EcoComponent<P>,
+			props: P,
+			renderOptions?: RenderOptions,
+		): Promise<Response> {
+			const locals = (this as { locals?: Record<string, unknown> } | undefined)?.locals;
+			const mergedProps = mergePropsWithLocals<P>(props, locals);
+
+			const renderer = getRendererForView(view);
+			const ctx: RenderToResponseContext = {
+				partial: true,
+				status: renderOptions?.status,
+				headers: renderOptions?.headers,
+			};
+			return renderer.renderToResponse(view, mergedProps, ctx);
+		},
+
+		json(data: unknown, responseOptions?: ResponseOptions): Response {
+			const headers = new Headers({ 'Content-Type': 'application/json; charset=utf-8' });
+			if (responseOptions?.headers) {
+				const incomingHeaders = new Headers(responseOptions.headers);
+				incomingHeaders.forEach((value, key) => headers.set(key, value));
+			}
+			return new Response(JSON.stringify(data), {
+				status: responseOptions?.status ?? 200,
+				headers,
+			});
+		},
+
+		html(content: string, responseOptions?: ResponseOptions): Response {
+			const headers = new Headers({ 'Content-Type': 'text/html; charset=utf-8' });
+			if (responseOptions?.headers) {
+				const incomingHeaders = new Headers(responseOptions.headers);
+				incomingHeaders.forEach((value, key) => headers.set(key, value));
+			}
+			return new Response(content, {
+				status: responseOptions?.status ?? 200,
+				headers,
+			});
+		},
+	};
+
+	return renderContext;
+}

package/src/adapters/shared/runtime-bootstrap.ts

@@ -0,0 +1,79 @@
+import path from 'node:path';
+import { fileSystem } from '@ecopages/file-system';
+import { getAppBrowserBuildPlugins, setupAppRuntimePlugins, type BuildExecutor } from '../../build/build-adapter.ts';
+import type { EcoBuildPlugin } from '../../build/build-types.ts';
+import { installAppRuntimeBuildExecutor } from '../../build/runtime-build-executor.ts';
+import { RESOLVED_ASSETS_DIR } from '../../config/constants.ts';
+import type { EcoPagesAppConfig, IClientBridge, IHmrManager } from '../../types/internal-types.ts';
+import { ProjectWatcher } from '../../watchers/project-watcher.ts';
+
+/**
+ * Installs and returns the app-owned runtime build executor used by adapter
+ * startup and follow-up runtime work.
+ */
+export function installSharedRuntimeBuildExecutor(
+	appConfig: EcoPagesAppConfig,
+	options: { development: boolean },
+): BuildExecutor {
+	return installAppRuntimeBuildExecutor(appConfig, options);
+}
+
+/**
+ * Copies app public assets into dist and ensures the resolved assets directory
+ * exists before request handling begins.
+ */
+export function prepareSharedRuntimePublicDir(appConfig: EcoPagesAppConfig): void {
+	const srcPublicDir = path.join(appConfig.rootDir, appConfig.srcDir, appConfig.publicDir);
+
+	if (fileSystem.exists(srcPublicDir)) {
+		fileSystem.copyDir(srcPublicDir, path.join(appConfig.rootDir, appConfig.distDir));
+	}
+
+	fileSystem.ensureDir(path.join(appConfig.absolutePaths.distDir, RESOLVED_ASSETS_DIR));
+}
+
+/**
+ * Runs runtime plugin setup against app-owned config/runtime state and optional
+ * host plugin registration hooks.
+ */
+export async function initializeSharedRuntimePlugins(options: {
+	appConfig: EcoPagesAppConfig;
+	runtimeOrigin: string;
+	hmrManager?: IHmrManager;
+	onRuntimePlugin?: (plugin: unknown) => void;
+}): Promise<void> {
+	await setupAppRuntimePlugins(options);
+}
+
+/**
+ * Starts shared project watching for runtime adapters.
+ */
+export async function startSharedProjectWatching(options: {
+	appConfig: EcoPagesAppConfig;
+	refreshRouterRoutesCallback: () => Promise<void>;
+	hmrManager: IHmrManager;
+	bridge: IClientBridge;
+}): Promise<void> {
+	const watcher = new ProjectWatcher({
+		config: options.appConfig,
+		refreshRouterRoutesCallback: options.refreshRouterRoutesCallback,
+		hmrManager: options.hmrManager,
+		bridge: options.bridge,
+	});
+
+	await watcher.createWatcherSubscription();
+}
+
+/**
+ * Binds a runtime HMR manager to app-owned plugin and integration state.
+ */
+export function bindSharedRuntimeHmrManager(appConfig: EcoPagesAppConfig, hmrManager: IHmrManager): EcoBuildPlugin[] {
+	const browserBuildPlugins = getAppBrowserBuildPlugins(appConfig);
+	hmrManager.setPlugins(browserBuildPlugins);
+
+	for (const integration of appConfig.integrations) {
+		integration.setHmrManager(hmrManager);
+	}
+
+	return browserBuildPlugins;
+}

package/src/adapters/shared/server-adapter.test.ts

@@ -0,0 +1,130 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { afterEach, test } from 'vitest';
+import { ConfigBuilder } from '../../config/config-builder.ts';
+import type { ServerAdapterResult } from '../abstract/server-adapter.ts';
+import type { ApiHandler } from '../../types/public-types.ts';
+import { SharedServerAdapter } from './server-adapter.ts';
+
+const tempRoots: string[] = [];
+
+function createTempRoot(prefix: string): string {
+	const root = fs.mkdtempSync(path.join(os.tmpdir(), `${prefix}-`));
+	tempRoots.push(root);
+	return root;
+}
+
+afterEach(() => {
+	for (const root of tempRoots.splice(0)) {
+		fs.rmSync(root, { recursive: true, force: true });
+	}
+});
+
+class TestSharedServerAdapter extends SharedServerAdapter<any, ServerAdapterResult> {
+	public async initialize(): Promise<void> {}
+	public getServerOptions(): Record<string, never> {
+		return {};
+	}
+	public async buildStatic(): Promise<void> {}
+	public async createAdapter(): Promise<ServerAdapterResult> {
+		return {
+			getServerOptions: () => ({}),
+			buildStatic: async () => {},
+		};
+	}
+	public async handleRequest(request: Request): Promise<Response> {
+		return await this.handleSharedRequest(request, {
+			apiHandlers: [],
+			hmrManager: {
+				getRuntimePath: () => '',
+				getDistDir: () => this.hmrDir,
+			},
+		});
+	}
+
+	public async handleSharedRequestForTest(request: Request, apiHandlers: ApiHandler[]): Promise<Response> {
+		return await this.handleSharedRequest(request, {
+			apiHandlers,
+		});
+	}
+
+	public setRouteHandlerForTest(handleResponse: (request: Request) => Promise<Response>): void {
+		this.routeHandler = {
+			handleResponse,
+		} as any;
+	}
+
+	constructor(
+		private readonly hmrDir: string,
+		rootDir: string,
+	) {
+		super({
+			appConfig: { rootDir } as any,
+			runtimeOrigin: 'http://localhost:3000',
+			serveOptions: {},
+			options: {},
+		});
+	}
+}
+
+test('SharedServerAdapter serves /assets/_hmr files from the HMR manager directory', async () => {
+	const rootDir = createTempRoot('ecopages-shared-server-hmr-assets');
+	const config = await new ConfigBuilder().setRootDir(rootDir).build();
+	const hmrDir = path.join(config.absolutePaths.workDir, 'assets', '_hmr');
+	const assetPath = path.join(hmrDir, 'pages', 'react-content.js');
+	fs.mkdirSync(path.dirname(assetPath), { recursive: true });
+	fs.writeFileSync(assetPath, 'export default 1;', 'utf8');
+
+	const adapter = new TestSharedServerAdapter(hmrDir, rootDir);
+	const response = await adapter.handleRequest(new Request('http://localhost/assets/_hmr/pages/react-content.js'));
+
+	assert.equal(response.status, 200);
+	assert.equal(response.headers.get('Content-Type'), 'application/javascript');
+	assert.equal(await response.text(), 'export default 1;');
+	assert.equal(
+		fs.existsSync(path.join(config.absolutePaths.distDir, 'assets', '_hmr', 'pages', 'react-content.js')),
+		false,
+	);
+});
+
+test('SharedServerAdapter dispatches matching API handlers before filesystem routes', async () => {
+	const rootDir = createTempRoot('ecopages-shared-server-api-dispatch');
+	const adapter = new TestSharedServerAdapter('', rootDir);
+	adapter.setRouteHandlerForTest(async () => new Response('filesystem'));
+
+	const response = await adapter.handleSharedRequestForTest(
+		new Request('http://localhost/api/posts/123', { method: 'GET' }),
+		[
+			{
+				path: '/api/posts/[id]',
+				method: 'GET',
+				handler: ({ params }) => new Response(`api:${params.id}`),
+			},
+		],
+	);
+
+	assert.equal(response.status, 200);
+	assert.equal(await response.text(), 'api:123');
+});
+
+test('SharedServerAdapter falls back to the route handler when no API handler matches', async () => {
+	const rootDir = createTempRoot('ecopages-shared-server-route-fallback');
+	const adapter = new TestSharedServerAdapter('', rootDir);
+	adapter.setRouteHandlerForTest(async () => new Response('filesystem'));
+
+	const response = await adapter.handleSharedRequestForTest(
+		new Request('http://localhost/blog/post-1', { method: 'GET' }),
+		[
+			{
+				path: '/api/posts/[id]',
+				method: 'GET',
+				handler: () => new Response('api'),
+			},
+		],
+	);
+
+	assert.equal(response.status, 200);
+	assert.equal(await response.text(), 'filesystem');
+});