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

package/src/services/assets/asset-processing-service/browser-runtime-asset.factory.test.ts

@@ -0,0 +1,74 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { test } from 'vitest';
+import {
+	BROWSER_RUNTIME_SCRIPT_ATTRIBUTES,
+	buildBrowserRuntimeAssetUrl,
+	createBrowserRuntimeModuleAsset,
+	createBrowserRuntimeScriptAsset,
+} from './browser-runtime-asset.factory.ts';
+
+test('buildBrowserRuntimeAssetUrl uses the vendors asset directory', () => {
+	assert.equal(buildBrowserRuntimeAssetUrl('react.js'), '/assets/vendors/react.js');
+});
+
+test('createBrowserRuntimeScriptAsset creates a hidden head runtime bundle asset', () => {
+	const plugin = { name: 'runtime-plugin', setup() {} };
+	const asset = createBrowserRuntimeScriptAsset({
+		importPath: '/tmp/react-entry.mjs',
+		name: 'react',
+		fileName: 'react.js',
+		bundleOptions: {
+			plugins: [plugin],
+		},
+	});
+
+	assert.deepEqual(asset, {
+		kind: 'script',
+		source: 'node-module',
+		position: 'head',
+		importPath: '/tmp/react-entry.mjs',
+		name: 'react',
+		packageRole: 'runtime',
+		excludeFromHtml: true,
+		bundleOptions: {
+			naming: 'react.js',
+			plugins: [plugin],
+		},
+		attributes: BROWSER_RUNTIME_SCRIPT_ATTRIBUTES,
+	});
+});
+
+test('createBrowserRuntimeModuleAsset creates an entry module and hidden runtime asset together', () => {
+	const rootDir = fs.mkdtempSync(path.join(os.tmpdir(), 'eco-browser-runtime-asset-'));
+	fs.writeFileSync(path.join(rootDir, 'package.json'), '{}', 'utf8');
+	fs.mkdirSync(path.join(rootDir, 'node_modules', 'runtime-a'), { recursive: true });
+	fs.writeFileSync(
+		path.join(rootDir, 'node_modules', 'runtime-a', 'index.js'),
+		"module.exports = { default: 'runtime-a', alpha: 'a' };",
+		'utf8',
+	);
+
+	try {
+		const asset = createBrowserRuntimeModuleAsset({
+			rootDir,
+			cacheDirName: 'ecopages-browser-runtime-test',
+			modules: [{ specifier: 'runtime-a', defaultExport: true }],
+			name: 'runtime-a',
+			fileName: 'runtime-a.js',
+		});
+
+		assert.equal(asset.source, 'node-module');
+		assert.equal(
+			asset.importPath.endsWith(path.join('ecopages-browser-runtime-test', 'runtime-a-entry.mjs')),
+			true,
+		);
+		assert.equal(asset.bundleOptions?.naming, 'runtime-a.js');
+		assert.equal(asset.excludeFromHtml, true);
+		assert.equal(asset.packageRole, 'runtime');
+	} finally {
+		fs.rmSync(rootDir, { recursive: true, force: true });
+	}
+});

package/src/services/assets/asset-processing-service/browser-runtime-asset.factory.ts

