pulse-js-framework 1.4.4 → 1.4.6

package/README.md

@@ -13,6 +13,7 @@ A declarative DOM framework with CSS selector-based structure and reactive pulsa
 - **No Build Required** - Works directly in the browser
 - **Lightweight** - Minimal footprint, maximum performance
 - **Router & Store** - Built-in SPA routing and state management
+- **Hot Module Replacement** - Full HMR with state preservation
 - **Mobile Apps** - Build native Android & iOS apps (zero dependencies)
 - **TypeScript Support** - Full type definitions for IDE autocomplete
 
@@ -280,6 +281,57 @@ const store = createStore({
 store.user.set({ name: 'John' });
 ```
 
+### HMR (Hot Module Replacement)
+
+Pulse supports full HMR with state preservation during development:
+
+```javascript
+import { createHMRContext } from 'pulse-js-framework/runtime/hmr';
+
+const hmr = createHMRContext(import.meta.url);
+
+// State preserved across HMR updates
+const count = hmr.preservePulse('count', 0);
+const items = hmr.preservePulse('items', []);
+
+// Effects tracked for automatic cleanup
+hmr.setup(() => {
+  effect(() => {
+    document.title = `Count: ${count.get()}`;
+  });
+});
+
+// Accept HMR updates
+hmr.accept();
+```
+
+**HMR Features:**
+- `preservePulse(key, value)` - Create pulses that survive module replacement
+- `setup(callback)` - Execute with effect tracking for cleanup
+- Automatic event listener cleanup (no accumulation)
+- Works with Vite dev server
+
+### Logger
+
+```javascript
+import { createLogger, setLogLevel, LogLevel } from 'pulse-js-framework/runtime/logger';
+
+// Create a namespaced logger
+const log = createLogger('MyComponent');
+
+log.info('Component initialized');    // [MyComponent] Component initialized
+log.warn('Deprecated method used');
+log.error('Failed to load', error);
+log.debug('Detailed info');           // Only shown at DEBUG level
+
+// Set global log level
+setLogLevel(LogLevel.DEBUG);  // SILENT, ERROR, WARN, INFO, DEBUG
+
+// Child loggers for sub-namespaces
+const childLog = log.child('Validation');
+childLog.info('Validating'); // [MyComponent:Validation] Validating
+```
+
 ## CLI Commands
 
 ```bash
@@ -399,6 +451,28 @@ onNativeReady(({ platform }) => {
 
 **Available APIs:** Storage, Device Info, Network Status, Toast, Vibration, Clipboard, App Lifecycle
 
+## VSCode Extension
+
+Pulse includes a VSCode extension for `.pulse` files with syntax highlighting and snippets.
+
+### Installation
+
+```bash
+# Windows (PowerShell)
+cd vscode-extension
+powershell -ExecutionPolicy Bypass -File install.ps1
+
+# macOS/Linux
+cd vscode-extension
+bash install.sh
+```
+
+Then restart VSCode. You'll get:
+- Syntax highlighting for `.pulse` files
+- Code snippets (`page`, `state`, `view`, `@click`, etc.)
+- Bracket matching and auto-closing
+- Comment toggling (Ctrl+/)
+
 ## TypeScript Support
 
 Pulse includes full TypeScript definitions for IDE autocomplete and type checking:

package/cli/index.js

@@ -7,11 +7,14 @@
 import { fileURLToPath } from 'url';
 import { dirname, join, resolve } from 'path';
 import { existsSync, mkdirSync, writeFileSync, readFileSync, cpSync } from 'fs';
+import { log } from './logger.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
-const VERSION = '1.4.3';
+// Version - read dynamically from package.json
+const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
+const VERSION = pkg.version;
 
 // Command handlers
 const commands = {
@@ -38,8 +41,8 @@ async function main() {
   if (command in commands) {
     await commands[command](args.slice(1));
   } else {
-    console.error(`Unknown command: ${command}`);
-    console.log('Run "pulse help" for usage information.');
+    log.error(`Unknown command: ${command}`);
+    log.info('Run "pulse help" for usage information.');
     process.exit(1);
   }
 }
@@ -48,7 +51,7 @@ async function main() {
  * Show help message
  */
 function showHelp() {
-  console.log(`
+  log.info(`
 Pulse Framework CLI v${VERSION}
 
 Usage: pulse <command> [options]
@@ -102,7 +105,7 @@ Documentation: https://github.com/vincenthirtz/pulse-js-framework
  * Show version
  */
 function showVersion() {
-  console.log(`Pulse Framework v${VERSION}`);
+  log.info(`Pulse Framework v${VERSION}`);
 }
 
 /**
@@ -112,19 +115,19 @@ async function createProject(args) {
   const projectName = args[0];
 
   if (!projectName) {
-    console.error('Please provide a project name.');
-    console.log('Usage: pulse create <project-name>');
+    log.error('Please provide a project name.');
+    log.info('Usage: pulse create <project-name>');
     process.exit(1);
   }
 
   const projectPath = resolve(process.cwd(), projectName);
 
   if (existsSync(projectPath)) {
-    console.error(`Directory "${projectName}" already exists.`);
+    log.error(`Directory "${projectName}" already exists.`);
     process.exit(1);
   }
 
-  console.log(`Creating new Pulse project: ${projectName}`);
+  log.info(`Creating new Pulse project: ${projectName}`);
 
   // Create project structure
   mkdirSync(projectPath);
@@ -281,7 +284,7 @@ dist
 
   writeFileSync(join(projectPath, '.gitignore'), gitignore);
 
-  console.log(`
+  log.info(`
 Project created successfully!
 
 Next steps:
@@ -297,7 +300,7 @@ Happy coding with Pulse!
  * Run development server
  */
 async function runDev(args) {
-  console.log('Starting Pulse development server...');
+  log.info('Starting Pulse development server...');
 
   // Use dynamic import for the dev server module
   const { startDevServer } = await import('./dev.js');
@@ -308,7 +311,7 @@ async function runDev(args) {
  * Build for production
  */
 async function runBuild(args) {
-  console.log('Building Pulse project for production...');
+  log.info('Building Pulse project for production...');
 
   const { buildProject } = await import('./build.js');
   await buildProject(args);
@@ -318,7 +321,7 @@ async function runBuild(args) {
  * Preview production build
  */
 async function runPreview(args) {
-  console.log('Starting Pulse preview server...');
+  log.info('Starting Pulse preview server...');
 
   const { previewBuild } = await import('./build.js');
   await previewBuild(args);
@@ -363,13 +366,13 @@ async function compileFile(args) {
   const inputFile = args[0];
 
   if (!inputFile) {
-    console.error('Please provide a file to compile.');
-    console.log('Usage: pulse compile <file.pulse>');
+    log.error('Please provide a file to compile.');
+    log.info('Usage: pulse compile <file.pulse>');
     process.exit(1);
   }
 
   if (!existsSync(inputFile)) {
-    console.error(`File not found: ${inputFile}`);
+    log.error(`File not found: ${inputFile}`);
     process.exit(1);
   }
 
@@ -381,11 +384,11 @@ async function compileFile(args) {
   if (result.success) {
     const outputFile = inputFile.replace(/\.pulse$/, '.js');
     writeFileSync(outputFile, result.code);
-    console.log(`Compiled: ${inputFile} -> ${outputFile}`);
+    log.info(`Compiled: ${inputFile} -> ${outputFile}`);
   } else {
-    console.error('Compilation failed:');
+    log.error('Compilation failed:');
     for (const error of result.errors) {
-      console.error(`  ${error.message}`);
+      log.error(`  ${error.message}`);
     }
     process.exit(1);
   }
@@ -393,6 +396,6 @@ async function compileFile(args) {
 
 // Run main
 main().catch(error => {
-  console.error('Error:', error.message);
+  log.error('Error:', error.message);
   process.exit(1);
 });

package/cli/logger.js

@@ -0,0 +1,122 @@
+/**
+ * Pulse CLI Logger
+ * Lightweight logger for CLI tools with support for verbose mode
+ * @module pulse-cli/logger
+ */
+
+/** @type {boolean} */
+let verboseMode = false;
+
+/**
+ * Enable or disable verbose mode for debug output
+ * @param {boolean} enabled - Whether to enable verbose mode
+ * @returns {void}
+ * @example
+ * setVerbose(true);
+ * log.debug('This will now be shown');
+ */
+export function setVerbose(enabled) {
+  verboseMode = enabled;
+}
+
+/**
+ * Check if verbose mode is currently enabled
+ * @returns {boolean} True if verbose mode is enabled
+ * @example
+ * if (isVerbose()) {
+ *   // Perform additional logging
+ * }
+ */
+export function isVerbose() {
+  return verboseMode;
+}
+
+/**
+ * CLI Logger object with console-like API
+ * @namespace log
+ */
+export const log = {
+  /**
+   * Log an info message (always shown)
+   * @param {...*} args - Values to log
+   * @returns {void}
+   * @example
+   * log.info('Starting server on port', 3000);
+   */
+  info(...args) {
+    console.log(...args);
+  },
+
+  /**
+   * Log a success message (always shown)
+   * @param {...*} args - Values to log
+   * @returns {void}
+   * @example
+   * log.success('Build completed successfully!');
+   */
+  success(...args) {
+    console.log(...args);
+  },
+
+  /**
+   * Log a warning message
+   * @param {...*} args - Values to log
+   * @returns {void}
+   * @example
+   * log.warn('Deprecated feature used');
+   */
+  warn(...args) {
+    console.warn(...args);
+  },
+
+  /**
+   * Log an error message
+   * @param {...*} args - Values to log
+   * @returns {void}
+   * @example
+   * log.error('Failed to compile:', error.message);
+   */
+  error(...args) {
+    console.error(...args);
+  },
+
+  /**
+   * Log a debug message (only shown in verbose mode)
+   * @param {...*} args - Values to log
+   * @returns {void}
+   * @example
+   * log.debug('Processing file:', filename);
+   */
+  debug(...args) {
+    if (verboseMode) {
+      console.log('[debug]', ...args);
+    }
+  },
+
+  /**
+   * Log a verbose message (only shown in verbose mode)
+   * @param {...*} args - Values to log
+   * @returns {void}
+   * @example
+   * log.verbose('Additional details:', data);
+   */
+  verbose(...args) {
+    if (verboseMode) {
+      console.log(...args);
+    }
+  },
+
+  /**
+   * Print a blank line for spacing
+   * @returns {void}
+   * @example
+   * log.info('Section 1');
+   * log.newline();
+   * log.info('Section 2');
+   */
+  newline() {
+    console.log();
+  }
+};
+
+export default log;

package/index.js

@@ -4,14 +4,20 @@
  * A declarative DOM framework with CSS selector-based structure
  */
 
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
 // Runtime exports
 export * from './runtime/index.js';
 
 // Compiler exports
 export { compile, parse, tokenize } from './compiler/index.js';
 
-// Version
-export const VERSION = '1.4.3';
+// Version - read dynamically from package.json
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, 'package.json'), 'utf-8'));
+export const VERSION = pkg.version;
 
 // Default export
 export default {

package/loader/vite-plugin.js

@@ -69,22 +69,30 @@ export default function pulsePlugin(options = {}) {
     /**
      * Handle hot module replacement
      */
-    handleHotUpdate({ file, server }) {
+    handleHotUpdate({ file, server, modules }) {
       if (file.endsWith('.pulse')) {
         console.log(`[Pulse] HMR update: ${file}`);
 
-        // Invalidate the module
+        // Invalidate the module in Vite's module graph
         const module = server.moduleGraph.getModuleById(file);
         if (module) {
           server.moduleGraph.invalidateModule(module);
         }
 
-        // Send full reload for now
-        // In a more advanced implementation, we could do partial updates
+        // Send HMR update instead of full reload
+        // The module will handle its own state preservation via hmrRuntime
         server.ws.send({
-          type: 'full-reload',
-          path: '*'
+          type: 'update',
+          updates: [{
+            type: 'js-update',
+            path: file,
+            acceptedPath: file,
+            timestamp: Date.now()
+          }]
         });
+
+        // Return empty array to prevent Vite's default HMR handling
+        return [];
       }
     },
 
@@ -117,6 +125,14 @@ export default function pulsePlugin(options = {}) {
  */
 export const hmrRuntime = `
 if (import.meta.hot) {
+  // Cleanup effects before module replacement
+  import.meta.hot.dispose(() => {
+    import('pulse-js-framework/runtime/pulse').then(m => {
+      m.disposeModule(import.meta.url);
+    });
+  });
+
+  // Accept HMR updates
   import.meta.hot.accept((newModule) => {
     if (newModule) {
       // Re-render with new module

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pulse-js-framework",
-  "version": "1.4.4",
+  "version": "1.4.6",
   "description": "A declarative DOM framework with CSS selector-based structure and reactive pulsations",
   "type": "module",
   "main": "index.js",
@@ -17,6 +17,14 @@
       "types": "./types/index.d.ts",
       "default": "./runtime/index.js"
     },
+    "./runtime/pulse": {
+      "types": "./types/pulse.d.ts",
+      "default": "./runtime/pulse.js"
+    },
+    "./runtime/dom": {
+      "types": "./types/dom.d.ts",
+      "default": "./runtime/dom.js"
+    },
     "./runtime/router": {
       "types": "./types/router.d.ts",
       "default": "./runtime/router.js"
@@ -25,9 +33,30 @@
       "types": "./types/store.d.ts",
       "default": "./runtime/store.js"
     },
-    "./runtime/*": "./runtime/*.js",
-    "./compiler": "./compiler/index.js",
-    "./vite": "./loader/vite-plugin.js"
+    "./runtime/native": {
+      "types": "./types/index.d.ts",
+      "default": "./runtime/native.js"
+    },
+    "./runtime/logger": {
+      "types": "./types/logger.d.ts",
+      "default": "./runtime/logger.js"
+    },
+    "./runtime/hmr": {
+      "default": "./runtime/hmr.js"
+    },
+    "./compiler": {
+      "types": "./types/index.d.ts",
+      "default": "./compiler/index.js"
+    },
+    "./compiler/lexer": "./compiler/lexer.js",
+    "./compiler/parser": "./compiler/parser.js",
+    "./compiler/transformer": "./compiler/transformer.js",
+    "./vite": {
+      "types": "./types/index.d.ts",
+      "default": "./loader/vite-plugin.js"
+    },
+    "./mobile": "./mobile/bridge/pulse-native.js",
+    "./package.json": "./package.json"
   },
   "files": [
     "index.js",
@@ -41,16 +70,18 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "npm run test:compiler && npm run test:pulse && npm run test:dom && npm run test:router && npm run test:store && npm run test:lint && npm run test:format && npm run test:analyze",
+    "test": "npm run test:compiler && npm run test:pulse && npm run test:dom && npm run test:router && npm run test:store && npm run test:hmr && npm run test:lint && npm run test:format && npm run test:analyze",
     "test:compiler": "node test/compiler.test.js",
     "test:pulse": "node test/pulse.test.js",
     "test:dom": "node test/dom.test.js",
     "test:router": "node test/router.test.js",
     "test:store": "node test/store.test.js",
+    "test:hmr": "node test/hmr.test.js",
     "test:lint": "node test/lint.test.js",
     "test:format": "node test/format.test.js",
     "test:analyze": "node test/analyze.test.js",
-    "build:netlify": "node scripts/build-netlify.js"
+    "build:netlify": "node scripts/build-netlify.js",
+    "version": "node scripts/sync-version.js"
   },
   "keywords": [
     "framework",

package/runtime/dom.js

@@ -6,6 +6,13 @@
  */
 
 import { effect, pulse, batch, onCleanup } from './pulse.js';
+import { loggers } from './logger.js';
+
+const log = loggers.dom;
+
+// Selector cache for parseSelector
+const selectorCache = new Map();
+const SELECTOR_CACHE_MAX = 500;
 
 // Lifecycle tracking
 let mountCallbacks = [];
@@ -38,6 +45,7 @@ export function onUnmount(fn) {
 /**
  * Parse a CSS selector-like string into element configuration
  * Supports: tag, #id, .class, [attr=value]
+ * Results are cached for performance.
  *
  * Examples:
  *   "div" -> { tag: "div" }
@@ -47,6 +55,22 @@ export function onUnmount(fn) {
  *   "input[type=text][placeholder=Name]" -> { tag: "input", attrs: { type: "text", placeholder: "Name" } }
  */
 export function parseSelector(selector) {
+  if (!selector || selector === '') {
+    return { tag: 'div', id: null, classes: [], attrs: {} };
+  }
+
+  // Check cache first
+  const cached = selectorCache.get(selector);
+  if (cached) {
+    // Return a shallow copy to prevent mutation
+    return {
+      tag: cached.tag,
+      id: cached.id,
+      classes: [...cached.classes],
+      attrs: { ...cached.attrs }
+    };
+  }
+
   const config = {
     tag: 'div',
     id: null,
@@ -54,30 +78,30 @@ export function parseSelector(selector) {
     attrs: {}
   };
 
-  if (!selector || selector === '') return config;
+  let remaining = selector;
 
   // Match tag name at the start
-  const tagMatch = selector.match(/^([a-zA-Z][a-zA-Z0-9-]*)/);
+  const tagMatch = remaining.match(/^([a-zA-Z][a-zA-Z0-9-]*)/);
   if (tagMatch) {
     config.tag = tagMatch[1];
-    selector = selector.slice(tagMatch[0].length);
+    remaining = remaining.slice(tagMatch[0].length);
   }
 
   // Match ID
-  const idMatch = selector.match(/#([a-zA-Z][a-zA-Z0-9-_]*)/);
+  const idMatch = remaining.match(/#([a-zA-Z][a-zA-Z0-9-_]*)/);
   if (idMatch) {
     config.id = idMatch[1];
-    selector = selector.replace(idMatch[0], '');
+    remaining = remaining.replace(idMatch[0], '');
   }
 
   // Match classes
-  const classMatches = selector.matchAll(/\.([a-zA-Z][a-zA-Z0-9-_]*)/g);
+  const classMatches = remaining.matchAll(/\.([a-zA-Z][a-zA-Z0-9-_]*)/g);
   for (const match of classMatches) {
     config.classes.push(match[1]);
   }
 
   // Match attributes
-  const attrMatches = selector.matchAll(/\[([a-zA-Z][a-zA-Z0-9-_]*)(?:=([^\]]+))?\]/g);
+  const attrMatches = remaining.matchAll(/\[([a-zA-Z][a-zA-Z0-9-_]*)(?:=([^\]]+))?\]/g);
   for (const match of attrMatches) {
     const key = match[1];
     let value = match[2] || '';
@@ -89,7 +113,21 @@ export function parseSelector(selector) {
     config.attrs[key] = value;
   }
 
-  return config;
+  // Cache the result (with size limit to prevent memory leaks)
+  if (selectorCache.size >= SELECTOR_CACHE_MAX) {
+    // Remove oldest entry (first key)
+    const firstKey = selectorCache.keys().next().value;
+    selectorCache.delete(firstKey);
+  }
+  selectorCache.set(selector, config);
+
+  // Return a copy
+  return {
+    tag: config.tag,
+    id: config.id,
+    classes: [...config.classes],
+    attrs: { ...config.attrs }
+  };
 }
 
 /**
@@ -262,6 +300,12 @@ export function style(element, prop, getValue) {
  */
 export function on(element, event, handler, options) {
   element.addEventListener(event, handler, options);
+
+  // Auto-cleanup: remove listener when effect is disposed (HMR support)
+  onCleanup(() => {
+    element.removeEventListener(event, handler, options);
+  });
+
   return element;
 }
 
@@ -523,7 +567,7 @@ export function component(setup) {
           try {
             cb();
           } catch (e) {
-            console.error('Mount callback error:', e);
+            log.error('Mount callback error:', e);
           }
         }
       });
@@ -559,7 +603,7 @@ export function portal(children, target) {
     : target;
 
   if (!resolvedTarget) {
-    console.warn('Portal target not found:', target);
+    log.warn('Portal target not found:', target);
     return document.createComment('portal-target-not-found');
   }
 
@@ -653,7 +697,7 @@ export function errorBoundary(children, fallback) {
         marker.parentNode?.insertBefore(fragment, marker.nextSibling);
       }
     } catch (e) {
-      console.error('Error in component:', e);
+      log.error('Error in component:', e);
       error.set(e);
       // Re-render with error
       if (!hasError) {