bitwrench 2.0.25 → 2.0.31

package/src/bwserve/bwclient.js

@@ -86,8 +86,8 @@ var BWCLIENT_SOURCE = '(function(bw) {\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'
+  + '      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'
@@ -95,7 +95,7 @@ var BWCLIENT_SOURCE = '(function(bw) {\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_tree: "function(opts){if(!bw._bwClient)return;var sel=opts.selector||\\"body\\";var depth=opts.depth||3;var root=document.querySelector(sel);if(typeof bw.inspect===\\"function\\"&&bw.inspect.length===2){bw._bwClient.respond(\\"query\\",opts.requestId,bw.inspect(root,depth));return;}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;}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'

package/src/bwserve/client.js

@@ -263,6 +263,32 @@ export class BwServeClient {
         return pend.promise;
     }
 
+    // ── Inspect ──
+
+    /**
+     * Inspect the DOM tree of the connected client.
+     *
+     * Calls the `_bw_tree` builtin on the client which delegates to
+     * `bw.inspect()` when available, returning a plain-object tree with
+     * bitwrench metadata (tag, uuid, type, handles, state, children).
+     *
+     * @param {string} [selector='body'] - CSS selector of root element
+     * @param {Object} [options]
+     * @param {number} [options.depth=3] - Max recursion depth
+     * @param {number} [options.timeout=10000] - Timeout in ms
+     * @returns {Promise<Object|null>} Tree object, or null if element not found
+     */
+    inspect(selector, options) {
+        var opts = options || {};
+        var pend = this._pend(opts.timeout || 10000);
+        this.call('_bw_tree', {
+            selector: selector || 'body',
+            depth: opts.depth || 3,
+            requestId: pend.requestId
+        });
+        return pend.promise;
+    }
+
     // ── Screenshot ──
 
     /**

package/src/bwserve/index.js

@@ -25,7 +25,7 @@ import { VERSION } from '../version.js';
 import { fileURLToPath } from 'url';
 import { dirname, resolve, join, extname } from 'path';
 import { createServer } from 'http';
-import { readFileSync, existsSync, statSync } from 'fs';
+import { readFileSync, readdirSync, existsSync, statSync } from 'fs';
 
 var __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -54,7 +54,21 @@ var MIME_TYPES = {
   '.woff': 'font/woff',
   '.woff2': 'font/woff2',
   '.ttf':  'font/ttf',
-  '.map':  'application/json'
+  '.map':  'application/json',
+  '.txt':  'text/plain; charset=utf-8',
+  '.xml':  'application/xml; charset=utf-8',
+  '.pdf':  'application/pdf',
+  '.zip':  'application/zip',
+  '.gz':   'application/gzip',
+  '.mp3':  'audio/mpeg',
+  '.mp4':  'video/mp4',
+  '.webm': 'video/webm',
+  '.webp': 'image/webp',
+  '.avif': 'image/avif',
+  '.wasm': 'application/wasm',
+  '.csv':  'text/csv; charset=utf-8',
+  '.md':   'text/markdown; charset=utf-8',
+  '.mjs':  'application/javascript; charset=utf-8'
 };
 
 /**
@@ -67,6 +81,8 @@ var MIME_TYPES = {
  * @param {boolean} [opts.injectBitwrench=true] - Auto-inject bitwrench client JS
  * @param {string|Object} [opts.theme] - Theme preset name or config object
  * @param {boolean} [opts.allowScreenshot=false] - Enable client.screenshot() capability
+ * @param {boolean} [opts.dirList=true] - Enable directory listings when no index.html
+ * @param {string} [opts.host='0.0.0.0'] - Host/address to bind to
  * @returns {BwServeApp} Application instance
  */
 export function create(opts) {
@@ -87,6 +103,8 @@ class BwServeApp {
     this.theme = opts.theme || null;
     this.allowExec = opts.allowExec || false;
     this.allowScreenshot = opts.allowScreenshot || false;
+    this.dirList = opts.dirList !== false;
+    this.host = opts.host || '0.0.0.0';
     this.keepAliveInterval = opts.keepAliveInterval || 15000;
     this._pages = new Map();
     this._clients = new Map();
@@ -120,7 +138,7 @@ class BwServeApp {
         self._handleRequest(req, rawRes);
       });
 
-      self._server.listen(self.port, function() {
+      self._server.listen(self.port, self.host, function() {
         if (callback) callback();
         res();
       });
@@ -284,6 +302,32 @@ class BwServeApp {
         res.end(content);
         return;
       }
+      // Directory index resolution: /foo/ => /foo/index.html
+      if (path.endsWith('/')) {
+        var indexPath = join(this.staticDir, path, 'index.html');
+        if (existsSync(indexPath) && statSync(indexPath).isFile()) {
+          var indexContent = readFileSync(indexPath);
+          res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+          res.end(indexContent);
+          return;
+        }
+        // Directory listing when no index.html
+        var dirPath = join(this.staticDir, path);
+        if (this.dirList && existsSync(dirPath) && statSync(dirPath).isDirectory()) {
+          var listing = this._generateDirListing(path, dirPath);
+          res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+          res.end(listing);
+          return;
+        }
+      }
+      // Bare directory without trailing slash: /foo => 301 to /foo/
+      if (!path.endsWith('/') && existsSync(filePath) && statSync(filePath).isDirectory()) {
+        var qs = url.split('?')[1];
+        var location = path + '/' + (qs ? '?' + qs : '');
+        res.writeHead(301, { 'Location': location });
+        res.end();
+        return;
+      }
     }
 
     // 404
@@ -453,6 +497,69 @@ class BwServeApp {
     });
     res.end(content);
   }
