npm - @ecopages/core - Versions diffs - 0.2.0-alpha.53 → 0.2.0-alpha.54 - Mend

@ecopages/core 0.2.0-alpha.53 → 0.2.0-alpha.54

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (590) hide show

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

@@ -0,0 +1,219 @@
+import { describe, expect, test } from 'vitest';
+import { addTriggerAttribute, isThenable, wrapWithScriptsInjector } 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('preserves JSX template metadata while injecting into the first string', () => {
+			const strings = ['<theme-toggle class=', '></theme-toggle>'];
+			Object.defineProperty(strings, 'raw', {
+				value: ['<theme-toggle class=', '></theme-toggle>'],
+			});
+			const template = {
+				_$rType$: 1,
+				rootLocalName: 'theme-toggle',
+				strings,
+				values: ['radiant-switch'],
+			};
+			const result = addTriggerAttribute(template, TRIGGER_ID) as unknown as {
+				_$rType$: number;
+				rootLocalName: string;
+				strings: string[];
+				values: unknown[];
+			};
+			expect(result._$rType$).toBe(1);
+			expect(result.rootLocalName).toBe('theme-toggle');
+			expect(result.values).toEqual(['radiant-switch']);
+			expect(result.strings).toEqual([
+				`<theme-toggle data-eco-trigger="${TRIGGER_ID}" class=`,
+				'></theme-toggle>',
+			]);
+			expect(Object.getOwnPropertyDescriptor(result.strings, 'raw')?.value).toEqual([
+				`<theme-toggle data-eco-trigger="${TRIGGER_ID}" class=`,
+				'></theme-toggle>',
+			]);
+		});
+		test('preserves SSR markup node output while injecting into outerHTML', () => {
+			const markupNode = {
+				nodeType: 1,
+				get outerHTML() {
+					return '<theme-toggle class="radiant-switch"></theme-toggle>';
+				},
+			};
+			const result = addTriggerAttribute(markupNode, TRIGGER_ID) as typeof markupNode;
+			expect(result.nodeType).toBe(1);
+			expect(result.outerHTML).toBe(
+				`<theme-toggle data-eco-trigger="${TRIGGER_ID}" class="radiant-switch"></theme-toggle>`,
+			);
+		});
+		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);
+	});
+});
+describe('wrapWithScriptsInjector', () => {
+	const lazyGroups = [{ lazy: { 'on:idle': true }, scripts: '/_assets/script.js' }] as const;
+	test('preserves JSX template metadata while wrapping content', () => {
+		const strings = ['<theme-toggle class=', '></theme-toggle>'];
+		Object.defineProperty(strings, 'raw', {
+			value: ['<theme-toggle class=', '></theme-toggle>'],
+		});
+		const template = {
+			_$rType$: 1,
+			rootLocalName: 'theme-toggle',
+			strings,
+			values: ['radiant-switch'],
+		};
+		const result = wrapWithScriptsInjector(template, lazyGroups) as unknown as typeof template;
+		expect(result._$rType$).toBe(1);
+		expect(result.rootLocalName).toBe('theme-toggle');
+		expect(result.values).toEqual(['radiant-switch']);
+		expect(result.strings[0]).toContain('<scripts-injector><script type="ecopages/injector-map">');
+		expect(result.strings[0]).toContain('<theme-toggle class=');
+		expect(result.strings[1]).toBe('></theme-toggle></scripts-injector>');
+		expect(Object.getOwnPropertyDescriptor(result.strings, 'raw')?.value[1]).toBe(
+			'></theme-toggle></scripts-injector>',
+		);
+	});
+	test('preserves markup-node-like output while wrapping content', () => {
+		const markupNode = {
+			nodeType: 1,
+			get outerHTML() {
+				return '<theme-toggle class="radiant-switch"></theme-toggle>';
+			},
+		};
+		const result = wrapWithScriptsInjector(markupNode, lazyGroups) as typeof markupNode;
+		expect(result.nodeType).toBe(1);
+		expect(result.outerHTML).toContain('<scripts-injector><script type="ecopages/injector-map">');
+		expect(result.outerHTML).toContain('<theme-toggle class="radiant-switch"></theme-toggle>');
+		expect(result.outerHTML).toContain('</scripts-injector>');
+	});
+});

package/src/eco/eco.utils.ts ADDED Viewed

@@ -0,0 +1,5 @@
+export {
+	addTriggerAttribute,
+	isThenable,
+	wrapWithScriptsInjector,
+} from '../route-renderer/orchestration/render-output.utils.ts';

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

@@ -0,0 +1,42 @@
+import { describe, expect, test } from 'vitest';
+import { buildGlobalInjectorBootstrapContent, buildGlobalInjectorMapScript } from './global-injector-map.ts';
+import type { ResolvedLazyTrigger } from '../types/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/global-injector-map.ts ADDED Viewed

