bitwrench 2.0.31 → 2.1.0

package/src/bwserve/index.js

@@ -9,7 +9,7 @@
  *   import bwserve from 'bitwrench/bwserve';
  *   const app = bwserve.create({ port: 7902 });
  *   app.page('/', (client) => {
- *     client.render('#app', bw.makeCard({ title: 'Hello' }));
+ *     client.mount('#app', bw.makeCard({ title: 'Hello' }));
  *   });
  *   app.listen();
  *
@@ -23,7 +23,7 @@ import { VERSION } from '../version.js';
 
 // Resolve dist/ paths relative to the package root
 import { fileURLToPath } from 'url';
-import { dirname, resolve, join, extname } from 'path';
+import { dirname, resolve, join, extname, sep } from 'path';
 import { createServer } from 'http';
 import { readFileSync, readdirSync, existsSync, statSync } from 'fs';
 
@@ -32,9 +32,11 @@ var __dirname = dirname(fileURLToPath(import.meta.url));
 // Resolve dist/ — try source layout (src/bwserve/), then npm install layout,
 // then dist/ itself (when running from dist/bwserve.esm.js)
 var DIST_DIR = resolve(__dirname, '..', '..', 'dist');
+/* c8 ignore next 3 -- DIST_DIR fallback at module load; only triggers in npm install layout */
 if (!existsSync(DIST_DIR)) {
   DIST_DIR = resolve(__dirname, '..', 'dist');
 }
+/* c8 ignore next 3 -- DIST_DIR fallback at module load; only triggers when no dist/ exists */
 if (!existsSync(DIST_DIR)) {
   DIST_DIR = __dirname;
 }
