bitwrench 2.0.15 → 2.0.16

package/src/bitwrench.js

@@ -2579,6 +2579,391 @@ bw.message = function(target, action, data) {
   return true;
 };
 
+// ===================================================================================
+// bw.clientApply() / bw.clientConnect() — Server-driven UI protocol
+// ===================================================================================
+
+/**
+ * Registry of named functions sent via register messages.
+ * Populated by clientApply({ type: 'register', name, body }).
+ * Invoked by clientApply({ type: 'call', name, args }).
+ * @private
+ */
+bw._clientFunctions = {};
+
+/**
+ * Whether exec messages are allowed. Set by clientConnect opts.allowExec.
+ * Default false — exec messages are rejected unless explicitly opted in.
+ * @private
+ */
+bw._allowExec = false;
+
+/**
+ * Built-in client functions available via call() without registration.
+ * @private
+ */
+bw._builtinClientFunctions = {
+  scrollTo: function(selector) {
+    var el = bw._el(selector);
+    if (el) el.scrollTop = el.scrollHeight;
+  },
+  focus: function(selector) {
+    var el = bw._el(selector);
+    if (el && typeof el.focus === 'function') el.focus();
+  },
+  download: function(filename, content, mimeType) {
+    if (typeof document === 'undefined') return;
+    var blob = new Blob([content], { type: mimeType || 'text/plain' });
+    var a = document.createElement('a');
+    a.href = URL.createObjectURL(blob);
+    a.download = filename;
+    a.click();
+    URL.revokeObjectURL(a.href);
+  },
+  clipboard: function(text) {
+    if (typeof navigator !== 'undefined' && navigator.clipboard) {
+      navigator.clipboard.writeText(text);
+    }
+  },
+  redirect: function(url) {
+    if (typeof window !== 'undefined') window.location.href = url;
+  },
+  log: function() {
+    console.log.apply(console, arguments);
+  }
+};
+
+/**
+ * Parse a bwserve protocol message string, supporting both strict JSON
+ * and r-prefixed relaxed JSON (single-quoted strings, trailing commas).
+ *
+ * The r-prefix format is designed for C/C++ string literals where
+ * double-quote escaping is painful. The parser is a state machine
+ * that walks character by character — not a regex replace.
+ *
+ * Escaping: apostrophes inside single-quoted values must be escaped
+ * with backslash: r{'name':'Barry\'s room'}
+ *
+ * @param {string} str - JSON or r-prefixed relaxed JSON string
+ * @returns {Object} Parsed message object
+ * @throws {SyntaxError} If the string is not valid JSON or relaxed JSON
+ * @category Server
+ */
+bw.clientParse = function(str) {
+  str = (str || '').trim();
+  if (str.charAt(0) !== 'r') return JSON.parse(str);
+  str = str.slice(1);
+
+  var out = [];
+  var i = 0;
+  var len = str.length;
+
+  while (i < len) {
+    var ch = str[i];
+
+    if (ch === "'") {
+      // Single-quoted string → emit as double-quoted
+      out.push('"');
+      i++;
+      while (i < len) {
+        var c = str[i];
+        if (c === '\\' && i + 1 < len) {
+          var next = str[i + 1];
+          if (next === "'") {
+            out.push("'");     // \' in input → ' in output
+          } else {
+            out.push('\\');
+            out.push(next);
+          }
+          i += 2;
+        } else if (c === '"') {
+          out.push('\\"');
+          i++;
+        } else if (c === "'") {
+          break;
+        } else {
+          out.push(c);
+          i++;
+        }
+      }
+      out.push('"');
+      i++; // skip closing '
+
+    } else if (ch === '"') {
+      // Double-quoted string — pass through verbatim
+      out.push(ch);
+      i++;
+      while (i < len) {
+        var c2 = str[i];
+        if (c2 === '\\' && i + 1 < len) {
+          out.push(c2);
+          out.push(str[i + 1]);
+          i += 2;
+        } else {
+          out.push(c2);
+          i++;
+          if (c2 === '"') break;
+        }
+      }
+
+    } else if (ch === ',') {
+      // Trailing comma check: skip comma if next non-whitespace is } or ]
+      var j = i + 1;
+      while (j < len && (str[j] === ' ' || str[j] === '\t' || str[j] === '\n' || str[j] === '\r')) j++;
+      if (j < len && (str[j] === '}' || str[j] === ']')) {
+        i++; // skip trailing comma
+      } else {
+        out.push(ch);
+        i++;
+      }
+
+    } else {
+      out.push(ch);
+      i++;
+    }
+  }
+
+  return JSON.parse(out.join(''));
+};
+
+/**
+ * Apply a bwserve protocol message to the DOM.
+ *
+ * Dispatches one of 9 message types:
+ *   replace  — bw.DOM(target, node)
+ *   append   — target.appendChild(bw.createDOM(node))
+ *   remove   — bw.cleanup(target); target.remove()
+ *   patch    — bw.patch(target, content, attr)
+ *   batch    — iterate ops, call clientApply for each
+ *   message  — bw.message(target, action, data)
+ *   register — store a named function for later call()
+ *   call     — invoke a registered or built-in function
+ *   exec     — execute arbitrary JS (requires allowExec)
+ *
+ * Target resolution:
+ *   Starts with '#' or '.' → CSS selector (querySelector)
+ *   Otherwise → getElementById, then bw._el fallback
+ *
+ * @param {Object} msg - Protocol message
+ * @returns {boolean} true if the message was applied successfully
+ * @category Server
+ */
+bw.clientApply = function(msg) {
+  if (!msg || !msg.type) return false;
+
+  var type = msg.type;
+  var target = msg.target;
+
+  if (type === 'replace') {
+    var el = bw._el(target);
+    if (!el) return false;
+    bw.DOM(el, msg.node);
+    return true;
+
+  } else if (type === 'patch') {
+    var patched = bw.patch(target, msg.content, msg.attr);
+    return patched !== null;
+
+  } else if (type === 'append') {
+    var parent = bw._el(target);
+    if (!parent) return false;
+    var child = bw.createDOM(msg.node);
+    parent.appendChild(child);
+    return true;
+
+  } else if (type === 'remove') {
+    var toRemove = bw._el(target);
+    if (!toRemove) return false;
+    if (typeof bw.cleanup === 'function') bw.cleanup(toRemove);
+    toRemove.remove();
+    return true;
+
+  } else if (type === 'batch') {
+    if (!Array.isArray(msg.ops)) return false;
+    var allOk = true;
+    msg.ops.forEach(function(op) {
+      if (!bw.clientApply(op)) allOk = false;
+    });
+    return allOk;
+
+  } else if (type === 'message') {
+    return bw.message(msg.target, msg.action, msg.data);
+
+  } else if (type === 'register') {
+    if (!msg.name || !msg.body) return false;
+    try {
+      bw._clientFunctions[msg.name] = new Function('return ' + msg.body)();
+      return true;
+    } catch (e) {
+      console.error('[bw] register error:', msg.name, e);
+      return false;
+    }
+
+  } else if (type === 'call') {
+    if (!msg.name) return false;
+    var fn = bw._clientFunctions[msg.name] || bw._builtinClientFunctions[msg.name];
+    if (typeof fn !== 'function') return false;
+    try {
+      var args = Array.isArray(msg.args) ? msg.args : [];
+      fn.apply(null, args);
+      return true;
+    } catch (e) {
+      console.error('[bw] call error:', msg.name, e);
+      return false;
+    }
+
+  } else if (type === 'exec') {
+    if (!bw._allowExec) {
+      console.warn('[bw] exec rejected: allowExec is not enabled');
+      return false;
+    }
+    if (!msg.code) return false;
+    try {
+      new Function(msg.code)();
+      return true;
+    } catch (e) {
+      console.error('[bw] exec error:', e);
+      return false;
+    }
+  }
+
+  return false;
+};
+
+/**
+ * Connect to a bwserve SSE endpoint and apply protocol messages automatically.
+ *
+ * Returns a connection object with sendAction(), on(), and close() methods.
+ *
+ * @param {string} url - SSE endpoint URL (e.g., '/__bw/events/client-1')
+ * @param {Object} [opts] - Connection options
+ * @param {string} [opts.transport='sse'] - Transport type: 'sse' (default) or 'poll'
+ * @param {number} [opts.interval=2000] - Poll interval in ms (only for 'poll' transport)
+ * @param {string} [opts.actionUrl] - POST endpoint for actions (default: derived from url)
+ * @param {boolean} [opts.reconnect=true] - Auto-reconnect on disconnect
+ * @param {boolean} [opts.allowExec=false] - Enable exec message type (arbitrary JS execution)
+ * @param {Function} [opts.onStatus] - Status callback: 'connecting'|'connected'|'disconnected'
+ * @param {Function} [opts.onMessage] - Raw message callback (before clientApply)
+ * @returns {Object} Connection object { sendAction, on, close, status }
+ * @category Server
+ */
+bw.clientConnect = function(url, opts) {
+  opts = opts || {};
+  var transport = opts.transport || 'sse';
+  var actionUrl = opts.actionUrl || url.replace(/\/events\//, '/action/');
+  var reconnect = opts.reconnect !== false;
+  var onStatus = opts.onStatus || function() {};
+  var onMessage = opts.onMessage || null;
+  var handlers = {};
+  // Set the global allowExec flag from connection options
+  bw._allowExec = !!opts.allowExec;
+  var conn = {
+    status: 'connecting',
+    _es: null,
+    _pollTimer: null
+  };
+
+  function setStatus(s) {
+    conn.status = s;
+    onStatus(s);
+  }
+
+  function handleMessage(data) {
+    try {
+      var msg = typeof data === 'string' ? bw.clientParse(data) : data;
+      if (onMessage) onMessage(msg);
+      if (handlers.message) handlers.message(msg);
+      bw.clientApply(msg);
+    } catch (e) {
+      if (handlers.error) handlers.error(e);
+    }
+  }
+
+  if (transport === 'sse' && typeof EventSource !== 'undefined') {
+    setStatus('connecting');
+    var es = new EventSource(url);
+    conn._es = es;
+
+    es.onopen = function() {
+      setStatus('connected');
+      if (handlers.open) handlers.open();
+    };
+
+    es.onmessage = function(e) {
+      handleMessage(e.data);
+    };
+
+    es.onerror = function() {
+      if (conn.status === 'connected') {
+        setStatus('disconnected');
+      }
+      if (handlers.error) handlers.error(new Error('SSE connection error'));
+      if (!reconnect) {
+        es.close();
+      }
+      // EventSource auto-reconnects by default when reconnect=true
+    };
+  } else if (transport === 'poll') {
+    var interval = opts.interval || 2000;
+    setStatus('connected');
+    conn._pollTimer = setInterval(function() {
+      fetch(url).then(function(r) { return r.json(); }).then(function(msgs) {
+        if (Array.isArray(msgs)) {
+          msgs.forEach(handleMessage);
+        } else if (msgs && msgs.type) {
+          handleMessage(msgs);
+        }
+      }).catch(function(e) {
+        if (handlers.error) handlers.error(e);
+      });
+    }, interval);
+  }
+
+  /**
+   * Send an action to the server via POST.
+   * @param {string} action - Action name
+   * @param {Object} [data] - Action payload
+   */
+  conn.sendAction = function(action, data) {
+    var body = JSON.stringify({ type: 'action', action: action, data: data || {} });
+    fetch(actionUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: body
+    }).catch(function(e) {
+      if (handlers.error) handlers.error(e);
+    });
+  };
+
+  /**
+   * Register an event handler.
+   * @param {string} event - 'open'|'message'|'error'|'close'
+   * @param {Function} handler
+   */
+  conn.on = function(event, handler) {
+    handlers[event] = handler;
+    return conn;
+  };
+
+  /**
+   * Close the connection.
+   */
+  conn.close = function() {
+    if (conn._es) {
+      conn._es.close();
+      conn._es = null;
+    }
+    if (conn._pollTimer) {
+      clearInterval(conn._pollTimer);
+      conn._pollTimer = null;
+    }
+    setStatus('disconnected');
+    if (handlers.close) handlers.close();
+  };
+
+  return conn;
+};
+
 // ===================================================================================
 // bw.inspect() — Debug utility
 // ===================================================================================

