bitwrench 2.0.17 → 2.0.19

package/src/bitwrench-bccl.js

@@ -172,7 +172,12 @@ export function makeCard(props = {}) {
       },
       o: {
         type: 'card',
-        state: props.state || {}
+        state: props.state || {},
+        slots: {
+          title: '.bw_card_title',
+          content: '.bw_card_body',
+          footer: '.bw_card_footer'
+        }
       }
     };
   }
@@ -183,7 +188,12 @@ export function makeCard(props = {}) {
     c: cardContent,
     o: {
       type: 'card',
-      state: props.state || {}
+      state: props.state || {},
+      slots: {
+        title: '.bw_card_title',
+        content: '.bw_card_body',
+        footer: '.bw_card_footer'
+      }
     }
   };
 }
@@ -327,7 +337,7 @@ export function makeCol(props = {}) {
       if (breakpoint === 'xs') {
         classes.push(`bw_col_${value}`);
       } else {
-        classes.push(`bw_col_${breakpoint}-${value}`);
+        classes.push(`bw_col_${breakpoint}_${value}`);
       }
     });
   } else if (size) {
@@ -501,6 +511,24 @@ export function makeTabs(props = {}) {
     }
   });
 
+  // Shared tab switching logic
+  function switchTab(el, index) {
+    var allTabs = el.querySelectorAll('.bw_nav_link');
+    var allPanes = el.querySelectorAll('.bw_tab_pane');
+    if (index < 0 || index >= allTabs.length) return;
+    allTabs.forEach(function(t) {
+      t.classList.remove('active');
+      t.setAttribute('aria-selected', 'false');
+      t.setAttribute('tabindex', '-1');
+    });
+    allPanes.forEach(function(p) { p.classList.remove('active'); });
+    allTabs[index].classList.add('active');
+    allTabs[index].setAttribute('aria-selected', 'true');
+    allTabs[index].setAttribute('tabindex', '0');
+    allPanes[index].classList.add('active');
+    if (el._bw_state) el._bw_state.activeIndex = index;
+  }
+
   return {
     t: 'div',
     a: { class: 'bw_tabs' },
@@ -519,24 +547,8 @@ export function makeTabs(props = {}) {
               role: 'tab',
               tabindex: index === actualActiveIndex ? '0' : '-1',
               'aria-selected': index === actualActiveIndex ? 'true' : 'false',
-              'data-tab-index': index,
               onclick: (e) => {
-                const tabsContainer = e.target.closest('.bw_tabs');
-                const allTabs = tabsContainer.querySelectorAll('.bw_nav_link');
-                const allPanes = tabsContainer.querySelectorAll('.bw_tab_pane');
-
-                allTabs.forEach(t => {
-                  t.classList.remove('active');
-                  t.setAttribute('aria-selected', 'false');
-                  t.setAttribute('tabindex', '-1');
-                });
-                allPanes.forEach(p => p.classList.remove('active'));
-
-                e.target.classList.add('active');
-                e.target.setAttribute('aria-selected', 'true');
-                e.target.setAttribute('tabindex', '0');
-                const targetIndex = parseInt(e.target.getAttribute('data-tab-index'));
-                allPanes[targetIndex].classList.add('active');
+                switchTab(e.target.closest('.bw_tabs'), index);
               }
             },
             c: tab.label
@@ -559,6 +571,10 @@ export function makeTabs(props = {}) {
     o: {
       type: 'tabs',
       state: { activeIndex: actualActiveIndex },
+      handle: {
+        setActiveTab: switchTab,
+        getActiveTab: function(el) { return (el._bw_state && el._bw_state.activeIndex) || 0; }
+      },
       mounted: function(el) {
         var tablist = el.querySelector('[role="tablist"]');
         if (!tablist) return;
@@ -644,7 +660,13 @@ export function makeAlert(props = {}) {
         },
         c: '×'
       }
-    ].filter(Boolean)
+    ].filter(Boolean),
+    o: {
+      type: 'alert',
+      handle: {
+        dismiss: function(el) { if (el && el.parentNode) el.parentNode.removeChild(el); }
+      }
+    }
   };
 }
 
