@lmjs/core 1.0.7 → 2.0.2

package/src/dom-shim.js

@@ -0,0 +1,640 @@
+// 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]; };
+    // 2026-09-17, found alongside .find()/.is() (same real bug's radio-
+    // group branch in checkFormInputs()) — excludes elements matching a
+    // raw DOM node, an array of nodes, or a $()-wrapped set; jQuery also
+    // supports a selector string here, not needed by anything in this
+    // codebase's actual usage (grepped), so not implemented.
+    $.fn.not = function (exclude) {
+        var excludeArr = exclude instanceof $ ? toArray(exclude) : (Array.isArray(exclude) ? exclude : [exclude]);
+        var out = [];
+        this.each(function () { if (excludeArr.indexOf(this) === -1) out.push(this); });
+        return $(out);
+    };
+
+    $.fn.attr = function (name, value) {
+        if (value === undefined) return this[0] ? this[0].getAttribute(name) : undefined;
+        return this.each(function () { this.setAttribute(name, value); });
+    };
+    // 2026-09-17, found in the same real-page click test as .find()/.is()/
+    // .not() above — real jQuery distinguishes .prop() (a direct DOM
+    // property, e.g. .checked/.disabled/.scrollHeight) from .attr() (the
+    // HTML attribute string); the two diverge for exactly the boolean
+    // properties this codebase's real usage needs (checkFormInputs()'s
+    // "disabled", the vendored search-widget's "disabled", scroll
+    // measurements) — grepped actual call sites, not guessed.
+    $.fn.prop = function (name, value) {
+        if (value === undefined) return this[0] ? this[0][name] : undefined;
+        return this.each(function () { this[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; });
+    };
+    // 2026-09-17, found alongside .find()/.is()/.not()/.prop() above —
+    // checkFormInputs()'s "data-into" error-message branch calls
+    // into.text(...). Not hit by the specific real page that surfaced
+    // the others (this codebase's checkbox demo has no data-into), added
+    // proactively rather than waiting for a second real crash to find it.
+    $.fn.text = function (value) {
+        if (value === undefined) return this[0] ? this[0].textContent : '';
+        return this.each(function () { this.textContent = 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); };
+    // 2026-09-17, real bug found and fixed: never implemented at all —
+    // vendor/reconnecting-websocket.js's ported V1 form-validation code
+    // (checkFormInputs()) calls f.find(...) on the result of .closest(
+    // "form"), and .closest() legitimately returns an empty $() when
+    // there's no enclosing form (a completely normal case — a single
+    // checkbox/input outside a <form>). With .find() missing, that threw
+    // "f.find is not a function" the moment ANY input/textarea/select
+    // fired a "change" event anywhere on the page, form or no form —
+    // found clicking a plain checkbox on lumenjs.com's own real V2
+    // homepage. Real jQuery .find() semantics: search descendants of
+    // each matched element, union the results (safe/empty on an empty
+    // set, exactly what's needed here).
+    $.fn.find = function (sel) {
+        var out = [];
+        this.each(function () {
+            var found = this.querySelectorAll(sel);
+            for (var i = 0; i < found.length; i++) if (out.indexOf(found[i]) === -1) out.push(found[i]);
+        });
+        return $(out);
+    };
+    // 2026-09-17, found alongside .find() (same crash, next line of the
+    // same real bug): checkFormInputs() also calls el.is(":checkbox")/
+    // ":radio"/":checked" — real CSS pseudo-classes for the former two
+    // don't exist (native .matches(":checkbox") throws a SyntaxError,
+    // it's a jQuery-only pseudo-selector), so a short, explicit table for
+    // the handful actually used across the vendored code (grepped, not
+    // guessed) plus a native .matches() fallback for everything else
+    // (tag names, real attribute selectors like "[dp0]") — safely false
+    // rather than throwing if a selector native matches() can't parse.
+    var JQUERY_PSEUDOS = {
+        ':checkbox': function (el) { return el.tagName === 'INPUT' && el.type === 'checkbox'; },
+        ':radio': function (el) { return el.tagName === 'INPUT' && el.type === 'radio'; },
+        ':checked': function (el) { return !!el.checked; },
+    };
+    $.fn.is = function (sel) {
+        if (!this[0]) return false;
+        if (JQUERY_PSEUDOS[sel]) return JQUERY_PSEUDOS[sel](this[0]);
+        try { return this[0].matches(sel); } catch (e) { return false; }
+    };
+    $.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;
+    };
+
+    // 2026-09-18, real gap found testing a real migrated V1 project end-to-
+    // end: `st()` (vendor/reconnecting-websocket.js's own real, shipped
+    // scroll-to helper — not project code, framework code) does
+    // `$("html,body").stop().animate({scrollTop: x}, {duration: 400})` —
+    // a very common pattern across real V1 pages (called at the top of
+    // most real view scripts for smooth-scroll navigation). Neither
+    // method existed in the shim at all, throwing "not a function" and
+    // aborting the rest of that script on every real page that called it.
+    // `scrollTop`/`scrollLeft` are DOM properties, not CSS ones — handled
+    // as a special case, matching real jQuery's own animate() behavior;
+    // any other property is treated as a numeric CSS property (adding
+    // "px" unless it's already a bare number-only string/value, matching
+    // jQuery's own unit-inference for a plain number).
+    var _animTimers = new WeakMap();
+    function _animGetScroll(el, prop) {
+        if (el === window) return prop === 'scrollLeft' ? window.pageXOffset : window.pageYOffset;
+        return el[prop];
+    }
+    function _animSetScroll(el, prop, val) {
+        if (el === window) {
+            if (prop === 'scrollLeft') window.scrollTo(val, window.pageYOffset);
+            else window.scrollTo(window.pageXOffset, val);
+        } else {
+            el[prop] = val;
+        }
+    }
+    // Real jQuery's own cssNumber list — these CSS properties take a bare
+    // unitless number, not "Npx" (opacity: "0.5px" is simply invalid and
+    // silently ignored by the browser, which is exactly what broke the
+    // very first real-content test of this: an opacity fade never moved).
+    var _cssNumberProps = { opacity: 1, zIndex: 1, zoom: 1, fontWeight: 1, lineHeight: 1, columnCount: 1, flexGrow: 1, flexShrink: 1, order: 1, widows: 1, orphans: 1 };
+    function _animSetStyle(el, prop, val) {
+        el.style[prop] = _cssNumberProps[prop] ? val : (val + 'px');
+    }
+    $.fn.animate = function (props, options) {
+        var opts = typeof options === 'number' ? { duration: options } : (options || {});
+        var duration = opts.duration == null ? 400 : opts.duration;
+        this.each(function () {
+            var el = this;
+            var isWindowScroll = (el === document.documentElement || el === document.body);
+            var target = isWindowScroll ? window : el;
+            var start = {};
+            var isScrollProp = {};
+            for (var prop in props) {
+                if (!Object.prototype.hasOwnProperty.call(props, prop)) continue;
+                isScrollProp[prop] = (prop === 'scrollTop' || prop === 'scrollLeft');
+                if (isScrollProp[prop]) {
+                    start[prop] = _animGetScroll(isWindowScroll ? window : el, prop);
+                } else {
+                    start[prop] = parseFloat(getComputedStyle(el)[prop]) || 0;
+                }
+            }
+            var existing = _animTimers.get(el);
+            if (existing) cancelAnimationFrame(existing);
+            if (duration === 0) {
+                for (var p in props) {
+                    var v = parseFloat(props[p]);
+                    if (isScrollProp[p]) _animSetScroll(isWindowScroll ? window : el, p, v);
+                    else _animSetStyle(el, p, v);
+                }
+                if (opts.complete) opts.complete.call(el);
+                return;
+            }
+            var startTime = null;
+            function step(ts) {
+                if (startTime === null) startTime = ts;
+                var elapsed = ts - startTime;
+                var t = Math.min(1, elapsed / duration);
+                for (var p in props) {
+                    if (!Object.prototype.hasOwnProperty.call(props, p)) continue;
+                    var end = parseFloat(props[p]);
+                    var val = start[p] + (end - start[p]) * t;
+                    if (isScrollProp[p]) _animSetScroll(isWindowScroll ? window : el, p, val);
+                    else _animSetStyle(el, p, val);
+                }
+                if (t < 1) {
+                    _animTimers.set(el, requestAnimationFrame(step));
+                } else {
+                    _animTimers.delete(el);
+                    if (opts.complete) opts.complete.call(el);
+                }
+            }
+            _animTimers.set(el, requestAnimationFrame(step));
+        });
+        return this;
+    };
+    $.fn.stop = function () {
+        this.each(function () {
+            var id = _animTimers.get(this);
+            if (id) {
+                cancelAnimationFrame(id);
+                _animTimers.delete(this);
+            }
+        });
+        return this;
+    };
+
+    global.$ = $;
+    global.jQuery = $;
+})(typeof window !== 'undefined' ? window : globalThis);