bitwrench 2.0.25 → 2.0.30

package/docs/bitwrench_api.md

@@ -4,27 +4,29 @@
 
 | Field | Value |
 |-------|-------|
-| Version | 2.0.25 |
-| Generated | 2026-03-31 |
-| Total APIs | 100 |
-| Categories | 12 |
-| bitwrench.js | 3631 lines |
+| Version | 2.0.30 |
+| Generated | 2026-04-12 |
+| Total APIs | 105 |
+| Categories | 14 |
+| bitwrench.js | 4100 lines |
 | bitwrench-bccl.js | 3793 lines |
 
 ## Table of Contents
 
 - [Core](#core) (5)
 - [DOM Generation](#dom-generation) (10)
+- [DOM Selection](#dom-selection) (1)
 - [Identifiers](#identifiers) (4)
 - [State Management](#state-management) (3)
 - [Events (DOM)](#events-dom-) (2)
-- [Pub/Sub](#pub-sub) (3)
+- [Pub/Sub](#pub-sub) (4)
 - [CSS & Styling](#css-styling) (10)
 - [Component Builders](#component-builders) (50)
 - [Browser Utilities](#browser-utilities) (4)
 - [Utilities](#utilities) (1)
 - [Function Registry](#function-registry) (5)
-- [Component](#component) (3)
+- [Component](#component) (5)
+- [Data Utilities](#data-utilities) (1)
 
 ---
 
@@ -293,6 +295,28 @@ Get all registered component handles as a Map.
 
 ---
 
+## DOM Selection
+
+### `bw.el(target, apply)`
+
+Look up a single DOM element by ID, CSS selector, UUID, or element ref. Optionally apply content or a function to the resolved element. Resolution order for string targets: 1. Check `bw._nodeMap[id]` cache (O(1), stale entries auto-pruned) 2. `document.getElementById(id)` 3. `document.querySelector(id)` for selectors starting with # or . 4. Class-based lookup for `bw_uuid_*` tokens With one argument, returns the element (or null). With two arguments, applies the second argument to the element and returns the element: - string/number: sets `el.textContent` - function: calls `apply(el)`, returns el - TACO object: clears children, mounts TACO via `bw.createDOM()` - array: clears children, appends each item (string -> text node, TACO -> element)
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `target` | `string|Element` | - Element ref, ID, CSS selector, or bw_uuid_* class |
+| `apply` | `string|number|Function|Object|Array` | - Content or function to apply |
+
+**Returns:** `Element|null` — DOM element, or null if not found
+
+**Example:**
+```javascript
+bw.el('#title')                         // lookup bw.el('#title', 'Hello')                // set text content bw.el('#app', { t: 'h1', c: 'Hi' })    // mount TACO bw.el('.card', function(el) {           // apply function el.style.opacity = '0.5'; })
+```
+
+---
+
 ## Identifiers
 
 ### `bw.uuid(prefix)`
@@ -488,32 +512,32 @@ Publish to a topic, calling all subscribers in registration order. Application-s
 | `topic` | `string` | - Topic name (plain string, no prefix) |
 | `detail` | `*` | - Data to pass to subscribers |
 
-**Returns:** `number` — of successfully called subscribers
+**Returns:** `number` — of successfully called subscribers (including wildcard matches)
 
 **Example:**
 ```javascript
-bw.pub('score:updated', { player: 'X', score: 10 });
+bw.pub('score:updated', { player: 'X', score: 10 }); // Wildcard subscribers matching 'score:*' will also fire
 ```
 
 ---
 
 ### `bw.sub(topic, handler, el)`
 
-Subscribe to a topic. Returns an unsub() function. Optional third argument ties the subscription to a DOM element's lifecycle — when `bw.cleanup()` is called on that element, the subscription is automatically removed, preventing memory leaks.
+Subscribe to a topic. Returns an unsub() function. Supports wildcard patterns: a topic ending in `*` matches any published topic that starts with the prefix before the `*`. For example, `'agui:*'` matches `'agui:ready'`, `'agui:error'`, etc. The handler receives `(detail, topic)` so it can distinguish which topic fired. Optional third argument ties the subscription to a DOM element's lifecycle -- when `bw.cleanup()` is called on that element, the subscription is automatically removed, preventing memory leaks.
 
 **Parameters:**
 
 | Name | Type | Description |
 |------|------|-------------|
-| `topic` | `string` | - Topic name |
-| `handler` | `Function` | - Called with (detail) on each publish |
+| `topic` | `string` | - Topic name, or wildcard pattern ending in '*' |
+| `handler` | `Function` | - Called with (detail, topic) on each publish |
 | `el` | `Element` | - Optional DOM element to tie lifecycle to |
 
 **Returns:** `Function` — to unsubscribe
 
 **Example:**
 ```javascript
-var unsub = bw.sub('score:updated', function(detail) { console.log(detail.player, 'scored', detail.score); }); // Later: unsub() to stop listening
+var unsub = bw.sub('score:updated', function(detail) { console.log(detail.player, 'scored', detail.score); }); // Later: unsub() to stop listening // Wildcard: listen to all 'agui:' topics bw.sub('agui:*', function(detail, topic) { console.log('Got', topic, detail); });
 ```
 
 ---
@@ -533,6 +557,27 @@ Unsubscribe a handler by reference from a topic. Removes ALL instances of the gi
 
 ---
 
+### `bw.once(topic, handler, el)`
+
+Subscribe to a topic for a single event only. The subscription is automatically removed after the first publish. Equivalent to manually calling unsub() inside a bw.sub() handler, but avoids the common bug of forgetting to unsubscribe.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `topic` | `string` | - Topic name |
+| `handler` | `Function` | - Called once with (detail) on the next publish |
+| `el` | `Element` | - Optional DOM element to tie lifecycle to |
+
+**Returns:** `Function` — to cancel the subscription before it fires
+
+**Example:**
+```javascript
+bw.once('data:loaded', function(detail) { console.log('Received:', detail); // No need to unsubscribe -- already done automatically }); // Cancel before it fires: var cancel = bw.once('timeout', handler); cancel(); // handler will never be called
+```
+
+---
+
 ## CSS & Styling
 
 ### `bw.css(rules, options = {})`
@@ -694,21 +739,21 @@ bw.loadReset();  // inject once, safe to call multiple times
 
 ---
 
-### `bw.toggleStyles(scope)`
+### `bw.toggleThemeMode(scope)`
 
-Toggle between primary and alternate palettes. Adds/removes the `bw_theme_alt` class on the scoping element. Without a scope, toggles on `<html>` (global). With a scope, toggles on the first matching element.
+Toggle between primary and alternate theme palettes. Adds/removes the `bw_theme_alt` class on the scoping element(s). Without a scope, toggles on `<html>` (global). With a scope, toggles on ALL matching elements.
 
 **Parameters:**
 
 | Name | Type | Description |
 |------|------|-------------|
-| `scope` | `string` | - Scope selector (e.g. '#my-dashboard'). Omit for global. |
+| `scope` | `string|Element` | - Selector or element. Omit for global. |
 
-**Returns:** `string` — mode after toggle: 'primary' or 'alternate'
+**Returns:** `string` — mode after toggle: 'primary' or 'alternate' (based on first element)
 
 **Example:**
 ```javascript
-bw.toggleStyles();                   // global toggle on <html> bw.toggleStyles('#my-dashboard');    // scoped toggle
+bw.toggleThemeMode();                   // global toggle on <html> bw.toggleThemeMode('#my-dashboard');    // scoped toggle bw.toggleThemeMode('.panel');           // toggle on ALL .panel elements
 ```
 
 ---
@@ -2212,21 +2257,86 @@ bw.message('my_carousel', 'goToSlide', 2); // Or from SSE handler: es.onmessage
 
 ---
 
-### `bw.inspect(target)`
+### `bw.formData(target)`
+
+Collect form data from all input, select, and textarea elements within a container. Each element's `name` attribute (or `id` if no name) becomes a key in the returned object. This provides a lightweight alternative to the browser FormData API that returns a plain object suitable for JSON serialization or bw.pub(). Handles all standard HTML form controls: - text/number/email/etc inputs: string value - checkboxes: boolean (true/false) - radio buttons: string value of the checked radio (unchecked groups omitted) - multi-select: array of selected option values - textarea: string value Elements without both `name` and `id` attributes are silently skipped.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `target` | `string|Element` | - CSS selector, UUID string, or DOM element |
+
+**Returns:** `Object` — object mapping field names to values
+
+**Example:**
+```javascript
+// Given a form with name="email" input and name="agree" checkbox: var data = bw.formData('#signup-form'); // => { email: 'user@example.com', agree: true } // Collect and publish in one step: bw.pub('form:submit', bw.formData('#my-form')); // Works with any container, not just <form>: bw.pub('settings:changed', bw.formData('.settings-panel'));
+```
+
+---
+
+### `bw.inspect(target, depth)`
+
+Inspect a DOM element and its subtree, returning a plain-object representation with bitwrench metadata at each node. Useful for debugging, devtools, MCP/AG-UI tool discovery, and automated testing. Each node in the returned tree includes: - `tag` -- lowercase tag name (or '#text' for text nodes) - `id` -- element id (if set) - `uuid` -- bitwrench UUID class (if lifecycle-managed) - `type` -- component type from o.type (if set, e.g. 'card', 'tabs') - `classes` -- first 5 CSS classes (string, space-separated) - `handles` -- array of el.bw method names (if any) - `state` -- copy of _bw_state (if any) - `hasRender` -- true if _bw_render is set - `hasSubs` -- true if element has pub/sub subscriptions - `refs` -- copy of _bw_refs keys (if any) - `children` -- array of child node trees (up to depth limit, max 50 per level)
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `target` | `string|Element` | - CSS selector, UUID, or DOM element |
+| `depth` | `number` | - Maximum recursion depth (0 = target only, no children) |
+
+**Returns:** `Object|null` — object tree, or null if element not found
+
+**Example:**
+```javascript
+// Get full tree from #app, 3 levels deep (default): var info = bw.inspect('#app'); // Shallow inspection (just the element, no children): var info = bw.inspect('#my-carousel', 0); console.log(info.handles); // ['next', 'prev', 'goToSlide'] console.log(info.type);    // 'carousel' // Deep inspection for debugging: console.log(JSON.stringify(bw.inspect('#app', 5), null, 2));
+```
+
+---
+
+### `bw.catalog(type)`
+
+Query the BCCL component registry. Returns metadata about registered component types -- their names and factory function names. Useful for tooling, introspection, documentation generators, and auto-complete systems (including MCP/AG-UI tool discovery). With no arguments, returns an array of all registered component types. With a type name, returns metadata for that single type (or null if the type is not registered).
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `type` | `string` | - Optional component type name to look up |
+
+**Returns:** `Array<Object>|Object|null` — of {type, factory} objects, a single {type, factory} object, or null if the type is not found
+
+**Example:**
+```javascript
+// List all available component types: bw.catalog(); // => [{ type: 'card', factory: 'makeCard' }, //     { type: 'button', factory: 'makeButton' }, ...] // Look up a specific type: bw.catalog('accordion'); // => { type: 'accordion', factory: 'makeAccordion' } // Check if a type exists: if (bw.catalog('chart')) { ... } // Get just the type names: bw.catalog().map(function(c) { return c.type; }); // => ['card', 'button', 'container', 'row', ...]
+```
+
+---
+
+## Data Utilities
+
+### `bw.jsonPatch(obj, ops)`
 
-Inspect a DOM element's bitwrench state, handle methods, and metadata. Works with DOM elements or CSS selectors.
+Apply RFC 6902 JSON Patch operations to a plain object. Supported operations: add, remove, replace, move, copy, test. Paths use JSON Pointer (RFC 6901) notation: `/foo/bar/0`. Mutates the target object in place and returns it.
 
 **Parameters:**
 
 | Name | Type | Description |
 |------|------|-------------|
-| `target` | `string|Element` | - Selector or DOM element |
+| `obj` | `Object` | - Target object to patch |
+| `ops` | `Array<Object>` | - Array of patch operations |
+| `ops[].op` | `string` | - Operation: 'add', 'remove', 'replace', 'move', 'copy', 'test' |
+| `ops[].path` | `string` | - JSON Pointer path (e.g. '/a/b/0') |
+| `ops[].value` | `*` | - Value for add/replace/test |
+| `ops[].from` | `string` | - Source path for move/copy |
 
-**Returns:** `Element|null` — element, or null if not found
+**Returns:** `Object` — patched object (same reference)
 
 **Example:**
 ```javascript
-bw.inspect('#my-carousel'); bw.inspect($0);
+var obj = { a: 1, b: { c: 2 } }; bw.jsonPatch(obj, [ { op: 'replace', path: '/a', value: 10 }, { op: 'add', path: '/b/d', value: 3 }, { op: 'remove', path: '/b/c' } ]); // obj => { a: 10, b: { d: 3 } }
 ```
 
 ---

package/docs/llm-bitwrench-guide.md

@@ -406,7 +406,7 @@ card.bw.setContent({ t: 'b', c: '$42k' });
 var el = bw.$('#app')[0];
 el._bw_state;         // current state
 el._bw_render;        // render function
-bw.inspect(el);       // formatted debug output (el.bw methods, state, classes)
+bw.inspect(el, 0);       // introspect element (state, handles, type, classes)
 ```
 
 ### bwcli attach -- remote debugging REPL
@@ -612,13 +612,14 @@ bwcli serve                                   # dev server (port 7902)
 | `bw.mount(sel, taco)` | Mount + return root element |
 | `bw.cleanup(el)` | Run unmount hooks, clear subscriptions |
 | `bw.patch(id, content)` | Update element by id or UUID |
-| `bw.inspect(el)` | Debug: log el.bw methods, state, classes |
+| `bw.inspect(el, depth)` | Introspect DOM subtree with bitwrench metadata |
 
 ### Communication
 | Function | Description |
 |----------|-------------|
-| `bw.pub(topic, data)` | App-wide publish |
-| `bw.sub(topic, fn, el?)` | Subscribe (optional lifecycle tie to element) |
+| `bw.pub(topic, data)` | App-wide publish (fires exact + wildcard matches) |
+| `bw.sub(topic, fn, el?)` | Subscribe (supports wildcard `'ns:*'`; optional lifecycle tie) |
+| `bw.once(topic, fn, el?)` | One-shot subscribe (auto-unsub after first fire) |
 | `bw.message(target, action, data)` | Dispatch to `el.bw[action](data)` |
 | `bw.emit(el, event, detail)` | DOM-scoped CustomEvent |
 
@@ -658,7 +659,7 @@ bwcli serve                                   # dev server (port 7902)
 9. **CSS classes use `bw-` prefix**: `bw-card`, `bw-btn`, `bw-container`.
 10. **Routing is built in** -- `bw.router()` for SPAs. Hash mode by default, history mode optional.
 11. **Use `bw.mount()` + `el.bw`** for targeted updates. `o.handle` for methods, `o.slots` for content areas. Avoids re-render side effects (lost focus, scroll reset).
-12. **Debug**: `bw.inspect(el)`, `el._bw_state`, `bwcli attach` for remote REPL.
+12. **Debug**: `bw.inspect(el, 0)`, `el._bw_state`, `bwcli attach` for remote REPL.
 
 ---
 

package/docs/state-management.md

@@ -567,6 +567,20 @@ var results = {
 
 Pub/sub is app-scoped -- publishers and subscribers do not need to know about each other. Pass the element as the third argument to `bw.sub()` to tie the subscription's lifetime to the element (auto-cleaned on `bw.cleanup()`).
 
+Wildcard subscriptions let you listen to a group of related topics at once:
+
+```javascript
+// Listen to ALL search-related topics
+bw.sub('search:*', function(detail, topic) {
+  console.log('Search event:', topic, detail);
+}, el);
+
+// These all fire the wildcard handler above:
+bw.pub('search:changed', { query: 'foo' });
+bw.pub('search:cleared');
+bw.pub('search:submitted', { query: 'foo' });
+```
+
 ### Updating child widgets within a parent component
 
 When a parent component contains child sub-components (like a progress bar inside a dashboard card), use pub/sub to update the child:
@@ -622,8 +636,9 @@ These primitives are the building blocks of the stateful TACO model. They are al
 | `bw.uuid(prefix)` | Generate a UUID class for addressing |
 | `bw.emit(el, event, detail)` | Dispatch a CustomEvent on a DOM element |
 | `bw.on(el, event, handler)` | Listen for a CustomEvent on a DOM element |
-| `bw.pub(topic, detail)` | Publish to app-wide topic |
-| `bw.sub(topic, handler, el?)` | Subscribe to app-wide topic |
+| `bw.pub(topic, detail)` | Publish to app-wide topic (fires exact + wildcard matches) |
+| `bw.sub(topic, handler, el?)` | Subscribe to topic (supports wildcard `'ns:*'` patterns) |
+| `bw.once(topic, handler, el?)` | One-shot subscribe (auto-unsub after first fire) |
 | `bw.unsub(topic, handler)` | Unsubscribe from topic |
 | `bw.cleanup(el)` | Run unmount hooks and clear subscriptions |
 
@@ -725,6 +740,15 @@ bw.sub('store:todos', renderTodos, todosEl);
 bw.sub('store:projects', renderProjects, projectsEl);
 ```
 
+If you need a global listener (e.g. for logging or debug), use a wildcard:
+
+```javascript
+// OK for debug/logging -- not for rendering
+bw.sub('store:*', function(data, topic) {
+  console.log('[store]', topic, data);
+});
+```
+
 ### When to use
 
 - Multi-view SPAs where views share data
@@ -758,7 +782,7 @@ bw.router({
 | Server pushes UI updates | Level 1 -- `bw.patch()` / `bw.DOM()` |
 | Components need to talk to each other | `bw.pub()`/`bw.sub()` |
 | URL-driven views (SPA) | `bw.router()` -- see [Routing](routing.md) |
-| Debugging component state | `el._bw_state` in the console, or `bw.inspect(selector)` |
+| Debugging component state | `el._bw_state` in the console, or `bw.inspect(selector, 0)` |
 
 ---
 

package/docs/thinking-in-bitwrench.md

@@ -1381,9 +1381,10 @@ Key things this example proves:
 
 | Function | What it does |
 |----------|-------------|
-| `bw.pub(topic, data)` | Publish to all subscribers |
-| `bw.sub(topic, fn)` | Subscribe (returns unsub function) |
+| `bw.pub(topic, data)` | Publish to all subscribers (exact + wildcard) |
+| `bw.sub(topic, fn)` | Subscribe (returns unsub function; supports wildcard `'ns:*'`) |
 | `bw.sub(topic, fn, owner)` | Subscribe with auto-cleanup when owner is removed |
+| `bw.once(topic, fn, el?)` | One-shot subscribe (auto-unsub after first fire) |
 
 ### Routing
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "bitwrench",
-	"version": "2.0.25",
+	"version": "2.0.30",
 	"description": "A library for javascript UI functions.",
 	"main": "./dist/bitwrench.umd.js",
 	"repository": {
@@ -63,32 +63,34 @@
 	},
 	"devDependencies": {
 		"@babel/core": "^7.25.2",
-		"@babel/preset-env": "^7.25.3",
+		"@babel/preset-env": "^7.29.2",
 		"@babel/preset-react": "^7.24.7",
-		"@playwright/test": "^1.54.1",
+		"@eslint/js": "^10.0.1",
+		"@playwright/test": "^1.59.1",
 		"@rollup/plugin-babel": "^6.0.4",
 		"@rollup/plugin-commonjs": "^26.0.1",
 		"@rollup/plugin-node-resolve": "^15.2.3",
 		"@rollup/plugin-terser": "^1.0.0",
 		"c8": "^8.0.1",
 		"chai": "^3.0.0",
-		"comment-parser": "^1.4.5",
-		"eslint": "^8.28.0",
-		"jsdom": "^25.0.0",
+		"comment-parser": "^1.4.6",
+		"eslint": "^10.2.0",
+		"globals": "^17.4.0",
+		"jsdom": "^26.1.0",
 		"jsdom-global": "3.0.2",
 		"karma": "^6.3.16",
 		"karma-chai": "^0.1.0",
 		"karma-chrome-launcher": "^3.1.0",
 		"karma-cli": "^2.0.0",
 		"karma-coverage": "^2.0.3",
-		"karma-coverage-istanbul-reporter": "^2.1.1",
+		"karma-coverage-istanbul-reporter": "^3.0.3",
 		"karma-firefox-launcher": "^1.3.0",
 		"karma-ie-launcher": "^1.0.0",
 		"karma-mocha": "^2.0.1",
 		"mocha": "^11.0.0",
 		"pixelmatch": "^7.1.0",
 		"pngjs": "^7.0.0",
-		"rollup": "^4.29.1",
+		"rollup": "^4.60.1",
 		"rollup-plugin-css-only": "^4.5.2",
 		"rollup-plugin-postcss": "^4.0.2",
 		"uglify-js": "^3.19.3",
@@ -105,7 +107,7 @@
 		"update_rm": "echo 'DEPRECATED: use build:index instead'",
 		"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 --reporter=json-summary 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_coverage_gaps.js ./test/bitwrench_test_bwserve.js ./test/bitwrench_test_attach.js ./test/bitwrench_test_serve.js ./test/bitwrench_test_code_edit.js ./test/bitwrench_test_html_page.js ./test/bitwrench_test_util_css.js ./test/bitwrench_test_handle.js ./test/bitwrench_test_debug.js ./test/bitwrench_test_router.js ./test/bitwrench_test_mcp_transport.js ./test/bitwrench_test_mcp_server.js ./test/bitwrench_test_mcp_tools.js ./test/bitwrench_test_mcp_knowledge.js ./test/bitwrench_test_mcp_live.js -r jsdom-global/register --exit",
+		"test": "c8 --reporter=text --reporter=json-summary 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_coverage_gaps.js ./test/bitwrench_test_bwserve.js ./test/bitwrench_test_attach.js ./test/bitwrench_test_serve.js ./test/bitwrench_test_code_edit.js ./test/bitwrench_test_html_page.js ./test/bitwrench_test_util_css.js ./test/bitwrench_test_handle.js ./test/bitwrench_test_debug.js ./test/bitwrench_test_router.js ./test/bitwrench_test_mcp_transport.js ./test/bitwrench_test_mcp_server.js ./test/bitwrench_test_mcp_tools.js ./test/bitwrench_test_mcp_knowledge.js ./test/bitwrench_test_mcp_live.js ./test/bitwrench_test_new_apis.js -r jsdom-global/register --exit",
 		"test:bwserve": "mocha ./test/bitwrench_test_bwserve.js -r jsdom-global/register",
 		"test:attach": "mocha ./test/bitwrench_test_attach.js -r jsdom-global/register",
 		"test:serve": "mocha ./test/bitwrench_test_serve.js -r jsdom-global/register --exit",

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.25">
+  <meta name="generator" content="bitwrench v2.0.30">
   <title>bitwrench.js - README</title>
   <link rel="icon" type="image/x-icon" href="images/favicon.ico">
   <script src="dist/bitwrench.umd.min.js"></script>
@@ -72,7 +72,7 @@
 <a class="quikdown-a" href="https://opensource.org/licenses/BSD-2-Clause" rel="noopener noreferrer"><img class="quikdown-img" src="https://img.shields.io/badge/License-BSD%202--Clause-blue.svg" alt="License"></a>
 <a class="quikdown-a" href="https://www.npmjs.com/package/bitwrench" rel="noopener noreferrer"><img class="quikdown-img" src="https://img.shields.io/npm/v/bitwrench.svg?style=flat-square" alt="NPM version"></a>
 <a class="quikdown-a" href="https://github.com/deftio/bitwrench/actions/workflows/ci.yml" rel="noopener noreferrer"><img class="quikdown-img" src="https://github.com/deftio/bitwrench/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
-<a class="quikdown-a" href="https://github.com/deftio/bitwrench" rel="noopener noreferrer"><img class="quikdown-img" src="https://img.shields.io/badge/coverage-97.3%25-brightgreen.svg" alt="Coverage"></a></p><p><a class="quikdown-a" href="https://deftio.github.io/bitwrench/pages/" rel="noopener noreferrer"><img class="quikdown-img" src="./images/bitwrench-logo-med.png" alt="bitwrench"></a></p><p>Bitwrench builds UI from plain JavaScript objects -- one format for components, styling, state, and server rendering, with no build step and zero dependencies.</p><pre class="quikdown-pre"><code class="language-javascript">// Describe UI as a JavaScript object (a &quot;TACO&quot;)
+<a class="quikdown-a" href="https://github.com/deftio/bitwrench" rel="noopener noreferrer"><img class="quikdown-img" src="https://img.shields.io/badge/coverage-97.6%25-brightgreen.svg" alt="Coverage"></a></p><p><a class="quikdown-a" href="https://deftio.github.io/bitwrench/pages/" rel="noopener noreferrer"><img class="quikdown-img" src="./images/bitwrench-logo-med.png" alt="bitwrench"></a></p><p>Bitwrench builds UI from plain JavaScript objects -- one format for components, styling, state, and server rendering, with no build step and zero dependencies.</p><pre class="quikdown-pre"><code class="language-javascript">// Describe UI as a JavaScript object (a &quot;TACO&quot;)
 var page = {
   t: &#39;div&#39;, a: { class: &#39;card&#39; },
   c: [
@@ -208,7 +208,12 @@ bw.DOM(&#39;#app&#39;, counter);</code></pre><blockquote class="quikdown-blockqu
   console.log(&#39;New item:&#39;, detail.name);
 });
 
-bw.pub(&#39;item-added&#39;, { name: &#39;Widget&#39; });</code></pre><h2 class="quikdown-h2">CSS from JavaScript</h2>
+bw.pub(&#39;item-added&#39;, { name: &#39;Widget&#39; });
+
+// Wildcard: listen to a group of related topics
+bw.sub(&#39;item:*&#39;, function(detail, topic) {
+  console.log(topic, detail);  // e.g. &#39;item:added&#39;, &#39;item:removed&#39;
+});</code></pre><h2 class="quikdown-h2">CSS from JavaScript</h2>
 <p><code class="quikdown-code">bw.css()</code> generates CSS from objects. <code class="quikdown-code">bw.s()</code> composes inline styles from reusable utility objects:</p><pre class="quikdown-pre"><code class="language-javascript">// Generate and inject a stylesheet
 bw.injectCSS(bw.css({
   &#39;.my-card&#39;: { padding: &#39;1rem&#39;, borderRadius: &#39;8px&#39; }
@@ -298,15 +303,19 @@ bw.toggleStyles();  // switch between primary and alternate palettes</code></pre
 </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>
+<td class="quikdown-td">Publish to subscribers (exact + wildcard matches)</td>
+</tr>
+<tr class="quikdown-tr">
+<td class="quikdown-td"><code class="quikdown-code">bw.sub(topic, handler, el?)</code></td>
+<td class="quikdown-td">Subscribe to topic (supports wildcard <code class="quikdown-code">&#39;ns:*&#39;</code>); returns unsub function</td>
 </tr>
 <tr class="quikdown-tr">
-<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>
+<td class="quikdown-td"><code class="quikdown-code">bw.once(topic, handler, el?)</code></td>
+<td class="quikdown-td">One-shot subscribe; auto-unsub after first fire</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&#39;s state, handles, and metadata in the console</td>
+<td class="quikdown-td"><code class="quikdown-code">bw.inspect(target, depth)</code></td>
+<td class="quikdown-td">Introspect a DOM subtree with bitwrench metadata (state, handles, type)</td>
 </tr>
 <tr class="quikdown-tr">
 <td class="quikdown-td"><code class="quikdown-code">bw.apply(msg)</code></td>

package/src/bitwrench.d.ts

@@ -315,8 +315,8 @@ export interface Bitwrench {
   html(taco: Taco | TacoContent, options?: { raw?: boolean; state?: Record<string, any> }): string;
   /** Generate complete HTML page string */
   htmlPage(opts: { title?: string; css?: string; content?: TacoContent; favicon?: string; [key: string]: any }): string;
-  /** Create DOM element from TACO (browser only) */
-  createDOM(taco: Taco | TacoContent, options?: Record<string, any>): HTMLElement | DocumentFragment;
+  /** Create DOM element from TACO (browser only). SVG TACOs ({t:'svg',...}) use createElementNS. */
+  createDOM(taco: Taco | TacoContent, options?: Record<string, any>): HTMLElement | SVGElement | DocumentFragment;
   /** Mount TACO into target, replacing contents */
   DOM(target: string | HTMLElement, taco: Taco | TacoContent, options?: Record<string, any>): void;
   /** Mount TACO and return root element (for el.bw access) */
@@ -331,24 +331,28 @@ export interface Bitwrench {
   update(target: string | HTMLElement): void;
   /** Quick-patch element content or attribute */
   patch(id: string | HTMLElement, content?: TacoContent, attr?: string): HTMLElement | null;
+  /** RFC 6902 JSON Patch on plain objects. Mutates and returns obj. @see bw.patch */
+  jsonPatch(obj: object, ops: Array<{ op: string; path: string; value?: any; from?: string }>): object;
   /** Batch patch multiple elements */
   patchAll(patches: Record<string, TacoContent> | Array<{ id: string; content?: TacoContent; attr?: string }>): Record<string, HTMLElement>;
   /** Clean up lifecycle hooks, subscriptions, cache */
   cleanup(element: HTMLElement): void;
 
   // -- DOM Selection --------------------------------------------------------
-  /** CSS selector to array of elements */
-  $(selector: string | HTMLElement | HTMLElement[]): HTMLElement[];
+  /** Resolve target to first matching element. Optional apply: string (textContent), function, TACO (mount), or array. @see bw.$ */
+  el(target: string | HTMLElement | null, apply?: string | number | boolean | Function | object | any[]): HTMLElement | null;
+  /** CSS selector to array of elements. Optional apply applied to each. @see bw.el */
+  $(selector: string | HTMLElement | HTMLElement[], apply?: string | number | boolean | Function | object | any[]): HTMLElement[];
   /** Dispatch DOM event */
   emit(target: string | HTMLElement, eventName: string, detail?: any): void;
   /** Add event listener */
   on(target: string | HTMLElement, eventName: string, handler: (e: Event) => void): void;
 
   // -- Pub/Sub --------------------------------------------------------------
-  /** Publish to topic */
+  /** Publish to topic. Fires exact-match and wildcard subscribers. */
   pub(topic: string, detail?: any): number;
-  /** Subscribe to topic; returns unsub() */
-  sub(topic: string, handler: (detail: any) => void, el?: HTMLElement): () => void;
+  /** Subscribe to topic (or wildcard pattern ending in '*'); returns unsub(). Handler receives (detail, topic). */
+  sub(topic: string, handler: (detail: any, topic?: string) => void, el?: HTMLElement): () => void;
   /** Unsubscribe handler from topic */
   unsub(topic: string, handler: Function): number;
 
@@ -365,8 +369,8 @@ export interface Bitwrench {
   message(target: string | HTMLElement, action: string, data?: any): any;
   /** Execute wire-protocol message object */
   apply(msg: Record<string, any>): any;
-  /** Inspect element properties */
-  inspect(target: string | HTMLElement): Record<string, any>;
+  /** Inspect DOM element and subtree, returning plain-object tree with bitwrench metadata */
+  inspect(target: string | HTMLElement, depth?: number): Record<string, any> | null;
 
   // -- Function Registry ----------------------------------------------------
   funcRegister(fn: Function, name?: string): string;
@@ -395,8 +399,10 @@ export interface Bitwrench {
   loadStyles(config?: StyleConfig, scope?: string): StylesResult | void;
   /** Load CSS reset */
   loadReset(): void;
-  /** Switch primary/alternate palette */
-  toggleStyles(scope?: string): void;
+  /** Toggle between primary/alternate theme palettes on all matching elements. @see bw.applyStyles */
+  toggleThemeMode(scope?: string | HTMLElement): string;
+  /** @deprecated Use bw.toggleThemeMode() instead. Alias kept for one release cycle. */
+  toggleStyles(scope?: string | HTMLElement): string;
   /** Remove injected styles */
   clearStyles(scope?: string): void;
   /** Generate type scale from base + ratio */
@@ -586,6 +592,7 @@ export interface Bitwrench {
 
   // -- Internal (access at own risk) ----------------------------------------
   _nodeMap: Record<string, HTMLElement>;
+  /** @deprecated Use bw.el() instead. Alias kept for one release cycle. */
   _el(id: string): HTMLElement | null;
   _registerNode(el: HTMLElement, uuid: string): void;
   _deregisterNode(el: HTMLElement, uuid: string): void;