bitwrench 2.0.24 → 2.0.30

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "bitwrench",
-	"version": "2.0.24",
+	"version": "2.0.30",
 	"description": "A library for javascript UI functions.",
 	"main": "./dist/bitwrench.umd.js",
 	"repository": {
@@ -20,16 +20,19 @@
 	"module": "./dist/bitwrench.esm.js",
 	"exports": {
 		".": {
+			"types": "./dist/bitwrench.d.ts",
 			"import": "./dist/bitwrench.esm.js",
 			"require": "./dist/bitwrench.cjs.js",
 			"default": "./dist/bitwrench.umd.js"
 		},
 		"./lean": {
+			"types": "./dist/bitwrench.d.ts",
 			"import": "./dist/bitwrench-lean.esm.js",
 			"require": "./dist/bitwrench-lean.cjs.js",
 			"default": "./dist/bitwrench-lean.umd.js"
 		},
 		"./bccl": {
+			"types": "./dist/bitwrench.d.ts",
 			"import": "./dist/bitwrench-bccl.esm.js",
 			"require": "./dist/bitwrench-bccl.cjs.js",
 			"default": "./dist/bitwrench-bccl.umd.js"
@@ -60,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",
@@ -94,14 +99,15 @@
 	"scripts": {
 		"generate-version": "node tools/generate-version.cjs",
 		"prebuild": "npm run generate-version && npm run lint",
-		"build": "rollup --config && npm run build:css && npm run build:metrics && npm run build:builds",
+		"build": "rollup --config && npm run build:css && npm run build:types && npm run build:metrics && npm run build:builds",
+		"build:types": "cp src/bitwrench.d.ts dist/bitwrench.d.ts",
 		"build:css": "node src/generate-css.js",
 		"build:readme": "node tools/build-readme.js",
 		"build:watch": "rollup --config --watch",
 		"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 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 -r jsdom-global/register",
+		"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,12 +3,12 @@
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <meta name="generator" content="bitwrench v2.0.24">
+  <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>
-  <script src="pages/shared-theme.js"></script>
   <script src="pages/shared-nav.js"></script>
+  <script src="pages/site.js"></script>
   <style>
 .quikdown-h1 { font-size:2em;font-weight:600;margin:.67em 0;text-align:left;color:#333 }
 .quikdown-h2 { font-size:1.5em;font-weight:600;margin:.83em 0;color:#333 }
@@ -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-96.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: [
@@ -86,13 +86,14 @@ bw.DOM(&#39;#app&#39;, page);          // -&gt; live DOM
 bw.html(page);                 // -&gt; HTML string (Node.js, emails, SSR)</code></pre><p>Each object has four keys: <strong class="quikdown-strong">t</strong> (tag), <strong class="quikdown-strong">a</strong> (attributes), <strong class="quikdown-strong">c</strong> (content), <strong class="quikdown-strong">o</strong> (options for state/lifecycle). Nest them, loop them, compose them -- it&#39;s just JavaScript.</p><h3 class="quikdown-h3">Why bitwrench?</h3>
 <strong class="quikdown-strong">One file, everywhere.</strong> At ~40KB gzipped with zero dependencies, bitwrench runs on anything with a browser -- phones, tablets, Raspberry Pi, even ESP32 microcontrollers. The device serves a single HTML page and pushes data as JSON; bitwrench handles all rendering, styling, and state on the client. No Node.js, no build step, no internet connection required.</p><p>Structure, styling, state, and server rendering are all handled as JavaScript objects:</p><ul class="quikdown-ul">
 <li class="quikdown-li"><strong class="quikdown-strong">No build toolchain</strong> -- works with a <code class="quikdown-code">&lt;script&gt;</code> tag</li>
-<li class="quikdown-li"><strong class="quikdown-strong">50+ ready-made components</strong> -- buttons, tables, modals, forms, charts, toasts -- one <code class="quikdown-code">make*()</code> call each, returns a composable TACO</li>
+<li class="quikdown-li"><strong class="quikdown-strong">Ready-made components</strong> -- buttons, tables, modals, forms, charts, toasts -- one <code class="quikdown-code">make*()</code> call each, returns a composable TACO</li>
 <li class="quikdown-li"><strong class="quikdown-strong">CSS from JavaScript</strong> -- <code class="quikdown-code">bw.css()</code> generates stylesheets, <code class="quikdown-code">bw.s()</code> composes inline styles, <code class="quikdown-code">bw.loadStyles()</code> derives a complete design system from 2 seed colors</li>
 <li class="quikdown-li"><strong class="quikdown-strong">Reactive state</strong> -- <code class="quikdown-code">o.state</code> + <code class="quikdown-code">o.render</code> + <code class="quikdown-code">bw.update()</code> for stateful components; <code class="quikdown-code">bw.pub()</code>/<code class="quikdown-code">bw.sub()</code> for cross-component messaging</li>
 <li class="quikdown-li"><strong class="quikdown-strong">Dual rendering</strong> -- same object renders to live DOM (<code class="quikdown-code">bw.DOM()</code>) or HTML string (<code class="quikdown-code">bw.html()</code>) for SSR, emails, or static sites</li>
 <li class="quikdown-li"><strong class="quikdown-strong">Server-driven UI</strong> -- push UI updates from any backend (Python, C, Rust, Go) over SSE via the biwrench bwserve protocol; <code class="quikdown-code">client.screenshot()</code> captures the page back as PNG/JPEG</li>
 <li class="quikdown-li"><strong class="quikdown-strong">CLI</strong> -- <code class="quikdown-code">bwcli</code> converts Markdown, HTML, and JSON to styled standalone pages</li>
 <li class="quikdown-li"><strong class="quikdown-strong">Debug tools</strong> -- live client and server debugging with remote incremental inspect, screenshots, and state updates</li>
+<li class="quikdown-li"><strong class="quikdown-strong">TypeScript</strong> -- full type declarations ship with the package (<code class="quikdown-code">dist/bitwrench.d.ts</code>); see the <a class="quikdown-a" href="docs/bitwrench<em class="quikdown-em">typescript</em>usage.md">TypeScript Usage Guide</a></li>
 <li class="quikdown-li"><strong class="quikdown-strong">Utilities</strong> -- color interpolation, random data, lorem ipsum, cookies, URL params, file I/O</li>
 </ul><h3 class="quikdown-h3">Coming from other Frameworks</h3>
 <p>Bitwrench uses JavaScript equivalents for most forms of front-end development. Here is a quick mapping (see the <a class="quikdown-a" href="docs/README.md">docs</a> and <a class="quikdown-a" href="docs/thinking-in-bitwrench.md">Thinking in Bitwrench</a> for more details).</p><table class="quikdown-table">
@@ -144,6 +145,11 @@ bw.html(page);                 // -&gt; HTML string (Node.js, emails, SSR)</code
 <td class="quikdown-td">Build tooling</td>
 <td class="quikdown-td">Not needed -- open the HTML file</td>
 </tr>
+<tr class="quikdown-tr">
+<td class="quikdown-td">DefinitelyTyped / @types</td>
+<td class="quikdown-td">Type declarations</td>
+<td class="quikdown-td">Ships <code class="quikdown-code">dist/bitwrench.d.ts</code> -- nothing extra to install</td>
+</tr>
 </tbody>
 </table><p>See the <a class="quikdown-a" href="docs/framework-translation-table.md">Framework Translation Table</a> for side-by-side code comparisons across 22 operations.</p><h2 class="quikdown-h2">Installation</h2>
 <p><pre class="quikdown-pre"><code class="language-bash">npm install bitwrench</code></pre></p><pre class="quikdown-pre"><code class="language-javascript">// ES module
@@ -202,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; }
@@ -292,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>
@@ -355,7 +370,7 @@ curl -X POST http://localhost:9000 -d &#39;{&quot;type&quot;:&quot;patch&quot;,&
 </ul><p><strong class="quikdown-strong">Reference 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, stateful TACO, 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/component-library.md">Component Library</a> -- all <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>
@@ -365,7 +380,7 @@ curl -X POST http://localhost:9000 -d &#39;{&quot;type&quot;:&quot;patch&quot;,&
 <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> -- all 50+ UI components with live demos</li>
+<li class="quikdown-li"><a class="quikdown-a" href="https://deftio.github.io/bitwrench/pages/01-components.html" rel="noopener noreferrer">Components</a> -- all UI components with live demos</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, <code class="quikdown-code">bw.s()</code>, 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> -- state patterns and stateful TACO</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>
@@ -382,10 +397,10 @@ curl -X POST http://localhost:9000 -d &#39;{&quot;type&quot;:&quot;patch&quot;,&
 <li class="quikdown-li"><a class="quikdown-a" href="examples/client-server/">bwserve Counter</a> -- server-driven UI demo</li>
 <li class="quikdown-li"><a class="quikdown-a" href="examples/llm-chat/">LLM Chat</a> -- streaming chat via bwserve + Ollama/OpenAI</li>
 </ul><h2 class="quikdown-h2">FAQ</h2>
-<strong class="quikdown-strong">Is this a framework?</strong> -- No. Bitwrench is a library (~40KB gzipped). No lifecycle to learn, no project structure to follow. Import it, call functions, done.</p><p><strong class="quikdown-strong">How does bitwrench compare to React/Vue?</strong> -- They solve different problems at different scales. React and Vue provide a component model, virtual DOM, and ecosystem for large team-built SPAs. Bitwrench provides rendering and state primitives in a single file with no build step, aimed at single-page tools, dashboards, embedded devices, and server-driven UIs. They coexist fine -- use whichever fits the job.</p><p><strong class="quikdown-strong">How does CSS work?</strong> -- Bitwrench doesn&#39;t own your CSS. Use any external stylesheet, Tailwind, or CSS file you want -- bitwrench doesn&#39;t interfere. On top of that, <code class="quikdown-code">bw.css()</code> generates CSS from JS objects (with <code class="quikdown-code">@media</code>, <code class="quikdown-code">@keyframes</code>, pseudo-classes), <code class="quikdown-code">bw.s()</code> composes inline style objects, and <code class="quikdown-code">bw.loadStyles()</code> derives a complete design system from 2 seed colors. You can use all three together or none at all.</p><p><strong class="quikdown-strong">What&#39;s the difference between <code class="quikdown-code">bw.DOM()</code> and <code class="quikdown-code">bw.html()</code>?</strong> -- Same TACO input, two outputs. <code class="quikdown-code">bw.DOM(&#39;#app&#39;, taco)</code> mounts live DOM elements in a browser. <code class="quikdown-code">bw.html(taco)</code> returns an HTML string -- use it in Node.js scripts, email generators, static site builds, or anywhere you need markup without a browser. One object format, two rendering modes.</p><p><strong class="quikdown-strong">What is bwserve?</strong> -- bwserve lets any server push UI updates to a browser over SSE. The server sends TACO objects as JSON; the browser renders them. It&#39;s language-agnostic -- the server can be Python, Go, Rust, C, or a shell script. Anything that can write JSON to an HTTP response can drive a bitwrench UI. See the <a class="quikdown-a" href="docs/bwserve.md">bwserve docs</a>.</p><p><strong class="quikdown-strong">Can I use bitwrench on embedded devices?</strong> -- Yes -- this is a primary use case. An ESP32 or Raspberry Pi serves one HTML page with bitwrench loaded, then pushes sensor data as JSON patches over SSE. The device never generates HTML. See the <a class="quikdown-a" href="docs/tutorial-embedded.md">ESP32 tutorial</a>.</p><p><strong class="quikdown-strong">Can I use it with TypeScript?</strong> -- Yes. Type declarations are included. TACO objects are plain JSON-compatible objects that TypeScript infers naturally.</p><p><strong class="quikdown-strong">What about accessibility?</strong> -- BCCL components emit semantic HTML with ARIA attributes where applicable. You can add any <code class="quikdown-code">aria-*</code> attribute via <code class="quikdown-code">a: { &#39;aria-label&#39;: &#39;...&#39; }</code>.</p><h2 class="quikdown-h2">Development</h2>
+<strong class="quikdown-strong">Is this a framework?</strong> -- No. Bitwrench is a library (~40KB gzipped). No lifecycle to learn, no project structure to follow. Import it, call functions, done.</p><p><strong class="quikdown-strong">How does bitwrench compare to React/Vue?</strong> -- They solve different problems at different scales. React and Vue provide a component model, virtual DOM, and ecosystem for large team-built SPAs. Bitwrench provides rendering and state primitives in a single file with no build step, aimed at single-page tools, dashboards, embedded devices, and server-driven UIs. They coexist fine -- use whichever fits the job.</p><p><strong class="quikdown-strong">How does CSS work?</strong> -- Bitwrench doesn&#39;t own your CSS. Use any external stylesheet, Tailwind, or CSS file you want -- bitwrench doesn&#39;t interfere. On top of that, <code class="quikdown-code">bw.css()</code> generates CSS from JS objects (with <code class="quikdown-code">@media</code>, <code class="quikdown-code">@keyframes</code>, pseudo-classes), <code class="quikdown-code">bw.s()</code> composes inline style objects, and <code class="quikdown-code">bw.loadStyles()</code> derives a complete design system from 2 seed colors. You can use all three together or none at all.</p><p><strong class="quikdown-strong">What&#39;s the difference between <code class="quikdown-code">bw.DOM()</code> and <code class="quikdown-code">bw.html()</code>?</strong> -- Same TACO input, two outputs. <code class="quikdown-code">bw.DOM(&#39;#app&#39;, taco)</code> mounts live DOM elements in a browser. <code class="quikdown-code">bw.html(taco)</code> returns an HTML string -- use it in Node.js scripts, email generators, static site builds, or anywhere you need markup without a browser. One object format, two rendering modes.</p><p><strong class="quikdown-strong">What is bwserve?</strong> -- bwserve lets any server push UI updates to a browser over SSE. The server sends TACO objects as JSON; the browser renders them. It&#39;s language-agnostic -- the server can be Python, Go, Rust, C, or a shell script. Anything that can write JSON to an HTTP response can drive a bitwrench UI. See the <a class="quikdown-a" href="docs/bwserve.md">bwserve docs</a>.</p><p><strong class="quikdown-strong">Can I use bitwrench on embedded devices?</strong> -- Yes -- this is a primary use case. An ESP32 or Raspberry Pi serves one HTML page with bitwrench loaded, then pushes sensor data as JSON patches over SSE. The device never generates HTML. See the <a class="quikdown-a" href="docs/tutorial-embedded.md">ESP32 tutorial</a>.</p><p><strong class="quikdown-strong">Can I use it with TypeScript?</strong> -- Yes. Type declarations ship with the package (<code class="quikdown-code">dist/bitwrench.d.ts</code>). TACO objects are plain JSON-compatible objects that TypeScript infers naturally. See the <a class="quikdown-a" href="docs/bitwrench<em class="quikdown-em">typescript</em>usage.md">TypeScript Usage Guide</a> for import patterns, typed configs, and examples.</p><p><strong class="quikdown-strong">What about accessibility?</strong> -- BCCL components emit semantic HTML with ARIA attributes where applicable. You can add any <code class="quikdown-code">aria-*</code> attribute via <code class="quikdown-code">a: { &#39;aria-label&#39;: &#39;...&#39; }</code>.</p><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 (1400+ tests, 96% coverage)
+npm test             # run unit tests
 npm run test:cli     # run CLI tests
 npm run test:e2e     # run Playwright browser tests
 npm run lint         # run ESLint

package/src/bitwrench-styles.js

@@ -232,7 +232,7 @@ function generateTypographyThemed(scope, palette, layout) {
     'transition': 'color ' + mot.fast + ' ' + mot.easing
   };
   rules[_sx(scope, 'a:hover')] = {
-    'color': palette.primary.hover,
+    'color': palette.tertiary.hover,
     'text-decoration': 'underline'
   };
   return rules;
@@ -412,7 +412,7 @@ function generateNavigation(scope, palette, layout) {
     'transition': 'color ' + layout.motion.fast + ' ' + layout.motion.easing + ', background-color ' + layout.motion.fast + ' ' + layout.motion.easing
   };
   rules[_sx(scope, '.bw_navbar_nav .bw_nav_link:hover')] = {
-    'color': palette.dark.base,
+    'color': palette.tertiary.base,
     'background-color': palette.surfaceAlt
   };
   rules[_sx(scope, '.bw_navbar_nav .bw_nav_link.active')] = {
@@ -493,7 +493,7 @@ function generateTabs(scope, palette, layout) {
     'transition': 'color ' + mo.fast + ' ' + mo.easing + ', border-color ' + mo.fast + ' ' + mo.easing + ', background-color ' + mo.fast + ' ' + mo.easing
   };
   rules[_sx(scope, '.bw_nav_tabs .bw_nav_link:hover')] = {
-    'color': palette.dark.base,
+    'color': palette.tertiary.base,
     'background-color': palette.surfaceAlt,
     'border-bottom-color': palette.light.border
   };
@@ -519,7 +519,7 @@ function generateListGroups(scope, palette, layout) {
   };
   rules[_sx(scope, 'a.bw_list_group_item:hover')] = {
     'background-color': palette.surfaceAlt,
-    'color': palette.dark.hover
+    'color': palette.tertiary.base
   };
   rules[_sx(scope, '.bw_list_group_item.active')] = {
     'color': palette.primary.textOn,
@@ -620,11 +620,11 @@ function generateBreadcrumbThemed(scope, palette, layout) {
     'color': palette.secondary.base
   };
   rules[_sx(scope, '.bw_breadcrumb_item a')] = {
-    'color': palette.primary.base,
+    'color': palette.tertiary.base,
     'transition': 'color ' + mo.fast + ' ' + mo.easing
   };
   rules[_sx(scope, '.bw_breadcrumb_item a:hover')] = {
-    'color': palette.primary.hover,
+    'color': palette.tertiary.hover,
     'text-decoration': 'underline'
   };
   rules[_sx(scope, '.bw_breadcrumb_item.active')] = {
@@ -859,11 +859,11 @@ function generateStepperThemed(scope, palette) {
     'font-weight': '600'
   };
   rules[_sx(scope, '.bw_step_completed .bw_step_indicator')] = {
-    'background-color': palette.primary.base,
-    'color': palette.primary.textOn
+    'background-color': palette.tertiary.base,
+    'color': palette.tertiary.textOn
   };
-  rules[_sx(scope, '.bw_step_completed .bw_step_label')] = { 'color': palette.primary.base };
-  rules[_sx(scope, '.bw_step_completed + .bw_step::before')] = { 'background-color': palette.primary.base };
+  rules[_sx(scope, '.bw_step_completed .bw_step_label')] = { 'color': palette.tertiary.base };
+  rules[_sx(scope, '.bw_step_completed + .bw_step::before')] = { 'background-color': palette.tertiary.base };
   return rules;
 }
 
@@ -1125,14 +1125,14 @@ function generatePaletteClasses(scope, palette) {
     };
   });
 
-  // Text muted — always a neutral gray, never a brand color
-  rules[_sx(scope, '.bw_text_muted')] = { 'color': '#6c757d' };
+  // Text muted — uses palette secondary for theme-aware muted text
+  rules[_sx(scope, '.bw_text_muted')] = { 'color': palette.secondary.base };
 
-  // Common bg/text utilities that aren't per-variant
-  rules[_sx(scope, '.bw_bg_dark')] = { 'background-color': '#212529', 'color': '#f8f9fa' };
-  rules[_sx(scope, '.bw_bg_light')] = { 'background-color': '#f8f9fa', 'color': '#212529' };
-  rules[_sx(scope, '.bw_text_light')] = { 'color': '#f8f9fa' };
-  rules[_sx(scope, '.bw_text_dark')] = { 'color': '#212529' };
+  // Common bg/text utilities — derive from palette for theme awareness
+  rules[_sx(scope, '.bw_bg_dark')] = { 'background-color': palette.dark.base, 'color': palette.dark.textOn };
+  rules[_sx(scope, '.bw_bg_light')] = { 'background-color': palette.light.base, 'color': palette.light.textOn };
+  rules[_sx(scope, '.bw_text_light')] = { 'color': palette.light.base };
+  rules[_sx(scope, '.bw_text_dark')] = { 'color': palette.dark.base };
 
   return rules;
 }