bitwrench 2.0.13 → 2.0.15

package/src/bitwrench.js

@@ -8,13 +8,23 @@
  */
 
 import { VERSION_INFO } from './version.js';
-import { getStructuralStyles, theme, updateTheme, generateDarkModeCSS,
-         generateThemedCSS, derivePalette as _derivePalette,
+import { getStructuralStyles,
+         generateThemedCSS, generateAlternateCSS, derivePalette as _derivePalette,
          DEFAULT_PALETTE_CONFIG, SPACING_PRESETS, RADIUS_PRESETS, THEME_PRESETS,
-         resolveLayout, addUnderscoreAliases } from './bitwrench-styles.js';
+         TYPE_RATIO_PRESETS, ELEVATION_PRESETS, MOTION_PRESETS, generateTypeScale,
+         resolveLayout } from './bitwrench-styles.js';
 import { hexToHsl, hslToHex, adjustLightness, mixColor,
          relativeLuminance, textOnColor, deriveShades,
-         derivePalette } from './bitwrench-color-utils.js';
+         derivePalette, harmonize, deriveAlternateSeed, deriveAlternateConfig,
+         isLightPalette,
+         colorParse, colorRgbToHsl, colorHslToRgb } from './bitwrench-color-utils.js';
+import { bindFileOps } from './bitwrench-file-ops.js';
+import { typeOf as _typeOf, mapScale as _mapScale, clip as _clip,
+         choice as _choice, arrayUniq as _arrayUniq, arrayBinA as _arrayBinA,
+         arrayBNotInA as _arrayBNotInA, colorInterp as _colorInterp,
+         loremIpsum as _loremIpsum, multiArray as _multiArray,
+         naturalCompare as _naturalCompare, setIntervalX as _setIntervalX,
+         repeatUntil as _repeatUntil } from './bitwrench-utils.js';
 
 // Environment-aware module loader for optional Node.js built-ins (fs).
 // Strategy: try require() first (CJS/UMD), fall back to import() (ESM).
