@kolkrabbi/kol-shell 0.62.0 → 0.64.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-shell",
-  "version": "0.62.0",
+  "version": "0.64.0",
   "private": false,
   "description": "The application shell",
   "license": "MIT",
@@ -12,7 +12,7 @@
     "./src/*": "./src/*"
   },
   "peerDependencies": {
-    "@kolkrabbi/kol-component": ">=0.229.0",
+    "@kolkrabbi/kol-component": ">=0.246.0",
     "@kolkrabbi/kol-icons": ">=0.16.0",
     "@kolkrabbi/kol-theme": ">=0.165.0",
     "gsap": "^3.13.0",
@@ -20,10 +20,10 @@
     "react-dom": "^18.3.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-component": "^0.240.0",
-    "@kolkrabbi/kol-icons": "^0.33.1",
-    "@kolkrabbi/kol-theme": "^0.166.0",
-    "@kolkrabbi/kol-framework": "^0.49.0"
+    "@kolkrabbi/kol-framework": "^0.49.0",
+    "@kolkrabbi/kol-theme": "^0.174.0",
+    "@kolkrabbi/kol-icons": "^0.38.0",
+    "@kolkrabbi/kol-component": "^0.261.0"
   },
   "files": [
     "src",

package/src/AppStudio.jsx

@@ -28,8 +28,12 @@ import PageShell from './PageShell.jsx'
  *
  * @param {Object} app          AppHub's `{ name, subtitle, logomark, about, links }`
  * @param {Object} home         HubHome's props — the landing Catalog (required: a Studio opens on Home)
- * @param {Object} [library]    CatalogPage's props, plus `{ path, label, icon }`
- * @param {Object} [create]     `{ header (PageHeader props), children, path, label, icon }`
+ * @param {Object} [library]    CatalogPage's props — or `children` (a router, for pages under the
+ *                              slot: `/library/:id`), which renders in place of the CatalogPage —
+ *                              plus `{ path, label, icon }`
+ * @param {Object} [create]     `{ header (PageHeader props), children, path, label, icon }`;
+ *                              `shell: false` renders `children` bare — for a Create that owns its
+ *                              PageShell (a fixed canvas beside a scrolling list)
  * @param {Object} [use]        `{ children, path, label, icon }` — the tool
  * @param {Array}  [pages]      `[{ path, icon, label, children }]` — opt-in pages, after Use
  * @param {Object} [settings]   HubSettings' props