@@ -96,15 +98,14 @@ export function create(opts) {
  */
 class BwServeApp {
   constructor(opts) {
-    this.port = opts.port || 7902;
+    this.port = opts.port != null ? opts.port : 7902;
     this.title = opts.title || 'bwserve';
     this.staticDir = opts.static || null;
     this.injectBitwrench = opts.injectBitwrench !== false;
     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.host = opts.host || '127.0.0.1';
     this.keepAliveInterval = opts.keepAliveInterval || 15000;
     this._pages = new Map();
     this._clients = new Map();
@@ -139,6 +140,11 @@ class BwServeApp {
       });
 
       self._server.listen(self.port, self.host, function() {
+        // Update port to the actual bound port (important when port 0 is used)
+        var addr = self._server.address();
+        if (addr && addr.port) {
+          self.port = addr.port;
+        }
         if (callback) callback();
         res();
       });
@@ -197,9 +203,9 @@ class BwServeApp {
       return 0;
     }
     var count = 0;
-    for (var record of this._clients.values()) {
-      if (record.client && !record.client._closed) {
-        record.client._send(msg);
+    for (var rec of this._clients.values()) {
+      if (rec.client && !rec.client._closed) {
+        rec.client._send(msg);
         count++;
       }
     }
@@ -218,6 +224,7 @@ class BwServeApp {
     var path = url.split('?')[0];
 
     // /bw/attach.js — self-contained attach script for remote debugging
+    /* c8 ignore next 3 -- covered in isolation; flaky in combined suite due to server state */
     if (path === '/bw/attach.js' && method === 'GET') {
       return this._serveAttachScript(req, res);
     }
@@ -244,6 +251,7 @@ class BwServeApp {
     }
 
     // CORS preflight for /bw/return/ (needed for cross-origin attach)
+    /* c8 ignore next 9 -- covered in isolation; flaky in combined suite */
     if (method === 'OPTIONS' && path.startsWith('/bw/return/')) {
       res.writeHead(204, {
         'Access-Control-Allow-Origin': '*',
@@ -258,6 +266,7 @@ class BwServeApp {
     if (method === 'POST' && path.startsWith('/bw/return/')) {
       var rest = path.slice('/bw/return/'.length);
       var slash = rest.indexOf('/');
+      /* c8 ignore next 4 -- covered in isolation; flaky in combined suite */
       if (slash === -1) {
         res.writeHead(400, { 'Content-Type': 'application/json' });
         res.end(JSON.stringify({ error: 'Invalid return path' }));
@@ -274,37 +283,30 @@ class BwServeApp {
       return this._serveVendorFile(res, vendorFile);
     }
 
-    // Registered page routes — serve shell HTML
-    if (method === 'GET' && this._pages.has(path)) {
-      var clientId2 = 'c' + (++this._clientCounter);
-      var shell = generateShell({
-        clientId: clientId2,
-        title: this.title,
-        theme: this.theme,
-        injectBitwrench: this.injectBitwrench,
-        allowExec: this.allowExec
-      });
-      // Store the page path for this client so SSE knows which handler to call
-      this._clients.set(clientId2, { pagePath: path, client: null });
-      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
-      res.end(shell);
-      return;
-    }
-
-    // Static file serving
+    // Static file serving — takes priority over registered page handlers
+    // so that bwserve works as a drop-in static server (like python -m
+    // http.server or npx serve) with opt-in bwserve superpowers.
     if (method === 'GET' && this.staticDir) {
-      var filePath = join(this.staticDir, path);
-      if (existsSync(filePath) && statSync(filePath).isFile()) {
-        var ext = extname(filePath);
+      // Path traversal guard: resolve to absolute and verify containment
+      var resolvedBase = resolve(this.staticDir);
+      var resolvedPath = resolve(resolvedBase, '.' + path);
+      if (resolvedPath !== resolvedBase && !resolvedPath.startsWith(resolvedBase + sep)) {
+        res.writeHead(403, { 'Content-Type': 'text/plain' });
+        res.end('Forbidden');
+        return;
+      }
+
+      if (existsSync(resolvedPath) && statSync(resolvedPath).isFile()) {
+        var ext = extname(resolvedPath);
         var mime = MIME_TYPES[ext] || 'application/octet-stream';
-        var content = readFileSync(filePath);
+        var content = readFileSync(resolvedPath);
         res.writeHead(200, { 'Content-Type': mime });
         res.end(content);
         return;
       }
       // Directory index resolution: /foo/ => /foo/index.html
       if (path.endsWith('/')) {
-        var indexPath = join(this.staticDir, path, 'index.html');
+        var indexPath = join(resolvedPath, 'index.html');
         if (existsSync(indexPath) && statSync(indexPath).isFile()) {
           var indexContent = readFileSync(indexPath);
           res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
@@ -312,16 +314,15 @@ class BwServeApp {
           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);
+        if (this.dirList && existsSync(resolvedPath) && statSync(resolvedPath).isDirectory()) {
+          var listing = this._generateDirListing(path, resolvedPath);
           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()) {
+      if (!path.endsWith('/') && existsSync(resolvedPath) && statSync(resolvedPath).isDirectory()) {
         var qs = url.split('?')[1];
         var location = path + '/' + (qs ? '?' + qs : '');
         res.writeHead(301, { 'Location': location });
@@ -330,6 +331,23 @@ class BwServeApp {
       }
     }
 
+    // Registered page routes — serve bwserve shell HTML (fallback when no
+    // static file matched, e.g. pipe/SSE driven pages)
+    if (method === 'GET' && this._pages.has(path)) {
+      var clientId2 = 'c' + (++this._clientCounter);
+      var shell = generateShell({
+        clientId: clientId2,
+        title: this.title,
+        theme: this.theme,
+        injectBitwrench: this.injectBitwrench
+      });
+      // Store the page path for this client so SSE knows which handler to call
+      this._clients.set(clientId2, { pagePath: path, client: null });
+      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+      res.end(shell);
+      return;
+    }
+
     // 404
     res.writeHead(404, { 'Content-Type': 'text/plain' });
     res.end('Not Found');
@@ -380,9 +398,13 @@ class BwServeApp {
     var pagePath = pending ? pending.pagePath : '/';
     self._clients.set(clientId, { pagePath: pagePath, client: client });
 
+    // Send the handshake as the very first SSE event
+    client._send({ type: 'hello' });
+
     // Keep-alive: send SSE comment periodically
     var keepAlive = setInterval(function() {
       if (!client._closed) {
+        /* c8 ignore next -- keepalive write failure only on socket close */
         try { res.write(':keepalive\n\n'); } catch (e) { /* ignore */ }
       }
     }, self.keepAliveInterval);
@@ -394,11 +416,12 @@ class BwServeApp {
       self._clients.delete(clientId);
     });
 
-    // Call the page handler
+    // Call the page handler (runs on every connection, including reconnects)
     var handler = self._pages.get(pagePath);
     if (handler) {
       try {
         handler(client);
+      /* c8 ignore next 3 -- page handler error catch; requires throwing handler in SSE context */
       } catch (e) {
         console.error('[bwserve] Page handler error:', e);
       }
@@ -411,8 +434,8 @@ class BwServeApp {
    *
    * Routes:
    *   action     — fire-and-forget action dispatch (no requestId)
-   *   query      — resolve pending query promise
-   *   mount      — resolve pending mount promise
+   *   event      — event dispatch from client listeners
+   *   topic      — topic dispatch from client pub/sub
    *   screenshot — resolve pending screenshot promise
    *
    * @private
@@ -430,18 +453,26 @@ class BwServeApp {
     req.on('end', function() {
       try {
         var data = JSON.parse(body);
-        if (route === 'action' || route === 'event') {
+        if (route === 'topic') {
+          // Topic dispatch — forward to the listen handler registered on the client
+          var topic = data.topic;
+          var topicData = data.data;
+          record.client._dispatch('_topic:' + topic, topicData);
+        } else if (route === 'action' || route === 'event') {
           // Action/event dispatch (no requestId/pending pattern)
           var action = route === 'event'
             ? '_bw_event'
             : (data.result ? data.result.action : data.action);
+          /* c8 ignore next 3 -- data.data fallback; covered in isolation */
           var payload = route === 'event'
             ? (data.result || data)
             : (data.result ? data.result.data : data.data || data);
           record.client._dispatch(action, payload);
         } else {
-          // All other routes: resolve pending promise
-          record.client._resolvePending(data.requestId, data);
+          // All other routes: resolve pending promise if mechanism exists
+          if (record.client._resolvePending) {
+            record.client._resolvePending(data.requestId, data);
+          }
         }
         res.writeHead(200, { 'Content-Type': 'application/json', 'Access-Control-Allow-Origin': '*' });
         res.end(JSON.stringify({ ok: true }));
@@ -459,13 +490,18 @@ class BwServeApp {
    */
   _serveAttachScript(req, res) {
     try {
-      var js = generateAttachScript({ origin: '' });
+      var h = req.headers || {};
+      var proto = (h['x-forwarded-proto'] || 'http');
+      var host = h['x-forwarded-host'] || h.host || '';
+      var origin = host ? (proto + '://' + host) : '';
+      var js = generateAttachScript({ origin: origin });
       res.writeHead(200, {
         'Content-Type': 'application/javascript; charset=utf-8',
         'Access-Control-Allow-Origin': '*',
         'Cache-Control': 'no-cache'
       });
       res.end(js);
+    /* c8 ignore next 4 -- generateAttachScript is a pure template; cannot throw */
     } catch (err) {
       res.writeHead(500, { 'Content-Type': 'text/plain' });
       res.end('Error generating attach script: ' + err.message);

package/src/bwserve.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Type declarations for bitwrench/bwserve — server-driven UI over SSE.
+ */
+
+import { IncomingMessage, ServerResponse } from 'http';
+
+/** Options for creating a BwServeApp instance. */
+export interface BwServeOptions {
+  /** Port to listen on (default: 7902) */
+  port?: number;
+  /** Page title (default: 'bwserve') */
+  title?: string;
+  /** Directory path for static file serving */
+  static?: string;
+  /** Auto-inject bitwrench client JS (default: true) */
+  injectBitwrench?: boolean;
+  /** Theme preset name or config object */
+  theme?: string | Record<string, string>;
+  /** Enable client.screenshot() (default: false) */
+  allowScreenshot?: boolean;
+  /** Enable directory listings (default: true) */
+  dirList?: boolean;
+  /** Host/address to bind to (default: '127.0.0.1') */
+  host?: string;
+  /** SSE keep-alive interval in ms (default: 15000) */
+  keepAliveInterval?: number;
+}
+
+/** Options for generateShell(). */
+export interface ShellOptions {
+  /** Unique client ID for this connection */
+  clientId: string;
+  /** Page title (default: 'bwserve') */
+  title?: string;
+  /** Theme preset name or config object */
+  theme?: string | Record<string, string>;
+  /** Whether to inject bitwrench scripts (default: true) */
+  injectBitwrench?: boolean;
+}
+
+/** A TACO object — Tag, Attributes, Content, Options. */
+export interface Taco {
+  t?: string;
+  a?: Record<string, any>;
+  c?: string | Taco | (string | Taco)[];
+  o?: Record<string, any>;
+}
+
+/** SSE protocol message. */
+export interface BwServeMessage {
+  v?: number;
+  type?: string;
+  ref?: string;
+  taco?: Taco;
+  [key: string]: any;
+}
+
+/** Batch operation entry. */
+export interface BatchOp {
+  type: string;
+  ref?: string;
+  taco?: Taco;
+  [key: string]: any;
+}
+
+/** Server-side client connection — represents one browser tab via SSE. */
+export declare class BwServeClient {
+  /** bwserve version string */
+  static version: string;
+
+  /** Unique client identifier */
+  id: string;
+
+  constructor(id: string, res: ServerResponse);
+
+  /** Mount TACO at selector, replacing contents */
+  mount(selector: string, taco: Taco): void;
+
+  /** @deprecated Use mount() instead */
+  render(selector: string, taco: Taco): void;
+
+  /** Patch element properties without full rebuild */
+  patch(ref: string, fields: Record<string, any>): void;
+
+  /** Append TACO as child of target element */
+  append(selector: string, taco: Taco): void;
+
+  /** Remove element from DOM with cleanup */
+  remove(selector: string): void;
+
+  /** Send array of operations as single batch message */
+  batch(ops: BatchOp[]): void;
+
+  /** Dispatch to component's el.bw[action](data) */
+  message(ref: string, action: string, data?: any): void;
+
+  /** Call registered or built-in client function */
+  call(name: string, ...args: any[]): void;
+
+  /** Subscribe to client topic. Returns this for chaining. */
+  listen(topic: string, handler: (data: any) => void): BwServeClient;
+
+  /** Register handler for client action. Returns this for chaining. */
+  on(action: string, handler: (data: any, client: BwServeClient) => void): BwServeClient;
+
+  /** Close SSE connection */
+  close(): void;
+}
+
+/** Main bwserve application — HTTP + SSE server for server-driven UI. */
+export declare class BwServeApp {
+  port: number;
+  title: string;
+  staticDir: string | null;
+  injectBitwrench: boolean;
+  theme: string | Record<string, string> | null;
+  allowScreenshot: boolean;
+  dirList: boolean;
+  host: string;
+  keepAliveInterval: number;
+
+  /** Number of active client connections */
+  readonly clientCount: number;
+
+  constructor(opts?: BwServeOptions);
+
+  /** Register a page handler. Returns this for chaining. */
+  page(path: string, handler: (client: BwServeClient) => void): BwServeApp;
+
+  /** Start HTTP server. Returns Promise that resolves when listening. */
+  listen(callback?: () => void): Promise<void>;
+
+  /** Stop server and close all client connections. */
+  close(): Promise<void>;
+
+  /** Send protocol message to all clients (or specific client if msg.clientId is set). Returns count of recipients. */
+  broadcast(msg: BwServeMessage): number;
+}
+
+/** Generate a complete HTML shell document for SSE connection. */
+export declare function generateShell(opts?: ShellOptions): string;
+
+/** Create a new BwServeApp instance. */
+export declare function create(opts?: BwServeOptions): BwServeApp;
+
+/** bwserve version string */
+export declare const version: string;
+
+/** Default export */
+declare const bwserve: {
+  create: typeof create;
+  version: string;
+  BwServeApp: typeof BwServeApp;
+  BwServeClient: typeof BwServeClient;
+  generateShell: typeof generateShell;
+};
+export default bwserve;

package/src/bwserve.h

@@ -0,0 +1,5 @@
+/*
+ * Shim header for the Arduino library layout ("recursive" layout adds only
+ * src/ to the include path). The real header lives in embedded_c/bwserve.h.
+ */
+#include "../embedded_c/bwserve.h"

package/src/cli/attach.js

@@ -29,8 +29,8 @@ Usage:
 Description:
   Starts a bwserve instance and waits for a browser to connect via the
   drop-in attach script. Once connected, you get an interactive REPL
-  where you can evaluate JS expressions, inspect the DOM, take
-  screenshots, and listen to events — all from your terminal.
+  for inspecting the DOM, mounting components, taking screenshots,
+  and listening to events — all from your terminal.
 
   To connect a page, either:
   1. Add <script src="http://localhost:<port>/bw/attach.js"></script>
@@ -44,7 +44,6 @@ Options:
   -h, --help                 Print this help
 
 REPL Commands:
-  <expression>               Evaluate JS in the connected browser (e.g., document.title)
   /help                      Show command reference
   /quit, /q                  Exit
   /inspect [selector] [depth] Show DOM tree summary (default: body, depth 3)
@@ -55,7 +54,6 @@ REPL Commands:
   /listen <sel> <event>      Start listening for DOM events (e.g., /listen button click)
   /unlisten <sel> <event>    Stop listening for a previously added listener
   /clients                   List connected clients
-  /exec <code>               Execute JS without capturing return value
 
 Examples:
   bwcli attach                            Start on default port 7902
@@ -64,8 +62,6 @@ Examples:
   bwcli attach -v                         Verbose mode (shows protocol)
 
   # In the REPL:
-  bw> document.title
-  bw> bw.$('.bw-card').length
   bw> /inspect #app 2
   bw> /screenshot body page.png
   bw> /listen .bw-btn click
@@ -80,21 +76,7 @@ Examples:
   bw> /listen .bw-btn click
 `.trim();
 
-/**
- * Wrap a JS expression for client.query().
- * Statements (var, let, const, if, for, etc.) are sent as-is.
- * Expressions are wrapped in return() so the result comes back.
- *
- * @param {string} code - User input
- * @returns {string} Code suitable for new Function()
- */
-export function wrapExpression(code) {
-  code = code.trim();
-  if (/^(var |let |const |if |for |while |function |try |switch |throw |class |\{)/.test(code)) {
-    return code;
-  }
-  return 'return (' + code + ')';
-}
+// v2.1: wrapExpression and bare JS eval removed — no code-over-wire.
 
 /**
  * Run the attach subcommand.
@@ -160,7 +142,6 @@ export function startAttach(bwserve, opts) {
   var app = bwserve.create({
     port: opts.port,
     title: 'bwcli attach',
-    allowExec: true,
     allowScreenshot: opts.allowScreenshot
   });
 
@@ -266,33 +247,9 @@ export function startAttach(bwserve, opts) {
       return;
     }
 
-    // JS expression — requires active client
-    if (!activeClient) {
-      console.log('No client connected. Add the attach script to a page first.');
-      safePrompt();
-      return;
-    }
-
-    var code = wrapExpression(line);
-    if (opts.verbose) {
-      console.log('[query] ' + code);
-    }
-
-    activeClient.query(code, { timeout: 10000 }).then(function(result) {
-      if (result !== undefined && result !== null) {
-        try {
-          console.log(typeof result === 'string' ? result : JSON.stringify(result, null, 2));
-        } catch (e) {
-          console.log(String(result));
-        }
-      } else {
-        console.log('undefined');
-      }
-      safePrompt();
-    }).catch(function(err) {
-      console.error('[error] ' + err.message);
-      safePrompt();
-    });
+    // Non-slash input: show hint (no more bare JS eval)
+    console.log('Unknown input. Type /help for available commands.');
+    safePrompt();
   });
 
   rl.on('close', function() {
@@ -417,13 +374,13 @@ export function handleSlashCommand(line, activeClient, clients, opts, rl) {
           break;
         }
       }
-      activeClient.mount(mountSel, mountComp, mountProps, { timeout: 10000 }).then(function() {
-        console.log('Mounted ' + mountComp + ' at ' + mountSel);
-        rl.prompt();
-      }).catch(function(err) {
-        console.error('[error] ' + err.message);
-        rl.prompt();
+      activeClient.call('_bw_mount', {
+        target: mountSel,
+        factory: mountComp,
+        props: mountProps
       });
+      console.log('Mounted ' + mountComp + ' at ' + mountSel);
+      rl.prompt();
       break;
 
     case '/render':
@@ -508,22 +465,6 @@ export function handleSlashCommand(line, activeClient, clients, opts, rl) {
       rl.prompt();
       break;
 
-    case '/exec':
-      if (!activeClient) {
-        console.log('No client connected.');
-        rl.prompt();
-        break;
-      }
-      if (parts.length < 2) {
-        console.log('Usage: /exec <code>');
-        rl.prompt();
-        break;
-      }
-      activeClient.exec(parts.slice(1).join(' '));
-      console.log('Executed.');
-      rl.prompt();
-      break;
-
     default:
       console.log('Unknown command: ' + cmd + '. Type /help for available commands.');
       rl.prompt();
@@ -558,9 +499,6 @@ export function printHelp() {
     '',
     'bwcli attach — REPL Commands',
     '',
-    '  <expression>               Evaluate JS in the browser and print result',
-    '                             Examples: document.title, bw.$(".card").length',
-    '',
     '  /help, /h                  Show this help',
     '  /quit, /q                  Exit',
     '',
@@ -577,7 +515,6 @@ export function printHelp() {
     '  /listen <sel> <event>      Listen for DOM events (prints inline)',
     '                             Example: /listen button click',
     '  /unlisten <sel> <event>    Remove a listener',
-    '  /exec <code>               Execute JS without capturing return value',
     '  /clients                   List connected clients',
     '',
     '  Workflow — build and push a component:',

package/src/cli/convert.js

@@ -7,7 +7,7 @@ import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { resolve, extname, basename, dirname } from 'node:path';
 import quikdown from '../vendor/quikdown.js';
 import bw from '../bitwrench.js';
-import { getAllStyles, THEME_PRESETS } from '../bitwrench-styles.js';
+import { THEME_PRESETS } from '../bitwrench-styles.js';
 import { getInjectionHead, getInjectionBodyEnd } from './inject.js';
 import { makePageLayout } from './layout-default.js';
 
@@ -110,7 +110,7 @@ export function convertFile(inputPath, flags = {}) {
     const raw = readFileSync(absInput, 'utf8');
     const ext = extname(absInput).toLowerCase();
 
-    let bodyHTML = '';
+    let bodyHTML;
     let autoTitle = null;
 
     // Process based on file extension