pulse-js-framework 1.10.4 → 1.11.1

package/runtime/context.js

@@ -72,6 +72,13 @@ const contextDefaults = new Map();
  */
 const contextNames = new Map();
 
+/**
+ * Shared default pulses for contexts without providers
+ * Uses a Map keyed by context symbol ID (since context objects are frozen)
+ * @type {Map<symbol, Pulse>}
+ */
+const contextDefaultPulses = new Map();
+
 // =============================================================================
 // CONTEXT CREATION
 // =============================================================================
@@ -235,12 +242,17 @@ export function useContext(context) {
     return value;
   }
 
-  // No provider found, return default as reactive pulse
+  // No provider found, return shared default as reactive pulse
   log.debug(`useContext: using default for ${context.displayName}`);
   const defaultVal = contextDefaults.get(context._id);
 
-  // Wrap default in pulse for consistent API
-  return isPulse(defaultVal) ? defaultVal : pulse(defaultVal);
+  // Lazily create a shared default pulse so all consumers without a Provider
+  // share the same reactive instance (avoids creating a new pulse per call)
+  if (isPulse(defaultVal)) return defaultVal;
+  if (!contextDefaultPulses.has(context._id)) {
+    contextDefaultPulses.set(context._id, pulse(defaultVal));
+  }
+  return contextDefaultPulses.get(context._id);
 }
 
 /**
@@ -305,6 +317,7 @@ export function disposeContext(context) {
   contextStacks.delete(context._id);
   contextDefaults.delete(context._id);
   contextNames.delete(context._id);
+  contextDefaultPulses.delete(context._id);
 
   log.debug(`Context disposed: ${context.displayName}`);
 }

package/runtime/dom-adapter.js

@@ -10,6 +10,8 @@
  * allowing the same reactive code to run in Node.js, Deno, or custom environments.
  */
 
+import { DOMError } from './errors.js';
+
 // ============================================================================
 // DOM Adapter Interface
 // ============================================================================
@@ -845,9 +847,9 @@ export function getAdapter() {
     if (typeof document !== 'undefined') {
       activeAdapter = new BrowserDOMAdapter();
     } else {
-      throw new Error(
-        '[Pulse] No DOM adapter configured. ' +
-        'In non-browser environments, call setAdapter() with a MockDOMAdapter or custom implementation.'
+      throw new DOMError(
+        'No DOM adapter configured',
+        { code: 'DOM_ADAPTER_MISSING', suggestion: 'In non-browser environments, call setAdapter() with a MockDOMAdapter or custom implementation.' }
       );
     }
   }

package/runtime/dom-virtual-list.js

@@ -13,6 +13,7 @@ import { pulse, effect, computed, batch } from './pulse.js';
 import { getAdapter } from './dom-adapter.js';
 import { list } from './dom-list.js';
 import { delegate } from './dom-event-delegate.js';
+import { DOMError } from './errors.js';
 
 // ============================================================================
 // Constants
@@ -57,7 +58,7 @@ export function virtualList(getItems, template, keyFn, options = {}) {
   const { itemHeight, overscan, containerHeight, recycle, on: eventHandlers } = config;
 
   if (!itemHeight || itemHeight <= 0) {
-    throw new Error('[Pulse] virtualList requires a positive itemHeight');
+    throw new DOMError('virtualList requires a positive itemHeight', { code: 'INVALID_ITEM_HEIGHT', suggestion: 'Provide options.itemHeight as a positive number' });
   }
 
   const dom = getAdapter();

package/runtime/form.js

@@ -40,6 +40,7 @@ function isLocalStorageAvailable() {
   try {
     return typeof localStorage !== 'undefined' && localStorage !== null;
   } catch {
+    // localStorage may throw in private browsing or restricted environments
     return false;
   }
 }
@@ -113,6 +114,7 @@ export const validators = {
         new URL(value);
         return true;
       } catch {
+        // URL constructor throws on invalid URLs — treat as validation failure
         return message;
       }
     }
@@ -641,6 +643,7 @@ export function useForm(initialValues, validationSchema = {}, options = {}) {
     try {
       return localStorage.getItem(persistKey) !== null;
     } catch {
+      // localStorage may be unavailable (private browsing, quota exceeded)
       return false;
     }
   })());
