@kolkrabbi/kol-framework 0.1.2 → 0.2.0

package/kol-framework.css

@@ -657,30 +657,12 @@ code, pre {
   padding-top: 32px;
 }
 
+/* Positioning only — the chip look itself is the CopyButton atom
+ * (.kol-copy-btn in kol-theme). */
 .kol-codeblock-copy {
   position: absolute;
   top: 8px;
   right: 8px;
-  display: inline-flex;
-  align-items: center;
-  gap: 6px;
-  padding: 6px 10px;
-  background: color-mix(in srgb, var(--kol-surface-primary) 80%, transparent);
-  border: 1px solid var(--kol-fg-16);
-  border-radius: 3px;
-  color: var(--kol-fg-64);
-  cursor: pointer;
-  font-family: var(--kol-font-family-mono, monospace);
-  font-size: 10px;
-  font-weight: 600;
-  letter-spacing: 0.08em;
-  text-transform: uppercase;
-  transition: color 150ms ease, border-color 150ms ease, background 150ms ease;
-}
-
-.kol-codeblock-copy:hover {
-  color: var(--kol-surface-on-primary);
-  border-color: var(--kol-fg-48);
 }
 
 /* ───── Reveal utility ───── */
@@ -1223,3 +1205,113 @@ code, pre {
 }
 
 /* .kol-checker + .kol-grid-bg — moved to src/editor/styles/kol-editor.css */
