@kolkrabbi/kol-shell 0.10.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-shell",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "private": false,
   "description": "KOL application shell — fixed 48px NavRail + AppShell layout root, PageShell/PageHeader scaffolds, ContentFilters catalog organism, GridCard, SettingsScaffold, WalkthroughPanel, ShortcutsOverlay. App chrome (kol-framework owns site chrome). Nav items, content, shortcuts and settings are consumer-injected. Sits above @kolkrabbi/kol-{theme,component,framework}.",
   "license": "MIT",
@@ -20,10 +20,10 @@
     "react-dom": "^18.3.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-component": "^0.108.0",
-    "@kolkrabbi/kol-framework": "^0.28.0",
+    "@kolkrabbi/kol-icons": "^0.22.0",
+    "@kolkrabbi/kol-component": "^0.110.0",
     "@kolkrabbi/kol-theme": "^0.72.0",
-    "@kolkrabbi/kol-icons": "^0.22.0"
+    "@kolkrabbi/kol-framework": "^0.28.0"
   },
   "files": [
     "src",

package/src/AppShell.jsx

@@ -26,6 +26,14 @@ import TouchDeviceOverlay, { useTouchPrimary } from './TouchDeviceOverlay.jsx'
  *                                        localStorage `kol-desktop` is '1' (fxr's gate); `overlay` keeps the shell and
  *                                        mounts TouchDeviceOverlay once (monitor's)
  * @param {string}  props.appName       TouchDeviceOverlay's subject
+ * @param {string}  props.pageWash      a CSS colour painted by `PageShell` OVER the shell's primary back
+ *                                        (ShellPageWash, kol-monitor 2026-08-27 — user: "the back of the back
+ *                                        should be primary — then you can just add transparent on top to step
+ *                                        up the lightness"): `'var(--kol-fg-12)'` steps the page a rung lighter
+ *                                        without swapping the surface. Set as `--kol-shell-page-wash` on the
+ *                                        content wrapper, so a page root that is not `PageShell` reads it too.
+ *                                        Default none — unset renders exactly as before. A prop, not a token
+ *                                        an app binds, because fxr's stylesheet is imports-only by rule.
  */
 export default function AppShell({
   items,
@@ -38,6 +46,7 @@ export default function AppShell({
   railToggleKey,
   touch = 'shell',
   appName,
+  pageWash,
   children,
 }) {
   const [navHidden, setNavHidden] = useState(false)
@@ -61,7 +70,9 @@ export default function AppShell({
 
   let wantsDesktop = false
   try { wantsDesktop = typeof localStorage !== 'undefined' && localStorage.getItem('kol-desktop') === '1' } catch { /* storage blocked */ }
-  if (touch === 'bare' && coarse && !wantsDesktop) return <div className="kol-app-shell contents">{children}</div>
+  /* the wash variable rides the bare wrapper too (custom properties inherit
+   * through `display: contents`); there is no box here to paint the back on */
+  if (touch === 'bare' && coarse && !wantsDesktop) return <div className="kol-app-shell contents" style={{ '--kol-shell-page-wash': pageWash }}>{children}</div>
 
   return (
     <NavHiddenContext.Provider value={{ navHidden, setNavHidden }}>
@@ -79,7 +90,9 @@ export default function AppShell({
           themeToggle={themeToggle}
         />
       )}
-      <div style={{ marginLeft: navHidden ? 0 : 'var(--kol-shell-rail-width)' }}>
+      {/* THE BACK OF THE BACK — surface-primary, always, in every app; the
+        * page paints its wash over it (ShellPageWash). */}
+      <div className="bg-surface-primary" style={{ marginLeft: navHidden ? 0 : 'var(--kol-shell-rail-width)', '--kol-shell-page-wash': pageWash }}>
         {children}
       </div>
       </div>

package/src/PageShell.jsx

@@ -8,6 +8,12 @@
  *
  * Gutter is `--kol-shell-page-pad` (kol-theme). `PageBleed` breaks it for
  * full-width embeds (monitor's rack bleed).
+ *
+ * The background is `var(--kol-shell-page-wash, var(--kol-surface-primary))`
+ * (ShellPageWash, 2026-08-27): unset, today's primary pixel; set by
+ * `AppShell pageWash`, a transparent wash over the shell's primary back —
+ * the lightness steps up and the structure stays visible, which an opaque
+ * surface swap would hide. The ink stays `text-auto` (surface-on-primary).
  */
 export default function PageShell({ mode = 'scroll', className = '', style, children }) {
   const modeStyle =
@@ -16,8 +22,9 @@ export default function PageShell({ mode = 'scroll', className = '', style, chil
       : { minHeight: '100vh' }
   return (
     <div
-      className={`bg-surface-primary ${className}`.trim()}
+      className={`text-auto ${className}`.trim()}
       style={{
+        background: 'var(--kol-shell-page-wash, var(--kol-surface-primary))',
         padding: 'var(--kol-shell-page-pad)',
         display: 'flex',
         flexDirection: 'column',