webspresso 0.0.109 → 0.0.110

package/core/client/forms.js

@@ -1,5 +1,7 @@
 'use strict';
 
+const { defaultStorage } = require('./storage');
+
 /**
  * Webspresso Native HTML Form Layer & Typed Form Handle
  *
@@ -13,6 +15,40 @@
  * - Mutation success vs refresh failure separation: a refresh failure never puts a succeeded form into validation error state
  */
 
+/**
+ * Validate that a redirect URL uses a safe protocol (http/https) or relative path
+ * to prevent DOM-based XSS (e.g. javascript: URIs) and protocol injection.
+ *
+ * @param {string} target
+ * @returns {boolean}
+ */
+function isSafeRedirectUrl(target) {
+  if (!target || typeof target !== 'string') return false;
+  const trimmed = target.trim();
+  if (!trimmed) return false;
+
+  // Block control characters
+  if (/[\u0000-\u001F\u007F-\u009F]/.test(trimmed)) return false;
+
+  // Block protocol-relative URLs (//example.com) and backslash traversal (/\ or \\)
+  if (trimmed.startsWith('//') || trimmed.startsWith('/\\') || trimmed.startsWith('\\')) {
+    return false;
+  }
+
+  // Relative path starting with single slash (e.g. /dashboard)
+  if (trimmed.startsWith('/')) {
+    return true;
+  }
+
+  // Absolute URL: MUST explicitly parse as http: or https:
+  try {
+    const parsed = new URL(trimmed);
+    return parsed.protocol === 'http:' || parsed.protocol === 'https:';
+  } catch {
+    return false;
+  }
+}
+
 let errorIdSeq = 0;
 
 /**
@@ -401,6 +437,89 @@ function createFormHandle(formEl, options = {}) {
   const errorListeners = new Set();
   const stateListeners = new Set();
 
+  // Form draft persistence setup (sessionStorage by default, or localStorage)
+  const rawDraftAttr = formEl
+    ? formEl.getAttribute('data-w-persist-draft') || formEl.getAttribute('data-w-draft')
+    : null;
+  const isDraftEnabled =
+    options.persistDraft !== undefined
+      ? Boolean(options.persistDraft)
+      : rawDraftAttr !== null && rawDraftAttr !== 'false';
+
+  let draftStorageType = 'session';
+  if (typeof options.persistDraft === 'string') {
+    draftStorageType = options.persistDraft.toLowerCase() === 'local' ? 'local' : 'session';
+  } else if (rawDraftAttr && rawDraftAttr.toLowerCase() === 'local') {
+    draftStorageType = 'local';
+  }
+
+  const draftKey =
+    options.draftKey ||
+    (formEl && (formEl.getAttribute('data-w-draft-key') || formEl.getAttribute('data-w-persist-key'))) ||
+    `form_draft:${formName || 'anon'}`;
+
+  const draftStorage =
+    (options.storage && options.storage[draftStorageType]) ||
+    (draftStorageType === 'local' ? defaultStorage.local : defaultStorage.session);
+
+  function extractDraftValues(el) {
+    if (!el || typeof el.querySelectorAll !== 'function') return {};
+    const { data } = parseFormElement(el);
+    const safeData = {};
+    for (const [key, val] of Object.entries(data)) {
+      const ctrl = el.querySelector(`[name="${key}"], [name="${key}[]"]`);
+      if (!ctrl) {
+        safeData[key] = val;
+        continue;
+      }
+      const type = (ctrl.type || '').toLowerCase();
+      if (type === 'password' || type === 'file') continue;
+      if (ctrl.hasAttribute('data-w-no-draft') || ctrl.getAttribute('data-w-persist') === 'false') continue;
+      safeData[key] = val;
+    }
+    return safeData;
+  }
+
+  function saveDraft() {
+    if (!formEl || !isDraftEnabled) return false;
+    const draftPayload = extractDraftValues(formEl);
+    return draftStorage.set(draftKey, draftPayload);
+  }
+
+  function restoreDraft() {
+    if (!formEl || !isDraftEnabled) return false;
+    const saved = draftStorage.get(draftKey, null);
+    if (saved && typeof saved === 'object' && Object.keys(saved).length > 0) {
+      fill(saved, { baseline: false });
+      if (typeof formEl.dispatchEvent === 'function') {
+        const CustomEventCtor =
+          (formEl.ownerDocument && formEl.ownerDocument.defaultView && formEl.ownerDocument.defaultView.CustomEvent) ||
+          (typeof CustomEvent !== 'undefined' ? CustomEvent : null);
+        if (CustomEventCtor) {
+          formEl.dispatchEvent(
+            new CustomEventCtor('w-form:draft-restored', {
+              bubbles: true,
+              cancelable: true,
+              detail: { form: handle, draft: saved, key: draftKey },
+            })
+          );
+        }
+      }
+      return true;
+    }
+    return false;
+  }
+
+  function clearDraft() {
+    if (!isDraftEnabled) return false;
+    return draftStorage.remove(draftKey);
+  }
+
+  function hasDraft() {
+    if (!isDraftEnabled) return false;
+    return draftStorage.has(draftKey);
+  }
+
   function notifyStateChange() {
     for (const fn of stateListeners) {
       try {
@@ -799,6 +918,10 @@ function createFormHandle(formEl, options = {}) {
         initialSnapshot = captureInitialFormSnapshot(formEl);
       }
 
+      if (isDraftEnabled) {
+        clearDraft();
+      }
+
       // Invoke registered success hooks. Note: Any background fragment refresh failure
       // is handled by the fragment coordinator and NEVER puts this form into validation error state!
       for (const listener of successListeners) {
@@ -810,7 +933,7 @@ function createFormHandle(formEl, options = {}) {
         submitOptions.redirectOnSuccess ||
         (formEl && formEl.getAttribute('data-w-redirect')) ||
         null;
-      if (redirectTarget) {
+      if (redirectTarget && isSafeRedirectUrl(redirectTarget)) {
         if (typeof options.navigate === 'function') {
           options.navigate(redirectTarget);
         } else if (typeof window !== 'undefined' && window.location) {
@@ -859,6 +982,7 @@ function createFormHandle(formEl, options = {}) {
   }
 
   // Listen to native submit and input/change events on `formEl`
+  let draftDebounceTimer = null;
   const onDomInput = (evt) => {
     dirty = computeFormDirty(formEl, initialSnapshot);
     const target = evt && evt.target;
@@ -873,6 +997,12 @@ function createFormHandle(formEl, options = {}) {
         }
       }
     }
+    if (isDraftEnabled) {
+      if (draftDebounceTimer) clearTimeout(draftDebounceTimer);
+      draftDebounceTimer = setTimeout(() => {
+        saveDraft();
+      }, 150);
+    }
     notifyStateChange();
   };
 
@@ -900,7 +1030,9 @@ function createFormHandle(formEl, options = {}) {
   // Initialize hidden state on empty error placeholders
   syncErrorsToDom(false);
 
-  const handle = {
+  let handle = null;
+
+  handle = {
     name: formName,
     el: formEl,
     get pending() {
@@ -938,6 +1070,12 @@ function createFormHandle(formEl, options = {}) {
       return parseFormElement(formEl, submitter).data;
     },
     fill,
+    saveDraft,
+    restoreDraft,
+    clearDraft,
+    get hasDraft() {
+      return hasDraft();
+    },
     setAction,
     setRouteParams,
     setDisabled,
@@ -1009,6 +1147,10 @@ function createFormHandle(formEl, options = {}) {
     debug.recordEvent('form:bind', { name: formName });
   }
 
+  if (isDraftEnabled) {
+    restoreDraft();
+  }
+
   return handle;
 }
 
@@ -1017,5 +1159,6 @@ module.exports = {
   isControlDisabled,
   coerceScalarControlValue,
   createFormHandle,
+  isSafeRedirectUrl,
 };
 

package/core/client/fragments.js

@@ -1,5 +1,7 @@
 'use strict';
 
+const { defaultStorage } = require('./storage');
+
 /**
  * Webspresso Client-Side SSR Fragment Coordinator & Invalidation Engine
  *
@@ -106,6 +108,7 @@ function createFragmentCoordinator(options = {}) {
   const endpoint = options.endpoint || DEFAULT_FRAGMENT_ENDPOINT;
   const datastar = options.datastar || options.adapter;
   const debug = options.debug || null;
+  const defaultTimeout = typeof options.timeout === 'number' ? options.timeout : 15000;
 
   // Map<instanceId, { instanceId, name, pagePath, input, dependsOn: Set<string>, version: number, el: Element, abortController: AbortController|null }>
   const instances = new Map();
@@ -151,25 +154,49 @@ function createFragmentCoordinator(options = {}) {
       const input = parseFragmentInputAttr(el.getAttribute('data-w-fragment-input'));
       const dependsOn = new Set(parseDependsOnAttr(el.getAttribute('data-w-depends-on')));
 
+      // Fragment input persistence setup
+      const rawPersistInput =
+        el.getAttribute('data-w-persist-input') ||
+        (el.getAttribute('data-w-persist') === 'input' ? 'session' : null);
+      const isInputPersistEnabled = Boolean(rawPersistInput && rawPersistInput !== 'false');
+      const inputStorageType = rawPersistInput && rawPersistInput.toLowerCase() === 'local' ? 'local' : 'session';
+      const inputStorageKey =
+        el.getAttribute('data-w-persist-key') ||
+        el.getAttribute('data-w-input-key') ||
+        `frag_input:${name}`;
+
+      let effectiveInput = input;
+      if (isInputPersistEnabled) {
+        const store = inputStorageType === 'local' ? defaultStorage.local : defaultStorage.session;
+        if (!el.hasAttribute('data-w-fragment-input') || Object.keys(effectiveInput).length === 0) {
+          const stored = store.get(inputStorageKey, null);
+          if (stored && typeof stored === 'object' && !Array.isArray(stored)) {
+            effectiveInput = stored;
+          }
+        }
+      }
+
       const existing = instances.get(instanceId);
       if (existing) {
         existing.name = name;
         existing.pagePath = pagePath;
         existing.el = el;
         existing.dependsOn = dependsOn;
-        if (el.hasAttribute('data-w-fragment-input')) {
-          existing.input = input;
+        if (el.hasAttribute('data-w-fragment-input') || isInputPersistEnabled) {
+          existing.input = effectiveInput;
         }
+        existing.persistInput = isInputPersistEnabled ? { type: inputStorageType, key: inputStorageKey } : null;
       } else {
         instances.set(instanceId, {
           instanceId,
           name,
           pagePath,
-          input,
+          input: effectiveInput,
           dependsOn,
           version: 0,
           el,
           abortController: null,
+          persistInput: isInputPersistEnabled ? { type: inputStorageType, key: inputStorageKey } : null,
         });
       }
     }
@@ -229,6 +256,10 @@ function createFragmentCoordinator(options = {}) {
     ) {
       inst.input = fragmentPayload.input;
       inst.el.setAttribute('data-w-fragment-input', JSON.stringify(fragmentPayload.input));
+      if (inst.persistInput) {
+        const store = inst.persistInput.type === 'local' ? defaultStorage.local : defaultStorage.session;
+        store.set(inst.persistInput.key, fragmentPayload.input);
+      }
     }
 
     if (datastar && typeof datastar.patchFragmentElement === 'function') {
@@ -266,7 +297,7 @@ function createFragmentCoordinator(options = {}) {
    * Execute a network refresh for a list of target fragment descriptors:
    * `Array<{ instanceId, name, pagePath, input, reqVersion }>`
    */
