veryfront 0.1.26 → 0.1.28

package/src/src/transforms/css-modules/naming.ts

@@ -0,0 +1,152 @@
+/**
+ * CSS Module naming and selector rewriting helpers.
+ *
+ * Provides deterministic class-name scoping that is stable across
+ * transform/runtime boundaries and HTML CSS aggregation.
+ */
+
+const CSS_MODULE_EXTENSION = ".module.css";
+
+/**
+ * Normalize a module key to a stable slash-based format.
+ * Removes query/hash suffixes and normalizes duplicate separators.
+ */
+export function normalizeCssModuleKey(path: string): string {
+  const withoutFilePrefix = path.startsWith("file://") ? path.slice("file://".length) : path;
+  const withoutQuery = withoutFilePrefix.replace(/[?#].*$/, "");
+  const slashed = withoutQuery.replace(/\\/g, "/");
+  const collapsed = slashed.replace(/\/{2,}/g, "/");
+  if (collapsed.startsWith("/")) return collapsed;
+  if (collapsed.startsWith("http://") || collapsed.startsWith("https://")) return collapsed;
+  return `/${collapsed.replace(/^\/+/, "")}`;
+}
+
+function dirname(path: string): string {
+  const normalized = normalizeCssModuleKey(path);
+  const lastSlash = normalized.lastIndexOf("/");
+  return lastSlash <= 0 ? "/" : normalized.slice(0, lastSlash);
+}
+
+function normalizePathSegments(path: string): string {
+  const normalized = normalizeCssModuleKey(path);
+  if (normalized.startsWith("http://") || normalized.startsWith("https://")) return normalized;
+
+  const parts = normalized.split("/").filter(Boolean);
+  const resolved: string[] = [];
+
+  for (const part of parts) {
+    if (part === ".") continue;
+    if (part === "..") {
+      resolved.pop();
+      continue;
+    }
+    resolved.push(part);
+  }
+
+  return `/${resolved.join("/")}`;
+}
+
+/**
+ * Resolve a CSS import specifier to a deterministic module key.
+ * Supports relative imports, @/ aliases, absolute paths, and URLs.
+ */
+export function resolveCssModuleKey(
+  specifier: string,
+  importerFilePath: string,
+  projectDir: string,
+): string {
+  if (specifier.startsWith("http://") || specifier.startsWith("https://")) {
+    return normalizeCssModuleKey(specifier);
+  }
+
+  if (specifier.startsWith("@/")) {
+    const aliasPath = specifier.slice(2).replace(/^\/+/, "");
+    return normalizePathSegments(`${normalizeCssModuleKey(projectDir)}/${aliasPath}`);
+  }
+
+  if (specifier.startsWith("/")) {
+    return normalizePathSegments(specifier);
+  }
+
+  if (specifier.startsWith("./") || specifier.startsWith("../")) {
+    const importerDir = dirname(importerFilePath);
+    return normalizePathSegments(`${importerDir}/${specifier}`);
+  }
+
+  // Bare specifiers are uncommon for CSS in this system, but keep deterministic behavior.
+  return normalizeCssModuleKey(specifier);
+}
+
+function hashString(input: string): string {
+  let hash = 5381;
+  for (let i = 0; i < input.length; i++) {
+    hash = ((hash << 5) + hash) ^ input.charCodeAt(i);
+  }
+  return (hash >>> 0).toString(36);
+}
+
+function sanitizeToken(token: string): string {
+  return token.replace(/[^\w-]/g, "_");
+}
+
+/**
+ * Build deterministic module scope info.
+ */
+export function getCssModuleScope(moduleKey: string): { base: string; hash: string } {
+  const normalized = normalizeCssModuleKey(moduleKey);
+  const filename = normalized.split("/").pop() || "module";
+  const base = sanitizeToken(
+    filename.endsWith(CSS_MODULE_EXTENSION)
+      ? filename.slice(0, -CSS_MODULE_EXTENSION.length)
+      : filename.replace(/\.css$/, ""),
+  ) || "module";
+  const hash = hashString(normalized).slice(0, 6);
+  return { base, hash };
+}
+
+/**
+ * Convert a local class name to its scoped CSS Module class.
+ */
+export function toScopedCssModuleClass(moduleKey: string, localName: string): string {
+  const { base, hash } = getCssModuleScope(moduleKey);
+  const normalizedLocal = sanitizeToken(localName);
+  return `${base}_${normalizedLocal}__${hash}`;
+}
+
+function maskGlobalSelectors(css: string): { masked: string; restore: (input: string) => string } {
+  const segments: string[] = [];
+  const masked = css.replace(/:global\(([^()]*)\)/g, (match) => {
+    const token = `__VF_CSS_GLOBAL_${segments.length}__`;
+    segments.push(match);
+    return token;
+  });
+
+  return {
+    masked,
+    restore: (input: string) => {
+      let result = input;
+      for (const [i, segment] of segments.entries()) {
+        result = result.replaceAll(`__VF_CSS_GLOBAL_${i}__`, segment);
+      }
+      return result;
+    },
+  };
+}
+
+/**
+ * Rewrite `.module.css` selectors to deterministic scoped class names.
+ * Keeps `:global(...)` segments untouched.
+ */
+export function rewriteCssModuleContent(content: string, moduleKey: string): string {
+  const { masked, restore } = maskGlobalSelectors(content);
+  // After :global() masking, every `.identifier` in the CSS is a local class
+  // selector. No lookbehind needed — numeric decimals like `0.5em` won't
+  // match because digits aren't in [_a-zA-Z].
+  const rewritten = masked.replace(
+    /\.([_a-zA-Z][_a-zA-Z0-9-]*)/g,
+    (_match, className: string) => {
+      return `.${toScopedCssModuleClass(moduleKey, className)}`;
+    },
+  );
+  return restore(rewritten);
+}

package/src/src/transforms/esm/import-parser.ts

@@ -26,12 +26,13 @@ export interface MissingImport {
 
 export interface ParseLocalImportsResult {
   imports: LocalImport[];
+  cssImports: LocalImport[];
   crossProjectImports: CrossProjectImport[];
   missing: MissingImport[];
 }
 
 const EXTENSIONS = [".tsx", ".ts", ".jsx", ".js", ".mdx"];
-const HAS_EXTENSION_RE = /\.(tsx?|jsx?|mjs|cjs|mdx)$/;
+const HAS_EXTENSION_RE = /\.(tsx?|jsx?|mjs|cjs|mdx|css)$/;
 
 export async function parseLocalImports(
   code: string,
@@ -40,7 +41,7 @@ export async function parseLocalImports(
   adapter?: RuntimeAdapter,
 ): Promise<ParseLocalImportsResult> {
   if (filePath.endsWith(".css") || filePath.endsWith(".json")) {
-    return { imports: [], crossProjectImports: [], missing: [] };
+    return { imports: [], cssImports: [], crossProjectImports: [], missing: [] };
   }
 
   const esbuild = await getEsbuild();
@@ -58,6 +59,7 @@ export async function parseLocalImports(
 
   const imports = await parseImports(result.code);
   const localImports: LocalImport[] = [];
+  const cssImports: LocalImport[] = [];
   const crossProjectImports: CrossProjectImport[] = [];
   const missingImports: MissingImport[] = [];
 
@@ -68,7 +70,11 @@ export async function parseLocalImports(
     if (specifier.startsWith("./") || specifier.startsWith("../")) {
       const resolved = await resolveLocalImportPath(filePath, specifier, adapter);
       if (resolved) {
-        localImports.push({ specifier, absolutePath: resolved });
+        if (resolved.endsWith(".css")) {
+          cssImports.push({ specifier, absolutePath: resolved });
+        } else {
+          localImports.push({ specifier, absolutePath: resolved });
+        }
         continue;
       }
 
@@ -84,7 +90,11 @@ export async function parseLocalImports(
       const aliasPath = specifier.slice(2);
       const resolved = await resolveAliasImportPath(aliasPath, projectDir, adapter);
       if (resolved) {
-        localImports.push({ specifier, absolutePath: resolved });
+        if (resolved.endsWith(".css")) {
+          cssImports.push({ specifier, absolutePath: resolved });
+        } else {
+          localImports.push({ specifier, absolutePath: resolved });
+        }
         continue;
       }
 
@@ -109,7 +119,7 @@ export async function parseLocalImports(
     });
   }
 
-  return { imports: localImports, crossProjectImports, missing: missingImports };
+  return { imports: localImports, cssImports, crossProjectImports, missing: missingImports };
 }
 
 async function checkFileExists(path: string, adapter?: RuntimeAdapter): Promise<boolean> {

package/src/src/transforms/pipeline/index.ts

@@ -22,6 +22,7 @@ import type {
 } from "./types.js";
 import {
   compilePlugin,
+  cssStripPlugin,
   finalizePlugin,
   parsePlugin,
   resolveImportsPlugin,
@@ -39,6 +40,7 @@ import { extractFrameworkBundlePaths } from "../shared/framework-bundle-paths.js
 const SSR_PIPELINE: TransformPlugin[] = [
   parsePlugin,
   compilePlugin,
+  cssStripPlugin, // Strip CSS imports before they hit import resolution
   resolveImportsPlugin, // Unified import resolution
   ssrVfModulesPlugin, // Resolve /_vf_modules/ to framework files with React transforms
   ssrHttpStubPlugin,
@@ -49,6 +51,7 @@ const SSR_PIPELINE: TransformPlugin[] = [
 const BROWSER_PIPELINE: TransformPlugin[] = [
   parsePlugin,
   compilePlugin,
+  cssStripPlugin, // Strip CSS imports before they hit import resolution
   resolveImportsPlugin, // Unified import resolution
   finalizePlugin,
 ];

package/src/src/transforms/pipeline/stages/index.ts

@@ -6,6 +6,7 @@
 
 export { parsePlugin } from "./parse.js";
 export { compilePlugin } from "./compile.js";
+export { cssStripPlugin } from "./ssr-css-strip.js";
 export { resolveImportsPlugin } from "./resolve-imports.js";
 export { ssrVfModulesPlugin } from "./ssr-vf-modules.js";
 export { ssrHttpStubPlugin } from "./ssr-http-stub.js";

package/src/src/transforms/pipeline/stages/ssr-css-strip.ts

@@ -0,0 +1,201 @@
+/**
+ * CSS Strip Stage - removes CSS import statements from compiled code.
+ *
+ * CSS files are not valid JS modules and will crash both the SSR module
+ * loader and browser module system if left in compiled code. This plugin
+ * strips them and records the CSS specifiers in pipeline metadata for
+ * downstream collection (used by the SSR rendering pipeline to include
+ * the CSS content in the HTML output).
+ *
+ * For CSS Module imports (`import styles from "./X.module.css"`), the
+ * import is replaced with a Proxy stub that returns the property name
+ * as the class name. This matches the Next.js convention where
+ * `styles.container` → `"container"` (identity mapping), which works
+ * correctly with Tailwind CSS class-based styling.
+ */
+
+import type { TransformPlugin } from "../types.js";
+import { TransformStage } from "../types.js";
+import { parseImports, rewriteImports } from "../../esm/lexer.js";
+import {
+  getCssModuleScope,
+  resolveCssModuleKey,
+  toScopedCssModuleClass,
+} from "../../css-modules/naming.js";
+
+function isCSSImport(specifier: string | undefined): boolean {
+  return specifier?.endsWith(".css") || false;
+}
+
+function isCssModuleImport(specifier: string | undefined): boolean {
+  return specifier?.endsWith(".module.css") || false;
+}
+
+function cssModuleProxyExpression(): string {
+  return "new Proxy({}, { get: (_, p) => String(p) })";
+}
+
+function scopedCssModuleProxyExpression(moduleKey: string): string {
+  const scope = getCssModuleScope(moduleKey);
+  return `new Proxy({}, { get: (_, p) => typeof p === "string" ? "${scope.base}_" + String(p).replace(/[^\\w-]/g, "_") + "__${scope.hash}" : "" })`;
+}
+
+type NamedImportBinding = { imported: string; local: string };
+
+function parseNamedImportBindings(namedClause: string): NamedImportBinding[] {
+  const bindings: NamedImportBinding[] = [];
+
+  for (const rawPart of namedClause.split(",")) {
+    const part = rawPart.trim();
+    if (!part) continue;
+
+    const aliasMatch = part.match(/^([_$a-zA-Z][\w$-]*)\s+as\s+([_$a-zA-Z][\w$]*)$/);
+    if (aliasMatch) {
+      const imported = aliasMatch[1];
+      const local = aliasMatch[2];
+      if (!imported || !local) continue;
+      bindings.push({ imported, local });
+      continue;
+    }
+
+    if (/^[_$a-zA-Z][\w$]*$/.test(part)) {
+      bindings.push({ imported: part, local: part });
+    }
+  }
+
+  return bindings;
+}
+
+/**
+ * Generate a replacement for a static CSS import statement.
+ *
+ * - Side-effect import: `import "./globals.css"` → comment
+ * - Default import: `import styles from "./X.module.css"` → Proxy stub
+ * - Named imports: `import { a } from "./X.css"` → null stubs
+ */
+function generateCSSStub(statement: string, specifier: string): string {
+  const trimmed = statement.trim();
+
+  // Re-export from CSS: export { default as styles } from './module.css'
+  // → strip entirely, the CSS is collected separately
+  if (/^export\s/.test(trimmed)) {
+    return `/* css re-export stripped: ${specifier} */`;
+  }
+
+  // Side-effect import: import "./globals.css"
+  if (/^import\s+['"`]/.test(trimmed)) {
+    return `/* css import: ${specifier} */`;
+  }
+
+  const fromIndex = trimmed.lastIndexOf(" from ");
+  if (fromIndex === -1) {
+    return `/* css import: ${specifier} */`;
+  }
+
+  const cssModuleKey = isCssModuleImport(specifier) ? specifier : undefined;
+  const importClause = trimmed.slice(6, fromIndex).trim(); // Skip "import "
+
+  // Default import: import styles from "./Button.module.css"
+  // → const styles = new Proxy({}, { get: (_, p) => String(p) })
+  // This makes styles.container return "container" (identity mapping)
+  if (/^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(importClause)) {
+    const expr = cssModuleKey
+      ? scopedCssModuleProxyExpression(cssModuleKey)
+      : cssModuleProxyExpression();
+    return `const ${importClause} = ${expr}; /* css module: ${specifier} */`;
+  }
+
+  // Namespace import: import * as styles from "./X.module.css"
+  const nsMatch = importClause.match(/^\*\s+as\s+([a-zA-Z_$][a-zA-Z0-9_$]*)$/);
+  if (nsMatch) {
+    const expr = cssModuleKey
+      ? scopedCssModuleProxyExpression(cssModuleKey)
+      : cssModuleProxyExpression();
+    return `const ${nsMatch[1]} = ${expr}; /* css module: ${specifier} */`;
+  }
+
+  // Named imports: import { container, header } from "./X.module.css"
+  const namedMatch = importClause.match(/^\{([^}]+)\}$/);
+  if (namedMatch?.[1]) {
+    const bindings = parseNamedImportBindings(namedMatch[1]);
+    if (bindings.length > 0) {
+      const stubs = bindings
+        .map((binding) => {
+          const value = cssModuleKey
+            ? toScopedCssModuleClass(cssModuleKey, binding.imported)
+            : binding.imported;
+          return `${binding.local} = "${value}"`;
+        })
+        .join(", ");
+      return `const ${stubs}; /* css module: ${specifier} */`;
+    }
+  }
+
+  // Mixed: import styles, { container } from "./X.module.css"
+  const mixedMatch = importClause.match(/^([a-zA-Z_$][a-zA-Z0-9_$]*)\s*,\s*\{([^}]+)\}$/);
+  if (mixedMatch?.[1] && mixedMatch[2]) {
+    const defaultName = mixedMatch[1];
+    const bindings = parseNamedImportBindings(mixedMatch[2]);
+    const namedStubs = bindings
+      .map((binding) => {
+        const value = cssModuleKey
+          ? toScopedCssModuleClass(cssModuleKey, binding.imported)
+          : binding.imported;
+        return `${binding.local} = "${value}"`;
+      })
+      .join(", ");
+    const defaultExpr = cssModuleKey
+      ? scopedCssModuleProxyExpression(cssModuleKey)
+      : cssModuleProxyExpression();
+    return namedStubs.length > 0
+      ? `const ${defaultName} = ${defaultExpr}, ${namedStubs}; /* css module: ${specifier} */`
+      : `const ${defaultName} = ${defaultExpr}; /* css module: ${specifier} */`;
+  }
+
+  return `/* css import: ${specifier} */`;
+}
+
+/**
+ * Generate a replacement for dynamic CSS imports.
+ * Keeps syntax valid in expression position (e.g. await import("./x.css")).
+ */
+function generateDynamicCSSStub(specifier: string): string {
+  if (isCssModuleImport(specifier)) {
+    return `Promise.resolve({ default: ${
+      scopedCssModuleProxyExpression(specifier)
+    } }) /* css import: ${specifier} */`;
+  }
+
+  return `Promise.resolve({}) /* css import: ${specifier} */`;
+}
+
+export const cssStripPlugin: TransformPlugin = {
+  name: "css-strip",
+  stage: TransformStage.COMPILE + 0.5, // Run after esbuild compile, before import resolution
+
+  async transform(ctx) {
+    const imports = await parseImports(ctx.code);
+
+    const hasCssImports = imports.some((imp) => isCSSImport(imp.n));
+    if (!hasCssImports) return ctx.code;
+
+    const cssSpecifiers: string[] = [];
+
+    const result = await rewriteImports(ctx.code, (imp, statement) => {
+      if (!isCSSImport(imp.n)) return null;
+      cssSpecifiers.push(imp.n!);
+      const moduleKey = isCssModuleImport(imp.n)
+        ? resolveCssModuleKey(imp.n!, ctx.filePath, ctx.projectDir)
+        : undefined;
+      const specifierForStub = moduleKey ?? imp.n!;
+      if (imp.d > -1) return generateDynamicCSSStub(specifierForStub);
+      return generateCSSStub(statement, specifierForStub);
+    });
+
+    if (cssSpecifiers.length > 0) {
+      ctx.metadata.set("cssImports", cssSpecifiers);
+    }
+
+    return result;
+  },
+};