pulse-js-framework 1.7.15 → 1.7.17

package/cli/index.js

@@ -9,6 +9,7 @@ import { dirname, join, resolve, relative } from 'path';
 import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, watch } from 'fs';
 import { log } from './logger.js';
 import { findPulseFiles, parseArgs } from './utils/file-utils.js';
+import { runHelp } from './help.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -23,6 +24,7 @@ const commands = {
   version: showVersion,
   create: createProject,
   init: initProject,
+  new: newPulseFile,
   dev: runDev,
   build: runBuild,
   preview: runPreview,
@@ -72,7 +74,9 @@ const commandAliases = {
   'scaffod': 'scaffold',
   'scafflod': 'scaffold',
   'doc': 'docs',
-  'dcos': 'docs'
+  'dcos': 'docs',
+  'nwe': 'new',
+  'enw': 'new'
 };
 
 /**
@@ -136,10 +140,28 @@ function suggestCommand(input) {
  */
 async function main() {
   const args = process.argv.slice(2);
-  const command = args[0] || 'help';
+  let command = args[0] || 'help';
+
+  // Handle global --help and -h flags
+  if (command === '--help' || command === '-h') {
+    command = 'help';
+  }
+
+  // Handle --version and -v flags
+  if (command === '--version' || command === '-v') {
+    command = 'version';
+  }
+
+  // Handle command-specific help: pulse <cmd> --help or pulse <cmd> -h
+  const cmdArgs = args.slice(1);
+  if (cmdArgs.includes('--help') || cmdArgs.includes('-h')) {
+    // Show help for the specific command
+    await commands.help([command]);
+    return;
+  }
 
   if (command in commands) {
-    await commands[command](args.slice(1));
+    await commands[command](cmdArgs);
   } else {
     log.error(`Unknown command: ${command}`);
 
@@ -156,110 +178,10 @@ async function main() {
 
 /**
  * Show help message
+ * Supports: pulse help, pulse help <command>
  */
-function showHelp() {
-  log.info(`
-Pulse Framework CLI v${VERSION}
-
-Usage: pulse <command> [options]
-
-Commands:
-  create <name>      Create a new Pulse project
-  init [options]     Initialize project in current directory
-  dev [port]         Start development server (default: 3000)
-  build              Build for production (minified)
-  preview [port]     Preview production build (default: 4173)
-  compile <file>     Compile a .pulse file to JavaScript
-  mobile <cmd>       Mobile app commands (init, build, run)
-  lint [files]       Validate .pulse files for errors and style
-  format [files]     Format .pulse files consistently
-  analyze            Analyze bundle size and dependencies
-  test [files]       Run tests with coverage support
-  doctor             Run project diagnostics
-  scaffold <type>    Generate components, pages, stores
-  docs               Generate API documentation from JSDoc
-  release <type>     Create a new release (patch, minor, major)
-  docs-test          Test documentation (syntax, imports, HTTP)
-  version            Show version number
-  help               Show this help message
-
-Create/Init Options:
-  --typescript       Create TypeScript project
-  --minimal          Create minimal project structure
-
-Compile Options:
-  --watch, -w        Watch files and recompile on changes
-  --dry-run          Show what would be compiled without writing
-  --output, -o       Output directory (default: same as input)
-
-Lint Options:
-  --fix              Auto-fix fixable issues
-  --watch, -w        Watch files and re-lint on changes
-  --dry-run          Show fixes without applying (use with --fix)
-
-Format Options:
-  --check            Check formatting without writing (dry-run)
-  --watch, -w        Watch files and re-format on changes
-  --write            Write formatted output (default)
-
-Analyze Options:
-  --json             Output analysis as JSON
-  --verbose          Show detailed metrics
-
-Test Options:
-  --coverage, -c     Collect code coverage
-  --watch, -w        Watch files and re-run tests
-  --filter, -f       Filter tests by name pattern
-  --timeout, -t      Test timeout in ms (default: 30000)
-  --bail, -b         Stop on first failure
-  --create <name>    Generate a new test file
-
-Doctor Options:
-  --verbose, -v      Show detailed diagnostics
-  --json             Output as JSON
-
-Scaffold Options:
-  --dir, -d <path>   Output directory
-  --force, -f        Overwrite existing files
-  --props            Include props section (components)
-
-Docs Options:
-  --generate, -g     Generate documentation
-  --format, -f       Output format: markdown, json, html
-  --output, -o       Output directory (default: docs/api)
-
-Release Options:
-  --dry-run          Show what would be done without making changes
-  --no-push          Create commit and tag but don't push
-  --title <text>     Release title for changelog
-  --skip-prompt      Use empty changelog (for automation)
-  --skip-docs-test   Skip documentation tests before release
-  --from-commits     Auto-extract changelog from git commits since last tag
-
-Examples:
-  pulse create my-app
-  pulse create my-app --typescript
-  pulse init --typescript
-  pulse dev
-  pulse build
-  pulse test
-  pulse test --coverage --watch
-  pulse test --create MyComponent
-  pulse doctor
-  pulse doctor --verbose
-  pulse scaffold component Button
-  pulse scaffold page Dashboard
-  pulse scaffold store user
-  pulse docs --generate
-  pulse docs --generate --format html
-  pulse compile src/App.pulse
-  pulse lint src/ --fix
-  pulse format --check
-  pulse analyze --json
-  pulse release patch
-
-Documentation: https://github.com/vincenthirtz/pulse-js-framework
-  `);
+function showHelp(args = []) {
+  runHelp(args);
 }
 
 /**
@@ -764,6 +686,80 @@ async function runScaffoldCmd(args) {
   await runScaffold(args);
 }
 
+/**
+ * Create a new .pulse file
+ * Usage: pulse new <name> [options]
+ * Options:
+ *   --type, -t <type>  Type: component, page, layout (default: component)
+ *   --dir, -d <path>   Output directory (default: src/components or based on type)
+ *   --force, -f        Overwrite existing files
+ *   --props            Include props section
+ *   --no-state         Skip state section
+ *   --no-style         Skip style section
+ */
+async function newPulseFile(args) {
+  const { options, patterns } = parseArgs(args);
+  const name = patterns[0];
+
+  if (!name) {
+    log.error('Please provide a name for the .pulse file.');
+    log.info(`
+Usage: pulse new <name> [options]
+
+Options:
+  --type, -t <type>  Type: component, page, layout (default: component)
+  --dir, -d <path>   Output directory
+  --force, -f        Overwrite existing files
+  --props            Include props section
+  --no-state         Skip state section
+  --no-style         Skip style section
+
+Examples:
+  pulse new Button                   Create src/components/Button.pulse
+  pulse new Dashboard --type page    Create src/pages/Dashboard.pulse
+  pulse new Admin --type layout      Create src/layouts/Admin.pulse
+  pulse new Modal --props            Create component with props section
+  pulse new Card -d src/ui           Create in custom directory
+`);
+    process.exit(1);
+  }
+
+  // Determine type
+  const type = options.type || options.t || 'component';
+  const validTypes = ['component', 'page', 'layout'];
+
+  if (!validTypes.includes(type)) {
+    log.error(`Invalid type: ${type}`);
+    log.info(`Valid types: ${validTypes.join(', ')}`);
+    process.exit(1);
+  }
+
+  // Map type to scaffold type and delegate
+  const { runScaffold } = await import('./scaffold.js');
+
+  // Build args for scaffold command
+  const scaffoldArgs = [type, name];
+
+  // Pass through options
+  if (options.dir || options.d) {
+    scaffoldArgs.push('--dir', options.dir || options.d);
+  }
+  if (options.force || options.f) {
+    scaffoldArgs.push('--force');
+  }
+  if (options.props) {
+    scaffoldArgs.push('--props');
+  }
+  if (options.state === false) {
+    scaffoldArgs.push('--no-state');
+  }
+  if (options.style === false) {
+    scaffoldArgs.push('--no-style');
+  }
+
+  await runScaffold(scaffoldArgs);
+}
+
 /**
  * Run docs command
  */

package/cli/utils/file-utils.js

@@ -247,6 +247,10 @@ export function resolveImportPath(fromFile, importPath) {
 
 /**
  * Parse CLI arguments into options and file patterns
+ * Supports:
+ * - Boolean flags: --verbose, -v
+ * - Value options: --dir /path, -d /path
+ * - Negation: --no-state
  * @param {string[]} args - Command line arguments
  * @returns {{ options: object, patterns: string[] }}
  */
@@ -254,15 +258,33 @@ export function parseArgs(args) {
   const options = {};
   const patterns = [];
 
+  // Options that take a value (not boolean)
+  const valueOptions = new Set([
+    'dir', 'd', 'output', 'o', 'type', 't', 'format', 'f', 'filter', 'timeout', 'title', 'from'
+  ]);
+
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
-    if (arg.startsWith('--')) {
+    if (arg.startsWith('--no-')) {
+      // Negation: --no-state -> state: false
+      const key = arg.slice(5);
+      options[key] = false;
+    } else if (arg.startsWith('--')) {
       const key = arg.slice(2);
-      // Boolean flags - don't consume next argument
-      options[key] = true;
+      // Check if this option takes a value
+      if (valueOptions.has(key) && i + 1 < args.length && !args[i + 1].startsWith('-')) {
+        options[key] = args[++i];
+      } else {
+        options[key] = true;
+      }
     } else if (arg.startsWith('-') && arg.length === 2) {
       const key = arg.slice(1);
-      options[key] = true;
+      // Check if this option takes a value
+      if (valueOptions.has(key) && i + 1 < args.length && !args[i + 1].startsWith('-')) {
+        options[key] = args[++i];
+      } else {
+        options[key] = true;
+      }
     } else {
       patterns.push(arg);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pulse-js-framework",
-  "version": "1.7.15",
+  "version": "1.7.17",
   "description": "A declarative DOM framework with CSS selector-based structure and reactive pulsations",
   "type": "module",
   "main": "index.js",
@@ -109,7 +109,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "npm run test:compiler && npm run test:sourcemap && npm run test:pulse && npm run test:dom && npm run test:dom-element && npm run test:dom-adapter && 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:lru-cache && npm run test:utils && npm run test:docs && npm run test:docs-nav && npm run test:async && 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:errors && npm run test:security && npm run test:websocket && npm run test:graphql && 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",
+    "test": "npm run test:compiler && npm run test:sourcemap && npm run test:pulse && npm run test:dom && npm run test:dom-element && npm run test:dom-adapter && 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:lru-cache && npm run test:utils && npm run test:docs && npm run test:docs-nav && npm run test:async && 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:errors && npm run test:security && npm run test:websocket && npm run test:graphql && 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",
     "test:compiler": "node test/compiler.test.js",
     "test:sourcemap": "node test/sourcemap.test.js",
     "test:pulse": "node test/pulse.test.js",
@@ -153,6 +153,7 @@
     "test:http-edge-cases": "node test/http-edge-cases.test.js",
     "test:integration-advanced": "node test/integration-advanced.test.js",
     "test:websocket-stress": "node test/websocket-stress.test.js",
+    "test:ssr": "node test/ssr.test.js",
     "build:netlify": "node scripts/build-netlify.js",
     "version": "node scripts/sync-version.js",
     "docs": "node cli/index.js dev docs"

package/runtime/async.js

@@ -7,6 +7,7 @@
  */
 
 import { pulse, effect, batch, onCleanup } from './pulse.js';
+import { getSSRAsyncContext, registerAsync, getCachedAsync, hasCachedAsync } from './ssr-async.js';
 
 // ============================================================================
 // Versioned Async - Centralized Race Condition Handling
@@ -328,6 +329,44 @@ export function useAsync(asyncFn, options = {}) {
     retryDelay = 1000
   } = options;
 
+  // SSR MODE: Check for cached data or register async operation
+  const ssrCtx = getSSRAsyncContext();
+  if (ssrCtx) {
+    // Check if we already have cached data (second render pass)
+    if (hasCachedAsync(asyncFn)) {
+      const cachedData = getCachedAsync(asyncFn);
+      return {
+        data: pulse(cachedData),
+        error: pulse(null),
+        loading: pulse(false),
+        status: pulse('success'),
+        execute: () => Promise.resolve(cachedData),
+        reset: () => {},
+        abort: () => {}
+      };
+    }
+
+    // First render pass: register async operation for collection
+    if (immediate) {
+      const promise = asyncFn().catch(err => {
+        // Store error for SSR error handling
+        return null;
+      });
+      registerAsync(asyncFn, promise);
+    }
+
+    // Return loading state for first pass
+    return {
+      data: pulse(initialData),
+      error: pulse(null),
+      loading: pulse(true),
+      status: pulse('loading'),
+      execute: () => Promise.resolve(initialData),
+      reset: () => {},
+      abort: () => {}
+    };
+  }
+
   const data = pulse(initialData);
   const error = pulse(null);
   const loading = pulse(false);

package/runtime/dom-element.js

@@ -10,6 +10,16 @@ import { loggers } from './logger.js';
 import { safeSetAttribute } from './utils.js';
 import { getAdapter } from './dom-adapter.js';
 import { parseSelector } from './dom-selector.js';
+import {
+  isHydratingMode,
+  getHydrationContext,
+  getCurrentNode,
+  advanceCursor,
+  enterChild,
+  exitChild,
+  registerListener,
+  warnMismatch
+} from './ssr-hydrator.js';
 
 const log = loggers.dom;
 
@@ -214,6 +224,62 @@ function applyRoleRequirements(element, role, attrs, dom) {
 export function el(selector, ...children) {
   const dom = getAdapter();
   const config = parseSelector(selector);
+
+  // HYDRATION MODE: Reuse existing DOM element
+  if (isHydratingMode()) {
+    const ctx = getHydrationContext();
+    const existing = getCurrentNode(ctx);
+
+    // Verify element matches
+    if (existing && existing.nodeType === 1) {
+      const tag = existing.tagName?.toLowerCase();
+      if (tag !== config.tag) {
+        warnMismatch(ctx, `<${config.tag}>`, existing);
+      }
+
+      // Process children to attach event handlers from attributes
+      const [attrs, childContent] = separateAttrsAndChildren(children);
+
+      if (attrs) {
+        // Attach event handlers to existing element
+        for (const [key, value] of Object.entries(attrs)) {
+          if (key.startsWith('on') && typeof value === 'function') {
+            const event = key.slice(2).toLowerCase();
+            registerListener(ctx, existing, event, value);
+          }
+          // Handle reactive attributes
+          else if (typeof value === 'function' && !key.startsWith('on')) {
+            effect(() => {
+              const result = value();
+              if (key === 'class' || key === 'className') {
+                existing.className = result || '';
+              } else if (key === 'style' && typeof result === 'string') {
+                existing.style.cssText = result;
+              } else if (result != null) {
+                existing.setAttribute(key, result);
+              } else {
+                existing.removeAttribute(key);
+              }
+            });
+          }
+        }
+      }
+
+      // Enter child scope and process children
+      enterChild(ctx, existing);
+      for (const child of childContent) {
+        hydrateChild(existing, child, ctx);
+      }
+      exitChild(ctx, existing);
+
+      return existing;
+    }
+
+    // No matching element found, warn and fall through to create
+    warnMismatch(ctx, `<${config.tag}>`, existing);
+  }
+
+  // NORMAL MODE: Create new element
   const element = dom.createElement(config.tag);
 
   if (config.id) {
@@ -240,6 +306,47 @@ export function el(selector, ...children) {
   return element;
 }
 
+/**
+ * Separate attributes object from children in el() arguments
+ * @private
+ */
+function separateAttrsAndChildren(children) {
+  if (children.length === 0) {
+    return [null, []];
+  }
+
+  const first = children[0];
+  if (first && typeof first === 'object' && !Array.isArray(first) &&
+      !(first instanceof Node) && !(first.nodeType)) {
+    return [first, children.slice(1)];
+  }
+
+  return [null, children];
+}
+
+/**
+ * Hydrate a child element (attach listeners without creating DOM)
+ * @private
+ */
+function hydrateChild(parent, child, ctx) {
+  if (child == null || child === false) return;
+
+  if (typeof child === 'string' || typeof child === 'number') {
+    // Text content - just advance cursor
+    advanceCursor(ctx);
+  } else if (typeof child === 'function') {
+    // Reactive child - set up effect but skip initial DOM creation
+    effect(() => {
+      child(); // Execute to track dependencies, but don't modify DOM on first run in hydration
+    });
+  } else if (Array.isArray(child)) {
+    for (const c of child) {
+      hydrateChild(parent, c, ctx);
+    }
+  }
+  // Node children are handled by recursive el() calls
+}
+
 /**
  * Append a child to an element, handling various types
  *

package/runtime/index.js

@@ -1,25 +1,89 @@
 /**
  * Pulse Runtime - Main exports
+ *
+ * Core modules are re-exported here for convenience.
+ * Development-only modules (devtools, hmr) should be imported directly
+ * from their respective paths to enable tree-shaking in production.
  */
 
+// Core reactivity
 export * from './pulse.js';
+
+// DOM creation and manipulation
 export * from './dom.js';
+
+// Routing
 export * from './router.js';
+
+// State management
 export * from './store.js';
-export * from './native.js';
-export * from './logger.js';
-export * from './a11y.js';
+
+// Context API
 export * from './context.js';
+
+// Async primitives (useAsync, useResource, usePolling)
+export * from './async.js';
+
+// Form handling (useForm, useField, validators)
+export * from './form.js';
+
+// HTTP client
+export * from './http.js';
+
+// WebSocket client
 export * from './websocket.js';
+
+// GraphQL client
 export * from './graphql.js';
 
+// Server-side rendering
+export * from './ssr.js';
+
+// Accessibility utilities
+export * from './a11y.js';
+
+// Native mobile bridge
+export * from './native.js';
+
+// Logging
+export * from './logger.js';
+
+// Security utilities (XSS prevention, URL sanitization)
+export * from './utils.js';
+
+// Error classes
+export * from './errors.js';
+
+// LRU Cache
+export * from './lru-cache.js';
+
+// DOM Adapter (for SSR/testing)
+export * from './dom-adapter.js';
+
+// Default exports for namespace imports
 export { default as PulseCore } from './pulse.js';
 export { default as PulseDOM } from './dom.js';
 export { default as PulseRouter } from './router.js';
 export { default as PulseStore } from './store.js';
-export { default as PulseNative } from './native.js';
-export { default as PulseLogger } from './logger.js';
-export { default as PulseA11y } from './a11y.js';
 export { default as PulseContext } from './context.js';
+export { default as PulseAsync } from './async.js';
+export { default as PulseForm } from './form.js';
+export { default as PulseHttp } from './http.js';
 export { default as PulseWebSocket } from './websocket.js';
 export { default as PulseGraphQL } from './graphql.js';
+export { default as PulseSSR } from './ssr.js';
+export { default as PulseA11y } from './a11y.js';
+export { default as PulseNative } from './native.js';
+export { default as PulseLogger } from './logger.js';
+
+// Note: The following modules are intentionally NOT re-exported here
+// to enable tree-shaking. Import them directly when needed:
+//
+// Development tools (adds overhead, use only in dev):
+//   import { enableDevTools, trackedPulse } from 'pulse-js-framework/runtime/devtools';
+//
+// HMR utilities (Vite/webpack integration):
+//   import { createHMRContext } from 'pulse-js-framework/runtime/hmr';
+//
+// Lite build (minimal ~5KB bundle):
+//   import { pulse, effect, el, mount } from 'pulse-js-framework/runtime/lite';

package/runtime/pulse.js

@@ -23,6 +23,35 @@ import { Errors } from './errors.js';
 
 const log = loggers.pulse;
 
+// =============================================================================
+// SSR MODE FLAG
+// =============================================================================
+
+/**
+ * SSR mode flag - when true, effects run once without setting up subscriptions.
+ * This is set by the SSR module during server-side rendering.
+ * @type {boolean}
+ */
+let ssrModeEnabled = false;
+
+/**
+ * Check if SSR mode is enabled.
+ * In SSR mode, effects run once but don't subscribe to changes.
+ * @returns {boolean}
+ */
+export function isSSRMode() {
+  return ssrModeEnabled;
+}
+
+/**
+ * Set SSR mode (used internally by ssr.js).
+ * @param {boolean} enabled - Whether to enable SSR mode
+ * @internal
+ */
+export function setSSRMode(enabled) {
+  ssrModeEnabled = enabled;
+}
+
 // =============================================================================
 // REACTIVE DEPENDENCY TRACKING ALGORITHM
 // =============================================================================
@@ -885,6 +914,17 @@ export function effect(fn, options = {}) {
   const { id: customId, onError } = options;
   const effectId = customId || `effect_${++effectIdCounter}`;
 
+  // SSR MODE: Run effect once without subscriptions
+  if (ssrModeEnabled) {
+    try {
+      fn();
+    } catch (e) {
+      log.warn(`SSR effect error (${effectId}):`, e.message);
+    }
+    // Return noop cleanup function
+    return () => {};
+  }
+
   // Capture module ID at creation time for HMR tracking
   const moduleId = activeContext.currentModuleId;