bitwrench 2.0.17 → 2.0.18

package/src/bwserve/attach.js

@@ -0,0 +1,57 @@
+/**
+ * bwserve attach — self-contained drop-in script generator.
+ *
+ * Generates JS that loads bitwrench + bwclient and auto-connects
+ * to a bwserve instance. When loaded in any browser page, it
+ * establishes an SSE connection for remote debugging.
+ *
+ * Usage:
+ *   <script src="http://localhost:7902/bw/attach.js"></script>
+ *
+ * @module bwserve/attach
+ */
+
+import { getBwClientSource } from './bwclient.js';
+import { VERSION } from '../version.js';
+
+/**
+ * Generate the self-contained attach script.
+ *
+ * The returned JS string, when evaluated in a browser:
+ * 1. Checks if bw is already loaded; if not, injects bitwrench UMD
+ * 2. Evaluates bwclient source to set up bw._bwClient
+ * 3. Calls bw._bwClient.attach() to connect via SSE
+ *
+ * @param {Object} [opts]
+ * @param {string} [opts.origin=''] - Server origin (empty = same origin)
+ * @returns {string} JavaScript source code
+ */
+export function generateAttachScript(opts) {
+  opts = opts || {};
+  var origin = opts.origin || '';
+
+  var clientSource = getBwClientSource();
+
+  return '(function() {\n'
+    + '  "use strict";\n'
+    + '  var origin = ' + JSON.stringify(origin) + ';\n'
+    + '  function _go() {\n'
+    + '    ' + clientSource + '\n'
+    + '    bw._bwClient.attach(origin, {\n'
+    + '      allowExec: true,\n'
+    + '      onStatus: function(s) { console.log("[bw-attach] " + s); }\n'
+    + '    });\n'
+    + '    console.log("[bw-attach] v' + VERSION + ' connecting to " + (origin || location.origin));\n'
+    + '  }\n'
+    + '  if (window.bw) { _go(); return; }\n'
+    + '  var s = document.createElement("script");\n'
+    + '  s.src = (origin || "") + "/bw/lib/bitwrench.umd.js";\n'
+    + '  s.onload = function() {\n'
+    + '    if (typeof bw !== "undefined" && bw.loadStyles) bw.loadStyles();\n'
+    + '    _go();\n'
+    + '  };\n'
+    + '  document.head.appendChild(s);\n'
+    + '})();\n';
+}
+
+generateAttachScript.version = VERSION;

package/src/bwserve/bwclient.js