@@ -742,6 +764,24 @@ export function makeProgress(props = {}) {
         'aria-valuemax': max
       },
       c: label || `${percentage}%`
+    },
+    o: {
+      type: 'progress',
+      handle: {
+        setValue: function(el, n) {
+          var bar = el.querySelector('.bw_progress_bar');
+          if (!bar) return;
+          var maxVal = parseInt(bar.getAttribute('aria-valuemax')) || 100;
+          var pct = Math.round((n / maxVal) * 100);
+          bar.style.width = pct + '%';
+          bar.setAttribute('aria-valuenow', n);
+          bar.textContent = pct + '%';
+        },
+        getValue: function(el) {
+          var bar = el.querySelector('.bw_progress_bar');
+          return bar ? parseInt(bar.getAttribute('aria-valuenow')) || 0 : 0;
+        }
+      }
     }
   };
 }
@@ -1710,8 +1750,8 @@ export function makePagination(props = {}) {
     t: 'li',
     a: { class: `bw_page_item ${currentPage <= 1 ? 'bw_disabled' : ''}`.trim() },
     c: {
-      t: 'a',
-      a: { class: 'bw_page_link', href: '#', onclick: handleClick(currentPage - 1), 'aria-label': 'Previous' },
+      t: 'button',
+      a: { class: 'bw_page_link', type: 'button', onclick: handleClick(currentPage - 1), 'aria-label': 'Previous', disabled: currentPage <= 1 ? true : undefined },
       c: '\u2039'
     }
   });
@@ -1723,8 +1763,8 @@ export function makePagination(props = {}) {
         t: 'li',
         a: { class: `bw_page_item ${pageNum === currentPage ? 'bw_active' : ''}`.trim() },
         c: {
-          t: 'a',
-          a: { class: 'bw_page_link', href: '#', onclick: handleClick(pageNum) },
+          t: 'button',
+          a: { class: 'bw_page_link', type: 'button', onclick: handleClick(pageNum), 'aria-current': pageNum === currentPage ? 'page' : undefined },
           c: '' + pageNum
         }
       });
@@ -1736,8 +1776,8 @@ export function makePagination(props = {}) {
     t: 'li',
     a: { class: `bw_page_item ${currentPage >= pages ? 'bw_disabled' : ''}`.trim() },
     c: {
-      t: 'a',
-      a: { class: 'bw_page_link', href: '#', onclick: handleClick(currentPage + 1), 'aria-label': 'Next' },
+      t: 'button',
+      a: { class: 'bw_page_link', type: 'button', onclick: handleClick(currentPage + 1), 'aria-label': 'Next', disabled: currentPage >= pages ? true : undefined },
       c: '\u203A'
     }
   });
@@ -1751,6 +1791,26 @@ export function makePagination(props = {}) {
         class: `bw_pagination ${size ? 'bw_pagination_' + size : ''} ${className}`.trim()
       },
       c: items
+    },
+    o: {
+      type: 'pagination',
+      state: { currentPage: currentPage, pages: pages },
+      handle: {
+        setPage: function(el, n) {
+          if (n < 1 || n > pages) return;
+          var allItems = el.querySelectorAll('.bw_page_item');
+          for (var i = 0; i < allItems.length; i++) {
+            allItems[i].classList.remove('bw_active');
+          }
+          // +1 offset: first item is prev arrow
+          if (allItems[n]) allItems[n].classList.add('bw_active');
+          if (el._bw_state) el._bw_state.currentPage = n;
+          if (onPageChange) onPageChange(n);
+        },
+        getPage: function(el) {
+          return (el._bw_state && el._bw_state.currentPage) || 1;
+        }
+      }
     }
   };
 }
