webspresso 0.0.109 → 0.0.111

package/core/client/controller.js

@@ -17,8 +17,211 @@
 
 const { createFormHandle } = require('./forms');
 const { createApiClient } = require('./api');
+const { defaultStorage, createClientStorage } = require('./storage');
+const { createClientServiceRegistry } = require('./services');
+const {
+  isArray,
+  isNumber,
+  decorateElement,
+  parseDurationMs,
+  parseRefetchMode,
+  setElementBusyState,
+} = require('./utils');
 
 let instanceSeq = 0;
+let activeControllerContext = null;
+
+function getActiveControllerContext() {
+  return activeControllerContext;
+}
+
+function resolveStatePath(root, pathStr) {
+  if (!root || !pathStr) return undefined;
+  const parts = String(pathStr).split('.');
+  let cur = root;
+  for (let i = 0; i < parts.length; i++) {
+    if (cur === null || typeof cur !== 'object') return undefined;
+    cur = cur[parts[i]];
+  }
+  return cur;
+}
+
+function deepTouch(val, visited = new Set()) {
+  if (val === null || typeof val !== 'object' || visited.has(val)) {
+    return;
+  }
+  visited.add(val);
+  if (isArray(val)) {
+    for (let i = 0; i < val.length; i++) {
+      deepTouch(val[i], visited);
+    }
+  } else {
+    const keys = Object.keys(val);
+    for (let i = 0; i < keys.length; i++) {
+      deepTouch(val[keys[i]], visited);
+    }
+  }
+}
+
+function deepCloneOrSnapshot(val) {
+  if (val === null || typeof val !== 'object') return val;
+  try {
+    return JSON.parse(JSON.stringify(val));
+  } catch {
+    return isArray(val) ? [...val] : { ...val };
+  }
+}
+
+function deepEqual(a, b) {
+  if (Object.is(a, b)) return true;
+  if (a === null || typeof a !== 'object' || b === null || typeof b !== 'object') return false;
+  if (isArray(a) !== isArray(b)) return false;
+  const keysA = Object.keys(a);
+  const keysB = Object.keys(b);
+  if (keysA.length !== keysB.length) return false;
+  for (let i = 0; i < keysA.length; i++) {
+    const k = keysA[i];
+    if (!Object.prototype.hasOwnProperty.call(b, k) || !deepEqual(a[k], b[k])) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function hasArrayChanged(newArr, oldArr) {
+  if (!isArray(newArr) || !isArray(oldArr)) return !Object.is(newArr, oldArr);
+  if (newArr.length !== oldArr.length) return true;
+  for (let i = 0; i < newArr.length; i++) {
+    if (!Object.is(newArr[i], oldArr[i])) return true;
+  }
+  return false;
+}
+
+function runUntracked(engine, fn) {
+  if (engine && typeof engine.untracked === 'function') {
+    return engine.untracked(fn);
+  }
+  return fn();
+}
+
+function createStandaloneWatch(engine, source, callback, options = {}) {
+  if (typeof callback !== 'function') {
+    throw new TypeError('watch(source, callback) requires callback to be a function.');
+  }
+
+  const immediate = Boolean(options.immediate);
+  const deep = Boolean(options.deep);
+  const once = Boolean(options.once);
+
+  let getter;
+  if (typeof source === 'function') {
+    getter = source;
+  } else if (isArray(source)) {
+    getter = () => source.map((s) => (typeof s === 'function' ? s() : s));
+  } else {
+    getter = () => source;
+  }
+
+  let oldValue = undefined;
+  let isFirstRun = true;
+  let stopped = false;
+  let userCleanup = null;
+
+  function runCleanup() {
+    if (typeof userCleanup === 'function') {
+      try {
+        userCleanup();
+      } catch (_e) {}
+      userCleanup = null;
+    }
+  }
+
+  function onCleanup(fn) {
+    if (typeof fn === 'function') {
+      userCleanup = fn;
+    }
+  }
+
+  function stopWatch() {
+    if (stopped) return;
+    stopped = true;
+    runCleanup();
+    stopEffect();
+  }
+
+  const stopEffect = engine.effect(() => {
+    if (stopped) return;
+
+    let newValue;
+    try {
+      newValue = getter();
+      if ((deep || (source && typeof source === 'object' && typeof source !== 'function' && !isArray(source))) && newValue && typeof newValue === 'object') {
+        deepTouch(newValue);
+      }
+    } catch (_err) {
+      return;
+    }
+
+    const isArr = isArray(source);
+
+    if (isFirstRun) {
+      isFirstRun = false;
+      oldValue = deep ? deepCloneOrSnapshot(newValue) : isArr ? [...newValue] : newValue;
+      if (immediate) {
+        runCleanup();
+        runUntracked(engine, () => {
+          callback(newValue, undefined, onCleanup);
+        });
+        if (once) stopWatch();
+      }
+      return;
+    }
+
+    const hasChanged = deep
+      ? !deepEqual(newValue, oldValue)
+      : isArr
+        ? hasArrayChanged(newValue, oldValue)
+        : !Object.is(newValue, oldValue);
+
+    if (!hasChanged) return;
+
+    const prev = oldValue;
+    oldValue = deep ? deepCloneOrSnapshot(newValue) : isArr ? [...newValue] : newValue;
+
+    runCleanup();
+    runUntracked(engine, () => {
+      callback(newValue, prev, onCleanup);
+    });
+
+    if (once) stopWatch();
+  });
+
+  return stopWatch;
+}
+
+/**
+ * Vue-style reactive watcher.
+ *
+ * @template T
+ * @param {(() => T) | string | Array<any>} source - Reactive getter function, state dot-path, or array of sources
+ * @param {(newValue: T, oldValue: T | undefined, onCleanup: (fn: () => void) => void) => void} callback - Handler invoked when value changes
+ * @param {object} [options]
+ * @param {boolean} [options.immediate=false] - Trigger callback immediately on registration
+ * @param {boolean} [options.deep=false] - Deep watch nested object/array mutations
+ * @param {boolean} [options.once=false] - Stop watching automatically after first trigger
+ * @returns {() => void} Unwatch function
+ */
+function watch(source, callback, options = {}) {
+  if (activeControllerContext && typeof activeControllerContext.watch === 'function') {
+    return activeControllerContext.watch(source, callback, options);
+  }
+  const { createDatastarAdapter } = require('./adapter/datastar');
+  const engine = createDatastarAdapter().engine;
+  if (!engine || typeof engine.effect !== 'function') {
+    return () => {};
+  }
+  return createStandaloneWatch(engine, source, callback, options);
+}
 
 /**
  * Derive a deterministic controller name from a `.client.{js,ts}` file path.
@@ -33,34 +236,67 @@ let instanceSeq = 0;
  * @param {string} filePath
  * @returns {string}
  */
+function stripBrackets(str) {
+  return str.replace(/[\[\]]/g, '');
+}
+
+function extractAfterMarker(path, marker) {
+  const candidates = ['/src/' + marker, 'src/' + marker, '/' + marker, marker];
+  for (const cand of candidates) {
+    const idx = path.lastIndexOf(cand);
+    if (idx !== -1) {
+      if (cand.startsWith('/') || idx === 0) {
+        return path.slice(idx + cand.length);
+      }
+    }
+  }
+  return null;
+}
+
+function stripClientExtension(path) {
+  const exts = ['.client.ts', '.client.tsx', '.client.js', '.client.jsx', '.client.mjs', '.client.cjs'];
+  const lower = path.toLowerCase();
+  for (const ext of exts) {
+    if (lower.endsWith(ext)) {
+      return path.slice(0, -ext.length);
+    }
+  }
+  return path;
+}
+
 function deriveControllerNameFromPath(filePath) {
   if (!filePath || typeof filePath !== 'string') return '';
   const normalized = filePath.replace(/\\/g, '/');
+  const withoutExt = stripClientExtension(normalized);
 
-  // Strip extension (.client.ts, .client.js, .client.mjs, etc.)
-  const withoutExt = normalized.replace(/\.client\.(?:ts|tsx|js|jsx|mjs|cjs)$/i, '');
-
-  // Check if under views/components/ or views/
-  const compMatch = withoutExt.match(/(?:^|\/)(?:src\/)?views\/components\/(.+)$/);
-  if (compMatch) {
-    return compMatch[1].replace(/\//g, '--').replace(/\[([^\]]+)\]/g, '$1');
+  // Check if under views/components/
+  const compRel = extractAfterMarker(withoutExt, 'views/components/');
+  if (compRel) {
+    return stripBrackets(compRel.split('/').join('--'));
   }
 
-  const viewsMatch = withoutExt.match(/(?:^|\/)(?:src\/)?views\/(.+)$/);
-  if (viewsMatch) {
-    const rel = viewsMatch[1];
-    const base = rel.split('/').pop();
-    return (base || rel).replace(/\[([^\]]+)\]/g, '$1');
+  // Check if under views/
+  const viewsRel = extractAfterMarker(withoutExt, 'views/');
+  if (viewsRel) {
+    const base = viewsRel.split('/').pop() || viewsRel;
+    return stripBrackets(base);
   }
 
-  const pagesMatch = withoutExt.match(/(?:^|\/)(?:src\/)?pages\/(.+)$/);
-  if (pagesMatch) {
-    const rel = pagesMatch[1].replace(/\/index$/, '') || 'index';
-    return rel.replace(/\//g, '--').replace(/\[([^\]]+)\]/g, '$1');
+  // Check if under pages/
+  const pagesRel = extractAfterMarker(withoutExt, 'pages/');
+  if (pagesRel) {
+    let rel = pagesRel;
+    if (rel.endsWith('/index')) {
+      rel = rel.slice(0, -6);
+    }
+    if (!rel || rel === 'index') {
+      rel = 'index';
+    }
+    return stripBrackets(rel.split('/').join('--'));
   }
 
   const base = withoutExt.split('/').pop() || withoutExt;
-  return base.replace(/\[([^\]]+)\]/g, '$1');
+  return stripBrackets(base);
 }
 
 /**
@@ -89,6 +325,23 @@ function defineController(definition = {}) {
   if (definition.tasks !== undefined && (typeof definition.tasks !== 'object' || definition.tasks === null)) {
     throw new TypeError('defineController({ tasks }) must be an object of task factory functions.');
   }
+  if (definition.watch !== undefined && (typeof definition.watch !== 'object' || definition.watch === null)) {
+    throw new TypeError('defineController({ watch }) must be an object of watcher functions or descriptors.');
+  }
+  if (definition.onError !== undefined && typeof definition.onError !== 'function') {
+    throw new TypeError('defineController({ onError }) must be an error handler function `(err, ctx, meta) => void`.');
+  }
+  if (definition.persist !== undefined && definition.persist !== null) {
+    const p = definition.persist;
+    const isArr = isArray(p);
+    const isStr = typeof p === 'string';
+    const isObj = typeof p === 'object' && p !== null && !isArr;
+    if (!isArr && !isStr && !isObj) {
+      throw new TypeError(
+        'defineController({ persist }) must be an array of keys, storage type string ("local" | "session"), or a config object { keys?, storage?, key?, debounce? }.'
+      );
+    }
+  }
 
   // Pre-validate collision between state and computed properties
   if (definition.computed && typeof definition.computed === 'object') {
@@ -114,10 +367,53 @@ function defineController(definition = {}) {
     tasks: definition.tasks && typeof definition.tasks === 'object' ? definition.tasks : {},
     connect: typeof definition.connect === 'function' ? definition.connect : null,
     disconnect: typeof definition.disconnect === 'function' ? definition.disconnect : null,
+    onError: typeof definition.onError === 'function' ? definition.onError : null,
+    persist: definition.persist || null,
+    watch: definition.watch && typeof definition.watch === 'object' ? definition.watch : null,
     actions: definition.actions && typeof definition.actions === 'object' ? definition.actions : {},
   });
 }
 
+/**
+ * Normalize controller persist configuration.
+ *
+ * @param {any} persistOpt
+ * @param {string|null} controllerName
+ * @returns {{ keys: string[]|null, storageType: 'local'|'session'|'memory', storageKey: string, debounce: number }|null}
+ */
+function normalizePersistConfig(persistOpt, controllerName) {
+  if (!persistOpt) return null;
+  let keys = null;
+  let storageType = 'local';
+  let storageKey = 'state';
+  let isGlobal = false;
+  let debounce = 50;
+
+  if (isArray(persistOpt)) {
+    keys = persistOpt.map(String);
+  } else if (typeof persistOpt === 'string') {
+    const s = persistOpt.trim().toLowerCase();
+    storageType = s === 'session' ? 'session' : 'local';
+  } else if (typeof persistOpt === 'object' && persistOpt !== null) {
+    if (isArray(persistOpt.keys)) {
+      keys = persistOpt.keys.map(String);
+    }
+    if (persistOpt.storage === 'session' || persistOpt.storage === 'memory') {
+      storageType = persistOpt.storage;
+    }
+    if (typeof persistOpt.key === 'string' && persistOpt.key.trim()) {
+      storageKey = persistOpt.key.trim();
+    }
+    if (Boolean(persistOpt.global)) {
+      isGlobal = true;
+    }
+    if (isNumber(persistOpt.debounce)) {
+      debounce = Math.max(0, persistOpt.debounce);
+    }
+  }
+  return { keys, storageType, storageKey, isGlobal, debounce };
+}
+
 /**
  * Check if `candidateEl` belongs to `rootEl`'s controller scope for `controllerName`,
  * and is NOT inside a nested `[data-w-controller]` element.
@@ -159,7 +455,7 @@ function queryScopedTargets(rootEl, controllerName, targetName) {
     const rawAttr = (el.getAttribute('data-w-target') || '').trim();
     const tokens = rawAttr.split(/\s+/);
     if (tokens.includes(cleanTarget) || tokens.includes(prefixedTarget)) {
-      matched.push(el);
+      matched.push(decorateElement(el));
     }
   }
 
@@ -182,6 +478,14 @@ function createControllerRuntime(options = {}) {
   const debug = options.debug || null;
   const baseApiConfig = options.apiConfig || {};
   const lazyLoader = typeof options.lazyLoader === 'function' ? options.lazyLoader : null;
+  const services =
+    options.services && typeof options.services.get === 'function'
+      ? options.services
+      : createClientServiceRegistry({
+          root: options.root || null,
+          debug,
+          services: options.services || undefined,
+        });
 
   // Registered controller definitions: name -> { name, definition, sourcePath }
   const definitions = new Map();
@@ -201,11 +505,18 @@ function createControllerRuntime(options = {}) {
    * @param {string} [meta.sourcePath]
    * @param {string[]} [meta.aliases]
    */
-  function register(name, rawDef, meta = {}) {
+  function register(nameOrDef, rawDef, meta = {}) {
+    let name = nameOrDef;
+    let actualDef = rawDef;
+    if (typeof nameOrDef === 'object' && nameOrDef !== null && !rawDef) {
+      actualDef = nameOrDef;
+      name = actualDef.name || (actualDef.default && actualDef.default.name) || null;
+    }
+
     const def =
-      rawDef && rawDef.__isWebspressoController
-        ? rawDef
-        : defineController(rawDef && rawDef.default ? rawDef.default : rawDef);
+      actualDef && actualDef.__isWebspressoController
+        ? actualDef
+        : defineController(actualDef && actualDef.default ? actualDef.default : actualDef);
 
     const canonicalName = String(name || def.name || '').trim();
     if (!canonicalName) {
@@ -239,7 +550,7 @@ function createControllerRuntime(options = {}) {
     };
     definitions.set(canonicalName, entry);
 
-    if (Array.isArray(meta.aliases)) {
+    if (isArray(meta.aliases)) {
       for (const alias of meta.aliases) {
         if (alias && !definitions.has(alias)) {
           definitions.set(alias, entry);
@@ -292,7 +603,122 @@ function createControllerRuntime(options = {}) {
     const scopedForms = new Map();
     const scopedTasks = {};
     const scopedTasksList = [];
+    const busyActionCounts = new Map();
+    let totalBusyActions = 0;
+    const busySignalPrefix = `__w_inst_${instanceId}.__busy`;
+    datastar.engine.signals.setValue(`${busySignalPrefix}.any`, false);
+
+    function syncAnyBusySignal() {
+      let busy = totalBusyActions > 0;
+      if (!busy) {
+        for (let i = 0; i < scopedTasksList.length; i++) {
+          if (scopedTasksList[i].pending) {
+            busy = true;
+            break;
+          }
+        }
+      }
+      datastar.engine.signals.setValue(`${busySignalPrefix}.any`, busy);
+    }
+
+    function setActionBusy(actionName, delta) {
+      const prevCount = busyActionCounts.get(actionName) || 0;
+      const nextCount = Math.max(0, prevCount + delta);
+      if (nextCount === 0) {
+        busyActionCounts.delete(actionName);
+      } else {
+        busyActionCounts.set(actionName, nextCount);
+      }
+      totalBusyActions = Math.max(0, totalBusyActions + delta);
+      datastar.engine.signals.setValue(`${busySignalPrefix}.action_${actionName}`, nextCount > 0);
+      syncAnyBusySignal();
+    }
+
+    function isActionBusy(actionName) {
+      if (!actionName) return false;
+      datastar.engine.signals.value(`${busySignalPrefix}.action_${actionName}`);
+      return (busyActionCounts.get(actionName) || 0) > 0;
+    }
+
+    function checkIsBusy() {
+      datastar.engine.signals.value(`${busySignalPrefix}.any`);
+      if (totalBusyActions > 0) return true;
+      for (let i = 0; i < scopedTasksList.length; i++) {
+        if (scopedTasksList[i].pending) return true;
+      }
+      return false;
+    }
+
+    function isLoadingTargetActive(rawSpec) {
+      const spec = typeof rawSpec === 'string' ? rawSpec.trim() : '';
+      if (!spec || spec === 'true') {
+        return checkIsBusy();
+      }
+      const parts = spec.split(',').map((s) => s.trim()).filter(Boolean);
+      for (let i = 0; i < parts.length; i++) {
+        const token = parts[i];
+        if (reg.definition.actions && Object.prototype.hasOwnProperty.call(reg.definition.actions, token)) {
+          if (isActionBusy(token)) return true;
+          continue;
+        }
+        if (
+          Object.prototype.hasOwnProperty.call(scopedTasks, token) ||
+          (reg.definition.tasks && Object.prototype.hasOwnProperty.call(reg.definition.tasks, token))
+        ) {
+          const t = getTask(token);
+          if (t && t.pending) return true;
+          continue;
+        }
+        if (Boolean(datastar.evaluateStateExpression(state, token))) {
+          return true;
+        }
+      }
+      return false;
+    }
+
     let currentActionEl = null;
+    let lastError = null;
+    const dynamicErrorListeners = new Set();
+
+    function handleControllerError(err, meta = {}) {
+      if (!err || err.isCanceled) {
+        return;
+      }
+
+      lastError = err;
+
+      // 1. Controller definition onError hook
+      if (typeof reg.definition.onError === 'function') {
+        try {
+          reg.definition.onError(err, ctx, meta);
+        } catch (hookErr) {
+          if (debug) {
+            debug.trackCleanupError(instanceId, controllerName, 'onError', hookErr);
+          }
+        }
+      }
+
+      // 2. Dynamic ctx.onError listeners
+      for (const listener of Array.from(dynamicErrorListeners)) {
+        try {
+          listener(err, meta);
+        } catch (_listenerErr) {
+          // Ignore
+        }
+      }
+
+      // 3. Dispatch bubbling CustomEvent 'w-controller:error' on rootEl
+      emitEvent(
+        'w-controller:error',
+        {
+          error: err,
+          instanceId,
+          controllerName,
+          ...meta,
+        },
+        { bubbles: true, cancelable: true }
+      );
+    }
 
     let taskSeq = 0;
     function createTaskInstance(runFnOrConfig, options = {}) {
@@ -310,10 +736,29 @@ function createControllerRuntime(options = {}) {
       const taskKey = taskOpts.key || `task_${++taskSeq}`;
       const signalPrefix = `__w_inst_${instanceId}.task_${taskKey}`;
 
+      // React Query-style automatic revalidation options for tasks
+      const staleTimeMs = parseDurationMs(taskOpts.staleTime, 0);
+      const refetchOnMountMode = parseRefetchMode(
+        taskOpts.refetchOnMount !== undefined ? taskOpts.refetchOnMount : taskOpts.refetchOnVisit,
+        false
+      );
+      const refetchOnFocusMode = parseRefetchMode(
+        taskOpts.refetchOnWindowFocus !== undefined ? taskOpts.refetchOnWindowFocus : taskOpts.refetchOnFocus,
+        false
+      );
+      const refetchOnReconnectMode = parseRefetchMode(taskOpts.refetchOnReconnect, false);
+      const refetchIntervalMs = parseDurationMs(taskOpts.refetchInterval, 0);
+      const refetchIntervalInBg =
+        parseRefetchMode(taskOpts.refetchIntervalInBackground, false) === true;
+
       let currentRunVersion = 0;
       let activeRuns = 0;
       let inFlightAbort = null;
       let queuedPromise = Promise.resolve();
+      let _lastUpdatedAt = 0;
+      let taskIntervalTimer = null;
+      let focusDebounceTimer = null;
+      const taskCleanupListeners = [];
 
       datastar.engine.signals.setValue(`${signalPrefix}.pending`, false);
       datastar.engine.signals.setValue(`${signalPrefix}.data`, null);
@@ -325,8 +770,19 @@ function createControllerRuntime(options = {}) {
       let _error = null;
       let _stale = false;
 
+      function isTaskStale(mode = true) {
+        if (!mode) return false;
+        if (mode === 'always') return true;
+        if (_lastUpdatedAt === 0) return true;
+        if (staleTimeMs <= 0) return true;
+        return Date.now() - _lastUpdatedAt >= staleTimeMs;
+      }
+
       function updateSignal(name, val) {
         datastar.engine.signals.setValue(`${signalPrefix}.${name}`, val);
+        if (name === 'pending') {
+          syncAnyBusySignal();
+        }
       }
 
       async function run(...args) {
@@ -385,6 +841,7 @@ function createControllerRuntime(options = {}) {
           _data = result;
           _error = null;
           _stale = false;
+          _lastUpdatedAt = Date.now();
           updateSignal('data', result);
           updateSignal('error', null);
           updateSignal('stale', false);
@@ -398,6 +855,10 @@ function createControllerRuntime(options = {}) {
           }
           _error = err;
           updateSignal('error', err);
+          handleControllerError(err, {
+            task: taskKey,
+            phase: 'task',
+          });
           throw err;
         } finally {
           if (inFlightAbort === abortCtrl) {
@@ -446,16 +907,103 @@ function createControllerRuntime(options = {}) {
         },
         get stale() {
           datastar.engine.signals.value(`${signalPrefix}.stale`);
-          return _stale;
+          return _stale || (_lastUpdatedAt > 0 && staleTimeMs > 0 && Date.now() - _lastUpdatedAt >= staleTimeMs);
+        },
+        get lastUpdatedAt() {
+          return _lastUpdatedAt;
         },
+        isStale: () => isTaskStale(true),
         run,
         cancel,
         dispose() {
+          if (taskIntervalTimer) {
+            clearInterval(taskIntervalTimer);
+            taskIntervalTimer = null;
+          }
+          if (focusDebounceTimer) {
+            clearTimeout(focusDebounceTimer);
+            focusDebounceTimer = null;
+          }
+          while (taskCleanupListeners.length > 0) {
+            const removeFn = taskCleanupListeners.pop();
+            try {
+              removeFn();
+            } catch (_e) {}
+          }
           cancel();
           datastar.engine.signals.remove(signalPrefix);
         },
       };
 
+      // Set up automatic background revalidation (mount / focus / reconnect / interval)
+      const doc = (rootEl && rootEl.ownerDocument) || (typeof document !== 'undefined' ? document : null);
+      const win = (doc && doc.defaultView) || (typeof window !== 'undefined' ? window : null);
+
+      function isDocHidden() {
+        return Boolean(doc && doc.visibilityState === 'hidden');
+      }
+
+      if (refetchOnMountMode) {
+        Promise.resolve().then(() => {
+          if (isConnected() && isTaskStale(refetchOnMountMode)) {
+            run().catch(() => {});
+          }
+        });
+      }
+
+      if (refetchOnFocusMode) {
+        const onTaskFocus = () => {
+          if (!isConnected() || isDocHidden()) return;
+          if (focusDebounceTimer) clearTimeout(focusDebounceTimer);
+          focusDebounceTimer = setTimeout(() => {
+            focusDebounceTimer = null;
+            if (isConnected() && !isDocHidden() && activeRuns === 0 && isTaskStale(refetchOnFocusMode)) {
+              run().catch(() => {});
+            }
+          }, 20);
+        };
+        const onVisChange = () => {
+          if (!isDocHidden()) onTaskFocus();
+        };
+        if (doc && typeof doc.addEventListener === 'function') {
+          doc.addEventListener('visibilitychange', onVisChange);
+          taskCleanupListeners.push(() => doc.removeEventListener('visibilitychange', onVisChange));
+        }
+        if (win && typeof win.addEventListener === 'function') {
+          win.addEventListener('focus', onTaskFocus);
+          taskCleanupListeners.push(() => win.removeEventListener('focus', onTaskFocus));
+        }
+      }
+
+      if (refetchOnReconnectMode && win && typeof win.addEventListener === 'function') {
+        const onTaskOnline = () => {
+          if (isConnected() && activeRuns === 0 && isTaskStale(refetchOnReconnectMode)) {
+            run().catch(() => {});
+          }
+        };
+        win.addEventListener('online', onTaskOnline);
+        taskCleanupListeners.push(() => win.removeEventListener('online', onTaskOnline));
+      }
+
+      if (refetchIntervalMs > 0) {
+        taskIntervalTimer = setInterval(() => {
+          if (!isConnected()) {
+            if (taskIntervalTimer) {
+              clearInterval(taskIntervalTimer);
+              taskIntervalTimer = null;
+            }
+            return;
+          }
+          if (!refetchIntervalInBg && isDocHidden()) return;
+          if (activeRuns === 0) {
+            run().catch(() => {});
+          }
+        }, refetchIntervalMs);
+        if (taskIntervalTimer && typeof taskIntervalTimer.unref === 'function') {
+          taskIntervalTimer.unref();
+        }
+      }
+
       scopedTasksList.push(taskObj);
       return taskObj;
     }
@@ -470,6 +1018,129 @@ function createControllerRuntime(options = {}) {
       return stop;
     }
 
+    function registerWatch(source, callback, options = {}) {
+      if (!isConnected()) return () => {};
+      if (typeof callback !== 'function') {
+        throw new TypeError('watch(source, callback) requires callback to be a function.');
+      }
+
+      const immediate = Boolean(options.immediate);
+      const deep = Boolean(options.deep);
+      const once = Boolean(options.once);
+
+      let getter;
+      if (typeof source === 'function') {
+        getter = () => source(ctx);
+      } else if (typeof source === 'string') {
+        getter = () => resolveStatePath(state, source);
+      } else if (isArray(source)) {
+        getter = () =>
+          source.map((s) =>
+            typeof s === 'function'
+              ? s(ctx)
+              : typeof s === 'string'
+                ? resolveStatePath(state, s)
+                : s
+          );
+      } else if (source && typeof source === 'object') {
+        getter = () => source;
+      } else {
+        getter = () => source;
+      }
+
+      let oldValue = undefined;
+      let isFirstRun = true;
+      let stopped = false;
+      let userCleanup = null;
+
+      function runCleanup() {
+        if (typeof userCleanup === 'function') {
+          try {
+            userCleanup();
+          } catch (e) {
+            handleError(e, 'watch:cleanup');
+          }
+          userCleanup = null;
+        }
+      }
+
+      function onCleanup(fn) {
+        if (typeof fn === 'function') {
+          userCleanup = fn;
+        }
+      }
+
+      function stopWatch() {
+        if (stopped) return;
+        stopped = true;
+        runCleanup();
+        stopEffect();
+      }
+
+      const stopEffect = datastar.engine.effect(() => {
+        if (stopped || !isConnected()) return;
+
+        let newValue;
+        try {
+          newValue = getter();
+          if ((deep || (source && typeof source === 'object' && typeof source !== 'function' && !isArray(source))) && newValue && typeof newValue === 'object') {
+            deepTouch(newValue);
+          }
+        } catch (err) {
+          handleError(err, 'watch:getter');
+          return;
+        }
+
+        const isArr = isArray(source);
+
+        if (isFirstRun) {
+          isFirstRun = false;
+          oldValue = deep ? deepCloneOrSnapshot(newValue) : isArr ? [...newValue] : newValue;
+          if (immediate) {
+            try {
+              runCleanup();
+              runUntracked(datastar.engine, () => {
+                callback(newValue, undefined, onCleanup);
+              });
+            } catch (err) {
+              handleError(err, 'watch:callback');
+            }
+            if (once) {
+              stopWatch();
+            }
+          }
+          return;
+        }
+
+        const hasChanged = deep
+          ? !deepEqual(newValue, oldValue)
+          : isArr
+            ? hasArrayChanged(newValue, oldValue)
+            : !Object.is(newValue, oldValue);
+
+        if (!hasChanged) return;
+
+        const prev = oldValue;
+        oldValue = deep ? deepCloneOrSnapshot(newValue) : isArr ? [...newValue] : newValue;
+
+        try {
+          runCleanup();
+          runUntracked(datastar.engine, () => {
+            callback(newValue, prev, onCleanup);
+          });
+        } catch (err) {
+          handleError(err, 'watch:callback');
+        }
+
+        if (once) {
+          stopWatch();
+        }
+      });
+
+      cleanupCallbacks.push(stopWatch);
+      return stopWatch;
+    }
+
     function registerListener(targetOrEventName, eventNameOrHandler, handlerOrOptions, maybeOptions) {
       if (!isConnected()) return () => {};
       let targetEl = rootEl;
@@ -605,6 +1276,7 @@ function createControllerRuntime(options = {}) {
         api: scopedApi,
         datastar,
         debug,
+        services,
         ...formOptions,
       });
       scopedForms.set(handle.name, handle);
@@ -677,6 +1349,24 @@ function createControllerRuntime(options = {}) {
     let state = null;
     let ctx = null;
 
+    const controllerStorage = defaultStorage.scoped(controllerName || 'anon');
+    const storageCtx = Object.freeze({
+      local: controllerStorage.local,
+      session: controllerStorage.session,
+      memory: controllerStorage.memory,
+      scoped: (sub) => controllerStorage.scoped(sub),
+      global: defaultStorage,
+      root: defaultStorage,
+    });
+    const persistConfig = normalizePersistConfig(reg.definition.persist, controllerName);
+    function resolvePersistDriver(pConfig) {
+      if (!pConfig) return storageCtx.local;
+      if (pConfig.isGlobal) {
+        return defaultStorage[pConfig.storageType] || defaultStorage.local;
+      }
+      return storageCtx[pConfig.storageType] || storageCtx.local;
+    }
+
     // 6. Context object passed to `connect(ctx)` and `actions[name](ctx, event, actionEl)`
     ctx = Object.freeze({
       instanceId,
@@ -686,15 +1376,26 @@ function createControllerRuntime(options = {}) {
         return state;
       },
       api: scopedApi,
+      services,
       forms: formsAccessor,
       target: targetAccessor,
       targets: targetsAccessor,
       tasks: tasksProxy,
       task: createTaskInstance,
+      storage: storageCtx,
+      clearPersistedState: () => {
+        if (persistConfig) {
+          const driver = resolvePersistDriver(persistConfig);
+          driver.remove(persistConfig.storageKey);
+        }
+      },
       param: (name, maybeEl) => {
         if (!name) return null;
-        const el = maybeEl || currentActionEl;
+        const el = decorateElement(maybeEl || currentActionEl);
         if (!el) return null;
+        if (typeof el.data === 'function') {
+          return el.data(name);
+        }
         const rawAttr = el.getAttribute ? el.getAttribute(`data-${name}`) : null;
         if (rawAttr !== null) return rawAttr;
         if (el.dataset && el.dataset[name] !== undefined) return el.dataset[name];
@@ -703,21 +1404,57 @@ function createControllerRuntime(options = {}) {
       on: registerListener,
       emit: emitEvent,
       effect: registerEffect,
+      watch: registerWatch,
       interval: registerInterval,
       timeout: registerTimeout,
       signal: lifecycleAbort.signal,
       isConnected,
       isDisposed: () => !isConnected(),
-      invalidate: (tags) => (fragments ? fragments.invalidate(tags) : Promise.resolve({ refreshed: [] })),
-      refresh: (idOrName, input, opts) =>
-        fragments ? fragments.refresh(idOrName, input, opts) : Promise.resolve({ refreshed: [] }),
+      get isBusy() {
+        return checkIsBusy();
+      },
+      isActionBusy,
+      get lastError() {
+        return lastError;
+      },
+      clearError() {
+        lastError = null;
+      },
+      onError(listener) {
+        if (typeof listener !== 'function') return () => {};
+        dynamicErrorListeners.add(listener);
+        const unregister = () => {
+          dynamicErrorListeners.delete(listener);
+        };
+        cleanupCallbacks.push(unregister);
+        return unregister;
+      },
+      invalidate: (tags) => (fragments ? fragments.invalidate(tags) : Promise.resolve({ ok: true, refreshed: [] })),
+      refresh: async (idOrName, input, opts) => {
+        if (!fragments) {
+          const empty = { ok: true, refreshed: [], skipped: true };
+          if (opts && typeof opts.onSuccess === 'function') await opts.onSuccess(empty);
+          if (opts && typeof opts.onSettled === 'function') await opts.onSettled(empty, null);
+          else if (opts && typeof opts.onComplete === 'function') await opts.onComplete(empty, null);
+          return empty;
+        }
+        return fragments.refresh(idOrName, input, opts);
+      },
       fragment: (idOrName) => ({
         get input() {
           const inst = fragments && fragments.getInstance ? fragments.getInstance(idOrName) : null;
           return inst && inst.input ? { ...inst.input } : {};
         },
-        refresh: (input, opts) =>
-          fragments ? fragments.refresh(idOrName, input, opts) : Promise.resolve({ refreshed: [] }),
+        refresh: (input, opts) => {
+          if (!fragments) {
+            const empty = { ok: true, refreshed: [], skipped: true };
+            if (opts && typeof opts.onSuccess === 'function') {
+              return Promise.resolve(opts.onSuccess(empty)).then(() => empty);
+            }
+            return Promise.resolve(empty);
+          }
+          return fragments.refresh(idOrName, input, opts);
+        },
       }),
     });
 
@@ -741,28 +1478,122 @@ function createControllerRuntime(options = {}) {
     );
     state = stateManager.state;
 
+    // Hydrate persisted state if defined
+    if (persistConfig) {
+      const driver = resolvePersistDriver(persistConfig);
+      const savedData = driver.get(persistConfig.storageKey, null);
+      if (savedData && typeof savedData === 'object' && !isArray(savedData)) {
+        for (const [k, v] of Object.entries(savedData)) {
+          if (persistConfig.keys && !persistConfig.keys.includes(k)) continue;
+          if (Object.prototype.hasOwnProperty.call(initialRawState, k)) {
+            state[k] = v;
+          }
+        }
+      }
+    }
+
+    // Register declarative watchers from definition
+    if (reg.definition.watch && typeof reg.definition.watch === 'object') {
+      for (const [watchKey, watchDef] of Object.entries(reg.definition.watch)) {
+        if (typeof watchDef === 'function') {
+          registerWatch(watchKey, (newVal, oldVal, onCleanup) => {
+            watchDef.call(ctx, newVal, oldVal, onCleanup, ctx);
+          });
+        } else if (watchDef && typeof watchDef === 'object' && typeof watchDef.handler === 'function') {
+          registerWatch(
+            watchKey,
+            (newVal, oldVal, onCleanup) => {
+              watchDef.handler.call(ctx, newVal, oldVal, onCleanup, ctx);
+            },
+            {
+              immediate: watchDef.immediate,
+              deep: watchDef.deep,
+              once: watchDef.once,
+            }
+          );
+        }
+      }
+    }
+
     function invokeAction(actionName, event, actionEl) {
       if (!isConnected()) return undefined;
       const fn = reg.definition.actions[actionName];
       if (typeof fn !== 'function') {
         return undefined;
       }
-      currentActionEl = actionEl || null;
+
+      // Guard against duplicate clicks while an async action on this exact element is already in-flight
+      if (
+        actionEl &&
+        actionEl.__wActionBusy === true &&
+        (!actionEl.hasAttribute || !actionEl.hasAttribute('data-w-allow-concurrent'))
+      ) {
+        if (event && typeof event.preventDefault === 'function') {
+          event.preventDefault();
+        }
+        return undefined;
+      }
+
+      // Built-in `data-w-confirm` guard
+      if (actionEl && typeof actionEl.getAttribute === 'function') {
+        const confirmMsg = actionEl.getAttribute('data-w-confirm');
+        if (confirmMsg !== null && confirmMsg !== '') {
+          const confirmFn =
+            typeof window !== 'undefined' && typeof window.confirm === 'function'
+              ? window.confirm.bind(window)
+              : null;
+          if (confirmFn && !confirmFn(confirmMsg)) {
+            if (event && typeof event.preventDefault === 'function') {
+              event.preventDefault();
+            }
+            return undefined;
+          }
+        }
+      }
+
+      const decoratedEl = decorateElement(actionEl);
+      currentActionEl = decoratedEl || null;
+      const prevContext = activeControllerContext;
+      activeControllerContext = ctx;
       try {
-        const res = fn(ctx, event, actionEl);
+        const res = fn(ctx, event, decoratedEl);
         if (res && typeof res.then === 'function') {
-          return res.catch((err) => {
-            // Ignore canceled/superseded request errors on disconnected or superseded instances
-            if (err && err.isCanceled) return undefined;
-            throw err;
-          });
+          setActionBusy(actionName, 1);
+          setElementBusyState(actionEl, true);
+          return res.then(
+            (val) => {
+              setActionBusy(actionName, -1);
+              setElementBusyState(actionEl, false);
+              return val;
+            },
+            (err) => {
+              setActionBusy(actionName, -1);
+              setElementBusyState(actionEl, false);
+              // Ignore canceled/superseded request errors on disconnected or superseded instances
+              if (err && err.isCanceled) return undefined;
+              handleControllerError(err, {
+                action: actionName,
+                event,
+                actionEl: decoratedEl,
+                phase: 'action',
+              });
+              throw err;
+            }
+          );
         }
         return res;
       } catch (err) {
         if (err && err.isCanceled) return undefined;
+        handleControllerError(err, {
+          action: actionName,
+          event,
+          actionEl: decoratedEl,
+          phase: 'action',
+        });
         throw err;
       } finally {
         currentActionEl = null;
+        activeControllerContext = prevContext;
       }
     }
 
@@ -776,6 +1607,7 @@ function createControllerRuntime(options = {}) {
         state,
         invokeAction,
         isConnected,
+        isLoadingTargetActive,
       });
       domDisposers.push(unbind);
 
@@ -787,7 +1619,7 @@ function createControllerRuntime(options = {}) {
         const formsInScope = rootEl.querySelectorAll('form[data-w-form]');
         for (let i = 0; i < formsInScope.length; i++) {
           if (isTargetInControllerScope(rootEl, formsInScope[i])) {
-            createFormHandle(formsInScope[i], { api: scopedApi, datastar, debug });
+            createFormHandle(formsInScope[i], { api: scopedApi, datastar, debug, services });
           }
         }
       }
@@ -795,17 +1627,59 @@ function createControllerRuntime(options = {}) {
 
     rebindDom();
 
+    // Auto-sync persisted state changes back to storage
+    if (persistConfig) {
+      const driver = resolvePersistDriver(persistConfig);
+      let persistTimer = null;
+      let lastSavedJson = '';
+
+      const stopPersistEffect = registerEffect(() => {
+        if (!isConnected()) return;
+        const keysToTrack = persistConfig.keys || Object.keys(initialRawState);
+        const payload = {};
+        for (const k of keysToTrack) {
+          payload[k] = state[k];
+        }
+
+        const serialized = JSON.stringify(payload);
+        if (serialized === lastSavedJson) return;
+
+        const writeToStorage = () => {
+          if (!isConnected()) return;
+          driver.set(persistConfig.storageKey, payload);
+          lastSavedJson = serialized;
+        };
+
+        if (persistConfig.debounce > 0) {
+          if (persistTimer) clearTimeout(persistTimer);
+          persistTimer = setTimeout(writeToStorage, persistConfig.debounce);
+        } else {
+          writeToStorage();
+        }
+      });
+
+      cleanupCallbacks.push(() => {
+        if (persistTimer) clearTimeout(persistTimer);
+        if (typeof stopPersistEffect === 'function') stopPersistEffect();
+      });
+    }
+
     // 8. Run `connect(ctx)` lifecycle hook
     if (reg.definition.connect) {
+      const prevContext = activeControllerContext;
+      activeControllerContext = ctx;
       try {
         const userCleanup = reg.definition.connect(ctx);
         if (typeof userCleanup === 'function') {
           cleanupCallbacks.push(userCleanup);
         }
       } catch (err) {
+        handleControllerError(err, { phase: 'connect' });
         if (debug) {
           debug.trackCleanupError(instanceId, controllerName, 'connect', err);
         }
+      } finally {
+        activeControllerContext = prevContext;
       }
     }
 
@@ -814,7 +1688,9 @@ function createControllerRuntime(options = {}) {
       name: controllerName,
       el: rootEl,
       state,
+      tasks: tasksProxy,
       ctx,
+      invokeAction,
       actions: new Proxy({}, {
         get(_target, prop) {
           if (typeof prop === 'string') {
@@ -837,6 +1713,7 @@ function createControllerRuntime(options = {}) {
           try {
             reg.definition.disconnect(ctx);
           } catch (err) {
+            handleControllerError(err, { phase: 'disconnect' });
             if (debug) {
               debug.trackCleanupError(instanceId, controllerName, 'disconnect', err);
             }
@@ -887,6 +1764,8 @@ function createControllerRuntime(options = {}) {
 
         // Dispose isolated Datastar signals for this instance
         stateManager.dispose();
+        dynamicErrorListeners.clear();
+        lastError = null;
 
         const mapOnEl = elementInstances.get(rootEl);
         if (mapOnEl) {
@@ -1019,6 +1898,7 @@ function createControllerRuntime(options = {}) {
           api: defaultApi,
           datastar,
           debug,
+          services,
         });
         standaloneForms.set(formEl, handle);
       }
@@ -1043,6 +1923,7 @@ function createControllerRuntime(options = {}) {
 
   return {
     register,
+    services,
     hasController(name) {
       return definitions.has(name);
     },
@@ -1077,5 +1958,7 @@ module.exports = {
   createControllerRuntime,
   queryScopedTargets,
   isTargetInControllerScope,
+  watch,
+  getActiveControllerContext,
 };