bhooai-nexus 2.0.13 → 3.0.4

package/packages/nexus-future/src/live/morph.js

@@ -0,0 +1,198 @@
+/**
+ * morph.js — morphdom-lite.
+ *
+ * Diffs two HTML strings / node trees and patches a live DOM element in
+ * place: keyed children (data-key) move instead of rebuild, other children
+ * patch positionally, attributes update individually, text nodes update in
+ * place. Event handler attributes (data-fx*) are preserved — never diffed
+ * away — because the server re-issues fresh ids each render.
+ */
+
+/**
+ * Patch `target` (a live DOM element) to match `html`.
+ * `html` is a full element string (e.g. '<div id="t">…</div>') whose root
+ * should correspond to `target` itself — attributes patch on target,
+ * children morph recursively.
+ * @param {Element} target
+ * @param {string} html
+ */
+export function morph(target, html) {
+  const tpl = target.ownerDocument.createElement('template');
+  tpl.innerHTML = html;
+  const root = tpl.content.firstElementChild;
+  if (!root) return;
+  morphNode(target, root);
+}
+
+/**
+ * Patch the children of `target` to match the children of `source`.
+ * @param {Element | DocumentFragment} target
+ * @param {Element | DocumentFragment} source
+ */
+export function morphChildren(target, source) {
+  const src = [...source.childNodes];
+  const dst = [...target.childNodes];
+
+  // Keyed pass: when both lists carry data-key children, reconcile by key —
+  // existing nodes are morphed in place and moved to their new position;
+  // missing keys are inserted; vanished keys are removed.
+  const srcKeyed = src.filter((n) => n instanceof Element && n.hasAttribute('data-key'));
+  const dstKeyed = dst.filter((n) => n instanceof Element && n.hasAttribute('data-key'));
+  if (srcKeyed.length > 0 && dstKeyed.length > 0) {
+    morphKeyed(target, src, dst);
+    return;
+  }
+
+  let srcIdx = 0;
+  let dstIdx = 0;
+
+  // Positional pass: pair up same-position children.
+  while (dstIdx < dst.length || srcIdx < src.length) {
+    const s = src[srcIdx];
+    const d = dst[dstIdx];
+
+    if (s === undefined && d === undefined) break;
+
+    if (s !== undefined && d !== undefined && sameType(s, d)) {
+      morphNode(/** @type {Node} */ (d), s);
+      srcIdx++;
+      dstIdx++;
+      continue;
+    }
+
+    if (s !== undefined && d === undefined) {
+      target.appendChild(cloneForMorph(s));
+      srcIdx++;
+      continue;
+    }
+    if (s === undefined && d !== undefined) {
+      target.removeChild(/** @type {Node} */ (d));
+      dstIdx++;
+      continue;
+    }
+    // Different types at same position: replace.
+    target.replaceChild(cloneForMorph(s), /** @type {Node} */ (d));
+    srcIdx++;
+    dstIdx++;
+  }
+}
+
+/**
+ * Keyed reconciliation for children lists where (a subset of) children have
+ * data-key attributes. Non-keyed children pair positionally at their spots.
+ * @param {Element | DocumentFragment} target
+ * @param {Node[]} src
+ * @param {Node[]} dst
+ */
+function morphKeyed(target, src, dst) {
+  /** @type {Map<string, Element>} */
+  const dstByKey = new Map();
+  for (const n of dst) {
+    if (n instanceof Element && n.hasAttribute('data-key')) {
+      dstByKey.set(String(n.getAttribute('data-key')), n);
+    }
+  }
+
+  /** @type {Node | null} */
+  let cursor = null; // last placed node
+
+  for (const s of src) {
+    const key = s instanceof Element ? s.getAttribute('data-key') : null;
+    /** @type {Node} */
+    let node;
+    if (key) {
+      const existing = dstByKey.get(String(key));
+      if (existing) {
+        morphNode(existing, s);
+        node = existing;
+        dstByKey.delete(String(key));
+      } else {
+        node = cloneForMorph(s);
+      }
+      // Place at correct position (move if needed).
+      /** @type {Node | null} */
+      const expectedNext = cursor ? cursor.nextSibling : target.firstChild;
+      if (node !== expectedNext) {
+        target.insertBefore(node, /** @type {Node} */ (expectedNext));
+      }
+    } else {
+      // Non-keyed node: append in order after cursor.
+      node = cloneForMorph(s);
+      target.insertBefore(node, cursor ? cursor.nextSibling : null);
+    }
+    cursor = node;
+  }
+
+  // Remove dst leftovers not consumed by key matching.
+  for (const leftover of dstByKey.values()) {
+    if (leftover.parentNode) leftover.parentNode.removeChild(leftover);
+  }
+  // Remove non-keyed destination nodes beyond what source consumed.
+  for (const d of dst) {
+    if (d instanceof Element && d.hasAttribute('data-key')) continue;
+    if (d.parentNode && !src.includes(d) && !([...target.childNodes]).includes(/** @type {ChildNode} */ (d))) {
+      /** @type {ChildNode} */ (d).remove();
+    }
+  }
+}
+
+/**
+ * Do two nodes have compatible types (morphable into each other)?
+ * @param {Node} a — live node
+ * @param {Node} b — incoming node
+ */
+function sameType(a, b) {
+  if (a.nodeType === 3 && b.nodeType === 3) return true; // text
+  if (a.nodeType === 8 && b.nodeType === 8) return true; // comment
+  if (a instanceof Element && b instanceof Element) {
+    return a.tagName === b.tagName;
+  }
+  return false;
+}
+
+/**
+ * Patch live node `a` to match incoming `b`. b stays untouched (owned by the
+ * parsed template); a's children recurse.
+ * @param {Node} a
+ * @param {Node} b
+ */
+function morphNode(a, b) {
+  if (a.nodeType === 3) {
+    const next = String(/** @type {Text} */ (b).data);
+    if (/** @type {Text} */ (a).data !== next) /** @type {Text} */ (a).data = next;
+    return;
+  }
+  if (a.nodeType === 8) {
+    const next = String(/** @type {Comment} */ (b).data);
+    if (/** @type {Comment} */ (a).data !== next) /** @type {Comment} */ (a).data = next;
+    return;
+  }
+  if (!(a instanceof Element) || !(b instanceof Element)) return;
+
+  // Attributes: apply incoming, remove stale (except data-fx* which are
+  // server-issued per-render and replaced wholesale below).
+  /** @type {Set<string>} */
+  const incoming = new Set();
+  for (const attr of b.attributes) {
+    incoming.add(attr.name);
+    if (a.getAttribute(attr.name) !== attr.value) {
+      a.setAttribute(attr.name, attr.value);
+    }
+  }
+  for (const attr of [...a.attributes]) {
+    if (attr.name.startsWith('data-fx')) continue; // managed by handler binding
+    if (!incoming.has(attr.name)) a.removeAttribute(attr.name);
+  }
+
+  morphChildren(a, b);
+}
+
+/**
+ * Clone a template node into a live node. Elements are cloned deeply;
+ * data-fx attributes survive so the delegated listener finds fresh ids.
+ * @param {Node} node
+ * @returns {Node}
+ */
+function cloneForMorph(node) {
+  return node.cloneNode(true);
+}

