@knighted/css 1.1.0 → 1.2.0-rc.0

package/README.md

@@ -30,7 +30,7 @@ I needed a single source of truth for UI components that could drop into both li
 - Deterministic selector duplication via `autoStable`: duplicate matching class selectors with a stable namespace (default `knighted-`) in both plain CSS and CSS Modules exports.
 - Pluggable resolver/filter hooks for custom module resolution (e.g., Rspack/Vite/webpack aliases) or selective inclusion.
 - First-class loader (`@knighted/css/loader`) so bundlers can import compiled CSS alongside their modules via `?knighted-css`.
-- Built-in type generation CLI (`knighted-css-generate-types`) that emits `.knighted-css.*` selector manifests so TypeScript gets literal tokens in lockstep with the loader exports.
+- Built-in type generation CLI (`knighted-css-generate-types`) that emits `.knighted-css.*` selector manifests (module mode) or declaration augmentations (declaration mode) so TypeScript stays in lockstep with loader exports.
 
 ## Requirements
 
@@ -107,7 +107,7 @@ See [docs/loader.md](../../docs/loader.md) for the full configuration, combined
 
 ### Type generation hook (`*.knighted-css*`)
 
-Run `knighted-css-generate-types` so every specifier that ends with `.knighted-css` produces a sibling manifest containing literal selector tokens:
+Run `knighted-css-generate-types` so every specifier that ends with `.knighted-css` produces a sibling manifest containing literal selector tokens (module mode, the default):
 
 ```ts
 import stableSelectors from './button.module.scss.knighted-css.js'
@@ -137,6 +137,58 @@ selectors.card // hashed CSS Modules class name
 > `--hashed` requires wiring `@knighted/css/loader-bridge` to handle `?knighted-css` queries so
 > the generated proxies can read `knightedCss` and `knightedCssModules` at build time.
 
+> [!NOTE]
+> `--hashed` builds the selector list from compiled CSS. The generated sidecar can therefore
+> include class names that are not exported by the module (e.g. sprinkles output), while the
+> runtime `selectors` map only includes exported locals from the loader bridge.
+
+Prefer module-level imports without the double extension? Use declaration mode to emit `.d.ts` augmentations next to JS/TS modules that import styles:
+
+```sh
+knighted-css-generate-types --root . --include src --mode declaration
+```
+
+```ts
+import Button, { knightedCss, stableSelectors } from './button.js'
+```
+
+See [docs/type-generation.md](../../docs/type-generation.md#mode-quick-reference) for a quick comparison of module vs declaration mode tradeoffs.
+
+> [!IMPORTANT]
+> Declaration mode requires a resolver plugin to append `?knighted-css` (and `&combined` when applicable)
+> at build time so runtime exports match the generated types.
+
+Install the resolver plugin via `@knighted/css/plugin` and wire it into your bundler resolver:
+
+```js
+// rspack.config.js
+import { knightedCssResolverPlugin } from '@knighted/css/plugin'
+
+export default {
+  resolve: {
+    plugins: [knightedCssResolverPlugin()],
+  },
+}
+```
+
+If you want the resolver to only match sidecars generated by the CLI, enable strict mode and provide a manifest (written by `knighted-css-generate-types --manifest`):
+
+```js
+import path from 'node:path'
+import { knightedCssResolverPlugin } from '@knighted/css/plugin'
+
+export default {
+  resolve: {
+    plugins: [
+      knightedCssResolverPlugin({
+        strictSidecar: true,
+        manifestPath: path.resolve('.knighted-css/knighted-manifest.json'),
+      }),
+    ],
+  },
+}
+```
+
 Refer to [docs/type-generation.md](../../docs/type-generation.md) for CLI options and workflow tips.
 
 ### Combined + runtime selectors

package/dist/cjs/generateTypes.cjs

@@ -66,6 +66,7 @@ function getImportMetaUrl() {
 }
 const SELECTOR_REFERENCE = '.knighted-css';
 const SELECTOR_MODULE_SUFFIX = '.knighted-css.ts';
+const DECLARATION_SUFFIX = '.d.ts';
 const STYLE_EXTENSIONS = css_js_1.DEFAULT_EXTENSIONS.map(ext => ext.toLowerCase());
 const SCRIPT_EXTENSIONS = Array.from(SUPPORTED_EXTENSIONS);
 const RESOLUTION_EXTENSIONS = Array.from(new Set([...SCRIPT_EXTENSIONS, ...STYLE_EXTENSIONS]));
@@ -75,11 +76,16 @@ const EXTENSION_FALLBACKS = {
     '.cjs': ['.cts', '.cjs', '.js', '.ts', '.tsx'],
     '.jsx': ['.tsx', '.jsx'],
 };
+const DECLARATION_MODE_WARNING = 'Declaration mode requires a resolver plugin to append ?knighted-css (and &combined when applicable) so runtime exports match the generated types.';
 async function generateTypes(options = {}) {
     const rootDir = await resolveRootDir(node_path_1.default.resolve(options.rootDir ?? process.cwd()));
     const include = normalizeIncludeOptions(options.include, rootDir);
     const cacheDir = node_path_1.default.resolve(options.outDir ?? node_path_1.default.join(rootDir, '.knighted-css'));
     const tsconfig = loadTsconfigResolutionContext(rootDir);
+    const mode = options.mode ?? 'module';
+    const manifestPath = options.manifestPath
+        ? node_path_1.default.resolve(rootDir, options.manifestPath)
+        : undefined;
     await promises_1.default.mkdir(cacheDir, { recursive: true });
     const internalOptions = {
         rootDir,
@@ -90,6 +96,8 @@ async function generateTypes(options = {}) {
         hashed: options.hashed,
         tsconfig,
         resolver: options.resolver,
+        mode,
+        manifestPath,
     };
     return generateDeclarations(internalOptions);
 }
@@ -108,79 +116,176 @@ async function generateDeclarations(options) {
     const selectorModulesManifestPath = node_path_1.default.join(options.cacheDir, 'selector-modules.json');
     const previousSelectorManifest = await readManifest(selectorModulesManifestPath);
     const nextSelectorManifest = {};
+    const sidecarManifest = {};
     const selectorCache = new Map();
     const processedSelectors = new Set();
     const proxyInfoCache = new Map();
     const warnings = [];
     let selectorModuleWrites = 0;
-    for (const filePath of files) {
-        const matches = await findSpecifierImports(filePath);
-        for (const match of matches) {
-            const cleaned = match.specifier.trim();
-            const inlineFree = stripInlineLoader(cleaned);
-            const { resource } = splitResourceAndQuery(inlineFree);
-            const selectorSource = extractSelectorSourceSpecifier(resource);
-            if (!selectorSource) {
+    if (options.mode === 'declaration') {
+        warnings.push(DECLARATION_MODE_WARNING);
+    }
+    if (options.mode === 'declaration') {
+        for (const filePath of files) {
+            if (!isScriptResource(filePath)) {
                 continue;
             }
-            const resolvedNamespace = (0, stableNamespace_js_1.resolveStableNamespace)(options.stableNamespace);
-            const resolvedPath = await resolveImportPath(selectorSource, match.importer, options.rootDir, options.tsconfig, options.resolver, resolverFactory, RESOLUTION_EXTENSIONS);
-            if (!resolvedPath) {
-                warnings.push(`Unable to resolve ${selectorSource} referenced by ${relativeToRoot(match.importer, options.rootDir)}.`);
+            if (!isWithinRoot(filePath, options.rootDir)) {
+                warnings.push(`Skipping declaration output for ${relativeToRoot(filePath, options.rootDir)} because it is outside the project root.`);
+                continue;
+            }
+            const manifestKey = buildSelectorModuleManifestKey(filePath);
+            if (processedSelectors.has(manifestKey)) {
+                continue;
+            }
+            const hasStyles = await hasStyleImports(filePath, {
+                rootDir: options.rootDir,
+                tsconfig: options.tsconfig,
+                resolver: options.resolver,
+                resolverFactory,
+            });
+            if (!hasStyles) {
+                processedSelectors.add(manifestKey);
                 continue;
             }
-            const cacheKey = `${resolvedPath}::${resolvedNamespace}`;
+            const resolvedNamespace = (0, stableNamespace_js_1.resolveStableNamespace)(options.stableNamespace);
+            const cacheKey = `${filePath}::${resolvedNamespace}::declaration`;
             let selectorMap = selectorCache.get(cacheKey);
             if (!selectorMap) {
                 try {
-                    const shouldUseCssModules = resolvedPath.endsWith('.module.css');
-                    const { css } = await activeCssWithMeta(resolvedPath, {
+                    let cssResult = await activeCssWithMeta(filePath, {
                         cwd: options.rootDir,
                         peerResolver,
                         autoStable: options.autoStable ? { namespace: resolvedNamespace } : undefined,
-                        lightningcss: options.autoStable && shouldUseCssModules
-                            ? { cssModules: true }
-                            : undefined,
                         resolver: options.resolver,
                     });
+                    if (cssResult.files.length === 0 || cssResult.css.trim().length === 0) {
+                        processedSelectors.add(manifestKey);
+                        continue;
+                    }
+                    if (options.autoStable &&
+                        cssResult.files.some(file => isCssModuleResource(file))) {
+                        cssResult = await activeCssWithMeta(filePath, {
+                            cwd: options.rootDir,
+                            peerResolver,
+                            autoStable: options.autoStable
+                                ? { namespace: resolvedNamespace }
+                                : undefined,
+                            lightningcss: { cssModules: true },
+                            resolver: options.resolver,
+                        });
+                    }
                     selectorMap = options.hashed
-                        ? collectSelectorTokensFromCss(css)
+                        ? collectSelectorTokensFromCss(cssResult.css)
                         : (0, stableSelectorsLiteral_js_1.buildStableSelectorsLiteral)({
-                            css,
+                            css: cssResult.css,
                             namespace: resolvedNamespace,
-                            resourcePath: resolvedPath,
+                            resourcePath: filePath,
                             emitWarning: message => warnings.push(message),
                         }).selectorMap;
                 }
                 catch (error) {
-                    warnings.push(`Failed to extract CSS for ${relativeToRoot(resolvedPath, options.rootDir)}: ${formatErrorMessage(error)}`);
+                    warnings.push(`Failed to extract CSS for ${relativeToRoot(filePath, options.rootDir)}: ${formatErrorMessage(error)}`);
+                    processedSelectors.add(manifestKey);
                     continue;
                 }
                 selectorCache.set(cacheKey, selectorMap);
             }
-            if (!isWithinRoot(resolvedPath, options.rootDir)) {
-                warnings.push(`Skipping selector module for ${relativeToRoot(resolvedPath, options.rootDir)} because it is outside the project root.`);
+            if (!selectorMap || selectorMap.size === 0) {
+                processedSelectors.add(manifestKey);
                 continue;
             }
-            const manifestKey = buildSelectorModuleManifestKey(resolvedPath);
-            if (processedSelectors.has(manifestKey)) {
+            const proxyInfo = await resolveDeclarationProxyInfo(manifestKey, filePath, proxyInfoCache);
+            if (!proxyInfo) {
+                processedSelectors.add(manifestKey);
                 continue;
             }
-            const proxyInfo = await resolveProxyInfo(manifestKey, selectorSource, resolvedPath, proxyInfoCache);
-            const moduleWrite = await ensureSelectorModule(resolvedPath, selectorMap, previousSelectorManifest, nextSelectorManifest, selectorSource, proxyInfo ?? undefined, options.hashed ?? false);
+            const moduleWrite = await ensureDeclarationModule(filePath, selectorMap, previousSelectorManifest, nextSelectorManifest, proxyInfo, options.hashed ?? false);
+            if (options.manifestPath) {
+                sidecarManifest[manifestKey] = { file: buildDeclarationPath(filePath) };
+            }
             if (moduleWrite) {
                 selectorModuleWrites += 1;
             }
             processedSelectors.add(manifestKey);
         }
     }
+    else {
+        for (const filePath of files) {
+            const matches = await findSpecifierImports(filePath);
+            for (const match of matches) {
+                const cleaned = match.specifier.trim();
+                const inlineFree = stripInlineLoader(cleaned);
+                const { resource } = splitResourceAndQuery(inlineFree);
+                const selectorSource = extractSelectorSourceSpecifier(resource);
+                if (!selectorSource) {
+                    continue;
+                }
+                const resolvedNamespace = (0, stableNamespace_js_1.resolveStableNamespace)(options.stableNamespace);
+                const resolvedPath = await resolveImportPath(selectorSource, match.importer, options.rootDir, options.tsconfig, options.resolver, resolverFactory, RESOLUTION_EXTENSIONS);
+                if (!resolvedPath) {
+                    warnings.push(`Unable to resolve ${selectorSource} referenced by ${relativeToRoot(match.importer, options.rootDir)}.`);
+                    continue;
+                }
+                const cacheKey = `${resolvedPath}::${resolvedNamespace}`;
+                let selectorMap = selectorCache.get(cacheKey);
+                if (!selectorMap) {
+                    try {
+                        const shouldUseCssModules = resolvedPath.endsWith('.module.css');
+                        const { css } = await activeCssWithMeta(resolvedPath, {
+                            cwd: options.rootDir,
+                            peerResolver,
+                            autoStable: options.autoStable
+                                ? { namespace: resolvedNamespace }
+                                : undefined,
+                            lightningcss: options.autoStable && shouldUseCssModules
+                                ? { cssModules: true }
+                                : undefined,
+                            resolver: options.resolver,
+                        });
+                        selectorMap = options.hashed
+                            ? collectSelectorTokensFromCss(css)
+                            : (0, stableSelectorsLiteral_js_1.buildStableSelectorsLiteral)({
+                                css,
+                                namespace: resolvedNamespace,
+                                resourcePath: resolvedPath,
+                                emitWarning: message => warnings.push(message),
+                            }).selectorMap;
+                    }
+                    catch (error) {
+                        warnings.push(`Failed to extract CSS for ${relativeToRoot(resolvedPath, options.rootDir)}: ${formatErrorMessage(error)}`);
+                        continue;
+                    }
+                    selectorCache.set(cacheKey, selectorMap);
+                }
+                if (!isWithinRoot(resolvedPath, options.rootDir)) {
+                    warnings.push(`Skipping selector module for ${relativeToRoot(resolvedPath, options.rootDir)} because it is outside the project root.`);
+                    continue;
+                }
+                const manifestKey = buildSelectorModuleManifestKey(resolvedPath);
+                if (processedSelectors.has(manifestKey)) {
+                    continue;
+                }
+                const proxyInfo = await resolveProxyInfo(manifestKey, selectorSource, resolvedPath, proxyInfoCache);
+                const moduleWrite = await ensureSelectorModule(resolvedPath, selectorMap, previousSelectorManifest, nextSelectorManifest, selectorSource, proxyInfo ?? undefined, options.hashed ?? false);
+                if (moduleWrite) {
+                    selectorModuleWrites += 1;
+                }
+                processedSelectors.add(manifestKey);
+            }
+        }
+    }
     const selectorModulesRemoved = await removeStaleSelectorModules(previousSelectorManifest, nextSelectorManifest);
     await writeManifest(selectorModulesManifestPath, nextSelectorManifest);
+    if (options.manifestPath && options.mode === 'declaration') {
+        await writeSidecarManifest(options.manifestPath, sidecarManifest);
+    }
     return {
         selectorModulesWritten: selectorModuleWrites,
         selectorModulesRemoved,
         warnings,
         manifestPath: selectorModulesManifestPath,
+        sidecarManifestPath: options.mode === 'declaration' ? options.manifestPath : undefined,
     };
 }
 function normalizeIncludeOptions(include, rootDir) {
@@ -359,6 +464,50 @@ function buildSelectorModulePath(resolvedPath) {
     const base = ext ? resolvedPath.slice(0, -ext.length) : resolvedPath;
     return `${base}${SELECTOR_MODULE_SUFFIX}`;
 }
+function buildDeclarationModuleSpecifier(resolvedPath) {
+    const ext = node_path_1.default.extname(resolvedPath).toLowerCase();
+    const baseName = node_path_1.default.basename(resolvedPath, ext);
+    const mappedExt = ext === '.mjs' || ext === '.mts'
+        ? '.mjs'
+        : ext === '.cjs' || ext === '.cts'
+            ? '.cjs'
+            : '.js';
+    return `./${baseName}${mappedExt}`;
+}
+function buildDeclarationPath(resolvedPath) {
+    if (resolvedPath.endsWith(DECLARATION_SUFFIX)) {
+        return resolvedPath;
+    }
+    return `${resolvedPath}${DECLARATION_SUFFIX}`;
+}
+function formatSelectorTypeLiteral(selectors) {
+    const entries = Array.from(selectors.keys()).sort((a, b) => a.localeCompare(b));
+    const typeLines = entries.map(token => `    readonly ${JSON.stringify(token)}: string`);
+    return typeLines.length > 0
+        ? `{
+${typeLines.join('\n')}
+  }`
+        : 'Record<string, string>';
+}
+function formatDeclarationSource(selectors, proxyInfo, options = {}) {
+    const header = '// Generated by @knighted/css/generate-types\n// Do not edit.';
+    const isHashed = options.hashed === true;
+    const marker = isHashed ? '// @knighted-css:hashed' : '// @knighted-css';
+    const exportName = isHashed ? 'selectors' : 'stableSelectors';
+    const typeLiteral = formatSelectorTypeLiteral(selectors);
+    const shouldEmit = (name) => !proxyInfo.exportedNames?.has(name);
+    const lines = [
+        header,
+        marker,
+        '',
+        `declare module '${proxyInfo.moduleSpecifier}' {`,
+        shouldEmit('knightedCss') ? '  export const knightedCss: string' : '',
+        shouldEmit(exportName) ? `  export const ${exportName}: ${typeLiteral}` : '',
+        '}',
+        'export {}',
+    ].filter(Boolean);
+    return `${lines.join('\n')}\n`;
+}
 function formatSelectorModuleSource(selectors, proxyInfo, options = {}) {
     const header = '// Generated by @knighted/css/generate-types\n// Do not edit.';
     const entries = Array.from(selectors.entries()).sort(([a], [b]) => a.localeCompare(b));
@@ -436,6 +585,10 @@ async function readManifest(manifestPath) {
 async function writeManifest(manifestPath, manifest) {
     await promises_1.default.writeFile(manifestPath, JSON.stringify(manifest, null, 2), 'utf8');
 }
+async function writeSidecarManifest(manifestPath, manifest) {
+    await promises_1.default.mkdir(node_path_1.default.dirname(manifestPath), { recursive: true });
+    await promises_1.default.writeFile(manifestPath, JSON.stringify(manifest, null, 2), 'utf8');
+}
 async function removeStaleSelectorModules(previous, next) {
     const stale = Object.entries(previous).filter(([key]) => !next[key]);
     let removed = 0;
@@ -480,6 +633,19 @@ async function ensureSelectorModule(resolvedPath, selectors, previousManifest, n
     nextManifest[manifestKey] = { file: targetPath, hash };
     return needsWrite;
 }
+async function ensureDeclarationModule(resolvedPath, selectors, previousManifest, nextManifest, proxyInfo, hashed) {
+    const manifestKey = buildSelectorModuleManifestKey(resolvedPath);
+    const targetPath = buildDeclarationPath(resolvedPath);
+    const source = formatDeclarationSource(selectors, proxyInfo, { hashed });
+    const hash = hashContent(source);
+    const previousEntry = previousManifest[manifestKey];
+    const needsWrite = previousEntry?.hash !== hash || !(await fileExists(targetPath));
+    if (needsWrite) {
+        await promises_1.default.writeFile(targetPath, source, 'utf8');
+    }
+    nextManifest[manifestKey] = { file: targetPath, hash };
+    return needsWrite;
+}
 async function fileExists(target) {
     try {
         await promises_1.default.access(target);
@@ -621,6 +787,60 @@ function isStyleResource(filePath) {
     const normalized = filePath.toLowerCase();
     return STYLE_EXTENSIONS.some(ext => normalized.endsWith(ext));
 }
+function isCssModuleResource(filePath) {
+    return /\.module\.(css|scss|sass|less)$/i.test(filePath);
+}
+function isScriptResource(filePath) {
+    const normalized = filePath.toLowerCase();
+    if (normalized.endsWith('.d.ts')) {
+        return false;
+    }
+    return SCRIPT_EXTENSIONS.some(ext => normalized.endsWith(ext));
+}
+async function hasStyleImports(filePath, options) {
+    let source;
+    try {
+        source = await promises_1.default.readFile(filePath, 'utf8');
+    }
+    catch {
+        return false;
+    }
+    const candidates = new Set();
+    try {
+        const analysis = await (0, lexer_js_1.analyzeModule)(source, filePath);
+        for (const specifier of analysis.imports) {
+            if (specifier) {
+                candidates.add(specifier);
+            }
+        }
+    }
+    catch {
+        // fall back to regex scanning below
+    }
+    const importRegex = /(import|require)\s*(?:\(|[^'"`]*)(['"])([^'"`]+)\2/g;
+    let match;
+    while ((match = importRegex.exec(source)) !== null) {
+        const specifier = match[3];
+        if (specifier) {
+            candidates.add(specifier);
+        }
+    }
+    for (const specifier of candidates) {
+        const cleaned = stripInlineLoader(specifier.trim());
+        const { resource } = splitResourceAndQuery(cleaned);
+        if (!resource) {
+            continue;
+        }
+        if (isStyleResource(resource)) {
+            return true;
+        }
+        const resolved = await resolveImportPath(resource, filePath, options.rootDir, options.tsconfig, options.resolver, options.resolverFactory, RESOLUTION_EXTENSIONS);
+        if (resolved && isStyleResource(resolved)) {
+            return true;
+        }
+    }
+    return false;
+}
 function collectSelectorTokensFromCss(css) {
     const tokens = new Set();
     const pattern = /\.([A-Za-z_-][A-Za-z0-9_-]*)\b/g;
@@ -653,6 +873,21 @@ async function resolveProxyInfo(manifestKey, selectorSource, resolvedPath, cache
     cache.set(manifestKey, proxyInfo);
     return proxyInfo;
 }
+async function resolveDeclarationProxyInfo(manifestKey, resolvedPath, cache) {
+    const cached = cache.get(manifestKey);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const defaultSignal = await getDefaultExportSignal(resolvedPath);
+    const exportedNames = await getNamedExports(resolvedPath);
+    const proxyInfo = {
+        moduleSpecifier: buildDeclarationModuleSpecifier(resolvedPath),
+        includeDefault: defaultSignal === 'has-default',
+        exportedNames,
+    };
+    cache.set(manifestKey, proxyInfo);
+    return proxyInfo;
+}
 function buildProxyModuleSpecifier(resolvedPath, selectorSource) {
     const resolvedExt = node_path_1.default.extname(resolvedPath);
     const baseName = node_path_1.default.basename(resolvedPath, resolvedExt);
@@ -670,6 +905,16 @@ async function getDefaultExportSignal(filePath) {
         return 'unknown';
     }
 }
+async function getNamedExports(filePath) {
+    try {
+        const source = await promises_1.default.readFile(filePath, 'utf8');
+        const analysis = await (0, lexer_js_1.analyzeModule)(source, filePath);
+        return new Set(analysis.exports ?? []);
+    }
+    catch {
+        return new Set();
+    }
+}
 function createProjectPeerResolver(rootDir) {
     const resolver = getProjectRequire(rootDir);
     return async (name) => {
@@ -742,6 +987,8 @@ async function runGenerateTypesCli(argv = process.argv.slice(2)) {
             autoStable: parsed.autoStable,
             hashed: parsed.hashed,
             resolver,
+            mode: parsed.mode,
+            manifestPath: parsed.manifestPath,
         });
         reportCliResult(result);
     }
@@ -759,10 +1006,20 @@ function parseCliArgs(argv) {
     let autoStable = false;
     let hashed = false;
     let resolver;
+    let mode = 'module';
+    let manifestPath;
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
         if (arg === '--help' || arg === '-h') {
-            return { rootDir, include, outDir, stableNamespace, autoStable, help: true };
+            return {
+                rootDir,
+                include,
+                outDir,
+                stableNamespace,
+                autoStable,
+                mode,
+                help: true,
+            };
         }
         if (arg === '--auto-stable') {
             autoStable = true;
@@ -796,6 +1053,14 @@ function parseCliArgs(argv) {
             outDir = value;
             continue;
         }
+        if (arg === '--manifest') {
+            const value = argv[++i];
+            if (!value) {
+                throw new Error('Missing value for --manifest');
+            }
+            manifestPath = value;
+            continue;
+        }
         if (arg === '--stable-namespace') {
             const value = argv[++i];
             if (!value) {
@@ -812,6 +1077,17 @@ function parseCliArgs(argv) {
             resolver = value;
             continue;
         }
+        if (arg === '--mode') {
+            const value = argv[++i];
+            if (!value) {
+                throw new Error('Missing value for --mode');
+            }
+            if (value !== 'module' && value !== 'declaration') {
+                throw new Error(`Unknown mode: ${value}`);
+            }
+            mode = value;
+            continue;
+        }
         if (arg.startsWith('-')) {
             throw new Error(`Unknown flag: ${arg}`);
         }
@@ -820,20 +1096,35 @@ function parseCliArgs(argv) {
     if (autoStable && hashed) {
         throw new Error('Cannot combine --auto-stable with --hashed');
     }
-    return { rootDir, include, outDir, stableNamespace, autoStable, hashed, resolver };
+    if (manifestPath && mode !== 'declaration') {
+        throw new Error('Cannot use --manifest unless --mode is declaration');
+    }
+    return {
+        rootDir,
+        include,
+        outDir,
+        stableNamespace,
+        autoStable,
+        hashed,
+        resolver,
+        mode,
+        manifestPath,
+    };
 }
 function printHelp() {
     console.log(`Usage: knighted-css-generate-types [options]
 
 Options:
-  -r, --root <path>              Project root directory (default: cwd)
-  -i, --include <path>           Additional directories/files to scan (repeatable)
-      --out-dir <path>           Directory to store selector module manifest cache
-      --stable-namespace <name>  Stable namespace prefix for generated selector maps
-      --auto-stable              Enable autoStable when extracting CSS for selectors
-      --hashed                   Emit selectors backed by loader-bridge hashed modules
-      --resolver <path>          Path or package name exporting a CssResolver
-  -h, --help                     Show this help message
+  -r, --root <path>                Project root directory (default: cwd)
+  -i, --include <path>             Additional directories/files to scan (repeatable)
+      --out-dir <path>             Directory to store selector module manifest cache
+      --stable-namespace <name>    Stable namespace prefix for generated selector maps
+      --auto-stable                Enable autoStable when extracting CSS for selectors
+      --hashed                     Emit selectors backed by loader-bridge hashed modules
+      --resolver <path>            Path or package name exporting a CssResolver
+      --mode <module|declaration>  Emit selector modules (module) or declaration files (declaration)
+      --manifest <path>            Write a sidecar manifest (declaration mode only)
+  -h, --help                       Show this help message
 `);
 }
 function reportCliResult(result) {
@@ -844,6 +1135,9 @@ function reportCliResult(result) {
         console.log(`[knighted-css] Selector modules updated: wrote ${result.selectorModulesWritten}, removed ${result.selectorModulesRemoved}.`);
     }
     console.log(`[knighted-css] Manifest: ${result.manifestPath}`);
+    if (result.sidecarManifestPath) {
+        console.log(`[knighted-css] Sidecar manifest: ${result.sidecarManifestPath}`);
+    }
     for (const warning of result.warnings) {
         console.warn(`[knighted-css] ${warning}`);
     }
@@ -873,23 +1167,31 @@ exports.__generateTypesInternals = {
     setImportMetaUrlProvider,
     isNonRelativeSpecifier,
     isStyleResource,
+    isCssModuleResource,
     resolveProxyInfo,
+    resolveDeclarationProxyInfo,
     resolveWithExtensionFallback,
     resolveIndexFallback,
     createProjectPeerResolver,
     getProjectRequire,
     loadTsconfigResolutionContext,
     resolveWithTsconfigPaths,
+    hasStyleImports,
     loadResolverModule,
     parseCliArgs,
     printHelp,
     reportCliResult,
     buildSelectorModuleManifestKey,
     buildSelectorModulePath,
+    buildDeclarationModuleSpecifier,
     formatSelectorModuleSource,
+    buildDeclarationPath,
+    formatDeclarationSource,
+    ensureDeclarationModule,
     ensureSelectorModule,
     removeStaleSelectorModules,
     readManifest,
     writeManifest,
+    writeSidecarManifest,
 };
 //# sourceMappingURL=generateTypes.cjs.map