@wular/pnext 0.0.1

package/src/compat/css/inline-css.ts

@@ -0,0 +1,73 @@
+// Inline CSS (COMPAT - `experimental.inlineCss`, prod-only).
+//
+// When the flag is on, Next inlines a route's built CSS into a `<style>` in the document instead of
+// shipping a `<link rel=stylesheet>`. This module owns the FLAG read plus the inliner (read the built
+// asset bytes, wrap in a `<style data-pnext-inline-css>` tag). The DECISION of link-vs-style at head
+// assembly is renderer territory: the renderer calls inlineCssEnabled(config) and, when true and not
+// dev, replaces each route/global stylesheet link with inlineCssTag(...).
+
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { readFileSync } from 'node:fs';
+import type { ResolvedConfig } from '../../config';
+import { getNextConfig } from '../next/config-loader';
+
+// Inlining is a DOCUMENT optimization: Next inlines a route's CSS into the HTML
+// it serves for a navigation to the URL, but a flight (`RSC: 1`) response for
+// the same route carries stylesheet references, never the CSS bytes (the
+// inline-css suite asserts the RSC payload of `/a` does NOT contain the page's
+// `font-size` rule while the HTML does). The full-route RSC responder wraps its
+// render in `withoutInlineCss`, which switches head assembly back to `<link>`.
+//
+// A scope (not a module flag) because renders are concurrent: a plain document
+// render running alongside a flight render must keep inlining.
+const INLINE_CSS_SUPPRESSED = Symbol.for('pnext.compat.inlineCssSuppressed');
+const suppressed = ((globalThis as Record<PropertyKey, unknown>)[INLINE_CSS_SUPPRESSED] ??=
+  new AsyncLocalStorage<true>()) as AsyncLocalStorage<true>;
+
+/** Run `render` with CSS inlining disabled (flight responses — see above). */
+export function withoutInlineCss<T>(render: () => T): T {
+  return suppressed.run(true, render);
+}
+
+/** True when `experimental.inlineCss` is set in next.config. */
+export function inlineCssEnabled(_config: ResolvedConfig): boolean {
+  const config = getNextConfig();
+  const experimental = config.experimental as { inlineCss?: unknown } | undefined;
+  return experimental?.inlineCss === true;
+}
+
+/**
+ * Wrap a built CSS file's bytes in an inline `<style>` tag. `nonce` (when the
+ * request carries a CSP nonce) is stamped so a strict CSP admits the style.
+ * Returns '' if the file can't be read (never fail the page over inlining).
+ */
+export function inlineCssTag(assetFile: string, nonce?: string): string {
+  const css = readCss(assetFile);
+  return css === undefined ? '' : inlineStyleTag(css, nonce);
+}
+
+function readCss(assetFile: string): string | undefined {
+  try {
+    return readFileSync(assetFile, 'utf8');
+  } catch {
+    return undefined;
+  }
+}
+
+function inlineStyleTag(css: string, nonce?: string): string {
+  const nonceAttr = nonce ? ` nonce="${nonce}"` : '';
+  return `<style data-pnext-inline-css${nonceAttr}>${css}</style>`;
+}
+
+export function inlineCssStylesheets(
+  config: ResolvedConfig,
+  options: { assetNames: string[]; dev: boolean; nonce?: string; prependCss?: string },
+): string[] | undefined {
+  if (options.dev || suppressed.getStore() === true || !inlineCssEnabled(config)) return undefined;
+  const assets = options.assetNames.map(asset =>
+    readCss(`${config.outPath}/public/assets/${asset}`),
+  );
+  if (assets.some(css => css === undefined)) return undefined;
+  const css = [options.prependCss, ...assets].filter(Boolean).join('\n');
+  return css ? [inlineStyleTag(css, options.nonce)] : [];
+}

package/src/compat/css/lightningcss.ts

