bitwrench 2.0.21 → 2.0.23

package/docs/tutorial-bwserve.md

@@ -0,0 +1,297 @@
+# Tutorial: Building a Server App with bwserve
+
+This tutorial builds a Streamlit-style dashboard where all state lives on the server. The browser is a thin display — the server pushes UI updates over SSE.
+
+## What you'll build
+
+A real-time analytics dashboard:
+- Live counter with increment/decrement buttons
+- Auto-updating metrics (requests/sec, memory, uptime)
+- Event log with scrolling entries
+- All state on the server — refresh the page and you pick up where you left off
+
+## Prerequisites
+
+- Node.js 18+
+- `npm install bitwrench` (local or global)
+
+## Step 1: Minimal server
+
+Create `server.js`:
+
+```javascript
+import bwserve from 'bitwrench/bwserve';
+
+var app = bwserve.create({ port: 7902, title: 'My Dashboard' });
+
+app.page('/', function(client) {
+  client.render('#app', { t: 'h1', c: 'Hello from the server!' });
+});
+
+app.listen();
+```
+
+Run it:
+
+```bash
+node server.js
+# Open http://localhost:7902
+```
+
+The browser shows "Hello from the server!" — rendered by bitwrench on the client from a TACO object sent over SSE.
+
+## Step 2: Add a counter with buttons
+
+Replace the page handler:
+
+```javascript
+app.page('/', function(client) {
+  var count = 0;
+
+  // Render initial UI
+  client.render('#app', {
+    t: 'div', c: [
+      { t: 'h1', c: 'Counter' },
+      { t: 'div', a: { id: 'count', style: 'font-size: 3rem; text-align: center' }, c: '0' },
+      { t: 'div', a: { style: 'text-align: center; margin-top: 1rem' }, c: [
+        { t: 'button', a: { 'data-bw-action': 'decrement', class: 'bw-btn bw-btn-secondary' }, c: '-1' },
+        { t: 'button', a: { 'data-bw-action': 'increment', class: 'bw-btn bw-btn-primary', style: 'margin-left: 0.5rem' }, c: '+1' },
+        { t: 'button', a: { 'data-bw-action': 'reset', class: 'bw-btn', style: 'margin-left: 0.5rem' }, c: 'Reset' }
+      ]}
+    ]
+  });
+
+  // Handle button clicks
+  client.on('increment', function() {
+    count++;
+    client.patch('count', String(count));
+  });
+
+  client.on('decrement', function() {
+    count--;
+    client.patch('count', String(count));
+  });
+
+  client.on('reset', function() {
+    count = 0;
+    client.patch('count', '0');
+  });
+});
+```
+
+Key concepts:
+- `data-bw-action="increment"` on the button tells the client to POST `{action: "increment"}` when clicked
+- `client.on('increment', fn)` registers a server-side handler for that action
+- `client.patch('count', '0')` sends an SSE message that updates the element with `id="count"`
+
+## Step 3: Add live metrics
+
+Add a metrics section that updates every 2 seconds:
+
+```javascript
+app.page('/', function(client) {
+  var count = 0;
+  var startTime = Date.now();
+  var requestCount = 0;
+
+  // ... counter UI from Step 2 ...
+
+  // Add metrics section below the counter
+  client.append('#app', {
+    t: 'div', a: { style: 'margin-top: 2rem' }, c: [
+      { t: 'h2', c: 'Live Metrics' },
+      { t: 'div', a: { style: 'display: grid; grid-template-columns: repeat(3, 1fr); gap: 1rem' }, c: [
+        { t: 'div', a: { class: 'bw-card' }, c: [
+          { t: 'div', a: { style: 'color: #666; font-size: 0.85rem' }, c: 'Uptime' },
+          { t: 'div', a: { id: 'uptime', style: 'font-size: 1.5rem; font-weight: 700' }, c: '0s' }
+        ]},
+        { t: 'div', a: { class: 'bw-card' }, c: [
+          { t: 'div', a: { style: 'color: #666; font-size: 0.85rem' }, c: 'Memory' },
+          { t: 'div', a: { id: 'memory', style: 'font-size: 1.5rem; font-weight: 700' }, c: '--' }
+        ]},
+        { t: 'div', a: { class: 'bw-card' }, c: [
+          { t: 'div', a: { style: 'color: #666; font-size: 0.85rem' }, c: 'Requests' },
+          { t: 'div', a: { id: 'requests', style: 'font-size: 1.5rem; font-weight: 700' }, c: '0' }
+        ]}
+      ]}
+    ]
+  });
+
+  // Push updates every 2 seconds
+  var interval = setInterval(function() {
+    var uptime = Math.floor((Date.now() - startTime) / 1000);
+    var mem = Math.round(process.memoryUsage().heapUsed / 1024 / 1024);
+
+    client.batch(
+      { type: 'patch', target: 'uptime', content: uptime + 's' },
+      { type: 'patch', target: 'memory', content: mem + ' MB' },
+      { type: 'patch', target: 'requests', content: String(requestCount) }
+    );
+  }, 2000);
+
+  // Track actions as requests
+  client.on('increment', function() { count++; requestCount++; client.patch('count', String(count)); });
+  client.on('decrement', function() { count--; requestCount++; client.patch('count', String(count)); });
+  client.on('reset',     function() { count = 0; requestCount++; client.patch('count', '0'); });
+
+  // Clean up when client disconnects
+  client.on('disconnect', function() {
+    clearInterval(interval);
+  });
+});
+```
+
+`client.batch()` sends all three patches in a single SSE frame — the browser applies them atomically.
+
+## Step 4: Add an event log
+
+Append a scrolling log that records every action:
+
+```javascript
+  // Add log section
+  client.append('#app', {
+    t: 'div', a: { style: 'margin-top: 2rem' }, c: [
+      { t: 'h2', c: 'Event Log' },
+      { t: 'div', a: { id: 'log', style: 'max-height: 200px; overflow-y: auto; border: 1px solid #e5e7eb; border-radius: 6px; padding: 0.5rem; font-family: monospace; font-size: 0.85rem' }, c: '' }
+    ]
+  });
+
+  function logEvent(msg) {
+    var time = new Date().toLocaleTimeString();
+    client.append('#log', {
+      t: 'div', a: { style: 'padding: 2px 0; border-bottom: 1px solid #f3f4f6' },
+      c: time + ' — ' + msg
+    });
+    // Auto-scroll to bottom
+    client.call('scrollTo', { target: '#log', behavior: 'smooth' });
+  }
+
+  // In each handler:
+  client.on('increment', function() {
+    count++; requestCount++;
+    client.patch('count', String(count));
+    logEvent('increment → ' + count);
+  });
+```
+
+`client.call('scrollTo', ...)` invokes a built-in client-side function. Other built-ins: `focus`, `download`, `clipboard`, `redirect`, `log`.
+
+## Step 5: Add a theme
+
+```javascript
+var app = bwserve.create({
+  port: 7902,
+  title: 'Analytics Dashboard',
+  theme: 'ocean'        // Built-in preset: ocean, sunset, forest, slate, etc.
+});
+```
+
+The auto-generated client page applies the theme automatically — all bitwrench components (buttons, cards, alerts) use the theme colors.
+
+## Step 6: Multi-page app
+
+Add a second page:
+
+```javascript
+app.page('/settings', function(client) {
+  client.render('#app', {
+    t: 'div', c: [
+      { t: 'h1', c: 'Settings' },
+      { t: 'a', a: { href: '/' }, c: 'Back to Dashboard' },
+      { t: 'p', c: 'Configure your dashboard preferences here.' }
+    ]
+  });
+});
+```
+
+Each page gets its own handler, its own state, its own client connection. Navigate between them with regular links.
+
+## How it works
+
+```
+Browser                              Server (Node.js)
+  |                                      |
+  |  GET /                               |
+  |  <── HTML shell (bitwrench + SSE)    |
+  |                                      |
+  |  GET /events/:id (SSE)               |
+  |  <── {type:'replace', target:'#app', |
+  |       node: {t:'div', c:[...]}}      |
+  |                                      |
+  |  User clicks [+1] button             |
+  |  POST /action/:id                    |
+  |  {action:'increment', data:{}}  ──>  |
+  |                                      |  count++
+  |  <── {type:'patch',                  |
+  |       target:'count',                |
+  |       content:'1'}                   |
+  |                                      |
+  |  (every 2s)                          |
+  |  <── {type:'batch', ops:[            |
+  |       {type:'patch',target:'uptime'} |
+  |       {type:'patch',target:'memory'} |
+  |      ]}                              |
+```
+
+## Protocol messages
+
+| Type | Method | What it does |
+|------|--------|-------------|
+| `replace` | `client.render(target, taco)` | Replace element content with TACO |
+| `patch` | `client.patch(id, text, attrs)` | Update text/attributes of element |
+| `append` | `client.append(target, taco)` | Add child element |
+| `remove` | `client.remove(target)` | Remove element from DOM |
+| `batch` | `client.batch(op1, op2, ...)` | Multiple ops in one frame |
+| `message` | `client.message(level, text)` | Show notification |
+| `call` | `client.call(name, ...args)` | Invoke registered or built-in function |
+| `exec` | `client.exec(code)` | Run arbitrary JS (requires `allowExec`) |
+| `register` | `client.register(name, body)` | Send named function to client |
+
+### Screenshots
+
+The server can capture what the browser is displaying:
+
+```javascript
+// Enable in server options
+var app = create({ port: 7902, allowScreenshot: true });
+
+app.page('/', function(client) {
+  client.render('#app', myDashboard);
+
+  client.on('capture', async function() {
+    // Capture the full page as PNG
+    var img = await client.screenshot();
+    require('fs').writeFileSync('screenshot.png', img.data);
+
+    // Capture a specific element, resized to max 800px wide
+    var thumb = await client.screenshot('#chart', {
+      maxWidth: 800,
+      format: 'jpeg',
+      quality: 0.8
+    });
+  });
+});
+```
+
+Uses html2canvas (vendored, lazy-loaded). See [screenshot example](../examples/client-server/screenshot-server.js).
+
+## Deployment
+
+bwserve apps are regular Node.js servers. Deploy like any other:
+
+```bash
+# systemd, PM2, Docker, etc.
+node server.js
+
+# Or with environment variables
+PORT=3000 node server.js
+```
+
+For production, put a reverse proxy (nginx, Caddy) in front for TLS and static asset caching.
+
+## Next steps
+
+- [bwserve Reference](bwserve.md) — full API documentation
+- [Component Library](component-library.md) — all 50+ `make*()` components work in bwserve
+- [Tutorial: Embedded](tutorial-embedded.md) — same protocol on ESP32
+- [examples/client-server/](../examples/client-server/) — runnable example