-  async function executeBatchRefresh(targets, chainIds = [], abortSignal = null) {
+  async function executeBatchRefresh(targets, chainIds = [], abortSignal = null, batchTimeout = defaultTimeout) {
     if (!targets || targets.length === 0) {
       return { refreshed: [], skipped: true };
     }
@@ -312,6 +343,27 @@ function createFragmentCoordinator(options = {}) {
       });
     }
 
+    const batchAbortController = new AbortController();
+    let timeoutTimer = null;
+    let timedOut = false;
+    const timeoutMs = typeof batchTimeout === 'number' ? batchTimeout : defaultTimeout;
+
+    if (timeoutMs > 0) {
+      timeoutTimer = setTimeout(() => {
+        timedOut = true;
+        batchAbortController.abort();
+      }, timeoutMs);
+    }
+
+    const onCallerAbort = () => batchAbortController.abort();
+    if (abortSignal) {
+      if (abortSignal.aborted) {
+        batchAbortController.abort();
+      } else {
+        abortSignal.addEventListener('abort', onCallerAbort, { once: true });
+      }
+    }
+
     let response;
     try {
       response = await fetchImpl(endpoint, {
@@ -319,11 +371,45 @@ function createFragmentCoordinator(options = {}) {
         headers,
         body: JSON.stringify(requestPayload),
         credentials: 'same-origin',
-        signal: abortSignal || undefined,
+        signal: batchAbortController.signal,
       });
     } catch (err) {
+      if (timeoutTimer) {
+        clearTimeout(timeoutTimer);
+        timeoutTimer = null;
+      }
+      if (abortSignal) {
+        try {
+          abortSignal.removeEventListener('abort', onCallerAbort);
+        } catch (_e) {}
+      }
+
+      if (timedOut) {
+        if (debug) {
+          debug.trackRequestEnd(reqId, {
+            status: 'failed',
+            errorKind: 'timeout',
+          });
+        }
+        const timeoutError = new Error(`Fragment refresh timed out after ${timeoutMs}ms.`);
+        timeoutError.code = 'FRAGMENT_REFRESH_TIMEOUT';
+        timeoutError.isTimedOut = true;
+        lastFailedBatch = { targets, chainIds };
+        for (const cid of chainIds) {
+          if (debug) {
+            debug.recordChainRefresh(cid, {
+              fragmentIds: targets.map((t) => t.instanceId),
+              status: 'failed',
+              error: timeoutError,
+            });
+          }
+        }
+        throw timeoutError;
+      }
+
       const isAbort =
         (abortSignal && abortSignal.aborted) ||
+        batchAbortController.signal.aborted ||
         (err && (err.name === 'AbortError' || err.code === 'ABORT_ERR'));
 
       if (debug) {
@@ -333,7 +419,7 @@ function createFragmentCoordinator(options = {}) {
         });
       }
       if (isAbort) {
-        return { refreshed: [], canceled: true };
+        return { ok: false, refreshed: [], canceled: true };
       }
       lastFailedBatch = { targets, chainIds };
       for (const cid of chainIds) {
@@ -346,6 +432,16 @@ function createFragmentCoordinator(options = {}) {
         }
       }
       throw err;
+    } finally {
+      if (timeoutTimer) {
+        clearTimeout(timeoutTimer);
+        timeoutTimer = null;
+      }
+      if (abortSignal) {
+        try {
+          abortSignal.removeEventListener('abort', onCallerAbort);
+        } catch (_e) {}
+      }
     }
 
     let body = null;