@@ -49,7 +59,7 @@ const bw = {
   // Fast O(1) lookup for elements by bw_id, id attribute, or bw_uuid.
   //
   // Populated by bw.createDOM() when elements have:
-  //   - data-bw-id attribute (user-declared addressable elements)
+  //   - data-bw_id attribute (user-declared addressable elements)
   //   - id attribute (standard HTML id)
   //   - bw_uuid (internal, for lifecycle-managed elements)
   //
@@ -207,58 +217,7 @@ bw._getFs = function() {
  * // baseTypeOnly mode:
  * bw.typeOf([1,2], true)     // => "object"
  */
-bw.typeOf = function(x, baseTypeOnly) {
-  if (x === null) return "null";
-  
-  const basic = typeof x;
-  
-  if (basic !== "object") {
-    return basic;  // covers: string, number, boolean, undefined, function, symbol, bigint
-  }
-
-  if (baseTypeOnly) return basic;
-  
-  const stringTag = Object.prototype.toString.call(x);
-  
-  const typeMap = {
-    '[object Array]': 'array',
-    '[object Date]': 'Date',
-    '[object RegExp]': 'RegExp',
-    '[object Error]': 'Error',
-    '[object Promise]': 'Promise',
-    '[object Map]': 'Map',
-    '[object Set]': 'Set',
-    '[object WeakMap]': 'WeakMap',
-    '[object WeakSet]': 'WeakSet',
-    '[object ArrayBuffer]': 'ArrayBuffer',
-    '[object DataView]': 'DataView',
-    '[object Int8Array]': 'Int8Array',
-    '[object Uint8Array]': 'Uint8Array',
-    '[object Uint8ClampedArray]': 'Uint8ClampedArray',
-    '[object Int16Array]': 'Int16Array',
-    '[object Uint16Array]': 'Uint16Array',
-    '[object Int32Array]': 'Int32Array',
-    '[object Uint32Array]': 'Uint32Array',
-    '[object Float32Array]': 'Float32Array',
-    '[object Float64Array]': 'Float64Array'
-  };
-  
-  if (typeMap[stringTag]) {
-    return typeMap[stringTag];
-  }
-  
-  // Check for custom bitwrench types
-  if (x._bw_type) {
-    return x._bw_type;
-  }
-  
-  // Try constructor name
-  if (x.constructor && x.constructor.name) {
-    return x.constructor.name;
-  }
-  
-  return basic;
-};
+bw.typeOf = _typeOf;
 
 // Alias
 bw.to = bw.typeOf;
@@ -308,9 +267,9 @@ bw.uuid = function(prefix) {
  * Accepts a DOM element directly (pass-through) or a string identifier.
  * String identifiers are tried as: direct map key, getElementById,
  * querySelector (for CSS selectors starting with . or #), and
- * data-bw-id attribute selector.
+ * data-bw_id attribute selector.
  *
- * @param {string|Element} id - Element ID, CSS selector, data-bw-id value, or DOM element
+ * @param {string|Element} id - Element ID, CSS selector, data-bw_id value, or DOM element
  * @returns {Element|null} The DOM element, or null if not found
  * @category Internal
  */
@@ -339,9 +298,9 @@ bw._el = function(id) {
     el = document.querySelector(id);
   }
 
-  // 4. Try data-bw-id attribute (for bw.uuid-generated IDs)
+  // 4. Try data-bw_id attribute (for bw.uuid-generated IDs)
   if (!el) {
-    el = document.querySelector('[data-bw-id="' + id + '"]');
+    el = document.querySelector('[data-bw_id="' + id + '"]');
   }
 
   // 5. Cache the result for next time
@@ -356,15 +315,15 @@ bw._el = function(id) {
  * Register a DOM element in the node cache under one or more keys.
  *
  * Called internally by `bw.createDOM()`. Registers elements that have
- * id attributes, data-bw-id attributes, or both.
+ * id attributes, data-bw_id attributes, or both.
  *
  * @param {Element} el - DOM element to register
- * @param {string} [bwId] - data-bw-id value to register under
+ * @param {string} [bwId] - data-bw_id value to register under
  * @category Internal
  */
 bw._registerNode = function(el, bwId) {
   if (!el) return;
-  // Register under data-bw-id
+  // Register under data-bw_id
   if (bwId) {
     bw._nodeMap[bwId] = el;
   }
@@ -382,11 +341,11 @@ bw._registerNode = function(el, bwId) {
  * through bitwrench APIs.
  *
  * @param {Element} el - DOM element to deregister
- * @param {string} [bwId] - data-bw-id value to remove
+ * @param {string} [bwId] - data-bw_id value to remove
  * @category Internal
  */
 bw._deregisterNode = function(el, bwId) {
-  // Remove data-bw-id entry
+  // Remove data-bw_id entry
   if (bwId) {
     delete bw._nodeMap[bwId];
   }
@@ -446,23 +405,6 @@ bw.raw = function(str) {
   return { __bw_raw: true, v: String(str) };
 };
 
-/**
- * Normalize CSS class names by converting underscores to hyphens for bw-prefixed classes.
- *
- * Allows users to write either `bw_card` or `bw-card` and get consistent
- * hyphenated output. Only converts the `bw_` prefix — other underscores are untouched.
- *
- * @param {string} classStr - Class string to normalize
- * @returns {string} Normalized class string with hyphens
- * @category Identifiers
- * @example
- * bw.normalizeClass('bw_card bw_btn')  // => 'bw-card bw-btn'
- * bw.normalizeClass('my_class')         // => 'my_class' (unchanged)
- */
-bw.normalizeClass = function(classStr) {
-  if (typeof classStr !== 'string') return classStr;
-  return classStr.replace(/\bbw_/g, 'bw-');
-};
 
 /**
  * Convert a TACO object (or array of TACOs) to an HTML string.
@@ -491,20 +433,52 @@ bw.normalizeClass = function(classStr) {
 bw.html = function(taco, options = {}) {
   // Handle null/undefined
   if (taco == null) return '';
-  
+
+  // Handle ComponentHandle — use its .taco
+  if (taco && taco._bwComponent === true) {
+    var compOptions = Object.assign({}, options);
+    if (!compOptions.state && taco._state) {
+      compOptions.state = taco._state;
+    }
+    return bw.html(taco.taco, compOptions);
+  }
+
   // Handle arrays of TACOs
   if (Array.isArray(taco)) {
     return taco.map(t => bw.html(t, options)).join('');
   }
-  
+
   // Handle bw.raw() marked content
   if (taco && taco.__bw_raw) {
     return taco.v;
   }
 
+  // Handle bw.when() markers
+  if (taco && taco._bwWhen && options.state) {
+    var whenExpr = taco.expr.replace(/^\$\{|\}$/g, '');
+    var whenVal = options.compile
+      ? bw._resolveTemplate('${' + whenExpr + '}', options.state, true)
+      : bw._evaluatePath(options.state, whenExpr);
+    var branch = whenVal ? taco.branches[0] : (taco.branches[1] || null);
+    return branch ? bw.html(branch, options) : '';
+  }
+
+  // Handle bw.each() markers
+  if (taco && taco._bwEach && options.state) {
+    var eachExpr = taco.expr.replace(/^\$\{|\}$/g, '');
+    var arr = bw._evaluatePath(options.state, eachExpr);
+    if (!Array.isArray(arr)) return '';
+    return arr.map(function(item, idx) { return bw.html(taco.factory(item, idx), options); }).join('');
+  }
+
   // Handle primitives and non-TACO objects
   if (typeof taco !== 'object' || !taco.t) {
-    return options.raw ? String(taco) : bw.escapeHTML(String(taco));
+    var str = options.raw ? String(taco) : bw.escapeHTML(String(taco));
+    // Resolve template bindings if state provided
+    if (options.state && typeof str === 'string' && str.indexOf('${') >= 0) {
+      str = bw._resolveTemplate(str, options.state, !!options.compile);
+    }
+    return str;
   }
   
   const { t: tag, a: attrs = {}, c: content, o: opts = {} } = taco;
@@ -534,12 +508,8 @@ bw.html = function(taco, options = {}) {
         attrStr += ` style="${bw.escapeHTML(styleStr)}"`;
       }
     } else if (key === 'class') {
-      // Handle class as array or string, normalize bw_ to bw-
-      const classStr = bw.normalizeClass(
-        Array.isArray(value)
-          ? value.filter(Boolean).join(' ')
-          : String(value)
-      );
+      // Handle class as array or string
+      const classStr = Array.isArray(value) ? value.filter(Boolean).join(' ') : String(value);
       if (classStr) {
         attrStr += ` class="${bw.escapeHTML(classStr)}"`;
       }
@@ -547,19 +517,23 @@ bw.html = function(taco, options = {}) {
       // Boolean attributes
       attrStr += ` ${key}`;
     } else {
-      // Regular attributes
-      attrStr += ` ${key}="${bw.escapeHTML(String(value))}"`;
+      // Regular attributes — resolve ${expr} if state provided
+      let resolvedVal = String(value);
+      if (options.state && resolvedVal.indexOf('${') >= 0) {
+        resolvedVal = bw._resolveTemplate(resolvedVal, options.state, !!options.compile);
+      }
+      attrStr += ` ${key}="${bw.escapeHTML(resolvedVal)}"`;
     }
   }
 
-  // Add bw-id as a class if lifecycle hooks present
-  if ((opts.mounted || opts.unmount) && !attrs.class?.includes('bw-id-')) {
+  // Add bw_id as a class if lifecycle hooks present
+  if ((opts.mounted || opts.unmount) && !attrs.class?.includes('bw_id_')) {
     const id = opts.bw_id || bw.uuid();
     attrStr = attrStr.replace(/class="([^"]*)"/, (_match, classes) => {
-      return `class="${classes} bw-id-${id}"`.trim();
+      return `class="${classes} bw_id_${id}"`.trim();
     });
     if (!attrStr.includes('class=')) {
-      attrStr += ` class="bw-id-${id}"`;
+      attrStr += ` class="bw_id_${id}"`;
     }
   }
   
@@ -569,8 +543,12 @@ bw.html = function(taco, options = {}) {
   }
   
   // Process content recursively
-  const contentStr = content != null ? bw.html(content, options) : '';
-  
+  let contentStr = content != null ? bw.html(content, options) : '';
+  // Resolve template bindings in content if state provided
+  if (options.state && typeof contentStr === 'string' && contentStr.indexOf('${') >= 0) {
+    contentStr = bw._resolveTemplate(contentStr, options.state, !!options.compile);
+  }
+
   return `<${tag}${attrStr}>${contentStr}</${tag}>`;
 };
 
@@ -590,7 +568,7 @@ bw.html = function(taco, options = {}) {
  * @example
  * var el = bw.createDOM({
  *   t: 'button',
- *   a: { class: 'bw-btn', onclick: () => alert('clicked') },
+ *   a: { class: 'bw_btn', onclick: () => alert('clicked') },
  *   c: 'Click Me'
  * });
  * document.body.appendChild(el);
@@ -612,6 +590,11 @@ bw.createDOM = function(taco, options = {}) {
     return frag;
   }
 
+  // Handle ComponentHandle — extract .taco for DOM creation
+  if (taco && taco._bwComponent === true) {
+    return bw.createDOM(taco.taco, options);
+  }
+
   // Handle text nodes
   if (typeof taco !== 'object' || !taco.t) {
     return document.createTextNode(String(taco));
@@ -630,12 +613,8 @@ bw.createDOM = function(taco, options = {}) {
       // Apply styles directly
       Object.assign(el.style, value);
     } else if (key === 'class') {
-      // Handle class as array or string, normalize bw_ to bw-
-      const classStr = bw.normalizeClass(
-        Array.isArray(value)
-          ? value.filter(Boolean).join(' ')
-          : String(value)
-      );
+      // Handle class as array or string
+      const classStr = Array.isArray(value) ? value.filter(Boolean).join(' ') : String(value);
       if (classStr) {
         el.className = classStr;
       }
@@ -656,16 +635,21 @@ bw.createDOM = function(taco, options = {}) {
   }
   
   // Add children, building _bw_refs for fast parent→child access.
-  // Children with data-bw-id or id attributes get local refs on the parent,
+  // Children with data-bw_id or id attributes get local refs on the parent,
   // so o.render functions can access them without any DOM lookup.
   if (content != null) {
     if (Array.isArray(content)) {
       content.forEach(child => {
         if (child != null) {
+          // Handle ComponentHandle in content arrays (Level 2 children)
+          if (child._bwComponent === true) {
+            child.mount(el);
+            return;
+          }
           var childEl = bw.createDOM(child, options);
           el.appendChild(childEl);
           // Build local refs for addressable children
-          var childBwId = (child && child.a) ? (child.a['data-bw-id'] || child.a.id) : null;
+          var childBwId = (child && child.a) ? (child.a['data-bw_id'] || child.a.id) : null;
           if (childBwId) {
             if (!el._bw_refs) el._bw_refs = {};
             el._bw_refs[childBwId] = childEl;
@@ -684,10 +668,13 @@ bw.createDOM = function(taco, options = {}) {
     } else if (typeof content === 'object' && content.__bw_raw) {
       // Raw HTML content — inject via innerHTML
       el.innerHTML = content.v;
+    } else if (content._bwComponent === true) {
+      // Single ComponentHandle as content
+      content.mount(el);
     } else if (typeof content === 'object' && content.t) {
       var childEl = bw.createDOM(content, options);
       el.appendChild(childEl);
-      var childBwId = content.a ? (content.a['data-bw-id'] || content.a.id) : null;
+      var childBwId = content.a ? (content.a['data-bw_id'] || content.a.id) : null;
       if (childBwId) {
         if (!el._bw_refs) el._bw_refs = {};
         el._bw_refs[childBwId] = childEl;
@@ -712,10 +699,10 @@ bw.createDOM = function(taco, options = {}) {
 
   // Handle lifecycle hooks and state
   if (opts.mounted || opts.unmount || opts.render || opts.state) {
-    const id = attrs['data-bw-id'] || bw.uuid();
-    el.setAttribute('data-bw-id', id);
+    const id = attrs['data-bw_id'] || bw.uuid();
+    el.setAttribute('data-bw_id', id);
 
-    // Register in node cache under data-bw-id
+    // Register in node cache under data-bw_id
     bw._registerNode(el, id);
 
     // Store state
@@ -760,9 +747,9 @@ bw.createDOM = function(taco, options = {}) {
         opts.unmount(el, el._bw_state || {});
       });
     }
-  } else if (attrs['data-bw-id']) {
-    // Element has explicit data-bw-id but no lifecycle hooks — still register it
-    bw._registerNode(el, attrs['data-bw-id']);
+  } else if (attrs['data-bw_id']) {
+    // Element has explicit data-bw_id but no lifecycle hooks — still register it
+    bw._registerNode(el, attrs['data-bw_id']);
   }
 
   return el;
@@ -809,7 +796,7 @@ bw.DOM = function(target, taco, options = {}) {
   // the target is the mount point, not the content being replaced)
   const savedState = targetEl._bw_state;
   const savedRender = targetEl._bw_render;
-  const savedBwId = targetEl.getAttribute('data-bw-id');
+  const savedBwId = targetEl.getAttribute('data-bw_id');
   const savedSubs = targetEl._bw_subs;
 
   // Temporarily remove _bw_subs so cleanup doesn't call them
@@ -822,7 +809,7 @@ bw.DOM = function(target, taco, options = {}) {
   if (savedState !== undefined) targetEl._bw_state = savedState;
   if (savedRender) targetEl._bw_render = savedRender;
   if (savedBwId) {
-    targetEl.setAttribute('data-bw-id', savedBwId);
+    targetEl.setAttribute('data-bw_id', savedBwId);
     // Re-register mount point in node cache (cleanup deregistered it)
     bw._registerNode(targetEl, savedBwId);
   }
@@ -832,15 +819,21 @@ bw.DOM = function(target, taco, options = {}) {
   targetEl.innerHTML = '';
   
   if (taco != null) {
+    // Handle ComponentHandle (reactive components from bw.component())
+    if (taco._bwComponent === true) {
+      taco.mount(targetEl);
+    }
     // Handle component handles (objects with element property)
-    if (taco.element instanceof Element) {
+    else if (taco.element instanceof Element) {
       targetEl.appendChild(taco.element);
     }
     // Handle arrays
     else if (Array.isArray(taco)) {
       taco.forEach(t => {
         if (t != null) {
-          if (t.element instanceof Element) {
+          if (t._bwComponent === true) {
+            t.mount(targetEl);
+          } else if (t.element instanceof Element) {
             targetEl.appendChild(t.element);
           } else {
             targetEl.appendChild(bw.createDOM(t, options));
@@ -1076,11 +1069,11 @@ bw.renderComponent = function(taco, options = {}) {
 bw.cleanup = function(element) {
   if (!bw._isBrowser || !element) return;
 
-  // Find all elements with data-bw-id
-  const elements = element.querySelectorAll('[data-bw-id]');
+  // Find all elements with data-bw_id
+  const elements = element.querySelectorAll('[data-bw_id]');
 
   elements.forEach(el => {
-    const id = el.getAttribute('data-bw-id');
+    const id = el.getAttribute('data-bw_id');
     const callback = bw._unmountCallbacks.get(id);
 
     if (callback) {
@@ -1104,7 +1097,7 @@ bw.cleanup = function(element) {
   });
 
   // Check element itself
-  const id = element.getAttribute('data-bw-id');
+  const id = element.getAttribute('data-bw_id');
   if (id) {
     const callback = bw._unmountCallbacks.get(id);
     if (callback) {
@@ -1123,6 +1116,13 @@ bw.cleanup = function(element) {
     delete element._bw_state;
     delete element._bw_render;
     delete element._bw_refs;
+
+    // Clean up ComponentHandle back-reference
+    if (element._bwComponentHandle) {
+      element._bwComponentHandle.mounted = false;
+      element._bwComponentHandle.element = null;
+      delete element._bwComponentHandle;
+    }
   }
 };
 
@@ -1137,7 +1137,7 @@ bw.cleanup = function(element) {
  * Calls `el._bw_render(el, state)` and emits `bw:statechange` so other
  * components can react without tight coupling.
  *
- * @param {string|Element} target - Element ID, data-bw-id, CSS selector, or DOM element
+ * @param {string|Element} target - Element ID, data-bw_id, CSS selector, or DOM element
  * @returns {Element|null} The element, or null if not found / no render function
  * @category State Management
  * @see bw.patch
@@ -1162,7 +1162,7 @@ bw.update = function(target) {
  * Use `bw.patch()` for lightweight value updates (scores, labels, counters)
  * and `bw.update()` for full structural re-renders.
  *
- * @param {string|Element} id - Element ID, data-bw-id, CSS selector, or DOM element.
+ * @param {string|Element} id - Element ID, data-bw_id, CSS selector, or DOM element.
  *   Uses node cache for O(1) lookup; falls back to DOM query on cache miss.
  * @param {string|Object} content - New text content, or TACO object to replace children
  * @param {string} [attr] - If provided, sets this attribute instead of content
@@ -1237,7 +1237,7 @@ bw.patchAll = function(patches) {
  * bubble by default so ancestor elements can listen. Use with `bw.on()` for
  * DOM-scoped communication between components.
  *
- * @param {string|Element} target - Element ID, data-bw-id, CSS selector, or DOM element.
+ * @param {string|Element} target - Element ID, data-bw_id, CSS selector, or DOM element.
  *   Uses node cache for O(1) lookup; falls back to DOM query on cache miss.
  * @param {string} eventName - Event name (will be prefixed with 'bw:')
  * @param {*} [detail] - Data to pass with the event
@@ -1264,7 +1264,7 @@ bw.emit = function(target, eventName, detail) {
  * is the first argument so you don't need to destructure `e.detail`.
  * Events bubble, so you can listen on an ancestor element.
  *
- * @param {string|Element} target - Element ID, data-bw-id, CSS selector, or DOM element.
+ * @param {string|Element} target - Element ID, data-bw_id, CSS selector, or DOM element.
  *   Uses node cache for O(1) lookup; falls back to DOM query on cache miss.
  * @param {string} eventName - Event name (will be prefixed with 'bw:')
  * @param {Function} handler - Called with (detail, event)
@@ -1362,10 +1362,10 @@ bw.sub = function(topic, handler, el) {
   if (el) {
     if (!el._bw_subs) el._bw_subs = [];
     el._bw_subs.push(unsub);
-    // Ensure element has data-bw-id so bw.cleanup() finds it
-    if (!el.getAttribute('data-bw-id')) {
+    // Ensure element has data-bw_id so bw.cleanup() finds it
+    if (!el.getAttribute('data-bw_id')) {
       var bwId = 'bw_sub_' + id;
-      el.setAttribute('data-bw-id', bwId);
+      el.setAttribute('data-bw_id', bwId);
     }
   }
 
@@ -1394,173 +1394,1490 @@ bw.unsub = function(topic, handler) {
   return removed;
 };
 
+// ===================================================================================
+// Function Registry (revived from v1 for string dispatch contexts)
+// ===================================================================================
+
+bw._fnRegistry = {};
+bw._fnIDCounter = 0;
+
+/**
+ * Register a function in the global function registry.
+ *
+ * Registered functions can be invoked by name in HTML string contexts
+ * (e.g., onclick attributes) via `bw.funcGetById()`. Useful for
+ * serializable event handlers, LLM wire format, and SSR.
+ *
+ * @param {Function} fn - Function to register
+ * @param {string} [name] - Optional name. Auto-generated if omitted.
+ * @returns {string} The registered name (use for dispatch)
+ * @category Function Registry
+ * @see bw.funcGetById
+ * @see bw.funcGetDispatchStr
+ */
+bw.funcRegister = function(fn, name) {
+  if (typeof fn !== 'function') return '';
+  var fnID = (typeof name === 'string' && name.length > 0) ? name : ('bw_fn_' + bw._fnIDCounter++);
+  bw._fnRegistry[fnID] = fn;
+  return fnID;
+};
+
 /**
- * Generate CSS from JavaScript objects.
+ * Retrieve a registered function by name.
  *
- * Converts an object of `{ selector: { prop: value } }` rules into a CSS string.
- * CamelCase property names are auto-converted to kebab-case (e.g. `fontSize` → `font-size`).
- * Accepts nested arrays of rule objects.
+ * Returns the function if found, or `errFn` (or a no-op logger) if not.
  *
- * @param {Object|Array|string} rules - CSS rules as JS objects, array of rule objects, or raw CSS string
- * @param {Object} [options] - Generation options
- * @param {boolean} [options.minify=false] - Minify output (no whitespace)
- * @returns {string} CSS string
- * @category CSS & Styling
- * @see bw.injectCSS
- * @example
- * bw.css({
- *   '.card': { padding: '1rem', fontSize: '14px', borderRadius: '8px' }
- * })
- * // => '.card {\n  padding: 1rem;\n  font-size: 14px;\n  border-radius: 8px;\n}'
+ * @param {string} name - Registered function name
+ * @param {Function} [errFn] - Fallback if not found
+ * @returns {Function} The registered function or fallback
+ * @category Function Registry
+ * @see bw.funcRegister
  */
-bw.css = function(rules, options = {}) {
-  const { minify = false, pretty = !minify } = options;
+bw.funcGetById = function(name, errFn) {
+  name = String(name);
+  if (name in bw._fnRegistry) return bw._fnRegistry[name];
+  return (typeof errFn === 'function') ? errFn : function() { console.warn('bw.funcGetById: unregistered fn "' + name + '"'); };
+};
 
-  if (typeof rules === 'string') return rules;
+/**
+ * Generate a dispatch string suitable for inline HTML event attributes.
+ *
+ * @param {string} name - Registered function name
+ * @param {string} [argStr=''] - Arguments string (literal, not variable names)
+ * @returns {string} Dispatch string like `"bw.funcGetById('name')(args)"`
+ * @category Function Registry
+ * @see bw.funcRegister
+ */
+bw.funcGetDispatchStr = function(name, argStr) {
+  argStr = (argStr != null) ? String(argStr) : '';
+  return "bw.funcGetById('" + name + "')(" + argStr + ")";
+};
 
-  let css = '';
-  const indent = pretty ? '  ' : '';
-  const newline = pretty ? '\n' : '';
-  const space = pretty ? ' ' : '';
+/**
+ * Remove a function from the registry.
+ *
+ * @param {string} name - Registered function name
+ * @returns {boolean} True if removed, false if not found
+ * @category Function Registry
+ */
+bw.funcUnregister = function(name) {
+  if (name in bw._fnRegistry) {
+    delete bw._fnRegistry[name];
+    return true;
+  }
+  return false;
+};
 
-  if (Array.isArray(rules)) {
-    css = rules.map(rule => bw.css(rule, options)).join(newline);
-  } else if (typeof rules === 'object') {
-    Object.entries(rules).forEach(([selector, styles]) => {
-      if (typeof styles === 'object' && !Array.isArray(styles)) {
-        // Handle @media, @keyframes, @supports — recurse into nested block
-        if (selector.charAt(0) === '@') {
-          const inner = bw.css(styles, options);
-          if (inner) {
-            css += `${selector}${space}{${newline}${inner}${newline}}${newline}`;
-          }
-          return;
-        }
-        const declarations = Object.entries(styles)
-          .filter(([, value]) => value != null)
-          .map(([prop, value]) => {
-            // Convert camelCase to kebab-case
-            const kebabProp = prop.replace(/[A-Z]/g, m => '-' + m.toLowerCase());
-            return `${indent}${kebabProp}:${space}${value};`;
-          })
-          .join(newline);
+/**
+ * Get a shallow copy of the function registry for inspection.
+ *
+ * @returns {Object} Copy of registry (name → function)
+ * @category Function Registry
+ */
+bw.funcGetRegistry = function() {
+  var copy = {};
+  for (var k in bw._fnRegistry) {
+    if (Object.prototype.hasOwnProperty.call(bw._fnRegistry, k)) {
+      copy[k] = bw._fnRegistry[k];
+    }
+  }
+  return copy;
+};
 
-        if (declarations) {
-          css += `${selector}${space}{${newline}${declarations}${newline}}${newline}`;
-        }
-      }
-    });
+// ===================================================================================
+// Template Binding Utilities
+// ===================================================================================
+
+/**
+ * Parse binding expressions from a template string.
+ * Returns array of {start, end, expr} for each `${expr}` found.
+ * @private
+ */
+bw._parseBindings = function(str) {
+  var results = [];
+  var re = /\$\{([^}]+)\}/g;
+  var match;
+  while ((match = re.exec(str)) !== null) {
+    results.push({ start: match.index, end: match.index + match[0].length, expr: match[1].trim() });
   }
+  return results;
+};
 
-  return css.trim();
+/**
+ * Evaluate a dot-path on a state object. Returns empty string for null/undefined.
+ * @private
+ */
+bw._evaluatePath = function(state, path) {
+  var parts = path.split('.');
+  var val = state;
+  for (var i = 0; i < parts.length; i++) {
+    if (val == null) return '';
+    val = val[parts[i]];
+  }
+  return (val == null) ? '' : val;
 };
 
 /**
- * Inject CSS into the document head (browser only).
+ * Resolve all `${expr}` bindings in a template string against a state object.
  *
- * Creates or reuses a `<style>` element (identified by `id`). Can accept
- * raw CSS strings or JS rule objects (which are converted via `bw.css()`).
- * By default appends to existing content; set `append: false` to replace.
+ * Tier 1 (default): dot-path lookup only (CSP-safe).
+ * Tier 2 (compile=true): uses new Function for complex expressions.
  *
- * @param {string|Object|Array} css - CSS string, or JS rule objects to convert
- * @param {Object} [options] - Injection options
- * @param {string} [options.id='bw-styles'] - ID for the style element
- * @param {boolean} [options.append=true] - Append to existing CSS (false to replace)
- * @returns {Element} The style element
- * @category CSS & Styling
- * @see bw.css
- * @see bw.loadDefaultStyles
- * @example
- * bw.injectCSS('.my-class { color: red; }');
- * bw.injectCSS({ '.card': { padding: '1rem' } }, { id: 'card-styles' });
+ * @param {string} str - Template string
+ * @param {Object} state - State object
+ * @param {boolean} [compile=false] - Use Tier 2 evaluation
+ * @returns {string} Resolved string
+ * @private
  */
-bw.injectCSS = function(css, options = {}) {
-  if (!bw._isBrowser) {
-    console.warn('bw.injectCSS requires a DOM environment');
-    return null;
+bw._compiledExprs = {};
+bw._resolveTemplate = function(str, state, compile) {
+  if (typeof str !== 'string' || str.indexOf('${') < 0) return str;
+  var bindings = bw._parseBindings(str);
+  if (bindings.length === 0) return str;
+
+  var result = '';
+  var lastEnd = 0;
+  for (var i = 0; i < bindings.length; i++) {
+    var b = bindings[i];
+    result += str.slice(lastEnd, b.start);
+    var val;
+    if (compile) {
+      // Tier 2: new Function evaluator (cached)
+      if (!bw._compiledExprs[b.expr]) {
+        try {
+          bw._compiledExprs[b.expr] = new Function('state', 'with(state){return (' + b.expr + ');}');
+        } catch (e) {
+          bw._compiledExprs[b.expr] = function() { return ''; };
+        }
+      }
+      try {
+        val = bw._compiledExprs[b.expr](state);
+      } catch (e) {
+        val = '';
+      }
+    } else {
+      // Tier 1: dot-path only
+      val = bw._evaluatePath(state, b.expr);
+    }
+    result += (val == null) ? '' : String(val);
+    lastEnd = b.end;
   }
-  
-  const { id = 'bw-styles', append = true } = options;
-  
-  // Get or create style element
-  let styleEl = document.getElementById(id);
-  
-  if (!styleEl) {
-    styleEl = document.createElement('style');
-    styleEl.id = id;
-    styleEl.type = 'text/css';
-    document.head.appendChild(styleEl);
+  result += str.slice(lastEnd);
+  return result;
+};
+
+/**
+ * Extract top-level state keys that an expression depends on.
+ * @param {string} expr - Expression string
+ * @param {string[]} stateKeys - Declared state keys
+ * @returns {string[]} Matching dependency keys
+ * @private
+ */
+bw._extractDeps = function(expr, stateKeys) {
+  var deps = [];
+  for (var i = 0; i < stateKeys.length; i++) {
+    var key = stateKeys[i];
+    // Match word boundary: key must be preceded by start/non-word and followed by non-word/end
+    var re = new RegExp('(?:^|[^\\w$.])' + key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '(?:[^\\w$]|$)');
+    if (re.test(expr) || expr === key || expr.indexOf(key + '.') === 0) {
+      deps.push(key);
+    }
   }
-  
-  // Convert CSS if needed
-  const cssStr = typeof css === 'string' ? css : bw.css(css, options);
-  
-  // Set or append CSS
-  if (append && styleEl.textContent) {
-    styleEl.textContent += '\n' + cssStr;
+  return deps;
+};
+
+// ===================================================================================
+// Microtask Batching
+// ===================================================================================
+
+bw._dirtyComponents = [];
+bw._flushScheduled = false;
+
+/**
+ * Schedule a microtask flush for dirty components.
+ * @private
+ */
+bw._scheduleFlush = function() {
+  if (bw._flushScheduled) return;
+  bw._flushScheduled = true;
+  if (typeof Promise !== 'undefined') {
+    Promise.resolve().then(bw._doFlush);
   } else {
-    styleEl.textContent = cssStr;
+    setTimeout(bw._doFlush, 0);
   }
-  
-  return styleEl;
 };
 
 /**
- * Merge multiple style objects into one (left-to-right).
- *
- * Like `Object.assign()` for styles, but filters out null/undefined arguments.
- * Compose inline styles or CSS rule objects without mutation.
- *
- * @param {...Object} styles - Style objects to merge (left-to-right)
- * @returns {Object} Merged style object
- * @category CSS & Styling
- * @see bw.u
- * @example
- * var style = bw.s(bw.u.flex, bw.u.gap4, { color: 'red' });
- * // => { display: 'flex', gap: '1rem', color: 'red' }
+ * Flush all dirty components. Deduplicates by _bwId.
+ * @private
  */
-bw.s = function() {
-  var result = {};
-  for (var i = 0; i < arguments.length; i++) {
-    var arg = arguments[i];
-    if (arg && typeof arg === 'object') Object.assign(result, arg);
+bw._doFlush = function() {
+  bw._flushScheduled = false;
+  var queue = bw._dirtyComponents.slice();
+  bw._dirtyComponents = [];
+  // Deduplicate by _bwId
+  var seen = {};
+  for (var i = 0; i < queue.length; i++) {
+    var comp = queue[i];
+    if (!seen[comp._bwId]) {
+      seen[comp._bwId] = true;
+      comp._flush();
+    }
   }
-  return result;
 };
 
 /**
- * Pre-built CSS utility objects (like Tailwind utilities, but in JS).
+ * Synchronous flush for testing and imperative code.
+ * Forces immediate re-render of all dirty components.
  *
- * Compose with `bw.s()` to build inline styles without writing raw CSS strings.
- * Includes flex, padding, margin, typography, color, border, and transition utilities.
+ * @category Component
+ */
+bw.flush = function() {
+  bw._doFlush();
+};
+
+// ===================================================================================
+// ComponentHandle — unified reactive component (Phase 1)
+// ===================================================================================
+
+/**
+ * ComponentHandle constructor.
+ * Wraps a TACO definition with reactive state, lifecycle hooks,
+ * template bindings, and named actions.
  *
- * @category CSS & Styling
- * @see bw.s
- * @example
- * { t: 'div', a: { style: bw.s(bw.u.flex, bw.u.gap4, bw.u.p4) },
- *   c: 'Flexbox with 1rem gap and padding' }
+ * @param {Object} taco - TACO definition {t, a, c, o}
+ * @constructor
+ * @private
  */
-bw.u = {
-  // Display
-  flex: { display: 'flex' },
-  flexCol: { display: 'flex', flexDirection: 'column' },
-  flexRow: { display: 'flex', flexDirection: 'row' },
-  flexWrap: { display: 'flex', flexWrap: 'wrap' },
-  block: { display: 'block' },
-  inline: { display: 'inline' },
-  hidden: { display: 'none' },
+function ComponentHandle(taco) {
+  this._bwComponent = true;         // duck-type marker
+  this._bwId = bw.uuid('comp');
+  this.taco = taco;
+  this.element = null;
+  this.mounted = false;
+
+  var o = taco.o || {};
+  // Copy initial state
+  this._state = {};
+  if (o.state) {
+    for (var k in o.state) {
+      if (Object.prototype.hasOwnProperty.call(o.state, k)) {
+        this._state[k] = o.state[k];
+      }
+    }
+  }
+  // Copy actions
+  this._actions = {};
+  if (o.actions) {
+    for (var k2 in o.actions) {
+      if (Object.prototype.hasOwnProperty.call(o.actions, k2)) {
+        this._actions[k2] = o.actions[k2];
+      }
+    }
+  }
+  // Promote o.methods to handle API (MFC/Qt pattern: component owns its methods)
+  this._methods = {};
+  if (o.methods) {
+    var self = this;
+    for (var k3 in o.methods) {
+      if (Object.prototype.hasOwnProperty.call(o.methods, k3)) {
+        this._methods[k3] = o.methods[k3];
+        (function(methodName, methodFn) {
+          self[methodName] = function() {
+            var args = [self].concat(Array.prototype.slice.call(arguments));
+            return methodFn.apply(null, args);
+          };
+        })(k3, o.methods[k3]);
+      }
+    }
+  }
+  // User tag for addressing via bw.message()
+  this._userTag = null;
+  // Lifecycle hooks
+  this._hooks = {
+    willMount: o.willMount || null,
+    mounted: o.mounted || null,
+    willUpdate: o.willUpdate || null,
+    onUpdate: o.onUpdate || null,
+    unmount: o.unmount || null,
+    willDestroy: o.willDestroy || null
+  };
+  // Binding tracking
+  this._bindings = [];
+  this._dirtyKeys = {};
+  this._scheduled = false;
+  this._subs = [];
+  this._eventListeners = [];
+  this._registeredActions = [];
+  this._prevValues = {};
+  this._compile = !!o.compile;
+  this._bw_refs = {};
+  this._refCounter = 0;
+}
 
-  // Flex alignment
-  justifyCenter: { justifyContent: 'center' },
-  justifyBetween: { justifyContent: 'space-between' },
-  justifyEnd: { justifyContent: 'flex-end' },
-  alignCenter: { alignItems: 'center' },
-  alignStart: { alignItems: 'flex-start' },
-  alignEnd: { alignItems: 'flex-end' },
+// ── State Methods ──
 
-  // Gap (0.25rem increments)
-  gap1: { gap: '0.25rem' },
-  gap2: { gap: '0.5rem' },
+/**
+ * Get a state value. Dot-path supported: `get('user.name')`
+ */
+ComponentHandle.prototype.get = function(key) {
+  return bw._evaluatePath(this._state, key);
+};
+
+/**
+ * Set a state value. Dot-path supported. Schedules re-render.
+ * @param {string} key - State key (dot-path)
+ * @param {*} value - New value
+ * @param {Object} [opts] - Options. `{sync: true}` for immediate flush.
+ */
+ComponentHandle.prototype.set = function(key, value, opts) {
+  // Dot-path set
+  var parts = key.split('.');
+  var obj = this._state;
+  for (var i = 0; i < parts.length - 1; i++) {
+    if (obj[parts[i]] == null || typeof obj[parts[i]] !== 'object') {
+      obj[parts[i]] = {};
+    }
+    obj = obj[parts[i]];
+  }
+  obj[parts[parts.length - 1]] = value;
+  // Mark top-level key dirty
+  this._dirtyKeys[parts[0]] = true;
+  if (this.mounted) {
+    if (opts && opts.sync) {
+      this._flush();
+    } else {
+      this._scheduleDirty();
+    }
+  }
+};
+
+/**
+ * Get a shallow clone of the full state.
+ */
+ComponentHandle.prototype.getState = function() {
+  var clone = {};
+  for (var k in this._state) {
+    if (Object.prototype.hasOwnProperty.call(this._state, k)) {
+      clone[k] = this._state[k];
+    }
+  }
+  return clone;
+};
+
+/**
+ * Merge multiple state keys. Schedules re-render.
+ * @param {Object} updates - Key-value pairs to merge
+ * @param {Object} [opts] - Options. `{sync: true}` for immediate flush.
+ */
+ComponentHandle.prototype.setState = function(updates, opts) {
+  for (var k in updates) {
+    if (Object.prototype.hasOwnProperty.call(updates, k)) {
+      this._state[k] = updates[k];
+      this._dirtyKeys[k] = true;
+    }
+  }
+  if (this.mounted) {
+    if (opts && opts.sync) {
+      this._flush();
+    } else {
+      this._scheduleDirty();
+    }
+  }
+};
+
+/**
+ * Push a value onto an array in state. Clones the array.
+ */
+ComponentHandle.prototype.push = function(key, val) {
+  var arr = this.get(key);
+  var newArr = Array.isArray(arr) ? arr.slice() : [];
+  newArr.push(val);
+  this.set(key, newArr);
+};
+
+/**
+ * Splice an array in state. Clones the array.
+ */
+ComponentHandle.prototype.splice = function(key, start, deleteCount) {
+  var arr = this.get(key);
+  var newArr = Array.isArray(arr) ? arr.slice() : [];
+  var args = [start, deleteCount].concat(Array.prototype.slice.call(arguments, 3));
+  Array.prototype.splice.apply(newArr, args);
+  this.set(key, newArr);
+};
+
+// ── Scheduling ──
+
+ComponentHandle.prototype._scheduleDirty = function() {
+  if (!this._scheduled) {
+    this._scheduled = true;
+    bw._dirtyComponents.push(this);
+    bw._scheduleFlush();
+  }
+};
+
+// ── Binding Compilation ──
+
+/**
+ * Walk the TACO tree and extract ${expr} bindings.
+ * Creates binding descriptors with refIds for targeted DOM updates.
+ * @private
+ */
+ComponentHandle.prototype._compileBindings = function() {
+  this._bindings = [];
+  this._refCounter = 0;
+  var stateKeys = Object.keys(this._state);
+  var self = this;
+
+  function walkTaco(taco, path) {
+    if (taco == null || typeof taco !== 'object' || !taco.t) return taco;
+
+    // Check content for bindings
+    if (typeof taco.c === 'string' && taco.c.indexOf('${') >= 0) {
+      var refId = 'bw_ref_' + self._refCounter++;
+      var parsed = bw._parseBindings(taco.c);
+      var deps = [];
+      for (var j = 0; j < parsed.length; j++) {
+        deps = deps.concat(bw._extractDeps(parsed[j].expr, stateKeys));
+      }
+      self._bindings.push({
+        expr: taco.c,
+        type: 'content',
+        refId: refId,
+        deps: deps,
+        template: taco.c
+      });
+      // Inject data-bw_ref on the TACO for createDOM to pick up
+      if (!taco.a) taco.a = {};
+      taco.a['data-bw_ref'] = refId;
+    }
+
+    // Check attributes for bindings
+    if (taco.a) {
+      for (var attrName in taco.a) {
+        if (!Object.prototype.hasOwnProperty.call(taco.a, attrName)) continue;
+        if (attrName === 'data-bw_ref') continue;
+        var attrVal = taco.a[attrName];
+        if (typeof attrVal === 'string' && attrVal.indexOf('${') >= 0) {
+          var refId2 = 'bw_ref_' + self._refCounter++;
+          var parsed2 = bw._parseBindings(attrVal);
+          var deps2 = [];
+          for (var j2 = 0; j2 < parsed2.length; j2++) {
+            deps2 = deps2.concat(bw._extractDeps(parsed2[j2].expr, stateKeys));
+          }
+          self._bindings.push({
+            expr: attrVal,
+            type: 'attribute',
+            attrName: attrName,
+            refId: refId2,
+            deps: deps2,
+            template: attrVal
+          });
+          if (!taco.a) taco.a = {};
+          taco.a['data-bw_ref'] = taco.a['data-bw_ref'] || refId2;
+          // If multiple attribute bindings on same element, store additional marker
+          if (taco.a['data-bw_ref'] !== refId2) {
+            taco.a['data-bw_ref_' + attrName] = refId2;
+          }
+        }
+      }
+    }
+
+    // Recurse into children
+    if (Array.isArray(taco.c)) {
+      for (var i = 0; i < taco.c.length; i++) {
+        if (taco.c[i] && typeof taco.c[i] === 'object' && taco.c[i].t) {
+          walkTaco(taco.c[i], path.concat(i));
+        }
+        // Handle bw.when/bw.each markers
+        if (taco.c[i] && taco.c[i]._bwWhen) {
+          var whenRefId = 'bw_ref_' + self._refCounter++;
+          var whenDeps = bw._extractDeps(taco.c[i].expr.replace(/^\$\{|\}$/g, ''), stateKeys);
+          self._bindings.push({
+            expr: taco.c[i].expr,
+            type: 'structural',
+            subtype: 'when',
+            refId: whenRefId,
+            deps: whenDeps,
+            branches: taco.c[i].branches,
+            index: i,
+            parentPath: path
+          });
+          taco.c[i]._refId = whenRefId;
+        }
+        if (taco.c[i] && taco.c[i]._bwEach) {
+          var eachRefId = 'bw_ref_' + self._refCounter++;
+          var eachDeps = bw._extractDeps(taco.c[i].expr.replace(/^\$\{|\}$/g, ''), stateKeys);
+          self._bindings.push({
+            expr: taco.c[i].expr,
+            type: 'structural',
+            subtype: 'each',
+            refId: eachRefId,
+            deps: eachDeps,
+            factory: taco.c[i].factory,
+            index: i,
+            parentPath: path
+          });
+          taco.c[i]._refId = eachRefId;
+        }
+      }
+    } else if (taco.c && typeof taco.c === 'object' && taco.c.t) {
+      walkTaco(taco.c, path.concat(0));
+    }
+
+    return taco;
+  }
+
+  walkTaco(this.taco, []);
+};
+
+// ── DOM Reference Collection ──
+
+/**
+ * Build ref map from the live DOM after createDOM.
+ * @private
+ */
+ComponentHandle.prototype._collectRefs = function() {
+  this._bw_refs = {};
+  if (!this.element) return;
+  var els = this.element.querySelectorAll('[data-bw_ref]');
+  for (var i = 0; i < els.length; i++) {
+    this._bw_refs[els[i].getAttribute('data-bw_ref')] = els[i];
+  }
+  // Also check root element
+  var rootRef = this.element.getAttribute && this.element.getAttribute('data-bw_ref');
+  if (rootRef) {
+    this._bw_refs[rootRef] = this.element;
+  }
+};
+
+// ── Lifecycle ──
+
+/**
+ * Mount the component into a parent DOM element.
+ * Creates DOM, compiles bindings, registers actions, and calls lifecycle hooks.
+ * @param {Element} parentEl - DOM element to mount into
+ */
+ComponentHandle.prototype.mount = function(parentEl) {
+  // willMount hook
+  if (this._hooks.willMount) this._hooks.willMount(this);
+
+  // Save original TACO for re-renders (structural changes clone from this)
+  if (!this._originalTaco) {
+    this._originalTaco = this.taco;
+  }
+
+  // Deep-clone TACO so binding annotations don't mutate original.
+  // Custom clone to preserve _bwWhen/_bwEach markers and their factory functions.
+  this.taco = this._deepCloneTaco(this._originalTaco);
+
+  // Compile bindings (annotates TACO with data-bw_ref attributes)
+  this._compileBindings();
+
+  // Prepare TACO: resolve initial binding values, evaluate when/each
+  this._prepareTaco(this.taco);
+
+  // Register named actions in function registry
+  var self = this;
+  for (var actionName in this._actions) {
+    if (Object.prototype.hasOwnProperty.call(this._actions, actionName)) {
+      var registeredName = this._bwId + '_' + actionName;
+      (function(aName) {
+        bw.funcRegister(function(evt) {
+          self._actions[aName](self, evt);
+        }, registeredName);
+      })(actionName);
+      this._registeredActions.push(registeredName);
+    }
+  }
+
+  // Wire action names in onclick etc. to dispatch strings
+  this._wireActions(this.taco);
+
+  // Create DOM (strip o before createDOM to prevent double lifecycle)
+  var tacoForDOM = this._tacoForDOM(this.taco);
+  this.element = bw.createDOM(tacoForDOM);
+  this.element._bwComponentHandle = this;
+  this.element.setAttribute('data-bw_comp_id', this._bwId);
+  if (this._userTag) {
+    this.element.classList.add(this._userTag);
+  }
+
+  // Append to parent
+  parentEl.appendChild(this.element);
+
+  // Collect refs from live DOM
+  this._collectRefs();
+
+  // Resolve initial bindings and apply to DOM
+  this._resolveAndApplyAll();
+
+  this.mounted = true;
+
+  // mounted hook (backward compat: fn.length === 2 wraps (el, state))
+  if (this._hooks.mounted) {
+    if (this._hooks.mounted.length === 2) {
+      this._hooks.mounted(this.element, this.getState());
+    } else {
+      this._hooks.mounted(this);
+    }
+  }
+};
+
+/**
+ * Prepare TACO for initial render: resolve when/each markers.
+ * @private
+ */
+ComponentHandle.prototype._prepareTaco = function(taco) {
+  if (!taco || typeof taco !== 'object') return;
+
+  if (Array.isArray(taco.c)) {
+    for (var i = taco.c.length - 1; i >= 0; i--) {
+      var child = taco.c[i];
+      if (child && child._bwWhen) {
+        var exprStr = child.expr.replace(/^\$\{|\}$/g, '');
+        var val;
+        if (this._compile) {
+          try {
+            val = (new Function('state', 'with(state){return (' + exprStr + ');}'))(this._state);
+          } catch(e) { val = false; }
+        } else {
+          val = bw._evaluatePath(this._state, exprStr);
+        }
+        var branch = val ? child.branches[0] : (child.branches[1] || null);
+        if (branch) {
+          // Wrap in a container so we can track it
+          taco.c[i] = { t: 'span', a: { 'data-bw_when': child._refId, style: 'display:contents' }, c: branch };
+        } else {
+          taco.c[i] = { t: 'span', a: { 'data-bw_when': child._refId, style: 'display:contents' }, c: '' };
+        }
+      }
+      if (child && child._bwEach) {
+        var eachExprStr = child.expr.replace(/^\$\{|\}$/g, '');
+        var arr = bw._evaluatePath(this._state, eachExprStr);
+        var items = [];
+        if (Array.isArray(arr)) {
+          for (var j = 0; j < arr.length; j++) {
+            items.push(child.factory(arr[j], j));
+          }
+        }
+        taco.c[i] = { t: 'span', a: { 'data-bw_each': child._refId, style: 'display:contents' }, c: items };
+      }
+      if (taco.c[i] && typeof taco.c[i] === 'object' && taco.c[i].t) {
+        this._prepareTaco(taco.c[i]);
+      }
+    }
+  } else if (taco.c && typeof taco.c === 'object' && taco.c.t) {
+    this._prepareTaco(taco.c);
+  }
+};
+
+/**
+ * Wire action name strings (in onclick etc.) to dispatch function calls.
+ * @private
+ */
+ComponentHandle.prototype._wireActions = function(taco) {
+  if (!taco || typeof taco !== 'object' || !taco.t) return;
+  if (taco.a) {
+    for (var key in taco.a) {
+      if (!Object.prototype.hasOwnProperty.call(taco.a, key)) continue;
+      if (key.startsWith('on') && typeof taco.a[key] === 'string') {
+        var actionName = taco.a[key];
+        if (actionName in this._actions) {
+          var registeredName = this._bwId + '_' + actionName;
+          // Replace string with actual function for createDOM event binding
+          (function(rName) {
+            taco.a[key] = function(evt) {
+              bw.funcGetById(rName)(evt);
+            };
+          })(registeredName);
+        }
+      }
+    }
+  }
+  if (Array.isArray(taco.c)) {
+    for (var i = 0; i < taco.c.length; i++) {
+      this._wireActions(taco.c[i]);
+    }
+  } else if (taco.c && typeof taco.c === 'object' && taco.c.t) {
+    this._wireActions(taco.c);
+  }
+};
+
+/**
+ * Deep-clone a TACO tree, preserving _bwWhen/_bwEach markers and their factories.
+ * @private
+ */
+ComponentHandle.prototype._deepCloneTaco = function(taco) {
+  if (taco == null) return taco;
+  // Preserve _bwWhen / _bwEach markers (contain functions)
+  if (taco._bwWhen) {
+    return { _bwWhen: true, expr: taco.expr, branches: [
+      this._deepCloneTaco(taco.branches[0]),
+      taco.branches[1] ? this._deepCloneTaco(taco.branches[1]) : null
+    ], _refId: taco._refId };
+  }
+  if (taco._bwEach) {
+    return { _bwEach: true, expr: taco.expr, factory: taco.factory, _refId: taco._refId };
+  }
+  if (typeof taco !== 'object' || !taco.t) return taco;
+  var result = { t: taco.t };
+  if (taco.a) {
+    result.a = {};
+    for (var k in taco.a) {
+      if (Object.prototype.hasOwnProperty.call(taco.a, k)) result.a[k] = taco.a[k];
+    }
+  }
+  if (taco.c != null) {
+    if (Array.isArray(taco.c)) {
+      result.c = taco.c.map(function(child) { return this._deepCloneTaco(child); }.bind(this));
+    } else if (typeof taco.c === 'object') {
+      result.c = this._deepCloneTaco(taco.c);
+    } else {
+      result.c = taco.c;
+    }
+  }
+  if (taco.o) result.o = taco.o; // Keep o reference (not deep-cloned; hooks are functions)
+  return result;
+};
+
+/**
+ * Create a copy of TACO suitable for createDOM (strips o to prevent double lifecycle).
+ * @private
+ */
+ComponentHandle.prototype._tacoForDOM = function(taco) {
+  if (!taco || typeof taco !== 'object' || !taco.t) return taco;
+  var result = { t: taco.t };
+  if (taco.a) result.a = taco.a;
+  if (taco.c != null) {
+    if (Array.isArray(taco.c)) {
+      result.c = taco.c.map(function(child) { return this._tacoForDOM(child); }.bind(this));
+    } else if (typeof taco.c === 'object' && taco.c.t) {
+      result.c = this._tacoForDOM(taco.c);
+    } else {
+      result.c = taco.c;
+    }
+  }
+  // Intentionally strip o (no mounted/unmount/state/render on sub-elements)
+  return result;
+};
+
+/**
+ * Unmount: remove from DOM, deactivate, preserve state for re-mount.
+ */
+ComponentHandle.prototype.unmount = function() {
+  if (!this.mounted) return;
+
+  // unmount hook
+  if (this._hooks.unmount) {
+    this._hooks.unmount(this);
+  }
+
+  // Remove DOM event listeners
+  for (var i = 0; i < this._eventListeners.length; i++) {
+    var l = this._eventListeners[i];
+    if (this.element) {
+      this.element.removeEventListener(l.event, l.handler);
+    }
+  }
+  this._eventListeners = [];
+
+  // Unsubscribe pub/sub
+  for (var j = 0; j < this._subs.length; j++) {
+    this._subs[j]();
+  }
+  this._subs = [];
+
+  // Remove from DOM
+  if (this.element && this.element.parentNode) {
+    this.element.parentNode.removeChild(this.element);
+  }
+
+  this.mounted = false;
+  // State preserved — can re-mount
+};
+
+/**
+ * Destroy: unmount + clear state + unregister actions.
+ */
+ComponentHandle.prototype.destroy = function() {
+  // willDestroy hook
+  if (this._hooks.willDestroy) {
+    this._hooks.willDestroy(this);
+  }
+
+  this.unmount();
+
+  // Unregister actions from function registry
+  for (var i = 0; i < this._registeredActions.length; i++) {
+    bw.funcUnregister(this._registeredActions[i]);
+  }
+  this._registeredActions = [];
+
+  // Clear state
+  this._state = {};
+  this._bindings = [];
+  this._bw_refs = {};
+  this._prevValues = {};
+  this._dirtyKeys = {};
+  if (this.element) {
+    delete this.element._bwComponentHandle;
+    this.element = null;
+  }
+};
+
+// ── Flush & Binding Resolution ──
+
+/**
+ * Flush dirty state: resolve changed bindings and apply to DOM.
+ * @private
+ */
+ComponentHandle.prototype._flush = function() {
+  this._scheduled = false;
+  var changedKeys = Object.keys(this._dirtyKeys);
+  this._dirtyKeys = {};
+  if (changedKeys.length === 0 || !this.mounted) return;
+
+  // willUpdate hook
+  if (this._hooks.willUpdate) {
+    this._hooks.willUpdate(this, changedKeys);
+  }
+
+  // Check if any structural bindings are affected
+  var needsFullRender = false;
+  for (var i = 0; i < this._bindings.length; i++) {
+    var b = this._bindings[i];
+    if (b.type === 'structural') {
+      for (var j = 0; j < b.deps.length; j++) {
+        if (changedKeys.indexOf(b.deps[j]) >= 0) {
+          needsFullRender = true;
+          break;
+        }
+      }
+      if (needsFullRender) break;
+    }
+  }
+
+  if (needsFullRender) {
+    this._render();
+  } else {
+    var patches = this._resolveBindings(changedKeys);
+    this._applyPatches(patches);
+  }
+
+  // onUpdate hook
+  if (this._hooks.onUpdate) {
+    this._hooks.onUpdate(this, changedKeys);
+  }
+};
+
+/**
+ * Resolve bindings whose deps intersect with changedKeys.
+ * Returns list of patches to apply.
+ * @private
+ */
+ComponentHandle.prototype._resolveBindings = function(changedKeys) {
+  var patches = [];
+  for (var i = 0; i < this._bindings.length; i++) {
+    var b = this._bindings[i];
+    if (b.type === 'structural') continue;
+
+    // Check if any dep matches
+    var affected = false;
+    for (var j = 0; j < b.deps.length; j++) {
+      if (changedKeys.indexOf(b.deps[j]) >= 0) {
+        affected = true;
+        break;
+      }
+    }
+    if (!affected) continue;
+
+    // Evaluate
+    var newVal = bw._resolveTemplate(b.template, this._state, this._compile);
+    var prevKey = b.refId + '_' + (b.attrName || 'content');
+    if (this._prevValues[prevKey] !== newVal) {
+      this._prevValues[prevKey] = newVal;
+      patches.push({
+        refId: b.refId,
+        type: b.type,
+        attrName: b.attrName,
+        value: newVal
+      });
+    }
+  }
+  return patches;
+};
+
+/**
+ * Apply patches to DOM.
+ * @private
+ */
+ComponentHandle.prototype._applyPatches = function(patches) {
+  for (var i = 0; i < patches.length; i++) {
+    var p = patches[i];
+    var el = this._bw_refs[p.refId];
+    if (!el) continue;
+    if (p.type === 'content') {
+      el.textContent = p.value;
+    } else if (p.type === 'attribute') {
+      if (p.attrName === 'class') {
+        el.className = p.value;
+      } else {
+        el.setAttribute(p.attrName, p.value);
+      }
+    }
+  }
+};
+
+/**
+ * Resolve all bindings and apply (used for initial render).
+ * @private
+ */
+ComponentHandle.prototype._resolveAndApplyAll = function() {
+  var patches = [];
+  for (var i = 0; i < this._bindings.length; i++) {
+    var b = this._bindings[i];
+    if (b.type === 'structural') continue;
+
+    var newVal = bw._resolveTemplate(b.template, this._state, this._compile);
+    var prevKey = b.refId + '_' + (b.attrName || 'content');
+    this._prevValues[prevKey] = newVal;
+    patches.push({
+      refId: b.refId,
+      type: b.type,
+      attrName: b.attrName,
+      value: newVal
+    });
+  }
+  this._applyPatches(patches);
+};
+
+/**
+ * Full re-render for structural changes (when/each branch switches).
+ * @private
+ */
+ComponentHandle.prototype._render = function() {
+  if (!this.element || !this.element.parentNode) return;
+  var parent = this.element.parentNode;
+  var nextSibling = this.element.nextSibling;
+
+  // Remove old DOM
+  parent.removeChild(this.element);
+
+  // Re-prepare TACO with current state (deep clone preserving functions)
+  this.taco = this._deepCloneTaco(this._originalTaco || this.taco);
+
+  // Re-compile bindings and prepare
+  this._compileBindings();
+  this._prepareTaco(this.taco);
+  this._wireActions(this.taco);
+
+  var tacoForDOM = this._tacoForDOM(this.taco);
+  this.element = bw.createDOM(tacoForDOM);
+  this.element._bwComponentHandle = this;
+  this.element.setAttribute('data-bw_comp_id', this._bwId);
+
+  // Re-insert at same position
+  if (nextSibling) {
+    parent.insertBefore(this.element, nextSibling);
+  } else {
+    parent.appendChild(this.element);
+  }
+
+  // Re-collect refs and apply all bindings
+  this._collectRefs();
+  this._resolveAndApplyAll();
+};
+
+// ── Event & Pub/Sub Methods ──
+
+/**
+ * Add a DOM event listener on the component's root element.
+ * @param {string} event - Event name (e.g., 'click')
+ * @param {Function} handler - Event handler
+ */
+ComponentHandle.prototype.on = function(event, handler) {
+  if (this.element) {
+    this.element.addEventListener(event, handler);
+  }
+  this._eventListeners.push({ event: event, handler: handler });
+};
+
+/**
+ * Remove a DOM event listener.
+ * @param {string} event - Event name
+ * @param {Function} handler - Handler to remove
+ */
+ComponentHandle.prototype.off = function(event, handler) {
+  if (this.element) {
+    this.element.removeEventListener(event, handler);
+  }
+  this._eventListeners = this._eventListeners.filter(function(l) {
+    return !(l.event === event && l.handler === handler);
+  });
+};
+
+/**
+ * Subscribe to a pub/sub topic. Lifecycle-tied: auto-unsubs on destroy.
+ * @param {string} topic - Topic name
+ * @param {Function} handler - Handler function
+ * @returns {Function} Unsubscribe function
+ */
+ComponentHandle.prototype.sub = function(topic, handler) {
+  var unsub = bw.sub(topic, handler);
+  this._subs.push(unsub);
+  return unsub;
+};
+
+/**
+ * Call a named action.
+ * @param {string} name - Action name
+ * @param {...*} args - Arguments passed after comp
+ */
+ComponentHandle.prototype.action = function(name) {
+  var fn = this._actions[name];
+  if (!fn) {
+    console.warn('ComponentHandle.action: unknown action "' + name + '"');
+    return;
+  }
+  var args = [this].concat(Array.prototype.slice.call(arguments, 1));
+  return fn.apply(null, args);
+};
+
+/**
+ * querySelector within the component's DOM.
+ * @param {string} sel - CSS selector
+ * @returns {Element|null}
+ */
+ComponentHandle.prototype.select = function(sel) {
+  return this.element ? this.element.querySelector(sel) : null;
+};
+
+/**
+ * querySelectorAll within the component's DOM.
+ * @param {string} sel - CSS selector
+ * @returns {Element[]}
+ */
+ComponentHandle.prototype.selectAll = function(sel) {
+  if (!this.element) return [];
+  return Array.prototype.slice.call(this.element.querySelectorAll(sel));
+};
+
+/**
+ * Tag this component with a user-defined ID for addressing via bw.message().
+ * The tag is added as a CSS class on the root element (DOM IS the registry).
+ * @param {string} tag - User-defined identifier (e.g. 'dashboard_prod_east')
+ * @returns {ComponentHandle} this (for chaining)
+ */
+ComponentHandle.prototype.userTag = function(tag) {
+  this._userTag = tag;
+  if (this.element) {
+    this.element.classList.add(tag);
+  }
+  return this;
+};
+
+// Expose ComponentHandle on bw (for testing and advanced use)
+bw._ComponentHandle = ComponentHandle;
+
+// ===================================================================================
+// Control Flow Helpers
+// ===================================================================================
+
+/**
+ * Conditional rendering helper.
+ * Returns a marker object that ComponentHandle detects during binding compilation.
+ * In static contexts (bw.html with state), evaluates immediately.
+ *
+ * @param {string} expr - Expression string like '${loggedIn}'
+ * @param {Object} tacoTrue - TACO to render when truthy
+ * @param {Object} [tacoFalse] - TACO to render when falsy
+ * @returns {Object} Marker object with _bwWhen flag
+ * @category Component
+ */
+bw.when = function(expr, tacoTrue, tacoFalse) {
+  return { _bwWhen: true, expr: expr, branches: [tacoTrue, tacoFalse || null] };
+};
+
+/**
+ * List rendering helper.
+ * Returns a marker object that ComponentHandle detects during binding compilation.
+ *
+ * @param {string} expr - Expression string like '${items}'
+ * @param {Function} fn - Factory function(item, index) returning TACO
+ * @returns {Object} Marker object with _bwEach flag
+ * @category Component
+ */
+bw.each = function(expr, fn) {
+  return { _bwEach: true, expr: expr, factory: fn };
+};
+
+// ===================================================================================
+// bw.component() — Factory for ComponentHandle
+// ===================================================================================
+
+/**
+ * Create a ComponentHandle from a TACO definition.
+ * The returned handle has .get(), .set(), .mount(), .destroy(), etc.
+ *
+ * @param {Object} taco - TACO definition with {t, a, c, o}
+ * @returns {ComponentHandle} Reactive component handle
+ * @category Component
+ * @see bw.DOM
+ * @example
+ * var counter = bw.component({
+ *   t: 'div', c: [{ t: 'h3', c: 'Count: ${count}' }],
+ *   o: { state: { count: 0 } }
+ * });
+ * bw.DOM('#app', counter);
+ * counter.set('count', 42); // DOM auto-updates
+ */
+bw.component = function(taco) {
+  return new ComponentHandle(taco);
+};
+
+// ===================================================================================
+// bw.message() — SendMessage() for the web
+// ===================================================================================
+
+/**
+ * Dispatch a message to a component by UUID or user tag.
+ * Finds the component's DOM element, looks up its ComponentHandle,
+ * and calls the named method. This is the bitwrench equivalent of
+ * Win32 SendMessage(hwnd, msg, wParam, lParam).
+ *
+ * @param {string} target - Component UUID (data-bw_comp_id) or user tag (CSS class)
+ * @param {string} action - Method name to call on the component
+ * @param {*} data - Data to pass to the method
+ * @returns {boolean} True if message was dispatched successfully
+ * @category Component
+ * @example
+ * // Tag a component
+ * myDash.userTag('dashboard_prod');
+ * // Dispatch locally
+ * bw.message('dashboard_prod', 'addAlert', { severity: 'warning', text: 'CPU spike' });
+ * // Or from SSE handler:
+ * es.onmessage = function(e) {
+ *   var msg = JSON.parse(e.data);
+ *   bw.message(msg.target, msg.action, msg.data);
+ * };
+ */
+bw.message = function(target, action, data) {
+  // Try data-bw_comp_id attribute first, then CSS class (user tag)
+  var el = bw.$('[data-bw_comp_id="' + target + '"]')[0];
+  if (!el) {
+    el = bw.$('.' + target)[0];
+  }
+  if (!el || !el._bwComponentHandle) return false;
+  var comp = el._bwComponentHandle;
+  if (typeof comp[action] !== 'function') {
+    console.warn('bw.message: unknown action "' + action + '" on component ' + target);
+    return false;
+  }
+  comp[action](data);
+  return true;
+};
+
+// ===================================================================================
+// bw.inspect() — Debug utility
+// ===================================================================================
+
+/**
+ * Inspect a component's state, bindings, methods, and metadata.
+ * Works with DOM elements, CSS selectors, or ComponentHandle objects.
+ * Returns the ComponentHandle for console chaining.
+ *
+ * @param {string|Element|ComponentHandle} target - Selector, element, or handle
+ * @returns {ComponentHandle|null} The component handle, or null if not found
+ * @category Component
+ * @example
+ * // In browser console, click element in Elements panel then:
+ * bw.inspect($0);
+ * // Or by selector:
+ * var h = bw.inspect('#my-dashboard');
+ * h.set('count', 99);  // chain from returned handle
+ */
+bw.inspect = function(target) {
+  var el = target;
+  var comp;
+  if (target && target._bwComponent === true) {
+    el = target.element;
+    comp = target;
+  } else {
+    if (typeof target === 'string') {
+      el = bw.$(target)[0];
+    }
+    if (!el) {
+      console.warn('bw.inspect: element not found');
+      return null;
+    }
+    comp = el._bwComponentHandle;
+  }
+  if (!comp) {
+    console.log('bw.inspect: no ComponentHandle on this element');
+    console.log('  Tag:', el.tagName);
+    console.log('  Classes:', el.className);
+    console.log('  _bw_state:', el._bw_state || '(none)');
+    return null;
+  }
+  var deps = comp._bindings.reduce(function(s, b) {
+    return s.concat(b.deps || []);
+  }, []).filter(function(v, i, a) { return a.indexOf(v) === i; });
+  console.group('Component: ' + comp._bwId);
+  console.log('State:', comp._state);
+  console.log('Bindings:', comp._bindings.length, '(deps:', deps, ')');
+  console.log('Methods:', Object.keys(comp._methods));
+  console.log('Actions:', Object.keys(comp._actions));
+  console.log('User tag:', comp._userTag || '(none)');
+  console.log('Mounted:', comp.mounted);
+  console.log('Element:', comp.element);
+  console.groupEnd();
+  return comp;
+};
+
+// ===================================================================================
+// bw.compile() — Pre-compile TACO into optimized factory
+// ===================================================================================
+
+/**
+ * Pre-compile a TACO definition into a factory function.
+ * The factory produces ComponentHandles with pre-compiled binding evaluators.
+ *
+ * Phase 1: validates API surface. Template cloning optimization deferred.
+ *
+ * @param {Object} taco - TACO definition
+ * @returns {Function} Factory function(initialState?) → ComponentHandle
+ * @category Component
+ */
+bw.compile = function(taco) {
+  // Pre-extract all binding expressions
+  var precompiled = [];
+  function walkExpressions(node) {
+    if (!node || typeof node !== 'object') return;
+    if (typeof node.c === 'string' && node.c.indexOf('${') >= 0) {
+      var parsed = bw._parseBindings(node.c);
+      for (var i = 0; i < parsed.length; i++) {
+        try {
+          precompiled.push({
+            expr: parsed[i].expr,
+            fn: new Function('state', 'with(state){return (' + parsed[i].expr + ');}')
+          });
+        } catch(e) {
+          precompiled.push({ expr: parsed[i].expr, fn: function() { return ''; } });
+        }
+      }
+    }
+    if (node.a) {
+      for (var key in node.a) {
+        if (Object.prototype.hasOwnProperty.call(node.a, key)) {
+          var v = node.a[key];
+          if (typeof v === 'string' && v.indexOf('${') >= 0) {
+            var parsed2 = bw._parseBindings(v);
+            for (var j = 0; j < parsed2.length; j++) {
+              try {
+                precompiled.push({
+                  expr: parsed2[j].expr,
+                  fn: new Function('state', 'with(state){return (' + parsed2[j].expr + ');}')
+                });
+              } catch(e2) {
+                precompiled.push({ expr: parsed2[j].expr, fn: function() { return ''; } });
+              }
+            }
+          }
+        }
+      }
+    }
+    if (Array.isArray(node.c)) {
+      for (var k = 0; k < node.c.length; k++) walkExpressions(node.c[k]);
+    } else if (node.c && typeof node.c === 'object' && node.c.t) {
+      walkExpressions(node.c);
+    }
+  }
+  walkExpressions(taco);
+
+  return function(initialState) {
+    var handle = new ComponentHandle(taco);
+    handle._compile = true;
+    handle._precompiledBindings = precompiled;
+    if (initialState) {
+      for (var k in initialState) {
+        if (Object.prototype.hasOwnProperty.call(initialState, k)) {
+          handle._state[k] = initialState[k];
+        }
+      }
+    }
+    return handle;
+  };
+};
+
+/**
+ * Generate CSS from JavaScript objects.
+ *
+ * Converts an object of `{ selector: { prop: value } }` rules into a CSS string.
+ * CamelCase property names are auto-converted to kebab-case (e.g. `fontSize` → `font-size`).
+ * Accepts nested arrays of rule objects.
+ *
+ * @param {Object|Array|string} rules - CSS rules as JS objects, array of rule objects, or raw CSS string
+ * @param {Object} [options] - Generation options
+ * @param {boolean} [options.minify=false] - Minify output (no whitespace)
+ * @returns {string} CSS string
+ * @category CSS & Styling
+ * @see bw.injectCSS
+ * @example
+ * bw.css({
+ *   '.card': { padding: '1rem', fontSize: '14px', borderRadius: '8px' }
+ * })
+ * // => '.card {\n  padding: 1rem;\n  font-size: 14px;\n  border-radius: 8px;\n}'
+ */
+bw.css = function(rules, options = {}) {
+  const { minify = false, pretty = !minify } = options;
+
+  if (typeof rules === 'string') return rules;
+
+  let css = '';
+  const indent = pretty ? '  ' : '';
+  const newline = pretty ? '\n' : '';
+  const space = pretty ? ' ' : '';
+
+  if (Array.isArray(rules)) {
+    css = rules.map(rule => bw.css(rule, options)).join(newline);
+  } else if (typeof rules === 'object') {
+    Object.entries(rules).forEach(([selector, styles]) => {
+      if (typeof styles === 'object' && !Array.isArray(styles)) {
+        // Handle @media, @keyframes, @supports — recurse into nested block
+        if (selector.charAt(0) === '@') {
+          const inner = bw.css(styles, options);
+          if (inner) {
+            css += `${selector}${space}{${newline}${inner}${newline}}${newline}`;
+          }
+          return;
+        }
+        const declarations = Object.entries(styles)
+          .filter(([, value]) => value != null)
+          .map(([prop, value]) => {
+            // Convert camelCase to kebab-case
+            const kebabProp = prop.replace(/[A-Z]/g, m => '-' + m.toLowerCase());
+            return `${indent}${kebabProp}:${space}${value};`;
+          })
+          .join(newline);
+
+        if (declarations) {
+          css += `${selector}${space}{${newline}${declarations}${newline}}${newline}`;
+        }
+      }
+    });
+  }
+
+  return css.trim();
+};
+
+/**
+ * Inject CSS into the document head (browser only).
+ *
+ * Creates or reuses a `<style>` element (identified by `id`). Can accept
+ * raw CSS strings or JS rule objects (which are converted via `bw.css()`).
+ * By default appends to existing content; set `append: false` to replace.
+ *
+ * @param {string|Object|Array} css - CSS string, or JS rule objects to convert
+ * @param {Object} [options] - Injection options
+ * @param {string} [options.id='bw_styles'] - ID for the style element
+ * @param {boolean} [options.append=true] - Append to existing CSS (false to replace)
+ * @returns {Element} The style element
+ * @category CSS & Styling
+ * @see bw.css
+ * @see bw.loadDefaultStyles
+ * @example
+ * bw.injectCSS('.my-class { color: red; }');
+ * bw.injectCSS({ '.card': { padding: '1rem' } }, { id: 'card-styles' });
+ */
+bw.injectCSS = function(css, options = {}) {
+  if (!bw._isBrowser) {
+    console.warn('bw.injectCSS requires a DOM environment');
+    return null;
+  }
+  
+  const { id = 'bw_styles', append = true } = options;
+  
+  // Get or create style element
+  let styleEl = document.getElementById(id);
+  
+  if (!styleEl) {
+    styleEl = document.createElement('style');
+    styleEl.id = id;
+    styleEl.type = 'text/css';
+    document.head.appendChild(styleEl);
+  }
+  
+  // Convert CSS if needed
+  const cssStr = typeof css === 'string' ? css : bw.css(css, options);
+  
+  // Set or append CSS
+  if (append && styleEl.textContent) {
+    styleEl.textContent += '\n' + cssStr;
+  } else {
+    styleEl.textContent = cssStr;
+  }
+  
+  return styleEl;
+};
+
+/**
+ * Merge multiple style objects into one (left-to-right).
+ *
+ * Like `Object.assign()` for styles, but filters out null/undefined arguments.
+ * Compose inline styles or CSS rule objects without mutation.
+ *
+ * @param {...Object} styles - Style objects to merge (left-to-right)
+ * @returns {Object} Merged style object
+ * @category CSS & Styling
+ * @see bw.u
+ * @example
+ * var style = bw.s(bw.u.flex, bw.u.gap4, { color: 'red' });
+ * // => { display: 'flex', gap: '1rem', color: 'red' }
+ */
+bw.s = function() {
+  var result = {};
+  for (var i = 0; i < arguments.length; i++) {
+    var arg = arguments[i];
+    if (arg && typeof arg === 'object') Object.assign(result, arg);
+  }
+  return result;
+};
+
+/**
+ * Pre-built CSS utility objects (like Tailwind utilities, but in JS).
+ *
+ * Compose with `bw.s()` to build inline styles without writing raw CSS strings.
+ * Includes flex, padding, margin, typography, color, border, and transition utilities.
+ *
+ * @category CSS & Styling
+ * @see bw.s
+ * @example
+ * { t: 'div', a: { style: bw.s(bw.u.flex, bw.u.gap4, bw.u.p4) },
+ *   c: 'Flexbox with 1rem gap and padding' }
+ */
+bw.u = {
+  // Display
+  flex: { display: 'flex' },
+  flexCol: { display: 'flex', flexDirection: 'column' },
+  flexRow: { display: 'flex', flexDirection: 'row' },
+  flexWrap: { display: 'flex', flexWrap: 'wrap' },
+  block: { display: 'block' },
+  inline: { display: 'inline' },
+  hidden: { display: 'none' },
+
+  // Flex alignment
+  justifyCenter: { justifyContent: 'center' },
+  justifyBetween: { justifyContent: 'space-between' },
+  justifyEnd: { justifyContent: 'flex-end' },
+  alignCenter: { alignItems: 'center' },
+  alignStart: { alignItems: 'flex-start' },
+  alignEnd: { alignItems: 'flex-end' },
+
+  // Gap (0.25rem increments)
+  gap1: { gap: '0.25rem' },
+  gap2: { gap: '0.5rem' },
   gap3: { gap: '0.75rem' },
   gap4: { gap: '1rem' },
   gap6: { gap: '1.5rem' },
@@ -1624,8 +2941,10 @@ bw.u = {
 /**
  * Generate responsive CSS with media query breakpoints.
  *
- * Produces a CSS string with `@media` rules for sm (640px), md (768px),
- * lg (1024px), and xl (1280px) breakpoints. Pass the result to `bw.injectCSS()`.
+ * Produces a CSS string with `@media (min-width)` rules for standard
+ * breakpoints. These match the grid system and theme.breakpoints:
+ *   sm: 576px, md: 768px, lg: 992px, xl: 1200px
+ * Pass the result to `bw.injectCSS()`.
  *
  * @param {string} selector - CSS selector
  * @param {Object} breakpoints - Object with keys: base, sm, md, lg, xl
@@ -1642,7 +2961,7 @@ bw.u = {
  * bw.injectCSS(css);
  */
 bw.responsive = function(selector, breakpoints) {
-  var sizes = { sm: '640px', md: '768px', lg: '1024px', xl: '1280px' };
+  var sizes = { sm: '576px', md: '768px', lg: '992px', xl: '1200px' };
   var parts = [];
   Object.keys(breakpoints).forEach(function(key) {
     var rules = {};
@@ -1678,29 +2997,7 @@ bw.responsive = function(selector, breakpoints) {
  * bw.mapScale(50, 0, 100, 0, 1)  // => 0.5
  * bw.mapScale(75, 0, 100, 0, 255) // => 191.25
  */
-bw.mapScale = function(x, in0, in1, out0, out1, options = {}) {
-  const { clip = false, expScale = 1 } = options;
-  
-  // Normalize to 0-1
-  let normalized = (x - in0) / (in1 - in0);
-  
-  // Apply exponential scaling
-  if (expScale !== 1) {
-    normalized = Math.pow(normalized, expScale);
-  }
-  
-  // Map to output range
-  let result = normalized * (out1 - out0) + out0;
-  
-  // Clip if requested
-  if (clip) {
-    const min = Math.min(out0, out1);
-    const max = Math.max(out0, out1);
-    result = Math.max(min, Math.min(max, result));
-  }
-  
-  return result;
-};
+bw.mapScale = _mapScale;
 
 /**
  * Clamp a value between min and max bounds.
@@ -1716,9 +3013,7 @@ bw.mapScale = function(x, in0, in1, out0, out1, options = {}) {
  * bw.clip(-5, 0, 100)   // => 0
  * bw.clip(50, 0, 100)   // => 50
  */
-bw.clip = function(value, min, max) {
-  return Math.max(min, Math.min(max, value));
-};
+bw.clip = _clip;
 
 /**
  * DOM selection helper that always returns an array (browser only).
@@ -1776,7 +3071,8 @@ if (bw._isBrowser) {
  * @returns {Element|null} Style element if in browser, null in Node.js
  * @category CSS & Styling
  * @see bw.setTheme
- * @see bw.toggleDarkMode
+ * @see bw.applyTheme
+ * @see bw.toggleTheme
  * @example
  * bw.loadDefaultStyles();  // inject all default CSS
  */
@@ -1786,7 +3082,7 @@ bw.loadDefaultStyles = function(options = {}) {
   // 1. Inject structural CSS (layout, sizing — never changes with theme)
   if (bw._isBrowser) {
     var structuralCSS = bw.css(getStructuralStyles());
-    bw.injectCSS(structuralCSS, { id: 'bw-structural', append: false, minify: minify });
+    bw.injectCSS(structuralCSS, { id: 'bw_structural', append: false, minify: minify });
   }
 
   // 2. Inject cosmetic CSS via generateTheme (colors, shadows, radii)
@@ -1795,100 +3091,6 @@ bw.loadDefaultStyles = function(options = {}) {
   return result;
 };
 
-/**
- * Get the current theme configuration as a deep copy.
- *
- * @returns {Object} Theme object with colors, fonts, spacing, etc.
- * @category CSS & Styling
- * @see bw.setTheme
- */
-bw.getTheme = function() {
-  if (typeof console !== 'undefined' && console.warn) {
-    console.warn('bw.getTheme() is deprecated. Use bw.generateTheme() instead.');
-  }
-  return JSON.parse(JSON.stringify(theme));
-};
-
-/**
- * Set theme overrides and optionally re-inject CSS custom properties.
- *
- * Merges your overrides into the current theme and updates `--bw-*` CSS
- * custom properties on `<html>` so all components pick up the changes live.
- *
- * @param {Object} overrides - Partial theme object to merge (e.g. { colors: { primary: '#ff0000' } })
- * @param {Object} [options] - Options
- * @param {boolean} [options.inject=true] - Whether to re-inject CSS (browser only)
- * @returns {Object} Updated theme
- * @category CSS & Styling
- * @see bw.getTheme
- * @see bw.loadDefaultStyles
- * @example
- * bw.setTheme({ colors: { primary: '#ff6600' } });
- */
-bw.setTheme = function(overrides, options = {}) {
-  if (typeof console !== 'undefined' && console.warn) {
-    console.warn('bw.setTheme() is deprecated. Use bw.generateTheme() instead.');
-  }
-  const { inject = true } = options;
-  updateTheme(overrides);
-
-  // Update CSS custom properties if colors changed and we're in browser
-  if (inject && bw._isBrowser && overrides.colors) {
-    const root = document.documentElement;
-    for (const [name, value] of Object.entries(overrides.colors)) {
-      root.style.setProperty('--bw-' + name, value);
-    }
-  }
-
-  return bw.getTheme();
-};
-
-/**
- * Toggle dark mode on/off.
- *
- * Adds/removes the `bw-dark` class on `<html>` and injects dark mode CSS
- * overrides. Pass `true`/`false` to force a mode, or omit to toggle.
- *
- * @param {boolean} [force] - Force dark (true) or light (false). Omit to toggle.
- * @returns {boolean} Whether dark mode is now active
- * @category CSS & Styling
- * @see bw.setTheme
- * @example
- * bw.toggleDarkMode();        // toggle
- * bw.toggleDarkMode(true);    // force dark
- * bw.toggleDarkMode(false);   // force light
- */
-bw.toggleDarkMode = function(force) {
-  const isDark = force !== undefined ? force : !theme.darkMode;
-  theme.darkMode = isDark;
-
-  if (bw._isBrowser) {
-    const root = document.documentElement;
-    if (isDark) {
-      root.classList.add('bw-dark');
-      // Generate palette-aware dark mode CSS, or fall back to default
-      var palette = bw._activePalette || derivePalette(DEFAULT_PALETTE_CONFIG);
-      var darkRules = generateDarkModeCSS(palette);
-      var darkCSS = bw.css(darkRules);
-
-      // Remove existing dark styles to allow regeneration
-      var existing = document.getElementById('bw-dark-styles');
-      if (existing) existing.remove();
-
-      var styleEl = document.createElement('style');
-      styleEl.id = 'bw-dark-styles';
-      styleEl.textContent = darkCSS;
-      document.head.appendChild(styleEl);
-    } else {
-      root.classList.remove('bw-dark');
-      // Remove dark mode styles when switching to light
-      var darkEl = document.getElementById('bw-dark-styles');
-      if (darkEl) darkEl.remove();
-    }
-  }
-
-  return isDark;
-};
 
 /**
  * Generate a complete, scoped theme from seed colors.
@@ -1909,16 +3111,24 @@ bw.toggleDarkMode = function(force) {
  * @param {string} [config.info='#0dcaf0'] - Info color hex
  * @param {string} [config.light='#f8f9fa'] - Light color hex
  * @param {string} [config.dark='#212529'] - Dark color hex
+ * @param {string} [config.background] - Page background hex (default: '#ffffff' light, derived dark)
+ * @param {string} [config.surface] - Surface/card background hex (default: '#f8f9fa' light, derived dark)
  * @param {string} [config.spacing='normal'] - 'compact' | 'normal' | 'spacious'
  * @param {string} [config.radius='md'] - 'none' | 'sm' | 'md' | 'lg' | 'pill'
  * @param {number} [config.fontSize=1.0] - Base font size scale factor
+ * @param {string|number} [config.typeRatio='normal'] - 'tight' | 'normal' | 'relaxed' | 'dramatic' or a number
+ * @param {string} [config.elevation='md'] - 'flat' | 'sm' | 'md' | 'lg'
+ * @param {string} [config.motion='standard'] - 'reduced' | 'standard' | 'expressive'
+ * @param {number} [config.harmonize=0.20] - 0-1, semantic color hue shift toward primary
  * @param {boolean} [config.inject=true] - Inject into DOM (browser only)
- * @returns {Object} { css, palette, name }
+ * @returns {Object} { css, palette, name, isLightPrimary, alternate: { css, palette } }
  * @category CSS & Styling
+ * @see bw.applyTheme
+ * @see bw.toggleTheme
  * @see bw.loadDefaultStyles
  * @example
- * // Generate and inject an ocean theme
- * bw.generateTheme('ocean', {
+ * // Generate and inject an ocean theme (primary + alternate)
+ * var theme = bw.generateTheme('ocean', {
  *   primary: '#0077b6',
  *   secondary: '#90e0ef',
  *   tertiary: '#00b4d8'
@@ -1927,14 +3137,16 @@ bw.toggleDarkMode = function(force) {
  * // Apply to a container
  * document.getElementById('app').classList.add('ocean');
  *
+ * // Toggle to alternate palette
+ * bw.toggleTheme();
+ *
  * // Generate CSS for static export (Node.js)
  * var result = bw.generateTheme('sunset', {
  *   primary: '#e76f51',
  *   secondary: '#264653',
- *   tertiary: '#e9c46a',
  *   inject: false
  * });
- * fs.writeFileSync('sunset.css', result.css);
+ * fs.writeFileSync('sunset.css', result.css + result.alternate.css);
  */
 bw.generateTheme = function(name, config) {
   if (!config || !config.primary || !config.secondary) {
@@ -1945,29 +3157,38 @@ bw.generateTheme = function(name, config) {
   var fullConfig = Object.assign({}, DEFAULT_PALETTE_CONFIG, config);
   if (!config.tertiary) fullConfig.tertiary = fullConfig.primary;
 
-  // Derive palette
+  // Derive primary palette
   var palette = derivePalette(fullConfig);
 
-  // Store active palette for dark mode
-  bw._activePalette = palette;
-
   // Resolve layout
   var layout = resolveLayout(fullConfig);
 
-  // Generate themed CSS rules
+  // Generate primary themed CSS rules
   var themedRules = generateThemedCSS(name, palette, layout);
+  var cssStr = bw.css(themedRules);
+
+  // Derive alternate palette (luminance-inverted)
+  var altConfig = deriveAlternateConfig(fullConfig);
+  var altPalette = derivePalette(altConfig);
 
-  // Add underscore aliases
-  var aliasedRules = addUnderscoreAliases(themedRules);
+  // Generate alternate CSS scoped under .bw_theme_alt
+  var altRules = generateAlternateCSS(name, altPalette, layout);
+  var altCssStr = bw.css(altRules);
 
-  // Convert to CSS string
-  var cssStr = bw.css(aliasedRules);
+  // Determine if primary is light-flavored
+  var lightPrimary = isLightPalette(fullConfig);
 
-  // Inject into DOM if requested and in browser
+  // Inject both CSS sets into DOM if requested
   var shouldInject = config.inject !== false;
   if (shouldInject && bw._isBrowser) {
-    var styleId = name ? 'bw-theme-' + name : 'bw-theme-default';
+    var safeName = name ? name.replace(/-/g, '_') : '';
+    var styleId = safeName ? 'bw_theme_' + safeName : 'bw_theme_default';
+    var altStyleId = safeName ? 'bw_theme_' + safeName + '_alt' : 'bw_theme_default_alt';
+
     bw.injectCSS(cssStr, { id: styleId, append: false });
+    bw.injectCSS(altCssStr, { id: altStyleId, append: false });
+
+    bw._activeThemeStyleIds = [styleId, altStyleId];
   }
 
   // Update bw.u color entries to reflect the palette
@@ -1978,314 +3199,144 @@ bw.generateTheme = function(name, config) {
     bw.u.textWhite = { color: '#ffffff' };
   }
 
-  return { css: cssStr, palette: palette, name: name };
-};
-
-// Expose color utility functions on bw namespace
-bw.hexToHsl = hexToHsl;
-bw.hslToHex = hslToHex;
-bw.adjustLightness = adjustLightness;
-bw.mixColor = mixColor;
-bw.relativeLuminance = relativeLuminance;
-bw.textOnColor = textOnColor;
-bw.deriveShades = deriveShades;
-bw.derivePalette = derivePalette;
-
-// Expose layout and theme presets
-bw.SPACING_PRESETS = SPACING_PRESETS;
-bw.RADIUS_PRESETS = RADIUS_PRESETS;
-bw.DEFAULT_PALETTE_CONFIG = DEFAULT_PALETTE_CONFIG;
-bw.THEME_PRESETS = THEME_PRESETS;
-
-// ===================================================================================
-// Legacy v1 Functions - Useful utilities retained from bitwrench v1
-// ===================================================================================
-
-/**
- * Use a dictionary as a switch statement, with support for function values.
- *
- * Looks up `x` in `choices`. If the value is a function, calls it with `x` as argument.
- * Returns `def` if the key is not found.
- *
- * @param {*} x - Key to look up
- * @param {Object} choices - Dictionary of choices (values can be functions)
- * @param {*} def - Default value if key not found
- * @returns {*} Value or function result
- * @category Array Utilities
- * @example
- * var colors = { red: 1, blue: 2, aqua: function(z) { return z + 'marine'; } };
- * bw.choice('red', colors, '0')   // => 1
- * bw.choice('aqua', colors)       // => 'aquamarine'
- * bw.choice('pink', colors, 'n/a') // => 'n/a'
- */
-bw.choice = function(x, choices, def) {
-  const z = (x in choices) ? choices[x] : def;
-  return bw.typeOf(z) === "function" ? z(x) : z;
-};
-
-/**
- * Return unique elements of an array (preserves first occurrence order).
- *
- * @param {Array} x - Input array
- * @returns {Array} Array with unique elements
- * @category Array Utilities
- * @example
- * bw.arrayUniq([1, 2, 2, 3, 1])  // => [1, 2, 3]
- */
-bw.arrayUniq = function(x) {
-  if (bw.typeOf(x) !== "array") return [];
-  return x.filter((v, i, arr) => arr.indexOf(v) === i);
-};
-
-/**
- * Return the intersection of two arrays (elements present in both).
- *
- * @param {Array} a - First array
- * @param {Array} b - Second array
- * @returns {Array} Unique elements found in both a and b
- * @category Array Utilities
- * @see bw.arrayBNotInA
- * @example
- * bw.arrayBinA([1, 2, 3], [2, 3, 4])  // => [2, 3]
- */
-bw.arrayBinA = function(a, b) {
-  if (bw.typeOf(a) !== "array" || bw.typeOf(b) !== "array") return [];
-  return bw.arrayUniq(a.filter(n => b.indexOf(n) !== -1));
-};
-
-/**
- * Return elements of b that are not present in a (set difference).
- *
- * @param {Array} a - First array (the "exclude" set)
- * @param {Array} b - Second array (source of results)
- * @returns {Array} Unique elements in b but not in a
- * @category Array Utilities
- * @see bw.arrayBinA
- * @example
- * bw.arrayBNotInA([1, 2, 3], [2, 3, 4, 5])  // => [4, 5]
- */
-bw.arrayBNotInA = function(a, b) {
-  if (bw.typeOf(a) !== "array" || bw.typeOf(b) !== "array") return [];
-  return bw.arrayUniq(b.filter(n => a.indexOf(n) < 0));
-};
+  // Store active theme state
+  var result = {
+    css: cssStr,
+    palette: palette,
+    name: name,
+    isLightPrimary: lightPrimary,
+    alternate: {
+      css: altCssStr,
+      palette: altPalette
+    }
+  };
+  bw._activeTheme = result;
+  bw._activeThemeMode = 'primary';
 
-/**
- * Interpolate between an array of colors based on a value in a range.
- *
- * Maps a value from [in0..in1] across a gradient of colors, smoothly blending
- * between adjacent stops. Useful for heatmaps, gauges, and data visualization.
- *
- * @param {number} x - Value to interpolate
- * @param {number} in0 - Input range start
- * @param {number} in1 - Input range end
- * @param {Array} colors - Array of CSS color strings to interpolate between
- * @param {number} [stretch] - Exponential scaling factor (1 = linear)
- * @returns {Array} Interpolated color as [r, g, b, a, "rgb"]
- * @category Color
- * @see bw.colorParse
- * @see bw.mapScale
- * @example
- * bw.colorInterp(50, 0, 100, ['#ff0000', '#00ff00'])
- * // => [128, 128, 0, 255, "rgb"] (yellow midpoint)
- */
-bw.colorInterp = function(x, in0, in1, colors, stretch) {
-  let c = Array.isArray(colors) ? colors : ["#000", "#fff"];
-  c = c.length === 0 ? ["#000", "#fff"] : c;
-  if (c.length === 1) return c[0];
-  
-  // Convert all colors to RGB format
-  c = c.map(col => bw.colorParse(col));
-  
-  const a = bw.mapScale(x, in0, in1, 0, c.length - 1, { clip: true, expScale: stretch });
-  const i = bw.clip(Math.floor(a), 0, c.length - 2);
-  const r = a - i;
-  
-  const interp = (idx) => bw.mapScale(r, 0, 1, c[i][idx], c[i + 1][idx], { clip: true });
-  return [interp(0), interp(1), interp(2), interp(3), "rgb"];
+  return result;
 };
 
 /**
- * Convert an HSL color to RGB.
- *
- * Accepts individual h, s, l values or a bitwrench color array [h, s, l, a, "hsl"].
+ * Apply a theme mode. Switches between primary and alternate palettes
+ * by adding/removing the `bw_theme_alt` class on `<html>`.
  *
- * @param {number|Array} h - Hue [0..360] or [h,s,l,a,"hsl"] array
- * @param {number} s - Saturation [0..100]
- * @param {number} l - Lightness [0..100]
- * @param {number} [a=255] - Alpha [0..255]
- * @param {boolean} [rnd=true] - Round results to integers
- * @returns {Array} RGB as [r, g, b, a, "rgb"]
- * @category Color
- * @see bw.colorRgbToHsl
+ * @param {string} mode - 'primary' | 'alternate' | 'light' | 'dark'
+ * @returns {string} Active mode: 'primary' or 'alternate'
+ * @category CSS & Styling
+ * @see bw.generateTheme
+ * @see bw.toggleTheme
  * @example
- * bw.colorHslToRgb(0, 100, 50)    // => [255, 0, 0, 255, "rgb"]
- * bw.colorHslToRgb(120, 100, 50)  // => [0, 255, 0, 255, "rgb"]
+ * bw.applyTheme('alternate');  // switch to alternate palette
+ * bw.applyTheme('dark');       // switch to whichever palette is darker
+ * bw.applyTheme('primary');    // switch back to primary palette
  */
-bw.colorHslToRgb = function(h, s, l, a = 255, rnd = true) {
-  if (bw.typeOf(h) === "array") {
-    s = h[1]; l = h[2]; a = h[3]; h = h[0];
-  }
-  
-  const hNorm = h / 360;
-  const sNorm = s / 100;
-  const lNorm = l / 100;
-  
-  let r, g, b;
-  
-  if (sNorm === 0) {
-    r = g = b = lNorm * 255;
+bw.applyTheme = function(mode) {
+  if (!bw._isBrowser) return mode || 'primary';
+  var root = document.documentElement;
+  var isLight = bw._activeTheme ? bw._activeTheme.isLightPrimary : true;
+
+  var wantAlt;
+  if (mode === 'primary')        wantAlt = false;
+  else if (mode === 'alternate') wantAlt = true;
+  else if (mode === 'light')     wantAlt = !isLight;
+  else if (mode === 'dark')      wantAlt = isLight;
+  else                           wantAlt = false;
+
+  if (wantAlt) {
+    root.classList.add('bw_theme_alt');
   } else {
-    const hue2rgb = (p, q, t) => {
-      if (t < 0) t += 1;
-      if (t > 1) t -= 1;
-      if (t < 1/6) return p + (q - p) * 6 * t;
-      if (t < 1/2) return q;
-      if (t < 2/3) return p + (q - p) * (2/3 - t) * 6;
-      return p;
-    };
-    
-    const q = lNorm < 0.5 ? lNorm * (1 + sNorm) : lNorm + sNorm - lNorm * sNorm;
-    const p = 2 * lNorm - q;
-    
-    r = hue2rgb(p, q, hNorm + 1/3) * 255;
-    g = hue2rgb(p, q, hNorm) * 255;
-    b = hue2rgb(p, q, hNorm - 1/3) * 255;
+    root.classList.remove('bw_theme_alt');
   }
-  
-  if (rnd) {
-    r = Math.round(r);
-    g = Math.round(g);
-    b = Math.round(b);
-    a = Math.round(a);
-  }
-  
-  return [r, g, b, a, "rgb"];
-};
 
-/**
- * Convert an RGB color to HSL.
- *
- * Accepts individual r, g, b values or a bitwrench color array [r, g, b, a, "rgb"].
- *
- * @param {number|Array} r - Red [0..255] or [r,g,b,a,"rgb"] array
- * @param {number} g - Green [0..255]
- * @param {number} b - Blue [0..255]
- * @param {number} [a=255] - Alpha [0..255]
- * @param {boolean} [rnd=true] - Round results to integers
- * @returns {Array} HSL as [h, s, l, a, "hsl"]
- * @category Color
- * @see bw.colorHslToRgb
- * @example
- * bw.colorRgbToHsl(255, 0, 0)   // => [0, 100, 50, 255, "hsl"]
- * bw.colorRgbToHsl(0, 0, 255)   // => [240, 100, 50, 255, "hsl"]
- */
-bw.colorRgbToHsl = function(r, g, b, a = 255, rnd = true) {
-  if (bw.typeOf(r) === "array") {
-    g = r[1]; b = r[2]; a = r[3]; r = r[0];
-  }
-  
-  r /= 255;
-  g /= 255;
-  b /= 255;
-  
-  const max = Math.max(r, g, b);
-  const min = Math.min(r, g, b);
-  let h, s, l = (max + min) / 2;
-  
-  if (max === min) {
-    h = s = 0; // achromatic
-  } else {
-    const d = max - min;
-    s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
-    
-    switch (max) {
-      case r: h = ((g - b) / d + (g < b ? 6 : 0)) / 6; break;
-      case g: h = ((b - r) / d + 2) / 6; break;
-      case b: h = ((r - g) / d + 4) / 6; break;
-    }
-  }
-  
-  h *= 360;
-  s *= 100;
-  l *= 100;
-  
-  if (rnd) {
-    h = Math.round(h);
-    s = Math.round(s);
-    l = Math.round(l);
-    a = Math.round(a);
-  }
-  
-  return [h, s, l, a, "hsl"];
+  bw._activeThemeMode = wantAlt ? 'alternate' : 'primary';
+  return bw._activeThemeMode;
 };
 
 /**
- * Parse a CSS color string into bitwrench's internal array format.
- *
- * Supports hex (#rgb, #rrggbb, #rrggbbaa), rgb(), rgba(), hsl(), and hsla().
- * Also accepts existing bitwrench color arrays (pass-through).
+ * Toggle between primary and alternate theme palettes.
  *
- * @param {string|Array} s - CSS color string (e.g. "#ff0000", "rgb(255,0,0)") or color array
- * @param {number} [defAlpha=255] - Default alpha value
- * @returns {Array} Color as [c0, c1, c2, a, "rgb"|"hsl"]
- * @category Color
- * @see bw.colorInterp
+ * @returns {string} Active mode after toggle: 'primary' or 'alternate'
+ * @category CSS & Styling
+ * @see bw.applyTheme
+ * @see bw.generateTheme
  * @example
- * bw.colorParse('#ff0000')        // => [255, 0, 0, 255, "rgb"]
- * bw.colorParse('rgb(0,128,255)') // => [0, 128, 255, 255, "rgb"]
+ * bw.toggleTheme();  // flip between primary and alternate
  */
-bw.colorParse = function(s, defAlpha = 255) {
-  let r = [0, 0, 0, defAlpha, "rgb"]; // default return
-  
-  if (bw.typeOf(s) === "array") {
-    // Handle bitwrench color array
-    const df = [0, 0, 0, 255, "rgb"];
-    for (let p = 0; p < s.length && p < df.length; p++) {
-      df[p] = s[p];
-    }
-    return df;
-  }
-  
-  s = String(s).replace(/\s/g, "");
-  
-  // Handle hex colors
-  if (s[0] === "#") {
-    const hex = s.slice(1);
-    if (hex.length === 3 || hex.length === 4) {
-      // #rgb or #rgba
-      for (let i = 0; i < hex.length; i++) {
-        r[i] = parseInt(hex[i] + hex[i], 16);
-      }
-    } else if (hex.length === 6 || hex.length === 8) {
-      // #rrggbb or #rrggbbaa
-      for (let i = 0; i < hex.length; i += 2) {
-        r[i / 2] = parseInt(hex.substring(i, i + 2), 16);
-      }
-    }
-  } else {
-    // Handle rgb() rgba() hsl() hsla()
-    const match = s.match(/^(rgb|hsl)a?\(([^)]+)\)$/i);
-    if (match) {
-      const type = match[1].toLowerCase();
-      const values = match[2].split(",").map(v => parseFloat(v));
-      
-      if (type === "rgb") {
-        r[0] = values[0] || 0;
-        r[1] = values[1] || 0;
-        r[2] = values[2] || 0;
-        r[3] = values[3] !== undefined ? values[3] * 255 : defAlpha;
-        r[4] = "rgb";
-      } else if (type === "hsl") {
-        const rgb = bw.colorHslToRgb(values[0] || 0, values[1] || 0, values[2] || 0, 
-                                      values[3] !== undefined ? values[3] * 255 : defAlpha);
-        return rgb;
-      }
-    }
+bw.toggleTheme = function() {
+  var current = bw._activeThemeMode || 'primary';
+  return bw.applyTheme(current === 'primary' ? 'alternate' : 'primary');
+};
+
+/**
+ * Remove the currently active theme's injected style elements from the DOM.
+ * Use this before generating a new theme with a different name to prevent
+ * stale CSS accumulation.
+ *
+ * @category CSS & Styling
+ * @see bw.generateTheme
+ * @example
+ * bw.clearTheme();                   // remove current theme styles
+ * bw.generateTheme('sunset', conf);  // inject fresh theme
+ */
+bw.clearTheme = function() {
+  if (bw._activeThemeStyleIds && bw._isBrowser) {
+    bw._activeThemeStyleIds.forEach(function(id) {
+      var el = document.getElementById(id);
+      if (el) el.remove();
+    });
+    bw._activeThemeStyleIds = null;
   }
-  
-  return r;
+  bw._activeTheme = null;
+  bw._activeThemeMode = 'primary';
+};
+
+// Expose color utility functions on bw namespace
+bw.hexToHsl = hexToHsl;
+bw.hslToHex = hslToHex;
+bw.adjustLightness = adjustLightness;
+bw.mixColor = mixColor;
+bw.relativeLuminance = relativeLuminance;
+bw.textOnColor = textOnColor;
+bw.deriveShades = deriveShades;
+bw.derivePalette = derivePalette;
+bw.harmonize = harmonize;
+bw.deriveAlternateSeed = deriveAlternateSeed;
+bw.deriveAlternateConfig = deriveAlternateConfig;
+bw.isLightPalette = isLightPalette;
+
+// Expose layout and theme presets
+bw.SPACING_PRESETS = SPACING_PRESETS;
+bw.RADIUS_PRESETS = RADIUS_PRESETS;
+bw.TYPE_RATIO_PRESETS = TYPE_RATIO_PRESETS;
+bw.ELEVATION_PRESETS = ELEVATION_PRESETS;
+bw.MOTION_PRESETS = MOTION_PRESETS;
+bw.generateTypeScale = generateTypeScale;
+bw.DEFAULT_PALETTE_CONFIG = DEFAULT_PALETTE_CONFIG;
+bw.THEME_PRESETS = THEME_PRESETS;
+
+// ===================================================================================
+// Legacy v1 Functions - Useful utilities retained from bitwrench v1
+// ===================================================================================
+
+/** @see bitwrench-utils.js for implementation */
+bw.choice = _choice;
+/** @see bitwrench-utils.js for implementation */
+bw.arrayUniq = _arrayUniq;
+/** @see bitwrench-utils.js for implementation */
+bw.arrayBinA = _arrayBinA;
+/** @see bitwrench-utils.js for implementation */
+bw.arrayBNotInA = _arrayBNotInA;
+
+/** @see bitwrench-utils.js for implementation — wraps _colorInterp with bw.colorParse */
+bw.colorInterp = function(x, in0, in1, colors, stretch) {
+  return _colorInterp(x, in0, in1, colors, stretch, colorParse);
 };
 
+// Color conversion functions — imported from bitwrench-color-utils.js (single source of truth)
+bw.colorHslToRgb = colorHslToRgb;
+bw.colorRgbToHsl = colorRgbToHsl;
+bw.colorParse = colorParse;
+
 /**
  * Set a browser cookie with expiration and options.
  *
@@ -2373,608 +3424,21 @@ bw.getURLParam = function(key, defaultValue) {
   }
 };
 
-/**
- * Create an HTML table string from a 2D data array.
- *
- * Legacy v1 API — returns an HTML string, not a TACO. First row is used
- * as headers by default. For TACO-based tables, use `bw.makeTable()` instead.
- *
- * @param {Array} data - 2D array of table data
- * @param {Object} [opts] - Table options
- * @param {boolean} [opts.useFirstRowAsHeaders=true] - Use first row as headers
- * @param {string} [opts.caption] - Table caption
- * @returns {string} HTML table string
- * @category Legacy (v1)
- * @see bw.makeTable
- */
-bw.htmlTable = function(data, opts = {}) {
-  console.warn('bw.htmlTable() is deprecated. Use bw.makeTableFromArray() for TACO output or bw.makeTable() for object-array data.');
-  if (bw.typeOf(data) !== "array" || data.length < 1) return "";
-  
-  const dopts = {
-    useFirstRowAsHeaders: true,
-    caption: null,
-    atr: { class: "table" },
-    thead_atr: {},
-    th_atr: {},
-    tbody_atr: {},
-    tr_atr: {},
-    td_atr: {}
-  };
-  
-  Object.assign(dopts, opts);
-  
-  let html = `<table${bw._attrsToStr(dopts.atr)}>`;
-  
-  if (dopts.caption) {
-    html += `<caption>${bw.escapeHTML(dopts.caption)}</caption>`;
-  }
-  
-  let startRow = 0;
-  
-  // Handle header row
-  if (dopts.useFirstRowAsHeaders && data.length > 0) {
-    html += `<thead${bw._attrsToStr(dopts.thead_atr)}>`;
-    html += `<tr${bw._attrsToStr(dopts.tr_atr)}>`;
-    
-    data[0].forEach(cell => {
-      html += `<th${bw._attrsToStr(dopts.th_atr)}>${bw.escapeHTML(String(cell))}</th>`;
-    });
-    
-    html += "</tr></thead>";
-    startRow = 1;
-  }
-  
-  // Body rows
-  if (data.length > startRow) {
-    html += `<tbody${bw._attrsToStr(dopts.tbody_atr)}>`;
-    
-    for (let i = startRow; i < data.length; i++) {
-      html += `<tr${bw._attrsToStr(dopts.tr_atr)}>`;
-      
-      data[i].forEach(cell => {
-        html += `<td${bw._attrsToStr(dopts.td_atr)}>${bw.escapeHTML(String(cell))}</td>`;
-      });
-      
-      html += "</tr>";
-    }
-    
-    html += "</tbody>";
-  }
-  
-  html += "</table>";
-  
-  return html;
-};
-
-/**
- * Convert an attributes object to an HTML attribute string
- *
- * Handles boolean attributes (key only), null/undefined/false (skipped),
- * and regular string values (HTML-escaped). Used internally by bw.htmlTable()
- * and bw.htmlTabs().
- *
- * @param {Object} attrs - Attribute key-value pairs
- * @returns {string} HTML attribute string with leading space, or empty string
- * @private
- */
-bw._attrsToStr = function(attrs) {
-  if (!attrs || typeof attrs !== "object") return "";
-  
-  let str = "";
-  for (const [key, value] of Object.entries(attrs)) {
-    if (value != null && value !== false) {
-      if (value === true) {
-        str += ` ${key}`;
-      } else {
-        str += ` ${key}="${bw.escapeHTML(String(value))}"`;
-      }
-    }
-  }
-  
-  return str;
-};
-
-/**
- * Create an HTML tabs structure from an array of [title, content] pairs.
- *
- * Legacy v1 API — returns an HTML string. For TACO-based tabs,
- * use `bw.makeTabs()` instead.
- *
- * @param {Array} tabData - Array of [title, content] pairs
- * @param {Object} [opts] - Tab options
- * @returns {string} HTML tabs string
- * @category Legacy (v1)
- * @see bw.makeTabs
- */
-bw.htmlTabs = function(tabData, opts = {}) {
-  console.warn('bw.htmlTabs() is deprecated. Use bw.makeTabs() instead.');
-  if (bw.typeOf(tabData) !== "array" || tabData.length < 1) return "";
-  
-  const dopts = {
-    atr: { class: "bw-tab-container" },
-    tab_atr: { class: "bw-tab-item-list" },
-    tabc_atr: { class: "bw-tab-content-list" }
-  };
-  
-  Object.assign(dopts, opts);
-  
-  // Create tab items
-  const tabItems = tabData.map((tab, idx) => ({
-    t: "li",
-    a: { 
-      class: idx === 0 ? "bw-tab-item bw-tab-active" : "bw-tab-item",
-      onclick: "bw.selectTabContent(this)"
-    },
-    c: tab[0]
-  }));
-  
-  // Create tab content
-  const tabContent = tabData.map((tab, idx) => ({
-    t: "div",
-    a: { class: idx === 0 ? "bw-tab-content bw-show" : "bw-tab-content" },
-    c: tab[1]
-  }));
-  
-  return bw.html({
-    t: "div",
-    a: dopts.atr,
-    c: [
-      { t: "ul", a: dopts.tab_atr, c: tabItems },
-      { t: "div", a: dopts.tabc_atr, c: tabContent }
-    ]
-  });
-};
-
-/**
- * Tab selection handler — shows the clicked tab's content and hides others.
- *
- * Used internally by `bw.htmlTabs()`. You generally don't call this directly.
- *
- * @param {Element} tabElement - Clicked tab element
- * @category Legacy (v1)
- */
-bw.selectTabContent = function(tabElement) {
-  console.warn('bw.selectTabContent() is deprecated. Use bw.makeTabs() instead.');
-  if (!bw._isBrowser || !tabElement) return;
-  
-  const container = tabElement.closest(".bw-tab-container");
-  if (!container) return;
-  
-  // Remove active class from all tabs
-  container.querySelectorAll(".bw-tab-item").forEach(tab => {
-    tab.classList.remove("bw-tab-active");
-  });
-  
-  // Add active to clicked tab
-  tabElement.classList.add("bw-tab-active");
-  
-  // Get tab index
-  const tabIndex = Array.from(tabElement.parentElement.children).indexOf(tabElement);
-  
-  // Hide all content
-  container.querySelectorAll(".bw-tab-content").forEach(content => {
-    content.classList.remove("bw-show");
-  });
-  
-  // Show selected content
-  const contents = container.querySelectorAll(".bw-tab-content");
-  if (contents[tabIndex]) {
-    contents[tabIndex].classList.add("bw-show");
-  }
-};
-
-/**
- * Generate Lorem Ipsum placeholder text.
- *
- * Useful for prototyping layouts. Generates repeatable text from the standard
- * Lorem Ipsum passage. Omit numChars for a random length between 25-150 characters.
- *
- * @param {number} [numChars] - Number of characters (random 25-150 if not provided)
- * @param {number} [startSpot] - Starting index in Lorem text (random if undefined)
- * @param {boolean} [startWithCapitalLetter=true] - Start with a capital letter
- * @returns {string} Lorem ipsum text
- * @category Text Generation
- * @example
- * bw.loremIpsum(50)
- * // => "Lorem ipsum dolor sit amet, consectetur adipiscin"
- */
-bw.loremIpsum = function(numChars, startSpot, startWithCapitalLetter = true) {
-  const lorem = "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. ";
-  
-  // If numChars not provided, generate random length between 25-150
-  if (typeof numChars !== "number") {
-    numChars = Math.floor(Math.random() * 125) + 25;
-  }
-  
-  // If startSpot is undefined, randomize it
-  if (startSpot === undefined) {
-    startSpot = Math.floor(Math.random() * lorem.length);
-  }
-  
-  startSpot = startSpot % lorem.length;
-  
-  // Track how many characters we skip to honor numChars
-  let skippedChars = 0;
-  // Move startSpot to the next non-whitespace and non-punctuation character
-  while (lorem[startSpot] === ' ' || /[.,:;!?]/.test(lorem[startSpot])) {
-    startSpot = (startSpot + 1) % lorem.length;
-    skippedChars++;
-    // Prevent infinite loop in case entire lorem is spaces/punctuation
-    if (skippedChars >= lorem.length) {
-      startSpot = 0;
-      skippedChars = 0;
-      break;
-    }
-  }
-  
-  let l = lorem.substring(startSpot) + lorem.substring(0, startSpot);
-  
-  let result = "";
-  let remaining = numChars + skippedChars;  // Add skipped chars to honor original numChars
-  
-  while (remaining > 0) {
-    result += remaining < l.length ? l.substring(0, remaining) : l;
-    remaining -= l.length;
-  }
-  
-  // Trim to exact numChars length
-  if (result.length > numChars) {
-    result = result.substring(0, numChars);
-  }
-  
-  // Ensure no trailing space
-  if (result[result.length - 1] === " ") {
-    result = result.substring(0, result.length - 1) + ".";
-  }
-  
-  // Ensure capital letter at start if requested
-  if (startWithCapitalLetter) {
-    let c = result[0].toUpperCase();
-    c = /[A-Z]/.test(c) ? c : "L";  // Use "L" as default if first char isn't a letter
-    result = c + result.substring(1);
-  }
-  
-  return result;
-};
-
-/**
- * Create a multidimensional array filled with a value or function result.
- *
- * If value is a function, it's called for each cell (useful for random data).
- *
- * @param {*} value - Value or function to fill array with
- * @param {number|Array} dims - Dimensions (number for 1D, array for multi-D)
- * @returns {Array} Multidimensional array
- * @category Array Utilities
- * @example
- * bw.multiArray(0, [4, 5])            // 4x5 array of 0s
- * bw.multiArray('test', 5)            // ['test','test','test','test','test']
- * bw.multiArray(Math.random, [3, 4])  // 3x4 array of random numbers
- */
-bw.multiArray = function(value, dims) {
-  const v = () => bw.typeOf(value) === "function" ? value() : value;
-  dims = typeof dims === "number" ? [dims] : dims;
-  
-  const createArray = (dim) => {
-    if (dim >= dims.length) return v();
-    
-    const arr = [];
-    for (let i = 0; i < dims[dim]; i++) {
-      arr[i] = createArray(dim + 1);
-    }
-    return arr;
-  };
-  
-  return createArray(0);
-};
-
-/**
- * Natural sort comparison function for use with `Array.sort()`.
- *
- * Sorts strings with embedded numbers in human-expected order
- * (e.g. "file2" before "file10") instead of lexicographic order.
- *
- * @param {*} as - First value
- * @param {*} bs - Second value
- * @returns {number} Sort order (-1, 0, 1)
- * @category Array Utilities
- * @example
- * ['item10', 'item2', 'item1'].sort(bw.naturalCompare)
- * // => ['item1', 'item2', 'item10']
- */
-bw.naturalCompare = function(as, bs) {
-  // Handle numbers
-  if (isFinite(as) && isFinite(bs)) {
-    return Math.sign(as - bs);
-  }
-  
-  const a = String(as).toLowerCase();
-  const b = String(bs).toLowerCase();
-  
-  if (a === b) return as > bs ? 1 : 0;
-  
-  // If no digits, simple string compare
-  if (!/\d/.test(a) || !/\d/.test(b)) {
-    return a > b ? 1 : -1;
-  }
-  
-  // Split into chunks of digits/non-digits
-  const aParts = a.match(/(\d+|\D+)/g) || [];
-  const bParts = b.match(/(\d+|\D+)/g) || [];
-  
-  const len = Math.min(aParts.length, bParts.length);
-  
-  for (let i = 0; i < len; i++) {
-    const aPart = aParts[i];
-    const bPart = bParts[i];
-    
-    if (aPart !== bPart) {
-      // Both numeric
-      if (/^\d+$/.test(aPart) && /^\d+$/.test(bPart)) {
-        // Handle leading zeros
-        let aNum = aPart;
-        let bNum = bPart;
-        
-        if (aPart[0] === "0") aNum = "0." + aPart;
-        if (bPart[0] === "0") bNum = "0." + bPart;
-        
-        return parseFloat(aNum) - parseFloat(bNum);
-      }
-      
-      // String comparison
-      return aPart > bPart ? 1 : -1;
-    }
-  }
-  
-  // Different lengths
-  return aParts.length - bParts.length;
-};
-
-/**
- * Run `setInterval` with a maximum number of repetitions.
- *
- * Like `setInterval` but automatically clears after N calls.
- *
- * @param {Function} callback - Function to call (receives iteration index)
- * @param {number} delay - Delay between calls in ms
- * @param {number} repetitions - Maximum number of times to call
- * @returns {number} Interval ID (can be passed to clearInterval)
- * @category Timing
- * @example
- * bw.setIntervalX(function(i) {
- *   console.log('Iteration', i);
- * }, 1000, 5); // Runs 5 times, 1 second apart
- */
-bw.setIntervalX = function(callback, delay, repetitions) {
-  let count = 0;
-  const intervalID = setInterval(function() {
-    callback(count);
-    
-    if (++count >= repetitions) {
-      clearInterval(intervalID);
-    }
-  }, delay);
-  
-  return intervalID;
-};
-
-/**
- * Repeat a test function until it returns truthy, or give up after max attempts.
- *
- * Useful for polling (waiting for an element to appear, an API to respond, etc.).
- *
- * @param {Function} testFn - Test function that returns truthy when done
- * @param {Function} successFn - Called with test result when test passes
- * @param {Function} [failFn] - Called on each failed test attempt
- * @param {number} [delay=250] - Delay between attempts in ms
- * @param {number} [maxReps=10] - Maximum number of attempts
- * @param {Function} [lastFn] - Called when done with (success, count)
- * @returns {string|number} "err" if invalid params, otherwise interval ID
- * @category Timing
- * @example
- * bw.repeatUntil(
- *   function() { return document.getElementById('myDiv'); },
- *   function() { console.log('Element found!'); },
- *   null, 100, 30
- * );
- */
-bw.repeatUntil = function(testFn, successFn, failFn, delay = 250, maxReps = 10, lastFn) {
-  if (typeof testFn !== "function") return "err";
-  
-  let count = 0;
-  
-  const intervalID = setInterval(function() {
-    const result = testFn();
-    count++;
-    
-    if (result) {
-      clearInterval(intervalID);
-      if (successFn) successFn(result);
-      if (lastFn) lastFn(true, count);
-    } else if (count >= maxReps) {
-      clearInterval(intervalID);
-      if (failFn) failFn();
-      if (lastFn) lastFn(false, count);
-    } else {
-      if (failFn) failFn();
-    }
-  }, delay);
-  
-  return intervalID;
-};
-
-// ===================================================================================
-// File I/O Functions - Works in both Node.js and browser
-// ===================================================================================
-
-/**
- * Save data to a file. Works in both Node.js (fs.writeFile) and browser (download link).
- *
- * @param {string} fname - Filename to save as
- * @param {*} data - Data to save (string or buffer)
- * @category File I/O
- * @see bw.saveClientJSON
- */
-bw.saveClientFile = function(fname, data) {
-  if (bw.isNodeJS()) {
-    bw._getFs().then(function(fs) {
-      if (!fs) { console.error('bw.saveClientFile: fs module not available'); return; }
-      fs.writeFile(fname, data, function(err) {
-        if (err) {
-          console.error("Error saving file:", err);
-        }
-      });
-    });
-  } else {
-    // Browser environment
-    const blob = new Blob([data], { type: "application/octet-stream" });
-    const url = window.URL.createObjectURL(blob);
-    const a = bw.createDOM({
-      t: 'a',
-      a: { 
-        href: url, 
-        download: fname,
-        style: 'display: none'
-      }
-    });
-    document.body.appendChild(a);
-    a.click();
-    window.URL.revokeObjectURL(url);
-    document.body.removeChild(a);
-  }
-};
-
-/**
- * Save data as a JSON file with pretty formatting.
- *
- * @param {string} fname - Filename to save as
- * @param {*} data - Data to serialize as JSON
- * @category File I/O
- * @see bw.saveClientFile
- */
-bw.saveClientJSON = function(fname, data) {
-  bw.saveClientFile(fname, JSON.stringify(data, null, 2));
-};
-
-/**
- * Load a file by path (Node.js) or URL (browser via XHR).
- *
- * @param {string} fname - File path (Node) or URL (browser)
- * @param {Function} callback - Called with (data, error). data is null on error.
- * @param {Object} [options] - Options
- * @param {string} [options.parser="raw"] - "raw" for string, "JSON" to auto-parse
- * @returns {string} "BW_OK"
- * @category File I/O
- * @see bw.loadClientJSON
- */
-bw.loadClientFile = function(fname, callback, options) {
-  var opts = { parser: 'raw' };
-  if (options && options.parser) { opts.parser = options.parser; }
-  var parse = (opts.parser === 'JSON') ? JSON.parse : function(s) { return s; };
-
-  if (bw.isNodeJS()) {
-    bw._getFs().then(function(fs) {
-      if (!fs) { callback(null, new Error('fs module not available')); return; }
-      fs.readFile(fname, 'utf8', function(err, data) {
-        if (err) { callback(null, err); }
-        else {
-          try { callback(parse(data), null); }
-          catch (e) { callback(null, e); }
-        }
-      });
-    });
-  } else {
-    var x = new XMLHttpRequest();
-    x.open('GET', fname, true);
-    x.onreadystatechange = function() {
-      if (x.readyState === 4) {
-        if (x.status >= 200 && x.status < 300) {
-          try { callback(parse(x.responseText), null); }
-          catch (e) { callback(null, e); }
-        } else {
-          callback(null, new Error('HTTP ' + x.status + ': ' + fname));
-        }
-      }
-    };
-    x.send(null);
-  }
-  return 'BW_OK';
-};
-
-/**
- * Load a JSON file by path (Node.js) or URL (browser). Convenience wrapper
- * around `bw.loadClientFile()` with `parser: "JSON"`.
- *
- * @param {string} fname - File path (Node) or URL (browser)
- * @param {Function} callback - Called with (parsedData, error)
- * @returns {string} "BW_OK"
- * @category File I/O
- * @see bw.loadClientFile
- */
-bw.loadClientJSON = function(fname, callback) {
-  return bw.loadClientFile(fname, callback, { parser: 'JSON' });
-};
-
-/**
- * Prompt user to pick a local file via file dialog (browser only).
- *
- * Opens a native file picker and reads the selected file.
- *
- * @param {Function} callback - Called with (data, filename, error)
- * @param {Object} [options] - Options
- * @param {string} [options.accept] - File type filter (e.g. ".json,.txt")
- * @param {string} [options.parser="raw"] - "raw" for string, "JSON" to auto-parse
- * @category File I/O
- * @see bw.loadLocalJSON
- */
-bw.loadLocalFile = function(callback, options) {
-  var opts = { parser: 'raw', accept: '' };
-  if (options) {
-    if (options.parser) { opts.parser = options.parser; }
-    if (options.accept) { opts.accept = options.accept; }
-  }
-  var parse = (opts.parser === 'JSON') ? JSON.parse : function(s) { return s; };
 
-  if (bw.isNodeJS()) {
-    callback(null, '', new Error('bw.loadLocalFile is browser-only. Use bw.loadClientFile() in Node.'));
-    return;
-  }
+/** @see bitwrench-utils.js for implementation */
+bw.loremIpsum = _loremIpsum;
 
-  var input = bw.createDOM({
-    t: 'input',
-    a: {
-      type: 'file',
-      accept: opts.accept,
-      style: 'display: none'
-    }
-  });
-  input.addEventListener('change', function() {
-    var file = input.files[0];
-    if (!file) { callback(null, '', new Error('No file selected')); return; }
-    var reader = new FileReader();
-    reader.onload = function(e) {
-      try { callback(parse(e.target.result), file.name, null); }
-      catch (err) { callback(null, file.name, err); }
-    };
-    reader.onerror = function() { callback(null, file.name, reader.error); };
-    reader.readAsText(file);
-    input.remove();
-  });
-  document.body.appendChild(input);
-  input.click();
-};
+/** @see bitwrench-utils.js for implementation */
+bw.multiArray = _multiArray;
+/** @see bitwrench-utils.js for implementation */
+bw.naturalCompare = _naturalCompare;
+/** @see bitwrench-utils.js for implementation */
+bw.setIntervalX = _setIntervalX;
+/** @see bitwrench-utils.js for implementation */
+bw.repeatUntil = _repeatUntil;
 
-/**
- * Prompt user to pick a local JSON file via file dialog (browser only).
- *
- * @param {Function} callback - Called with (parsedData, filename, error)
- * @category File I/O
- * @see bw.loadLocalFile
- */
-bw.loadLocalJSON = function(callback) {
-  bw.loadLocalFile(callback, { parser: 'JSON', accept: '.json' });
-};
+// File I/O — see bitwrench-file-ops.js
+bindFileOps(bw);
 
 /**
  * Copy text to the system clipboard (browser only).
@@ -3035,9 +3499,13 @@ bw.copyToClipboard = function(text) {
 /**
  * Create a sortable TACO table from an array of row objects.
  *
+ * Returns a bare `<table>` TACO — no wrapper, title, or responsive scroll.
+ * Use this when you need full control over table placement, or when embedding
+ * the table inside your own layout. For a ready-to-use table with title,
+ * responsive wrapper, and defaults (striped + hover), use `bw.makeDataTable()`.
+ *
  * Auto-detects columns from data keys if not specified. Supports click-to-sort
- * headers with ascending/descending indicators. Returns a TACO object —
- * render with `bw.DOM()` or `bw.html()`.
+ * headers with ascending/descending indicators.
  *
  * @param {Object} config - Table configuration
  * @param {Array<Object>} config.data - Array of row objects to display
@@ -3073,10 +3541,10 @@ bw.makeTable = function(config) {
     sortDirection = 'asc'
   } = config;
 
-  // Build class list: always include bw-table, add striped/hover, append user className
-  let cls = 'bw-table';
-  if (striped) cls += ' bw-table-striped';
-  if (hover) cls += ' bw-table-hover';
+  // Build class list: always include bw_table, add striped/hover, append user className
+  let cls = 'bw_table';
+  if (striped) cls += ' bw_table_striped';
+  if (hover) cls += ' bw_table_hover';
   if (className) cls += ' ' + className;
   cls = cls.trim();
   
@@ -3290,7 +3758,7 @@ bw.makeBarChart = function(config) {
   } = config;
 
   if (!Array.isArray(data) || data.length === 0) {
-    return { t: 'div', a: { class: ('bw-bar-chart-container ' + className).trim() }, c: '' };
+    return { t: 'div', a: { class: ('bw_bar_chart_container ' + className).trim() }, c: '' };
   }
 
   const values = data.map(function(d) { return Number(d[valueKey]) || 0; });
@@ -3303,44 +3771,46 @@ bw.makeBarChart = function(config) {
 
     const children = [];
     if (showValues) {
-      children.push({ t: 'div', a: { class: 'bw-bar-value' }, c: formatted });
+      children.push({ t: 'div', a: { class: 'bw_bar_value' }, c: formatted });
     }
     children.push({
       t: 'div',
       a: {
-        class: 'bw-bar',
+        class: 'bw_bar',
         style: 'height:' + pct + '%;background:' + color + ';'
       }
     });
     if (showLabels) {
-      children.push({ t: 'div', a: { class: 'bw-bar-label' }, c: String(d[labelKey] || '') });
+      children.push({ t: 'div', a: { class: 'bw_bar_label' }, c: String(d[labelKey] || '') });
     }
 
-    return { t: 'div', a: { class: 'bw-bar-group' }, c: children };
+    return { t: 'div', a: { class: 'bw_bar_group' }, c: children };
   });
 
   const chartChildren = [];
   if (title) {
-    chartChildren.push({ t: 'h3', a: { class: 'bw-bar-chart-title' }, c: title });
+    chartChildren.push({ t: 'h3', a: { class: 'bw_bar_chart_title' }, c: title });
   }
   chartChildren.push({
     t: 'div',
-    a: { class: 'bw-bar-chart', style: 'height:' + height + ';' },
+    a: { class: 'bw_bar_chart', style: 'height:' + height + ';' },
     c: bars
   });
 
   return {
     t: 'div',
-    a: { class: ('bw-bar-chart-container ' + className).trim() },
+    a: { class: ('bw_bar_chart_container ' + className).trim() },
     c: chartChildren
   };
 };
 
 /**
- * Create a responsive data table with title and optional wrapper
+ * Create a ready-to-use data table with title and responsive wrapper.
  *
- * Wraps bw.makeTable() output in a responsive container div.
- * Adds an optional title heading above the table.
+ * Convenience wrapper around `bw.makeTable()` that adds a title heading,
+ * responsive horizontal scroll container, and defaults to striped + hover.
+ * Use this for the common case; use `bw.makeTable()` when you need a bare
+ * table element with no wrapper.
  *
  * @param {Object} config - Table configuration
  * @param {string} [config.title] - Table title heading
@@ -3428,7 +3898,7 @@ bw._componentRegistry = new Map();
  * @see bw.DOM
  * @example
  * var handle = bw.render('#app', 'append', {
- *   t: 'button', a: { class: 'bw-btn' }, c: 'Click Me',
+ *   t: 'button', a: { class: 'bw_btn' }, c: 'Click Me',
  *   o: { state: { clicks: 0 } }
  * });
  * handle.setState({ clicks: 1 });
@@ -3466,7 +3936,7 @@ bw.render = function(element, position, taco) {
   }
   
   // Add component ID to element
-  domElement.setAttribute('data-bw-id', componentId);
+  domElement.setAttribute('data-bw_id', componentId);
   
   // Insert into DOM based on position
   try {
@@ -3541,7 +4011,7 @@ bw.render = function(element, position, taco) {
       
       // Re-render
       const newElement = bw.createDOM(this._taco);
-      newElement.setAttribute('data-bw-id', componentId);
+      newElement.setAttribute('data-bw_id', componentId);
       
       // Replace in DOM
       parent.replaceChild(newElement, this.element);
@@ -3715,7 +4185,7 @@ bw.getAllComponents = function() {
 // =========================================================================
 // Import and register all components
 // =========================================================================
-import * as components from './bitwrench-components-v2.js';
+import * as components from './bitwrench-bccl.js';
 
 // Register all make functions
 Object.entries(components).forEach(([name, fn]) => {
@@ -3724,50 +4194,26 @@ Object.entries(components).forEach(([name, fn]) => {
   }
 });
 
-// Register component handles
-bw._componentHandles = components.componentHandles || {};
+// Factory dispatch: bw.make('card', props) → bw.makeCard(props)
+bw.make = components.make;
 
-// Create functions that return handles
+// Component registry: bw.BCCL lists all available component types
+bw.BCCL = components.BCCL;
+
+// Variant class helper: bw.variantClass('primary') → 'bw_primary'
+bw.variantClass = components.variantClass;
+
+// Create functions that return handles (plain renderComponent, no Handle overlay)
 Object.entries(components).forEach(([name, fn]) => {
   if (name.startsWith('make')) {
-    const componentType = name.substring(4).toLowerCase(); // Remove 'make' prefix
     const createName = 'create' + name.substring(4); // createCard, createTable, etc.
-    
     bw[createName] = function(props) {
       const taco = fn(props);
-      const handle = bw.renderComponent(taco);
-      
-      // Use specialized handle class if available
-      const HandleClass = bw._componentHandles[componentType];
-      if (HandleClass) {
-        const specializedHandle = new HandleClass(handle.element, taco);
-        // Copy base handle properties
-        Object.setPrototypeOf(specializedHandle, handle);
-        return specializedHandle;
-      }
-      
-      return handle;
+      return bw.renderComponent(taco);
     };
   }
 });
 
-// Manual registration for functions defined in this file
-// createTable
-bw.createTable = function(data, options = {}) {
-  const taco = bw.makeTable({ data, ...options });
-  const handle = bw.renderComponent(taco);
-  
-  // Use specialized TableHandle
-  const TableHandle = bw._componentHandles.table;
-  if (TableHandle) {
-    const specializedHandle = new TableHandle(handle.element, taco);
-    Object.setPrototypeOf(specializedHandle, handle);
-    return specializedHandle;
-  }
-  
-  return handle;
-};
-
 // Export for different environments
 export default bw;