@@ -0,0 +1,141 @@
+/**
+ * bwclient.js — Browser-side protocol client for bwserve.
+ *
+ * Injected inline by bwshell. Requires window.bw (bitwrench loaded first).
+ * NOT bundled into bitwrench dist — this is a bwserve runtime asset.
+ *
+ * Responsibilities:
+ * - SSE connection lifecycle (connect, reconnect, status)
+ * - Unified POST-back via /bw/return/<route>/<clientId>
+ * - Register built-in client functions (scrollTo, focus, etc.)
+ * - data-bw-action click/key delegation
+ * - Attach mode for remote-controlling any bitwrench page
+ *
+ * @module bwserve/bwclient
+ */
+
+import { VERSION } from '../version.js';
+
+/**
+ * Return the bwclient source as a string for inline injection into the shell.
+ * The version is embedded at serve-time from package.json via version.js.
+ * @returns {string} JavaScript source code
+ */
+export function getBwClientSource() {
+  return BWCLIENT_SOURCE.replace('__BW_VERSION__', VERSION);
+}
+
+var BWCLIENT_SOURCE = '(function(bw) {\n'
+  + '  "use strict";\n'
+  + '  if (!bw) return;\n'
+  + '\n'
+  + '  var _client = {\n'
+  + '    id: null,\n'
+  + '    version: "__BW_VERSION__",\n'
+  + '    status: "idle",\n'
+  + '    _es: null\n'
+  + '  };\n'
+  + '\n'
+  + '  // ── Unified POST-back ──\n'
+  + '  _client.respond = function(route, requestId, result, error) {\n'
+  + '    fetch("/bw/return/" + route + "/" + _client.id, {\n'
+  + '      method: "POST",\n'
+  + '      headers: { "Content-Type": "application/json" },\n'
+  + '      body: JSON.stringify({ requestId: requestId, route: route, result: result, error: error || null })\n'
+  + '    }).catch(function() {});\n'
+  + '  };\n'
+  + '\n'
+  + '  // ── SSE connect ──\n'
+  + '  _client.connect = function(url, opts) {\n'
+  + '    opts = opts || {};\n'
+  + '    var onStatus = opts.onStatus || function() {};\n'
+  + '    function setStatus(s) { _client.status = s; onStatus(s); }\n'
+  + '    setStatus("connecting");\n'
+  + '    if (typeof EventSource === "undefined") return;\n'
+  + '    var es = new EventSource(url);\n'
+  + '    _client._es = es;\n'
+  + '    es.onopen = function() { setStatus("connected"); };\n'
+  + '    es.onmessage = function(e) {\n'
+  + '      try {\n'
+  + '        var msg = typeof e.data === "string" ? bw.parseJSONFlex(e.data) : e.data;\n'
+  + '        bw.apply(msg);\n'
+  + '      } catch (err) {\n'
+  + '        if (typeof console !== "undefined") console.error("[bwclient]", err);\n'
+  + '      }\n'
+  + '    };\n'
+  + '    es.onerror = function() {\n'
+  + '      if (_client.status === "connected") setStatus("disconnected");\n'
+  + '    };\n'
+  + '  };\n'
+  + '\n'
+  + '  // ── Attach mode ──\n'
+  + '  _client.attach = function(url, opts) {\n'
+  + '    opts = opts || {};\n'
+  + '    _client.id = opts.clientId || "att_" + Math.random().toString(36).slice(2, 10);\n'
+  + '    if (opts.allowExec) bw._allowExec = true;\n'
+  + '    _client._registerBuiltins();\n'
+  + '    _client._wireActions();\n'
+  + '    _client.connect(url + "/bw/events/" + _client.id, opts);\n'
+  + '  };\n'
+  + '\n'
+  + '  // ── Send action to server ──\n'
+  + '  _client.sendAction = function(action, data) {\n'
+  + '    _client.respond("action", null, { action: action, data: data || {} });\n'
+  + '  };\n'
+  + '\n'
+  + '  // ── Register built-in functions ──\n'
+  + '  _client._registerBuiltins = function() {\n'
+  + '    var builtins = {\n'
+  + '      scrollTo: "function(sel){var el=bw._el(sel);if(el)el.scrollTop=el.scrollHeight;}",\n'
+  + '      focus: "function(sel){var el=bw._el(sel);if(el&&typeof el.focus===\\"function\\")el.focus();}",\n'
+  + '      download: "function(fn,c,m){if(typeof document===\\"undefined\\")return;var b=new Blob([c],{type:m||\\"text/plain\\"});var a=document.createElement(\\"a\\");a.href=URL.createObjectURL(b);a.download=fn;a.click();URL.revokeObjectURL(a.href);}",\n'
+  + '      clipboard: "function(t){if(typeof navigator!==\\"undefined\\"&&navigator.clipboard)navigator.clipboard.writeText(t);}",\n'
+  + '      redirect: "function(u){if(typeof window!==\\"undefined\\")window.location.href=u;}",\n'
+  + '      log: "function(){console.log.apply(console,arguments);}",\n'
+  + '      _bw_query: "function(opts){if(!bw._bwClient)return;try{var r=new Function(opts.code)();if(r&&typeof r.then===\\"function\\"){r.then(function(v){bw._bwClient.respond(\\"query\\",opts.requestId,v);}).catch(function(e){bw._bwClient.respond(\\"query\\",opts.requestId,null,e.message);});}else{bw._bwClient.respond(\\"query\\",opts.requestId,r);}}catch(e){bw._bwClient.respond(\\"query\\",opts.requestId,null,e.message);}}",\n'
+  + '      _bw_mount: "function(opts){if(!bw._bwClient)return;try{var taco;var f=opts.factory;var n=f.replace(/-([a-z])/g,function(_,c){return c.toUpperCase();});if(bw.BCCL&&bw.BCCL[n]){taco=bw.make(n,opts.props||{});}else if(bw._allowExec){taco=new Function(\\"props\\",f)(opts.props||{});}else{throw new Error(\\"Unknown component and allowExec disabled\\");}bw.DOM(opts.target,taco);bw._bwClient.respond(\\"mount\\",opts.requestId,{mounted:true});}catch(e){bw._bwClient.respond(\\"mount\\",opts.requestId,null,e.message);}}",\n'
+  + '      _bw_screenshot: "function(opts){if(!bw._bwClient)return;var sel=opts.selector||\\"body\\";var el=document.querySelector(sel);if(!el){bw._bwClient.respond(\\"screenshot\\",opts.requestId,null,\\"Element not found: \\"+sel);return;}function _ls(url){return new Promise(function(res,rej){var s=document.createElement(\\"script\\");s.src=url;s.onload=function(){res(window.html2canvas);};s.onerror=function(){rej(new Error(\\"Failed to load html2canvas\\"));};document.head.appendChild(s);});}var p=window.html2canvas?Promise.resolve(window.html2canvas):_ls(opts.captureUrl||\\"/bw/lib/vendor/html2canvas.min.js\\");p.then(function(h2c){return h2c(el,{scale:opts.scale||1,useCORS:true});}).then(function(canvas){var out=canvas;var mw=opts.maxWidth;var mh=opts.maxHeight;if((mw&&canvas.width>mw)||(mh&&canvas.height>mh)){var sw=mw?mw/canvas.width:1;var sh=mh?mh/canvas.height:1;var sc=Math.min(sw,sh);out=document.createElement(\\"canvas\\");out.width=Math.round(canvas.width*sc);out.height=Math.round(canvas.height*sc);out.getContext(\\"2d\\").drawImage(canvas,0,0,out.width,out.height);}var fmt=opts.format===\\"jpeg\\"?\\"image/jpeg\\":\\"image/png\\";var q=opts.format===\\"jpeg\\"?(opts.quality||0.85):undefined;var dataUrl=out.toDataURL(fmt,q);bw._bwClient.respond(\\"screenshot\\",opts.requestId,{data:dataUrl,width:out.width,height:out.height,format:opts.format||\\"png\\"});}).catch(function(err){bw._bwClient.respond(\\"screenshot\\",opts.requestId,null,err.message||String(err));});}",\n'
+  + '      _bw_tree: "function(opts){if(!bw._bwClient)return;var sel=opts.selector||\\"body\\";var depth=opts.depth||3;function walk(el,d){if(!el||d>depth)return null;var info={tag:el.tagName?el.tagName.toLowerCase():\\"#text\\"};if(el.id)info.id=el.id;if(el.className&&typeof el.className===\\"string\\")info.cls=el.className.split(\\" \\").slice(0,5).join(\\" \\");if(el.children&&el.children.length>0&&d<depth){info.children=[];for(var i=0;i<Math.min(el.children.length,20);i++){var c=walk(el.children[i],d+1);if(c)info.children.push(c);}}return info;}var root=document.querySelector(sel);bw._bwClient.respond(\\"query\\",opts.requestId,walk(root,0));}",\n'
+  + '      _bw_listen: "function(opts){if(!bw._bwClient)return;if(!bw._bwClient._listeners)bw._bwClient._listeners={};var key=opts.selector+\\":::\\"+opts.event;if(bw._bwClient._listeners[key])return;var fn=function(e){var el=e.target.closest?e.target.closest(opts.selector):null;if(!el)return;bw._bwClient.respond(\\"event\\",null,{event:opts.event,selector:opts.selector,tagName:el.tagName,id:el.id||null,text:(el.textContent||\\"\\").slice(0,100)});};document.addEventListener(opts.event,fn,true);bw._bwClient._listeners[key]={fn:fn,event:opts.event};}",\n'
+  + '      _bw_unlisten: "function(opts){if(!bw._bwClient||!bw._bwClient._listeners)return;var key=opts.selector+\\":::\\"+opts.event;var entry=bw._bwClient._listeners[key];if(!entry)return;document.removeEventListener(entry.event,entry.fn,true);delete bw._bwClient._listeners[key];}"\n'
+  + '    };\n'
+  + '    Object.keys(builtins).forEach(function(name) {\n'
+  + '      bw.apply({ type: "register", name: name, body: builtins[name] });\n'
+  + '    });\n'
+  + '  };\n'
+  + '\n'
+  + '  // ── Wire up data-bw-action click delegation ──\n'
+  + '  _client._wireActions = function() {\n'
+  + '    document.addEventListener("click", function(e) {\n'
+  + '      var el = e.target.closest ? e.target.closest("[data-bw-action]") : null;\n'
+  + '      if (!el) return;\n'
+  + '      e.preventDefault();\n'
+  + '      var actionData = {};\n'
+  + '      if (el.getAttribute("data-bw-id")) actionData.bwId = el.getAttribute("data-bw-id");\n'
+  + '      var form = el.closest("div") || document;\n'
+  + '      var inp = form.querySelector("input[type=text],input:not([type])");\n'
+  + '      if (inp) { actionData.inputValue = inp.value; inp.value = ""; }\n'
+  + '      _client.sendAction(el.getAttribute("data-bw-action"), actionData);\n'
+  + '    });\n'
+  + '    document.addEventListener("keydown", function(e) {\n'
+  + '      if (e.key === "Enter" && e.target.tagName === "INPUT") {\n'
+  + '        var form = e.target.closest("div") || document;\n'
+  + '        var btn = form.querySelector("[data-bw-action]");\n'
+  + '        if (btn) {\n'
+  + '          _client.sendAction(btn.getAttribute("data-bw-action"), { inputValue: e.target.value });\n'
+  + '          e.target.value = "";\n'
+  + '        }\n'
+  + '      }\n'
+  + '    });\n'
+  + '  };\n'
+  + '\n'
+  + '  // ── Event delegation helper ──\n'
+  + '  _client.listen = function(selector, event, action) {\n'
+  + '    document.addEventListener(event, function(e) {\n'
+  + '      var el = e.target.closest ? e.target.closest(selector) : null;\n'
+  + '      if (el) _client.sendAction(action, { selector: selector, event: event });\n'
+  + '    });\n'
+  + '  };\n'
+  + '\n'
+  + '  bw._bwClient = _client;\n'
+  + '})(window.bw);\n';