@@ -429,6 +525,7 @@ function createFragmentCoordinator(options = {}) {
     }
 
     return {
+      ok: true,
       refreshed: refreshedIds,
       errors: [],
       timings: {
@@ -452,7 +549,7 @@ function createFragmentCoordinator(options = {}) {
     }
 
     if (pendingTags.size === 0) {
-      return { refreshed: [], skipped: true };
+      return { ok: true, refreshed: [], skipped: true };
     }
 
     const tagsToFlush = new Set(pendingTags);
@@ -487,7 +584,7 @@ function createFragmentCoordinator(options = {}) {
           });
         }
       }
-      return { refreshed: [], skipped: true };
+      return { ok: true, refreshed: [], skipped: true };
     }
 
     // Parent/Child deduplication: if parent & child are both invalidated, parent refresh covers child
@@ -602,7 +699,16 @@ function createFragmentCoordinator(options = {}) {
     }
 
     if (matched.length === 0) {
-      return { refreshed: [], skipped: true };
+      const skippedRes = { ok: true, refreshed: [], skipped: true };
+      if (typeof refreshOpts.onSuccess === 'function') {
+        await refreshOpts.onSuccess(skippedRes);
+      }
+      if (typeof refreshOpts.onSettled === 'function') {
+        await refreshOpts.onSettled(skippedRes, null);
+      } else if (typeof refreshOpts.onComplete === 'function') {
+        await refreshOpts.onComplete(skippedRes, null);
+      }
+      return skippedRes;
     }
 
     const deduped = deduplicateParentChildFragments(matched);
