bitwrench 2.0.31 → 2.1.0

package/src/cli/serve.js

@@ -15,7 +15,6 @@
 
 import { parseArgs } from 'node:util';
 import { createServer } from 'node:http';
-import { createReadStream } from 'node:fs';
 import { VERSION } from '../version.js';
 
 var SERVE_USAGE = `
@@ -34,8 +33,8 @@ Options:
       --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
+      --allow-screenshot     Enable client.screenshot() capability
       --open                 Open browser on start
   -v, --verbose              Verbose output
   -h, --help                 Print this help
@@ -45,8 +44,7 @@ Examples:
   bwcli serve ./public --port 3000        Serve ./public on :3000
   bwcli serve --stdin                     Read from pipe instead of input port
   sensor-reader | bwcli serve --stdin     Pipe sensor data to browser
-  curl -X POST :9000 -d '{"type":"replace","target":"#app","node":{"t":"h1","c":"Hi"}}'
-  curl -X POST :9000 -d '{"command":"query","code":"document.title"}'
+  curl -X POST :9000 -d '{"type":"mount","ref":"#app","taco":{"t":"h1","c":"Hi"},"v":1}'
   curl -X POST :9000 -d '{"command":"clients"}'
 `.trim();
 
@@ -141,20 +139,19 @@ function parseRelaxedJSON(str) {
 
 // Required fields per command (async commands also listed)
 var _COMMAND_REQUIRED = {
-    query:    ['code'],
     screenshot: [],
     tree:     [],
-    mount:    ['selector', 'factory'],
-    exec:     ['code'],
-    render:   ['selector', 'taco'],
-    patch:    ['id'],
-    listen:   ['selector', 'event'],
-    unlisten: ['selector', 'event'],
+    query:    ['code'],
+    mount:    ['ref', 'taco'],
+    render:   ['ref', 'taco'],   // deprecated alias for mount
+    patch:    ['ref'],
+    listen:   ['topic'],
+    unlisten: ['topic'],
     clients:  []
 };
 
 // Commands that return a result via promise
-var _ASYNC_COMMANDS = { query: 1, screenshot: 1, tree: 1, mount: 1 };
+var _ASYNC_COMMANDS = { screenshot: 1, tree: 1, query: 1 };
 
 /**
  * Handle an interactive command from the listen port.
@@ -177,7 +174,7 @@ function handleCommand(msg, app, verbose) {
     }
 
     // Validate command name
-    if (!_COMMAND_REQUIRED.hasOwnProperty(cmd)) {
+    if (!Object.prototype.hasOwnProperty.call(_COMMAND_REQUIRED, cmd)) {
         return Promise.resolve({ error: 'Unknown command: ' + cmd });
     }
 
@@ -202,12 +199,11 @@ function handleCommand(msg, app, verbose) {
             return Promise.resolve({ error: 'Client not found: ' + msg.clientId });
         }
     } else {
-        // Pick first connected client
+        // Pick most recently connected client (last non-closed in insertion order)
         for (var pair of app._clients) {
             if (pair[1] && pair[1].client && !pair[1].client._closed) {
                 client = pair[1].client;
                 clientId = pair[0];
-                break;
             }
         }
     }
@@ -225,11 +221,6 @@ function handleCommand(msg, app, verbose) {
     // Dispatch
     try {
         switch (cmd) {
-            case 'query':
-                return client.query(msg.code, { timeout: timeout || 5000 }).then(function(result) {
-                    return { ok: true, result: result, clientId: clientId };
-                });
-
             case 'screenshot':
                 return client.screenshot(msg.selector || 'body', { timeout: timeout || 10000 }).then(function(result) {
                     // Convert Buffer to base64 for JSON response
@@ -237,6 +228,16 @@ function handleCommand(msg, app, verbose) {
                     return { ok: true, result: { data: data, width: result.width, height: result.height, format: result.format }, clientId: clientId };
                 });
 
+            case 'query':
+                var qPend = client._pend(timeout || 10000);
+                client.call('_bw_query', {
+                    code: msg.code,
+                    requestId: qPend.requestId
+                });
+                return qPend.promise.then(function(result) {
+                    return { ok: true, result: result, clientId: clientId };
+                });
+
             case 'tree':
                 var pend = client._pend(timeout || 10000);
                 client.call('_bw_tree', {
@@ -249,28 +250,26 @@ function handleCommand(msg, app, verbose) {
                 });
 
             case 'mount':
-                return client.mount(msg.selector, msg.factory, msg.props || {}, { timeout: timeout || 10000 }).then(function(result) {
-                    return { ok: true, result: result, clientId: clientId };
-                });
-
-            case 'exec':
-                client.exec(msg.code);
-                return Promise.resolve({ ok: true, clientId: clientId });
-
             case 'render':
-                client.render(msg.selector, msg.taco);
+                client.mount(msg.ref, msg.taco);
                 return Promise.resolve({ ok: true, clientId: clientId });
 
             case 'patch':
-                client.patch(msg.id, msg.content, msg.attr);
+                var patchFields = {};
+                for (var pk in msg) {
+                    if (pk !== 'command' && pk !== 'ref' && pk !== 'clientId' && pk !== 'timeout') {
+                        patchFields[pk] = msg[pk];
+                    }
+                }
+                client.patch(msg.ref, patchFields);
                 return Promise.resolve({ ok: true, clientId: clientId });
 
             case 'listen':
-                client.call('_bw_listen', { selector: msg.selector, event: msg.event });
+                client.listen(msg.topic);
                 return Promise.resolve({ ok: true, clientId: clientId });
 
             case 'unlisten':
-                client.call('_bw_unlisten', { selector: msg.selector, event: msg.event });
+                client._send({ type: 'unlisten', topic: msg.topic });
                 return Promise.resolve({ ok: true, clientId: clientId });
         }
     } catch (err) {
@@ -298,9 +297,9 @@ export function runServe(argv, ioOpts) {
                 stdin:   { type: 'boolean' },
                 theme:   { type: 'string', short: 't' },
                 title:   { type: 'string' },
-                'allow-exec': { type: 'boolean' },
                 'no-dir-list': { type: 'boolean' },
                 open:    { type: 'boolean' },
+                'allow-screenshot': { type: 'boolean' },
                 verbose: { type: 'boolean', short: 'v' },
                 help:    { type: 'boolean', short: 'h' }
             }
@@ -352,7 +351,7 @@ export function runServe(argv, ioOpts) {
             dirList: dirList,
             verbose: verbose,
             open: !!values.open,
-            allowExec: !!values['allow-exec']
+            allowScreenshot: !!values['allow-screenshot']
         });
     }).catch(function(err) {
         console.error('Failed to load bwserve: ' + err.message);
@@ -373,7 +372,7 @@ function startServer(bwserve, opts) {
         static: opts.dir,
         theme: opts.theme,
         dirList: opts.dirList,
-        allowExec: opts.allowExec
+        allowScreenshot: opts.allowScreenshot
     });
 
     // Register a passthrough page handler — just keeps clients alive
@@ -434,6 +433,7 @@ function startInputServer(app, listenPort, verbose) {
             if (err.code === 'EADDRINUSE') {
                 console.error('  Warning: Input port ' + listenPort + ' in use, picking a free port...');
                 var retry = _createInputServer(app, verbose);
+                /* c8 ignore next 5 -- double port failure is a rare edge case */
                 retry.on('error', function(err2) {
                     console.error('  Warning: Could not bind input server (' + err2.message + '). Continuing without input port.');
                     resolve(null);
@@ -443,6 +443,7 @@ function startInputServer(app, listenPort, verbose) {
                     console.error('  Input port:  http://localhost:' + actualPort + ' (fallback)');
                     resolve(retry);
                 });
+            /* c8 ignore next 3 -- non-EADDRINUSE errors are rare */
             } else {
                 console.error('  Warning: Input server error (' + err.message + '). Continuing without input port.');
                 resolve(null);
@@ -480,6 +481,7 @@ function _createInputServer(app, verbose) {
             // Interactive command path
             if (msg.command) {
                 handleCommand(msg, app, verbose).then(function(result) {
+                    /* c8 ignore next -- error status covered in isolation; flaky in combined */
                     var status = result.error ? 400 : 200;
                     // Unknown command and client-not-found get 400; timeout also 400
                     res.writeHead(status, { 'Content-Type': 'application/json' });

package/src/generate-css.js

@@ -3,7 +3,7 @@
  * Creates class-based CSS to prevent collisions with other frameworks
  */
 
-import { getAllStyles, getStructuralStyles, generateThemedCSS,
+import { getStructuralStyles, generateThemedCSS,
          resolveLayout, DEFAULT_PALETTE_CONFIG } from './bitwrench-styles.js';
 import { derivePalette } from './bitwrench-color-utils.js';
 import fs from 'fs';

package/src/mcp/knowledge.js

@@ -17,7 +17,7 @@ var DOCS_DIR = resolve(__dirname, '../../docs');
 // Section name -> heading prefix mapping for bitwrench_guide
 var GUIDE_SECTIONS = {
   'taco':           'Step 2: Understand TACO',
-  'levels':         'Step 3: Three Levels',
+  'materialization': 'Step 3: From Data to DOM',
   'events':         'Step 4: Events',
   'css':            'Step 5: CSS and Theming',
   'components':     'Step 6: BCCL Components',
@@ -102,7 +102,7 @@ export var knowledgeToolDefs = [
         section: {
           type: 'string',
           description: 'Optional: return only a specific section. Omit for full guide.',
-          enum: ['taco', 'levels', 'events', 'css', 'components', 'bwserve', 'routing', 'api-reference', 'rules']
+          enum: ['taco', 'materialization', 'events', 'css', 'components', 'bwserve', 'routing', 'api-reference', 'rules']
         }
       }
     }
@@ -124,7 +124,7 @@ export var knowledgeToolDefs = [
   {
     name: 'bitwrench_server_guide',
     title: 'Server-Driven UI Guide',
-    description: 'Tutorial for building server-driven UI with bwserve. Covers: SSE streaming, replace/patch/append protocol, data-bw-action buttons, live metrics, screenshots. Call this when building real-time or server-pushed interfaces.',
+    description: 'Tutorial for building server-driven UI with bwserve. Covers: SSE streaming, mount/patch/append protocol, bw_act_* action buttons, live metrics, screenshots. Call this when building real-time or server-pushed interfaces.',
     inputSchema: { type: 'object', properties: {} }
   },
   {
@@ -169,7 +169,7 @@ var START_HERE_TEXT = [
   '- Call build_page to get a complete standalone .html file (works offline)',
   '',
   'OTHER KNOWLEDGE TOOLS (call as needed):',
-  '- bitwrench_guide: Full tutorial (TACO format, 3 levels, events, CSS,',
+  '- bitwrench_guide: Full tutorial (TACO format, materialization, events, CSS,',
   '  components, bwserve, routing, API reference)',
   '- bitwrench_components: Props reference for all 47+ make*() components',
   '- bitwrench_server_guide: bwserve tutorial (SSE streaming, live UI)',

package/src/mcp/live.js

@@ -1,5 +1,5 @@
 /**
- * MCP live rendering -- bwserve integration for render_live, screenshot, query_dom.
+ * MCP live rendering -- bwserve integration for render_live, screenshot, inspect_dom.
  *
  * Starts a bwserve instance that serves a shell page. The MCP agent pushes
  * TACO to the browser via SSE, captures screenshots, and queries DOM state.
@@ -34,7 +34,7 @@ export function startLive(opts) {
   // Register the default page handler
   _app.page('/', function(client) {
     // Render an initial placeholder
-    client.render('#app', {
+    client.mount('#app', {
       t: 'div',
       a: { class: 'bw_container', style: 'padding: 2rem; text-align: center; color: #888;' },
       c: { t: 'p', c: 'bwmcp ready -- waiting for agent to render UI...' }
@@ -50,6 +50,7 @@ export function startLive(opts) {
         if (opts.open) {
           import('child_process').then(function(cp) {
             var url = 'http://localhost:' + port;
+            /* c8 ignore next 2 -- platform-dependent; only darwin in CI */
             var cmd = process.platform === 'darwin' ? 'open'
               : process.platform === 'win32' ? 'start' : 'xdg-open';
             cp.exec(cmd + ' ' + url);
@@ -58,6 +59,7 @@ export function startLive(opts) {
 
         resolve(_app);
       });
+    /* c8 ignore next 3 -- defensive catch for synchronous listen errors */
     } catch (e) {
       reject(e);
     }
@@ -129,15 +131,15 @@ export var liveToolDefs = [
     }
   },
   {
-    name: 'query_dom',
-    title: 'Query DOM State',
-    description: 'Execute JavaScript in the browser and return the result. Use this to inspect DOM state, read text content, count elements, etc.',
+    name: 'inspect_dom',
+    title: 'Inspect DOM Tree',
+    description: 'Inspect the DOM tree in the connected browser. Returns a structured tree with tag names, IDs, classes, and children.',
     inputSchema: {
       type: 'object',
       properties: {
-        code: { type: 'string', description: 'JavaScript code to evaluate in the browser. The return value is sent back.' }
-      },
-      required: ['code']
+        selector: { type: 'string', description: 'CSS selector of root element to inspect (default: "body")' },
+        depth: { type: 'number', description: 'Maximum depth to traverse (default: 3)' }
+      }
     }
   }
 ];
@@ -149,7 +151,7 @@ export var liveHandlers = {
     if (!_app) {
       return { content: [{ type: 'text', text: 'Error: bwserve not started. Live rendering not available.' }], isError: true };
     }
-    var client = getClient();
+    getClient();
     var target = args.target || '#app';
     var action = args.action || 'replace';
 
@@ -204,7 +206,7 @@ export var liveHandlers = {
       });
   },
 
-  query_dom: function(args) {
+  inspect_dom: function(args) {
     var client = getClient();
     if (!client) {
       return Promise.resolve({
@@ -213,14 +215,20 @@ export var liveHandlers = {
       });
     }
 
-    return client.query(args.code, { timeout: 5000 })
+    var pend = client._pend(5000);
+    client.call('_bw_tree', {
+      selector: args.selector || 'body',
+      depth: args.depth || 3,
+      requestId: pend.requestId
+    });
+    return pend.promise
       .then(function(result) {
-        var text = typeof result === 'string' ? result : JSON.stringify(result);
+        var text = typeof result === 'string' ? result : JSON.stringify(result, null, 2);
         return { content: [{ type: 'text', text: text }] };
       })
       .catch(function(e) {
         return {
-          content: [{ type: 'text', text: 'Query error: ' + e.message }],
+          content: [{ type: 'text', text: 'Inspect error: ' + e.message }],
           isError: true
         };
       });

package/src/mcp/tools.js

@@ -18,7 +18,6 @@ var BOOL = { type: 'boolean' };
 var OBJ = { type: 'object' };
 var NUM = { type: 'number' };
 var STR_OR_OBJ = { oneOf: [{ type: 'string' }, { type: 'object' }] };
-var STR_OR_ARRAY = { oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'object' } }] };
 var VARIANT_ENUM = {
   type: 'string',
   enum: ['primary', 'secondary', 'success', 'danger', 'warning', 'info'],

package/src/version.js

@@ -3,14 +3,10 @@
  * DO NOT EDIT DIRECTLY - Use npm run generate-version
  */
 
-export const VERSION = '2.0.31';
+export const VERSION = '2.1.0';
 export const VERSION_INFO = {
-  version: '2.0.31',
+  version: '2.1.0',
   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-04-12T07:56:29.791Z'
+  buildDate: '2026-07-15T05:51:07.722Z'
 };