bitwrench 2.0.15 → 2.0.17

package/README.md

@@ -54,7 +54,8 @@ Or include directly in a page:
 - **Built-in reactivity** — `bw.update()` re-renders components when state changes, `bw.patch()` updates individual elements by ID, `bw.pub()`/`bw.sub()` provides decoupled messaging between any part of the application
 - **CSS and theme generation** — `bw.css()` generates stylesheets from objects, `bw.generateTheme()` derives a complete visual theme (buttons, alerts, badges, cards, forms, tables, dark mode) from 2-3 seed colors
 - **45+ ready-made components** — 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
-- **Static site CLI** — the `bitwrench` command converts Markdown, HTML, and JSON files into styled, self-contained pages with theme support
+- **Server-driven UI (bwserve)** — 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 `bwcli serve` pipe server
+- **Static site CLI** — the `bwcli` command converts Markdown, HTML, and JSON files into styled, self-contained pages with theme support
 - **Utilities** — color interpolation, random data generation, lorem ipsum, cookies, URL params, file I/O for both browser and Node.js
 
 ## Getting Started
@@ -88,28 +89,31 @@ Or include directly in a page:
 
 ## Adding State
 
-The `o` key adds state and a render function to any element. When state changes, call `bw.update()` to re-render:
+Wrap any TACO in `bw.component()` to get a reactive component with `.get()`, `.set()`, and template bindings:
 
 ```javascript
-bw.DOM('#counter', {
-  t: 'div',
+var counter = bw.component({
+  t: 'div', c: [
+    { t: 'span', c: 'Count: ${count}' },
+    { t: 'button', c: '+1', a: {
+      onclick: function() { counter.set('count', counter.get('count') + 1); }
+    }}
+  ],
   o: {
     state: { count: 0 },
-    render: function(el) {
-      var s = el._bw_state;
-      bw.DOM(el, {
-        t: 'div', c: [
-          { t: 'span', c: 'Count: ' + s.count },
-          { t: 'button', a: {
-            onclick: function() { s.count++; bw.update(el); }
-          }, c: '+1' }
-        ]
-      });
+    methods: {
+      reset: function(comp) { comp.set('count', 0); }
     }
   }
 });
+
+bw.DOM('#app', counter);
+counter.set('count', 42);   // DOM updates automatically
+counter.reset();             // methods from o.methods are callable on the handle
 ```
 
+For low-level control, you can also use `o.render` + `bw.update()` directly — see the [State Management guide](docs/state-management.md).
+
 For communication between components, use pub/sub:
 
 ```javascript
@@ -139,13 +143,19 @@ bw.toggleTheme();  // switch between primary and alternate palettes
 |---|---|
 | `bw.html(obj)` | Convert an object to an HTML string |
 | `bw.DOM(selector, obj)` | Mount an object to a DOM element |
+| `bw.component(taco)` | Wrap a TACO in a ComponentHandle with `.get()/.set()` reactive API |
 | `bw.css(rules)` | Generate CSS from a JS object |
 | `bw.loadDefaultStyles()` | Inject the built-in stylesheet |
 | `bw.generateTheme(name, config)` | Generate a scoped theme from seed colors |
 | `bw.patch(id, content)` | Update a specific element by UUID |
 | `bw.update(el)` | Re-render via the element's `o.render` function |
+| `bw.message(target, action, data)` | Send a message to a component by tag name |
 | `bw.pub(topic, detail)` | Publish a message to subscribers |
 | `bw.sub(topic, handler)` | Subscribe to a topic; returns an unsub function |
+| `bw.inspect(target)` | Debug a component in the browser console |
+| `bw.clientConnect(url, opts)` | Connect to a bwserve SSE endpoint |
+| `bw.clientApply(msg)` | Apply a bwserve protocol message to the DOM |
+| `bw.clientParse(str)` | Parse strict or r-prefix relaxed JSON |
 
 See the full [API Reference](https://deftio.github.io/bitwrench/pages/08-api-reference.html) for all functions.
 
@@ -155,17 +165,26 @@ Convert Markdown, HTML, or JSON files to styled standalone pages:
 
 ```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 "#336699,#cc6633"
+bwcli doc.md -o doc.html --standalone --theme "#336699,#cc6633"
 ```
 
 Flags: `--output/-o`, `--standalone/-s`, `--cdn`, `--theme/-t`, `--css/-c`, `--title`, `--favicon/-f`, `--highlight`, `--verbose/-v`
 
+### Pipe Server
+
+`bwcli serve` turns any language into a bwserve backend — send JSON protocol messages via HTTP POST or stdin, and connected browsers update in real time:
+
+```bash
+bwcli serve --port 8080 --input-port 9000
+curl -X POST http://localhost:9000 -d '{"type":"patch","target":"temp","content":"23.5 C"}'
+```
+
 ## Build Formats
 
 | Format | File | Use case |
@@ -179,21 +198,38 @@ All formats include source maps. A separate CSS file (`bitwrench.css`) is also a
 
 ## Documentation
 
-- [Interactive docs and demos](https://deftio.github.io/bitwrench/pages/) — full tutorial site with live examples
+**Guides** (in `docs/`):
+
+- [TACO Format](docs/taco-format.md) — the `{t, a, c, o}` object format
+- [State Management](docs/state-management.md) — three-level component model, ComponentHandle, reactive state
+- [Component Library](docs/component-library.md) — all 50+ `make*()` functions with signatures and examples
+- [Theming](docs/theming.md) — palette-driven theme generation, presets, design tokens
+- [CLI](docs/cli.md) — the `bwcli` command for file conversion and pipe server
+- [bwserve](docs/bwserve.md) — server-driven UI protocol (SSE, actions, embedded devices)
+- [LLM Guide](docs/llm-bitwrench-guide.md) — compact single-file reference for AI-assisted development
+
+**Tutorials:**
+
+- [Build a Website](docs/tutorial-website.md) — multi-section landing page from TACO objects
+- [bwserve Dashboard](docs/tutorial-bwserve.md) — Streamlit-style server-push dashboard
+- [ESP32 IoT Dashboard](docs/tutorial-embedded.md) — embedded sensor dashboard with C macros
+
+**Interactive demos** (live site):
+
 - [Quick Start](https://deftio.github.io/bitwrench/pages/00-quick-start.html) — first steps with `bw.DOM()`
 - [Components](https://deftio.github.io/bitwrench/pages/01-components.html) — buttons, cards, alerts, badges, navbars
 - [Styling & Theming](https://deftio.github.io/bitwrench/pages/03-styling.html) — CSS generation and theming strategies
-- [State & Interactivity](https://deftio.github.io/bitwrench/pages/05-state.html) — `bw.patch()`, `bw.update()`, pub/sub
+- [State & Interactivity](https://deftio.github.io/bitwrench/pages/05-state.html) — state patterns and ComponentHandle
 - [Tic Tac Toe Tutorial](https://deftio.github.io/bitwrench/pages/06-tic-tac-toe-tutorial.html) — step-by-step game with state management
 - [Framework Comparison](https://deftio.github.io/bitwrench/pages/07-framework-comparison.html) — bitwrench vs React, Vue, Svelte
-- [Themes](https://deftio.github.io/bitwrench/pages/10-themes.html) — interactive theme generator with presets, dark mode, and CSS export
+- [Themes](https://deftio.github.io/bitwrench/pages/10-themes.html) — interactive theme generator with presets and CSS export
 
 ## Development
 
 ```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