@@ -627,6 +733,10 @@ function createFragmentCoordinator(options = {}) {
         if (inst.el && typeof inst.el.setAttribute === 'function') {
           inst.el.setAttribute('data-w-fragment-input', JSON.stringify(inst.input));
         }
+        if (inst.persistInput) {
+          const store = inst.persistInput.type === 'local' ? defaultStorage.local : defaultStorage.session;
+          store.set(inst.persistInput.key, inst.input);
+        }
       }
 
       return {
@@ -638,7 +748,45 @@ function createFragmentCoordinator(options = {}) {
       };
     });
 
-    return executeBatchRefresh(targets, [], abortController.signal);
+    try {
+      const result = await executeBatchRefresh(targets, [], abortController.signal, refreshOpts.timeout);
+      const enrichedResult = { ok: true, ...result };
+      if (!enrichedResult.canceled && enrichedResult.ok !== false) {
+        if (typeof refreshOpts.onSuccess === 'function') {
+          await refreshOpts.onSuccess(enrichedResult);
+        }
+      }
+      if (typeof refreshOpts.onSettled === 'function') {
+        await refreshOpts.onSettled(enrichedResult, null);
+      } else if (typeof refreshOpts.onComplete === 'function') {
+        await refreshOpts.onComplete(enrichedResult, null);
+      }
+      return enrichedResult;
+    } catch (err) {
+      const failHandler = refreshOpts.onFailure || refreshOpts.onError;
+      if (typeof failHandler === 'function') {
+        try {
+          await failHandler(err);
+        } catch (callbackErr) {
+          throw callbackErr;
+        }
+      }
+      if (typeof refreshOpts.onSettled === 'function') {
+        await refreshOpts.onSettled(null, err);
+      } else if (typeof refreshOpts.onComplete === 'function') {
+        await refreshOpts.onComplete(null, err);
+      }
+
+      if (refreshOpts.throwOnError !== true && (typeof failHandler === 'function' || refreshOpts.throwOnError === false)) {
+        return {
+          ok: false,
+          error: err,
+          refreshed: [],
+          timings: { loadMs: 0, renderMs: 0 },
+        };
+      }
+      throw err;
+    }
   }
 
   /**
@@ -722,6 +870,14 @@ function createFragmentCoordinator(options = {}) {
       syncDomInstances();
       return Array.from(instances.values());
     },
+    getStoredInput(instanceIdOrName, storageType = 'session') {
+      const store = storageType === 'local' ? defaultStorage.local : defaultStorage.session;
+      return store.get(`frag_input:${instanceIdOrName}`, null);
+    },
+    clearStoredInput(instanceIdOrName, storageType = 'session') {
+      const store = storageType === 'local' ? defaultStorage.local : defaultStorage.session;
+      return store.remove(`frag_input:${instanceIdOrName}`);
+    },
     get hasFailedRefresh() {
       return Boolean(lastFailedBatch);
     },

package/core/client/index.d.ts

@@ -3,6 +3,7 @@ export {
   ClientRequestErrorKind,
   ClientRequestError,
   ClientRequestCallOptions,
+  ClientRetryOptions,
   ClientApiClient,
   AppApiRouteMap,
   ClientTask,
@@ -11,12 +12,23 @@ export {
   ClientFormHandle,
   ClientFormFillOptions,
   ControllerFormsRegistry,
+  FragmentRefreshResult,
+  FragmentRefreshOptions,
   ControllerFragmentHandle,
   ControllerContext,
+  ControllerErrorMeta,
+  ControllerElement,
+  ControllerErrorHandler,
   ControllerActionHandler,
   ControllerComputedGetter,
   ControllerTaskFactory,
   ControllerDefinition,
+  WatchSource,
+  WatchCleanupCallback,
+  WatchCallback,
+  WatchOptions,
+  WatchDescriptor,
+  watch,
   defineController,
   deriveControllerNameFromPath,
   FragmentLoaderContext,
@@ -36,5 +48,12 @@ export {
   bootLiteClient,
   createDatastarAdapter,
   createClientDebugger,
+  StorageAdapter,
+  ClientStorage,
+  ControllerPersistConfig,
+  createClientStorage,
+  defaultStorage,
+  ClientDevtoolHandle,
+  mountDevtool,
 } from '../../index';
 

package/core/client/index.js

@@ -38,6 +38,8 @@ const {
   createControllerRuntime,
   queryScopedTargets,
   isTargetInControllerScope,
+  watch,
+  getActiveControllerContext,
 } = require('./controller');
 
 const {
@@ -60,6 +62,20 @@ const {
   summarizePayloadSafely,
 } = require('./debug');
 
+const {
+  MemoryStorage,
+  StorageAdapter,
+  getNativeStorageBackend,
+  createClientStorage,
+  defaultStorage,
+} = require('./storage');
+
+const {
+  mountDevtool,
+  highlightElement,
+  setupReduxDevToolsBridge,
+} = require('./devtool');
+
 let _serverFragments = null;
 function getServerFragments() {
   if (!_serverFragments) {
@@ -217,6 +233,7 @@ function createClientRuntime(options = {}) {
     getController: (el, name) => controllers.getInstanceForElement(el, name),
     invalidate: (tags, meta) => fragments.invalidate(tags, meta),
     refresh: (idOrName, input, opts) => fragments.refresh(idOrName, input, opts),
+    mountDevtool: (opts) => mountDevtool(runtime, opts),
     forms: {
       parse: parseFormElement,
       create: (formEl, formOpts = {}) =>
@@ -241,11 +258,26 @@ function createClientRuntime(options = {}) {
  */
 function bootClient(options = {}) {
   const runtime = createClientRuntime(options);
+  const shouldMountDevtools =
+    options.devtools === true ||
+    (options.devtools !== false &&
+      (options.debug ||
+        options.dev ||
+        (typeof window !== 'undefined' &&
+          (window.__WEBSPRESSO_DEVTOOLS_ENABLED__ || window.__WEBSPRESSO_DEV__)) ||
+        (typeof process !== 'undefined' && process.env && process.env.NODE_ENV !== 'production')));
+
   if (typeof document !== 'undefined') {
+    const onReady = () => {
+      runtime.mount();
+      if (shouldMountDevtools) {
+        runtime.devtool = mountDevtool(runtime, options.devtoolsOptions || {});
+      }
+    };
     if (document.readyState === 'loading') {
-      document.addEventListener('DOMContentLoaded', () => runtime.mount(), { once: true });
+      document.addEventListener('DOMContentLoaded', onReady, { once: true });
     } else {
-      runtime.mount();
+      onReady();
     }
   }
   return runtime;
@@ -266,6 +298,8 @@ module.exports = {
   createControllerRuntime,
   queryScopedTargets,
   isTargetInControllerScope,
+  watch,
+  getActiveControllerContext,
 
   // Typed API Client & Request Management
   ClientRequestError,
@@ -340,8 +374,18 @@ module.exports = {
   morphDomTrees,
   parseHtmlFragment,
 
-  // Debug & Telemetry
+  // Debug & Telemetry & DevTools
   createClientDebugger,
   summarizePayloadSafely,
+  mountDevtool,
+  highlightElement,
+  setupReduxDevToolsBridge,
+
+  // Client Storage & Persistence
+  MemoryStorage,
+  StorageAdapter,
+  getNativeStorageBackend,
+  createClientStorage,
+  defaultStorage,
 };
 

package/core/client/lite.js

@@ -36,6 +36,13 @@ const {
   deduplicateParentChildFragments,
 } = require('./fragments');
 
+const {
+  createClientStorage,
+  defaultStorage,
+  StorageAdapter,
+  MemoryStorage,
+} = require('./storage');
+
 const { NOOP_DEBUGGER } = require('./utils');
 
 let _serverFragments = null;
@@ -160,5 +167,9 @@ module.exports = {
   apiResult: (data, meta) => getServerFragments().apiResult(data, meta),
   isApiResultEnvelope: (val) => getServerFragments().isApiResultEnvelope(val),
   defineFragment: (def) => getServerFragments().defineFragment(def),
+  createClientStorage,
+  defaultStorage,
+  StorageAdapter,
+  MemoryStorage,
 };