@@ -0,0 +1,90 @@
+// experimental.useLightningcss / lightningCssFeatures (COMPAT).
+//
+// When next.config enables `experimental.useLightningcss`, CSS chunk sources run through the APP's own
+// `lightningcss` package (resolved from the project root - pnext ships no copy) with the
+// include/exclude feature masks from `experimental.lightningCssFeatures`. Matching Next's
+// lightningcss-loader: Nesting is always in the include mask; user `include` names add flags and user
+// `exclude` names remove them. An included feature is transpiled regardless of browser targets - that
+// forced transpilation is exactly what the suite asserts.
+//
+// Zero-cost when disabled or when the app has no lightningcss install: the source passes through.
+
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { getNextConfig } from '../next/config-loader';
+
+interface LightningModule {
+  transform(options: {
+    filename: string;
+    code: Uint8Array;
+    include?: number;
+    exclude?: number;
+    errorRecovery?: boolean;
+  }): { code: Uint8Array };
+  Features: Record<string, number>;
+}
+
+interface LightningFeaturesConfig {
+  include?: string[];
+  exclude?: string[];
+}
+
+const moduleCache = new Map<string, LightningModule | null>();
+
+function loadLightningcss(root: string): LightningModule | null {
+  const cached = moduleCache.get(root);
+  if (cached !== undefined) return cached;
+  let loaded: LightningModule | null = null;
+  try {
+    const require = createRequire(path.join(root, 'package.json'));
+    loaded = require('lightningcss') as LightningModule;
+  } catch {
+    loaded = null;
+  }
+  moduleCache.set(root, loaded);
+  return loaded;
+}
+
+/** `'light-dark'` -> `LightDark` (lightningcss `Features` enum key). */
+function featureKey(name: string): string {
+  return name.replace(/(?:^|-)([a-z0-9])/g, (_match, char: string) => char.toUpperCase());
+}
+
+function featureMask(features: Record<string, number>, names: string[] | undefined): number {
+  let mask = 0;
+  for (const name of names ?? []) mask |= features[featureKey(name)] ?? 0;
+  return mask;
+}
+
+/**
+ * Transform CSS chunk source through the app's lightningcss when
+ * `experimental.useLightningcss` is enabled; returns the source unchanged
+ * otherwise (or when lightningcss is missing / the transform fails).
+ */
+export function maybeLightningcssTransform(css: string, file: string, root: string): string {
+  const experimental = getNextConfig().experimental as
+    | { useLightningcss?: boolean; lightningCssFeatures?: LightningFeaturesConfig }
+    | undefined;
+  if (experimental?.useLightningcss !== true) return css;
+  const lightning = loadLightningcss(root);
+  if (!lightning) return css;
+
+  const features = experimental.lightningCssFeatures;
+  const userInclude = featureMask(lightning.Features, features?.include);
+  const userExclude = featureMask(lightning.Features, features?.exclude);
+  // Nesting always transpiles (Next hardcodes it), user excludes win.
+  const include = ((lightning.Features.Nesting ?? 1) | userInclude) & ~userExclude;
+
+  try {
+    const result = lightning.transform({
+      filename: file,
+      code: new TextEncoder().encode(css),
+      include,
+      exclude: userExclude,
+      errorRecovery: true,
+    });
+    return new TextDecoder().decode(result.code);
+  } catch {
+    return css;
+  }
+}

package/src/compat/css/modules.ts