@@ -0,0 +1,96 @@
+import type { EcoBuildPlugin } from '../../../build/build-types.ts';
+import { AssetFactory } from './asset.factory.ts';
+import type { AssetDefinition } from './assets.types.ts';
+import {
+	createBrowserRuntimeEntryModule,
+	type BrowserRuntimeEntryModuleConfig,
+} from './browser-runtime-entry.factory.ts';
+
+export const BROWSER_RUNTIME_SCRIPT_ATTRIBUTES = {
+	type: 'module',
+	defer: '',
+} as const;
+
+/**
+ * Builds the public vendor URL used for generated browser runtime assets.
+ */
+export function buildBrowserRuntimeAssetUrl(fileName: string): string {
+	return `/${AssetFactory.RESOLVED_ASSETS_VENDORS_DIR}/${fileName}`;
+}
+
+/**
+ * Declares a browser runtime script asset backed by one importable module.
+ *
+ * @remarks
+ * Runtime assets are emitted as excluded head scripts because integrations often
+ * need the bundler output and specifier registration without injecting the raw
+ * asset directly into HTML during dependency resolution.
+ */
+export function createBrowserRuntimeScriptAsset(options: {
+	importPath: string;
+	name: string;
+	fileName: string;
+	bundleOptions?: {
+		define?: Record<string, string>;
+		minify?: boolean;
+		external?: string[];
+		naming?: string;
+		plugins?: EcoBuildPlugin[];
+	};
+	attributes?: Record<string, string>;
+}): AssetDefinition {
+	return AssetFactory.createNodeModuleScript({
+		position: 'head',
+		importPath: options.importPath,
+		name: options.name,
+		packageRole: 'runtime',
+		excludeFromHtml: true,
+		bundleOptions: {
+			naming: options.fileName,
+			...options.bundleOptions,
+		},
+		attributes: {
+			...BROWSER_RUNTIME_SCRIPT_ATTRIBUTES,
+			...(options.attributes ?? {}),
+		},
+	});
+}
+
+/**
+ * Creates a browser runtime asset from a generated re-export entry module.
+ *
+ * @remarks
+ * This is the shared "module list -> generated entry file -> runtime asset"
+ * path used by integrations that need browser-side runtime bundles without
+ * owning bespoke entry-file generation logic.
+ */
+export function createBrowserRuntimeModuleAsset(options: {
+	modules: BrowserRuntimeEntryModuleConfig[];
+	name: string;
+	fileName: string;
+	cacheDirName?: string;
+	rootDir?: string;
+	bundleOptions?: {
+		define?: Record<string, string>;
+		minify?: boolean;
+		external?: string[];
+		naming?: string;
+		plugins?: EcoBuildPlugin[];
+	};
+	attributes?: Record<string, string>;
+}): AssetDefinition {
+	const importPath = createBrowserRuntimeEntryModule({
+		modules: options.modules,
+		fileName: `${options.name}-entry.mjs`,
+		rootDir: options.rootDir,
+		cacheDirName: options.cacheDirName,
+	});
+
+	return createBrowserRuntimeScriptAsset({
+		importPath,
+		name: options.name,
+		fileName: options.fileName,
+		bundleOptions: options.bundleOptions,
+		attributes: options.attributes,
+	});
+}

package/src/services/assets/asset-processing-service/browser-runtime-entry.factory.test.ts

@@ -0,0 +1,67 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { tmpdir } from 'node:os';
+import { test } from 'vitest';
+import { createBrowserRuntimeEntryModule } from './browser-runtime-entry.factory.ts';
+
+test('createBrowserRuntimeEntryModule writes a shared runtime entry file', () => {
+	const rootDir = fs.mkdtempSync(path.join(tmpdir(), 'eco-browser-runtime-entry-'));
+	fs.writeFileSync(path.join(rootDir, 'package.json'), '{}', 'utf8');
+
+	try {
+		const filePath = createBrowserRuntimeEntryModule({
+			rootDir,
+			cacheDirName: 'ecopages-react-runtime-test',
+			fileName: 'runtime-entry.mjs',
+			modules: [{ specifier: 'node:path' }, { specifier: 'node:fs' }],
+		});
+
+		assert.equal(path.basename(filePath), 'runtime-entry.mjs');
+		assert.equal(
+			filePath,
+			path.join(rootDir, 'node_modules', '.cache', 'ecopages-react-runtime-test', 'runtime-entry.mjs'),
+		);
+
+		const contents = fs.readFileSync(filePath, 'utf8');
+		assert.match(contents, /export \{ .*basename.* \} from 'node:path';/);
+		assert.match(contents, /export \{ .*readFileSync.* \} from 'node:fs';/);
+	} finally {
+		fs.rmSync(rootDir, { recursive: true, force: true });
+	}
+});
+
+test('createBrowserRuntimeEntryModule preserves a default export and deduplicates named exports', () => {
+	const rootDir = fs.mkdtempSync(path.join(tmpdir(), 'eco-browser-runtime-entry-'));
+	fs.writeFileSync(path.join(rootDir, 'package.json'), '{}', 'utf8');
+	fs.mkdirSync(path.join(rootDir, 'node_modules', 'runtime-a'), { recursive: true });
+	fs.mkdirSync(path.join(rootDir, 'node_modules', 'runtime-b'), { recursive: true });
+	fs.writeFileSync(
+		path.join(rootDir, 'node_modules', 'runtime-a', 'index.js'),
+		"module.exports = { default: 'runtime-a', alpha: 'a', shared: 'shared-a' };",
+		'utf8',
+	);
+	fs.writeFileSync(
+		path.join(rootDir, 'node_modules', 'runtime-b', 'index.js'),
+		"module.exports = { beta: 'b', shared: 'shared-b' };",
+		'utf8',
+	);
+
+	try {
+		const filePath = createBrowserRuntimeEntryModule({
+			rootDir,
+			cacheDirName: 'ecopages-react-runtime-test',
+			fileName: 'runtime-entry.mjs',
+			modules: [{ specifier: 'runtime-a', defaultExport: true }, { specifier: 'runtime-b' }],
+		});
+
+		const contents = fs.readFileSync(filePath, 'utf8');
+		assert.match(contents, /import __ecopages_default_export__ from 'runtime-a';/);
+		assert.match(contents, /export default __ecopages_default_export__;/);
+		assert.match(contents, /export \{ alpha, shared \} from 'runtime-a';/);
+		assert.match(contents, /export \{ beta \} from 'runtime-b';/);
+		assert.doesNotMatch(contents, /export \{ .*shared.* \} from 'runtime-b';/);
+	} finally {
+		fs.rmSync(rootDir, { recursive: true, force: true });
+	}
+});

