@lmjs/core 2.0.2 → 2.1.1

package/src/_re.js

@@ -190,7 +190,17 @@ function _x(_x) {
             // so a stale tail from a prior _vt.Global read (which never hit
             // "View" to reset it) would otherwise get prepended to the next
             // chain and corrupt which key set()'s update(key) fires for.
-            if (key == "View" || key == "Global") currPath = [];
+            // 2026-09-18: generalized from a hardcoded `key == "View" ||
+            // key == "Global"` name list (which needed editing every time a
+            // new permanent root, e.g. "Widgets", got added) to the one
+            // thing that's actually invariant: `target === _x` is only ever
+            // true for THIS proxy's own outermost target (the raw root
+            // object this whole closure was built from) — any nested proxy
+            // in the tree wraps some OTHER object as its target, never `_x`
+            // itself. So this fires on any fresh top-level access
+            // (`_vt.View`, `_vt.Global`, `_vt.Widgets`, ...) regardless of
+            // the key name, with nothing new to maintain per root added.
+            if (target === _x) currPath = [];
             currPath.push(key);
             if (typeof target[key] === 'object' && target[key] !== null && key != "_re") {
                 // cl("salsaa", target, key)
@@ -287,11 +297,55 @@ function _x(_x) {
 // an uncaught exception there aborts every remaining statement in the
 // whole bundle file, breaking the entire app on every real production
 // site with this pattern. Found deploying lumenjs.com's own real build.
+// "Widgets" (2026-09-18): a third permanent root, sibling of Global/View,
+// generalizing V1's hardcoded hasNav/hasHeader/hasFooter widget-loading past
+// its fixed 3-name list — see renderView()'s layout branch below for the
+// resolve/mount/diff logic, and fcs.js's annotateLayoutRegions() for how a
+// layout's own bare attributes (e.g. `<nav nav>`) become the region names
+// used to key this object. Deliberately NOT an ancestor of View in the
+// scope tree (widget regions and [body] are DOM SIBLINGS under the layout
+// root, never one containing the other — unlike a subview's real, singular
+// parent, there's no single unambiguous "the" widget a view could shadow
+// into) — each entry gets its own real `._re` instead (see
+// _dispatchVarsUpdate's generic owner-walk below, which already handles
+// this with zero special-casing once an entry has `._re` set, same as any
+// subview). Starts empty; populated lazily, one entry per declared region
+// name, the first time a layout using that region is mounted.
 let _vt = _x({
     "View": new _v({}),
-    "Global": { "vars": {}, "fns": {} }
+    "Global": { "vars": {}, "fns": {} },
+    "Widgets": {}
 });
 
+// 2026-09-18: shared by getVal()/evalExp()/concatVarsAtLevel() below, so the
+// "first-declared widget wins on a name collision" rule is defined exactly
+// once. Object key iteration order for string keys is real insertion order,
+// so this naturally checks widgets in the order they were first mounted —
+// which, in practice, is document order (renderView()'s layout branch walks
+// `hstL.regions`, itself built in document order by fcs.js's
+// annotateLayoutRegions()).
+function _lookupInWidgets(name) {
+    for (const wname in _vt.Widgets) {
+        if (_vt.Widgets[wname].vars.hasOwnProperty(name)) return _vt.Widgets[wname].vars[name];
+    }
+    return undefined;
+}
+
+// concatVarsAtLevel() below merges via object spread, not the loop-with-
+// break shape _lookupInWidgets() uses — spread's "later wins" needs the
+// widgets merged in REVERSE declaration order so the first-declared widget
+// still wins a name collision, matching _lookupInWidgets()'s own semantics
+// exactly (both must agree, since getVal()/evalExp() use one and
+// concatVarsAtLevel()/lookup()/scopedEval() use the other for the same read).
+function _mergedWidgetsVars() {
+    let out = {};
+    let names = Object.keys(_vt.Widgets).reverse();
+    for (const wname of names) {
+        out = { ...out, ..._vt.Widgets[wname].vars };
+    }
+    return out;
+}
+
 class _lm {
     _RealDOM = [];
     _effects = {};
@@ -1073,10 +1127,17 @@ class _lm {
                 // lookup()/scopedEval(); getVal() (what mustache text nodes
                 // actually call) had its own separate, unmerged read here
                 // and was silently rendering these as empty.
+                // 2026-09-18: inserted a middle tier — _lookupInWidgets()
+                // (all currently-mounted widgets' vars, first-declared
+                // wins) — between View and Global, per this session's
+                // agreed read-fallback order.
                 let __name = this.reactiveVariables[i];
-                vars[__name] = _vt.View.vars.hasOwnProperty(__name)
-                    ? _vt.View.vars[__name]
-                    : _vt.Global.vars[__name];
+                if (_vt.View.vars.hasOwnProperty(__name)) {
+                    vars[__name] = _vt.View.vars[__name];
+                } else {
+                    let _wv = _lookupInWidgets(__name);
+                    vars[__name] = _wv !== undefined ? _wv : _vt.Global.vars[__name];
+                }
             }
             for (const ky in this.vrs) {
                 if (Object.prototype.hasOwnProperty.call(this.vrs, ky)) {
@@ -1207,8 +1268,10 @@ class _lm {
                 // Global vars (index.js's top-level state, see _vt.Global
                 // above) sit at the lowest priority here — a view or a
                 // narrower scope declaring the same name shadows it, same
-                // as real JS scoping would.
-                concatenatedVars = { ..._vt.Global.vars, ...parent.view.vars, ...concatenatedVars };
+                // as real JS scoping would. 2026-09-18: widgets' vars sit
+                // one tier above Global, below the view's own — see
+                // _mergedWidgetsVars()'s comment for the ordering rationale.
+                concatenatedVars = { ..._vt.Global.vars, ..._mergedWidgetsVars(), ...parent.view.vars, ...concatenatedVars };
             }
             return concatenatedVars;
         }
@@ -1462,12 +1525,11 @@ class _lm {
         // minified code) — [sl]/[color]/[time]/[date]/[datetime] elements
         // become their respective widgets on mount, no explicit script
         // call needed, matching V1's documented behavior (lumenjs-
-        // spec.md §5.6/§6.7). Built into core directly rather than living
-        // only in the --with-plugins bundle (explicit choice, 2026-09-16)
-        // — autoInitPlugins() itself guards every call on the matching
-        // $.fn.* method actually existing, so a plain (no --with-plugins)
-        // project's dom-shim-based bundle silently no-ops instead of
-        // throwing when it encounters one of these attributes.
+        // spec.md §5.6/§6.7). Built into core directly, always available
+        // (explicit choice, 2026-09-16) — autoInitPlugins() itself guards
+        // every call on the matching $.fn.* method actually existing, so a
+        // plain project with no plugins selected silently no-ops instead
+        // of throwing when it encounters one of these attributes.
         autoInitPlugins(_el, attrs);
 
         return _el;
@@ -1520,10 +1582,15 @@ class _lm {
                 // value scopedEval() would otherwise have found in
                 // _vt.Global.vars — breaking :if/:for conditions on any
                 // index.js-declared var, not just mustache text (getVal()).
+                // 2026-09-18: same middle tier as getVal() — see its
+                // matching comment.
                 let __name = vars[i];
-                rvars[__name] = _vt.View.vars.hasOwnProperty(__name)
-                    ? _vt.View.vars[__name]
-                    : _vt.Global.vars[__name];
+                if (_vt.View.vars.hasOwnProperty(__name)) {
+                    rvars[__name] = _vt.View.vars[__name];
+                } else {
+                    let _wv = _lookupInWidgets(__name);
+                    rvars[__name] = _wv !== undefined ? _wv : _vt.Global.vars[__name];
+                }
             }
             // 2026-09-17, real bug found and fixed: getVal() (mustache
             // text, e.g. {{f.name}}) has always merged this.vrs in after
@@ -2284,12 +2351,11 @@ async function fireRenderHook(cx, n, containerEl, extra) {
 // (SBEACDN/s.beacdn.com/beajs/core.js:2846/3834, confirmed against the
 // real V1 build root this session already located, not reverse-engineered
 // from minified code). Called from createEl() on every element's mount.
-// Deliberately built into packages/core's own engine rather than kept
-// inside the --with-plugins bundle only — every call below is guarded on
-// the matching $.fn.* method actually existing, so a plain project (no
-// --with-plugins, dom-shim-based, none of these libraries loaded) safely
-// no-ops instead of throwing when a view happens to use one of these
-// attributes.
+// Deliberately built into packages/core's own engine, always available —
+// every call below is guarded on the matching $.fn.* method actually
+// existing, so a plain project (dom-shim-based, none of these libraries
+// loaded) safely no-ops instead of throwing when a view happens to use one
+// of these attributes.
 function autoInitPlugins(el, attrs) {
     if (!attrs) return;
     try {
@@ -2400,9 +2466,9 @@ var _dbcrsTime = 250;
 
 // Real V1 source, ported as-is (SBEACDN core.js:3834-3891) — bootstrap-
 // datetimepicker option builder + optional start/end date-linking. Not
-// documented in lumenjs-spec.md (see PROVENANCE.md's --with-plugins
-// section); this exact option shape was confirmed directly against V1's
-// real source once it was located this session, not reverse-engineered.
+// documented in lumenjs-spec.md (see PROVENANCE.md's plugins section);
+// this exact option shape was confirmed directly against V1's real source
+// once it was located this session, not reverse-engineered.
 function dtp(el, t) {
     el.removeAttr(t);
     let opts = {
@@ -2544,7 +2610,6 @@ async function renderView(n, isSub, d, type = 'views', viewsArr, scopeBase = ["V
     let filePath = "src/views/" + n + ".view"
     if (type == 'layouts') filePath = "src/layouts/" + n + ".layout";
 
-    cl(arguments);
     let fileKey = btoa(filePath);
     if (!isSub) {
         View.props = d ?? {};
@@ -2657,12 +2722,21 @@ async function renderView(n, isSub, d, type = 'views', viewsArr, scopeBase = ["V
 
                 let appSelector = appSettings.App ?? "[app]";
                 var appContainer = $(appSelector);
+                // 2026-09-18: whether THIS call just replaced the layout's
+                // own DOM wholesale — needed below by the widget
+                // resolve/mount/diff pass, since a widget whose resolution
+                // hasn't changed still needs its already-rendered nodes
+                // reattached to the fresh layout element (the old one they
+                // were living in is gone), even though nothing about the
+                // widget itself needs re-rendering.
+                let layoutJustSwapped = false;
                 if (appContainer.length) {
                     let currentLayout = $(appSelector).data('layout');
                     if (currentLayout != layout) {
                         let _rel = await renderHST(hstL, layout, 'layout');
                         appContainer.data('layout', layout).html(_rel._RealDOM);
                         _rel.renderAll();
+                        layoutJustSwapped = true;
                     } else {
                         // cl("Same Layout");
                     }
@@ -2672,6 +2746,59 @@ async function renderView(n, isSub, d, type = 'views', viewsArr, scopeBase = ["V
                     appContainer = $(appSelector);
                     appContainer.data('layout', layout).html(_rel._RealDOM);
                     _rel.renderAll();
+                    layoutJustSwapped = true;
+                }
+
+                // Persistent layout widgets (_vt.Widgets, 2026-09-18) — see
+                // that object's own declaration comment for the design.
+                // Runs on EVERY navigation, not gated on layoutJustSwapped:
+                // a view's own settings (hasNav: false, hasNav: "nav2", ...)
+                // can change what belongs in a region even when the layout
+                // itself didn't change at all. hstL.regions is precomputed
+                // build-time by fcs.js's annotateLayoutRegions() — the bare
+                // (valueless) attribute names the CURRENTLY MOUNTED layout
+                // itself declares (e.g. ["header","nav","footer"] for
+                // `<header header>`/`<nav nav>`/`<footer footer>`).
+                let declaredRegions = (hstL && hstL.regions) || [];
+                for (const regionName of declaredRegions) {
+                    let settingsKey = "has" + regionName[0].toUpperCase() + regionName.slice(1);
+                    let want = _re.view.settings.hasOwnProperty(settingsKey) ? _re.view.settings[settingsKey] : true;
+                    let resolvedFile = want === false ? null : (want === true ? regionName : want);
+
+                    let w = _vt.Widgets[regionName] || (_vt.Widgets[regionName] = { vars: {}, fns: {}, views: [], _re: null, _resolvedFile: undefined });
+
+                    if (resolvedFile !== w._resolvedFile) {
+                        // Resolution genuinely changed since the last time
+                        // this region was resolved — mount fresh, or clear.
+                        if (resolvedFile === null) {
+                            $('[' + regionName + ']').html('');
+                            w._re = null;
+                        } else {
+                            let wFilePath = "src/views/widgets/" + resolvedFile + ".view";
+                            let wHst = _payload['views'][btoa(wFilePath)];
+                            if (wHst) {
+                                let _rew = await renderHST(wHst, resolvedFile, 'widget', undefined, null, ["Widgets", regionName], w.vars, w.fns, w.views);
+                                w._re = _rew;
+                                $('[' + regionName + ']').html(_rew._RealDOM);
+                                _rew.renderAll();
+                            }
+                        }
+                        w._resolvedFile = resolvedFile;
+                    } else if (layoutJustSwapped && w._re) {
+                        // Same widget as before, but the layout element it
+                        // lives in was just replaced wholesale — reattach
+                        // the EXISTING rendered nodes (.html() moves real
+                        // node references, same as [body]/[slot] below,
+                        // it doesn't clone) rather than re-rendering. The
+                        // widget's own state (w.vars/.fns/.views) never
+                        // lived on the old DOM to begin with, so nothing
+                        // was lost — only the attachment point needed
+                        // fixing up.
+                        $('[' + regionName + ']').html(w._re._RealDOM);
+                    }
+                    // else: nothing changed and the layout didn't just
+                    // swap — this region's DOM/state is left completely
+                    // untouched, on purpose (the whole point of this).
                 }
 
                 // return;