@@ -0,0 +1,373 @@
+import { existsSync, lstatSync, readdirSync, readFileSync, symlinkSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import type { Plugin } from 'esbuild';
+import type { ResolvedConfig } from '../../config';
+import { resolveImport } from '../../resolve/imports';
+import { maybeLightningcssTransform } from './lightningcss';
+
+interface ComposeRef {
+  names: string[];
+  from?: string;
+}
+
+interface CssModuleInfo {
+  classes: Set<string>;
+  composes: Map<string, ComposeRef[]>;
+  dependencies: string[];
+}
+
+const pagesCompatIgnoredSourceEntries = new Set([
+  '.next',
+  '.pnext',
+  'app',
+  'node_modules',
+  'pages',
+]);
+
+export function materializeNextCssSources(config: ResolvedConfig) {
+  const generatedRoot = path.dirname(config.appPath);
+  if (path.basename(path.dirname(generatedRoot)) !== 'pnext-pages-compat') return;
+
+  for (const entry of readdirSync(config.root)) {
+    if (pagesCompatIgnoredSourceEntries.has(entry)) continue;
+    const source = path.join(config.root, entry);
+    const target = path.join(generatedRoot, entry);
+    if (existsSync(target)) continue;
+    try {
+      symlinkSync(source, target, lstatSync(source).isDirectory() ? 'dir' : 'file');
+    } catch {
+      // A concurrent materialization may have linked the same source already.
+    }
+  }
+}
+
+export function nextCssModuleChunkPlugin(config: ResolvedConfig): Plugin {
+  return {
+    name: 'pnext-compat-css-modules',
+    setup(build) {
+      build.onLoad({ filter: /\.css$/ }, ({ path: file }) => {
+        const source = nextCssSource(file, config.root);
+        const contents = file.endsWith('.module.css')
+          ? transformCssModule(readFileSync(source, 'utf8'), source, config.root)
+          : rewriteTransparentBodyChildren(readFileSync(source, 'utf8'));
+        return {
+          // No-op unless next.config enables experimental.useLightningcss.
+          contents: maybeLightningcssTransform(contents, source, config.root),
+          loader: 'css',
+          resolveDir: path.dirname(source),
+        };
+      });
+    },
+  };
+}
+
+export function nextCssResolveModule(config: ResolvedConfig) {
+  return (file: string): Record<string, string> | undefined =>
+    isCssModuleFile(file) ? cssModuleMapping(file, config.root) : undefined;
+}
+
+export function nextCssLoadModuleForClient(config: ResolvedConfig) {
+  return (file: string): string | undefined =>
+    isCssModuleFile(file)
+      ? `export default ${JSON.stringify(cssModuleMapping(file, config.root))};`
+      : undefined;
+}
+
+export function nextCssResolveDependency(config: ResolvedConfig) {
+  const requires = new Map<string, NodeJS.Require>();
+  return (_root: string, fromFile: string, specifier: string): string | undefined => {
+    if (specifier.startsWith('.') || path.isAbsolute(specifier)) return undefined;
+    const source = nextCssSource(fromFile, config.root);
+    let require = requires.get(source);
+    if (!require) {
+      require = createRequire(source);
+      requires.set(source, require);
+    }
+    try {
+      const resolved = require.resolve(specifier);
+      return isCssDependency(resolved) ? resolved : undefined;
+    } catch {
+      return undefined;
+    }
+  };
+}
+
+function isCssModuleFile(file: string) {
+  return file.endsWith('.module.css');
+}
+
+function isCssDependency(file: string) {
+  return /\.(?:css|scss|sass)$/.test(file);
+}
+
+function cssModuleMapping(file: string, root: string) {
+  file = nextCssSource(file, root);
+  const cache = new Map<string, CssModuleInfo>();
+  const info = moduleInfo(file, root, cache);
+  return Object.fromEntries(
+    [...info.classes].map(className => [
+      className,
+      classValue(file, className, root, cache, new Set()),
+    ]),
+  );
+}
+
+export function nextCssSource(file: string, root: string) {
+  const resolved = path.resolve(file);
+  const parts = resolved.split(path.sep);
+  const buildClientIndex = parts.findIndex(
+    (part, index) =>
+      part === '.pnext' && parts.slice(index + 1, index + 4).join('/') === 'cache/server/build-client',
+  );
+  if (buildClientIndex !== -1) {
+    const source = path.join(root, ...parts.slice(buildClientIndex + 4));
+    if (existsSync(source)) return source;
+  }
+  const generatedIndex = parts.lastIndexOf('pnext-pages-compat');
+  const relative = generatedIndex === -1 ? undefined : parts.slice(generatedIndex + 2);
+  if (relative?.length) {
+    const source = path.join(
+      root,
+      ...(relative[0] === 'source-app'
+        ? ['app', ...relative.slice(1)]
+        : relative[0] === 'source-pages'
+          ? ['pages', ...relative.slice(1)]
+          : relative),
+    );
+    if (existsSync(source)) return source;
+  }
+
+  return resolved;
+}
+
+function rewriteTransparentBodyChildren(source: string) {
+  return source.replace(
+    /body\s*>\s*(-?[_a-zA-Z][\w-]*)/g,
+    (_, element: string) =>
+      `:is(body>${element},body :where(pnext-layout,#pnext-page)>${element})`,
+  );
+}
+
+function transformCssModule(source: string, file: string, root: string) {
+  const info = moduleInfoFromSource(source, file, root);
+  const imports = info.dependencies.map(dep => `@import ${JSON.stringify(dep)};`).join('\n');
+  const css = scopeKeyframes(rewriteModuleSelectors(stripComposes(source), file), file);
+  return [imports, css].filter(Boolean).join('\n');
+}
+
+function moduleInfo(
+  file: string,
+  root: string,
+  cache: Map<string, CssModuleInfo>,
+): CssModuleInfo {
+  const key = path.resolve(file);
+  const cached = cache.get(key);
+  if (cached) return cached;
+  const info = moduleInfoFromSource(readFileSync(key, 'utf8'), key, root);
+  cache.set(key, info);
+  return info;
+}
+
+function moduleInfoFromSource(source: string, file: string, root: string): CssModuleInfo {
+  const classes = cssClassNames(source);
+  const composes = new Map<string, ComposeRef[]>();
+  const dependencies: string[] = [];
+  const seenDependencies = new Set<string>();
+  const rulePattern = /(^|})([^{}]+)\{([^{}]*)\}/g;
+  let match: RegExpExecArray | null;
+
+  while ((match = rulePattern.exec(source))) {
+    const [, , selector, body] = match;
+    if (!selector || !body) continue;
+    const localClasses = selectorClassNames(selector).filter(className => classes.has(className));
+    if (localClasses.length === 0) continue;
+
+    for (const ref of composeRefs(body)) {
+      for (const localClass of localClasses) {
+        const refs = composes.get(localClass) ?? [];
+        refs.push(ref);
+        composes.set(localClass, refs);
+      }
+      if (!ref.from || ref.from === 'global') continue;
+      const dependency = resolveCssModuleImport(root, file, ref.from);
+      if (!dependency || seenDependencies.has(dependency)) continue;
+      dependencies.push(dependency);
+      seenDependencies.add(dependency);
+    }
+  }
+
+  return { classes, composes, dependencies };
+}
+
+function classValue(
+  file: string,
+  className: string,
+  root: string,
+  cache: Map<string, CssModuleInfo>,
+  stack: Set<string>,
+): string {
+  const key = `${path.resolve(file)}\0${className}`;
+  if (stack.has(key)) return cssModuleClassName(file, className);
+  stack.add(key);
+
+  const info = moduleInfo(file, root, cache);
+  const parts = [cssModuleClassName(file, className)];
+  for (const ref of info.composes.get(className) ?? []) {
+    if (ref.from === 'global') {
+      parts.push(...ref.names);
+      continue;
+    }
+    const refFile = ref.from ? resolveCssModuleImport(root, file, ref.from) : file;
+    if (!refFile) continue;
+    const refInfo = moduleInfo(refFile, root, cache);
+    for (const name of ref.names) {
+      if (!refInfo.classes.has(name)) continue;
+      parts.push(...classValue(refFile, name, root, cache, stack).split(/\s+/));
+    }
+  }
+
+  stack.delete(key);
+  return [...new Set(parts)].join(' ');
+}
+
+function composeRefs(body: string): ComposeRef[] {
+  const refs: ComposeRef[] = [];
+  const pattern = /\bcomposes\s*:\s*([^;]+);/g;
+  let match: RegExpExecArray | null;
+
+  while ((match = pattern.exec(body))) {
+    const value = match[1]?.trim();
+    if (!value) continue;
+    const fromMatch = /^(.+?)\s+from\s+(['"]?)([^'"]+)\2$/.exec(value);
+    const names = (fromMatch?.[1] ?? value).split(/\s+/).filter(Boolean);
+    if (names.length === 0) continue;
+    refs.push({ names, ...(fromMatch?.[3] ? { from: fromMatch[3] } : {}) });
+  }
+
+  return refs;
+}
+
+function resolveCssModuleImport(root: string, fromFile: string, specifier: string) {
+  const resolved = resolveImport(root, fromFile, specifier);
+  if (resolved && isCssModuleFile(resolved)) return path.resolve(resolved);
+  if (specifier.startsWith('.') || path.isAbsolute(specifier)) return undefined;
+
+  const sibling = path.resolve(path.dirname(fromFile), specifier);
+  return existsSync(sibling) && isCssModuleFile(sibling) ? sibling : undefined;
+}
+
+function stripComposes(source: string) {
+  return source.replace(/\s*composes\s*:[^;{}]+;/g, '');
+}
+
+function cssClassNames(source: string) {
+  return new Set(selectorClassNames(source.replace(/\{[^{}]*\}/g, '{')));
+}
+
+function selectorClassNames(selector: string) {
+  const classes: string[] = [];
+  const pattern = /(^|[\s,>+~])\.(-?[_a-zA-Z][\w-]*)/g;
+  let match: RegExpExecArray | null;
+  while ((match = pattern.exec(selector))) {
+    if (match[2]) classes.push(match[2]);
+  }
+  return classes;
+}
+
+function rewriteModuleSelectors(css: string, file: string) {
+  // A selector is any brace/semicolon-free run ending at a brace - which also covers NESTED rule
+  // openings (postcss-nested / native CSS nesting and rules inside `@media`), whose selectors follow a
+  // brace or a declaration's semicolon. A prior version anchored on (^|}) and left nested class
+  // selectors unhashed while the JS mapping handed out the hashed name.
+  //
+  // Scanned by hand rather than with a regex: on a stylesheet whose tail holds no brace, the obvious
+  // pattern re-consumes the whole tail from every offset and backtracks it away again, which is
+  // quadratic and can cost minutes of build time on a large module.
+  let out = '';
+  let runStart = 0;
+  for (let index = 0; index < css.length; index++) {
+    const char = css[index];
+    if (char === '{') {
+      out += `${rewriteSelectorRun(css.slice(runStart, index), file)}{`;
+      runStart = index + 1;
+    } else if (char === '}' || char === ';') {
+      out += css.slice(runStart, index + 1);
+      runStart = index + 1;
+    }
+  }
+  return out + css.slice(runStart);
+}
+
+function rewriteSelectorRun(selector: string, file: string) {
+  if (selector.trimStart().startsWith('@')) return selector;
+  let out = selector;
+  for (const className of selectorClassNames(selector)) {
+    out = rewriteClassSelector(out, cssModuleClassName(file, className), className);
+  }
+  return out.replace(/:global\(((?:[^()]|\([^()]*\))*)\)/g, '$1');
+}
+
+function scopeKeyframes(css: string, file: string) {
+  let out = css;
+  for (const name of keyframeNames(css)) {
+    const scoped = cssModuleClassName(file, name);
+    out = out.replace(
+      new RegExp(`(@(?:-webkit-)?keyframes\\s+)${escapeRegex(name)}(?![-_a-zA-Z0-9])`, 'g'),
+      `$1${scoped}`,
+    );
+    out = out.replace(
+      new RegExp(
+        `(animation-name\\s*:\\s*)${escapeRegex(name)}(?![-_a-zA-Z0-9])`,
+        'g',
+      ),
+      `$1${scoped}`,
+    );
+    out = out.replace(
+      new RegExp(
+        `(animation\\s*:[^;{}]*?(?<![-_a-zA-Z0-9]))${escapeRegex(name)}(?![-_a-zA-Z0-9])`,
+        'g',
+      ),
+      `$1${scoped}`,
+    );
+  }
+  return out;
+}
+
+function keyframeNames(css: string) {
+  const names = new Set<string>();
+  const pattern = /@(?:-webkit-)?keyframes\s+(-?[_a-zA-Z][\w-]*)/g;
+  let match: RegExpExecArray | null;
+  while ((match = pattern.exec(css))) {
+    if (match[1]) names.add(match[1]);
+  }
+  return names;
+}
+
+function cssModuleClassName(file: string, className: string) {
+  const base = path.basename(file).replace(/\.module\.css$/, '').replace(/[^_a-zA-Z0-9]/g, '_');
+  const hash = pathHash(cssModuleScopePath(file));
+  return `${base}_${className}_${hash}`;
+}
+
+function cssModuleScopePath(file: string) {
+  const normalized = file.split(path.sep).join('/');
+  const appIndex = normalized.lastIndexOf('/app/');
+  if (appIndex !== -1) return normalized.slice(appIndex + 1);
+  return normalized.split('/').slice(-3).join('/');
+}
+
+function rewriteClassSelector(css: string, scopedClassName: string, originalClassName: string) {
+  const pattern = new RegExp(`\\.${escapeRegex(originalClassName)}(?![-_a-zA-Z0-9])`, 'g');
+  return css.replace(pattern, `.${scopedClassName}`);
+}
+
+function pathHash(file: string) {
+  let hash = 5381;
+  for (const char of file) hash = ((hash << 5) + hash) ^ char.charCodeAt(0);
+  return (hash >>> 0).toString(36).slice(0, 5);
+}
+
+function escapeRegex(value: string) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/src/compat/css/nonce.ts

@@ -0,0 +1,30 @@
+// CSP nonce extraction (COMPAT).
+//
+// Next reads a `nonce-<value>` token out of the request's Content-Security-Policy header and stamps it
+// onto the script / style / preload tags it emits so a strict CSP admits them. This module owns the
+// EXTRACTION, parsing the header exactly as Next does; the actual stamping onto the emitted tags is
+// renderer territory.
+//
+// Matches Next's parser: scan every directive's sources for a single-quoted `'nonce-<base64>'` token
+// and return the first one found.
+
+/** Extract the CSP nonce from a Content-Security-Policy header value, if any. */
+export function nonceFromCsp(csp: string | null | undefined): string | undefined {
+  if (!csp) return undefined;
+  // A directive looks like `script-src 'self' 'nonce-abc123=='`. Sources are
+  // whitespace-separated; the nonce token is single-quoted `'nonce-<value>'`.
+  const directives = csp.split(';');
+  for (const directive of directives) {
+    for (const token of directive.trim().split(/\s+/)) {
+      const match = /^'nonce-([^']+)'$/.exec(token);
+      if (match?.[1]) return match[1];
+    }
+  }
+  return undefined;
+}
+
+/** Extract the CSP nonce from a request's headers. */
+export function nonceFromRequest(request: Request | undefined): string | undefined {
+  if (!request) return undefined;
+  return nonceFromCsp(request.headers.get('content-security-policy'));
+}