package/docs/tutorial-embedded.md

@@ -0,0 +1,314 @@
+# Tutorial: ESP32 IoT Dashboard with Bitwrench
+
+This tutorial builds a real-time sensor dashboard served by an ESP32 microcontroller. The device sends data — bitwrench renders the UI in the browser.
+
+## What you'll build
+
+- ESP32 serves a bitwrench-powered web page over WiFi
+- Temperature and humidity readings pushed via SSE every 2 seconds
+- LED control button sends commands back to the device
+- Total HTML payload: ~5KB (excluding bitwrench library)
+
+## Architecture
+
+```
+ESP32                                 Browser
+  |                                      |
+  |  GET /                               |
+  |  <── index.html (from SPIFFS)        |
+  |  GET /bitwrench.umd.min.js           |
+  |  <── JS (from SPIFFS)                |
+  |                                      |
+  |  GET /events (SSE)                   |
+  |  <── sensor JSON every 2s            |
+  |                                      |
+  |  POST /api/command                   |
+  |  {cmd: 'led', val: 'on'}  ──>       |
+  |  <── {ok: true}                      |
+```
+
+The ESP32 never generates HTML. It only sends JSON data. The browser renders everything.
+
+## Prerequisites
+
+- ESP32 DevKit (any variant)
+- DHT22 temperature/humidity sensor (GPIO 4)
+- Arduino IDE or PlatformIO
+- Arduino libraries: `ESPAsyncWebServer`, `AsyncTCP`, `DHT sensor library`, `ArduinoJson`
+
+## Step 1: Set up the project
+
+### With bitwrench C headers (recommended)
+
+Copy the embedded C headers into your project:
+
+```
+my_project/
+  my_project.ino
+  bitwrench.h      ← from embedded_c/
+  bwserve.h        ← from embedded_c/
+  data/
+    index.html                 ← the dashboard page
+    bitwrench.umd.min.js.gz   ← gzip -k dist/bitwrench.umd.min.js
+```
+
+### With PlatformIO
+
+```
+lib/
+  bitwrench/
+    bitwrench.h
+    bwserve.h
+data/
+  index.html
+  bitwrench.umd.min.js.gz
+```
+
+Store the gzipped file on flash (~40KB instead of ~150KB). ESPAsyncWebServer
+serves `.gz` files transparently -- the browser decompresses automatically.
+
+## Step 2: Write the Arduino sketch
+
+```cpp
+#include <WiFi.h>
+#include <ESPAsyncWebServer.h>
+#include <SPIFFS.h>
+#include <DHT.h>
+#include "bitwrench.h"
+#include "bwserve.h"
+
+const char* SSID = "YOUR_WIFI";
+const char* PASS = "YOUR_PASSWORD";
+
+#define DHT_PIN  4
+#define LED_PIN  2
+
+AsyncWebServer server(80);
+AsyncEventSource events("/events");
+DHT dht(DHT_PIN, DHT22);
+
+void setup() {
+  Serial.begin(115200);
+  pinMode(LED_PIN, OUTPUT);
+  dht.begin();
+
+  // Mount flash filesystem
+  SPIFFS.begin(true);
+
+  // Connect WiFi
+  WiFi.begin(SSID, PASS);
+  while (WiFi.status() != WL_CONNECTED) delay(500);
+  Serial.print("IP: ");
+  Serial.println(WiFi.localIP());
+
+  // Serve static files from SPIFFS
+  server.serveStatic("/", SPIFFS, "/").setDefaultFile("index.html");
+
+  // SSE endpoint
+  events.onConnect([](AsyncEventSourceClient* client) {
+    Serial.println("Browser connected");
+  });
+  server.addHandler(&events);
+
+  // Command endpoint
+  server.on("/api/command", HTTP_POST,
+    [](AsyncWebServerRequest* req) {},
+    NULL,
+    [](AsyncWebServerRequest* req, uint8_t* data, size_t len, size_t, size_t) {
+      if (strstr((char*)data, "\"led_on\"")) {
+        digitalWrite(LED_PIN, HIGH);
+      } else if (strstr((char*)data, "\"led_off\"")) {
+        digitalWrite(LED_PIN, LOW);
+      }
+      req->send(200, "application/json", "{\"ok\":true}");
+    }
+  );
+
+  server.begin();
+}
+
+void loop() {
+  static unsigned long lastSend = 0;
+  if (millis() - lastSend < 2000) return;
+  lastSend = millis();
+
+  // Read sensors
+  float temp = dht.readTemperature();
+  float hum  = dht.readHumidity();
+
+  // Send batch update using bwserve macros
+  bw_batch_t batch;
+  bw_batch_begin(&batch);
+
+  char m1[256], m2[256], m3[256];
+  char ts[16], hs[16], us[16];
+
+  snprintf(ts, sizeof(ts), "%.1f C", isnan(temp) ? 0.0 : temp);
+  BW_PATCH(m1, "val-temp", ts);
+  bw_batch_add(&batch, m1);
+
+  snprintf(hs, sizeof(hs), "%.1f%%", isnan(hum) ? 0.0 : hum);
+  BW_PATCH(m2, "val-humidity", hs);
+  bw_batch_add(&batch, m2);
+
+  snprintf(us, sizeof(us), "%lus", millis() / 1000);
+  BW_PATCH(m3, "val-uptime", us);
+  bw_batch_add(&batch, m3);
+
+  char out[1024];
+  bw_batch_end(out, sizeof(out), &batch);
+  events.send(out, NULL, millis());
+}
+```
+
+The `BW_PATCH` and `bw_batch_*` macros from `bwserve.h` compose the protocol messages. They use the r-prefix relaxed JSON format, so no double-quote escaping needed.
+
+## Step 3: Write the dashboard HTML
+
+Create `data/index.html`:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>ESP32 Dashboard</title>
+  <script src="/bitwrench.umd.min.js"></script>
+  <style>
+    body { font-family: system-ui, sans-serif; background: #0f172a; color: #e2e8f0; margin: 0; padding: 1rem; }
+    .grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(160px, 1fr)); gap: 0.75rem; max-width: 600px; margin: 1rem auto; }
+    .card { background: #1e293b; border-radius: 8px; padding: 1rem; text-align: center; }
+    .card h3 { margin: 0 0 0.5rem; font-size: 0.8rem; color: #94a3b8; text-transform: uppercase; }
+    .card .val { font-size: 1.5rem; font-weight: 700; color: #38bdf8; }
+    h1 { text-align: center; color: #10b981; }
+    button { background: #334155; color: #e2e8f0; border: 1px solid #475569; border-radius: 6px; padding: 0.5rem 1.5rem; cursor: pointer; margin: 0.25rem; }
+  </style>
+</head>
+<body>
+  <h1>ESP32 Dashboard</h1>
+  <div class="grid">
+    <div class="card"><h3>Temperature</h3><div class="val" id="val-temp">--</div></div>
+    <div class="card"><h3>Humidity</h3><div class="val" id="val-humidity">--</div></div>
+    <div class="card"><h3>Uptime</h3><div class="val" id="val-uptime">--</div></div>
+  </div>
+  <div style="text-align: center; margin-top: 1rem;">
+    <button onclick="sendCmd('led_on')">LED On</button>
+    <button onclick="sendCmd('led_off')">LED Off</button>
+  </div>
+
+  <script>
+    // Connect to SSE stream
+    var es = new EventSource('/events');
+    es.onmessage = function(e) {
+      var raw = e.data;
+      // Handle r-prefix relaxed JSON from ESP32
+      if (raw.charAt(0) === 'r') raw = raw.slice(1).replace(/'/g, '"');
+      try { var msg = JSON.parse(raw); } catch(x) { return; }
+
+      if (msg.type === 'batch') {
+        msg.ops.forEach(applyOp);
+      } else {
+        applyOp(msg);
+      }
+    };
+
+    function applyOp(op) {
+      if (op.type === 'patch') {
+        var el = document.getElementById(op.target);
+        if (el) el.textContent = op.content;
+      }
+    }
+
+    function sendCmd(cmd) {
+      fetch('/api/command', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ cmd: cmd })
+      });
+    }
+  </script>
+</body>
+</html>
+```
+
+This page is ~2KB. With bitwrench.umd.min.js.gz (~40KB), the total SPIFFS usage is ~42KB out of 1.5MB available. ESPAsyncWebServer serves `.gz` files transparently -- the browser decompresses automatically.
+
+## Step 4: Upload and test
+
+1. Edit `SSID` and `PASS` in the sketch
+2. Upload the `data/` folder to SPIFFS (Arduino IDE: Tools > ESP32 Sketch Data Upload)
+3. Upload the sketch
+4. Open Serial Monitor — note the IP address
+5. Navigate to `http://<ip-address>/` in your browser
+
+## Try without hardware first
+
+The `examples/embedded/cmake-demo/` directory contains a POSIX version that compiles on Linux/macOS:
+
+```bash
+cd examples/embedded/cmake-demo
+mkdir build && cd build
+cmake .. && make
+./bwserve_demo
+# Open http://localhost:8080
+```
+
+Same protocol, same macros, simulated sensors. Copy the pattern to your real sketch.
+
+## Memory budget
+
+| Item | Size |
+|------|------|
+| Dashboard HTML | ~2 KB |
+| bitwrench.umd.min.js.gz | ~40 KB |
+| **Total SPIFFS** | **~42 KB** |
+| ESP32 SPIFFS partition | 1.5 MB |
+| Free heap (runtime) | ~240 KB |
+| SSE frame per update | ~200 bytes |
+
+Store gzipped: `gzip -k dist/bitwrench.umd.min.js`. ESPAsyncWebServer
+serves `.gz` files transparently for the matching uncompressed filename.
+
+## The r-prefix relaxed JSON
+
+The C macros produce strings like:
+```
+r{'type':'patch','target':'val-temp','content':'23.5 C'}
+```
+
+The `r` prefix tells the browser parser to convert single quotes to double quotes before `JSON.parse()`. This avoids escaping double quotes in C string literals — a major ergonomic win.
+
+**Escaping rule**: Since single quotes delimit strings, apostrophes in values need escaping with `\'`:
+
+```c
+// Static text with apostrophe — escape in the literal:
+BW_PATCH(msg, "room", "Barry\\'s Room");
+
+// Dynamic user text — use BW_PATCH_SAFE (auto-escapes):
+char user_text[] = "it's 23.5 C";
+BW_PATCH_SAFE(msg, sizeof(msg), "status", user_text);
+```
+
+This is still far better than standard JSON in C, where every quote needs `\"`.
+
+Direction: r-prefix is outbound only (ESP32 to browser). The browser always sends strict JSON back via `fetch()`.
+
+## Other languages
+
+The same protocol works from any language:
+
+| Platform | Language | Library |
+|----------|----------|---------|
+| ESP32 (Arduino) | C/C++ | `embedded_c/bwserve.h` |
+| ESP32 (esp-idf) | Rust | `embedded_rust/` |
+| ESP32/RPi (MicroPython) | Python | `embedded_python/bwserve.py` |
+| Adafruit boards | CircuitPython | `embedded_python/bwserve.py` |
+| Node.js | JavaScript | `import bwserve from 'bitwrench/bwserve'` |
+
+## Next steps
+
+- [bwserve Reference](bwserve.md) — full protocol documentation
+- [embedded_c/ README](../embedded_c/README.md) — C/C++ macro reference
+- [examples/embedded/](../examples/embedded/) — complete example with mock data
+- [Tutorial: bwserve](tutorial-bwserve.md) — same pattern in Node.js