bitwrench 2.0.15 → 2.0.17

package/dist/sri.json

@@ -1,33 +1,41 @@
 {
-  "version": "2.0.15",
+  "version": "2.0.17",
   "algorithm": "sha384",
-  "generated": "2026-03-10",
+  "generated": "2026-03-13",
   "files": {
-    "bitwrench-code-edit.cjs.js": "sha384-/bNOqn95bkCYJCgvldLJRxaxrEMiOL9piW7D31QjgOnE0Bj8ke48M7R3K/ZHi5vz",
-    "bitwrench-code-edit.cjs.min.js": "sha384-ps1tCwgt+YjAGinSLyGKY5ZsnV7KutVYKxVWYruS3gP3TbyafQJySwih5Fn80ZFK",
-    "bitwrench-code-edit.es5.js": "sha384-vGhHBjXz591gQgE+pckuNJWsnPqisOchcSe04rudf6hYVBAwoNhRSemylUapsDv7",
-    "bitwrench-code-edit.es5.min.js": "sha384-g6K2l3no0codjtoRbKBLqn2eYGqYbRitFqxpw7aO2u8Nbx++4EOmAG/XqcENBTAK",
-    "bitwrench-code-edit.esm.js": "sha384-xEJF0fnbv5RPG+mh6uPb6tKmV1icZ1ZV46+LP+JzNNDYy43AOc32UdmRtbPM/CnX",
-    "bitwrench-code-edit.esm.min.js": "sha384-kxjp+unxOUGXueWiOYK7r9snqgLE2d1wpjybHrEILes1+bS3rnWVhg2OVFScnzY/",
-    "bitwrench-code-edit.umd.js": "sha384-B5lapHaMiyQ0mnd41EYO8N2F9vWyw+G1pocd0s2IxztRCoqLxQ9yMfyFJqdUB7s1",
-    "bitwrench-code-edit.umd.min.js": "sha384-IHAz1etjFsiS5iYQUamcrysiuhJ64CrgwaXcTyyoxOAiXnDpCcGW/q1C/+/RddbX",
-    "bitwrench-lean.cjs.js": "sha384-qlWuZnAZS14Zp/FKrTGtfH8AwI4A9mrXNh3cq8kBDkUlo4ZI3hQEiCRQwfQpn0ic",
-    "bitwrench-lean.cjs.min.js": "sha384-pVY2BB/U0dn5JZM/r47Hv61bgiSryf9ZIePN+hQkhkFAkFJrsDqIT+HjQB3D7WRw",
-    "bitwrench-lean.es5.js": "sha384-Xb+Lra8oUB0jRRTwFyfVppS/lFOiHthdu4eYWYbRqWkJ/PbByyhEoQV5bHB8EvPI",
-    "bitwrench-lean.es5.min.js": "sha384-z4Qf0p+RbLyXVhft6XrqDFapRaKh4fh6CrJSwdRruVlY1oHp+sMpuEtoyhuR5nGA",
-    "bitwrench-lean.esm.js": "sha384-JtZWDCq1UZGqvFUUtuMFeSAruMdCSK7xZq3XOjZv8AE03IF8+nRjmlyfJCZDGVNV",
-    "bitwrench-lean.esm.min.js": "sha384-8uBjskc3WvHSTbe8ZGOUOCc1UJH85iBRcdDqnsjBC6EI1Skzu5fWR/i9hgpA3psD",
-    "bitwrench-lean.umd.js": "sha384-iV0Un/IlMdxbT3Mfi6fVTXkaVP2NDVLa2u3K5dQtKXBEhVYfPMv+jv9lultT+kSh",
-    "bitwrench-lean.umd.min.js": "sha384-mhHV7Zd3oamSfYyU/mX5OD3xw3gqCiUvYmm2IM9/T4GrrD0Aj9Bvif9Aae/eLT36",
-    "bitwrench.cjs.js": "sha384-Gl3hM4aTs/afOUDefxOfyriRruD69mJsC7pChob/Esg3qdV3+RoY90wLsThEJN4n",
-    "bitwrench.cjs.min.js": "sha384-/mPUPWrJE0/9176PeMBw0hZGBFtQ0LNzRk8F9EK3mkVBQFQUpRmOrxy7q7KDEP4C",
-    "bitwrench.css": "sha384-G7kC+3If3rNHBh23G8LHZa3NvPsf+s5fNGaXAZkqtg8Nas0WmhOdWHTbqTEijKQM",
-    "bitwrench.es5.js": "sha384-Q8ctFLQAXaBuM5JXFwCUQelQUKE21k0Gc5i+2nsM3Ym329Fh930RYk4b5ateACSp",
-    "bitwrench.es5.min.js": "sha384-pb/2mUSIQW5L3jH21snKnd3Hp+VD8CmxKgFVr2qgZQbruDeY1PLCp/eLU70C+A1T",
-    "bitwrench.esm.js": "sha384-HAlG1Fs6lhPxVP5zn0rkgyf2GqvLCjos71Va0lTF1HvSX6eWOs8LWXQ1ku+J7/9I",
-    "bitwrench.esm.min.js": "sha384-GWl9IOVhYVEa51cA+COtFM9wFkfD3fQqO3DYTVGl8QJOP3dbuuDLWtP0aFwZBveF",
-    "bitwrench.min.css": "sha384-okjJZx1EoXcKaEospKzJk0MxyQprKaGYaqBYGWEHkknFyOWhfAsf0gYCw7hU7mAs",
-    "bitwrench.umd.js": "sha384-MvEk3PxsoQTdUunY7vEMh+ysBA7tIErjU/vCj5MF3INyxTWXbqiwYwud+8erXEQ9",
-    "bitwrench.umd.min.js": "sha384-aXIq51Hw9LQDyIeq4mJEbvUkPf5E8tfkj/ffyQ+fOdE569kRu0IBglpMIiE2Cpt9"
+    "bitwrench-bccl.cjs.js": "sha384-JtHrGKdL2R+Np/4hJCUnnKa+gVhO1HMojkcUDQsnX4iyyf/CVq4SaTuCWQyz1q1q",
+    "bitwrench-bccl.cjs.min.js": "sha384-gKYoqvlm7yhCh7//O/fkRZtdC6X2j7+cTrl85bAj6fNfB8DnZqvhqnXGPdKSthF7",
+    "bitwrench-bccl.esm.js": "sha384-go+h+i6cxCy1JnOTEQ3ukm9RCf5KwBInhSnofh++ktdhKAfqoWmB766VseRGCtXY",
+    "bitwrench-bccl.esm.min.js": "sha384-zt2eb/zS5QAotiywhp3nZXmxwBRR4rb4R8A8mKo0IpZIXL3tWYTwSrr87k+aUOa5",
+    "bitwrench-bccl.umd.js": "sha384-85C9Wud5azObw2tgX7KVS0zOo/+GhNSYldFZehW5f917xe86WR6ai28Yqb2bV7BG",
+    "bitwrench-bccl.umd.min.js": "sha384-MnURAnFgYO7gpv2AD/nSra7oCppx/LaeWr7Zhn++o66Grw+tfBcIjmbmTBzR8suQ",
+    "bitwrench-code-edit.cjs.js": "sha384-pYMU67JSAuOzmvDIptwgJU9l1ATHRZVIKYIbmJtxJJiwmbTBF023aYxNYuU2kCFh",
+    "bitwrench-code-edit.cjs.min.js": "sha384-gyKZwcVfwGq+oJdbhzOrjROdtQUW9GR+m1iU69kh+ybPZ+OzSAH7cOx1Z3Cib0EM",
+    "bitwrench-code-edit.es5.js": "sha384-i6eXPifX0VPfeKo4jI1JYD26PQJh2HxtDQblAFeeFC0k5y8jmOgLKtk86UPT14vs",
+    "bitwrench-code-edit.es5.min.js": "sha384-I2r5vCUHcQT/UqKdbMqLk5uhc7rqBKhP4qJzoItEHBcuLFdzMbfRrTj5l3lk15QJ",
+    "bitwrench-code-edit.esm.js": "sha384-CVdqruuHB4k6wehD26cio10tl8xCcQfdQmdMWlDuYFYF3R2re7ZjTZClz1TAvxlb",
+    "bitwrench-code-edit.esm.min.js": "sha384-kKtUe03iCRXxIV1bpLffhl1apf8JJeteXVSdfM2HS9HyKkvf5uiFN96CC2VzFt24",
+    "bitwrench-code-edit.umd.js": "sha384-qzPZG4wK/7oBf+uXwbUBNNRA9zuOsxChJXXipoZBg8gt51e/uhmkiD5jVBDsXPNF",
+    "bitwrench-code-edit.umd.min.js": "sha384-zEBjo8SgTdGymQQwRYva/iW2iCUjT0Tdtocik63xi00qE88OEFl8kejj5KCrxCNc",
+    "bitwrench-lean.cjs.js": "sha384-XP0qyS4rfU2MUK93n0zgpIhOMjyTxEqMtTrErOopcsDRuYIsY0b4zeS/wa+6GEJn",
+    "bitwrench-lean.cjs.min.js": "sha384-Aep5GOW8Qu0H5ZDbMXna4ku9QQQgrAAfpJFMBiRHY+XuglwZooFfgSTezhR1eftj",
+    "bitwrench-lean.es5.js": "sha384-bkwm+dTlJQ/DyPOz04TVSpDd0UqdCY7B6/y01N/P9pAnTlx/S94mkm8TQfzQW+gy",
+    "bitwrench-lean.es5.min.js": "sha384-+JD7oSIx3Gl1wsUNWXeSZqBz1mOLcjpI+ScQR1d0oFyhf62zyyWSl02KhC1vO46m",
+    "bitwrench-lean.esm.js": "sha384-5lIJxbMwgIeJnNk9yNMvUf7PnIdt4e6b1QzQD3psRv46xDLDcTFRxXA1rloyAY1i",
+    "bitwrench-lean.esm.min.js": "sha384-XLQK7n6rfH6mXKYJFWi0TlwDyE20YyzGtkuFffQRwKCLD7yMn1ZAHxQxwKP1MvuW",
+    "bitwrench-lean.umd.js": "sha384-HHotDwMh/Ipq3JcDJzr2anOJcLynPS8XBJkPFsbUOz+Irbwd1LyEYZ7HkUCgmrJu",
+    "bitwrench-lean.umd.min.js": "sha384-G18BfqAXGt/2VzZ0oCTxpdZZSh/eriVzz8xlf0MxFrEDfj6NWLWn6Rqp9pHEtyHf",
+    "bitwrench.cjs.js": "sha384-TjEj7ETG/CylzHHnyc3dbxjJ9A8CXoaCouPzBpdex/u6wU68YayPG+yXyt+Jcg83",
+    "bitwrench.cjs.min.js": "sha384-w1Gl0tTOOSMBqXYVAKMudrFfXJ+nNf5va7q5GEPKMYtxVQQyDpDP4yL9+/uyZtTW",
+    "bitwrench.css": "sha384-TLf4tWABJynZ7cb9epG9VhRM1IvuK5k4VD5wHE2esbGXcuKzG6iArqimHPzZDLD2",
+    "bitwrench.es5.js": "sha384-FE2hzUIF9en6TGljWhEr1vKvofcNSLQJsjU6XlDiezwG3DgJgDKIafuSDu00NWfK",
+    "bitwrench.es5.min.js": "sha384-c3gOIHjeEUGSVtcv6M1N6KmGoWuOUz3H8hGbcIOh90dIZY7Xflx2SLdSaSl5yRWJ",
+    "bitwrench.esm.js": "sha384-08iatqu6LAtx8cZsgXkE34sK7FvN99nn+wXNx0YEEMMRuGRRq35uATUNKv7FcO5U",
+    "bitwrench.esm.min.js": "sha384-S/DNxHQzWvbbrszBTs9wc78m7NnO6Ml7iw18/V5mki40a7WKfckhLGmsFMKfQw+N",
+    "bitwrench.min.css": "sha384-Sl7+BxWfINNnNdN+ZCL1s/p4Hn+5WeJPciWS9svNuzal8h9baX19xGeOJNzradRY",
+    "bitwrench.umd.js": "sha384-8nLO+4nHEnvnbslfteLo04OfUqDTZcB/Q5uelctfeIuPU2MXP02BO3iE4Jsz3Bp5",
+    "bitwrench.umd.min.js": "sha384-y+l0IvKb1/9dBiradZkR1Alh6o0KtJgrkupdlYVLw/x4By7+tNtJcSu5D7N5u4IE",
+    "bwserve.cjs.js": "sha384-ShnkqIcaohORoeDTsw/KEij2kTbtuj6dFtZExUgLJdvgy3hWmHWVpktT9jhUczTg",
+    "bwserve.esm.js": "sha384-Je3FPrcpT8TjizTUMW3tzlRgmJxKnLFabVV+eaCfZRnPDx5uJVARuS+TEXbnrWWt"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "bitwrench",
-	"version": "2.0.15",
+	"version": "2.0.17",
 	"description": "A library for javascript UI functions.",
 	"main": "./dist/bitwrench.umd.js",
 	"repository": {
@@ -13,7 +13,7 @@
 	"author": "manu a. chatterjee <deftio@deftio.com> (https://deftio.com/)",
 	"license": "BSD-2-Clause",
 	"bin": {
-		"bitwrench": "./bin/bitwrench.js"
+		"bwcli": "./bin/bwcli.js"
 	},
 	"type": "module",
 	"module": "./dist/bitwrench.esm.js",
@@ -22,6 +22,20 @@
 			"import": "./dist/bitwrench.esm.js",
 			"require": "./dist/bitwrench.cjs.js",
 			"default": "./dist/bitwrench.umd.js"
+		},
+		"./lean": {
+			"import": "./dist/bitwrench-lean.esm.js",
+			"require": "./dist/bitwrench-lean.cjs.js",
+			"default": "./dist/bitwrench-lean.umd.js"
+		},
+		"./bccl": {
+			"import": "./dist/bitwrench-bccl.esm.js",
+			"require": "./dist/bitwrench-bccl.cjs.js",
+			"default": "./dist/bitwrench-bccl.umd.js"
+		},
+		"./bwserve": {
+			"import": "./dist/bwserve.esm.js",
+			"require": "./dist/bwserve.cjs.js"
 		}
 	},
 	"types": "./dist/bitwrench.d.ts",
@@ -81,7 +95,8 @@
 		"build_1_x": "./tools/update-bw-package.js package.json package.json && ./tools/export-bw-default-css.js bitwrench.css && uglifyjs bitwrench.js -o  bitwrench.min.js && uglifyjs bitwrench_ESM.js -o bitwrench_ESM.min.js && ./tools/umd2ModuleHack.js && npm pack",
 		"cleanbuild": "npm run clean && npm run build && npm run build:generated",
 		"oldtest": "./node_modules/mocha/bin/mocha test/bitwrench_test.js --reporter spec",
-		"test": "c8 --reporter=text mocha ./test/bitwrench_ci.js ./test/bitwrench_test_coverage.js ./test/bitwrench_test_pubsub.js ./test/bitwrench_test_theme.js ./test/bitwrench_test_nodemap.js ./test/bitwrench_test_components.js ./test/bitwrench_test_component_handle.js ./test/bitwrench_test_coverage_gaps.js -r jsdom-global/register",
+		"test": "c8 --reporter=text mocha ./test/bitwrench_ci.js ./test/bitwrench_test_coverage.js ./test/bitwrench_test_pubsub.js ./test/bitwrench_test_theme.js ./test/bitwrench_test_nodemap.js ./test/bitwrench_test_components.js ./test/bitwrench_test_component_handle.js ./test/bitwrench_test_coverage_gaps.js ./test/bitwrench_test_bwserve.js ./test/bitwrench_test_code_edit.js ./test/bitwrench_test_html_page.js -r jsdom-global/register",
+		"test:bwserve": "mocha ./test/bitwrench_test_bwserve.js -r jsdom-global/register",
 		"test:components": "mocha ./test/bitwrench_test_components.js -r jsdom-global/register",
 		"test:v1": "c8 --reporter=text mocha ./test/bitwrench_test.js -r jsdom-global/",
 		"test:pending": "mocha ./test/bitwrench_test_pending.js -r jsdom-global/",
@@ -96,6 +111,8 @@
 		"generate-sri": "node tools/generate-sri.js",
 		"test:nodemap": "mocha ./test/bitwrench_test_nodemap.js -r jsdom-global/register",
 		"test:cli": "mocha ./test/bitwrench_test_cli.js",
+		"test:code-edit": "mocha ./test/bitwrench_test_code_edit.js -r jsdom-global/register",
+		"test:html-page": "mocha ./test/bitwrench_test_html_page.js -r jsdom-global/register",
 		"test:e2e": "playwright test",
 		"test:e2e:headed": "playwright test --headed",
 		"test:e2e:debug": "playwright test --debug",

package/readme.html

@@ -3,7 +3,7 @@
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <meta name="generator" content="bitwrench v2.0.15">
+  <meta name="generator" content="bitwrench v2.0.17">
   <title>bitwrench.js - README</title>
   <link rel="icon" type="image/x-icon" href="images/favicon.ico">
   <script src="dist/bitwrench.umd.js"></script>
@@ -96,7 +96,8 @@ const bw = require(&#39;bitwrench&#39;);</code></pre><p>Or include directly in a
 <li class="quikdown-li"><strong class="quikdown-strong">Built-in reactivity</strong> — <code class="quikdown-code">bw.update()</code> re-renders components when state changes, <code class="quikdown-code">bw.patch()</code> updates individual elements by ID, <code class="quikdown-code">bw.pub()</code>/<code class="quikdown-code">bw.sub()</code> provides decoupled messaging between any part of the application</li>
 <li class="quikdown-li"><strong class="quikdown-strong">CSS and theme generation</strong> — <code class="quikdown-code">bw.css()</code> generates stylesheets from objects, <code class="quikdown-code">bw.generateTheme()</code> derives a complete visual theme (buttons, alerts, badges, cards, forms, tables, dark mode) from 2-3 seed colors</li>
 <li class="quikdown-li"><strong class="quikdown-strong">45+ ready-made components</strong> — cards, buttons, sortable tables, form inputs, modals, dropdowns, accordions, tooltips, popovers, toasts, timelines, steppers, file uploads, stat cards — each a single function call that returns a composable object</li>
-<li class="quikdown-li"><strong class="quikdown-strong">Static site CLI</strong> — the <code class="quikdown-code">bitwrench</code> command converts Markdown, HTML, and JSON files into styled, self-contained pages with theme support</li>
+<li class="quikdown-li"><strong class="quikdown-strong">Server-driven UI (bwserve)</strong> — push TACO rendering commands from Node.js to the browser over SSE; same protocol works from C (ESP32), Python, Rust, or any language via the <code class="quikdown-code">bwcli serve</code> pipe server</li>
+<li class="quikdown-li"><strong class="quikdown-strong">Static site CLI</strong> — the <code class="quikdown-code">bwcli</code> command converts Markdown, HTML, and JSON files into styled, self-contained pages with theme support</li>
 <li class="quikdown-li"><strong class="quikdown-strong">Utilities</strong> — color interpolation, random data generation, lorem ipsum, cookies, URL params, file I/O for both browser and Node.js</li>
 </ul><h2 class="quikdown-h2">Getting Started</h2>
 <p><pre class="quikdown-pre"><code class="language-html">&lt;!DOCTYPE html&gt;
@@ -123,23 +124,24 @@ const bw = require(&#39;bitwrench&#39;);</code></pre><p>Or include directly in a
   &lt;/script&gt;
 &lt;/body&gt;
 &lt;/html&gt;</code></pre></p><h2 class="quikdown-h2">Adding State</h2>
-<p>The <code class="quikdown-code">o</code> key adds state and a render function to any element. When state changes, call <code class="quikdown-code">bw.update()</code> to re-render:</p><pre class="quikdown-pre"><code class="language-javascript">bw.DOM(&#39;#counter&#39;, {
-  t: &#39;div&#39;,
+<p>Wrap any TACO in <code class="quikdown-code">bw.component()</code> to get a reactive component with <code class="quikdown-code">.get()</code>, <code class="quikdown-code">.set()</code>, and template bindings:</p><pre class="quikdown-pre"><code class="language-javascript">var counter = bw.component({
+  t: &#39;div&#39;, c: [
+    { t: &#39;span&#39;, c: &#39;Count: ${count}&#39; },
+    { t: &#39;button&#39;, c: &#39;+1&#39;, a: {
+      onclick: function() { counter.set(&#39;count&#39;, counter.get(&#39;count&#39;) + 1); }
+    }}
+  ],
   o: {
     state: { count: 0 },
-    render: function(el) {
-      var s = el._bw_state;
-      bw.DOM(el, {
-        t: &#39;div&#39;, c: [
-          { t: &#39;span&#39;, c: &#39;Count: &#39; + s.count },
-          { t: &#39;button&#39;, a: {
-            onclick: function() { s.count++; bw.update(el); }
-          }, c: &#39;+1&#39; }
-        ]
-      });
+    methods: {
+      reset: function(comp) { comp.set(&#39;count&#39;, 0); }
     }
   }
-});</code></pre><p>For communication between components, use pub/sub:</p><pre class="quikdown-pre"><code class="language-javascript">bw.sub(&#39;item-added&#39;, function(detail) {
+});
+
+bw.DOM(&#39;#app&#39;, counter);
+counter.set(&#39;count&#39;, 42);   // DOM updates automatically
+counter.reset();             // methods from o.methods are callable on the handle</code></pre><p>For low-level control, you can also use <code class="quikdown-code">o.render</code> + <code class="quikdown-code">bw.update()</code> directly — see the <a class="quikdown-a" href="docs/state-management.md">State Management guide</a>.</p><p>For communication between components, use pub/sub:</p><pre class="quikdown-pre"><code class="language-javascript">bw.sub(&#39;item-added&#39;, function(detail) {
   console.log(&#39;New item:&#39;, detail.name);
 });
 
@@ -167,6 +169,10 @@ bw.toggleTheme();  // switch between primary and alternate palettes</code></pre>
 <td class="quikdown-td">Mount an object to a DOM element</td>
 </tr>
 <tr class="quikdown-tr">
+<td class="quikdown-td"><code class="quikdown-code">bw.component(taco)</code></td>
+<td class="quikdown-td">Wrap a TACO in a ComponentHandle with <code class="quikdown-code">.get()/.set()</code> reactive API</td>
+</tr>
+<tr class="quikdown-tr">
 <td class="quikdown-td"><code class="quikdown-code">bw.css(rules)</code></td>
 <td class="quikdown-td">Generate CSS from a JS object</td>
 </tr>
@@ -187,6 +193,10 @@ bw.toggleTheme();  // switch between primary and alternate palettes</code></pre>
 <td class="quikdown-td">Re-render via the element&#39;s <code class="quikdown-code">o.render</code> function</td>
 </tr>
 <tr class="quikdown-tr">
+<td class="quikdown-td"><code class="quikdown-code">bw.message(target, action, data)</code></td>
+<td class="quikdown-td">Send a message to a component by tag name</td>
+</tr>
+<tr class="quikdown-tr">
 <td class="quikdown-td"><code class="quikdown-code">bw.pub(topic, detail)</code></td>
 <td class="quikdown-td">Publish a message to subscribers</td>
 </tr>
@@ -194,16 +204,34 @@ bw.toggleTheme();  // switch between primary and alternate palettes</code></pre>
 <td class="quikdown-td"><code class="quikdown-code">bw.sub(topic, handler)</code></td>
 <td class="quikdown-td">Subscribe to a topic; returns an unsub function</td>
 </tr>
+<tr class="quikdown-tr">
+<td class="quikdown-td"><code class="quikdown-code">bw.inspect(target)</code></td>
+<td class="quikdown-td">Debug a component in the browser console</td>
+</tr>
+<tr class="quikdown-tr">
+<td class="quikdown-td"><code class="quikdown-code">bw.clientConnect(url, opts)</code></td>
+<td class="quikdown-td">Connect to a bwserve SSE endpoint</td>
+</tr>
+<tr class="quikdown-tr">
+<td class="quikdown-td"><code class="quikdown-code">bw.clientApply(msg)</code></td>
+<td class="quikdown-td">Apply a bwserve protocol message to the DOM</td>
+</tr>
+<tr class="quikdown-tr">
+<td class="quikdown-td"><code class="quikdown-code">bw.clientParse(str)</code></td>
+<td class="quikdown-td">Parse strict or r-prefix relaxed JSON</td>
+</tr>
 </tbody>
 </table><p>See the full <a class="quikdown-a" href="https://deftio.github.io/bitwrench/pages/08-api-reference.html" rel="noopener noreferrer">API Reference</a> for all functions.</p><h2 class="quikdown-h2">CLI</h2>
 <p>Convert Markdown, HTML, or JSON files to styled standalone pages:</p><pre class="quikdown-pre"><code class="language-bash"># Convert Markdown to a self-contained HTML page
-bitwrench README.md -o index.html --standalone
+bwcli README.md -o index.html --standalone
 
 # Apply a theme preset
-bitwrench doc.md -o doc.html --standalone --theme ocean
+bwcli doc.md -o doc.html --standalone --theme ocean
 
 # Custom colors
-bitwrench doc.md -o doc.html --standalone --theme &quot;#336699,#cc6633&quot;</code></pre><p>Flags: <code class="quikdown-code">--output/-o</code>, <code class="quikdown-code">--standalone/-s</code>, <code class="quikdown-code">--cdn</code>, <code class="quikdown-code">--theme/-t</code>, <code class="quikdown-code">--css/-c</code>, <code class="quikdown-code">--title</code>, <code class="quikdown-code">--favicon/-f</code>, <code class="quikdown-code">--highlight</code>, <code class="quikdown-code">--verbose/-v</code></p><h2 class="quikdown-h2">Build Formats</h2>
+bwcli doc.md -o doc.html --standalone --theme &quot;#336699,#cc6633&quot;</code></pre><p>Flags: <code class="quikdown-code">--output/-o</code>, <code class="quikdown-code">--standalone/-s</code>, <code class="quikdown-code">--cdn</code>, <code class="quikdown-code">--theme/-t</code>, <code class="quikdown-code">--css/-c</code>, <code class="quikdown-code">--title</code>, <code class="quikdown-code">--favicon/-f</code>, <code class="quikdown-code">--highlight</code>, <code class="quikdown-code">--verbose/-v</code></p><h3 class="quikdown-h3">Pipe Server</h3>
+<p><code class="quikdown-code">bwcli serve</code> turns any language into a bwserve backend — send JSON protocol messages via HTTP POST or stdin, and connected browsers update in real time:</p><pre class="quikdown-pre"><code class="language-bash">bwcli serve --port 8080 --input-port 9000
+curl -X POST http://localhost:9000 -d &#39;{&quot;type&quot;:&quot;patch&quot;,&quot;target&quot;:&quot;temp&quot;,&quot;content&quot;:&quot;23.5 C&quot;}&#39;</code></pre><h2 class="quikdown-h2">Build Formats</h2>
 <table class="quikdown-table">
 <thead class="quikdown-thead">
 <tr class="quikdown-tr">
@@ -235,19 +263,30 @@ bitwrench doc.md -o doc.html --standalone --theme &quot;#336699,#cc6633&quot;</c
 </tr>
 </tbody>
 </table><p>All formats include source maps. A separate CSS file (<code class="quikdown-code">bitwrench.css</code>) is also available for use without JavaScript.</p><h2 class="quikdown-h2">Documentation</h2>
-<ul class="quikdown-ul">
-<li class="quikdown-li"><a class="quikdown-a" href="https://deftio.github.io/bitwrench/pages/" rel="noopener noreferrer">Interactive docs and demos</a> — full tutorial site with live examples</li>
+<strong class="quikdown-strong">Guides</strong> (in <code class="quikdown-code">docs/</code>):</p><ul class="quikdown-ul">
+<li class="quikdown-li"><a class="quikdown-a" href="docs/taco-format.md">TACO Format</a> — the <code class="quikdown-code">{t, a, c, o}</code> object format</li>
+<li class="quikdown-li"><a class="quikdown-a" href="docs/state-management.md">State Management</a> — three-level component model, ComponentHandle, reactive state</li>
+<li class="quikdown-li"><a class="quikdown-a" href="docs/component-library.md">Component Library</a> — all 50+ <code class="quikdown-code">make*()</code> functions with signatures and examples</li>
+<li class="quikdown-li"><a class="quikdown-a" href="docs/theming.md">Theming</a> — palette-driven theme generation, presets, design tokens</li>
+<li class="quikdown-li"><a class="quikdown-a" href="docs/cli.md">CLI</a> — the <code class="quikdown-code">bwcli</code> command for file conversion and pipe server</li>
+<li class="quikdown-li"><a class="quikdown-a" href="docs/bwserve.md">bwserve</a> — server-driven UI protocol (SSE, actions, embedded devices)</li>
+<li class="quikdown-li"><a class="quikdown-a" href="docs/llm-bitwrench-guide.md">LLM Guide</a> — compact single-file reference for AI-assisted development</li>
+</ul><p><strong class="quikdown-strong">Tutorials:</strong></p><ul class="quikdown-ul">
+<li class="quikdown-li"><a class="quikdown-a" href="docs/tutorial-website.md">Build a Website</a> — multi-section landing page from TACO objects</li>
+<li class="quikdown-li"><a class="quikdown-a" href="docs/tutorial-bwserve.md">bwserve Dashboard</a> — Streamlit-style server-push dashboard</li>
+<li class="quikdown-li"><a class="quikdown-a" href="docs/tutorial-embedded.md">ESP32 IoT Dashboard</a> — embedded sensor dashboard with C macros</li>
+</ul><p><strong class="quikdown-strong">Interactive demos</strong> (live site):</p><ul class="quikdown-ul">
 <li class="quikdown-li"><a class="quikdown-a" href="https://deftio.github.io/bitwrench/pages/00-quick-start.html" rel="noopener noreferrer">Quick Start</a> — first steps with <code class="quikdown-code">bw.DOM()</code></li>
 <li class="quikdown-li"><a class="quikdown-a" href="https://deftio.github.io/bitwrench/pages/01-components.html" rel="noopener noreferrer">Components</a> — buttons, cards, alerts, badges, navbars</li>
 <li class="quikdown-li"><a class="quikdown-a" href="https://deftio.github.io/bitwrench/pages/03-styling.html" rel="noopener noreferrer">Styling &amp; Theming</a> — CSS generation and theming strategies</li>
-<li class="quikdown-li"><a class="quikdown-a" href="https://deftio.github.io/bitwrench/pages/05-state.html" rel="noopener noreferrer">State &amp; Interactivity</a> — <code class="quikdown-code">bw.patch()</code>, <code class="quikdown-code">bw.update()</code>, pub/sub</li>
+<li class="quikdown-li"><a class="quikdown-a" href="https://deftio.github.io/bitwrench/pages/05-state.html" rel="noopener noreferrer">State &amp; Interactivity</a> — state patterns and ComponentHandle</li>
 <li class="quikdown-li"><a class="quikdown-a" href="https://deftio.github.io/bitwrench/pages/06-tic-tac-toe-tutorial.html" rel="noopener noreferrer">Tic Tac Toe Tutorial</a> — step-by-step game with state management</li>
 <li class="quikdown-li"><a class="quikdown-a" href="https://deftio.github.io/bitwrench/pages/07-framework-comparison.html" rel="noopener noreferrer">Framework Comparison</a> — bitwrench vs React, Vue, Svelte</li>
-<li class="quikdown-li"><a class="quikdown-a" href="https://deftio.github.io/bitwrench/pages/10-themes.html" rel="noopener noreferrer">Themes</a> — interactive theme generator with presets, dark mode, and CSS export</li>
+<li class="quikdown-li"><a class="quikdown-a" href="https://deftio.github.io/bitwrench/pages/10-themes.html" rel="noopener noreferrer">Themes</a> — interactive theme generator with presets and CSS export</li>
 </ul><h2 class="quikdown-h2">Development</h2>
 <p><pre class="quikdown-pre"><code class="language-bash">npm install          # install dev dependencies
 npm run build        # build all dist formats (UMD, ESM, CJS, ES5)
-npm test             # run unit tests (558 tests)
+npm test             # run unit tests (1000+ tests)
 npm run test:cli     # run CLI tests (49 tests)
 npm run test:e2e     # run Playwright browser tests
 npm run lint         # run ESLint

package/src/bitwrench-bccl-entry.js

@@ -0,0 +1,72 @@
+/**
+ * bitwrench-bccl-entry.js — Standalone entry point for BCCL component library.
+ *
+ * Use this alongside bitwrench-lean when you want the core library and
+ * BCCL components as separate files. The UMD build auto-registers all
+ * make*() functions onto the global `bw` object if present.
+ *
+ * Usage (browser):
+ *   <script src="bitwrench-lean.umd.min.js"></script>
+ *   <script src="bitwrench-bccl.umd.min.js"></script>
+ *
+ * Usage (ESM):
+ *   import bw from 'bitwrench/lean';
+ *   import { registerBCCL } from 'bitwrench/bccl';
+ *   registerBCCL(bw);
+ *
+ * @module bitwrench-bccl
+ * @license BSD-2-Clause
+ */
+
+import * as components from './bitwrench-bccl.js';
+
+/**
+ * Register all BCCL components onto a bitwrench instance.
+ * Called automatically in UMD builds when `bw` is a global.
+ *
+ * @param {Object} bw - The bitwrench instance to register on
+ */
+export function registerBCCL(bw) {
+  if (!bw) return;
+
+  // Register all make* functions
+  Object.entries(components).forEach(function(entry) {
+    var name = entry[0], fn = entry[1];
+    if (name.indexOf('make') === 0) {
+      bw[name] = fn;
+    }
+  });
+
+  // Factory dispatch: bw.make('card', props) → bw.makeCard(props)
+  bw.make = components.make;
+
+  // Component registry
+  bw.BCCL = components.BCCL;
+
+  // Variant class helper
+  bw.variantClass = components.variantClass;
+
+  // Create functions that return handles
+  if (typeof bw.renderComponent === 'function') {
+    Object.entries(components).forEach(function(entry) {
+      var name = entry[0], fn = entry[1];
+      if (name.indexOf('make') === 0) {
+        var createName = 'create' + name.substring(4);
+        bw[createName] = function(props) {
+          var taco = fn(props);
+          return bw.renderComponent(taco);
+        };
+      }
+    });
+  }
+}
+
+// Re-export all components for direct import
+export { BCCL, make, variantClass } from './bitwrench-bccl.js';
+
+// UMD auto-registration: if `bw` exists as a global, register automatically
+if (typeof window !== 'undefined' && typeof window.bw !== 'undefined') {
+  registerBCCL(window.bw);
+} else if (typeof globalThis !== 'undefined' && typeof globalThis.bw !== 'undefined') {
+  registerBCCL(globalThis.bw);
+}

package/src/bitwrench-bccl.js

@@ -3610,5 +3610,9 @@ export var BCCL = {
 export function make(type, props) {
   var def = BCCL[type];
   if (!def) throw new Error('bw.make: unknown component type "' + type + '". Available: ' + Object.keys(BCCL).join(', '));
-  return def.make(props || {});
+  var taco = def.make(props || {});
+  if (taco && typeof taco === 'object') {
+    taco._bwFactory = { type: type, props: props || {} };
+  }
+  return taco;
 }

package/src/bitwrench-code-edit.js

@@ -4,6 +4,13 @@
  * Provides bw.highlight() for tokenizing JS/CSS/HTML into TACO spans,
  * and bw.codeEditor() for a live editable code block with syntax coloring.
  *
+ * Theme integration: The editor chrome (background, text color, font) reads
+ * from CSS custom properties --bw_code_bg, --bw_code_text, --bw_font_mono,
+ * falling back to built-in dark values when no theme is active. Syntax
+ * highlighting colors are intentionally fixed (they are a code color scheme,
+ * not brand colors). The bw_ce_light class is still supported for manual
+ * light-mode override.
+ *
  * Can be loaded standalone (browser script tag after bitwrench.umd.js),
  * or imported as an ES module / CJS module.
  *
@@ -14,9 +21,9 @@
 // -- CSS (injected once) ----------------------------------------------
 var _cssInjected = false;
 var CSS_TEXT =
-  '.bw_ce{background:#1e293b;border-radius:6px;border:1px solid rgba(255,255,255,0.08);overflow:auto}' +
+  '.bw_ce{background:var(--bw_code_bg,#1e293b);border-radius:6px;border:1px solid rgba(255,255,255,0.08);overflow:auto}' +
   '.bw_ce pre{margin:0;padding:0}' +
-  '.bw_ce code{font-family:"SF Mono",Monaco,"Cascadia Code",Consolas,monospace;font-size:0.875rem;line-height:1.6;color:#e2e8f0;outline:none;white-space:pre-wrap;display:block;padding:0.75rem 1rem}' +
+  '.bw_ce code{font-family:var(--bw_font_mono,"SF Mono",Monaco,"Cascadia Code",Consolas,monospace);font-size:0.875rem;line-height:1.6;color:var(--bw_code_text,#e2e8f0);outline:none;white-space:pre-wrap;display:block;padding:0.75rem 1rem}' +
   '.bw_ce code:empty::before{content:"\\200b"}' +
   '.bw_ce .bw_ce_keyword{color:#c792ea}' +
   '.bw_ce .bw_ce_string{color:#c3e88d}' +
@@ -54,7 +61,12 @@ var CSS_TEXT =
   '.bw_ce_light.bw_ce .bw_ce_css_value{color:#ea580c}' +
   '.bw_ce_light.bw_ce .bw_ce_at_rule{color:#7c3aed}' +
   '.bw_ce_light.bw_ce .bw_ce_color{color:#ea580c}' +
-  '.bw_ce_light.bw_ce .bw_ce_template_interp{color:#0891b2}';
+  '.bw_ce_light.bw_ce .bw_ce_template_interp{color:#0891b2}' +
+  // Line number gutter (opt-in via lineNumbers option)
+  '.bw_ce_wrap{display:flex;flex-direction:row}' +
+  '.bw_ce_gutter{flex:0 0 auto;padding:0.75rem 0;text-align:right;user-select:none;-webkit-user-select:none;color:#546e7a;font-family:var(--bw_font_mono,"SF Mono",Monaco,"Cascadia Code",Consolas,monospace);font-size:0.875rem;line-height:1.6;border-right:1px solid rgba(255,255,255,0.08);overflow:hidden}' +
+  '.bw_ce_gutter span{display:block;padding:0 0.5rem 0 0.75rem}' +
+  '.bw_ce_light .bw_ce_gutter{color:#9ca3af;border-right-color:#d8d8d8}';
 
 function ensureCSS(bw) {
   if (_cssInjected) return;
@@ -537,6 +549,7 @@ function codeEditor(opts) {
   var lang = opts.lang || 'js';
   var height = opts.height || '180px';
   var readOnly = !!opts.readOnly;
+  var showLineNumbers = !!opts.lineNumbers;
   var className = 'bw_ce' + (opts.className ? ' ' + opts.className : '');
 
   var highlighted = highlight(code, lang);
@@ -549,12 +562,26 @@ function codeEditor(opts) {
     codeAttrs.contenteditable = 'true';
   }
 
+  // Build line number gutter TACO if requested
+  var gutterTaco = null;
+  if (showLineNumbers) {
+    var lineCount = (code.match(/\n/g) || []).length + 1;
+    var gutterLines = [];
+    for (var li = 1; li <= lineCount; li++) {
+      gutterLines.push({ t: 'span', c: String(li) });
+    }
+    gutterTaco = { t: 'div', a: { class: 'bw_ce_gutter' }, c: gutterLines };
+  }
+
+  var preBlock = { t: 'pre', a: { style: 'flex:1;min-width:0;margin:0' }, c: { t: 'code', a: codeAttrs, c: highlighted } };
+  var innerContent = showLineNumbers
+    ? { t: 'div', a: { class: 'bw_ce_wrap' }, c: [gutterTaco, preBlock] }
+    : preBlock;
+
   return {
     t: 'div',
     a: { class: className, style: 'max-height:' + height + ';overflow:auto' },
-    c: [
-      { t: 'pre', c: { t: 'code', a: codeAttrs, c: highlighted } }
-    ],
+    c: [innerContent],
     o: {
       mounted: function(el) {
         var codeEl = el.querySelector('.bw_ce_code');
@@ -562,21 +589,43 @@ function codeEditor(opts) {
 
         var currentCode = code;
         var debounceTimer = null;
+        var gutterEl = showLineNumbers ? el.querySelector('.bw_ce_gutter') : null;
 
         // Resolve bw from global or import context
         var bw = (typeof window !== 'undefined' && window.bw) || {};
 
         function getValue() { return codeEl.textContent || ''; }
 
+        function updateGutter(text) {
+          if (!gutterEl) return;
+          var count = (text.match(/\n/g) || []).length + 1;
+          var html = '';
+          for (var i = 1; i <= count; i++) html += '<span>' + i + '</span>';
+          gutterEl.innerHTML = html;
+        }
+
         function setValue(newCode) {
           currentCode = newCode;
           var tacos = highlight(newCode, lang);
           if (bw.html) codeEl.innerHTML = bw.html({ t: 'span', c: tacos });
+          updateGutter(newCode);
         }
 
         // Expose API on the element
         el._bwCodeEdit = { getValue: getValue, setValue: setValue };
 
+        // Scroll sync: keep gutter aligned with code
+        if (gutterEl) {
+          var scrollParent = codeEl.closest('.bw_ce') || el;
+          scrollParent.addEventListener('scroll', function() {
+            gutterEl.style.transform = 'translateY(' + (-scrollParent.scrollTop) + 'px)';
+          });
+          // If the outer .bw_ce has overflow, sync from there
+          el.addEventListener('scroll', function() {
+            gutterEl.style.transform = 'translateY(' + (-el.scrollTop) + 'px)';
+          });
+        }
+
         if (readOnly) return;
 
         function rehighlight() {
@@ -587,6 +636,7 @@ function codeEditor(opts) {
           var tacos = highlight(newCode, lang);
           if (bw.html) codeEl.innerHTML = bw.html({ t: 'span', c: tacos });
           setCaretOffset(codeEl, offset);
+          updateGutter(newCode);
           if (opts.onChange) opts.onChange(newCode);
         }
 

package/src/bitwrench-color-utils.js

@@ -413,12 +413,11 @@ export function derivePalette(config) {
   var lightBase = config.light || hslToHex([h, 8, 97]);
   var darkBase  = config.dark  || hslToHex([h, 10, 13]);
 
-  // Background & surface tokens — default to light (white/near-white).
-  // Dark backgrounds require explicit config.background / config.surface.
-  // Primary/secondary colors are accents, not page backgrounds, so
-  // isLightPalette should NOT drive bg/surface defaults.
-  var bgBase = config.background || '#ffffff';
-  var surfBase = config.surface || '#f8f9fa';
+  // Background & surface tokens — tinted with primary hue for theme personality.
+  // Very subtle: bg at L=98/S=6, surface at L=96/S=8.
+  // User can override with config.background / config.surface.
+  var bgBase = config.background || hslToHex([h, 6, 98]);
+  var surfBase = config.surface || hslToHex([h, 8, 96]);
 
   var palette = {
     primary:    deriveShades(config.primary),

package/src/bitwrench-styles.js

@@ -1119,7 +1119,7 @@ var structuralRules = {
     '@media (min-width: 992px)': { '.bw_container': { 'max-width': '960px' } },
     '@media (min-width: 1200px)': { '.bw_container': { 'max-width': '1140px' } },
     '.bw_container_fluid': {
-      'width': '100%', 'padding-right': '15px', 'padding-left': '15px',
+      'width': '100%', 'padding-right': '0.75rem', 'padding-left': '0.75rem',
       'margin-right': 'auto', 'margin-left': 'auto'
     },
     '.bw_row': {
@@ -1280,7 +1280,8 @@ var structuralRules = {
     '.bw_badge': {
       'display': 'inline-block', 'font-size': '0.875rem',
       'font-weight': '600', 'line-height': '1.3', 'text-align': 'center',
-      'white-space': 'nowrap', 'vertical-align': 'baseline'
+      'white-space': 'nowrap', 'vertical-align': 'baseline',
+      'padding': '0.35rem 0.65rem', 'border-radius': '0.25rem'
     },
     '.bw_badge:empty': { 'display': 'none' },
     '.bw_badge_sm': { 'font-size': '0.75rem', 'padding': '0.25rem 0.5rem' },
@@ -1465,7 +1466,7 @@ var structuralRules = {
   // ---- Code demo ----
   codeDemo: {
     '.bw_code_demo': { 'margin-bottom': '2rem' },
-    '.bw_code_pre': { 'margin': '0', 'border': 'none', 'overflow-x': 'auto' },
+    '.bw_code_pre': { 'margin': '0', 'border': 'none', 'overflow-x': 'auto', 'max-width': '100%' },
     '.bw_code_block': {
       'display': 'block', 'padding': '1.25rem',
       'font-family': '"SF Mono", Monaco, "Cascadia Code", "Roboto Mono", Consolas, "Courier New", monospace',
@@ -1562,7 +1563,7 @@ var structuralRules = {
     },
     '.bw_modal.bw_modal_show': { 'opacity': '1', 'visibility': 'visible', 'pointer-events': 'auto' },
     '.bw_modal_dialog': {
-      'position': 'relative', 'width': '100%', 'max-width': '500px', 'margin': '1.75rem auto',
+      'position': 'relative', 'width': 'calc(100% - 1rem)', 'max-width': '500px', 'margin': '1.75rem auto',
       'pointer-events': 'none'
     },
     '.bw_modal.bw_modal_show .bw_modal_dialog': { 'transform': 'translateY(0)' },
@@ -1592,7 +1593,7 @@ var structuralRules = {
     '.bw_toast_container.bw_toast_top_center': { 'top': '0', 'left': '50%', 'transform': 'translateX(-50%)' },
     '.bw_toast_container.bw_toast_bottom_center': { 'bottom': '0', 'left': '50%', 'transform': 'translateX(-50%)' },
     '.bw_toast': {
-      'pointer-events': 'auto', 'width': '350px', 'max-width': '100%', 'background-clip': 'padding-box',
+      'pointer-events': 'auto', 'width': '350px', 'max-width': 'calc(100vw - 2rem)', 'background-clip': 'padding-box',
       'opacity': '0'
     },
     '.bw_toast.bw_toast_show': { 'opacity': '1', 'transform': 'translateY(0)' },
@@ -1678,7 +1679,7 @@ var structuralRules = {
     '.bw_tooltip_wrapper': { 'position': 'relative', 'display': 'inline-block' },
     '.bw_tooltip': {
       'position': 'absolute', 'z-index': '999',
-      'font-size': '0.875rem', 'white-space': 'nowrap', 'pointer-events': 'none',
+      'font-size': '0.875rem', 'white-space': 'nowrap', 'max-width': 'min(300px, calc(100vw - 1rem))', 'pointer-events': 'none',
       'opacity': '0', 'visibility': 'hidden'
     },
     '.bw_tooltip.bw_tooltip_show': { 'opacity': '1', 'visibility': 'visible' },
@@ -1698,7 +1699,7 @@ var structuralRules = {
     '.bw_popover_trigger': { 'cursor': 'pointer' },
     '.bw_popover': {
       'position': 'absolute', 'z-index': '1000',
-      'min-width': '200px', 'max-width': '320px',
+      'min-width': '200px', 'max-width': 'min(320px, calc(100vw - 2rem))',
       'pointer-events': 'none', 'opacity': '0', 'visibility': 'hidden'
     },
     '.bw_popover.bw_popover_show': { 'opacity': '1', 'visibility': 'visible', 'pointer-events': 'auto' },
@@ -1881,7 +1882,18 @@ var structuralRules = {
       '.bw_hero, .bw_hero': { 'padding': '2rem 1rem' },
       '.bw_cta_actions, .bw_cta-actions': { 'flex-direction': 'column' },
       '.bw_hstack, .bw_hstack': { 'flex-direction': 'column' },
-      '.bw_feature_grid, .bw_feature-grid': { 'grid-template-columns': '1fr' }
+      '.bw_feature_grid, .bw_feature-grid': { 'grid-template-columns': '1fr' },
+      '.bw_modal_dialog': { 'margin': '0.5rem auto' },
+      '.bw_modal_lg': { 'max-width': 'calc(100% - 1rem)' },
+      '.bw_modal_xl': { 'max-width': 'calc(100% - 1rem)' },
+      '.bw_navbar': { 'padding': '0.5rem 0.75rem' },
+      '.bw_navbar_brand': { 'margin-right': '0.5rem', 'font-size': '1rem' },
+      '.bw_navbar_nav': { 'flex-wrap': 'wrap' },
+      '.bw_tooltip': { 'white-space': 'normal' },
+      '.bw_table': { 'display': 'block', 'overflow-x': 'auto', '-webkit-overflow-scrolling': 'touch' },
+      '.bw_col, .bw_col_1, .bw_col_2, .bw_col_3, .bw_col_4, .bw_col_5, .bw_col_6, .bw_col_7, .bw_col_8, .bw_col_9, .bw_col_10, .bw_col_11, .bw_col_12': { 'flex': '0 0 100%', 'max-width': '100%' },
+      '.bw_container': { 'padding-right': '0.5rem', 'padding-left': '0.5rem' },
+      '.bw_container_fluid': { 'padding-right': '0.5rem', 'padding-left': '0.5rem' }
     }
   }
 };