pulse-js-framework 1.7.31 → 1.7.32

package/cli/build.js

@@ -7,9 +7,13 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSync, copyFileSync } from 'fs';
 import { join, extname, relative, dirname } from 'path';
 import { compile } from '../compiler/index.js';
+import { preprocessStylesSync, isSassAvailable, getSassVersion } from '../compiler/preprocessor.js';
 import { log } from './logger.js';
 import { createTimer, createProgressBar, formatDuration, createSpinner } from './utils/cli-ui.js';
 
+// SASS availability (checked once at build start)
+let sassAvailable = false;
+
 /**
  * Build project for production
  */
@@ -34,6 +38,13 @@ export async function buildProject(args) {
 
   log.info('Building with Pulse compiler...\n');
 
+  // Check for SASS availability
+  sassAvailable = isSassAvailable();
+  if (sassAvailable) {
+    const version = getSassVersion();
+    log.info(`  SASS support enabled (sass ${version || 'unknown'})`);
+  }
+
   // Create output directory
   if (!existsSync(outDir)) {
     mkdirSync(outDir, { recursive: true });
@@ -140,8 +151,30 @@ function processDirectory(srcDir, outDir, progress = null) {
       });
 
       if (result.success) {
+        let code = result.code;
+
+        // Preprocess SASS/SCSS in style blocks if sass is available
+        if (sassAvailable) {
+          const stylesMatch = code.match(/const styles = `([\s\S]*?)`;/);
+          if (stylesMatch) {
+            try {
+              const preprocessed = preprocessStylesSync(stylesMatch[1], {
+                filename: srcPath,
+                loadPaths: [dirname(srcPath)],
+                compressed: true
+              });
+
+              if (preprocessed.wasSass) {
+                code = code.replace(stylesMatch[0], `const styles = \`${preprocessed.css}\`;`);
+              }
+            } catch (sassError) {
+              log.warn(`  SASS warning in ${file}: ${sassError.message}`);
+            }
+          }
+        }
+
         const outPath = join(outDir, file.replace('.pulse', '.js'));
-        writeFileSync(outPath, result.code);
+        writeFileSync(outPath, code);
       } else {
         log.error(`  Error compiling ${file}:`);
         for (const error of result.errors) {

package/cli/dev.js

@@ -6,10 +6,14 @@
 
 import { createServer } from 'http';
 import { readFileSync, existsSync, statSync, watch } from 'fs';
-import { join, extname, resolve } from 'path';
+import { join, extname, resolve, dirname } from 'path';
 import { compile } from '../compiler/index.js';
+import { preprocessStylesSync, isSassAvailable, getSassVersion } from '../compiler/preprocessor.js';
 import { log } from './logger.js';
 
+// SASS availability (checked once at server start)
+let sassAvailable = false;
+
 const MIME_TYPES = {
   '.html': 'text/html',
   '.js': 'application/javascript',
@@ -87,6 +91,13 @@ export async function startDevServer(args) {
     // Vite not available, use built-in server
   }
 
+  // Check for SASS availability
+  sassAvailable = isSassAvailable();
+  if (sassAvailable) {
+    const version = getSassVersion();
+    log.info(`SASS support enabled (sass ${version || 'unknown'})`);
+  }
+
   // Built-in development server
   const server = createServer(async (req, res) => {
     const url = new URL(req.url, `http://localhost:${port}`);
@@ -128,11 +139,31 @@ export async function startDevServer(args) {
           });
 
           if (result.success) {
+            let code = result.code;
+
+            // Preprocess SASS/SCSS if available
+            if (sassAvailable) {
+              const stylesMatch = code.match(/const styles = `([\s\S]*?)`;/);
+              if (stylesMatch) {
+                try {
+                  const preprocessed = preprocessStylesSync(stylesMatch[1], {
+                    filename: filePath,
+                    loadPaths: [dirname(filePath)]
+                  });
+                  if (preprocessed.wasSass) {
+                    code = code.replace(stylesMatch[0], `const styles = \`${preprocessed.css}\`;`);
+                  }
+                } catch (sassError) {
+                  console.warn(`[Pulse] SASS warning: ${sassError.message}`);
+                }
+              }
+            }
+
             res.writeHead(200, {
               'Content-Type': 'application/javascript',
               'Cache-Control': 'no-cache, no-store, must-revalidate'
             });
-            res.end(result.code);
+            res.end(code);
           } else {
             const errorDetails = result.errors.map(e => `${e.message} at line ${e.line || '?'}:${e.column || '?'}`).join('\n');
             console.error(`[Pulse] Compilation error in ${filePath}:`, result.errors);
@@ -173,11 +204,31 @@ export async function startDevServer(args) {
           });
 
           if (result.success) {
+            let code = result.code;
+
+            // Preprocess SASS/SCSS if available
+            if (sassAvailable) {
+              const stylesMatch = code.match(/const styles = `([\s\S]*?)`;/);
+              if (stylesMatch) {
+                try {
+                  const preprocessed = preprocessStylesSync(stylesMatch[1], {
+                    filename: pulseFilePath,
+                    loadPaths: [dirname(pulseFilePath)]
+                  });
+                  if (preprocessed.wasSass) {
+                    code = code.replace(stylesMatch[0], `const styles = \`${preprocessed.css}\`;`);
+                  }
+                } catch (sassError) {
+                  console.warn(`[Pulse] SASS warning: ${sassError.message}`);
+                }
+              }
+            }
+
             res.writeHead(200, {
               'Content-Type': 'application/javascript',
               'Cache-Control': 'no-cache, no-store, must-revalidate'
             });
-            res.end(result.code);
+            res.end(code);
           } else {
             res.writeHead(500, { 'Content-Type': 'text/plain' });
             res.end(`Compilation error: ${result.errors.map(e => e.message).join('\n')}`);

package/compiler/preprocessor.js

@@ -0,0 +1,819 @@
+/**
+ * CSS Preprocessor Support
+ *
+ * Provides optional SASS/SCSS, LESS, and Stylus support without requiring them as direct dependencies.
+ * If the user has `sass`, `less`, or `stylus` installed in their project, they will be automatically detected
+ * and used to compile SCSS/LESS/Stylus syntax in style blocks.
+ *
+ * @module pulse-js-framework/compiler/preprocessor
+ */
+
+import { createRequire } from 'module';
+
+// Cache for the sass module (null = not checked, false = not available, object = sass module)
+let sassModule = null;
+
+// Cache for the less module (null = not checked, false = not available, object = less module)
+let lessModule = null;
+
+// Cache for the stylus module (null = not checked, false = not available, object = stylus module)
+let stylusModule = null;
+
+/**
+ * Patterns that indicate SASS/SCSS syntax
+ */
+const SASS_PATTERNS = [
+  /\$[\w-]+\s*:/,           // Variables: $primary-color:
+  /@mixin\s+[\w-]+/,        // Mixins: @mixin button-styles
+  /@include\s+[\w-]+/,      // Include: @include button-styles
+  /@extend\s+[.%][\w-]+/,   // Extend: @extend .class or @extend %placeholder
+  /@function\s+[\w-]+/,     // Functions: @function calculate
+  /@use\s+['"][^'"]+['"]/,  // Use: @use 'module'
+  /@forward\s+['"][^'"]+['"]/, // Forward: @forward 'module'
+  /%[\w-]+\s*\{/,           // Placeholder selectors: %button { }
+  /#\{.*\}/,                // Interpolation: #{$variable}
+  /@if\s+/,                 // Control: @if
+  /@else\s*/,               // Control: @else
+  /@for\s+\$/,              // Loop: @for $i
+  /@each\s+\$/,             // Loop: @each $item
+  /@while\s+/,              // Loop: @while
+  /@debug\s+/,              // Debug: @debug
+  /@warn\s+/,               // Warn: @warn
+  /@error\s+/,              // Error: @error
+];
+
+/**
+ * Patterns that indicate LESS syntax
+ */
+const LESS_PATTERNS = [
+  /@[\w-]+\s*:/,            // Variables: @primary-color:
+  /\.[\w-]+\s*\([^)]*\)\s*\{/, // Mixins: .button-styles() { }
+  /\.[\w-]+\s*>\s*\([^)]*\)\s*\{/, // Parametric mixins: .button-styles > () { }
+  /\.[\w-]+\([^)]*\);/,     // Mixin calls: .button-styles();
+  /&:extend\(/,             // Extend: &:extend(.class)
+  /@\{[\w-]+\}/,            // Interpolation: @{variable}
+  /when\s*\(/,              // Guards: when (@a > 0)
+  /\.[\w-]+\(\)\s*when/,    // Guarded mixins
+  /@import\s+\(.*\)\s+['"]/, // Import options: @import (less) "file"
+  /@plugin\s+['"][^'"]+['"]/, // Plugin: @plugin "plugin-name"
+];
+
+/**
+ * Patterns that indicate Stylus syntax
+ */
+const STYLUS_PATTERNS = [
+  /^[\w-]+\s*=/m,           // Variables without $ or @: primary-color = #333
+  /^\s*[\w-]+\([^)]*\)$/m,  // Mixins without braces: button-style()
+  /^\s*[\w-]+$/m,           // Mixin calls without parens or semicolon
+  /\{\s*\$[\w-]+\s*\}/,     // Interpolation: {$variable}
+  /^\s*if\s+/m,             // Conditionals: if condition
+  /^\s*unless\s+/m,         // Unless: unless condition
+  /^\s*for\s+[\w-]+\s+in\s+/m, // Loops: for item in items
+  /^\s*@css\s+\{/m,         // Literal CSS blocks: @css { }
+  /^\s*@extends?\s+/m,      // Extend: @extend or @extends
+  /^\s*\+[\w-]+/m,          // Mixin calls with +: +button-style
+  /arguments/,              // Stylus arguments variable
+  /^[\w-]+\s*\?=/m,         // Conditional assignment: var ?= value
+];
+
+/**
+ * Patterns that indicate EITHER SASS or LESS syntax
+ * These are shared between both preprocessors
+ */
+const SHARED_PATTERNS = [
+  /&\s*\{/,                 // Parent selector nesting
+  /&:[\w-]+/,               // Parent pseudo-class: &:hover
+  /&\.[\w-]+/,              // Parent class: &.active
+];
+
+/**
+ * Check if CSS contains exclusively SASS/SCSS-specific syntax
+ * (excludes shared patterns that could be LESS or Stylus)
+ * @param {string} css - CSS string to check
+ * @returns {boolean} True if SASS syntax is detected
+ */
+function hasSassSpecificSyntax(css) {
+  return SASS_PATTERNS.some(pattern => pattern.test(css));
+}
+
+/**
+ * Check if CSS contains exclusively LESS-specific syntax
+ * (excludes shared patterns that could be SASS or Stylus)
+ * @param {string} css - CSS string to check
+ * @returns {boolean} True if LESS syntax is detected
+ */
+function hasLessSpecificSyntax(css) {
+  return LESS_PATTERNS.some(pattern => pattern.test(css));
+}
+
+/**
+ * Check if CSS contains exclusively Stylus-specific syntax
+ * @param {string} css - CSS string to check
+ * @returns {boolean} True if Stylus syntax is detected
+ */
+function hasStylusSpecificSyntax(css) {
+  return STYLUS_PATTERNS.some(pattern => pattern.test(css));
+}
+
+/**
+ * Check if CSS contains SASS/SCSS-specific syntax
+ * @param {string} css - CSS string to check
+ * @returns {boolean} True if SASS syntax is detected
+ */
+export function hasSassSyntax(css) {
+  return hasSassSpecificSyntax(css);
+}
+
+/**
+ * Check if CSS contains LESS-specific syntax
+ * @param {string} css - CSS string to check
+ * @returns {boolean} True if LESS syntax is detected
+ */
+export function hasLessSyntax(css) {
+  return hasLessSpecificSyntax(css);
+}
+
+/**
+ * Check if CSS contains Stylus-specific syntax
+ * @param {string} css - CSS string to check
+ * @returns {boolean} True if Stylus syntax is detected
+ */
+export function hasStylusSyntax(css) {
+  return hasStylusSpecificSyntax(css);
+}
+
+/**
+ * Detect which preprocessor the CSS is using
+ * @param {string} css - CSS string to check
+ * @returns {'sass'|'less'|'stylus'|'none'} Detected preprocessor
+ */
+export function detectPreprocessor(css) {
+  const hasSass = hasSassSpecificSyntax(css);
+  const hasLess = hasLessSpecificSyntax(css);
+  const hasStylus = hasStylusSpecificSyntax(css);
+
+  // Priority order: SASS > LESS > Stylus (based on popularity)
+  if (hasSass) return 'sass';
+  if (hasLess) return 'less';
+  if (hasStylus) return 'stylus';
+
+  return 'none';
+}
+
+/**
+ * Try to load the sass module from the user's project (sync version)
+ * Uses require() for compatibility with sync contexts
+ * @returns {object|false} The sass module or false if not available
+ */
+export function tryLoadSassSync() {
+  // Return cached result if already checked
+  if (sassModule !== null) {
+    return sassModule;
+  }
+
+  try {
+    // Use createRequire to load sass synchronously from the user's project
+    const require = createRequire(import.meta.url);
+    sassModule = require('sass');
+    return sassModule;
+  } catch {
+    // sass not installed in user's project
+    sassModule = false;
+    return false;
+  }
+}
+
+/**
+ * Try to load the sass module from the user's project (async version)
+ * @returns {Promise<object|false>} The sass module or false if not available
+ */
+export async function tryLoadSass() {
+  // Return cached result if already checked
+  if (sassModule !== null) {
+    return sassModule;
+  }
+
+  try {
+    // Try to import sass from the user's project
+    sassModule = await import('sass');
+    return sassModule;
+  } catch {
+    // Fall back to sync require
+    return tryLoadSassSync();
+  }
+}
+
+/**
+ * Compile SASS/SCSS to CSS (sync version)
+ * @param {string} scss - SCSS source code
+ * @param {object} options - Compilation options
+ * @param {string} [options.filename] - Source filename for error messages
+ * @param {string[]} [options.loadPaths] - Paths to search for @use/@import
+ * @param {boolean} [options.sourceMap] - Generate source map
+ * @param {boolean} [options.compressed] - Compress output
+ * @returns {{css: string, sourceMap?: object}|null} Compiled CSS or null if sass unavailable
+ */
+export function compileSassSync(scss, options = {}) {
+  const sass = tryLoadSassSync();
+
+  if (!sass) {
+    return null;
+  }
+
+  try {
+    const result = sass.compileString(scss, {
+      syntax: 'scss',
+      loadPaths: options.loadPaths || [],
+      sourceMap: options.sourceMap || false,
+      sourceMapIncludeSources: true,
+      style: options.compressed ? 'compressed' : 'expanded',
+      // Silence deprecation warnings for @import
+      silenceDeprecations: ['import'],
+    });
+
+    return {
+      css: result.css,
+      sourceMap: result.sourceMap || null
+    };
+  } catch (error) {
+    // Re-throw with better context
+    const sassError = new Error(`SASS compilation error: ${error.message}`);
+    sassError.line = error.span?.start?.line;
+    sassError.column = error.span?.start?.column;
+    sassError.file = options.filename;
+    sassError.cause = error;
+    throw sassError;
+  }
+}
+
+/**
+ * Compile SASS/SCSS to CSS (async version)
+ * @param {string} scss - SCSS source code
+ * @param {object} options - Compilation options
+ * @returns {Promise<{css: string, sourceMap?: object}|null>} Compiled CSS or null if sass unavailable
+ */
+export async function compileSass(scss, options = {}) {
+  const sass = await tryLoadSass();
+
+  if (!sass) {
+    return null;
+  }
+
+  try {
+    // Use compileStringAsync if available (dart-sass)
+    const compileFunc = sass.compileStringAsync || sass.compileString;
+    const result = await Promise.resolve(compileFunc.call(sass, scss, {
+      syntax: 'scss',
+      loadPaths: options.loadPaths || [],
+      sourceMap: options.sourceMap || false,
+      sourceMapIncludeSources: true,
+      style: options.compressed ? 'compressed' : 'expanded',
+      silenceDeprecations: ['import'],
+    }));
+
+    return {
+      css: result.css,
+      sourceMap: result.sourceMap || null
+    };
+  } catch (error) {
+    const sassError = new Error(`SASS compilation error: ${error.message}`);
+    sassError.line = error.span?.start?.line;
+    sassError.column = error.span?.start?.column;
+    sassError.file = options.filename;
+    sassError.cause = error;
+    throw sassError;
+  }
+}
+
+// Note: preprocessStylesSync and preprocessStyles are defined later in the file
+// with support for both SASS and LESS auto-detection
+
+/**
+ * Check if sass package is available in user's project
+ * @returns {boolean}
+ */
+export function isSassAvailable() {
+  const sass = tryLoadSassSync();
+  return sass !== false;
+}
+
+/**
+ * Check if sass package is available (async)
+ * @returns {Promise<boolean>}
+ */
+export async function isSassAvailableAsync() {
+  const sass = await tryLoadSass();
+  return sass !== false;
+}
+
+/**
+ * Get sass version if available
+ * @returns {string|null}
+ */
+export function getSassVersion() {
+  const sass = tryLoadSassSync();
+  if (sass && sass.info) {
+    // sass.info is a string like "dart-sass\t1.77.0"
+    const match = sass.info.match(/(\d+\.\d+\.\d+)/);
+    return match ? match[1] : null;
+  }
+  return null;
+}
+
+/**
+ * Reset the cached sass module (for testing)
+ */
+export function resetSassCache() {
+  sassModule = null;
+}
+
+// ===== LESS SUPPORT =====
+
+/**
+ * Try to load the less module from the user's project (sync version)
+ * @returns {object|false} The less module or false if not available
+ */
+export function tryLoadLessSync() {
+  // Return cached result if already checked
+  if (lessModule !== null) {
+    return lessModule;
+  }
+
+  try {
+    const require = createRequire(import.meta.url);
+    lessModule = require('less');
+    return lessModule;
+  } catch {
+    // less not installed in user's project
+    lessModule = false;
+    return false;
+  }
+}
+
+/**
+ * Try to load the less module from the user's project (async version)
+ * @returns {Promise<object|false>} The less module or false if not available
+ */
+export async function tryLoadLess() {
+  // Return cached result if already checked
+  if (lessModule !== null) {
+    return lessModule;
+  }
+
+  try {
+    lessModule = await import('less');
+    return lessModule;
+  } catch {
+    // Fall back to sync require
+    return tryLoadLessSync();
+  }
+}
+
+/**
+ * Compile LESS to CSS (async - LESS is async-only)
+ * @param {string} less - LESS source code
+ * @param {object} options - Compilation options
+ * @param {string} [options.filename] - Source filename for error messages
+ * @param {string[]} [options.loadPaths] - Paths to search for @import
+ * @param {boolean} [options.sourceMap] - Generate source map
+ * @param {boolean} [options.compressed] - Compress output
+ * @returns {Promise<{css: string, sourceMap?: object}|null>} Compiled CSS or null if less unavailable
+ */
+export async function compileLess(less, options = {}) {
+  const lessModule = await tryLoadLess();
+
+  if (!lessModule) {
+    return null;
+  }
+
+  try {
+    const result = await lessModule.render(less, {
+      filename: options.filename || 'input.less',
+      paths: options.loadPaths || [],
+      sourceMap: options.sourceMap ? {} : undefined,
+      compress: options.compressed || false,
+      strictMath: false, // Allow math without parentheses
+      strictUnits: false,
+    });
+
+    return {
+      css: result.css,
+      sourceMap: result.map ? JSON.parse(result.map) : null
+    };
+  } catch (error) {
+    // Re-throw with better context
+    const lessError = new Error(`LESS compilation error: ${error.message}`);
+    lessError.line = error.line;
+    lessError.column = error.column;
+    lessError.file = options.filename || error.filename;
+    lessError.cause = error;
+    throw lessError;
+  }
+}
+
+/**
+ * Compile LESS to CSS (sync version - NOT RECOMMENDED)
+ * Note: LESS is fundamentally async. This function returns null in sync contexts.
+ * Use compileLess() (async) instead for proper LESS compilation.
+ * @param {string} _less - LESS source code (unused in sync context)
+ * @param {object} _options - Compilation options (unused in sync context)
+ * @returns {{css: string, sourceMap?: object}|null} Compiled CSS or null (LESS requires async)
+ */
+export function compileLessSync(_less, _options = {}) {
+  const lessModule = tryLoadLessSync();
+
+  if (!lessModule) {
+    return null;
+  }
+
+  // LESS is fundamentally async and has no true sync API
+  // Return null to indicate compilation not possible in sync context
+  // The preprocessStylesSync will fall back to returning original CSS
+  console.warn('[Pulse] LESS compilation requires async context. Use preprocessStyles() instead of preprocessStylesSync()');
+  return null;
+}
+
+/**
+ * Check if less package is available in user's project
+ * @returns {boolean}
+ */
+export function isLessAvailable() {
+  const less = tryLoadLessSync();
+  return less !== false;
+}
+
+/**
+ * Check if less package is available (async)
+ * @returns {Promise<boolean>}
+ */
+export async function isLessAvailableAsync() {
+  const less = await tryLoadLess();
+  return less !== false;
+}
+
+/**
+ * Get less version if available
+ * @returns {string|null}
+ */
+export function getLessVersion() {
+  const less = tryLoadLessSync();
+  if (less && less.version) {
+    return Array.isArray(less.version) ? less.version.join('.') : less.version;
+  }
+  return null;
+}
+
+/**
+ * Reset the cached less module (for testing)
+ */
+export function resetLessCache() {
+  lessModule = null;
+}
+
+// ===== STYLUS SUPPORT =====
+
+/**
+ * Try to load the stylus module from the user's project (sync version)
+ * @returns {object|false} The stylus module or false if not available
+ */
+export function tryLoadStylusSync() {
+  // Return cached result if already checked
+  if (stylusModule !== null) {
+    return stylusModule;
+  }
+
+  try {
+    const require = createRequire(import.meta.url);
+    stylusModule = require('stylus');
+    return stylusModule;
+  } catch {
+    // stylus not installed in user's project
+    stylusModule = false;
+    return false;
+  }
+}
+
+/**
+ * Try to load the stylus module from the user's project (async version)
+ * @returns {Promise<object|false>} The stylus module or false if not available
+ */
+export async function tryLoadStylus() {
+  // Return cached result if already checked
+  if (stylusModule !== null) {
+    return stylusModule;
+  }
+
+  try {
+    stylusModule = await import('stylus');
+    return stylusModule;
+  } catch {
+    // Fall back to sync require
+    return tryLoadStylusSync();
+  }
+}
+
+/**
+ * Compile Stylus to CSS (async)
+ * @param {string} stylus - Stylus source code
+ * @param {object} options - Compilation options
+ * @param {string} [options.filename] - Source filename for error messages
+ * @param {string[]} [options.loadPaths] - Paths to search for @import/@require
+ * @param {boolean} [options.sourceMap] - Generate source map
+ * @param {boolean} [options.compressed] - Compress output
+ * @returns {Promise<{css: string, sourceMap?: object}|null>} Compiled CSS or null if stylus unavailable
+ */
+export async function compileStylus(stylus, options = {}) {
+  const stylusModule = await tryLoadStylus();
+
+  if (!stylusModule) {
+    return null;
+  }
+
+  return new Promise((resolve, reject) => {
+    try {
+      const renderer = stylusModule(stylus)
+        .set('filename', options.filename || 'input.styl')
+        .set('compress', options.compressed || false);
+
+      // Add load paths
+      if (options.loadPaths && options.loadPaths.length > 0) {
+        options.loadPaths.forEach(path => renderer.include(path));
+      }
+
+      // Enable source maps if requested
+      if (options.sourceMap) {
+        renderer.set('sourcemap', {});
+      }
+
+      renderer.render((err, css) => {
+        if (err) {
+          const stylusError = new Error(`Stylus compilation error: ${err.message}`);
+          stylusError.line = err.line;
+          stylusError.column = err.column;
+          stylusError.file = options.filename || err.filename;
+          stylusError.cause = err;
+          reject(stylusError);
+        } else {
+          resolve({
+            css,
+            sourceMap: renderer.sourcemap || null
+          });
+        }
+      });
+    } catch (error) {
+      const stylusError = new Error(`Stylus compilation error: ${error.message}`);
+      stylusError.file = options.filename;
+      stylusError.cause = error;
+      reject(stylusError);
+    }
+  });
+}
+
+/**
+ * Compile Stylus to CSS (sync version)
+ * @param {string} stylus - Stylus source code
+ * @param {object} options - Compilation options
+ * @param {string} [options.filename] - Source filename for error messages
+ * @param {string[]} [options.loadPaths] - Paths to search for @import/@require
+ * @param {boolean} [options.sourceMap] - Generate source map
+ * @param {boolean} [options.compressed] - Compress output
+ * @returns {{css: string, sourceMap?: object}|null} Compiled CSS or null if stylus unavailable
+ */
+export function compileStylusSync(stylus, options = {}) {
+  const stylusModule = tryLoadStylusSync();
+
+  if (!stylusModule) {
+    return null;
+  }
+
+  try {
+    const renderer = stylusModule(stylus)
+      .set('filename', options.filename || 'input.styl')
+      .set('compress', options.compressed || false);
+
+    // Add load paths
+    if (options.loadPaths && options.loadPaths.length > 0) {
+      options.loadPaths.forEach(path => renderer.include(path));
+    }
+
+    // Enable source maps if requested
+    if (options.sourceMap) {
+      renderer.set('sourcemap', {});
+    }
+
+    const css = renderer.render();
+
+    return {
+      css,
+      sourceMap: renderer.sourcemap || null
+    };
+  } catch (error) {
+    // Re-throw with better context
+    const stylusError = new Error(`Stylus compilation error: ${error.message}`);
+    stylusError.line = error.line;
+    stylusError.column = error.column;
+    stylusError.file = options.filename || error.filename;
+    stylusError.cause = error;
+    throw stylusError;
+  }
+}
+
+/**
+ * Check if stylus package is available in user's project
+ * @returns {boolean}
+ */
+export function isStylusAvailable() {
+  const stylus = tryLoadStylusSync();
+  return stylus !== false;
+}
+
+/**
+ * Check if stylus package is available (async)
+ * @returns {Promise<boolean>}
+ */
+export async function isStylusAvailableAsync() {
+  const stylus = await tryLoadStylus();
+  return stylus !== false;
+}
+
+/**
+ * Get stylus version if available
+ * @returns {string|null}
+ */
+export function getStylusVersion() {
+  const stylus = tryLoadStylusSync();
+  if (stylus && stylus.version) {
+    return stylus.version;
+  }
+  return null;
+}
+
+/**
+ * Reset the cached stylus module (for testing)
+ */
+export function resetStylusCache() {
+  stylusModule = null;
+}
+
+/**
+ * Preprocess CSS - auto-detect and compile SASS, LESS, or Stylus if detected (sync)
+ * Falls back to returning original CSS if preprocessor is not available
+ * @param {string} css - CSS, SCSS, LESS, or Stylus source
+ * @param {object} options - Options
+ * @param {string} [options.filename] - Source filename
+ * @param {string[]} [options.loadPaths] - Paths for @use/@import/@require
+ * @param {boolean} [options.forceCompile] - Compile even if no syntax detected
+ * @param {'auto'|'sass'|'less'|'stylus'} [options.preprocessor] - Force specific preprocessor
+ * @returns {{css: string, preprocessor: 'sass'|'less'|'stylus'|'none', sourceMap?: object}}
+ */
+export function preprocessStylesSync(css, options = {}) {
+  // Determine which preprocessor to use
+  let preprocessor = options.preprocessor || 'auto';
+
+  if (preprocessor === 'auto') {
+    preprocessor = detectPreprocessor(css);
+  }
+
+  // Try SASS compilation
+  if (preprocessor === 'sass') {
+    const result = compileSassSync(css, options);
+    if (result) {
+      return {
+        css: result.css,
+        preprocessor: 'sass',
+        sourceMap: result.sourceMap
+      };
+    }
+  }
+
+  // Try LESS compilation
+  if (preprocessor === 'less') {
+    const result = compileLessSync(css, options);
+    if (result) {
+      return {
+        css: result.css,
+        preprocessor: 'less',
+        sourceMap: result.sourceMap
+      };
+    }
+  }
+
+  // Try Stylus compilation
+  if (preprocessor === 'stylus') {
+    const result = compileStylusSync(css, options);
+    if (result) {
+      return {
+        css: result.css,
+        preprocessor: 'stylus',
+        sourceMap: result.sourceMap
+      };
+    }
+  }
+
+  // No preprocessor detected or available
+  return { css, preprocessor: 'none' };
+}
+
+/**
+ * Preprocess CSS - auto-detect and compile SASS, LESS, or Stylus if detected (async)
+ * @param {string} css - CSS, SCSS, LESS, or Stylus source
+ * @param {object} options - Options
+ * @returns {Promise<{css: string, preprocessor: 'sass'|'less'|'stylus'|'none', sourceMap?: object}>}
+ */
+export async function preprocessStyles(css, options = {}) {
+  // Determine which preprocessor to use
+  let preprocessor = options.preprocessor || 'auto';
+
+  if (preprocessor === 'auto') {
+    preprocessor = detectPreprocessor(css);
+  }
+
+  // Try SASS compilation
+  if (preprocessor === 'sass') {
+    const result = await compileSass(css, options);
+    if (result) {
+      return {
+        css: result.css,
+        preprocessor: 'sass',
+        sourceMap: result.sourceMap
+      };
+    }
+  }
+
+  // Try LESS compilation
+  if (preprocessor === 'less') {
+    const result = await compileLess(css, options);
+    if (result) {
+      return {
+        css: result.css,
+        preprocessor: 'less',
+        sourceMap: result.sourceMap
+      };
+    }
+  }
+
+  // Try Stylus compilation
+  if (preprocessor === 'stylus') {
+    const result = await compileStylus(css, options);
+    if (result) {
+      return {
+        css: result.css,
+        preprocessor: 'stylus',
+        sourceMap: result.sourceMap
+      };
+    }
+  }
+
+  // No preprocessor detected or available
+  return { css, preprocessor: 'none' };
+}
+
+/**
+ * Reset all preprocessor caches (for testing)
+ */
+export function resetPreprocessorCaches() {
+  resetSassCache();
+  resetLessCache();
+  resetStylusCache();
+}
+
+export default {
+  // SASS
+  hasSassSyntax,
+  tryLoadSass,
+  tryLoadSassSync,
+  compileSass,
+  compileSassSync,
+  isSassAvailable,
+  isSassAvailableAsync,
+  getSassVersion,
+  resetSassCache,
+
+  // LESS
+  hasLessSyntax,
+  tryLoadLess,
+  tryLoadLessSync,
+  compileLess,
+  compileLessSync,
+  isLessAvailable,
+  isLessAvailableAsync,
+  getLessVersion,
+  resetLessCache,
+
+  // Stylus
+  hasStylusSyntax,
+  tryLoadStylus,
+  tryLoadStylusSync,
+  compileStylus,
+  compileStylusSync,
+  isStylusAvailable,
+  isStylusAvailableAsync,
+  getStylusVersion,
+  resetStylusCache,
+
+  // Auto-detect
+  detectPreprocessor,
+  preprocessStyles,
+  preprocessStylesSync,
+  resetPreprocessorCaches
+};

package/loader/vite-plugin.js

@@ -4,11 +4,17 @@
  * Enables .pulse file support in Vite projects
  * Extracts CSS to virtual .css modules so Vite's CSS pipeline handles them
  * (prevents JS minifier from corrupting CSS in template literals)
+ *
+ * SASS/SCSS Support:
+ * - If `sass` is installed in the user's project, SCSS syntax in style blocks
+ *   is automatically compiled before being passed to Vite's CSS pipeline
+ * - No configuration needed - just install sass: `npm install -D sass`
  */
 
 import { compile } from '../compiler/index.js';
 import { existsSync } from 'fs';
 import { resolve, dirname } from 'path';
+import { preprocessStylesSync, isSassAvailable, getSassVersion } from '../compiler/preprocessor.js';
 
 // Virtual module ID for extracted CSS (uses .css extension so Vite treats it as CSS)
 const VIRTUAL_CSS_SUFFIX = '.pulse.css';
@@ -19,16 +25,37 @@ const VIRTUAL_CSS_SUFFIX = '.pulse.css';
 export default function pulsePlugin(options = {}) {
   const {
     exclude = /node_modules/,
-    sourceMap = true
+    sourceMap = true,
+    // SASS options
+    sass: sassOptions = {}
   } = options;
 
   // Store extracted CSS for each .pulse module
   const cssMap = new Map();
 
+  // Check for sass availability once at startup
+  let sassAvailable = false;
+  let sassVersion = null;
+
   return {
     name: 'vite-plugin-pulse',
     enforce: 'pre',
 
+    /**
+     * Log sass availability on build start
+     */
+    buildStart() {
+      // Clear CSS map on new build
+      cssMap.clear();
+
+      // Check sass availability
+      sassAvailable = isSassAvailable();
+      if (sassAvailable) {
+        sassVersion = getSassVersion();
+        console.log(`[Pulse] SASS support enabled (sass ${sassVersion || 'unknown'})`);
+      }
+    },
+
     /**
      * Resolve .pulse files and virtual CSS modules
      */
@@ -107,9 +134,27 @@ export default function pulsePlugin(options = {}) {
         // Extract CSS from compiled output and move to virtual CSS module
         const stylesMatch = outputCode.match(/const styles = `([\s\S]*?)`;/);
         if (stylesMatch) {
-          const css = stylesMatch[1];
+          let css = stylesMatch[1];
           const virtualCssId = id + '.css';
 
+          // Preprocess SASS/SCSS if detected and sass is available
+          if (sassAvailable) {
+            try {
+              const preprocessed = preprocessStylesSync(css, {
+                filename: id,
+                loadPaths: [dirname(id), ...(sassOptions.loadPaths || [])],
+                compressed: sassOptions.compressed || false
+              });
+
+              if (preprocessed.wasSass) {
+                css = preprocessed.css;
+              }
+            } catch (sassError) {
+              this.warn(`SASS compilation warning in ${id}: ${sassError.message}`);
+              // Continue with original CSS if SASS fails
+            }
+          }
+
           // Store CSS for the virtual module loader
           cssMap.set(id, css);
 
@@ -168,21 +213,21 @@ export default function pulsePlugin(options = {}) {
     },
 
     /**
-     * Configure dev server
+     * Configure dev server - log sass status on start
      */
     configureServer(server) {
+      // Check sass on server start if not already checked
+      if (!sassAvailable) {
+        sassAvailable = isSassAvailable();
+        if (sassAvailable) {
+          sassVersion = getSassVersion();
+          console.log(`[Pulse] SASS support enabled (sass ${sassVersion || 'unknown'})`);
+        }
+      }
+
       server.middlewares.use((_req, _res, next) => {
-        // Add any custom middleware here
         next();
       });
-    },
-
-    /**
-     * Build hooks
-     */
-    buildStart() {
-      // Clear CSS map on new build
-      cssMap.clear();
     }
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pulse-js-framework",
-  "version": "1.7.31",
+  "version": "1.7.32",
   "description": "A declarative DOM framework with CSS selector-based structure and reactive pulsations",
   "type": "module",
   "main": "index.js",
@@ -88,6 +88,7 @@
     "./compiler/lexer": "./compiler/lexer.js",
     "./compiler/parser": "./compiler/parser.js",
     "./compiler/transformer": "./compiler/transformer.js",
+    "./compiler/preprocessor": "./compiler/preprocessor.js",
     "./core/errors": "./runtime/errors.js",
     "./vite": {
       "types": "./types/index.d.ts",
@@ -109,10 +110,11 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "npm run test:compiler && npm run test:sourcemap && npm run test:css-parsing && npm run test:pulse && npm run test:dom && npm run test:dom-element && npm run test:dom-list && npm run test:dom-conditional && npm run test:dom-lifecycle && npm run test:dom-selector && npm run test:dom-adapter && npm run test:dom-advanced && npm run test:enhanced-mock-adapter && npm run test:router && npm run test:store && npm run test:context && npm run test:hmr && npm run test:lint && npm run test:format && npm run test:analyze && npm run test:cli && npm run test:cli-ui && npm run test:cli-create && npm run test:lru-cache && npm run test:utils && npm run test:utils-coverage && npm run test:docs && npm run test:docs-nav && npm run test:async && npm run test:async-coverage && npm run test:form && npm run test:http && npm run test:devtools && npm run test:native && npm run test:a11y && npm run test:a11y-enhanced && npm run test:logger && npm run test:logger-prod && npm run test:errors && npm run test:security && npm run test:websocket && npm run test:graphql && npm run test:graphql-coverage && npm run test:doctor && npm run test:scaffold && npm run test:test-runner && npm run test:build && npm run test:integration && npm run test:context-stress && npm run test:form-edge-cases && npm run test:graphql-subscriptions && npm run test:http-edge-cases && npm run test:integration-advanced && npm run test:websocket-stress && npm run test:ssr && npm run test:ssr-hydrator",
+    "test": "npm run test:compiler && npm run test:sourcemap && npm run test:css-parsing && npm run test:preprocessor && npm run test:pulse && npm run test:dom && npm run test:dom-element && npm run test:dom-list && npm run test:dom-conditional && npm run test:dom-lifecycle && npm run test:dom-selector && npm run test:dom-adapter && npm run test:dom-advanced && npm run test:enhanced-mock-adapter && npm run test:router && npm run test:store && npm run test:context && npm run test:hmr && npm run test:lint && npm run test:format && npm run test:analyze && npm run test:cli && npm run test:cli-ui && npm run test:cli-create && npm run test:lru-cache && npm run test:utils && npm run test:utils-coverage && npm run test:docs && npm run test:docs-nav && npm run test:async && npm run test:async-coverage && npm run test:form && npm run test:http && npm run test:devtools && npm run test:native && npm run test:a11y && npm run test:a11y-enhanced && npm run test:logger && npm run test:logger-prod && npm run test:errors && npm run test:security && npm run test:websocket && npm run test:graphql && npm run test:graphql-coverage && npm run test:doctor && npm run test:scaffold && npm run test:test-runner && npm run test:build && npm run test:integration && npm run test:context-stress && npm run test:form-edge-cases && npm run test:graphql-subscriptions && npm run test:http-edge-cases && npm run test:integration-advanced && npm run test:websocket-stress && npm run test:ssr && npm run test:ssr-hydrator",
     "test:compiler": "node test/compiler.test.js",
     "test:sourcemap": "node test/sourcemap.test.js",
     "test:css-parsing": "node test/css-parsing.test.js",
+    "test:preprocessor": "node test/preprocessor.test.js",
     "test:pulse": "node test/pulse.test.js",
     "test:dom": "node test/dom.test.js",
     "test:dom-element": "node test/dom-element.test.js",