@@ -1899,7 +1959,6 @@ export function makeAccordion(props = {}) {
                 class: `bw_accordion_button ${item.open ? '' : 'bw_collapsed'}`.trim(),
                 type: 'button',
                 'aria-expanded': item.open ? 'true' : 'false',
-                'data-accordion-index': index,
                 onclick: function(e) {
                   var btn = e.target.closest('.bw_accordion_button');
                   var accordionEl = btn.closest('.bw_accordion');
@@ -1974,7 +2033,43 @@ export function makeAccordion(props = {}) {
     }),
     o: {
       type: 'accordion',
-      state: { multiOpen: multiOpen }
+      state: { multiOpen: multiOpen },
+      handle: {
+        toggle: function(el, index) {
+          var items = el.querySelectorAll('.bw_accordion_item');
+          if (index < 0 || index >= items.length) return;
+          var btn = items[index].querySelector('.bw_accordion_button');
+          if (btn) btn.click();
+        },
+        openAll: function(el) {
+          var items = el.querySelectorAll('.bw_accordion_item');
+          for (var i = 0; i < items.length; i++) {
+            var collapse = items[i].querySelector('.bw_accordion_collapse');
+            var btn = items[i].querySelector('.bw_accordion_button');
+            if (!collapse.classList.contains('bw_collapse_show')) {
+              collapse.classList.add('bw_collapse_show');
+              collapse.style.maxHeight = 'none';
+              btn.classList.remove('bw_collapsed');
+              btn.setAttribute('aria-expanded', 'true');
+            }
+          }
+        },
+        closeAll: function(el) {
+          var items = el.querySelectorAll('.bw_accordion_item');
+          for (var i = 0; i < items.length; i++) {
+            var collapse = items[i].querySelector('.bw_accordion_collapse');
+            var btn = items[i].querySelector('.bw_accordion_button');
+            if (collapse.classList.contains('bw_collapse_show')) {
+              collapse.style.maxHeight = collapse.scrollHeight + 'px';
+              collapse.offsetHeight;
+              collapse.style.maxHeight = '0px';
+              collapse.classList.remove('bw_collapse_show');
+              btn.classList.add('bw_collapsed');
+              btn.setAttribute('aria-expanded', 'false');
+            }
+          }
+        }
+      }
     }
   };
 }
