@lmjs/core 1.0.7 → 2.0.0

package/src/dom-shim.js

@@ -0,0 +1,473 @@
+// dom-shim.js — a minimal jQuery-compatible layer.
+//
+// Scope, deliberately narrow: covers exactly the surface LumenJS's own core
+// (_re.js, walk.js, ws.js, lstnrs.js) uses internally, plus the documented
+// app-facing API (el.css/.data/.val/.attr, el[0], .trigger) from
+// lumenjs-spec.md §6.3/§10. Scoped by grepping actual usage across the core
+// files, not guessed.
+//
+// This is NOT a jQuery replacement for everything — optional plugins
+// (Select2, Flickity, the colorpicker, etc.) stay on real jQuery when a page
+// opts into them, since they're third-party code written against jQuery's
+// actual $.fn plugin architecture. This shim only has to satisfy the core
+// runtime, which is what makes it small.
+(function (global) {
+    function toArray(x) {
+        if (x == null) return [];
+        if (typeof NodeList !== 'undefined' && x instanceof NodeList) return Array.prototype.slice.call(x);
+        if (typeof HTMLCollection !== 'undefined' && x instanceof HTMLCollection) return Array.prototype.slice.call(x);
+        if (Array.isArray(x)) return x;
+        if (x instanceof $) return Array.prototype.slice.call(x);
+        return [x];
+    }
+
+    function $(selector, context) {
+        if (!(this instanceof $)) return new $(selector, context);
+
+        var els = [];
+        var sel = undefined;
+        if (!selector) {
+            els = [];
+        } else if (typeof selector === 'string') {
+            var trimmed = selector.trim();
+            if (trimmed[0] === '<') {
+                var tpl = document.createElement('template');
+                tpl.innerHTML = trimmed;
+                els = toArray(tpl.content.childNodes).filter(function (n) { return n.nodeType === 1; });
+            } else {
+                sel = selector;
+                var root = context ? (context instanceof $ ? context[0] : context) : document;
+                els = root ? toArray(root.querySelectorAll(selector)) : [];
+            }
+        } else {
+            els = toArray(selector);
+        }
+
+        for (var i = 0; i < els.length; i++) this[i] = els[i];
+        this.length = els.length;
+        this.selector = sel;
+        return this;
+    }
+
+    $.fn = $.prototype;
+    $.fn.jquery = 'lumenjs-shim';
+
+    $.fn.extend = function (methods) {
+        for (var k in methods) if (Object.prototype.hasOwnProperty.call(methods, k)) $.fn[k] = methods[k];
+        return $;
+    };
+    $.extend = function (target) {
+        for (var i = 1; i < arguments.length; i++) {
+            var src = arguments[i];
+            for (var k in src) if (Object.prototype.hasOwnProperty.call(src, k)) target[k] = src[k];
+        }
+        return target;
+    };
+
+    // jQuery's own Event wrapper — used internally by the vendored WebWorker
+    // helper (`new $.Event(type)`, then it assigns custom properties onto
+    // the result). A plain native Event supports arbitrary property
+    // assignment already, so this just needs to exist as a constructor.
+    $.Event = function (type, props) {
+        var e = typeof type === 'string' ? new Event(type, { bubbles: true, cancelable: true }) : type;
+        if (props) for (var k in props) e[k] = props[k];
+        return e;
+    };
+
+    $.proxy = function (fn, context) { return fn.bind(context); };
+    $.trim = function (s) { return (s == null ? '' : String(s)).trim(); };
+    $.inArray = function (val, arr) { return Array.prototype.indexOf.call(arr, val); };
+    $.each = function (arr, fn) {
+        if (Array.isArray(arr) || arr instanceof $) {
+            for (var i = 0; i < arr.length; i++) if (fn.call(arr[i], i, arr[i]) === false) break;
+        } else {
+            for (var k in arr) if (fn.call(arr[k], k, arr[k]) === false) break;
+        }
+        return arr;
+    };
+    // Minimal fetch-based $.ajax — covers ws.js's one call site (a plain
+    // GET/POST with success/error callbacks), not jQuery's full option set.
+    // Fires the global ajaxStart/ajaxStop events real jQuery provides for a
+    // loading-indicator pattern (`$(document).ajaxStart(...)`) — used at
+    // _re.js's top level.
+    var _ajaxActive = 0;
+    $.ajax = function (opts) {
+        opts = opts || {};
+        var method = (opts.method || opts.type || 'GET').toUpperCase();
+        var init = { method: method, headers: opts.headers || {} };
+        if (opts.data != null && method !== 'GET') {
+            init.body = typeof opts.data === 'string' ? opts.data : JSON.stringify(opts.data);
+        }
+        if (_ajaxActive === 0) $(document).trigger('ajaxStart');
+        _ajaxActive++;
+        $(document).trigger('ajaxSend');
+        return fetch(opts.url, init)
+            .then(function (res) {
+                var ct = res.headers.get('content-type') || '';
+                return ct.indexOf('json') > -1 ? res.json() : res.text();
+            })
+            .then(function (data) {
+                opts.success && opts.success(data);
+                $(document).trigger('ajaxSuccess');
+                return data;
+            })
+            .catch(function (err) {
+                opts.error && opts.error(err);
+                $(document).trigger('ajaxError');
+                throw err;
+            })
+            .finally(function () {
+                _ajaxActive--;
+                $(document).trigger('ajaxComplete');
+                if (_ajaxActive === 0) $(document).trigger('ajaxStop');
+            });
+    };
+
+    $.fn.each = function (fn) {
+        for (var i = 0; i < this.length; i++) if (fn.call(this[i], i, this[i]) === false) break;
+        return this;
+    };
+    $.fn.get = function (i) { return i === undefined ? toArray(this) : this[i]; };
+
+    $.fn.attr = function (name, value) {
+        if (value === undefined) return this[0] ? this[0].getAttribute(name) : undefined;
+        return this.each(function () { this.setAttribute(name, value); });
+    };
+    $.fn.removeAttr = function (name) {
+        return this.each(function () { this.removeAttribute(name); });
+    };
+    // Not a real jQuery method — LumenJS's own $.fn.extend addition
+    // (lstnrs.js), kept here since the core relies on it directly.
+    //
+    // 2026-09-16, real bug found and fixed: native `hasAttribute` can never
+    // see a `@`-prefixed name (`@click`, `@sort`, ...) — vendor/
+    // reconnecting-websocket.js monkey-patches HTMLElement.prototype.
+    // setAttribute/getAttribute/removeAttribute so any `@`-prefixed write
+    // is redirected to `el.events[name]` instead of the real attribute
+    // store (deliberate, real V2 framework behavior, not something this
+    // shim invented — see that file). Native `hasAttribute` was never part
+    // of that patch, so it always returned false for these, and lstnrs.js's
+    // processEv() bails immediately on `!el.hasAttr("@" + n)` — meaning
+    // every `@`-event handler's before/after-guard and payload lookup was
+    // unreachable. `getAttribute` *is* patch-aware, so route through that
+    // instead — correct for both real attributes (native getAttribute
+    // returns null when absent) and `@`-prefixed ones.
+    $.fn.hasAttr = function (name) {
+        return !!(this[0] && this[0].getAttribute(name) != null);
+    };
+    $.fn.data = function (key, value) {
+        if (value === undefined) {
+            if (!this[0]) return undefined;
+            if (key === undefined) return Object.assign({}, this[0].dataset);
+            var v = this[0].dataset[key];
+            try { return JSON.parse(v); } catch (e) { return v; }
+        }
+        return this.each(function () { this.dataset[key] = typeof value === 'string' ? value : JSON.stringify(value); });
+    };
+    $.fn.val = function (value) {
+        if (value === undefined) return this[0] ? this[0].value : undefined;
+        return this.each(function () { this.value = value; });
+    };
+    $.fn.html = function (value) {
+        if (value === undefined) return this[0] ? this[0].innerHTML : undefined;
+        // 2026-09-14, real bug found alongside .append()'s: _re.js calls
+        // `.html(_rel._RealDOM)` (an array of real Nodes, e.g. for a
+        // rendered layout/view) and `.html(_re._RealDOM)` for the view
+        // itself — a bare string assignment (`this.innerHTML = value`)
+        // coerces an array via toString(), producing garbage text like
+        // "[object HTMLDivElement]" instead of actually inserting the
+        // rendered content. Route anything non-string through the same
+        // append() normalization instead.
+        if (typeof value !== 'string') {
+            var nodes = _normalizeAppendable([value]);
+            return this.each(function () {
+                this.innerHTML = '';
+                var self = this;
+                nodes.forEach(function (n) { self.appendChild(n); });
+            });
+        }
+        return this.each(function () { this.innerHTML = value; });
+    };
+    $.fn.css = function (name, value) {
+        if (typeof name === 'object') {
+            return this.each(function () {
+                var el = this;
+                for (var k in name) el.style[k] = name[k];
+            });
+        }
+        if (value === undefined) return this[0] ? getComputedStyle(this[0])[name] : undefined;
+        return this.each(function () { this.style[name] = value; });
+    };
+    $.fn.addClass = function (cls) {
+        var list = cls.split(/\s+/).filter(Boolean);
+        return this.each(function () { this.classList.add.apply(this.classList, list); });
+    };
+    $.fn.removeClass = function (cls) {
+        var list = cls.split(/\s+/).filter(Boolean);
+        return this.each(function () { this.classList.remove.apply(this.classList, list); });
+    };
+    $.fn.hasClass = function (cls) { return !!(this[0] && this[0].classList.contains(cls)); };
+    $.fn.toggleClass = function (cls, force) {
+        var list = cls.split(/\s+/).filter(Boolean);
+        return this.each(function () {
+            var el = this;
+            list.forEach(function (c) { el.classList.toggle(c, force); });
+        });
+    };
+    $.fn.remove = function () {
+        return this.each(function () { this.parentNode && this.parentNode.removeChild(this); });
+    };
+    // Flattens real jQuery's .append()/.prepend() calling convention — any
+    // number of arguments, each a string, a real Node, a $-wrapped
+    // element, or an array of any of those — into a flat list of real
+    // Nodes. Anything else (a plain object, a number, etc.) is silently
+    // dropped, matching real jQuery's tolerance for garbage input.
+    //
+    // 2026-09-14, real bug found testing a real project against a real dev
+    // server: this file's old `.append(content)` only ever looked at its
+    // FIRST argument and assumed it was a string, a Node, or $-wrapped —
+    // `_re.js`'s `el.append(..._re._RealDOM)` (spreading a Node array) hit
+    // this whenever _RealDOM had zero or more-than-one entries, and a
+    // pre-existing, vestigial `$("body").append({beajs:true, ...})` call
+    // in vendor/reconnecting-websocket.js (a plain object, not a Node —
+    // dead/legacy code, evidenced by the commented-out line right above
+    // it) crashed outright instead of being silently ignored the way real
+    // jQuery would have.
+    function _normalizeAppendable(args) {
+        var out = [];
+        function add(item) {
+            if (item == null) return;
+            if (Array.isArray(item)) { item.forEach(add); return; }
+            if (item instanceof $) { for (var i = 0; i < item.length; i++) add(item[i]); return; }
+            if (typeof item === 'string') {
+                var tpl = document.createElement('template');
+                tpl.innerHTML = item;
+                while (tpl.content.firstChild) out.push(tpl.content.removeChild(tpl.content.firstChild));
+                return;
+            }
+            if (item instanceof Node) { out.push(item); return; }
+        }
+        for (var i = 0; i < args.length; i++) add(args[i]);
+        return out;
+    }
+    $.fn.append = function () {
+        if (arguments.length === 1 && typeof arguments[0] === 'string') {
+            var html = arguments[0];
+            return this.each(function () { this.insertAdjacentHTML('beforeend', html); });
+        }
+        var nodes = _normalizeAppendable(arguments);
+        return this.each(function () {
+            var self = this;
+            nodes.forEach(function (n) { self.appendChild(n); });
+        });
+    };
+    $.fn.prepend = function () {
+        if (arguments.length === 1 && typeof arguments[0] === 'string') {
+            var html = arguments[0];
+            return this.each(function () { this.insertAdjacentHTML('afterbegin', html); });
+        }
+        var nodes = _normalizeAppendable(arguments);
+        return this.each(function () {
+            var self = this;
+            var ref = self.firstChild;
+            nodes.forEach(function (n) { self.insertBefore(n, ref); });
+        });
+    };
+    $.fn.after = function (content) {
+        return this.each(function () {
+            if (typeof content === 'string') this.insertAdjacentHTML('afterend', content);
+            else this.parentNode.insertBefore(content instanceof $ ? content[0] : content, this.nextSibling);
+        });
+    };
+    $.fn.appendTo = function (target) { $(target).append(this); return this; };
+    // Real layout metrics (jsdom has no rendering engine, so these will
+    // read 0 here — harmless for anything that isn't actually testing
+    // pixel measurements, which nothing in this codebase's core does).
+    $.fn.width = function () { return this[0] ? this[0].offsetWidth : 0; };
+    $.fn.height = function () { return this[0] ? this[0].offsetHeight : 0; };
+    $.fn.outerWidth = function (includeMargin) {
+        if (!this[0]) return 0;
+        var w = this[0].offsetWidth;
+        if (includeMargin) {
+            var s = getComputedStyle(this[0]);
+            w += parseFloat(s.marginLeft || 0) + parseFloat(s.marginRight || 0);
+        }
+        return w;
+    };
+    $.fn.outerHeight = function (includeMargin) {
+        if (!this[0]) return 0;
+        var h = this[0].offsetHeight;
+        if (includeMargin) {
+            var s = getComputedStyle(this[0]);
+            h += parseFloat(s.marginTop || 0) + parseFloat(s.marginBottom || 0);
+        }
+        return h;
+    };
+    $.fn.parent = function () { return $(this[0] ? this[0].parentElement : null); };
+    $.fn.next = function () { return $(this[0] ? this[0].nextElementSibling : null); };
+    $.fn.closest = function (sel) { return $(this[0] ? this[0].closest(sel) : null); };
+    $.fn.ready = function (fn) {
+        if (document.readyState !== 'loading') fn($);
+        else document.addEventListener('DOMContentLoaded', function () { fn($); });
+        return this;
+    };
+    // jQuery's full family of global ajax events — all just named events on
+    // document under the hood, registered/fired the same way.
+    ['ajaxStart', 'ajaxStop', 'ajaxSend', 'ajaxSuccess', 'ajaxError', 'ajaxComplete'].forEach(function (name) {
+        $.fn[name] = function (fn) { return this.on(name, fn); };
+    });
+
+    // ---- Events ----
+    // A handful of event names need translating for delegation to actually
+    // work — left as-is, these would silently never fire, exactly the class
+    // of bug point 6 exists to stop happening. `touch` isn't a real DOM
+    // event name at all. `focus`/`blur` are real, but don't bubble, so
+    // delegating them from `document`/`body` (lstnrs.js's whole pattern)
+    // requires their bubbling equivalents instead — this is what real
+    // jQuery does internally for the same reason.
+    var EVENT_NAME_MAP = { touch: 'touchstart', focus: 'focusin', blur: 'focusout' };
+
+    // jQuery lets you `.on()`/`.trigger()` an arbitrary plain object, not
+    // just DOM nodes — real jQuery keeps its own event table for that case.
+    // Needed here: the vendored WebWorker helper wraps itself (`$(this)`)
+    // and uses `.on()`/`.trigger()` purely as a pub/sub bus, never touching
+    // the DOM. Bridge non-Node targets to a real EventTarget instead of
+    // assuming addEventListener always exists.
+    var _eventBuses = typeof WeakMap !== 'undefined' ? new WeakMap() : null;
+    function _isNode(x) {
+        return x === window || x === document || (typeof Node !== 'undefined' && x instanceof Node);
+    }
+    // 2026-09-14, real bug found testing a real project end-to-end: the
+    // same WebWorker helper ALSO does `$(this.getNativeWorker()).on(
+    // "message", ...)` to receive real messages posted FROM the actual
+    // worker thread. A native `Worker` isn't a DOM Node, so `_isNode` was
+    // false and this got routed through the fake WeakMap-bridged
+    // EventTarget below instead of the real Worker instance's own native
+    // event system — meaning real `message` events the browser itself
+    // dispatches on the Worker never reached it, and the worker's
+    // load/start handshake (which is entirely message-driven) silently
+    // stalled forever. Any object that's already a genuine EventTarget
+    // (Worker, WebSocket, XMLHttpRequest, ...) should be used directly,
+    // not bridged.
+    function _isRealEventTarget(x) {
+        return x != null && typeof x.addEventListener === 'function' && typeof x.dispatchEvent === 'function';
+    }
+    function _eventTargetFor(x) {
+        if (_isNode(x) || _isRealEventTarget(x)) return x;
+        if (!_eventBuses.has(x)) _eventBuses.set(x, new EventTarget());
+        return _eventBuses.get(x);
+    }
+
+    // 2026-09-16, real bug found and fixed: lstnrs.js delegates every
+    // @click/@sort/@drag/... binding via `$("body").on(evt, "[\\@name]",
+    // handler)` — 34 call sites, all this exact single-attribute-presence
+    // shape. Native `Element.prototype.closest()` (used below for every
+    // other selector) matches against the browser's real internal
+    // attribute storage, which can never see the `@`-prefixed redirect
+    // described in $.fn.hasAttr's comment above — so a delegated `@`-event
+    // listener could never fire at all, in any environment, real browser
+    // included (confirmed against an actual `lm build` output driven by
+    // real Chrome, not just jsdom). Detect that exact selector shape and
+    // walk up manually using `getAttribute` (patch-aware) instead of
+    // native closest(); every other selector (e.g. lstnrs.js's own
+    // "[up] [browse]") is untouched, still native.
+    var AT_ATTR_SELECTOR = /^\[\\@([\w-]+)\]$/;
+    $.fn.on = function (events, selector, handler) {
+        if (typeof selector === 'function') { handler = selector; selector = null; }
+        var evts = events.split(/\s+/).filter(Boolean);
+        var atMatch = selector && AT_ATTR_SELECTOR.exec(selector);
+        var atAttr = atMatch ? '@' + atMatch[1] : null;
+        return this.each(function () {
+            var node = this;
+            var bus = _eventTargetFor(node);
+            evts.forEach(function (evt) {
+                var real = EVENT_NAME_MAP[evt] || evt;
+                bus.addEventListener(real, function (e) {
+                    if (atAttr) {
+                        var el = e.target;
+                        var match = null;
+                        while (el && el.nodeType === 1) {
+                            if (el.getAttribute(atAttr) != null) { match = el; break; }
+                            el = el.parentElement;
+                        }
+                        if (match && node.contains(match)) handler.call(match, e);
+                    } else if (selector && _isNode(node)) {
+                        var match2 = e.target.closest(selector);
+                        if (match2 && node.contains(match2)) handler.call(match2, e);
+                    } else {
+                        handler.call(node, e);
+                    }
+                });
+            });
+        });
+    };
+    // No .live() — 2026-09-13: confirmed every call site in lstnrs.js was
+    // internal (never part of the app-facing API), and the file already
+    // uses `$("body").on(event, selector, handler)` everywhere else for the
+    // exact same pattern. Migrated all 11 sites to that instead of shimming
+    // a deprecated jQuery API just to keep two spellings of one thing.
+    $.fn.click = function (handler) { return handler ? this.on('click', handler) : this.trigger('click'); };
+    $.fn.keydown = function (handler) { return handler ? this.on('keydown', handler) : this.trigger('keydown'); };
+    $.fn.trigger = function (type, data) {
+        return this.each(function () {
+            var bus = _eventTargetFor(this);
+            var ev;
+            if (type instanceof Event) {
+                // 2026-09-14, real bug found testing a real project end-to-
+                // end: the vendored WebWorker helper (vendor/webworker-
+                // helper.js) builds `$.Event(name)` — a real Event — then
+                // assigns custom properties onto it (e.g. `.worker`) and
+                // triggers with THAT OBJECT, not a name string. The old
+                // code here did `new Event(type, ...)` regardless, so
+                // passing an Event object as `type` got silently coerced
+                // to garbage like "[object Event]" by the native Event
+                // constructor — no error, just an event nothing ever
+                // matched, which is why _csswrk (the scoped-CSS worker,
+                // gating renderView() itself) never got past its
+                // INITIALIZED state: its own start()/load() sequence is
+                // entirely driven by trigger()ing exactly this pattern.
+                // Dispatch the existing Event as-is so its custom
+                // properties survive.
+                ev = type;
+            } else if (type && typeof type === 'object' && typeof type.type === 'string') {
+                ev = new Event(type.type, { bubbles: _isNode(this) });
+                for (var k in type) {
+                    if (k !== 'type' && Object.prototype.hasOwnProperty.call(type, k)) {
+                        try { ev[k] = type[k]; } catch (e) { /* read-only Event own-property, e.g. `target` */ }
+                    }
+                }
+            } else {
+                ev = new Event(type, { bubbles: _isNode(this) });
+            }
+            if (data !== undefined) ev.detail = data;
+            bus.dispatchEvent(ev);
+        });
+    };
+    // Real removal needs the original listener reference, which this shim
+    // doesn't track (LumenJS's own model is delegation-first — see
+    // lumenjs-spec.md §5.6 — so long-lived per-node listeners needing unbind
+    // are already the exception, not the pattern). Kept for API completeness.
+    $.fn.unbind = function () { return this; };
+
+    // jQuery's shorthand event methods (2026-09-14, real gap found testing
+    // a real project's vendor code end-to-end — `$(el).keyup(...)` threw
+    // "not a function", never caught before because nothing had exercised
+    // this vendor code path this far). `.eventname(handler)` binds,
+    // `.eventname()` triggers — matching real jQuery exactly.
+    ["click", "dblclick", "keyup", "keydown", "keypress", "focus", "blur",
+        "change", "submit", "focusin", "focusout", "mouseenter", "mouseleave",
+        "mouseover", "mouseout", "mousedown", "mouseup", "mousemove",
+        "resize", "scroll", "load", "select"].forEach(function (name) {
+            $.fn[name] = function (handler) {
+                return handler ? this.on(name, handler) : this.trigger(name);
+            };
+        });
+    $.fn.hover = function (enter, leave) {
+        this.on('mouseenter', enter);
+        this.on('mouseleave', leave || enter);
+        return this;
+    };
+
+    global.$ = $;
+    global.jQuery = $;
+})(typeof window !== 'undefined' ? window : globalThis);