@@ -0,0 +1,112 @@
+import type { ResolvedLazyTrigger } from '../types/public-types.ts';
+type GlobalInjectorEntry = {
+	'on:idle'?: { scripts: string[] };
+	'on:interaction'?: { value: string; scripts: string[] };
+	'on:visible'?: { value?: string; scripts: string[] };
+};
+type GlobalInjectorMap = Record<string, GlobalInjectorEntry>;
+/**
+ * Converts a flat list of resolved triggers into the map structure consumed
+ * by the `initGlobalInjector` bootstrap. Multiple triggers sharing the same
+ * `triggerId` are merged so their script lists are deduplicated.
+ */
+function buildGlobalInjectorMap(triggers: ResolvedLazyTrigger[]): GlobalInjectorMap {
+	const map: GlobalInjectorMap = {};
+	for (const { triggerId, rules } of triggers) {
+		const entry: GlobalInjectorEntry = map[triggerId] ?? {};
+		for (const rule of rules) {
+			if ('on:idle' in rule) {
+				const { scripts } = rule['on:idle'];
+				entry['on:idle'] = {
+					scripts: Array.from(new Set([...(entry['on:idle']?.scripts ?? []), ...scripts])),
+				};
+				continue;
+			}
+			if ('on:interaction' in rule) {
+				const { value, scripts } = rule['on:interaction'];
+				entry['on:interaction'] = {
+					value,
+					scripts: Array.from(new Set([...(entry['on:interaction']?.scripts ?? []), ...scripts])),
+				};
+				continue;
+			}
+			if ('on:visible' in rule) {
+				const { value, scripts } = rule['on:visible'];
+				entry['on:visible'] = {
+					...(value ? { value } : {}),
+					scripts: Array.from(new Set([...(entry['on:visible']?.scripts ?? []), ...scripts])),
+				};
+				continue;
+			}
+		}
+		if (Object.keys(entry).length > 0) {
+			map[triggerId] = entry;
+		}
+	}
+	return map;
+}
+/**
+ * Serializes resolved lazy triggers into a JSON string safe for embedding
+ * inside an inline `<script type="ecopages/global-injector-map">` tag.
+ *
+ * The `</script` sequence is escaped because an unescaped occurrence in inline
+ * script content causes the HTML parser to close the script tag prematurely,
+ * breaking page rendering. `JSON.stringify` does not perform this escape by
+ * default, so a targeted replacement is applied after serialization.
+ */
+export function buildGlobalInjectorMapScript(triggers: ResolvedLazyTrigger[]): string {
+	const map = buildGlobalInjectorMap(triggers);
+	return JSON.stringify(map).replace(/<\/script/gi, '<\\/script');
+}
+/**
+ * Builds the module source that boots the global lazy injector on the client.
+ * Emitted once per page alongside the `ecopages/global-injector-map` script block.
+ */
+export function buildGlobalInjectorBootstrapContent(globalInjectorModuleSpecifier: string): string {
+	return `import { initGlobalInjector } from ${JSON.stringify(globalInjectorModuleSpecifier)};
+function pruneStaleTriggerMaps() {
+	const mapScripts = Array.from(document.querySelectorAll('script[type="ecopages/global-injector-map"]'));
+	if (mapScripts.length <= 1) {
+		return;
+	}
+	const latestMapScript = mapScripts[mapScripts.length - 1];
+	for (const mapScript of mapScripts) {
+		if (mapScript !== latestMapScript) {
+			mapScript.remove();
+		}
+	}
+}
+const globalScope = window;
+if (typeof globalScope.__ecoGlobalInjectorCleanup === 'function') {
+	globalScope.__ecoGlobalInjectorCleanup();
+}
+const injector = initGlobalInjector();
+const handleAfterSwap = () => {
+	pruneStaleTriggerMaps();
+	injector.refresh();
+};
+document.addEventListener('eco:after-swap', handleAfterSwap);
+pruneStaleTriggerMaps();
+globalScope.__ecoGlobalInjectorCleanup = () => {
+	document.removeEventListener('eco:after-swap', handleAfterSwap);
+	injector.cleanup();
+};`;
+}

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

@@ -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 '../types/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/lazy-injector-map.ts ADDED Viewed

