mnfst 0.5.198-next.3 → 0.5.198

package/lib/manifest.bindings.js

@@ -0,0 +1,31 @@
+/* Manifest Bindings */
+
+(function () {
+
+// x-text: same as Alpine's, but never rewrites an unchanged string (each write is a DOM mutation)
+function initializeBindingsPlugin() {
+    Alpine.directive('text', (el, { expression }, { effect, evaluateLater }) => {
+        const evaluate = evaluateLater(expression);
+        effect(() => {
+            evaluate((value) => {
+                const next = value == null ? '' : String(value);
+                if (el.textContent === next) return;
+                Alpine.mutateDom(() => { el.textContent = next; });
+            });
+        });
+    });
+}
+
+let bindingsPluginInitialized = false;
+
+function ensureBindingsPluginInitialized() {
+    if (bindingsPluginInitialized) return;
+    if (!window.Alpine || typeof window.Alpine.directive !== 'function') return;
+    bindingsPluginInitialized = true;
+    initializeBindingsPlugin();
+}
+
+document.addEventListener('alpine:init', ensureBindingsPluginInitialized);
+if (window.Alpine && typeof window.Alpine.directive === 'function') ensureBindingsPluginInitialized();
+
+})();

package/lib/manifest.data.js

@@ -279,6 +279,9 @@ const pendingLocal = new Map(); // source -> Map<$id, { patch, removed }>
 let allCache = null;
 let allDirty = true;
 
