@kolkrabbi/kol-shell 0.56.0 → 0.57.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-shell",
-  "version": "0.56.0",
+  "version": "0.57.1",
   "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.202.0",
+    "@kolkrabbi/kol-component": "^0.226.0",
+    "@kolkrabbi/kol-icons": "^0.28.0",
     "@kolkrabbi/kol-framework": "^0.44.0",
-    "@kolkrabbi/kol-icons": "^0.26.0",
-    "@kolkrabbi/kol-theme": "^0.142.0"
+    "@kolkrabbi/kol-theme": "^0.153.0"
   },
   "files": [
     "src",

package/src/AppHub.jsx

@@ -0,0 +1,101 @@
+import { useEffect, useState } from 'react'
+import AppShell from './AppShell.jsx'
+import HubHome from './HubHome.jsx'
+import HubSettings from './HubSettings.jsx'
+import ShortcutsOverlay from './ShortcutsOverlay.jsx'
+
+/* taxonomy-ok: organism — nests AppShell / HubHome / HubSettings / ShortcutsOverlay (relative) */
+
+/**
+ * AppHub — Shell + Hub in one call; the app passes its Tool as children (the app anatomy,
+ * `docs/documentation/04-compositions/16-app-anatomy.md`, 2026-09-26).
+ *
+ * monitor, mirror and fxr each assembled this by hand: the same AppShell props, the same
+ * Home on CatalogPage, the same Settings on SettingsScaffold, a local ⌥-digit handler
+ * apiece and a local shortcuts-sheet key — so their small things drifted. The Hub is
+ * those decisions made once. An app describes itself and supplies its tool.
+ *
+ * ROUTES: `homePath` (default `/`) is Home, `settingsPath` is Settings, every other path renders
+ * `children` — the tool. A tool that should be what LOADS moves Home off `/` (media-shell, user
+ * 2026-09-26: "the point of this is not to bury media, the column browser is what we want loaded"):
+ * `homePath="/library"`, a rail row for it, and the mark still goes to `/` — the tool.
+ * Router-agnostic like AppShell: pass `currentPath` + `onNavigate`, and your router's element
+ * (`<Outlet/>`) as children.
+ *
+ * KEYS: `,` toggles Settings · `S` toggles the shortcuts sheet · `\` hides the rail ·
+ * ⌥1…9 walks the rail top to bottom, mark first, Settings last. None fire while typing.
+ *
+ * @param {Object}   app        `{ name, subtitle, logomark (svg url), about (node), links [{label,url}] }`
+ * @param {Array}    items      the tool's rail rows `{ icon, path, label }` — Home is the mark, Settings is pinned
+ * @param {string}   currentPath · {Function} onNavigate · {ElementType} iconComponent   as AppShell
+ * @param {string}   homePath   where Home lives (default `/`); anything else puts the tool at `/`
+ * @param {Object}   home       HubHome's props (`items`, `toCard`, `views`, `actions`, `filterGroups`, …)
+ * @param {Array}    walkthrough  the steps Home's Walkthrough button opens
+ * @param {Object}   settings   HubSettings' props (`content`, `tabs`, `picker`, `onOpenSettings`, `comboLabel`)
+ * @param {Array}    shortcuts  `[{ section, items: [{ id, label, combo }] }]` — the sheet AND Settings
+ * @param {ReactNode} themeToggle  Settings' masthead toggle (a node — kol-framework is not a peer)
+ * @param {string}   shortcutsKey  default `s`; `null` turns the sheet key off (a tool that owns S)
+ * @param {Object}   shell      any AppShell prop, spread last (`touch`, `pageWash`, `drawerOpenOn`, `railComponent`, …)
+ */
+const SETTINGS_ROW = (path) => [{ icon: 'nav-settings', path, label: 'Settings' }]
+
+export default function AppHub({
+  app = {},
+  items = [],
+  currentPath,
+  onNavigate,
+  iconComponent,
+  home,
+  walkthrough,
+  settings,
+  shortcuts = [],
+  themeToggle,
+  settingsPath = '/settings',
+  homePath = '/',
+  shortcutsKey = 's',
+  shell,
+  children,
+}) {
+  const [sheet, setSheet] = useState(false)
+
+  useEffect(() => {
+    if (!shortcutsKey) return undefined
+    const onKey = (e) => {
+      if (e.key.toLowerCase() !== shortcutsKey || e.metaKey || e.ctrlKey || e.altKey || e.repeat) return
+      const t = e.target
+      if (t?.isContentEditable || /^(INPUT|TEXTAREA|SELECT)$/.test(t?.tagName)) return
+      e.preventDefault()
+      setSheet((v) => !v)
+    }
+    window.addEventListener('keydown', onKey)
+    return () => window.removeEventListener('keydown', onKey)
+  }, [shortcutsKey])
+
+  const page = currentPath === homePath
+    ? <HubHome app={app} iconComponent={iconComponent} walkthrough={walkthrough} {...home} />
+    : currentPath === settingsPath
+      ? <HubSettings app={app} shortcuts={shortcuts} themeToggle={themeToggle} {...settings} />
+      : children
+
+  return (
+    <AppShell
+      items={items}
+      bottomItems={SETTINGS_ROW(settingsPath)}
+      logomark={app.logomark ? { svgUrl: app.logomark, title: app.name } : undefined}
+      currentPath={currentPath}
+      onNavigate={onNavigate}
+      iconComponent={iconComponent}
+      appName={app.name}
+      railToggleKey={'\\'}
+      settingsPath={settingsPath}
+      settingsKey=","
+      navKeys
+      touch="drawer"
+      pageWash="var(--kol-fg-02)"
+      {...shell}
+    >
+      {page}
+      {sheet && <ShortcutsOverlay shortcuts={shortcuts} onClose={() => setSheet(false)} />}
+    </AppShell>
+  )
+}

package/src/AppShell.jsx

@@ -272,7 +272,10 @@ export default function AppShell({
    * With a `logomark`, the order is the order you see: the mark, then the items.
    * Without one, `items[n - 1]` exactly as before, so an app that renders no
    * mark is untouched. */
-  const navPaths = (logomark ? ['/'] : []).concat((items ?? []).map((i) => i?.path)).filter(Boolean)
+  /* …and the BOTTOM rows after them (the Hub, 2026-09-26): the rail read top to bottom,
+   * Settings included. kol-fxr kept a local ⌥-digit handler for exactly this — its ⌥6 is
+   * Settings — and monitor and mirror kept theirs; three copies of one key map. */
+  const navPaths = (logomark ? ['/'] : []).concat([...(items ?? []), ...(bottomItems ?? [])].map((i) => i?.path)).filter(Boolean)
   useEffect(() => {
     if (!navKeys) return undefined
     const onKey = (e) => {

package/src/CatalogPage.jsx

@@ -52,7 +52,7 @@ import WalkthroughPanel from './WalkthroughPanel.jsx'
  * @param {string}   view · onViewChange   controlled view; or `defaultView`
  * @param {Array}    layouts       LIST / GRID (default both)
  * @param {string}   defaultLayout 'grid' (default) | 'list'
- * @param {{steps: Array, open: boolean, iconComponent?: ElementType}} walkthrough  the panel over the catalog
+ * @param {{steps: Array, open: boolean, onClose?: Function, iconComponent?: ElementType}} walkthrough  the panel over the catalog; `onClose` draws its X inside the card
  * @param {ReactNode} actions      the bottom row's buttons
  * @param {'bleed'|'capped'} width   the page's TIER, forwarded to PageShell (two-page-scaffolds-one-job, 2026-09-03):
  *                                 `bleed` (default) fills the window — the app tier; `capped` centres on the
@@ -209,7 +209,7 @@ export default function CatalogPage({
     <PageShell width={width} className={`${PRESETS[preset]?.className ?? ''} ${className}`.trim()} style={{ overflow: 'hidden', '--kol-catalog-n': cols ?? undefined, ...style }}>
       {header && <PageHeader {...header} />}
       <div style={{ flex: 1, position: 'relative' }}>
-        {open && <WalkthroughPanel steps={walkthrough.steps} iconComponent={walkthrough.iconComponent} />}
+        {open && <WalkthroughPanel steps={walkthrough.steps} iconComponent={walkthrough.iconComponent} onClose={walkthrough.onClose} />}
         <ContentFilters
           items={items}
           title={filtersTitle}

package/src/HubHome.jsx

@@ -0,0 +1,83 @@
+import { useState } from 'react'
+import { Button } from '@kolkrabbi/kol-component'
+import CatalogPage from './CatalogPage.jsx'
+
+/* taxonomy-ok: organism — nests CatalogPage (relative) + kol-component's Button */
+
+/**
+ * HubHome — the Hub's Home: a Catalog under the app's masthead (the Hub, 2026-09-26).
+ * monitor, mirror and fxr each wrote this page on `CatalogPage` with the same five
+ * decisions — the mono masthead, RECENT · SAVED, a walkthrough opened by a button,
+ * that button's Close label, a "Get started" last step — and the case of the view
+ * labels had already drifted. They are made here once.
+ *
+ * THE WALKTHROUGH IS OPT-IN (user, 2026-09-26, on media-shell): it never opens by
+ * itself. The Walkthrough button at the end of the action row opens it; the X inside
+ * the card and the same button close it.
+ *
+ * @param {Object}   app          `{ name, subtitle }` — the masthead, when Home is the app's front door
+ * @param {string}   title · subtitle  Home's own masthead instead — for a Home that is not the front
+ *                                door (media-shell's Library at `/library`, 2026-09-26: it said "Media")
+ * @param {Array|Function} items  the catalog's items, or `(view) => items` — RECENT
+ *                                and SAVED are different sets in every app
+ * @param {Array}    views        the view strip (default RECENT · SAVED); rename a set by
+ *                                passing your own, e.g. `[…, { value: 'saved', label: 'FAVOURITES' }]`
+ * @param {Array}    walkthrough  steps (WalkthroughPanel's); a step whose `actions` is a
+ *                                FUNCTION gets `close` — the "Get started" step's buttons
+ * @param {ReactNode} actions     the app's buttons; the Walkthrough button follows them
+ * THE LIST IS THE FILE ROW, one per line (user, 2026-09-26, on apps/shell: CatalogPage's
+ * 36px `catalog` row four across "both a bad hover state and using columns wrong"; brand's
+ * library row is the reference) — `rowVariant="file"` + `listLayout="stack"`: the ruled
+ * 48px thumb row, `date` · `size` · `actions` from `toCard`. Only the Hub's default —
+ * CatalogPage's own default does not move, and either prop can be passed back.
+ *
+ * @param {...*}     rest         every other CatalogPage prop (`toCard`, `filterGroups`,
+ *                                `filtersTitle`, `filtersProps`, …) — spread through
+ */
+const HUB_VIEWS = [
+  { value: 'recent', label: 'RECENT' },
+  { value: 'saved', label: 'SAVED' },
+]
+
+export default function HubHome({
+  app = {},
+  title,
+  subtitle,
+  items = [],
+  views = HUB_VIEWS,
+  defaultView,
+  walkthrough,
+  actions,
+  iconComponent,
+  ...rest
+}) {
+  const [view, setView] = useState(defaultView ?? views?.[0]?.value)
+  const [touring, setTouring] = useState(false)
+  const close = () => setTouring(false)
+  const steps = (walkthrough ?? []).map((s) => (typeof s.actions === 'function' ? { ...s, actions: s.actions(close) } : s))
+
+  return (
+    <CatalogPage
+      header={{ title: title ?? app.name, subtitle: subtitle ?? app.subtitle, size: 'sm', voice: 'mono' }}
+      items={typeof items === 'function' ? items(view) : items}
+      views={views}
+      view={view}
+      onViewChange={setView}
+      iconComponent={iconComponent}
+      rowVariant="file"
+      listLayout="stack"
+      walkthrough={steps.length ? { open: touring, steps, onClose: close, iconComponent } : undefined}
+      actions={(actions || steps.length) ? (
+        <>
+          {actions}
+          {steps.length > 0 && (
+            <Button variant="grey" size="md" onClick={() => setTouring((t) => !t)}>
+              {touring ? 'Close' : 'Walkthrough'}
+            </Button>
+          )}
+        </>
+      ) : undefined}
+      {...rest}
+    />
+  )
+}

package/src/HubSettings.jsx

@@ -0,0 +1,207 @@
+import { useState } from 'react'
+import { Divider, LabeledControlSection, SettingsFooter, SettingsPanel, SettingsSections, ViewToggle } from '@kolkrabbi/kol-component'
+import SettingsScaffold from './SettingsScaffold.jsx'
+import SettingsShortcuts from './SettingsShortcuts.jsx'
+import SettingsLinks, { SettingsColophon } from './SettingsLinks.jsx'
+
+/* taxonomy-ok: organism — nests SettingsScaffold / SettingsShortcuts / SettingsLinks (relative) + kol-component's SettingsPanel / SettingsSections */
+
+/**
+ * HubSettings — the Hub's Settings page (the Hub, 2026-09-26). monitor, mirror and fxr
+ * each put the same page on `SettingsScaffold`: SETTINGS · ABOUT · REPO with the same
+ * three subtitles, the same theme toggle in the masthead, About as the app's prose over
+ * the colophon, Repo as a link list, and the keyboard shortcuts from the one array the
+ * sheet shows. Only the app's own settings differ, so only those are passed in.
+ *
+ * kol-fxr's page is the richest of the three and is the reference (user, 2026-09-26:
+ * "not saying its more true then other versions, just more feature rich, which we want
+ * as options, based on what repo has"). Every one of its features is here, and each
+ * turns on only when the app supplies what it needs:
+ *
+ *   sections        settings rows AS DATA (`SettingsSections`' shape). The page renders
+ *                   them, and the search reads them with the shortcuts, under a Section
+ *                   filter — fxr's page
+ *   drawer          the gear in the masthead opens the SAME sections as a right-hand
+ *                   `SettingsPanel` — one definition, two frames, so they cannot drift.
+ *                   `true`, or `{ title, onReset }` (a reset foot)
+ *   picker          the masthead's dropdown (fxr: open a chrome)
+ *   splitShortcuts  OPTIONS / SHORTCUTS as an icon pair beside the row, instead of the
+ *                   shortcuts stacked under the settings — fxr's page
+ *   content         free-form sections instead of (or above) `sections` — monitor's prose
+ *   tabs            extra tabs after SETTINGS (mirror's PERFORMANCE)
+ *
+ * ABOUT and REPO sit BELOW the rule (`row: 'layout'`) — fxr's, the page the scaffold
+ * was rebuilt from (SettingsScaffoldTabRows).
+ *
+ * @param {Object}    app          `{ name, about, links }`
+ * @param {Array}     sections     `[{ label, rows: [{ label, render | value, align? }] }]`
+ * @param {boolean|Object} drawer  gear + drawer over `sections` — `{ title = 'Display settings', onReset }`
+ * @param {ReactNode} content      free-form body above the sections
+ * @param {Array}     tabs         `[{ value, label, title, subtitle, content }]`
+ * @param {Array}     shortcuts    `[{ section, items: [{ id, label, combo }] }]`
+ * @param {boolean}   splitShortcuts  the OPTIONS / SHORTCUTS pair (default off — stacked)
+ * @param {ReactNode} themeToggle · picker   the masthead cluster, as SettingsScaffold
+ * @param {'masthead'|'drawer'} themeIn  where the theme toggle sits (user, 2026-09-26). `masthead`
+ *                                 (default) is the 2026-08-30 ruling (SettingsMastheadCluster) — and the
+ *                                 only place on a page with no drawer; `drawer` puts it in the drawer's
+ *                                 footer beside reset, apps/media's arrangement. `drawer` with no drawer
+ *                                 falls back to the masthead, so the toggle is never lost
+ * @param {Function}  comboLabel   (combo) => string, for SettingsShortcuts
+ * @param {string}    tone         the page's control tone (default `sunken`, SettingsScaffold's): the
+ *                                 filter row, the masthead gear AND every control in the settings rows,
+ *                                 which inherit it from a `kol-tone-*` wrapper — `tone: 'primary'` in an
+ *                                 app's `settings` is the one line that changes all of them
+ */
+const SHORTCUTS = 'Shortcuts'
+/* ONE settings column for every app on the Hub (user, 2026-09-26: "the layout has 2 different
+ * settings, thats wrong") — a per-app width was how two pages drifted within a day. 320 = the 160
+ * label + a dropdown holding a bucket name ("R2 · kol-media"); fxr's 268 was sized for switches. */
+const COLUMN = 320
+const PAIR = [
+  { value: 'options', label: 'OPTIONS', icon: 'slider-01' },
+  { value: 'shortcuts', label: 'SHORTCUTS', icon: 'view-list' },
+]
+
+export default function HubSettings({
+  app = {},
+  sections,
+  drawer,
+  content,
+  tabs = [],
+  shortcuts = [],
+  splitShortcuts = false,
+  themeToggle,
+  picker,
+  comboLabel,
+  tone = 'sunken',
+  themeIn = 'masthead',
+}) {
+  const [drawerOpen, setDrawerOpen] = useState(false)
+  const [mode, setMode] = useState('options')
+  const drawerCfg = drawer === true ? {} : drawer
+  const hasDrawer = !!drawerCfg && sections?.length > 0
+  const themeInDrawer = themeIn === 'drawer' && hasDrawer && !!themeToggle
+
+  const all = [
+    { value: 'settings', label: 'SETTINGS', title: 'Settings', subtitle: 'Configuration and preferences' },
+    ...tabs,
+    { value: 'about', label: 'ABOUT', row: 'layout', title: 'About', subtitle: `${app.name ?? ''} by Kolkrabbi`.trim() },
+    { value: 'repo', label: 'REPO', row: 'layout', title: 'Repo', subtitle: 'Source and deployments' },
+  ]
+
+  /* ONE FLAT LIST for the filter row: a setting row carries its section, a shortcut its
+   * own group under the one Shortcuts section — fxr's page, so the chips stay few */
+  const items = [
+    ...(sections ?? []).flatMap((sec) => sec.rows.map((row) => ({
+      id: `${sec.label}:${row.label}`, kind: 'setting', label: row.label, section: sec.label, row,
+    }))),
+    ...shortcuts.flatMap((sec) => (sec.items ?? []).map((k) => ({
+      id: `shortcut:${k.id ?? k.label}`, kind: 'shortcut', label: k.label, combo: k.combo, section: SHORTCUTS, group: sec.section, k,
+    }))),
+  ]
+  const filterGroups = sections?.length
+    ? [{ label: 'Section', key: 'section', values: [...sections.map((s) => s.label), ...(shortcuts.length ? [SHORTCUTS] : [])] }]
+    : undefined
+
+  /* regroup what survived in the declared order — a search narrows, it never reorders */
+  const liveSections = (rows) => (sections ?? [])
+    .map((sec) => ({ ...sec, rows: rows.filter((i) => i.kind === 'setting' && i.section === sec.label).map((i) => i.row) }))
+    .filter((sec) => sec.rows.length)
+  const liveShortcuts = (rows) => shortcuts
+    .map((sec) => ({ section: sec.section, items: rows.filter((i) => i.kind === 'shortcut' && i.group === sec.section).map((i) => i.k) }))
+    .filter((sec) => sec.items.length)
+
+  const renderSettings = (filtered) => {
+    const rows = filtered ?? items
+    const keys = liveShortcuts(rows)
+    /* SPLIT: the page-wide multi-column grid, for a keymap that fills a page (monitor's) */
+    if (splitShortcuts && mode === 'shortcuts') return keys.length > 0 && <SettingsShortcuts sections={keys} comboLabel={comboLabel} />
+    const live = liveSections(rows)
+    /* STACKED: the shortcuts are settings ROWS in the settings column (user, 2026-09-26: "why
+     * doesnt items justify space between right side? where toggle and dropdown align?") — the
+     * page-wide grid packed them into ~180px tracks, so the combos ended short of the controls
+     * above. Same anatomy as the S sheet's rows; the combo is the row's value, right-aligned. */
+    const keyRows = keys.map(({ section, items: ks }) => ({
+      label: section,
+      rows: ks.map((k) => ({
+        id: k.id ?? k.label,
+        label: k.label,
+        value: <span className="text-fg-32 kol-helper-12 whitespace-nowrap">{comboLabel ? comboLabel(k.combo) : k.combo}</span>,
+      })),
+    }))
+    return (
+      <div className="flex flex-col gap-8">
+        {content}
+        {/* the rows are sized for the drawer's 380 (a 160 label + the control); unbounded on a
+          * page the control runs the full width, so the column is capped — one column for every app (COLUMN) */}
+        {live.length > 0 && <div style={{ maxWidth: COLUMN }}><SettingsSections sections={live} /></div>}
+        {!splitShortcuts && keyRows.length > 0 && (
+          <LabeledControlSection label="Keyboard Shortcuts">
+            <div style={{ maxWidth: COLUMN }}><SettingsSections sections={keyRows} /></div>
+          </LabeledControlSection>
+        )}
+      </div>
+    )
+  }
+
+  const render = (tab, filtered) => {
+    if (tab === 'settings') return <div className={`kol-tone-${tone}`}>{renderSettings(filtered)}</div>
+    if (tab === 'about') return (
+      <div className="flex flex-col gap-8">
+        {app.about && (
+          <LabeledControlSection label={app.name}>
+            <div className="text-fg-48 kol-mono-14" style={{ maxWidth: 640 }}>{app.about}</div>
+          </LabeledControlSection>
+        )}
+        <SettingsColophon />
+      </div>
+    )
+    if (tab === 'repo') return (
+      <LabeledControlSection label="Links">
+        <SettingsLinks links={app.links ?? []} />
+      </LabeledControlSection>
+    )
+    return tabs.find((t) => t.value === tab)?.content ?? null
+  }
+
+  return (
+    <>
+      <SettingsScaffold
+        tabs={all}
+        defaultTab="settings"
+        header={{ size: 'sm', voice: 'mono' }}
+        tone={tone}
+        picker={picker}
+        themeToggle={themeInDrawer ? undefined : themeToggle}
+        onOpenSettings={hasDrawer ? () => setDrawerOpen(true) : undefined}
+        items={items}
+        filterGroups={filterGroups}
+        searchKeys={['label', 'section', 'group', 'combo']}
+        /* the pair picks the Settings view, so from ABOUT or REPO it also takes you back to Settings */
+        trailingActions={splitShortcuts ? (tab, setTab) => (
+          <>
+            <ViewToggle variant="icon" size="sm" tone="sunken" options={PAIR} viewMode={mode}
+              onViewChange={(v) => { setMode(v); setTab('settings') }} />
+            <Divider variant="vertical" />
+          </>
+        ) : undefined}
+        renderContent={render}
+      />
+      {/* the drawer is the page's other half, a SIBLING of the scaffold — never inside its scroll */}
+      {hasDrawer && (
+        <SettingsPanel
+          open={drawerOpen}
+          variant="drawer"
+          title={drawerCfg.title ?? 'Display settings'}
+          onClose={() => setDrawerOpen(false)}
+          /* the footer's children sit before reset in its row — media's theme · reset arrangement */
+          footer={(drawerCfg.onReset || themeInDrawer)
+            ? <SettingsFooter onReset={drawerCfg.onReset}>{themeInDrawer ? themeToggle : null}</SettingsFooter>
+            : undefined}
+        >
+          <SettingsSections sections={sections} divided />
+        </SettingsPanel>
+      )}
+    </>
+  )
+}

package/src/NavRail.jsx

@@ -1,6 +1,6 @@
 import { useEffect, useRef, useState } from 'react'
 import gsap from 'gsap'
-import { Button } from '@kolkrabbi/kol-component'
+import { Button, Tooltip } from '@kolkrabbi/kol-component'
 import { GRAB } from '@kolkrabbi/kol-component/utilities/motion'
 /* the grab pill's proximity wake, travel and dwell — ONE implementation, shared
  * with kol-framework's useDragResize (OneGrabGestureBothRails, kol-fxr
@@ -187,6 +187,9 @@ function RailItem({ icon, path, label, sub, currentPath, onNavigate, iconCompone
   return (
     <>
       <div className="flex items-center gap-3 w-full overflow-hidden shrink-0">
+        {/* the DS tooltip, not the browser's (the native-title sweep, 2026-09-26) — to the RIGHT,
+          * out over the page, since the collapsed rail's glyph is all there is to read */}
+        <Tooltip label={label} placement="right" triggerClassName="inline-flex shrink-0">
         <Button
           iconOnly={icon}
           iconSize={20}
@@ -202,9 +205,9 @@ function RailItem({ icon, path, label, sub, currentPath, onNavigate, iconCompone
            * in the rail") */
           style={{ color: 'var(--kol-oq-96)' }}
           onClick={press}
-          title={label}
           aria-label={label}
         />
+        </Tooltip>
         <span
           className="kol-helper-12 uppercase text-oq-96 flex-1 min-w-0 truncate cursor-pointer"
           onClick={press}
@@ -212,6 +215,7 @@ function RailItem({ icon, path, label, sub, currentPath, onNavigate, iconCompone
           {label}
         </span>
         {sub?.length > 0 && (
+          <Tooltip label={label} placement="right" triggerClassName="inline-flex shrink-0">
           <Button
             iconOnly={open ? 'chevron-down' : 'chevron-right'}
             iconSize={16}
@@ -222,23 +226,22 @@ function RailItem({ icon, path, label, sub, currentPath, onNavigate, iconCompone
             style={{ color: 'var(--kol-oq-96)' }}
             aria-expanded={open}
             onClick={() => setOpen((v) => !v)}
-            title={label}
             aria-label={`${label} sub categories`}
           />
+          </Tooltip>
         )}
       </div>
       {railOpen && open && sub.map((s) => {
         const on = s.path === '/' ? currentPath === '/' : currentPath.startsWith(s.path)
         return (
+          <Tooltip key={s.path} label={s.label} placement="right" asChild>
           <div
-            key={s.path}
             /* 18px of gutter puts the 20px box at x 26, so its 12px glyph starts
              * at 30 — one step right of L1's 20-in-32 at 14 (measured in fxr) */
             className="flex items-center gap-3 w-full overflow-hidden shrink-0 cursor-pointer"
             style={{ paddingLeft: 18 }}
             onClick={() => onNavigate?.(s.path)}
             aria-current={on ? 'page' : undefined}
-            title={s.label}
           >
             {s.icon && (
               <span
@@ -256,6 +259,7 @@ function RailItem({ icon, path, label, sub, currentPath, onNavigate, iconCompone
               {s.label}
             </span>
           </div>
+          </Tooltip>
         )
       })}
     </>
@@ -324,14 +328,15 @@ export default function NavRail({
         /* the mark, and the app name beside it when open — uppercase like the
          * rows (user 2026-08-28: "uppercase CONSISTENCY"). The `w-8` centring box
          * puts the 20px mark on the same x as the 20px glyphs below it. */
+        <Tooltip label={logomark.title} placement="right" asChild>
         <div
           onClick={() => onNavigate?.('/')}
           className="text-oq-96 cursor-pointer flex items-center gap-3 w-full overflow-hidden shrink-0 pt-1 mb-4"
-          title={logomark.title}
         >
           <span className="w-8 flex justify-center shrink-0"><Logomark svgUrl={logomark.svgUrl} size={20} /></span>
           <span className="kol-helper-12 uppercase flex-1 min-w-0 truncate">{logomark.title}</span>
         </div>
+        </Tooltip>
       )}
       {items.map(row)}
       {/* the spacer IS the layout */}

package/src/SettingsScaffold.jsx

@@ -1,5 +1,5 @@
 import { useState } from 'react'
-import { ContentFilters, IconFrame } from '@kolkrabbi/kol-component'
+import { ContentFilters, IconFrame, Tooltip } from '@kolkrabbi/kol-component'
 import PageShell from './PageShell.jsx'
 import { PageHeader } from '@kolkrabbi/kol-component'
 
@@ -110,19 +110,22 @@ export default function SettingsScaffold({
    * 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">
+    /* the cluster carries the page's tone as a wrapper (the Hub review, 2026-09-26), so a picker
+     * or toggle passed with no tone of its own matches the gear and the filter row */
+    <div className={`flex items-center gap-2 kol-tone-${tone}`}>
       {picker}
       {themeToggle}
       {onOpenSettings && (
+        <Tooltip label="Display settings">
         <IconFrame
           name="settings-01"
           variant="primary"
           tone={tone}
           size="sm"
           onClick={onOpenSettings}
-          title="Display settings"
           aria-label="Display settings"
         />
+        </Tooltip>
       )}
     </div>
   ) : null

package/src/ShortcutsOverlay.jsx

@@ -82,8 +82,11 @@ export default function ShortcutsOverlay({ shortcuts = [], onClose }) {
           ground rather than a surface from the page's own ladder — so the
           panel separates from the scrimmed canvas without a stroke. */}
       <div
-        className="kol-shortcuts-panel text-fg-64 kol-helper-12 bg-oq-04 flex flex-col gap-6"
-        style={{ padding: 24, borderRadius: 4 }}
+        /* THE SHEET FITS THE WINDOW (editor review #4, 2026-09-27): a long keymap — the design
+         * editor's is six sections — ran past both edges of the viewport with no way to reach the
+         * rest. Capped to the window less a margin, scrolling inside. */
+        className="kol-shortcuts-panel text-fg-64 kol-helper-12 bg-oq-04 flex flex-col gap-6 overflow-y-auto"
+        style={{ padding: 24, borderRadius: 4, maxHeight: 'calc(100dvh - 48px)' }}
         onClick={(e) => e.stopPropagation()}
       >
         <SettingsSections

package/src/WalkthroughPanel.jsx

@@ -9,8 +9,12 @@ import { Button } from '@kolkrabbi/kol-component'
  * `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).
+ *
+ * `onClose` draws an X INSIDE the card, top-right (user, 2026-09-26, on media-shell:
+ * 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.
  */
-export default function WalkthroughPanel({ steps = [], iconComponent }) {
+export default function WalkthroughPanel({ steps = [], iconComponent, onClose }) {
   const [step, setStep] = useState(0)
   const current = steps[step]
   if (!current) return null
@@ -34,8 +38,19 @@ export default function WalkthroughPanel({ steps = [], iconComponent }) {
 
       <div
         className="bg-surface-tertiary border border-fg-08"
-        style={{ flex: 1, display: 'flex', borderRadius: 4, minHeight: 480, overflow: 'hidden' }}
+        style={{ flex: 1, display: 'flex', borderRadius: 4, minHeight: 480, overflow: 'hidden', position: 'relative' }}
       >
+        {onClose && (
+          <Button
+            variant="nav"
+            size="sm"
+            iconOnly="x"
+            iconComponent={iconComponent}
+            aria-label="Close walkthrough"
+            onClick={onClose}
+            style={{ position: 'absolute', top: 8, right: 8 }}
+          />
+        )}
         {current.actions ? (
           <div style={{ flex: 1, display: 'flex', flexDirection: 'column', alignItems: 'center', justifyContent: 'center', gap: 12 }}>
             {current.actions}

package/src/index.js

@@ -31,3 +31,7 @@ export { default as CatalogPage } from './CatalogPage.jsx'
 export { default as SettingsShortcuts } from './SettingsShortcuts.jsx'
 export { default as SettingsLinks, SettingsColophon } from './SettingsLinks.jsx'
 export { default as TouchDeviceOverlay, useTouchPrimary } from './TouchDeviceOverlay.jsx'
+// the Hub — Shell + Home + Settings + keys, made once (the app anatomy, 2026-09-26)
+export { default as AppHub } from './AppHub.jsx'
+export { default as HubHome } from './HubHome.jsx'
+export { default as HubSettings } from './HubSettings.jsx'