@@ -0,0 +1,120 @@
+import type { InjectorMapConfig } from '@ecopages/scripts-injector/types';
+import type { ResolvedLazyScriptGroup } from '../types/public-types.ts';
+/**
+ * Normalizes a comma-separated scripts string into absolute script URLs.
+ *
+ * @param scripts Comma-separated script paths.
+ * @returns Normalized script path list.
+ */
+function normalizeScripts(scripts: string): string[] {
+	return scripts
+		.split(',')
+		.map((scriptPath) => scriptPath.trim())
+		.filter(Boolean)
+		.map((scriptPath) => {
+			if (scriptPath.startsWith('/')) {
+				return scriptPath;
+			}
+			const normalizedRelativePath = scriptPath.replace(/^\/+/, '').replace(/^(\.\/)+/, '');
+			return `/${normalizedRelativePath}`;
+		});
+}
+/**
+ * Deduplicates comma-separated values while preserving first-seen order.
+ *
+ * @param values CSV value list.
+ * @returns A single normalized CSV string.
+ */
+function dedupeCsvValues(values: string[]): string {
+	const seen = new Set<string>();
+	for (const value of values) {
+		for (const token of value
+			.split(',')
+			.map((part) => part.trim())
+			.filter(Boolean)) {
+			seen.add(token);
+		}
+	}
+	return Array.from(seen).join(',');
+}
+/**
+ * Builds a scripts-injector map config from resolved lazy script groups.
+ *
+ * @param lazyGroups Lazy script groups resolved during dependency processing.
+ * @returns Injector map config keyed by lazy trigger.
+ */
+function buildInjectorMap(lazyGroups: readonly ResolvedLazyScriptGroup[]): InjectorMapConfig {
+	const map: InjectorMapConfig = {};
+	for (const group of lazyGroups) {
+		const scripts = normalizeScripts(group.scripts);
+		const lazy = group.lazy;
+		if ('on:idle' in lazy) {
+			map['on:idle'] = {
+				scripts: [...(map['on:idle']?.scripts ?? []), ...scripts],
+			};
+			continue;
+		}
+		if ('on:interaction' in lazy) {
+			const currentValue = map['on:interaction']?.value;
+			const nextValue = lazy['on:interaction'];
+			map['on:interaction'] = {
+				value: typeof currentValue === 'string' ? dedupeCsvValues([currentValue, nextValue]) : nextValue,
+				scripts: [...(map['on:interaction']?.scripts ?? []), ...scripts],
+			};
+			continue;
+		}
+		if ('on:visible' in lazy) {
+			const currentValue = map['on:visible']?.value;
+			const currentThreshold = typeof currentValue === 'string' ? currentValue : undefined;
+			const nextValue = lazy['on:visible'];
+			map['on:visible'] = {
+				...(nextValue === true
+					? currentThreshold
+						? { value: currentThreshold }
+						: {}
+					: { value: String(nextValue) }),
+				scripts: [...(map['on:visible']?.scripts ?? []), ...scripts],
+			};
+			continue;
+		}
+		throw new Error(
+			`Invalid lazy options: must specify on:idle, on:interaction, or on:visible. Received: ${JSON.stringify(lazy)}`,
+		);
+	}
+	for (const key of Object.keys(map)) {
+		const scripts = map[key]?.scripts;
+		if (scripts) {
+			map[key] = {
+				...map[key],
+				scripts: Array.from(new Set(scripts)),
+			};
+		}
+	}
+	return map;
+}
+/**
+ * Creates a safe JSON payload string for `<script type="ecopages/injector-map">`.
+ *
+ * @param lazyGroups Lazy script groups resolved during dependency processing.
+ * @returns Escaped JSON string safe for inline script embedding.
+ */
+export function buildInjectorMapScript(lazyGroups: readonly ResolvedLazyScriptGroup[]): string {
+	const map = buildInjectorMap(lazyGroups);
+	return JSON.stringify(map).replace(/<\/script/gi, '<\\/script');
+}

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

@@ -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/eco/module-dependencies.ts ADDED Viewed

@@ -0,0 +1,75 @@
+export type ModuleDependencyDeclaration = {
+	from: string;
+	imports?: string[];
+};
+function normalizeImports(imports: string[] | undefined): string[] | undefined {
+	if (!imports || imports.length === 0) {
+		return undefined;
+	}
+	const normalized = Array.from(new Set(imports.map((entry) => entry.trim()).filter((entry) => entry.length > 0)));
+	return normalized.length > 0 ? normalized : undefined;
+}
+/**
+ * Parses a module grammar declaration into normalized object form.
+ *
+ * Supported input examples:
+ * - `react-aria-components`
+ * - `react-aria-components{Table,Select}`
+ */
+export function parseModuleDeclaration(value: string): ModuleDependencyDeclaration {
+	const source = value.trim();
+	if (source.length === 0) {
+		throw new Error('Module declaration cannot be empty');
+	}
+	const openBraceIndex = source.indexOf('{');
+	if (openBraceIndex < 0) {
+		return { from: source };
+	}
+	const closeBraceIndex = source.lastIndexOf('}');
+	if (closeBraceIndex !== source.length - 1 || closeBraceIndex <= openBraceIndex) {
+		throw new Error(`Invalid module declaration '${value}'`);
+	}
+	const from = source.slice(0, openBraceIndex).trim();
+	if (from.length === 0) {
+		throw new Error(`Invalid module declaration '${value}'`);
+	}
+	const importsSlice = source.slice(openBraceIndex + 1, closeBraceIndex);
+	const imports = normalizeImports(importsSlice.split(','));
+	return {
+		from,
+		imports,
+	};
+}
+/**
+ * Normalizes and deduplicates module declarations from `modules`.
+ *
+ * Returns canonical object declarations suitable for downstream bundling logic.
+ */
+export function normalizeModuleDeclarations(modules?: string[]): ModuleDependencyDeclaration[] {
+	const declarations = modules ?? [];
+	const output: ModuleDependencyDeclaration[] = [];
+	const seen = new Set<string>();
+	for (const declaration of declarations) {
+		const normalized = parseModuleDeclaration(declaration);
+		const key = `${normalized.from}::${(normalized.imports ?? []).join(',')}`;
+		if (!seen.has(key)) {
+			seen.add(key);
+			output.push(normalized);
+		}
+	}
+	return output;
+}