package/src/bwserve/bwshell.js

@@ -0,0 +1,102 @@
+/**
+ * bwserve shell — generates the HTML page shell served to browsers.
+ *
+ * The shell is a minimal HTML doc that:
+ * - Loads bitwrench UMD + CSS from /bw/lib/ routes
+ * - Calls bw.loadStyles()
+ * - Optionally applies a custom theme
+ * - Creates a #app div
+ * - Inlines bwclient.js for SSE, action delegation, and built-ins
+ *
+ * @module bwserve/bwshell
+ */
+
+import { getBwClientSource } from './bwclient.js';
+import { VERSION } from '../version.js';
+
+/**
+ * Generate the shell HTML page for a bwserve app.
+ *
+ * @param {Object} opts
+ * @param {string} opts.clientId - Unique client ID for this connection
+ * @param {string} [opts.title='bwserve'] - Page title
+ * @param {string} [opts.theme] - Theme preset name or config
+ * @param {boolean} [opts.injectBitwrench=true] - Whether to inject bitwrench scripts
+ * @param {boolean} [opts.allowExec=false] - Enable exec message type
+ * @returns {string} Complete HTML document
+ */
+export function generateShell(opts) {
+  opts = opts || {};
+  var clientId = opts.clientId || 'default';
+  var title = opts.title || 'bwserve';
+  var inject = opts.injectBitwrench !== false;
+
+  var head = [
+    '<!DOCTYPE html>',
+    '<html lang="en">',
+    '<head>',
+    '<meta charset="UTF-8">',
+    '<meta name="viewport" content="width=device-width, initial-scale=1.0">',
+    '<title>' + title + '</title>',
+    '<meta name="generator" content="bwserve ' + VERSION + '">'
+  ];
+
+  if (inject) {
+    head.push('<script src="/bw/lib/bitwrench.umd.js"></script>');
+    head.push('<link rel="stylesheet" href="/bw/lib/bitwrench.css">');
+  }
+
+  head.push('</head>');
+  head.push('<body>');
+  head.push('<div id="app"></div>');
+
+  var script = [
+    '<script>',
+    '(function() {',
+    '  "use strict";',
+    '  bw.loadStyles();'
+  ];
+
+  if (opts.theme) {
+    script.push('  bw.loadStyles(' + JSON.stringify(
+      typeof opts.theme === 'string'
+        ? { primary: '#006666', secondary: '#333333' }
+        : opts.theme
+    ) + ');');
+  }
+
+  script.push('})();');
+  script.push('</script>');
+
+  // Inline bwclient.js
+  script.push('<script>');
+  script.push(getBwClientSource());
+  script.push('</script>');
+
+  // Init script: wire up bwclient
+  script.push('<script>');
+  script.push('(function() {');
+  script.push('  "use strict";');
+  script.push('  var clientId = ' + JSON.stringify(clientId) + ';');
+  if (opts.allowExec) {
+    script.push('  bw._allowExec = true;');
+  }
+  script.push('  bw._bwClient.id = clientId;');
+  script.push('  bw._bwClient._registerBuiltins();');
+  script.push('  bw._bwClient._wireActions();');
+  script.push('  bw._bwClient.connect("/bw/events/" + clientId, {');
+  script.push('    onStatus: function(s) {');
+  script.push('      if (typeof console !== "undefined") console.log("[bwserve] " + s);');
+  script.push('    }');
+  script.push('  });');
+  script.push('})();');
+  script.push('</script>');
+
+  script.push('</body>');
+  script.push('</html>');
+
+  return head.concat(script).join('\n');
+}
+
+/** bwshell version (from package.json) */
+generateShell.version = VERSION;

