@kolkrabbi/kol-shell 0.25.0 → 0.27.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-shell",
-  "version": "0.25.0",
+  "version": "0.27.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.135.0",
+    "@kolkrabbi/kol-component": "^0.136.0",
     "@kolkrabbi/kol-icons": "^0.25.0",
     "@kolkrabbi/kol-framework": "^0.35.0",
-    "@kolkrabbi/kol-theme": "^0.99.0"
+    "@kolkrabbi/kol-theme": "^0.106.0"
   },
   "files": [
     "src",

package/src/AppShell.jsx

@@ -1,6 +1,7 @@
 import { useCallback, useEffect, useRef, useState } from 'react'
 import NavRail from './NavRail.jsx'
 import { NavHiddenContext } from './navHidden.js'
+import { SettingsToggleContext } from './settingsToggle.js'
 import TouchDeviceOverlay, { useTouchPrimary } from './TouchDeviceOverlay.jsx'
 
 /**
@@ -71,6 +72,14 @@ import TouchDeviceOverlay, { useTouchPrimary } from './TouchDeviceOverlay.jsx'
  *                                        Bare and with ⌥, ignored while typing in a field. Needs
  *                                        `settingsPath`; alone it does nothing.
  */
+/* the physical-key name for a bound character. Only the keys people actually
+ * bind — a full layout table would be a lie about coverage. */
+const CODE_FOR_KEY = {
+  ',': 'Comma', '.': 'Period', '/': 'Slash', ';': 'Semicolon', "'": 'Quote',
+  '[': 'BracketLeft', ']': 'BracketRight', '\\': 'Backslash', '`': 'Backquote',
+  '-': 'Minus', '=': 'Equal',
+}
+
 export default function AppShell({
   items,
   bottomItems,
@@ -117,7 +126,15 @@ export default function AppShell({
   useEffect(() => {
     if (!settingsKey || !settingsPath) return undefined
     const onKey = (e) => {
-      if (e.key !== settingsKey || e.metaKey || e.ctrlKey) return
+      /* MATCH THE PHYSICAL KEY (SettingsToggleGestureConsumerSeam, kol-fxr
+       * 2026-08-30). Option rewrites `e.key` on macOS — **the chord for `,` is
+       * `≤`** — so an `e.key` comparison silently drops it while the bare key
+       * works, which is the worst way to fail. `e.code` is the same physical key
+       * either way; it is why the Option-digit handler above reads `Digit1…`
+       * rather than `¡ ™ £`. `e.key` still matches too, so a character with no
+       * entry in the table below is unaffected. */
+      const wanted = CODE_FOR_KEY[settingsKey]
+      if (!(e.key === settingsKey || (wanted && e.code === wanted)) || e.metaKey || e.ctrlKey) return
       const t = e.target
       if (t?.isContentEditable || /^(INPUT|TEXTAREA|SELECT)$/.test(t?.tagName)) return
       e.preventDefault()
@@ -191,6 +208,7 @@ export default function AppShell({
 
   return (
     <NavHiddenContext.Provider value={{ navHidden, setNavHidden }}>
+      <SettingsToggleContext.Provider value={toggleSettings}>
       {/* `kol-app-shell` = the app tier: neutral ::selection (kol-theme).
         * A hidden rail zeroes the live width token, so the content's own
         * margin closes with it — one variable, both sides. */}
@@ -218,6 +236,7 @@ export default function AppShell({
         {children}
       </div>
       </div>
+      </SettingsToggleContext.Provider>
     </NavHiddenContext.Provider>
   )
 }

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}

package/src/index.js

@@ -12,6 +12,7 @@
  */
 export { default as AppShell } from './AppShell.jsx'
 export { NavHiddenContext, useNavHidden } from './navHidden.js'
+export { SettingsToggleContext, useSettingsToggle } from './settingsToggle.js'
 export { default as NavRail } from './NavRail.jsx'
 export { default as PageShell, PageBleed } from './PageShell.jsx'
 export { default as PageHeader } from './PageHeader.jsx'

package/src/settingsToggle.js

@@ -0,0 +1,22 @@
+import { createContext, useContext } from 'react'
+
+/* Settings-toggle context — own file so AppShell exports only components
+ * (the react-refresh constraint `navHidden.js` was split out for).
+ *
+ * WHY A HOOK AND NOT JUST THE PROPS (SettingsToggleGestureConsumerSeam, kol-fxr
+ * 2026-08-30). `settingsKey` navigates unconditionally, and that is wrong for an
+ * app whose settings are sometimes a DRAWER: on kol-fxr's `/editor`, `,` opens
+ * the panel in place and must not leave the canvas. Its rule is "open whatever
+ * settings is available", which only the app can know.
+ *
+ * So the shell keeps what is genuinely shared — the return path, and the rail
+ * row toggling — and hands out the toggle for a consumer that owns the gesture.
+ * Without this, fxr had to keep its whole local copy (a `lastPage` ref and a
+ * branch in `onNavigate`) to keep one line of app-specific routing, which is
+ * the duplication `settingsPath` exists to end.
+ *
+ * No-op when `settingsPath` is unset, and safe outside an AppShell — a hook
+ * that throws on a missing provider would make it unusable in exactly the
+ * conditional places it is for. */
+export const SettingsToggleContext = createContext(null)
+export const useSettingsToggle = () => useContext(SettingsToggleContext) ?? (() => {})