@kolkrabbi/kol-shell 0.26.0 → 0.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-shell",
-  "version": "0.26.0",
+  "version": "0.28.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.136.0",
-    "@kolkrabbi/kol-framework": "^0.35.0",
     "@kolkrabbi/kol-icons": "^0.25.0",
-    "@kolkrabbi/kol-theme": "^0.100.0"
+    "@kolkrabbi/kol-component": "^0.137.0",
+    "@kolkrabbi/kol-framework": "^0.35.0",
+    "@kolkrabbi/kol-theme": "^0.108.0"
   },
   "files": [
     "src",

package/src/AppShell.jsx

@@ -155,6 +155,20 @@ export default function AppShell({
 
   /* the rail comes back on every route change */
   useEffect(() => { setNavHidden(false) }, [currentPath])
+
+  /* THE WASH ALSO GOES ON THE ROOT (2026-08-30). It is set on the content
+   * wrapper below, which every page inherits — but a PORTALLED surface does
+   * not: `.kol-dd-panel` renders at document.body, so it read the fallback
+   * `transparent` while its own trigger, inside the shell, took the wash. The
+   * two halves of one connected control rendered at different values, which is
+   * exactly what the user saw. Anything floating over the page is still ON the
+   * page as far as this film is concerned. */
+  useEffect(() => {
+    const root = document.documentElement
+    if (pageWash == null) { root.style.removeProperty('--kol-shell-page-wash'); return undefined }
+    root.style.setProperty('--kol-shell-page-wash', pageWash)
+    return () => root.style.removeProperty('--kol-shell-page-wash')
+  }, [pageWash])
   /* one key toggles the rail — never while typing in a field */
   useEffect(() => {
     if (!railToggleKey) return undefined

package/src/SettingsScaffold.jsx

@@ -1,5 +1,5 @@
 import { useState } from 'react'
-import { ContentFilters } from '@kolkrabbi/kol-component'
+import { ContentFilters, IconFrame } from '@kolkrabbi/kol-component'
 import PageShell from './PageShell.jsx'
 import PageHeader from './PageHeader.jsx'
 
@@ -54,6 +54,13 @@ import PageHeader from './PageHeader.jsx'
  *                                  A FUNCTION receives `(tab, setTab)` — for a control that has to
  *                                  move the page, e.g. an icon pair that jumps back to Settings
  * @param {string}    props.tone            forwarded to ContentFilters (`sunken` is fxr's approved page)
+ * @param {ReactNode} props.picker         the app's own picker for the masthead cluster —
+ *                                          fxr opens a chrome, kol-r2b2 a bucket. Optional
+ * @param {ReactNode} props.themeToggle     the app's ThemeToggle node. A NODE, not rendered
+ *                                          here, because it lives in kol-framework and shell
+ *                                          dropped that peer in 0.16.0
+ * @param {Function}  props.onOpenSettings  the gear's handler — opens the app's settings
+ *                                          drawer. The scaffold draws the control
  * @param {Object}    props.filtersProps    escape hatch — anything else the organism takes
  */
 export default function SettingsScaffold({
@@ -67,6 +74,9 @@ export default function SettingsScaffold({
   searchKeys,
   trailingActions,
   tone = 'sunken',
+  picker,
+  themeToggle,
+  onOpenSettings,
   filtersProps,
 }) {
   const [tab, setTab] = useState(defaultTab ?? tabs[0]?.value)
@@ -85,13 +95,50 @@ export default function SettingsScaffold({
   const viewTabs = tabs.filter((t) => t.row !== 'layout')
   const layoutTabs = tabs.filter((t) => t.row === 'layout')
 
+  /* THE MASTHEAD CLUSTER — picker · theme toggle · gear, in that order, on the
+   * subtitle's baseline (user ruling 2026-08-30, off kol-fxr's approved page;
+   * kol-r2b2's row 1 is the same shape). It was a raw `header.actions` slot, so
+   * fxr and r2b2 each hand-built it and kol-mirror and kol-monitor passed
+   * NOTHING — which is the whole of why the three settings pages did not match.
+   * Order, gap and tone are the scaffold's now; only the picker's contents are
+   * the app's.
+   *
+   * `themeToggle` is a NODE rather than drawn here: it lives in kol-framework,
+   * and shell dropped that peer in 0.16.0. The gear is `IconFrame`, which is a
+   * peer, so the DS rules its glyph, tone and size.
+   *
+   * Pass none of the three and no cluster renders — mirror and monitor are
+   * untouched until they opt in. An explicit `header.actions` still wins. */
+  const cluster = picker || themeToggle || onOpenSettings ? (
+    <div className="flex items-center gap-2">
+      {picker}
+      {themeToggle}
+      {onOpenSettings && (
+        <IconFrame
+          name="settings-01"
+          variant="primary"
+          tone={tone}
+          size="sm"
+          onClick={onOpenSettings}
+          title="Display settings"
+          aria-label="Display settings"
+        />
+      )}
+    </div>
+  ) : null
+
   return (
     <PageShell mode="fixed">
       {/* `header` is spread onto the PageHeader (PageHeaderMonoTitle addendum,
         * kol-fxr 2026-08-27): a consumer could not reach this title at all —
         * `voice="mono"`, `size`, `titleClass`, `eyebrow` all pass through.
         * `actions` is where the drawer opener goes. */}
-      <PageHeader title={active?.title} subtitle={active?.subtitle} {...header} />
+      <PageHeader
+        title={active?.title}
+        subtitle={active?.subtitle}
+        actions={cluster}
+        {...header}
+      />
       <ContentFilters
         tone={tone}
         title={title}