@knighted/css 1.0.0-rc.11 → 1.0.0-rc.13

package/dist/cjs/generateTypes.cjs

@@ -16,7 +16,6 @@ const node_module_type_1 = require("node-module-type");
 const get_tsconfig_1 = require("get-tsconfig");
 const tsconfig_paths_1 = require("tsconfig-paths");
 const css_js_1 = require("./css.cjs");
-const loaderInternals_js_1 = require("./loaderInternals.cjs");
 const stableSelectorsLiteral_js_1 = require("./stableSelectorsLiteral.cjs");
 const stableNamespace_js_1 = require("./stableNamespace.cjs");
 let activeCssWithMeta = css_js_1.cssWithMeta;
@@ -65,22 +64,19 @@ function getImportMetaUrl() {
     }
 }
 const PACKAGE_ROOT = resolvePackageRoot();
-const DEFAULT_TYPES_ROOT = node_path_1.default.join(PACKAGE_ROOT, 'types-stub');
-const DEFAULT_OUT_DIR = node_path_1.default.join(PACKAGE_ROOT, 'node_modules', '.knighted-css');
+const SELECTOR_REFERENCE = '.knighted-css';
+const SELECTOR_MODULE_SUFFIX = '.knighted-css.ts';
 async function generateTypes(options = {}) {
     const rootDir = node_path_1.default.resolve(options.rootDir ?? process.cwd());
     const include = normalizeIncludeOptions(options.include, rootDir);
-    const outDir = node_path_1.default.resolve(options.outDir ?? DEFAULT_OUT_DIR);
-    const typesRoot = node_path_1.default.resolve(options.typesRoot ?? DEFAULT_TYPES_ROOT);
+    const cacheDir = node_path_1.default.resolve(options.outDir ?? node_path_1.default.join(rootDir, '.knighted-css'));
     const tsconfig = loadTsconfigResolutionContext(rootDir);
     await es_module_lexer_1.init;
-    await promises_1.default.mkdir(outDir, { recursive: true });
-    await promises_1.default.mkdir(typesRoot, { recursive: true });
+    await promises_1.default.mkdir(cacheDir, { recursive: true });
     const internalOptions = {
         rootDir,
         include,
-        outDir,
-        typesRoot,
+        cacheDir,
         stableNamespace: options.stableNamespace,
         tsconfig,
     };
@@ -89,29 +85,27 @@ async function generateTypes(options = {}) {
 async function generateDeclarations(options) {
     const peerResolver = createProjectPeerResolver(options.rootDir);
     const files = await collectCandidateFiles(options.include);
-    const manifestPath = node_path_1.default.join(options.outDir, 'manifest.json');
-    const previousManifest = await readManifest(manifestPath);
-    const nextManifest = {};
+    const selectorModulesManifestPath = node_path_1.default.join(options.cacheDir, 'selector-modules.json');
+    const previousSelectorManifest = await readManifest(selectorModulesManifestPath);
+    const nextSelectorManifest = {};
     const selectorCache = new Map();
-    const processedSpecifiers = new Set();
-    const declarations = [];
+    const processedSelectors = new Set();
     const warnings = [];
-    let writes = 0;
+    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);
-            if (!inlineFree.includes('?knighted-css'))
-                continue;
-            const { resource, query } = splitResourceAndQuery(inlineFree);
-            if (!query || !(0, loaderInternals_js_1.hasQueryFlag)(query, loaderInternals_js_1.TYPES_QUERY_FLAG)) {
+            const { resource } = splitResourceAndQuery(inlineFree);
+            const selectorSource = extractSelectorSourceSpecifier(resource);
+            if (!selectorSource) {
                 continue;
             }
             const resolvedNamespace = (0, stableNamespace_js_1.resolveStableNamespace)(options.stableNamespace);
-            const resolvedPath = await resolveImportPath(resource, match.importer, options.rootDir, options.tsconfig);
+            const resolvedPath = await resolveImportPath(selectorSource, match.importer, options.rootDir, options.tsconfig);
             if (!resolvedPath) {
-                warnings.push(`Unable to resolve ${resource} referenced by ${relativeToRoot(match.importer, options.rootDir)}.`);
+                warnings.push(`Unable to resolve ${selectorSource} referenced by ${relativeToRoot(match.importer, options.rootDir)}.`);
                 continue;
             }
             const cacheKey = `${resolvedPath}::${resolvedNamespace}`;
@@ -135,42 +129,28 @@ async function generateDeclarations(options) {
                 }
                 selectorCache.set(cacheKey, selectorMap);
             }
-            const canonicalSpecifier = buildDeclarationModuleSpecifier(resolvedPath, options.outDir, query);
-            if (processedSpecifiers.has(canonicalSpecifier)) {
+            if (!isWithinRoot(resolvedPath, options.rootDir)) {
+                warnings.push(`Skipping selector module for ${relativeToRoot(resolvedPath, options.rootDir)} because it is outside the project root.`);
                 continue;
             }
-            const variant = (0, loaderInternals_js_1.determineSelectorVariant)(query);
-            const declaration = formatModuleDeclaration(canonicalSpecifier, variant, selectorMap);
-            const declarationHash = hashContent(declaration);
-            const fileName = buildDeclarationFileName(canonicalSpecifier);
-            const targetPath = node_path_1.default.join(options.outDir, fileName);
-            const previousEntry = previousManifest[canonicalSpecifier];
-            const needsWrite = previousEntry?.hash !== declarationHash || !(await fileExists(targetPath));
-            if (needsWrite) {
-                await promises_1.default.writeFile(targetPath, declaration, 'utf8');
-                writes += 1;
+            const manifestKey = buildSelectorModuleManifestKey(resolvedPath);
+            if (processedSelectors.has(manifestKey)) {
+                continue;
             }
-            nextManifest[canonicalSpecifier] = { file: fileName, hash: declarationHash };
-            if (needsWrite) {
-                declarations.push({ specifier: canonicalSpecifier, filePath: targetPath });
+            const moduleWrite = await ensureSelectorModule(resolvedPath, selectorMap, previousSelectorManifest, nextSelectorManifest);
+            if (moduleWrite) {
+                selectorModuleWrites += 1;
             }
-            processedSpecifiers.add(canonicalSpecifier);
+            processedSelectors.add(manifestKey);
         }
     }
-    const removed = await removeStaleDeclarations(previousManifest, nextManifest, options.outDir);
-    await writeManifest(manifestPath, nextManifest);
-    const typesIndexPath = node_path_1.default.join(options.typesRoot, 'index.d.ts');
-    await writeTypesIndex(typesIndexPath, nextManifest, options.outDir);
-    if (Object.keys(nextManifest).length === 0) {
-        declarations.length = 0;
-    }
+    const selectorModulesRemoved = await removeStaleSelectorModules(previousSelectorManifest, nextSelectorManifest);
+    await writeManifest(selectorModulesManifestPath, nextSelectorManifest);
     return {
-        written: writes,
-        removed,
-        declarations,
+        selectorModulesWritten: selectorModuleWrites,
+        selectorModulesRemoved,
         warnings,
-        outDir: options.outDir,
-        typesIndexPath,
+        manifestPath: selectorModulesManifestPath,
     };
 }
 function normalizeIncludeOptions(include, rootDir) {
@@ -228,18 +208,18 @@ async function findSpecifierImports(filePath) {
     catch {
         return [];
     }
-    if (!source.includes('?knighted-css')) {
+    if (!source.includes(SELECTOR_REFERENCE)) {
         return [];
     }
     const matches = [];
     const [imports] = (0, es_module_lexer_1.parse)(source, filePath);
     for (const record of imports) {
         const specifier = record.n ?? source.slice(record.s, record.e);
-        if (specifier && specifier.includes('?knighted-css')) {
+        if (specifier && specifier.includes(SELECTOR_REFERENCE)) {
             matches.push({ specifier, importer: filePath });
         }
     }
-    const requireRegex = /require\((['"])([^'"`]+?\?knighted-css[^'"`]*)\1\)/g;
+    const requireRegex = /require\((['"])([^'"`]+?\.knighted-css[^'"`]*)\1\)/g;
     let reqMatch;
     while ((reqMatch = requireRegex.exec(source)) !== null) {
         const spec = reqMatch[2];
@@ -262,6 +242,21 @@ function splitResourceAndQuery(specifier) {
     }
     return { resource: trimmed.slice(0, queryIndex), query: trimmed.slice(queryIndex) };
 }
+function extractSelectorSourceSpecifier(specifier) {
+    const markerIndex = specifier.indexOf(SELECTOR_REFERENCE);
+    if (markerIndex < 0) {
+        return undefined;
+    }
+    const suffix = specifier.slice(markerIndex + SELECTOR_REFERENCE.length);
+    if (suffix.length > 0 && !/\.(?:[cm]?[tj]s|[tj]sx)$/.test(suffix)) {
+        return undefined;
+    }
+    const base = specifier.slice(0, markerIndex);
+    if (!base) {
+        return undefined;
+    }
+    return base;
+}
 const projectRequireCache = new Map();
 async function resolveImportPath(resourceSpecifier, importerPath, rootDir, tsconfig) {
     if (!resourceSpecifier)
@@ -284,91 +279,29 @@ async function resolveImportPath(resourceSpecifier, importerPath, rootDir, tscon
         return undefined;
     }
 }
-function buildDeclarationFileName(specifier) {
-    const digest = node_crypto_1.default.createHash('sha1').update(specifier).digest('hex').slice(0, 12);
-    return `knt-${digest}.d.ts`;
-}
-function formatModuleDeclaration(specifier, variant, selectors) {
-    const literalSpecifier = JSON.stringify(specifier);
-    const selectorType = formatSelectorType(selectors);
-    const header = `declare module ${literalSpecifier} {`;
-    const footer = '}';
-    if (variant === 'types') {
-        return `${header}
-  export const knightedCss: string
-  export const stableSelectors: ${selectorType}
-${footer}
-`;
-    }
-    const stableLine = `  export const stableSelectors: ${selectorType}`;
-    const shared = `  const combined: KnightedCssCombinedModule<Record<string, unknown>>
-  export const knightedCss: string
-${stableLine}`;
-    if (variant === 'combined') {
-        return `${header}
-${shared}
-  export default combined
-${footer}
-`;
-    }
-    return `${header}
-${shared}
-${footer}
-`;
+function buildSelectorModuleManifestKey(resolvedPath) {
+    return resolvedPath.split(node_path_1.default.sep).join('/');
 }
-function formatSelectorType(selectors) {
-    if (selectors.size === 0) {
-        return 'Readonly<Record<string, string>>';
-    }
+function buildSelectorModulePath(resolvedPath) {
+    return `${resolvedPath}${SELECTOR_MODULE_SUFFIX}`;
+}
+function formatSelectorModuleSource(selectors) {
+    const header = '// Generated by @knighted/css/generate-types\n// Do not edit.\n';
     const entries = Array.from(selectors.entries()).sort(([a], [b]) => a.localeCompare(b));
-    const lines = entries.map(([token, selector]) => `    readonly ${JSON.stringify(token)}: ${JSON.stringify(selector)}`);
-    return `Readonly<{
+    const lines = entries.map(([token, selector]) => `  ${JSON.stringify(token)}: ${JSON.stringify(selector)},`);
+    const literal = lines.length > 0
+        ? `{
 ${lines.join('\n')}
-  }>`;
-}
-function buildDeclarationModuleSpecifier(resolvedPath, declarationDir, query) {
-    const relativePath = node_path_1.default.relative(declarationDir, resolvedPath);
-    const normalizedPath = normalizeRelativePath(relativePath);
-    const canonicalQuery = buildCanonicalQuery(query);
-    return `${normalizedPath}${canonicalQuery}`;
-}
-function normalizeRelativePath(relativePath) {
-    let normalized = relativePath.split(node_path_1.default.sep).join('/');
-    if (!normalized || normalized === '') {
-        normalized = '.';
-    }
-    if (normalized === '.') {
-        return './';
-    }
-    if (normalized.startsWith('./') || normalized.startsWith('../')) {
-        return normalized;
-    }
-    if (normalized.startsWith('.')) {
-        return normalized;
-    }
-    return `./${normalized}`;
-}
-function buildCanonicalQuery(query) {
-    if (!query) {
-        return '';
-    }
-    const sanitized = (0, loaderInternals_js_1.buildSanitizedQuery)(query);
-    const extraParts = sanitized ? sanitized.slice(1).split('&').filter(Boolean) : [];
-    const parts = [];
-    parts.push('knighted-css');
-    if ((0, loaderInternals_js_1.hasQueryFlag)(query, loaderInternals_js_1.COMBINED_QUERY_FLAG)) {
-        parts.push(loaderInternals_js_1.COMBINED_QUERY_FLAG);
-    }
-    for (const flag of loaderInternals_js_1.NAMED_ONLY_QUERY_FLAGS) {
-        if ((0, loaderInternals_js_1.hasQueryFlag)(query, flag)) {
-            parts.push(flag);
-        }
-    }
-    if ((0, loaderInternals_js_1.hasQueryFlag)(query, loaderInternals_js_1.TYPES_QUERY_FLAG)) {
-        parts.push(loaderInternals_js_1.TYPES_QUERY_FLAG);
-    }
-    const merged = [...parts, ...extraParts];
-    return merged.length > 0 ? `?${merged.join('&')}` : '';
+} as const`
+        : '{} as const';
+    return `${header}
+export const stableSelectors = ${literal}
+
+export type KnightedCssStableSelectors = typeof stableSelectors
+export type KnightedCssStableSelectorToken = keyof typeof stableSelectors
+
+export default stableSelectors
+`;
 }
 function hashContent(content) {
     return node_crypto_1.default.createHash('sha1').update(content).digest('hex');
@@ -385,13 +318,12 @@ async function readManifest(manifestPath) {
 async function writeManifest(manifestPath, manifest) {
     await promises_1.default.writeFile(manifestPath, JSON.stringify(manifest, null, 2), 'utf8');
 }
-async function removeStaleDeclarations(previous, next, outDir) {
-    const stale = Object.entries(previous).filter(([specifier]) => !next[specifier]);
+async function removeStaleSelectorModules(previous, next) {
+    const stale = Object.entries(previous).filter(([key]) => !next[key]);
     let removed = 0;
     for (const [, entry] of stale) {
-        const targetPath = node_path_1.default.join(outDir, entry.file);
         try {
-            await promises_1.default.unlink(targetPath);
+            await promises_1.default.unlink(entry.file);
             removed += 1;
         }
         catch {
@@ -400,25 +332,6 @@ async function removeStaleDeclarations(previous, next, outDir) {
     }
     return removed;
 }
-async function writeTypesIndex(indexPath, manifest, outDir) {
-    const header = '// Generated by @knighted/css/generate-types\n// Do not edit.\n';
-    const references = Object.values(manifest)
-        .sort((a, b) => a.file.localeCompare(b.file))
-        .map(entry => {
-        const rel = node_path_1.default
-            .relative(node_path_1.default.dirname(indexPath), node_path_1.default.join(outDir, entry.file))
-            .split(node_path_1.default.sep)
-            .join('/');
-        return `/// <reference path="${rel}" />`;
-    });
-    const content = references.length > 0
-        ? `${header}
-${references.join('\n')}
-`
-        : `${header}
-`;
-    await promises_1.default.writeFile(indexPath, content, 'utf8');
-}
 function formatErrorMessage(error) {
     if (error instanceof Error && typeof error.message === 'string') {
         return error.message;
@@ -428,6 +341,23 @@ function formatErrorMessage(error) {
 function relativeToRoot(filePath, rootDir) {
     return node_path_1.default.relative(rootDir, filePath) || filePath;
 }
+function isWithinRoot(filePath, rootDir) {
+    const relative = node_path_1.default.relative(rootDir, filePath);
+    return relative === '' || (!relative.startsWith('..') && !node_path_1.default.isAbsolute(relative));
+}
+async function ensureSelectorModule(resolvedPath, selectors, previousManifest, nextManifest) {
+    const manifestKey = buildSelectorModuleManifestKey(resolvedPath);
+    const targetPath = buildSelectorModulePath(resolvedPath);
+    const source = formatSelectorModuleSource(selectors);
+    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);
@@ -551,7 +481,6 @@ async function runGenerateTypesCli(argv = process.argv.slice(2)) {
             rootDir: parsed.rootDir,
             include: parsed.include,
             outDir: parsed.outDir,
-            typesRoot: parsed.typesRoot,
             stableNamespace: parsed.stableNamespace,
         });
         reportCliResult(result);
@@ -566,12 +495,11 @@ function parseCliArgs(argv) {
     let rootDir = process.cwd();
     const include = [];
     let outDir;
-    let typesRoot;
     let stableNamespace;
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
         if (arg === '--help' || arg === '-h') {
-            return { rootDir, include, outDir, typesRoot, stableNamespace, help: true };
+            return { rootDir, include, outDir, stableNamespace, help: true };
         }
         if (arg === '--root' || arg === '-r') {
             const value = argv[++i];
@@ -597,14 +525,6 @@ function parseCliArgs(argv) {
             outDir = value;
             continue;
         }
-        if (arg === '--types-root') {
-            const value = argv[++i];
-            if (!value) {
-                throw new Error('Missing value for --types-root');
-            }
-            typesRoot = value;
-            continue;
-        }
         if (arg === '--stable-namespace') {
             const value = argv[++i];
             if (!value) {
@@ -618,7 +538,7 @@ function parseCliArgs(argv) {
         }
         include.push(arg);
     }
-    return { rootDir, include, outDir, typesRoot, stableNamespace };
+    return { rootDir, include, outDir, stableNamespace };
 }
 function printHelp() {
     console.log(`Usage: knighted-css-generate-types [options]
@@ -626,20 +546,19 @@ function printHelp() {
 Options:
   -r, --root <path>              Project root directory (default: cwd)
   -i, --include <path>           Additional directories/files to scan (repeatable)
-      --out-dir <path>           Output directory for generated declarations
-      --types-root <path>        Directory for generated @types entrypoint
+      --out-dir <path>           Directory to store selector module manifest cache
       --stable-namespace <name>  Stable namespace prefix for generated selector maps
   -h, --help                     Show this help message
 `);
 }
 function reportCliResult(result) {
-    if (result.written === 0 && result.removed === 0) {
-        console.log('[knighted-css] No changes to ?knighted-css&types declarations (cache is up to date).');
+    if (result.selectorModulesWritten === 0 && result.selectorModulesRemoved === 0) {
+        console.log('[knighted-css] Selector modules are up to date.');
     }
     else {
-        console.log(`[knighted-css] Updated ${result.written} declaration(s), removed ${result.removed}, output in ${result.outDir}.`);
+        console.log(`[knighted-css] Selector modules updated: wrote ${result.selectorModulesWritten}, removed ${result.selectorModulesRemoved}.`);
     }
-    console.log(`[knighted-css] Type references: ${result.typesIndexPath}`);
+    console.log(`[knighted-css] Manifest: ${result.manifestPath}`);
     for (const warning of result.warnings) {
         console.warn(`[knighted-css] ${warning}`);
     }
@@ -654,17 +573,12 @@ function setImportMetaUrlProvider(provider) {
     importMetaUrlProvider = provider ?? getImportMetaUrl;
 }
 exports.__generateTypesInternals = {
-    writeTypesIndex,
     stripInlineLoader,
     splitResourceAndQuery,
+    extractSelectorSourceSpecifier,
     findSpecifierImports,
     resolveImportPath,
     resolvePackageRoot,
-    buildDeclarationFileName,
-    formatModuleDeclaration,
-    formatSelectorType,
-    buildDeclarationModuleSpecifier,
-    buildCanonicalQuery,
     relativeToRoot,
     collectCandidateFiles,
     normalizeIncludeOptions,
@@ -680,4 +594,11 @@ exports.__generateTypesInternals = {
     parseCliArgs,
     printHelp,
     reportCliResult,
+    buildSelectorModuleManifestKey,
+    buildSelectorModulePath,
+    formatSelectorModuleSource,
+    ensureSelectorModule,
+    removeStaleSelectorModules,
+    readManifest,
+    writeManifest,
 };

package/dist/cjs/generateTypes.d.cts

@@ -3,38 +3,30 @@ import { moduleType } from 'node-module-type';
 import { getTsconfig } from 'get-tsconfig';
 import { type MatchPath } from 'tsconfig-paths';
 import { cssWithMeta } from './css.cjs';
-import { type SelectorTypeVariant } from './loaderInternals.cjs';
-interface ManifestEntry {
-    file: string;
-    hash: string;
-}
-type Manifest = Record<string, ManifestEntry>;
 interface ImportMatch {
     specifier: string;
     importer: string;
 }
-interface DeclarationRecord {
-    specifier: string;
-    filePath: string;
+interface ManifestEntry {
+    file: string;
+    hash: string;
 }
+type SelectorModuleManifest = Record<string, ManifestEntry>;
 interface TsconfigResolutionContext {
     absoluteBaseUrl?: string;
     matchPath?: MatchPath;
 }
 type CssWithMetaFn = typeof cssWithMeta;
 export interface GenerateTypesResult {
-    written: number;
-    removed: number;
-    declarations: DeclarationRecord[];
+    selectorModulesWritten: number;
+    selectorModulesRemoved: number;
     warnings: string[];
-    outDir: string;
-    typesIndexPath: string;
+    manifestPath: string;
 }
 export interface GenerateTypesOptions {
     rootDir?: string;
     include?: string[];
     outDir?: string;
-    typesRoot?: string;
     stableNamespace?: string;
 }
 type ModuleTypeDetector = () => ReturnType<typeof moduleType>;
@@ -48,14 +40,16 @@ declare function splitResourceAndQuery(specifier: string): {
     resource: string;
     query: string;
 };
+declare function extractSelectorSourceSpecifier(specifier: string): string | undefined;
 declare function resolveImportPath(resourceSpecifier: string, importerPath: string, rootDir: string, tsconfig?: TsconfigResolutionContext): Promise<string | undefined>;
-declare function buildDeclarationFileName(specifier: string): string;
-declare function formatModuleDeclaration(specifier: string, variant: SelectorTypeVariant, selectors: Map<string, string>): string;
-declare function formatSelectorType(selectors: Map<string, string>): string;
-declare function buildDeclarationModuleSpecifier(resolvedPath: string, declarationDir: string, query: string): string;
-declare function buildCanonicalQuery(query: string): string;
-declare function writeTypesIndex(indexPath: string, manifest: Manifest, outDir: string): Promise<void>;
+declare function buildSelectorModuleManifestKey(resolvedPath: string): string;
+declare function buildSelectorModulePath(resolvedPath: string): string;
+declare function formatSelectorModuleSource(selectors: Map<string, string>): string;
+declare function readManifest(manifestPath: string): Promise<SelectorModuleManifest>;
+declare function writeManifest(manifestPath: string, manifest: SelectorModuleManifest): Promise<void>;
+declare function removeStaleSelectorModules(previous: SelectorModuleManifest, next: SelectorModuleManifest): Promise<number>;
 declare function relativeToRoot(filePath: string, rootDir: string): string;
+declare function ensureSelectorModule(resolvedPath: string, selectors: Map<string, string>, previousManifest: SelectorModuleManifest, nextManifest: SelectorModuleManifest): Promise<boolean>;
 declare function resolveWithTsconfigPaths(specifier: string, tsconfig?: TsconfigResolutionContext): Promise<string | undefined>;
 declare function loadTsconfigResolutionContext(rootDir: string, loader?: typeof getTsconfig): TsconfigResolutionContext | undefined;
 declare function normalizeTsconfigPaths(paths: Record<string, string[] | string> | undefined): Record<string, string[]> | undefined;
@@ -67,7 +61,6 @@ export interface ParsedCliArgs {
     rootDir: string;
     include?: string[];
     outDir?: string;
-    typesRoot?: string;
     stableNamespace?: string;
     help?: boolean;
 }
@@ -78,17 +71,12 @@ declare function setCssWithMetaImplementation(impl?: CssWithMetaFn): void;
 declare function setModuleTypeDetector(detector?: ModuleTypeDetector): void;
 declare function setImportMetaUrlProvider(provider?: () => string | undefined): void;
 export declare const __generateTypesInternals: {
-    writeTypesIndex: typeof writeTypesIndex;
     stripInlineLoader: typeof stripInlineLoader;
     splitResourceAndQuery: typeof splitResourceAndQuery;
+    extractSelectorSourceSpecifier: typeof extractSelectorSourceSpecifier;
     findSpecifierImports: typeof findSpecifierImports;
     resolveImportPath: typeof resolveImportPath;
     resolvePackageRoot: typeof resolvePackageRoot;
-    buildDeclarationFileName: typeof buildDeclarationFileName;
-    formatModuleDeclaration: typeof formatModuleDeclaration;
-    formatSelectorType: typeof formatSelectorType;
-    buildDeclarationModuleSpecifier: typeof buildDeclarationModuleSpecifier;
-    buildCanonicalQuery: typeof buildCanonicalQuery;
     relativeToRoot: typeof relativeToRoot;
     collectCandidateFiles: typeof collectCandidateFiles;
     normalizeIncludeOptions: typeof normalizeIncludeOptions;
@@ -104,5 +92,12 @@ export declare const __generateTypesInternals: {
     parseCliArgs: typeof parseCliArgs;
     printHelp: typeof printHelp;
     reportCliResult: typeof reportCliResult;
+    buildSelectorModuleManifestKey: typeof buildSelectorModuleManifestKey;
+    buildSelectorModulePath: typeof buildSelectorModulePath;
+    formatSelectorModuleSource: typeof formatSelectorModuleSource;
+    ensureSelectorModule: typeof ensureSelectorModule;
+    removeStaleSelectorModules: typeof removeStaleSelectorModules;
+    readManifest: typeof readManifest;
+    writeManifest: typeof writeManifest;
 };
 export {};

package/dist/cjs/stableSelectors.cjs

@@ -6,8 +6,10 @@ exports.stableClass = stableClass;
 exports.stableSelector = stableSelector;
 exports.createStableClassFactory = createStableClassFactory;
 exports.stableClassName = stableClassName;
+exports.mergeStableClass = mergeStableClass;
 const DEFAULT_NAMESPACE = 'knighted';
 const defaultJoin = (values) => values.filter(Boolean).join(' ');
+const toArray = (value) => Array.isArray(value) ? value : [value];
 const normalizeToken = (token) => {
     const sanitized = token
         .trim()
@@ -42,3 +44,30 @@ function stableClassName(styles, key, options) {
     return join([hashed, stable]);
 }
 exports.stableClassFromModule = stableClassName;
+function mergeStableClass(input) {
+    if ('token' in input) {
+        return mergeSingle(input);
+    }
+    return mergeBatch(input);
+}
+function mergeSingle(input) {
+    const join = input.join ?? defaultJoin;
+    const hashed = toArray(input.hashed);
+    const stable = input.selector?.trim().length
+        ? input.selector
+        : stableClass(input.token, { namespace: input.namespace });
+    return join([...hashed, stable]);
+}
+function mergeBatch(input) {
+    const join = input.join ?? defaultJoin;
+    const output = {};
+    for (const key of Object.keys(input.hashed)) {
+        const hashedValue = input.hashed[key];
+        const selector = input.selectors?.[String(key)];
+        const stable = selector?.trim().length
+            ? selector
+            : stableClass(String(key), { namespace: input.namespace });
+        output[key] = join([...toArray(hashedValue), stable]);
+    }
+    return output;
+}

package/dist/cjs/stableSelectors.d.cts

@@ -5,9 +5,24 @@ export interface StableClassNameOptions extends StableSelectorOptions {
     token?: string;
     join?: (values: string[]) => string;
 }
+export interface MergeStableClassSingleInput extends StableSelectorOptions {
+    hashed: string | string[];
+    selector?: string;
+    token: string;
+    join?: (values: string[]) => string;
+}
+export interface MergeStableClassBatchInput<Hashed extends Record<string, string | string[]>, Selectors extends Record<string, string> | undefined = Record<string, string>> extends StableSelectorOptions {
+    hashed: Hashed;
+    selectors?: Selectors;
+    join?: (values: string[]) => string;
+}
 export declare function stableToken(token: string, options?: StableSelectorOptions): string;
 export declare function stableClass(token: string, options?: StableSelectorOptions): string;
 export declare function stableSelector(token: string, options?: StableSelectorOptions): string;
 export declare function createStableClassFactory(options?: StableSelectorOptions): (token: string) => string;
 export declare function stableClassName<T extends Record<string, string>>(styles: T, key: keyof T | string, options?: StableClassNameOptions): string;
 export declare const stableClassFromModule: typeof stableClassName;
+export declare function mergeStableClass(input: MergeStableClassSingleInput): string;
+export declare function mergeStableClass<Hashed extends Record<string, string | string[]>>(input: MergeStableClassBatchInput<Hashed>): {
+    [Key in keyof Hashed]: string;
+};

package/dist/generateTypes.d.ts

@@ -3,38 +3,30 @@ import { moduleType } from 'node-module-type';
 import { getTsconfig } from 'get-tsconfig';
 import { type MatchPath } from 'tsconfig-paths';
 import { cssWithMeta } from './css.js';
-import { type SelectorTypeVariant } from './loaderInternals.js';
-interface ManifestEntry {
-    file: string;
-    hash: string;
-}
-type Manifest = Record<string, ManifestEntry>;
 interface ImportMatch {
     specifier: string;
     importer: string;
 }
-interface DeclarationRecord {
-    specifier: string;
-    filePath: string;
+interface ManifestEntry {
+    file: string;
+    hash: string;
 }
+type SelectorModuleManifest = Record<string, ManifestEntry>;
 interface TsconfigResolutionContext {
     absoluteBaseUrl?: string;
     matchPath?: MatchPath;
 }
 type CssWithMetaFn = typeof cssWithMeta;
 export interface GenerateTypesResult {
-    written: number;
-    removed: number;
-    declarations: DeclarationRecord[];
+    selectorModulesWritten: number;
+    selectorModulesRemoved: number;
     warnings: string[];
-    outDir: string;
-    typesIndexPath: string;
+    manifestPath: string;
 }
 export interface GenerateTypesOptions {
     rootDir?: string;
     include?: string[];
     outDir?: string;
-    typesRoot?: string;
     stableNamespace?: string;
 }
 type ModuleTypeDetector = () => ReturnType<typeof moduleType>;
@@ -48,14 +40,16 @@ declare function splitResourceAndQuery(specifier: string): {
     resource: string;
     query: string;
 };
+declare function extractSelectorSourceSpecifier(specifier: string): string | undefined;
 declare function resolveImportPath(resourceSpecifier: string, importerPath: string, rootDir: string, tsconfig?: TsconfigResolutionContext): Promise<string | undefined>;
-declare function buildDeclarationFileName(specifier: string): string;
-declare function formatModuleDeclaration(specifier: string, variant: SelectorTypeVariant, selectors: Map<string, string>): string;
-declare function formatSelectorType(selectors: Map<string, string>): string;
-declare function buildDeclarationModuleSpecifier(resolvedPath: string, declarationDir: string, query: string): string;
-declare function buildCanonicalQuery(query: string): string;
-declare function writeTypesIndex(indexPath: string, manifest: Manifest, outDir: string): Promise<void>;
+declare function buildSelectorModuleManifestKey(resolvedPath: string): string;
+declare function buildSelectorModulePath(resolvedPath: string): string;
+declare function formatSelectorModuleSource(selectors: Map<string, string>): string;
+declare function readManifest(manifestPath: string): Promise<SelectorModuleManifest>;
+declare function writeManifest(manifestPath: string, manifest: SelectorModuleManifest): Promise<void>;
+declare function removeStaleSelectorModules(previous: SelectorModuleManifest, next: SelectorModuleManifest): Promise<number>;
 declare function relativeToRoot(filePath: string, rootDir: string): string;
+declare function ensureSelectorModule(resolvedPath: string, selectors: Map<string, string>, previousManifest: SelectorModuleManifest, nextManifest: SelectorModuleManifest): Promise<boolean>;
 declare function resolveWithTsconfigPaths(specifier: string, tsconfig?: TsconfigResolutionContext): Promise<string | undefined>;
 declare function loadTsconfigResolutionContext(rootDir: string, loader?: typeof getTsconfig): TsconfigResolutionContext | undefined;
 declare function normalizeTsconfigPaths(paths: Record<string, string[] | string> | undefined): Record<string, string[]> | undefined;
@@ -67,7 +61,6 @@ export interface ParsedCliArgs {
     rootDir: string;
     include?: string[];
     outDir?: string;
-    typesRoot?: string;
     stableNamespace?: string;
     help?: boolean;
 }
@@ -78,17 +71,12 @@ declare function setCssWithMetaImplementation(impl?: CssWithMetaFn): void;
 declare function setModuleTypeDetector(detector?: ModuleTypeDetector): void;
 declare function setImportMetaUrlProvider(provider?: () => string | undefined): void;
 export declare const __generateTypesInternals: {
-    writeTypesIndex: typeof writeTypesIndex;
     stripInlineLoader: typeof stripInlineLoader;
     splitResourceAndQuery: typeof splitResourceAndQuery;
+    extractSelectorSourceSpecifier: typeof extractSelectorSourceSpecifier;
     findSpecifierImports: typeof findSpecifierImports;
     resolveImportPath: typeof resolveImportPath;
     resolvePackageRoot: typeof resolvePackageRoot;
-    buildDeclarationFileName: typeof buildDeclarationFileName;
-    formatModuleDeclaration: typeof formatModuleDeclaration;
-    formatSelectorType: typeof formatSelectorType;
-    buildDeclarationModuleSpecifier: typeof buildDeclarationModuleSpecifier;
-    buildCanonicalQuery: typeof buildCanonicalQuery;
     relativeToRoot: typeof relativeToRoot;
     collectCandidateFiles: typeof collectCandidateFiles;
     normalizeIncludeOptions: typeof normalizeIncludeOptions;
@@ -104,5 +92,12 @@ export declare const __generateTypesInternals: {
     parseCliArgs: typeof parseCliArgs;
     printHelp: typeof printHelp;
     reportCliResult: typeof reportCliResult;
+    buildSelectorModuleManifestKey: typeof buildSelectorModuleManifestKey;
+    buildSelectorModulePath: typeof buildSelectorModulePath;
+    formatSelectorModuleSource: typeof formatSelectorModuleSource;
+    ensureSelectorModule: typeof ensureSelectorModule;
+    removeStaleSelectorModules: typeof removeStaleSelectorModules;
+    readManifest: typeof readManifest;
+    writeManifest: typeof writeManifest;
 };
 export {};

package/dist/generateTypes.js

@@ -8,7 +8,6 @@ import { moduleType } from 'node-module-type';
 import { getTsconfig } from 'get-tsconfig';
 import { createMatchPath } from 'tsconfig-paths';
 import { cssWithMeta } from './css.js';
-import { determineSelectorVariant, hasQueryFlag, TYPES_QUERY_FLAG, buildSanitizedQuery, COMBINED_QUERY_FLAG, NAMED_ONLY_QUERY_FLAGS, } from './loaderInternals.js';
 import { buildStableSelectorsLiteral } from './stableSelectorsLiteral.js';
 import { resolveStableNamespace } from './stableNamespace.js';
 let activeCssWithMeta = cssWithMeta;
@@ -57,22 +56,19 @@ function getImportMetaUrl() {
     }
 }
 const PACKAGE_ROOT = resolvePackageRoot();
-const DEFAULT_TYPES_ROOT = path.join(PACKAGE_ROOT, 'types-stub');
-const DEFAULT_OUT_DIR = path.join(PACKAGE_ROOT, 'node_modules', '.knighted-css');
+const SELECTOR_REFERENCE = '.knighted-css';
+const SELECTOR_MODULE_SUFFIX = '.knighted-css.ts';
 export async function generateTypes(options = {}) {
     const rootDir = path.resolve(options.rootDir ?? process.cwd());
     const include = normalizeIncludeOptions(options.include, rootDir);
-    const outDir = path.resolve(options.outDir ?? DEFAULT_OUT_DIR);
-    const typesRoot = path.resolve(options.typesRoot ?? DEFAULT_TYPES_ROOT);
+    const cacheDir = path.resolve(options.outDir ?? path.join(rootDir, '.knighted-css'));
     const tsconfig = loadTsconfigResolutionContext(rootDir);
     await init;
-    await fs.mkdir(outDir, { recursive: true });
-    await fs.mkdir(typesRoot, { recursive: true });
+    await fs.mkdir(cacheDir, { recursive: true });
     const internalOptions = {
         rootDir,
         include,
-        outDir,
-        typesRoot,
+        cacheDir,
         stableNamespace: options.stableNamespace,
         tsconfig,
     };
@@ -81,29 +77,27 @@ export async function generateTypes(options = {}) {
 async function generateDeclarations(options) {
     const peerResolver = createProjectPeerResolver(options.rootDir);
     const files = await collectCandidateFiles(options.include);
-    const manifestPath = path.join(options.outDir, 'manifest.json');
-    const previousManifest = await readManifest(manifestPath);
-    const nextManifest = {};
+    const selectorModulesManifestPath = path.join(options.cacheDir, 'selector-modules.json');
+    const previousSelectorManifest = await readManifest(selectorModulesManifestPath);
+    const nextSelectorManifest = {};
     const selectorCache = new Map();
-    const processedSpecifiers = new Set();
-    const declarations = [];
+    const processedSelectors = new Set();
     const warnings = [];
-    let writes = 0;
+    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);
-            if (!inlineFree.includes('?knighted-css'))
-                continue;
-            const { resource, query } = splitResourceAndQuery(inlineFree);
-            if (!query || !hasQueryFlag(query, TYPES_QUERY_FLAG)) {
+            const { resource } = splitResourceAndQuery(inlineFree);
+            const selectorSource = extractSelectorSourceSpecifier(resource);
+            if (!selectorSource) {
                 continue;
             }
             const resolvedNamespace = resolveStableNamespace(options.stableNamespace);
-            const resolvedPath = await resolveImportPath(resource, match.importer, options.rootDir, options.tsconfig);
+            const resolvedPath = await resolveImportPath(selectorSource, match.importer, options.rootDir, options.tsconfig);
             if (!resolvedPath) {
-                warnings.push(`Unable to resolve ${resource} referenced by ${relativeToRoot(match.importer, options.rootDir)}.`);
+                warnings.push(`Unable to resolve ${selectorSource} referenced by ${relativeToRoot(match.importer, options.rootDir)}.`);
                 continue;
             }
             const cacheKey = `${resolvedPath}::${resolvedNamespace}`;
@@ -127,42 +121,28 @@ async function generateDeclarations(options) {
                 }
                 selectorCache.set(cacheKey, selectorMap);
             }
-            const canonicalSpecifier = buildDeclarationModuleSpecifier(resolvedPath, options.outDir, query);
-            if (processedSpecifiers.has(canonicalSpecifier)) {
+            if (!isWithinRoot(resolvedPath, options.rootDir)) {
+                warnings.push(`Skipping selector module for ${relativeToRoot(resolvedPath, options.rootDir)} because it is outside the project root.`);
                 continue;
             }
-            const variant = determineSelectorVariant(query);
-            const declaration = formatModuleDeclaration(canonicalSpecifier, variant, selectorMap);
-            const declarationHash = hashContent(declaration);
-            const fileName = buildDeclarationFileName(canonicalSpecifier);
-            const targetPath = path.join(options.outDir, fileName);
-            const previousEntry = previousManifest[canonicalSpecifier];
-            const needsWrite = previousEntry?.hash !== declarationHash || !(await fileExists(targetPath));
-            if (needsWrite) {
-                await fs.writeFile(targetPath, declaration, 'utf8');
-                writes += 1;
+            const manifestKey = buildSelectorModuleManifestKey(resolvedPath);
+            if (processedSelectors.has(manifestKey)) {
+                continue;
             }
-            nextManifest[canonicalSpecifier] = { file: fileName, hash: declarationHash };
-            if (needsWrite) {
-                declarations.push({ specifier: canonicalSpecifier, filePath: targetPath });
+            const moduleWrite = await ensureSelectorModule(resolvedPath, selectorMap, previousSelectorManifest, nextSelectorManifest);
+            if (moduleWrite) {
+                selectorModuleWrites += 1;
             }
-            processedSpecifiers.add(canonicalSpecifier);
+            processedSelectors.add(manifestKey);
         }
     }
-    const removed = await removeStaleDeclarations(previousManifest, nextManifest, options.outDir);
-    await writeManifest(manifestPath, nextManifest);
-    const typesIndexPath = path.join(options.typesRoot, 'index.d.ts');
-    await writeTypesIndex(typesIndexPath, nextManifest, options.outDir);
-    if (Object.keys(nextManifest).length === 0) {
-        declarations.length = 0;
-    }
+    const selectorModulesRemoved = await removeStaleSelectorModules(previousSelectorManifest, nextSelectorManifest);
+    await writeManifest(selectorModulesManifestPath, nextSelectorManifest);
     return {
-        written: writes,
-        removed,
-        declarations,
+        selectorModulesWritten: selectorModuleWrites,
+        selectorModulesRemoved,
         warnings,
-        outDir: options.outDir,
-        typesIndexPath,
+        manifestPath: selectorModulesManifestPath,
     };
 }
 function normalizeIncludeOptions(include, rootDir) {
@@ -220,18 +200,18 @@ async function findSpecifierImports(filePath) {
     catch {
         return [];
     }
-    if (!source.includes('?knighted-css')) {
+    if (!source.includes(SELECTOR_REFERENCE)) {
         return [];
     }
     const matches = [];
     const [imports] = parse(source, filePath);
     for (const record of imports) {
         const specifier = record.n ?? source.slice(record.s, record.e);
-        if (specifier && specifier.includes('?knighted-css')) {
+        if (specifier && specifier.includes(SELECTOR_REFERENCE)) {
             matches.push({ specifier, importer: filePath });
         }
     }
-    const requireRegex = /require\((['"])([^'"`]+?\?knighted-css[^'"`]*)\1\)/g;
+    const requireRegex = /require\((['"])([^'"`]+?\.knighted-css[^'"`]*)\1\)/g;
     let reqMatch;
     while ((reqMatch = requireRegex.exec(source)) !== null) {
         const spec = reqMatch[2];
@@ -254,6 +234,21 @@ function splitResourceAndQuery(specifier) {
     }
     return { resource: trimmed.slice(0, queryIndex), query: trimmed.slice(queryIndex) };
 }
+function extractSelectorSourceSpecifier(specifier) {
+    const markerIndex = specifier.indexOf(SELECTOR_REFERENCE);
+    if (markerIndex < 0) {
+        return undefined;
+    }
+    const suffix = specifier.slice(markerIndex + SELECTOR_REFERENCE.length);
+    if (suffix.length > 0 && !/\.(?:[cm]?[tj]s|[tj]sx)$/.test(suffix)) {
+        return undefined;
+    }
+    const base = specifier.slice(0, markerIndex);
+    if (!base) {
+        return undefined;
+    }
+    return base;
+}
 const projectRequireCache = new Map();
 async function resolveImportPath(resourceSpecifier, importerPath, rootDir, tsconfig) {
     if (!resourceSpecifier)
@@ -276,91 +271,29 @@ async function resolveImportPath(resourceSpecifier, importerPath, rootDir, tscon
         return undefined;
     }
 }
-function buildDeclarationFileName(specifier) {
-    const digest = crypto.createHash('sha1').update(specifier).digest('hex').slice(0, 12);
-    return `knt-${digest}.d.ts`;
-}
-function formatModuleDeclaration(specifier, variant, selectors) {
-    const literalSpecifier = JSON.stringify(specifier);
-    const selectorType = formatSelectorType(selectors);
-    const header = `declare module ${literalSpecifier} {`;
-    const footer = '}';
-    if (variant === 'types') {
-        return `${header}
-  export const knightedCss: string
-  export const stableSelectors: ${selectorType}
-${footer}
-`;
-    }
-    const stableLine = `  export const stableSelectors: ${selectorType}`;
-    const shared = `  const combined: KnightedCssCombinedModule<Record<string, unknown>>
-  export const knightedCss: string
-${stableLine}`;
-    if (variant === 'combined') {
-        return `${header}
-${shared}
-  export default combined
-${footer}
-`;
-    }
-    return `${header}
-${shared}
-${footer}
-`;
+function buildSelectorModuleManifestKey(resolvedPath) {
+    return resolvedPath.split(path.sep).join('/');
 }
-function formatSelectorType(selectors) {
-    if (selectors.size === 0) {
-        return 'Readonly<Record<string, string>>';
-    }
+function buildSelectorModulePath(resolvedPath) {
+    return `${resolvedPath}${SELECTOR_MODULE_SUFFIX}`;
+}
+function formatSelectorModuleSource(selectors) {
+    const header = '// Generated by @knighted/css/generate-types\n// Do not edit.\n';
     const entries = Array.from(selectors.entries()).sort(([a], [b]) => a.localeCompare(b));
-    const lines = entries.map(([token, selector]) => `    readonly ${JSON.stringify(token)}: ${JSON.stringify(selector)}`);
-    return `Readonly<{
+    const lines = entries.map(([token, selector]) => `  ${JSON.stringify(token)}: ${JSON.stringify(selector)},`);
+    const literal = lines.length > 0
+        ? `{
 ${lines.join('\n')}
-  }>`;
-}
-function buildDeclarationModuleSpecifier(resolvedPath, declarationDir, query) {
-    const relativePath = path.relative(declarationDir, resolvedPath);
-    const normalizedPath = normalizeRelativePath(relativePath);
-    const canonicalQuery = buildCanonicalQuery(query);
-    return `${normalizedPath}${canonicalQuery}`;
-}
-function normalizeRelativePath(relativePath) {
-    let normalized = relativePath.split(path.sep).join('/');
-    if (!normalized || normalized === '') {
-        normalized = '.';
-    }
-    if (normalized === '.') {
-        return './';
-    }
-    if (normalized.startsWith('./') || normalized.startsWith('../')) {
-        return normalized;
-    }
-    if (normalized.startsWith('.')) {
-        return normalized;
-    }
-    return `./${normalized}`;
-}
-function buildCanonicalQuery(query) {
-    if (!query) {
-        return '';
-    }
-    const sanitized = buildSanitizedQuery(query);
-    const extraParts = sanitized ? sanitized.slice(1).split('&').filter(Boolean) : [];
-    const parts = [];
-    parts.push('knighted-css');
-    if (hasQueryFlag(query, COMBINED_QUERY_FLAG)) {
-        parts.push(COMBINED_QUERY_FLAG);
-    }
-    for (const flag of NAMED_ONLY_QUERY_FLAGS) {
-        if (hasQueryFlag(query, flag)) {
-            parts.push(flag);
-        }
-    }
-    if (hasQueryFlag(query, TYPES_QUERY_FLAG)) {
-        parts.push(TYPES_QUERY_FLAG);
-    }
-    const merged = [...parts, ...extraParts];
-    return merged.length > 0 ? `?${merged.join('&')}` : '';
+} as const`
+        : '{} as const';
+    return `${header}
+export const stableSelectors = ${literal}
+
+export type KnightedCssStableSelectors = typeof stableSelectors
+export type KnightedCssStableSelectorToken = keyof typeof stableSelectors
+
+export default stableSelectors
+`;
 }
 function hashContent(content) {
     return crypto.createHash('sha1').update(content).digest('hex');
@@ -377,13 +310,12 @@ async function readManifest(manifestPath) {
 async function writeManifest(manifestPath, manifest) {
     await fs.writeFile(manifestPath, JSON.stringify(manifest, null, 2), 'utf8');
 }
-async function removeStaleDeclarations(previous, next, outDir) {
-    const stale = Object.entries(previous).filter(([specifier]) => !next[specifier]);
+async function removeStaleSelectorModules(previous, next) {
+    const stale = Object.entries(previous).filter(([key]) => !next[key]);
     let removed = 0;
     for (const [, entry] of stale) {
-        const targetPath = path.join(outDir, entry.file);
         try {
-            await fs.unlink(targetPath);
+            await fs.unlink(entry.file);
             removed += 1;
         }
         catch {
@@ -392,25 +324,6 @@ async function removeStaleDeclarations(previous, next, outDir) {
     }
     return removed;
 }
-async function writeTypesIndex(indexPath, manifest, outDir) {
-    const header = '// Generated by @knighted/css/generate-types\n// Do not edit.\n';
-    const references = Object.values(manifest)
-        .sort((a, b) => a.file.localeCompare(b.file))
-        .map(entry => {
-        const rel = path
-            .relative(path.dirname(indexPath), path.join(outDir, entry.file))
-            .split(path.sep)
-            .join('/');
-        return `/// <reference path="${rel}" />`;
-    });
-    const content = references.length > 0
-        ? `${header}
-${references.join('\n')}
-`
-        : `${header}
-`;
-    await fs.writeFile(indexPath, content, 'utf8');
-}
 function formatErrorMessage(error) {
     if (error instanceof Error && typeof error.message === 'string') {
         return error.message;
@@ -420,6 +333,23 @@ function formatErrorMessage(error) {
 function relativeToRoot(filePath, rootDir) {
     return path.relative(rootDir, filePath) || filePath;
 }
+function isWithinRoot(filePath, rootDir) {
+    const relative = path.relative(rootDir, filePath);
+    return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+async function ensureSelectorModule(resolvedPath, selectors, previousManifest, nextManifest) {
+    const manifestKey = buildSelectorModuleManifestKey(resolvedPath);
+    const targetPath = buildSelectorModulePath(resolvedPath);
+    const source = formatSelectorModuleSource(selectors);
+    const hash = hashContent(source);
+    const previousEntry = previousManifest[manifestKey];
+    const needsWrite = previousEntry?.hash !== hash || !(await fileExists(targetPath));
+    if (needsWrite) {
+        await fs.writeFile(targetPath, source, 'utf8');
+    }
+    nextManifest[manifestKey] = { file: targetPath, hash };
+    return needsWrite;
+}
 async function fileExists(target) {
     try {
         await fs.access(target);
@@ -543,7 +473,6 @@ export async function runGenerateTypesCli(argv = process.argv.slice(2)) {
             rootDir: parsed.rootDir,
             include: parsed.include,
             outDir: parsed.outDir,
-            typesRoot: parsed.typesRoot,
             stableNamespace: parsed.stableNamespace,
         });
         reportCliResult(result);
@@ -558,12 +487,11 @@ function parseCliArgs(argv) {
     let rootDir = process.cwd();
     const include = [];
     let outDir;
-    let typesRoot;
     let stableNamespace;
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i];
         if (arg === '--help' || arg === '-h') {
-            return { rootDir, include, outDir, typesRoot, stableNamespace, help: true };
+            return { rootDir, include, outDir, stableNamespace, help: true };
         }
         if (arg === '--root' || arg === '-r') {
             const value = argv[++i];
@@ -589,14 +517,6 @@ function parseCliArgs(argv) {
             outDir = value;
             continue;
         }
-        if (arg === '--types-root') {
-            const value = argv[++i];
-            if (!value) {
-                throw new Error('Missing value for --types-root');
-            }
-            typesRoot = value;
-            continue;
-        }
         if (arg === '--stable-namespace') {
             const value = argv[++i];
             if (!value) {
@@ -610,7 +530,7 @@ function parseCliArgs(argv) {
         }
         include.push(arg);
     }
-    return { rootDir, include, outDir, typesRoot, stableNamespace };
+    return { rootDir, include, outDir, stableNamespace };
 }
 function printHelp() {
     console.log(`Usage: knighted-css-generate-types [options]
@@ -618,20 +538,19 @@ function printHelp() {
 Options:
   -r, --root <path>              Project root directory (default: cwd)
   -i, --include <path>           Additional directories/files to scan (repeatable)
-      --out-dir <path>           Output directory for generated declarations
-      --types-root <path>        Directory for generated @types entrypoint
+      --out-dir <path>           Directory to store selector module manifest cache
       --stable-namespace <name>  Stable namespace prefix for generated selector maps
   -h, --help                     Show this help message
 `);
 }
 function reportCliResult(result) {
-    if (result.written === 0 && result.removed === 0) {
-        console.log('[knighted-css] No changes to ?knighted-css&types declarations (cache is up to date).');
+    if (result.selectorModulesWritten === 0 && result.selectorModulesRemoved === 0) {
+        console.log('[knighted-css] Selector modules are up to date.');
     }
     else {
-        console.log(`[knighted-css] Updated ${result.written} declaration(s), removed ${result.removed}, output in ${result.outDir}.`);
+        console.log(`[knighted-css] Selector modules updated: wrote ${result.selectorModulesWritten}, removed ${result.selectorModulesRemoved}.`);
     }
-    console.log(`[knighted-css] Type references: ${result.typesIndexPath}`);
+    console.log(`[knighted-css] Manifest: ${result.manifestPath}`);
     for (const warning of result.warnings) {
         console.warn(`[knighted-css] ${warning}`);
     }
@@ -646,17 +565,12 @@ function setImportMetaUrlProvider(provider) {
     importMetaUrlProvider = provider ?? getImportMetaUrl;
 }
 export const __generateTypesInternals = {
-    writeTypesIndex,
     stripInlineLoader,
     splitResourceAndQuery,
+    extractSelectorSourceSpecifier,
     findSpecifierImports,
     resolveImportPath,
     resolvePackageRoot,
-    buildDeclarationFileName,
-    formatModuleDeclaration,
-    formatSelectorType,
-    buildDeclarationModuleSpecifier,
-    buildCanonicalQuery,
     relativeToRoot,
     collectCandidateFiles,
     normalizeIncludeOptions,
@@ -672,4 +586,11 @@ export const __generateTypesInternals = {
     parseCliArgs,
     printHelp,
     reportCliResult,
+    buildSelectorModuleManifestKey,
+    buildSelectorModulePath,
+    formatSelectorModuleSource,
+    ensureSelectorModule,
+    removeStaleSelectorModules,
+    readManifest,
+    writeManifest,
 };

package/dist/stableSelectors.d.ts

@@ -5,9 +5,24 @@ export interface StableClassNameOptions extends StableSelectorOptions {
     token?: string;
     join?: (values: string[]) => string;
 }
+export interface MergeStableClassSingleInput extends StableSelectorOptions {
+    hashed: string | string[];
+    selector?: string;
+    token: string;
+    join?: (values: string[]) => string;
+}
+export interface MergeStableClassBatchInput<Hashed extends Record<string, string | string[]>, Selectors extends Record<string, string> | undefined = Record<string, string>> extends StableSelectorOptions {
+    hashed: Hashed;
+    selectors?: Selectors;
+    join?: (values: string[]) => string;
+}
 export declare function stableToken(token: string, options?: StableSelectorOptions): string;
 export declare function stableClass(token: string, options?: StableSelectorOptions): string;
 export declare function stableSelector(token: string, options?: StableSelectorOptions): string;
 export declare function createStableClassFactory(options?: StableSelectorOptions): (token: string) => string;
 export declare function stableClassName<T extends Record<string, string>>(styles: T, key: keyof T | string, options?: StableClassNameOptions): string;
 export declare const stableClassFromModule: typeof stableClassName;
+export declare function mergeStableClass(input: MergeStableClassSingleInput): string;
+export declare function mergeStableClass<Hashed extends Record<string, string | string[]>>(input: MergeStableClassBatchInput<Hashed>): {
+    [Key in keyof Hashed]: string;
+};

package/dist/stableSelectors.js

@@ -1,5 +1,6 @@
 const DEFAULT_NAMESPACE = 'knighted';
 const defaultJoin = (values) => values.filter(Boolean).join(' ');
+const toArray = (value) => Array.isArray(value) ? value : [value];
 const normalizeToken = (token) => {
     const sanitized = token
         .trim()
@@ -34,3 +35,30 @@ export function stableClassName(styles, key, options) {
     return join([hashed, stable]);
 }
 export const stableClassFromModule = stableClassName;
+export function mergeStableClass(input) {
+    if ('token' in input) {
+        return mergeSingle(input);
+    }
+    return mergeBatch(input);
+}
+function mergeSingle(input) {
+    const join = input.join ?? defaultJoin;
+    const hashed = toArray(input.hashed);
+    const stable = input.selector?.trim().length
+        ? input.selector
+        : stableClass(input.token, { namespace: input.namespace });
+    return join([...hashed, stable]);
+}
+function mergeBatch(input) {
+    const join = input.join ?? defaultJoin;
+    const output = {};
+    for (const key of Object.keys(input.hashed)) {
+        const hashedValue = input.hashed[key];
+        const selector = input.selectors?.[String(key)];
+        const stable = selector?.trim().length
+            ? selector
+            : stableClass(String(key), { namespace: input.namespace });
+        output[key] = join([...toArray(hashedValue), stable]);
+    }
+    return output;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knighted/css",
-  "version": "1.0.0-rc.11",
+  "version": "1.0.0-rc.13",
   "description": "A build-time utility that traverses JavaScript/TypeScript module dependency graphs to extract, compile, and optimize all imported CSS into a single, in-memory string.",
   "type": "module",
   "main": "./dist/css.js",