package/src/bwserve/client.js

@@ -0,0 +1,182 @@
+/**
+ * BwServeClient — per-client connection for bwserve.
+ *
+ * Represents one browser tab connected via SSE. The server calls methods
+ * on this object to push UI updates to the client.
+ *
+ * Protocol message types (sent as SSE data):
+ *   { type: 'replace',  target: '#app', node: {t,a,c,o} }
+ *   { type: 'append',   target: '#list', node: {t,a,c,o} }
+ *   { type: 'remove',   target: '#item-3' }
+ *   { type: 'patch',    target: 'bw_counter_abc', content: '42', attr: null }
+ *   { type: 'batch',    ops: [ ...messages ] }
+ *   { type: 'register', name: 'fn', body: 'function(x) { ... }' }
+ *   { type: 'call',     name: 'fn', args: [...] }
+ *   { type: 'exec',     code: 'js code string' }
+ *
+ * @module bwserve/client
+ */
+
+/**
+ * BwServeClient — one connected browser tab.
+ */
+export class BwServeClient {
+    constructor(id, res) {
+        this.id = id;
+        this._res = res;       // SSE response stream (null in stub)
+        this._handlers = {};   // action name → handler
+        this._closed = false;
+    }
+
+    /**
+     * Replace the content of a DOM element with a TACO.
+     *
+     * @param {string} selector - CSS selector or UUID
+     * @param {Object} taco - TACO object to render
+     */
+    render(selector, taco) {
+        this._send({ type: 'replace', target: selector, node: taco });
+    }
+
+    /**
+     * Patch an element's content or attributes without rebuild.
+     *
+     * @param {string} id - Element UUID (from bw.uuid())
+     * @param {string} content - New text content
+     * @param {Object} [attr] - Attributes to update
+     */
+    patch(id, content, attr) {
+        this._send({ type: 'patch', target: id, content, attr: attr || null });
+    }
+
+    /**
+     * Append a TACO as a new child of the target element.
+     *
+     * @param {string} selector - CSS selector of parent
+     * @param {Object} taco - TACO object to append
+     */
+    append(selector, taco) {
+        this._send({ type: 'append', target: selector, node: taco });
+    }
+
+    /**
+     * Remove an element from the DOM (with cleanup).
+     *
+     * @param {string} selector - CSS selector or UUID of element to remove
+     */
+    remove(selector) {
+        this._send({ type: 'remove', target: selector });
+    }
+
+    /**
+     * Send multiple operations as a single batch.
+     *
+     * @param {Array} ops - Array of message objects (replace/append/remove/patch)
+     */
+    batch(ops) {
+        this._send({ type: 'batch', ops });
+    }
+
+    /**
+     * Send a bw.message() dispatch to a tagged component on the client.
+     *
+     * @param {string} target - Component userTag or UUID
+     * @param {string} action - Method name to call
+     * @param {*} data - Data to pass to the method
+     */
+    message(target, action, data) {
+        this._send({ type: 'message', target, action, data });
+    }
+
+    /**
+     * Register a named function on the client for later invocation via call().
+     *
+     * The function body is sent as a string and compiled on the client side.
+     * Registered functions persist for the lifetime of the connection.
+     *
+     * @param {string} name - Function name (used as key for later call())
+     * @param {string} body - Function source as string, e.g. "function(el) { el.scrollTop = el.scrollHeight; }"
+     */
+    register(name, body) {
+        this._send({ type: 'register', name, body });
+    }
+
+    /**
+     * Call a previously registered or built-in function on the client.
+     *
+     * Built-in functions (always available, no registration needed):
+     *   scrollTo, focus, download, clipboard, redirect, log
+     *
+     * @param {string} name - Function name (registered or built-in)
+     * @param {...*} args - Arguments to pass to the function
+     */
+    call(name, ...args) {
+        this._send({ type: 'call', name, args });
+    }
+
+    /**
+     * Execute arbitrary JavaScript code on the client.
+     *
+     * Requires the client connection to be created with { allowExec: true }.
+     * Use call() as the safe alternative when possible.
+     *
+     * @param {string} code - JavaScript code string to execute
+     */
+    exec(code) {
+        this._send({ type: 'exec', code });
+    }
+
+    /**
+     * Register a handler for client actions (button clicks, form submits, etc.).
+     *
+     * @param {string} action - Action name (from o.events declarative handler)
+     * @param {Function} handler - Called with (data, client)
+     * @returns {BwServeClient} this (for chaining)
+     */
+    on(action, handler) {
+        this._handlers[action] = handler;
+        return this;
+    }
+
+    /**
+     * Close the SSE connection to this client.
+     */
+    close() {
+        this._closed = true;
+        if (this._res && typeof this._res.end === 'function') {
+            try { this._res.end(); } catch (e) { /* ignore */ }
+        }
+    }
+
+    /**
+     * Send a protocol message to the client via SSE.
+     * @private
+     */
+    _send(msg) {
+        if (this._closed) return;
+        // Always store for testing / inspection
+        if (!this._sent) this._sent = [];
+        this._sent.push(msg);
+        // Write SSE frame if we have a live response stream
+        if (this._res && typeof this._res.write === 'function') {
+            try {
+                this._res.write('data: ' + JSON.stringify(msg) + '\n\n');
+            } catch (e) {
+                // Stream may have been closed — ignore write errors
+            }
+        }
+    }
+
+    /**
+     * Dispatch an incoming action from the client.
+     * @private
+     */
+    _dispatch(action, data) {
+        const handler = this._handlers[action];
+        if (handler) {
+            handler(data, this);
+            return true;
+        }
+        return false;
+    }
+}