+
+  /**
+   * Generate an HTML directory listing page.
+   * @private
+   * @param {string} urlPath - URL path (with trailing slash)
+   * @param {string} dirPath - Filesystem path to the directory
+   * @returns {string} HTML page
+   */
+  _generateDirListing(urlPath, dirPath) {
+    var entries = readdirSync(dirPath);
+    var dirs = [];
+    var files = [];
+
+    for (var i = 0; i < entries.length; i++) {
+      var name = entries[i];
+      var fullPath = join(dirPath, name);
+      try {
+        var st = statSync(fullPath);
+        if (st.isDirectory()) {
+          dirs.push({ name: name + '/', size: '-' });
+        } else {
+          files.push({ name: name, size: _formatSize(st.size) });
+        }
+      } catch (e) {
+        // Skip entries we cannot stat
+      }
+    }
+
+    // Sort alphabetically
+    dirs.sort(function(a, b) { return a.name.localeCompare(b.name); });
+    files.sort(function(a, b) { return a.name.localeCompare(b.name); });
+
+    var all = dirs.concat(files);
+
+    var rows = '';
+    // Parent directory link (unless at root)
+    if (urlPath !== '/') {
+      rows += '<tr><td><a href="../">..</a></td><td>-</td></tr>\n';
+    }
+    for (var j = 0; j < all.length; j++) {
+      var entry = all[j];
+      var escaped = entry.name.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+      rows += '<tr><td><a href="' + encodeURIComponent(entry.name.replace(/\/$/, '')) + (entry.size === '-' ? '/' : '') + '">' + escaped + '</a></td><td>' + entry.size + '</td></tr>\n';
+    }
+
+    var escapedPath = urlPath.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+    return '<!DOCTYPE html>\n<html><head><meta charset="utf-8"><title>Index of ' + escapedPath + '</title>' +
+      '<style>body{font-family:monospace;margin:2em}table{border-collapse:collapse}td,th{text-align:left;padding:4px 16px}a{text-decoration:none}a:hover{text-decoration:underline}</style>' +
+      '</head><body><h1>Index of ' + escapedPath + '</h1><table><tr><th>Name</th><th>Size</th></tr>\n' +
+      rows + '</table></body></html>';
+  }
+}
+
+/**
+ * Format a byte size as a human-readable string.
+ * @param {number} bytes
+ * @returns {string}
+ */
+function _formatSize(bytes) {
+  if (bytes < 1024) return bytes + ' B';
+  if (bytes < 1024 * 1024) return (bytes / 1024).toFixed(1) + ' KB';
+  if (bytes < 1024 * 1024 * 1024) return (bytes / (1024 * 1024)).toFixed(1) + ' MB';
+  return (bytes / (1024 * 1024 * 1024)).toFixed(1) + ' GB';
 }
 
 export var version = VERSION;

package/src/cli/attach.js

@@ -47,7 +47,7 @@ REPL Commands:
   <expression>               Evaluate JS in the connected browser (e.g., document.title)
   /help                      Show command reference
   /quit, /q                  Exit
