@qwik-custom-elements/core 1.0.0

package/dist/__tests__/generator.test.js

@@ -0,0 +1,1331 @@
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import { GenerationError, generateFromConfig } from '../generator.js';
+const validStencilAdapterOptions = {
+    runtime: {
+        loaderImport: '@acme/stencil-lib/loader',
+    },
+};
+async function withTempDir(run) {
+    const tempDir = await mkdtemp(path.join(os.tmpdir(), 'qce-core-'));
+    try {
+        await run(tempDir);
+    }
+    finally {
+        await rm(tempDir, { recursive: true, force: true });
+    }
+}
+function createSingleProjectConfig(tempDir, dryRun = false) {
+    return {
+        dryRun,
+        projects: [
+            {
+                id: 'demo',
+                adapter: 'stencil',
+                adapterPackage: '@qwik-custom-elements/adapter-stencil',
+                source: { type: 'CEM', path: './custom-elements.json' },
+                adapterOptions: validStencilAdapterOptions,
+                outDir: './src/generated',
+            },
+        ],
+    };
+}
+async function createFixturePackage(tempDir, packageName) {
+    const packageRoot = path.join(tempDir, 'node_modules', ...packageName.split('/'));
+    await mkdir(packageRoot, { recursive: true });
+    await writeFile(path.join(packageRoot, 'package.json'), JSON.stringify({ name: packageName, version: '1.0.0' }, null, 2), 'utf8');
+    return packageRoot;
+}
+describe('generateFromConfig', () => {
+    it('produces deterministic planned writes in dry-run mode without mutating files', async () => {
+        await withTempDir(async (tempDir) => {
+            await writeFile(path.join(tempDir, 'custom-elements.json'), JSON.stringify({
+                modules: [
+                    {
+                        declarations: [
+                            { tagName: 'z-card' },
+                            {
+                                tagName: 'a-button',
+                                attributes: [
+                                    {
+                                        name: 'size',
+                                        fieldName: 'size',
+                                        type: { text: '"lg" | "md" | "sm"' },
+                                    },
+                                ],
+                                members: [
+                                    {
+                                        kind: 'field',
+                                        name: '#internalCount',
+                                        privacy: 'private',
+                                        type: { text: 'number' },
+                                    },
+                                    {
+                                        kind: 'field',
+                                        name: 'variant',
+                                        privacy: 'public',
+                                        type: { text: '"primary" | "secondary"' },
+                                    },
+                                ],
+                                events: [
+                                    {
+                                        name: 'tripleClick',
+                                        type: { text: 'CustomEvent<MouseEvent>' },
+                                    },
+                                ],
+                                slots: [
+                                    {
+                                        name: 'footer',
+                                    },
+                                    {
+                                        name: 'footer',
+                                    },
+                                ],
+                            },
+                            { tagName: 'z-card' },
+                        ],
+                    },
+                ],
+            }, null, 2), 'utf8');
+            const result = await generateFromConfig(createSingleProjectConfig(tempDir, true), { cwd: tempDir });
+            expect(result.dryRun).toBe(true);
+            expect(result.projects).toHaveLength(1);
+            expect(result.projects[0].wroteFiles).toBe(false);
+            expect(result.projects[0].componentTags).toEqual(['a-button', 'z-card']);
+            expect(result.projects[0].plannedWrites).toHaveLength(5);
+            const indexWrite = result.projects[0].plannedWrites.find((plannedWrite) => plannedWrite.path.endsWith(path.join('src', 'generated', 'index.ts')));
+            const runtimeBarrelWrite = result.projects[0].plannedWrites.find((plannedWrite) => plannedWrite.path.endsWith(path.join('src', 'generated', 'runtime.ts')));
+            const runtimeWrite = result.projects[0].plannedWrites.find((plannedWrite) => plannedWrite.path.endsWith(path.join('src', 'generated', 'runtime-csr.generated.ts')));
+            const buttonWrite = result.projects[0].plannedWrites.find((plannedWrite) => plannedWrite.path.endsWith(path.join('src', 'generated', 'a-button.tsx')));
+            const cardWrite = result.projects[0].plannedWrites.find((plannedWrite) => plannedWrite.path.endsWith(path.join('src', 'generated', 'z-card.tsx')));
+            expect(indexWrite?.content).toContain('// Generated by @qwik-custom-elements/core. Project: demo.');
+            expect(indexWrite?.content).toContain('export const generatedComponentTags = ["a-button","z-card"] as const;');
+            expect(indexWrite?.content).toContain("export { QwikAButton } from './a-button';");
+            expect(indexWrite?.content).toContain("export { QwikZCard } from './z-card';");
+            expect(buttonWrite?.content).toContain("import { Slot, component$ } from '@builder.io/qwik';");
+            expect(buttonWrite?.content).toContain("import type { QRL } from '@builder.io/qwik';");
+            expect(buttonWrite?.content).toContain("import { GeneratedStencilCSRComponent } from './runtime';");
+            expect(buttonWrite?.content).not.toContain('useStencilClientSetup();');
+            expect(buttonWrite?.content).toContain('export interface QwikAButtonProps {');
+            expect(buttonWrite?.content).toContain('  size?: "lg" | "md" | "sm";');
+            expect(buttonWrite?.content).toContain('  variant?: "primary" | "secondary";');
+            expect(buttonWrite?.content).not.toContain('#internalCount');
+            expect(buttonWrite?.content).toContain('  onTripleClick$?: QRL<(event: CustomEvent<MouseEvent>) => void>;');
+            expect(buttonWrite?.content).toContain('export const QwikAButton = component$<QwikAButtonProps>');
+            expect(buttonWrite?.content).toContain('  const eventProps: Record<string, unknown> = {};');
+            expect(buttonWrite?.content).toContain('    if (isEventBindingKey(key)) {');
+            expect(buttonWrite?.content).toContain('    <GeneratedStencilCSRComponent');
+            expect(buttonWrite?.content).toContain('      tagName="a-button"');
+            expect(buttonWrite?.content).toContain('      props={elementProps}');
+            expect(buttonWrite?.content).toContain('      events={mappedEvents}');
+            expect(buttonWrite?.content).toContain('      slots={["footer"]}');
+            expect(buttonWrite?.content).toContain('      {...passthroughEventProps}');
+            expect(buttonWrite?.content).toContain('    </GeneratedStencilCSRComponent>');
+            expect(buttonWrite?.content).toContain('      <Slot />');
+            expect(buttonWrite?.content).toContain('        <Slot name="footer" />');
+            expect(cardWrite?.content).toContain('export interface QwikZCardProps {');
+            expect(runtimeBarrelWrite?.content).toContain("export * from './runtime-csr.generated';");
+            expect(runtimeWrite?.content).toContain("import { defineCustomElements as runtimeDefineCustomElements } from '@acme/stencil-lib/loader';");
+            await expect(readFile(indexWrite.path, 'utf8')).rejects.toThrow();
+            await expect(readFile(runtimeBarrelWrite.path, 'utf8')).rejects.toThrow();
+            await expect(readFile(runtimeWrite.path, 'utf8')).rejects.toThrow();
+            await expect(readFile(buttonWrite.path, 'utf8')).rejects.toThrow();
+            await expect(readFile(cardWrite.path, 'utf8')).rejects.toThrow();
+        });
+    });
+    it('writes generated index.ts in non-dry-run mode', async () => {
+        await withTempDir(async (tempDir) => {
+            await writeFile(path.join(tempDir, 'custom-elements.json'), JSON.stringify({
+                modules: [{ declarations: [{ tagName: 'app-root' }] }],
+            }), 'utf8');
+            const result = await generateFromConfig(createSingleProjectConfig(tempDir), { cwd: tempDir });
+            const indexWrite = result.projects[0].plannedWrites.find((plannedWrite) => plannedWrite.path.endsWith(path.join('src', 'generated', 'index.ts')));
+            const wrapperWrite = result.projects[0].plannedWrites.find((plannedWrite) => plannedWrite.path.endsWith(path.join('src', 'generated', 'app-root.tsx')));
+            const runtimeWrite = result.projects[0].plannedWrites.find((plannedWrite) => plannedWrite.path.endsWith(path.join('src', 'generated', 'runtime-csr.generated.ts')));
+            const runtimeBarrelWrite = result.projects[0].plannedWrites.find((plannedWrite) => plannedWrite.path.endsWith(path.join('src', 'generated', 'runtime.ts')));
+            const indexDiskContent = await readFile(indexWrite.path, 'utf8');
+            const runtimeBarrelDiskContent = await readFile(runtimeBarrelWrite.path, 'utf8');
+            const runtimeDiskContent = await readFile(runtimeWrite.path, 'utf8');
+            const wrapperDiskContent = await readFile(wrapperWrite.path, 'utf8');
+            expect(result.projects[0].wroteFiles).toBe(true);
+            expect(result.projects[0].plannedWrites).toHaveLength(4);
+            expect(indexDiskContent).toBe(indexWrite.content);
+            expect(runtimeBarrelDiskContent).toBe(runtimeBarrelWrite.content);
+            expect(runtimeDiskContent).toBe(runtimeWrite.content);
+            expect(wrapperDiskContent).toBe(wrapperWrite.content);
+        });
+    });
+    it('keeps generated files byte-stable across repeated write runs', async () => {
+        await withTempDir(async (tempDir) => {
+            await writeFile(path.join(tempDir, 'custom-elements.json'), JSON.stringify({
+                modules: [
+                    {
+                        declarations: [
+                            { tagName: 'card-panel' },
+                            { tagName: 'app-root' },
+                        ],
+                    },
+                ],
+            }, null, 2), 'utf8');
+            const config = createSingleProjectConfig(tempDir);
+            const firstRun = await generateFromConfig(config, { cwd: tempDir });
+            const firstIndexWrite = firstRun.projects[0].plannedWrites.find((plannedWrite) => plannedWrite.path.endsWith(path.join('src', 'generated', 'index.ts')));
+            const firstAppRootWrite = firstRun.projects[0].plannedWrites.find((plannedWrite) => plannedWrite.path.endsWith(path.join('src', 'generated', 'app-root.tsx')));
+            const firstCardPanelWrite = firstRun.projects[0].plannedWrites.find((plannedWrite) => plannedWrite.path.endsWith(path.join('src', 'generated', 'card-panel.tsx')));
+            const firstIndexDiskContent = await readFile(firstIndexWrite.path, 'utf8');
+            const firstAppRootDiskContent = await readFile(firstAppRootWrite.path, 'utf8');
+            const firstCardPanelDiskContent = await readFile(firstCardPanelWrite.path, 'utf8');
+            const secondRun = await generateFromConfig(config, { cwd: tempDir });
+            const secondIndexWrite = secondRun.projects[0].plannedWrites.find((plannedWrite) => plannedWrite.path.endsWith(path.join('src', 'generated', 'index.ts')));
+            const secondAppRootWrite = secondRun.projects[0].plannedWrites.find((plannedWrite) => plannedWrite.path.endsWith(path.join('src', 'generated', 'app-root.tsx')));
+            const secondCardPanelWrite = secondRun.projects[0].plannedWrites.find((plannedWrite) => plannedWrite.path.endsWith(path.join('src', 'generated', 'card-panel.tsx')));
+            const secondIndexDiskContent = await readFile(secondIndexWrite.path, 'utf8');
+            const secondAppRootDiskContent = await readFile(secondAppRootWrite.path, 'utf8');
+            const secondCardPanelDiskContent = await readFile(secondCardPanelWrite.path, 'utf8');
+            expect(secondRun.projects[0].plannedWrites.map((write) => write.path)).toEqual(firstRun.projects[0].plannedWrites.map((write) => write.path));
+            expect(secondIndexWrite.content).toBe(firstIndexWrite.content);
+            expect(secondAppRootWrite.content).toBe(firstAppRootWrite.content);
+            expect(secondCardPanelWrite.content).toBe(firstCardPanelWrite.content);
+            expect(secondIndexDiskContent).toBe(firstIndexDiskContent);
+            expect(secondAppRootDiskContent).toBe(firstAppRootDiskContent);
+            expect(secondCardPanelDiskContent).toBe(firstCardPanelDiskContent);
+        });
+    });
+    it('fails with deterministic code when CEM source cannot be read', async () => {
+        await withTempDir(async (tempDir) => {
+            const config = createSingleProjectConfig(tempDir, true);
+            await expect(generateFromConfig(config, { cwd: tempDir })).rejects.toMatchObject({ code: 'QCE_CEM_READ_FAILED' });
+            await expect(generateFromConfig(config, { cwd: tempDir })).rejects.toBeInstanceOf(GenerationError);
+        });
+    });
+    it('fails when the adapter rejects a stencil CEM project without loaderImport', async () => {
+        await withTempDir(async (tempDir) => {
+            await writeFile(path.join(tempDir, 'custom-elements.json'), JSON.stringify({
+                modules: [{ declarations: [{ tagName: 'app-root' }] }],
+            }), 'utf8');
+            await writeFile(path.join(tempDir, 'adapter-validating.mjs'), [
+                'export const metadata = {',
+                "  supportedSourceTypes: ['CEM', 'PACKAGE_NAME'],",
+                '  supportsSsrProbe: true,',
+                "  ssrRuntimeSubpath: './ssr',",
+                '};',
+                '',
+                'export function validateProject({ source, adapterOptions }) {',
+                "  if (source.type !== 'CEM') return;",
+                '  const loaderImport = adapterOptions?.runtime?.loaderImport;',
+                "  if (typeof loaderImport === 'string' && loaderImport.trim() !== '') return;",
+                "  throw Object.assign(new Error('Stencil CEM projects must provide adapterOptions.runtime.loaderImport.'), {",
+                "    code: 'QCE_STENCIL_RUNTIME_LOADER_REQUIRED',",
+                '  });',
+                '}',
+                '',
+                'export async function probeSSR() {',
+                '  return { available: true };',
+                '}',
+                '',
+            ].join('\n'), 'utf8');
+            const config = createSingleProjectConfig(tempDir, true);
+            config.projects[0].adapterPackage = './adapter-validating.mjs';
+            config.projects[0].adapterOptions = {};
+            await expect(generateFromConfig(config, { cwd: tempDir })).rejects.toMatchObject({
+                code: 'QCE_STENCIL_RUNTIME_LOADER_REQUIRED',
+                message: 'Stencil CEM projects must provide adapterOptions.runtime.loaderImport.',
+            });
+        });
+    });
+    it('falls back to CEM-only generation when adapter SSR is unavailable', async () => {
+        await withTempDir(async (tempDir) => {
+            await writeFile(path.join(tempDir, 'custom-elements.json'), JSON.stringify({
+                modules: [{ declarations: [{ tagName: 'app-root' }] }],
+            }), 'utf8');
+            await writeFile(path.join(tempDir, 'adapter-unsupported.mjs'), [
+                'export async function probeSSR() {',
+                '  return { available: false };',
+                '}',
+                '',
+                'export function createGeneratedOutput() {',
+                '  return [];',
+                '}',
+                '',
+            ].join('\n'), 'utf8');
+            const config = createSingleProjectConfig(tempDir, true);
+            config.projects[0].adapterPackage = './adapter-unsupported.mjs';
+            const result = await generateFromConfig(config, { cwd: tempDir });
+            expect(result.projects[0].status).toBe('success');
+            expect(result.projects[0].plannedWrites).toHaveLength(0);
+            expect(result.projects[0].ssrCapabilities).toEqual({
+                available: false,
+                supportsSsrProbe: false,
+                ssrRuntimeSubpath: null,
+            });
+            expect(result.projects[0].observedErrorCodes).toEqual([
+                'QCE_SSR_UNSUPPORTED_FALLBACK',
+            ]);
+        });
+    });
+    it('emits generatedMode csr and QCE_SSR_UNSUPPORTED_FALLBACK together when SSR probe returns unavailable', async () => {
+        await withTempDir(async (tempDir) => {
+            await writeFile(path.join(tempDir, 'custom-elements.json'), JSON.stringify({
+                modules: [{ declarations: [{ tagName: 'lit-button' }] }],
+            }), 'utf8');
+            await writeFile(path.join(tempDir, 'adapter-ssr-probe-unavailable.mjs'), [
+                'export const metadata = {',
+                "  supportedSourceTypes: ['CEM', 'PACKAGE_NAME'],",
+                '  supportsSsrProbe: true,',
+                "  ssrRuntimeSubpath: './ssr',",
+                '};',
+                '',
+                'export async function probeSSR() {',
+                '  return { available: false };',
+                '}',
+                '',
+                'export function createGeneratedOutput({ componentDefinitions, ssrAvailable }) {',
+                '  const tags = componentDefinitions.map((d) => JSON.stringify(d.tagName)).join(",");',
+                "  const mode = ssrAvailable ? 'ssr' : 'csr';",
+                '  return [{',
+                "    relativePath: 'index.ts',",
+                "    content: `export const generatedComponentTags = [${tags}] as const;\\nexport const generatedMode = '${mode}' as const;\\n`,",
+                '  }];',
+                '}',
+                '',
+            ].join('\n'), 'utf8');
+            const config = {
+                dryRun: true,
+                projects: [
+                    {
+                        id: 'demo',
+                        adapter: 'lit',
+                        adapterPackage: './adapter-ssr-probe-unavailable.mjs',
+                        source: { type: 'CEM', path: './custom-elements.json' },
+                        outDir: './src/generated',
+                    },
+                ],
+            };
+            const result = await generateFromConfig(config, { cwd: tempDir });
+            expect(result.projects[0].status).toBe('success');
+            expect(result.projects[0].observedErrorCodes).toContain('QCE_SSR_UNSUPPORTED_FALLBACK');
+            const indexWrite = result.projects[0].plannedWrites.find((w) => w.path.endsWith(path.join('src', 'generated', 'index.ts')));
+            expect(indexWrite?.content).toContain("export const generatedMode = 'csr' as const;");
+        });
+    });
+    it('uses the primary adapter generation contract when the adapter exposes createGeneratedOutput', async () => {
+        await withTempDir(async (tempDir) => {
+            await writeFile(path.join(tempDir, 'custom-elements.json'), JSON.stringify({
+                modules: [{ declarations: [{ tagName: 'app-root' }] }],
+            }), 'utf8');
+            await writeFile(path.join(tempDir, 'adapter-primary-generation.mjs'), [
+                'export const metadata = {',
+                "  supportedSourceTypes: ['CEM', 'PACKAGE_NAME'],",
+                '  supportsSsrProbe: false,',
+                '  ssrRuntimeSubpath: null,',
+                '};',
+                '',
+                'export function createGeneratedOutput({ projectId, componentDefinitions }) {',
+                '  return componentDefinitions.map((componentDefinition) => ({',
+                '    relativePath: `${componentDefinition.tagName}.txt`,',
+                '    content: `primary:${projectId}:${componentDefinition.tagName}` ,',
+                '  }));',
+                '}',
+                '',
+            ].join('\n'), 'utf8');
+            const config = createSingleProjectConfig(tempDir, true);
+            config.projects[0].adapterPackage = './adapter-primary-generation.mjs';
+            const result = await generateFromConfig(config, { cwd: tempDir });
+            expect(result.projects[0].plannedWrites).toEqual([
+                expect.objectContaining({
+                    path: path.join(tempDir, 'src', 'generated', 'app-root.txt'),
+                    content: 'primary:demo:app-root',
+                }),
+            ]);
+        });
+    });
+    it('passes optional libraryName to createGeneratedOutput when configured', async () => {
+        await withTempDir(async (tempDir) => {
+            await writeFile(path.join(tempDir, 'custom-elements.json'), JSON.stringify({
+                modules: [{ declarations: [{ tagName: 'app-root' }] }],
+            }), 'utf8');
+            await writeFile(path.join(tempDir, 'adapter-library-name.mjs'), [
+                'export const metadata = {',
+                "  supportedSourceTypes: ['CEM', 'PACKAGE_NAME'],",
+                '  supportsSsrProbe: false,',
+                '  ssrRuntimeSubpath: null,',
+                '};',
+                '',
+                'export function createGeneratedOutput({ projectId, libraryName, componentDefinitions }) {',
+                '  return componentDefinitions.map((componentDefinition) => ({',
+                '    relativePath: `${componentDefinition.tagName}.txt`,',
+                '    content: `library:${projectId}:${libraryName ?? "missing"}:${componentDefinition.tagName}` ,',
+                '  }));',
+                '}',
+                '',
+            ].join('\n'), 'utf8');
+            const config = createSingleProjectConfig(tempDir, true);
+            config.projects[0].adapterPackage = './adapter-library-name.mjs';
+            config.projects[0].libraryName = 'test-stencil-lib';
+            const result = await generateFromConfig(config, { cwd: tempDir });
+            expect(result.projects[0].plannedWrites).toEqual([
+                expect.objectContaining({
+                    path: path.join(tempDir, 'src', 'generated', 'app-root.txt'),
+                    content: 'library:demo:test-stencil-lib:app-root',
+                }),
+            ]);
+        });
+    });
+    it('returns only adapter-generated files without adding core fallback output', async () => {
+        await withTempDir(async (tempDir) => {
+            await writeFile(path.join(tempDir, 'custom-elements.json'), JSON.stringify({
+                modules: [{ declarations: [{ tagName: 'app-root' }] }],
+            }, null, 2), 'utf8');
+            await writeFile(path.join(tempDir, 'adapter-owned-output.mjs'), [
+                'export const metadata = {',
+                "  supportedSourceTypes: ['CEM', 'PACKAGE_NAME'],",
+                '  supportsSsrProbe: false,',
+                '  ssrRuntimeSubpath: null,',
+                '};',
+                '',
+                'export function createGeneratedOutput({ projectId, componentDefinitions }) {',
+                '  return [',
+                '    {',
+                "      relativePath: 'owned/runtime-entry.ts',",
+                '      content: `owned:${projectId}:${componentDefinitions[0]?.tagName ?? "missing"}`,',
+                '    },',
+                '  ];',
+                '}',
+                '',
+            ].join('\n'), 'utf8');
+            const config = createSingleProjectConfig(tempDir, true);
+            config.projects[0].adapterPackage = './adapter-owned-output.mjs';
+            const result = await generateFromConfig(config, { cwd: tempDir });
+            expect(result.projects[0].plannedWrites).toEqual([
+                {
+                    path: path.join(tempDir, 'src', 'generated', 'owned', 'runtime-entry.ts'),
+                    content: 'owned:demo:app-root',
+                },
+            ]);
+        });
+    });
+    it('fails when an adapter only exposes the deprecated additional planned writes contract', async () => {
+        await withTempDir(async (tempDir) => {
+            await writeFile(path.join(tempDir, 'custom-elements.json'), JSON.stringify({
+                modules: [{ declarations: [{ tagName: 'app-root' }] }],
+            }), 'utf8');
+            await writeFile(path.join(tempDir, 'adapter-legacy-generation.mjs'), [
+                'export const metadata = {',
+                "  supportedSourceTypes: ['CEM', 'PACKAGE_NAME'],",
+                '  supportsSsrProbe: false,',
+                '  ssrRuntimeSubpath: null,',
+                '};',
+                '',
+                'export function createAdditionalPlannedWrites({ projectId, componentDefinitions }) {',
+                '  return componentDefinitions.map((componentDefinition) => ({',
+                '    relativePath: `${componentDefinition.tagName}.txt`,',
+                '    content: `legacy:${projectId}:${componentDefinition.tagName}` ,',
+                '  }));',
+                '}',
+                '',
+            ].join('\n'), 'utf8');
+            const config = createSingleProjectConfig(tempDir, true);
+            config.projects[0].adapterPackage = './adapter-legacy-generation.mjs';
+            await expect(generateFromConfig(config, { cwd: tempDir })).rejects.toMatchObject({
+                code: 'QCE_ADAPTER_GENERATION_CONTRACT_REQUIRED',
+                message: expect.stringContaining('createGeneratedOutput'),
+            });
+        });
+    });
+    it('passes adapter-resolved runtime imports into SSR probing', async () => {
+        await withTempDir(async (tempDir) => {
+            const fixturePackageRoot = await createFixturePackage(tempDir, '@acme/stencil-lib');
+            await writeFile(path.join(fixturePackageRoot, 'custom-elements.json'), JSON.stringify({
+                modules: [{ declarations: [{ tagName: 'app-root' }] }],
+            }), 'utf8');
+            await writeFile(path.join(tempDir, 'adapter-runtime-resolution.mjs'), [
+                'export const metadata = {',
+                "  supportedSourceTypes: ['CEM', 'PACKAGE_NAME'],",
+                '  supportsSsrProbe: true,',
+                "  ssrRuntimeSubpath: './ssr',",
+                '};',
+                '',
+                'export function resolveRuntimeImports({ source, adapterOptions }) {',
+                '  return {',
+                '    loaderImport: adapterOptions?.runtime?.loaderImport ?? `${source.packageName}/loader`,',
+                '    hydrateImport: adapterOptions?.runtime?.hydrateImport ?? `${source.packageName}/hydrate`,',
+                '  };',
+                '}',
+                '',
+                'export async function probeSSR({ runtimeImports }) {',
+                "  return { available: runtimeImports?.loaderImport === '@acme/stencil-lib/loader' && runtimeImports?.hydrateImport === '@acme/stencil-lib/hydrate' };",
+                '}',
+                '',
+                'export function createGeneratedOutput() {',
+                '  return [];',
+                '}',
+                '',
+            ].join('\n'), 'utf8');
+            const config = {
+                dryRun: true,
+                projects: [
+                    {
+                        id: 'demo',
+                        adapter: 'stencil',
+                        adapterPackage: './adapter-runtime-resolution.mjs',
+                        source: {
+                            type: 'PACKAGE_NAME',
+                            packageName: '@acme/stencil-lib',
+                        },
+                        outDir: './src/generated',
+                    },
+                ],
+            };
+            const result = await generateFromConfig(config, { cwd: tempDir });
+            expect(result.projects[0].ssrCapabilities).toEqual({
+                available: true,
+                supportsSsrProbe: true,
+                ssrRuntimeSubpath: './ssr',
+            });
+            expect(result.projects[0].observedErrorCodes).toEqual([]);
+        });
+    });
+    it('fails when a PACKAGE_NAME stencil loader runtime import cannot be resolved', async () => {
+        await withTempDir(async (tempDir) => {
+            const fixturePackageRoot = await createFixturePackage(tempDir, '@acme/stencil-lib');
+            await writeFile(path.join(fixturePackageRoot, 'custom-elements.json'), JSON.stringify({
+                modules: [{ declarations: [{ tagName: 'app-root' }] }],
+            }), 'utf8');
+            const config = {
+                dryRun: true,
+                projects: [
+                    {
+                        id: 'demo',
+                        adapter: 'stencil',
+                        adapterPackage: '@qwik-custom-elements/adapter-stencil',
+                        source: {
+                            type: 'PACKAGE_NAME',
+                            packageName: '@acme/stencil-lib',
+                        },
+                        outDir: './src/generated',
+                    },
+                ],
+            };
+            await expect(generateFromConfig(config, { cwd: tempDir })).rejects.toMatchObject({
+                code: 'QCE_STENCIL_RUNTIME_LOADER_RESOLVE_FAILED',
+                message: expect.stringContaining('@acme/stencil-lib/loader'),
+            });
+        });
+    });
+    it('records a hydrate runtime diagnostic and falls back when a PACKAGE_NAME stencil hydrate import cannot be resolved', async () => {
+        await withTempDir(async (tempDir) => {
+            const fixturePackageRoot = await createFixturePackage(tempDir, '@acme/stencil-lib');
+            await writeFile(path.join(fixturePackageRoot, 'custom-elements.json'), JSON.stringify({
+                modules: [{ declarations: [{ tagName: 'app-root' }] }],
+            }), 'utf8');
+            await mkdir(path.join(fixturePackageRoot, 'loader'), { recursive: true });
+            await writeFile(path.join(fixturePackageRoot, 'loader', 'index.js'), 'export const defineCustomElements = () => undefined;\n', 'utf8');
+            const config = {
+                dryRun: true,
+                projects: [
+                    {
+                        id: 'demo',
+                        adapter: 'stencil',
+                        adapterPackage: '@qwik-custom-elements/adapter-stencil',
+                        source: {
+                            type: 'PACKAGE_NAME',
+                            packageName: '@acme/stencil-lib',
+                        },
+                        outDir: './src/generated',
+                    },
+                ],
+            };
+            const result = await generateFromConfig(config, { cwd: tempDir });
+            expect(result.projects[0].status).toBe('success');
+            expect(result.projects[0].ssrCapabilities).toEqual({
+                available: false,
+                supportsSsrProbe: true,
+                ssrRuntimeSubpath: './ssr',
+                clientOnlyMode: true,
+            });
+            expect(result.projects[0].observedErrorCodes).toEqual([
+                'QCE_SSR_UNSUPPORTED_FALLBACK',
+                'QCE_STENCIL_RUNTIME_HYDRATE_RESOLVE_FAILED',
+            ]);
+        });
+    });
+    it('generates a loader-only runtime barrel and CSR wrapper when PACKAGE_NAME hydrate resolution fails', async () => {
+        await withTempDir(async (tempDir) => {
+            const fixturePackageRoot = await createFixturePackage(tempDir, '@acme/stencil-lib');
+            await writeFile(path.join(fixturePackageRoot, 'custom-elements.json'), JSON.stringify({
+                modules: [{ declarations: [{ tagName: 'app-root' }] }],
+            }), 'utf8');
+            await mkdir(path.join(fixturePackageRoot, 'loader'), { recursive: true });
+            await writeFile(path.join(fixturePackageRoot, 'loader', 'index.js'), 'export const defineCustomElements = () => undefined;\n', 'utf8');
+            const config = {
+                dryRun: true,
+                projects: [
+                    {
+                        id: 'demo',
+                        adapter: 'stencil',
+                        adapterPackage: '@qwik-custom-elements/adapter-stencil',
+                        source: {
+                            type: 'PACKAGE_NAME',
+                            packageName: '@acme/stencil-lib',
+                        },
+                        outDir: './src/generated',
+                    },
+                ],
+            };
+            const result = await generateFromConfig(config, { cwd: tempDir });
+            const runtimeBarrelWrite = result.projects[0].plannedWrites.find((plannedWrite) => plannedWrite.path.endsWith(path.join('src', 'generated', 'runtime.ts')));
+            const runtimeCsrWrite = result.projects[0].plannedWrites.find((plannedWrite) => plannedWrite.path.endsWith(path.join('src', 'generated', 'runtime-csr.generated.ts')));
+            const wrapperWrite = result.projects[0].plannedWrites.find((plannedWrite) => plannedWrite.path.endsWith(path.join('src', 'generated', 'app-root.tsx')));
+            expect(result.projects[0].plannedWrites).not.toEqual(expect.arrayContaining([
+                expect.objectContaining({
+                    path: path.join(tempDir, 'src', 'generated', 'runtime-ssr.generated.ts'),
+                }),
+            ]));
+            expect(runtimeBarrelWrite?.content).toContain("export * from './runtime-csr.generated';");
+            expect(runtimeBarrelWrite?.content).not.toContain("export * from './runtime-ssr.generated';");
+            expect(runtimeCsrWrite?.content).toContain("import { createStencilCSRComponent, createStencilClientSetup } from '@qwik-custom-elements/adapter-stencil/client';");
+            expect(runtimeCsrWrite?.content).toContain('export const GeneratedStencilCSRComponent = createStencilCSRComponent();');
+            expect(runtimeCsrWrite?.content).not.toContain('createStencilSSRComponent');
+            expect(wrapperWrite?.content).toContain("import { GeneratedStencilCSRComponent } from './runtime';");
+            expect(wrapperWrite?.content).not.toContain('useStencilClientSetup();');
+            expect(wrapperWrite?.content).toContain('    <GeneratedStencilCSRComponent');
+            expect(wrapperWrite?.content).toContain('      tagName="app-root"');
+            expect(wrapperWrite?.content).toContain('      props={elementProps}');
+            expect(wrapperWrite?.content).toContain('      events={mappedEvents}');
+            expect(wrapperWrite?.content).toContain('      slots={undefined}');
+            expect(wrapperWrite?.content).toContain('      {...passthroughEventProps}');
+            expect(wrapperWrite?.content).toContain('    </GeneratedStencilCSRComponent>');
+        });
+    });
+    it('generates a client runtime bootstrap from resolved PACKAGE_NAME loader imports', async () => {
+        await withTempDir(async (tempDir) => {
+            const fixturePackageRoot = await createFixturePackage(tempDir, '@acme/stencil-lib');
+            await writeFile(path.join(fixturePackageRoot, 'custom-elements.json'), JSON.stringify({
+                modules: [{ declarations: [{ tagName: 'app-root' }] }],
+            }), 'utf8');
+            await mkdir(path.join(fixturePackageRoot, 'loader'), { recursive: true });
+            await writeFile(path.join(fixturePackageRoot, 'loader', 'index.js'), 'export const defineCustomElements = () => undefined;\n', 'utf8');
+            const config = {
+                dryRun: true,
+                projects: [
+                    {
+                        id: 'demo',
+                        adapter: 'stencil',
+                        adapterPackage: '@qwik-custom-elements/adapter-stencil',
+                        source: {
+                            type: 'PACKAGE_NAME',
+                            packageName: '@acme/stencil-lib',
+                        },
+                        outDir: './src/generated',
+                    },
+                ],
+            };
+            const result = await generateFromConfig(config, { cwd: tempDir });
+            const runtimeWrite = result.projects[0].plannedWrites.find((plannedWrite) => plannedWrite.path.endsWith(path.join('src', 'generated', 'runtime-csr.generated.ts')));
+            expect(runtimeWrite).toBeDefined();
+            expect(runtimeWrite.content).toContain("import { defineCustomElements as runtimeDefineCustomElements } from '@acme/stencil-lib/loader';");
+            expect(runtimeWrite.content).toContain('export const useStencilClientSetup =');
+            expect(runtimeWrite.content).toContain('createStencilClientSetup(defineCustomElementsQrl);');
+        });
+    });
+    it('generates a server runtime bridge from resolved PACKAGE_NAME hydrate imports', async () => {
+        await withTempDir(async (tempDir) => {
+            const fixturePackageRoot = await createFixturePackage(tempDir, '@acme/stencil-lib');
+            await writeFile(path.join(fixturePackageRoot, 'custom-elements.json'), JSON.stringify({
+                modules: [{ declarations: [{ tagName: 'app-root' }] }],
+            }), 'utf8');
+            await mkdir(path.join(fixturePackageRoot, 'loader'), { recursive: true });
+            await writeFile(path.join(fixturePackageRoot, 'loader', 'index.js'), 'export const defineCustomElements = () => undefined;\n', 'utf8');
+            await mkdir(path.join(fixturePackageRoot, 'hydrate'), {
+                recursive: true,
+            });
+            await writeFile(path.join(fixturePackageRoot, 'hydrate', 'index.js'), 'export const renderToString = async () => ({ html: "<app-root></app-root>" });\n', 'utf8');
+            const config = {
+                dryRun: true,
+                projects: [
+                    {
+                        id: 'demo',
+                        adapter: 'stencil',
+                        adapterPackage: '@qwik-custom-elements/adapter-stencil',
+                        source: {
+                            type: 'PACKAGE_NAME',
+                            packageName: '@acme/stencil-lib',
+                        },
+                        outDir: './src/generated',
+                    },
+                ],
+            };
+            const result = await generateFromConfig(config, { cwd: tempDir });
+            const runtimeWrite = result.projects[0].plannedWrites.find((plannedWrite) => plannedWrite.path.endsWith(path.join('src', 'generated', 'runtime-ssr.generated.ts')));
+            expect(runtimeWrite).toBeDefined();
+            expect(runtimeWrite.content).toContain("const hydrateModuleId = '@acme/stencil-lib/hydrate';");
+            expect(runtimeWrite.content).toContain('export const renderToString: StencilRenderToString = async (input, options) => {');
+            expect(runtimeWrite.content).toContain('/* @vite-ignore */ hydrateModuleId');
+            expect(runtimeWrite.content).toContain('return runtimeRenderToString(input, options);');
+            expect(runtimeWrite.content).toContain('export const GeneratedStencilComponent = createStencilSSRBridgeComponent(');
+        });
+    });
+    it('renders Stencil wrappers through the generated SSR component when hydrate runtime is available', async () => {
+        await withTempDir(async (tempDir) => {
+            const hydrateModulePath = path.join(tempDir, 'runtime', 'acme-hydrate.mjs');
+            await mkdir(path.dirname(hydrateModulePath), { recursive: true });
+            await writeFile(hydrateModulePath, 'export async function renderToString() { return { html: "" }; }\n', 'utf8');
+            await writeFile(path.join(tempDir, 'custom-elements.json'), JSON.stringify({
+                modules: [
+                    {
+                        declarations: [
+                            {
+                                tagName: 'a-button',
+                                attributes: [
+                                    {
+                                        name: 'size',
+                                        fieldName: 'size',
+                                        type: { text: '"lg" | "md" | "sm"' },
+                                    },
+                                ],
+                                events: [
+                                    {
+                                        name: 'tripleClick',
+                                        type: { text: 'CustomEvent<MouseEvent>' },
+                                    },
+                                ],
+                                slots: [
+                                    {
+                                        name: 'footer',
+                                    },
+                                ],
+                            },
+                        ],
+                    },
+                ],
+            }, null, 2), 'utf8');
+            const config = {
+                dryRun: true,
+                projects: [
+                    {
+                        id: 'demo',
+                        adapter: 'stencil',
+                        adapterPackage: '@qwik-custom-elements/adapter-stencil',
+                        source: {
+                            type: 'CEM',
+                            path: './custom-elements.json',
+                        },
+                        outDir: './src/generated',
+                        adapterOptions: {
+                            runtime: {
+                                loaderImport: './runtime/acme-loader',
+                                hydrateImport: pathToFileURL(hydrateModulePath).href,
+                            },
+                        },
+                    },
+                ],
+            };
+            const result = await generateFromConfig(config, { cwd: tempDir });
+            expect(result.projects[0].ssrCapabilities.available).toBe(true);
+            expect(result.projects[0].ssrCapabilities.supportsSsrProbe).toBe(true);
+            expect(result.projects[0].ssrCapabilities.ssrRuntimeSubpath).toBe('./ssr');
+            expect(result.projects[0].ssrCapabilities.clientOnlyMode).toBeUndefined();
+            const runtimeSsrWrite = result.projects[0].plannedWrites.find((plannedWrite) => plannedWrite.path.endsWith(path.join('src', 'generated', 'runtime-ssr.generated.ts')));
+            const buttonWrite = result.projects[0].plannedWrites.find((plannedWrite) => plannedWrite.path.endsWith(path.join('src', 'generated', 'a-button.tsx')));
+            expect(runtimeSsrWrite).toBeDefined();
+            expect(buttonWrite).toBeDefined();
+            expect(buttonWrite.content).toContain("import { GeneratedStencilComponent } from './runtime';");
+            expect(buttonWrite.content).not.toContain('useStencilClientSetup();');
+            expect(buttonWrite.content).toContain('  const events: Record<string, QRL<(...args: any[]) => void>> = {};');
+            expect(buttonWrite.content).toContain('  const passthroughEventProps = Object.fromEntries(');
+            expect(buttonWrite.content).toContain('      ([key]) => !mappedEventPropKeys.has(key),');
+            expect(buttonWrite.content).toContain("  if (props.onTripleClick$) { events['tripleClick'] = props.onTripleClick$; }");
+            expect(buttonWrite.content).toContain('      tagName="a-button"');
+            expect(buttonWrite.content).toContain('      events={mappedEvents}');
+            expect(buttonWrite.content).toContain('      slots={["footer"]}');
+            expect(buttonWrite.content).toContain('      {...passthroughEventProps}');
+            expect(buttonWrite.content).toContain('    </GeneratedStencilComponent>');
+        });
+    });
+    it('generates a runtime barrel for resolved Stencil runtime modules', async () => {
+        await withTempDir(async (tempDir) => {
+            const fixturePackageRoot = await createFixturePackage(tempDir, '@acme/stencil-lib');
+            await writeFile(path.join(fixturePackageRoot, 'custom-elements.json'), JSON.stringify({
+                modules: [{ declarations: [{ tagName: 'app-root' }] }],
+            }), 'utf8');
+            await mkdir(path.join(fixturePackageRoot, 'loader'), { recursive: true });
+            await writeFile(path.join(fixturePackageRoot, 'loader', 'index.js'), 'export const defineCustomElements = () => undefined;\n', 'utf8');
+            await mkdir(path.join(fixturePackageRoot, 'hydrate'), {
+                recursive: true,
+            });
+            await writeFile(path.join(fixturePackageRoot, 'hydrate', 'index.js'), 'export const renderToString = async () => ({ html: "<app-root></app-root>" });\n', 'utf8');
+            const config = {
+                dryRun: true,
+                projects: [
+                    {
+                        id: 'demo',
+                        adapter: 'stencil',
+                        adapterPackage: '@qwik-custom-elements/adapter-stencil',
+                        source: {
+                            type: 'PACKAGE_NAME',
+                            packageName: '@acme/stencil-lib',
+                        },
+                        outDir: './src/generated',
+                    },
+                ],
+            };
+            const result = await generateFromConfig(config, { cwd: tempDir });
+            const runtimeWrite = result.projects[0].plannedWrites.find((plannedWrite) => plannedWrite.path.endsWith(path.join('src', 'generated', 'runtime.ts')));
+            expect(runtimeWrite).toBeDefined();
+            expect(runtimeWrite.content).toContain("export * from './runtime-csr.generated';");
+            expect(runtimeWrite.content).toContain("export * from './runtime-ssr.generated';");
+        });
+    });
+    it('generates a client runtime bootstrap from explicit CEM loader imports', async () => {
+        await withTempDir(async (tempDir) => {
+            await writeFile(path.join(tempDir, 'custom-elements.json'), JSON.stringify({
+                modules: [{ declarations: [{ tagName: 'app-root' }] }],
+            }), 'utf8');
+            const config = {
+                dryRun: true,
+                projects: [
+                    {
+                        id: 'demo',
+                        adapter: 'stencil',
+                        adapterPackage: '@qwik-custom-elements/adapter-stencil',
+                        source: {
+                            type: 'CEM',
+                            path: './custom-elements.json',
+                        },
+                        outDir: './src/generated',
+                        adapterOptions: {
+                            runtime: {
+                                loaderImport: './runtime/acme-loader',
+                            },
+                        },
+                    },
+                ],
+            };
+            const result = await generateFromConfig(config, { cwd: tempDir });
+            const runtimeWrite = result.projects[0].plannedWrites.find((plannedWrite) => plannedWrite.path.endsWith(path.join('src', 'generated', 'runtime-csr.generated.ts')));
+            expect(runtimeWrite).toBeDefined();
+            expect(runtimeWrite.content).toContain("import { defineCustomElements as runtimeDefineCustomElements } from './runtime/acme-loader';");
+            expect(runtimeWrite.content).toContain("import { createStencilCSRComponent, createStencilClientSetup } from '@qwik-custom-elements/adapter-stencil/client';");
+            expect(runtimeWrite.content).toContain('export const useStencilClientSetup =');
+            expect(runtimeWrite.content).toContain('export const GeneratedStencilCSRComponent = createStencilCSRComponent();');
+        });
+    });
+    it('loads the lit adapter SSR subpath package without fallback warning', async () => {
+        await withTempDir(async (tempDir) => {
+            await writeFile(path.join(tempDir, 'custom-elements.json'), JSON.stringify({
+                modules: [{ declarations: [{ tagName: 'lit-button' }] }],
+            }), 'utf8');
+            const config = createSingleProjectConfig(tempDir, true);
+            config.projects[0].adapter = 'lit';
+            config.projects[0].adapterPackage =
+                '@qwik-custom-elements/adapter-lit/ssr';
+            const result = await generateFromConfig(config, { cwd: tempDir });
+            const litWrapperWrite = result.projects[0].plannedWrites.find((plannedWrite) => plannedWrite.path.endsWith(path.join('src', 'generated', 'lit-button.tsx')));
+            expect(result.projects[0].status).toBe('success');
+            expect(result.projects[0].componentTags).toEqual(['lit-button']);
+            expect(result.projects[0].ssrCapabilities).toEqual({
+                available: true,
+                supportsSsrProbe: true,
+                ssrRuntimeSubpath: './ssr',
+            });
+            expect(result.projects[0].observedErrorCodes).toEqual([]);
+            const indexWrite = result.projects[0].plannedWrites.find((plannedWrite) => plannedWrite.path.endsWith(path.join('src', 'generated', 'index.ts')));
+            expect(litWrapperWrite?.content).toContain('export const QwikLitButton = component$<QwikLitButtonProps>((props) => {');
+            expect(litWrapperWrite?.content).toContain('    <GeneratedLitComponent');
+            expect(litWrapperWrite?.content).not.toContain('QwikLitButtonSsrHtml');
+            expect(indexWrite?.content).toContain("export { QwikLitButton } from './lit-button';");
+            expect(indexWrite?.content).toContain("export const generatedMode = 'ssr' as const;");
+        });
+    });
+    it('generates generatedMode csr constant via real adapter-lit root entrypoint', async () => {
+        await withTempDir(async (tempDir) => {
+            await writeFile(path.join(tempDir, 'custom-elements.json'), JSON.stringify({
+                modules: [{ declarations: [{ tagName: 'lit-button' }] }],
+            }), 'utf8');
+            const config = {
+                dryRun: true,
+                projects: [
+                    {
+                        id: 'demo-lit-csr',
+                        adapter: 'lit',
+                        adapterPackage: '@qwik-custom-elements/adapter-lit',
+                        source: { type: 'CEM', path: './custom-elements.json' },
+                        outDir: './src/generated',
+                    },
+                ],
+            };
+            const result = await generateFromConfig(config, { cwd: tempDir });
+            expect(result.projects[0].status).toBe('success');
+            expect(result.projects[0].ssrCapabilities).toEqual({
+                available: false,
+                supportsSsrProbe: true,
+                ssrRuntimeSubpath: './ssr',
+            });
+            expect(result.projects[0].observedErrorCodes).toContain('QCE_SSR_UNSUPPORTED_FALLBACK');
+            const indexWrite = result.projects[0].plannedWrites.find((w) => w.path.endsWith(path.join('src', 'generated', 'index.ts')));
+            expect(indexWrite?.content).toContain("export const generatedMode = 'csr' as const;");
+        });
+    });
+    it('fails when adapter capabilities do not support the project source type', async () => {
+        await withTempDir(async (tempDir) => {
+            await writeFile(path.join(tempDir, 'custom-elements.json'), JSON.stringify({
+                modules: [{ declarations: [{ tagName: 'app-root' }] }],
+            }), 'utf8');
+            await writeFile(path.join(tempDir, 'adapter-package-name-only.mjs'), [
+                'export const metadata = {',
+                "  id: 'custom-adapter',",
+                "  supportedSourceTypes: ['PACKAGE_NAME'],",
+                '};',
+                '',
+                'export function createGeneratedOutput() {',
+                '  return [];',
+                '}',
+                '',
+            ].join('\n'), 'utf8');
+            const config = createSingleProjectConfig(tempDir, true);
+            config.projects[0].adapterPackage = './adapter-package-name-only.mjs';
+            await expect(generateFromConfig(config, { cwd: tempDir })).rejects.toMatchObject({
+                code: 'QCE_ADAPTER_SOURCE_INCOMPATIBLE',
+                message: 'Project "demo" source type "CEM" is not supported by adapter "./adapter-package-name-only.mjs".',
+            });
+        });
+    });
+    it('discovers CEM for PACKAGE_NAME mode when one canonical candidate exists', async () => {
+        await withTempDir(async (tempDir) => {
+            const packageName = '@demo/components';
+            const packageRoot = await createFixturePackage(tempDir, packageName);
+            await writeFile(path.join(packageRoot, 'custom-elements.json'), JSON.stringify({
+                modules: [{ declarations: [{ tagName: 'pkg-button' }] }],
+            }), 'utf8');
+            const config = createSingleProjectConfig(tempDir, true);
+            config.projects[0].adapterPackage = './adapter-package-name-only.mjs';
+            config.projects[0].source = {
+                type: 'PACKAGE_NAME',
+                packageName,
+            };
+            await writeFile(path.join(tempDir, 'adapter-package-name-only.mjs'), [
+                'export const metadata = {',
+                "  id: 'custom-adapter',",
+                "  supportedSourceTypes: ['PACKAGE_NAME'],",
+                '};',
+                '',
+                'export function createGeneratedOutput() {',
+                '  return [];',
+                '}',
+                '',
+            ].join('\n'), 'utf8');
+            const result = await generateFromConfig(config, { cwd: tempDir });
+            expect(result.projects[0].componentTags).toEqual(['pkg-button']);
+            expect(result.projects[0].sourcePath).toBe(path.join(packageRoot, 'custom-elements.json'));
+        });
+    });
+    it('fails with remediation guidance when PACKAGE_NAME CEM discovery finds no candidates', async () => {
+        await withTempDir(async (tempDir) => {
+            const packageName = '@demo/components';
+            await createFixturePackage(tempDir, packageName);
+            await writeFile(path.join(tempDir, 'adapter-package-name-only.mjs'), [
+                'export const metadata = {',
+                "  id: 'custom-adapter',",
+                "  supportedSourceTypes: ['PACKAGE_NAME'],",
+                '};',
+                '',
+            ].join('\n'), 'utf8');
+            const config = createSingleProjectConfig(tempDir, true);
+            config.projects[0].adapterPackage = './adapter-package-name-only.mjs';
+            config.projects[0].source = {
+                type: 'PACKAGE_NAME',
+                packageName,
+            };
+            await expect(generateFromConfig(config, { cwd: tempDir })).rejects.toMatchObject({
+                code: 'QCE_PACKAGE_NAME_CEM_NOT_FOUND',
+                message: expect.stringContaining('Set source.cemPath'),
+            });
+        });
+    });
+    it('fails deterministically when PACKAGE_NAME CEM discovery is ambiguous', async () => {
+        await withTempDir(async (tempDir) => {
+            const packageName = '@demo/components';
+            const packageRoot = await createFixturePackage(tempDir, packageName);
+            await writeFile(path.join(packageRoot, 'custom-elements.json'), JSON.stringify({ modules: [] }), 'utf8');
+            await mkdir(path.join(packageRoot, 'dist'), { recursive: true });
+            await writeFile(path.join(packageRoot, 'dist', 'custom-elements.json'), JSON.stringify({ modules: [] }), 'utf8');
+            await writeFile(path.join(tempDir, 'adapter-package-name-only.mjs'), [
+                'export const metadata = {',
+                "  id: 'custom-adapter',",
+                "  supportedSourceTypes: ['PACKAGE_NAME'],",
+                '};',
+                '',
+            ].join('\n'), 'utf8');
+            const config = createSingleProjectConfig(tempDir, true);
+            config.projects[0].adapterPackage = './adapter-package-name-only.mjs';
+            config.projects[0].source = {
+                type: 'PACKAGE_NAME',
+                packageName,
+            };
+            await expect(generateFromConfig(config, { cwd: tempDir })).rejects.toMatchObject({
+                code: 'QCE_PACKAGE_NAME_CEM_AMBIGUOUS',
+                message: expect.stringContaining('Set source.cemPath'),
+            });
+        });
+    });
+    it('rejects absolute PACKAGE_NAME cemPath override values', async () => {
+        await withTempDir(async (tempDir) => {
+            const packageName = '@demo/components';
+            const packageRoot = await createFixturePackage(tempDir, packageName);
+            const absoluteCemPath = path.join(packageRoot, 'custom-elements.json');
+            await writeFile(path.join(tempDir, 'adapter-package-name-only.mjs'), [
+                'export const metadata = {',
+                "  id: 'custom-adapter',",
+                "  supportedSourceTypes: ['PACKAGE_NAME'],",
+                '};',
+                '',
+            ].join('\n'), 'utf8');
+            const config = createSingleProjectConfig(tempDir, true);
+            config.projects[0].adapterPackage = './adapter-package-name-only.mjs';
+            config.projects[0].source = {
+                type: 'PACKAGE_NAME',
+                packageName,
+                cemPath: absoluteCemPath,
+            };
+            await expect(generateFromConfig(config, { cwd: tempDir })).rejects.toMatchObject({
+                code: 'QCE_PACKAGE_NAME_CEM_PATH_ABSOLUTE',
+            });
+        });
+    });
+    it('rejects PACKAGE_NAME cemPath overrides that escape package root', async () => {
+        await withTempDir(async (tempDir) => {
+            const packageName = '@demo/components';
+            await createFixturePackage(tempDir, packageName);
+            await writeFile(path.join(tempDir, 'adapter-package-name-only.mjs'), [
+                'export const metadata = {',
+                "  id: 'custom-adapter',",
+                "  supportedSourceTypes: ['PACKAGE_NAME'],",
+                '};',
+                '',
+            ].join('\n'), 'utf8');
+            const config = createSingleProjectConfig(tempDir, true);
+            config.projects[0].adapterPackage = './adapter-package-name-only.mjs';
+            config.projects[0].source = {
+                type: 'PACKAGE_NAME',
+                packageName,
+                cemPath: '../outside/custom-elements.json',
+            };
+            await expect(generateFromConfig(config, { cwd: tempDir })).rejects.toMatchObject({
+                code: 'QCE_PACKAGE_NAME_CEM_PATH_OUTSIDE_PACKAGE',
+            });
+        });
+    });
+    it('fails with deterministic code when CEM shape is invalid', async () => {
+        await withTempDir(async (tempDir) => {
+            await writeFile(path.join(tempDir, 'custom-elements.json'), JSON.stringify({ schemaVersion: '1.0.0' }), 'utf8');
+            const config = createSingleProjectConfig(tempDir, true);
+            await expect(generateFromConfig(config, { cwd: tempDir })).rejects.toMatchObject({
+                code: 'QCE_CEM_INVALID_SHAPE',
+                message: 'CEM at ' +
+                    path.join(tempDir, 'custom-elements.json') +
+                    ' must include a "modules" array.',
+            });
+        });
+    });
+    it('fails when a module declarations field is not an array', async () => {
+        await withTempDir(async (tempDir) => {
+            await writeFile(path.join(tempDir, 'custom-elements.json'), JSON.stringify({ modules: [{ declarations: 'not-an-array' }] }), 'utf8');
+            const config = createSingleProjectConfig(tempDir, true);
+            await expect(generateFromConfig(config, { cwd: tempDir })).rejects.toMatchObject({
+                code: 'QCE_CEM_INVALID_SHAPE',
+                message: 'CEM at ' +
+                    path.join(tempDir, 'custom-elements.json') +
+                    ' has invalid shape: modules[0].declarations must be an array when provided.',
+            });
+        });
+    });
+    it('fails when declaration tagName is present but not a non-empty string', async () => {
+        await withTempDir(async (tempDir) => {
+            await writeFile(path.join(tempDir, 'custom-elements.json'), JSON.stringify({ modules: [{ declarations: [{ tagName: '   ' }] }] }), 'utf8');
+            const config = createSingleProjectConfig(tempDir, true);
+            await expect(generateFromConfig(config, { cwd: tempDir })).rejects.toMatchObject({
+                code: 'QCE_CEM_INVALID_SHAPE',
+                message: 'CEM at ' +
+                    path.join(tempDir, 'custom-elements.json') +
+                    ' has invalid shape: modules[0].declarations[0].tagName must be a non-empty string when provided.',
+            });
+        });
+    });
+    it('fails with deterministic diagnostics when targeted project id does not exist', async () => {
+        await withTempDir(async (tempDir) => {
+            await writeFile(path.join(tempDir, 'custom-elements.json'), JSON.stringify({
+                modules: [{ declarations: [{ tagName: 'app-root' }] }],
+            }), 'utf8');
+            const config = createSingleProjectConfig(tempDir, true);
+            await expect(generateFromConfig(config, {
+                cwd: tempDir,
+                targetProjectIds: ['unknown-project'],
+            })).rejects.toMatchObject({
+                code: 'QCE_PROJECT_TARGET_UNKNOWN',
+                message: 'Unknown project id "unknown-project" requested via CLI targeting.',
+            });
+        });
+    });
+    it('executes multiple projects sequentially in deterministic id order', async () => {
+        await withTempDir(async (tempDir) => {
+            await writeFile(path.join(tempDir, 'custom-elements-a.json'), JSON.stringify({
+                modules: [{ declarations: [{ tagName: 'alpha-card' }] }],
+            }), 'utf8');
+            await writeFile(path.join(tempDir, 'custom-elements-z.json'), JSON.stringify({
+                modules: [{ declarations: [{ tagName: 'zeta-card' }] }],
+            }), 'utf8');
+            const config = {
+                dryRun: true,
+                projects: [
+                    {
+                        id: 'z-project',
+                        adapter: 'stencil',
+                        adapterPackage: '@qwik-custom-elements/adapter-stencil',
+                        source: { type: 'CEM', path: './custom-elements-z.json' },
+                        adapterOptions: validStencilAdapterOptions,
+                        outDir: './src/generated/z',
+                    },
+                    {
+                        id: 'a-project',
+                        adapter: 'stencil',
+                        adapterPackage: '@qwik-custom-elements/adapter-stencil',
+                        source: { type: 'CEM', path: './custom-elements-a.json' },
+                        adapterOptions: validStencilAdapterOptions,
+                        outDir: './src/generated/a',
+                    },
+                ],
+            };
+            const result = await generateFromConfig(config, { cwd: tempDir });
+            expect(result.projects.map((project) => project.projectId)).toEqual([
+                'a-project',
+                'z-project',
+            ]);
+            expect(result.projects[0].componentTags).toEqual(['alpha-card']);
+            expect(result.projects[1].componentTags).toEqual(['zeta-card']);
+        });
+    });
+    it('executes multiple projects in parallel mode with deterministic id ordering', async () => {
+        await withTempDir(async (tempDir) => {
+            await writeFile(path.join(tempDir, 'custom-elements-a.json'), JSON.stringify({
+                modules: [{ declarations: [{ tagName: 'alpha-card' }] }],
+            }), 'utf8');
+            await writeFile(path.join(tempDir, 'custom-elements-z.json'), JSON.stringify({
+                modules: [{ declarations: [{ tagName: 'zeta-card' }] }],
+            }), 'utf8');
+            const config = {
+                dryRun: true,
+                parallel: true,
+                projects: [
+                    {
+                        id: 'z-project',
+                        adapter: 'stencil',
+                        adapterPackage: '@qwik-custom-elements/adapter-stencil',
+                        source: { type: 'CEM', path: './custom-elements-z.json' },
+                        adapterOptions: validStencilAdapterOptions,
+                        outDir: './src/generated/z',
+                    },
+                    {
+                        id: 'a-project',
+                        adapter: 'stencil',
+                        adapterPackage: '@qwik-custom-elements/adapter-stencil',
+                        source: { type: 'CEM', path: './custom-elements-a.json' },
+                        adapterOptions: validStencilAdapterOptions,
+                        outDir: './src/generated/a',
+                    },
+                ],
+            };
+            const result = await generateFromConfig(config, { cwd: tempDir });
+            expect(result.projects.map((project) => project.projectId)).toEqual([
+                'a-project',
+                'z-project',
+            ]);
+            expect(result.projects[0].componentTags).toEqual(['alpha-card']);
+            expect(result.projects[1].componentTags).toEqual(['zeta-card']);
+        });
+    });
+    it('aggregates all project failures in parallel mode', async () => {
+        await withTempDir(async (tempDir) => {
+            await writeFile(path.join(tempDir, 'custom-elements-valid.json'), JSON.stringify({
+                modules: [{ declarations: [{ tagName: 'alpha-card' }] }],
+            }), 'utf8');
+            const config = {
+                dryRun: true,
+                parallel: true,
+                projects: [
+                    {
+                        id: 'b-missing-project',
+                        adapter: 'stencil',
+                        adapterPackage: '@qwik-custom-elements/adapter-stencil',
+                        source: { type: 'CEM', path: './custom-elements-missing-b.json' },
+                        adapterOptions: validStencilAdapterOptions,
+                        outDir: './src/generated/b',
+                    },
+                    {
+                        id: 'a-valid-project',
+                        adapter: 'stencil',
+                        adapterPackage: '@qwik-custom-elements/adapter-stencil',
+                        source: { type: 'CEM', path: './custom-elements-valid.json' },
+                        adapterOptions: validStencilAdapterOptions,
+                        outDir: './src/generated/a',
+                    },
+                    {
+                        id: 'c-missing-project',
+                        adapter: 'stencil',
+                        adapterPackage: '@qwik-custom-elements/adapter-stencil',
+                        source: { type: 'CEM', path: './custom-elements-missing-c.json' },
+                        adapterOptions: validStencilAdapterOptions,
+                        outDir: './src/generated/c',
+                    },
+                ],
+            };
+            await expect(generateFromConfig(config, { cwd: tempDir })).rejects.toMatchObject({
+                code: 'QCE_PARALLEL_PROJECT_FAILURES',
+                message: expect.stringContaining('b-missing-project'),
+            });
+            await expect(generateFromConfig(config, { cwd: tempDir })).rejects.toMatchObject({
+                message: expect.stringContaining('c-missing-project'),
+            });
+            await expect(generateFromConfig(config, { cwd: tempDir })).rejects.toMatchObject({
+                message: expect.stringContaining('QCE_CEM_READ_FAILED'),
+            });
+        });
+    });
+    it('rejects output paths that resolve outside the workspace root', async () => {
+        await withTempDir(async (tempDir) => {
+            await writeFile(path.join(tempDir, 'custom-elements.json'), JSON.stringify({
+                modules: [{ declarations: [{ tagName: 'app-root' }] }],
+            }), 'utf8');
+            const config = createSingleProjectConfig(tempDir, true);
+            config.projects[0].outDir = '../outside-generated';
+            await expect(generateFromConfig(config, { cwd: tempDir })).rejects.toMatchObject({
+                code: 'QCE_OUTPUT_OUTSIDE_WORKSPACE',
+                message: 'Project "demo" output path resolves outside workspace root: ../outside-generated',
+            });
+        });
+    });
+    it('fails when multiple projects resolve to the same output directory', async () => {
+        await withTempDir(async (tempDir) => {
+            await writeFile(path.join(tempDir, 'custom-elements.json'), JSON.stringify({
+                modules: [{ declarations: [{ tagName: 'app-root' }] }],
+            }), 'utf8');
+            const config = {
+                dryRun: true,
+                projects: [
+                    {
+                        id: 'a-project',
+                        adapter: 'stencil',
+                        adapterPackage: '@qwik-custom-elements/adapter-stencil',
+                        source: { type: 'CEM', path: './custom-elements.json' },
+                        outDir: './src/generated',
+                    },
+                    {
+                        id: 'b-project',
+                        adapter: 'stencil',
+                        adapterPackage: '@qwik-custom-elements/adapter-stencil',
+                        source: { type: 'CEM', path: './custom-elements.json' },
+                        outDir: './src/../src/generated',
+                    },
+                ],
+            };
+            await expect(generateFromConfig(config, { cwd: tempDir })).rejects.toMatchObject({
+                code: 'QCE_OUTPUT_PATH_COLLISION',
+                message: 'Projects "a-project" and "b-project" resolve to the same output directory: ' +
+                    path.resolve(tempDir, 'src/generated'),
+            });
+        });
+    });
+    describe('augmentComponentDefinitions adapter hook', () => {
+        it('calls augmentComponentDefinitions when exported and passes enriched slots to createGeneratedOutput', async () => {
+            await withTempDir(async (tempDir) => {
+                await writeFile(path.join(tempDir, 'custom-elements.json'), JSON.stringify({
+                    modules: [{ declarations: [{ tagName: 'app-root' }] }],
+                }), 'utf8');
+                await writeFile(path.join(tempDir, 'adapter-with-augment.mjs'), [
+                    'export const metadata = {',
+                    "  supportedSourceTypes: ['CEM', 'PACKAGE_NAME'],",
+                    '  supportsSsrProbe: false,',
+                    '  ssrRuntimeSubpath: null,',
+                    '};',
+                    '',
+                    'export async function augmentComponentDefinitions({ componentDefinitions }) {',
+                    '  return componentDefinitions.map((def) => ({',
+                    '    ...def,',
+                    "    slots: [...def.slots, { name: 'probe-injected' }],",
+                    '  }));',
+                    '}',
+                    '',
+                    'export function createGeneratedOutput({ componentDefinitions }) {',
+                    '  return componentDefinitions.map((def) => ({',
+                    '    relativePath: `${def.tagName}.txt`,',
+                    '    content: def.slots.map((s) => s.name).join(","),',
+                    '  }));',
+                    '}',
+                    '',
+                ].join('\n'), 'utf8');
+                const config = {
+                    dryRun: true,
+                    projects: [
+                        {
+                            id: 'demo',
+                            adapter: 'stencil',
+                            adapterPackage: `${pathToFileURL(path.join(tempDir, 'adapter-with-augment.mjs'))}`,
+                            source: { type: 'CEM', path: './custom-elements.json' },
+                            outDir: './src/generated',
+                        },
+                    ],
+                };
+                const result = await generateFromConfig(config, { cwd: tempDir });
+                expect(result.projects[0].plannedWrites).toEqual([
+                    expect.objectContaining({
+                        path: path.join(tempDir, 'src', 'generated', 'app-root.txt'),
+                        content: 'probe-injected',
+                    }),
+                ]);
+            });
+        });
+        it('skips augmentComponentDefinitions when adapter does not export it', async () => {
+            await withTempDir(async (tempDir) => {
+                await writeFile(path.join(tempDir, 'custom-elements.json'), JSON.stringify({
+                    modules: [{ declarations: [{ tagName: 'app-root' }] }],
+                }), 'utf8');
+                await writeFile(path.join(tempDir, 'adapter-without-augment.mjs'), [
+                    'export const metadata = {',
+                    "  supportedSourceTypes: ['CEM', 'PACKAGE_NAME'],",
+                    '  supportsSsrProbe: false,',
+                    '  ssrRuntimeSubpath: null,',
+                    '};',
+                    '',
+                    'export function createGeneratedOutput({ componentDefinitions }) {',
+                    '  return componentDefinitions.map((def) => ({',
+                    '    relativePath: `${def.tagName}.txt`,',
+                    '    content: def.slots.map((s) => s.name).join(","),',
+                    '  }));',
+                    '}',
+                    '',
+                ].join('\n'), 'utf8');
+                const config = {
+                    dryRun: true,
+                    projects: [
+                        {
+                            id: 'demo',
+                            adapter: 'stencil',
+                            adapterPackage: `${pathToFileURL(path.join(tempDir, 'adapter-without-augment.mjs'))}`,
+                            source: { type: 'CEM', path: './custom-elements.json' },
+                            outDir: './src/generated',
+                        },
+                    ],
+                };
+                const result = await generateFromConfig(config, { cwd: tempDir });
+                expect(result.projects[0].plannedWrites).toEqual([
+                    expect.objectContaining({
+                        path: path.join(tempDir, 'src', 'generated', 'app-root.txt'),
+                        content: '',
+                    }),
+                ]);
+            });
+        });
+    });
+});