package/packages/nexus-future/src/live/rpc.js

@@ -0,0 +1,53 @@
+/**
+ * rpc.js — live() RPC protocol.
+ *
+ * Server-side handlers are captured per-render with captureHandlers() and
+ * stored in the LiveServer's session. The browser runtime sends:
+ *
+ *   { t: 'rpc', rid, id, args? }
+ *
+ * over the WS connection; the server invokes the handler, then pushes a
+ * patch (or patch set) produced by re-rendering the live view.
+ *
+ * The rid (render id) routes to the correct handler set: each page render
+ * creates a fresh set, and the browser always sends the rid it last
+ * received, so stale clicks after a re-render fail safely (no-op + warn).
+ */
+
+import { captureHandlers } from '../html/index.js';
+
+/**
+ * Run `render()` with handler capture. Returns the HTML string plus the
+ * captured handler map.
+ * @param {() => import('../html/template.js').HtmlResult} render
+ */
+export function renderWithHandlers(render) {
+  /** @type {Map<string, Function>} */
+  const handlers = new Map();
+  const stop = captureHandlers(/** @type {any} */ (handlers));
+  let html = '';
+  try {
+    html = String(render());
+  } finally {
+    stop();
+  }
+  return { html, handlers };
+}
+
+/**
+ * Invoke a captured handler by id.
+ * @param {Map<string, Function>} handlers
+ * @param {string} id
+ * @param {unknown[]} args
+ * @returns {{ ok: boolean, error?: string }}
+ */
+export function invokeHandler(handlers, id, args) {
+  const fn = handlers.get(id);
+  if (typeof fn !== 'function') return { ok: false, error: `unknown handler ${id}` };
+  try {
+    fn(...(Array.isArray(args) ? args : []));
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}