-  /tree [selector] [depth]   Show DOM tree summary (default: body, depth 3)
+  /inspect [selector] [depth] Show DOM tree summary (default: body, depth 3)
   /screenshot [sel] [file]   Capture screenshot (requires --allow-screenshot)
   /mount <sel> <comp> [json] Mount a BCCL component on the client
   /render <sel> <taco-json>  Render a TACO object at selector
@@ -66,7 +66,7 @@ Examples:
   # In the REPL:
   bw> document.title
   bw> bw.$('.bw-card').length
-  bw> /tree #app 2
+  bw> /inspect #app 2
   bw> /screenshot body page.png
   bw> /listen .bw-btn click
   bw> /mount #app card {"title":"Hello","content":"World"}
@@ -76,7 +76,7 @@ Examples:
   bw> /patch users "Users: 342"
   bw> /patch orders "Orders: 28"
   bw> /mount #app card {"title":"Status","content":"All systems go"}
-  bw> /tree #app 2
+  bw> /inspect #app 2
   bw> /listen .bw-btn click
 `.trim();
 
@@ -342,7 +342,8 @@ export function handleSlashCommand(line, activeClient, clients, opts, rl) {
       rl.prompt();
       break;
 
-    case '/tree':
+    case '/inspect':
+    case '/tree':  // alias kept for muscle memory
       if (!activeClient) {
         console.log('No client connected.');
         rl.prompt();
@@ -563,7 +564,8 @@ export function printHelp() {
     '  /help, /h                  Show this help',
     '  /quit, /q                  Exit',
     '',
-    '  /tree [sel] [depth]        Show DOM tree (default: body, depth 3)',
+    '  /inspect [sel] [depth]     Show DOM tree (default: body, depth 3)',
+    '  /tree [sel] [depth]        Alias for /inspect',
     '  /screenshot [sel] [file]   Capture screenshot to PNG file',
     '                             Requires --allow-screenshot flag',
     '  /mount <sel> <comp> [json] Mount a BCCL component',

package/src/cli/serve.js

@@ -30,10 +30,12 @@ Arguments:
 Options:
   -p, --port <number>        Browser-facing web port (default: 8080)
   -l, --listen <number>      Input port for protocol messages (default: 9000)
+  -b, --bind <address>       Host/address to bind to (default: 0.0.0.0)
       --stdin                Read protocol messages from stdin (newline-delimited JSON)
   -t, --theme <name>         Theme preset or hex colors ("#pri,#sec")
       --title <string>       Page title (default: "bwcli serve")
       --allow-exec           Enable exec messages (runs JS in browser, use for dev only)
+      --no-dir-list          Disable directory listings
       --open                 Open browser on start
   -v, --verbose              Verbose output
   -h, --help                 Print this help
@@ -292,10 +294,12 @@ export function runServe(argv, ioOpts) {
             options: {
                 port:    { type: 'string', short: 'p' },
                 listen:  { type: 'string', short: 'l' },
+                bind:    { type: 'string', short: 'b' },
                 stdin:   { type: 'boolean' },
                 theme:   { type: 'string', short: 't' },
                 title:   { type: 'string' },
                 'allow-exec': { type: 'boolean' },
+                'no-dir-list': { type: 'boolean' },
                 open:    { type: 'boolean' },
                 verbose: { type: 'boolean', short: 'v' },
                 help:    { type: 'boolean', short: 'h' }
@@ -317,9 +321,11 @@ export function runServe(argv, ioOpts) {
     var dir = positionals[0] || '.';
     var webPort = values.port ? parseInt(values.port, 10) : 8080;
     var listenPort = values.listen ? parseInt(values.listen, 10) : 9000;
+    var bindAddr = values.bind || '0.0.0.0';
     var useStdin = !!values.stdin;
     var theme = values.theme || null;
     var title = values.title || 'bwcli serve';
+    var dirList = !values['no-dir-list'];
     var verbose = !!values.verbose;
 
     if (isNaN(webPort) || webPort < 1 || webPort > 65535) {
@@ -339,9 +345,11 @@ export function runServe(argv, ioOpts) {
             dir: dir,
             webPort: webPort,
             listenPort: listenPort,
+            bind: bindAddr,
             useStdin: useStdin,
             theme: theme,
             title: title,
+            dirList: dirList,
             verbose: verbose,
             open: !!values.open,
             allowExec: !!values['allow-exec']
@@ -360,9 +368,11 @@ export function runServe(argv, ioOpts) {
 function startServer(bwserve, opts) {
     var app = bwserve.create({
         port: opts.webPort,
+        host: opts.bind,
         title: opts.title,
         static: opts.dir,
         theme: opts.theme,
+        dirList: opts.dirList,
         allowExec: opts.allowExec
     });
 
@@ -381,21 +391,24 @@ function startServer(bwserve, opts) {
     // Start web server
     app.listen(function() {
         console.error('bwcli serve v' + VERSION);
-        console.error('  Web server:  http://localhost:' + opts.webPort);
+        console.error('  Web server:  http://' + (opts.bind === '0.0.0.0' ? 'localhost' : opts.bind) + ':' + opts.webPort);
+        console.error('  Bind:        ' + opts.bind);
         console.error('  Static dir:  ' + opts.dir);
         if (opts.theme) console.error('  Theme:       ' + opts.theme);
+        if (opts.dirList === false) console.error('  Dir listing: disabled');
 
         if (opts.useStdin) {
             console.error('  Input:       stdin (newline-delimited JSON)');
             startStdinReader(app, opts.verbose);
+            console.error('');
+            console.error('Ready. Send protocol messages to push UI to browsers.');
         } else {
-            console.error('  Input port:  http://localhost:' + opts.listenPort);
-            startInputServer(app, opts.listenPort, opts.verbose);
+            startInputServer(app, opts.listenPort, opts.verbose).then(function() {
+                console.error('');
+                console.error('Ready. Send protocol messages to push UI to browsers.');
+            });
         }
 
-        console.error('');
-        console.error('Ready. Send protocol messages to push UI to browsers.');
-
         if (opts.open) {
             import('node:child_process').then(function(cp) {
                 var url = 'http://localhost:' + opts.webPort;
@@ -414,7 +427,40 @@ function startServer(bwserve, opts) {
  * Messages with a `type` field (no `command`) are broadcast to all clients.
  */
 function startInputServer(app, listenPort, verbose) {
-    var inputServer = createServer(function(req, res) {
+    var inputServer = _createInputServer(app, verbose);
+
+    return new Promise(function(resolve) {
+        inputServer.on('error', function(err) {
+            if (err.code === 'EADDRINUSE') {
+                console.error('  Warning: Input port ' + listenPort + ' in use, picking a free port...');
+                var retry = _createInputServer(app, verbose);
+                retry.on('error', function(err2) {
+                    console.error('  Warning: Could not bind input server (' + err2.message + '). Continuing without input port.');
+                    resolve(null);
+                });
+                retry.listen(0, function() {
+                    var actualPort = retry.address().port;
+                    console.error('  Input port:  http://localhost:' + actualPort + ' (fallback)');
+                    resolve(retry);
+                });
+            } else {
+                console.error('  Warning: Input server error (' + err.message + '). Continuing without input port.');
+                resolve(null);
+            }
+        });
+        inputServer.listen(listenPort, function() {
+            console.error('  Input port:  http://localhost:' + listenPort);
+            resolve(inputServer);
+        });
+    });
+}
+
+/**
+ * Create the input HTTP server (without binding).
+ * @private
+ */
+function _createInputServer(app, verbose) {
+    return createServer(function(req, res) {
         if (req.method !== 'POST') {
             res.writeHead(405, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify({ error: 'Use POST' }));
@@ -458,9 +504,6 @@ function startInputServer(app, listenPort, verbose) {
             res.end(JSON.stringify({ ok: true, clients: count }));
         });
     });
-
-    inputServer.listen(listenPort);
-    return inputServer;
 }
 
 /**

package/src/version.js

@@ -3,14 +3,14 @@
  * DO NOT EDIT DIRECTLY - Use npm run generate-version
  */
 
-export const VERSION = '2.0.25';
+export const VERSION = '2.0.31';
 export const VERSION_INFO = {
-  version: '2.0.25',
+  version: '2.0.31',
   name: 'bitwrench',
   description: 'A library for javascript UI functions.',
   license: 'BSD-2-Clause',
   homepage: 'https://deftio.github.com/bitwrench/pages',
   repository: 'git+https://github.com/deftio/bitwrench.git',
   author: 'manu a. chatterjee <deftio@deftio.com> (https://deftio.com/)',
-  buildDate: '2026-03-31T03:03:30.752Z'
+  buildDate: '2026-04-12T07:56:29.791Z'
 };