+
+/* ───── AppShell TOC rail + SideNav collapsible-sections (monorepo shell merge, 2026-07-03) ───── */
+
+:root {
+  --kol-toc-w: 160px;
+}
+
+/* Opt-in third grid column: AppShell sets data-toc="true" on .kol-brand-layout
+   only when a page registers TOC content (ShellTocContext) or the app passes
+   defaultTocContent. Without the attribute the base 2-col template applies. */
+@media (min-width: 1280px) {
+  .kol-brand-layout[data-toc="true"] {
+    grid-template-columns: var(--kol-sidenav-w) minmax(0, 1fr) var(--kol-toc-w);
+  }
+}
+
+/* SideNav collapsibleSections chrome — inert unless that mode renders.
+   Rail (collapsed) + forced rail (≤1024px) hide count/toggle with the labels;
+   the open ≤767px drawer restores them, mirroring -hop-label. */
+.kol-sidenav.is-collapsed .kol-sidenav-hop-count,
+.kol-sidenav.is-collapsed .kol-sidenav-section-toggle {
+  display: none;
+}
+
+@media (max-width: 1024px) {
+  .kol-sidenav-hop-count,
+  .kol-sidenav-section-toggle {
+    display: none;
+  }
+}
+
+@media (max-width: 767px) {
+  .kol-sidenav.is-drawer-open .kol-sidenav-hop-count { display: inline; }
+  .kol-sidenav.is-drawer-open .kol-sidenav-section-toggle { display: inline-flex; }
+}
+
+/* ── ShellHeader — kol-shell-header-* ─────────────────────────────────────
+   Chrome the JSX utilities can't express: hidden scrollbar on the tab strip,
+   the tab type/underline recipe with its active state, and the wide-viewport
+   (1600px) bumps. Colors are --kol-fg-* tokens; no raw color-mix() here.
+   Target: packages/framework/kol-framework.css */
+
+/* Brand block — reserves the nav-column width at lg+ so Row-2 tabs align to
+   the shell grid (keyed to the live sidenav token; source used lg:w-[256px]). */
+@media (min-width: 1024px) {
+  .kol-shell-header-brand {
+    width: var(--kol-sidenav-w, 256px);
+  }
+}
+
+/* Tab strip — horizontally scrollable, scrollbar hidden. */
+.kol-shell-header-tabs {
+  display: flex;
+  flex-wrap: nowrap;
+  gap: 24px;
+  overflow-x: auto;
+  padding-top: 8px;
+  scrollbar-width: none;
+  -ms-overflow-style: none;
+}
+
+.kol-shell-header-tabs::-webkit-scrollbar {
+  display: none;
+}
+
+/* Section tab — mono type, muted rest, underline on active (aria-current). */
+.kol-shell-header-tab {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  font-family: var(--kol-font-family-mono, monospace);
+  font-size: 13px;
+  font-weight: 500;
+  letter-spacing: 0.02em;
+  color: var(--kol-fg-64);
+  white-space: nowrap;
+  flex-shrink: 0;
+  padding: 8px 0 12px;
+  border-bottom: 2px solid transparent;
+  transition: color 0.2s ease, border-color 0.2s ease;
+  text-decoration: none;
+}
+
+.kol-shell-header-tab:hover {
+  color: var(--kol-fg-88);
+}
+
+.kol-shell-header-tab[aria-current="page"] {
+  color: var(--kol-surface-on-primary);
+  border-bottom-color: var(--kol-surface-on-primary);
+}
+
+/* Wide-viewport bumps (matches the shell's 1600px nav font step). */
+@media (min-width: 1600px) {
+  .kol-shell-header-tabs {
+    gap: 32px;
+  }
+
+  .kol-shell-header-tab {
+    font-size: 16px;
+    gap: 8px;
+    padding-top: 10px;
+    padding-bottom: 14px;
+  }
+
+  .kol-shell-header-tab svg {
+    width: 18px;
+    height: 18px;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-framework",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "KOL app shell — sidenav, layout, theme toggle, footer, heroes + brand color layer. SideNav takes nav data as props so the tree stays app-local.",
   "license": "MIT",
   "type": "module",
@@ -27,8 +27,8 @@
     "app-shell"
   ],
   "dependencies": {
-    "@kolkrabbi/kol-component": "0.1.2",
-    "@kolkrabbi/kol-loader": "0.2.0"
+    "@kolkrabbi/kol-component": "0.3.0",
+    "@kolkrabbi/kol-loader": "0.3.0"
   },
   "peerDependencies": {
     "react": "^18.3.0 || ^19.0.0",

package/src/AppShell.jsx

@@ -1,11 +1,24 @@
-import { useEffect, useState } from 'react'
+import { createContext, useEffect, useState } from 'react'
 import { Outlet, useLocation } from 'react-router-dom'
 import SideNav from './SideNav.jsx'
 import { Icon } from '@kolkrabbi/kol-loader'
 import { ModalProvider } from '@kolkrabbi/kol-component'
 
-export default function AppShell({ navTree = [], getActivePage }) {
+/* Pages can register right-rail TOC content via this context.
+ * Usage: const setTocContent = useContext(ShellTocContext)
+ * useLayoutEffect(() => { setTocContent(<MyToc />); return () => setTocContent(null) }, [])
+ * No page registered + no defaultTocContent prop → no rail, layout unchanged. */
+export const ShellTocContext = createContext(null)
+
+/* Pages can suppress the TOC rail (e.g. hide an app-level defaultTocContent).
+ * Usage: const setTocCollapsed = useContext(ShellTocCollapsedContext)
+ * useLayoutEffect(() => { setTocCollapsed(true); return () => setTocCollapsed(false) }, [setTocCollapsed]) */
+export const ShellTocCollapsedContext = createContext(null)
+
+export default function AppShell({ navTree = [], getActivePage, header, footer, defaultTocContent }) {
   const [drawerOpen, setDrawerOpen] = useState(false)
+  const [tocContent, setTocContent] = useState(null)
+  const [tocCollapsed, setTocCollapsed] = useState(false)
   const { pathname } = useLocation()
 
   useEffect(() => { setDrawerOpen(false) }, [pathname])
@@ -17,30 +30,49 @@ export default function AppShell({ navTree = [], getActivePage }) {
     return () => window.removeEventListener('keydown', onKey)
   }, [drawerOpen])
 
+  const effectiveTocContent = tocContent ?? defaultTocContent
+  const showToc = Boolean(effectiveTocContent) && !tocCollapsed
+
   return (
     <ModalProvider>
-      <div className="kol-brand-layout" data-drawer-open={drawerOpen ? 'true' : undefined}>
-        <button
-          type="button"
-          className="kol-sidenav-hamburger md:hidden fixed top-3 left-3 z-30 w-10 h-10 inline-flex items-center justify-center rounded-full bg-surface-primary border border-fg-08 text-emphasis"
-          aria-label={drawerOpen ? 'Close menu' : 'Open menu'}
-          aria-expanded={drawerOpen}
-          onClick={() => setDrawerOpen((v) => !v)}
-        >
-          <Icon name={drawerOpen ? 'x' : 'menu'} size={18} />
-        </button>
-
-        <div
-          className="kol-sidenav-backdrop fixed inset-0 z-20 bg-black/50 opacity-0 pointer-events-none transition-opacity duration-200 md:hidden"
-          onClick={() => setDrawerOpen(false)}
-          aria-hidden="true"
-        />
-
-        <SideNav navTree={navTree} getActivePage={getActivePage} drawerOpen={drawerOpen} onCloseDrawer={() => setDrawerOpen(false)} />
-        <div className="min-w-0">
-          <Outlet />
-        </div>
-      </div>
+      <ShellTocContext.Provider value={setTocContent}>
+        <ShellTocCollapsedContext.Provider value={setTocCollapsed}>
+          <div
+            className="kol-brand-layout"
+            data-drawer-open={drawerOpen ? 'true' : undefined}
+            data-toc={showToc ? 'true' : undefined}
+          >
+            <button
+              type="button"
+              className="kol-sidenav-hamburger md:hidden fixed top-3 left-3 z-30 w-10 h-10 inline-flex items-center justify-center rounded-full bg-surface-primary border border-fg-08 text-emphasis"
+              aria-label={drawerOpen ? 'Close menu' : 'Open menu'}
+              aria-expanded={drawerOpen}
+              onClick={() => setDrawerOpen((v) => !v)}
+            >
+              <Icon name={drawerOpen ? 'x' : 'menu'} size={18} />
+            </button>
+
+            <div
+              className="kol-sidenav-backdrop fixed inset-0 z-20 bg-black/50 opacity-0 pointer-events-none transition-opacity duration-200 md:hidden"
+              onClick={() => setDrawerOpen(false)}
+              aria-hidden="true"
+            />
+
+            <SideNav navTree={navTree} getActivePage={getActivePage} drawerOpen={drawerOpen} onCloseDrawer={() => setDrawerOpen(false)} />
+            <div className="min-w-0">
+              {header}
+              <Outlet />
+              {footer}
+            </div>
+
+            {showToc && (
+              <aside className="kol-toc-rail hidden xl:block min-w-0 sticky top-0 self-start h-dvh overflow-y-auto pt-8 pr-6">
+                {effectiveTocContent}
+              </aside>
+            )}
+          </div>
+        </ShellTocCollapsedContext.Provider>
+      </ShellTocContext.Provider>
     </ModalProvider>
   )
 }

package/src/PortalFooter.jsx

@@ -1,22 +1,99 @@
-export default function PortalFooter() {
+/**
+ * PortalFooter — site footer chrome.
+ *
+ * Zero-prop: the Kolkrabbi favicon mark + credit line (portal default,
+ * unchanged). Opt-in slots turn it into a full site footer:
+ *   brand    node — brand block (wordmark/logo), top-left.
+ *   columns  [{ title, links: [{ label, href }] }] — link columns, top-right.
+ *   socials  [{ label, href, icon? }] — bottom-bar strip; icon node optional,
+ *            label renders as text when no icon (and feeds aria-label).
+ *   note     node — bottom-bar legal/credit line.
+ *   children node — escape hatch, rendered between columns and the bottom bar.
+ * Links are plain <a href> — router-agnostic. Strings render as authored.
+ */
+export default function PortalFooter({ brand, columns, socials, note, children }) {
   const year = new Date().getFullYear()
+  const hasColumns = columns?.length > 0
+  const hasSocials = socials?.length > 0
+
+  if (!brand && !hasColumns && !hasSocials && !note && !children) {
+    return (
+      <footer className="kol-portal-footer">
+        <a
+          href="https://kolkrabbi.io"
+          target="_blank"
+          rel="noopener"
+          aria-label="Kolkrabbi Vinnustofa"
+        >
+          <img src="/favicon/favicon.svg" alt="" width="32" height="32" />
+        </a>
+        <p className="kol-helper-12 text-meta">
+          <a href="https://kolkrabbi.io" target="_blank" rel="noopener" className="hover:text-strong">
+            Kolkrabbi Vinnustofa
+          </a>
+          {' · '}
+          {year}
+        </p>
+      </footer>
+    )
+  }
+
+  const hasTop = Boolean(brand || hasColumns)
+
   return (
     <footer className="kol-portal-footer">
-      <a
-        href="https://kolkrabbi.io"
-        target="_blank"
-        rel="noopener"
-        aria-label="Kolkrabbi Vinnustofa"
-      >
-        <img src="/favicon/favicon.svg" alt="" width="32" height="32" />
-      </a>
-      <p className="kol-helper-12 text-meta">
-        <a href="https://kolkrabbi.io" target="_blank" rel="noopener" className="hover:text-strong">
-          Kolkrabbi Vinnustofa
-        </a>
-        {' · '}
-        {year}
-      </p>
+      <div className="w-full flex flex-col gap-12">
+        {hasTop && (
+          <div className="flex flex-col md:flex-row md:justify-between items-start gap-10 md:gap-12">
+            {brand}
+            {hasColumns && (
+              <nav className="flex flex-wrap items-start gap-12 md:gap-16 lg:gap-20">
+                {columns.map((column) => (
+                  <div key={column.title} className="flex flex-col gap-4">
+                    <p className="kol-helper-12 tracking-widest text-meta">{column.title}</p>
+                    <ul className="m-0 p-0 list-none flex flex-col gap-1 lg:gap-2">
+                      {column.links.map((link) => (
+                        <li key={link.label}>
+                          <a href={link.href} className="kol-sans-heading-03 text-auto">
+                            {link.label}
+                          </a>
+                        </li>
+                      ))}
+                    </ul>
+                  </div>
+                ))}
+              </nav>
+            )}
+          </div>
+        )}
+
+        {children}
+
+        {(note || hasSocials) && (
+          <div className="flex flex-col gap-3">
+            {(hasTop || children) && <div className="border-t border-[var(--kol-fg-08)]" />}
+            <div className="flex flex-wrap justify-between items-center gap-4">
+              {note && <p className="kol-helper-12 text-meta">{note}</p>}
+              {hasSocials && (
+                <div className="flex items-center gap-4">
+                  {socials.map(({ label, href, icon }) => (
+                    <a
+                      key={label}
+                      href={href}
+                      target="_blank"
+                      rel="noopener"
+                      aria-label={label}
+                      className="kol-helper-12 text-meta hover:text-strong inline-flex items-center gap-2"
+                    >
+                      {icon ?? label}
+                    </a>
+                  ))}
+                </div>
+              )}
+            </div>
+          </div>
+        )}
+      </div>
     </footer>
   )
 }

package/src/ShellHeader.jsx

@@ -0,0 +1,147 @@
+import { Icon } from '@kolkrabbi/kol-loader'
+import { SearchInput } from '@kolkrabbi/kol-component'
+import ThemeToggle from './ThemeToggle.jsx'
+
+/**
+ * ShellHeader — the shell's sticky two-row top chrome.
+ *
+ * Row 1 is the brand block (consumer-supplied `brand` node — logo, wordmark,
+ * link element, whatever the app wants) plus right-side controls: an `actions`
+ * slot, the framework ThemeToggle, and an optional hamburger. Row 2 is a
+ * horizontal section-tab strip plus an optional inline search and the
+ * dock-left / dock-right rail toggles. The bar is stateless — every action is
+ * delegated up via callbacks; only ThemeToggle owns state (its own).
+ *
+ * Router-agnostic: tabs are plain anchors built from `nav` items
+ * (`{ label, href, icon? }`). Active styling keys on `aria-current="page"`,
+ * set by the `isActive(href)` predicate; `onNavigate(event, item)` is the
+ * client-routing seam (preventDefault + push in the consumer).
+ *
+ * Row 2 renders only when it has content (tabs, search, or a rail toggle).
+ * Tab-strip chrome (mono type, active underline, hidden scrollbar, wide-
+ * viewport bumps) lives in kol-framework.css under kol-shell-header-*.
+ *
+ * @param {ReactNode} brand          Row-1 left slot — logo/wordmark + link, consumer-supplied
+ * @param {Array}     nav            section tabs: [{ label, href, icon? }]
+ * @param {Function}  isActive       (href) => boolean — marks the active tab
+ * @param {Function}  onNavigate     (event, item) => void — tab click seam for client routing
+ * @param {boolean|Object} search    Row-2 inline search; object spreads onto SearchInput
+ *                                   ({ value, onChange, onFocus, placeholder, shortcutHint, onClear, … })
+ * @param {ReactNode} actions        Row-1 trailing slot before the theme toggle (e.g. a search-overlay trigger)
+ * @param {boolean}   showThemeToggle render the framework ThemeToggle (default true)
+ * @param {Function}  onMenuClick    hamburger click; button renders only when set
+ * @param {Function}  onNavToggle    dock-left click → toggle left nav; button renders only when set (lg+)
+ * @param {Function}  onTocToggle    dock-right click → toggle TOC rail; button renders only when set (lg+)
+ * @param {boolean}   navCollapsed   tints the dock-left button
+ * @param {boolean}   tocCollapsed   tints the dock-right button
+ * @param {string}    className      extra classes on the outer bar
+ */
+
+const iconBtnCls =
+  'flex h-9 w-9 items-center justify-center rounded p-0 bg-transparent border-0 cursor-pointer transition-colors hover:bg-fg-08 hover:text-emphasis'
+
+export default function ShellHeader({
+  brand,
+  nav = [],
+  isActive,
+  onNavigate,
+  search,
+  actions,
+  showThemeToggle = true,
+  onMenuClick,
+  onNavToggle,
+  onTocToggle,
+  navCollapsed,
+  tocCollapsed,
+  className = '',
+}) {
+  const hasTabRow = nav.length > 0 || Boolean(search) || Boolean(onNavToggle) || Boolean(onTocToggle)
+
+  return (
+    <div className={`kol-shell-header sticky top-0 z-50 shrink-0 bg-surface-primary ${className}`.trim()}>
+      {/* Row 1: brand block + controls */}
+      <div className="border-b border-fg-08">
+        <div className="mx-auto max-w-[1800px] px-4 py-4 md:px-6 lg:px-8">
+          <div className="flex items-center justify-between">
+            {/* kol-shell-header-brand reserves the nav-column width at lg+ so
+             * the Row-2 tabs align to the shell grid. */}
+            <div className="kol-shell-header-brand flex min-w-0 items-center gap-8">
+              {brand}
+            </div>
+            <div className="flex shrink-0 items-center gap-1">
+              {actions}
+              {showThemeToggle && <ThemeToggle />}
+              {onMenuClick && (
+                <button
+                  type="button"
+                  className={`${iconBtnCls} text-fg-64`}
+                  onClick={onMenuClick}
+                  aria-label="Open navigation menu"
+                >
+                  <Icon name="menu" size={18} />
+                </button>
+              )}
+            </div>
+          </div>
+        </div>
+      </div>
+
+      {/* Row 2: section tabs + inline search + rail toggles */}
+      {hasTabRow && (
+        <div className="border-b border-fg-08">
+          <div className="mx-auto max-w-[1800px] px-4 md:px-5 lg:px-6">
+            <div className="kol-shell-header-tabs">
+              <nav className="flex flex-1 gap-6" aria-label="Sections">
+                {nav.map((item) => {
+                  const active = isActive ? isActive(item.href) : false
+                  return (
+                    <a
+                      key={item.href ?? item.label}
+                      href={item.href}
+                      className="kol-shell-header-tab"
+                      aria-current={active ? 'page' : undefined}
+                      onClick={onNavigate ? (event) => onNavigate(event, item) : undefined}
+                    >
+                      {item.icon && <Icon name={item.icon} size={14} />}
+                      {item.label}
+                    </a>
+                  )
+                })}
+              </nav>
+              {search && (
+                <SearchInput
+                  className="shrink-0 self-center"
+                  {...(search === true ? {} : search)}
+                />
+              )}
+              {(onNavToggle || onTocToggle) && (
+                <div className="hidden lg:flex items-center gap-1 pb-2">
+                  {onNavToggle && (
+                    <button
+                      type="button"
+                      className={`${iconBtnCls} ${navCollapsed ? 'text-fg-32' : 'text-fg-64'}`}
+                      onClick={onNavToggle}
+                      aria-label="Toggle navigation sidebar"
+                    >
+                      <Icon name="dock-left" size={18} />
+                    </button>
+                  )}
+                  {onTocToggle && (
+                    <button
+                      type="button"
+                      className={`${iconBtnCls} ${tocCollapsed ? 'text-fg-32' : 'text-fg-64'}`}
+                      onClick={onTocToggle}
+                      aria-label="Toggle table of contents sidebar"
+                    >
+                      <Icon name="dock-right" size={18} />
+                    </button>
+                  )}
+                </div>
+              )}
+            </div>
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}

package/src/SideNav.jsx

@@ -37,13 +37,14 @@ const leafStyle = (indent) => ({
   '--kol-sidenav-dot-left': `${indent - 14}px`,
 })
 
-function SectionLeaf({ leaf, basePath, isActive, indent }) {
+function SectionLeaf({ leaf, basePath, isActive, indent, onNavigate }) {
   return (
     <li>
       <Link
         to={`${basePath}#${leaf.id}`}
         className={isActive ? linkActiveCls : linkCls}
         style={leafStyle(indent)}
+        onClick={onNavigate}
       >
         {leaf.label}
       </Link>
@@ -51,14 +52,15 @@ function SectionLeaf({ leaf, basePath, isActive, indent }) {
   )
 }
 
-function RouteLeaf({ leaf, indent }) {
+function RouteLeaf({ leaf, indent, onNavigate, isActiveFn }) {
   return (
     <li>
       <NavLink
         to={leaf.to}
         end
-        className={({ isActive }) => (isActive ? linkActiveCls : linkCls)}
+        className={({ isActive }) => ((isActiveFn ? isActiveFn(leaf.to) : isActive) ? linkActiveCls : linkCls)}
         style={leafStyle(indent)}
+        onClick={onNavigate}
       >
         {leaf.label}
       </NavLink>
@@ -66,7 +68,7 @@ function RouteLeaf({ leaf, indent }) {
   )
 }
 
-function GroupNode({ group, basePath, activeSectionId, indent }) {
+function GroupNode({ group, basePath, activeSectionId, indent, onNavigate, isActiveFn }) {
   const isAncestor = hasActiveDescendant(group.children, activeSectionId)
   return (
     <li>
@@ -84,6 +86,8 @@ function GroupNode({ group, basePath, activeSectionId, indent }) {
             basePath={basePath}
             activeSectionId={activeSectionId}
             indent={indent + 12}
+            onNavigate={onNavigate}
+            isActiveFn={isActiveFn}
           />
         ))}
       </ul>
@@ -91,12 +95,21 @@ function GroupNode({ group, basePath, activeSectionId, indent }) {
   )
 }
 
-function ChildNode({ child, basePath, activeSectionId, indent }) {
+function ChildNode({ child, basePath, activeSectionId, indent, onNavigate, isActiveFn }) {
   if (child.children) {
-    return <GroupNode group={child} basePath={basePath} activeSectionId={activeSectionId} indent={indent} />
+    return (
+      <GroupNode
+        group={child}
+        basePath={basePath}
+        activeSectionId={activeSectionId}
+        indent={indent}
+        onNavigate={onNavigate}
+        isActiveFn={isActiveFn}
+      />
+    )
   }
   if (child.to) {
-    return <RouteLeaf leaf={child} indent={indent} />
+    return <RouteLeaf leaf={child} indent={indent} onNavigate={onNavigate} isActiveFn={isActiveFn} />
   }
   if (child.id) {
     return (
@@ -105,21 +118,37 @@ function ChildNode({ child, basePath, activeSectionId, indent }) {
         basePath={basePath}
         isActive={activeSectionId === child.id}
         indent={indent}
+        onNavigate={onNavigate}
       />
     )
   }
   return null
 }
 
-export default function SideNav({ drawerOpen = false, onCloseDrawer, navTree = [], getActivePage }) {
+export default function SideNav({
+  drawerOpen = false,
+  onCloseDrawer,
+  navTree = [],
+  getActivePage,
+  onNavigate,
+  collapsed: collapsedProp,
+  onToggle,
+  collapsibleSections = false,
+  isActive,
+}) {
   const { pathname } = useLocation()
   const activePage = getActivePage?.(pathname)
   const sectionIds = activePage ? collectSectionIds(activePage) : []
   const onPageRoot = activePage && pathname === activePage.to
   const activeSectionId = useScrollSpy(onPageRoot ? sectionIds : [])
 
+  /* Root collapse: controlled when `collapsed` is defined (pair with
+   * onToggle), otherwise internal state. */
   const isEditor = pathname.startsWith('/editor/')
-  const [collapsed, setCollapsed] = useState(isEditor)
+  const [internalCollapsed, setInternalCollapsed] = useState(isEditor)
+  const isControlled = collapsedProp !== undefined
+  const collapsed = isControlled ? collapsedProp : internalCollapsed
+  const handleToggle = isControlled ? onToggle : () => setInternalCollapsed((v) => !v)
 
   useEffect(() => {
     const root = document.documentElement
@@ -128,10 +157,26 @@ export default function SideNav({ drawerOpen = false, onCloseDrawer, navTree = [
   }, [collapsed])
 
   /* /editor → collapsed. Anywhere else → expanded. Manual chevron toggle
-   * works for the session but doesn't persist across navigation. */
+   * works for the session but doesn't persist across navigation.
+   * Skipped in controlled mode — the parent owns collapse. */
+  useEffect(() => {
+    if (!isControlled) setInternalCollapsed(isEditor)
+  }, [isEditor, isControlled])
+
+  /* Per-page section expand/collapse (opt-in via collapsibleSections).
+   * The section containing the active route auto-expands on every
+   * navigation; manual toggles persist for the session. */
+  const [expandedSections, setExpandedSections] = useState(() =>
+    collapsibleSections && activePage?.id ? { [activePage.id]: true } : {}
+  )
+
   useEffect(() => {
-    setCollapsed(isEditor)
-  }, [isEditor])
+    if (!collapsibleSections || !activePage?.id) return
+    setExpandedSections((prev) => (prev[activePage.id] ? prev : { ...prev, [activePage.id]: true }))
+  }, [collapsibleSections, activePage?.id, pathname])
+
+  const toggleSection = (pageId) =>
+    setExpandedSections((prev) => ({ ...prev, [pageId]: !prev[pageId] }))
 
   return (
     <aside
@@ -139,10 +184,10 @@ export default function SideNav({ drawerOpen = false, onCloseDrawer, navTree = [
     >
       <button
         type="button"
-        className="kol-sidenav-toggle absolute top-5 right-[-12px] z-[2] w-6 h-6 inline-flex items-center justify-center bg-[var(--kol-surface-primary)] border border-[var(--kol-border-default)] rounded-full p-0 cursor-pointer text-[14px] leading-none transition-colors duration-150 text-meta hover:text-emphasis hover:border-fg-24"
+        className="kol-sidenav-toggle absolute top-5 right-[-12px] z-[2] w-6 h-6 inline-flex items-center justify-center bg-[var(--kol-surface-primary)] border border-[var(--kol-border-default)] rounded-full p-0 cursor-pointer kol-helper-14 transition-colors duration-150 text-meta hover:text-emphasis hover:border-fg-24"
         aria-label={collapsed ? 'Expand sidebar' : 'Collapse sidebar'}
         title={collapsed ? 'Expand' : 'Collapse'}
-        onClick={() => setCollapsed((v) => !v)}
+        onClick={handleToggle}
       >
         <Icon name={collapsed ? 'chevron-right' : 'chevron-left'} size={12} />
       </button>
@@ -151,22 +196,52 @@ export default function SideNav({ drawerOpen = false, onCloseDrawer, navTree = [
         <ul className="kol-sidenav-tree flex flex-col gap-[2px]">
           {navTree.map((page) => {
             const isActivePage = activePage?.id === page.id
+            const isSectionCollapsible = collapsibleSections && page.children?.length > 0
+            const sectionExpanded = isSectionCollapsible && !!expandedSections[page.id]
+            const hopLink = (
+              <NavLink
+                to={page.to}
+                end={page.to === '/'}
+                className={({ isActive: navActive }) =>
+                  `kol-sidenav-hop kol-helper-12 relative flex items-center gap-3 py-2 pr-10 pl-6 no-underline${(isActive ? isActive(page.to) : navActive) ? ' is-active' : ''}`
+                }
+                onClick={onNavigate}
+              >
+                <span className="kol-sidenav-hop-icon inline-flex items-center justify-center w-5 h-5 shrink-0" aria-hidden="true">
+                  <Icon name={page.icon} size={16} />
+                </span>
+                <span className="kol-sidenav-hop-label flex-1 min-w-0">{page.label}</span>
+                {isSectionCollapsible && (
+                  <span className="kol-sidenav-hop-count kol-helper-10 text-meta shrink-0">
+                    ({page.children.length})
+                  </span>
+                )}
+              </NavLink>
+            )
             return (
               <li key={page.id}>
-                <NavLink
-                  to={page.to}
-                  end={page.to === '/'}
-                  className={({ isActive }) =>
-                    `kol-sidenav-hop kol-helper-12 relative flex items-center gap-3 py-2 pr-10 pl-6 no-underline${isActive ? ' is-active' : ''}`
-                  }
-                >
-                  <span className="kol-sidenav-hop-icon inline-flex items-center justify-center w-5 h-5 shrink-0" aria-hidden="true">
-                    <Icon name={page.icon} size={16} />
-                  </span>
-                  <span className="kol-sidenav-hop-label flex-1 min-w-0">{page.label}</span>
-                </NavLink>
+                {isSectionCollapsible ? (
+                  <div className="relative">
+                    {hopLink}
+                    <button
+                      type="button"
+                      className="kol-sidenav-section-toggle absolute right-3 top-1/2 -translate-y-1/2 z-[1] inline-flex items-center justify-center w-5 h-5 p-0 bg-transparent border-0 cursor-pointer text-meta hover:text-emphasis transition-colors duration-150"
+                      aria-label={sectionExpanded ? `Collapse ${page.label}` : `Expand ${page.label}`}
+                      aria-expanded={sectionExpanded}
+                      onClick={() => toggleSection(page.id)}
+                    >
+                      <Icon
+                        name="chevron-right"
+                        size={12}
+                        className={`transition-transform duration-150${sectionExpanded ? ' rotate-90' : ''}`}
+                      />
+                    </button>
+                  </div>
+                ) : (
+                  hopLink
+                )}
 
-                {isActivePage && page.children && (
+                {page.children && (collapsibleSections ? sectionExpanded : isActivePage) && (
                   <ul className="kol-sidenav-list mb-2 flex flex-col gap-2">
                     {page.children.map((child, i) => (
                       <ChildNode
@@ -175,6 +250,8 @@ export default function SideNav({ drawerOpen = false, onCloseDrawer, navTree = [
                         basePath={page.to}
                         activeSectionId={activeSectionId}
                         indent={56}
+                        onNavigate={onNavigate}
+                        isActiveFn={isActive}
                       />
                     ))}
                   </ul>

package/src/index.js

@@ -8,7 +8,9 @@
  */
 
 export { default as AppShell } from './AppShell.jsx'
+export { ShellTocContext, ShellTocCollapsedContext } from './AppShell.jsx'
 export { default as SideNav } from './SideNav.jsx'
+export { default as ShellHeader } from './ShellHeader.jsx'
 export { default as ThemeToggle } from './ThemeToggle.jsx'
 export { default as Layout } from './Layout.jsx'
 export { default as PageSection } from './PageSection.jsx'