bitwrench 2.0.24 → 2.0.25

package/README.md

@@ -3,7 +3,7 @@
 [![License](https://img.shields.io/badge/License-BSD%202--Clause-blue.svg)](https://opensource.org/licenses/BSD-2-Clause)
 [![NPM version](https://img.shields.io/npm/v/bitwrench.svg?style=flat-square)](https://www.npmjs.com/package/bitwrench)
 [![CI](https://github.com/deftio/bitwrench/actions/workflows/ci.yml/badge.svg)](https://github.com/deftio/bitwrench/actions/workflows/ci.yml)
-[![Coverage](https://img.shields.io/badge/coverage-96.3%25-brightgreen.svg)](https://github.com/deftio/bitwrench)
+[![Coverage](https://img.shields.io/badge/coverage-97.3%25-brightgreen.svg)](https://github.com/deftio/bitwrench)
 
 [![bitwrench](./images/bitwrench-logo-med.png)](https://deftio.github.io/bitwrench/pages/)
 
@@ -33,13 +33,14 @@ Each object has four keys: **t** (tag), **a** (attributes), **c** (content), **o
 Structure, styling, state, and server rendering are all handled as JavaScript objects:
 
 - **No build toolchain** -- works with a `<script>` tag
-- **50+ ready-made components** -- buttons, tables, modals, forms, charts, toasts -- one `make*()` call each, returns a composable TACO
+- **Ready-made components** -- buttons, tables, modals, forms, charts, toasts -- one `make*()` call each, returns a composable TACO
 - **CSS from JavaScript** -- `bw.css()` generates stylesheets, `bw.s()` composes inline styles, `bw.loadStyles()` derives a complete design system from 2 seed colors
 - **Reactive state** -- `o.state` + `o.render` + `bw.update()` for stateful components; `bw.pub()`/`bw.sub()` for cross-component messaging
 - **Dual rendering** -- same object renders to live DOM (`bw.DOM()`) or HTML string (`bw.html()`) for SSR, emails, or static sites
 - **Server-driven UI** -- push UI updates from any backend (Python, C, Rust, Go) over SSE via the biwrench bwserve protocol; `client.screenshot()` captures the page back as PNG/JPEG
 - **CLI** -- `bwcli` converts Markdown, HTML, and JSON to styled standalone pages
 - **Debug tools** -- live client and server debugging with remote incremental inspect, screenshots, and state updates
+- **TypeScript** -- full type declarations ship with the package (`dist/bitwrench.d.ts`); see the [TypeScript Usage Guide](docs/bitwrench_typescript_usage.md)
 - **Utilities** -- color interpolation, random data, lorem ipsum, cookies, URL params, file I/O
 
 
@@ -58,6 +59,7 @@ Bitwrench uses JavaScript equivalents for most forms of front-end development. H
 | Streamlit / Gradio | Server-driven UI | bwserve SSE -- from any language (Python, Go, C, Rust) |
 | Redux / Zustand / Pinia | State management | `o.state` + `bw.update()` + `bw.pub()/sub()` |
 | Vite / webpack / Babel | Build tooling | Not needed -- open the HTML file |
+| DefinitelyTyped / @types | Type declarations | Ships `dist/bitwrench.d.ts` -- nothing extra to install |
 
 See the [Framework Translation Table](docs/framework-translation-table.md) for side-by-side code comparisons across 22 operations.
 
@@ -264,7 +266,7 @@ All formats include source maps. A separate CSS file (`bitwrench.css`) is also a
 
 - [TACO Format](docs/taco-format.md) -- the `{t, a, c, o}` object format
 - [State Management](docs/state-management.md) -- three-level component model, stateful TACO, reactive state
-- [Component Library](docs/component-library.md) -- all 50+ `make*()` functions with signatures and examples
+- [Component Library](docs/component-library.md) -- all `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)
@@ -278,7 +280,7 @@ All formats include source maps. A separate CSS file (`bitwrench.css`) is also a
 **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) -- all 50+ UI components with live demos
+- [Components](https://deftio.github.io/bitwrench/pages/01-components.html) -- all UI components with live demos
 - [Styling & Theming](https://deftio.github.io/bitwrench/pages/03-styling.html) -- CSS generation, `bw.s()`, and theming strategies
 - [State & Interactivity](https://deftio.github.io/bitwrench/pages/05-state.html) -- state patterns and stateful TACO
 - [Tic Tac Toe Tutorial](https://deftio.github.io/bitwrench/pages/06-tic-tac-toe-tutorial.html) -- step-by-step game with state management
@@ -311,7 +313,7 @@ All formats include source maps. A separate CSS file (`bitwrench.css`) is also a
 
 **Can I use bitwrench on embedded devices?** -- 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 [ESP32 tutorial](docs/tutorial-embedded.md).
 
-**Can I use it with TypeScript?** -- Yes. Type declarations are included. TACO objects are plain JSON-compatible objects that TypeScript infers naturally.
+**Can I use it with TypeScript?** -- Yes. Type declarations ship with the package (`dist/bitwrench.d.ts`). TACO objects are plain JSON-compatible objects that TypeScript infers naturally. See the [TypeScript Usage Guide](docs/bitwrench_typescript_usage.md) for import patterns, typed configs, and examples.
 
 **What about accessibility?** -- BCCL components emit semantic HTML with ARIA attributes where applicable. You can add any `aria-*` attribute via `a: { 'aria-label': '...' }`.
 
@@ -320,7 +322,7 @@ All formats include source maps. A separate CSS file (`bitwrench.css`) is also a
 ```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/dist/bitwrench-bccl.cjs.js

@@ -1,4 +1,4 @@
-/*! bitwrench-bccl v2.0.24 | BSD-2-Clause | https://deftio.github.com/bitwrench/pages */
+/*! bitwrench-bccl v2.0.25 | BSD-2-Clause | https://deftio.github.com/bitwrench/pages */
 'use strict';
 
 /**

package/dist/bitwrench-bccl.cjs.min.js

@@ -1,4 +1,4 @@
-/*! bitwrench-bccl v2.0.24 | BSD-2-Clause | https://deftio.github.com/bitwrench/pages */
+/*! bitwrench-bccl v2.0.25 | BSD-2-Clause | https://deftio.github.com/bitwrench/pages */
 "use strict";
 /**
  * Bitwrench v2 Components

package/dist/bitwrench-bccl.esm.js

@@ -1,4 +1,4 @@
-/*! bitwrench-bccl v2.0.24 | BSD-2-Clause | https://deftio.github.com/bitwrench/pages */
+/*! bitwrench-bccl v2.0.25 | BSD-2-Clause | https://deftio.github.com/bitwrench/pages */
 /**
  * Bitwrench v2 Components
  *

package/dist/bitwrench-bccl.esm.min.js

@@ -1,4 +1,4 @@
-/*! bitwrench-bccl v2.0.24 | BSD-2-Clause | https://deftio.github.com/bitwrench/pages */
+/*! bitwrench-bccl v2.0.25 | BSD-2-Clause | https://deftio.github.com/bitwrench/pages */
 /**
  * Bitwrench v2 Components
  *

package/dist/bitwrench-bccl.umd.js

@@ -1,4 +1,4 @@
-/*! bitwrench-bccl v2.0.24 | BSD-2-Clause | https://deftio.github.com/bitwrench/pages */
+/*! bitwrench-bccl v2.0.25 | BSD-2-Clause | https://deftio.github.com/bitwrench/pages */
 (function (global, factory) {
   typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports) :
   typeof define === 'function' && define.amd ? define(['exports'], factory) :

package/dist/bitwrench-bccl.umd.min.js

@@ -1,4 +1,4 @@
-/*! bitwrench-bccl v2.0.24 | BSD-2-Clause | https://deftio.github.com/bitwrench/pages */
+/*! bitwrench-bccl v2.0.25 | BSD-2-Clause | https://deftio.github.com/bitwrench/pages */
 !function(e,t){"object"==typeof exports&&"undefined"!=typeof module?t(exports):"function"==typeof define&&define.amd?define(["exports"],t):t((e="undefined"!=typeof globalThis?globalThis:e||self).bwBCCL={})}(this,function(e){"use strict";
 /**
    * Bitwrench v2 Components

package/dist/bitwrench-code-edit.cjs.js

@@ -1,4 +1,4 @@
-/*! bitwrench v2.0.24 | BSD-2-Clause | https://deftio.github.com/bitwrench/pages */
+/*! bitwrench v2.0.25 | BSD-2-Clause | https://deftio.github.com/bitwrench/pages */
 'use strict';
 
 Object.defineProperty(exports, '__esModule', { value: true });

package/dist/bitwrench-code-edit.cjs.min.js

@@ -1,4 +1,4 @@
-/*! bitwrench v2.0.24 | BSD-2-Clause | https://deftio.github.com/bitwrench/pages */
+/*! bitwrench v2.0.25 | BSD-2-Clause | https://deftio.github.com/bitwrench/pages */
 "use strict";Object.defineProperty(exports,"__esModule",{value:!0});
 /**
  * bitwrench-code-edit.js - syntax-highlighted contenteditable code editor addon

package/dist/bitwrench-code-edit.es5.js

@@ -1,4 +1,4 @@
-/*! bitwrench v2.0.24 | BSD-2-Clause | https://deftio.github.com/bitwrench/pages */
+/*! bitwrench v2.0.25 | BSD-2-Clause | https://deftio.github.com/bitwrench/pages */
 (function (global, factory) {
   typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports) :
   typeof define === 'function' && define.amd ? define(['exports'], factory) :

package/dist/bitwrench-code-edit.es5.min.js

@@ -1,4 +1,4 @@
-/*! bitwrench v2.0.24 | BSD-2-Clause | https://deftio.github.com/bitwrench/pages */
+/*! bitwrench v2.0.25 | BSD-2-Clause | https://deftio.github.com/bitwrench/pages */
 !function(e,t){"object"==typeof exports&&"undefined"!=typeof module?t(exports):"function"==typeof define&&define.amd?define(["exports"],t):t((e="undefined"!=typeof globalThis?globalThis:e||self).bwCodeEdit={})}(this,function(e){"use strict";
 /**
    * bitwrench-code-edit.js - syntax-highlighted contenteditable code editor addon

package/dist/bitwrench-code-edit.esm.js

@@ -1,4 +1,4 @@
-/*! bitwrench v2.0.24 | BSD-2-Clause | https://deftio.github.com/bitwrench/pages */
+/*! bitwrench v2.0.25 | BSD-2-Clause | https://deftio.github.com/bitwrench/pages */
 /**
  * bitwrench-code-edit.js - syntax-highlighted contenteditable code editor addon
  *

package/dist/bitwrench-code-edit.esm.min.js

@@ -1,4 +1,4 @@
-/*! bitwrench v2.0.24 | BSD-2-Clause | https://deftio.github.com/bitwrench/pages */
+/*! bitwrench v2.0.25 | BSD-2-Clause | https://deftio.github.com/bitwrench/pages */
 /**
  * bitwrench-code-edit.js - syntax-highlighted contenteditable code editor addon
  *

package/dist/bitwrench-code-edit.umd.js

@@ -1,4 +1,4 @@
-/*! bitwrench v2.0.24 | BSD-2-Clause | https://deftio.github.com/bitwrench/pages */
+/*! bitwrench v2.0.25 | BSD-2-Clause | https://deftio.github.com/bitwrench/pages */
 (function (global, factory) {
   typeof exports === 'object' && typeof module !== 'undefined' ? factory(exports) :
   typeof define === 'function' && define.amd ? define(['exports'], factory) :

package/dist/bitwrench-code-edit.umd.min.js

@@ -1,4 +1,4 @@
-/*! bitwrench v2.0.24 | BSD-2-Clause | https://deftio.github.com/bitwrench/pages */
+/*! bitwrench v2.0.25 | BSD-2-Clause | https://deftio.github.com/bitwrench/pages */
 !function(e,t){"object"==typeof exports&&"undefined"!=typeof module?t(exports):"function"==typeof define&&define.amd?define(["exports"],t):t((e="undefined"!=typeof globalThis?globalThis:e||self).bwCodeEdit={})}(this,function(e){"use strict";
 /**
    * bitwrench-code-edit.js - syntax-highlighted contenteditable code editor addon

package/dist/bitwrench-debug.js

@@ -1,4 +1,4 @@
-/*! bitwrench-debug v2.0.24 | BSD-2-Clause | https://deftio.github.com/bitwrench/pages */
+/*! bitwrench-debug v2.0.25 | BSD-2-Clause | https://deftio.github.com/bitwrench/pages */
 (function (global, factory) {
 	typeof exports === 'object' && typeof module !== 'undefined' ? module.exports = factory() :
 	typeof define === 'function' && define.amd ? define(factory) :

package/dist/bitwrench-debug.min.js

@@ -1,3 +1,3 @@
-/*! bitwrench-debug v2.0.24 | BSD-2-Clause | https://deftio.github.com/bitwrench/pages */
+/*! bitwrench-debug v2.0.25 | BSD-2-Clause | https://deftio.github.com/bitwrench/pages */
 !function(e,n){"object"==typeof exports&&"undefined"!=typeof module?module.exports=n():"function"==typeof define&&define.amd?define(n):(e="undefined"!=typeof globalThis?globalThis:e||self).bwd=n()}(this,function(){"use strict";function e(e){return e&&e.__esModule&&Object.prototype.hasOwnProperty.call(e,"default")?e.default:e}var n={exports:{}};return function(e){!function(){var n={};function o(e){return new Promise(function(n,o){var t=document.createElement("script");t.src=e,t.onload=function(){n()},t.onerror=function(){o(new Error("Failed to load "+e))},document.head.appendChild(t)})}function t(e,n,o){if(!e||n>o)return null;var l={tag:e.tagName?e.tagName.toLowerCase():"#text"};if(e.id&&(l.id=e.id),e.className&&"string"==typeof e.className&&(l.cls=e.className.split(" ").slice(0,5).join(" ")),e.children&&e.children.length>0&&n<o){l.children=[];for(var i=0;i<Math.min(e.children.length,20);i++){var r=t(e.children[i],n+1,o);r&&l.children.push(r)}}return l}function l(e,n){if(e){var o=e.tag||"?";if(e.id&&(o+="#"+e.id),e.cls&&(o+="."+e.cls.split(" ").join(".")),console.log("  ".repeat(n)+o),e.children)for(var t=0;t<e.children.length;t++)l(e.children[t],n+1)}}var i={tree:function(e,n){e=e||"body",n=n||3;var o=document.querySelector(e);if(!o)return console.log('(no element found for "'+e+'")'),null;var i=t(o,0,n);return l(i,0),i},listen:function(e,o){var t=e+":::"+o;if(n[t])console.log("[bwd] already listening for "+o+" on "+e);else{var l=function(n){var t=n.target.closest?n.target.closest(e):null;t&&console.log("[bwd] "+o+" on "+e+" -> "+t.tagName+(t.id?"#"+t.id:"")+(t.textContent?' "'+t.textContent.slice(0,50).trim()+'"':""))};document.addEventListener(o,l,!0),n[t]={fn:l,event:o},console.log("[bwd] listening for "+o+" on "+e)}},unlisten:function(e,o){var t=e+":::"+o,l=n[t];l?(document.removeEventListener(l.event,l.fn,!0),delete n[t],console.log("[bwd] stopped listening for "+o+" on "+e)):console.log("[bwd] no listener for "+o+" on "+e)},state:function(e){e=e||".bw_lc";for(var n=document.querySelectorAll(e),o=[],t=0;t<n.length;t++){var l=n[t],i="";"undefined"!=typeof window&&window.bw&&window.bw.getUUID&&(i=window.bw.getUUID(l)||""),o.push({id:l.id||"",uuid:i,state:l._bw_state||null})}return 0===o.length?console.log('[bwd] no stateful elements found for "'+e+'"'):"function"==typeof console.table?console.table(o):console.log(o),o},screenshot:function(e){e=e||"body";var n=document.querySelector(e);return n?("undefined"!=typeof window&&window.html2canvas?Promise.resolve(window.html2canvas):o("https://cdn.jsdelivr.net/npm/html2canvas@1.4.1/dist/html2canvas.min.js").then(function(){return window.html2canvas})).then(function(o){return console.log("[bwd] capturing "+e+" ..."),o(n,{useCORS:!0})}).then(function(e){var n="screenshot-"+Date.now()+".png";e.toBlob(function(e){if("undefined"!=typeof window&&window.bw&&window.bw.saveClientFile)window.bw.saveClientFile(n,e);else{var o=document.createElement("a");o.href=URL.createObjectURL(e),o.download=n,o.click(),URL.revokeObjectURL(o.href)}console.log("[bwd] saved: "+n)})}).catch(function(e){console.error("[bwd] screenshot failed: "+e.message)}):(console.log('[bwd] no element found for "'+e+'"'),Promise.resolve(null))},_listeners:n};function r(){console.log("[bwd] bitwrench debug toolkit ready"),console.log("  bwd.tree(sel?, depth?)       -- print DOM tree"),console.log("  bwd.listen(sel, event)       -- log events"),console.log("  bwd.unlisten(sel, event)     -- stop logging"),console.log("  bwd.state(sel?)              -- dump stateful elements"),console.log("  bwd.screenshot(sel?)         -- capture screenshot")}e.exports&&(e.exports=i),"undefined"!=typeof window&&(window.bwd=i),"undefined"!=typeof window&&(window.bw&&window.bw.version?r():(console.log("[bwd] bitwrench not detected, loading from CDN..."),o("https://cdn.jsdelivr.net/npm/bitwrench@2/dist/bitwrench.umd.min.js").then(function(){r()}).catch(function(e){console.warn("[bwd] could not load bitwrench: "+e.message),console.log("[bwd] toolkit ready (limited -- bw.* not available)"),console.log("  bwd.tree, bwd.listen, bwd.unlisten still work")})))}()}(n),e(n.exports)});
 //# sourceMappingURL=bitwrench-debug.min.js.map

package/dist/bitwrench-lean.cjs.js

@@ -1,4 +1,4 @@
-/*! bitwrench-lean v2.0.24 | BSD-2-Clause | https://deftio.github.com/bitwrench/pages */
+/*! bitwrench-lean v2.0.25 | BSD-2-Clause | https://deftio.github.com/bitwrench/pages */
 'use strict';
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
@@ -8,14 +8,14 @@ var _documentCurrentScript = typeof document !== 'undefined' ? document.currentS
  */
 
 const VERSION_INFO = {
-  version: '2.0.24',
+  version: '2.0.25',
   name: 'bitwrench',
   description: 'A library for javascript UI functions.',
   license: 'BSD-2-Clause',
   homepage: 'https://deftio.github.com/bitwrench/pages',
   repository: 'git+https://github.com/deftio/bitwrench.git',
   author: 'manu a. chatterjee <deftio@deftio.com> (https://deftio.com/)',
-  buildDate: '2026-03-28T09:12:50.073Z'
+  buildDate: '2026-03-31T03:03:30.752Z'
 };
 
 /**
@@ -705,7 +705,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;
@@ -885,7 +885,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')] = {
@@ -966,7 +966,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
   };
@@ -992,7 +992,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,
@@ -1089,11 +1089,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')] = {
@@ -1328,11 +1328,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;
 }
 
@@ -1594,14 +1594,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;
 }
@@ -6252,7 +6252,8 @@ bw.applyStyles = function(styles, scope) {
  *
  * @param {Object} [config] - Style configuration (same as `makeStyles`)
  * @param {string} [scope] - Scope selector (same as `applyStyles`)
- * @returns {Element|null} The `<style>` element, or null in Node.js
+ * @returns {Object} The styles object (same as `makeStyles` return value:
+ *   `{css, alternateCss, palette, alternatePalette, rules, alternateRules, isLightPrimary}`)
  * @category CSS & Styling
  * @see bw.makeStyles
  * @see bw.applyStyles
@@ -6270,9 +6271,27 @@ bw.loadStyles = function(config, scope) {
       bw.injectCSS(structuralCSS, { id: 'bw_structural', append: false });
     }
   }
-  return bw.applyStyles(bw.makeStyles(config), scope);
+  var styles = bw.makeStyles(config);
+  bw.applyStyles(styles, scope);
+  return styles;
 };
 
+/**
+ * Prefix every selector in a rules object with a scope selector.
+ * Useful for wrapping site-level CSS under `.bw_theme_alt` for dark mode.
+ *
+ * @param {Object} rules - CSS rules object (selector -> declarations)
+ * @param {string} prefix - Scope prefix (e.g. '.bw_theme_alt')
+ * @returns {Object} New rules object with scoped selectors
+ * @category CSS & Styling
+ * @see bw.applyStyles
+ * @see bw.css
+ * @example
+ * var altRules = bw.scopeRulesUnder(myRules, '.bw_theme_alt');
+ * bw.injectCSS(bw.css(altRules));
+ */
+bw.scopeRulesUnder = scopeRulesUnder;
+
 /**
  * Inject the CSS reset (box-sizing, html/body font, reduced-motion).
  * Idempotent — if already injected, returns the existing `<style>` element.