package/src/services/assets/asset-processing-service/browser-runtime-entry.factory.ts

@@ -0,0 +1,78 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+export type BrowserRuntimeEntryModuleConfig = {
+	specifier: string;
+	defaultExport?: boolean;
+};
+
+/**
+ * Creates a generated ESM entry module that re-exports runtime modules through
+ * one stable file.
+ *
+ * @remarks
+ * Integrations use this helper when they need a browser runtime asset composed
+ * from multiple bare specifiers but do not want to own temporary file assembly
+ * logic themselves. The generated file lives under a cache directory inside the
+ * consuming app root so repeated runs can reuse the same location.
+ */
+export function createBrowserRuntimeEntryModule(options: {
+	modules: BrowserRuntimeEntryModuleConfig[];
+	fileName: string;
+	rootDir?: string;
+	cacheDirName?: string;
+}): string {
+	const rootDir = options.rootDir ?? process.cwd();
+	const artifactsDir = path.join(
+		rootDir,
+		'node_modules',
+		'.cache',
+		options.cacheDirName ?? 'ecopages-browser-runtime',
+	);
+	fs.mkdirSync(artifactsDir, { recursive: true });
+
+	const requireFromRoot = createRequire(path.join(rootDir, 'package.json'));
+	const seenExports = new Set<string>();
+	const statements: string[] = [];
+
+	for (const module of options.modules) {
+		if (module.defaultExport) {
+			statements.push(`import __ecopages_default_export__ from '${module.specifier}';`);
+			statements.push('export default __ecopages_default_export__;');
+		}
+
+		const exportNames = getModuleExportNames(module.specifier, requireFromRoot).filter(
+			(name) => !seenExports.has(name),
+		);
+
+		if (exportNames.length > 0) {
+			statements.push(`export { ${exportNames.join(', ')} } from '${module.specifier}';`);
+			for (const exportName of exportNames) {
+				seenExports.add(exportName);
+			}
+		}
+	}
+
+	const filePath = path.join(artifactsDir, options.fileName);
+	fs.writeFileSync(filePath, statements.join('\n'), 'utf-8');
+	return filePath;
+}
+
+/**
+ * Reads the named runtime exports that should be re-exported from a generated
+ * runtime entry module.
+ *
+ * @remarks
+ * Default exports are handled separately because generated runtime entry files
+ * need to emit a synthetic default binding only when the caller explicitly asks
+ * for it.
+ */
+function getModuleExportNames(specifier: string, requireFromRoot: ReturnType<typeof createRequire>): string[] {
+	const moduleExports = requireFromRoot(specifier);
+
+	return Object.keys(moduleExports)
+		.filter((name) => name !== '__esModule' && name !== 'default')
+		.filter((name) => /^[$A-Z_a-z][$\w]*$/.test(name))
+		.sort();
+}

package/src/services/assets/asset-processing-service/grouped-content-bundles.ts

