@kolkrabbi/kol-shell 0.1.0

package/README.md

@@ -0,0 +1,98 @@
+# @kolkrabbi/kol-shell
+
+The KOL **application shell** — the fixed 48px NavRail, the AppShell layout
+root, and the page scaffolds an app is built from. Lifted 2026-08-14 from the
+hand-copied twins in kol-monitor ("Monitor") and kol-mirror ("Hall of
+Mirrors").
+
+**App chrome, not site chrome.** kol-framework owns the site register (SideNav
+with a two-level navTree, footer, heroes); this rail is deliberately flat
+`{ icon, path, label }`. They are different components, not variants.
+
+## Requirements
+
+Same consumer contract as every KOL package — raw `.jsx` source, so:
+
+- **Vite + Tailwind v4** consumer
+- `@source "../node_modules/@kolkrabbi/kol-shell/src"` in your CSS (Tailwind
+  skips `node_modules`; see the kol-theme README for the full `@source` contract)
+- CSS cascade: `tailwindcss` → `@kolkrabbi/kol-theme` → brand color → framework
+  CSS `layer(components)` — the shell's chrome (`kol-components-shell.css`)
+  ships inside kol-theme ≥0.41.0
+- Peers: `@kolkrabbi/kol-{theme,component,framework,icons}` + React
+
+## Pieces
+
+| Piece | What it is |
+|---|---|
+| `AppShell` | Layout root — rail + content offset by `--kol-shell-rail-width`. Router-agnostic: children + `currentPath`/`onNavigate` |
+| `NavRail` / `useNavHidden` | The fixed rail — logomark top, items, spacer, ThemeToggle, bottom items. Full-bleed routes flip `useNavHidden` |
+| `PageShell` / `PageBleed` | Page scaffold — `mode="scroll"` or `"fixed"`; gutter `--kol-shell-page-pad`, `PageBleed` breaks it |
+| `PageHeader` | Title + mono subtitle as values (kills the tab-driven inline fork) |
+| `ContentFilters` | The catalog organism — chips, expanding pill search, view/layout strips, render-prop |
+| `TabStrip` | The flat text-tab idiom (view modes, settings tabs) |
+| `GridCard` | A4 card + `list` row + monitor's `expanded` 2×2; preview fits via `.kol-shell-card-preview--*` |
+| `SettingsScaffold` / `SettingsSection` / `LabelRow` | The settings idiom — tabs feed the header; 160px label rows |
+| `WalkthroughPanel` | Centred stepped intro card; steps/illustrations/actions are content |
+| `ShortcutsOverlay` | Blurred scrim + flat 2-col shortcut sheet at `--kol-z-modal` |
+| `Logomark` | Fetch-and-inline SVG mark (currentColor-safe in dark mode) |
+
+## Wiring (react-router example)
+
+```jsx
+import { AppShell } from '@kolkrabbi/kol-shell'
+import { Outlet, useLocation, useNavigate } from 'react-router-dom'
+import Icon from './icons/Icon'   // your registry, via the iconComponent seam
+
+const NAV = [
+  { icon: 'nav-library', path: '/library', label: 'Library' },
+]
+const BOTTOM = [{ icon: 'nav-settings', path: '/settings', label: 'Settings' }]
+
+export default function Layout() {
+  const { pathname } = useLocation()
+  const navigate = useNavigate()
+  return (
+    <AppShell
+      items={NAV} bottomItems={BOTTOM}
+      logomark={{ svgUrl: '/svg/favicon-01.svg', title: 'Monitor' }}
+      currentPath={pathname} onNavigate={navigate}
+      iconComponent={Icon}
+    >
+      <Outlet />
+    </AppShell>
+  )
+}
+```
+
+## Laws carried natively
+
+- **Rail active state (user ruling 2026-08-12):** ink `--kol-oq-96` in every
+  state; hover = the `--kol-oq-04` wash; active route = that wash **held on**,
+  keyed off `aria-current="page"`. Never `selected`/`pressed`. Both source
+  repos' overrides die on adoption.
+- **Rail stacking:** `--kol-z-sticky` — above content, below overlay/modal
+  (monitor's raw `z-70` rail sat above its own `z-50` overlays).
+- **No auto-casing:** the source repos' `text-transform: uppercase` strips are
+  dropped — author labels in the case they should render.
+- **Grid geometry (documented default):** catalog grid = `repeat(6, 1fr)`
+  gap 24 · list = `repeat(4, 1fr)` gap 8.
+- **Shortcuts single-source:** feed ONE array to both `ShortcutsOverlay` and
+  the settings page's `LabelRow` map — the twice-maintained lists drifted in
+  both source repos.
+
+## Theme boot
+
+Re-stamp the theme before first paint (both repos' `main.jsx`, the canonical
+snippet — a helper would be four lines of ceremony):
+
+```js
+import { applyTheme, getInitialTheme } from '@kolkrabbi/kol-framework'
+applyTheme(getInitialTheme())
+```
+
+## Stays per-app
+
+Domain surfaces (rack, studio, detail pages), accent bindings, product names,
+logomark files, nav arrays, walkthrough/shortcut/settings **content**,
+touch-device gates.

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@kolkrabbi/kol-shell",
+  "version": "0.1.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",
+  "type": "module",
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./src/*": "./src/*"
+  },
+  "peerDependencies": {
+    "@kolkrabbi/kol-component": ">=0.38.0",
+    "@kolkrabbi/kol-framework": ">=0.20.0",
+    "@kolkrabbi/kol-icons": ">=0.16.0",
+    "@kolkrabbi/kol-theme": ">=0.41.0",
+    "react": "^18.3.0 || ^19.0.0",
+    "react-dom": "^18.3.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@kolkrabbi/kol-component": "^0.38.0",
+    "@kolkrabbi/kol-icons": "^0.16.0",
+    "@kolkrabbi/kol-framework": "^0.20.0",
+    "@kolkrabbi/kol-theme": "^0.41.0"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "keywords": [
+    "kol",
+    "kolkrabbi",
+    "design-system",
+    "shell",
+    "app-shell",
+    "nav-rail",
+    "layout"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Tor-Grimsson/kol-ds.git",
+    "directory": "packages/shell"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/AppShell.jsx

@@ -0,0 +1,52 @@
+import { useState } from 'react'
+import NavRail from './NavRail.jsx'
+import { NavHiddenContext } from './navHidden.js'
+
+/**
+ * AppShell — layout root: fixed NavRail + content offset by the rail width.
+ * No header, no footer. Router-agnostic: render your router's element (e.g.
+ * `<Outlet/>`) as children and wire `currentPath`/`onNavigate` from your
+ * router at the call site.
+ *
+ * Rail width is `--kol-shell-rail-width` (kol-theme) — read by both the rail
+ * and the offset so they can never disagree.
+ *
+ * @param {Array}  props.items         nav items `{ icon, path, label }`
+ * @param {Array}  props.bottomItems   items pinned below the theme toggle
+ * @param {Object} props.logomark      `{ svgUrl, title }` — top mark, navigates to '/'
+ * @param {string} props.currentPath   the router's current pathname
+ * @param {Function} props.onNavigate  `(path) => void`
+ * @param {ElementType} props.iconComponent  icon renderer seam (see Button)
+ * @param {boolean} props.themeToggle  render the ThemeToggle above bottomItems (default true)
+ */
+export default function AppShell({
+  items,
+  bottomItems,
+  logomark,
+  currentPath,
+  onNavigate,
+  iconComponent,
+  themeToggle,
+  children,
+}) {
+  const [navHidden, setNavHidden] = useState(false)
+
+  return (
+    <NavHiddenContext.Provider value={{ navHidden, setNavHidden }}>
+      {!navHidden && (
+        <NavRail
+          items={items}
+          bottomItems={bottomItems}
+          logomark={logomark}
+          currentPath={currentPath}
+          onNavigate={onNavigate}
+          iconComponent={iconComponent}
+          themeToggle={themeToggle}
+        />
+      )}
+      <div style={{ marginLeft: navHidden ? 0 : 'var(--kol-shell-rail-width)' }}>
+        {children}
+      </div>
+    </NavHiddenContext.Provider>
+  )
+}

package/src/ContentFilters.jsx

@@ -0,0 +1,274 @@
+import { useState, useMemo, useRef, useEffect } from 'react'
+import { Tag, Divider } from '@kolkrabbi/kol-component'
+import { Icon } from '@kolkrabbi/kol-icons'
+import TabStrip from './TabStrip.jsx'
+
+/**
+ * ContentFilters — the catalog organism: header row (title + count), a
+ * toggled filter-chip panel, the expanding pill search, view-mode/layout
+ * strips (TabStrip), and a render-prop for the filtered items.
+ *
+ * Recreated from the mirror cut (the newer of the two shipped copies) with
+ * the shipped defects fixed: the dead ViewToggle import dropped (both repos
+ * carried it), `text-transform: uppercase` on the strips dropped (no
+ * auto-casing law — author labels in the case they should render; the 1px
+ * tracking stays via TabStrip `tracked`), and mirror's `bg-container-secondary`
+ * hover (a class no theme CSS defines) → `bg-fg-04`.
+ *
+ * Grid geometry law (documented default, both source repos, both pages):
+ * grid = `repeat(6, 1fr)` gap 24 · list = `repeat(4, 1fr)` gap 8.
+ *
+ * @param {Array} props.items - Items to filter
+ * @param {string} props.title - Section title
+ * @param {number} props.totalCount - Count before filtering
+ * @param {Array} props.filterGroups - `[{ label, key, values }]`
+ * @param {Function} props.renderItem - `(filteredItems, viewMode, layout) => node`
+ * @param {Array} props.viewModeOptions - `[{ value, label }]` for the view strip
+ * @param {Array} props.mutuallyExclusiveFilters - filter keys that self-clear
+ * @param {Array} props.customFilterKeys - keys renderItem handles, not this organism
+ * @param {ElementType} props.iconComponent - icon seam (defaults to DS Icon; needs `filter` + `search`)
+ */
+const ContentFilters = ({
+  items,
+  title,
+  totalCount,
+  filterGroups = [],
+  renderItem,
+  viewModeOptions,
+  viewMode: viewModeProp,
+  onViewModeChange,
+  defaultViewMode = 'list',
+  layoutOptions,
+  defaultLayout = 'grid',
+  onFilterChange,
+  mutuallyExclusiveFilters = [],
+  customFilterKeys = [],
+  searchKeys = ['label', 'name', 'title', 'type'],
+  headerActions,
+  showCountOnlyWhenFiltering = false,
+  iconComponent,
+}) => {
+  const [activeFilters, setActiveFilters] = useState(new Set())
+  const [isExpanded, setIsExpanded] = useState(false)
+  const [internalViewMode, setInternalViewMode] = useState(defaultViewMode)
+  const viewMode = viewModeProp !== undefined ? viewModeProp : internalViewMode
+  const [layout, setLayout] = useState(defaultLayout)
+  const [searchOpen, setSearchOpen] = useState(false)
+  const [searchText, setSearchText] = useState('')
+  const searchRef = useRef(null)
+  const IconSeam = iconComponent || Icon
+
+  useEffect(() => {
+    if (searchOpen && searchRef.current) searchRef.current.focus()
+  }, [searchOpen])
+
+  const toggleFilter = (filterType, value) => {
+    const newFilters = new Set(activeFilters)
+    const filterKey = `${filterType}:${value}`
+
+    if (newFilters.has(filterKey)) {
+      newFilters.delete(filterKey)
+    } else {
+      if (mutuallyExclusiveFilters.includes(filterType)) {
+        Array.from(newFilters).forEach(existingFilter => {
+          if (existingFilter.startsWith(`${filterType}:`)) {
+            newFilters.delete(existingFilter)
+          }
+        })
+      }
+      newFilters.add(filterKey)
+    }
+
+    setActiveFilters(newFilters)
+    if (onFilterChange) {
+      onFilterChange(newFilters, viewMode)
+    }
+  }
+
+  const clearAllFilters = () => {
+    setActiveFilters(new Set())
+    if (onFilterChange) {
+      onFilterChange(new Set(), viewMode)
+    }
+  }
+
+  const handleViewModeChange = (mode) => {
+    if (onViewModeChange) onViewModeChange(mode)
+    else setInternalViewMode(mode)
+    if (onFilterChange) {
+      onFilterChange(activeFilters, mode)
+    }
+  }
+
+  const filteredItems = useMemo(() => {
+    let result = items
+
+    if (searchText) {
+      const q = searchText.toLowerCase()
+      result = result.filter(item =>
+        searchKeys.some(key => {
+          const val = item[key]
+          return val && String(val).toLowerCase().includes(q)
+        })
+      )
+    }
+
+    if (activeFilters.size === 0) return result
+
+    return result.filter((item) => {
+      let matches = true
+      activeFilters.forEach((filter) => {
+        const [filterType, value] = filter.split(':')
+        if (customFilterKeys.includes(filterType)) return
+
+        const itemValue = item[filterType]
+        if (Array.isArray(itemValue)) {
+          if (!itemValue.includes(value)) matches = false
+        } else {
+          if (itemValue !== value) matches = false
+        }
+      })
+      return matches
+    })
+  }, [items, activeFilters, customFilterKeys, searchText, searchKeys])
+
+  const renderFilterGroup = (group) => (
+    <div key={group.key}>
+      <h4 className="kol-helper-12 text-fg-48">{group.label}</h4>
+      <div className="flex flex-wrap gap-2 pt-3">
+        {group.values.map((value) => {
+          const filterKey = `${group.key}:${value}`
+          const isActive = activeFilters.has(filterKey)
+
+          return (
+            <div key={value} onClick={() => toggleFilter(group.key, value)}>
+              <Tag
+                size="md"
+                variant="default"
+                className={isActive ? 'border-fg-32' : 'border-fg-08'}
+              >
+                {value}
+              </Tag>
+            </div>
+          )
+        })}
+      </div>
+    </div>
+  )
+
+  return (
+    <div className="w-full" style={{ display: 'flex', flexDirection: 'column', flex: 1 }}>
+      {/* Header with filter toggle + expanding search */}
+      <div className="flex items-center justify-between mb-4">
+        <div className="flex items-center gap-6">
+          <h2 className="kol-helper-14">{title}</h2>
+          <div className="flex items-center gap-1">
+            <button
+              onClick={() => setIsExpanded(!isExpanded)}
+              className="p-2 hover:bg-fg-04 rounded-sm transition-colors leading-none"
+              aria-label="Toggle filters"
+            >
+              <IconSeam name="filter" size={16} />
+            </button>
+            <div
+              className="flex items-center rounded-full cursor-pointer"
+              style={{
+                height: 28,
+                width: searchOpen ? 200 : 28,
+                background: searchOpen ? 'var(--kol-fg-04, rgba(255,255,255,0.04))' : 'transparent',
+                transition: 'width 600ms cubic-bezier(0.16, 1, 0.3, 1), background 400ms cubic-bezier(0.16, 1, 0.3, 1)',
+                overflow: 'hidden',
+              }}
+              onClick={() => {
+                if (searchOpen) { setSearchOpen(false); setSearchText('') }
+                else setSearchOpen(true)
+              }}
+            >
+              <span
+                className="flex items-center justify-center flex-shrink-0"
+                style={{
+                  width: 28, height: 28,
+                  opacity: searchOpen ? 0 : 1,
+                  transition: 'opacity 300ms cubic-bezier(0.16, 1, 0.3, 1)',
+                  position: searchOpen ? 'absolute' : 'relative',
+                }}
+              >
+                <IconSeam name="search" size={16} />
+              </span>
+              {searchOpen && (
+                <input
+                  ref={searchRef}
+                  type="text"
+                  value={searchText}
+                  onChange={e => setSearchText(e.target.value)}
+                  onClick={e => e.stopPropagation()}
+                  placeholder=""
+                  className="bg-transparent outline-none kol-helper-12 flex-1 text-fg-80 caret-current px-4"
+                  onBlur={() => { if (!searchText) { setSearchOpen(false) } }}
+                  onKeyDown={e => { if (e.key === 'Escape') { setSearchOpen(false); setSearchText('') } }}
+                />
+              )}
+            </div>
+            {headerActions}
+          </div>
+          {activeFilters.size > 0 && (
+            <span
+              className="kol-helper-12 text-fg-48 cursor-pointer select-none group flex items-center gap-2"
+              onClick={(e) => { e.stopPropagation(); clearAllFilters() }}
+            >
+              <span className="underline">({activeFilters.size}) {activeFilters.size === 1 ? 'filter' : 'filters'} active</span>
+              <span className="hidden group-hover:inline text-fg-64">×</span>
+            </span>
+          )}
+        </div>
+
+        <div className="flex items-center gap-8">
+          {(!showCountOnlyWhenFiltering || isExpanded || searchOpen || activeFilters.size > 0) && (
+            <span className="kol-helper-14 text-fg-64">
+              {filteredItems.length} of {totalCount}
+            </span>
+          )}
+          {viewModeOptions && (
+            <TabStrip options={viewModeOptions} value={viewMode} onChange={handleViewModeChange} tracked />
+          )}
+        </div>
+      </div>
+
+      <Divider className="mb-4" />
+
+      {isExpanded && (
+        <div className="flex items-start gap-16">
+          {filterGroups.map((group) => renderFilterGroup(group))}
+          {activeFilters.size > 0 && (
+            <button
+              onClick={clearAllFilters}
+              className="kol-helper-12 transition-colors underline text-fg-48"
+              style={{ marginLeft: 'auto' }}
+            >
+              Clear all ({activeFilters.size})
+            </button>
+          )}
+        </div>
+      )}
+
+      {/* Layout toggle */}
+      {layoutOptions && (
+        <TabStrip
+          options={layoutOptions}
+          value={layout}
+          onChange={setLayout}
+          size={12}
+          tracked
+          className="justify-end gap-4 mt-4"
+        />
+      )}
+
+      {/* Render filtered items */}
+      <div className="mt-8" style={{ display: 'flex', flexDirection: 'column', flex: 1 }}>
+        {renderItem(filteredItems, viewMode, layout)}
+      </div>
+    </div>
+  )
+}
+
+export default ContentFilters

package/src/GridCard.jsx

@@ -0,0 +1,69 @@
+/**
+ * GridCard — A4-ratio card for catalog grids (monitor's full cut: expanded
+ * 2×2 mode + previewFit). Preview clipped on top, label plate at bottom;
+ * `variant="list"` renders the compact 36px row.
+ *
+ * Recreated from both repos with the shipped divergences fixed:
+ * - the label plate's hardcoded `borderTop: rgba(255,255,255,0.06)` (a live
+ *   light-theme bug in both apps) → `border-t border-fg-04`
+ * - monitor's `textTransform: capitalize` on the list detail dropped (no
+ *   auto-casing law — author the string in the case it should render)
+ *
+ * Preview fits: `.kol-shell-card-preview--{natural|compact|cover}` in
+ * kol-theme. Grid geometry law (documented default, both source repos):
+ * grid = `repeat(6, 1fr)` gap 24 · list = `repeat(4, 1fr)` gap 8.
+ * Neighbour-hiding for `expanded` stays consumer-side.
+ */
+export default function GridCard({ title, detail, preview, expanded, expandedContent, onClick, variant, action, previewFit = 'natural' }) {
+  if (variant === 'list') {
+    return (
+      <div
+        onClick={onClick}
+        className="flex items-center justify-between px-3 cursor-pointer bg-surface-tertiary hover:bg-fg-04 rounded border border-fg-04 transition-colors select-none"
+        style={{ height: 36 }}
+      >
+        <span className="kol-helper-12 text-fg-64">{title}</span>
+        {action || (detail && <span className="kol-helper-10 text-fg-32">{detail}</span>)}
+      </div>
+    )
+  }
+
+  return (
+    <div
+      onClick={onClick}
+      className="bg-fg-04 hover:bg-surface-tertiary border border-fg-04"
+      style={{
+        borderRadius: 4, cursor: 'pointer',
+        aspectRatio: expanded ? undefined : '1 / 1.41421',
+        gridColumn: expanded ? 'span 2' : 'span 1',
+        gridRow: expanded ? 'span 2' : 'span 1',
+        position: 'relative', overflow: 'hidden',
+        display: 'flex', flexDirection: expanded ? 'row-reverse' : 'column',
+        transition: 'all 300ms cubic-bezier(0.16, 1, 0.3, 1)',
+      }}
+    >
+      <div style={{
+        overflow: 'hidden',
+        position: 'relative',
+        flex: expanded ? '0 0 50%' : 1,
+        minHeight: 0,
+        minWidth: 0,
+      }}>
+        <div className={`kol-shell-card-preview kol-shell-card-preview--${previewFit}`} style={{ position: 'absolute', top: 0, left: 0, width: '100%', height: '100%' }}>
+          {preview}
+        </div>
+      </div>
+
+      {expanded ? (
+        <div style={{ flex: 1, padding: 24, display: 'flex', flexDirection: 'column', justifyContent: 'space-between', overflow: 'auto' }}>
+          {expandedContent}
+        </div>
+      ) : (
+        <div className="bg-surface-primary border-t border-fg-04" style={{ padding: '12px 16px', width: '100%' }}>
+          <div className="text-fg-96 kol-helper-14" style={{ marginBottom: 4 }}>{title}</div>
+          {detail && <div className="text-fg-32 kol-helper-8">{detail}</div>}
+        </div>
+      )}
+    </div>
+  )
+}

package/src/Logomark.jsx

@@ -0,0 +1,38 @@
+import { useState, useEffect } from 'react'
+
+/**
+ * Logomark — fetches and INLINES an SVG so currentColor theming works: an
+ * <img> renders a currentColor mark black in dark mode (invisible). Ported
+ * verbatim from the kol-mirror cut (module-level cache; async resolve even on
+ * cache hit — sync setState in an effect cascades renders).
+ */
+
+const svgCache = new Map()
+
+export default function Logomark({ svgUrl, size = 20, className = '', ...props }) {
+  const [svgContent, setSvgContent] = useState(() => svgCache.get(svgUrl) || null)
+
+  useEffect(() => {
+    if (!svgUrl) return
+    let active = true
+    Promise.resolve(
+      svgCache.get(svgUrl) ?? fetch(svgUrl).then(res => res.text()).then(svg => { svgCache.set(svgUrl, svg); return svg })
+    )
+      .then(svg => { if (active) setSvgContent(svg) })
+      .catch(() => {})
+    return () => { active = false }
+  }, [svgUrl])
+
+  if (!svgContent) return <span style={{ width: size, height: size, display: 'inline-block' }} />
+
+  return (
+    <span
+      className={className}
+      style={{ width: size, height: size, display: 'inline-flex', color: 'currentColor' }}
+      dangerouslySetInnerHTML={{
+        __html: svgContent.replace('<svg', `<svg width="${size}" height="${size}"`),
+      }}
+      {...props}
+    />
+  )
+}

package/src/NavRail.jsx

@@ -0,0 +1,82 @@
+import { Button } from '@kolkrabbi/kol-component'
+import { ThemeToggle } from '@kolkrabbi/kol-framework'
+import Logomark from './Logomark.jsx'
+
+/**
+ * NavRail — the fixed 48px icon rail. Geometry/stacking live in kol-theme's
+ * `.kol-shell-rail`; surface/border ride the theme utility classes.
+ *
+ * Items are flat `{ icon, path, label }` — deliberately NOT kol-framework
+ * SideNav's two-level navTree; different component, not a variant.
+ *
+ * Active state (user ruling 2026-08-12, carried natively in kol-theme):
+ * ink `--kol-oq-96` in every state, hover = the `--kol-oq-04` wash, active
+ * route = that wash held on via `aria-current="page"` — never
+ * `selected`/`pressed`; navigation is location, not a toggled tool.
+ */
+
+function RailItem({ icon, path, label, active, onNavigate, iconComponent }) {
+  return (
+    <Button
+      iconOnly={icon}
+      iconSize={20}
+      variant="nav"
+      size="md"
+      aria-current={active ? 'page' : undefined}
+      onClick={() => onNavigate?.(path)}
+      title={label}
+      iconComponent={iconComponent}
+    />
+  )
+}
+
+export default function NavRail({
+  items = [],
+  bottomItems = [],
+  logomark,
+  currentPath = '',
+  onNavigate,
+  iconComponent,
+  themeToggle = true,
+  hidden = false,
+}) {
+  if (hidden) return null
+  const isActive = (path) =>
+    path === '/' ? currentPath === '/' : currentPath.startsWith(path)
+
+  return (
+    <div className="kol-shell-rail bg-surface-tertiary border-r border-fg-04">
+      {logomark && (
+        <div
+          onClick={() => onNavigate?.('/')}
+          className="text-oq-96"
+          style={{ cursor: 'pointer', marginBottom: 16, paddingTop: 4 }}
+          title={logomark.title}
+        >
+          <Logomark svgUrl={logomark.svgUrl} size={20} />
+        </div>
+      )}
+      {items.map((item) => (
+        <RailItem
+          key={item.path}
+          {...item}
+          active={isActive(item.path)}
+          onNavigate={onNavigate}
+          iconComponent={iconComponent}
+        />
+      ))}
+      <div style={{ flex: 1 }} />
+      {themeToggle && <ThemeToggle label={false} style={{ color: 'var(--kol-oq-96)' }} />}
+      {bottomItems.map((item) => (
+        <RailItem
+          key={item.path}
+          {...item}
+          active={isActive(item.path)}
+          onNavigate={onNavigate}
+          iconComponent={iconComponent}
+        />
+      ))}
+      <div style={{ height: 8 }} />
+    </div>
+  )
+}

package/src/PageHeader.jsx

@@ -0,0 +1,14 @@
+/**
+ * PageHeader — page title + mono subtitle. The mirror cut (subtitle
+ * `kol-mono-14`, the newer voice) wins over monitor's `kol-text-sm`; override
+ * via a wrapper if a consumer needs otherwise. Takes title/subtitle as values
+ * so tab-driven headers (Settings) stop re-implementing the markup inline.
+ */
+export default function PageHeader({ title, subtitle }) {
+  return (
+    <>
+      <h1 className="text-fg-96 kol-heading-sm">{title}</h1>
+      <p className="text-fg-48 kol-mono-14" style={{ marginBottom: 40 }}>{subtitle}</p>
+    </>
+  )
+}

package/src/PageShell.jsx

@@ -0,0 +1,46 @@
+/**
+ * PageShell — the page scaffold every shell page re-declared by hand (6 pages
+ * in monitor, 4 in mirror — the most-duplicated block in both repos).
+ *
+ * `mode="scroll"` (default): min-height 100vh, natural page scroll.
+ * `mode="fixed"`: height 100vh, overflow hidden — pair with a `flex:1
+ * overflow:auto` body (the settings idiom; SettingsScaffold does this).
+ *
+ * Gutter is `--kol-shell-page-pad` (kol-theme). `PageBleed` breaks it for
+ * full-width embeds (monitor's rack bleed).
+ */
+export default function PageShell({ mode = 'scroll', className = '', style, children }) {
+  const modeStyle =
+    mode === 'fixed'
+      ? { height: '100vh', overflow: 'hidden' }
+      : { minHeight: '100vh' }
+  return (
+    <div
+      className={`bg-surface-primary ${className}`.trim()}
+      style={{
+        padding: 'var(--kol-shell-page-pad)',
+        display: 'flex',
+        flexDirection: 'column',
+        ...modeStyle,
+        ...style,
+      }}
+    >
+      {children}
+    </div>
+  )
+}
+
+/** Full-bleed slot — cancels PageShell's horizontal gutter. */
+export function PageBleed({ style, children }) {
+  return (
+    <div
+      style={{
+        marginLeft: 'calc(var(--kol-shell-page-pad) * -1)',
+        marginRight: 'calc(var(--kol-shell-page-pad) * -1)',
+        ...style,
+      }}
+    >
+      {children}
+    </div>
+  )
+}

package/src/SettingsScaffold.jsx

@@ -0,0 +1,71 @@
+import { useState } from 'react'
+import { Divider } from '@kolkrabbi/kol-component'
+import PageShell from './PageShell.jsx'
+import PageHeader from './PageHeader.jsx'
+import TabStrip from './TabStrip.jsx'
+
+/**
+ * SettingsScaffold — the settings-page idiom both shells re-implemented
+ * inline: fixed PageShell, tab-driven PageHeader, TabStrip, Divider, then a
+ * `flex:1 overflow:auto` body. Content is consumer-authored via
+ * `renderContent(tabValue)` — sections/rows are content, not markup.
+ *
+ * Building blocks exported for the body: `SettingsSection` (h2 + column) and
+ * `LabelRow` (the 160px label-column row — the de-facto standard both repos
+ * and monitor's ColorPickerPage share).
+ *
+ * Shortcuts single-source: both repos hand-maintained the shortcut list twice
+ * (settings + overlay) and both pairs drifted. Feed ONE array to both your
+ * `ShortcutsOverlay` and a `LabelRow` map here.
+ *
+ * @param {Array} props.tabs - `[{ value, label, title, subtitle }]` — title/subtitle feed the header
+ * @param {Function} props.renderContent - `(tabValue) => node`
+ */
+export default function SettingsScaffold({ tabs = [], defaultTab, renderContent }) {
+  const [tab, setTab] = useState(defaultTab ?? tabs[0]?.value)
+  const active = tabs.find((t) => t.value === tab)
+
+  return (
+    <PageShell mode="fixed">
+      <PageHeader title={active?.title} subtitle={active?.subtitle} />
+      <TabStrip
+        options={tabs}
+        value={tab}
+        onChange={setTab}
+        className="gap-6"
+        style={{ marginBottom: 24 }}
+      />
+      <Divider className="mb-6" />
+      <div style={{ flex: 1, overflow: 'auto', paddingTop: 4, paddingBottom: 4 }}>
+        {renderContent?.(tab)}
+      </div>
+    </PageShell>
+  )
+}
+
+/** Section — `h2` header + 8px column, the body block both repos share. */
+export function SettingsSection({ title, children }) {
+  return (
+    <div>
+      <h2 className="text-fg-80 kol-helper-16" style={{ marginBottom: 16 }}>{title}</h2>
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
+        {children}
+      </div>
+    </div>
+  )
+}
+
+/**
+ * LabelRow — 160px flex-shrink-0 label column + value. `align="center"` for
+ * control rows (a toggle), `align="baseline"` (default) for text rows.
+ */
+export function LabelRow({ label, align = 'baseline', children }) {
+  return (
+    <div style={{ display: 'flex', gap: 12, alignItems: align }}>
+      <span className="text-fg-48 kol-helper-12" style={{ width: 160, flexShrink: 0 }}>{label}</span>
+      {typeof children === 'string'
+        ? <span className="text-fg-32 kol-helper-12">{children}</span>
+        : children}
+    </div>
+  )
+}

package/src/ShortcutsOverlay.jsx

@@ -0,0 +1,36 @@
+import { useEffect } from 'react'
+
+/**
+ * ShortcutsOverlay — the keyboard-shortcut sheet: blurred scrim, centred
+ * panel, one flat 2-col grid (label · keys), Esc / backdrop-click close.
+ * Ported from the shared cut (mirror's, "copied from kol-monitor").
+ *
+ * `shortcuts` is a prop — feed the SAME array your settings page renders
+ * (both repos hand-maintained the list twice and both pairs drifted).
+ * Stacks at `--kol-z-modal`, above the rail's sticky tier.
+ *
+ * @param {Array} props.shortcuts - `[{ label, keys }]`
+ */
+export default function ShortcutsOverlay({ shortcuts = [], onClose }) {
+  useEffect(() => {
+    const onKey = (e) => { if (e.key === 'Escape') onClose?.() }
+    window.addEventListener('keydown', onKey)
+    return () => window.removeEventListener('keydown', onKey)
+  }, [onClose])
+
+  return (
+    <div
+      onClick={onClose}
+      className="fixed inset-0 select-none bg-fg-inverse-08"
+      style={{ display: 'grid', placeItems: 'center', backdropFilter: 'blur(2px)', zIndex: 'var(--kol-z-modal)' }}
+    >
+      <div className="text-fg-64 kol-helper-12 bg-surface-primary border border-fg-16" style={{ display: 'grid', gridTemplateColumns: 'auto auto', gap: '10px 62px', padding: 24, borderRadius: 4 }}>
+        {shortcuts.map(({ label, keys }) => (
+          <span key={label} className="contents">
+            <span>{label}</span><span className="text-fg-96">{keys}</span>
+          </span>
+        ))}
+      </div>
+    </div>
+  )
+}

package/src/TabStrip.jsx

@@ -0,0 +1,28 @@
+/**
+ * TabStrip — the flat text-tab idiom both shells use twice (ContentFilters
+ * view-mode/layout spans, Settings tabs): `kol-helper-14`, active
+ * `text-fg-96`, rest `text-fg-32 hover:text-fg-48`.
+ *
+ * No auto-casing — labels render exactly as authored (the source repos'
+ * `text-transform: uppercase` dropped per the DS law; author "GRID" if you
+ * want GRID). `tracked` adds the 1px letter-spacing the view-mode strips
+ * carried.
+ *
+ * @param {Array} props.options  `[{ value, label }]`
+ */
+export default function TabStrip({ options = [], value, onChange, size = 14, tracked = false, className = 'gap-6', style }) {
+  return (
+    <div className={`flex items-center ${className}`.trim()} style={style}>
+      {options.map((opt) => (
+        <span
+          key={opt.value}
+          onClick={() => onChange?.(opt.value)}
+          className={`kol-helper-${size} cursor-pointer select-none ${value === opt.value ? 'text-fg-96' : 'text-fg-32 hover:text-fg-48'}`}
+          style={tracked ? { letterSpacing: 1 } : undefined}
+        >
+          {opt.label}
+        </span>
+      ))}
+    </div>
+  )
+}

package/src/WalkthroughPanel.jsx

@@ -0,0 +1,74 @@
+import { useState } from 'react'
+import { Button } from '@kolkrabbi/kol-component'
+
+/**
+ * WalkthroughPanel — the absolutely-centred stepped intro card (both repos'
+ * HomePage): chevron Buttons either side, text column + illustration pane.
+ *
+ * Steps are content: `[{ title, text: [..], illustration?, actions? }]` —
+ * `illustration` is a render slot (monitor globs SVGs, mirror uses a JPEG),
+ * a step with `actions` renders that node centred instead of the text/image
+ * split (the "Get started" step).
+ */
+export default function WalkthroughPanel({ steps = [], iconComponent }) {
+  const [step, setStep] = useState(0)
+  const current = steps[step]
+  if (!current) return null
+
+  return (
+    <div style={{
+      position: 'absolute', top: '50%', left: '50%',
+      transform: 'translate(-50%, -50%)',
+      display: 'flex', alignItems: 'center', gap: 16,
+      maxWidth: 960, width: '100%', zIndex: 10,
+    }}>
+      <Button
+        variant="grey"
+        size="md"
+        iconOnly="chevron-left"
+        iconComponent={iconComponent}
+        disabled={step === 0}
+        onClick={() => setStep((s) => Math.max(0, s - 1))}
+        style={{ padding: 8 }}
+      />
+
+      <div
+        className="bg-surface-tertiary border border-fg-08"
+        style={{ flex: 1, display: 'flex', borderRadius: 4, minHeight: 480, overflow: 'hidden' }}
+      >
+        {current.actions ? (
+          <div style={{ flex: 1, display: 'flex', flexDirection: 'column', alignItems: 'center', justifyContent: 'center', gap: 12 }}>
+            {current.actions}
+          </div>
+        ) : (
+          <>
+            <div style={{ flex: 1, padding: '64px 24px 24px', display: 'flex', flexDirection: 'column', justifyContent: 'space-between' }}>
+              <div>
+                <h3 className="text-fg-80 kol-mono-14" style={{ marginBottom: 12 }}>{current.title}</h3>
+                {(current.text || []).map((t, i) => (
+                  <p key={i} className="text-fg-48 kol-helper-12" style={{ lineHeight: 1.8, marginTop: i > 0 ? 12 : 0 }}>{t}</p>
+                ))}
+              </div>
+              <span className="text-fg-48 kol-helper-12">{step + 1} / {steps.length}</span>
+            </div>
+            {current.illustration && (
+              <div style={{ flex: '0 0 50%', overflow: 'hidden' }}>
+                {current.illustration}
+              </div>
+            )}
+          </>
+        )}
+      </div>
+
+      <Button
+        variant="grey"
+        size="md"
+        iconOnly="chevron-right"
+        iconComponent={iconComponent}
+        disabled={step === steps.length - 1}
+        onClick={() => setStep((s) => Math.min(steps.length - 1, s + 1))}
+        style={{ padding: 8 }}
+      />
+    </div>
+  )
+}

package/src/index.js

@@ -0,0 +1,23 @@
+/**
+ * @kolkrabbi/kol-shell — the KOL application shell set.
+ *
+ * Lifted 2026-08-14 from the hand-copied twins in kol-monitor ("Monitor") and
+ * kol-mirror ("Hall of Mirrors") — AppShellSet lobby brief. App chrome, not
+ * site chrome: kol-framework's SideNav/footer/heroes are the site register;
+ * this is the fixed 48px rail + page scaffolds an application is built from.
+ *
+ * Router-agnostic: no react-router dependency — pass `currentPath` +
+ * `onNavigate` and render your router's element as children.
+ */
+export { default as AppShell } from './AppShell.jsx'
+export { NavHiddenContext, useNavHidden } from './navHidden.js'
+export { default as NavRail } from './NavRail.jsx'
+export { default as PageShell, PageBleed } from './PageShell.jsx'
+export { default as PageHeader } from './PageHeader.jsx'
+export { default as ContentFilters } from './ContentFilters.jsx'
+export { default as TabStrip } from './TabStrip.jsx'
+export { default as GridCard } from './GridCard.jsx'
+export { default as SettingsScaffold, SettingsSection, LabelRow } from './SettingsScaffold.jsx'
+export { default as WalkthroughPanel } from './WalkthroughPanel.jsx'
+export { default as ShortcutsOverlay } from './ShortcutsOverlay.jsx'
+export { default as Logomark } from './Logomark.jsx'

package/src/navHidden.js

@@ -0,0 +1,9 @@
+import { createContext, useContext } from 'react'
+
+// Nav-hidden context — own file so AppShell exports only components
+// (react-refresh constraint, learned in both source repos). Pages with a full
+// sidebar of their own (monitor's rack, mirror's studio) set this to replace
+// the global rail with their own nav header row. Load-bearing seam — keep it
+// a context.
+export const NavHiddenContext = createContext(null)
+export const useNavHidden = () => useContext(NavHiddenContext)