pulse-js-framework 1.7.30 → 1.7.31

package/cli/index.js

@@ -15,8 +15,14 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
 // Version - read dynamically from package.json
-const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
-const VERSION = pkg.version;
+let VERSION = '0.0.0';
+try {
+  const pkgContent = readFileSync(join(__dirname, '..', 'package.json'), 'utf-8');
+  const pkg = JSON.parse(pkgContent);
+  VERSION = pkg.version || VERSION;
+} catch (err) {
+  log.warn(`Could not read package.json: ${err.message}`);
+}
 
 // Available example templates
 const TEMPLATES = {
@@ -683,10 +689,19 @@ async function initProject(args) {
 
   if (existsSync(pkgPath)) {
     try {
-      pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
-      log.info('Found existing package.json, merging...');
+      const pkgContent = readFileSync(pkgPath, 'utf-8');
+      if (!pkgContent.trim()) {
+        log.warn('Existing package.json is empty, creating new one.');
+      } else {
+        pkg = JSON.parse(pkgContent);
+        log.info('Found existing package.json, merging...');
+      }
     } catch (e) {
-      log.warn('Could not parse existing package.json, creating new one.');
+      if (e instanceof SyntaxError) {
+        log.warn(`Invalid JSON in package.json: ${e.message}. Creating new one.`);
+      } else {
+        log.warn(`Could not read package.json: ${e.message}. Creating new one.`);
+      }
     }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pulse-js-framework",
-  "version": "1.7.30",
+  "version": "1.7.31",
   "description": "A declarative DOM framework with CSS selector-based structure and reactive pulsations",
   "type": "module",
   "main": "index.js",
@@ -109,14 +109,19 @@
     "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-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:cli-create && 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": "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:compiler": "node test/compiler.test.js",
     "test:sourcemap": "node test/sourcemap.test.js",
     "test:css-parsing": "node test/css-parsing.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",
+    "test:dom-list": "node test/dom-list.test.js",
+    "test:dom-conditional": "node test/dom-conditional.test.js",
+    "test:dom-lifecycle": "node test/dom-lifecycle.test.js",
+    "test:dom-selector": "node test/dom-selector.test.js",
     "test:dom-adapter": "node test/dom-adapter.test.js",
+    "test:dom-advanced": "node test/dom-advanced.test.js",
     "test:enhanced-mock-adapter": "node test/enhanced-mock-adapter.test.js",
     "test:router": "node test/router.test.js",
     "test:store": "node test/store.test.js",
@@ -130,9 +135,11 @@
     "test:cli-create": "node test/cli-create.test.js",
     "test:lru-cache": "node test/lru-cache.test.js",
     "test:utils": "node test/utils.test.js",
+    "test:utils-coverage": "node test/utils-coverage.test.js",
     "test:docs": "node test/docs.test.js",
     "test:docs-nav": "node test/docs-navigation.test.js",
     "test:async": "node test/async.test.js",
+    "test:async-coverage": "node test/async-coverage.test.js",
     "test:form": "node test/form.test.js",
     "test:http": "node test/http.test.js",
     "test:devtools": "node test/devtools.test.js",
@@ -140,10 +147,12 @@
     "test:a11y": "node test/a11y.test.js",
     "test:a11y-enhanced": "node test/a11y-enhanced.test.js",
     "test:logger": "node test/logger.test.js",
+    "test:logger-prod": "node test/logger-prod.test.js",
     "test:errors": "node test/errors.test.js",
     "test:security": "node test/security.test.js",
     "test:websocket": "node test/websocket.test.js",
     "test:graphql": "node test/graphql.test.js",
+    "test:graphql-coverage": "node test/graphql-coverage.test.js",
     "test:doctor": "node test/doctor.test.js",
     "test:scaffold": "node test/scaffold.test.js",
     "test:test-runner": "node test/test-runner.test.js",
@@ -156,6 +165,7 @@
     "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",
+    "test:ssr-hydrator": "node test/ssr-hydrator.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

@@ -8,6 +8,7 @@
 
 import { pulse, effect, batch, onCleanup } from './pulse.js';
 import { getSSRAsyncContext, registerAsync, getCachedAsync, hasCachedAsync } from './ssr-async.js';
+import { onWindowFocus, onWindowOnline, onNetworkChange } from './utils.js';
 
 // ============================================================================
 // Versioned Async - Centralized Race Condition Handling
@@ -694,26 +695,18 @@ export function useResource(key, fetcher, options = {}) {
   }
 
   // Setup window focus listener
-  if (refreshOnFocus && typeof window !== 'undefined') {
-    const handleFocus = () => {
+  if (refreshOnFocus) {
+    onWindowFocus(() => {
       const cached = getCachedData();
       if (!cached || cached.isStale) {
         fetch();
       }
-    };
-
-    window.addEventListener('focus', handleFocus);
-    onCleanup(() => window.removeEventListener('focus', handleFocus));
+    }, onCleanup);
   }
 
   // Setup online listener
-  if (refreshOnReconnect && typeof window !== 'undefined') {
-    const handleOnline = () => {
-      fetch();
-    };
-
-    window.addEventListener('online', handleOnline);
-    onCleanup(() => window.removeEventListener('online', handleOnline));
+  if (refreshOnReconnect) {
+    onWindowOnline(() => fetch(), onCleanup);
   }
 
   // Track current key for change detection
@@ -868,19 +861,14 @@ export function usePolling(asyncFn, options) {
   }
 
   // Online/offline handling
-  if (pauseOnOffline && typeof window !== 'undefined') {
-    const handleOffline = () => pause();
-    const handleOnline = () => {
-      resume();
-      if (isPolling.get()) poll();
-    };
-
-    window.addEventListener('offline', handleOffline);
-    window.addEventListener('online', handleOnline);
-    onCleanup(() => {
-      window.removeEventListener('offline', handleOffline);
-      window.removeEventListener('online', handleOnline);
-    });
+  if (pauseOnOffline) {
+    onNetworkChange({
+      onOffline: () => pause(),
+      onOnline: () => {
+        resume();
+        if (isPolling.get()) poll();
+      }
+    }, onCleanup);
   }
 
   // Cleanup on unmount

package/runtime/devtools/diagnostics.js

@@ -29,7 +29,9 @@ export const config = {
   logUpdates: false,
   logEffects: false,
   warnOnSlowEffects: true,
-  slowEffectThreshold: 16 // ms (one frame at 60fps)
+  slowEffectThreshold: 16, // ms (one frame at 60fps)
+  autoTimeline: false, // Automatically record all pulse changes to timeline
+  timelineDebounce: 100 // Debounce interval for timeline recording (ms)
 };
 
 // =============================================================================
@@ -51,6 +53,46 @@ export const effectRegistry = new Map();
 let pulseIdCounter = 0;
 let trackedEffectIdCounter = 0;
 
+// Timeline auto-recording state
+let timelineDebounceTimer = null;
+let pendingTimelineActions = [];
+let takeSnapshotFn = null;
+
+/**
+ * Set the snapshot function for auto-timeline
+ * Called by devtools.js to wire up time-travel
+ * @param {Function} fn - takeSnapshot function
+ */
+export function _setTakeSnapshotFn(fn) {
+  takeSnapshotFn = fn;
+}
+
+/**
+ * Schedule a timeline snapshot (debounced)
+ * @param {string} action - Description of the action
+ */
+function scheduleTimelineSnapshot(action) {
+  if (!config.autoTimeline || !takeSnapshotFn) return;
+
+  pendingTimelineActions.push(action);
+
+  if (timelineDebounceTimer) {
+    clearTimeout(timelineDebounceTimer);
+  }
+
+  timelineDebounceTimer = setTimeout(() => {
+    timelineDebounceTimer = null;
+    if (pendingTimelineActions.length > 0) {
+      // Combine multiple actions into one snapshot
+      const combinedAction = pendingTimelineActions.length === 1
+        ? pendingTimelineActions[0]
+        : `${pendingTimelineActions.length} changes: ${pendingTimelineActions.slice(0, 3).join(', ')}${pendingTimelineActions.length > 3 ? '...' : ''}`;
+      pendingTimelineActions = [];
+      takeSnapshotFn(combinedAction);
+    }
+  }, config.timelineDebounce);
+}
+
 // =============================================================================
 // DIAGNOSTICS API
 // =============================================================================
@@ -267,9 +309,14 @@ export function trackedPulse(initialValue, name, options = {}) {
     if (config.enabled && config.logUpdates) {
       log.info(`${name || id} updated:`, value);
     }
-    if (config.enabled && options.onSnapshot) {
+    // Manual snapshot callback (for non-auto mode)
+    if (config.enabled && options.onSnapshot && !config.autoTimeline) {
       options.onSnapshot(`${name || id} = ${JSON.stringify(value)}`);
     }
+    // Auto-timeline recording (debounced)
+    if (config.enabled && config.autoTimeline) {
+      scheduleTimelineSnapshot(`${name || id} = ${JSON.stringify(value)}`);
+    }
     return result;
   };
 
@@ -399,5 +446,6 @@ export default {
   mark,
   resetDiagnostics,
   pulseRegistry,
-  effectRegistry
+  effectRegistry,
+  _setTakeSnapshotFn
 };

package/runtime/devtools.js

@@ -31,7 +31,8 @@ import {
   profile,
   mark,
   resetDiagnostics,
-  _setSnapshotCountFn
+  _setSnapshotCountFn,
+  _setTakeSnapshotFn
 } from './devtools/diagnostics.js';
 
 import {
@@ -50,6 +51,9 @@ import {
 // Wire up snapshot count for diagnostics
 _setSnapshotCountFn(getSnapshotCount);
 
+// Wire up takeSnapshot for auto-timeline
+_setTakeSnapshotFn(takeSnapshot);
+
 import {
   a11yAuditConfig,
   runA11yAudit,
@@ -88,9 +92,41 @@ export function trackedPulse(initialValue, name) {
 // DEV TOOLS API
 // =============================================================================
 
+/**
+ * Enable automatic timeline recording
+ * Records all pulse changes to the timeline automatically (debounced)
+ * @param {Object} [options] - Configuration options
+ * @param {number} [options.debounce=100] - Debounce interval in ms
+ */
+export function enableAutoTimeline(options = {}) {
+  config.autoTimeline = true;
+  if (options.debounce !== undefined) {
+    config.timelineDebounce = options.debounce;
+  }
+  log.info(`Auto-timeline enabled (debounce: ${config.timelineDebounce}ms)`);
+}
+
+/**
+ * Disable automatic timeline recording
+ */
+export function disableAutoTimeline() {
+  config.autoTimeline = false;
+  log.info('Auto-timeline disabled');
+}
+
+/**
+ * Check if auto-timeline is enabled
+ * @returns {boolean}
+ */
+export function isAutoTimelineEnabled() {
+  return config.autoTimeline;
+}
+
 /**
  * Enable dev tools
  * @param {Object} [options] - Configuration options
+ * @param {boolean} [options.autoTimeline] - Enable automatic timeline recording
+ * @param {number} [options.timelineDebounce] - Debounce interval for timeline (ms)
  */
 export function enableDevTools(options = {}) {
   Object.assign(config, options, { enabled: true });
@@ -99,6 +135,14 @@ export function enableDevTools(options = {}) {
     timeTravelConfig.maxSnapshots = options.maxSnapshots;
   }
 
+  // Enable auto-timeline if specified
+  if (options.autoTimeline) {
+    config.autoTimeline = true;
+    if (options.timelineDebounce !== undefined) {
+      config.timelineDebounce = options.timelineDebounce;
+    }
+  }
+
   if (typeof window !== 'undefined') {
     // Expose to window for browser dev tools
     window.__PULSE_DEVTOOLS__ = {
@@ -119,6 +163,11 @@ export function enableDevTools(options = {}) {
       forward,
       clearHistory,
 
+      // Auto-timeline
+      enableAutoTimeline,
+      disableAutoTimeline,
+      isAutoTimelineEnabled,
+
       // A11y Audit
       runA11yAudit,
       getA11yIssues,
@@ -216,6 +265,9 @@ export {
   resetA11yAudit
 };
 
+// Note: enableAutoTimeline, disableAutoTimeline, isAutoTimelineEnabled
+// are already exported via their function declarations above
+
 // =============================================================================
 // DEFAULT EXPORT
 // =============================================================================
@@ -241,6 +293,11 @@ export default {
   forward,
   clearHistory,
 
+  // Auto-timeline
+  enableAutoTimeline,
+  disableAutoTimeline,
+  isAutoTimelineEnabled,
+
   // Configuration
   enableDevTools,
   disableDevTools,

package/runtime/errors.js

@@ -217,6 +217,163 @@ export class RouterError extends RuntimeError {
   }
 }
 
+// ============================================================================
+// Client Errors (HTTP, WebSocket, GraphQL)
+// ============================================================================
+
+/**
+ * Base class for client errors (HTTP, WebSocket, GraphQL).
+ * Provides common patterns for error creation with suggestions.
+ *
+ * @example
+ * class HttpError extends ClientError {
+ *   static suggestions = { TIMEOUT: 'Increase timeout...' };
+ *   static errorName = 'HttpError';
+ *   static defaultCode = 'HTTP_ERROR';
+ *   static markerProperty = 'isHttpError';
+ * }
+ */
+export class ClientError extends RuntimeError {
+  /** @type {Object<string, string>} Error code to suggestion mapping */
+  static suggestions = {};
+
+  /** @type {string} The error class name */
+  static errorName = 'ClientError';
+
+  /** @type {string} Default error code when none provided */
+  static defaultCode = 'CLIENT_ERROR';
+
+  /** @type {string} Property name for instance type checking (e.g., 'isHttpError') */
+  static markerProperty = 'isClientError';
+
+  /**
+   * @param {string} message - Error message
+   * @param {Object} [options={}] - Error options
+   * @param {string} [options.code] - Error code
+   * @param {string} [options.context] - Error context
+   * @param {string} [options.suggestion] - Custom suggestion (overrides default)
+   */
+  constructor(message, options = {}) {
+    const code = options.code || new.target.defaultCode;
+    const suggestion = options.suggestion || new.target.suggestions[code];
+
+    const formattedMessage = createErrorMessage({
+      code,
+      message,
+      context: options.context,
+      suggestion
+    });
+
+    super(formattedMessage, { code });
+
+    this.name = new.target.errorName;
+    this.code = code;
+    this[new.target.markerProperty] = true;
+  }
+
+  /**
+   * Check if an error is an instance of this error type
+   * @param {any} error - The error to check
+   * @returns {boolean}
+   */
+  static isError(error) {
+    return error?.[this.markerProperty] === true;
+  }
+
+  /**
+   * Check if this is a timeout error
+   * @returns {boolean}
+   */
+  isTimeout() {
+    return this.code === 'TIMEOUT';
+  }
+
+  /**
+   * Check if this is a network error
+   * @returns {boolean}
+   */
+  isNetworkError() {
+    return this.code === 'NETWORK' || this.code === 'NETWORK_ERROR';
+  }
+}
+
+/**
+ * Factory to create a client error class with specific suggestions and properties.
+ *
+ * @param {Object} config - Error class configuration
+ * @param {string} config.name - Error class name (e.g., 'HttpError')
+ * @param {string} config.defaultCode - Default error code
+ * @param {string} config.markerProperty - Instance marker property (e.g., 'isHttpError')
+ * @param {Object<string, string>} config.suggestions - Error code to suggestion mapping
+ * @param {string[]} [config.codeMethods] - Error codes to create isXxx() methods for
+ * @param {string[]} [config.additionalProperties] - Extra properties to copy from options
+ * @returns {typeof ClientError} The created error class
+ *
+ * @example
+ * const HttpError = createClientErrorClass({
+ *   name: 'HttpError',
+ *   defaultCode: 'HTTP_ERROR',
+ *   markerProperty: 'isHttpError',
+ *   suggestions: {
+ *     TIMEOUT: 'Consider increasing the timeout.',
+ *     NETWORK: 'Check internet connectivity.'
+ *   },
+ *   codeMethods: ['TIMEOUT', 'NETWORK', 'ABORT'],
+ *   additionalProperties: ['config', 'request', 'response', 'status']
+ * });
+ */
+export function createClientErrorClass(config) {
+  const {
+    name,
+    defaultCode,
+    markerProperty,
+    suggestions = {},
+    codeMethods = [],
+    additionalProperties = []
+  } = config;
+
+  class CustomClientError extends ClientError {
+    static suggestions = suggestions;
+    static errorName = name;
+    static defaultCode = defaultCode;
+    static markerProperty = markerProperty;
+
+    constructor(message, options = {}) {
+      super(message, options);
+
+      // Copy additional properties from options
+      for (const prop of additionalProperties) {
+        this[prop] = options[prop] ?? null;
+      }
+    }
+
+    /**
+     * Static type check method (e.g., HttpError.isHttpError(err))
+     */
+    static [`is${name}`](error) {
+      return error?.[markerProperty] === true;
+    }
+  }
+
+  // Add isXxx() methods for each code
+  for (const code of codeMethods) {
+    const methodName = 'is' + code.split('_').map(
+      (part, i) => i === 0
+        ? part.charAt(0).toUpperCase() + part.slice(1).toLowerCase()
+        : part.charAt(0).toUpperCase() + part.slice(1).toLowerCase()
+    ).join('');
+
+    CustomClientError.prototype[methodName] = function () {
+      return this.code === code;
+    };
+  }
+
+  // Set the class name for better debugging
+  Object.defineProperty(CustomClientError, 'name', { value: name });
+
+  return CustomClientError;
+}
+
 // ============================================================================
 // CLI Errors
 // ============================================================================
@@ -564,6 +721,8 @@ export default {
   DOMError,
   StoreError,
   RouterError,
+  ClientError,
+  createClientErrorClass,
   CLIError,
   ConfigError,
   SUGGESTIONS,