webspresso 0.0.113 → 0.0.114

package/README.md

@@ -153,6 +153,31 @@ app.listen(PORT, () => {
 });
 ```
 
+### 5. Client Behavior Controller (`pages/notes.client.ts`)
+
+Co-locate reactive client logic right next to `pages/notes.njk` (`<div data-w-controller="notes">`) with automatic bundling and server-import boundary protection:
+
+```typescript
+import { defineController } from 'webspresso/client';
+
+export default defineController({
+  state: () => ({ title: '', saving: false }),
+  actions: {
+    async create(ctx) {
+      if (!ctx.state.title.trim()) return;
+      ctx.state.saving = true;
+      try {
+        await ctx.api.post('/api/notes', { title: ctx.state.title });
+        ctx.state.title = '';
+        await ctx.fragments.invalidate('notes'); // Refresh SSR fragments tagged with "notes"
+      } finally {
+        ctx.state.saving = false;
+      }
+    },
+  },
+});
+```
+
 ---
 
 ## ⚡ High-Performance Architecture (Cold Start & AOT)
@@ -202,6 +227,7 @@ Detailed topic guides are available in the repository:
 
 - **[Installation & First App](docs/getting-started/installation.md)** — Node.js requirements, setup, and first steps.
 - **[File-Based Routing & API Routes](.agents/ROUTING.md)** — Routing conventions, parameters, and cascading layouts.
+- **[Client Behavior & SSR Fragments](docs/guides/client-behavior.md)** — `defineController`, `defineFragment`, forms, and auto-revalidation.
 - **[SSR Streaming & Chunked Transfer](.agents/STREAMING.md)** — Out-of-order slots, `_loading.njk` skeletons, and TTFB optimization.
 - **[Database & ORM Guide](.agents/ORM.md)** — Repositories, relations, soft deletes, and ambient transactions.
 - **[Dual Authentication System](.agents/AUTH.md)** — Sessions, JWT rotation, magic links, and device management.

package/bin/commands/admin-password.js

@@ -3,13 +3,7 @@
  * Reset admin user password via CLI
  */
 
-let _inquirer;
-const inquirer = {
-  prompt: (...args) => {
-    if (!_inquirer) _inquirer = require('inquirer');
-    return _inquirer.prompt(...args);
-  },
-};
+const inquirer = require('../utils/prompt');
 const { loadDbConfig, createDbInstance } = require('../utils/db');
 
 function registerCommand(program) {

package/bin/commands/api.js

@@ -6,13 +6,7 @@
  * @module bin/commands/api
  */
 
-let _inquirer;
-const inquirer = {
-  prompt: (...args) => {
-    if (!_inquirer) _inquirer = require('inquirer');
-    return _inquirer.prompt(...args);
-  },
-};
+const inquirer = require('../utils/prompt');
 const fs = require('fs');
 const path = require('path');
 

package/bin/commands/new.js

@@ -3,13 +3,7 @@
  * Creates a new Webspresso project
  */
 
-let _inquirer;
-const inquirer = {
-  prompt: (...args) => {
-    if (!_inquirer) _inquirer = require('inquirer');
-    return _inquirer.prompt(...args);
-  },
-};
+const inquirer = require('../utils/prompt');
 const fs = require('fs');
 const path = require('path');
 

package/bin/commands/page.js

@@ -6,13 +6,7 @@
  * @module bin/commands/page
  */
 
-let _inquirer;
-const inquirer = {
-  prompt: (...args) => {
-    if (!_inquirer) _inquirer = require('inquirer');
-    return _inquirer.prompt(...args);
-  },
-};
+const inquirer = require('../utils/prompt');
 const fs = require('fs');
 const path = require('path');
 

package/bin/commands/seed.js

@@ -3,13 +3,7 @@
  * Run database seeders to populate database with fake data
  */
 
-let _inquirer;
-const inquirer = {
-  prompt: (...args) => {
-    if (!_inquirer) _inquirer = require('inquirer');
-    return _inquirer.prompt(...args);
-  },
-};
+const inquirer = require('../utils/prompt');
 const fs = require('fs');
 const path = require('path');
 const { execSync } = require('child_process');

package/bin/commands/service.js

@@ -5,13 +5,7 @@
  */
 
 const path = require('path');
-let _inquirer;
-const inquirer = {
-  prompt: (...args) => {
-    if (!_inquirer) _inquirer = require('inquirer');
-    return _inquirer.prompt(...args);
-  },
-};
+const inquirer = require('../utils/prompt');
 const { resolveDbConfigIfExists, createDbInstance } = require('../utils/db');
 
 /**

package/bin/utils/prompt.js

@@ -0,0 +1,17 @@
+/**
+ * Shared lazy ESM loader for Inquirer v13+ in CommonJS CLI commands.
+ */
+let _inquirer;
+
+const inquirer = {
+  async prompt(...args) {
+    if (!_inquirer) {
+      const mod = await import('inquirer');
+      _inquirer = mod.default || mod;
+    }
+    return _inquirer.prompt(...args);
+  },
+};
+
+module.exports = inquirer;
+

package/core/cache/tagged-lru.js

@@ -165,14 +165,18 @@ class TaggedLruCache {
   set(key, value, options = {}) {
     const tags = normalizeTags(options.tags);
 
-    // If key already had tags, clean them up first before assigning new tags
+    // Clear previous tags before lru.set so stale tags never survive if lru.set rejects (e.g. > maxBytes)
     if (this.keyToTags.has(key)) {
       this._removeKeyFromTags(key);
     }
 
-    this._addKeyToTags(key, tags);
+    // Run lru.set first so any internal _removeEntry('delete') on overwrite fires onEvict BEFORE we bind new tags
     this.lru.set(key, value, options);
 
+    if (tags.length > 0 && this.lru.has(key)) {
+      this._addKeyToTags(key, tags);
+    }
+
     return this;
   }
 
@@ -290,7 +294,9 @@ class TaggedLruCache {
       if (this.keyToTags.has(key)) {
         this._removeKeyFromTags(key);
       }
-      this._addKeyToTags(key, tags);
+      if (tags.length > 0 && this.lru.has(key)) {
+        this._addKeyToTags(key, tags);
+      }
     }
     return val;
   }

package/core/client/adapter/datastar.js

@@ -1026,6 +1026,21 @@ function syncFormControlValue(toEl, fromEl, ownership, preserveDraft) {
 function morphDomTrees(toEl, fromEl, ctx = {}) {
   if (!toEl || !fromEl) return toEl;
 
+  // Preserve an already-loaded lazy child fragment if a parent refresh sends a lazy placeholder
+  if (
+    toEl.hasAttribute &&
+    fromEl.hasAttribute &&
+    toEl.hasAttribute('data-w-fragment') &&
+    fromEl.hasAttribute('data-w-fragment') &&
+    !toEl.hasAttribute('data-w-lazy')
+  ) {
+    const incomingLazy = fromEl.getAttribute('data-w-lazy');
+    if (incomingLazy && incomingLazy !== 'false' && incomingLazy !== 'loaded') {
+      toEl.__wPreservedLazyChild = true;
+      return toEl;
+    }
+  }
+
   const rawOwnership = getClientOwnership(toEl);
   const ignoreMode = getIgnoreMode(toEl);
   const isForm = toEl.tagName === 'FORM';

package/core/client/api.js

@@ -693,6 +693,10 @@ function executeXhrUpload({ url, method, headers, body, credentials, signal, onU
 
     xhr.onload = () => {
       cleanup();
+      if (xhr.status === 0) {
+        reject(new TypeError('Network request failed'));
+        return;
+      }
       const status = xhr.status === 1223 ? 204 : xhr.status;
       const rawText = typeof xhr.responseText === 'string' ? xhr.responseText : '';
       const headerObj = parseXhrHeaders(xhr.getAllResponseHeaders ? xhr.getAllResponseHeaders() : '');

package/core/client/controller.js

@@ -2066,7 +2066,28 @@ function createControllerRuntime(options = {}) {
     return mounted;
   }
 
-  const patchCycleTracker = typeof WeakMap !== 'undefined' ? new WeakMap() : null;
+  let activeHookContext = null;
+
+  function isInsideIgnoredSubtree(el, rootEl) {
+    let cur = el && el.parentElement ? el.parentElement : null;
+    while (cur) {
+      if (typeof cur.hasAttribute === 'function' && cur.hasAttribute('data-w-ignore')) {
+        const mode = (cur.getAttribute('data-w-ignore') || '').trim().toLowerCase();
+        if (mode !== 'self') {
+          return true;
+        }
+      }
+      if (cur === rootEl) break;
+      cur = cur.parentElement || null;
+    }
+    if (el === rootEl && el && typeof el.hasAttribute === 'function' && el.hasAttribute('data-w-ignore')) {
+      const mode = (el.getAttribute('data-w-ignore') || '').trim().toLowerCase();
+      if (mode === 'all' || mode === 'both') {
+        return true;
+      }
+    }
+    return false;
+  }
 
   function collectAffectedInstances(fragmentEl) {
     if (!fragmentEl) return [];
@@ -2078,6 +2099,7 @@ function createControllerRuntime(options = {}) {
         (typeof fragmentEl.contains === 'function' && fragmentEl.contains(inst.el)) ||
         (typeof inst.el.contains === 'function' && inst.el.contains(fragmentEl))
       ) {
+        if (isInsideIgnoredSubtree(inst.el, fragmentEl)) continue;
         affected.push(inst);
       }
     }
@@ -2098,47 +2120,60 @@ function createControllerRuntime(options = {}) {
 
   function notifyBeforePatch(fragmentEl, meta = {}) {
     const affected = collectAffectedInstances(fragmentEl);
-    for (let i = 0; i < affected.length; i++) {
-      const inst = affected[i];
-      inst.invokeBeforePatch({
-        ...meta,
-        isFragmentRoot: inst.el === fragmentEl,
-        isDescendant: inst.el !== fragmentEl && typeof fragmentEl.contains === 'function' && fragmentEl.contains(inst.el),
-      });
+    const prevHookCtx = activeHookContext;
+    activeHookContext = {
+      fragmentEl,
+      depth: meta && typeof meta.hookChainDepth === 'number' ? meta.hookChainDepth : 0,
+    };
+    try {
+      for (let i = 0; i < affected.length; i++) {
+        const inst = affected[i];
+        inst.invokeBeforePatch({
+          ...meta,
+          isFragmentRoot: inst.el === fragmentEl,
+          isDescendant: inst.el !== fragmentEl && typeof fragmentEl.contains === 'function' && fragmentEl.contains(inst.el),
+        });
+      }
+    } finally {
+      activeHookContext = prevHookCtx;
     }
   }
 
   function notifyAfterPatch(fragmentEl, meta = {}) {
-    if (patchCycleTracker && fragmentEl) {
-      const now = Date.now();
-      const prev = patchCycleTracker.get(fragmentEl) || { count: 0, lastAt: 0 };
-      const count = now - prev.lastAt < 100 ? prev.count + 1 : 1;
-      patchCycleTracker.set(fragmentEl, { count, lastAt: now });
-      if (count > 5) {
-        const msg = `Possible patch hook refresh loop detected on fragment "${meta.fragmentName || meta.fragmentId || 'unknown'}" (${count} rapid patch cycles).`;
-        if (debug && typeof debug.recordEvent === 'function') {
-          debug.recordEvent('patch:loop-warning', {
-            code: 'PATCH_HOOK_LOOP_DETECTED',
-            fragmentId: meta.fragmentId || null,
-            fragmentName: meta.fragmentName || null,
-            count,
-            message: msg,
-          });
-        } else if (typeof process !== 'undefined' && process.env && process.env.NODE_ENV !== 'production' && typeof console !== 'undefined') {
-          console.warn(`[webspresso] ${msg}`);
-        }
+    const chainDepth = meta && typeof meta.hookChainDepth === 'number' ? meta.hookChainDepth : 0;
+    if (chainDepth > 3) {
+      const msg = `Possible patch hook refresh loop detected on fragment "${meta.fragmentName || meta.fragmentId || 'unknown'}" (causal chain depth ${chainDepth}).`;
+      if (debug && typeof debug.recordEvent === 'function') {
+        debug.recordEvent('patch:loop-warning', {
+          code: 'PATCH_HOOK_LOOP_DETECTED',
+          fragmentId: meta.fragmentId || null,
+          fragmentName: meta.fragmentName || null,
+          count: chainDepth,
+          message: msg,
+        });
+      } else if (typeof process !== 'undefined' && process.env && process.env.NODE_ENV !== 'production' && typeof console !== 'undefined') {
+        console.warn(`[webspresso] ${msg}`);
       }
     }
 
     const affected = collectAffectedInstances(fragmentEl);
-    // Reverse order for afterPatch: inner descendants first, outer ancestors second
-    for (let i = affected.length - 1; i >= 0; i--) {
-      const inst = affected[i];
-      inst.invokeAfterPatch({
-        ...meta,
-        isFragmentRoot: inst.el === fragmentEl,
-        isDescendant: inst.el !== fragmentEl && typeof fragmentEl.contains === 'function' && fragmentEl.contains(inst.el),
-      });
+    const prevHookCtx = activeHookContext;
+    activeHookContext = {
+      fragmentEl,
+      depth: chainDepth,
+    };
+    try {
+      // Reverse order for afterPatch: inner descendants first, outer ancestors second
+      for (let i = affected.length - 1; i >= 0; i--) {
+        const inst = affected[i];
+        inst.invokeAfterPatch({
+          ...meta,
+          isFragmentRoot: inst.el === fragmentEl,
+          isDescendant: inst.el !== fragmentEl && typeof fragmentEl.contains === 'function' && fragmentEl.contains(inst.el),
+        });
+      }
+    } finally {
+      activeHookContext = prevHookCtx;
     }
   }
 
@@ -2157,6 +2192,9 @@ function createControllerRuntime(options = {}) {
     unmountSubtree,
     notifyBeforePatch,
     notifyAfterPatch,
+    getActivePatchHookContext() {
+      return activeHookContext;
+    },
     mountControllerOnElement,
     getInstanceForElement(el, name) {
       const map = elementInstances.get(el);

package/core/client/forms.js

@@ -469,6 +469,7 @@ function createFormHandle(formEl, options = {}) {
   const validationSeqByField = new Map();
   const validationTimersByField = new Map();
   const validationAbortByField = new Map();
+  let validationEpoch = 0;
 
   let activeSubmitAbort = null;
   let uploadEntries = [];
@@ -476,6 +477,7 @@ function createFormHandle(formEl, options = {}) {
 
   function cancelFieldValidation(fieldName) {
     if (fieldName) {
+      validationSeqByField.set(fieldName, (validationSeqByField.get(fieldName) || 0) + 1);
       const t = validationTimersByField.get(fieldName);
       if (t) {
         clearTimeout(t);
@@ -490,6 +492,7 @@ function createFormHandle(formEl, options = {}) {
       }
       return;
     }
+    validationEpoch += 1;
     for (const t of validationTimersByField.values()) clearTimeout(t);
     validationTimersByField.clear();
     for (const ac of validationAbortByField.values()) {
@@ -1324,6 +1327,7 @@ function createFormHandle(formEl, options = {}) {
     if (!formEl || !api || !fieldName) return { ok: true, valid: true, errors: {} };
     const norm = fieldName.endsWith('[]') ? fieldName.slice(0, -2) : fieldName;
 
+    const epoch = validationEpoch;
     const seq = (validationSeqByField.get(norm) || 0) + 1;
     validationSeqByField.set(norm, seq);
 
@@ -1368,7 +1372,7 @@ function createFormHandle(formEl, options = {}) {
         signal: ac.signal,
       });
 
-      if (seq !== validationSeqByField.get(norm)) {
+      if (epoch !== validationEpoch || seq !== validationSeqByField.get(norm)) {
         return { ok: true, stale: true, valid: true, errors: {} };
       }
 
@@ -1386,7 +1390,7 @@ function createFormHandle(formEl, options = {}) {
         errors: fieldErrors[norm] ? { [norm]: fieldErrors[norm] } : {},
       };
     } catch (err) {
-      if (seq !== validationSeqByField.get(norm) || (err && err.isCanceled)) {
+      if (epoch !== validationEpoch || seq !== validationSeqByField.get(norm) || (err && err.isCanceled)) {
         return { ok: true, stale: true, canceled: Boolean(err && err.isCanceled), errors: {} };
       }
       // If server returned a 400/422 validation envelope, extract only this field's error

package/core/client/fragments.js

@@ -157,8 +157,9 @@ function createFragmentCoordinator(options = {}) {
   let isDisposed = false;
   let lifecycleListenersAttached = false;
 
-  // Per-version patch options (mode, limit, target, removeKeys, onBeforePatch, onAfterPatch)
+  // Per-version patch options (mode, limit, target, removeKeys, onBeforePatch, onAfterPatch, hookChainDepth)
   const pendingPatchOptsByKey = new Map();
+  let pendingInvalidateHookDepth = 0;
 
   // Lazy fragment IntersectionObserver state
   let lazyObserver = null;
@@ -792,16 +793,21 @@ function createFragmentCoordinator(options = {}) {
       pendingPatchOptsByKey.delete(patchKey);
     }
 
+    const patchMeta = {
+      hookChainDepth: (patchOpts && patchOpts.hookChainDepth) || 0,
+    };
+
     if (typeof options.onBeforePatch === 'function') {
-      options.onBeforePatch(inst.el, inst);
+      options.onBeforePatch(inst.el, inst, patchMeta);
     }
     if (patchOpts && typeof patchOpts.onBeforePatch === 'function') {
       try {
-        patchOpts.onBeforePatch(inst.el, inst);
+        patchOpts.onBeforePatch(inst.el, inst, patchMeta);
       } catch (_e) {}
     }
 
     const patchStart = Date.now();
+    const patchMode = fragmentPayload.mode || (patchOpts && patchOpts.mode) || 'replace';
 
     const committedInput =
       fragmentPayload.input && typeof fragmentPayload.input === 'object' && !isArray(fragmentPayload.input)
@@ -811,6 +817,8 @@ function createFragmentCoordinator(options = {}) {
           : null;
 
     if (
+      patchMode !== 'append' &&
+      patchMode !== 'prepend' &&
       committedInput &&
       !followUpNeeded &&
       pendingTags.size === 0
@@ -827,7 +835,16 @@ function createFragmentCoordinator(options = {}) {
       }
     }
 
-    const patchMode = fragmentPayload.mode || (patchOpts && patchOpts.mode) || 'replace';
+    // Track existing strict descendant fragments before replace morph so removed children can be cleaned up
+    const prevDescendants = [];
+    if (patchMode !== 'append' && patchMode !== 'prepend') {
+      for (const otherInst of instances.values()) {
+        if (otherInst !== inst && otherInst.el && isStrictAncestor(inst.el, otherInst.el)) {
+          prevDescendants.push(otherInst);
+        }
+      }
+    }
+
     if (patchMode === 'append' || patchMode === 'prepend') {
       patchIncrementalList(inst.el, html, {
         mode: patchMode,
@@ -861,20 +878,40 @@ function createFragmentCoordinator(options = {}) {
     const now = Date.now();
     inst.lastUpdatedAt = now;
 
+    // Clean up any nested child fragments removed during this parent patch
+    for (let i = 0; i < prevDescendants.length; i++) {
+      const prevChild = prevDescendants[i];
+      if (!prevChild.el || prevChild.el.isConnected === false || !isStrictAncestor(inst.el, prevChild.el)) {
+        clearInstanceInterval(prevChild);
+        unobserveLazyFragment(prevChild);
+        if (prevChild.abortController) {
+          try {
+            prevChild.abortController.abort();
+          } catch (_e) {}
+          prevChild.abortController = null;
+        }
+        instances.delete(prevChild.instanceId);
+      }
+    }
+
     // Re-sync nested fragment instances that may have been updated inside this parent fragment
     scanDomInstances(inst.el);
     for (const otherInst of instances.values()) {
       if (otherInst !== inst && otherInst.el && isStrictAncestor(inst.el, otherInst.el)) {
-        otherInst.lastUpdatedAt = now;
+        if (otherInst.el.__wPreservedLazyChild) {
+          delete otherInst.el.__wPreservedLazyChild;
+        } else if (!(otherInst.lazy && otherInst.lazyState === 'idle')) {
+          otherInst.lastUpdatedAt = now;
+        }
       }
     }
 
     if (typeof options.onAfterPatch === 'function') {
-      options.onAfterPatch(inst.el, inst);
+      options.onAfterPatch(inst.el, inst, patchMeta);
     }
     if (patchOpts && typeof patchOpts.onAfterPatch === 'function') {
       try {
-        patchOpts.onAfterPatch(inst.el, inst);
+        patchOpts.onAfterPatch(inst.el, inst, patchMeta);
       } catch (_e) {}
     }
 
@@ -1339,8 +1376,16 @@ function createFragmentCoordinator(options = {}) {
     // Parent/Child deduplication: if parent & child are both invalidated, parent refresh covers child
     const dedupedInstances = deduplicateParentChildFragments(matchingInstances);
 
+    const batchHookDepth = pendingInvalidateHookDepth;
+    pendingInvalidateHookDepth = 0;
+
     const targets = dedupedInstances.map((inst) => {
       inst.version += 1;
+      if (batchHookDepth > 0) {
+        pendingPatchOptsByKey.set(`${inst.instanceId}:${inst.version}`, {
+          hookChainDepth: batchHookDepth,
+        });
+      }
       return {
         instanceId: inst.instanceId,
         name: inst.name,
@@ -1385,6 +1430,13 @@ function createFragmentCoordinator(options = {}) {
    * @returns {Promise<{ refreshed: string[], skipped?: boolean }>}
    */
   function invalidate(tags, meta = {}) {
+    const activeHook = typeof options.getPatchHookContext === 'function' ? options.getPatchHookContext() : null;
+    if (activeHook) {
+      const nextDepth = (activeHook.depth || 0) + 1;
+      if (nextDepth > pendingInvalidateHookDepth) {
+        pendingInvalidateHookDepth = nextDepth;
+      }
+    }
     const tagList = isArray(tags) ? tags : [tags];
     for (const raw of tagList) {
       if (typeof raw === 'string' && raw.trim()) {
@@ -1480,11 +1532,15 @@ function createFragmentCoordinator(options = {}) {
         unobserveLazyFragment(inst);
       }
 
+      const activeHook = typeof options.getPatchHookContext === 'function' ? options.getPatchHookContext() : null;
+      const hookChainDepth = activeHook ? (activeHook.depth || 0) + 1 : 0;
+
       if (
         refreshOpts.mode ||
         refreshOpts.limit !== undefined ||
         refreshOpts.target ||
         refreshOpts.removeKeys ||
+        hookChainDepth > 0 ||
         typeof refreshOpts.onBeforePatch === 'function' ||
         typeof refreshOpts.onAfterPatch === 'function'
       ) {
@@ -1493,6 +1549,7 @@ function createFragmentCoordinator(options = {}) {
           limit: refreshOpts.limit,
           target: refreshOpts.target,
           removeKeys: refreshOpts.removeKeys,
+          hookChainDepth,
           onBeforePatch: refreshOpts.onBeforePatch,
           onAfterPatch: refreshOpts.onAfterPatch,
         });

package/core/client/index.js

@@ -192,20 +192,25 @@ function createClientRuntime(options = {}) {
         controllers.mountSubtree(addedEl);
       }
     },
-    onBeforePatch(patchedEl, inst) {
+    getPatchHookContext() {
+      return controllers ? controllers.getActivePatchHookContext() : null;
+    },
+    onBeforePatch(patchedEl, inst, meta) {
       if (controllers) {
         controllers.notifyBeforePatch(patchedEl, {
           fragmentId: inst && inst.instanceId ? inst.instanceId : null,
           fragmentName: inst && inst.name ? inst.name : null,
+          hookChainDepth: meta && meta.hookChainDepth ? meta.hookChainDepth : 0,
         });
       }
     },
-    onAfterPatch(patchedEl, inst) {
+    onAfterPatch(patchedEl, inst, meta) {
       if (controllers) {
         controllers.mountSubtree(patchedEl);
         controllers.notifyAfterPatch(patchedEl, {
           fragmentId: inst && inst.instanceId ? inst.instanceId : null,
           fragmentName: inst && inst.name ? inst.name : null,
+          hookChainDepth: meta && meta.hookChainDepth ? meta.hookChainDepth : 0,
         });
       }
     },

package/core/client/server-fragments.js

@@ -646,6 +646,17 @@ async function executeAndRenderFragment({
   };
 }
 
+function getPluginRegisteredFragment(name) {
+  try {
+    const { getPluginManager } = require('../plugins/plugin-manager');
+    const pm = typeof getPluginManager === 'function' ? getPluginManager() : null;
+    if (pm && typeof pm.getFragment === 'function') {
+      return pm.getFragment(name) || null;
+    }
+  } catch (_e) {}
+  return null;
+}
+
 /**
  * Create the `fsy.fragment(name, input?, options?)` template helper for a page render pass.
  * Uses the exact same `executeAndRenderFragment` pipeline for initial SSR as subsequent refreshes!
@@ -665,7 +676,9 @@ function attachSsrFragmentHelper({ req, res, ctx, pageMod, pagePath, nunjucksEnv
 
   function renderFragmentHelper(name, rawInput = {}, options = {}) {
     const cleanName = String(name || '').trim();
-    const fragmentDef = fragmentsMap[cleanName];
+    const fragmentDef =
+      (Object.prototype.hasOwnProperty.call(fragmentsMap, cleanName) ? fragmentsMap[cleanName] : null) ||
+      getPluginRegisteredFragment(cleanName);
     if (!fragmentDef) {
       throw new NotFoundError(
         `Fragment "${cleanName}" is not defined in fragments export for page "${pagePath}".`
@@ -898,9 +911,10 @@ function createFragmentRefreshHandler(config) {
       req.params = { ...(req.params || {}), ...params };
 
       const pageMod = typeof entry.getPageMod === 'function' ? entry.getPageMod() : entry.pageMod;
-      const fragmentsMap = (pageMod && pageMod.fragments) || {};
+      const pageFragmentsMap = (pageMod && pageMod.fragments) || {};
+      const fragmentsMap = { ...pageFragmentsMap };
 
-      // Validate that all requested fragments are registered on this page BEFORE running loaders
+      // Validate that all requested fragments are registered on this page (or by a plugin) BEFORE running loaders
       // (Rejects arbitrary template paths or unknown fragment names)
       for (const item of requestedFragments) {
         if (!item || typeof item.name !== 'string' || !item.name.trim()) {
@@ -910,7 +924,12 @@ function createFragmentRefreshHandler(config) {
           throw new BadRequestError('Client cannot specify arbitrary template paths in fragment refresh requests.');
         }
         if (!Object.prototype.hasOwnProperty.call(fragmentsMap, item.name)) {
-          throw new NotFoundError(`Fragment "${item.name}" is not registered on page "${entry.routePath}".`);
+          const pluginFrag = getPluginRegisteredFragment(item.name);
+          if (pluginFrag) {
+            fragmentsMap[item.name] = pluginFrag;
+          } else {
+            throw new NotFoundError(`Fragment "${item.name}" is not registered on page "${entry.routePath}".`);
+          }
         }
       }
 

package/core/console/commands.js

@@ -6,6 +6,8 @@
  * @module core/console/commands
  */
 
+const fs = require('fs');
+const path = require('path');
 const { discoverAppRoutes } = require('../../src/discovery/scan-routes');
 
 /**
@@ -50,9 +52,12 @@ function registerConsoleCommands(replServer, { context, meta, rootDir }) {
         } else {
           console.log(`\n⚙️  Registered Services (${services.length}):`);
           for (const s of services) {
-            console.log(`  • \x1b[32m${s.name}\x1b[0m ${s.description ? `(${s.description})` : ''}`);
+            const name = typeof s === 'string' ? s : (s?.name || String(s));
+            const desc = typeof s === 'object' && s?.description ? `(${s.description})` : '';
+            console.log(`  • \x1b[32m${name}\x1b[0m ${desc}`);
           }
-          console.log('\n  Tip: Call a service with: await service(\'' + services[0].name + '\', payload)\n');
+          const firstName = typeof services[0] === 'string' ? services[0] : (services[0]?.name || String(services[0]));
+          console.log('\n  Tip: Call a service with: await service(\'' + firstName + '\', payload)\n');
         }
       }
       this.displayPrompt();
@@ -64,7 +69,14 @@ function registerConsoleCommands(replServer, { context, meta, rootDir }) {
     help: 'Scan and list all application API endpoints and SSR pages',
     action() {
       try {
-        const result = discoverAppRoutes({ rootDir });
+        const pagesApiDir = ['src/pages/api', 'pages/api']
+          .map((rel) => path.join(rootDir, rel))
+          .find((p) => fs.existsSync(p));
+        const hasStandaloneApi = ['src/api', 'api'].some((rel) => fs.existsSync(path.join(rootDir, rel)));
+        const result = discoverAppRoutes({
+          rootDir,
+          ...(!hasStandaloneApi && pagesApiDir ? { api: { dir: pagesApiDir, prefix: '/api' } } : {}),
+        });
         const descriptors = result.descriptors || [];
 
         if (descriptors.length === 0) {
@@ -101,10 +113,19 @@ function registerConsoleCommands(replServer, { context, meta, rootDir }) {
   replServer.defineCommand('flags', {
     help: 'List all active feature flags and targeting rules',
     action() {
-      if (!context.flags || typeof context.flags.list !== 'function') {
+      if (!context.flags) {
         console.log('\n⚠️  No feature flags configured.\n');
       } else {
-        const flags = context.flags.list();
+        const flags = typeof context.flags.list === 'function'
+          ? context.flags.list()
+          : (typeof context.flags.store?.getAll === 'function'
+            ? context.flags.store.getAll()
+            : (typeof context.flags.getAllFlags === 'function' ? context.flags.getAllFlags() : null));
+        if (!flags || typeof flags !== 'object') {
+          console.log('\n⚠️  No feature flags configured.\n');
+          this.displayPrompt();
+          return;
+        }
         const entries = Object.entries(flags);
         if (entries.length === 0) {
           console.log('\n⚠️  No feature flags registered.\n');

package/core/console/repl.js

@@ -7,6 +7,7 @@
  * @module core/console/repl
  */
 
+const fs = require('fs');
 const repl = require('repl');
 const path = require('path');
 const { buildConsoleContext } = require('./context');
@@ -67,7 +68,12 @@ async function startConsole(options = {}) {
   if (options.history !== false && typeof replServer.setupHistory === 'function') {
     const historyPath = options.historyPath || path.resolve(meta.rootDir, '.webspresso_history');
     try {
-      replServer.setupHistory(historyPath, () => {});
+      if (fs.existsSync(path.dirname(historyPath))) {
+        const res = replServer.setupHistory(historyPath, () => {});
+        if (res && typeof res.catch === 'function') {
+          res.catch(() => {});
+        }
+      }
     } catch (_) {
       // Gracefully continue without persistent history if write fails
     }

package/core/plugins/plugin-manager.js

@@ -147,6 +147,9 @@ class PluginManager {
     this.routes = [];                   // Collected route metadata
     this.customRoutes = [];             // Routes added by plugins
     this.cspDirectives = new Map();     // directive -> Set of sources (from plugins)
+    this.clientControllers = new Map(); // name -> { name, filePath, pluginName }
+    this.clientServices = new Map();    // name -> { name, filePath, pluginName }
+    this.registeredFragments = new Map(); // name -> { name, def, pluginName }
     this.disposers = [];                // Array<{ name: string, fn: Function }>
     this._cachedHelpers = null;         // Cached helpers object
     this.pendingAsyncOperations = [];   // Track background promises
@@ -271,7 +274,7 @@ class PluginManager {
 
     // Build graph
     for (const plugin of plugins) {
-      if (!plugin.name) {
+      if (!plugin || !plugin.name) {
         console.warn('[plugin-manager] Skipping plugin without name:', plugin);
         continue;
       }
@@ -730,6 +733,33 @@ class PluginManager {
        */
       getScriptInjector() {
         return getCachedScriptInjector();
+      },
+
+      /**
+       * Register a client controller entry file (`.client.js` / `.client.ts`) for bundler discovery
+       * @param {string} name - Controller name used in `data-w-controller="<name>"`
+       * @param {string} filePath - Absolute or project-relative path to the client controller module
+       */
+      registerClientController(name, filePath) {
+        self.registerClientController(name, filePath, pluginName);
+      },
+
+      /**
+       * Register a client service module (`defineClientService(...)`) for bundler discovery
+       * @param {string} name - Service name used in `ctx.services.get('<name>')`
+       * @param {string} filePath - Absolute or project-relative path to the client service module
+       */
+      registerClientService(name, filePath) {
+        self.registerClientService(name, filePath, pluginName);
+      },
+
+      /**
+       * Register a reusable SSR fragment (`defineFragment(...)`) usable across pages
+       * @param {string} name - Fragment name used in `fsy.fragment('<name>', ...)`
+       * @param {Object} fragmentDef - Fragment definition created via `defineFragment(...)`
+       */
+      registerFragment(name, fragmentDef) {
+        self.registerFragment(name, fragmentDef, pluginName);
       }
     };
   }
@@ -808,6 +838,130 @@ class PluginManager {
     }
   }
 
+  /**
+   * Register a client controller module from a plugin.
+   * @param {string} name
+   * @param {string} filePath
+   * @param {string} [pluginName='unknown']
+   */
+  registerClientController(name, filePath, pluginName = 'unknown') {
+    const cleanName = typeof name === 'string' ? name.trim() : '';
+    const cleanPath = typeof filePath === 'string' ? filePath.trim() : '';
+    if (!cleanName || !cleanPath) {
+      throw new TypeError(`[plugin-manager] registerClientController(name, filePath) requires non-empty strings (plugin "${pluginName}").`);
+    }
+    const existing = this.clientControllers.get(cleanName);
+    if (existing && existing.filePath !== cleanPath) {
+      const err = new Error(
+        `Client controller name collision: "${cleanName}" is registered by both plugin "${existing.pluginName}" (${existing.filePath}) and "${pluginName}" (${cleanPath}).`
+      );
+      err.code = 'PLUGIN_CLIENT_CONTROLLER_COLLISION';
+      throw err;
+    }
+    this.clientControllers.set(cleanName, {
+      name: cleanName,
+      filePath: cleanPath,
+      pluginName,
+    });
+  }
+
+  /**
+   * Register a client service module from a plugin.
+   * @param {string} name
+   * @param {string} filePath
+   * @param {string} [pluginName='unknown']
+   */
+  registerClientService(name, filePath, pluginName = 'unknown') {
+    const cleanName = typeof name === 'string' ? name.trim() : '';
+    const cleanPath = typeof filePath === 'string' ? filePath.trim() : '';
+    if (!cleanName || !cleanPath) {
+      throw new TypeError(`[plugin-manager] registerClientService(name, filePath) requires non-empty strings (plugin "${pluginName}").`);
+    }
+    const existing = this.clientServices.get(cleanName);
+    if (existing && existing.filePath !== cleanPath) {
+      const err = new Error(
+        `Client service name collision: "${cleanName}" is registered by both plugin "${existing.pluginName}" (${existing.filePath}) and "${pluginName}" (${cleanPath}).`
+      );
+      err.code = 'PLUGIN_CLIENT_SERVICE_COLLISION';
+      throw err;
+    }
+    this.clientServices.set(cleanName, {
+      name: cleanName,
+      filePath: cleanPath,
+      pluginName,
+    });
+  }
+
+  /**
+   * Register a reusable SSR fragment definition from a plugin.
+   * @param {string} name
+   * @param {Object} fragmentDef
+   * @param {string} [pluginName='unknown']
+   */
+  registerFragment(name, fragmentDef, pluginName = 'unknown') {
+    const cleanName = typeof name === 'string' ? name.trim() : '';
+    if (!cleanName || !fragmentDef || typeof fragmentDef !== 'object') {
+      throw new TypeError(`[plugin-manager] registerFragment(name, fragmentDef) requires a valid fragment name and definition (plugin "${pluginName}").`);
+    }
+    if (this.registeredFragments.has(cleanName)) {
+      console.warn(`[plugin-manager] Fragment "${cleanName}" is already registered (registered by "${pluginName}" overwrites existing fragment).`);
+    }
+    this.registeredFragments.set(cleanName, {
+      name: cleanName,
+      def: fragmentDef,
+      pluginName,
+    });
+  }
+
+  /**
+   * Get all client controllers registered by plugins.
+   * @returns {Array<{ name: string, filePath: string, pluginName: string }>}
+   */
+  getClientControllers() {
+    return Array.from(this.clientControllers.values());
+  }
+
+  /**
+   * Get all client services registered by plugins.
+   * @returns {Array<{ name: string, filePath: string, pluginName: string }>}
+   */
+  getClientServices() {
+    return Array.from(this.clientServices.values());
+  }
+
+  /**
+   * Look up a plugin-registered fragment definition by name.
+   * @param {string} name
+   * @returns {Object|null}
+   */
+  getFragment(name) {
+    const entry = this.registeredFragments.get(name);
+    return entry ? entry.def : null;
+  }
+
+  /**
+   * Get all plugin-registered fragments as a plain map `{ [name]: fragmentDef }`.
+   * @returns {Record<string, Object>}
+   */
+  getFragments() {
+    const out = {};
+    for (const [name, entry] of this.registeredFragments) {
+      out[name] = entry.def;
+    }
+    return out;
+  }
+
+  /**
+   * Get combined client manifest of controllers, services, and fragment names registered by plugins.
+   */
+  getClientManifest() {
+    return {
+      controllers: this.getClientControllers(),
+      services: this.getClientServices(),
+      fragments: Array.from(this.registeredFragments.keys()),
+    };
+  }
+
   /**
    * Register a request-scoped helper provider (called on each SSR request)
    * @param {Function} fn - (req) => Record<string, any>

package/index.d.ts

@@ -1919,6 +1919,9 @@ export interface PluginRegisterContext {
   addHelper(name: string, fn: (...args: unknown[]) => unknown): void;
   addFilter(name: string, fn: (...args: unknown[]) => unknown): void;
   addRoute(method: string, path: string, ...handlers: RequestHandler[]): void;
+  registerClientController(name: string, filePath: string): void;
+  registerClientService(name: string, filePath: string): void;
+  registerFragment(name: string, fragmentDef: FragmentDefinition<any, any>): void;
   routes: unknown;
   [key: string]: unknown;
 }
@@ -1936,6 +1939,18 @@ export interface WebspressoPlugin {
 }
 
 export class PluginManager {
+  registerClientController(name: string, filePath: string, pluginName?: string): void;
+  registerClientService(name: string, filePath: string, pluginName?: string): void;
+  registerFragment(name: string, fragmentDef: FragmentDefinition<any, any>, pluginName?: string): void;
+  getClientControllers(): Array<{ name: string; filePath: string; pluginName: string }>;
+  getClientServices(): Array<{ name: string; filePath: string; pluginName: string }>;
+  getFragment(name: string): FragmentDefinition<any, any> | null;
+  getFragments(): Record<string, FragmentDefinition<any, any>>;
+  getClientManifest(): {
+    controllers: Array<{ name: string; filePath: string; pluginName: string }>;
+    services: Array<{ name: string; filePath: string; pluginName: string }>;
+    fragments: string[];
+  };
   [key: string]: unknown;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webspresso",
-  "version": "0.0.113",
+  "version": "0.0.114",
   "description": "Minimal, production-ready SSR framework for Node.js with file-based routing, Nunjucks templating, built-in i18n, and CLI tooling",
   "main": "index.js",
   "types": "index.d.ts",
@@ -134,14 +134,14 @@
     "views/partials/webspresso-client-runtime.njk"
   ],
   "dependencies": {
-    "commander": "^11.1.0",
+    "commander": "^14.0.3",
     "cookie-parser": "^1.4.7",
     "csv-parse": "^7.0.2",
     "dayjs": "^1.11.19",
     "express": "^5.2.1",
     "express-session": "^1.18.0",
-    "helmet": "^7.2.0",
-    "inquirer": "^8.2.6",
+    "helmet": "^8.3.0",
+    "inquirer": "^13.4.3",
     "knex": "^3.1.0",
     "multer": "^2.4.0",
     "nunjucks": "^3.2.4",

package/src/bundle/index.js

@@ -213,22 +213,52 @@ function findPageEntryPoints(cwd = process.cwd()) {
     walkViews(dirToScan);
   }
 
+  // 4. Plugin-registered client controllers and services (if PluginManager is active)
+  try {
+    const { getPluginManager } = require('../../core/plugins/plugin-manager');
+    const pm = typeof getPluginManager === 'function' ? getPluginManager() : null;
+    if (pm) {
+      if (typeof pm.getClientControllers === 'function') {
+        for (const ctrl of pm.getClientControllers()) {
+          const entryName = `plugins/${ctrl.pluginName}/${ctrl.name}`;
+          if (!pageEntries[entryName]) {
+            pageEntries[entryName] = path.isAbsolute(ctrl.filePath)
+              ? ctrl.filePath
+              : path.resolve(cwd, ctrl.filePath);
+          }
+        }
+      }
+      if (typeof pm.getClientServices === 'function') {
+        for (const svc of pm.getClientServices()) {
+          const entryName = `plugins/${svc.pluginName}/services/${svc.name}`;
+          if (!pageEntries[entryName]) {
+            pageEntries[entryName] = path.isAbsolute(svc.filePath)
+              ? svc.filePath
+              : path.resolve(cwd, svc.filePath);
+          }
+        }
+      }
+    }
+  } catch (_e) {}
+
   return pageEntries;
 }
 
 /**
- * Discovers all `.client.{js,ts,mjs,jsx,tsx}` controller files across `pages/` and `views/`
+ * Discovers all `.client.{js,ts,mjs,jsx,tsx}` controller files across `pages/`, `views/`, and plugins
  * and validates deterministic controller names for collisions.
  *
  * @param {string} [cwd=process.cwd()]
- * @returns {Array<{ controllerName: string, entryName: string, filePath: string, relativePath: string }>}
+ * @param {object} [options]
+ * @returns {Array<{ controllerName: string, entryName: string, filePath: string, relativePath: string, pluginName?: string }>}
  */
-function discoverClientControllers(cwd = process.cwd()) {
+function discoverClientControllers(cwd = process.cwd(), options = {}) {
   const pageEntries = findPageEntryPoints(cwd);
   const discovered = [];
   const byControllerName = new Map();
 
   for (const [entryName, filePath] of Object.entries(pageEntries)) {
+    if (entryName.startsWith('plugins/')) continue;
     const relativePath = path.relative(cwd, filePath).replace(/\\/g, '/');
     const controllerName = deriveControllerNameFromPath(relativePath);
     if (!controllerName) continue;
@@ -256,6 +286,46 @@ function discoverClientControllers(cwd = process.cwd()) {
     discovered.push(record);
   }
 
+  try {
+    const pm =
+      options.pluginManager ||
+      require('../../core/plugins/plugin-manager').getPluginManager();
+    if (pm && typeof pm.getClientControllers === 'function') {
+      for (const ctrl of pm.getClientControllers()) {
+        const absPath = path.isAbsolute(ctrl.filePath)
+          ? ctrl.filePath
+          : path.resolve(cwd, ctrl.filePath);
+        const relativePath = path.relative(cwd, absPath).replace(/\\/g, '/');
+        if (byControllerName.has(ctrl.name)) {
+          const existing = byControllerName.get(ctrl.name);
+          if (existing.filePath !== absPath) {
+            const err = new Error(
+              `Controller name collision: "${ctrl.name}" is defined by both "${existing.relativePath}" and "${relativePath}".`
+            );
+            err.code = 'CONTROLLER_NAME_COLLISION';
+            err.controllerName = ctrl.name;
+            err.files = [existing.relativePath, relativePath];
+            throw err;
+          }
+          continue;
+        }
+        const record = {
+          controllerName: ctrl.name,
+          entryName: `plugins/${ctrl.pluginName}/${ctrl.name}`,
+          filePath: absPath,
+          relativePath,
+          pluginName: ctrl.pluginName,
+        };
+        byControllerName.set(ctrl.name, record);
+        discovered.push(record);
+      }
+    }
+  } catch (err) {
+    if (err && err.code === 'CONTROLLER_NAME_COLLISION') {
+      throw err;
+    }
+  }
+
   return discovered;
 }
 

package/src/dev-reload/index.js

@@ -168,8 +168,39 @@ const CLIENT_RUNTIME_SCRIPT = `(function() {
     document.addEventListener('keydown', onKeyDown);
   }
 
+  function saveScrollPosition() {
+    try {
+      if (typeof window.sessionStorage !== 'undefined') {
+        window.sessionStorage.setItem('__ws_dev_scroll', JSON.stringify({
+          url: window.location.pathname + window.location.search,
+          x: window.scrollX || 0,
+          y: window.scrollY || 0,
+        }));
+      }
+    } catch (_) {}
+  }
+
+  function restoreScrollPosition() {
+    try {
+      if (typeof window.sessionStorage === 'undefined') return;
+      var raw = window.sessionStorage.getItem('__ws_dev_scroll');
+      if (!raw) return;
+      window.sessionStorage.removeItem('__ws_dev_scroll');
+      var pos = JSON.parse(raw);
+      if (pos && pos.url === (window.location.pathname + window.location.search)) {
+        var apply = function() { window.scrollTo(pos.x || 0, pos.y || 0); };
+        if (typeof window.requestAnimationFrame === 'function') {
+          window.requestAnimationFrame(apply);
+        } else {
+          apply();
+        }
+      }
+    } catch (_) {}
+  }
+
   function safeReload(reason) {
     clearOverlay();
+    saveScrollPosition();
     var reasonMsg = reason ? ' (' + reason + ')' : '';
     console.log('[Webspresso] 🔄 Reloading page' + reasonMsg + '...');
 
@@ -246,10 +277,15 @@ const CLIENT_RUNTIME_SCRIPT = `(function() {
     };
   }
 
+  function init() {
+    restoreScrollPosition();
+    connect();
+  }
+
   if (document.readyState === 'loading') {
-    document.addEventListener('DOMContentLoaded', connect);
+    document.addEventListener('DOMContentLoaded', init);
   } else {
-    connect();
+    init();
   }
 })();
 `;
@@ -290,6 +326,7 @@ function createDevReloadHub(config = {}) {
   const autoInject = options.autoInject !== false;
   const watchPublicAll = options.watchPublicAll === true;
   const extraWatch = Array.isArray(options.watch) ? options.watch : [];
+  let ignoreClientFiles = Boolean(options.ignoreClientFiles);
 
   const templateExtensions = new Set(
     (Array.isArray(options.templateExtensions)
@@ -393,6 +430,9 @@ function createDevReloadHub(config = {}) {
     setDevMetaProvider: (fn) => {
       getDevMetaCallback = fn;
     },
+    setIgnoreClientFiles: (flag) => {
+      ignoreClientFiles = Boolean(flag);
+    },
     invalidateTemplateCache,
     triggerTemplateReload: (filename, reason = 'template') => {
       onTemplateFileChanged(filename, reason);
@@ -594,6 +634,7 @@ function createDevReloadHub(config = {}) {
     if (watchTemplates && viewsDir && fs.existsSync(viewsDir)) {
       watchDirectory(viewsDir, (eventType, filename) => {
         if (!filename || shouldIgnore(filename)) return;
+        if (ignoreClientFiles && filename.includes('.client.')) return;
         const ext = path.extname(filename).toLowerCase();
         if (ext === '.css') {
           onCssFileChanged(filename);
@@ -607,6 +648,7 @@ function createDevReloadHub(config = {}) {
     if (watchTemplates && pagesDir && fs.existsSync(pagesDir)) {
       watchDirectory(pagesDir, (eventType, filename) => {
         if (!filename || shouldIgnore(filename)) return;
+        if (ignoreClientFiles && filename.includes('.client.')) return;
         const ext = path.extname(filename).toLowerCase();
         if (ext === '.css') {
           onCssFileChanged(filename);

package/src/server.js

@@ -24,7 +24,7 @@ const { resolveClientRuntime } = require('./client-runtime/resolve');
 const { mountPages, detectLocale, loadI18n, createTranslator } = require('./file-router');
 const { configureAssets, createHelpers, getScriptInjector, AssetManager } = require('./helpers');
 const { createDevReloadHub } = require('./dev-reload');
-const { createDevBundler } = require('./bundle');
+const { createDevBundler, findDefaultEntryPoints } = require('./bundle');
 const { registerClearHook } = require('./njk-frontmatter');
 const { createPluginManager } = require('./plugin-manager');
 const { createServiceRegistry } = require('./services');
@@ -1558,15 +1558,19 @@ function createApp(options = {}) {
   // Client-side JS incremental bundler (esbuild context() API)
   const bundleOption = options.bundle;
   const isBundleExplicit = bundleOption === true || (typeof bundleOption === 'object' && bundleOption.enabled !== false);
-  const isBundleDisabled = bundleOption === false;
+  const isBundleDisabled = bundleOption === false || (typeof bundleOption === 'object' && bundleOption.enabled === false);
+  const shouldAutoBundle = bundleOption === undefined && isDev && !isTest && findDefaultEntryPoints(rootDir).length > 0;
 
-  if (isBundleExplicit && !isBundleDisabled) {
+  if ((isBundleExplicit || shouldAutoBundle) && !isBundleDisabled) {
     const bundlerOpts = typeof bundleOption === 'object' ? { ...bundleOption } : {};
     if (!bundlerOpts.cwd) bundlerOpts.cwd = rootDir;
     const devBundler = createDevBundler(bundlerOpts, devReloadHub);
     app.devBundler = devBundler;
 
     if (devBundler.isAvailable() && bundlerOpts.watch !== false && isDev && !isTest) {
+      if (devReloadHub && typeof devReloadHub.setIgnoreClientFiles === 'function') {
+        devReloadHub.setIgnoreClientFiles(true);
+      }
       devBundler.startWatch().catch((err) => {
         if (logging) console.error('[Webspresso Bundler] Watch error:', err.message);
       });
@@ -1577,6 +1581,58 @@ function createApp(options = {}) {
     }
   }
 
+  // Auto-refresh generated TypeScript types & typed API client in dev mode when models/services/api routes change
+  if (isDev && !isTest && options.typegen !== false) {
+    const typegenWatchDirs = [
+      path.join(rootDir, 'models'),
+      path.join(rootDir, 'services'),
+      path.join(rootDir, 'pages', 'api'),
+    ].filter((d) => fs.existsSync(d));
+
+    if (typegenWatchDirs.length > 0) {
+      const typegenWatchers = [];
+      let typegenTimer = null;
+      const scheduleTypegenRefresh = () => {
+        if (typegenTimer) clearTimeout(typegenTimer);
+        typegenTimer = setTimeout(() => {
+          typegenTimer = null;
+          try {
+            const { generateTypes } = require('./dev/typegen');
+            generateTypes({ rootDir, silent: true });
+            const hasGeneratedClient =
+              fs.existsSync(path.join(rootDir, '.webspresso', 'client.ts')) ||
+              fs.existsSync(path.join(rootDir, 'src', 'client.ts'));
+            if (hasGeneratedClient) {
+              const { generateClient } = require('./dev/client-gen');
+              generateClient({ rootDir, silent: true });
+            }
+          } catch (_) {}
+        }, 250);
+        if (typeof typegenTimer.unref === 'function') typegenTimer.unref();
+      };
+
+      for (const watchDir of typegenWatchDirs) {
+        try {
+          const w = fs.watch(watchDir, { recursive: true }, (_evt, filename) => {
+            if (!filename || filename.includes('node_modules') || filename.includes('.webspresso')) return;
+            scheduleTypegenRefresh();
+          });
+          w.on('error', () => {});
+          typegenWatchers.push(w);
+        } catch (_) {}
+      }
+
+      if (shutdownManager) {
+        shutdownManager.registerDisposer('devTypegen', () => {
+          if (typegenTimer) clearTimeout(typegenTimer);
+          for (const w of typegenWatchers) {
+            try { w.close(); } catch (_) {}
+          }
+        });
+      }
+    }
+  }
+
   // Configure Nunjucks with viewsDir priority and circular extension guard
   const templateDirs = [viewsDir, pagesDir].filter(Boolean);
   if (templateDirs.length === 0) {