@@ -0,0 +1,104 @@
+import type { AssetDefinition, ProcessedAsset } from './assets.types.ts';
+
+/**
+ * Splits grouped content-script dependencies from ordinary dependencies so callers can
+ * route them through `processGrouped` without changing ordering for the remaining assets.
+ */
+export function partitionGroupedContentScriptDependencies(typeDeps: AssetDefinition[]): {
+	groupedBundleDeps: Map<string, AssetDefinition[]>;
+	ungroupedDeps: AssetDefinition[];
+} {
+	const groupedBundleDeps = new Map<string, AssetDefinition[]>();
+	const ungroupedDeps: AssetDefinition[] = [];
+
+	for (const dep of typeDeps) {
+		if (dep.kind === 'script' && dep.source === 'content' && dep.groupedBundle?.id) {
+			const existing = groupedBundleDeps.get(dep.groupedBundle.id) ?? [];
+			existing.push(dep);
+			groupedBundleDeps.set(dep.groupedBundle.id, existing);
+			continue;
+		}
+
+		ungroupedDeps.push(dep);
+	}
+
+	return {
+		groupedBundleDeps,
+		ungroupedDeps,
+	};
+}
+
+type GroupedBundleProcessor = {
+	processGrouped?: (deps: AssetDefinition[]) => Promise<ProcessedAsset[]>;
+};
+
+type ProcessGroupedDependencyBundlesOptions = {
+	bundles: AssetDefinition[][];
+	key: string;
+	getCachedAsset: (dep: AssetDefinition, depKey: string) => ProcessedAsset | null;
+	getDependencyKey: (dep: AssetDefinition) => string;
+	getGroupedProcessor: () => GroupedBundleProcessor | undefined;
+	resolveProcessedAssetSrcUrl: (processed: ProcessedAsset) => string | undefined;
+	setCachedAsset: (dep: AssetDefinition, depKey: string, processed: ProcessedAsset) => void;
+	logError: (error: unknown) => void;
+};
+
+/**
+ * Processes grouped content-script bundles while preserving per-entry cache keys.
+ *
+ * When every dependency in a bundle already has a cached processed asset, the cached
+ * entries are returned directly and the grouped processor is skipped.
+ */
+export async function processGroupedDependencyBundles(
+	options: ProcessGroupedDependencyBundlesOptions,
+): Promise<ProcessedAsset[]> {
+	const {
+		bundles,
+		key,
+		getCachedAsset,
+		getDependencyKey,
+		getGroupedProcessor,
+		resolveProcessedAssetSrcUrl,
+		setCachedAsset,
+		logError,
+	} = options;
+
+	const groupedPromises = bundles.map(async (bundleDeps) => {
+		const cachedResults = bundleDeps.map((dep) => {
+			const cached = getCachedAsset(dep, getDependencyKey(dep));
+			return cached ? ({ key, ...cached } as ProcessedAsset) : null;
+		});
+
+		if (cachedResults.every((result) => result !== null)) {
+			return cachedResults.filter((result): result is ProcessedAsset => result !== null);
+		}
+
+		const processor = getGroupedProcessor();
+		if (!processor?.processGrouped) {
+			return [];
+		}
+
+		try {
+			const processedResults = await processor.processGrouped(bundleDeps);
+
+			return processedResults.map((processed, index) => {
+				const dep = bundleDeps[index]!;
+				const depKey = getDependencyKey(dep);
+				const srcUrl = resolveProcessedAssetSrcUrl(processed);
+				const processedWithKey = {
+					key,
+					...processed,
+					srcUrl,
+				};
+
+				setCachedAsset(dep, depKey, processedWithKey);
+				return processedWithKey as ProcessedAsset;
+			});
+		} catch (error) {
+			logError(error);
+			return [];
+		}
+	});
+
+	return (await Promise.all(groupedPromises)).flat();
+}

package/src/services/assets/asset-processing-service/index.ts

@@ -0,0 +1,6 @@
+export * from './asset.factory.ts';
+export * from './page-package.ts';
+export * from './asset-processing.service.ts';
+export * from './assets.types.ts';
+export * from './browser-runtime-asset.factory.ts';
+export * from './browser-runtime-entry.factory.ts';