package/src/bwserve/client.js

@@ -17,15 +17,20 @@
  * @module bwserve/client
  */
 
+import { VERSION } from '../version.js';
+
 /**
  * BwServeClient — one connected browser tab.
  */
 export class BwServeClient {
+    /** bwserve version (from package.json) */
+    static version = VERSION;
     constructor(id, res) {
         this.id = id;
         this._res = res;       // SSE response stream (null in stub)
         this._handlers = {};   // action name → handler
         this._closed = false;
+        this._pending = {};    // requestId → { resolve, reject, timer }
     }
 
     /**
@@ -104,7 +109,7 @@ export class BwServeClient {
     /**
      * Call a previously registered or built-in function on the client.
      *
-     * Built-in functions (always available, no registration needed):
+     * Built-in functions (registered by bwclient on connection):
      *   scrollTo, focus, download, clipboard, redirect, log
      *
      * @param {string} name - Function name (registered or built-in)
@@ -167,6 +172,151 @@ export class BwServeClient {
         }
     }
 
+    // ── Pending promise mechanism ──
+
+    /**
+     * Create a pending promise with a unique requestId and timeout.
+     *
+     * @param {number} [timeout=10000] - Timeout in ms
+     * @returns {{ requestId: string, promise: Promise }}
+     * @private
+     */
+    _pend(timeout) {
+        var self = this;
+        timeout = timeout || 10000;
+        var requestId = 'req_' + Date.now() + '_' + Math.random().toString(36).slice(2, 8);
+
+        var promise = new Promise(function(resolve, reject) {
+            var timer = setTimeout(function() {
+                delete self._pending[requestId];
+                reject(new Error('Request timeout after ' + timeout + 'ms'));
+            }, timeout);
+
+            self._pending[requestId] = { resolve: resolve, reject: reject, timer: timer };
+        });
+
+        return { requestId: requestId, promise: promise };
+    }
+
+    /**
+     * Resolve a pending promise by requestId.
+     * Called by the server route handler when a POST-back arrives.
+     *
+     * @param {string} requestId
+     * @param {Object} data - Response data (may contain .error)
+     * @returns {boolean} true if a pending request was found and resolved
+     * @private
+     */
+    _resolvePending(requestId, data) {
+        var pending = this._pending[requestId];
+        if (!pending) return false;
+
+        clearTimeout(pending.timer);
+        delete this._pending[requestId];
+
+        if (data.error) {
+            pending.reject(new Error(data.error));
+        } else {
+            pending.resolve(data.result !== undefined ? data.result : data);
+        }
+        return true;
+    }
+
+    // ── Query ──
+
+    /**
+     * Execute code on the client and get the result back.
+     *
+     * @param {string} code - JavaScript code to evaluate (return value is sent back)
+     * @param {Object} [options]
+     * @param {number} [options.timeout=5000] - Timeout in ms
+     * @returns {Promise<*>} The result of evaluating the code
+     */
+    query(code, options) {
+        var opts = options || {};
+        var pend = this._pend(opts.timeout || 5000);
+        this.call('_bw_query', { code: code, requestId: pend.requestId });
+        return pend.promise;
+    }
+
+    // ── Mount ──
+
+    /**
+     * Mount a BCCL component or factory function on the client.
+     *
+     * @param {string} selector - CSS selector of target element
+     * @param {string} factory - BCCL component name (e.g. 'accordion') or JS factory code
+     * @param {Object} [props] - Props to pass to the component/factory
+     * @param {Object} [options]
+     * @param {number} [options.timeout=10000] - Timeout in ms
+     * @returns {Promise<Object>} Resolves with { mounted: true } on success
+     */
+    mount(selector, factory, props, options) {
+        var opts = options || {};
+        var pend = this._pend(opts.timeout || 10000);
+        this.call('_bw_mount', {
+            target: selector,
+            factory: factory,
+            props: props || {},
+            requestId: pend.requestId
+        });
+        return pend.promise;
+    }
+
+    // ── Screenshot ──
+
+    /**
+     * Capture a screenshot of the client's page or a specific element.
+     *
+     * Requires the server to be created with `{ allowScreenshot: true }`.
+     * Uses html2canvas on the client side (lazy-loaded on first call).
+     *
+     * @param {string} [selector='body'] - CSS selector of element to capture
+     * @param {Object} [options]
+     * @param {string} [options.format='png'] - 'png' or 'jpeg'
+     * @param {number} [options.quality=0.85] - JPEG quality 0-1 (ignored for PNG)
+     * @param {number} [options.maxWidth] - Resize if wider (preserves aspect ratio)
+     * @param {number} [options.maxHeight] - Resize if taller (preserves aspect ratio)
+     * @param {number} [options.scale=1] - Device pixel ratio override
+     * @param {number} [options.timeout=10000] - Reject after ms
+     * @returns {Promise<Object>} { data: Buffer, width, height, format }
+     */
+    screenshot(selector, options) {
+        var self = this;
+        var opts = options || {};
+        var timeout = opts.timeout || 10000;
+
+        if (!self._allowScreenshot) {
+            return Promise.reject(new Error('Screenshot not enabled. Set allowScreenshot: true in server options.'));
+        }
+
+        var pend = self._pend(timeout);
+
+        // Call the bwclient-registered capture function
+        self.call('_bw_screenshot', {
+            requestId: pend.requestId,
+            selector: selector || 'body',
+            format: opts.format || 'png',
+            quality: opts.quality || 0.85,
+            maxWidth: opts.maxWidth || null,
+            maxHeight: opts.maxHeight || null,
+            scale: opts.scale || 1,
+            captureUrl: '/bw/lib/vendor/html2canvas.min.js'
+        });
+
+        // Transform the raw response into { data: Buffer, width, height, format }
+        return pend.promise.then(function(result) {
+            if (!result || !result.data) return result;
+            var base64 = result.data.split(',')[1];
+            return {
+                data: Buffer.from(base64, 'base64'),
+                width: result.width,
+                height: result.height,
+                format: result.format
+            };
+        });
+    }
+
     /**
      * Dispatch an incoming action from the client.
      * @private