@@ -2064,6 +2159,14 @@ export function makeModal(props = {}) {
     },
     o: {
       type: 'modal',
+      handle: {
+        open: function(el) {
+          el.classList.add('bw_modal_show');
+          el.style.display = 'flex';
+          document.body.style.overflow = 'hidden';
+        },
+        close: function(el) { closeModal(el); }
+      },
       mounted: function(el) {
         // Click backdrop to close
         el.addEventListener('click', function(e) {
@@ -2122,9 +2225,8 @@ export function makeToast(props = {}) {
   return {
     t: 'div',
     a: {
-      class: `bw_toast ${variantClass(variant)} ${className}`.trim(),
-      role: 'alert',
-      'data-position': position
+      class: `bw_toast ${variantClass(variant)} bw_toast_${position.replace(/-/g, '_')} ${className}`.trim(),
+      role: 'alert'
     },
     c: [
       (title) && {
@@ -2158,6 +2260,12 @@ export function makeToast(props = {}) {
     ].filter(Boolean),
     o: {
       type: 'toast',
+      handle: {
+        dismiss: function(el) {
+          el.classList.add('bw_toast_hiding');
+          setTimeout(function() { if (el.parentNode) el.parentNode.removeChild(el); }, 300);
+        }
+      },
       mounted: function(el) {
         // Trigger show animation
         requestAnimationFrame(function() {
@@ -2515,7 +2623,7 @@ export function makeCarousel(props = {}) {
     var total = carouselEl.querySelectorAll('.bw_carousel_slide').length;
     if (index < 0) index = total - 1;
     if (index >= total) index = 0;
-    carouselEl.setAttribute('data-carousel-index', index);
+    carouselEl._bw_carouselIndex = index;
     var track = carouselEl.querySelector('.bw_carousel_track');
     track.style.transform = 'translateX(-' + (index * 100) + '%)';
     // Update indicators
@@ -2572,7 +2680,7 @@ export function makeCarousel(props = {}) {
         'aria-label': 'Previous slide',
         onclick: function(e) {
           var carousel = e.target.closest('.bw_carousel');
-          var idx = parseInt(carousel.getAttribute('data-carousel-index') || '0');
+          var idx = carousel._bw_carouselIndex || 0;
           goToSlide(carousel, idx - 1);
         }
       },
@@ -2586,7 +2694,7 @@ export function makeCarousel(props = {}) {
         'aria-label': 'Next slide',
         onclick: function(e) {
           var carousel = e.target.closest('.bw_carousel');
-          var idx = parseInt(carousel.getAttribute('data-carousel-index') || '0');
+          var idx = carousel._bw_carouselIndex || 0;
           goToSlide(carousel, idx + 1);
         }
       },
@@ -2606,11 +2714,9 @@ export function makeCarousel(props = {}) {
             class: 'bw_carousel_indicator' + (i === startIndex ? ' active' : ''),
             type: 'button',
             'aria-label': 'Go to slide ' + (i + 1),
-            'data-slide-index': i,
             onclick: function(e) {
               var carousel = e.target.closest('.bw_carousel');
-              var idx = parseInt(e.target.getAttribute('data-slide-index'));
-              goToSlide(carousel, idx);
+              goToSlide(carousel, i);
             }
           }
         };
@@ -2624,17 +2730,37 @@ export function makeCarousel(props = {}) {
       class: ('bw_carousel ' + className).trim(),
       style: 'height: ' + height,
       tabindex: '0',
-      'aria-roledescription': 'carousel',
-      'data-carousel-index': startIndex
+      'aria-roledescription': 'carousel'
     },
     c: children,
     o: {
       type: 'carousel',
       state: { activeIndex: startIndex, autoPlay: autoPlay, interval: interval },
+      handle: {
+        goToSlide: function(el, index) { goToSlide(el, index); },
+        next: function(el) { goToSlide(el, (el._bw_carouselIndex || 0) + 1); },
+        prev: function(el) { goToSlide(el, (el._bw_carouselIndex || 0) - 1); },
+        getActiveIndex: function(el) { return el._bw_carouselIndex || 0; },
+        pause: function(el) {
+          if (el._bw_carouselInterval) {
+            clearInterval(el._bw_carouselInterval);
+            el._bw_carouselInterval = null;
+          }
+        },
+        play: function(el) {
+          if (!el._bw_carouselInterval && el._bw_state) {
+            var ms = el._bw_state.interval || 5000;
+            el._bw_carouselInterval = setInterval(function() {
+              goToSlide(el, (el._bw_carouselIndex || 0) + 1);
+            }, ms);
+          }
+        }
+      },
       mounted: function(el) {
+        el._bw_carouselIndex = startIndex;
         // Keyboard navigation
         el.addEventListener('keydown', function(e) {
-          var idx = parseInt(el.getAttribute('data-carousel-index') || '0');
+          var idx = el._bw_carouselIndex || 0;
           if (e.key === 'ArrowLeft') {
             e.preventDefault();
             goToSlide(el, idx - 1);
@@ -2646,7 +2772,7 @@ export function makeCarousel(props = {}) {
         // Auto-play
         if (autoPlay) {
           var intervalId = setInterval(function() {
-            var idx = parseInt(el.getAttribute('data-carousel-index') || '0');
+            var idx = el._bw_carouselIndex || 0;
             goToSlide(el, idx + 1);
           }, interval);
           el._bw_carouselInterval = intervalId;
@@ -2656,7 +2782,7 @@ export function makeCarousel(props = {}) {
           });
           el.addEventListener('mouseleave', function() {
             el._bw_carouselInterval = setInterval(function() {
-              var idx = parseInt(el.getAttribute('data-carousel-index') || '0');
+              var idx = el._bw_carouselIndex || 0;
               goToSlide(el, idx + 1);
             }, interval);
           });
@@ -2772,7 +2898,13 @@ export function makeStatCard(props = {}) {
     t: 'div',
     a: { class: classes, style: style },
     c: children,
-    o: { type: 'stat-card' }
+    o: {
+      type: 'stat-card',
+      slots: {
+        value: '.bw_stat_value',
+        label: '.bw_stat_label'
+      }
+    }
   };
 }
 
@@ -3451,7 +3583,7 @@ export function makeChipInput(props = {}) {
   function makeChipEl(text) {
     return {
       t: 'span',
-      a: { class: 'bw_chip', 'data-chip-value': text },
+      a: { class: 'bw_chip' },
       c: [
         text,
         {
@@ -3462,9 +3594,8 @@ export function makeChipInput(props = {}) {
             'aria-label': 'Remove ' + text,
             onclick: function(e) {
               var chip = e.target.closest('.bw_chip');
-              var val = chip.getAttribute('data-chip-value');
               chip.parentNode.removeChild(chip);
-              if (onRemove) onRemove(val);
+              if (onRemove) onRemove(text);
             }
           },
           c: '\u00D7'
@@ -3492,7 +3623,7 @@ export function makeChipInput(props = {}) {
               // Insert chip before the input
               var chipEl = document.createElement('span');
               chipEl.className = 'bw_chip';
-              chipEl.setAttribute('data-chip-value', val);
+              chipEl._bw_chipValue = val;
               chipEl.innerHTML = '';
               chipEl.textContent = val;
               var removeBtn = document.createElement('button');
@@ -3515,7 +3646,7 @@ export function makeChipInput(props = {}) {
               var chipEls = wrapper.querySelectorAll('.bw_chip');
               if (chipEls.length) {
                 var last = chipEls[chipEls.length - 1];
-                var removedVal = last.getAttribute('data-chip-value');
+                var removedVal = last._bw_chipValue || last.firstChild.textContent;
                 last.parentNode.removeChild(last);
                 if (onRemove) onRemove(removedVal);
               }
@@ -3524,7 +3655,50 @@ export function makeChipInput(props = {}) {
         }
       }
     ],
-    o: { type: 'chip-input' }
+    o: {
+      type: 'chip-input',
+      handle: {
+        addChip: function(el, text) {
+          if (!text) return;
+          var input = el.querySelector('.bw_chip_field');
+          var chipEl = document.createElement('span');
+          chipEl.className = 'bw_chip';
+          chipEl._bw_chipValue = text;
+          chipEl.textContent = text;
+          var removeBtn = document.createElement('button');
+          removeBtn.type = 'button';
+          removeBtn.className = 'bw_chip_remove';
+          removeBtn.setAttribute('aria-label', 'Remove ' + text);
+          removeBtn.textContent = '\u00D7';
+          removeBtn.onclick = function() { chipEl.parentNode.removeChild(chipEl); };
+          chipEl.appendChild(removeBtn);
+          el.insertBefore(chipEl, input);
+        },
+        removeChip: function(el, text) {
+          var chips = el.querySelectorAll('.bw_chip');
+          for (var i = 0; i < chips.length; i++) {
+            if ((chips[i]._bw_chipValue || chips[i].firstChild.textContent) === text) {
+              chips[i].parentNode.removeChild(chips[i]);
+              return;
+            }
+          }
+        },
+        getChips: function(el) {
+          var chips = el.querySelectorAll('.bw_chip');
+          var values = [];
+          for (var i = 0; i < chips.length; i++) {
+            values.push(chips[i]._bw_chipValue || chips[i].firstChild.textContent);
+          }
+          return values;
+        },
+        clear: function(el) {
+          var chips = el.querySelectorAll('.bw_chip');
+          for (var i = chips.length - 1; i >= 0; i--) {
+            chips[i].parentNode.removeChild(chips[i]);
+          }
+        }
+      }
+    }
   };
 }
 

package/src/bitwrench-code-edit.js

@@ -4,11 +4,9 @@
  * Provides bw.highlight() for tokenizing JS/CSS/HTML into TACO spans,
  * and bw.codeEditor() for a live editable code block with syntax coloring.
  *
- * Theme integration: The editor chrome (background, text color, font) reads
- * from CSS custom properties --bw_code_bg, --bw_code_text, --bw_font_mono,
- * falling back to built-in dark values when no theme is active. Syntax
- * highlighting colors are intentionally fixed (they are a code color scheme,
- * not brand colors). The bw_ce_light class is still supported for manual
+ * Theme integration: The editor chrome uses self-contained dark defaults.
+ * Syntax highlighting colors are intentionally fixed (they are a code color
+ * scheme, not brand colors). The bw_ce_light class is supported for manual
  * light-mode override.
  *
  * Can be loaded standalone (browser script tag after bitwrench.umd.js),
@@ -21,9 +19,9 @@
 // -- CSS (injected once) ----------------------------------------------
 var _cssInjected = false;
 var CSS_TEXT =
-  '.bw_ce{background:var(--bw_code_bg,#1e293b);border-radius:6px;border:1px solid rgba(255,255,255,0.08);overflow:auto}' +
+  '.bw_ce{background:#1e293b;border-radius:6px;border:1px solid rgba(255,255,255,0.08);overflow:auto}' +
   '.bw_ce pre{margin:0;padding:0}' +
-  '.bw_ce code{font-family:var(--bw_font_mono,"SF Mono",Monaco,"Cascadia Code",Consolas,monospace);font-size:0.875rem;line-height:1.6;color:var(--bw_code_text,#e2e8f0);outline:none;white-space:pre-wrap;display:block;padding:0.75rem 1rem}' +
+  '.bw_ce code{font-family:"SF Mono",Monaco,"Cascadia Code",Consolas,monospace;font-size:0.875rem;line-height:1.6;color:#e2e8f0;outline:none;white-space:pre-wrap;display:block;padding:0.75rem 1rem}' +
   '.bw_ce code:empty::before{content:"\\200b"}' +
   '.bw_ce .bw_ce_keyword{color:#c792ea}' +
   '.bw_ce .bw_ce_string{color:#c3e88d}' +
@@ -64,7 +62,7 @@ var CSS_TEXT =
   '.bw_ce_light.bw_ce .bw_ce_template_interp{color:#0891b2}' +
   // Line number gutter (opt-in via lineNumbers option)
   '.bw_ce_wrap{display:flex;flex-direction:row}' +
-  '.bw_ce_gutter{flex:0 0 auto;padding:0.75rem 0;text-align:right;user-select:none;-webkit-user-select:none;color:#546e7a;font-family:var(--bw_font_mono,"SF Mono",Monaco,"Cascadia Code",Consolas,monospace);font-size:0.875rem;line-height:1.6;border-right:1px solid rgba(255,255,255,0.08);overflow:hidden}' +
+  '.bw_ce_gutter{flex:0 0 auto;padding:0.75rem 0;text-align:right;user-select:none;-webkit-user-select:none;color:#546e7a;font-family:"SF Mono",Monaco,"Cascadia Code",Consolas,monospace;font-size:0.875rem;line-height:1.6;border-right:1px solid rgba(255,255,255,0.08);overflow:hidden}' +
   '.bw_ce_gutter span{display:block;padding:0 0.5rem 0 0.75rem}' +
   '.bw_ce_light .bw_ce_gutter{color:#9ca3af;border-right-color:#d8d8d8}';
 

package/src/bitwrench-color-utils.js

@@ -289,13 +289,18 @@ export function harmonize(sourceHex, targetHex, amount) {
  */
 export function deriveShades(hex) {
   var rgb = colorParse(hex);
+  // For light input colors (L > 75), mixing toward white produces invisible borders.
+  // Darken instead so borders remain visible against light backgrounds.
+  var borderColor = hexToHsl(hex)[2] > 75
+    ? adjustLightness(hex, -18)
+    : mixColor(hex, '#ffffff', 0.60);
   return {
     base: hex,
     hover: adjustLightness(hex, -10),
     active: adjustLightness(hex, -15),
     light: mixColor(hex, '#ffffff', 0.85),
     darkText: adjustLightness(hex, -40),
-    border: mixColor(hex, '#ffffff', 0.60),
+    border: borderColor,
     focus: 'rgba(' + rgb[0] + ',' + rgb[1] + ',' + rgb[2] + ',0.25)',
     textOn: textOnColor(hex)
   };
@@ -354,19 +359,27 @@ export function deriveAlternateConfig(config) {
   alt.secondary = deriveAlternateSeed(config.secondary);
   alt.tertiary = config.tertiary ? deriveAlternateSeed(config.tertiary) : alt.primary;
 
-  // Derive alternate surface colors from primary hue
+  // Derive alternate surface colors from primary hue.
+  // Check actual page surface brightness (not seed color brightness) to decide
+  // whether alternate should be dark or light.  The page surface is what the
+  // user sees; seeds can be dark while the page is still light (default L=96).
   var priHsl = hexToHsl(config.primary);
   var h = priHsl[0];
-  var isLight = isLightPalette(config);
+  var primarySurface = config.surface || hslToHex([h, 8, 96]);
+  var isLight = relativeLuminance(primarySurface) > 0.179;
 
   if (isLight) {
-    // Primary is light → alternate needs dark surfaces
+    // Page surface is light → alternate needs dark surfaces
     alt.light = hslToHex([h, Math.min(priHsl[1], 15), 15]);
     alt.dark = hslToHex([h, 5, 88]);
+    alt.surface = hslToHex([h, 12, 18]);
+    alt.background = hslToHex([h, 10, 14]);
   } else {
-    // Primary is dark → alternate needs light surfaces
+    // Page surface is dark → alternate needs light surfaces
     alt.light = hslToHex([h, Math.min(priHsl[1], 10), 96]);
     alt.dark = hslToHex([h, 10, 18]);
+    alt.surface = hslToHex([h, 8, 96]);
+    alt.background = hslToHex([h, 6, 98]);
   }
 
   // Semantic colors: harmonize toward primary, then invert for alternate
@@ -414,10 +427,18 @@ export function derivePalette(config) {
   var darkBase  = config.dark  || hslToHex([h, 10, 13]);
 
   // Background & surface tokens — tinted with primary hue for theme personality.
-  // Very subtle: bg at L=98/S=6, surface at L=96/S=8.
+  // Saturation high enough that the hue is visible (each theme feels distinct)
+  // but low enough to stay neutral and readable.
   // User can override with config.background / config.surface.
-  var bgBase = config.background || hslToHex([h, 6, 98]);
-  var surfBase = config.surface || hslToHex([h, 8, 96]);
+  var bgBase = config.background || hslToHex([h, 22, 96]);
+  var surfBase = config.surface || hslToHex([h, 25, 94]);
+
+  // surfaceAlt: subtle background variant for striped rows, hover states, headers.
+  // Slightly lighter than surface in dark mode, slightly darker in light mode.
+  var surfHsl = hexToHsl(surfBase);
+  var surfAlt = surfHsl[2] <= 50
+    ? hslToHex([surfHsl[0], surfHsl[1], Math.min(surfHsl[2] + 8, 100)])
+    : hslToHex([surfHsl[0], surfHsl[1], Math.max(surfHsl[2] - 3, 0)]);
 
   var palette = {
     primary:    deriveShades(config.primary),
@@ -430,7 +451,8 @@ export function derivePalette(config) {
     light:      deriveShades(lightBase),
     dark:       deriveShades(darkBase),
     background: bgBase,
-    surface:    surfBase
+    surface:    surfBase,
+    surfaceAlt: surfAlt
   };
 
   return palette;