pulse-js-framework 1.7.15 → 1.7.16

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);
@@ -136,10 +137,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 +175,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);
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pulse-js-framework",
-  "version": "1.7.15",
+  "version": "1.7.16",
   "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

@@ -12,6 +12,7 @@ export * from './a11y.js';
 export * from './context.js';
 export * from './websocket.js';
 export * from './graphql.js';
+export * from './ssr.js';
 
 export { default as PulseCore } from './pulse.js';
 export { default as PulseDOM } from './dom.js';
@@ -23,3 +24,4 @@ export { default as PulseA11y } from './a11y.js';
 export { default as PulseContext } from './context.js';
 export { default as PulseWebSocket } from './websocket.js';
 export { default as PulseGraphQL } from './graphql.js';
+export { default as PulseSSR } from './ssr.js';

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;
 

package/runtime/ssr-async.js

@@ -0,0 +1,229 @@
+/**
+ * Pulse SSR Async Context - Async operation collection for SSR
+ *
+ * Collects and manages async operations during server-side rendering.
+ * Enables data prefetching before HTML generation.
+ */
+
+// ============================================================================
+// SSR Async Context
+// ============================================================================
+
+/**
+ * Context for collecting async operations during SSR.
+ * Tracks pending promises and caches resolved data for re-renders.
+ */
+export class SSRAsyncContext {
+  constructor() {
+    /** @type {Array<{key: any, promise: Promise}>} */
+    this.pending = [];
+
+    /** @type {Map<any, any>} */
+    this.resolved = new Map();
+
+    /** @type {Map<any, Error>} */
+    this.errors = new Map();
+
+    /** @type {boolean} */
+    this.collecting = true;
+  }
+
+  /**
+   * Register an async operation for collection.
+   * @param {any} key - Unique key for this operation (usually the async function)
+   * @param {Promise} promise - The promise to track
+   */
+  register(key, promise) {
+    if (!this.collecting) return;
+
+    // Wrap promise to capture result
+    const tracked = promise
+      .then(data => {
+        this.resolved.set(key, data);
+        return data;
+      })
+      .catch(error => {
+        this.errors.set(key, error);
+        throw error;
+      });
+
+    this.pending.push({ key, promise: tracked });
+  }
+
+  /**
+   * Check if a result is already cached.
+   * @param {any} key - Operation key
+   * @returns {boolean} True if result is cached
+   */
+  has(key) {
+    return this.resolved.has(key);
+  }
+
+  /**
+   * Get cached result for a key.
+   * @param {any} key - Operation key
+   * @returns {any} Cached result or undefined
+   */
+  get(key) {
+    return this.resolved.get(key);
+  }
+
+  /**
+   * Get error for a key (if the operation failed).
+   * @param {any} key - Operation key
+   * @returns {Error|undefined} Error or undefined
+   */
+  getError(key) {
+    return this.errors.get(key);
+  }
+
+  /**
+   * Wait for all pending async operations to complete.
+   * @param {number} [timeout=5000] - Maximum wait time in ms
+   * @returns {Promise<void>}
+   * @throws {Error} If timeout is exceeded
+   */
+  async waitAll(timeout = 5000) {
+    if (this.pending.length === 0) return;
+
+    const timeoutPromise = new Promise((_, reject) => {
+      setTimeout(() => {
+        reject(new Error(`[Pulse SSR] Async operations timed out after ${timeout}ms`));
+      }, timeout);
+    });
+
+    // Wait for all promises, catching individual errors
+    const allSettled = Promise.all(
+      this.pending.map(p => p.promise.catch(() => null))
+    );
+
+    await Promise.race([allSettled, timeoutPromise]);
+
+    // Stop collecting after wait
+    this.collecting = false;
+  }
+
+  /**
+   * Get the number of pending operations.
+   * @returns {number}
+   */
+  get pendingCount() {
+    return this.pending.length;
+  }
+
+  /**
+   * Get the number of resolved operations.
+   * @returns {number}
+   */
+  get resolvedCount() {
+    return this.resolved.size;
+  }
+
+  /**
+   * Get the number of failed operations.
+   * @returns {number}
+   */
+  get errorCount() {
+    return this.errors.size;
+  }
+
+  /**
+   * Get all resolved data as a plain object.
+   * @returns {Object} Map of key → value
+   */
+  getAllResolved() {
+    const result = {};
+    for (const [key, value] of this.resolved) {
+      // Use string key if function, otherwise try to serialize
+      const keyStr = typeof key === 'function' ? key.name || 'anonymous' : String(key);
+      result[keyStr] = value;
+    }
+    return result;
+  }
+
+  /**
+   * Reset the context for a new render pass.
+   */
+  reset() {
+    this.pending = [];
+    this.resolved.clear();
+    this.errors.clear();
+    this.collecting = true;
+  }
+}
+
+// ============================================================================
+// Global SSR Async Context
+// ============================================================================
+
+/** @type {SSRAsyncContext|null} */
+let ssrAsyncContext = null;
+
+/**
+ * Get the current SSR async context.
+ * Returns null if not in SSR mode.
+ * @returns {SSRAsyncContext|null}
+ */
+export function getSSRAsyncContext() {
+  return ssrAsyncContext;
+}
+
+/**
+ * Set the SSR async context.
+ * @param {SSRAsyncContext|null} ctx - Context to set, or null to clear
+ */
+export function setSSRAsyncContext(ctx) {
+  ssrAsyncContext = ctx;
+}
+
+/**
+ * Check if currently in SSR async collection mode.
+ * @returns {boolean}
+ */
+export function isCollectingAsync() {
+  return ssrAsyncContext !== null && ssrAsyncContext.collecting;
+}
+
+/**
+ * Register an async operation in the current SSR context.
+ * No-op if not in SSR mode.
+ * @param {any} key - Unique key for this operation
+ * @param {Promise} promise - The promise to track
+ */
+export function registerAsync(key, promise) {
+  if (ssrAsyncContext) {
+    ssrAsyncContext.register(key, promise);
+  }
+}
+
+/**
+ * Get cached async result from current SSR context.
+ * @param {any} key - Operation key
+ * @returns {any} Cached result or undefined
+ */
+export function getCachedAsync(key) {
+  return ssrAsyncContext?.get(key);
+}
+
+/**
+ * Check if an async result is cached in current SSR context.
+ * @param {any} key - Operation key
+ * @returns {boolean}
+ */
+export function hasCachedAsync(key) {
+  return ssrAsyncContext?.has(key) ?? false;
+}
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export default {
+  SSRAsyncContext,
+  getSSRAsyncContext,
+  setSSRAsyncContext,
+  isCollectingAsync,
+  registerAsync,
+  getCachedAsync,
+  hasCachedAsync
+};