package/src/services/assets/asset-processing-service/page-package.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, it } from 'vitest';
+import type { ProcessedAsset } from './assets.types.ts';
+import { createPagePackage } from './page-package.ts';
+
+describe('createPagePackage', () => {
+	it('classifies page assets, inline assets, separate assets, and dynamic chunks', () => {
+		const pageScript = {
+			kind: 'script',
+			srcUrl: '/assets/page.js',
+			position: 'head',
+		} as ProcessedAsset;
+		const pageStylesheet = {
+			kind: 'stylesheet',
+			srcUrl: '/assets/page.css',
+			position: 'head',
+		} as ProcessedAsset;
+		const runtimeScript = {
+			kind: 'script',
+			srcUrl: '/assets/vendors/react.js',
+			position: 'head',
+			excludeFromHtml: true,
+			packageRole: 'runtime',
+		} as ProcessedAsset;
+		const inlineScript = {
+			kind: 'script',
+			content: 'console.log("inline")',
+			inline: true,
+			position: 'head',
+		} as ProcessedAsset;
+		const dynamicChunk = {
+			kind: 'script',
+			srcUrl: '/assets/chunks/page-chunk.js',
+			position: 'head',
+			packageRole: 'dynamic-chunk',
+		} as ProcessedAsset;
+
+		const result = createPagePackage([pageStylesheet, pageScript, runtimeScript, inlineScript, dynamicChunk]);
+
+		expect(result.pageScript).toBe(pageScript);
+		expect(result.pageStylesheet).toBe(pageStylesheet);
+		expect(result.htmlAssets).toEqual([pageStylesheet, pageScript, inlineScript, dynamicChunk]);
+		expect(result.inlineAssets).toEqual([inlineScript]);
+		expect(result.separateAssets).toEqual([runtimeScript]);
+		expect(result.dynamicChunks).toEqual([dynamicChunk]);
+	});
+
+	it('prefers explicit page roles over visibility heuristics', () => {
+		const hiddenPageScript = {
+			kind: 'script',
+			srcUrl: '/assets/pages/index.js',
+			position: 'head',
+			excludeFromHtml: true,
+			packageRole: 'page-script',
+		} as ProcessedAsset;
+		const hydrationBootstrap = {
+			kind: 'script',
+			srcUrl: '/assets/pages/index-hydration.js',
+			position: 'head',
+			packageRole: 'keep-separate',
+		} as ProcessedAsset;
+
+		const result = createPagePackage([hiddenPageScript, hydrationBootstrap]);
+
+		expect(result.pageScript).toBe(hiddenPageScript);
+		expect(result.htmlAssets).toEqual([hydrationBootstrap]);
+		expect(result.separateAssets).toEqual([hydrationBootstrap]);
+	});
+
+	it('suppresses bundled source stylesheet assets from final html assets', () => {
+		const pageStylesheet = {
+			kind: 'stylesheet',
+			srcUrl: '/assets/page.css',
+			position: 'head',
+			packageRole: 'page-style',
+			bundledSourceFilepaths: ['/app/src/styles/tailwind.css', '/app/src/styles/fonts.css'],
+		} as ProcessedAsset;
+		const bundledTailwind = {
+			kind: 'stylesheet',
+			srcUrl: '/assets/styles/tailwind.css',
+			position: 'head',
+			sourceFilepath: '/app/src/styles/tailwind.css',
+		} as ProcessedAsset;
+		const bundledFonts = {
+			kind: 'stylesheet',
+			srcUrl: '/assets/styles/fonts.css',
+			position: 'head',
+			sourceFilepath: '/app/src/styles/fonts.css',
+		} as ProcessedAsset;
+		const pageScript = {
+			kind: 'script',
+			srcUrl: '/assets/page.js',
+			position: 'head',
+		} as ProcessedAsset;
+
+		const result = createPagePackage([pageStylesheet, bundledTailwind, bundledFonts, pageScript]);
+
+		expect(result.pageStylesheet).toBe(pageStylesheet);
+		expect(result.htmlAssets).toEqual([pageStylesheet, pageScript]);
+	});
+});

package/src/services/assets/asset-processing-service/page-package.ts