@@ -853,7 +856,7 @@ export function useForm(initialValues, validationSchema = {}, options = {}) {
       try {
         localStorage.removeItem(persistKey);
       } catch {
-        // Ignore
+        // localStorage may throw if storage is restricted; safe to ignore on cleanup
       }
     }
     hasDraft.set(false);
@@ -1616,15 +1619,17 @@ export function useFileField(options = {}) {
     // Revoke removed preview URL
     if (preview && canCreateObjectURL()) {
       const currentPreviews = previews.get();
+      // Revoke the URL at this file index (may be null for non-image files)
       if (currentPreviews[index]) {
         try {
           URL.revokeObjectURL(currentPreviews[index]);
         } catch {
-          // Ignore
+          // Object URL may already be revoked; safe to ignore
         }
       }
       const newPreviews = currentPreviews.filter((_, i) => i !== index);
-      previewUrls = previewUrls.filter((_, i) => i !== index);
+      // Rebuild previewUrls from the filtered previews to avoid index mismatch
+      previewUrls = newPreviews.filter(Boolean);
       previews.set(newPreviews);
     }
 

package/runtime/graphql/cache.js

@@ -50,7 +50,7 @@ function stableStringify(obj) {
     return '[' + obj.map(stableStringify).join(',') + ']';
   }
   const keys = Object.keys(obj).sort();
-  return '{' + keys.map(k => `"${k}":${stableStringify(obj[k])}`).join(',') + '}';
+  return '{' + keys.map(k => `${JSON.stringify(k)}:${stableStringify(obj[k])}`).join(',') + '}';
 }
 
 /**

package/runtime/graphql/client.js

@@ -8,6 +8,8 @@
 
 import { pulse, computed, batch } from '../pulse.js';
 import { createHttp, HttpError } from '../http.js';
+import { createWebSocket } from '../websocket.js';
+import { SubscriptionManager } from './subscriptions.js';
 import { ClientError } from '../errors.js';
 import { LRUCache } from '../lru-cache.js';
 import { InterceptorManager } from '../interceptor-manager.js';
@@ -370,12 +372,32 @@ export class GraphQLClient {
   async query(query, variables, options = {}) {
     const cacheKey = options.cacheKey || generateCacheKey(query, variables);
 
+    // Check LRU cache first (if caching is enabled and not explicitly skipped)
+    if (this.#options.cache && !options.skipCache) {
+      const cached = this.#cache.get(cacheKey);
+      if (cached) {
+        const age = Date.now() - cached.timestamp;
+        if (age < this.#options.cacheTime) {
+          return cached.data;
+        }
+        // Stale entry — remove it
+        this.#cache.delete(cacheKey);
+      }
+    }
+
     // Check for in-flight request (deduplication)
     if (this.#options.dedupe && this.#inflightQueries.has(cacheKey)) {
       return this.#inflightQueries.get(cacheKey);
     }
 
     const promise = this.#execute(query, variables, options)
+      .then((data) => {
+        // Populate cache on successful query
+        if (this.#options.cache) {
+          this.#cache.set(cacheKey, { data, timestamp: Date.now() });
+        }
+        return data;
+      })
       .finally(() => {
         this.#inflightQueries.delete(cacheKey);
       });

package/runtime/graphql/hooks.js

@@ -102,7 +102,7 @@ export function useQuery(query, variables, options = {}) {
   const versionController = createVersionedAsync();
 
   // Execute query
-  async function executeQuery() {
+  async function executeQuery(queryOptions = {}) {
     if (!isEnabled()) return null;
 
     const ctx = versionController.begin();
@@ -117,7 +117,8 @@ export function useQuery(query, variables, options = {}) {
 
     try {
       const result = await client.query(query, resolveVariables(), {
-        cacheKey: getCacheKey()
+        cacheKey: getCacheKey(),
+        ...queryOptions
       });
 
       const selectedData = options.select ? options.select(result) : result;
@@ -160,7 +161,7 @@ export function useQuery(query, variables, options = {}) {
   if (options.refetchInterval && options.refetchInterval > 0) {
     const intervalId = setInterval(() => {
       if (!loading.get() && !fetching.get() && isEnabled()) {
-        executeQuery();
+        executeQuery({ skipCache: true });
       }
     }, options.refetchInterval);
 
@@ -169,12 +170,12 @@ export function useQuery(query, variables, options = {}) {
 
   // Setup window focus listener
   if (options.refetchOnFocus) {
-    onWindowFocus(() => { if (isEnabled()) executeQuery(); }, onCleanup);
+    onWindowFocus(() => { if (isEnabled()) executeQuery({ skipCache: true }); }, onCleanup);
   }
 
   // Setup online listener
   if (options.refetchOnReconnect) {
-    onWindowOnline(() => { if (isEnabled()) executeQuery(); }, onCleanup);
+    onWindowOnline(() => { if (isEnabled()) executeQuery({ skipCache: true }); }, onCleanup);
   }
 
   return {
@@ -189,7 +190,7 @@ export function useQuery(query, variables, options = {}) {
       return 'idle';
     }),
     isStale,
-    refetch: executeQuery,
+    refetch: () => executeQuery({ skipCache: true }),
     invalidate: () => {
       isStale.set(true);
       client.invalidate(getCacheKey());
@@ -411,7 +412,12 @@ export function useSubscription(subscription, variables, options = {}) {
         if (options.shouldResubscribe !== false) {
           const currentRetry = retryCount.peek();
           if (currentRetry < maxRetries) {
+            // Send Complete to server before abandoning the old subscription
+            const oldUnsubscribe = unsubscribeFn;
             unsubscribeFn = null;
+            if (oldUnsubscribe) {
+              try { oldUnsubscribe(); } catch { /* connection may already be closed */ }
+            }
             const delay = calculateBackoffDelay(currentRetry);
             retryCount.set(currentRetry + 1);
             status.set('reconnecting');