package/src/compat/css/sass-plugin.ts

@@ -0,0 +1,65 @@
+// Sass esbuild plugin + CSS-module resolvers (COMPAT).
+//
+// The concrete CssExtensions implementations wired by register-css-extras.ts:
+//   - sassChunkPlugin(config): an esbuild onLoad for `.scss`/`.sass` used in the CSS-chunk builds.
+//     Compiles to css text; a `*.module.*` file's selectors are already scoped by compileSassCss.
+//   - sassResolveCssModule / sassLoadCssModuleForClient: the class-map resolvers for the Bun
+//     render-time loader and the client bundle.
+//
+// includePaths come from next.config `sassOptions.includePaths`. All fields degrade to core's empty
+// behavior when `sass` is not installed.
+
+import type { Plugin } from 'esbuild';
+import type { ResolvedConfig } from '../../config';
+import { getNextConfig } from '../next/config-loader';
+import {
+  compileSassCss,
+  isSassFile,
+  isSassModuleFile,
+  sassModuleMapping,
+} from './sass';
+
+/** Read `sassOptions.includePaths` from the loaded next.config. */
+function sassIncludePaths(): string[] {
+  const config = getNextConfig();
+  const sassOptions = config.sassOptions as { includePaths?: unknown } | undefined;
+  const includePaths = sassOptions?.includePaths;
+  return Array.isArray(includePaths) ? includePaths.filter((p): p is string => typeof p === 'string') : [];
+}
+
+/**
+ * esbuild plugin: compile `.scss`/`.sass` to css inside the CSS-chunk build.
+ * Returns `loader: 'css'` so esbuild's CSS bundler concatenates the result in
+ * import order alongside the `@import`-ed `.css`.
+ */
+export function sassChunkPlugin(config: ResolvedConfig): Plugin {
+  return {
+    name: 'pnext-compat-sass',
+    setup(build) {
+      build.onLoad({ filter: /\.(?:scss|sass)$/ }, ({ path: file }) => ({
+        contents: compileSassCss(file, config.root, sassIncludePaths()),
+        loader: 'css',
+      }));
+    },
+  };
+}
+
+/** Bun render-time loader / class-map resolver for `*.module.{scss,sass}`. */
+export function sassResolveCssModule(config: ResolvedConfig) {
+  return (file: string): Record<string, string> | undefined =>
+    isSassModuleFile(file) ? sassModuleMapping(file, config.root, sassIncludePaths()) : undefined;
+}
+
+/** Client-bundle ESM text for a `.scss`/`.sass` import. */
+export function sassLoadCssModuleForClient(config: ResolvedConfig) {
+  return (file: string): string | undefined => {
+    if (!isSassFile(file)) return undefined;
+    if (isSassModuleFile(file)) {
+      const map = sassModuleMapping(file, config.root, sassIncludePaths());
+      return `export default ${JSON.stringify(map)};`;
+    }
+    // Global (non-module) sass carries no class map; the css bytes ship via the
+    // CSS chunk, so the client import is a side-effect-only empty module.
+    return 'export default undefined;';
+  };
+}