@lmjs/core 2.0.0 → 2.1.0

package/src/_re.js

@@ -17,6 +17,7 @@ class _v {
     static name;
     static type;
     static vars;
+    static fns;
     static rvs;
     static _pv;
     static mx;
@@ -29,6 +30,16 @@ class _v {
         this.hst = obj.hst ?? [];
         this.views = obj.views ?? [];
         this.vars = obj.vars ?? {};
+        // 2026-09-17: per-instance event-handler functions (see walk.js's
+        // matching addition, and lstnrs.js's evalEvAttr) — a subview's own
+        // `function bump(){}` still becomes a real `window.bump` too (plain
+        // <script>-tag semantics, unchanged), but multiple mounted
+        // instances of the same subview file all define a same-named
+        // function, so window.bump silently becomes whichever instance's
+        // script ran last — every instance's @click ended up calling THAT
+        // one instance's handler regardless of which was actually clicked.
+        // .fns is this instance's own, unambiguous copy.
+        this.fns = obj.fns ?? {};
         this.rvs = obj.rvs ?? {};
         this._pv = obj._pv ?? null;
         this.mx = obj.mx ?? [];
@@ -110,6 +121,67 @@ function reportLumenError(info) {
 
 function _x(_x) {
     var currPath = [];
+    // 2026-09-17: generalized from a position-specific check
+    // (`currPath[1] == "vars"`, only ever matched a flat `_vt.<root>.vars`
+    // write) to a real owner-walk — needed for per-instance subview
+    // scoping (`_vt.View.views[i].vars`, and its nested form
+    // `_vt.View.views[0].views[2].vars`), where "vars" can sit at any
+    // depth. `path` is currPath *without* the trailing "vars" segment.
+    // `Global` is a real special case, not a bug in this generalization:
+    // it has no `._re` of its own (see the object literal below — just
+    // `{vars:{}}`) since Global-var writes need to re-render whichever
+    // view is *currently* looking at that value, exactly like the
+    // pre-existing behavior this preserves. Everything else (View itself,
+    // or any views[i]/views[i].views[j]/... chain) is walked against the
+    // raw (non-proxied) tree — using the outer `_x` param directly, not
+    // the `_vt` proxy — so this traversal itself can't re-enter these
+    // traps and corrupt the in-flight currPath.
+    function _dispatchVarsUpdate(key) {
+        // "vars" can be anywhere in currPath, not just at index 1 — find
+        // it. The var name to update() is whatever comes right after it
+        // in currPath (e.g. `_vt.View.vars["obj"].nested = x` — the write
+        // itself is on "obj"'s own proxy, so `key` here is "nested", but
+        // the reactive var is "obj", one segment before it in currPath);
+        // if "vars" is the *last* segment, there's no next segment yet —
+        // that means this write IS the var (`_vt.View.vars["x"] = ...`),
+        // so `key` itself (the set() trap's own key) is the var name.
+        let varsIdx = currPath.indexOf("vars");
+        if (varsIdx === -1) return;
+        let varName = varsIdx < currPath.length - 1 ? currPath[varsIdx + 1] : key;
+        let rootPath = currPath.slice(0, varsIdx);
+        // Global has no ._re of its own (see its plain {vars:{}} literal
+        // below) — a Global write always re-renders whichever view is
+        // currently looking at it, exactly like the pre-existing behavior
+        // this preserves, for both the flat and nested-property case.
+        if (rootPath[0] === "Global") {
+            // 2026-09-18, real gap found and fixed: this file's own design
+            // comment above _vt's declaration says a Global var should be
+            // usable by "ordinary view code" just by referencing the
+            // name — but nothing ever made that true for a VIEW's own
+            // <script> statements (as opposed to mustaches/:if conditions,
+            // which already fall back to _vt.Global.vars via getVal()/
+            // evalExp()'s own merge). A view's compiled script only
+            // rewrites references to names IT ITSELF declares — it has no
+            // way to know index.js declared some other name as Global, so
+            // a bare reference to it (e.g. `rx.post(...)` where `rx =
+            // new RX(...)` was set in index.js's init()) resolved via the
+            // real JS scope chain, which only ever finds a real `window.rx`
+            // if something put it there — nothing did. Mirroring every
+            // Global write onto `window[varName]` too makes plain bare-
+            // identifier references resolve correctly and naturally,
+            // with zero per-script rewriting needed.
+            try {
+                if (typeof window !== 'undefined') window[varName] = _x.Global.vars[varName];
+            } catch (e) { }
+            if (_vt.View._re) _vt.View._re.update(varName);
+            return;
+        }
+        let owner = _x;
+        for (let i = 0; i < rootPath.length && owner; i++) {
+            owner = owner[rootPath[i]];
+        }
+        if (owner && owner._re) owner._re.update(varName);
+    }
     const handler = {
         get(target, key) {
             if (key == "__isProxy") return true;
@@ -118,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)
@@ -136,31 +218,12 @@ function _x(_x) {
             // var _View = currPath[1] == "views" ? currPath[2] : "";
 
             try {
-                // cl(["hiiiiii", currPath, key, value]);
                 // `_vt.View._re` genuinely doesn't exist yet during
                 // index.js's own bootstrap (before any view has mounted —
                 // see index-bootstrap.js) — that's the normal case now,
-                // not an error, so it's guarded here rather than left to
-                // throw into the catch below on every such write.
-                if (currPath.length == 2 && currPath[1] == "vars") {
-                    if (_vt.View._re) _vt.View._re.update(key);
-                } else if (currPath.length > 2 && currPath[1] == "vars") {
-                    let ky = clone(currPath[2]);
-                    if (_vt.View._re) _vt.View._re.update(ky);
-                }
-                // if (currPath.length) {
-                // _vt.View._re.set(key, value);
-                // }
-                // cl(currPath, _View);
-                // eval("var kira = " + "_vt." + currPath.join("."));
-                // if (kira.__isProxy) {
-                //     currPath.push(key);
-                //     eval("kira = " + "_vt." + currPath.join("."));
-                // }
-
-                // if (kira) {
-                //     // if (_el.data('_re')) _el.data('_re').set(key, value);
-                // }
+                // not an error, so it's guarded (inside _dispatchVarsUpdate)
+                // rather than left to throw into the catch below.
+                _dispatchVarsUpdate(key);
             } catch (e) {
                 cl(e);
             }
@@ -175,31 +238,7 @@ function _x(_x) {
             delete target[key];
 
             try {
-                // cl(["hiiiiii", currPath, key, value]);
-                // `_vt.View._re` genuinely doesn't exist yet during
-                // index.js's own bootstrap (before any view has mounted —
-                // see index-bootstrap.js) — that's the normal case now,
-                // not an error, so it's guarded here rather than left to
-                // throw into the catch below on every such write.
-                if (currPath.length == 2 && currPath[1] == "vars") {
-                    if (_vt.View._re) _vt.View._re.update(key);
-                } else if (currPath.length > 2 && currPath[1] == "vars") {
-                    let ky = clone(currPath[2]);
-                    if (_vt.View._re) _vt.View._re.update(ky);
-                }
-                // if (currPath.length) {
-                // _vt.View._re.set(key, value);
-                // }
-                // cl(currPath, _View);
-                // eval("var kira = " + "_vt." + currPath.join("."));
-                // if (kira.__isProxy) {
-                //     currPath.push(key);
-                //     eval("kira = " + "_vt." + currPath.join("."));
-                // }
-
-                // if (kira) {
-                //     // if (_el.data('_re')) _el.data('_re').set(key, value);
-                // }
+                _dispatchVarsUpdate(key);
             } catch (e) {
                 cl(e);
             }
@@ -240,11 +279,73 @@ function _x(_x) {
 // its vars (V1's documented convention for app-wide state like `isAdmin`)
 // need to outlive any single view. concatVarsAtLevel() below merges it into
 // every scope lookup so ordinary view code can just reference the name.
+// 2026-09-17, real bug found and fixed: `.fns` was missing here (only
+// `.vars` existed) — `walk.js`'s `_fnRegisterStatement()` (added for
+// per-instance subview scoping, see the per-instance-scoping work above)
+// unconditionally builds `<targetRoot>.fns["name"] = name;` for EVERY
+// top-level function declaration, regardless of target — including
+// `targetKey: "Global"`, used to compile index.js/project scripts. Any
+// real project with so much as one function declaration in index.js (an
+// extremely common pattern) crashed with "Cannot set properties of
+// undefined (setting '<fnName>')" the moment that line ran. Nearly
+// invisible in `lm serve` dev mode — index-bootstrap.js's synchronous XHR
+// fetch-and-eval of the compiled index.js is wrapped in a try/catch that
+// only `console.log`s the failure (never `console.error`/throws), so nothing
+// looked broken as long as the crash landed after anything load-bearing
+// (Reactor()) in that same script. Fatal in a real `lm build` production
+// bundle, where the compiled index.js is concatenated inline, unguarded —
+// 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": {} }
+    "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 = {};
@@ -388,7 +489,6 @@ class _lm {
                             } else {
                                 effect.nd.setAttribute(effect.name, this.render(effect));
                                 if (effect.name == "view") {
-                                    cl("We Must Trigger View Change", effect, this.render(effect));
                                     effect.nd.subPath = this.render(effect);
                                     renderView(this.render(effect), true, {});
                                 }
@@ -407,6 +507,19 @@ class _lm {
         this.updateCXRs();
         this.updateLXRs();
         this.updateVXRs();
+
+        // 2026-09-18: same Reactor({tick}) fix as update() below — also
+        // fired on the very first render (not just subsequent reactive
+        // updates), since a real tick() use (e.g. hljs.highlightAll())
+        // needs to run on initial content too, not just after the first
+        // change.
+        if (typeof appSettings !== 'undefined' && appSettings && typeof appSettings.tick === 'function') {
+            try {
+                appSettings.tick();
+            } catch (e) {
+                cl(e);
+            }
+        }
     }
 
     chainConnected(cx) {
@@ -423,13 +536,25 @@ class _lm {
         let subsNames = [];
         for (let i = 0; i < this.view.views.length; i++) {
             const _view = this.view.views[i];
-            cl("We Must Render A SubView", _view, subsNames.includes(_view.subPath), subsNames, _view.subPath);
             if (!subsNames.includes(_view.subPath)) subsNames.push(_view.subPath);
         }
         // cl(subsNames);
+        // 2026-09-17: real bug found and fixed — this used to always call
+        // the plain, no-args renderView(n, true, {}), which only ever
+        // searches _vt.View.views (the MAIN view's own array). That's
+        // correct when `this` IS the main view, but updateVXRs() also
+        // runs on every SUBVIEW instance's own _re (renderAll() calls it
+        // unconditionally) — for a subview that itself hosts further
+        // subviews, `this.view.views` holds THOSE, not the main view's,
+        // so the old call could never find them: nested subviews never
+        // rendered at all. Passing this.view.views + this.view.scopePath
+        // (set once, in renderHST(), when this instance itself was
+        // rendered — ["View"] for the main view, unchanged) lets
+        // renderView() search the RIGHT array and address the RIGHT
+        // nested scope regardless of how deep this instance is.
         for (let i = 0; i < subsNames.length; i++) {
             const n = subsNames[i];
-            renderView(n, true, {});
+            renderView(n, true, {}, 'views', this.view.views, this.view.scopePath || ["View"]);
         }
     }
 
@@ -531,7 +656,6 @@ class _lm {
                         } else {
                             effect.nd.setAttribute(effect.name, this.render(effect));
                             if (effect.name == "view") {
-                                cl("We Must Trigger View Change", effect, this.render(effect));
                                 effect.nd.subPath = this.render(effect);
                                 renderView(this.render(effect), true, {});
                             }
@@ -551,6 +675,24 @@ class _lm {
             const sbscr = this.sbscrbs[sbscsi];
             sbscr._re.update(k);
         }
+
+        // 2026-09-18: Reactor({tick}) — documented ("runs after every
+        // re-render, anywhere", lumenjs-spec.md §5.4/llms.md §3) but never
+        // actually called anywhere in this runtime — see this fix's fuller
+        // comment at Reactor()'s own definition (vendor/reconnecting-
+        // websocket.js) for how this was found. update() is the real
+        // per-reactive-change render point (unlike renderAll(), which only
+        // ever runs once per _lm instance, at initial mount) — this is
+        // where "after every re-render, anywhere" actually lives. Guarded
+        // on appSettings existing since update() can fire during index.js's
+        // own bootstrap, before Reactor() has run.
+        if (typeof appSettings !== 'undefined' && appSettings && typeof appSettings.tick === 'function') {
+            try {
+                appSettings.tick();
+            } catch (e) {
+                cl(e);
+            }
+        }
     }
 
     async updateLXRs(k) {
@@ -632,12 +774,61 @@ class _lm {
                             vx['value'] = marray[index]['value'];
                         } else {
                             if (forX['as']['k']) vx[forX['as']['k']] = marray[index];
+                            // 2026-09-17, real bug found and fixed: a bare
+                            // `:for="items"` (no `as item` alias) is
+                            // documented — and was V1's real, working
+                            // behavior — to spread each item's own object
+                            // keys directly into loop scope, so
+                            // `items = [{number:1}]` lets a mustache read
+                            // `{{number}}` with no alias at all. Nothing in
+                            // this branch ever did that spread — `vx` had
+                            // no alias key AND no spread keys, so a bare
+                            // mustache like this always evaluated as an
+                            // undefined identifier and silently rendered
+                            // blank. Only spread for a plain-object item —
+                            // a primitive (string/number) array item has no
+                            // keys to spread and is read via the untouched
+                            // alias path instead.
+                            else if (marray[index] && typeof marray[index] === 'object') {
+                                for (const k2 in marray[index]) {
+                                    if (Object.prototype.hasOwnProperty.call(marray[index], k2)) {
+                                        vx[k2] = marray[index][k2];
+                                    }
+                                }
+                            }
                         }
                         // cl(forX, vx);
                         // cl("VXXXX", vx, this);
 
                         if (forIf) {
-                            let isTrue = this.evalExp(forIf, vx);
+                            // 2026-09-17, real bug found and fixed:
+                            // evalExp()'s 2nd param is a NAMES array to
+                            // look up in _vt.View.vars/_vt.Global.vars (see
+                            // its other real call site, `this.evalExp(cx.content,
+                            // this.reactiveVariables)`) — but `vx` here is
+                            // a VALUES object (the just-built loop-item
+                            // scope), not a names array. `vars.length` on a
+                            // plain object is undefined, so evalExp's own
+                            // `for (i=0; i<vars.length; i++)` loop never
+                            // ran even once — every `:for-if` condition
+                            // referencing the loop item (`item.value > 10`,
+                            // the exact documented example) always
+                            // evaluated against an empty scope and either
+                            // threw (caught, filtered out) or read
+                            // `undefined`. evalExp() already has a real,
+                            // working mechanism for exactly this — it
+                            // merges `this.vrs` (the loop-scope override
+                            // object) at the highest priority — so route
+                            // through that instead of a second, broken
+                            // parameter shape.
+                            let _prevVrs = this.vrs;
+                            this.vrs = vx;
+                            let isTrue;
+                            try {
+                                isTrue = this.evalExp(forIf, []);
+                            } finally {
+                                this.vrs = _prevVrs;
+                            }
                             if (!isTrue) continue;
                         }
 
@@ -670,7 +861,29 @@ class _lm {
 
                 // cl("ATR", arrayToRender);
                 let oldATR = cx.atr;
-                cx.atr = arrayToRender;
+                // 2026-09-17, real bug found and fixed: cx.atr used to
+                // store a reference to arrayToRender's own item objects,
+                // not an independent snapshot — arrayToRender's items are
+                // the actual current elements of the reactive array (e.g.
+                // _vt.View.vars["features"]), so a completely ordinary
+                // update pattern (mutate an item in place inside .map(),
+                // return the same reference — `f.done = !f.done; return
+                // f;`, not "rebuild a new object") left oldATR and the
+                // next render's arrayToRender pointing at the exact same,
+                // already-mutated objects by the time compareArrays()
+                // ran. deepCompare()'s JSON.stringify comparison was
+                // never wrong — it was comparing an object against
+                // itself, so every 'update' action was silently lost and
+                // the DOM never re-rendered. clone() (already used a few
+                // lines above for `vals`) gives cx.atr a true independent
+                // snapshot instead. Found clicking a real @click-toggled
+                // :for item on lumenjs.com's own real V2 homepage — no
+                // existing test used an in-place item mutation, only
+                // whole-array reassignment with new items (see render-
+                // hooks.integration.test.js's `images = [...,'c']`),
+                // which never exposed this since a length change always
+                // hits compareArrays()'s add/remove branches regardless.
+                cx.atr = clone(arrayToRender);
                 // cl(oldATR, arrayToRender);
 
                 const actions = this.compareArrays(oldATR, arrayToRender);
@@ -914,16 +1127,38 @@ 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)) {
                     vars[ky] = this.vrs[ky]
                 }
             }
+            // 2026-09-17: per-instance subview scoping — a subview's own
+            // declared vars live on `this.view.vars` (wired up in
+            // renderHST()/renderView() to be the SAME object its compiled
+            // script's `_vt.View.views[i].vars[...]` writes reach), not
+            // in the flat `_vt.View.vars` checked above (that's still
+            // only ever the MAIN view). Checked last/highest-priority,
+            // same shadowing shape as the `this.vrs` merge just above —
+            // an instance's own var wins over anything it inherited.
+            if (this.view && this.view.vars) {
+                for (const ky in this.view.vars) {
+                    if (Object.prototype.hasOwnProperty.call(this.view.vars, ky)) {
+                        vars[ky] = this.view.vars[ky];
+                    }
+                }
+            }
         } catch (e) {
             cl(e);
         }
@@ -1033,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;
         }
@@ -1157,16 +1394,97 @@ class _lm {
     createEl(tag, attrs, children, events, doc) {
         const _el = document.createElement(tag);
 
+        // 2026-09-17: every element knows which _lm instance rendered it —
+        // needed so a click on it can resolve its @click handler against
+        // the RIGHT instance's own .fns (see lstnrs.js's evalEvAttr), and
+        // (below) so an @init handler on a subview mount resolves against
+        // ITS creator's own functions/scope, not window. Stamped before
+        // anything below that might need it. Non-enumerable: real bug
+        // found and fixed — an ordinary DOM element has no own enumerable
+        // properties by default, so JSON.stringify(someElement) safely
+        // produced "{}" everywhere this codebase already did that (e.g. a
+        // real test asserting on JSON.stringify(view._slots), real DOM
+        // nodes). An ENUMERABLE back-reference here closes a genuine
+        // cycle (element -> _ownerRe -> that instance's own _RealDOM ->
+        // the same element) and breaks every one of those call sites. Defined this way
+        // instead of a plain `=` assignment so it's reachable
+        // (`el._ownerRe`) but invisible to JSON.stringify/for-in/
+        // Object.keys, matching how a parent-pointer is normally done.
+        Object.defineProperty(_el, '_ownerRe', { value: this, enumerable: false, configurable: true, writable: true });
+
         _el.isSub = false;
         if (attrs.hasOwnProperty('view')) {
             _el.isSub = true;
             _el.subPath = attrs['view'];
+            // 2026-09-17: per-instance subview scoping. `views[]` used to
+            // hold just the raw element — every instance of the same
+            // subview file shared one flat _vt.View.vars, so two mounts of
+            // the same .view file collided on the same variable slots (a
+            // real, confirmed bug — clicking one instance changed a value
+            // neither instance's DOM reflected). DOM elements already
+            // carry arbitrary extra JS properties throughout this file
+            // (.isSub, .subPath, .events) — .vars/.views here follow that
+            // same convention rather than a new parallel structure. .vars
+            // is this instance's own scope, addressed at
+            // _vt.View.views[i].vars once renderHST() wires up the path
+            // (see renderView()); .views lets this instance itself host
+            // further nested subviews the same way.
+            _el.vars = {};
+            _el.views = [];
+            _el.fns = {};
+            // 2026-09-17: `@init="fn"` — the actual, decided mechanism
+            // for giving a subview mount its own data at creation time
+            // (replaces an earlier, narrower `:data="name"` attempt —
+            // reusing the existing @before-render/@after-render hook
+            // machinery instead of a bespoke attribute, per real
+            // discussion of real use cases: a subview file mounted
+            // multiple times needing distinct config per instance — the
+            // same widget showing a different crypto coin per mount, or
+            // a :for item needing its own data slice). `fn`'s return
+            // value (a plain object) is merged into this instance's own
+            // `.vars`, so it can hand over multiple named values at once
+            // — not tied to matching a parent variable's name the way
+            // `:data` was. Reads an ancestor's own variable by name
+            // still needs no special syntax at all (getVal()/evalExp()'s
+            // existing fallthrough already covers that); @init is for
+            // data that's computed/selected specifically for this one
+            // mount. fireRenderHook() needed a real fix first (used to
+            // discard its handler's return value entirely) — see its own
+            // comment. Deliberately one-way — a subview writing back to
+            // a PARENT variable (a steps-form wizard sharing accumulated
+            // state across steps, for instance) is a real, different,
+            // not-yet-designed mechanism, not what this covers.
+            //
+            // Calls evalEvAttr() directly rather than fireRenderHook()
+            // (which every other @before-render/@after-render call site
+            // uses): createEl() itself isn't async, and this result has
+            // to be ready synchronously, before the subview actually
+            // renders (a later, separate, real async call). An @init
+            // handler that returns a Promise can't be awaited here —
+            // deliberately unsupported for now, not silently broken:
+            // only a plain object return is used.
+            if (doc && doc.evs && doc.evs.hasOwnProperty('@init')) {
+                let _initAttr = doc.evs['@init'];
+                if (_initAttr) {
+                    // 3rd arg: the CALLING scope's own loop-local bindings
+                    // (e.g. `item` from `:for="items as item"`) — these
+                    // aren't real JS variables an @init handler could
+                    // otherwise close over (it's an ordinary top-level
+                    // function, not defined inside the loop), so without
+                    // this there'd be no way for it to know which
+                    // iteration it's being called for at all.
+                    let _initResult = evalEvAttr(_initAttr, { cType: 'init' }, $(_el), 'init', this.vrs);
+                    if (_initResult && typeof _initResult === 'object' && typeof _initResult.then !== 'function') {
+                        Object.assign(_el.vars, _initResult);
+                    }
+                }
+            }
             this.view.views.push(_el);
         }
 
         _el.events = {};
         for (const prop in attrs) {
-            if (prop == "view" || prop == ":if" || prop == ":else-if" || prop == ":else" || prop == ":for" || prop == ":for-limit" || prop == ":for-offset" || prop == ":for-if") continue;
+            if (prop == "view" || prop == ":data" || prop == ":if" || prop == ":else-if" || prop == ":else" || prop == ":for" || prop == ":for-limit" || prop == ":for-offset" || prop == ":for-if") continue;
             try {
                 // cl("DD", doc);
                 let val = (doc && doc.ax.hasOwnProperty(prop)) ? "" : attrs[prop];
@@ -1265,10 +1583,48 @@ 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
+            // the View/Global loop above — the local :for-loop-scoped
+            // binding (f, k, v, index — set via tx._re.vrs = vx, see the
+            // :for update path above) correctly shadows/supplies names a
+            // view's own script never declares. evalExp() (used for
+            // :if="f.done"/:else-if conditions) never had the same merge
+            // — any :if/:else-if condition referencing a :for loop
+            // variable's property could never evaluate correctly, in any
+            // LumenJS V2 project, not just this page. It "looked" correct
+            // on first render only by coincidence: :else isn't gated by
+            // evalExp at all, so an all-false-by-default loop (every item
+            // starting unchecked) rendered the same whether the condition
+            // genuinely evaluated false or silently threw and was caught
+            // below. Found clicking a real @click-toggled :for item on
+            // lumenjs.com's own real V2 homepage.
+            for (const ky in this.vrs) {
+                if (Object.prototype.hasOwnProperty.call(this.vrs, ky)) {
+                    rvars[ky] = this.vrs[ky];
+                }
+            }
+            // 2026-09-17: same per-instance subview merge as getVal()
+            // above — a subview's own vars live on this.view.vars, not
+            // the flat _vt.View.vars checked above (always the main
+            // view). See getVal()'s matching comment for the full
+            // rationale.
+            if (this.view && this.view.vars) {
+                for (const ky in this.view.vars) {
+                    if (Object.prototype.hasOwnProperty.call(this.view.vars, ky)) {
+                        rvars[ky] = this.view.vars[ky];
+                    }
+                }
             }
         } catch (e) {
             cl(e);
@@ -1615,6 +1971,22 @@ class _lm {
                         }
                         (par.view._slots ?? (par.view._slots = {}))[slotName] = childs;
                     }
+                } else if (doc.attrs && doc.attrs.hasOwnProperty('tpl') && !doc.attrs.hasOwnProperty(':for')) {
+                    // 2026-09-17: `tpl="name"` used WITHOUT `:for=` on the
+                    // same element — the real, documented (lumenjs-
+                    // spec.md §4.3) shape always pairs the two, and only
+                    // makes sense paired: a template renders inside
+                    // whatever repeated context it's used from (see
+                    // renderSection()'s own tpl handling, for the
+                    // WITH-:for case — an element carrying both never
+                    // reaches this branch at all, since :for makes it a
+                    // 'sections'-type node the switch above already
+                    // dispatched elsewhere). Reported as a real error
+                    // rather than silently rendering nothing.
+                    reportLumenError({
+                        stage: 'tpl',
+                        error: new Error('tpl="' + doc.attrs['tpl'] + '" must be used together with :for on the same element — templates only render inside a repeated/list context.'),
+                    });
                 } else {
                     el = par.createEl(doc.name, doc.attrs, [], doc.evs, doc);
 
@@ -1797,7 +2169,26 @@ class _lm {
 }
 
 
-async function renderHST(hst, n, type = 'main', tx, _pv = null) {
+// 2026-09-17: `scopePath` (new) — where in the _vt tree THIS render's own
+// compiled <script> should write/read its reactive vars. Defaults to
+// ["View"] (the main view, unchanged behavior for every existing caller).
+// A subview mount passes its own ["View","views",i] (or the nested form
+// for a subview hosting a subview) — see renderView()'s isSub branch.
+// `ownVars`/`ownFns`/`ownViews` (new): for a subview render, the SAME
+// objects the mount element's `.vars`/`.fns`/`.views` already point to
+// (not fresh `{}`/`[]`s) — so a write through the compiled script's
+// `_vt.View.views[i].vars[...]`/`.fns[...]` path (which resolves to that
+// element's `.vars`/`.fns`) and a read through this instance's own
+// `getVal()`/`evalExp()` (`this.view.vars`) or `evalEvAttr()`
+// (`this.view.fns`) see the exact same data. `ownViews` matters for
+// NESTED subviews specifically: createEl() pushes onto `this.view.views`
+// while THIS instance is rendering — without linking that to the mount
+// element's own `.views`, a subview hosting further subviews pushed them
+// into a freshly-constructed, orphaned array nothing else could ever
+// find (real bug found testing exactly this — nested subviews mounted
+// and rendered their own content correctly, but their OWN vars/state
+// were unreachable from outside, landing in a throwaway array).
+async function renderHST(hst, n, type = 'main', tx, _pv = null, scopePath = ["View"], ownVars, ownFns, ownViews) {
 
     var reactiveVariables = hst.reactiveVars;
     hst = hst.hst;
@@ -1806,10 +2197,16 @@ async function renderHST(hst, n, type = 'main', tx, _pv = null) {
         "name": n,
         "type": type,
         "hst": hst,
-        "vars": tx?.vx,
+        "vars": ownVars ?? tx?.vx,
+        "fns": ownFns,
+        "views": ownViews,
         "rvs": reactiveVariables,
         "_pv": _pv
     }));
+    // 2026-09-17: persisted so THIS instance can later render ITS OWN
+    // subviews (updateVXRs() -> renderView()) at the right nested path —
+    // see both of those for the other half of this.
+    _re.view.scopePath = scopePath;
 
     if (Object.keys(_re._cc).length) {
 
@@ -1882,7 +2279,7 @@ async function renderHST(hst, n, type = 'main', tx, _pv = null) {
                 const jses = _re._jj[ky];
                 for (let inde = 0; inde < jses.length; inde++) {
                     const nd = jses[inde].nd;
-                    let code = getWatcher(nd._jst, _re.view, reactiveVariables).code;
+                    let code = getWatcher(nd._jst, _re.view, reactiveVariables, scopePath).code;
                     code = `try { ` + code + ` } catch (e) { reportLumenError({ stage: 'script', error: e }); }`;
                     // sourceURL: DevTools shows this <script>'s errors against
                     // "<viewname>.view" instead of an anonymous VM context.
@@ -1936,8 +2333,16 @@ async function fireRenderHook(cx, n, containerEl, extra) {
     let ev = Object.assign({ cType: n }, extra || {});
     let result = evalEvAttr(attrVal, ev, $(containerEl), n);
     if (result && typeof result.then === 'function') {
-        try { await result; } catch (e) { }
+        // 2026-09-17: this used to just await-and-discard. @init (new,
+        // subview mounts) needs the handler's actual return value — its
+        // whole purpose is "compute this instance's own initial data" —
+        // so a Promise result is now awaited AND returned, not thrown
+        // away. Every existing @before-render/@after-render caller
+        // already ignores this function's return value (none of them
+        // needed it), so this is additive, not a behavior change for them.
+        try { return await result; } catch (e) { return undefined; }
     }
+    return result;
 }
 
 // 2026-09-16: V1's real automatic plugin-init pass — [sl] (Select2),
@@ -2126,7 +2531,45 @@ async function renderSection(tx, doc, par, k, sectionsData) {
 
     var hst = doc.children;
 
-    let _re = await renderHST({ hst, mxes: [] }, tx.key, 'section', tx, par);
+    // 2026-09-17: `tpl="name"` on a :for element (`<li :for="items as
+    // item" tpl="row"></li>`, the real, documented — lumenjs-spec.md
+    // §4.3 — shape; never built in V2 until now). A :for element's own
+    // `doc.children` is empty (there's nothing between its tags in the
+    // source), which is exactly what's rendered per item above — so
+    // this substitutes the template file's own HST as this section's
+    // children instead, walked by the SAME engine instance rendering
+    // everything else here (this section already has its own vx/vrs —
+    // no separate scope, no isolated instance, just this item's content).
+    if (doc.attrs && doc.attrs.hasOwnProperty('tpl')) {
+        let _payload = (typeof _vcD !== 'undefined' && _vcD) || (typeof _vcData !== 'undefined' ? _vcData : undefined);
+        let _tplName = doc.attrs['tpl'];
+        let _tplKey = btoa("src/tpls/" + _tplName + ".tpl");
+        let _tplEntry = _payload && _payload.tpls && _payload.tpls[_tplKey];
+        if (_tplEntry) {
+            hst = _tplEntry.hst;
+        } else {
+            reportLumenError({
+                stage: 'tpl',
+                error: new Error('tpl="' + _tplName + '" — no such file at src/tpls/' + _tplName + '.tpl'),
+            });
+        }
+    }
+
+    // 2026-09-17: real bug found and fixed — a subview mounted INSIDE a
+    // :for item (e.g. <div :for="items as item"><div view="widgets/
+    // card"></div></div>) never worked at all: renderHST() used to always
+    // build a fresh, empty `.views` array for whatever it constructs
+    // (see _v's constructor), so createEl() calls made while rendering
+    // THIS item's own content pushed the subview's mount element onto a
+    // throwaway array nothing else could ever find — renderView()'s
+    // isSub search only ever looks at the ENCLOSING view's real `.views`
+    // (or a nested subview's own, itself wired the same way). Passing
+    // par's own `.view.views`/`.scopePath` through here makes every
+    // loop item share the SAME real registry as its enclosing view, so
+    // subview mounts inside a loop accumulate into one addressable array
+    // (sequential index, in render order) exactly like a static mount —
+    // same mechanism either way, just a dynamically-arriving index.
+    let _re = await renderHST({ hst, mxes: [] }, tx.key, 'section', tx, par, par?.view?.scopePath || ["View"], undefined, undefined, par?.view?.views);
     // if(par) {
     //     _re.reactiveVariables = par.reactiveVariables;
     // }
@@ -2157,11 +2600,18 @@ async function renderSection(tx, doc, par, k, sectionsData) {
     return _re;
 }
 
-async function renderView(n, isSub, d, type = 'views') {
+// `viewsArr`/`scopeBase` (2026-09-17): which subview registry to search
+// and which scope path to address matches under — default to the main
+// view's own (_vt.View.views / ["View"]) for the top-level, non-recursive
+// caller (ws.js's real navigation, index-bootstrap.js, etc. — all
+// unaffected, still work exactly as before). A subview instance rendering
+// ITS OWN subviews (updateVXRs(), above) passes its own `.views`/
+// `.scopePath` instead, so nested subviews resolve against the RIGHT
+// array at the RIGHT nested address instead of always the main view's.
+async function renderView(n, isSub, d, type = 'views', viewsArr, scopeBase = ["View"]) {
     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 ?? {};
@@ -2213,23 +2663,42 @@ async function renderView(n, isSub, d, type = 'views') {
         // return;
 
         if (isSub) {
+            // 2026-09-17: per-instance subview scoping — each matched
+            // element needs ITS OWN index within the search array (not its
+            // position in this filtered-by-subPath list) so its compiled
+            // script rewrites into `<scopeBase>.views[<that exact index>].vars`,
+            // not the flat `_vt.View.vars` every subview used to collide on.
+            // Searches viewsArr (this main view's _vt.View.views by
+            // default — unchanged for the top-level caller) or, when
+            // called recursively from a subview instance's own
+            // updateVXRs(), THAT instance's own `.views` — see
+            // updateVXRs() for why nested subviews need this.
+            let searchArr = viewsArr || _vt.View.views;
             let els = [];
-            for (let i = 0; i < _vt.View.views.length; i++) {
-                let _el = _vt.View.views[i];
+            for (let i = 0; i < searchArr.length; i++) {
+                let _el = searchArr[i];
                 if (_el.__isProxy) _el = _el.target;
-                if (_el.subPath == n) els.push(_el);
+                if (_el.subPath == n) els.push({ el: _el, viewsIndex: i });
             }
             if (els.length) {
                 // cl(els);
                 for (let i = 0; i < els.length; i++) {
-                    let _re = await renderHST(hst, n, 'sub');
-                    const el = els[i];
+                    const { el, viewsIndex } = els[i];
+                    // Create/reuse el.vars BEFORE rendering, so the fresh
+                    // _v instance renderHST() constructs uses this EXACT
+                    // object as its own .vars — see renderHST()'s ownVars
+                    // param comment for why that identity matters.
+                    el.vars = el.vars || {};
+                    el.views = el.views || [];
+                    el.fns = el.fns || {};
+                    let _re = await renderHST(hst, n, 'sub', undefined, null, scopeBase.concat(["views", viewsIndex]), el.vars, el.fns, el.views);
+                    el._re = _re;
                     el.innerHTML = "";
                     // cl(el);
                     el.append(..._re._RealDOM);
                     _re.renderAll();
                 }
-                // _re._RealDOM.forEach(_el => el[0].appendChild(_el)) 
+                // _re._RealDOM.forEach(_el => el[0].appendChild(_el))
                 // cl(_re);
             }
         } else {
@@ -2255,12 +2724,21 @@ async function renderView(n, isSub, d, type = 'views') {
 
                 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");
                     }
@@ -2270,6 +2748,59 @@ async function renderView(n, isSub, d, type = 'views') {
                     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;