@csszyx/unplugin 0.12.0 → 0.14.0

package/dist/shared/{unplugin.CtnKJhAi.d.cts → unplugin.BsjD3mtb.d.cts}

@@ -65,7 +65,7 @@ interface GlobalVarScanCacheKeyInput {
     /** Source file mtime in milliseconds. */
     mtimeMs: number;
 }
-/** CSS source supplied to the Phase H validation orchestrator. */
+/** CSS source supplied to the global-variable validation orchestrator. */
 interface GlobalVarCssSource {
     /** Source file path. */
     filePath: string;
@@ -74,7 +74,7 @@ interface GlobalVarCssSource {
     /** Source file mtime in milliseconds, used when cacheDir is set. */
     mtimeMs?: number;
 }
-/** JS/TS/JSX/TSX source supplied to the Phase H validation orchestrator. */
+/** JS/TS/JSX/TSX source supplied to the global-variable validation orchestrator. */
 interface GlobalVarCodeSource {
     /** Source file path. */
     filePath: string;
@@ -101,7 +101,7 @@ type GlobalVarAliasDiagnosticSeverity = 'error';
 interface GlobalVarAliasDiagnostic {
     /** Machine-readable diagnostic code. */
     code: 'missing-definition' | 'tailwind-reserved' | 'tailwind-owned' | 'registered-property' | 'alias-collision';
-    /** Diagnostic severity. Phase H M2 is fail-closed. */
+    /** Diagnostic severity. Every finding fails the build. */
     severity: GlobalVarAliasDiagnosticSeverity;
     /** Related custom-property name. */
     name: string;
@@ -141,7 +141,7 @@ interface GlobalVarAliasPlan {
     /** Planner diagnostics. */
     diagnostics: GlobalVarAliasDiagnostic[];
 }
-/** Input for Phase H scanner/planner/diagnostics integration. */
+/** Input for the global-variable scanner/planner/diagnostics integration. */
 interface ValidateGlobalVarAliasInputsOptions {
     /** CSS sources that define or reference custom properties. */
     cssFiles: GlobalVarCssSource[];
@@ -177,7 +177,7 @@ interface CreateGlobalVarAliasValidationOptionsInput {
     /** Optional global-var scan cache directory. */
     cacheDir?: string;
 }
-/** Output from Phase H scanner/planner/diagnostics integration. */
+/** Output from the global-variable scanner/planner/diagnostics integration. */
 interface GlobalVarAliasValidationResult {
     /** CSS scan results. */
     scans: CssVarScanResult[];
@@ -405,12 +405,21 @@ interface PluginState {
      * Drives the `@source` safelist; NOT the mangle map.
      */
     classes: Set<string>;
-    /** Merged @theme scan result — feeds the theme-groups virtual module. */
+    /**
+     * Merged @theme scan result — the ONLY consumer is the theme-groups virtual
+     * module, so this is a merge-correctness input, not a typing one.
+     */
     parsedTheme: ParsedTheme | null;
     /**
-     * CSS files the zero-config @theme auto-scan found tokens in (only when
-     * `build.scanCss` is unset). Dev HMR re-scans when one of these — or any
-     * other .css file — changes, mirroring the explicit scanCss reload path.
+     * Tokens from the files `build.scanCss` lists, kept apart from the
+     * project-wide discovery so a token deleted from either source disappears
+     * from the merged result instead of lingering across a re-scan.
+     */
+    scanCssTheme: ParsedTheme | null;
+    /**
+     * CSS files the project-wide @theme scan found tokens in. Dev HMR re-scans
+     * when one of these — or any other .css file — changes, mirroring the
+     * explicit scanCss reload path.
      */
     autoThemeCssFiles: string[];
     /**
@@ -450,11 +459,29 @@ interface PluginState {
     /** Unresolvable-spread warnings surfaced to the build log in every mode. */
     spreadWarnings: Set<string>;
     /**
-     * Workspace-package files under `/packages/` that contain `sz` but were
+     * Advisory sz fallbacks this build declined to list.
+     *
+     * Counted so the build can say the list is partial. Printing nothing is not
+     * the same as printing "nothing happened", and a log that names five
+     * fallbacks while holding three back reads as a total.
+     */
+    suppressedAdvisories: number;
+    /**
+     * Workspace-package files under `/packages/` that use csszyx but were
      * skipped by the hard-ignore (not under any `compileSources` dir). Surfaced at
      * build end so the silent no-op (skipped `sz` → no CSS) becomes visible.
      */
     skippedSzFiles: Set<string>;
+    /**
+     * The subset of {@link skippedSzFiles} that may export szv factories.
+     *
+     * Skipping one of these does more than lose a file's own CSS: it keeps the
+     * module out of the cross-module registry, so every importer — compiled or
+     * not — silently falls back to the runtime path. That is dropped csszyx
+     * output rather than a usage nudge, so its presence promotes the warning
+     * out of dev-only.
+     */
+    skippedSzvExportFiles: Set<string>;
     /** Guards the skipped-sz-files warning so it fires at most once. */
     skipWarningEmitted: boolean;
     /**
@@ -608,10 +635,10 @@ declare function collectMangleHybridHazards(mangleMap: Record<string, string>, m
 declare function mangleHybridHazardMessage(hazards: MangleHybridHazards): string | null;
 /**
  * Whether a CSS module scopes Tailwind's content detection — `source(none)` or
- * `source("…")` on the `@import "tailwindcss"`, or any `@source not` exclusion.
+ * `source("…")` on a `@import "tailwindcss"`, or any `@source not` exclusion.
  * A plain additive `@source "…"` does NOT count: it only adds a path, it does
- * not stop the automatic climb-to-the-workspace-root scan. Block comments are
- * stripped first so a commented-out directive does not count.
+ * not stop the automatic scan. Block comments are stripped first so a
+ * commented-out directive does not count.
  *
  * @param code - CSS module source.
  * @returns true when the entry scopes (or excludes from) content detection.
@@ -644,38 +671,104 @@ declare function shouldWarnUnscopedMonorepo(sawTailwindEntry: boolean, tailwindE
 /**
  * Build the unscoped-monorepo warning message: what is wrong, why it matters,
  * the exact two-line fix, the guide link, and how to silence it.
+ *
+ * Describes the detection BASE rather than promising a climb to the workspace
+ * root. Measured on a workspace package built through the Vite plugin, the scan
+ * was rooted at the Vite root: files beside the entry were scanned, the sibling
+ * package and the workspace root were not. Naming a worse failure than the one
+ * that is happening is how an advisory gets discounted — a reader who checks
+ * for phantom classes from sibling packages finds none and stops believing the
+ * rest of the message.
+ *
+ * The suggested snippet carries no CSS comment on purpose. A block comment ends
+ * at the first `*` followed by `/`, which any recursive glob contains, so
+ * inviting the reader to annotate `@source` lines invites a stylesheet that
+ * stops parsing where they documented it.
+ *
  * @returns the warning string.
  */
 declare function unscopedMonorepoMessage(): string;
 /**
- * Whether a csszyx build warning should be emitted. `quiet` mutes all of them;
- * `devOnly` additionally suppresses the warning in a production build (for usage
- * nudges that must not noise a host app's prod output). Pure so the gating policy
- * is unit-tested without the worker-based buildEnd wiring.
+ * Whether a diagnostic is an advisory one — the class a build may hold back.
+ *
+ * Spread warnings, budget bails and `missing-css` fallbacks all describe absent
+ * output and print regardless. What is left says the runtime path was taken
+ * where a compiled one was possible: real, worth acting on, and not a failure.
+ *
+ * @param message - One raw diagnostic line as an engine emitted it.
+ * @returns True when the diagnostic is advisory rather than a build result.
+ */
+declare function isAdvisoryDiagnostic(message: string): boolean;
+/**
+ * Build the one-line disclosure that the fallback list above is partial.
+ *
+ * Four of the five `sz`-site fallback kinds never print in a production build,
+ * so a log can list the `szr` fallbacks it found and silently hold every
+ * `sz={factory()}` beside them. A consumer counting affected sites from that
+ * log counts a lower bound and has no way to know it — one reported a site
+ * count that was short by half for exactly this reason, and only caught it by
+ * reading sources instead.
+ *
+ * Suppression is the right default; implying zero is not. One line costs
+ * nothing and keeps the difference visible.
+ *
+ * @param count - Advisory fallbacks the build declined to list.
+ * @returns The disclosure, or null when nothing was held back.
+ */
+declare function suppressedAdvisoryMessage(count: number): string | null;
+/**
+ * The `quiet` option, normalized.
+ *
+ * `'all'` is the blunt setting a plain `true` selects; `'nudges'` keeps every
+ * report that the build produced less output than it was asked for.
+ */
+type QuietMode = 'off' | 'nudges' | 'all';
+/**
+ * Normalize the authored `quiet` value. Idempotent, so a already-normalized
+ * mode passes through unchanged.
+ *
+ * @param quiet - Authored option value, or an already-resolved mode.
+ * @returns The mode the gates read.
+ */
+declare function resolveQuietMode(quiet: boolean | 'nudges' | QuietMode | undefined): QuietMode;
+/**
+ * Whether a csszyx build warning should be emitted.
+ *
+ * `devOnly` is already this plugin's marker for "usage nudge": it suppresses
+ * the warning in a production build so it cannot noise a host app's output.
+ * `'nudges'` mutes exactly that same set, which keeps one axis instead of
+ * inventing a second classification for the same distinction. `true` mutes
+ * everything. Pure so the gating policy is unit-tested without the
+ * worker-based buildEnd wiring.
  *
- * @param quiet - The `quiet` option: mute every warning.
- * @param devOnly - This warning is a dev-only usage nudge.
+ * @param quiet - Resolved quiet mode.
+ * @param devOnly - This warning is a usage nudge.
  * @param isProduction - Whether this is a production build.
  * @returns true when the warning should be printed.
  */
-declare function shouldEmitWarning(quiet: boolean, devOnly: boolean, isProduction: boolean): boolean;
+declare function shouldEmitWarning(quiet: QuietMode, devOnly: boolean, isProduction: boolean): boolean;
 /**
  * Whether a transform diagnostic describes missing CSS and may be printed.
  *
- * @param quiet - Whether all build warnings are muted.
+ * Only the blunt mode hides these. A missing-CSS diagnostic says classes never
+ * reached the safelist, so the styles are absent from the output — a build
+ * result, not a style opinion, and `'nudges'` exists so a calmer log does not
+ * have to cost it.
+ *
+ * @param quiet - Resolved quiet mode.
  * @param message - Compiler diagnostic to classify.
  * @returns True when the diagnostic is an unsilenced missing-CSS failure.
  */
-declare function shouldEmitMissingCssFallback(quiet: boolean, message: string): boolean;
+declare function shouldEmitMissingCssFallback(quiet: QuietMode, message: string): boolean;
 /**
  * Emit one missing-CSS fallback through the caller's output channel.
  *
- * @param quiet - Whether all build warnings are muted.
+ * @param quiet - Resolved quiet mode.
  * @param message - Compiler diagnostic to classify and emit.
  * @param id - Bundler module identifier included in the warning.
  * @param emit - Warning output channel.
  */
-declare function emitMissingCssFallback(quiet: boolean, message: string, id: string, emit: (message: string) => void): void;
+declare function emitMissingCssFallback(quiet: QuietMode, message: string, id: string, emit: (message: string) => void): void;
 /**
  * Resolve `compileSources` entries to absolute, realpath-resolved directories.
  * Each entry resolves like a Vite config path: relative to the project `root`
@@ -770,14 +863,46 @@ declare function allocateMangleTokens(eligibleClasses: readonly string[], forbid
  */
 declare function isPackagesSkippedSource(id: string, sourceDirs?: readonly string[]): boolean;
 /**
- * Build the workspace-package skip warning. Lists the skipped files that contain
- * `sz` so the developer can add the package directory to `compileSources`
+ * Build the workspace-package skip warning. Lists the skipped files that use
+ * csszyx so the developer can add the package directory to `compileSources`
  * instead of silently shipping no CSS for them.
  *
- * @param files - skipped `/packages/` file paths that contain `sz`.
+ * @param files - skipped `/packages/` file paths that use csszyx.
+ * @param szvExportFiles - the subset that may export `szv` factories, whose
+ *   skip also costs every importer its cross-module precompile.
  * @returns the warning string.
  */
-declare function skippedSzFilesMessage(files: readonly string[]): string;
+declare function skippedSzFilesMessage(files: readonly string[], szvExportFiles?: readonly string[]): string;
+/**
+ * Explains a class census that grew after the mangle map was already frozen.
+ *
+ * The map is settled right after the prescan because the CSS a build ships is
+ * hashed while it is still being transformed. A class discovered later would be
+ * mangled in one artifact and not in another, so the build stops here rather
+ * than emitting output whose CSS, JS and HTML disagree.
+ *
+ * @param lateOwned csszyx-owned classes first seen after the freeze.
+ * @param lateAuthored raw author classes first seen after the freeze.
+ * @returns the error text.
+ */
+declare function lateMangleCensusMessage(lateOwned: readonly string[], lateAuthored: readonly string[]): string;
+/**
+ * Explains why a watch build does not mangle.
+ *
+ * @returns the warning text.
+ */
+declare function watchModeMangleMessage(): string;
+/**
+ * Explains why webpack must keep recomputing content hashes.
+ *
+ * csszyx rewrites webpack assets in `processAssets`, which is only safe
+ * because `optimization.realContentHash` runs later and recomputes each hash
+ * from the final bytes. Turning it off puts webpack back in the state this
+ * release fixed for Vite: same filename, different bytes.
+ *
+ * @returns the warning text.
+ */
+declare function realContentHashDisabledMessage(): string;
 /**
  * Computes the `@source` target path for a CSS module: the location of the
  * generated safelist file relative to the CSS file, in posix form and always
@@ -807,8 +932,8 @@ declare function shouldTrackGlobalVarSources(config?: {
     enabled?: boolean;
 }): boolean;
 /**
- * Records source text available before bundling/minification for Phase H
- * global-var diagnostics.
+ * Records source text available before bundling/minification for global-var
+ * diagnostics.
  *
  * @param state Plugin state to update.
  * @param filename Source filename that owns the text.
@@ -816,7 +941,14 @@ declare function shouldTrackGlobalVarSources(config?: {
  */
 declare function recordGlobalVarSourceFile(state: Pick<PluginState, 'globalVarSourceFilesByFile'>, filename: string, code: string | null): void;
 /**
- * Extracts Phase H global custom-property aliases for manifest/debug tooling.
+ * Decides whether a module id is a stylesheet csszyx should rewrite.
+ *
+ * @param id Bundler module identifier.
+ * @returns True for a stylesheet whose text is destined for emitted CSS.
+ */
+declare function isMangleableCssId(id: string): boolean;
+/**
+ * Extracts global custom-property aliases for manifest/debug tooling.
  *
  * The legacy `varMangleMap` also carries dynamic s/c-tier CSS variables. This
  * helper keeps manifest consumers from guessing tiers by exposing only aliases
@@ -886,5 +1018,5 @@ declare const rollupPlugin: (options?: PartialCsszyxConfig) => InputPluginOption
  */
 declare const esbuildPlugin: (options?: PartialCsszyxConfig) => Plugin;
 
-export { mangleEligibleClasses as $, cssImportsTailwind as A, unplugin as B, deleteRSCModuleRecord as D, emitMissingCssFallback as E, esbuildPlugin as F, extractGlobalVarAliasesForManifest as H, fileMayContainSafelistableSz as I, findLocalImportSources as J, findRSCBoundaryViolation as K, findRSCGraphViolation as L, hasInjectableTailwindCandidate as N, hasTokens as O, hasUseClientDirective as Q, hasUseServerDirective as T, isCompileSourceOptedIn as U, isHardIgnoredPath as W, isMonorepoPackage as X, isPackagesSkippedSource as Y, isRSCServerModule as Z, mangleCodeClassesSync as _, mangleHybridHazardMessage as a0, mergeThemes as a1, missingTailwindEntryMessage as a2, normalizeGlobalVarAliasesForCache as a3, parseThemeBlocks as a4, recordGlobalVarSourceFile as a5, resolveCompileSourceDirs as a6, resolveNativeCacheIdentity as a7, rollupPlugin as a8, scanCustomPropertyNames as a9, shouldEmitMissingCssFallback as aa, shouldEmitWarning as ab, shouldTrackGlobalVarSources as ac, shouldWarnMissingTailwindEntry as ad, shouldWarnUnscopedMonorepo as ae, skippedSzFilesMessage as af, unscopedMonorepoMessage as ag, vitePlugin as ah, webpackPlugin as ai, allocateMangleTokens as r, appendTailwindSourceDirective as s, assertNoRSCBoundaryViolation as t, assertNoRSCGraphViolation as u, collectMangleHybridHazards as v, computeSafelistRelPath as w, createGlobalVarMapAssetSource as x, createRSCModuleRecord as y, cssHasContentScope as z };
-export type { CssVarScanResult as C, GlobalVarScanCacheKeyInput as G, MangleHybridHazards as M, PlanGlobalVarAliasesInput as P, RewriteGlobalVarCssAliasesOptions as R, ScanGlobalVarCssOptions as S, ValidateGlobalVarAliasInputsOptions as V, GlobalVarAliasPlan as a, GlobalVarCssAliasRewriteResult as b, CreateGlobalVarAliasValidationOptionsInput as c, GlobalVarAliasValidationResult as d, CssVarDefinition as e, CssVarLocation as f, CssVarReference as g, GlobalVarAliasDiagnostic as h, GlobalVarAliasDiagnosticSeverity as i, GlobalVarAliasEntry as j, GlobalVarCodeSource as k, GlobalVarCssAssetSource as l, GlobalVarCssSource as m, GlobalVarScanCacheEntry as n, ParsedTheme as o, RSCBoundaryViolation as p, RSCModuleRecord as q };
+export { isPackagesSkippedSource as $, cssImportsTailwind as A, unplugin as B, deleteRSCModuleRecord as D, emitMissingCssFallback as E, esbuildPlugin as F, extractGlobalVarAliasesForManifest as H, fileMayContainSafelistableSz as I, findLocalImportSources as J, findRSCBoundaryViolation as K, findRSCGraphViolation as L, hasInjectableTailwindCandidate as N, hasTokens as O, hasUseClientDirective as T, hasUseServerDirective as U, isAdvisoryDiagnostic as W, isCompileSourceOptedIn as X, isHardIgnoredPath as Y, isMangleableCssId as Z, isMonorepoPackage as _, isRSCServerModule as a0, lateMangleCensusMessage as a1, mangleCodeClassesSync as a2, mangleEligibleClasses as a3, mangleHybridHazardMessage as a4, mergeThemes as a5, missingTailwindEntryMessage as a6, normalizeGlobalVarAliasesForCache as a7, parseThemeBlocks as a8, realContentHashDisabledMessage as a9, recordGlobalVarSourceFile as aa, resolveCompileSourceDirs as ab, resolveNativeCacheIdentity as ac, resolveQuietMode as ad, rollupPlugin as ae, scanCustomPropertyNames as af, shouldEmitMissingCssFallback as ag, shouldEmitWarning as ah, shouldTrackGlobalVarSources as ai, shouldWarnMissingTailwindEntry as aj, shouldWarnUnscopedMonorepo as ak, skippedSzFilesMessage as al, suppressedAdvisoryMessage as am, unscopedMonorepoMessage as an, vitePlugin as ao, watchModeMangleMessage as ap, webpackPlugin as aq, allocateMangleTokens as r, appendTailwindSourceDirective as s, assertNoRSCBoundaryViolation as t, assertNoRSCGraphViolation as u, collectMangleHybridHazards as v, computeSafelistRelPath as w, createGlobalVarMapAssetSource as x, createRSCModuleRecord as y, cssHasContentScope as z };
+export type { CssVarScanResult as C, GlobalVarScanCacheKeyInput as G, MangleHybridHazards as M, PlanGlobalVarAliasesInput as P, QuietMode as Q, RewriteGlobalVarCssAliasesOptions as R, ScanGlobalVarCssOptions as S, ValidateGlobalVarAliasInputsOptions as V, GlobalVarAliasPlan as a, GlobalVarCssAliasRewriteResult as b, CreateGlobalVarAliasValidationOptionsInput as c, GlobalVarAliasValidationResult as d, CssVarDefinition as e, CssVarLocation as f, CssVarReference as g, GlobalVarAliasDiagnostic as h, GlobalVarAliasDiagnosticSeverity as i, GlobalVarAliasEntry as j, GlobalVarCodeSource as k, GlobalVarCssAssetSource as l, GlobalVarCssSource as m, GlobalVarScanCacheEntry as n, ParsedTheme as o, RSCBoundaryViolation as p, RSCModuleRecord as q };

package/dist/shared/{unplugin.CtnKJhAi.d.mts → unplugin.BsjD3mtb.d.mts}

@@ -65,7 +65,7 @@ interface GlobalVarScanCacheKeyInput {
     /** Source file mtime in milliseconds. */
     mtimeMs: number;
 }
-/** CSS source supplied to the Phase H validation orchestrator. */
+/** CSS source supplied to the global-variable validation orchestrator. */
 interface GlobalVarCssSource {
     /** Source file path. */
     filePath: string;
@@ -74,7 +74,7 @@ interface GlobalVarCssSource {
     /** Source file mtime in milliseconds, used when cacheDir is set. */
     mtimeMs?: number;
 }
-/** JS/TS/JSX/TSX source supplied to the Phase H validation orchestrator. */
+/** JS/TS/JSX/TSX source supplied to the global-variable validation orchestrator. */
 interface GlobalVarCodeSource {
     /** Source file path. */
     filePath: string;
@@ -101,7 +101,7 @@ type GlobalVarAliasDiagnosticSeverity = 'error';
 interface GlobalVarAliasDiagnostic {
     /** Machine-readable diagnostic code. */
     code: 'missing-definition' | 'tailwind-reserved' | 'tailwind-owned' | 'registered-property' | 'alias-collision';
-    /** Diagnostic severity. Phase H M2 is fail-closed. */
+    /** Diagnostic severity. Every finding fails the build. */
     severity: GlobalVarAliasDiagnosticSeverity;
     /** Related custom-property name. */
     name: string;
@@ -141,7 +141,7 @@ interface GlobalVarAliasPlan {
     /** Planner diagnostics. */
     diagnostics: GlobalVarAliasDiagnostic[];
 }
-/** Input for Phase H scanner/planner/diagnostics integration. */
+/** Input for the global-variable scanner/planner/diagnostics integration. */
 interface ValidateGlobalVarAliasInputsOptions {
     /** CSS sources that define or reference custom properties. */
     cssFiles: GlobalVarCssSource[];
@@ -177,7 +177,7 @@ interface CreateGlobalVarAliasValidationOptionsInput {
     /** Optional global-var scan cache directory. */
     cacheDir?: string;
 }
-/** Output from Phase H scanner/planner/diagnostics integration. */
+/** Output from the global-variable scanner/planner/diagnostics integration. */
 interface GlobalVarAliasValidationResult {
     /** CSS scan results. */
     scans: CssVarScanResult[];
@@ -405,12 +405,21 @@ interface PluginState {
      * Drives the `@source` safelist; NOT the mangle map.
      */
     classes: Set<string>;
-    /** Merged @theme scan result — feeds the theme-groups virtual module. */
+    /**
+     * Merged @theme scan result — the ONLY consumer is the theme-groups virtual
+     * module, so this is a merge-correctness input, not a typing one.
+     */
     parsedTheme: ParsedTheme | null;
     /**
-     * CSS files the zero-config @theme auto-scan found tokens in (only when
-     * `build.scanCss` is unset). Dev HMR re-scans when one of these — or any
-     * other .css file — changes, mirroring the explicit scanCss reload path.
+     * Tokens from the files `build.scanCss` lists, kept apart from the
+     * project-wide discovery so a token deleted from either source disappears
+     * from the merged result instead of lingering across a re-scan.
+     */
+    scanCssTheme: ParsedTheme | null;
+    /**
+     * CSS files the project-wide @theme scan found tokens in. Dev HMR re-scans
+     * when one of these — or any other .css file — changes, mirroring the
+     * explicit scanCss reload path.
      */
     autoThemeCssFiles: string[];
     /**
@@ -450,11 +459,29 @@ interface PluginState {
     /** Unresolvable-spread warnings surfaced to the build log in every mode. */
     spreadWarnings: Set<string>;
     /**
-     * Workspace-package files under `/packages/` that contain `sz` but were
+     * Advisory sz fallbacks this build declined to list.
+     *
+     * Counted so the build can say the list is partial. Printing nothing is not
+     * the same as printing "nothing happened", and a log that names five
+     * fallbacks while holding three back reads as a total.
+     */
+    suppressedAdvisories: number;
+    /**
+     * Workspace-package files under `/packages/` that use csszyx but were
      * skipped by the hard-ignore (not under any `compileSources` dir). Surfaced at
      * build end so the silent no-op (skipped `sz` → no CSS) becomes visible.
      */
     skippedSzFiles: Set<string>;
+    /**
+     * The subset of {@link skippedSzFiles} that may export szv factories.
+     *
+     * Skipping one of these does more than lose a file's own CSS: it keeps the
+     * module out of the cross-module registry, so every importer — compiled or
+     * not — silently falls back to the runtime path. That is dropped csszyx
+     * output rather than a usage nudge, so its presence promotes the warning
+     * out of dev-only.
+     */
+    skippedSzvExportFiles: Set<string>;
     /** Guards the skipped-sz-files warning so it fires at most once. */
     skipWarningEmitted: boolean;
     /**
@@ -608,10 +635,10 @@ declare function collectMangleHybridHazards(mangleMap: Record<string, string>, m
 declare function mangleHybridHazardMessage(hazards: MangleHybridHazards): string | null;
 /**
  * Whether a CSS module scopes Tailwind's content detection — `source(none)` or
- * `source("…")` on the `@import "tailwindcss"`, or any `@source not` exclusion.
+ * `source("…")` on a `@import "tailwindcss"`, or any `@source not` exclusion.
  * A plain additive `@source "…"` does NOT count: it only adds a path, it does
- * not stop the automatic climb-to-the-workspace-root scan. Block comments are
- * stripped first so a commented-out directive does not count.
+ * not stop the automatic scan. Block comments are stripped first so a
+ * commented-out directive does not count.
  *
  * @param code - CSS module source.
  * @returns true when the entry scopes (or excludes from) content detection.
@@ -644,38 +671,104 @@ declare function shouldWarnUnscopedMonorepo(sawTailwindEntry: boolean, tailwindE
 /**
  * Build the unscoped-monorepo warning message: what is wrong, why it matters,
  * the exact two-line fix, the guide link, and how to silence it.
+ *
+ * Describes the detection BASE rather than promising a climb to the workspace
+ * root. Measured on a workspace package built through the Vite plugin, the scan
+ * was rooted at the Vite root: files beside the entry were scanned, the sibling
+ * package and the workspace root were not. Naming a worse failure than the one
+ * that is happening is how an advisory gets discounted — a reader who checks
+ * for phantom classes from sibling packages finds none and stops believing the
+ * rest of the message.
+ *
+ * The suggested snippet carries no CSS comment on purpose. A block comment ends
+ * at the first `*` followed by `/`, which any recursive glob contains, so
+ * inviting the reader to annotate `@source` lines invites a stylesheet that
+ * stops parsing where they documented it.
+ *
  * @returns the warning string.
  */
 declare function unscopedMonorepoMessage(): string;
 /**
- * Whether a csszyx build warning should be emitted. `quiet` mutes all of them;
- * `devOnly` additionally suppresses the warning in a production build (for usage
- * nudges that must not noise a host app's prod output). Pure so the gating policy
- * is unit-tested without the worker-based buildEnd wiring.
+ * Whether a diagnostic is an advisory one — the class a build may hold back.
+ *
+ * Spread warnings, budget bails and `missing-css` fallbacks all describe absent
+ * output and print regardless. What is left says the runtime path was taken
+ * where a compiled one was possible: real, worth acting on, and not a failure.
+ *
+ * @param message - One raw diagnostic line as an engine emitted it.
+ * @returns True when the diagnostic is advisory rather than a build result.
+ */
+declare function isAdvisoryDiagnostic(message: string): boolean;
+/**
+ * Build the one-line disclosure that the fallback list above is partial.
+ *
+ * Four of the five `sz`-site fallback kinds never print in a production build,
+ * so a log can list the `szr` fallbacks it found and silently hold every
+ * `sz={factory()}` beside them. A consumer counting affected sites from that
+ * log counts a lower bound and has no way to know it — one reported a site
+ * count that was short by half for exactly this reason, and only caught it by
+ * reading sources instead.
+ *
+ * Suppression is the right default; implying zero is not. One line costs
+ * nothing and keeps the difference visible.
+ *
+ * @param count - Advisory fallbacks the build declined to list.
+ * @returns The disclosure, or null when nothing was held back.
+ */
+declare function suppressedAdvisoryMessage(count: number): string | null;
+/**
+ * The `quiet` option, normalized.
+ *
+ * `'all'` is the blunt setting a plain `true` selects; `'nudges'` keeps every
+ * report that the build produced less output than it was asked for.
+ */
+type QuietMode = 'off' | 'nudges' | 'all';
+/**
+ * Normalize the authored `quiet` value. Idempotent, so a already-normalized
+ * mode passes through unchanged.
+ *
+ * @param quiet - Authored option value, or an already-resolved mode.
+ * @returns The mode the gates read.
+ */
+declare function resolveQuietMode(quiet: boolean | 'nudges' | QuietMode | undefined): QuietMode;
+/**
+ * Whether a csszyx build warning should be emitted.
+ *
+ * `devOnly` is already this plugin's marker for "usage nudge": it suppresses
+ * the warning in a production build so it cannot noise a host app's output.
+ * `'nudges'` mutes exactly that same set, which keeps one axis instead of
+ * inventing a second classification for the same distinction. `true` mutes
+ * everything. Pure so the gating policy is unit-tested without the
+ * worker-based buildEnd wiring.
  *
- * @param quiet - The `quiet` option: mute every warning.
- * @param devOnly - This warning is a dev-only usage nudge.
+ * @param quiet - Resolved quiet mode.
+ * @param devOnly - This warning is a usage nudge.
  * @param isProduction - Whether this is a production build.
  * @returns true when the warning should be printed.
  */
-declare function shouldEmitWarning(quiet: boolean, devOnly: boolean, isProduction: boolean): boolean;
+declare function shouldEmitWarning(quiet: QuietMode, devOnly: boolean, isProduction: boolean): boolean;
 /**
  * Whether a transform diagnostic describes missing CSS and may be printed.
  *
- * @param quiet - Whether all build warnings are muted.
+ * Only the blunt mode hides these. A missing-CSS diagnostic says classes never
+ * reached the safelist, so the styles are absent from the output — a build
+ * result, not a style opinion, and `'nudges'` exists so a calmer log does not
+ * have to cost it.
+ *
+ * @param quiet - Resolved quiet mode.
  * @param message - Compiler diagnostic to classify.
  * @returns True when the diagnostic is an unsilenced missing-CSS failure.
  */
-declare function shouldEmitMissingCssFallback(quiet: boolean, message: string): boolean;
+declare function shouldEmitMissingCssFallback(quiet: QuietMode, message: string): boolean;
 /**
  * Emit one missing-CSS fallback through the caller's output channel.
  *
- * @param quiet - Whether all build warnings are muted.
+ * @param quiet - Resolved quiet mode.
  * @param message - Compiler diagnostic to classify and emit.
  * @param id - Bundler module identifier included in the warning.
  * @param emit - Warning output channel.
  */
-declare function emitMissingCssFallback(quiet: boolean, message: string, id: string, emit: (message: string) => void): void;
+declare function emitMissingCssFallback(quiet: QuietMode, message: string, id: string, emit: (message: string) => void): void;
 /**
  * Resolve `compileSources` entries to absolute, realpath-resolved directories.
  * Each entry resolves like a Vite config path: relative to the project `root`
@@ -770,14 +863,46 @@ declare function allocateMangleTokens(eligibleClasses: readonly string[], forbid
  */
 declare function isPackagesSkippedSource(id: string, sourceDirs?: readonly string[]): boolean;
 /**
- * Build the workspace-package skip warning. Lists the skipped files that contain
- * `sz` so the developer can add the package directory to `compileSources`
+ * Build the workspace-package skip warning. Lists the skipped files that use
+ * csszyx so the developer can add the package directory to `compileSources`
  * instead of silently shipping no CSS for them.
  *
- * @param files - skipped `/packages/` file paths that contain `sz`.
+ * @param files - skipped `/packages/` file paths that use csszyx.
+ * @param szvExportFiles - the subset that may export `szv` factories, whose
+ *   skip also costs every importer its cross-module precompile.
  * @returns the warning string.
  */
-declare function skippedSzFilesMessage(files: readonly string[]): string;
+declare function skippedSzFilesMessage(files: readonly string[], szvExportFiles?: readonly string[]): string;
+/**
+ * Explains a class census that grew after the mangle map was already frozen.
+ *
+ * The map is settled right after the prescan because the CSS a build ships is
+ * hashed while it is still being transformed. A class discovered later would be
+ * mangled in one artifact and not in another, so the build stops here rather
+ * than emitting output whose CSS, JS and HTML disagree.
+ *
+ * @param lateOwned csszyx-owned classes first seen after the freeze.
+ * @param lateAuthored raw author classes first seen after the freeze.
+ * @returns the error text.
+ */
+declare function lateMangleCensusMessage(lateOwned: readonly string[], lateAuthored: readonly string[]): string;
+/**
+ * Explains why a watch build does not mangle.
+ *
+ * @returns the warning text.
+ */
+declare function watchModeMangleMessage(): string;
+/**
+ * Explains why webpack must keep recomputing content hashes.
+ *
+ * csszyx rewrites webpack assets in `processAssets`, which is only safe
+ * because `optimization.realContentHash` runs later and recomputes each hash
+ * from the final bytes. Turning it off puts webpack back in the state this
+ * release fixed for Vite: same filename, different bytes.
+ *
+ * @returns the warning text.
+ */
+declare function realContentHashDisabledMessage(): string;
 /**
  * Computes the `@source` target path for a CSS module: the location of the
  * generated safelist file relative to the CSS file, in posix form and always
@@ -807,8 +932,8 @@ declare function shouldTrackGlobalVarSources(config?: {
     enabled?: boolean;
 }): boolean;
 /**
- * Records source text available before bundling/minification for Phase H
- * global-var diagnostics.
+ * Records source text available before bundling/minification for global-var
+ * diagnostics.
  *
  * @param state Plugin state to update.
  * @param filename Source filename that owns the text.
@@ -816,7 +941,14 @@ declare function shouldTrackGlobalVarSources(config?: {
  */
 declare function recordGlobalVarSourceFile(state: Pick<PluginState, 'globalVarSourceFilesByFile'>, filename: string, code: string | null): void;
 /**
- * Extracts Phase H global custom-property aliases for manifest/debug tooling.
+ * Decides whether a module id is a stylesheet csszyx should rewrite.
+ *
+ * @param id Bundler module identifier.
+ * @returns True for a stylesheet whose text is destined for emitted CSS.
+ */
+declare function isMangleableCssId(id: string): boolean;
+/**
+ * Extracts global custom-property aliases for manifest/debug tooling.
  *
  * The legacy `varMangleMap` also carries dynamic s/c-tier CSS variables. This
  * helper keeps manifest consumers from guessing tiers by exposing only aliases
@@ -886,5 +1018,5 @@ declare const rollupPlugin: (options?: PartialCsszyxConfig) => InputPluginOption
  */
 declare const esbuildPlugin: (options?: PartialCsszyxConfig) => Plugin;
 
-export { mangleEligibleClasses as $, cssImportsTailwind as A, unplugin as B, deleteRSCModuleRecord as D, emitMissingCssFallback as E, esbuildPlugin as F, extractGlobalVarAliasesForManifest as H, fileMayContainSafelistableSz as I, findLocalImportSources as J, findRSCBoundaryViolation as K, findRSCGraphViolation as L, hasInjectableTailwindCandidate as N, hasTokens as O, hasUseClientDirective as Q, hasUseServerDirective as T, isCompileSourceOptedIn as U, isHardIgnoredPath as W, isMonorepoPackage as X, isPackagesSkippedSource as Y, isRSCServerModule as Z, mangleCodeClassesSync as _, mangleHybridHazardMessage as a0, mergeThemes as a1, missingTailwindEntryMessage as a2, normalizeGlobalVarAliasesForCache as a3, parseThemeBlocks as a4, recordGlobalVarSourceFile as a5, resolveCompileSourceDirs as a6, resolveNativeCacheIdentity as a7, rollupPlugin as a8, scanCustomPropertyNames as a9, shouldEmitMissingCssFallback as aa, shouldEmitWarning as ab, shouldTrackGlobalVarSources as ac, shouldWarnMissingTailwindEntry as ad, shouldWarnUnscopedMonorepo as ae, skippedSzFilesMessage as af, unscopedMonorepoMessage as ag, vitePlugin as ah, webpackPlugin as ai, allocateMangleTokens as r, appendTailwindSourceDirective as s, assertNoRSCBoundaryViolation as t, assertNoRSCGraphViolation as u, collectMangleHybridHazards as v, computeSafelistRelPath as w, createGlobalVarMapAssetSource as x, createRSCModuleRecord as y, cssHasContentScope as z };
-export type { CssVarScanResult as C, GlobalVarScanCacheKeyInput as G, MangleHybridHazards as M, PlanGlobalVarAliasesInput as P, RewriteGlobalVarCssAliasesOptions as R, ScanGlobalVarCssOptions as S, ValidateGlobalVarAliasInputsOptions as V, GlobalVarAliasPlan as a, GlobalVarCssAliasRewriteResult as b, CreateGlobalVarAliasValidationOptionsInput as c, GlobalVarAliasValidationResult as d, CssVarDefinition as e, CssVarLocation as f, CssVarReference as g, GlobalVarAliasDiagnostic as h, GlobalVarAliasDiagnosticSeverity as i, GlobalVarAliasEntry as j, GlobalVarCodeSource as k, GlobalVarCssAssetSource as l, GlobalVarCssSource as m, GlobalVarScanCacheEntry as n, ParsedTheme as o, RSCBoundaryViolation as p, RSCModuleRecord as q };
+export { isPackagesSkippedSource as $, cssImportsTailwind as A, unplugin as B, deleteRSCModuleRecord as D, emitMissingCssFallback as E, esbuildPlugin as F, extractGlobalVarAliasesForManifest as H, fileMayContainSafelistableSz as I, findLocalImportSources as J, findRSCBoundaryViolation as K, findRSCGraphViolation as L, hasInjectableTailwindCandidate as N, hasTokens as O, hasUseClientDirective as T, hasUseServerDirective as U, isAdvisoryDiagnostic as W, isCompileSourceOptedIn as X, isHardIgnoredPath as Y, isMangleableCssId as Z, isMonorepoPackage as _, isRSCServerModule as a0, lateMangleCensusMessage as a1, mangleCodeClassesSync as a2, mangleEligibleClasses as a3, mangleHybridHazardMessage as a4, mergeThemes as a5, missingTailwindEntryMessage as a6, normalizeGlobalVarAliasesForCache as a7, parseThemeBlocks as a8, realContentHashDisabledMessage as a9, recordGlobalVarSourceFile as aa, resolveCompileSourceDirs as ab, resolveNativeCacheIdentity as ac, resolveQuietMode as ad, rollupPlugin as ae, scanCustomPropertyNames as af, shouldEmitMissingCssFallback as ag, shouldEmitWarning as ah, shouldTrackGlobalVarSources as ai, shouldWarnMissingTailwindEntry as aj, shouldWarnUnscopedMonorepo as ak, skippedSzFilesMessage as al, suppressedAdvisoryMessage as am, unscopedMonorepoMessage as an, vitePlugin as ao, watchModeMangleMessage as ap, webpackPlugin as aq, allocateMangleTokens as r, appendTailwindSourceDirective as s, assertNoRSCBoundaryViolation as t, assertNoRSCGraphViolation as u, collectMangleHybridHazards as v, computeSafelistRelPath as w, createGlobalVarMapAssetSource as x, createRSCModuleRecord as y, cssHasContentScope as z };
+export type { CssVarScanResult as C, GlobalVarScanCacheKeyInput as G, MangleHybridHazards as M, PlanGlobalVarAliasesInput as P, QuietMode as Q, RewriteGlobalVarCssAliasesOptions as R, ScanGlobalVarCssOptions as S, ValidateGlobalVarAliasInputsOptions as V, GlobalVarAliasPlan as a, GlobalVarCssAliasRewriteResult as b, CreateGlobalVarAliasValidationOptionsInput as c, GlobalVarAliasValidationResult as d, CssVarDefinition as e, CssVarLocation as f, CssVarReference as g, GlobalVarAliasDiagnostic as h, GlobalVarAliasDiagnosticSeverity as i, GlobalVarAliasEntry as j, GlobalVarCodeSource as k, GlobalVarCssAssetSource as l, GlobalVarCssSource as m, GlobalVarScanCacheEntry as n, ParsedTheme as o, RSCBoundaryViolation as p, RSCModuleRecord as q };