@kolkrabbi/kol-framework 0.27.0 → 0.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-framework",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "KOL app shell — sidenav, layout, theme toggle, footer, heroes + brand color layer. SideNav takes nav data as props so the tree stays app-local.",
   "license": "MIT",
   "type": "module",
@@ -20,8 +20,8 @@
     "react-router-dom": "^6.0.0 || ^7.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-icons": "^0.18.0",
-    "@kolkrabbi/kol-component": "^0.80.0"
+    "@kolkrabbi/kol-component": "^0.99.0",
+    "@kolkrabbi/kol-icons": "^0.20.0"
   },
   "files": [
     "src",

package/src/ThemeToggle.jsx

@@ -64,6 +64,11 @@ import { useTheme } from './theme.js'
  * sees) and one click commits it. The reset lives behind a modifier — alt- or
  * shift-click — which is the "separate affordance" the ruling allows, with no
  * new chrome and no third stop. */
+/* The VISIBLE label names the TARGET, not the state (ThemeToggleLabelTarget,
+ * user 2026-08-27: "should it not say dark mode in light mode and vice versa?
+ * as to what the button actually does when you click it?"). A button's label
+ * names its action — the aria-label / title always said "Switch to …"; the eye
+ * was told the opposite. Rendered as MODE_LABEL[next], never MODE_LABEL[shown]. */
 const MODE_LABEL = { light: 'Light mode', dark: 'Dark mode' }
 const SLOT = { dark: 0, light: 1 }
 
@@ -171,7 +176,7 @@ export default function ThemeToggle({
           {iconSwap(bare ? glyphWithText : glyphSolo)}
         </span>
         <span className="kol-sidenav-hop-label flex-1 min-w-0 text-left">
-          {MODE_LABEL[shown]}
+          {MODE_LABEL[next]}
         </span>
       </button>
     )
@@ -186,7 +191,7 @@ export default function ThemeToggle({
     return (
       <button {...shared} className={cls.replace(/\s+/g, ' ').trim()}>
         {!iconRight && iconSwap(glyph)}
-        {label && <span className={fullWidth ? 'flex-1 min-w-0 text-left' : ''}>{MODE_LABEL[shown]}</span>}
+        {label && <span className={fullWidth ? 'flex-1 min-w-0 text-left' : ''}>{MODE_LABEL[next]}</span>}
         {iconRight && iconSwap(glyph)}
       </button>
     )
@@ -207,7 +212,7 @@ export default function ThemeToggle({
   return (
     <button {...shared} className={`kol-theme-toggle ${fillCls} kol-btn-${size} ${mono} gap-2 ${width} ${className}`.replace(/\s+/g, ' ').trim()}>
       {!iconRight && iconSwap(glyphWithText)}
-      <span className={fullWidth ? 'flex-1 min-w-0 text-left' : ''}>{MODE_LABEL[shown]}</span>
+      <span className={fullWidth ? 'flex-1 min-w-0 text-left' : ''}>{MODE_LABEL[next]}</span>
       {iconRight && iconSwap(glyphWithText)}
     </button>
   )

package/src/index.js

@@ -13,7 +13,7 @@ export { default as SideNav } from './SideNav.jsx'
 export { default as useDragResize } from './useDragResize.js'
 export { default as ShellHeader, HEADER_ICON } from './ShellHeader.jsx'
 export { default as ThemeToggle } from './ThemeToggle.jsx'
-export { useTheme, applyTheme, getInitialTheme, THEME_STORAGE_KEY } from './theme.js'
+export { useTheme, applyTheme, getInitialTheme, THEME_STORAGE_KEY, THEME_BOOT_SCRIPT } from './theme.js'
 export { default as Layout } from './Layout.jsx'
 export { default as PageSection } from './PageSection.jsx'
 export { default as PortalFooter } from './PortalFooter.jsx'

package/src/theme.js

@@ -18,6 +18,22 @@ import { useEffect, useState } from 'react'
 
 export const THEME_STORAGE_KEY = 'kol-theme'
 
+/* THE NO-FLASH BOOT SNIPPET (ShellHomeSystem, 2026-08-27 — every app hand-wrote
+ * it against this file's key): inline it in index.html before the app script.
+ * USER law: explicit choice > system > light — a saved light/dark stamps
+ * `data-theme` before first paint; no saved choice leaves the page un-stamped
+ * so the theme CSS follows the OS live. The versioned cutover (v3, 2026-07-30)
+ * discards stamps written by the old two-state toggle, once. */
+export const THEME_BOOT_SCRIPT = `try {
+  if (localStorage.getItem('kol-theme-v') !== '3') {
+    localStorage.removeItem('kol-theme')
+    localStorage.removeItem('theme')
+    localStorage.setItem('kol-theme-v', '3')
+  }
+  var t = localStorage.getItem('kol-theme')
+  if (t === 'light' || t === 'dark') document.documentElement.dataset.theme = t
+} catch (e) {}`
+
 function getExplicitTheme() {
   const attr = document.documentElement.dataset.theme
   if (attr === 'light' || attr === 'dark') return attr