@@ -0,0 +1,93 @@
+import type { PagePackageResult } from '../../../types/public-types.ts';
+import type { ProcessedAsset } from './assets.types.ts';
+
+function getSuppressedSourceFilepaths(assets: ProcessedAsset[]): Set<string> {
+	const suppressed = new Set<string>();
+
+	for (const asset of assets) {
+		if (
+			(asset.packageRole === 'page-style' || asset.packageRole === 'page-script') &&
+			Array.isArray(asset.bundledSourceFilepaths)
+		) {
+			for (const filepath of asset.bundledSourceFilepaths) {
+				suppressed.add(filepath);
+			}
+		}
+	}
+
+	return suppressed;
+}
+
+export function createPagePackage(assets: ProcessedAsset[]): PagePackageResult {
+	const inlineAssets: ProcessedAsset[] = [];
+	const separateAssets: ProcessedAsset[] = [];
+	const dynamicChunks: ProcessedAsset[] = [];
+	let pageScript: ProcessedAsset | undefined;
+	let pageStylesheet: ProcessedAsset | undefined;
+	const suppressedSourceFilepaths = getSuppressedSourceFilepaths(assets);
+
+	for (const asset of assets) {
+		if (asset.inline) {
+			inlineAssets.push(asset);
+			continue;
+		}
+
+		if (asset.packageRole === 'dynamic-chunk') {
+			dynamicChunks.push(asset);
+			continue;
+		}
+
+		if (!pageScript && asset.packageRole === 'page-script') {
+			pageScript = asset;
+			continue;
+		}
+
+		if (!pageStylesheet && asset.packageRole === 'page-style') {
+			pageStylesheet = asset;
+			continue;
+		}
+
+		if (asset.packageRole === 'keep-separate' || asset.packageRole === 'runtime') {
+			separateAssets.push(asset);
+			continue;
+		}
+
+		if (!pageScript && asset.kind === 'script' && !asset.excludeFromHtml) {
+			pageScript = asset;
+			continue;
+		}
+
+		if (!pageStylesheet && asset.kind === 'stylesheet') {
+			pageStylesheet = asset;
+			continue;
+		}
+
+		separateAssets.push(asset);
+	}
+
+	return {
+		assets,
+		htmlAssets: assets.filter((asset) => shouldIncludeInHtml(asset, suppressedSourceFilepaths)),
+		pageScript,
+		pageStylesheet,
+		inlineAssets,
+		separateAssets,
+		dynamicChunks,
+	};
+}
+
+function shouldIncludeInHtml(asset: ProcessedAsset, suppressedSourceFilepaths: Set<string>): boolean {
+	if (asset.excludeFromHtml) {
+		return false;
+	}
+
+	if (asset.packageRole === 'runtime') {
+		return false;
+	}
+
+	if (asset.sourceFilepath && suppressedSourceFilepaths.has(asset.sourceFilepath)) {
+		return false;
+	}
+
+	return true;
+}

package/src/services/assets/asset-processing-service/{processor.interface.d.ts → processor.interface.ts}

@@ -1,22 +1,27 @@
-import type { IHmrManager } from '../../../types/internal-types.js';
-import type { AssetDefinition, ProcessedAsset } from './assets.types.js';
+import type { IHmrManager } from '../../../types/internal-types.ts';
+import type { AssetDefinition, ProcessedAsset } from './assets.types.ts';
+
 /**
  * Base interface for asset processors.
  * Processors transform asset definitions into processed assets.
  */
 export interface AssetProcessor<T extends AssetDefinition = AssetDefinition> {
-    process(asset: T): Promise<ProcessedAsset>;
+	process(asset: T): Promise<ProcessedAsset>;
 }
+
 /**
  * Interface for processors that support HMR (Hot Module Replacement).
  * These processors can receive an HMR manager to enable hot reloading capabilities.
  */
 export interface HmrAwareProcessor extends AssetProcessor {
-    setHmrManager(hmrManager: IHmrManager): void;
+	setHmrManager(hmrManager: IHmrManager): void;
 }
+
 /**
  * Type guard to check if a processor supports HMR.
  * @param processor - The processor to check
  * @returns True if the processor implements HmrAwareProcessor
  */
-export declare function isHmrAware(processor: AssetProcessor): processor is HmrAwareProcessor;
+export function isHmrAware(processor: AssetProcessor): processor is HmrAwareProcessor {
+	return 'setHmrManager' in processor && typeof (processor as HmrAwareProcessor).setHmrManager === 'function';
+}

package/src/services/assets/asset-processing-service/processor.registry.ts

@@ -0,0 +1,18 @@
+import type { AssetKind, AssetSource } from './assets.types.ts';
+import type { BaseProcessor } from './processors/base/base-processor.ts';
+
+export class ProcessorRegistry {
+	private processors = new Map<`${AssetKind}-${AssetSource}`, BaseProcessor<any>>();
+
+	register(kind: AssetKind, variant: AssetSource, processor: BaseProcessor<any>) {
+		this.processors.set(`${kind}-${variant}`, processor);
+	}
+
+	getProcessor(kind: AssetKind, variant: AssetSource): BaseProcessor<any> | undefined {
+		return this.processors.get(`${kind}-${variant}`);
+	}
+
+	getAllProcessors(): Map<`${AssetKind}-${AssetSource}`, BaseProcessor<any>> {
+		return this.processors;
+	}
+}