feat(rspeedy): add CSS sourcemap diagnostics plumbing

examples/react/src/App.css

@@ -1,6 +1,7 @@
 :root {
   background-color: #000;
   --color-text: #fff;
+  unknown-prop: unknown-value;
 }
 
 .Background {

packages/rspeedy/core/src/config/defaults.ts

@@ -30,6 +30,10 @@ export function applyDefaultRspeedyConfig(config: Config): Config {
       // from the `output.filename.bundle` field.
       filename: getFilename(config.output?.filename),
 
+      sourceMap: {
+        css: true,
+      },
+
       // inlineScripts defaults to false when chunk splitting is enabled, true otherwise
       inlineScripts: !enableChunkSplitting,
 

packages/rspeedy/core/src/config/output/source-map.ts

@@ -78,7 +78,7 @@ export interface SourceMap {
    *
    * @remarks
    *
-   * Defaults to `false`.
+   * Defaults to `true`.
    *
    * @example
    *

packages/rspeedy/core/test/config/output/source-map.test.ts

@@ -0,0 +1,63 @@
+// Copyright 2026 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+import { describe, expect, test } from 'vitest'
+
+import { createRspeedy } from '../../../src/index.js'
+
+describe('output.sourceMap', () => {
+  test('defaults css source map to true', async () => {
+    const rspeedy = await createRspeedy({
+      rspeedyConfig: {},
+    })
+
+    expect(rspeedy.getRspeedyConfig().output?.sourceMap).toEqual({
+      css: true,
+    })
+  })
+
+  test('respects output.sourceMap false', async () => {
+    const rspeedy = await createRspeedy({
+      rspeedyConfig: {
+        output: {
+          sourceMap: false,
+        },
+      },
+    })
+
+    expect(rspeedy.getRspeedyConfig().output?.sourceMap).toBe(false)
+  })
+
+  test('respects output.sourceMap.css false', async () => {
+    const rspeedy = await createRspeedy({
+      rspeedyConfig: {
+        output: {
+          sourceMap: {
+            css: false,
+          },
+        },
+      },
+    })
+
+    expect(rspeedy.getRspeedyConfig().output?.sourceMap).toEqual({
+      css: false,
+    })
+  })
+
+  test('merges css default with user js source map config', async () => {
+    const rspeedy = await createRspeedy({
+      rspeedyConfig: {
+        output: {
+          sourceMap: {
+            js: 'source-map',
+          },
+        },
+      },
+    })
+
+    expect(rspeedy.getRspeedyConfig().output?.sourceMap).toEqual({
+      css: true,
+      js: 'source-map',
+    })
+  })
+})

packages/tools/css-serializer/package.json

@@ -26,6 +26,7 @@
     "css-tree": "^3.1.0"
   },
   "devDependencies": {
+    "@jridgewell/gen-mapping": "^0.3.12",
     "@types/css-tree": "^2.3.11"
   }
 }

packages/tools/css-serializer/src/css/ast.ts

@@ -1,14 +1,15 @@
 // Copyright 2024 The Lynx Authors. All rights reserved.
 // Licensed under the Apache License Version 2.0 that can be found in the
 // LICENSE file in the root directory of this source tree.
-import * as CSS from '../index.js';
-import type { Plugin } from '../index.js';
+import { parse } from '../parse.js';
+import type { LynxStyleNode } from '../types/LynxStyleNode.js';
+import type { ParserError, Plugin } from '../types/Plugin.js';
 
 export function cssToAst(
   content: string,
   plugins: Plugin[],
-): [CSS.LynxStyleNode[], CSS.ParserError[]] {
-  const parsedCSS = CSS.parse(content, {
+): [LynxStyleNode[], ParserError[]] {
+  const parsedCSS = parse(content, {
     plugins,
   });
   return [parsedCSS.root, parsedCSS.errors] as const;

packages/tools/css-serializer/src/css/cssChunksToMap.ts

@@ -1,47 +1,107 @@
 // Copyright 2024 The Lynx Authors. All rights reserved.
 // Licensed under the Apache License Version 2.0 that can be found in the
 // LICENSE file in the root directory of this source tree.
-import type * as CSS from '../index.js';
-
 import { cssToAst } from './ast.js';
 import { debundleCSS } from './debundle.js';
+import type { LynxStyleNode } from '../types/LynxStyleNode.js';
+import type { Plugin } from '../types/Plugin.js';
+
+interface CSSChunkAsset {
+  content: string;
+  sourceMap?: import('./sourceMap.js').CSSSourceMap | undefined;
+}
 
+/**
+ * Convert CSS chunks into `cssMap` / `cssSource`.
+ *
+ * `loc` fields remain in bundle CSS coordinates so they can be resolved later
+ * via `main.css.map`.
+ *
+ * `cssSource` intentionally keeps the historical `/cssId/<id>.css` shape.
+ */
 export function cssChunksToMap(
-  cssChunks: string[],
-  plugins: CSS.Plugin[],
+  cssChunks: Array<string | CSSChunkAsset>,
+  plugins: Plugin[],
   enableCSSSelector: boolean,
 ): {
-  cssMap: Record<string, CSS.LynxStyleNode[]>;
+  cssMap: Record<string, LynxStyleNode[]>;
   cssSource: Record<string, string>;
   contentMap: Map<number, string[]>;
 } {
   const cssMap = cssChunks
-    .reduce<Map<number, string[]>>((cssMap, css) => {
-      debundleCSS(css, cssMap, enableCSSSelector);
+    .reduce<Map<number, CSSChunkAsset[]>>((cssMap, cssChunk) => {
+      const normalizedCSSChunk = normalizeCSSChunk(cssChunk);
+      const debundledMap = new Map<number, string[]>();
+
+      debundleCSS(
+        normalizedCSSChunk.content,
+        debundledMap,
+        enableCSSSelector,
+        true,
+      );
+
+      debundledMap.forEach((content, cssId) => {
+        if (!cssMap.has(cssId)) {
+          cssMap.set(cssId, []);
+        }
+
+        cssMap.get(cssId)!.push(
+          ...content.map(content => ({
+            content,
+            sourceMap: normalizedCSSChunk.sourceMap,
+          })),
+        );
+      });
+
       return cssMap;
     }, new Map());
 
+  const stylesheets = Array.from(cssMap.entries()).map(
+    ([cssId, contentSegments]) => {
+      const content = contentSegments.map(({ content }) => content);
+      const [root] = cssToAst(content.join('\n'), plugins);
+
+      root.forEach(rule => {
+        if (rule.type === 'ImportRule') {
+          // For example: '/981029' -> '981029'
+          rule.href = rule.href.replace('/', '');
+        }
+      });
+
+      return {
+        cssId,
+        root,
+        cssSource: `/cssId/${cssId}.css`,
+        content,
+      };
+    },
+  );
+
+  const contentMap = Array.from(cssMap.entries()).reduce<Map<number, string[]>>(
+    (contentMap, [cssId, contentSegments]) => {
+      contentMap.set(cssId, contentSegments.map(({ content }) => content));
+      return contentMap;
+    },
+    new Map(),
+  );
+
   return {
     cssMap: Object.fromEntries(
-      Array.from(cssMap.entries()).map(([cssId, content]) => {
-        const [root] = cssToAst(content.join('\n'), plugins);
-
-        root.forEach(rule => {
-          if (rule.type === 'ImportRule') {
-            // For example: '/981029' -> '981029'
-            rule.href = rule.href.replace('/', '');
-          }
-        });
-
-        return [cssId, root];
-      }),
+      stylesheets.map(({ cssId, root }) => [cssId, root]),
     ),
     cssSource: Object.fromEntries(
-      Array.from(cssMap.keys()).map(cssId => [
-        cssId,
-        `/cssId/${cssId}.css`,
-      ]),
+      stylesheets.map(({ cssId, cssSource }) => [cssId, cssSource]),
     ),
-    contentMap: cssMap,
+    contentMap,
   };
 }
+
+function normalizeCSSChunk(cssChunk: string | CSSChunkAsset): CSSChunkAsset {
+  if (typeof cssChunk === 'string') {
+    return {
+      content: cssChunk,
+    };
+  }
+
+  return cssChunk;
+}