webspresso 0.0.109 → 0.0.110

package/core/client/controller.js

@@ -17,8 +17,203 @@
 
 const { createFormHandle } = require('./forms');
 const { createApiClient } = require('./api');
+const { defaultStorage, createClientStorage } = require('./storage');
+const { decorateElement } = 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 (Array.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 Array.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 (Array.isArray(a) !== Array.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 (!Array.isArray(newArr) || !Array.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 (Array.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' && !Array.isArray(source))) && newValue && typeof newValue === 'object') {
+        deepTouch(newValue);
+      }
+    } catch (_err) {
+      return;
+    }
+
+    const isArr = Array.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 +228,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 +317,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 = Array.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 +359,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 (Array.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 (Array.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 (typeof persistOpt.debounce === 'number') {
+      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 +447,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));
     }
   }
 
@@ -201,11 +489,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) {
@@ -293,6 +588,48 @@ function createControllerRuntime(options = {}) {
     const scopedTasks = {};
     const scopedTasksList = [];
     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 = {}) {
@@ -398,6 +735,10 @@ function createControllerRuntime(options = {}) {
           }
           _error = err;
           updateSignal('error', err);
+          handleControllerError(err, {
+            task: taskKey,
+            phase: 'task',
+          });
           throw err;
         } finally {
           if (inFlightAbort === abortCtrl) {
@@ -470,6 +811,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 (Array.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' && !Array.isArray(source))) && newValue && typeof newValue === 'object') {
+            deepTouch(newValue);
+          }
+        } catch (err) {
+          handleError(err, 'watch:getter');
+          return;
+        }
+
+        const isArr = Array.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;
@@ -677,6 +1141,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,
@@ -691,10 +1173,20 @@ function createControllerRuntime(options = {}) {
       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 +1195,53 @@ 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 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 +1265,81 @@ 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' && !Array.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;
+      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;
+            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;
       }
     }
 
@@ -795,17 +1372,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;
       }
     }
 
@@ -815,6 +1434,7 @@ function createControllerRuntime(options = {}) {
       el: rootEl,
       state,
       ctx,
+      invokeAction,
       actions: new Proxy({}, {
         get(_target, prop) {
           if (typeof prop === 'string') {
@@ -837,6 +1457,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 +1508,8 @@ function createControllerRuntime(options = {}) {
 
         // Dispose isolated Datastar signals for this instance
         stateManager.dispose();
+        dynamicErrorListeners.clear();
+        lastError = null;
 
         const mapOnEl = elementInstances.get(rootEl);
         if (mapOnEl) {
@@ -1077,5 +1700,7 @@ module.exports = {
   createControllerRuntime,
   queryScopedTargets,
   isTargetInControllerScope,
+  watch,
+  getActiveControllerContext,
 };