package/runtime/graphql/subscriptions.js

@@ -98,6 +98,8 @@ export class SubscriptionManager {
         code: 'SUBSCRIPTION_ERROR'
       }));
     }
+    // Clear stale entries to prevent accumulation on reconnect
+    this.#subscriptions.clear();
   }
 
   /**

package/runtime/hmr.js

@@ -56,12 +56,15 @@ import { setCurrentModule, clearCurrentModule, disposeModule } from './pulse.js'
  */
 export function createHMRContext(moduleId) {
   // Check if HMR is available (Vite dev server)
-  if (typeof import.meta === 'undefined' || !import.meta.hot) {
+  // import.meta.hot is injected by Vite at build time
+  // Also check globalThis.__PULSE_HMR_HOT__ for testing purposes
+  const hot = (typeof import.meta !== 'undefined' && import.meta.hot) ||
+              (typeof globalThis !== 'undefined' && (globalThis.__PULSE_HMR_HOT__ || globalThis.import?.meta?.hot));
+
+  if (!hot) {
     return createNoopContext();
   }
 
-  const hot = import.meta.hot;
-
   // Initialize data storage if not present
   if (!hot.data) {
     hot.data = {};

package/runtime/http.js

@@ -246,6 +246,7 @@ class HttpClient {
           try {
             return JSON.parse(text);
           } catch {
+            // Response body is not valid JSON — return raw text
             return text;
           }
 

package/runtime/i18n.js

@@ -322,6 +322,7 @@ export function createI18n(options = {}) {
     try {
       return new Intl.NumberFormat(locale.get(), opts).format(value);
     } catch {
+      // Intl may throw on invalid locale or value — fall back to plain string
       return String(value);
     }
   }
@@ -337,6 +338,7 @@ export function createI18n(options = {}) {
     try {
       return new Intl.DateTimeFormat(locale.get(), opts).format(value);
     } catch {
+      // Intl may throw on invalid locale or date — fall back to plain string
       return String(value);
     }
   }

package/runtime/lru-cache.js

@@ -6,6 +6,8 @@
  * When capacity is reached, the least recently used item is evicted.
  */
 
+import { RuntimeError } from './errors.js';
+
 /**
  * LRU Cache implementation
  * Uses Map's insertion order for O(1) operations.
@@ -20,7 +22,7 @@ export class LRUCache {
    */
   constructor(capacity, options = {}) {
     if (capacity <= 0) {
-      throw new Error('LRU cache capacity must be greater than 0');
+      throw new RuntimeError('LRU cache capacity must be greater than 0', { code: 'INVALID_CAPACITY' });
     }
     this._capacity = capacity;
     this._cache = new Map();

package/runtime/native.js

@@ -10,6 +10,7 @@
 import { pulse, effect, batch } from './pulse.js';
 import { loggers } from './logger.js';
 import { DANGEROUS_KEYS } from './security.js';
+import { RuntimeError } from './errors.js';
 
 const log = loggers.native;
 
@@ -92,9 +93,10 @@ function _compareSemver(a, b) {
  * Validate that an object has all required methods/properties
  * @param {Object} obj - Object to validate
  * @param {string[]} required - Required property names
+ * @param {string} [namespace] - Namespace label for error context
  * @returns {{valid: boolean, missing: string[]}}
  */
-function _validateApiSurface(obj, required) {
+function _validateApiSurface(obj, required, namespace = '') {
   if (!obj || typeof obj !== 'object') {
     return { valid: false, missing: required };
   }
@@ -281,6 +283,7 @@ function _tryParseJson(value) {
   try {
     return JSON.parse(value);
   } catch {
+    // Value is not valid JSON — return the raw string as-is
     return value;
   }
 }
@@ -374,7 +377,7 @@ export function getNative() {
         'This API only works in a Pulse native mobile app. ' +
         'For web, use isNativeAvailable() to check before calling native APIs, ' +
         'or use getPlatform() to detect the current environment.';
-    throw new Error(error);
+    throw new RuntimeError(error, { code: 'NATIVE_UNAVAILABLE', suggestion: 'Use isNativeAvailable() to check before calling native APIs' });
   }
   return window.PulseMobile;
 }
@@ -500,6 +503,7 @@ export function createNativeStorage(prefix = '') {
 export function createDeviceInfo() {
   const info = pulse(null);
   const network = pulse({ connected: true, type: 'unknown' });
+  const cleanups = [];
 
   // Load device info
   if (isNativeAvailable()) {
@@ -529,13 +533,14 @@ export function createDeviceInfo() {
         type: 'unknown'
       });
 
-      window.addEventListener('online', () => {
-        network.set({ connected: true, type: 'unknown' });
-      });
-
-      window.addEventListener('offline', () => {
-        network.set({ connected: false, type: 'none' });
-      });
+      const onOnline = () => { network.set({ connected: true, type: 'unknown' }); };
+      const onOffline = () => { network.set({ connected: false, type: 'none' }); };
+      window.addEventListener('online', onOnline);
+      window.addEventListener('offline', onOffline);
+      cleanups.push(
+        () => window.removeEventListener('online', onOnline),
+        () => window.removeEventListener('offline', onOffline)
+      );
     }
   }
 
@@ -559,6 +564,12 @@ export function createDeviceInfo() {
     /** Is currently online */
     get isOnline() {
       return network.get().connected;
+    },
+
+    /** Dispose event listeners to prevent memory leaks */
+    dispose() {
+      cleanups.forEach(fn => fn());
+      cleanups.length = 0;
     }
   };
 }
@@ -627,30 +638,38 @@ export const NativeClipboard = {
 
 /**
  * App lifecycle - pause handler
+ * @param {Function} callback - Called when app is paused/hidden
+ * @returns {Function} Cleanup function to remove the listener
  */
 export function onAppPause(callback) {
+  const cleanups = [];
   if (typeof document !== 'undefined') {
-    document.addEventListener('visibilitychange', () => {
-      if (document.hidden) callback();
-    });
+    const handler = () => { if (document.hidden) callback(); };
+    document.addEventListener('visibilitychange', handler);
+    cleanups.push(() => document.removeEventListener('visibilitychange', handler));
   }
   if (isNativeAvailable()) {
     getNative().App.onPause(callback);
   }
+  return () => cleanups.forEach(fn => fn());
 }
 
 /**
  * App lifecycle - resume handler
+ * @param {Function} callback - Called when app is resumed/visible
+ * @returns {Function} Cleanup function to remove the listener
  */
 export function onAppResume(callback) {
+  const cleanups = [];
   if (typeof document !== 'undefined') {
-    document.addEventListener('visibilitychange', () => {
-      if (!document.hidden) callback();
-    });
+    const handler = () => { if (!document.hidden) callback(); };
+    document.addEventListener('visibilitychange', handler);
+    cleanups.push(() => document.removeEventListener('visibilitychange', handler));
   }
   if (isNativeAvailable()) {
     getNative().App.onResume(callback);
   }
+  return () => cleanups.forEach(fn => fn());
 }
 
 /**
@@ -664,19 +683,26 @@ export function onBackButton(callback) {
 
 /**
  * Wait for native bridge to be ready
+ * @param {Function} callback - Called with { platform } when bridge is ready
+ * @returns {Function} Cleanup function to remove the listener
  */
 export function onNativeReady(callback) {
-  if (typeof window === 'undefined') return;
+  if (typeof window === 'undefined') return () => {};
 
-  window.addEventListener('pulse:ready', (e) => {
-    callback(e.detail);
-  });
+  const handler = (e) => { callback(e.detail); };
+  window.addEventListener('pulse:ready', handler);
 
+  let timerId;
   // If already ready (web or native initialized)
   if (typeof window.PulseMobile !== 'undefined') {
     const platform = window.PulseMobile.platform;
-    setTimeout(() => callback({ platform }), 0);
+    timerId = setTimeout(() => callback({ platform }), 0);
   }
+
+  return () => {
+    window.removeEventListener('pulse:ready', handler);
+    if (timerId) clearTimeout(timerId);
+  };
 }
 
 /**

package/runtime/pulse.js

@@ -20,6 +20,7 @@
 
 import { loggers } from './logger.js';
 import { Errors } from './errors.js';
+import { DANGEROUS_KEYS } from './security.js';
 
 const log = loggers.pulse;
 
@@ -1080,6 +1081,8 @@ export function createState(obj) {
   const pulses = {};
 
   for (const [key, value] of Object.entries(obj)) {
+    if (DANGEROUS_KEYS.has(key)) continue;
+
     if (Array.isArray(value)) {
       // Arrays get special handling with reactive methods
       pulses[key] = new Pulse(value);

package/runtime/router/core.js

@@ -507,7 +507,11 @@ export function createRouter(options = {}) {
    */
   function outlet(container) {
     if (typeof container === 'string') {
-      container = document.querySelector(container);
+      const el = document.querySelector(container);
+      if (!el) {
+        throw new Error(`outlet(): no element found matching selector "${container}"`);
+      }
+      container = el;
     }
 
     let currentView = null;

package/runtime/router/index.js

@@ -12,6 +12,7 @@ export * from './lazy.js';
 export * from './guards.js';
 export * from './history.js';
 export * from './utils.js';
+export * from './psc-integration.js';
 
 // Default export for backward compatibility
 import {
@@ -22,6 +23,14 @@ import {
 } from './core.js';
 import { lazy, preload } from './lazy.js';
 import { matchRoute, parseQuery, buildQueryString } from './utils.js';
+import {
+  fetchPSCPayload,
+  navigatePSC,
+  prefetchPSC,
+  clearPSCCache,
+  getPSCCacheStats,
+  configurePSCCache
+} from './psc-integration.js';
 
 export default {
   createRouter,
@@ -32,5 +41,12 @@ export default {
   parseQuery,
   buildQueryString,
   onBeforeLeave,
-  onAfterEnter
+  onAfterEnter,
+  // PSC Integration
+  fetchPSCPayload,
+  navigatePSC,
+  prefetchPSC,
+  clearPSCCache,
+  getPSCCacheStats,
+  configurePSCCache
 };