package/src/index-bootstrap.js

@@ -0,0 +1,47 @@
+// index.js bootstrap (2026-09-14). index.js no longer has a <script> tag
+// in index.html (see packages/cli's scaffold + dev-server middleware); its
+// top-level vars are compiled server-side into _vt.Global.vars (walk.js /
+// _re.js), and this is what actually fetches and runs that compiled code
+// in dev.
+//
+// Placement (see build/bundle.js): concatenated right after the WHOLE
+// vendor/reconnecting-websocket.js file, which is where `Reactor` comes
+// from (index.js's compiled code calls it as its last line) — but also
+// where real index.js scripts commonly reference other framework globals
+// defined much later in that same file (`cookies`, `session`, ...), so
+// running only after `Reactor` specifically isn't enough (tried that
+// first, 2026-09-14 — see git history). That vendor file's own
+// $(document).ready(...) handler, which needs Reactor() to have already
+// run (it reads appSettings.Base), is guarded to retry instead of
+// assuming this file has already run by the time it fires — see
+// `_lumenReadyHandler` in that file's own comment for why that guarantee
+// doesn't actually hold (jQuery's ready() can fire synchronously, at
+// registration time, before this file gets a chance to run).
+//
+// Uses console.log directly, not `cl` — this runs after _re.js's own
+// `var cl = console.log;`, so `cl` would work too, but there's no reason
+// to depend on that when a bare console.log is just as simple.
+if (typeof _beaTn === 'undefined' || !_beaTn) {
+    if (typeof XMLHttpRequest === 'function') {
+        try {
+            var _idxXhr = new XMLHttpRequest();
+            _idxXhr.open('GET', '/index.js', false); // synchronous — see comment above
+            _idxXhr.send(null);
+            if (_idxXhr.status >= 200 && _idxXhr.status < 300) {
+                // Indirect eval (the comma-expression form), not `new
+                // Function`: a `function` executes in its OWN fresh scope,
+                // so a top-level `function greet(){}` inside it would
+                // become a local variable of that wrapper, not a real
+                // global — breaking the documented V1 pattern of calling
+                // index.js-declared functions straight from view markup
+                // (e.g. `onclick="greet()"`, resolved against window).
+                // Indirect eval runs in true global scope instead.
+                (0, eval)(_idxXhr.responseText);
+            } else {
+                console.log('Failed to load index.js: HTTP ' + _idxXhr.status);
+            }
+        } catch (e) {
+            console.log('Failed to load index.js: ', e);
+        }
+    }
+}