+// Per-source freshness: `$fresh` resolves on the first network-fresh landing of this page-load
+const freshness = new Map(); // source -> { promise, resolve, done }
+
 // Deep seal so Alpine won't proxy (double-proxying causes recursion)
 function deepSeal(obj) {
     if (obj === null || typeof obj !== 'object') {
@@ -372,10 +375,48 @@ function mergeRowFields(target, fields, dataSourceName) {
 }
 
 function attachMethods(array, dataSourceName) {
-    const loadDataSource = window.ManifestDataMain?.loadDataSource;
-    if (Array.isArray(array) && loadDataSource && window.ManifestDataProxies?.attachArrayMethods) {
-        window.ManifestDataProxies.attachArrayMethods(array, dataSourceName, loadDataSource);
+    const main = window.ManifestDataMain;
+    const reload = main?.reloadDataSource || main?.loadDataSource;
+    if (Array.isArray(array) && reload && window.ManifestDataProxies?.attachArrayMethods) {
+        window.ManifestDataProxies.attachArrayMethods(array, dataSourceName, reload);
+    }
+}
+
+function sourceFreshness(dataSourceName) {
+    let f = freshness.get(dataSourceName);
+    if (!f) {
+        f = { done: false, resolve: null, promise: null };
+        f.promise = new Promise(resolve => { f.resolve = resolve; });
+        freshness.set(dataSourceName, f);
     }
+    return f;
+}
+
+function markFresh(dataSourceName) {
+    const f = sourceFreshness(dataSourceName);
+    if (!f.done) { f.done = true; f.resolve(); }
+}
+
+// State-only write (loading/error) — rows stay live, no version bump
+function setSourceState(dataSourceName, patch) {
+    const store = typeof Alpine !== 'undefined' ? Alpine.store('data') : null;
+    if (!store) return null;
+    const key = `_${dataSourceName}_state`;
+    const current = store[key] || { loading: false, error: null, ready: false, stale: true };
+    const next = { ...current, ...patch };
+    if (patch.error !== undefined) next.errorTime = patch.error ? (patch.errorTime || Date.now()) : null;
+    store[key] = next;
+    return next;
+}
+
+// Authoritative in-flight map: one promise per key, cleared on settle
+function runDeduped(key, factory) {
+    if (loadingPromises.has(key)) return loadingPromises.get(key);
+    const promise = Promise.resolve().then(factory).finally(() => {
+        if (loadingPromises.get(key) === promise) loadingPromises.delete(key);
+    });
+    loadingPromises.set(key, promise);
+    return promise;
 }
 
 // Reactive source array, created on demand; raw map tracks the same identity
@@ -466,14 +507,18 @@ function writeSource(dataSourceName, data, options = {}) {
         rawDataStore.set(dataSourceName, data);
     }
 
-    const currentState = store[`_${dataSourceName}_state`] || { loading: false, error: null, ready: false };
+    const currentState = store[`_${dataSourceName}_state`] || { loading: false, error: null, ready: false, stale: true };
+    // `fresh`: network-origin rows → clears `stale` for the rest of the page-load
+    const fresh = options.fresh === true && data !== null && data !== undefined;
     const newState = {
         loading: options.loading !== undefined ? options.loading : currentState.loading,
         error: options.error !== undefined ? options.error : currentState.error,
         ready: options.ready !== undefined ? options.ready : (data !== null && data !== undefined),
-        errorTime: options.error !== undefined && options.error !== null ? Date.now() : (currentState.errorTime || null)
+        errorTime: options.error !== undefined && options.error !== null ? Date.now() : (currentState.errorTime || null),
+        stale: fresh ? false : currentState.stale !== false
     };
     store[`_${dataSourceName}_state`] = newState;
+    if (fresh) markFresh(dataSourceName);
     store._initialized = true;
     store._ready = true;
 
@@ -1386,6 +1431,10 @@ window.ManifestDataStore = {
     landRemove,
     flushLandings,
     noteLocalWrite,
+    // Stale-first + dedupe (§11.1)
+    setSourceState,
+    runDeduped,
+    sourceFreshness,
     touchSource,
     bumpAllVersions,
     mergeRowFields,
@@ -3231,6 +3280,25 @@ function attachArrayMethods(array, dataSourceName, reloadDataSource) {
         }
     });
 
+    // $stale / $fresh: semantics in manifest.data.proxies.magic.state.js
+    Object.defineProperty(array, '$stale', {
+        enumerable: false,
+        configurable: true,
+        get: function () {
+            const store = Alpine.store('data');
+            const state = store?.[`_${dataSourceName}_state`];
+            return !state || state.stale !== false;
+        }
+    });
+
+    Object.defineProperty(array, '$fresh', {
+        enumerable: false,
+        configurable: true,
+        get: function () {
+            return window.ManifestDataStore?.sourceFreshness?.(dataSourceName)?.promise || Promise.resolve();
+        }
+    });
+
     // Attach $search method for client-side text filtering
     Object.defineProperty(array, '$search', {
         enumerable: false,
@@ -3902,7 +3970,10 @@ function createArrayProxyWithRoute(arrayTarget, dataSourceName = null, reloadDat
                     return undefined;
                 }
 
-                // Handle state properties ($loading, $error, $ready)
+                // Handle state properties ($loading, $error, $ready, $stale, $fresh)
+                if (key === '$stale' || key === '$fresh') {
+                    return window.ManifestDataProxiesMagic?.getStateProperty?.(key, dataSourceName);
+                }
                 if (key === '$loading' || key === '$error' || key === '$ready') {
                     const store = Alpine.store('data');
                     // Safely access dataSourceName - if it's not defined, use null
@@ -4089,7 +4160,7 @@ function createArrayProxyWithRoute(arrayTarget, dataSourceName = null, reloadDat
                         return true;
                     }
                     // Check custom methods we've added
-                    if (key === '$route' || key === '$loading' || key === '$error' || key === '$ready') {
+                    if (key === '$route' || key === '$loading' || key === '$error' || key === '$ready' || key === '$stale' || key === '$fresh') {
                         return true;
                     }
                     // For other string keys, check if they exist on the array
@@ -6947,16 +7018,22 @@ function createAppwriteMethodsHandler(dataSourceName, reloadDataSource) {
                         queries || [],
                         scope
                     );
-                    const result = await window.ManifestDataAppwrite.loadTableRows(
-                        appwriteConfig.databaseId,
-                        tableId,
-                        appwriteQueries
-                    );
-                    // Network landing: query result replaces the source (coalesced, identity-preserving)
-                    if (result !== undefined && window.ManifestDataStore?.landRows) {
-                        await window.ManifestDataStore.landRows(dataSourceName, result, { mode: 'replace' });
-                    }
-                    return result;
+                    // Dedupe key: source + serialized queries (never across different queries)
+                    const key = `${dataSourceName}:$query:${JSON.stringify(appwriteQueries.map(q => String(q)))}`;
+                    const { runDeduped, landRows } = window.ManifestDataStore || {};
+                    const run = async () => {
+                        const result = await window.ManifestDataAppwrite.loadTableRows(
+                            appwriteConfig.databaseId,
+                            tableId,
+                            appwriteQueries
+                        );
+                        // Network landing: query result replaces the source (coalesced, identity-preserving)
+                        if (result !== undefined && landRows) {
+                            await landRows(dataSourceName, result, { mode: 'replace', fresh: true });
+                        }
+                        return result;
+                    };
+                    return runDeduped ? await runDeduped(key, run) : await run();
                 }
             }
 
@@ -7737,20 +7814,39 @@ window.ManifestDataProxiesAppwrite.createAppwriteMethodsHandler = createAppwrite
 
 
 /* Manifest Data Sources - Magic Method State Properties */
-// $loading, $error, $ready state properties
+// $loading, $error, $ready, $stale, $fresh state properties
+//
+// $stale: true until the first network-fresh landing of this page-load is
+//   applied (rows from a fetch, `$query`, or the memory cache of a fetch made
+//   this page-load); false from then on — a later reload keeps it false and
+//   reports through $loading. Single-reveal UIs gate on `!$stale`.
+// $fresh: promise resolving at that same first fresh landing; never rejects
+//   (a failed reload keeps old rows and sets $error). Per page-load.
+
+const STATE_PROPS = ['$loading', '$error', '$ready', '$stale', '$fresh'];
+
+function defaultStateValue(prop) {
+    if (prop === '$error') return null;
+    if (prop === '$stale') return true;
+    return false;
+}
 
 function getStateProperty(prop, dataSourceName) {
+    if (prop === '$fresh') {
+        return window.ManifestDataStore?.sourceFreshness?.(dataSourceName)?.promise || Promise.resolve();
+    }
+
     if (typeof Alpine === 'undefined' || !Alpine.store) {
-        return prop === '$loading' ? false : (prop === '$error' ? null : false);
+        return defaultStateValue(prop);
     }
 
     const store = Alpine.store('data');
     if (!store) {
-        return prop === '$loading' ? false : (prop === '$error' ? null : false);
+        return defaultStateValue(prop);
     }
 
     const stateKey = `_${dataSourceName}_state`;
-    const state = store[stateKey] || { loading: false, error: null, ready: false };
+    const state = store[stateKey] || { loading: false, error: null, ready: false, stale: true };
 
     if (prop === '$loading') {
         return state.loading !== false; // Default to true if loading
@@ -7758,6 +7854,8 @@ function getStateProperty(prop, dataSourceName) {
         return state.error || null;
     } else if (prop === '$ready') {
         return state.ready || false;
+    } else if (prop === '$stale') {
+        return state.stale !== false;
     }
 
     return undefined;
@@ -7766,7 +7864,7 @@ function getStateProperty(prop, dataSourceName) {
 // State property handler for use in proxy get() traps
 function createStatePropertyHandler(dataSourceName) {
     return function (key) {
-        if (key === '$loading' || key === '$error' || key === '$ready') {
+        if (STATE_PROPS.includes(key)) {
             return getStateProperty(key, dataSourceName);
         }
         return undefined;
@@ -7777,11 +7875,11 @@ function createStatePropertyHandler(dataSourceName) {
 if (!window.ManifestDataProxiesMagic) {
     window.ManifestDataProxiesMagic = {};
 }
+window.ManifestDataProxiesMagic.STATE_PROPS = STATE_PROPS;
 window.ManifestDataProxiesMagic.getStateProperty = getStateProperty;
 window.ManifestDataProxiesMagic.createStatePropertyHandler = createStatePropertyHandler;
 
 
-
 /* Manifest Data Sources - Magic Method $files Handler */
 // Handles $files method for reactive file arrays
 
@@ -8250,10 +8348,14 @@ function registerXMagicMethod(loadDataSource) {
             window._manifestXAccessed = true;
         }
         const pendingLoads = new Map();
+        const preDataProxies = new Map();
         const store = Alpine.store('data');
 
-        // Store loadDataSource in closure for Appwrite methods
-        const reloadDataSource = loadDataSource;
+        // Reload variant for Appwrite methods: bypasses the memory cache, keeps rows live
+        const reloadDataSource = (name, locale) => {
+            const reload = window.ManifestDataMain?.reloadDataSource;
+            return reload ? reload(name, locale) : loadDataSource(name, locale, { reload: true });
+        };
 
         const ACTIVE_PROPS = Symbol('activeProps');
 
@@ -8285,7 +8387,8 @@ function registerXMagicMethod(loadDataSource) {
                             const stamped = Array.isArray(data)
                                 ? data.map(d => (d && typeof d === 'object' && !('contentType' in d)) ? { contentType: name, ...d } : d)
                                 : data;
-                            window.ManifestDataStore?.updateStore?.(name, stamped, { loading: false, error: null, ready: true, allowDuringInit: true });
+                            // App-supplied rows are authoritative → fresh
+                            window.ManifestDataStore?.updateStore?.(name, stamped, { loading: false, error: null, ready: true, fresh: true, allowDuringInit: true });
                             return true;
                         };
                     }
@@ -8353,7 +8456,21 @@ function registerXMagicMethod(loadDataSource) {
                         track();
                         const createLoadingProxy = window.ManifestDataProxiesCore?.createLoadingProxy;
                         if (createLoadingProxy) {
-                            return createLoadingProxy(prop);
+                            // Cached per source so re-evaluations see one identity; state props
+                            // ($loading/$error/$ready/$stale/$fresh) answer before any rows exist
+                            if (!preDataProxies.has(prop)) {
+                                const loading = createLoadingProxy(prop);
+                                const stateProps = window.ManifestDataProxiesMagic?.STATE_PROPS || [];
+                                preDataProxies.set(prop, new Proxy(loading, {
+                                    get(target, key) {
+                                        if (stateProps.includes(key)) {
+                                            return window.ManifestDataProxiesMagic.getStateProperty(key, prop);
+                                        }
+                                        return target[key];
+                                    }
+                                }));
+                            }
+                            return preDataProxies.get(prop);
                         }
                         return window.ManifestDataProxiesCore?.getChainingFallback?.() ?? '';
                     }
@@ -8461,7 +8578,7 @@ function registerXMagicMethod(loadDataSource) {
                                         const arrayForMethods = valueIsArray ? value : (rawIsArray ? rawValue : arrayToProxy);
 
                                         if (attachArrayMethods) {
-                                            const arrayWithMethods = attachArrayMethods(arrayForMethods, prop, loadDataSource);
+                                            const arrayWithMethods = attachArrayMethods(arrayForMethods, prop, reloadDataSource);
                                             // has() trap so Alpine sees $search/$query/etc. before accessing
                                             return new Proxy(arrayWithMethods, {
                                                 get(target, key) {
@@ -8479,7 +8596,7 @@ function registerXMagicMethod(loadDataSource) {
                                                                     const manifest = window.ManifestComponentsRegistry?.manifest || null;
                                                                     const dataSource = manifest?.data?.[prop] || manifest?.appwrite?.[prop];
                                                                     if (dataSource && window.ManifestDataConfig?.isAppwriteCollection?.(dataSource)) {
-                                                                        const methodsHandler = createAppwriteMethodsHandler(prop, loadDataSource);
+                                                                        const methodsHandler = createAppwriteMethodsHandler(prop, reloadDataSource);
                                                                         return methodsHandler.bind(null, key);
                                                                     }
                                                                 } catch { /* fall through */ }
@@ -8497,7 +8614,8 @@ function registerXMagicMethod(loadDataSource) {
                                                 has(target, key) {
                                                     // Report that base plugin methods exist
                                                     if (key === '$search' || key === '$query' || key === '$route' ||
-                                                        key === '$loading' || key === '$error' || key === '$ready') {
+                                                        key === '$loading' || key === '$error' || key === '$ready' ||
+                                                        key === '$stale' || key === '$fresh') {
                                                         return key in target;
                                                     }
                                                     // Report that array methods exist
@@ -10751,37 +10869,56 @@ async function checkFileMatchesScope(file, scope) {
     });
 }
 
-// Load dataSource data
-async function loadDataSource(dataSourceName, locale = 'en') {
+// Rows already in the store (array or object) — a reload keeps them live
+function hasLiveRows(dataSourceName) {
+    const store = typeof Alpine !== 'undefined' ? Alpine.store('data') : null;
+    const raw = store ? (window.ManifestDataStore?.rawOf?.(store) || store) : null;
+    const current = raw ? raw[dataSourceName] : undefined;
+    return current !== null && current !== undefined;
+}
+
+function liveLocale() {
+    return (typeof document !== 'undefined' && document.documentElement?.lang)
+        || (typeof Alpine !== 'undefined' && Alpine.store('locale')?.current)
+        || 'en';
+}
+
+// Load dataSource data. options.reload: bypass the memory cache and refetch;
+// existing rows stay live ($loading only), fresh rows merge by $id.
+async function loadDataSource(dataSourceName, locale = 'en', options = {}) {
+    locale = locale || 'en';
     const cacheKey = `${dataSourceName}:${locale}`;
-    const { dataSourceCache, loadingPromises, isInitializing, updateStore, landRows } = window.ManifestDataStore;
+    const { dataSourceCache, loadingPromises, isInitializing, updateStore, landRows, setSourceState, runDeduped } = window.ManifestDataStore;
 
-    // Memory cache. Serving cached data is fine, but writing an old locale to the
-    // live store would clobber a concurrent locale switch — so guard the store
-    // write via the `_locale` stamp (unstamped/non-localized data writes freely).
-    if (dataSourceCache.has(cacheKey)) {
+    // Memory cache (this page-load's fetches). Serving cached data is fine, but
+    // writing an old locale to the live store would clobber a concurrent locale
+    // switch — so guard the store write via the `_locale` stamp.
+    if (!options.reload && dataSourceCache.has(cacheKey)) {
         const cachedData = dataSourceCache.get(cacheKey);
-        const liveLocale = (window.Alpine && Alpine.store('locale')?.current)
+        const live = (window.Alpine && Alpine.store('locale')?.current)
             || document.documentElement.lang || locale;
-        const staleLocaleHit = locale !== liveLocale && !!(cachedData && cachedData._locale);
+        const staleLocaleHit = locale !== live && !!(cachedData && cachedData._locale);
         if (!isInitializing && !staleLocaleHit) {
             // Landing (coalesced): resolves once the cached rows are visible
-            await landRows(dataSourceName, cachedData, { mode: 'replace', loading: false, error: null, ready: true });
+            await landRows(dataSourceName, cachedData, { mode: 'replace', loading: false, error: null, ready: true, fresh: true });
         }
         return cachedData;
     }
 
-    // If already loading, return existing promise
+    // In flight for this source+locale: share it (every entry path lands here)
     if (loadingPromises.has(cacheKey)) {
         return loadingPromises.get(cacheKey);
     }
 
-    // Set loading state
+    // Loading state: rows already landed stay live; first-ever load clears
+    const keepRows = hasLiveRows(dataSourceName);
     if (!isInitializing) {
-        updateStore(dataSourceName, null, { loading: true, error: null, ready: false });
+        if (keepRows) setSourceState(dataSourceName, { loading: true, error: null });
+        else updateStore(dataSourceName, null, { loading: true, error: null, ready: false });
     }
 
-    const loadPromise = (async () => {
+    return runDeduped(cacheKey, async () => {
+        let landed = false;
         try {
             const manifest = await window.ManifestDataConfig.ensureManifest();
             if (!manifest) {
@@ -11043,23 +11180,29 @@ async function loadDataSource(dataSourceName, locale = 'en') {
                 || document.documentElement.lang || locale;
             const staleLocale = localeSensitive && liveLocale !== locale;
 
-            // Network landing (coalesced per frame); resolves once visible
+            // Network landing (coalesced per frame, merges by $id); resolves once visible
             if (!isInitializing && !staleLocale) {
-                await landRows(dataSourceName, enhancedData, { mode: 'replace', loading: false, error: null, ready: true });
+                landed = true;
+                await landRows(dataSourceName, enhancedData, { mode: 'replace', loading: false, error: null, ready: true, fresh: true });
             }
 
             // Return unsealed version for our proxy system
             return enhancedData;
         } catch (error) {
-            // Set error state with timestamp to prevent rapid retries
+            // Error state (timestamped to prevent rapid retries); live rows stay
             if (!isInitializing) {
+                landed = true;
                 const errorMessage = error?.message || error?.toString() || `Failed to load dataSource "${dataSourceName}"`;
-                updateStore(dataSourceName, null, {
-                    loading: false,
-                    error: errorMessage,
-                    ready: false,
-                    errorTime: Date.now() // Track when error occurred
-                });
+                if (hasLiveRows(dataSourceName)) {
+                    setSourceState(dataSourceName, { loading: false, error: errorMessage, errorTime: Date.now() });
+                } else {
+                    updateStore(dataSourceName, null, {
+                        loading: false,
+                        error: errorMessage,
+                        ready: false,
+                        errorTime: Date.now() // Track when error occurred
+                    });
+                }
             }
 
             // Only log non-auth errors to reduce noise (401 is expected until user authenticates)
@@ -11073,12 +11216,15 @@ async function loadDataSource(dataSourceName, locale = 'en') {
             }
             return null;
         } finally {
-            loadingPromises.delete(cacheKey);
+            // Early exits (no source, stale locale) must not strand a live source in $loading
+            if (!landed && keepRows && !isInitializing) setSourceState(dataSourceName, { loading: false });
         }
-    })();
+    });
+}
 
-    loadingPromises.set(cacheKey, loadPromise);
-    return loadPromise;
+// Reload: refetch past the memory cache; rows stay live and merge by $id
+function reloadDataSource(dataSourceName, locale) {
+    return loadDataSource(dataSourceName, locale || liveLocale(), { reload: true });
 }
 
 // Listen for URL changes to trigger reactivity
@@ -11203,7 +11349,8 @@ async function initializeDataSourcesPlugin() {
     // Export loadDataSource for use by team change listener
     window.ManifestDataMain = {
         loadDataSource,
-        _loadDataSource: loadDataSource, // Export for internal use
+        reloadDataSource,
+        _loadDataSource: reloadDataSource, // Internal: every user is a reload-after-mutation
         filterFilesByScope // Export for use by getFilesForEntry
     };
 
@@ -11216,18 +11363,16 @@ async function initializeDataSourcesPlugin() {
         const locale = document.documentElement.lang ||
             (typeof Alpine !== 'undefined' && Alpine.store('locale')?.current) || 'en';
 
-        const { dataSourceCache, loadingPromises } = window.ManifestDataStore;
+        const { dataSourceCache } = window.ManifestDataStore;
         const isAppwriteCollection = window.ManifestDataConfig.isAppwriteCollection;
 
         for (const [name, source] of Object.entries(manifest.data)) {
             if (isAppwriteCollection(source)) continue;
             if (source && typeof source === 'object' && source.url) continue;
 
-            const cacheKey = `${name}:${locale}`;
-            dataSourceCache.delete(cacheKey);
-            loadingPromises.delete(cacheKey);
-
-            try { await loadDataSource(name, locale); } catch { /* skip failed sources */ }
+            dataSourceCache.delete(`${name}:${locale}`);
+            // Reload keeps rows live and merges (identity survives an edit-save)
+            try { await loadDataSource(name, locale, { reload: true }); } catch { /* skip failed sources */ }
         }
     });
 
@@ -11265,7 +11410,7 @@ async function initializeDataSourcesPlugin() {
                                 const data = await loadDataSource(name, locale);
                                 if (data != null) {
                                     // Boot landing: every pre-loaded source lands in ONE flush
-                                    await landRows(name, data, { mode: 'replace', loading: false, error: null, ready: true, allowDuringInit: true });
+                                    await landRows(name, data, { mode: 'replace', loading: false, error: null, ready: true, fresh: true, allowDuringInit: true });
                                 }
                             } catch (err) {
                                 console.warn(`[Manifest Data] Failed to pre-load ${name}:`, err);
@@ -11283,7 +11428,7 @@ async function initializeDataSourcesPlugin() {
                 // allowDuringInit: setIsInitializing(true) is active, so without this
                 // flag updateStore short-circuits and $x.manifest stays unpopulated.
                 window.ManifestDataStore.dataSourceCache.set(`manifest:${locale}`, publicManifest);
-                updateStore('manifest', publicManifest, { loading: false, error: null, ready: true, allowDuringInit: true });
+                updateStore('manifest', publicManifest, { loading: false, error: null, ready: true, fresh: true, allowDuringInit: true });
             }
             Alpine.store('data')._ready = true;
         } catch (error) {

package/lib/manifest.defer.js

@@ -12,7 +12,17 @@ const OWNS_CHILDREN = new Set([
 // Kill switch: data-defer="off" on the loader script; prerender snapshots keep eager markup
 const killed = !!document.querySelector('script[data-defer="off"]') || window.__manifestRender === true;
 
+// Route deferral (spike, opt-in): data-defer-routes on the loader script or ManifestDeferConfig.routes
+let routesScriptFlag = null;
+function routesOn() {
+    const cfg = window.ManifestDeferConfig;
+    if (cfg && cfg.routes !== undefined) return cfg.routes === true;
+    if (routesScriptFlag === null) routesScriptFlag = !!document.querySelector('script[data-defer-routes]');
+    return routesScriptFlag;
+}
+
 const pending = new Set();
+const routes = new Set();        // deferred route panes: render on activation only, never prewarmed
 let ready = false;
 let bootDrained = false;
 let idleHandle = null;
@@ -73,12 +83,21 @@ function firstPanel(el) {
     return scope.querySelector(`[x-tabpanel="${set}"]`);
 }
 
+// A route pane is closed when the router says it does not match the URL (or it is already hidden)
+function routeInactive(el) {
+    if (el.hasAttribute('hidden')) return true;
+    const vis = window.ManifestRoutingVisibility;
+    return !!(vis && typeof vis.isRouteActive === 'function' && !vis.isRouteActive(el));
+}
+
 // Closed-container rule, or the visibility rule for explicit x-defer
 function ruleFor(el, explicit) {
+    const isRoute = el.hasAttribute('x-route');
+    if (isRoute && routesOn() && routeInactive(el)) return 'route';
     if (el.hasAttribute('popover')) return isPopoverOpen(el) ? null : 'popover';
     const tag = el.tagName;
     if (tag === 'DIALOG' || tag === 'DETAILS') return el.hasAttribute('open') ? null : 'toggle';
-    if (el.hasAttribute('hidden') && !el.hasAttribute('x-route')) return 'hidden';
+    if (el.hasAttribute('hidden') && !isRoute) return 'hidden';
     if (el.hasAttribute('x-tabpanel') && window.ensureTabsPluginInitialized) return firstPanel(el) === el ? null : 'panel';
     return explicit ? 'visible' : null;
 }
@@ -115,7 +134,8 @@ function register(el, rule, opts) {
         cleanup: []
     };
     wire(rec);
-    if (!rec.lazy) { pending.add(rec); schedule(); }
+    if (rule === 'route') routes.add(rec);
+    else if (!rec.lazy) { pending.add(rec); schedule(); }
     return rec;
 }
 
@@ -208,6 +228,15 @@ function wire(rec) {
         });
         arm();
         if (rec.discard) observe(['hidden'], () => { if (el.hasAttribute('hidden')) teardown(rec); });
+    } else if (rule === 'route') {
+        // Router fires manifest:route-activate before it unhides the pane; hidden removal is the fallback
+        listen('manifest:route-activate', () => render(rec));
+        const arm = () => Alpine.onAttributeRemoved(el, 'hidden', () => {
+            if (!el.hasAttribute('hidden')) render(rec);
+            if (!rec.rendered || rec.discard) arm();
+        });
+        arm();
+        if (rec.discard) observe(['hidden'], () => { if (el.hasAttribute('hidden')) teardown(rec); });
     } else if (rule === 'panel') {
         observe(['style', 'x-show', 'x-tabpanel'], () => onState(shown(el, false)));
     } else if (rule === 'visible') {
@@ -218,11 +247,12 @@ function wire(rec) {
 
 // ---- Idle prewarm (after manifest:ready; urgent first, then priority asc, then document order) ----
 
-const idle = (fn, timeout) => {
+// Genuine idle only: no timeout, so a never-idle page never prewarms (its stashed containers cost nothing)
+const idle = (fn) => {
     idleIsTimer = !window.requestIdleCallback;
     return idleIsTimer
-        ? setTimeout(() => fn({ didTimeout: true, timeRemaining: () => 0 }), 50)
-        : window.requestIdleCallback(fn, { timeout });
+        ? setTimeout(() => fn({ didTimeout: false, timeRemaining: () => IDLE_BUDGET_MS + 1 }), 200)
+        : window.requestIdleCallback(fn);
 };
 function cancelIdle() {
     if (idleHandle === null) return;
@@ -232,7 +262,6 @@ function cancelIdle() {
 
 // A gesture that revealed a pane (tab switch, panel open) makes its containers urgent
 function promoteNearViewport() {
-    promoteTimer = null;
     if (!ready || !bootDrained) return;
     // The on-screen containers nearest the gesture point (a revealed pane sits under the click)
     const candidates = [];
@@ -255,9 +284,11 @@ function promoteNearViewport() {
 function onGesture(e) {
     lastGestureAt = now();
     if (e && typeof e.clientX === 'number' && (e.clientX || e.clientY)) { gestureX = e.clientX; gestureY = e.clientY; }
-    if (promoteTimer !== null || now() - lastPromoteAt < 500) return;
+    if (now() - lastPromoteAt < 300) return;
+    clearTimeout(promoteTimer);
     lastPromoteAt = now();
-    promoteTimer = setTimeout(promoteNearViewport, 150);
+    // Three passes: a revealed pane lays out and mounts its menus over the next few hundred ms
+    promoteTimer = setTimeout(() => { promoteNearViewport(); promoteTimer = setTimeout(() => { promoteNearViewport(); promoteTimer = setTimeout(promoteNearViewport, 400); }, 150); }, 50);
 }
 
 // Only containers the user can reach: not under a hidden route; visible parents first
@@ -309,19 +340,20 @@ function schedule() {
     if (!head.urgent && warm.size >= PREWARM_CAP) return;       // paused at the cap; resumes when a warm one opens or evicts
     idleHandle = idle((deadline) => {
         idleHandle = null;
-        // Forced fire (never-idle page): one container. Genuine idle: batch within the budget.
+        // Render while the browser reports idle time; the first container of a slice always gets its turn
         let n = 0;
-        do {
+        while (n < SLICE_MAX && (n === 0 || (deadline && deadline.timeRemaining() > IDLE_BUDGET_MS))) {
+            if (deadline && deadline.didTimeout) break;
             const rec = next();
             if (!rec) break;
             if (!rec.urgent && warm.size >= PREWARM_CAP) break;   // cap = max warm; only urgent renders may exceed it
             for (const other of pending) other.near = undefined;
             render(rec, true);
             n++;
-        } while (deadline && !deadline.didTimeout && deadline.timeRemaining() > IDLE_BUDGET_MS && n < SLICE_MAX);
+        }
         evict();
         schedule();
-    }, head.urgent ? 100 : 500);
+    });
 }
 
 function markReady() {
@@ -370,7 +402,11 @@ window.ManifestDefer = {
     defer,
     render: (el) => { if (el && el.__mnfstDefer) render(el.__mnfstDefer); },
     isPending: (el) => !!(el && el.__mnfstDefer && !el.__mnfstDefer.rendered),
-    stats: () => ({ pending: pending.size, warm: warm.size, cap: PREWARM_CAP, ready, bootDrained, armed: idleHandle !== null, head: (() => { const h = next(); return h ? (h.el.id || h.el.tagName) : null; })() })
+    stats: () => ({
+        pending: pending.size, warm: warm.size, cap: PREWARM_CAP, ready, bootDrained, armed: idleHandle !== null,
+        head: (() => { const h = next(); return h ? (h.el.id || h.el.tagName) : null; })(),
+        routes: { enabled: routesOn(), stashed: Array.from(routes).filter((r) => !r.rendered).length, rendered: Array.from(routes).filter((r) => r.rendered).length }
+    })
 };
 if (window.Manifest && typeof window.Manifest === 'object') window.Manifest.defer = defer;
 

package/lib/manifest.integrity.json

@@ -2,6 +2,7 @@
   "manifest.appwrite.auth.js": "sha384-lWvffK6C2Zs9dOiMh/0OQTnU2ycZq1USOeJDlPUgJsbtrdA9+3zq4VHcIdS40qR0",
   "manifest.appwrite.data.js": "sha384-FusD+MQKkRQexKYl7j6egjDzsPYMWgtNublkgOl595aNqbx4yh8/PfbhLEyI06T1",
   "manifest.appwrite.presences.js": "sha384-JyVDWFT69b7Svq8J8p9tNWe2v9PZNQBY5UyhtOl1vnuHFAX0CRQ3MA9SiKq5wzNh",
+  "manifest.bindings.js": "sha384-lPtMf8Ykaic9gNVZKq8Scia1881ZeMAyxer3WCIkUNwwrgzGBWto1OXADUwjvORF",
   "manifest.charts.js": "sha384-qQrjhWkIDi4oU5uQrpy8DdlMjY+gfiivBuX6mssNiFdkawgkVBvKneGgp+nd3PYJ",
   "manifest.chat.js": "sha384-UN5BmhqyafJ8OfLFaOLszrvUW5r001dRheQWqsEBCCLnfBcW1bjXaGOdZvURtrnL",
   "manifest.code.js": "sha384-aoQ4E26vrhNe/+tL7K0h90c8/0ies7e8oIR6Ay92he2X3dnWZ+OPcn2Dna8fmc+c",
@@ -10,9 +11,9 @@
   "manifest.combobox.js": "sha384-SN3XHumoebxcduFQqx5zt65/Cd10y8nuf9Gkco6UnsZ42sadRd+gvVLfWPdkkuPH",
   "manifest.components.js": "sha384-HEyeJtV20k7po8WH0LEj800MlsqgDH0vE5GTAl62SgdEhn1aJ7VfryQcA6yIi18U",
   "manifest.computed.js": "sha384-LDxER8pyYyYwUxIYIyiJA02s+49g8CzpSlOj28On0DFIUgetT3UmvE/9xOsTwT66",
-  "manifest.data.js": "sha384-urUiANuQfrc+AfwTB7+nMneF2C1+EfV+S5+eg4PQnZCJ0Aid50KwSARufiVrGAXd",
+  "manifest.data.js": "sha384-LhX1a36AITeixPrC4RHz0X+TNMEoDwxi6JVclaIhNAlTYCtkYOHE2KmxJZhfJheD",
   "manifest.datepicker.js": "sha384-8vTJYkLqqvgXgm1w1becuaRR/jUEpiLBjBJ6RsRbUr+ZkypvspD6EsssuDrX4SQq",
-  "manifest.defer.js": "sha384-szMa04R4gWsZl3nICHz3Mtku8vgROEHvrAIMap+wuqITKvMVQHJOa0kVzHHjMcwN",
+  "manifest.defer.js": "sha384-t/g++osVS3qDXeY8+gfxUtLF9o0SCQQJKNxHGpb8NkIciDvxOAvA6sFIVcM0AKeA",
   "manifest.dropdowns.js": "sha384-4HuHkBt4i8sTPUDLB9rNLli2/lWLY1tjtCLzey37gRwueG+FRLCnVH1q7ljiVvJR",
   "manifest.edit.js": "sha384-ZvgV3ax7yHtSC23zdvRYJPzBsBpGFBLuBJMgfQ1IDumv97Cn2bpHOePxyQikfl5L",
   "manifest.export.js": "sha384-HCy3n6ifrcAGIyzTRgZ5JIRvSX9q9/8ykMKRSbt1QTnhXz6PgYlV0AE2N2Yi2re+",
@@ -22,7 +23,7 @@
   "manifest.native.js": "sha384-nIngj4CM5hV4bvQvgs8C7JmSy1UUzobsbhvDE2NH5dXqQVNW/Hiat34wHUxMqSaO",
   "manifest.payments.js": "sha384-QGctMZtxF0Wb2JUJbb9sJ4bFbyQvUdr9HaKs4afyaTXb7zedAAIWeB27XINMe3VZ",
   "manifest.resize.js": "sha384-+0IsyrGP/4gZmNbD6oU8dCgEyhpBsXMm74NIenYeUGuGRWyJDurcG27xE/CA0/aA",
-  "manifest.router.js": "sha384-uVGpY/d+v4fK0rR1wkePGe11LrNE1ePyZICv7L/ob9d1p/kGxu/3Z2D2ClFuQkr8",
+  "manifest.router.js": "sha384-4qmGEkRpgAo9xoQkW6+hHIhowvcyAggKB2J3Wf8tJtXp+L0hufoVAqzfhnqw4cNR",
   "manifest.slides.js": "sha384-3uRTkyK9XPLmnxI2+igZlpi4EyPlU/7IHj5j3BZJJ2KN455vXyk99fiXV3feO/XY",
   "manifest.status.js": "sha384-fXqDnKwldB7XRxcfEQYTm/WqLl2oP24xY2Znq8FqnFM9LQo0zrQkXszqAOksArUX",
   "manifest.svg.js": "sha384-qr/8H9+2cIhSXNbRWRtIdrDlTOxKlNJqwEefHvCYoiBNW/kKhPTFa109Orv/EBnb",
@@ -34,5 +35,5 @@
   "manifest.url.parameters.js": "sha384-J2aSVBOPsoqsbafHndrWLHEDpKb4AKJAoQnVmKA4gZh5P/8HHjFWHO/lkusmG84l",
   "manifest.utilities.js": "sha384-YcGKTEviTv9FLkw890CTociA7Rjp6xuhLyfpn3Gk4mT0fexDFqpW7VSuohcpGfsw",
   "manifest.virtual.js": "sha384-YwwmAsZNddajnAkLhBWtrK8edHMJOhD7cJkQi3qmm5o1Thg0wbtDU0dsfrCHKTIQ",
-  "manifest.js": "sha384-IaRa1ZZNj8C/mcB9e6qNiTqK7oriQr0Vmt4Q7FcGWOqfUgPxojYixbs+g8XR9lNz"
+  "manifest.js": "sha384-4r0X5QSeiQ6bGMrw4Y8CDhTAS38w7CPXyxrid+l+sGWEwJ2XRG0STzrLU6XF+GIX"
 }

package/lib/manifest.js

@@ -227,6 +227,7 @@
 		'dropdowns',
 		'combobox',
 		'computed',
+		'bindings',
 		'tabs',
 		'text-edit',
 		'slides',

package/lib/manifest.router.js

@@ -636,39 +636,21 @@ function isPrerenderedStaticMPA() {
     }
 }
 
-// Process visibility for all elements with x-route
-function processRouteVisibility(normalizedPath) {
-    // Static prerender output already contains only this route's sections; x-cloak + toggling here
-    // causes a visible flash (content → hidden via x-cloak → shown when Alpine boots).
-    if (isPrerenderedStaticMPA()) return;
-
-    const routeElements = document.querySelectorAll('[x-route]');
-
-    // First pass: collect all defined routes (excluding !* and other negative conditions)
-    const definedRoutes = [];
-    routeElements.forEach(element => {
-        const routeCondition = element.getAttribute('x-route');
-        if (!routeCondition) return;
-
-        const conditions = routeCondition.split(',').map(cond => cond.trim());
-        conditions.forEach(cond => {
-            // Only collect positive conditions and wildcards (not negative ones)
-            if (!cond.startsWith('!') && cond !== '!*') {
-                definedRoutes.push(cond);
-            }
-        });
-    });
+// Logical path for the current URL, normalized the way route conditions expect
+function currentNormalizedPath() {
+    const currentPath = window.ManifestRoutingNavigation?.getCurrentRoute() ?? window.location.pathname;
+    return currentPath === '/' ? '/' : currentPath.replace(/^\/|\/$/g, '');
+}
 
-    // Extract localization codes from manifest.json data sources
+// Localization codes from manifest.json data sources
+function getLocalizationCodes() {
     const localizationCodes = [];
     try {
-        // Check if manifest is available and has data sources
         const manifest = window.ManifestComponentsRegistry?.manifest || window.manifest;
         if (manifest && manifest.data) {
             Object.values(manifest.data).forEach(dataSource => {
                 if (typeof dataSource === 'object' && dataSource !== null) {
                     Object.keys(dataSource).forEach(key => {
-                        // Check if this looks like a localization key (common language codes)
                         if (key.match(/^[a-z]{2}(-[A-Z]{2})?$/)) {
                             localizationCodes.push(key);
                         }
@@ -679,80 +661,117 @@ function processRouteVisibility(normalizedPath) {
     } catch (e) {
         // Ignore errors if manifest is not available
     }
+    return localizationCodes;
+}
 
-    // Check if current route is defined by any route
-    let isRouteDefined = definedRoutes.some(route =>
+// Positive conditions of every route, including routes stashed inside a deferred route
+function collectDefinedRoutes() {
+    const definedRoutes = [];
+    const collect = (element) => {
+        const routeCondition = element.getAttribute('x-route');
+        if (!routeCondition) return;
+        routeCondition.split(',').map(cond => cond.trim()).forEach(cond => {
+            if (!cond.startsWith('!') && cond !== '!*') definedRoutes.push(cond);
+        });
+    };
+    document.querySelectorAll('[x-route]').forEach(collect);
+    document.querySelectorAll('[x-route] > template[data-mnfst-defer]').forEach(tpl => {
+        tpl.content.querySelectorAll('[x-route]').forEach(collect);
+    });
+    return definedRoutes;
+}
+
+// Whether any defined route (or its localized form) covers the path — drives x-route="!*"
+function isRouteDefined(normalizedPath, definedRoutes) {
+    let defined = definedRoutes.some(route =>
         window.ManifestRouting.matchesCondition(normalizedPath, route)
     );
-
-    // Also check if the route starts with a localization code
-    if (!isRouteDefined && localizationCodes.length > 0) {
+    const localizationCodes = getLocalizationCodes();
+    if (!defined && localizationCodes.length > 0) {
         const pathSegments = normalizedPath.split('/').filter(segment => segment);
-        if (pathSegments.length > 0) {
-            const firstSegment = pathSegments[0];
-            if (localizationCodes.includes(firstSegment)) {
-                // This is a localized route - check if the remaining path is defined
-                const remainingPath = pathSegments.slice(1).join('/');
-
-                // If no remaining path, treat as root route
-                if (remainingPath === '') {
-                    isRouteDefined = definedRoutes.some(route =>
-                        window.ManifestRouting.matchesCondition('/', route) ||
-                        window.ManifestRouting.matchesCondition('', route)
-                    );
-                } else {
-                    // Check if the remaining path matches any defined route
-                    isRouteDefined = definedRoutes.some(route =>
-                        window.ManifestRouting.matchesCondition(remainingPath, route)
-                    );
-                }
+        if (pathSegments.length > 0 && localizationCodes.includes(pathSegments[0])) {
+            const remainingPath = pathSegments.slice(1).join('/');
+            if (remainingPath === '') {
+                defined = definedRoutes.some(route =>
+                    window.ManifestRouting.matchesCondition('/', route) ||
+                    window.ManifestRouting.matchesCondition('', route)
+                );
+            } else {
+                defined = definedRoutes.some(route =>
+                    window.ManifestRouting.matchesCondition(remainingPath, route)
+                );
             }
         }
     }
+    return defined;
+}
+
+// Match one route element against a path: true/false, or null when it carries no condition
+function routeMatches(element, normalizedPath, defined) {
+    const routeCondition = element.getAttribute('x-route');
+    if (!routeCondition) return null;
+
+    const conditions = routeCondition.split(',').map(cond => cond.trim());
+    if (conditions.includes('!*')) {
+        if (defined === undefined) defined = isRouteDefined(normalizedPath, collectDefinedRoutes());
+        return !defined;
+    }
 
-    routeElements.forEach(element => {
-        const routeCondition = element.getAttribute('x-route');
-        if (!routeCondition) return;
+    const positiveConditions = conditions.filter(cond => !cond.startsWith('!'));
+    const negativeConditions = conditions
+        .filter(cond => cond.startsWith('!'))
+        .map(cond => cond.slice(1));
+    const hasNegativeMatch = negativeConditions.some(cond =>
+        window.ManifestRouting.matchesCondition(normalizedPath, cond)
+    );
+    const hasPositiveMatch = positiveConditions.length === 0 || positiveConditions.some(cond =>
+        window.ManifestRouting.matchesCondition(normalizedPath, cond)
+    );
+    return hasPositiveMatch && !hasNegativeMatch;
+}
 
-        // Parse route conditions
-        const conditions = routeCondition.split(',').map(cond => cond.trim());
-        const positiveConditions = conditions.filter(cond => !cond.startsWith('!'));
-        const negativeConditions = conditions
-            .filter(cond => cond.startsWith('!'))
-            .map(cond => cond.slice(1));
-
-        // Special handling for !* (undefined routes)
-        if (conditions.includes('!*')) {
-            const shouldShow = !isRouteDefined;
-            if (shouldShow) {
-                element.removeAttribute('hidden');
-                element.style.display = '';
-            } else {
-                element.setAttribute('hidden', '');
-                element.style.display = 'none';
-            }
-            return;
-        }
+// Cooperative check (defer plugin): is this route active for the current URL? Static MPA output always is.
+function isRouteActive(element, normalizedPath) {
+    if (isPrerenderedStaticMPA()) return true;
+    return routeMatches(element, normalizedPath === undefined ? currentNormalizedPath() : normalizedPath) !== false;
+}
 
-        // Check conditions
-        const hasNegativeMatch = negativeConditions.some(cond =>
-            window.ManifestRouting.matchesCondition(normalizedPath, cond)
-        );
-        const hasPositiveMatch = positiveConditions.length === 0 || positiveConditions.some(cond =>
-            window.ManifestRouting.matchesCondition(normalizedPath, cond)
-        );
+// Activation hook fires before the route becomes visible so deferred content renders first
+function showRoute(element) {
+    element.dispatchEvent(new CustomEvent('manifest:route-activate'));
+    element.removeAttribute('hidden');
+    element.style.display = '';
+}
 
-        const shouldShow = hasPositiveMatch && !hasNegativeMatch;
+function hideRoute(element) {
+    element.setAttribute('hidden', '');
+    element.style.display = 'none';
+}
 
-        // Show/hide element
-        if (shouldShow) {
-            element.removeAttribute('hidden');
-            element.style.display = '';
+// Process visibility for all elements with x-route
+function processRouteVisibility(normalizedPath) {
+    // Static prerender output already contains only this route's sections; x-cloak + toggling here
+    // causes a visible flash (content → hidden via x-cloak → shown when Alpine boots).
+    if (isPrerenderedStaticMPA()) return;
+
+    const defined = isRouteDefined(normalizedPath, collectDefinedRoutes());
+
+    // Worklist: activating a deferred route can reveal nested routes that need this pass too
+    const seen = new Set();
+    const queue = Array.from(document.querySelectorAll('[x-route]'));
+    while (queue.length) {
+        const element = queue.shift();
+        if (seen.has(element)) continue;
+        seen.add(element);
+        const match = routeMatches(element, normalizedPath, defined);
+        if (match === null) continue;
+        if (match) {
+            showRoute(element);
+            element.querySelectorAll('[x-route]').forEach(nested => { if (!seen.has(nested)) queue.push(nested); });
         } else {
-            element.setAttribute('hidden', '');
-            element.style.display = 'none';
+            hideRoute(element);
         }
-    });
+    }
 }
 
 // Add x-cloak to route elements that don't have it
@@ -770,9 +789,7 @@ function initializeVisibility() {
     addXCloakToRouteElements();
 
     // Process initial visibility (use logical path when app is in a subpath)
-    const currentPath = window.ManifestRoutingNavigation?.getCurrentRoute() ?? window.location.pathname;
-    const normalizedPath = currentPath === '/' ? '/' : currentPath.replace(/^\/|\/$/g, '');
-    processRouteVisibility(normalizedPath);
+    processRouteVisibility(currentNormalizedPath());
 
     // Listen for route changes
     window.addEventListener('manifest:route-change', (event) => {
@@ -785,10 +802,7 @@ function initializeVisibility() {
         if (isPrerenderedStaticMPA()) return;
         // Add x-cloak to any new route elements
         addXCloakToRouteElements();
-
-        const currentPath = window.ManifestRoutingNavigation?.getCurrentRoute() ?? window.location.pathname;
-        const normalizedPath = currentPath === '/' ? '/' : currentPath.replace(/^\/|\/$/g, '');
-        processRouteVisibility(normalizedPath);
+        processRouteVisibility(currentNormalizedPath());
     });
 }
 
@@ -809,8 +823,10 @@ if (document.readyState === 'loading') {
 window.ManifestRoutingVisibility = {
     initialize: initializeVisibility,
     processRouteVisibility,
+    isRouteActive,
     isPrerenderedStaticMPA
-}; 
+};
+
 
 // Router head
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "mnfst",
-    "version": "0.5.198-next.3",
+    "version": "0.5.198",
     "private": false,
     "workspaces": [
         "templates/starter",