@@ -63,10 +67,10 @@ export default function AppStudio({
 
   let page = null
   if (lib && at(lib.path)) {
-    const { path: _p, label: _l, icon: _i, ...props } = lib
-    page = <CatalogPage {...props} />
+    const { path: _p, label: _l, icon: _i, children, ...props } = lib
+    page = children ?? <CatalogPage {...props} />
   } else if (make && at(make.path)) {
-    page = (
+    page = make.shell === false ? make.children : (
       <PageShell>
         {make.header && <PageHeader size="sm" {...make.header} />}
         {make.children}

package/src/NavRail.jsx

@@ -9,6 +9,7 @@ import { GRAB } from '@kolkrabbi/kol-component/utilities/motion'
 import { useGrabEdge } from '@kolkrabbi/kol-component'
 import { Icon } from '@kolkrabbi/kol-icons'
 import Logomark from './Logomark.jsx'
+import { useRailSlot } from './railSlot.jsx'
 
 /**
  * NavRail — the flat rail. ONE fixed column, every child a direct child of it
@@ -70,6 +71,11 @@ import Logomark from './Logomark.jsx'
  * @param {boolean} drawer  off-canvas mode: no grab, no drag, no token writes, rows always
  *   labelled, and the rail sizes itself from `--kol-shell-drawer-width` (default 240px).
  *   AppShell sets this from `touch="drawer"` — see ShellRailNoDrawerOnMobile, 2026-08-31.
+ * Under a `RailSlotProvider` the opened width also carries a CONSUMER SLOT below the rows
+ * (NavRailConsumerSlot, kol-monitor 2026-10-15) — content that is not a row list (monitor's module
+ * catalog: rows that insert, not paths). Always mounted so portalled content keeps its state across
+ * open/close; zero tall and clipped while closed. No provider → no slot, the render unchanged.
+ *
  * @param {boolean} [fade=true]  the list fades out at its foot — the workshop rail's fade
  *   (2026-10-01), here too on the user's word (2026-10-02). The rows sit in their own scroll
  *   region between the mark and the pinned bottom rows, so a list longer than the window scrolls
@@ -299,6 +305,13 @@ export default function NavRail({
    * ten rows each, which is where an accordion stops reading. */
   const [entered, setEntered] = useState(null)
   const snapOpenRef = useRef(null)
+  const slotRef = useRef(null)
+  const ctx = useRailSlot()
+  const setSlot = ctx?.setSlot
+  const setCtxOpen = ctx?.setRailOpen
+  const slotOpen = drawer || railOpen
+  useEffect(() => { setSlot?.(slotRef.current); return () => setSlot?.(null) }, [setSlot, hidden])
+  useEffect(() => { setCtxOpen?.(slotOpen) }, [setCtxOpen, slotOpen])
   /* the grab strip is not rendered in drawer mode, so the hook's ref stays null
    * and it no-ops on its own — no second argument needed */
   useGrabEdge(grabRef)
@@ -363,7 +376,7 @@ export default function NavRail({
       {/* THE LIST IS ITS OWN REGION (2026-10-02): it takes the room between the mark and the pinned
         * bottom rows — what the bare spacer used to hold — scrolls when the rows outrun the window,
         * and fades at its foot unless `fade={false}`. Same column, same gap, as the rail's own. */}
-      <div className={`kol-shell-rail-list flex min-h-0 w-full flex-1 flex-col items-start gap-2 overflow-y-auto overflow-x-hidden ${fade ? 'kol-shell-rail-list--fade' : ''}`.trim()}>
+      <div style={ctx && slotOpen ? { flex: '0 1 auto' } : undefined} className={`kol-shell-rail-list flex min-h-0 w-full flex-1 flex-col items-start gap-2 overflow-y-auto overflow-x-hidden ${fade ? 'kol-shell-rail-list--fade' : ''}`.trim()}>
         {section ? (
           <>
             <RailItem icon="arrow-left" path={section.path} label={section.label} currentPath="" onNavigate={() => setEntered(null)} iconComponent={iconComponent} railOpen={drawer || railOpen} />
@@ -371,6 +384,13 @@ export default function NavRail({
           </>
         ) : items.map(row)}
       </div>
+      {ctx && (
+        <div
+          ref={slotRef}
+          className="kol-shell-rail-slot w-full min-h-0 overflow-x-hidden"
+          style={{ flex: slotOpen ? '1 1 auto' : '0 0 0px', overflowY: slotOpen ? 'auto' : 'hidden' }}
+        />
+      )}
       {/* the rule runs the full rail width, out past the px-2 */}
       {bottomItems.length > 0 && <div className="self-stretch -mx-2 border-t border-fg-08" />}
       {bottomItems.map(row)}

package/src/WalkthroughPanel.jsx

@@ -1,5 +1,5 @@
-import { useState } from 'react'
-import { Button } from '@kolkrabbi/kol-component'
+import { useEffect, useRef, useState } from 'react'
+import { Button, pushLayer, popLayer, isTopLayer } from '@kolkrabbi/kol-component'
 
 /**
  * WalkthroughPanel — A stepped intro card. the absolutely-centred stepped intro card (both repos'
@@ -13,10 +13,29 @@ import { Button } from '@kolkrabbi/kol-component'
  * `onClose` draws an X INSIDE the card, top-right (user, 2026-09-26, on media-hub:
  * the panel had no close of its own, so every app put one outside the card or on a
  * page button). Unset = no X, exactly as before.
+ *
+ * KEYS (kol-fxr 2026-10-09, HubWalkthroughEscape): Escape calls `onClose`, ← → page. The panel
+ * joins the DS overlay layer stack, so a sheet opened above it takes the Escape first, and keys
+ * typed into a field are left alone.
  */
 export default function WalkthroughPanel({ steps = [], iconComponent, onClose }) {
   const [step, setStep] = useState(0)
   const current = steps[step]
+  const live = useRef()
+  live.current = { onClose, last: steps.length - 1 }
+  useEffect(() => {
+    const layer = pushLayer()
+    const onKey = (e) => {
+      if (!isTopLayer(layer) || e.metaKey || e.ctrlKey || e.altKey) return
+      const el = e.target
+      if (el?.isContentEditable || /^(INPUT|TEXTAREA|SELECT)$/.test(el?.tagName ?? '')) return
+      if (e.key === 'Escape' && live.current.onClose) { e.preventDefault(); live.current.onClose() }
+      else if (e.key === 'ArrowLeft') { e.preventDefault(); setStep((s) => Math.max(0, s - 1)) }
+      else if (e.key === 'ArrowRight') { e.preventDefault(); setStep((s) => Math.min(live.current.last, s + 1)) }
+    }
+    document.addEventListener('keydown', onKey)
+    return () => { document.removeEventListener('keydown', onKey); popLayer(layer) }
+  }, [])
   if (!current) return null
 
   return (

package/src/index.js

@@ -39,3 +39,5 @@ export { default as HubHome } from './HubHome.jsx'
 export { default as HubSettings } from './HubSettings.jsx'
 // the Studio — the Hub + Home · Library · Create · Use · pages · Settings, the workstation (apps review §6c, 2026-09-29)
 export { default as AppStudio } from './AppStudio.jsx'
+// a consumer slot in the opened rail — the page portals into it (NavRailConsumerSlot, kol-monitor 2026-10-15)
+export { RailSlotProvider, useRailSlot } from './railSlot.jsx'

package/src/railSlot.jsx

@@ -0,0 +1,28 @@
+import { createContext, useContext, useMemo, useState } from 'react'
+
+/**
+ * RailSlotProvider / useRailSlot — a consumer slot in NavRail's opened width (NavRailConsumerSlot,
+ * kol-monitor 2026-10-15). The rail renders in AppShell's own tree, outside the page's providers,
+ * so it cannot read page state and the page cannot render into it. The rail publishes its slot's
+ * DOM node here instead, and the page portals into it with its own state:
+ *
+ *   <RailSlotProvider><AppStudio … /></RailSlotProvider>
+ *   const rail = useRailSlot(); rail?.slot && createPortal(<Panel />, rail.slot)
+ *
+ * The provider goes ABOVE the shell so the rail and the page both see it. No provider → no slot,
+ * and the rail renders as it did. `railOpen` mirrors the rail's open state for the page.
+ *
+ * Monitor's shape (`src/hooks/useRailSlot.jsx`), shipped so its NavRail fork can retire.
+ */
+const RailSlotContext = createContext(null)
+
+export function useRailSlot() {
+  return useContext(RailSlotContext)
+}
+
+export function RailSlotProvider({ children }) {
+  const [slot, setSlot] = useState(null)
+  const [railOpen, setRailOpen] = useState(false)
+  const value = useMemo(() => ({ slot, setSlot, railOpen, setRailOpen }), [slot, railOpen])
+  return <RailSlotContext.Provider value={value}>{children}</RailSlotContext.Provider>
+}